From dccb7aff653035782f95e87102338cabcd318122 Mon Sep 17 00:00:00 2001 From: Rob Browning Date: Sat, 16 Jun 2012 16:36:55 -0500 Subject: [PATCH] Remove files that are incompatible with the Debian Free Software Guidelines. --- doc/emacs/ChangeLog | 9304 ------ doc/emacs/Makefile.in | 194 - doc/emacs/abbrevs.texi | 447 - doc/emacs/ack.texi | 1446 - doc/emacs/anti.texi | 114 - doc/emacs/arevert-xtra.texi | 189 - doc/emacs/basic.texi | 796 - doc/emacs/buffers.texi | 640 - doc/emacs/building.texi | 1590 - doc/emacs/cal-xtra.texi | 918 - doc/emacs/calendar.texi | 1714 -- doc/emacs/cmdargs.texi | 1120 - doc/emacs/commands.texi | 185 - doc/emacs/custom.texi | 2539 -- doc/emacs/dired-xtra.texi | 50 - doc/emacs/dired.texi | 1433 - doc/emacs/display.texi | 1580 - doc/emacs/doclicense.texi | 508 - doc/emacs/emacs-xtra.texi | 139 - doc/emacs/emacs.texi | 1598 - doc/emacs/emacsver.texi | 4 - doc/emacs/emerge-xtra.texi | 413 - doc/emacs/entering.texi | 162 - doc/emacs/files.texi | 1984 -- doc/emacs/fixit.texi | 417 - doc/emacs/fortran-xtra.texi | 581 - doc/emacs/frames.texi | 1170 - doc/emacs/glossary.texi | 1457 - doc/emacs/gnu.texi | 551 - doc/emacs/gpl.texi | 717 - doc/emacs/help.texi | 636 - doc/emacs/indent.texi | 240 - doc/emacs/killing.texi | 872 - doc/emacs/kmacro.texi | 573 - doc/emacs/m-x.texi | 71 - doc/emacs/macos.texi | 210 - doc/emacs/maintaining.texi | 2375 -- doc/emacs/makefile.w32-in | 150 - doc/emacs/mark.texi | 471 - doc/emacs/mini.texi | 735 - doc/emacs/misc.texi | 2583 -- doc/emacs/modes.texi | 450 - doc/emacs/msdog-xtra.texi | 620 - doc/emacs/msdog.texi | 1021 - doc/emacs/mule.texi | 1807 -- doc/emacs/package.texi | 249 - doc/emacs/picture-xtra.texi | 289 - doc/emacs/programs.texi | 1787 -- doc/emacs/regs.texi | 332 - doc/emacs/rmail.texi | 1556 - doc/emacs/screen.texi | 318 - doc/emacs/search.texi | 1372 - doc/emacs/sending.texi | 691 - doc/emacs/text.texi | 2808 -- doc/emacs/trouble.texi | 1113 - doc/emacs/vc-xtra.texi | 25 - doc/emacs/vc1-xtra.texi | 447 - doc/emacs/windows.texi | 469 - doc/emacs/xresources.texi | 821 - doc/lispintro/ChangeLog | 535 - doc/lispintro/Makefile.in | 101 - doc/lispintro/README | 82 - doc/lispintro/cons-1.eps | 578 - doc/lispintro/cons-1.pdf | 71 - doc/lispintro/cons-2.eps | 600 - doc/lispintro/cons-2.pdf | Bin 1399 -> 0 bytes doc/lispintro/cons-2a.eps | 594 - doc/lispintro/cons-2a.pdf | Bin 1504 -> 0 bytes doc/lispintro/cons-3.eps | 624 - doc/lispintro/cons-3.pdf | Bin 1475 -> 0 bytes doc/lispintro/cons-4.eps | 677 - doc/lispintro/cons-4.pdf | Bin 1587 -> 0 bytes doc/lispintro/cons-5.eps | 622 - doc/lispintro/cons-5.pdf | Bin 1511 -> 0 bytes doc/lispintro/doclicense.texi | 508 - doc/lispintro/drawers.eps | 510 - doc/lispintro/drawers.pdf | Bin 3906 -> 0 bytes doc/lispintro/emacs-lisp-intro.texi | 22288 -------------- doc/lispintro/lambda-1.eps | 465 - doc/lispintro/lambda-1.pdf | 69 - doc/lispintro/lambda-2.eps | 465 - doc/lispintro/lambda-2.pdf | Bin 1225 -> 0 bytes doc/lispintro/lambda-3.eps | 465 - doc/lispintro/lambda-3.pdf | 69 - doc/lispintro/makefile.w32-in | 79 - doc/lispref/ChangeLog | 11075 ------- doc/lispref/Makefile.in | 164 - doc/lispref/README | 48 - doc/lispref/abbrevs.texi | 501 - doc/lispref/advice.texi | 749 - doc/lispref/anti.texi | 141 - doc/lispref/back.texi | 37 - doc/lispref/backups.texi | 774 - doc/lispref/book-spine.texi | 27 - doc/lispref/buffers.texi | 1238 - doc/lispref/commands.texi | 3437 --- doc/lispref/compile.texi | 742 - doc/lispref/control.texi | 1333 - doc/lispref/customize.texi | 1420 - doc/lispref/debugging.texi | 794 - doc/lispref/display.texi | 6422 ---- doc/lispref/doclicense.texi | 510 - doc/lispref/edebug.texi | 1633 -- doc/lispref/elisp-covers.texi | 252 - doc/lispref/elisp.texi | 1552 - doc/lispref/errors.texi | 238 - doc/lispref/eval.texi | 866 - doc/lispref/files.texi | 3276 --- doc/lispref/frames.texi | 2443 -- doc/lispref/front-cover-1.texi | 52 - doc/lispref/functions.texi | 1482 - doc/lispref/gpl.texi | 723 - doc/lispref/hash.texi | 356 - doc/lispref/help.texi | 727 - doc/lispref/hooks.texi | 285 - doc/lispref/index.texi | 29 - doc/lispref/internals.texi | 1406 - doc/lispref/intro.texi | 553 - doc/lispref/keymaps.texi | 2813 -- doc/lispref/lay-flat.texi | 43 - doc/lispref/lists.texi | 1803 -- doc/lispref/loading.texi | 1003 - doc/lispref/macros.texi | 659 - doc/lispref/makefile.w32-in | 127 - doc/lispref/maps.texi | 199 - doc/lispref/markers.texi | 695 - doc/lispref/minibuf.texi | 2346 -- doc/lispref/modes.texi | 4038 --- doc/lispref/nonascii.texi | 1962 -- doc/lispref/numbers.texi | 1230 - doc/lispref/objects.texi | 2115 -- doc/lispref/os.texi | 2448 -- doc/lispref/package.texi | 339 - doc/lispref/positions.texi | 988 - doc/lispref/processes.texi | 3117 -- doc/lispref/searching.texi | 1901 -- doc/lispref/sequences.texi | 827 - doc/lispref/spellfile | 731 - doc/lispref/streams.texi | 836 - doc/lispref/strings.texi | 1155 - doc/lispref/symbols.texi | 573 - doc/lispref/syntax.texi | 1224 - doc/lispref/text.texi | 4385 --- doc/lispref/tindex.pl | 124 - doc/lispref/tips.texi | 1096 - doc/lispref/two-volume-cross-refs.txt | 319 - doc/lispref/two-volume.make | 224 - doc/lispref/two.el | 78 - doc/lispref/variables.texi | 1947 -- doc/lispref/vol1.texi | 1568 - doc/lispref/vol2.texi | 1567 - doc/lispref/windows.texi | 3452 --- doc/misc/ada-mode.texi | 1526 - doc/misc/auth.texi | 536 - doc/misc/autotype.texi | 665 - doc/misc/calc.texi | 36957 ------------------------ doc/misc/cc-mode.texi | 7246 ----- doc/misc/cl.texi | 5344 ---- doc/misc/dbus.texi | 1852 -- doc/misc/dired-x.texi | 1113 - doc/misc/doclicense.texi | 507 - doc/misc/ebrowse.texi | 1453 - doc/misc/ede.texi | 3792 --- doc/misc/ediff.texi | 2533 -- doc/misc/edt.texi | 944 - doc/misc/eieio.texi | 1908 -- doc/misc/emacs-gnutls.texi | 198 - doc/misc/emacs-mime.texi | 1895 -- doc/misc/epa.texi | 498 - doc/misc/erc.texi | 1063 - doc/misc/ert.texi | 849 - doc/misc/eshell.texi | 1016 - doc/misc/eudc.texi | 960 - doc/misc/flymake.texi | 759 - doc/misc/forms.texi | 977 - doc/misc/gnus-coding.texi | 393 - doc/misc/gnus-faq.texi | 2310 -- doc/misc/gnus-news.texi | 371 - doc/misc/gnus-overrides.texi | 0 doc/misc/gnus.texi | 30641 -------------------- doc/misc/gpl.texi | 717 - doc/misc/idlwave.texi | 4297 --- doc/misc/info.texi | 1515 - doc/misc/mairix-el.texi | 351 - doc/misc/message.texi | 2502 -- doc/misc/mh-e.texi | 9064 ------ doc/misc/newsticker.texi | 314 - doc/misc/nxml-mode.texi | 902 - doc/misc/org.texi | 16640 ----------- doc/misc/pcl-cvs.texi | 1431 - doc/misc/pgg.texi | 506 - doc/misc/rcirc.texi | 950 - doc/misc/reftex.texi | 5892 ---- doc/misc/remember.texi | 412 - doc/misc/sasl.texi | 277 - doc/misc/sc.texi | 1924 -- doc/misc/sem-user.texi | 1331 - doc/misc/semantic.texi | 623 - doc/misc/ses.texi | 983 - doc/misc/sieve.texi | 361 - doc/misc/smtpmail.texi | 444 - doc/misc/speedbar.texi | 1255 - doc/misc/tramp.texi | 3716 --- doc/misc/trampver.texi | 69 - doc/misc/url.texi | 1196 - doc/misc/vip.texi | 1947 -- doc/misc/viper.texi | 4557 --- doc/misc/widget.texi | 1829 -- doc/misc/woman.texi | 1431 - etc/CENSORSHIP | 87 - etc/COOKIES | 157 - etc/DEVEL.HUMOR | 196 - etc/GNU | 544 - etc/INTERVIEW | 442 - etc/JOKES | 647 - etc/LINUX-GNU | 147 - etc/MOTIVATION | 179 - etc/THE-GNU-PROJECT | 903 - etc/WHY-FREE | 244 - etc/copying.paper | 819 - 220 files changed, 361777 deletions(-) delete mode 100644 doc/emacs/ChangeLog delete mode 100644 doc/emacs/Makefile.in delete mode 100644 doc/emacs/abbrevs.texi delete mode 100644 doc/emacs/ack.texi delete mode 100644 doc/emacs/anti.texi delete mode 100644 doc/emacs/arevert-xtra.texi delete mode 100644 doc/emacs/basic.texi delete mode 100644 doc/emacs/buffers.texi delete mode 100644 doc/emacs/building.texi delete mode 100644 doc/emacs/cal-xtra.texi delete mode 100644 doc/emacs/calendar.texi delete mode 100644 doc/emacs/cmdargs.texi delete mode 100644 doc/emacs/commands.texi delete mode 100644 doc/emacs/custom.texi delete mode 100644 doc/emacs/dired-xtra.texi delete mode 100644 doc/emacs/dired.texi delete mode 100644 doc/emacs/display.texi delete mode 100644 doc/emacs/doclicense.texi delete mode 100644 doc/emacs/emacs-xtra.texi delete mode 100644 doc/emacs/emacs.texi delete mode 100644 doc/emacs/emacsver.texi delete mode 100644 doc/emacs/emerge-xtra.texi delete mode 100644 doc/emacs/entering.texi delete mode 100644 doc/emacs/files.texi delete mode 100644 doc/emacs/fixit.texi delete mode 100644 doc/emacs/fortran-xtra.texi delete mode 100644 doc/emacs/frames.texi delete mode 100644 doc/emacs/glossary.texi delete mode 100644 doc/emacs/gnu.texi delete mode 100644 doc/emacs/gpl.texi delete mode 100644 doc/emacs/help.texi delete mode 100644 doc/emacs/indent.texi delete mode 100644 doc/emacs/killing.texi delete mode 100644 doc/emacs/kmacro.texi delete mode 100644 doc/emacs/m-x.texi delete mode 100644 doc/emacs/macos.texi delete mode 100644 doc/emacs/maintaining.texi delete mode 100644 doc/emacs/makefile.w32-in delete mode 100644 doc/emacs/mark.texi delete mode 100644 doc/emacs/mini.texi delete mode 100644 doc/emacs/misc.texi delete mode 100644 doc/emacs/modes.texi delete mode 100644 doc/emacs/msdog-xtra.texi delete mode 100644 doc/emacs/msdog.texi delete mode 100644 doc/emacs/mule.texi delete mode 100644 doc/emacs/package.texi delete mode 100644 doc/emacs/picture-xtra.texi delete mode 100644 doc/emacs/programs.texi delete mode 100644 doc/emacs/regs.texi delete mode 100644 doc/emacs/rmail.texi delete mode 100644 doc/emacs/screen.texi delete mode 100644 doc/emacs/search.texi delete mode 100644 doc/emacs/sending.texi delete mode 100644 doc/emacs/text.texi delete mode 100644 doc/emacs/trouble.texi delete mode 100644 doc/emacs/vc-xtra.texi delete mode 100644 doc/emacs/vc1-xtra.texi delete mode 100644 doc/emacs/windows.texi delete mode 100644 doc/emacs/xresources.texi delete mode 100644 doc/lispintro/ChangeLog delete mode 100644 doc/lispintro/Makefile.in delete mode 100644 doc/lispintro/README delete mode 100644 doc/lispintro/cons-1.eps delete mode 100644 doc/lispintro/cons-1.pdf delete mode 100644 doc/lispintro/cons-2.eps delete mode 100644 doc/lispintro/cons-2.pdf delete mode 100644 doc/lispintro/cons-2a.eps delete mode 100644 doc/lispintro/cons-2a.pdf delete mode 100644 doc/lispintro/cons-3.eps delete mode 100644 doc/lispintro/cons-3.pdf delete mode 100644 doc/lispintro/cons-4.eps delete mode 100644 doc/lispintro/cons-4.pdf delete mode 100644 doc/lispintro/cons-5.eps delete mode 100644 doc/lispintro/cons-5.pdf delete mode 100644 doc/lispintro/doclicense.texi delete mode 100644 doc/lispintro/drawers.eps delete mode 100644 doc/lispintro/drawers.pdf delete mode 100644 doc/lispintro/emacs-lisp-intro.texi delete mode 100644 doc/lispintro/lambda-1.eps delete mode 100644 doc/lispintro/lambda-1.pdf delete mode 100644 doc/lispintro/lambda-2.eps delete mode 100644 doc/lispintro/lambda-2.pdf delete mode 100644 doc/lispintro/lambda-3.eps delete mode 100644 doc/lispintro/lambda-3.pdf delete mode 100644 doc/lispintro/makefile.w32-in delete mode 100644 doc/lispref/ChangeLog delete mode 100644 doc/lispref/Makefile.in delete mode 100644 doc/lispref/README delete mode 100644 doc/lispref/abbrevs.texi delete mode 100644 doc/lispref/advice.texi delete mode 100644 doc/lispref/anti.texi delete mode 100644 doc/lispref/back.texi delete mode 100644 doc/lispref/backups.texi delete mode 100644 doc/lispref/book-spine.texi delete mode 100644 doc/lispref/buffers.texi delete mode 100644 doc/lispref/commands.texi delete mode 100644 doc/lispref/compile.texi delete mode 100644 doc/lispref/control.texi delete mode 100644 doc/lispref/customize.texi delete mode 100644 doc/lispref/debugging.texi delete mode 100644 doc/lispref/display.texi delete mode 100644 doc/lispref/doclicense.texi delete mode 100644 doc/lispref/edebug.texi delete mode 100644 doc/lispref/elisp-covers.texi delete mode 100644 doc/lispref/elisp.texi delete mode 100644 doc/lispref/errors.texi delete mode 100644 doc/lispref/eval.texi delete mode 100644 doc/lispref/files.texi delete mode 100644 doc/lispref/frames.texi delete mode 100644 doc/lispref/front-cover-1.texi delete mode 100644 doc/lispref/functions.texi delete mode 100644 doc/lispref/gpl.texi delete mode 100644 doc/lispref/hash.texi delete mode 100644 doc/lispref/help.texi delete mode 100644 doc/lispref/hooks.texi delete mode 100644 doc/lispref/index.texi delete mode 100644 doc/lispref/internals.texi delete mode 100644 doc/lispref/intro.texi delete mode 100644 doc/lispref/keymaps.texi delete mode 100644 doc/lispref/lay-flat.texi delete mode 100644 doc/lispref/lists.texi delete mode 100644 doc/lispref/loading.texi delete mode 100644 doc/lispref/macros.texi delete mode 100644 doc/lispref/makefile.w32-in delete mode 100644 doc/lispref/maps.texi delete mode 100644 doc/lispref/markers.texi delete mode 100644 doc/lispref/minibuf.texi delete mode 100644 doc/lispref/modes.texi delete mode 100644 doc/lispref/nonascii.texi delete mode 100644 doc/lispref/numbers.texi delete mode 100644 doc/lispref/objects.texi delete mode 100644 doc/lispref/os.texi delete mode 100644 doc/lispref/package.texi delete mode 100644 doc/lispref/positions.texi delete mode 100644 doc/lispref/processes.texi delete mode 100644 doc/lispref/searching.texi delete mode 100644 doc/lispref/sequences.texi delete mode 100644 doc/lispref/spellfile delete mode 100644 doc/lispref/streams.texi delete mode 100644 doc/lispref/strings.texi delete mode 100644 doc/lispref/symbols.texi delete mode 100644 doc/lispref/syntax.texi delete mode 100644 doc/lispref/text.texi delete mode 100755 doc/lispref/tindex.pl delete mode 100644 doc/lispref/tips.texi delete mode 100644 doc/lispref/two-volume-cross-refs.txt delete mode 100644 doc/lispref/two-volume.make delete mode 100644 doc/lispref/two.el delete mode 100644 doc/lispref/variables.texi delete mode 100644 doc/lispref/vol1.texi delete mode 100644 doc/lispref/vol2.texi delete mode 100644 doc/lispref/windows.texi delete mode 100644 doc/misc/ada-mode.texi delete mode 100644 doc/misc/auth.texi delete mode 100644 doc/misc/autotype.texi delete mode 100644 doc/misc/calc.texi delete mode 100644 doc/misc/cc-mode.texi delete mode 100644 doc/misc/cl.texi delete mode 100644 doc/misc/dbus.texi delete mode 100644 doc/misc/dired-x.texi delete mode 100644 doc/misc/doclicense.texi delete mode 100644 doc/misc/ebrowse.texi delete mode 100644 doc/misc/ede.texi delete mode 100644 doc/misc/ediff.texi delete mode 100644 doc/misc/edt.texi delete mode 100644 doc/misc/eieio.texi delete mode 100644 doc/misc/emacs-gnutls.texi delete mode 100644 doc/misc/emacs-mime.texi delete mode 100644 doc/misc/epa.texi delete mode 100644 doc/misc/erc.texi delete mode 100644 doc/misc/ert.texi delete mode 100644 doc/misc/eshell.texi delete mode 100644 doc/misc/eudc.texi delete mode 100644 doc/misc/flymake.texi delete mode 100644 doc/misc/forms.texi delete mode 100644 doc/misc/gnus-coding.texi delete mode 100644 doc/misc/gnus-faq.texi delete mode 100644 doc/misc/gnus-news.texi delete mode 100644 doc/misc/gnus-overrides.texi delete mode 100644 doc/misc/gnus.texi delete mode 100644 doc/misc/gpl.texi delete mode 100644 doc/misc/idlwave.texi delete mode 100644 doc/misc/info.texi delete mode 100644 doc/misc/mairix-el.texi delete mode 100644 doc/misc/message.texi delete mode 100644 doc/misc/mh-e.texi delete mode 100644 doc/misc/newsticker.texi delete mode 100644 doc/misc/nxml-mode.texi delete mode 100644 doc/misc/org.texi delete mode 100644 doc/misc/pcl-cvs.texi delete mode 100644 doc/misc/pgg.texi delete mode 100644 doc/misc/rcirc.texi delete mode 100644 doc/misc/reftex.texi delete mode 100644 doc/misc/remember.texi delete mode 100644 doc/misc/sasl.texi delete mode 100644 doc/misc/sc.texi delete mode 100644 doc/misc/sem-user.texi delete mode 100644 doc/misc/semantic.texi delete mode 100644 doc/misc/ses.texi delete mode 100644 doc/misc/sieve.texi delete mode 100644 doc/misc/smtpmail.texi delete mode 100644 doc/misc/speedbar.texi delete mode 100644 doc/misc/tramp.texi delete mode 100644 doc/misc/trampver.texi delete mode 100644 doc/misc/url.texi delete mode 100644 doc/misc/vip.texi delete mode 100644 doc/misc/viper.texi delete mode 100644 doc/misc/widget.texi delete mode 100644 doc/misc/woman.texi delete mode 100644 etc/CENSORSHIP delete mode 100644 etc/COOKIES delete mode 100644 etc/DEVEL.HUMOR delete mode 100644 etc/GNU delete mode 100644 etc/INTERVIEW delete mode 100644 etc/JOKES delete mode 100644 etc/LINUX-GNU delete mode 100644 etc/MOTIVATION delete mode 100644 etc/THE-GNU-PROJECT delete mode 100644 etc/WHY-FREE delete mode 100644 etc/copying.paper diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog deleted file mode 100644 index 2c6fb23d75a..00000000000 --- a/doc/emacs/ChangeLog +++ /dev/null @@ -1,9304 +0,0 @@ -2012-06-01 Chong Yidong - - * Version 24.1 released. - -2012-05-06 Chong Yidong - - * frames.texi (Mouse References, Mouse Commands): Fix index - entries (Bug#11362). - -2012-05-03 Glenn Morris - - * custom.texi (Customization Groups, Custom Themes, Examining): - Improve page breaks. - - * rmail.texi (Rmail Display): Use example rather than smallexample. - - * calendar.texi: Convert inforefs to refs. - - * dired.texi (Dired Enter): Improve page break. - - * abbrevs.texi (Abbrev Concepts): Copyedits. - - * maintaining.texi (Registering, Tag Syntax): - Tweak line and page breaks. - - * programs.texi (Programs, Electric C): Copyedits. - (Program Modes): Add xref to Fortran. - (Left Margin Paren): Remove what was (oddly enough) the only use - of defvar in the entire Emacs manual. - (Hungry Delete): Remove footnote about ancient Emacs version. - (Other C Commands): Use example rather than smallexample. - - * text.texi (Pages, Filling, Foldout, Org Mode, HTML Mode) - (Nroff Mode, Enriched Indentation, Table Rows and Columns): - Tweak line and page breaks. - - * modes.texi (Major Modes, Minor Modes): Reword to improve page-breaks. - (Major Modes): Use example rather than smallexample. - - * mule.texi (Output Coding): Reword to improve page-breaks. - - * frames.texi (Fonts): Tweak line and page breaks. - Use example rather than smallexample. Change cross-reference. - (Text-Only Mouse): Fix xref. - - * buffers.texi (Buffers, Kill Buffer, Several Buffers) - (Indirect Buffers): Tweak line- and page-breaks. - - * fixit.texi (Fixit, Undo): Reword to improve page-breaks. - -2012-05-01 Glenn Morris - - * emacs.texi (@copying): Only print EDITION in the TeX version. - -2012-04-30 Glenn Morris - - * search.texi (Regexp Search): Just say "Emacs". - - * display.texi (Auto Scrolling): - Reword to avoid repetition and improve page break. - -2012-04-28 Glenn Morris - - * xresources.texi (Resources): - * mule.texi (Language Environments): - * misc.texi (Amusements): - * maintaining.texi (VC Change Log): - * frames.texi (Fonts): - * custom.texi (Specifying File Variables, Minibuffer Maps): - * cmdargs.texi (Initial Options): - * building.texi (Flymake): - Reword to remove/reduce some overly long/short lines. - -2012-04-27 Glenn Morris - - * emacs.texi: Some fixes for detailed menu. - -2012-04-26 Glenn Morris - - * emacs.texi: Add "et al." to authors. - - * ack.texi, basic.texi, buffers.texi, building.texi: - * calendar.texi, cmdargs.texi, commands.texi, custom.texi: - * dired.texi, display.texi, emerge-xtra.texi, files.texi: - * fortran-xtra.texi, help.texi, kmacro.texi, mini.texi, misc.texi: - * msdog-xtra.texi, picture-xtra.texi, programs.texi, rmail.texi: - * search.texi, trouble.texi, windows.texi: - Use Texinfo recommended convention for quotes+punctuation. - -2012-04-25 Eli Zaretskii - - * mule.texi (Bidirectional Editing): Improve indexing. Minor - wording tweaks. - -2012-04-15 Chong Yidong - - * misc.texi (emacsclient Options): More clarifications. - -2012-04-14 Glenn Morris - - * msdog.texi (Windows Printing): It doesn't set printer-name. - - * mule.texi (Language Environments): Move font info to "Fontsets". - (Fontsets): Move intlfonts etc here from "Language Environments". - Copyedits. - (Defining Fontsets, Modifying Fontsets, Undisplayable Characters) - (Unibyte Mode, Charsets, Bidirectional Editing): Copyedits. - -2012-04-14 Chong Yidong - - * glossary.texi (Glossary): Standardize on "text terminal" - terminology. All callers changed. - - * misc.texi (emacsclient Options): Document "client frame" concept - and its effect on C-x C-c more carefully. - -2012-04-14 Glenn Morris - - * frames.texi (Scroll Bars): - * glossary.texi (Glossary): Use consistent case for "X Window System". - - * mule.texi (Select Input Method, Coding Systems): - State command names in kbd tables. - (Recognize Coding): Add cross-ref. - (Output Coding): Don't mention message mode in particular. - (Text Coding, Communication Coding, File Name Coding, Terminal Coding): - Copyedits. - -2012-04-13 Glenn Morris - - * mule.texi (Select Input Method, Coding Systems, Recognize Coding): - Copyedits. - (Coding Systems): Mac OS X apparently uses newlines for EOL. - (Recognize Coding): Remove old auto-coding-regexp-alist example. - auto-coding-functions does not override coding: tags. - Remove rmail-decode-mime-charset; it no longer has any effect. - -2012-04-12 Chong Yidong - - * custom.texi (Creating Custom Themes): Add reference to Custom - Themes node in Lisp manual. - -2012-04-12 Glenn Morris - - * mule.texi (International): Copyedits. - (International Chars): Update C-x = example output. - (Disabling Multibyte): Rename from "Enabling Multibyte". - Clarify what "unibyte: t" does, and mode-line description. - (Unibyte Mode): Update for "Disabling Multibyte" node name change. - Use Texinfo recommended convention for quotes+punctuation. - (Language Environments): Copyedits. - (Input Methods): Copyedits. Use "^" for the postfix example, - because it is less confusing inside Info's `quotes'. - - * custom.texi (Specifying File Variables): Fix "unibyte" description. - Update for "Disabling Multibyte" node name change. - * emacs.texi: Update for "Disabling Multibyte" node name change. - -2012-04-10 Glenn Morris - - * abbrevs.texi, arevert-xtra.texi, buffers.texi, building.texi: - * cmdargs.texi, custom.texi, entering.texi, files.texi, frames.texi: - * glossary.texi, help.texi, macos.texi, maintaining.texi, mini.texi: - * misc.texi, package.texi, programs.texi, screen.texi, search.texi: - * sending.texi, text.texi, trouble.texi: - Use @file for buffers, per the Texinfo manual. - - * entering.texi (Entering Emacs): - Do not mention initial-buffer-choice = t. - -2012-04-08 Glenn Morris - - * misc.texi (Gnus Startup): Use @env for environment variables. - -2012-04-07 Glenn Morris - - * Makefile.in: Replace non-portable use of $< in ordinary rules. - -2012-04-05 Glenn Morris - - * glossary.texi (Glossary): Use anchors for internal cross-references. - -2012-04-04 Glenn Morris - - * glossary.texi (Glossary): Copyedits. - Use Texinfo-recommended convention for quotes and punctuation. - Comment out a few specialized (Rmail) items. - New items: Bidirectional Text, Client, Directory Local Variable, - File Local Variable, Package, Server, Theme, Trash Can. - -2012-04-03 Chong Yidong - - * sending.texi (Mail Misc): Fix an index entry. - -2012-04-02 Eli Zaretskii - - * msdog.texi (Windows Startup): Add description of emacsclient - operation under -c and -t on MS-Windows. - - * misc.texi (emacsclient Options): Add cross-reference to "Windows - Startup". (Bug#11091) - -2012-04-02 Dani Moncayo (tiny change) - - * custom.texi (Changing a Variable): Fix example. - -2012-04-01 Eli Zaretskii - - * misc.texi (emacsclient Options): More clarifications about -t - and -c on MS-Windows. (Bug#11091) - -2012-03-31 Eli Zaretskii - - * misc.texi (emacsclient Options): Document peculiarities of new - frame creation on MS-Windows under -c or -t options. (Bug#11091) - -2012-03-30 Chong Yidong - - * files.texi (File Conveniences): Clarify Imagemagick discussion. - -2012-03-22 Glenn Morris - - * dired.texi (Operating on Files): Fix dired-recursive-copies default. - -2012-03-17 Chong Yidong - - * package.texi (Package Installation): Document use of - package-initialize in init file. - -2012-03-16 Glenn Morris - - * help.texi (Language Help): - * mule.texi (International Chars): - etc/HELLO is for character demonstration. - -2012-03-15 Dani Moncayo (tiny change) - - * dired.texi (Shell Commands in Dired): Fix typo. - -2012-03-04 Chong Yidong - - * killing.texi (Clipboard): Document clipboard manager. - -2012-02-29 Glenn Morris - - * ack.texi (Acknowledgments): Use @Tex{} in more places. - - * emacs.texi, help.texi, text.texi: Use "" quotes in menus. - - * dired.texi, emacs.texi: Use @code{} in menus when appropriate. - -2012-02-28 Glenn Morris - - * custom.texi, display.texi, emacs.texi, files.texi: - * msdog-xtra.texi, msdog.texi, vc-xtra.texi: - Standardize possessive apostrophe usage. - -2012-02-25 Jan Djärv - - * macos.texi (Mac / GNUstep Customization): Remove text about - ns-find-file and ns-drag-file (Bug#5855, Bug#10050). - -2012-02-25 Dani Moncayo (tiny change) - - * buffers.texi (Select Buffer): Mention that saving in a new file - name can switch to a different major mode. - -2012-02-23 Glenn Morris - - * mini.texi (Minibuffer File, Completion Options, Repetition): - Copyedits. - (Completion Example): Other M-x au* commands may be defined. - (Completion Styles): Mention emacs21 and completion-category-overrides. - - * msdog.texi (Text and Binary, ls in Lisp, Windows HOME) - (Windows Keyboard, Windows Mouse, Windows Processes) - (Windows Printing, Windows Misc): Copyedits. - (ls in Lisp): Update switches list. - - * msdog-xtra.texi (MS-DOS Display): Update list-colors-display xref. - Update dos-mode* function names. - (MS-DOS Printing, MS-DOS and MULE): Copyedits. - (MS-DOS Processes): Add xref to main ls-lisp section. - - * ack.texi (Acknowledgments): Mention smie. - -2012-02-22 Glenn Morris - - * macos.texi: Copyedits. Fix @key/@kbd usage. - (Mac / GNUstep Basics): Don't mention the panels, since the next - section covers them. - (Mac / GNUstep Customization): Merge some panel info from previous. - -2012-02-21 Glenn Morris - - * emerge-xtra.texi (Emerge, Submodes of Emerge, Combining in Emerge): - Small fixes. - - * emacs-xtra.texi: Picture mode is no longer a chapter. - - * picture-xtra.texi (Basic Picture): C-a does get remapped. - - * ack.texi (Acknowledgments): Small changes, including resorting, - and removal of things no longer distributed. - -2012-02-20 Glenn Morris - - * emacs.texi (Top, Preface): Small rephrasings. - (menu, detailmenu): Update entries, and reformat some descriptions. - * building.texi, display.texi, emacs-xtra.texi, files.texi: - * frames.texi, kmacro.texi, msdog.texi, programs.texi, text.texi: - Reformat some menu descriptions. - - * ack.texi (Acknowledgments): More updates. - - * emacs.texi (Acknowledgments): Add several names from ack.texi, - and from Author: headers. - (Distrib): Small updates. - -2012-02-18 Glenn Morris - - * ack.texi (Acknowledgments): Add xref to Org manual. - - * rmail.texi: Copyedits. Use 'mail composition buffer' in place - of '*mail*', since Message does not call it that. - (Rmail Reply): Rename rmail-dont-reply-to-names. - \\`info- no longer handled specially. - Update for rmail-enable-mime-composing. - Don't mention 'm' for replies. - Don't mention rmail-mail-new-frame and cancelling, since it does - not work for Message at the moment. - - * cal-xtra.texi: Copyedits. - - * emacs-xtra.texi: Set encoding to ISO-8859-1. - -2012-02-17 Glenn Morris - - * maintaining.texi (Old Revisions): Fix cross-refs to Ediff manual. - - * ack.texi (Acknowledgments): Mention Gnulib. - - * ack.texi, calendar.texi, cal-xtra.texi: Use "Bahá'í". - - * calendar.texi: Misc small changes, including updating the dates - of examples. - -2012-02-16 Glenn Morris - - * calendar.texi: Misc small changes. - - * vc1-xtra.texi (VC Delete/Rename, CVS Options): - * cal-xtra.texi (Diary Display): Fix TeX cross-refs to other manuals. - - * dired-xtra.texi (Subdir Switches): Small fixes. - - * fortran-xtra.texi: Tiny changes and some adjustments to line breaks. - -2012-02-15 Glenn Morris - - * sending.texi (Mail Sending): smtpmail-auth-credentials was removed. - -2012-02-12 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Updates for new files in 24.1. - -2012-02-10 Glenn Morris - - * mini.texi (Minibuffer Edit): Mention minibuffer-inactive-mode. - - * programs.texi (Misc for Programs): Mention electric-layout-mode. - -2012-02-09 Glenn Morris - - * buffers.texi (Misc Buffer): M-x info does not seem to require a - buffer switch after M-x rename-uniquely. - - * trouble.texi (Checklist): Mention C-c m in report-emacs-bug. - -2012-02-09 Jay Belanger - - * text.texi (Org Mode): Fix typo. - -2012-02-08 Glenn Morris - - * ack.texi (Acknowledgments): Update emacs-lock info. - - * rmail.texi (Rmail Display): Mention rmail-epa-decrypt. - - * text.texi (LaTeX Editing): Mention latex-electric-env-pair-mode. - -2012-02-07 Glenn Morris - - * files.texi (File Conveniences): Mention ImageMagick images. - -2012-02-05 Glenn Morris - - * trouble.texi (Checklist): Mention debug-on-event. - - * maintaining.texi (Maintaining): Add cross-ref to ERT. - -2012-02-04 Glenn Morris - - * macos.texi (Customization options specific to Mac OS / GNUstep): - New subsection. - - * display.texi (Colors): Mention list-colors-sort. - - * files.texi (File Conveniences): Mention image animation. - -2012-01-31 Chong Yidong - - * windows.texi (Split Window): C-mouse-2 doesn't work on GTK+ - scroll bars (Bug#10666). - -2012-01-28 Chong Yidong - - * files.texi (Filesets): Fix typos. - - * display.texi (Faces): Add xref to Colors node. - -2012-01-27 Dani Moncayo - - * buffers.texi (Select Buffer): Clarify explanation of switching - to new buffers. Fix description of next-buffer and - previous-buffer (Bug#10334). - (Misc Buffer): Add xref to View Mode. - - * text.texi (Fill Commands): Fix description of - sentence-end-double-space. - -2012-01-23 Chong Yidong - - * anti.texi (Antinews): Add Emacs 23 antinews. - -2012-01-16 Volker Sobek (tiny change) - - * programs.texi (Comment Commands): Typo (bug#10514). - -2012-01-15 Chong Yidong - - * xresources.texi (X Resources): Describe GTK+ case first. - (Resources): Don't use borderWidth as an example, since it doesn't - work with GTK+. - (Table of Resources): Clarify role of several resources, including - the Emacs 24 behavior of cursorBlink etc. - (Face Resources): Node deleted. Recommend using Customize - instead. Add paragraph to `Table of Resources' node summarizing - how to use X resources for changing faces. - (Lucid Resources): Rewrite, omitting description of font names, - referring to the Fonts node instead. - (LessTif Resources): Copyedits. - (GTK resources): Rewrite, describing the difference between gtk2 - and gtk3. - (GTK Resource Basics): New node. - (GTK Widget Names, GTK Names in Emacs): Rewrite. - (GTK styles): Just refer to Fonts node for GTK font format. - - * display.texi (Faces): Document the cursor face. - -2012-01-14 Chong Yidong - - * cmdargs.texi (Action Arguments): No need to mention EMACSLOADPATH. - (General Variables): Add xref to Lisp Libraries. - (Initial Options): Copyedits. - (Resume Arguments): Node deleted; emacs.bash/csh are obsolete. - (Environment): Clarify what getenv does. - (General Variables): Clarify EMACSPATH etc. Emacs does not assume - light backgrounds on xterms. - (Misc Variables): TEMP and TMP are not Windows-specific. - (Display X): Copyedits. - (Colors X): -bd does nothing for GTK. - (Icons X): Gnome 3 doesn't use taskbars. - - * misc.texi (Shell): Document exec-path here. - - * rmail.texi (Movemail): Add xref for exec-path. - -2012-01-13 Glenn Morris - - * dired.texi (Dired and Find): Clarify find-ls-options. - -2012-01-09 Chong Yidong - - * custom.texi (Custom Themes): Switched custom-safe-themes to use - SHA-256. - -2012-01-07 Chong Yidong - - * display.texi (Useless Whitespace): Add Whitespace mode. - - * custom.texi (Hooks): Discuss how to disable minor modes. - - * files.texi (Diff Mode): Discuss diff-auto-refine-mode - (Bug#10309). Discuss use of Whitespace mode (Bug#10300). - - * trouble.texi (Lossage): Refer to Bugs node for problems. - (DEL Does Not Delete): Don't use "usual erasure key" teminology. - (Screen Garbled): Don't refer to terminal "manufacturers". - (Total Frustration): Node deleted. Eliza is documented in - Amusements now. - (Known Problems): More info about using the bug tracker. Mention - debbugs package. - (Bug Criteria): Copyedits. - (Understanding Bug Reporting): Mention emacs -Q. - -2012-01-06 Chong Yidong - - * custom.texi (Specifying File Variables): The mode: keyword - doesn't have to be first anymore. Add example of specifying minor - modes. - (Directory Variables): Simplify example. Mention application to - non-file buffers. - (Disabling): Use "initialization file" terminology. - (Init Examples): Fix hook example. - -2012-01-06 Eli Zaretskii - - * cmdargs.texi (MS-Windows Registry): Shorten the index entry. - (Bug#10422) - Move the stuff about resources to xresources.texi. - - * xresources.texi (Resources): Move information about setting X - resources in the Registry from cmdargs.texi. Make the index entry - be similar to the one in cmdargs.texi. - -2012-01-05 Chong Yidong - - * custom.texi (Customization Groups): Update example. - (Browsing Custom): Document the new search field. - (Changing a Variable): Update example for Emacs 24 changes. - Document Custom-set and Custom-save commands. - (Face Customization): Document Emacs 24 changes. De-document - modify-face. - (Specific Customization): Mention customize-variable. - (Custom Themes): Add customize-themes, custom-theme-load-path, - custom-theme-directory, and describe-theme. - (Creating Custom Themes): New node. - (Examining): Mention M-:. - - * package.texi (Packages): Fix typo. - -2012-01-03 Chong Yidong - - * misc.texi (Single Shell): Don't document Lisp usage of - shell-command. Tidy up discussion of synchronicity. Add index - entries for async-shell-command. - (Interactive Shell): Note that M-x shell uses shell-file-name. - Note change in behavior in Emacs 24. - (Shell Mode): Shell mode now uses completion-at-point. - (Shell Prompts): Emphasize that comint-use-prompt-regexp isn't the - default method for recognizing prompts nowadays. - (Shell Ring): Add xref to Minibuffer History. - (Directory Tracking): Explain Dirtrack mode in more detail. - (Term Mode): Fix index entries. - (Paging in Term): Merge into Term Mode. - (Serial Terminal, Emacs Server, emacsclient Options): Copyedits. - (Printing): Fix xref. State default of lpr-switches. - (PostScript): Remove obsolete sentence. Omit description of - non-interactive behaviors. - (Hyperlinking): Improve description. - (Browse-URL): Using compose-mail for mailto URLs is the default. - Document browse-url-mailto-function. - (Goto Address mode): Add index entries. Add xref to Browse-URL. - (FFAP): FFAP is not a minor mode. - (Amusements): M-x lm was renamed to M-x landmark. Document - nato-region. - -2012-01-01 Chong Yidong - - * misc.texi (Gnus, Buffers of Gnus): Copyedits. - (Gnus Startup): Note that the system might not be set up for news. - Describe group levels more clearly. - (Gnus Group Buffer, Gnus Summary Buffer): New nodes, split from - Summary of Gnus. - (Document View): Copyedits. Move zoom commads to DocView - Navigation node. - (DocView Navigation, DocView Searching, DocView Slicing) - (DocView Conversion): Nodes renamed from Navigation, etc. - - * sending.texi (Mail Sending): Add message-kill-buffer-on-exit. - -2011-12-31 Eli Zaretskii - - * basic.texi (Moving Point): Fix the description of C-n and C-p. - (Bug#10380) - -2011-12-30 Chong Yidong - - * sending.texi (Sending Mail): Document initial mail buffer name, - and changed multiple mail buffer behavior. - (Mail Format): Put the example at the top of the section. - (Mail Headers): Move discussion of "From" to the top. - (Mail Sending): Document sendmail-query-once. - (Citing Mail): Make it less Rmail-specific. - -2011-12-29 Chong Yidong - - * text.texi (Org Mode): Copyedits. Refer to Outline Format for - example. Add index entries. - (Org Organizer, Org Authoring): Nodes renamed. Copyedits. - -2011-12-26 Chong Yidong - - * dired.texi (Dired Enter, Misc Dired Features): Document - dired-use-ls-dired changes. Mention quit-window. - (Dired Navigation): Add index entries. - (Dired Visiting): Fix View Mode xref. - (Marks vs Flags): Prefer C-/ binding for undo. - (Subdirectories in Dired): Add xrefs. - (Misc Dired Features): Document some Emacs 24 changes. Add index - entries. - - * abbrevs.texi (Abbrev Concepts): No need to mention abbrev-mode - variable, since it is explained in Minor Modes node. - (Defining Abbrevs): Copyedits. - (Expanding Abbrevs): State default of abbrev-all-caps. Prefer the - C-/ binding for undo. - (Dabbrev Customization): Add xrefs for case-fold-search and - case-replace. - - * dired-xtra.texi (Subdir Switches): Add xref. - - * maintaining.texi (VC Directory Commands): Mention quit-window. - -2011-12-25 Chong Yidong - - * maintaining.texi (Tags): Mention Semantic. - (Create Tags Table, Etags Regexps): Copyedits. - (Find Tag): Mention minibuffer completion. - (List Tags): Mention completion-at-point. Completion is actually - available in M-x list-tags. - - * vc1-xtra.texi (VC Delete/Rename): Rename from Renaming and VC. - Document vc-delete-file. - - * files.texi (Misc File Ops): Mention vc-delete-file. - - * programs.texi (Symbol Completion): Mention completion-at-point - explicitly. - -2011-12-22 Chong Yidong - - * maintaining.texi (Change Log Commands): Don't specially mention - vc-update-change-log which is CVS-only. - - * vc1-xtra.texi (Version Headers): Note that these are for - Subversion, CVS, etc. only. - (General VC Options): De-document vc-keep-workfiles. Fix - RCS-isms. - -2011-12-22 Eli Zaretskii - - * building.texi (Debugger Operation): Fix a typo: "@end iftext" - should be @end iftex". - -2011-12-21 Chong Yidong - - * maintaining.texi (Advanced C-x v v): Use fileset terminology. - (VC With A Merging VCS, VC Change Log): Add xref to VC Pull node. - (VC Pull): Mention vc-log-incoming. - (Log Buffer): Add CVS/RCS only disclaimer. - - * vc1-xtra.texi (Remote Repositories): Update introduction. - (Local Version Control): Node deleted (obsolete with DVCSes). - (Remote Repositories, Version Backups): Node deleted. Move - documentation of vc-cvs-stay-local to CVS Options. - (CVS Options): Reduce verbosity of description of obscure CVS - locking feature. - (Making Revision Tags, Revision Tag Caveats): Merge into Revision - Tags node. - (Revision Tags): Move under Miscellaneous VC subsection. - (Change Logs and VC): Note that this is wrong for DVCSs. - De-document log entry manipulating features. - (Renaming and VC): Describe how it works on modern VCSes. - - * files.texi (Misc File Ops): Mention vc-rename-file. - - * programs.texi (Custom C Indent): Add index entries. - -2011-12-20 Alan Mackenzie - - * programs.texi (Motion in C): Update the description of C-M-a and - C-M-e, they now DTRT in enclosing scopes. - (Custom C Indent): Add @dfn{guessing} of the indentation style. - -2011-12-20 Chong Yidong - - * maintaining.texi (VCS Concepts): Add "working tree" terminology. - (Old Revisions): Use it. - (VCS Repositories): Add "distributed" terminology. - (Log Buffer): Remove duplicate description - about changesets. Fix "current VC fileset" ambiguity. - (Multi-User Branching): Node deleted. - (Branches, Switching Branches): Discuss decentralized version - control systems. - (VC Pull): New node. - (Merging): Document merging on decentralized systems. - (Creating Branches): Note that this is specific to CVS and related - systems. - -2011-12-19 Chong Yidong - - * maintaining.texi (VCS Merging, VCS Changesets): Index entries. - (VC Mode Line): Add index entry for "version control status". - (VC Undo): Use vc-revert instead of its vc-revert-buffer alias. - Document vc-revert-show-diff. De-document vc-rollback. - (VC Directory Mode): Rewrite introduction. Move prefix arg - documentation here from VC Directory Buffer node. - (VC Directory Buffer): Use a decentralized VCS example. - (VC Directory Commands): Use a table. Remove material duplicated - in previous nodes on multi-file VC filsets. - -2011-12-17 Chong Yidong - - * maintaining.texi (VCS Concepts): Make "revision" terminology - less CVS-specific. - (VC With A Merging VCS, VC With A Locking VCS): Add xref to - Registering node. - (Secondary VC Commands): Deleted. Promote subnodes. - (Log Buffer): Add command name for C-c C-c. Fix the name of the - log buffer. Add index entries. - (VCS Changesets, Types of Log File, VC With A Merging VCS): Use - "commit" terminology. - (Old Revisions): Move it to just before VC Change Log. "Tag" here - doesn't refer to tags tables. Note other possible forms of the - revision ID. C-x v = does not save. - (Registering): Note similarity to C-x v v action. Fix description - of how backends are chosen. De-document vc-default-init-revision. - (VC Change Log): Document C-x v l in VC-Dir buffer. Document RET - in root log buffers. - -2011-12-16 Chong Yidong - - * maintaining.texi (Version Control Systems): Drop Meta-CVS. - (Basic VC Editing): Remove redundant descriptions. - (VC With A Merging VCS): Make description more general instead of - CVS-specific. - (VC With A Locking VCS): Use VC fileset terminology. - -2011-12-12 Chong Yidong - - * building.texi (Executing Lisp): Fix xref for C-M-x. - (Lisp Libraries): Add xref to node explaining `load' in Lisp - manual. Note that load-path is not customizable. - (Lisp Eval): Note that listed commands are available globally. - Explain the meaning of "defun" in the C-M-x context. - (Lisp Interaction): Copyedits. - (External Lisp): Fix name of inferior Lisp buffer. Mention - Scheme. - (Compilation): Define "inferior process". - -2011-12-10 Eli Zaretskii - - * msdog.texi (Windows Fonts): Document how to force GDI font - backend on MS-Windows. - -2011-12-10 Chong Yidong - - * building.texi (Compilation): Say what the -k flag to make does. - Move subprocess discussion to Compilation Shell. - (Compilation Mode): Add xref for grep, occur, and mouse - references. Define "locus". - (Grep Searching): Use @command. - (Debuggers, Commands of GUD, GDB Graphical Interface): Clarify - intro. - (Starting GUD): Clarify how arguments are specified. - (Debugger Operation): Index entry for "GUD interaction buffer", - and move basic description here from Commands of GUD node. - (GDB User Interface Layout): Copyedits. - (Source Buffers): Remove gdb-find-source-frame, which is not in - gdb-mi.el. - (Other GDB Buffers): Remove gdb-use-separate-io-buffer and - toggle-gdb-all-registers, which are not in gdb-mi.el. Don't - re-document GUD interaction buffers. - - * programs.texi (Symbol Completion): M-TAB can now use Semantic. - (Semantic): Add cindex entries for Semantic. - -2011-12-06 Chong Yidong - - * programs.texi (Man Page): Clarify how to use Man-switches. - Don't bother documenting Man-fontify-manpage-flag. - (Lisp Doc): Add xref to Name Help node. - (Hideshow): Add cindex. Mention role of ellipses, and default - value of hs-isearch-open. Don't bother documenting - hs-special-modes-alist. - (Symbol Completion): Add kindex for C-M-i. Don't recommend - changing the window manager binding of M-TAB. - -2011-12-05 Chong Yidong - - * programs.texi (Comment Commands): Fix description of for M-; on - blank lines. Move documentation of comment-region here. - (Multi-Line Comments): Clarify the role of comment-multi-line. - Refer to Comment Commands for comment-region doc. - (Options for Comments): Refer to Multi-Line Comments for - comment-multi-line doc, instead of duplicating it. Fix default - values of comment-padding and comment-start-skip. - -2011-12-04 Chong Yidong - - * programs.texi (Program Modes): Mention modes that are not - included with Emacs. Fix references to other manuals for tex. - Add index entry for backward-delete-char-untabify. Mention - prog-mode-hook. - (Which Function): Use "global minor mode" terminology. - (Basic Indent, Multi-line Indent): Refer to previous descriptions - in Indentation chapter to avoid duplication. - (Expressions): Copyedit. - (Matching): Document Electric Pair mode. - - * ack.texi (Acknowledgments): - * rmail.texi (Movemail, Other Mailbox Formats): - * frames.texi (Frames): Don't capitalize "Unix". - -2011-12-04 Chong Yidong - - * text.texi (Nroff Mode): Mention what nroff is. - (Text Based Tables, Table Recognition): Don't say "Table mode" - since it's not a major or minor mode. - (Text Based Tables): Reduce the size of the example. - (Table Definition): Clarify definitions. - (Table Creation): Add key table. - (Cell Commands): Use kbd for commands. - (Table Rows and Columns): Combine nodes Row Commands and Column - Commands. - (Fixed Width Mode): Node deleted; contents moved to parent. - (Table Conversion): Shorten example. - (Measuring Tables): Merge into Table Misc. - -2011-12-03 Chong Yidong - - * text.texi (TeX Mode): Mention AUCTeX package. - (TeX Editing): Add xref to documentation for Occur. - (LaTeX Editing): Add xref to Completion node. - (TeX Print): Fix description of tex-directory. - (Enriched Text): Renamed from Formatted Text. Make this node and - its subnodes less verbose, since text/enriched files are - practically unused. - (Enriched Mode): Renamed from Requesting Formatted Text. - (Format Colors): Node deleted. - (Enriched Faces): Renamed from Format Faces. Describe commands - for applying colors too. - (Forcing Enriched Mode): Node deleted; merged into Enriched Mode. - - * frames.texi (Menu Mouse Clicks): Tweak description of C-Mouse-2. - - * display.texi (Colors): New node. - - * cmdargs.texi (Colors X): - * xresources.texi (GTK styles): - * custom.texi (Face Customization): Reference it. - - * glossary.texi (Glossary): Remove "formatted text" and "WYSIWYG". - Link to Fill Commands for Justification entry. - -2011-12-03 Eli Zaretskii - - * display.texi (Auto Scrolling): More accurate description of what - scroll-*-aggressively does, including the effect of non-zero - margin. Fix "i.e." markup. - -2011-12-02 Chong Yidong - - * text.texi (Pages): Mention how formfeed chars are displayed. - (Auto Fill): Note convention for calling auto-fill-mode from Lisp. - Describe adaptive filling more precisely. - (Fill Commands): Note that filling removes excess whitespace. - (Text Mode): Note auto-mode-alist entries for Text mode. TAB is - now bound to indent-for-tab-command in Text mode. - (Outline Mode): Copyedits. - (Outline Visibility): Note that Reveal mode is a buffer-local - minor mode. - - * modes.texi (Major Modes): Move note about checking major-mode in - a hook function here, from Text mode. - -2011-11-28 Chong Yidong - - * text.texi (Words): Add xref to Position Info. - (Paragraphs): Add xref to Regexps. - - * indent.texi (Indentation): Rewrite introduction. Move table to - Indentation Commands node. - (Indentation Commands): Add index entries to table. Copyedits. - (Tab Stops, Just Spaces): Copyedits. - (Indent Convenience): New node. Document electric-indent-mode. - - * programs.texi (Basic Indent): - * windows.texi (Pop Up Window): Fix kindex entry. - -2011-11-28 Chong Yidong - - * modes.texi (Major Modes): Move major-mode variable doc here from - Choosing Modes. Document describe-mode. Document prog-mode-hook - and text-mode-hook. Add example of using hooks. - (Minor Modes): Document behavior of mode command calls from Lisp. - Note that setting the mode variable using Customize will DTRT. - (Choosing Modes): Add example of setting a minor mode using a - local variable. - -2011-11-27 Chong Yidong - - * frames.texi (Creating Frames): Move frame parameter example to - Frame Parameters node. - (Frame Commands): C-x 5 o does not warp the mouse by default. - (Fonts): Add more GTK-style properties; also, they should be - capitalized. - (Special Buffer Frames): Node deleted; special-display is on the - way out. - (Frame Parameters): Example moved here from Creating Frames. - Clarify that default-frame-alist affects the initial frame too. - Delete auto-raise-mode and auto-lower-mode. - (Wheeled Mice): Node deleted. Content moved to Mouse Commands. - (Dialog Boxes): Delete x-gtk-use-old-file-dialog. - - * windows.texi (Window Choice): Add xref to Lisp manual for - special-display-*. - -2011-11-26 Eli Zaretskii - - * display.texi (Text Display): Update the description, - cross-references, and indexing related to display of control - characters and raw bytes. - -2011-11-25 Chong Yidong - - * frames.texi (Frames): Rewrite introduction. - (Mouse Commands): Default for mouse-drag-copy-region is now t. - Mouse-3 does not copy to kill ring by default. DEL does not - behave specially for mouse commands any more. - (Mouse References): Document mouse-1-click-follows-link more - thoroughly. - (Menu Mouse Clicks): Move footnote to the main text and add xref - to Init Rebinding node. - (Mode Line Mouse): Mouse-3 on the mode-line does not bury buffer. - - * files.texi (Visiting): `C-x 5 f' works on ttys too. - -2011-11-24 Juanma Barranquero - - * display.texi (Font Lock): Fix typo. - -2011-11-24 Glenn Morris - - * rmail.texi (Rmail Output): - Mention rmail-automatic-folder-directives. (Bug#9657) - -2011-11-21 Chong Yidong - - * mark.texi (Global Mark Ring): Fix description of global mark - ring (Bug#10032). - -2011-11-20 Juanma Barranquero - - * msdog.texi (Windows Fonts): Fix typo. - -2011-11-17 Glenn Morris - - * regs.texi (Bookmarks): Small fixes related to saving. (Bug#10058) - -2011-11-16 Juanma Barranquero - - * killing.texi (Rectangles): - * misc.texi (Document View): - * modes.texi (Choosing Modes): - * msdog.texi (Windows Fonts): - * regs.texi (Rectangle Registers): - * search.texi (Isearch Yank): Fix typos. - -2011-11-06 Chong Yidong - - * windows.texi (Basic Window): Add xref to Cursor Display. - (Split Window): Document negative arg for splitting commands. - (Other Window): Document mouse-1 in text area of window. - (Change Window): Don't mention window attributes, since they - aren't defined. C-x 1 can't be used with minibuffer windows. - Windows are no longer auto-deleted. - (Window Choice): Add xref to Choosing Window in Lisp manual. - (Window Convenience): Note that windmove disables shift-selection. - Move M-x compare-windows here from Other Window node. - - * custom.texi (Mouse Buttons): - * search.texi (Isearch Scroll): - * windows.texi (Split Window): Use new names split-window-below - and split-window-right. - -2011-10-26 Juanma Barranquero - - * emacs.texi (Top): Fix typo. - -2011-10-25 Glenn Morris - - * abbrevs.texi (Saving Abbrevs): - quietly-read-abbrev-file is not a command. (Bug#9866) - -2011-10-24 Chong Yidong - - * display.texi (Scrolling): Document scroll-up-line and - scroll-down-line. Document scroll-command property. - (Recentering): New node, split off from Scrolling. - -2011-10-23 Chong Yidong - - * frames.texi (Scroll Bars): GTK uses right scroll bars now. - (Tool Bars): Copyedits. - - * buffers.texi (Misc Buffer): Don't mention vc-toggle-read-only. - -2011-10-22 Chong Yidong - - * windows.texi (Displaying Buffers): Fix broken lispref link. - -2011-10-22 Chong Yidong - - * mini.texi (Minibuffer Exit): Rename from Strict Completion. - Move confirm-nonexistent-file-or-buffer discussion here. - - * files.texi (File Names, Visiting): Move detailed discussion of - minibuffer confirmation to Minibuffer Exit. - - * buffers.texi (Buffers): Tweak mention of mail buffer name. - (Select Buffer): Move confirmation discussion to Minibuffer Exit. - -2011-10-21 Chong Yidong - - * files.texi (File Names, Visiting, Interlocking): Copyedits. - (Backup Copying): backup-by-copying-when-mismatch is now t. - (Customize Save): Fix description of require-final-newline. - (Reverting): Note that revert-buffer can't be undone. Mention VC. - (Auto Save Control): Clarify. - (File Archives): Add 7z. - (Remote Files): ange-ftp-make-backup-files defaults to nil. - - * arevert-xtra.texi (Autorevert): Copyedits. - -2011-10-20 Chong Yidong - - * custom.texi (Hooks, Init Examples): - * display.texi (Font Lock): - * fixit.texi (Spelling): - * rmail.texi (Rmail Display): Minor mode function with no arg now - enables it. - - * fixit.texi (Spelling): Fix description of inline completion. - -2011-10-19 Chong Yidong - - * search.texi (Repeat Isearch, Error in Isearch): Add kindex - entries. - (Isearch Yank): Document isearch-yank-pop. - (Isearch Scroll): Refer to C-l instead of unbound `recenter'. - (Other Repeating Search): Document Occur Edit mode. - -2011-10-18 Chong Yidong - - * display.texi (Fringes): Move overflow-newline-into-fringe here, - from Line Truncation node. - (Standard Faces): Note that only the background of the cursor face - has an effect. - (Cursor Display): Fix descriptions of cursor face - and bar cursor blinking. - (Text Display): Document nobreak-char-display more clearly. - (Line Truncation): Add xref to Split Window node. - (Display Custom): Don't bother documenting baud-rate or - no-redraw-on-reenter. - - * search.texi (Slow Isearch): Node removed. - -2011-10-18 Glenn Morris - - * maintaining.texi (Registering): Remove vc-initial-comment. (Bug#9745) - -2011-10-18 Chong Yidong - - * display.texi (Faces): Simplify discussion. Move documentation - of list-faces-display here, from Standard Faces node. Note - special role of `default' background. - (Standard Faces): Note special role of `default' background. Note - that region face may be taken fom GTK. Add xref to Text Display. - (Text Scale): Rename from "Temporary Face Changes". Callers - changed. Don't bother documenting variable-pitch-mode. - (Font Lock): Copyedits. Remove font-lock-maximum-size. - (Useless Whitespace): Simplify description of - delete-trailing-whitespace. Note active region case. - (Text Display): Fix description of escape-glyph face assignment. - Remove unibye mode discussion. Update some parts for Unicode. - Move glyphless chars documentation to Lisp manual. - - * frames.texi (Tooltips): Document x-gtk-use-system-tooltips. - -2011-10-15 Chong Yidong - - * display.texi (Scrolling): Tweak explanation of scroll direction. - (View Mode): Add index entries. - - * killing.texi (Deletion): Document negative prefix arg to M-SPC. - - * regs.texi (Text Registers): C-x r i does not activate the mark. - (Bookmarks): Document new default bookmark location. - -2011-10-13 Chong Yidong - - * killing.texi (Deletion): Add xref to Using Region. Document - delete-forward-char. - (Yanking): Move yank-excluded-properties to Lisp manual. Move C-y - description here. Recommend C-u C-SPC for jumping to mark. - (Kill Ring): Move kill ring variable documentation here. - (Primary Selection): Copyedits. - (Rectangles): Document new command rectangle-number-lines. - (CUA Bindings): Note that this disables the mark-even-if-inactive - behavior for C-x and C-c. - - * mark.texi (Mark): Mention "active region" terminology. - (Using Region): Document delete-active-region. - -2011-10-12 Chong Yidong - - * mark.texi (Mark): Clarify description of disabled Transient Mark - mode (Bug#9689). - (Setting Mark): Document prefix arg for C-x C-x. Document primary - selection changes. Mention that commands like C-y set the mark. - (Marking Objects): Add xref to Words node. Note that mark-word - and mark-sexp also have the "extend region" behavior. - (Using Region): Mention M-$ in the table. Document - mark-even-if-inactive here instead of in Mark Ring. - (Mark Ring): Move mark-even-if-inactive to Using Region. Take - note of the "Mark Set" behavior. - (Disabled Transient Mark): Rename from "Persistent Mark" - (Bug#9688). Callers changed. - - * programs.texi (Expressions): - * text.texi (Words): Defer to Marking Objects for mark-word doc. - -2011-10-09 Chong Yidong - - * help.texi (Help, Help Summary): Eliminate the unnecessary "help - option" terminology. - (Key Help): Add command names. Define "documentation string". - (Name Help): Remove an over-long joke. - (Apropos): Document prefix args. Remove duplicated descriptions. - (Help Mode): Add C-c C-b to table. Update TAB binding. - (Package Keywords): Rename from "Library by Keyword". Describe - new package menu interface. - (Help Files, Help Echo): Tweak description. - - * mini.texi (Completion Options): Add completion-cycle-threshold. - (Minibuffer History): Document numeric args to history commands. - -2011-10-08 Eli Zaretskii - - * mule.texi (Bidirectional Editing): Correct some inaccuracies. - -2011-10-08 Chong Yidong - - * basic.texi (Position Info): Omit page commands. Document - count-words-region and count-words. - - * text.texi (Pages): Move what-page documentation here. - -2011-10-08 Chong Yidong - - * mini.texi (Minibuffer File): Minor copyedits. Use xref to - Remote Files node instead of linking directly to the Tramp manual. - (Minibuffer Edit): Add xref to Blank Lines. - (Completion): Add xref to Symbol Completion. Remove redundant - example, which is repeated in the next node. - (Completion Commands): Minor clarifications. - (Completion Styles): New node, split from Completion Commands. - Document substring and initials styles. - (Strict Completion): Remove information duplicated in other nodes. - (Completion Options): Consolidate case difference discussion here. - - * help.texi (Help Mode): Fix kindex entries. - - * files.texi (File Names): Add index entries. - -2011-10-07 Chong Yidong - - * basic.texi (Inserting Text): Add xref to Completion. Add - ucs-insert example, and document prefix argument. - (Moving Point): Fix introduction; C-f/C-b are no longer equivalent - to left/right. Tweak left-char and right-char descriptions. - M-left and M-right are now bound to left-word/right-word. - (Erasing): Document delete-forward-char. - - * screen.texi (Screen, Menu Bar): Copyedits. - (Point): Remove duplicate paragraph on cursors, also in Screen. - (Mode Line): Trailing dashes no longer shown on X displays. - - * frames.texi (Non-Window Terminals): Index just "text-only - terminal", which is used throughout the manual now. - - * entering.texi (Entering Emacs): Define "startup screen". - Document window-splitting behavior with command-line inputs. - (Exiting): Remove obsolete paragraph about shells without suspend - functionality. - - * commands.texi (User Input): Define "input event" more clearly. - (Keys): Add xref to Echo Area. - (Commands): Clarify relation between commands and functions. - -2011-10-06 Chong Yidong - - * misc.texi (emacsclient Options): Document how emacsclient runs - the Emacs daemon (Bug#9674). - -2011-10-01 Chong Yidong - - * basic.texi (Moving Point): - * custom.texi (Mouse Buttons): - * rmail.texi (Rmail Scrolling): - * search.texi (Isearch Scroll): - - * display.texi (Scrolling): Replace scroll-up/down with - scroll-up/down-command. Fix scroll-preserve-screen-position - description. Document scroll-error-top-bottom. - -2011-09-30 Glenn Morris - - * commands.texi (Keys): Whitespace fix. (Bug#9635) - -2011-09-24 Chong Yidong - - * windows.texi (Pop Up Window): Defer discussion of window - splitting to the Window Choice node. Add index entries. - (Force Same Window): Node deleted. - (Displaying Buffers, Window Choice): New nodes. - - * buffers.texi (Select Buffer): Clarify description of - buffer-switching commands. Add xref to Window Display node. - Don't repeat confirm-nonexistent-file-or-buffer description from - Visiting node. Remove even-window-heights. - - * frames.texi (Special Buffer Frames): Add xref to Window Choice. - -2011-09-18 Chong Yidong - - * cmdargs.texi (Icons X): Fix description of Emacs icon. - - * xresources.texi (Table of Resources): Fix documentation of - bitmapIcon. - -2011-09-15 Chong Yidong - - * package.texi (Package Menu): Add package-menu-mark-upgrades. - -2011-09-12 Eric Hanchrow - - * frames.texi (Frame Commands): Note that delete-other-frames only - deletes frames on current terminal. - -2011-09-10 Eli Zaretskii - - * sending.texi (Mail Misc): Document mail-add-attachment. - -2011-09-04 Eli Zaretskii - - * basic.texi (Inserting Text): Add index entries. (Bug#9433) - -2011-08-29 Chong Yidong - - * modes.texi (Choosing Modes): auto-mode-case-fold is now t. - -2011-08-28 Chong Yidong - - * files.texi (File Archives): - * cal-xtra.texi (Diary Display): - * help.texi (Help Mode): Add xref to View Mode. - -2011-08-28 Chong Yidong - - * display.texi (View Mode): New node. Move view-file here from - Misc File Ops. Move view-buffer here from Misc Buffer. - - * buffers.texi (Misc Buffer): Move view-buffer to View Mode. - - * files.texi (Misc File Ops): Document new - delete-by-moving-to-trash behavior. Remove view-file. - - * dired.texi (Dired Deletion): Shorten description of Trash. - - * misc.texi (emacsclient Options): Document server-port. - -2011-08-27 Eli Zaretskii - - * frames.texi (Frame Commands): Advise setting focus-follows-mouse - even on MS-Windows. Fix a typo. - -2011-08-26 Chong Yidong - - * package.texi: New file, documenting the package manager. - - * emacs.texi: Include it. - - * help.texi (Help Summary): Add describe-package. - -2011-08-25 Chong Yidong - - * misc.texi (Printing): Convert subnodes into subsections. - - * text.texi (Two-Column): Move into Text chapter. - - * picture-xtra.texi (Picture Mode): Group with Editing Binary - Files section. Convert from chapter into section. - - * display.texi (Narrowing): Move into display chapter. - - * sending.texi (Sending Mail): - * rmail.texi (Rmail): - * misc.texi (Gnus, Document View): - * dired.texi (Dired): - * emacs.texi: Group the mail, rmail, and gnus chapters together. - -2011-08-07 Juri Linkov - - * dired.texi (Operating on Files): Rewrite according to the fact - that `dired-do-chmod' doesn't use the `chmod' program anymore. - -2011-07-30 Michael Albinus - - * mini.texi (Minibuffer File): Insert a reference to Tramp for - remote file name completion. (Bug#9197) - -2011-07-28 Eli Zaretskii - - * mule.texi (Bidirectional Editing): Document the fact that - bidi-display-reordering is t by default. - -2011-07-15 Lars Magne Ingebrigtsen - - * help.texi (Misc Help): Mention `describe-prefix-bindings' - explicitly (bug#8904). - -2011-07-14 Lars Magne Ingebrigtsen - - * trouble.texi (Checklist): Use an `M-x' example instead of an - Emacs Lisp form to switch on the dribble file (bug#8056). - -2011-07-13 Lars Magne Ingebrigtsen - - * custom.texi (Hooks): Mention buffer-local hooks (bug#6218). - -2011-07-13 Glenn Morris - - * dired.texi (Dired Enter): Mention --dired. (Bug#9039) - -2011-07-13 Lars Magne Ingebrigtsen - - * mark.texi (Mark Ring): Clarify how many locations are saved - (bug#5770). - (Global Mark Ring): Ditto. - -2011-07-12 Lars Magne Ingebrigtsen - - * text.texi (Table Recognition): Use "at point" instead of "under - point" (bug#4345). - - * display.texi (Cursor Display): Mention `cursor-type'. - - * screen.texi (Point): Clarify that it's only if you use a block - cursor that it appears to be on a character (bug#4345). - -2011-07-12 Chong Yidong - - * misc.texi (Amusements): Move dissociated press here, from its - own section. - - * emacs.texi (Top): Update node listing. - -2011-07-12 Lars Magne Ingebrigtsen - - * emacs.texi (Top): Change "inferiors" to "subnodes" for greater - clarity (bug#3523). - -2011-07-12 Chong Yidong - - * cmdargs.texi (Initial Options): Document --no-site-lisp. - (Misc X): Document --parent-id. - - * frames.texi (Frame Commands): Note that focus-follows-mouse now - defaults to nil. - - * misc.texi (emacsclient Options): Document --parent-id. - - * msdog.texi (Windows HOME): Document _emacs as obsolete. - -2011-07-11 Lars Magne Ingebrigtsen - - * emacs.texi: Use "..." instead of ``...'' in the menus - (bug#3503). - -2011-07-11 Chong Yidong - - * killing.texi (Primary Selection): Document `only' setting for - select-active-regions. - - * mark.texi (Setting Mark): Reference Shift Selection node. - - * frames.texi (Mouse Commands): Document mouse-yank-primary. - -2011-07-11 Lars Magne Ingebrigtsen - - * mark.texi (Setting Mark): Clarify what's meant by "Shifted - motion keys" (bug#3503). - - * emacs.texi: Change all the register node names from "RegPos" - (etc.) to "Positional Registers" (etc.) (bug#3314). - -2011-07-11 Chong Yidong - - * killing.texi (Killing, Deletion and Killing, Killing by Lines) - (Other Kill Commands, Kill Options): Copyedits. - (Deletion and Killing, Kill Ring): Kill/yank now use clipboard. - (Yanking): Move yank-excluded properties discussion here. - (Cut and Paste): Move from frames.texi. Update subnodes to - describe x-select-enable-clipboard case. - - * frames.texi: Move Cut and Paste node and subnodes into - killing.texi, except Mouse Commands and Word and Line Mouse. - -2011-07-10 Andy Moreton (tiny change) - - * makefile.w32-in (EMACSSOURCES): Replace major.texi with modes.texi. - -2011-07-10 Lars Magne Ingebrigtsen - - * screen.texi (Mode Line): Clarify that coding systems are - characters, not letters (bug#1749). - - * cmdargs.texi (Environment): Mention removing variables - (bug#1615). Text suggested by Kevin Rodgers. - -2011-07-10 Chong Yidong - - * misc.texi (Amusements): Don't mention Yow; it's crippled. - - * modes.texi: Rename from major.texi. - (Modes): New node. Make Major Modes and Minor Modes subsections - of this. All callers changed. - - * custom.texi (Minor Modes): Move to modes.texi. - -2011-07-10 Chong Yidong - - * custom.texi (Syntax): Node deleted. - - * help.texi (Help Summary): - * major.texi (Major Modes): - * programs.texi (Parentheses): - * search.texi (Regexp Backslash, Regexp Backslash) - (Regexp Backslash): - * text.texi (Words): Callers changed. - - * text.texi (Refill, Longlines): Delete nodes. - - * ack.texi (Acknowledgments): Longlines removed from manual. - - * emacs.texi (Top): Update node listing. - -2011-07-09 Glenn Morris - - * fortran-xtra.texi (Fortran): Update handled extensions. - -2011-07-03 Lars Magne Ingebrigtsen - - * display.texi (Scrolling): `C-v' (etc) are now bound to - `scroll-*-command' (bug#8349). - -2011-07-02 Lars Magne Ingebrigtsen - - * dired.texi (Subdirectories in Dired): Clarify that `C-u k' - doesn't actually delete any files (bug#7125). - - * picture-xtra.texi (Rectangles in Picture): Clarify the prefix - argument for `C-c C-k' (bug#7391). - - * frames.texi (Fonts): Mention "C-u C-x =" to find out what font - you're currently using (bug#8489). - -2011-07-01 Eli Zaretskii - - * mule.texi (Coding Systems): Move index entries from the previous - change into their proper places. - -2011-07-01 Lars Magne Ingebrigtsen - - * help.texi (Help Files): Document view-external-packages (bug#8902). - - * mule.texi (Coding Systems): Put a few more of the coding systems - into the index (bug#8900). - -2011-06-26 Glenn Morris - - * fortran-xtra.texi (Fortran): F90 mode is also for F2008. - -2011-06-25 Andreas Rottmann - - * misc.texi (emacsclient Options): Mention --frame-parameters. - -2011-06-09 Glenn Morris - - * custom.texi (Specifying File Variables): - Recommend explicit arguments for minor modes. - -2011-06-02 Paul Eggert - - Document wide integers better. - * buffers.texi (Buffers): - * files.texi (Visiting): Document maxima for 64-bit machines, - and mention virtual memory limits. - -2011-05-28 Chong Yidong - - * custom.texi (Hooks): Reorganize. Mention Prog mode. - - * fixit.texi (Spelling): Mention using prog-mode-hook for flypsell - prog mode (Bug#8240). - -2011-05-27 Glenn Morris - - * custom.texi (Specifying File Variables): - Major modes no longer need come first. - -2011-05-22 Chong Yidong - - * mule.texi (Specify Coding, Text Coding, Communication Coding): - (File Name Coding, Terminal Coding): Add command names (Bug#8312). - -2011-05-18 Glenn Morris - - * ack.texi (Acknowledgments): Remove fakemail.c. - -2011-05-17 Chong Yidong - - Fixes for fitting text into 7x9 printed manual. - * building.texi (Flymake, Breakpoints Buffer): - * calendar.texi (Appointments): - * cmdargs.texi (General Variables, Display X): - * custom.texi (Saving Customizations, Face Customization) - (Directory Variables, Minibuffer Maps, Init Rebinding): - * display.texi (Font Lock, Font Lock, Useless Whitespace): - * fixit.texi (Spelling): - * frames.texi (Creating Frames, Fonts): - * help.texi (Help Files): - * mini.texi (Minibuffer File): - * misc.texi (emacsclient Options, Emulation): - * msdog.texi (Windows Startup, Windows HOME, Windows Fonts): - * mule.texi (International Chars, Language Environments) - (Select Input Method, Modifying Fontsets, Charsets): - * programs.texi (Custom C Indent): - * rmail.texi (Rmail Labels): - * text.texi (Table Conversion): - * trouble.texi (Known Problems, Known Problems): - * windows.texi (Change Window): - * xresources.texi (GTK resources): Reflow text and re-indent code - examples to avoid TeX overflows and underflows on 7x9 paper. - - * emacs.texi: Fix the (commented out) smallbook command. - - * macos.texi (Mac / GNUstep Events): - * xresources.texi (Lucid Resources): Remove extraneous examples. - -2011-05-10 Glenn Morris - - * custom.texi (Specifying File Variables): - Deprecate using mode: for minor modes. - -2011-05-07 Glenn Morris - - * cal-xtra.texi (Sexp Diary Entries): Mention diary-hebrew-birthday. - -2011-05-06 Glenn Morris - - * calendar.texi (Appointments): Mention appt-warning-time-regexp. - - * cal-xtra.texi (Fancy Diary Display): Mention diary comments. - -2011-05-02 Lars Magne Ingebrigtsen - - * misc.texi (Emacs Server): Document `server-eval-at'. - -2011-04-24 Chong Yidong - - * maintaining.texi (List Tags): Document next-file. Suggested by - Uday S Reddy. - -2011-04-23 Juanma Barranquero - - * mini.texi (Minibuffer Edit): - * screen.texi (Mode Line): Fix typo. - -2011-04-20 Christoph Scholtes - - * maintaining.texi (Old Revisions): Mention new function vc-ediff. - -2011-03-26 Chong Yidong - - * display.texi (Auto Scrolling): Fix scroll-up/scroll-down confusion. - -2011-03-30 Eli Zaretskii - - * display.texi (Auto Scrolling): Document the limit of 100 lines - for never-recentering scrolling with `scroll-conservatively'. - (Bug#6671) - -2011-03-12 Eli Zaretskii - - * msdog.texi (Windows HOME): Fix the wording to clarify how Emacs sets - HOME on Windows and where it looks for init files. (Bug#8221) - -2011-03-10 Eli Zaretskii - - * search.texi (Regexp Example): - * mule.texi (International Chars): - * building.texi (External Lisp): Don't use characters outside - ISO-8859-1. - -2011-03-09 Eli Zaretskii - - * ack.texi (Acknowledgments): Convert to ISO-8859-1 encoding. - Use Texinfo @-commands for non Latin-1 characters. - - * makefile.w32-in (MAKEINFO_OPTS): Add --enable-encoding. - - * custom.texi (Init File): Add index entries for ".emacs". - (Bug#8210) - -2011-03-08 Jan Djärv - - * xresources.texi (GTK resources): ~/.emacs.d/gtkrc does not work - for Gtk+ 3. - -2011-03-08 Glenn Morris - - * Makefile.in (MAKEINFO_OPTS): Add --enable-encoding. - * emacs.texi (Acknowledgments): - * ack.texi (Acknowledgments): Names to UTF-8. - * emacs.texi: Set documentencoding. - - * display.texi (Optional Mode Line): Don't mention exactly where - display-time appears. (Bug#8193) - -2011-03-07 Chong Yidong - - * Version 23.3 released. - -2011-03-06 Chong Yidong - - * search.texi (Isearch Yank): C-y now bound to isearch-yank-kill. - -2011-03-03 Drake Wilson (tiny change) - - * misc.texi (emacsclient Options): Add q/quiet. - -2011-03-02 Glenn Morris - - * mule.texi (Communication Coding) : - Remove duplicate (essentially) paragraph. (Bug#8148) - -2011-03-01 Christoph Scholtes - - * maintaining.texi (Format of ChangeLog): Add reference to - add-log-full-name. - (Change Log Commands): Add documentation for combining multiple - symbols in one change. - -2011-03-01 Glenn Morris - - * custom.texi (Directory Variables): - Give an example of excluding subdirectories. - -2011-02-28 Eli Zaretskii - - * search.texi (Regexp Search): Move index entries about regexps to the - "Regexps" node. Add index entries for regexp search. (Bug#8096) - -2011-02-19 Glenn Morris - - * dired.texi (Dired): Dired-X version number was dropped. - -2011-02-14 Jan Djärv - - * xresources.texi (X Resources): Remove *faceName and replace it with - *font for Lucid. - -2011-02-05 Chong Yidong - - * rmail.texi (Rmail Display): Document Rmail MIME support more - accurately. - - * maintaining.texi (VC Change Log): Document vc-log-incoming and - vc-log-outgoing. - (Merging): Document vc-find-conflicted-file. - -2011-02-05 Glenn Morris - - * custom.texi (Variables): Fix typo. - -2011-01-31 Chong Yidong - - * search.texi (Regexps): Copyedits. Mention character classes - (Bug#7809). - - * files.texi (File Aliases): Restore explanatory text from Eli - Zaretskii, accidentally removed in 2011-01-08 commit. - -2011-01-29 Eli Zaretskii - - * makefile.w32-in (MAKEINFO): Remove options, leave only program name. - (MAKEINFO_OPTS): New variable. - (ENVADD, $(infodir)/emacs): Use $(MAKEINFO_OPTS). - (emacs.html): New target. - (clean): Remove emacs.html. - -2011-01-23 Werner Lemberg - - * Makefile.in (MAKEINFO): Now controlled by `configure'. - (MAKEINFO_OPTS): New variable. Use it where appropriate. - (ENVADD): Updated. - -2011-01-18 Glenn Morris - - * ack.texi, emacs.texi (Acknowledgments): Update for ERT addition. - - * ack.texi (Acknowledgments): Remove mention of replaced prolog.el. - -2011-01-15 Chong Yidong - - * building.texi (Compilation): Improve instructions for running two - compilations (Bug#7573). - - * files.texi (Backup Names): Document the new location of the - last-resort backup file. - - * files.texi (File Aliases): Move directory-abbrev-alist doc from Lisp - manual. Explain why directory-abbrev-alist elements should be anchored - (Bug#7777). - -2011-01-15 Eli Zaretskii - - * msdog.texi (Windows Startup): Correct inaccurate description of - differences between emacsclient.exe and emacsclientw.exe. - -2011-01-02 Chong Yidong - - * rmail.texi (Rmail Display): Edit for grammar and conciseness. - -2011-01-02 Kenichi Handa - - * rmail.texi (Rmail Display): Describe new features of Rmail in Info. - -2011-01-02 Eli Zaretskii - - * frames.texi (Cut and Paste): Modify the section's name and text: - don't mix "cut/paste" with "kill/yank". - (Cut/Paste Other App): Describe the per-session emulation of PRIMARY. - (Bug#7702) - - * trouble.texi (Checklist): Mention debug-on-quit. (Bug#7667) - -2011-01-02 Glenn Morris - - * maintaining.texi: Move inclusion of emerge after EDE, so that it - matches its position in the menu. (Bug#7674) - -2011-01-02 Glenn Morris - - * trouble.texi (Checklist): Mention not replying via news either. - -2010-12-30 Tassilo Horn - - * misc.texi (Document View): Update DocView section with newly - supported document formats. - -2010-12-21 Chong Yidong - - * killing.texi: Resection the Info version to conform to the - printed manual, to avoid making sections on Accumulating Text, CUA - and Rectangles into full chapters. - -2010-12-13 Eli Zaretskii - - * custom.texi (Init Syntax): Add index entries for "character syntax". - (Bug#7576) - -2010-12-13 Karel Klíč - - * text.texi (HTML Mode): Small fixes. (Bug#7607) - -2010-12-13 Glenn Morris - - * trouble.texi (Checklist): Fix typo in newsgroup name. - -2010-12-13 Chong Yidong - - * search.texi (Word Search): Note that the lazy highlight always - matches to whole words (Bug#7470). - -2010-12-13 Eli Zaretskii - - * display.texi (Optional Mode Line): Make the description of - load-average more accurate. - - * msdog.texi (Windows HOME): Mention that HOME can also be set in the - registry, with a cross-reference. - (Windows Startup): New node. Move the stuff about the current - directory from "Windows HOME". - -2010-11-27 Bob Rogers - - * maintaining.texi (VC With A Locking VCS, VC Directory Commands): - * vc1-xtra.texi (Customizing VC, General VC Options): Small fixes. - -2010-11-27 Chong Yidong - - * maintaining.texi (Version Control Systems): Fix repeated sentence. - Suggested by Å těpán Němec. - -2010-11-27 Chong Yidong - - * maintaining.texi (Version Control): Say "commit", not "check in". - (Version Control Systems): Simplify descriptions. - (VCS Merging, VCS Changesets, VCS Repositories): New nodes, split from - VCS Concepts. - (VC Mode Line): Update example. - (Old Revisions): Document revert-buffer for vc-diff. - (Log Buffer): Promote to a subsection. Document header lines. - - * macos.texi (Mac / GNUstep Basics): - Document ns-right-alternate-modifier. - - * emacs.texi (Top): Update node listing. - -2010-11-13 Eli Zaretskii - - * rmail.texi (Rmail Coding): Characters with no fonts are not - necessarily displayed as empty boxes. - - * mule.texi (Language Environments, Fontsets): Characters with no - fonts are not necessarily displayed as empty boxes. - - * display.texi (Text Display): Document display of glyphless - characters. - -2010-11-13 Glenn Morris - - * basic.texi (Position Info): Add M-x count-words-region. - -2010-11-11 Glenn Morris - - * msdog.texi (ls in Lisp): Update for ls-lisp changes. - -2010-11-09 Eli Zaretskii - - * msdog.texi (Windows HOME): Add information regarding startup - directory when invoking Emacs from a desktop shortcut. (bug#7300) - -2010-10-11 Glenn Morris - - * Makefile.in (MAKEINFO): Add explicit -I$srcdir. - - * Makefile.in (.texi.dvi): Remove unnecessary suffix rule. - (DVIPS): New variable. - (.PHONY): Add html, ps. - (html, emacs.html, ps, emacs.ps, emacs-xtra.ps): New targets. - (clean): Delete html, ps files. - -2010-10-09 Eli Zaretskii - - * makefile.w32-in (EMACSSOURCES): Add emacsver.texi. - -2010-10-09 Glenn Morris - - * Makefile.in (VPATH): Remove. - (infodir): Make it absolute. - (mkinfodir, $(infodir)/emacs, infoclean): No need to cd $srcdir. - - * Makefile.in (dist): Anchor regexps. - - * Makefile.in (EMACSSOURCES): Put emacs.texi first. - ($(infodir)/emacs, emacs.dvi, emacs.pdf, emacs-xtra.dvi) - (emacs-xtra.pdf): Use $<. - - * Makefile.in (infoclean): Remove harmless, long-standing error. - - * Makefile.in ($(infodir)): Delete rule. - (mkinfodir): New. - ($(infodir)/emacs): Use $mkinfodir instead of infodir. - - * Makefile.in (distclean): Do not delete emacsver.texi. - (dist): Remove reference to emacsver.texi.in. - * emacsver.texi: New file, replacing emacsver.texi.in. - -2010-10-09 Glenn Morris - - * emacsver.texi.in: New file. - * emacs.texi: Set EMACSVER by including emacsver.texi. - * Makefile.in (distclean): Delete emacsver.texi. - (dist): Copy emacsver.texi. - (EMACSSOURCES): Add emacsver.texi. - - * ack.texi (Acknowledgments): No more b2m.c. - - * Makefile.in (.PHONY): Declare info, dvi, pdf, dist. - (emacs): Remove rule. - (dist): No need to deal with the emacs rule any more. - -2010-10-07 Glenn Morris - - * Makefile.in (version): New, set by configure. - (clean): Delete dist tar file. - (dist): Use version in tar name. - -2010-10-06 Glenn Morris - - * Makefile.in (EMACS_XTRA): Add the main source file. - (emacs-xtra.dvi, emacs-xtra.pdf): Remove explicit emacs-xtra.texi. - (mostlyclean): No core files, reorder other files. - (clean): Delete specific dvi and pdf files. - (infoclean, dist): New rules. - (maintainer-clean): Use infoclean. - ($(infodir)): Add parallel build workaround. - -2010-10-04 Glenn Morris - - * Makefile.in (SHELL): Set it. - (INFO_TARGETS, DVI_TARGETS): Remove variables. - (info, dvi): Replace above variables with their expansions. - (info): Move mkdir from here... - ($(infodir)/emacs): ... to here (for parallel builds). - (pdf): New target. - ($(infodir)/emacs): Pass -o option to makeinfo. - (.PHONY): Declare clean rules. - (maintainer-clean): Delete dvi and pdf files. - Guard against cd failures. Use a more restrictive delete. - -2010-10-02 Glenn Morris - - * misc.texi (Shell Mode): Remove reference to old function name. - -2010-09-30 Eli Zaretskii - - * maintaining.texi (VC Mode Line): Mention all the possible VC status - indicator characters. - -2010-09-29 Glenn Morris - - * Makefile.in (top_srcdir): Remove unused variable. - -2010-09-14 Glenn Morris - - * cal-xtra.texi (Fancy Diary Display): Emphasize that sort should be - the last hook item. - - * calendar.texi (Appointments): Also updated when a diary include file - is saved. - -2010-09-14 Glenn Morris - - * trouble.texi (Bugs): Update the section intro. - (Known Problems): New section. - (Checklist): Misc updates. Prefer M-x report-emacs-bug. - (Sending Patches): Bug fixes are best as responses to existing bugs. - * emacs.texi (Known Problems): Add menu entry for new section. - -2010-09-09 Glenn Morris - - * xresources.texi: Untabify. - -2010-09-06 Chong Yidong - - * dired.texi (Dired Enter): Minor doc fix (Bug#6982). - -2010-09-06 Glenn Morris - - * misc.texi (Saving Emacs Sessions): Mention desktop-path. (Bug#6948) - -2010-09-02 Jan Djärv - - * frames.texi (Cut/Paste Other App): Remove vut-buffer text. - -2010-08-21 Glenn Morris - - * misc.texi (Amusements): Mention bubbles and animate. - -2010-07-31 Eli Zaretskii - - * files.texi (Visiting): Add more index entries for - large-file-warning-threshold. - -2010-07-29 Jan Djärv - - * frames.texi (Tool Bars): Add doc for tool-bar-position. - -2010-06-23 Glenn Morris - - * abbrevs.texi, basic.texi, buffers.texi, building.texi, calendar.texi: - * custom.texi, dired.texi, display.texi, emacs.texi, emerge-xtra.texi: - * files.texi, fortran-xtra.texi, frames.texi, help.texi, killing.texi: - * maintaining.texi, mark.texi, mini.texi, misc.texi, msdog.texi: - * mule.texi, programs.texi, rmail.texi, screen.texi, search.texi: - * sending.texi, text.texi, trouble.texi, vc1-xtra.texi, xresources.texi: - Untabify Texinfo files. - -2010-06-10 Glenn Morris - - * basic.texi (Inserting Text): Minor clarification. (Bug#6374) - - * basic.texi (Inserting Text): Fix typo. - -2010-06-10 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Update for notifications.el. - -2010-05-31 Daiki Ueno - - * dired.texi (Operating on Files): Mention encryption commands - (Bug#6315). - -2010-05-29 Eli Zaretskii - - * basic.texi (Moving Point): Update due to renaming of commands bound - to arrows. Document bidi-aware behavior of C- and C-. - -2010-05-18 Eli Zaretskii - - * display.texi (Fringes): Document reversal of fringe arrows for R2L - paragraphs. - (Line Truncation): Fix wording for bidi display. - - * basic.texi (Moving Point): Document bidi-aware behavior of the arrow - keys. - -2010-05-08 Chong Yidong - - * building.texi (GDB Graphical Interface): Remove misleading comparison - to an IDE (Bug#6128). - -2010-05-08 Å těpán Němec (tiny change) - - * programs.texi (Man Page): - * misc.texi (Invoking emacsclient): - * mini.texi (Repetition): - * mark.texi (Setting Mark): Fix typos. - -2010-05-08 Chong Yidong - - * misc.texi (Printing): Document htmlfontify-buffer. - -2010-05-08 Glenn Morris - - * calendar.texi (Displaying the Diary, Format of Diary File): - Fix external cross-references for TeX format output. - -2010-05-07 Chong Yidong - - * Version 23.2 released. - -2010-05-02 Jan Djärv - - * cmdargs.texi (Initial Options): Mention --chdir. - -2010-04-21 Jan Djärv - - * frames.texi (Tool Bars): Add tool-bar-style. - -2010-04-21 Glenn Morris - - * ack.texi, emacs.texi (Acknowledgments): Add SELinux support. - -2010-04-18 Chong Yidong - - * programs.texi (Semantic): New node. - - * maintaining.texi (EDE): New node. - - * emacs.texi: Update node listing. - - * misc.texi (Gnus): Use the `C-h i' keybinding for info. - -2010-04-18 Glenn Morris - - * emacs.texi (Acknowledgments): Remove duplicate. - - * maintaining.texi (VC Directory Commands): Mention stashes and shelves. - -2010-04-18 Glenn Morris - - * dired.texi (Misc Dired Features): Mention VC diff and log. - * maintaining.texi (Old Revisions, VC Change Log): - Mention that diff and log work in Dired buffers. - - * help.texi (Help Summary): Mention M-x info-finder. - - * ack.texi (Acknowledgments): Add mpc.el. - - * custom.texi (Specifying File Variables, Directory Variables): - Document new commands for manipulating local variable lists. - -2010-04-18 Glenn Morris - - * trouble.texi (Contributing): Add cindex entry. - Mention etc/CONTRIBUTE. - -2010-04-18 Chong Yidong - - * mark.texi (Persistent Mark): Copyedits. Replace undo example with - query-replace (Bug#5774). - -2010-04-16 Glenn Morris - - * ack.texi, emacs.texi (Acknowledgments): Update for Org changes. - -2010-04-11 Jan Djärv - - * xresources.texi (Lucid Resources): Mention faceName for dialogs. - -2010-04-08 Jan Djärv - - * xresources.texi (Lucid Resources): Mention faceName to set Xft fonts. - -2010-03-30 Eli Zaretskii - - * mule.texi (Input Methods): Mention "C-x 8 RET" and add a - cross-reference to "Inserting Text". - - * basic.texi (Inserting Text): Add an index entry for "C-x 8 RET". - Mention completion provided by `ucs-insert'. - -2010-03-30 Chong Yidong - - * sending.texi (Sending Mail): Note variables that may need - customizing. - (Mail Sending): Expand discussion of send-mail-function. - -2010-03-30 Chong Yidong - - Document Message mode as the default mail mode. - - * sending.texi (Sending Mail): Copyedits. - (Mail Format, Mail Headers): Document mail-from-style changes. - (Mail Commands): Rename from Mail mode. Document Message mode. - (Mail Misc): Rename from Mail mode Misc. - (Mail Sending, Header Editing, Mail Misc): Switch to Message mode - command names and update keybindings. - (Header Editing): Document message-tab. De-document - mail-self-blind, mail-default-reply-to, and mail-archive-file-name in - favor of mail-default-headers. Ad index entries for user-full-name and - user-mail-address. - (Citing Mail): Update changes in Message mode behavior. - Document mail-yank-prefix. - (Mail Signature): New node, moved from Mail Misc. - (Mail Aliases): Mail abbrevs are the default with Message mode. - (Mail Methods): Note that Message mode is now the default. - - * rmail.texi (Rmail Reply): - * text.texi (Text Mode): - * major.texi (Major Modes): - * mule.texi (Output Coding): Refer to Message mode. - - * custom.texi (Init Examples): Add xref to Mail Header. - - * emacs.texi (Top): Fix xrefs. - -2010-03-30 Chong Yidong - - * maintaining.texi (VC With A Merging VCS): C-x v v now creates a - repository if there is none. - (VC Change Log): Rename from VC Status. Document vc-log-show-limit and - vc-print-root-log. - (Old Revisions): Copyedits. Document vc-root-diff. - - * programs.texi (Program Modes): Mention Javascript mode. - - * text.texi (HTML Mode): Note that nXML is now the default XML mode. - * emacs.texi: Update node description. - - * misc.texi (Navigation): Document doc-view-continuous. - (Shell Ring): Document new M-r binding. M-s is no longer bound. - -2010-03-30 Juri Linkov - - * search.texi (Other Repeating Search): Remove line that `occur' - can not handle multiline matches. - -2010-03-30 Eli Zaretskii - - * mule.texi (International): Mention support of bidirectional editing. - (Bidirectional Editing): New section. - -2010-03-28 Nick Roberts - - * emacs.texi (Top): Update node names to those in building.texi. - -2010-03-27 Nick Roberts - - doc/emacs/building.texi: Describe restored GDB/MI functionality - removed by r99212. - doc/emacs/emacs.texi: Update node names for building.texi. - -2010-03-24 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Fix ispell attribution. (Bug#5759) - -2010-03-20 Jan Djärv - - * xresources.texi (Table of Resources): Clarify toolBar number - for Gtk+. - - * frames.texi (Menu Bars): menuBarLines => menuBar (bug#5736). - -2010-03-21 Chong Yidong - - * dired.texi (Dired Updating): Document dired-auto-revert-buffer. - - * search.texi (Other Repeating Search): Document multi-isearch-buffers - and multi-isearch-buffers-regexp. - - * indent.texi (Indentation): Clarify description of - indent-for-tab-command. Document tab-always-indent. - -2010-03-20 Chong Yidong - - * cmdargs.texi (Font X): Move most content to Fonts. - - * frames.texi (Fonts): New node. Document font-use-system-font. - - * emacs.texi (Top): - * xresources.texi (Table of Resources): - * mule.texi (Defining Fontsets, Charsets): Update xrefs. - -2010-03-10 Chong Yidong - - * Branch for 23.2. - -2010-03-06 Chong Yidong - - * custom.texi (Init Examples): Add xref to Locals. - - * major.texi (Choosing Modes): Mention usage of setq-default for - setting the default value of major-mode (Bug#5688). - -2010-03-02 Chong Yidong - - * frames.texi (Mouse Avoidance): Mention make-pointer-invisible. - - * display.texi (Display Custom): Document make-pointer-invisible and - underline-minimum-offset. Remove inverse-video. - -2010-02-21 Chong Yidong - - * frames.texi (Frame Commands): Note that the last ordinary frame can - be deleted in daemon mode (Bug#5616). - -2010-02-18 Glenn Morris - - * trouble.texi (Contributing): Repository is no longer CVS. - -2010-02-08 Glenn Morris - - * buffers.texi (Uniquify): Must explicitly load library. (Bug#5529) - -2010-02-01 Stefan Monnier - - * display.texi (Useless Whitespace, Text Display): - * custom.texi (Init Examples): Avoid obsolete special default variables - like default-major-mode. - -2010-01-24 Mark A. Hershberger - - * programs.texi (Other C Commands): Replace reference to obsolete - c-subword-mode. - -2010-01-21 Glenn Morris - - * trouble.texi (Bugs): Fix PROBLEMS keybinding. - -2010-01-12 Glenn Morris - - * trouble.texi (Checklist): Use bug-gnu-emacs rather than - emacs-pretest-bug for bug reports for development versions. - -2010-01-11 Glenn Morris - - * display.texi (Highlight Interactively): `t' does not mean highlight - all patterns. (Bug#5335) - -2009-12-29 Chong Yidong - - * misc.texi (Shell): Document async-shell-command. - - * building.texi (Grep Searching): Document zrgrep. - - * mini.texi (Completion Options): Mention `initials' completion style. - -2009-12-29 Nick Roberts - - * building.texi: Import GDB Graphical Interface description from - EMACS_23_1_RC. - -2009-12-24 Chong Yidong - - * emacs.texi (Top): Update node listing. - - * abbrevs.texi (Saving Abbrevs): Abbrev file should be in .emacs.d. - - * basic.texi (Moving Point): M-r is now move-to-window-line-top-bottom. - - * cmdargs.texi (Initial Options): - * xresources.texi (Resources): Document inhibit-x-resources. - - * custom.texi (Specifying File Variables): Note that minor modes are - enabled unconditionally. - - * display.texi (Scrolling): Briefly document the old recenter command, - and document recenter-positions. - - * files.texi (Visiting): - * buffers.texi (Buffers): Max buffer size is now 512 MB. - - * frames.texi (Cut/Paste Other App): - Document save-interprogram-paste-before-kill. - - * killing.texi (Kill Options): New node. - -2009-12-05 Chong Yidong - - * misc.texi (Shell Options): ansi-color is now default. - -2009-12-05 Glenn Morris - - * emacs.texi (Top): Update menu for cal-xtra node changes. - * calendar.texi (Displaying the Diary): Holidays may be in the buffer - or mode line. Don't mention invisible text or the details of - diary-print-entries here, only in cal-xtra. - (Format of Diary File): Mention that the "date on first line" format - only really affects the simple display. - * cal-xtra.texi (Advanced Calendar/Diary Usage): Update menu. - (Diary Customizing): Holidays may be in the buffer or mode line. - Move diary-print-entries to the "Diary Display" section. - (Diary Display): New section, split out from "Fancy Diary Display". - Explain the limitations of simple display, and how to print it. - - * calendar.texi (Displaying the Diary): Mention keys apply to calendar. - - * cal-xtra.texi (Diary Display): Mention View mode. - -2009-11-29 Juri Linkov - - * display.texi (Highlight Interactively): Actually a list of - default faces is pre-loaded into a list of default values - instead of the history. - -2009-11-20 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Add htmlfontify. - -2009-11-14 Glenn Morris - - * cal-xtra.texi (Holiday Customizing): Replace obsolete alias. - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Update for recent Org changes. - -2009-10-31 Chong Yidong - - * mule.texi (Charsets): Numerous copyedits. Don't discuss the - `charset' property, which is irrelevant to the user manual (Bug#3526). - -2009-10-14 Juanma Barranquero - - * trouble.texi (DEL Does Not Delete): Fix typo. - -2009-10-05 Michael Albinus - - * files.texi (Misc File Ops): Mention copy-directory. - -2009-10-04 Eli Zaretskii - - * mule.texi (Unibyte Mode): Emphasize that - unibyte-display-via-language-environment affects only the display. - - * display.texi (Horizontal Scrolling): Document cursor behavior under - horizontal scrolling when point moves off the screen (Bug#4564). - Improve wording. - -2009-10-01 Michael Albinus - - * files.texi (Directories): delete-directory prompts for recursive - deletion. - -2009-09-30 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): CEDET updates. Fix Hungarian accent. - -2009-09-25 Tassilo Horn - - * dired.texi (Dired Navigation): Use @code instead of @var for - dired-isearch-filenames, so that it's not capitalized. - -2009-09-19 Chong Yidong - - * frames.texi (Frame Commands): C-z is now bound to suspend-frame. - - * entering.texi (Exiting): C-z is now bound to suspend-frame. - - * custom.texi (Init Examples): Replace Rumseld with Cheny (Bug#3519). - (Key Bindings): Reference Init Rebinding in introductory text. - Shift some of the introduction to Keymaps node. - (Keymaps): Simplify. - (Local Keymaps): Simplify. Move binding example to Init Rebinding. - (Minibuffer Maps): Remove mention of Mocklisp. - (Init Rebinding): Move mode-local rebinding example here from Local - Keymaps. - (Modifier Keys): Clarify. - (Rebinding): Add cindex for "binding keys". - -2009-09-13 Chong Yidong - - * misc.texi (Invoking emacsclient): Minor clarifications (Bug#4419). - -2009-08-31 Nick Roberts - - * building.texi (Threads Buffer, Multithreaded Debugging): - Reorganize these two sections. - -2009-08-29 Eli Zaretskii - - * cmdargs.texi (Initial Options): Fix last change. - -2009-08-29 Stefan Monnier - - * mule.texi (Enabling Multibyte): - * cmdargs.texi (General Variables): Remove EMACS_UNIBYTE. - (Initial Options): Remove --(no-)multibyte, --(no-)unibyte. - -2009-08-20 Glenn Morris - - * cal-xtra.texi (Non-Gregorian Diary): Mention ``Adar I'' special case. - -2009-08-19 Glenn Morris - - * ack.texi (Acknowledgments): Remove cvtmail. Mention info-finder. - -2009-08-18 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Update for js.el replacing js2-mode.el. - - * ack.texi (Acknowledgments): Add ucs-normalize.el and files-x.el. - -2009-08-09 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Add gdb-mi entry. - -2009-08-08 Dmitry Dzhus - - * emacs.texi (Top): Add new menu items for GDB-UI. - - * building.texi (GDB Graphical Interface): Add Multithreaded debugging - section. Threads buffer is in separate section now. - -2009-08-08 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): - Update for js2-mode and org changes. - -2009-08-02 Michael Albinus - - * files.texi (Reverting): Auto-Revert Tail mode works also for remote - files. - -2009-07-28 Chong Yidong - - * building.texi (Lisp Libraries): Clarify meaning of autoloading. - -2009-07-23 Glenn Morris - - * programs.texi (Matching): Update blink-matching-paren-distance. - -2009-07-21 Chong Yidong - - * frames.texi (Cut/Paste Other App): For select-active-regions, - selection is now updated on moving point. - -2009-07-21 Richard Stallman - - * glossary.texi (GNU, Daemon): Update information. - -2009-07-19 Juri Linkov - - * custom.texi (Specifying File Variables, Safe File Variables): - "variables/value pairs" -> "variable/value pairs". - -2009-07-15 Glenn Morris - - * misc.texi (Gnus): Remove widow. - -2009-07-11 Glenn Morris - - * Makefile.in (TEXI2PDF): New. - (emacs.pdf, emacs-xtra.pdf): New targets. - - * arevert-xtra.texi (Autorevert): Add menu descriptions. - - * display.texi (Horizontal Scrolling): Re-word to remove widow. - - * emacs.texi (Top): Info can be read from other places than Emacs. - Don't print the copying notice twice in the printed version. - Update the menu and detailmenu. - (Preface): The meaning of "on-line" has changed. - Correct name for "Common Problems" chapter. - (Distrib): Update FSF shop URL. - (Intro): Showing two files at once is not so exciting. - - * macos.texi (Mac OS / GNUstep): Fix spelling and cross-reference. - (Mac / GNUstep Basics): Minor grammar changes. - (Mac / GNUstep Events): Fix typo. - (GNUstep Support): CANNOT_DUMP no longer applies. - - * misc.texi (Document View): Fix typos. - - * dired.texi (Dired): - * help.texi (Help): - * macos.texi (Mac OS / GNUstep): - * maintaining.texi (Version Control, Introduction to VC): - End menu descriptions with a period. - -2009-07-09 Eli Zaretskii - - * msdog.texi (Windows Files) : Don't be - so categorical in saying that the option is only useful on NTFS. - -2009-07-09 Glenn Morris - - * Makefile.in (texinfodir): New variable, with location of texinfo.tex. - (ENVADD): Add texinfodir to TEXINPUTS. - - * emacs.texi (Top): Fix cross-reference. - - * maintaining.texi (VC Directory Buffer): Fix cross-reference. - - * vc1-xtra.texi (Revision Tags): Fix typo. - -2009-07-03 Glenn Morris - - * emerge-xtra.texi (Emerge): Tweak Misc menu description. - (Submodes of Emerge): Skip Prefers is only relevant with an ancestor. - (Merge Commands): `.' does not seem to work in A or B buffer. - `l' can recreate the 3-window display. - - * glossary.texi (Glossary): Minor phrasing changes throughout. - Add more internal cross-references. - : You can't really autoload a variable. - : Move details here from `M-C-' item. - : Refer to `Truncation.' - : - : New entries. - : Mention recycle bins. - : Mention ``folders.'' - : Don't mention ``type-ahead.'' - : Refer to the manual node. - : Can be global or local. - : There are other checkers besides Ispell. - -2009-07-02 Glenn Morris - - * anti.texi (Antinews): Minor changes in phrasing. - - * cal-xtra.texi, fortran-xtra.texi: Re-order a few things to reduce - some underfull lines in dvi output. - - * emacs-xtra.texi (Introduction): Mention included in info Emacs manual. - - * sending.texi (Mail Sending): Add a tiny bit on mailclient. - - * vc-xtra.texi (Advanced VC Usage): End all menu items with a period. - -2009-07-01 Jan Djärv - - * xresources.texi (Table of Resources): Mention maximized for - fullscreen. - - * cmdargs.texi (Window Size X): -mm/--maximized is new. - -2009-07-01 Chong Yidong - - * anti.texi (Antinews): Correct the list of removed platforms. - -2009-06-28 Glenn Morris - - * arevert-xtra.texi: Minor language tweaks. - - * dired-xtra.texi: Minor revisions. - -2009-06-23 Miles Bader - - * display.texi (Scrolling): Document `recenter-redisplay'. - (Temporary Face Changes): Document `text-scale-set'. - -2009-06-21 Chong Yidong - - * Branch for 23.1. - -2009-06-17 Kenichi Handa - - * mule.texi (Charsets): Update the description for the new charset. - (list-character-sets): New findex. - (Language Environments): Add @anchor{Describe Language Environment}. - -2009-06-10 Chong Yidong - - * basic.texi (Moving Point): Fix tag. - - * picture-xtra.texi (Insert in Picture): Use and . - - * mini.texi (Completion Commands): Decapitalize and , and - use camel-case for PageUp and PageDown. - - * display.texi (Scrolling): Decapitalize and , and use - camel-case for PageUp and PageDown. - - * calendar.texi (Scroll Calendar): Decapitalize and . - - * search.texi (Isearch Scroll): Add isearch-allow-scroll to index. - (Isearch Scroll): Decapitalize and . - -2009-06-09 Agustín Martín - - * fixit.texi (Spelling): Set default dictionary. - Improve descriptions (Bug#2554) - -2009-06-08 David Reitter - - * macos.texi (Color panel, Font panel): Remove mention of Save Options, - since saving colors and faces set this way is not implemented. - (Environment variables): Remove mention of mac-fix-env, which is - scheduled to be removed. - -2009-06-04 Chong Yidong - - * custom.texi (Init Examples): Add example of changing load-path. - - * building.texi (Lisp Libraries): Add example of changing - load-path (Bug#3446). - -2009-05-28 Chong Yidong - - * mark.texi (Mark): Further clarifications. - (Setting Mark): Emphasize that C-SPC activates the mark. - -2009-05-28 Chong Yidong - - * mark.texi (Mark): Clarify introduction. Mention disabling Transient - Mark mode. - (Using Region, Persistent Mark): Use "active mark" instead of "active - region". - -2009-05-16 Ari Roponen (tiny change) - - * mule.texi (Select Input Method): Fix typo. - -2009-05-13 Chong Yidong - - * anti.texi (Antinews): Document completion changes. Some additional - copyedits and rearrangement of entries. - -2009-05-12 Chong Yidong - - * misc.texi (Interactive Shell, Saving Emacs Sessions) - (Shell History Copying, Terminal emulator): Copyedits. - - * xresources.texi (Resources): Simplify descriptions. - Shorten description of editres, which is not very useful these days. - (Table of Resources): Document fontBackend resource. - - * trouble.texi (Quitting): Add other undo bindings to table. - (DEL Does Not Delete): Note that the erasure key is usually labeled - "Backspace". Remove discussion of obscure Xmodmap issue. - -2009-05-07 Chong Yidong - - * files.texi (Visiting): Copyedits. - -2009-05-06 Chong Yidong - - * basic.texi (Inserting Text): Document ucs-insert. - - * mule.texi (International Chars): Define "multibyte". Note that - internal representation is unicode-based. Simplify definition of raw - bytes. Mention ucs-insert. - (Enabling Multibyte): Remove obsolete discussion. Copyedits. - (Language Environments): Add language environments new to Emacs 23. - (Multibyte Conversion): Node deleted. - (Coding Systems): Remove obsolete unify-8859-on-decoding-mode. - Don't mention obsolete emacs-mule coding system. - (Output Coding): Copyedits. - - * emacs.texi (Top): Update node listing. - -2009-05-05 Per Starbäck (tiny change) - - * trouble.texi (Lossage): Use new binding of view-emacs-problems. - -2009-04-28 Stefan Monnier - - * building.texi (Lisp Libraries): `load-library' does offer completion. - -2009-04-28 Chong Yidong - - * frames.texi (Text-Only Mouse): Mention gpm-mouse-mode instead of - t-mouse-mode. Suggested by Per Starbäck (Bug#3126). - -2009-04-25 Eli Zaretskii - - * maintaining.texi (Tags): Clarify text. (Bug#3101) - -2009-04-22 Chong Yidong - - * entering.texi (Entering Emacs): Document initial-buffer-choice. - - * building.texi (Lisp Interaction): Document initial-scratch-message. - -2009-04-18 Juanma Barranquero - - * msdog.texi (Windows Fonts): Fix typos. - - * files.texi (Save Commands): Fix pxref. - -2009-04-18 Chong Yidong - - * files.texi (Save Commands): Mention diff-buffer-with-file. - (Comparing Files): Document diff-buffer-with-file. Suggested by Magnus - Henoch (Bug#3036). - -2009-03-15 Glenn Morris - - * sending.texi (Mail Format): Replace "Sender" with "Message-Id", since - the former is not always used. - (Mail Headers): Use active voice. Add "Mail-reply-to". - Change case of "Id". Avoid repeated "appropriate". - (Mail Aliases): Fix previous change - use an example with a ".", so it - does actually get quoted when expanded. - (Mail Sending): Mailclient is the default on some systems. - (Citing Mail): Mention mail-indentation-spaces. - (Mail Mode Misc): Add an @dfn for "mail signature". - -2009-03-15 Chong Yidong - - * mini.texi (Completion Commands): Describe Emacs 23 completion rules. - (Completion Options): Document read-file-name-completion-ignore-case, - read-buffer-completion-ignore-case, and completion-styles. - Remove description of partial-completion-mode. - -2009-03-14 Glenn Morris - - * sending.texi (Mail Format): Fix typo. Add index entry for - mail-header-separator. - (Mail Headers): Put info about initialization and changing in one place - at the start. Update FCC section for mbox Rmail. Clarify From - section, mention mail-setup-with-from. Clarify Reply-to section. - Add Mail-followup-to and mail-mailing-lists. Clarify References - section. - (Mail Aliases): Update example, make less contentious. - Update for name change of mail-interactive-insert-alias. - (Mail Mode): Remove mention of `%' as a word separator. - (Mail Sending): Mention mail-send-hook. Mention Mailclient. - (Header Editing): Add reply-to, mail-reply-to, and mail-followup-to - commands. Clarify FCC handling. In mail-complete, add reference to - Mail Aliases section, and mention mail-complete-function. - (Citing Mail): Mention mail-yank-ignored-headers and mail-citation-hook. - (Mail Mode Misc): Clarify the mail-signature function. Add basic - signature netiquette. Explain how the mail hooks work when continuing - a composition. - (Mail Amusements): Internationalize the spook section a bit. - Remove the spook mail-setup-hook example, since it doesn't work well. - Mention fortune-file. - (Mail Methods): Mention read-mail-command. - -2009-03-14 David Reitter - - * macos.texi (Mac / GNUstep Basics): Remove references to Prefs panel - and NS resources following recent changes. - -2009-03-10 Jason Rumney - - * msdog.texi (Windows Misc): Remove doc for obsolete variable. Modify - w32-use-visible-system-caret doc to indicate that it should get set - automatically. - (Windows Fonts): Add doc for the uniscribe backend. - -2009-03-08 Dan Nicolaescu - - * maintaining.texi (VC Directory Commands): Fix doc for the x key in - vc-dir. (Bug#2598) - -2009-03-05 Reiner Steib - - * fixit.texi (Spelling): Add turn-on-flyspell. (Bug#2517) - -2009-03-05 Glenn Morris - - * rmail.texi (Rmail Basics): Add reference to sorting. - (Rmail Scrolling, Rmail Motion, Rmail Reply, Rmail Display): - Minor re-wordings. - (Rmail Motion): Mention rmail-next-same-subject. - (Rmail Deletion): Expunging is not the only way to change the numbers. - (Rmail Labels): Labels can also be used in sorting. - (Rmail Summary Edit): Mention rmail-summary-next-same-subject. - (Rmail Display): Mention rmail-mime. - -2009-03-04 Glenn Morris - - * rmail.texi (Rmail Sorting): Add the keybindings associated with each - sort command. Fix `rmail-sort-by-labels' name. Mention sorting from - summary. Mention sorts cannot be undone. - (Rmail Display): Give an example of how to use goto-address-mode. - (Rmail Editing): It's keybindings that are redefined, not commands. - Fix some typos. - (Movemail): Some minor rewording. - (Remote Mailboxes): Emacs movemail supports pop by default. - Fix some minor grammatical issues. The "two alternative ways" to - specify a POP mailbox are really just one. Remove all reference to the - variables rmail-pop-password and rmail-pop-password-required, obsolete - since Emacs 22.1. Clarify the four password steps. Emacs movemail - can support Kerberos. - -2009-03-03 Glenn Morris - - * rmail.texi (Rmail Deletion): Revert previous change, which was - describing the Rmail summary versions. - (Rmail Reply): Give more details of rmail-dont-reply-to-names. - Minor re-wording for rmail-resend. - (Rmail Make Summary): Summaries apply to buffers rather than files. - : Headers includes the subject. - : Give more - details, including prefix arguments. - Mention rmail-summary-by-senders on C-M-f. - Not counting lines might be faster. - (Rmail Summary Edit): More details on the delete commands. - Mention rmail-summary-undelete-many, rmail-summary-bury, and C-M-n/p. - Name the commands bound to the various keys. Mention prefix argument - for searching. - (Rmail Display): Mention rmail-displayed-headers. Fix typo. - Simplify rmail-highlighted-headers description. Update face name. - -2009-03-02 Juanma Barranquero - - * mark.texi (Marking Objects): Fix typo. - -2009-03-01 Chong Yidong - - * abbrevs.texi (Expanding Abbrevs): Mention abbrev-expand-functions - instead of obsolete pre-abbrev-expand-hook. Link to elisp manual. - -2009-03-01 Glenn Morris - - * rmail.texi (Rmail): Fix some typos. Use consistent case in menu. - (Rmail Motion): - M-s searches from the end of messages. - (Rmail Deletion): Minor clarification. Fix numeric argument - description. - (Rmail Inbox): Fix default inbox description. Mention `mbox' by name. - newmail and RMAILOSE files need not be in home-directory. - (Rmail Files): Mention I/O menus are unselectable if no files match. - Mention `MAIL' env-var. - -2009-02-24 Jason Rumney - - * mule.texi (Fontsets): Mention fontset-default, font specs and - fallback fontsets. - (Defining Fontsets): Mention ns and w32 variants of - standard-fontset-spec. Update description of startup fontset to match - Emacs 23 behavior. - (Modifying Fontsets): New section. (Bug#656) - (International): Link to Modifying Fontsets. - -2009-02-23 Adrian Robert - - * macos.texi (Mac / GNUstep Basics, Mac / GNUstep Customization): - Mention ns-extended-platform-support-mode. - -2009-02-22 Karl Berry - - * macos.texi (Mac / GNUstep Customization): One more duplicate "the". - -2009-02-19 Juanma Barranquero - - * basic.texi (Moving Point, Position Info): - * files.texi (Visiting): - * mini.texi (Completion Options): - * text.texi (HTML Mode): Remove duplicate words. - -2009-02-20 Glenn Morris - - * rmail.texi: Minor updates for mbox rather than Babyl. - -2009-02-17 Karl Berry - - * emacs.texi (Top): Add @insertcopying before master menu. (Bug#1988) - -2009-02-17 Richard M Stallman - - * anti.texi (Antinews): Mention Babyl format. - - * emacs.texi (Top): Delete `Out of Rmail' from subnode menu. - - * rmail.texi: Update for mbox format. - Various small fixes, as well as the following. - (Out of Rmail): Node deleted. - (Rmail): Update menu. - (Rmail Files): Comment out set-rmail-inbox-list. - Document rmail-inbox-list instead. - (Rmail Output): Substantial changes since C-o is now - rmail-output-as-seen and o is rmail-output. - (Rmail Attributes): Delete `stored', add `retried'. - (Rmail Display): Editing headers works in all cases. - -2009-02-17 Glenn Morris - - * basic.texi (Position Info): M-x count-lines-region is not always on - M-=. (Bug#2269) - -2009-02-09 Glenn Morris - - * calendar.texi (Holidays, Displaying the Diary): Update for new marker - defaults. - -2009-02-07 Eli Zaretskii - - * rmail.texi (Rmail Coding) : Remove stale - documentation of possible problems with redecoding. - -2009-02-03 Glenn Morris - - * rmail.texi (Out of Rmail): Mention b2m.pl. - -2009-01-31 Glenn Morris - - * rmail.texi (Out of Rmail): Correct b2m location. - -2009-01-27 Chong Yidong - - * fixit.texi (Undo): Update undo limit values. - -2009-01-27 Glenn Morris - - * emacs.texi (Top): Fix Antinews menu entry. - -2009-01-25 Karl Berry - - * text.texi (Foldout): Use @itemize @w{} to make an itemize - item with no marker, instead of the syntactically incorrect - @itemize @asis. - -2009-01-25 Juri Linkov - - * building.texi (Grep Searching): Fix index entry for lgrep. - -2009-01-24 Eli Zaretskii - - * msdog.texi (Windows Printing): Add an index entry for Ghostscript. - -2009-01-21 Adrian Robert - - * macos.texi (Preferences Panel): Update description of font setting to - reflect that prior frame selection is no longer needed. - -2009-01-20 Nick Roberts - - * building.texi (Debuggers): Revert some of 2008-10-31 change to - raise GUD subsections. - -2009-01-15 Glenn Morris - - * ack.texi (Acknowledgments): Another update based mainly on AUTHORS. - -2009-01-10 Glenn Morris - - * ack.texi (Acknowledgments): Some more updates based on AUTHORS. - -2009-01-04 Chong Yidong - - * display.texi (Visual Line Mode): M-] and M-[ no longer move by - logical lines. - -2008-12-29 Juri Linkov - - * mini.texi (Minibuffer History): Add a link to `Isearch Minibuffer'. - - * text.texi (Fill Commands): Replace `M-s' with `M-o M-s'. - -2008-12-28 Chong Yidong - - * misc.texi (Goto Address mode): Rename from Goto-address. Refer to - goto-address-mode instead of goto-address. - - * rmail.texi (Rmail Display): Goto-address renamed to Goto Address - mode. - - * emacs.texi (Top): Update node listing. - -2008-12-26 Eli Zaretskii - - * custom.texi (Directory Variables): Explain what is a "project". - Add indexing. Improve wording. Add a footnote about using - _dir-locals.el on MS-DOS. - -2008-12-24 Dan Nicolaescu - - * files.texi (Misc File Ops): Mention chmod as an alias for - set-file-modes. - -2008-12-24 Martin Rudalics - - * help.texi (Help): Fix typos and reword. - (Help Summary): Add entries for C-h n and C-h r, reorder - entries, and do some minor fixes. - (Name Help): Say that C-h F works for commands only. - (Misc Help): Say that view-lossage displays 300 keystrokes. - -2008-12-20 Glenn Morris - - * ack.texi (Acknowledgments): General update based on AUTHORS, - including removal of some stuff no longer distributed. - -2008-12-19 Agustin Martin - - * fixit.texi: Mention hunspell - -2008-12-19 Glenn Morris - - * ack.texi (Acknowledgments): Small grammar fix. - Consolidate explanatory text at start. - - * display.texi (Text Display): - * indent.texi (Indentation): Use @acronym with ASCII. - -2008-12-18 Glenn Morris - - * ack.texi: Various small updates and fixes. - -2008-12-18 Juri Linkov - - * search.texi (Word Search): Replace `C-s RET C-w' with `M-s w RET' - as a key binding to start a forward nonincremental word search. - Replace `C-r RET C-w' with `M-s w C-r RET' as a key binding to start - a backward nonincremental word search. Add index for `M-s w' - `isearch-forward-word'. - (Regexp Search): Add a short summary of regexp key commands like - in the node "Basic Isearch". - (Other Repeating Search): Fix typo. - -2008-12-14 Vinicius Jose Latorre - - * misc.texi (PostScript Variables): Fix doc. - -2008-12-10 Chong Yidong - - * programs.texi (Program Modes): Mention Ruby mode. - -2008-12-10 Dan Nicolaescu - - * misc.texi (emacsclient Options): Describe what an empty string - argument does for --alternate-editor. - -2008-12-09 Frank Schmitt - - * cmdargs.texi (Font X): Distinguish between client-side and - server-side fonts. List valid Fontconfig properties. Add reference to - Fontconfig manual. List valid GTK font properties. Explain use of - fc-list. - -2008-12-09 Chong Yidong - - * cmdargs.texi (Font X): Move discussion of quoting to top. - -2008-12-06 Glenn Morris - - * maintaining.texi (Old Revisions): Improve previous change. - -2008-12-05 Richard M Stallman - - * anti.texi (Antinews): Minor fixes. - -2008-12-03 Glenn Morris - - * maintaining.texi (Old Revisions): Fix diff-switches description. - -2008-12-01 Martin Rudalics - - * emacs.texi (Top): Fix typo. - -2008-11-30 Chong Yidong - - * misc.texi (Document View): Explain dependence on gs at the top. - Copyedits. - - * emacs.texi (Top): Add DocView nodes to detailed node listing. - - * programs.texi (Other C Commands): Document hide-ifdef-shadow. - (Comment Commands): Discuss region-active behavior of M-; first. - -2008-11-29 Martin Rudalics - - * display.texi (Line Truncation): Add reference to Continuation - Lines. - - * windows.texi (Pop Up Window): Mention split-height-threshold - and split-width-threshold. - (Split Window): Add reference to Continuation Lines. - -2008-11-28 Adrian Robert - - * macos.texi: Change references to "Mac" to "Mac / GNUstep". - (GNUstep Support): New node. - * anti.texi: - * emacs.texi: - * msdog.texi: Change reference to Mac OS node to Mac OS / GNUstep. - -2008-11-28 Richard M Stallman - - * misc.texi (Dissociated Press): Minor cleanups. - - * dired.texi (Image-Dired): Avoid passive. - -2008-11-28 Eli Zaretskii - - * anti.texi (Antinews): Add stuff about Unicode vs emacs-mule - representation. - -2008-11-26 Richard M. Stallman - - * files.texi (Visiting): Rewrite paragraph for clarity. - - * buffers.texi (Select Buffer): Rewrite paragraphs using active voice. - -2008-11-25 Alan Mackenzie - - * programs.texi (Moving by Parens): Clarify that parens inside strings - and comments are ignored, and that the commands assume the starting - point isn't in a string or comment. - -2008-11-26 Adrian Robert - - * macos.texi: Add Prev/Next/Top pointers to all nodes. - (Mac Basics): Merge in Grabbing Environment Variables from earlier - version. - (Mac Customization): Rewrite Preferences Panel section and merge in to - this node, add Open files by dragging to an Emacs window. - - * emacs.texi: Remove TOC reference to Mac Preferences Panel section. - -2008-11-26 Chong Yidong - - * files.texi (Misc File Ops): Document set-file-modes. - - * windows.texi (Split Window): Document integer values of - truncate-partial-width-windows. - - * text.texi (Text): Simplify description of markup languages. - (TeX Mode): Simplify introduction. Mention BibTeX mode. - (TeX Editing): Note that `""' inserts one `"' character. - (HTML Mode): Note in the introduction that XML mode is an alias for - SGML mode. Mention nXML mode. - -2008-11-25 Chong Yidong - - * building.texi (Watch Expressions): Fix typo. - -2008-11-24 Chong Yidong - - * files.texi (Visiting): Document new behavior of - confirm-nonexistent-file-or-buffer. - - * buffers.texi (Select Buffer): - Document confirm-nonexistent-file-or-buffer. - - * picture-xtra.texi (Picture Mode): Use picture-mode instead of - edit-picture. - - * text.texi (Text): Simplify introduction. Discard mention of `M-x - edit-picture', since that is just an alias for picture-mode. - (Sentences): Note that repeated M-@ extends the region. - (Pages): Make terminology more consistent. Link to Regexps node. - (Longlines): Discuss relationship with Visual Line mode. - (Text Mode): Remove extraneous discussion of other modes, since they - were already introduced in the parent node. - -2008-11-23 Chong Yidong - - * anti.texi (Antinews): Rewrite. - - * entering.texi (Exiting): Mention "minimize" terminology. - - * frames.texi (Frame Commands): Mention "minimize" terminology. - - * cmdargs.texi (Font X): Document Fontconfig and GTK font specification - formats. - (Icons X): Mention "minimize" terminology and use of icons in taskbar. - (Misc X): Don't document useless -hb option. - -2008-11-22 Juri Linkov - - * dired.texi (Dired Navigation): Change normal file name search option - from `non-nil' to `t'. Add `dwim' option. - -2008-11-22 Juri Linkov - - * custom.texi (Directory Variables): Rename ".dir-settings.el" to - ".dir-locals.el". Rename `define-project-bindings' to - `dir-locals-set-class-variables'. Rename `set-directory-project' to - `dir-locals-set-directory-class'. - -2008-11-22 Lute Kamstra - - * buffers.texi (Select Buffer): Index goto-line. - * basic.texi (Moving Point): Mention the use of a numeric prefix - argument with goto-line and refer to Select Buffer for the use of a - plain prefix argument. - -2008-11-19 Glenn Morris - - * doclicense.texi: Update to FDL 1.3. - * emacs.texi, emacs-xtra.texi: Relicense under FDL 1.3 or later. - -2008-11-17 Chong Yidong - - * custom.texi (Minor Modes): Define mode commands and mode variables - more precisely. Recommend using mode commands instead of setting - variables directly. Put minor modes in a list, and add more modes. - (Easy Customization): Use "init file" instead of .emacs. - (Customization Groups): Update to new Custom buffer appearance. - (Saving Customizations): Copyedits. Update example. - (Variables): Give example of variable type-sensitivity. - (Examining): Update example. - (Hooks): Copyedits. - (Specifying File Variables): Use C comments instead of an artificial - Lisp for the example. - (Keymaps): Move internals discussion to Prefix Keymaps. - (Rebinding): Remove redundant paragraph (stated in Key Binding). - (Init Rebinding): Document kbd macro. - (Init File): Link to Find Init. - - * mark.texi (Using Region): Document Delete Selection Mode more - thoroughly. - - * frames.texi (Mouse Commands): Move most of the description of Delete - Selection Mode to Using Region, and link to it. - (Clipboard): Note that paste is bound to clipboard-yank. - - * building.texi (Compilation): Document first-error value of - compilation-scroll-output. - (Compilation Mode): Note that compilation-auto-jump-to-first-error - works as soon as an error is available. Suggested by Juri Linkov. - - * mini.texi (Passwords): New node. - - * files.texi (Remote Files): Link to Passwords node. - - * emacs.texi (Top): Update node listings. - -2008-11-16 Chong Yidong - - * ack.texi (Acknowledgments): Some updating of credits. - - * emacs.texi (Acknowledgments): Add a couple more names. - - * dired.texi (Dired Deletion): Document delete-by-moving-to-trash. - - * files.texi (Directories): Describe delete-directory in text. - (Misc File Ops): Document use of trash. - -2008-11-16 Juanma Barranquero - - * macos.texi (Mac Customization): Fix typos. - -2008-11-14 Chong Yidong - - * macos.texi (Mac OS): Move Cocoa manual from ns-emacs.texi to here, - replacing previous contents. Numerous copyedits to adapt ns-emacs to - the conventions of the main Emacs manual. - - * emacs.texi (Top): Update node listings. - -2008-11-12 Chong Yidong - - * cmdargs.texi (Emacs Invocation): Link to Emacs Server. Note that - command-line-args is processed during startup. - (Action Arguments): Correctly describe how file arguments interact with - the startup screen. Link to Lisp Interaction for scratch buffer. - (Initial Options): Link to Command Example for -batch option. - (Environment): Document initial-environment. - - * entering.texi (Entering Emacs): Note that inhibit-startup-screen - can't be changed in the site-start file. - -2008-11-07 Chong Yidong - - * dired.texi (Dired): Mention C-x C-d too. - (Dired Enter): Document M-n in the Dired minibuffer. - (Dired Navigation): Explain dired-goto-file more clearly. - Document dired-isearch-filenames. - (Dired Deletion): Remove unnecessary "expunged" terminology. - (Flagging Many Files): & is now rebound to `% &'. - (Shell Commands in Dired): Document dired-do-async-shell-command. - Clarify how multi-file arguments are passed. - (Misc Dired Features): Document dired-do-isearch. - -2008-11-06 Chong Yidong - - * entering.texi (Entering Emacs): Document inhibit-startup-screen. - -2008-11-03 Chong Yidong - - * search.texi (Other Repeating Search): Remove obsolete findex entries. - -2008-11-01 Chong Yidong - - * programs.texi (Program Modes): Link to Program Indent node. - (Left Margin Paren): Explain consequences of changing - open-paren-in-column-0-is-defun-start more concisely. - (Which Function, Program Indent, Info Lookup): Minor edits. - (Basic Indent): If region is active, TAB indents the region. - (Multi-line Indent): If region is active, TAB indents the region. - Note that indent-region is useful when Transient Mark mode is off. - (Matching): The delimiter at the cursor is highlighted---the character - changes color. - (Symbol Completion): Link to Completion node. - - * misc.texi (Invoking emacsclient): Describe how to use Emacs server in - a strictly text-only system. - - * abbrevs.texi (Saving Abbrevs): Note that abbrev file is not loaded in - batch mode. - -2008-11-01 Richard M. Stallman - - * misc.texi (Document View): Major rewrite. - - * maintaining.texi (Types of Log File): Change logs are older than - version control. - (VCS Concepts): Simplify and rearrange. - (Version Control Systems): Make it clear that Linux is only the kernel. - (VC Mode Line): Shorten reference to menu item. - (Basic VC Editing): Clarify VC fileset. Shorten and simplify. - (VC Directory Mode): Minor cleanup. - Unchanged files are hidden, not omitted. - (VC Directory Commands): Shorten and simplify. - (Change Log Commands): New node, split from Change Logs. - (VC Directory Buffer): New node, split from VC Directory Mode. - -2008-10-31 Chong Yidong - - * misc.texi (Document View): Rename from Document Files, moved here - from files.texi. - - * files.texi (Version Control): Move to maintaining.texi. - Subnodes moved as well. - (Document Files): Move to misc.texi. - - * maintaining.texi (Change Log): Document log-edit-insert-changelog and - vc-update-change-log. - (Version Control): Move here from files.texi. - (Format of ChangeLog): Make it a subnode of Change Log. - - * emacs.texi (Top): Update node listing. - -2008-10-31 Tassilo Horn - - * files.texi (Files): Add a section about document - files (doc-view-mode). - -2008-10-31 Chong Yidong - - * building.texi (Compilation Mode): - Document compilation-auto-jump-to-first-error. - (Debuggers): Lower GUD subsections to subsubsections. - (Starting GUD): Add cindex. - (Lisp Interaction): Note that scratch is no longer the initial buffer. - -2008-10-30 Chong Yidong - - * indent.texi (Indentation): Link to Program Indent. - - * misc.texi (Invoking emacsclient): If Emacs has no available frame, it - now uses emacsclient's terminal. - -2008-10-29 Chong Yidong - - * mark.texi (Using Region): Document use-empty-active-region. - - * emacs.texi (Top): Update node listings. - - * misc.texi (Emacs Server): Rewrite. Document daemon-mode. - Don't mention obsolete emacs.bash script. - (Invoking emacsclient): Rewrite, moving optional arguments to - emacsclient Options. - (emacsclient Options): New node. Document server-use-tcp and - server-host. - -2008-10-28 Chong Yidong - - * indent.texi (Indentation): Replace list with paragraphed text, - putting description of syntax-driven indentation first. Document new - effect of active regions on tab. - (Tab Stops): Note that editable tab stops affect indentation commands. - -2008-10-27 Dan Nicolaescu - - * cmdargs.texi (Initial Options): Document -daemon=SERVER_NAME. - -2008-10-23 Chong Yidong - - * custom.texi (Function Keys): Note that modified keypad keys are not - translated. - - * basic.texi (Arguments): Explain how to insert multiple digits. - -2008-10-22 Michael Albinus - - * files.texi (Remote Files): Precise selection of default method. - Rewrite paragraph about disabling remote file names. - -2008-10-22 Chong Yidong - - * search.texi (Special Isearch): Document M-TAB is isearch. - - * files.texi (VC Mode Line): Use @kbd instead of @key for mouse - command. - - * frames.texi: Use @kbd instead of @key for mouse commands throughout. - -2008-10-22 Tassilo Horn - - * emacs.texi (Acknowledgments): Add myself to Acknowledgments - section. - -2008-10-21 Chong Yidong - - * vc1-xtra.texi: Move nodes VC Directory Mode and VC Directory Commands - to files.texi. Move contents of vc2-xtra.texi here. - - * vc2-xtra.texi: File removed. - - * vc-xtra.texi (Advanced VC Usage): Remove VC Directory Mode and VC - Directory Commands from the submenu. Don't include deleted file - vc2-xtra.texi. - - * files.texi (Visiting): Document find-file-confirm-nonexistent-file. - (Version Control): Add VC Directory Mode and VC Directory Commands to - the submenu. - (Why Version Control?): Use table format. - (Version Control Systems): Note that Meta-CVS support is gone. - (VCS Concepts): Note precisely when VC started supporting filesets. - Remove bogus xref to CVS Options node. - (Types of Log File): Copyedits. - (VC Mode Line): Document tooltips and mouse-1 on VC indicator. - (Basic VC Editing): Content moved from Selecting A Fileset and Doing - The Right Thing. - (Selecting A Fileset, Doing The Right Thing): Nodes deleted. - (Log Buffer): Reorganize node, putting C-c C-c description first. - (Old Revisions): Use CVS for example, not RCS. - (Secondary VC Commands): Remove VC Directory Mode and VC Directory - Commands from the submenu, putting them under Version Control. - (VC Directory Mode): Move node contents here from vc1-xtra.texi; we - need to include it in the manual unconditionally, since it is now - crucial to using distributed version control systems. - (Comparing Files): Note that diff uses the minibuffer, and that the - output is shown using Diff mode. - (Diff Mode): Explain what "patch" and "hunk" mean. - Document diff-update-on-the-fly, diff-refine-hunk, and - diff-show-trailing-whitespaces. - (File Archives): Add rar support. - - * major.texi (Choosing Modes): Make mode selection sequence more - obvious by describing the steps in order of priority. Note that - magic-mode-alist is nil by default. - Document magic-fallback-mode-alist. - -2008-10-20 Chong Yidong - - * frames.texi (Mouse References): Copyedits. - -2008-10-20 Tassilo Horn - - * ack.texi (Acknowledgments): Add myself as doc-view author. - -2008-10-20 Eli Zaretskii - - * frames.texi (Dialog Boxes): Add @cindex entries. - -2008-10-20 Chong Yidong - - * frames.texi (Dialog Boxes): Clarify description of GTK+ file chooser. - (Text-Only Mouse): Copyedit. - -2008-10-19 Chong Yidong - - * frames.texi: Use @key throughout for mouse clicks. - (Cut/Paste Other App): Document yank-pop-change-selection. - (Secondary Selection): Fix modified mouse click syntax. - (Clipboard): Describe Cut, Copy and Paste commands. - (Mouse References): Not all references are in read-only buffers. - Copyedits. - (Creating Frames): Add xref to Init File. - (Frame Commands): Add xref to Exiting. - (Scroll Bars): Document GTK vs toolkit behavior. - -2008-10-15 Chong Yidong - - * files.texi (Version Control): Copyedits. Add Bazaar. - (Version Control Systems): List different VCS's using an itemized list. - Add Bazaar. - (VCS Concepts): Copyedits. Tweak description of file merging. - - * frames.texi (Mouse Commands, Cut/Paste Other App): Rewrite. - (Cut/Paste Other App): Document select-active-regions and - x-select-enable-primary. - -2008-10-13 Chong Yidong - - * mark.texi (Shift Selection): Correct case in node name. - - * emacs.texi (Top): Update node order in Mark chapter. - -2008-10-12 Eli Zaretskii - - * msdog-xtra.texi (MS-DOS): Fix bad pxref. - - * mini.texi (Minibuffer File): Fix markup in last change. Refer to - elsewhere in the manual instead of describing yet again the intricacies - of $HOME on MS-Windows and MS-DOS. - -2008-10-12 Chong Yidong - - * mini.texi (Minibuffer File): Add xref to File Names. - (Minibuffer File): Add discussion of `~' in file names. - Add insert-default-directory index reference. - - * files.texi (File Names): Reorganize description. - (Visiting): Add xref to Mode Line. Copyedits. - (Save Commands): Mention prefix behavior of C-x C-s. - (Numbered Backups): Node deleted. - (Backup Names): Contents of Numbered Backups moved here. State default - of version-control variable. - (Reverting): Copyedits. - (Version Control): Add additional version control systems. - - * emacs.texi (Top): Delete Numbered Backups node. - - * cmdargs.texi (General Variables): Change Numbered Backups xref to - Backup Names. - (Initial Options): Document renamed variable inhibit-startup-screen. - -2008-10-11 Romain Francoise - - * kmacro.texi (Edit Keyboard Macro): Lossage is now 300 keys. - -2008-10-11 Chong Yidong - - * buffers.texi (Buffers): Add xrefs to Mode Line and Lisp Interaction. - (Select Buffer): Mention use of minibuffer history. Describe default - value of default-major-mode. Mention that C-x 4 b selects the other - window. - (List Buffers): Document CRM indicators in the order they appear. - (Kill Buffer): Document new command kill-matching buffers. - (Several Buffers): Move explanation of the relationship between buffer - list and buffer menu to the top. - (Indirect Buffers): Document new variable clone-indirect-buffer-hook. - -2008-10-10 Chong Yidong - - * entering.texi (Exiting): Document change of C-x C-c to - save-buffers-kill-terminal. Document kill-emacs. - -2008-09-30 Eli Zaretskii - - * mule.texi (Coding Systems): Don't mention codepage-setup. - - * msdog-xtra.texi (MS-DOS Printing, MS-DOS and MULE): No need to create - cpNNN coding systems anymore. - (MS-DOS and MULE): Don't mention code-pages.el. Don't mention support - for unibyte mode. Don't mention line-drawing characters. - Don't mention dos-unsupported-char-glyph. - -2008-09-25 Chong Yidong - - * search.texi (Search): Shorten introduction. - (Basic Isearch): Add command table. Discuss reverse isearch and - isearch highlighting. - (Repeat Isearch): Move lazy highlighting discussion here. Add search - ring to cindex. - (Special Isearch): Move input methods discussion here. - (Non-ASCII Isearch): Node deleted, merged with Special Isearch. - (Isearch Yank): Node deleted, and contents moved into Basic Isearch and - Repeat Isearch. - (Isearch Minibuffer): New node. - (Word Search): Document new word search commands. - (Regexp Example): Simplify example using sentence-end-base variable. - (Replace): Reword introduction. - (Unconditional Replace): Remove unnecessary example. - (Other Repeating Search): Document new `M-s o' binding. - - * emacs.texi (Top): Update node listings. - -2008-09-22 Juanma Barranquero - - * emacs.texi (Top): Remove Kill Errors from menu. - -2008-09-22 Chong Yidong - - * kmacro.texi (Basic Keyboard Macro): Make F3 and F4 the preferred - interface for defining macros. Simplify examples. Note that C-g quits - macro definitions. - (Keyboard Macro Counter): Document using F3 to insert counter. - Give usage example. - (Keyboard Macro Query): Organize query responses in a table. - - * fixit.texi (Fixit): Favor C-/ keybinding for undo throughout. - Link to Erasing node. - (Undo): Reorganize paragraphs for logical flow. Move keybinding - rationale to a footnote. - (Kill Errors): Remove node, due to redundancy with Erasing. - (Spelling): Move discussion of flyspell to end. Note new behavior of - M-$ in active region. Remove non-ispell-specific keybindings from - table. - -2008-09-21 Dan Nicolaescu - - * cmdargs.texi (Initial Options): Document --daemon. - -2008-09-20 Glenn Morris - - * files.texi (Numbered Backups): Mention that some modes set - version-control. - -2008-09-20 Jim Blandy - - * files.texi (Numbered Backups): Reference File Variables, as well. - Remove discussion of Rmail's implementation. - -2008-09-06 Chong Yidong - - * misc.texi (Recursive Edit): Note that top-level exits active - minibuffers. - - * trouble.texi (Quitting): Likewise. - -2008-08-31 Chong Yidong - - * emacs.texi (Top): Add Temporary Face Changes xref. - - * display.texi (Display): Move Temporary Face Changes node to just - after Standard Faces. - (Scrolling): Document recenter-top-bottom instead of recenter. - (Horizontal Scrolling): Move auto hscroll discussion to the top. - (Faces, Standard Faces, Temporary Face Changes, Useless Whitespace) - (Display Custom): Copyedits. - (Optional Mode Line): Document display-battery-mode. - -2008-08-27 Romain Francoise - - * custom.texi (Directory Variables): Minor fix. - -2008-08-27 Glenn Morris - - * cal-xtra.texi (Advanced Calendar/Diary Usage): Tweak some menu - descriptions. - (Calendar Customizing): Tweak layout description. - Move calendar-today-marker and calendar-today face to the other - markers. Condense calendar-star-date and calendar-mark-today - description. - (Holiday Customizing): Add oriental and solar holidays. - Add index entries for Baha'i, Christian, Hebrew and Islamic holidays. - Fix holiday-float description. Use zerop in examples. Be less verbose. - (Date Display Format): Change ISO format. Be less verbose. - (Diary Customizing): Mention day and month abbrev arrays. - Mention the date-form variables by name. Update European example. - (Non-Gregorian Diary): Change node name. Mention Baha'i functions. - Condense examples. Mention diary-entry-symbols by name. - Condense table for insertion commands. - (Fancy Diary Display): Mention diary-include-string and - diary-sexp-entry-symbol. Condense example. Add Chinese, Coptic, - Ethiopic, Persian date functions. Condense descriptions. - - * calendar.texi (Format of Diary File): Mention diary-nonmarking-symbol. - (Adding to Diary): Adapt for changed node name. - -2008-08-26 Glenn Morris - - * cal-xtra.texi (Non-Gregorian Diary Entries): New name for - node "Hebrew/Islamic Entries". - - * calendar.texi (Specified Dates): Fix names of iso functions. - (General Calendar): There may not be another window. - (Writing Calendar Files, Holidays): Tweak intro. - (Holidays): Mention Baha'i and Chinese holidays. - (Sunrise/Sunset): Add M-x calendar-sunrise-sunset-month. - (Lunar Phases): Remove incorrect reference to calendar-time-zone. - (To Other Calendar): Add calendar-print-other-dates. - Refer to "graphic display" rather than "X. - (From Other Calendar): Add calendar-bahai-goto-date. Fix reference. - (Displaying the Diary): Fix whitespace after reference. - Fix `diary-number-of-entries' reference. - (Date Formats): Explicitly mention that day names can be abbreviated. - (Adding to Diary): Add some references to other sections. - (Special Diary Entries): Fix reference. - (Appointments): Simplify appt-message-warning-time entry. - Clarify where times must be. - (Importing Diary): Comment out icalendar paragraph that does not apply. - (Time Intervals): Simplify entry for timeclock-ask-before-exiting. - -2008-08-23 Glenn Morris - - * fortran-xtra.texi (Fortran): Change description of free form and - fixed form a bit. Mention hideshow and imenu. - (Fortran Motion): Mention fortran-end-of-subprogram, - fortran-beginning-of-subprogram, fortran-mark-do, fortran-mark-if. - (Fortran Indent): Minor re-word. - (ForIndent Commands): Mention fortran-fill-paragraph and - fortran-fill-statement. - (ForIndent Cont): Mention fortran-tab-mode-string. - (Fortran Comments): Mention fortran-comment-line-start-skip. - (Fortran Columns): Mention font-locking. - (Fortran Abbrev): Word syntax not relevant with new-style abbrev. - -2008-08-23 Johan BockgÃ¥rd - - * basic.texi (Moving Point): Fix / confusion. - -2008-08-22 Chong Yidong - - * mini.texi (Minibuffer): Simplify introduction. - (Minibuffer File): Document tilde in minibuffer filenames. - (Minibuffer Edit): Mention that the prompt is read-only. Describe how - to enter tabs, spaces, and question marks. Describe behavior of C-a. - (Completion Example): Update example to current command list. - (Completion Options): Document `lazy' value of completion-auto-help. - Update contents of completion-ignored-extensions. - (Minibuffer History): Describe "future history" list. State default - value of history-delete-duplicates. - -2008-08-21 Glenn Morris - - * fortran-xtra.texi (Fortran Columns): Document `fortran-line-length'. - (Fortran Comments): Replace fortran-indent-comment with comment-dwim. - -2008-08-17 Chong Yidong - - * regs.texi (Registers): Clarify valid register names. - (RegPos): Note that buffer is saved and restored too. - (RegText): Note that mark is reactivated/deactivated. - (RegConfig): Xref to Windows node. - -2008-08-16 Chong Yidong - - * basic.texi (Inserting Text): Provide command name for C-q. - - * killing.texi (Killing): Copyedit. Define read-only text. - (Deletion): DEL and C-d were already explained in Erasing; xref there. - (Killing by Lines): Copyedit. - (Other Kill Commands): Move M-w description here. - (Yanking): Move M-w to Other Kill Commands. - (Kill Ring): Also mention saving text in registers. Link to Text - Properties in elisp manual. - (Accumulating Text): Copyedit. - (CUA Bindings): Shift selection is now the default. - -2008-08-12 Teodor Zlatanov - - * maintaining.texi (Change Log): Mention next-error is available. - -2008-08-10 Glenn Morris - - * cal-xtra.texi (Calendar Customizing): Mention whitespace variables - and intermonth text. - (Holiday Customizing): Add holiday-chinese. - -2008-08-08 Eli Zaretskii - - * files.texi (Log Buffer, Diff Mode): Fix last changes. Add indexing. - -2008-08-07 Dan Nicolaescu - - * files.texi (Log Buffer): Describe C-c C-d. - (Diff Mode): Describe C-x 4 A. - -2008-08-06 Eli Zaretskii - - * vc1-xtra.texi (VC Directory Mode): Fix last change. - -2008-08-06 Dan Nicolaescu - - * files.texi (Old Revisions): Update the keys used by vc-annotate and - describe the new bindings to show the changeset diff, toggle annotation - visibility, show revisions. - (VC Status): Describe key bindings for modifying the change comments, - displaying changeset diffs and annotations. - - * vc1-xtra.texi (VC Directory Mode): Talk about multiple VC systems. - -2008-08-05 Nick Roberts - - * vc1-xtra.texi (VC Directory Mode): Fix typo. - -2008-08-02 Eli Zaretskii - - * vc1-xtra.texi (VC Directory Mode, VC Directory Commands): Fix English - and wording. - -2008-08-02 Dan Nicolaescu - - * vc1-xtra.texi (VC Directory Mode): Fix and improve the info about - marking/unmarking. Add descriptions for the multiple file search - commands. Improve some old info. - -2008-07-31 Chong Yidong - - * display.texi (Visual Line Mode): New node. - - * basic.texi (Inserting Text): Move DEL to deletion node. - (Moving Point): Add additional alternative key bindings. - Describe line-move-visual. - (Erasing): Describe DEL. - (Basic Undo, Blank Lines, Arguments): Copyedit. - (Continuation Lines): Mention Visual Line mode. - (Position Info): Move extended discussion to mule.texi. - - * mule.texi (International Chars): Describe C-x =. - - * emacs.texi (Top): Add Visual Line Mode node. - -2008-07-31 Dan Nicolaescu - - * emacs.texi: Remove VMS support. - -2008-07-30 Dan Nicolaescu - - * vc1-xtra.texi (VC Directory Mode): Update the display format and fix - the vc-dir command name. - -2008-07-27 Dan Nicolaescu - - * xresources.texi: Remove mentions of Mac Carbon. - -2008-07-19 Andreas Schwab - - * ns-emacs.texi: Move to ../misc. - -2008-07-15 Chong Yidong - - * entering.texi (Exiting): Don't describe text-only terminals as the - default. Describe the new startup screen. - (Exiting): Describe how to kill Emacs first. Change description of - iconification to handle modern window systems. - -2008-07-15 Adrian Robert - - * ns-emacs.texi: New file, documents features of Emacs port under - NeXTstep windowing. - -2008-07-15 Chong Yidong - - * entering.texi (Entering Emacs): Update prev node. - - * glossary.texi (Glossary): Remove xref to Text Characters. - - * commands.texi (User Input): Rewrite. Describe Emacs' behavior - directly, rather than in the context of ASCII. Move description of - special properties of modifier key to new Modifier Keys node. - (Keys): Copyedit. - (Text Characters): Delete node. Multibyte is the default nowadays, and - the node contents are obsolete. - - * custom.texi (Modifier Keys): New node. - - * emacs.texi (Top): Update node list. - -2008-07-13 Chong Yidong - - * emacs.texi (Intro): Increase conciseness slightly. Remove paragraph - saying that Emacs provides menus and mouse support (which is par for - the course). - - * screen.texi (Screen): Copyedit. Define "buffer" and "current buffer" - early on. - (Point): Copyedit. Relegate historical trivia to a footnote. - (Mode Line): Explain mode-line format more consistently. - (Menu Bar): Copyedit. - -2008-06-27 Glenn Morris - - * cal-xtra.texi (Sexp Diary Entries): - * calendar.texi (Lunar Phases): Update for lunar.el name changes. - -2008-06-26 Chong Yidong - - * mark.texi (Shift selection): New node. - (Mark): Copyedits. - (Persistent Mark): Move to the end of the chapter. - -2008-06-20 Eli Zaretskii - - * makefile.w32-in (distclean): Remove makefile. - -2008-06-17 Nick Roberts - - * building.texi (Starting GUD): Add an entry for gud-gdb. - (GDB Graphical Interface): Explain that gud-gdb is now needed for text - command mode. - -2008-06-17 Glenn Morris - - * calendar.texi: Fix references to mouse-2 and mouse-3 in calendar. - -2008-06-17 Nick Roberts - - * building.texi (Starting GUD): Expand on remote debugging. - (Other GDB-UI Buffers): Mention new keyboard bindings. - -2008-06-15 Glenn Morris - - * gnu.texi: Use a verbatim license for this invariant section, - as per etc/GNU. - -2008-06-13 Daniel Engeler - - * emacs.texi, misc.texi: Add documentation about serial port access. - -2008-06-13 Glenn Morris - - * emacs-xtra.texi, emacs.texi: Update Back-Cover text per - maintain.info. - -2008-06-05 Miles Bader - - * display.texi (Temporary Face Changes): Update to reflect function - renamings in face-remap.el. - -2008-06-04 Miles Bader - - * display.texi (Temporary Face Changes): - Add `adjust-buffer-face-height'. Rewrite description of - `increase-buffer-face-height' and `decrease-default-face-height' now - that they aren't bound by default. - -2008-06-03 Miles Bader - - * display.texi (Temporary Face Changes): New node. - -2008-05-31 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Fix text added on 2008-05-29. - -2008-05-31 Glenn Morris - - * cal-xtra.texi (Fancy Diary Display): Simplify. - -2008-05-30 Glenn Morris - - * cal-xtra.texi (Fancy Diary Display): Update for - diary-display-function replacing diary-display-hook. - -2008-05-29 Drew Adams - - * msdog.texi (Windows Keyboard): Add descriptions of - w32-register-hot-key and w32-unregister-hot-key. - -2008-05-21 Tom Tromey - - * custom.texi (Directory Variables): Grammar fix. Link to Safe File - Variables node. - -2008-05-19 Tom Tromey - - * custom.texi (Variables): Add Directory Variables to menu. - (Directory Variables): New node. - -2008-05-16 Eric S. Raymond - - * vc2-xtra.texi: Modify an example so it reflects what vc.el now does. - -2008-05-15 Eric S. Raymond - - * vc2-xtra.texi, emacs.texi, files.texi: Snapshots node renamed to - Revision Tags and rewritten. Section now uses modern terminology, - (tags rather than snapshots) and describes post-SCCS systems more - accurately. - -2008-05-10 Eli Zaretskii - - * msdog.texi (Windows Files): Update documentation of - w32-get-true-file-attributes. - -2008-05-09 Eric S. Raymond - - * files.texi, vc-xtra.texi, vc1-xtra.texi: Document the new VC - directory mode. - -2008-05-08 Chong Yidong - - * killing.texi (Appending Kills): Remove a strangely off-topic index - entry "television". - -2008-05-07 Eric S. Raymond - - * ack.texi, files.texi, vc2-xtra.texi: Meta-CVS is no longer supported. - -2008-05-02 Eric S. Raymond - - * emacs/buffers.texi, emacs/files.texi (Version-control): - vc-toggle-read-only is no longer a good idea... - -2008-04-29 Glenn Morris - - * cal-xtra.texi (Sexp Diary Entries): Clarify diary-float. - -2008-04-22 Juri Linkov - - * dired.texi (Subdirectories in Dired): Describe using `^' - to return to the parent directory. - -2008-04-22 Nick Roberts - - * building.texi (GDB-UI Layout, Other GDB-UI Buffers): Update for - recent changes. - -2008-04-19 Nick Roberts - - * building.texi (GDB-UI Layout, Breakpoints Buffer) - (Other GDB-UI Buffers): Update for recent thread related changes. - -2008-04-11 Mirko Vukovic (tiny change) - - * maintaining.texi (Maintaining): - * emacs.texi (Top): Typo. - -2008-04-08 Stefan Monnier - - * display.texi (Font Lock): Prefer add-hook to using a non-nil `mode' - arg in `font-lock-add-keywords'. - -2008-04-08 Glenn Morris - - * cal-xtra.texi, calendar.texi: Update for calendar name changes. - Also add Baha'i calendar references where appropriate. - -2008-04-05 Glenn Morris - - * custom.texi (Init File): Byte-compiling .emacs is bad. - -2008-04-04 Stefan Monnier - - * mini.texi (Minibuffer Edit) : Adjust default. - -2008-03-29 Glenn Morris - - * calendar.texi: Update for `calendar-date-style' replacing - `european-calendar'. - -2008-03-28 Jason Rumney - - * display.texi (Display Custom): Mention overlay-margin in text. - -2008-03-12 Reiner Steib - - * custom.texi, dired.texi, mini.texi, mule.texi: Add `referenced in the - tutorial' comments. - -2008-03-28 Chong Yidong - - * mark.texi (Mark): Rearrange nodes. - (Persistent Mark): Rename from Transient Mark. - (Mark, Setting Mark, Marking Objects, Persistent Mark, Mark Ring): - Describe Transient Mark mode as the default. - - * basic.texi (Basic Undo): Don't mention setting the mark, which isn't - the default behavior with Transient Mark mode off. - (Position Info): Fix typo. - - * display.texi (Standard Faces): Reference the Mark node. - Remove discussion of the region face, which is discussed there. - - * emacs.texi (Top): Update node listings. - - * files.texi (Diff Mode, Misc File Ops): Describe Transient Mark mode - as the default. - - * fixit.texi (Undo): Standardize choice of undo key sequence. - (Undo, Spelling): Describe Transient Mark mode as the default. - - * frames.texi (Mouse Commands): Treat Transient Mark mode as the - default. - - * glossary.texi (Glossary): Treat Transient Mark mode as the default. - - * killing.texi (Kill Ring, Accumulating Text): Assume Transient Mark - mode is the default, and note that the mark is not activated when set. - - * programs.texi (Moving by Defuns, Expressions, Comment Commands): - Describe Transient Mark mode as the default. - - * search.texi (Basic Isearch): Reference the Mark Ring node. - (Replace, Unconditional Replace, Other Repeating Search): - Describe Transient Mark mode as the default. - - * text.texi (Words, Pages, Fill Commands, HTML Mode): - Describe Transient Mark mode as the default. - (Paragraphs): Describe how M-h behaves when region is active. - - * trouble.texi (Quitting): Clarify effects of C-g. - -2008-03-13 Glenn Morris - - * emacs.texi (EMACSVER): Set to 23.0.60. - -2008-03-05 Glenn Morris - - * dired.texi (Hiding Subdirectories): Fix previous change. - -2008-03-05 Drew Adams - - * dired.texi (Hiding Subdirectories): Document `dired-hide-subdir'. - -2008-02-28 Kim F. Storm - - * help.texi (Help Files): Move describe-gnu-project to C-h g. - Move describe-distribution to C-h C-o. - Move view-emacs-problems to C-h C-p. - Add view-emacs-debugging on C-h C-d. - Add view-external-packages on C-h C-e. - Add view-order-manuals on C-h C-m. - -2008-02-17 Ulrich Mueller - - * msdog-xtra.texi (MS-DOS): Docstring fix. - -2008-02-09 Eli Zaretskii - - * msdog.texi (Windows Fonts): Use a @table for describing font - properties. - -2008-02-07 Jason Rumney - - * msdog.texi (Windows Files): w32-get-true-file-attributes default - value has changed. - (Windows HOME): Clarify what is meant by "if that fails as well". - (Windows Fonts): New section. - -2008-02-07 D. E. Evans (tiny change) - - * basic.texi (Basic Undo): Remove duplicate "you can". - -2008-02-02 Eli Zaretskii - - * maintaining.texi (Tags): Fix last change. - -2008-02-02 Michael Albinus - - * tramp.texi: Use new FSF's Back-Cover Text. - -2008-01-31 Nick Roberts - - * trouble.texi (Checklist): Direct users to emacs-devel@gnu.org. - -2008-01-26 Richard Stallman - - * maintaining.texi (Tags): Delete redundant index entry. - -2008-01-26 Eli Zaretskii - - * programs.texi (Imenu): Move "@cindex tags" from here... - * maintaining.texi (Tags): ...to here. - -2008-01-23 Kevin Ryde - - * custom.texi (Mouse Buttons): Update elisp xref to "Click Events" on - click count. - -2008-01-21 Juanma Barranquero - - * entering.texi (Exiting): Fix typo. - Reported by D. E. Evans . - -2007-12-31 Martin Rudalics - - * glossary.texi (Glossary): Fix typo. - -2007-12-27 Richard Stallman - - * text.texi (Formatted Text): Improve menu tag. - (Editing Format Info): In Info, add duplicate menu of nodes - about the submenus. - (Format Faces): Say where Faces menu is found. Mention Other. - (Format Colors): Say where these submenus are found. - (Format Indentation, Format Justification): Likewise. - (Format Properties): Likewise. - -2007-12-22 Richard Stallman - - * search.texi (Query Replace): Make exp of query-replace more - self-contained, and clarify. - - * cc-mode.texi (Getting Started): Change @ref to @pxref. - -2007-12-15 Richard Stallman - - * files.texi (Auto Save): Clarify definition of auto-saving. - -2007-11-26 Richard Stallman - - * help.texi (Help Echo): Cleanups. - -2007-11-23 Thien-Thi Nguyen - - * files.texi (Why Version Control?): Fix typo. - (VCS Concepts): Fix typos; small tense fix. - (Selecting a Fileset): Fix typos; small rewording. - (Log Buffer): Likewise. - (Old Revisions): Likewise. - -2007-11-17 Eli Zaretskii - - * mule.texi (Communication Coding): Fix wording of last change. - -2007-11-16 Werner Lemberg - - * custom.texi (Specifying File Variables): - * major.texi (Choosing Modes): Mention '\" in man pages. - -2007-11-16 Kenichi Handa - - * mule.texi (Communication Coding): Document x-select-request-type. - - * frames.texi (Cut/Paste Other App): Mention x-select-request-type. - -2007-11-15 Francesco Potortì - - * maintaining.texi (TEXTAGS): Note that you can use "-" for stdout with - --output=file. - -2007-11-13 Martin Rudalics - - * help.texi (Help Summary, Apropos, Misc Help): Fix typos. - (Help Echo): Avoid mentioning the term "region" here and - consistently use the term "active text". - -2007-11-11 Glenn Morris - - * calendar.texi (Special Diary Entries): Fix Thanksgiving example. - -2007-11-10 Paul Pogonyshev - - * search.texi (Query Replace): - Mention `query-replace-show-replacement'. - -2007-11-09 Nick Roberts - - * building.texi (Watch Expressions): Remove obscure sentence. - -2007-11-06 Kenichi Handa - - * mule.texi (Select Input Method): Describe how to activate an input - method in the text mode. - -2007-11-01 Dan Nicolaescu - - * cmdargs.texi (Misc Variables): Remove Sun windows info. - -2007-10-30 Nick Roberts - - * building.texi (Watch Expressions): Describe gdb-delete-out-of-scope. - -2007-10-30 Glenn Morris - - * misc.texi (Directory Tracking): Explain a bit more about - dirtrack-mode. - -2007-10-25 Glenn Morris - - * fortran-xtra.texi (Fortran): F90 mode handles F2003. - -2007-10-24 Richard Stallman - - * misc.texi (Interactive Shell): Cleanup last change. - -2007-10-22 Juri Linkov - - * mini.texi (Minibuffer History): Add text about a list of minibuffer - default values. - -2007-10-20 Eric S. Raymond - - * files.texi: Disambiguate two slightly different uses of the term - 'filesets'. - -2007-10-18 Martin Rudalics - - * trouble.texi (Quitting): Fix typo. - -2007-10-18 Glenn Morris - - * frames.texi (Mode Line Mouse): Mention minor mode names. - -2007-10-17 Juri Linkov - - * text.texi (Fill Commands): Undocument fill-paragraph-or-region. - fill-paragraph operates on the active region in Transient Mark mode. - (Fill Prefix, Format Indentation): Replace fill-paragraph-or-region - with fill-paragraph. - - * basic.texi (Arguments): Replace fill-paragraph-or-region with - fill-paragraph. - - * fixit.texi (Spelling): ispell-word operates on the active region - in Transient Mark mode. - -2007-10-17 Aaron S. Hawley - - * building.texi (Source Buffers): - * custom.texi (Init Non-ASCII): - * glossary.texi (Glossary): Use "key binding" consistently. - -2007-10-17 Juanma Barranquero - - * calendar.texi (Diary): Fix directive. - -2007-10-16 Richard Stallman - - * calendar.texi (Diary): Clarify text about diary file example. - -2007-10-13 Eric S. Raymond - - * files.texi: Capitalize node names according to convention. - -2007-10-13 Glenn Morris - - * misc.texi (Interactive Shell): Correct INSIDE_EMACS reference. - -2007-10-11 Eric S. Raymond - - * emacs.texi: - * files.texi (Version Systems): Minor fixes to version-control material - suggested by RMS and Robert J. Chassell. - -2007-10-10 Eric S. Raymond - - * files.texi (Version Systems): - * vc-xtra.texi: - * vc1-xtra.texi: - * vc2-xtra.texi: Merge in changes for new VC with fileset-oriented - operations. Change of terminology from `version' to `revision'. - Revise text for adequate description of VCSes with monotonic IDs. - * emacs.texi: Change of terminology from `version' to `revision'. - -2007-10-09 Eric S. Raymond - - * files.texi (Version Systems): Describe newer VCses. - Reorder the descriptions to be chronological. - -2007-10-09 Richard Stallman - - * display.texi (Cursor Display): Correct how cursor appears - in nonselected windows. - -2007-10-04 Nick Roberts - - * building.texi (GDB Graphical Interface): Remove references to gdba - and mention gud-gdb. - -2007-08-31 Eli Zaretskii - - * rmail.texi (Rmail Sorting): Improve indexing. - -2007-10-06 Juri Linkov - - * text.texi (Fill Commands): Document fill-paragraph-or-region. - (Fill Prefix, Format Indentation): Replace fill-paragraph with - fill-paragraph-or-region. - - * basic.texi (Arguments): Replace fill-paragraph with - fill-paragraph-or-region. - -2007-10-06 Eric S. Raymond - - * files.texi: Update the section on version control for 2007 - conditions. None of these changes are new-VC-specific; that - will come later. - -2007-09-15 Glenn Morris - - * calendar.texi (Holidays): Change all instances of `holiday-list' back - to `list-holidays'. - -2007-09-14 Glenn Morris - - * calendar.texi: Update all instances of mark-calendar-holidays, - list-calendar-holidays, list-holidays with the new names. - -2007-09-06 Glenn Morris - - Move manual sources from man/ to subdirectories of doc/. - Split into the Emacs manual in emacs/, and other manuals in misc/. - * Makefile.in (INFO_TARGETS, DVI_TARGETS): Reduce to just the Emacs - manual. - (infodir): New variable. - (info): Use $infodir. - (emacsman): Delete target, not needed any more. - Move all targets that are not the Emacs manual to misc/Makefile.in. - (mostlyclean): Remove `gnustmp'. - * makefile.w32-in (INFO_TARGETS, DVI_TARGETS): Reduce to just the Emacs - manual. - (MULTI_INSTALL_INFO, ENVADD, infodir): Go up one more level. - (emacsman): Delete target, not needed any more. - (clean): Remove all info files but Emacs manual. - Move all targets that are not the Emacs manual to misc/Makefile.in. - * emacs-xtra.texi, emacs.texi (setfilename): Go up one more level. - - * Makefile.in (INFOSOURCES): Delete. - (.SUFFIXES): Use $(TEXI2DVI) rather than texi2dvi. - (mostlyclean): Add *.op, *.ops. Move *.aux *.cps *.fns *.kys *.pgs - *.vrs *.toc here... - (maintainer-clean): ...from here. - -2007-09-05 Glenn Morris - - * custom.texi (Safe File Variables): Clarify `!' and risky variables. - -2007-08-29 Glenn Morris - - * emacs.texi (EMACSVER): Increase to 23.0.50. - -2007-08-27 Richard Stallman - - * emacs.texi (Top): Clarify menu item for Glossary. - - * display.texi (Faces): Change secn title. - Clarify not all fonts come from Font Lock. - -2007-08-17 Eli Zaretskii - - * basic.texi (Position Info): Add index entry for face at point. - Mention that character faces are also displayed by "C-u C-x =". - -2007-08-08 Glenn Morris - - * glossary.texi (Glossary): Deprecate `iff'. - -2007-08-07 Chong Yidong - - * files.texi (File Conveniences): Document point motion keys in Image - mode. - -2007-07-27 Glenn Morris - - * emacs.texi (Copying): Include license text from gpl.texi, rather than - in-line. - - * gpl.texi: New file with text of GPL. - * Makefile.in (EMACSSOURCES): Add gpl.texi. - -2007-07-26 Dan Nicolaescu - - * vc2-xtra.texi (Customizing VC): Add GIT and HG. - - * dired.texi (Wdired): Mention C-x C-q key binding. - -2007-07-28 Nick Roberts - - * building.texi (GDB Graphical Interface): Qualify use of "M-x gdba". - -2007-07-25 Glenn Morris - - * emacs.texi (Copying): Replace license with GPLv3. - - * Relicense all FSF files to GPLv3 or later. - -2007-07-24 Glenn Morris - - * calendar.texi (Writing Calendar Files): cal-tex-diary etc only work - for some calendars. - -2007-07-23 Nick Roberts - - * screen.texi (Mode Line): Describe new mode-line flag that shows if - default-directory for the current buffer is on a remote machine. - -2007-07-21 Eli Zaretskii - - * vc2-xtra.texi (Customizing VC) : Update the - default value. - -2007-07-21 Richard Stallman - - * files.texi (Why Version Control?): Improve previous change. - -2007-07-18 Eric S. Raymond - - * files.texi (Why Version Control?): New node. - -2007-07-12 Nick Roberts - - * building.texi (Starting GUD): Add xref to this anchor. - -2007-06-24 Karl Berry - - * emacs.texi: New Back-Cover Text. - -2007-06-07 Alan Mackenzie - - * display.texi (Optional Mode Line): Document the new form of - line+column numbers, "(561,2)". - -2007-06-06 Juanma Barranquero - - * maintaining.texi (Create Tags Table): Fix typos. - -2007-06-02 Chong Yidong - - * Version 22.1 released. - -2007-05-07 Karl Berry - - * emacs.texi (EMACSVER): Back to 22. - -2007-05-06 Richard Stallman - - * maintaining.texi (Create Tags Table): Clean up previous change. - -2007-05-05 Francesco Potortì - - * maintaining.texi (Create Tags Table): Add text about the dangers of - making symbolic links to tags files. - -2007-05-04 Karl Berry - - * emacs.texi (EMACSVER) [smallbook]: 22.1 for printed version, not 22. - -2007-05-03 Karl Berry - - * emacs.texi (EMACSVER) [smallbook]: 22 for printed version. - - * .cvsignore (*.pdf): New entry. - - * emacs.texi (\urlcolor, \linkcolor) [smallbook]: \let to \Black - for printing. - -2007-05-01 Richard Stallman - - * cmdargs.texi (Initial Options): Under --batch, mention --eval. - -2007-04-28 Glenn Morris - - * ack.texi (Acknowledgments): - * anti.texi (Antinews): - * programs.texi (Program Modes): Restore mention of python.el pending - consideration of legal status. - -2007-04-28 Richard Stallman - - * files.texi (File Names): Fixes to ~ description on MS systems. - -2007-04-26 Glenn Morris - - * emacs.texi (EMACSVER): Increase to 22.1.50. - -2007-04-25 Karl Berry - - * emacs.texi: Improve line breaks on copyright page, - similar layout to lispref, 8.5x11 by default. - - * dired.texi (Image-Dired): Improve line break, fix typo. - -2007-04-24 Chong Yidong - - * programs.texi (Program Modes): - * anti.texi (Antinews): - * ack.texi (Acknowledgments): python.el removed. - -2007-04-23 Chong Yidong - - * display.texi (Highlight Interactively): Correct description of - hi-lock-file-patterns-policy. - - * files.texi (File Archives): Mention self-extracting executables. - -2007-04-23 Eli Zaretskii - - * search.texi (Unconditional Replace, Query Replace): Add xref to - "Replacement and Case". - -2007-04-22 Chong Yidong - - * dired.texi (Image-Dired): Move from Thumbnails node. - * misc.texi (Thumbnails): Node deleted. - * emacs.texi (Top): Update node listing. - - * files.texi (File Conveniences): - * ack.texi (Acknowledgments): Rename "tumme" to "image-dired". - -2007-04-21 Richard Stallman - - * display.texi (Highlight Interactively): Correct previous change. - Clarify doc of hi-lock-find-patterns, and move new features into it. - -2007-04-20 David Koppelman - - * display.texi (Highlight Interactively): - Document hi-lock-file-patterns-policy. - -2007-04-20 Martin Rudalics - - * display.texi (Scrolling): Fix typo. - -2007-04-15 Chong Yidong - - * doclicense.texi: Remove node heading, so that it can be included by - other files. - - * emacs.texi: Insert node heading for GFDL. - -2007-04-14 Eli Zaretskii - - * cmdargs.texi (Colors): Qualify "color of window" index entry by - "command line". - - * display.texi (Faces): Refer to "Creating Frames" for face - and other frame customizations in .emacs. - - * frames.texi (Creating Frames): Mention that face customizations can - be put in .emacs. Add index entries. - -2007-04-12 Richard Stallman - - * glossary.texi (Glossary): Explain `iff'. - -2007-04-11 Karl Berry - - * gnu.texi (Top), - * macos.texi (Mac Font Specs), - * anti.texi (Antinews), - * xresources.texi (Resources), - * misc.texi (Emulation), - * calendar.texi (Daylight Saving), - * dired.texi (Dired and Find), - * rmail.texi (Remote Mailboxes), - * sending.texi (Mail Headers), - * programs.texi (Which Function), - * files.texi (Recover), - * buffers.texi (Uniquify), - * frames.texi (Wheeled Mice), - * killing.texi (Rectangles): Wording to improve breaks in - 8.5x11 format. - * mule.texi (Language Environments): \hbadness=10000 since there's - no way to reword. - * emacs.texi (smallbook): New @set to more easily switch between - smallbook and 8.5x11. - -2007-04-11 Richard Stallman - - * files.texi (File Conveniences): Add xref to Tumme. - Delete text about Thumbnail mode. - -2007-04-09 Alan Mackenzie - - * cmdargs.texi (Initial Options): Call "inhibit-splash-screen" by its - new name. Insert concept index entries. - -2007-04-08 Chong Yidong - - * display.texi (Standard Faces): Document prefix arg for - list-faces-display. - - * rmail.texi (Rmail Scrolling): Document rmail-end-of-message. - -2007-04-07 Chong Yidong - - * killing.texi (Deletion): Rewrite description of M-\ prefix argument. - - * files.texi (Misc File Ops): Rewrite description of - insert-file-literally. - -2007-03-31 Eli Zaretskii - - * misc.texi (Printing): Postscript -> PostScript. - - * ack.texi (Acknowledgments): Postscript -> PostScript. - - * custom.texi (Init File, Init Non-ASCII): Fix last change. - - * emacs.texi (Top): Fix the menu due to the change in custom.texi - below. - -2007-03-30 Chong Yidong - - * custom.texi (Non-ASCII Rebinding): Node deleted. Material moved to - Init Non-ASCII. - (Init Rebinding, Init Syntax): Link to Init Non-ASCII instead. - (Init Non-ASCII): New node. - -2007-03-28 YAMAMOTO Mitsuharu - - * macos.texi (Mac Font Specs): Mention AppleAntiAliasingThreshold. - -2007-03-12 Glenn Morris - - * calendar.texi, emacs.texi (Daylight Saving): Rename node from - "Daylight Savings". - - * calendar.texi: Replace "daylight savings" with "daylight - saving" in text throughout. - -2007-03-04 Richard Stallman - - * custom.texi (Safe File Variables): Minor correction. - -2007-02-28 Thien-Thi Nguyen - - * rmail.texi (Movemail): Add internal ref. - Don't indent the intro for the PROTO table. - Format PROTO table items with @code. - -2007-02-26 Nick Roberts - - * building.texi: Remove references to bashdb. - -2007-02-19 Juanma Barranquero - - * mule.texi (Language Environments): Update list of supported language - environments. - -2007-02-14 Kim F. Storm - - * building.texi (Grep Searching): Fix lgrep doc. - -2007-02-12 Chong Yidong - - * back.texi: Remove unused file. - -2007-02-05 Francesco Potortì - - * maintaining.texi (Tag Syntax): Now --members is the default for - etags, not for ctags yet. - -2007-02-03 Eli Zaretskii - - * emacs.texi (Top): Update the top-level menus. Make the detailed menu - headers compliant with Texinfo guidelines and with what texnfo-upd.el - expects. Add comments to prevent people from inadvertently modifying - the key parts needed by `texinfo-multiple-files-update'. - -2007-01-29 Chong Yidong - - * frames.texi (Secondary Selection): Window clicked does not matter - when mouse-yank-at-point is non-nil. - -2007-01-16 Glenn Morris - - * abbrevs.texi (Editing Abbrevs): Describe how to disable a - system abbrev. - -2007-01-11 Richard Stallman - - * msdog.texi (Windows Keyboard): Another small cleanup. - -2007-01-10 Richard Stallman - - * msdog.texi (Windows Keyboard): Yet another try to make - everyone happy with that passage. - -2007-01-05 Richard Stallman - - * anti.texi (Antinews): Mention M-x shell scrolling. - -2007-01-05 Nick Roberts - - * building.texi (Watch Expressions): Describe gdb-max-children. - -2007-01-04 Richard Stallman - - * msdog.texi (Windows Keyboard): Clarify previous change. - -2007-01-02 Richard Stallman - - * custom.texi (Changing a Variable): Minor clarification. - (Specific Customization): customize-customized => customize-unsaved. - - * entering.texi (Entering Emacs): Clean up text about restarting - Emacs for each file. - - * misc.texi (Shell Options): Minor cleanup. - - * msdog.texi (Windows Keyboard): Explain that Windows was incompatible - with Emacs, not vice versa. - - * programs.texi (Symbol Completion): Recommend customizing - window manager. - - * xresources.texi (Resources): Minor fix. - -2007-01-01 Jan Djärv - - * xresources.texi (Table of Resources): Add scrollBarWidth resource. - -2007-01-01 Richard Stallman - - * commands.texi (User Input): Document keys stolen by window mangers. - -2006-12-31 Richard Stallman - - * custom.texi (Specific Customization): Document customize-option - instead of customize-variable. - -2006-12-31 Kim F. Storm - - * major.texi (Choosing Modes): Document auto-mode-case-fold. - -2006-12-30 Kim F. Storm - - * killing.texi (CUA Bindings): Fix typo. - - * xresources.texi (Table of Resources): Mention grow-only value for - auto-resize-tool-bars. - -2006-12-27 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Mention widespread Windows bindings, - and how to get them back. - -2006-12-26 Richard Stallman - - * calendar.texi (Holidays): Holiday listing is based on current - practice, but DST is not. - -2006-12-25 Richard Stallman - - * emacs.texi (Top): Update subnode menus. - - * mark.texi (Transient Mark): Fix xref. - - * killing.texi (Graphical Kill): Node deleted. - (Killing): Add xref to Cut and Paste. - (CUA Bindings): Update xref. - - * frames.texi (Cut and Paste): New section to hold other nodes. - (Mouse Commands): Node demoted. - (Cut/Paste Other App): Split out from Mouse Commands. - (Word and Line Mouse): Likewise. - (Secondary Selection, Clipboard): Nodes demoted. - -2006-12-24 Kevin Ryde - - * calendar.texi (Holidays): US daylight saving begins second Sunday - in March for 2007 onwards. - (Daylight Savings): Show new US default daylight saving rules, 2nd - Sun in Mar to 1st Sun in Nov, now in cal-dst.el. - -2006-12-23 Chong Yidong - - * calendar.texi (Scroll Calendar): < and > are switched. - -2006-12-23 Kevin Rodgers - - * killing.texi (Deletion): Describe M-\ prefix argument. - -2006-12-23 Richard Stallman - - * search.texi (Regexp Search): Explain why forward and reverse regexp - search are not mirror images. - -2006-12-19 Kim F. Storm - - * major.texi (Choosing Modes): Describe match-function elements for - magic-mode-alist. - -2006-12-18 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Add a footnote about "Windows" keys - peculiarities. - -2006-12-18 Richard Stallman - - * abbrevs.texi (Editing Abbrevs): Fix previous change. - -2006-12-17 Alan Mackenzie - - * programs.texi (Left Margin Paren): Remove the bit which says - that CC Mode sets open-paren-in-column-0-is-defun-start to nil. - Discuss some of the issues of setting this option to nil. - -2006-12-17 Glenn Morris - - * abbrevs.texi (Editing Abbrevs): Mention system abbrevs. - -2006-12-16 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Clarify `w32-recognize-altgr' effect. - (Windows Files): `w32-get-true-file-attributes' is only relevant for - NTFS volumes. - (ls in Lisp): `links' in `ls-lisp-verbosity' is only relevant to NTFS - volumes. - -2006-12-15 Eli Zaretskii - - * text.texi (HTML Mode): Fix "C-c TAB". - -2006-12-09 Richard Stallman - - * misc.texi (Invoking emacsclient): Simplify TCP file text. - -2006-12-08 Kevin Rodgers - - * files.texi (Misc File Ops): Document insert-file-literally. - -2006-12-08 Eli Zaretskii - - * cmdargs.texi (Colors): Note that --color is intended for overriding - the terminal defaults, not for normal invocation. - - * misc.texi (Emacs Server): Improve wording. Don't mention the - ``server program''. Add a cross-reference to "Init File" node. - (Invoking emacsclient): Add index entries. Document both short and - long versions of command-line options. Document the -f option. - -2006-12-06 Richard Stallman - - * text.texi (Outline Format): Say to set outline-regexp - and outline-level with major modes and file local variables. - -2006-12-05 Michaël Cadilhac - - * anti.texi (Antinews): Mention the alternative to - `~/.emacs_SHELLNAME', which is `~/.emacs.d/init_SHELLNAME.sh'. - - * misc.texi (Interactive Shell): Ditto. - -2006-12-04 Eli Zaretskii - - * emacs.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. - - * ack.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. - -2006-12-01 Eli Zaretskii - - * mule.texi (Enabling Multibyte): Rephrase the confusing reference to a - colon in the mode line. - - * msdog.texi (Windows Processes) [@ifnottex]: Mention w32-shell-execute. - -2006-11-26 Nick Roberts - - * building.texi (Watch Expressions): Mention SPC for expanding/ - contracting watch expressions. - -2006-11-26 Kim F. Storm - - * kmacro.texi (Basic Keyboard Macro): Mention F3/F4 more. - -2006-11-26 Nick Roberts - - * building.texi (Debugger Operation): Define text command mode. - Clarify how tooltips work. - (GDB Graphical Interface): Explain how to run in text command mode - more clearly. - -2006-11-25 Juanma Barranquero - - * mule.texi (Defining Fontsets): Fix use of `charset' and `font'. - -2006-11-22 Juanma Barranquero - - * anti.texi (Antinews): Mention --server-file and TCP sockets. - -2006-11-18 Chong Yidong - - * misc.texi (Interactive Shell): INSIDE_EMACS is set to t, - and EMACS is deprecated. - -2006-11-18 Juanma Barranquero - - * makefile.w32-in (emacs.dvi): Remove xresmini.texi. - -2006-11-18 Jan Djärv - - * Makefile.in (emacs.dvi): Remove xresmini.texi. - - * emacs.texi: Include xresources.texi both for info and dvi. - - * xresources.texi: Merge text from xresmini.texi. - -2006-11-12 Roberto Rodríguez (tiny change) - - * glossary.texi: Fix typos. - -2006-11-06 Richard Stallman - - * emacs.texi (Acknowledgments): Fix name spelling, add Anna Bigatti. - - * ack.texi (Acknowledgments): Fix name spelling. - -2006-11-01 Juri Linkov - - * search.texi (Word Search): Document incremental word search. - -2006-10-28 Glenn Morris - - * ack.texi (Acknowledgments): Add cal-html author. - - * calendar.texi (Writing Calendar Files): Rename section (was "LaTeX - Calendar"). Describe new package cal-html. - * emacs.texi (Top): Rename old node "LaTeX Calendar" to "Writing - Calendar Files." - -2006-10-23 Richard Stallman - - * abbrevs.texi (Expanding Abbrevs): Expansion happens only when - Abbrev mode is enabled. - -2006-10-16 Richard Stallman - - * emacs.texi: Update ISBN. - -2006-10-11 Kim F. Storm - - * emacs.texi (Acknowledgments): Use @dotless{i}. - -2006-10-08 Nick Roberts - - * building.texi (Breakpoints Buffer): Mention catchpoints. - -2006-10-08 Kim F. Storm - - * ack.texi (Acknowledgments): Update. - - * emacs.texi (Acknowledgments): Fix bad @/ form. - -2006-10-05 Kim F. Storm - - * emacs.texi (Acknowledgments): Add more contributors. - -2006-10-03 Richard Stallman - - * emacs.texi (Acknowledgments): Update version and edition. - -2006-10-01 Karl Berry - - * custom.texi (Customization Groups): Page break to keep example buffer - on one page. - -2006-09-30 Karl Berry - - * programs.texi (Basic Indent): @need to improve page break. - * text.texi: Rewording to improve page breaks, and use @LaTeX{}. - -2006-09-29 Glenn Morris - - * calendar.texi (Date Formats): Doc fix for european-calendar-style. - -2006-09-29 Karl Berry - - * windows.texi (Basic Window): Remove forced @break, no longer - desirable. - * frames.texi (Frame Commands), - * mark.texi (Marking Objects): Reword to avoid bad page break. - * display.texi (Auto Scrolling): Use @tie{} to avoid bad line break. - -2006-09-19 Richard Stallman - - * frames.texi (Dialog Boxes): Clean up wording: avoid passive, - stick to present tense. - -2006-09-18 Jan Djärv - - * frames.texi (Dialog Boxes): Rename x-use-old-gtk-file-dialog - to x-gtk-use-old-file-dialog. - (Dialog Boxes): Document x-gtk-file-dialog-help-text. - -2006-09-15 Jay Belanger - - * emacs.texi (GNU GENERAL PUBLIC LICENSE): - Change "Library Public License" to "Lesser Public License" - throughout. Use "yyyy" to represent year. - -2006-09-12 Reiner Steib - - * files.texi (Visiting): Add index entry "open file". - -2006-09-11 Richard Stallman - - * building.texi (Compilation Mode): Clarification. - (Grep Searching): Add xref to Compilation Mode. - -2006-09-08 Richard Stallman - - * search.texi (Search): Ref multi-file search commands here. - (Other Repeating Search): Not here. - -2006-08-28 Richard Stallman - - * windows.texi (Split Window): Update xref. - - * basic.texi (Continuation Lines): Update xref. - - * indent.texi (Tab Stops): Update xref. - - * emacs.texi (Top): Update subnode menu. - - * display.texi (Line Truncation, Displaying Boundaries): New nodes, - split out of Display Custom. - -2006-08-25 Kim F. Storm - - * display.texi (Display Custom): Add variables overline-margin - and x-underline-at-descent-line. - -2006-08-25 Richard Stallman - - * entering.texi (Exiting): Rewrite to give graphical displays - priority over text terminals. - - * search.texi (Incremental Search): Move index entries. - -2006-08-23 Chong Yidong - - * custom.texi (Init File): Reference Find Init to avoid "home - directory" confusion. - -2006-08-22 Nick Roberts - - * building.texi (Other GDB-UI Buffers): Describe how to edit - a value in the locals buffer. - -2006-08-21 Richard Stallman - - * search.texi (Basic Isearch): Add `isearch' index entry. - -2006-08-16 Richard Stallman - - * misc.texi (Saving Emacs Sessions): Clean up wording. - - * mark.texi (Marking Objects): Mention term "select all". - - * emacs.texi (Top): Update subnode menu. - - * help.texi (Help Mode): Move node up in file. - -2006-08-15 Nick Roberts - - * building.texi (Stack Buffer): Explain fringe arrow. - -2006-08-12 Eli Zaretskii - - * misc.texi (Saving Emacs Sessions): Clarify when desktop is restored - on startup. - -2006-08-11 Romain Francoise - - * ack.texi (Acknowledgments): Delete mention to zone-mode.el. - -2006-08-10 Sven Joachim (tiny change) - - * mule.texi (Recognize Coding, Text Coding): Fix typos. - -2006-08-10 Richard Stallman - - * text.texi (Format Faces): Substantial rewrites to deal - with face merging. Empty regions don't count. - Clarify face property inheritance. - -2006-08-08 Romain Francoise - - * dired.texi (Marks vs Flags): Fix typo reported by Ari Roponen - . - -2006-08-04 Eli Zaretskii - - * cmdargs.texi (Window Size X) <--geometry>: Only width and height - apply to all frames. - -2006-08-01 Richard Stallman - - * help.texi (Name Help): Add index entries for describe-variable. - -2006-08-01 Nick Roberts - - * building.texi (GDB Graphical Interface): Shorten node names. - (GDB-UI Layout): Use GDB-related. - (Other GDB-UI Buffers): Simplify English. - -2006-07-31 Richard Stallman - - * search.texi (Query Replace): Add xref for Dired's Q command. - -2006-07-31 Nick Roberts - - * building.texi (GDB commands in Fringe): Rename to... - (Source Buffers): ..this and move forward. Describe hollow arrow and - new option gdb-find-source-frame. - -2006-07-29 Richard Stallman - - * dired.texi (Operating on Files): Simplify previous change - and fix Texinfo usage. - -2006-07-29 Eli Zaretskii - - * dired.texi (Operating on Files): Add cross-references. State the - Unix commands that do similar things. - -2006-07-28 Richard Stallman - - * mark.texi (Transient Mark): Clarify that region never disappears - when Transient Mark mode is off, and not when it is on. - -2006-07-27 Richard Stallman - - * search.texi (Non-ASCII Isearch): Clarify. Mention C-q. - -2006-07-24 Richard Stallman - - * xresources.texi (GTK styles): Fix texinfo usage. - - * commands.texi (User Input): Explain why we teach keyboard cmds. - - * xresources.texi, xresmini.texi, search.texi, programs.texi: - * misc.texi, kmacro.texi, killing.texi, glossary.texi: - * fortran-xtra.texi, files.texi, emacs.texi, emacs-xtra.texi: - * doclicense.texi, display.texi, dired.texi, basic.texi: - * anti.texi, ack.texi: Move periods and commas inside quotes. - -2006-07-22 Eli Zaretskii - - * cmdargs.texi (General Variables): Document EMAIL. - -2006-07-21 Eli Zaretskii - - * frames.texi (Frame Commands): Mention that focus-follows-mouse - doesn't have effect on MS-Windows. - -2006-07-17 Richard Stallman - - * building.texi (Grep Searching): Explain about chaining grep commands. - -2006-07-10 Nick Roberts - - * killing.texi, mini.texi: Fix typos. - -2006-07-09 Chong Yidong - - * misc.texi (Invoking emacsclient): Document behavior when emacsclient - is invoked for multiple files. - -2006-07-08 Eli Zaretskii - - * msdog.texi (Windows Keyboard) [@iftex]: Add an @inforef to the - on-line manual for the rest of this node. - (Windows Mouse) : Include - unconditionally. - (Windows Processes) : Include unconditionally. - Improve wording. - (Windows Printing): Improve wording. - (Windows Misc) [@iftex]: Add an @inforef to the on-line manual for the - rest of this node. - -2006-07-05 Thien-Thi Nguyen - - * building.texi (Lisp Eval): Throughout, replace eval-current-buffer - with eval-buffer. - -2006-07-05 Nick Roberts - - * mule.texi (Coding Systems, Specify Coding): Link descriptions - of character translation. - -2006-07-04 Nick Roberts - - * rmail.texi (Remote Mailboxes): Add missing @code keyword. - -2006-07-03 Karl Berry - - * emacs.texi (\hbadness): Set to 6000 so we aren't bothered by - not-too-underfull hboxes in the TeX output. - * abbrevs.texi, buffers.texi, building.texi, calendar.texi, - * cmdargs.texi, custom.texi, dired.texi, macos.texi, - * maintaining.texi, misc.texi, mule.texi, programs.texi, rmail.texi, - * sending.texi, text.texi: Fix overfull/underfull boxes. - -2006-07-03 Romain Francoise - - * m-x.texi (M-x): Fix. - -2006-07-03 Richard Stallman - - * search.texi (Other Repeating Search): filename -> file name. - - * misc.texi (Narrowing): Minor cleanups. - - * files.texi (Visiting): filename -> file name. - - * emacs.texi (Top): Update subnode menus. - - * mule.texi (Coding Systems): Move char translation stuff here. - (Specify Coding, Output Coding): New nodes, out of Recognize Coding. - (Recognize Coding): Substantial local rewrites. - (International): Update menu. - - * display.texi (Auto Scrolling): New node, broken out of Scrolling. - (Scrolling): Substantial local rewrites. - (Display): Update menu and intro. - - * dired.texi: filename -> file name. - - * custom.texi (Safe File Variables): Texinfo usage fix. - -2006-07-03 Teodor Zlatanov - - * help.texi, m-x.texi: Lots of cleanups. - -2006-06-30 Eli Zaretskii - - * msdog.texi (ls in Lisp, Windows Keyboard, Windows Mouse) - (Windows Processes, Windows Misc): Shorten the printed version by - selectively conditioning less important portions by @ifnottex. - -2006-06-27 Richard Stallman - - * mini.texi (Minibuffer File): Minor cleanup. - -2006-06-25 Nick Roberts - - * frames.texi (XTerm Mouse): Rename to... - (Text-Only Mouse): ...this. Mention t-mouse-mode. - - * emacs.texi (Top): Use new node name. - -2006-06-24 Eli Zaretskii - - * emacs.texi (Top): Update the detailed menu according to changes in - msdog.texi. - - * msdog.texi (Windows Keyboard): New section. - (Windows Mouse): New section. - (Windows System Menu): Remove section (text merged with "Windows - Keyboard"). - (Windows Misc): New section. - - * dired.texi (Dired Enter): Refer to msdog.texi for ls-lisp emulation. - - * msdog.texi (ls in Lisp): New section. - - * files.texi (Visiting): Document case-insensitive wildcard matching - under find-file-wildcards. - -2006-06-16 YAMAMOTO Mitsuharu - - * macos.texi (Mac Input): Add description of mac-function-modifier. - Now Unicode keyboard layouts work. - -2006-06-10 Richard Stallman - - * mule.texi (Recognize Coding): Clarify previous change. - -2006-06-09 Kenichi Handa - - * mule.texi (Recognize Coding): Describe the convention of "CODING!" - notation. - -2006-06-07 Kevin Ryde - - * mule.texi (Coding Systems): Footnote xref "MS-DOS and MULE" in main - manual for @ifnottex, but in emacs-extra for @iftex. - - * cmdargs.texi (General Variables): Fix smtpmail xref. - -2006-05-29 Stefan Monnier - - * programs.texi (Comment Commands): - * custom.texi (Specifying File Variables): - Use ;; instead of ;;; to better follow coding conventions. - -2006-06-07 Nick Roberts - - * building.texi (Watch Expressions): Move node to end. - (GDB Graphical Interface): Move description of clicks in fringe... - (GDB commands in the Fringe): ...to here. New node. - -2006-06-05 Romain Francoise - - * xresmini.texi (GTK resources): Fix various typos. - -2006-06-05 Nick Roberts - - * building.texi (GDB Graphical Interface): Update bindings. - (Commands of GUD): Add gud-print. Remove gud-run. - Restate availability more generally. - -2006-06-03 Teodor Zlatanov - - * mini.texi: Lots of cleanups. - -2006-06-01 Luc Teirlinck - - * misc.texi (Shell History Copying): Update descriptions of `C-c RET' - and Mouse-2. - -2006-06-01 Jan Djärv - - * screen.texi (Menu Bar): Change menu-bar-start to menu-bar-open. - -2006-05-31 Richard Stallman - - * basic.texi (Moving Point): Fix previous change. - -2006-05-29 Jan Djärv - - * screen.texi (Menu Bar): F10 for Gtk+/Lesstif/Lucid menus. - -2006-05-28 Teodor Zlatanov - - * basic.texi: Many simplifications and improvements in wording. - -2006-05-26 Nick Roberts - - * anti.texi (Antinews): Create a node for gdb-ui. - -2006-05-22 Reiner Steib - - * frames.texi (Menu Bars, Tool Bars): Add index entries. - -2006-05-20 Richard Stallman - - * dired.texi (Dired Navigation): dired-goto-file is now j. - -2006-05-20 Eli Zaretskii - - * mule.texi (Coding Systems): Mention the undecided-* coding systems - and their aliases. - - * msdog.texi (Windows Printing): Mention non-support of plain text - printing with some el-cheapo printers, and suggest a workaround. - -2006-05-20 Kevin Ryde - - * text.texi (TeX Print): tex-dvi-view-command has a default value, - remove the bit saying you must set it. - -2006-05-19 Luc Teirlinck - - * trouble.texi (Checklist): - * text.texi (Text, Auto Fill, Text Mode): - * search.texi (Nonincremental Search): - * rmail.texi (Rmail Labels): - * mule.texi (Input Methods, Multibyte Conversion): - * misc.texi (Gnus, Where to Look, PostScript): - * maintaining.texi (Create Tags Table): - * indent.texi (Indentation Commands): - * fixit.texi (Spelling): - * emacs.texi (Copying): - * custom.texi (Init File): ifinfo -> ifnottex. - -2006-05-17 Richard Stallman - - * files.texi (Diff Mode): Mention C-x `. - -2006-05-08 Richard Stallman - - * custom.texi (Disabling): Textual cleanups. - -2006-05-12 Glenn Morris - - * calendar.texi (Displaying the Diary, Format of Diary File): - Refer to diary-view-entries, diary-list-entries, - diary-show-all-entries rather than obsolete aliases. - -2006-05-12 Eli Zaretskii - - * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) - (Displaying the Diary, Special Diary Entries, Importing Diary): - * building.texi (Compilation Shell): - * buffers.texi (Several Buffers) [iftex]: Replace @xref's to - emacs-xtra with @inforef's. - - * files.texi (Visiting): Fix wording. - - * mule.texi (Coding Systems, Text Coding): More indexing. - Mention that C-x RET f can set eol conversion. - -2006-05-07 Jan Djärv - - * xresmini.texi (GTK resources): Insert GTK description. - - * xresources.texi (GTK resources): metafont should be menufont. - -2006-05-06 Michael Albinus - - * mini.texi (Completion Options): Completion of remote files' - method, user name and host name is active only in partial - completion mode. - -2006-05-06 Eli Zaretskii - - * makefile.w32-in (emacs.dvi): - * Makefile.in (emacs.dvi): Add xresmini.texi. - - * xresmini.texi (Table of Resources): Remove xref to non-existent - node "LessTif Resources". - - * msdog.texi (Microsoft Windows): - * calendar.texi (Calendar/Diary, Displaying the Diary) - (Special Diary Entries, Importing Diary, Holidays): - * programs.texi (Program Modes): - * text.texi (Text): - * buffers.texi (Several Buffers): - * files.texi (Comparing Files): Fix cross-references to emacs-xtra. - -2006-05-06 Eli Zaretskii - - The following changes merge the emacs-xtra manual into the main - manual, but only for on-line version of the manual. - - * vc2-xtra.texi (Version Backups, Local Version Control) - (Making Snapshots, Change Logs and VC, Version Headers) - (Customizing VC, CVS Options) [ifnottex]: Conditional xref's for - on-line manual. - - * vc1-xtra.texi (VC Dired Mode) [ifnottex]: Conditional xref's - for on-line manual. - - * msdog-xtra.texi (MS-DOS, MS-DOS Keyboard, MS-DOS Mouse) - (MS-DOS Display, MS-DOS File Names, MS-DOS Printing) - (MS-DOS and MULE, MS-DOS Processes) [ifnottex]: Conditional xref's - for on-line manual. - - * fortran-xtra.texi (Fortran, Fortran Autofill) - (Fortran Autofill, Fortran Abbrev) [ifnottex]: Conditional xref's - for on-line manual. - - * picture-xtra.texi (Basic Picture, Rectangles in Picture) [ifnottex]: - Conditional xref's for on-line manual. - - * emerge-xtra.texi (Emerge, Overview of Emerge) - (Fine Points of Emerge) [ifnottex]: Conditional xref's for on-line - manual. - - * Makefile.in (INFO_TARGETS): Remove ../info/emacs-xtra. - (EMACS_XTRA): New variable, lists the new *-xtra.texi files. - (EMACSSOURCES): Use EMACS_XTRA. - (../info/emacs-xtra): Remove. - (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. - - * makefile.w32-in (INFO_TARGETS): Remove $(infodir)/emacs-xtra. - (EMACS_XTRA): New variable, lists the new *-xtra.texi files. - (EMACSSOURCES): Use EMACS_XTRA. - ($(infodir)/emacs-xtra): Remove. - (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. - - * trouble.texi (Quitting): - * text.texi (Text): - * programs.texi (Program Modes): - * msdog.texi (Microsoft Windows): - * frames.texi (Frames): - * files.texi (Backup, Version Control, VC Concepts) - (Types of Log File, Advanced C-x v v, Log Buffer, Old Versions) - (Registering, VC Status, VC Undo, Multi-User Branching) - (Comparing Files): - * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) - (Displaying the Diary, Special Diary Entries, Importing Diary): - * buffers.texi (Several Buffers): Replace inforef to emacs-xtra by - conditional xref's, depending on @iftex/@ifnottex. - - * msdog.texi (Microsoft Windows) [ifnottex]: Add menu entry for - "MS-DOS". @include msdog-xtra.texi. - - * programs.texi (Programs) [ifnottex]: Add menu entry for "Fortran". - [ifnottex]: @include fortran-xtra.texi. - - * files.texi (Secondary VC Commands) [ifnottex]: Add menu entries - for vc-xtra.texi subsections. - (VC Undo) [ifnottex]: @include vc1-xtra.texi and @lowersections it. - (Multi-User Branching) [ifnottex]: @include vc2-xtra.texi. - - * sending.texi (Sending Mail): A @node line without explicit Prev, - Next, and Up links. - - * abbrevs.texi (Abbrevs): A @node line without explicit Prev, - Next, and Up links. - - * emacs.texi (Top) [ifnottex]: Add menu entries for "Picture Mode" - and its sections. @include picture-xtra.texi. - - * maintaining.texi (Maintaining) [ifnottex]: Add menu entry for - "Emerge". - (List Tags) [ifnottex]: @include emerge-xtra.texi. - - * cal-xtra.texi (Daylight Savings): Remove this node: it is an - exact duplicate of its name-sake in calendar.texi. - - * calendar.texi (Calendar/Diary) [ifnottex]: Add menu item for - "Advanced Calendar/Diary Usage". - (Time Intervals) [ifnottex]: @include cal-xtra.texi. - - * dired.texi (Subdirectories in Dired) [ifnottex]: @include - dired-xtra.texi. - (Dired) [ifnottex]: Add menu entry for "Subdir Switches". - - * files.texi (Reverting) [ifnottex]: @include arevert-xtra.texi. - (Files) [ifnottex]: Add menu entry for Autorevert. - - * emacs-xtra.texi (Introduction): Reword to make consistent with - printed version only. - : Remove the body of all chapters and move them to the - new *-xtra.texi files. Use @raisesections and @lowersections to - convert sections to chapters etc. - - * msdog-xtra.texi: - * fortran-xtra.texi: - * vc-xtra.texi: - * vc1-xtra.texi: - * vc2-xtra.texi: - * emerge-xtra.texi: - * cal-xtra.texi: - * dired-xtra.texi: - * arevert-xtra.texi: New files, with text from respective chapters - of emacs-xtra.texi. Convert each @chapter into @section, @section - into @subsection, etc. - - * emacs-xtra.texi (MS-DOS): Rename from "MS-DOG". All references - updated. - - * msdog.texi (Microsoft Windows): Rename from "Emacs and Microsoft - Windows". All references updated. - -2006-05-06 YAMAMOTO Mitsuharu - - * macos.texi (Mac Input): Mention input from Character Palette. - (Mac Font Specs): Fix typo. - -2006-05-05 Richard Stallman - - * files.texi (Diff Mode): Minor cleanup. - -2006-05-05 Karl Berry - - * emacs.texi: Call @fonttextsize 10, inside @tex to avoid - errors from the current release of makeinfo (4.8). - * help.texi (Library Keywords): Change widest word in multitable - template from `emulations' to `convenience'. (Not sure if this is - related to the font change.) - -2006-05-05 Eli Zaretskii - - * files.texi (File Names): Add a footnote about limited support of - ~USER on MS-Windows. - - * cmdargs.texi (Initial Options): Add a footnote about limited - support of ~USER on MS-Windows. - -2006-05-03 Richard Stallman - - * files.texi (Diff Mode): Node moved here. - (Comparing Files): Delete what duplicates new node. - (Files): Put Diff Mode in menu. - - * misc.texi (Diff Mode): Move to files.texi. - - * emacs.texi (Top): Update menu for Diff Mode. - - * trouble.texi (Emergency Escape): Simplify. - - * emacs.texi (Top): Minor clarification. - -2006-05-03 Teodor Zlatanov - - * commands.texi, entering.texi, screen.texi: Many simplifications. - -2006-05-03 Richard Stallman - - * commands.texi (Text Characters): Delete paragraph about unibyte - non-ASCII printing chars. - - * killing.texi (Killing): Say "graphical displays". - * display.texi: Say "graphical displays". - - * cmdargs.texi (Misc X): Say "graphical displays". - -2006-05-01 Richard Stallman - - * emacs.texi (Top): Add Diff Mode to menu. - -2006-05-01 Aaron S. Hawley - - * misc.texi (Diff Mode): New node. - -2006-05-01 YAMAMOTO Mitsuharu - - * macos.texi (Mac International): Now Carbon Emacs has ATSUI support. - (Mac Environment Variables): Shorten example line. - (Mac Font Specs): Shorten lisp lines. Add descriptions for ATSUI. - -2006-05-01 Nick Roberts - - * building.texi (GUD Customization): Describe cases %d and %c. - Update description for %e. - -2006-04-30 Glenn Morris - - * calendar.texi (LaTeX Calendar): Mention cal-tex-preamble-extra. - -2006-04-29 Dan Nicolaescu - - * custom.texi (Examining): Update C-h v output example. - -2006-04-29 Kim F. Storm - - * building.texi (Grep Searching): Add lgrep and rgrep. - -2006-04-23 Richard Stallman - - * emacs.texi [TeX]: Use xresmini.texi instead of xresources.texi. - - * xresmini.texi: New file. - - * xresources.texi (Face Resources): Split table into font resources - and the rest. Combine similar attributes for brevity. - -2006-04-21 Eli Zaretskii - - * emacs-xtra.texi (MS-DOS File Names): Remove section about - backslashes and case-insensitivity in file names (moved to the - main manual). - (MS-DOS Printing): Move most of the text to the main manual. - - * msdog.texi (Windows Files, Windows HOME, MS-Windows Printing): - New nodes. - (Windows Processes, Windows System Menu): Add index entries and - fix wording. - -2006-04-18 J.D. Smith - - * misc.texi (Shell Ring): Add notes on saved input when - navigating off the end of the history list. - -2006-04-18 Chong Yidong - - * misc.texi (Shell Options): Correct default value of - comint-scroll-show-maximum-output. - -2006-04-18 Nick Roberts - - * building.texi (Watch Expressions): Update. - -2006-04-12 Richard Stallman - - * search.texi: Clean up previous change. - -2006-04-12 Eli Zaretskii - - * search.texi (Regexp Backslash, Regexp Replace): Add index - entries for ``back reference'' and mention the term itself in the - text. - -2006-04-11 Richard Stallman - - * custom.texi (Safe File Variables): - Document enable-local-variables = :safe. - -2006-04-11 Karl Berry - - * emacs-xtra.texi, emacs.texi (Dired under VC, VC Dired Commands) - (Remote Repositories, Version Backups, Local Version Control) - (Snapshots, Making and Using Snapshots, Snapshot Caveats) - (Miscellaneous Commands and Features of VC, Change Logs and VC) - (Renaming VC Work Files and Master Files) - (Inserting Version Control Headers, Customizing VC, General Options) - (Options for RCS and SCCS, Options specific for CVS): Move all - these nodes to emacs-xtra.texi, for brevity. - * cmdargs.texi, files.texi: Change cross-references. - -2006-04-11 J.D. Smith - - * files.texi (Old Versions): Update description of vc-annotate's - use of color to indicate date ranges. - -2006-04-09 Kevin Ryde - - * sending.texi (Mail Sending): In send-mail-function @pxref smtpmail, - put info and printed manual names the right way around. - -2006-04-09 Karl Berry - - * msdog.texi, emacs-xtra.texi: Move all the MS-DOS material to - emacs-xtra.texi, leaving only MS Windows information. - * building.texi, emacs.texi, frames.texi, gnu.texi, macos.texi, - * msdog.texi, mule.texi, trouble.texi: Change cross-references and - node names. - - * emacs.texi: Move @summarycontents and @contents to the beginning - of the file. - -2006-04-08 Kevin Ryde - - * text.texi (Fill Commands): fill-nobreak-predicate is now a hook. - -2006-04-07 Richard Stallman - - * programs.texi (Comments, Comment Commands, Options for Comments) - (Multi-Line Comments): "Align", not "indent". - (Basic Indent): C-j deletes trailing whitespace before the newline. - -2006-04-06 Richard Stallman - - * programs.texi (Basic Indent): Clarify relationship of C-j to TAB. - -2006-04-06 Eli Zaretskii - - * killing.texi (Rectangles): Add index entry for marking a rectangle. - -2006-04-05 Richard Stallman - - * emacs.texi (Top): Update subnode menu. - - * trouble.texi (Unasked-for Search): Node deleted. - (Lossage): Delete from menu. - -2006-04-04 Richard Stallman - - * trouble.texi: Various cleanups. - (Checklist): Don't bother saying how to snail a bug report. - (Emergency Escape): Much rewriting. - (After a Crash): Rename the core dump immediately. - (Total Frustration): Call it a psychotherapist. - (Bug Criteria): Avoid "illegal instruction". - (Sending Patches): We always put the contributor's name in. - - * misc.texi (Thumbnails): Minor correction. - -2006-04-03 Richard Stallman - - * misc.texi (Thumbnails): Minor cleanup. - -2006-04-02 Karl Berry - - * sending.texi (Mail Sending): pxref to Top needs five args. - - * texinfo.tex: Update to current version (2006-03-21.13). - -2006-03-31 Richard Stallman - - * emacs.texi (Top): Update subnode menu. - - * help.texi (Help Mode): Cleanup. - - * dired.texi: Many cleanups. - (Dired Deletion): Describe dired-recursive-deletes. - (Operating on Files): dired-create-directory moved. - (Misc Dired Features): Move to here. - (Tumme): Node moved to misc.texi. - - * custom.texi: Many cleanups. - (Minor Modes): Don't mention ISO Accents Mode. - (Examining): Update C-h v output example. - (Hooks): Add index and xref for add-hook. - (Locals): Delete list of vars that are always per-buffer. Rearrange. - (Local Keymaps): Don't mention lisp-mode-map, c-mode-map. - - * misc.texi: Many cleanups. - (beginning): Add to summary of topics. - (Shell): Put eshell xref at the end. Remove eshell from table. - (Thumbnails): New node. - -2006-03-28 Eli Zaretskii - - * files.texi (File Name Cache): Make it clear that the cache is - not persistent. - -2006-03-25 Karl Berry - - * emacs-xtra.texi, emacs.texi, gnu.texi: - (1) use @copyright{} instead of (C) in typeset text; - (2) do not indent copyright year list (or anything else). - -2006-03-21 Juanma Barranquero - - * files.texi (VC Dired Mode): Remove misplaced brackets. - -2006-03-21 Andre Spiegel - - * files.texi: Various updates and clarifications in the VC chapter. - -2006-03-19 Luc Teirlinck - - * help.texi (Help Mode): Document "C-c C-c". - -2006-03-16 Luc Teirlinck - - * emacs-xtra.texi (Top): Avoid ugly continuation line in - menu in the standalone Info reader. - -2006-03-15 Chong Yidong - - * emacs-xtra.texi (Emerge, Picture Mode, Fortran): New chapters, - moved here from Emacs manual. - - * programs.texi (Fortran): Section moved to emacs-xtra. - (Program Modes): Xref to Fortran in emacs-xtra. - - * maintaining.texi (Emerge): Move to emacs-xtra. - * files.texi (Comparing Files): Xref to Emerge in emacs-xtra. - - * picture.texi: File deleted. - * Makefile.in: - * makefile.w32-in: Remove picture.texi. - - * text.texi (Text): Xref to Picture Mode in emacs-xtra. - * abbrevs.texi (Abbrevs): - * sending.texi (Sending Mail): Picture node removed. - - * emacs.texi (Top): Update node listings. - -2006-03-12 Richard Stallman - - * calendar.texi: Various cleanups. - -2006-03-11 Luc Teirlinck - - * search.texi (Regexps): Use @samp for regexp that is not in Lisp - syntax. - -2006-03-08 Luc Teirlinck - - * search.texi (Regexps): More accurately describe which characters - are special in which situations. Recommend _not_ to quote `]' or - `-' when they are not special. - -2006-02-28 Andre Spiegel - - * files.texi (Old Versions): Clarify operation of C-x v =. - -2006-02-21 Nick Roberts - - * building.texi (Watch Expressions): Update and describe - gdb-speedbar-auto-raise. - -2006-02-19 Richard M. Stallman - - * emacs.texi: Use @smallbook. - (Top): Update ref to Emacs paper, delete ref to Cookbook. - Update subnode menu. - - * building.texi (Lisp Interaction): Minor addition. - -2006-02-18 Nick Roberts - - * building.texi (Watch Expressions): Update and be more precise. - -2006-02-15 Francesco Potortì - - * maintaining.texi (Create Tags Table): Explain why the - exception when etags writes to files under the /dev tree. - -2006-02-14 Richard M. Stallman - - * custom.texi (Safe File Variables): Lots of clarification. - Renamed from Unsafe File Variables. - -2006-02-14 Chong Yidong - - * custom.texi (Unsafe File Variables): File variable confirmation - assumed denied in batch mode. - -2006-02-14 Richard M. Stallman - - * building.texi (GDB User Interface Layout): Don't say `inferior' - for program being debugged. - -2006-02-15 Nick Roberts - - * building.texi (GDB Graphical Interface): - Replace gdb-use-inferior-io-buffer with gdb-use-separate-io-buffer. - -2006-02-13 Chong Yidong - - * custom.texi (Specifying File Variables, Unsafe File Variables): - New nodes, split from File Variables. Document new file local - variable behavior. - -2006-02-13 YAMAMOTO Mitsuharu - - * display.texi (Standard Faces): - * files.texi (Visiting): - * frames.texi (Clipboard): - * glossary.texi (Glossary) : - * xresources.texi (X Resources): Mention Mac OS port. - -2006-02-12 Richard M. Stallman - - * building.texi (Building): Clarify topic in intro. - - * maintaining.texi (Maintaining): Change title; clarify topic. - Delete duplicate index entries. - - * building.texi (Other GDB User Interface Buffers): Clarifications. - - * text.texi (Cell Commands): Clarifications. - - * programs.texi (Defuns): Delete duplicate explanation of - left-margin paren convention. - (Hungry Delete): Minor cleanup. - -2006-02-11 Mathias Dahl - - * dired.texi (Tumme): More tumme documentation. - -2006-02-11 Alan Mackenzie - - * programs.texi ("Hungry Delete"): Correct the appellation of the - backspace and delete keys to @kbd{DEL} and @kbd{DELETE}. - -2006-02-11 Mathias Dahl - - * dired.texi (Tumme): Fix small bug. - -2006-02-10 YAMAMOTO Mitsuharu - - * macos.texi (Mac International): Rename "fontset-mac" to - "fontset-standard". - -2006-02-09 Mathias Dahl - - * dired.texi (Tumme): Basic documentation for Tumme added. - -2006-02-07 Luc Teirlinck - - * mule.texi (International): - * programs.texi (Basic Indent): Fix typos. - - * custom.texi (Minor Modes): - * display.texi (Text Display): - * commands.texi (Text Characters): Update xrefs. - -2006-02-07 Richard M. Stallman - - * emacs.texi (Top): Update subnode menu. - Update info on old Emacs papers. - (Intro): "Graphical display", not window system. - - * xresources.texi (GTK styles): Minor clarifications. - - * trouble.texi: "Graphical display", not window system. - (Stuck Recursive): Minor clarification. - - * text.texi: Minor clarifications. - (Sentences): Explain why two-space convention is better. - Explain sentence-end-without-period here. - (Fill Commands): Not here. - (Refill): Node moved down. - (Filling): Update menu. - (Table Creation, Cell Justification, Column Commands): Clarify. - - * sending.texi: Minor clarifications. - - * search.texi (Regexp Backslash): Clarification. - - * rmail.texi: Minor cleanups. - (Rmail): Delete digression about `rmail-mode'. - (Rmail Inbox): Delete false advice wrt rmail-primary-inbox-list. - (Rmail Files): Mention C-u M-x rmail. - (Rmail Reply): Mention References. - (Rmail Display): Mention rmail-nonignored-headers. - - * programs.texi: Minor cleanups. - (Comment Commands): Mention momentary Transient Mark mode. - (Matching): Be more specific about customizing show-paren-mode. - (Info Lookup): Don't list the modes that support C-h S. - Just say what it does in an unsupported mode. - (Man Page): Delete excessive info on customizing woman. - (Motion in C): Don't mention c-for/backward-into-nomenclature. - - * abbrevs.texi: Minor clarifications. - (Dabbrev Customization): Talk about "dynamic abbrev expansion", - not "dynamic abbrevs" as if they were a kind of abbrev. - - * picture.texi (Picture): Minor cleanup. - - * mule.texi (Communication Coding): Say "other applications". - (Fontsets): Not specific to X. Add xref to X Resources. - (Unibyte Mode): Rename from Single-Byte Character Support. - "Graphical display", not window system. - (International): Update menu. - - * maintaining.texi (Format of ChangeLog): - New node, split out from ChangeLog. - (ChangeLog): Clarifications in the remaining text. - (Create Tags Table, Etags Regexps, Select Tags Table): Cleanups. - (Find Tag): Add @w. - (Tags Search): Explain tag table order here. Simplify grep ref. - (List Tags): tags-tag-face is a variable, not a face. - (Emerge): Cleanups. - - * kmacro.texi (Keyboard Macro Counter): Rewrite for clarity. - (Keyboard Macros): Avoid "the user". - - * killing.texi: "Graphical display", not window system. - - * help.texi (Help Echo): "Graphical display", not window system. - - * glossary.texi: Say "you", not "the user". Say "graphical display". - - * frames.texi: Minor cleanups. "Graphical display", not window system. - - * files.texi (Visiting): Make drag-and-drop not X-specific. - - * custom.texi: Minor cleanups. "Graphical display", not window system. - - * cmdargs.texi: Minor cleanups. - - * building.texi (Compilation): Move and split kill-compilation para. - Add para about multiple compilers. - (Compilation Mode): Commands also available in grep mode and others. - Mention C-u C-x ` more tutorially. Clarify C-x `. - (Compilation Shell): Clarify. Put Bash example first. - (Grep Searching): Minor cleanups; add @w. - (Debuggers): Minor cleanups. - (Starting GUD): Make GDB xgraphical mode issue clearer. - (Debugger Operation): Lots of clarifications including - GDB tooltip side-effect issue. - (Commands of GUD): Clarify. - (GUD Customization): Add bashdb-mode-hook. - (GDB Graphical Interface): Rewrite for clarity. - (GDB User Interface Layout): Rewrite for clarity. - (Stack Buffer, Watch Expressions): Likewise. - (Other GDB User Interface Buffers): Cleanups. - (Lisp Libraries, External Lisp): Cleanup. - - * basic.texi (Position Info): "Graphical displays", rather than - window systems. - - * anti.texi: Minor cleanup. - -2006-02-03 Eli Zaretskii - - * custom.texi (Init File, Find Init): Add cross-references to - where $HOME is described. - -2006-02-01 Luc Teirlinck - - * frames.texi (Frame Parameters): Remove @item for S-Mouse-1; it - is not inside the @table. - - * emacs.texi (Top): Correct node name. - - * files.texi (File Names): Fix @xref. - (Reverting): Fix typo. - - * mule.texi (International): Correct node name. - - * kmacro.texi (Save Keyboard Macro): Add missing @kbd to @table. - -2006-02-01 Richard M. Stallman - - * emacs.texi (Top): Update subnode menu. - - * mule.texi: Minor clarifications. - Reduce the specific references to X Windows. - Refer to "graphical" terminals, rather than window systems. - (Text Coding): Rename from Specify Coding. - (Communication Coding, File Name Coding, Terminal Coding): - New nodes split out from Text Coding. - - * kmacro.texi: Minor clarifications. - (Keyboard Macro Ring): Comment out some excessive commands. - (Basic Keyboard Macro): Split up the table, putting part in each node. - - * major.texi: Minor clarifications. - - * misc.texi (Single Shell, Interactive Shell): Fix xrefs. - - * windows.texi: Minor clarifications. - (Change Window): Don't describe mode-line mouse cmds here. - Add xref to Mode Line Mouse. - - * msdog.texi (Text and Binary, MS-DOS and MULE): Fix xrefs. - - * macos.texi (Mac International): Fix xref. - - * indent.texi: Minor clarifications. - - * frames.texi: Minor clarifications. - Reduce the specific references to X Windows. - Refer to "graphical" terminals, rather than window systems. - (Frame Parameters): Don't mention commands like - set-foreground-color. Just say to customize a face. - (Drag and Drop): Lisp-level stuff moved to Emacs Lisp manual. - - * files.texi: Minor clarifications. - (Numbered Backups): New node, split out from Backup Names. - - * display.texi (Font Lock): C mode no longer depends on (-in-col-0. - - * cmdargs.texi (General Variables): Fix xref. - - * buffers.texi: Minor clarifications. - -2006-01-31 Richard M. Stallman - - * display.texi (Scrolling, Horizontal Scrolling, Follow Mode): - Nodes moved to top. - - * display.texi: Minor clarifications. - (Display): Rearrange menu. - (Standard Faces): Mention query-replace face. - (Faces): Simplify. - (Font Lock): Simplify face customization info. - (Highlight Changes): Node merged into Highlight Interactively. - (Highlight Interactively): Much rewriting and cleanup. - (Optional Mode Line): Narrowed line number not good for goto-line. - Simplify face customization advice. - (Text Display): Mention use of escape-glyph face. - Move ctl-arrow and tab-width here. - (Display Custom): Move no-redraw-on-reenter to end of node. - - * search.texi: Minor clarifications. - (Isearch Scroll): Simplify. - (Other Repeating Search): Document multi-occur-in-matching-buffers. - - * regs.texi (Registers): Mention bookmarks here. - - * mark.texi: Minor clarifications. - (Selective Undo): Node deleted. - - * m-x.texi: Minor clarifications. - - * killing.texi: Minor clarifications. - Refer to "graphical" terminals, rather than window systems. - - * help.texi: Clarifications. - (Help): Don't describe C-h F and C-h K here. - (Key Help): Describe C-h K here. - (Name Help): Mention Emacs Lisp Intro. - Describe C-h F here. - (Misc Help): Mention C-h F and C-h K only briefly. - - * fixit.texi (Undo): New node, mostly copied from basic.texi. - Selective undo text merged in. - (Spelling): Mention Aspell along with Ispell. - - * emacs.texi (Top): Update subnode menus. - - * basic.texi (Basic Undo): Rename from Undo. Most of text - moved to new Undo node. - -2006-01-29 Chong Yidong - - * basic.texi (Continuation Lines, Inserting Text): - Mention longlines mode. - -2006-01-29 Richard M. Stallman - - * screen.texi: Minor cleanups. - (Screen): Clean up the intro paragraphs. - (Mode Line): Lots of rewriting. Handle frame-name better. - eol-mnemonic-... vars moved out. - - * emacs.texi (Top): Change menu item for MS-DOS node. - Update subnode menu. - - * msdog.texi (MS-DOS): Rewrite intro to explain how this - chapter relates to Windows. Title changed. - - * mini.texi: Minor cleanups. - - * mark.texi (Selective Undo): New node, text moved from basic.texi. - (Mark): Put it in the menu. - - * entering.texi: Minor cleanups. - - * emacs.texi (Top): Add xref to Mac chapter; explain Windows better. - (Intro): Refer to "graphical" terminals, rather than X. - - * display.texi (Display Custom): Add xref to Variables. - (Optional Mode Line): eol-mnemonic-... vars moved here. - - * commands.texi: Minor cleanups. Refer to "graphical" terminals, - rather than X. - - * basic.texi: Minor cleanups. - (Undo): selective-undo moved. - -2006-01-25 Luc Teirlinck - - * anti.texi (Antinews): Various corrections and additions. - -2006-01-23 Juri Linkov - - * custom.texi (Easy Customization, Customization Groups) - (Browsing Custom): Mention links along with buttons. - -2006-01-21 Eli Zaretskii - - * text.texi (TeX Print): Use @key for TAB. - - * kmacro.texi (Keyboard Macro Step-Edit): Use @key for TAB. - -2006-01-15 Sven Joachim (tiny change) - - * files.texi (File Aliases): Don't claim that usually separate - buffers are created for two file names that name the same data. - Mention additional situations where different names mean the same - file on disk. - -2006-01-19 Richard M. Stallman - - * killing.texi (Deletion): Upcase @key argument. - - * custom.texi (Custom Themes): Minor cleanup. - - * programs.texi (Hungry Delete): Upcase @key argument. - -2006-01-16 Juri Linkov - - * display.texi (Standard Faces): Add `mode-line-buffer-id'. - Move `mode-line-highlight' before `mode-line-buffer-id'. - -2006-01-14 Richard M. Stallman - - * basic.texi (Inserting Text): Minor cleanup. - -2006-01-11 Luc Teirlinck - - * custom.texi (Changing a Variable, Face Customization): - Update for changes in Custom menus. - -2006-01-05 YAMAMOTO Mitsuharu - - * macos.texi (Mac International): Undo last change. - -2006-01-02 Chong Yidong - - * custom.texi (Custom Themes): Describe the new - customize-create-theme interface. - -2005-12-30 Juri Linkov - - * basic.texi (Position Info): Update example. - -2005-12-27 Jan Djärv - - * frames.texi (Dialog Boxes): Add x-gtk-show-hidden-files. - -2005-12-24 Chong Yidong - - * custom.texi (Custom Themes): `load-theme' always loads. - -2005-12-23 Juri Linkov - - * display.texi (Highlight Interactively): Use double space to - separate sentences. Replace C-p with M-p, and C-n with M-n. - -2005-12-22 Richard M. Stallman - - * custom.texi (Easy Customization and subnodes): - Replace "active field" with "button". - Use "user option" only for variables. - Use "setting" for variable-or-face. - -2005-12-22 Luc Teirlinck - - * buffers.texi (Select Buffer): Change order in table to make - "Similar" refer to the correct item. - (Indirect Buffers): Minor rewording. - -2005-12-20 Juri Linkov - - * files.texi (VC Status): Put P and N near p and n. - -2005-12-19 Richard M. Stallman - - * programs.texi (Electric C): Delete the info about newline control. - (Other C Commands): Minor cleanup. - (Left Margin Paren): Minor cleanup. - -2005-12-19 Luc Teirlinck - - * custom.texi (Easy Customization): Add "Browsing Custom" to menu. - (Customization Groups): Delete text moved to "Browsing Custom". - (Browsing Custom): New node. - (Specific Customization): Clarify which commands only work for - loaded options. - -2005-12-18 Bill Wohler - - * frames.texi (Tool Bars): Shorten text of previous change. - -2005-12-18 Aaron S. Hawley - - * files.texi (VC Status): Document log-view mode. - -2005-12-18 Bill Wohler - - * frames.texi (Tool Bars): Mention that you can turn off tool bars - permanently via the customize interface. - -2005-12-16 Ralf Angeli - - * killing.texi (Killing by Lines): Document `kill-whole-line' - function. - -2005-12-16 Lőrentey Károly - - * buffers.texi (Select Buffer): Change `prev-buffer' to - `previous-buffer'. Indicate that these functions use a frame - local buffer list. - -2005-12-12 Richard M. Stallman - - * custom.texi (Easy Customization): Change menu comment. - (Prefix Keymaps): Fix spelling of Control-X-prefix. - - * help.texi (Apropos): Rewrite. Talk about "apropos patterns". - (Help): Among the Apropos commands, describe only C-h a here. - -2005-12-11 Richard M. Stallman - - * programs.texi (Options for Comments): Comment-end starts with space. - - * glossary.texi (Glossary): Minor cleanup. - - * files.texi (Old Versions): Use @table. - -2005-12-10 David Koppelman - - * display.texi (Highlight Interactively): Include - global-hi-lock-mode. Add miscellaneous details and elaborations. - -2005-12-09 Richard M. Stallman - - * display.texi (Font Lock): Delete the Global FL menu item. - -2005-12-09 Luc Teirlinck - - * custom.texi (Minibuffer Maps): Mention the maps for file name - completion. - -2005-12-09 Kim F. Storm - - * killing.texi (CUA Bindings): Describe how to use C-x and C-c as - prefix keys even when mark is active. Describe that RET moves - cursor to next corner in rectangle; clarify insert around rectangle. - -2005-12-08 Luc Teirlinck - - * custom.texi (Customization): Use xref to elisp manual for - non-TeX output. - (Minor Modes): Update. - (Customization Groups, Changing a Variable, Face Customization): - Update for new appearance of Custom buffers. - (Changing a Variable): `custom-buffer-done-function' has been - replaced by `custom-buffer-done-kill'. - (Specific Customization): In the `customize-group' buffer, a - subgroup's contents are not "hidden". They are not included at - all. They have no [Show] button. - (Mouse Buttons): Add pxref to description of mouse event lists in - Elisp manual. Add `menu-bar' and `header-line' dummy prefix keys. - (Find Init): Emacs now looks for ~/.emacs.d/init.el instead of - ~/.emacs.d/.emacs, if it can not find ~/.emacs(.el). - -2005-12-08 Richard M. Stallman - - * mini.texi (Completion Commands, Completion): - In file name input, SPC does not do completion. - -2005-12-08 Nick Roberts - - * building.texi (GDB Graphical Interface): Explain screen size - setting. - (Other GDB User Interface Buffers): Describe features specific to - GDB 6.4. - -2005-12-01 Nick Roberts - - * building.texi (GDB User Interface Layout): Describe how to - kill associated buffers. - (Breakpoints Buffer): Use D instead of d for gdb-delete-breakpoint. - (Watch Expressions): Be more precise. - (Other GDB User Interface Buffers): Describe how to change a - register value. - -2005-11-24 YAMAMOTO Mitsuharu - - * macos.texi (Mac Input): Remove description of - mac-command-key-is-meta. Add descriptions of - mac-control-modifier, mac-command-modifier, and - mac-option-modifier. - (Mac International): Fix description of conversion of clipboard data. - (Mac Font Specs): Add example of font customization by face attributes. - -2005-11-22 Nick Roberts - - * building.texi (Watch Expressions): Expand description. - (Other GDB User Interface Buffers): Describe local map for - gud-watch. - -2005-11-21 Chong Yidong - - * display.texi (Font Lock): Font lock is enabled by default now. - -2005-11-20 Juri Linkov - - * basic.texi (Position Info): Update examples of the output. - Remove the fact that examples are produced in the TeXinfo buffer, - because in the Info reader users will get a different output from - `C-x ='. - - * building.texi (Compilation Mode): Remove paragraph duplicated - from the node `Compilation'. Add `compilation-skip-threshold'. - - * display.texi (Font Lock): Suggest more user-friendly method of - finding all Font Lock faces (M-x customize-group RET font-lock-faces). - -2005-11-18 Richard M. Stallman - - * files.texi (Registering): Mention @@ in mode line. - - * mini.texi (Minibuffer File): Clarify previous change. Add @findex. - -2005-11-08 Aaron S. Hawley - - * files.texi (Renaming and VC): Some back-ends don't - handle renaming. - -2005-11-17 Juri Linkov - - * emacs.texi (Top): - * display.texi (Highlight Interactively): Put this font-lock based - mode near Font Lock node. - -2005-11-16 Chong Yidong - - * ack.texi (Acknowledgments): Acknowledge Andrew Zhilin for Emacs - icons. - -2005-11-12 Kim F. Storm - - * help.texi (Help): Fix C-h a entry. Add C-h d entry. - (Help Summary): Add C-h d and C-h e. - (Apropos): Clarify that all apropos commands may search for either - list of words or a regexp. Add C-h d for apropos-documentation. - Describe apropos-documentation-sort-by-scores user option. - -2005-11-09 Luc Teirlinck - - * killing.texi (CUA Bindings): Add @section. - -2005-11-10 Kim F. Storm - - * emacs.texi (Top): Add CUA Bindings entry to menu. - - * killing.texi (CUA Bindings): New node. Moved here from - misc.texi and extended with info on rectangle commands and - rectangle highlighting, interface to registers, and the global - mark feature. - - * misc.texi (Emulation): Move CUA bindings item to killing.texi. - - * regs.texi: Prev link points to CUA Bindings node. - -2005-11-07 Luc Teirlinck - - * help.texi (Help Echo): By default, help echos are only shown on - mouse-over, not on point-over. - -2005-11-04 Jérôme Marant - - * misc.texi (Shell Mode): Describe how to activate password echoing. - -2005-11-04 Romain Francoise - - * mark.texi (Mark Ring): Fix typo. - -2005-11-03 Richard M. Stallman - - * mark.texi (Mark Ring): Mention set-mark-command-repeat-pop. - -2005-11-01 Bill Wohler - - * help.texi (Help Mode): Fix typo. - -2005-11-01 Nick Roberts - - * building.texi (Other GDB User Interface Buffers): - Describe the command gdb-use-inferior-io-buffer. - -2005-10-31 Romain Francoise - - * files.texi (Compressed Files): Fix typo. - - * buffers.texi (Misc Buffer): Downcase `*shell*'. - - * windows.texi (Force Same Window): Likewise. - -2005-10-30 Bill Wohler - - * help.texi (Help Mode): URLs viewed with browse-url. - -2005-10-31 Nick Roberts - - * building.texi (GDB Graphical Interface): Don't reference - gdb-mouse-set-clear-breakpoint. Explain gdb-mouse-until - must stay in same frame. - -2005-10-29 Chong Yidong - - * custom.texi (Init File): Document ~/.emacs.d/init.el. - - * anti.texi (Antinews): Likewise. - -2005-10-28 Bill Wohler - - * help.texi (Help): Help mode now creates hyperlinks for URLs. - -2005-10-28 Richard M. Stallman - - * files.texi (Visiting): Explain how to enter ? in a file name. - - * trouble.texi (Memory Full): Mention !MEM FULL! in mode line. - -2005-10-25 Nick Roberts - - * building.texi (GDB Graphical Interface): - Describe gdb-mouse-until. - -2005-10-23 Richard M. Stallman - - * custom.texi (Init File): Recommend when to use site-start.el. - -2005-10-21 Juri Linkov - - * custom.texi (Examining): Mention accessing the old variable - value via M-n in set-variable. - -2005-10-18 Romain Francoise - - * files.texi (Version Systems): Capitalize GNU. - -2005-10-18 Nick Roberts - - * building.texi (Compilation Mode): Remove redundant paragraph. - (Watch Expressions): Remove paragraph to reflect code change. - -2005-10-16 Richard M. Stallman - - * building.texi (Compilation Mode, Compilation): Clarified. - -2005-10-15 Richard M. Stallman - - * misc.texi (Saving Emacs Sessions): Mention savehist library. - -2005-10-13 Kenichi Handa - - * basic.texi (Position Info): Fix previous change. - -2005-10-12 Jan Djärv - - * cmdargs.texi (Icons X): Fix typo. - -2005-10-12 Kenichi Handa - - * basic.texi (Position Info): Describe the case that Emacs shows - "part of display ...". - -2005-10-10 Jan Djärv - - * cmdargs.texi (Icons X): -nb => -nbi. - -2005-10-10 Chong Yidong - - * frames.texi (Speedbar): A couple more clarifications. - -2005-10-11 Nick Roberts - - * building.texi (GDB User Interface Layout): Improve diagram. - (Watch Expressions): Explain how to make speedbar global. - (Other GDB User Interface Buffers): Make references more precise. - -2005-10-09 Richard M. Stallman - - * frames.texi (Speedbar): Clarify the text. - -2005-10-09 Chong Yidong - - * frames.texi (Speedbar): Add information on keybindings, - dismissing the speedbar, and buffer display mode. Link to - speedbar manual. - -2005-10-09 Jan Djärv - - * cmdargs.texi (Icons X): Remove options -i, -itype, --icon-type, - added -nb, --no-bitmap-icon. - -2005-10-07 Nick Roberts - - * building.texi (GDB Graphical Interface): Add variables and - functions to indices. Be more precise. - -2005-10-03 Jan Djärv - - * frames.texi (Drag and Drop): Remove the x- from - x-dnd-open-file-other-window and xdnd-protocol-alist. - -2005-09-30 Romain Francoise - - * mini.texi (Minibuffer): The default value now appears before the - colon in minibuffer prompts. - -2005-09-25 Richard M. Stallman - - * search.texi (Regexp Search): Doc search-whitespace-regexp. - -2005-09-20 Emanuele Giaquinta (tiny change) - - * text.texi (Paragraphs): Correction about Paragraph-Indent Text mode. - -2005-09-21 YAMAMOTO Mitsuharu - - * emacs.texi (Top): Update submenus from macos.texi. - - * macos.texi: Change `Mac OS 8 or 9' to `Mac OS Classic'. - (Mac OS): Update feature support status. - (Mac Input): List supported input scripts. Remove description - about `mac-keyboard-text-encoding'. Mention mouse button - emulation and related variables. - (Mac International): Mention Central European and Cyrillic - support. Now `keyboard-coding-system' is dynamically changed. - Add description about coding system for selection. - Add description about language environment. - (Mac Environment Variables): - Mention `~/.MacOSX/environment.plist'. Give example of command line - arguments. Add Preferences support. - (Mac Directories): Explicitly state that this node is for Mac OS - Classic only. - (Mac Font Specs): Mention specification for scalable fonts. - List supported charsets. Add preferred way of creating fontsets. - Add description about `mac-allow-anti-aliasing'. - (Mac Functions): Add descriptions about `mac-set-file-creator', - `mac-get-file-creator', `mac-set-file-type', `mac-get-file-type', - and `mac-get-preference'. - -2005-09-16 Romain Francoise - - Update all files to specify GFDL version 1.2. - - * doclicense.texi (GNU Free Documentation License): Update to - version 1.2. - -2005-09-15 Richard M. Stallman - - * buffers.texi (List Buffers): Fix xref. - - * rmail.texi (Rmail Basics): Fix xref. - - * emacs.texi (Top): Update subnode menus. - - * files.texi (Saving Commands): New node, broken out of Saving. - (Customize Save): New node, broken out of Saving. - Clarify effect of write-region-inhibit-fsync. - (Misc File Ops): Say write-region-inhibit-fsync affects write-region. - -2005-09-14 Romain Francoise - - * files.texi (Saving): Mention write-region-inhibit-fsync. - -2005-09-05 Chong Yidong - - * custom.texi (Custom Themes): New node. - -2005-09-03 Richard M. Stallman - - * search.texi (Search Case): Mention vars that control - case-fold-search for various operations. - -2005-08-22 Juri Linkov - - * display.texi (Standard Faces): Merge the text from - `(elisp)Standard Faces' into this node. - -2005-08-18 Luc Teirlinck - - * emacs.texi (Top): Delete menu item for deleted node - Keyboard Translations. - -2005-08-18 Richard M. Stallman - - * trouble.texi (Unasked-for Search): - Delete xref to Keyboard Translations. - - * glossary.texi (Glossary): Delete xref. - - * custom.texi (Minor Modes): Say that the list here is not complete. - (Keyboard Translations): Node deleted. - (Disabling): Delete xref to it. - (Customization Groups): Fix Custom buffer example. - (Hooks): Mention remove-hooks. - -2005-08-17 Luc Teirlinck - - * building.texi (GDB Graphical Interface): Improve filling of menu - item. - -2005-08-18 Nick Roberts - - * building.texi (GDB Graphical Interface): Use better node names. - -2005-08-14 Richard M. Stallman - - * text.texi (Sentences): Fix xref. - -2005-08-14 Juri Linkov - - * building.texi (Compilation, Grep Searching): Move grep command - headings from `Compilation' to `Grep Searching'. - - * dired.texi (Dired and Find): - * maintaining.texi (Tags Search): Replace grep xref to - `Compilation' node with `Grep Searching'. - - * files.texi (Comparing Files): Replace xref to `Compilation' with - `Compilation Mode'. - -2005-08-13 Alan Mackenzie - - * search.texi (Non-ASCII Isearch): Correct a typo. - (Replacement Commands): Mention query-replace key binding. - -2005-08-11 Richard M. Stallman - - * programs.texi (Options for Comments): Fix xref. - - * search.texi (Regexp Backslash, Regexp Example): New nodes split - out of Regexps. - -2005-08-09 Juri Linkov - - * building.texi (Compilation): Use `itemx' instead of `item'. - (Grep Searching): Simplify phrase. - - * display.texi (Standard Faces): Describe vertical-border on - window systems. - - * windows.texi (Split Window): Simplify phrase and mention - vertical-border face. - -2005-08-09 Richard M. Stallman - - * files.texi (Comparing Files): Clarify compare-windows. - - * calendar.texi (Scroll Calendar): Document < and > in calendar. - -2005-08-06 Eli Zaretskii - - * mule.texi (Coding Systems): Rephrase the paragraph about - codepages: no need for "M-x codepage-setup" anymore, except on - MS-DOS. - - * msdog.texi (MS-DOS and MULE): Clarify that this section is for - the MS-DOS port only. - -2005-07-30 Eli Zaretskii - - * makefile.w32-in (info): Don't run multi-install-info.bat. - ($(infodir)/dir): New target, produced by running - multi-install-info.bat. - -2005-07-22 Eli Zaretskii - - * files.texi (Quoted File Names): Add index entry. - -2005-07-19 Juri Linkov - - * files.texi (Comparing Files): Mention resync for `compare-windows'. - -2005-07-18 Juri Linkov - - * custom.texi (Easy Customization): - * files.texi (Old Versions): - * frames.texi (Wheeled Mice): - * mule.texi (Specify Coding): - * text.texi (Cell Justification): - * trouble.texi (After a Crash): - * xresources.texi (GTK styles): - Delete duplicate duplicate words. - -2005-07-17 Richard M. Stallman - - * frames.texi (Creating Frames): Fix foreground color example. - - * custom.texi (Init Examples): Clean up text about conditionals. - -2005-07-16 Richard M. Stallman - - * mini.texi (Completion Commands): Fix command name for ?. - -2005-07-16 Eli Zaretskii - - * display.texi (Standard Faces): Explain that customization of - `menu' face has no effect on w32 and with GTK. - Add cross-references. - - * cmdargs.texi (General Variables): Clarify the default location - of $HOME on w32 systems. - -2005-07-15 Jason Rumney - - * cmdargs.texi (General Variables): Default HOME on MS Windows has - changed. - -2005-07-08 Kenichi Handa - - * mule.texi (Recognize Coding): - Recommend revert-buffer-with-coding-system instead of revert-buffer. - -2005-07-07 Richard M. Stallman - - * anti.texi (Antinews): Mention mode-line-inverse-video. - - * files.texi (Saving): Minor correction about C-x C-w. - - * display.texi (Display Custom): Don't mention mode-line-inverse-video. - -2005-07-07 Luc Teirlinck - - * search.texi (Isearch Scroll): Add example of using the - `isearch-scroll' property. - (Slow Isearch): Reference anchor for `baud-rate' instead of entire - `Display Custom' node. - (Regexp Replace): Put text that requires Emacs Lisp knowledge last - and de-emphasize it. - (Other Repeating Search): `occur' currently can not correctly - handle multiline matches. Correct, clarify and update description - of `flush-lines' and `keep-lines'. - - * display.texi (Display Custom): Add anchor for `baud-rate'. - -2005-07-07 Richard M. Stallman - - * gnu.texi: Update where to get GNU status; add refs for how to help. - Add footnotes 6 and 7. - -2005-07-04 Lute Kamstra - - Update FSF's address in GPL notices. - - * doclicense.texi (GNU Free Documentation License): - * trouble.texi (Checklist): Update FSF's address. - -2005-06-24 Richard M. Stallman - - * display.texi (Text Display): Change index entries. - -2005-06-24 Eli Zaretskii - - * makefile.w32-in (MAKEINFO): Use --force. - (INFO_TARGETS, DVI_TARGETS): Make identical to the lists in - Makefile.in. - -2005-06-23 Richard M. Stallman - - * anti.texi (Antinews): Rename show-nonbreak-escape to - nobreak-char-display. - - * emacs.texi (Top): Update detailed node listing. - - * display.texi (Text Display): Rename show-nonbreak-escape - to nobreak-char-display and no-break-space to nobreak-space. - (Standard Faces): Split up the list of standard faces - and put it in a separate node. Add nobreak-space and - escape-glyph. - -2005-06-23 Lute Kamstra - - * mule.texi (Select Input Method): Fix typo. - -2005-06-23 Kenichi Handa - - * mule.texi (International): List all supported scripts. - Adjust text for that leim is now included in the normal Emacs - distribution. - (Language Environments): List all language environments. - Intlfonts contains fonts for most supported scripts, not all.. - (Select Input Method): Refer to C-u C-x = to see how to type to - input a specific character. - (Recognize Coding): Fix typo, china-iso-8bit -> chinese-iso-8bit. - -2005-06-23 Juanma Barranquero - - * building.texi (Grep Searching): Texinfo usage fix. - -2005-06-22 Miles Bader - - * display.texi (Faces): Change `vertical-divider' to `vertical-border'. - -2005-06-20 Miles Bader - - * display.texi (Faces): Add `vertical-divider'. - -2005-06-17 Richard M. Stallman - - * text.texi (Adaptive Fill): Minor clarification. - -2005-06-10 Lute Kamstra - - * emacs.texi (Top): Correct version number. - * anti.texi (Antinews): Correct version number. Use EMACSVER to - refer to the current version of Emacs. - -2005-06-08 Luc Teirlinck - - * files.texi (Log Buffer): Document when there can be more than - one file to be committed. - -2005-06-08 Juri Linkov - - * display.texi (Faces): Add `shadow' face. - -2005-06-07 Masatake YAMATO - - * display.texi (Faces): Write about mode-line-highlight. - -2005-06-06 Richard M. Stallman - - * misc.texi (Printing Package): Explain how to initialize - printing package. - - * cmdargs.texi (Action Arguments): Clarify directory default for -l. - -2005-06-05 Chong Yidong - - * emacs.texi: Rename Hardcopy to Printing. - Make PostScript and PostScript Variables subnodes of it. - - * misc.texi (Printing): Rename node from Hardcopy. - Mention menu bar options. - Move PostScript and PostScript Variables to submenu. - (Printing package): New node. - - * mark.texi (Using Region): Change Hardcopy xref to Printing. - - * dired.texi (Operating on Files): Likewise. - - * calendar.texi (Displaying the Diary): Likewise. - - * msdog.texi (MS-DOS Printing, MS-DOS Processes): Likewise. - - * glossary.texi (Glossary): Likewise. - - * frames.texi (Mode Line Mouse): Mention mode-line-highlight - effect. - -2005-06-04 Richard M. Stallman - - * trouble.texi (After a Crash): Polish previous change. - -2005-05-30 Noah Friedman - - * trouble.texi (After a Crash): Mention emacs-buffer.gdb as a - recovery mechanism. - -2005-05-28 Nick Roberts - - * building.texi (Other Buffers): SPC toggles display of - floating point registers. - -2005-05-27 Nick Roberts - - * files.texi (Log Buffer): Merge in description of Log Edit - mode from pcl-cvs.texi. - -2005-05-26 Richard M. Stallman - - * building.texi (Lisp Eval): C-M-x with arg runs Edebug. - -2005-05-24 Luc Teirlinck - - * fixit.texi (Spelling): Delete confusing sentence; flyspell is - not enabled by default. - When not on a word, `ispell-word' by default checks the word - before point. - -2005-05-24 Nick Roberts - - * building.texi (Debugger Operation): Simplify last sentence. - -2005-05-23 Lute Kamstra - - * emacs.texi: Update FSF's address throughout. - (Preface): Use @cite. - (Distrib): Add cross reference to the node "Copying". Mention the - FDL. Don't refer to etc/{FTP,ORDERS}. Mention the sale of - printed manuals. - (Intro): Use @xref for the Emacs Lisp Intro. - -2005-05-18 Luc Teirlinck - - * buffers.texi (Select Buffer): Document `C-u M-g M-g'. - - * basic.texi (Moving Point): Mention default for `goto-line'. - - * programs.texi (Lisp Doc): Eldoc mode shows only the first line - of a variable's docstring. - -2005-05-18 Lute Kamstra - - * maintaining.texi (Overview of Emerge): Add cross reference. - Remove duplication. - - * emacs.texi (Top): Update to the current structure of the manual. - * misc.texi (Emacs Server): Add menu description. - * files.texi (Saving): Fix menu. - * custom.texi (Customization): Fix menu. - * mule.texi (International): Fix menu. - * kmacro.texi (Keyboard Macros): Fix menu. - -2005-05-16 Luc Teirlinck - - * display.texi: Various minor changes. - (Faces): Delete text that is repeated in the next section. - -2005-05-16 Nick Roberts - - * building.texi (Debugger Operation): Mention GUD tooltips are - disabled with GDB in text command mode. - -2005-05-16 Nick Roberts - - * building.texi: Replace toolbar with "tool bar" for consistency. - (Compilation Mode): Describe compilation-context-lines - and use of arrow in compilation buffer. - (Debugger Operation): Replace help text with variable's value. - - * frames.texi (Tooltips): Replace toolbar with "tool bar" for - consistency. - -2005-05-15 Luc Teirlinck - - * major.texi (Choosing Modes): normal-mode processes the -*- line. - Add xref. - -2005-05-14 Luc Teirlinck - - * basic.texi (Moving Point): Mention `M-g g' binding for `goto-line'. - (Position Info): Delete discussion of `goto-line'. It is already - described in `Moving point'. - - * mini.texi (Completion Commands): Correct reference. - (Completion Options): Fix typo. - - * killing.texi (Deletion): Complete description of `C-x C-o'. - -2005-05-10 Richard M. Stallman - - * building.texi (Compilation): Clarify recompile's directory choice. - - * frames.texi (Tooltips): Cleanups. - - * basic.texi (Arguments): Fix punctuation. - -2005-05-09 Luc Teirlinck - - * screen.texi (Menu Bar): The up and down (not left and right) - arrow keys move through a keyboard menu. - -2005-05-08 Luc Teirlinck - - * basic.texi: Various typo and grammar fixes. - (Moving Point): C-a now runs move-beginning-of-line. - -2005-05-08 Nick Roberts - - * building.texi (Debugger Operation): Describe gud-tooltip-echo-area. - - * frames.texi (Tooltips): Describe help tooltips and GUD tooltips - as different animals. - -2005-05-07 Luc Teirlinck - - * frames.texi (Mouse References): Clarify `mouse-1-click-follows-link'. - Correct index entry. - -2005-05-07 Nick Roberts - - * building.texi (Debugger Operation): Update to reflect changes - in GUD tooltips. - -2005-04-30 Richard M. Stallman - - * files.texi (Compressed Files): Auto Compression normally enabled. - - * building.texi (Debugger Operation): Clarify previous change. - -2005-04-28 Nick Roberts - - * building.texi (Debugger Operation): Add description for - GUD tooltips when program is not running. - -2005-04-26 Luc Teirlinck - - * misc.texi (Shell): Add `Shell Prompts' to menu. - (Shell Mode): Add xref to `Shell Prompts'. Clarify `C-c C-u' - description. Delete remarks moved to new node. - (Shell Prompts): New node. - (History References): Replace remarks moved to `Shell Prompts' - with xref to that node. - (Remote Host): Clarify how to specify the terminal type when - logging in to a different machine. - -2005-04-26 Richard M. Stallman - - * emacs.texi (Top): Update submenus from files.texi. - - * files.texi (Filesets): Clarify previous change. - - * dired.texi (Misc Dired Features): Clarify previous change. - -2005-04-25 Chong Yidong - - * ack.texi (Acknowledgments): Delete info about iso-acc.el. - - * dired.texi (Misc Dired Features): - Document dired-compare-directories. - - * files.texi (Filesets): New node. - (File Conveniences): Document Image mode. - - * text.texi (TeX Print): Document tex-compile. - -2005-04-25 Luc Teirlinck - - * frames.texi (Tooltips): Tooltip mode is enabled by default. - Delete redundant reference to tooltip Custom group. It is - referred too again in the next paragraph. - -2005-04-24 Richard M. Stallman - - * ack.texi: Delete info about lazy-lock.el and fast-lock.el. - -2005-04-19 Kim F. Storm - - * building.texi (Compilation Mode): Add M-g M-n and M-g M-p bindings. - -2005-04-18 Lars Hansen - - * misc.texi (Saving Emacs Sessions): Add that "--no-desktop" now - turns off desktop-save-mode. - -2005-04-17 Luc Teirlinck - - * frames.texi (XTerm Mouse): Xterm Mouse mode is no longer enabled - by default in terminals compatible with xterm. Mention that - xterm-mouse-mode is a minor mode and put in pxref to Minor Modes - node. - -2005-04-12 Luc Teirlinck - - * frames.texi (XTerm Mouse): Xterm Mouse mode is now enabled by default. - -2005-04-12 Jan Djärv - - * xresources.texi (Table of Resources): Add cursorBlink. - -2005-04-11 Luc Teirlinck - - * rmail.texi (Rmail Summary Edit): Explain numeric arguments to - `d', `C-d' and `u'. - -2005-04-11 Richard M. Stallman - - * cmdargs.texi (Initial Options): -Q is now --quick, and does less. - (Misc X): Add -D, --basic-display. - - * maintaining.texi (Change Log): Correct the description of - the example. - - * major.texi (Choosing Modes): Document magic-mode-alist. - -2005-04-10 Luc Teirlinck - - * rmail.texi (Rmail Basics): Clarify description of `q' and `b'. - (Rmail Deletion): `C-d' in RMAIL buffer does not accept a numeric arg. - (Rmail Inbox): Give full name of `rmail-primary-inbox-list'. - (Rmail Output): Clarify which statements apply to `o', `C-o' and - `w', respectively. - (Rmail Labels): Mention `l'. - (Rmail Attributes): Correct pxref. Mention `stored' attribute. - (Rmail Summary Edit): Describe `j' and RET. - -2005-04-10 Jan Djärv - - * xresources.texi (Lucid Resources): Add fontSet resource. - -2005-04-09 Luc Teirlinck - - * display.texi (Useless Whitespace): `indicate-unused-lines' is - now called `indicate-empty-lines'. - -2005-04-06 Kim F. Storm - - * cmdargs.texi (Initial Options): Add --bare-bones alias for -Q. - -2005-04-04 Luc Teirlinck - - * dired.texi (Dired Visiting): `dired-view-command-alist' has been - deleted. - (Marks vs Flags): Add some convenient key bindings. - (Hiding Subdirectories): Delete redundant and inaccurate sentence. - (Misc Dired Features): Correct and expand description of `w' command. - - * frames.texi (XTerm Mouse): Delete apparently false info. - The GNU/Linux console currently does not appear to support - `xterm-mouse-mode'. - -2005-04-03 Glenn Morris - - * calendar.texi (Diary): Mention shell utility `calendar'. - -2005-04-01 Richard M. Stallman - - * cmdargs.texi (Misc X): Explain horizontal scroll bars don't exist. - -2005-04-01 Lute Kamstra - - * maintaining.texi (Change Log): add-change-log-entry uses - add-log-mailing-address. - -2005-03-31 Luc Teirlinck - - * files.texi (Reverting): Move `auto-revert-check-vc-info' to - `VC Mode Line' and put in an xref to that node. - (VC Mode Line): Move `auto-revert-check-vc-info' here and clarify - its description. - -2005-03-31 Paul Eggert - - * calendar.texi (Calendar Systems): Say that the Persian calendar - implemented here is the arithmetical one championed by Birashk. - -2005-03-30 Glenn Morris - - * programs.texi (Fortran Motion): Fix previous change. - -2005-03-29 Richard M. Stallman - - * mule.texi (Single-Byte Character Support): Reinstall the C-x 8 info. - -2005-03-29 Chong Yidong - - * text.texi (Refill): Refer to Long Lines Mode. - (Longlines): New node. - (Auto Fill): Don't index "word wrap" here. - (Filling): Add Longlines to menu. - -2005-03-29 Richard M. Stallman - - * xresources.texi: Minor fixes. - - * misc.texi (Emacs Server): Fix Texinfo usage. - - * emacs.texi (Top): Don't use a real section heading for - "Detailed Node Listing". Fake it instead. - - * basic.texi (Position Info): Minor cleanup. - - * mule.texi (Input Methods): Minor cleanup. - -2005-03-29 Glenn Morris - - * programs.texi (ForIndent Vars): `fortran-if-indent' does other - constructs as well. - (Fortran Motion): Add fortran-end-of-block, fortran-beginning-of-block. - -2005-03-29 Kenichi Handa - - * mule.texi (Input Methods): Refer to the command C-u C-x =. - - * basic.texi (Position Info): Update the description about the - command C-u C-x =. - -2005-03-28 Richard M. Stallman - - * emacs.texi (Top): Use @section for the detailed node listing. - - * calendar.texi: Minor fixes to previous change. - - * programs.texi (Fortran): Small fixes to previous changes. - - * emacs.texi (Top): Update list of subnodes of Dired. - Likewise for building.texi. - - * files.texi (File Conveniences): Delete Auto Image File mode. - -2005-03-28 Chong Yidong - - * building.texi (Flymake): New node. - - * custom.texi (Function Keys): Document kp- event types and - keypad-setup package. - - * dired.texi (Wdired): New node. - - * files.texi (File Conveniences): Reorder entries. - Explain how to turn on Auto-image-file mode. - Document Thumbs mode. - - * mule.texi (Specify Coding): Document recode-region and - recode-file-name. - - * programs.texi (Program Modes): Add Conf mode and DNS mode. - -2005-03-27 Luc Teirlinck - - * commands.texi (Keys): M-o is now a prefix key. - -2005-03-27 Glenn Morris - - * programs.texi: Reformat and update copyright years. - (Fortran): Update section. - -2005-03-26 Luc Teirlinck - - * files.texi: Several small changes in addition to: - (Visiting): Change xref for Dialog Boxes to ref. - (Version Headers): Replace references to obsolete var - `vc-header-alist' with `vc-BACKEND-header'. - (Customizing VC): Update value of `vc-handled-backends'. - -2005-03-26 Glenn Morris - - * emacs-xtra.texi (Advanced Calendar/Diary Usage): New section; - move here from Emacs Lisp Reference Manual. - * calendar.texi (Calendar/Diary, Diary Commands) - (Special Diary Entries, Importing Diary): Change some xrefs to - point to emacs-xtra rather than elisp. - - * emacs-xtra.texi (Calendar Customizing): - Move view-diary-entries-initially, view-calendar-holidays-initially, - mark-diary-entries-in-calendar, mark-holidays-in-calendar to main - Emacs Manual. - (Appt Customizing): Merge entire section into main Emacs Manual. - * calendar.texi (Holidays): Move view-calendar-holidays-initially, - mark-holidays-in-calendar here from emacs-xtra. - (Displaying the Diary): Move view-diary-entries-initially, - mark-diary-entries-in-calendar here from emacs-xtra. - (Appointments): Move appt-display-mode-line, - appt-display-duration, appt-disp-window-function, - appt-delete-window-function here from emacs-xtra. - - * calendar.texi: Update and reformat copyright. - Change all @xrefs to the non-printing emacs-xtra to @inforefs. - (Calendar/Diary): Menu now only on Mouse-3, not C-Mouse-3. - (Diary): Refer to `diary-file' rather than ~/diary. - (Diary Commands): Rename node to "Displaying the Diary". - * emacs.texi (Top): Rename "Diary Commands" section. - * misc.texi (Hardcopy): Rename "Diary Commands" xref. - -2005-03-26 Eli Zaretskii - - * misc.texi (Emacs Server): Fix the command for setting - server-name. Add an xref to Invoking emacsclient. - - * help.texi (Help Summary): Clarify when "C-h ." will do something - nontrivial. - (Apropos): Add cindex entry for apropos-sort-by-scores. - - * display.texi (Text Display): Add index entries for how no-break - characters are displayed. - -2005-03-26 Eli Zaretskii - - * files.texi (Visiting): Fix cross-references introduced with the - last change. - - * xresources.texi (GTK resources): Fix last change. - -2005-03-25 Chong Yidong - - * xresources.texi (X Resources): GTK options documented too. - (Resources): Clarify meaning of program name. - (Table of Resources): Add visualClass. - (GTK resources): Rewrite. - (GTK widget names, GTK Names in Emacs, GTK styles): Cleanups. - - * display.texi (Text Display): Mention non-breaking spaces. - - * files.texi (Reverting): Document auto-revert-check-vc-info. - - * frames.texi (Mouse Commands): Document - x-mouse-click-focus-ignore-position and mouse-drag-copy-region. - - * help.texi (Help Summary): Add `C-h .'. - (Apropos): Apropos accepts a list of search terms. - Document apropos-sort-by-scores. - (Help Echo): Document display-local-help. - - * misc.texi (Emacs Server): Document server-name. - (Invoking emacsclient): Document -s option for server names. - - * text.texi (Outline Visibility): Introduce "current heading - line" (commands can be called with point on a body line). - Re-order table to follow the sequence of discussion. - hide-body won't hide lines before first header line. - (TeX Mode): Add DocTeX mode. - -2005-03-24 Richard M. Stallman - - * mule.texi (Single-Byte Character Support): Delete mention - of iso-acc.el and iso-transl.el. - -2005-03-23 Lute Kamstra - - * search.texi (Non-ASCII Isearch): Rename from Non-Ascii Isearch. - -2005-03-23 Richard M. Stallman - - * search.texi: Delete explicit node pointers. - (Incremental Search): New menu. - (Basic Isearch, Repeat Isearch, Error in Isearch) - (Non-Ascii Isearch, Isearch Yank, Highlight Isearch, Isearch Scroll) - (Slow Isearch): New subnodes. - (Configuring Scrolling): Node deleted. - (Search Case): Doc default-case-fold-search. - (Regexp Replace): Move replace-regexp doc here. - - * rmail.texi (Movemail): Put commas inside closequotes. - - * picture.texi (Insert in Picture): Document C-c arrow combos. - (Basic Picture): Clarify erasure. - - * display.texi (Font Lock): Put commas inside closequotes. - - * cmdargs.texi (General Variables): Put commas inside closequotes. - -2005-03-23 Nick Roberts - - * building.texi (Stack Buffer): Mention reverse contrast for - *selected* frame (might not be current frame). - -2005-03-21 Richard M. Stallman - - * building.texi (Starting GUD): Add bashdb. - -2005-03-20 Chong Yidong - - * basic.texi (Moving Point): Add M-g M-g binding. - (Undo): Document undo-only. - (Position Info): Document M-g M-g and C-u M-g M-g. - - * building.texi (Building): Put Grep Searching after Compilation - Shell. - (Compilation Mode): Document M-n, M-p, M-}, M-{, and C-c C-f bindings. - Document next-error-highlight. - (Grep Searching): Document grep-highlight-matches. - (Lisp Eval): Typing C-x C-e twice prints integers specially. - - * calendar.texi (Importing Diary): Rename node from iCalendar. - Document diary-from-outlook. - - * dired.texi (Misc Dired Features): Rename node from Misc Dired - Commands. - Mention effect of X drag and drop on Dired buffers. - - * files.texi (Visiting): Document large-file-warning-threshold. - Move paragraph on file-selection dialog. - Mention visiting files using X drag and drop. - (Reverting): Mention using Auto-Revert mode to tail files. - Document auto-revert-tail-mode. - (Version Systems): Minor correction. - (Comparing Files): Diff-mode is no longer based on Compilation - mode. - Document compare-ignore-whitespace. - (Misc File Ops): Explain passing a directory to rename-file. - Likewise for copy-file and make-symbolic-link. - - * frames.texi (Wheeled Mice): Mouse wheel support on by default. - Document mouse-wheel-progressive speed. - - * help.texi (Misc Help): Document numeric argument for C-h i. - Correctly explain the effect of just C-u as argument. - - * killing.texi (Deletion): Document numeric argument for - just-one-space. - - * mini.texi (Completion): Completion acts on text before point. - - * misc.texi (Saving Emacs Sessions): Document desktop-restore-eager. - (Emulation): CUA mode replaces pc-bindings-mode, - pc-selection-mode, and s-region. - - * mule.texi (Input Methods): Leim is now built-in. - (Select Input Method): Document quail-show-key. - (Specify Coding): Document revert-buffer-with-coding-system. - - * programs.texi (Fortran Motion): Document f90-next-statement, - f90-previous-statement, f90-next-block, f90-previous-block, - f90-end-of-block, and f90-beginning-of-block. - - * text.texi (Format Faces): Replace old M-g key prefix with M-o. - - * emacs.texi (Acknowledgments): Updated. - - * anti.texi: Total rewrite. - -2005-03-19 Chong Yidong - - * ack.texi (Acknowledgments): Update. - -2005-03-19 Eli Zaretskii - - * anti.texi (Antinews): Refer to Emacs 21.4, not 21.3. - Update copyright years. - -2005-03-14 Nick Roberts - - * building.texi (Commands of GUD): Move paragraph on setting - breakpoints with mouse to the GDB Graphical Interface node. - -2005-03-07 Richard M. Stallman - - * misc.texi (Single Shell, Shell Options): Fix previous change. - - * building.texi (Debugger Operation): Update GUD tooltip enable info. - -2005-03-06 Richard M. Stallman - - * building.texi (Starting GUD): Don't explain text vs graphical - GDB here. Just mention it and xref. - Delete "just one debugger process". - (Debugger Operation): Move GUD tooltip info here. - (GUD Tooltips): Node deleted. - (GDB Graphical Interface): Explain the two GDB modes here. - - * sending.texi (Sending Mail): Minor cleanup. - (Mail Aliases): Explain quoting conventions. - Update key rebinding example. - (Header Editing): C-M-i is like M-TAB. - (Mail Mode Misc): mail-attach-file does not do MIME. - - * rmail.texi (Rmail Inbox): Move text from Remote Mailboxes - that really belongs here. - (Remote Mailboxes): Text moved to Rmail Inbox. - (Rmail Display): Mention Mouse-1. - (Movemail): Clarify two movemail versions. - Clarify rmail-movemail-program. - - * misc.texi (Single Shell): Replace uudecode example with gpg example. - Document async shell commands. - (Shell History): Clarify. - (Shell Ring): Mention C-UP an C-DOWN. - (Shell Options): Add comint-prompt-read-only. - (Invoking emacsclient): Set EDITOR to run Emacs. - (Sorting): No need to explain what region is. - (Saving Emacs Sessions): Fix typo. - (Recursive Edit): Fix punctuation. - (Emulation): Don't mention "PC bindings" which are standard. - (Hyperlinking): Explain Mouse-1 convention here. - (Find Func): Node deleted. - - * help.texi (Name Help): Xref to Hyperlinking. - - * glossary.texi (Glossary): - Rename "Balance Parentheses" to "Balancing...". - Add "Byte Compilation". Correct "Copyleft". - New xref in "Customization". - Clarify "Current Line", "Echoing", "Fringe", "Frame", "Speedbar". - Add "Graphical Terminal" "Keybinding", "Margin", "Window System". - Rename "Registers" to "Register". - Replace "Selecting" with "Selected Frame", - "Selected Window", and "Selecting a Buffer". - - * files.texi (Types of Log File): Explain how projects' - methods can vary. - - * display.texi (Faces): Delete "Emacs 21". - - * custom.texi (Changing a Variable): C-M-i like M-TAB. - * fixit.texi (Spelling): C-M-i like M-TAB. - * mini.texi (Completion Options): C-M-i like M-TAB. - * programs.texi (Symbol Completion): C-M-i like M-TAB. - * text.texi (Text Mode): C-M-i like M-TAB. - - * commands.texi (Keys): Mention F1 and F2 in list of prefixes. - - * calendar.texi (Specified Dates): Mention `g w'. - (Appointments): appt-activate toggles with no arg. - -2005-03-05 Juri Linkov - - * cmdargs.texi (Emacs Invocation): Add cindex - "invocation (command line arguments)". - (Misc X): Add -nbc, --no-blinking-cursor. - -2005-03-04 Ulf Jasper - - * calendar.texi (iCalendar): No need to require it now. - -2005-03-03 Nick Roberts - - * trouble.texi (Contributing): Mention Savannah. Direct users to - emacs-devel. - -2005-03-01 Glenn Morris - - * calendar.texi (Adding to Diary): Mention redrawing of calendar - window. - -2005-02-27 Richard M. Stallman - - * building.texi (Compilation): Update mode line status info. - -2005-02-27 Matt Hodges - - * calendar.texi (General Calendar): Document binding of - scroll-other-window-down. - (Mayan Calendar): Fix earliest date. - (Time Intervals): Document timeclock-change. - Fix timeclock-ask-before-exiting documentation. - -2005-02-26 Kim F. Storm - - * frames.texi (Mouse References): - Add mouse-1-click-in-non-selected-windows. - -2005-02-25 Richard M. Stallman - - * screen.texi (Screen): Explain better about cursors and mode lines; - don't presuppose text terminals. - (Point): Don't assume just one cursor. - Clarify explanation of cursors. - (Echo Area, Menu Bar): Cleanups. - - * mini.texi (Minibuffer): Prompts are highlighted. - (Minibuffer Edit): Newline = C-j only on text terminals. - Clarify resize-mini-windows values. - Mention M-PAGEUP and M-PAGEDOWN. - (Completion Commands): Mouse-1 like Mouse-2. - (Minibuffer History): Explain history commands better. - (Repetition): Add xref to Incremental Search. - - * mark.texi (Setting Mark): Clarify info about displaying mark. - Clarify explanation of C-@ and C-SPC. - (Transient Mark): Mention Delete Selection mode. - (Marking Objects): Clean up text about extending the region. - - * m-x.texi (M-x): One C-g doesn't always go to top level. - No delay before suggest-key-bindings output. - - * fixit.texi (Fixit): Mention C-/ for undo. - (Spelling): Mention ESC TAB like M-TAB. - Replacement words with r and R are rechecked. - Say where C-g leaves point. Mention ? as input. - -2005-02-23 Lute Kamstra - - * cmdargs.texi (Initial Options): Add cross reference. - -2005-02-16 Luc Teirlinck - - * emacs.texi (Top): Update menu for splitting of node in - msdog.texi. - * frames.texi (Frames): Update xref for splitting of node in - msdog.texi. - * trouble.texi (Quitting): Ditto. - -2005-02-16 Richard M. Stallman - - * windows.texi (Split Window): Simplify line truncation info - and xref to Display Custom. - - * trouble.texi (Quitting): Emergency escape only for text terminal. - (Screen Garbled): C-l for ungarbling is only for text terminal. - - * text.texi (Text Mode): ESC TAB alternative for M-TAB. - - * sending.texi (Header Editing): ESC TAB alternative for M-TAB. - - * programs.texi (Program Modes): Mention Python mode. - (Moving by Defuns): Repeating C-M-h extends region. - (Basic Indent): Clarify. - (Custom C Indent): Clarify. - (Expressions): Repeating C-M-@ extends region. - (Info Lookup): Clarify for C-h S. - (Symbol Completion): ESC TAB alternative for M-TAB. - (Electric C): Clarify. - - * emacs.texi (Top): Update display.texi and frames.texi submenu data. - - * msdog.texi (MS-DOS Keyboard, MS-DOS Mouse): Split from - MS-DOS Input node. - (MS-DOS Keyboard): Start with explaining DEL and BREAK. - (MS-DOS and MULE): Clarify. - (MS-DOS Processes, Windows Processes): Fix typos. - - * major.texi (Choosing Modes): Clarify. - - * kmacro.texi (Basic Keyboard Macro): Doc F3, F4. - (Keyboard Macro Step-Edit): Clarify. - - * indent.texi (Indentation): Clarifications. - - * help.texi (Help): Correct error about C-h in query-replace. - Clarify apropos vs C-h a. Fix how to search in FAQ. - (Key Help): Describe C-h w here. - (Name Help): Minor cleanup. C-h w moved to Key Help. - Clarify the "object" joke. - (Apropos): Clarify. Mouse-1 like Mouse-2. - (Help Mode): Mouse-1 like Mouse-2. - - * fixit.texi (Spelling): Mention ESC TAB as alt. for M-TAB. - - * display.texi (Display): Reorder menu. - (Faces): Cleanup. - (Font Lock): Cleanup. Mention Options menu. - Delete obsolete text. - (Scrolling): For C-l, don't presume text terminal. - (Horizontal Scrolling): Simplify intro. - (Follow Mode): Clarify. - (Cursor Display): Move before Display Custom. - (Display Custom): Explain no-redraw-on-reenter is for text terminals. - Doc default-tab-width. Doc line truncation more thoroughly. - - * dired.texi (Dired Enter): C-x C-f can run Dired. - (Dired Visiting): Comment out `a' command. - Mouse-1 is like Mouse-2. - (Shell Commands in Dired): ? can be used more than once. - - * basic.texi (Continuation Lines): Simplify description of truncation, - and refer to Display Custom for the rest of it. - -2005-02-06 Lute Kamstra - - * basic.texi (Undo): Fix typo. - - * cmdargs.texi (Emacs Invocation): Fix typo. - - * custom.texi (Init Examples): Fix typo. - - * abbrevs.texi (Expanding Abbrevs): Fix typo. - -2005-02-06 Richard M. Stallman - - * regs.texi (Registers): Registers can hold numbers, too. - - * killing.texi (Other Kill Commands): Cleanup. - Delete redundant explanation of kill in read-only buffer. - (Yanking): Mention term "copying". - (Accumulating Text): Fix typo. - - * entering.texi (Entering Emacs): Update rationale at start. - (Exiting): Treat iconifying on a par with suspension. - - * custom.texi (Minor Modes): Fix typo. - (Easy Customization): Fix menu style. - (Variables): Add xref. - (Examining): Setting for future sessions works through .emacs. - (Keymaps): "Text terminals", not "Many". - (Init Rebinding): Explain \C-. Show example of \M-. - Fix minor wording errors. - (Function Keys): Explain vector syntax just once. - (Named ASCII Chars): Clarify history of TAB/C-i connection. - (Init File): Mention .emacs.d directory. - (Init Examples): Add xref. - (Find Init): Mention .emacs.d directory. - - * cmdargs.texi (Emacs Invocation): +LINENUM is also an option. - (Action Arguments): Explain which kinds of -l args are found how. - (Initial Options): --batch does not inhibit site-start. - Add xrefs. - (Command Example): Use --batch, not -batch. - - * basic.texi (Inserting Text): Cleanup wording. - (Moving Point): Doc PRIOR, PAGEUP, NEXT, PAGEDOWN more systematically. - C-n is not error at end of buffer. - (Undo): Doc C-/ like C-_. Add xrefs. - (Arguments): META key may be labeled ALT. - Peculiar arg meanings are explained in doc strings. - - * abbrevs.texi (Expanding Abbrevs): Clarify. - -2005-02-05 Eli Zaretskii - - * frames.texi (Frame Parameters): Add an xref to the description - of list-colors-display. Add a pointer to the X docs about colors. - - * cmdargs.texi (Colors): Mention 16-, 88- and 256-color modes. - Improve docs of list-colors-display. - -2005-02-03 Lute Kamstra - - * frames.texi (Frames, Drag and Drop): Fix typos. - -2005-02-03 Richard M. Stallman - - * windows.texi (Basic Window): Mention color-change in mode line. - (Change Window): Explain dragging vertical boundaries. - - * text.texi (Sentences): Clarify. - (Paragraphs): Explain M-a and blank lines. - (Outline Mode): Clarify text and menu. - (Hard and Soft Newlines): Mention use-hard-newlines. - - * frames.texi (Frames): Delete unnecessary mention of Windows. - (Mouse Commands): Likewise. Mention xterm mouse support. - (Clipboard): Clarify. - (Mouse References): Mention use of Mouse-1 for following links. - (Menu Mouse Clicks): Clarify. - (Mode Line Mouse): Clarify. - (Drag and Drop): Rewrite. - - * fixit.texi (Spelling): Fix typo. - - * files.texi (File Names): Clarify. - (Visiting): Update conditions for use of file dialog. Clarify. - (Saving): Doc d as answer in save-some-buffers. - (Remote Files): Clean up the text. - - * dired.texi (Misc Dired Commands): Delete dired-marked-files. - - * buffers.texi (Select Buffer): Doc next-buffer and prev-buffer. - (List Buffers): Clarify. - (Several Buffers): Doc T command. - (Buffer Convenience): Clarify menu. - - * basic.texi (Undo): Clarify last change. - -2005-02-02 Matt Hodges - - * fixit.texi (Spelling): Fix typo. - -2005-02-01 Luc Teirlinck - - * basic.texi (Undo): Update description of `undo-outer-limit'. - -2005-02-01 Nick Roberts - - * building.texi: Update documentation relating to GDB Graphical - Interface. - -2005-01-30 Luc Teirlinck - - * custom.texi (Easy Customization): Adapt menu to node name change. - -2005-01-30 Richard M. Stallman - - * custom.texi (Easy Customization): Defn of "User Option" now - includes faces. Don't say just "option" when talking about variables. - Do say just "options" to mean "anything customizable". - (Specific Customization): Describe `customize-variable', - not `customize-option'. - - * glossary.texi (Glossary) : Add xref. - : Change definition--include faces. Change xref. - - * picture.texi (Picture): Mention artist.el. - - * sending.texi, screen.texi, programs.texi, misc.texi: - * mini.texi, major.texi, maintaining.texi, macos.texi: - * help.texi, frames.texi, files.texi: - Don't say just "option" when talking about variables. - - * display.texi, mule.texi: Don't say just "option" when talking - about variables. Other minor cleanups. - -2005-01-26 Lute Kamstra - - * cmdargs.texi (Initial Options): Add a cross reference to `Init - File'. Mention the `-Q' option at the `--no-site-file' option. - -2005-01-22 David Kastrup - - * building.texi (Grep Searching): Mention alias `find-grep' for - `grep-find'. - -2005-01-20 Richard M. Stallman - - * calendar.texi (Time Intervals): Delete special stuff for MS-DOS. - -2005-01-15 Sergey Poznyakoff - - * rmail.texi (Movemail): Explain differences - between standard and mailutils versions of movemail. - Describe command line and configuration options introduced - with the latter. - Explain the notion of mailbox URL, provide examples and - cross-references to mailutils documentation. - Describe various methods of specifying mailbox names, - user names and user passwords for rmail. - (Remote Mailboxes): New section. - Describe how movemail handles remote mailboxes. Describe configuration - options used to control its behavior. - (Other Mailbox Formats): Explain handling of various mailbox - formats. - -2005-01-13 Richard M. Stallman - - * commands.texi (Commands): Clarification. - -2005-01-11 Richard M. Stallman - - * programs.texi (Multi-line Indent): Fix previous change. - (Fortran Autofill): Simplify description of fortran-auto-fill-mode. - -2005-01-08 Richard M. Stallman - - * display.texi (Faces): isearch-lazy-highlight-face renamed to - lazy-highlight. - - * search.texi (Query Replace): Mention faces query-replace - and lazy-highlight. - (Incremental Search): Update isearch highlighting info. - -2005-01-04 Richard M. Stallman - - * custom.texi (Saving Customizations): Minor improvement. - -2005-01-03 Luc Teirlinck - - * custom.texi (Saving Customizations): Emacs no longer loads - `custom-file' after .emacs. No longer mention customizing through - Custom. - -2005-01-01 Andreas Schwab - - * killing.texi (Graphical Kill): Move up under node Killing, - change @section to @subsection. - -2005-01-01 Richard M. Stallman - - * custom.texi (Face Customization): Mention hex color specs. - - * emacs.texi (Top): Update Killing submenu. - - * killing.texi (Killing): Reorganize section. - No more TeX-only text; put the node command at start of chapter. - But the first section heading is used only in TeX. - Rewrite the text to read better in this mode. - (Graphical Kill): New subnode gets some of the text that - used to be in the first section. - -2004-12-31 Richard M. Stallman - - * dired.texi (Shell Commands in Dired): Delete the ? example. - - * display.texi (Scrolling): Correct scroll-preserve-screen-position. - - * files.texi (Saving): Describe new require-final-newline features - and mode-require-final-newline. - -2004-12-29 Richard M. Stallman - - * custom.texi (File Variables): Clarify previous change. - -2004-12-27 Jan Djärv - - * frames.texi (Dialog Boxes): Mention Gtk+ 2.6 also, as that version is - out now. - -2004-12-27 Richard M. Stallman - - * Makefile.in (MAKEINFO): Specify --force. - - * basic.texi (Moving Point): C-e now runs move-end-of-line. - (Undo): Doc undo-outer-limit. - -2004-12-15 Juri Linkov - - * mark.texi (Transient Mark, Mark Ring): M-< and other - movement commands don't set mark in Transient Mark mode - if mark is active. - -2004-12-12 Juri Linkov - - * misc.texi (FFAP): Add C-x C-r, C-x C-v, C-x C-d, - C-x 4 r, C-x 4 d, C-x 5 r, C-x 5 d. - - * dired.texi (Dired Navigation): Add @r{(Dired)} to M-g. - (Misc Dired Commands): Add @r{(Dired)} to w. - -2004-12-12 Juri Linkov - - * mark.texi (Marking Objects): Marking commands also extend the - region when mark is active in Transient Mark mode. - -2004-12-08 Luc Teirlinck - - * custom.texi (Saving Customizations): Emacs only loads the custom - file automatically after the init file in version 22.1 or later. - Adapt text and examples to this fact. - -2004-12-07 Luc Teirlinck - - * frames.texi (Scroll Bars): The option `scroll-bar-mode' has to - be set through Custom. Otherwise, it has no effect. - -2004-12-05 Richard M. Stallman - - * cmdargs.texi, doclicense.texi, xresources.texi, emacs.texi: - * entering.texi: Rename Command Line to Emacs Invocation. - - * misc.texi (Term Mode): Correctly describe C-c. - - * custom.texi (Easy Customization): Move up to section level, - before Variables. Avoid using the term "variable"; say "option". - New initial explanation. - (Variables): In initial explanation, connect "variable" to the - already-explained "user option". - - * emacs.texi (Top): Fix ref to Command Line. - Move reference to Easy Customization. - - * xresources.texi (X Resources): Fix From link. - - * doclicense.texi (GNU Free Documentation License): Fix To link. - - * entering.texi (Entering Emacs): Fix xref, now to Command Line. - - * cmdargs.texi (Command Line): Node renamed from Command Arguments. - -2004-12-03 Richard M. Stallman - - * cmdargs.texi (Initial Options): Clarify batch mode i/o. - -2004-12-01 Luc Teirlinck - - * kmacro.texi: Several small changes in addition to the following. - (Keyboard Macro Ring): Describe behavior of `C-x C-k C-k' when - defining a keyboard macro. - Mention `kmacro-ring-max'. - (Keyboard Macro Counter): Clarify description of - `kmacro-insert-counter', `kmacro-set-counter', - `kmacro-add-counter' and `kmacro-set-format'. - -2004-11-29 Reiner Steib - - * custom.texi (File Variables): Add `unibyte' and make it more - clear that `unibyte' and `coding' are special. Suggested by Simon - Krahnke . - - * mule.texi (Enabling Multibyte): Refer to File Variables. - Suggested by Simon Krahnke . - -2004-11-26 Jan Djärv - - * frames.texi (Dialog Boxes): Rename use-old-gtk-file-dialog to - x-use-old-gtk-file-dialog. - -2004-11-20 Richard M. Stallman - - * text.texi (Fill Prefix): M-q doesn't apply fill prefix to first line. - -2004-11-09 Lars Brinkhoff - - * building.texi (Lisp Eval): Delete hyphen in section name. - -2004-11-19 Thien-Thi Nguyen - - * files.texi (Old Versions): - No longer document annotation as "CVS only". - -2004-11-10 Andre Spiegel - - * files.texi (Version Control): Rewrite the introduction about - version systems, mentioning the new ones that we support. - Thanks to Alex Ott, Karl Fogel, Stefan Monnier, and David Kastrup for - suggestions. - -2004-11-03 Jan Djärv - - * frames.texi (Dialog Boxes): Replace non-nil with non-@code{nil}. - -2004-11-02 Jan Djärv - - * frames.texi (Dialog Boxes): Document use-old-gtk-file-dialog. - -2004-10-23 Eli Zaretskii - - * text.texi (Text Based Tables, Table Definition) - (Table Creation, Table Recognition, Cell Commands) - (Cell Justification, Row Commands, Column Commands) - (Fixed Width Mode, Table Conversion, Measuring Tables) - (Table Misc): New nodes, documenting the Table Mode. - -2004-10-19 Jason Rumney - - * makefile.w32-in (info): Change order of arguments to makeinfo. - -2004-10-19 Ulf Jasper - - * calendar.texi (iCalendar): Update for package changes. - -2004-10-09 Luc Teirlinck - - * files.texi (Misc File Ops): View mode is a minor mode. - -2004-10-08 Glenn Morris - - * calendar.texi (iCalendar): Style changes. - -2004-10-07 Luc Teirlinck - - * search.texi (Regexps): The regexp described in the example is no - longer stored in the variable `sentence-end'. - -2004-10-06 Nick Roberts - - * building.texi (Starting GUD): Note that multiple debugging - sessions requires `gdb --fullname'. - -2004-10-05 Ulf Jasper - - * calendar.texi (iCalendar): New section for a new package. - -2004-10-05 Luc Teirlinck - - * text.texi: Various small changes in addition to the following. - (Text): Replace xref for autotype with inforef. - (Sentences): Explain nil value for `sentence-end'. - (Paragraphs): Update default values for `paragraph-start' and - `paragraph-separate'. - (Text Mode): Correct description of Text mode's effect on the - syntax table. - (Outline Visibility): `hide-other' does not hide top level headings. - `selective-display-ellipses' no longer has an effect on Outline mode. - (TeX Misc): Add missing @cindex. - Replace xref for RefTeX with inforef. - (Requesting Formatted Text): The variable - `enriched-fill-after-visiting' no longer exists. - (Editing Format Info): Update names of menu items and commands. - (Format Faces): Mention special effect of specifying the default face. - Describe inheritance of text properties. - Correct description of `fixed' face. - (Format Indentation): Correct description of effect of setting - margins. Mention `set-left-margin' and `set-right-margin'. - (Format Justification): Update names of menu items. - `set-justification-full' is now bound to `M-j b'. - Mention that `default-justification' is a per buffer variable. - (Format Properties): Update name of menu item. - (Forcing Enriched Mode): `format-decode-buffer' automatically - turns on Enriched mode if the buffer is in text/enriched format. - -2004-10-05 Emilio C. Lopes - - * calendar.texi (From Other Calendar): Add calendar-goto-iso-week. - -2004-09-28 Kim F. Storm - - * display.texi (Display Custom) : - Align with new functionality. - -2004-09-22 Luc Teirlinck - - * display.texi (Display Custom): Remove stray `@end defvar'. - -2004-09-23 Kim F. Storm - - * display.texi (Display Custom): Add `overflow-newline-into-fringe', - `indicate-buffer-boundaries' and `default-indicate-buffer-boundaries'. - -2004-09-20 Richard M. Stallman - - * custom.texi (Hooks): Explain using setq to clear out a hook. - (File Variables): Explain multiline string constants. - (Non-ASCII Rebinding): Explain when you need to update - non-ASCII char codes in .emacs. - - * building.texi (Compilation): Explain how to make a silent - subprocess that won't be terminated. Explain compilation-environment. - -2004-09-13 Kim F. Storm - - * mini.texi (Repetition): Rename isearch-resume-enabled to - isearch-resume-in-command-history and change default to disabled. - -2004-09-09 Kim F. Storm - - * kmacro.texi (Save Keyboard Macro): Replace `name-last-kbd-macro' - with new `kmacro-name-last-macro'. - -2004-09-08 Juri Linkov - - * mini.texi (Minibuffer History): Add `history-delete-duplicates'. - -2004-09-03 Juri Linkov - - * search.texi (Incremental Search): Update wording for M-%. - -2004-09-02 Luc Teirlinck - - * killing.texi (Killing): Correct description of kill commands in - read-only buffer. - -2004-09-02 Teodor Zlatanov - - * building.texi (Compilation Mode): Add a paragraph about rules - for finding the compilation buffer for `next-error'. - - * search.texi (Other Repeating Search): Mention that Occur mode - supports the next-error functionality. - -2004-09-02 Juri Linkov - - * search.texi (Regexp Replace): Add missing backslash to \footnote. - -2004-08-31 Luc Teirlinck - - * kmacro.texi (Basic Keyboard Macro): - `apply-macro-to-region-lines' now operates on all lines that begin - in the region, rather than on all complete lines in the region. - -2004-08-31 Jan Djärv - - * frames.texi (Drag and drop): Add documentation about - x-dnd-test-function and x-dnd-known-types. - -2004-08-30 Luc Teirlinck - - * indent.texi: Various minor changes in addition to: - (Indentation Commands): Correct description of `indent-relative'. - (Tab Stops): is no longer bound to `tab-to-tab-stop' in Text - mode. The *Tab Stops* buffer uses Overwrite Mode. - (Just Spaces): `tabify' converts sequences of at least two spaces - to tabs. - -2004-08-27 Luc Teirlinck - - * frames.texi (Secondary Selection): Setting the secondary - selection with M-Drag-Mouse-1 does not alter the kill ring, - setting it with M-Mouse-1 and M-Mouse-3 does. - (Mode Line Mouse): C-Mouse-2 on scroll bar now also works for - toolkit scroll bars. - (Scroll Bars): Ditto. - - * windows.texi (Basic Window): When using a window system, the value - of point in a non-selected window is indicated by a hollow box. - (Split Window): Side by side windows are separated by a scroll bar, - if scroll bars are used. - C-Mouse-2 on scroll bar now also works for toolkit scroll bars. - (Change Window): Correct Mouse-2 vs Mouse-3 mess-up. - (Window Convenience): Update bindings for `winner-undo' and - `winner-redo'. - - * ack.texi (Acknowledgments): Use `@unnumbered'. - * misc.texi: Adapt sectioning in Info to the node structure. - (Invoking emacsclient): Make "Invoking emacsclient" a subsection - of "Using Emacs as a Server". - * building.texi (Building): Interchange nodes (for correct numbering). - * programs.texi (Programs): Interchange nodes (for correct numbering). - * killing.texi, entering.texi, commands.texi: Adapt sectioning in - Info to the node structure. - * emacs.texi: Make "GNU GENERAL PUBLIC LICENSE" an appendix. - Rearrange order of nodes and sections such that both "GNU GENERAL - PUBLIC LICENSE" and "GNU Free Documentation License" appear at the - end, as appropriate for appendices. - (Acknowledgments): Put inside @iftex instead of @ifnotinfo. - Use `@unnumberedsec'. - * trouble.texi: Adapt sectioning in Info to the node structure. - Adapt node pointers to change in emacs.texi. - * cmdargs.texi, doclicense.texi: Adapt node pointers. - -2004-08-25 Kenichi Handa - - * custom.texi (Non-ASCII Rebinding): Fix and simplify the - description for unibyte mode. - -2004-08-23 Luc Teirlinck - - * display.texi (Font Lock): Correct invalid (for hardcopy) @xref. - - * search.texi (Regexps): Correct cryptic (in hardcopy) @ref. - (Configuring Scrolling): Correct invalid (for hardcopy) @xref. - (Regexp Replace): Standardize reference to hardcopy Elisp Manual - in @pxref. - -2004-08-22 Luc Teirlinck - - * kmacro.texi (Keyboard Macro Counter, Keyboard Macro Step-Edit): - Change section names. - -2004-08-21 Luc Teirlinck - - * kmacro.texi (Keyboard Macro Ring): Rename section. - Emacs treats the head of the macro ring as the `last keyboard macro'. - (Keyboard Macro Counter): Minor change. - (Save Keyboard Macro): Some clarifications. - (Edit Keyboard Macro): Rename section. - - * buffers.texi (Buffers): Maximum buffer size is now 256M on - 32-bit machines. - (Several Buffers): Clarify which buffer is selected if `2' is - pressed in the Buffer Menu. - Auto Revert mode can be used to update the Buffer Menu - automatically. - -2004-08-21 Eli Zaretskii - - * help.texi (Misc Help): Add an index entry for finding an Info - manual by its file name. - -2004-08-20 Luc Teirlinck - - * files.texi (Backup Deletion): Correct description of - `delete-old-versions'. - (Time Stamps): `time-stamp' needs to be added to `before-save-hook'. - (Auto Save Files): Recommend `auto-save-mode' to reenable - auto-saving, rather than the abbreviation `auto-save'. - -2004-08-17 Luc Teirlinck - - * emacs.texi (Top): Mention "cutting" and "pasting" as synonyms - for "killing" and "yanking" in main menu. - -2004-08-16 Richard M. Stallman - - * killing.texi (Yanking, Killing): Minor cleanups. - - * mark.texi (Momentary Mark): Minor cleanups. - -2004-08-15 Kenichi Handa - - * custom.texi (Non-ASCII Rebinding): - C-q always inserts the right code to pass to global-set-key. - -2004-08-13 Luc Teirlinck - - * regs.texi (RegNumbers): Mention `C-x r i' binding for - `insert-register', instead of `C-x r g' binding, for consistency. - -2004-08-12 Luc Teirlinck - - * fixit.texi (Spelling): Fix typo. - -2004-08-11 Luc Teirlinck - - * help.texi (Help): Fix Texinfo usage. - -2004-07-24 Richard M. Stallman - - * text.texi (Paragraphs): Update how paragraphs are separated - and the default for paragraph-separate. - - * search.texi (Regexp Replace): Further update text for new - replacement operators. - -2004-07-18 Luc Teirlinck - - * emacs-xtra.texi (Subdir switches): Dired does not remember the - `R' switch. - - * dired.texi (Dired Updating): `k' only deletes inserted - subdirectories from the Dired buffer if a prefix argument was given. - - * search.texi (Regexps): Delete redundant definition of `symbol' in - description of `\_>'. It already occurs in the description of `\_<'. - -2004-07-01 Juri Linkov - - * search.texi (Incremental Search): Add C-M-w, C-M-y, M-%, C-M-%, M-e. - (Regexp Search): Add M-r. - -2004-06-30 Luc Teirlinck - - * makefile.w32-in (EMACSSOURCES): Remove emacs-xtra. - -2004-06-29 Jesper Harder - - * search.texi, calendar.texi: Markup fixes. - -2004-06-25 Richard M. Stallman - - * search.texi (Regexp Replace): Rewrite description of \# \, and \?. - -2004-06-25 David Kastrup - - * search.texi (Regexp Replace): Some typo corrections and - rearrangement. - -2004-06-24 David Kastrup - - * search.texi (Unconditional Replace): Use replace-string instead - of query-replace in example. - (Regexp Replace): Add explanations for `\,', `\#' and `\?' - sequences. - (Query Replace): Correct explanation of `^' which does not use - the mark stack. - -2004-06-21 Nick Roberts - - * misc.texi (Shell History Copying): Document comint-insert-input. - (Shell Ring): Describe comint-dynamic-list-input-ring here. - -2004-06-20 Jesper Harder - - * msdog.texi (Text and Binary, MS-DOS Printing): Use m-dash. - * custom.texi (Customization): Do. - * anti.texi (Antinews): Do. - * abbrevs.texi (Defining Abbrevs): Do. - - * programs.texi (Info Lookup): Fix keybinding for - info-lookup-symbol. - -2004-06-16 Juanma Barranquero - - * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, EMACSSOURCES): - Add emacs-xtra. - ($(infodir)/emacs-xtra, emacs-xtra.dvi): New dependencies. - (clean): Add emacs-xtra and flymake. Remove redundancies. - -2004-06-15 Luc Teirlinck - - * Makefile.in (INFO_TARGETS, DVI_TARGETS, ../info/emacs-xtra): - Add emacs-xtra. - * emacs-xtra.texi: New file. - -2004-06-14 Luc Teirlinck - - * dired.texi (Dired Enter): Mention conditions on `ls' switches. - (Dired and Find): Mention differences with ordinary Dired buffers. - -2004-06-13 Richard M. Stallman - - * custom.texi (Init Syntax): Explain about vars that do special - things when set with setq or with Custom. - (Init Examples): Add line-number-mode example. - -2004-06-12 Juri Linkov - - * dired.texi (Operating on Files): Add dired-do-touch. - -2004-06-10 Juri Linkov - - * building.texi (Lisp Eval): Add C-M-x on defface. - -2004-06-08 Luc Teirlinck - - * files.texi (Reverting): Auto-Revert mode and - Global Auto-Revert mode no longer revert remote files. - -2004-05-29 Richard M. Stallman - - * custom.texi (Init File): Two dashes start --no-site-file. - -2004-05-29 Alan Mackenzie - - * programs.texi: Update for CC Mode 5.30 and incidental amendments. - ("AWK"): Is consistently thus spelled throughout. - (AWK, Pike): Document as "C-like modes". - (@kbd{M-j}): Document as alternative to @kbd{C-M-j}. - (M-x man): Supersedes M-x manual-entry. - Add numerous index entries. Correct "ESC a/e" to "M-a/e". - - ("Comments in C"): Delete node; the info is in CC Mode manual. - (c-comment-only-line-offset): Remove description. - - (C-c ., C-c C-c): Describe new C Mode bindings. - - (C-u TAB, indent-code-rigidly, c-indent-exp, c-tab-always-indent) - (@dfn{Style}, c-default-style, comment-column, comment-padding) - (c-up-conditional, c-beginning-of-statement, c-end-of-statement): - Amend definitions. - - (c-beginning-of-defun, c-end-of-defun, c-context-line-break): - Describe functions. - - (c-comment-start-regexp, c-hanging-comment-ender-p) - (c-hanging-comment-starter-p): Remove obsolete definitions. - - * emacs.texi: Remove the menu entry "Comments in C". - -2004-05-27 Luc Teirlinck - - * dired.texi (Dired and Find): `find-ls-option' does not apply to - `M-x locate'. - -2004-05-16 Karl Berry - - * emacs.texi (ack.texi) [@ifnottex]: Change condition; with @ifinfo, - makeinfo --html fails. - * help.texi (Help Summary) [@ifnottex]: Likewise. - -2004-05-13 Nick Roberts - - * building.texi (GDB Graphical Interface): Update and describe - layout first. - -2004-05-04 Jason Rumney - - * makefile.w32-in: Revert last change. - -2004-05-03 Jason Rumney - - * makefile.w32-in (MULTI_INSTALL_INFO, ENVADD): Use forward slashes. - -2004-04-23 Juanma Barranquero - - * makefile.w32-in: Add "-*- makefile -*-" mode tag. - -2004-04-18 Juri Linkov - - * fixit.texi (Spelling): Remove file extension from ispell xref. - -2004-04-15 Kim F. Storm - - * cmdargs.texi (Initial Options): Add -Q. - -2004-04-05 Kim F. Storm - - * custom.texi (File Variables): Add safe-local-eval-forms. - -2004-04-02 Luc Teirlinck - - * files.texi (Reverting): Correct description of revert-buffer's - handling of point. - -2004-03-22 Juri Linkov - - * emacs.texi (Top): Add `Misc X'. - - * trouble.texi: Fix help key bindings. - - * glossary.texi: Improve references. - - * help.texi: Sync keywords with finder.el. - - * mini.texi (Completion): Add description for menu items. - - * misc.texi (Browse-URL, FFAP): Add information about keywords. - - * sending.texi (Mail Methods): Fix xref to Message manual. - -2004-03-12 Richard M. Stallman - - * buffers.texi (Misc Buffer): Add index entry for rename-uniquely. - -2004-03-04 Richard M. Stallman - - * search.texi (Regexps): Explain that ^ and $ have their - special meanings only in certain contexts. - - * programs.texi (Expressions): Doc C-M-SPC as alias for C-M-@. - - * mule.texi (Specify Coding): Doc C-x RET F. - - * buffers.texi (Misc Buffer): Explain use of M-x rename-uniquely - for multiple compile and grep buffers. - (Indirect Buffers): Don't recommand clone-indirect-buffer - for multiple compile and grep buffers. - -2004-02-29 Juanma Barranquero - - * makefile.w32-in (mostlyclean, clean, maintainer-clean): - Use $(DEL) instead of rm, and ignore exit code. - -2004-02-23 Nick Roberts - - * building.texi (Watch Expressions): Update. - -2004-02-21 Juri Linkov - - * cmdargs.texi (Action Arguments): Add alias --find-file. - Add --directory, --help, --version. Move text about command-line-args - to Command Arguments. - (Initial Options): Add @cindex for --script. Fix @cindex for -q. - Add --no-desktop. Add alias --no-multibyte, --no-unibyte. - (Window Size X): Join -g and --geometry. Add @cindex. - (Borders X): Fix @cindex for -ib. Add @cindex for -bw. - (Title X): Remove alias -title. - (Misc X): New node. - -2004-02-15 Jan Djärv - - * frames.texi (Drag and drop): Add Motif to list of supported - protocols. - -2004-02-03 Jan Djärv - - * frames.texi (Drag and drop): New section. - -2004-01-24 Richard M. Stallman - - * emacs.texi (Acknowledgments): Rename from Acknowledgements. - Include it only @ifnotinfo. Patch the preceding and following - node headers to point to each other. - -2004-01-11 Glenn Morris - - * calendar.texi (Appointments): Update section. - -2003-12-29 Kevin Ryde - - * programs.texi (C Modes): Fix the xref. - -2003-12-23 Nick Roberts - - * building.texi (Watch Expressions): Update. - (Commands of GUD): Include use of toolbar + breakpoints set from - fringe/margin. - -2003-12-03 Andre Spiegel - - * files.texi: Say how to disable VC. Suggested by Alan Mackenzie - . - -2003-11-29 Jan Djärv - - * frames.texi (Dialog Boxes): Add use-file-dialog. - -2003-11-22 Martin Stjernholm - - * ack.texi: Note that Alan Mackenzie contributed the AWK support - in CC Mode. - -2003-11-02 Jesper Harder (tiny change) - - * man/ack.texi, man/basic.texi, man/cmdargs.texi: - * man/commands.texi, man/custom.texi, man/display.texi: - * man/emacs.texi, man/files.texi: - * man/frames.texi, man/glossary.texi, man/killing.texi: - * man/macos.texi, man/mark.texi, man/misc.texi, man/msdog.texi: - * man/mule.texi, man/rmail.texi, man/search.texi: - * man/sending.texi, man/text.texi, man/trouble.texi: - Replace @sc{ascii} and ASCII with @acronym{ASCII}. - -2003-11-01 Alan Mackenzie - - * search.texi (Scrolling During Incremental Search): Document a - new scrolling facility in isearch mode. - -2003-10-22 Miles Bader - - * Makefile.in (info): Move before $(top_srcdir)/info. - -2003-10-22 Nick Roberts - - * building.texi (Watch Expressions): Update section on data display - to reflect code changes (GDB Graphical Interface). - -2003-10-13 Richard M. Stallman - - * xresources.texi (GTK resources): Clean up previous change. - -2003-10-12 Jan Djärv - - * xresources.texi (GTK resources): Add a note that some themes - disallow customizations. Add scroll theme example. - -2003-09-30 Richard M. Stallman - - * cmdargs.texi (General Variables): Remove MAILRC envvar. - - * misc.texi (Saving Emacs Sessions): Shorten the section, - collapsing back into one node. - -2003-09-30 Lars Hansen - - * misc.texi: Section "Saving Emacs Sessions" rewritten. - -2003-09-29 Jan Djärv - - * xresources.texi (GTK names in Emacs): Correct typo. - -2003-09-24 Luc Teirlinck - - * cmdargs.texi (Font X): Mention new default font. - More fully describe long font names, wildcard patterns and the - problems involved. (Result of discussion on emacs-devel.) - -2003-09-22 Luc Teirlinck - - * emacs.texi (Acknowledgements): Correct typo. - -2003-09-22 Richard M. Stallman - - * dired.texi (Misc Dired Commands): New node. - (Dired Navigation): Add dired-goto-file. - - * files.texi (File Aliases, Misc File Ops): Add @cindex entries. - - * emacs.texi (Acknowledgements): New node, split from Distribution. - - * cmdargs.texi (Action Arguments): -f reads interactive args. - -2003-09-08 Lute Kamstra - - * screen.texi (Mode Line): Say that POS comes before LINE. - Mention `size-indication-mode'. - * display.texi (Optional Mode Line): - Document `size-indication-mode'. - * basic.texi (Position Info): Mention `size-indication-mode'. - -2003-09-07 Luc Teirlinck - - * xresources.texi (Resources): Refer to `editres' man page. - (Lucid Resources): Update defaults. Expand description of - `shadowThickness'. - -2003-09-04 Miles Bader - - * Makefile.in (top_srcdir): New variable. - ($(top_srcdir)/info): New rule. - (info): Depend on it. - -2003-09-03 Peter Runestig - - * makefile.w32-in: New file. - -2003-08-29 Richard M. Stallman - - * misc.texi (Saving Emacs Sessions): Correct previous change. - -2003-08-19 Luc Teirlinck - - * emacs.texi (Top): Update menu to reflect new Keyboard Macros chapter. - (Intro): Include kmacro.texi after fixit.texi instead of after - custom.texi. (As suggested by Kim Storm.) - -2003-08-18 Luc Teirlinck - - * fixit.texi (Fixit): Update `Next' pointer. - * files.texi (Files): Update `Previous' pointer. - * kmacro.texi (Keyboard Macros): Remove redundant node and section. - * emacs.texi (Intro): Include kmacro.texi after custom.texi. - (Suggested by Kim Storm.) - * Makefile (EMACSSOURCES): Add kmacro.texi. (Suggested by Kim Storm.) - -2003-08-18 Kim F. Storm - - * kmacro.texi: New file describing enhanced keyboard macro - functionality. Replaces old description in custom.texi. - - * custom.texi (Customization): Add xref to Keyboard Macros chapter. - (Keyboard Macros): Move to new kmacro.texi file. - - * emacs.texi (Keyboard Macros): Reference new keyboard macro topics. - -2003-08-17 Edward M. Reingold - - * calendar.texi (Specified Dates): Add `calendar-goto-day-of-year'. - -2003-08-17 Alex Schroeder - - * misc.texi (Saving Emacs Sessions): Manual M-x desktop-save not - required. - -2003-08-05 Richard M. Stallman - - * programs.texi (Lisp Indent): Don't describe - lisp-indent-function property here. Use xref to Lisp Manual. - -2003-08-03 Glenn Morris - - * calendar.texi (Date Formats): Document changed behavior of - abbreviations. - -2003-07-24 Markus Rost - - * buffers.texi (List Buffers): Fix previous change. - -2003-07-13 Markus Rost - - * buffers.texi (List Buffers): Adjust to new format of *Buffer - List*. - -2003-07-07 Luc Teirlinck - - * display.texi (Font Lock): Fix typo. - -2003-07-07 Richard M. Stallman - - * display.texi (Font Lock): Add xref for format info on - font-lock-remove-keywords. - - * building.texi (Compilation): Document what happens with asynch - children of compiler process. - - * help.texi (Library Keywords): Use @multitable. - -2003-06-04 Richard M. Stallman - - * programs.texi (Expressions): Delete C-M-DEL. - - * misc.texi (Shell Options): Clarify comint-scroll-show-maximum-output. - comint-move-point-for-output renamed from - comint-scroll-to-bottom-on-output. - - * custom.texi (Init Rebinding): Replace previous change with xref. - (Non-ASCII Rebinding): Explain that issue more briefly here. - -2003-05-28 Richard M. Stallman - - * indent.texi (Indentation): Condense, simplify, clarify prev change. - -2003-05-28 Nick Roberts - - * building.texi (GDB Graphical Interface): New node. - (Rewritten somewhat by RMS.) - -2003-05-28 Kai Großjohann - - * custom.texi (Init Rebinding): Xref Non-ASCII Rebinding, for - non-English letters. Explain how to set coding systems correctly - and how to include the right coding cookie in the file. - -2003-05-22 Kai Großjohann - - * indent.texi (Indentation): Explain the concepts. - (Just Spaces): Explain why preventing tabs for indentation might - be useful. - -2003-04-16 Richard M. Stallman - - * search.texi (Regexps): Ref to Lisp manual for more regexp features. - -2003-02-22 Alex Schroeder - - * cmdargs.texi (General Variables): Document SMTPSERVER. - - * sending.texi: Remove SMTP node. - (Mail Sending): Describe `send-mail-function'. Link to SMTP - library. - -2003-02-22 Alex Schroeder - - * sending.texi (Sending via SMTP): Explain MTA/MUA. - -2003-02-22 Simon Josefsson - - * sending.texi (Mail Methods): Add node about SMTP. - -2003-02-17 Jan Djärv - - * xresources.texi (GTK names in Emacs): Add emacs-toolbar - GtkToolbar. - -2003-02-01 Kevin Ryde - - * glossary.texi (Glossary): Correction to cl cross reference. - -2003-01-20 Richard M. Stallman - - * killing.texi (Rectangles): Document C-x c r. - -2003-01-19 Jan Djärv - - * xresources.texi (GTK resources): New node. - (GTK widget names): New node. - (GTK names in Emacs): New node. - (GTK styles): New node. - -2003-01-09 Francesco Potortì - - * maintaining.texi (Create Tags Table): Add reference to the new - `etags --help --lang=LANG' option. - -2002-10-02 Karl Berry - - * emacs.texi: Per rms, update all manuals to use @copying instead of - @ifinfo. Also use @ifnottex instead of @ifinfo around the top node, - where needed for the sake of the HTML output. - -2001-12-20 Eli Zaretskii - - * Makefile.in (EMACSSOURCES): Update the list of Emacs manual - source files. - -2001-11-16 Eli Zaretskii - - * Makefile.in (emacsman): New target. - -2001-10-20 Gerd Moellmann - - * (Version 21.1 released.) - -2001-10-05 Gerd Moellmann - - * Branch for 21.1. - -2001-03-05 Gerd Moellmann - - * Makefile.in (mostlyclean, maintainer-clean): Delete more files. - -2000-05-31 Stefan Monnier - - * .cvsignore (*.tmp): New entry. Seems to be used for @macro. - -1999-07-12 Richard Stallman - - * Version 20.4 released. - -1998-12-04 Markus Rost - - * Makefile.in (INFO_TARGETS): Delete customize.info. - (DVI_TARGETS): Delete customize.dvi. - (../info/customize, customize.dvi): Targets deleted. - -1998-08-19 Richard Stallman - - * Version 20.3 released. - -1998-05-06 Richard Stallman - - * Makefile.in (EMACSSOURCES): Add mule.texi. - Add msdog.texi, ack.texi. Remove gnu1.texi. - -1998-04-06 Andreas Schwab - - * Makefile.in (ENVADD): Environment vars to pass to texi2dvi. - Use it in dvi targets. - -1997-09-23 Paul Eggert - - * Makefile.in: Merge changes mistakenly made to `Makefile'. - (INFO_TARGETS): Change ../info/custom to ../info/customize. - (../info/customize): Rename from ../info/custom. - -1997-09-19 Richard Stallman - - * Version 20.2 released. - -1997-09-15 Richard Stallman - - * Version 20.1 released. - -1997-08-24 Richard Stallman - - * Makefile (../info/customize, customize.dvi): New targets. - (INFO_TARGETS): Add ../info/customize. - (DVI_TARGETS): Add customize.dvi. - -1996-08-11 Richard Stallman - - * Version 19.33 released. - -1996-07-31 Richard Stallman - - * Version 19.32 released. - -1996-06-20 Richard Stallman - - * Makefile.in (All info targets): cd $(srcdir) to do the work. - -1996-06-19 Richard Stallman - - * Makefile.in (All info targets): Specify $(srcdir) in input files. - Specify -I option. - (All dvi targets): Set the TEXINPUTS variable. - -1996-05-25 Karl Heuer - - * Version 19.31 released. - -1995-11-24 Richard Stallman - - * Version 19.30 released. - -1995-02-07 Richard Stallman - - * Makefile.in (maintainer-clean): Rename from realclean. - -1994-11-23 Richard Stallman - - * Makefile.in: New file. - * Makefile: File deleted. - -1994-11-19 Richard Stallman - - * Makefile (TEXINDEX_OBJS): Variable deleted. - (texindex, texindex.o, getopt.o): Rules deleted. - All deps on texindex deleted. - (distclean): Don't delete texindex. - (mostlyclean): Don't delete *.o. - * texindex.c, getopt.c: Files deleted. - -1994-09-07 Richard Stallman - - * Version 19.26 released. - -1994-07-02 Richard Stallman (rms@gnu.ai.mit.edu) - - * Makefile (EMACSSOURCES): Exclude undo.texi. - -1994-05-30 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.25 released. - -1994-05-23 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.24 released. - -1994-05-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.23 released. - -1994-04-17 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile: Delete spurious tab. - -1994-02-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (.SUFFIXES): New rule. - -1993-12-04 Richard Stallman (rms@srarc2) - - * getopt.c: New file. - * Makefile (TEXINDEX_OBJS): Use getopt.o in this dir, not ../lib-src. - (getopt.o): New rule. - (dvi): Don't depend on texindex. - (emacs.dvi): Depend on texindex. - -1993-12-03 Richard Stallman (rms@srarc2) - - * Makefile (TEXI2DVI): New variable. - (emacs.dvi): Add explicit command. - (TEXINDEX_OBJS): Delete duplicate getopt.o. - -1993-11-27 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.22 released. - -1993-11-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (TEXINDEX_OBJS): Delete spurious period. - -1993-11-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.21 released. - -1993-11-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (realclean): Don't delete the Info files. - -1993-10-25 Brian J. Fox (bfox@albert.gnu.ai.mit.edu) - - * frames.texi (Creating Frames): Mention `C-x 5' instead of `C-x - 4' where appropriate. - -1993-10-20 Brian J. Fox (bfox@ai.mit.edu) - - * Makefile: Fix targets for texindex. - - * texindex.c: Include "../src/config.h" if building in emacs. - - * Makefile: Change all files to FILENAME.texi, force all targets - to be FILENAME, not FILENAME.info. - Add target to build texindex.c, defining `emacs'. - -1993-08-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.19 released. - -1993-08-08 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.18 released. - -1993-07-20 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile: Fix source file names of the separate manuals. - -1993-07-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.17 released. - -1993-07-10 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * split-man: Fix typos in last change. - -1993-07-06 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Version 19.16 released. - -1993-06-19 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * version 19.15 released. - -1993-06-18 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Makefile (distclean): It's rm, not rf. - -1993-06-17 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Version 19.14 released. - -1993-06-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile: New file. - -1993-06-08 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Version 19.13 released. - -1993-05-27 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Version 19.9 released. - -1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Version 19.8 released. - -1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * cmdargs.texi: Document the -i, -itype, and -iconic options. - - * trouble.texi: It's `enable-flow-control-on', not - `evade-flow-control-on'. - -1993-05-24 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * display.texi: Document standard-display-european. - -1993-05-22 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Version 19.7 released. - - * emacs.texi: Add a sentence to the top menu mentioning the - specific version of Emacs this manual applies to. - -1993-04-25 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * basic.texi: Document next-line-add-lines variable used to - implement down-arrow. - - * killing.texi: Document kill-whole-line. - -1993-04-18 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) - - * text.texi: Update unix TeX ordering information. - -1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) - - * news.texi: Mention fill-rectangle in keybinding list. - - * killing.texi: Document fill-rectangle. - -1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * vc.texi: Bring the docs up to date with VC 5.2. - -1992-01-10 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * emacs.tex: Mention blackbox and gomoku under Amusements. - Assembler mode is now mentioned and appropriately indexed - under Programming Modes. - -1991-02-15 Robert J. Chassell (bob@wookumz.ai.mit.edu) - - * emacs.tex: Update TeX ordering information. - -1990-06-26 David Lawrence (tale@geech) - - * emacs.tex: Note that completion-ignored-extensions is not used - to filter out names when all completions are displayed in - *Completions*. - -1990-05-25 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - - * texindex.tex: If USG, include sys/types.h and sys/fcntl.h. - -1990-03-21 Jim Kingdon (kingdon@pogo.ai.mit.edu) - - * emacs.tex: Add @findex grep. - -1988-08-16 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) - - * emacs.tex: Correct two typos. No other changes before - Version 19 will be made. - -1988-05-23 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) - - * emacs.tex: Update information for obtaining TeX distribution from the - University of Washington. - -;; Local Variables: -;; coding: utf-8 -;; End: - - Copyright (C) 1993-1999, 2001-2012 Free Software Foundation, Inc. - - This file is part of GNU Emacs. - - GNU Emacs is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - GNU Emacs is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNU Emacs. If not, see . diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in deleted file mode 100644 index b25f6dbe490..00000000000 --- a/doc/emacs/Makefile.in +++ /dev/null @@ -1,194 +0,0 @@ -#### Makefile for the Emacs Manual - -# Copyright (C) 1994, 1996-2012 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -SHELL = /bin/sh - -# Where to find the source code. $(srcdir) will be the doc/emacs subdirectory -# of the source tree. This is set by configure's `--srcdir' option. -srcdir=@srcdir@ - -# Only for make dist. -version=@version@ - -## Where the output files go. -## Note that the setfilename command in the .texi files assumes this. -## This is a bit funny. Because the info files are in the -## distribution tarfiles, they are always made in $scrdir/../../info, -## even for out-of-tree builds. -infodir = $(srcdir)/../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc - -# The makeinfo program is part of the Texinfo distribution. -# Use --force so that it generates output even if there are errors. -MAKEINFO = @MAKEINFO@ -MAKEINFO_OPTS = --force --enable-encoding -I $(srcdir) - -TEXI2DVI = texi2dvi -TEXI2PDF = texi2pdf -DVIPS = dvips - - -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" - - -EMACS_XTRA= \ - ${srcdir}/emacs-xtra.texi \ - $(srcdir)/arevert-xtra.texi \ - $(srcdir)/cal-xtra.texi \ - $(srcdir)/dired-xtra.texi \ - $(srcdir)/picture-xtra.texi \ - $(srcdir)/emerge-xtra.texi \ - $(srcdir)/vc-xtra.texi \ - $(srcdir)/vc1-xtra.texi \ - $(srcdir)/fortran-xtra.texi \ - $(srcdir)/msdog-xtra.texi - -EMACSSOURCES= \ - ${srcdir}/emacs.texi \ - ${srcdir}/emacsver.texi \ - ${srcdir}/doclicense.texi \ - ${srcdir}/gpl.texi \ - ${srcdir}/screen.texi \ - ${srcdir}/commands.texi \ - ${srcdir}/entering.texi \ - ${srcdir}/basic.texi \ - ${srcdir}/mini.texi \ - ${srcdir}/m-x.texi \ - ${srcdir}/help.texi \ - ${srcdir}/mark.texi \ - ${srcdir}/killing.texi \ - ${srcdir}/regs.texi \ - ${srcdir}/display.texi \ - ${srcdir}/search.texi \ - ${srcdir}/fixit.texi \ - ${srcdir}/files.texi \ - ${srcdir}/buffers.texi \ - ${srcdir}/windows.texi \ - ${srcdir}/frames.texi \ - ${srcdir}/mule.texi \ - ${srcdir}/modes.texi \ - ${srcdir}/indent.texi \ - ${srcdir}/text.texi \ - ${srcdir}/programs.texi \ - ${srcdir}/building.texi \ - ${srcdir}/maintaining.texi \ - ${srcdir}/abbrevs.texi \ - ${srcdir}/sending.texi \ - ${srcdir}/rmail.texi \ - ${srcdir}/dired.texi \ - ${srcdir}/calendar.texi \ - ${srcdir}/misc.texi \ - ${srcdir}/package.texi \ - ${srcdir}/custom.texi \ - ${srcdir}/trouble.texi \ - ${srcdir}/cmdargs.texi \ - ${srcdir}/xresources.texi \ - ${srcdir}/anti.texi \ - ${srcdir}/macos.texi \ - ${srcdir}/msdog.texi \ - ${srcdir}/gnu.texi \ - ${srcdir}/glossary.texi \ - ${srcdir}/ack.texi \ - ${srcdir}/kmacro.texi \ - $(EMACS_XTRA) - -## This seems pointless. The info/ directory exists in both the -## repository and the release tarfiles. We do not use any -## equivalent of mkdir -p/install-sh -d, so this is not a general -## solution anyway. The second test -d is for parallel builds. -mkinfodir = @test -d ${infodir} || mkdir ${infodir} || test -d ${infodir} - -.PHONY: info dvi html pdf ps - -info: $(infodir)/emacs -dvi: emacs.dvi -html: emacs.html -pdf: emacs.pdf -ps: emacs.ps - -# Note that all the Info targets build the Info files in srcdir. -# There is no provision for Info files to exist in the build directory. -# In a distribution of Emacs, the Info files should be up to date. -# Note: "<" is not portable in ordinary make rules. -$(infodir)/emacs: ${EMACSSOURCES} - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) -o $@ ${srcdir}/emacs.texi - -emacs.dvi: ${EMACSSOURCES} - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs.texi - -emacs.ps: emacs.dvi - $(DVIPS) -o $@ emacs.dvi - -emacs.pdf: ${EMACSSOURCES} - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs.texi - -emacs.html: ${EMACSSOURCES} - $(MAKEINFO) $(MAKEINFO_OPTS) --html -o $@ ${srcdir}/emacs.texi - -emacs-xtra.dvi: $(EMACS_XTRA) - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-xtra.texi - -emacs-xtra.ps: emacs-xtra.dvi - $(DVIPS) -o $@ emacs-xtra.dvi - -emacs-xtra.pdf: $(EMACS_XTRA) - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-xtra.texi - -.PHONY: mostlyclean clean distclean maintainer-clean infoclean - -## Temp files. -mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs - -## Products not in the release tarfiles. -clean: mostlyclean - rm -f emacs.dvi emacs-xtra.dvi emacs.pdf emacs-xtra.pdf \ - emacs.ps emacs-xtra.ps - rm -rf emacs.html/ - rm -f emacs-manual-${version}.tar* - -distclean: clean - -## In the standalone tarfile, the clean rule runs this. -infoclean: - -cd $(infodir) && rm -f emacs emacs-[1-9] emacs-[1-9][0-9] - -maintainer-clean: distclean infoclean - -.PHONY: dist - -## Make a standalone tarfile of the Emacs manual sources. -## The [c] is a dumb way to prevent configure expanding it. -dist: - rm -rf emacs-manual-${version} - mkdir emacs-manual-${version} - cp ${srcdir}/*.texi ${texinfodir}/texinfo.tex \ - ${srcdir}/ChangeLog* emacs-manual-${version}/ - sed -e 's/@sr[c]dir@/./' -e 's/^\(texinfodir *=\).*/\1 ./' \ - -e 's/^\(infodir *=\).*/\1 ./' -e 's/^\(clean:.*\)/\1 infoclean/' \ - -e "s/@ver[s]ion@/${version}/" \ - ${srcdir}/Makefile.in > emacs-manual-${version}/Makefile - tar -cf emacs-manual-${version}.tar emacs-manual-${version} - rm -rf emacs-manual-${version} - -### Makefile ends here diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi deleted file mode 100644 index d3c914d92b0..00000000000 --- a/doc/emacs/abbrevs.texi +++ /dev/null @@ -1,447 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Abbrevs -@chapter Abbrevs -@cindex abbrevs -@cindex expansion (of abbrevs) - - A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert -it, into some different text. Abbrevs are defined by the user to expand -in specific ways. For example, you might define @samp{foo} as an abbrev -expanding to @samp{find outer otter}. Then you could insert -@samp{find outer otter } into the buffer by typing @kbd{f o o -@key{SPC}}. - - A second kind of abbreviation facility is called @dfn{dynamic abbrev -expansion}. You use dynamic abbrev expansion with an explicit command -to expand the letters in the buffer before point by looking for other -words in the buffer that start with those letters. @xref{Dynamic -Abbrevs}. - - ``Hippie'' expansion generalizes abbreviation expansion. -@xref{Hippie Expand, , Hippie Expansion, autotype, Features for -Automatic Typing}. - -@menu -* Abbrev Concepts:: Fundamentals of defined abbrevs. -* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. -* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. -* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. -* Saving Abbrevs:: Saving the entire list of abbrevs for another session. -* Dynamic Abbrevs:: Abbreviations for words already in the buffer. -* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling. -@end menu - -@node Abbrev Concepts -@section Abbrev Concepts - - An @dfn{abbrev} is a word that has been defined to @dfn{expand} into -a specified @dfn{expansion}. When you insert a word-separator character -following the abbrev, that expands the abbrev---replacing the abbrev -with its expansion. For example, if @samp{foo} is defined as an abbrev -expanding to @samp{find outer otter}, then typing @kbd{f o o .} will -insert @samp{find outer otter.}. - -@findex abbrev-mode -@cindex Abbrev mode -@cindex mode, Abbrev - Abbrevs expand only when Abbrev mode, a buffer-local minor mode, is -enabled. Disabling Abbrev mode does not cause abbrev definitions to -be forgotten, but they do not expand until Abbrev mode is enabled -again. The command @kbd{M-x abbrev-mode} toggles Abbrev mode; with a -numeric argument, it turns Abbrev mode on if the argument is positive, -off otherwise. @xref{Minor Modes}. - - Abbrevs can have @dfn{mode-specific} definitions, active only in one major -mode. Abbrevs can also have @dfn{global} definitions that are active in -all major modes. The same abbrev can have a global definition and various -mode-specific definitions for different major modes. A mode-specific -definition for the current major mode overrides a global definition. - - You can define abbrevs interactively during the editing session, -irrespective of whether Abbrev mode is enabled. You can also save -lists of abbrev definitions in files, which you can the reload for use -in later sessions. - -@node Defining Abbrevs -@section Defining Abbrevs - -@table @kbd -@item C-x a g -Define an abbrev, using one or more words before point as its expansion -(@code{add-global-abbrev}). -@item C-x a l -Similar, but define an abbrev specific to the current major mode -(@code{add-mode-abbrev}). -@item C-x a i g -Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}). -@item C-x a i l -Define a word in the buffer as a mode-specific abbrev -(@code{inverse-add-mode-abbrev}). -@item M-x define-global-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} -Define @var{abbrev} as an abbrev expanding into @var{exp}. -@item M-x define-mode-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} -Define @var{abbrev} as a mode-specific abbrev expanding into @var{exp}. -@item M-x kill-all-abbrevs -Discard all abbrev definitions, leaving a blank slate. -@end table - -@kindex C-x a g -@findex add-global-abbrev - The usual way to define an abbrev is to enter the text you want the -abbrev to expand to, position point after it, and type @kbd{C-x a g} -(@code{add-global-abbrev}). This reads the abbrev itself using the -minibuffer, and then defines it as an abbrev for one or more words before -point. Use a numeric argument to say how many words before point should be -taken as the expansion. For example, to define the abbrev @samp{foo} as -mentioned above, insert the text @samp{find outer otter} and then type -@kbd{C-u 3 C-x a g f o o @key{RET}}. - - An argument of zero to @kbd{C-x a g} means to use the contents of the -region as the expansion of the abbrev being defined. - -@kindex C-x a l -@findex add-mode-abbrev - The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but -defines a mode-specific abbrev for the current major mode. The -arguments work the same as for @kbd{C-x a g}. - -@kindex C-x a i g -@findex inverse-add-global-abbrev -@kindex C-x a i l -@findex inverse-add-mode-abbrev - @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and @kbd{C-x a i -l} (@code{inverse-add-mode-abbrev}) perform the opposite task: if the -abbrev text is already in the buffer, you use these commands to define -an abbrev by specifying the expansion in the minibuffer. These -commands will expand the abbrev text used for the definition. - -@findex define-mode-abbrev -@findex define-global-abbrev - You can define an abbrev without inserting either the abbrev or its -expansion in the buffer using the command @code{define-global-abbrev}. -It reads two arguments---the abbrev, and its expansion. The command -@code{define-mode-abbrev} does likewise for a mode-specific abbrev. - - To change the definition of an abbrev, just make a new definition. -When an abbrev has a prior definition, the abbrev definition commands -ask for confirmation before replacing it. - -@findex kill-all-abbrevs - To remove an abbrev definition, give a negative argument to the -abbrev definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}. -The former removes a global definition, while the latter removes a -mode-specific definition. @kbd{M-x kill-all-abbrevs} removes all -abbrev definitions, both global and local. - -@node Expanding Abbrevs -@section Controlling Abbrev Expansion - - When Abbrev mode is enabled, an abbrev expands whenever it is -present in the buffer just before point and you type a self-inserting -whitespace or punctuation character (@key{SPC}, comma, etc.@:). More -precisely, any character that is not a word constituent expands an -abbrev, and any word-constituent character can be part of an abbrev. -The most common way to use an abbrev is to insert it and then insert a -punctuation or whitespace character to expand it. - -@vindex abbrev-all-caps - Abbrev expansion preserves case: @samp{foo} expands to @samp{find -outer otter}, and @samp{Foo} to @samp{Find outer otter}. @samp{FOO} -expands to @samp{Find Outer Otter} by default, but if you change the -variable @code{abbrev-all-caps} to a non-@code{nil} value, it expands -to @samp{FIND OUTER OTTER}. - - These commands are used to control abbrev expansion: - -@table @kbd -@item M-' -Separate a prefix from a following abbrev to be expanded -(@code{abbrev-prefix-mark}). -@item C-x a e -@findex expand-abbrev -Expand the abbrev before point (@code{expand-abbrev}). -This is effective even when Abbrev mode is not enabled. -@item M-x expand-region-abbrevs -Expand some or all abbrevs found in the region. -@end table - -@kindex M-' -@findex abbrev-prefix-mark - You may wish to expand an abbrev and attach a prefix to the expansion; -for example, if @samp{cnst} expands into @samp{construction}, you might want -to use it to enter @samp{reconstruction}. It does not work to type -@kbd{recnst}, because that is not necessarily a defined abbrev. What -you can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) in -between the prefix @samp{re} and the abbrev @samp{cnst}. First, insert -@samp{re}. Then type @kbd{M-'}; this inserts a hyphen in the buffer to -indicate that it has done its work. Then insert the abbrev @samp{cnst}; -the buffer now contains @samp{re-cnst}. Now insert a non-word character -to expand the abbrev @samp{cnst} into @samp{construction}. This -expansion step also deletes the hyphen that indicated @kbd{M-'} had been -used. The result is the desired @samp{reconstruction}. - - If you actually want the text of the abbrev in the buffer, rather than -its expansion, you can accomplish this by inserting the following -punctuation with @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} in -the buffer, not expanding it. - -@findex unexpand-abbrev - If you expand an abbrev by mistake, you can undo the expansion by -typing @kbd{C-/} (@code{undo}). @xref{Undo}. This undoes the -insertion of the abbrev expansion and brings back the abbrev text. If -the result you want is the terminating non-word character plus the -unexpanded abbrev, you must reinsert the terminating character, -quoting it with @kbd{C-q}. You can also use the command @kbd{M-x -unexpand-abbrev} to cancel the last expansion without deleting the -terminating character. - -@findex expand-region-abbrevs - @kbd{M-x expand-region-abbrevs} searches through the region for defined -abbrevs, and for each one found offers to replace it with its expansion. -This command is useful if you have typed in text using abbrevs but forgot -to turn on Abbrev mode first. It may also be useful together with a -special set of abbrev definitions for making several global replacements at -once. This command is effective even if Abbrev mode is not enabled. - - Expanding any abbrev runs @code{abbrev-expand-functions}, a special -hook. Functions in this special hook can make arbitrary changes to -the abbrev expansion. @xref{Abbrev Expansion,,, elisp, The Emacs Lisp -Reference Manual}. - -@node Editing Abbrevs -@section Examining and Editing Abbrevs - -@table @kbd -@item M-x list-abbrevs -Display a list of all abbrev definitions. With a numeric argument, list -only local abbrevs. -@item M-x edit-abbrevs -Edit a list of abbrevs; you can add, alter or remove definitions. -@end table - -@findex list-abbrevs - The output from @kbd{M-x list-abbrevs} looks like this: - -@example -@var{various other tables@dots{}} -(lisp-mode-abbrev-table) -"dk" 0 "define-key" -(global-abbrev-table) -"dfn" 0 "definition" -@end example - -@noindent -(Some blank lines of no semantic significance, and some other abbrev -tables, have been omitted.) - - A line containing a name in parentheses is the header for abbrevs in a -particular abbrev table; @code{global-abbrev-table} contains all the global -abbrevs, and the other abbrev tables that are named after major modes -contain the mode-specific abbrevs. - - Within each abbrev table, each nonblank line defines one abbrev. The -word at the beginning of the line is the abbrev. The number that -follows is the number of times the abbrev has been expanded. Emacs -keeps track of this to help you see which abbrevs you actually use, so -that you can eliminate those that you don't use often. The string at -the end of the line is the expansion. - - Some abbrevs are marked with @samp{(sys)}. These ``system'' abbrevs -(@pxref{Abbrevs,,, elisp, The Emacs Lisp Reference Manual}) are -pre-defined by various modes, and are not saved to your abbrev file. -To disable a ``system'' abbrev, define an abbrev of the same name that -expands to itself, and save it to your abbrev file. - -@findex edit-abbrevs -@kindex C-c C-c @r{(Edit Abbrevs)} - @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev -definitions by editing a list of them in an Emacs buffer. The list has -the same format described above. The buffer of abbrevs is called -@file{*Abbrevs*}, and is in Edit-Abbrevs mode. Type @kbd{C-c C-c} in -this buffer to install the abbrev definitions as specified in the -buffer---and delete any abbrev definitions not listed. - - The command @code{edit-abbrevs} is actually the same as -@code{list-abbrevs} except that it selects the buffer @file{*Abbrevs*} -whereas @code{list-abbrevs} merely displays it in another window. - -@node Saving Abbrevs -@section Saving Abbrevs - - These commands allow you to keep abbrev definitions between editing -sessions. - -@table @kbd -@item M-x write-abbrev-file @key{RET} @var{file} @key{RET} -Write a file @var{file} describing all defined abbrevs. -@item M-x read-abbrev-file @key{RET} @var{file} @key{RET} -Read the file @var{file} and define abbrevs as specified therein. -@item M-x define-abbrevs -Define abbrevs from definitions in current buffer. -@item M-x insert-abbrevs -Insert all abbrevs and their expansions into current buffer. -@end table - -@findex write-abbrev-file - @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and -then writes a description of all current abbrev definitions into that -file. This is used to save abbrev definitions for use in a later -session. The text stored in the file is a series of Lisp expressions -that, when executed, define the same abbrevs that you currently have. - -@findex read-abbrev-file -@findex quietly-read-abbrev-file -@vindex abbrev-file-name -@cindex abbrev file - @kbd{M-x read-abbrev-file} reads a file name using the minibuffer -and then reads the file, defining abbrevs according to the contents of -the file. The function @code{quietly-read-abbrev-file} is similar -except that it does not display a message in the echo area; you cannot -invoke it interactively, and it is used primarily in your init file -(@pxref{Init File}). If either of these functions is called with -@code{nil} as the argument, it uses the file given by the variable -@code{abbrev-file-name}, which is @file{~/.emacs.d/abbrev_defs} by -default. This is your standard abbrev definition file, and Emacs -loads abbrevs from it automatically when it starts up. (As an -exception, Emacs does not load the abbrev file when it is started in -batch mode. @xref{Initial Options}, for a description of batch mode.) - -@vindex save-abbrevs - Emacs will offer to save abbrevs automatically if you have changed -any of them, whenever it offers to save all files (for @kbd{C-x s} or -@kbd{C-x C-c}). It saves them in the file specified by -@code{abbrev-file-name}. This feature can be inhibited by setting the -variable @code{save-abbrevs} to @code{nil}. - -@findex insert-abbrevs -@findex define-abbrevs - The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are -similar to the previous commands but work on text in an Emacs buffer. -@kbd{M-x insert-abbrevs} inserts text into the current buffer after point, -describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses -the entire current buffer and defines abbrevs accordingly. - -@node Dynamic Abbrevs -@section Dynamic Abbrev Expansion - - The abbrev facility described above operates automatically as you -insert text, but all abbrevs must be defined explicitly. By contrast, -@dfn{dynamic abbrevs} allow the meanings of abbreviations to be -determined automatically from the contents of the buffer, but dynamic -abbrev expansion happens only when you request it explicitly. - -@kindex M-/ -@kindex C-M-/ -@findex dabbrev-expand -@findex dabbrev-completion -@table @kbd -@item M-/ -Expand the word in the buffer before point as a @dfn{dynamic abbrev}, -by searching in the buffer for words starting with that abbreviation -(@code{dabbrev-expand}). - -@item C-M-/ -Complete the word before point as a dynamic abbrev -(@code{dabbrev-completion}). -@end table - -@vindex dabbrev-limit - For example, if the buffer contains @samp{does this follow } and you -type @kbd{f o M-/}, the effect is to insert @samp{follow} because that -is the last word in the buffer that starts with @samp{fo}. A numeric -argument to @kbd{M-/} says to take the second, third, etc.@: distinct -expansion found looking backward from point. Repeating @kbd{M-/} -searches for an alternative expansion by looking farther back. After -scanning all the text before point, it searches the text after point. -The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far -away in the buffer to search for an expansion. - -@vindex dabbrev-check-all-buffers - After scanning the current buffer, @kbd{M-/} normally searches other -buffers, unless you have set @code{dabbrev-check-all-buffers} to -@code{nil}. - -@vindex dabbrev-ignored-buffer-regexps - For finer control over which buffers to scan, customize the variable -@code{dabbrev-ignored-buffer-regexps}. Its value is a list of regular -expressions. If a buffer's name matches any of these regular -expressions, dynamic abbrev expansion skips that buffer. - - A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to -search first for expansions after point, then other buffers, and -consider expansions before point only as a last resort. If you repeat -the @kbd{M-/} to look for another expansion, do not specify an -argument. Repeating @kbd{M-/} cycles through all the expansions after -point and then the expansions before point. - - After you have expanded a dynamic abbrev, you can copy additional -words that follow the expansion in its original context. Simply type -@kbd{@key{SPC} M-/} for each additional word you want to copy. The -spacing and punctuation between words is copied along with the words. - - The command @kbd{C-M-/} (@code{dabbrev-completion}) performs -completion of a dynamic abbrev. Instead of trying the possible -expansions one by one, it finds all of them, then inserts the text -that they have in common. If they have nothing in common, @kbd{C-M-/} -displays a list of completions, from which you can select a choice in -the usual manner. @xref{Completion}. - - Dynamic abbrev expansion is completely independent of Abbrev mode; the -expansion of a word with @kbd{M-/} is completely independent of whether -it has a definition as an ordinary abbrev. - -@node Dabbrev Customization -@section Customizing Dynamic Abbreviation - - Normally, dynamic abbrev expansion ignores case when searching for -expansions. That is, the expansion need not agree in case with the word -you are expanding. - -@vindex dabbrev-case-fold-search - This feature is controlled by the variable -@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored -in this search; if it is @code{nil}, the word and the expansion must -match in case. If the value is @code{case-fold-search} (the default), -then the variable @code{case-fold-search} controls whether to ignore -case while searching for expansions (@pxref{Search Case}). - -@vindex dabbrev-case-replace - Normally, dynamic abbrev expansion preserves the case pattern -@emph{of the dynamic abbrev you are expanding}, by converting the -expansion to that case pattern. - -@vindex dabbrev-case-fold-search - The variable @code{dabbrev-case-replace} controls whether to -preserve the case pattern of the dynamic abbrev. If it is @code{t}, -the dynamic abbrev's case pattern is preserved in most cases; if it is -@code{nil}, the expansion is always copied verbatim. If the value is -@code{case-replace} (the default), then the variable -@code{case-replace} controls whether to copy the expansion verbatim -(@pxref{Replacement and Case}). - - However, if the expansion contains a complex mixed case pattern, and -the dynamic abbrev matches this pattern as far as it goes, then the -expansion is always copied verbatim, regardless of those variables. -Thus, for example, if the buffer contains -@code{variableWithSillyCasePattern}, and you type @kbd{v a M-/}, it -copies the expansion verbatim including its case pattern. - -@vindex dabbrev-abbrev-char-regexp - The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil}, -controls which characters are considered part of a word, for dynamic expansion -purposes. The regular expression must match just one character, never -two or more. The same regular expression also determines which -characters are part of an expansion. The value @code{nil} has a special -meaning: dynamic abbrevs are made of word characters, but expansions are -made of word and symbol characters. - -@vindex dabbrev-abbrev-skip-leading-regexp - In shell scripts and makefiles, a variable name is sometimes prefixed -with @samp{$} and sometimes not. Major modes for this kind of text can -customize dynamic abbrev expansion to handle optional prefixes by setting -the variable @code{dabbrev-abbrev-skip-leading-regexp}. Its value -should be a regular expression that matches the optional prefix that -dynamic abbrev expression should ignore. diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi deleted file mode 100644 index 5e4e6f25474..00000000000 --- a/doc/emacs/ack.texi +++ /dev/null @@ -1,1446 +0,0 @@ -@c -*- coding: iso-latin-1 -*- -@c This is part of the Emacs manual. -@c Copyright (C) 1994-1997, 1999-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@node Acknowledgments, Screen, Concept Index, Top -@unnumbered Acknowledgments - -Many people have contributed code included in the Free Software -Foundation's distribution of GNU Emacs. To show our appreciation for -their public spirit, we list here in alphabetical order those who have -written substantial portions. Others too numerous to mention have -reported and fixed bugs, and added features to many parts of Emacs. -We thank them for their generosity as well. - -This list is intended to mention every contributor of a major package or -feature we currently distribute; if you know of someone we have omitted, -please report that as a manual bug. More comprehensive information is -available in the @file{ChangeLog} files, summarized in the file -@file{etc/AUTHORS} in the distribution. - -@c We should list here anyone who has contributed a new package, -@c and anyone who has made major enhancements in Emacs -@c that many users would notice and consider important. -@c Remove things that are no longer distributed. -@c Note this file is only used ifnottex; otherwise a shorter version in -@c emacs.texi is used. - -@itemize @bullet -@item -Per Abrahamsen wrote the customization facilities, as well as -@file{double.el}, for typing accented characters not normally available -from the keyboard; @file{xt-mouse.el}, which allows mouse commands -through Xterm; @file{gnus-cus.el}, which implements customization -commands for Gnus; @file{gnus-cite.el}, a citation-parsing facility for -news articles; @file{gnus-score.el}, scoring for Gnus; @file{cpp.el}, -which hides or highlights parts of C programs according to preprocessor -conditionals; and the widget library files @file{wid-browse.el}, -@file{wid-edit.el}, @file{widget.el}. He also co-wrote -@file{gnus-soup.el}. - -@item -Tomas Abrahamsson wrote @file{artist.el}, a package for producing -@acronym{ASCII} art with a mouse or with keyboard keys. - -@item -Jay K.@: Adams wrote @file{jka-compr.el} and @file{jka-cmpr-hook.el}, -providing automatic decompression and recompression for compressed -files. - -@item -Michael Albinus wrote @file{dbus.el}, a package that implements the -D-Bus message bus protocol; @file{zeroconf.el}, a mode for browsing -Avahi services; @file{xesam.el}, a Xesam-based search engine -interface; and @file{secrets.el}, an interface to keyring daemons for -storing confidential data. He and Kai Großjohann wrote the Tramp package, which -provides transparent remote file editing using rcp, ssh, ftp, and -other network protocols. He and Daniel Pittman wrote -@file{tramp-cache.el}. - -@item -Ralf Angeli wrote @file{scroll-lock.el}, a minor mode which keeps the -point vertically fixed by scrolling the window when moving up and down -in the buffer. - -@item -Joe Arceneaux wrote the original text property implementation, and -implemented support for X11. - -@item -Emil Åström, Milan Zamaza, and Stefan Bruda wrote @file{prolog.el}, -a mode for editing Prolog (and Mercury) code. - -@item -Miles Bader wrote @file{image-file.el}, support code for visiting image -files; @file{minibuf-eldef.el}, a minor mode that hides the minibuffer -default value when appropriate; @file{rfn-eshadow.el}, shadowing of -@code{read-file-name} input; @file{mb-depth.el}, display of minibuffer -depth; @file{button.el}, the library that implements clickable buttons; -@file{face-remap.el}, a package for changing the default face in -individual buffers; and @file{macroexp.el} for macro-expansion. He -also worked on an early version of the lexical binding code. - -@item -David Bakhash wrote @file{strokes.el}, a mode for controlling Emacs by -moving the mouse in particular patterns. - -@item -Juanma Barranquero wrote @file{emacs-lock.el} (based on the original -version by Tom Wurgler), which makes it harder to exit with valuable -buffers unsaved. He also made many other contributions to other -areas, including MS Windows support. - -@item -Eli Barzilay wrote @file{calculator.el}, a desktop calculator for -Emacs. - -@item -Steven L.@: Baur wrote @file{footnote.el} which lets you include -footnotes in email messages; and @file{gnus-audio.el} and -@file{earcon.el}, which provide sound effects for Gnus. He also wrote -@file{gnus-setup.el}. - -@item -Alexander L.@: Belikoff, Sergey Berezin, Sacha Chua, David Edmondson, -Noah Friedman, Andreas Fuchs, Mario Lang, Ben Mesander, Lawrence -Mitchell, Gergely Nagy, Michael Olson, Per Persson, Jorgen Schaefer, -Alex Schroeder, and Tom Tromey wrote ERC, an advanced Internet Relay -Chat client (for more information, see the file @file{CREDITS} in the -ERC distribution). - -@item -Scott Bender, Michael Brouwer, Christophe de Dinechin, Carl Edman, -Christian Limpach and Adrian Robert developed and maintained the -NeXTstep port of Emacs. - -@item -Anna M.@: Bigatti wrote @file{cal-html.el}, which produces HTML calendars. - -@item -Ray Blaak and Simon South wrote @file{delphi.el}, a mode for editing -Delphi (Object Pascal) source code. - -@item -Martin Blais, Stefan Merten, and David Goodger wrote @file{rst.el}, a -mode for editing reStructuredText documents. - -@item -Jim Blandy wrote Emacs 19's input system, brought its configuration and -build process up to the GNU coding standards, and contributed to the -frame support and multi-face support. Jim also wrote @file{tvi970.el}, -terminal support for the TeleVideo 970 terminals; and co-wrote -@file{wyse50.el} (q.v.@:). - -@item -Per Bothner wrote @file{term.el}, a terminal emulator in an Emacs -buffer. - -@item -Terrence M.@: Brannon wrote @file{landmark.el}, a neural-network robot -that learns landmarks. - -@item -Frank Bresz wrote @file{diff.el}, a program to display @code{diff} -output. - -@item -Peter Breton implemented @file{dirtrack.el}, a library for tracking -directory changes in shell buffers; @file{filecache.el}, which records -which directories your files are in; @file{locate.el}, which -interfaces to the @code{locate} command; @file{find-lisp.el}, an Emacs -Lisp emulation of the @command{find} program; @file{net-utils.el}; and -the ``generic mode'' feature. - -@item -Emmanuel Briot wrote @file{xml.el}, an XML parser for Emacs; and -@file{ada-prj.el}, editing of Ada mode project files, as well as -co-authoring @file{ada-mode.el} and @file{ada-xref.el}. - -@item -Kevin Broadey wrote @file{foldout.el}, providing folding extensions to -Emacs's outline modes. - -@item -David M.@: Brown wrote @file{array.el}, for editing arrays and other -tabular data. - -@item -W@l{}odek Bzyl and Ryszard Kubiak wrote @file{ogonek.el}, a package for -changing the encoding of Polish characters. - -@item -Bill Carpenter provided @file{feedmail.el}, a package for massaging -outgoing mail messages and sending them through various popular mailers. - -@item -Per Cederqvist and Inge Wallin wrote @file{ewoc.el}, an Emacs widget for -manipulating object collections. Per Cederqvist, Inge Wallin, and -Thomas Bellman wrote @file{avl-tree.el}, for balanced binary trees. - -@item -Hans Chalupsky wrote @file{advice.el}, an overloading mechanism for -Emacs Lisp functions; and @file{trace.el}, a tracing facility for Emacs -Lisp. - -@item -Chris Chase, Carsten Dominik, and J.@: D.@: Smith wrote IDLWAVE mode, -for editing IDL and WAVE CL. - -@item -Bob Chassell wrote @file{texnfo-upd.el}, @file{texinfo.el}, and -@file{makeinfo.el}, modes and utilities for working with Texinfo files; -and @file{page-ext.el}, commands for extended page handling. He also -wrote the ``Introduction to programming in Emacs Lisp'' manual. - -@item -Jihyun Cho wrote @file{hanja-util.el} and @file{hangul.el}, utilities -for Korean Hanja. - -@item -Andrew Choi and Yamamoto Mitsuharu wrote the Carbon support, used -prior to Emacs 23 for Mac OS. - -@item -Chong Yidong was the Emacs co-maintainer from Emacs 23 onwards. He made many -improvements to the Emacs display engine. He also wrote -@file{tabulated-list.el}, a generic major mode for lists of data; -and improved support for themes and packages. - -@item -James Clark wrote SGML mode, a mode for editing SGML documents; and -nXML mode, a mode for editing XML documents. He also contributed to -Emacs's dumping procedures. - -@item -Mike Clarkson wrote @file{edt.el}, an emulation of DEC's EDT editor. - -@item -Glynn Clements provided @file{gamegrid.el} and a couple of games that -use it, Snake and Tetris. - -@item -Andrew Cohen wrote @file{spam-wash.el}, to decode and clean email before -it is analyzed for spam. - -@item -Edward O'Connor wrote @file{json.el}, a file for parsing and -generating JSON files. - -@item -Georges Brun-Cottan and Stefan Monnier wrote @file{easy-mmode.el}, a -package for easy definition of major and minor modes. - -@item -Andrew Csillag wrote M4 mode (@file{m4-mode.el}). - -@item -Doug Cutting and Jamie Zawinski wrote @file{disass.el}, a disassembler -for compiled Emacs Lisp code. - -@item -Mathias Dahl wrote @file{image-dired.el}, a package for viewing image -files as ``thumbnails''. - -@item -Julien Danjou wrote an implementation of ``Desktop Notifications'' -(@file{notifications.el}); and @file{color.el}, a library for general -color manipulation. He also made various contributions to Gnus. - -@item -Vivek Dasmohapatra wrote @file{htmlfontify.el}, to convert a buffer or -source tree to HTML. - -@item -Gary Delp wrote @file{mailpost.el}, an interface between RMAIL and the -@file{/usr/uci/post} mailer. - -@item -Matthieu Devin wrote @file{delsel.el}, a package to make newly-typed -text replace the current selection. - -@item -Eric Ding wrote @file{goto-addr.el}, - -@item -Jan Djärv added support for the GTK+ toolkit and X drag-and-drop. -He also wrote @file{dynamic-setting.el}. - -@item -Carsten Dominik wrote Ref@TeX{}, a package for setting up labels and -cross-references in La@TeX{} documents; and co-wrote IDLWAVE mode -(q.v.@:). He was the original author of Org mode, for maintaining notes, -todo lists, and project planning. Bastien Guerry subsequently took -over maintainership. Benjamin Andresen, Thomas Baumann, Joel Boehland, Jan Böcker, Lennart -Borgman, Baoqiu Cui, Dan Davison, Christian Egli, Eric S.@: Fraga, Daniel German, Chris Gray, Konrad Hinsen, Tassilo Horn, Philip -Jackson, Martyn Jago, Thorsten Jolitz, Jambunathan K, Tokuya Kameshima, Sergey Litvinov, David Maus, Ross Patterson, Juan Pechiar, Sebastian Rose, Eric Schulte, -Paul Sexton, Ulf Stegemann, Andy Stewart, Christopher Suckling, David O'Toole, John Wiegley, Zhang Weize, -Piotr Zielinski, and others also wrote various Org mode components. -For more information, @pxref{History and Acknowledgments,,, org, The Org Manual}. - -@item -Scott Draves wrote @file{tq.el}, help functions for maintaining -transaction queues between Emacs and its subprocesses. - -@item -Benjamin Drieu wrote @file{pong.el}, an implementation of the classical -pong game. - -@item -Viktor Dukhovni wrote support for dumping under SunOS version 4. - -@item -John Eaton and Kurt Hornik wrote Octave mode. - -@item -Rolf Ebert, Markus Heritsch, and Emmanuel Briot wrote Ada mode. - -@item -Paul Eggert integrated the Gnulib portability library, and made many -other portability fixes to the C code; as well as his contributions -to VC and the calendar. - -@item -Stephen Eglen wrote @file{mspools.el}, which tells you which Procmail -folders have mail waiting in them; and @file{iswitchb.el}, a feature -for incremental reading and completion of buffer names. - -@item -Torbjörn Einarsson wrote @file{f90.el}, a mode for Fortran 90 files. - -@item -Tsugutomo Enami co-wrote the support for international character sets. - -@item -David Engster wrote @file{mairix.el} and @file{nnmairix.el}, an -interface to the Mairix indexing tool. - -@item -Hans Henrik Eriksen wrote @file{simula.el}, a mode for editing SIMULA 87 -code. - -@item -Michael Ernst wrote @file{reposition.el}, a command for recentering a -function's source code and preceding comment on the screen. - -@item -Ata Etemadi wrote @file{cdl.el}, functions for working with Common Data -Language source code. - -@item -Frederick Farnbach implemented @file{morse.el}, which converts text to -Morse code. - -@item -Oscar Figueiredo wrote EUDC, the Emacs Unified Directory Client, which -is an interface to directory servers via LDAP, CCSO PH/QI, or BBDB; and -@file{ldap.el}, the LDAP client interface. - -@item -Fred Fish wrote the support for dumping COFF executable files. - -@item -Karl Fogel wrote @file{bookmark.el}, which implements named -placeholders; @file{mail-hist.el}, a history mechanism for outgoing -mail messages; and @file{saveplace.el}, for preserving point's -location in files between editing sessions. - -@item -Gary Foster wrote @file{crisp.el}, the emulation for CRiSP and Brief -editors; and @file{scroll-all.el}, a mode for scrolling several buffers -together. - -@item -Noah Friedman wrote @file{rlogin.el}, an interface to Rlogin, -@file{type-break.el}, which reminds you to take periodic breaks from -typing, and @code{eldoc-mode}, a mode to show the defined parameters or -the doc string for the Lisp function near point. - -@item -Shigeru Fukaya wrote a testsuite for the byte-compiler. - -@item -Keith Gabryelski wrote @file{hexl.el}, a mode for editing binary files. - -@item -Kevin Gallagher rewrote and enhanced the EDT emulation, and wrote -@file{flow-ctrl.el}, a package for coping with unsuppressible XON/XOFF -flow control. - -@item -Kevin Gallo added multiple-frame support for Windows NT and wrote -@file{w32-win.el}, support functions for the MS-Windows window system. - -@item -Juan León Lahoz García wrote @file{wdired.el}, a package for -performing file operations by directly editing Dired buffers. - -@item -Howard Gayle wrote much of the C and Lisp code for display tables and -case tables. He also wrote @file{rot13.el}, a command to display the -plain-text form of a buffer encoded with the Caesar cipher; -@file{vt100-led.el}, a package for controlling the LEDs on -VT100-compatible terminals; and much of the support for ISO-8859 -European character sets (which includes @file{iso-ascii.el}, -@file{iso-insert.el}, @file{iso-swed.el}, -@file{iso-syntax.el}, @file{iso-transl.el}, and @file{swedish.el}). - -@item -Stephen Gildea made the Emacs quick reference card, and made many -contributions for @file{time-stamp.el}, a package for maintaining -last-change time stamps in files. - -@item -Julien Gilles wrote @file{gnus-ml.el}, a mailing list minor mode for -Gnus. - -@item -David Gillespie wrote the Common Lisp compatibility packages; -@code{Calc}, an advanced calculator and mathematical tool, since -maintained and developed by Jay Belanger; @file{complete.el}, a partial -completion mechanism; and @file{edmacro.el}, a package for editing -keyboard macros. - -@item -Bob Glickstein wrote @file{sregex.el}, a facility for writing regexps -using a Lisp-like syntax. - -@item -Boris Goldowsky wrote @file{avoid.el}, a package to keep the mouse -cursor out of the way of the text cursor; @file{shadowfile.el}, a -package for keeping identical copies of files in more than one place; -@file{format.el}, a package for reading and writing files in various -formats; @file{enriched.el}, a package for saving text properties in -files; @file{facemenu.el}, a package for specifying faces; and -@file{descr-text.el}, describing text and character properties. - -@item -Michelangelo Grigni wrote @file{ffap.el} which visits a file, -taking the file name from the buffer. - -@item -Odd Gripenstam wrote @file{dcl-mode.el} for editing DCL command files. - -@item -Michael Gschwind wrote @file{iso-cvt.el}, a package to convert between -the ISO 8859-1 character set and the notations for non-@acronym{ASCII} -characters used by @TeX{} and net tradition. - -@item -Bastien Guerry wrote @file{gnus-bookmark.el}, bookmark support for Gnus; -as well as helping to maintain Org mode (q.v.@:). - -@item -Henry Guillaume wrote @file{find-file.el}, a package to visit files -related to the currently visited file. - -@item -Doug Gwyn wrote the portable @code{alloca} implementation. - -@item -Ken'ichi Handa implemented most of the support for international -character sets, and wrote most of the Emacs 23 font handling code. He -also wrote @file{composite.el}, which provides a minor mode that -composes characters automatically when they are displayed; -@file{isearch-x.el}, a facility for searching non-@acronym{ASCII} -text; and @file{ps-bdf.el}, a BDF font support for printing -non-@acronym{ASCII} text on a PostScript printer. Together with Naoto -Takahashi, he wrote @file{quail.el}, an input facility for typing -non-@acronym{ASCII} text from an @acronym{ASCII} keyboard. - -@item -Jesper Harder wrote @file{yenc.el}, for decoding yenc encoded messages. - -@item -Alexandru Harsanyi wrote a library for accessing SOAP web services. - -@item -K.@: Shane Hartman wrote @file{chistory.el} and @file{echistory.el}, -packages for browsing command history lists; @file{electric.el} and -@file{helper.el}, which provide an alternative command loop and -appropriate help facilities; @file{emacsbug.el}, a package for -reporting Emacs bugs; @file{picture.el}, a mode for editing -@acronym{ASCII} pictures; and @file{view.el}, a package for perusing -files and buffers without editing them. - -@item -John Heidemann wrote @file{mouse-copy.el} and @file{mouse-drag.el}, -which provide alternative mouse-based editing and scrolling features. - -@item -Jon K Hellan wrote @file{utf7.el}, support for mail-safe transformation -format of Unicode. - -@item -Karl Heuer wrote the original blessmail script, implemented the -@code{intangible} text property, and rearranged the structure of the -@code{Lisp_Object} type to allow for more data bits. - -@item -Manabu Higashida ported Emacs to MS-DOS. - -@item -Anders Holst wrote @file{hippie-exp.el}, a versatile completion and -expansion package. - -@item -Tassilo Horn wrote DocView mode, allowing viewing of PDF, PostScript and -DVI documents. - -@item -Tom Houlder wrote @file{mantemp.el}, which generates manual C@t{++} -template instantiations. - -@item -Joakim Hove wrote @file{html2text.el}, a html to plain text converter. - -@item -Denis Howe wrote @file{browse-url.el}, a package for invoking a WWW -browser to display a URL. - -@item -Lars Magne Ingebrigtsen did a major redesign of the Gnus news-reader and -wrote many of its parts. Several of these are now general components of -Emacs, including: @file{dns.el} for Domain Name Service lookups; -@file{format-spec.el} for formatting arbitrary format strings; -@file{netrc.el} for parsing of @file{.netrc} files; and -@file{time-date.el} for general date and time handling. -He also wrote @file{network-stream.el}, for opening network processes; -@file{url-queue.el}, for controlling parallel downloads of URLs; -and implemented libxml2 support. -Components of Gnus have also been written by: Nagy Andras, David -Blacka, Scott Byer, Ludovic Courtès, Julien Danjou, Kevin Greiner, Kai -Großjohann, Joe Hildebrand, Paul Jarc, Simon Josefsson, Sascha -Lüdecke, David Moore, Jim Radford, Benjamin Rutt, Raymond Scholz, -Thomas Steffen, Reiner Steib, Didier Verna, Ilja Weis, Katsumi -Yamaoka, Teodor Zlatanov, and others (@pxref{Contributors,,,gnus, the -Gnus Manual}). - -@item -Andrew Innes contributed extensively to the MS-Windows support. - -@item -Seiichiro Inoue improved Emacs's XIM support. - -@item -Philip Jackson wrote @file{find-cmd.el}, to build a @code{find} -command-line. - -@item -Ulf Jasper wrote @file{icalendar.el}, a package for converting Emacs -diary entries to and from the iCalendar format; -@file{newsticker.el}, an RSS and Atom based Newsticker; and -@file{bubbles.el}, a puzzle game. - -@item -Kyle Jones wrote @file{life.el}, a package to play Conway's ``life'' game. - -@item -Terry Jones wrote @file{shadow.el}, a package for finding potential -load-path problems when some Lisp file ``shadows'' another. - -@item -Simon Josefsson wrote @file{dns-mode.el}, an editing mode for Domain -Name System master files; @file{dig.el}, a Domain Name System interface; -@file{flow-fill.el}, a package for interpreting RFC2646 formatted text -in messages; @file{fringe.el}, a package for customizing the fringe; -@file{imap.el}, an Emacs Lisp library for talking to IMAP servers; -@file{password-cache.el}, a password reader; @file{nnimap.el}, the IMAP -back-end for Gnus; @file{url-imap.el} for the URL library; -@file{rfc2104.el}, a hashed message authentication facility; the Gnus -S/MIME and Sieve components; and @file{tls.el} and @file{starttls.el} -for the Transport Layer Security protocol. - -@item -Arne Jørgensen wrote @file{latexenc.el}, a package to -automatically guess the correct coding system in La@TeX{} files. - -@item -Alexandre Julliard wrote @file{vc-git.el}, support for the Git version -control system. - -@item -Tomoji Kagatani implemented @file{smtpmail.el}, used for sending out -mail with SMTP. - -@item -Ivan Kanis wrote @file{vc-hg.el}, support for the Mercurial version -control system. - -@item -Henry Kautz wrote @file{bib-mode.el}, a mode for maintaining -bibliography databases compatible with @code{refer} (the @code{troff} -version) and @code{lookbib}, and @file{refbib.el}, a package to convert -those databases to the format used by the La@TeX{} text formatting package. - -@item -Taichi Kawabata added support for Devanagari script and the Indian -languages, and wrote @file{ucs-normalize.el} for Unicode normalization. - -@item -Taro Kawagishi implemented the MD4 Message Digest Algorithm in Lisp; and -wrote @file{ntlm.el} and @file{sasl-ntlm.el} for NT LanManager -authentication support. - -@item -Howard Kaye wrote @file{sort.el}, commands to sort text in Emacs -buffers. - -@item -Michael Kifer wrote @code{ediff}, an interactive interface to the -@command{diff}, @command{patch}, and @command{merge} programs; and -Viper, another emulator of the VI editor. - -@item -Richard King wrote the first version of @file{userlock.el} and -@file{filelock.c}, which provide simple support for multiple users -editing the same file. He also wrote the initial version of -@file{uniquify.el}, a facility to make buffer names unique by adding -parts of the file's name to the buffer name. - -@item -Peter Kleiweg wrote @file{ps-mode.el}, a mode for editing PostScript -files and running a PostScript interpreter interactively from within -Emacs. - -@item -Karel Klí@v{c} contributed SELinux support, for preserving the -Security-Enhanced Linux context of files on backup and copy. - -@item -Shuhei Kobayashi wrote @file{hex-util.el}, for operating on hexadecimal -strings; and support for HMAC (Keyed-Hashing for Message Authentication). - -@item -Pavel Kobyakov wrote @file{flymake.el}, a minor mode for performing -on-the-fly syntax checking. - -@item -David M.@: Koppelman wrote @file{hi-lock.el}, a minor mode for -interactive automatic highlighting of parts of the buffer text. - -@item -Koseki Yoshinori wrote @file{iimage.el}, a minor mode for displaying -inline images. - -@item -Robert Krawitz wrote the original @file{xmenu.c}, part of Emacs's pop-up -menu support. - -@item -Sebastian Kremer wrote @code{dired-mode}, with contributions by Lawrence -R.@: Dodd. He also wrote @file{ls-lisp.el}, a Lisp emulation of the -@code{ls} command for platforms that don't have @code{ls} as a standard -program. - -@item -David K@ringaccent{a}gedal wrote @file{tempo.el}, providing support for -easy insertion of boilerplate text and other common constructions. - -@item -Igor Kuzmin wrote @file{cconv.el}, providing closure conversion for -statically scoped Emacs lisp. - -@item -Daniel LaLiberte wrote @file{edebug.el}, a source-level debugger for -Emacs Lisp; @file{cl-specs.el}, specifications to help @code{edebug} -debug code written using David Gillespie's Common Lisp support; -@file{cust-print.el}, a customizable package for printing lisp -objects; and @file{isearch.el}, Emacs's incremental search minor mode. -He also co-wrote @file{hideif.el} (q.v.@:). - -@item -Karl Landstrom and Daniel Colascione wrote @file{js.el}, a mode for -editing JavaScript. - -@item -Vinicius Jose Latorre wrote the Emacs printing facilities, as well as -@code{ps-print} (with Jim Thompson, Jacques Duthen, and Kenichi Handa), -a package for pretty-printing Emacs buffers to PostScript printers; -@file{delim-col.el}, a package to arrange text into columns; -@file{ebnf2ps.el}, a package that translates EBNF grammar to a syntactic -chart that can be printed to a PostScript printer; and -@file{whitespace.el}, a package that detects and cleans up excess -whitespace in a file (building on an earlier version by Rajesh Vaidheeswarran). - -@item -Frederic Lepied wrote @file{expand.el}, which uses the abbrev -mechanism for inserting programming constructs. - -@item -Peter Liljenberg wrote @file{elint.el}, a Lint-style code checker for -Emacs Lisp programs. - -@item -Lars Lindberg wrote @file{msb.el}, which provides more flexible menus -for buffer selection; co-wrote @file{imenu.el} (q.v.@:); and rewrote -@file{dabbrev.el}, originally written by Don Morrison. - -@item -Anders Lindgren wrote @file{autorevert.el}, a package for automatically -reverting files visited by Emacs that were changed on disk; -@file{cwarn.el}, a package to highlight suspicious C and C@t{++} -constructs; and @file{follow.el}, a minor mode to synchronize windows -that show the same buffer. - -@item -Thomas Link wrote @file{filesets.el}, a package for handling sets of -files. - -@item -Juri Linkov wrote @file{misearch.el}, extending isearch to multi-buffer -searches; the code in @file{files-x.el} for handling file- and -directory-local variables; and the @code{info-finder} feature that -creates a virtual Info manual of package keywords. - -@item -Károly L@H{o}rentey wrote the ``multi-terminal'' code, which allows -Emacs to run on graphical and text terminals simultaneously. - -@item -Martin Lorentzon wrote @file{vc-annotate.el}, support for version -control annotation. - -@item -Dave Love wrote much of the code dealing with Unicode support and -Latin-N unification. He added support for many coding systems, -including the various UTF-7 and UTF-16 coding systems. He also wrote -@code{autoarg-mode}, a global minor mode whereby digit keys supply -prefix arguments; @code{autoarg-kp-mode}, which redefines the keypad -numeric keys to digit arguments; @file{autoconf.el}, a mode for editing -Autoconf files; @file{cfengine.el}, a mode for editing Cfengine files; -@file{elide-head.el}, a package for eliding boilerplate text from file -headers; @file{hl-line.el}, a minor mode for highlighting the line in -the current window on which point is; @file{cap-words.el}, a minor mode -for motion in ``CapitalizedWordIdentifiers''; @file{latin1-disp.el}, a -package that lets you display ISO 8859 characters on Latin-1 terminals -by setting up appropriate display tables; @file{python.el}, a major mode -for the Python programming language; @file{smiley.el}, a facility for -displaying smiley faces; @file{sym-comp.el}, a library for performing -mode-dependent symbol completion; @file{benchmark.el} for timing code -execution; and @file{tool-bar.el}, a mode to control the display of -the Emacs tool bar. With Riccardo Murri he wrote @file{vc-bzr.el}, -support for the Bazaar version control system. - -@item -Eric Ludlam wrote the Speedbar package; @file{checkdoc.el}, for checking -doc strings in Emacs Lisp programs; @file{dframe.el}, providing -dedicated frame support modes; @file{ezimage.el}, a generalized way to -place images over text; @file{chart.el} for drawing bar charts etc; and -the EIEIO (Enhanced Implementation of Emacs Interpreted Objects) -package. He was also the main author of the CEDET (Collection of Emacs -Development Environment Tools) package. Portions were also written by -Jan Moringen, David Ponce, and Joakim Verona. - -@item -Roland McGrath wrote @file{compile.el} (since updated by Daniel -Pfeiffer), a package for running compilations in a buffer, and then -visiting the locations reported in error messages; @file{etags.el}, a -package for jumping to function definitions and searching or replacing -in all the files mentioned in a @file{TAGS} file; with Sebastian -Kremer @file{find-dired.el}, for using @code{dired} commands on output -from the @code{find} program; @file{grep.el} for running the -@code{grep} command; @file{map-ynp.el}, a general purpose boolean -question-asker; @file{autoload.el}, providing semi-automatic -maintenance of autoload files. - -@item -Alan Mackenzie wrote the integrated AWK support in CC Mode, and -maintained CC Mode from Emacs 22 onwards. - -@item -Michael McNamara and Wilson Snyder wrote Verilog mode. - -@item -Christopher J.@: Madsen wrote @file{decipher.el}, a package for cracking -simple substitution ciphers. - -@item -Neil M.@: Mager wrote @file{appt.el}, functions to notify users of their -appointments. It finds appointments recorded in the diary files -used by the @code{calendar} package. - -@item -Ken Manheimer wrote @file{allout.el}, a mode for manipulating and -formatting outlines, and @file{icomplete.el}, which provides incremental -completion feedback in the minibuffer. - -@item -Bill Mann wrote @file{perl-mode.el}, a mode for editing Perl code. - -@item -Brian Marick and Daniel LaLiberte wrote @file{hideif.el}, support for -hiding selected code within C @code{#ifdef} clauses. - -@item -Simon Marshall wrote @file{regexp-opt.el}, which generates a regular -expression from a list of strings; and the fast-lock and lazy-lock -font-lock support modes. He also extended @file{comint.el} and -@file{shell.el}, originally written by Olin Shivers. - -@item -Bengt Martensson, Dirk Herrmann, Marc Shapiro, Mike Newton, Aaron Larson, -and Stefan Schoef, wrote @file{bibtex.el}, a mode for editing Bib@TeX{} -bibliography files. - -@item -Charlie Martin wrote @file{autoinsert.el}, which provides automatic -mode-sensitive insertion of text into new files. - -@item -Yukihiro Matsumoto and Nobuyoshi Nakada wrote Ruby-mode. - -@item -Thomas May wrote @file{blackbox.el}, a version of the traditional -blackbox game. - -@item -David Megginson wrote @file{derived.el}, which allows one to define new -major modes by inheriting key bindings and commands from existing major -modes. - -@item -Will Mengarini wrote @file{repeat.el}, a command to repeat the preceding -command with its arguments. - -@item -Richard Mlynarik wrote @file{cl-indent.el}, a package for indenting -Common Lisp code; @file{ebuff-menu.el}, an ``electric'' browser for -buffer listings; @file{ehelp.el}, bindings for browsing help screens; -@file{rfc822.el}, a parser for E-mail addresses in the RFC-822 format, -used in mail messages and news articles; @file{terminal.el}, a -terminal emulator for Emacs subprocesses; and @file{yow.el}, an -essential utility. - -@item -Gerd Moellmann was the Emacs maintainer from the beginning of Emacs 21 -development until the release of 21.1. He wrote the new display -engine used from Emacs 21 onwards, and the asynchronous timers -facility. He also wrote @code{ebrowse}, the C@t{++} browser; -@file{jit-lock.el}, the Just-In-Time font-lock support mode; -@file{tooltip.el}, a package for displaying tooltips; -@file{authors.el}, a package for maintaining the @file{AUTHORS} file; -and @file{rx.el}, a regular expression constructor. - -@item -Stefan Monnier was the Emacs co-maintainer from Emacs 23 onwards. He added -support for Arch and Subversion to VC, re-wrote much of the Emacs server -to use the built-in networking primitives, and re-wrote the abbrev and -minibuffer completion code for Emacs 23. He also wrote @code{PCL-CVS}, -a directory-level front end to the CVS version control system; -@file{reveal.el}, a minor mode for automatically revealing invisible -text; @file{smerge-mode.el}, a minor mode for resolving @code{diff3} -conflicts; @file{diff-mode.el}, a mode for viewing and editing context -diffs; @file{css-mode.el} for Cascading Style Sheets; -@file{bibtex-style.el} for Bib@TeX{} Style files; @file{mpc.el}, a -client for the ``Music Player Daemon''; @file{smie.el}, a generic -indentation engine; and @file{pcase.el}, implementing ML-style pattern -matching. He integrated the lexical binding code in Emacs 24. - -@item -Morioka Tomohiko wrote several packages for MIME support in Gnus and -elsewhere. - -@item -Sen Nagata wrote @file{crm.el}, a package for reading multiple strings -with completion, and @file{rfc2368.el}, support for @code{mailto:} -URLs. - -@item -Erik Naggum wrote the time-conversion functions. He also wrote -@file{disp-table.el}, for dealing with display tables; -@file{mailheader.el}, for parsing email headers; and -@file{parse-time.el}, for parsing time strings. - -@item -Takahashi Naoto co-wrote @file{quail.el} (q.v.@:), and wrote -@file{robin.el}, another input method. - -@item -Thomas Neumann and Eric Raymond wrote @file{make-mode.el}, -a mode for editing makefiles. - -@item -Thien-Thi Nguyen and Dan Nicolaescu wrote @file{hideshow.el}, a minor -mode for selectively displaying blocks of text. - -@item -Jurgen Nickelsen wrote @file{ws-mode.el}, providing WordStar emulation. - -@item -Dan Nicolaescu added support for running Emacs as a daemon. He also -wrote @file{romanian.el}, support for editing Romanian text; -@file{iris-ansi.el}, support for running Emacs on SGI's @code{xwsh} -and @code{winterm} terminal emulators; and @file{vc-dir.el}, displaying -the status of version-controlled directories. - -@item -Hrvoje Niksic wrote @file{savehist.el}, for saving the minibuffer -history between Emacs sessions. - -@item -Jeff Norden wrote @file{kermit.el}, a package to help the Kermit -dialup communications program run comfortably in an Emacs shell buffer. - -@item -Andrew Norman wrote @file{ange-ftp.el}, providing transparent FTP -support. - -@item -Kentaro Ohkouchi created the Emacs icons used beginning with Emacs 23. - -@item -Christian Ohler wrote @file{ert.el}, a library for automated regression -testing. - -@item -Alexandre Oliva wrote @file{gnus-mlspl.el}, a group params-based mail -splitting mechanism. - -@item -Takaaki Ota wrote @file{table.el}, a package for creating and editing -embedded text-based tables. - -@item -Pieter E.@: J.@: Pareit wrote @file{mixal-mode.el}, an editing mode for -the MIX assembly language. - -@item -David Pearson wrote @file{quickurl.el}, a simple method of inserting a -URL into the current buffer based on text at point; @file{5x5.el}, a -game to fill all squares on the field. - -@item -Jeff Peck wrote @file{sun.el}, key bindings for sunterm keys. - -@item -Damon Anton Permezel wrote @file{hanoi.el}, an animated demonstration of -the ``Towers of Hanoi'' puzzle. - -@item -William M.@: Perry wrote @file{mailcap.el} (with Lars Magne -Ingebrigtsen), a MIME media types configuration facility; -@file{mwheel.el}, a package for supporting mouse wheels; co-wrote (with -Dave Love) @file{socks.el}, a Socks v5 client; and developed the URL -package. - -@item -Per Persson wrote @file{gnus-vm.el}, the VM interface for Gnus. - -@item -Jens Petersen wrote @file{find-func.el}, which makes it easy to find -the source code for an Emacs Lisp function or variable. - -@item -Daniel Pfeiffer wrote @file{conf-mode.el}, a mode for editing -configuration files; @file{copyright.el}, a package for updating -copyright notices in files; @file{executable.el}, a package for -executing interpreter scripts; @file{sh-script.el}, a mode for editing -shell scripts; @file{skeleton.el}, implementing a concise language for -writing statement skeletons; and @file{two-column.el}, a minor mode -for simultaneous two-column editing. - -Daniel also rewrote @file{apropos.el} (originally written by Joe Wells), -for finding commands, functions, and variables matching a regular -expression; and, together with Jim Blandy, co-authored @file{wyse50.el}, -support for Wyse 50 terminals. He also co-wrote @file{compile.el} -(q.v.@:) and @file{ada-stmt.el}. - -@item -Richard L.@: Pieri wrote @file{pop3.el}, a Post Office Protocol (RFC -1460) interface for Emacs. - -@item -Fred Pierresteguy and Paul Reilly made Emacs work with X Toolkit -widgets. - -@item -François Pinard, Greg McGary, and Bruno Haible wrote @file{po.el}, -support for PO translation files. - -@item -Christian Plaunt wrote @file{soundex.el}, an implementation of the -Soundex algorithm for comparing English words by their pronunciation. - -@item -David Ponce wrote @file{recentf.el}, a package that puts a menu of -recently visited files in the Emacs menu bar; @file{ruler-mode.el}, a -minor mode for displaying a ruler in the header line; and -@file{tree-widget.el}, a package to display hierarchical data -structures. - -@item -Francesco A.@: Potorti wrote @file{cmacexp.el}, providing a command which -runs the C preprocessor on a region of a file and displays the results. -He also expanded and redesigned the @code{etags} program. - -@item -Michael D.@: Prange and Steven A.@: Wood wrote @file{fortran.el}, a mode -for editing Fortran code. - -@item -Ashwin Ram wrote @file{refer.el}, commands to look up references in -bibliography files by keyword. - -@item -Eric S.@: Raymond wrote @file{vc.el}, an interface to the RCS and SCCS -source code version control systems, with Paul Eggert; @file{gud.el}, -a package for running source-level debuggers like GDB and SDB in -Emacs; @file{asm-mode.el}, a mode for editing assembly language code; -@file{AT386.el}, terminal support package for IBM's AT keyboards; -@file{cookie1.el}, support for ``fortune-cookie'' programs like -@file{yow.el} and @file{spook.el}; @file{finder.el}, a package for -finding Emacs Lisp packages by keyword and topic; @file{keyswap.el}, -code to swap the @key{BS} and @key{DEL} keys; @file{loadhist.el}, -functions for loading and unloading Emacs features; -@file{lisp-mnt.el}, functions for working with the special headers -used in Emacs Lisp library files; and code to set and make use of the -@code{load-history} lisp variable, which records the source file from -which each lisp function loaded into Emacs came. - -@item -Edward M.@: Reingold wrote the calendar and diary support, -with contributions from Stewart Clamen (@file{cal-mayan.el}), Nachum -Dershowitz (@file{cal-hebrew.el}), Paul Eggert (@file{cal-dst.el}), -Steve Fisk (@file{cal-tex.el}), Michael Kifer (@file{cal-x.el}), Lara -Rios (@file{cal-menu.el}), and Denis B.@: Roegel (@file{solar.el}). -Andy Oram contributed to its documentation. Reingold also contributed -to @file{tex-mode.el}, a mode for editing @TeX{} files, as did William -F.@: Schelter, Dick King, Stephen Gildea, Michael Prange, and Jacob -Gore. - -@item -David Reitter wrote @file{mailclient.el} which can send mail via the -system's designated mail client. - -@item -Alex Rezinsky wrote @file{which-func.el}, a mode that shows the name -of the current function in the mode line. - -@item -Rob Riepel wrote @file{tpu-edt.el} and its associated files, providing -an emulation of the VMS TPU text editor emulating the VMS EDT editor, -and @file{vt-control.el}, providing some control functions for the DEC -VT line of terminals. - -@item -Nick Roberts wrote @file{t-mouse.el}, for mouse support in text -terminals; and @file{gdb-ui.el}, a graphical user interface to GDB. -Together with Dmitry Dzhus, he wrote @file{gdb-mi.el}, the successor to -@file{gdb-ui.el}. - -@item -Danny Roozendaal implemented @file{handwrite.el}, which converts text -into ``handwriting''. - -@item -Markus Rost wrote @file{cus-test.el}, a testing framework for customize. - -@item -Guillermo J.@: Rozas wrote @file{scheme.el}, a mode for editing Scheme and -DSSSL code. - -@item -Martin Rudalics implemented improved display-buffer handling in Emacs 24. - -@item -Ivar Rummelhoff wrote @file{winner.el}, which records recent window -configurations so you can move back to them. - -@item -Jason Rumney ported the Emacs 21 display engine to MS-Windows, and has -contributed extensively to the MS-Windows port of Emacs. - -@item -Wolfgang Rupprecht wrote Emacs 19's floating-point support (including -@file{float-sup.el} and @file{floatfns.c}), and @file{sup-mouse.el}, -support for the Supdup mouse on lisp machines. - -@item -Kevin Ryde wrote @file{info-xref.el}, a library for checking -references in Info files. - -@item -James B.@: Salem and Brewster Kahle wrote @file{completion.el}, providing -dynamic word completion. - -@item -Masahiko Sato wrote @file{vip.el}, an emulation of the VI editor. - -@item -Holger Schauer wrote @file{fortune.el}, a package for using fortune in -message signatures. - -@item -William Schelter wrote @file{telnet.el}, support for @code{telnet} -sessions within Emacs. - -@item -Ralph Schleicher wrote @file{battery.el}, a package for displaying -laptop computer battery status, and @file{info-look.el}, a package for -looking up Info documentation for symbols in the buffer. - -@item -Michael Schmidt and Tom Perrine wrote @file{modula2.el}, a mode for -editing Modula-2 code, based on work by Mick Jordan and Peter Robinson. - -@item -Ronald S.@: Schnell wrote @file{dunnet.el}, a text adventure game. - -@item -Philippe Schnoebelen wrote @file{gomoku.el}, a Go Moku game played -against Emacs; and @file{mpuz.el}, a multiplication puzzle. - -@item -Rainer Schoepf contributed to Alpha and OSF1 support. - -@item -Jan Schormann wrote @file{solitaire.el}, an implementation of the -Solitaire game. - -@item -Alex Schroeder wrote @file{ansi-color.el}, a package for translating -ANSI color escape sequences to Emacs faces; @file{sql.el}, a package -for interactively running an SQL interpreter in an Emacs buffer; -@file{cus-theme.el}, an interface for custom themes; @file{master.el}, a -package for making a buffer @samp{master} over another; and -@file{spam-stat.el}, for statistical detection of junk email. He also -wrote parts of the IRC client ERC (q.v.@:). - -@item -Randal Schwartz wrote @file{pp.el}, a pretty-printer for lisp objects. - -@item -Oliver Seidel wrote @file{todo-mode.el}, a package for maintaining -@file{TODO} list files. - -@item -Manuel Serrano wrote the Flyspell package, which does spell checking -as you type. - -@item -Hovav Shacham wrote @file{windmove.el}, a set of commands for selecting -windows based on their geometrical position on the frame. - -@item -Stanislav Shalunov wrote @file{uce.el}, for responding to unsolicited -commercial email. - -@item -Richard Sharman wrote @file{hilit-chg.el}, which uses colors to show -recent editing changes. - -@item -Olin Shivers wrote @file{comint.el}, a library for modes running -interactive command-line-oriented subprocesses, and @file{shell.el}, for -running inferior shells (both since extended by Simon Marshall); -@file{cmuscheme.el}, for running inferior Scheme processes; -@file{inf-lisp.el}, for running inferior Lisp process. - -@item -Espen Skoglund wrote @file{pascal.el}, a mode for editing Pascal code. - -@item -Rick Sladkey wrote @file{backquote.el}, a lisp macro for creating -mostly-constant data. - -@item -Lynn Slater wrote @file{help-macro.el}, a macro for writing interactive -help for key bindings. - -@item -Chris Smith wrote @file{icon.el}, a mode for editing Icon code. - -@item -David Smith wrote @file{ielm.el}, a mode for interacting with the Emacs -Lisp interpreter as a subprocess. - -@item -Paul D.@: Smith wrote @file{snmp-mode.el}. - -@item -William Sommerfeld wrote @file{scribe.el}, a mode for editing Scribe -files, and @file{server.el}, a package allowing programs to send files -to an extant Emacs job to be edited. - -@item -Andre Spiegel made many contributions to the Emacs Version Control -package, and in particular made it support multiple back ends. - -@item -Michael Staats wrote @file{pc-select.el}, which rebinds keys for -selecting regions to follow many other systems. - -@item -Richard Stallman invented Emacs. He is the original author of GNU -Emacs, and has been Emacs maintainer over several non-contiguous -periods. In addition to much of the ``core'' Emacs code, he has -written @file{easymenu.el}, a facility for defining Emacs menus; -@file{image-mode.el}, support for visiting image files; -@file{menu-bar.el}, the Emacs menu bar support code; -@file{paren.el}, a package to make matching parentheses stand out in -color; and also co-authored portions of CC mode. - -@item -Sam Steingold wrote @file{gulp.el}, a facility for asking package -maintainers for updated versions of their packages via e-mail, and -@file{midnight.el}, a package for running a command every midnight. - -@item -Ake Stenhoff and Lars Lindberg wrote @file{imenu.el}, a framework for -browsing indices made from buffer contents. - -@item -Peter Stephenson wrote @file{vcursor.el}, which implements a ``virtual -cursor'' that you can move with the keyboard and use for copying text. - -@item -Ken Stevens wrote @file{ispell.el}, a spell-checker interface. - -@item -Kim F.@: Storm made many improvements to the Emacs display engine, -process support, and networking support. He also wrote -@file{bindat.el}, a package for encoding and decoding binary data; -CUA mode, which allows Emacs to emulate the standard CUA key -bindings; @file{ido.el}, a package for selecting buffers and files -quickly; @file{keypad.el} for simplified keypad bindings; and -@file{kmacro.el}, the keyboard macro facility. - -@item -Martin Stjernholm co-authored CC Mode, a major editing mode for C, -C@t{++}, Objective-C, Java, Pike, CORBA IDL, and AWK code. - -@item -Steve Strassmann did not write @file{spook.el}, and even if he did, he -really didn't mean for you to use it in an anarchistic way. - -@item -Olaf Sylvester wrote @file{bs.el}, a package for manipulating Emacs -buffers. - -@item -Tibor @v{S}imko and Milan Zamazal wrote @file{slovak.el}, support for -editing text in Slovak language. - -@item -Luc Teirlinck wrote @file{help-at-pt.el}, providing local help through -the keyboard. - -@item -Jean-Philippe Theberge wrote @file{thumbs.el}, a package for viewing -image files as ``thumbnails''. - -@item -Spencer Thomas wrote the original @file{dabbrev.el}, providing a command -which completes the partial word before point, based on other nearby -words for which it is a prefix. He also wrote the original dumping -support. - -@item -Toru Tomabechi contributed to Tibetan support. - -@item -Markus Triska wrote @file{linum.el}, a minor mode that displays line -numbers in the left margin. - -@item -Tom Tromey and Chris Lindblad wrote @file{tcl.el}, a mode for editing -Tcl/Tk source files and running a Tcl interpreter as an Emacs -subprocess. Tom Tromey also wrote @file{bug-reference.el}, providing -clickable links to bug reports; and the first version of the Emacs -package system. - -@item -Eli Tziperman wrote @file{rmail-spam-filter.el}, a spam filter for RMAIL. - -@item -Daiki Ueno wrote @file{starttls.el}, support for Transport Layer -Security protocol; @file{sasl-cram.el} and @file{sasl-digest.el} (with -Kenichi Okada), and @file{sasl.el}, support for Simple Authentication -and Security Layer (SASL); @file{plstore.el} for secure storage of -property lists; and the EasyPG (and its predecessor PGG) -package, for GnuPG and PGP support. - -@item -Masanobu Umeda wrote GNUS, a feature-rich reader for Usenet news that -was the ancestor of the current Gnus package. He also wrote -@file{rmailsort.el}, a package for sorting messages in RMAIL folders; -@file{metamail.el}, an interface to the Metamail program; -@file{gnus-kill.el}, the Kill File mode for Gnus; @file{gnus-mh.el}, an -mh-e interface for Gnus; @file{gnus-msg.el}, a mail and post interface -for Gnus; and @file{timezone.el}, providing functions for dealing with -time zones. - -@item -Neil W.@: Van Dyke wrote @file{webjump.el}, a ``hot links'' package. - -@item -Didier Verna wrote @file{rect.el}, a package of functions for -operations on rectangle regions of text. He also contributed to Gnus -(q.v.@:). - -@item -Joakim Verona implemented ImageMagick support. - -@item -Ulrik Vieth implemented @file{meta-mode.el}, for editing MetaFont code. - -@item -Geoffrey Voelker wrote the Windows NT support. He also wrote -@file{dos-w32.el}, functions shared by the MS-DOS and MS-Windows ports -of Emacs, and @file{w32-fns.el}, MS-Windows specific support functions. - -@item -Johan Vromans wrote @file{forms.el} and its associated files, a mode for -filling in forms. He also wrote @file{iso-acc.el}, a minor mode -providing electric accent keys. - -@item -Colin Walters wrote Ibuffer, an enhanced buffer menu. - -@item -Barry Warsaw wrote @file{assoc.el}, a set of utility functions for -working with association lists; @file{cc-mode.el}, a mode for editing -C, C@t{++}, and Java code, based on earlier work by Dave Detlefs, -Stewart Clamen, and Richard Stallman; @file{elp.el}, a profiler for -Emacs Lisp programs; @file{man.el}, a mode for reading Unix manual -pages; @file{regi.el}, providing an AWK-like functionality for use in -lisp programs; @file{reporter.el}, providing customizable bug -reporting for lisp packages; and @file{supercite.el}, a minor mode for -quoting sections of mail messages and news articles. - -@item -Christoph Wedler wrote @file{antlr-mode.el}, a major mode for ANTLR -grammar files. - -@item -Morten Welinder helped port Emacs to MS-DOS, and introduced face -support into the MS-DOS port of Emacs. He also wrote -@file{desktop.el}, facilities for saving some of Emacs's state between -sessions; @file{timer.el}, the Emacs facility to run commands at a -given time or frequency, or when Emacs is idle, and its C-level -support code; @file{pc-win.el}, the MS-DOS ``window-system'' support; -@file{internal.el}, an ``internal terminal'' emulator for the MS-DOS -port of Emacs; @file{arc-mode.el}, the mode for editing compressed -archives; @file{s-region.el}, commands for setting the region using -the shift key and motion commands; and @file{dos-fns.el}, functions -for use under MS-DOS. - -@item -Joe Wells wrote the original version of @file{apropos.el} (q.v.@:); -@file{resume.el}, support for processing command-line arguments after -resuming a suspended Emacs job; and @file{mail-extr.el}, a package for -extracting names and addresses from mail headers, with contributions -from Jamie Zawinski. - -@item -Rodney Whitby and Reto Zimmermann wrote @file{vhdl-mode.el}, a major -mode for editing VHDL source code. - -@item -John Wiegley wrote @file{align.el}, a set of commands for aligning text -according to regular-expression based rules; @file{isearchb.el} for fast -buffer switching; @file{timeclock.el}, a package for keeping track of -time spent on projects; the Bahá'í calendar support; -@file{pcomplete.el}, a programmable completion facility; -@file{remember.el}, a mode for jotting down things to remember; -@file{eudcb-mab.el}, an address book backend for the Emacs Unified -Directory Client; and @code{eshell}, a command shell implemented -entirely in Emacs Lisp. He also contributed to Org mode (q.v.@:). - -@item -Mike Williams wrote @file{mouse-sel.el}, providing enhanced mouse -selection; and @file{thingatpt.el}, a library of functions for finding -the ``thing'' (word, line, s-expression) containing point. - -@item -Roland Winkler wrote @file{proced.el}, a system process editor. - -@item -Bill Wohler wrote MH-E, the Emacs interface to the MH mail system; -making use of earlier work by James R.@: Larus. Satyaki Das, Peter S.@: -Galbraith, Stephen Gildea, and Jeffrey C.@: Honig also wrote various -MH-E components. - -@item -Dale R.@: Worley wrote @file{emerge.el}, a package for interactively -merging two versions of a file. - -@item -Francis J.@: Wright wrote @file{woman.el}, a package for browsing -manual pages without the @code{man} command. - -@item -Masatake Yamato wrote @file{ld-script.el}, an editing mode for GNU -linker scripts, and contributed subword handling and style -``guessing'' in CC mode. - -@item -Jonathan Yavner wrote @file{testcover.el}, a package for keeping track -of the testing status of Emacs Lisp code; @file{unsafep.el} to determine -if a Lisp form is safe; and the SES spreadsheet package. - -@item -Ryan Yeske wrote @file{rcirc.el} a simple Internet Relay Chat client. - -@item -Ilya Zakharevich and Bob Olson wrote @file{cperl-mode.el}, a major -mode for editing Perl code. Ilya Zakharevich also wrote -@file{tmm.el}, a mode for accessing the Emacs menu bar on a text-mode -terminal. - -@item -Milan Zamazal wrote @file{czech.el}, support for editing Czech text; -@file{glasses.el}, a package for easier reading of source code that -uses illegible identifier names; and @file{tildify.el}, commands for -adding hard spaces to text, @TeX{}, and SGML/HTML files. - -@item -Victor Zandy wrote @file{zone.el}, a package for people who like to -zone out in front of Emacs. - -@item -Eli Zaretskii made many standard Emacs features work on MS-DOS and -Microsoft Windows. He also wrote @file{tty-colors.el}, which -implements transparent mapping of X colors to tty colors; and -@file{rxvt.el}. He implemented support for bidirectional text. - -@item -Jamie Zawinski wrote much of the support for faces and X selections. -With Hallvard Furuseth, he wrote the optimizing byte compiler used -from Emacs 19 onwards. He also wrote @file{mailabbrev.el}, a package -that provides automatic expansion of mail aliases, and -@file{tar-mode.el}, which provides simple viewing and editing commands -for tar files. - -@item -Andrew Zhilin created the Emacs 22 icons. - -@item -Shenghuo Zhu wrote @file{binhex.el}, a package for reading and writing -binhex files; @file{mm-partial.el}, message/partial support for MIME -messages; @file{rfc1843.el}, an HZ decoding package; -@file{uudecode.el}, an Emacs Lisp decoder for uuencoded data; and -@file{webmail.el}, an interface to Web mail. He also wrote several -other Gnus components. - -@item -Ian T.@: Zimmerman wrote @file{gametree.el}. - -@item -Reto Zimmermann wrote @file{vera-mode.el}. - -@item -Neal Ziring and Felix S.@: T.@: Wu wrote @file{vi.el}, an emulation of the -VI text editor. - -@item -Ted Zlatanov (as well as his contributions to the Gnus newsreader) -wrote an interface to the GnuTLS library, for secure network -connections; and a futures facility for the URL library. - -@item -Detlev Zundel wrote @file{re-builder.el}, a package for building regexps -with visual feedback. - -@end itemize diff --git a/doc/emacs/anti.texi b/doc/emacs/anti.texi deleted file mode 100644 index 7bc405e442e..00000000000 --- a/doc/emacs/anti.texi +++ /dev/null @@ -1,114 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2005-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. - -@node Antinews, Mac OS / GNUstep, X Resources, Top -@appendix Emacs 23 Antinews -@c Update the emacs.texi Antinews menu entry with the above version number. - - For those users who live backwards in time, here is information -about downgrading to Emacs version 23.4. We hope you will enjoy the -greater simplicity that results from the absence of many Emacs -@value{EMACSVER} features. - -@itemize @bullet -@item -Support for displaying and editing ``bidirectional'' text has been -removed. Text is now always displayed on the screen in a single -consistent direction---left to right---regardless of the underlying -script. Similarly, @kbd{C-f} and @kbd{C-b} always move the text -cursor to the right and left respectively. Also, @key{right} and -@key{left} are now equivalent to @kbd{C-f} and @kbd{C-b}, as you might -expect, rather than moving forward or backward based on the underlying -``paragraph direction''. - -Users of ``right-to-left'' languages, like Arabic and Hebrew, may -adapt by reading and/or editing text in left-to-right order. - -@item -The Emacs Lisp package manager has been removed. Instead of using a -``user interface'' (@kbd{M-x list-packages}), additional Lisp packages -must now be installed by hand, which is the most flexible and -``Lispy'' method anyway. Typically, this just involves editing your -init file to add the package installation directory to the load path -and defining some autoloads; see each package's commentary section -and/or README file for details. - -@item -The option @code{delete-active-region} has been deleted. When the -region is active, typing @key{DEL} or @key{delete} no longer deletes -the text in the region; it deletes a single character instead. - -@item -We have reworked how Emacs handles the clipboard and the X primary -selection. Commands for killing and yanking, like @kbd{C-w} and -@kbd{C-y}, use the primary selection and not the clipboard, so you can -use these commands without interfering with ``cutting'' or ``pasting'' -in other programs. The @samp{Cut}/@samp{Copy}/@samp{Paste} menu items -are bound to separate clipboard commands, not to the same commands as -@kbd{C-w}/@kbd{M-w}/@kbd{C-y}. - -Selecting text by dragging with the mouse now puts the text in the -kill ring, in addition to the primary selection. But note that -selecting an active region with @kbd{C-@key{SPC}} does @emph{not} -alter the kill ring nor the primary selection, even though the text -highlighting is visually identical. - -@item -In Isearch, @kbd{C-y} and @kbd{M-y} are no longer bound to -@code{isearch-yank-kill} and @code{isearch-yank-pop} respectively. -Instead, @kbd{C-y} yanks the rest of the current line into the search -string (@code{isearch-yank-line}), whereas @kbd{M-y} does -@code{isearch-yank-kill}. The mismatch with the usual meanings of -@kbd{C-y} and @kbd{M-y} is unintended. - -@item -Various completion features have been simplified. The options -@code{completion-cycle-threshold} and -@code{completion-category-overrides} have been removed. Due to the -latter removal, Emacs uses a single consistent scheme to generate -completions, instead of using a separate scheme for (say) buffer name -completion. Several major modes, such as Shell mode, now implement -their own inline completion commands instead of using -@code{completion-at-point}. - -@item -We have removed various options for controlling how windows are used, -e.g.@: @code{display-buffer-base-action}, @code{display-buffer-alist}, -@code{window-combination-limit}, and @code{window-combination-resize}. - -@item -The command @kbd{M-x customize-themes} has been removed. Emacs no -longer comes with pre-defined themes (you can write your own). - -@item -Emacs no longer adapts various aspects of its display to GTK+ -settings, opting instead for a uniform toolkit-independent look. GTK+ -scroll bars are placed on the left, the same position as non-GTK+ X -scroll bars. Emacs no longer refers to GTK+ to set the default -@code{region} face, nor for drawing tooltips. - -@item -Setting the option @code{delete-by-moving-to-trash} to a -non-@code{nil} now causes all file deletions to use the system trash, -even temporary files created by Lisp programs; furthermore, the -@kbd{M-x delete-file} and @kbd{M-x delete-directory} commands no -longer accept prefix arguments to force true deletion. - -@item -On GNU/Linux and Unix, the default method for sending mail (as -specified by @code{send-mail-function}) is to use the -@command{sendmail} program. Emacs no longer asks for a delivery -method the first time you try to send mail, trusting instead that the -system is configured for mail delivery, as it ought to be. - -@item -Several VC features have been removed, including the @kbd{C-x v +} and -@kbd{C-x v m} commands for pulling and merging on distributed version -control systems, and the ability to view inline log entries in the log -buffers made by @kbd{C-x v L}. - -@item -To keep up with decreasing computer memory capacity and disk space, many -other functions and files have been eliminated in Emacs 23.4. -@end itemize diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi deleted file mode 100644 index 5a957b02843..00000000000 --- a/doc/emacs/arevert-xtra.texi +++ /dev/null @@ -1,189 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Autorevert -@section Auto Reverting Non-File Buffers - -Global Auto Revert Mode normally only reverts file buffers. There are -two ways to auto-revert certain non-file buffers: by enabling Auto -Revert Mode in those buffers (using @kbd{M-x auto-revert-mode}); and -by setting @code{global-auto-revert-non-file-buffers} to a -non-@code{nil} value. The latter enables Auto Reverting for all types -of buffers for which it is implemented (listed in the menu below). - -Like file buffers, non-file buffers should normally not revert while -you are working on them, or while they contain information that might -get lost after reverting. Therefore, they do not revert if they are -``modified''. This can get tricky, because deciding when a non-file -buffer should be marked modified is usually more difficult than for -file buffers. - -Another tricky detail is that, for efficiency reasons, Auto Revert -often does not try to detect all possible changes in the buffer, only -changes that are ``major'' or easy to detect. Hence, enabling -auto-reverting for a non-file buffer does not always guarantee that -all information in the buffer is up-to-date, and does not necessarily -make manual reverts useless. - -At the other extreme, certain buffers automatically revert every -@code{auto-revert-interval} seconds. (This currently only applies to -the Buffer Menu.) In this case, Auto Revert does not print any -messages while reverting, even when @code{auto-revert-verbose} is -non-@code{nil}. - -The details depend on the particular types of buffers and are -explained in the corresponding sections. - -@menu -* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. -* Auto Reverting Dired:: Auto Revert of Dired buffers. -* Supporting additional buffers:: How to add more Auto Revert support. -@end menu - -@node Auto Reverting the Buffer Menu -@subsection Auto Reverting the Buffer Menu - -If auto-reverting of non-file buffers is enabled, the Buffer Menu -automatically reverts every @code{auto-revert-interval} seconds, -whether there is a need for it or not. (It would probably take longer -to check whether there is a need than to actually revert.) - -If the Buffer Menu inappropriately gets marked modified, just revert -it manually using @kbd{g} and auto-reverting will resume. However, if -you marked certain buffers to get deleted or to be displayed, you have -to be careful, because reverting erases all marks. The fact that -adding marks sets the buffer's modified flag prevents Auto Revert from -automatically erasing the marks. - -@node Auto Reverting Dired -@subsection Auto Reverting Dired buffers - -Auto-reverting Dired buffers currently works on GNU or Unix style -operating systems. It may not work satisfactorily on some other -systems. - -Dired buffers only auto-revert when the file list of the buffer's main -directory changes (e.g. when a new file is added). They do not -auto-revert when information about a particular file changes -(e.g. when the size changes) or when inserted subdirectories change. -To be sure that @emph{all} listed information is up to date, you have -to manually revert using @kbd{g}, @emph{even} if auto-reverting is -enabled in the Dired buffer. Sometimes, you might get the impression -that modifying or saving files listed in the main directory actually -does cause auto-reverting. This is because making changes to a file, -or saving it, very often causes changes in the directory itself; for -instance, through backup files or auto-save files. However, this is -not guaranteed. - -If the Dired buffer is marked modified and there are no changes you -want to protect, then most of the time you can make auto-reverting -resume by manually reverting the buffer using @kbd{g}. There is one -exception. If you flag or mark files, you can safely revert the -buffer. This will not erase the flags or marks (unless the marked -file has been deleted, of course). However, the buffer will stay -modified, even after reverting, and auto-reverting will not resume. -This is because, if you flag or mark files, you may be working on the -buffer and you might not want the buffer to change without warning. -If you want auto-reverting to resume in the presence of marks and -flags, mark the buffer non-modified using @kbd{M-~}. However, adding, -deleting or changing marks or flags will mark it modified again. - -Remote Dired buffers are not auto-reverted (because it may be slow). -Neither are Dired buffers for which you used shell wildcards or file -arguments to list only some of the files. @file{*Find*} and -@file{*Locate*} buffers do not auto-revert either. - -@c FIXME? This should be in the elisp manual? -@node Supporting additional buffers -@subsection Adding Support for Auto-Reverting additional Buffers. - -This section is intended for Elisp programmers who would like to add -support for auto-reverting new types of buffers. - -To support auto-reverting the buffer must first of all have a -@code{revert-buffer-function}. @xref{Definition of -revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. - -In addition, it @emph{must} have a @code{buffer-stale-function}. - -@c FIXME only defvar in all of doc/emacs! -@defvar buffer-stale-function -The value of this variable is a function to check whether a non-file -buffer needs reverting. This should be a function with one optional -argument @var{noconfirm}. The function should return non-@code{nil} -if the buffer should be reverted. The buffer is current when this -function is called. - -While this function is mainly intended for use in auto-reverting, it -could be used for other purposes as well. For instance, if -auto-reverting is not enabled, it could be used to warn the user that -the buffer needs reverting. The idea behind the @var{noconfirm} -argument is that it should be @code{t} if the buffer is going to be -reverted without asking the user and @code{nil} if the function is -just going to be used to warn the user that the buffer is out of date. -In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. -If the function is only going to be used for auto-reverting, you can -ignore the @var{noconfirm} argument. - -If you just want to automatically auto-revert every -@code{auto-revert-interval} seconds (like the Buffer Menu), use: - -@example -(set (make-local-variable 'buffer-stale-function) - #'(lambda (&optional noconfirm) 'fast)) -@end example - -@noindent -in the buffer's mode function. - -The special return value @samp{fast} tells the caller that the need -for reverting was not checked, but that reverting the buffer is fast. -It also tells Auto Revert not to print any revert messages, even if -@code{auto-revert-verbose} is non-@code{nil}. This is important, as -getting revert messages every @code{auto-revert-interval} seconds can -be very annoying. The information provided by this return value could -also be useful if the function is consulted for purposes other than -auto-reverting. -@end defvar - -Once the buffer has a @code{revert-buffer-function} and a -@code{buffer-stale-function}, several problems usually remain. - -The buffer will only auto-revert if it is marked unmodified. Hence, -you will have to make sure that various functions mark the buffer -modified if and only if either the buffer contains information that -might be lost by reverting, or there is reason to believe that the user -might be inconvenienced by auto-reverting, because he is actively -working on the buffer. The user can always override this by manually -adjusting the modified status of the buffer. To support this, calling -the @code{revert-buffer-function} on a buffer that is marked -unmodified should always keep the buffer marked unmodified. - -It is important to assure that point does not continuously jump around -as a consequence of auto-reverting. Of course, moving point might be -inevitable if the buffer radically changes. - -You should make sure that the @code{revert-buffer-function} does not -print messages that unnecessarily duplicate Auto Revert's own messages, -displayed if @code{auto-revert-verbose} is @code{t}, and effectively -override a @code{nil} value for @code{auto-revert-verbose}. Hence, -adapting a mode for auto-reverting often involves getting rid of such -messages. This is especially important for buffers that automatically -revert every @code{auto-revert-interval} seconds. - -If the new auto-reverting is part of Emacs, you should mention it -in the documentation string of @code{global-auto-revert-non-file-buffers}. - -@ifinfo -Similarly, you should add a node to this chapter's menu. This node -@end ifinfo -@ifnotinfo -Similarly, you should add a section to this chapter. This section -@end ifnotinfo -should at the very least make clear whether enabling auto-reverting -for the buffer reliably assures that all information in the buffer is -completely up to date (or will be after @code{auto-revert-interval} -seconds). diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi deleted file mode 100644 index 2650b55811f..00000000000 --- a/doc/emacs/basic.texi +++ /dev/null @@ -1,796 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Basic, Minibuffer, Exiting, Top -@chapter Basic Editing Commands - -@kindex C-h t -@findex help-with-tutorial - Here we explain the basics of how to enter text, make corrections, -and save the text in a file. If this material is new to you, we -suggest you first run the Emacs learn-by-doing tutorial, by typing -@kbd{C-h t} (@code{help-with-tutorial}). - -@menu - -* Inserting Text:: Inserting text by simply typing it. -* Moving Point:: Moving the cursor to the place where you want to - change something. -* Erasing:: Deleting and killing text. -* Basic Undo:: Undoing recent changes in the text. -* Files: Basic Files. Visiting, creating, and saving files. -* Help: Basic Help. Asking what a character does. -* Blank Lines:: Making and deleting blank lines. -* Continuation Lines:: How Emacs displays lines too wide for the screen. -* Position Info:: What line, row, or column is point on? -* Arguments:: Numeric arguments for repeating a command N times. -* Repeating:: Repeating the previous command quickly. -@end menu - -@node Inserting Text -@section Inserting Text - -@cindex insertion -@cindex graphic characters - You can insert an ordinary @dfn{graphic character} (e.g., @samp{a}, -@samp{B}, @samp{3}, and @samp{=}) by typing the associated key. This -adds the character to the buffer at point. Insertion moves point -forward, so that point remains just after the inserted text. -@xref{Point}. - -@kindex RET -@cindex newline - To end a line and start a new one, type @key{RET} (@code{newline}). -(The @key{RET} key may be labeled @key{Return} or @key{Enter} on your -keyboard, but we refer to it as @key{RET} in this manual.) This -command inserts a newline character into the buffer. If point is at -the end of the line, the effect is to create a new blank line after -it; if point is in the middle of a line, the line is split at that -position. - - As we explain later in this manual, you can change the way Emacs -handles text insertion by turning on @dfn{minor modes}. For instance, -the minor mode called Auto Fill mode splits lines automatically when -they get too long (@pxref{Filling}). The minor mode called Overwrite -mode causes inserted characters to replace (overwrite) existing text, -instead of shoving it to the right. @xref{Minor Modes}. - -@cindex quoting -@kindex C-q -@findex quoted-insert - Only graphic characters can be inserted by typing the associated -key; other keys act as editing commands and do not insert themselves. -For instance, @kbd{DEL} runs the command @code{delete-backward-char} -by default (some modes bind it to a different command); it does not -insert a literal @samp{DEL} character (@acronym{ASCII} character code -127). - - To insert a non-graphic character, or a character that your keyboard -does not support, first @dfn{quote} it by typing @kbd{C-q} -(@code{quoted-insert}). There are two ways to use @kbd{C-q}: - -@itemize @bullet -@item -@kbd{C-q} followed by any non-graphic character (even @kbd{C-g}) -inserts that character. For instance, @kbd{C-q @key{DEL}} inserts a -literal @samp{DEL} character. - -@item -@kbd{C-q} followed by a sequence of octal digits inserts the character -with the specified octal character code. You can use any number of -octal digits; any non-digit terminates the sequence. If the -terminating character is @key{RET}, that @key{RET} serves only to -terminate the sequence. Any other non-digit terminates the sequence -and then acts as normal input---thus, @kbd{C-q 1 0 1 B} inserts -@samp{AB}. - -The use of octal sequences is disabled in ordinary non-binary -Overwrite mode, to give you a convenient way to insert a digit instead -of overwriting with it. -@end itemize - -@vindex read-quoted-char-radix -@noindent -To use decimal or hexadecimal instead of octal, set the variable -@code{read-quoted-char-radix} to 10 or 16. If the radix is 16, -the letters @kbd{a} to @kbd{f} serve as part of a character code, -just like digits. Case is ignored. - -@findex ucs-insert -@kindex C-x 8 RET -@cindex Unicode characters, inserting -@cindex insert Unicode character -@cindex characters, inserting by name or code-point - Instead of @kbd{C-q}, you can use the command @kbd{C-x 8 @key{RET}} -(@code{ucs-insert}). This prompts for the Unicode name or code-point -of a character, using the minibuffer. If you enter a name, the -command provides completion (@pxref{Completion}). If you enter a -code-point, it should be a hexadecimal number (which is the convention -for Unicode). The command then inserts the corresponding character -into the buffer. For example, both of the following insert the -infinity sign (Unicode code-point @code{U+221E}): - -@example -@kbd{C-x 8 @key{RET} infinity @key{RET}} -@kbd{C-x 8 @key{RET} 221e @key{RET}} -@end example - - A numeric argument to either @kbd{C-q} or @kbd{C-x 8 @key{RET}} -specifies how many copies of the character to insert -(@pxref{Arguments}). - -@node Moving Point -@section Changing the Location of Point - -@cindex arrow keys -@cindex moving point -@cindex movement -@cindex cursor motion -@cindex moving the cursor - To do more than insert characters, you have to know how to move -point (@pxref{Point}). The keyboard commands @kbd{C-f}, @kbd{C-b}, -@kbd{C-n}, and @kbd{C-p} move point to the right, left, down, and up, -respectively. You can also move point using the @dfn{arrow keys} -present on most keyboards: @kbd{@key{right}}, @kbd{@key{left}}, -@kbd{@key{down}}, and @kbd{@key{up}}; however, many Emacs users find -that it is slower to use the arrow keys than the control keys, because -you need to move your hand to the area of the keyboard where those -keys are located. - - You can also click the left mouse button to move point to the -position clicked. Emacs also provides a variety of additional -keyboard commands that move point in more sophisticated ways. - -@table @kbd - -@item C-f -@kindex C-f -@findex forward-char -Move forward one character (@code{forward-char}). - -@item @key{right} -@kindex RIGHT -@findex right-char -This command (@code{right-char}) behaves like @kbd{C-f}, with one -exception: when editing right-to-left scripts such as Arabic, it -instead moves @emph{backward} if the current paragraph is a -right-to-left paragraph. @xref{Bidirectional Editing}. - -@item C-b -@kindex C-b -@findex backward-char -Move backward one character (@code{backward-char}). - -@item @key{left} -@kindex LEFT -@findex left-char -This command (@code{left-char}) behaves like @kbd{C-b}, except it -moves @emph{forward} if the current paragraph is right-to-left. -@xref{Bidirectional Editing}. - -@item C-n -@itemx @key{down} -@kindex C-n -@kindex DOWN -@findex next-line -Move down one screen line (@code{next-line}). This command attempts -to keep the horizontal position unchanged, so if you start in the -middle of one line, you move to the middle of the next. - -@item C-p -@itemx @key{up} -@kindex C-p -@kindex UP -@findex previous-line -Move up one screen line (@code{previous-line}). This command -preserves position within the line, like @kbd{C-n}. - -@item C-a -@itemx @key{Home} -@kindex C-a -@kindex HOME -@findex move-beginning-of-line -Move to the beginning of the line (@code{move-beginning-of-line}). - -@item C-e -@itemx @key{End} -@kindex C-e -@kindex END -@findex move-end-of-line -Move to the end of the line (@code{move-end-of-line}). - -@item M-f -@kindex M-f -@findex forward-word -Move forward one word (@code{forward-word}). - -@item C-@key{right} -@itemx M-@key{right} -@kindex C-RIGHT -@kindex M-RIGHT -@findex right-word -This command (@code{right-word}) behaves like @kbd{M-f}, except it -moves @emph{backward} by one word if the current paragraph is -right-to-left. @xref{Bidirectional Editing}. - -@item M-b -@kindex M-b -@findex backward-word -Move backward one word (@code{backward-word}). - -@item C-@key{left} -@itemx M-@key{left} -@kindex C-LEFT -@kindex M-LEFT -@findex left-word -This command (@code{left-word}) behaves like @kbd{M-f}, except it -moves @emph{forward} by one word if the current paragraph is -right-to-left. @xref{Bidirectional Editing}. - -@item M-r -@kindex M-r -@findex move-to-window-line-top-bottom -Without moving the text on the screen, reposition point on the left -margin of the center-most text line of the window; on subsequent -consecutive invocations, move point to the left margin of the top-most -line, the bottom-most line, and so forth, in cyclic order -(@code{move-to-window-line-top-bottom}). - -A numeric argument says which screen line to place point on, counting -downward from the top of the window (zero means the top line). A -negative argument counts lines up from the bottom (@minus{}1 means the -bottom line). @xref{Arguments}, for more information on numeric -arguments. - -@item M-< -@kindex M-< -@findex beginning-of-buffer -Move to the top of the buffer (@code{beginning-of-buffer}). With -numeric argument @var{n}, move to @var{n}/10 of the way from the top. - -@item M-> -@kindex M-> -@findex end-of-buffer -Move to the end of the buffer (@code{end-of-buffer}). - -@item C-v -@itemx @key{PageDown} -@itemx @key{next} -Scroll the display one screen forward, and move point onscreen if -necessary (@code{scroll-up-command}). @xref{Scrolling}. - -@item M-v -@itemx @key{PageUp} -@itemx @key{prior} -Scroll one screen backward, and move point onscreen if necessary -(@code{scroll-down-command}). @xref{Scrolling}. - -@item M-x goto-char -@findex goto-char -Read a number @var{n} and move point to buffer position @var{n}. -Position 1 is the beginning of the buffer. - -@item M-g M-g -@itemx M-g g -@kindex M-g M-g -@kindex M-g g -@findex goto-line -Read a number @var{n} and move point to the beginning of line number -@var{n} (@code{goto-line}). Line 1 is the beginning of the buffer. If -point is on or just after a number in the buffer, that is the default -for @var{n}. Just type @key{RET} in the minibuffer to use it. You can -also specify @var{n} by giving @kbd{M-g M-g} a numeric prefix argument. -@xref{Select Buffer}, for the behavior of @kbd{M-g M-g} when you give it -a plain prefix argument. - -@item C-x C-n -@kindex C-x C-n -@findex set-goal-column -Use the current column of point as the @dfn{semipermanent goal column} -for @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}). When a -semipermanent goal column is in effect, those commands always try to -move to this column, or as close as possible to it, after moving -vertically. The goal column remains in effect until canceled. - -@item C-u C-x C-n -Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} try to -preserve the horizontal position, as usual. -@end table - -@vindex line-move-visual - When a line of text in the buffer is longer than the width of the -window, Emacs usually displays it on two or more @dfn{screen lines}. -For convenience, @kbd{C-n} and @kbd{C-p} move point by screen lines, -as do the equivalent keys @kbd{@key{down}} and @kbd{@key{up}}. You -can force these commands to move according to @dfn{logical lines} -(i.e., according to the text lines in the buffer) by setting the -variable @code{line-move-visual} to @code{nil}; if a logical line -occupies multiple screen lines, the cursor then skips over the -additional screen lines. For details, see @ref{Continuation Lines}. -@xref{Variables}, for how to set variables such as -@code{line-move-visual}. - - Unlike @kbd{C-n} and @kbd{C-p}, most of the Emacs commands that work -on lines work on @emph{logical} lines. For instance, @kbd{C-a} -(@code{move-beginning-of-line}) and @kbd{C-e} -(@code{move-end-of-line}) respectively move to the beginning and end -of the logical line. Whenever we encounter commands that work on -screen lines, such as @kbd{C-n} and @kbd{C-p}, we will point these -out. - -@vindex track-eol - When @code{line-move-visual} is @code{nil}, you can also set the -variable @code{track-eol} to a non-@code{nil} value. Then @kbd{C-n} -and @kbd{C-p}, when starting at the end of the logical line, move to -the end of the next logical line. Normally, @code{track-eol} is -@code{nil}. - -@vindex next-line-add-newlines - @kbd{C-n} normally stops at the end of the buffer when you use it on -the last line in the buffer. However, if you set the variable -@code{next-line-add-newlines} to a non-@code{nil} value, @kbd{C-n} on -the last line of a buffer creates an additional line at the end and -moves down into it. - -@node Erasing -@section Erasing Text -@cindex killing characters and lines -@cindex deleting characters and lines -@cindex erasing characters and lines - -@table @kbd -@item @key{DEL} -@itemx @key{Backspace} -Delete the character before point, or the region if it is active -(@code{delete-backward-char}). - -@itemx @key{Delete} -Delete the character after point, or the region if it is active -(@code{delete-forward-char}). - -@item C-d -Delete the character after point (@code{delete-char}). - -@item C-k -Kill to the end of the line (@code{kill-line}). -@item M-d -Kill forward to the end of the next word (@code{kill-word}). -@item M-@key{DEL} -Kill back to the beginning of the previous word -(@code{backward-kill-word}). -@end table - - The @kbd{@key{DEL}} (@code{delete-backward-char}) command removes -the character before point, moving the cursor and the characters after -it backwards. If point was at the beginning of a line, this deletes -the preceding newline, joining this line to the previous one. - - If, however, the region is active, @kbd{@key{DEL}} instead deletes -the text in the region. @xref{Mark}, for a description of the region. - - On most keyboards, @key{DEL} is labeled @key{Backspace}, but we -refer to it as @key{DEL} in this manual. (Do not confuse @key{DEL} -with the @key{Delete} key; we will discuss @key{Delete} momentarily.) -On some text terminals, Emacs may not recognize the @key{DEL} key -properly. @xref{DEL Does Not Delete}, if you encounter this problem. - - The @key{delete} (@code{delete-forward-char}) command deletes in the -``opposite direction'': it deletes the character after point, i.e. the -character under the cursor. If point was at the end of a line, this -joins the following line onto this one. Like @kbd{@key{DEL}}, it -deletes the text in the region if the region is active (@pxref{Mark}). - - @kbd{C-d} (@code{delete-char}) deletes the character after point, -similar to @key{delete}, but regardless of whether the region is -active. - - @xref{Deletion}, for more detailed information about the above -deletion commands. - - @kbd{C-k} (@code{kill-line}) erases (kills) a line at a time. If -you type @kbd{C-k} at the beginning or middle of a line, it kills all -the text up to the end of the line. If you type @kbd{C-k} at the end -of a line, it joins that line with the following line. - - @xref{Killing}, for more information about @kbd{C-k} and related -commands. - -@node Basic Undo -@section Undoing Changes - -@table @kbd -@item C-/ -Undo one entry of the undo records---usually, one command worth -(@code{undo}). -@itemx C-x u -@itemx C-_ -The same. -@end table - - Emacs records a list of changes made in the buffer text, so you can -undo recent changes. This is done using the @code{undo} command, -which is bound to @kbd{C-/} (as well as @kbd{C-x u} and @kbd{C-_}). -Normally, this command undoes the last change, moving point back to -where it was before the change. The undo command applies only to -changes in the buffer; you can't use it to undo cursor motion. - - Although each editing command usually makes a separate entry in the -undo records, very simple commands may be grouped together. -Sometimes, an entry may cover just part of a complex command. - - If you repeat @kbd{C-/} (or its aliases), each repetition undoes -another, earlier change, back to the limit of the undo information -available. If all recorded changes have already been undone, the undo -command displays an error message and does nothing. - - To learn more about the @code{undo} command, see @ref{Undo}. - -@node Basic Files -@section Files - - Text that you insert in an Emacs buffer lasts only as long as the -Emacs session. To keep any text permanently, you must put it in a -@dfn{file}. - - Suppose there is a file named @file{test.emacs} in your home -directory. To begin editing this file in Emacs, type - -@example -C-x C-f test.emacs @key{RET} -@end example - -@noindent -Here the file name is given as an @dfn{argument} to the command @kbd{C-x -C-f} (@code{find-file}). That command uses the @dfn{minibuffer} to -read the argument, and you type @key{RET} to terminate the argument -(@pxref{Minibuffer}). - - Emacs obeys this command by @dfn{visiting} the file: it creates a -buffer, copies the contents of the file into the buffer, and then -displays the buffer for editing. If you alter the text, you can -@dfn{save} the new text in the file by typing @kbd{C-x C-s} -(@code{save-buffer}). This copies the altered buffer contents back -into the file @file{test.emacs}, making them permanent. Until you -save, the changed text exists only inside Emacs, and the file -@file{test.emacs} is unaltered. - - To create a file, just visit it with @kbd{C-x C-f} as if it already -existed. This creates an empty buffer, in which you can insert the -text you want to put in the file. Emacs actually creates the file the -first time you save this buffer with @kbd{C-x C-s}. - - To learn more about using files in Emacs, see @ref{Files}. - -@node Basic Help -@section Help - -@cindex getting help with keys - If you forget what a key does, you can find out by typing @kbd{C-h -k} (@code{describe-key}), followed by the key of interest; for -example, @kbd{C-h k C-n} tells you what @kbd{C-n} does. - - The prefix key @kbd{C-h} stands for ``help''. The key @key{F1} -serves as an alias for @kbd{C-h}. Apart from @kbd{C-h k}, there are -many other help commands providing different kinds of help. - - @xref{Help}, for details. - -@node Blank Lines -@section Blank Lines - -@cindex inserting blank lines -@cindex deleting blank lines - Here are special commands and techniques for inserting and deleting -blank lines. - -@table @kbd -@item C-o -Insert a blank line after the cursor (@code{open-line}). -@item C-x C-o -Delete all but one of many consecutive blank lines -(@code{delete-blank-lines}). -@end table - -@kindex C-o -@kindex C-x C-o -@cindex blank lines -@findex open-line -@findex delete-blank-lines - We have seen how @kbd{@key{RET}} (@code{newline}) starts a new line -of text. However, it may be easier to see what you are doing if you -first make a blank line and then insert the desired text into it. -This is easy to do using the key @kbd{C-o} (@code{open-line}), which -inserts a newline after point but leaves point in front of the -newline. After @kbd{C-o}, type the text for the new line. - - You can make several blank lines by typing @kbd{C-o} several times, or -by giving it a numeric argument specifying how many blank lines to make. -@xref{Arguments}, for how. If you have a fill prefix, the @kbd{C-o} -command inserts the fill prefix on the new line, if typed at the -beginning of a line. @xref{Fill Prefix}. - - The easy way to get rid of extra blank lines is with the command -@kbd{C-x C-o} (@code{delete-blank-lines}). If point lies within a run -of several blank lines, @kbd{C-x C-o} deletes all but one of them. If -point is on a single blank line, @kbd{C-x C-o} deletes it. If point -is on a nonblank line, @kbd{C-x C-o} deletes all following blank -lines, if any exists. - -@node Continuation Lines -@section Continuation Lines - -@cindex continuation line -@cindex wrapping -@cindex line wrapping -@cindex fringes, and continuation lines - Sometimes, a line of text in the buffer---a @dfn{logical line}---is -too long to fit in the window, and Emacs displays it as two or more -@dfn{screen lines}. This is called @dfn{line wrapping} or -@dfn{continuation}, and the long logical line is called a -@dfn{continued line}. On a graphical display, Emacs indicates line -wrapping with small bent arrows in the left and right window fringes. -On a text terminal, Emacs indicates line wrapping by displaying a -@samp{\} character at the right margin. - - Most commands that act on lines act on logical lines, not screen -lines. For instance, @kbd{C-k} kills a logical line. As described -earlier, @kbd{C-n} (@code{next-line}) and @kbd{C-p} -(@code{previous-line}) are special exceptions: they move point down -and up, respectively, by one screen line (@pxref{Moving Point}). - -@cindex truncation -@cindex line truncation, and fringes - Emacs can optionally @dfn{truncate} long logical lines instead of -continuing them. This means that every logical line occupies a single -screen line; if it is longer than the width of the window, the rest of -the line is not displayed. On a graphical display, a truncated line -is indicated by a small straight arrow in the right fringe; on a text -terminal, it is indicated by a @samp{$} character in the right margin. -@xref{Line Truncation}. - - By default, continued lines are wrapped at the right window edge. -Since the wrapping may occur in the middle of a word, continued lines -can be difficult to read. The usual solution is to break your lines -before they get too long, by inserting newlines. If you prefer, you -can make Emacs insert a newline automatically when a line gets too -long, by using Auto Fill mode. @xref{Filling}. - -@cindex word wrap - Sometimes, you may need to edit files containing many long logical -lines, and it may not be practical to break them all up by adding -newlines. In that case, you can use Visual Line mode, which enables -@dfn{word wrapping}: instead of wrapping long lines exactly at the -right window edge, Emacs wraps them at the word boundaries (i.e., -space or tab characters) nearest to the right window edge. Visual -Line mode also redefines editing commands such as @code{C-a}, -@code{C-n}, and @code{C-k} to operate on screen lines rather than -logical lines. @xref{Visual Line Mode}. - -@node Position Info -@section Cursor Position Information - - Here are commands to get information about the size and position of -parts of the buffer, and to count words and lines. - -@table @kbd -@item M-x what-line -Display the line number of point. -@item M-x line-number-mode -@itemx M-x column-number-mode -Toggle automatic display of the current line number or column number. -@xref{Optional Mode Line}. - -@item M-= -Display the number of lines, words, and characters that are present in -the region (@code{count-words-region}). @xref{Mark}, for information -about the region. - -@item M-x count-words -Display the number of lines, words, and characters that are present in -the buffer. If the region is active (@pxref{Mark}), display the -numbers for the region instead. - -@item C-x = -Display the character code of character after point, character position of -point, and column of point (@code{what-cursor-position}). -@item M-x hl-line-mode -Enable or disable highlighting of the current line. @xref{Cursor -Display}. -@item M-x size-indication-mode -Toggle automatic display of the size of the buffer. -@xref{Optional Mode Line}. -@end table - -@findex what-line -@cindex line number commands -@cindex location of point -@cindex cursor location -@cindex point location - @kbd{M-x what-line} displays the current line number in the echo -area. This command is usually redundant, because the current line -number is shown in the mode line (@pxref{Mode Line}). However, if you -narrow the buffer, the mode line shows the line number relative to -the accessible portion (@pxref{Narrowing}). By contrast, -@code{what-line} displays both the line number relative to the -narrowed region and the line number relative to the whole buffer. - -@kindex M-= -@findex count-words-region -@findex count-words - @kbd{M-=} (@code{count-words-region}) displays a message reporting -the number of lines, words, and characters in the region. @kbd{M-x -count-words} displays a similar message for the entire buffer, or for -the region if the region is @dfn{active}. @xref{Mark}, for an -explanation of the region. - -@kindex C-x = -@findex what-cursor-position - The command @kbd{C-x =} (@code{what-cursor-position}) shows -information about the current cursor position and the buffer contents -at that position. It displays a line in the echo area that looks like -this: - -@smallexample -Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53 -@end smallexample - - After @samp{Char:}, this shows the character in the buffer at point. -The text inside the parenthesis shows the corresponding decimal, octal -and hex character codes; for more information about how @kbd{C-x =} -displays character information, see @ref{International Chars}. After -@samp{point=} is the position of point as a character count (the first -character in the buffer is position 1, the second character is -position 2, and so on). The number after that is the total number of -characters in the buffer, and the number in parenthesis expresses the -position as a percentage of the total. After @samp{column=} is the -horizontal position of point, in columns counting from the left edge -of the window. - - If the buffer has been narrowed, making some of the text at the -beginning and the end temporarily inaccessible, @kbd{C-x =} displays -additional text describing the currently accessible range. For -example, it might display this: - -@smallexample -Char: C (67, #o103, #x43) point=252 of 889 (28%) <231-599> column=0 -@end smallexample - -@noindent -where the two extra numbers give the smallest and largest character -position that point is allowed to assume. The characters between -those two positions are the accessible ones. @xref{Narrowing}. - -@node Arguments -@section Numeric Arguments -@cindex numeric arguments -@cindex prefix arguments -@cindex arguments to commands - - In the terminology of mathematics and computing, @dfn{argument} -means ``data provided to a function or operation''. You can give any -Emacs command a @dfn{numeric argument} (also called a @dfn{prefix -argument}). Some commands interpret the argument as a repetition -count. For example, giving @kbd{C-f} an argument of ten causes it to -move point forward by ten characters instead of one. With these -commands, no argument is equivalent to an argument of one, and -negative arguments cause them to move or act in the opposite -direction. - -@kindex M-1 -@kindex M-@t{-} -@findex digit-argument -@findex negative-argument - The easiest way to specify a numeric argument is to type a digit -and/or a minus sign while holding down the @key{META} key. For -example, - -@example -M-5 C-n -@end example - -@noindent -moves down five lines. The keys @kbd{M-1}, @kbd{M-2}, and so on, as -well as @kbd{M--}, are bound to commands (@code{digit-argument} and -@code{negative-argument}) that set up an argument for the next -command. @kbd{Meta--} without digits normally means @minus{}1. - -If you enter more than one digit, you need not hold down the -@key{META} key for the second and subsequent digits. Thus, to move -down fifty lines, type - -@example -M-5 0 C-n -@end example - -@noindent -Note that this @emph{does not} insert five copies of @samp{0} and move -down one line, as you might expect---the @samp{0} is treated as part -of the prefix argument. - -(What if you do want to insert five copies of @samp{0}? Type @kbd{M-5 -C-u 0}. Here, @kbd{C-u} ``terminates'' the prefix argument, so that -the next keystroke begins the command that you want to execute. Note -that this meaning of @kbd{C-u} applies only to this case. For the -usual role of @kbd{C-u}, see below.) - -@kindex C-u -@findex universal-argument - Instead of typing @kbd{M-1}, @kbd{M-2}, and so on, another way to -specify a numeric argument is to type @kbd{C-u} -(@code{universal-argument}) followed by some digits, or (for a -negative argument) a minus sign followed by digits. A minus sign -without digits normally means @minus{}1. - - @kbd{C-u} alone has the special meaning of ``four times'': it -multiplies the argument for the next command by four. @kbd{C-u C-u} -multiplies it by sixteen. Thus, @kbd{C-u C-u C-f} moves forward -sixteen characters. Other useful combinations are @kbd{C-u C-n}, -@kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u -C-u C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four -lines). - - You can use a numeric argument before a self-inserting character to -insert multiple copies of it. This is straightforward when the -character is not a digit; for example, @kbd{C-u 6 4 a} inserts 64 -copies of the character @samp{a}. But this does not work for -inserting digits; @kbd{C-u 6 4 1} specifies an argument of 641. You -can separate the argument from the digit to insert with another -@kbd{C-u}; for example, @kbd{C-u 6 4 C-u 1} does insert 64 copies of -the character @samp{1}. - - Some commands care whether there is an argument, but ignore its -value. For example, the command @kbd{M-q} (@code{fill-paragraph}) -fills text; with an argument, it justifies the text as well. -(@xref{Filling}, for more information on @kbd{M-q}.) For these -commands, it is enough to the argument with a single @kbd{C-u}. - - Some commands use the value of the argument as a repeat count, but -do something special when there is no argument. For example, the -command @kbd{C-k} (@code{kill-line}) with argument @var{n} kills -@var{n} lines, including their terminating newlines. But @kbd{C-k} -with no argument is special: it kills the text up to the next newline, -or, if point is right at the end of the line, it kills the newline -itself. Thus, two @kbd{C-k} commands with no arguments can kill a -nonblank line, just like @kbd{C-k} with an argument of one. -(@xref{Killing}, for more information on @kbd{C-k}.) - - A few commands treat a plain @kbd{C-u} differently from an ordinary -argument. A few others may treat an argument of just a minus sign -differently from an argument of @minus{}1. These unusual cases are -described when they come up; they exist to make an individual command -more convenient, and they are documented in that command's -documentation string. - - We use the term ``prefix argument'' as well as ``numeric argument'', -to emphasize that you type these argument before the command, and to -distinguish them from minibuffer arguments that come after the -command. - -@node Repeating -@section Repeating a Command -@cindex repeating a command - - Many simple commands, such as those invoked with a single key or -with @kbd{M-x @var{command-name} @key{RET}}, can be repeated by -invoking them with a numeric argument that serves as a repeat count -(@pxref{Arguments}). However, if the command you want to repeat -prompts for input, or uses a numeric argument in another way, that -method won't work. - -@kindex C-x z -@findex repeat - The command @kbd{C-x z} (@code{repeat}) provides another way to repeat -an Emacs command many times. This command repeats the previous Emacs -command, whatever that was. Repeating a command uses the same arguments -that were used before; it does not read new arguments each time. - - To repeat the command more than once, type additional @kbd{z}'s: each -@kbd{z} repeats the command one more time. Repetition ends when you -type a character other than @kbd{z}, or press a mouse button. - - For example, suppose you type @kbd{C-u 2 0 C-d} to delete 20 -characters. You can repeat that command (including its argument) three -additional times, to delete a total of 80 characters, by typing @kbd{C-x -z z z}. The first @kbd{C-x z} repeats the command once, and each -subsequent @kbd{z} repeats it once again. diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi deleted file mode 100644 index 5dd95cc2a6f..00000000000 --- a/doc/emacs/buffers.texi +++ /dev/null @@ -1,640 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Buffers, Windows, Files, Top -@chapter Using Multiple Buffers - -@cindex buffers - The text you are editing in Emacs resides in an object called a -@dfn{buffer}. Each time you visit a file, a buffer is used to hold -the file's text. Each time you invoke Dired, a buffer is used to hold -the directory listing. If you send a message with @kbd{C-x m}, a -buffer is used to hold the text of the message. When you ask for a -command's documentation, that appears in a buffer named @file{*Help*}. - - Each buffer has a unique name, which can be of any length. When a -buffer is displayed in a window, its name is shown in the mode line -(@pxref{Mode Line}). The distinction between upper and lower case -matters in buffer names. Most buffers are made by visiting files, and -their names are derived from the files' names; however, you can also -create an empty buffer with any name you want. A newly started Emacs -has several buffers, including one named @file{*scratch*}, which can -be used for evaluating Lisp expressions and is not associated with any -file (@pxref{Lisp Interaction}). - -@cindex selected buffer -@cindex current buffer - At any time, one and only one buffer is @dfn{selected}; we call it -the @dfn{current buffer}. We sometimes say that a command operates on -``the buffer''; this really means that it operates on the current -buffer. When there is only one Emacs window, the buffer displayed in -that window is current. When there are multiple windows, the buffer -displayed in the @dfn{selected window} is current. @xref{Windows}. - - Aside from its textual contents, each buffer records several pieces -of information, such as what file it is visiting (if any), whether it -is modified, and what major mode and minor modes are in effect -(@pxref{Modes}). These are stored in @dfn{buffer-local -variables}---variables that can have a different value in each buffer. -@xref{Locals}. - -@cindex buffer size, maximum - A buffer's size cannot be larger than some maximum, which is defined -by the largest buffer position representable by @dfn{Emacs integers}. -This is because Emacs tracks buffer positions using that data type. -For typical 64-bit machines, this maximum buffer size is @math{2^61 - -2} bytes, or about 2 EiB. For typical 32-bit machines, the maximum is -usually @math{2^29 - 2} bytes, or about 512 MiB. Buffer sizes are -also limited by the amount of memory in the system. - -@menu -* Select Buffer:: Creating a new buffer or reselecting an old one. -* List Buffers:: Getting a list of buffers that exist. -* Misc Buffer:: Renaming; changing read-onlyness; copying text. -* Kill Buffer:: Killing buffers you no longer need. -* Several Buffers:: How to go through the list of all buffers - and operate variously on several of them. -* Indirect Buffers:: An indirect buffer shares the text of another buffer. -* Buffer Convenience:: Convenience and customization features for - buffer handling. -@end menu - -@node Select Buffer -@section Creating and Selecting Buffers -@cindex change buffers -@cindex switch buffers - -@table @kbd -@item C-x b @var{buffer} @key{RET} -Select or create a buffer named @var{buffer} (@code{switch-to-buffer}). -@item C-x 4 b @var{buffer} @key{RET} -Similar, but select @var{buffer} in another window -(@code{switch-to-buffer-other-window}). -@item C-x 5 b @var{buffer} @key{RET} -Similar, but select @var{buffer} in a separate frame -(@code{switch-to-buffer-other-frame}). -@item C-x @key{LEFT} -Select the previous buffer in the buffer list (@code{previous-buffer}). -@item C-x @key{RIGHT} -Select the next buffer in the buffer list (@code{next-buffer}). -@item C-u M-g M-g -@itemx C-u M-g g -Read a number @var{n} and move to line @var{n} in the most recently -selected buffer other than the current buffer. -@end table - -@kindex C-x b -@findex switch-to-buffer - The @kbd{C-x b} (@code{switch-to-buffer}) command reads a buffer -name using the minibuffer. Then it makes that buffer current, and -displays it in the currently-selected window. An empty input -specifies the buffer that was current most recently among those not -now displayed in any window. - - While entering the buffer name, you can use the usual completion and -history commands (@pxref{Minibuffer}). Note that @kbd{C-x b}, and -related commands, use ``permissive completion with confirmation'' for -minibuffer completion: if you type @key{RET} immediately after -completing up to a nonexistent buffer name, Emacs prints -@samp{[Confirm]} and you must type a second @key{RET} to submit that -buffer name. @xref{Completion Exit}, for details. - - If you specify a buffer that does not exist, @kbd{C-x b} creates a -new, empty buffer that is not visiting any file, and selects it for -editing. The default value of the variable @code{major-mode} -determines the new buffer's major mode; the default value is -Fundamental mode. @xref{Major Modes}. One reason to create a new -buffer is to use it for making temporary notes. If you try to save -it, Emacs asks for the file name to use, and the buffer's major mode -is re-established taking that file name into account (@pxref{Choosing -Modes}). - -@kindex C-x @key{LEFT} -@kindex C-x @key{RIGHT} -@findex next-buffer -@findex previous-buffer - For conveniently switching between a few buffers, use the commands -@kbd{C-x @key{LEFT}} and @kbd{C-x @key{RIGHT}}. @kbd{C-x @key{LEFT}} -(@code{previous-buffer}) selects the previous buffer (following the -order of most recent selection in the current frame), while @kbd{C-x -@key{RIGHT}} (@code{next-buffer}) moves through buffers in the reverse -direction. - -@kindex C-x 4 b -@findex switch-to-buffer-other-window - To select a buffer in a window other than the current one, type -@kbd{C-x 4 b} (@code{switch-to-buffer-other-window}). This prompts -for a buffer name using the minibuffer, displays that buffer in -another window, and selects that window. - -@kindex C-x 5 b -@findex switch-to-buffer-other-frame - Similarly, @kbd{C-x 5 b} (@code{switch-to-buffer-other-frame}) -prompts for a buffer name, displays that buffer in another frame, and -selects that frame. If the buffer is already being shown in a window -on another frame, Emacs selects that window and frame instead of -creating a new frame. - - @xref{Displaying Buffers}, for how the @kbd{C-x 4 b} and @kbd{C-x 5 -b} commands get the window and/or frame to display in. - - In addition, @kbd{C-x C-f}, and any other command for visiting a -file, can also be used to switch to an existing file-visiting buffer. -@xref{Visiting}. - -@findex goto-line - @kbd{C-u M-g M-g}, that is @code{goto-line} with a plain prefix -argument, reads a number @var{n} using the minibuffer, selects the -most recently selected buffer other than the current buffer in another -window, and then moves point to the beginning of line number @var{n} -in that buffer. This is mainly useful in a buffer that refers to line -numbers in another buffer: if point is on or just after a number, -@code{goto-line} uses that number as the default for @var{n}. Note -that prefix arguments other than just @kbd{C-u} behave differently. -@kbd{C-u 4 M-g M-g} goes to line 4 in the @emph{current} buffer, -without reading a number from the minibuffer. (Remember that @kbd{M-g -M-g} without prefix argument reads a number @var{n} and then moves to -line number @var{n} in the current buffer. @xref{Moving Point}.) - - Emacs uses buffer names that start with a space for internal purposes. -It treats these buffers specially in minor ways---for example, by -default they do not record undo information. It is best to avoid using -such buffer names yourself. - -@node List Buffers -@section Listing Existing Buffers - -@table @kbd -@item C-x C-b -List the existing buffers (@code{list-buffers}). -@end table - -@cindex listing current buffers -@kindex C-x C-b -@findex list-buffers - To display a list of existing buffers, type @kbd{C-x C-b}. Each -line in the list shows one buffer's name, major mode and visited file. -The buffers are listed in the order that they were current; the -buffers that were current most recently come first. - - @samp{.} in the first field of a line indicates that the buffer is -current. @samp{%} indicates a read-only buffer. @samp{*} indicates -that the buffer is ``modified''. If several buffers are modified, it -may be time to save some with @kbd{C-x s} (@pxref{Save Commands}). -Here is an example of a buffer list: - -@smallexample -CRM Buffer Size Mode File -. * .emacs 3294 Emacs-Lisp ~/.emacs - % *Help* 101 Help - search.c 86055 C ~/cvs/emacs/src/search.c - % src 20959 Dired by name ~/cvs/emacs/src/ - * *mail* 42 Mail - % HELLO 1607 Fundamental ~/cvs/emacs/etc/HELLO - % NEWS 481184 Outline ~/cvs/emacs/etc/NEWS - *scratch* 191 Lisp Interaction - * *Messages* 1554 Fundamental -@end smallexample - -@noindent -The buffer @file{*Help*} was made by a help request (@pxref{Help}); it -is not visiting any file. The buffer @code{src} was made by Dired on -the directory @file{~/cvs/emacs/src/}. You can list only buffers that -are visiting files by giving the command a prefix argument, as in -@kbd{C-u C-x C-b}. - - @code{list-buffers} omits buffers whose names begin with a space, -unless they visit files: such buffers are used internally by Emacs. - -@node Misc Buffer -@section Miscellaneous Buffer Operations - -@table @kbd -@item C-x C-q -Toggle read-only status of buffer (@code{toggle-read-only}). -@item M-x rename-buffer @key{RET} @var{name} @key{RET} -Change the name of the current buffer. -@item M-x rename-uniquely -Rename the current buffer by adding @samp{<@var{number}>} to the end. -@item M-x view-buffer @key{RET} @var{buffer} @key{RET} -Scroll through buffer @var{buffer}. @xref{View Mode}. -@end table - -@kindex C-x C-q -@vindex buffer-read-only -@cindex read-only buffer - A buffer can be @dfn{read-only}, which means that commands to change -its contents are not allowed. The mode line indicates read-only -buffers with @samp{%%} or @samp{%*} near the left margin. Read-only -buffers are usually made by subsystems such as Dired and Rmail that -have special commands to operate on the text; also by visiting a file -whose access control says you cannot write it. - -@findex toggle-read-only - The command @kbd{C-x C-q} (@code{toggle-read-only}) makes a read-only -buffer writable, and makes a writable buffer read-only. This works by -setting the variable @code{buffer-read-only}, which has a local value -in each buffer and makes the buffer read-only if its value is -non-@code{nil}. - -@findex rename-buffer - @kbd{M-x rename-buffer} changes the name of the current buffer. You -specify the new name as a minibuffer argument; there is no default. -If you specify a name that is in use for some other buffer, an error -happens and no renaming is done. - -@findex rename-uniquely - @kbd{M-x rename-uniquely} renames the current buffer to a similar -name with a numeric suffix added to make it both different and unique. -This command does not need an argument. It is useful for creating -multiple shell buffers: if you rename the @file{*shell*} buffer, then -do @kbd{M-x shell} again, it makes a new shell buffer named -@file{*shell*}; meanwhile, the old shell buffer continues to exist -under its new name. This method is also good for mail buffers, -compilation buffers, and most Emacs features that create special -buffers with particular names. (With some of these features, such as -@kbd{M-x compile}, @kbd{M-x grep}, you need to switch to some other -buffer before using the command again, otherwise it will reuse the -current buffer despite the name change.) - - The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer} -can also be used to copy text from one buffer to another. -@xref{Accumulating Text}. - -@node Kill Buffer -@section Killing Buffers - -@cindex killing buffers - If you continue an Emacs session for a while, you may accumulate a -large number of buffers. You may then find it convenient to @dfn{kill} -the buffers you no longer need. On most operating systems, killing a -buffer releases its space back to the operating system so that other -programs can use it. Here are some commands for killing buffers: - -@table @kbd -@item C-x k @var{bufname} @key{RET} -Kill buffer @var{bufname} (@code{kill-buffer}). -@item M-x kill-some-buffers -Offer to kill each buffer, one by one. -@item M-x kill-matching-buffers -Offer to kill all buffers matching a regular expression. -@end table - -@findex kill-buffer -@kindex C-x k - @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you -specify in the minibuffer. The default, used if you type just -@key{RET} in the minibuffer, is to kill the current buffer. If you -kill the current buffer, another buffer becomes current: one that was -current in the recent past but is not displayed in any window now. If -you ask to kill a file-visiting buffer that is modified, then you must -confirm with @kbd{yes} before the buffer is killed. - -@findex kill-some-buffers - The command @kbd{M-x kill-some-buffers} asks about each buffer, one -by one. An answer of @kbd{y} means to kill the buffer, just like -@code{kill-buffer}. This command ignores buffers whose names begin -with a space, which are used internally by Emacs. - -@findex kill-matching-buffers - The command @kbd{M-x kill-matching-buffers} prompts for a regular -expression and kills all buffers whose names match that expression. -@xref{Regexps}. Like @code{kill-some-buffers}, it asks for -confirmation before each kill. This command normally ignores buffers -whose names begin with a space, which are used internally by Emacs. -To kill internal buffers as well, call @code{kill-matching-buffers} -with a prefix argument. - - The buffer menu feature is also convenient for killing various -buffers. @xref{Several Buffers}. - -@vindex kill-buffer-hook - If you want to do something special every time a buffer is killed, you -can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}). - -@findex clean-buffer-list - If you run one Emacs session for a period of days, as many people do, -it can fill up with buffers that you used several days ago. The command -@kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills -all the unmodified buffers that you have not used for a long time. An -ordinary buffer is killed if it has not been displayed for three days; -however, you can specify certain buffers that should never be killed -automatically, and others that should be killed if they have been unused -for a mere hour. - -@cindex Midnight mode -@vindex midnight-mode -@vindex midnight-hook - You can also have this buffer purging done for you, once a day, -by enabling Midnight mode. Midnight mode operates each day -at midnight; at that time, it runs @code{clean-buffer-list}, or -whichever functions you have placed in the normal hook -@code{midnight-hook} (@pxref{Hooks}). To enable Midnight mode, use -the Customization buffer to set the variable @code{midnight-mode} to -@code{t}. @xref{Easy Customization}. - -@node Several Buffers -@section Operating on Several Buffers -@cindex buffer menu - -@table @kbd -@item M-x buffer-menu -Begin editing a buffer listing all Emacs buffers. -@item M-x buffer-menu-other-window. -Similar, but do it in another window. -@end table - - The @dfn{buffer menu} opened by @kbd{C-x C-b} (@pxref{List Buffers}) -does not merely list buffers. It also allows you to perform various -operations on buffers, through an interface similar to Dired -(@pxref{Dired}). You can save buffers, kill them (here called -@dfn{deleting} them, for consistency with Dired), or display them. - -@findex buffer-menu -@findex buffer-menu-other-window - To use the buffer menu, type @kbd{C-x C-b} and switch to the window -displaying the @file{*Buffer List*} buffer. You can also type -@kbd{M-x buffer-menu} to open the buffer menu in the selected window. -Alternatively, the command @kbd{M-x buffer-menu-other-window} opens -the buffer menu in another window, and selects that window. - - The buffer menu is a read-only buffer, and can be changed only -through the special commands described in this section. The usual -cursor motion commands can be used in this buffer. The -following commands apply to the buffer described on the current line: - -@table @kbd -@item d -Request to delete (kill) the buffer, then move down. The request -shows as a @samp{D} on the line, before the buffer name. Requested -deletions take place when you type the @kbd{x} command. -@item C-d -Like @kbd{d} but move up afterwards instead of down. -@item s -Request to save the buffer. The request shows as an @samp{S} on the -line. Requested saves take place when you type the @kbd{x} command. -You may request both saving and deletion for the same buffer. -@item x -Perform previously requested deletions and saves. -@item u -Remove any request made for the current line, and move down. -@item @key{DEL} -Move to previous line and remove any request made for that line. -@end table - - The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove -flags also move down (or up) one line. They accept a numeric argument -as a repeat count. - - These commands operate immediately on the buffer listed on the current -line: - -@table @kbd -@item ~ -Mark the buffer ``unmodified''. The command @kbd{~} does this -immediately when you type it. -@item % -Toggle the buffer's read-only flag. The command @kbd{%} does -this immediately when you type it. -@item t -Visit the buffer as a tags table. @xref{Select Tags Table}. -@end table - - There are also commands to select another buffer or buffers: - -@table @kbd -@item q -Quit the buffer menu---immediately display the most recent formerly -visible buffer in its place. -@item @key{RET} -@itemx f -Immediately select this line's buffer in place of the @file{*Buffer -List*} buffer. -@item o -Immediately select this line's buffer in another window as if by -@kbd{C-x 4 b}, leaving @file{*Buffer List*} visible. -@item C-o -Immediately display this line's buffer in another window, but don't -select the window. -@item 1 -Immediately select this line's buffer in a full-screen window. -@item 2 -Immediately set up two windows, with this line's buffer selected in -one, and the previously current buffer (aside from the buffer -@file{*Buffer List*}) displayed in the other. -@item b -Bury the buffer listed on this line. -@item m -Mark this line's buffer to be displayed in another window if you exit -with the @kbd{v} command. The request shows as a @samp{>} at the -beginning of the line. (A single buffer may not have both a delete -request and a display request.) -@item v -Immediately select this line's buffer, and also display in other windows -any buffers previously marked with the @kbd{m} command. If you have not -marked any buffers, this command is equivalent to @kbd{1}. -@end table - - There is also a command that affects the entire buffer list: - -@table @kbd -@item T -Delete, or reinsert, lines for non-file buffers. This command toggles -the inclusion of such buffers in the buffer list. -@end table - - What @code{buffer-menu} actually does is create and switch to a -suitable buffer, and turn on Buffer Menu mode in it. Everything else -described above is implemented by the special commands provided in -Buffer Menu mode. One consequence of this is that you can switch from -the @file{*Buffer List*} buffer to another Emacs buffer, and edit -there. You can reselect the @file{*Buffer List*} buffer later, to -perform the operations already requested, or you can kill it, or pay -no further attention to it. - - Normally, the buffer @file{*Buffer List*} is not updated -automatically when buffers are created and killed; its contents are -just text. If you have created, deleted or renamed buffers, the way -to update @file{*Buffer List*} to show what you have done is to type -@kbd{g} (@code{revert-buffer}). You can make this happen regularly -every @code{auto-revert-interval} seconds if you enable Auto Revert -mode in this buffer, as long as it is not marked modified. Global -Auto Revert mode applies to the @file{*Buffer List*} buffer only if -@code{global-auto-revert-non-file-buffers} is non-@code{nil}. -@iftex -@inforef{Autorevert,, emacs-xtra}, for details. -@end iftex -@ifnottex -@xref{Autorevert, global-auto-revert-non-file-buffers}, for details. -@end ifnottex - -@node Indirect Buffers -@section Indirect Buffers -@cindex indirect buffer -@cindex base buffer - - An @dfn{indirect buffer} shares the text of some other buffer, which -is called the @dfn{base buffer} of the indirect buffer. In some ways it -is a buffer analogue of a symbolic link between files. - -@table @kbd -@findex make-indirect-buffer -@item M-x make-indirect-buffer @key{RET} @var{base-buffer} @key{RET} @var{indirect-name} @key{RET} -Create an indirect buffer named @var{indirect-name} with base buffer -@var{base-buffer}. -@findex clone-indirect-buffer -@item M-x clone-indirect-buffer @key{RET} -Create an indirect buffer that is a twin copy of the current buffer. -@item C-x 4 c -@kindex C-x 4 c -@findex clone-indirect-buffer-other-window -Create an indirect buffer that is a twin copy of the current buffer, and -select it in another window (@code{clone-indirect-buffer-other-window}). -@end table - - The text of the indirect buffer is always identical to the text of its -base buffer; changes made by editing either one are visible immediately -in the other. But in all other respects, the indirect buffer and its -base buffer are completely separate. They can have different names, -different values of point, different narrowing, different markers, -different major modes, and different local variables. - - An indirect buffer cannot visit a file, but its base buffer can. If -you try to save the indirect buffer, that actually works by saving the -base buffer. Killing the base buffer effectively kills the indirect -buffer, but killing an indirect buffer has no effect on its base buffer. - - One way to use indirect buffers is to display multiple views of an -outline. @xref{Outline Views}. - -@vindex clone-indirect-buffer-hook - A quick and handy way to make an indirect buffer is with the command -@kbd{M-x clone-indirect-buffer}. It creates and selects an indirect -buffer whose base buffer is the current buffer. With a numeric -argument, it prompts for the name of the indirect buffer; otherwise it -uses the name of the current buffer, with a @samp{<@var{n}>} suffix -added. @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window}) -works like @kbd{M-x clone-indirect-buffer}, but it selects the new -buffer in another window. These functions run the hook -@code{clone-indirect-buffer-hook} after creating the indirect buffer. - - The more general way to make an indirect buffer is with the command -@kbd{M-x make-indirect-buffer}. It creates an indirect buffer -named @var{indirect-name} from a buffer @var{base-buffer}, prompting for -both using the minibuffer. - -@node Buffer Convenience -@section Convenience Features and Customization of Buffer Handling - - This section describes several modes and features that make it more -convenient to switch between buffers. - -@menu -* Uniquify:: Making buffer names unique with directory parts. -* Iswitchb:: Switching between buffers with substrings. -* Buffer Menus:: Configurable buffer menu. -@end menu - -@node Uniquify -@subsection Making Buffer Names Unique - -@cindex unique buffer names -@cindex directories in buffer names - When several buffers visit identically-named files, Emacs must give -the buffers distinct names. The usual method for making buffer names -unique adds @samp{<2>}, @samp{<3>}, etc. to the end of the buffer -names (all but one of them). - -@vindex uniquify-buffer-name-style - Other methods work by adding parts of each file's directory to the -buffer name. To select one, load the library @file{uniquify} (e.g. -using @code{(require 'uniquify)}), and customize the variable -@code{uniquify-buffer-name-style} (@pxref{Easy Customization}). - - To begin with, the @code{forward} naming method includes part of the -file's directory name at the beginning of the buffer name; using this -method, buffers visiting the files @file{/u/rms/tmp/Makefile} and -@file{/usr/projects/zaphod/Makefile} would be named -@samp{tmp/Makefile} and @samp{zaphod/Makefile}, respectively (instead -of @samp{Makefile} and @samp{Makefile<2>}). - - In contrast, the @code{post-forward} naming method would call the -buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}, and the -@code{reverse} naming method would call them @samp{Makefile\tmp} and -@samp{Makefile\zaphod}. The nontrivial difference between -@code{post-forward} and @code{reverse} occurs when just one directory -name is not enough to distinguish two files; then @code{reverse} puts -the directory names in reverse order, so that @file{/top/middle/file} -becomes @samp{file\middle\top}, while @code{post-forward} puts them in -forward order after the file name, as in @samp{file|top/middle}. - - Which rule to follow for putting the directory names in the buffer -name is not very important if you are going to @emph{look} at the -buffer names before you type one. But as an experienced user, if you -know the rule, you won't have to look. And then you may find that one -rule or another is easier for you to remember and apply quickly. - -@node Iswitchb -@subsection Switching Between Buffers using Substrings - -@findex iswitchb-mode -@cindex Iswitchb mode -@cindex mode, Iswitchb -@kindex C-x b @r{(Iswitchb mode)} -@kindex C-x 4 b @r{(Iswitchb mode)} -@kindex C-x 5 b @r{(Iswitchb mode)} -@kindex C-x 4 C-o @r{(Iswitchb mode)} - - Iswitchb global minor mode provides convenient switching between -buffers using substrings of their names. It replaces the normal -definitions of @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b}, and @kbd{C-x -4 C-o} with alternative commands that are somewhat ``smarter''. - - When one of these commands prompts you for a buffer name, you can -type in just a substring of the name you want to choose. As you enter -the substring, Iswitchb mode continuously displays a list of buffers -that match the substring you have typed. - - At any time, you can type @key{RET} to select the first buffer in -the list. So the way to select a particular buffer is to make it the -first in the list. There are two ways to do this. You can type more -of the buffer name and thus narrow down the list, excluding unwanted -buffers above the desired one. Alternatively, you can use @kbd{C-s} -and @kbd{C-r} to rotate the list until the desired buffer is first. - - @key{TAB} while entering the buffer name performs completion on the -string you have entered, based on the displayed list of buffers. - - To enable Iswitchb mode, type @kbd{M-x iswitchb-mode}, or customize -the variable @code{iswitchb-mode} to @code{t} (@pxref{Easy -Customization}). - -@node Buffer Menus -@subsection Customizing Buffer Menus - -@findex bs-show -@cindex buffer list, customizable -@table @kbd -@item M-x bs-show -Make a list of buffers similarly to @kbd{M-x list-buffers} but -customizable. -@end table - - @kbd{M-x bs-show} pops up a buffer list similar to the one normally -displayed by @kbd{C-x C-b} but which you can customize. If you prefer -this to the usual buffer list, you can bind this command to @kbd{C-x -C-b}. To customize this buffer list, use the @code{bs} Custom group -(@pxref{Easy Customization}). - -@findex msb-mode -@cindex mode, MSB -@cindex MSB mode -@cindex buffer menu -@findex mouse-buffer-menu -@kindex C-Down-Mouse-1 - MSB global minor mode (``MSB'' stands for ``mouse select buffer'') -provides a different and customizable mouse buffer menu which you may -prefer. It replaces the bindings of @code{mouse-buffer-menu}, -normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You -can customize the menu in the @code{msb} Custom group. diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi deleted file mode 100644 index 999afa7df2c..00000000000 --- a/doc/emacs/building.texi +++ /dev/null @@ -1,1590 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Building, Maintaining, Programs, Top -@chapter Compiling and Testing Programs -@cindex building programs -@cindex program building -@cindex running Lisp functions - - The previous chapter discusses the Emacs commands that are useful -for making changes in programs. This chapter deals with commands that -assist in the process of compiling and testing programs. - -@menu -* Compilation:: Compiling programs in languages other - than Lisp (C, Pascal, etc.). -* Compilation Mode:: The mode for visiting compiler errors. -* Compilation Shell:: Customizing your shell properly - for use in the compilation buffer. -* Grep Searching:: Searching with grep. -* Flymake:: Finding syntax errors on the fly. -* Debuggers:: Running symbolic debuggers for non-Lisp programs. -* Executing Lisp:: Various modes for editing Lisp programs, - with different facilities for running - the Lisp programs. -* Libraries: Lisp Libraries. How Lisp programs are loaded into Emacs. -* Eval: Lisp Eval. Executing a single Lisp expression in Emacs. -* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. -* External Lisp:: Communicating through Emacs with a separate Lisp. -@end menu - -@node Compilation -@section Running Compilations under Emacs -@cindex inferior process -@cindex make -@cindex compilation errors -@cindex error log - - Emacs can run compilers for languages such as C and Fortran, feeding -the compilation log into an Emacs buffer. It can also parse the error -messages and show you where the errors occurred. - -@table @kbd -@item M-x compile -Run a compiler asynchronously under Emacs, with error messages going to -the @file{*compilation*} buffer. -@item M-x recompile -Invoke a compiler with the same command as in the last invocation of -@kbd{M-x compile}. -@item M-x kill-compilation -Kill the running compilation subprocess. -@end table - -@findex compile - To run @code{make} or another compilation command, type @kbd{M-x -compile}. This reads a shell command line using the minibuffer, and -then executes the command by running a shell as a subprocess (or -@dfn{inferior process}) of Emacs. The output is inserted in a buffer -named @file{*compilation*}. The current buffer's default directory is -used as the working directory for the execution of the command; -normally, therefore, compilation takes place in this directory. - -@vindex compile-command - The default compilation command is @samp{make -k}, which is usually -correct for programs compiled using the @command{make} utility (the -@samp{-k} flag tells @command{make} to continue compiling as much as -possible after an error). @xref{Top,, Make, make, GNU Make Manual}. -If you have done @kbd{M-x compile} before, the command that you -specified is automatically stored in the variable -@code{compile-command}; this is used as the default the next time you -type @kbd{M-x compile}. A file can also specify a file-local value -for @code{compile-command} (@pxref{File Variables}). - - Starting a compilation displays the @file{*compilation*} buffer in -another window but does not select it. While the compilation is -running, the word @samp{run} is shown in the major mode indicator for -the @file{*compilation*} buffer, and the word @samp{Compiling} appears -in all mode lines. You do not have to keep the @file{*compilation*} -buffer visible while compilation is running; it continues in any case. -When the compilation ends, for whatever reason, the mode line of the -@file{*compilation*} buffer changes to say @samp{exit} (followed by -the exit code: @samp{[0]} for a normal exit), or @samp{signal} (if a -signal terminated the process). - - If you want to watch the compilation transcript as it appears, -switch to the @file{*compilation*} buffer and move point to the end of -the buffer. When point is at the end, new compilation output is -inserted above point, which remains at the end. Otherwise, point -remains fixed while compilation output is added at the end of the -buffer. - -@cindex compilation buffer, keeping point at end -@vindex compilation-scroll-output - If you change the variable @code{compilation-scroll-output} to a -non-@code{nil} value, the @file{*compilation*} buffer scrolls -automatically to follow the output. If the value is -@code{first-error}, scrolling stops when the first error appears, -leaving point at that error. For any other non-@code{nil} value, -scrolling continues until there is no more output. - -@findex recompile - To rerun the last compilation with the same command, type @kbd{M-x -recompile}. This reuses the compilation command from the last -invocation of @kbd{M-x compile}. It also reuses the -@file{*compilation*} buffer and starts the compilation in its default -directory, which is the directory in which the previous compilation -was started. - -@findex kill-compilation - Starting a new compilation also kills any compilation already -running in @file{*compilation*}, as the buffer can only handle one -compilation at any time. However, @kbd{M-x compile} asks for -confirmation before actually killing a compilation that is running. -You can also kill the compilation process with @kbd{M-x -kill-compilation}. - - To run two compilations at once, start the first one, then rename -the @file{*compilation*} buffer (perhaps using @code{rename-uniquely}; -@pxref{Misc Buffer}), then switch buffers and start the other -compilation. This will create a new @file{*compilation*} buffer. - -@vindex compilation-environment - You can control the environment passed to the compilation command -with the variable @code{compilation-environment}. Its value is a list -of environment variable settings; each element should be a string of -the form @code{"@var{envvarname}=@var{value}"}. These environment -variable settings override the usual ones. - -@node Compilation Mode -@section Compilation Mode - -@cindex Compilation mode -@cindex mode, Compilation -@cindex locus - The @file{*compilation*} buffer uses a major mode called Compilation -mode. Compilation mode turns each error message in the buffer into a -hyperlink; you can move point to it and type @key{RET}, or click on it -with the mouse (@pxref{Mouse References}), to visit the @dfn{locus} of -the error message in a separate window. The locus is the specific -position in a file where that error occurred. - -@findex compile-goto-error -@vindex compilation-auto-jump-to-first-error - If you change the variable -@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value, -Emacs automatically visits the locus of the first error message that -appears in the @file{*compilation*} buffer. - - Compilation mode provides the following additional commands. These -commands can also be used in @file{*grep*} buffers, where the -hyperlinks are search matches rather than error messages (@pxref{Grep -Searching}). - -@table @kbd -@item M-g M-n -@itemx M-g n -@itemx C-x ` -Visit the locus of the next error message or match (@code{next-error}). -@item M-g M-p -@itemx M-g p -Visit the locus of the previous error message or match -(@code{previous-error}). -@item M-n -Move point to the next error message or match, without visiting its -locus (@code{compilation-next-error}). -@item M-p -Move point to the previous error message or match, without visiting -its locus (@code{compilation-previous-error}). -@item M-@} -Move point to the next error message or match occurring in a different -file (@code{compilation-next-file}). -@item M-@{ -Move point to the previous error message or match occurring in a -different file (@code{compilation-previous-file}). -@item C-c C-f -Toggle Next Error Follow minor mode, which makes cursor motion in the -compilation buffer produce automatic source display. -@end table - -@kindex M-g M-n -@kindex M-g n -@kindex C-x ` -@findex next-error -@vindex next-error-highlight - To visit errors sequentially, type @w{@kbd{C-x `}} -(@code{next-error}), or equivalently @kbd{M-g M-n} or @kbd{M-g n}. -This command can be invoked from any buffer, not just a Compilation -mode buffer. The first time you invoke it after a compilation, it -visits the locus of the first error message. Each subsequent -@w{@kbd{C-x `}} visits the next error, in a similar fashion. If you -visit a specific error with @key{RET} or a mouse click in the -@file{*compilation*} buffer, subsequent @w{@kbd{C-x `}} commands -advance from there. When @w{@kbd{C-x `}} finds no more error messages -to visit, it signals an error. @w{@kbd{C-u C-x `}} starts again from -the beginning of the compilation buffer, and visits the first locus. - - @kbd{M-g M-p} or @kbd{M-g p} (@code{previous-error}) iterates -through errors in the opposite direction. - - The @code{next-error} and @code{previous-error} commands don't just -act on the errors or matches listed in @file{*compilation*} and -@file{*grep*} buffers; they also know how to iterate through error or -match lists produced by other commands, such as @kbd{M-x occur} -(@pxref{Other Repeating Search}). If you are already in a buffer -containing error messages or matches, those are the ones that are -iterated through; otherwise, Emacs looks for a buffer containing error -messages or matches amongst the windows of the selected frame, then -for one that @code{next-error} or @code{previous-error} previously -iterated through, and finally amongst all other buffers. If the -buffer chosen for iterating through is not currently displayed in a -window, it will be displayed. - -@vindex compilation-skip-threshold - By default, the @code{next-error} and @code{previous-error} commands -skip less important messages. The variable -@code{compilation-skip-threshold} controls this. The default value, -1, means to skip anything less important than a warning. A value of 2 -means to skip anything less important than an error, while 0 means not -to skip any messages. - - When Emacs visits the locus of an error message, it momentarily -highlights the relevant source line. The duration of this highlight -is determined by the variable @code{next-error-highlight}. - -@vindex compilation-context-lines - If the @file{*compilation*} buffer is shown in a window with a left -fringe (@pxref{Fringes}), the locus-visiting commands put an arrow in -the fringe, pointing to the current error message. If the window has -no left fringe, such as on a text terminal, these commands scroll the -window so that the current message is at the top of the window. If -you change the variable @code{compilation-context-lines} to an integer -value @var{n}, these commands scroll the window so that the current -error message is @var{n} lines from the top, whether or not there is a -fringe; the default value, @code{nil}, gives the behavior described -above. - -@vindex compilation-error-regexp-alist -@vindex grep-regexp-alist - To parse messages from the compiler, Compilation mode uses the -variable @code{compilation-error-regexp-alist} which lists various -error message formats and tells Emacs how to extract the locus from -each. A similar variable, @code{grep-regexp-alist}, tells Emacs how -to parse output from a @code{grep} command (@pxref{Grep Searching}). - -@findex compilation-next-error -@findex compilation-previous-error -@findex compilation-next-file -@findex compilation-previous-file - Compilation mode also defines the keys @key{SPC} and @key{DEL} to -scroll by screenfuls; @kbd{M-n} (@code{compilation-next-error}) and -@kbd{M-p} (@code{compilation-previous-error}) to move to the next or -previous error message; and @kbd{M-@{} (@code{compilation-next-file}) -and @kbd{M-@}} (@code{compilation-previous-file}) to move to the next -or previous error message for a different source file. - -@cindex Next Error Follow mode -@findex next-error-follow-minor-mode - You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In -this minor mode, ordinary cursor motion in the compilation buffer -automatically updates the source buffer, i.e.@: moving the cursor over -an error message causes the locus of that error to be displayed. - - The features of Compilation mode are also available in a minor mode -called Compilation Minor mode. This lets you parse error messages in -any buffer, not just a normal compilation output buffer. Type -@kbd{M-x compilation-minor-mode} to enable the minor mode. For -instance, in an Rlogin buffer (@pxref{Remote Host}), Compilation minor -mode automatically accesses remote source files by FTP (@pxref{File -Names}). - -@node Compilation Shell -@section Subshells for Compilation - - The @kbd{M-x compile} command uses a shell to run the compilation -command, but specifies the option for a noninteractive shell. This -means, in particular, that the shell should start with no prompt. If -you find your usual shell prompt making an unsightly appearance in the -@file{*compilation*} buffer, it means you have made a mistake in your -shell's init file by setting the prompt unconditionally. (This init -file may be named @file{.bashrc}, @file{.profile}, @file{.cshrc}, -@file{.shrc}, etc., depending on what shell you use.) The shell init -file should set the prompt only if there already is a prompt. Here's -how to do it in bash: - -@example -if [ "$@{PS1+set@}" = set ] -then PS1=@dots{} -fi -@end example - -@noindent -And here's how to do it in csh: - -@example -if ($?prompt) set prompt = @dots{} -@end example - - Emacs does not expect a compiler process to launch asynchronous -subprocesses; if it does, and they keep running after the main -compiler process has terminated, Emacs may kill them or their output -may not arrive in Emacs. To avoid this problem, make the main -compilation process wait for its subprocesses to finish. In a shell -script, you can do this using @samp{$!} and @samp{wait}, like this: - -@example -(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess} -echo first message -wait $pid # @r{Wait for subprocess} -@end example - -@noindent -If the background process does not output to the compilation buffer, -so you only need to prevent it from being killed when the main -compilation process terminates, this is sufficient: - -@example -nohup @var{command}; sleep 1 -@end example - -@ifnottex - On the MS-DOS ``operating system'', asynchronous subprocesses are -not supported, so @kbd{M-x compile} runs the compilation command -synchronously (i.e.@: you must wait until the command finishes before -you can do anything else in Emacs). @xref{MS-DOS}. -@end ifnottex - -@node Grep Searching -@section Searching with Grep under Emacs - - Just as you can run a compiler from Emacs and then visit the lines -with compilation errors, you can also run @command{grep} and then -visit the lines on which matches were found. This works by treating -the matches reported by @command{grep} as if they were ``errors''. -The output buffer uses Grep mode, which is a variant of Compilation -mode (@pxref{Compilation Mode}). - -@table @kbd -@item M-x grep -@itemx M-x lgrep -Run @command{grep} asynchronously under Emacs, listing matching lines in -the buffer named @file{*grep*}. -@item M-x grep-find -@itemx M-x find-grep -@itemx M-x rgrep -Run @command{grep} via @code{find}, and collect output in the -@file{*grep*} buffer. -@item M-x zrgrep -Run @code{zgrep} and collect output in the @file{*grep*} buffer. -@item M-x kill-grep -Kill the running @command{grep} subprocess. -@end table - -@findex grep - To run @command{grep}, type @kbd{M-x grep}, then enter a command line -that specifies how to run @command{grep}. Use the same arguments you -would give @command{grep} when running it normally: a @command{grep}-style -regexp (usually in single-quotes to quote the shell's special -characters) followed by file names, which may use wildcards. If you -specify a prefix argument for @kbd{M-x grep}, it finds the tag -(@pxref{Tags}) in the buffer around point, and puts that into the -default @command{grep} command. - - Your command need not simply run @command{grep}; you can use any shell -command that produces output in the same format. For instance, you -can chain @command{grep} commands, like this: - -@example -grep -nH -e foo *.el | grep bar | grep toto -@end example - - The output from @command{grep} goes in the @file{*grep*} buffer. You -can find the corresponding lines in the original files using @w{@kbd{C-x -`}}, @key{RET}, and so forth, just like compilation errors. - - Some grep programs accept a @samp{--color} option to output special -markers around matches for the purpose of highlighting. You can make -use of this feature by setting @code{grep-highlight-matches} to -@code{t}. When displaying a match in the source buffer, the exact -match will be highlighted, instead of the entire source line. - -@findex grep-find -@findex find-grep - The command @kbd{M-x grep-find} (also available as @kbd{M-x -find-grep}) is similar to @kbd{M-x grep}, but it supplies a different -initial default for the command---one that runs both @code{find} and -@command{grep}, so as to search every file in a directory tree. See also -the @code{find-grep-dired} command, in @ref{Dired and Find}. - -@findex lgrep -@findex rgrep -@findex zrgrep - The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep} -(recursive grep) are more user-friendly versions of @command{grep} and -@code{grep-find}, which prompt separately for the regular expression -to match, the files to search, and the base directory for the search. -Case sensitivity of the search is controlled by the current value of -@code{case-fold-search}. The command @kbd{M-x zrgrep} is similar to -@kbd{M-x rgrep}, but it calls @command{zgrep} instead of -@command{grep} to search the contents of gzipped files. - - These commands build the shell commands based on the variables -@code{grep-template} (for @code{lgrep}) and @code{grep-find-template} -(for @code{rgrep}). The files to search can use aliases defined in -the variable @code{grep-files-aliases}. - -@vindex grep-find-ignored-directories - Directories listed in the variable -@code{grep-find-ignored-directories} are automatically skipped by -@kbd{M-x rgrep}. The default value includes the data directories used -by various version control systems. - -@node Flymake -@section Finding Syntax Errors On The Fly -@cindex checking syntax - - Flymake mode is a minor mode that performs on-the-fly syntax -checking for many programming and markup languages, including C, C++, -Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell -mode, which performs spell checking for ordinary human languages in a -similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode -runs an appropriate syntax checking tool in the background, using a -temporary copy of the buffer. It then parses the error and warning -messages, and highlights the erroneous lines in the buffer. The -syntax checking tool used depends on the language; for example, for -C/C++ files this is usually the C compiler. Flymake can also use -build tools such as @code{make} for checking complicated projects. - - To enable Flymake mode, type @kbd{M-x flymake-mode}. You can jump to -the errors that it finds by using @kbd{M-x -flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. -Use the command @kbd{M-x flymake-display-err-menu-for-current-line} -to display any error messages associated with the current line. - - For more details about using Flymake, -@ifnottex -see @ref{Top, Flymake, Flymake, flymake, The Flymake Manual}. -@end ifnottex -@iftex -see the Flymake Info manual, which is distributed with Emacs. -@end iftex - -@node Debuggers -@section Running Debuggers Under Emacs -@cindex debuggers -@cindex GUD library -@cindex GDB -@cindex DBX -@cindex SDB -@cindex XDB -@cindex Perldb -@cindex JDB -@cindex PDB - -The GUD (Grand Unified Debugger) library provides an Emacs interface -to a wide variety of symbolic debuggers. It can run the GNU Debugger -(GDB), as well as DBX, SDB, XDB, Perl's debugging mode, the Python -debugger PDB, and the Java Debugger JDB. - - Emacs provides a special interface to GDB, which uses extra Emacs -windows to display the state of the debugged program. @xref{GDB -Graphical Interface}. - - Emacs also has a built-in debugger for Emacs Lisp programs. -@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference -Manual}. - -@menu -* Starting GUD:: How to start a debugger subprocess. -* Debugger Operation:: Connection between the debugger and source buffers. -* Commands of GUD:: Key bindings for common commands. -* GUD Customization:: Defining your own commands for GUD. -* GDB Graphical Interface:: An enhanced mode that uses GDB features to - implement a graphical debugging environment. -@end menu - -@node Starting GUD -@subsection Starting GUD - - There are several commands for starting a debugger subprocess, each -corresponding to a particular debugger program. - -@table @kbd -@item M-x gdb -@findex gdb -Run GDB as a subprocess, and interact with it via an IDE-like Emacs -interface. @xref{GDB Graphical Interface}, for more information about -this command. - -@item M-x gud-gdb -@findex gud-gdb -Run GDB, using a GUD interaction buffer for input and output to the -GDB subprocess (@pxref{Debugger Operation}). If such a buffer already -exists, switch to it; otherwise, create the buffer and switch to it. - -The other commands in this list do the same, for other debugger -programs. - -@item M-x perldb -@findex perldb -Run the Perl interpreter in debug mode. - -@item M-x jdb -@findex jdb -Run the Java debugger. - -@item M-x pdb -@findex pdb -Run the Python debugger. - -@item M-x dbx -@findex dbx -Run the DBX debugger. - -@item M-x xdb -@findex xdb -@vindex gud-xdb-directories -Run the XDB debugger. - -@item M-x sdb -@findex sdb -Run the SDB debugger. -@end table - - Each of these commands reads a command line to invoke the debugger, -using the minibuffer. The minibuffer's initial contents contain the -standard executable name and options for the debugger, and sometimes -also a guess for the name of the executable file you want to debug. -Shell wildcards and variables are not allowed in this command line. -Emacs assumes that the first command argument which does not start -with a @samp{-} is the executable file name. - -@cindex remote host, debugging on - Tramp provides a facility for remote debugging, whereby both the -debugger and the program being debugged are on the same remote host. -@xref{Running a debugger on a remote host,,, tramp, The Tramp Manual}, -for details. This is separate from GDB's remote debugging feature, -where the program and the debugger run on different machines -(@pxref{Remote Debugging,, Debugging Remote Programs, gdb, The GNU -debugger}). - -@node Debugger Operation -@subsection Debugger Operation -@cindex GUD interaction buffer - - The @dfn{GUD interaction buffer} is an Emacs buffer which is used to -send text commands to a debugger subprocess, and record its output. -This is the basic interface for interacting with a debugger, used by -@kbd{M-x gud-gdb} and other commands listed in -@iftex -the preceding section. -@end iftex -@ifnottex -@ref{Starting GUD}. -@end ifnottex -The @kbd{M-x gdb} command extends this interface with additional -specialized buffers for controlling breakpoints, stack frames, and -other aspects of the debugger state (@pxref{GDB Graphical Interface}). - - The GUD interaction buffer uses a variant of Shell mode, so the -Emacs commands defined by Shell mode are available (@pxref{Shell -Mode}). Completion is available for most debugger commands -(@pxref{Completion}), and you can use the usual Shell mode history -commands to repeat them. -@iftex -See the next section -@end iftex -@ifnottex -@xref{Commands of GUD}, -@end ifnottex -for special commands that can be used in the GUD interaction buffer. - - As you debug a program, Emacs displays the relevant source files by -visiting them in Emacs buffers, with an arrow in the left fringe -indicating the current execution line. (On a text terminal, the arrow -appears as @samp{=>}, overlaid on the first two text columns.) Moving -point in such a buffer does not move the arrow. You are free to edit -these source files, but note that inserting or deleting lines will -throw off the arrow's positioning, as Emacs has no way to figure out -which edited source line corresponds to the line reported by the -debugger subprocess. To update this information, you typically have -to recompile and restart the program. - -@cindex GUD Tooltip mode -@cindex mode, GUD Tooltip -@findex gud-tooltip-mode -@vindex gud-tooltip-echo-area - GUD Tooltip mode is a global minor mode that adds tooltip support to -GUD. To toggle this mode, type @kbd{M-x gud-tooltip-mode}. It is -disabled by default. If enabled, you can move the mouse cursor over a -variable to show its value in a tooltip (@pxref{Tooltips}); this takes -effect in the GUD interaction buffer, and in all source buffers with -major modes listed in the variable @code{gud-tooltip-modes}. If the -variable @code{gud-tooltip-echo-area} is non-@code{nil}, values are -shown in the echo area instead of a tooltip. - - When using GUD Tooltip mode with @kbd{M-x gud-gdb}, you should note -that displaying an expression's value in GDB can sometimes expand a -macro, potentially causing side effects in the debugged program. If -you use the @kbd{M-x gdb} interface, this problem does not occur, as -there is special code to avoid side-effects; furthermore, you can -display macro definitions associated with an identifier when the -program is not executing. - -@node Commands of GUD -@subsection Commands of GUD - - GUD provides commands for setting and clearing breakpoints, -selecting stack frames, and stepping through the program. - -@table @kbd -@item C-x @key{SPC} -@kindex C-x SPC -Set a breakpoint on the source line that point is on. -@end table - - @kbd{C-x @key{SPC}} (@code{gud-break}), when called in a source -buffer, sets a debugger breakpoint on the current source line. This -command is available only after starting GUD. If you call it in a -buffer that is not associated with any debugger subprocess, it signals -a error. - -@kindex C-x C-a @r{(GUD)} - The following commands are available both in the GUD interaction -buffer and globally, but with different key bindings. The keys -starting with @kbd{C-c} are available only in the GUD interaction -buffer, while those starting with @kbd{C-x C-a} are available -globally. Some of these commands are also available via the tool bar; -some are not supported by certain debuggers. - -@table @kbd -@item C-c C-l -@kindex C-c C-l @r{(GUD)} -@itemx C-x C-a C-l -@findex gud-refresh -Display, in another window, the last source line referred to in the -GUD interaction buffer (@code{gud-refresh}). - -@item C-c C-s -@kindex C-c C-s @r{(GUD)} -@itemx C-x C-a C-s -@findex gud-step -Execute the next single line of code (@code{gud-step}). If the line -contains a function call, execution stops after entering the called -function. - -@item C-c C-n -@kindex C-c C-n @r{(GUD)} -@itemx C-x C-a C-n -@findex gud-next -Execute the next single line of code, stepping across function calls -without stopping inside the functions (@code{gud-next}). - -@item C-c C-i -@kindex C-c C-i @r{(GUD)} -@itemx C-x C-a C-i -@findex gud-stepi -Execute a single machine instruction (@code{gud-stepi}). - -@item C-c C-p -@kindex C-c C-p @r{(GUD)} -@itemx C-x C-a C-p -@findex gud-print -Evaluate the expression at point (@code{gud-print}). If Emacs -does not print the exact expression that you want, mark it as a region -first. - -@need 3000 -@item C-c C-r -@kindex C-c C-r @r{(GUD)} -@itemx C-x C-a C-r -@findex gud-cont -Continue execution without specifying any stopping point. The program -will run until it hits a breakpoint, terminates, or gets a signal that -the debugger is checking for (@code{gud-cont}). - -@need 1000 -@item C-c C-d -@kindex C-c C-d @r{(GUD)} -@itemx C-x C-a C-d -@findex gud-remove -Delete the breakpoint(s) on the current source line, if any -(@code{gud-remove}). If you use this command in the GUD interaction -buffer, it applies to the line where the program last stopped. - -@item C-c C-t -@kindex C-c C-t @r{(GUD)} -@itemx C-x C-a C-t -@findex gud-tbreak -Set a temporary breakpoint on the current source line, if any -(@code{gud-tbreak}). If you use this command in the GUD interaction -buffer, it applies to the line where the program last stopped. - -@item C-c < -@kindex C-c < @r{(GUD)} -@itemx C-x C-a < -@findex gud-up -Select the next enclosing stack frame (@code{gud-up}). This is -equivalent to the GDB command @samp{up}. - -@item C-c > -@kindex C-c > @r{(GUD)} -@itemx C-x C-a > -@findex gud-down -Select the next inner stack frame (@code{gud-down}). This is -equivalent to the GDB command @samp{down}. - -@item C-c C-u -@kindex C-c C-u @r{(GUD)} -@itemx C-x C-a C-u -@findex gud-until -Continue execution to the current line (@code{gud-until}). The -program will run until it hits a breakpoint, terminates, gets a signal -that the debugger is checking for, or reaches the line on which the -cursor currently sits. - -@item C-c C-f -@kindex C-c C-f @r{(GUD)} -@itemx C-x C-a C-f -@findex gud-finish -Run the program until the selected stack frame returns or -stops for some other reason (@code{gud-finish}). -@end table - - If you are using GDB, these additional key bindings are available: - -@table @kbd -@item C-x C-a C-j -@kindex C-x C-a C-j @r{(GUD)} -@findex gud-jump -Only useful in a source buffer, @code{gud-jump} transfers the -program's execution point to the current line. In other words, the -next line that the program executes will be the one where you gave the -command. If the new execution line is in a different function from -the previously one, GDB prompts for confirmation since the results may -be bizarre. See the GDB manual entry regarding @code{jump} for -details. - -@item @key{TAB} -@kindex TAB @r{(GUD)} -@findex gud-gdb-complete-command -With GDB, complete a symbol name (@code{gud-gdb-complete-command}). -This key is available only in the GUD interaction buffer. -@end table - - These commands interpret a numeric argument as a repeat count, when -that makes sense. - - Because @key{TAB} serves as a completion command, you can't use it to -enter a tab as input to the program you are debugging with GDB. -Instead, type @kbd{C-q @key{TAB}} to enter a tab. - -@node GUD Customization -@subsection GUD Customization - -@vindex gdb-mode-hook -@vindex dbx-mode-hook -@vindex sdb-mode-hook -@vindex xdb-mode-hook -@vindex perldb-mode-hook -@vindex pdb-mode-hook -@vindex jdb-mode-hook - On startup, GUD runs one of the following hooks: -@code{gdb-mode-hook}, if you are using GDB; @code{dbx-mode-hook}, if -you are using DBX; @code{sdb-mode-hook}, if you are using SDB; -@code{xdb-mode-hook}, if you are using XDB; @code{perldb-mode-hook}, -for Perl debugging mode; @code{pdb-mode-hook}, for PDB; -@code{jdb-mode-hook}, for JDB. @xref{Hooks}. - - The @code{gud-def} Lisp macro (@pxref{Defining Macros,,, elisp, the -Emacs Lisp Reference Manual}) provides a convenient way to define an -Emacs command that sends a particular command string to the debugger, -and set up a key binding for in the GUD interaction buffer: - -@findex gud-def -@example -(gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring}) -@end example - - This defines a command named @var{function} which sends -@var{cmdstring} to the debugger process, and gives it the documentation -string @var{docstring}. You can then use the command @var{function} in any -buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds -the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to -@kbd{C-x C-a @var{binding}} generally. - - The command string @var{cmdstring} may contain certain -@samp{%}-sequences that stand for data to be filled in at the time -@var{function} is called: - -@table @samp -@item %f -The name of the current source file. If the current buffer is the GUD -buffer, then the ``current source file'' is the file that the program -stopped in. - -@item %l -The number of the current source line. If the current buffer is the GUD -buffer, then the ``current source line'' is the line that the program -stopped in. - -@item %e -In transient-mark-mode the text in the region, if it is active. -Otherwise the text of the C lvalue or function-call expression at or -adjacent to point. - -@item %a -The text of the hexadecimal address at or adjacent to point. - -@item %p -The numeric argument of the called function, as a decimal number. If -the command is used without a numeric argument, @samp{%p} stands for the -empty string. - -If you don't use @samp{%p} in the command string, the command you define -ignores any numeric argument. - -@item %d -The name of the directory of the current source file. - -@item %c -Fully qualified class name derived from the expression surrounding point -(jdb only). -@end table - -@node GDB Graphical Interface -@subsection GDB Graphical Interface - - The command @kbd{M-x gdb} starts GDB in an IDE-like interface, with -specialized buffers for controlling breakpoints, stack frames, and -other aspects of the debugger state. It also provides additional ways -to control the debugging session with the mouse, such as clicking in -the fringe of a source buffer to set a breakpoint there. - -@vindex gud-gdb-command-name - To run GDB using just the GUD interaction buffer interface, without -these additional features, use @kbd{M-x gud-gdb} (@pxref{Starting -GUD}). You must use this if you want to debug multiple programs -within one Emacs session, as that is currently unsupported by @kbd{M-x -gdb}. - - Internally, @kbd{M-x gdb} informs GDB that its ``screen size'' is -unlimited; for correct operation, you must not change GDB's screen -height and width values during the debugging session. - -@menu -* GDB User Interface Layout:: Control the number of displayed buffers. -* Source Buffers:: Use the mouse in the fringe/margin to - control your program. -* Breakpoints Buffer:: A breakpoint control panel. -* Threads Buffer:: Displays your threads. -* Stack Buffer:: Select a frame from the call stack. -* Other GDB Buffers:: Other buffers for controlling the GDB state. -* Watch Expressions:: Monitor variable values in the speedbar. -* Multithreaded Debugging:: Debugging programs with several threads. -@end menu - -@node GDB User Interface Layout -@subsubsection GDB User Interface Layout -@cindex GDB User Interface layout - -@vindex gdb-many-windows - If the variable @code{gdb-many-windows} is @code{nil} (the default), -@kbd{M-x gdb} normally displays only the GUD interaction buffer. -However, if the variable @code{gdb-show-main} is also non-@code{nil}, -it starts with two windows: one displaying the GUD interaction buffer, -and the other showing the source for the @code{main} function of the -program you are debugging. - - If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb} -displays the following frame layout: - -@smallexample -@group -+--------------------------------+--------------------------------+ -| GUD interaction buffer | Locals/Registers buffer | -|--------------------------------+--------------------------------+ -| Primary Source buffer | I/O buffer for debugged pgm | -|--------------------------------+--------------------------------+ -| Stack buffer | Breakpoints/Threads buffer | -+--------------------------------+--------------------------------+ -@end group -@end smallexample - - However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O -buffer does not appear and the primary source buffer occupies the full -width of the frame. - -@findex gdb-restore-windows -@findex gdb-many-windows - If you ever change the window layout, you can restore the ``many -windows'' layout by typing @kbd{M-x gdb-restore-windows}. To toggle -between the many windows layout and a simple layout with just the GUD -interaction buffer and a source file, type @kbd{M-x gdb-many-windows}. - - You may also specify additional GDB-related buffers to display, -either in the same frame or a different one. Select the buffers you -want by typing @code{M-x gdb-display-@var{buffertype}-buffer} or -@code{M-x gdb-frame-@var{buffertype}-buffer}, where @var{buffertype} -is the relevant buffer type, such as @samp{breakpoints}. You can do -the same with the menu bar, with the @samp{GDB-Windows} and -@samp{GDB-Frames} sub-menus of the @samp{GUD} menu. - - When you finish debugging, kill the GUD interaction buffer with -@kbd{C-x k}, which will also kill all the buffers associated with the -session. However you need not do this if, after editing and -re-compiling your source code within Emacs, you wish to continue -debugging. When you restart execution, GDB automatically finds the -new executable. Keeping the GUD interaction buffer has the advantage -of keeping the shell history as well as GDB's breakpoints. You do -need to check that the breakpoints in recently edited source files are -still in the right places. - -@node Source Buffers -@subsubsection Source Buffers -@cindex fringes, for debugging - -@table @asis -@item @kbd{Mouse-1} (in fringe) -Set or clear a breakpoint on that line. - -@item @kbd{C-Mouse-1} (in fringe) -Enable or disable a breakpoint on that line. - -@item @kbd{Mouse-3} (in fringe) -Continue execution to that line. - -@item @kbd{C-Mouse-3} (in fringe) -Jump to that line. -@end table - - On a graphical display, you can click @kbd{Mouse-1} in the fringe of -a source buffer, to set a breakpoint on that line (@pxref{Fringes}). -A red dot appears in the fringe, where you clicked. If a breakpoint -already exists there, the click removes it. A @kbd{C-Mouse-1} click -enables or disables an existing breakpoint; a breakpoint that is -disabled, but not unset, is indicated by a gray dot. - - On a text terminal, or when fringes are disabled, enabled -breakpoints are indicated with a @samp{B} character in the left margin -of the window. Disabled breakpoints are indicated with @samp{b}. -(The margin is only displayed if a breakpoint is present.) - - A solid arrow in the left fringe of a source buffer indicates the -line of the innermost frame where the debugged program has stopped. A -hollow arrow indicates the current execution line of a higher-level -frame. If you drag the arrow in the fringe with @kbd{Mouse-1}, that -causes execution to advance to the line where you release the button. -Alternatively, you can click @kbd{Mouse-3} in the fringe to advance to -that line. You can click @kbd{C-Mouse-3} in the fringe to jump to -that line without executing the intermediate lines. This command -allows you to go backwards, which can be useful for running through -code that has already executed, in order to examine its execution in -more detail. - -@node Breakpoints Buffer -@subsubsection Breakpoints Buffer - - The GDB Breakpoints buffer shows the breakpoints, watchpoints and -catchpoints in the debugger session. @xref{Breakpoints,,, gdb, The -GNU debugger}. It provides the following commands, which mostly apply -to the @dfn{current breakpoint} (the breakpoint which point is on): - -@table @kbd -@item @key{SPC} -@kindex SPC @r{(GDB Breakpoints buffer)} -@findex gdb-toggle-breakpoint -Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}). On -a graphical display, this changes the color of the dot in the fringe -of the source buffer at that line. The dot is red when the breakpoint -is enabled, and gray when it is disabled. - -@item D -@kindex D @r{(GDB Breakpoints buffer)} -@findex gdb-delete-breakpoint -Delete the current breakpoint (@code{gdb-delete-breakpoint}). - -@item @key{RET} -@kindex RET @r{(GDB Breakpoints buffer)} -@findex gdb-goto-breakpoint -Visit the source line for the current breakpoint -(@code{gdb-goto-breakpoint}). - -@item Mouse-2 -@kindex Mouse-2 @r{(GDB Breakpoints buffer)} -Visit the source line for the breakpoint you click on. -@end table - -@vindex gdb-show-threads-by-default - When @code{gdb-many-windows} is non-@code{nil}, the GDB Breakpoints -buffer shares its window with the GDB Threads buffer. To switch from -one to the other click with @kbd{Mouse-1} on the relevant button in -the header line. If @code{gdb-show-threads-by-default} is -non-@code{nil}, the GDB Threads buffer is the one shown by default. - -@node Threads Buffer -@subsubsection Threads Buffer - -@findex gdb-select-thread - The GDB Threads buffer displays a summary of the threads in the -debugged program. @xref{Threads, Threads, Debugging programs with -multiple threads, gdb, The GNU debugger}. To select a thread, move -point there and type @key{RET} (@code{gdb-select-thread}), or click on -it with @kbd{Mouse-2}. This also displays the associated source -buffer, and updates the contents of the other GDB buffers. - - You can customize variables under @code{gdb-buffers} group to select -fields included in GDB Threads buffer. - -@table @code -@item gdb-thread-buffer-verbose-names -@vindex gdb-thread-buffer-verbose-names -Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)}. - -@item gdb-thread-buffer-arguments -@vindex gdb-thread-buffer-arguments -Show arguments of thread top frames. - -@item gdb-thread-buffer-locations -@vindex gdb-thread-buffer-locations -Show file information or library names. - -@item gdb-thread-buffer-addresses -@vindex gdb-thread-buffer-addresses -Show addresses for thread frames in threads buffer. -@end table - - To view information for several threads simultaneously, use the -following commands from the GDB Threads buffer. - -@table @kbd -@item d -@kindex d @r{(GDB threads buffer)} -@findex gdb-display-disassembly-for-thread -Display disassembly buffer for the thread at current line -(@code{gdb-display-disassembly-for-thread}). - -@item f -@kindex f @r{(GDB threads buffer)} -@findex gdb-display-stack-for-thread -Display the GDB Stack buffer for the thread at current line -(@code{gdb-display-stack-for-thread}). - -@item l -@kindex l @r{(GDB threads buffer)} -@findex gdb-display-locals-for-thread -Display the GDB Locals buffer for the thread at current line -(@code{gdb-display-locals-for-thread}). - -@item r -@kindex r @r{(GDB threads buffer)} -@findex gdb-display-registers-for-thread -Display the GDB Registers buffer for the thread at current line -(@code{gdb-display-registers-for-thread}). -@end table - -@noindent -Their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and @kbd{R}, -display the corresponding buffer in a new frame. - - When you create a buffer showing information about some specific -thread, it becomes bound to that thread and keeps showing actual -information while you debug your program. The mode indicator for each -GDB buffer shows the number of thread it is showing information about. -The thread number is also included in the buffer name of bound -buffers. - - Further commands are available in the GDB Threads buffer which -depend on the mode of GDB that is used for controlling execution of -your program. @xref{Multithreaded Debugging}. - -@node Stack Buffer -@subsubsection Stack Buffer - - The GDB Stack buffer displays a @dfn{call stack}, with one line for -each of the nested subroutine calls (@dfn{stack frames}) in the -debugger session. @xref{Backtrace,, Backtraces, gdb, The GNU -debugger}. - -@findex gdb-frames-select - On graphical displays, the selected stack frame is indicated by an -arrow in the fringe. On text terminals, or when fringes are disabled, -the selected stack frame is displayed in reverse contrast. To select -a stack frame, move point in its line and type @key{RET} -(@code{gdb-frames-select}), or click @kbd{Mouse-2} on it. Doing so -also updates the Locals buffer -@ifnottex -(@pxref{Other GDB Buffers}). -@end ifnottex -@iftex -(described in the next section). -@end iftex - -@node Other GDB Buffers -@subsubsection Other GDB Buffers - -@table @asis -@item Locals Buffer -This buffer displays the values of local variables of the current -frame for simple data types (@pxref{Frame Info, Frame Info, -Information on a frame, gdb, The GNU debugger}). Press @key{RET} or -click @kbd{Mouse-2} on the value if you want to edit it. - -Arrays and structures display their type only. With GDB 6.4 or later, -you can examine the value of the local variable at point by typing -@key{RET}, or with a @kbd{Mouse-2} click. With earlier versions of -GDB, use @key{RET} or @kbd{Mouse-2} on the type description -(@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}. - -@item Registers Buffer -@findex toggle-gdb-all-registers -This buffer displays the values held by the registers -(@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or -click @kbd{Mouse-2} on a register if you want to edit its value. With -GDB 6.4 or later, recently changed register values display with -@code{font-lock-warning-face}. - -@item Assembler Buffer -The assembler buffer displays the current frame as machine code. An -arrow points to the current instruction, and you can set and remove -breakpoints as in a source buffer. Breakpoint icons also appear in -the fringe or margin. - -@item Memory Buffer -The memory buffer lets you examine sections of program memory -(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}). -Click @kbd{Mouse-1} on the appropriate part of the header line to -change the starting address or number of data items that the buffer -displays. Alternatively, use @kbd{S} or @kbd{N} respectively. Click -@kbd{Mouse-3} on the header line to select the display format or unit -size for these data items. -@end table - -When @code{gdb-many-windows} is non-@code{nil}, the locals buffer -shares its window with the registers buffer, just like breakpoints and -threads buffers. To switch from one to the other, click with -@kbd{Mouse-1} on the relevant button in the header line. - -@node Watch Expressions -@subsubsection Watch Expressions -@cindex Watching expressions in GDB - -@findex gud-watch -@kindex C-x C-a C-w @r{(GUD)} - If you want to see how a variable changes each time your program -stops, move point into the variable name and click on the watch icon -in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you -specify a prefix argument, you can enter the variable name in the -minibuffer. - - Each watch expression is displayed in the speedbar -(@pxref{Speedbar}). Complex data types, such as arrays, structures -and unions are represented in a tree format. Leaves and simple data -types show the name of the expression and its value and, when the -speedbar frame is selected, display the type as a tooltip. Higher -levels show the name, type and address value for pointers and just the -name and type otherwise. Root expressions also display the frame -address as a tooltip to help identify the frame in which they were -defined. - - To expand or contract a complex data type, click @kbd{Mouse-2} or -press @key{SPC} on the tag to the left of the expression. Emacs asks -for confirmation before expanding the expression if its number of -immediate children exceeds the value of the variable -@code{gdb-max-children}. - -@kindex D @r{(GDB speedbar)} -@findex gdb-var-delete - To delete a complex watch expression, move point to the root -expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}). - -@kindex RET @r{(GDB speedbar)} -@findex gdb-edit-value - To edit a variable with a simple data type, or a simple element of a -complex data type, move point there in the speedbar and type @key{RET} -(@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to -edit it. Either way, this reads the new value using the minibuffer. - -@vindex gdb-show-changed-values - If you set the variable @code{gdb-show-changed-values} to -non-@code{nil} (the default value), Emacs uses -@code{font-lock-warning-face} to highlight values that have recently -changed and @code{shadow} face to make variables which have gone out of -scope less noticeable. When a variable goes out of scope you can't -edit its value. - -@vindex gdb-delete-out-of-scope - If the variable @code{gdb-delete-out-of-scope} is non-@code{nil} -(the default value), Emacs automatically deletes watch expressions -which go out of scope. Sometimes, when re-entering the same function, -it may be useful to set this value to @code{nil} so that you don't -need to recreate the watch expression. - -@vindex gdb-use-colon-colon-notation - If the variable @code{gdb-use-colon-colon-notation} is -non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}} -format. This allows the user to display watch expressions which share -the same variable name. The default value is @code{nil}. - -@vindex gdb-speedbar-auto-raise -To automatically raise the speedbar every time the display of watch -expressions updates, set @code{gdb-speedbar-auto-raise} to -non-@code{nil}. This can be useful if you are debugging with a full -screen Emacs frame. - -@node Multithreaded Debugging -@subsubsection Multithreaded Debugging -@cindex Multithreaded debugging in GDB -@cindex Non-stop debugging in GDB - - In GDB's @dfn{all-stop mode}, whenever your program stops, all -execution threads stop. Likewise, whenever you restart the program, -all threads start executing. @xref{All-Stop Mode, , All-Stop Mode, -gdb, The GNU debugger}. For some multi-threaded targets, GDB supports -a further mode of operation, called @dfn{non-stop mode}, in which you -can examine stopped program threads in the debugger while other -threads continue to execute freely. @xref{Non-Stop Mode, , Non-Stop -Mode, gdb, The GNU debugger}. Versions of GDB prior to 7.0 do not -support non-stop mode, and it does not work on all targets. - -@vindex gdb-non-stop-setting - The variable @code{gdb-non-stop-setting} determines whether Emacs -runs GDB in all-stop mode or non-stop mode. The default is @code{t}, -which means it tries to use non-stop mode if that is available. If -you change the value to @code{nil}, or if non-stop mode is -unavailable, Emacs runs GDB in all-stop mode. The variable takes -effect when Emacs begins a debugging session; if you change its value, -you should restart any active debugging session. - -@vindex gdb-switch-when-another-stopped - When a thread stops in non-stop mode, Emacs usually switches to that -thread. If you don't want Emacs to do this switch if another stopped -thread is already selected, change the variable -@code{gdb-switch-when-another-stopped} to @code{nil}. - -@vindex gdb-switch-reasons - Emacs can decide whether or not to switch to the stopped thread -depending on the reason which caused the stop. Customize the variable -@code{gdb-switch-reasons} to select the stop reasons which will cause -a thread switch. - -@vindex gdb-stopped-hooks - The variable @code{gdb-stopped-hooks} allows you to execute your -functions whenever some thread stops. - - In non-stop mode, you can switch between different modes for GUD -execution control commands. - -@vindex gdb-gud-control-all-threads -@table @dfn -@item Non-stop/A - - When @code{gdb-gud-control-all-threads} is @code{t} (the default -value), interruption and continuation commands apply to all threads, -so you can halt or continue all your threads with one command using -@code{gud-stop-subjob} and @code{gud-cont}, respectively. The -@samp{Go} button is shown on the toolbar when at least one thread is -stopped, whereas @samp{Stop} button is shown when at least one thread -is running. - -@item Non-stop/T - -When @code{gdb-gud-control-all-threads} is @code{nil}, only the -current thread is stopped/continued. @samp{Go} and @samp{Stop} -buttons on the GUD toolbar are shown depending on the state of current -thread. -@end table - -You can change the current value of @code{gdb-gud-control-all-threads} -from the tool bar or from @samp{GUD->GDB-MI} menu. - - Stepping commands always apply to the current thread. - - In non-stop mode, you can interrupt/continue your threads without -selecting them. Hitting @kbd{i} in threads buffer interrupts thread -under point, @kbd{c} continues it, @kbd{s} steps through. More such -commands may be added in the future. - - Note that when you interrupt a thread, it stops with the -@samp{signal received} reason. If that reason is included in your -@code{gdb-switch-reasons} (it is by default), Emacs will switch to -that thread. - -@node Executing Lisp -@section Executing Lisp Expressions - - Emacs has major modes for several variants of Lisp. They use the -same editing commands as other programming language modes -(@pxref{Programs}). In addition, they provide special commands for -executing Lisp expressions. - -@table @asis -@item Emacs Lisp mode -The mode for editing Emacs Lisp source files. It defines @kbd{C-M-x} -to evaluate the current top-level Lisp expression. @xref{Lisp Eval}. - -@item Lisp Interaction mode -The mode for an interactive Emacs Lisp session. It defines @kbd{C-j} -to evaluate the expression before point and insert its value in the -buffer. @xref{Lisp Interaction}. - -@item Lisp mode -The mode for editing source files of programs that run in Lisps other -than Emacs Lisp. It defines @kbd{C-M-x} to evaluate the current -top-level expression in an external Lisp. @xref{External Lisp}. - -@item Inferior Lisp mode -The mode for an interactive session with an external Lisp which is -being run as a subprocess (or @dfn{inferior process}) of Emacs. -@ifnottex -@xref{External Lisp}. -@end ifnottex - -@item Scheme mode -Like Lisp mode, but for Scheme programs. - -@item Inferior Scheme mode -Like Inferior Lisp mode, but for Scheme. -@end table - -@node Lisp Libraries -@section Libraries of Lisp Code for Emacs -@cindex libraries -@cindex loading Lisp code - - Emacs Lisp code is stored in files whose names conventionally end in -@file{.el}. Such files are automatically visited in Emacs Lisp mode. - -@cindex byte code - Emacs Lisp code can be compiled into byte-code, which loads faster, -takes up less space, and executes faster. By convention, compiled -Emacs Lisp code goes in a separate file whose name ends in -@samp{.elc}. For example, the compiled code for @file{foo.el} goes in -@file{foo.elc}. @xref{Byte Compilation,, Byte Compilation, elisp, the -Emacs Lisp Reference Manual}. - -@findex load-file - To @dfn{load} an Emacs Lisp file, type @kbd{M-x load-file}. This -command reads a file name using the minibuffer, and executes the -contents of that file as Emacs Lisp code. It is not necessary to -visit the file first; this command reads the file directly from disk, -not from an existing Emacs buffer. - -@findex load -@findex load-library -@cindex load path for Emacs Lisp - If an Emacs Lisp file is installed in the Emacs Lisp @dfn{load path} -(defined below), you can load it by typing @kbd{M-x load-library}, -instead of using @kbd{M-x load-file}. The @kbd{M-x load-library} -command prompts for a @dfn{library name} rather than a file name; it -searches through each directory in the Emacs Lisp load path, trying to -find a file matching that library name. If the library name is -@samp{@var{foo}}, it tries looking for files named -@file{@var{foo}.elc}, @file{@var{foo}.el}, and lastly just -@file{@var{foo}}; the first one found is loaded. This command prefers -@file{.elc} files over @file{.el} files because compiled files load -and run faster. If it finds that @file{@var{lib}.el} is newer than -@file{@var{lib}.elc}, it issues a warning, in case someone made -changes to the @file{.el} file and forgot to recompile it, but loads -the @file{.elc} file anyway. (Due to this behavior, you can save -unfinished edits to Emacs Lisp source files, and not recompile until -your changes are ready for use.) - - Emacs Lisp programs usually load Emacs Lisp files using the -@code{load} function. This is similar to @code{load-library}, but is -lower-level and accepts additional arguments. @xref{How Programs Do -Loading,,, elisp, the Emacs Lisp Reference Manual}. - -@vindex load-path - The Emacs Lisp load path is specified by the variable -@code{load-path}. Its value should be a list of directory names -(strings). These directories are searched, in the specified order, by -the @kbd{M-x load-library} command, the lower-level @code{load} -function, and other Emacs functions that find Emacs Lisp libraries. A -list entry in @code{load-path} can also have the special value -@code{nil}, which stands for the current default directory, but it is -almost always a bad idea to use this. (If you find yourself wishing -that @code{nil} were in the list, most likely what you really want is -to use @kbd{M-x load-file}.) - - The default value of @code{load-path} is a list of directories where -the Lisp code for Emacs itself is stored. If you have libraries of -your own in another directory, you can add that directory to the load -path. Unlike most other variables described in this manual, -@code{load-path} cannot be changed via the Customize interface -(@pxref{Easy Customization}), but you can add a directory to it by -putting a line like this in your init file (@pxref{Init File}): - -@example -(add-to-list 'load-path "/path/to/my/lisp/library") -@end example - -@cindex autoload - Some commands are @dfn{autoloaded}: when you run them, Emacs -automatically loads the associated library first. For instance, the -@kbd{M-x compile} command (@pxref{Compilation}) is autoloaded; if you -call it, Emacs automatically loads the @code{compile} library first. -In contrast, the command @kbd{M-x recompile} is not autoloaded, so it -is unavailable until you load the @code{compile} library. - -@vindex load-dangerous-libraries -@cindex Lisp files byte-compiled by XEmacs - By default, Emacs refuses to load compiled Lisp files which were -compiled with XEmacs, a modified versions of Emacs---they can cause -Emacs to crash. Set the variable @code{load-dangerous-libraries} to -@code{t} if you want to try loading them. - -@node Lisp Eval -@section Evaluating Emacs Lisp Expressions -@cindex Emacs Lisp mode -@cindex mode, Emacs Lisp - -@findex emacs-lisp-mode - Emacs Lisp mode is the major mode for editing Emacs Lisp. Its mode -command is @kbd{M-x emacs-lisp-mode}. - - Emacs provides several commands for evaluating Emacs Lisp -expressions. You can use these commands in Emacs Lisp mode, to test -your Emacs Lisp code as it is being written. For example, after -re-writing a function, you can evaluate the function definition to -make it take effect for subsequent function calls. These commands are -also available globally, and can be used outside Emacs Lisp mode. - -@table @asis -@item @kbd{M-:} -Read a single Emacs Lisp expression in the minibuffer, evaluate it, -and print the value in the echo area (@code{eval-expression}). -@item @kbd{C-x C-e} -Evaluate the Emacs Lisp expression before point, and print the value -in the echo area (@code{eval-last-sexp}). -@item @kbd{C-M-x} @r{(in Emacs Lisp mode)} -@itemx @kbd{M-x eval-defun} -Evaluate the defun containing or after point, and print the value in -the echo area (@code{eval-defun}). -@item @kbd{M-x eval-region} -Evaluate all the Emacs Lisp expressions in the region. -@item @kbd{M-x eval-buffer} -Evaluate all the Emacs Lisp expressions in the buffer. -@end table - -@ifinfo -@c This uses ``colon'' instead of a literal `:' because Info cannot -@c cope with a `:' in a menu -@kindex M-@key{colon} -@end ifinfo -@ifnotinfo -@kindex M-: -@end ifnotinfo -@findex eval-expression - @kbd{M-:} (@code{eval-expression}) reads an expression using the -minibuffer, and evaluates it. (Before evaluating the expression, the -current buffer switches back to the buffer that was current when you -typed @kbd{M-:}, not the minibuffer into which you typed the -expression.) - -@kindex C-x C-e -@findex eval-last-sexp - The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the -Emacs Lisp expression preceding point in the buffer, and displays the -value in the echo area. When the result of an evaluation is an -integer, you can type @kbd{C-x C-e} a second time to display the value -of the integer result in additional formats (octal, hexadecimal, and -character). - - If @kbd{M-:} or @kbd{C-x C-e} is given a prefix argument, it inserts -the value into the current buffer at point, rather than displaying it -in the echo area. The argument's value does not matter. - -@kindex C-M-x @r{(Emacs Lisp mode)} -@findex eval-defun - The @code{eval-defun} command is bound to @kbd{C-M-x} in Emacs Lisp -mode. It evaluates the top-level Lisp expression containing or -following point, and prints the value in the echo area. In this -context, a top-level expression is referred to as a ``defun'', but it -need not be an actual @code{defun} (function definition). In -particular, this command treats @code{defvar} expressions specially. -Normally, evaluating a @code{defvar} expression does nothing if the -variable it defines already has a value. But this command -unconditionally resets the variable to the initial value specified by -the @code{defvar}; this is convenient for debugging Emacs Lisp -programs. @code{defcustom} and @code{defface} expressions are treated -similarly. Note that the other commands documented in this section do -not have this special feature. - - With a prefix argument, @kbd{C-M-x} instruments the function -definition for Edebug, the Emacs Lisp Debugger. @xref{Instrumenting, -Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}. - -@findex eval-region -@findex eval-buffer - The command @kbd{M-x eval-region} parses the text of the region as -one or more Lisp expressions, evaluating them one by one. @kbd{M-x -eval-buffer} is similar but evaluates the entire buffer. - -@vindex eval-expression-print-level -@vindex eval-expression-print-length -@vindex eval-expression-debug-on-error - The customizable variables @code{eval-expression-print-level} and -@code{eval-expression-print-length} control the maximum depth and -length of lists to print in the result of the evaluation commands -before abbreviating them. @code{eval-expression-debug-on-error} -controls whether evaluation errors invoke the debugger when these -commands are used; its default is @code{t}. - -@node Lisp Interaction -@section Lisp Interaction Buffers - -@findex lisp-interaction-mode - When Emacs starts up, it contains a buffer named @file{*scratch*}, -which is provided for evaluating Emacs Lisp expressions interactively. -Its major mode is Lisp Interaction mode. You can also enable Lisp -Interaction mode by typing @kbd{M-x lisp-interaction-mode}. - -@findex eval-print-last-sexp -@kindex C-j @r{(Lisp Interaction mode)} - In the @file{*scratch*} buffer, and other Lisp Interaction mode -buffers, @kbd{C-j} (@code{eval-print-last-sexp}) evaluates the Lisp -expression before point, and inserts the value at point. Thus, as you -type expressions into the buffer followed by @kbd{C-j} after each -expression, the buffer records a transcript of the evaluated -expressions and their values. All other commands in Lisp Interaction -mode are the same as in Emacs Lisp mode. - -@vindex initial-scratch-message - At startup, the @file{*scratch*} buffer contains a short message, in -the form of a Lisp comment, that explains what it is for. This -message is controlled by the variable @code{initial-scratch-message}, -which should be either a string, or @code{nil} (which means to -suppress the message). - -@findex ielm - An alternative way of evaluating Emacs Lisp expressions -interactively is to use Inferior Emacs Lisp mode, which provides an -interface rather like Shell mode (@pxref{Shell Mode}) for evaluating -Emacs Lisp expressions. Type @kbd{M-x ielm} to create an -@file{*ielm*} buffer which uses this mode. For more information, see -that command's documentation. - -@node External Lisp -@section Running an External Lisp -@cindex Lisp mode -@cindex mode, Lisp -@cindex Common Lisp - - Lisp mode is the major mode for editing programs written in -general-purpose Lisp dialects, such as Common Lisp. Its mode command -is @kbd{M-x lisp-mode}. Emacs uses Lisp mode automatically for files -whose names end in @file{.l}, @file{.lsp}, or @file{.lisp}. - -@findex run-lisp -@vindex inferior-lisp-program -@kindex C-x C-z - You can run an external Lisp session as a subprocess or -@dfn{inferior process} of Emacs, and pass expressions to it to be -evaluated. To begin an external Lisp session, type @kbd{M-x -run-lisp}. This runs the program named @command{lisp}, and sets it up -so that both input and output go through an Emacs buffer named -@file{*inferior-lisp*}. To change the name of the Lisp program run by -@kbd{M-x run-lisp}, change the variable @code{inferior-lisp-program}. - - The major mode for the @file{*lisp*} buffer is Inferior Lisp mode, -which combines the characteristics of Lisp mode and Shell mode -(@pxref{Shell Mode}). To send input to the Lisp session, go to the -end of the @file{*lisp*} buffer and type the input, followed by -@key{RET}. Terminal output from the Lisp session is automatically -inserted in the buffer. - -@kindex C-M-x @r{(Lisp mode)} -@findex lisp-eval-defun - When you edit a Lisp program in Lisp mode, you can type @kbd{C-M-x} -(@code{lisp-eval-defun}) to send an expression from the Lisp mode -buffer to a Lisp session that you had started with @kbd{M-x run-lisp}. -The expression sent is the top-level Lisp expression at or following -point. The resulting value goes as usual into the -@file{*inferior-lisp*} buffer. Note that the effect of @kbd{C-M-x} in -Lisp mode is thus very similar to its effect in Emacs Lisp mode -(@pxref{Lisp Eval}), except that the expression is sent to a different -Lisp environment instead of being evaluated in Emacs. - -@findex scheme-mode -@findex run-scheme -@cindex Scheme mode -@cindex mode, Scheme -@kindex C-M-x @r{(Scheme mode)} - The facilities for editing Scheme code, and for sending expressions -to a Scheme subprocess, are very similar. Scheme source files are -edited in Scheme mode, which can be explicitly enabled with @kbd{M-x -scheme-mode}. You can initiate a Scheme session by typing @kbd{M-x -run-scheme} (the buffer for interacting with Scheme is named -@file{*scheme*}), and send expressions to it by typing @kbd{C-M-x}. diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi deleted file mode 100644 index 45760afd7a6..00000000000 --- a/doc/emacs/cal-xtra.texi +++ /dev/null @@ -1,918 +0,0 @@ -@c This is part of the Emacs manual. -*- coding: iso-latin-1 -*- -@c Copyright (C) 2004-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). - -@c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. -@node Advanced Calendar/Diary Usage -@section Customizing the Calendar and Diary - - There are many ways in which you can customize the calendar and -diary to suit your personal tastes. - -@menu -* Calendar Customizing:: Calendar layout and hooks. -* Holiday Customizing:: Defining your own holidays. -* Date Display Format:: Changing the format. -* Time Display Format:: Changing the format. -* Diary Customizing:: Defaults you can set. -* Non-Gregorian Diary:: Diary entries based on other calendars. -* Diary Display:: A choice of ways to display the diary. -* Fancy Diary Display:: Sorting diary entries, using included diary files. -* Sexp Diary Entries:: More flexible diary entries. -@end menu - -@node Calendar Customizing -@subsection Customizing the Calendar - -@vindex calendar-intermonth-text -@cindex calendar layout -@cindex calendar week numbers - The calendar display unfortunately cannot be changed from three -months, but you can customize the whitespace used by setting the -variables: @code{calendar-left-margin}, -@code{calendar-day-header-width}, @code{calendar-day-digit-width}, -@code{calendar-column-width}, and @code{calendar-intermonth-spacing}. -To display text @emph{between} the months, for example week numbers, -customize the variables @code{calendar-intermonth-header} and -@code{calendar-intermonth-text} as described in their documentation. - -@vindex calendar-holiday-marker -@vindex diary-entry-marker -@vindex calendar-today-marker - The variable @code{calendar-holiday-marker} specifies how to mark a -date that is a holiday. Its value may be a single-character string to -insert next to the date, or a face name to use for displaying the date. -Likewise, the variable @code{diary-entry-marker} specifies how to mark a -date that has diary entries. The function @code{calendar-mark-today} -uses @code{calendar-today-marker} to mark today's date. By default, -the calendar uses faces named @code{holiday}, @code{diary}, and -@code{calendar-today} for these purposes. - -@vindex calendar-load-hook - The variable @code{calendar-load-hook} is a normal hook run when the -calendar package is first loaded (before actually starting to display -the calendar). - -@vindex calendar-initial-window-hook - Starting the calendar runs the normal hook -@code{calendar-initial-window-hook}. Recomputation of the calendar -display does not run this hook. But if you leave the calendar with the -@kbd{q} command and reenter it, the hook runs again.@refill - -@vindex calendar-today-visible-hook -@findex calendar-star-date - The variable @code{calendar-today-visible-hook} is a normal hook run -after the calendar buffer has been prepared with the calendar, when the -current date is visible in the window. One use of this hook is to -mark today's date; to do that use either of the functions -@code{calendar-mark-today} or @code{calendar-star-date}: - -@findex calendar-mark-today -@smallexample -(add-hook 'calendar-today-visible-hook 'calendar-mark-today) -@end smallexample - -@vindex calendar-today-invisible-hook -@noindent - A similar normal hook, @code{calendar-today-invisible-hook} is run if -the current date is @emph{not} visible in the window. - -@vindex calendar-move-hook - Each of the calendar cursor motion commands runs the hook -@code{calendar-move-hook} after it moves the cursor. - -@node Holiday Customizing -@subsection Customizing the Holidays - -@vindex calendar-holidays -@vindex holiday-oriental-holidays -@vindex holiday-solar-holidays - There are several variables listing the default holidays that Emacs -knows about. These are: @code{holiday-general-holidays}, -@code{holiday-local-holidays}, @code{holiday-solar-holidays}, -@code{holiday-bahai-holidays}, @code{holiday-christian-holidays}, -@code{holiday-hebrew-holidays}, @code{holiday-islamic-holidays}, -@code{holiday-oriental-holidays}, and @code{holiday-other-holidays}. -The names should be self-explanatory; e.g.@: @code{holiday-solar-holidays} -lists sun- and moon-related holidays. - -You can customize these lists of holidays to your own needs, deleting or -adding holidays as described below. Set any of them to @code{nil} to -not show the associated holidays. - -@vindex holiday-general-holidays -@vindex holiday-local-holidays -@vindex holiday-other-holidays - The general holidays are, by default, holidays common throughout the -United States. In contrast, @code{holiday-local-holidays} and -@code{holiday-other-holidays} are both empty by default. These are -intended for system-wide settings and your individual use, -respectively. - -@vindex holiday-bahai-holidays -@vindex holiday-christian-holidays -@vindex holiday-hebrew-holidays -@vindex holiday-islamic-holidays -@vindex calendar-bahai-all-holidays-flag -@vindex calendar-christian-all-holidays-flag -@vindex calendar-hebrew-all-holidays-flag -@vindex calendar-islamic-all-holidays-flag - By default, Emacs does not include all the holidays of the religions -that it knows, only those commonly found in secular calendars. For a -more extensive collection of religious holidays, you can set any (or -all) of the variables @code{calendar-bahai-all-holidays-flag}, -@code{calendar-christian-all-holidays-flag}, -@code{calendar-hebrew-all-holidays-flag}, or -@code{calendar-islamic-all-holidays-flag} to @code{t}. - -@cindex holiday forms - Each of the holiday variables is a list of @dfn{holiday forms}, each -form describing a holiday (or sometimes a list of holidays). Here is -a table of the possible kinds of holiday form. Day numbers and month -numbers count starting from 1, but ``dayname'' numbers count Sunday as -0. The argument @var{string} is always the description of the -holiday, as a string. - -@table @code -@item (holiday-fixed @var{month} @var{day} @var{string}) -A fixed date on the Gregorian calendar. - -@item (holiday-float @var{month} @var{dayname} @var{k} @var{string} - &optional @var{day}) -The @var{k}th @var{dayname} (@var{dayname}=0 for Sunday, and so on) -after or before Gregorian date @var{month}, @var{day}. Negative @var{k} -means count back from the end of the month. Optional @var{day} defaults -to 1 if @var{k} is positive, and the last day of @var{month} otherwise. - -@item (holiday-chinese @var{month} @var{day} @var{string}) -A fixed date on the Chinese calendar. - -@item (holiday-hebrew @var{month} @var{day} @var{string}) -A fixed date on the Hebrew calendar. - -@item (holiday-islamic @var{month} @var{day} @var{string}) -A fixed date on the Islamic calendar. - -@item (holiday-julian @var{month} @var{day} @var{string}) -A fixed date on the Julian calendar. - -@item (holiday-sexp @var{sexp} @var{string}) -A date calculated by the Lisp expression @var{sexp}. The expression -should use the variable @code{year} to compute and return the date of a -holiday in the form of a list @code{(@var{month} @var{day} @var{year})}, -or @code{nil} if the holiday doesn't happen this year. - -@item (if @var{condition} @var{holiday-form}) -A holiday that happens only if @var{condition} is true. - -@item (@var{function} @r{[}@var{args}@r{]}) -A list of dates calculated by the function @var{function}, called with -arguments @var{args}. -@end table - - For example, suppose you want to add Bastille Day, celebrated in -France on July 14 (i.e., the fourteenth day of the seventh month). You -can do this as follows: - -@smallexample -(setq holiday-other-holidays '((holiday-fixed 7 14 "Bastille Day"))) -@end smallexample - - Many holidays occur on a specific day of the week, at a specific time -of month. Here is a holiday form describing Hurricane Supplication Day, -celebrated in the Virgin Islands on the fourth Monday in August: - -@smallexample -(holiday-float 8 1 4 "Hurricane Supplication Day") -@end smallexample - -@noindent -Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, -Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in -the month (1 specifies the first occurrence, 2 the second occurrence, -@minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and -so on). - - You can specify holidays that occur on fixed days of the Bahá'í, -Chinese, Hebrew, Islamic, and Julian calendars too. For example, - -@smallexample -(setq holiday-other-holidays - '((holiday-hebrew 10 2 "Last day of Hanukkah") - (holiday-islamic 3 12 "Mohammed's Birthday") - (holiday-julian 4 2 "Jefferson's Birthday"))) -@end smallexample - -@noindent -adds the last day of Hanukkah (since the Hebrew months are numbered with -1 starting from Nisan), the Islamic feast celebrating Mohammed's -birthday (since the Islamic months are numbered from 1 starting with -Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the -Julian calendar. - - To include a holiday conditionally, use either Emacs Lisp's @code{if} -or the @code{holiday-sexp} form. For example, American presidential -elections occur on the first Tuesday after the first Monday in November -of years divisible by 4: - -@smallexample -(holiday-sexp '(if (zerop (% year 4)) - (calendar-gregorian-from-absolute - (1+ (calendar-dayname-on-or-before - 1 (+ 6 (calendar-absolute-from-gregorian - (list 11 1 year))))))) - "US Presidential Election") -@end smallexample - -@noindent -or - -@smallexample -(if (zerop (% displayed-year 4)) - (holiday-fixed 11 - (calendar-extract-day - (calendar-gregorian-from-absolute - (1+ (calendar-dayname-on-or-before - 1 (+ 6 (calendar-absolute-from-gregorian - (list 11 1 displayed-year))))))) - "US Presidential Election")) -@end smallexample - - Some holidays just don't fit into any of these forms because special -calculations are involved in their determination. In such cases you -must write a Lisp function to do the calculation. To include eclipses, -for example, add @code{(eclipses)} to @code{holiday-other-holidays} -and write an Emacs Lisp function @code{eclipses} that returns a -(possibly empty) list of the relevant Gregorian dates among the range -visible in the calendar window, with descriptive strings, like this: - -@smallexample -(((6 4 2012) "Lunar Eclipse") ((11 13 2012) "Solar Eclipse") ... ) -@end smallexample - -@node Date Display Format -@subsection Date Display Format -@vindex calendar-date-display-form - - You can customize the way dates are displayed in the diary, mode -lines, and messages by setting @code{calendar-date-display-form}. -This variable holds a list of expressions that can involve the variables -@code{month}, @code{day}, and @code{year}, which are all numbers in -string form, and @code{monthname} and @code{dayname}, which are both -alphabetic strings. In the American style, the default value of this -list is as follows: - -@smallexample -((if dayname (concat dayname ", ")) monthname " " day ", " year) -@end smallexample - -@noindent -while in the European style this value is the default: - -@smallexample -((if dayname (concat dayname ", ")) day " " monthname " " year) -@end smallexample - -@noindent -The default ISO date representation is: - -@smallexample -((format "%s-%.2d-%.2d" year (string-to-number month) - (string-to-number day))) -@end smallexample - -@noindent -Another typical American format is: - -@smallexample -(month "/" day "/" (substring year -2)) -@end smallexample - -@node Time Display Format -@subsection Time Display Format -@vindex calendar-time-display-form - - The calendar and diary by default display times of day in the -conventional American style with the hours from 1 through 12, minutes, -and either @samp{am} or @samp{pm}. If you prefer the European style, -also known in the US as military, in which the hours go from 00 to 23, -you can alter the variable @code{calendar-time-display-form}. This -variable is a list of expressions that can involve the variables -@code{12-hours}, @code{24-hours}, and @code{minutes}, which are all -numbers in string form, and @code{am-pm} and @code{time-zone}, which are -both alphabetic strings. The default value is: - -@smallexample -(12-hours ":" minutes am-pm - (if time-zone " (") time-zone (if time-zone ")")) -@end smallexample - -@noindent -Here is a value that provides European style times: - -@smallexample -(24-hours ":" minutes - (if time-zone " (") time-zone (if time-zone ")")) -@end smallexample - -Note that few calendar functions return a time of day (at present, only -solar functions). - -@node Diary Customizing -@subsection Customizing the Diary - -@vindex diary-show-holidays-flag - Ordinarily, the diary window indicates any holidays that fall on the -date of the diary entries, either in the mode line or the buffer itself. -The process of checking for holidays can be slow, depending on the -defined holidays. In that case, setting @code{diary-show-holidays-flag} -to @code{nil} will speed up the diary display. - -@vindex diary-number-of-entries - The variable @code{diary-number-of-entries} controls the number of -days of diary entries to be displayed at one time. It affects the -initial display when @code{calendar-view-diary-initially-flag} is -@code{t}, as well as the command @kbd{M-x diary}. For example, a value -of 1 (the default) displays only the current day's diary entries, -whereas a value of 2 will also show the next day's entries. The value -can also be a vector of seven integers: for example, if the value is -@code{[0 2 2 2 2 4 1]} then no diary entries appear on Sunday, the -current date's and the next day's diary entries appear Monday through -Thursday, Friday through Monday's entries appear on Friday, while on -Saturday only that day's entries appear. - -@vindex diary-date-forms - You can customize the form of dates in your diary file by setting the -variable @code{diary-date-forms}. This variable is a list of patterns -for recognizing a date. Each date pattern is a list whose elements may -be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs -Lisp Reference Manual}) or the symbols @code{month}, @code{day}, -@code{year}, @code{monthname}, and @code{dayname}. All these elements -serve as patterns that match certain kinds of text in the diary file. -In order for the date pattern as a whole to match, all of its elements -must match consecutively. - - A regular expression in a date pattern matches in its usual fashion, -using the standard syntax table altered so that @samp{*} is a word -constituent. - - The symbols @code{month}, @code{day}, @code{year}, @code{monthname}, -and @code{dayname} match the month number, day number, year number, -month name, and day name of the date being considered. The symbols that -match numbers allow leading zeros; those that match names allow -capitalization and abbreviation (as specified by -@code{calendar-month-abbrev-array} and -@code{calendar-day-abbrev-array}). All the symbols can match @samp{*}; -since @samp{*} in a diary entry means ``any day'', ``any month'', and so -on, it should match regardless of the date being considered. - - The default value of @code{diary-date-forms} in the American style is -provided by @code{diary-american-date-forms}: - -@example -((month "/" day "[^/0-9]") - (month "/" day "/" year "[^0-9]") - (monthname " *" day "[^,0-9]") - (monthname " *" day ", *" year "[^0-9]") - (dayname "\\W")) -@end example - -@noindent -The variables @code{diary-european-date-forms} and -@code{diary-iso-date-forms} provide other default styles. - - The date patterns in the list must be @emph{mutually exclusive} and -must not match any portion of the diary entry itself, just the date and -one character of whitespace. If, to be mutually exclusive, the pattern -must match a portion of the diary entry text---beyond the whitespace -that ends the date---then the first element of the date pattern -@emph{must} be @code{backup}. This causes the date recognizer to back -up to the beginning of the current word of the diary entry, after -finishing the match. Even if you use @code{backup}, the date pattern -must absolutely not match more than a portion of the first word of the -diary entry. For example, the default value of -@code{diary-european-date-forms} is: - -@example -((day "/" month "[^/0-9]") - (day "/" month "/" year "[^0-9]") - (backup day " *" monthname "\\W+\\<\\([^*0-9]\\|\\([0-9]+[:aApP]\\)\\)") - (day " *" monthname " *" year "[^0-9]") - (dayname "\\W")) -@end example - -@noindent -Notice the use of @code{backup} in the third pattern, because it needs -to match part of a word beyond the date itself to distinguish it from -the fourth pattern. - -@node Non-Gregorian Diary -@subsection Diary Entries Using non-Gregorian Calendars - - As well as entries based on the standard Gregorian calendar, your -diary can have entries based on Bahá'í, Hebrew, or Islamic dates. -Recognition of such entries can be time-consuming, however, and since -most people don't use them, you must explicitly enable their use. If -you want the diary to recognize Hebrew-date diary entries, for example, -you must do this: - -@vindex diary-nongregorian-listing-hook -@vindex diary-nongregorian-marking-hook -@findex diary-hebrew-list-entries -@findex diary-hebrew-mark-entries -@findex diary-islamic-list-entries -@findex diary-islamic-mark-entries -@findex diary-bahai-list-entries -@findex diary-bahai-mark-entries -@smallexample -(add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries) -(add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries) -@end smallexample - -@noindent -Similarly, for Islamic and Bahá'í entries, add -@code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, or -@code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}. - -@vindex diary-bahai-entry-symbol -@vindex diary-hebrew-entry-symbol -@vindex diary-islamic-entry-symbol - These diary entries have the same formats as Gregorian-date diary -entries; except that @code{diary-bahai-entry-symbol} (default @samp{B}) -must precede a Bahá'í date, @code{diary-hebrew-entry-symbol} (default -@samp{H}) a Hebrew date, and @code{diary-islamic-entry-symbol} (default -@samp{I}) an Islamic date. Moreover, non-Gregorian month names may not -be abbreviated (because the first three letters are often not unique). -(Note also that you must use ``Adar I'' if you want Adar of a common -Hebrew year.) For example, a diary entry for the Hebrew date Heshvan 25 -could look like this: - -@smallexample -HHeshvan 25 Happy Hebrew birthday! -@end smallexample - -@noindent -and would appear in the diary for any date that corresponds to Heshvan 25 -on the Hebrew calendar. And here is an Islamic-date diary entry that matches -Dhu al-Qada 25: - -@smallexample -IDhu al-Qada 25 Happy Islamic birthday! -@end smallexample - - As with Gregorian-date diary entries, non-Gregorian entries are -nonmarking if preceded by @code{diary-nonmarking-symbol} (default -@samp{&}). - - Here is a table of commands used in the calendar to create diary -entries that match the selected date and other dates that are similar in -the Bahá'í, Hebrew, or Islamic calendars: - -@table @kbd -@item i h d -@code{diary-hebrew-insert-entry} -@item i h m -@code{diary-hebrew-insert-monthly-entry} -@item i h y -@code{diary-hebrew-insert-yearly-entry} -@item i i d -@code{diary-islamic-insert-entry} -@item i i m -@code{diary-islamic-insert-monthly-entry} -@item i i y -@code{diary-islamic-insert-yearly-entry} -@item i B d -@code{diary-bahai-insert-entry} -@item i B m -@code{diary-bahai-insert-monthly-entry} -@item i B y -@code{diary-bahai-insert-yearly-entry} -@end table - -@findex diary-hebrew-insert-entry -@findex diary-hebrew-insert-monthly-entry -@findex diary-hebrew-insert-yearly-entry -@findex diary-islamic-insert-entry -@findex diary-islamic-insert-monthly-entry -@findex diary-islamic-insert-yearly-entry -@findex diary-bahai-insert-entry -@findex diary-bahai-insert-monthly-entry -@findex diary-bahai-insert-yearly-entry - These commands work much like the corresponding commands for ordinary -diary entries: they apply to the date that point is on in the calendar -window, and what they do is insert just the date portion of a diary -entry at the end of your diary file. You must then insert the rest of -the diary entry. The basic commands add an entry for the specific -non-Gregorian date, the @samp{monthly} commands for the given -non-Gregorian day-within-month in every month, and the @samp{yearly} -commands for the given non-Gregorian day and month in every year. - -@node Diary Display -@subsection Diary Display -@vindex diary-display-function -@findex diary-simple-display -@findex diary-fancy-display -@cindex diary buffer - - Diary display works by preparing the list of diary entries and then -running the function specified by the variable -@code{diary-display-function}. The default value -@code{diary-fancy-display} displays diary entries and holidays by -copying them into a special buffer that exists only for the sake of -display. Copying diary entries to a separate buffer provides an -opportunity to change the displayed text to make it prettier---for -example, to sort the entries by the dates they apply to. - -@vindex diary-list-include-blanks - Ordinarily, the fancy diary buffer does not show days for which there -are no diary entries, even if that day is a holiday. If you want such -days to be shown in the fancy diary buffer, set the variable -@code{diary-list-include-blanks} to @code{t}.@refill - - The fancy diary buffer enables View mode -@iftex -(@pxref{View Mode,,, emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{View Mode}). -@end ifnottex - - The alternative display method @code{diary-simple-display} shows the -actual diary buffer, and uses invisible text to hide entries that don't -apply. Holidays are shown in the mode line. The advantage of this -method is that you can edit the buffer and save your changes directly to -the diary file. This method is not as flexible as the fancy method, -however. For example, it cannot sort entries. Another disadvantage is -that invisible text can be confusing. For example, if you copy a region -of text in order to paste it elsewhere, invisible text may be included. -Similarly, since the diary buffer as you see it is an illusion, simply -printing the buffer may not print what you see on your screen. - -@vindex diary-print-entries-hook -@findex diary-print-entries - For this reason, there is a special command to print hard copy of the -diary buffer @emph{as it appears}; this command is @kbd{M-x -diary-print-entries}. It works with either display method, although -with the fancy display you can also print the buffer like any other. To -print a hard copy of a day-by-day diary for a week, position point on -the first day of the week, type @kbd{7 d}, and then do @kbd{M-x -diary-print-entries}. As usual, the inclusion of the holidays slows -down the display slightly; you can speed things up by setting the -variable @code{diary-show-holidays-flag} to @code{nil}. - - This command prepares a temporary buffer that contains only the diary -entries currently visible in the diary buffer. Unlike with the simple -display, the other irrelevant entries are really absent, not just -hidden. After preparing the buffer, it runs the hook -@code{diary-print-entries-hook}. The default value of this hook sends -the data directly to the printer with the command @code{lpr-buffer} -@iftex -(@pxref{Printing,,, emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Printing}). -@end ifnottex -If you want to use a different command to do the -printing, just change the value of this hook. Other uses might include, -for example, rearranging the lines into order by day and time. - - You can edit the diary entries as they appear in the simple diary -window, but it is important to remember that the buffer displayed -contains the @emph{entire} diary file, with portions of it concealed -from view. This means, for instance, that the @kbd{C-f} -(@code{forward-char}) command can put point at what appears to be the -end of the line, but what is in reality the middle of some concealed -line. - - @emph{Be careful when editing the diary entries in the simple display!} -Inserting additional lines or adding/deleting characters in the middle -of a visible line cannot cause problems, but editing at the end of a -line may not do what you expect. Deleting a line may delete other -invisible entries that follow it. Before editing the simple diary -buffer, it is best to display the entire file with @kbd{s} -(@code{diary-show-all-entries}). - -@node Fancy Diary Display -@subsection Fancy Diary Display - -The following features only work with the fancy diary display. - -@cindex sorting diary entries - You can use the normal hook @code{diary-list-entries-hook} to sort -each day's diary entries by their time of day. Here's how: - -@findex diary-sort-entries -@example -(add-hook 'diary-list-entries-hook 'diary-sort-entries t) -@end example - -@noindent -For each day, this sorts diary entries that begin with a recognizable -time of day according to their times. Diary entries without times come -first within each day. Note how the sort command is placed at the end -of the hook list, in case earlier members of the list change the order -of the diary entries, or add items. - -@vindex diary-comment-start - You can write @samp{comments} in diary entries, by setting the -variables @code{diary-comment-start} and @code{diary-comment-end} to -strings that delimit comments. The fancy display does not print -comments. You might want to put meta-data for the use of other packages -(e.g.@: the appointment package, -@iftex -@pxref{Appointments,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -@pxref{Appointments}) -@end ifnottex -inside comments. - -@vindex diary-include-string - Your main diary file can include other files. This permits a group of -people to share a diary file for events that apply to all of them. -Lines in the diary file starting with @code{diary-include-string}: - -@smallexample -#include "@var{filename}" -@end smallexample - -@noindent -include the diary entries from the file @var{filename} in the fancy -diary buffer. The include mechanism is recursive, so that included -files can include other files, and so on (you must be careful not to -have a cycle of inclusions, of course). Here is how to enable the -include facility: - -@vindex diary-list-entries-hook -@vindex diary-mark-entries-hook -@findex diary-include-other-diary-files -@findex diary-mark-included-diary-files -@smallexample -(add-hook 'diary-list-entries-hook 'diary-include-other-diary-files) -(add-hook 'diary-mark-entries-hook 'diary-mark-included-diary-files) -@end smallexample - -The include mechanism works only with the fancy diary display, because -simple diary display shows the entries directly from your diary file. - -@node Sexp Diary Entries -@subsection Sexp Entries and the Fancy Diary Display -@cindex sexp diary entries - -@vindex diary-sexp-entry-symbol - Sexp diary entries allow you to do more than just have complicated -conditions under which a diary entry applies. Sexp entries should be -preceded by @code{diary-sexp-entry-symbol} (default @samp{%%}) in the -diary file. With the fancy diary display, sexp entries can generate the -text of the entry depending on the date itself. - -For example, an anniversary diary entry can insert -the number of years since the anniversary date into the text of the -diary entry. Thus the @samp{%d} in this diary entry: - -@findex diary-anniversary -@smallexample -%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) -@end smallexample - -@noindent -gets replaced by the age, so on October 31, 1990 the entry appears in -the fancy diary buffer like this: - -@smallexample -Arthur's birthday (42 years old) -@end smallexample - -@noindent -If the diary file instead contains this entry: - -@smallexample -%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday -@end smallexample - -@noindent -the entry in the fancy diary buffer for October 31, 1990 appears like this: - -@smallexample -Arthur's 42nd birthday -@end smallexample - - Similarly, cyclic diary entries can interpolate the number of repetitions -that have occurred: - -@findex diary-cyclic -@smallexample -%%(diary-cyclic 50 1 1 2012) Renew medication (%d%s time) -@end smallexample - -@noindent -looks like this: - -@smallexample -Renew medication (5th time) -@end smallexample - -@noindent -in the fancy diary display on September 7, 2012. - - There is an ``early reminder'' diary sexp that includes its entry in the -diary not only on the date of occurrence, but also on earlier dates. -For example, if you want a reminder a week before your anniversary, you -can use - -@findex diary-remind -@smallexample -%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary -@end smallexample - -@noindent -and the fancy diary will show @samp{Ed's anniversary} both on December -15 and on December 22. - -@findex diary-date - The function @code{diary-date} applies to dates described by a month, -day, year combination, each of which can be an integer, a list of -integers, or @code{t} (meaning all values). For example, - -@smallexample -%%(diary-date '(10 11 12) 22 t) Rake leaves -@end smallexample - -@noindent -causes the fancy diary to show - -@smallexample -Rake leaves -@end smallexample - -@noindent -on October 22, November 22, and December 22 of every year. - -@findex diary-float - The function @code{diary-float} allows you to describe diary entries -that apply to dates like the third Friday of November, or the last -Tuesday in April. The parameters are the @var{month}, @var{dayname}, -and an index @var{n}. The entry appears on the @var{n}th @var{dayname} -after the first day of @var{month}, where @var{dayname}=0 means Sunday, -1 means Monday, and so on. If @var{n} is negative it counts backward -from the end of @var{month}. The value of @var{month} can be a list of -months, a single month, or @code{t} to specify all months. You can also -use an optional parameter @var{day} to specify the @var{n}th -@var{dayname} on or after/before @var{day} of @var{month}; the value of -@var{day} defaults to 1 if @var{n} is positive and to the last day of -@var{month} if @var{n} is negative. For example, - -@smallexample -%%(diary-float t 1 -1) Pay rent -@end smallexample - -@noindent -causes the fancy diary to show - -@smallexample -Pay rent -@end smallexample - -@noindent -on the last Monday of every month. - - The generality of sexp diary entries lets you specify any diary -entry that you can describe algorithmically. A sexp diary entry -contains an expression that computes whether the entry applies to any -given date. If its value is non-@code{nil}, the entry applies to that -date; otherwise, it does not. The expression can use the variable -@code{date} to find the date being considered; its value is a list -(@var{month} @var{day} @var{year}) that refers to the Gregorian -calendar. - - The sexp diary entry applies to a date when the expression's value -is non-@code{nil}, but some values have more specific meanings. If -the value is a string, that string is a description of the event which -occurs on that date. The value can also have the form -@code{(@var{mark} . @var{string})}; then @var{mark} specifies how to -mark the date in the calendar, and @var{string} is the description of -the event. If @var{mark} is a single-character string, that character -appears next to the date in the calendar. If @var{mark} is a face -name, the date is displayed in that face. If @var{mark} is -@code{nil}, that specifies no particular highlighting for the date. - - Suppose you get paid on the 21st of the month if it is a weekday, and -on the Friday before if the 21st is on a weekend. Here is how to write -a sexp diary entry that matches those dates: - -@smallexample -&%%(let ((dayname (calendar-day-of-week date)) - (day (cadr date))) - (or (and (= day 21) (memq dayname '(1 2 3 4 5))) - (and (memq day '(19 20)) (= dayname 5))) - ) Pay check deposited -@end smallexample - - The following sexp diary entries take advantage of the ability (in the fancy -diary display) to concoct diary entries whose text varies based on the date: - -@findex diary-sunrise-sunset -@findex diary-lunar-phases -@findex diary-day-of-year -@findex diary-iso-date -@findex diary-julian-date -@findex diary-astro-day-number -@findex diary-bahai-date -@findex diary-chinese-date -@findex diary-coptic-date -@findex diary-ethiopic-date -@findex diary-hebrew-date -@findex diary-islamic-date -@findex diary-french-date -@findex diary-mayan-date -@findex diary-persian-date -@table @code -@item %%(diary-sunrise-sunset) -Make a diary entry for today's local times of sunrise and sunset. -@item %%(diary-lunar-phases) -Make a diary entry for the phases (quarters) of the moon. -@item %%(diary-day-of-year) -Make a diary entry with today's day number in the current year and the number -of days remaining in the current year. -@item %%(diary-iso-date) -Make a diary entry with today's equivalent ISO commercial date. -@item %%(diary-julian-date) -Make a diary entry with today's equivalent Julian calendar date. -@item %%(diary-astro-day-number) -Make a diary entry with today's equivalent astronomical (Julian) day number. -@item %%(diary-bahai-date) -Make a diary entry with today's equivalent Bahá'í calendar date. -@item %%(diary-chinese-date) -Make a diary entry with today's equivalent Chinese calendar date. -@item %%(diary-coptic-date) -Make a diary entry with today's equivalent Coptic calendar date. -@item %%(diary-ethiopic-date) -Make a diary entry with today's equivalent Ethiopic calendar date. -@item %%(diary-french-date) -Make a diary entry with today's equivalent date on the French Revolutionary -calendar. -@item %%(diary-hebrew-date) -Make a diary entry with today's equivalent Hebrew calendar date. -@item %%(diary-islamic-date) -Make a diary entry with today's equivalent Islamic calendar date. -@item %%(diary-mayan-date) -Make a diary entry with today's equivalent Mayan calendar date. -@item %%(diary-persian-date) -Make a diary entry with today's equivalent Persian calendar date. -@end table - -@noindent -For example, including the diary entry - -@smallexample -&%%(diary-hebrew-date) -@end smallexample - -@noindent -causes every day's diary display to contain the equivalent date on the -Hebrew calendar, if you are using the fancy diary display. (With simple -diary display, the literal line @samp{&%%(diary-hebrew-date)} appears in -the diary for any date.) - - This function has been used to construct certain standard Hebrew sexp -diary entries: - -@cindex rosh hodesh -@findex diary-hebrew-rosh-hodesh -@cindex parasha, weekly -@findex diary-hebrew-parasha -@cindex candle lighting times -@findex diary-hebrew-sabbath-candles -@cindex omer count -@findex diary-hebrew-omer -@cindex yahrzeits -@findex diary-hebrew-yahrzeit -@findex diary-hebrew-birthday -@table @code -@item %%(diary-hebrew-rosh-hodesh) -Make a diary entry that tells the occurrence and ritual announcement of each -new Hebrew month. -@item %%(diary-hebrew-parasha) -Make a Saturday diary entry that tells the weekly synagogue scripture reading. -@item %%(diary-hebrew-sabbath-candles) -Make a Friday diary entry that tells the @emph{local time} of Sabbath -candle lighting. -@item %%(diary-hebrew-omer) -Make a diary entry that gives the omer count, when appropriate. -@item %%(diary-hebrew-yahrzeit @var{month} @var{day} @var{year}) @var{name} -Make a diary entry marking the anniversary of a date of death. The date -is the @emph{Gregorian} (civil) date of death. The diary entry appears -on the proper Hebrew calendar anniversary and on the day before. (The -order of the parameters changes according to the calendar date style; -for example in the European style to @var{day}, @var{month}, @var{year}.) -@item %%(diary-hebrew-birthday @var{month} @var{day} @var{year}) -Make a diary entry for a birthday on the Hebrew calendar. -@end table - - All the functions documented above take an optional argument -@var{mark} which specifies how to mark the date in the calendar display. -If one of these functions decides that it applies to a certain date, -it returns a value that contains @var{mark}, as described above. diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi deleted file mode 100644 index e55d40767f4..00000000000 --- a/doc/emacs/calendar.texi +++ /dev/null @@ -1,1714 +0,0 @@ -@c This is part of the Emacs manual. -*- coding: iso-latin-1 -*- -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Calendar/Diary -@chapter The Calendar and the Diary -@cindex calendar -@findex calendar - - Emacs provides the functions of a desk calendar, with a diary of -planned or past events. It also has facilities for managing your -appointments, and keeping track of how much time you spend working on -certain projects. - - To enter the calendar, type @kbd{M-x calendar}; this displays a -three-month calendar centered on the current month, with point on the -current date. With a numeric argument, as in @kbd{C-u M-x calendar}, it -prompts you for the month and year to be the center of the three-month -calendar. The calendar uses its own buffer, whose major mode is -Calendar mode. - - @kbd{Mouse-3} in the calendar brings up a menu of operations on a -particular date; @kbd{Mouse-2} brings up a menu of commonly used -calendar features that are independent of any particular date. To exit -the calendar, type @kbd{q}. - -@iftex - This chapter describes the basic calendar features. -For more advanced topics, -@pxref{Advanced Calendar/Diary Usage,,, emacs-xtra, Specialized Emacs Features}. -@end iftex - -@menu -* Calendar Motion:: Moving through the calendar; selecting a date. -* Scroll Calendar:: Bringing earlier or later months onto the screen. -* Counting Days:: How many days are there between two dates? -* General Calendar:: Exiting or recomputing the calendar. -* Writing Calendar Files:: Writing calendars to files of various formats. -* Holidays:: Displaying dates of holidays. -* Sunrise/Sunset:: Displaying local times of sunrise and sunset. -* Lunar Phases:: Displaying phases of the moon. -* Other Calendars:: Converting dates to other calendar systems. -* Diary:: Displaying events from your diary. -* Appointments:: Reminders when it's time to do something. -* Importing Diary:: Converting diary events to/from other formats. -* Daylight Saving:: How to specify when daylight saving time is active. -* Time Intervals:: Keeping track of time intervals. -@ifnottex -* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. -@end ifnottex -@end menu - -@node Calendar Motion -@section Movement in the Calendar - -@cindex moving inside the calendar - Calendar mode provides commands to move through the calendar in -logical units of time such as days, weeks, months, and years. If you -move outside the three months originally displayed, the calendar -display ``scrolls'' automatically through time to make the selected -date visible. Moving to a date lets you view its holidays or diary -entries, or convert it to other calendars; moving by long time periods -is also useful simply to scroll the calendar. - -@menu -* Calendar Unit Motion:: Moving by days, weeks, months, and years. -* Move to Beginning or End:: Moving to start/end of weeks, months, and years. -* Specified Dates:: Moving to the current date or another - specific date. -@end menu - -@node Calendar Unit Motion -@subsection Motion by Standard Lengths of Time - - The commands for movement in the calendar buffer parallel the -commands for movement in text. You can move forward and backward by -days, weeks, months, and years. - -@table @kbd -@item C-f -Move point one day forward (@code{calendar-forward-day}). -@item C-b -Move point one day backward (@code{calendar-backward-day}). -@item C-n -Move point one week forward (@code{calendar-forward-week}). -@item C-p -Move point one week backward (@code{calendar-backward-week}). -@item M-@} -Move point one month forward (@code{calendar-forward-month}). -@item M-@{ -Move point one month backward (@code{calendar-backward-month}). -@item C-x ] -Move point one year forward (@code{calendar-forward-year}). -@item C-x [ -Move point one year backward (@code{calendar-backward-year}). -@end table - -@kindex C-f @r{(Calendar mode)} -@findex calendar-forward-day -@kindex C-b @r{(Calendar mode)} -@findex calendar-backward-day -@kindex C-n @r{(Calendar mode)} -@findex calendar-forward-week -@kindex C-p @r{(Calendar mode)} -@findex calendar-backward-week - The day and week commands are natural analogues of the usual Emacs -commands for moving by characters and by lines. Just as @kbd{C-n} -usually moves to the same column in the following line, in Calendar -mode it moves to the same day in the following week. And @kbd{C-p} -moves to the same day in the previous week. - - The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and -@kbd{C-p}, just as they normally are in other modes. - -@kindex M-@} @r{(Calendar mode)} -@findex calendar-forward-month -@kindex M-@{ @r{(Calendar mode)} -@findex calendar-backward-month -@kindex C-x ] @r{(Calendar mode)} -@findex calendar-forward-year -@kindex C-x [ @r{(Calendar mode)} -@findex calendar-forward-year - The commands for motion by months and years work like those for -weeks, but move a larger distance. The month commands @kbd{M-@}} and -@kbd{M-@{} move forward or backward by an entire month. The year -commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a -whole year. - - The easiest way to remember these commands is to consider months and -years analogous to paragraphs and pages of text, respectively. But -the commands themselves are not quite analogous. The ordinary Emacs -paragraph commands move to the beginning or end of a paragraph, -whereas these month and year commands move by an entire month or an -entire year, keeping the same date within the month or year. - - All these commands accept a numeric argument as a repeat count. -For convenience, the digit keys and the minus sign specify numeric -arguments in Calendar mode even without the Meta modifier. For example, -@kbd{100 C-f} moves point 100 days forward from its present location. - -@node Move to Beginning or End -@subsection Beginning or End of Week, Month or Year - - A week (or month, or year) is not just a quantity of days; we think of -weeks (months, years) as starting on particular dates. So Calendar mode -provides commands to move to the start or end of a week, month or year: - -@table @kbd -@kindex C-a @r{(Calendar mode)} -@findex calendar-beginning-of-week -@item C-a -Move point to start of week (@code{calendar-beginning-of-week}). -@kindex C-e @r{(Calendar mode)} -@findex calendar-end-of-week -@item C-e -Move point to end of week (@code{calendar-end-of-week}). -@kindex M-a @r{(Calendar mode)} -@findex calendar-beginning-of-month -@item M-a -Move point to start of month (@code{calendar-beginning-of-month}). -@kindex M-e @r{(Calendar mode)} -@findex calendar-end-of-month -@item M-e -Move point to end of month (@code{calendar-end-of-month}). -@kindex M-< @r{(Calendar mode)} -@findex calendar-beginning-of-year -@item M-< -Move point to start of year (@code{calendar-beginning-of-year}). -@kindex M-> @r{(Calendar mode)} -@findex calendar-end-of-year -@item M-> -Move point to end of year (@code{calendar-end-of-year}). -@end table - - These commands also take numeric arguments as repeat counts, with the -repeat count indicating how many weeks, months, or years to move -backward or forward. - -@vindex calendar-week-start-day -@cindex weeks, which day they start on -@cindex calendar, first day of week - By default, weeks begin on Sunday. To make them begin on Monday -instead, set the variable @code{calendar-week-start-day} to 1. - -@node Specified Dates -@subsection Specified Dates - - Calendar mode provides commands for moving to a particular date -specified in various ways. - -@table @kbd -@item g d -Move point to specified date (@code{calendar-goto-date}). -@item g D -Move point to specified day of year (@code{calendar-goto-day-of-year}). -@item g w -Move point to specified week of year (@code{calendar-iso-goto-week}). -@item o -Center calendar around specified month (@code{calendar-other-month}). -@item . -Move point to today's date (@code{calendar-goto-today}). -@end table - -@kindex g d @r{(Calendar mode)} -@findex calendar-goto-date - @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day -of the month, and then moves to that date. Because the calendar includes all -dates from the beginning of the current era, you must type the year in its -entirety; that is, type @samp{1990}, not @samp{90}. - -@kindex g D @r{(Calendar mode)} -@findex calendar-goto-day-of-year -@kindex g w @r{(Calendar mode)} -@findex calendar-iso-goto-week - @kbd{g D} (@code{calendar-goto-day-of-year}) prompts for a year and -day number, and moves to that date. Negative day numbers count -backward from the end of the year. @kbd{g w} -(@code{calendar-iso-goto-week}) prompts for a year and week number, -and moves to that week. - -@kindex o @r{(Calendar mode)} -@findex calendar-other-month - @kbd{o} (@code{calendar-other-month}) prompts for a month and year, -then centers the three-month calendar around that month. - -@kindex . @r{(Calendar mode)} -@findex calendar-goto-today - You can return to today's date with @kbd{.}@: -(@code{calendar-goto-today}). - -@node Scroll Calendar -@section Scrolling in the Calendar - -@cindex scrolling in the calendar - The calendar display scrolls automatically through time when you -move out of the visible portion. You can also scroll it manually. -Imagine that the calendar window contains a long strip of paper with -the months on it. Scrolling the calendar means moving the strip -horizontally, so that new months become visible in the window. - -@table @kbd -@item > -Scroll calendar one month forward (@code{calendar-scroll-left}). -@item < -Scroll calendar one month backward (@code{calendar-scroll-right}). -@item C-v -@itemx @key{next} -Scroll three months forward (@code{calendar-scroll-left-three-months}). -@item M-v -@itemx @key{prior} -Scroll three months backward (@code{calendar-scroll-right-three-months}). -@end table - -@kindex > @r{(Calendar mode)} -@findex calendar-scroll-left -@kindex < @r{(Calendar mode)} -@findex calendar-scroll-right - The most basic calendar scroll commands scroll by one month at a -time. This means that there are two months of overlap between the -display before the command and the display after. @kbd{>} scrolls the -calendar contents one month forward in time. @kbd{<} scrolls the -contents one month backwards in time. - -@kindex C-v @r{(Calendar mode)} -@findex calendar-scroll-left-three-months -@kindex M-v @r{(Calendar mode)} -@findex calendar-scroll-right-three-months - The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire -``screenful''---three months---in analogy with the usual meaning of -these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes -earlier dates visible. These commands take a numeric argument as a -repeat count; in particular, since @kbd{C-u} multiplies the next command -by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and -typing @kbd{C-u M-v} scrolls the calendar backward by a year. - - The function keys @key{next} and @key{prior} are equivalent to -@kbd{C-v} and @kbd{M-v}, just as they are in other modes. - -@node Counting Days -@section Counting Days - -@table @kbd -@item M-= -Display the number of days in the current region -(@code{calendar-count-days-region}). -@end table - -@kindex M-= @r{(Calendar mode)} -@findex calendar-count-days-region - To determine the number of days in a range, set the mark on one -date using @kbd{C-SPC}, move point to another date, and type @kbd{M-=} -(@code{calendar-count-days-region}). The numbers of days shown is -@emph{inclusive}; that is, it includes the days specified by mark and -point. - -@node General Calendar -@section Miscellaneous Calendar Commands - -@table @kbd -@item p d -Display day-in-year (@code{calendar-print-day-of-year}). -@item C-c C-l -Regenerate the calendar window (@code{calendar-redraw}). -@item SPC -Scroll the next window up (@code{scroll-other-window}). -@item DEL -Scroll the next window down (@code{scroll-other-window-down}). -@item q -Exit from calendar (@code{calendar-exit}). -@end table - -@kindex p d @r{(Calendar mode)} -@cindex day of year -@findex calendar-print-day-of-year - To display the number of days elapsed since the start of the year, or -the number of days remaining in the year, type the @kbd{p d} command -(@code{calendar-print-day-of-year}). This displays both of those -numbers in the echo area. The count of days elapsed includes the -selected date. The count of days remaining does not include that -date. - -@kindex C-c C-l @r{(Calendar mode)} -@findex calendar-redraw - If the calendar window text gets corrupted, type @kbd{C-c C-l} -(@code{calendar-redraw}) to redraw it. (This can only happen if you use -non-Calendar-mode editing commands.) - -@kindex SPC @r{(Calendar mode)} - In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window}) -and @kbd{DEL} (@code{scroll-other-window-down}) to scroll the other -window (if there is one) up or down, respectively. This is handy when -you display a list of holidays or diary entries in another window. - -@kindex q @r{(Calendar mode)} -@findex exit-calendar -@vindex calendar-remove-frame-by-deleting - To exit from the calendar, type @kbd{q} (@code{calendar-exit}). This -buries all buffers related to the calendar, selecting other buffers. -(If a frame contains a dedicated calendar window, exiting from the -calendar deletes or iconifies that frame depending on the value of -@code{calendar-remove-frame-by-deleting}.) - -@c FIXME this mentions holidays and diary entries, albeit briefly, so -@c should it be moved after those sections? Or at least xref them. -@node Writing Calendar Files -@section Writing Calendar Files - - You can write calendars and diary entries to HTML and La@TeX{} files. - -@cindex calendar and HTML - The Calendar HTML commands produce files of HTML code that contain -calendar and diary entries. Each file applies to one month, and has a -name of the format @file{@var{yyyy}-@var{mm}.html}, where @var{yyyy} and -@var{mm} are the four-digit year and two-digit month, respectively. The -variable @code{cal-html-directory} specifies the default output -directory for the HTML files. - -@vindex cal-html-css-default - Diary entries enclosed by @code{<} and @code{>} are interpreted as -HTML tags (for example: this is a diary entry with some red text). You can change the overall -appearance of the displayed HTML pages (for example, the color of -various page elements, header styles) via a stylesheet @file{cal.css} in -the directory containing the HTML files (see the value of the variable -@code{cal-html-css-default} for relevant style settings). - -@kindex t @r{(Calendar mode)} -@table @kbd -@item H m -Generate a one-month calendar (@code{cal-html-cursor-month}). -@item H y -Generate a calendar file for each month of a year, as well as an index -page (@code{cal-html-cursor-year}). By default, this command writes -files to a @var{yyyy} subdirectory - if this is altered some hyperlinks -between years will not work. -@end table - - If the variable @code{cal-html-print-day-number-flag} is -non-@code{nil}, then the monthly calendars show the day-of-the-year -number. The variable @code{cal-html-year-index-cols} specifies the -number of columns in the yearly index page. - -@cindex calendar and La@TeX{} - The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that -prints as a calendar. Depending on the command you use, the printed -calendar covers the day, week, month or year that point is in. - -@kindex t @r{(Calendar mode)} -@table @kbd -@item t m -Generate a one-month calendar (@code{cal-tex-cursor-month}). -@item t M -Generate a sideways-printing one-month calendar -(@code{cal-tex-cursor-month-landscape}). -@item t d -Generate a one-day calendar -(@code{cal-tex-cursor-day}). -@item t w 1 -Generate a one-page calendar for one week -(@code{cal-tex-cursor-week}). -@item t w 2 -Generate a two-page calendar for one week -(@code{cal-tex-cursor-week2}). -@item t w 3 -Generate an ISO-style calendar for one week -(@code{cal-tex-cursor-week-iso}). -@item t w 4 -Generate a calendar for one Monday-starting week -(@code{cal-tex-cursor-week-monday}). -@item t f w -Generate a Filofax-style two-weeks-at-a-glance calendar -(@code{cal-tex-cursor-filofax-2week}). -@item t f W -Generate a Filofax-style one-week-at-a-glance calendar -(@code{cal-tex-cursor-filofax-week}). -@item t y -Generate a calendar for one year -(@code{cal-tex-cursor-year}). -@item t Y -Generate a sideways-printing calendar for one year -(@code{cal-tex-cursor-year-landscape}). -@item t f y -Generate a Filofax-style calendar for one year -(@code{cal-tex-cursor-filofax-year}). -@end table - - Some of these commands print the calendar sideways (in ``landscape -mode''), so it can be wider than it is long. Some of them use Filofax -paper size (3.75in x 6.75in). All of these commands accept a prefix -argument, which specifies how many days, weeks, months or years to print -(starting always with the selected one). - - If the variable @code{cal-tex-holidays} is non-@code{nil} (the default), -then the printed calendars show the holidays in @code{calendar-holidays}. -If the variable @code{cal-tex-diary} is non-@code{nil} (the default is -@code{nil}), diary entries are included also (in monthly, filofax, and -iso-week calendars only). If the variable @code{cal-tex-rules} is -non-@code{nil} (the default is @code{nil}), the calendar displays ruled -pages in styles that have sufficient room. Consult the documentation of -the individual cal-tex functions to see which calendars support which -features. - - You can use the variable @code{cal-tex-preamble-extra} to insert extra -La@TeX{} commands in the preamble of the generated document if you need -to. - -@node Holidays -@section Holidays -@cindex holidays - - The Emacs calendar knows about many major and minor holidays, -and can display them. You can add your own holidays to the default list. - -@table @kbd -@item Mouse-3 Holidays -@itemx h -Display holidays for the selected date -(@code{calendar-cursor-holidays}). -@item x -Mark holidays in the calendar window (@code{calendar-mark-holidays}). -@item u -Unmark calendar window (@code{calendar-unmark}). -@item a -List all holidays for the displayed three months in another window -(@code{calendar-list-holidays}). -@item M-x holidays -List all holidays for three months around today's date in another -window. -@item M-x list-holidays -List holidays in another window for a specified range of years. -@end table - -@kindex h @r{(Calendar mode)} -@findex calendar-cursor-holidays -@vindex calendar-view-holidays-initially-flag - To see if any holidays fall on a given date, position point on that -date in the calendar window and use the @kbd{h} command. Alternatively, -click on that date with @kbd{Mouse-3} and then choose @kbd{Holidays} -from the menu that appears. Either way, this displays the holidays for -that date, in the echo area if they fit there, otherwise in a separate -window. - -@kindex x @r{(Calendar mode)} -@findex calendar-mark-holidays -@kindex u @r{(Calendar mode)} -@findex calendar-unmark -@vindex calendar-mark-holidays-flag - To view the distribution of holidays for all the dates shown in the -calendar, use the @kbd{x} command. This displays the dates that are -holidays in a different face. -@iftex -@xref{Calendar Customizing,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Calendar Customizing, calendar-holiday-marker}. -@end ifnottex - The command applies both to the currently visible months and to -other months that subsequently become visible by scrolling. To turn -marking off and erase the current marks, type @kbd{u}, which also -erases any diary marks (@pxref{Diary}). If the variable -@code{calendar-mark-holidays-flag} is non-@code{nil}, creating or -updating the calendar marks holidays automatically. - -@kindex a @r{(Calendar mode)} -@findex calendar-list-holidays - To get even more detailed information, use the @kbd{a} command, which -displays a separate buffer containing a list of all holidays in the -current three-month range. You can use @key{SPC} and @key{DEL} in the -calendar window to scroll that list up and down, respectively. - -@findex holidays - The command @kbd{M-x holidays} displays the list of holidays for the -current month and the preceding and succeeding months; this works even -if you don't have a calendar window. If the variable -@code{calendar-view-holidays-initially-flag} is non-@code{nil}, creating -the calendar displays holidays in this way. If you want the list of -holidays centered around a different month, use @kbd{C-u M-x -holidays}, which prompts for the month and year. - - The holidays known to Emacs include United States holidays and the -major Bahá'í, Chinese, Christian, Islamic, and Jewish holidays; also the -solstices and equinoxes. - -@findex list-holidays - The command @kbd{M-x holiday-list} displays the list of holidays for -a range of years. This function asks you for the starting and stopping -years, and allows you to choose all the holidays or one of several -categories of holidays. You can use this command even if you don't have -a calendar window. - - The dates used by Emacs for holidays are based on @emph{current -practice}, not historical fact. For example Veteran's Day began in -1919, but is shown in earlier years. - -@node Sunrise/Sunset -@section Times of Sunrise and Sunset -@cindex sunrise and sunset - - Special calendar commands can tell you, to within a minute or two, the -times of sunrise and sunset for any date. - -@table @kbd -@item Mouse-3 Sunrise/sunset -@itemx S -Display times of sunrise and sunset for the selected date -(@code{calendar-sunrise-sunset}). -@item M-x sunrise-sunset -Display times of sunrise and sunset for today's date. -@item C-u M-x sunrise-sunset -Display times of sunrise and sunset for a specified date. -@item M-x calendar-sunrise-sunset-month -Display times of sunrise and sunset for the selected month. -@end table - -@kindex S @r{(Calendar mode)} -@findex calendar-sunrise-sunset -@findex sunrise-sunset - Within the calendar, to display the @emph{local times} of sunrise and -sunset in the echo area, move point to the date you want, and type -@kbd{S}. Alternatively, click @kbd{Mouse-3} on the date, then choose -@samp{Sunrise/sunset} from the menu that appears. The command @kbd{M-x -sunrise-sunset} is available outside the calendar to display this -information for today's date or a specified date. To specify a date -other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for -the year, month, and day. - - You can display the times of sunrise and sunset for any location and -any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a -longitude, latitude, number of minutes difference from Coordinated -Universal Time, and date, and then tells you the times of sunrise and -sunset for that location on that date. - - Because the times of sunrise and sunset depend on the location on -earth, you need to tell Emacs your latitude, longitude, and location -name before using these commands. Here is an example of what to set: - -@vindex calendar-location-name -@vindex calendar-longitude -@vindex calendar-latitude -@example -(setq calendar-latitude 40.1) -(setq calendar-longitude -88.2) -(setq calendar-location-name "Urbana, IL") -@end example - -@noindent -Use one decimal place in the values of @code{calendar-latitude} and -@code{calendar-longitude}. - - Your time zone also affects the local time of sunrise and sunset. -Emacs usually gets time zone information from the operating system, but -if these values are not what you want (or if the operating system does -not supply them), you must set them yourself. Here is an example: - -@vindex calendar-time-zone -@vindex calendar-standard-time-zone-name -@vindex calendar-daylight-time-zone-name -@example -(setq calendar-time-zone -360) -(setq calendar-standard-time-zone-name "CST") -(setq calendar-daylight-time-zone-name "CDT") -@end example - -@noindent -The value of @code{calendar-time-zone} is the number of minutes -difference between your local standard time and Coordinated Universal -Time (Greenwich time). The values of -@code{calendar-standard-time-zone-name} and -@code{calendar-daylight-time-zone-name} are the abbreviations used in -your time zone. Emacs displays the times of sunrise and sunset -@emph{corrected for daylight saving time}. @xref{Daylight Saving}, -for how daylight saving time is determined. - - As a user, you might find it convenient to set the calendar location -variables for your usual physical location in your @file{.emacs} file. -If you are a system administrator, you may want to set these variables -for all users in a @file{default.el} file. @xref{Init File}. - -@node Lunar Phases -@section Phases of the Moon -@cindex phases of the moon -@cindex moon, phases of - - These calendar commands display the dates and times of the phases of -the moon (new moon, first quarter, full moon, last quarter). This -feature is useful for debugging problems that ``depend on the phase of -the moon''. - -@table @kbd -@item M -Display the dates and times for all the quarters of the moon for the -three-month period shown (@code{calendar-lunar-phases}). -@item M-x lunar-phases -Display dates and times of the quarters of the moon for three months around -today's date. -@end table - -@kindex M @r{(Calendar mode)} -@findex calendar-lunar-phases - Within the calendar, use the @kbd{M} command to display a separate -buffer of the phases of the moon for the current three-month range. The -dates and times listed are accurate to within a few minutes. - -@findex lunar-phases - Outside the calendar, use the command @kbd{M-x lunar-phases} to -display the list of the phases of the moon for the current month and the -preceding and succeeding months. For information about a different -month, use @kbd{C-u M-x lunar-phases}, which prompts for the month and -year. - - The dates and times given for the phases of the moon are given in -local time (corrected for daylight saving, when appropriate). -See the discussion in the previous section. @xref{Sunrise/Sunset}. - -@node Other Calendars -@section Conversion To and From Other Calendars - -@cindex Gregorian calendar - The Emacs calendar displayed is @emph{always} the Gregorian calendar, -sometimes called the ``new style'' calendar, which is used in most of -the world today. However, this calendar did not exist before the -sixteenth century and was not widely used before the eighteenth century; -it did not fully displace the Julian calendar and gain universal -acceptance until the early twentieth century. The Emacs calendar can -display any month since January, year 1 of the current era, but the -calendar displayed is always the Gregorian, even for a date at which -the Gregorian calendar did not exist. - - While Emacs cannot display other calendars, it can convert dates to -and from several other calendars. - -@menu -* Calendar Systems:: The calendars Emacs understands - (aside from Gregorian). -* To Other Calendar:: Converting the selected date to various calendars. -* From Other Calendar:: Moving to a date specified in another calendar. -* Mayan Calendar:: Moving to a date specified in a Mayan calendar. -@end menu - -@c FIXME perhaps most of the details should be moved to cal-xtra. -@c Just list the major supported systems here? -@node Calendar Systems -@subsection Supported Calendar Systems - -@cindex ISO commercial calendar - The ISO commercial calendar is often used in business. - -@cindex Julian calendar - The Julian calendar, named after Julius Caesar, was the one used in Europe -throughout medieval times, and in many countries up until the nineteenth -century. - -@cindex Julian day numbers -@cindex astronomical day numbers - Astronomers use a simple counting of days elapsed since noon, Monday, -January 1, 4713 B.C. on the Julian calendar. The number of days elapsed -is called the @dfn{Julian day number} or the @dfn{Astronomical day number}. - -@cindex Hebrew calendar - The Hebrew calendar is used by tradition in the Jewish religion. The -Emacs calendar program uses the Hebrew calendar to determine the dates -of Jewish holidays. Hebrew calendar dates begin and end at sunset. - -@cindex Islamic calendar - The Islamic calendar is used in many predominantly Islamic countries. -Emacs uses it to determine the dates of Islamic holidays. There is no -universal agreement in the Islamic world about the calendar; Emacs uses -a widely accepted version, but the precise dates of Islamic holidays -often depend on proclamation by religious authorities, not on -calculations. As a consequence, the actual dates of observance can vary -slightly from the dates computed by Emacs. Islamic calendar dates begin -and end at sunset. - -@cindex French Revolutionary calendar - The French Revolutionary calendar was created by the Jacobins after the 1789 -revolution, to represent a more secular and nature-based view of the annual -cycle, and to install a 10-day week in a rationalization measure similar to -the metric system. The French government officially abandoned this -calendar at the end of 1805. - -@cindex Mayan calendar - The Maya of Central America used three separate, overlapping calendar -systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}. -Emacs knows about all three of these calendars. Experts dispute the -exact correlation between the Mayan calendar and our calendar; Emacs uses the -Goodman-Martinez-Thompson correlation in its calculations. - -@cindex Coptic calendar -@cindex Ethiopic calendar - The Copts use a calendar based on the ancient Egyptian solar calendar. -Their calendar consists of twelve 30-day months followed by an extra -five-day period. Once every fourth year they add a leap day to this -extra period to make it six days. The Ethiopic calendar is identical in -structure, but has different year numbers and month names. - -@cindex Persian calendar - The Persians use a solar calendar based on a design of Omar Khayyam. -Their calendar consists of twelve months of which the first six have 31 -days, the next five have 30 days, and the last has 29 in ordinary years -and 30 in leap years. Leap years occur in a complicated pattern every -four or five years. -The calendar implemented here is the arithmetical Persian calendar -championed by Birashk, based on a 2,820-year cycle. It differs from -the astronomical Persian calendar, which is based on astronomical -events. As of this writing the first future discrepancy is projected -to occur on March 20, 2025. It is currently not clear what the -official calendar of Iran will be at that time. -@c FIXME not so far in the future now. - -@cindex Chinese calendar - The Chinese calendar is a complicated system of lunar months arranged -into solar years. The years go in cycles of sixty, each year containing -either twelve months in an ordinary year or thirteen months in a leap -year; each month has either 29 or 30 days. Years, ordinary months, and -days are named by combining one of ten ``celestial stems'' with one of -twelve ``terrestrial branches'' for a total of sixty names that are -repeated in a cycle of sixty. - -@cindex Bahá'í calendar - The Bahá'í calendar system is based on a solar cycle of 19 months with -19 days each. The four remaining ``intercalary'' days are placed -between the 18th and 19th months. - -@node To Other Calendar -@subsection Converting To Other Calendars - - The following commands describe the selected date (the date at point) -in various other calendar systems: - -@table @kbd -@kindex p @r{(Calendar mode)} -@findex calendar-print-other-dates -@item Mouse-3 Other calendars -@itemx p o -Display the selected date in various other calendars. -(@code{calendar-print-other-dates}). -@findex calendar-iso-print-date -@item p c -Display ISO commercial calendar equivalent for selected day -(@code{calendar-iso-print-date}). -@findex calendar-julian-print-date -@item p j -Display Julian date for selected day (@code{calendar-julian-print-date}). -@findex calendar-astro-print-day-number -@item p a -Display astronomical (Julian) day number for selected day -(@code{calendar-astro-print-day-number}). -@findex calendar-hebrew-print-date -@item p h -Display Hebrew date for selected day (@code{calendar-hebrew-print-date}). -@findex calendar-islamic-print-date -@item p i -Display Islamic date for selected day (@code{calendar-islamic-print-date}). -@findex calendar-french-print-date -@item p f -Display French Revolutionary date for selected day -(@code{calendar-french-print-date}). -@findex calendar-bahai-print-date -@item p b -Display Bahá'í date for selected day -(@code{calendar-bahai-print-date}). -@findex calendar-chinese-print-date -@item p C -Display Chinese date for selected day -(@code{calendar-chinese-print-date}). -@findex calendar-coptic-print-date -@item p k -Display Coptic date for selected day -(@code{calendar-coptic-print-date}). -@findex calendar-ethiopic-print-date -@item p e -Display Ethiopic date for selected day -(@code{calendar-ethiopic-print-date}). -@findex calendar-persian-print-date -@item p p -Display Persian date for selected day -(@code{calendar-persian-print-date}). -@findex calendar-mayan-print-date -@item p m -Display Mayan date for selected day (@code{calendar-mayan-print-date}). -@end table - - Otherwise, move point to the date you want to convert, then type the -appropriate command starting with @kbd{p} from the table above. The -prefix @kbd{p} is a mnemonic for ``print'', since Emacs ``prints'' the -equivalent date in the echo area. @kbd{p o} displays the -date in all forms known to Emacs. You can also use @kbd{Mouse-3} and -then choose @kbd{Other calendars} from the menu that appears. This -displays the equivalent forms of the date in all the calendars Emacs -understands, in the form of a menu. (Choosing an alternative from -this menu doesn't actually do anything---the menu is used only for -display.) - -@node From Other Calendar -@subsection Converting From Other Calendars - - You can use the other supported calendars to specify a date to move -to. This section describes the commands for doing this using calendars -other than Mayan; for the Mayan calendar, see the following section. - -@kindex g @var{char} @r{(Calendar mode)} -@findex calendar-iso-goto-date -@findex calendar-iso-goto-week -@findex calendar-julian-goto-date -@findex calendar-astro-goto-day-number -@findex calendar-bahai-goto-date -@findex calendar-hebrew-goto-date -@findex calendar-islamic-goto-date -@findex calendar-french-goto-date -@findex calendar-chinese-goto-date -@findex calendar-persian-goto-date -@findex calendar-coptic-goto-date -@findex calendar-ethiopic-goto-date -@table @kbd -@item g c -Move to a date specified in the ISO commercial calendar -(@code{calendar-iso-goto-date}). -@item g w -Move to a week specified in the ISO commercial calendar -(@code{calendar-iso-goto-week}). -@item g j -Move to a date specified in the Julian calendar -(@code{calendar-julian-goto-date}). -@item g a -Move to a date specified with an astronomical (Julian) day number -(@code{calendar-astro-goto-day-number}). -@item g b -Move to a date specified in the Bahá'í calendar -(@code{calendar-bahai-goto-date}). -@item g h -Move to a date specified in the Hebrew calendar -(@code{calendar-hebrew-goto-date}). -@item g i -Move to a date specified in the Islamic calendar -(@code{calendar-islamic-goto-date}). -@item g f -Move to a date specified in the French Revolutionary calendar -(@code{calendar-french-goto-date}). -@item g C -Move to a date specified in the Chinese calendar -(@code{calendar-chinese-goto-date}). -@item g p -Move to a date specified in the Persian calendar -(@code{calendar-persian-goto-date}). -@item g k -Move to a date specified in the Coptic calendar -(@code{calendar-coptic-goto-date}). -@item g e -Move to a date specified in the Ethiopic calendar -(@code{calendar-ethiopic-goto-date}). -@end table - - These commands ask you for a date on the other calendar, move point -to the Gregorian calendar date equivalent to that date, and display -the other calendar's date in the echo area. Emacs uses strict -completion (@pxref{Completion Exit}) whenever it asks you to type a -month name, so you don't have to worry about the spelling of Hebrew, -Islamic, or French names. - -@c FIXME move? -@findex calendar-hebrew-list-yahrzeits -@cindex yahrzeits - One common issue concerning the Hebrew calendar is the computation -of the anniversary of a date of death, called a ``yahrzeit''. The Emacs -calendar includes a facility for such calculations. If you are in the -calendar, the command @kbd{M-x calendar-hebrew-list-yahrzeits} asks you for -a range of years and then displays a list of the yahrzeit dates for those -years for the date given by point. If you are not in the calendar, -this command first asks you for the date of death and the range of -years, and then displays the list of yahrzeit dates. - -@c FIXME move to emacs-xtra. -@node Mayan Calendar -@subsection Converting from the Mayan Calendar - - Here are the commands to select dates based on the Mayan calendar: - -@table @kbd -@item g m l -Move to a date specified by the long count calendar -(@code{calendar-mayan-goto-long-count-date}). -@item g m n t -Move to the next occurrence of a place in the -tzolkin calendar (@code{calendar-mayan-next-tzolkin-date}). -@item g m p t -Move to the previous occurrence of a place in the -tzolkin calendar (@code{calendar-mayan-previous-tzolkin-date}). -@item g m n h -Move to the next occurrence of a place in the -haab calendar (@code{calendar-mayan-next-haab-date}). -@item g m p h -Move to the previous occurrence of a place in the -haab calendar (@code{calendar-mayan-previous-haab-date}). -@item g m n c -Move to the next occurrence of a place in the -calendar round (@code{calendar-mayan-next-calendar-round-date}). -@item g m p c -Move to the previous occurrence of a place in the -calendar round (@code{calendar-mayan-previous-calendar-round-date}). -@end table - -@cindex Mayan long count - To understand these commands, you need to understand the Mayan calendars. -The @dfn{long count} is a counting of days with these units: - -@display -1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal -1 katun = 20 tun@ @ @ 1 baktun = 20 katun -@end display - -@kindex g m @r{(Calendar mode)} -@findex calendar-mayan-goto-long-count-date -@noindent -Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 -tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long -count dates as early as 7.17.18.13.3, but no earlier. When you use the -@kbd{g m l} command, type the Mayan long count date with the baktun, -katun, tun, uinal, and kin separated by periods. - -@findex calendar-mayan-previous-tzolkin-date -@findex calendar-mayan-next-tzolkin-date -@cindex Mayan tzolkin calendar - The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of -independent cycles of 13 and 20 days. Since this cycle repeats -endlessly, Emacs provides commands to move backward and forward to the -previous or next point in the cycle. Type @kbd{g m p t} to go to the -previous tzolkin date; Emacs asks you for a tzolkin date and moves point -to the previous occurrence of that date. Similarly, type @kbd{g m n t} -to go to the next occurrence of a tzolkin date. - -@findex calendar-mayan-previous-haab-date -@findex calendar-mayan-next-haab-date -@cindex Mayan haab calendar - The Mayan haab calendar is a cycle of 365 days arranged as 18 months -of 20 days each, followed by a 5-day monthless period. Like the tzolkin -cycle, this cycle repeats endlessly, and there are commands to move -backward and forward to the previous or next point in the cycle. Type -@kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab -date and moves point to the previous occurrence of that date. -Similarly, type @kbd{g m n h} to go to the next occurrence of a haab -date. - -@c This is omitted because it is too long for smallbook format. -@c @findex calendar-mayan-previous-calendar-round-date -@findex calendar-mayan-next-calendar-round-date -@cindex Mayan calendar round - The Maya also used the combination of the tzolkin date and the haab -date. This combination is a cycle of about 52 years called a -@emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for -both a haab and a tzolkin date and then moves point to the previous -occurrence of that combination. Use @kbd{g m n c} to move point to the -next occurrence of a combination. These commands signal an error if the -haab/tzolkin date combination you have typed is impossible. - - Emacs uses strict completion (@pxref{Completion Exit}) whenever it -asks you to type a Mayan name, so you don't have to worry about -spelling. - -@node Diary -@section The Diary -@cindex diary - - The Emacs diary keeps track of appointments or other events on a daily -basis, in conjunction with the calendar. To use the diary feature, you -must first create a @dfn{diary file} containing a list of events and -their dates. Then Emacs can automatically pick out and display the -events for today, for the immediate future, or for any specified -date. - - The name of the diary file is specified by the variable -@code{diary-file}; @file{~/diary} is the default. Here's an example -showing what that file looks like: - -@example -12/22/2012 Twentieth wedding anniversary!! -&1/1. Happy New Year! -10/22 Ruth's birthday. -* 21, *: Payday -Tuesday--weekly meeting with grad students at 10am - Supowit, Shen, Bitner, and Kapoor to attend. -1/13/89 Friday the thirteenth!! -&thu 4pm squash game with Lloyd. -mar 16 Dad's birthday -April 15, 2013 Income tax due. -&* 15 time cards due. -@end example - -@noindent -This format is essentially the same as the one used by the separate -@command{calendar} utility that is present on some Unix systems. This -example uses extra spaces to align the event descriptions of most of -the entries. Such formatting is purely a matter of taste. - - Although you probably will start by creating a diary manually, Emacs -provides a number of commands to let you view, add, and change diary -entries. - -@menu -* Displaying the Diary:: Viewing diary entries and associated calendar dates. -* Format of Diary File:: Entering events in your diary. -* Date Formats:: Various ways you can specify dates. -* Adding to Diary:: Commands to create diary entries. -* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. -@end menu - -@node Displaying the Diary -@subsection Displaying the Diary - - Once you have created a diary file, you can use the calendar to view -it. You can also view today's events outside of Calendar mode. In the -following, key bindings refer to the Calendar buffer. - -@table @kbd -@item Mouse-3 Diary -@itemx d -Display all diary entries for the selected date -(@code{diary-view-entries}). -@item s -Display the entire diary file (@code{diary-show-all-entries}). -@item m -Mark all visible dates that have diary entries -(@code{diary-mark-entries}). -@item u -Unmark the calendar window (@code{calendar-unmark}). -@item M-x diary-print-entries -Print hard copy of the diary display as it appears. -@item M-x diary -Display all diary entries for today's date. -@item M-x diary-mail-entries -Mail yourself email reminders about upcoming diary entries. -@end table - -@kindex d @r{(Calendar mode)} -@findex diary-view-entries -@vindex calendar-view-diary-initially-flag - Displaying the diary entries with @kbd{d} shows in a separate window -the diary entries for the selected date in the calendar. The mode line -of the new window shows the date of the diary entries. Holidays are -shown either in the buffer or in the mode line, depending on the display -method you choose -@iftex -(@pxref{Diary Display,,, emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Diary Display}). -@end ifnottex -If you specify a numeric argument with @kbd{d}, it shows all the diary -entries for that many successive days. Thus, @kbd{2 d} displays all the -entries for the selected date and for the following day. - - Another way to display the diary entries for a date is to click -@kbd{Mouse-3} on the date, and then choose @kbd{Diary entries} from -the menu that appears. If the variable -@code{calendar-view-diary-initially-flag} is non-@code{nil}, creating the -calendar lists the diary entries for the current date (provided the -current date is visible). - -@kindex m @r{(Calendar mode)} -@findex diary-mark-entries -@vindex calendar-mark-diary-entries-flag - To get a broader view of which days are mentioned in the diary, use -the @kbd{m} command. This marks the dates that have diary entries in -a different face. -@iftex -@xref{Calendar Customizing,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Calendar Customizing, diary-entry-marker}. -@end ifnottex - - This command applies both to the months that are currently visible -and to those that subsequently become visible after scrolling. To turn -marking off and erase the current marks, type @kbd{u}, which also -turns off holiday marks (@pxref{Holidays}). If the variable -@code{calendar-mark-diary-entries-flag} is non-@code{nil}, creating or -updating the calendar marks diary dates automatically. - -@kindex s @r{(Calendar mode)} -@findex diary-show-all-entries - To see the full diary file, rather than just some of the entries, use -the @kbd{s} command. - -@findex diary - The command @kbd{M-x diary} displays the diary entries for the current -date, independently of the calendar display, and optionally for the next -few days as well; the variable @code{diary-number-of-entries} specifies -how many days to include. -@iftex -@xref{Diary Customizing,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Diary Customizing, diary-number-of-entries}. -@end ifnottex - - If you put @code{(diary)} in your @file{.emacs} file, this -automatically displays a window with the day's diary entries when you -start Emacs. - -@findex diary-mail-entries -@vindex diary-mail-days - Some people like to receive email notifications of events in their -diary. To send such mail to yourself, use the command @kbd{M-x -diary-mail-entries}. A prefix argument specifies how many days -(starting with today) to check; otherwise, the variable -@code{diary-mail-days} says how many days. - -@node Format of Diary File -@subsection The Diary File -@cindex diary file - -@vindex diary-file - Your @dfn{diary file} is a file that records events associated with -particular dates. The name of the diary file is specified by the -variable @code{diary-file}; @file{~/diary} is the default. The -@code{calendar} utility program supports a subset of the format allowed -by the Emacs diary facilities, so you can use that utility to view the -diary file, with reasonable results aside from the entries it cannot -understand. - - Each entry in the diary file describes one event and consists of one -or more lines. An entry always begins with a date specification at the -left margin. The rest of the entry is simply text to describe the -event. If the entry has more than one line, then the lines after the -first must begin with whitespace to indicate they continue a previous -entry. Lines that do not begin with valid dates and do not continue a -preceding entry are ignored. - - You can also use a format where the first line of a diary entry -consists only of the date or day name (with no following blanks or -punctuation). For example: - -@example -02/11/2012 - Bill B. visits Princeton today - 2pm Cognitive Studies Committee meeting - 2:30-5:30 Liz at Lawrenceville - 4:00pm Dentist appt - 7:30pm Dinner at George's - 8:00-10:00pm concert -@end example - -@noindent -This entry will have a different appearance if you use the simple diary -display -@iftex -(@pxref{Diary Display,,, emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Diary Display}). -@end ifnottex -The simple diary display omits the date line at the beginning; only the -continuation lines appear. This style of entry looks neater when you -display just a single day's entries, but can cause confusion if you ask -for more than one day's entries. - -@vindex diary-nonmarking-symbol - You can inhibit the marking of certain diary entries in the calendar -window; to do this, insert the string that -@code{diary-nonmarking-symbol} specifies (default @samp{&}) at the -beginning of the entry, before the date. This -has no effect on display of the entry in the diary window; it only -affects marks on dates in the calendar window. Nonmarking entries are -especially useful for generic entries that would otherwise mark many -different dates. - -@node Date Formats -@subsection Date Formats - - Here are some sample diary entries, illustrating different ways of -formatting a date. The examples all show dates in American order -(month, day, year), but Calendar mode supports European order (day, -month, year) and ISO order (year, month, day) as options. - -@example -4/20/12 Switch-over to new tabulation system -apr. 25 Start tabulating annual results -4/30 Results for April are due -*/25 Monthly cycle finishes -Friday Don't leave without backing up files -@end example - - The first entry appears only once, on April 20, 2012. The second and -third appear every year on the specified dates, and the fourth uses a -wildcard (asterisk) for the month, so it appears on the 25th of every -month. The final entry appears every week on Friday. - - You can use just numbers to express a date, as in -@samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}. -This must be followed by a nondigit. In the date itself, @var{month} -and @var{day} are numbers of one or two digits. The optional @var{year} -is also a number, and may be abbreviated to the last two digits; that -is, you can use @samp{11/12/2012} or @samp{11/12/12}. - - Dates can also have the form @samp{@var{monthname} @var{day}} or -@samp{@var{monthname} @var{day}, @var{year}}, where the month's name can -be spelled in full or abbreviated (with or without a period). The -preferred abbreviations for month and day names can be set using -the variables @code{calendar-abbrev-length}, -@code{calendar-month-abbrev-array}, and -@code{calendar-day-abbrev-array}. The default is to use the first three -letters of a name as its abbreviation. Case is not significant. - - A date may be @dfn{generic}; that is, partially unspecified. Then the -entry applies to all dates that match the specification. If the date -does not contain a year, it is generic and applies to any year. -Alternatively, @var{month}, @var{day}, or @var{year} can be @samp{*}; -this matches any month, day, or year, respectively. Thus, a diary entry -@samp{3/*/*} matches any day in March of any year; so does @samp{march -*}. - -@vindex calendar-date-style -@findex calendar-set-date-style - If you prefer the European style of writing dates (in which the day -comes before the month), or the ISO style (in which the order is year, -month, day), type @kbd{M-x calendar-set-date-style} while in the -calendar, or customize the variable @code{calendar-date-style}. This -affects how diary dates are interpreted, date display, and the order in -which some commands expect their arguments to be given. - - You can use the name of a day of the week as a generic date which -applies to any date falling on that day of the week. You can abbreviate -the day of the week as described above, or spell it in full; case is not -significant. - -@node Adding to Diary -@subsection Commands to Add to the Diary - - While in the calendar, there are several commands to create diary -entries. The basic commands are listed here; more sophisticated -commands are in the next section (@pxref{Special Diary Entries}). -Entries can also be based on non-Gregorian calendars. -@iftex -@xref{Non-Gregorian Diary,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Non-Gregorian Diary}. -@end ifnottex - -@table @kbd -@item i d -Add a diary entry for the selected date (@code{diary-insert-entry}). -@item i w -Add a diary entry for the selected day of the week (@code{diary-insert-weekly-entry}). -@item i m -Add a diary entry for the selected day of the month (@code{diary-insert-monthly-entry}). -@item i y -Add a diary entry for the selected day of the year (@code{diary-insert-yearly-entry}). -@end table - -@kindex i d @r{(Calendar mode)} -@findex diary-insert-entry - You can make a diary entry for a specific date by selecting that date -in the calendar window and typing the @kbd{i d} command. This command -displays the end of your diary file in another window and inserts the -date; you can then type the rest of the diary entry. - -@kindex i w @r{(Calendar mode)} -@findex diary-insert-weekly-entry -@kindex i m @r{(Calendar mode)} -@findex diary-insert-monthly-entry -@kindex i y @r{(Calendar mode)} -@findex diary-insert-yearly-entry - If you want to make a diary entry that applies to a specific day of -the week, select that day of the week (any occurrence will do) and type -@kbd{i w}. This inserts the day-of-week as a generic date; you can then -type the rest of the diary entry. You can make a monthly diary entry in -the same fashion: select the day of the month, use the @kbd{i m} -command, and type the rest of the entry. Similarly, you can insert a -yearly diary entry with the @kbd{i y} command. - - All of the above commands make marking diary entries by default. To -make a nonmarking diary entry, give a prefix argument to the command. -For example, @kbd{C-u i w} makes a nonmarking weekly diary entry. - - When you modify the diary file, be sure to save the file before -exiting Emacs. Saving the diary file after using any of the above -insertion commands will automatically update the diary marks in the -calendar window, if appropriate. You can use the command -@code{calendar-redraw} to force an update at any time. - -@node Special Diary Entries -@subsection Special Diary Entries - - In addition to entries based on calendar dates, the diary file can -contain @dfn{sexp entries} for regular events such as anniversaries. -These entries are based on Lisp expressions (sexps) that Emacs evaluates -as it scans the diary file. Instead of a date, a sexp entry contains -@samp{%%} followed by a Lisp expression which must begin and end with -parentheses. The Lisp expression determines which dates the entry -applies to. - - Calendar mode provides commands to insert certain commonly used -sexp entries: - -@table @kbd -@item i a -Add an anniversary diary entry for the selected date -(@code{diary-insert-anniversary-entry}). -@item i b -Add a block diary entry for the current region -(@code{diary-insert-block-entry}). -@item i c -Add a cyclic diary entry starting at the date -(@code{diary-insert-cyclic-entry}). -@end table - -@kindex i a @r{(Calendar mode)} -@findex diary-insert-anniversary-entry - If you want to make a diary entry that applies to the anniversary of a -specific date, move point to that date and use the @kbd{i a} command. -This displays the end of your diary file in another window and inserts -the anniversary description; you can then type the rest of the diary -entry. The entry looks like this: - -@findex diary-anniversary -@example -%%(diary-anniversary 10 31 1948) Arthur's birthday -@end example - -@noindent -This entry applies to October 31 in any year after 1948; @samp{10 31 -1948} specifies the date. (If you are using the European or ISO -calendar style, the input order of month, day and year is different.) -The reason this expression requires a beginning year is that advanced -diary functions can use it to calculate the number of elapsed years. - - A @dfn{block} diary entry applies to a specified range of consecutive -dates. Here is a block diary entry that applies to all dates from June -24, 2012 through July 10, 2012: - -@findex diary-block -@example -%%(diary-block 6 24 2012 7 10 2012) Vacation -@end example - -@noindent -The @samp{6 24 2012} indicates the starting date and the @samp{7 10 2012} -indicates the stopping date. (Again, if you are using the European or ISO -calendar style, the input order of month, day and year is different.) - -@kindex i b @r{(Calendar mode)} -@findex diary-insert-block-entry - To insert a block entry, place point and the mark on the two -dates that begin and end the range, and type @kbd{i b}. This command -displays the end of your diary file in another window and inserts the -block description; you can then type the diary entry. - -@kindex i c @r{(Calendar mode)} -@findex diary-insert-cyclic-entry - @dfn{Cyclic} diary entries repeat after a fixed interval of days. To -create one, select the starting date and use the @kbd{i c} command. The -command prompts for the length of interval, then inserts the entry, -which looks like this: - -@findex diary-cyclic -@example -%%(diary-cyclic 50 3 1 2012) Renew medication -@end example - -@noindent -This entry applies to March 1, 2012 and every 50th day following; -@samp{3 1 2012} specifies the starting date. (If you are using the -European or ISO calendar style, the input order of month, day and year -is different.) - - All three of these commands make marking diary entries. To insert a -nonmarking entry, give a prefix argument to the command. For example, -@kbd{C-u i a} makes a nonmarking anniversary diary entry. - - Marking sexp diary entries in the calendar can be time-consuming, -since every date visible in the calendar window must be individually -checked. So it's a good idea to make sexp diary entries nonmarking -(with @samp{&}) when possible. - - Another sophisticated kind of sexp entry, a @dfn{floating} diary entry, -specifies a regularly occurring event by offsets specified in days, -weeks, and months. It is comparable to a crontab entry interpreted by -the @code{cron} utility. Here is a nonmarking, floating diary entry -that applies to the fourth Thursday in November: - -@findex diary-float -@example -&%%(diary-float 11 4 4) American Thanksgiving -@end example - -@noindent -The 11 specifies November (the eleventh month), the 4 specifies Thursday -(the fourth day of the week, where Sunday is numbered zero), and the -second 4 specifies the fourth Thursday (1 would mean ``first'', 2 would -mean ``second'', @minus{}2 would mean ``second-to-last'', and so on). -The month can be a single month or a list of months. Thus you could change -the 11 above to @samp{'(1 2 3)} and have the entry apply to the last -Thursday of January, February, and March. If the month is @code{t}, the -entry applies to all months of the year.@refill - - Each of the standard sexp diary entries takes an optional parameter -specifying the name of a face or a single-character string to use when -marking the entry in the calendar. Most generally, sexp diary entries -can perform arbitrary computations to determine when they apply. -@iftex -@xref{Sexp Diary Entries,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Sexp Diary Entries}. -@end ifnottex - -@node Appointments -@section Appointments -@cindex appointment notification - -@vindex appt-display-format -@vindex appt-audible -@vindex appt-display-mode-line - If you have a diary entry for an appointment, and that diary entry -begins with a recognizable time of day, Emacs can warn you in advance -that an appointment is pending. Emacs alerts you -to the appointment by displaying a message in your chosen format, as -specified by the variable @code{appt-display-format}. If the value of -@code{appt-audible} is non-@code{nil}, the warning includes an audible -reminder. In addition, if @code{appt-display-mode-line} is -non-@code{nil}, Emacs displays the number of minutes to the -appointment on the mode line. - -@vindex appt-display-duration -@vindex appt-disp-window-function -@vindex appt-delete-window-function - If @code{appt-display-format} has the value @code{window}, then the -variable @code{appt-display-duration} controls how long the reminder -window is visible for; and the variables -@code{appt-disp-window-function} and @code{appt-delete-window-function} -give the names of functions used to create and destroy the window, -respectively. - -@findex appt-activate - To enable appointment notification, type @kbd{M-x appt-activate}. -With a positive argument, it enables notification; with a negative -argument, it disables notification; with no argument, it toggles. -Enabling notification also sets up an appointment list for today from -the diary file, giving all diary entries found with recognizable times -of day, and reminds you just before each of them. - - For example, suppose the diary file contains these lines: - -@example -Monday - 9:30am Coffee break - 12:00pm Lunch -@end example - -@vindex appt-message-warning-time -@vindex appt-warning-time-regexp -@noindent -Then on Mondays, you will be reminded at around 9:20am about your -coffee break and at around 11:50am about lunch. The variable -@code{appt-message-warning-time} specifies how many minutes (default 12) -in advance to warn you. This is a default warning time. Each -appointment can specify a different warning time by adding a piece -matching @code{appt-warning-time-regexp} (see that variable's -documentation for details). - - You can write times in am/pm style (with @samp{12:00am} standing -for midnight and @samp{12:00pm} standing for noon), or 24-hour -European/military style. You need not be consistent; your diary file -can have a mixture of the two styles. Times must be at the beginning of -diary entries if they are to be recognized. - -@vindex appt-display-diary - Emacs updates the appointments list from the diary file -automatically just after midnight. You can force an update at any -time by re-enabling appointment notification. Both these actions also -display the day's diary buffer, unless you set -@code{appt-display-diary} to @code{nil}. The appointments list is -also updated whenever the diary file (or a file it includes; see -@iftex -@ref{Fancy Diary Display,,, emacs-xtra, Specialized Emacs Features}) -@end iftex -@ifnottex -@ref{Fancy Diary Display}) -@end ifnottex -is saved. - -@findex appt-add -@findex appt-delete -@cindex alarm clock - You can also use the appointment notification facility like an alarm -clock. The command @kbd{M-x appt-add} adds entries to the appointment -list without affecting your diary file. You delete entries from the -appointment list with @kbd{M-x appt-delete}. - -@node Importing Diary -@section Importing and Exporting Diary Entries - - You can transfer diary entries between Emacs diary files and a -variety of other formats. - -@vindex diary-outlook-formats - You can import diary entries from Outlook-generated appointment -messages. While viewing such a message in Rmail or Gnus, do @kbd{M-x -diary-from-outlook} to import the entry. You can make this command -recognize additional appointment message formats by customizing the -variable @code{diary-outlook-formats}. - -@c FIXME the name of the RFC is hardly very relevant. -@cindex iCalendar support - The icalendar package allows you to transfer data between your Emacs -diary file and iCalendar files, which are defined in ``RFC -2445---Internet Calendaring and Scheduling Core Object Specification -(iCalendar)'' (as well as the earlier vCalendar format). - -@c Importing works for ``ordinary'' (i.e. non-recurring) events, but -@c (at present) may not work correctly (if at all) for recurring events. -@c Exporting of diary files into iCalendar files should work correctly -@c for most diary entries. This feature is a work in progress, so the -@c commands may evolve in future. - -@findex icalendar-import-buffer - The command @code{icalendar-import-buffer} extracts -iCalendar data from the current buffer and adds it to your -diary file. This function is also suitable for automatic extraction of -iCalendar data; for example with the Rmail mail client one could use: - -@example -(add-hook 'rmail-show-message-hook 'icalendar-import-buffer) -@end example - -@findex icalendar-import-file - The command @code{icalendar-import-file} imports an iCalendar file -and adds the results to an Emacs diary file. For example: - -@example -(icalendar-import-file "/here/is/calendar.ics" - "/there/goes/ical-diary") -@end example - -@noindent -You can use an @code{#include} directive to add the import file contents -to the main diary file, if these are different files. -@iftex -@xref{Fancy Diary Display,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Fancy Diary Display}. -@end ifnottex - - -@findex icalendar-export-file, icalendar-export-region - Use @code{icalendar-export-file} to interactively export an entire -Emacs diary file to iCalendar format. To export only a part of a diary -file, mark the relevant area, and call @code{icalendar-export-region}. -In both cases, Emacs appends the result to the target file. - -@node Daylight Saving -@section Daylight Saving Time -@cindex daylight saving time - - Emacs understands the difference between standard time and daylight -saving time---the times given for sunrise, sunset, solstices, -equinoxes, and the phases of the moon take that into account. The rules -for daylight saving time vary from place to place and have also varied -historically from year to year. To do the job properly, Emacs needs to -know which rules to use. - -@vindex calendar-daylight-savings-starts -@vindex calendar-daylight-savings-ends - Some operating systems keep track of the rules that apply to the place -where you are; on these systems, Emacs gets the information it needs -from the system automatically. If some or all of this information is -missing, Emacs fills in the gaps with the rules currently used in -Cambridge, Massachusetts. If the resulting rules are not what you want, -you can tell Emacs the rules to use by setting certain variables: -@code{calendar-daylight-savings-starts} and -@code{calendar-daylight-savings-ends}. - - These values should be Lisp expressions that refer to the variable -@code{year}, and evaluate to the Gregorian date on which daylight -saving time starts or (respectively) ends, in the form of a list -@code{(@var{month} @var{day} @var{year})}. The values should be -@code{nil} if your area does not use daylight saving time. - - Emacs uses these expressions to determine the starting date of -daylight saving time for the holiday list and for correcting times of -day in the solar and lunar calculations. - - The values for Cambridge, Massachusetts are as follows: - -@example -(calendar-nth-named-day 2 0 3 year) -(calendar-nth-named-day 1 0 11 year) -@end example - -@noindent -That is, the second 0th day (Sunday) of the third month (March) in -the year specified by @code{year}, and the first Sunday of the eleventh month -(November) of that year. If daylight saving time were -changed to start on October 1, you would set -@code{calendar-daylight-savings-starts} to this: - -@example -(list 10 1 year) -@end example - - If there is no daylight saving time at your location, or if you want -all times in standard time, set @code{calendar-daylight-savings-starts} -and @code{calendar-daylight-savings-ends} to @code{nil}. - -@vindex calendar-daylight-time-offset - The variable @code{calendar-daylight-time-offset} specifies the -difference between daylight saving time and standard time, measured in -minutes. The value for Cambridge, Massachusetts is 60. - -@c @vindex calendar-daylight-savings-starts-time too long! -@vindex calendar-daylight-savings-ends-time - Finally, the two variables -@code{calendar-daylight-savings-starts-time} and -@code{calendar-daylight-savings-ends-time} specify the number of -minutes after midnight local time when the transition to and from -daylight saving time should occur. For Cambridge, Massachusetts both -variables' values are 120. - -@node Time Intervals -@section Summing Time Intervals -@cindex time intervals, summing -@cindex summing time intervals -@cindex timeclock - - The timeclock package adds up time intervals, so you can (for -instance) keep track of how much time you spend working on particular -projects. - -@findex timeclock-in -@findex timeclock-out -@findex timeclock-change -@findex timeclock-workday-remaining -@findex timeclock-when-to-leave - Use the @kbd{M-x timeclock-in} command when you start working on a -project, and @kbd{M-x timeclock-out} command when you're done. Each -time you do this, it adds one time interval to the record of the -project. You can change to working on a different project with @kbd{M-x -timeclock-change}. - - Once you've collected data from a number of time intervals, you can use -@kbd{M-x timeclock-workday-remaining} to see how much time is left to -work today (assuming a typical average of 8 hours a day), and @kbd{M-x -timeclock-when-to-leave} which will calculate when you're ``done''. - -@vindex timeclock-modeline-display -@findex timeclock-modeline-display - If you want Emacs to display the amount of time ``left'' of your -workday in the mode line, either customize the -@code{timeclock-modeline-display} variable and set its value to -@code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command. - -@vindex timeclock-ask-before-exiting - Terminating the current Emacs session might or might not mean that -you have stopped working on the project and, by default, Emacs asks -you. You can, however, customize the value of the variable -@code{timeclock-ask-before-exiting} to @code{nil} to avoid the question; -then, only an explicit @kbd{M-x timeclock-out} or @kbd{M-x -timeclock-change} will tell Emacs that the current interval is over. - -@cindex @file{.timelog} file -@vindex timeclock-file -@findex timeclock-reread-log - The timeclock functions work by accumulating the data in a file -called @file{.timelog} in your home directory. You can specify a -different name for this file by customizing the variable -@code{timeclock-file}. If you edit the timeclock file manually, or if -you change the value of any of timeclock's customizable variables, you -should run the command @kbd{M-x timeclock-reread-log} to update the -data in Emacs from the file. - -@ifnottex -@include cal-xtra.texi -@end ifnottex diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi deleted file mode 100644 index c387b99915f..00000000000 --- a/doc/emacs/cmdargs.texi +++ /dev/null @@ -1,1120 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Emacs Invocation, X Resources, GNU Free Documentation License, Top -@appendix Command Line Arguments for Emacs Invocation -@cindex command line arguments -@cindex arguments (command line) -@cindex options (command line) -@cindex switches (command line) -@cindex startup (command line arguments) -@cindex invocation (command line arguments) - - Emacs supports command line arguments to request various actions -when invoking Emacs. These are for compatibility with other editors -and for sophisticated activities. We don't recommend using them for -ordinary editing (@xref{Emacs Server}, for a way to access an existing -Emacs job from the command line). - - Arguments starting with @samp{-} are @dfn{options}, and so is -@samp{+@var{linenum}}. All other arguments specify files to visit. -Emacs visits the specified files while it starts up. The last file -specified on the command line becomes the current buffer; the other -files are also visited in other buffers. As with most programs, the -special argument @samp{--} says that all subsequent arguments are file -names, not options, even if they start with @samp{-}. - - Emacs command options can specify many things, such as the size and -position of the X window Emacs uses, its colors, and so on. A few -options support advanced usage, such as running Lisp functions on files -in batch mode. The sections of this chapter describe the available -options, arranged according to their purpose. - - There are two ways of writing options: the short forms that start with -a single @samp{-}, and the long forms that start with @samp{--}. For -example, @samp{-d} is a short form and @samp{--display} is the -corresponding long form. - - The long forms with @samp{--} are easier to remember, but longer to -type. However, you don't have to spell out the whole option name; any -unambiguous abbreviation is enough. When a long option takes an -argument, you can use either a space or an equal sign to separate the -option name and the argument. Thus, you can write either -@samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}. -We recommend an equal sign because it makes the relationship clearer, -and the tables below always show an equal sign. - -@cindex initial options (command line) -@cindex action options (command line) -@vindex command-line-args - Most options specify how to initialize Emacs, or set parameters for -the Emacs session. We call them @dfn{initial options}. A few options -specify things to do, such as loading libraries or calling Lisp -functions. These are called @dfn{action options}. These and file -names together are called @dfn{action arguments}. The action -arguments are stored as a list of strings in the variable -@code{command-line-args}. (Actually, when Emacs starts up, -@code{command-line-args} contains all the arguments passed from the -command line; during initialization, the initial arguments are removed -from this list when they are processed, leaving only the action -arguments.) - -@menu -* Action Arguments:: Arguments to visit files, load libraries, - and call functions. -* Initial Options:: Arguments that take effect while starting Emacs. -* Command Example:: Examples of using command line arguments. -* Environment:: Environment variables that Emacs uses. -* Display X:: Changing the default display and using remote login. -* Font X:: Choosing a font for text, under X. -* Colors X:: Choosing display colors. -* Window Size X:: Start-up window size, under X. -* Borders X:: Internal and external borders, under X. -* Title X:: Specifying the initial frame's title. -* Icons X:: Choosing what sort of icon to use, under X. -* Misc X:: Other display options. -@end menu - -@node Action Arguments -@appendixsec Action Arguments - - Here is a table of action arguments: - -@table @samp -@item @var{file} -@opindex --file -@itemx --file=@var{file} -@opindex --find-file -@itemx --find-file=@var{file} -@opindex --visit -@itemx --visit=@var{file} -@cindex visiting files, command-line argument -@vindex inhibit-startup-buffer-menu -Visit @var{file} using @code{find-file}. @xref{Visiting}. - -When Emacs starts up, it displays the startup buffer in one window, -and the buffer visiting @var{file} in another window -(@pxref{Windows}). If you supply more than one file argument, the -displayed file is the last one specified on the command line; the -other files are visited but their buffers are not shown. - -If the startup buffer is disabled (@pxref{Entering Emacs}), then -@var{file} is visited in a single window if one file argument was -supplied; with two file arguments, Emacs displays the files in two -different windows; with more than two file argument, Emacs displays -the last file specified in one window, plus a Buffer Menu in a -different window (@pxref{Several Buffers}). To inhibit using the -Buffer Menu for this, change the variable -@code{inhibit-startup-buffer-menu} to @code{t}. - -@item +@var{linenum} @var{file} -@opindex +@var{linenum} -Visit @var{file} using @code{find-file}, then go to line number -@var{linenum} in it. - -@item +@var{linenum}:@var{columnnum} @var{file} -Visit @var{file} using @code{find-file}, then go to line number -@var{linenum} and put point at column number @var{columnnum}. - -@item -l @var{file} -@opindex -l -@itemx --load=@var{file} -@opindex --load -@cindex loading Lisp libraries, command-line argument -Load a Lisp library named @var{file} with the function @code{load}. -If @var{file} is not an absolute file name, Emacs first looks for it -in the current directory, then in the directories listed in -@code{load-path} (@pxref{Lisp Libraries}). - -@strong{Warning:} If previous command-line arguments have visited -files, the current directory is the directory of the last file -visited. - -@item -L @var{dir} -@opindex -L -@itemx --directory=@var{dir} -@opindex --directory -Add directory @var{dir} to the variable @code{load-path}. - -@item -f @var{function} -@opindex -f -@itemx --funcall=@var{function} -@opindex --funcall -@cindex call Lisp functions, command-line argument -Call Lisp function @var{function}. If it is an interactive function -(a command), it reads the arguments interactively just as if you had -called the same function with a key sequence. Otherwise, it calls the -function with no arguments. - -@item --eval=@var{expression} -@opindex --eval -@itemx --execute=@var{expression} -@opindex --execute -@cindex evaluate expression, command-line argument -Evaluate Lisp expression @var{expression}. - -@item --insert=@var{file} -@opindex --insert -@cindex insert file contents, command-line argument -Insert the contents of @var{file} into the @file{*scratch*} buffer -(@pxref{Lisp Interaction}). This is like what @kbd{M-x insert-file} -does (@pxref{Misc File Ops}). - -@item --kill -@opindex --kill -Exit from Emacs without asking for confirmation. - -@item --help -@opindex --help -Print a usage message listing all available options, then exit -successfully. - -@item --version -@opindex --version -Print Emacs version, then exit successfully. -@end table - -@node Initial Options -@appendixsec Initial Options - - The initial options specify parameters for the Emacs session. This -section describes the more general initial options; some other options -specifically related to the X Window System appear in the following -sections. - - Some initial options affect the loading of the initialization file. -Normally, Emacs first loads @file{site-start.el} if it exists, then -your own initialization file if it exists, and finally the default -initialization file @file{default.el} if it exists (@pxref{Init -File}). Certain options prevent loading of some of these files or -substitute other files for them. - -@table @samp -@item -chdir @var{directory} -@opindex -chdir -@itemx --chdir=@var{directory} -@opindex --chdir -@cindex change Emacs directory -Change to @var{directory} before doing anything else. This is mainly used -by session management in X so that Emacs starts in the same directory as it -stopped. This makes desktop saving and restoring easier. - -@item -t @var{device} -@opindex -t -@itemx --terminal=@var{device} -@opindex --terminal -@cindex device for Emacs terminal I/O -Use @var{device} as the device for terminal input and output. This -option implies @samp{--no-window-system}. - -@item -d @var{display} -@opindex -d -@itemx --display=@var{display} -@opindex --display -@cindex display for Emacs frame -Use the X Window System and use the display named @var{display} to open -the initial Emacs frame. @xref{Display X}, for more details. - -@item -nw -@opindex -nw -@itemx --no-window-system -@opindex --no-window-system -@cindex disable window system -Don't communicate directly with the window system, disregarding the -@env{DISPLAY} environment variable even if it is set. This means that -Emacs uses the terminal from which it was launched for all its display -and input. - -@cindex batch mode -@item -batch -@opindex --batch -@itemx --batch -Run Emacs in @dfn{batch mode}. Batch mode is used for running -programs written in Emacs Lisp from shell scripts, makefiles, and so -on. To invoke a Lisp program, use the @samp{-batch} option in -conjunction with one or more of @samp{-l}, @samp{-f} or @samp{--eval} -(@pxref{Action Arguments}). @xref{Command Example}, for an example. - -In batch mode, Emacs does not display the text being edited, and the -standard terminal interrupt characters such as @kbd{C-z} and @kbd{C-c} -have their usual effect. Emacs functions that normally print a -message in the echo area will print to either the standard output -stream (@code{stdout}) or the standard error stream (@code{stderr}) -instead. (To be precise, functions like @code{prin1}, @code{princ} -and @code{print} print to @code{stdout}, while @code{message} and -@code{error} print to @code{stderr}.) Functions that normally read -keyboard input from the minibuffer take their input from the -terminal's standard input stream (@code{stdin}) instead. - -@samp{--batch} implies @samp{-q} (do not load an initialization file), -but @file{site-start.el} is loaded nonetheless. It also causes Emacs -to exit after processing all the command options. In addition, it -disables auto-saving except in buffers for which auto-saving is -explicitly requested. - -@item --script @var{file} -@opindex --script -@cindex script mode -Run Emacs in batch mode, like @samp{--batch}, and then read and -execute the Lisp code in @var{file}. - -The normal use of this option is in executable script files that run -Emacs. They can start with this text on the first line - -@example -#!/usr/bin/emacs --script -@end example - -@noindent -which will invoke Emacs with @samp{--script} and supply the name of -the script file as @var{file}. Emacs Lisp then treats the @samp{#!} -on this first line as a comment delimiter. - -@item -q -@opindex -q -@itemx --no-init-file -@opindex --no-init-file -@cindex bypassing init and @file{default.el} file -@cindex init file, not loading -@cindex @file{default.el} file, not loading -Do not load any initialization file (@pxref{Init File}). When Emacs -is invoked with this option, the Customize facility does not allow -options to be saved (@pxref{Easy Customization}). This option does -not disable loading @file{site-start.el}. - -@item --no-site-file -@opindex --no-site-file -@cindex @file{site-start.el} file, not loading -Do not load @file{site-start.el} (@pxref{Init File}). The @samp{-Q} -option does this too, but other options like @samp{-q} do not. - -@item --no-site-lisp -@opindex --no-site-lisp -@cindex @file{site-start.el} file, not loading -Do not include the @file{site-lisp} directories in @code{load-path} -(@pxref{Init File}). The @samp{-Q} option does this too. - -@item --no-splash -@opindex --no-splash -@vindex inhibit-startup-screen -@cindex splash screen -@cindex startup message -Do not display a startup screen. You can also achieve this effect by -setting the variable @code{inhibit-startup-screen} to non-@code{nil} -in your initialization file (@pxref{Entering Emacs}). - -@item -Q -@opindex -Q -@itemx --quick -@opindex --quick -Start emacs with minimum customizations. This is similar to using @samp{-q}, -@samp{--no-site-file}, @samp{--no-site-lisp}, and @samp{--no-splash} -together. This also stops Emacs from processing X resources by -setting @code{inhibit-x-resources} to @code{t} (@pxref{Resources}). - -@item -daemon -@opindex -daemon -@itemx --daemon -@opindex --daemon -Start Emacs as a daemon---after Emacs starts up, it starts the Emacs -server and disconnects from the terminal without opening any frames. -You can then use the @command{emacsclient} command to connect to Emacs -for editing. @xref{Emacs Server}, for information about using Emacs -as a daemon. - -@item -daemon=@var{SERVER-NAME} -Start emacs in background as a daemon, and use @var{SERVER-NAME} as -the server name. - -@item --no-desktop -@opindex --no-desktop -Do not reload any saved desktop. @xref{Saving Emacs Sessions}. - -@item -u @var{user} -@opindex -u -@itemx --user=@var{user} -@opindex --user -@cindex load init file of another user -Load @var{user}'s initialization file instead of your -own@footnote{This option has no effect on MS-Windows.}. - -@item --debug-init -@opindex --debug-init -@cindex errors in init file -Enable the Emacs Lisp debugger for errors in the init file. -@xref{Error Debugging,, Entering the Debugger on an Error, elisp, The -GNU Emacs Lisp Reference Manual}. -@end table - -@node Command Example -@appendixsec Command Argument Example - - Here is an example of using Emacs with arguments and options. It -assumes you have a Lisp program file called @file{hack-c.el} which, when -loaded, performs some useful operation on the current buffer, expected -to be a C program. - -@example -emacs --batch foo.c -l hack-c -f save-buffer >& log -@end example - -@noindent -This says to visit @file{foo.c}, load @file{hack-c.el} (which makes -changes in the visited file), save @file{foo.c} (note that -@code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and -then exit back to the shell (because of @samp{--batch}). @samp{--batch} -also guarantees there will be no problem redirecting output to -@file{log}, because Emacs will not assume that it has a display terminal -to work with. - -@node Environment -@appendixsec Environment Variables -@cindex environment variables - - The @dfn{environment} is a feature of the operating system; it -consists of a collection of variables with names and values. Each -variable is called an @dfn{environment variable}; environment variable -names are case-sensitive, and it is conventional to use upper case -letters only. The values are all text strings. - - What makes the environment useful is that subprocesses inherit the -environment automatically from their parent process. This means you -can set up an environment variable in your login shell, and all the -programs you run (including Emacs) will automatically see it. -Subprocesses of Emacs (such as shells, compilers, and version control -programs) inherit the environment from Emacs, too. - -@findex setenv -@findex getenv -@vindex initial-environment - Inside Emacs, the command @kbd{M-x getenv} reads the name of an -environment variable, and prints its value in the echo area. @kbd{M-x -setenv} sets a variable in the Emacs environment, and @kbd{C-u M-x -setenv} removes a variable. (Environment variable substitutions with -@samp{$} work in the value just as in file names; see @ref{File Names -with $}.) The variable @code{initial-environment} stores the initial -environment inherited by Emacs. - - The way to set environment variables outside of Emacs depends on the -operating system, and especially the shell that you are using. For -example, here's how to set the environment variable @env{ORGANIZATION} -to @samp{not very much} using Bash: - -@example -export ORGANIZATION="not very much" -@end example - -@noindent -and here's how to do it in csh or tcsh: - -@example -setenv ORGANIZATION "not very much" -@end example - - When Emacs is using the X Window System, various environment -variables that control X work for Emacs as well. See the X -documentation for more information. - -@menu -* General Variables:: Environment variables that all versions of Emacs use. -* Misc Variables:: Certain system-specific variables. -* MS-Windows Registry:: An alternative to the environment on MS-Windows. -@end menu - -@node General Variables -@appendixsubsec General Variables - - Here is an alphabetical list of environment variables that have -special meanings in Emacs. Most of these variables are also used by -some other programs. Emacs does not require any of these environment -variables to be set, but it uses their values if they are set. - -@table @env -@item CDPATH -Used by the @code{cd} command to search for the directory you specify, -when you specify a relative directory name. -@item EMACSDATA -Directory for the architecture-independent files that come with Emacs. -This is used to initialize the Lisp variable @code{data-directory}. -@item EMACSDOC -Directory for the documentation string file, which is used to -initialize the Lisp variable @code{doc-directory}. -@item EMACSLOADPATH -A colon-separated list of directories@footnote{ Here and below, -whenever we say ``colon-separated list of directories'', it pertains -to Unix and GNU/Linux systems. On MS-DOS and MS-Windows, the -directories are separated by semi-colons instead, since DOS/Windows -file names might include a colon after a drive letter.} to search for -Emacs Lisp files. If set, it overrides the usual initial value of the -@code{load-path} variable (@pxref{Lisp Libraries}). -@item EMACSPATH -A colon-separated list of directories to search for executable files. -If set, Emacs uses this in addition to @env{PATH} (see below) when -initializing the variable @code{exec-path} (@pxref{Shell}). -@item EMAIL -@vindex user-mail-address@r{, initialization} -Your email address; used to initialize the Lisp variable -@code{user-mail-address}, which the Emacs mail interface puts into the -@samp{From} header of outgoing messages (@pxref{Mail Headers}). -@item ESHELL -Used for shell-mode to override the @env{SHELL} environment variable -(@pxref{Interactive Shell}). -@item HISTFILE -The name of the file that shell commands are saved in between logins. -This variable defaults to @file{~/.bash_history} if you use Bash, to -@file{~/.sh_history} if you use ksh, and to @file{~/.history} -otherwise. -@item HOME -The location of your files in the directory tree; used for -expansion of file names starting with a tilde (@file{~}). On MS-DOS, -it defaults to the directory from which Emacs was started, with -@samp{/bin} removed from the end if it was present. On Windows, the -default value of @env{HOME} is the @file{Application Data} -subdirectory of the user profile directory (normally, this is -@file{C:/Documents and Settings/@var{username}/Application Data}, -where @var{username} is your user name), though for backwards -compatibility @file{C:/} will be used instead if a @file{.emacs} file -is found there. -@item HOSTNAME -The name of the machine that Emacs is running on. -@item INCPATH -A colon-separated list of directories. Used by the @code{complete} package -to search for files. -@item INFOPATH -A colon-separated list of directories in which to search for Info files. -@item LC_ALL -@itemx LC_COLLATE -@itemx LC_CTYPE -@itemx LC_MESSAGES -@itemx LC_MONETARY -@itemx LC_NUMERIC -@itemx LC_TIME -@itemx LANG -The user's preferred locale. The locale has six categories, specified -by the environment variables @env{LC_COLLATE} for sorting, -@env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system -messages, @env{LC_MONETARY} for monetary formats, @env{LC_NUMERIC} for -numbers, and @env{LC_TIME} for dates and times. If one of these -variables is not set, the category defaults to the value of the -@env{LANG} environment variable, or to the default @samp{C} locale if -@env{LANG} is not set. But if @env{LC_ALL} is specified, it overrides -the settings of all the other locale environment variables. - -On MS-Windows, if @env{LANG} is not already set in the environment -when Emacs starts, Emacs sets it based on the system-wide default -language, which you can set in the @samp{Regional Settings} Control Panel -on some versions of MS-Windows. - -The value of the @env{LC_CTYPE} category is -matched against entries in @code{locale-language-names}, -@code{locale-charset-language-names}, and -@code{locale-preferred-coding-systems}, to select a default language -environment and coding system. @xref{Language Environments}. -@item LOGNAME -The user's login name. See also @env{USER}. -@item MAIL -The name of your system mail inbox. -@ifnottex -@item MH -Name of setup file for the mh system. @xref{Top,,MH-E,mh-e, The Emacs -Interface to MH}. -@end ifnottex -@item NAME -Your real-world name. This is used to initialize the variable -@code{user-full-name} (@pxref{Mail Headers}). -@item NNTPSERVER -The name of the news server. Used by the mh and Gnus packages. -@item ORGANIZATION -The name of the organization to which you belong. Used for setting the -`Organization:' header in your posts from the Gnus package. -@item PATH -A colon-separated list of directories containing executable files. -This is used to initialize the variable @code{exec-path} -(@pxref{Shell}). -@item PWD -If set, this should be the default directory when Emacs was started. -@item REPLYTO -If set, this specifies an initial value for the variable -@code{mail-default-reply-to} (@pxref{Mail Headers}). -@item SAVEDIR -The name of a directory in which news articles are saved by default. -Used by the Gnus package. -@item SHELL -The name of an interpreter used to parse and execute programs run from -inside Emacs. -@item SMTPSERVER -The name of the outgoing mail server. This is used to initialize the -variable @code{smtpmail-smtp-server} (@pxref{Mail Sending}). -@cindex background mode, on @command{xterm} -@item TERM -The type of the terminal that Emacs is using. This variable must be -set unless Emacs is run in batch mode. On MS-DOS, it defaults to -@samp{internal}, which specifies a built-in terminal emulation that -handles the machine's own display. -@item TERMCAP -The name of the termcap library file describing how to program the -terminal specified by @env{TERM}. This defaults to -@file{/etc/termcap}. -@item TMPDIR -@itemx TMP -@itemx TEMP -These environment variables are used to initialize the variable -@code{temporary-file-directory}, which specifies a directory in which -to put temporary files (@pxref{Backup}). Emacs tries to use -@env{TMPDIR} first; if that is unset, it tries @env{TMP}, then -@env{TEMP}, and finally @file{/tmp}. But on MS-Windows and MS-DOS, -Emacs tries @env{TEMP}, then @env{TMPDIR}, then @env{TMP}, and finally -@file{c:/temp}. - -@item TZ -This specifies the current time zone and possibly also daylight -saving time information. On MS-DOS, if @env{TZ} is not set in the -environment when Emacs starts, Emacs defines a default value as -appropriate for the country code returned by DOS. On MS-Windows, Emacs -does not use @env{TZ} at all. -@item USER -The user's login name. See also @env{LOGNAME}. On MS-DOS, this -defaults to @samp{root}. -@item VERSION_CONTROL -Used to initialize the @code{version-control} variable (@pxref{Backup Names}). -@end table - -@node Misc Variables -@appendixsubsec Miscellaneous Variables - -These variables are used only on particular configurations: - -@table @env -@item COMSPEC -On MS-DOS and MS-Windows, the name of the command interpreter to use -when invoking batch files and commands internal to the shell. On MS-DOS -this is also used to make a default value for the @env{SHELL} environment -variable. - -@item NAME -On MS-DOS, this variable defaults to the value of the @env{USER} -variable. - -@item EMACSTEST -On MS-DOS, this specifies a file to use to log the operation of the -internal terminal emulator. This feature is useful for submitting bug -reports. - -@item EMACSCOLORS -On MS-DOS, this specifies the screen colors. It is useful to set them -this way, since otherwise Emacs would display the default colors -momentarily when it starts up. - -The value of this variable should be the two-character encoding of the -foreground (the first character) and the background (the second -character) colors of the default face. Each character should be the -hexadecimal code for the desired color on a standard PC text-mode -display. For example, to get blue text on a light gray background, -specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and -7 is the code of the light gray color. - -The PC display usually supports only eight background colors. However, -Emacs switches the DOS display to a mode where all 16 colors can be used -for the background, so all four bits of the background color are -actually used. - -@item PRELOAD_WINSOCK -On MS-Windows, if you set this variable, Emacs will load and initialize -the network library at startup, instead of waiting until the first -time it is required. - -@item emacs_dir -On MS-Windows, @env{emacs_dir} is a special environment variable, which -indicates the full path of the directory in which Emacs is installed. -If Emacs is installed in the standard directory structure, it -calculates this value automatically. It is not much use setting this -variable yourself unless your installation is non-standard, since -unlike other environment variables, it will be overridden by Emacs at -startup. When setting other environment variables, such as -@env{EMACSLOADPATH}, you may find it useful to use @env{emacs_dir} -rather than hard-coding an absolute path. This allows multiple -versions of Emacs to share the same environment variable settings, and -it allows you to move the Emacs installation directory, without -changing any environment or registry settings. -@end table - -@node MS-Windows Registry -@appendixsubsec The MS-Windows System Registry -@pindex addpm, MS-Windows installation program -@cindex registry, setting environment variables (MS-Windows) - -On MS-Windows, the installation program @command{addpm.exe} adds -values for @env{emacs_dir}, @env{EMACSLOADPATH}, @env{EMACSDATA}, -@env{EMACSPATH}, @env{EMACSDOC}, @env{SHELL} and @env{TERM} to the -@file{HKEY_LOCAL_MACHINE} section of the system registry, under -@file{/Software/GNU/Emacs}. It does this because there is no standard -place to set environment variables across different versions of -Windows. Running @command{addpm.exe} is no longer strictly necessary -in recent versions of Emacs, but if you are upgrading from an older -version, running @command{addpm.exe} ensures that you do not have -older registry entries from a previous installation, which may not be -compatible with the latest version of Emacs. - -When Emacs starts, as well as checking the environment, it also checks -the System Registry for those variables and for @env{HOME}, @env{LANG} -and @env{PRELOAD_WINSOCK}. - -To determine the value of those variables, Emacs goes through the -following procedure. First, the environment is checked. If the -variable is not found there, Emacs looks for registry keys by that -name under @file{/Software/GNU/Emacs}; first in the -@file{HKEY_CURRENT_USER} section of the registry, and if not found -there, in the @file{HKEY_LOCAL_MACHINE} section. Finally, if Emacs -still cannot determine the values, compiled-in defaults are used. - -In addition to the environment variables above, you can also add many -of the settings which on X belong in the @file{.Xdefaults} file -(@pxref{X Resources}) to the @file{/Software/GNU/Emacs} registry key. - -@node Display X -@appendixsec Specifying the Display Name -@cindex display name (X Window System) -@cindex @env{DISPLAY} environment variable - - The environment variable @env{DISPLAY} tells all X clients, -including Emacs, where to display their windows. Its value is set by -default in ordinary circumstances, when you start an X server and run -jobs locally. You can specify the display yourself; one reason to do -this is if you want to log into another system and run Emacs there, -and have the window displayed at your local terminal. - - @env{DISPLAY} has the syntax -@samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the -host name of the X Window System server machine, @var{display} is an -arbitrarily-assigned number that distinguishes your server (X -terminal) from other servers on the same machine, and @var{screen} is -a field that allows an X server to control multiple terminal screens. -The period and the @var{screen} field are optional. If included, -@var{screen} is usually zero. - - For example, if your host is named @samp{glasperle} and your server is -the first (or perhaps the only) server listed in the configuration, your -@env{DISPLAY} is @samp{glasperle:0.0}. - - You can specify the display name explicitly when you run Emacs, either -by changing the @env{DISPLAY} variable, or with the option @samp{-d -@var{display}} or @samp{--display=@var{display}}. Here is an example: - -@smallexample -emacs --display=glasperle:0 & -@end smallexample - - You can inhibit the use of the X window system with the @samp{-nw} -option. Then Emacs uses its controlling text terminal for display. -@xref{Initial Options}. - - Sometimes, security arrangements prevent a program on a remote system -from displaying on your local system. In this case, trying to run Emacs -produces messages like this: - -@smallexample -Xlib: connection to "glasperle:0.0" refused by server -@end smallexample - -@noindent -You might be able to overcome this problem by using the @command{xhost} -command on the local system to give permission for access from your -remote machine. - -@node Font X -@appendixsec Font Specification Options -@cindex font name (X Window System) - -You can use the command line option @samp{-fn @var{font}} (or -@samp{--font}, which is an alias for @samp{-fn}) to specify a default -font: - -@table @samp -@item -fn @var{font} -@opindex -fn -@itemx --font=@var{font} -@opindex --font -@cindex specify default font from the command line -Use @var{font} as the default font. -@end table - -When passing a font name to Emacs on the command line, you may need to -``quote'' it, by enclosing it in quotation marks, if it contains -characters that the shell treats specially (e.g.@: spaces). For -example: - -@smallexample -emacs -fn "DejaVu Sans Mono-12" -@end smallexample - -@xref{Fonts}, for details about font names and other ways to specify -the default font. - -@node Colors X -@appendixsec Window Color Options -@cindex color of window, from command line -@cindex text colors, from command line - - You can use the following command-line options to specify the colors -to use for various parts of the Emacs display. Colors may be -specified using either color names or RGB triplets (@pxref{Colors}). - -@table @samp -@item -fg @var{color} -@opindex -fg -@itemx --foreground-color=@var{color} -@opindex --foreground-color -@cindex foreground color, command-line argument -Specify the foreground color, overriding the color specified by the -@code{default} face (@pxref{Faces}). -@item -bg @var{color} -@opindex -bg -@itemx --background-color=@var{color} -@opindex --background-color -@cindex background color, command-line argument -Specify the background color, overriding the color specified by the -@code{default} face. -@item -bd @var{color} -@opindex -bd -@itemx --border-color=@var{color} -@opindex --border-color -@cindex border color, command-line argument -Specify the color of the border of the X window. This has no effect -if Emacs is compiled with GTK+ support. -@item -cr @var{color} -@opindex -cr -@itemx --cursor-color=@var{color} -@opindex --cursor-color -@cindex cursor color, command-line argument -Specify the color of the Emacs cursor which indicates where point is. -@item -ms @var{color} -@opindex -ms -@itemx --mouse-color=@var{color} -@opindex --mouse-color -@cindex mouse pointer color, command-line argument -Specify the color for the mouse cursor when the mouse is in the Emacs window. -@item -r -@opindex -r -@itemx -rv -@opindex -rv -@itemx --reverse-video -@opindex --reverse-video -@cindex reverse video, command-line argument -Reverse video---swap the foreground and background colors. -@item --color=@var{mode} -@opindex --color -@cindex standard colors on a character terminal -@cindex override character terminal color support -Set the @dfn{color support mode} when Emacs is run on a text terminal. -This option overrides the number of supported colors that the -character terminal advertises in its @code{termcap} or @code{terminfo} -database. The parameter @var{mode} can be one of the following: -@table @samp -@item never -@itemx no -Don't use colors even if the terminal's capabilities specify color -support. -@item default -@itemx auto -Same as when @option{--color} is not used at all: Emacs detects at -startup whether the terminal supports colors, and if it does, turns on -colored display. -@item always -@itemx yes -@itemx ansi8 -Turn on the color support unconditionally, and use color commands -specified by the ANSI escape sequences for the 8 standard colors. -@item @var{num} -Use color mode for @var{num} colors. If @var{num} is -1, turn off -color support (equivalent to @samp{never}); if it is 0, use the -default color support for this terminal (equivalent to @samp{auto}); -otherwise use an appropriate standard mode for @var{num} colors. -Depending on your terminal's capabilities, Emacs might be able to turn -on a color mode for 8, 16, 88, or 256 as the value of @var{num}. If -there is no mode that supports @var{num} colors, Emacs acts as if -@var{num} were 0, i.e.@: it uses the terminal's default color support -mode. -@end table -If @var{mode} is omitted, it defaults to @var{ansi8}. -@end table - - For example, to use a coral mouse cursor and a slate blue text cursor, -enter: - -@example -emacs -ms coral -cr 'slate blue' & -@end example - - You can reverse the foreground and background colors through the -@samp{-rv} option or with the X resource @samp{reverseVideo}. - - The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on text -terminals as well as on graphical displays. - -@node Window Size X -@appendixsec Options for Window Size and Position -@cindex geometry of Emacs window -@cindex position and size of Emacs frame -@cindex width and height of Emacs frame -@cindex specifying fullscreen for Emacs frame - - Here is a list of the command-line options for specifying size and -position of the initial Emacs frame: - -@table @samp -@item -g @var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} -@opindex -g -@itemx --geometry=@var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} -@opindex --geometry -@cindex geometry, command-line argument -Specify the size @var{width} and @var{height} (measured in character -columns and lines), and positions @var{xoffset} and @var{yoffset} -(measured in pixels). The @var{width} and @var{height} parameters -apply to all frames, whereas @var{xoffset} and @var{yoffset} only to -the initial frame. - -@item -fs -@opindex -fs -@itemx --fullscreen -@opindex --fullscreen -@cindex fullscreen, command-line argument -Specify that width and height shall be the size of the screen. Normally -no window manager decorations are shown. - -@item -mm -@opindex -mm -@itemx --maximized -@opindex --maximized -@cindex maximized, command-line argument -Specify that the Emacs frame shall be maximized. This normally -means that the frame has window manager decorations. - -@item -fh -@opindex -fh -@itemx --fullheight -@opindex --fullheight -@cindex fullheight, command-line argument -Specify that the height shall be the height of the screen. - -@item -fw -@opindex -fw -@itemx --fullwidth -@opindex --fullwidth -@cindex fullwidth, command-line argument -Specify that the width shall be the width of the screen. -@end table - -@noindent -In the @samp{--geometry} option, @code{@r{@{}+-@r{@}}} means either a plus - sign or a minus sign. A plus -sign before @var{xoffset} means it is the distance from the left side of -the screen; a minus sign means it counts from the right side. A plus -sign before @var{yoffset} means it is the distance from the top of the -screen, and a minus sign there indicates the distance from the bottom. -The values @var{xoffset} and @var{yoffset} may themselves be positive or -negative, but that doesn't change their meaning, only their direction. - - Emacs uses the same units as @command{xterm} does to interpret the geometry. -The @var{width} and @var{height} are measured in characters, so a large font -creates a larger frame than a small font. (If you specify a proportional -font, Emacs uses its maximum bounds width as the width unit.) The -@var{xoffset} and @var{yoffset} are measured in pixels. - - You do not have to specify all of the fields in the geometry -specification. If you omit both @var{xoffset} and @var{yoffset}, the -window manager decides where to put the Emacs frame, possibly by -letting you place it with the mouse. For example, @samp{164x55} -specifies a window 164 columns wide, enough for two ordinary width -windows side by side, and 55 lines tall. - - The default frame width is 80 characters and the default height is -40 lines. You can omit either the width or the height or both. If -you start the geometry with an integer, Emacs interprets it as the -width. If you start with an @samp{x} followed by an integer, Emacs -interprets it as the height. Thus, @samp{81} specifies just the -width; @samp{x45} specifies just the height. - - If you start with @samp{+} or @samp{-}, that introduces an offset, -which means both sizes are omitted. Thus, @samp{-3} specifies the -@var{xoffset} only. (If you give just one offset, it is always -@var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the -@var{yoffset}, placing the frame near the bottom left of the screen. - - You can specify a default for any or all of the fields in your X -resource file (@pxref{Resources}), and then override selected fields -with a @samp{--geometry} option. - - Since the mode line and the echo area occupy the last 2 lines of the -frame, the height of the initial text window is 2 less than the height -specified in your geometry. In non-X-toolkit versions of Emacs, the -menu bar also takes one line of the specified number. But in the X -toolkit version, the menu bar is additional and does not count against -the specified height. The tool bar, if present, is also additional. - - Enabling or disabling the menu bar or tool bar alters the amount of -space available for ordinary text. Therefore, if Emacs starts up with -a tool bar (which is the default), and handles the geometry -specification assuming there is a tool bar, and then your -initialization file disables the tool bar, you will end up with a -frame geometry different from what you asked for. To get the intended -size with no tool bar, use an X resource to specify ``no tool bar'' -(@pxref{Table of Resources}); then Emacs will already know there's no -tool bar when it processes the specified geometry. - - When using one of @samp{--fullscreen}, @samp{--maximized}, @samp{--fullwidth} -or @samp{--fullheight} there may be some space around the frame -anyway. That is because Emacs rounds the sizes so they are an -even number of character heights and widths. - - Some window managers have options that can make them ignore both -program-specified and user-specified positions. If these are set, -Emacs fails to position the window correctly. - -@node Borders X -@appendixsec Internal and External Borders -@cindex borders (X Window System) - - An Emacs frame has an internal border and an external border. The -internal border is an extra strip of the background color around the -text portion of the frame. Emacs itself draws the internal border. -The external border is added by the window manager outside the frame; -depending on the window manager you use, it may contain various boxes -you can click on to move or iconify the window. - -@table @samp -@item -ib @var{width} -@opindex -ib -@itemx --internal-border=@var{width} -@opindex --internal-border -@cindex internal border width, command-line argument -Specify @var{width} as the width of the internal border (between the text -and the main border), in pixels. - -@item -bw @var{width} -@opindex -bw -@itemx --border-width=@var{width} -@opindex --border-width -@cindex main border width, command-line argument -Specify @var{width} as the width of the main border, in pixels. -@end table - - When you specify the size of the frame, that does not count the -borders. The frame's position is measured from the outside edge of the -external border. - - Use the @samp{-ib @var{n}} option to specify an internal border -@var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to -specify the width of the external border (though the window manager may -not pay attention to what you specify). The default width of the -external border is 2. - -@node Title X -@appendixsec Frame Titles - - An Emacs frame may or may not have a specified title. The frame -title, if specified, appears in window decorations and icons as the -name of the frame. If an Emacs frame has no specified title, the -default title has the form @samp{@var{invocation-name}@@@var{machine}} -(if there is only one frame) or the selected window's buffer name (if -there is more than one frame). - - You can specify a title for the initial Emacs frame with a command -line option: - -@table @samp -@item -T @var{title} -@opindex -T -@itemx --title=@var{title} -@opindex --title -@cindex frame title, command-line argument -Specify @var{title} as the title for the initial Emacs frame. -@end table - - The @samp{--name} option (@pxref{Resources}) also specifies the title -for the initial Emacs frame. - -@node Icons X -@appendixsec Icons -@cindex icons (X Window System) -@cindex minimizing a frame at startup - -@table @samp -@item -iconic -@opindex --iconic -@itemx --iconic -@cindex start iconified, command-line argument -Start Emacs in an iconified (``minimized'') state. - -@item -nbi -@opindex -nbi -@itemx --no-bitmap-icon -@opindex --no-bitmap-icon -@cindex Emacs icon, a gnu -Disable the use of the Emacs icon. -@end table - - Most window managers allow you to ``iconify'' (or ``minimize'') an -Emacs frame, hiding it from sight. Some window managers replace -iconified windows with tiny ``icons'', while others remove them -entirely from sight. The @samp{-iconic} option tells Emacs to begin -running in an iconified state, rather than showing a frame right away. -The text frame doesn't appear until you deiconify (or ``un-minimize'') -it. - - By default, Emacs uses an icon containing the Emacs logo. On -desktop environments such as Gnome, this icon is also displayed in -other contexts, e.g.@: when switching into an Emacs frame. The -@samp{-nbi} or @samp{--no-bitmap-icon} option tells Emacs to let the -window manager choose what sort of icon to use---usually just a small -rectangle containing the frame's title. - -@node Misc X -@appendixsec Other Display Options - -@table @samp -@c @item -hb -@c @opindex -hb -@c @itemx --horizontal-scroll-bars -@c @opindex --horizontal-scroll-bars -@c @c @cindex horizontal scroll bars, command-line argument -@c Enable horizontal scroll bars. Since horizontal scroll bars -@c are not yet implemented, this actually does nothing. - -@item --parent-id @var{ID} -Open Emacs as a client X window via the XEmbed protocol, with @var{ID} -as the parent X window id. Currently, this option is mainly useful -for developers. - -@item -vb -@opindex -vb -@itemx --vertical-scroll-bars -@opindex --vertical-scroll-bars -@cindex vertical scroll bars, command-line argument -Enable vertical scroll bars. - -@item -lsp @var{pixels} -@opindex -lsp -@itemx --line-spacing=@var{pixels} -@opindex --line-spacing -@cindex line spacing, command-line argument -Specify @var{pixels} as additional space to put between lines, in pixels. - -@item -nbc -@opindex -nbc -@itemx --no-blinking-cursor -@opindex --no-blinking-cursor -@cindex blinking cursor disable, command-line argument -Disable the blinking cursor on graphical displays. - -@item -D -@opindex -D -@itemx --basic-display -@opindex --basic-display -Disable the menu-bar, the tool-bar, the scroll-bars, and tool tips, -and turn off the blinking cursor. This can be useful for making a -test case that simplifies debugging of display problems. -@end table - - The @samp{--xrm} option (@pxref{Resources}) specifies additional -X resource values. diff --git a/doc/emacs/commands.texi b/doc/emacs/commands.texi deleted file mode 100644 index 9678adfe87f..00000000000 --- a/doc/emacs/commands.texi +++ /dev/null @@ -1,185 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Characters, Keys and Commands - - This chapter explains the character sets used by Emacs for input -commands, and the fundamental concepts of @dfn{keys} and -@dfn{commands}, whereby Emacs interprets your keyboard and mouse -input. -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node User Input, Keys, Screen, Top -@section Kinds of User Input -@cindex input with the keyboard -@cindex keyboard input -@cindex character set (keyboard) -@cindex @acronym{ASCII} -@cindex C- -@cindex Control - - GNU Emacs is primarily designed for use with the keyboard. While it -is possible to use the mouse to issue editing commands through the -menu bar and tool bar, that is not as efficient as using the keyboard. -Therefore, this manual mainly documents how to edit with the keyboard. - -@cindex control character - Keyboard input into Emacs is based on a heavily-extended version of -@acronym{ASCII}. Simple characters, like @samp{a}, @samp{B}, -@samp{3}, @samp{=}, and the space character (denoted as @key{SPC}), -are entered by typing the corresponding key. @dfn{Control -characters}, such as @key{RET}, @key{TAB}, @key{DEL}, @key{ESC}, -@key{F1}, @key{Home}, and @key{left}, are also entered this way, as -are certain characters found on non-English keyboards -(@pxref{International}). - -@cindex modifier keys -@cindex Control -@cindex C- -@cindex Meta -@cindex M- - Emacs also recognizes control characters that are entered using -@dfn{modifier keys}. Two commonly-used modifier keys are -@key{Control} (usually labeled @key{Ctrl}), and @key{Meta} (usually -labeled @key{Alt})@footnote{We refer to @key{Alt} as @key{Meta} for -historical reasons.}. For example, @kbd{Control-a} is entered by -holding down the @key{Ctrl} key while pressing @kbd{a}; we will refer -to this as @kbd{C-a} for short. Similarly @kbd{Meta-a}, or @kbd{M-a} -for short, is entered by holding down the @key{Alt} key and pressing -@kbd{a}. Modifier keys can also be applied to non-alphanumerical -characters, e.g. @kbd{C-@key{F1}} or @kbd{M-@key{left}}. - -@cindex @key{ESC} replacing @key{Meta} key - You can also type Meta characters using two-character sequences -starting with @key{ESC}. Thus, you can enter @kbd{M-a} by typing -@kbd{@key{ESC} a}. You can enter @kbd{C-M-a} by typing @kbd{@key{ESC} -C-a}. Unlike @key{Meta}, @key{ESC} is entered as a separate -character. You don't hold down @key{ESC} while typing the next -character; instead, press @key{ESC} and release it, then enter the -next character. This feature is useful on certain text terminals -where the @key{Meta} key does not function reliably. - -@cindex keys stolen by window manager -@cindex window manager, keys stolen by - On graphical displays, the window manager might block some keyboard -inputs, including @kbd{M-@key{TAB}}, @kbd{M-@key{SPC}}, @kbd{C-M-d} -and @kbd{C-M-l}. If you have this problem, you can either customize -your window manager to not block those keys, or ``rebind'' the -affected Emacs commands (@pxref{Customization}). - -@cindex input event - Simple characters and control characters, as well as certain -non-keyboard inputs such as mouse clicks, are collectively referred to -as @dfn{input events}. For details about how Emacs internally handles -input events, see @ref{Input Events,,, elisp, The Emacs Lisp Reference -Manual}. - -@node Keys, Commands, User Input, Top -@section Keys - - Some Emacs commands are invoked by just one input event; for -example, @kbd{C-f} moves forward one character in the buffer. Other -commands take two or more input events to invoke, such as @kbd{C-x -C-f} and @kbd{C-x 4 C-f}. - -@cindex key -@cindex key sequence -@cindex complete key -@cindex prefix key - A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one -or more input events that is meaningful as a unit. If a key sequence -invokes a command, we call it a @dfn{complete key}; for example, -@kbd{C-f}, @kbd{C-x C-f} and @kbd{C-x 4 C-f} are all complete keys. -If a key sequence isn't long enough to invoke a command, we call it a -@dfn{prefix key}; from the preceding example, we see that @kbd{C-x} -and @kbd{C-x 4} are prefix keys. Every key sequence is either a -complete key or a prefix key. - - A prefix key combines with the following input event to make a -longer key sequence. For example, @kbd{C-x} is a prefix key, so -typing @kbd{C-x} alone does not invoke a command; instead, Emacs waits -for further input (if you pause for longer than a second, it echoes -the @kbd{C-x} key to prompt for that input; @pxref{Echo Area}). -@kbd{C-x} combines with the next input event to make a two-event key -sequence, which could itself be a prefix key (such as @kbd{C-x 4}), or -a complete key (such as @kbd{C-x C-f}). There is no limit to the -length of key sequences, but in practice they are seldom longer than -three or four input events. - - You can't add input events onto a complete key. For example, -because @kbd{C-f} is a complete key, the two-event sequence @kbd{C-f -C-k} is two key sequences, not one. - - By default, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h}, -@kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x -n}, @kbd{C-x r}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x 6}, -@key{ESC}, @kbd{M-g}, and @kbd{M-o}. (@key{F1} and @key{F2} are -aliases for @kbd{C-h} and @kbd{C-x 6}.) This list is not cast in -stone; if you customize Emacs, you can make new prefix keys. You -could even eliminate some of the standard ones, though this is not -recommended for most users; for example, if you remove the prefix -definition of @kbd{C-x 4}, then @kbd{C-x 4 C-f} becomes an invalid key -sequence. @xref{Key Bindings}. - - Typing the help character (@kbd{C-h} or @key{F1}) after a prefix key -displays a list of the commands starting with that prefix. The sole -exception to this rule is @key{ESC}: @kbd{@key{ESC} C-h} is equivalent -to @kbd{C-M-h}, which does something else entirely. You can, however, -use @key{F1} to display a list of commands starting with @key{ESC}. - -@node Commands, Entering Emacs, Keys, Top -@section Keys and Commands - -@cindex binding -@cindex command - This manual is full of passages that tell you what particular keys -do. But Emacs does not assign meanings to keys directly. Instead, -Emacs assigns meanings to named @dfn{commands}, and then gives keys -their meanings by @dfn{binding} them to commands. - - Every command has a name chosen by a programmer. The name is -usually made of a few English words separated by dashes; for example, -@code{next-line} or @code{forward-word}. Internally, each command is -a special type of Lisp @dfn{function}, and the actions associated with -the command are performed by running the function. @xref{What Is a -Function,, What Is a Function, elisp, The Emacs Lisp Reference -Manual}. - - The bindings between keys and commands are recorded in tables called -@dfn{keymaps}. @xref{Keymaps}. - - When we say that ``@kbd{C-n} moves down vertically one line'' we are -glossing over a subtle distinction that is irrelevant in ordinary use, -but vital for Emacs customization. The command @code{next-line} does -a vertical move downward. @kbd{C-n} has this effect @emph{because} it -is bound to @code{next-line}. If you rebind @kbd{C-n} to the command -@code{forward-word}, @kbd{C-n} will move forward one word instead. - - In this manual, we will often speak of keys like @kbd{C-n} as -commands, even though strictly speaking the key is bound to a command. -Usually we state the name of the command which really does the work in -parentheses after mentioning the key that runs it. For example, we -will say that ``The command @kbd{C-n} (@code{next-line}) moves point -vertically down'', meaning that the command @code{next-line} moves -vertically down, and the key @kbd{C-n} is normally bound to it. - - Since we are discussing customization, we should tell you about -@dfn{variables}. Often the description of a command will say, ``To -change this, set the variable @code{mumble-foo}.'' A variable is a -name used to store a value. Most of the variables documented in this -manual are meant for customization: some command or other part of -Emacs examines the variable and behaves differently according to the -value that you set. You can ignore the information about variables -until you are interested in customizing them. Then read the basic -information on variables (@pxref{Variables}) and the information about -specific variables will make sense. - -@ifnottex -@lowersections -@end ifnottex diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi deleted file mode 100644 index d5a68249ec4..00000000000 --- a/doc/emacs/custom.texi +++ /dev/null @@ -1,2539 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Customization -@chapter Customization -@cindex customization - - This chapter describes some simple methods to customize the behavior -of Emacs. - - Apart from the methods described here, see @ref{X Resources} for -information about using X resources to customize Emacs, and see -@ref{Keyboard Macros} for information about recording and replaying -keyboard macros. Making more far-reaching and open-ended changes -involves writing Emacs Lisp code; see -@iftex -@cite{The Emacs Lisp Reference Manual}. -@end iftex -@ifnottex -@ref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp -Reference Manual}. -@end ifnottex - -@menu -* Easy Customization:: Convenient way to browse and change settings. -* Variables:: Many Emacs commands examine Emacs variables - to decide what to do; by setting variables, - you can control their functioning. -* Key Bindings:: The keymaps say what command each key runs. - By changing them, you can "redefine keys". -* Init File:: How to write common customizations in the - initialization file. -@end menu - -@node Easy Customization -@section Easy Customization Interface - -@cindex settings -@cindex user option -@cindex customizable variable - Emacs has many @dfn{settings} which you can change. Most settings -are @dfn{customizable variables} (@pxref{Variables}), which are also -called @dfn{user options}. There is a huge number of customizable -variables, controlling numerous aspects of Emacs behavior; the -variables documented in this manual are listed in @ref{Variable -Index}. A separate class of settings are the @dfn{faces}, which -determine the fonts, colors, and other attributes of text -(@pxref{Faces}). - -@findex customize -@cindex customization buffer - To browse and alter settings (both variables and faces), type -@kbd{M-x customize}. This creates a @dfn{customization buffer}, which -lets you navigate through a logically organized list of settings, edit -and set their values, and save them permanently. - -@menu -* Customization Groups:: How settings are classified. -* Browsing Custom:: Browsing and searching for settings. -* Changing a Variable:: How to edit an option's value and set the option. -* Saving Customizations:: Saving customizations for future Emacs sessions. -* Face Customization:: How to edit the attributes of a face. -* Specific Customization:: Customizing specific settings or groups. -* Custom Themes:: Collections of customization settings. -* Creating Custom Themes:: How to create a new custom theme. -@end menu - -@node Customization Groups -@subsection Customization Groups -@cindex customization groups - - Customization settings are organized into @dfn{customization -groups}. These groups are collected into bigger groups, all the way -up to a master group called @code{Emacs}. - - @kbd{M-x customize} creates a customization buffer that shows the -top-level @code{Emacs} group. It looks like this, in part: - -@c we want the buffer example to all be on one page, but unfortunately -@c that's quite a bit of text, so force all space to the bottom. -@c @page -@smallexample -@group -To apply changes, use the Save or Set buttons. -For details, see [Saving Customizations] in the [Emacs manual]. - -________________________________________ [ Search ] - - Operate on all settings in this buffer: - [ Set for current session ] [ Save for future sessions ] - [ Undo edits ] [ Reset to saved ] [ Erase customizations ] [ Exit ] - - -Emacs group: Customization of the One True Editor. - [State]: visible group members are all at standard values. - See also [Manual]. - -[Editing] : Basic text editing facilities. - -[Convenience] : Convenience features for faster editing. - -@var{more second-level groups} -@end group -@end smallexample - -@noindent -The main part of this buffer shows the @samp{Emacs} customization -group, which contains several other groups (@samp{Editing}, -@samp{Convenience}, etc.). The contents of those groups are not -listed here, only one line of documentation each. - - The @dfn{state} of the group indicates whether setting in that group -has been edited, set or saved. @xref{Changing a Variable}. - -@cindex editable fields (customization buffer) -@cindex buttons (customization buffer) -@cindex links (customization buffer) - Most of the customization buffer is read-only, but it includes some -@dfn{editable fields} that you can edit. For example, at the top of -the customization buffer is an editable field for searching for -settings (@pxref{Browsing Custom}). There are also @dfn{buttons} and -@dfn{links}, which you can activate by either clicking with the mouse, -or moving point there and typing @key{RET}. For example, the group -names like @samp{[Editing]} are links; activating one of these links -brings up the customization buffer for that group. - -@kindex TAB @r{(customization buffer)} -@kindex S-TAB @r{(customization buffer)} -@findex widget-forward -@findex widget-backward - In the customizable buffer, you can type @key{TAB} -(@code{widget-forward}) to move forward to the next button or editable -field. @kbd{S-@key{TAB}} (@code{widget-backward}) moves back to the -previous button or editable field. - -@node Browsing Custom -@subsection Browsing and Searching for Settings -@findex customize-browse - - From the top-level customization buffer created by @kbd{M-x -customize}, you can follow the links to the subgroups of the -@samp{Emacs} customization group. These subgroups may contain -settings for you to customize; they may also contain further subgroups, -dealing with yet more specialized subsystems of Emacs. As you -navigate the hierarchy of customization groups, you should find some -settings that you want to customize. - - If you are interested in customizing a particular setting or -customization group, you can go straight there with the commands -@kbd{M-x customize-option}, @kbd{M-x customize-face}, or @kbd{M-x -customize-group}. @xref{Specific Customization}. - -@vindex custom-search-field - If you don't know exactly what groups or settings you want to -customize, you can search for them using the editable search field at -the top of each customization buffer. Here, you can type in a search -term---either one or more words separated by spaces, or a regular -expression (@pxref{Regexps}). Then type @key{RET} in the field, or -activate the @samp{Search} button next to it, to switch to a -customization buffer containing groups and settings that match those -terms. Note, however, that this feature only finds groups and -settings that are loaded in the current Emacs session. - - If you don't want customization buffers to show the search field, -change the variable @code{custom-search-field} to @code{nil}. - - The command @kbd{M-x customize-apropos} is similar to using the -search field, except that it reads the search term(s) using the -minibuffer. @xref{Specific Customization}. - - @kbd{M-x customize-browse} is another way to browse the available -settings. This command creates a special customization buffer which -shows only the names of groups and settings, in a structured layout. -You can show the contents of a group, in the same buffer, by invoking -the @samp{[+]} button next to the group name. When the group contents -are shown, the button changes to @samp{[-]}; invoking that hides the -group contents again. Each group or setting in this buffer has a link -which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking -this link creates an ordinary customization buffer showing just that -group, option, or face; this is the way to change settings that you -find with @kbd{M-x customize-browse}. - -@node Changing a Variable -@subsection Changing a Variable - - Here is an example of what a variable, or user option, looks like in -the customization buffer: - -@smallexample -[Hide] Kill Ring Max: 60 - [State]: STANDARD. - Maximum length of kill ring before oldest elements are thrown away. -@end smallexample - - The first line shows that the variable is named -@code{kill-ring-max}, formatted as @samp{Kill Ring Max} for easier -viewing. Its value is @samp{60}. The button labeled @samp{[Hide]}, -if activated, hides the variable's value and state; this is useful to -avoid cluttering up the customization buffer with very long values -(for this reason, variables that have very long values may start out -hidden). If you use the @samp{[Hide]} button, it changes to -@samp{[Show Value]}, which you can activate to reveal the value and -state. On a graphical display, the @samp{[Hide]} and @samp{[Show -Value]} buttons are replaced with graphical triangles pointing -downwards and rightwards respectively. - - The line after the variable name indicates the @dfn{customization -state} of the variable: in this example, @samp{STANDARD} means you -have not changed the variable, so its value is the default one. The -@samp{[State]} button gives a menu of operations for customizing the -variable. - - Below the customization state is the documentation for the variable. -This is the same documentation that would be shown by the @kbd{C-h v} -command (@pxref{Examining}). If the documentation is more than one -line long, only one line may be shown. If so, that line ends with a -@samp{[More]} button; activate this to see the full documentation. - -@cindex user options, changing -@cindex customizing variables -@cindex variables, changing - To enter a new value for @samp{Kill Ring Max}, just move point to -the value and edit it. For example, type @kbd{M-d} to delete the -@samp{60} and type in another number. As you begin to alter the text, -the @samp{[State]} line will change: - -@smallexample -[State]: EDITED, shown value does not take effect until you - set or save it. -@end smallexample - -@noindent -Editing the value does not make it take effect right away. To do -that, you must @dfn{set} the variable by activating the @samp{[State]} -button and choosing @samp{Set for Current Session}. Then the -variable's state becomes: - -@smallexample -[State]: SET for current session only. -@end smallexample - -@noindent -You don't have to worry about specifying a value that is not valid; -the @samp{Set for Current Session} operation checks for validity and -will not install an unacceptable value. - -@kindex M-TAB @r{(customization buffer)} -@kindex C-M-i @r{(customization buffer)} -@findex widget-complete - While editing certain kinds of values, such as file names, directory -names, and Emacs command names, you can perform completion with -@kbd{C-M-i} (@code{widget-complete}), or the equivalent keys -@kbd{M-@key{TAB}} or @kbd{@key{ESC} @key{TAB}}. This behaves much -like minibuffer completion (@pxref{Completion}). - - Typing @key{RET} on an editable value field moves point forward to -the next field or button, like @key{TAB}. You can thus type @key{RET} -when you are finished editing a field, to move on to the next button -or field. To insert a newline within an editable field, use @kbd{C-o} -or @kbd{C-q C-j}. - - For some variables, there is only a fixed set of legitimate values, -and you are not allowed to edit the value directly. Instead, a -@samp{[Value Menu]} button appears before the value; activating this -button presents a choice of values. For a boolean ``on or off'' -value, the button says @samp{[Toggle]}, and flips the value. After -using the @samp{[Value Menu]} or @samp{[Toggle]} button, you must -again set the variable to make the chosen value take effect. - - Some variables have values with complex structure. For example, the -value of @code{minibuffer-frame-alist} is an association list. Here -is how it appears in the customization buffer: - -@smallexample -[Hide] Minibuffer Frame Alist: -[INS] [DEL] Parameter: width - Value: 80 -[INS] [DEL] Parameter: height - Value: 2 -[INS] - [ State ]: STANDARD. - Alist of parameters for the initial minibuffer frame. [Hide] - @r{[@dots{}more lines of documentation@dots{}]} -@end smallexample - -@noindent -In this case, each association in the list consists of two items, one -labeled @samp{Parameter} and one labeled @samp{Value}; both are -editable fields. You can delete an association from the list with the -@samp{[DEL]} button next to it. To add an association, use the -@samp{[INS]} button at the position where you want to insert it; the -very last @samp{[INS]} button inserts at the end of the list. - -@cindex saving a setting -@cindex settings, how to save - When you set a variable, the new value takes effect only in the -current Emacs session. To @dfn{save} the value for future sessions, -use the @samp{[State]} button and select the @samp{Save for Future -Sessions} operation. @xref{Saving Customizations}. - - You can also restore the variable to its standard value by using the -@samp{[State]} button and selecting the @samp{Erase Customization} -operation. There are actually four reset operations: - -@table @samp -@item Undo Edits -If you have modified but not yet set the variable, this restores the -text in the customization buffer to match the actual value. - -@item Reset to Saved -This restores the value of the variable to the last saved value, -and updates the text accordingly. - -@item Erase Customization -This sets the variable to its standard value. Any saved value that -you have is also eliminated. - -@item Set to Backup Value -This sets the variable to a previous value that was set in the -customization buffer in this session. If you customize a variable -and then reset it, which discards the customized value, -you can get the discarded value back again with this operation. -@end table - -@cindex comments on customized settings - Sometimes it is useful to record a comment about a specific -customization. Use the @samp{Add Comment} item from the -@samp{[State]} menu to create a field for entering the comment. - - Near the top of the customization buffer are two lines of buttons: - -@smallexample - [Set for Current Session] [Save for Future Sessions] - [Undo Edits] [Reset to Saved] [Erase Customization] [Exit] -@end smallexample - -@noindent -Each of the first five buttons performs the stated operation---set, -save, reset, etc.---on all the settings in the buffer that could -meaningfully be affected. They do not operate on settings that are -hidden, nor on subgroups that are hidden or not visible in the buffer. - -@kindex C-c C-c @r{(customization buffer)} -@kindex C-x C-c @r{(customization buffer)} -@findex Custom-set -@findex Custom-save - The command @kbd{C-c C-c} (@code{Custom-set}) is equivalent using to -the @samp{[Set for Current Session]} button. The command @kbd{C-x -C-s} (@code{Custom-save}) is like using the @samp{[Save for Future -Sessions]} button. - -@vindex custom-buffer-done-kill - The @samp{[Exit]} button switches out of the customization buffer, -and buries the buffer at the bottom of the buffer list. To make it -kill the customization buffer instead, change the variable -@code{custom-buffer-done-kill} to @code{t}. - -@node Saving Customizations -@subsection Saving Customizations - - In the customization buffer, you can @dfn{save} a customization -setting by choosing the @samp{Save for Future Sessions} choice from -its @samp{[State]} button. The @kbd{C-x C-s} (@code{Custom-save}) -command, or the @samp{[Save for Future Sessions]} button at the top of -the customization buffer, saves all applicable settings in the buffer. - - Saving works by writing code to a file, usually your initialization -file (@pxref{Init File}). Future Emacs sessions automatically read -this file at startup, which sets up the customizations again. - -@vindex custom-file - You can choose to save customizations somewhere other than your -initialization file. To make this work, you must add a couple of -lines of code to your initialization file, to set the variable -@code{custom-file} to the name of the desired file, and to load that -file. For example: - -@example -(setq custom-file "~/.emacs-custom.el") -(load custom-file) -@end example - - You can even specify different customization files for different -Emacs versions, like this: - -@example -(cond ((< emacs-major-version 22) - ;; @r{Emacs 21 customization.} - (setq custom-file "~/.custom-21.el")) - ((and (= emacs-major-version 22) - (< emacs-minor-version 3)) - ;; @r{Emacs 22 customization, before version 22.3.} - (setq custom-file "~/.custom-22.el")) - (t - ;; @r{Emacs version 22.3 or later.} - (setq custom-file "~/.emacs-custom.el"))) - -(load custom-file) -@end example - - If Emacs was invoked with the @option{-q} or @option{--no-init-file} -options (@pxref{Initial Options}), it will not let you save your -customizations in your initialization file. This is because saving -customizations from such a session would wipe out all the other -customizations you might have on your initialization file. - -@node Face Customization -@subsection Customizing Faces -@cindex customizing faces -@cindex faces, customizing -@cindex fonts and faces - - You can customize faces (@pxref{Faces}), which determine how Emacs -displays different types of text. Customization groups can contain -both variables and faces. - - For example, in programming language modes, source code comments are -shown with @code{font-lock-comment-face} (@pxref{Font Lock}). In a -customization buffer, that face appears like this: - -@smallexample -[Hide] Font Lock Comment Face:[sample] - [State] : STANDARD. - Font Lock mode face used to highlight comments. - [ ] Font Family: -- - [ ] Font Foundry: -- - [ ] Width: -- - [ ] Height: -- - [ ] Weight: -- - [ ] Slant: -- - [ ] Underline: -- - [ ] Overline: -- - [ ] Strike-through: -- - [ ] Box around text: -- - [ ] Inverse-video: -- - [X] Foreground: Firebrick [Choose] (sample) - [ ] Background: -- - [ ] Stipple: -- - [ ] Inherit: -- - [Hide Unused Attributes] -@end smallexample - -@noindent -The first three lines show the name, @samp{[State]} button, and -documentation for the face. Below that is a list of @dfn{face -attributes}. In front of each attribute is a checkbox. A filled -checkbox, @samp{[X]}, means that the face specifies a value for this -attribute; an empty checkbox, @samp{[ ]}, means that the face does not -specify any special value for the attribute. You can activate a -checkbox to specify or unspecify its attribute. - - Most faces only specify a few attributes (in the above example, -@code{font-lock-comment-face} only specifies the foreground color). -Emacs has a special face, @code{default}, whose attributes are all -specified; it determines the attributes left unspecified by other -faces. - - The @samp{Hide Unused Attributes} button, at the end of the -attribute list, hides the unspecified attributes of the face. When -attributes are being hidden, the button changes to @samp{[Show All -Attributes]}, which reveals the entire attribute list. The -customization buffer may start out with unspecified attributes hidden, -to avoid cluttering the interface. - - When an attribute is specified, you can change its value in the -usual ways. - - Foreground and background colors can be specified using either color -names or RGB triplets (@pxref{Colors}). You can also use the -@samp{[Choose]} button to switch to a list of color names; select a -color with @key{RET} in that buffer to put the color name in the value -field. - - Setting, saving and resetting a face work like the same operations for -variables (@pxref{Changing a Variable}). - - A face can specify different appearances for different types of -displays. For example, a face can make text red on a color display, -but use a bold font on a monochrome display. To specify multiple -appearances for a face, select @samp{For All Kinds of Displays} in the -menu you get from invoking @samp{[State]}. - -@node Specific Customization -@subsection Customizing Specific Items - -@table @kbd -@item M-x customize-option @key{RET} @var{option} @key{RET} -@itemx M-x customize-variable @key{RET} @var{option} @key{RET} -Set up a customization buffer for just one user option, @var{option}. -@item M-x customize-face @key{RET} @var{face} @key{RET} -Set up a customization buffer for just one face, @var{face}. -@item M-x customize-group @key{RET} @var{group} @key{RET} -Set up a customization buffer for just one group, @var{group}. -@item M-x customize-apropos @key{RET} @var{regexp} @key{RET} -Set up a customization buffer for all the settings and groups that -match @var{regexp}. -@item M-x customize-changed @key{RET} @var{version} @key{RET} -Set up a customization buffer with all the settings and groups -whose meaning has changed since Emacs version @var{version}. -@item M-x customize-saved -Set up a customization buffer containing all settings that you -have saved with customization buffers. -@item M-x customize-unsaved -Set up a customization buffer containing all settings that you have -set but not saved. -@end table - -@findex customize-option - If you want to customize a particular user option, type @kbd{M-x -customize-option}. This reads the variable name, and sets up the -customization buffer with just that one user option. When entering -the variable name into the minibuffer, completion is available, but -only for the names of variables that have been loaded into Emacs. - -@findex customize-face -@findex customize-group - Likewise, you can customize a specific face using @kbd{M-x -customize-face}. You can set up a customization buffer for a specific -customization group using @kbd{M-x customize-group}. - -@findex customize-apropos - @kbd{M-x customize-apropos} prompts for a search term---either one -or more words separated by spaces, or a regular expression---and sets -up a customization buffer for all @emph{loaded} settings and groups -with matching names. This is like using the search field at the top -of the customization buffer (@pxref{Customization Groups}). - -@findex customize-changed - When you upgrade to a new Emacs version, you might want to consider -customizing new settings, and settings whose meanings or default -values have changed. To do this, use @kbd{M-x customize-changed} and -specify a previous Emacs version number using the minibuffer. It -creates a customization buffer which shows all the settings and groups -whose definitions have been changed since the specified version, -loading them if necessary. - -@findex customize-saved -@findex customize-unsaved - If you change settings and then decide the change was a mistake, you -can use two commands to revisit your changes. Use @kbd{M-x -customize-saved} to customize settings that you have saved. Use -@kbd{M-x customize-unsaved} to customize settings that you have set -but not saved. - -@node Custom Themes -@subsection Custom Themes -@cindex custom themes - - @dfn{Custom themes} are collections of settings that can be enabled -or disabled as a unit. You can use Custom themes to switch easily -between various collections of settings, and to transfer such -collections from one computer to another. - - A Custom theme is stored an Emacs Lisp source file. If the name of -the Custom theme is @var{name}, the theme file is named -@file{@var{name}-theme.el}. @xref{Creating Custom Themes}, for the -format of a theme file and how to make one. - -@findex customize-themes -@vindex custom-theme-directory -@cindex color scheme - Type @kbd{M-x customize-themes} to switch to a buffer named -@file{*Custom Themes*}, which lists the Custom themes that Emacs knows -about. By default, Emacs looks for theme files in two locations: the -directory specified by the variable @code{custom-theme-directory} -(which defaults to @file{~/.emacs.d/}), and a directory named -@file{etc/themes} in your Emacs installation (see the variable -@code{data-directory}). The latter contains several Custom themes -which are distributed with Emacs, which customize Emacs's faces to fit -various color schemes. (Note, however, that Custom themes need not be -restricted to this purpose; they can be used to customize variables -too). - -@vindex custom-theme-load-path - If you want Emacs to look for Custom themes in some other directory, -add the directory name to the list variable -@code{custom-theme-load-path}. Its default value is -@code{(custom-theme-directory t)}; here, the symbol -@code{custom-theme-directory} has the special meaning of the value of -the variable @code{custom-theme-directory}, while @code{t} stands for -the built-in theme directory @file{etc/themes}. The themes listed in -the @file{*Custom Themes*} buffer are those found in the directories -specified by @code{custom-theme-load-path}. - -@kindex C-x C-s @r{(Custom Themes buffer)} - In the @file{*Custom Themes*} buffer, you can activate the checkbox -next to a Custom theme to enable or disable the theme for the current -Emacs session. When a Custom theme is enabled, all of its settings -(variables and faces) take effect in the Emacs session. To apply the -choice of theme(s) to future Emacs sessions, type @kbd{C-x C-s} -(@code{custom-theme-save}) or use the @samp{[Save Theme Settings]} -button. - -@vindex custom-safe-themes - When you first enable a Custom theme, Emacs displays the contents of -the theme file and asks if you really want to load it. Because -loading a Custom theme can execute arbitrary Lisp code, you should -only say yes if you know that the theme is safe; in that case, Emacs -offers to remember in the future that the theme is safe (this is done -by saving the theme file's SHA-256 hash to the variable -@code{custom-safe-themes}; if you want to treat all themes as safe, -change its value to @code{t}). Themes that come with Emacs (in the -@file{etc/themes} directory) are exempt from this check, and are -always considered safe. - -@vindex custom-enabled-themes - Setting or saving Custom themes actually works by customizing the -variable @code{custom-enabled-themes}. The value of this variable is -a list of Custom theme names (as Lisp symbols, e.g.@: @code{tango}). -Instead of using the @file{*Custom Themes*} buffer to set -@code{custom-enabled-themes}, you can customize the variable using the -usual customization interface, e.g.@: with @kbd{M-x customize-option}. -Note that Custom themes are not allowed to set -@code{custom-enabled-themes} themselves. - - Any customizations that you make through the customization buffer -take precedence over theme settings. This lets you easily override -individual theme settings that you disagree with. If settings from -two different themes overlap, the theme occurring earlier in -@code{custom-enabled-themes} takes precedence. In the customization -buffer, if a setting has been changed from its default by a Custom -theme, its @samp{State} display shows @samp{THEMED} instead of -@samp{STANDARD}. - -@findex load-theme -@findex enable-theme -@findex disable-theme - You can enable a specific Custom theme in the current Emacs session -by typing @kbd{M-x load-theme}. This prompts for a theme name, loads -the theme from the theme file, and enables it. If a theme file -has been loaded before, you can enable the theme without loading its -file by typing @kbd{M-x enable-theme}. To disable a Custom theme, -type @kbd{M-x disable-theme}. - -@findex describe-theme - To see a description of a Custom theme, type @kbd{?} on its line in -the @file{*Custom Themes*} buffer; or type @kbd{M-x describe-theme} -anywhere in Emacs and enter the theme name. - -@node Creating Custom Themes -@subsection Creating Custom Themes -@cindex custom themes, creating - -@findex customize-create-theme - You can define a Custom theme using an interface similar to the -customization buffer, by typing @kbd{M-x customize-create-theme}. -This switches to a buffer named @file{*Custom Theme*}. It also offers -to insert some common Emacs faces into the theme (a convenience, since -Custom themes are often used to customize faces). If you answer no, -the theme will initially contain no settings. - - Near the top of the @file{*Custom Theme*} buffer are editable fields -where you can enter the theme's name and description. The name can be -anything except @samp{user}. The description is the one that will be -shown when you invoke @kbd{M-x describe-theme} for the theme. Its -first line should be a brief one-sentence summary; in the buffer made -by @kbd{M-x customize-themes}, this sentence is displayed next to the -theme name. - - To add a new setting to the theme, use the @samp{[Insert Additional -Face]} or @samp{[Insert Additional Variable]} buttons. Each button -reads a face or variable name using the minibuffer, with completion, -and inserts a customization entry for the face or variable. You can -edit the variable values or face attributes in the same way as in a -normal customization buffer. To remove a face or variable from the -theme, uncheck the checkbox next to its name. - -@vindex custom-theme-directory - After specifying the Custom theme's faces and variables, type -@kbd{C-x C-s} (@code{custom-theme-write}) or use the buffer's -@samp{[Save Theme]} button. This saves the theme file, named -@file{@var{name}-theme.el} where @var{name} is the theme name, in the -directory named by @code{custom-theme-directory}. - - From the @file{*Custom Theme*} buffer, you can view and edit an -existing Custom theme by activating the @samp{[Visit Theme]} button -and specifying the theme name. You can also add the settings of -another theme into the buffer, using the @samp{[Merge Theme]} button. -You can import your non-theme settings into a Custom theme by using -the @samp{[Merge Theme]} button and specifying the special theme named -@samp{user}. - - A theme file is simply an Emacs Lisp source file, and loading the -Custom theme works by loading the Lisp file. Therefore, you can edit -a theme file directly instead of using the @file{*Custom Theme*} -buffer. @xref{Custom Themes,,, elisp, The Emacs Lisp Reference -Manual}, for details. - -@node Variables -@section Variables -@cindex variable - - A @dfn{variable} is a Lisp symbol which has a value. The symbol's -name is also called the @dfn{variable name}. A variable name can -contain any characters that can appear in a file, but most variable -names consist of ordinary words separated by hyphens. - - The name of the variable serves as a compact description of its -role. Most variables also have a @dfn{documentation string}, which -describes what the variable's purpose is, what kind of value it should -have, and how the value will be used. You can view this documentation -using the help command @kbd{C-h v} (@code{describe-variable}). -@xref{Examining}. - - Emacs uses many Lisp variables for internal record keeping, but the -most interesting variables for a non-programmer user are those meant -for users to change---these are called @dfn{customizable variables} or -@dfn{user options} (@pxref{Easy Customization}). In the following -sections, we will describe other aspects of Emacs variables, such as -how to set them outside Customize. - - Emacs Lisp allows any variable (with a few exceptions) to have any -kind of value. However, many variables are meaningful only if -assigned values of a certain type. For example, only numbers are -meaningful values for @code{kill-ring-max}, which specifies the -maximum length of the kill ring (@pxref{Earlier Kills}); if you give -@code{kill-ring-max} a string value, commands such as @kbd{C-y} -(@code{yank}) will signal an error. On the other hand, some variables -don't care about type; for instance, if a variable has one effect for -@code{nil} values and another effect for ``non-@code{nil}'' values, -then any value that is not the symbol @code{nil} induces the second -effect, regardless of its type (by convention, we usually use the -value @code{t}---a symbol which stands for ``true''---to specify a -non-@code{nil} value). If you set a variable using the customization -buffer, you need not worry about giving it an invalid type: the -customization buffer usually only allows you to enter meaningful -values. When in doubt, use @kbd{C-h v} (@code{describe-variable}) to -check the variable's documentation string to see kind of value it -expects (@pxref{Examining}). - -@menu -* Examining:: Examining or setting one variable's value. -* Hooks:: Hook variables let you specify programs for parts - of Emacs to run on particular occasions. -* Locals:: Per-buffer values of variables. -* File Variables:: How files can specify variable values. -* Directory Variables:: How variable values can be specified by directory. -@end menu - -@node Examining -@subsection Examining and Setting Variables -@cindex setting variables - -@table @kbd -@item C-h v @var{var} @key{RET} -Display the value and documentation of variable @var{var} -(@code{describe-variable}). -@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} -Change the value of variable @var{var} to @var{value}. -@end table - - To examine the value of a variable, use @kbd{C-h v} -(@code{describe-variable}). This reads a variable name using the -minibuffer, with completion, and displays both the value and the -documentation of the variable. For example, - -@example -C-h v fill-column @key{RET} -@end example - -@noindent -displays something like this: - -@example -fill-column is a variable defined in `C source code'. -fill-column's value is 70 -Local in buffer custom.texi; global value is 70 -Automatically becomes buffer-local when set in any fashion. - - Automatically becomes buffer-local when set in any fashion. - This variable is safe as a file local variable if its value - satisfies the predicate `integerp'. - -Documentation: -*Column beyond which automatic line-wrapping should happen. -Interactively, you can set the buffer local value using C-x f. - -You can customize this variable. -@end example - -@noindent -The line that says ``You can customize the variable'' indicates that -this variable is a user option. @kbd{C-h v} is not restricted to user -options; it allows non-customizable variables too. - -@findex set-variable - The most convenient way to set a specific customizable variable is -with @kbd{M-x set-variable}. This reads the variable name with the -minibuffer (with completion), and then reads a Lisp expression for the -new value using the minibuffer a second time (you can insert the old -value into the minibuffer for editing via @kbd{M-n}). For example, - -@example -M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} -@end example - -@noindent -sets @code{fill-column} to 75. - - @kbd{M-x set-variable} is limited to customizable variables, but you -can set any variable with a Lisp expression like this: - -@example -(setq fill-column 75) -@end example - -@noindent -To execute such an expression, type @kbd{M-:} (@code{eval-expression}) -and enter the expression in the minibuffer (@pxref{Lisp Eval}). -Alternatively, go to the @file{*scratch*} buffer, type in the -expression, and then type @kbd{C-j} (@pxref{Lisp Interaction}). - - Setting variables, like all means of customizing Emacs except where -otherwise stated, affects only the current Emacs session. The only -way to alter the variable in future sessions is to put something in -your initialization file (@pxref{Init File}). - -@node Hooks -@subsection Hooks -@cindex hook -@cindex running a hook - - @dfn{Hooks} are an important mechanism for customizing Emacs. A -hook is a Lisp variable which holds a list of functions, to be called -on some well-defined occasion. (This is called @dfn{running the -hook}.) The individual functions in the list are called the @dfn{hook -functions} of the hook. For example, the hook @code{kill-emacs-hook} -runs just before exiting Emacs (@pxref{Exiting}). - -@cindex normal hook - Most hooks are @dfn{normal hooks}. This means that when Emacs runs -the hook, it calls each hook function in turn, with no arguments. We -have made an effort to keep most hooks normal, so that you can use -them in a uniform way. Every variable whose name ends in @samp{-hook} -is a normal hook. - -@cindex abnormal hook - A few hooks are @dfn{abnormal hooks}. Their names end in -@samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What -makes these hooks abnormal is the way its functions are -called---perhaps they are given arguments, or perhaps the values they -return are used in some way. For example, -@code{find-file-not-found-functions} is abnormal because as soon as -one hook function returns a non-@code{nil} value, the rest are not -called at all (@pxref{Visiting}). The documentation of each abnormal -hook variable explains how its functions are used. - -@findex add-hook - You can set a hook variable with @code{setq} like any other Lisp -variable, but the recommended way to add a function to a hook (either -normal or abnormal) is to use @code{add-hook}, as shown by the -following examples. @xref{Hooks,,, elisp, The Emacs Lisp Reference -Manual}, for details. - - Most major modes run one or more @dfn{mode hooks} as the last step -of initialization. Mode hooks are a convenient way to customize the -behavior of individual modes; they are always normal. For example, -here's how to set up a hook to turn on Auto Fill mode in Text mode and -other modes based on Text mode: - -@example -(add-hook 'text-mode-hook 'auto-fill-mode) -@end example - -@noindent -This works by calling @code{auto-fill-mode}, which enables the minor -mode when no argument is supplied (@pxref{Minor Modes}). Next, -suppose you don't want Auto Fill mode turned on in La@TeX{} mode, -which is one of the modes based on Text mode. You can do this with -the following additional line: - -@example -(add-hook 'latex-mode-hook (lambda () (auto-fill-mode -1))) -@end example - -@noindent -Here we have used the special macro @code{lambda} to construct an -anonymous function (@pxref{Lambda Expressions,,, elisp, The Emacs Lisp -Reference Manual}), which calls @code{auto-fill-mode} with an argument -of @code{-1} to disable the minor mode. Because La@TeX{} mode runs -@code{latex-mode-hook} after running @code{text-mode-hook}, the result -leaves Auto Fill mode disabled. - - Here is a more complex example, showing how to use a hook to -customize the indentation of C code: - -@example -@group -(setq my-c-style - '((c-comment-only-line-offset . 4) -@end group -@group - (c-cleanup-list . (scope-operator - empty-defun-braces - defun-close-semi)))) -@end group - -@group -(add-hook 'c-mode-common-hook - (lambda () (c-add-style "my-style" my-c-style t))) -@end group -@end example - -@cindex Prog mode -@cindex program editing - Major mode hooks also apply to other major modes @dfn{derived} from -the original mode (@pxref{Derived Modes,,, elisp, The Emacs Lisp -Reference Manual}). For instance, HTML mode is derived from Text mode -(@pxref{HTML Mode}); when HTML mode is enabled, it runs -@code{text-mode-hook} before running @code{html-mode-hook}. This -provides a convenient way to use a single hook to affect several -related modes. In particular, if you want to apply a hook function to -any programming language mode, add it to @code{prog-mode-hook}; Prog -mode is a major mode that does little else than to let other major -modes inherit from it, exactly for this purpose. - - It is best to design your hook functions so that the order in which -they are executed does not matter. Any dependence on the order is -asking for trouble. However, the order is predictable: the hook -functions are executed in the order they appear in the hook. - -@findex remove-hook - If you play with adding various different versions of a hook -function by calling @code{add-hook} over and over, remember that all -the versions you added will remain in the hook variable together. You -can clear out individual functions by calling @code{remove-hook}, or -do @code{(setq @var{hook-variable} nil)} to remove everything. - -@cindex buffer-local hooks - If the hook variable is buffer-local, the buffer-local variable will -be used instead of the global variable. However, if the buffer-local -variable contains the element @code{t}, the global hook variable will -be run as well. - -@node Locals -@subsection Local Variables - -@table @kbd -@item M-x make-local-variable @key{RET} @var{var} @key{RET} -Make variable @var{var} have a local value in the current buffer. -@item M-x kill-local-variable @key{RET} @var{var} @key{RET} -Make variable @var{var} use its global value in the current buffer. -@item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET} -Mark variable @var{var} so that setting it will make it local to the -buffer that is current at that time. -@end table - -@cindex local variables - Almost any variable can be made @dfn{local} to a specific Emacs -buffer. This means that its value in that buffer is independent of its -value in other buffers. A few variables are always local in every -buffer. Every other Emacs variable has a @dfn{global} value which is in -effect in all buffers that have not made the variable local. - -@findex make-local-variable - @kbd{M-x make-local-variable} reads the name of a variable and makes -it local to the current buffer. Changing its value subsequently in -this buffer will not affect others, and changes in its global value -will not affect this buffer. - -@findex make-variable-buffer-local -@cindex per-buffer variables - @kbd{M-x make-variable-buffer-local} marks a variable so it will -become local automatically whenever it is set. More precisely, once a -variable has been marked in this way, the usual ways of setting the -variable automatically do @code{make-local-variable} first. We call -such variables @dfn{per-buffer} variables. Many variables in Emacs -are normally per-buffer; the variable's document string tells you when -this is so. A per-buffer variable's global value is normally never -effective in any buffer, but it still has a meaning: it is the initial -value of the variable for each new buffer. - - Major modes (@pxref{Major Modes}) always make variables local to the -buffer before setting the variables. This is why changing major modes -in one buffer has no effect on other buffers. Minor modes also work -by setting variables---normally, each minor mode has one controlling -variable which is non-@code{nil} when the mode is enabled -(@pxref{Minor Modes}). For many minor modes, the controlling variable -is per buffer, and thus always buffer-local. Otherwise, you can make -it local in a specific buffer like any other variable. - - A few variables cannot be local to a buffer because they are always -local to each display instead (@pxref{Multiple Displays}). If you try to -make one of these variables buffer-local, you'll get an error message. - -@findex kill-local-variable - @kbd{M-x kill-local-variable} makes a specified variable cease to be -local to the current buffer. The global value of the variable -henceforth is in effect in this buffer. Setting the major mode kills -all the local variables of the buffer except for a few variables -specially marked as @dfn{permanent locals}. - -@findex setq-default - To set the global value of a variable, regardless of whether the -variable has a local value in the current buffer, you can use the Lisp -construct @code{setq-default}. This construct is used just like -@code{setq}, but it sets variables' global values instead of their local -values (if any). When the current buffer does have a local value, the -new global value may not be visible until you switch to another buffer. -Here is an example: - -@example -(setq-default fill-column 75) -@end example - -@noindent -@code{setq-default} is the only way to set the global value of a variable -that has been marked with @code{make-variable-buffer-local}. - -@findex default-value - Lisp programs can use @code{default-value} to look at a variable's -default value. This function takes a symbol as argument and returns its -default value. The argument is evaluated; usually you must quote it -explicitly. For example, here's how to obtain the default value of -@code{fill-column}: - -@example -(default-value 'fill-column) -@end example - -@node File Variables -@subsection Local Variables in Files -@cindex local variables in files -@cindex file local variables - - A file can specify local variable values to use when editing the -file with Emacs. Visiting the file checks for local variable -specifications; it automatically makes these variables local to the -buffer, and sets them to the values specified in the file. - -@menu -* Specifying File Variables:: Specifying file local variables. -* Safe File Variables:: Making sure file local variables are safe. -@end menu - -@node Specifying File Variables -@subsubsection Specifying File Variables - - There are two ways to specify file local variable values: in the first -line, or with a local variables list. Here's how to specify them in the -first line: - -@example --*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*- -@end example - -@noindent -You can specify any number of variable/value pairs in this way, each -pair with a colon and semicolon. The special variable/value pair -@code{mode: @var{modename};}, if present, specifies a major mode. The -@var{value}s are used literally, and not evaluated. - -@findex add-file-local-variable-prop-line -@findex delete-file-local-variable-prop-line -@findex copy-dir-locals-to-file-locals-prop-line - You can use the command @kbd{M-x add-file-local-variable-prop-line} -instead of adding entries by hand. It prompts for -a variable and value, and adds them to the first line in the -appropriate way. @kbd{M-x delete-file-local-variable-prop-line} -prompts for a variable, and deletes its entry from the line. @kbd{M-x -copy-dir-locals-to-file-locals-prop-line} copies directory-local -variables to the first line (@pxref{Directory Variables}). - - Here is an example first line that specifies Lisp mode and sets two -variables with numeric values: - -@smallexample -;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*- -@end smallexample - -@noindent -Aside from @code{mode}, other keywords that have special meanings as -file variables are @code{coding}, @code{unibyte}, and @code{eval}. -These are described below. - -@cindex shell scripts, and local file variables -@cindex man pages, and local file variables - In shell scripts, the first line is used to identify the script -interpreter, so you cannot put any local variables there. To -accommodate this, Emacs looks for local variable specifications in the -@emph{second} line if the first line specifies an interpreter. The -same is true for man pages which start with the magic string -@samp{'\"} to specify a list of troff preprocessors (not all do, -however). - - Apart from using a @samp{-*-} line, you can define file local -variables using a @dfn{local variables list} near the end of the file. -The start of the local variables list should be no more than 3000 -characters from the end of the file, and must be on the last page if -the file is divided into pages. - - If a file has both a local variables list and a @samp{-*-} line, -Emacs processes @emph{everything} in the @samp{-*-} line first, and -@emph{everything} in the local variables list afterward. The exception -to this is a major mode specification. Emacs applies this first, -wherever it appears, since most major modes kill all local variables as -part of their initialization. - - A local variables list starts with a line containing the string -@samp{Local Variables:}, and ends with a line containing the string -@samp{End:}. In between come the variable names and values, one set -per line, like this: - -@example -/* Local Variables: */ -/* mode: c */ -/* comment-column: 0 */ -/* End: */ -@end example - -@noindent -In this example, each line starts with the prefix @samp{/*} and ends -with the suffix @samp{*/}. Emacs recognizes the prefix and suffix by -finding them surrounding the magic string @samp{Local Variables:}, on -the first line of the list; it then automatically discards them from -the other lines of the list. The usual reason for using a prefix -and/or suffix is to embed the local variables list in a comment, so it -won't confuse other programs that the file is intended for. The -example above is for the C programming language, where comments start -with @samp{/*} and end with @samp{*/}. - -@findex add-file-local-variable -@findex delete-file-local-variable -@findex copy-dir-locals-to-file-locals - Instead of typing in the local variables list directly, you can use -the command @kbd{M-x add-file-local-variable}. This prompts for a -variable and value, and adds them to the list, adding the @samp{Local -Variables:} string and start and end markers as necessary. The -command @kbd{M-x delete-file-local-variable} deletes a variable from -the list. @kbd{M-x copy-dir-locals-to-file-locals} copies -directory-local variables to the list (@pxref{Directory Variables}). - - As with the @samp{-*-} line, the variables in a local variables list -are used literally, and are not evaluated first. If you want to split -a long string value across multiple lines of the file, you can use -backslash-newline, which is ignored in Lisp string constants; you -should put the prefix and suffix on each line, even lines that start -or end within the string, as they will be stripped off when processing -the list. Here is an example: - -@example -# Local Variables: -# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \ -# -Dmumble=blaah" -# End: -@end example - - Some ``variable names'' have special meanings in a local variables -list: - -@itemize -@item -@code{mode} enables the specified major mode. - -@item -@code{eval} evaluates the specified Lisp expression (the value -returned by that expression is ignored). - -@item -@code{coding} specifies the coding system for character code -conversion of this file. @xref{Coding Systems}. - -@item -@code{unibyte} says to load or compile a file of Emacs Lisp in unibyte -mode, if the value is @code{t}. @xref{Disabling Multibyte}. -@end itemize - -@noindent -These four keywords are not really variables; setting them in any -other context has no special meaning. - - Do not use the @code{mode} keyword for minor modes. To enable or -disable a minor mode in a local variables list, use the @code{eval} -keyword with a Lisp expression that runs the mode command -(@pxref{Minor Modes}). For example, the following local variables -list enables Eldoc mode (@pxref{Lisp Doc}) by calling -@code{eldoc-mode} with no argument (calling it with an argument of 1 -would do the same), and disables Font Lock mode (@pxref{Font Lock}) by -calling @code{font-lock-mode} with an argument of -1. - -@example -;; Local Variables: -;; eval: (eldoc-mode) -;; eval: (font-lock-mode -1) -;; End: -@end example - -@noindent -Note, however, that it is often a mistake to specify minor modes this -way. Minor modes represent individual user preferences, and it may be -inappropriate to impose your preferences on another user who might -edit the file. If you wish to automatically enable or disable a minor -mode in a situation-dependent way, it is often better to do it in a -major mode hook (@pxref{Hooks}). - - Use the command @kbd{M-x normal-mode} to reset the local variables -and major mode of a buffer according to the file name and contents, -including the local variables list if any. @xref{Choosing Modes}. - -@node Safe File Variables -@subsubsection Safety of File Variables - - File-local variables can be dangerous; when you visit someone else's -file, there's no telling what its local variables list could do to -your Emacs. Improper values of the @code{eval} ``variable'', and -other variables such as @code{load-path}, could execute Lisp code you -didn't intend to run. - - Therefore, whenever Emacs encounters file local variable values that -are not known to be safe, it displays the file's entire local -variables list, and asks you for confirmation before setting them. -You can type @kbd{y} or @key{SPC} to put the local variables list into -effect, or @kbd{n} to ignore it. When Emacs is run in batch mode -(@pxref{Initial Options}), it can't really ask you, so it assumes the -answer @kbd{n}. - - Emacs normally recognizes certain variable/value pairs as safe. -For instance, it is safe to give @code{comment-column} or -@code{fill-column} any integer value. If a file specifies only -known-safe variable/value pairs, Emacs does not ask for confirmation -before setting them. Otherwise, you can tell Emacs to record all the -variable/value pairs in this file as safe, by typing @kbd{!} at the -confirmation prompt. When Emacs encounters these variable/value pairs -subsequently, in the same file or others, it will assume they are -safe. - -@vindex safe-local-variable-values -@cindex risky variable - Some variables, such as @code{load-path}, are considered -particularly @dfn{risky}: there is seldom any reason to specify them -as local variables, and changing them can be dangerous. If a file -contains only risky local variables, Emacs neither offers nor accepts -@kbd{!} as input at the confirmation prompt. If some of the local -variables in a file are risky, and some are only potentially unsafe, you -can enter @kbd{!} at the prompt. It applies all the variables, but only -marks the non-risky ones as safe for the future. If you really want to -record safe values for risky variables, do it directly by customizing -@samp{safe-local-variable-values} (@pxref{Easy Customization}). - -@vindex enable-local-variables - The variable @code{enable-local-variables} allows you to change the -way Emacs processes local variables. Its default value is @code{t}, -which specifies the behavior described above. If it is @code{nil}, -Emacs simply ignores all file local variables. @code{:safe} means use -only the safe values and ignore the rest. Any other value says to -query you about each file that has local variables, without trying to -determine whether the values are known to be safe. - -@vindex enable-local-eval -@vindex safe-local-eval-forms - The variable @code{enable-local-eval} controls whether Emacs -processes @code{eval} variables. The three possibilities for the -variable's value are @code{t}, @code{nil}, and anything else, just as -for @code{enable-local-variables}. The default is @code{maybe}, which -is neither @code{t} nor @code{nil}, so normally Emacs does ask for -confirmation about processing @code{eval} variables. - - As an exception, Emacs never asks for confirmation to evaluate any -@code{eval} form if that form occurs within the variable -@code{safe-local-eval-forms}. - -@node Directory Variables -@subsection Per-Directory Local Variables -@cindex local variables, for all files in a directory -@cindex directory-local variables -@cindex per-directory local variables - - Sometimes, you may wish to define the same set of local variables to -all the files in a certain directory and its subdirectories, such as -the directory tree of a large software project. This can be -accomplished with @dfn{directory-local variables}. - -@cindex @file{.dir-locals.el} file - The usual way to define directory-local variables is to put a file -named @file{.dir-locals.el}@footnote{ On MS-DOS, the name of this file -should be @file{_dir-locals.el}, due to limitations of the DOS -filesystems. If the filesystem is limited to 8+3 file names, the name -of the file will be truncated by the OS to @file{_dir-loc.el}. } in a -directory. Whenever Emacs visits any file in that directory or any of -its subdirectories, it will apply the directory-local variables -specified in @file{.dir-locals.el}, as though they had been defined as -file-local variables for that file (@pxref{File Variables}). Emacs -searches for @file{.dir-locals.el} starting in the directory of the -visited file, and moving up the directory tree. To avoid slowdown, -this search is skipped for remote files. - - The @file{.dir-locals.el} file should hold a specially-constructed -list, which maps major mode names (symbols) to alists -(@pxref{Association Lists,,, elisp, The Emacs Lisp Reference Manual}). -Each alist entry consists of a variable name and the directory-local -value to assign to that variable, when the specified major mode is -enabled. Instead of a mode name, you can specify @samp{nil}, which -means that the alist applies to any mode; or you can specify a -subdirectory name (a string), in which case the alist applies to all -files in that subdirectory. - - Here's an example of a @file{.dir-locals.el} file: - -@example -((nil . ((indent-tabs-mode . t) - (fill-column . 80))) - (c-mode . ((c-file-style . "BSD"))) - (subdirs . nil))) - ("src/imported" - . ((nil . ((change-log-default-name - . "ChangeLog.local")))))) -@end example - -@noindent -This sets @samp{indent-tabs-mode} and @code{fill-column} for any file -in the directory tree, and the indentation style for any C source -file. The special @code{subdirs} element is not a variable, but a -special keyword which indicates that the C mode settings are only to -be applied in the current directory, not in any subdirectories. -Finally, it specifies a different @file{ChangeLog} file name for any -file in the @file{src/imported} subdirectory. - -@findex add-dir-local-variable -@findex delete-dir-local-variable -@findex copy-file-locals-to-dir-locals - Instead of editing the @file{.dir-locals.el} file by hand, you can -use the command @kbd{M-x add-dir-local-variable}. This prompts for a -mode or subdirectory name, and for variable and value, and adds the -entry defining the directory-local variable. @kbd{M-x -delete-dir-local-variable} deletes an entry. @kbd{M-x -copy-file-locals-to-dir-locals} copies the file-local variables in the -current file into @file{.dir-locals.el}. - -@findex dir-locals-set-class-variables -@findex dir-locals-set-directory-class - Another method of specifying directory-local variables is to define -a group of variables/value pairs in a @dfn{directory class}, using the -@code{dir-locals-set-class-variables} function; then, tell Emacs which -directories correspond to the class by using the -@code{dir-locals-set-directory-class} function. These function calls -normally go in your initialization file (@pxref{Init File}). This -method is useful when you can't put @file{.dir-locals.el} in a -directory for some reason. For example, you could apply settings to -an unwritable directory this way: - -@example -(dir-locals-set-class-variables 'unwritable-directory - '((nil . ((some-useful-setting . value))))) - -(dir-locals-set-directory-class - "/usr/include/" 'unwritable-directory) -@end example - - If a variable has both a directory-local and file-local value -specified, the file-local value takes effect. Unsafe directory-local -variables are handled in the same way as unsafe file-local variables -(@pxref{Safe File Variables}). - - Directory-local variables also take effect in certain buffers that -do not visit a file directly but perform work within a directory, such -as Dired buffers (@pxref{Dired}). - -@node Key Bindings -@section Customizing Key Bindings -@cindex key bindings - - This section describes @dfn{key bindings}, which map keys to -commands, and @dfn{keymaps}, which record key bindings. It also -explains how to customize key bindings, which is done by editing your -init file (@pxref{Init Rebinding}). - -@menu -* Keymaps:: Generalities. The global keymap. -* Prefix Keymaps:: Keymaps for prefix keys. -* Local Keymaps:: Major and minor modes have their own keymaps. -* Minibuffer Maps:: The minibuffer uses its own local keymaps. -* Rebinding:: How to redefine one key's meaning conveniently. -* Init Rebinding:: Rebinding keys with your initialization file. -* Modifier Keys:: Using modifier keys in key bindings. -* Function Keys:: Rebinding terminal function keys. -* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. -* Mouse Buttons:: Rebinding mouse buttons in Emacs. -* Disabling:: Disabling a command means confirmation is required - before it can be executed. This is done to protect - beginners from surprises. -@end menu - -@node Keymaps -@subsection Keymaps -@cindex keymap - - As described in @ref{Commands}, each Emacs command is a Lisp -function whose definition provides for interactive use. Like every -Lisp function, a command has a function name, which usually consists -of lower-case letters and hyphens. - - A @dfn{key sequence} (@dfn{key}, for short) is a sequence of -@dfn{input events} that have a meaning as a unit. Input events -include characters, function keys and mouse buttons---all the inputs -that you can send to the computer. A key sequence gets its meaning -from its @dfn{binding}, which says what command it runs. - - The bindings between key sequences and command functions are -recorded in data structures called @dfn{keymaps}. Emacs has many of -these, each used on particular occasions. - -@cindex global keymap - The @dfn{global} keymap is the most important keymap because it is -always in effect. The global keymap defines keys for Fundamental mode -(@pxref{Major Modes}); most of these definitions are common to most or -all major modes. Each major or minor mode can have its own keymap -which overrides the global definitions of some keys. - - For example, a self-inserting character such as @kbd{g} is -self-inserting because the global keymap binds it to the command -@code{self-insert-command}. The standard Emacs editing characters -such as @kbd{C-a} also get their standard meanings from the global -keymap. Commands to rebind keys, such as @kbd{M-x global-set-key}, -work by storing the new binding in the proper place in the global map -(@pxref{Rebinding}). - -@cindex function key - Most modern keyboards have function keys as well as character keys. -Function keys send input events just as character keys do, and keymaps -can have bindings for them. Key sequences can mix function keys and -characters. For example, if your keyboard has a @key{Home} function -key, Emacs can recognize key sequences like @kbd{C-x @key{Home}}. You -can even mix mouse events with keyboard events, such as -@kbd{S-down-mouse-1}. - - On text terminals, typing a function key actually sends the computer -a sequence of characters; the precise details of the sequence depends -on the function key and on the terminal type. (Often the sequence -starts with @kbd{@key{ESC} [}.) If Emacs understands your terminal -type properly, it automatically handles such sequences as single input -events. - -@node Prefix Keymaps -@subsection Prefix Keymaps - - Internally, Emacs records only single events in each keymap. -Interpreting a key sequence of multiple events involves a chain of -keymaps: the first keymap gives a definition for the first event, -which is another keymap, which is used to look up the second event in -the sequence, and so on. Thus, a prefix key such as @kbd{C-x} or -@key{ESC} has its own keymap, which holds the definition for the event -that immediately follows that prefix. - - The definition of a prefix key is usually the keymap to use for -looking up the following event. The definition can also be a Lisp -symbol whose function definition is the following keymap; the effect is -the same, but it provides a command name for the prefix key that can be -used as a description of what the prefix key is for. Thus, the binding -of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function -definition is the keymap for @kbd{C-x} commands. The definitions of -@kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in -the global map, so these prefix keys are always available. - - Aside from ordinary prefix keys, there is a fictitious ``prefix key'' -which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp -Reference Manual}, for special information about menu bar key bindings. -Mouse button events that invoke pop-up menus are also prefix keys; see -@ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more -details. - - Some prefix keymaps are stored in variables with names: - -@itemize @bullet -@item -@vindex ctl-x-map -@code{ctl-x-map} is the variable name for the map used for characters that -follow @kbd{C-x}. -@item -@vindex help-map -@code{help-map} is for characters that follow @kbd{C-h}. -@item -@vindex esc-map -@code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta -characters are actually defined by this map. -@item -@vindex ctl-x-4-map -@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}. -@item -@vindex mode-specific-map -@code{mode-specific-map} is for characters that follow @kbd{C-c}. -@end itemize - -@node Local Keymaps -@subsection Local Keymaps - -@cindex local keymap -@cindex minor mode keymap - So far, we have explained the ins and outs of the global map. Major -modes customize Emacs by providing their own key bindings in -@dfn{local keymaps}. For example, C mode overrides @key{TAB} to make -it indent the current line for C code. Minor modes can also have -local keymaps; whenever a minor mode is in effect, the definitions in -its keymap override both the major mode's local keymap and the global -keymap. In addition, portions of text in the buffer can specify their -own keymaps, which override all other keymaps. - - A local keymap can redefine a key as a prefix key by defining it as -a prefix keymap. If the key is also defined globally as a prefix, its -local and global definitions (both keymaps) effectively combine: both -definitions are used to look up the event that follows the prefix key. -For example, if a local keymap defines @kbd{C-c} as a prefix keymap, -and that keymap defines @kbd{C-z} as a command, this provides a local -meaning for @kbd{C-c C-z}. This does not affect other sequences that -start with @kbd{C-c}; if those sequences don't have their own local -bindings, their global bindings remain in effect. - - Another way to think of this is that Emacs handles a multi-event key -sequence by looking in several keymaps, one by one, for a binding of the -whole key sequence. First it checks the minor mode keymaps for minor -modes that are enabled, then it checks the major mode's keymap, and then -it checks the global keymap. This is not precisely how key lookup -works, but it's good enough for understanding the results in ordinary -circumstances. - -@node Minibuffer Maps -@subsection Minibuffer Keymaps - -@cindex minibuffer keymaps -@vindex minibuffer-local-map -@vindex minibuffer-local-ns-map -@vindex minibuffer-local-completion-map -@vindex minibuffer-local-must-match-map -@vindex minibuffer-local-filename-completion-map -@vindex minibuffer-local-filename-must-match-map - The minibuffer has its own set of local keymaps; they contain various -completion and exit commands. - -@itemize @bullet -@item -@code{minibuffer-local-map} is used for ordinary input (no completion). -@item -@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits -just like @key{RET}. -@item -@code{minibuffer-local-completion-map} is for permissive completion. -@item -@code{minibuffer-local-must-match-map} is for strict completion and -for cautious completion. -@item -@code{minibuffer-local-filename-completion-map} and -@code{minibuffer-local-filename-must-match-map} are like the two -previous ones, but they are specifically for file name completion. -They do not bind @key{SPC}. -@end itemize - -@node Rebinding -@subsection Changing Key Bindings Interactively -@cindex key rebinding, this session -@cindex redefining keys, this session -@cindex binding keys - - The way to redefine an Emacs key is to change its entry in a keymap. -You can change the global keymap, in which case the change is -effective in all major modes (except those that have their own -overriding local bindings for the same key). Or you can change a -local keymap, which affects all buffers using the same major mode. - - In this section, we describe how to rebind keys for the present -Emacs session. @xref{Init Rebinding}, for a description of how to -make key rebindings affect future Emacs sessions. - -@findex global-set-key -@findex local-set-key -@findex global-unset-key -@findex local-unset-key -@table @kbd -@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET} -Define @var{key} globally to run @var{cmd}. -@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET} -Define @var{key} locally (in the major mode now in effect) to run -@var{cmd}. -@item M-x global-unset-key @key{RET} @var{key} -Make @var{key} undefined in the global map. -@item M-x local-unset-key @key{RET} @var{key} -Make @var{key} undefined locally (in the major mode now in effect). -@end table - - For example, the following binds @kbd{C-z} to the @code{shell} -command (@pxref{Interactive Shell}), replacing the normal global -definition of @kbd{C-z}: - -@example -M-x global-set-key @key{RET} C-z shell @key{RET} -@end example - -@noindent -The @code{global-set-key} command reads the command name after the -key. After you press the key, a message like this appears so that you -can confirm that you are binding the key you want: - -@example -Set key C-z to command: -@end example - - You can redefine function keys and mouse events in the same way; just -type the function key or click the mouse when it's time to specify the -key to rebind. - - You can rebind a key that contains more than one event in the same -way. Emacs keeps reading the key to rebind until it is a complete key -(that is, not a prefix key). Thus, if you type @kbd{C-f} for -@var{key}, that's the end; it enters the minibuffer immediately to -read @var{cmd}. But if you type @kbd{C-x}, since that's a prefix, it -reads another character; if that is @kbd{4}, another prefix character, -it reads one more character, and so on. For example, - -@example -M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET} -@end example - -@noindent -redefines @kbd{C-x 4 $} to run the (fictitious) command -@code{spell-other-window}. - - You can remove the global definition of a key with -@code{global-unset-key}. This makes the key @dfn{undefined}; if you -type it, Emacs will just beep. Similarly, @code{local-unset-key} makes -a key undefined in the current major mode keymap, which makes the global -definition (or lack of one) come back into effect in that major mode. - - If you have redefined (or undefined) a key and you subsequently wish -to retract the change, undefining the key will not do the job---you need -to redefine the key with its standard definition. To find the name of -the standard definition of a key, go to a Fundamental mode buffer in a -fresh Emacs and use @kbd{C-h c}. The documentation of keys in this -manual also lists their command names. - - If you want to prevent yourself from invoking a command by mistake, it -is better to disable the command than to undefine the key. A disabled -command is less work to invoke when you really want to. -@xref{Disabling}. - -@node Init Rebinding -@subsection Rebinding Keys in Your Init File -@cindex rebinding major mode keys -@c This node is referenced in the tutorial. When renaming or deleting -@c it, the tutorial needs to be adjusted. (TUTORIAL.de) - - If you have a set of key bindings that you like to use all the time, -you can specify them in your initialization file by writing Lisp code. -@xref{Init File}, for a description of the initialization file. - -@findex kbd - There are several ways to write a key binding using Lisp. The -simplest is to use the @code{kbd} macro, which converts a textual -representation of a key sequence---similar to how we have written key -sequences in this manual---into a form that can be passed as an -argument to @code{global-set-key}. For example, here's how to bind -@kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}): - -@example -(global-set-key (kbd "C-z") 'shell) -@end example - -@noindent -The single-quote before the command name, @code{shell}, marks it as a -constant symbol rather than a variable. If you omit the quote, Emacs -would try to evaluate @code{shell} as a variable. This probably -causes an error; it certainly isn't what you want. - - Here are some additional examples, including binding function keys -and mouse events: - -@example -(global-set-key (kbd "C-c y") 'clipboard-yank) -(global-set-key (kbd "C-M-q") 'query-replace) -(global-set-key (kbd "") 'flyspell-mode) -(global-set-key (kbd "C-") 'linum-mode) -(global-set-key (kbd "C-") 'forward-sentence) -(global-set-key (kbd "") 'mouse-save-then-kill) -@end example - - Instead of using the @code{kbd} macro, you can use a Lisp string or -vector to specify the key sequence. Using a string is simpler, but -only works for @acronym{ASCII} characters and Meta-modified -@acronym{ASCII} characters. For example, here's how to bind @kbd{C-x -M-l} to @code{make-symbolic-link} (@pxref{Misc File Ops}): - -@example -(global-set-key "\C-x\M-l" 'make-symbolic-link) -@end example - - To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the string, -use the Emacs Lisp escape sequences @samp{\t}, @samp{\r}, @samp{\e}, -and @samp{\d} respectively. Here is an example which binds @kbd{C-x -@key{TAB}} to @code{indent-rigidly} (@pxref{Indentation}): - -@example -(global-set-key "\C-x\t" 'indent-rigidly) -@end example - - When the key sequence includes function keys or mouse button events, -or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, -you can use a vector to specify the key sequence. Each element in the -vector stands for an input event; the elements are separated by spaces -and surrounded by a pair of square brackets. If a vector element is a -character, write it as a Lisp character constant: @samp{?} followed by -the character as it would appear in a string. Function keys are -represented by symbols (@pxref{Function Keys}); simply write the -symbol's name, with no other delimiters or punctuation. Here are some -examples: - -@example -(global-set-key [?\C-=] 'make-symbolic-link) -(global-set-key [?\M-\C-=] 'make-symbolic-link) -(global-set-key [?\H-a] 'make-symbolic-link) -(global-set-key [f7] 'make-symbolic-link) -(global-set-key [C-mouse-1] 'make-symbolic-link) -@end example - -@noindent -You can use a vector for the simple cases too: - -@example -(global-set-key [?\C-z ?\M-l] 'make-symbolic-link) -@end example - - Language and coding systems may cause problems with key bindings for -non-@acronym{ASCII} characters. @xref{Init Non-ASCII}. - - As described in @ref{Local Keymaps}, major modes and minor modes can -define local keymaps. These keymaps are constructed when the mode is -used for the first time in a session. If you wish to change one of -these keymaps, you must use the @dfn{mode hook} (@pxref{Hooks}). - -@findex define-key - For example, Texinfo mode runs the hook @code{texinfo-mode-hook}. -Here's how you can use the hook to add local bindings for @kbd{C-c n} -and @kbd{C-c p} in Texinfo mode: - -@example -(add-hook 'texinfo-mode-hook - '(lambda () - (define-key texinfo-mode-map "\C-cp" - 'backward-paragraph) - (define-key texinfo-mode-map "\C-cn" - 'forward-paragraph))) -@end example - -@node Modifier Keys -@subsection Modifier Keys -@cindex modifier keys - - The default key bindings in Emacs are set up so that modified -alphabetical characters are case-insensitive. In other words, -@kbd{C-A} does the same thing as @kbd{C-a}, and @kbd{M-A} does the -same thing as @kbd{M-a}. This concerns only alphabetical characters, -and does not apply to ``shifted'' versions of other keys; for -instance, @kbd{C-@@} is not the same as @kbd{C-2}. - - A @key{Control}-modified alphabetical character is always considered -case-insensitive: Emacs always treats @kbd{C-A} as @kbd{C-a}, -@kbd{C-B} as @kbd{C-b}, and so forth. The reason for this is -historical. - - For all other modifiers, you can make the modified alphabetical -characters case-sensitive when you customize Emacs. For instance, you -could make @kbd{M-a} and @kbd{M-A} run different commands. - - Although only the @key{Control} and @key{Meta} modifier keys are -commonly used, Emacs supports three other modifier keys. These are -called @key{Super}, @key{Hyper} and @key{Alt}. Few terminals provide -ways to use these modifiers; the key labeled @key{Alt} on most -keyboards usually issues the @key{Meta} modifier, not @key{Alt}. The -standard key bindings in Emacs do not include any characters with -these modifiers. However, you can customize Emacs to assign meanings -to them. The modifier bits are labeled as @samp{s-}, @samp{H-} and -@samp{A-} respectively. - - Even if your keyboard lacks these additional modifier keys, you can -enter it using @kbd{C-x @@}: @kbd{C-x @@ h} adds the ``hyper'' flag to -the next character, @kbd{C-x @@ s} adds the ``super'' flag, and -@kbd{C-x @@ a} adds the ``alt'' flag. For instance, @kbd{C-x @@ h -C-a} is a way to enter @kbd{Hyper-Control-a}. (Unfortunately, there -is no way to add two modifiers by using @kbd{C-x @@} twice for the -same character, because the first one goes to work on the @kbd{C-x}.) - -@node Function Keys -@subsection Rebinding Function Keys - - Key sequences can contain function keys as well as ordinary -characters. Just as Lisp characters (actually integers) represent -keyboard characters, Lisp symbols represent function keys. If the -function key has a word as its label, then that word is also the name of -the corresponding Lisp symbol. Here are the conventional Lisp names for -common function keys: - -@table @asis -@item @code{left}, @code{up}, @code{right}, @code{down} -Cursor arrow keys. - -@item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior} -Other cursor repositioning keys. - -@item @code{select}, @code{print}, @code{execute}, @code{backtab} -@itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline} -@itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar} -Miscellaneous function keys. - -@item @code{f1}, @code{f2}, @dots{} @code{f35} -Numbered function keys (across the top of the keyboard). - -@item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide} -@itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter} -@itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal} -Keypad keys (to the right of the regular keyboard), with names or punctuation. - -@item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9} -Keypad keys with digits. - -@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} -Keypad PF keys. -@end table - - These names are conventional, but some systems (especially when using -X) may use different names. To make certain what symbol is used for a -given function key on your terminal, type @kbd{C-h c} followed by that -key. - - @xref{Init Rebinding}, for examples of binding function keys. - -@cindex keypad - Many keyboards have a ``numeric keypad'' on the right hand side. -The numeric keys in the keypad double up as cursor motion keys, -toggled by a key labeled @samp{Num Lock}. By default, Emacs -translates these keys to the corresponding keys in the main keyboard. -For example, when @samp{Num Lock} is on, the key labeled @samp{8} on -the numeric keypad produces @code{kp-8}, which is translated to -@kbd{8}; when @samp{Num Lock} is off, the same key produces -@code{kp-up}, which is translated to @key{UP}. If you rebind a key -such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too. -However, if you rebind a @samp{kp-} key directly, that won't affect -its non-keypad equivalent. Note that the modified keys are not -translated: for instance, if you hold down the @key{META} key while -pressing the @samp{8} key on the numeric keypad, that generates -@kbd{M-@key{kp-8}}. - - Emacs provides a convenient method for binding the numeric keypad -keys, using the variables @code{keypad-setup}, -@code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and -@code{keypad-numlock-shifted-setup}. These can be found in the -@samp{keyboard} customization group (@pxref{Easy Customization}). You -can rebind the keys to perform other tasks, such as issuing numeric -prefix arguments. - -@node Named ASCII Chars -@subsection Named @acronym{ASCII} Control Characters - - @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL} -started out as names for certain @acronym{ASCII} control characters, -used so often that they have special keys of their own. For instance, -@key{TAB} was another name for @kbd{C-i}. Later, users found it -convenient to distinguish in Emacs between these keys and the ``same'' -control characters typed with the @key{CTRL} key. Therefore, on most -modern terminals, they are no longer the same: @key{TAB} is different -from @kbd{C-i}. - - Emacs can distinguish these two kinds of input if the keyboard does. -It treats the ``special'' keys as function keys named @code{tab}, -@code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and -@code{delete}. These function keys translate automatically into the -corresponding @acronym{ASCII} characters @emph{if} they have no -bindings of their own. As a result, neither users nor Lisp programs -need to pay attention to the distinction unless they care to. - - If you do not want to distinguish between (for example) @key{TAB} and -@kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB} -(octal code 011). If you do want to distinguish, make one binding for -this @acronym{ASCII} character, and another for the ``function key'' @code{tab}. - - With an ordinary @acronym{ASCII} terminal, there is no way to distinguish -between @key{TAB} and @kbd{C-i} (and likewise for other such pairs), -because the terminal sends the same character in both cases. - -@node Mouse Buttons -@subsection Rebinding Mouse Buttons -@cindex mouse button events -@cindex rebinding mouse buttons -@cindex click events -@cindex drag events -@cindex down events -@cindex button down events - - Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary -mouse events in Emacs are @dfn{click} events; these happen when you -press a button and release it without moving the mouse. You can also -get @dfn{drag} events, when you move the mouse while holding the button -down. Drag events happen when you finally let go of the button. - - The symbols for basic click events are @code{mouse-1} for the leftmost -button, @code{mouse-2} for the next, and so on. Here is how you can -redefine the second mouse button to split the current window: - -@example -(global-set-key [mouse-2] 'split-window-below) -@end example - - The symbols for drag events are similar, but have the prefix -@samp{drag-} before the word @samp{mouse}. For example, dragging the -first button generates a @code{drag-mouse-1} event. - - You can also define bindings for events that occur when a mouse button -is pressed down. These events start with @samp{down-} instead of -@samp{drag-}. Such events are generated only if they have key bindings. -When you get a button-down event, a corresponding click or drag event -will always follow. - -@cindex double clicks -@cindex triple clicks - If you wish, you can distinguish single, double, and triple clicks. A -double click means clicking a mouse button twice in approximately the -same place. The first click generates an ordinary click event. The -second click, if it comes soon enough, generates a double-click event -instead. The event type for a double-click event starts with -@samp{double-}: for example, @code{double-mouse-3}. - - This means that you can give a special meaning to the second click at -the same place, but it must act on the assumption that the ordinary -single click definition has run when the first click was received. - - This constrains what you can do with double clicks, but user interface -designers say that this constraint ought to be followed in any case. A -double click should do something similar to the single click, only -``more so''. The command for the double-click event should perform the -extra work for the double click. - - If a double-click event has no binding, it changes to the -corresponding single-click event. Thus, if you don't define a -particular double click specially, it executes the single-click command -twice. - - Emacs also supports triple-click events whose names start with -@samp{triple-}. Emacs does not distinguish quadruple clicks as event -types; clicks beyond the third generate additional triple-click events. -However, the full number of clicks is recorded in the event list, so -if you know Emacs Lisp you can distinguish if you really want to -(@pxref{Click Events,,, elisp, The Emacs Lisp Reference Manual}). -We don't recommend distinct meanings for more than three clicks, but -sometimes it is useful for subsequent clicks to cycle through the same -set of three meanings, so that four clicks are equivalent to one -click, five are equivalent to two, and six are equivalent to three. - - Emacs also records multiple presses in drag and button-down events. -For example, when you press a button twice, then move the mouse while -holding the button, Emacs gets a @samp{double-drag-} event. And at the -moment when you press it down for the second time, Emacs gets a -@samp{double-down-} event (which is ignored, like all button-down -events, if it has no binding). - -@vindex double-click-time - The variable @code{double-click-time} specifies how much time can -elapse between clicks and still allow them to be grouped as a multiple -click. Its value is in units of milliseconds. If the value is -@code{nil}, double clicks are not detected at all. If the value is -@code{t}, then there is no time limit. The default is 500. - -@vindex double-click-fuzz - The variable @code{double-click-fuzz} specifies how much the mouse -can move between clicks and still allow them to be grouped as a multiple -click. Its value is in units of pixels on windowed displays and in -units of 1/8 of a character cell on text-mode terminals; the default is -3. - - The symbols for mouse events also indicate the status of the modifier -keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-}, -@samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-} -or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}. - - A frame includes areas that don't show text from the buffer, such as -the mode line and the scroll bar. You can tell whether a mouse button -comes from a special area of the screen by means of dummy ``prefix -keys''. For example, if you click the mouse in the mode line, you get -the prefix key @code{mode-line} before the ordinary mouse-button symbol. -Thus, here is how to define the command for clicking the first button in -a mode line to run @code{scroll-up-command}: - -@example -(global-set-key [mode-line mouse-1] 'scroll-up-command) -@end example - - Here is the complete list of these dummy prefix keys and their -meanings: - -@table @code -@item mode-line -The mouse was in the mode line of a window. -@item vertical-line -The mouse was in the vertical line separating side-by-side windows. (If -you use scroll bars, they appear in place of these vertical lines.) -@item vertical-scroll-bar -The mouse was in a vertical scroll bar. (This is the only kind of -scroll bar Emacs currently supports.) -@item menu-bar -The mouse was in the menu bar. -@item header-line -The mouse was in a header line. -@ignore -@item horizontal-scroll-bar -The mouse was in a horizontal scroll bar. Horizontal scroll bars do -horizontal scrolling, and people don't use them often. -@end ignore -@end table - - You can put more than one mouse button in a key sequence, but it isn't -usual to do so. - -@node Disabling -@subsection Disabling Commands -@cindex disabled command - - Disabling a command means that invoking it interactively asks for -confirmation from the user. The purpose of disabling a command is to -prevent users from executing it by accident; we do this for commands -that might be confusing to the uninitiated. - - Attempting to invoke a disabled command interactively in Emacs -displays a window containing the command's name, its documentation, -and some instructions on what to do immediately; then Emacs asks for -input saying whether to execute the command as requested, enable it -and execute it, or cancel. If you decide to enable the command, you -must then answer another question---whether to do this permanently, or -just for the current session. (Enabling permanently works by -automatically editing your initialization file.) You can also type -@kbd{!} to enable @emph{all} commands, for the current session only. - - The direct mechanism for disabling a command is to put a -non-@code{nil} @code{disabled} property on the Lisp symbol for the -command. Here is the Lisp program to do this: - -@example -(put 'delete-region 'disabled t) -@end example - - If the value of the @code{disabled} property is a string, that string -is included in the message displayed when the command is used: - -@example -(put 'delete-region 'disabled - "It's better to use `kill-region' instead.\n") -@end example - -@findex disable-command -@findex enable-command - You can make a command disabled either by editing the initialization -file directly, or with the command @kbd{M-x disable-command}, which -edits the initialization file for you. Likewise, @kbd{M-x -enable-command} edits the initialization file to enable a command -permanently. @xref{Init File}. - - If Emacs was invoked with the @option{-q} or @option{--no-init-file} -options (@pxref{Initial Options}), it will not edit your -initialization file. Doing so could lose information because Emacs -has not read your initialization file. - - Whether a command is disabled is independent of what key is used to -invoke it; disabling also applies if the command is invoked using -@kbd{M-x}. However, disabling a command has no effect on calling it -as a function from Lisp programs. - -@node Init File -@section The Emacs Initialization File -@cindex init file -@cindex .emacs file -@cindex ~/.emacs file -@cindex Emacs initialization file -@cindex key rebinding, permanent -@cindex rebinding keys, permanently -@cindex startup (init file) - - When Emacs is started, it normally tries to load a Lisp program from -an @dfn{initialization file}, or @dfn{init file} for short. This -file, if it exists, specifies how to initialize Emacs for you. Emacs -looks for your init file using the filenames @file{~/.emacs}, -@file{~/.emacs.el}, or @file{~/.emacs.d/init.el}; you can choose to -use any one of these three names (@pxref{Find Init}). Here, @file{~/} -stands for your home directory. - - You can use the command line switch @samp{-q} to prevent loading -your init file, and @samp{-u} (or @samp{--user}) to specify a -different user's init file (@pxref{Initial Options}). - -@cindex @file{default.el}, the default init file - There can also be a @dfn{default init file}, which is the library -named @file{default.el}, found via the standard search path for -libraries. The Emacs distribution contains no such library; your site -may create one for local customizations. If this library exists, it is -loaded whenever you start Emacs (except when you specify @samp{-q}). -But your init file, if any, is loaded first; if it sets -@code{inhibit-default-init} non-@code{nil}, then @file{default} is not -loaded. - -@cindex site init file -@cindex @file{site-start.el}, the site startup file - Your site may also have a @dfn{site startup file}; this is named -@file{site-start.el}, if it exists. Like @file{default.el}, Emacs -finds this file via the standard search path for Lisp libraries. -Emacs loads this library before it loads your init file. To inhibit -loading of this library, use the option @samp{--no-site-file}. -@xref{Initial Options}. We recommend against using -@file{site-start.el} for changes that some users may not like. It is -better to put them in @file{default.el}, so that users can more easily -override them. - - You can place @file{default.el} and @file{site-start.el} in any of -the directories which Emacs searches for Lisp libraries. The variable -@code{load-path} (@pxref{Lisp Libraries}) specifies these directories. -Many sites put these files in the @file{site-lisp} subdirectory of the -Emacs installation directory, typically -@file{/usr/local/share/emacs/site-lisp}. - - Byte-compiling your init file is not recommended (@pxref{Byte -Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference -Manual}). It generally does not speed up startup very much, and often -leads to problems when you forget to recompile the file. A better -solution is to use the Emacs server to reduce the number of times you -have to start Emacs (@pxref{Emacs Server}). If your init file defines -many functions, consider moving them to a separate (byte-compiled) -file that you load in your init file. - - If you are going to write actual Emacs Lisp programs that go beyond -minor customization, you should read the @cite{Emacs Lisp Reference Manual}. -@ifnottex -@xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference -Manual}. -@end ifnottex - -@menu -* Init Syntax:: Syntax of constants in Emacs Lisp. -* Init Examples:: How to do some things with an init file. -* Terminal Init:: Each terminal type can have an init file. -* Find Init:: How Emacs finds the init file. -* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. -@end menu - -@node Init Syntax -@subsection Init File Syntax - - The init file contains one or more Lisp expressions. Each of these -consists of a function name followed by arguments, all surrounded by -parentheses. For example, @code{(setq fill-column 60)} calls the -function @code{setq} to set the variable @code{fill-column} -(@pxref{Filling}) to 60. - - You can set any Lisp variable with @code{setq}, but with certain -variables @code{setq} won't do what you probably want in the -@file{.emacs} file. Some variables automatically become buffer-local -when set with @code{setq}; what you want in @file{.emacs} is to set -the default value, using @code{setq-default}. Some customizable minor -mode variables do special things to enable the mode when you set them -with Customize, but ordinary @code{setq} won't do that; to enable the -mode in your @file{.emacs} file, call the minor mode command. The -following section has examples of both of these methods. - - The second argument to @code{setq} is an expression for the new -value of the variable. This can be a constant, a variable, or a -function call expression. In @file{.emacs}, constants are used most -of the time. They can be: - -@table @asis -@item Numbers: -Numbers are written in decimal, with an optional initial minus sign. - -@item Strings: -@cindex Lisp string syntax -@cindex string syntax -Lisp string syntax is the same as C string syntax with a few extra -features. Use a double-quote character to begin and end a string constant. - -In a string, you can include newlines and special characters literally. -But often it is cleaner to use backslash sequences for them: @samp{\n} -for newline, @samp{\b} for backspace, @samp{\r} for carriage return, -@samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for -escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or -@samp{\@var{ooo}} for the character whose octal code is @var{ooo}. -Backslash and double-quote are the only characters for which backslash -sequences are mandatory. - -@samp{\C-} can be used as a prefix for a control character, as in -@samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for -a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for -@kbd{Control-Meta-A}.@refill - -@xref{Init Non-ASCII}, for information about including -non-@acronym{ASCII} in your init file. - -@item Characters: -@cindex Lisp character syntax -@cindex character syntax -Lisp character constant syntax consists of a @samp{?} followed by -either a character or an escape sequence starting with @samp{\}. -Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that -strings and characters are not interchangeable in Lisp; some contexts -require one and some contexts require the other. - -@xref{Init Non-ASCII}, for information about binding commands to -keys which send non-@acronym{ASCII} characters. - -@item True: -@code{t} stands for `true'. - -@item False: -@code{nil} stands for `false'. - -@item Other Lisp objects: -@cindex Lisp object syntax -Write a single-quote (@code{'}) followed by the Lisp object you want. -@end table - -@node Init Examples -@subsection Init File Examples - - Here are some examples of doing certain commonly desired things with -Lisp expressions: - -@itemize @bullet -@item -Add a directory to the variable @code{load-path}. You can then put -Lisp libraries that are not included with Emacs in this directory, and -load them with @kbd{M-x load-library}. @xref{Lisp Libraries}. - -@example -(add-to-list 'load-path "/path/to/lisp/libraries") -@end example - -@item -Make @key{TAB} in C mode just insert a tab if point is in the middle of a -line. - -@example -(setq c-tab-always-indent nil) -@end example - -Here we have a variable whose value is normally @code{t} for `true' -and the alternative is @code{nil} for `false'. - -@item -Make searches case sensitive by default (in all buffers that do not -override this). - -@example -(setq-default case-fold-search nil) -@end example - -This sets the default value, which is effective in all buffers that do -not have local values for the variable (@pxref{Locals}). Setting -@code{case-fold-search} with @code{setq} affects only the current -buffer's local value, which is probably not what you want to do in an -init file. - -@item -@vindex user-mail-address -Specify your own email address, if Emacs can't figure it out correctly. - -@example -(setq user-mail-address "cheney@@torture.gov") -@end example - -Various Emacs packages, such as Message mode, consult -@code{user-mail-address} when they need to know your email address. -@xref{Mail Headers}. - -@item -Make Text mode the default mode for new buffers. - -@example -(setq-default major-mode 'text-mode) -@end example - -Note that @code{text-mode} is used because it is the command for -entering Text mode. The single-quote before it makes the symbol a -constant; otherwise, @code{text-mode} would be treated as a variable -name. - -@need 1500 -@item -Set up defaults for the Latin-1 character set -which supports most of the languages of Western Europe. - -@example -(set-language-environment "Latin-1") -@end example - -@need 1500 -@item -Turn off Line Number mode, a global minor mode. - -@example -(line-number-mode 0) -@end example - -@need 1500 -@item -Turn on Auto Fill mode automatically in Text mode and related modes -(@pxref{Hooks}). - -@example -(add-hook 'text-mode-hook 'auto-fill-mode) -@end example - -@item -Load the installed Lisp library named @file{foo} (actually a file -@file{foo.elc} or @file{foo.el} in a standard Emacs directory). - -@example -(load "foo") -@end example - -When the argument to @code{load} is a relative file name, not starting -with @samp{/} or @samp{~}, @code{load} searches the directories in -@code{load-path} (@pxref{Lisp Libraries}). - -@item -Load the compiled Lisp file @file{foo.elc} from your home directory. - -@example -(load "~/foo.elc") -@end example - -Here a full file name is used, so no searching is done. - -@item -@cindex loading Lisp libraries automatically -@cindex autoload Lisp libraries -Tell Emacs to find the definition for the function @code{myfunction} -by loading a Lisp library named @file{mypackage} (i.e.@: a file -@file{mypackage.elc} or @file{mypackage.el}): - -@example -(autoload 'myfunction "mypackage" "Do what I say." t) -@end example - -@noindent -Here the string @code{"Do what I say."} is the function's -documentation string. You specify it in the @code{autoload} -definition so it will be available for help commands even when the -package is not loaded. The last argument, @code{t}, indicates that -this function is interactive; that is, it can be invoked interactively -by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key. -If the function is not interactive, omit the @code{t} or use -@code{nil}. - -@item -Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link} -(@pxref{Init Rebinding}). - -@example -(global-set-key "\C-xl" 'make-symbolic-link) -@end example - -or - -@example -(define-key global-map "\C-xl" 'make-symbolic-link) -@end example - -Note once again the single-quote used to refer to the symbol -@code{make-symbolic-link} instead of its value as a variable. - -@item -Do the same thing for Lisp mode only. - -@example -(define-key lisp-mode-map "\C-xl" 'make-symbolic-link) -@end example - -@item -Redefine all keys which now run @code{next-line} in Fundamental mode -so that they run @code{forward-line} instead. - -@findex substitute-key-definition -@example -(substitute-key-definition 'next-line 'forward-line - global-map) -@end example - -@item -Make @kbd{C-x C-v} undefined. - -@example -(global-unset-key "\C-x\C-v") -@end example - -One reason to undefine a key is so that you can make it a prefix. -Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a -prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix -definition. - -@item -Make @samp{$} have the syntax of punctuation in Text mode. -Note the use of a character constant for @samp{$}. - -@example -(modify-syntax-entry ?\$ "." text-mode-syntax-table) -@end example - -@item -Enable the use of the command @code{narrow-to-region} without confirmation. - -@example -(put 'narrow-to-region 'disabled nil) -@end example - -@item -Adjusting the configuration to various platforms and Emacs versions. - -Users typically want Emacs to behave the same on all systems, so the -same init file is right for all platforms. However, sometimes it -happens that a function you use for customizing Emacs is not available -on some platforms or in older Emacs versions. To deal with that -situation, put the customization inside a conditional that tests whether -the function or facility is available, like this: - -@example -(if (fboundp 'blink-cursor-mode) - (blink-cursor-mode 0)) - -(if (boundp 'coding-category-utf-8) - (set-coding-priority '(coding-category-utf-8))) -@end example - -@noindent -You can also simply disregard the errors that occur if the -function is not defined. - -@example -(condition case () - (set-face-background 'region "grey75") - (error nil)) -@end example - -A @code{setq} on a variable which does not exist is generally -harmless, so those do not need a conditional. -@end itemize - -@node Terminal Init -@subsection Terminal-specific Initialization - - Each terminal type can have a Lisp library to be loaded into Emacs when -it is run on that type of terminal. For a terminal type named -@var{termtype}, the library is called @file{term/@var{termtype}} and it is -found by searching the directories @code{load-path} as usual and trying the -suffixes @samp{.elc} and @samp{.el}. Normally it appears in the -subdirectory @file{term} of the directory where most Emacs libraries are -kept.@refill - - The usual purpose of the terminal-specific library is to map the -escape sequences used by the terminal's function keys onto more -meaningful names, using @code{input-decode-map} (or -@code{function-key-map} before it). See the file -@file{term/lk201.el} for an example of how this is done. Many function -keys are mapped automatically according to the information in the -Termcap data base; the terminal-specific library needs to map only the -function keys that Termcap does not specify. - - When the terminal type contains a hyphen, only the part of the name -before the first hyphen is significant in choosing the library name. -Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use -the library @file{term/aaa}. The code in the library can use -@code{(getenv "TERM")} to find the full terminal type name.@refill - -@vindex term-file-prefix - The library's name is constructed by concatenating the value of the -variable @code{term-file-prefix} and the terminal type. Your @file{.emacs} -file can prevent the loading of the terminal-specific library by setting -@code{term-file-prefix} to @code{nil}. - -@vindex term-setup-hook - Emacs runs the hook @code{term-setup-hook} at the end of -initialization, after both your @file{.emacs} file and any -terminal-specific library have been read in. Add hook functions to this -hook if you wish to override part of any of the terminal-specific -libraries and to define initializations for terminals that do not have a -library. @xref{Hooks}. - -@node Find Init -@subsection How Emacs Finds Your Init File - - Normally Emacs uses the environment variable @env{HOME} -(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what -@samp{~} means in a file name. If @file{.emacs} is not found inside -@file{~/} (nor @file{.emacs.el}), Emacs looks for -@file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be -byte-compiled). - - However, if you run Emacs from a shell started by @code{su}, Emacs -tries to find your own @file{.emacs}, not that of the user you are -currently pretending to be. The idea is that you should get your own -editor customizations even if you are running as the super user. - - More precisely, Emacs first determines which user's init file to use. -It gets your user name from the environment variables @env{LOGNAME} and -@env{USER}; if neither of those exists, it uses effective user-ID. -If that user name matches the real user-ID, then Emacs uses @env{HOME}; -otherwise, it looks up the home directory corresponding to that user -name in the system's data base of users. -@c LocalWords: backtab - -@node Init Non-ASCII -@subsection Non-@acronym{ASCII} Characters in Init Files -@cindex international characters in @file{.emacs} -@cindex non-@acronym{ASCII} characters in @file{.emacs} -@cindex non-@acronym{ASCII} keys, binding -@cindex rebinding non-@acronym{ASCII} keys - - Language and coding systems may cause problems if your init file -contains non-@acronym{ASCII} characters, such as accented letters, in -strings or key bindings. - - If you want to use non-@acronym{ASCII} characters in your init file, -you should put a @w{@samp{-*-coding: @var{coding-system}-*-}} tag on -the first line of the init file, and specify a coding system that -supports the character(s) in question. @xref{Recognize Coding}. This -is because the defaults for decoding non-@acronym{ASCII} text might -not yet be set up by the time Emacs reads those parts of your init -file which use such strings, possibly leading Emacs to decode those -strings incorrectly. You should then avoid adding Emacs Lisp code -that modifies the coding system in other ways, such as calls to -@code{set-language-environment}. - - To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init -Rebinding}). The string syntax cannot be used, since the -non-@acronym{ASCII} characters will be interpreted as meta keys. For -instance: - -@example -(global-set-key [?@var{char}] 'some-function) -@end example - -@noindent -Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. - - @strong{Warning:} if you change the keyboard encoding, or change -between multibyte and unibyte mode, or anything that would alter which -code @kbd{C-q} would insert for that character, this key binding may -stop working. It is therefore advisable to use one and only one -coding system, for your init file as well as the files you edit. For -example, don't mix the @samp{latin-1} and @samp{latin-9} coding -systems. diff --git a/doc/emacs/dired-xtra.texi b/doc/emacs/dired-xtra.texi deleted file mode 100644 index 81de9a800f9..00000000000 --- a/doc/emacs/dired-xtra.texi +++ /dev/null @@ -1,50 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Subdir Switches -@section Subdirectory Switches in Dired - -You can insert subdirectories with specified @command{ls} switches in -Dired buffers using @kbd{C-u i}. You can change the @command{ls} -switches of an already inserted subdirectory at point using @kbd{C-u l}. - -Dired preserves the switches if you revert the buffer. Deleting a -subdirectory forgets about its switches. - -Using @code{dired-undo} -@iftex -(@pxref{Marks vs Flags,,, emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Marks vs Flags}) -@end ifnottex -to reinsert or delete -subdirectories that were inserted with explicit switches can bypass -Dired's machinery for remembering (or forgetting) switches. Deleting -a subdirectory using @code{dired-undo} does not forget its switches. -When later reinserted using @kbd{i}, it will be reinserted using its -old switches. Using @code{dired-undo} to reinsert a subdirectory that -was deleted using the regular Dired commands (not @code{dired-undo}) -will originally insert it with its old switches. Reverting the -buffer, however, will relist it using the buffer's default switches. -If any of this yields problems, you can easily correct the situation -using @kbd{C-u i} or @kbd{C-u l}. - -Dired does not remember the @code{R} switch. Inserting a subdirectory -with switches that include the @code{R} switch is equivalent to -inserting each of its subdirectories using all remaining switches. -For instance, updating or killing a subdirectory that was inserted -with the @code{R} switch will not update or kill its subdirectories. - -The buffer's default switches do not affect subdirectories that were -inserted using explicitly specified switches. In particular, -commands such as @kbd{s} that change the buffer's switches do not -affect such subdirectories. (They do, however, affect subdirectories -without explicitly assigned switches.) - -You can make Dired forget about all subdirectory switches and relist -all subdirectories with the buffer's default switches using -@kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer. diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi deleted file mode 100644 index 0dcded78364..00000000000 --- a/doc/emacs/dired.texi +++ /dev/null @@ -1,1433 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Dired -@chapter Dired, the Directory Editor -@c This node is referenced in the tutorial. When renaming or deleting -@c it, the tutorial needs to be adjusted. -@cindex Dired -@cindex file management - - Dired makes an Emacs buffer containing a listing of a directory, and -optionally some of its subdirectories as well. You can use the normal -Emacs commands to move around in this buffer, and special Dired -commands to operate on the listed files. - - The Dired buffer is ``read-only'', and inserting text in it is not -allowed. Ordinary printing characters such as @kbd{d} and @kbd{x} are -redefined for special Dired commands. Some Dired commands @dfn{mark} -or @dfn{flag} the @dfn{current file} (that is, the file on the current -line); other commands operate on the marked files or on the flagged -files. You first mark certain files in order to operate on all of -them with one command. - - The Dired-X package provides various extra features for Dired mode. -@xref{Top, Dired-X,,dired-x, Dired Extra User's Manual}. - - You can also view a list of files in a directory with @kbd{C-x C-d} -(@code{list-directory}). Unlike Dired, this command does not allow -you to operate on the listed files. @xref{Directories}. - -@menu -* Enter: Dired Enter. How to invoke Dired. -* Navigation: Dired Navigation. Special motion commands in the Dired buffer. -* Deletion: Dired Deletion. Deleting files with Dired. -* Flagging Many Files:: Flagging files based on their names. -* Visit: Dired Visiting. Other file operations through Dired. -* Marks vs Flags:: Flagging for deletion vs marking. -* Operating on Files:: How to copy, rename, print, compress, etc. - either one file or several files. -* Shell Commands in Dired:: Running a shell command on the marked files. -* Transforming File Names:: Using patterns to rename multiple files. -* Comparison in Dired:: Running @code{diff} by way of Dired. -* Subdirectories in Dired:: Adding subdirectories to the Dired buffer. -@ifnottex -* Subdir Switches:: Subdirectory switches in Dired. -@end ifnottex -* Subdirectory Motion:: Moving across subdirectories, and up and down. -* Hiding Subdirectories:: Making subdirectories visible or invisible. -* Updating: Dired Updating. Discarding lines for files of no interest. -* Find: Dired and Find. Using @code{find} to choose the files for Dired. -* Wdired:: Operating on files by editing the Dired buffer. -* Image-Dired:: Viewing image thumbnails in Dired. -* Misc: Misc Dired Features. Various other features. -@end menu - -@node Dired Enter -@section Entering Dired - -@findex dired -@kindex C-x d -@vindex dired-listing-switches - To invoke Dired, type @kbd{C-x d} (@code{dired}). This reads a -directory name using the minibuffer, and opens a @dfn{Dired buffer} -listing the files in that directory. You can also supply a wildcard -file name pattern as the minibuffer argument, in which case the Dired -buffer lists all files matching that pattern. The usual history and -completion commands can be used in the minibuffer; in particular, -@kbd{M-n} puts the name of the visited file (if any) in the minibuffer -(@pxref{Minibuffer History}). - - You can also invoke Dired by giving @kbd{C-x C-f} (@code{find-file}) -a directory name. - - The variable @code{dired-listing-switches} specifies the options to -give to @command{ls} for listing the directory; this string -@emph{must} contain @samp{-l}. If you use a prefix argument with the -@code{dired} command, you can specify the @command{ls} switches with the -minibuffer before you enter the directory specification. No matter -how they are specified, the @command{ls} switches can include short -options (that is, single characters) requiring no arguments, and long -options (starting with @samp{--}) whose arguments are specified with -@samp{=}. - -@vindex dired-use-ls-dired - If your @command{ls} program supports the @samp{--dired} option, -Dired automatically passes it that option; this causes @command{ls} to -emit special escape sequences for certain unusual file names, without -which Dired will not be able to parse those names. The first time you -run Dired in an Emacs session, it checks whether @command{ls} supports -the @samp{--dired} option by calling it once with that option. If the -exit code is 0, Dired will subsequently use the @samp{--dired} option; -otherwise it will not. You can inhibit this check by customizing the -variable @code{dired-use-ls-dired}. The value @code{unspecified} (the -default) means to perform the check; any other non-@code{nil} value -means to use the @samp{--dired} option; and @code{nil} means not to -use the @samp{--dired} option. - - On MS-Windows and MS-DOS systems, Emacs emulates @command{ls}. -@xref{ls in Lisp}, for options and peculiarities of this emulation. - -@findex dired-other-window -@kindex C-x 4 d -@findex dired-other-frame -@kindex C-x 5 d - To display the Dired buffer in another window, use @kbd{C-x 4 d} -(@code{dired-other-window}). @kbd{C-x 5 d} -(@code{dired-other-frame}) displays the Dired buffer in a separate -frame. - -@kindex q @r{(Dired)} -@findex quit-window - Typing @kbd{q} (@code{quit-window}) buries the Dired buffer, and -deletes its window if the window was created just for that buffer. - -@node Dired Navigation -@section Navigation in the Dired Buffer - -@kindex C-n @r{(Dired)} -@kindex C-p @r{(Dired)} - All the usual Emacs cursor motion commands are available in Dired -buffers. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the -cursor at the beginning of the file name on the line, rather than at -the beginning of the line. - -@kindex SPC @r{(Dired)} - For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent -to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines -is so common in Dired that it deserves to be easy to type.) @key{DEL} -(move up and unflag) is also often useful simply for moving up -(@pxref{Dired Deletion}). - -@findex dired-goto-file -@kindex j @r{(Dired)} - @kbd{j} (@code{dired-goto-file}) prompts for a file name using the -minibuffer, and moves point to the line in the Dired buffer describing -that file. - -@cindex searching Dired buffers -@findex dired-isearch-filenames -@vindex dired-isearch-filenames -@findex dired-isearch-filenames-regexp -@kindex M-s f C-s @r{(Dired)} -@kindex M-s f M-C-s @r{(Dired)} - @kbd{M-s f C-s} (@code{dired-isearch-filenames}) performs a forward -incremental search in the Dired buffer, looking for matches only -amongst the file names and ignoring the rest of the text in the -buffer. @kbd{M-s f M-C-s} (@code{dired-isearch-filenames-regexp}) -does the same, using a regular expression search. If you change the -variable @code{dired-isearch-filenames} to @code{t}, then the -usual search commands also limit themselves to the file names; for -instance, @kbd{C-s} behaves like @kbd{M-s f C-s}. If the value is -@code{dwim}, then search commands match the file names only when point -was on a file name initially. @xref{Search}, for information about -incremental search. - - Some additional navigation commands are available when the Dired -buffer includes several directories. @xref{Subdirectory Motion}. - -@node Dired Deletion -@section Deleting Files with Dired -@cindex flagging files (in Dired) -@cindex deleting files (in Dired) - - One of the most frequent uses of Dired is to first @dfn{flag} files for -deletion, then delete the files that were flagged. - -@table @kbd -@item d -Flag this file for deletion. -@item u -Remove deletion flag on this line. -@item @key{DEL} -Move point to previous line and remove the deletion flag on that line. -@item x -Delete the files that are flagged for deletion. -@end table - -@kindex d @r{(Dired)} -@findex dired-flag-file-deletion - You can flag a file for deletion by moving to the line describing -the file and typing @kbd{d} (@code{dired-flag-file-deletion}). The -deletion flag is visible as a @samp{D} at the beginning of the line. -This command moves point to the next line, so that repeated @kbd{d} -commands flag successive files. A numeric argument serves as a repeat -count. - -@kindex u @r{(Dired deletion)} -@kindex DEL @r{(Dired)} - The reason for flagging files for deletion, rather than deleting -files immediately, is to reduce the danger of deleting a file -accidentally. Until you direct Dired to delete the flagged files, you -can remove deletion flags using the commands @kbd{u} and @key{DEL}. -@kbd{u} (@code{dired-unmark}) works just like @kbd{d}, but removes -flags rather than making flags. @key{DEL} -(@code{dired-unmark-backward}) moves upward, removing flags; it is -like @kbd{u} with argument @minus{}1. - -@kindex x @r{(Dired)} -@findex dired-do-flagged-delete - To delete the flagged files, type @kbd{x} -(@code{dired-do-flagged-delete}). This command first displays a list -of all the file names flagged for deletion, and requests confirmation -with @kbd{yes}. If you confirm, Dired deletes the flagged files, then -deletes their lines from the text of the Dired buffer. The Dired -buffer, with somewhat fewer lines, remains selected. - - If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you -return immediately to Dired, with the deletion flags still present in -the buffer, and no files actually deleted. - -@cindex recursive deletion -@vindex dired-recursive-deletes - You can delete empty directories just like other files, but normally -Dired cannot delete directories that are nonempty. If the variable -@code{dired-recursive-deletes} is non-@code{nil}, then Dired can -delete nonempty directories including all their contents. That can -be somewhat risky. - -@vindex delete-by-moving-to-trash - If you change the variable @code{delete-by-moving-to-trash} to -@code{t}, the above deletion commands will move the affected files or -directories into the operating system's Trash, instead of deleting -them outright. @xref{Misc File Ops}. - -@node Flagging Many Files -@section Flagging Many Files at Once -@cindex flagging many files for deletion (in Dired) - - The @kbd{#}, @kbd{~}, @kbd{.}, @kbd{% &}, and @kbd{% d} commands -flag many files for deletion, based on their file names: - -@table @kbd -@item # -Flag all auto-save files (files whose names start and end with @samp{#}) -for deletion (@pxref{Auto Save}). - -@item ~ -Flag all backup files (files whose names end with @samp{~}) for deletion -(@pxref{Backup}). - -@item .@: @r{(Period)} -Flag excess numeric backup files for deletion. The oldest and newest -few backup files of any one file are exempt; the middle ones are -flagged. - -@item % & -Flag for deletion all files with certain kinds of names which suggest -you could easily create those files again. - -@item % d @var{regexp} @key{RET} -Flag for deletion all files whose names match the regular expression -@var{regexp}. -@end table - -@kindex # @r{(Dired)} -@findex dired-flag-auto-save-files -@cindex deleting auto-save files - @kbd{#} (@code{dired-flag-auto-save-files}) flags all files whose -names look like auto-save files---that is, files whose names begin and -end with @samp{#}. @xref{Auto Save}. - -@kindex ~ @r{(Dired)} -@findex dired-flag-backup-files - @kbd{~} (@code{dired-flag-backup-files}) flags all files whose names -say they are backup files---that is, files whose names end in -@samp{~}. @xref{Backup}. - -@kindex . @r{(Dired)} -@vindex dired-kept-versions -@findex dired-clean-directory - @kbd{.} (period, @code{dired-clean-directory}) flags just some of -the backup files for deletion: all but the oldest few and newest few -backups of any one file. Normally, the number of newest versions kept -for each file is given by the variable @code{dired-kept-versions} -(@strong{not} @code{kept-new-versions}; that applies only when -saving). The number of oldest versions to keep is given by the -variable @code{kept-old-versions}. - - Period with a positive numeric argument, as in @kbd{C-u 3 .}, -specifies the number of newest versions to keep, overriding -@code{dired-kept-versions}. A negative numeric argument overrides -@code{kept-old-versions}, using minus the value of the argument to -specify the number of oldest versions of each file to keep. - -@kindex % & @r{(Dired)} -@findex dired-flag-garbage-files -@vindex dired-garbage-files-regexp -@cindex deleting some backup files - @kbd{% &} (@code{dired-flag-garbage-files}) flags files whose names -match the regular expression specified by the variable -@code{dired-garbage-files-regexp}. By default, this matches certain -files produced by @TeX{}, @samp{.bak} files, and the @samp{.orig} and -@samp{.rej} files produced by @code{patch}. - -@findex dired-flag-files-regexp -@kindex % d @r{(Dired)} - @kbd{% d} flags all files whose names match a specified regular -expression (@code{dired-flag-files-regexp}). Only the non-directory -part of the file name is used in matching. You can use @samp{^} and -@samp{$} to anchor matches. You can exclude certain subdirectories -from marking by hiding them while you use @kbd{% d}. @xref{Hiding -Subdirectories}. - -@node Dired Visiting -@section Visiting Files in Dired - - There are several Dired commands for visiting or examining the files -listed in the Dired buffer. All of them apply to the current line's -file; if that file is really a directory, these commands invoke Dired on -that subdirectory (making a separate Dired buffer). - -@table @kbd -@item f -@kindex f @r{(Dired)} -@findex dired-find-file -Visit the file described on the current line, like typing @kbd{C-x C-f} -and supplying that file name (@code{dired-find-file}). @xref{Visiting}. - -@item @key{RET} -@itemx e -@kindex RET @r{(Dired)} -@kindex e @r{(Dired)} -Equivalent to @kbd{f}. - -@ignore @c This command seems too risky to document at all. -@item a -@kindex a @r{(Dired)} -@findex dired-find-alternate-file -Like @kbd{f}, but replaces the contents of the Dired buffer with -that of an alternate file or directory (@code{dired-find-alternate-file}). -@end ignore - -@item o -@kindex o @r{(Dired)} -@findex dired-find-file-other-window -Like @kbd{f}, but uses another window to display the file's buffer -(@code{dired-find-file-other-window}). The Dired buffer remains visible -in the first window. This is like using @kbd{C-x 4 C-f} to visit the -file. @xref{Windows}. - -@item C-o -@kindex C-o @r{(Dired)} -@findex dired-display-file -Visit the file described on the current line, and display the buffer in -another window, but do not select that window (@code{dired-display-file}). - -@item Mouse-1 -@itemx Mouse-2 -@findex dired-mouse-find-file-other-window -Visit the file whose name you clicked on -(@code{dired-mouse-find-file-other-window}). This uses another window -to display the file, like the @kbd{o} command. - -@item v -@kindex v @r{(Dired)} -@findex dired-view-file -View the file described on the current line, with View mode -(@code{dired-view-file}). View mode provides convenient commands to -navigate the buffer but forbids changing it; @xref{View Mode}. - -@item ^ -@kindex ^ @r{(Dired)} -@findex dired-up-directory -Visit the parent directory of the current directory -(@code{dired-up-directory}). This is equivalent to moving to the line -for @file{..} and typing @kbd{f} there. -@end table - -@node Marks vs Flags -@section Dired Marks vs. Flags - -@cindex marking many files (in Dired) - Instead of flagging a file with @samp{D}, you can @dfn{mark} the -file with some other character (usually @samp{*}). Most Dired -commands to operate on files use the files marked with @samp{*}. The -only command that operates on flagged files is @kbd{x}, which deletes -them. - - Here are some commands for marking with @samp{*}, for unmarking, and -for operating on marks. (@xref{Dired Deletion}, for commands to flag -and unflag files.) - -@table @kbd -@item m -@itemx * m -@kindex m @r{(Dired)} -@kindex * m @r{(Dired)} -@findex dired-mark -Mark the current file with @samp{*} (@code{dired-mark}). With a numeric -argument @var{n}, mark the next @var{n} files starting with the current -file. (If @var{n} is negative, mark the previous @minus{}@var{n} -files.) - -@item * * -@kindex * * @r{(Dired)} -@findex dired-mark-executables -@cindex marking executable files (in Dired) -Mark all executable files with @samp{*} -(@code{dired-mark-executables}). With a numeric argument, unmark all -those files. - -@item * @@ -@kindex * @@ @r{(Dired)} -@findex dired-mark-symlinks -@cindex marking symbolic links (in Dired) -Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}). -With a numeric argument, unmark all those files. - -@item * / -@kindex * / @r{(Dired)} -@findex dired-mark-directories -@cindex marking subdirectories (in Dired) -Mark with @samp{*} all files which are directories, except for -@file{.} and @file{..} (@code{dired-mark-directories}). With a numeric -argument, unmark all those files. - -@item * s -@kindex * s @r{(Dired)} -@findex dired-mark-subdir-files -Mark all the files in the current subdirectory, aside from @file{.} -and @file{..} (@code{dired-mark-subdir-files}). - -@item u -@itemx * u -@kindex u @r{(Dired)} -@kindex * u @r{(Dired)} -@findex dired-unmark -Remove any mark on this line (@code{dired-unmark}). - -@item @key{DEL} -@itemx * @key{DEL} -@kindex * DEL @r{(Dired)} -@findex dired-unmark-backward -@cindex unmarking files (in Dired) -Move point to previous line and remove any mark on that line -(@code{dired-unmark-backward}). - -@item * ! -@itemx U -@kindex * ! @r{(Dired)} -@kindex U @r{(Dired)} -@findex dired-unmark-all-marks -Remove all marks from all the files in this Dired buffer -(@code{dired-unmark-all-marks}). - -@item * ? @var{markchar} -@itemx M-@key{DEL} -@kindex * ? @r{(Dired)} -@kindex M-DEL @r{(Dired)} -@findex dired-unmark-all-files -Remove all marks that use the character @var{markchar} -(@code{dired-unmark-all-files}). The argument is a single -character---do not use @key{RET} to terminate it. See the description -of the @kbd{* c} command below, which lets you replace one mark -character with another. - -With a numeric argument, this command queries about each marked file, -asking whether to remove its mark. You can answer @kbd{y} meaning yes, -@kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining -files without asking about them. - -@item * C-n -@itemx M-@} -@findex dired-next-marked-file -@kindex * C-n @r{(Dired)} -@kindex M-@} @r{(Dired)} -Move down to the next marked file (@code{dired-next-marked-file}) -A file is ``marked'' if it has any kind of mark. - -@item * C-p -@itemx M-@{ -@findex dired-prev-marked-file -@kindex * C-p @r{(Dired)} -@kindex M-@{ @r{(Dired)} -Move up to the previous marked file (@code{dired-prev-marked-file}) - -@item t -@itemx * t -@kindex t @r{(Dired)} -@kindex * t @r{(Dired)} -@findex dired-toggle-marks -@cindex toggling marks (in Dired) -Toggle all marks (@code{dired-toggle-marks}): files marked with @samp{*} -become unmarked, and unmarked files are marked with @samp{*}. Files -marked in any other way are not affected. - -@item * c @var{old-markchar} @var{new-markchar} -@kindex * c @r{(Dired)} -@findex dired-change-marks -Replace all marks that use the character @var{old-markchar} with marks -that use the character @var{new-markchar} (@code{dired-change-marks}). -This command is the primary way to create or use marks other than -@samp{*} or @samp{D}. The arguments are single characters---do not use -@key{RET} to terminate them. - -You can use almost any character as a mark character by means of this -command, to distinguish various classes of files. If @var{old-markchar} -is a space (@samp{ }), then the command operates on all unmarked files; -if @var{new-markchar} is a space, then the command unmarks the files it -acts on. - -To illustrate the power of this command, here is how to put @samp{D} -flags on all the files that have no marks, while unflagging all those -that already have @samp{D} flags: - -@example -* c D t * c SPC D * c t SPC -@end example - -This assumes that no files were already marked with @samp{t}. - -@item % m @var{regexp} @key{RET} -@itemx * % @var{regexp} @key{RET} -@findex dired-mark-files-regexp -@kindex % m @r{(Dired)} -@kindex * % @r{(Dired)} -Mark (with @samp{*}) all files whose names match the regular expression -@var{regexp} (@code{dired-mark-files-regexp}). This command is like -@kbd{% d}, except that it marks files with @samp{*} instead of flagging -with @samp{D}. - -Only the non-directory part of the file name is used in matching. Use -@samp{^} and @samp{$} to anchor matches. You can exclude -subdirectories by temporarily hiding them (@pxref{Hiding -Subdirectories}). - -@item % g @var{regexp} @key{RET} -@findex dired-mark-files-containing-regexp -@kindex % g @r{(Dired)} -@cindex finding files containing regexp matches (in Dired) -Mark (with @samp{*}) all files whose @emph{contents} contain a match for -the regular expression @var{regexp} -(@code{dired-mark-files-containing-regexp}). This command is like -@kbd{% m}, except that it searches the file contents instead of the file -name. - -@item C-/ -@itemx C-x u -@itemx C-_ -@kindex C-_ @r{(Dired)} -@findex dired-undo -Undo changes in the Dired buffer, such as adding or removing -marks (@code{dired-undo}). @emph{This command does not revert the -actual file operations, nor recover lost files!} It just undoes -changes in the buffer itself. - -In some cases, using this after commands that operate on files can -cause trouble. For example, after renaming one or more files, -@code{dired-undo} restores the original names in the Dired buffer, -which gets the Dired buffer out of sync with the actual contents of -the directory. -@end table - -@node Operating on Files -@section Operating on Files -@cindex operating on files in Dired - - This section describes the basic Dired commands to operate on one file -or several files. All of these commands are capital letters; all of -them use the minibuffer, either to read an argument or to ask for -confirmation, before they act. All of them let you specify the -files to manipulate in these ways: - -@itemize @bullet -@item -If you give the command a numeric prefix argument @var{n}, it operates -on the next @var{n} files, starting with the current file. (If @var{n} -is negative, the command operates on the @minus{}@var{n} files preceding -the current line.) - -@item -Otherwise, if some files are marked with @samp{*}, the command operates -on all those files. - -@item -Otherwise, the command operates on the current file only. -@end itemize - -@noindent -Certain other Dired commands, such as @kbd{!} and the @samp{%} -commands, use the same conventions to decide which files to work on. - -@vindex dired-dwim-target -@cindex two directories (in Dired) - Commands which ask for a destination directory, such as those which -copy and rename files or create links for them, try to guess the default -target directory for the operation. Normally, they suggest the Dired -buffer's default directory, but if the variable @code{dired-dwim-target} -is non-@code{nil}, and if there is another Dired buffer displayed in the -next window, that other buffer's directory is suggested instead. - - Here are the file-manipulating Dired commands that operate on files. - -@table @kbd -@findex dired-do-copy -@kindex C @r{(Dired)} -@cindex copying files (in Dired) -@item C @var{new} @key{RET} -Copy the specified files (@code{dired-do-copy}). The argument @var{new} -is the directory to copy into, or (if copying a single file) the new -name. This is like the shell command @code{cp}. - -@vindex dired-copy-preserve-time -If @code{dired-copy-preserve-time} is non-@code{nil}, then copying -with this command preserves the modification time of the old file in -the copy, like @samp{cp -p}. - -@vindex dired-recursive-copies -@cindex recursive copying -The variable @code{dired-recursive-copies} controls whether to copy -directories recursively (like @samp{cp -r}). The default is -@code{top}, which means to ask before recursively copying a directory. - -@item D -@findex dired-do-delete -@kindex D @r{(Dired)} -Delete the specified files (@code{dired-do-delete}). This is like the -shell command @code{rm}. - -Like the other commands in this section, this command operates on the -@emph{marked} files, or the next @var{n} files. By contrast, @kbd{x} -(@code{dired-do-flagged-delete}) deletes all @dfn{flagged} files. - -@findex dired-do-rename -@kindex R @r{(Dired)} -@cindex renaming files (in Dired) -@cindex moving files (in Dired) -@item R @var{new} @key{RET} -Rename the specified files (@code{dired-do-rename}). If you rename a -single file, the argument @var{new} is the new name of the file. If -you rename several files, the argument @var{new} is the directory into -which to move the files (this is like the shell command @command{mv}). - -Dired automatically changes the visited file name of buffers associated -with renamed files so that they refer to the new names. - -@findex dired-do-hardlink -@kindex H @r{(Dired)} -@cindex hard links (in Dired) -@item H @var{new} @key{RET} -Make hard links to the specified files (@code{dired-do-hardlink}). -This is like the shell command @command{ln}. The argument @var{new} is -the directory to make the links in, or (if making just one link) the -name to give the link. - -@findex dired-do-symlink -@kindex S @r{(Dired)} -@cindex symbolic links (creation in Dired) -@item S @var{new} @key{RET} -Make symbolic links to the specified files (@code{dired-do-symlink}). -This is like @samp{ln -s}. The argument @var{new} is the directory to -make the links in, or (if making just one link) the name to give the -link. - -@findex dired-do-chmod -@kindex M @r{(Dired)} -@cindex changing file permissions (in Dired) -@item M @var{modespec} @key{RET} -Change the mode (also called @dfn{permission bits}) of the specified -files (@code{dired-do-chmod}). @var{modespec} can be in octal or -symbolic notation, like arguments handled by the @command{chmod} -program. - -@findex dired-do-chgrp -@kindex G @r{(Dired)} -@cindex changing file group (in Dired) -@item G @var{newgroup} @key{RET} -Change the group of the specified files to @var{newgroup} -(@code{dired-do-chgrp}). - -@findex dired-do-chown -@kindex O @r{(Dired)} -@cindex changing file owner (in Dired) -@item O @var{newowner} @key{RET} -Change the owner of the specified files to @var{newowner} -(@code{dired-do-chown}). (On most systems, only the superuser can do -this.) - -@vindex dired-chown-program -The variable @code{dired-chown-program} specifies the name of the -program to use to do the work (different systems put @command{chown} -in different places). - -@findex dired-do-touch -@kindex T @r{(Dired)} -@cindex changing file time (in Dired) -@item T @var{timestamp} @key{RET} -Touch the specified files (@code{dired-do-touch}). This means -updating their modification times to the present time. This is like -the shell command @code{touch}. - -@findex dired-do-print -@kindex P @r{(Dired)} -@cindex printing files (in Dired) -@item P @var{command} @key{RET} -Print the specified files (@code{dired-do-print}). You must specify the -command to print them with, but the minibuffer starts out with a -suitable guess made using the variables @code{lpr-command} and -@code{lpr-switches} (the same variables that @code{lpr-buffer} uses; -@pxref{Printing}). - -@findex dired-do-compress -@kindex Z @r{(Dired)} -@cindex compressing files (in Dired) -@item Z -Compress the specified files (@code{dired-do-compress}). If the file -appears to be a compressed file already, uncompress it instead. - -@findex epa-dired-do-decrypt -@kindex :d @r{(Dired)} -@cindex decrypting files (in Dired) -@item :d -Decrypt the specified files (@code{epa-dired-do-decrypt}). -@xref{Dired integration,,, epa, EasyPG Assistant User's Manual}. - -@findex epa-dired-do-verify -@kindex :v @r{(Dired)} -@cindex verifying digital signatures on files (in Dired) -@item :v -Verify digital signatures on the specified files (@code{epa-dired-do-verify}). -@xref{Dired integration,,, epa, EasyPG Assistant User's Manual}. - -@findex epa-dired-do-sign -@kindex :s @r{(Dired)} -@cindex signing files (in Dired) -@item :s -Digitally sign the specified files (@code{epa-dired-do-sign}). -@xref{Dired integration,,, epa, EasyPG Assistant User's Manual}. - -@findex epa-dired-do-encrypt -@kindex :e @r{(Dired)} -@cindex encrypting files (in Dired) -@item :e -Encrypt the specified files (@code{epa-dired-do-encrypt}). -@xref{Dired integration,,, epa, EasyPG Assistant User's Manual}. - -@findex dired-do-load -@kindex L @r{(Dired)} -@cindex loading several files (in Dired) -@item L -Load the specified Emacs Lisp files (@code{dired-do-load}). -@xref{Lisp Libraries}. - -@findex dired-do-byte-compile -@kindex B @r{(Dired)} -@cindex byte-compiling several files (in Dired) -@item B -Byte compile the specified Emacs Lisp files -(@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte -Compilation, elisp, The Emacs Lisp Reference Manual}. - -@kindex A @r{(Dired)} -@findex dired-do-search -@cindex search multiple files (in Dired) -@item A @var{regexp} @key{RET} -Search all the specified files for the regular expression @var{regexp} -(@code{dired-do-search}). - -This command is a variant of @code{tags-search}. The search stops at -the first match it finds; use @kbd{M-,} to resume the search and find -the next match. @xref{Tags Search}. - -@kindex Q @r{(Dired)} -@findex dired-do-query-replace-regexp -@cindex search and replace in multiple files (in Dired) -@item Q @var{regexp} @key{RET} @var{to} @key{RET} -Perform @code{query-replace-regexp} on each of the specified files, -replacing matches for @var{regexp} with the string -@var{to} (@code{dired-do-query-replace-regexp}). - -This command is a variant of @code{tags-query-replace}. If you exit the -query replace loop, you can use @kbd{M-,} to resume the scan and replace -more matches. @xref{Tags Search}. -@end table - -@node Shell Commands in Dired -@section Shell Commands in Dired -@cindex shell commands, Dired - -@findex dired-do-shell-command -@kindex ! @r{(Dired)} -@kindex X @r{(Dired)} -The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a -shell command string in the minibuffer and runs that shell command on -one or more files. The files that the shell command operates on are -determined in the usual way for Dired commands (@pxref{Operating on -Files}). The command @kbd{X} is a synonym for @kbd{!}. - - The command @kbd{&} (@code{dired-do-async-shell-command}) does the -same, except that it runs the shell command asynchronously. You can -also do this with @kbd{!}, by appending a @samp{&} character to the -end of the shell command. - - For both @kbd{!} and @kbd{&}, the working directory for the shell -command is the top-level directory of the Dired buffer. - - If you tell @kbd{!} or @kbd{&} to operate on more than one file, the -shell command string determines how those files are passed to the -shell command: - -@itemize @bullet -@item -If you use @samp{*} surrounded by whitespace in the command string, -then the command runs just once, with the list of file names -substituted for the @samp{*}. The order of file names is the order of -appearance in the Dired buffer. - -Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire -list of file names, putting them into one tar file @file{foo.tar}. - -If you want to use @samp{*} as a shell wildcard with whitespace around -it, write @samp{*""}. In the shell, this is equivalent to @samp{*}; -but since the @samp{*} is not surrounded by whitespace, Dired does not -treat it specially. - -@item -Otherwise, if the command string contains @samp{?} surrounded by -whitespace, Emacs runs the shell command once @emph{for each file}, -substituting the current file name for @samp{?} each time. You can -use @samp{?} more than once in the command; the same file name -replaces each occurrence. - -@item -If the command string contains neither @samp{*} nor @samp{?}, Emacs -runs the shell command once for each file, adding the file name at the -end. For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on -each file. -@end itemize - - To iterate over the file names in a more complicated fashion, use an -explicit shell loop. For example, here is how to uuencode each file, -making the output file name by appending @samp{.uu} to the input file -name: - -@example -for file in * ; do uuencode "$file" "$file" >"$file".uu; done -@end example - - The @kbd{!} and @kbd{&} commands do not attempt to update the Dired -buffer to show new or modified files, because they don't know what -files will be changed. Use the @kbd{g} command to update the Dired -buffer (@pxref{Dired Updating}). - - @xref{Single Shell}, for information about running shell commands -outside Dired. - -@node Transforming File Names -@section Transforming File Names in Dired - - This section describes Dired commands which alter file names in a -systematic way. Each command operates on some or all of the marked -files, using a new name made by transforming the existing name. - - Like the basic Dired file-manipulation commands (@pxref{Operating on -Files}), the commands described here operate either on the next -@var{n} files, or on all files marked with @samp{*}, or on the current -file. (To mark files, use the commands described in @ref{Marks vs -Flags}.) - - All of the commands described in this section work -@emph{interactively}: they ask you to confirm the operation for each -candidate file. Thus, you can select more files than you actually -need to operate on (e.g., with a regexp that matches many files), and -then filter the selected names by typing @kbd{y} or @kbd{n} when the -command prompts for confirmation. - -@table @kbd -@findex dired-upcase -@kindex % u @r{(Dired)} -@cindex upcase file names -@item % u -Rename each of the selected files to an upper-case name -(@code{dired-upcase}). If the old file names are @file{Foo} -and @file{bar}, the new names are @file{FOO} and @file{BAR}. - -@item % l -@findex dired-downcase -@kindex % l @r{(Dired)} -@cindex downcase file names -Rename each of the selected files to a lower-case name -(@code{dired-downcase}). If the old file names are @file{Foo} and -@file{bar}, the new names are @file{foo} and @file{bar}. - -@item % R @var{from} @key{RET} @var{to} @key{RET} -@kindex % R @r{(Dired)} -@findex dired-do-rename-regexp -@itemx % C @var{from} @key{RET} @var{to} @key{RET} -@kindex % C @r{(Dired)} -@findex dired-do-copy-regexp -@itemx % H @var{from} @key{RET} @var{to} @key{RET} -@kindex % H @r{(Dired)} -@findex dired-do-hardlink-regexp -@itemx % S @var{from} @key{RET} @var{to} @key{RET} -@kindex % S @r{(Dired)} -@findex dired-do-symlink-regexp -These four commands rename, copy, make hard links and make soft links, -in each case computing the new name by regular-expression substitution -from the name of the old file. -@end table - - The four regular-expression substitution commands effectively -perform a search-and-replace on the selected file names. They read -two arguments: a regular expression @var{from}, and a substitution -pattern @var{to}; they match each ``old'' file name against -@var{from}, and then replace the matching part with @var{to}. You can -use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to all or -part of what the pattern matched in the old file name, as in -@code{replace-regexp} (@pxref{Regexp Replace}). If the regular -expression matches more than once in a file name, only the first match -is replaced. - - For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each -selected file by prepending @samp{x-} to its name. The inverse of this, -removing @samp{x-} from the front of each file name, is also possible: -one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is -@kbd{% R ^x- @key{RET} @key{RET}}. (Use @samp{^} and @samp{$} to anchor -matches that should span the whole file name.) - - Normally, the replacement process does not consider the files' -directory names; it operates on the file name within the directory. If -you specify a numeric argument of zero, then replacement affects the -entire absolute file name including directory name. (A non-zero -argument specifies the number of files to operate on.) - - You may want to select the set of files to operate on using the same -regexp @var{from} that you will use to operate on them. To do this, -mark those files with @kbd{% m @var{from} @key{RET}}, then use the -same regular expression in the command to operate on the files. To -make this more convenient, the @kbd{%} commands to operate on files -use the last regular expression specified in any @kbd{%} command as a -default. - -@node Comparison in Dired -@section File Comparison with Dired -@cindex file comparison (in Dired) -@cindex compare files (in Dired) - - Here are two Dired commands that compare specified files using -@code{diff}. They show the output in a buffer using Diff mode -(@pxref{Comparing Files}). - -@table @kbd -@item = -@findex dired-diff -@kindex = @r{(Dired)} -Compare the current file (the file at point) with another file (the -file at the mark) using the @code{diff} program (@code{dired-diff}). -The file at the mark is the first argument of @code{diff}, and the -file at point is the second argument. This refers to the ordinary -Emacs mark, not Dired marks; use @kbd{C-@key{SPC}} -(@code{set-mark-command}) to set the mark at the first file's line -(@pxref{Setting Mark}). - -@findex dired-backup-diff -@kindex M-= @r{(Dired)} -@item M-= -Compare the current file with its latest backup file -(@code{dired-backup-diff}). If the current file is itself a backup, -compare it with the file it is a backup of; this way, you can compare -a file with any one of its backups. - -The backup file is the first file given to @code{diff}. -@end table - -@node Subdirectories in Dired -@section Subdirectories in Dired -@cindex subdirectories in Dired -@cindex expanding subdirectories in Dired - - A Dired buffer usually displays just one directory, but you can -optionally include its subdirectories as well. - - The simplest way to include multiple directories in one Dired buffer is -to specify the options @samp{-lR} for running @command{ls}. (If you give a -numeric argument when you run Dired, then you can specify these options -in the minibuffer.) That produces a recursive directory listing showing -all subdirectories at all levels. - - More often, you will want to show only specific subdirectories. You -can do this with @kbd{i} (@code{dired-maybe-insert-subdir}): - -@table @kbd -@findex dired-maybe-insert-subdir -@kindex i @r{(Dired)} -@item i -@cindex inserted subdirectory (Dired) -@cindex in-situ subdirectory (Dired) -Insert the contents of a subdirectory later in the buffer. -@end table - -@noindent -If you use this command on a line that describes a file which is a -directory, it inserts the contents of that directory into the same -Dired buffer, and moves there. Inserted subdirectory contents follow -the top-level directory of the Dired buffer, just as they do in -@samp{ls -lR} output. - - If the subdirectory's contents are already present in the buffer, -the @kbd{i} command just moves to it. - - In either case, @kbd{i} sets the Emacs mark before moving, so -@kbd{C-u C-@key{SPC}} returns to your previous position in the Dired -buffer (@pxref{Setting Mark}). You can also use @samp{^} to return to -the parent directory in the same Dired buffer (@pxref{Dired -Visiting}). - - Use the @kbd{l} command (@code{dired-do-redisplay}) to update the -subdirectory's contents, and use @kbd{C-u k} on the subdirectory -header line to remove the subdirectory listing (@pxref{Dired -Updating}). You can also hide and show inserted subdirectories -(@pxref{Hiding Subdirectories}). - -@ifnottex -@include dired-xtra.texi -@end ifnottex - -@node Subdirectory Motion -@section Moving Over Subdirectories - - When a Dired buffer lists subdirectories, you can use the page motion -commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories -(@pxref{Pages}). - -@cindex header line (Dired) -@cindex directory header lines - The following commands move across, up and down in the tree of -directories within one Dired buffer. They move to @dfn{directory header -lines}, which are the lines that give a directory's name, at the -beginning of the directory's contents. - -@table @kbd -@findex dired-next-subdir -@kindex C-M-n @r{(Dired)} -@item C-M-n -Go to next subdirectory header line, regardless of level -(@code{dired-next-subdir}). - -@findex dired-prev-subdir -@kindex C-M-p @r{(Dired)} -@item C-M-p -Go to previous subdirectory header line, regardless of level -(@code{dired-prev-subdir}). - -@findex dired-tree-up -@kindex C-M-u @r{(Dired)} -@item C-M-u -Go up to the parent directory's header line (@code{dired-tree-up}). - -@findex dired-tree-down -@kindex C-M-d @r{(Dired)} -@item C-M-d -Go down in the directory tree, to the first subdirectory's header line -(@code{dired-tree-down}). - -@findex dired-prev-dirline -@kindex < @r{(Dired)} -@item < -Move up to the previous directory-file line (@code{dired-prev-dirline}). -These lines are the ones that describe a directory as a file in its -parent directory. - -@findex dired-next-dirline -@kindex > @r{(Dired)} -@item > -Move down to the next directory-file line (@code{dired-prev-dirline}). -@end table - -@node Hiding Subdirectories -@section Hiding Subdirectories -@cindex hiding subdirectories (Dired) -@cindex showing hidden subdirectories (Dired) - - @dfn{Hiding} a subdirectory means to make it invisible, except for its -header line. - -@table @kbd -@item $ -@findex dired-hide-subdir -@kindex $ @r{(Dired)} -Hide or show the subdirectory that point is in, and move point to the -next subdirectory (@code{dired-hide-subdir}). This is a toggle. A -numeric argument serves as a repeat count. - -@item M-$ -@findex dired-hide-all -@kindex M-$ @r{(Dired)} -Hide all subdirectories in this Dired buffer, leaving only their header -lines (@code{dired-hide-all}). Or, if any subdirectory is currently -hidden, make all subdirectories visible again. You can use this command -to get an overview in very deep directory trees or to move quickly to -subdirectories far away. -@end table - - Ordinary Dired commands never consider files inside a hidden -subdirectory. For example, the commands to operate on marked files -ignore files in hidden directories even if they are marked. Thus you -can use hiding to temporarily exclude subdirectories from operations -without having to remove the Dired marks on files in those -subdirectories. - -@xref{Dired Updating}, for how to insert or delete a subdirectory listing. - -@node Dired Updating -@section Updating the Dired Buffer -@cindex updating Dired buffer -@cindex refreshing displayed files - - This section describes commands to update the Dired buffer to reflect -outside (non-Dired) changes in the directories and files, and to delete -part of the Dired buffer. - -@table @kbd -@item g -Update the entire contents of the Dired buffer (@code{revert-buffer}). - -@item l -Update the specified files (@code{dired-do-redisplay}). You specify the -files for @kbd{l} in the same way as for file operations. - -@item k -Delete the specified @emph{file lines}---not the files, just the lines -(@code{dired-do-kill-lines}). - -@item s -Toggle between alphabetical order and date/time order -(@code{dired-sort-toggle-or-edit}). - -@item C-u s @var{switches} @key{RET} -Refresh the Dired buffer using @var{switches} as -@code{dired-listing-switches}. -@end table - -@kindex g @r{(Dired)} -@findex revert-buffer @r{(Dired)} - Type @kbd{g} (@code{revert-buffer}) to update the contents of the -Dired buffer, based on changes in the files and directories listed. -This preserves all marks except for those on files that have vanished. -Hidden subdirectories are updated but remain hidden. - -@kindex l @r{(Dired)} -@findex dired-do-redisplay - To update only some of the files, type @kbd{l} -(@code{dired-do-redisplay}). Like the Dired file-operating commands, -this command operates on the next @var{n} files (or previous -@minus{}@var{n} files), or on the marked files if any, or on the -current file. Updating the files means reading their current status, -then updating their lines in the buffer to indicate that status. - - If you use @kbd{l} on a subdirectory header line, it updates the -contents of the corresponding subdirectory. - -@vindex dired-auto-revert-buffer - If you use @kbd{C-x d} or some other Dired command to visit a -directory that is already being shown in a Dired buffer, Dired -switches to that buffer but does not update it. If the buffer is not -up-to-date, Dired displays a warning telling you to type @key{g} to -update it. You can also tell Emacs to revert each Dired buffer -automatically when you revisit it, by setting the variable -@code{dired-auto-revert-buffer} to a non-@code{nil} value. - -@kindex k @r{(Dired)} -@findex dired-do-kill-lines - To delete the specified @emph{file lines} from the buffer---not -delete the files---type @kbd{k} (@code{dired-do-kill-lines}). Like -the file-operating commands, this command operates on the next @var{n} -files, or on the marked files if any; but it does not operate on the -current file as a last resort. - - If you use @kbd{k} with a numeric prefix argument to kill the line -for a file that is a directory, which you have inserted in the Dired -buffer as a subdirectory, it removed that subdirectory line from the -buffer as well. Typing @kbd{C-u k} on the header line for a -subdirectory also removes the subdirectory line from the Dired buffer. - - The @kbd{g} command brings back any individual lines that you have -killed in this way, but not subdirectories---you must use @kbd{i} to -reinsert a subdirectory. - -@cindex Dired sorting -@cindex sorting Dired buffer -@kindex s @r{(Dired)} -@findex dired-sort-toggle-or-edit - The files in a Dired buffers are normally listed in alphabetical order -by file names. Alternatively Dired can sort them by date/time. The -Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches -between these two sorting modes. The mode line in a Dired buffer -indicates which way it is currently sorted---by name, or by date. - - @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for -@code{dired-listing-switches}. - -@node Dired and Find -@section Dired and @code{find} -@cindex @code{find} and Dired - - You can select a set of files for display in a Dired buffer more -flexibly by using the @command{find} utility to choose the files. - -@findex find-name-dired - To search for files with names matching a wildcard pattern use -@kbd{M-x find-name-dired}. It reads arguments @var{directory} and -@var{pattern}, and chooses all the files in @var{directory} or its -subdirectories whose individual names match @var{pattern}. - - The files thus chosen are displayed in a Dired buffer, in which the -ordinary Dired commands are available. - -@findex find-grep-dired - If you want to test the contents of files, rather than their names, -use @kbd{M-x find-grep-dired}. This command reads two minibuffer -arguments, @var{directory} and @var{regexp}; it chooses all the files -in @var{directory} or its subdirectories that contain a match for -@var{regexp}. It works by running the programs @command{find} and -@command{grep}. See also @kbd{M-x grep-find}, in @ref{Grep -Searching}. Remember to write the regular expression for -@command{grep}, not for Emacs. (An alternative method of showing -files whose contents match a given regexp is the @kbd{% g -@var{regexp}} command, see @ref{Marks vs Flags}.) - -@findex find-dired - The most general command in this series is @kbd{M-x find-dired}, -which lets you specify any condition that @command{find} can test. It -takes two minibuffer arguments, @var{directory} and @var{find-args}; -it runs @command{find} in @var{directory}, passing @var{find-args} to -tell @command{find} what condition to test. To use this command, you -need to know how to use @command{find}. - -@vindex find-ls-option - The format of listing produced by these commands is controlled by -the variable @code{find-ls-option}. This is a pair of options; the -first specifying how to call @command{find} to produce the file listing, -and the second telling Dired to parse the output. - -@findex locate -@findex locate-with-filter -@cindex file database (locate) -@vindex locate-command - The command @kbd{M-x locate} provides a similar interface to the -@command{locate} program. @kbd{M-x locate-with-filter} is similar, but -keeps only files whose names match a given regular expression. - - These buffers don't work entirely like ordinary Dired buffers: file -operations work, but do not always automatically update the buffer. -Reverting the buffer with @kbd{g} deletes all inserted subdirectories, -and erases all flags and marks. - -@node Wdired -@section Editing the Dired Buffer - -@cindex wdired mode -@findex wdired-change-to-wdired-mode - Wdired is a special mode that allows you to perform file operations -by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands -for ``writable''.) To enter Wdired mode, type @kbd{C-x C-q} -(@code{dired-toggle-read-only}) while in a Dired buffer. -Alternatively, use the @samp{Immediate / Edit File Names} menu item. - -@findex wdired-finish-edit - While in Wdired mode, you can rename files by editing the file names -displayed in the Dired buffer. All the ordinary Emacs editing -commands, including rectangle operations and @code{query-replace}, are -available for this. Once you are done editing, type @kbd{C-c C-c} -(@code{wdired-finish-edit}). This applies your changes and switches -back to ordinary Dired mode. - - Apart from simply renaming files, you can move a file to another -directory by typing in the new file name (either absolute or -relative). To mark a file for deletion, delete the entire file name. -To change the target of a symbolic link, edit the link target name -which appears next to the link name. - - The rest of the text in the buffer, such as the file sizes and -modification dates, is marked read-only, so you can't edit it. -However, if you set @code{wdired-allow-to-change-permissions} to -@code{t}, you can edit the file permissions. For example, you can -change @samp{-rw-r--r--} to @samp{-rw-rw-rw-} to make a file -world-writable. These changes also take effect when you type @kbd{C-c -C-c}. - -@node Image-Dired -@section Viewing Image Thumbnails in Dired -@cindex image-dired mode -@cindex image-dired - - Image-Dired is a facility for browsing image files. It provides viewing -the images either as thumbnails or in full size, either inside Emacs -or through an external viewer. - -@kindex C-t d @r{(Image-Dired)} -@findex image-dired-display-thumbs - To enter Image-Dired, mark the image files you want to look at in -the Dired buffer, using @kbd{m} as usual. Then type @kbd{C-t d} -(@code{image-dired-display-thumbs}). This creates and switches to a -buffer containing image-dired, corresponding to the marked files. - - You can also enter Image-Dired directly by typing @kbd{M-x -image-dired}. This prompts for a directory; specify one that has -image files. This creates thumbnails for all the images in that -directory, and displays them all in the ``thumbnail buffer''. This -takes a long time if the directory contains many image files, and it -asks for confirmation if the number of image files exceeds -@code{image-dired-show-all-from-dir-max-files}. - - With point in the thumbnail buffer, you can type @kbd{RET} -(@code{image-dired-display-thumbnail-original-image}) to display a -sized version of it in another window. This sizes the image to fit -the window. Use the arrow keys to move around in the buffer. For -easy browsing, use @kbd{SPC} -(@code{image-dired-display-next-thumbnail-original}) to advance and -display the next image. Typing @kbd{DEL} -(@code{image-dired-display-previous-thumbnail-original}) backs up to -the previous thumbnail and displays that instead. - -@vindex image-dired-external-viewer - To view and the image in its original size, either provide a prefix -argument (@kbd{C-u}) before pressing @kbd{RET}, or type -@kbd{C-@key{RET}} (@code{image-dired-thumbnail-display-external}) to -display the image in an external viewer. You must first configure -@code{image-dired-external-viewer}. - - You can delete images through Image-Dired also. Type @kbd{d} -(@code{image-dired-flag-thumb-original-file}) to flag the image file -for deletion in the Dired buffer. You can also delete the thumbnail -image from the thumbnail buffer with @kbd{C-d} -(@code{image-dired-delete-char}). - - More advanced features include @dfn{image tags}, which are metadata -used to categorize image files. The tags are stored in a plain text -file configured by @code{image-dired-db-file}. - - To tag image files, mark them in the dired buffer (you can also mark -files in Dired from the thumbnail buffer by typing @kbd{m}) and type -@kbd{C-t t} (@code{image-dired-tag-files}). This reads the tag name -in the minibuffer. To mark files having a certain tag, type @kbd{C-t f} -(@code{image-dired-mark-tagged-files}). After marking image files -with a certain tag, you can use @kbd{C-t d} to view them. - - You can also tag a file directly from the thumbnail buffer by typing -@kbd{t t} and you can remove a tag by typing @kbd{t r}. There is also -a special ``tag'' called ``comment'' for each file (it is not a tag in -the exact same sense as the other tags, it is handled slightly -different). That is used to enter a comment or description about the -image. You comment a file from the thumbnail buffer by typing -@kbd{c}. You will be prompted for a comment. Type @kbd{C-t c} to add -a comment from Dired (@code{image-dired-dired-comment-files}). - - Image-Dired also provides simple image manipulation. In the -thumbnail buffer, type @kbd{L} to rotate the original image 90 degrees -anti clockwise, and @kbd{R} to rotate it 90 degrees clockwise. This -rotation is lossless, and uses an external utility called JpegTRAN. - -@node Misc Dired Features -@section Other Dired Features - -@kindex + @r{(Dired)} -@findex dired-create-directory - The command @kbd{+} (@code{dired-create-directory}) reads a -directory name, and creates that directory. It signals an error if -the directory already exists. - -@cindex searching multiple files via Dired -@kindex M-s a C-s @r{(Dired)} -@kindex M-s a M-C-s @r{(Dired)} -@findex dired-do-isearch -@findex dired-do-isearch-regexp - The command @kbd{M-s a C-s} (@code{dired-do-isearch}) begins a -``multi-file'' incremental search on the marked files. If a search -fails at the end of a file, typing @kbd{C-s} advances to the next -marked file and repeats the search; at the end of the last marked -file, the search wraps around to the first marked file. The command -@kbd{M-s a M-C-s} (@code{dired-do-isearch-regexp}) does the same with -a regular expression search. @xref{Repeat Isearch}, for information -about search repetition. - -@cindex Adding to the kill ring in Dired. -@kindex w @r{(Dired)} -@findex dired-copy-filename-as-kill - The command @kbd{w} (@code{dired-copy-filename-as-kill}) puts the -names of the marked (or next @var{n}) files into the kill ring, as if -you had killed them with @kbd{C-w}. The names are separated by a -space. - - With a zero prefix argument, this uses the absolute file name of -each marked file. With just @kbd{C-u} as the prefix argument, it uses -file names relative to the Dired buffer's default directory. (This -can still contain slashes if in a subdirectory.) As a special case, -if point is on a directory headerline, @kbd{w} gives you the absolute -name of that directory. Any prefix argument or marked files are -ignored in this case. - - The main purpose of this command is so that you can yank the file -names into arguments for other Emacs commands. It also displays what -it added to the kill ring, so you can use it to display the list of -currently marked files in the echo area. - -@cindex Dired and version control - If the directory you are visiting is under version control -(@pxref{Version Control}), then the normal VC diff and log commands -will operate on the selected files. - -@findex dired-compare-directories - The command @kbd{M-x dired-compare-directories} is used to compare -the current Dired buffer with another directory. It marks all the files -that are ``different'' between the two directories. It puts these marks -in all Dired buffers where these files are listed, which of course includes -the current buffer. - - The default comparison method (used if you type @key{RET} at the -prompt) is to compare just the file names---each file name that does -not appear in the other directory is ``different''. You can specify -more stringent comparisons by entering a Lisp expression, which can -refer to the variables @code{size1} and @code{size2}, the respective -file sizes; @code{mtime1} and @code{mtime2}, the last modification -times in seconds, as floating point numbers; and @code{fa1} and -@code{fa2}, the respective file attribute lists (as returned by the -function @code{file-attributes}). This expression is evaluated for -each pair of like-named files, and if the expression's value is -non-@code{nil}, those files are considered ``different''. - - For instance, the sequence @code{M-x dired-compare-directories -@key{RET} (> mtime1 mtime2) @key{RET}} marks files newer in this -directory than in the other, and marks files older in the other -directory than in this one. It also marks files with no counterpart, -in both directories, as always. - -@cindex drag and drop, Dired - On the X Window System, Emacs supports the ``drag and drop'' -protocol. You can drag a file object from another program, and drop -it onto a Dired buffer; this either moves, copies, or creates a link -to the file in that directory. Precisely which action is taken is -determined by the originating program. Dragging files out of a Dired -buffer is currently not supported. diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi deleted file mode 100644 index de5e8df9dc5..00000000000 --- a/doc/emacs/display.texi +++ /dev/null @@ -1,1580 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. - -@c See file emacs.texi for copying conditions. -@node Display, Search, Registers, Top -@chapter Controlling the Display - - Since only part of a large buffer fits in the window, Emacs has to -show only a part of it. This chapter describes commands and variables -that let you specify which part of the text you want to see, and how -the text is displayed. - -@menu -* Scrolling:: Commands to move text up and down in a window. -* Recentering:: A scroll command that centers the current line. -* Auto Scrolling:: Redisplay scrolls text automatically when needed. -* Horizontal Scrolling:: Moving text left and right in a window. -* Narrowing:: Restricting display and editing to a portion - of the buffer. -* View Mode:: Viewing read-only buffers. -* Follow Mode:: Follow mode lets two windows scroll as one. -* Faces:: How to change the display style using faces. -* Colors:: Specifying colors for faces. -* Standard Faces:: The main predefined faces. -* Text Scale:: Increasing or decreasing text size in a buffer. -* Font Lock:: Minor mode for syntactic highlighting using faces. -* Highlight Interactively:: Tell Emacs what text to highlight. -* Fringes:: Enabling or disabling window fringes. -* Displaying Boundaries:: Displaying top and bottom of the buffer. -* Useless Whitespace:: Showing possibly spurious trailing whitespace. -* Selective Display:: Hiding lines with lots of indentation. -* Optional Mode Line:: Optional mode line display features. -* Text Display:: How text characters are normally displayed. -* Cursor Display:: Features for displaying the cursor. -* Line Truncation:: Truncating lines to fit the screen width instead - of continuing them to multiple screen lines. -* Visual Line Mode:: Word wrap and screen line-based editing. -* Display Custom:: Information on variables for customizing display. -@end menu - -@node Scrolling -@section Scrolling -@cindex scrolling - - If a window is too small to display all the text in its buffer, it -displays only a portion of it. @dfn{Scrolling} commands change which -portion of the buffer is displayed. - - Scrolling ``forward'' or ``up'' advances the portion of the buffer -displayed in the window; equivalently, it moves the buffer text -upwards relative to the window. Scrolling ``backward'' or ``down'' -displays an earlier portion of the buffer, and moves the text -downwards relative to the window. - - In Emacs, scrolling ``up'' or ``down'' refers to the direction that -the text moves in the window, @emph{not} the direction that the window -moves relative to the text. This terminology was adopted by Emacs -before the modern meaning of ``scrolling up'' and ``scrolling down'' -became widespread. Hence, the strange result that @key{PageDown} -scrolls ``up'' in the Emacs sense. - - The portion of a buffer displayed in a window always contains point. -If you move point past the bottom or top of the window, scrolling -occurs automatically to bring it back onscreen (@pxref{Auto -Scrolling}). You can also scroll explicitly with these commands: - -@table @kbd -@item C-v -@itemx @key{next} -@itemx @key{PageDown} -Scroll forward by nearly a full window (@code{scroll-up-command}). -@item M-v -@itemx @key{prior} -@itemx @key{PageUp} -Scroll backward (@code{scroll-down-command}). -@end table - -@kindex C-v -@kindex M-v -@kindex next -@kindex prior -@kindex PageDown -@kindex PageUp -@findex scroll-up-command -@findex scroll-down-command - @kbd{C-v} (@code{scroll-up-command}) scrolls forward by nearly the -whole window height. The effect is to take the two lines at the -bottom of the window and put them at the top, followed by lines that -were not previously visible. If point was in the text that scrolled -off the top, it ends up on the window's new topmost line. The -@key{next} (or @key{PageDown}) key is equivalent to @kbd{C-v}. - - @kbd{M-v} (@code{scroll-down-command}) scrolls backward in a similar -way. The @key{prior} (or @key{PageUp}) key is equivalent to -@kbd{M-v}. - -@vindex next-screen-context-lines - The number of lines of overlap left by these scroll commands is -controlled by the variable @code{next-screen-context-lines}, whose -default value is 2. You can supply the commands with a numeric prefix -argument, @var{n}, to scroll by @var{n} lines; Emacs attempts to leave -point unchanged, so that the text and point move up or down together. -@kbd{C-v} with a negative argument is like @kbd{M-v} and vice versa. - -@vindex scroll-error-top-bottom - By default, these commands signal an error (by beeping or flashing -the screen) if no more scrolling is possible, because the window has -reached the beginning or end of the buffer. If you change the -variable @code{scroll-error-top-bottom} to @code{t}, the command moves -point to the farthest possible position. If point is already there, -the command signals an error. - -@vindex scroll-preserve-screen-position -@cindex @code{scroll-command} property - Some users like scroll commands to keep point at the same screen -position, so that scrolling back to the same screen conveniently -returns point to its original position. You can enable this behavior -via the variable @code{scroll-preserve-screen-position}. If the value -is @code{t}, Emacs adjusts point to keep the cursor at the same screen -position whenever a scroll command moves it off-window, rather than -moving it to the topmost or bottommost line. With any other -non-@code{nil} value, Emacs adjusts point this way even if the scroll -command leaves point in the window. This variable affects all the -scroll commands documented in this section, as well as scrolling with -the mouse wheel (@pxref{Mouse Commands}); in general, it affects any -command that has a non-@code{nil} @code{scroll-command} property. -@xref{Property Lists,,, elisp, The Emacs Lisp Reference Manual}. - -@vindex scroll-up -@vindex scroll-down -@findex scroll-up-line -@findex scroll-down-line - The commands @kbd{M-x scroll-up} and @kbd{M-x scroll-down} behave -similarly to @code{scroll-up-command} and @code{scroll-down-command}, -except they do not obey @code{scroll-error-top-bottom}. Prior to -Emacs 24, these were the default commands for scrolling up and down. -The commands @kbd{M-x scroll-up-line} and @kbd{M-x scroll-down-line} -scroll the current window by one line at a time. If you intend to use -any of these commands, you might want to give them key bindings -(@pxref{Init Rebinding}). - -@node Recentering -@section Recentering - -@table @kbd -@item C-l -Scroll the selected window so the current line is the center-most text -line; on subsequent consecutive invocations, make the current line the -top line, the bottom line, and so on in cyclic order. Possibly -redisplay the screen too (@code{recenter-top-bottom}). - -@item M-x recenter -Scroll the selected window so the current line is the center-most text -line. Possibly redisplay the screen too. - -@item C-M-l -Scroll heuristically to bring useful information onto the screen -(@code{reposition-window}). -@end table - -@kindex C-l -@findex recenter-top-bottom - The @kbd{C-l} (@code{recenter-top-bottom}) command @dfn{recenters} -the selected window, scrolling it so that the current screen line is -exactly in the center of the window, or as close to the center as -possible. - - Typing @kbd{C-l} twice in a row (@kbd{C-l C-l}) scrolls the window -so that point is on the topmost screen line. Typing a third @kbd{C-l} -scrolls the window so that point is on the bottom-most screen line. -Each successive @kbd{C-l} cycles through these three positions. - -@vindex recenter-positions - You can change the cycling order by customizing the list variable -@code{recenter-positions}. Each list element should be the symbol -@code{top}, @code{middle}, or @code{bottom}, or a number; an integer -means to move the line to the specified screen line, while a -floating-point number between 0.0 and 1.0 specifies a percentage of -the screen space from the top of the window. The default, -@code{(middle top bottom)}, is the cycling order described above. -Furthermore, if you change the variable @code{scroll-margin} to a -non-zero value @var{n}, @kbd{C-l} always leaves at least @var{n} -screen lines between point and the top or bottom of the window -(@pxref{Auto Scrolling}). - - You can also give @kbd{C-l} a prefix argument. A plain prefix -argument, @kbd{C-u C-l}, simply recenters point. A positive argument -@var{n} puts point @var{n} lines down from the top of the window. An -argument of zero puts point on the topmost line. A negative argument -@var{-n} puts point @var{n} lines from the bottom of the window. When -given an argument, @kbd{C-l} does not clear the screen or cycle -through different screen positions. - -@vindex recenter-redisplay - If the variable @code{recenter-redisplay} has a non-@code{nil} -value, each invocation of @kbd{C-l} also clears and redisplays the -screen; the special value @code{tty} (the default) says to do this on -text-terminal frames only. Redisplaying is useful in case the screen -becomes garbled for any reason (@pxref{Screen Garbled}). - -@findex recenter - The more primitive command @kbd{M-x recenter} behaves like -@code{recenter-top-bottom}, but does not cycle among screen positions. - -@kindex C-M-l -@findex reposition-window - @kbd{C-M-l} (@code{reposition-window}) scrolls the current window -heuristically in a way designed to get useful information onto the -screen. For example, in a Lisp file, this command tries to get the -entire current defun onto the screen if possible. - -@node Auto Scrolling -@section Automatic Scrolling - - Emacs performs @dfn{automatic scrolling} when point moves out of the -visible portion of the text. - -@vindex scroll-conservatively - Normally, this centers point vertically within the window. However, -if you set @code{scroll-conservatively} to a small number @var{n}, -then if you move point just a little off the screen (less than @var{n} -lines), Emacs scrolls the text just far enough to bring point back on -screen. By default, @code{scroll-conservatively} is@tie{}0. If you -set @code{scroll-conservatively} to a large number (larger than 100), -Emacs will never center point as result of scrolling, even if point -moves far away from the text previously displayed in the window. With -such a large value, Emacs will always scroll text just enough for -bringing point into view, so point will end up at the top or bottom of -the window, depending on the scroll direction. - -@vindex scroll-step - The variable @code{scroll-step} determines how many lines to scroll -the window when point moves off the screen. If moving by that number -of lines fails to bring point back into view, point is centered -instead. The default value is zero, which causes point to always be -centered after scrolling. - -@cindex aggressive scrolling -@vindex scroll-up-aggressively -@vindex scroll-down-aggressively - When the window does scroll by a distance longer than -@code{scroll-step}, you can control how aggressively it scrolls by -setting the variables @code{scroll-up-aggressively} and -@code{scroll-down-aggressively}. The value of -@code{scroll-up-aggressively} should be either @code{nil}, or a -fraction @var{f} between 0 and 1. A fraction specifies where on the -screen to put point when scrolling upward, i.e.@: forward. When point -goes off the window end, the new start position is chosen to put point -@var{f} parts of the window height from the bottom margin. Thus, -larger @var{f} means more aggressive scrolling: more new text is -brought into view. The default value, @code{nil}, is equivalent to -0.5. - - Likewise, @code{scroll-down-aggressively} is used for scrolling -down, i.e.@: backward. The value specifies how far point should be -placed from the top margin of the window; thus, as with -@code{scroll-up-aggressively}, a larger value is more aggressive. - - These two variables are ignored if either @code{scroll-step} or -@code{scroll-conservatively} are set to a non-zero value. - -@vindex scroll-margin - The variable @code{scroll-margin} restricts how close point can come -to the top or bottom of a window (even if aggressive scrolling -specifies a fraction @var{f} that is larger than the window portion -between the top and the bottom margins). Its value is a number of screen -lines; if point comes within that many lines of the top or bottom of -the window, Emacs performs automatic scrolling. By default, -@code{scroll-margin} is 0. - -@node Horizontal Scrolling -@section Horizontal Scrolling -@cindex horizontal scrolling - -@vindex auto-hscroll-mode - @dfn{Horizontal scrolling} means shifting all the lines sideways -within a window, so that some of the text near the left margin is not -displayed. When the text in a window is scrolled horizontally, text -lines are truncated rather than continued (@pxref{Line Truncation}). -If a window shows truncated lines, Emacs performs automatic horizontal -scrolling whenever point moves off the left or right edge of the -screen. To disable automatic horizontal scrolling, set the variable -@code{auto-hscroll-mode} to @code{nil}. Note that when the automatic -horizontal scrolling is turned off, if point moves off the edge of the -screen, the cursor disappears to indicate that. (On text terminals, -the cursor is left at the edge instead.) - -@vindex hscroll-margin - The variable @code{hscroll-margin} controls how close point can get -to the window's edges before automatic scrolling occurs. It is -measured in columns. For example, if the value is 5, then moving -point within 5 columns of an edge causes horizontal scrolling away -from that edge. - -@vindex hscroll-step - The variable @code{hscroll-step} determines how many columns to -scroll the window when point gets too close to the edge. Zero, the -default value, means to center point horizontally within the window. -A positive integer value specifies the number of columns to scroll by. -A floating-point number specifies the fraction of the window's width -to scroll by. - - You can also perform explicit horizontal scrolling with the -following commands: - -@table @kbd -@item C-x < -Scroll text in current window to the left (@code{scroll-left}). -@item C-x > -Scroll to the right (@code{scroll-right}). -@end table - -@kindex C-x < -@kindex C-x > -@findex scroll-left -@findex scroll-right - @kbd{C-x <} (@code{scroll-left}) scrolls text in the selected window -to the left by the full width of the window, less two columns. (In -other words, the text in the window moves left relative to the -window.) With a numeric argument @var{n}, it scrolls by @var{n} -columns. - - If the text is scrolled to the left, and point moves off the left -edge of the window, the cursor will freeze at the left edge of the -window, until point moves back to the displayed portion of the text. -This is independent of the current setting of -@code{auto-hscroll-mode}, which, for text scrolled to the left, only -affects the behavior at the right edge of the window. - - @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. -The window cannot be scrolled any farther to the right once it is -displayed normally, with each line starting at the window's left -margin; attempting to do so has no effect. This means that you don't -have to calculate the argument precisely for @w{@kbd{C-x >}}; any -sufficiently large argument will restore the normal display. - - If you use those commands to scroll a window horizontally, that sets -a lower bound for automatic horizontal scrolling. Automatic scrolling -will continue to scroll the window, but never farther to the right -than the amount you previously set by @code{scroll-left}. - -@node Narrowing -@section Narrowing -@cindex widening -@cindex restriction -@cindex narrowing -@cindex accessible portion - - @dfn{Narrowing} means focusing in on some portion of the buffer, -making the rest temporarily inaccessible. The portion which you can -still get to is called the @dfn{accessible portion}. Canceling the -narrowing, which makes the entire buffer once again accessible, is -called @dfn{widening}. The bounds of narrowing in effect in a buffer -are called the buffer's @dfn{restriction}. - - Narrowing can make it easier to concentrate on a single subroutine or -paragraph by eliminating clutter. It can also be used to limit the -range of operation of a replace command or repeating keyboard macro. - -@table @kbd -@item C-x n n -Narrow down to between point and mark (@code{narrow-to-region}). -@item C-x n w -Widen to make the entire buffer accessible again (@code{widen}). -@item C-x n p -Narrow down to the current page (@code{narrow-to-page}). -@item C-x n d -Narrow down to the current defun (@code{narrow-to-defun}). -@end table - - When you have narrowed down to a part of the buffer, that part appears -to be all there is. You can't see the rest, you can't move into it -(motion commands won't go outside the accessible part), you can't change -it in any way. However, it is not gone, and if you save the file all -the inaccessible text will be saved. The word @samp{Narrow} appears in -the mode line whenever narrowing is in effect. - -@kindex C-x n n -@findex narrow-to-region - The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}). -It sets the current buffer's restrictions so that the text in the current -region remains accessible, but all text before the region or after the -region is inaccessible. Point and mark do not change. - -@kindex C-x n p -@findex narrow-to-page -@kindex C-x n d -@findex narrow-to-defun - Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow -down to the current page. @xref{Pages}, for the definition of a page. -@kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun -containing point (@pxref{Defuns}). - -@kindex C-x n w -@findex widen - The way to cancel narrowing is to widen with @kbd{C-x n w} -(@code{widen}). This makes all text in the buffer accessible again. - - You can get information on what part of the buffer you are narrowed down -to using the @kbd{C-x =} command. @xref{Position Info}. - - Because narrowing can easily confuse users who do not understand it, -@code{narrow-to-region} is normally a disabled command. Attempting to use -this command asks for confirmation and gives you the option of enabling it; -if you enable the command, confirmation will no longer be required for -it. @xref{Disabling}. - -@node View Mode -@section View Mode -@cindex View mode -@cindex mode, View - -@kindex s @r{(View mode)} -@kindex SPC @r{(View mode)} -@kindex DEL @r{(View mode)} - View mode is a minor mode that lets you scan a buffer by sequential -screenfuls. It provides commands for scrolling through the buffer -conveniently but not for changing it. Apart from the usual Emacs -cursor motion commands, you can type @key{SPC} to scroll forward one -windowful, @key{DEL} to scroll backward, and @kbd{s} to start an -incremental search. - -@kindex q @r{(View mode)} -@kindex e @r{(View mode)} -@findex View-quit -@findex View-exit - Typing @kbd{q} (@code{View-quit}) disables View mode, and switches -back to the buffer and position before View mode was enabled. Typing -@kbd{e} (@code{View-exit}) disables View mode, keeping the current -buffer and position. - -@findex view-buffer -@findex view-file - @kbd{M-x view-buffer} prompts for an existing Emacs buffer, switches -to it, and enables View mode. @kbd{M-x view-file} prompts for a file -and visits it with View mode enabled. - -@node Follow Mode -@section Follow Mode -@cindex Follow mode -@cindex mode, Follow -@findex follow-mode -@cindex windows, synchronizing -@cindex synchronizing windows - - @dfn{Follow mode} is a minor mode that makes two windows, both -showing the same buffer, scroll as a single tall ``virtual window''. -To use Follow mode, go to a frame with just one window, split it into -two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x -follow-mode}. From then on, you can edit the buffer in either of the -two windows, or scroll either one; the other window follows it. - - In Follow mode, if you move point outside the portion visible in one -window and into the portion visible in the other window, that selects -the other window---again, treating the two as if they were parts of -one large window. - - To turn off Follow mode, type @kbd{M-x follow-mode} a second time. - -@node Faces -@section Text Faces -@cindex faces - - Emacs can display text in several different styles, called -@dfn{faces}. Each face can specify various @dfn{face attributes}, -such as the font, height, weight, slant, foreground and background -color, and underlining or overlining. Most major modes assign faces -to the text automatically, via Font Lock mode. @xref{Font Lock}, for -more information about how these faces are assigned. - -@findex list-faces-display - To see what faces are currently defined, and what they look like, -type @kbd{M-x list-faces-display}. With a prefix argument, this -prompts for a regular expression, and displays only faces with names -matching that regular expression (@pxref{Regexps}). - - It's possible for a given face to look different in different -frames. For instance, some text terminals do not support all face -attributes, particularly font, height, and width, and some support a -limited range of colors. - -@cindex background color -@cindex default face - You can customize a face to alter its appearance, and save those -changes for future Emacs sessions. @xref{Face Customization}. A face -does not have to specify every single attribute; often it inherits -most attributes from another face. Any ultimately unspecified -attribute is taken from the face named @code{default}. - - The @code{default} face is the default for displaying text, and all -of its attributes are specified. Its background color is also used as -the frame's background color. @xref{Colors}. - -@cindex cursor face - Another special face is the @code{cursor} face. On graphical -displays, the background color of this face is used to draw the text -cursor. None of the other attributes of this face have any effect; -the foreground color for text under the cursor is taken from the -background color of the underlying text. On text terminals, the -appearance of the text cursor is determined by the terminal, not by -the @code{cursor} face. - - You can also use X resources to specify attributes of any particular -face. @xref{Resources}. - - Emacs can display variable-width fonts, but some Emacs commands, -particularly indentation commands, do not account for variable -character display widths. Therefore, we recommend not using -variable-width fonts for most faces, particularly those assigned by -Font Lock mode. - -@node Colors -@section Colors for Faces -@cindex color name -@cindex RGB triplet - - Faces can have various foreground and background colors. When you -specify a color for a face---for instance, when customizing the face -(@pxref{Face Customization})---you can use either a @dfn{color name} -or an @dfn{RGB triplet}. - -@findex list-colors-display -@vindex list-colors-sort - A color name is a pre-defined name, such as @samp{dark orange} or -@samp{medium sea green}. To view a list of color names, type @kbd{M-x -list-colors-display}. To control the order in which colors are shown, -customize @code{list-colors-sort}. If you run this command on a -graphical display, it shows the full range of color names known to -Emacs (these are the standard X11 color names, defined in X's -@file{rgb.txt} file). If you run the command on a text terminal, it -shows only a small subset of colors that can be safely displayed on -such terminals. However, Emacs understands X11 color names even on -text terminals; if a face is given a color specified by an X11 color -name, it is displayed using the closest-matching terminal color. - - An RGB triplet is a string of the form @samp{#RRGGBB}. Each of the -R, G, and B components is a hexadecimal number specifying the -component's relative intensity, one to four digits long (usually two -digits are used). The components must have the same number of digits. -For hexadecimal values A to F, either upper or lower case are -acceptable. - - The @kbd{M-x list-colors-display} command also shows the equivalent -RGB triplet for each named color. For instance, @samp{medium sea -green} is equivalent to @samp{#3CB371}. - -@cindex face colors, setting -@findex set-face-foreground -@findex set-face-background - You can change the foreground and background colors of a face with -@kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}. -These commands prompt in the minibuffer for a face name and a color, -with completion, and then set that face to use the specified color. -They affect the face colors on all frames, but their effects do not -persist for future Emacs sessions, unlike using the customization -buffer or X resources. You can also use frame parameters to set -foreground and background colors for a specific frame; @xref{Frame -Parameters}. - -@node Standard Faces -@section Standard Faces - - Here are the standard faces for specifying text appearance. You can -apply them to specific text when you want the effects they produce. - -@table @code -@item default -This face is used for ordinary text that doesn't specify any face. -Its background color is used as the frame's background color. -@item bold -This face uses a bold variant of the default font. -@item italic -This face uses an italic variant of the default font. -@item bold-italic -This face uses a bold italic variant of the default font. -@item underline -This face underlines text. -@item fixed-pitch -This face forces use of a fixed-width font. It's reasonable to -customize this face to use a different fixed-width font, if you like, -but you should not make it a variable-width font. -@item variable-pitch -This face forces use of a variable-width font. -@item shadow -This face is used for making the text less noticeable than the surrounding -ordinary text. Usually this can be achieved by using shades of gray in -contrast with either black or white default foreground color. -@end table - - Here's an incomplete list of faces used to highlight parts of the -text temporarily for specific purposes. (Many other modes define -their own faces for this purpose.) - -@table @code -@item highlight -This face is used for text highlighting in various contexts, such as -when the mouse cursor is moved over a hyperlink. -@item isearch -This face is used to highlight the current Isearch match -(@pxref{Incremental Search}). -@item query-replace -This face is used to highlight the current Query Replace match -(@pxref{Replace}). -@item lazy-highlight -This face is used to highlight ``lazy matches'' for Isearch and Query -Replace (matches other than the current one). -@item region -This face is used for displaying an active region (@pxref{Mark}). -When Emacs is built with GTK support, its colors are taken from the -current GTK theme. -@item secondary-selection -This face is used for displaying a secondary X selection (@pxref{Secondary -Selection}). -@item trailing-whitespace -The face for highlighting excess spaces and tabs at the end of a line -when @code{show-trailing-whitespace} is non-@code{nil} (@pxref{Useless -Whitespace}). -@item escape-glyph -The face for displaying control characters and escape sequences -(@pxref{Text Display}). -@item nobreak-space -The face for displaying ``no-break'' space characters (@pxref{Text -Display}). -@end table - - The following faces control the appearance of parts of the Emacs -frame: - -@table @code -@item mode-line -This face is used for the mode line of the currently selected window, -and for menu bars when toolkit menus are not used. By default, it's -drawn with shadows for a ``raised'' effect on graphical displays, and -drawn as the inverse of the default face on non-windowed terminals. -@item mode-line-inactive -Like @code{mode-line}, but used for mode lines of the windows other -than the selected one (if @code{mode-line-in-non-selected-windows} is -non-@code{nil}). This face inherits from @code{mode-line}, so changes -in that face affect mode lines in all windows. -@item mode-line-highlight -Like @code{highlight}, but used for portions of text on mode lines. -@item mode-line-buffer-id -This face is used for buffer identification parts in the mode line. -@item header-line -Similar to @code{mode-line} for a window's header line, which appears -at the top of a window just as the mode line appears at the bottom. -Most windows do not have a header line---only some special modes, such -Info mode, create one. -@item vertical-border -This face is used for the vertical divider between windows on text -terminals. -@item minibuffer-prompt -@cindex @code{minibuffer-prompt} face -@vindex minibuffer-prompt-properties -This face is used for the prompt strings displayed in the minibuffer. -By default, Emacs automatically adds this face to the value of -@code{minibuffer-prompt-properties}, which is a list of text -properties used to display the prompt text. (This variable takes -effect when you enter the minibuffer.) -@item fringe -@cindex @code{fringe} face -The face for the fringes to the left and right of windows on graphic -displays. (The fringes are the narrow portions of the Emacs frame -between the text area and the window's right and left borders.) -@xref{Fringes}. -@item cursor -The @code{:background} attribute of this face specifies the color of -the text cursor. @xref{Cursor Display}. -@item tooltip -This face is used for tooltip text. By default, if Emacs is built -with GTK support, tooltips are drawn via GTK and this face has no -effect. @xref{Tooltips}. -@item mouse -This face determines the color of the mouse pointer. -@end table - - The following faces likewise control the appearance of parts of the -Emacs frame, but only on text terminals, or when Emacs is built on X -with no toolkit support. (For all other cases, the appearance of the -respective frame elements is determined by system-wide settings.) - -@table @code -@item scroll-bar -This face determines the visual appearance of the scroll bar. -@xref{Scroll Bars}. -@item tool-bar -This face determines the color of tool bar icons. @xref{Tool Bars}. -@item menu -@cindex menu bar appearance -@cindex @code{menu} face, no effect if customized -@cindex customization of @code{menu} face -This face determines the colors and font of Emacs's menus. @xref{Menu -Bars}. -@end table - -@node Text Scale -@section Text Scale - -@cindex adjust buffer face height -@findex text-scale-adjust -@kindex C-x C-+ -@kindex C-x C-- -@kindex C-x C-= -@kindex C-x C-0 - To increase the height of the default face in the current buffer, -type @kbd{C-x C-+} or @kbd{C-x C-=}. To decrease it, type @kbd{C-x -C--}. To restore the default (global) face height, type @kbd{C-x -C-0}. These keys are all bound to the same command, -@code{text-scale-adjust}, which looks at the last key typed to -determine which action to take. - - The final key of these commands may be repeated without the leading -@kbd{C-x}. For instance, @kbd{C-x C-= C-= C-=} increases the face -height by three steps. Each step scales the text height by a factor -of 1.2; to change this factor, customize the variable -@code{text-scale-mode-step}. As an exception, a numeric argument of 0 -to the @code{text-scale-adjust} command restores the default height, -similar to typing @kbd{C-x C-0}. - -@cindex increase buffer face height -@findex text-scale-increase -@cindex decrease buffer face height -@findex text-scale-decrease - The commands @code{text-scale-increase} and -@code{text-scale-decrease} increase or decrease the height of the -default face, just like @kbd{C-x C-+} and @kbd{C-x C--} respectively. -You may find it convenient to bind to these commands, rather than -@code{text-scale-adjust}. - -@cindex set buffer face height -@findex text-scale-set - The command @code{text-scale-set} scales the height of the default -face in the current buffer to an absolute level specified by its -prefix argument. - -@findex text-scale-mode - The above commands automatically enable the minor mode -@code{text-scale-mode} if the current font scaling is other than 1, -and disable it otherwise. - -@node Font Lock -@section Font Lock mode -@cindex Font Lock mode -@cindex mode, Font Lock -@cindex syntax highlighting and coloring - - Font Lock mode is a minor mode, always local to a particular buffer, -which assigns faces to (or @dfn{fontifies}) the text in the buffer. -Each buffer's major mode tells Font Lock mode which text to fontify; -for instance, programming language modes fontify syntactically -relevant constructs like comments, strings, and function names. - -@findex font-lock-mode - Font Lock mode is enabled by default. To toggle it in the current -buffer, type @kbd{M-x font-lock-mode}. A positive numeric argument -unconditionally enables Font Lock mode, and a negative or zero -argument disables it. - -@findex global-font-lock-mode -@vindex global-font-lock-mode - To toggle Font Lock mode in all buffers, type @kbd{M-x -global-font-lock-mode}. To impose this setting for future Emacs -sessions, customize the variable @code{global-font-lock-mode} -(@pxref{Easy Customization}), or add the following line to your init -file: - -@example -(global-font-lock-mode 0) -@end example - -@noindent -If you have disabled Global Font Lock mode, you can still enable Font -Lock for specific major modes by adding the function -@code{font-lock-mode} to the mode hooks (@pxref{Hooks}). For example, -to enable Font Lock mode for editing C files, you can do this: - -@example -(add-hook 'c-mode-hook 'font-lock-mode) -@end example - - Font Lock mode uses several specifically named faces to do its job, -including @code{font-lock-string-face}, @code{font-lock-comment-face}, -and others. The easiest way to find them all is to use @kbd{M-x -customize-group @key{RET} font-lock-faces @key{RET}}. You can then -use that customization buffer to customize the appearance of these -faces. @xref{Face Customization}. - -@vindex font-lock-maximum-decoration - You can customize the variable @code{font-lock-maximum-decoration} -to alter the amount of fontification applied by Font Lock mode, for -major modes that support this feature. The value should be a number -(with 1 representing a minimal amount of fontification; some modes -support levels as high as 3); or @code{t}, meaning ``as high as -possible'' (the default). You can also specify different numbers for -particular major modes; for example, to use level 1 for C/C++ modes, -and the default level otherwise, use the value - -@example -'((c-mode . 1) (c++-mode . 1))) -@end example - -@vindex font-lock-beginning-of-syntax-function -@cindex incorrect fontification -@cindex parenthesis in column zero and fontification -@cindex brace in column zero and fontification - Comment and string fontification (or ``syntactic'' fontification) -relies on analysis of the syntactic structure of the buffer text. For -the sake of speed, some modes, including Lisp mode, rely on a special -convention: an open-parenthesis or open-brace in the leftmost column -always defines the beginning of a defun, and is thus always outside -any string or comment. Therefore, you should avoid placing an -open-parenthesis or open-brace in the leftmost column, if it is inside -a string or comment. @xref{Left Margin Paren}, for details. - -@cindex slow display during scrolling - The variable @code{font-lock-beginning-of-syntax-function}, which is -always buffer-local, specifies how Font Lock mode can find a position -guaranteed to be outside any comment or string. In modes which use -the leftmost column parenthesis convention, the default value of the -variable is @code{beginning-of-defun}---that tells Font Lock mode to -use the convention. If you set this variable to @code{nil}, Font Lock -no longer relies on the convention. This avoids incorrect results, -but the price is that, in some cases, fontification for a changed text -must rescan buffer text from the beginning of the buffer. This can -considerably slow down redisplay while scrolling, particularly if you -are close to the end of a large buffer. - -@findex font-lock-add-keywords - Font Lock highlighting patterns already exist for most modes, but -you may want to fontify additional patterns. You can use the function -@code{font-lock-add-keywords}, to add your own highlighting patterns -for a particular mode. For example, to highlight @samp{FIXME:} words -in C comments, use this: - -@example -(add-hook 'c-mode-hook - (lambda () - (font-lock-add-keywords nil - '(("\\<\\(FIXME\\):" 1 - font-lock-warning-face t))))) -@end example - -@findex font-lock-remove-keywords -@noindent -To remove keywords from the font-lock highlighting patterns, use the -function @code{font-lock-remove-keywords}. @xref{Search-based -Fontification,,, elisp, The Emacs Lisp Reference Manual}. - -@cindex just-in-time (JIT) font-lock -@cindex background syntax highlighting - Fontifying large buffers can take a long time. To avoid large -delays when a file is visited, Emacs initially fontifies only the -visible portion of a buffer. As you scroll through the buffer, each -portion that becomes visible is fontified as soon as it is displayed; -this type of Font Lock is called @dfn{Just-In-Time} (or @dfn{JIT}) -Lock. You can control how JIT Lock behaves, including telling it to -perform fontification while idle, by customizing variables in the -customization group @samp{jit-lock}. @xref{Specific Customization}. - -@node Highlight Interactively -@section Interactive Highlighting -@cindex highlighting by matching -@cindex interactive highlighting -@cindex Highlight Changes mode - -@findex highlight-changes-mode -Highlight Changes mode is a minor mode that @dfn{highlights} the parts -of the buffer that were changed most recently, by giving that text a -different face. To enable or disable Highlight Changes mode, use -@kbd{M-x highlight-changes-mode}. - -@cindex Hi Lock mode -@findex hi-lock-mode - Hi Lock mode is a minor mode that highlights text that matches -regular expressions you specify. For example, you can use it to -highlight all the references to a certain variable in a program source -file, highlight certain parts in a voluminous output of some program, -or highlight certain names in an article. To enable or disable Hi -Lock mode, use the command @kbd{M-x hi-lock-mode}. To enable Hi Lock -mode for all buffers, use @kbd{M-x global-hi-lock-mode} or place -@code{(global-hi-lock-mode 1)} in your @file{.emacs} file. - - Hi Lock mode works like Font Lock mode (@pxref{Font Lock}), except -that you specify explicitly the regular expressions to highlight. You -control them with these commands: - -@table @kbd -@item C-x w h @var{regexp} @key{RET} @var{face} @key{RET} -@kindex C-x w h -@findex highlight-regexp -Highlight text that matches @var{regexp} using face @var{face} -(@code{highlight-regexp}). The highlighting will remain as long as -the buffer is loaded. For example, to highlight all occurrences of -the word ``whim'' using the default face (a yellow background) -@kbd{C-x w h whim @key{RET} @key{RET}}. Any face can be used for -highlighting, Hi Lock provides several of its own and these are -pre-loaded into a list of default values. While being prompted -for a face use @kbd{M-n} and @kbd{M-p} to cycle through them. - -You can use this command multiple times, specifying various regular -expressions to highlight in different ways. - -@item C-x w r @var{regexp} @key{RET} -@kindex C-x w r -@findex unhighlight-regexp -Unhighlight @var{regexp} (@code{unhighlight-regexp}). - -If you invoke this from the menu, you select the expression to -unhighlight from a list. If you invoke this from the keyboard, you -use the minibuffer. It will show the most recently added regular -expression; use @kbd{M-p} to show the next older expression and -@kbd{M-n} to select the next newer expression. (You can also type the -expression by hand, with completion.) When the expression you want to -unhighlight appears in the minibuffer, press @kbd{@key{RET}} to exit -the minibuffer and unhighlight it. - -@item C-x w l @var{regexp} @key{RET} @var{face} @key{RET} -@kindex C-x w l -@findex highlight-lines-matching-regexp -@cindex lines, highlighting -@cindex highlighting lines of text -Highlight entire lines containing a match for @var{regexp}, using face -@var{face} (@code{highlight-lines-matching-regexp}). - -@item C-x w b -@kindex C-x w b -@findex hi-lock-write-interactive-patterns -Insert all the current highlighting regexp/face pairs into the buffer -at point, with comment delimiters to prevent them from changing your -program. (This key binding runs the -@code{hi-lock-write-interactive-patterns} command.) - -These patterns are extracted from the comments, if appropriate, if you -invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while -Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}). - -@item C-x w i -@kindex C-x w i -@findex hi-lock-find-patterns -Extract regexp/face pairs from comments in the current buffer -(@code{hi-lock-find-patterns}). Thus, you can enter patterns -interactively with @code{highlight-regexp}, store them into the file -with @code{hi-lock-write-interactive-patterns}, edit them (perhaps -including different faces for different parenthesized parts of the -match), and finally use this command (@code{hi-lock-find-patterns}) to -have Hi Lock highlight the edited patterns. - -@vindex hi-lock-file-patterns-policy -The variable @code{hi-lock-file-patterns-policy} controls whether Hi -Lock mode should automatically extract and highlight patterns found in a -file when it is visited. Its value can be @code{nil} (never highlight), -@code{ask} (query the user), or a function. If it is a function, -@code{hi-lock-find-patterns} calls it with the patterns as argument; if -the function returns non-@code{nil}, the patterns are used. The default -is @code{ask}. Note that patterns are always highlighted if you call -@code{hi-lock-find-patterns} directly, regardless of the value of this -variable. - -@vindex hi-lock-exclude-modes -Also, @code{hi-lock-find-patterns} does nothing if the current major -mode's symbol is a member of the list @code{hi-lock-exclude-modes}. -@end table - -@node Fringes -@section Window Fringes -@cindex fringes - -@findex set-fringe-style -@findex fringe-mode - On graphical displays, each Emacs window normally has narrow -@dfn{fringes} on the left and right edges. The fringes are used to -display symbols that provide information about the text in the window. -You can type @kbd{M-x fringe-mode} to disable the fringes, or modify -their width. This command affects fringes in all frames; to modify -fringes on the selected frame only, use @kbd{M-x set-fringe-style}. - - The most common use of the fringes is to indicate a continuation -line (@pxref{Continuation Lines}). When one line of text is split -into multiple screen lines, the left fringe shows a curving arrow for -each screen line except the first, indicating that ``this is not the -real beginning''. The right fringe shows a curving arrow for each -screen line except the last, indicating that ``this is not the real -end''. If the line's direction is right-to-left (@pxref{Bidirectional -Editing}), the meanings of the curving arrows in the fringes are -swapped. - - The fringes indicate line truncation with short horizontal arrows -meaning ``there's more text on this line which is scrolled -horizontally out of view''. Clicking the mouse on one of the arrows -scrolls the display horizontally in the direction of the arrow. - - The fringes can also indicate other things, such as buffer -boundaries (@pxref{Displaying Boundaries}), and where a program you -are debugging is executing (@pxref{Debuggers}). - -@vindex overflow-newline-into-fringe - The fringe is also used for drawing the cursor, if the current line -is exactly as wide as the window and point is at the end of the line. -To disable this, change the variable -@code{overflow-newline-into-fringe} to @code{nil}; this causes Emacs -to continue or truncate lines that are exactly as wide as the window. - -@node Displaying Boundaries -@section Displaying Boundaries - -@vindex indicate-buffer-boundaries - On graphical displays, Emacs can indicate the buffer boundaries in -the fringes. If you enable this feature, the first line and the last -line are marked with angle images in the fringes. This can be -combined with up and down arrow images which say whether it is -possible to scroll the window. - - The buffer-local variable @code{indicate-buffer-boundaries} controls -how the buffer boundaries and window scrolling is indicated in the -fringes. If the value is @code{left} or @code{right}, both angle and -arrow bitmaps are displayed in the left or right fringe, respectively. - - If value is an alist, each element @code{(@var{indicator} . -@var{position})} specifies the position of one of the indicators. -The @var{indicator} must be one of @code{top}, @code{bottom}, -@code{up}, @code{down}, or @code{t} which specifies the default -position for the indicators not present in the alist. -The @var{position} is one of @code{left}, @code{right}, or @code{nil} -which specifies not to show this indicator. - - For example, @code{((top . left) (t . right))} places the top angle -bitmap in left fringe, the bottom angle bitmap in right fringe, and -both arrow bitmaps in right fringe. To show just the angle bitmaps in -the left fringe, but no arrow bitmaps, use @code{((top . left) -(bottom . left))}. - -@node Useless Whitespace -@section Useless Whitespace - -@cindex trailing whitespace -@cindex whitespace, trailing -@vindex show-trailing-whitespace - It is easy to leave unnecessary spaces at the end of a line, or -empty lines at the end of a file, without realizing it. In most -cases, this @dfn{trailing whitespace} has no effect, but there are -special circumstances where it matters, and it can be a nuisance. - - You can make trailing whitespace at the end of a line visible by -setting the buffer-local variable @code{show-trailing-whitespace} to -@code{t}. Then Emacs displays trailing whitespace, using the face -@code{trailing-whitespace}. - - This feature does not apply when point is at the end of the line -containing the whitespace. Strictly speaking, that is ``trailing -whitespace'' nonetheless, but displaying it specially in that case -looks ugly while you are typing in new text. In this special case, -the location of point is enough to show you that the spaces are -present. - -@findex delete-trailing-whitespace - Type @kbd{M-x delete-trailing-whitespace} to delete all trailing -whitespace within the buffer. If the region is active, it deletes all -trailing whitespace in the region instead. - -@vindex indicate-empty-lines -@cindex unused lines -@cindex fringes, and unused line indication - On graphical displays, Emacs can indicate unused lines at the end of -the window with a small image in the left fringe (@pxref{Fringes}). -The image appears for screen lines that do not correspond to any -buffer text, so blank lines at the end of the buffer stand out because -they lack this image. To enable this feature, set the buffer-local -variable @code{indicate-empty-lines} to a non-@code{nil} value. You -can enable or disable this feature for all new buffers by setting the -default value of this variable, e.g.@: @code{(setq-default -indicate-empty-lines t)}. - -@cindex Whitespace mode -@cindex mode, Whitespace -@findex whitespace-mode -@vindex whitespace-style - Whitespace mode is a buffer-local minor mode that lets you -``visualize'' many kinds of whitespace in the buffer, by either -drawing the whitespace characters with a special face or displaying -them as special glyphs. To toggle this mode, type @kbd{M-x -whitespace-mode}. The kinds of whitespace visualized are determined -by the list variable @code{whitespace-style}. Here is a partial list -of possible elements (see the variable's documentation for the full -list): - -@table @code -@item face -Enable all visualizations which use special faces. This element has a -special meaning: if it is absent from the list, none of the other -visualizations take effect except @code{space-mark}, @code{tab-mark}, -and @code{newline-mark}. - -@item trailing -Highlight trailing whitespace. - -@item tabs -Highlight tab characters. - -@item spaces -Highlight space and non-breaking space characters. - -@item lines -@vindex whitespace-line-column -Highlight lines longer than 80 lines. To change the column limit, -customize the variable @code{whitespace-line-column}. - -@item newline -Highlight newlines. - -@item empty -Highlight empty lines. - -@item space-mark -Draw space and non-breaking characters with a special glyph. - -@item tab-mark -Draw tab characters with a special glyph. - -@item newline-mark -Draw newline characters with a special glyph. -@end table - -@node Selective Display -@section Selective Display -@cindex selective display -@findex set-selective-display -@kindex C-x $ - - Emacs has the ability to hide lines indented more than a given -number of columns. You can use this to get an overview of a part of a -program. - - To hide lines in the current buffer, type @kbd{C-x $} -(@code{set-selective-display}) with a numeric argument @var{n}. Then -lines with at least @var{n} columns of indentation disappear from the -screen. The only indication of their presence is that three dots -(@samp{@dots{}}) appear at the end of each visible line that is -followed by one or more hidden ones. - - The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as -if they were not there. - - The hidden lines are still present in the buffer, and most editing -commands see them as usual, so you may find point in the middle of the -hidden text. When this happens, the cursor appears at the end of the -previous line, after the three dots. If point is at the end of the -visible line, before the newline that ends it, the cursor appears before -the three dots. - - To make all lines visible again, type @kbd{C-x $} with no argument. - -@vindex selective-display-ellipses - If you set the variable @code{selective-display-ellipses} to -@code{nil}, the three dots do not appear at the end of a line that -precedes hidden lines. Then there is no visible indication of the -hidden lines. This variable becomes local automatically when set. - - See also @ref{Outline Mode} for another way to hide part of -the text in a buffer. - -@node Optional Mode Line -@section Optional Mode Line Features - -@cindex buffer size display -@cindex display of buffer size -@findex size-indication-mode - The buffer percentage @var{pos} indicates the percentage of the -buffer above the top of the window. You can additionally display the -size of the buffer by typing @kbd{M-x size-indication-mode} to turn on -Size Indication mode. The size will be displayed immediately -following the buffer percentage like this: - -@example -@var{POS} of @var{SIZE} -@end example - -@noindent -Here @var{SIZE} is the human readable representation of the number of -characters in the buffer, which means that @samp{k} for 10^3, @samp{M} -for 10^6, @samp{G} for 10^9, etc., are used to abbreviate. - -@cindex line number display -@cindex display of line number -@findex line-number-mode - The current line number of point appears in the mode line when Line -Number mode is enabled. Use the command @kbd{M-x line-number-mode} to -turn this mode on and off; normally it is on. The line number appears -after the buffer percentage @var{pos}, with the letter @samp{L} to -indicate what it is. - -@cindex Column Number mode -@cindex mode, Column Number -@findex column-number-mode - Similarly, you can display the current column number by turning on -Column number mode with @kbd{M-x column-number-mode}. The column -number is indicated by the letter @samp{C}. However, when both of -these modes are enabled, the line and column numbers are displayed in -parentheses, the line number first, rather than with @samp{L} and -@samp{C}. For example: @samp{(561,2)}. @xref{Minor Modes}, for more -information about minor modes and about how to use these commands. - -@cindex narrowing, and line number display - If you have narrowed the buffer (@pxref{Narrowing}), the displayed -line number is relative to the accessible portion of the buffer. -Thus, it isn't suitable as an argument to @code{goto-line}. (Use -@code{what-line} command to see the line number relative to the whole -file.) - -@vindex line-number-display-limit - If the buffer is very large (larger than the value of -@code{line-number-display-limit}), Emacs won't compute the line -number, because that would be too slow; therefore, the line number -won't appear on the mode-line. To remove this limit, set -@code{line-number-display-limit} to @code{nil}. - -@vindex line-number-display-limit-width - Line-number computation can also be slow if the lines in the buffer -are too long. For this reason, Emacs doesn't display line numbers if -the average width, in characters, of lines near point is larger than -the value of @code{line-number-display-limit-width}. The default -value is 200 characters. - -@findex display-time -@cindex time (on mode line) - Emacs can optionally display the time and system load in all mode -lines. To enable this feature, type @kbd{M-x display-time} or customize -the option @code{display-time-mode}. The information added to the mode -line looks like this: - -@example -@var{hh}:@var{mm}pm @var{l.ll} -@end example - -@noindent -@vindex display-time-24hr-format -Here @var{hh} and @var{mm} are the hour and minute, followed always by -@samp{am} or @samp{pm}. @var{l.ll} is the average number, collected -for the last few minutes, of processes in the whole system that were -either running or ready to run (i.e.@: were waiting for an available -processor). (Some fields may be missing if your operating system -cannot support them.) If you prefer time display in 24-hour format, -set the variable @code{display-time-24hr-format} to @code{t}. - -@cindex mail (on mode line) -@vindex display-time-use-mail-icon -@vindex display-time-mail-face -@vindex display-time-mail-file -@vindex display-time-mail-directory - The word @samp{Mail} appears after the load level if there is mail -for you that you have not read yet. On graphical displays, you can -use an icon instead of @samp{Mail} by customizing -@code{display-time-use-mail-icon}; this may save some space on the -mode line. You can customize @code{display-time-mail-face} to make -the mail indicator prominent. Use @code{display-time-mail-file} to -specify the mail file to check, or set -@code{display-time-mail-directory} to specify the directory to check -for incoming mail (any nonempty regular file in the directory is -considered as ``newly arrived mail''). - -@cindex mail (on mode line) -@findex display-battery-mode -@vindex display-battery-mode -@vindex battery-mode-line-format - When running Emacs on a laptop computer, you can display the battery -charge on the mode-line, by using the command -@code{display-battery-mode} or customizing the variable -@code{display-battery-mode}. The variable -@code{battery-mode-line-format} determines the way the battery charge -is displayed; the exact mode-line message depends on the operating -system, and it usually shows the current battery charge as a -percentage of the total charge. - -@cindex mode line, 3D appearance -@cindex attributes of mode line, changing -@cindex non-integral number of lines in a window - On graphical displays, the mode line is drawn as a 3D box. If you -don't like this effect, you can disable it by customizing the -@code{mode-line} face and setting its @code{box} attribute to -@code{nil}. @xref{Face Customization}. - -@cindex non-selected windows, mode line appearance - By default, the mode line of nonselected windows is displayed in a -different face, called @code{mode-line-inactive}. Only the selected -window is displayed in the @code{mode-line} face. This helps show -which window is selected. When the minibuffer is selected, since -it has no mode line, the window from which you activated the minibuffer -has its mode line displayed using @code{mode-line}; as a result, -ordinary entry to the minibuffer does not change any mode lines. - -@vindex mode-line-in-non-selected-windows - You can disable use of @code{mode-line-inactive} by setting variable -@code{mode-line-in-non-selected-windows} to @code{nil}; then all mode -lines are displayed in the @code{mode-line} face. - -@vindex eol-mnemonic-unix -@vindex eol-mnemonic-dos -@vindex eol-mnemonic-mac -@vindex eol-mnemonic-undecided - You can customize the mode line display for each of the end-of-line -formats by setting each of the variables @code{eol-mnemonic-unix}, -@code{eol-mnemonic-dos}, @code{eol-mnemonic-mac}, and -@code{eol-mnemonic-undecided} to the strings you prefer. - -@node Text Display -@section How Text Is Displayed -@cindex characters (in text) -@cindex printing character - - Most characters are @dfn{printing characters}: when they appear in a -buffer, they are displayed literally on the screen. Printing -characters include @acronym{ASCII} numbers, letters, and punctuation -characters, as well as many non-@acronym{ASCII} characters. - -@vindex tab-width -@cindex control characters on display - The @acronym{ASCII} character set contains non-printing @dfn{control -characters}. Two of these are displayed specially: the newline -character (Unicode code point @code{U+000A}) is displayed by starting -a new line, while the tab character (@code{U+0009}) is displayed as a -space that extends to the next tab stop column (normally every 8 -columns). The number of spaces per tab is controlled by the -buffer-local variable @code{tab-width}, which must have an integer -value between 1 and 1000, inclusive. Note that how the tab character -in the buffer is displayed has nothing to do with the definition of -@key{TAB} as a command. - - Other @acronym{ASCII} control characters, whose codes are below -@code{U+0020} (octal 40, decimal 32), are displayed as a caret -(@samp{^}) followed by the non-control version of the character, with -the @code{escape-glyph} face. For instance, the @samp{control-A} -character, @code{U+0001}, is displayed as @samp{^A}. - -@cindex octal escapes -@vindex ctl-arrow - The raw bytes with codes @code{U+0080} (octal 200) through -@code{U+009F} (octal 237) are displayed as @dfn{octal escape -sequences}, with the @code{escape-glyph} face. For instance, -character code @code{U+0098} (octal 230) is displayed as @samp{\230}. -If you change the buffer-local variable @code{ctl-arrow} to -@code{nil}, the @acronym{ASCII} control characters are also displayed -as octal escape sequences instead of caret escape sequences. - -@vindex nobreak-char-display -@cindex non-breaking space -@cindex non-breaking hyphen -@cindex soft hyphen - Some non-@acronym{ASCII} characters have the same appearance as an -@acronym{ASCII} space or hyphen (minus) character. Such characters -can cause problems if they are entered into a buffer without your -realization, e.g.@: by yanking; for instance, source code compilers -typically do not treat non-@acronym{ASCII} spaces as whitespace -characters. To deal with this problem, Emacs displays such characters -specially: it displays @code{U+00A0} (no-break space) with the -@code{nobreak-space} face, and it displays @code{U+00AD} (soft -hyphen), @code{U+2010} (hyphen), and @code{U+2011} (non-breaking -hyphen) with the @code{escape-glyph} face. To disable this, change -the variable @code{nobreak-char-display} to @code{nil}. If you give -this variable a non-@code{nil} and non-@code{t} value, Emacs instead -displays such characters as a highlighted backslash followed by a -space or hyphen. - - You can customize the way any particular character code is displayed -by means of a display table. @xref{Display Tables,, Display Tables, -elisp, The Emacs Lisp Reference Manual}. - -@cindex glyphless characters -@cindex characters with no font glyphs - On graphical displays, some characters may have no glyphs in any of -the fonts available to Emacs. These @dfn{glyphless characters} are -normally displayed as boxes containing the hexadecimal character code. -Similarly, on text terminals, characters that cannot be displayed -using the terminal encoding (@pxref{Terminal Coding}) are normally -displayed as question signs. You can control the display method by -customizing the variable @code{glyphless-char-display-control}. -@xref{Glyphless Chars,, Glyphless Character Display, elisp, The Emacs -Lisp Reference Manual}, for details. - -@node Cursor Display -@section Displaying the Cursor -@cindex text cursor - -@vindex visible-cursor - On a text terminal, the cursor's appearance is controlled by the -terminal, largely out of the control of Emacs. Some terminals offer -two different cursors: a ``visible'' static cursor, and a ``very -visible'' blinking cursor. By default, Emacs uses the very visible -cursor, and switches to it when you start or resume Emacs. If the -variable @code{visible-cursor} is @code{nil} when Emacs starts or -resumes, it uses the normal cursor. - -@cindex cursor face -@vindex cursor-type - On a graphical display, many more properties of the text cursor can -be altered. To customize its color, change the @code{:background} -attribute of the face named @code{cursor} (@pxref{Face -Customization}). (The other attributes of this face have no effect; -the text shown under the cursor is drawn using the frame's background -color.) To change its shape, customize the buffer-local variable -@code{cursor-type}; possible values are @code{box} (the default), -@code{hollow} (a hollow box), @code{bar} (a vertical bar), @code{(bar -. @var{n})} (a vertical bar @var{n} pixels wide), @code{hbar} (a -horizontal bar), @code{(hbar . @var{n})} (a horizontal bar @var{n} -pixels tall), or @code{nil} (no cursor at all). - -@findex blink-cursor-mode -@cindex cursor, blinking -@cindex blinking cursor -@vindex blink-cursor-alist - To disable cursor blinking, change the variable -@code{blink-cursor-mode} to @code{nil} (@pxref{Easy Customization}), -or add the line @code{(blink-cursor-mode 0)} to your init file. -Alternatively, you can change how the cursor looks when it ``blinks -off'' by customizing the list variable @code{blink-cursor-alist}. -Each element in the list should have the form @code{(@var{on-type} -. @var{off-type})}; this means that if the cursor is displayed as -@var{on-type} when it blinks on (where @var{on-type} is one of the -cursor types described above), then it is displayed as @var{off-type} -when it blinks off. - -@vindex x-stretch-cursor -@cindex wide block cursor - Some characters, such as tab characters, are ``extra wide''. When -the cursor is positioned over such a character, it is normally drawn -with the default character width. You can make the cursor stretch to -cover wide characters, by changing the variable -@code{x-stretch-cursor} to a non-@code{nil} value. - -@cindex cursor in non-selected windows -@vindex cursor-in-non-selected-windows - The cursor normally appears in non-selected windows as a -non-blinking hollow box. (For a bar cursor, it instead appears as a -thinner bar.) To turn off cursors in non-selected windows, change the -variable @code{cursor-in-non-selected-windows} to @code{nil}. - -@findex hl-line-mode -@findex global-hl-line-mode -@cindex highlight current line - To make the cursor even more visible, you can use HL Line mode, a -minor mode that highlights the line containing point. Use @kbd{M-x -hl-line-mode} to enable or disable it in the current buffer. @kbd{M-x -global-hl-line-mode} enables or disables the same mode globally. - -@node Line Truncation -@section Line Truncation - -@cindex truncation -@cindex line truncation, and fringes - As an alternative to continuation (@pxref{Continuation Lines}), -Emacs can display long lines by @dfn{truncation}. This means that all -the characters that do not fit in the width of the screen or window do -not appear at all. On graphical displays, a small straight arrow in -the fringe indicates truncation at either end of the line. On text -terminals, this is indicated with @samp{$} signs in the leftmost -and/or rightmost columns. - -@vindex truncate-lines -@findex toggle-truncate-lines - Horizontal scrolling automatically causes line truncation -(@pxref{Horizontal Scrolling}). You can explicitly enable line -truncation for a particular buffer with the command @kbd{M-x -toggle-truncate-lines}. This works by locally changing the variable -@code{truncate-lines}. If that variable is non-@code{nil}, long lines -are truncated; if it is @code{nil}, they are continued onto multiple -screen lines. Setting the variable @code{truncate-lines} in any way -makes it local to the current buffer; until that time, the default -value, which is normally @code{nil}, is in effect. - -@vindex truncate-partial-width-windows - If a split window becomes too narrow, Emacs may automatically enable -line truncation. @xref{Split Window}, for the variable -@code{truncate-partial-width-windows} which controls this. - -@node Visual Line Mode -@section Visual Line Mode - -@cindex word wrap - Another alternative to ordinary line continuation is to use -@dfn{word wrap}. Here, each long logical line is divided into two or -more screen lines, like in ordinary line continuation. However, Emacs -attempts to wrap the line at word boundaries near the right window -edge. This makes the text easier to read, as wrapping does not occur -in the middle of words. - -@cindex Visual Line mode -@findex visual-line-mode -@findex global-visual-line-mode - Word wrap is enabled by Visual Line mode, an optional minor mode. -To turn on Visual Line mode in the current buffer, type @kbd{M-x -visual-line-mode}; repeating this command turns it off. You can also -turn on Visual Line mode using the menu bar: in the Options menu, -select the @samp{Line Wrapping in this Buffer} submenu, followed by -the @samp{Word Wrap (Visual Line Mode)} menu item. While Visual Line -mode is enabled, the mode-line shows the string @samp{wrap} in the -mode display. The command @kbd{M-x global-visual-line-mode} toggles -Visual Line mode in all buffers. - -@findex beginning-of-visual-line -@findex end-of-visual-line -@findex next-logical-line -@findex previous-logical-line - In Visual Line mode, some editing commands work on screen lines -instead of logical lines: @kbd{C-a} (@code{beginning-of-visual-line}) -moves to the beginning of the screen line, @kbd{C-e} -(@code{end-of-visual-line}) moves to the end of the screen line, and -@kbd{C-k} (@code{kill-visual-line}) kills text to the end of the -screen line. - - To move by logical lines, use the commands @kbd{M-x -next-logical-line} and @kbd{M-x previous-logical-line}. These move -point to the next logical line and the previous logical line -respectively, regardless of whether Visual Line mode is enabled. If -you use these commands frequently, it may be convenient to assign key -bindings to them. @xref{Init Rebinding}. - - By default, word-wrapped lines do not display fringe indicators. -Visual Line mode is often used to edit files that contain many long -logical lines, so having a fringe indicator for each wrapped line -would be visually distracting. You can change this by customizing the -variable @code{visual-line-fringe-indicators}. - -@node Display Custom -@section Customization of Display - - This section describes variables that control miscellaneous aspects -of the appearance of the Emacs screen. Beginning users can skip it. - -@vindex visible-bell - If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts -to make the whole screen blink when it would normally make an audible bell -sound. This variable has no effect if your terminal does not have a way -to make the screen blink. - -@vindex echo-keystrokes - The variable @code{echo-keystrokes} controls the echoing of multi-character -keys; its value is the number of seconds of pause required to cause echoing -to start, or zero, meaning don't echo at all. The value takes effect when -there is something to echo. @xref{Echo Area}. - -@cindex mouse pointer -@cindex hourglass pointer display -@vindex display-hourglass -@vindex hourglass-delay - On graphical displays, Emacs displays the mouse pointer as an -hourglass if Emacs is busy. To disable this feature, set the variable -@code{display-hourglass} to @code{nil}. The variable -@code{hourglass-delay} determines the number of seconds of ``busy -time'' before the hourglass is shown; the default is 1. - -@vindex make-pointer-invisible - If the mouse pointer lies inside an Emacs frame, Emacs makes it -invisible each time you type a character to insert text, to prevent it -from obscuring the text. (To be precise, the hiding occurs when you -type a ``self-inserting'' character. @xref{Inserting Text}.) Moving -the mouse pointer makes it visible again. To disable this feature, -set the variable @code{make-pointer-invisible} to @code{nil}. - -@vindex underline-minimum-offset -@vindex x-underline-at-descent-line - On graphical displays, the variable @code{underline-minimum-offset} -determines the minimum distance between the baseline and underline, in -pixels, for underlined text. By default, the value is 1; increasing -it may improve the legibility of underlined text for certain fonts. -(However, Emacs will never draw the underline below the current line -area.) The variable @code{x-underline-at-descent-line} determines how -to draw underlined text. The default is @code{nil}, which means to -draw it at the baseline level of the font; if you change it to -@code{nil}, Emacs draws the underline at the same height as the font's -descent line. - -@vindex overline-margin - The variable @code{overline-margin} specifies the vertical position -of an overline above the text, including the height of the overline -itself, in pixels; the default is 2. - -@findex tty-suppress-bold-inverse-default-colors - On some text terminals, bold face and inverse video together result -in text that is hard to read. Call the function -@code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil} -argument to suppress the effect of bold-face in this case. diff --git a/doc/emacs/doclicense.texi b/doc/emacs/doclicense.texi deleted file mode 100644 index 51342e96d60..00000000000 --- a/doc/emacs/doclicense.texi +++ /dev/null @@ -1,508 +0,0 @@ -@c -*-texinfo-*- -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008, 2009 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input -format, @acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML}, -PostScript or @acronym{PDF} designed for human modification. Examples -of transparent image formats include @acronym{PNG}, @acronym{XCF} and -@acronym{JPG}. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, @acronym{SGML} or -@acronym{XML} for which the @acronym{DTD} and/or processing tools are -not generally available, and the machine-generated @acronym{HTML}, -PostScript or @acronym{PDF} produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.'' line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: - diff --git a/doc/emacs/emacs-xtra.texi b/doc/emacs/emacs-xtra.texi deleted file mode 100644 index 78cac7d8a10..00000000000 --- a/doc/emacs/emacs-xtra.texi +++ /dev/null @@ -1,139 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename ../../info/emacs-xtra -@settitle Specialized Emacs Features -@c Merge all functions, variables, and keys into the concept index. -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@comment %**end of header - -@copying -This manual describes specialized features of Emacs. - -Copyright @copyright{} 2004-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@documentencoding ISO-8859-1 - -@dircategory Emacs -@direntry -* Emacs-Xtra: (emacs-xtra). Specialized Emacs features. -@end direntry - -@titlepage -@title Specialized Emacs Features -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Specialized Emacs Features - -@insertcopying - -@end ifnottex - -@menu -* Introduction:: What documentation belongs here? -@iftex -* Picture Mode:: Editing pictures made up of characters using - the quarter-plane screen model. - -* Autorevert:: Auto Reverting non-file buffers. -* Subdir Switches:: Subdirectory switches in Dired. -* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. -* Emerge:: A convenient way of merging two versions of a program. -* Advanced VC Usage:: Advanced VC (version control) features. -* Fortran:: Fortran mode and its special features. -* MS-DOS:: Using Emacs on MS-DOS. -@end iftex -* Index:: -@end menu - -@node Introduction -@unnumbered Introduction - -This manual contains detailed information about various features that -are too specialized to be included in the printed Emacs manual. It is -intended to be readable by anyone having a basic knowledge of Emacs. -However, certain sections may be intended for a more specialized -audience, such as Elisp authors. This should be clearly pointed out -at the beginning of these sections. - -@c Note to authors - you need to be careful about cross-references to -@c topics in the Emacs manual. As a printed document, the xtra files -@c are separate from the Emacs manual; but as an info document, they -@c are part of the Emacs manual. Hence you need to use something like: -@c @iftex -@c @ref{Comparing Files,,, emacs, the Emacs Manual}, -@c @end iftex -@c @ifnottex -@c @ref{Comparing Files}, -@c @end ifnottex - -Certain packages (or collections of related features) have their own -manuals, separate from the main Emacs manual. This manual is -intended as a complement, rather than an alternative, to reading those -additional manuals. In a nutshell, it is a collection of smaller -specialized features (or extra detail about standard features), too -small or too obscure to justify their own manual, or inclusion in the -printed Emacs manual. The chapters in this manual are, however, -included (at the relevant places) in the main Emacs manual when it is -formatted as an Info document. - -Sections intended specifically for Elisp programmers can follow the -style of the Elisp manual. Other sections should follow the style of -the Emacs manual. - -@iftex - -@raisesections -@include picture-xtra.texi - -@include arevert-xtra.texi - -@include dired-xtra.texi - -@include cal-xtra.texi - -@include emerge-xtra.texi - -@include vc-xtra.texi - -@include fortran-xtra.texi - -@include msdog-xtra.texi - -@lowersections -@end iftex - -@node Index -@unnumbered Index - -@printindex cp - -@bye diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi deleted file mode 100644 index 9042f84e3b6..00000000000 --- a/doc/emacs/emacs.texi +++ /dev/null @@ -1,1598 +0,0 @@ -\input texinfo @c -*- coding: iso-latin-1 -*- - -@setfilename ../../info/emacs -@settitle GNU Emacs Manual - -@c The edition number appears in more than one place in this file -@c I don't really know what it means... -@c For example, it has said "Sixteenth" since sometime in the Emacs 22 -@c series, all through 23, and into 24. So it is not very useful IMO, -@c and offers nothing that EMACSVER does not. I guess it relates -@c mainly to the published book sold by the FSF. Hence no longer -@c bother including it except iftex. Really, I think it should not be -@c here at all (since anyone can make a pdf version), but should just -@c be something added by the FSF during the publishing process. -@c Also, the lispref uses a float (3.0), whereas this uses an ordinal, -@c so the format is not even consistent. -@set EDITION Sixteenth -@include emacsver.texi - -@copying -@iftex -This is the @value{EDITION} edition of the @cite{GNU Emacs Manual},@* -@end iftex -@ifnottex -This is the @cite{GNU Emacs Manual}, -@end ifnottex -updated for Emacs version @value{EMACSVER}. - -Copyright @copyright{} 1985-1987, 1993-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``The GNU Manifesto,'' ``Distribution'' and -``GNU GENERAL PUBLIC LICENSE,'' with the Front-Cover texts being ``A GNU -Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@documentencoding ISO-8859-1 - -@dircategory Emacs -@direntry -* Emacs: (emacs). The extensible self-documenting text editor. -@end direntry - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. The manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@c @smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@defcodeindex op -@synindex pg cp - -@iftex -@kbdinputstyle code - -@shorttitlepage GNU Emacs Manual -@end iftex - -@titlepage -@sp 6 -@center @titlefont{GNU Emacs Manual} -@sp 4 -@center @value{EDITION} Edition, Updated for Emacs Version @value{EMACSVER}. -@sp 5 -@center Richard Stallman et al. -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 -Published by the Free Software Foundation @* -51 Franklin Street, Fifth Floor @* -Boston, MA 02110-1301 USA @* -ISBN 1-882114-86-8 - -@sp 2 -Cover art by Etienne Suvasa. - -@end titlepage - - -@summarycontents -@contents - - -@ifnottex -@node Top, Distrib, (dir), (dir) -@top The Emacs Editor - -Emacs is the extensible, customizable, self-documenting real-time -display editor. This Info file describes how to edit with Emacs and -some of the ways to customize it; it corresponds to GNU Emacs version -@value{EMACSVER}. - -@ifinfo -If you are reading this in Emacs, type @kbd{h} to read a basic -introduction to the Info documentation system. -@end ifinfo - -For information on extending Emacs, see @ref{Top, Emacs Lisp,, elisp, The -Emacs Lisp Reference Manual}. - -@insertcopying -@end ifnottex - -@c Note that the TeX version generates its own TOC, so the ifnottex's -@c here are not really necessary. -@menu -* Distrib:: How to get the latest Emacs distribution. -* Intro:: An introduction to Emacs concepts. -@c Note that in the printed manual, the glossary and indices come last. -* Glossary:: Terms used in this manual. - -Indexes (each index contains a large menu) -* Key Index:: An item for each standard Emacs key sequence. -* Option Index:: An item for every command-line option. -* Command Index:: An item for each command name. -* Variable Index:: An item for each documented variable. -* Concept Index:: An item for each concept. - -* Acknowledgments:: Major contributors to GNU Emacs. - -Important General Concepts -* Screen:: How to interpret what you see on the screen. -* User Input:: Kinds of input events (characters, buttons, - function keys). -* Keys:: Key sequences: what you type to request one - editing action. -* Commands:: Named functions run by key sequences to do editing. -* Entering Emacs:: Starting Emacs from the shell. -* Exiting:: Stopping or killing Emacs. - -Fundamental Editing Commands -* Basic:: The most basic editing commands. -* Minibuffer:: Entering arguments that are prompted for. -* M-x:: Invoking commands by their names. -* Help:: Commands for asking Emacs about its commands. - -Important Text-Changing Commands -* Mark:: The mark: how to delimit a "region" of text. -* Killing:: Killing (cutting) and yanking (copying) text. -* Registers:: Saving a text string or a location in the buffer. -* Display:: Controlling what text is displayed. -* Search:: Finding or replacing occurrences of a string. -* Fixit:: Commands especially useful for fixing typos. -* Keyboard Macros:: Recording a sequence of keystrokes to be replayed. - -Major Structures of Emacs -* Files:: All about handling files. -* Buffers:: Multiple buffers; editing several files at once. -* Windows:: Viewing multiple pieces of text in one frame. -* Frames:: Using multiple "windows" on your display. -* International:: Using non-@acronym{ASCII} character sets. - -Advanced Features -* Modes:: Major and minor modes alter Emacs's basic behavior. -* Indentation:: Editing the white space at the beginnings of lines. -* Text:: Commands and modes for editing human languages. -* Programs:: Commands and modes for editing programs. -* Building:: Compiling, running and debugging programs. -* Maintaining:: Features for maintaining large programs. -* Abbrevs:: Defining text abbreviations to reduce typing. -* Dired:: Directory and file manager. -* Calendar/Diary:: Calendar and diary facilities. -* Sending Mail:: Sending mail in Emacs. -* Rmail:: Reading mail in Emacs. -* Gnus:: A flexible mail and news reader. -* Document View:: Viewing PDF, PS and DVI files. -* Shell:: Executing shell commands from Emacs. -* Emacs Server:: Using Emacs as an editing server. -* Printing:: Printing hardcopies of buffers or regions. -* Sorting:: Sorting lines, paragraphs or pages within Emacs. -@ifnottex -* Picture Mode:: Editing pictures made up of text characters. -@end ifnottex -* Editing Binary Files:: Editing binary files with Hexl mode. -* Saving Emacs Sessions:: Saving Emacs state from one session to the next. -* Recursive Edit:: Performing edits while "within another command". -* Emulation:: Emulating some other editors with Emacs. -* Hyperlinking:: Following links in buffers. -* Amusements:: Various games and hacks. -* Packages:: Installing additional features. -* Customization:: Modifying the behavior of Emacs. - -Recovery from Problems -* Quitting:: Quitting and aborting. -* Lossage:: What to do if Emacs is hung or malfunctioning. -* Bugs:: How and when to report a bug. -* Contributing:: How to contribute improvements to Emacs. -* Service:: How to get help for your own Emacs needs. - -Appendices -* Copying:: The GNU General Public License gives you permission - to redistribute GNU Emacs on certain terms; - it also explains that there is no warranty. -* GNU Free Documentation License:: The license for this documentation. -* Emacs Invocation:: Hairy startup options. -* X Resources:: X resources for customizing Emacs. -* Antinews:: Information about Emacs version 23. -* Mac OS / GNUstep:: Using Emacs under Mac OS and GNUstep. -* Microsoft Windows:: Using Emacs on Microsoft Windows and MS-DOS. -* Manifesto:: What's GNU? Gnu's Not Unix! - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. - -@detailmenu - --- The Detailed Node Listing --- - --------------------------------- - -Here are some other nodes which are really subnodes of the ones -already listed, mentioned here so you can get to them in one step: - -The Organization of the Screen - -* Point:: The place in the text where editing commands operate. -* Echo Area:: Short messages appear at the bottom of the screen. -* Mode Line:: Interpreting the mode line. -* Menu Bar:: How to use the menu bar. - -Basic Editing Commands - -* Inserting Text:: Inserting text by simply typing it. -* Moving Point:: Moving the cursor to the place where you want to - change something. -* Erasing:: Deleting and killing text. -* Basic Undo:: Undoing recent changes in the text. -* Basic Files:: Visiting, creating, and saving files. -* Basic Help:: Asking what a character does. -* Blank Lines:: Making and deleting blank lines. -* Continuation Lines:: How Emacs displays lines too wide for the screen. -* Position Info:: What line, row, or column is point on? -* Arguments:: Numeric arguments for repeating a command N times. -* Repeating:: Repeating the previous command quickly. - -The Minibuffer - -* Minibuffer File:: Entering file names with the minibuffer. -* Minibuffer Edit:: How to edit in the minibuffer. -* Completion:: An abbreviation facility for minibuffer input. -* Minibuffer History:: Reusing recent minibuffer arguments. -* Repetition:: Re-executing commands that used the minibuffer. -* Passwords:: Entering passwords in the echo area. - -Completion - -* Completion Example:: Examples of using completion. -* Completion Commands:: A list of completion commands. -* Completion Exit:: Completion and minibuffer text submission. -* Completion Styles:: How completion matches are chosen. -* Completion Options:: Options for completion. - -Help - -* Help Summary:: Brief list of all Help commands. -* Key Help:: Asking what a key does in Emacs. -* Name Help:: Asking about a command, variable or function name. -* Apropos:: Asking what pertains to a given topic. -* Help Mode:: Special features of Help mode and Help buffers. -* Package Keywords:: Finding Lisp libraries by keywords (topics). -* Language Help:: Help relating to international language support. -* Misc Help:: Other help commands. -* Help Files:: Commands to display auxiliary help files. -* Help Echo:: Help on active text and tooltips ("balloon help"). - -The Mark and the Region - -* Setting Mark:: Commands to set the mark. -* Marking Objects:: Commands to put region around textual units. -* Using Region:: Summary of ways to operate on contents of the region. -* Mark Ring:: Previous mark positions saved so you can go back there. -* Global Mark Ring:: Previous mark positions in various buffers. -* Shift Selection:: Using shifted cursor motion keys. -* Disabled Transient Mark:: Leaving regions unhighlighted by default. - -Killing and Moving Text - -* Deletion and Killing:: Commands that remove text. -* Yanking:: Commands that insert text. -* Cut and Paste:: Clipboard and selections on graphical displays. -* Accumulating Text:: Other methods to add text to the buffer. -* Rectangles:: Operating on text in rectangular areas. -* CUA Bindings:: Using @kbd{C-x}/@kbd{C-c}/@kbd{C-v} to kill and yank. - -Deletion and Killing - -* Deletion:: Commands for deleting small amounts of text and - blank areas. -* Killing by Lines:: How to kill entire lines of text at one time. -* Other Kill Commands:: Commands to kill large regions of text and - syntactic units such as words and sentences. -* Kill Options:: Options that affect killing. - -Yanking - -* Kill Ring:: Where killed text is stored. -* Earlier Kills:: Yanking something killed some time ago. -* Appending Kills:: Several kills in a row all yank together. - -"Cut and Paste" Operations on Graphical Displays - -* Clipboard:: How Emacs uses the system clipboard. -* Primary Selection:: The temporarily selected text selection. -* Secondary Selection:: Cutting without altering point and mark. - -Registers - -* Position Registers:: Saving positions in registers. -* Text Registers:: Saving text in registers. -* Rectangle Registers:: Saving rectangles in registers. -* Configuration Registers:: Saving window configurations in registers. -* Number Registers:: Numbers in registers. -* File Registers:: File names in registers. -* Bookmarks:: Bookmarks are like registers, but persistent. - -Controlling the Display - -* Scrolling:: Commands to move text up and down in a window. -* Recentering:: A scroll command that centers the current line. -* Auto Scrolling:: Redisplay scrolls text automatically when needed. -* Horizontal Scrolling:: Moving text left and right in a window. -* Narrowing:: Restricting display and editing to a portion - of the buffer. -* View Mode:: Viewing read-only buffers. -* Follow Mode:: Follow mode lets two windows scroll as one. -* Faces:: How to change the display style using faces. -* Colors:: Specifying colors for faces. -* Standard Faces:: The main predefined faces. -* Text Scale:: Increasing or decreasing text size in a buffer. -* Font Lock:: Minor mode for syntactic highlighting using faces. -* Highlight Interactively:: Tell Emacs what text to highlight. -* Fringes:: Enabling or disabling window fringes. -* Displaying Boundaries:: Displaying top and bottom of the buffer. -* Useless Whitespace:: Showing possibly spurious trailing whitespace. -* Selective Display:: Hiding lines with lots of indentation. -* Optional Mode Line:: Optional mode line display features. -* Text Display:: How text characters are normally displayed. -* Cursor Display:: Features for displaying the cursor. -* Line Truncation:: Truncating lines to fit the screen width instead - of continuing them to multiple screen lines. -* Visual Line Mode:: Word wrap and screen line-based editing. -* Display Custom:: Information on variables for customizing display. - -Searching and Replacement - -* Incremental Search:: Search happens as you type the string. -* Nonincremental Search:: Specify entire string and then search. -* Word Search:: Search for sequence of words. -* Regexp Search:: Search for match for a regexp. -* Regexps:: Syntax of regular expressions. -* Regexp Backslash:: Regular expression constructs starting with `\'. -* Regexp Example:: A complex regular expression explained. -* Search Case:: To ignore case while searching, or not. -* Replace:: Search, and replace some or all matches. -* Other Repeating Search:: Operating on all matches for some regexp. - -Incremental Search - -* Basic Isearch:: Basic incremental search commands. -* Repeat Isearch:: Searching for the same string again. -* Error in Isearch:: When your string is not found. -* Special Isearch:: Special input in incremental search. -* Isearch Yank:: Commands that grab text into the search string - or else edit the search string. -* Isearch Scroll:: Scrolling during an incremental search. -* Isearch Minibuffer:: Incremental search of the minibuffer history. - -Replacement Commands - -* Unconditional Replace:: Replacing all matches for a string. -* Regexp Replace:: Replacing all matches for a regexp. -* Replacement and Case:: How replacements preserve case of letters. -* Query Replace:: How to use querying. - -Commands for Fixing Typos - -* Undo:: The Undo commands. -* Transpose:: Exchanging two characters, words, lines, lists... -* Fixing Case:: Correcting case of last word entered. -* Spelling:: Apply spelling checker to a word, or a whole file. - -Keyboard Macros - -* Basic Keyboard Macro:: Defining and running keyboard macros. -* Keyboard Macro Ring:: Where previous keyboard macros are saved. -* Keyboard Macro Counter:: Inserting incrementing numbers in macros. -* Keyboard Macro Query:: Making keyboard macros do different things each - time. -* Save Keyboard Macro:: Giving keyboard macros names; saving them in - files. -* Edit Keyboard Macro:: Editing keyboard macros. -* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard - macro. - -File Handling - -* File Names:: How to type and edit file-name arguments. -* Visiting:: Visiting a file prepares Emacs to edit the file. -* Saving:: Saving makes your changes permanent. -* Reverting:: Reverting cancels all the changes not saved. -@ifnottex -* Autorevert:: Auto Reverting non-file buffers. -@end ifnottex -* Auto Save:: Auto Save periodically protects against loss of data. -* File Aliases:: Handling multiple names for one file. -* Directories:: Creating, deleting, and listing file directories. -* Comparing Files:: Finding where two files differ. -* Diff Mode:: Mode for editing file differences. -* Misc File Ops:: Other things you can do on files. -* Compressed Files:: Accessing compressed files. -* File Archives:: Operating on tar, zip, jar etc. archive files. -* Remote Files:: Accessing files on other machines. -* Quoted File Names:: Quoting special characters in file names. -* File Name Cache:: Completion against a list of files you often use. -* File Conveniences:: Convenience Features for Finding Files. -* Filesets:: Handling sets of files. - -Saving Files - -* Save Commands:: Commands for saving files. -* Backup:: How Emacs saves the old version of your file. -* Customize Save:: Customizing the saving of files. -* Interlocking:: How Emacs protects against simultaneous editing - of one file by two users. -* File Shadowing:: Copying files to "shadows" automatically. -* Time Stamps:: Emacs can update time stamps on saved files. - -Backup Files - -* Backup Names:: How backup files are named. -* Backup Deletion:: Emacs deletes excess numbered backups. -* Backup Copying:: Backups can be made by copying or renaming. - -@ifnottex -Auto Reverting Non-File Buffers - -* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. -* Auto Reverting Dired:: Auto Revert of Dired buffers. -* Supporting additional buffers:: How to add more Auto Revert support. -@end ifnottex - -Auto-Saving: Protection Against Disasters - -* Auto Save Files:: The file where auto-saved changes are - actually made until you save the file. -* Auto Save Control:: Controlling when and how often to auto-save. -* Recover:: Recovering text from auto-save files. - -Using Multiple Buffers - -* Select Buffer:: Creating a new buffer or reselecting an old one. -* List Buffers:: Getting a list of buffers that exist. -* Misc Buffer:: Renaming; changing read-onlyness; copying text. -* Kill Buffer:: Killing buffers you no longer need. -* Several Buffers:: How to go through the list of all buffers - and operate variously on several of them. -* Indirect Buffers:: An indirect buffer shares the text of another buffer. -* Buffer Convenience:: Convenience and customization features for - buffer handling. - -Convenience Features and Customization of Buffer Handling - -* Uniquify:: Making buffer names unique with directory parts. -* Iswitchb:: Switching between buffers with substrings. -* Buffer Menus:: Configurable buffer menu. - -Multiple Windows - -* Basic Window:: Introduction to Emacs windows. -* Split Window:: New windows are made by splitting existing windows. -* Other Window:: Moving to another window or doing something to it. -* Pop Up Window:: Finding a file or buffer in another window. -* Change Window:: Deleting windows and changing their sizes. -* Displaying Buffers:: How Emacs picks a window for displaying a buffer. -* Window Convenience:: Convenience functions for window handling. - -Displaying a Buffer in a Window - -* Window Choice:: How @code{display-buffer} works. - -Frames and Graphical Displays - -* Mouse Commands:: Moving, cutting, and pasting, with the mouse. -* Word and Line Mouse:: Mouse commands for selecting whole words or lines. -* Mouse References:: Using the mouse to select an item from a list. -* Menu Mouse Clicks:: Mouse clicks that bring up menus. -* Mode Line Mouse:: Mouse clicks on the mode line. -* Creating Frames:: Creating additional Emacs frames with various contents. -* Frame Commands:: Iconifying, deleting, and switching frames. -* Fonts:: Changing the frame font. -* Speedbar:: How to make and use a speedbar frame. -* Multiple Displays:: How one Emacs instance can talk to several displays. -* Frame Parameters:: Changing the colors and other modes of frames. -* Scroll Bars:: How to enable and disable scroll bars; how to use them. -* Drag and Drop:: Using drag and drop to open files and insert text. -* Menu Bars:: Enabling and disabling the menu bar. -* Tool Bars:: Enabling and disabling the tool bar. -* Dialog Boxes:: Controlling use of dialog boxes. -* Tooltips:: Displaying information at the current mouse position. -* Mouse Avoidance:: Preventing the mouse pointer from obscuring text. -* Non-Window Terminals:: Multiple frames on terminals that show only one. -* Text-Only Mouse:: Using the mouse in text terminals. - -International Character Set Support - -* International Chars:: Basic concepts of multibyte characters. -* Disabling Multibyte:: Controlling whether to use multibyte characters. -* Language Environments:: Setting things up for the language you use. -* Input Methods:: Entering text characters not on your keyboard. -* Select Input Method:: Specifying your choice of input methods. -* Coding Systems:: Character set conversion when you read and - write files, and so on. -* Recognize Coding:: How Emacs figures out which conversion to use. -* Specify Coding:: Specifying a file's coding system explicitly. -* Output Coding:: Choosing coding systems for output. -* Text Coding:: Choosing conversion to use for file text. -* Communication Coding:: Coding systems for interprocess communication. -* File Name Coding:: Coding systems for file @emph{names}. -* Terminal Coding:: Specifying coding systems for converting - terminal input and output. -* Fontsets:: Fontsets are collections of fonts - that cover the whole spectrum of characters. -* Defining Fontsets:: Defining a new fontset. -* Modifying Fontsets:: Modifying an existing fontset. -* Undisplayable Characters::When characters don't display. -* Unibyte Mode:: You can pick one European character set - to use without multibyte characters. -* Charsets:: How Emacs groups its internal character codes. -* Bidirectional Editing:: Support for right-to-left scripts. - -Major and Minor Modes - -* Major Modes:: Text mode vs. Lisp mode vs. C mode... -* Minor Modes:: Each minor mode is a feature you can turn on - independently of any others. -* Choosing Modes:: How modes are chosen when visiting files. - -Indentation - -* Indentation Commands:: More commands for performing indentation. -* Tab Stops:: Stop points for indentation in Text modes. -* Just Spaces:: Using only space characters for indentation. -* Indent Convenience:: Optional indentation features. - -Commands for Human Languages - -* Words:: Moving over and killing words. -* Sentences:: Moving over and killing sentences. -* Paragraphs:: Moving over paragraphs. -* Pages:: Moving over pages. -* Filling:: Filling or justifying text. -* Case:: Changing the case of text. -* Text Mode:: The major modes for editing text files. -* Outline Mode:: Editing outlines. -* Org Mode:: The Emacs organizer. -* TeX Mode:: Editing TeX and LaTeX files. -* HTML Mode:: Editing HTML and SGML files. -* Nroff Mode:: Editing input to the nroff formatter. -* Enriched Text:: Editing text "enriched" with fonts, colors, etc. -* Text Based Tables:: Commands for editing text-based tables. -* Two-Column:: Splitting text columns into separate windows. - -Filling Text - -* Auto Fill:: Auto Fill mode breaks long lines automatically. -* Fill Commands:: Commands to refill paragraphs and center lines. -* Fill Prefix:: Filling paragraphs that are indented - or in a comment, etc. -* Adaptive Fill:: How Emacs can determine the fill prefix automatically. - -Outline Mode - -* Outline Format:: What the text of an outline looks like. -* Outline Motion:: Special commands for moving through outlines. -* Outline Visibility:: Commands to control what is visible. -* Outline Views:: Outlines and multiple views. -* Foldout:: Folding means zooming in on outlines. - -Org Mode - -* Org Organizer:: Managing TODO lists and agendas. -* Org Authoring:: Exporting Org buffers to various formats. - -@TeX{} Mode - -* TeX Editing:: Special commands for editing in TeX mode. -* LaTeX Editing:: Additional commands for LaTeX input files. -* TeX Print:: Commands for printing part of a file with TeX. -* TeX Misc:: Customization of TeX mode, and related features. - -Enriched Text - -* Enriched Mode:: Entering and exiting Enriched mode. -* Hard and Soft Newlines:: There are two different kinds of newlines. -* Editing Format Info:: How to edit text properties. -* Enriched Faces:: Bold, italic, underline, etc. -* Enriched Indentation:: Changing the left and right margins. -* Enriched Justification:: Centering, setting text flush with the - left or right margin, etc. -* Enriched Properties:: The "special" text properties submenu. - -@c The automatic texinfo menu update inserts some duplicate items here -@c (faces, colors, indentation, justification, properties), because -@c they are listed in two menus. But we already have them above, no -@c need to list them twice. - -Editing Text-based Tables - -* Table Definition:: What is a text based table. -* Table Creation:: How to create a table. -* Table Recognition:: How to activate and deactivate tables. -* Cell Commands:: Cell-oriented commands in a table. -* Cell Justification:: Justifying cell contents. -* Table Rows and Columns:: Inserting and deleting rows and columns. -* Table Conversion:: Converting between plain text and tables. -* Table Misc:: Table miscellany. - -Editing Programs - -* Program Modes:: Major modes for editing programs. -* Defuns:: Commands to operate on major top-level parts - of a program. -* Program Indent:: Adjusting indentation to show the nesting. -* Parentheses:: Commands that operate on parentheses. -* Comments:: Inserting, killing, and aligning comments. -* Documentation:: Getting documentation of functions you plan to call. -* Hideshow:: Displaying blocks selectively. -* Symbol Completion:: Completion on symbol names of your program or language. -* Glasses:: Making identifiersLikeThis more readable. -* Semantic:: Suite of editing tools based on source code parsing. -* Misc for Programs:: Other Emacs features useful for editing programs. -* C Modes:: Special commands of C, C++, Objective-C, - Java, IDL, Pike and AWK modes. -* Asm Mode:: Asm mode and its special features. -@ifnottex -* Fortran:: Fortran mode and its special features. -@end ifnottex - -Top-Level Definitions, or Defuns - -* Left Margin Paren:: An open-paren or similar opening delimiter - starts a defun if it is at the left margin. -* Moving by Defuns:: Commands to move over or mark a major definition. -* Imenu:: Making buffer indexes as menus. -* Which Function:: Which Function mode shows which function you are in. - -Indentation for Programs - -* Basic Indent:: Indenting a single line. -* Multi-line Indent:: Commands to reindent many lines at once. -* Lisp Indent:: Specifying how each Lisp function should be indented. -* C Indent:: Extra features for indenting C and related modes. -* Custom C Indent:: Controlling indentation style for C and related modes. - -Commands for Editing with Parentheses - -* Expressions:: Expressions with balanced parentheses. -* Moving by Parens:: Commands for moving up, down and across - in the structure of parentheses. -* Matching:: Insertion of a close-delimiter flashes matching open. - -Manipulating Comments - -* Comment Commands:: Inserting, killing, and aligning comments. -* Multi-Line Comments:: Commands for adding and editing multi-line comments. -* Options for Comments::Customizing the comment features. - -Documentation Lookup - -* Info Lookup:: Looking up library functions and commands in Info files. -* Man Page:: Looking up man pages of library functions and commands. -* Lisp Doc:: Looking up Emacs Lisp functions, etc. - -C and Related Modes - -* Motion in C:: Commands to move by C statements, etc. -* Electric C:: Colon and other chars can automatically reindent. -* Hungry Delete:: A more powerful DEL command. -* Other C Commands:: Filling comments, viewing expansion of macros, - and other neat features. - -@ifnottex -Fortran Mode - -* Fortran Motion:: Moving point by statements or subprograms. -* Fortran Indent:: Indentation commands for Fortran. -* Fortran Comments:: Inserting and aligning comments. -* Fortran Autofill:: Auto fill support for Fortran. -* Fortran Columns:: Measuring columns for valid Fortran. -* Fortran Abbrev:: Built-in abbrevs for Fortran keywords. - -Fortran Indentation - -* ForIndent Commands:: Commands for indenting and filling Fortran. -* ForIndent Cont:: How continuation lines indent. -* ForIndent Num:: How line numbers auto-indent. -* ForIndent Conv:: Conventions you must obey to avoid trouble. -* ForIndent Vars:: Variables controlling Fortran indent style. -@end ifnottex - -Compiling and Testing Programs - -* Compilation:: Compiling programs in languages other - than Lisp (C, Pascal, etc.). -* Compilation Mode:: The mode for visiting compiler errors. -* Compilation Shell:: Customizing your shell properly - for use in the compilation buffer. -* Grep Searching:: Searching with grep. -* Flymake:: Finding syntax errors on the fly. -* Debuggers:: Running symbolic debuggers for non-Lisp programs. -* Executing Lisp:: Various modes for editing Lisp programs, - with different facilities for running - the Lisp programs. -* Lisp Libraries:: How Lisp programs are loaded into Emacs. -* Lisp Eval:: Executing a single Lisp expression in Emacs. -* Lisp Interaction:: Executing Lisp in an Emacs buffer. -* External Lisp:: Communicating through Emacs with a separate Lisp. - -Running Debuggers Under Emacs - -* Starting GUD:: How to start a debugger subprocess. -* Debugger Operation:: Connection between the debugger and source buffers. -* Commands of GUD:: Key bindings for common commands. -* GUD Customization:: Defining your own commands for GUD. -* GDB Graphical Interface:: An enhanced mode that uses GDB features to - implement a graphical debugging environment. - -GDB Graphical Interface - -* GDB User Interface Layout:: Control the number of displayed buffers. -* Source Buffers:: Use the mouse in the fringe/margin to - control your program. -* Breakpoints Buffer:: A breakpoint control panel. -* Threads Buffer:: Displays your threads. -* Stack Buffer:: Select a frame from the call stack. -* Other GDB Buffers:: Other buffers for controlling the GDB state. -* Watch Expressions:: Monitor variable values in the speedbar. -* Multithreaded Debugging:: Debugging programs with several threads. - -Maintaining Large Programs - -* Version Control:: Using version control systems. -* Change Log:: Maintaining a change history for your program. -* Tags:: Go directly to any function in your program in one - command. Tags remembers which file it is in. -* EDE:: An integrated development environment for Emacs. -@ifnottex -* Emerge:: A convenient way of merging two versions of a program. -@end ifnottex - -Version Control - -* Introduction to VC:: How version control works in general. -* VC Mode Line:: How the mode line shows version control status. -* Basic VC Editing:: How to edit a file under version control. -* Log Buffer:: Features available in log entry buffers. -* Registering:: Putting a file under version control. -* Old Revisions:: Examining and comparing old versions. -* VC Change Log:: Viewing the VC Change Log. -* VC Undo:: Canceling changes before or after committing. -* VC Directory Mode:: Listing files managed by version control. -* Branches:: Multiple lines of development. -@ifnottex -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. -@end ifnottex - -Introduction to Version Control - -* Why Version Control?:: Understanding the problems it addresses. -* Version Control Systems:: Supported version control back-end systems. -* VCS Concepts:: Words and concepts related to version control. -* VCS Merging:: How file conflicts are handled. -* VCS Changesets:: How changes are grouped. -* VCS Repositories:: Where version control repositories are stored. -* Types of Log File:: The VCS log in contrast to the ChangeLog. - -Basic Editing under Version Control - -* VC With A Merging VCS:: Without locking: default mode for CVS. -* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. -* Advanced C-x v v:: Advanced features available with a prefix argument. - -VC Directory Mode - -* VC Directory Buffer:: What the buffer looks like and means. -* VC Directory Commands:: Commands to use in a VC directory buffer. - -Version Control Branches - -* Switching Branches:: How to get to another existing branch. -* VC Pull:: Updating the contents of a branch. -* Merging:: Transferring changes between branches. -* Creating Branches:: How to start a new branch. - -@ifnottex -Miscellaneous Commands and Features of VC - -* Change Logs and VC:: Generating a change log file from log entries. -* VC Delete/Rename:: Deleting and renaming version-controlled files. -* Revision Tags:: Symbolic names for revisions. -* Version Headers:: Inserting version control headers into working files. - -Customizing VC - -* General VC Options:: Options that apply to multiple back ends. -* RCS and SCCS:: Options for RCS and SCCS. -* CVS Options:: Options for CVS. -@end ifnottex - -Change Logs - -* Change Log Commands:: Commands for editing change log files. -* Format of ChangeLog:: What the change log file looks like. - -Tags Tables - -* Tag Syntax:: Tag syntax for various types of code and text files. -* Create Tags Table:: Creating a tags table with @command{etags}. -* Etags Regexps:: Create arbitrary tags using regular expressions. -* Select Tags Table:: How to visit a tags table. -* Find Tag:: Commands to find the definition of a specific tag. -* Tags Search:: Using a tags table for searching and replacing. -* List Tags:: Using tags for completion, and listing them. - -@ifnottex -Merging Files with Emerge - -* Overview of Emerge:: How to start Emerge. Basic concepts. -* Submodes of Emerge:: Fast mode vs. Edit mode. - Skip Prefers mode and Auto Advance mode. -* State of Difference:: You do the merge by specifying state A or B - for each difference. -* Merge Commands:: Commands for selecting a difference, - changing states of differences, etc. -* Exiting Emerge:: What to do when you've finished the merge. -* Combining in Emerge:: How to keep both alternatives for a difference. -* Fine Points of Emerge:: Miscellaneous issues. -@end ifnottex - -Abbrevs - -* Abbrev Concepts:: Fundamentals of defined abbrevs. -* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. -* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. -* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. -* Saving Abbrevs:: Saving the entire list of abbrevs for another session. -* Dynamic Abbrevs:: Abbreviations for words already in the buffer. -* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling. - -@ifnottex -Editing Pictures - -* Basic Picture:: Basic concepts and simple commands of Picture Mode. -* Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. -* Tabs in Picture:: Various features for tab stops and indentation. -* Rectangles in Picture:: Clearing and superimposing rectangles. -@end ifnottex - -Dired, the Directory Editor - -* Dired Enter:: How to invoke Dired. -* Dired Navigation:: Special motion commands in the Dired buffer. -* Dired Deletion:: Deleting files with Dired. -* Flagging Many Files:: Flagging files based on their names. -* Dired Visiting:: Other file operations through Dired. -* Marks vs Flags:: Flagging for deletion vs marking. -* Operating on Files:: How to copy, rename, print, compress, etc. - either one file or several files. -* Shell Commands in Dired:: Running a shell command on the marked files. -* Transforming File Names:: Using patterns to rename multiple files. -* Comparison in Dired:: Running @code{diff} by way of Dired. -* Subdirectories in Dired:: Adding subdirectories to the Dired buffer. -@ifnottex -* Subdir Switches:: Subdirectory switches in Dired. -@end ifnottex -* Subdirectory Motion:: Moving across subdirectories, and up and down. -* Hiding Subdirectories:: Making subdirectories visible or invisible. -* Dired Updating:: Discarding lines for files of no interest. -* Dired and Find:: Using @code{find} to choose the files for Dired. -* Wdired:: Operating on files by editing the Dired buffer. -* Image-Dired:: Viewing image thumbnails in Dired. -* Misc Dired Features:: Various other features. - -The Calendar and the Diary - -* Calendar Motion:: Moving through the calendar; selecting a date. -* Scroll Calendar:: Bringing earlier or later months onto the screen. -* Counting Days:: How many days are there between two dates? -* General Calendar:: Exiting or recomputing the calendar. -* Writing Calendar Files:: Writing calendars to files of various formats. -* Holidays:: Displaying dates of holidays. -* Sunrise/Sunset:: Displaying local times of sunrise and sunset. -* Lunar Phases:: Displaying phases of the moon. -* Other Calendars:: Converting dates to other calendar systems. -* Diary:: Displaying events from your diary. -* Appointments:: Reminders when it's time to do something. -* Importing Diary:: Converting diary events to/from other formats. -* Daylight Saving:: How to specify when daylight saving time is active. -* Time Intervals:: Keeping track of time intervals. -@ifnottex -* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. -@end ifnottex - -Movement in the Calendar - -* Calendar Unit Motion:: Moving by days, weeks, months, and years. -* Move to Beginning or End:: Moving to start/end of weeks, months, and years. -* Specified Dates:: Moving to the current date or another - specific date. - -Conversion To and From Other Calendars - -* Calendar Systems:: The calendars Emacs understands - (aside from Gregorian). -* To Other Calendar:: Converting the selected date to various calendars. -* From Other Calendar:: Moving to a date specified in another calendar. -* Mayan Calendar:: Moving to a date specified in a Mayan calendar. - -The Diary - -* Displaying the Diary:: Viewing diary entries and associated calendar dates. -* Format of Diary File:: Entering events in your diary. -* Date Formats:: Various ways you can specify dates. -* Adding to Diary:: Commands to create diary entries. -* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. - -@ifnottex -Customizing the Calendar and Diary - -* Calendar Customizing:: Calendar layout and hooks. -* Holiday Customizing:: Defining your own holidays. -* Date Display Format:: Changing the format. -* Time Display Format:: Changing the format. -* Diary Customizing:: Defaults you can set. -* Non-Gregorian Diary:: Diary entries based on other calendars. -* Diary Display:: A choice of ways to display the diary. -* Fancy Diary Display:: Sorting diary entries, using included diary files. -* Sexp Diary Entries:: More flexible diary entries. -@end ifnottex - -Sending Mail - -* Mail Format:: Format of a mail message. -* Mail Headers:: Details of some standard mail header fields. -* Mail Aliases:: Abbreviating and grouping mail addresses. -* Mail Commands:: Special commands for editing mail being composed. -* Mail Signature:: Adding a signature to every message. -* Mail Amusements:: Distracting the NSA; adding fortune messages. -* Mail Methods:: Using alternative mail-composition methods. - -Mail Commands - -* Mail Sending:: Commands to send the message. -* Header Editing:: Commands to move to header fields and edit them. -* Citing Mail:: Quoting a message you are replying to. -* Mail Misc:: Attachments, spell checking, etc. - -Reading Mail with Rmail - -* Rmail Basics:: Basic concepts of Rmail, and simple use. -* Rmail Scrolling:: Scrolling through a message. -* Rmail Motion:: Moving to another message. -* Rmail Deletion:: Deleting and expunging messages. -* Rmail Inbox:: How mail gets into the Rmail file. -* Rmail Files:: Using multiple Rmail files. -* Rmail Output:: Copying message out to files. -* Rmail Labels:: Classifying messages by labeling them. -* Rmail Attributes:: Certain standard labels, called attributes. -* Rmail Reply:: Sending replies to messages you are viewing. -* Rmail Summary:: Summaries show brief info on many messages. -* Rmail Sorting:: Sorting messages in Rmail. -* Rmail Display:: How Rmail displays a message; customization. -* Rmail Coding:: How Rmail handles decoding character sets. -* Rmail Editing:: Editing message text and headers in Rmail. -* Rmail Digest:: Extracting the messages from a digest message. -* Rmail Rot13:: Reading messages encoded in the rot13 code. -* Movemail:: More details of fetching new mail. -* Remote Mailboxes:: Retrieving mail from remote mailboxes. -* Other Mailbox Formats:: Retrieving mail from local mailboxes in - various formats. - -Rmail Summaries - -* Rmail Make Summary:: Making various sorts of summaries. -* Rmail Summary Edit:: Manipulating messages from the summary. - -Gnus - -* Buffers of Gnus:: The group, summary, and article buffers. -* Gnus Startup:: What you should know about starting Gnus. -* Gnus Group Buffer:: A short description of Gnus group commands. -* Gnus Summary Buffer:: A short description of Gnus summary commands. - -Document Viewing - -* DocView Navigation:: Navigating DocView buffers. -* DocView Searching:: Searching inside documents. -* DocView Slicing:: Specifying which part of a page is displayed. -* DocView Conversion:: Influencing and triggering conversion. - -Running Shell Commands from Emacs - -* Single Shell:: How to run one shell command and return. -* Interactive Shell:: Permanent shell taking input via Emacs. -* Shell Mode:: Special Emacs commands used with permanent shell. -* Shell Prompts:: Two ways to recognize shell prompts. -* Shell History:: Repeating previous commands in a shell buffer. -* Directory Tracking:: Keeping track when the subshell changes directory. -* Shell Options:: Options for customizing Shell mode. -* Terminal emulator:: An Emacs window as a terminal emulator. -* Term Mode:: Special Emacs commands used in Term mode. -* Remote Host:: Connecting to another computer. -* Serial Terminal:: Connecting to a serial port. - -Shell Command History - -* Shell Ring:: Fetching commands from the history list. -* Shell History Copying::Moving to a command and then copying it. -* History References:: Expanding @samp{!}-style history references. - -Using Emacs as a Server - -* Invoking emacsclient:: Connecting to the Emacs server. -* emacsclient Options:: Emacs client startup options. - -Printing Hard Copies - -* PostScript:: Printing buffers or regions as PostScript. -* PostScript Variables:: Customizing the PostScript printing commands. -* Printing Package:: An optional advanced printing interface. - -Hyperlinking and Navigation Features - -* Browse-URL:: Following URLs. -* Goto Address mode:: Activating URLs. -* FFAP:: Finding files etc. at point. - -Emacs Lisp Packages - -* Package Menu:: Buffer for viewing and managing packages. -* Package Installation:: Options for package installation. -* Package Files:: Where packages are installed. - -Customization - -* Easy Customization:: Convenient way to browse and change settings. -* Variables:: Many Emacs commands examine Emacs variables - to decide what to do; by setting variables, - you can control their functioning. -* Key Bindings:: The keymaps say what command each key runs. - By changing them, you can "redefine" keys. -* Init File:: How to write common customizations in the - initialization file. - -Easy Customization Interface - -* Customization Groups:: How settings are classified. -* Browsing Custom:: Browsing and searching for settings. -* Changing a Variable:: How to edit an option's value and set the option. -* Saving Customizations:: Saving customizations for future Emacs sessions. -* Face Customization:: How to edit the attributes of a face. -* Specific Customization:: Customizing specific settings or groups. -* Custom Themes:: Collections of customization settings. -* Creating Custom Themes:: How to create a new custom theme. - -Variables - -* Examining:: Examining or setting one variable's value. -* Hooks:: Hook variables let you specify programs for parts - of Emacs to run on particular occasions. -* Locals:: Per-buffer values of variables. -* File Variables:: How files can specify variable values. -* Directory Variables:: How variable values can be specified by directory. - -Local Variables in Files - -* Specifying File Variables:: Specifying file local variables. -* Safe File Variables:: Making sure file local variables are safe. - -Customizing Key Bindings - -* Keymaps:: Generalities. The global keymap. -* Prefix Keymaps:: Keymaps for prefix keys. -* Local Keymaps:: Major and minor modes have their own keymaps. -* Minibuffer Maps:: The minibuffer uses its own local keymaps. -* Rebinding:: How to redefine one key's meaning conveniently. -* Init Rebinding:: Rebinding keys with your initialization file. -* Modifier Keys:: Using modifier keys in key bindings. -* Function Keys:: Rebinding terminal function keys. -* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. -* Mouse Buttons:: Rebinding mouse buttons in Emacs. -* Disabling:: Disabling a command means confirmation is required - before it can be executed. This is done to protect - beginners from surprises. - -The Emacs Initialization File - -* Init Syntax:: Syntax of constants in Emacs Lisp. -* Init Examples:: How to do some things with an init file. -* Terminal Init:: Each terminal type can have an init file. -* Find Init:: How Emacs finds the init file. -* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. - -Dealing with Emacs Trouble - -* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. -* Stuck Recursive:: `[...]' in mode line around the parentheses. -* Screen Garbled:: Garbage on the screen. -* Text Garbled:: Garbage in the text. -* Memory Full:: How to cope when you run out of memory. -* After a Crash:: Recovering editing in an Emacs session that crashed. -* Emergency Escape:: What to do if Emacs stops responding. - -Reporting Bugs - -* Known Problems:: How to read about known problems and bugs. -* Bug Criteria:: Have you really found a bug? -* Understanding Bug Reporting:: How to report a bug effectively. -* Checklist:: Steps to follow for a good bug report. -* Sending Patches:: How to send a patch for GNU Emacs. - -Command Line Arguments for Emacs Invocation - -* Action Arguments:: Arguments to visit files, load libraries, - and call functions. -* Initial Options:: Arguments that take effect while starting Emacs. -* Command Example:: Examples of using command line arguments. -* Environment:: Environment variables that Emacs uses. -* Display X:: Changing the default display and using remote login. -* Font X:: Choosing a font for text, under X. -* Colors X:: Choosing display colors. -* Window Size X:: Start-up window size, under X. -* Borders X:: Internal and external borders, under X. -* Title X:: Specifying the initial frame's title. -* Icons X:: Choosing what sort of icon to use, under X. -* Misc X:: Other display options. - -Environment Variables - -* General Variables:: Environment variables that all versions of Emacs use. -* Misc Variables:: Certain system-specific variables. -* MS-Windows Registry:: An alternative to the environment on MS-Windows. - -X Options and Resources - -* Resources:: Using X resources with Emacs (in general). -* Table of Resources:: Table of specific X resources that affect Emacs. -* Lucid Resources:: X resources for Lucid menus. -* LessTif Resources:: X resources for LessTif and Motif menus. -* GTK resources:: Resources for GTK widgets. - -GTK resources - -* GTK Resource Basics:: Basic usage of GTK+ resources. -* GTK Widget Names:: How GTK+ widgets are named. -* GTK Names in Emacs:: GTK widgets used by Emacs. -* GTK styles:: What can be customized in a GTK widget. - -Emacs and Mac OS / GNUstep - -* Mac / GNUstep Basics:: Basic Emacs usage under GNUstep or Mac OS. -* Mac / GNUstep Customization:: Customizations under GNUstep or Mac OS. -* Mac / GNUstep Events:: How window system events are handled. -* GNUstep Support:: Details on status of GNUstep support. - -Emacs and Microsoft Windows/MS-DOS - -* Windows Startup:: How to start Emacs on Windows. -* Text and Binary:: Text files use CRLF to terminate lines. -* Windows Files:: File-name conventions on Windows. -* ls in Lisp:: Emulation of @code{ls} for Dired. -* Windows HOME:: Where Emacs looks for your @file{.emacs} and - where it starts up. -* Windows Keyboard:: Windows-specific keyboard features. -* Windows Mouse:: Windows-specific mouse features. -* Windows Processes:: Running subprocesses on Windows. -* Windows Printing:: How to specify the printer on MS-Windows. -* Windows Fonts:: Specifying fonts on MS-Windows. -* Windows Misc:: Miscellaneous Windows features. -@ifnottex -* MS-DOS:: Using Emacs on MS-DOS. - -Emacs and MS-DOS - -* MS-DOS Keyboard:: Keyboard conventions on MS-DOS. -* MS-DOS Mouse:: Mouse conventions on MS-DOS. -* MS-DOS Display:: Fonts, frames and display size on MS-DOS. -* MS-DOS File Names:: File name conventions on MS-DOS. -* MS-DOS Printing:: Printing specifics on MS-DOS. -* MS-DOS and MULE:: Support for internationalization on MS-DOS. -* MS-DOS Processes:: Running subprocesses on MS-DOS. -@end ifnottex - -@end detailmenu -@end menu - -@iftex -@unnumbered Preface - - This manual documents the use and simple customization of the Emacs -editor. Simple Emacs customizations do not require you to be a -programmer, but if you are not interested in customizing, you can -ignore the customization hints. - - This is primarily a reference manual, but can also be used as a -primer. If you are new to Emacs, we recommend you start with -the integrated, learn-by-doing tutorial, before reading the manual. To -run the tutorial, start Emacs and type @kbd{C-h t}. The tutorial -describes commands, tells you when to try them, and explains the -results. The tutorial is available in several languages. - - On first reading, just skim chapters 1 and 2, which describe the -notational conventions of the manual and the general appearance of the -Emacs display screen. Note which questions are answered in these -chapters, so you can refer back later. After reading chapter 4, you -should practice the commands shown there. The next few chapters -describe fundamental techniques and concepts that are used constantly. -You need to understand them thoroughly, so experiment with them -until you are fluent. - - Chapters 14 through 19 describe intermediate-level features that are -useful for many kinds of editing. Chapter 20 and following chapters -describe optional but useful features; read those chapters when you -need them. - - Read the Common Problems chapter if Emacs does not seem to be -working properly. It explains how to cope with several common -problems (@pxref{Lossage,, Dealing with Emacs Trouble}), as well as -when and how to report Emacs bugs (@pxref{Bugs}). - - To find the documentation of a particular command, look in the index. -Keys (character commands) and command names have separate indexes. -There is also a glossary, with a cross reference for each term. - - This manual is available as a printed book and also as an Info file. -The Info file is for reading from Emacs itself, or with the Info program. -Info is the principal format for documentation in the GNU system. -The Info file and the printed book contain substantially the same text -and are generated from the same source files, which are also -distributed with GNU Emacs. - - GNU Emacs is a member of the Emacs editor family. There are many -Emacs editors, all sharing common principles of organization. For -information on the underlying philosophy of Emacs and the lessons -learned from its development, see @cite{Emacs, the Extensible, -Customizable Self-Documenting Display Editor}, available from -@url{ftp://publications.ai.mit.edu/ai-publications/pdf/AIM-519A.pdf}. - -This version of the manual is mainly intended for use with GNU Emacs -installed on GNU and Unix systems. GNU Emacs can also be used on -MS-DOS, Microsoft Windows, and Macintosh systems. The Info file -version of this manual contains some more information about using -Emacs on those systems. Those systems use different file name syntax; -in addition MS-DOS does not support all GNU Emacs features. -@xref{Microsoft Windows}, for information about using Emacs on -Windows. @xref{Mac OS / GNUstep}, for information about using Emacs -on Macintosh (and GNUstep). -@end iftex - -@node Distrib, Intro, Top, Top -@unnumbered Distribution - -GNU Emacs is @dfn{free software}; this means that everyone is free to -use it and free to redistribute it under certain conditions. GNU Emacs -is not in the public domain; it is copyrighted and there are -restrictions on its distribution, but these restrictions are designed -to permit everything that a good cooperating citizen would want to do. -What is not allowed is to try to prevent others from further sharing -any version of GNU Emacs that they might get from you. The precise -conditions are found in the GNU General Public License that comes with -Emacs and also appears in this manual@footnote{This manual is itself -covered by the GNU Free Documentation License. This license is -similar in spirit to the General Public License, but is more suitable -for documentation. @xref{GNU Free Documentation License}.}. -@xref{Copying}. - -One way to get a copy of GNU Emacs is from someone else who has it. -You need not ask for our permission to do so, or tell any one else; -just copy it. If you have access to the Internet, you can get the -latest distribution version of GNU Emacs by anonymous FTP; see -@url{http://www.gnu.org/software/emacs} on our website for more -information. - -You may also receive GNU Emacs when you buy a computer. Computer -manufacturers are free to distribute copies on the same terms that apply to -everyone else. These terms require them to give you the full sources, -including whatever changes they may have made, and to permit you to -redistribute the GNU Emacs received from them under the usual terms of the -General Public License. In other words, the program must be free for you -when you get it, not just free for the manufacturer. - -If you find GNU Emacs useful, please @strong{send a donation} to the -Free Software Foundation to support our work. Donations to the Free -Software Foundation are tax deductible in the US. If you use GNU Emacs -at your workplace, please suggest that the company make a donation. -For more information on how you can help, see -@url{http://www.gnu.org/help/help.html}. - -We also sell hardcopy versions of this manual and @cite{An -Introduction to Programming in Emacs Lisp}, by Robert J.@: Chassell. -You can visit our online store at @url{http://shop.fsf.org/}. -The income from sales goes to support the foundation's purpose: the -development of new free software, and improvements to our existing -programs including GNU Emacs. - -If you need to contact the Free Software Foundation, see -@url{http://www.fsf.org/about/contact/}, or write to - -@display -Free Software Foundation -51 Franklin Street, Fifth Floor -Boston, MA 02110-1301 -USA -@end display - -@iftex -@node Acknowledgments, Intro, Distrib, Top -@unnumberedsec Acknowledgments - -Contributors to GNU Emacs include Jari Aalto, Per Abrahamsen, Tomas -Abrahamsson, Jay K.@: Adams, Alon Albert, Michael Albinus, Nagy -Andras, Benjamin Andresen, Ralf Angeli, Joe Arceneaux, Emil Åström, -Miles Bader, David Bakhash, Juanma Barranquero, Eli Barzilay, Thomas -Baumann, Steven L.@: Baur, Jay Belanger, Alexander L.@: Belikoff, -Thomas Bellman, Scott Bender, Boaz Ben-Zvi, Sergey Berezin, Karl -Berry, Anna M.@: Bigatti, Ray Blaak, Martin Blais, Jim Blandy, Johan -Bockgård, Jan Böcker, Joel Boehland, Lennart Borgman, Per Bothner, -Terrence Brannon, Frank Bresz, Peter Breton, Emmanuel Briot, Kevin -Broadey, Vincent Broman, Michael Brouwer, David M.@: Brown, Stefan Bruda, -Georges Brun-Cottan, Joe Buehler, Scott Byer, W@l{}odek Bzyl, -Bill Carpenter, Per Cederqvist, Hans Chalupsky, Chris Chase, Bob -Chassell, Andrew Choi, Chong Yidong, Sacha Chua, Stewart Clamen, James -Clark, Mike Clarkson, Glynn Clements, Andrew Cohen, Daniel Colascione, -Edward O'Connor, Christoph Conrad, Ludovic Courtès, Andrew Csillag, -Toby Cubitt, Baoqiu Cui, Doug Cutting, Mathias Dahl, Julien Danjou, Satyaki -Das, Vivek Dasmohapatra, Dan Davison, Michael DeCorte, Gary Delp, Nachum -Dershowitz, Dave Detlefs, Matthieu Devin, Christophe de Dinechin, Eri -Ding, Jan Djärv, Lawrence R.@: Dodd, Carsten Dominik, Scott Draves, -Benjamin Drieu, Viktor Dukhovni, Jacques Duthen, Dmitry Dzhus, John -Eaton, Rolf Ebert, Carl Edman, David Edmondson, Paul Eggert, Stephen -Eglen, Christian Egli, Torbjörn Einarsson, Tsugutomo Enami, David -Engster, Hans Henrik Eriksen, Michael Ernst, Ata Etemadi, Frederick -Farnbach, Oscar Figueiredo, Fred Fish, Steve Fisk, Karl Fogel, Gary -Foster, Eric S.@: Fraga, Romain Francoise, Noah Friedman, Andreas -Fuchs, Shigeru Fukaya, Hallvard Furuseth, Keith Gabryelski, Peter S.@: -Galbraith, Kevin Gallagher, Kevin Gallo, Juan León Lahoz García, -Howard Gayle, Daniel German, Stephen Gildea, Julien Gilles, David -Gillespie, Bob Glickstein, Deepak Goel, David De La Harpe Golden, Boris -Goldowsky, David Goodger, Chris Gray, Kevin Greiner, Michelangelo Grigni, Odd -Gripenstam, Kai Großjohann, Michael Gschwind, Bastien Guerry, Henry -Guillaume, Doug Gwyn, Bruno Haible, Ken'ichi Handa, Lars Hansen, Chris -Hanson, Jesper Harder, Alexandru Harsanyi, K.@: Shane Hartman, John -Heidemann, Jon K.@: Hellan, Magnus Henoch, Markus Heritsch, Dirk -Herrmann, Karl Heuer, Manabu Higashida, Konrad Hinsen, Anders Holst, -Jeffrey C.@: Honig, Tassilo Horn, Kurt Hornik, Tom Houlder, Joakim -Hove, Denis Howe, Lars Ingebrigtsen, Andrew Innes, Seiichiro Inoue, -Philip Jackson, Martyn Jago, Pavel Janik, Paul Jarc, Ulf Jasper, -Thorsten Jolitz, Michael K.@: Johnson, Kyle Jones, Terry Jones, Simon -Josefsson, Alexandre Julliard, Arne Jørgensen, Tomoji Kagatani, -Brewster Kahle, Tokuya Kameshima, Lute Kamstra, Ivan Kanis, David -Kastrup, David Kaufman, Henry Kautz, Taichi Kawabata, Taro Kawagishi, -Howard Kaye, Michael Kifer, Richard King, Peter Kleiweg, Karel -Klí@v{c}, Shuhei Kobayashi, Pavel Kobyakov, Larry K.@: Kolodney, David -M.@: Koppelman, Koseki Yoshinori, Robert Krawitz, Sebastian Kremer, -Ryszard Kubiak, Igor Kuzmin, David Kågedal, Daniel LaLiberte, Karl -Landstrom, Mario Lang, Aaron Larson, James R.@: Larus, Vinicius Jose -Latorre, Werner Lemberg, Frederic Lepied, Peter Liljenberg, Christian -Limpach, Lars Lindberg, Chris Lindblad, Anders Lindgren, Thomas Link, -Juri Linkov, Francis Litterio, Sergey Litvinov, Emilio C.@: Lopes, -Martin Lorentzon, Dave Love, Eric Ludlam, Károly L@H{o}rentey, Sascha -Lüdecke, Greg McGary, Roland McGrath, Michael McNamara, Alan Mackenzie, -Christopher J.@: Madsen, Neil M.@: Mager, Ken Manheimer, Bill Mann, -Brian Marick, Simon Marshall, Bengt Martensson, Charlie Martin, -Yukihiro Matsumoto, David Maus, Thomas May, Will Mengarini, David -Megginson, Stefan Merten, Ben A.@: Mesander, Wayne Mesard, Brad -Miller, Lawrence Mitchell, Richard Mlynarik, Gerd Moellmann, Stefan -Monnier, Keith Moore, Jan Moringen, Morioka Tomohiko, Glenn Morris, -Don Morrison, Diane Murray, Riccardo Murri, Sen Nagata, Erik Naggum, -Gergely Nagy, Nobuyoshi Nakada, Thomas Neumann, Mike Newton, Thien-Thi Nguyen, -Jurgen Nickelsen, Dan Nicolaescu, Hrvoje Niksic, Jeff Norden, -Andrew Norman, Kentaro Ohkouchi, Christian Ohler, -Kenichi Okada, Alexandre Oliva, Bob Olson, Michael Olson, Takaaki Ota, -Pieter E.@: J.@: Pareit, Ross Patterson, David Pearson, Juan Pechiar, -Jeff Peck, Damon Anton Permezel, Tom Perrine, William M.@: Perry, Per -Persson, Jens Petersen, Daniel Pfeiffer, Justus Piater, Richard L.@: -Pieri, Fred Pierresteguy, François Pinard, Daniel Pittman, Christian -Plaunt, Alexander Pohoyda, David Ponce, Francesco A.@: Potorti, -Michael D.@: Prange, Mukesh Prasad, Ken Raeburn, Marko Rahamaa, Ashwin -Ram, Eric S.@: Raymond, Paul Reilly, Edward M.@: Reingold, David -Reitter, Alex Rezinsky, Rob Riepel, Lara Rios, Adrian Robert, Nick -Roberts, Roland B.@: Roberts, John Robinson, Denis B.@: Roegel, Danny -Roozendaal, Sebastian Rose, William Rosenblatt, Markus Rost, Guillermo -J.@: Rozas, Martin Rudalics, Ivar Rummelhoff, Jason Rumney, Wolfgang -Rupprecht, Benjamin Rutt, Kevin Ryde, James B.@: Salem, Masahiko Sato, -Timo Savola, Jorgen Schaefer, Holger Schauer, William Schelter, Ralph -Schleicher, Gregor Schmid, Michael Schmidt, Ronald S.@: Schnell, -Philippe Schnoebelen, Jan Schormann, Alex Schroeder, Stefan Schoef, -Rainer Schoepf, Raymond Scholz, Eric Schulte, Andreas Schwab, Randal -Schwartz, Oliver Seidel, Manuel Serrano, Paul Sexton, Hovav Shacham, -Stanislav Shalunov, Marc Shapiro, Richard Sharman, Olin Shivers, Tibor -@v{S}imko, Espen Skoglund, Rick Sladkey, Lynn Slater, Chris Smith, -David Smith, Paul D.@: Smith, Wilson Snyder, William Sommerfeld, Simon -South, Andre Spiegel, Michael Staats, Thomas Steffen, Ulf Stegemann, -Reiner Steib, Sam Steingold, Ake Stenhoff, Peter Stephenson, Ken -Stevens, Andy Stewart, Jonathan Stigelman, Martin Stjernholm, Kim F.@: -Storm, Steve Strassmann, Christopher Suckling, Olaf Sylvester, Naoto -Takahashi, Steven Tamm, Luc Teirlinck, Jean-Philippe Theberge, Jens -T.@: Berger Thielemann, Spencer Thomas, Jim Thompson, Toru Tomabechi, -David O'Toole, Markus Triska, Tom Tromey, Enami Tsugutomo, Eli -Tziperman, Daiki Ueno, Masanobu Umeda, Rajesh Vaidheeswarran, Neil -W.@: Van Dyke, Didier Verna, Joakim Verona, Ulrik Vieth, Geoffrey -Voelker, Johan Vromans, Inge Wallin, John Paul Wallington, Colin -Walters, Barry Warsaw, Christoph Wedler, Ilja Weis, Zhang Weize, -Morten Welinder, Joseph Brian Wells, Rodney Whitby, John Wiegley, -Sascha Wilde, Ed Wilkinson, Mike Williams, Roland Winkler, Bill -Wohler, Steven A.@: Wood, Dale R.@: Worley, Francis J.@: Wright, Felix -S.@: T.@: Wu, Tom Wurgler, Yamamoto Mitsuharu, Katsumi Yamaoka, -Masatake Yamato, Jonathan Yavner, Ryan Yeske, Ilya Zakharevich, Milan -Zamazal, Victor Zandy, Eli Zaretskii, Jamie Zawinski, Andrew Zhilin, -Shenghuo Zhu, Piotr Zielinski, Ian T.@: Zimmermann, Reto Zimmermann, -Neal Ziring, Teodor Zlatanov, and Detlev Zundel. -@end iftex - -@node Intro, Glossary, Distrib, Top -@unnumbered Introduction - - You are reading about GNU Emacs, the GNU incarnation of the -advanced, self-documenting, customizable, extensible editor Emacs. -(The `G' in `GNU' is not silent.) - - We call Emacs @dfn{advanced} because it can do much more than simple -insertion and deletion of text. It can control subprocesses, indent -programs automatically, show multiple files at once, and more. -Emacs editing commands operate in terms of characters, words, lines, -sentences, paragraphs, and pages, as well as expressions and comments -in various programming languages. - - @dfn{Self-documenting} means that at any time you can use special -commands, known as @dfn{help commands}, to find out what your options -are, or to find out what any command does, or to find all the -commands that pertain to a given topic. @xref{Help}. - - @dfn{Customizable} means that you can easily alter the behavior of -Emacs commands in simple ways. For instance, if you use a programming -language in which comments start with @samp{<**} and end with -@samp{**>}, you can tell the Emacs comment manipulation commands to -use those strings (@pxref{Comments}). To take another example, you -can rebind the basic cursor motion commands (up, down, left and right) -to any keys on the keyboard that you find comfortable. -@xref{Customization}. - - @dfn{Extensible} means that you can go beyond simple customization -and create entirely new commands. New commands are simply programs -written in the Lisp language, which are run by Emacs's own Lisp -interpreter. Existing commands can even be redefined in the middle of -an editing session, without having to restart Emacs. Most of the -editing commands in Emacs are written in Lisp; the few exceptions -could have been written in Lisp but use C instead for efficiency. -Writing an extension is programming, but non-programmers can use it -afterwards. @xref{Top, Emacs Lisp Intro, Preface, eintr, An -Introduction to Programming in Emacs Lisp}, if you want to learn Emacs -Lisp programming. - -@include screen.texi -@include commands.texi -@include entering.texi -@include basic.texi -@include mini.texi -@include m-x.texi -@include help.texi -@include mark.texi -@include killing.texi -@include regs.texi -@include display.texi -@include search.texi -@include fixit.texi -@include kmacro.texi -@c Includes arevert-xtra. -@include files.texi -@include buffers.texi -@include windows.texi -@include frames.texi -@include mule.texi -@include modes.texi -@include indent.texi -@include text.texi -@c Includes fortran-xtra. -@include programs.texi -@include building.texi -@c Includes vc1-xtra, emerge-xtra. -@include maintaining.texi -@include abbrevs.texi -@c Includes dired-xtra. -@include dired.texi -@c Includes cal-xtra. -@include calendar.texi -@include sending.texi -@include rmail.texi -@c Includes picture-xtra.texi -@include misc.texi -@include package.texi -@include custom.texi -@include trouble.texi - -@node Copying, GNU Free Documentation License, Service, Top -@appendix GNU GENERAL PUBLIC LICENSE -@include gpl.texi - -@node GNU Free Documentation License, Emacs Invocation, Copying, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@include cmdargs.texi -@include xresources.texi - -@include anti.texi -@include macos.texi -@c Includes msdog-xtra. -@include msdog.texi -@include gnu.texi -@include glossary.texi -@ifnottex -@include ack.texi -@end ifnottex - -@c The Option Index is produced only in the on-line version, -@c because the index entries related to command-line options -@c tend to point to the same pages and all begin with a dash. -@c This, and the need to keep the node links consistent, are -@c the reasons for the funky @iftex/@ifnottex dance below. -@c The Option Index is _not_ before Key Index, because that -@c would require changes in the glossary.texi's @node line. -@c It is not after Concept Index for similar reasons. - -@iftex -@node Key Index, Command Index, Glossary, Top -@unnumbered Key (Character) Index -@printindex ky -@end iftex - -@ifnottex -@node Key Index, Option Index, Glossary, Top -@unnumbered Key (Character) Index -@printindex ky - -@node Option Index, Command Index, Key Index, Top -@unnumbered Command-Line Options Index -@printindex op - -@node Command Index, Variable Index, Option Index, Top -@unnumbered Command and Function Index -@printindex fn -@end ifnottex - -@iftex -@node Command Index, Variable Index, Key Index, Top -@unnumbered Command and Function Index -@printindex fn -@end iftex - -@node Variable Index, Concept Index, Command Index, Top -@unnumbered Variable Index -@printindex vr - -@node Concept Index, Acknowledgments, Variable Index, Top -@unnumbered Concept Index -@printindex cp - -@bye diff --git a/doc/emacs/emacsver.texi b/doc/emacs/emacsver.texi deleted file mode 100644 index 1c12f47497c..00000000000 --- a/doc/emacs/emacsver.texi +++ /dev/null @@ -1,4 +0,0 @@ -@c It would be nicer to generate this using configure and @version@. -@c However, that would mean emacsver.texi would always be newer -@c then the info files in release tarfiles. -@set EMACSVER 24.1 diff --git a/doc/emacs/emerge-xtra.texi b/doc/emacs/emerge-xtra.texi deleted file mode 100644 index 552580ef851..00000000000 --- a/doc/emacs/emerge-xtra.texi +++ /dev/null @@ -1,413 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Emerge -@section Merging Files with Emerge -@cindex Emerge -@cindex merging files - - It's not unusual for programmers to get their signals crossed and -modify the same program in two different directions. To recover from -this confusion, you need to merge the two versions. Emerge makes this -easier. For other ways to compare files, see -@iftex -@ref{Comparing Files,,, emacs, the Emacs Manual}, -@end iftex -@ifnottex -@ref{Comparing Files}, -@end ifnottex -and @ref{Top,, Ediff, ediff, The Ediff Manual}. - -@menu -* Overview of Emerge:: How to start Emerge. Basic concepts. -* Submodes of Emerge:: Fast mode vs. Edit mode. - Skip Prefers mode and Auto Advance mode. -* State of Difference:: You do the merge by specifying state A or B - for each difference. -* Merge Commands:: Commands for selecting a difference, - changing states of differences, etc. -* Exiting Emerge:: What to do when you've finished the merge. -* Combining in Emerge:: How to keep both alternatives for a difference. -* Fine Points of Emerge:: Miscellaneous issues. -@end menu - -@node Overview of Emerge -@subsection Overview of Emerge - - To start Emerge, run one of these four commands: - -@table @kbd -@item M-x emerge-files -@findex emerge-files -Merge two specified files. - -@item M-x emerge-files-with-ancestor -@findex emerge-files-with-ancestor -Merge two specified files, with reference to a common ancestor. - -@item M-x emerge-buffers -@findex emerge-buffers -Merge two buffers. - -@item M-x emerge-buffers-with-ancestor -@findex emerge-buffers-with-ancestor -Merge two buffers with reference to a common ancestor in a third -buffer. -@end table - -@cindex merge buffer (Emerge) -@cindex A and B buffers (Emerge) - The Emerge commands compare two files or buffers, and display the -comparison in three buffers: one for each input text (the @dfn{A buffer} -and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging -takes place. The merge buffer shows the full merged text, not just the -differences. Wherever the two input texts differ, you can choose which -one of them to include in the merge buffer. - - The Emerge commands that take input from existing buffers use only -the accessible portions of those buffers, if they are narrowed. -@iftex -@xref{Narrowing,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Narrowing}. -@end ifnottex - - - If a common ancestor version is available, from which the two texts to -be merged were both derived, Emerge can use it to guess which -alternative is right. Wherever one current version agrees with the -ancestor, Emerge presumes that the other current version is a deliberate -change which should be kept in the merged version. Use the -@samp{with-ancestor} commands if you want to specify a common ancestor -text. These commands read three file or buffer names---variant A, -variant B, and the common ancestor. - - After the comparison is done and the buffers are prepared, the -interactive merging starts. You control the merging by typing special -@dfn{merge commands} in the merge buffer (@pxref{Merge Commands}). -For each run of differences between the input texts, you can choose -which one of them to keep, or edit them both together. - - The merge buffer uses a special major mode, Emerge mode, with commands -for making these choices. But you can also edit the buffer with -ordinary Emacs commands. - - At any given time, the attention of Emerge is focused on one -particular difference, called the @dfn{selected} difference. This -difference is marked off in the three buffers like this: - -@example -vvvvvvvvvvvvvvvvvvvv -@var{text that differs} -^^^^^^^^^^^^^^^^^^^^ -@end example - -@noindent -Emerge numbers all the differences sequentially and the mode -line always shows the number of the selected difference. - - Normally, the merge buffer starts out with the A version of the text. -But when the A version of a difference agrees with the common ancestor, -then the B version is initially preferred for that difference. - - Emerge leaves the merged text in the merge buffer when you exit. At -that point, you can save it in a file with @kbd{C-x C-w}. If you give a -numeric argument to @code{emerge-files} or -@code{emerge-files-with-ancestor}, it reads the name of the output file -using the minibuffer. (This is the last file name those commands read.) -Then exiting from Emerge saves the merged text in the output file. - - Normally, Emerge commands save the output buffer in its file when you -exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not -save the output buffer, but you can save it yourself if you wish. - -@node Submodes of Emerge -@subsection Submodes of Emerge - - You can choose between two modes for giving merge commands: Fast mode -and Edit mode. In Fast mode, basic merge commands are single -characters, but ordinary Emacs commands are disabled. This is -convenient if you use only merge commands. In Edit mode, all merge -commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs -commands are also available. This allows editing the merge buffer, but -slows down Emerge operations. - - Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to -Fast mode. The mode line indicates Edit and Fast modes with @samp{E} -and @samp{F}. - - Emerge has two additional submodes that affect how particular merge -commands work: Auto Advance mode and Skip Prefers mode. - - If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands -advance to the next difference. This lets you go through the merge -faster as long as you simply choose one of the alternatives from the -input. The mode line indicates Auto Advance mode with @samp{A}. - - If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands -skip over differences in states ``prefer-A'' and ``prefer-B'' -(@pxref{State of Difference}). Thus you see only differences for -which neither version is presumed ``correct''. The mode line -indicates Skip Prefers mode with @samp{S}. This mode is only relevant -when there is an ancestor. - -@findex emerge-auto-advance -@findex emerge-skip-prefers - Use the command @kbd{s a} (@code{emerge-auto-advance}) to set or clear -Auto Advance mode. Use @kbd{s s} (@code{emerge-skip-prefers}) to set or -clear Skip Prefers mode. These commands turn on the mode with a -positive argument, turn it off with a negative or zero argument, and -toggle the mode with no argument. - -@node State of Difference -@subsection State of a Difference - - In the merge buffer, a difference is marked with lines of @samp{v} and -@samp{^} characters. Each difference has one of these seven states: - -@table @asis -@item A -The difference is showing the A version. The @kbd{a} command always -produces this state; the mode line indicates it with @samp{A}. - -@item B -The difference is showing the B version. The @kbd{b} command always -produces this state; the mode line indicates it with @samp{B}. - -@item default-A -@itemx default-B -The difference is showing the A or the B state by default, because you -haven't made a choice. All differences start in the default-A state -(and thus the merge buffer is a copy of the A buffer), except those for -which one alternative is ``preferred'' (see below). - -When you select a difference, its state changes from default-A or -default-B to plain A or B. Thus, the selected difference never has -state default-A or default-B, and these states are never displayed in -the mode line. - -The command @kbd{d a} chooses default-A as the default state, and @kbd{d -b} chooses default-B. This chosen default applies to all differences -that you have never selected and for which no alternative is preferred. -If you are moving through the merge sequentially, the differences you -haven't selected are those following the selected one. Thus, while -moving sequentially, you can effectively make the A version the default -for some sections of the merge buffer and the B version the default for -others by using @kbd{d a} and @kbd{d b} between sections. - -@item prefer-A -@itemx prefer-B -The difference is showing the A or B state because it is -@dfn{preferred}. This means that you haven't made an explicit choice, -but one alternative seems likely to be right because the other -alternative agrees with the common ancestor. Thus, where the A buffer -agrees with the common ancestor, the B version is preferred, because -chances are it is the one that was actually changed. - -These two states are displayed in the mode line as @samp{A*} and @samp{B*}. - -@item combined -The difference is showing a combination of the A and B states, as a -result of the @kbd{x c} or @kbd{x C} commands. - -Once a difference is in this state, the @kbd{a} and @kbd{b} commands -don't do anything to it unless you give them a numeric argument. - -The mode line displays this state as @samp{comb}. -@end table - -@node Merge Commands -@subsection Merge Commands - - Here are the Merge commands for Fast mode; in Edit mode, precede them -with @kbd{C-c C-c}: - -@table @kbd -@item p -Select the previous difference. - -@item n -Select the next difference. - -@item a -Choose the A version of this difference. - -@item b -Choose the B version of this difference. - -@item C-u @var{n} j -Select difference number @var{n}. - -@item . -Select the difference containing point. -@c [Does not work in the A or B buffer?] -@c You can use this command in the merge buffer or in the A or B buffer. - -@item q -Quit---finish the merge. - -@item C-] -Abort---exit merging and do not save the output. - -@item f -Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) - -@item e -Go into Edit mode. - -@item l -Recenter (like @kbd{C-l}) all three windows. With an argument, -reestablish the default three-window display. - -@item - -Specify part of a prefix numeric argument. - -@item @var{digit} -Also specify part of a prefix numeric argument. - -@item d a -Choose the A version as the default from here down in -the merge buffer. - -@item d b -Choose the B version as the default from here down in -the merge buffer. - -@item c a -Copy the A version of this difference into the kill ring. - -@item c b -Copy the B version of this difference into the kill ring. - -@item i a -Insert the A version of this difference at point. - -@item i b -Insert the B version of this difference at point. - -@item m -Put point and mark around the difference. - -@item ^ -Scroll all three windows down (like @kbd{M-v}). - -@item v -Scroll all three windows up (like @kbd{C-v}). - -@item < -Scroll all three windows left (like @kbd{C-x <}). - -@item > -Scroll all three windows right (like @kbd{C-x >}). - -@item | -Reset horizontal scroll on all three windows. - -@item x 1 -Shrink the merge window to one line. (Use @kbd{C-u l} to restore it -to full size.) - -@item x c -Combine the two versions of this difference (@pxref{Combining in -Emerge}). - -@item x f -Show the names of the files/buffers Emerge is operating on, in a Help -window. (Use @kbd{C-u l} to restore windows.) - -@item x j -Join this difference with the following one. -(@kbd{C-u x j} joins this difference with the previous one.) - -@item x s -Split this difference into two differences. Before you use this -command, position point in each of the three buffers at the place where -you want to split the difference. - -@item x t -Trim identical lines off the top and bottom of the difference. -Such lines occur when the A and B versions are -identical but differ from the ancestor version. -@end table - -@node Exiting Emerge -@subsection Exiting Emerge - - The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing -the results into the output file if you specified one. It restores the -A and B buffers to their proper contents, or kills them if they were -created by Emerge and you haven't changed them. It also disables the -Emerge commands in the merge buffer, since executing them later could -damage the contents of the various buffers. - - @kbd{C-]} aborts the merge. This means exiting without writing the -output file. If you didn't specify an output file, then there is no -real difference between aborting and finishing the merge. - - If the Emerge command was called from another Lisp program, then its -return value is @code{t} for successful completion, or @code{nil} if you -abort. - -@node Combining in Emerge -@subsection Combining the Two Versions - - Sometimes you want to keep @emph{both} alternatives for a particular -difference. To do this, use @kbd{x c}, which edits the merge buffer -like this: - -@example -@group -#ifdef NEW -@var{version from B buffer} -#else /* not NEW */ -@var{version from A buffer} -#endif /* not NEW */ -@end group -@end example - -@noindent -@vindex emerge-combine-versions-template -While this example shows C preprocessor conditionals delimiting the two -alternative versions, you can specify the strings to use by setting -the variable @code{emerge-combine-versions-template} to a string of your -choice. In the string, @samp{%a} says where to put version A, and -@samp{%b} says where to put version B. The default setting, which -produces the results shown above, looks like this: - -@example -@group -"#ifdef NEW\n%b#else /* not NEW */\n%a#endif /* not NEW */\n" -@end group -@end example - -@node Fine Points of Emerge -@subsection Fine Points of Emerge - - During the merge, you mustn't try to edit the A and B buffers yourself. -Emerge modifies them temporarily, but ultimately puts them back the way -they were. - - You can have any number of merges going at once---just don't use any one -buffer as input to more than one merge at once, since the temporary -changes made in these buffers would get in each other's way. - - Starting Emerge can take a long time because it needs to compare the -files fully. Emacs can't do anything else until @code{diff} finishes. -Perhaps in the future someone will change Emerge to do the comparison in -the background when the input files are large---then you could keep on -doing other things with Emacs until Emerge is ready to accept -commands. - -@vindex emerge-startup-hook - After setting up the merge, Emerge runs the hook -@code{emerge-startup-hook}. -@iftex -@xref{Hooks,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Hooks}. -@end ifnottex diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi deleted file mode 100644 index 3ec51ddfb60..00000000000 --- a/doc/emacs/entering.texi +++ /dev/null @@ -1,162 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Entering and Exiting Emacs - - This chapter explains how to enter Emacs, and how to exit it. -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node Entering Emacs, Exiting, Commands, Top -@section Entering Emacs -@cindex entering Emacs -@cindex starting Emacs - - The usual way to invoke Emacs is with the shell command -@command{emacs}. From a terminal window running in the X Window -System, you can run Emacs in the background with @command{emacs &}; -this way, Emacs won't tie up the terminal window, so you can use it to -run other shell commands. - -@cindex startup screen - When Emacs starts up, the initial frame displays a special buffer -named @samp{*GNU Emacs*}. This @dfn{startup screen} contains -information about Emacs and @dfn{links} to common tasks that are -useful for beginning users. For instance, activating the @samp{Emacs -Tutorial} link opens the Emacs tutorial; this does the same thing as -the command @kbd{C-h t} (@code{help-with-tutorial}). To activate a -link, either move point onto it and type @kbd{@key{RET}}, or click on -it with @kbd{mouse-1} (the left mouse button). - - Using a command line argument, you can tell Emacs to visit one or -more files as soon as it starts up. For example, @command{emacs -foo.txt} starts Emacs with a buffer displaying the contents of the -file @samp{foo.txt}. This feature exists mainly for compatibility -with other editors, which are designed to be launched from the shell -for short editing sessions. If you call Emacs this way, the initial -frame is split into two windows---one showing the specified file, and -the other showing the startup screen. @xref{Windows}. - - Generally, it is unnecessary and wasteful to start Emacs afresh each -time you want to edit a file. The recommended way to use Emacs is to -start it just once, just after you log in, and do all your editing in -the same Emacs session. @xref{Files}, for information on visiting -more than one file. If you use Emacs this way, the Emacs session -accumulates valuable context, such as the kill ring, registers, undo -history, and mark ring data, which together make editing more -convenient. These features are described later in the manual. - - To edit a file from another program while Emacs is running, you can -use the @command{emacsclient} helper program to open a file in the -existing Emacs session. @xref{Emacs Server}. - - Emacs accepts other command line arguments that tell it to load -certain Lisp files, where to put the initial frame, and so forth. -@xref{Emacs Invocation}. - -@vindex inhibit-startup-screen - If the variable @code{inhibit-startup-screen} is non-@code{nil}, -Emacs does not display the startup screen. In that case, if one or -more files were specified on the command line, Emacs simply displays -those files; otherwise, it displays a buffer named @file{*scratch*}, -which can be used to evaluate Emacs Lisp expressions interactively. -@xref{Lisp Interaction}. You can set the variable -@code{inhibit-startup-screen} using the Customize facility -(@pxref{Easy Customization}), or by editing your initialization file -(@pxref{Init File}).@footnote{Setting @code{inhibit-startup-screen} in -@file{site-start.el} doesn't work, because the startup screen is set -up before reading @file{site-start.el}. @xref{Init File}, for -information about @file{site-start.el}.} - - You can also force Emacs to display a file or directory at startup -by setting the variable @code{initial-buffer-choice} to a -non-@code{nil} value. (In that case, even if you specify one or more -files on the command line, Emacs opens but does not display them.) -The value of @code{initial-buffer-choice} should be the name of -the desired file or directory. -@ignore -@c I do not think this should be mentioned. AFAICS it is just a dodge -@c around inhibit-startup-screen not being settable on a site-wide basis. -or @code{t}, which means to display the @file{*scratch*} buffer. -@end ignore - -@node Exiting, Basic, Entering Emacs, Top -@section Exiting Emacs -@cindex exiting -@cindex killing Emacs -@cindex leaving Emacs -@cindex quitting Emacs - -@table @kbd -@item C-x C-c -Kill Emacs (@code{save-buffers-kill-terminal}). -@item C-z -On a text terminal, suspend Emacs; on a graphical display, -``minimize'' the selected frame (@code{suspend-emacs}). -@end table - -@kindex C-x C-c -@findex save-buffers-kill-terminal - @dfn{Killing} Emacs means terminating the Emacs program. To do -this, type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}). A -two-character key sequence is used to make it harder to type by -accident. If there are any modified file-visiting buffers when you -type @kbd{C-x C-c}, Emacs first offers to save these buffers. If you -do not save them all, it asks for confirmation again, since the -unsaved changes will be lost. Emacs also asks for confirmation if any -subprocesses are still running, since killing Emacs will also kill the -subprocesses (@pxref{Shell}). - - @kbd{C-x C-c} behaves specially if you are using Emacs as a server. -If you type it from a ``client frame'', it closes the client -connection. @xref{Emacs Server}. - - Emacs can, optionally, record certain session information when you -kill it, such as the files you were visiting at the time. This -information is then available the next time you start Emacs. -@xref{Saving Emacs Sessions}. - -@vindex confirm-kill-emacs - If the value of the variable @code{confirm-kill-emacs} is -non-@code{nil}, @kbd{C-x C-c} assumes that its value is a predicate -function, and calls that function. If the result of the function call -is non-@code{nil}, the session is killed, otherwise Emacs continues to -run. One convenient function to use as the value of -@code{confirm-kill-emacs} is the function @code{yes-or-no-p}. The -default value of @code{confirm-kill-emacs} is @code{nil}. - -@findex kill-emacs - To kill Emacs without being prompted about saving, type @kbd{M-x -kill-emacs}. - -@kindex C-z -@findex suspend-frame -@cindex minimizing -@cindex iconifying -@cindex suspending - @kbd{C-z} runs the command @code{suspend-frame}. On a graphical -display, this command @dfn{minimizes} (or @dfn{iconifies}) the -selected Emacs frame, hiding it in a way that lets you bring it back -later (exactly how this hiding occurs depends on the window system). -On a text terminal, the @kbd{C-z} command @dfn{suspends} Emacs, -stopping the program temporarily and returning control to the parent -process (usually a shell); in most shells, you can resume Emacs after -suspending it with the shell command @command{%emacs}. - - Text terminals usually listen for certain special characters whose -meaning is to kill or suspend the program you are running. @b{This -terminal feature is turned off while you are in Emacs.} The meanings -of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were inspired by the -use of @kbd{C-z} and @kbd{C-c} on several operating systems as the -characters for stopping or killing a program, but that is their only -relationship with the operating system. You can customize these keys -to run any commands of your choice (@pxref{Keymaps}). - -@ifnottex -@lowersections -@end ifnottex diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi deleted file mode 100644 index 31883a1f5cc..00000000000 --- a/doc/emacs/files.texi +++ /dev/null @@ -1,1984 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Files, Buffers, Keyboard Macros, Top -@chapter File Handling -@cindex files - - The operating system stores data permanently in named @dfn{files}, so -most of the text you edit with Emacs comes from a file and is ultimately -stored in a file. - - To edit a file, you must tell Emacs to read the file and prepare a -buffer containing a copy of the file's text. This is called -@dfn{visiting} the file. Editing commands apply directly to text in the -buffer; that is, to the copy inside Emacs. Your changes appear in the -file itself only when you @dfn{save} the buffer back into the file. - - In addition to visiting and saving files, Emacs can delete, copy, -rename, and append to files, keep multiple versions of them, and operate -on file directories. - -@menu -* File Names:: How to type and edit file-name arguments. -* Visiting:: Visiting a file prepares Emacs to edit the file. -* Saving:: Saving makes your changes permanent. -* Reverting:: Reverting cancels all the changes not saved. -@ifnottex -* Autorevert:: Auto Reverting non-file buffers. -@end ifnottex -* Auto Save:: Auto Save periodically protects against loss of data. -* File Aliases:: Handling multiple names for one file. -* Directories:: Creating, deleting, and listing file directories. -* Comparing Files:: Finding where two files differ. -* Diff Mode:: Mode for editing file differences. -* Misc File Ops:: Other things you can do on files. -* Compressed Files:: Accessing compressed files. -* File Archives:: Operating on tar, zip, jar etc. archive files. -* Remote Files:: Accessing files on other machines. -* Quoted File Names:: Quoting special characters in file names. -* File Name Cache:: Completion against a list of files you often use. -* File Conveniences:: Convenience Features for Finding Files. -* Filesets:: Handling sets of files. -@end menu - -@node File Names -@section File Names -@cindex file names - -@cindex default file name - Many Emacs commands that operate on a file require you to specify -the file name, using the minibuffer (@pxref{Minibuffer File}). - - While in the minibuffer, you can use the usual completion and -history commands (@pxref{Minibuffer}). Note that file name completion -ignores file names whose extensions appear in the variable -@code{completion-ignored-extensions} (@pxref{Completion Options}). -Note also that most commands use ``permissive completion with -confirmation'' for reading file names: you are allowed to submit a -nonexistent file name, but if you type @key{RET} immediately after -completing up to a nonexistent file name, Emacs prints -@samp{[Confirm]} and you must type a second @key{RET} to confirm. -@xref{Completion Exit}, for details. - -@cindex default directory -@vindex default-directory -@vindex insert-default-directory - Each buffer has a @dfn{default directory}, stored in the -buffer-local variable @code{default-directory}. Whenever Emacs reads -a file name using the minibuffer, it usually inserts the default -directory into the minibuffer as the initial contents. You can -inhibit this insertion by changing the variable -@code{insert-default-directory} to @code{nil} (@pxref{Minibuffer -File}). Regardless, Emacs always assumes that any relative file name -is relative to the default directory, e.g. entering a file name -without a directory specifies a file in the default directory. - -@findex cd -@findex pwd - When you visit a file, Emacs sets @code{default-directory} in the -visiting buffer to the directory of its file. When you create a new -buffer that is not visiting a file, via a command like @kbd{C-x b}, -its default directory is usually copied from the buffer that was -current at the time (@pxref{Select Buffer}). You can use the command -@kbd{M-x pwd} to see the value of @code{default-directory} in the -current buffer. The command @kbd{M-x cd} prompts for a directory -name, and sets the buffer's @code{default-directory} to that directory -(doing this does not change the buffer's file name, if any). - - As an example, when you visit the file @file{/u/rms/gnu/gnu.tasks}, -the default directory is set to @file{/u/rms/gnu/}. If you invoke a -command that reads a file name, entering just @samp{foo} in the -minibuffer, with a directory omitted, specifies the file -@file{/u/rms/gnu/foo}; entering @samp{../.login} specifies -@file{/u/rms/.login}; and entering @samp{new/foo} specifies -@file{/u/rms/gnu/new/foo}. - - When typing a file name into the minibuffer, you can make use of a -couple of shortcuts: a double slash is interpreted as ``ignore -everything before the second slash in the pair'', and @samp{~/} is -interpreted as your home directory. @xref{Minibuffer File}. - -@cindex environment variables in file names -@cindex expansion of environment variables -@cindex @code{$} in file names - @anchor{File Names with $}The character @samp{$} is used to -substitute an environment variable into a file name. The name of the -environment variable consists of all the alphanumeric characters after -the @samp{$}; alternatively, it can be enclosed in braces after the -@samp{$}. For example, if you have used the shell command -@command{export FOO=rms/hacks} to set up an environment variable named -@env{FOO}, then both @file{/u/$FOO/test.c} and -@file{/u/$@{FOO@}/test.c} are abbreviations for -@file{/u/rms/hacks/test.c}. If the environment variable is not -defined, no substitution occurs, so that the character @samp{$} stands -for itself. Note that environment variables affect Emacs only if they -are applied before Emacs is started. - - To access a file with @samp{$} in its name, if the @samp{$} causes -expansion, type @samp{$$}. This pair is converted to a single -@samp{$} at the same time that variable substitution is performed for -a single @samp{$}. Alternatively, quote the whole file name with -@samp{/:} (@pxref{Quoted File Names}). File names which begin with a -literal @samp{~} should also be quoted with @samp{/:}. - - You can include non-@acronym{ASCII} characters in file names. -@xref{File Name Coding}. - -@node Visiting -@section Visiting Files -@cindex visiting files -@cindex open file - -@table @kbd -@item C-x C-f -Visit a file (@code{find-file}). -@item C-x C-r -Visit a file for viewing, without allowing changes to it -(@code{find-file-read-only}). -@item C-x C-v -Visit a different file instead of the one visited last -(@code{find-alternate-file}). -@item C-x 4 f -Visit a file, in another window (@code{find-file-other-window}). Don't -alter what is displayed in the selected window. -@item C-x 5 f -Visit a file, in a new frame (@code{find-file-other-frame}). Don't -alter what is displayed in the selected frame. -@item M-x find-file-literally -Visit a file with no conversion of the contents. -@end table - -@cindex files, visiting and saving -@cindex saving files - @dfn{Visiting} a file means reading its contents into an Emacs -buffer so you can edit them. Emacs makes a new buffer for each file -that you visit. - -@kindex C-x C-f -@findex find-file - To visit a file, type @kbd{C-x C-f} (@code{find-file}) and use the -minibuffer to enter the name of the desired file. While in the -minibuffer, you can abort the command by typing @kbd{C-g}. @xref{File -Names}, for details about entering file names into minibuffers. - - If the specified file exists but the system does not allow you to -read it, an error message is displayed in the echo area. Otherwise, -you can tell that @kbd{C-x C-f} has completed successfully by the -appearance of new text on the screen, and by the buffer name shown in -the mode line (@pxref{Mode Line}). Emacs normally constructs the -buffer name from the file name, omitting the directory name. For -example, a file named @file{/usr/rms/emacs.tex} is visited in a buffer -named @samp{emacs.tex}. If there is already a buffer with that name, -Emacs constructs a unique name; the normal method is to append -@samp{<2>}, @samp{<3>}, and so on, but you can select other methods. -@xref{Uniquify}. - -@cindex creating files - To create a new file, just visit it using the same command, @kbd{C-x -C-f}. Emacs displays @samp{(New file)} in the echo area, but in other -respects behaves as if you had visited an existing empty file. - -@cindex modified (buffer) - After visiting a file, the changes you make with editing commands are -made in the Emacs buffer. They do not take effect in the visited -file, until you @dfn{save} the buffer (@pxref{Saving}). If a buffer -contains changes that have not been saved, we say the buffer is -@dfn{modified}. This implies that some changes will be lost if the -buffer is not saved. The mode line displays two stars near the left -margin to indicate that the buffer is modified. - - If you visit a file that is already in Emacs, @kbd{C-x C-f} switches -to the existing buffer instead of making another copy. Before doing -so, it checks whether the file has changed since you last visited or -saved it. If the file has changed, Emacs offers to reread it. - -@vindex large-file-warning-threshold -@cindex file, warning when size is large -@cindex size of file, warning when visiting -@cindex maximum buffer size exceeded, error message - If you try to visit a file larger than -@code{large-file-warning-threshold} (the default is 10000000, which is -about 10 megabytes), Emacs asks you for confirmation first. You can -answer @kbd{y} to proceed with visiting the file. Note, however, that -Emacs cannot visit files that are larger than the maximum Emacs buffer -size, which is limited by the amount of memory Emacs can allocate and -by the integers that Emacs can represent (@pxref{Buffers}). If you -try, Emacs displays an error message saying that the maximum buffer -size has been exceeded. - -@cindex wildcard characters in file names -@vindex find-file-wildcards - If the file name you specify contains shell-style wildcard -characters, Emacs visits all the files that match it. (On -case-insensitive filesystems, Emacs matches the wildcards disregarding -the letter case.) Wildcards include @samp{?}, @samp{*}, and -@samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file -name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted -File Names}, for information on how to visit a file whose name -actually contains wildcard characters. You can disable the wildcard -feature by customizing @code{find-file-wildcards}. - -@kindex C-x C-v -@findex find-alternate-file - If you visit the wrong file unintentionally by typing its name -incorrectly, type @kbd{C-x C-v} (@code{find-alternate-file}) to visit -the file you really wanted. @kbd{C-x C-v} is similar to @kbd{C-x -C-f}, but it kills the current buffer (after first offering to save it -if it is modified). When @kbd{C-x C-v} reads the file name to visit, -it inserts the entire default file name in the buffer, with point just -after the directory part; this is convenient if you made a slight -error in typing the name. - -@vindex find-file-run-dired - If you ``visit'' a file that is actually a directory, Emacs invokes -Dired, the Emacs directory browser. @xref{Dired}. You can disable -this behavior by setting the variable @code{find-file-run-dired} to -@code{nil}; in that case, it is an error to try to visit a directory. - - Files which are actually collections of other files, or @dfn{file -archives}, are visited in special modes which invoke a Dired-like -environment to allow operations on archive members. @xref{File -Archives}, for more about these features. - - If you visit a file that the operating system won't let you modify, -or that is marked read-only, Emacs makes the buffer read-only too, so -that you won't go ahead and make changes that you'll have trouble -saving afterward. You can make the buffer writable with @kbd{C-x C-q} -(@code{toggle-read-only}). @xref{Misc Buffer}. - -@kindex C-x C-r -@findex find-file-read-only - If you want to visit a file as read-only in order to protect -yourself from entering changes accidentally, visit it with the command -@kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}. - -@kindex C-x 4 f -@findex find-file-other-window - @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f} -except that the buffer containing the specified file is selected in another -window. The window that was selected before @kbd{C-x 4 f} continues to -show the same buffer it was already showing. If this command is used when -only one window is being displayed, that window is split in two, with one -window showing the same buffer as before, and the other one showing the -newly requested file. @xref{Windows}. - -@kindex C-x 5 f -@findex find-file-other-frame - @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a -new frame, or selects any existing frame showing the specified file. -@xref{Frames}. - -@cindex file selection dialog - On graphical displays, there are two additional methods for visiting -files. Firstly, when Emacs is built with a suitable GUI toolkit, -commands invoked with the mouse (by clicking on the menu bar or tool -bar) use the toolkit's standard ``File Selection'' dialog instead of -prompting for the file name in the minibuffer. On GNU/Linux and Unix -platforms, Emacs does this when built with GTK, LessTif, and Motif -toolkits; on MS-Windows and Mac, the GUI version does that by default. -For information on how to customize this, see @ref{Dialog Boxes}. - - Secondly, Emacs supports ``drag and drop'': dropping a file into an -ordinary Emacs window visits the file using that window. As an -exception, dropping a file into a window displaying a Dired buffer -moves or copies the file into the displayed directory. For details, -see @ref{Drag and Drop}, and @ref{Misc Dired Features}. - - Each time you visit a file, Emacs automatically scans its contents -to detect what character encoding and end-of-line convention it uses, -and converts these to Emacs's internal encoding and end-of-line -convention within the buffer. When you save the buffer, Emacs -performs the inverse conversion, writing the file to disk with its -original encoding and end-of-line convention. @xref{Coding Systems}. - -@findex find-file-literally - If you wish to edit a file as a sequence of @acronym{ASCII} -characters with no special encoding or conversion, use the @kbd{M-x -find-file-literally} command. This visits a file, like @kbd{C-x C-f}, -but does not do format conversion (@pxref{Format Conversion,, Format -Conversion, elisp, the Emacs Lisp Reference Manual}), character code -conversion (@pxref{Coding Systems}), or automatic uncompression -(@pxref{Compressed Files}), and does not add a final newline because -of @code{require-final-newline} (@pxref{Customize Save}). If you have -already visited the same file in the usual (non-literal) manner, this -command asks you whether to visit it literally instead. - -@vindex find-file-hook -@vindex find-file-not-found-functions - Two special hook variables allow extensions to modify the operation -of visiting files. Visiting a file that does not exist runs the -functions in @code{find-file-not-found-functions}; this variable holds -a list of functions, which are called one by one (with no arguments) -until one of them returns non-@code{nil}. This is not a normal hook, -and the name ends in @samp{-functions} rather than @samp{-hook} to -indicate that fact. - - Successful visiting of any file, whether existing or not, calls the -functions in @code{find-file-hook}, with no arguments. This variable -is a normal hook. In the case of a nonexistent file, the -@code{find-file-not-found-functions} are run first. @xref{Hooks}. - - There are several ways to specify automatically the major mode for -editing the file (@pxref{Choosing Modes}), and to specify local -variables defined for that file (@pxref{File Variables}). - -@node Saving -@section Saving Files - - @dfn{Saving} a buffer in Emacs means writing its contents back into the file -that was visited in the buffer. - -@menu -* Save Commands:: Commands for saving files. -* Backup:: How Emacs saves the old version of your file. -* Customize Save:: Customizing the saving of files. -* Interlocking:: How Emacs protects against simultaneous editing - of one file by two users. -* Shadowing: File Shadowing. Copying files to "shadows" automatically. -* Time Stamps:: Emacs can update time stamps on saved files. -@end menu - -@node Save Commands -@subsection Commands for Saving Files - - These are the commands that relate to saving and writing files. - -@table @kbd -@item C-x C-s -Save the current buffer to its file (@code{save-buffer}). -@item C-x s -Save any or all buffers to their files (@code{save-some-buffers}). -@item M-~ -Forget that the current buffer has been changed (@code{not-modified}). -With prefix argument (@kbd{C-u}), mark the current buffer as changed. -@item C-x C-w -Save the current buffer with a specified file name (@code{write-file}). -@item M-x set-visited-file-name -Change the file name under which the current buffer will be saved. -@end table - -@kindex C-x C-s -@findex save-buffer - When you wish to save the file and make your changes permanent, type -@kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s} -displays a message like this: - -@example -Wrote /u/rms/gnu/gnu.tasks -@end example - -@noindent -If the current buffer is not modified (no changes have been made in it -since the buffer was created or last saved), saving is not really -done, because it would have no effect. Instead, @kbd{C-x C-s} -displays a message like this in the echo area: - -@example -(No changes need to be saved) -@end example - -With a prefix argument, @kbd{C-u C-x C-s}, Emacs also marks the buffer -to be backed up when the next save is done. @xref{Backup}. - -@kindex C-x s -@findex save-some-buffers - The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any -or all modified buffers. It asks you what to do with each buffer. The -possible responses are analogous to those of @code{query-replace}: - -@table @kbd -@item y -Save this buffer and ask about the rest of the buffers. -@item n -Don't save this buffer, but ask about the rest of the buffers. -@item ! -Save this buffer and all the rest with no more questions. -@c following generates acceptable underfull hbox -@item @key{RET} -Terminate @code{save-some-buffers} without any more saving. -@item . -Save this buffer, then exit @code{save-some-buffers} without even asking -about other buffers. -@item C-r -View the buffer that you are currently being asked about. When you exit -View mode, you get back to @code{save-some-buffers}, which asks the -question again. -@item d -Diff the buffer against its corresponding file, so you can see what -changes you would be saving. This calls the command -@code{diff-buffer-with-file} (@pxref{Comparing Files}). -@item C-h -Display a help message about these options. -@end table - - @kbd{C-x C-c}, the key sequence to exit Emacs, invokes -@code{save-some-buffers} and therefore asks the same questions. - -@kindex M-~ -@findex not-modified - If you have changed a buffer but do not wish to save the changes, -you should take some action to prevent it. Otherwise, each time you -use @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer -by mistake. One thing you can do is type @kbd{M-~} -(@code{not-modified}), which clears out the indication that the buffer -is modified. If you do this, none of the save commands will believe -that the buffer needs to be saved. (@samp{~} is often used as a -mathematical symbol for `not'; thus @kbd{M-~} is `not', metafied.) -Alternatively, you can cancel all the changes made since the file was -visited or saved, by reading the text from the file again. This is -called @dfn{reverting}. @xref{Reverting}. (You could also undo all -the changes by repeating the undo command @kbd{C-x u} until you have -undone all the changes; but reverting is easier.) - -@findex set-visited-file-name - @kbd{M-x set-visited-file-name} alters the name of the file that the -current buffer is visiting. It reads the new file name using the -minibuffer. Then it marks the buffer as visiting that file name, and -changes the buffer name correspondingly. @code{set-visited-file-name} -does not save the buffer in the newly visited file; it just alters the -records inside Emacs in case you do save later. It also marks the -buffer as ``modified'' so that @kbd{C-x C-s} in that buffer -@emph{will} save. - -@kindex C-x C-w -@findex write-file - If you wish to mark the buffer as visiting a different file and save -it right away, use @kbd{C-x C-w} (@code{write-file}). This is -equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}, -except that @kbd{C-x C-w} asks for confirmation if the file exists. -@kbd{C-x C-s} used on a buffer that is not visiting a file has the -same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the -buffer as visiting that file, and saves it there. The default file -name in a buffer that is not visiting a file is made by combining the -buffer name with the buffer's default directory (@pxref{File Names}). - - If the new file name implies a major mode, then @kbd{C-x C-w} switches -to that major mode, in most cases. The command -@code{set-visited-file-name} also does this. @xref{Choosing Modes}. - - If Emacs is about to save a file and sees that the date of the latest -version on disk does not match what Emacs last read or wrote, Emacs -notifies you of this fact, because it probably indicates a problem caused -by simultaneous editing and requires your immediate attention. -@xref{Interlocking,, Simultaneous Editing}. - -@node Backup -@subsection Backup Files -@cindex backup file -@vindex make-backup-files -@vindex vc-make-backup-files - - On most operating systems, rewriting a file automatically destroys all -record of what the file used to contain. Thus, saving a file from Emacs -throws away the old contents of the file---or it would, except that -Emacs carefully copies the old contents to another file, called the -@dfn{backup} file, before actually saving. - - Emacs makes a backup for a file only the first time the file is -saved from a buffer. No matter how many times you subsequently save -the file, its backup remains unchanged. However, if you kill the -buffer and then visit the file again, a new backup file will be made. - - For most files, the variable @code{make-backup-files} determines -whether to make backup files. On most operating systems, its default -value is @code{t}, so that Emacs does write backup files. - - For files managed by a version control system (@pxref{Version -Control}), the variable @code{vc-make-backup-files} determines whether -to make backup files. By default it is @code{nil}, since backup files -are redundant when you store all the previous versions in a version -control system. -@iftex -@xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{General VC Options}. -@end ifnottex - - At your option, Emacs can keep either a single backup for each file, -or make a series of numbered backup files for each file that you edit. -@xref{Backup Names}. - -@vindex backup-enable-predicate -@vindex temporary-file-directory -@vindex small-temporary-file-directory - The default value of the @code{backup-enable-predicate} variable -prevents backup files being written for files in the directories used -for temporary files, specified by @code{temporary-file-directory} or -@code{small-temporary-file-directory}. - - You can explicitly tell Emacs to make another backup file from a -buffer, even though that buffer has been saved before. If you save -the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made -into a backup file if you save the buffer again. @kbd{C-u C-u C-x -C-s} saves the buffer, but first makes the previous file contents into -a new backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it -makes a backup from the previous contents, and arranges to make -another from the newly saved contents if you save again. - -@menu -* Names: Backup Names. How backup files are named. -* Deletion: Backup Deletion. Emacs deletes excess numbered backups. -* Copying: Backup Copying. Backups can be made by copying or renaming. -@end menu - -@node Backup Names -@subsubsection Single or Numbered Backups - - When Emacs makes a backup file, its name is normally constructed by -appending @samp{~} to the file name being edited; thus, the backup -file for @file{eval.c} would be @file{eval.c~}. - - If access control stops Emacs from writing backup files under the -usual names, it writes the backup file as @file{~/.emacs.d/%backup%~}. -Only one such file can exist, so only the most recently made such -backup is available. - - Emacs can also make @dfn{numbered backup files}. Numbered backup -file names contain @samp{.~}, the number, and another @samp{~} after -the original file name. Thus, the backup files of @file{eval.c} would -be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way -through names like @file{eval.c.~259~} and beyond. - -@vindex version-control - The variable @code{version-control} determines whether to make -single backup files or multiple numbered backup files. Its possible -values are: - -@table @code -@item nil -Make numbered backups for files that have numbered backups already. -Otherwise, make single backups. This is the default. -@item t -Make numbered backups. -@item never -Never make numbered backups; always make single backups. -@end table - -@noindent -The usual way to set this variable is globally, through your init file -or the customization buffer. However, you can set -@code{version-control} locally in an individual buffer to control the -making of backups for that buffer's file (@pxref{Locals}). You can -have Emacs set @code{version-control} locally whenever you visit a -given file (@pxref{File Variables}). Some modes, such as Rmail mode, -set this variable. - -@cindex @env{VERSION_CONTROL} environment variable - If you set the environment variable @env{VERSION_CONTROL}, to tell -various GNU utilities what to do with backup files, Emacs also obeys the -environment variable by setting the Lisp variable @code{version-control} -accordingly at startup. If the environment variable's value is @samp{t} -or @samp{numbered}, then @code{version-control} becomes @code{t}; if the -value is @samp{nil} or @samp{existing}, then @code{version-control} -becomes @code{nil}; if it is @samp{never} or @samp{simple}, then -@code{version-control} becomes @code{never}. - -@vindex backup-directory-alist - You can customize the variable @code{backup-directory-alist} to -specify that files matching certain patterns should be backed up in -specific directories. This variable applies to both single and -numbered backups. A typical use is to add an element @code{("." -. @var{dir})} to make all backups in the directory with absolute name -@var{dir}; Emacs modifies the backup file names to avoid clashes -between files with the same names originating in different -directories. Alternatively, adding, @code{("." . ".~")} would make -backups in the invisible subdirectory @file{.~} of the original file's -directory. Emacs creates the directory, if necessary, to make the -backup. - -@vindex make-backup-file-name-function - If you define the variable @code{make-backup-file-name-function} to -a suitable Lisp function, that overrides the usual way Emacs -constructs backup file names. - -@node Backup Deletion -@subsubsection Automatic Deletion of Backups - - To prevent excessive consumption of disk space, Emacs can delete numbered -backup versions automatically. Generally Emacs keeps the first few backups -and the latest few backups, deleting any in between. This happens every -time a new backup is made. - -@vindex kept-old-versions -@vindex kept-new-versions - The two variables @code{kept-old-versions} and -@code{kept-new-versions} control this deletion. Their values are, -respectively, the number of oldest (lowest-numbered) backups to keep -and the number of newest (highest-numbered) ones to keep, each time a -new backup is made. The backups in the middle (excluding those oldest -and newest) are the excess middle versions---those backups are -deleted. These variables' values are used when it is time to delete -excess versions, just after a new backup version is made; the newly -made backup is included in the count in @code{kept-new-versions}. By -default, both variables are 2. - -@vindex delete-old-versions - If @code{delete-old-versions} is @code{t}, Emacs deletes the excess -backup files silently. If it is @code{nil}, the default, Emacs asks -you whether it should delete the excess backup versions. If it has -any other value, then Emacs never automatically deletes backups. - - Dired's @kbd{.} (Period) command can also be used to delete old versions. -@xref{Dired Deletion}. - -@node Backup Copying -@subsubsection Copying vs.@: Renaming - - Backup files can be made by copying the old file or by renaming it. -This makes a difference when the old file has multiple names (hard -links). If the old file is renamed into the backup file, then the -alternate names become names for the backup file. If the old file is -copied instead, then the alternate names remain names for the file -that you are editing, and the contents accessed by those names will be -the new contents. - - The method of making a backup file may also affect the file's owner -and group. If copying is used, these do not change. If renaming is used, -you become the file's owner, and the file's group becomes the default -(different operating systems have different defaults for the group). - -@vindex backup-by-copying -@vindex backup-by-copying-when-linked -@vindex backup-by-copying-when-mismatch -@vindex backup-by-copying-when-privileged-mismatch -@cindex file ownership, and backup -@cindex backup, and user-id - The choice of renaming or copying is made as follows: - -@itemize -@item -If the variable @code{backup-by-copying} is non-@code{nil} (the -default is @code{nil}), use copying. - -@item -Otherwise, if the variable @code{backup-by-copying-when-linked} is -non-@code{nil} (the default is @code{nil}), and the file has multiple -names, use copying. - -@item -Otherwise, if the variable @code{backup-by-copying-when-mismatch} is -non-@code{nil} (the default is @code{t}), and renaming would change -the file's owner or group, use copying. - -If you change @code{backup-by-copying-when-mismatch} to @code{nil}, -Emacs checks the numeric user-id of the file's owner. If this is -higher than @code{backup-by-copying-when-privileged-mismatch}, then it -behaves as though @code{backup-by-copying-when-mismatch} is -non-@code{nil} anyway. - -@item -Otherwise, renaming is the default choice. -@end itemize - - When a file is managed with a version control system (@pxref{Version -Control}), Emacs does not normally make backups in the usual way for -that file. But check-in and check-out are similar in some ways to -making backups. One unfortunate similarity is that these operations -typically break hard links, disconnecting the file name you visited from -any alternate names for the same file. This has nothing to do with -Emacs---the version control system does it. - -@node Customize Save -@subsection Customizing Saving of Files - -@vindex require-final-newline - If the value of the variable @code{require-final-newline} is -@code{t}, saving or writing a file silently puts a newline at the end -if there isn't already one there. If the value is @code{visit}, Emacs -adds a newline at the end of any file that doesn't have one, just -after it visits the file. (This marks the buffer as modified, and you -can undo it.) If the value is @code{visit-save}, Emacs adds such -newlines both on visiting and on saving. If the value is @code{nil}, -Emacs leaves the end of the file unchanged; any other non-@code{nil} -value means to asks you whether to add a newline. The default is -@code{nil}. - -@vindex mode-require-final-newline - Some major modes are designed for specific kinds of files that are -always supposed to end in newlines. Such major modes set the variable -@code{require-final-newline} to the value of -@code{mode-require-final-newline}, which defaults to @code{t}. By -setting the latter variable, you can control how these modes handle -final newlines. - -@vindex write-region-inhibit-fsync - When Emacs saves a file, it invokes the @code{fsync} system call to -force the data immediately out to disk. This is important for safety -if the system crashes or in case of power outage. However, it can be -disruptive on laptops using power saving, as it may force a disk -spin-up each time you save a file. If you accept an increased risk of -data loss, you can set @code{write-region-inhibit-fsync} to a -non-@code{nil} value to disable the synchronization. - -@node Interlocking -@subsection Protection against Simultaneous Editing - -@cindex file dates -@cindex simultaneous editing - Simultaneous editing occurs when two users visit the same file, both -make changes, and then both save them. If nobody is informed that -this is happening, whichever user saves first would later find that -his changes were lost. - - On some systems, Emacs notices immediately when the second user starts -to change the file, and issues an immediate warning. On all systems, -Emacs checks when you save the file, and warns if you are about to -overwrite another user's changes. You can prevent loss of the other -user's work by taking the proper corrective action instead of saving the -file. - -@findex ask-user-about-lock -@cindex locking files - When you make the first modification in an Emacs buffer that is -visiting a file, Emacs records that the file is @dfn{locked} by you. -(It does this by creating a specially-named symbolic link in the same -directory.) Emacs removes the lock when you save the changes. The -idea is that the file is locked whenever an Emacs buffer visiting it -has unsaved changes. - -@cindex collision - If you begin to modify the buffer while the visited file is locked by -someone else, this constitutes a @dfn{collision}. When Emacs detects a -collision, it asks you what to do, by calling the Lisp function -@code{ask-user-about-lock}. You can redefine this function for the sake -of customization. The standard definition of this function asks you a -question and accepts three possible answers: - -@table @kbd -@item s -Steal the lock. Whoever was already changing the file loses the lock, -and you gain the lock. -@item p -Proceed. Go ahead and edit the file despite its being locked by someone else. -@item q -Quit. This causes an error (@code{file-locked}), and the buffer -contents remain unchanged---the modification you were trying to make -does not actually take place. -@end table - - If Emacs or the operating system crashes, this may leave behind lock -files which are stale, so you may occasionally get warnings about -spurious collisions. When you determine that the collision is -spurious, just use @kbd{p} to tell Emacs to go ahead anyway. - - Note that locking works on the basis of a file name; if a file has -multiple names, Emacs does not prevent two users from editing it -simultaneously under different names. - - A lock file cannot be written in some circumstances, e.g. if Emacs -lacks the system permissions or the system does not support symbolic -links. In these cases, Emacs can still detect the collision when you -try to save a file, by checking the file's last-modification date. If -the file has changed since the last time Emacs visited or saved it, -that implies that changes have been made in some other way, and will -be lost if Emacs proceeds with saving. Emacs then displays a warning -message and asks for confirmation before saving; answer @kbd{yes} to -save, and @kbd{no} or @kbd{C-g} cancel the save. - - If you are notified that simultaneous editing has already taken -place, one way to compare the buffer to its file is the @kbd{M-x -diff-buffer-with-file} command. @xref{Comparing Files}. - -@node File Shadowing -@subsection Shadowing Files -@cindex shadow files -@cindex file shadows -@findex shadow-initialize - -@table @kbd -@item M-x shadow-initialize -Set up file shadowing. -@item M-x shadow-define-literal-group -Declare a single file to be shared between sites. -@item M-x shadow-define-regexp-group -Make all files that match each of a group of files be shared between hosts. -@item M-x shadow-define-cluster @key{RET} @var{name} @key{RET} -Define a shadow file cluster @var{name}. -@item M-x shadow-copy-files -Copy all pending shadow files. -@item M-x shadow-cancel -Cancel the instruction to shadow some files. -@end table - -You can arrange to keep identical @dfn{shadow} copies of certain files -in more than one place---possibly on different machines. To do this, -first you must set up a @dfn{shadow file group}, which is a set of -identically-named files shared between a list of sites. The file -group is permanent and applies to further Emacs sessions as well as -the current one. Once the group is set up, every time you exit Emacs, -it will copy the file you edited to the other files in its group. You -can also do the copying without exiting Emacs, by typing @kbd{M-x -shadow-copy-files}. - -To set up a shadow file group, use @kbd{M-x -shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}. -See their documentation strings for further information. - -Before copying a file to its shadows, Emacs asks for confirmation. -You can answer ``no'' to bypass copying of this file, this time. If -you want to cancel the shadowing permanently for a certain file, use -@kbd{M-x shadow-cancel} to eliminate or change the shadow file group. - -A @dfn{shadow cluster} is a group of hosts that share directories, so -that copying to or from one of them is sufficient to update the file -on all of them. Each shadow cluster has a name, and specifies the -network address of a primary host (the one we copy files to), and a -regular expression that matches the host names of all the other hosts -in the cluster. You can define a shadow cluster with @kbd{M-x -shadow-define-cluster}. - -@node Time Stamps -@subsection Updating Time Stamps Automatically -@cindex time stamps -@cindex modification dates -@cindex locale, date format - -You can arrange to put a time stamp in a file, so that it is updated -automatically each time you edit and save the file. The time stamp -must be in the first eight lines of the file, and you should insert it -like this: - -@example -Time-stamp: <> -@end example - -@noindent -or like this: - -@example -Time-stamp: " " -@end example - -@findex time-stamp - Then add the function @code{time-stamp} to the hook -@code{before-save-hook} (@pxref{Hooks}). When you save the file, this -function then automatically updates the time stamp with the current -date and time. You can also use the command @kbd{M-x time-stamp} to -update the time stamp manually. For other customizations, see the -Custom group @code{time-stamp}. Note that the time stamp is formatted -according to your locale setting (@pxref{Environment}). - -@node Reverting -@section Reverting a Buffer -@findex revert-buffer -@cindex drastic changes -@cindex reread a file - - If you have made extensive changes to a file-visiting buffer and -then change your mind, you can @dfn{revert} the changes and go back to -the saved version of the file. To do this, type @kbd{M-x -revert-buffer}. Since reverting unintentionally could lose a lot of -work, Emacs asks for confirmation first. - - The @code{revert-buffer} command tries to position point in such a -way that, if the file was edited only slightly, you will be at -approximately the same part of the text as before. But if you have -made major changes, point may end up in a totally different location. - - Reverting marks the buffer as ``not modified''. It also clears the -buffer's undo history (@pxref{Undo}). Thus, the reversion cannot be -undone---if you change your mind yet again, you can't use the undo -commands to bring the reverted changes back. - - Some kinds of buffers that are not associated with files, such as -Dired buffers, can also be reverted. For them, reverting means -recalculating their contents. Buffers created explicitly with -@kbd{C-x b} cannot be reverted; @code{revert-buffer} reports an error -if you try. - -@vindex revert-without-query - When you edit a file that changes automatically and frequently---for -example, a log of output from a process that continues to run---it may -be useful for Emacs to revert the file without querying you. To -request this behavior, set the variable @code{revert-without-query} to -a list of regular expressions. When a file name matches one of these -regular expressions, @code{find-file} and @code{revert-buffer} will -revert it automatically if it has changed---provided the buffer itself -is not modified. (If you have edited the text, it would be wrong to -discard your changes.) - -@cindex Global Auto-Revert mode -@cindex mode, Global Auto-Revert -@cindex Auto-Revert mode -@cindex mode, Auto-Revert -@findex global-auto-revert-mode -@findex auto-revert-mode -@findex auto-revert-tail-mode -@vindex auto-revert-interval - You can also tell Emacs to revert buffers periodically. To do this -for a specific buffer, enable the minor mode Auto-Revert mode by -typing @kbd{M-x auto-revert-mode}. This automatically reverts the -current buffer every five seconds; you can change the interval through -the variable @code{auto-revert-interval}. To do the same for all file -buffers, type @kbd{M-x global-auto-revert-mode} to enable Global -Auto-Revert mode. These minor modes do not check or revert remote -files, because that is usually too slow. - - One use of Auto-Revert mode is to ``tail'' a file such as a system -log, so that changes made to that file by other programs are -continuously displayed. To do this, just move the point to the end of -the buffer, and it will stay there as the file contents change. -However, if you are sure that the file will only change by growing at -the end, use Auto-Revert Tail mode instead -(@code{auto-revert-tail-mode}). It is more efficient for this. -Auto-Revert Tail mode works also for remote files. - - @xref{VC Undo}, for commands to revert to earlier versions of files -under version control. @xref{VC Mode Line}, for Auto Revert -peculiarities when visiting files under version control. - -@ifnottex -@include arevert-xtra.texi -@end ifnottex - -@node Auto Save -@section Auto-Saving: Protection Against Disasters -@cindex Auto Save mode -@cindex mode, Auto Save -@cindex crashes - - From time to time, Emacs automatically saves each visited file in a -separate file, without altering the file you actually use. This is -called @dfn{auto-saving}. It prevents you from losing more than a -limited amount of work if the system crashes. - - When Emacs determines that it is time for auto-saving, it considers -each buffer, and each is auto-saved if auto-saving is enabled for it -and it has been changed since the last time it was auto-saved. The -message @samp{Auto-saving...} is displayed in the echo area during -auto-saving, if any files are actually auto-saved. Errors occurring -during auto-saving are caught so that they do not interfere with the -execution of commands you have been typing. - -@menu -* Files: Auto Save Files. The file where auto-saved changes are - actually made until you save the file. -* Control: Auto Save Control. Controlling when and how often to auto-save. -* Recover:: Recovering text from auto-save files. -@end menu - -@node Auto Save Files -@subsection Auto-Save Files - - Auto-saving does not normally save in the files that you visited, -because it can be very undesirable to save a change that you did not -want to make permanent. Instead, auto-saving is done in a different -file called the @dfn{auto-save file}, and the visited file is changed -only when you request saving explicitly (such as with @kbd{C-x C-s}). - - Normally, the auto-save file name is made by appending @samp{#} to the -front and rear of the visited file name. Thus, a buffer visiting file -@file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that -are not visiting files are auto-saved only if you request it explicitly; -when they are auto-saved, the auto-save file name is made by appending -@samp{#} to the front and rear of buffer name, then -adding digits and letters at the end for uniqueness. For -example, the @file{*mail*} buffer in which you compose messages to be -sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file -names are made this way unless you reprogram parts of Emacs to do -something different (the functions @code{make-auto-save-file-name} and -@code{auto-save-file-name-p}). The file name to be used for auto-saving -in a buffer is calculated when auto-saving is turned on in that buffer. - -@cindex auto-save for remote files -@vindex auto-save-file-name-transforms - The variable @code{auto-save-file-name-transforms} allows a degree -of control over the auto-save file name. It lets you specify a series -of regular expressions and replacements to transform the auto save -file name. The default value puts the auto-save files for remote -files (@pxref{Remote Files}) into the temporary file directory on the -local machine. - - When you delete a substantial part of the text in a large buffer, auto -save turns off temporarily in that buffer. This is because if you -deleted the text unintentionally, you might find the auto-save file more -useful if it contains the deleted text. To reenable auto-saving after -this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x -auto-save-mode}. - -@vindex auto-save-visited-file-name - If you want auto-saving to be done in the visited file rather than -in a separate auto-save file, set the variable -@code{auto-save-visited-file-name} to a non-@code{nil} value. In this -mode, there is no real difference between auto-saving and explicit -saving. - -@vindex delete-auto-save-files - A buffer's auto-save file is deleted when you save the buffer in its -visited file. (You can inhibit this by setting the variable -@code{delete-auto-save-files} to @code{nil}.) Changing the visited -file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames -any auto-save file to go with the new visited name. - -@node Auto Save Control -@subsection Controlling Auto-Saving - -@vindex auto-save-default -@findex auto-save-mode - Each time you visit a file, auto-saving is turned on for that file's -buffer if the variable @code{auto-save-default} is non-@code{nil} (but -not in batch mode; @pxref{Initial Options}). The default for this -variable is @code{t}, so auto-saving is the usual practice for -file-visiting buffers. To toggle auto-saving in the current buffer, -type @kbd{M-x auto-save-mode}. Auto Save mode acts as a buffer-local -minor mode (@pxref{Minor Modes}). - -@vindex auto-save-interval - Emacs auto-saves periodically based on how many characters you have -typed since the last auto-save. The variable -@code{auto-save-interval} specifies how many characters there are -between auto-saves. By default, it is 300. Emacs doesn't accept -values that are too small: if you customize @code{auto-save-interval} -to a value less than 20, Emacs will behave as if the value is 20. - -@vindex auto-save-timeout - Auto-saving also takes place when you stop typing for a while. By -default, it does this after 30 seconds of idleness (at this time, -Emacs may also perform garbage collection; @pxref{Garbage -Collection,,, elisp, The Emacs Lisp Reference Manual}). To change -this interval, customize the variable @code{auto-save-timeout}. The -actual time period is longer if the current buffer is long; this is a -heuristic which aims to keep out of your way when you are editing long -buffers, in which auto-save takes an appreciable amount of time. -Auto-saving during idle periods accomplishes two things: first, it -makes sure all your work is saved if you go away from the terminal for -a while; second, it may avoid some auto-saving while you are actually -typing. - - Emacs also does auto-saving whenever it gets a fatal error. This -includes killing the Emacs job with a shell command such as @samp{kill -%emacs}, or disconnecting a phone line or network connection. - -@findex do-auto-save - You can perform an auto-save explicitly with the command @kbd{M-x -do-auto-save}. - -@node Recover -@subsection Recovering Data from Auto-Saves - -@findex recover-file - You can use the contents of an auto-save file to recover from a loss -of data with the command @kbd{M-x recover-file @key{RET} @var{file} -@key{RET}}. This visits @var{file} and then (after your confirmation) -restores the contents from its auto-save file @file{#@var{file}#}. -You can then save with @kbd{C-x C-s} to put the recovered text into -@var{file} itself. For example, to recover file @file{foo.c} from its -auto-save file @file{#foo.c#}, do:@refill - -@example -M-x recover-file @key{RET} foo.c @key{RET} -yes @key{RET} -C-x C-s -@end example - - Before asking for confirmation, @kbd{M-x recover-file} displays a -directory listing describing the specified file and the auto-save file, -so you can compare their sizes and dates. If the auto-save file -is older, @kbd{M-x recover-file} does not offer to read it. - -@findex recover-session - If Emacs or the computer crashes, you can recover all the files you -were editing from their auto save files with the command @kbd{M-x -recover-session}. This first shows you a list of recorded interrupted -sessions. Move point to the one you choose, and type @kbd{C-c C-c}. - - Then @code{recover-session} asks about each of the files that were -being edited during that session, asking whether to recover that file. -If you answer @kbd{y}, it calls @code{recover-file}, which works in its -normal fashion. It shows the dates of the original file and its -auto-save file, and asks once again whether to recover that file. - - When @code{recover-session} is done, the files you've chosen to -recover are present in Emacs buffers. You should then save them. Only -this---saving them---updates the files themselves. - -@vindex auto-save-list-file-prefix - Emacs records information about interrupted sessions for later -recovery in files named @file{.saves-@var{pid}-@var{hostname}} in the -directory @file{~/.emacs.d/auto-save-list/}. This directory is -determined by the variable @code{auto-save-list-file-prefix}. If you -set @code{auto-save-list-file-prefix} to @code{nil}, sessions are not -recorded for recovery. - -@node File Aliases -@section File Name Aliases -@cindex symbolic links (visiting) -@cindex hard links (visiting) - - Symbolic links and hard links both make it possible for several file -names to refer to the same file. Hard links are alternate names that -refer directly to the file; all the names are equally valid, and no one -of them is preferred. By contrast, a symbolic link is a kind of defined -alias: when @file{foo} is a symbolic link to @file{bar}, you can use -either name to refer to the file, but @file{bar} is the real name, while -@file{foo} is just an alias. More complex cases occur when symbolic -links point to directories. - -@vindex find-file-existing-other-name -@vindex find-file-suppress-same-file-warnings - Normally, if you visit a file which Emacs is already visiting under -a different name, Emacs displays a message in the echo area and uses -the existing buffer visiting that file. This can happen on systems -that support hard or symbolic links, or if you use a long file name on -a system that truncates long file names, or on a case-insensitive file -system. You can suppress the message by setting the variable -@code{find-file-suppress-same-file-warnings} to a non-@code{nil} -value. You can disable this feature entirely by setting the variable -@code{find-file-existing-other-name} to @code{nil}: then if you visit -the same file under two different names, you get a separate buffer for -each file name. - -@vindex find-file-visit-truename -@cindex truenames of files -@cindex file truenames - If the variable @code{find-file-visit-truename} is non-@code{nil}, -then the file name recorded for a buffer is the file's @dfn{truename} -(made by replacing all symbolic links with their target names), rather -than the name you specify. Setting @code{find-file-visit-truename} also -implies the effect of @code{find-file-existing-other-name}. - -@cindex directory name abbreviation -@vindex directory-abbrev-alist - Sometimes, a directory is ordinarily accessed through a symbolic -link, and you may want Emacs to preferentially show its ``linked'' -name. To do this, customize @code{directory-abbrev-alist}. Each -element in this list should have the form @code{(@var{from} -. @var{to})}, which means to replace @var{from} with @var{to} whenever -@var{from} appears in a directory name. The @var{from} string is a -regular expression (@pxref{Regexps}). It is matched against directory -names anchored at the first character, and should start with @samp{\`} -(to support directory names with embedded newlines, which would defeat -@samp{^}). The @var{to} string should be an ordinary absolute -directory name pointing to the same directory. Do not use @samp{~} to -stand for a home directory in the @var{to} string; Emacs performs -these substitutions separately. Here's an example, from a system on -which @file{/home/fsf} is normally accessed through a symbolic link -named @file{/fsf}: - -@example -(("\\`/home/fsf" . "/fsf")) -@end example - -@node Directories -@section File Directories - -@cindex file directory -@cindex directory listing - The file system groups files into @dfn{directories}. A @dfn{directory -listing} is a list of all the files in a directory. Emacs provides -commands to create and delete directories, and to make directory -listings in brief format (file names only) and verbose format (sizes, -dates, and authors included). Emacs also includes a directory browser -feature called Dired; see @ref{Dired}. - -@table @kbd -@item C-x C-d @var{dir-or-pattern} @key{RET} -Display a brief directory listing (@code{list-directory}). -@item C-u C-x C-d @var{dir-or-pattern} @key{RET} -Display a verbose directory listing. -@item M-x make-directory @key{RET} @var{dirname} @key{RET} -Create a new directory named @var{dirname}. -@item M-x delete-directory @key{RET} @var{dirname} @key{RET} -Delete the directory named @var{dirname}. If it isn't empty, -you will be asked whether you want to delete it recursively. -@end table - -@findex list-directory -@kindex C-x C-d - The command to display a directory listing is @kbd{C-x C-d} -(@code{list-directory}). It reads using the minibuffer a file name -which is either a directory to be listed or a wildcard-containing -pattern for the files to be listed. For example, - -@example -C-x C-d /u2/emacs/etc @key{RET} -@end example - -@noindent -lists all the files in directory @file{/u2/emacs/etc}. Here is an -example of specifying a file name pattern: - -@example -C-x C-d /u2/emacs/src/*.c @key{RET} -@end example - - Normally, @kbd{C-x C-d} displays a brief directory listing containing -just file names. A numeric argument (regardless of value) tells it to -make a verbose listing including sizes, dates, and owners (like -@samp{ls -l}). - -@vindex list-directory-brief-switches -@vindex list-directory-verbose-switches - The text of a directory listing is mostly obtained by running -@code{ls} in an inferior process. Two Emacs variables control the -switches passed to @code{ls}: @code{list-directory-brief-switches} is -a string giving the switches to use in brief listings (@code{"-CF"} by -default), and @code{list-directory-verbose-switches} is a string -giving the switches to use in a verbose listing (@code{"-l"} by -default). - -@vindex directory-free-space-program -@vindex directory-free-space-args - In verbose directory listings, Emacs adds information about the -amount of free space on the disk that contains the directory. To do -this, it runs the program specified by -@code{directory-free-space-program} with arguments -@code{directory-free-space-args}. - - The command @kbd{M-x delete-directory} prompts for a directory name -using the minibuffer, and deletes the directory if it is empty. If -the directory is not empty, you will be asked whether you want to -delete it recursively. On systems that have a ``Trash'' (or ``Recycle -Bin'') feature, you can make this command move the specified directory -to the Trash instead of deleting it outright, by changing the variable -@code{delete-by-moving-to-trash} to @code{t}. @xref{Misc File Ops}, -for more information about using the Trash. - -@node Comparing Files -@section Comparing Files -@cindex comparing files - -@findex diff -@vindex diff-switches - The command @kbd{M-x diff} prompts for two file names, using the -minibuffer, and displays the differences between the two files in a -buffer named @file{*diff*}. This works by running the @command{diff} -program, using options taken from the variable @code{diff-switches}. -The value of @code{diff-switches} should be a string; the default is -@code{"-c"} to specify a context diff. @xref{Top,, Diff, diff, -Comparing and Merging Files}, for more information about the -@command{diff} program. - - The output of the @code{diff} command is shown using a major mode -called Diff mode. @xref{Diff Mode}. - -@findex diff-backup - The command @kbd{M-x diff-backup} compares a specified file with its -most recent backup. If you specify the name of a backup file, -@code{diff-backup} compares it with the source file that it is a -backup of. In all other respects, this behaves like @kbd{M-x diff}. - -@findex diff-buffer-with-file - The command @kbd{M-x diff-buffer-with-file} compares a specified -buffer with its corresponding file. This shows you what changes you -would make to the file if you save the buffer. - -@findex compare-windows - The command @kbd{M-x compare-windows} compares the text in the -current window with that in the next window. (For more information -about windows in Emacs, @ref{Windows}.) Comparison starts at point in -each window, after pushing each initial point value on the mark ring -in its respective buffer. Then it moves point forward in each window, -one character at a time, until it reaches characters that don't match. -Then the command exits. - - If point in the two windows is followed by non-matching text when -the command starts, @kbd{M-x compare-windows} tries heuristically to -advance up to matching text in the two windows, and then exits. So if -you use @kbd{M-x compare-windows} repeatedly, each time it either -skips one matching range or finds the start of another. - -@vindex compare-ignore-case -@vindex compare-ignore-whitespace - With a numeric argument, @code{compare-windows} ignores changes in -whitespace. If the variable @code{compare-ignore-case} is -non-@code{nil}, the comparison ignores differences in case as well. -If the variable @code{compare-ignore-whitespace} is non-@code{nil}, -@code{compare-windows} normally ignores changes in whitespace, and a -prefix argument turns that off. - -@cindex Smerge mode -@findex smerge-mode -@cindex failed merges -@cindex merges, failed -@cindex comparing 3 files (@code{diff3}) - You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor -mode for editing output from the @command{diff3} program. This is -typically the result of a failed merge from a version control system -``update'' outside VC, due to conflicting changes to a file. Smerge -mode provides commands to resolve conflicts by selecting specific -changes. - -@iftex -@xref{Emerge,,, emacs-xtra, Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{Emerge}, -@end ifnottex -for the Emerge facility, which provides a powerful interface for -merging files. - -@node Diff Mode -@section Diff Mode -@cindex Diff mode -@findex diff-mode -@cindex patches, editing - - Diff mode is a major mode used for the output of @kbd{M-x diff} and -other similar commands. This kind of output is called a @dfn{patch}, -because it can be passed to the @command{patch} command to -automatically apply the specified changes. To select Diff mode -manually, type @kbd{M-x diff-mode}. - -@cindex hunk, diff - The changes specified in a patch are grouped into @dfn{hunks}, which -are contiguous chunks of text that contain one or more changed lines. -Hunks can also include unchanged lines to provide context for the -changes. Each hunk is preceded by a @dfn{hunk header}, which -specifies the old and new line numbers at which the hunk occurs. Diff -mode highlights each hunk header, to distinguish it from the actual -contents of the hunk. - -@vindex diff-update-on-the-fly - You can edit a Diff mode buffer like any other buffer. (If it is -read-only, you need to make it writable first. @xref{Misc Buffer}.) -Whenever you change a hunk, Diff mode attempts to automatically -correct the line numbers in the hunk headers, to ensure that the diff -remains ``correct''. To disable automatic line number correction, -change the variable @code{diff-update-on-the-fly} to @code{nil}. - - Diff mode treats each hunk as an ``error message'', similar to -Compilation mode. Thus, you can use commands such as @kbd{C-x '} to -visit the corresponding source locations. @xref{Compilation Mode}. - - In addition, Diff mode provides the following commands to navigate, -manipulate and apply parts of patches: - -@table @kbd -@item M-n -@findex diff-hunk-next -Move to the next hunk-start (@code{diff-hunk-next}). - -@findex diff-auto-refine-mode -@cindex mode, Diff Auto-Refine -@cindex Diff Auto-Refine mode -This command has a side effect: it @dfn{refines} the hunk you move to, -highlighting its changes with better granularity. To disable this -feature, type @kbd{M-x diff-auto-refine-mode} to toggle off the minor -mode Diff Auto-Refine mode. To disable Diff Auto Refine mode by -default, add this to your init file (@pxref{Hooks}): - -@example -(add-hook 'diff-mode-hook - (lambda () (diff-auto-refine-mode -1))) -@end example - -@item M-p -@findex diff-hunk-prev -Move to the previous hunk-start (@code{diff-hunk-prev}). Like -@kbd{M-n}, this has the side-effect of refining the hunk you move to, -unless you disable Diff Auto-Refine mode. - -@item M-@} -@findex diff-file-next -Move to the next file-start, in a multi-file patch -(@code{diff-file-next}). - -@item M-@{ -@findex diff-file-prev -Move to the previous file-start, in a multi-file patch -(@code{diff-file-prev}). - -@item M-k -@findex diff-hunk-kill -Kill the hunk at point (@code{diff-hunk-kill}). - -@item M-K -@findex diff-file-kill -In a multi-file patch, kill the current file part. -(@code{diff-file-kill}). - -@item C-c C-a -@findex diff-apply-hunk -Apply this hunk to its target file (@code{diff-apply-hunk}). With a -prefix argument of @kbd{C-u}, revert this hunk. - -@item C-c C-b -@findex diff-refine-hunk -Highlight the changes of the hunk at point with a finer granularity -(@code{diff-refine-hunk}). This allows you to see exactly which parts -of each changed line were actually changed. - -@item C-c C-c -@findex diff-goto-source -Go to the source file and line corresponding to this hunk -(@code{diff-goto-source}). - -@item C-c C-e -@findex diff-ediff-patch -Start an Ediff session with the patch (@code{diff-ediff-patch}). -@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}. - -@item C-c C-n -@findex diff-restrict-view -Restrict the view to the current hunk (@code{diff-restrict-view}). -@xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the -view to the current file of a multiple-file patch. To widen again, -use @kbd{C-x n w} (@code{widen}). - -@item C-c C-r -@findex diff-reverse-direction -Reverse the direction of comparison for the entire buffer -(@code{diff-reverse-direction}). - -@item C-c C-s -@findex diff-split-hunk -Split the hunk at point (@code{diff-split-hunk}). This is for -manually editing patches, and only works with the @dfn{unified diff -format} produced by the @option{-u} or @option{--unified} options to -the @command{diff} program. If you need to split a hunk in the -@dfn{context diff format} produced by the @option{-c} or -@option{--context} options to @command{diff}, first convert the buffer -to the unified diff format with @kbd{C-c C-u}. - -@item C-c C-d -@findex diff-unified->context -Convert the entire buffer to the @dfn{context diff format} -(@code{diff-unified->context}). With a prefix argument, convert only -the text within the region. - -@item C-c C-u -@findex diff-context->unified -Convert the entire buffer to unified diff format -(@code{diff-context->unified}). With a prefix argument, convert -unified format to context format. When the mark is active, convert -only the text within the region. - -@item C-c C-w -@findex diff-refine-hunk -Refine the current hunk so that it disregards changes in whitespace -(@code{diff-refine-hunk}). - -@item C-x 4 A -@findex diff-add-change-log-entries-other-window -@findex add-change-log-entry-other-window@r{, in Diff mode} -Generate a ChangeLog entry, like @kbd{C-x 4 a} does (@pxref{Change -Log}), for each one of the hunks -(@code{diff-add-change-log-entries-other-window}). This creates a -skeleton of the log of changes that you can later fill with the actual -descriptions of the changes. @kbd{C-x 4 a} itself in Diff mode -operates on behalf of the current hunk's file, but gets the function -name from the patch itself. This is useful for making log entries for -functions that are deleted by the patch. -@end table - - By default, Diff mode highlights trailing whitespace on modified -lines, so that they are more obvious. This is done by enabling -Whitespace mode in the Diff buffer (@pxref{Useless Whitespace}). Diff -mode buffers are set up so that Whitespace mode avoids highlighting -trailing whitespace occurring in the diff context. - -@node Misc File Ops -@section Miscellaneous File Operations - - Emacs has commands for performing many other operations on files. -All operate on one file; they do not accept wildcard file names. - -@findex delete-file -@cindex deletion (of files) - @kbd{M-x delete-file} prompts for a file and deletes it. If you are -deleting many files in one directory, it may be more convenient to use -Dired rather than @code{delete-file}. @xref{Dired Deletion}. - -@cindex trash -@cindex recycle bin - @kbd{M-x move-file-to-trash} moves a file into the system -@dfn{Trash} (or @dfn{Recycle Bin}). This is a facility available on -most operating systems; files that are moved into the Trash can be -brought back later if you change your mind. - -@vindex delete-by-moving-to-trash - By default, Emacs deletion commands do @emph{not} use the Trash. To -use the Trash (when it is available) for common deletion commands, -change the variable @code{delete-by-moving-to-trash} to @code{t}. -This affects the commands @kbd{M-x delete-file} and @kbd{M-x -delete-directory} (@pxref{Directories}), as well as the deletion -commands in Dired (@pxref{Dired Deletion}). Supplying a prefix -argument to @kbd{M-x delete-file} or @kbd{M-x delete-directory} makes -them delete outright, instead of using the Trash, regardless of -@code{delete-by-moving-to-trash}. - -@ifnottex - If a file is under version control (@pxref{Version Control}), you -should delete it using @kbd{M-x vc-delete-file} instead of @kbd{M-x -delete-file}. @xref{VC Delete/Rename}. -@end ifnottex - -@findex copy-file -@cindex copying files - @kbd{M-x copy-file} reads the file @var{old} and writes a new file -named @var{new} with the same contents. - -@findex copy-directory - @kbd{M-x copy-directory} copies directories, similar to the -@command{cp -r} shell command. It prompts for a directory @var{old} -and a destination @var{new}. If @var{new} is an existing directory, -it creates a copy of the @var{old} directory and puts it in @var{new}. -If @var{new} is not an existing directory, it copies all the contents -of @var{old} into a new directory named @var{new}. - -@cindex renaming files -@findex rename-file - @kbd{M-x rename-file} reads two file names @var{old} and @var{new} -using the minibuffer, then renames file @var{old} as @var{new}. If -the file name @var{new} already exists, you must confirm with -@kbd{yes} or renaming is not done; this is because renaming causes the -old meaning of the name @var{new} to be lost. If @var{old} and -@var{new} are on different file systems, the file @var{old} is copied -and deleted. If the argument @var{new} is just a directory name, the -real new name is in that directory, with the same non-directory -component as @var{old}. For example, @kbd{M-x rename-file RET ~/foo -RET /tmp RET} renames @file{~/foo} to @file{/tmp/foo}. The same rule -applies to all the remaining commands in this section. All of them -ask for confirmation when the new file name already exists, too. - -@ifnottex - If a file is under version control (@pxref{Version Control}), you -should rename it using @kbd{M-x vc-rename-file} instead of @kbd{M-x -rename-file}. @xref{VC Delete/Rename}. -@end ifnottex - -@findex add-name-to-file -@cindex hard links (creation) - @kbd{M-x add-name-to-file} adds an additional name to an existing -file without removing its old name. The new name is created as a -``hard link'' to the existing file. The new name must belong on the -same file system that the file is on. On MS-Windows, this command -works only if the file resides in an NTFS file system. On MS-DOS, it -works by copying the file. - -@findex make-symbolic-link -@cindex symbolic links (creation) - @kbd{M-x make-symbolic-link} reads two file names @var{target} and -@var{linkname}, then creates a symbolic link named @var{linkname}, -which points at @var{target}. The effect is that future attempts to -open file @var{linkname} will refer to whatever file is named -@var{target} at the time the opening is done, or will get an error if -the name @var{target} is nonexistent at that time. This command does -not expand the argument @var{target}, so that it allows you to specify -a relative name as the target of the link. Not all systems support -symbolic links; on systems that don't support them, this command is -not defined. - -@kindex C-x i -@findex insert-file - @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the -contents of the specified file into the current buffer at point, -leaving point unchanged before the contents. The position after the -inserted contents is added to the mark ring, without activating the -mark (@pxref{Mark Ring}). - -@findex insert-file-literally - @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file}, -except the file is inserted ``literally'': it is treated as a sequence -of @acronym{ASCII} characters with no special encoding or conversion, -similar to the @kbd{M-x find-file-literally} command -(@pxref{Visiting}). - -@findex write-region - @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it -copies the contents of the region into the specified file. @kbd{M-x -append-to-file} adds the text of the region to the end of the -specified file. @xref{Accumulating Text}. The variable -@code{write-region-inhibit-fsync} applies to these commands, as well -as saving files; see @ref{Customize Save}. - -@findex set-file-modes -@cindex file modes -@cindex file permissions - @kbd{M-x set-file-modes} reads a file name followed by a @dfn{file -mode}, and applies that file mode to the specified file. File modes, -also called @dfn{file permissions}, determine whether a file can be -read, written to, or executed, and by whom. This command reads file -modes using the same symbolic or octal format accepted by the -@command{chmod} command; for instance, @samp{u+x} means to add -execution permission for the user who owns the file. It has no effect -on operating systems that do not support file modes. @code{chmod} is a -convenience alias for this function. - -@node Compressed Files -@section Accessing Compressed Files -@cindex compression -@cindex uncompression -@cindex Auto Compression mode -@cindex mode, Auto Compression -@pindex gzip - - Emacs automatically uncompresses compressed files when you visit -them, and automatically recompresses them if you alter them and save -them. Emacs recognizes compressed files by their file names. File -names ending in @samp{.gz} indicate a file compressed with -@code{gzip}. Other endings indicate other compression programs. - - Automatic uncompression and compression apply to all the operations in -which Emacs uses the contents of a file. This includes visiting it, -saving it, inserting its contents into a buffer, loading it, and byte -compiling it. - -@findex auto-compression-mode -@vindex auto-compression-mode - To disable this feature, type the command @kbd{M-x -auto-compression-mode}. You can disable it permanently by -customizing the variable @code{auto-compression-mode}. - -@node File Archives -@section File Archives -@cindex mode, tar -@cindex Tar mode -@cindex file archives - - A file whose name ends in @samp{.tar} is normally an @dfn{archive} -made by the @code{tar} program. Emacs views these files in a special -mode called Tar mode which provides a Dired-like list of the contents -(@pxref{Dired}). You can move around through the list just as you -would in Dired, and visit the subfiles contained in the archive. -However, not all Dired commands are available in Tar mode. - - If Auto Compression mode is enabled (@pxref{Compressed Files}), then -Tar mode is used also for compressed archives---files with extensions -@samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. - - The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file -into its own buffer. You can edit it there, and if you save the -buffer, the edited version will replace the version in the Tar buffer. -Clicking with the mouse on the file name in the Tar buffer does -likewise. @kbd{v} extracts a file into a buffer in View mode -(@pxref{View Mode}). @kbd{o} extracts the file and displays it in -another window, so you could edit the file and operate on the archive -simultaneously. - - @kbd{d} marks a file for deletion when you later use @kbd{x}, and -@kbd{u} unmarks a file, as in Dired. @kbd{C} copies a file from the -archive to disk and @kbd{R} renames a file within the archive. -@kbd{g} reverts the buffer from the archive on disk. The keys -@kbd{M}, @kbd{G}, and @kbd{O} change the file's permission bits, -group, and owner, respectively. - - Saving the Tar buffer writes a new version of the archive to disk with -the changes you made to the components. - - You don't need the @code{tar} program to use Tar mode---Emacs reads -the archives directly. However, accessing compressed archives -requires the appropriate uncompression program. - -@cindex Archive mode -@cindex mode, archive -@cindex @code{arc} -@cindex @code{jar} -@cindex @code{rar} -@cindex @code{zip} -@cindex @code{lzh} -@cindex @code{zoo} -@cindex @code{7z} -@pindex arc -@pindex jar -@pindex zip -@pindex rar -@pindex lzh -@pindex zoo -@pindex 7z -@cindex Java class archives -@cindex unzip archives - A separate but similar Archive mode is used for @code{arc}, -@code{jar}, @code{lzh}, @code{zip}, @code{rar}, @code{7z}, and -@code{zoo} archives, as well as @code{exe} files that are -self-extracting executables. - - The key bindings of Archive mode are similar to those in Tar mode, -with the addition of the @kbd{m} key which marks a file for subsequent -operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. -Also, the @kbd{a} key toggles the display of detailed file -information, for those archive types where it won't fit in a single -line. Operations such as renaming a subfile, or changing its mode or -owner, are supported only for some of the archive formats. - - Unlike Tar mode, Archive mode runs the archiving programs to unpack -and repack archives. However, you don't need these programs to look -at the archive table of contents, only to extract or manipulate the -subfiles in the archive. Details of the program names and their -options can be set in the @samp{Archive} Customize group. - -@node Remote Files -@section Remote Files - -@cindex Tramp -@cindex FTP -@cindex remote file access - You can refer to files on other machines using a special file name -syntax: - -@example -@group -/@var{host}:@var{filename} -/@var{user}@@@var{host}:@var{filename} -/@var{user}@@@var{host}#@var{port}:@var{filename} -/@var{method}:@var{user}@@@var{host}:@var{filename} -/@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename} -@end group -@end example - -@noindent -To carry out this request, Emacs uses a remote-login program such as -@command{ftp}, @command{ssh}, @command{rlogin}, or @command{telnet}. -You can always specify in the file name which method to use---for -example, @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, -whereas @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses -@command{ssh}. When you don't specify a method in the file name, -Emacs chooses the method as follows: - -@enumerate -@item -If the host name starts with @samp{ftp.} (with dot), Emacs uses FTP. -@item -If the user name is @samp{ftp} or @samp{anonymous}, Emacs uses FTP. -@item -If the variable @code{tramp-default-method} is set to @samp{ftp}, -Emacs uses FTP. -@item -If @command{ssh-agent} is running, Emacs uses @command{scp}. -@item -Otherwise, Emacs uses @command{ssh}. -@end enumerate - -@cindex disabling remote files -@noindent -You can entirely turn off the remote file name feature by setting the -variable @code{tramp-mode} to @code{nil}. You can turn off the -feature in individual cases by quoting the file name with @samp{/:} -(@pxref{Quoted File Names}). - -@cindex ange-ftp - Remote file access through FTP is handled by the Ange-FTP package, which -is documented in the following. Remote file access through the other -methods is handled by the Tramp package, which has its own manual. -@xref{Top, The Tramp Manual,, tramp, The Tramp Manual}. - -@vindex ange-ftp-default-user -@cindex user name for remote file access - When the Ange-FTP package is used, Emacs logs in through FTP using -the name @var{user}, if that is specified in the remote file name. If -@var{user} is unspecified, Emacs logs in using your user name on the -local system; but if you set the variable @code{ange-ftp-default-user} -to a string, that string is used instead. When logging in, Emacs may -also ask for a password. - -@cindex backups for remote files -@vindex ange-ftp-make-backup-files - For performance reasons, Emacs does not make backup files for files -accessed via FTP by default. To make it do so, change the variable -@code{ange-ftp-make-backup-files} to a non-@code{nil} value. - - By default, auto-save files for remote files are made in the -temporary file directory on the local machine, as specified by the -variable @code{auto-save-file-name-transforms}. @xref{Auto Save -Files}. - -@cindex anonymous FTP -@vindex ange-ftp-generate-anonymous-password - To visit files accessible by anonymous FTP, you use special user -names @samp{anonymous} or @samp{ftp}. Passwords for these user names -are handled specially. The variable -@code{ange-ftp-generate-anonymous-password} controls what happens: if -the value of this variable is a string, then that string is used as -the password; if non-@code{nil} (the default), then the value of -@code{user-mail-address} is used; if @code{nil}, then Emacs prompts -you for a password as usual (@pxref{Passwords}). - -@cindex firewall, and accessing remote files -@cindex gateway, and remote file access with @code{ange-ftp} -@vindex ange-ftp-smart-gateway -@vindex ange-ftp-gateway-host - Sometimes you may be unable to access files on a remote machine -because a @dfn{firewall} in between blocks the connection for security -reasons. If you can log in on a @dfn{gateway} machine from which the -target files @emph{are} accessible, and whose FTP server supports -gatewaying features, you can still use remote file names; all you have -to do is specify the name of the gateway machine by setting the -variable @code{ange-ftp-gateway-host}, and set -@code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able -to make remote file names work, but the procedure is complex. You can -read the instructions by typing @kbd{M-x finder-commentary @key{RET} -ange-ftp @key{RET}}. - -@node Quoted File Names -@section Quoted File Names - -@cindex quoting file names -@cindex file names, quote special characters - You can @dfn{quote} an absolute file name to prevent special -characters and syntax in it from having their special effects. -The way to do this is to add @samp{/:} at the beginning. - - For example, you can quote a local file name which appears remote, to -prevent it from being treated as a remote file name. Thus, if you have -a directory named @file{/foo:} and a file named @file{bar} in it, you -can refer to that file in Emacs as @samp{/:/foo:/bar}. - - @samp{/:} can also prevent @samp{~} from being treated as a special -character for a user's home directory. For example, @file{/:/tmp/~hack} -refers to a file whose name is @file{~hack} in directory @file{/tmp}. - - Quoting with @samp{/:} is also a way to enter in the minibuffer a -file name that contains @samp{$}. In order for this to work, the -@samp{/:} must be at the beginning of the minibuffer contents. (You -can also double each @samp{$}; see @ref{File Names with $}.) - - You can also quote wildcard characters with @samp{/:}, for visiting. -For example, @file{/:/tmp/foo*bar} visits the file -@file{/tmp/foo*bar}. - - Another method of getting the same result is to enter -@file{/tmp/foo[*]bar}, which is a wildcard specification that matches -only @file{/tmp/foo*bar}. However, in many cases there is no need to -quote the wildcard characters because even unquoted they give the -right result. For example, if the only file name in @file{/tmp} that -starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, -then specifying @file{/tmp/foo*bar} will visit only -@file{/tmp/foo*bar}. - -@node File Name Cache -@section File Name Cache - -@cindex file name caching -@cindex cache of file names -@pindex find -@kindex C-TAB -@findex file-cache-minibuffer-complete - You can use the @dfn{file name cache} to make it easy to locate a -file by name, without having to remember exactly where it is located. -When typing a file name in the minibuffer, @kbd{C-@key{tab}} -(@code{file-cache-minibuffer-complete}) completes it using the file -name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the -possible completions of what you had originally typed. (However, note -that the @kbd{C-@key{tab}} character cannot be typed on most text -terminals.) - - The file name cache does not fill up automatically. Instead, you -load file names into the cache using these commands: - -@findex file-cache-add-directory -@table @kbd -@item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} to the file name cache. -@item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} and all of its nested -subdirectories to the file name cache. -@item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} and all of its nested -subdirectories to the file name cache, using @command{locate} to find -them all. -@item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} -Add each file name in each directory listed in @var{variable} to the -file name cache. @var{variable} should be a Lisp variable whose value -is a list of directory names, like @code{load-path}. -@item M-x file-cache-clear-cache @key{RET} -Clear the cache; that is, remove all file names from it. -@end table - - The file name cache is not persistent: it is kept and maintained -only for the duration of the Emacs session. You can view the contents -of the cache with the @code{file-cache-display} command. - -@node File Conveniences -@section Convenience Features for Finding Files - - In this section, we introduce some convenient facilities for finding -recently-opened files, reading file names from a buffer, and viewing -image files. - -@findex recentf-mode -@vindex recentf-mode -@findex recentf-save-list -@findex recentf-edit-list - If you enable Recentf mode, with @kbd{M-x recentf-mode}, the -@samp{File} menu includes a submenu containing a list of recently -opened files. @kbd{M-x recentf-save-list} saves the current -@code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list} -edits it. - - The @kbd{M-x ffap} command generalizes @code{find-file} with more -powerful heuristic defaults (@pxref{FFAP}), often based on the text at -point. Partial Completion mode offers other features extending -@code{find-file}, which can be used with @code{ffap}. -@xref{Completion Options}. - -@findex image-mode -@findex image-toggle-display -@findex image-toggle-animation -@cindex images, viewing -@cindex image animation -@cindex animated images - Visiting image files automatically selects Image mode. In this -major mode, you can type @kbd{C-c C-c} (@code{image-toggle-display}) -to toggle between displaying the file as an image in the Emacs buffer, -and displaying its underlying text (or raw byte) representation. -Displaying the file as an image works only if Emacs is compiled with -support for displaying such images. If the displayed image is wider -or taller than the frame, the usual point motion keys (@kbd{C-f}, -@kbd{C-p}, and so forth) cause different parts of the image to be -displayed. If the image can be animated, the command @kbd{RET} -(@code{image-toggle-animation}) starts or stops the animation. -Animation plays once, unless the option @code{image-animate-loop} is -non-@code{nil}. Currently, Emacs only supports animation in GIF -files. - -@cindex ImageMagick support - If your Emacs was compiled with ImageMagick support, it is possible -to view a much wider variety of image types in Image mode, by -rendering the images via ImageMagick. However, this feature is -currently disabled by default. To enable it, add the following line -to your init file: - -@example -(imagemagick-register-types) -@end example - -@findex thumbs-mode -@findex mode, thumbs - The Image-Dired package can also be used to view images as -thumbnails. @xref{Image-Dired}. - -@node Filesets -@section Filesets -@cindex filesets - -@findex filesets-init - If you regularly edit a certain group of files, you can define them -as a @dfn{fileset}. This lets you perform certain operations, such as -visiting, @code{query-replace}, and shell commands on all the files at -once. To make use of filesets, you must first add the expression -@code{(filesets-init)} to your init file (@pxref{Init File}). This -adds a @samp{Filesets} menu to the menu bar. - -@findex filesets-add-buffer -@findex filesets-remove-buffer - The simplest way to define a fileset is by adding files to it one at -a time. To add a file to fileset @var{name}, visit the file and type -@kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If -there is no fileset @var{name}, this creates a new one, which -initially contains only the current file. The command @kbd{M-x -filesets-remove-buffer} removes the current file from a fileset. - - You can also edit the list of filesets directly, with @kbd{M-x -filesets-edit} (or by choosing @samp{Edit Filesets} from the -@samp{Filesets} menu). The editing is performed in a Customize buffer -(@pxref{Easy Customization}). Normally, a fileset is a simple list of -files, but you can also define a fileset as a regular expression -matching file names. Some examples of these more complicated filesets -are shown in the Customize buffer. Remember to select @samp{Save for -future sessions} if you want to use the same filesets in future Emacs -sessions. - - You can use the command @kbd{M-x filesets-open} to visit all the -files in a fileset, and @kbd{M-x filesets-close} to close them. Use -@kbd{M-x filesets-run-cmd} to run a shell command on all the files in -a fileset. These commands are also available from the @samp{Filesets} -menu, where each existing fileset is represented by a submenu. - - @xref{Version Control}, for a different concept of ``filesets'': -groups of files bundled together for version control operations. -Filesets of that type are unnamed, and do not persist across Emacs -sessions. diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi deleted file mode 100644 index 2857e2b1af6..00000000000 --- a/doc/emacs/fixit.texi +++ /dev/null @@ -1,417 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Fixit, Keyboard Macros, Search, Top -@chapter Commands for Fixing Typos -@cindex typos, fixing -@cindex mistakes, correcting - - In this chapter we describe commands that are useful when you catch -a mistake while editing. The most fundamental of these commands is -the undo command @kbd{C-/} (also bound to @kbd{C-x u} and @kbd{C-_}). -This undoes a single command, or a -part of a command (as in the case of @code{query-replace}), or several -consecutive character insertions. Consecutive repetitions of -@kbd{C-/} undo earlier and earlier changes, back to the limit of the -undo information available. - - Aside from the commands described here, you can erase text using -deletion commands such as @key{DEL} (@code{delete-backward-char}). -These were described earlier in this manual. @xref{Erasing}. - -@menu -* Undo:: The Undo commands. -* Transpose:: Exchanging two characters, words, lines, lists... -* Fixing Case:: Correcting case of last word entered. -* Spelling:: Apply spelling checker to a word, or a whole file. -@end menu - -@node Undo -@section Undo -@cindex undo -@cindex changes, undoing - - The @dfn{undo} command reverses recent changes in the buffer's text. -Each buffer records changes individually, and the undo command always -applies to the current buffer. You can undo all the changes in a -buffer for as far as back its records go. Usually, each editing -command makes a separate entry in the undo records, but some commands -such as @code{query-replace} divide their changes into multiple -entries for flexibility in undoing. Consecutive character insertion -commands are usually grouped together into a single undo record, to -make undoing less tedious. - -@table @kbd -@item C-/ -@itemx C-x u -@itemx C-_ -Undo one entry in the current buffer's undo records (@code{undo}). -@end table - -@kindex C-x u -@kindex C-_ -@kindex C-/ -@findex undo - To begin to undo, type @kbd{C-/} (or its aliases, @kbd{C-_} or -@kbd{C-x u})@footnote{Aside from @kbd{C-/}, the @code{undo} command is -also bound to @kbd{C-x u} because that is more straightforward for -beginners to remember: @samp{u} stands for ``undo''. It is also bound -to @kbd{C-_} because typing @kbd{C-/} on some text terminals actually -enters @kbd{C-_}.}. This undoes the most recent change in the buffer, -and moves point back to where it was before that change. - Consecutive repetitions of @kbd{C-/} (or its aliases) undo earlier -and earlier changes in the current buffer. If all the recorded -changes have already been undone, the undo command signals an error. - -@cindex redo -@findex undo-only - Any command other than an undo command breaks the sequence of undo -commands. Starting from that moment, the entire sequence of undo -commands that you have just performed are themselves placed into the -undo record, as a single set of changes. Therefore, to re-apply -changes you have undone, type @kbd{C-f} or any other command that -harmlessly breaks the sequence of undoing; then type @kbd{C-/} to undo -the undo command. - - Alternatively, if you want to resume undoing, without redoing -previous undo commands, use @kbd{M-x undo-only}. This is like -@code{undo}, but will not redo changes you have just undone. - - If you notice that a buffer has been modified accidentally, the -easiest way to recover is to type @kbd{C-/} repeatedly until the stars -disappear from the front of the mode line (@pxref{Mode Line}). -Whenever an undo command makes the stars disappear from the mode line, -it means that the buffer contents are the same as they were when the -file was last read in or saved. If you do not remember whether you -changed the buffer deliberately, type @kbd{C-/} once. When you see -the last change you made undone, you will see whether it was an -intentional change. If it was an accident, leave it undone. If it -was deliberate, redo the change as described above. - -@cindex selective undo -@kindex C-u C-/ - When there is an active region, any use of @code{undo} performs -@dfn{selective undo}: it undoes the most recent change within the -region, instead of the entire buffer. However, when Transient Mark -mode is off (@pxref{Disabled Transient Mark}), @kbd{C-/} always -operates on the entire buffer, ignoring the region. In this case, you -can perform selective undo by supplying a prefix argument to the -@code{undo} command: @kbd{C-u C-/}. To undo further changes in the -same region, repeat the @code{undo} command (no prefix argument is -needed). - - Some specialized buffers do not make undo records. Buffers whose -names start with spaces never do; these buffers are used internally by -Emacs to hold text that users don't normally look at or edit. - -@vindex undo-limit -@vindex undo-strong-limit -@vindex undo-outer-limit -@cindex undo limit - When the undo records for a buffer becomes too large, Emacs discards -the oldest undo records from time to time (during @dfn{garbage -collection}). You can specify how much undo records to keep by -setting the variables @code{undo-limit}, @code{undo-strong-limit}, and -@code{undo-outer-limit}. Their values are expressed in bytes. - - The variable @code{undo-limit} sets a soft limit: Emacs keeps undo -data for enough commands to reach this size, and perhaps exceed it, -but does not keep data for any earlier commands beyond that. Its -default value is 80000. The variable @code{undo-strong-limit} sets a -stricter limit: any previous command (though not the most recent one) -that pushes the size past this amount is forgotten. The default value -of @code{undo-strong-limit} is 120000. - - Regardless of the values of those variables, the most recent change -is never discarded unless it gets bigger than @code{undo-outer-limit} -(normally 12,000,000). At that point, Emacs discards the undo data and -warns you about it. This is the only situation in which you cannot -undo the last command. If this happens, you can increase the value of -@code{undo-outer-limit} to make it even less likely to happen in the -future. But if you didn't expect the command to create such large -undo data, then it is probably a bug and you should report it. -@xref{Bugs,, Reporting Bugs}. - -@node Transpose -@section Transposing Text - -@table @kbd -@item C-t -Transpose two characters (@code{transpose-chars}). -@item M-t -Transpose two words (@code{transpose-words}). -@item C-M-t -Transpose two balanced expressions (@code{transpose-sexps}). -@item C-x C-t -Transpose two lines (@code{transpose-lines}). -@end table - -@kindex C-t -@findex transpose-chars - The common error of transposing two characters can be fixed, when they -are adjacent, with the @kbd{C-t} command (@code{transpose-chars}). Normally, -@kbd{C-t} transposes the two characters on either side of point. When -given at the end of a line, rather than transposing the last character of -the line with the newline, which would be useless, @kbd{C-t} transposes the -last two characters on the line. So, if you catch your transposition error -right away, you can fix it with just a @kbd{C-t}. If you don't catch it so -fast, you must move the cursor back between the two transposed -characters before you type @kbd{C-t}. If you transposed a space with -the last character of the word before it, the word motion commands are -a good way of getting there. Otherwise, a reverse search (@kbd{C-r}) -is often the best way. @xref{Search}. - -@kindex C-x C-t -@findex transpose-lines -@kindex M-t -@findex transpose-words -@c Don't index C-M-t and transpose-sexps here, they are indexed in -@c programs.texi, in the "List Commands" node. -@c @kindex C-M-t -@c @findex transpose-sexps - @kbd{M-t} transposes the word before point with the word after point -(@code{transpose-words}). It moves point forward over a word, -dragging the word preceding or containing point forward as well. The -punctuation characters between the words do not move. For example, -@w{@samp{FOO, BAR}} transposes into @w{@samp{BAR, FOO}} rather than -@samp{@w{BAR FOO,}}. - - @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for -transposing two expressions (@pxref{Expressions}), and @kbd{C-x C-t} -(@code{transpose-lines}) exchanges lines. They work like @kbd{M-t} -except as regards what units of text they transpose. - - A numeric argument to a transpose command serves as a repeat count: it -tells the transpose command to move the character (word, expression, line) -before or containing point across several other characters (words, -expressions, lines). For example, @kbd{C-u 3 C-t} moves the character before -point forward across three other characters. It would change -@samp{f@point{}oobar} into @samp{oobf@point{}ar}. This is equivalent to -repeating @kbd{C-t} three times. @kbd{C-u - 4 M-t} moves the word -before point backward across four words. @kbd{C-u - C-M-t} would cancel -the effect of plain @kbd{C-M-t}.@refill - - A numeric argument of zero is assigned a special meaning (because -otherwise a command with a repeat count of zero would do nothing): to -transpose the character (word, expression, line) ending after point -with the one ending after the mark. - -@node Fixing Case -@section Case Conversion - -@table @kbd -@item M-- M-l -Convert last word to lower case. Note @kbd{Meta--} is Meta-minus. -@item M-- M-u -Convert last word to all upper case. -@item M-- M-c -Convert last word to lower case with capital initial. -@end table - -@kindex M-@t{-} M-l -@kindex M-@t{-} M-u -@kindex M-@t{-} M-c - A very common error is to type words in the wrong case. Because of this, -the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a -special feature when used with a negative argument: they do not move the -cursor. As soon as you see you have mistyped the last word, you can simply -case-convert it and go on typing. @xref{Case}.@refill - -@node Spelling -@section Checking and Correcting Spelling -@cindex spelling, checking and correcting -@cindex checking spelling -@cindex correcting spelling - - This section describes the commands to check the spelling of a -single word or of a portion of a buffer. These commands only work if -the spelling checker program Aspell, Ispell or Hunspell is installed. -These programs are not part of Emacs, but one of them is usually -installed in GNU/Linux and other free operating systems. -@ifnottex -@xref{Top, Aspell,, aspell, The Aspell Manual}. -@end ifnottex - -@table @kbd -@item M-$ -Check and correct spelling of the word at point (@code{ispell-word}). -If the region is active, do it for all words in the region instead. -@item M-x ispell -Check and correct spelling of all words in the buffer. If the region -is active, do it for all words in the region instead. -@item M-x ispell-buffer -Check and correct spelling in the buffer. -@item M-x ispell-region -Check and correct spelling in the region. -@item M-x ispell-message -Check and correct spelling in a draft mail message, excluding cited -material. -@item M-x ispell-change-dictionary @key{RET} @var{dict} @key{RET} -Restart the Aspell/Ispell/Hunspell process, using @var{dict} as the dictionary. -@item M-x ispell-kill-ispell -Kill the Aspell/Ispell/Hunspell subprocess. -@item M-@key{TAB} -@itemx @key{ESC} @key{TAB} -Complete the word before point based on the spelling dictionary -(@code{ispell-complete-word}). -@item M-x flyspell-mode -Enable Flyspell mode, which highlights all misspelled words. -@item M-x flyspell-prog-mode -Enable Flyspell mode for comments and strings only. -@end table - -@kindex M-$ -@findex ispell-word - To check the spelling of the word around or before point, and -optionally correct it as well, type @kbd{M-$} (@code{ispell-word}). -If a region is active, @kbd{M-$} checks the spelling of all words -within the region. @xref{Mark}. (When Transient Mark mode is off, -@kbd{M-$} always acts on the word around or before point, ignoring the -region; @pxref{Disabled Transient Mark}.) - -@findex ispell -@findex ispell-buffer -@findex ispell-region -@cindex spell-checking the active region - Similarly, the command @kbd{M-x ispell} performs spell-checking in -the region if one is active, or in the entire buffer otherwise. The -commands @kbd{M-x ispell-buffer} and @kbd{M-x ispell-region} -explicitly perform spell-checking on the entire buffer or the region -respectively. To check spelling in an email message you are writing, -use @kbd{M-x ispell-message}; that command checks the whole buffer, -except for material that is indented or appears to be cited from other -messages. @xref{Sending Mail}. - - When one of these commands encounters what appears to be an -incorrect word, it asks you what to do. It usually displays a list of -numbered ``near-misses''---words that are close to the incorrect word. -Then you must type a single-character response. Here are the valid -responses: - -@table @kbd -@item @var{digit} -Replace the word, just this time, with one of the displayed -near-misses. Each near-miss is listed with a digit; type that digit -to select it. - -@item @key{SPC} -Skip this word---continue to consider it incorrect, but don't change it -here. - -@item r @var{new} @key{RET} -Replace the word, just this time, with @var{new}. (The replacement -string will be rescanned for more spelling errors.) - -@item R @var{new} @key{RET} -Replace the word with @var{new}, and do a @code{query-replace} so you -can replace it elsewhere in the buffer if you wish. (The replacements -will be rescanned for more spelling errors.) - -@item a -Accept the incorrect word---treat it as correct, but only in this -editing session. - -@item A -Accept the incorrect word---treat it as correct, but only in this -editing session and for this buffer. - -@item i -Insert this word in your private dictionary file so that Aspell or Ispell -or Hunspell will consider it correct from now on, even in future sessions. - -@item m -Like @kbd{i}, but you can also specify dictionary completion -information. - -@item u -Insert the lower-case version of this word in your private dic@-tion@-ary -file. - -@item l @var{word} @key{RET} -Look in the dictionary for words that match @var{word}. These words -become the new list of ``near-misses''; you can select one of them as -the replacement by typing a digit. You can use @samp{*} in @var{word} as a -wildcard. - -@item C-g -@itemx X -Quit interactive spell checking, leaving point at the word that was -being checked. You can restart checking again afterward with @kbd{C-u -M-$}. - -@item x -Quit interactive spell checking and move point back to where it was -when you started spell checking. - -@item q -Quit interactive spell checking and kill the spell-checker subprocess. - -@item ? -Show the list of options. -@end table - -@findex ispell-complete-word - In Text mode and related modes, @kbd{M-@key{TAB}} -(@code{ispell-complete-word}) performs in-buffer completion based on -spelling correction. Insert the beginning of a word, and then type -@kbd{M-@key{TAB}}; this shows a list of completions. (If your -window manager intercepts @kbd{M-@key{TAB}}, type @kbd{@key{ESC} -@key{TAB}} or @kbd{C-M-i}.) Each completion is listed with a digit or -character; type that digit or character to choose it. - -@cindex @code{ispell} program -@findex ispell-kill-ispell - Once started, the Aspell or Ispell or Hunspell subprocess continues -to run, waiting for something to do, so that subsequent spell checking -commands complete more quickly. If you want to get rid of the -process, use @kbd{M-x ispell-kill-ispell}. This is not usually -necessary, since the process uses no processor time except when you do -spelling correction. - -@vindex ispell-dictionary -@vindex ispell-local-dictionary -@vindex ispell-personal-dictionary -@findex ispell-change-dictionary - Ispell, Aspell and Hunspell look up spelling in two dictionaries: -the standard dictionary and your personal dictionary. The standard -dictionary is specified by the variable @code{ispell-local-dictionary} -or, if that is @code{nil}, by the variable @code{ispell-dictionary}. -If both are @code{nil}, the spelling program's default dictionary is -used. The command @kbd{M-x ispell-change-dictionary} sets the -standard dictionary for the buffer and then restarts the subprocess, -so that it will use a different standard dictionary. Your personal -dictionary is specified by the variable -@code{ispell-personal-dictionary}. If that is @code{nil}, the -spelling program looks for a personal dictionary in a default -location. - -@vindex ispell-complete-word-dict - A separate dictionary is used for word completion. The variable -@code{ispell-complete-word-dict} specifies the file name of this -dictionary. The completion dictionary must be different because it -cannot use root and affix information. For some languages, there -is a spell checking dictionary but no word completion dictionary. - -@cindex Flyspell mode -@cindex mode, Flyspell -@findex flyspell-mode - Flyspell mode is a minor mode that performs automatic spell checking -as you type. When it finds a word that it does not recognize, it -highlights that word. Type @kbd{M-x flyspell-mode} to toggle Flyspell -mode in the current buffer. To enable Flyspell mode in all text mode -buffers, add @code{flyspell-mode} to @code{text-mode-hook}. -@xref{Hooks}. - - When Flyspell mode highlights a word as misspelled, you can click on -it with @kbd{Mouse-2} to display a menu of possible corrections and -actions. You can also correct the word by editing it manually in any -way you like. - -@findex flyspell-prog-mode - Flyspell Prog mode works just like ordinary Flyspell mode, except -that it only checks words in comments and string constants. This -feature is useful for editing programs. Type @kbd{M-x -flyspell-prog-mode} to enable or disable this mode in the current -buffer. To enable this mode in all programming mode buffers, add -@code{flyspell-prog-mode} to @code{prog-mode-hook} (@pxref{Hooks}). diff --git a/doc/emacs/fortran-xtra.texi b/doc/emacs/fortran-xtra.texi deleted file mode 100644 index 43e2e63863e..00000000000 --- a/doc/emacs/fortran-xtra.texi +++ /dev/null @@ -1,581 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Fortran -@section Fortran Mode -@cindex Fortran mode -@cindex mode, Fortran - -@cindex Fortran fixed form and free form -@cindex Fortran 77 and Fortran 90, 95, 2003, 2008 -@findex f90-mode -@findex fortran-mode - Fortran mode is meant for editing ``fixed form'' (and also ``tab -format'') source code (normally Fortran 77). For editing more modern -``free form'' source code (Fortran 90, 95, 2003, 2008), use F90 mode -(@code{f90-mode}). Emacs normally uses Fortran mode for files with -extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 mode for the -extensions @samp{.f90}, @samp{.f95}, @samp{.f03} and @samp{.f08}. -Customize @code{auto-mode-alist} to add more extensions. GNU Fortran -supports both free and fixed form. This manual mainly documents Fortran -mode, but the corresponding F90 mode features are mentioned when -relevant. - - Fortran mode provides special motion commands for Fortran statements -and subprograms, and indentation commands that understand Fortran -conventions of nesting, line numbers and continuation statements. -Fortran mode has support for Auto Fill mode that breaks long lines into -proper Fortran continuation lines. Fortran mode also supports Hideshow -minor mode -@iftex -(@pxref{Hideshow,,, emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Hideshow}), -@end ifnottex -and Imenu -@iftex -(@pxref{Imenu,,, emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Imenu}). -@end ifnottex - - Special commands for comments are provided because Fortran comments -are unlike those of other languages. Built-in abbrevs optionally save -typing when you insert Fortran keywords. - - Use @kbd{M-x fortran-mode} to switch to this major mode. This -command runs the hook @code{fortran-mode-hook}. -@iftex -@xref{Hooks,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Hooks}. -@end ifnottex - -@menu -* Motion: Fortran Motion. Moving point by statements or subprograms. -* Indent: Fortran Indent. Indentation commands for Fortran. -* Comments: Fortran Comments. Inserting and aligning comments. -* Autofill: Fortran Autofill. Auto fill support for Fortran. -* Columns: Fortran Columns. Measuring columns for valid Fortran. -* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. -@end menu - -@node Fortran Motion -@subsection Motion Commands - - In addition to the normal commands for moving by and operating on -``defuns'' (Fortran subprograms---functions and subroutines, as well -as modules for F90 mode, using the commands @code{fortran-end-of-subprogram} -and @code{fortran-beginning-of-subprogram}), Fortran mode provides -special commands to move by statements and other program units. - -@table @kbd -@kindex C-c C-n @r{(Fortran mode)} -@findex fortran-next-statement -@findex f90-next-statement -@item C-c C-n -Move to the beginning of the next statement -(@code{fortran-next-statement}/@code{f90-next-statement}). - -@kindex C-c C-p @r{(Fortran mode)} -@findex fortran-previous-statement -@findex f90-previous-statement -@item C-c C-p -Move to the beginning of the previous statement -(@code{fortran-previous-statement}/@code{f90-previous-statement}). -If there is no previous statement (i.e. if called from the first -statement in the buffer), move to the start of the buffer. - -@kindex C-c C-e @r{(F90 mode)} -@findex f90-next-block -@item C-c C-e -Move point forward to the start of the next code block, or the end of -the current one, whichever comes first (@code{f90-next-block}). -A code block is a subroutine, @code{if}--@code{endif} statement, and -so forth. This command exists for F90 mode only, not Fortran mode. -With a numeric argument, it moves forward that many blocks. - -@kindex C-c C-a @r{(F90 mode)} -@findex f90-previous-block -@item C-c C-a -Move point backward to the previous block -(@code{f90-previous-block}). This is like @code{f90-next-block}, but -moves backwards. - -@kindex C-M-n @r{(Fortran mode)} -@findex fortran-end-of-block -@findex f90-end-of-block -@item C-M-n -Move to the end of the current code block -(@code{fortran-end-of-block}/@code{f90-end-of-block}). With a numeric -argument, move forward that number of blocks. The mark is set before -moving point. The F90 mode version of this command checks for -consistency of block types and labels (if present), but it does not -check the outermost block since that may be incomplete. - -@kindex C-M-p @r{(Fortran mode)} -@findex fortran-beginning-of-block -@findex f90-beginning-of-block -@item C-M-p -Move to the start of the current code block -(@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This -is like @code{fortran-end-of-block}, but moves backwards. -@end table - -The commands @code{fortran-beginning-of-subprogram} and -@code{fortran-end-of-subprogram} move to the start or end of the -current subprogram, respectively. The commands @code{fortran-mark-do} -and @code{fortran-mark-if} mark the end of the current @code{do} or -@code{if} block, and move point to the start. - - -@node Fortran Indent -@subsection Fortran Indentation - - Special commands and features are needed for indenting fixed (or tab) -form Fortran code in order to make sure various syntactic entities (line -numbers, comment line indicators and continuation line flags) appear in -the required columns. - -@menu -* Commands: ForIndent Commands. Commands for indenting and filling Fortran. -* Contline: ForIndent Cont. How continuation lines indent. -* Numbers: ForIndent Num. How line numbers auto-indent. -* Conv: ForIndent Conv. Conventions you must obey to avoid trouble. -* Vars: ForIndent Vars. Variables controlling Fortran indent style. -@end menu - -@node ForIndent Commands -@subsubsection Fortran Indentation and Filling Commands - -@table @kbd -@item C-M-j -Break the current line at point and set up a continuation line -(@code{fortran-split-line}). -@item M-^ -Join this line to the previous line (@code{fortran-join-line}). -@item C-M-q -Indent all the lines of the subprogram that point is in -(@code{fortran-indent-subprogram}). -@item M-q -Fill a comment block or statement (using @code{fortran-fill-paragraph} -or @code{fortran-fill-statement}). -@end table - -@kindex C-M-q @r{(Fortran mode)} -@findex fortran-indent-subprogram - The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command -to reindent all the lines of the Fortran subprogram (function or -subroutine) containing point. - -@kindex C-M-j @r{(Fortran mode)} -@findex fortran-split-line - The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits -a line in the appropriate fashion for Fortran. In a non-comment line, -the second half becomes a continuation line and is indented -accordingly. In a comment line, both halves become separate comment -lines. - -@kindex M-^ @r{(Fortran mode)} -@kindex C-c C-d @r{(Fortran mode)} -@findex fortran-join-line - @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, -which joins a continuation line back to the previous line, roughly as -the inverse of @code{fortran-split-line}. The point must be on a -continuation line when this command is invoked. - -@kindex M-q @r{(Fortran mode)} -@kbd{M-q} in Fortran mode fills the comment block or statement that -point is in. This removes any excess statement continuations. - -@node ForIndent Cont -@subsubsection Continuation Lines -@cindex Fortran continuation lines - -@vindex fortran-continuation-string - Most Fortran 77 compilers allow two ways of writing continuation lines. -If the first non-space character on a line is in column 5, then that -line is a continuation of the previous line. We call this @dfn{fixed -form}. (In GNU Emacs we always count columns from 0; but note that -the Fortran standard counts from 1.) The variable -@code{fortran-continuation-string} specifies what character to put in -column 5. A line that starts with a tab character followed by any digit -except @samp{0} is also a continuation line. We call this style of -continuation @dfn{tab format}. (Fortran 90 introduced ``free form'', -with another style of continuation lines). - -@vindex indent-tabs-mode @r{(Fortran mode)} -@vindex fortran-analyze-depth -@vindex fortran-tab-mode-default - Fortran mode can use either style of continuation line. When you -enter Fortran mode, it tries to deduce the proper continuation style -automatically from the buffer contents. It does this by scanning up to -@code{fortran-analyze-depth} (default 100) lines from the start of the -buffer. The first line that begins with either a tab character or six -spaces determines the choice. If the scan fails (for example, if the -buffer is new and therefore empty), the value of -@code{fortran-tab-mode-default} (@code{nil} for fixed form, and -non-@code{nil} for tab format) is used. @samp{/t} -(@code{fortran-tab-mode-string}) in the mode line indicates tab format -is selected. Fortran mode sets the value of @code{indent-tabs-mode} -accordingly. - - If the text on a line starts with the Fortran continuation marker -@samp{$}, or if it begins with any non-whitespace character in column -5, Fortran mode treats it as a continuation line. When you indent a -continuation line with @key{TAB}, it converts the line to the current -continuation style. When you split a Fortran statement with -@kbd{C-M-j}, the continuation marker on the newline is created according -to the continuation style. - - The setting of continuation style affects several other aspects of -editing in Fortran mode. In fixed form mode, the minimum column -number for the body of a statement is 6. Lines inside of Fortran -blocks that are indented to larger column numbers must use only the -space character for whitespace. In tab format mode, the minimum -column number for the statement body is 8, and the whitespace before -column 8 must consist of one tab character. - -@node ForIndent Num -@subsubsection Line Numbers - - If a number is the first non-whitespace in the line, Fortran -indentation assumes it is a line number and moves it to columns 0 -through 4. (Columns always count from 0 in Emacs.) - -@vindex fortran-line-number-indent - Line numbers of four digits or less are normally indented one space. -The variable @code{fortran-line-number-indent} controls this; it -specifies the maximum indentation a line number can have. The default -value of the variable is 1. Fortran mode tries to prevent line number -digits passing column 4, reducing the indentation below the specified -maximum if necessary. If @code{fortran-line-number-indent} has the -value 5, line numbers are right-justified to end in column 4. - -@vindex fortran-electric-line-number - Simply inserting a line number is enough to indent it according to -these rules. As each digit is inserted, the indentation is recomputed. -To turn off this feature, set the variable -@code{fortran-electric-line-number} to @code{nil}. - - -@node ForIndent Conv -@subsubsection Syntactic Conventions - - Fortran mode assumes that you follow certain conventions that simplify -the task of understanding a Fortran program well enough to indent it -properly: - -@itemize @bullet -@item -Two nested @samp{do} loops never share a @samp{continue} statement. - -@item -Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} -and others are written without embedded whitespace or line breaks. - -Fortran compilers generally ignore whitespace outside of string -constants, but Fortran mode does not recognize these keywords if they -are not contiguous. Constructs such as @samp{else if} or @samp{end do} -are acceptable, but the second word should be on the same line as the -first and not on a continuation line. -@end itemize - -@noindent -If you fail to follow these conventions, the indentation commands may -indent some lines unaesthetically. However, a correct Fortran program -retains its meaning when reindented even if the conventions are not -followed. - -@node ForIndent Vars -@subsubsection Variables for Fortran Indentation - -@vindex fortran-do-indent -@vindex fortran-if-indent -@vindex fortran-structure-indent -@vindex fortran-continuation-indent -@vindex fortran-check-all-num@dots{} -@vindex fortran-minimum-statement-indent@dots{} - Several additional variables control how Fortran indentation works: - -@table @code -@item fortran-do-indent -Extra indentation within each level of @samp{do} statement (default 3). - -@item fortran-if-indent -Extra indentation within each level of @samp{if}, @samp{select case}, or -@samp{where} statements (default 3). - -@item fortran-structure-indent -Extra indentation within each level of @samp{structure}, @samp{union}, -@samp{map}, or @samp{interface} statements (default 3). - -@item fortran-continuation-indent -Extra indentation for bodies of continuation lines (default 5). - -@item fortran-check-all-num-for-matching-do -In Fortran 77, a numbered @samp{do} statement is ended by any statement -with a matching line number. It is common (but not compulsory) to use a -@samp{continue} statement for this purpose. If this variable has a -non-@code{nil} value, indenting any numbered statement must check for a -@samp{do} that ends there. If you always end @samp{do} statements with -a @samp{continue} line (or if you use the more modern @samp{enddo}), -then you can speed up indentation by setting this variable to -@code{nil} (the default). - -@item fortran-blink-matching-if -If this is @code{t}, indenting an @samp{endif} (or @samp{enddo} -statement moves the cursor momentarily to the matching @samp{if} (or -@samp{do}) statement to show where it is. The default is @code{nil}. - -@item fortran-minimum-statement-indent-fixed -Minimum indentation for Fortran statements when using fixed form -continuation line style. Statement bodies are never indented by less than -this. The default is 6. - -@item fortran-minimum-statement-indent-tab -Minimum indentation for Fortran statements for tab format continuation line -style. Statement bodies are never indented by less than this. The -default is 8. -@end table - -The following section describes the variables controlling the -indentation of comments. - -@node Fortran Comments -@subsection Fortran Comments - - The usual Emacs comment commands assume that a comment can follow a -line of code. In Fortran 77, the standard comment syntax requires an -entire line to be just a comment. Therefore, Fortran mode replaces the -standard Emacs comment commands and defines some new variables. - -@vindex fortran-comment-line-start - Fortran mode can also handle the Fortran 90 comment syntax where -comments start with @samp{!} and can follow other text. Because only -some Fortran 77 compilers accept this syntax, Fortran mode will not -insert such comments unless you have said in advance to do so. To do -this, set the variable @code{fortran-comment-line-start} to @samp{"!"}. -If you use an unusual value, you may need to change -@code{fortran-comment-line-start-skip}. - - -@table @kbd -@item M-; -Align comment or insert new comment (@code{comment-dwim}). - -@item C-x ; -Applies to nonstandard @samp{!} comments only (@code{comment-set-column}). - -@item C-c ; -Turn all lines of the region into comments, or (with argument) turn them back -into real code (@code{fortran-comment-region}). -@end table - - @kbd{M-;} in Fortran mode runs the standard @code{comment-dwim}. -This recognizes any kind of existing comment and aligns its text -appropriately; if there is no existing comment, a comment is inserted -and aligned. Inserting and aligning comments are not the same in -Fortran mode as in other modes. - - When a new comment must be inserted, if the current line is blank, a -full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} -comment is inserted if you have said you want to use them. Otherwise a -full-line comment is inserted on a new line before the current line. - - Nonstandard @samp{!} comments are aligned like comments in other -languages, but full-line comments are different. In a standard full-line -comment, the comment delimiter itself must always appear in column zero. -What can be aligned is the text within the comment. You can choose from -three styles of alignment by setting the variable -@code{fortran-comment-indent-style} to one of these values: - -@vindex fortran-comment-indent-style -@vindex fortran-comment-line-extra-indent -@table @code -@item fixed -Align the text at a fixed column, which is the sum of -@code{fortran-comment-line-extra-indent} and the minimum statement -indentation. This is the default. - -The minimum indentation is -@code{fortran-minimum-statement-indent-tab} for tab format -continuation line style and @code{fortran-minimum-statement-indent-fixed} -for fixed form style. - -@item relative -Align the text as if it were a line of code, but with an additional -@code{fortran-comment-line-extra-indent} columns of indentation. - -@item nil -Don't move text in full-line comments automatically. -@end table - -@vindex fortran-comment-indent-char - In addition, you can specify the character to be used to indent within -full-line comments by setting the variable -@code{fortran-comment-indent-char} to the single-character string you want -to use. - -@vindex fortran-directive-re - Compiler directive lines, or preprocessor lines, have much the same -appearance as comment lines. It is important, though, that such lines -never be indented at all, no matter what the value of -@code{fortran-comment-indent-style}. The variable -@code{fortran-directive-re} is a regular expression that specifies which -lines are directives. Matching lines are never indented, and receive -distinctive font-locking. - - The normal Emacs comment command @kbd{C-x ;} (@code{comment-set-column}) -has not been redefined. If you use @samp{!} comments, this command -can be used with them. Otherwise it is useless in Fortran mode. - -@kindex C-c ; @r{(Fortran mode)} -@findex fortran-comment-region -@vindex fortran-comment-region - The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the -lines of the region into comments by inserting the string @samp{c$$$} at -the front of each one. With a numeric argument, it turns the region -back into live code by deleting @samp{c$$$} from the front of each line -in it. The string used for these comments can be controlled by setting -the variable @code{fortran-comment-region}. Note that here we have an -example of a command and a variable with the same name; these two uses -of the name never conflict because in Lisp and in Emacs it is always -clear from the context which one is meant. - -@node Fortran Autofill -@subsection Auto Fill in Fortran Mode - - Fortran mode has specialized support for Auto Fill mode, which is a -minor mode that automatically splits statements as you insert them -when they become too wide. Splitting a statement involves making -continuation lines using @code{fortran-continuation-string} -(@pxref{ForIndent Cont}). This splitting happens when you type -@key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran -indentation commands. You activate Auto Fill in Fortran mode in the -normal way. -@iftex -@xref{Auto Fill,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Auto Fill}. -@end ifnottex - -@vindex fortran-break-before-delimiters - Auto Fill breaks lines at spaces or delimiters when the lines get -longer than the desired width (the value of @code{fill-column}). The -delimiters (besides whitespace) that Auto Fill can break at are -@samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, @samp{<}, @samp{>}, -and @samp{,}. The line break comes after the delimiter if the -variable @code{fortran-break-before-delimiters} is @code{nil}. -Otherwise (and by default), the break comes before the delimiter. - - To enable Auto Fill in all Fortran buffers, add -@code{auto-fill-mode} to @code{fortran-mode-hook}. -@iftex -@xref{Hooks,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Hooks}. -@end ifnottex - -@node Fortran Columns -@subsection Checking Columns in Fortran - -@vindex fortran-line-length -In standard Fortran 77, anything beyond column 72 is ignored. -Most compilers provide an option to change this (for example, -@samp{-ffixed-line-length-N} in gfortran). Customize the variable -@code{fortran-line-length} to change the line length in Fortran mode. -Anything beyond this point is font-locked as a comment. (Unless it is -inside a string: strings that extend beyond @code{fortran-line-length} -will confuse font-lock.) - -@table @kbd -@item C-c C-r -Display a ``column ruler'' momentarily above the current line -(@code{fortran-column-ruler}). -@item C-c C-w -Split the current window horizontally temporarily so that it is -@code{fortran-line-length} columns wide -(@code{fortran-window-create-momentarily}). This may help you avoid -making lines longer than the limit imposed by your Fortran compiler. -@item C-u C-c C-w -Split the current window horizontally so that it is -@code{fortran-line-length} columns wide (@code{fortran-window-create}). -You can then continue editing. -@item M-x fortran-strip-sequence-nos -Delete all text in column @code{fortran-line-length} and beyond. -@end table - -@kindex C-c C-r @r{(Fortran mode)} -@findex fortran-column-ruler - The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column -ruler momentarily above the current line. The comment ruler is two lines -of text that show you the locations of columns with special significance in -Fortran programs. Square brackets show the limits of the columns for line -numbers, and curly brackets show the limits of the columns for the -statement body. Column numbers appear above them. - - Note that the column numbers count from zero, as always in GNU Emacs. -As a result, the numbers may be one less than those you are familiar -with; but the positions they indicate in the line are standard for -Fortran. - -@vindex fortran-column-ruler-fixed -@vindex fortran-column-ruler-tabs - The text used to display the column ruler depends on the value of the -variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is -@code{nil}, then the value of the variable -@code{fortran-column-ruler-fixed} is used as the column ruler. -Otherwise, the value of the variable @code{fortran-column-ruler-tab} is -displayed. By changing these variables, you can change the column ruler -display. - -@kindex C-c C-w @r{(Fortran mode)} -@findex fortran-window-create-momentarily - @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily -splits the current window horizontally, making a window -@code{fortran-line-length} columns wide, so you can see any lines that -are too long. Type a space to restore the normal width. - -@kindex C-u C-c C-w @r{(Fortran mode)} -@findex fortran-window-create - You can also split the window horizontally and continue editing with -the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x -fortran-window-create}). By editing in this window you can -immediately see when you make a line too wide to be correct Fortran. - -@findex fortran-strip-sequence-nos - The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in -column @code{fortran-line-length} and beyond, on all lines in the -current buffer. This is the easiest way to get rid of old sequence -numbers. - -@node Fortran Abbrev -@subsection Fortran Keyword Abbrevs - - Fortran mode provides many built-in abbrevs for common keywords and -declarations. These are the same sort of abbrev that you can define -yourself. To use them, you must turn on Abbrev mode. -@iftex -@xref{Abbrevs,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Abbrevs}. -@end ifnottex - - The built-in abbrevs are unusual in one way: they all start with a -semicolon. For example, one built-in Fortran abbrev is @samp{;c} for -@samp{continue}. If you insert @samp{;c} and then insert a punctuation -character such as a space or a newline, the @samp{;c} expands automatically -to @samp{continue}, provided Abbrev mode is enabled.@refill - - Type @samp{;?} or @samp{;C-h} to display a list of all the built-in -Fortran abbrevs and what they stand for. diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi deleted file mode 100644 index ee468e6f685..00000000000 --- a/doc/emacs/frames.texi +++ /dev/null @@ -1,1170 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Frames, International, Windows, Top -@chapter Frames and Graphical Displays -@cindex frames - - When Emacs is started on a graphical display, e.g.@: on the X Window -System, it occupies a graphical system-level ``window''. In this -manual, we call this a @dfn{frame}, reserving the word ``window'' for -the part of the frame used for displaying a buffer. A frame initially -contains one window, but it can be subdivided into multiple windows -(@pxref{Windows}). A frame normally also contains a menu bar, tool -bar, and echo area. - - You can also create additional frames (@pxref{Creating Frames}). -All frames created in the same Emacs session have access to the same -underlying buffers and other data. For instance, if a buffer is being -shown in more than one frame, any changes made to it in one frame show -up immediately in the other frames too. - - Typing @kbd{C-x C-c} closes all the frames on the current display, -and ends the Emacs session if it has no frames open on any other -displays (@pxref{Exiting}). To close just the selected frame, type -@kbd{C-x 5 0} (that is zero, not @kbd{o}). - - This chapter describes Emacs features specific to graphical displays -(particularly mouse commands), and features for managing multiple -frames. On text terminals, many of these features are unavailable. -However, it is still possible to create multiple ``frames'' on text -terminals; such frames are displayed one at a time, filling the entire -terminal screen (@pxref{Non-Window Terminals}). It is also possible -to use the mouse on some text terminals (@pxref{Text-Only Mouse}, for -doing so on GNU and Unix systems; and -@iftex -@pxref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}, -@end iftex -@ifnottex -@pxref{MS-DOS Mouse}, -@end ifnottex -for doing so on MS-DOS). - -@menu -* Mouse Commands:: Moving, cutting, and pasting, with the mouse. -* Word and Line Mouse:: Mouse commands for selecting whole words or lines. -* Mouse References:: Using the mouse to select an item from a list. -* Menu Mouse Clicks:: Mouse clicks that bring up menus. -* Mode Line Mouse:: Mouse clicks on the mode line. -* Creating Frames:: Creating additional Emacs frames with various contents. -* Frame Commands:: Iconifying, deleting, and switching frames. -* Fonts:: Changing the frame font. -* Speedbar:: How to make and use a speedbar frame. -* Multiple Displays:: How one Emacs instance can talk to several displays. -* Frame Parameters:: Changing the colors and other modes of frames. -* Scroll Bars:: How to enable and disable scroll bars; how to use them. -* Drag and Drop:: Using drag and drop to open files and insert text. -* Menu Bars:: Enabling and disabling the menu bar. -* Tool Bars:: Enabling and disabling the tool bar. -* Dialog Boxes:: Controlling use of dialog boxes. -* Tooltips:: Displaying information at the current mouse position. -* Mouse Avoidance:: Preventing the mouse pointer from obscuring text. -* Non-Window Terminals:: Multiple frames on terminals that show only one. -* Text-Only Mouse:: Using the mouse in text terminals. -@end menu - -@node Mouse Commands -@section Mouse Commands for Editing -@cindex mouse buttons (what they do) -@cindex mouse, selecting text using - -@kindex Mouse-1 -@kindex Mouse-2 -@kindex Mouse-3 -@table @kbd -@item Mouse-1 -Move point to where you click (@code{mouse-set-point}). - -@item Drag-Mouse-1 -Activate the region around the text selected by dragging, and copy it -to the kill ring (@code{mouse-set-region}). - -@item Mouse-2 -Yank the last killed text at the click position -(@code{mouse-yank-at-click}). - -@item Mouse-3 -If the region is active, move the nearer end of the region to the -click position; otherwise, set mark at the current value of point and -point at the click position. Save the resulting region in the kill -ring; on a second click, kill it (@code{mouse-save-then-kill}). -@end table - -@findex mouse-set-point - The most basic mouse command is @code{mouse-set-point}, which is -invoked by clicking with the left mouse button, @kbd{Mouse-1}, in the -text area of a window. This moves point to the position where you -clicked. If that window was not the selected window, it becomes the -selected window. - -@vindex x-mouse-click-focus-ignore-position - Normally, if the frame you clicked in was not the selected frame, it -is made the selected frame, in addition to selecting the window and -setting the cursor. On the X Window System, you can change this by -setting the variable @code{x-mouse-click-focus-ignore-position} to -@code{t}. In that case, the initial click on an unselected frame just -selects the frame, without doing anything else; clicking again selects -the window and sets the cursor position. - -@cindex mouse, dragging -@findex mouse-set-region - Holding down @kbd{Mouse-1} and ``dragging'' the mouse over a stretch -of text activates the region around that text -(@code{mouse-set-region}), placing the mark where you started holding -down the mouse button, and point where you release it (@pxref{Mark}). -In addition, the text in the region becomes the primary selection -(@pxref{Primary Selection}). - -@vindex mouse-drag-copy-region - If you change the variable @code{mouse-drag-copy-region} to a -non-@code{nil} value, dragging the mouse over a stretch of text also -adds the text to the kill ring. The default is @code{nil}. - -@vindex mouse-scroll-min-lines - If you move the mouse off the top or bottom of the window while -dragging, the window scrolls at a steady rate until you move the mouse -back into the window. This way, you can select regions that don't fit -entirely on the screen. The number of lines scrolled per step depends -on how far away from the window edge the mouse has gone; the variable -@code{mouse-scroll-min-lines} specifies a minimum step size. - -@findex mouse-yank-primary -@findex mouse-yank-at-click - Clicking with the middle mouse button, @kbd{Mouse-2}, moves point to -the position where you clicked and inserts the contents of the primary -selection (@code{mouse-yank-primary}). @xref{Primary Selection}. -This behavior is consistent with other X applications. Alternatively, -you can rebind @kbd{Mouse-2} to @code{mouse-yank-at-click}, which -performs a yank at point. - -@vindex mouse-yank-at-point - If you change the variable @code{mouse-yank-at-point} to a -non-@code{nil} value, @kbd{Mouse-2} does not move point; it inserts -the text at point, regardless of where you clicked or even which of -the frame's windows you clicked on. This variable affects both -@code{mouse-yank-primary} and @code{mouse-yank-at-click}. - -@findex mouse-save-then-kill - Clicking with the right mouse button, @kbd{Mouse-3}, runs the -command @code{mouse-save-then-kill}. This performs several actions -depending on where you click and the status of the region: - -@itemize @bullet -@item -If no region is active, clicking @kbd{Mouse-3} activates the region, -placing the mark where point was and point at the clicked position. - -@item -If a region is active, clicking @kbd{Mouse-3} adjusts the nearer end -of the region by moving it to the clicked position. The adjusted -region's text is copied to the kill ring; if the text in the original -region was already on the kill ring, it replaces it there. - -@item -If you originally specified the region using a double or triple -@kbd{Mouse-1}, so that the region is defined to consist of entire -words or lines (@pxref{Word and Line Mouse}), then adjusting the -region with @kbd{Mouse-3} also proceeds by entire words or lines. - -@item -If you use @kbd{Mouse-3} a second time consecutively, at the same -place, that kills the region already selected. Thus, the simplest way -to kill text with the mouse is to click @kbd{Mouse-1} at one end, then -click @kbd{Mouse-3} twice at the other end. To copy the text into the -kill ring without deleting it from the buffer, press @kbd{Mouse-3} -just once---or just drag across the text with @kbd{Mouse-1}. Then you -can copy it elsewhere by yanking it. -@end itemize - - The @code{mouse-save-then-kill} command also obeys the variable -@code{mouse-drag-copy-region} (described above). If the value is -non-@code{nil}, then whenever the command sets or adjusts the active -region, the text in the region is also added to the kill ring. If the -latest kill ring entry had been added the same way, that entry is -replaced rather than making a new entry. - - Whenever you set the region using any of the mouse commands -described above, the mark will be deactivated by any subsequent -unshifted cursor motion command, in addition to the usual ways of -deactivating the mark. @xref{Shift Selection}. - -@cindex mouse wheel -@findex mouse-wheel-mode -@cindex Mouse Wheel minor mode -@cindex mode, Mouse Wheel -@vindex mouse-wheel-follow-mouse -@vindex mouse-wheel-scroll-amount -@vindex mouse-wheel-progressive-speed - Some mice have a ``wheel'' which can be used for scrolling. Emacs -supports scrolling windows with the mouse wheel, by default, on most -graphical displays. To toggle this feature, use @kbd{M-x -mouse-wheel-mode}. The variables @code{mouse-wheel-follow-mouse} and -@code{mouse-wheel-scroll-amount} determine where and by how much -buffers are scrolled. The variable -@code{mouse-wheel-progressive-speed} determines whether the scroll -speed is linked to how fast you move the wheel. - -@node Word and Line Mouse -@section Mouse Commands for Words and Lines - - These variants of @kbd{Mouse-1} select entire words or lines at a -time. Emacs activates the region around the selected text, which is -also copied to the kill ring. - -@table @kbd -@item Double-Mouse-1 -Select the text around the word which you click on. - -Double-clicking on a character with ``symbol'' syntax (such as -underscore, in C mode) selects the symbol surrounding that character. -Double-clicking on a character with open- or close-parenthesis syntax -selects the parenthetical grouping which that character starts or -ends. Double-clicking on a character with string-delimiter syntax -(such as a single-quote or double-quote in C) selects the string -constant (Emacs uses heuristics to figure out whether that character -is the beginning or the end of it). - -@item Double-Drag-Mouse-1 -Select the text you drag across, in the form of whole words. - -@item Triple-Mouse-1 -Select the line you click on. - -@item Triple-Drag-Mouse-1 -Select the text you drag across, in the form of whole lines. -@end table - -@node Mouse References -@section Following References with the Mouse -@kindex Mouse-1 @r{(on buttons)} -@kindex Mouse-2 @r{(on buttons)} -@cindex hyperlinks -@cindex links -@cindex text buttons -@cindex buttons - -@vindex mouse-highlight - Some Emacs buffers include @dfn{buttons}, or @dfn{hyperlinks}: -pieces of text that perform some action (e.g.@: following a reference) -when activated (e.g.@: by clicking on them). Usually, a button's text -is visually highlighted: it is underlined, or a box is drawn around -it. If you move the mouse over a button, the shape of the mouse -cursor changes and the button lights up. If you change the variable -@code{mouse-highlight} to @code{nil}, Emacs disables this -highlighting. - - You can activate a button by moving point to it and typing -@key{RET}, or by clicking either @kbd{Mouse-1} or @kbd{Mouse-2} on the -button. For example, in a Dired buffer, each file name is a button; -activating it causes Emacs to visit that file (@pxref{Dired}). In a -@file{*Compilation*} buffer, each error message is a button, and -activating it visits the source code for that error -(@pxref{Compilation}). - - Although clicking @kbd{Mouse-1} on a button usually activates the -button, if you hold the mouse button down for a period of time before -releasing it (specifically, for more than 450 milliseconds), then -Emacs moves point where you clicked, without activating the button. -In this way, you can use the mouse to move point over a button without -activating it. Dragging the mouse over or onto a button has its usual -behavior of setting the region, and does not activate the button. - - You can change how @kbd{Mouse-1} applies to buttons by customizing -the variable @code{mouse-1-click-follows-link}. If the value is a -positive integer, that determines how long you need to hold the mouse -button down for, in milliseconds, to cancel button activation; the -default is 450, as described in the previous paragraph. If the value -is @code{nil}, @kbd{Mouse-1} just sets point where you clicked, and -does not activate buttons. If the value is @code{double}, double -clicks activate buttons but single clicks just set point. - -@vindex mouse-1-click-in-non-selected-windows - Normally, @kbd{Mouse-1} on a button activates the button even if it -is in a non-selected window. If you change the variable -@code{mouse-1-click-in-non-selected-windows} to @code{nil}, -@kbd{Mouse-1} on a button in an unselected window moves point to the -clicked position and selects that window, without activating the -button. - -@node Menu Mouse Clicks -@section Mouse Clicks for Menus - - Several mouse clicks with the @key{CTRL} and @key{SHIFT} modifiers -bring up menus. - -@table @kbd -@item C-Mouse-1 -@kindex C-Mouse-1 -This menu is for selecting a buffer. - -The MSB (``mouse select buffer'') global minor mode makes this -menu smarter and more customizable. @xref{Buffer Menus}. - -@item C-Mouse-2 -@kindex C-Mouse-2 -This menu contains entries for examining faces and other text -properties, and well as for setting them (the latter is mainly useful -when editing enriched text; @pxref{Enriched Text}). - -@item C-Mouse-3 -@kindex C-Mouse-3 -This menu is mode-specific. For most modes if Menu-bar mode is on, -this menu has the same items as all the mode-specific menu-bar menus -put together. Some modes may specify a different menu for this -button. If Menu Bar mode is off, this menu contains all the items -which would be present in the menu bar---not just the mode-specific -ones---so that you can access them without having to display the menu -bar. - -@item S-Mouse-1 -This menu is for changing the default face within the window's buffer. -@xref{Text Scale}. -@end table - - Some graphical applications use @kbd{Mouse-3} for a mode-specific -menu. If you prefer @kbd{Mouse-3} in Emacs to bring up such a menu -instead of running the @code{mouse-save-then-kill} command, rebind -@kbd{Mouse-3} by adding the following line to your init file -(@pxref{Init Rebinding}): - -@smallexample -(global-set-key [mouse-3] 'mouse-popup-menubar-stuff) -@end smallexample - -@node Mode Line Mouse -@section Mode Line Mouse Commands -@cindex mode line, mouse -@cindex mouse on mode line - - You can use mouse clicks on window mode lines to select and manipulate -windows. - - Some areas of the mode line, such as the buffer name, and major and minor -mode names, have their own special mouse bindings. These areas are -highlighted when you hold the mouse over them, and information about -the special bindings will be displayed (@pxref{Tooltips}). This -section's commands do not apply in those areas. - -@table @kbd -@item Mouse-1 -@kindex Mouse-1 @r{(mode line)} -@kbd{Mouse-1} on a mode line selects the window it belongs to. By -dragging @kbd{Mouse-1} on the mode line, you can move it, thus -changing the height of the windows above and below. Changing heights -with the mouse in this way never deletes windows, it just refuses to -make any window smaller than the minimum height. - -@item Mouse-2 -@kindex Mouse-2 @r{(mode line)} -@kbd{Mouse-2} on a mode line expands that window to fill its frame. - -@item Mouse-3 -@kindex Mouse-3 @r{(mode line)} -@kbd{Mouse-3} on a mode line deletes the window it belongs to. If the -frame has only one window, it does nothing. - -@item C-Mouse-2 -@kindex C-mouse-2 @r{(mode line)} -@kbd{C-Mouse-2} on a mode line splits that window, producing two -side-by-side windows with the boundary running through the click -position (@pxref{Split Window}). -@end table - -@kindex Mouse-1 @r{(scroll bar)} - Furthermore, by clicking and dragging @kbd{Mouse-1} on the divider -between two side-by-side mode lines, you can move the vertical -boundary to the left or right. - -@node Creating Frames -@section Creating Frames -@cindex creating frames - -@kindex C-x 5 - The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}. Whereas -each @kbd{C-x 4} command pops up a buffer in a different window in the -selected frame (@pxref{Pop Up Window}), the @kbd{C-x 5} commands use a -different frame. If an existing visible or iconified (``minimized'') -frame already displays the requested buffer, that frame is raised and -deiconified (``un-minimized''); otherwise, a new frame is created on -the current display terminal. - - The various @kbd{C-x 5} commands differ in how they find or create the -buffer to select: - -@table @kbd -@item C-x 5 2 -@kindex C-x 5 2 -@findex make-frame-command -Create a new frame (@code{make-frame-command}). -@item C-x 5 b @var{bufname} @key{RET} -Select buffer @var{bufname} in another frame. This runs -@code{switch-to-buffer-other-frame}. -@item C-x 5 f @var{filename} @key{RET} -Visit file @var{filename} and select its buffer in another frame. This -runs @code{find-file-other-frame}. @xref{Visiting}. -@item C-x 5 d @var{directory} @key{RET} -Select a Dired buffer for directory @var{directory} in another frame. -This runs @code{dired-other-frame}. @xref{Dired}. -@item C-x 5 m -Start composing a mail message in another frame. This runs -@code{mail-other-frame}. It is the other-frame variant of @kbd{C-x m}. -@xref{Sending Mail}. -@item C-x 5 . -Find a tag in the current tag table in another frame. This runs -@code{find-tag-other-frame}, the multiple-frame variant of @kbd{M-.}. -@xref{Tags}. -@item C-x 5 r @var{filename} @key{RET} -@kindex C-x 5 r -@findex find-file-read-only-other-frame -Visit file @var{filename} read-only, and select its buffer in another -frame. This runs @code{find-file-read-only-other-frame}. -@xref{Visiting}. -@end table - - You can control the appearance and behavior of the newly-created -frames by specifying @dfn{frame parameters}. @xref{Frame Parameters}. - -@node Frame Commands -@section Frame Commands - - The following commands are used to delete and operate on frames: - -@table @kbd -@item C-x 5 0 -@kindex C-x 5 0 -@findex delete-frame -Delete the selected frame (@code{delete-frame}). This signals an -error if there is only one frame. - -@item C-z -@kindex C-z @r{(X windows)} -@findex suspend-frame -Minimize (or ``iconify) the selected Emacs frame -(@code{suspend-frame}). @xref{Exiting}. - -@item C-x 5 o -@kindex C-x 5 o -@findex other-frame -Select another frame, and raise it. If you repeat this command, it -cycles through all the frames on your terminal. - -@item C-x 5 1 -@kindex C-x 5 1 -@findex delete-other-frames -Delete all frames on the current terminal, except the selected one. -@end table - - The @kbd{C-x 5 0} (@code{delete-frame}) command deletes the selected -frame. However, it will refuse to delete the last frame in an Emacs -session, to prevent you from losing the ability to interact with the -Emacs session. Note that when Emacs is run as a daemon (@pxref{Emacs -Server}), there is always a ``virtual frame'' that remains after all -the ordinary, interactive frames are deleted. In this case, @kbd{C-x -5 0} can delete the last interactive frame; you can use -@command{emacsclient} to reconnect to the Emacs session. - - The @kbd{C-x 5 1} (@code{delete-other-frames}) command deletes all -other frames on the current terminal (this terminal refers to either a -graphical display, or a text terminal; @pxref{Non-Window Terminals}). -If the Emacs session has frames open on other graphical displays or -text terminals, those are not deleted. - -@vindex focus-follows-mouse - The @kbd{C-x 5 o} (@code{other-frame}) command selects the next -frame on the current terminal. If you are using Emacs on the X Window -System with a window manager that selects (or @dfn{gives focus to}) -whatever frame the mouse cursor is over, you have to change the -variable @code{focus-follows-mouse} to @code{t} in order for this -command to work properly. Then invoking @kbd{C-x 5 o} will also warp -the mouse cursor to the chosen frame. - -@node Fonts -@section Fonts -@cindex fonts - - By default, Emacs displays text on graphical displays using a -12-point monospace font. There are several different ways to specify -a different font: - -@itemize -@item -Click on @samp{Set Default Font} in the @samp{Options} menu. To save -this for future sessions, click on @samp{Save Options} in the -@samp{Options} menu. - -@item -Add a line to your init file, modifying the variable -@code{default-frame-alist} to specify the @code{font} parameter -(@pxref{Frame Parameters}), like this: - -@example -(add-to-list 'default-frame-alist '(font . "DejaVu Sans Mono-10")) -@end example - -@cindex X defaults file -@cindex X resources file -@item -Add an @samp{emacs.font} X resource setting to your X resource file, -like this: - -@example -emacs.font: DejaVu Sans Mono-12 -@end example - -@noindent -You must restart X, or use the @command{xrdb} command, for the X -resources file to take effect. @xref{Resources}. Do not quote -font names in X resource files. - -@item -If you are running Emacs on the GNOME desktop, you can tell Emacs to -use the default system font by setting the variable -@code{font-use-system-font} to @code{t} (the default is @code{nil}). -For this to work, Emacs must have been compiled with Gconf support. - -@item -Use the command line option @samp{-fn} (or @samp{--font}). @xref{Font -X}. -@end itemize - - To check what font you're currently using, the @kbd{C-u C-x =} -command can be helpful. It describes the character at point, and -names the font that it's rendered in. - -@cindex fontconfig - On X, there are four different ways to express a ``font name''. The -first is to use a @dfn{Fontconfig pattern}. Fontconfig patterns have -the following form: - -@example -@var{fontname}[-@var{fontsize}][:@var{name1}=@var{values1}][:@var{name2}=@var{values2}]... -@end example - -@noindent -Within this format, any of the elements in braces may be omitted. -Here, @var{fontname} is the @dfn{family name} of the font, such as -@samp{Monospace} or @samp{DejaVu Sans Mono}; @var{fontsize} is the -@dfn{point size} of the font (one @dfn{printer's point} is about 1/72 -of an inch); and the @samp{@var{name}=@var{values}} entries specify -settings such as the slant and weight of the font. Each @var{values} -may be a single value, or a list of values separated by commas. In -addition, some property values are valid with only one kind of -property name, in which case the @samp{@var{name}=} part may be -omitted. - -Here is a list of common font properties: - -@table @samp -@item slant -One of @samp{italic}, @samp{oblique}, or @samp{roman}. - -@item weight -One of @samp{light}, @samp{medium}, @samp{demibold}, @samp{bold} or -@samp{black}. - -@item style -Some fonts define special styles which are a combination of slant and -weight. For instance, @samp{Dejavu Sans} defines the @samp{book} -style, which overrides the slant and weight properties. - -@item width -One of @samp{condensed}, @samp{normal}, or @samp{expanded}. - -@item spacing -One of @samp{monospace}, @samp{proportional}, @samp{dual-width}, or -@samp{charcell}. -@end table - -@noindent -Here are some examples of Fontconfig patterns: - -@example -Monospace -Monospace-12 -Monospace-12:bold -DejaVu Sans Mono:bold:italic -Monospace-12:weight=bold:slant=italic -@end example - -For a more detailed description of Fontconfig patterns, see the -Fontconfig manual, which is distributed with Fontconfig and available -online at @url{http://fontconfig.org/fontconfig-user.html}. - -@cindex GTK font pattern - The second way to specify a font is to use a @dfn{GTK font pattern}. -These have the syntax - -@example -@var{fontname} [@var{properties}] [@var{fontsize}] -@end example - -@noindent -where @var{fontname} is the family name, @var{properties} is a list of -property values separated by spaces, and @var{fontsize} is the point -size. The properties that you may specify for GTK font patterns are -as follows: - -@itemize -@item -Slant properties: @samp{Italic} or @samp{Oblique}. If omitted, the -default (roman) slant is implied. -@item -Weight properties: @samp{Bold}, @samp{Book}, @samp{Light}, -@samp{Medium}, @samp{Semi-bold}, or @samp{Ultra-light}. If omitted, -@samp{Medium} weight is implied. -@item -Width properties: @samp{Semi-Condensed} or @samp{Condensed}. If -omitted, a default width is used. -@end itemize - -@noindent -Here are some examples of GTK font patterns: - -@example -Monospace 12 -Monospace Bold Italic 12 -@end example - -@cindex XLFD -@cindex X Logical Font Description - The third way to specify a font is to use an @dfn{XLFD} (@dfn{X -Logical Font Description}). This is the traditional method for -specifying fonts under X. Each XLFD consists of fourteen words or -numbers, separated by dashes, like this: - -@example --misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 -@end example - -@noindent -A wildcard character (@samp{*}) in an XLFD matches any sequence of -characters (including none), and @samp{?} matches any single -character. However, matching is implementation-dependent, and can be -inaccurate when wildcards match dashes in a long name. For reliable -results, supply all 14 dashes and use wildcards only within a field. -Case is insignificant in an XLFD. The syntax for an XLFD is as -follows: - -@example --@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{} -@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{registry}-@var{encoding} -@end example - -@noindent -The entries have the following meanings: - -@table @var -@item maker -The name of the font manufacturer. -@item family -The name of the font family (e.g.@: @samp{courier}). -@item weight -The font weight---normally either @samp{bold}, @samp{medium} or -@samp{light}. Some font names support other values. -@item slant -The font slant---normally @samp{r} (roman), @samp{i} (italic), -@samp{o} (oblique), @samp{ri} (reverse italic), or @samp{ot} (other). -Some font names support other values. -@item widthtype -The font width---normally @samp{normal}, @samp{condensed}, -@samp{semicondensed}, or @samp{extended}. Some font names support -other values. -@item style -An optional additional style name. Usually it is empty---most XLFDs -have two hyphens in a row at this point. -@item pixels -The font height, in pixels. -@item height -The font height on the screen, measured in tenths of a printer's -point. This is the point size of the font, times ten. For a given -vertical resolution, @var{height} and @var{pixels} are proportional; -therefore, it is common to specify just one of them and use @samp{*} -for the other. -@item horiz -The horizontal resolution, in pixels per inch, of the screen for which -the font is intended. -@item vert -The vertical resolution, in pixels per inch, of the screen for which -the font is intended. Normally the resolution of the fonts on your -system is the right value for your screen; therefore, you normally -specify @samp{*} for this and @var{horiz}. -@item spacing -This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c} -(character cell). -@item width -The average character width, in pixels, multiplied by ten. -@item registry -@itemx encoding -The X font character set that the font depicts. (X font character -sets are not the same as Emacs character sets, but they are similar.) -You can use the @command{xfontsel} program to check which choices you -have. Normally you should use @samp{iso8859} for @var{registry} and -@samp{1} for @var{encoding}. -@end table - - The fourth and final method of specifying a font is to use a ``font -nickname''. Certain fonts have shorter nicknames, which you can use -instead of a normal font specification. For instance, @samp{6x13} is -equivalent to - -@example --misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 -@end example - -@cindex client-side fonts -@cindex server-side fonts - On X, Emacs recognizes two types of fonts: @dfn{client-side} fonts, -which are provided by the Xft and Fontconfig libraries, and -@dfn{server-side} fonts, which are provided by the X server itself. -Most client-side fonts support advanced font features such as -antialiasing and subpixel hinting, while server-side fonts do not. -Fontconfig and GTK patterns match only client-side fonts. - -@cindex listing system fonts - You will probably want to use a fixed-width default font---that is, -a font in which all characters have the same width. For Xft and -Fontconfig fonts, you can use the @command{fc-list} command to list -the available fixed-width fonts, like this: - -@example -fc-list :spacing=mono fc-list :spacing=charcell -@end example - -@noindent -For server-side X fonts, you can use the @command{xlsfonts} program to -list the available fixed-width fonts, like this: - -@example -xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+" -xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*' -xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*' -@end example - -@noindent -Any font with @samp{m} or @samp{c} in the @var{spacing} field of the -XLFD is a fixed-width font. To see what a particular font looks like, -use the @command{xfd} command. For example: - -@example -xfd -fn 6x13 -@end example - -@noindent -displays the entire font @samp{6x13}. - - While running Emacs, you can also set the font of a specific kind of -text (@pxref{Faces}), or a particular frame (@pxref{Frame -Parameters}). - -@node Speedbar -@section Speedbar Frames -@cindex speedbar - -@cindex attached frame (of speedbar) - The @dfn{speedbar} is a special frame for conveniently navigating in -or operating on another frame. The speedbar, when it exists, is -always associated with a specific frame, called its @dfn{attached -frame}; all speedbar operations act on that frame. - - Type @kbd{M-x speedbar} to create the speedbar and associate it with -the current frame. To dismiss the speedbar, type @kbd{M-x speedbar} -again, or select the speedbar and type @kbd{q}. (You can also delete -the speedbar frame like any other Emacs frame.) If you wish to -associate the speedbar with a different frame, dismiss it and call -@kbd{M-x speedbar} from that frame. - - The speedbar can operate in various modes. Its default mode is -@dfn{File Display} mode, which shows the files in the current -directory of the selected window of the attached frame, one file per -line. Clicking on a file name visits that file in the selected window -of the attached frame, and clicking on a directory name shows that -directory in the speedbar (@pxref{Mouse References}). Each line also -has a box, @samp{[+]} or @samp{<+>}, that you can click on to -@dfn{expand} the contents of that item. Expanding a directory adds -the contents of that directory to the speedbar display, underneath the -directory's own line. Expanding an ordinary file adds a list of the -tags in that file to the speedbar display; you can click on a tag name -to jump to that tag in the selected window of the attached frame. -When a file or directory is expanded, the @samp{[+]} changes to -@samp{[-]}; you can click on that box to @dfn{contract} the item, -hiding its contents. - - You navigate through the speedbar using the keyboard, too. Typing -@kbd{RET} while point is on a line in the speedbar is equivalent to -clicking the item on the current line, and @kbd{SPC} expands or -contracts the item. @kbd{U} displays the parent directory of the -current directory. To copy, delete, or rename the file on the current -line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively. To create a -new directory, type @kbd{M}. - - Another general-purpose speedbar mode is @dfn{Buffer Display} mode; -in this mode, the speedbar displays a list of Emacs buffers. To -switch to this mode, type @kbd{b} in the speedbar. To return to File -Display mode, type @kbd{f}. You can also change the display mode by -clicking @kbd{mouse-3} anywhere in the speedbar window (or -@kbd{mouse-1} on the mode-line) and selecting @samp{Displays} in the -pop-up menu. - - Some major modes, including Rmail mode, Info, and GUD, have -specialized ways of putting useful items into the speedbar for you to -select. For example, in Rmail mode, the speedbar shows a list of Rmail -files, and lets you move the current message to another Rmail file by -clicking on its @samp{} box. - - For more details on using and programming the speedbar, @xref{Top, -Speedbar,,speedbar, Speedbar Manual}. - -@node Multiple Displays -@section Multiple Displays -@cindex multiple displays - - A single Emacs can talk to more than one X display. Initially, Emacs -uses just one display---the one specified with the @env{DISPLAY} -environment variable or with the @samp{--display} option (@pxref{Initial -Options}). To connect to another display, use the command -@code{make-frame-on-display}: - -@findex make-frame-on-display -@table @kbd -@item M-x make-frame-on-display @key{RET} @var{display} @key{RET} -Create a new frame on display @var{display}. -@end table - - A single X server can handle more than one screen. When you open -frames on two screens belonging to one server, Emacs knows they share a -single keyboard, and it treats all the commands arriving from these -screens as a single stream of input. - - When you open frames on different X servers, Emacs makes a separate -input stream for each server. Each server also has its own selected -frame. The commands you enter with a particular X server apply to -that server's selected frame. - -@node Frame Parameters -@section Frame Parameters -@cindex default-frame-alist - - You can control the default appearance and behavior of all frames by -specifying a default list of @dfn{frame parameters} in the variable -@code{default-frame-alist}. Its value should be a list of entries, -each specifying a parameter name and a value for that parameter. -These entries take effect whenever Emacs creates a new frame, -including the initial frame. - -@cindex frame size, specifying default - For example, you can add the following lines to your init file -(@pxref{Init File}) to set the default frame width to 90 character -columns, the default frame height to 40 character rows, and the -default font to @samp{Monospace-10}: - -@example -(add-to-list 'default-frame-alist '(width . 90)) -(add-to-list 'default-frame-alist '(height . 40)) -(add-to-list 'default-frame-alist '(font . "Monospace-10")) -@end example - - For a list of frame parameters and their effects, see @ref{Frame -Parameters,,, elisp, The Emacs Lisp Reference Manual}. - -@cindex initial-frame-alist - You can also specify a list of frame parameters which apply to just -the initial frame, by customizing the variable -@code{initial-frame-alist}. - - If Emacs is compiled to use an X toolkit, frame parameters that -specify colors and fonts don't affect menus and the menu bar, since -those are drawn by the toolkit and not directly by Emacs. - -@node Scroll Bars -@section Scroll Bars -@cindex Scroll Bar mode -@cindex mode, Scroll Bar - - On graphical displays, there is a @dfn{scroll bar} on the side of -each Emacs window. Clicking @kbd{Mouse-1} on the scroll bar's up and -down buttons scrolls the window by one line at a time. Clicking -@kbd{Mouse-1} above or below the scroll bar's inner box scrolls the -window by nearly the entire height of the window, like @kbd{M-v} and -@kbd{C-v} respectively (@pxref{Moving Point}). Dragging the inner box -scrolls continuously. - - If Emacs is compiled on the X Window System without X toolkit -support, the scroll bar behaves differently. Clicking @kbd{Mouse-1} -anywhere on the scroll bar scrolls forward like @kbd{C-v}, while -@kbd{Mouse-3} scrolls backward like @kbd{M-v}. Clicking @kbd{Mouse-2} -in the scroll bar lets you drag the inner box up and down. - -@findex scroll-bar-mode -@findex toggle-scroll-bar - To toggle the use of scroll bars, type @kbd{M-x scroll-bar-mode}. -This command applies to all frames, including frames yet to be -created. To toggle scroll bars for just the selected frame, use the -command @kbd{M-x toggle-scroll-bar}. - -@vindex scroll-bar-mode - To control the use of scroll bars at startup, customize the variable -@code{scroll-bar-mode}. Its value should be either @code{right} (put -scroll bars on the right side of windows), @code{left} (put them on -the left), or @code{nil} (disable scroll bars). By default, Emacs -puts scroll bars on the right if it was compiled with GTK+ support on -the X Window System, and on MS-Windows or Mac OS; Emacs puts scroll -bars on the left if compiled on the X Window System without GTK+ -support (following the old convention for X applications). - -@vindex scroll-bar-width -@cindex width of the scroll bar - You can also use the X resource @samp{verticalScrollBars} to enable -or disable the scroll bars (@pxref{Resources}). To control the scroll -bar width, change the @code{scroll-bar-width} frame parameter -(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}). - -@node Drag and Drop -@section Drag and Drop -@cindex drag and drop - - In most graphical desktop environments, Emacs has basic support for -@dfn{drag and drop} operations. For instance, dropping text onto an -Emacs frame inserts the text where it is dropped. Dropping a file -onto an Emacs frame visits that file. As a special case, dropping the -file on a Dired buffer moves or copies the file (according to the -conventions of the application it came from) into the directory -displayed in that buffer. - -@vindex dnd-open-file-other-window - Dropping a file normally visits it in the window you drop it on. If -you prefer to visit the file in a new window in such cases, customize -the variable @code{dnd-open-file-other-window}. - - The XDND and Motif drag and drop protocols, and the old KDE 1.x -protocol, are currently supported. - -@node Menu Bars -@section Menu Bars -@cindex Menu Bar mode -@cindex mode, Menu Bar -@findex menu-bar-mode -@vindex menu-bar-mode - - You can toggle the use of menu bars with @kbd{M-x menu-bar-mode}. -With no argument, this command toggles Menu Bar mode, a global minor -mode. With an argument, the command turns Menu Bar mode on if the -argument is positive, off if the argument is not positive. To control -the use of menu bars at startup, customize the variable -@code{menu-bar-mode}. - -@kindex C-Mouse-3 @r{(when menu bar is disabled)} - Expert users often turn off the menu bar, especially on text -terminals, where this makes one additional line available for text. -If the menu bar is off, you can still pop up a menu of its contents -with @kbd{C-Mouse-3} on a display which supports pop-up menus. -@xref{Menu Mouse Clicks}. - - @xref{Menu Bar}, for information on how to invoke commands with the -menu bar. @xref{X Resources}, for how to customize the menu bar -menus' visual appearance. - -@node Tool Bars -@section Tool Bars -@cindex Tool Bar mode -@cindex mode, Tool Bar -@cindex icons, toolbar - - On graphical displays, Emacs puts a @dfn{tool bar} at the top of -each frame, just below the menu bar. This is a row of icons which you -can click on with the mouse to invoke various commands. - - The global (default) tool bar contains general commands. Some major -modes define their own tool bars; whenever a buffer with such a major -mode is current, the mode's tool bar replaces the global tool bar. - -@findex tool-bar-mode -@vindex tool-bar-mode - To toggle the use of tool bars, type @kbd{M-x tool-bar-mode}. This -command applies to all frames, including frames yet to be created. To -control the use of tool bars at startup, customize the variable -@code{tool-bar-mode}. - -@vindex tool-bar-style -@cindex Tool Bar style - When Emacs is compiled with GTK+ support, each tool bar item can -consist of an image, or a text label, or both. By default, Emacs -follows the Gnome desktop's tool bar style setting; if none is -defined, it displays tool bar items as just images. To impose a -specific tool bar style, customize the variable @code{tool-bar-style}. - -@cindex Tool Bar position - You can also control the placement of the tool bar for the GTK+ tool -bar with the frame parameter @code{tool-bar-position}. @xref{Frame -Parameters,,, elisp, The Emacs Lisp Reference Manual}. - -@node Dialog Boxes -@section Using Dialog Boxes -@cindex dialog boxes - -@vindex use-dialog-box - A dialog box is a special kind of menu for asking you a yes-or-no -question or some other special question. Many Emacs commands use a -dialog box to ask a yes-or-no question, if you used the mouse to -invoke the command that led to the question. - - To disable the use of dialog boxes, change the variable -@code{use-dialog-box} to @code{nil}. In that case, Emacs always -performs yes-or-no prompts using the echo area and keyboard input. -This variable also controls whether to use file selection windows (but -those are not supported on all platforms). - -@vindex use-file-dialog -@cindex file selection dialog, how to disable - A file selection window is a special kind of dialog box for asking -for file names. You can customize the variable @code{use-file-dialog} -to suppress the use of file selection windows, even if you still want -other kinds of dialogs. This variable has no effect if you have -suppressed all dialog boxes with the variable @code{use-dialog-box}. - -@vindex x-gtk-show-hidden-files -@vindex x-gtk-file-dialog-help-text -@cindex hidden files, in GTK+ file chooser -@cindex help text, in GTK+ file chooser - When Emacs is compiled with GTK+ support, it uses the GTK+ ``file -chooser'' dialog. Emacs adds an additional toggle button to this -dialog, which you can use to enable or disable the display of hidden -files (files starting with a dot) in that dialog. If you want this -toggle to be activated by default, change the variable -@code{x-gtk-show-hidden-files} to @code{t}. In addition, Emacs adds -help text to the GTK+ file chooser dialog; to disable this help text, -change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}. - -@node Tooltips -@section Tooltips -@cindex tooltips - - @dfn{Tooltips} are small windows that display text information at -the current mouse position. They activate when there is a pause in -mouse movement over some significant piece of text in a window, or the -mode line, or some other part of the Emacs frame such as a tool bar -button or menu item. - -@findex tooltip-mode - You can toggle the use of tooltips with the command @kbd{M-x -tooltip-mode}. When Tooltip mode is disabled, the help text is -displayed in the echo area instead. To control the use of tooltips at -startup, customize the variable @code{tooltip-mode}. - -@vindex tooltip-delay - The variables @code{tooltip-delay} specifies how long Emacs should -wait before displaying a tooltip. For additional customization -options for displaying tooltips, use @kbd{M-x customize-group -@key{RET} tooltip @key{RET}}. - -@vindex x-gtk-use-system-tooltips - If Emacs is built with GTK+ support, it displays tooltips via GTK+, -using the default appearance of GTK+ tooltips. To disable this, -change the variable @code{x-gtk-use-system-tooltips} to @code{nil}. -If you do this, or if Emacs is built without GTK+ support, most -attributes of the tooltip text are specified by the @code{tooltip} -face, and by X resources (@pxref{X Resources}). - - @dfn{GUD tooltips} are special tooltips that show the values of -variables when debugging a program with GUD. @xref{Debugger -Operation}. - -@node Mouse Avoidance -@section Mouse Avoidance -@cindex avoiding mouse in the way of your typing -@cindex mouse avoidance - - On graphical terminals, the mouse pointer may obscure the text in -the Emacs frame. Emacs provides two methods to avoid this problem. - -@vindex make-pointer-invisible - Firstly, Emacs hides the mouse pointer each time you type a -self-inserting character, if the pointer lies inside an Emacs frame; -moving the mouse pointer makes it visible again. To disable this -feature, set the variable @code{make-pointer-invisible} to @code{nil}. - -@vindex mouse-avoidance-mode - Secondly, you can use Mouse Avoidance mode, a minor mode, to keep -the mouse pointer away from point. To use Mouse Avoidance mode, -customize the variable @code{mouse-avoidance-mode}. You can set this -to various values to move the mouse in several ways: - -@table @code -@item banish -Move the mouse to the upper-right corner on any key-press; -@item exile -Move the mouse to the corner only if the cursor gets too close, -and allow it to return once the cursor is out of the way; -@item jump -If the cursor gets too close to the mouse, displace the mouse -a random distance & direction; -@item animate -As @code{jump}, but shows steps along the way for illusion of motion; -@item cat-and-mouse -The same as @code{animate}; -@item proteus -As @code{animate}, but changes the shape of the mouse pointer too. -@end table - -@findex mouse-avoidance-mode -You can also use the command @kbd{M-x mouse-avoidance-mode} to enable -the mode. Whenever Mouse Avoidance mode moves the mouse, it also -raises the frame. - -@node Non-Window Terminals -@section Non-Window Terminals -@cindex text terminal - - On a text terminal, Emacs can display only one Emacs frame at a -time. However, you can still create multiple Emacs frames, and switch -between them. Switching frames on these terminals is much like -switching between different window configurations. - - Use @kbd{C-x 5 2} to create a new frame and switch to it; use @kbd{C-x -5 o} to cycle through the existing frames; use @kbd{C-x 5 0} to delete -the current frame. - - Each frame has a number to distinguish it. If your terminal can -display only one frame at a time, the selected frame's number @var{n} -appears near the beginning of the mode line, in the form -@samp{F@var{n}}. - -@findex set-frame-name -@findex select-frame-by-name - @samp{F@var{n}} is in fact the frame's initial name. You can give -frames more meaningful names if you wish, and you can select a frame -by its name. Use the command @kbd{M-x set-frame-name @key{RET} -@var{name} @key{RET}} to specify a new name for the selected frame, -and use @kbd{M-x select-frame-by-name @key{RET} @var{name} @key{RET}} -to select a frame according to its name. The name you specify appears -in the mode line when the frame is selected. - -@node Text-Only Mouse -@section Using a Mouse in Text Terminals -@cindex mouse support -@cindex terminal emulators, mouse support - -Some text terminals support mouse clicks in the terminal window. - -@cindex xterm - In a terminal emulator which is compatible with @command{xterm}, you -can use @kbd{M-x xterm-mouse-mode} to give Emacs control over simple -uses of the mouse---basically, only non-modified single clicks are -supported. The normal @command{xterm} mouse functionality for such -clicks is still available by holding down the @kbd{SHIFT} key when you -press the mouse button. Xterm Mouse mode is a global minor mode -(@pxref{Minor Modes}). Repeating the command turns the mode off -again. - -@findex gpm-mouse-mode - In the console on GNU/Linux, you can use @kbd{M-x gpm-mouse-mode} to -enable mouse support. You must have the gpm server installed and -running on your system in order for this to work. - -@iftex -@xref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{MS-DOS Mouse}, -@end ifnottex -for information about mouse support on MS-DOS. diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi deleted file mode 100644 index 44c59eea668..00000000000 --- a/doc/emacs/glossary.texi +++ /dev/null @@ -1,1457 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Glossary, Key Index, Intro, Top -@unnumbered Glossary - -@table @asis -@anchor{Glossary - Abbrev} -@item Abbrev -An abbrev is a text string that expands into a different text string -when present in the buffer. For example, you might define a few letters -as an abbrev for a long phrase that you want to insert frequently. -@xref{Abbrevs}. - -@item Aborting -Aborting means getting out of a recursive edit (q.v.@:). The -commands @kbd{C-]} and @kbd{M-x top-level} are used for this. -@xref{Quitting}. - -@c FIXME? Active Region - -@item Alt -Alt is the name of a modifier bit that a keyboard input character may -have. To make a character Alt, type it while holding down the @key{ALT} -key. Such characters are given names that start with @kbd{Alt-} -(usually written @kbd{A-} for short). (Note that many terminals have a -key labeled @key{ALT} that is really a @key{META} key.) @xref{User -Input, Alt}. - -@item Argument -@xref{Glossary - Numeric Argument}. - -@item @acronym{ASCII} character -An @acronym{ASCII} character is either an @acronym{ASCII} control -character or an @acronym{ASCII} printing character. @xref{User Input}. - -@item @acronym{ASCII} control character -An @acronym{ASCII} control character is the Control version of an upper-case -letter, or the Control version of one of the characters @samp{@@[\]^_?}. - -@item @acronym{ASCII} printing character -@acronym{ASCII} printing characters include letters, digits, space, and these -punctuation characters: @samp{!@@#$%^&*()_-+=|\~`@{@}[]:;"'<>,.?/}. - -@item Auto Fill Mode -Auto Fill mode is a minor mode (q.v.@:) in which text that you insert is -automatically broken into lines of a given maximum width. -@xref{Filling}. - -@item Auto Saving -Auto saving is the practice of periodically saving the contents of an -Emacs buffer in a specially-named file, so that the information will -be preserved if the buffer is lost due to a system error or user error. -@xref{Auto Save}. - -@item Autoloading -Emacs can automatically load Lisp libraries when a Lisp program requests a -function from those libraries. This is called `autoloading'. -@xref{Lisp Libraries}. - -@item Backtrace -A backtrace is a trace of a series of function calls showing how a -program arrived at a certain point. It is used mainly for finding and -correcting bugs (q.v.@:). Emacs can display a backtrace when it signals -an error or when you type @kbd{C-g} (@pxref{Glossary - Quitting}). -@xref{Checklist}. - -@item Backup File -A backup file records the contents that a file had before the current -editing session. Emacs makes backup files automatically to help you -track down or cancel changes you later regret making. @xref{Backup}. - -@item Balancing Parentheses -Emacs can balance parentheses (or other matching delimiters) either -manually or automatically. You do manual balancing with the commands -to move over parenthetical groupings (@pxref{Moving by Parens}). -Automatic balancing works by blinking or highlighting the delimiter -that matches the one you just inserted, or inserting the matching -delimiter for you (@pxref{Matching,,Matching Parens}). - -@anchor{Glossary - Balanced Expression} -@item Balanced Expressions -A balanced expression is a syntactically recognizable expression, such -as a symbol, number, string constant, block, or parenthesized expression -in C. @xref{Expressions,Balanced Expressions}. - -@item Balloon Help -@xref{Glossary - Tooltips}. - -@item Base Buffer -A base buffer is a buffer whose text is shared by an indirect buffer -(q.v.@:). - -@item Bidirectional Text -Some human languages, such as English, are written from left to right. -Others, such as Arabic, are written from right to left. Emacs -supports both of these forms, as well as any mixture of them---this -is `bidirectional text'. @xref{Bidirectional Editing}. - -@item Bind -To bind a key sequence means to give it a binding (q.v.@:). -@xref{Rebinding}. - -@anchor{Glossary - Binding} -@item Binding -A key sequence gets its meaning in Emacs by having a binding, which is a -command (q.v.@:), a Lisp function that is run when you type that -sequence. @xref{Commands,Binding}. Customization often involves -rebinding a character to a different command function. The bindings of -all key sequences are recorded in the keymaps (q.v.@:). @xref{Keymaps}. - -@item Blank Lines -Blank lines are lines that contain only whitespace. Emacs has several -commands for operating on the blank lines in the buffer. @xref{Blank Lines}. - -@item Bookmark -Bookmarks are akin to registers (q.v.@:) in that they record positions -in buffers to which you can return later. Unlike registers, bookmarks -persist between Emacs sessions. @xref{Bookmarks}. - -@item Border -A border is a thin space along the edge of the frame, used just for -spacing, not for displaying anything. An Emacs frame has an ordinary -external border, outside of everything including the menu bar, plus an -internal border that surrounds the text windows, their scroll bars -and fringes, and separates them from the menu bar and tool bar. You -can customize both borders with options and resources (@pxref{Borders -X}). Borders are not the same as fringes (q.v.@:). - -@item Buffer -The buffer is the basic editing unit; one buffer corresponds to one text -being edited. You normally have several buffers, but at any time you are -editing only one, the `current buffer', though several can be visible -when you are using multiple windows or frames (q.v.@:). Most buffers -are visiting (q.v.@:) some file. @xref{Buffers}. - -@item Buffer Selection History -Emacs keeps a buffer selection history that records how recently each -Emacs buffer has been selected. This is used for choosing a buffer to -select. @xref{Buffers}. - -@item Bug -A bug is an incorrect or unreasonable behavior of a program, or -inaccurate or confusing documentation. Emacs developers treat bug -reports, both in Emacs code and its documentation, very seriously and -ask you to report any bugs you find. @xref{Bugs}. - -@item Button Down Event -A button down event is the kind of input event (q.v.@:) generated -right away when you press down on a mouse button. @xref{Mouse Buttons}. - -@item By Default -@xref{Glossary - Default}. - -@item Byte Compilation -@xref{Glossary - Compilation}. - -@anchor{Glossary - C-} -@item @kbd{C-} -@kbd{C-} in the name of a character is an abbreviation for Control. -@xref{User Input,C-}. - -@item @kbd{C-M-} -@kbd{C-M-} in the name of a character is an abbreviation for -Control-Meta. If your terminal lacks a real @key{META} key, you type -a Control-Meta character by typing @key{ESC} and then typing the -corresponding Control character. @xref{User Input,C-M-}. - -@item Case Conversion -Case conversion means changing text from upper case to lower case or -vice versa. @xref{Case}. - -@item Character -Characters form the contents of an Emacs buffer. Also, key sequences -(q.v.@:) are usually made up of characters (though they may include -other input events as well). @xref{User Input}. - -@item Character Set -Emacs supports a number of character sets, each of which represents a -particular alphabet or script. @xref{International}. - -@item Character Terminal -@xref{Glossary - Text Terminal}. - -@item Click Event -A click event is the kind of input event (q.v.@:) generated when you -press a mouse button and release it without moving the mouse. -@xref{Mouse Buttons}. - -@item Client -@xref{Glossary - Server}. - -@item Clipboard -A clipboard is a buffer provided by the window system for transferring -text between applications. On the X Window System, the clipboard is -provided in addition to the primary selection (q.v.@:); on MS-Windows and Mac, -the clipboard is used @emph{instead} of the primary selection. -@xref{Clipboard}. - -@item Coding System -A coding system is an encoding for representing text characters in a -file or in a stream of information. Emacs has the ability to convert -text to or from a variety of coding systems when reading or writing it. -@xref{Coding Systems}. - -@item Command -A command is a Lisp function specially defined to be able to serve as a -key binding in Emacs. When you type a key sequence (q.v.@:), its -binding (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find -the command to run. @xref{Commands}. - -@item Command History -@xref{Glossary - Minibuffer History}. - -@item Command Name -A command name is the name of a Lisp symbol that is a command -(@pxref{Commands}). You can invoke any command by its name using -@kbd{M-x} (@pxref{M-x,M-x,Running Commands by Name}). - -@item Comment -A comment is text in a program which is intended only for humans reading -the program, and which is specially marked so that it will be ignored -when the program is loaded or compiled. Emacs offers special commands -for creating, aligning and killing comments. @xref{Comments}. - -@item Common Lisp -Common Lisp is a dialect of Lisp (q.v.@:) much larger and more powerful -than Emacs Lisp. Emacs provides a subset of Common Lisp in the CL -package. @xref{Top, Common Lisp, Overview, cl, Common Lisp Extensions}. - -@anchor{Glossary - Compilation} -@item Compilation -Compilation is the process of creating an executable program from source -code. Emacs has commands for compiling files of Emacs Lisp code -(@pxref{Byte Compilation,,, elisp, the Emacs Lisp -Reference Manual}) and programs in C and other languages -(@pxref{Compilation}). - -@item Complete Key -A complete key is a key sequence that fully specifies one action to be -performed by Emacs. For example, @kbd{X} and @kbd{C-f} and @kbd{C-x m} -are complete keys. Complete keys derive their meanings from being bound -(q.v.@:) to commands (q.v.@:). Thus, @kbd{X} is conventionally bound to -a command to insert @samp{X} in the buffer; @kbd{C-x m} is -conventionally bound to a command to begin composing a mail message. -@xref{Keys}. - -@item Completion -Completion is what Emacs does when it automatically expands an -abbreviation for a name into the entire name. Completion is done for -minibuffer (q.v.@:) arguments when the set of possible valid inputs -is known; for example, on command names, buffer names, and -file names. Completion usually occurs when @key{TAB}, @key{SPC} or -@key{RET} is typed. @xref{Completion}.@refill - -@anchor{Glossary - Continuation Line} -@item Continuation Line -When a line of text is longer than the width of the window, it -normally (but see @ref{Glossary - Truncation}) takes up more than one -screen line when displayed. We say that the text line is continued, and all -screen lines used for it after the first are called continuation -lines. @xref{Continuation Lines}. A related Emacs feature is -`filling' (q.v.@:). - -@item Control Character -A control character is a character that you type by holding down the -@key{CTRL} key. Some control characters also have their own keys, so -that you can type them without using @key{CTRL}. For example, -@key{RET}, @key{TAB}, @key{ESC} and @key{DEL} are all control -characters. @xref{User Input}. - -@item Copyleft -A copyleft is a notice giving the public legal permission to -redistribute and modify a program or other work of art, but requiring -modified versions to carry similar permission. Copyright is normally -used to keep users divided and helpless; with copyleft we turn that -around to empower users and encourage them to cooperate. - -The particular form of copyleft used by the GNU project is called the -GNU General Public License. @xref{Copying}. - -@item @key{CTRL} -The @key{CTRL} or ``control'' key is what you hold down -in order to enter a control character (q.v.). @xref{Glossary - C-}. - -@item Current Buffer -The current buffer in Emacs is the Emacs buffer on which most editing -commands operate. You can select any Emacs buffer as the current one. -@xref{Buffers}. - -@item Current Line -The current line is the line that point is on (@pxref{Point}). - -@item Current Paragraph -The current paragraph is the paragraph that point is in. If point is -between two paragraphs, the current paragraph is the one that follows -point. @xref{Paragraphs}. - -@item Current Defun -The current defun is the defun (q.v.@:) that point is in. If point is -between defuns, the current defun is the one that follows point. -@xref{Defuns}. - -@item Cursor -The cursor is the rectangle on the screen which indicates the position -(called point; q.v.@:) at which insertion and deletion takes place. -The cursor is on or under the character that follows point. Often -people speak of `the cursor' when, strictly speaking, they mean -`point'. @xref{Point,Cursor}. - -@item Customization -Customization is making minor changes in the way Emacs works, to -reflect your preferences or needs. It is often done by setting -variables (@pxref{Variables}) or faces (@pxref{Face Customization}), -or by rebinding key sequences (@pxref{Keymaps}). - -@cindex cut and paste -@item Cut and Paste -@xref{Glossary - Killing}, and @ref{Glossary - Yanking}. - -@anchor{Glossary - Daemon} -@item Daemon -A daemon is a standard term for a system-level process that runs in the -background. Daemons are often started when the system first starts up. -When Emacs runs in daemon-mode, it runs in the background and does not -open a display. You can then connect to it with the -@command{emacsclient} program. @xref{Emacs Server}. - -@item Default Argument -The default for an argument is the value that will be assumed if you -do not specify one. When the minibuffer is used to read an argument, -the default argument is used if you just type @key{RET}. -@xref{Minibuffer}. - -@anchor{Glossary - Default} -@item Default -A default is the value that is used for a certain purpose when -you do not explicitly specify a value to use. - -@item Default Directory -When you specify a file name that does not start with @samp{/} or @samp{~}, -it is interpreted relative to the current buffer's default directory. -(On MS systems, file names that start with a drive letter -@samp{@var{x}:} are treated as absolute, not relative.) -@xref{Minibuffer File,Default Directory}. - -@item Defun -A defun is a major definition at the top level in a program. The name -`defun' comes from Lisp, where most such definitions use the construct -@code{defun}. @xref{Defuns}. - -@item @key{DEL} -@key{DEL} is a character that runs the command to delete one character -of text before the cursor. It is typically either the @key{DELETE} -key or the @key{BACKSPACE} key, whichever one is easy to type. -@xref{Erasing,DEL}. - -@item Deletion -Deletion means erasing text without copying it into the kill ring -(q.v.@:). The alternative is killing (q.v.@:). @xref{Killing,Deletion}. - -@anchor{Glossary - Deletion of Files} -@item Deletion of Files -Deleting a file means erasing it from the file system. -(Note that some systems use the concept of a ``trash can'', or ``recycle -bin'', to allow you to ``undelete'' files.) -@xref{Misc File Ops,Misc File Ops,Miscellaneous File Operations}. - -@item Deletion of Messages -Deleting a message (in Rmail, and other mail clients) means flagging -it to be eliminated from your mail file. Until you expunge (q.v.@:) -the Rmail file, you can still undelete the messages you have deleted. -@xref{Rmail Deletion}. - -@item Deletion of Windows -Deleting a window means eliminating it from the screen. Other windows -expand to use up the space. The text that was in the window is not -lost, and you can create a new window with the same dimensions as the -old if you wish. @xref{Windows}. - -@item Directory -File directories are named collections in the file system, within which -you can place individual files or subdirectories. They are sometimes -referred to as ``folders''. @xref{Directories}. - -@anchor{Glossary - Directory Local Variable} -@item Directory Local Variable -A directory local variable is a local variable (q.v.@:) that applies -to all the files within a certain directory. @xref{Directory -Variables}. - -@item Dired -Dired is the Emacs facility that displays the contents of a file -directory and allows you to ``edit the directory'', performing -operations on the files in the directory. @xref{Dired}. - -@item Disabled Command -A disabled command is one that you may not run without special -confirmation. The usual reason for disabling a command is that it is -confusing for beginning users. @xref{Disabling}. - -@item Down Event -Short for `button down event' (q.v.@:). - -@item Drag Event -A drag event is the kind of input event (q.v.@:) generated when you -press a mouse button, move the mouse, and then release the button. -@xref{Mouse Buttons}. - -@item Dribble File -A dribble file is a file into which Emacs writes all the characters that -you type on the keyboard. Dribble files can be used to make a record -for debugging Emacs bugs. Emacs does not make a dribble file unless you -tell it to. @xref{Bugs}. - -@c TODO? Not really appropriate for the user manual I think. -@c Dynamic Binding - -@item Echo Area -The echo area is the bottom line of the screen, used for echoing the -arguments to commands, for asking questions, and showing brief messages -(including error messages). The messages are stored in the buffer -@file{*Messages*} so you can review them later. @xref{Echo Area}. - -@item Echoing -Echoing is acknowledging the receipt of input events by displaying -them (in the echo area). Emacs never echoes single-character key -sequences; longer key sequences echo only if you pause while typing -them. - -@item Electric -We say that a character is electric if it is normally self-inserting -(q.v.@:), but the current major mode (q.v.@:) redefines it to do something -else as well. For example, some programming language major modes define -particular delimiter characters to reindent the line, or insert one or -more newlines in addition to self-insertion. - -@anchor{Glossary - End Of Line} -@item End Of Line -End of line is a character or a sequence of characters that indicate -the end of a text line. On GNU and Unix systems, this is a newline -(q.v.@:), but other systems have other conventions. @xref{Coding -Systems,end-of-line}. Emacs can recognize several end-of-line -conventions in files and convert between them. - -@item Environment Variable -An environment variable is one of a collection of variables stored by -the operating system, each one having a name and a value. Emacs can -access environment variables set by its parent shell, and it can set -variables in the environment it passes to programs it invokes. -@xref{Environment}. - -@item EOL -@xref{Glossary - End Of Line}. - -@item Error -An error occurs when an Emacs command cannot execute in the current -circumstances. When an error occurs, execution of the command stops -(unless the command has been programmed to do otherwise) and Emacs -reports the error by displaying an error message (q.v.@:). -@c Not helpful? -@c Type-ahead is discarded. Then Emacs is ready to read another -@c editing command. - -@item Error Message -An error message is output displayed by Emacs when you ask it to do -something impossible (such as, killing text forward when point is at -the end of the buffer), or when a command malfunctions in some way. -Such messages appear in the echo area, accompanied by a beep. - -@item @key{ESC} -@key{ESC} is a character used as a prefix for typing Meta characters on -keyboards lacking a @key{META} key. Unlike the @key{META} key (which, -like the @key{SHIFT} key, is held down while another character is -typed), you press the @key{ESC} key as you would press a letter key, and -it applies to the next character you type. - -@item Expression -@xref{Glossary - Balanced Expression}. - -@item Expunging -Expunging an Rmail, Gnus newsgroup, or Dired buffer is an operation -that truly discards the messages or files you have previously flagged -for deletion. - -@item Face -A face is a style of displaying characters. It specifies attributes -such as font family and size, foreground and background colors, -underline and strike-through, background stipple, etc. Emacs provides -features to associate specific faces with portions of buffer text, in -order to display that text as specified by the face attributes. -@xref{Faces}. - -@item File Local Variable -A file local variable is a local variable (q.v.@:) specified in a -given file. @xref{File Variables}, and @ref{Glossary - Directory -Local Variable}. - -@anchor{Glossary - File Locking} -@item File Locking -Emacs uses file locking to notice when two different users -start to edit one file at the same time. @xref{Interlocking}. - -@item File Name -@c This is fairly tautological... -A file name is a name that refers to a file. File names may be relative -or absolute; the meaning of a relative file name depends on the current -directory, but an absolute file name refers to the same file regardless -of which directory is current. On GNU and Unix systems, an absolute -file name starts with a slash (the root directory) or with @samp{~/} or -@samp{~@var{user}/} (a home directory). On MS-Windows/MS-DOS, an -absolute file name can also start with a drive letter and a colon, e.g. -@samp{@var{d}:}. - -Some people use the term ``pathname'' for file names, but we do not; -we use the word ``path'' only in the term ``search path'' (q.v.@:). - -@item File-Name Component -A file-name component names a file directly within a particular -directory. On GNU and Unix systems, a file name is a sequence of -file-name components, separated by slashes. For example, @file{foo/bar} -is a file name containing two components, @samp{foo} and @samp{bar}; it -refers to the file named @samp{bar} in the directory named @samp{foo} in -the current directory. MS-DOS/MS-Windows file names can also use -backslashes to separate components, as in @file{foo\bar}. - -@item Fill Prefix -The fill prefix is a string that should be expected at the beginning -of each line when filling is done. It is not regarded as part of the -text to be filled. @xref{Filling}. - -@anchor{Glossary - Filling} -@item Filling -Filling text means adjusting the position of line-breaks to shift text -between consecutive lines, so that all the lines are approximately the -same length. @xref{Filling}. Some other editors call this feature -``line wrapping''. - -@anchor{Glossary - Font Lock} -@item Font Lock -Font Lock is a mode that highlights parts of buffer text in different -faces, according to the syntax. Some other editors refer to this as -``syntax highlighting''. For example, all comments (q.v.@:) -might be colored red. @xref{Font Lock}. - -@item Fontset -A fontset is a named collection of fonts. A fontset specification lists -character sets and which font to use to display each of them. Fontsets -make it easy to change several fonts at once by specifying the name of a -fontset, rather than changing each font separately. @xref{Fontsets}. - -@item Formfeed Character -@xref{Glossary - Page}. - -@item Frame -A frame is a rectangular cluster of Emacs windows. Emacs starts out -with one frame, but you can create more. You can subdivide each frame -into Emacs windows (q.v.@:). When you are using a window system -(q.v.@:), more than one frame can be visible at the same time. -@xref{Frames}. Some other editors use the term ``window'' for this, -but in Emacs a window means something else. - -@item Free Software -Free software is software that gives you the freedom to share, study -and modify it. Emacs is free software, part of the GNU project -(q.v.@:), and distributed under a copyleft (q.v.@:) license called the -GNU General Public License. @xref{Copying}. - -@anchor{Glossary - Free Software Foundation} -@item Free Software Foundation -The Free Software Foundation (FSF) is a charitable foundation -dedicated to promoting the development of free software (q.v.@:). -For more information, see @uref{http://fsf.org/, the FSF website}. - -@item Fringe -On a graphical display (q.v.@:), there's a narrow portion of the frame -(q.v.@:) between the text area and the window's border. These -``fringes'' are used to display symbols that provide information about -the buffer text (@pxref{Fringes}). Emacs displays the fringe using a -special face (q.v.@:) called @code{fringe}. @xref{Faces,fringe}. - -@item FSF -@xref{Glossary - Free Software Foundation}. - -@item FTP -FTP is an acronym for File Transfer Protocol. This is one standard -method for retrieving remote files (q.v.@:). - -@item Function Key -A function key is a key on the keyboard that sends input but does not -correspond to any character. @xref{Function Keys}. - -@item Global -Global means ``independent of the current environment; in effect -throughout Emacs''. It is the opposite of local (q.v.@:). Particular -examples of the use of `global' appear below. - -@item Global Abbrev -A global definition of an abbrev (q.v.@:) is effective in all major -modes that do not have local (q.v.@:) definitions for the same abbrev. -@xref{Abbrevs}. - -@item Global Keymap -The global keymap (q.v.@:) contains key bindings that are in effect -everywhere, except when overridden by local key bindings in a major -mode's local keymap (q.v.@:). @xref{Keymaps}. - -@item Global Mark Ring -The global mark ring records the series of buffers you have recently -set a mark (q.v.@:) in. In many cases you can use this to backtrack -through buffers you have been editing, or in which you have found -tags (@pxref{Glossary - Tags Table}). @xref{Global Mark Ring}. - -@anchor{Glossary - Global Substitution} -@item Global Substitution -Global substitution means replacing each occurrence of one string by -another string throughout a large amount of text. @xref{Replace}. - -@item Global Variable -The global value of a variable (q.v.@:) takes effect in all buffers -that do not have their own local (q.v.@:) values for the variable. -@xref{Variables}. - -@item GNU -GNU is a recursive acronym for GNU's Not Unix, and it refers to a -Unix-compatible operating system which is free software (q.v.@:). -@xref{Manifesto}. GNU is normally used with Linux as the kernel since -Linux works better than the GNU kernel. For more information, see -@uref{http://www.gnu.org/, the GNU website}. - -@item Graphic Character -Graphic characters are those assigned pictorial images rather than -just names. All the non-Meta (q.v.@:) characters except for the -Control (q.v.@:) characters are graphic characters. These include -letters, digits, punctuation, and spaces; they do not include -@key{RET} or @key{ESC}. In Emacs, typing a graphic character inserts -that character (in ordinary editing modes). @xref{Inserting Text}. - -@item Graphical Display -A graphical display is one that can display images and multiple fonts. -Usually it also has a window system (q.v.@:). - -@item Highlighting -Highlighting text means displaying it with a different foreground and/or -background color to make it stand out from the rest of the text in the -buffer. - -Emacs uses highlighting in several ways. It highlights the region -whenever it is active (@pxref{Mark}). Incremental search also -highlights matches (@pxref{Incremental Search}). @xref{Glossary - Font Lock}. - -@item Hardcopy -Hardcopy means printed output. Emacs has various commands for -printing the contents of Emacs buffers. @xref{Printing}. - -@item @key{HELP} -@key{HELP} is the Emacs name for @kbd{C-h} or @key{F1}. You can type -@key{HELP} at any time to ask what options you have, or to ask what a -command does. @xref{Help}. - -@item Help Echo -Help echo is a short message displayed in the echo area (q.v.@:) when -the mouse pointer is located on portions of display that require some -explanations. Emacs displays help echo for menu items, parts of the -mode line, tool-bar buttons, etc. On graphical displays, the messages -can be displayed as tooltips (q.v.@:). @xref{Tooltips}. - -@item Home Directory -Your home directory contains your personal files. On a multi-user GNU -or Unix system, each user has his or her own home directory. When you -start a new login session, your home directory is the default -directory in which to start. A standard shorthand for your home -directory is @samp{~}. Similarly, @samp{~@var{user}} represents the -home directory of some other user. - -@item Hook -A hook is a list of functions to be called on specific occasions, such -as saving a buffer in a file, major mode activation, etc. By -customizing the various hooks, you can modify Emacs's behavior without -changing any of its code. @xref{Hooks}. - -@item Hyper -Hyper is the name of a modifier bit that a keyboard input character may -have. To make a character Hyper, type it while holding down the -@key{HYPER} key. Such characters are given names that start with -@kbd{Hyper-} (usually written @kbd{H-} for short). @xref{User Input}. - -@item Iff -``Iff'' means ``if and only if''. This terminology comes from -mathematics. Try to avoid using this term in documentation, since -many are unfamiliar with it and mistake it for a typo. - -@item Inbox -An inbox is a file in which mail is delivered by the operating system. -Rmail transfers mail from inboxes to Rmail files in which the -mail is then stored permanently or until explicitly deleted. -@xref{Rmail Inbox}. - -@anchor{Glossary - Incremental Search} -@item Incremental Search -Emacs provides an incremental search facility, whereby Emacs begins -searching for a string as soon as you type the first character. -As you type more characters, it refines the search. @xref{Incremental Search}. - -@item Indentation -Indentation means blank space at the beginning of a line. Most -programming languages have conventions for using indentation to -illuminate the structure of the program, and Emacs has special -commands to adjust indentation. -@xref{Indentation}. - -@item Indirect Buffer -An indirect buffer is a buffer that shares the text of another buffer, -called its base buffer (q.v.@:). @xref{Indirect Buffers}. - -@item Info -Info is the hypertext format used by the GNU project for writing -documentation. - -@item Input Event -An input event represents, within Emacs, one action taken by the user on -the terminal. Input events include typing characters, typing function -keys, pressing or releasing mouse buttons, and switching between Emacs -frames. @xref{User Input}. - -@item Input Method -An input method is a system for entering non-@acronym{ASCII} text characters by -typing sequences of @acronym{ASCII} characters (q.v.@:). @xref{Input Methods}. - -@item Insertion -Insertion means adding text into the buffer, either from the keyboard -or from some other place in Emacs. - -@item Interlocking -@xref{Glossary - File Locking}. - -@item Isearch -@xref{Glossary - Incremental Search}. - -@item Justification -Justification means adding extra spaces within lines of text in order -to adjust the position of the text edges. @xref{Fill Commands}. - -@item Key Binding -@xref{Glossary - Binding}. - -@item Keyboard Macro -Keyboard macros are a way of defining new Emacs commands from -sequences of existing ones, with no need to write a Lisp program. -You can use a macro to record a sequence of commands, then -play them back as many times as you like. -@xref{Keyboard Macros}. - -@cindex keyboard shortcuts -@item Keyboard Shortcut -A keyboard shortcut is a key sequence (q.v.@:) that invokes a -command. What some programs call ``assigning a keyboard shortcut'', -Emacs calls ``binding a key sequence''. @xref{Glossary - Binding}. - -@item Key Sequence -A key sequence (key, for short) is a sequence of input events (q.v.@:) -that are meaningful as a single unit. If the key sequence is enough to -specify one action, it is a complete key (q.v.@:); if it is not enough, -it is a prefix key (q.v.@:). @xref{Keys}. - -@item Keymap -The keymap is the data structure that records the bindings (q.v.@:) of -key sequences to the commands that they run. For example, the global -keymap binds the character @kbd{C-n} to the command function -@code{next-line}. @xref{Keymaps}. - -@item Keyboard Translation Table -The keyboard translation table is an array that translates the character -codes that come from the terminal into the character codes that make up -key sequences. - -@item Kill Ring -The kill ring is where all text you have killed (@pxref{Glossary - Killing}) -recently is saved. You can reinsert any of the killed text still in -the ring; this is called yanking (q.v.@:). @xref{Yanking}. - -@anchor{Glossary - Killing} -@item Killing -Killing means erasing text and saving it on the kill ring so it can be -yanked (q.v.@:) later. Some other systems call this ``cutting''. -Most Emacs commands that erase text perform killing, as opposed to -deletion (q.v.@:). @xref{Killing}. - -@item Killing a Job -Killing a job (such as, an invocation of Emacs) means making it cease -to exist. Any data within it, if not saved in a file, is lost. -@xref{Exiting}. - -@item Language Environment -Your choice of language environment specifies defaults for the input -method (q.v.@:) and coding system (q.v.@:). @xref{Language -Environments}. These defaults are relevant if you edit -non-@acronym{ASCII} text (@pxref{International}). - -@c TODO? Not really appropriate for the user manual I think. -@c Lexical Binding - -@item Line Wrapping -@xref{Glossary - Filling}. - -@item Lisp -Lisp is a programming language. Most of Emacs is written in a dialect -of Lisp, called Emacs Lisp, which is extended with special features that -make it especially suitable for text editing tasks. - -@item List -A list is, approximately, a text string beginning with an open -parenthesis and ending with the matching close parenthesis. In C mode -and other non-Lisp modes, groupings surrounded by other kinds of matched -delimiters appropriate to the language, such as braces, are also -considered lists. Emacs has special commands for many operations on -lists. @xref{Moving by Parens}. - -@item Local -Local means ``in effect only in a particular context''; the relevant -kind of context is a particular function execution, a particular -buffer, or a particular major mode. It is the opposite of `global' -(q.v.@:). Specific uses of `local' in Emacs terminology appear below. - -@item Local Abbrev -A local abbrev definition is effective only if a particular major mode -is selected. In that major mode, it overrides any global definition -for the same abbrev. @xref{Abbrevs}. - -@item Local Keymap -A local keymap is used in a particular major mode; the key bindings -(q.v.@:) in the current local keymap override global bindings of the -same key sequences. @xref{Keymaps}. - -@item Local Variable -A local value of a variable (q.v.@:) applies to only one buffer. -@xref{Locals}. - -@item @kbd{M-} -@kbd{M-} in the name of a character is an abbreviation for @key{META}, -one of the modifier keys that can accompany any character. -@xref{User Input,M-}. - -@item @kbd{M-C-} -@kbd{M-C-} in the name of a character is an abbreviation for -Control-Meta; it means the same thing as `@kbd{C-M-}' (q.v.@:). - -@item @kbd{M-x} -@kbd{M-x} is the key sequence that is used to call an Emacs command by -name. This is how you run commands that are not bound to key sequences. -@xref{M-x,M-x,Running Commands by Name}. - -@anchor{Glossary - Mail} -@item Mail -Mail means messages sent from one user to another through the computer -system, to be read at the recipient's convenience. Emacs has commands for -composing and sending mail, and for reading and editing the mail you have -received. @xref{Sending Mail}. @xref{Rmail}, for one way to read -mail with Emacs. - -@item Mail Composition Method -A mail composition method is a program runnable within Emacs for editing -and sending a mail message. Emacs lets you select from several -alternative mail composition methods. @xref{Mail Methods}. - -@item Major Mode -The Emacs major modes are a mutually exclusive set of options, each of -which configures Emacs for editing a certain sort of text. Ideally, -each programming language has its own major mode. @xref{Major Modes}. - -@item Margin -The space between the usable part of a window (including the -fringe) and the window edge. - -@item Mark -The mark points to a position in the text. It specifies one end of the -region (q.v.@:), point being the other end. Many commands operate on -all the text from point to the mark. Each buffer has its own mark. -@xref{Mark}. - -@item Mark Ring -The mark ring is used to hold several recent previous locations of the -mark, in case you want to move back to them. Each buffer has its -own mark ring; in addition, there is a single global mark ring (q.v.@:). -@xref{Mark Ring}. - -@item Menu Bar -The menu bar is a line at the top of an Emacs frame. It contains -words you can click on with the mouse to bring up menus, or you can use -a keyboard interface to navigate it. @xref{Menu Bars}. - -@item Message -@xref{Glossary - Mail}. - -@item Meta -Meta is the name of a modifier bit which you can use in a command -character. To enter a meta character, you hold down the @key{META} -key while typing the character. We refer to such characters with -names that start with @kbd{Meta-} (usually written @kbd{M-} for -short). For example, @kbd{M-<} is typed by holding down @key{META} -and at the same time typing @kbd{<} (which itself is done, on most -terminals, by holding down @key{SHIFT} and typing @kbd{,}). -@xref{User Input,Meta}. - -On some terminals, the @key{META} key is actually labeled @key{ALT} -or @key{EDIT}. - -@item Meta Character -A Meta character is one whose character code includes the Meta bit. - -@item Minibuffer -The minibuffer is the window that appears when necessary inside the -echo area (q.v.@:), used for reading arguments to commands. -@xref{Minibuffer}. - -@anchor{Glossary - Minibuffer History} -@item Minibuffer History -The minibuffer history records the text you have specified in the past -for minibuffer arguments, so you can conveniently use the same text -again. @xref{Minibuffer History}. - -@item Minor Mode -A minor mode is an optional feature of Emacs, which can be switched on -or off independently of all other features. Each minor mode has a -command to turn it on or off. Some minor modes are global (q.v.@:), -and some are local (q.v.@:). @xref{Minor Modes}. - -@item Minor Mode Keymap -A minor mode keymap is a keymap that belongs to a minor mode and is -active when that mode is enabled. Minor mode keymaps take precedence -over the buffer's local keymap, just as the local keymap takes -precedence over the global keymap. @xref{Keymaps}. - -@item Mode Line -The mode line is the line at the bottom of each window (q.v.@:), giving -status information on the buffer displayed in that window. @xref{Mode -Line}. - -@item Modified Buffer -A buffer (q.v.@:) is modified if its text has been changed since the -last time the buffer was saved (or since it was created, if it -has never been saved). @xref{Saving}. - -@item Moving Text -Moving text means erasing it from one place and inserting it in -another. The usual way to move text is by killing (q.v.@:) it and then -yanking (q.v.@:) it. @xref{Killing}. - -@item MULE -MULE refers to the Emacs features for editing multilingual -non-@acronym{ASCII} text using multibyte characters (q.v.@:). -@xref{International}. - -@item Multibyte Character -A multibyte character is a character that takes up several bytes in a -buffer. Emacs uses multibyte characters to represent non-@acronym{ASCII} text, -since the number of non-@acronym{ASCII} characters is much more than 256. -@xref{International Chars, International Characters}. - -@item Named Mark -A named mark is a register (q.v.@:), in its role of recording a -location in text so that you can move point to that location. -@xref{Registers}. - -@item Narrowing -Narrowing means creating a restriction (q.v.@:) that limits editing in -the current buffer to only a part of the text. Text outside that part -is inaccessible for editing (or viewing) until the boundaries are -widened again, but it is still there, and saving the file saves it -all. @xref{Narrowing}. - -@item Newline -Control-J characters in the buffer terminate lines of text and are -therefore also called newlines. @xref{Glossary - End Of Line}. - -@cindex nil -@cindex t -@item @code{nil} -@code{nil} is a value usually interpreted as a logical ``false''. Its -opposite is @code{t}, interpreted as ``true''. - -@anchor{Glossary - Numeric Argument} -@item Numeric Argument -A numeric argument is a number, specified before a command, to change -the effect of the command. Often the numeric argument serves as a -repeat count. @xref{Arguments}. - -@item Overwrite Mode -Overwrite mode is a minor mode. When it is enabled, ordinary text -characters replace the existing text after point rather than pushing -it to one side. @xref{Minor Modes}. - -@item Package -A package is a collection of Lisp code that you download and -automatically install from within Emacs. Packages provide a -convenient way to add new features. @xref{Packages}. - -@anchor{Glossary - Page} -@item Page -A page is a unit of text, delimited by formfeed characters (@acronym{ASCII} -control-L, code 014) at the beginning of a line. Some Emacs -commands are provided for moving over and operating on pages. -@xref{Pages}. - -@item Paragraph -Paragraphs are the medium-size unit of human-language text. There are -special Emacs commands for moving over and operating on paragraphs. -@xref{Paragraphs}. - -@item Parsing -We say that certain Emacs commands parse words or expressions in the -text being edited. Really, all they know how to do is find the other -end of a word or expression. - -@item Point -Point is the place in the buffer at which insertion and deletion -occur. Point is considered to be between two characters, not at one -character. The terminal's cursor (q.v.@:) indicates the location of -point. @xref{Point}. - -@item Prefix Argument -@xref{Glossary - Numeric Argument}. - -@item Prefix Key -A prefix key is a key sequence (q.v.@:) whose sole function is to -introduce a set of longer key sequences. @kbd{C-x} is an example of -prefix key; any two-character sequence starting with @kbd{C-x} is -therefore a legitimate key sequence. @xref{Keys}. - -@c I don't think this kind of thing needs to be here. -@ignore -@item Primary Rmail File -Your primary Rmail file is the file named @samp{RMAIL} in your home -directory. That's where Rmail stores your incoming mail, unless you -specify a different file name. @xref{Rmail}. -@end ignore - -@item Primary Selection -The primary selection is one particular X selection (q.v.@:); it is the -selection that most X applications use for transferring text to and from -other applications. - -The Emacs kill commands set the primary selection and the yank command -uses the primary selection when appropriate. @xref{Killing}. - -@item Prompt -A prompt is text used to ask you for input. Displaying a prompt -is called prompting. Emacs prompts always appear in the echo area -(q.v.@:). One kind of prompting happens when the minibuffer is used to -read an argument (@pxref{Minibuffer}); the echoing that happens when -you pause in the middle of typing a multi-character key sequence is also -a kind of prompting (@pxref{Echo Area}). - -@item Query-Replace -Query-replace is an interactive string replacement feature provided by -Emacs. @xref{Query Replace}. - -@anchor{Glossary - Quitting} -@item Quitting -Quitting means canceling a partially typed command or a running -command, using @kbd{C-g} (or @kbd{C-@key{BREAK}} on MS-DOS). @xref{Quitting}. - -@item Quoting -Quoting means depriving a character of its usual special significance. -The most common kind of quoting in Emacs is with @kbd{C-q}. What -constitutes special significance depends on the context and on -convention. For example, an ``ordinary'' character as an Emacs command -inserts itself; so in this context, a special character is any character -that does not normally insert itself (such as @key{DEL}, for example), -and quoting it makes it insert itself as if it were not special. Not -all contexts allow quoting. @xref{Inserting Text,Quoting}. - -@item Quoting File Names -Quoting a file name turns off the special significance of constructs -such as @samp{$}, @samp{~} and @samp{:}. @xref{Quoted File Names}. - -@item Read-Only Buffer -A read-only buffer is one whose text you are not allowed to change. -Normally Emacs makes buffers read-only when they contain text which -has a special significance to Emacs; for example, Dired buffers. -Visiting a file that is write-protected also makes a read-only buffer. -@xref{Buffers}. - -@item Rectangle -A rectangle consists of the text in a given range of columns on a given -range of lines. Normally you specify a rectangle by putting point at -one corner and putting the mark at the diagonally opposite corner. -@xref{Rectangles}. - -@item Recursive Editing Level -A recursive editing level is a state in which part of the execution of -a command involves asking you to edit some text. This text may -or may not be the same as the text to which the command was applied. -The mode line indicates recursive editing levels with square brackets -(@samp{[} and @samp{]}). @xref{Recursive Edit}. - -@item Redisplay -Redisplay is the process of correcting the image on the screen to -correspond to changes that have been made in the text being edited. -@xref{Screen,Redisplay}. - -@item Regexp -@xref{Glossary - Regular Expression}. - -@item Region -The region is the text between point (q.v.@:) and the mark (q.v.@:). -Many commands operate on the text of the region. @xref{Mark,Region}. - -@item Register -Registers are named slots in which text, buffer positions, or -rectangles can be saved for later use. @xref{Registers}. A related -Emacs feature is `bookmarks' (q.v.@:). - -@anchor{Glossary - Regular Expression} -@item Regular Expression -A regular expression is a pattern that can match various text strings; -for example, @samp{a[0-9]+} matches @samp{a} followed by one or more -digits. @xref{Regexps}. - -@item Remote File -A remote file is a file that is stored on a system other than your own. -Emacs can access files on other computers provided that they are -connected to the same network as your machine, and (obviously) that -you have a supported method to gain access to those files. -@xref{Remote Files}. - -@item Repeat Count -@xref{Glossary - Numeric Argument}. - -@item Replacement -@xref{Glossary - Global Substitution}. - -@item Restriction -A buffer's restriction is the amount of text, at the beginning or the -end of the buffer, that is temporarily inaccessible. Giving a buffer a -nonzero amount of restriction is called narrowing (q.v.@:); removing -a restriction is called widening (q.v.@:). @xref{Narrowing}. - -@item @key{RET} -@key{RET} is a character that in Emacs runs the command to insert a -newline into the text. It is also used to terminate most arguments -read in the minibuffer (q.v.@:). @xref{User Input,Return}. - -@item Reverting -Reverting means returning to the original state. Emacs lets you -revert a buffer by re-reading its file from disk. @xref{Reverting}. - -@c Seems too obvious, also there is nothing special about the format -@c these days. -@ignore -@item Rmail File -An Rmail file is a file containing text in the format used by -Rmail for storing mail. @xref{Rmail}. -@end ignore - -@item Saving -Saving a buffer means copying its text into the file that was visited -(q.v.@:) in that buffer. This is the way text in files actually gets -changed by your Emacs editing. @xref{Saving}. - -@item Scroll Bar -A scroll bar is a tall thin hollow box that appears at the side of a -window. You can use mouse commands in the scroll bar to scroll the -window. The scroll bar feature is supported only under windowing -systems. @xref{Scroll Bars}. - -@item Scrolling -Scrolling means shifting the text in the Emacs window so as to see a -different part of the buffer. @xref{Scrolling}. - -@item Searching -Searching means moving point to the next occurrence of a specified -string or the next match for a specified regular expression. -@xref{Search}. - -@item Search Path -A search path is a list of directory names, to be used for searching for -files for certain purposes. For example, the variable @code{load-path} -holds a search path for finding Lisp library files. @xref{Lisp Libraries}. - -@item Secondary Selection -The secondary selection is one particular X selection (q.v.@:); some X -applications can use it for transferring text to and from other -applications. Emacs has special mouse commands for transferring text -using the secondary selection. @xref{Secondary Selection}. - -@item Selected Frame -The selected frame is the one your input currently operates on. -@xref{Frames}. - -@item Selected Window -The selected window is the one your input currently operates on. -@xref{Basic Window}. - -@item Selecting a Buffer -Selecting a buffer means making it the current (q.v.@:) buffer. -@xref{Select Buffer}. - -@item Selection -Windowing systems allow an application program to specify -selections whose values are text. A program can also read the -selections that other programs have set up. This is the principal way -of transferring text between window applications. Emacs has commands to -work with the primary (q.v.@:) selection and the secondary (q.v.@:) -selection, and also with the clipboard (q.v.@:). - -@item Self-Documentation -Self-documentation is the feature of Emacs that can tell you what any -command does, or give you a list of all commands related to a topic -you specify. You ask for self-documentation with the help character, -@kbd{C-h}. @xref{Help}. - -@item Self-Inserting Character -A character is self-inserting if typing that character inserts that -character in the buffer. Ordinary printing and whitespace characters -are self-inserting in Emacs, except in certain special major modes. - -@item Sentences -Emacs has commands for moving by or killing by sentences. -@xref{Sentences}. - -@anchor{Glossary - Server} -@item Server -Within Emacs, you can start a `server' process, which listens for -connections from `clients'. This offers a faster alternative to -starting several Emacs instances. @xref{Emacs Server}, and -@ref{Glossary - Daemon}. - -@c This is only covered in the lispref, not the user manual. -@ignore -@item Session Manager -Some window systems (q.v.@:) provide a tool called a `session manager'. -This offers the ability to save your windows when you log off, -and restore them after you log in again. -@end ignore - -@item Sexp -A sexp (short for ``s-expression'') is the basic syntactic unit of -Lisp in its textual form: either a list, or Lisp atom. Sexps are also -the balanced expressions (q.v.@:) of the Lisp language; this is why -the commands for editing balanced expressions have `sexp' in their -name. @xref{Expressions,Sexps}. - -@item Simultaneous Editing -Simultaneous editing means two users modifying the same file at once. -Simultaneous editing, if not detected, can cause one user to lose his -or her work. Emacs detects all cases of simultaneous editing, and -warns one of the users to investigate. -@xref{Interlocking,Interlocking,Simultaneous Editing}. - -@item @key{SPC} -@key{SPC} is the space character, which you enter by pressing the -space bar. - -@item Speedbar -The speedbar is a special tall frame that provides fast access to Emacs -buffers, functions within those buffers, Info nodes, and other -interesting parts of text within Emacs. @xref{Speedbar}. - -@item Spell Checking -Spell checking means checking correctness of the written form of each -one of the words in a text. Emacs can use various external -spelling-checker programs to check the spelling of parts of a buffer -via a convenient user interface. @xref{Spelling}. - -@item String -A string is a kind of Lisp data object that contains a sequence of -characters. Many Emacs variables are intended to have strings as -values. The Lisp syntax for a string consists of the characters in the -string with a @samp{"} before and another @samp{"} after. A @samp{"} -that is part of the string must be written as @samp{\"} and a @samp{\} -that is part of the string must be written as @samp{\\}. All other -characters, including newline, can be included just by writing them -inside the string; however, backslash sequences as in C, such as -@samp{\n} for newline or @samp{\241} using an octal character code, are -allowed as well. - -@item String Substitution -@xref{Glossary - Global Substitution}. - -@item Syntax Highlighting -@xref{Glossary - Font Lock}. - -@item Syntax Table -The syntax table tells Emacs which characters are part of a word, -which characters balance each other like parentheses, etc. -@xref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp Reference -Manual}. - -@item Super -Super is the name of a modifier bit that a keyboard input character may -have. To make a character Super, type it while holding down the -@key{SUPER} key. Such characters are given names that start with -@kbd{Super-} (usually written @kbd{s-} for short). @xref{User Input}. - -@item Suspending -Suspending Emacs means stopping it temporarily and returning control -to its parent process, which is usually a shell. Unlike killing a job -(q.v.@:), you can later resume the suspended Emacs job without losing -your buffers, unsaved edits, undo history, etc. @xref{Exiting}. - -@item @key{TAB} -@key{TAB} is the tab character. In Emacs it is typically used for -indentation or completion. - -@anchor{Glossary - Tags Table} -@item Tags Table -A tags table is a file that serves as an index to the function -definitions in one or more other files. @xref{Tags}. - -@item Termscript File -A termscript file contains a record of all characters sent by Emacs to -the terminal. It is used for tracking down bugs in Emacs redisplay. -Emacs does not make a termscript file unless you tell it to. -@xref{Bugs}. - -@item Text -`Text' has two meanings (@pxref{Text}): - -@itemize @bullet -@item -Data consisting of a sequence of characters, as opposed to binary -numbers, executable programs, and the like. The basic contents of an -Emacs buffer (aside from the text properties, q.v.@:) are always text -in this sense. -@item -Data consisting of written human language (as opposed to programs), -or following the stylistic conventions of human language. -@end itemize - -@anchor{Glossary - Text Terminal} -@item Text Terminal -A text terminal, or character terminal, is a display that is limited -to displaying text in character units. Such a terminal cannot control -individual pixels it displays. Emacs supports a subset of display -features on text terminals. - -@item Text Properties -Text properties are annotations recorded for particular characters in -the buffer. Images in the buffer are recorded as text properties; -they also specify formatting information. @xref{Editing Format Info}. - -@item Theme -A theme is a set of customizations (q.v.@:) that give Emacs a -particular appearance or behavior. For example, you might use a theme -for your favorite set of faces (q.v.@:). - -@item Tool Bar -The tool bar is a line (sometimes multiple lines) of icons at the top -of an Emacs frame. Clicking on one of these icons executes a command. -You can think of this as a graphical relative of the menu bar (q.v.@:). -@xref{Tool Bars}. - -@anchor{Glossary - Tooltips} -@item Tooltips -Tooltips are small windows displaying a help echo (q.v.@:) text, which -explains parts of the display, lists useful options available via mouse -clicks, etc. @xref{Tooltips}. - -@item Top Level -Top level is the normal state of Emacs, in which you are editing the -text of the file you have visited. You are at top level whenever you -are not in a recursive editing level (q.v.@:) or the minibuffer -(q.v.@:), and not in the middle of a command. You can get back to top -level by aborting (q.v.@:) and quitting (q.v.@:). @xref{Quitting}. - -@c FIXME? Transient Mark Mode - -@item Transposition -Transposing two units of text means putting each one into the place -formerly occupied by the other. There are Emacs commands to transpose -two adjacent characters, words, balanced expressions (q.v.@:) or lines -(@pxref{Transpose}). - -@item Trash Can -@xref{Glossary - Deletion of Files}. - -@anchor{Glossary - Truncation} -@item Truncation -Truncating text lines in the display means leaving out any text on a -line that does not fit within the right margin of the window -displaying it. @xref{Continuation Lines,Truncation}, and -@ref{Glossary - Continuation Line}. - -@item TTY -@xref{Glossary - Text Terminal}. - -@item Undoing -Undoing means making your previous editing go in reverse, bringing -back the text that existed earlier in the editing session. -@xref{Undo}. - -@item Unix -Unix is a class of multi-user computer operating systems with a long -history. There are several implementations today. The GNU project -(q.v.@:) aims to develop a complete Unix-like operating system that -is free software (q.v.@:). - -@item User Option -A user option is a face (q.v.@:) or a variable (q.v.@:) that exists so -that you can customize Emacs by setting it to a new value. -@xref{Easy Customization}. - -@item Variable -A variable is an object in Lisp that can store an arbitrary value. -Emacs uses some variables for internal purposes, and has others (known -as `user options'; q.v.@:) just so that you can set their values to -control the behavior of Emacs. The variables used in Emacs that you -are likely to be interested in are listed in the Variables Index in -this manual (@pxref{Variable Index}). @xref{Variables}, for -information on variables. - -@item Version Control -Version control systems keep track of multiple versions of a source file. -They provide a more powerful alternative to keeping backup files (q.v.@:). -@xref{Version Control}. - -@item Visiting -Visiting a file means loading its contents into a buffer (q.v.@:) -where they can be edited. @xref{Visiting}. - -@item Whitespace -Whitespace is any run of consecutive formatting characters (space, -tab, newline, and backspace). - -@item Widening -Widening is removing any restriction (q.v.@:) on the current buffer; -it is the opposite of narrowing (q.v.@:). @xref{Narrowing}. - -@item Window -Emacs divides a frame (q.v.@:) into one or more windows, each of which -can display the contents of one buffer (q.v.@:) at any time. -@xref{Screen}, for basic information on how Emacs uses the screen. -@xref{Windows}, for commands to control the use of windows. Some -other editors use the term ``window'' for what we call a `frame' -(q.v.@:) in Emacs. - -@item Window System -A window system is software that operates on a graphical display -(q.v.@:), to subdivide the screen so that multiple applications can -have their] own windows at the same time. All modern operating systems -include a window system. - -@item Word Abbrev -@xref{Glossary - Abbrev}. - -@item Word Search -Word search is searching for a sequence of words, considering the -punctuation between them as insignificant. @xref{Word Search}. - -@anchor{Glossary - Yanking} -@item Yanking -Yanking means reinserting text previously killed (q.v.@:). It can be -used to undo a mistaken kill, or for copying or moving text. Some -other systems call this ``pasting''. @xref{Yanking}. -@end table diff --git a/doc/emacs/gnu.texi b/doc/emacs/gnu.texi deleted file mode 100644 index ac9b9de6dcb..00000000000 --- a/doc/emacs/gnu.texi +++ /dev/null @@ -1,551 +0,0 @@ -@c Copyright (C) 1985-1987, 1993, 1995, 2001-2012 -@c Free Software Foundation, Inc. -@c -@c Permission is granted to anyone to make or distribute verbatim copies -@c of this document, in any medium, provided that the copyright notice and -@c permission notice are preserved, and that the distributor grants the -@c recipient permission for further redistribution as permitted by this -@c notice. -@c -@c Modified versions may not be made. - -@ifclear justgnu -@node Manifesto,, Microsoft Windows, Top -@unnumbered The GNU Manifesto -@end ifclear -@ifset justgnu -@node Top -@top The GNU Manifesto -@end ifset - -@quotation -The GNU Manifesto which appears below was written by Richard Stallman at -the beginning of the GNU project, to ask for participation and support. -For the first few years, it was updated in minor ways to account for -developments, but now it seems best to leave it unchanged as most people -have seen it. - -Since that time, we have learned about certain common misunderstandings -that different wording could help avoid. Footnotes added in 1993 help -clarify these points. - -For up-to-date information about available GNU software, please see -our web site, @uref{http://www.gnu.org}. For software tasks and other -ways to contribute, see @uref{http://www.gnu.org/help}. -@end quotation - -@unnumberedsec What's GNU? Gnu's Not Unix! - -GNU, which stands for Gnu's Not Unix, is the name for the complete -Unix-compatible software system which I am writing so that I can give it -away free to everyone who can use it.@footnote{The wording here was -careless. The intention was that nobody would have to pay for -@emph{permission} to use the GNU system. But the words don't make this -clear, and people often interpret them as saying that copies of GNU -should always be distributed at little or no charge. That was never the -intent; later on, the manifesto mentions the possibility of companies -providing the service of distribution for a profit. Subsequently I have -learned to distinguish carefully between ``free'' in the sense of -freedom and ``free'' in the sense of price. Free software is software -that users have the freedom to distribute and change. Some users may -obtain copies at no charge, while others pay to obtain copies---and if -the funds help support improving the software, so much the better. The -important thing is that everyone who has a copy has the freedom to -cooperate with others in using it.} Several other volunteers are helping -me. Contributions of time, money, programs and equipment are greatly -needed. - -So far we have an Emacs text editor with Lisp for writing editor commands, -a source level debugger, a yacc-compatible parser generator, a linker, and -around 35 utilities. A shell (command interpreter) is nearly completed. A -new portable optimizing C compiler has compiled itself and may be released -this year. An initial kernel exists but many more features are needed to -emulate Unix. When the kernel and compiler are finished, it will be -possible to distribute a GNU system suitable for program development. We -will use @TeX{} as our text formatter, but an nroff is being worked on. We -will use the free, portable X window system as well. After this we will -add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of -other things, plus on-line documentation. We hope to supply, eventually, -everything useful that normally comes with a Unix system, and more. - -GNU will be able to run Unix programs, but will not be identical to Unix. -We will make all improvements that are convenient, based on our experience -with other operating systems. In particular, we plan to have longer -file names, file version numbers, a crashproof file system, file name -completion perhaps, terminal-independent display support, and perhaps -eventually a Lisp-based window system through which several Lisp programs -and ordinary Unix programs can share a screen. Both C and Lisp will be -available as system programming languages. We will try to support UUCP, -MIT Chaosnet, and Internet protocols for communication. - -GNU is aimed initially at machines in the 68000/16000 class with virtual -memory, because they are the easiest machines to make it run on. The extra -effort to make it run on smaller machines will be left to someone who wants -to use it on them. - -To avoid horrible confusion, please pronounce the `G' in the word `GNU' -when it is the name of this project. - -@unnumberedsec Why I Must Write GNU - -I consider that the golden rule requires that if I like a program I must -share it with other people who like it. Software sellers want to divide -the users and conquer them, making each user agree not to share with -others. I refuse to break solidarity with other users in this way. I -cannot in good conscience sign a nondisclosure agreement or a software -license agreement. For years I worked within the Artificial Intelligence -Lab to resist such tendencies and other inhospitalities, but eventually -they had gone too far: I could not remain in an institution where such -things are done for me against my will. - -So that I can continue to use computers without dishonor, I have decided to -put together a sufficient body of free software so that I will be able to -get along without any software that is not free. I have resigned from the -AI lab to deny MIT any legal excuse to prevent me from giving GNU away. - -@unnumberedsec Why GNU Will Be Compatible with Unix - -Unix is not my ideal system, but it is not too bad. The essential features -of Unix seem to be good ones, and I think I can fill in what Unix lacks -without spoiling them. And a system compatible with Unix would be -convenient for many other people to adopt. - -@unnumberedsec How GNU Will Be Available - -GNU is not in the public domain. Everyone will be permitted to modify and -redistribute GNU, but no distributor will be allowed to restrict its -further redistribution. That is to say, proprietary modifications will not -be allowed. I want to make sure that all versions of GNU remain free. - -@unnumberedsec Why Many Other Programmers Want to Help - -I have found many other programmers who are excited about GNU and want to -help. - -Many programmers are unhappy about the commercialization of system -software. It may enable them to make more money, but it requires them to -feel in conflict with other programmers in general rather than feel as -comrades. The fundamental act of friendship among programmers is the -sharing of programs; marketing arrangements now typically used essentially -forbid programmers to treat others as friends. The purchaser of software -must choose between friendship and obeying the law. Naturally, many decide -that friendship is more important. But those who believe in law often do -not feel at ease with either choice. They become cynical and think that -programming is just a way of making money. - -By working on and using GNU rather than proprietary programs, we can be -hospitable to everyone and obey the law. In addition, GNU serves as an -example to inspire and a banner to rally others to join us in sharing. -This can give us a feeling of harmony which is impossible if we use -software that is not free. For about half the programmers I talk to, this -is an important happiness that money cannot replace. - -@unnumberedsec How You Can Contribute - -I am asking computer manufacturers for donations of machines and money. -I'm asking individuals for donations of programs and work. - -One consequence you can expect if you donate machines is that GNU will run -on them at an early date. The machines should be complete, ready to use -systems, approved for use in a residential area, and not in need of -sophisticated cooling or power. - -I have found very many programmers eager to contribute part-time work for -GNU. For most projects, such part-time distributed work would be very hard -to coordinate; the independently-written parts would not work together. -But for the particular task of replacing Unix, this problem is absent. A -complete Unix system contains hundreds of utility programs, each of which -is documented separately. Most interface specifications are fixed by Unix -compatibility. If each contributor can write a compatible replacement for -a single Unix utility, and make it work properly in place of the original -on a Unix system, then these utilities will work right when put together. -Even allowing for Murphy to create a few unexpected problems, assembling -these components will be a feasible task. (The kernel will require closer -communication and will be worked on by a small, tight group.) - -If I get donations of money, I may be able to hire a few people full or -part time. The salary won't be high by programmers' standards, but I'm -looking for people for whom building community spirit is as important as -making money. I view this as a way of enabling dedicated people to devote -their full energies to working on GNU by sparing them the need to make a -living in another way. - -@unnumberedsec Why All Computer Users Will Benefit - -Once GNU is written, everyone will be able to obtain good system -software free, just like air.@footnote{This is another place I failed to -distinguish carefully between the two different meanings of ``free.'' -The statement as it stands is not false---you can get copies of GNU -software at no charge, from your friends or over the net. But it does -suggest the wrong idea.} - -This means much more than just saving everyone the price of a Unix license. -It means that much wasteful duplication of system programming effort will -be avoided. This effort can go instead into advancing the state of the -art. - -Complete system sources will be available to everyone. As a result, a user -who needs changes in the system will always be free to make them himself, -or hire any available programmer or company to make them for him. Users -will no longer be at the mercy of one programmer or company which owns the -sources and is in sole position to make changes. - -Schools will be able to provide a much more educational environment by -encouraging all students to study and improve the system code. Harvard's -computer lab used to have the policy that no program could be installed on -the system if its sources were not on public display, and upheld it by -actually refusing to install certain programs. I was very much inspired by -this. - -Finally, the overhead of considering who owns the system software and what -one is or is not entitled to do with it will be lifted. - -Arrangements to make people pay for using a program, including licensing of -copies, always incur a tremendous cost to society through the cumbersome -mechanisms necessary to figure out how much (that is, which programs) a -person must pay for. And only a police state can force everyone to obey -them. Consider a space station where air must be manufactured at great -cost: charging each breather per liter of air may be fair, but wearing the -metered gas mask all day and all night is intolerable even if everyone can -afford to pay the air bill. And the TV cameras everywhere to see if you -ever take the mask off are outrageous. It's better to support the air -plant with a head tax and chuck the masks. - -Copying all or parts of a program is as natural to a programmer as -breathing, and as productive. It ought to be as free. - -@unnumberedsec Some Easily Rebutted Objections to GNU's Goals - -@quotation -``Nobody will use it if it is free, because that means they can't rely -on any support.'' - -``You have to charge for the program to pay for providing the -support.'' -@end quotation - -If people would rather pay for GNU plus service than get GNU free without -service, a company to provide just service to people who have obtained GNU -free ought to be profitable.@footnote{Several such companies now exist.} - -We must distinguish between support in the form of real programming work -and mere handholding. The former is something one cannot rely on from a -software vendor. If your problem is not shared by enough people, the -vendor will tell you to get lost. - -If your business needs to be able to rely on support, the only way is to -have all the necessary sources and tools. Then you can hire any available -person to fix your problem; you are not at the mercy of any individual. -With Unix, the price of sources puts this out of consideration for most -businesses. With GNU this will be easy. It is still possible for there to -be no available competent person, but this problem cannot be blamed on -distribution arrangements. GNU does not eliminate all the world's problems, -only some of them. - -Meanwhile, the users who know nothing about computers need handholding: -doing things for them which they could easily do themselves but don't know -how. - -Such services could be provided by companies that sell just hand-holding -and repair service. If it is true that users would rather spend money and -get a product with service, they will also be willing to buy the service -having got the product free. The service companies will compete in quality -and price; users will not be tied to any particular one. Meanwhile, those -of us who don't need the service should be able to use the program without -paying for the service. - -@quotation -``You cannot reach many people without advertising, -and you must charge for the program to support that.'' - -``It's no use advertising a program people can get free.'' -@end quotation - -There are various forms of free or very cheap publicity that can be used to -inform numbers of computer users about something like GNU. But it may be -true that one can reach more microcomputer users with advertising. If this -is really so, a business which advertises the service of copying and -mailing GNU for a fee ought to be successful enough to pay for its -advertising and more. This way, only the users who benefit from the -advertising pay for it. - -On the other hand, if many people get GNU from their friends, and such -companies don't succeed, this will show that advertising was not really -necessary to spread GNU. Why is it that free market advocates don't -want to let the free market decide this?@footnote{The Free Software -Foundation raises most of its funds from a distribution service, -although it is a charity rather than a company. If @emph{no one} -chooses to obtain copies by ordering from the FSF, it will be unable -to do its work. But this does not mean that proprietary restrictions -are justified to force every user to pay. If a small fraction of all -the users order copies from the FSF, that is sufficient to keep the FSF -afloat. So we ask users to choose to support us in this way. Have you -done your part?} - -@quotation -``My company needs a proprietary operating system -to get a competitive edge.'' -@end quotation - -GNU will remove operating system software from the realm of competition. -You will not be able to get an edge in this area, but neither will your -competitors be able to get an edge over you. You and they will compete in -other areas, while benefiting mutually in this one. If your business is -selling an operating system, you will not like GNU, but that's tough on -you. If your business is something else, GNU can save you from being -pushed into the expensive business of selling operating systems. - -I would like to see GNU development supported by gifts from many -manufacturers and users, reducing the cost to each.@footnote{A group of -computer companies recently pooled funds to support maintenance of the -GNU C Compiler.} - -@quotation -``Don't programmers deserve a reward for their creativity?'' -@end quotation - -If anything deserves a reward, it is social contribution. Creativity can -be a social contribution, but only in so far as society is free to use the -results. If programmers deserve to be rewarded for creating innovative -programs, by the same token they deserve to be punished if they restrict -the use of these programs. - -@quotation -``Shouldn't a programmer be able to ask for a reward for his creativity?'' -@end quotation - -There is nothing wrong with wanting pay for work, or seeking to maximize -one's income, as long as one does not use means that are destructive. But -the means customary in the field of software today are based on -destruction. - -Extracting money from users of a program by restricting their use of it is -destructive because the restrictions reduce the amount and the ways that -the program can be used. This reduces the amount of wealth that humanity -derives from the program. When there is a deliberate choice to restrict, -the harmful consequences are deliberate destruction. - -The reason a good citizen does not use such destructive means to become -wealthier is that, if everyone did so, we would all become poorer from the -mutual destructiveness. This is Kantian ethics; or, the Golden Rule. -Since I do not like the consequences that result if everyone hoards -information, I am required to consider it wrong for one to do so. -Specifically, the desire to be rewarded for one's creativity does not -justify depriving the world in general of all or part of that creativity. - -@quotation -``Won't programmers starve?'' -@end quotation - -I could answer that nobody is forced to be a programmer. Most of us cannot -manage to get any money for standing on the street and making faces. But -we are not, as a result, condemned to spend our lives standing on the -street making faces, and starving. We do something else. - -But that is the wrong answer because it accepts the questioner's implicit -assumption: that without ownership of software, programmers cannot possibly -be paid a cent. Supposedly it is all or nothing. - -The real reason programmers will not starve is that it will still be -possible for them to get paid for programming; just not paid as much as -now. - -Restricting copying is not the only basis for business in software. It is -the most common basis because it brings in the most money. If it were -prohibited, or rejected by the customer, software business would move to -other bases of organization which are now used less often. There are -always numerous ways to organize any kind of business. - -Probably programming will not be as lucrative on the new basis as it is -now. But that is not an argument against the change. It is not considered -an injustice that sales clerks make the salaries that they now do. If -programmers made the same, that would not be an injustice either. (In -practice they would still make considerably more than that.) - -@quotation -``Don't people have a right to control how their creativity is used?'' -@end quotation - -``Control over the use of one's ideas'' really constitutes control over -other people's lives; and it is usually used to make their lives more -difficult. - -People who have studied the issue of intellectual property -rights@footnote{In the 80s I had not yet realized how confusing it was -to speak of ``the issue'' of ``intellectual property.'' That term is -obviously biased; more subtle is the fact that it lumps together -various disparate laws which raise very different issues. Nowadays I -urge people to reject the term ``intellectual property'' entirely, -lest it lead others to suppose that those laws form one coherent -issue. The way to be clear is to discuss patents, copyrights, and -trademarks separately. See -@uref{http://www.gnu.org/philosophy/not-ipr.xhtml} for more -explanation of how this term spreads confusion and bias.} carefully -(such as lawyers) say that there is no intrinsic right to intellectual -property. The kinds of supposed intellectual property rights that the -government recognizes were created by specific acts of legislation for -specific purposes. - -For example, the patent system was established to encourage inventors to -disclose the details of their inventions. Its purpose was to help society -rather than to help inventors. At the time, the life span of 17 years for -a patent was short compared with the rate of advance of the state of the -art. Since patents are an issue only among manufacturers, for whom the -cost and effort of a license agreement are small compared with setting up -production, the patents often do not do much harm. They do not obstruct -most individuals who use patented products. - -The idea of copyright did not exist in ancient times, when authors -frequently copied other authors at length in works of non-fiction. This -practice was useful, and is the only way many authors' works have survived -even in part. The copyright system was created expressly for the purpose -of encouraging authorship. In the domain for which it was -invented---books, which could be copied economically only on a printing -press---it did little harm, and did not obstruct most of the individuals -who read the books. - -All intellectual property rights are just licenses granted by society -because it was thought, rightly or wrongly, that society as a whole would -benefit by granting them. But in any particular situation, we have to ask: -are we really better off granting such license? What kind of act are we -licensing a person to do? - -The case of programs today is very different from that of books a hundred -years ago. The fact that the easiest way to copy a program is from one -neighbor to another, the fact that a program has both source code and -object code which are distinct, and the fact that a program is used rather -than read and enjoyed, combine to create a situation in which a person who -enforces a copyright is harming society as a whole both materially and -spiritually; in which a person should not do so regardless of whether the -law enables him to. - -@quotation -``Competition makes things get done better.'' -@end quotation - -The paradigm of competition is a race: by rewarding the winner, we -encourage everyone to run faster. When capitalism really works this way, -it does a good job; but its defenders are wrong in assuming it always works -this way. If the runners forget why the reward is offered and become -intent on winning, no matter how, they may find other strategies---such as, -attacking other runners. If the runners get into a fist fight, they will -all finish late. - -Proprietary and secret software is the moral equivalent of runners in a -fist fight. Sad to say, the only referee we've got does not seem to -object to fights; he just regulates them (``For every ten yards you run, -you can fire one shot''). He really ought to break them up, and penalize -runners for even trying to fight. - -@quotation -``Won't everyone stop programming without a monetary incentive?'' -@end quotation - -Actually, many people will program with absolutely no monetary incentive. -Programming has an irresistible fascination for some people, usually the -people who are best at it. There is no shortage of professional musicians -who keep at it even though they have no hope of making a living that way. - -But really this question, though commonly asked, is not appropriate to the -situation. Pay for programmers will not disappear, only become less. So -the right question is, will anyone program with a reduced monetary -incentive? My experience shows that they will. - -For more than ten years, many of the world's best programmers worked at the -Artificial Intelligence Lab for far less money than they could have had -anywhere else. They got many kinds of non-monetary rewards: fame and -appreciation, for example. And creativity is also fun, a reward in itself. - -Then most of them left when offered a chance to do the same interesting -work for a lot of money. - -What the facts show is that people will program for reasons other than -riches; but if given a chance to make a lot of money as well, they will -come to expect and demand it. Low-paying organizations do poorly in -competition with high-paying ones, but they do not have to do badly if the -high-paying ones are banned. - -@quotation -``We need the programmers desperately. If they demand that we -stop helping our neighbors, we have to obey.'' -@end quotation - -You're never so desperate that you have to obey this sort of demand. -Remember: millions for defense, but not a cent for tribute! - -@quotation -``Programmers need to make a living somehow.'' -@end quotation - -In the short run, this is true. However, there are plenty of ways that -programmers could make a living without selling the right to use a program. -This way is customary now because it brings programmers and businessmen the -most money, not because it is the only way to make a living. It is easy to -find other ways if you want to find them. Here are a number of examples. - -A manufacturer introducing a new computer will pay for the porting of -operating systems onto the new hardware. - -The sale of teaching, hand-holding and maintenance services could also -employ programmers. - -People with new ideas could distribute programs as -freeware@footnote{Subsequently we have discovered the need to -distinguish between ``free software'' and ``freeware''. The term -``freeware'' means software you are free to redistribute, but usually -you are not free to study and change the source code, so most of it is -not free software. See -@uref{http://www.gnu.org/philosophy/words-to-avoid.html} for more -explanation.}, asking for donations from satisfied users, or selling -hand-holding services. I have met people who are already working this -way successfully. - -Users with related needs can form users' groups, and pay dues. A group -would contract with programming companies to write programs that the -group's members would like to use. - -All sorts of development can be funded with a Software Tax: - -@quotation -Suppose everyone who buys a computer has to pay x percent of -the price as a software tax. The government gives this to -an agency like the NSF to spend on software development. - -But if the computer buyer makes a donation to software development -himself, he can take a credit against the tax. He can donate to -the project of his own choosing---often, chosen because he hopes to -use the results when it is done. He can take a credit for any amount -of donation up to the total tax he had to pay. - -The total tax rate could be decided by a vote of the payers of -the tax, weighted according to the amount they will be taxed on. - -The consequences: - -@itemize @bullet -@item -The computer-using community supports software development. -@item -This community decides what level of support is needed. -@item -Users who care which projects their share is spent on -can choose this for themselves. -@end itemize -@end quotation - -In the long run, making programs free is a step toward the post-scarcity -world, where nobody will have to work very hard just to make a living. -People will be free to devote themselves to activities that are fun, such -as programming, after spending the necessary ten hours a week on required -tasks such as legislation, family counseling, robot repair and asteroid -prospecting. There will be no need to be able to make a living from -programming. - -We have already greatly reduced the amount of work that the whole society -must do for its actual productivity, but only a little of this has -translated itself into leisure for workers because much nonproductive -activity is required to accompany productive activity. The main causes of -this are bureaucracy and isometric struggles against competition. Free -software will greatly reduce these drains in the area of software -production. We must do this, in order for technical gains in productivity -to translate into less work for us. diff --git a/doc/emacs/gpl.texi b/doc/emacs/gpl.texi deleted file mode 100644 index 1908d1f8f98..00000000000 --- a/doc/emacs/gpl.texi +++ /dev/null @@ -1,717 +0,0 @@ -@c The GNU General Public License. -@center Version 3, 29 June 2007 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. -@end display - -@heading Preamble - -The GNU General Public License is a free, copyleft license for -software and other kinds of works. - -The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom -to share and change all versions of a program---to make sure it remains -free software for all its users. We, the Free Software Foundation, -use the GNU General Public License for most of our software; it -applies also to any other work released this way by its authors. You -can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - -To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you -have certain responsibilities if you distribute copies of the -software, or if you modify it: responsibilities to respect the freedom -of others. - -For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, -receive or can get the source code. And you must show them these -terms so they know their rights. - -Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - -For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - -Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the -manufacturer can do so. This is fundamentally incompatible with the -aim of protecting users' freedom to change the software. The -systematic pattern of such abuse occurs in the area of products for -individuals to use, which is precisely where it is most unacceptable. -Therefore, we have designed this version of the GPL to prohibit the -practice for those products. If such problems arise substantially in -other domains, we stand ready to extend this provision to those -domains in future versions of the GPL, as needed to protect the -freedom of users. - -Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish -to avoid the special danger that patents applied to a free program -could make it effectively proprietary. To prevent this, the GPL -assures that patents cannot be used to render the program non-free. - -The precise terms and conditions for copying, distribution and -modification follow. - -@heading TERMS AND CONDITIONS - -@enumerate 0 -@item Definitions. - -``This License'' refers to version 3 of the GNU General Public License. - -``Copyright'' also means copyright-like laws that apply to other kinds -of works, such as semiconductor masks. - -``The Program'' refers to any copyrightable work licensed under this -License. Each licensee is addressed as ``you''. ``Licensees'' and -``recipients'' may be individuals or organizations. - -To ``modify'' a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of -an exact copy. The resulting work is called a ``modified version'' of -the earlier work or a work ``based on'' the earlier work. - -A ``covered work'' means either the unmodified Program or a work based -on the Program. - -To ``propagate'' a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - -To ``convey'' a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user -through a computer network, with no transfer of a copy, is not -conveying. - -An interactive user interface displays ``Appropriate Legal Notices'' to -the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - -@item Source Code. - -The ``source code'' for a work means the preferred form of the work for -making modifications to it. ``Object code'' means any non-source form -of a work. - -A ``Standard Interface'' means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - -The ``System Libraries'' of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -``Major Component'', in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - -The ``Corresponding Source'' for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - -The Corresponding Source need not include anything that users can -regenerate automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same -work. - -@item Basic Permissions. - -All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - -You may make, run and propagate covered works that you do not convey, -without conditions so long as your license otherwise remains in force. -You may convey covered works to others for the sole purpose of having -them make modifications exclusively for you, or provide you with -facilities for running those works, provided that you comply with the -terms of this License in conveying all material for which you do not -control copyright. Those thus making or running the covered works for -you must do so exclusively on your behalf, under your direction and -control, on terms that prohibit them from making any copies of your -copyrighted material outside their relationship with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - -@item Protecting Users' Legal Rights From Anti-Circumvention Law. - -No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such -circumvention is effected by exercising rights under this License with -respect to the covered work, and you disclaim any intention to limit -operation or modification of the work as a means of enforcing, against -the work's users, your or third parties' legal rights to forbid -circumvention of technological measures. - -@item Conveying Verbatim Copies. - -You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - -@item Conveying Modified Source Versions. - -You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these -conditions: - -@enumerate a -@item -The work must carry prominent notices stating that you modified it, -and giving a relevant date. - -@item -The work must carry prominent notices stating that it is released -under this License and any conditions added under section 7. This -requirement modifies the requirement in section 4 to ``keep intact all -notices''. - -@item -You must license the entire work, as a whole, under this License to -anyone who comes into possession of a copy. This License will -therefore apply, along with any applicable section 7 additional terms, -to the whole of the work, and all its parts, regardless of how they -are packaged. This License gives no permission to license the work in -any other way, but it does not invalidate such permission if you have -separately received it. - -@item -If the work has interactive user interfaces, each must display -Appropriate Legal Notices; however, if the Program has interactive -interfaces that do not display Appropriate Legal Notices, your work -need not make them do so. -@end enumerate - -A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -``aggregate'' if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -@item Conveying Non-Source Forms. - -You may convey a covered work in object code form under the terms of -sections 4 and 5, provided that you also convey the machine-readable -Corresponding Source under the terms of this License, in one of these -ways: - -@enumerate a -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by the -Corresponding Source fixed on a durable physical medium customarily -used for software interchange. - -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by a written -offer, valid for at least three years and valid for as long as you -offer spare parts or customer support for that product model, to give -anyone who possesses the object code either (1) a copy of the -Corresponding Source for all the software in the product that is -covered by this License, on a durable physical medium customarily used -for software interchange, for a price no more than your reasonable -cost of physically performing this conveying of source, or (2) access -to copy the Corresponding Source from a network server at no charge. - -@item -Convey individual copies of the object code with a copy of the written -offer to provide the Corresponding Source. This alternative is -allowed only occasionally and noncommercially, and only if you -received the object code with such an offer, in accord with subsection -6b. - -@item -Convey the object code by offering access from a designated place -(gratis or for a charge), and offer equivalent access to the -Corresponding Source in the same way through the same place at no -further charge. You need not require recipients to copy the -Corresponding Source along with the object code. If the place to copy -the object code is a network server, the Corresponding Source may be -on a different server (operated by you or a third party) that supports -equivalent copying facilities, provided you maintain clear directions -next to the object code saying where to find the Corresponding Source. -Regardless of what server hosts the Corresponding Source, you remain -obligated to ensure that it is available for as long as needed to -satisfy these requirements. - -@item -Convey the object code using peer-to-peer transmission, provided you -inform other peers where the object code and Corresponding Source of -the work are being offered to the general public at no charge under -subsection 6d. - -@end enumerate - -A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - -A ``User Product'' is either (1) a ``consumer product'', which means any -tangible personal property which is normally used for personal, -family, or household purposes, or (2) anything designed or sold for -incorporation into a dwelling. In determining whether a product is a -consumer product, doubtful cases shall be resolved in favor of -coverage. For a particular product received by a particular user, -``normally used'' refers to a typical or common use of that class of -product, regardless of the status of the particular user or of the way -in which the particular user actually uses, or expects or is expected -to use, the product. A product is a consumer product regardless of -whether the product has substantial commercial, industrial or -non-consumer uses, unless such uses represent the only significant -mode of use of the product. - -``Installation Information'' for a User Product means any methods, -procedures, authorization keys, or other information required to -install and execute modified versions of a covered work in that User -Product from a modified version of its Corresponding Source. The -information must suffice to ensure that the continued functioning of -the modified object code is in no case prevented or interfered with -solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - -The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or -updates for a work that has been modified or installed by the -recipient, or for the User Product in which it has been modified or -installed. Access to a network may be denied when the modification -itself materially and adversely affects the operation of the network -or violates the rules and protocols for communication across the -network. - -Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - -@item Additional Terms. - -``Additional permissions'' are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - -Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders -of that material) supplement the terms of this License with terms: - -@enumerate a -@item -Disclaiming warranty or limiting liability differently from the terms -of sections 15 and 16 of this License; or - -@item -Requiring preservation of specified reasonable legal notices or author -attributions in that material or in the Appropriate Legal Notices -displayed by works containing it; or - -@item -Prohibiting misrepresentation of the origin of that material, or -requiring that modified versions of such material be marked in -reasonable ways as different from the original version; or - -@item -Limiting the use for publicity purposes of names of licensors or -authors of the material; or - -@item -Declining to grant rights under trademark law for use of some trade -names, trademarks, or service marks; or - -@item -Requiring indemnification of licensors and authors of that material by -anyone who conveys the material (or modified versions of it) with -contractual assumptions of liability to the recipient, for any -liability that these contractual assumptions directly impose on those -licensors and authors. -@end enumerate - -All other non-permissive additional terms are considered ``further -restrictions'' within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; the -above requirements apply either way. - -@item Termination. - -You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - -@item Acceptance Not Required for Having Copies. - -You are not required to accept this License in order to receive or run -a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - -@item Automatic Licensing of Downstream Recipients. - -Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - -An ``entity transaction'' is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - -You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - -@item Patents. - -A ``contributor'' is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's ``contributor version''. - -A contributor's ``essential patent claims'' are all patent claims owned -or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, ``control'' includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - -In the following three paragraphs, a ``patent license'' is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To ``grant'' such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - -If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. ``Knowingly relying'' means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - -If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - -A patent license is ``discriminatory'' if it does not include within the -scope of its coverage, prohibits the exercise of, or is conditioned on -the non-exercise of one or more of the rights that are specifically -granted under this License. You may not convey a covered work if you -are a party to an arrangement with a third party that is in the -business of distributing software, under which you make payment to the -third party based on the extent of your activity of conveying the -work, and under which the third party grants, to any of the parties -who would receive the covered work from you, a discriminatory patent -license (a) in connection with copies of the covered work conveyed by -you (or copies made from those copies), or (b) primarily for and in -connection with specific products or compilations that contain the -covered work, unless you entered into that arrangement, or that patent -license was granted, prior to 28 March 2007. - -Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - -@item No Surrender of Others' Freedom. - -If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey -a covered work so as to satisfy simultaneously your obligations under -this License and any other pertinent obligations, then as a -consequence you may not convey it at all. For example, if you agree -to terms that obligate you to collect a royalty for further conveying -from those to whom you convey the Program, the only way you could -satisfy both those terms and this License would be to refrain entirely -from conveying the Program. - -@item Use with the GNU Affero General Public License. - -Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - -@item Revised Versions of this License. - -The Free Software Foundation may publish revised and/or new versions -of the GNU General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies that a certain numbered version of the GNU General Public -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that numbered version or -of any later version published by the Free Software Foundation. If -the Program does not specify a version number of the GNU General -Public License, you may choose any version ever published by the Free -Software Foundation. - -If the Program specifies that a proxy can decide which future versions -of the GNU General Public License can be used, that proxy's public -statement of acceptance of a version permanently authorizes you to -choose that version for the Program. - -Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - -@item Disclaimer of Warranty. - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT -WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND -PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -@item Limitation of Liability. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR -CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT -NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR -LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM -TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER -PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -@item Interpretation of Sections 15 and 16. - -If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - -@end enumerate - -@heading END OF TERMS AND CONDITIONS - -@heading How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or (at -your option) any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see @url{http://www.gnu.org/licenses/}. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - -@smallexample -@var{program} Copyright (C) @var{year} @var{name of author} -This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. -This is free software, and you are welcome to redistribute it -under certain conditions; type @samp{show c} for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, your -program's commands might be different; for a GUI interface, you would -use an ``about box''. - -You should also get your employer (if you work as a programmer) or school, -if any, to sign a ``copyright disclaimer'' for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -@url{http://www.gnu.org/licenses/}. - -The GNU General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use -the GNU Lesser General Public License instead of this License. But -first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi deleted file mode 100644 index e8c5614ff58..00000000000 --- a/doc/emacs/help.texi +++ /dev/null @@ -1,636 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Help, Mark, M-x, Top -@chapter Help -@kindex Help -@cindex help -@cindex self-documentation -@findex help-command -@kindex C-h -@kindex F1 - -@kindex C-h C-h -@findex help-for-help - Emacs provides a wide variety of help commands, all accessible -through the prefix key @kbd{C-h} (or, equivalently, the function key -@key{F1}). These help commands are described in the following -sections. You can also type @kbd{C-h C-h} to view a list of help -commands (@code{help-for-help}). You can scroll the list with -@key{SPC} and @key{DEL}, then type the help command you want. To -cancel, type @kbd{C-g}. - - Many help commands display their information in a special @dfn{help -buffer}. In this buffer, you can type @key{SPC} and @key{DEL} to -scroll and type @key{RET} to follow hyperlinks. @xref{Help Mode}. - -@cindex searching documentation efficiently -@cindex looking for a subject in documentation - If you are looking for a certain feature, but don't know what it is -called or where to look, we recommend three methods. First, try an -apropos command, then try searching the manual index, then look in the -FAQ and the package keywords. - -@table @kbd -@item C-h a @var{topics} @key{RET} -This searches for commands whose names match the argument -@var{topics}. The argument can be a keyword, a list of keywords, or a -regular expression (@pxref{Regexps}). @xref{Apropos}. - -@item C-h i d m emacs @key{RET} i @var{topic} @key{RET} -This searches for @var{topic} in the indices of the Emacs Info manual, -displaying the first match found. Press @kbd{,} to see subsequent -matches. You can use a regular expression as @var{topic}. - -@item C-h i d m emacs @key{RET} s @var{topic} @key{RET} -Similar, but searches the @emph{text} of the manual rather than the -indices. - -@item C-h C-f -This displays the Emacs FAQ, using Info. - -@item C-h p -This displays the available Emacs packages based on keywords. -@xref{Package Keywords}. -@end table - - @kbd{C-h} or @key{F1} means ``help'' in various other contexts as -well. For instance, you can type them after a prefix key to view a -list of the keys that can follow the prefix key. (A few prefix keys -don't support @kbd{C-h} in this way, because they define other -meanings for it, but they all support @key{F1} for help.) - -@menu -* Help Summary:: Brief list of all Help commands. -* Key Help:: Asking what a key does in Emacs. -* Name Help:: Asking about a command, variable or function name. -* Apropos:: Asking what pertains to a given topic. -* Help Mode:: Special features of Help mode and Help buffers. -* Package Keywords:: Finding Lisp libraries by keywords (topics). -* Language Help:: Help relating to international language support. -* Misc Help:: Other help commands. -* Help Files:: Commands to display auxiliary help files. -* Help Echo:: Help on active text and tooltips ("balloon help"). -@end menu - -@iftex -@node Help Summary -@end iftex -@ifnottex -@node Help Summary -@section Help Summary -@end ifnottex - - Here is a summary of help commands for accessing the built-in -documentation. Most of these are described in more detail in the -following sections. - -@table @kbd -@item C-h a @var{topics} @key{RET} -Display a list of commands whose names match @var{topics} -(@code{apropos-command}). -@item C-h b -Display all active key bindings; minor mode bindings first, then those -of the major mode, then global bindings (@code{describe-bindings}). -@item C-h c @var{key} -Show the name of the command that the key sequence @var{key} is bound -to (@code{describe-key-briefly}). Here @kbd{c} stands for -``character''. For more extensive information on @var{key}, use -@kbd{C-h k}. -@item C-h d @var{topics} @key{RET} -Display the commands and variables whose documentation matches -@var{topics} (@code{apropos-documentation}). -@item C-h e -Display the @file{*Messages*} buffer -(@code{view-echo-area-messages}). -@item C-h f @var{function} @key{RET} -Display documentation on the Lisp function named @var{function} -(@code{describe-function}). Since commands are Lisp functions, -this works for commands too. -@item C-h h -Display the @file{HELLO} file, which shows examples of various character -sets. -@item C-h i -Run Info, the GNU documentation browser (@code{info}). The Emacs -manual is available in Info. -@item C-h k @var{key} -Display the name and documentation of the command that @var{key} runs -(@code{describe-key}). -@item C-h l -Display a description of your last 300 keystrokes -(@code{view-lossage}). -@item C-h m -Display documentation of the current major mode (@code{describe-mode}). -@item C-h n -Display news of recent Emacs changes (@code{view-emacs-news}). -@item C-h p -Find packages by topic keyword (@code{finder-by-keyword}). This lists -packages using a package menu buffer. @xref{Packages}. -@item C-h P @var{package} @key{RET} -Display documentation about the package named @var{package} -(@code{describe-package}). -@item C-h r -Display the Emacs manual in Info (@code{info-emacs-manual}). -@item C-h s -Display the contents of the current @dfn{syntax table} -(@code{describe-syntax}). The syntax table says which characters are -opening delimiters, which are parts of words, and so on. @xref{Syntax -Tables,, Syntax Tables, elisp, The Emacs Lisp Reference Manual}, for -details. -@item C-h t -Enter the Emacs interactive tutorial (@code{help-with-tutorial}). -@item C-h v @var{var} @key{RET} -Display the documentation of the Lisp variable @var{var} -(@code{describe-variable}). -@item C-h w @var{command} @key{RET} -Show which keys run the command named @var{command} (@code{where-is}). -@item C-h C @var{coding} @key{RET} -Describe the coding system @var{coding} -(@code{describe-coding-system}). -@item C-h C @key{RET} -Describe the coding systems currently in use. -@item C-h F @var{command} @key{RET} -Enter Info and go to the node that documents the Emacs command -@var{command} (@code{Info-goto-emacs-command-node}). -@item C-h I @var{method} @key{RET} -Describe the input method @var{method} (@code{describe-input-method}). -@item C-h K @var{key} -Enter Info and go to the node that documents the key sequence -@var{key} (@code{Info-goto-emacs-key-command-node}). -@item C-h L @var{language-env} @key{RET} -Display information on the character sets, coding systems, and input -methods used in language environment @var{language-env} -(@code{describe-language-environment}). -@item C-h S @var{symbol} @key{RET} -Display the Info documentation on symbol @var{symbol} according to the -programming language you are editing (@code{info-lookup-symbol}). -@item C-h . -Display the help message for a special text area, if point is in one -(@code{display-local-help}). (These include, for example, links in -@file{*Help*} buffers.) -@end table - -@node Key Help -@section Documentation for a Key - -@findex describe-key-briefly -@findex describe-key - The help commands to get information about a key sequence are -@kbd{C-h c} (@code{describe-key-briefly}) and @kbd{C-h k} -(@code{describe-key}). - -@kindex C-h c - @kbd{C-h c @var{key}} displays in the echo area the name of the -command that @var{key} is bound to. For example, @kbd{C-h c C-f} -displays @samp{forward-char}. - -@cindex documentation string -@kindex C-h k - @kbd{C-h k @var{key}} is similar but gives more information: it -displays a help buffer containing the command's @dfn{documentation -string}, which describes exactly what the command does. - -@kindex C-h K -@findex Info-goto-emacs-key-command-node - @kbd{C-h K @var{key}} displays the section of the Emacs manual that -describes the command corresponding to @var{key}. - - @kbd{C-h c}, @kbd{C-h k} and @kbd{C-h K} work for any sort of key -sequences, including function keys, menus, and mouse events. For -instance, after @kbd{C-h k} you can select a menu item from the menu -bar, to view the documentation string of the command it runs. - -@kindex C-h w -@findex where-is - @kbd{C-h w @var{command} @key{RET}} lists the keys that are bound to -@var{command}. It displays the list in the echo area. If it says the -command is not on any key, that means you must use @kbd{M-x} to run -it. @kbd{C-h w} runs the command @code{where-is}. - -@node Name Help -@section Help by Command or Variable Name - -@kindex C-h f -@findex describe-function - @kbd{C-h f @var{function} @key{RET}} (@code{describe-function}) -displays the documentation of Lisp function @var{function}, in a -window. Since commands are Lisp functions, you can use this method to -view the documentation of any command whose name you know. For -example, - -@example -C-h f auto-fill-mode @key{RET} -@end example - -@noindent -displays the documentation of @code{auto-fill-mode}. This is the only -way to get the documentation of a command that is not bound to any key -(one which you would normally run using @kbd{M-x}). - - @kbd{C-h f} is also useful for Lisp functions that you use in a Lisp -program. For example, if you have just written the expression -@code{(make-vector len)} and want to check that you are using -@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}. -Because @kbd{C-h f} allows all function names, not just command names, -you may find that some of your favorite completion abbreviations that -work in @kbd{M-x} don't work in @kbd{C-h f}. An abbreviation that is -unique among command names may not be unique among all function names. - - If you type @kbd{C-h f @key{RET}}, it describes the function called -by the innermost Lisp expression in the buffer around point, -@emph{provided} that function name is a valid, defined Lisp function. -(That name appears as the default while you enter the argument.) For -example, if point is located following the text @samp{(make-vector -(car x)}, the innermost list containing point is the one that starts -with @samp{(make-vector}, so @kbd{C-h f @key{RET}} will describe the -function @code{make-vector}. - - @kbd{C-h f} is also useful just to verify that you spelled a -function name correctly. If the minibuffer prompt for @kbd{C-h f} -shows the function name from the buffer as the default, it means that -name is defined as a Lisp function. Type @kbd{C-g} to cancel the -@kbd{C-h f} command if you don't really want to view the -documentation. - -@kindex C-h v -@findex describe-variable - @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but -describes Lisp variables instead of Lisp functions. Its default is -the Lisp symbol around or before point, if that is the name of a -defined Lisp variable. @xref{Variables}. - - Help buffers that describe Emacs variables and functions normally -have hyperlinks to the corresponding source code, if you have the -source files installed (@pxref{Hyperlinking}). - -@kindex C-h F -@findex Info-goto-emacs-command-node - To find a command's documentation in a manual, use @kbd{C-h F} -(@code{Info-goto-emacs-command-node}). This knows about various -manuals, not just the Emacs manual, and finds the right one. - -@node Apropos -@section Apropos -@cindex apropos - - The @dfn{apropos} commands answer questions like, ``What are the -commands for working with files?'' More precisely, you specify an -@dfn{apropos pattern}, which means either a word, a list of words, or -a regular expression. - - Each of the following apropos commands reads an apropos pattern in -the minibuffer, searches for items that match the pattern, and -displays the results in a different window. - -@table @kbd -@item C-h a -@kindex C-h a -@findex apropos-command -Search for commands (@code{apropos-command}). With a prefix argument, -search for noninteractive functions too. - -@item M-x apropos -@findex apropos -Search for functions and variables. Both interactive functions -(commands) and noninteractive functions can be found by this. - -@item M-x apropos-variable -@findex apropos-variable -Search for user-customizable variables. With a prefix argument, -search for non-customizable variables too. - -@item M-x apropos-value -@findex apropos-value -Search for variables whose values match the specified pattern. With a -prefix argument, search also for functions with definitions matching -the pattern, and Lisp symbols with properties matching the pattern. - -@item C-h d -@kindex C-h d -@findex apropos-documentation -Search for functions and variables whose documentation strings match -the specified pattern (@code{apropos-documentation}). -@end table - - The simplest kind of apropos pattern is one word. Anything -containing that word matches the pattern. Thus, to find commands that -work on files, type @kbd{C-h a file @key{RET}}. This displays a list -of all command names that contain @samp{file}, including -@code{copy-file}, @code{find-file}, and so on. Each command name -comes with a brief description and a list of keys you can currently -invoke it with. In our example, it would say that you can invoke -@code{find-file} by typing @kbd{C-x C-f}. - - For more information about a function definition, variable or symbol -property listed in an apropos buffer, you can click on it with -@kbd{Mouse-1} or @kbd{Mouse-2}, or move there and type @key{RET}. - - When you specify more than one word in the apropos pattern, a name -must contain at least two of the words in order to match. Thus, if -you are looking for commands to kill a chunk of text before point, you -could try @kbd{C-h a kill back backward behind before @key{RET}}. The -real command name @code{kill-backward} will match that; if there were -a command @code{kill-text-before}, it would also match, since it -contains two of the specified words. - - For even greater flexibility, you can specify a regular expression -(@pxref{Regexps}). An apropos pattern is interpreted as a regular -expression if it contains any of the regular expression special -characters, @samp{^$*+?.\[}. - - Following the conventions for naming Emacs commands, here are some -words that you'll find useful in apropos patterns. By using them in -@kbd{C-h a}, you will also get a feel for the naming conventions. - -@quotation -char, line, word, sentence, paragraph, region, page, sexp, list, defun, -rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, -forward, backward, next, previous, up, down, search, goto, kill, delete, -mark, insert, yank, fill, indent, case, change, set, what, list, find, -view, describe, default. -@end quotation - -@vindex apropos-do-all - If the variable @code{apropos-do-all} is non-@code{nil}, the apropos -commands always behave as if they had been given a prefix argument. - -@vindex apropos-sort-by-scores -@cindex apropos search results, order by score -@vindex apropos-documentation-sort-by-scores - By default, all apropos commands except @code{apropos-documentation} -list their results in alphabetical order. If the variable -@code{apropos-sort-by-scores} is non-@code{nil}, these commands -instead try to guess the relevance of each result, and display the -most relevant ones first. The @code{apropos-documentation} command -lists its results in order of relevance by default; to list them in -alphabetical order, change the variable -@code{apropos-documentation-sort-by-scores} to @code{nil}. - -@node Help Mode -@section Help Mode Commands - - Help buffers provide the same commands as View mode (@pxref{View -Mode}); for instance, @key{SPC} scrolls forward, and @key{DEL} scrolls -backward. A few special commands are also provided: - -@table @kbd -@item @key{RET} -Follow a cross reference at point (@code{help-follow}). -@item @key{TAB} -Move point forward to the next hyperlink (@code{forward-button}). -@item S-@key{TAB} -Move point back to the previous hyperlink (@code{backward-button}). -@item Mouse-1 -@itemx Mouse-2 -Follow a hyperlink that you click on. -@item C-c C-c -Show all documentation about the symbol at point -(@code{help-follow-symbol}). -@item C-c C-b -Go back to the previous help topic (@code{help-go-back}). -@end table - -@cindex hyperlink -@findex help-follow -@findex help-go-back -@kindex RET @r{(Help mode)} -@kindex C-c C-b @r{(Help mode)} - When a function name, variable name, or face name (@pxref{Faces}) -appears in the documentation in the help buffer, it is normally an -underlined @dfn{hyperlink}. To view the associated documentation, -move point there and type @key{RET} (@code{help-follow}), or click on -the hyperlink with @kbd{Mouse-1} or @kbd{Mouse-2}. Doing so replaces -the contents of the help buffer; to retrace your steps, type @kbd{C-c -C-b} (@code{help-go-back}). - -@cindex URL, viewing in help -@cindex help, viewing web pages -@cindex viewing web pages in help -@cindex web pages, viewing in help -@findex browse-url - A help buffer can also contain hyperlinks to Info manuals, source -code definitions, and URLs (web pages). The first two are opened in -Emacs, and the third using a web browser via the @code{browse-url} -command (@pxref{Browse-URL}). - -@kindex TAB @r{(Help mode)} -@findex forward-button -@kindex S-TAB @r{(Help mode)} -@findex backward-button - In a help buffer, @key{TAB} (@code{forward-button}) moves point -forward to the next hyperlink, while @kbd{S-@key{TAB}} -(@code{backward-button}) point back to the previous hyperlink. These -commands act cyclically; for instance, typing @key{TAB} at the last -hyperlink moves back to the first hyperlink. - - To view all documentation about any symbol in the text, move point -to there and type @kbd{C-c C-c} (@code{help-follow-symbol}). This -shows all available documentation about the symbol---as a variable, -function and/or face. - -@node Package Keywords -@section Keyword Search for Packages -@cindex finder - -Most optional features in Emacs are grouped into @dfn{packages}. -Emacs contains several hundred built-in packages, and more can be -installed over the network (@pxref{Packages}). - -@kindex C-h p -@findex finder-by-keyword - To make it easier to find packages related to a topic, most packages -are associated with one or more @dfn{keywords} based on what they do. -Type @kbd{C-h p} (@code{finder-by-keyword}) to bring up a list of -package keywords, together with a description of what the keywords -mean. To view a list of packages for a given keyword, type @key{RET} -on that line; this displays the list of packages in a Package Menu -buffer (@pxref{Package Menu}). - -@findex describe-package -@kindex C-h P - @kbd{C-h P} (@code{describe-package}) prompts for the name of a -package, and displays a help buffer describing the attributes of the -package and the features that it implements. - -@node Language Help -@section Help for International Language Support - - For information on a specific language environment (@pxref{Language -Environments}), type @kbd{C-h L} -(@code{describe-language-environment}). This displays a help buffer -describing the languages supported by the language environment, and -listing the associated character sets, coding systems, and input -methods, as well as some sample text for that language environment. - - The command @kbd{C-h h} (@code{view-hello-file}) displays the file -@file{etc/HELLO}, which demonstrates various character sets by showing -how to say ``hello'' in many languages. - - The command @kbd{C-h I} (@code{describe-input-method}) describes an -input method---either a specified input method, or by default the -input method currently in use. @xref{Input Methods}. - - The command @kbd{C-h C} (@code{describe-coding-system}) describes -coding systems---either a specified coding system, or the ones -currently in use. @xref{Coding Systems}. - -@node Misc Help -@section Other Help Commands - -@kindex C-h i -@findex info -@cindex Info -@cindex manuals, on-line -@cindex on-line manuals - @kbd{C-h i} (@code{info}) runs the Info program, which browses -structured documentation files. The entire Emacs manual is available -within Info, along with many other manuals for the GNU system. Type -@kbd{h} after entering Info to run a tutorial on using Info. - -@cindex find Info manual by its file name - With a numeric argument @var{n}, @kbd{C-h i} selects the Info buffer -@samp{*info*<@var{n}>}. This is useful if you want to browse multiple -Info manuals simultaneously. If you specify just @kbd{C-u} as the -prefix argument, @kbd{C-h i} prompts for the name of a documentation -file, so you can browse a file which doesn't have an entry in the -top-level Info menu. - - The help commands @kbd{C-h F @var{function} @key{RET}} and @kbd{C-h -K @var{key}}, described above, enter Info and go straight to the -documentation of @var{function} or @var{key}. - -@kindex C-h S -@findex info-lookup-symbol - When editing a program, if you have an Info version of the manual -for the programming language, you can use @kbd{C-h S} -(@code{info-lookup-symbol}) to find an entry for a symbol (keyword, -function or variable) in the proper manual. The details of how this -command works depend on the major mode. - -@kindex C-h l -@findex view-lossage - If something surprising happens, and you are not sure what you typed, -use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} displays your last -300 input keystrokes. If you see commands that you don't know, you can -use @kbd{C-h c} to find out what they do. - -@kindex C-h e -@findex view-echo-area-messages - To review recent echo area messages, use @kbd{C-h e} -(@code{view-echo-area-messages}). This displays the buffer -@file{*Messages*}, where those messages are kept. - -@kindex C-h m -@findex describe-mode - Each Emacs major mode typically redefines a few keys and makes other -changes in how editing works. @kbd{C-h m} (@code{describe-mode}) -displays documentation on the current major mode, which normally -describes the commands and features that are changed in this mode. - -@kindex C-h b -@findex describe-bindings - @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s} -(@code{describe-syntax}) show other information about the current -environment within Emacs. @kbd{C-h b} displays a list of all the key -bindings now in effect: first the local bindings of the current minor -modes, then the local bindings defined by the current major mode, and -finally the global bindings (@pxref{Key Bindings}). @kbd{C-h s} -displays the contents of the syntax table, with explanations of each -character's syntax (@pxref{Syntax Tables,, Syntax Tables, elisp, The -Emacs Lisp Reference Manual}). - -@findex describe-prefix-bindings - You can get a list of subcommands for a particular prefix key by -typing @kbd{C-h} (@code{describe-prefix-bindings}) after the prefix -key. (There are a few prefix keys for which this does not -work---those that provide their own bindings for @kbd{C-h}. One of -these is @key{ESC}, because @kbd{@key{ESC} C-h} is actually -@kbd{C-M-h}, which marks a defun.) - -@node Help Files -@section Help Files - - Apart from the built-in documentation and manuals, Emacs contains -several other files describing topics like copying conditions, release -notes, instructions for debugging and reporting bugs, and so forth. -You can use the following commands to view these files. Apart from -@kbd{C-h g}, they all have the form @kbd{C-h C-@var{char}}. - -@kindex C-h C-c -@findex describe-copying -@kindex C-h C-d -@findex view-emacs-debugging -@kindex C-h C-e -@findex view-external-packages -@kindex C-h C-f -@findex view-emacs-FAQ -@kindex C-h g -@findex describe-gnu-project -@kindex C-h C-m -@findex view-order-manuals -@kindex C-h C-n -@findex view-emacs-news -@kindex C-h C-o -@findex describe-distribution -@kindex C-h C-p -@findex view-emacs-problems -@kindex C-h C-t -@findex view-emacs-todo -@kindex C-h C-w -@findex describe-no-warranty - -@table @kbd -@item C-h C-c -Display the rules under which you can copy and redistribute Emacs -(@code{describe-copying}). -@item C-h C-d -Display help for debugging Emacs (@code{view-emacs-debugging}). -@item C-h C-e -Display information about where to get external packages -(@code{view-external-packages}). -@item C-h C-f -Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}). -@item C-h g -Display information about the GNU Project (@code{describe-gnu-project}). -@item C-h C-m -Display information about ordering printed copies of Emacs manuals -(@code{view-order-manuals}). -@item C-h C-n -Display the ``news'' file, which lists the new features in this -version of Emacs (@code{view-emacs-news}). -@item C-h C-o -Display how to order or download the latest version of -Emacs and other GNU software (@code{describe-distribution}). -@item C-h C-p -Display the list of known Emacs problems, sometimes with suggested -workarounds (@code{view-emacs-problems}). -@item C-h C-t -Display the Emacs to-do list (@code{view-emacs-todo}). -@item C-h C-w -Display the full details on the complete absence of warranty for GNU -Emacs (@code{describe-no-warranty}). -@end table - -@node Help Echo -@section Help on Active Text and Tooltips - -@cindex tooltips -@cindex balloon help - In Emacs, stretches of ``active text'' (text that does something -special in response to mouse clicks or @key{RET}) often have -associated help text. This includes hyperlinks in Emacs buffers, as -well as parts of the mode line. On graphical displays, as well as -some text terminals which support mouse tracking, moving the mouse -over the active text displays the help text as a @dfn{tooltip}. -@xref{Tooltips}. - -@kindex C-h . -@findex display-local-help -@vindex help-at-pt-display-when-idle - On terminals that don't support mouse-tracking, you can display the -help text for active buffer text at point by typing @kbd{C-h .} -(@code{display-local-help}). This shows the help text in the echo -area. To display help text automatically whenever it is available at -point, set the variable @code{help-at-pt-display-when-idle} to -@code{t}. diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi deleted file mode 100644 index 3892dc2ae99..00000000000 --- a/doc/emacs/indent.texi +++ /dev/null @@ -1,240 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Indentation, Text, Modes, Top -@chapter Indentation -@cindex indentation -@cindex tabs -@cindex columns (indentation) - -@cindex whitespace character - @dfn{Indentation} refers to inserting or adjusting @dfn{whitespace -characters} (space and/or tab characters) at the beginning of a line -of text. This chapter documents indentation commands and options -which are common to Text mode and related modes, as well as -programming language modes. @xref{Program Indent}, for additional -documentation about indenting in programming modes. - -@findex indent-for-tab-command -@kindex TAB @r{(indentation)} - The simplest way to perform indentation is the @key{TAB} key. In -most major modes, this runs the command @code{indent-for-tab-command}. -(In C and related modes, @key{TAB} runs the command -@code{c-indent-line-or-region}, which behaves similarly). - -@table @key -@item TAB -Insert whitespace, or indent the current line, in a mode-appropriate -way (@code{indent-for-tab-command}). If the region is active, indent -all the lines within it. -@end table - - The exact behavior of @key{TAB} depends on the major mode. In Text -mode and related major modes, @key{TAB} normally inserts some -combination of space and tab characters to advance point to the next -tab stop (@pxref{Tab Stops}). For this purpose, the position of the -first non-whitespace character on the preceding line is treated as an -additional tab stop, so you can use @key{TAB} to ``align'' point with -the preceding line. If the region is active (@pxref{Using Region}), -@key{TAB} acts specially: it indents each line in the region so that -its first non-whitespace character is aligned with the preceding line. - - In programming modes, @key{TAB} indents the current line of code in -a way that makes sense given the code in the preceding lines. If the -region is active, all the lines in the region are indented this way. -If point was initially within the current line's indentation, it is -repositioned to the first non-whitespace character on the line. - - If you just want to insert a tab character in the buffer, type -@kbd{C-q @key{TAB}} (@pxref{Inserting Text}). - -@menu -* Indentation Commands:: More commands for performing indentation. -* Tab Stops:: Stop points for indentation in Text modes. -* Just Spaces:: Using only space characters for indentation. -* Indent Convenience:: Optional indentation features. -@end menu - -@node Indentation Commands -@section Indentation Commands - -Apart from the @key{TAB} (@code{indent-for-tab-command}) command, -Emacs provides a variety of commands to perform indentation in other -ways. - -@table @kbd -@item C-j -@kindex C-j -@findex newline-and-indent -Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). - -@item C-M-o -@kindex C-M-o -@findex split-line -Split the current line at point (@code{split-line}). The text on the -line after point becomes a new line, indented to the same column where -point is located. This command first moves point forward over any -spaces and tabs. Afterward, point is positioned before the inserted -newline. - -@kindex M-m -@findex back-to-indentation -@item M-m -Move (forward or back) to the first non-whitespace character on the -current line (@code{back-to-indentation}). If there are no -non-whitespace characters on the line, move to the end of the line. - -@item M-i -@kindex M-i -@findex tab-to-tab-stop -Indent whitespace at point, up to the next tab stop -(@code{tab-to-tab-stop}). @xref{Tab Stops}. - -@findex indent-relative -@item M-x indent-relative -Insert whitespace at point, until point is aligned with the first -non-whitespace character on the previous line (actually, the last -non-blank line). If point is already farther right than that, run -@code{tab-to-tab-stop} instead---unless called with a numeric -argument, in which case do nothing. - -@item M-^ -@kindex M-^ -@findex delete-indentation -Merge the previous and the current line (@code{delete-indentation}). -This ``joins'' the two lines cleanly, by replacing any indentation at -the front of the current line, together with the line boundary, with a -single space. - -As a special case (useful for Lisp code), the single space is omitted -if the characters to be joined are consecutive opening and closing -parentheses, or if the junction follows another newline. - -If there is a fill prefix, @kbd{M-^} deletes the fill prefix if it -appears after the newline that is deleted. @xref{Fill Prefix}. - -@item C-M-\ -@kindex C-M-\ -@findex indent-region -Indent all the lines in the region, as though you had typed @key{TAB} -at the beginning of each line (@code{indent-region}). - -If a numeric argument is supplied, indent every line in the region to -that column number. - -@item C-x @key{TAB} -@kindex C-x TAB -@findex indent-rigidly -@cindex remove indentation -Shift each line in the region by a fixed distance, to the right or -left (@code{indent-rigidly}). The distance to move is determined by -the numeric argument (positive to move rightward, negative to move -leftward). - -This command can be used to remove all indentation from the lines in -the region, by invoking it with a large negative argument, -e.g. @kbd{C-u -1000 C-x @key{TAB}}. -@end table - -@node Tab Stops -@section Tab Stops -@cindex tab stops - -@vindex tab-stop-list - Emacs defines certain column numbers to be @dfn{tab stops}. These -are used as stopping points by @key{TAB} when inserting whitespace in -Text mode and related modes (@pxref{Indentation}), and by commands -like @kbd{M-i} (@pxref{Indentation Commands}). By default, tab stops -are located every 8 columns. These positions are stored in the -variable @code{tab-stop-list}, whose value is a list of column numbers -in increasing order. - -@findex edit-tab-stops -@kindex C-c C-c @r{(Edit Tab Stops)} - Instead of customizing the variable @code{tab-stop-list} directly, a -convenient way to view and set tab stops is via the command @kbd{M-x -edit-tab-stops}. This switches to a buffer containing a description -of the tab stop settings, which looks like this: - -@example - : : : : : : -0 1 2 3 4 -0123456789012345678901234567890123456789012345678 -To install changes, type C-c C-c -@end example - -@noindent -The first line contains a colon at each tab stop. The numbers on the -next two lines are present just to indicate where the colons are. - - You can edit this buffer to specify different tab stops by placing -colons on the desired columns. The buffer uses Overwrite mode -(@pxref{Minor Modes}). When you are done, type @kbd{C-c C-c} to make -the new tab stops take effect. Normally, the new tab stop settings -apply to all buffers. However, if you have made the -@code{tab-stop-list} variable local to the buffer where you called -@kbd{M-x edit-tab-stops} (@pxref{Locals}), then the new tab stop -settings apply only to that buffer. To save the tab stop settings for -future Emacs sessions, use the Customize interface to save the value -of @code{tab-stop-list} (@pxref{Easy Customization}). - - Note that the tab stops discussed in this section have nothing to do -with how tab characters are displayed in the buffer. Tab characters -are always displayed as empty spaces extending to the next -@dfn{display tab stop}. @xref{Text Display}. - -@node Just Spaces -@section Tabs vs. Spaces - -@vindex tab-width - Normally, indentation commands insert (or remove) an optimal mix of -space characters and tab characters to align to the desired column. -Tab characters are displayed as a stretch of empty space extending to -the next @dfn{display tab stop}. By default, there is one display tab -stop every @code{tab-width} columns (the default is 8). @xref{Text -Display}. - -@vindex indent-tabs-mode - If you prefer, all indentation can be made from spaces only. To -request this, set the buffer-local variable @code{indent-tabs-mode} to -@code{nil}. @xref{Locals}, for information about setting buffer-local -variables. Note, however, that @kbd{C-q @key{TAB}} always inserts a -tab character, regardless of the value of @code{indent-tabs-mode}. - - One reason to set @code{indent-tabs-mode} to @code{nil} is that not -all editors display tab characters in the same way. Emacs users, too, -may have different customized values of @code{tab-width}. By using -spaces only, you can make sure that your file always looks the same. -If you only care about how it looks within Emacs, another way to -tackle this problem is to set the @code{tab-width} variable in a -file-local variable (@pxref{File Variables}). - -@findex tabify -@findex untabify - There are also commands to convert tabs to spaces or vice versa, always -preserving the columns of all non-whitespace text. @kbd{M-x tabify} scans the -region for sequences of spaces, and converts sequences of at least two -spaces to tabs if that can be done without changing indentation. @kbd{M-x -untabify} changes all tabs in the region to appropriate numbers of spaces. - -@node Indent Convenience -@section Convenience Features for Indentation - -@vindex tab-always-indent - The variable @code{tab-always-indent} tweaks the behavior of the -@key{TAB} (@code{indent-for-tab-command}) command. The default value, -@code{t}, gives the behavior described in @ref{Indentation}. If you -change the value to the symbol @code{complete}, then @key{TAB} first -tries to indent the current line, and if the line was already -indented, it tries to complete the text at point (@pxref{Symbol -Completion}). If the value is @code{nil}, then @key{TAB} indents the -current line only if point is at the left margin or in the line's -indentation; otherwise, it inserts a tab character. - -@cindex Electric Indent mode -@cindex mode, Electric Indent -@findex electric-indent-mode - Electric Indent mode is a global minor mode that automatically -indents the line after every @key{RET} you type. To toggle this minor -mode, type @kbd{M-x electric-indent-mode}. diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi deleted file mode 100644 index 270ca9e77a8..00000000000 --- a/doc/emacs/killing.texi +++ /dev/null @@ -1,872 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. - -@node Killing, Registers, Mark, Top -@chapter Killing and Moving Text - - In Emacs, @dfn{killing} means erasing text and copying it into the -@dfn{kill ring}. @dfn{Yanking} means bringing text from the kill ring -back into the buffer. (Some applications use the terms ``cutting'' -and ``pasting'' for similar operations.) The kill ring is so-named -because it can be visualized as a set of blocks of text arranged in a -ring, which you can access in cyclic order. @xref{Kill Ring}. - - Killing and yanking are the most common way to move or copy text -within Emacs. It is very versatile, because there are commands for -killing many different types of syntactic units. - -@menu -* Deletion and Killing:: Commands that remove text. -* Yanking:: Commands that insert text. -* Cut and Paste:: Clipboard and selections on graphical displays. -* Accumulating Text:: Other methods to add text to the buffer. -* Rectangles:: Operating on text in rectangular areas. -* CUA Bindings:: Using @kbd{C-x}/@kbd{C-c}/@kbd{C-v} to kill and yank. -@end menu - -@node Deletion and Killing -@section Deletion and Killing - -@cindex killing text -@cindex cutting text -@cindex deletion - Most commands which erase text from the buffer save it in the kill -ring. These are known as @dfn{kill} commands, and their names -normally contain the word @samp{kill} (e.g. @code{kill-line}). The -kill ring stores several recent kills, not just the last one, so -killing is a very safe operation: you don't have to worry much about -losing text that you previously killed. The kill ring is shared by -all buffers, so text that is killed in one buffer can be yanked into -another buffer. - - When you use @kbd{C-/} (@code{undo}) to undo a kill command -(@pxref{Undo}), that brings the killed text back into the buffer, but -does not remove it from the kill ring. - - On graphical displays, killing text also copies it to the system -clipboard. @xref{Cut and Paste}. - - Commands that erase text but do not save it in the kill ring are -known as @dfn{delete} commands; their names usually contain the word -@samp{delete}. These include @kbd{C-d} (@code{delete-char}) and -@key{DEL} (@code{delete-backward-char}), which delete only one -character at a time, and those commands that delete only spaces or -newlines. Commands that can erase significant amounts of nontrivial -data generally do a kill operation instead. - - You can also use the mouse to kill and yank. @xref{Cut and Paste}. - -@menu -* Deletion:: Commands for deleting small amounts of text and - blank areas. -* Killing by Lines:: How to kill entire lines of text at one time. -* Other Kill Commands:: Commands to kill large regions of text and - syntactic units such as words and sentences. -* Kill Options:: Options that affect killing. -@end menu - -@node Deletion -@subsection Deletion -@findex delete-backward-char -@findex delete-char - - Deletion means erasing text and not saving it in the kill ring. For -the most part, the Emacs commands that delete text are those that -erase just one character or only whitespace. - -@table @kbd -@item @key{DEL} -@itemx @key{Backspace} -Delete the previous character, or the text in the region if it is -active (@code{delete-backward-char}). - -@item @key{Delete} -Delete the next character, or the text in the region if it is active -(@code{delete-forward-char}). - -@item C-d -Delete the next character (@code{delete-char}). - -@item M-\ -Delete spaces and tabs around point (@code{delete-horizontal-space}). -@item M-@key{SPC} -Delete spaces and tabs around point, leaving one space -(@code{just-one-space}). -@item C-x C-o -Delete blank lines around the current line (@code{delete-blank-lines}). -@item M-^ -Join two lines by deleting the intervening newline, along with any -indentation following it (@code{delete-indentation}). -@end table - - We have already described the basic deletion commands @key{DEL} -(@code{delete-backward-char}), @key{delete} -(@code{delete-forward-char}), and @kbd{C-d} (@code{delete-char}). -@xref{Erasing}. With a numeric argument, they delete the specified -number of characters. If the numeric argument is omitted or one, they -delete all the text in the region if it is active (@pxref{Using -Region}). - -@kindex M-\ -@findex delete-horizontal-space -@kindex M-SPC -@findex just-one-space - The other delete commands are those that delete only whitespace -characters: spaces, tabs and newlines. @kbd{M-\} -(@code{delete-horizontal-space}) deletes all the spaces and tab -characters before and after point. With a prefix argument, this only -deletes spaces and tab characters before point. @kbd{M-@key{SPC}} -(@code{just-one-space}) does likewise but leaves a single space before -point, regardless of the number of spaces that existed previously -(even if there were none before). With a numeric argument @var{n}, it -leaves @var{n} spaces before point if @var{n} is positive; if @var{n} -is negative, it deletes newlines in addition to spaces and tabs, -leaving a single space before point. - - @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines -after the current line. If the current line is blank, it deletes all -blank lines preceding the current line as well (leaving one blank line, -the current line). On a solitary blank line, it deletes that line. - - @kbd{M-^} (@code{delete-indentation}) joins the current line and the -previous line, by deleting a newline and all surrounding spaces, usually -leaving a single space. @xref{Indentation,M-^}. - -@node Killing by Lines -@subsection Killing by Lines - -@table @kbd -@item C-k -Kill rest of line or one or more lines (@code{kill-line}). -@item C-S-backspace -Kill an entire line at once (@code{kill-whole-line}) -@end table - -@kindex C-k -@findex kill-line - The simplest kill command is @kbd{C-k} (@code{kill-line}). If used -at the end of a line, it kills the line-ending newline character, -merging the next line into the current one (thus, a blank line is -entirely removed). Otherwise, @kbd{C-k} kills all the text from point -up to the end of the line; if point was originally at the beginning of -the line, this leaves the line blank. - - Spaces and tabs at the end of the line are ignored when deciding -which case applies. As long as point is after the last visible -character in the line, you can be sure that @kbd{C-k} will kill the -newline. To kill an entire non-blank line, go to the beginning and -type @kbd{C-k} twice. - - In this context, ``line'' means a logical text line, not a screen -line (@pxref{Continuation Lines}). - - When @kbd{C-k} is given a positive argument @var{n}, it kills -@var{n} lines and the newlines that follow them (text on the current -line before point is not killed). With a negative argument -@minus{}@var{n}, it kills @var{n} lines preceding the current line, -together with the text on the current line before point. @kbd{C-k} -with an argument of zero kills the text before point on the current -line. - -@vindex kill-whole-line - If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} at -the very beginning of a line kills the entire line including the -following newline. This variable is normally @code{nil}. - -@kindex C-S-backspace -@findex kill-whole-line - @kbd{C-S-backspace} (@code{kill-whole-line}) kills a whole line -including its newline, regardless of the position of point within the -line. Note that many text terminals will prevent you from typing the -key sequence @kbd{C-S-backspace}. - -@node Other Kill Commands -@subsection Other Kill Commands -@findex kill-region -@kindex C-w - -@table @kbd -@item C-w -Kill the region (@code{kill-region}). -@item M-w -Copy the region into the kill ring (@code{kill-ring-save}). -@item M-d -Kill the next word (@code{kill-word}). @xref{Words}. -@item M-@key{DEL} -Kill one word backwards (@code{backward-kill-word}). -@item C-x @key{DEL} -Kill back to beginning of sentence (@code{backward-kill-sentence}). -@xref{Sentences}. -@item M-k -Kill to the end of the sentence (@code{kill-sentence}). -@item C-M-k -Kill the following balanced expression (@code{kill-sexp}). @xref{Expressions}. -@item M-z @var{char} -Kill through the next occurrence of @var{char} (@code{zap-to-char}). -@end table - -@kindex C-w -@findex kill-region -@kindex M-w -@findex kill-ring-save - One of the commonly-used kill commands is @kbd{C-w} -(@code{kill-region}), which kills the text in the region -(@pxref{Mark}). Similarly, @kbd{M-w} (@code{kill-ring-save}) copies -the text in the region into the kill ring without removing it from the -buffer. If the mark is inactive when you type @kbd{C-w} or @kbd{M-w}, -the command acts on the text between point and where you last set the -mark (@pxref{Using Region}). - - Emacs also provides commands to kill specific syntactic units: -words, with @kbd{M-@key{DEL}} and @kbd{M-d} (@pxref{Words}); balanced -expressions, with @kbd{C-M-k} (@pxref{Expressions}); and sentences, -with @kbd{C-x @key{DEL}} and @kbd{M-k} (@pxref{Sentences}). - -@kindex M-z -@findex zap-to-char - The command @kbd{M-z} (@code{zap-to-char}) combines killing with -searching: it reads a character and kills from point up to (and -including) the next occurrence of that character in the buffer. A -numeric argument acts as a repeat count; a negative argument means to -search backward and kill text before point. - -@node Kill Options -@subsection Options for Killing - -@vindex kill-read-only-ok -@cindex read-only text, killing - Some specialized buffers contain @dfn{read-only text}, which cannot -be modified and therefore cannot be killed. The kill commands work -specially in a read-only buffer: they move over text and copy it to -the kill ring, without actually deleting it from the buffer. -Normally, they also beep and display an error message when this -happens. But if you set the variable @code{kill-read-only-ok} to a -non-@code{nil} value, they just print a message in the echo area to -explain why the text has not been erased. - -@vindex kill-do-not-save-duplicates - If you change the variable @code{kill-do-not-save-duplicates} to a -non-@code{nil} value, identical subsequent kills yield a single -kill-ring entry, without duplication. - -@node Yanking -@section Yanking -@cindex moving text -@cindex copying text -@cindex kill ring -@cindex yanking -@cindex pasting - - @dfn{Yanking} means reinserting text previously killed. The usual -way to move or copy text is to kill it and then yank it elsewhere. - -@table @kbd -@item C-y -Yank the last kill into the buffer, at point (@code{yank}). -@item M-y -Replace the text just yanked with an earlier batch of killed text -(@code{yank-pop}). @xref{Earlier Kills}. -@item C-M-w -Cause the following command, if it is a kill command, to append to the -previous kill (@code{append-next-kill}). @xref{Appending Kills}. -@end table - -@kindex C-y -@findex yank - The basic yanking command is @kbd{C-y} (@code{yank}). It inserts -the most recent kill, leaving the cursor at the end of the inserted -text. It also sets the mark at the beginning of the inserted text, -without activating the mark; this lets you jump easily to that -position, if you wish, with @kbd{C-u C-@key{SPC}} (@pxref{Mark Ring}). - - With a plain prefix argument (@kbd{C-u C-y}), the command instead -leaves the cursor in front of the inserted text, and sets the mark at -the end. Using any other prefix argument specifies an earlier kill; -e.g. @kbd{C-u 4 C-y} reinserts the fourth most recent kill. -@xref{Earlier Kills}. - - On graphical displays, @kbd{C-y} first checks if another application -has placed any text in the system clipboard more recently than the -last Emacs kill. If so, it inserts the text in the clipboard instead. -Thus, Emacs effectively treats ``cut'' or ``copy'' clipboard -operations performed in other applications like Emacs kills, except -that they are not recorded in the kill ring. @xref{Cut and Paste}, -for details. - -@menu -* Kill Ring:: Where killed text is stored. -* Earlier Kills:: Yanking something killed some time ago. -* Appending Kills:: Several kills in a row all yank together. -@end menu - -@node Kill Ring -@subsection The Kill Ring - - The @dfn{kill ring} is a list of blocks of text that were previously -killed. There is only one kill ring, shared by all buffers, so you -can kill text in one buffer and yank it in another buffer. This is -the usual way to move text from one buffer to another. (There are -several other methods: for instance, you could store the text in a -register; see @ref{Registers}. @xref{Accumulating Text}, for some -other ways to move text around.) - -@vindex kill-ring-max - The maximum number of entries in the kill ring is controlled by the -variable @code{kill-ring-max}. The default is 60. If you make a new -kill when this limit has been reached, Emacs makes room by deleting -the oldest entry in the kill ring. - -@vindex kill-ring - The actual contents of the kill ring are stored in a variable named -@code{kill-ring}; you can view the entire contents of the kill ring -with @kbd{C-h v kill-ring}. - -@node Earlier Kills -@subsection Yanking Earlier Kills -@cindex yanking previous kills - - As explained in @ref{Yanking}, you can use a numeric argument to -@kbd{C-y} to yank text that is no longer the most recent kill. This -is useful if you remember which kill ring entry you want. If you -don't, you can use the @kbd{M-y} (@code{yank-pop}) command to cycle -through the possibilities. - -@kindex M-y -@findex yank-pop - If the previous command was a yank command, @kbd{M-y} takes the text -that was yanked and replaces it with the text from an earlier kill. -So, to recover the text of the next-to-the-last kill, first use -@kbd{C-y} to yank the last kill, and then use @kbd{M-y} to replace it -with the previous kill. @kbd{M-y} is allowed only after a @kbd{C-y} -or another @kbd{M-y}. - - You can understand @kbd{M-y} in terms of a ``last yank'' pointer which -points at an entry in the kill ring. Each time you kill, the ``last -yank'' pointer moves to the newly made entry at the front of the ring. -@kbd{C-y} yanks the entry which the ``last yank'' pointer points to. -@kbd{M-y} moves the ``last yank'' pointer to a different entry, and the -text in the buffer changes to match. Enough @kbd{M-y} commands can move -the pointer to any entry in the ring, so you can get any entry into the -buffer. Eventually the pointer reaches the end of the ring; the next -@kbd{M-y} loops back around to the first entry again. - - @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does -not change the order of the entries in the ring, which always runs from -the most recent kill at the front to the oldest one still remembered. - - @kbd{M-y} can take a numeric argument, which tells it how many entries -to advance the ``last yank'' pointer by. A negative argument moves the -pointer toward the front of the ring; from the front of the ring, it -moves ``around'' to the last entry and continues forward from there. - - Once the text you are looking for is brought into the buffer, you can -stop doing @kbd{M-y} commands and it will stay there. It's just a copy -of the kill ring entry, so editing it in the buffer does not change -what's in the ring. As long as no new killing is done, the ``last -yank'' pointer remains at the same place in the kill ring, so repeating -@kbd{C-y} will yank another copy of the same previous kill. - - When you call @kbd{C-y} with a numeric argument, that also sets the -``last yank'' pointer to the entry that it yanks. - -@node Appending Kills -@subsection Appending Kills - -@cindex appending kills in the ring - Normally, each kill command pushes a new entry onto the kill ring. -However, two or more kill commands in a row combine their text into a -single entry, so that a single @kbd{C-y} yanks all the text as a unit, -just as it was before it was killed. - - Thus, if you want to yank text as a unit, you need not kill all of it -with one command; you can keep killing line after line, or word after -word, until you have killed it all, and you can still get it all back at -once. - - Commands that kill forward from point add onto the end of the previous -killed text. Commands that kill backward from point add text onto the -beginning. This way, any sequence of mixed forward and backward kill -commands puts all the killed text into one entry without rearrangement. -Numeric arguments do not break the sequence of appending kills. For -example, suppose the buffer contains this text: - -@example -This is a line @point{}of sample text. -@end example - -@noindent -with point shown by @point{}. If you type @kbd{M-d M-@key{DEL} M-d -M-@key{DEL}}, killing alternately forward and backward, you end up with -@samp{a line of sample} as one entry in the kill ring, and @samp{This -is@ @ text.} in the buffer. (Note the double space between @samp{is} -and @samp{text}, which you can clean up with @kbd{M-@key{SPC}} or -@kbd{M-q}.) - - Another way to kill the same text is to move back two words with -@kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}. -This produces exactly the same results in the buffer and in the kill -ring. @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going -backward; once again, the result is the same. The text in the kill ring -entry always has the same order that it had in the buffer before you -killed it. - -@kindex C-M-w -@findex append-next-kill - If a kill command is separated from the last kill command by other -commands (not just numeric arguments), it starts a new entry on the kill -ring. But you can force it to append by first typing the command -@kbd{C-M-w} (@code{append-next-kill}) right before it. The @kbd{C-M-w} -tells the following command, if it is a kill command, to append the text -it kills to the last killed text, instead of starting a new entry. With -@kbd{C-M-w}, you can kill several separated pieces of text and -accumulate them to be yanked back in one place.@refill - - A kill command following @kbd{M-w} (@code{kill-ring-save}) does not -append to the text that @kbd{M-w} copied into the kill ring. - -@node Cut and Paste -@section ``Cut and Paste'' Operations on Graphical Displays -@cindex cut -@cindex copy -@cindex paste - - In most graphical desktop environments, you can transfer data -(usually text) between different applications using a system facility -called the @dfn{clipboard}. On X, two other similar facilities are -available: the primary selection and the secondary selection. When -Emacs is run on a graphical display, its kill and yank commands -integrate with these facilities, so that you can easily transfer text -between Emacs and other graphical applications. - - By default, Emacs uses UTF-8 as the coding system for inter-program -text transfers. If you find that the pasted text is not what you -expected, you can specify another coding system by typing @kbd{C-x -@key{RET} x} or @kbd{C-x @key{RET} X}. You can also request a -different data type by customizing @code{x-select-request-type}. -@xref{Communication Coding}. - -@menu -* Clipboard:: How Emacs uses the system clipboard. -* Primary Selection:: The temporarily selected text selection. -* Secondary Selection:: Cutting without altering point and mark. -@end menu - -@node Clipboard -@subsection Using the Clipboard -@cindex clipboard - - The @dfn{clipboard} is the facility that most graphical applications -use for ``cutting and pasting''. When the clipboard exists, the kill -and yank commands in Emacs make use of it. - - When you kill some text with a command such as @kbd{C-w} -(@code{kill-region}), or copy it to the kill ring with a command such -as @kbd{M-w} (@code{kill-ring-save}), that text is also put in the -clipboard. - -@vindex save-interprogram-paste-before-kill - When an Emacs kill command puts text in the clipboard, the existing -clipboard contents are normally lost. Optionally, you can change -@code{save-interprogram-paste-before-kill} to @code{t}. Then Emacs -will first save the clipboard to its kill ring, preventing you from -losing the old clipboard data---at the risk of high memory consumption -if that data turns out to be large. - - Yank commands, such as @kbd{C-y} (@code{yank}), also use the -clipboard. If another application ``owns'' the clipboard---i.e., if -you cut or copied text there more recently than your last kill command -in Emacs---then Emacs yanks from the clipboard instead of the kill -ring. - -@vindex yank-pop-change-selection - Normally, rotating the kill ring with @kbd{M-y} (@code{yank-pop}) -does not alter the clipboard. However, if you change -@code{yank-pop-change-selection} to @code{t}, then @kbd{M-y} saves the -new yank to the clipboard. - -@vindex x-select-enable-clipboard - To prevent kill and yank commands from accessing the clipboard, -change the variable @code{x-select-enable-clipboard} to @code{nil}. - -@cindex clipboard manager -@vindex x-select-enable-clipboard-manager - Many X desktop environments support a feature called the -@dfn{clipboard manager}. If you exit Emacs while it is the current -``owner'' of the clipboard data, and there is a clipboard manager -running, Emacs transfers the clipboard data to the clipboard manager -so that it is not lost. In some circumstances, this may cause a delay -when exiting Emacs; if you wish to prevent Emacs from transferring -data to the clipboard manager, change the variable -@code{x-select-enable-clipboard-manager} to @code{nil}. - -@vindex x-select-enable-primary -@findex clipboard-kill-region -@findex clipboard-kill-ring-save -@findex clipboard-yank - Prior to Emacs 24, the kill and yank commands used the primary -selection (@pxref{Primary Selection}), not the clipboard. If you -prefer this behavior, change @code{x-select-enable-clipboard} to -@code{nil}, @code{x-select-enable-primary} to @code{t}, and -@code{mouse-drag-copy-region} to @code{t}. In this case, you can use -the following commands to act explicitly on the clipboard: -@code{clipboard-kill-region} kills the region and saves it to the -clipboard; @code{clipboard-kill-ring-save} copies the region to the -kill ring and saves it to the clipboard; and @code{clipboard-yank} -yanks the contents of the clipboard at point. - -@node Primary Selection -@subsection Cut and Paste with Other Window Applications -@cindex X cutting and pasting -@cindex X selection -@cindex primary selection -@cindex selection, primary - - Under the X Window System, there exists a @dfn{primary selection} -containing the last stretch of text selected in an X application -(usually by dragging the mouse). Typically, this text can be inserted -into other X applications by @kbd{mouse-2} clicks. The primary -selection is separate from the clipboard. Its contents are more -``fragile''; they are overwritten each time you select text with the -mouse, whereas the clipboard is only overwritten by explicit ``cut'' -or ``copy'' commands. - - Under X, whenever the region is active (@pxref{Mark}), the text in -the region is saved in the primary selection. This applies regardless -of whether the region was made by dragging or clicking the mouse -(@pxref{Mouse Commands}), or by keyboard commands (e.g. by typing -@kbd{C-@key{SPC}} and moving point; @pxref{Setting Mark}). - -@vindex select-active-regions - If you change the variable @code{select-active-regions} to -@code{only}, Emacs saves only temporarily active regions to the -primary selection, i.e. those made with the mouse or with shift -selection (@pxref{Shift Selection}). If you change -@code{select-active-regions} to @code{nil}, Emacs avoids saving active -regions to the primary selection entirely. - - To insert the primary selection into an Emacs buffer, click -@kbd{mouse-2} (@code{mouse-yank-primary}) where you want to insert it. -@xref{Mouse Commands}. - -@cindex MS-Windows, and primary selection - MS-Windows provides no primary selection, but Emacs emulates it -within a single Emacs session by storing the selected text internally. -Therefore, all the features and commands related to the primary -selection work on Windows as they do on X, for cutting and pasting -within the same session, but not across Emacs sessions or with other -applications. - -@node Secondary Selection -@subsection Secondary Selection -@cindex secondary selection - - In addition to the primary selection, the X Window System provides a -second similar facility known as the @dfn{secondary selection}. -Nowadays, few X applications make use of the secondary selection, but -you can access it using the following Emacs commands: - -@table @kbd -@findex mouse-set-secondary -@kindex M-Drag-Mouse-1 -@item M-Drag-Mouse-1 -Set the secondary selection, with one end at the place where you press -down the button, and the other end at the place where you release it -(@code{mouse-set-secondary}). The selected text is highlighted, using -the @code{secondary-selection} face, as you drag. The window scrolls -automatically if you drag the mouse off the top or bottom of the -window, just like @code{mouse-set-region} (@pxref{Mouse Commands}). - -This command does not alter the kill ring. - -@findex mouse-start-secondary -@kindex M-Mouse-1 -@item M-Mouse-1 -Set one endpoint for the @dfn{secondary selection} -(@code{mouse-start-secondary}). - -@findex mouse-secondary-save-then-kill -@kindex M-Mouse-3 -@item M-Mouse-3 -Set the secondary selection, with one end at the position clicked and -the other at the position specified with @kbd{M-Mouse-1} -(@code{mouse-secondary-save-then-kill}). This also puts the selected -text in the kill ring. A second @kbd{M-Mouse-3} at the same place -kills the secondary selection just made. - -@findex mouse-yank-secondary -@kindex M-Mouse-2 -@item M-Mouse-2 -Insert the secondary selection where you click, placing point at the -end of the yanked text (@code{mouse-yank-secondary}). -@end table - -Double or triple clicking of @kbd{M-Mouse-1} operates on words and -lines, much like @kbd{Mouse-1}. - -If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-Mouse-2} yanks -at point. Then it does not matter precisely where you click, or even -which of the frame's windows you click on. @xref{Mouse Commands}. - -@node Accumulating Text -@section Accumulating Text -@findex append-to-buffer -@findex prepend-to-buffer -@findex copy-to-buffer -@findex append-to-file - -@cindex accumulating scattered text - Usually we copy or move text by killing it and yanking it, but there -are other convenient methods for copying one block of text in many -places, or for copying many scattered blocks of text into one place. -Here we describe the commands to accumulate scattered pieces of text -into a buffer or into a file. - -@table @kbd -@item M-x append-to-buffer -Append region to the contents of a specified buffer. -@item M-x prepend-to-buffer -Prepend region to the contents of a specified buffer. -@item M-x copy-to-buffer -Copy region into a specified buffer, deleting that buffer's old contents. -@item M-x insert-buffer -Insert the contents of a specified buffer into current buffer at point. -@item M-x append-to-file -Append region to the contents of a specified file, at the end. -@end table - - To accumulate text into a buffer, use @kbd{M-x append-to-buffer}. -This reads a buffer name, then inserts a copy of the region into the -buffer specified. If you specify a nonexistent buffer, -@code{append-to-buffer} creates the buffer. The text is inserted -wherever point is in that buffer. If you have been using the buffer for -editing, the copied text goes into the middle of the text of the buffer, -starting from wherever point happens to be at that moment. - - Point in that buffer is left at the end of the copied text, so -successive uses of @code{append-to-buffer} accumulate the text in the -specified buffer in the same order as they were copied. Strictly -speaking, @code{append-to-buffer} does not always append to the text -already in the buffer---it appends only if point in that buffer is at -the end. However, if @code{append-to-buffer} is the only command you -use to alter a buffer, then point is always at the end. - - @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer} -except that point in the other buffer is left before the copied text, so -successive prependings add text in reverse order. @kbd{M-x -copy-to-buffer} is similar, except that any existing text in the other -buffer is deleted, so the buffer is left containing just the text newly -copied into it. - - The command @kbd{M-x insert-buffer} can be used to retrieve the -accumulated text from another buffer. This prompts for the name of a -buffer, and inserts a copy of all the text in that buffer into the -current buffer at point, leaving point at the beginning of the -inserted text. It also adds the position of the end of the inserted -text to the mark ring, without activating the mark. @xref{Buffers}, -for background information on buffers. - - Instead of accumulating text in a buffer, you can append text -directly into a file with @kbd{M-x append-to-file}. This prompts for -a filename, and adds the text of the region to the end of the -specified file. The file is changed immediately on disk. - - You should use @code{append-to-file} only with files that are -@emph{not} being visited in Emacs. Using it on a file that you are -editing in Emacs would change the file behind Emacs's back, which -can lead to losing some of your editing. - - Another way to move text around is to store it in a register. -@xref{Registers}. - -@node Rectangles -@section Rectangles -@cindex rectangle -@cindex columns (and rectangles) -@cindex killing rectangular areas of text - - @dfn{Rectangle} commands operate on rectangular areas of the text: -all the characters between a certain pair of columns, in a certain -range of lines. Emacs has commands to kill rectangles, yank killed -rectangles, clear them out, fill them with blanks or text, or delete -them. Rectangle commands are useful with text in multicolumn formats, -and for changing text into or out of such formats. - -@cindex mark rectangle - To specify a rectangle for a command to work on, set the mark at one -corner and point at the opposite corner. The rectangle thus specified -is called the @dfn{region-rectangle}. If point and the mark are in -the same column, the region-rectangle is empty. If they are in the -same line, the region-rectangle is one line high. - - The region-rectangle is controlled in much the same way as the -region is controlled. But remember that a given combination of point -and mark values can be interpreted either as a region or as a -rectangle, depending on the command that uses them. - -@table @kbd -@item C-x r k -Kill the text of the region-rectangle, saving its contents as the -``last killed rectangle'' (@code{kill-rectangle}). -@item C-x r d -Delete the text of the region-rectangle (@code{delete-rectangle}). -@item C-x r y -Yank the last killed rectangle with its upper left corner at point -(@code{yank-rectangle}). -@item C-x r o -Insert blank space to fill the space of the region-rectangle -(@code{open-rectangle}). This pushes the previous contents of the -region-rectangle to the right. -@item C-x r N -Insert line numbers along the left edge of the region-rectangle -(@code{rectangle-number-lines}). This pushes the previous contents of -the region-rectangle to the right. -@item C-x r c -Clear the region-rectangle by replacing all of its contents with spaces -(@code{clear-rectangle}). -@item M-x delete-whitespace-rectangle -Delete whitespace in each of the lines on the specified rectangle, -starting from the left edge column of the rectangle. -@item C-x r t @var{string} @key{RET} -Replace rectangle contents with @var{string} on each line -(@code{string-rectangle}). -@item M-x string-insert-rectangle @key{RET} @var{string} @key{RET} -Insert @var{string} on each line of the rectangle. -@end table - - The rectangle operations fall into two classes: commands to erase or -insert rectangles, and commands to make blank rectangles. - -@kindex C-x r k -@kindex C-x r d -@findex kill-rectangle -@findex delete-rectangle - There are two ways to erase the text in a rectangle: @kbd{C-x r d} -(@code{delete-rectangle}) to delete the text outright, or @kbd{C-x r -k} (@code{kill-rectangle}) to remove the text and save it as the -@dfn{last killed rectangle}. In both cases, erasing the -region-rectangle is like erasing the specified text on each line of -the rectangle; if there is any following text on the line, it moves -backwards to fill the gap. - - ``Killing'' a rectangle is not killing in the usual sense; the -rectangle is not stored in the kill ring, but in a special place that -only records the most recent rectangle killed. This is because -yanking a rectangle is so different from yanking linear text that -different yank commands have to be used. Yank-popping is not defined -for rectangles. - -@kindex C-x r y -@findex yank-rectangle - To yank the last killed rectangle, type @kbd{C-x r y} -(@code{yank-rectangle}). The rectangle's first line is inserted at -point, the rectangle's second line is inserted at the same horizontal -position one line vertically below, and so on. The number of lines -affected is determined by the height of the saved rectangle. - - For example, you can convert two single-column lists into a -double-column list by killing one of the single-column lists as a -rectangle, and then yanking it beside the other list. - - You can also copy rectangles into and out of registers with @kbd{C-x r -r @var{r}} and @kbd{C-x r i @var{r}}. @xref{Rectangle Registers}. - -@kindex C-x r o -@findex open-rectangle -@kindex C-x r c -@findex clear-rectangle - There are two commands you can use for making blank rectangles: -@kbd{C-x r c} (@code{clear-rectangle}) blanks out existing text in the -region-rectangle, and @kbd{C-x r o} (@code{open-rectangle}) inserts a -blank rectangle. - -@findex delete-whitespace-rectangle - @kbd{M-x delete-whitespace-rectangle} deletes horizontal whitespace -starting from a particular column. This applies to each of the lines -in the rectangle, and the column is specified by the left edge of the -rectangle. The right edge of the rectangle does not make any -difference to this command. - -@kindex C-x r N -@findex rectangle - The command @kbd{C-x r N} (@code{rectangle-number-lines}) inserts -line numbers along the left edge of the region-rectangle. Normally, -the numbering begins from 1 (for the first line of the rectangle). -With a prefix argument, the command prompts for a number to begin -from, and for a format string with which to print the numbers -(@pxref{Formatting Strings,,, elisp, The Emacs Lisp Reference -Manual}). - -@kindex C-x r t -@findex string-rectangle - The command @kbd{C-x r t} (@code{string-rectangle}) replaces the -contents of a region-rectangle with a string on each line. The -string's width need not be the same as the width of the rectangle. If -the string's width is less, the text after the rectangle shifts left; -if the string is wider than the rectangle, the text after the -rectangle shifts right. - -@findex string-insert-rectangle - The command @kbd{M-x string-insert-rectangle} is similar to -@code{string-rectangle}, but inserts the string on each line, -shifting the original text to the right. - -@node CUA Bindings -@section CUA Bindings -@findex cua-mode -@vindex cua-mode -@cindex CUA key bindings -@vindex cua-enable-cua-keys - The command @kbd{M-x cua-mode} sets up key bindings that are -compatible with the Common User Access (CUA) system used in many other -applications. - - When CUA mode is enabled, the keys @kbd{C-x}, @kbd{C-c}, @kbd{C-v}, -and @kbd{C-z} invoke commands that cut (kill), copy, paste (yank), and -undo respectively. The @kbd{C-x} and @kbd{C-c} keys perform cut and -copy only if the region is active. Otherwise, they still act as -prefix keys, so that standard Emacs commands like @kbd{C-x C-c} still -work. Note that this means the variable @code{mark-even-if-inactive} -has no effect for @kbd{C-x} and @kbd{C-c} (@pxref{Using Region}). - - To enter an Emacs command like @kbd{C-x C-f} while the mark is -active, use one of the following methods: either hold @kbd{Shift} -together with the prefix key, e.g. @kbd{S-C-x C-f}, or quickly type -the prefix key twice, e.g. @kbd{C-x C-x C-f}. - - To disable the overriding of standard Emacs binding by CUA mode, -while retaining the other features of CUA mode described below, set -the variable @code{cua-enable-cua-keys} to @code{nil}. - - In CUA mode, typed text replaces the active region as in -Delete-Selection mode (@pxref{Mouse Commands}). - -@cindex rectangle highlighting - CUA mode provides enhanced rectangle support with visible -rectangle highlighting. Use @kbd{C-RET} to start a rectangle, -extend it using the movement commands, and cut or copy it using -@kbd{C-x} or @kbd{C-c}. @kbd{RET} moves the cursor to the next -(clockwise) corner of the rectangle, so you can easily expand it in -any direction. Normal text you type is inserted to the left or right -of each line in the rectangle (on the same side as the cursor). - - With CUA you can easily copy text and rectangles into and out of -registers by providing a one-digit numeric prefix to the kill, copy, -and yank commands, e.g. @kbd{C-1 C-c} copies the region into register -@code{1}, and @kbd{C-2 C-v} yanks the contents of register @code{2}. - -@cindex global mark - CUA mode also has a global mark feature which allows easy moving and -copying of text between buffers. Use @kbd{C-S-SPC} to toggle the -global mark on and off. When the global mark is on, all text that you -kill or copy is automatically inserted at the global mark, and text -you type is inserted at the global mark rather than at the current -position. - - For example, to copy words from various buffers into a word list in -a given buffer, set the global mark in the target buffer, then -navigate to each of the words you want in the list, mark it (e.g. with -@kbd{S-M-f}), copy it to the list with @kbd{C-c} or @kbd{M-w}, and -insert a newline after the word in the target list by pressing -@key{RET}. diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi deleted file mode 100644 index e7522a9db43..00000000000 --- a/doc/emacs/kmacro.texi +++ /dev/null @@ -1,573 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Keyboard Macros, Files, Fixit, Top -@chapter Keyboard Macros -@cindex defining keyboard macros -@cindex keyboard macro - - In this chapter we describe how to record a sequence of editing -commands so you can repeat it conveniently later. - - A @dfn{keyboard macro} is a command defined by an Emacs user to stand for -another sequence of keys. For example, if you discover that you are -about to type @kbd{C-n M-d C-d} forty times, you can speed your work by -defining a keyboard macro to do @kbd{C-n M-d C-d}, and then executing -it 39 more times. - - You define a keyboard macro by executing and recording the commands -which are its definition. Put differently, as you define a keyboard -macro, the definition is being executed for the first time. This way, -you can see the effects of your commands, so that you don't have to -figure them out in your head. When you close the definition, the -keyboard macro is defined and also has been, in effect, executed once. -You can then do the whole thing over again by invoking the macro. - - Keyboard macros differ from ordinary Emacs commands in that they are -written in the Emacs command language rather than in Lisp. This makes it -easier for the novice to write them, and makes them more convenient as -temporary hacks. However, the Emacs command language is not powerful -enough as a programming language to be useful for writing anything -intelligent or general. For such things, Lisp must be used. - -@menu -* Basic Keyboard Macro:: Defining and running keyboard macros. -* Keyboard Macro Ring:: Where previous keyboard macros are saved. -* Keyboard Macro Counter:: Inserting incrementing numbers in macros. -* Keyboard Macro Query:: Making keyboard macros do different things each - time. -* Save Keyboard Macro:: Giving keyboard macros names; saving them in - files. -* Edit Keyboard Macro:: Editing keyboard macros. -* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard - macro. -@end menu - -@node Basic Keyboard Macro -@section Basic Use - -@table @kbd -@item @key{F3} -Start defining a keyboard macro -(@code{kmacro-start-macro-or-insert-counter}). -@item @key{F4} -If a keyboard macro is being defined, end the definition; otherwise, -execute the most recent keyboard macro -(@code{kmacro-end-or-call-macro}). -@item C-u @key{F3} -Re-execute last keyboard macro, then append keys to its definition. -@item C-u C-u @key{F3} -Append keys to the last keyboard macro without re-executing it. -@item C-x C-k r -Run the last keyboard macro on each line that begins in the region -(@code{apply-macro-to-region-lines}). -@end table - -@kindex F3 -@kindex F4 -@findex kmacro-start-macro-or-insert-counter -@findex kmacro-end-or-call-macro -@findex kmacro-end-and-call-macro - To start defining a keyboard macro, type @key{F3}. From then on, -your keys continue to be executed, but also become part of the -definition of the macro. @samp{Def} appears in the mode line to -remind you of what is going on. When you are finished, type @key{F4} -(@code{kmacro-end-or-call-macro}) to terminate the definition. For -example, - -@example -@key{F3} M-f foo @key{F4} -@end example - -@noindent -defines a macro to move forward a word and then insert @samp{foo}. -Note that @key{F3} and @key{F4} do not become part of the macro. - - After defining the macro, you can call it with @key{F4}. For the -above example, this has the same effect as typing @kbd{M-f foo} again. -(Note the two roles of the @key{F4} command: it ends the macro if you -are in the process of defining one, or calls the last macro -otherwise.) You can also supply @key{F4} with a numeric prefix -argument @samp{n}, which means to invoke the macro @samp{n} times. An -argument of zero repeats the macro indefinitely, until it gets an -error or you type @kbd{C-g} (or, on MS-DOS, @kbd{C-@key{BREAK}}). - - The above example demonstrates a handy trick that you can employ -with keyboard macros: if you wish to repeat an operation at regularly -spaced places in the text, include a motion command as part of the -macro. In this case, repeating the macro inserts the string -@samp{foo} after each successive word. - - After terminating the definition of a keyboard macro, you can append -more keystrokes to its definition by typing @kbd{C-u @key{F3}}. This -is equivalent to plain @key{F3} followed by retyping the whole -definition so far. As a consequence, it re-executes the macro as -previously defined. If you change the variable -@code{kmacro-execute-before-append} to @code{nil}, the existing macro -will not be re-executed before appending to it (the default is -@code{t}). You can also add to the end of the definition of the last -keyboard macro without re-executing it by typing @kbd{C-u C-u -@key{F3}}. - - When a command reads an argument with the minibuffer, your -minibuffer input becomes part of the macro along with the command. So -when you replay the macro, the command gets the same argument as when -you entered the macro. For example, - -@example -@key{F3} C-a C-k C-x b foo @key{RET} C-y C-x b @key{RET} @key{F4} -@end example - -@noindent -defines a macro that kills the current line, yanks it into the buffer -@samp{foo}, then returns to the original buffer. - - Most keyboard commands work as usual in a keyboard macro definition, -with some exceptions. Typing @kbd{C-g} (@code{keyboard-quit}) quits -the keyboard macro definition. Typing @kbd{C-M-c} -(@code{exit-recursive-edit}) can be unreliable: it works as you'd -expect if exiting a recursive edit that started within the macro, but -if it exits a recursive edit that started before you invoked the -keyboard macro, it also necessarily exits the keyboard macro too. -Mouse events are also unreliable, even though you can use them in a -keyboard macro: when the macro replays the mouse event, it uses the -original mouse position of that event, the position that the mouse had -while you were defining the macro. The effect of this may be hard to -predict. - -@findex apply-macro-to-region-lines -@kindex C-x C-k r - The command @kbd{C-x C-k r} (@code{apply-macro-to-region-lines}) -repeats the last defined keyboard macro on each line that begins in -the region. It does this line by line, by moving point to the -beginning of the line and then executing the macro. - -@kindex C-x ( -@kindex C-x ) -@kindex C-x e -@findex kmacro-start-macro -@findex kmacro-end-macro - In addition to the @key{F3} and @key{F4} commands described above, -Emacs also supports an older set of key bindings for defining and -executing keyboard macros. To begin a macro definition, type @kbd{C-x -(} (@code{kmacro-start-macro}); as with @key{F3}, a prefix argument -appends this definition to the last keyboard macro. To end a macro -definition, type @kbd{C-x )} (@code{kmacro-end-macro}). To execute -the most recent macro, type @kbd{C-x e} -(@code{kmacro-end-and-call-macro}). If you enter @kbd{C-x e} while -defining a macro, the macro is terminated and executed immediately. -Immediately after typing @kbd{C-x e}, you can type @key{e} repeatedly -to immediately repeat the macro one or more times. You can also give -@kbd{C-x e} a repeat argument, just like @key{F4}. - - @kbd{C-x )} can be given a repeat count as an argument. This means -to repeat the macro right after defining it. The macro definition -itself counts as the first repetition, since it is executed as you -define it, so @kbd{C-u 4 C-x )} executes the macro immediately 3 -additional times. - -@node Keyboard Macro Ring -@section The Keyboard Macro Ring - - All defined keyboard macros are recorded in the @dfn{keyboard macro -ring}. There is only one keyboard macro ring, shared by all buffers. - -@table @kbd -@item C-x C-k C-k -Execute the keyboard macro at the head of the ring (@code{kmacro-end-or-call-macro-repeat}). -@item C-x C-k C-n -Rotate the keyboard macro ring to the next macro (defined earlier) -(@code{kmacro-cycle-ring-next}). -@item C-x C-k C-p -Rotate the keyboard macro ring to the previous macro (defined later) -(@code{kmacro-cycle-ring-previous}). -@end table - - All commands which operate on the keyboard macro ring use the -same @kbd{C-x C-k} prefix. Most of these commands can be executed and -repeated immediately after each other without repeating the @kbd{C-x -C-k} prefix. For example, - -@example -C-x C-k C-p C-p C-k C-k C-k C-n C-n C-k C-p C-k C-d -@end example - -@noindent -will rotate the keyboard macro ring to the ``second previous'' macro, -execute the resulting head macro three times, rotate back to the -original head macro, execute that once, rotate to the ``previous'' -macro, execute that, and finally delete it from the macro ring. - -@findex kmacro-end-or-call-macro-repeat -@kindex C-x C-k C-k - The command @kbd{C-x C-k C-k} (@code{kmacro-end-or-call-macro-repeat}) -executes the keyboard macro at the head of the macro ring. You can -repeat the macro immediately by typing another @kbd{C-k}, or you can -rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}. - - When a keyboard macro is being defined, @kbd{C-x C-k C-k} behaves -like @key{F4} except that, immediately afterward, you can use most key -bindings of this section without the @kbd{C-x C-k} prefix. For -instance, another @kbd{C-k} will re-execute the macro. - -@findex kmacro-cycle-ring-next -@kindex C-x C-k C-n -@findex kmacro-cycle-ring-previous -@kindex C-x C-k C-p - The commands @kbd{C-x C-k C-n} (@code{kmacro-cycle-ring-next}) and -@kbd{C-x C-k C-p} (@code{kmacro-cycle-ring-previous}) rotate the -macro ring, bringing the next or previous keyboard macro to the head -of the macro ring. The definition of the new head macro is displayed -in the echo area. You can continue to rotate the macro ring -immediately by repeating just @kbd{C-n} and @kbd{C-p} until the -desired macro is at the head of the ring. To execute the new macro -ring head immediately, just type @kbd{C-k}. - - Note that Emacs treats the head of the macro ring as the ``last -defined keyboard macro''. For instance, @key{F4} will execute that -macro, and @kbd{C-x C-k n} will give it a name. - -@vindex kmacro-ring-max - The maximum number of macros stored in the keyboard macro ring is -determined by the customizable variable @code{kmacro-ring-max}. - -@node Keyboard Macro Counter -@section The Keyboard Macro Counter - - Each keyboard macro has an associated counter, which is initialized -to 0 when you start defining the macro. This counter allows you to -insert a number into the buffer that depends on the number of times -the macro has been called. The counter is incremented each time its -value is inserted into the buffer. - -@table @kbd -@item @key{F3} -In a keyboard macro definition, insert the keyboard macro counter -value in the buffer (@code{kmacro-start-macro-or-insert-counter}). -@item C-x C-k C-i -Insert the keyboard macro counter value in the buffer -(@code{kmacro-insert-counter}). -@item C-x C-k C-c -Set the keyboard macro counter (@code{kmacro-set-counter}). -@item C-x C-k C-a -Add the prefix arg to the keyboard macro counter (@code{kmacro-add-counter}). -@item C-x C-k C-f -Specify the format for inserting the keyboard macro counter -(@code{kmacro-set-format}). -@end table - -@findex kmacro-insert-counter -@kindex C-x C-k C-i - When you are defining a keyboard macro, the command @key{F3} -(@code{kmacro-start-macro-or-insert-counter}) inserts the current -value of the keyboard macro's counter into the buffer, and increments -the counter by 1. (If you are not defining a macro, @key{F3} begins a -macro definition instead. @xref{Basic Keyboard Macro}.) You can use -a numeric prefix argument to specify a different increment. If you -just specify a @kbd{C-u} prefix, that is the same as an increment of -zero: it inserts the current counter value without changing it. - - As an example, let us show how the keyboard macro counter can be -used to build a numbered list. Consider the following key sequence: - -@example -@key{F3} C-a @key{F3} . @key{SPC} @key{F4} -@end example - -@noindent -As part of this keyboard macro definition, the string @samp{0. } was -inserted into the beginning of the current line. If you now move -somewhere else in the buffer and type @key{F4} to invoke the macro, -the string @samp{1. } is inserted at the beginning of that line. -Subsequent invocations insert @samp{2. }, @samp{3. }, and so forth. - - The command @kbd{C-x C-k C-i} (@code{kmacro-insert-counter}) does -the same thing as @key{F3}, but it can be used outside a keyboard -macro definition. When no keyboard macro is being defined or -executed, it inserts and increments the counter of the macro at the -head of the keyboard macro ring. - -@findex kmacro-set-counter -@kindex C-x C-k C-c - The command @kbd{C-x C-k C-c} (@code{kmacro-set-counter}) sets the -current macro counter to the value of the numeric argument. If you use -it inside the macro, it operates on each repetition of the macro. If -you specify just @kbd{C-u} as the prefix, while executing the macro, -that resets the counter to the value it had at the beginning of the -current repetition of the macro (undoing any increments so far in this -repetition). - -@findex kmacro-add-counter -@kindex C-x C-k C-a - The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) adds the -prefix argument to the current macro counter. With just @kbd{C-u} as -argument, it resets the counter to the last value inserted by any -keyboard macro. (Normally, when you use this, the last insertion -will be in the same macro and it will be the same counter.) - -@findex kmacro-set-format -@kindex C-x C-k C-f - The command @kbd{C-x C-k C-f} (@code{kmacro-set-format}) prompts for -the format to use when inserting the macro counter. The default -format is @samp{%d}, which means to insert the number in decimal -without any padding. You can exit with empty minibuffer to reset the -format to this default. You can specify any format string that the -@code{format} function accepts and that makes sense with a single -integer extra argument (@pxref{Formatting Strings,,, elisp, The Emacs -Lisp Reference Manual}). Do not put the format string inside double -quotes when you insert it in the minibuffer. - - If you use this command while no keyboard macro is being defined or -executed, the new format affects all subsequent macro definitions. -Existing macros continue to use the format in effect when they were -defined. If you set the format while defining a keyboard macro, this -affects the macro being defined from that point on, but it does not -affect subsequent macros. Execution of the macro will, at each step, -use the format in effect at that step during its definition. Changes -to the macro format during execution of a macro, like the -corresponding changes during its definition, have no effect on -subsequent macros. - - The format set by @kbd{C-x C-k C-f} does not affect insertion of -numbers stored in registers. - - If you use a register as a counter, incrementing it on each -repetition of the macro, that accomplishes the same thing as a -keyboard macro counter. @xref{Number Registers}. For most purposes, -it is simpler to use a keyboard macro counter. - -@node Keyboard Macro Query -@section Executing Macros with Variations - - In a keyboard macro, you can create an effect similar to that of -@code{query-replace}, in that the macro asks you each time around -whether to make a change. - -@table @kbd -@item C-x q -When this point is reached during macro execution, ask for confirmation -(@code{kbd-macro-query}). -@end table - -@kindex C-x q -@findex kbd-macro-query - While defining the macro, type @kbd{C-x q} at the point where you -want the query to occur. During macro definition, the @kbd{C-x q} -does nothing, but when you run the macro later, @kbd{C-x q} asks you -interactively whether to continue. - - The valid responses when @kbd{C-x q} asks are: - -@table @asis -@item @key{SPC} (or @kbd{y}) -Continue executing the keyboard macro. - -@item @key{DEL} (or @kbd{n}) -Skip the remainder of this repetition of the macro, and start right -away with the next repetition. - -@item @key{RET} (or @kbd{q}) -Skip the remainder of this repetition and cancel further repetitions. - -@item @kbd{C-r} -Enter a recursive editing level, in which you can perform editing -which is not part of the macro. When you exit the recursive edit -using @kbd{C-M-c}, you are asked again how to continue with the -keyboard macro. If you type a @key{SPC} at this time, the rest of the -macro definition is executed. It is up to you to leave point and the -text in a state such that the rest of the macro will do what you want. -@end table - - @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, -performs a completely different function. It enters a recursive edit -reading input from the keyboard, both when you type it during the -definition of the macro, and when it is executed from the macro. During -definition, the editing you do inside the recursive edit does not become -part of the macro. During macro execution, the recursive edit gives you -a chance to do some particularized editing on each repetition. -@xref{Recursive Edit}. - -@node Save Keyboard Macro -@section Naming and Saving Keyboard Macros - -@table @kbd -@item C-x C-k n -Give a command name (for the duration of the Emacs session) to the most -recently defined keyboard macro (@code{kmacro-name-last-macro}). -@item C-x C-k b -Bind the most recently defined keyboard macro to a key sequence (for -the duration of the session) (@code{kmacro-bind-to-key}). -@item M-x insert-kbd-macro -Insert in the buffer a keyboard macro's definition, as Lisp code. -@end table - -@cindex saving keyboard macros -@findex kmacro-name-last-macro -@kindex C-x C-k n - If you wish to save a keyboard macro for later use, you can give it -a name using @kbd{C-x C-k n} (@code{kmacro-name-last-macro}). -This reads a name as an argument using the minibuffer and defines that -name to execute the last keyboard macro, in its current form. (If you -later add to the definition of this macro, that does not alter the -name's definition as a macro.) The macro name is a Lisp symbol, and -defining it in this way makes it a valid command name for calling with -@kbd{M-x} or for binding a key to with @code{global-set-key} -(@pxref{Keymaps}). If you specify a name that has a prior definition -other than a keyboard macro, an error message is shown and nothing is -changed. - -@cindex binding keyboard macros -@findex kmacro-bind-to-key -@kindex C-x C-k b - You can also bind the last keyboard macro (in its current form) to a -key, using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the -key sequence you want to bind. You can bind to any key sequence in -the global keymap, but since most key sequences already have other -bindings, you should select the key sequence carefully. If you try to -bind to a key sequence with an existing binding (in any keymap), this -command asks you for confirmation before replacing the existing binding. - - To avoid problems caused by overriding existing bindings, the key -sequences @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A} -through @kbd{C-x C-k Z} are reserved for your own keyboard macro -bindings. In fact, to bind to one of these key sequences, you only -need to type the digit or letter rather than the whole key sequences. -For example, - -@example -C-x C-k b 4 -@end example - -@noindent -will bind the last keyboard macro to the key sequence @kbd{C-x C-k 4}. - -@findex insert-kbd-macro - Once a macro has a command name, you can save its definition in a file. -Then it can be used in another editing session. First, visit the file -you want to save the definition in. Then use this command: - -@example -M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET} -@end example - -@noindent -This inserts some Lisp code that, when executed later, will define the -same macro with the same definition it has now. (You need not -understand Lisp code to do this, because @code{insert-kbd-macro} writes -the Lisp code for you.) Then save the file. You can load the file -later with @code{load-file} (@pxref{Lisp Libraries}). If the file you -save in is your init file @file{~/.emacs} (@pxref{Init File}) then the -macro will be defined each time you run Emacs. - - If you give @code{insert-kbd-macro} a numeric argument, it makes -additional Lisp code to record the keys (if any) that you have bound -to @var{macroname}, so that the macro will be reassigned the same keys -when you load the file. - -@node Edit Keyboard Macro -@section Editing a Keyboard Macro - -@table @kbd -@item C-x C-k C-e -Edit the last defined keyboard macro (@code{kmacro-edit-macro}). -@item C-x C-k e @var{name} @key{RET} -Edit a previously defined keyboard macro @var{name} (@code{edit-kbd-macro}). -@item C-x C-k l -Edit the last 300 keystrokes as a keyboard macro -(@code{kmacro-edit-lossage}). -@end table - -@findex kmacro-edit-macro -@kindex C-x C-k C-e -@kindex C-x C-k RET - You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or -@kbd{C-x C-k RET} (@code{kmacro-edit-macro}). This formats the macro -definition in a buffer and enters a specialized major mode for editing -it. Type @kbd{C-h m} once in that buffer to display details of how to -edit the macro. When you are finished editing, type @kbd{C-c C-c}. - -@findex edit-kbd-macro -@kindex C-x C-k e - You can edit a named keyboard macro or a macro bound to a key by typing -@kbd{C-x C-k e} (@code{edit-kbd-macro}). Follow that with the -keyboard input that you would use to invoke the macro---@kbd{C-x e} or -@kbd{M-x @var{name}} or some other key sequence. - -@findex kmacro-edit-lossage -@kindex C-x C-k l - You can edit the last 300 keystrokes as a macro by typing -@kbd{C-x C-k l} (@code{kmacro-edit-lossage}). - -@node Keyboard Macro Step-Edit -@section Stepwise Editing a Keyboard Macro - -@findex kmacro-step-edit-macro -@kindex C-x C-k SPC - You can interactively replay and edit the last keyboard -macro, one command at a time, by typing @kbd{C-x C-k SPC} -(@code{kmacro-step-edit-macro}). Unless you quit the macro using -@kbd{q} or @kbd{C-g}, the edited macro replaces the last macro on the -macro ring. - - This macro editing feature shows the last macro in the minibuffer -together with the first (or next) command to be executed, and prompts -you for an action. You can enter @kbd{?} to get a summary of your -options. These actions are available: - -@itemize @bullet{} -@item -@kbd{SPC} and @kbd{y} execute the current command, and advance to the -next command in the keyboard macro. -@item -@kbd{n}, @kbd{d}, and @kbd{DEL} skip and delete the current command. -@item -@kbd{f} skips the current command in this execution of the keyboard -macro, but doesn't delete it from the macro. -@item -@kbd{@key{TAB}} executes the current command, as well as all similar -commands immediately following the current command; for example, @key{TAB} -may be used to insert a sequence of characters (corresponding to a -sequence of @code{self-insert-command} commands). -@item -@kbd{c} continues execution (without further editing) until the end of -the keyboard macro. If execution terminates normally, the edited -macro replaces the original keyboard macro. -@item -@kbd{C-k} skips and deletes the rest of the keyboard macro, -terminates step-editing, and replaces the original keyboard macro -with the edited macro. -@item -@kbd{q} and @kbd{C-g} cancels the step-editing of the keyboard macro; -discarding any changes made to the keyboard macro. -@item -@kbd{i KEY... C-j} reads and executes a series of key sequences (not -including the final @kbd{C-j}), and inserts them before the current -command in the keyboard macro, without advancing over the current -command. -@item -@kbd{I KEY...} reads one key sequence, executes it, and inserts it -before the current command in the keyboard macro, without advancing -over the current command. -@item -@kbd{r KEY... C-j} reads and executes a series of key sequences (not -including the final @kbd{C-j}), and replaces the current command in -the keyboard macro with them, advancing over the inserted key -sequences. -@item -@kbd{R KEY...} reads one key sequence, executes it, and replaces the -current command in the keyboard macro with that key sequence, -advancing over the inserted key sequence. -@item -@kbd{a KEY... C-j} executes the current command, then reads and -executes a series of key sequences (not including the final -@kbd{C-j}), and inserts them after the current command in the keyboard -macro; it then advances over the current command and the inserted key -sequences. -@item -@kbd{A KEY... C-j} executes the rest of the commands in the keyboard -macro, then reads and executes a series of key sequences (not -including the final @kbd{C-j}), and appends them at the end of the -keyboard macro; it then terminates the step-editing and replaces the -original keyboard macro with the edited macro. -@end itemize diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi deleted file mode 100644 index 81ceb1e3ac9..00000000000 --- a/doc/emacs/m-x.texi +++ /dev/null @@ -1,71 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node M-x, Help, Minibuffer, Top -@chapter Running Commands by Name - - Every Emacs command has a name that you can use to run it. For -convenience, many commands also have key bindings. You can run those -commands by typing the keys, or run them by name. Most Emacs commands -have no key bindings, so the only way to run them is by name. -(@xref{Key Bindings}, for how to set up key bindings.) - - By convention, a command name consists of one or more words, -separated by hyphens; for example, @code{auto-fill-mode} or -@code{manual-entry}. Command names mostly use complete English words -to make them easier to remember. - -@kindex M-x - To run a command by name, start with @kbd{M-x}, type the command -name, then terminate it with @key{RET}. @kbd{M-x} uses the minibuffer -to read the command name. The string @samp{M-x} appears at the -beginning of the minibuffer as a @dfn{prompt} to remind you to enter a -command name to be run. @key{RET} exits the minibuffer and runs the -command. @xref{Minibuffer}, for more information on the minibuffer. - - You can use completion to enter the command name. For example, -to invoke the command @code{forward-char}, you can type - -@example -M-x forward-char @key{RET} -@end example - -@noindent -or - -@example -M-x forw @key{TAB} c @key{RET} -@end example - -@noindent -Note that @code{forward-char} is the same command that you invoke with -the key @kbd{C-f}. The existence of a key binding does not stop you -from running the command by name. - - To cancel the @kbd{M-x} and not run a command, type @kbd{C-g} instead -of entering the command name. This takes you back to command level. - - To pass a numeric argument to the command you are invoking with -@kbd{M-x}, specify the numeric argument before @kbd{M-x}. The -argument value appears in the prompt while the command name is being -read, and finally @kbd{M-x} passes the argument to that command. - -@vindex suggest-key-bindings - When the command you run with @kbd{M-x} has a key binding, Emacs -mentions this in the echo area after running the command. For -example, if you type @kbd{M-x forward-word}, the message says that you -can run the same command by typing @kbd{M-f}. You can turn off these -messages by setting the variable @code{suggest-key-bindings} to -@code{nil}. - - In this manual, when we speak of running a command by name, we often -omit the @key{RET} that terminates the name. Thus we might say -@kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode -@key{RET}}. We mention the @key{RET} only for emphasis, such as when -the command is followed by arguments. - -@findex execute-extended-command - @kbd{M-x} works by running the command -@code{execute-extended-command}, which is responsible for reading the -name of another command and invoking it. diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi deleted file mode 100644 index 695f8f9c6c3..00000000000 --- a/doc/emacs/macos.texi +++ /dev/null @@ -1,210 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2000-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Mac OS / GNUstep, Microsoft Windows, Antinews, Top -@appendix Emacs and Mac OS / GNUstep -@cindex Mac OS X -@cindex Macintosh -@cindex GNUstep - - This section describes the peculiarities of using Emacs built with -the GNUstep libraries on GNU/Linux or other operating systems, or on -Mac OS X with native window system support. On Mac OS X, Emacs can be -built either without window system support, with X11, or with the -Cocoa interface; this section only applies to the Cocoa build. This -does not support versions of Mac OS X earlier than 10.4. - - For various historical and technical reasons, Emacs uses the term -@samp{Nextstep} internally, instead of ``Cocoa'' or ``Mac OS X''; for -instance, most of the commands and variables described in this section -begin with @samp{ns-}, which is short for @samp{Nextstep}. NeXTstep -was an application interface released by NeXT Inc during the 1980s, of -which Cocoa is a direct descendant. Apart from Cocoa, there is -another NeXTstep-style system: GNUstep, which is free software. As of -this writing, Emacs GNUstep support is alpha status (@pxref{GNUstep -Support}), but we hope to improve it in the future. - -@menu -* Mac / GNUstep Basics:: Basic Emacs usage under GNUstep or Mac OS. -* Mac / GNUstep Customization:: Customizations under GNUstep or Mac OS. -* Mac / GNUstep Events:: How window system events are handled. -* GNUstep Support:: Details on status of GNUstep support. -@end menu - -@node Mac / GNUstep Basics, Mac / GNUstep Customization, , Mac OS / GNUstep -@section Basic Emacs usage under Mac OS and GNUstep - - By default, the @key{alt} and @key{option} keys are the same as -@key{Meta}. The Mac @key{Cmd} key is the same as @key{Super}, and -Emacs provides a set of key bindings using this modifier key that mimic -other Mac / GNUstep applications (@pxref{Mac / GNUstep Events}). You -can change these bindings in the usual way (@pxref{Key Bindings}). - -@c FIXME mention ns-alternate-modifier? - The variable @code{ns-right-alternate-modifier} controls the -behavior of the right @key{alt} and @key{option} keys. These keys -behave like the left-hand keys if the value is @code{left} (the -default). A value of @code{control}, @code{meta}, @code{alt}, -@code{super}, or @code{hyper} makes them behave like the corresponding -modifier keys; a value of @code{none} tells Emacs to ignore them. - - @kbd{S-Mouse-1} adjusts the region to the click position, -just like @kbd{Mouse-3} (@code{mouse-save-then-kill}); it does not pop -up a menu for changing the default face, as @kbd{S-Mouse-1} normally -does (@pxref{Text Scale}). This change makes Emacs behave more like -other Mac / GNUstep applications. - - When you open or save files using the menus, or using the -@kbd{Cmd-o} and @kbd{Cmd-S} bindings, Emacs uses graphical file -dialogs to read file names. However, if you use the regular Emacs key -sequences, such as @kbd{C-x C-f}, Emacs uses the minibuffer to read -file names. - - On GNUstep, in an X-windows environment you need to use @kbd{Cmd-c} -instead of one of the @kbd{C-w} or @kbd{M-w} commands to transfer text -to the X primary selection; otherwise, Emacs will use the -``clipboard'' selection. Likewise, @kbd{Cmd-y} (instead of @kbd{C-y}) -yanks from the X primary selection instead of the kill-ring or -clipboard. - - -@subsection Grabbing environment variables - -@c How is this any different to launching from a window manager menu -@c in GNU/Linux? These are sometimes not login shells either. -Many programs which may run under Emacs, like latex or man, depend on the -settings of environment variables. If Emacs is launched from the shell, it -will automatically inherit these environment variables and its subprocesses -will inherit them from it. But if Emacs is launched from the Finder it -is not a descendant of any shell, so its environment variables haven't been -set, which often causes the subprocesses it launches to behave differently than -they would when launched from the shell. - -For the PATH and MANPATH variables, a system-wide method -of setting PATH is recommended on Mac OS X 10.5 and later, using the -@file{/etc/paths} files and the @file{/etc/paths.d} directory. - -@node Mac / GNUstep Customization, Mac / GNUstep Events, Mac / GNUstep Basics, Mac OS / GNUstep -@section Mac / GNUstep Customization - -Emacs can be customized in several ways in addition to the standard -customization buffers and the Options menu. - - -@subsection Font and Color Panels - -The standard Mac / GNUstep font and color panels are accessible via -Lisp commands. The Font Panel may be accessed with @kbd{M-x -ns-popup-font-panel}. It will set the default font in the frame most -recently used or clicked on. - -@c To make the setting permanent, use @samp{Save Options} in the -@c Options menu, or run @code{menu-bar-options-save}. - -You can bring up a color panel with @kbd{M-x ns-popup-color-panel} and -drag the color you want over the Emacs face you want to change. Normal -dragging will alter the foreground color. Shift dragging will alter the -background color. To discard the settings, create a new frame and -close the altered one. - -@c To make the changes permanent select the "Save Options" -@c item in the "Options" menu, or run @code{menu-bar-options-save}. - -Useful in this context is the listing of all faces obtained by -@kbd{M-x list-faces-display}. - -@subsection Customization options specific to Mac OS / GNUstep - -The following customization options are specific to the Nextstep port. - -@table @code -@item ns-auto-hide-menu-bar -Non-nil means the menu-bar is hidden by default, but appears if you -move the mouse pointer over it. (Requires Mac OS X 10.6 or later.) - -@end table - - -@node Mac / GNUstep Events, GNUstep Support, Mac / GNUstep Customization, Mac OS / GNUstep -@section Windowing System Events under Mac OS / GNUstep - - Nextstep applications receive a number of special events which have -no X equivalent. These are sent as specially defined ``keys'', which -do not correspond to any sequence of keystrokes. Under Emacs, these -``key'' events can be bound to functions just like ordinary -keystrokes. Here is a list of these events. - -@table @key -@item ns-open-file -@vindex ns-pop-up-frames -This event occurs when another Nextstep application requests that -Emacs open a file. A typical reason for this would be a user -double-clicking a file in the Finder application. By default, Emacs -responds to this event by opening a new frame and visiting the file in -that frame (@code{ns-find-file}). As an exception, if the selected -buffer is the @file{*scratch*} buffer, Emacs visits the file in the -selected frame. - -You can change how Emacs responds to a @code{ns-open-file} event by -changing the variable @code{ns-pop-up-frames}. Its default value, -@samp{fresh}, is what we have just described. A value of @code{t} -means to always visit the file in a new frame. A value of @code{nil} -means to always visit the file in an existing frame. - -@item ns-open-temp-file -This event occurs when another application requests that Emacs open a -temporary file. By default, this is handled by just generating a -@code{ns-open-file} event, the results of which are described above. - -@item ns-open-file-line -Some applications, such as ProjectBuilder and gdb, request not only a -particular file, but also a particular line or sequence of lines in -the file. Emacs handles this by visiting that file and highlighting -the requested line (@code{ns-open-file-select-line}). - -@item ns-drag-file -This event occurs when a user drags files from another application -into an Emacs frame. The default behavior is to insert the contents -of all the dragged files into the current buffer -(@code{ns-insert-files}). The list of dragged files is stored in the -variable @code{ns-input-file}. - -@item ns-drag-color -This event occurs when a user drags a color from the color well (or -some other source) into an Emacs frame. The default behavior is to -alter the foreground color of the area the color was dragged onto -(@code{ns-set-foreground-at-mouse}). If this event is issued with a -@key{Shift} modifier, Emacs changes the background color instead -(@code{ns-set-background-at-mouse}). The name of the dragged color is -stored in the variable @code{ns-input-color}. - -@item ns-change-font -This event occurs when the user selects a font in a Nextstep font -panel (which can be opened with @kbd{Cmd-t}). The default behavior is -to adjust the font of the selected frame -(@code{ns-respond-to-changefont}). The name and size of the selected -font are stored in the variables @code{ns-input-font} and -@code{ns-input-fontsize}, respectively. - -@item ns-power-off -This event occurs when the user logs out and Emacs is still running, or when -`Quit Emacs' is chosen from the application menu. -The default behavior is to save all file-visiting buffers. -@end table - - Emacs also allows users to make use of Nextstep services, via a set -of commands whose names begin with @samp{ns-service-} and end with the -name of the service. Type @kbd{M-x ns-service-@key{TAB}} to -see a list of these commands. These functions either operate on -marked text (replacing it with the result) or take a string argument -and return the result as a string. You can also use the Lisp function -@code{ns-perform-service} to pass arbitrary strings to arbitrary -services and receive the results back. Note that you may need to -restart Emacs to access newly-available services. - -@node GNUstep Support, , Mac / GNUstep Events, Mac OS / GNUstep -@section GNUstep Support - -Emacs can be built and run under GNUstep, but there are still -issues to be addressed. Interested developers should contact -@email{emacs-devel@@gnu.org}. diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi deleted file mode 100644 index b0ee5bd5f2f..00000000000 --- a/doc/emacs/maintaining.texi +++ /dev/null @@ -1,2375 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Maintaining, Abbrevs, Building, Top -@chapter Maintaining Large Programs - - This chapter describes Emacs features for maintaining large -programs. If you are maintaining a large Lisp program, then in -addition to the features described here, you may find -the @file{ERT} (``Emacs Lisp Regression Testing'') library useful -(@pxref{Top,,ERT,ert, Emacs Lisp Regression Testing}). - -@menu -* Version Control:: Using version control systems. -* Change Log:: Maintaining a change history for your program. -* Tags:: Go directly to any function in your program in one - command. Tags remembers which file it is in. -* EDE:: An integrated development environment for Emacs. -@ifnottex -* Emerge:: A convenient way of merging two versions of a program. -@end ifnottex -@end menu - -@node Version Control -@section Version Control -@cindex version control - - A @dfn{version control system} is a program that can record multiple -versions of a source file, storing information such as the creation -time of each version, who made it, and a description of what was -changed. - - The Emacs version control interface is called @dfn{VC}. VC commands -work with several different version control systems; currently, it -supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, -SCCS/CSSC, and Subversion. Of these, the GNU project distributes CVS, -Arch, RCS, and Bazaar. - - VC is enabled automatically whenever you visit a file governed by a -version control system. To disable VC entirely, set the customizable -variable @code{vc-handled-backends} to @code{nil} -@iftex -(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Customizing VC}). -@end ifnottex - -@menu -* Introduction to VC:: How version control works in general. -* VC Mode Line:: How the mode line shows version control status. -* Basic VC Editing:: How to edit a file under version control. -* Log Buffer:: Features available in log entry buffers. -* Registering:: Putting a file under version control. -* Old Revisions:: Examining and comparing old versions. -* VC Change Log:: Viewing the VC Change Log. -* VC Undo:: Canceling changes before or after committing. -* VC Directory Mode:: Listing files managed by version control. -* Branches:: Multiple lines of development. -@ifnottex -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. -@end ifnottex -@end menu - -@node Introduction to VC -@subsection Introduction to Version Control - - VC allows you to use a version control system from within Emacs, -integrating the version control operations smoothly with editing. It -provides a uniform interface for common operations in many version -control operations. - - Some uncommon or intricate version control operations, such as -altering repository settings, are not supported in VC. You should -perform such tasks outside Emacs, e.g.@: via the command line. - - This section provides a general overview of version control, and -describes the version control systems that VC supports. You can skip -this section if you are already familiar with the version control system -you want to use. - -@menu -* Why Version Control?:: Understanding the problems it addresses. -* Version Control Systems:: Supported version control back-end systems. -* VCS Concepts:: Words and concepts related to version control. -* VCS Merging:: How file conflicts are handled. -* VCS Changesets:: How changes are grouped. -* VCS Repositories:: Where version control repositories are stored. -* Types of Log File:: The VCS log in contrast to the ChangeLog. -@end menu - -@node Why Version Control? -@subsubsection Understanding the problems it addresses - - Version control systems provide you with three important -capabilities: - -@itemize @bullet -@item -@dfn{Reversibility}: the ability to back up to a previous state if you -discover that some modification you did was a mistake or a bad idea. - -@item -@dfn{Concurrency}: the ability to have many people modifying the same -collection of files knowing that conflicting modifications can be -detected and resolved. - -@item -@dfn{History}: the ability to attach historical data to your data, -such as explanatory comments about the intention behind each change to -it. Even for a programmer working solo, change histories are an -important aid to memory; for a multi-person project, they are a -vitally important form of communication among developers. -@end itemize - -@node Version Control Systems -@subsubsection Supported Version Control Systems - -@cindex back end (version control) - VC currently works with many different version control systems, -which it refers to as @dfn{back ends}: - -@itemize @bullet - -@cindex SCCS -@item -SCCS was the first version control system ever built, and was long ago -superseded by more advanced ones. VC compensates for certain features -missing in SCCS (e.g.@: tag names for releases) by implementing them -itself. Other VC features, such as multiple branches, are simply -unavailable. Since SCCS is non-free, we recommend avoiding it. - -@cindex CSSC -@item -CSSC is a free replacement for SCCS. You should use CSSC only if, for -some reason, you cannot use a more recent and better-designed version -control system. - -@cindex RCS -@item -RCS is the free version control system around which VC was initially -built. It is relatively primitive: it cannot be used over the -network, and works at the level of individual files. Almost -everything you can do with RCS can be done through VC. - -@cindex CVS -@item -CVS is the free version control system that was, until recently (circa -2008), used by the majority of free software projects. Nowadays, it -is slowly being superseded by newer systems. CVS allows concurrent -multi-user development either locally or over the network. Unlike -newer systems, it lacks support for atomic commits and file -moving/renaming. VC supports all basic editing operations under CVS. - -@cindex SVN -@cindex Subversion -@item -Subversion (svn) is a free version control system designed to be -similar to CVS but without its problems (e.g., it supports atomic -commits of filesets, and versioning of directories, symbolic links, -meta-data, renames, copies, and deletes). - -@cindex GNU Arch -@cindex Arch -@item -GNU Arch is one of the earliest @dfn{decentralized} version control -systems (the other being Monotone). @xref{VCS Concepts}, for a -description of decentralized version control systems. It is no longer -under active development, and has been deprecated in favor of Bazaar. - -@cindex git -@item -Git is a decentralized version control system originally invented by -Linus Torvalds to support development of Linux (his kernel). VC -supports many common Git operations, but others, such as repository -syncing, must be done from the command line. - -@cindex hg -@cindex Mercurial -@item -Mercurial (hg) is a decentralized version control system broadly -resembling Git. VC supports most Mercurial commands, with the -exception of repository sync operations. - -@cindex bzr -@cindex Bazaar -@item -Bazaar (bzr) is a decentralized version control system that supports -both repository-based and decentralized versioning. VC supports most -basic editing operations under Bazaar. -@end itemize - -@node VCS Concepts -@subsubsection Concepts of Version Control - -@cindex repository -@cindex registered file - When a file is under version control, we say that it is -@dfn{registered} in the version control system. The system has a -@dfn{repository} which stores both the file's present state and its -change history---enough to reconstruct the current version or any -earlier version. The repository also contains other information, such -as @dfn{log entries} that describe the changes made to each file. - -@cindex work file -@cindex checking out files - The copy of a version-controlled file that you actually edit is -called the @dfn{work file}. You can change each work file as you -would an ordinary file. After you are done with a set of changes, you -may @dfn{commit} (or @dfn{check in}) the changes; this records the -changes in the repository, along with a descriptive log entry. - -@cindex working tree - A directory tree of work files is called a @dfn{working tree}. - -@cindex revision -@cindex revision ID - Each commit creates a new @dfn{revision} in the repository. The -version control system keeps track of all past revisions and the -changes that were made in each revision. Each revision is named by a -@dfn{revision ID}, whose format depends on the version control system; -in the simplest case, it is just an integer. - - To go beyond these basic concepts, you will need to understand three -aspects in which version control systems differ. As explained in the -next three sections, they can be lock-based or merge-based; file-based -or changeset-based; and centralized or decentralized. VC handles all -these modes of operation, but it cannot hide the differences. - -@node VCS Merging -@subsubsection Merge-based vs lock-based Version Control - - A version control system typically has some mechanism to coordinate -between users who want to change the same file. There are two ways to -do this: merging and locking. - -@cindex merging-based version - In a version control system that uses merging, each user may modify -a work file at any time. The system lets you @dfn{merge} your work -file, which may contain changes that have not been committed, with the -latest changes that others have committed. - -@cindex locking-based version - Older version control systems use a @dfn{locking} scheme instead. -Here, work files are normally read-only. To edit a file, you ask the -version control system to make it writable for you by @dfn{locking} -it; only one user can lock a given file at any given time. This -procedure is analogous to, but different from, the locking that Emacs -uses to detect simultaneous editing of ordinary files -(@pxref{Interlocking}). When you commit your changes, that unlocks -the file, and the work file becomes read-only again. Other users may -then lock the file to make their own changes. - - Both locking and merging systems can have problems when multiple -users try to modify the same file at the same time. Locking systems -have @dfn{lock conflicts}; a user may try to check a file out and be -unable to because it is locked. In merging systems, @dfn{merge -conflicts} happen when you commit a change to a file that conflicts -with a change committed by someone else after your checkout. Both -kinds of conflict have to be resolved by human judgment and -communication. Experience has shown that merging is superior to -locking, both in convenience to developers and in minimizing the -number and severity of conflicts that actually occur. - - SCCS always uses locking. RCS is lock-based by default but can be -told to operate in a merging style. CVS and Subversion are -merge-based by default but can be told to operate in a locking mode. -Decentralized version control systems, such as GNU Arch, Git, and -Mercurial, are exclusively merging-based. - - VC mode supports both locking and merging version control. The -terms ``commit'' and ``update'' are used in newer version control -systems; older lock-based systems use the terms ``check in'' and -``check out''. VC hides the differences between them as much as -possible. - -@node VCS Changesets -@subsubsection Changeset-based vs File-based Version Control - -@cindex file-based version control - On SCCS, RCS, CVS, and other early version control systems, version -control operations are @dfn{file-based}: each file has its own comment -and revision history separate from that of all other files. Newer -systems, beginning with Subversion, are @dfn{changeset-based}: a -commit may include changes to several files, and the entire set of -changes is handled as a unit. Any comment associated with the change -does not belong to a single file, but to the changeset itself. - -@cindex changeset-based version control - Changeset-based version control is more flexible and powerful than -file-based version control; usually, when a change to multiple files -has to be reversed, it's good to be able to easily identify and remove -all of it. - -@node VCS Repositories -@subsubsection Decentralized vs Centralized Repositories - -@cindex centralized version control -@cindex decentralized version control -@cindex distributed version control - Early version control systems were designed around a -@dfn{centralized} model in which each project has only one repository -used by all developers. SCCS, RCS, CVS, and Subversion share this -kind of model. One of its drawbacks is that the repository is a choke -point for reliability and efficiency. - - GNU Arch pioneered the concept of @dfn{distributed} or -@dfn{decentralized} version control, later implemented in Git, -Mercurial, and Bazaar. A project may have several different -repositories, and these systems support a sort of super-merge between -repositories that tries to reconcile their change histories. In -effect, there is one repository for each developer, and repository -merges take the place of commit operations. - - VC helps you manage the traffic between your personal workfiles and -a repository. Whether the repository is a single master, or one of a -network of peer repositories, is not something VC has to care about. - -@node Types of Log File -@subsubsection Types of Log File -@cindex types of log file -@cindex log File, types of -@cindex version control log - - Projects that use a version control system can have two types of log -for changes. One is the log maintained by the version control system: -each time you commit a change, you fill out a @dfn{log entry} for the -change (@pxref{Log Buffer}). This is called the @dfn{version control -log}. - - The other kind of log is the file @file{ChangeLog} (@pxref{Change -Log}). It provides a chronological record of all changes to a large -portion of a program---typically one directory and its subdirectories. -A small program would use one @file{ChangeLog} file; a large program -may have a @file{ChangeLog} file in each major directory. -@xref{Change Log}. Programmers have used change logs since long -before version control systems. - - Changeset-based version systems typically maintain a changeset-based -modification log for the entire system, which makes change log files -somewhat redundant. One advantage that they retain is that it is -sometimes useful to be able to view the transaction history of a -single directory separately from those of other directories. - - A project maintained with version control can use just the version -control log, or it can use both kinds of logs. It can handle some -files one way and some files the other way. Each project has its -policy, which you should follow. - - When the policy is to use both, you typically want to write an entry -for each change just once, then put it into both logs. You can write -the entry in @file{ChangeLog}, then copy it to the log buffer with -@kbd{C-c C-a} when committing the change (@pxref{Log Buffer}). Or you -can write the entry in the log buffer while committing the change, and -later use the @kbd{C-x v a} command to copy it to @file{ChangeLog} -@iftex -(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Change Logs and VC}). -@end ifnottex - -@node VC Mode Line -@subsection Version Control and the Mode Line -@cindex VC mode line indicator - - When you visit a file that is under version control, Emacs indicates -this on the mode line. For example, @samp{Bzr-1223} says that Bazaar -is used for that file, and the current revision ID is 1223. - -@cindex version control status - The character between the back-end name and the revision ID -indicates the @dfn{version control status} of the work file. In a -merge-based version control system, a @samp{-} character indicates -that the work file is unmodified, and @samp{:} indicates that it has -been modified. @samp{!} indicates that the file contains conflicts as -result of a recent merge operation (@pxref{Merging}), or that the file -was removed from the version control. Finally, @samp{?} means that -the file is under version control, but is missing from the working -tree. - - In a lock-based system, @samp{-} indicates an unlocked file, and -@samp{:} a locked file; if the file is locked by another user (for -instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. -@samp{@@} means that the file was locally added, but not yet committed -to the master repository. - - On a graphical display, you can move the mouse over this mode line -indicator to pop up a ``tool-tip'', which displays a more verbose -description of the version control status. Pressing @kbd{Mouse-1} -over the indicator pops up a menu of VC commands, identical to -@samp{Tools / Version Control} on the menu bar. - -@vindex auto-revert-check-vc-info - When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is -under version control, it updates the version control information in -the mode line. However, Auto Revert mode may not properly update this -information if the version control status changes without changes to -the work file, from outside the current Emacs session. If you set -@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates -the version control status information every -@code{auto-revert-interval} seconds, even if the work file itself is -unchanged. The resulting CPU usage depends on the version control -system, but is usually not excessive. - -@node Basic VC Editing -@subsection Basic Editing under Version Control - -@cindex filesets, VC -@cindex VC filesets - Most VC commands operate on @dfn{VC filesets}. A VC fileset is a -collection of one or more files that a VC operation acts on. When you -type VC commands in a buffer visiting a version-controlled file, the -VC fileset is simply that one file. When you type them in a VC -Directory buffer, and some files in it are marked, the VC fileset -consists of the marked files (@pxref{VC Directory Mode}). - - On modern changeset-based version control systems (@pxref{VCS -Changesets}), VC commands handle multi-file VC filesets as a group. -For example, committing a multi-file VC fileset generates a single -revision, containing the changes to all those files. On older -file-based version control systems like CVS, each file in a multi-file -VC fileset is handled individually; for example, a commit generates -one revision for each changed file. - -@table @kbd -@itemx C-x v v -Perform the next appropriate version control operation on the current -VC fileset. -@end table - -@findex vc-next-action -@kindex C-x v v - The principal VC command is a multi-purpose command, @kbd{C-x v v} -(@code{vc-next-action}), which performs the ``most appropriate'' -action on the current VC fileset: either registering it with a version -control system, or committing it, or unlocking it, or merging changes -into it. The precise actions are described in detail in the following -subsections. You can use @kbd{C-x v v} either in a file-visiting -buffer or in a VC Directory buffer. - - Note that VC filesets are distinct from the ``named filesets'' used -for viewing and visiting files in functional groups -(@pxref{Filesets}). Unlike named filesets, VC filesets are not named -and don't persist across sessions. - -@menu -* VC With A Merging VCS:: Without locking: default mode for CVS. -* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. -* Advanced C-x v v:: Advanced features available with a prefix argument. -@end menu - -@node VC With A Merging VCS -@subsubsection Basic Version Control with Merging - - On a merging-based version control system (i.e.@: most modern ones; -@pxref{VCS Merging}), @kbd{C-x v v} does the following: - -@itemize @bullet -@item -If there is more than one file in the VC fileset and the files have -inconsistent version control statuses, signal an error. (Note, -however, that a fileset is allowed to include both ``newly-added'' -files and ``modified'' files; @pxref{Registering}.) - -@item -If none of the files in the VC fileset are registered with a version -control system, register the VC fileset, i.e.@: place it under version -control. @xref{Registering}. If Emacs cannot find a system to -register under, it prompts for a repository type, creates a new -repository, and registers the VC fileset with it. - -@item -If every work file in the VC fileset is unchanged, do nothing. - -@item -If every work file in the VC fileset has been modified, commit the -changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the -desired log entry for the new revision, followed by @kbd{C-c C-c} to -commit. @xref{Log Buffer}. - -If committing to a shared repository, the commit may fail if the -repository that has been changed since your last update. In that -case, you must perform an update before trying again. On a -decentralized version control system, use @kbd{C-x v +} (@pxref{VC -Pull}) or @kbd{C-x v m} (@pxref{Merging}). On a centralized version -control system, type @kbd{C-x v v} again to merge in the repository -changes. - -@item -Finally, if you are using a centralized version control system, check -if each work file in the VC fileset is up-to-date. If any file has -been changed in the repository, offer to update it. -@end itemize - - These rules also apply when you use RCS in its ``non-locking'' mode, -except that changes are not automatically merged from the repository. -Nothing informs you if another user has committed changes in the same -file since you began editing it; when you commit your revision, his -changes are removed (however, they remain in the repository and are -thus not irrevocably lost). Therefore, you must verify that the -current revision is unchanged before committing your changes. In -addition, locking is possible with RCS even in this mode: @kbd{C-x v -v} with an unmodified file locks the file, just as it does with RCS in -its normal locking mode (@pxref{VC With A Locking VCS}). - -@node VC With A Locking VCS -@subsubsection Basic Version Control with Locking - - On a locking-based version control system (such as SCCS, and RCS in -its default mode), @kbd{C-x v v} does the following: - -@itemize @bullet -@item -If there is more than one file in the VC fileset and the files have -inconsistent version control statuses, signal an error. - -@item -If each file in the VC fileset is not registered with a version -control system, register the VC fileset. @xref{Registering}. If -Emacs cannot find a system to register under, it prompts for a -repository type, creates a new repository, and registers the VC -fileset with it. - -@item -If each file is registered and unlocked, lock it and make it writable, -so that you can begin to edit it. - -@item -If each file is locked by you and contains changes, commit the -changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the -desired log entry for the new revision, followed by @kbd{C-c C-c} to -commit (@pxref{Log Buffer}). - -@item -If each file is locked by you, but you have not changed it, release -the lock and make the file read-only again. - -@item -If each file is locked by another user, ask whether you want to -``steal the lock''. If you say yes, the file becomes locked by you, -and a warning message is sent to the user who had formerly locked the -file. -@end itemize - - These rules also apply when you use CVS in locking mode, except -that CVS does not support stealing locks. - -@node Advanced C-x v v -@subsubsection Advanced Control in @kbd{C-x v v} - -@cindex revision ID in version control - When you give a prefix argument to @code{vc-next-action} (@kbd{C-u -C-x v v}), it still performs the next logical version control -operation, but accepts additional arguments to specify precisely how -to do the operation. - -@itemize @bullet -@item -@cindex specific version control system -You can specify the name of a version control system. This is useful -if the fileset can be managed by more than one version control system, -and Emacs fails to detect the correct one. - -@item -Otherwise, if using CVS or RCS, you can specify a revision ID. - -If the fileset is modified (or locked), this makes Emacs commit with -that revision ID. You can create a new branch by supplying an -appropriate revision ID (@pxref{Branches}). - -If the fileset is unmodified (and unlocked), this checks the specified -revision into the working tree. You can also specify a revision on -another branch by giving its revision or branch ID (@pxref{Switching -Branches}). An empty argument (i.e.@: @kbd{C-u C-x v v @key{RET}}) -checks out the latest (``head'') revision on the current branch. - -This signals an error on a decentralized version control system. -Those systems do not let you specify your own revision IDs, nor do -they use the concept of ``checking out'' individual files. -@end itemize - -@node Log Buffer -@subsection Features of the Log Entry Buffer - -@cindex C-c C-c @r{(Log Edit mode)} -@findex log-edit-done - When you tell VC to commit a change, it pops up a buffer named -@file{*vc-log*}. In this buffer, you should write a @dfn{log entry} -describing the changes you have made (@pxref{Why Version Control?}). -After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit -the buffer and commit the change, together with your log entry. - -@cindex Log Edit mode -@cindex mode, Log Edit -@vindex vc-log-mode-hook - The major mode for the @file{*vc-log*} buffer is Log Edit mode, a -variant of Text mode (@pxref{Text Mode}). On entering Log Edit mode, -Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook} -(@pxref{Hooks}). - - In the @file{*vc-log*} buffer, you can write one or more @dfn{header -lines}, specifying additional information to be supplied to the -version control system. Each header line must occupy a single line at -the top of the buffer; the first line that is not a header line is -treated as the start of the log entry. For example, the following -header line states that the present change was not written by you, but -by another developer: - -@smallexample -Author: J. R. Hacker -@end smallexample - -@noindent -Apart from the @samp{Author} header, Emacs recognizes the headers -@samp{Date} (a manually-specified commit time) and @samp{Fixes} (a -reference to a bug fixed by the change). Not all version control -systems recognize all headers: Bazaar recognizes all three headers, -while Git, Mercurial, and Monotone recognize only @samp{Author} and -@samp{Date}. If you specify a header for a system that does not -support it, the header is treated as part of the log entry. - -@kindex C-c C-f @r{(Log Edit mode)} -@findex log-edit-show-files -@kindex C-c C-d @r{(Log Edit mode)} -@findex log-edit-show-diff - While in the @file{*vc-log*} buffer, the ``current VC fileset'' is -considered to be the fileset that will be committed if you type -@w{@kbd{C-c C-c}}. To view a list of the files in the VC fileset, -type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}). To view a diff -of changes between the VC fileset and the version from which you -started editing (@pxref{Old Revisions}), type @kbd{C-c C-d} -(@code{log-edit-show-diff}). - -@kindex C-c C-a @r{(Log Edit mode)} -@findex log-edit-insert-changelog - If the VC fileset includes one or more @file{ChangeLog} files -(@pxref{Change Log}), type @kbd{C-c C-a} -(@code{log-edit-insert-changelog}) to pull the relevant entries into -the @file{*vc-log*} buffer. If the topmost item in each -@file{ChangeLog} was made under your user name on the current date, -this command searches that item for entries matching the file(s) to be -committed, and inserts them. -@ifnottex -If you are using CVS or RCS, see @ref{Change Logs and VC}, for the -opposite way of working---generating ChangeLog entries from the Log -Edit buffer. -@end ifnottex - - To abort a commit, just @strong{don't} type @kbd{C-c C-c} in that -buffer. You can switch buffers and do other editing. As long as you -don't try to make another commit, the entry you were editing remains -in the @file{*vc-log*} buffer, and you can go back to that buffer at -any time to complete the commit. - -@kindex M-n @r{(Log Edit mode)} -@kindex M-p @r{(Log Edit mode)} -@kindex M-s @r{(Log Edit mode)} -@kindex M-r @r{(Log Edit mode)} - You can also browse the history of previous log entries to duplicate -a commit comment. This can be useful when you want to make several -commits with similar comments. The commands @kbd{M-n}, @kbd{M-p}, -@kbd{M-s} and @kbd{M-r} for doing this work just like the minibuffer -history commands (@pxref{Minibuffer History}), except that they are -used outside the minibuffer. - -@node Registering -@subsection Registering a File for Version Control - -@table @kbd -@item C-x v i -Register the visited file for version control. -@end table - -@kindex C-x v i -@findex vc-register - The command @kbd{C-x v i} (@code{vc-register}) @dfn{registers} each -file in the current VC fileset, placing it under version control. -This is essentially equivalent to the action of @kbd{C-x v v} on an -unregistered VC fileset (@pxref{Basic VC Editing}), except that if the -VC fileset is already registered, @kbd{C-x v i} signals an error -whereas @kbd{C-x v v} performs some other action. - - To register a file, Emacs must choose a version control system. For -a multi-file VC fileset, the VC Directory buffer specifies the system -to use (@pxref{VC Directory Mode}). For a single-file VC fileset, if -the file's directory already contains files registered in a version -control system, or if the directory is part of a directory tree -controlled by a version control system, Emacs chooses that system. In -the event that more than one version control system is applicable, -Emacs uses the one that appears first in the variable -@iftex -@code{vc-handled-backends}. -@end iftex -@ifnottex -@code{vc-handled-backends} (@pxref{Customizing VC}). -@end ifnottex -If Emacs cannot find a version control system to register the file -under, it prompts for a repository type, creates a new repository, and -registers the file into that repository. - - On most version control systems, registering a file with @kbd{C-x v -i} or @kbd{C-x v v} adds it to the ``working tree'' but not to the -repository. Such files are labeled as @samp{added} in the VC -Directory buffer, and show a revision ID of @samp{@@@@} in the mode -line. To make the registration take effect in the repository, you -must perform a commit (@pxref{Basic VC Editing}). Note that a single -commit can include both file additions and edits to existing files. - - On a locking-based version control system (@pxref{VCS Merging}), -registering a file leaves it unlocked and read-only. Type @kbd{C-x v -v} to start editing it. - -@node Old Revisions -@subsection Examining And Comparing Old Revisions - -@table @kbd -@item C-x v = -Compare the work files in the current VC fileset with the versions you -started from (@code{vc-diff}). With a prefix argument, prompt for two -revisions of the current VC fileset and compare them. You can also -call this command from a Dired buffer (@pxref{Dired}). - -@ifnottex -@item M-x vc-ediff -Like @kbd{C-x v =}, but using Ediff. @xref{Top,, Ediff, ediff, The -Ediff Manual}. -@end ifnottex - -@item C-x v D -Compare the entire working tree to the revision you started from -(@code{vc-root-diff}). With a prefix argument, prompt for two -revisions and compare their trees. - -@item C-x v ~ -Prompt for a revision of the current file, and visit it in a separate -buffer (@code{vc-revision-other-window}). - -@item C-x v g -Display an annotated version of the current file: for each line, show -the latest revision in which it was modified (@code{vc-annotate}). -@end table - -@findex vc-diff -@kindex C-x v = - @kbd{C-x v =} (@code{vc-diff}) displays a @dfn{diff} which compares -each work file in the current VC fileset to the version(s) from which -you started editing. The diff is displayed in another window, in a -Diff mode buffer (@pxref{Diff Mode}) named @file{*vc-diff*}. The -usual Diff mode commands are available in this buffer. In particular, -the @kbd{g} (@code{revert-buffer}) command performs the file -comparison again, generating a new diff. - -@kindex C-u C-x v = - To compare two arbitrary revisions of the current VC fileset, call -@code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This -prompts for two revision IDs (@pxref{VCS Concepts}), and displays a -diff between those versions of the fileset. This will not work -reliably for multi-file VC filesets, if the version control system is -file-based rather than changeset-based (e.g.@: CVS), since then -revision IDs for different files would not be related in any -meaningful way. - - Instead of the revision ID, some version control systems let you -specify revisions in other formats. For instance, under Bazaar you -can enter @samp{date:yesterday} for the argument to @kbd{C-u C-x v =} -(and related commands) to specify the first revision committed after -yesterday. See the documentation of the version control system for -details. - - If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer -(@pxref{Dired}), the file listed on the current line is treated as the -current VC fileset. - -@ifnottex -@findex vc-ediff - @kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an -Ediff session. @xref{Top,, Ediff, ediff, The Ediff Manual}. -@end ifnottex - -@findex vc-root-diff -@kindex C-x v D - @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but -it displays the changes in the entire current working tree (i.e.@: the -working tree containing the current VC fileset). If you invoke this -command from a Dired buffer, it applies to the working tree containing -the directory. - -@vindex vc-diff-switches - You can customize the @command{diff} options that @kbd{C-x v =} and -@kbd{C-x v D} use for generating diffs. The options used are taken -from the first non-@code{nil} value amongst the variables -@code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and -@code{diff-switches} (@pxref{Comparing Files}), in that order. Here, -@var{backend} stands for the relevant version control system, -e.g.@: @code{bzr} for Bazaar. Since @code{nil} means to check the -next variable in the sequence, either of the first two may use the -value @code{t} to mean no switches at all. Most of the -@code{vc-@var{backend}-diff-switches} variables default to @code{nil}, -but some default to @code{t}; these are for version control systems -whose @code{diff} implementations do not accept common diff options, -such as Subversion. - -@findex vc-revision-other-window -@kindex C-x v ~ - To directly examine an older version of a file, visit the work file -and type @kbd{C-x v ~ @var{revision} @key{RET}} -(@code{vc-revision-other-window}). This retrieves the file version -corresponding to @var{revision}, saves it to -@file{@var{filename}.~@var{revision}~}, and visits it in a separate -window. - -@findex vc-annotate -@kindex C-x v g - Many version control systems allow you to view files @dfn{annotated} -with per-line revision information, by typing @kbd{C-x v g} -(@code{vc-annotate}). This creates a new buffer (the ``annotate -buffer'') displaying the file's text, with each line colored to show -how old it is. Red text is new, blue is old, and intermediate colors -indicate intermediate ages. By default, the color is scaled over the -full range of ages, such that the oldest changes are blue, and the -newest changes are red. - - When you give a prefix argument to this command, Emacs reads two -arguments using the minibuffer: the revision to display and annotate -(instead of the current file contents), and the time span in days the -color range should cover. - - From the annotate buffer, these and other color scaling options are -available from the @samp{VC-Annotate} menu. In this buffer, you can -also use the following keys to browse the annotations of past revisions, -view diffs, or view log entries: - -@table @kbd -@item p -Annotate the previous revision, i.e.@: the revision before the one -currently annotated. A numeric prefix argument is a repeat count, so -@kbd{C-u 10 p} would take you back 10 revisions. - -@item n -Annotate the next revision, i.e.@: the revision after the one -currently annotated. A numeric prefix argument is a repeat count. - -@item j -Annotate the revision indicated by the current line. - -@item a -Annotate the revision before the one indicated by the current line. -This is useful to see the state the file was in before the change on -the current line was made. - -@item f -Show in a buffer the file revision indicated by the current line. - -@item d -Display the diff between the current line's revision and the previous -revision. This is useful to see what the current line's revision -actually changed in the file. - -@item D -Display the diff between the current line's revision and the previous -revision for all files in the changeset (for VC systems that support -changesets). This is useful to see what the current line's revision -actually changed in the tree. - -@item l -Show the log of the current line's revision. This is useful to see -the author's description of the changes in the revision on the current -line. - -@item w -Annotate the working revision--the one you are editing. If you used -@kbd{p} and @kbd{n} to browse to other revisions, use this key to -return to your working revision. - -@item v -Toggle the annotation visibility. This is useful for looking just at -the file contents without distraction from the annotations. -@end table - -@node VC Change Log -@subsection VC Change Log - -@table @kbd -@item C-x v l -Display the change history for the current fileset -(@code{vc-print-log}). - -@item C-x v L -Display the change history for the current repository -(@code{vc-print-root-log}). - -@item C-x v I -Display the changes that a pull operation will retrieve -(@code{vc-log-incoming}). - -@item C-x v O -Display the changes that will be sent by the next push operation -(@code{vc-log-outgoing}). -@end table - -@kindex C-x v l -@findex vc-print-log - The command @kbd{C-x v l} (@code{vc-print-log}) displays a buffer -named @file{*vc-change-log*}, showing the history of changes made to -the current file, including who made the changes, the dates, and the -log entry for each change (these are the same log entries you would -enter via the @file{*vc-log*} buffer; @pxref{Log Buffer}). Point is -centered at the revision of the file currently being visited. With a -prefix argument, the command prompts for the revision to center on, -and the maximum number of revisions to display. - - If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC -Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the -file listed on the current line. - -@findex vc-print-root-log -@findex log-view-toggle-entry-display - @kbd{C-x v L} (@code{vc-print-root-log}) displays a -@file{*vc-change-log*} buffer showing the history of the entire -version-controlled directory tree (RCS, SCCS, and CVS do not support -this feature). With a prefix argument, the command prompts for the -maximum number of revisions to display. - - The @kbd{C-x v L} history is shown in a compact form, usually -showing only the first line of each log entry. However, you can type -@key{RET} (@code{log-view-toggle-entry-display}) in the -@file{*vc-change-log*} buffer to reveal the entire log entry for the -revision at point. A second @key{RET} hides it again. - - On a decentralized version control system, the @kbd{C-x v I} -(@code{vc-log-incoming}) command displays a log buffer showing the -changes that will be applied, the next time you run the version -control system's ``pull'' command to get new revisions from another -repository (@pxref{VC Pull}). This other repository is the default -one from which changes are pulled, as defined by the version control -system; with a prefix argument, @code{vc-log-incoming} prompts for a -specific repository. Similarly, @kbd{C-x v O} -(@code{vc-log-outgoing}) shows the changes that will be sent to -another repository, the next time you run the ``push'' command; with a -prefix argument, it prompts for a specific destination repository. - - In the @file{*vc-change-log*} buffer, you can use the following keys -to move between the logs of revisions and of files, and to examine and -compare past revisions (@pxref{Old Revisions}): - -@table @kbd -@item p -Move to the previous revision entry. (Revision entries in the log -buffer are usually in reverse-chronological order, so the previous -revision-item usually corresponds to a newer revision.) A numeric -prefix argument is a repeat count. - -@item n -Move to the next revision entry. A numeric prefix argument is a -repeat count. - -@item P -Move to the log of the previous file, if showing logs for a multi-file -VC fileset. Otherwise, just move to the beginning of the log. A -numeric prefix argument is a repeat count. - -@item N -Move to the log of the next file, if showing logs for a multi-file VC -fileset. A numeric prefix argument is a repeat count. - -@item a -Annotate the revision on the current line (@pxref{Old Revisions}). - -@item e -Modify the change comment displayed at point. Note that not all VC -systems support modifying change comments. - -@item f -Visit the revision indicated at the current line. - -@item d -Display a diff between the revision at point and the next earlier -revision, for the specific file. - -@item D -Display the changeset diff between the revision at point and the next -earlier revision. This shows the changes to all files made in that -revision. - -@item @key{RET} -In a compact-style log buffer (e.g.@: the one created by @kbd{C-x v -L}), toggle between showing and hiding the full log entry for the -revision at point. -@end table - -@vindex vc-log-show-limit -Because fetching many log entries can be slow, the -@file{*vc-change-log*} buffer displays no more than 2000 revisions by -default. The variable @code{vc-log-show-limit} specifies this limit; -if you set the value to zero, that removes the limit. You can also -increase the number of revisions shown in an existing -@file{*vc-change-log*} buffer by clicking on the @samp{Show 2X -entries} or @samp{Show unlimited entries} buttons at the end of the -buffer. However, RCS, SCCS, and CVS do not support this feature. - -@node VC Undo -@subsection Undoing Version Control Actions - -@table @kbd -@item C-x v u -Revert the work file(s) in the current VC fileset to the last revision -(@code{vc-revert}). -@end table - -@c `C-x v c' (vc-rollback) was removed, since it's RCS/SCCS specific. - -@kindex C-x v u -@findex vc-revert -@vindex vc-revert-show-diff - If you want to discard all the changes you have made to the current -VC fileset, type @kbd{C-x v u} (@code{vc-revert-buffer}). This shows -you a diff between the work file(s) and the revision from which you -started editing, and asks for confirmation for discarding the changes. -If you agree, the fileset is reverted. If you don't want @kbd{C-x v -u} to show a diff, set the variable @code{vc-revert-show-diff} to -@code{nil} (you can still view the diff directly with @kbd{C-x v =}; -@pxref{Old Revisions}). Note that @kbd{C-x v u} cannot be reversed -with the usual undo commands (@pxref{Undo}), so use it with care. - - On locking-based version control systems, @kbd{C-x v u} leaves files -unlocked; you must lock again to resume editing. You can also use -@kbd{C-x v u} to unlock a file if you lock it and then decide not to -change it. - -@node VC Directory Mode -@subsection VC Directory Mode - -@cindex VC Directory buffer - The @dfn{VC Directory buffer} is a specialized buffer for viewing -the version control statuses of the files in a directory tree, and -performing version control operations on those files. In particular, -it is used to specify multi-file VC filesets for commands like -@w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}). - -@kindex C-x v d -@findex vc-dir - To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}). -This reads a directory name using the minibuffer, and switches to a VC -Directory buffer for that directory. By default, the buffer is named -@file{*vc-dir*}. Its contents are described -@iftex -below. -@end iftex -@ifnottex -in @ref{VC Directory Buffer}. -@end ifnottex - - The @code{vc-dir} command automatically detects the version control -system to be used in the specified directory. In the event that more -than one system is being used in the directory, you should invoke the -command with a prefix argument, @kbd{C-u C-x v d}; this prompts for -the version control system which the VC Directory buffer should use. - -@ifnottex -@cindex PCL-CVS -@pindex cvs -@cindex CVS directory mode - In addition to the VC Directory buffer, Emacs has a similar facility -called PCL-CVS which is specialized for CVS. @xref{Top, , About -PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}. -@end ifnottex - -@menu -* Buffer: VC Directory Buffer. What the buffer looks like and means. -* Commands: VC Directory Commands. Commands to use in a VC directory buffer. -@end menu - -@node VC Directory Buffer -@subsubsection The VC Directory Buffer - - The VC Directory buffer contains a list of version-controlled files -and their version control statuses. It lists files in the current -directory (the one specified when you called @kbd{C-x v d}) and its -subdirectories, but only those with a ``noteworthy'' status. Files -that are up-to-date (i.e.@: the same as in the repository) are -omitted. If all the files in a subdirectory are up-to-date, the -subdirectory is not listed either. As an exception, if a file has -become up-to-date as a direct result of a VC command, it is listed. - - Here is an example of a VC Directory buffer listing: - -@smallexample -@group - ./ - edited configure.ac -* added README - unregistered temp.txt - src/ -* edited src/main.c -@end group -@end smallexample - -@noindent -Two work files have been modified but not committed: -@file{configure.ac} in the current directory, and @file{foo.c} in the -@file{src/} subdirectory. The file named @file{README} has been added -but is not yet committed, while @file{temp.txt} is not under version -control (@pxref{Registering}). - -The @samp{*} characters next to the entries for @file{README} and -@file{src/main.c} indicate that the user has marked out these files as -the current VC fileset -@iftex -(see below). -@end iftex -@ifnottex -(@pxref{VC Directory Commands}). -@end ifnottex - - The above example is typical for a decentralized version control -system like Bazaar, Git, or Mercurial. Other systems can show other -statuses. For instance, CVS shows the @samp{needs-update} status if -the repository has changes that have not been applied to the work -file. RCS and SCCS show the name of the user locking a file as its -status. - -@ifnottex -@vindex vc-stay-local -@vindex vc-cvs-stay-local - On CVS and Subversion, the @code{vc-dir} command normally contacts -the repository, which may be on a remote machine, to check for -updates. If you change the variable @code{vc-stay-local} or -@code{vc-cvs-stay-local} (for CVS) to @code{nil} (@pxref{CVS -Options}), then Emacs avoids contacting a remote repository when -generating the VC Directory buffer (it will still contact it when -necessary, e.g.@: when doing a commit). This may be desirable if you -are working offline or the network is slow. -@end ifnottex - -@vindex vc-directory-exclusion-list - The VC Directory buffer omits subdirectories listed in the variable -@code{vc-directory-exclusion-list}. Its default value contains -directories that are used internally by version control systems. - -@node VC Directory Commands -@subsubsection VC Directory Commands - - Emacs provides several commands for navigating the VC Directory -buffer, and for ``marking'' files as belonging to the current VC -fileset. - -@table @kbd -@item n -@itemx @key{SPC} -Move point to the next entry (@code{vc-dir-next-line}). - -@item p -Move point to the previous entry (@code{vc-dir-previous-line}). - -@item @key{TAB} -Move to the next directory entry (@code{vc-dir-next-directory}). - -@item S-@key{TAB} -Move to the previous directory entry -(@code{vc-dir-previous-directory}). - -@item @key{RET} -@itemx f -Visit the file or directory listed on the current line -(@code{vc-dir-find-file}). - -@item o -Visit the file or directory on the current line, in a separate window -(@code{vc-dir-find-file-other-window}). - -@item m -Mark the file or directory on the current line (@code{vc-dir-mark}), -putting it in the current VC fileset. If the region is active, mark -all files in the region. - -A file cannot be marked with this command if it is already in a marked -directory, or one of its subdirectories. Similarly, a directory -cannot be marked with this command if any file in its tree is marked. - -@item M -If point is on a file entry, mark all files with the same status; if -point is on a directory entry, mark all files in that directory tree -(@code{vc-dir-mark-all-files}). With a prefix argument, mark all -listed files and directories. - -@kindex q @r{(VC Directory)} -@findex quit-window -@item q -Bury the VC Directory buffer, and delete its window if the window was -created just for that buffer. - -@item u -Unmark the file or directory on the current line. If the region is -active, unmark all the files in the region (@code{vc-dir-unmark}). - -@item U -If point is on a file entry, unmark all files with the same status; if -point is on a directory entry, unmark all files in that directory tree -(@code{vc-dir-unmark-all-files}). With a prefix argument, unmark all -files and directories. - -@item x -Hide files with @samp{up-to-date} status -(@code{vc-dir-hide-up-to-date}). - -@item q -Quit the VC Directory buffer, and bury it (@code{quit-window}). -@end table - -@findex vc-dir-mark -@findex vc-dir-mark-all-files - While in the VC Directory buffer, all the files that you mark with -@kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark}) are in -the current VC fileset. If you mark a directory entry with @kbd{m}, -all the listed files in that directory tree are in the current VC -fileset. The files and directories that belong to the current VC -fileset are indicated with a @samp{*} character in the VC Directory -buffer, next to their VC status. In this way, you can set up a -multi-file VC fileset to be acted on by VC commands like @w{@kbd{C-x v -v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}} (@pxref{Old -Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}). - - The VC Directory buffer also defines some single-key shortcuts for -VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l}, -@kbd{i}, and @kbd{v}. - - For example, you can commit a set of edited files by opening a VC -Directory buffer, where the files are listed with the @samp{edited} -status; marking the files; and typing @kbd{v} or @kbd{C-x v v} -(@code{vc-next-action}). If the version control system is -changeset-based, Emacs will commit the files in a single revision. - - While in the VC Directory buffer, you can also perform search and -replace on the current VC fileset, with the following commands: - -@table @kbd -@item S -Search the fileset (@code{vc-dir-search}). - -@item Q -Do a regular expression query replace on the fileset -(@code{vc-dir-query-replace-regexp}). - -@item M-s a C-s -Do an incremental search on the fileset (@code{vc-dir-isearch}). - -@item M-s a C-M-s -Do an incremental regular expression search on the fileset -(@code{vc-dir-isearch-regexp}). -@end table - -@noindent -Apart from acting on multiple files, these commands behave much like -their single-buffer counterparts (@pxref{Search}). - -@cindex stashes in version control -@cindex shelves in version control - The above commands are also available via the menu bar, and via a -context menu invoked by @kbd{Mouse-2}. Furthermore, some VC backends -use the menu to provide extra backend-specific commands. For example, -Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves} -(where are a way to temporarily put aside uncommitted changes, and -bring them back at a later time). - -@node Branches -@subsection Version Control Branches -@cindex branch (version control) - - One use of version control is to support multiple independent lines -of development, which are called @dfn{branches}. Branches are used -for maintaining separate ``stable'' and ``development'' versions of a -program, and for developing unrelated features in isolation from one -another. - - VC's support for branch operations is currently fairly limited. For -decentralized version control systems, it provides commands for -@dfn{updating} one branch with the contents of another, and for -@dfn{merging} the changes made to two different branches -(@pxref{Merging}). For centralized version control systems, it -supports checking out different branches and committing into new or -different branches. - -@menu -* Switching Branches:: How to get to another existing branch. -* VC Pull:: Updating the contents of a branch. -* Merging:: Transferring changes between branches. -* Creating Branches:: How to start a new branch. -@end menu - -@node Switching Branches -@subsubsection Switching between Branches - - The various version control systems differ in how branches are -implemented, and these differences cannot be entirely concealed by VC. - - On some decentralized version control systems, including Bazaar and -Mercurial in its normal mode of operation, each branch has its own -working directory tree, so switching between branches just involves -switching directories. On Git, switching between branches is done -using the @command{git branch} command, which changes the contents of -the working tree itself. - - On centralized version control systems, you can switch between -branches by typing @kbd{C-u C-x v v} in an up-to-date work file -(@pxref{Advanced C-x v v}), and entering the revision ID for a -revision on another branch. On CVS, for instance, revisions on the -@dfn{trunk} (the main line of development) normally have IDs of the -form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say) -revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second -branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2, -@dots{}, and so forth. You can also specify the @dfn{branch ID}, -which is a branch revision ID omitting its final component -(e.g.@: 1.2.1), to switch to the latest revision on that branch. - - On a locking-based system, switching to a different branch also -unlocks (write-protects) the working tree. - - Once you have switched to a branch, VC commands will apply to that -branch until you switch away; for instance, any VC filesets that you -commit will be committed to that specific branch. - -@node VC Pull -@subsubsection Pulling Changes into a Branch - -@table @kbd -@itemx C-x v + -On a decentralized version control system, update the current branch -by ``pulling in'' changes from another location. - -On a centralized version control system, update the current VC -fileset. -@end table - -@kindex C-x v + -@findex vc-pull - On a decentralized version control system, the command @kbd{C-x v +} -(@code{vc-pull}) updates the current branch and working tree. It is -typically used to update a copy of a remote branch. If you supply a -prefix argument, the command prompts for the exact version control -command to use, which lets you specify where to pull changes from. -Otherwise, it pulls from a default location determined by the version -control system. - - Amongst decentralized version control systems, @kbd{C-x v +} is -currently supported only by Bazaar, Git, and Mercurial. On Bazaar, it -calls @command{bzr pull} for ordinary branches (to pull from a master -branch into a mirroring branch), and @command{bzr update} for a bound -branch (to pull from a central repository). On Git, it calls -@command{git pull} to fetch changes from a remote repository and merge -it into the current branch. On Mercurial, it calls @command{hg pull --u} to fetch changesets from the default remote repository and update -the working directory. - - Prior to pulling, you can use @kbd{C-x v I} (@code{vc-log-incoming}) -to view a log buffer of the changes to be applied. @xref{VC Change -Log}. - - On a centralized version control system like CVS, @kbd{C-x v +} -updates the current VC fileset from the repository. - -@node Merging -@subsubsection Merging Branches -@cindex merging changes - -@table @kbd -@itemx C-x v m -On a decentralized version control system, merge changes from another -branch into the current one. - -On a centralized version control system, merge changes from another -branch into the current VC fileset. -@end table - - While developing a branch, you may sometimes need to @dfn{merge} in -changes that have already been made in another branch. This is not a -trivial operation, as overlapping changes may have been made to the -two branches. - - On a decentralized version control system, merging is done with the -command @kbd{C-x v m} (@code{vc-merge}). On Bazaar, this prompts for -the exact arguments to pass to @command{bzr merge}, offering a -sensible default if possible. On Git, this prompts for the name of a -branch to merge from, with completion (based on the branch names known -to the current repository). The output from running the merge command -is shown in a separate buffer. - - On a centralized version control system like CVS, @kbd{C-x v m} -prompts for a branch ID, or a pair of revision IDs (@pxref{Switching -Branches}); then it finds the changes from that branch, or the changes -between the two revisions you specified, and merges those changes into -the current VC fileset. If you just type @key{RET}, Emacs simply -merges any changes that were made on the same branch since you checked -the file out. - -@cindex conflicts -@cindex resolving conflicts - Immediately after performing a merge, only the working tree is -modified, and you can review the changes produced by the merge with -@kbd{C-x v D} and related commands (@pxref{Old Revisions}). If the -two branches contained overlapping changes, merging produces a -@dfn{conflict}; a warning appears in the output of the merge command, -and @dfn{conflict markers} are inserted into each affected work file, -surrounding the two sets of conflicting changes. You must then -resolve the conflict by editing the conflicted files. Once you are -done, the modified files must be committed in the usual way for the -merge to take effect (@pxref{Basic VC Editing}). - -@node Creating Branches -@subsubsection Creating New Branches - - On centralized version control systems like CVS, Emacs supports -creating new branches as part of a commit operation. When committing -a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action} -with a prefix argument; @pxref{Advanced C-x v v}). Then Emacs prompts -for a revision ID for the new revision. You should specify a suitable -branch ID for a branch starting at the current revision. For example, -if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2, -and so on, depending on the number of existing branches at that point. - - To create a new branch at an older revision (one that is no longer -the head of a branch), first select that revision (@pxref{Switching -Branches}). Your procedure will then differ depending on whether you -are using a locking or merging-based VCS. - - On a locking VCS, you will need to lock the old revision branch with -@kbd{C-x v v}. You'll be asked to confirm, when you lock the old -revision, that you really mean to create a new branch---if you say no, -you'll be offered a chance to lock the latest revision instead. On a -merging-based VCS you will skip this step. - - Then make your changes and type @kbd{C-x v v} again to commit a new -revision. This creates a new branch starting from the selected -revision. - - After the branch is created, subsequent commits create new revisions -on that branch. To leave the branch, you must explicitly select a -different revision with @kbd{C-u C-x v v}. - -@ifnottex -@include vc1-xtra.texi -@end ifnottex - -@node Change Log -@section Change Logs - -@cindex change log - Many software projects keep a @dfn{change log}. This is a file, -normally named @file{ChangeLog}, containing a chronological record of -when and how the program was changed. Sometimes, there are several -change log files, each recording the changes in one directory or -directory tree. - -@menu -* Change Log Commands:: Commands for editing change log files. -* Format of ChangeLog:: What the change log file looks like. -@end menu - -@node Change Log Commands -@subsection Change Log Commands - -@kindex C-x 4 a -@findex add-change-log-entry-other-window - The Emacs command @kbd{C-x 4 a} adds a new entry to the change log -file for the file you are editing -(@code{add-change-log-entry-other-window}). If that file is actually -a backup file, it makes an entry appropriate for the file's -parent---that is useful for making log entries for functions that -have been deleted in the current version. - - @kbd{C-x 4 a} visits the change log file and creates a new entry -unless the most recent entry is for today's date and your name. It -also creates a new item for the current file. For many languages, it -can even guess the name of the function or other object that was -changed. - -@vindex add-log-keep-changes-together - When the variable @code{add-log-keep-changes-together} is -non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file -rather than starting a new item. - -You can combine multiple changes of the same nature. If you don't -enter any text after the initial @kbd{C-x 4 a}, any subsequent -@kbd{C-x 4 a} adds another symbol to the change log entry. - -@vindex add-log-always-start-new-record - If @code{add-log-always-start-new-record} is non-@code{nil}, -@kbd{C-x 4 a} always makes a new entry, even if the last entry -was made by you and on the same date. - -@vindex change-log-version-info-enabled -@vindex change-log-version-number-regexp-list -@cindex file version in change log entries - If the value of the variable @code{change-log-version-info-enabled} -is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the -change log entry. It finds the version number by searching the first -ten percent of the file, using regular expressions from the variable -@code{change-log-version-number-regexp-list}. - -@cindex Change Log mode -@findex change-log-mode - The change log file is visited in Change Log mode. In this major -mode, each bunch of grouped items counts as one paragraph, and each -entry is considered a page. This facilitates editing the entries. -@kbd{C-j} and auto-fill indent each new line like the previous line; -this is convenient for entering the contents of an entry. - -You can use the @code{next-error} command (by default bound to -@kbd{C-x `}) to move between entries in the Change Log, when Change -Log mode is on. You will jump to the actual site in the file that was -changed, not just to the next Change Log entry. You can also use -@code{previous-error} to move back in the same list. - -@findex change-log-merge - You can use the command @kbd{M-x change-log-merge} to merge other -log files into a buffer in Change Log Mode, preserving the date -ordering of entries. - - Version control systems are another way to keep track of changes in -your program and keep a change log. In the VC log buffer, typing -@kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant -Change Log entry, if one exists. @xref{Log Buffer}. - -@node Format of ChangeLog -@subsection Format of ChangeLog - - A change log entry starts with a header line that contains the -current date, your name (taken from the variable -@code{add-log-full-name}), and your email address (taken from the -variable @code{add-log-mailing-address}). Aside from these header -lines, every line in the change log starts with a space or a tab. The -bulk of the entry consists of @dfn{items}, each of which starts with a -line starting with whitespace and a star. Here are two entries, both -dated in May 1993, with two items and one item respectively. - -@iftex -@medbreak -@end iftex -@smallexample -1993-05-25 Richard Stallman - - * man.el: Rename symbols `man-*' to `Man-*'. - (manual-entry): Make prompt string clearer. - - * simple.el (blink-matching-paren-distance): - Change default to 12,000. - -1993-05-24 Richard Stallman - - * vc.el (minor-mode-map-alist): Don't use it if it's void. - (vc-cancel-version): Doc fix. -@end smallexample - - One entry can describe several changes; each change should have its -own item, or its own line in an item. Normally there should be a -blank line between items. When items are related (parts of the same -change, in different places), group them by leaving no blank line -between them. - - You should put a copyright notice and permission notice at the -end of the change log file. Here is an example: - -@smallexample -Copyright 1997, 1998 Free Software Foundation, Inc. -Copying and distribution of this file, with or without modification, are -permitted provided the copyright notice and this notice are preserved. -@end smallexample - -@noindent -Of course, you should substitute the proper years and copyright holder. - -@node Tags -@section Tags Tables -@cindex tags and tag tables - - A @dfn{tag} is a reference to a subunit in a program or in a -document. In source code, tags reference syntactic elements of the -program: functions, subroutines, data types, macros, etc. In a -document, tags reference chapters, sections, appendices, etc. Each -tag specifies the name of the file where the corresponding subunit is -defined, and the position of the subunit's definition in that file. - - A @dfn{tags table} records the tags extracted by scanning the source -code of a certain program or a certain document. Tags extracted from -generated files reference the original files, rather than the -generated files that were scanned during tag extraction. Examples of -generated files include C files generated from Cweb source files, from -a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed -C files; and Fortran files produced by preprocessing @file{.fpp} -source files. - -@cindex etags - To produce a tags table, you run the @command{etags} shell command -on a document or the source code file. The @samp{etags} program -writes the tags to a @dfn{tags table file}, or @dfn{tags file} in -short. The conventional name for a tags file is @file{TAGS}. -@xref{Create Tags Table}. - - Emacs provides many commands for searching and replacing using the -information recorded in tags tables. For instance, the @kbd{M-.} -(@code{find-tag}) jumps to the location of a specified function -definition in its source file. @xref{Find Tag}. - -@cindex C++ class browser, tags -@cindex tags, C++ -@cindex class browser, C++ -@cindex Ebrowse - The Ebrowse facility is similar to @command{etags} but specifically -tailored for C++. @xref{Top,, Ebrowse, ebrowse, Ebrowse User's -Manual}. The Semantic package provides another way to generate and -use tags, separate from the @command{etags} facility. -@xref{Semantic}. - -@menu -* Tag Syntax:: Tag syntax for various types of code and text files. -* Create Tags Table:: Creating a tags table with @command{etags}. -* Etags Regexps:: Create arbitrary tags using regular expressions. -* Select Tags Table:: How to visit a tags table. -* Find Tag:: Commands to find the definition of a specific tag. -* Tags Search:: Using a tags table for searching and replacing. -* List Tags:: Using tags for completion, and listing them. -@end menu - -@node Tag Syntax -@subsection Source File Tag Syntax - - Here is how tag syntax is defined for the most popular languages: - -@itemize @bullet -@item -In C code, any C function or typedef is a tag, and so are definitions of -@code{struct}, @code{union} and @code{enum}. -@code{#define} macro definitions, @code{#undef} and @code{enum} -constants are also -tags, unless you specify @samp{--no-defines} when making the tags table. -Similarly, global variables are tags, unless you specify -@samp{--no-globals}, and so are struct members, unless you specify -@samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines} -and @samp{--no-members} can make the tags table file much smaller. - -You can tag function declarations and external variables in addition -to function definitions by giving the @samp{--declarations} option to -@command{etags}. - -@item -In C++ code, in addition to all the tag constructs of C code, member -functions are also recognized; member variables are also recognized, -unless you use the @samp{--no-members} option. Tags for variables and -functions in classes are named @samp{@var{class}::@var{variable}} and -@samp{@var{class}::@var{function}}. @code{operator} definitions have -tag names like @samp{operator+}. - -@item -In Java code, tags include all the constructs recognized in C++, plus -the @code{interface}, @code{extends} and @code{implements} constructs. -Tags for variables and functions in classes are named -@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}. - -@item -In La@TeX{} documents, the arguments for @code{\chapter}, -@code{\section}, @code{\subsection}, @code{\subsubsection}, -@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, -@code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry}, -@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand}, -@code{\newenvironment} and @code{\renewenvironment} are tags. - -Other commands can make tags as well, if you specify them in the -environment variable @env{TEXTAGS} before invoking @command{etags}. The -value of this environment variable should be a colon-separated list of -command names. For example, - -@example -TEXTAGS="mycommand:myothercommand" -export TEXTAGS -@end example - -@noindent -specifies (using Bourne shell syntax) that the commands -@samp{\mycommand} and @samp{\myothercommand} also define tags. - -@item -In Lisp code, any function defined with @code{defun}, any variable -defined with @code{defvar} or @code{defconst}, and in general the first -argument of any expression that starts with @samp{(def} in column zero is -a tag. - -@item -In Scheme code, tags include anything defined with @code{def} or with a -construct whose name starts with @samp{def}. They also include variables -set with @code{set!} at top level in the file. -@end itemize - - Several other languages are also supported: - -@itemize @bullet - -@item -In Ada code, functions, procedures, packages, tasks and types are -tags. Use the @samp{--packages-only} option to create tags for -packages only. - -In Ada, the same name can be used for different kinds of entity -(e.g.@:, for a procedure and for a function). Also, for things like -packages, procedures and functions, there is the spec (i.e.@: the -interface) and the body (i.e.@: the implementation). To make it -easier to pick the definition you want, Ada tag name have suffixes -indicating the type of entity: - -@table @samp -@item /b -package body. -@item /f -function. -@item /k -task. -@item /p -procedure. -@item /s -package spec. -@item /t -type. -@end table - - Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go -directly to the body of the package @code{bidule}, while @kbd{M-x -find-tag @key{RET} bidule @key{RET}} will just search for any tag -@code{bidule}. - -@item -In assembler code, labels appearing at the start of a line, -followed by a colon, are tags. - -@item -In Bison or Yacc input files, each rule defines as a tag the nonterminal -it constructs. The portions of the file that contain C code are parsed -as C code. - -@item -In Cobol code, tags are paragraph names; that is, any word starting in -column 8 and followed by a period. - -@item -In Erlang code, the tags are the functions, records and macros defined -in the file. - -@item -In Fortran code, functions, subroutines and block data are tags. - -@item -In HTML input files, the tags are the @code{title} and the @code{h1}, -@code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors -and all occurrences of @code{id=}. - -@item -In Lua input files, all functions are tags. - -@item -In makefiles, targets are tags; additionally, variables are tags -unless you specify @samp{--no-globals}. - -@item -In Objective C code, tags include Objective C definitions for classes, -class categories, methods and protocols. Tags for variables and -functions in classes are named @samp{@var{class}::@var{variable}} and -@samp{@var{class}::@var{function}}. - -@item -In Pascal code, the tags are the functions and procedures defined in -the file. - -@item -In Perl code, the tags are the packages, subroutines and variables -defined by the @code{package}, @code{sub}, @code{my} and @code{local} -keywords. Use @samp{--globals} if you want to tag global variables. -Tags for subroutines are named @samp{@var{package}::@var{sub}}. The -name for subroutines defined in the default package is -@samp{main::@var{sub}}. - -@item -In PHP code, tags are functions, classes and defines. Vars are tags -too, unless you use the @samp{--no-members} option. - -@item -In PostScript code, the tags are the functions. - -@item -In Prolog code, tags are predicates and rules at the beginning of -line. - -@item -In Python code, @code{def} or @code{class} at the beginning of a line -generate a tag. -@end itemize - - You can also generate tags based on regexp matching (@pxref{Etags -Regexps}) to handle other formats and languages. - -@node Create Tags Table -@subsection Creating Tags Tables -@cindex @command{etags} program - - The @command{etags} program is used to create a tags table file. It knows -the syntax of several languages, as described in -@iftex -the previous section. -@end iftex -@ifnottex -@ref{Tag Syntax}. -@end ifnottex -Here is how to run @command{etags}: - -@example -etags @var{inputfiles}@dots{} -@end example - -@noindent -The @command{etags} program reads the specified files, and writes a tags -table named @file{TAGS} in the current working directory. You can -optionally specify a different file name for the tags table by using the -@samp{--output=@var{file}} option; specifying @file{-} as a file name -prints the tags table to standard output. - - If the specified files don't exist, @command{etags} looks for -compressed versions of them and uncompresses them to read them. Under -MS-DOS, @command{etags} also looks for file names like @file{mycode.cgz} -if it is given @samp{mycode.c} on the command line and @file{mycode.c} -does not exist. - - If the tags table becomes outdated due to changes in the files -described in it, you can update it by running the @command{etags} -program again. If the tags table does not record a tag, or records it -for the wrong file, then Emacs will not be able to find that -definition until you update the tags table. But if the position -recorded in the tags table becomes a little bit wrong (due to other -editing), Emacs will still be able to find the right position, with a -slight delay. - - Thus, there is no need to update the tags table after each edit. -You should update a tags table when you define new tags that you want -to have listed, or when you move tag definitions from one file to -another, or when changes become substantial. - - You can make a tags table @dfn{include} another tags table, by -passing the @samp{--include=@var{file}} option to @command{etags}. It -then covers all the files covered by the included tags file, as well -as its own. - - If you specify the source files with relative file names when you run -@command{etags}, the tags file will contain file names relative to the -directory where the tags file was initially written. This way, you can -move an entire directory tree containing both the tags file and the -source files, and the tags file will still refer correctly to the source -files. If the tags file is @file{-} or is in the @file{/dev} directory, -however, the file names are -made relative to the current working directory. This is useful, for -example, when writing the tags to @file{/dev/stdout}. - - When using a relative file name, it should not be a symbolic link -pointing to a tags file in a different directory, because this would -generally render the file names invalid. - - If you specify absolute file names as arguments to @command{etags}, then -the tags file will contain absolute file names. This way, the tags file -will still refer to the same files even if you move it, as long as the -source files remain in the same place. Absolute file names start with -@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows. - - When you want to make a tags table from a great number of files, -you may have problems listing them on the command line, because some -systems have a limit on its length. You can circumvent this limit by -telling @command{etags} to read the file names from its standard -input, by typing a dash in place of the file names, like this: - -@smallexample -find . -name "*.[chCH]" -print | etags - -@end smallexample - - @command{etags} recognizes the language used in an input file based -on its file name and contents. You can specify the language -explicitly with the @samp{--language=@var{name}} option. You can -intermix these options with file names; each one applies to the file -names that follow it. Specify @samp{--language=auto} to tell -@command{etags} to resume guessing the language from the file names -and file contents. Specify @samp{--language=none} to turn off -language-specific processing entirely; then @command{etags} recognizes -tags by regexp matching alone (@pxref{Etags Regexps}). - - The option @samp{--parse-stdin=@var{file}} is mostly useful when -calling @command{etags} from programs. It can be used (only once) in -place of a file name on the command line. @command{etags} will read from -standard input and mark the produced tags as belonging to the file -@var{file}. - - @samp{etags --help} outputs the list of the languages @command{etags} -knows, and the file name rules for guessing the language. It also prints -a list of all the available @command{etags} options, together with a short -explanation. If followed by one or more @samp{--language=@var{lang}} -options, it outputs detailed information about how tags are generated for -@var{lang}. - -@node Etags Regexps -@subsection Etags Regexps - - The @samp{--regex} option to @command{etags} allows tags to be -recognized by regular expression matching. You can intermix this -option with file names; each one applies to the source files that -follow it. If you specify multiple @samp{--regex} options, all of -them are used in parallel. The syntax is: - -@smallexample ---regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers} -@end smallexample - -@noindent -The essential part of the option value is @var{tagregexp}, the regexp -for matching tags. It is always used anchored, that is, it only -matches at the beginning of a line. If you want to allow indented -tags, use a regexp that matches initial whitespace; start it with -@samp{[ \t]*}. - - In these regular expressions, @samp{\} quotes the next character, and -all the GCC character escape sequences are supported (@samp{\a} for -bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for -escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for -carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab). - - Ideally, @var{tagregexp} should not match more characters than are -needed to recognize what you want to tag. If the syntax requires you -to write @var{tagregexp} so it matches more characters beyond the tag -itself, you should add a @var{nameregexp}, to pick out just the tag. -This will enable Emacs to find tags more accurately and to do -completion on tag names more reliably. You can find some examples -below. - - The @var{modifiers} are a sequence of zero or more characters that -modify the way @command{etags} does the matching. A regexp with no -modifiers is applied sequentially to each line of the input file, in a -case-sensitive way. The modifiers and their meanings are: - -@table @samp -@item i -Ignore case when matching this regexp. -@item m -Match this regular expression against the whole file, so that -multi-line matches are possible. -@item s -Match this regular expression against the whole file, and allow -@samp{.} in @var{tagregexp} to match newlines. -@end table - - The @samp{-R} option cancels all the regexps defined by preceding -@samp{--regex} options. It too applies to the file names following -it. Here's an example: - -@smallexample -etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \ - bar.ber -R --lang=lisp los.er -@end smallexample - -@noindent -Here @command{etags} chooses the parsing language for @file{voo.doo} and -@file{bar.ber} according to their contents. @command{etags} also uses -@var{reg1} to recognize additional tags in @file{voo.doo}, and both -@var{reg1} and @var{reg2} to recognize additional tags in -@file{bar.ber}. @var{reg1} is checked against each line of -@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while -@var{reg2} is checked against the whole @file{bar.ber} file, -permitting multi-line matches, in a case-sensitive way. @command{etags} -uses only the Lisp tags rules, with no user-specified regexp matching, -to recognize tags in @file{los.er}. - - You can restrict a @samp{--regex} option to match only files of a -given language by using the optional prefix @var{@{language@}}. -(@samp{etags --help} prints the list of languages recognized by -@command{etags}.) This is particularly useful when storing many -predefined regular expressions for @command{etags} in a file. The -following example tags the @code{DEFVAR} macros in the Emacs source -files, for the C language only: - -@smallexample ---regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' -@end smallexample - -@noindent -When you have complex regular expressions, you can store the list of -them in a file. The following option syntax instructs @command{etags} to -read two files of regular expressions. The regular expressions -contained in the second file are matched without regard to case. - -@smallexample ---regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file} -@end smallexample - -@noindent -A regex file for @command{etags} contains one regular expression per -line. Empty lines, and lines beginning with space or tab are ignored. -When the first character in a line is @samp{@@}, @command{etags} assumes -that the rest of the line is the name of another file of regular -expressions; thus, one such file can include another file. All the -other lines are taken to be regular expressions. If the first -non-whitespace text on the line is @samp{--}, that line is a comment. - - For example, we can create a file called @samp{emacs.tags} with the -following contents: - -@smallexample - -- This is for GNU Emacs C source files -@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ -@end smallexample - -@noindent -and then use it like this: - -@smallexample -etags --regex=@@emacs.tags *.[ch] */*.[ch] -@end smallexample - - Here are some more examples. The regexps are quoted to protect them -from shell interpretation. - -@itemize @bullet - -@item -Tag Octave files: - -@smallexample -etags --language=none \ - --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ - --regex='/###key \(.*\)/\1/' \ - --regex='/[ \t]*global[ \t].*/' \ - *.m -@end smallexample - -@noindent -Note that tags are not generated for scripts, so that you have to add -a line by yourself of the form @samp{###key @var{scriptname}} if you -want to jump to it. - -@item -Tag Tcl files: - -@smallexample -etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl -@end smallexample - -@item -Tag VHDL files: - -@smallexample -etags --language=none \ - --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ - --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ - \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' -@end smallexample -@end itemize - -@node Select Tags Table -@subsection Selecting a Tags Table - -@findex visit-tags-table - Emacs has at any time one @dfn{selected} tags table. All the -commands for working with tags tables use the selected one. To select -a tags table, type @kbd{M-x visit-tags-table}, which reads the tags -table file name as an argument, with @file{TAGS} in the default -directory as the default. - -@vindex tags-file-name - Emacs does not actually read in the tags table contents until you -try to use them; all @code{visit-tags-table} does is store the file -name in the variable @code{tags-file-name}, and setting the variable -yourself is just as good. The variable's initial value is @code{nil}; -that value tells all the commands for working with tags tables that -they must ask for a tags table file name to use. - - Using @code{visit-tags-table} when a tags table is already loaded -gives you a choice: you can add the new tags table to the current list -of tags tables, or start a new list. The tags commands use all the tags -tables in the current list. If you start a new list, the new tags table -is used @emph{instead} of others. If you add the new table to the -current list, it is used @emph{as well as} the others. - -@vindex tags-table-list - You can specify a precise list of tags tables by setting the variable -@code{tags-table-list} to a list of strings, like this: - -@c keep this on two lines for formatting in smallbook -@example -@group -(setq tags-table-list - '("~/emacs" "/usr/local/lib/emacs/src")) -@end group -@end example - -@noindent -This tells the tags commands to look at the @file{TAGS} files in your -@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src} -directory. The order depends on which file you are in and which tags -table mentions that file, as explained above. - - Do not set both @code{tags-file-name} and @code{tags-table-list}. - -@node Find Tag -@subsection Finding a Tag - - The most important thing that a tags table enables you to do is to find -the definition of a specific tag. - -@table @kbd -@item M-.@: @var{tag} @key{RET} -Find first definition of @var{tag} (@code{find-tag}). -@item C-u M-. -Find next alternate definition of last tag specified. -@item C-u - M-. -Go back to previous tag found. -@item C-M-. @var{pattern} @key{RET} -Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}). -@item C-u C-M-. -Find the next tag whose name matches the last pattern used. -@item C-x 4 .@: @var{tag} @key{RET} -Find first definition of @var{tag}, but display it in another window -(@code{find-tag-other-window}). -@item C-x 5 .@: @var{tag} @key{RET} -Find first definition of @var{tag}, and create a new frame to select the -buffer (@code{find-tag-other-frame}). -@item M-* -Pop back to where you previously invoked @kbd{M-.} and friends. -@end table - -@kindex M-. -@findex find-tag - @kbd{M-.}@: (@code{find-tag}) prompts for a tag name and jumps to -its source definition. It works by searching through the tags table -for that tag's file and approximate character position, visiting that -file, and searching for the tag definition at ever-increasing -distances away from the recorded approximate position. - - When entering the tag argument to @kbd{M-.}, the usual minibuffer -completion commands can be used (@pxref{Completion}), with the tag -names in the selected tags table as completion candidates. If you -specify an empty argument, the balanced expression in the buffer -before or around point is the default argument. @xref{Expressions}. - - You don't need to give @kbd{M-.} the full name of the tag; a part -will do. @kbd{M-.} finds tags which contain that argument as a -substring. However, it prefers an exact match to a substring match. -To find other tags that match the same substring, give @code{find-tag} -a numeric argument, as in @kbd{C-u M-.} or @kbd{M-0 M-.}; this does -not read a tag name, but continues searching the tags table's text for -another tag containing the same substring last used. - -@kindex C-x 4 . -@findex find-tag-other-window -@kindex C-x 5 . -@findex find-tag-other-frame - Like most commands that can switch buffers, @code{find-tag} has a -variant that displays the new buffer in another window, and one that -makes a new frame for it. The former is @w{@kbd{C-x 4 .}} -(@code{find-tag-other-window}), and the latter is @w{@kbd{C-x 5 .}} -(@code{find-tag-other-frame}). - - To move back to previous tag definitions, use @kbd{C-u - M-.}; more -generally, @kbd{M-.} with a negative numeric argument. Similarly, -@w{@kbd{C-x 4 .}} with a negative argument finds the previous tag -location in another window. - -@kindex M-* -@findex pop-tag-mark -@vindex find-tag-marker-ring-length - As well as going back to places you've found tags recently, you can -go back to places @emph{from where} you found them, using @kbd{M-*} -(@code{pop-tag-mark}). Thus you can find and examine the definition -of something with @kbd{M-.} and then return to where you were with -@kbd{M-*}. - - Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to -a depth determined by the variable @code{find-tag-marker-ring-length}. - -@findex find-tag-regexp -@kindex C-M-. - The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that -match a specified regular expression. It is just like @kbd{M-.} except -that it does regexp matching instead of substring matching. - -@node Tags Search -@subsection Searching and Replacing with Tags Tables -@cindex search and replace in multiple files -@cindex multiple-file search and replace - - The commands in this section visit and search all the files listed -in the selected tags table, one by one. For these commands, the tags -table serves only to specify a sequence of files to search. These -commands scan the list of tags tables starting with the first tags -table (if any) that describes the current file, proceed from there to -the end of the list, and then scan from the beginning of the list -until they have covered all the tables in the list. - -@table @kbd -@item M-x tags-search @key{RET} @var{regexp} @key{RET} -Search for @var{regexp} through the files in the selected tags -table. -@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} -Perform a @code{query-replace-regexp} on each file in the selected tags table. -@item M-, -Restart one of the commands above, from the current location of point -(@code{tags-loop-continue}). -@end table - -@findex tags-search - @kbd{M-x tags-search} reads a regexp using the minibuffer, then -searches for matches in all the files in the selected tags table, one -file at a time. It displays the name of the file being searched so you -can follow its progress. As soon as it finds an occurrence, -@code{tags-search} returns. - -@kindex M-, -@findex tags-loop-continue - Having found one match, you probably want to find all the rest. -Type @kbd{M-,} (@code{tags-loop-continue}) to resume the -@code{tags-search}, finding one more match. This searches the rest of -the current buffer, followed by the remaining files of the tags table. - -@findex tags-query-replace - @kbd{M-x tags-query-replace} performs a single -@code{query-replace-regexp} through all the files in the tags table. It -reads a regexp to search for and a string to replace with, just like -ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x -tags-search}, but repeatedly, processing matches according to your -input. @xref{Replace}, for more information on query replace. - -@vindex tags-case-fold-search -@cindex case-sensitivity and tags search - You can control the case-sensitivity of tags search commands by -customizing the value of the variable @code{tags-case-fold-search}. The -default is to use the same setting as the value of -@code{case-fold-search} (@pxref{Search Case}). - - It is possible to get through all the files in the tags table with a -single invocation of @kbd{M-x tags-query-replace}. But often it is -useful to exit temporarily, which you can do with any input event that -has no special query replace meaning. You can resume the query -replace subsequently by typing @kbd{M-,}; this command resumes the -last tags search or replace command that you did. For instance, to -skip the rest of the current file, you can type @kbd{M-> M-,}. - - The commands in this section carry out much broader searches than the -@code{find-tag} family. The @code{find-tag} commands search only for -definitions of tags that match your substring or regexp. The commands -@code{tags-search} and @code{tags-query-replace} find every occurrence -of the regexp, as ordinary search commands and replace commands do in -the current buffer. - - These commands create buffers only temporarily for the files that they -have to search (those which are not already visited in Emacs buffers). -Buffers in which no match is found are quickly killed; the others -continue to exist. - - As an alternative to @code{tags-search}, you can run @command{grep} -as a subprocess and have Emacs show you the matching lines one by one. -@xref{Grep Searching}. - -@node List Tags -@subsection Tags Table Inquiries - -@table @kbd -@item C-M-i -@itemx M-@key{TAB} -Perform completion on the text around point, using the selected tags -table if one is loaded (@code{completion-at-point}). -@item M-x list-tags @key{RET} @var{file} @key{RET} -Display a list of the tags defined in the program file @var{file}. -@item M-x tags-apropos @key{RET} @var{regexp} @key{RET} -Display a list of all tags matching @var{regexp}. -@end table - -@cindex completion (symbol names) - In most programming language modes, you can type @kbd{C-M-i} or -@kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol -at point. If there is a selected tags table, this command can use it -to generate completion candidates. @xref{Symbol Completion}. - -@findex list-tags - @kbd{M-x list-tags} reads the name of one of the files covered by -the selected tags table, and displays a list of tags defined in that -file. Do not include a directory as part of the file name unless the -file name recorded in the tags table includes a directory. - -@findex tags-apropos -@vindex tags-apropos-verbose -@vindex tags-tag-face -@vindex tags-apropos-additional-actions - @kbd{M-x tags-apropos} is like @code{apropos} for tags -(@pxref{Apropos}). It displays a list of tags in the selected tags -table whose entries match @var{regexp}. If the variable -@code{tags-apropos-verbose} is non-@code{nil}, it displays the names -of the tags files together with the tag names. You can customize the -appearance of the output by setting the variable @code{tags-tag-face} -to a face. You can display additional output by customizing the -variable @code{tags-apropos-additional-actions}; see its documentation -for details. - -@findex next-file - @kbd{M-x next-file} visits files covered by the selected tags table. -The first time it is called, it visits the first file covered by the -table. Each subsequent call visits the next covered file, unless a -prefix argument is supplied, in which case it returns to the first -file. - -@node EDE -@section Emacs Development Environment -@cindex EDE (Emacs Development Environment) -@cindex Emacs Development Environment -@cindex Integrated development environment - -EDE (@dfn{Emacs Development Environment}) is a package that simplifies -the task of creating, building, and debugging large programs with -Emacs. It provides some of the features of an IDE, or @dfn{Integrated -Development Environment}, in Emacs. - -This section provides a brief description of EDE usage. -@ifnottex -For full details, see @ref{Top, EDE,, ede, Emacs Development Environment}. -@end ifnottex -@iftex -For full details on Ede, type @kbd{C-h i} and then select the EDE -manual. -@end iftex - - EDE is implemented as a global minor mode (@pxref{Minor Modes}). To -enable it, type @kbd{M-x global-ede-mode} or click on the -@samp{Project Support (EDE)} item in the @samp{Tools} menu. You can -also enable EDE each time you start Emacs, by adding the following -line to your initialization file: - -@smallexample -(global-ede-mode t) -@end smallexample - -@noindent -Activating EDE adds a menu named @samp{Development} to the menu bar. -Many EDE commands, including the ones described below, can be invoked -from this menu. - - EDE organizes files into @dfn{projects}, which correspond to -directory trees. The @dfn{project root} is the topmost directory of a -project. To define a new project, visit a file in the desired project -root and type @kbd{M-x ede-new}. This command prompts for a -@dfn{project type}, which refers to the underlying method that EDE -will use to manage the project (@pxref{Creating a Project, EDE,, ede, -Emacs Development Environment}). The most common project types are -@samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU -Automake (@pxref{Top, Automake,, automake, Automake}). In both cases, -EDE also creates a file named @file{Project.ede}, which stores -information about the project. - - A project may contain one or more @dfn{targets}. A target can be an -object file, executable program, or some other type of file, which is -``built'' from one or more of the files in the project. - - To add a new @dfn{target} to a project, type @kbd{C-c . t} -(@code{M-x ede-new-target}). This command also asks if you wish to -``add'' the current file to that target, which means that the target -is to be built from that file. After you have defined a target, you -can add more files to it by typing @kbd{C-c . a} -(@code{ede-add-file}). - - To build a target, type @kbd{C-c . c} (@code{ede-compile-target}). -To build all the targets in the project, type @kbd{C-c . C} -(@code{ede-compile-project}). EDE uses the file types to guess how -the target should be built. - -@ifnottex -@include emerge-xtra.texi -@end ifnottex diff --git a/doc/emacs/makefile.w32-in b/doc/emacs/makefile.w32-in deleted file mode 100644 index 488ccbaaf52..00000000000 --- a/doc/emacs/makefile.w32-in +++ /dev/null @@ -1,150 +0,0 @@ -#### -*- Makefile -*- for the Emacs Manual - -# Copyright (C) 2003-2012 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -# Where to find the source code. The source code for Emacs's C kernel is -# expected to be in $(srcdir)/src, and the source code for Emacs's -# utility programs is expected to be in $(srcdir)/lib-src. This is -# set by the configure script's `--srcdir' option. -srcdir=. - -infodir = $(srcdir)/../../info - -# The makeinfo program is part of the Texinfo distribution. -MAKEINFO = makeinfo -MAKEINFO_OPTS = --force --enable-encoding -I$(srcdir) -MULTI_INSTALL_INFO = $(srcdir)\..\..\nt\multi-install-info.bat -INFO_TARGETS = $(infodir)/emacs -DVI_TARGETS = emacs.dvi -INFOSOURCES = info.texi - -# The following rule does not work with all versions of `make'. -.SUFFIXES: .texi .dvi -.texi.dvi: - texi2dvi $< - -TEXI2DVI = texi2dvi -ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) $(MAKEINFO_OPTS)" /C - -EMACS_XTRA=\ - $(srcdir)/arevert-xtra.texi \ - $(srcdir)/cal-xtra.texi \ - $(srcdir)/dired-xtra.texi \ - $(srcdir)/picture-xtra.texi \ - $(srcdir)/emerge-xtra.texi \ - $(srcdir)/vc-xtra.texi \ - $(srcdir)/vc1-xtra.texi \ - $(srcdir)/fortran-xtra.texi \ - $(srcdir)/msdog-xtra.texi - -EMACSSOURCES= \ - $(srcdir)/emacs.texi \ - $(srcdir)/emacsver.texi \ - $(srcdir)/doclicense.texi \ - $(srcdir)/screen.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/entering.texi \ - $(srcdir)/basic.texi \ - $(srcdir)/mini.texi \ - $(srcdir)/m-x.texi \ - $(srcdir)/help.texi \ - $(srcdir)/mark.texi \ - $(srcdir)/killing.texi \ - $(srcdir)/regs.texi \ - $(srcdir)/display.texi \ - $(srcdir)/search.texi \ - $(srcdir)/fixit.texi \ - $(srcdir)/files.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/mule.texi \ - $(srcdir)/modes.texi \ - $(srcdir)/indent.texi \ - $(srcdir)/text.texi \ - $(srcdir)/programs.texi \ - $(srcdir)/building.texi \ - $(srcdir)/maintaining.texi \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/sending.texi \ - $(srcdir)/rmail.texi \ - $(srcdir)/dired.texi \ - $(srcdir)/calendar.texi \ - $(srcdir)/misc.texi \ - $(srcdir)/package.texi \ - $(srcdir)/custom.texi \ - $(srcdir)/trouble.texi \ - $(srcdir)/cmdargs.texi \ - $(srcdir)/xresources.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/macos.texi \ - $(srcdir)/msdog.texi \ - $(srcdir)/gnu.texi \ - $(srcdir)/glossary.texi \ - $(srcdir)/ack.texi \ - $(srcdir)/kmacro.texi \ - $(EMACS_XTRA) - -info: $(INFO_TARGETS) - -dvi: $(DVI_TARGETS) - -# Note that all the Info targets build the Info files -# in srcdir. There is no provision for Info files -# to exist in the build directory. -# In a distribution of Emacs, the Info files should be up to date. - -$(infodir)/dir: - $(MULTI_INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) - -$(infodir)/emacs: $(EMACSSOURCES) - $(MAKEINFO) $(MAKEINFO_OPTS) emacs.texi - -emacs.dvi: $(EMACSSOURCES) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs.texi - -emacs.html: $(EMACSSOURCES) - $(MAKEINFO) $(MAKEINFO_OPTS) --html -o $@ emacs.texi - -emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-xtra.texi - -mostlyclean: - - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* - -clean: mostlyclean - - $(DEL) *.dvi - - $(DEL) $(infodir)/emacs* - - $(DEL_TREE) emacs.html - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc -# Don't delete these, because they are outside the current directory. -# for file in $(INFO_TARGETS); do rm -f $${file}*; done - - -# Formerly this directory had texindex.c and getopt.c in it -# and this makefile built them to make texindex. -# That caused trouble because this is run entirely in the source directory. -# Since we expect to get texi2dvi from elsewhere, -# it is ok to expect texindex from elsewhere also. diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi deleted file mode 100644 index 9a15f9454dd..00000000000 --- a/doc/emacs/mark.texi +++ /dev/null @@ -1,471 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Mark, Killing, Help, Top -@chapter The Mark and the Region -@cindex mark -@cindex setting a mark -@cindex region - - Many Emacs commands operate on an arbitrary contiguous part of the -current buffer. To specify the text for such a command to operate on, -you set @dfn{the mark} at one end of it, and move point to the other -end. The text between point and the mark is called @dfn{the region}. -The region always extends between point and the mark, no matter which -one comes earlier in the text; each time you move point, the region -changes. - -@cindex active region - Setting the mark at a position in the text also @dfn{activates} it. -When the mark is active, we say also that the region is active; Emacs -indicates its extent by highlighting the text within it, using the -@code{region} face (@pxref{Face Customization}). - - After certain non-motion commands, including any command that -changes the text in the buffer, Emacs automatically @dfn{deactivates} -the mark; this turns off the highlighting. You can also explicitly -deactivate the mark at any time, by typing @kbd{C-g} -(@pxref{Quitting}). - - The above default behavior is known as Transient Mark mode. -Disabling Transient Mark mode switches Emacs to an alternative -behavior, in which the region is usually not highlighted. -@xref{Disabled Transient Mark}. - -@vindex highlight-nonselected-windows - Setting the mark in one buffer has no effect on the marks in other -buffers. When you return to a buffer with an active mark, the mark is -at the same place as before. When multiple windows show the same -buffer, they can have different values of point, and thus different -regions, but they all share one common mark position. @xref{Windows}. -Ordinarily, only the selected window highlights its region; however, -if the variable @code{highlight-nonselected-windows} is -non-@code{nil}, each window highlights its own region. - -@menu -* Setting Mark:: Commands to set the mark. -* Marking Objects:: Commands to put region around textual units. -* Using Region:: Summary of ways to operate on contents of the region. -* Mark Ring:: Previous mark positions saved so you can go back there. -* Global Mark Ring:: Previous mark positions in various buffers. -* Shift Selection:: Using shifted cursor motion keys. -* Disabled Transient Mark:: Leaving regions unhighlighted by default. -@end menu - -@node Setting Mark -@section Setting the Mark - - Here are some commands for setting the mark: - -@table @kbd -@item C-@key{SPC} -Set the mark at point, and activate it (@code{set-mark-command}). -@item C-@@ -The same. -@item C-x C-x -Set the mark at point, and activate it; then move point where the mark -used to be (@code{exchange-point-and-mark}). -@item Drag-Mouse-1 -Set point and the mark around the text you drag across. -@item Mouse-3 -Set the mark at point, then move point to where you click -(@code{mouse-save-then-kill}). -@item @samp{Shifted cursor motion keys} -Set the mark at point if the mark is inactive, then move point. -@xref{Shift Selection}. -@end table - -@kindex C-SPC -@kindex C-@@ -@findex set-mark-command - The most common way to set the mark is with @kbd{C-@key{SPC}} -(@code{set-mark-command})@footnote{There is no @kbd{C-@key{SPC}} -character in @acronym{ASCII}; usually, typing @kbd{C-@key{SPC}} on a -text terminal gives the character @kbd{C-@@}. This key is also bound -to @code{set-mark-command}, so unless you are unlucky enough to have -a text terminal that behaves differently, you might as well think of -@kbd{C-@@} as @kbd{C-@key{SPC}}.}. This sets the mark where point is, -and activates it. You can then move point away, leaving the mark -behind. - - For example, suppose you wish to convert part of the buffer to upper -case. To accomplish this, go to one end of the desired text, type -@kbd{C-@key{SPC}}, and move point until the desired portion of text is -highlighted. Now type @kbd{C-x C-u} (@code{upcase-region}). This -converts the text in the region to upper case, and then deactivates -the mark. - - Whenever the mark is active, you can deactivate it by typing -@kbd{C-g} (@pxref{Quitting}). Most commands that operate on the -region also automatically deactivate the mark, like @kbd{C-x C-u} in -the above example. - - Instead of setting the mark in order to operate on a region, you can -also use it to ``remember'' a position in the buffer (by typing -@kbd{C-@key{SPC} C-@key{SPC}}), and later jump back there (by typing -@kbd{C-u C-@key{SPC}}). @xref{Mark Ring}, for details. - -@kindex C-x C-x -@findex exchange-point-and-mark - The command @kbd{C-x C-x} (@code{exchange-point-and-mark}) exchanges -the positions of point and the mark. @kbd{C-x C-x} is useful when you -are satisfied with the position of point but want to move the other -end of the region (where the mark is). Using @kbd{C-x C-x} a second -time, if necessary, puts the mark at the new position with point back -at its original position. Normally, if the mark is inactive, this -command first reactivates the mark wherever it was last set, to ensure -that the region is left highlighted. However, if you call it with a -prefix argument, it leaves the mark inactive and the region -unhighlighted; you can use this to jump to the mark in a manner -similar to @kbd{C-u C-@key{SPC}}. - - You can also set the mark with the mouse. If you press the left -mouse button (@kbd{down-mouse-1}) and drag the mouse across a range of -text, this sets the mark where you first pressed the mouse button and -puts point where you release it. Alternatively, clicking the right -mouse button (@kbd{mouse-3}) sets the mark at point and then moves -point to where you clicked. @xref{Mouse Commands}, for a more -detailed description of these mouse commands. - -@cindex shift-selection - Finally, you can set the mark by holding down the shift key while -typing certain cursor motion commands (such as @kbd{S-@key{right}}, -@kbd{S-C-f}, @kbd{S-C-n}, etc.) This is called @dfn{shift-selection}. -It sets the mark at point before moving point, but only if there is no -active mark set via shift-selection. The mark set by mouse commands -and by shift-selection behaves slightly differently from the usual -mark: any subsequent unshifted cursor motion command deactivates it -automatically. For details, @xref{Shift Selection}. - - Many commands that insert text, such as @kbd{C-y} (@code{yank}), set -the mark at the other end of the inserted text, without activating it. -This lets you easily return to that position (@pxref{Mark Ring}). You -can tell that a command does this when it shows @samp{Mark set} in the -echo area. - -@cindex primary selection - Under X, every time the active region changes, Emacs saves the text -in the region to the @dfn{primary selection}. This lets you insert -that text into other X applications with @kbd{mouse-2} clicks. -@xref{Primary Selection}. - -@node Marking Objects -@section Commands to Mark Textual Objects - -@cindex marking sections of text - Here are commands for placing point and the mark around a textual -object such as a word, list, paragraph or page: - -@table @kbd -@item M-@@ -Set mark after end of next word (@code{mark-word}). This does not -move point. -@item C-M-@@ -Set mark after end of following balanced expression -(@code{mark-sexp}). This does not move point. -@item M-h -Move point to the beginning of the current paragraph, and set mark at -the end (@code{mark-paragraph}). -@item C-M-h -Move point to the beginning of the current defun, and set mark at the -end (@code{mark-defun}). -@item C-x C-p -Move point to the beginning of the current page, and set mark at the -end (@code{mark-page}). -@item C-x h -Move point to the beginning of the buffer, and set mark at the end -(@code{mark-whole-buffer}). -@end table - -@kindex M-@@ -@findex mark-word - @kbd{M-@@} (@code{mark-word}) sets the mark at the end of the next -word (@pxref{Words}, for information about words). Repeated -invocations of this command extend the region by advancing the mark -one word at a time. As an exception, if the mark is active and -located before point, @kbd{M-@@} moves the mark backwards from its -current position one word at a time. - - This command also accepts a numeric argument @var{n}, which tells it -to advance the mark by @var{n} words. A negative argument moves the -mark back by @var{n} words. - -@kindex C-M-@@ -@findex mark-sexp - Similarly, @kbd{C-M-@@} (@code{mark-sexp}) puts the mark at the end -of the next balanced expression (@pxref{Expressions}). Repeated -invocations extend the region to subsequent expressions, while -positive or negative numeric arguments move the mark forward or -backward by the specified number of expressions. - - The other commands in the above list set both point and mark, so as -to delimit an object in the buffer. @kbd{M-h} (@code{mark-paragraph}) -marks paragraphs (@pxref{Paragraphs}), @kbd{C-M-h} (@code{mark-defun}) -marks top-level definitions (@pxref{Moving by Defuns}), and @kbd{C-x -C-p} (@code{mark-page}) marks pages (@pxref{Pages}). Repeated -invocations again play the same role, extending the region to -consecutive objects; similarly, numeric arguments specify how many -objects to move the mark by. - -@kindex C-x h -@findex mark-whole-buffer -@cindex select all - @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire buffer as -the region, by putting point at the beginning and the mark at the end. - -@node Using Region -@section Operating on the Region - -@cindex operations on a marked region - Once you have a region, here are some of the ways you can operate on -it: - -@itemize @bullet -@item -Kill it with @kbd{C-w} (@pxref{Killing}). -@item -Copy it to the kill ring with @kbd{M-w} (@pxref{Yanking}). -@item -Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} (@pxref{Case}). -@item -Undo changes within it using @kbd{C-u C-/} (@pxref{Undo}). -@item -Replace text within it using @kbd{M-%} (@pxref{Query Replace}). -@item -Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}). -@item -Fill it as text with @kbd{M-x fill-region} (@pxref{Filling}). -@item -Check the spelling of words within it with @kbd{M-$} (@pxref{Spelling}). -@item -Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}). -@item -Save it in a register with @kbd{C-x r s} (@pxref{Registers}). -@item -Save it in a buffer or a file (@pxref{Accumulating Text}). -@end itemize - - Some commands have a default behavior when the mark is inactive, but -operate on the region if the mark is active. For example, @kbd{M-$} -(@code{ispell-word}) normally checks the spelling of the word at -point, but it checks the text in the region if the mark is active -(@pxref{Spelling}). Normally, such commands use their default -behavior if the region is empty (i.e., if mark and point are at the -same position). If you want them to operate on the empty region, -change the variable @code{use-empty-active-region} to @code{t}. - -@vindex delete-active-region - As described in @ref{Erasing}, the @key{DEL} -(@code{backward-delete-char}) and @key{delete} -(@code{delete-forward-char}) commands also act this way. If the mark -is active, they delete the text in the region. (As an exception, if -you supply a numeric argument @var{n}, where @var{n} is not one, these -commands delete @var{n} characters regardless of whether the mark is -active). If you change the variable @code{delete-active-region} to -@code{nil}, then these commands don't act differently when the mark is -active. If you change the value to @code{kill}, these commands -@dfn{kill} the region instead of deleting it (@pxref{Killing}). - -@vindex mark-even-if-inactive - Other commands always operate on the region, and have no default -behavior. Such commands usually have the word @code{region} in their -names, like @kbd{C-w} (@code{kill-region}) and @code{C-x C-u} -(@code{upcase-region}). If the mark is inactive, they operate on the -``inactive region''---that is, on the text between point and the -position at which the mark was last set (@pxref{Mark Ring}). To -disable this behavior, change the variable -@code{mark-even-if-inactive} to @code{nil}. Then these commands will -instead signal an error if the mark is inactive. - -@cindex Delete Selection mode -@cindex mode, Delete Selection -@findex delete-selection-mode - By default, text insertion occurs normally even if the mark is -active---for example, typing @kbd{a} inserts the character @samp{a}, -then deactivates the mark. If you enable Delete Selection mode, a -minor mode, then inserting text while the mark is active causes the -text in the region to be deleted first. To toggle Delete Selection -mode on or off, type @kbd{M-x delete-selection-mode}. - -@node Mark Ring -@section The Mark Ring - -@cindex mark ring - Each buffer remembers previous locations of the mark, in the -@dfn{mark ring}. Commands that set the mark also push the old mark -onto this ring. One of the uses of the mark ring is to remember spots -that you may want to go back to. - -@table @kbd -@item C-@key{SPC} C-@key{SPC} -Set the mark, pushing it onto the mark ring, without activating it. -@item C-u C-@key{SPC} -Move point to where the mark was, and restore the mark from the ring -of former marks. -@end table - -@kindex C-SPC C-SPC - The command @kbd{C-@key{SPC} C-@key{SPC}} is handy when you want to -use the mark to remember a position to which you may wish to return. -It pushes the current point onto the mark ring, without activating the -mark (which would cause Emacs to highlight the region). This is -actually two consecutive invocations of @kbd{C-@key{SPC}} -(@code{set-mark-command}); the first @kbd{C-@key{SPC}} sets the mark, -and the second @kbd{C-@key{SPC}} deactivates it. (When Transient Mark -mode is off, @kbd{C-@key{SPC} C-@key{SPC}} instead activates Transient -Mark mode temporarily; @pxref{Disabled Transient Mark}.) - -@kindex C-u C-SPC - To return to a marked position, use @code{set-mark-command} with a -prefix argument: @kbd{C-u C-@key{SPC}}. This moves point to where the -mark was, and deactivates the mark if it was active. Each subsequent -@kbd{C-u C-@key{SPC}} jumps to a prior position stored in the mark -ring. The positions you move through in this way are not lost; they -go to the end of the ring. - -@vindex set-mark-command-repeat-pop - If you set @code{set-mark-command-repeat-pop} to non-@code{nil}, -then immediately after you type @kbd{C-u C-@key{SPC}}, you can type -@kbd{C-@key{SPC}} instead of @kbd{C-u C-@key{SPC}} to cycle through -the mark ring. By default, @code{set-mark-command-repeat-pop} is -@code{nil}. - - Each buffer has its own mark ring. All editing commands use the -current buffer's mark ring. In particular, @kbd{C-u C-@key{SPC}} -always stays in the same buffer. - -@vindex mark-ring-max - The variable @code{mark-ring-max} specifies the maximum number of -entries to keep in the mark ring. This defaults to 16 entries. If -that many entries exist and another one is pushed, the earliest one in -the list is discarded. Repeating @kbd{C-u C-@key{SPC}} cycles through -the positions currently in the ring. - - If you want to move back to the same place over and over, the mark -ring may not be convenient enough. If so, you can record the position -in a register for later retrieval (@pxref{Position Registers,, Saving -Positions in Registers}). - -@node Global Mark Ring -@section The Global Mark Ring -@cindex global mark ring - -@vindex global-mark-ring-max - In addition to the ordinary mark ring that belongs to each buffer, -Emacs has a single @dfn{global mark ring}. Each time you set a mark, -this is recorded in the global mark ring in addition to the current -buffer's own mark ring, if you have switched buffers since the -previous mark setting. Hence, the global mark ring records a sequence -of buffers that you have been in, and, for each buffer, a place where -you set the mark. The length of the global mark ring is controlled by -@code{global-mark-ring-max}, and is 16 by default. - -@kindex C-x C-@key{SPC} -@findex pop-global-mark - The command @kbd{C-x C-@key{SPC}} (@code{pop-global-mark}) jumps to -the buffer and position of the latest entry in the global ring. It also -rotates the ring, so that successive uses of @kbd{C-x C-@key{SPC}} take -you to earlier buffers and mark positions. - -@node Shift Selection -@section Shift Selection -@cindex shift-selection - - If you hold down the shift key while typing a cursor motion command, -this sets the mark before moving point, so that the region extends -from the original position of point to its new position. This feature -is referred to as @dfn{shift-selection}. It is similar to the way -text is selected in other editors. - - The mark set via shift-selection behaves a little differently from -what we have described above. Firstly, in addition to the usual ways -of deactivating the mark (such as changing the buffer text or typing -@kbd{C-g}), the mark is deactivated by any @emph{unshifted} cursor -motion command. Secondly, any subsequent @emph{shifted} cursor motion -command avoids setting the mark anew. Therefore, a series of shifted -cursor motion commands will continuously adjust the region. - - Shift-selection only works if the shifted cursor motion key is not -already bound to a separate command (@pxref{Customization}). For -example, if you bind @kbd{S-C-f} to another command, typing -@kbd{S-C-f} runs that command instead of performing a shift-selected -version of @kbd{C-f} (@code{forward-char}). - - A mark set via mouse commands behaves the same as a mark set via -shift-selection (@pxref{Setting Mark}). For example, if you specify a -region by dragging the mouse, you can continue to extend the region -using shifted cursor motion commands. In either case, any unshifted -cursor motion command deactivates the mark. - - To turn off shift-selection, set @code{shift-select-mode} to -@code{nil}. Doing so does not disable setting the mark via mouse -commands. - -@node Disabled Transient Mark -@section Disabling Transient Mark Mode -@cindex mode, Transient Mark -@cindex Transient Mark mode -@cindex highlighting region -@cindex region highlighting -@cindex Zmacs mode -@findex transient-mark-mode - - The default behavior of the mark and region, in which setting the -mark activates it and highlights the region, is called Transient Mark -mode. This is a minor mode that is enabled by default. It can be -toggled with @kbd{M-x transient-mark-mode}, or with the @samp{Active -Region Highlighting} menu item in the @samp{Options} menu. Turning it -off switches Emacs to an alternative mode of operation: - -@itemize @bullet -@item -Setting the mark, with commands like @kbd{C-@key{SPC}} or @kbd{C-x -C-x}, does not highlight the region. Therefore, you can't tell by -looking where the mark is located; you have to remember. - -The usual solution to this problem is to set the mark and then use it -soon, before you forget where it is. You can also check where the -mark is by using @kbd{C-x C-x}, which exchanges the positions of the -point and the mark (@pxref{Setting Mark}). - -@item -Many commands that move point long distances, like @kbd{M-<} and -@kbd{C-s}, first set the mark where point was. - -@item -Some commands, which ordinarily act on the region when the mark is -active, no longer do so. For example, normally @kbd{M-%} -(@code{query-replace}) performs replacements within the region, if the -mark is active. When Transient Mark mode is off, it always operates -from point to the end of the buffer. Commands that act this way are -identified in their own documentation. -@end itemize - - While Transient Mark mode is off, you can activate it temporarily -using @kbd{C-@key{SPC} C-@key{SPC}} or @kbd{C-u C-x C-x}. - -@table @kbd -@item C-@key{SPC} C-@key{SPC} -@kindex C-@key{SPC} C-@key{SPC} -Set the mark at point (like plain @kbd{C-@key{SPC}}) and enable -Transient Mark mode just once, until the mark is deactivated. (This -is not really a separate command; you are using the @kbd{C-@key{SPC}} -command twice.) - -@item C-u C-x C-x -@kindex C-u C-x C-x -Activate the mark and enable Transient Mark mode temporarily, until -the mark is next deactivated. (This is the @kbd{C-x C-x} command, -@code{exchange-point-and-mark}, with a prefix argument.) -@end table - - These commands set or activate the mark, and enable Transient Mark -mode only until the mark is deactivated. One reason you may want to -use them is that some commands operate on the entire buffer instead of -the region when Transient Mark mode is off. Enabling Transient Mark -mode momentarily gives you a way to use these commands on the region. - - When you specify a region with the mouse (@pxref{Setting Mark}), or -with shift-selection (@pxref{Shift Selection}), this likewise -activates Transient Mark mode temporarily and highlights the region. diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi deleted file mode 100644 index f50e3085f2d..00000000000 --- a/doc/emacs/mini.texi +++ /dev/null @@ -1,735 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Minibuffer, M-x, Basic, Top -@chapter The Minibuffer -@cindex minibuffer - - The @dfn{minibuffer} is where Emacs commands read complicated -arguments, such as file names, buffer names, Emacs command names, or -Lisp expressions. We call it the ``minibuffer'' because it's a -special-purpose buffer with a small amount of screen space. You can -use the usual Emacs editing commands in the minibuffer to edit the -argument text. - -@cindex prompt - When the minibuffer is in use, it appears in the echo area, with a -cursor. The minibuffer starts with a @dfn{prompt} in a distinct -color, usually ending with a colon. The prompt states what kind of -input is expected, and how it will be used. - - The simplest way to enter a minibuffer argument is to type the text, -then @key{RET} to submit the argument and exit the minibuffer. You -can cancel the minibuffer, and the command that wants the argument, by -typing @kbd{C-g}. - -@cindex default argument - Sometimes, a @dfn{default argument} appears in the prompt, inside -parentheses before the colon. This default will be used as the -argument if you just type @key{RET}. For example, commands that read -buffer names usually show a buffer name as the default; you can type -@key{RET} to operate on that default buffer. - - Since the minibuffer appears in the echo area, it can conflict with -other uses of the echo area. If an error message or an informative -message is emitted while the minibuffer is active, the message hides -the minibuffer for a few seconds, or until you type something; then -the minibuffer comes back. While the minibuffer is in use, keystrokes -do not echo. - -@menu -* Minibuffer File:: Entering file names with the minibuffer. -* Minibuffer Edit:: How to edit in the minibuffer. -* Completion:: An abbreviation facility for minibuffer input. -* Minibuffer History:: Reusing recent minibuffer arguments. -* Repetition:: Re-executing commands that used the minibuffer. -* Passwords:: Entering passwords in the echo area. -@end menu - -@node Minibuffer File -@section Minibuffers for File Names - -@cindex default directory - Commands such as @kbd{C-x C-f} (@code{find-file}) use the minibuffer -to read a file name argument (@pxref{Basic Files}). When the -minibuffer is used to read a file name, it typically starts out with -some initial text ending in a slash. This is the @dfn{default -directory}. For example, it may start out like this: - -@example -Find file: /u2/emacs/src/ -@end example - -@noindent -Here, @samp{Find file:@: } is the prompt and @samp{/u2/emacs/src/} is -the default directory. If you now type @kbd{buffer.c} as input, that -specifies the file @file{/u2/emacs/src/buffer.c}. @xref{File Names}, -for information about the default directory. - - You can specify the parent directory with @file{..}: -@file{/a/b/../foo.el} is equivalent to @file{/a/foo.el}. -Alternatively, you can use @kbd{M-@key{DEL}} to kill directory names -backwards (@pxref{Words}). - - To specify a file in a completely different directory, you can kill -the entire default with @kbd{C-a C-k} (@pxref{Minibuffer Edit}). -Alternatively, you can ignore the default, and enter an absolute file -name starting with a slash or a tilde after the default directory. -For example, you can specify @file{/etc/termcap} as follows: - -@example -Find file: /u2/emacs/src//etc/termcap -@end example - -@noindent -@cindex // in file name -@cindex double slash in file name -@cindex slashes repeated in file name -@findex file-name-shadow-mode -Emacs interprets a double slash as ``ignore everything before the -second slash in the pair''. In the example above, -@file{/u2/emacs/src/} is ignored, so the argument you supplied is -@file{/etc/termcap}. The ignored part of the file name is dimmed if -the terminal allows it. (To disable this dimming, turn off File Name -Shadow mode with the command @kbd{M-x file-name-shadow-mode}.) - -@cindex home directory shorthand - Emacs interprets @file{~/} as your home directory. Thus, -@file{~/foo/bar.txt} specifies a file named @file{bar.txt}, inside a -directory named @file{foo}, which is in turn located in your home -directory. In addition, @file{~@var{user-id}/} means the home -directory of a user whose login name is @var{user-id}. Any leading -directory name in front of the @file{~} is ignored: thus, -@file{/u2/emacs/~/foo/bar.txt} is equivalent to @file{~/foo/bar.txt}. - - On MS-Windows and MS-DOS systems, where a user doesn't always have a -home directory, Emacs uses several alternatives. For MS-Windows, see -@ref{Windows HOME}; for MS-DOS, see -@ifnottex -@ref{MS-DOS File Names}. -@end ifnottex -@iftex -@ref{MS-DOS File Names, HOME on MS-DOS,, emacs, the digital version of -the Emacs Manual}. -@end iftex -On these systems, the @file{~@var{user-id}/} construct is supported -only for the current user, i.e., only if @var{user-id} is the current -user's login name. - -@vindex insert-default-directory - To prevent Emacs from inserting the default directory when reading -file names, change the variable @code{insert-default-directory} to -@code{nil}. In that case, the minibuffer starts out empty. -Nonetheless, relative file name arguments are still interpreted based -on the same default directory. - - You can also enter remote file names in the minibuffer. -@xref{Remote Files}. - -@node Minibuffer Edit -@section Editing in the Minibuffer - - The minibuffer is an Emacs buffer, albeit a peculiar one, and the -usual Emacs commands are available for editing the argument text. -(The prompt, however, is @dfn{read-only}, and cannot be changed.) - - Since @key{RET} in the minibuffer submits the argument, you can't -use it to insert a newline. You can do that with @kbd{C-q C-j}, which -inserts a @kbd{C-j} control character, which is formally equivalent to -a newline character (@pxref{Inserting Text}). Alternatively, you can -use the @kbd{C-o} (@code{open-line}) command (@pxref{Blank Lines}). - - Inside a minibuffer, the keys @key{TAB}, @key{SPC}, and @kbd{?} are -often bound to @dfn{completion commands}, which allow you to easily -fill in the desired text without typing all of it. @xref{Completion}. -As with @key{RET}, you can use @kbd{C-q} to insert a @key{TAB}, -@key{SPC}, or @samp{?} character. - - For convenience, @kbd{C-a} (@code{move-beginning-of-line}) in a -minibuffer moves point to the beginning of the argument text, not the -beginning of the prompt. For example, this allows you to erase the -entire argument with @kbd{C-a C-k}. - -@cindex height of minibuffer -@cindex size of minibuffer -@cindex growing minibuffer -@cindex resizing minibuffer - When the minibuffer is active, the echo area is treated much like an -ordinary Emacs window. For instance, you can switch to another window -(with @kbd{C-x o}), edit text there, then return to the minibuffer -window to finish the argument. You can even kill text in another -window, return to the minibuffer window, and yank the text into the -argument. There are some restrictions on the minibuffer window, -however: for instance, you cannot split it. @xref{Windows}. - -@vindex resize-mini-windows - Normally, the minibuffer window occupies a single screen line. -However, if you add two or more lines' worth of text into the -minibuffer, it expands automatically to accommodate the text. The -variable @code{resize-mini-windows} controls the resizing of the -minibuffer. The default value is @code{grow-only}, which means the -behavior we have just described. If the value is @code{t}, the -minibuffer window will also shrink automatically if you remove some -lines of text from the minibuffer, down to a minimum of one screen -line. If the value is @code{nil}, the minibuffer window never changes -size automatically, but you can use the usual window-resizing commands -on it (@pxref{Windows}). - -@vindex max-mini-window-height - The variable @code{max-mini-window-height} controls the maximum -height for resizing the minibuffer window. A floating-point number -specifies a fraction of the frame's height; an integer specifies the -maximum number of lines; @code{nil} means do not resize the minibuffer -window automatically. The default value is 0.25. - - The @kbd{C-M-v} command in the minibuffer scrolls the help text from -commands that display help text of any sort in another window. You -can also scroll the help text with @kbd{M-@key{prior}} and -@kbd{M-@key{next}} (or, equivalently, @kbd{M-@key{PageUp}} and -@kbd{M-@key{PageDown}}). This is especially useful with long lists of -possible completions. @xref{Other Window}. - -@vindex enable-recursive-minibuffers - Emacs normally disallows most commands that use the minibuffer while -the minibuffer is active. To allow such commands in the minibuffer, -set the variable @code{enable-recursive-minibuffers} to @code{t}. - -@findex minibuffer-inactive-mode - When not active, the minibuffer is in @code{minibuffer-inactive-mode}, -and clicking @kbd{Mouse-1} there shows the @file{*Messages*} buffer. -If you use a dedicated frame for minibuffers, Emacs also recognizes -certain keys there, for example @kbd{n} to make a new frame. - -@node Completion -@section Completion -@c This node is referenced in the tutorial. When renaming or deleting -@c it, the tutorial needs to be adjusted. -@cindex completion - - You can often use a feature called @dfn{completion} to help enter -arguments. This means that after you type part of the argument, Emacs -can fill in the rest, or some of it, based on what was typed so far. - -@cindex completion alternative - When completion is available, certain keys (usually @key{TAB}, -@key{RET}, and @key{SPC}) are rebound in the minibuffer to special -completion commands (@pxref{Completion Commands}). These commands -attempt to complete the text in the minibuffer, based on a set of -@dfn{completion alternatives} provided by the command that requested -the argument. You can usually type @kbd{?} to see a list of -completion alternatives. - - Although completion is usually done in the minibuffer, the feature -is sometimes available in ordinary buffers too. @xref{Symbol -Completion}. - -@menu -* Completion Example:: Examples of using completion. -* Completion Commands:: A list of completion commands. -* Completion Exit:: Completion and minibuffer text submission. -* Completion Styles:: How completion matches are chosen. -* Completion Options:: Options for completion. -@end menu - -@node Completion Example -@subsection Completion Example - -@kindex TAB @r{(completion)} - A simple example may help here. @kbd{M-x} uses the minibuffer to -read the name of a command, so completion works by matching the -minibuffer text against the names of existing Emacs commands. Suppose -you wish to run the command @code{auto-fill-mode}. You can do that by -typing @kbd{M-x auto-fill-mode @key{RET}}, but it is easier to use -completion. - - If you type @kbd{M-x a u @key{TAB}}, the @key{TAB} looks for -completion alternatives (in this case, command names) that start with -@samp{au}. There are several, including @code{auto-fill-mode} and -@code{autoconf-mode}, but they all begin with @code{auto}, so the -@samp{au} in the minibuffer completes to @samp{auto}. (More commands -may be defined in your Emacs session. For example, if a command -called @code{authorize-me} was defined, Emacs could only complete -as far as @samp{aut}.) - - If you type @key{TAB} again immediately, it cannot determine the -next character; it could be @samp{-}, @samp{a}, or @samp{c}. So it -does not add any characters; instead, @key{TAB} displays a list of all -possible completions in another window. - - Next, type @kbd{-f}. The minibuffer now contains @samp{auto-f}, and -the only command name that starts with this is @code{auto-fill-mode}. -If you now type @key{TAB}, completion fills in the rest of the -argument @samp{auto-fill-mode} into the minibuffer. - - Hence, typing just @kbd{a u @key{TAB} - f @key{TAB}} allows you to -enter @samp{auto-fill-mode}. - -@node Completion Commands -@subsection Completion Commands - - Here is a list of the completion commands defined in the minibuffer -when completion is allowed. - -@table @kbd -@item @key{TAB} -@findex minibuffer-complete -Complete the text in the minibuffer as much as possible; if unable to -complete, display a list of possible completions -(@code{minibuffer-complete}). -@item @key{SPC} -Complete up to one word from the minibuffer text before point -(@code{minibuffer-complete-word}). This command is not available for -arguments that often include spaces, such as file names. -@item @key{RET} -Submit the text in the minibuffer as the argument, possibly completing -first (@code{minibuffer-complete-and-exit}). @xref{Completion Exit}. -@item ? -Display a list of completions (@code{minibuffer-completion-help}). -@end table - -@kindex TAB @r{(completion)} -@findex minibuffer-complete - @key{TAB} (@code{minibuffer-complete}) is the most fundamental -completion command. It searches for all possible completions that -match the existing minibuffer text, and attempts to complete as much -as it can. @xref{Completion Styles}, for how completion alternatives -are chosen. - -@kindex SPC @r{(completion)} -@findex minibuffer-complete-word - @key{SPC} (@code{minibuffer-complete-word}) completes like -@key{TAB}, but only up to the next hyphen or space. If you have -@samp{auto-f} in the minibuffer and type @key{SPC}, it finds that the -completion is @samp{auto-fill-mode}, but it only inserts @samp{ill-}, -giving @samp{auto-fill-}. Another @key{SPC} at this point completes -all the way to @samp{auto-fill-mode}. - -@kindex ? @r{(completion)} -@cindex completion list - If @key{TAB} or @key{SPC} is unable to complete, it displays a list -of matching completion alternatives (if there are any) in another -window. You can display the same list with @kbd{?} -(@code{minibuffer-completion-help}). The following commands can be -used with the completion list: - -@table @kbd -@findex mouse-choose-completion -@item Mouse-1 -@itemx Mouse-2 -Clicking mouse button 1 or 2 on a completion alternative chooses it -(@code{mouse-choose-completion}). - -@findex switch-to-completions -@item M-v -@itemx @key{PageUp} -@itemx @key{prior} -Typing @kbd{M-v}, while in the minibuffer, selects the window showing -the completion list (@code{switch-to-completions}). This paves the -way for using the commands below. @key{PageUp} or @key{prior} does -the same. You can also select the window in other ways -(@pxref{Windows}). - -@findex choose-completion -@item @key{RET} -While in the completion list buffer, this chooses the completion at -point (@code{choose-completion}). - -@findex next-completion -@item @key{Right} -While in the completion list buffer, this moves point to the following -completion alternative (@code{next-completion}). - -@findex previous-completion -@item @key{Left} -While in the completion list buffer, this moves point to the previous -completion alternative (@code{previous-completion}). -@end table - -@node Completion Exit -@subsection Completion Exit - -@kindex RET @r{(completion in minibuffer)} -@findex minibuffer-complete-and-exit - When a command reads an argument using the minibuffer with -completion, it also controls what happens when you type @key{RET} -(@code{minibuffer-complete-and-exit}) to submit the argument. There -are four types of behavior: - -@itemize @bullet -@item -@dfn{Strict completion} accepts only exact completion matches. Typing -@key{RET} exits the minibuffer only if the minibuffer text is an exact -match, or completes to one. Otherwise, Emacs refuses to exit the -minibuffer; instead it tries to complete, and if no completion can be -done it momentarily displays @samp{[No match]} after the minibuffer -text. (You can still leave the minibuffer by typing @kbd{C-g} to -cancel the command.) - -An example of a command that uses this behavior is @kbd{M-x}, since it -is meaningless for it to accept a non-existent command name. - -@item -@dfn{Cautious completion} is like strict completion, except @key{RET} -exits only if the text is already an exact match. If the text -completes to an exact match, @key{RET} performs that completion but -does not exit yet; you must type a second @key{RET} to exit. - -Cautious completion is used for reading file names for files that must -already exist, for example. - -@item -@dfn{Permissive completion} allows any input; the completion -candidates are just suggestions. Typing @key{RET} does not complete, -it just submits the argument as you have entered it. - -@cindex minibuffer confirmation -@cindex confirming in the minibuffer -@item -@dfn{Permissive completion with confirmation} is like permissive -completion, with an exception: if you typed @key{TAB} and this -completed the text up to some intermediate state (i.e., one that is not -yet an exact completion match), typing @key{RET} right afterward does -not submit the argument. Instead, Emacs asks for confirmation by -momentarily displaying @samp{[Confirm]} after the text; type @key{RET} -again to confirm and submit the text. This catches a common mistake, -in which one types @key{RET} before realizing that @key{TAB} did not -complete as far as desired. - -@vindex confirm-nonexistent-file-or-buffer -You can tweak the confirmation behavior by customizing the variable -@code{confirm-nonexistent-file-or-buffer}. The default value, -@code{after-completion}, gives the behavior we have just described. -If you change it to @code{nil}, Emacs does not ask for confirmation, -falling back on permissive completion. If you change it to any other -non-@code{nil} value, Emacs asks for confirmation whether or not the -preceding command was @key{TAB}. - -This behavior is used by most commands that read file names, like -@kbd{C-x C-f}, and commands that read buffer names, like @kbd{C-x b}. -@end itemize - -@node Completion Styles -@subsection How Completion Alternatives Are Chosen -@cindex completion style - - Completion commands work by narrowing a large list of possible -completion alternatives to a smaller subset that ``matches'' what you -have typed in the minibuffer. In @ref{Completion Example}, we gave a -simple example of such matching. The procedure of determining what -constitutes a ``match'' is quite intricate. Emacs attempts to offer -plausible completions under most circumstances. - - Emacs performs completion using one or more @dfn{completion -styles}---sets of criteria for matching minibuffer text to completion -alternatives. During completion, Emacs tries each completion style in -turn. If a style yields one or more matches, that is used as the list -of completion alternatives. If a style produces no matches, Emacs -falls back on the next style. - -@vindex completion-styles - The list variable @code{completion-styles} specifies the completion -styles to use. Each list element is the name of a completion style (a -Lisp symbol). The default completion styles are (in order): - -@table @code -@item basic -A matching completion alternative must have the same beginning as the -text in the minibuffer before point. Furthermore, if there is any -text in the minibuffer after point, the rest of the completion -alternative must contain that text as a substring. - -@findex partial completion -@item partial-completion -This aggressive completion style divides the minibuffer text into -words separated by hyphens or spaces, and completes each word -separately. (For example, when completing command names, -@samp{em-l-m} completes to @samp{emacs-lisp-mode}.) - -Furthermore, a @samp{*} in the minibuffer text is treated as a -@dfn{wildcard}---it matches any character at the corresponding -position in the completion alternative. - -@item emacs22 -This completion style is similar to @code{basic}, except that it -ignores the text in the minibuffer after point. It is so-named -because it corresponds to the completion behavior in Emacs 22. -@end table - -@noindent -The following additional completion styles are also defined, and you -can add them to @code{completion-styles} if you wish -(@pxref{Customization}): - -@table @code -@item substring -A matching completion alternative must contain the text in the -minibuffer before point, and the text in the minibuffer after point, -as substrings (in that same order). - -Thus, if the text in the minibuffer is @samp{foobar}, with point -between @samp{foo} and @samp{bar}, that matches -@samp{@var{a}foo@var{b}bar@var{c}}, where @var{a}, @var{b}, and -@var{c} can be any string including the empty string. - -@item initials -This very aggressive completion style attempts to complete acronyms -and initialisms. For example, when completing command names, it -matches @samp{lch} to @samp{list-command-history}. -@end table - -@noindent -There is also a very simple completion style called @code{emacs21}. -In this style, if the text in the minibuffer is @samp{foobar}, -only matches starting with @samp{foobar} are considered. - -@vindex completion-category-overrides -You can use different completion styles in different situations, -by setting the variable @code{completion-category-overrides}. -For example, the default setting says to use only @code{basic} -and @code{substring} completion for buffer names. - - -@node Completion Options -@subsection Completion Options - -@cindex case-sensitivity and completion -@cindex case in completion - Case is significant when completing case-sensitive arguments, such -as command names. For example, when completing command names, -@samp{AU} does not complete to @samp{auto-fill-mode}. Case -differences are ignored when completing arguments in which case does -not matter. - -@vindex read-file-name-completion-ignore-case -@vindex read-buffer-completion-ignore-case - When completing file names, case differences are ignored if the -variable @code{read-file-name-completion-ignore-case} is -non-@code{nil}. The default value is @code{nil} on systems that have -case-sensitive file-names, such as GNU/Linux; it is non-@code{nil} on -systems that have case-insensitive file-names, such as Microsoft -Windows. When completing buffer names, case differences are ignored -if the variable @code{read-buffer-completion-ignore-case} is -non-@code{nil}; the default is @code{nil}. - -@vindex completion-ignored-extensions -@cindex ignored file names, in completion - When completing file names, Emacs usually omits certain alternatives -that are considered unlikely to be chosen, as determined by the list -variable @code{completion-ignored-extensions}. Each element in the -list should be a string; any file name ending in such a string is -ignored as a completion alternative. Any element ending in a slash -(@file{/}) represents a subdirectory name. The standard value of -@code{completion-ignored-extensions} has several elements including -@code{".o"}, @code{".elc"}, and @code{"~"}. For example, if a -directory contains @samp{foo.c} and @samp{foo.elc}, @samp{foo} -completes to @samp{foo.c}. However, if @emph{all} possible -completions end in ``ignored'' strings, they are not ignored: in the -previous example, @samp{foo.e} completes to @samp{foo.elc}. Emacs -disregards @code{completion-ignored-extensions} when showing -completion alternatives in the completion list. - -@vindex completion-auto-help - If @code{completion-auto-help} is set to @code{nil}, the completion -commands never display the completion list buffer; you must type -@kbd{?} to display the list. If the value is @code{lazy}, Emacs only -shows the completion list buffer on the second attempt to complete. -In other words, if there is nothing to complete, the first @key{TAB} -echoes @samp{Next char not unique}; the second @key{TAB} shows the -completion list buffer. - -@vindex completion-cycle-threshold - If @code{completion-cycle-threshold} is non-@code{nil}, completion -commands can ``cycle'' through completion alternatives. Normally, if -there is more than one completion alternative for the text in the -minibuffer, a completion command completes up to the longest common -substring. If you change @code{completion-cycle-threshold} to -@code{t}, the completion command instead completes to the first of -those completion alternatives; each subsequent invocation of the -completion command replaces that with the next completion alternative, -in a cyclic manner. If you give @code{completion-cycle-threshold} a -numeric value @var{n}, completion commands switch to this cycling -behavior only when there are fewer than @var{n} alternatives. - -@cindex Icomplete mode -@findex icomplete-mode - Icomplete mode presents a constantly-updated display that tells you -what completions are available for the text you've entered so far. The -command to enable or disable this minor mode is @kbd{M-x -icomplete-mode}. - -@node Minibuffer History -@section Minibuffer History -@cindex minibuffer history -@cindex history of minibuffer input - - Every argument that you enter with the minibuffer is saved in a -@dfn{minibuffer history list} so you can easily use it again later. -You can use the following arguments to quickly fetch an earlier -argument into the minibuffer: - -@table @kbd -@item M-p -@itemx @key{Up} -Move to the previous item in the minibuffer history, an earlier -argument (@code{previous-history-element}). -@item M-n -@itemx @key{Down} -Move to the next item in the minibuffer history -(@code{next-history-element}). -@item M-r @var{regexp} @key{RET} -Move to an earlier item in the minibuffer history that -matches @var{regexp} (@code{previous-matching-history-element}). -@item M-s @var{regexp} @key{RET} -Move to a later item in the minibuffer history that matches -@var{regexp} (@code{next-matching-history-element}). -@end table - -@kindex M-p @r{(minibuffer history)} -@kindex M-n @r{(minibuffer history)} -@kindex UP @r{(minibuffer history)} -@kindex DOWN @r{(minibuffer history)} -@findex next-history-element -@findex previous-history-element - While in the minibuffer, @kbd{M-p} or @key{Up} -(@code{previous-history-element}) moves through the minibuffer history -list, one item at a time. Each @kbd{M-p} fetches an earlier item from -the history list into the minibuffer, replacing its existing contents. -Typing @kbd{M-n} or @key{Down} (@code{next-history-element}) moves -through the minibuffer history list in the opposite direction, -fetching later entries into the minibuffer. - - If you type @kbd{M-n} in the minibuffer when there are no later -entries in the minibuffer history (e.g., if you haven't previously -typed @kbd{M-p}), Emacs tries fetching from a list of default -arguments: values that you are likely to enter. You can think of this -as moving through the ``future history'' list. - - If you edit the text inserted by the @kbd{M-p} or @key{M-n} -minibuffer history commands, this does not change its entry in the -history list. However, the edited argument does go at the end of the -history list when you submit it. - -@findex previous-matching-history-element -@findex next-matching-history-element -@kindex M-r @r{(minibuffer history)} -@kindex M-s @r{(minibuffer history)} - You can use @kbd{M-r} (@code{previous-matching-history-element}) to -search through older elements in the history list, and @kbd{M-s} -(@code{next-matching-history-element}) to search through newer -entries. Each of these commands asks for a @dfn{regular expression} -as an argument, and fetches the first matching entry into the -minibuffer. @xref{Regexps}, for an explanation of regular -expressions. A numeric prefix argument @var{n} means to fetch the -@var{n}th matching entry. These commands are unusual, in that they -use the minibuffer to read the regular expression argument, even -though they are invoked from the minibuffer. An upper-case letter in -the regular expression makes the search case-sensitive (@pxref{Search -Case}). - - You can also search through the history using an incremental search. -@xref{Isearch Minibuffer}. - - Emacs keeps separate history lists for several different kinds of -arguments. For example, there is a list for file names, used by all -the commands that read file names. Other history lists include buffer -names, command names (used by @kbd{M-x}), and command arguments (used -by commands like @code{query-replace}). - -@vindex history-length - The variable @code{history-length} specifies the maximum length of a -minibuffer history list; adding a new element deletes the oldest -element if the list gets too long. If the value is @code{t}, there is -no maximum length. - -@vindex history-delete-duplicates - The variable @code{history-delete-duplicates} specifies whether to -delete duplicates in history. If it is non-@code{nil}, adding a new -element deletes from the list all other elements that are equal to it. -The default is @code{nil}. - -@node Repetition -@section Repeating Minibuffer Commands -@cindex command history -@cindex history of commands - - Every command that uses the minibuffer once is recorded on a special -history list, the @dfn{command history}, together with the values of -its arguments, so that you can repeat the entire command. In -particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x} -uses the minibuffer to read the command name. - -@findex list-command-history -@table @kbd -@item C-x @key{ESC} @key{ESC} -Re-execute a recent minibuffer command from the command history - (@code{repeat-complex-command}). -@item M-x list-command-history -Display the entire command history, showing all the commands -@kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first. -@end table - -@kindex C-x ESC ESC -@findex repeat-complex-command - @kbd{C-x @key{ESC} @key{ESC}} re-executes a recent command that used -the minibuffer. With no argument, it repeats the last such command. -A numeric argument specifies which command to repeat; 1 means the last -one, 2 the previous, and so on. - - @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command -into a Lisp expression and then entering a minibuffer initialized with -the text for that expression. Even if you don't know Lisp, it will -probably be obvious which command is displayed for repetition. If you -type just @key{RET}, that repeats the command unchanged. You can also -change the command by editing the Lisp expression before you execute -it. The repeated command is added to the front of the command history -unless it is identical to the most recent item. - - Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you -can use the usual minibuffer history commands (@pxref{Minibuffer -History}) to move through the history list. After finding the desired -previous command, you can edit its expression as usual and then repeat -it by typing @key{RET}. - -@vindex isearch-resume-in-command-history - Incremental search does not, strictly speaking, use the minibuffer. -Therefore, although it behaves like a complex command, it normally -does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}. -You can make incremental search commands appear in the history by -setting @code{isearch-resume-in-command-history} to a non-@code{nil} -value. @xref{Incremental Search}. - -@vindex command-history - The list of previous minibuffer-using commands is stored as a Lisp -list in the variable @code{command-history}. Each element is a Lisp -expression that describes one command and its arguments. Lisp programs -can re-execute a command by calling @code{eval} with the -@code{command-history} element. - -@node Passwords -@section Entering passwords - -Sometimes, you may need to enter a password into Emacs. For instance, -when you tell Emacs to visit a file on another machine via a network -protocol such as FTP, you often need to supply a password to gain -access to the machine (@pxref{Remote Files}). - - Entering a password is similar to using a minibuffer. Emacs -displays a prompt in the echo area (such as @samp{Password: }); after -you type the required password, press @key{RET} to submit it. To -prevent others from seeing your password, every character you type is -displayed as a dot (@samp{.}) instead of its usual form. - - Most of the features and commands associated with the minibuffer can -@emph{not} be used when entering a password. There is no history or -completion, and you cannot change windows or perform any other action -with Emacs until you have submitted the password. - - While you are typing the password, you may press @key{DEL} to delete -backwards, removing the last character entered. @key{C-u} deletes -everything you have typed so far. @kbd{C-g} quits the password prompt -(@pxref{Quitting}). @kbd{C-y} inserts the current kill into the -password (@pxref{Killing}). You may type either @key{RET} or -@key{ESC} to submit the password. Any other self-inserting character -key inserts the associated character into the password, and all other -input is ignored. diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi deleted file mode 100644 index ecbcda1ce8a..00000000000 --- a/doc/emacs/misc.texi +++ /dev/null @@ -1,2583 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Miscellaneous Commands - - This chapter contains several brief topics that do not fit anywhere -else: viewing ``document files'', reading Usenet news, running shell -commands and shell subprocesses, using a single shared Emacs for -utilities that expect to run an editor as a subprocess, printing -hardcopy, sorting text, narrowing display to part of the buffer, -editing binary files, saving an Emacs session for later resumption, -following hyperlinks, browsing images, emulating other editors, and -various diversions and amusements. - -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node Gnus -@section Gnus -@cindex Gnus -@cindex Usenet news -@cindex newsreader - - Gnus is an Emacs package primarily designed for reading and posting -Usenet news. It can also be used to read and respond to messages from -a number of other sources---email, remote directories, digests, and so -on. Here we introduce Gnus and describe several basic features. -@ifnottex -For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}. -@end ifnottex -@iftex -For full details on Gnus, type @kbd{C-h i} and then select the Gnus -manual. -@end iftex - -@menu -* Buffers of Gnus:: The group, summary, and article buffers. -* Gnus Startup:: What you should know about starting Gnus. -* Gnus Group Buffer:: A short description of Gnus group commands. -* Gnus Summary Buffer:: A short description of Gnus summary commands. -@end menu - -@node Buffers of Gnus -@subsection Gnus Buffers - - Gnus uses several buffers to display information and to receive -commands. The three most commonly-used Gnus buffers are the -@dfn{group buffer}, the @dfn{summary buffer} and the @dfn{article -buffer}. - - The @dfn{group buffer} contains a list of article sources (e.g.@: -newsgroups and email inboxes), which are collectively referred to as -@dfn{groups}. This is the first buffer Gnus displays when it starts -up. It normally displays only the groups to which you subscribe and -that contain unread articles. From this buffer, you can select a -group to read. - - The @dfn{summary buffer} lists the articles in a single group, -showing one article per line. By default, it displays each article's -author, subject, and line -@iftex -number. -@end iftex -@ifnottex -number, but this is customizable; @xref{Summary Buffer Format,,, gnus, -The Gnus Manual}. -@end ifnottex -The summary buffer is created when you select a group in the group -buffer, and is killed when you exit the group. - - From the summary buffer, you can choose an article to view. The -article is displayed in the @dfn{article buffer}. In normal Gnus -usage, you view this buffer but do not select it---all useful Gnus -commands can be invoked from the summary buffer. But you can select -the article buffer, and execute Gnus commands from it, if you wish. - -@node Gnus Startup -@subsection When Gnus Starts Up - -@findex gnus -@cindex @file{.newsrc} file - If your system has been set up for reading Usenet news, getting -started with Gnus is easy---just type @kbd{M-x gnus}. - - On starting up, Gnus reads your @dfn{news initialization file}: a -file named @file{.newsrc} in your home directory which lists your -Usenet newsgroups and subscriptions (this file is not unique to Gnus; -it is used by many other newsreader programs). It then tries to -contact the system's default news server, which is typically specified -by the @env{NNTPSERVER} environment variable. - - If your system does not have a default news server, or if you wish -to use Gnus for reading email, then before invoking @kbd{M-x gnus} you -need to tell Gnus where to get news and/or mail. To do this, -customize the variables @code{gnus-select-method} and/or -@code{gnus-secondary-select-methods}. -@iftex -See the Gnus manual for details. -@end iftex -@ifnottex -@xref{Finding the News,,, gnus, The Gnus Manual}. -@end ifnottex - - Once Gnus has started up, it displays the group buffer. By default, -the group buffer shows only a small number of @dfn{subscribed groups}. -Groups with other statuses---@dfn{unsubscribed}, @dfn{killed}, or -@dfn{zombie}---are hidden. The first time you start Gnus, any group -to which you are not subscribed is made into a killed group; any group -that subsequently appears on the news server becomes a zombie group. - - To proceed, you must select a group in the group buffer to open the -summary buffer for that group; then, select an article in the summary -buffer to view its article buffer in a separate window. The following -sections explain how to use the group and summary buffers to do this. - - To quit Gnus, type @kbd{q} in the group buffer. This automatically -records your group statuses in the files @file{.newsrc} and -@file{.newsrc.eld}, so that they take effect in subsequent Gnus -sessions. - -@node Gnus Group Buffer -@subsection Using the Gnus Group Buffer - - The following commands are available in the Gnus group buffer: - -@table @kbd -@kindex SPC @r{(Gnus Group mode)} -@findex gnus-group-read-group -@item @key{SPC} -Switch to the summary buffer for the group on the current line. - -@kindex l @r{(Gnus Group mode)} -@kindex A s @r{(Gnus Group mode)} -@findex gnus-group-list-groups -@item l -@itemx A s -In the group buffer, list only the groups to which you subscribe and -which contain unread articles (this is the default listing). - -@kindex L @r{(Gnus Group mode)} -@kindex A u @r{(Gnus Group mode)} -@findex gnus-group-list-all-groups -@item L -@itemx A u -List all subscribed and unsubscribed groups, but not killed or zombie -groups. - -@kindex A k @r{(Gnus Group mode)} -@findex gnus-group-list-all-groups -@item A k -List killed groups. - -@kindex A z @r{(Gnus Group mode)} -@findex gnus-group-list-all-groups -@item A z -List zombie groups. - -@kindex u @r{(Gnus Group mode)} -@findex gnus-group-unsubscribe-current-group -@cindex subscribe groups -@cindex unsubscribe groups -@item u -Toggle the subscription status of the group on the current line -(i.e.@: turn a subscribed group into an unsubscribed group, or vice -versa). Invoking this on a killed or zombie group turns it into an -unsubscribed group. - -@kindex C-k @r{(Gnus Group mode)} -@findex gnus-group-kill-group -@item C-k -Kill the group on the current line. Killed groups are not recorded in -the @file{.newsrc} file, and they are not shown in the @kbd{l} or -@kbd{L} listings. - -@kindex DEL @r{(Gnus Group mode)} -@item @key{DEL} -Move point to the previous group containing unread articles. - -@kindex n @r{(Gnus Group mode)} -@findex gnus-group-next-unread-group -@findex gnus-summary-next-unread-article -@item n -Move point to the next unread group. - -@kindex p @r{(Gnus Group mode)} -@findex gnus-group-prev-unread-group -@findex gnus-summary-prev-unread-article -@item p -Move point to the previous unread group. - -@kindex q @r{(Gnus Group mode)} -@findex gnus-group-exit -@item q -Update your Gnus settings, and quit Gnus. -@end table - -@node Gnus Summary Buffer -@subsection Using the Gnus Summary Buffer - - The following commands are available in the Gnus summary buffer: - -@table @kbd -@kindex SPC @r{(Gnus Summary mode)} -@findex gnus-group-read-group -@item @key{SPC} -If there is no article selected, select the article on the current -line and display its article buffer. Otherwise, try scrolling the -selected article buffer in its window; on reaching the end of the -buffer, select the next unread article. - -Thus, you can read through all articles by repeatedly typing -@key{SPC}. - -@kindex DEL @r{(Gnus Summary mode)} -@findex gnus-summary-prev-page -@item @key{DEL} -Scroll the text of the article backwards. - -@kindex n @r{(Gnus Summary mode)} -@findex gnus-group-next-unread-group -@findex gnus-summary-next-unread-article -@item n -Select the next unread article. - -@kindex p @r{(Gnus Summary mode)} -@findex gnus-group-prev-unread-group -@findex gnus-summary-prev-unread-article -@item p -Select the previous unread article. - -@kindex s @r{(Gnus Summary mode)} -@findex gnus-summary-isearch-article -@item s -Do an incremental search on the selected article buffer, as if you -switched to the buffer and typed @kbd{C-s} (@pxref{Incremental -Search}). - -@kindex M-s @r{(Gnus Summary mode)} -@findex gnus-summary-search-article-forward -@item M-s @var{regexp} @key{RET} -Search forward for articles containing a match for @var{regexp}. - -@kindex q @r{(Gnus Summary mode)} -@item q -Exit the summary buffer and return to the group buffer. -@end table - -@node Document View -@section Document Viewing -@cindex DVI file -@cindex PDF file -@cindex PS file -@cindex PostScript file -@cindex OpenDocument file -@cindex Microsoft Office file -@cindex DocView mode -@cindex mode, DocView -@cindex document viewer (DocView) -@findex doc-view-mode - - DocView mode is a major mode for viewing DVI, PostScript (PS), PDF, -OpenDocument, and Microsoft Office documents. It provides features -such as slicing, zooming, and searching inside documents. It works by -converting the document to a set of images using the @command{gs} -(GhostScript) command and other external tools @footnote{@code{gs} is -a hard requirement. For DVI files, @code{dvipdf} or @code{dvipdfm} is -needed. For OpenDocument and Microsoft Office documents, the -@code{unoconv} tool is needed.}, and displaying those images. - -@findex doc-view-toggle-display -@findex doc-view-toggle-display -@cindex doc-view-minor-mode - When you visit a document file that can be displayed with DocView -mode, Emacs automatically uses DocView mode @footnote{The needed -external tools for the document type must be available, and Emacs must -be running in a graphical frame and have PNG image support. If any of -these requirements is not fulfilled, Emacs falls back to another major -mode.}. As an exception, when you visit a PostScript file, Emacs -switches to PS mode, a major mode for editing PostScript files as -text; however, it also enables DocView minor mode, so you can type -@kbd{C-c C-c} to view the document with DocView. In either DocView -mode or DocView minor mode, repeating @kbd{C-c C-c} -(@code{doc-view-toggle-display}) toggles between DocView and the -underlying file contents. - - You can explicitly enable DocView mode with the command @code{M-x -doc-view-mode}. You can toggle DocView minor mode with @code{M-x -doc-view-minor-mode}. - - When DocView mode starts, it displays a welcome screen and begins -formatting the file, page by page. It displays the first page once -that has been formatted. - - To kill the DocView buffer, type @kbd{k} -(@code{doc-view-kill-proc-and-buffer}). To bury it, type @kbd{q} -(@code{quit-window}). - -@menu -* Navigation: DocView Navigation. Navigating DocView buffers. -* Searching: DocView Searching. Searching inside documents. -* Slicing: DocView Slicing. Specifying which part of a page is displayed. -* Conversion: DocView Conversion. Influencing and triggering conversion. -@end menu - -@node DocView Navigation -@subsection DocView Navigation - - In DocView mode, you can scroll the current page using the usual -Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and -the arrow keys. - -@vindex doc-view-continuous - By default, the line-motion keys @kbd{C-p} and @kbd{C-n} stop -scrolling at the beginning and end of the current page, respectively. -However, if you change the variable @code{doc-view-continuous} to a -non-@code{nil} value, then @kbd{C-p} displays the previous page if you -are already at the beginning of the current page, and @kbd{C-n} -displays the next page if you are at the end of the current page. - -@findex doc-view-next-page -@findex doc-view-previous-page -@kindex n @r{(DocView mode)} -@kindex p @r{(DocView mode)} -@kindex C-x ] @r{(DocView mode)} -@kindex C-x [ @r{(DocView mode)} - You can also display the next page by typing @kbd{n}, @key{next} or -@kbd{C-x ]} (@code{doc-view-next-page}). To display the previous -page, type @kbd{p}, @key{prior} or @kbd{C-x [} -(@code{doc-view-previous-page}). - -@findex doc-view-scroll-up-or-next-page -@findex doc-view-scroll-down-or-previous-page -@kindex SPC @r{(DocView mode)} -@kindex DEL @r{(DocView mode)} - @key{SPC} (@code{doc-view-scroll-up-or-next-page}) is a convenient -way to advance through the document. It scrolls within the current -page or advances to the next. @key{DEL} moves backwards in a similar -way (@code{doc-view-scroll-down-or-previous-page}). - -@findex doc-view-first-page -@findex doc-view-last-page -@findex doc-view-goto-page -@kindex M-< @r{(DocView mode)} -@kindex M-> @r{(DocView mode)} - To go to the first page, type @kbd{M-<} -(@code{doc-view-first-page}); to go to the last one, type @kbd{M->} -(@code{doc-view-last-page}). To jump to a page by its number, type -@kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}). - -@findex doc-view-enlarge -@findex doc-view-shrink -@vindex doc-view-resolution -@kindex + @r{(DocView mode)} -@kindex - @r{(DocView mode)} - You can enlarge or shrink the document with @kbd{+} -(@code{doc-view-enlarge}) and @kbd{-} (@code{doc-view-shrink}). These -commands work by reconverting the document at the new size. To -specify the default size for DocView, customize the variable -@code{doc-view-resolution}. - -@node DocView Searching -@subsection DocView Searching - - In DocView mode, you can search the file's text for a regular -expression (@pxref{Regexps}). The interface for searching is inspired -by @code{isearch} (@pxref{Incremental Search}). - -@findex doc-view-search -@findex doc-view-search-backward -@findex doc-view-show-tooltip - To begin a search, type @kbd{C-s} (@code{doc-view-search}) or -@kbd{C-r} (@code{doc-view-search-backward}). This reads a regular -expression using a minibuffer, then echoes the number of matches found -within the document. You can move forward and back among the matches -by typing @kbd{C-s} and @kbd{C-r}. DocView mode has no way to show -the match inside the page image; instead, it displays a tooltip (at -the mouse position) listing all matching lines in the current page. -To force display of this tooltip, type @kbd{C-t} -(@code{doc-view-show-tooltip}). - - To start a new search, use the search command with a prefix -argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r} -for a backward search. - -@node DocView Slicing -@subsection DocView Slicing - -Documents often have wide margins for printing. They are annoying -when reading the document on the screen, because they use up screen -space and can cause inconvenient scrolling. - -@findex doc-view-set-slice -@findex doc-view-set-slice-using-mouse - With DocView you can hide these margins by selecting a @dfn{slice} -of pages to display. A slice is a rectangle within the page area; -once you specify a slice in DocView, it applies to whichever page you -look at. - - To specify the slice numerically, type @kbd{s s} -(@code{doc-view-set-slice}); then enter the top left pixel position -and the slice's width and height. -@c ??? how does this work? - - A more convenient graphical way to specify the slice is with @kbd{s -m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to -select the slice. -@c ??? How does this work? - -@findex doc-view-reset-slice - To cancel the selected slice, type @kbd{s r} -(@code{doc-view-reset-slice}). Then DocView shows the entire page -including its entire margins. - -@node DocView Conversion -@subsection DocView Conversion - -@vindex doc-view-cache-directory -@findex doc-view-clear-cache - For efficiency, DocView caches the images produced by @command{gs}. -The name of this directory is given by the variable -@code{doc-view-cache-directory}. You can clear the cache directory by -typing @code{M-x doc-view-clear-cache}. - -@findex doc-view-kill-proc -@findex doc-view-kill-proc-and-buffer - To force reconversion of the currently viewed document, type @kbd{r} -or @kbd{g} (@code{revert-buffer}). To kill the converter process -associated with the current buffer, type @kbd{K} -(@code{doc-view-kill-proc}). The command @kbd{k} -(@code{doc-view-kill-proc-and-buffer}) kills the converter process and -the DocView buffer. - -@node Shell -@section Running Shell Commands from Emacs -@cindex subshell -@cindex shell commands - - Emacs has commands for passing single command lines to shell -subprocesses, and for running a shell interactively with input and -output to an Emacs buffer, and for running a shell in a terminal -emulator window. - -@table @kbd -@item M-! @var{cmd} @key{RET} -Run the shell command @var{cmd} and display the output -(@code{shell-command}). -@item M-| @var{cmd} @key{RET} -Run the shell command @var{cmd} with region contents as input; -optionally replace the region with the output -(@code{shell-command-on-region}). -@item M-& @var{cmd} @key{RET} -Run the shell command @var{cmd} asynchronously, and display the output -(@code{async-shell-command}). -@item M-x shell -Run a subshell with input and output through an Emacs buffer. You can -then give commands interactively. -@item M-x term -Run a subshell with input and output through an Emacs buffer. You can -then give commands interactively. Full terminal emulation is -available. -@end table - -@vindex exec-path - Whenever you specify a relative file name for an executable program -(either in the @var{cmd} argument to one of the above commands, or in -other contexts), Emacs searches for the program in the directories -specified by the variable @code{exec-path}. The value of this -variable must be a list of directory names; the default value is -initialized from the environment variable @env{PATH} when Emacs is -started (@pxref{General Variables}). - - @kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It -is documented in its own manual. -@ifnottex -@xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}. -@end ifnottex -@iftex -See the Eshell Info manual, which is distributed with Emacs. -@end iftex - -@menu -* Single Shell:: How to run one shell command and return. -* Interactive Shell:: Permanent shell taking input via Emacs. -* Shell Mode:: Special Emacs commands used with permanent shell. -* Shell Prompts:: Two ways to recognize shell prompts. -* History: Shell History. Repeating previous commands in a shell buffer. -* Directory Tracking:: Keeping track when the subshell changes directory. -* Options: Shell Options. Options for customizing Shell mode. -* Terminal emulator:: An Emacs window as a terminal emulator. -* Term Mode:: Special Emacs commands used in Term mode. -* Remote Host:: Connecting to another computer. -* Serial Terminal:: Connecting to a serial port. -@end menu - -@node Single Shell -@subsection Single Shell Commands - -@kindex M-! -@findex shell-command - @kbd{M-!} (@code{shell-command}) reads a line of text using the -minibuffer and executes it as a shell command, in a subshell made just -for that command. Standard input for the command comes from the null -device. If the shell command produces any output, the output appears -either in the echo area (if it is short), or in an Emacs buffer named -@file{*Shell Command Output*}, displayed in another window (if the -output is long). - - For instance, one way to decompress a file named @file{foo.gz} is to -type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command normally -creates the file @file{foo} and produces no terminal output. - - A numeric argument to @code{shell-command}, e.g.@: @kbd{M-1 M-!}, -causes it to insert terminal output into the current buffer instead of -a separate buffer. It puts point before the output, and sets the mark -after the output. For instance, @kbd{M-1 M-! gunzip < foo.gz -@key{RET}} would insert the uncompressed form of the file -@file{foo.gz} into the current buffer. - - Provided the specified shell command does not end with @samp{&}, it -runs @dfn{synchronously}, and you must wait for it to exit before -continuing to use Emacs. To stop waiting, type @kbd{C-g} to quit; -this sends a @code{SIGINT} signal to terminate the shell command (this -is the same signal that @kbd{C-c} normally generates in the shell). -Emacs then waits until the command actually terminates. If the shell -command doesn't stop (because it ignores the @code{SIGINT} signal), -type @kbd{C-g} again; this sends the command a @code{SIGKILL} signal, -which is impossible to ignore. - -@kindex M-& -@findex async-shell-command - A shell command that ends in @samp{&} is executed -@dfn{asynchronously}, and you can continue to use Emacs as it runs. -You can also type @kbd{M-&} (@code{async-shell-command}) to execute a -shell command asynchronously; this is exactly like calling @kbd{M-!} -with a trailing @samp{&}, except that you do not need the @samp{&}. -The output buffer for asynchronous shell commands is named -@samp{*Async Shell Command*}. Emacs inserts the output into this -buffer as it comes in, whether or not the buffer is visible in a -window. - -@kindex M-| -@findex shell-command-on-region - @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!}, but -passes the contents of the region as the standard input to the shell -command, instead of no input. With a numeric argument, it deletes the -old region and replaces it with the output from the shell command. - - For example, you can use @kbd{M-|} with the @command{gpg} program to -see what keys are in the buffer. If the buffer contains a GnuPG key, -type @kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents -to @command{gpg}. This will output the list of keys to the -@file{*Shell Command Output*} buffer. - -@vindex shell-file-name - The above commands use the shell specified by the variable -@code{shell-file-name}. Its default value is determined by the -@env{SHELL} environment variable when Emacs is started. If the file -name is relative, Emacs searches the directories listed in -@code{exec-path} (@pxref{Shell}). - - To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command -@kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}. - -@vindex shell-command-default-error-buffer - By default, error output is intermixed with the regular output in -the output buffer. But if you change the value of the variable -@code{shell-command-default-error-buffer} to a string, error output is -inserted into a buffer of that name. - -@node Interactive Shell -@subsection Interactive Subshell - -@findex shell - To run a subshell interactively, type @kbd{M-x shell}. This creates -(or reuses) a buffer named @file{*shell*}, and runs a shell subprocess -with input coming from and output going to that buffer. That is to -say, any terminal output from the subshell goes into the buffer, -advancing point, and any terminal input for the subshell comes from -text in the buffer. To give input to the subshell, go to the end of -the buffer and type the input, terminated by @key{RET}. - - While the subshell is waiting or running a command, you can switch -windows or buffers and perform other editing in Emacs. Emacs inserts -the output from the subshell into the Shell buffer whenever it has -time to process it (e.g.@: while waiting for keyboard input). - -@cindex @code{comint-highlight-input} face -@cindex @code{comint-highlight-prompt} face - In the Shell buffer, prompts are displayed with the face -@code{comint-highlight-prompt}, and submitted input lines are -displayed with the face @code{comint-highlight-input}. This makes it -easier to distinguish input lines from the shell output. -@xref{Faces}. - - To make multiple subshells, invoke @kbd{M-x shell} with a prefix -argument (e.g. @kbd{C-u M-x shell}). Then the command will read a -buffer name, and create (or reuse) a subshell in that buffer. You can -also rename the @file{*shell*} buffer using @kbd{M-x rename-uniquely}, -then create a new @file{*shell*} buffer using plain @kbd{M-x shell}. -Subshells in different buffers run independently and in parallel. - -@vindex explicit-shell-file-name -@cindex environment variables for subshells -@cindex @env{ESHELL} environment variable -@cindex @env{SHELL} environment variable - To specify the shell file name used by @kbd{M-x shell}, customize -the variable @code{explicit-shell-file-name}. If this is @code{nil} -(the default), Emacs uses the environment variable @env{ESHELL} if it -exists. Otherwise, it usually uses the variable -@code{shell-file-name} (@pxref{Single Shell}); but if the default -directory is remote (@pxref{Remote Files}), it prompts you for the -shell file name. - - Emacs sends the new shell the contents of the file -@file{~/.emacs_@var{shellname}} as input, if it exists, where -@var{shellname} is the name of the file that the shell was loaded -from. For example, if you use bash, the file sent to it is -@file{~/.emacs_bash}. If this file is not found, Emacs tries with -@file{~/.emacs.d/init_@var{shellname}.sh}. - - To specify a coding system for the shell, you can use the command -@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can -also change the coding system for a running subshell by typing -@kbd{C-x @key{RET} p} in the shell buffer. @xref{Communication -Coding}. - -@cindex @env{INSIDE_EMACS} environment variable -@cindex @env{EMACS} environment variable - Emacs sets the environment variable @env{INSIDE_EMACS} in the -subshell to @samp{@var{version},comint}, where @var{version} is the -Emacs version (e.g.@: @samp{24.1}). Programs can check this variable -to determine whether they are running inside an Emacs subshell. (It -also sets the @env{EMACS} environment variable to @code{t}, if that -environment variable is not already defined. However, this -environment variable is deprecated; programs that use it should switch -to using @env{INSIDE_EMACS} instead.) - -@node Shell Mode -@subsection Shell Mode -@cindex Shell mode -@cindex mode, Shell - - The major mode for Shell buffers is Shell mode. Many of its special -commands are bound to the @kbd{C-c} prefix, and resemble the usual -editing and job control characters present in ordinary shells, except -that you must type @kbd{C-c} first. Here is a list of Shell mode -commands: - -@table @kbd -@item @key{RET} -@kindex RET @r{(Shell mode)} -@findex comint-send-input -Send the current line as input to the subshell -(@code{comint-send-input}). Any shell prompt at the beginning of the -line is omitted (@pxref{Shell Prompts}). If point is at the end of -buffer, this is like submitting the command line in an ordinary -interactive shell. However, you can also invoke @key{RET} elsewhere -in the shell buffer to submit the current line as input. - -@item @key{TAB} -@kindex TAB @r{(Shell mode)} -@findex completion-at-point -Complete the command name or file name before point in the shell -buffer (@code{completion-at-point}). This uses the usual Emacs -completion rules (@pxref{Completion}), with the completion -alternatives being file names, environment variable names, the shell -command history, and history references (@pxref{History References}). - -@vindex shell-completion-fignore -@vindex comint-completion-fignore -The variable @code{shell-completion-fignore} specifies a list of file -name extensions to ignore in Shell mode completion. The default -setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to -ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other -related Comint modes use the variable @code{comint-completion-fignore} -instead. - -@item M-? -@kindex M-? @r{(Shell mode)} -@findex comint-dynamic-list-filename@dots{} -Display temporarily a list of the possible completions of the file -name before point (@code{comint-dynamic-list-filename-completions}). - -@item C-d -@kindex C-d @r{(Shell mode)} -@findex comint-delchar-or-maybe-eof -Either delete a character or send @acronym{EOF} -(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell -buffer, this sends @acronym{EOF} to the subshell. Typed at any other -position in the buffer, this deletes a character as usual. - -@item C-c C-a -@kindex C-c C-a @r{(Shell mode)} -@findex comint-bol-or-process-mark -Move to the beginning of the line, but after the prompt if any -(@code{comint-bol-or-process-mark}). If you repeat this command twice -in a row, the second time it moves back to the process mark, which is -the beginning of the input that you have not yet sent to the subshell. -(Normally that is the same place---the end of the prompt on this -line---but after @kbd{C-c @key{SPC}} the process mark may be in a -previous line.) - -@item C-c @key{SPC} -Accumulate multiple lines of input, then send them together. This -command inserts a newline before point, but does not send the preceding -text as input to the subshell---at least, not yet. Both lines, the one -before this newline and the one after, will be sent together (along with -the newline that separates them), when you type @key{RET}. - -@item C-c C-u -@kindex C-c C-u @r{(Shell mode)} -@findex comint-kill-input -Kill all text pending at end of buffer to be sent as input -(@code{comint-kill-input}). If point is not at end of buffer, -this only kills the part of this text that precedes point. - -@item C-c C-w -@kindex C-c C-w @r{(Shell mode)} -Kill a word before point (@code{backward-kill-word}). - -@item C-c C-c -@kindex C-c C-c @r{(Shell mode)} -@findex comint-interrupt-subjob -Interrupt the shell or its current subjob if any -(@code{comint-interrupt-subjob}). This command also kills -any shell input pending in the shell buffer and not yet sent. - -@item C-c C-z -@kindex C-c C-z @r{(Shell mode)} -@findex comint-stop-subjob -Stop the shell or its current subjob if any (@code{comint-stop-subjob}). -This command also kills any shell input pending in the shell buffer and -not yet sent. - -@item C-c C-\ -@findex comint-quit-subjob -@kindex C-c C-\ @r{(Shell mode)} -Send quit signal to the shell or its current subjob if any -(@code{comint-quit-subjob}). This command also kills any shell input -pending in the shell buffer and not yet sent. - -@item C-c C-o -@kindex C-c C-o @r{(Shell mode)} -@findex comint-delete-output -Delete the last batch of output from a shell command -(@code{comint-delete-output}). This is useful if a shell command spews -out lots of output that just gets in the way. - -@item C-c C-s -@kindex C-c C-s @r{(Shell mode)} -@findex comint-write-output -Write the last batch of output from a shell command to a file -(@code{comint-write-output}). With a prefix argument, the file is -appended to instead. Any prompt at the end of the output is not -written. - -@item C-c C-r -@itemx C-M-l -@kindex C-c C-r @r{(Shell mode)} -@kindex C-M-l @r{(Shell mode)} -@findex comint-show-output -Scroll to display the beginning of the last batch of output at the top -of the window; also move the cursor there (@code{comint-show-output}). - -@item C-c C-e -@kindex C-c C-e @r{(Shell mode)} -@findex comint-show-maximum-output -Scroll to put the end of the buffer at the bottom of the window -(@code{comint-show-maximum-output}). - -@item C-c C-f -@kindex C-c C-f @r{(Shell mode)} -@findex shell-forward-command -@vindex shell-command-regexp -Move forward across one shell command, but not beyond the current line -(@code{shell-forward-command}). The variable @code{shell-command-regexp} -specifies how to recognize the end of a command. - -@item C-c C-b -@kindex C-c C-b @r{(Shell mode)} -@findex shell-backward-command -Move backward across one shell command, but not beyond the current line -(@code{shell-backward-command}). - -@item M-x dirs -Ask the shell for its working directory, and update the Shell buffer's -default directory. @xref{Directory Tracking}. - -@item M-x send-invisible @key{RET} @var{text} @key{RET} -@findex send-invisible -Send @var{text} as input to the shell, after reading it without -echoing. This is useful when a shell command runs a program that asks -for a password. - -Please note that Emacs will not echo passwords by default. If you -really want them to be echoed, evaluate the following Lisp -expression: - -@example -(remove-hook 'comint-output-filter-functions - 'comint-watch-for-password-prompt) -@end example - -@item M-x comint-continue-subjob -@findex comint-continue-subjob -Continue the shell process. This is useful if you accidentally suspend -the shell process.@footnote{You should not suspend the shell process. -Suspending a subjob of the shell is a completely different matter---that -is normal practice, but you must use the shell to continue the subjob; -this command won't do it.} - -@item M-x comint-strip-ctrl-m -@findex comint-strip-ctrl-m -Discard all control-M characters from the current group of shell output. -The most convenient way to use this command is to make it run -automatically when you get output from the subshell. To do that, -evaluate this Lisp expression: - -@example -(add-hook 'comint-output-filter-functions - 'comint-strip-ctrl-m) -@end example - -@item M-x comint-truncate-buffer -@findex comint-truncate-buffer -This command truncates the shell buffer to a certain maximum number of -lines, specified by the variable @code{comint-buffer-maximum-size}. -Here's how to do this automatically each time you get output from the -subshell: - -@example -(add-hook 'comint-output-filter-functions - 'comint-truncate-buffer) -@end example -@end table - -@cindex Comint mode -@cindex mode, Comint - Shell mode is a derivative of Comint mode, a general-purpose mode for -communicating with interactive subprocesses. Most of the features of -Shell mode actually come from Comint mode, as you can see from the -command names listed above. The special features of Shell mode include -the directory tracking feature, and a few user commands. - - Other Emacs features that use variants of Comint mode include GUD -(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}). - -@findex comint-run - You can use @kbd{M-x comint-run} to execute any program of your choice -in a subprocess using unmodified Comint mode---without the -specializations of Shell mode. - -@node Shell Prompts -@subsection Shell Prompts - -@cindex prompt, shell - A prompt is text output by a program to show that it is ready to -accept new user input. Normally, Comint mode (and thus Shell mode) -automatically figures out part of the buffer is a prompt, based on the -output of the subprocess. (Specifically, it assumes that any received -output line which doesn't end with a newline is a prompt.) - - Comint mode divides the buffer into two types of @dfn{fields}: input -fields (where user input is typed) and output fields (everywhere -else). Prompts are part of the output fields. Most Emacs motion -commands do not cross field boundaries, unless they move over multiple -lines. For instance, when point is in the input field on a shell -command line, @kbd{C-a} puts point at the beginning of the input -field, after the prompt. Internally, the fields are implemented using -the @code{field} text property (@pxref{Text Properties,,, elisp, the -Emacs Lisp Reference Manual}). - -@vindex comint-use-prompt-regexp -@vindex shell-prompt-pattern - If you change the variable @code{comint-use-prompt-regexp} to a -non-@code{nil} value, then Comint mode recognize prompts using a -regular expression (@pxref{Regexps}). In Shell mode, the regular -expression is specified by the variable @code{shell-prompt-pattern}. -The default value of @code{comint-use-prompt-regexp} is @code{nil}, -because this method for recognizing prompts is unreliable, but you may -want to set it to a non-@code{nil} value in unusual circumstances. In -that case, Emacs does not divide the Comint buffer into fields, so the -general motion commands behave as they normally do in buffers without -special text properties. However, you can use the paragraph motion -commands to conveniently navigate the buffer (@pxref{Paragraphs}); in -Shell mode, Emacs uses @code{shell-prompt-pattern} as paragraph -boundaries. - -@node Shell History -@subsection Shell Command History - - Shell buffers support three ways of repeating earlier commands. You -can use keys like those used for the minibuffer history; these work -much as they do in the minibuffer, inserting text from prior commands -while point remains always at the end of the buffer. You can move -through the buffer to previous inputs in their original place, then -resubmit them or copy them to the end. Or you can use a -@samp{!}-style history reference. - -@menu -* Ring: Shell Ring. Fetching commands from the history list. -* Copy: Shell History Copying. Moving to a command and then copying it. -* History References:: Expanding @samp{!}-style history references. -@end menu - -@node Shell Ring -@subsubsection Shell History Ring - -@table @kbd -@findex comint-previous-input -@kindex M-p @r{(Shell mode)} -@item M-p -@itemx C-@key{UP} -Fetch the next earlier old shell command. - -@kindex M-n @r{(Shell mode)} -@findex comint-next-input -@item M-n -@itemx C-@key{DOWN} -Fetch the next later old shell command. - -@kindex M-r @r{(Shell mode)} -@findex comint-history-isearch-backward-regexp -@item M-r -Begin an incremental regexp search of old shell commands. - -@item C-c C-x -@kindex C-c C-x @r{(Shell mode)} -@findex comint-get-next-from-history -Fetch the next subsequent command from the history. - -@item C-c . -@kindex C-c . @r{(Shell mode)} -@findex comint-input-previous-argument -Fetch one argument from an old shell command. - -@item C-c C-l -@kindex C-c C-l @r{(Shell mode)} -@findex comint-dynamic-list-input-ring -Display the buffer's history of shell commands in another window -(@code{comint-dynamic-list-input-ring}). -@end table - - Shell buffers provide a history of previously entered shell -commands. To reuse shell commands from the history, use the editing -commands @kbd{M-p}, @kbd{M-n}, @kbd{M-r} and @kbd{M-s}. These work -just like the minibuffer history commands (@pxref{Minibuffer -History}), except that they operate within the Shell buffer rather -than the minibuffer. - - @kbd{M-p} fetches an earlier shell command to the end of the shell -buffer. Successive use of @kbd{M-p} fetches successively earlier -shell commands, each replacing any text that was already present as -potential shell input. @kbd{M-n} does likewise except that it finds -successively more recent shell commands from the buffer. -@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like -@kbd{M-n}. - - The history search command @kbd{M-r} begins an incremental regular -expression search of previous shell commands. After typing @kbd{M-r}, -start typing the desired string or regular expression; the last -matching shell command will be displayed in the current line. -Incremental search commands have their usual effects---for instance, -@kbd{C-s} and @kbd{C-r} search forward and backward for the next match -(@pxref{Incremental Search}). When you find the desired input, type -@key{RET} to terminate the search. This puts the input in the command -line. Any partial input you were composing before navigating the -history list is restored when you go to the beginning or end of the -history ring. - - Often it is useful to reexecute several successive shell commands that -were previously executed in sequence. To do this, first find and -reexecute the first command of the sequence. Then type @kbd{C-c C-x}; -that will fetch the following command---the one that follows the command -you just repeated. Then type @key{RET} to reexecute this command. You -can reexecute several successive commands by typing @kbd{C-c C-x -@key{RET}} over and over. - - The command @kbd{C-c .}@: (@code{comint-input-previous-argument}) -copies an individual argument from a previous command, like @kbd{ESC -.} in Bash. The simplest use copies the last argument from the -previous shell command. With a prefix argument @var{n}, it copies the -@var{n}th argument instead. Repeating @kbd{C-c .} copies from an -earlier shell command instead, always using the same value of @var{n} -(don't give a prefix argument when you repeat the @kbd{C-c .} -command). - - These commands get the text of previous shell commands from a special -history list, not from the shell buffer itself. Thus, editing the shell -buffer, or even killing large parts of it, does not affect the history -that these commands access. - -@vindex shell-input-ring-file-name - Some shells store their command histories in files so that you can -refer to commands from previous shell sessions. Emacs reads -the command history file for your chosen shell, to initialize its own -command history. The file name is @file{~/.bash_history} for bash, -@file{~/.sh_history} for ksh, and @file{~/.history} for other shells. - -@node Shell History Copying -@subsubsection Shell History Copying - -@table @kbd -@kindex C-c C-p @r{(Shell mode)} -@findex comint-previous-prompt -@item C-c C-p -Move point to the previous prompt (@code{comint-previous-prompt}). - -@kindex C-c C-n @r{(Shell mode)} -@findex comint-next-prompt -@item C-c C-n -Move point to the following prompt (@code{comint-next-prompt}). - -@kindex C-c RET @r{(Shell mode)} -@findex comint-copy-old-input -@item C-c @key{RET} -Copy the input command at point, inserting the copy at the end of the -buffer (@code{comint-copy-old-input}). This is useful if you move -point back to a previous command. After you copy the command, you can -submit the copy as input with @key{RET}. If you wish, you can edit -the copy before resubmitting it. If you use this command on an output -line, it copies that line to the end of the buffer. - -@item Mouse-2 -If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy -the old input command that you click on, inserting the copy at the end -of the buffer (@code{comint-insert-input}). If -@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is -not over old input, just yank as usual. -@end table - - Moving to a previous input and then copying it with @kbd{C-c -@key{RET}} or @kbd{Mouse-2} produces the same results---the same -buffer contents---that you would get by using @kbd{M-p} enough times -to fetch that previous input from the history list. However, @kbd{C-c -@key{RET}} copies the text from the buffer, which can be different -from what is in the history list if you edit the input text in the -buffer after it has been sent. - -@node History References -@subsubsection Shell History References -@cindex history reference - - Various shells including csh and bash support @dfn{history -references} that begin with @samp{!} and @samp{^}. Shell mode -recognizes these constructs, and can perform the history substitution -for you. - - If you insert a history reference and type @key{TAB}, this searches -the input history for a matching command, performs substitution if -necessary, and places the result in the buffer in place of the history -reference. For example, you can fetch the most recent command -beginning with @samp{mv} with @kbd{! m v @key{TAB}}. You can edit the -command if you wish, and then resubmit the command to the shell by -typing @key{RET}. - -@vindex comint-input-autoexpand -@findex comint-magic-space - Shell mode can optionally expand history references in the buffer -when you send them to the shell. To request this, set the variable -@code{comint-input-autoexpand} to @code{input}. You can make -@key{SPC} perform history expansion by binding @key{SPC} to the -command @code{comint-magic-space}. - - Shell mode recognizes history references when they follow a prompt. -@xref{Shell Prompts}, for how Shell mode recognizes prompts. - -@node Directory Tracking -@subsection Directory Tracking -@cindex directory tracking - -@vindex shell-pushd-regexp -@vindex shell-popd-regexp -@vindex shell-cd-regexp - Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd} -commands given to the subshell, in order to keep the Shell buffer's -default directory (@pxref{File Names}) the same as the shell's working -directory. It recognizes these commands by examining lines of input -that you send. - - If you use aliases for these commands, you can tell Emacs to -recognize them also, by setting the variables -@code{shell-pushd-regexp}, @code{shell-popd-regexp}, and -@code{shell-cd-regexp} to the appropriate regular expressions -(@pxref{Regexps}). For example, if @code{shell-pushd-regexp} matches -the beginning of a shell command line, that line is regarded as a -@code{pushd} command. These commands are recognized only at the -beginning of a shell command line. - -@findex dirs - If Emacs gets confused about changes in the working directory of the -subshell, type @kbd{M-x dirs}. This command asks the shell for its -working directory and updates the default directory accordingly. It -works for shells that support the most common command syntax, but may -not work for unusual shells. - -@findex dirtrack-mode -@cindex Dirtrack mode -@cindex mode, Dirtrack -@vindex dirtrack-list - You can also use Dirtrack mode, a buffer-local minor mode that -implements an alternative method of tracking the shell's working -directory. To use this method, your shell prompt must contain the -working directory at all times, and you must supply a regular -expression for recognizing which part of the prompt contains the -working directory; see the documentation of the variable -@code{dirtrack-list} for details. To use Dirtrack mode, type @kbd{M-x -dirtrack-mode} in the Shell buffer, or add @code{dirtrack-mode} to -@code{shell-mode-hook} (@pxref{Hooks}). - -@node Shell Options -@subsection Shell Mode Options - -@vindex comint-scroll-to-bottom-on-input - If the variable @code{comint-scroll-to-bottom-on-input} is -non-@code{nil}, insertion and yank commands scroll the selected window -to the bottom before inserting. The default is @code{nil}. - -@vindex comint-scroll-show-maximum-output - If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then -arrival of output when point is at the end tries to scroll the last -line of text to the bottom line of the window, showing as much useful -text as possible. (This mimics the scrolling behavior of most -terminals.) The default is @code{t}. - -@vindex comint-move-point-for-output - By setting @code{comint-move-point-for-output}, you can opt for -having point jump to the end of the buffer whenever output arrives---no -matter where in the buffer point was before. If the value is -@code{this}, point jumps in the selected window. If the value is -@code{all}, point jumps in each window that shows the Comint buffer. If -the value is @code{other}, point jumps in all nonselected windows that -show the current buffer. The default value is @code{nil}, which means -point does not jump to the end. - -@vindex comint-prompt-read-only - If you set @code{comint-prompt-read-only}, the prompts in the Comint -buffer are read-only. - -@vindex comint-input-ignoredups - The variable @code{comint-input-ignoredups} controls whether successive -identical inputs are stored in the input history. A non-@code{nil} -value means to omit an input that is the same as the previous input. -The default is @code{nil}, which means to store each input even if it is -equal to the previous input. - -@vindex comint-completion-addsuffix -@vindex comint-completion-recexact -@vindex comint-completion-autolist - Three variables customize file name completion. The variable -@code{comint-completion-addsuffix} controls whether completion inserts a -space or a slash to indicate a fully completed file or directory name -(non-@code{nil} means do insert a space or slash). -@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB} -to choose the shortest possible completion if the usual Emacs completion -algorithm cannot add even a single character. -@code{comint-completion-autolist}, if non-@code{nil}, says to list all -the possible completions whenever completion is not exact. - -@vindex shell-completion-execonly - Command completion normally considers only executable files. -If you set @code{shell-completion-execonly} to @code{nil}, -it considers nonexecutable files as well. - -@findex shell-pushd-tohome -@findex shell-pushd-dextract -@findex shell-pushd-dunique - You can configure the behavior of @samp{pushd}. Variables control -whether @samp{pushd} behaves like @samp{cd} if no argument is given -(@code{shell-pushd-tohome}), pop rather than rotate with a numeric -argument (@code{shell-pushd-dextract}), and only add directories to the -directory stack if they are not already on it -(@code{shell-pushd-dunique}). The values you choose should match the -underlying shell, of course. - -@node Terminal emulator -@subsection Emacs Terminal Emulator -@findex term - - To run a subshell in a terminal emulator, use @kbd{M-x term}. This -creates (or reuses) a buffer named @file{*terminal*}, and runs a -subshell with input coming from your keyboard, and output going to -that buffer. - - The terminal emulator uses Term mode, which has two input modes. In -line mode, Term basically acts like Shell mode (@pxref{Shell Mode}). - - In char mode, each character is sent directly to the subshell, as -``terminal input''. Any ``echoing'' of your input is the -responsibility of the subshell. The sole exception is the terminal -escape character, which by default is @kbd{C-c} (@pxref{Term Mode}). -Any ``terminal output'' from the subshell goes into the buffer, -advancing point. - - Some programs (such as Emacs itself) need to control the appearance -on the terminal screen in detail. They do this by sending special -control codes. The exact control codes needed vary from terminal to -terminal, but nowadays most terminals and terminal emulators -(including @code{xterm}) understand the ANSI-standard (VT100-style) -escape sequences. Term mode recognizes these escape sequences, and -handles each one appropriately, changing the buffer so that the -appearance of the window matches what it would be on a real terminal. -You can actually run Emacs inside an Emacs Term window. - - You can also Term mode to communicate with a device connected to a -serial port. @xref{Serial Terminal}. - - The file name used to load the subshell is determined the same way -as for Shell mode. To make multiple terminal emulators, rename the -buffer @file{*terminal*} to something different using @kbd{M-x -rename-uniquely}, just as with Shell mode. - - Unlike Shell mode, Term mode does not track the current directory by -examining your input. But some shells can tell Term what the current -directory is. This is done automatically by @code{bash} version 1.15 -and later. - -@node Term Mode -@subsection Term Mode -@cindex Term mode -@cindex mode, Term - - The terminal emulator uses Term mode, which has two input modes. In -line mode, Term basically acts like Shell mode (@pxref{Shell Mode}). -In char mode, each character is sent directly to the subshell, except -for the Term escape character, normally @kbd{C-c}. - - To switch between line and char mode, use these commands: - -@table @kbd -@kindex C-c C-j @r{(Term mode)} -@findex term-line-mode -@item C-c C-j -Switch to line mode (@code{term-line-mode}). Do nothing if already in -line mode. - -@kindex C-c C-k @r{(Term mode)} -@findex term-char-mode -@item C-c C-k -Switch to char mode (@code{term-char-mode}). Do nothing if already in -char mode. -@end table - - The following commands are only available in char mode: - -@table @kbd -@item C-c C-c -Send a literal @key{C-c} to the sub-shell. - -@item C-c @var{char} -This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For -example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which -is normally @samp{other-window}. -@end table - -@cindex paging in Term mode - Term mode has a page-at-a-time feature. When enabled, it makes -output pause at the end of each screenful: - -@table @kbd -@kindex C-c C-q @r{(Term mode)} -@findex term-pager-toggle -@item C-c C-q -Toggle the page-at-a-time feature. This command works in both line -and char modes. When the feature is enabled, the mode-line displays -the word @samp{page}, and each time Term receives more than a -screenful of output, it pauses and displays @samp{**MORE**} in the -mode-line. Type @key{SPC} to display the next screenful of output, or -@kbd{?} to see your other options. The interface is similar to the -@code{more} program. -@end table - -@node Remote Host -@subsection Remote Host Shell -@cindex remote host -@cindex connecting to remote host -@cindex Telnet -@cindex Rlogin - - You can login to a remote computer, using whatever commands you -would from a regular terminal (e.g.@: using the @code{telnet} or -@code{rlogin} commands), from a Term window. - - A program that asks you for a password will normally suppress -echoing of the password, so the password will not show up in the -buffer. This will happen just as if you were using a real terminal, -if the buffer is in char mode. If it is in line mode, the password is -temporarily visible, but will be erased when you hit return. (This -happens automatically; there is no special password processing.) - - When you log in to a different machine, you need to specify the type -of terminal you're using, by setting the @env{TERM} environment -variable in the environment for the remote login command. (If you use -bash, you do that by writing the variable assignment before the remote -login command, without a separating comma.) Terminal types -@samp{ansi} or @samp{vt100} will work on most systems. - -@node Serial Terminal -@subsection Serial Terminal -@cindex terminal, serial -@findex serial-term - - If you have a device connected to a serial port of your computer, -you can communicate with it by typing @kbd{M-x serial-term}. This -command asks for a serial port name and speed, and switches to a new -Term mode buffer. Emacs communicates with the serial device through -this buffer just like it does with a terminal in ordinary Term mode. - - The speed of the serial port is measured in bits per second. The -most common speed is 9600 bits per second. You can change the speed -interactively by clicking on the mode line. - - A serial port can be configured even more by clicking on ``8N1'' in -the mode line. By default, a serial port is configured as ``8N1'', -which means that each byte consists of 8 data bits, No parity check -bit, and 1 stopbit. - - If the speed or the configuration is wrong, you cannot communicate -with your device and will probably only see garbage output in the -window. - -@node Emacs Server, Printing, Shell, Top -@section Using Emacs as a Server -@pindex emacsclient -@cindex Emacs as a server -@cindex server, using Emacs as -@cindex @env{EDITOR} environment variable - - Various programs can invoke your choice of editor to edit a -particular piece of text. For instance, version control programs -invoke an editor to enter version control logs (@pxref{Version -Control}), and the Unix @command{mail} utility invokes an editor to -enter a message to send. By convention, your choice of editor is -specified by the environment variable @env{EDITOR}. If you set -@env{EDITOR} to @samp{emacs}, Emacs would be invoked, but in an -inconvenient way---by starting a new Emacs process. This is -inconvenient because the new Emacs process doesn't share buffers, a -command history, or other kinds of information with any existing Emacs -process. - - You can solve this problem by setting up Emacs as an @dfn{edit -server}, so that it ``listens'' for external edit requests and acts -accordingly. There are two ways to start an Emacs server: - -@itemize -@findex server-start -@item -Run the command @code{server-start} in an existing Emacs process: -either type @kbd{M-x server-start}, or put the expression -@code{(server-start)} in your init file (@pxref{Init File}). The -existing Emacs process is the server; when you exit Emacs, the server -dies with the Emacs process. - -@cindex daemon, Emacs -@item -Run Emacs as a @dfn{daemon}, using the @samp{--daemon} command-line -option. @xref{Initial Options}. When Emacs is started this way, it -calls @code{server-start} after initialization, and returns control to -the calling terminal instead of opening an initial frame; it then -waits in the background, listening for edit requests. -@end itemize - -@cindex @env{TEXEDIT} environment variable - Either way, once an Emacs server is started, you can use a shell -command called @command{emacsclient} to connect to the Emacs process -and tell it to visit a file. You can then set the @env{EDITOR} -environment variable to @samp{emacsclient}, so that external programs -will use the existing Emacs process for editing.@footnote{Some -programs use a different environment variable; for example, to make -@TeX{} use @samp{emacsclient}, set the @env{TEXEDIT} environment -variable to @samp{emacsclient +%d %s}.} - -@vindex server-name - You can run multiple Emacs servers on the same machine by giving -each one a unique ``server name'', using the variable -@code{server-name}. For example, @kbd{M-x set-variable @key{RET} -server-name @key{RET} foo @key{RET}} sets the server name to -@samp{foo}. The @code{emacsclient} program can specify a server by -name, using the @samp{-s} option (@pxref{emacsclient Options}). - -@findex server-eval-at - If you have defined a server by a unique server name, it is possible -to connect to the server from another Emacs instance and evaluate Lisp -expressions on the server, using the @code{server-eval-at} function. -For instance, @code{(server-eval-at "foo" '(+ 1 2))} evaluates the -expression @code{(+ 1 2)} on the @samp{foo} server, and returns -@code{3}. (If there is no server with that name, an error is -signaled.) Currently, this feature is mainly useful for developers. - -@menu -* Invoking emacsclient:: Connecting to the Emacs server. -* emacsclient Options:: Emacs client startup options. -@end menu - -@node Invoking emacsclient -@subsection Invoking @code{emacsclient} -@cindex @code{emacsclient} invocation - - The simplest way to use the @command{emacsclient} program is to run -the shell command @samp{emacsclient @var{file}}, where @var{file} is a -file name. This connects to an Emacs server, and tells that Emacs -process to visit @var{file} in one of its existing frames---either a -graphical frame, or one in a text terminal (@pxref{Frames}). You -can then select that frame to begin editing. - - If there is no Emacs server, the @command{emacsclient} program halts -with an error message. If the Emacs process has no existing -frame---which can happen if it was started as a daemon (@pxref{Emacs -Server})---then Emacs opens a frame on the terminal in which you -called @command{emacsclient}. - - You can also force @command{emacsclient} to open a new frame on a -graphical display, or on a text terminal, using the @samp{-c} and -@samp{-t} options. @xref{emacsclient Options}. - - If you are running on a single text terminal, you can switch between -@command{emacsclient}'s shell and the Emacs server using one of two -methods: (i) run the Emacs server and @command{emacsclient} on -different virtual terminals, and switch to the Emacs server's virtual -terminal after calling @command{emacsclient}; or (ii) call -@command{emacsclient} from within the Emacs server itself, using Shell -mode (@pxref{Interactive Shell}) or Term mode (@pxref{Term Mode}); -@code{emacsclient} blocks only the subshell under Emacs, and you can -still use Emacs to edit the file. - -@kindex C-x # -@findex server-edit - When you finish editing @var{file} in the Emacs server, type -@kbd{C-x #} (@code{server-edit}) in its buffer. This saves the file -and sends a message back to the @command{emacsclient} program, telling -it to exit. Programs that use @env{EDITOR} usually wait for the -``editor''---in this case @command{emacsclient}---to exit before doing -something else. - - You can also call @command{emacsclient} with multiple file name -arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the -Emacs server to visit @var{file1}, @var{file2}, and so forth. Emacs -selects the buffer visiting @var{file1}, and buries the other buffers -at the bottom of the buffer list (@pxref{Buffers}). The -@command{emacsclient} program exits once all the specified files are -finished (i.e., once you have typed @kbd{C-x #} in each server -buffer). - -@vindex server-kill-new-buffers -@vindex server-temp-file-regexp - Finishing with a server buffer also kills the buffer, unless it -already existed in the Emacs session before the server was asked to -create it. However, if you set @code{server-kill-new-buffers} to -@code{nil}, then a different criterion is used: finishing with a -server buffer kills it if the file name matches the regular expression -@code{server-temp-file-regexp}. This is set up to distinguish certain -``temporary'' files. - - Each @kbd{C-x #} checks for other pending external requests to edit -various files, and selects the next such file. You can switch to a -server buffer manually if you wish; you don't have to arrive at it -with @kbd{C-x #}. But @kbd{C-x #} is the way to tell -@command{emacsclient} that you are finished. - -@vindex server-window - If you set the value of the variable @code{server-window} to a -window or a frame, @kbd{C-x #} always displays the next server buffer -in that window or in that frame. - -@node emacsclient Options -@subsection @code{emacsclient} Options -@cindex @code{emacsclient} options - - You can pass some optional arguments to the @command{emacsclient} -program, such as: - -@example -emacsclient -c +12 @var{file1} +4:3 @var{file2} -@end example - -@noindent -The @samp{+@var{line}} or @samp{+@var{line}:@var{column}} arguments -specify line numbers, or line and column numbers, for the next file -argument. These behave like the command line arguments for Emacs -itself. @xref{Action Arguments}. - - The other optional arguments recognized by @command{emacsclient} are -listed below: - -@table @samp -@item -a @var{command} -@itemx --alternate-editor=@var{command} -Specify a command to run if @code{emacsclient} fails to contact Emacs. -This is useful when running @code{emacsclient} in a script. - -As a special exception, if @var{command} is the empty string, then -@code{emacsclient} starts Emacs in daemon mode (as @command{emacs ---daemon}) and then tries connecting again. - -@cindex @env{ALTERNATE_EDITOR} environment variable -The environment variable @env{ALTERNATE_EDITOR} has the same effect as -the @samp{-a} option. If both are present, the latter takes -precedence. - -@cindex client frame -@item -c -Create a new graphical @dfn{client frame}, instead of using an -existing Emacs frame. If you omit a filename argument while supplying -the @samp{-c} option, the new frame displays the @file{*scratch*} -buffer (@pxref{Buffers}). See below for the special behavior of -@kbd{C-x C-c} in a client frame. - -If Emacs is unable to create a new graphical frame (e.g.@: if it is -unable to connect to the X server), it tries to create a text terminal -client frame, as though you had supplied the @samp{-t} option instead -(see below). - -On MS-Windows, a single Emacs session cannot display frames on both -graphical and text terminals, nor on multiple text terminals. Thus, -if the Emacs server is running on a text terminal, the @samp{-c} -option, like the @samp{-t} option, creates a new frame in the server's -current text terminal. @xref{Windows Startup}. - -@item -F @var{alist} -@itemx --frame-parameters=@var{alist} -Set the parameters for a newly-created graphical frame -(@pxref{Frame Parameters}). - -@item -d @var{display} -@itemx --display=@var{display} -Tell Emacs to open the given files on the X display @var{display} -(assuming there is more than one X display available). - -@item -e -@itemx --eval -Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some -files. When this option is given, the arguments to -@command{emacsclient} are interpreted as a list of expressions to -evaluate, @emph{not} as a list of files to visit. - -@item -f @var{server-file} -@itemx --server-file=@var{server-file} -@cindex @env{EMACS_SERVER_FILE} environment variable -@cindex server file -@vindex server-use-tcp -@vindex server-host -Specify a @dfn{server file} for connecting to an Emacs server via TCP. - -An Emacs server usually uses an operating system feature called a -``local socket'' to listen for connections. Some operating systems, -such as Microsoft Windows, do not support local sockets; in that case, -Emacs uses TCP instead. When you start the Emacs server, Emacs -creates a server file containing some TCP information that -@command{emacsclient} needs for making the connection. By default, -the server file is in @file{~/.emacs.d/server/}. On Microsoft -Windows, if @command{emacsclient} does not find the server file there, -it looks in the @file{.emacs.d/server/} subdirectory of the directory -pointed to by the @env{APPDATA} environment variable. You can tell -@command{emacsclient} to use a specific server file with the @samp{-f} -or @samp{--server-file} option, or by setting the -@env{EMACS_SERVER_FILE} environment variable. - -Even if local sockets are available, you can tell Emacs to use TCP by -setting the variable @code{server-use-tcp} to @code{t}. One advantage -of TCP is that the server can accept connections from remote machines. -For this to work, you must (i) set the variable @code{server-host} to -the hostname or IP address of the machine on which the Emacs server -runs, and (ii) provide @command{emacsclient} with the server file. -(One convenient way to do the latter is to put the server file on a -networked file system such as NFS.) - -@vindex server-port - When the Emacs server is using TCP, the variable @code{server-port} -determines the port number to listen on; the default value, -@code{nil}, means to choose a random port when the server starts. - -@item -n -@itemx --no-wait -Let @command{emacsclient} exit immediately, instead of waiting until -all server buffers are finished. You can take as long as you like to -edit the server buffers within Emacs, and they are @emph{not} killed -when you type @kbd{C-x #} in them. - -@item --parent-id @var{ID} -Open an @command{emacsclient} frame as a client frame in the parent X -window with id @var{ID}, via the XEmbed protocol. Currently, this -option is mainly useful for developers. - -@item -q -@itemx --quiet -Do not let @command{emacsclient} display messages about waiting for -Emacs or connecting to remote server sockets. - -@item -s @var{server-name} -@itemx --socket-name=@var{server-name} -Connect to the Emacs server named @var{server-name}. The server name -is given by the variable @code{server-name} on the Emacs server. If -this option is omitted, @command{emacsclient} connects to the first -server it finds. (This option is not supported on MS-Windows.) - -@item -t -@itemx --tty -@itemx -nw -Create a new client frame on the current text terminal, instead of -using an existing Emacs frame. This is similar to the @samp{-c} -option, above, except that it creates a text terminal frame -(@pxref{Non-Window Terminals}). If you omit a filename argument while -supplying this option, the new frame displays the @file{*scratch*} -buffer (@pxref{Buffers}). See below for the special behavior of -@kbd{C-x C-c} in a client frame. - -On MS-Windows, a single Emacs session cannot display frames on both -graphical and text terminals, nor on multiple text terminals. Thus, -if the Emacs server is using the graphical display, @samp{-t} behaves -like @samp{-c} (see above); whereas if the Emacs server is running on -a text terminal, it creates a new frame in its current text terminal. -@xref{Windows Startup}. -@end table - - The new graphical or text terminal frames created by the @samp{-c} -or @samp{-t} options are considered @dfn{client frames}. Any new -frame that you create from a client frame is also considered a client -frame. If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}) -in a client frame, that command does not kill the Emacs session as it -normally does (@pxref{Exiting}). Instead, Emacs deletes the client -frame; furthermore, if the client frame has an @command{emacsclient} -waiting to regain control (i.e.@: if you did not supply the @samp{-n} -option), Emacs deletes all other frames of the same client, and marks -the client's server buffers as finished, as though you had typed -@kbd{C-x #} in all of them. If it so happens that there are no -remaining frames after the client frame(s) are deleted, the Emacs -session exits. - - As an exception, when Emacs is started as a daemon, all frames are -considered client frames, and @kbd{C-x C-c} never kills Emacs. To -kill a daemon session, type @kbd{M-x kill-emacs}. - - Note that the @samp{-t} and @samp{-n} options are contradictory: -@samp{-t} says to take control of the current text terminal to create -a new client frame, while @samp{-n} says not to take control of the -text terminal. If you supply both options, Emacs visits the specified -files(s) in an existing frame rather than a new client frame, negating -the effect of @samp{-t}. - -@node Printing, Sorting, Emacs Server, Top -@section Printing Hard Copies -@cindex hardcopy -@cindex printing - - Emacs provides commands for printing hardcopies of either an entire -buffer or part of one. You can invoke the printing commands directly, -as detailed below, or using the @samp{File} menu on the menu bar. - -@findex htmlfontify-buffer - Aside from the commands described in this section, you can also -print hardcopies from Dired (@pxref{Operating on Files}) and the diary -(@pxref{Displaying the Diary}). You can also ``print'' an Emacs -buffer to HTML with the command @kbd{M-x htmlfontify-buffer}, which -converts the current buffer to a HTML file, replacing Emacs faces with -CSS-based markup. Furthermore, Org mode allows you to ``print'' Org -files to a variety of formats, such as PDF (@pxref{Org Mode}). - -@table @kbd -@item M-x print-buffer -Print hardcopy of current buffer with page headings containing the -file name and page number. -@item M-x lpr-buffer -Print hardcopy of current buffer without page headings. -@item M-x print-region -Like @code{print-buffer} but print only the current region. -@item M-x lpr-region -Like @code{lpr-buffer} but print only the current region. -@end table - -@findex print-buffer -@findex print-region -@findex lpr-buffer -@findex lpr-region -@vindex lpr-switches -@vindex lpr-commands - On most operating system, the above hardcopy commands submit files -for printing by calling the @command{lpr} program. To change the -printer program, customize the variable @code{lpr-command}. To -specify extra switches to give the printer program, customize the list -variable @code{lpr-switches}. Its value should be a list of option -strings, each of which should start with @samp{-} (e.g.@: the option -string @code{"-w80"} specifies a line width of 80 columns). The -default is the empty list, @code{nil}. - -@vindex printer-name -@vindex lpr-printer-switch - To specify the printer to use, set the variable @code{printer-name}. -The default, @code{nil}, specifies the default printer. If you set it -to a printer name (a string), that name is passed to @command{lpr} -with the @samp{-P} switch; if you are not using @command{lpr}, you -should specify the switch with @code{lpr-printer-switch}. - -@vindex lpr-headers-switches -@vindex lpr-add-switches - The variable @code{lpr-headers-switches} similarly specifies the -extra switches to use to make page headers. The variable -@code{lpr-add-switches} controls whether to supply @samp{-T} and -@samp{-J} options (suitable for @command{lpr}) to the printer program: -@code{nil} means don't add them (this should be the value if your -printer program is not compatible with @command{lpr}). - -@menu -* PostScript:: Printing buffers or regions as PostScript. -* PostScript Variables:: Customizing the PostScript printing commands. -* Printing Package:: An optional advanced printing interface. -@end menu - -@node PostScript, PostScript Variables,, Printing -@subsection PostScript Hardcopy - - These commands convert buffer contents to PostScript, -either printing it or leaving it in another Emacs buffer. - -@table @kbd -@item M-x ps-print-buffer -Print hardcopy of the current buffer in PostScript form. -@item M-x ps-print-region -Print hardcopy of the current region in PostScript form. -@item M-x ps-print-buffer-with-faces -Print hardcopy of the current buffer in PostScript form, showing the -faces used in the text by means of PostScript features. -@item M-x ps-print-region-with-faces -Print hardcopy of the current region in PostScript form, showing the -faces used in the text. -@item M-x ps-spool-buffer -Generate and spool a PostScript image for the current buffer text. -@item M-x ps-spool-region -Generate and spool a PostScript image for the current region. -@item M-x ps-spool-buffer-with-faces -Generate and spool a PostScript image for the current buffer, showing the faces used. -@item M-x ps-spool-region-with-faces -Generate and spool a PostScript image for the current region, showing the faces used. -@item M-x ps-despool -Send the spooled PostScript to the printer. -@item M-x handwrite -Generate/print PostScript for the current buffer as if handwritten. -@end table - -@findex ps-print-region -@findex ps-print-buffer -@findex ps-print-region-with-faces -@findex ps-print-buffer-with-faces - The @code{ps-print-buffer} and @code{ps-print-region} commands print -buffer contents in PostScript form. One command prints the entire -buffer; the other, just the region. The commands -@code{ps-print-buffer-with-faces} and -@code{ps-print-region-with-faces} behave similarly, but use PostScript -features to show the faces (fonts and colors) of the buffer text. - - Interactively, when you use a prefix argument (@kbd{C-u}), the command -prompts the user for a file name, and saves the PostScript image in that file -instead of sending it to the printer. - -@findex ps-spool-region -@findex ps-spool-buffer -@findex ps-spool-region-with-faces -@findex ps-spool-buffer-with-faces - The commands whose names have @samp{spool} instead of @samp{print}, -generate the PostScript output in an Emacs buffer instead of sending -it to the printer. - -@findex ps-despool - Use the command @code{ps-despool} to send the spooled images to the -printer. This command sends the PostScript generated by -@samp{-spool-} commands (see commands above) to the printer. With a -prefix argument (@kbd{C-u}), it prompts for a file name, and saves the -spooled PostScript image in that file instead of sending it to the -printer. - -@findex handwrite -@cindex handwriting - @kbd{M-x handwrite} is more frivolous. It generates a PostScript -rendition of the current buffer as a cursive handwritten document. It -can be customized in group @code{handwrite}. This function only -supports ISO 8859-1 characters. - -@node PostScript Variables, Printing Package, PostScript, Printing -@subsection Variables for PostScript Hardcopy - -@vindex ps-lpr-command -@vindex ps-lpr-switches -@vindex ps-printer-name - All the PostScript hardcopy commands use the variables -@code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print -the output. @code{ps-lpr-command} specifies the command name to run, -@code{ps-lpr-switches} specifies command line options to use, and -@code{ps-printer-name} specifies the printer. If you don't set the -first two variables yourself, they take their initial values from -@code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name} -is @code{nil}, @code{printer-name} is used. - -@vindex ps-print-header - The variable @code{ps-print-header} controls whether these commands -add header lines to each page---set it to @code{nil} to turn headers -off. - -@cindex color emulation on black-and-white printers -@vindex ps-print-color-p - If your printer doesn't support colors, you should turn off color -processing by setting @code{ps-print-color-p} to @code{nil}. By -default, if the display supports colors, Emacs produces hardcopy output -with color information; on black-and-white printers, colors are emulated -with shades of gray. This might produce illegible output, even if your -screen colors only use shades of gray. - - Alternatively, you can set @code{ps-print-color-p} to @code{black-white} to -print colors on black/white printers. - -@vindex ps-use-face-background - By default, PostScript printing ignores the background colors of the -faces, unless the variable @code{ps-use-face-background} is -non-@code{nil}. This is to avoid unwanted interference with the zebra -stripes and background image/text. - -@vindex ps-paper-type -@vindex ps-page-dimensions-database - The variable @code{ps-paper-type} specifies which size of paper to -format for; legitimate values include @code{a4}, @code{a3}, -@code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger}, -@code{legal}, @code{letter}, @code{letter-small}, @code{statement}, -@code{tabloid}. The default is @code{letter}. You can define -additional paper sizes by changing the variable -@code{ps-page-dimensions-database}. - -@vindex ps-landscape-mode - The variable @code{ps-landscape-mode} specifies the orientation of -printing on the page. The default is @code{nil}, which stands for -``portrait'' mode. Any non-@code{nil} value specifies ``landscape'' -mode. - -@vindex ps-number-of-columns - The variable @code{ps-number-of-columns} specifies the number of -columns; it takes effect in both landscape and portrait mode. The -default is 1. - -@vindex ps-font-family -@vindex ps-font-size -@vindex ps-font-info-database - The variable @code{ps-font-family} specifies which font family to use -for printing ordinary text. Legitimate values include @code{Courier}, -@code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and -@code{Times}. The variable @code{ps-font-size} specifies the size of -the font for ordinary text. It defaults to 8.5 points. - -@vindex ps-multibyte-buffer -@cindex Intlfonts for PostScript printing -@cindex fonts for PostScript printing - Emacs supports more scripts and characters than a typical PostScript -printer. Thus, some of the characters in your buffer might not be -printable using the fonts built into your printer. You can augment -the fonts supplied with the printer with those from the GNU Intlfonts -package, or you can instruct Emacs to use Intlfonts exclusively. The -variable @code{ps-multibyte-buffer} controls this: the default value, -@code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1 -characters; a value of @code{non-latin-printer} is for printers which -have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean -characters built into them. A value of @code{bdf-font} arranges for -the BDF fonts from the Intlfonts package to be used for @emph{all} -characters. Finally, a value of @code{bdf-font-except-latin} -instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1 -characters, and Intlfonts BDF fonts for the rest. - -@vindex bdf-directory-list - To be able to use the BDF fonts, Emacs needs to know where to find -them. The variable @code{bdf-directory-list} holds the list of -directories where Emacs should look for the fonts; the default value -includes a single directory @file{/usr/local/share/emacs/fonts/bdf}. - - Many other customization variables for these commands are defined and -described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}. - -@node Printing Package,, PostScript Variables, Printing -@subsection Printing Package -@cindex Printing package - - The basic Emacs facilities for printing hardcopy can be extended -using the Printing package. This provides an easy-to-use interface -for choosing what to print, previewing PostScript files before -printing, and setting various printing options such as print headers, -landscape or portrait modes, duplex modes, and so forth. On GNU/Linux -or Unix systems, the Printing package relies on the @file{gs} and -@file{gv} utilities, which are distributed as part of the GhostScript -program. On MS-Windows, the @file{gstools} port of Ghostscript can be -used. - -@findex pr-interface - To use the Printing package, add @code{(require 'printing)} to your -init file (@pxref{Init File}), followed by @code{(pr-update-menus)}. -This function replaces the usual printing commands in the menu bar -with a @samp{Printing} submenu that contains various printing options. -You can also type @kbd{M-x pr-interface RET}; this creates a -@file{*Printing Interface*} buffer, similar to a customization buffer, -where you can set the printing options. After selecting what and how -to print, you start the print job using the @samp{Print} button (click -@kbd{mouse-2} on it, or move point over it and type @kbd{RET}). For -further information on the various options, use the @samp{Interface -Help} button. - -@node Sorting -@section Sorting Text -@cindex sorting - - Emacs provides several commands for sorting text in the buffer. All -operate on the contents of the region. -They divide the text of the region into many @dfn{sort records}, -identify a @dfn{sort key} for each record, and then reorder the records -into the order determined by the sort keys. The records are ordered so -that their keys are in alphabetical order, or, for numeric sorting, in -numeric order. In alphabetic sorting, all upper-case letters `A' through -`Z' come before lower-case `a', in accord with the @acronym{ASCII} character -sequence. - - The various sort commands differ in how they divide the text into sort -records and in which part of each record is used as the sort key. Most of -the commands make each line a separate sort record, but some commands use -paragraphs or pages as sort records. Most of the sort commands use each -entire sort record as its own sort key, but some use only a portion of the -record as the sort key. - -@findex sort-lines -@findex sort-paragraphs -@findex sort-pages -@findex sort-fields -@findex sort-numeric-fields -@vindex sort-numeric-base -@table @kbd -@item M-x sort-lines -Divide the region into lines, and sort by comparing the entire -text of a line. A numeric argument means sort into descending order. - -@item M-x sort-paragraphs -Divide the region into paragraphs, and sort by comparing the entire -text of a paragraph (except for leading blank lines). A numeric -argument means sort into descending order. - -@item M-x sort-pages -Divide the region into pages, and sort by comparing the entire -text of a page (except for leading blank lines). A numeric -argument means sort into descending order. - -@item M-x sort-fields -Divide the region into lines, and sort by comparing the contents of -one field in each line. Fields are defined as separated by -whitespace, so the first run of consecutive non-whitespace characters -in a line constitutes field 1, the second such run constitutes field -2, etc. - -Specify which field to sort by with a numeric argument: 1 to sort by -field 1, etc. A negative argument means count fields from the right -instead of from the left; thus, minus 1 means sort by the last field. -If several lines have identical contents in the field being sorted, they -keep the same relative order that they had in the original buffer. - -@item M-x sort-numeric-fields -Like @kbd{M-x sort-fields} except the specified field is converted -to an integer for each line, and the numbers are compared. @samp{10} -comes before @samp{2} when considered as text, but after it when -considered as a number. By default, numbers are interpreted according -to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or -@samp{0} are interpreted as hexadecimal and octal, respectively. - -@item M-x sort-columns -Like @kbd{M-x sort-fields} except that the text within each line -used for comparison comes from a fixed range of columns. See below -for an explanation. - -@item M-x reverse-region -Reverse the order of the lines in the region. This is useful for -sorting into descending order by fields or columns, since those sort -commands do not have a feature for doing that. -@end table - - For example, if the buffer contains this: - -@smallexample -On systems where clash detection (locking of files being edited) is -implemented, Emacs also checks the first time you modify a buffer -whether the file has changed on disk since it was last visited or -saved. If it has, you are asked to confirm that you want to change -the buffer. -@end smallexample - -@noindent -applying @kbd{M-x sort-lines} to the entire buffer produces this: - -@smallexample -On systems where clash detection (locking of files being edited) is -implemented, Emacs also checks the first time you modify a buffer -saved. If it has, you are asked to confirm that you want to change -the buffer. -whether the file has changed on disk since it was last visited or -@end smallexample - -@noindent -where the upper-case @samp{O} sorts before all lower-case letters. If -you use @kbd{C-u 2 M-x sort-fields} instead, you get this: - -@smallexample -implemented, Emacs also checks the first time you modify a buffer -saved. If it has, you are asked to confirm that you want to change -the buffer. -On systems where clash detection (locking of files being edited) is -whether the file has changed on disk since it was last visited or -@end smallexample - -@noindent -where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer}, -@samp{systems} and @samp{the}. - -@findex sort-columns - @kbd{M-x sort-columns} requires more explanation. You specify the -columns by putting point at one of the columns and the mark at the other -column. Because this means you cannot put point or the mark at the -beginning of the first line of the text you want to sort, this command -uses an unusual definition of ``region'': all of the line point is in is -considered part of the region, and so is all of the line the mark is in, -as well as all the lines in between. - - For example, to sort a table by information found in columns 10 to 15, -you could put the mark on column 10 in the first line of the table, and -point on column 15 in the last line of the table, and then run -@code{sort-columns}. Equivalently, you could run it with the mark on -column 15 in the first line and point on column 10 in the last line. - - This can be thought of as sorting the rectangle specified by point and -the mark, except that the text on each line to the left or right of the -rectangle moves along with the text inside the rectangle. -@xref{Rectangles}. - -@vindex sort-fold-case - Many of the sort commands ignore case differences when comparing, if -@code{sort-fold-case} is non-@code{nil}. - -@c Picture Mode documentation -@ifnottex -@include picture-xtra.texi -@end ifnottex - - -@node Editing Binary Files -@section Editing Binary Files - -@cindex Hexl mode -@cindex mode, Hexl -@cindex editing binary files -@cindex hex editing - There is a special major mode for editing binary files: Hexl mode. To -use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit -the file. This command converts the file's contents to hexadecimal and -lets you edit the translation. When you save the file, it is converted -automatically back to binary. - - You can also use @kbd{M-x hexl-mode} to translate an existing buffer -into hex. This is useful if you visit a file normally and then discover -it is a binary file. - - Ordinary text characters overwrite in Hexl mode. This is to reduce -the risk of accidentally spoiling the alignment of data in the file. -There are special commands for insertion. Here is a list of the -commands of Hexl mode: - -@c I don't think individual index entries for these commands are useful--RMS. -@table @kbd -@item C-M-d -Insert a byte with a code typed in decimal. - -@item C-M-o -Insert a byte with a code typed in octal. - -@item C-M-x -Insert a byte with a code typed in hex. - -@item C-x [ -Move to the beginning of a 1k-byte ``page''. - -@item C-x ] -Move to the end of a 1k-byte ``page''. - -@item M-g -Move to an address specified in hex. - -@item M-j -Move to an address specified in decimal. - -@item C-c C-c -Leave Hexl mode, going back to the major mode this buffer had before you -invoked @code{hexl-mode}. -@end table - -@noindent -Other Hexl commands let you insert strings (sequences) of binary -bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a -hexl-@key{RET}} for details. - - -@node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top -@section Saving Emacs Sessions -@cindex saving sessions -@cindex restore session -@cindex remember editing session -@cindex reload files -@cindex desktop - - Use the desktop library to save the state of Emacs from one session -to another. Once you save the Emacs @dfn{desktop}---the buffers, -their file names, major modes, buffer positions, and so on---then -subsequent Emacs sessions reload the saved desktop. - -@findex desktop-save -@vindex desktop-save-mode - You can save the desktop manually with the command @kbd{M-x -desktop-save}. You can also enable automatic saving of the desktop -when you exit Emacs, and automatic restoration of the last saved -desktop when Emacs starts: use the Customization buffer (@pxref{Easy -Customization}) to set @code{desktop-save-mode} to @code{t} for future -sessions, or add this line in your init file (@pxref{Init File}): - -@example -(desktop-save-mode 1) -@end example - -@findex desktop-change-dir -@findex desktop-revert -@vindex desktop-path - If you turn on @code{desktop-save-mode} in your init file, then when -Emacs starts, it looks for a saved desktop in the current directory. -(More precisely, it looks in the directories specified by -@var{desktop-path}, and uses the first desktop it finds.) -Thus, you can have separate saved desktops in different directories, -and the starting directory determines which one Emacs reloads. You -can save the current desktop and reload one saved in another directory -by typing @kbd{M-x desktop-change-dir}. Typing @kbd{M-x -desktop-revert} reverts to the desktop previously reloaded. - - Specify the option @samp{--no-desktop} on the command line when you -don't want it to reload any saved desktop. This turns off -@code{desktop-save-mode} for the current session. Starting Emacs with -the @samp{--no-init-file} option also disables desktop reloading, -since it bypasses the init file, where @code{desktop-save-mode} is -usually turned on. - -@vindex desktop-restore-eager - By default, all the buffers in the desktop are restored at one go. -However, this may be slow if there are a lot of buffers in the -desktop. You can specify the maximum number of buffers to restore -immediately with the variable @code{desktop-restore-eager}; the -remaining buffers are restored ``lazily'', when Emacs is idle. - -@findex desktop-clear -@vindex desktop-globals-to-clear -@vindex desktop-clear-preserve-buffers-regexp - Type @kbd{M-x desktop-clear} to empty the Emacs desktop. This kills -all buffers except for internal ones, and clears the global variables -listed in @code{desktop-globals-to-clear}. If you want this to -preserve certain buffers, customize the variable -@code{desktop-clear-preserve-buffers-regexp}, whose value is a regular -expression matching the names of buffers not to kill. - - If you want to save minibuffer history from one session to -another, use the @code{savehist} library. - -@node Recursive Edit, Emulation, Saving Emacs Sessions, Top -@section Recursive Editing Levels -@cindex recursive editing level -@cindex editing level, recursive - - A @dfn{recursive edit} is a situation in which you are using Emacs -commands to perform arbitrary editing while in the middle of another -Emacs command. For example, when you type @kbd{C-r} inside of a -@code{query-replace}, you enter a recursive edit in which you can change -the current buffer. On exiting from the recursive edit, you go back to -the @code{query-replace}. - -@kindex C-M-c -@findex exit-recursive-edit -@cindex exiting recursive edit - @dfn{Exiting} the recursive edit means returning to the unfinished -command, which continues execution. The command to exit is @kbd{C-M-c} -(@code{exit-recursive-edit}). - - You can also @dfn{abort} the recursive edit. This is like exiting, -but also quits the unfinished command immediately. Use the command -@kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}. - - The mode line shows you when you are in a recursive edit by displaying -square brackets around the parentheses that always surround the major and -minor mode names. Every window's mode line shows this in the same way, -since being in a recursive edit is true of Emacs as a whole rather than -any particular window or buffer. - - It is possible to be in recursive edits within recursive edits. For -example, after typing @kbd{C-r} in a @code{query-replace}, you may type a -command that enters the debugger. This begins a recursive editing level -for the debugger, within the recursive editing level for @kbd{C-r}. -Mode lines display a pair of square brackets for each recursive editing -level currently in progress. - - Exiting the inner recursive edit (such as with the debugger @kbd{c} -command) resumes the command running in the next level up. When that -command finishes, you can then use @kbd{C-M-c} to exit another recursive -editing level, and so on. Exiting applies to the innermost level only. -Aborting also gets out of only one level of recursive edit; it returns -immediately to the command level of the previous recursive edit. If you -wish, you can then abort the next recursive editing level. - - Alternatively, the command @kbd{M-x top-level} aborts all levels of -recursive edits, returning immediately to the top-level command -reader. It also exits the minibuffer, if it is active. - - The text being edited inside the recursive edit need not be the same text -that you were editing at top level. It depends on what the recursive edit -is for. If the command that invokes the recursive edit selects a different -buffer first, that is the buffer you will edit recursively. In any case, -you can switch buffers within the recursive edit in the normal manner (as -long as the buffer-switching keys have not been rebound). You could -probably do all the rest of your editing inside the recursive edit, -visiting files and all. But this could have surprising effects (such as -stack overflow) from time to time. So remember to exit or abort the -recursive edit when you no longer need it. - - In general, we try to minimize the use of recursive editing levels in -GNU Emacs. This is because they constrain you to ``go back'' in a -particular order---from the innermost level toward the top level. When -possible, we present different activities in separate buffers so that -you can switch between them as you please. Some commands switch to a -new major mode which provides a command to switch back. These -approaches give you more flexibility to go back to unfinished tasks in -the order you choose. - -@node Emulation, Hyperlinking, Recursive Edit, Top -@section Emulation -@cindex emulating other editors -@cindex other editors -@cindex EDT -@cindex vi -@cindex PC key bindings -@cindex scrolling all windows -@cindex PC selection -@cindex Motif key bindings -@cindex Macintosh key bindings -@cindex WordStar - - GNU Emacs can be programmed to emulate (more or less) most other -editors. Standard facilities can emulate these: - -@table @asis -@item CRiSP/Brief (PC editor) -@findex crisp-mode -@vindex crisp-override-meta-x -@findex scroll-all-mode -@cindex CRiSP mode -@cindex Brief emulation -@cindex emulation of Brief -@cindex mode, CRiSP -You can turn on key bindings to emulate the CRiSP/Brief editor with -@kbd{M-x crisp-mode}. Note that this rebinds @kbd{M-x} to exit Emacs -unless you set the variable @code{crisp-override-meta-x}. You can -also use the command @kbd{M-x scroll-all-mode} or set the variable -@code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature -(scrolling all windows together). - -@item EDT (DEC VMS editor) -@findex edt-emulation-on -@findex edt-emulation-off -Turn on EDT emulation @kbd{M-x edt-emulation-on}; use @kbd{M-x -edt-emulation-off} to restore normal Emacs command bindings. - -Most of the EDT emulation commands are keypad keys, and most standard -Emacs key bindings are still available. The EDT emulation rebindings -are done in the global keymap, so there is no problem switching -buffers or major modes while in EDT emulation. - -@item TPU (DEC VMS editor) -@findex tpu-edt-on -@cindex TPU -@kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT. - -@item vi (Berkeley editor) -@findex viper-mode -Viper is the newest emulator for vi. It implements several levels of -emulation; level 1 is closest to vi itself, while level 5 departs -somewhat from strict emulation to take advantage of the capabilities of -Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you -the rest of the way and ask for the emulation level. @inforef{Top, -Viper, viper}. - -@item vi (another emulator) -@findex vi-mode -@kbd{M-x vi-mode} enters a major mode that replaces the previously -established major mode. All of the vi commands that, in real vi, enter -``input'' mode are programmed instead to return to the previous major -mode. Thus, ordinary Emacs serves as vi's ``input'' mode. - -Because vi emulation works through major modes, it does not work -to switch buffers during emulation. Return to normal Emacs first. - -If you plan to use vi emulation much, you probably want to bind a key -to the @code{vi-mode} command. - -@item vi (alternate emulator) -@findex vip-mode -@kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi -more thoroughly than @kbd{M-x vi-mode}. ``Input'' mode in this emulator -is changed from ordinary Emacs so you can use @key{ESC} to go back to -emulated vi command mode. To get from emulated vi command mode back to -ordinary Emacs, type @kbd{C-z}. - -This emulation does not work through major modes, and it is possible -to switch buffers in various ways within the emulator. It is not -so necessary to assign a key to the command @code{vip-mode} as -it is with @code{vi-mode} because terminating insert mode does -not use it. - -@inforef{Top, VIP, vip}, for full information. - -@item WordStar (old wordprocessor) -@findex wordstar-mode -@kbd{M-x wordstar-mode} provides a major mode with WordStar-like -key bindings. -@end table - -@node Hyperlinking, Amusements, Emulation, Top -@section Hyperlinking and Navigation Features - - The following subsections describe convenience features for handling -URLs and other types of links occurring in Emacs buffer text. - -@menu -* Browse-URL:: Following URLs. -* Goto Address mode:: Activating URLs. -* FFAP:: Finding files etc. at point. -@end menu - -@node Browse-URL -@subsection Following URLs -@cindex World Wide Web -@cindex Web -@findex browse-url -@findex browse-url-at-point -@findex browse-url-at-mouse -@cindex Browse-URL -@cindex URLs - -@table @kbd -@item M-x browse-url @key{RET} @var{url} @key{RET} -Load a URL into a Web browser. -@end table - - The Browse-URL package allows you to easily follow URLs from within -Emacs. Most URLs are followed by invoking a web browser; -@samp{mailto:} URLs are followed by invoking the @code{compose-mail} -Emacs command to send mail to the specified address (@pxref{Sending -Mail}). - - The command @kbd{M-x browse-url} prompts for a URL, and follows it. -If point is located near a plausible URL, that URL is offered as the -default. The Browse-URL package also provides other commands which -you might like to bind to keys, such as @code{browse-url-at-point} and -@code{browse-url-at-mouse}. - -@vindex browse-url-mailto-function -@vindex browse-url-browser-function - You can customize Browse-URL's behavior via various options in the -@code{browse-url} Customize group. In particular, the option -@code{browse-url-mailto-function} lets you define how to follow -@samp{mailto:} URLs, while @code{browse-url-browser-function} lets you -define how to follow other types of URLs. For more information, view -the package commentary by typing @kbd{C-h P browse-url @key{RET}}. - -@node Goto Address mode -@subsection Activating URLs -@findex goto-address-mode -@cindex mode, Goto Address -@cindex Goto Address mode -@cindex URLs, activating - -@table @kbd -@item M-x goto-address-mode -Activate URLs and e-mail addresses in the current buffer. -@end table - -@kindex C-c RET @r{(Goto Address mode)} -@findex goto-address-at-point - You can make Emacs mark out URLs specially in the current buffer, by -typing @kbd{M-x goto-address-mode}. When this buffer-local minor mode -is enabled, it finds all the URLs in the buffer, highlights them, and -turns them into clickable buttons. You can follow the URL by typing -@kbd{C-c @key{RET}} (@code{goto-address-at-point}) while point is on -its text; or by clicking with @kbd{Mouse-2}, or by clicking -@kbd{Mouse-1} quickly (@pxref{Mouse References}). Following a URL is -done by calling @code{browse-url} as a subroutine -(@pxref{Browse-URL}). - - It can be useful to add @code{goto-address-mode} to mode hooks and -hooks for displaying an incoming message -(e.g.@: @code{rmail-show-message-hook} for Rmail, and -@code{mh-show-mode-hook} for MH-E). This is not needed for Gnus, -which has a similar feature of its own. - -@node FFAP -@subsection Finding Files and URLs at Point -@findex find-file-at-point -@findex ffap -@findex dired-at-point -@findex ffap-next -@findex ffap-menu -@cindex finding file at point - - The FFAP package replaces certain key bindings for finding files, -such as @kbd{C-x C-f}, with commands that provide more sensitive -defaults. These commands behave like the ordinary ones when given a -prefix argument. Otherwise, they get the default file name or URL -from the text around point. If what is found in the buffer has the -form of a URL rather than a file name, the commands use -@code{browse-url} to view it (@pxref{Browse-URL}). - - This feature is useful for following references in mail or news -buffers, @file{README} files, @file{MANIFEST} files, and so on. For -more information, view the package commentary by typing @kbd{C-h P -ffap @key{RET}}. - -@cindex FFAP minor mode -@findex ffap-mode - To enable FFAP, type @kbd{M-x ffap-bindings}. This makes the -following key bindings, and also installs hooks for additional FFAP -functionality in Rmail, Gnus and VM article buffers. - -@table @kbd -@item C-x C-f @var{filename} @key{RET} -@kindex C-x C-f @r{(FFAP)} -Find @var{filename}, guessing a default from text around point -(@code{find-file-at-point}). -@item C-x C-r -@kindex C-x C-r @r{(FFAP)} -@code{ffap-read-only}, analogous to @code{find-file-read-only}. -@item C-x C-v -@kindex C-x C-v @r{(FFAP)} -@code{ffap-alternate-file}, analogous to @code{find-alternate-file}. -@item C-x d @var{directory} @key{RET} -@kindex C-x d @r{(FFAP)} -Start Dired on @var{directory}, defaulting to the directory name at -point (@code{dired-at-point}). -@item C-x C-d -@code{ffap-list-directory}, analogous to @code{list-directory}. -@item C-x 4 f -@kindex C-x 4 f @r{(FFAP)} -@code{ffap-other-window}, analogous to @code{find-file-other-window}. -@item C-x 4 r -@code{ffap-read-only-other-window}, analogous to -@code{find-file-read-only-other-window}. -@item C-x 4 d -@code{ffap-dired-other-window}, analogous to @code{dired-other-window}. -@item C-x 5 f -@kindex C-x 5 f @r{(FFAP)} -@code{ffap-other-frame}, analogous to @code{find-file-other-frame}. -@item C-x 5 r -@code{ffap-read-only-other-frame}, analogous to -@code{find-file-read-only-other-frame}. -@item C-x 5 d -@code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}. -@item M-x ffap-next -Search buffer for next file name or URL, then find that file or URL. -@item S-Mouse-3 -@kindex S-Mouse-3 @r{(FFAP)} -@code{ffap-at-mouse} finds the file guessed from text around the position -of a mouse click. -@item C-S-Mouse-3 -@kindex C-S-Mouse-3 @r{(FFAP)} -Display a menu of files and URLs mentioned in current buffer, then -find the one you select (@code{ffap-menu}). -@end table - -@node Amusements, Packages, Hyperlinking, Top -@section Other Amusements -@cindex boredom - -@findex animate-birthday-present -@cindex animate - The @code{animate} package makes text dance (e.g. try -@kbd{M-x animate-birthday-present}). - -@findex blackbox -@findex mpuz -@findex 5x5 -@cindex puzzles - @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are puzzles. -@code{blackbox} challenges you to determine the location of objects -inside a box by tomography. @code{mpuz} displays a multiplication -puzzle with letters standing for digits in a code that you must -guess---to guess a value, type a letter and then the digit you think it -stands for. The aim of @code{5x5} is to fill in all the squares. - -@findex bubbles - @kbd{M-x bubbles} is a game in which the object is to remove as many -bubbles as you can in the smallest number of moves. - -@findex decipher -@cindex ciphers -@cindex cryptanalysis - @kbd{M-x decipher} helps you to cryptanalyze a buffer which is -encrypted in a simple monoalphabetic substitution cipher. - -@findex dissociated-press - @kbd{M-x dissociated-press} scrambles the text in the current Emacs -buffer, word by word or character by character, writing its output to -a buffer named @file{*Dissociation*}. A positive argument tells it to -operate character by character, and specifies the number of overlap -characters. A negative argument tells it to operate word by word, and -specifies the number of overlap words. Dissociated Press produces -results fairly like those of a Markov chain, but is however, an -independent, ignoriginal invention; it techniquitously copies several -consecutive characters from the sample text between random jumps, -unlike a Markov chain which would jump randomly after each word or -character. Keep dissociwords out of your documentation, if you want -it to be well userenced and properbose. - -@findex dunnet - @kbd{M-x dunnet} runs an text-based adventure game. - -@findex gomoku -@cindex Go Moku - If you want a little more personal involvement, try @kbd{M-x gomoku}, -which plays the game Go Moku with you. - -@cindex tower of Hanoi -@findex hanoi - If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are -considerably bored, give it a numeric argument. If you are very, very -bored, try an argument of 9. Sit back and watch. - -@findex life -@cindex Life - @kbd{M-x life} runs Conway's ``Life'' cellular automaton. - -@findex landmark -@cindex landmark game - @kbd{M-x landmark} runs a relatively non-participatory game in which -a robot attempts to maneuver towards a tree at the center of the -window based on unique olfactory cues from each of the four -directions. - -@findex morse-region -@findex unmorse-region -@findex nato-region -@cindex Morse code -@cindex --/---/.-./.../. - @kbd{M-x morse-region} converts the text in the region to Morse -code; @kbd{M-x unmorse-region} converts it back. @kbd{M-x -nato-region} converts the text in the region to NATO phonetic -alphabet; @kbd{M-x denato-region} converts it back. - -@findex pong -@cindex Pong game -@findex tetris -@cindex Tetris -@findex snake -@cindex Snake - @kbd{M-x pong}, @kbd{M-x snake} and @kbd{M-x tetris} are -implementations of the well-known Pong, Snake and Tetris games. - -@findex solitaire -@cindex solitaire - @kbd{M-x solitaire} plays a game of solitaire in which you jump pegs -across other pegs. - -@findex zone - The command @kbd{M-x zone} plays games with the display when Emacs -is idle. - -@findex doctor -@cindex Eliza - Finally, if you find yourself frustrated, try describing your -problems to the famous psychotherapist Eliza. Just do @kbd{M-x -doctor}. End each input by typing @key{RET} twice. - -@ifnottex -@lowersections -@end ifnottex diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi deleted file mode 100644 index a48299768a8..00000000000 --- a/doc/emacs/modes.texi +++ /dev/null @@ -1,450 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Modes, Indentation, International, Top -@chapter Major and Minor Modes - - Emacs contains many @dfn{editing modes} that alter its basic -behavior in useful ways. These are divided into @dfn{major modes} and -@dfn{minor modes}. - - Major modes provide specialized facilities for working on a -particular file type, such as a C source file (@pxref{Programs}), or a -particular type of non-file buffer, such as a shell buffer -(@pxref{Shell}). Major modes are mutually exclusive; each buffer has -one and only one major mode at any time. - - Minor modes are optional features which you can turn on or off, not -necessarily specific to a type of file or buffer. For example, Auto -Fill mode is a minor mode in which @key{SPC} breaks lines between -words as you type (@pxref{Auto Fill}). Minor modes are independent of -one another, and of the selected major mode. - -@menu -* Major Modes:: Text mode vs. Lisp mode vs. C mode... -* Minor Modes:: Each minor mode is a feature you can turn on - independently of any others. -* Choosing Modes:: How modes are chosen when visiting files. -@end menu - -@node Major Modes -@section Major Modes -@cindex major modes -@cindex mode, major -@kindex TAB @r{(and major modes)} -@kindex DEL @r{(and major modes)} -@kindex C-j @r{(and major modes)} - - Every buffer possesses a major mode, which determines the editing -behavior of Emacs while that buffer is current. The mode line -normally shows the name of the current major mode, in parentheses -(@pxref{Mode Line}). - - The least specialized major mode is called @dfn{Fundamental mode}. -This mode has no mode-specific redefinitions or variable settings, so -that each Emacs command behaves in its most general manner, and each -user option variable is in its default state. - - For editing text of a specific type that Emacs knows about, such as -Lisp code or English text, you typically use a more specialized major -mode, such as Lisp mode or Text mode. Most major modes fall into -three major groups. The first group contains modes for normal text, -either plain or with mark-up. It includes Text mode, HTML mode, SGML -mode, @TeX{} mode and Outline mode. The second group contains modes -for specific programming languages. These include Lisp mode (which -has several variants), C mode, Fortran mode, and others. The third -group consists of major modes that are not associated directly with -files; they are used in buffers created for specific purposes by -Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}), -Message mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}), -and Shell mode for buffers used to communicate with an inferior shell -process (@pxref{Interactive Shell}). - - Usually, the major mode is automatically set by Emacs, when you -first visit a file or create a buffer (@pxref{Choosing Modes}). You -can explicitly select a new major mode by using an @kbd{M-x} command. -Take the name of the mode and add @code{-mode} to get the name of the -command to select that mode (e.g., @kbd{M-x lisp-mode} enters Lisp mode). - -@vindex major-mode - The value of the buffer-local variable @code{major-mode} is a symbol -with the same name as the major mode command (e.g. @code{lisp-mode}). -This variable is set automatically; you should not change it yourself. - - The default value of @code{major-mode} determines the major mode to -use for files that do not specify a major mode, and for new buffers -created with @kbd{C-x b}. Normally, this default value is the symbol -@code{fundamental-mode}, which specifies Fundamental mode. You can -change this default value via the Customization interface (@pxref{Easy -Customization}), or by adding a line like this to your init file -(@pxref{Init File}): - -@example -(setq-default major-mode 'text-mode) -@end example - -@noindent -If the default value of @code{major-mode} is @code{nil}, the major -mode is taken from the previously current buffer. - - Specialized major modes often change the meanings of certain keys to -do something more suitable for the mode. For instance, programming -language modes bind @key{TAB} to indent the current line according to -the rules of the language (@pxref{Indentation}). The keys that are -commonly changed are @key{TAB}, @key{DEL}, and @kbd{C-j}. Many modes -also define special commands of their own, usually bound in the prefix -key @kbd{C-c}. Major modes can also alter user options and variables; -for instance, programming language modes typically set a buffer-local -value for the variable @code{comment-start}, which determines how -source code comments are delimited (@pxref{Comments}). - -@findex describe-mode -@kindex C-h m - To view the documentation for the current major mode, including a -list of its key bindings, type @code{C-h m} (@code{describe-mode}). - -@cindex mode hook -@vindex text-mode-hook -@vindex prog-mode-hook - Every major mode, apart from Fundamental mode, defines a @dfn{mode -hook}, a customizable list of Lisp functions to run each time the mode -is enabled in a buffer. @xref{Hooks}, for more information about -hooks. Each mode hook is named after its major mode, e.g. Fortran -mode has @code{fortran-mode-hook}. Furthermore, all text-based major -modes run @code{text-mode-hook}, and all programming language modes -run @code{prog-mode-hook}, prior to running their own mode hooks. -Hook functions can look at the value of the variable @code{major-mode} -to see which mode is actually being entered. - - Mode hooks are commonly used to enable minor modes (@pxref{Minor -Modes}). For example, you can put the following lines in your init -file to enable Flyspell minor mode in all text-based major modes -(@pxref{Spelling}), and Eldoc minor mode in Emacs Lisp mode -(@pxref{Lisp Doc}): - -@example -(add-hook 'text-mode-hook 'flyspell-mode) -(add-hook 'emacs-lisp-mode-hook 'eldoc-mode) -@end example - -@node Minor Modes -@section Minor Modes -@cindex minor modes -@cindex mode, minor - - A minor mode is an optional editing mode that alters the behavior of -Emacs in some well-defined way. Unlike major modes, any number of -minor modes can be in effect at any time. Some minor modes are -@dfn{buffer-local}, and can be turned on (enabled) in certain buffers -and off (disabled) in others. Other minor modes are @dfn{global}: -while enabled, they affect everything you do in the Emacs session, in -all buffers. Most minor modes are disabled by default, but a few are -enabled by default. - - Most buffer-local minor modes say in the mode line when they are -enabled, just after the major mode indicator. For example, -@samp{Fill} in the mode line means that Auto Fill mode is enabled. -@xref{Mode Line}. - -@cindex mode commands for minor modes - Like major modes, each minor mode is associated with a @dfn{mode -command}, whose name consists of the mode name followed by -@samp{-mode}. For instance, the mode command for Auto Fill mode is -@code{auto-fill-mode}. But unlike a major mode command, which simply -enables the mode, the mode command for a minor mode can either enable -or disable it: - -@itemize -@item -If you invoke the mode command directly with no prefix argument -(either via @kbd{M-x}, or by binding it to a key and typing that key; -@pxref{Key Bindings}), that @dfn{toggles} the minor mode. The minor -mode is turned on if it was off, and turned off if it was on. - -@item -If you invoke the mode command with a prefix argument, the minor mode -is unconditionally turned off if that argument is zero or negative; -otherwise, it is unconditionally turned on. - -@item -If the mode command is called via Lisp, the minor mode is -unconditionally turned on if the argument is omitted or @code{nil}. -This makes it easy to turn on a minor mode from a major mode's mode -hook (@pxref{Major Modes}). A non-@code{nil} argument is handled like -an interactive prefix argument, as described above. -@end itemize - - Most minor modes also have a @dfn{mode variable}, with the same name -as the mode command. Its value is non-@code{nil} if the mode is -enabled, and @code{nil} if it is disabled. In general, you should not -try to enable or disable the mode by changing the value of the mode -variable directly in Lisp; you should run the mode command instead. -However, setting the mode variable through the Customize interface -(@pxref{Easy Customization}) will always properly enable or disable -the mode, since Customize automatically runs the mode command for you. - - The following is a list of some buffer-local minor modes: - -@itemize @bullet -@item -Abbrev mode automatically expands text based on pre-defined -abbreviation definitions. @xref{Abbrevs}. - -@item -Auto Fill mode inserts newlines as you type to prevent lines from -becoming too long. @xref{Filling}. - -@item -Auto Save mode saves the buffer contents periodically to reduce the -amount of work you can lose in case of a crash. @xref{Auto Save}. - -@item -Enriched mode enables editing and saving of formatted text. -@xref{Enriched Text}. - -@item -Flyspell mode automatically highlights misspelled words. -@xref{Spelling}. - -@item -Font-Lock mode automatically highlights certain textual units found in -programs. It is enabled globally by default, but you can disable it -in individual buffers. @xref{Faces}. - -@findex linum-mode -@cindex Linum mode -@item -Linum mode displays each line's line number in the window's left margin. - -@item -Outline minor mode provides similar facilities to the major mode -called Outline mode. @xref{Outline Mode}. - -@cindex Overwrite mode -@cindex mode, Overwrite -@findex overwrite-mode -@kindex INSERT -@item -Overwrite mode causes ordinary printing characters to replace existing -text instead of shoving it to the right. For example, if point is in -front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing -a @kbd{G} changes it to @samp{FOOGAR}, instead of producing -@samp{FOOGBAR} as usual. In Overwrite mode, the command @kbd{C-q} -inserts the next character whatever it may be, even if it is a -digit---this gives you a way to insert a character instead of -replacing an existing character. The mode command, -@code{overwrite-mode}, is bound to the @key{Insert} key. - -@findex binary-overwrite-mode -@item -Binary Overwrite mode is a variant of Overwrite mode for editing -binary files; it treats newlines and tabs like other characters, so -that they overwrite other characters and can be overwritten by them. -In Binary Overwrite mode, digits after @kbd{C-q} specify an octal -character code, as usual. - -@item -Visual Line mode performs ``word wrapping'', causing long lines to be -wrapped at word boundaries. @xref{Visual Line Mode}. -@end itemize - -@noindent -And here are some useful global minor modes: - -@itemize @bullet -@item -Column Number mode enables display of the current column number in the -mode line. @xref{Mode Line}. - -@item -Delete Selection mode causes text insertion to first delete the text -in the region, if the region is active. @xref{Using Region}. - -@item -Icomplete mode displays an indication of available completions when -you are in the minibuffer and completion is active. @xref{Completion -Options}. - -@item -Line Number mode enables display of the current line number in the -mode line. It is enabled by default. @xref{Mode Line}. - -@item -Menu Bar mode gives each frame a menu bar. It is enabled by default. -@xref{Menu Bars}. - -@item -Scroll Bar mode gives each window a scroll bar. It is enabled by -default, but the scroll bar is only displayed on graphical terminals. -@xref{Scroll Bars}. - -@item -Tool Bar mode gives each frame a tool bar. It is enabled by default, -but the tool bar is only displayed on graphical terminals. @xref{Tool -Bars}. - -@item -Transient Mark mode highlights the region, and makes many Emacs -commands operate on the region when the mark is active. It is enabled -by default. @xref{Mark}. -@end itemize - -@node Choosing Modes -@section Choosing File Modes - -@cindex choosing a major mode -@cindex choosing a minor mode -@vindex auto-mode-alist - When you visit a file, Emacs chooses a major mode automatically. -Normally, it makes the choice based on the file name---for example, -files whose names end in @samp{.c} are normally edited in C mode---but -sometimes it chooses the major mode based on special text in the file. -This special text can also be used to enable buffer-local minor modes. - - Here is the exact procedure: - - First, Emacs checks whether the file contains file-local mode -variables. @xref{File Variables}. If there is a file-local variable -that specifies a major mode, then Emacs uses that major mode, ignoring -all other criteria. There are several methods to specify a major mode -using a file-local variable; the simplest is to put the mode name in -the first nonblank line, preceded and followed by @samp{-*-}. Other -text may appear on the line as well. For example, - -@example -; -*-Lisp-*- -@end example - -@noindent -tells Emacs to use Lisp mode. Note how the semicolon is used to make -Lisp treat this line as a comment. You could equivalently write - -@example -; -*- mode: Lisp;-*- -@end example - -@noindent -You can also use file-local variables to specify buffer-local minor -modes, by using @code{eval} specifications. For example, this first -nonblank line puts the buffer in Lisp mode and enables Auto-Fill mode: - -@example -; -*- mode: Lisp; eval: (auto-fill-mode 1); -*- -@end example - -@noindent -Note, however, that it is usually inappropriate to enable minor modes -this way, since most minor modes represent individual user -preferences. If you personally want to use a minor mode for a -particular file type, it is better to enable the minor mode via a -major mode hook (@pxref{Major Modes}). - -@vindex interpreter-mode-alist - Second, if there is no file variable specifying a major mode, Emacs -checks whether the file's contents begin with @samp{#!}. If so, that -indicates that the file can serve as an executable shell command, -which works by running an interpreter named on the file's first line -(the rest of the file is used as input to the interpreter). -Therefore, Emacs tries to use the interpreter name to choose a mode. -For instance, a file that begins with @samp{#!/usr/bin/perl} is opened -in Perl mode. The variable @code{interpreter-mode-alist} specifies -the correspondence between interpreter program names and major modes. - - When the first line starts with @samp{#!}, you usually cannot use -the @samp{-*-} feature on the first line, because the system would get -confused when running the interpreter. So Emacs looks for @samp{-*-} -on the second line in such files as well as on the first line. The -same is true for man pages which start with the magic string -@samp{'\"} to specify a list of troff preprocessors. - -@vindex magic-mode-alist - Third, Emacs tries to determine the major mode by looking at the -text at the start of the buffer, based on the variable -@code{magic-mode-alist}. By default, this variable is @code{nil} (an -empty list), so Emacs skips this step; however, you can customize it -in your init file (@pxref{Init File}). The value should be a list of -elements of the form - -@example -(@var{regexp} . @var{mode-function}) -@end example - -@noindent -where @var{regexp} is a regular expression (@pxref{Regexps}), and -@var{mode-function} is a major mode command. If the text at the -beginning of the file matches @var{regexp}, Emacs chooses the major -mode specified by @var{mode-function}. - -Alternatively, an element of @code{magic-mode-alist} may have the form - -@example -(@var{match-function} . @var{mode-function}) -@end example - -@noindent -where @var{match-function} is a Lisp function that is called at the -beginning of the buffer; if the function returns non-@code{nil}, Emacs -set the major mode with @var{mode-function}. - - Fourth---if Emacs still hasn't found a suitable major mode---it -looks at the file's name. The correspondence between file names and -major modes is controlled by the variable @code{auto-mode-alist}. Its -value is a list in which each element has this form, - -@example -(@var{regexp} . @var{mode-function}) -@end example - -@noindent -or this form, - -@example -(@var{regexp} @var{mode-function} @var{flag}) -@end example - -@noindent -For example, one element normally found in the list has the form -@code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C -mode for files whose names end in @file{.c}. (Note that @samp{\\} is -needed in Lisp syntax to include a @samp{\} in the string, which must -be used to suppress the special meaning of @samp{.} in regexps.) If -the element has the form @code{(@var{regexp} @var{mode-function} -@var{flag})} and @var{flag} is non-@code{nil}, then after calling -@var{mode-function}, Emacs discards the suffix that matched -@var{regexp} and searches the list again for another match. - -@vindex auto-mode-case-fold - On GNU/Linux and other systems with case-sensitive file names, Emacs -performs a case-sensitive search through @code{auto-mode-alist}; if -this search fails, it performs a second case-insensitive search -through the alist. To suppress the second search, change the variable -@code{auto-mode-case-fold} to @code{nil}. On systems with -case-insensitive file names, such as Microsoft Windows, Emacs performs -a single case-insensitive search through @code{auto-mode-alist}. - -@vindex magic-fallback-mode-alist - Finally, if Emacs @emph{still} hasn't found a major mode to use, it -compares the text at the start of the buffer to the variable -@code{magic-fallback-mode-alist}. This variable works like -@code{magic-mode-alist}, described above, except that is consulted -only after @code{auto-mode-alist}. By default, -@code{magic-fallback-mode-alist} contains forms that check for image -files, HTML/XML/SGML files, and PostScript files. - -@findex normal-mode - If you have changed the major mode of a buffer, you can return to -the major mode Emacs would have chosen automatically, by typing -@kbd{M-x normal-mode}. This is the same function that -@code{find-file} calls to choose the major mode. It also processes -the file's @samp{-*-} line or local variables list (if any). -@xref{File Variables}. - -@vindex change-major-mode-with-file-name - The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to -a new major mode if the new file name implies a mode (@pxref{Saving}). -(@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.) -However, this does not happen if the buffer contents specify a major -mode, and certain ``special'' major modes do not allow the mode to -change. You can turn off this mode-changing feature by setting -@code{change-major-mode-with-file-name} to @code{nil}. diff --git a/doc/emacs/msdog-xtra.texi b/doc/emacs/msdog-xtra.texi deleted file mode 100644 index 0d05c8ac9c6..00000000000 --- a/doc/emacs/msdog-xtra.texi +++ /dev/null @@ -1,620 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node MS-DOS -@section Emacs and MS-DOS -@cindex MS-DOG -@cindex MS-DOS peculiarities - - This section briefly describes the peculiarities of using Emacs on -the MS-DOS ``operating system'' (also known as ``MS-DOG''). -@iftex -Information about Emacs and Microsoft's current operating system -Windows (also known as ``Losedows'') is in the main Emacs manual -(@pxref{Microsoft Windows,,, emacs, the Emacs Manual}). -@end iftex -@ifnottex -Information about peculiarities common to MS-DOS and Microsoft's -current operating systems Windows (also known as ``Losedows'') is in -@ref{Microsoft Windows}. -@end ifnottex - - If you build Emacs for MS-DOS, the binary will also run on Windows -3.X, Windows NT, Windows 9X/ME, Windows 2000/XP, or OS/2 as a DOS -application; all of this chapter applies for all of those systems, if -you use an Emacs that was built for MS-DOS. - -@iftex - @xref{Text and Binary,,,emacs, the Emacs Manual}, for information -@end iftex -@ifnottex - @xref{Text and Binary}, for information -@end ifnottex -about Emacs's special handling of text files under MS-DOS (and Windows). - -@menu -* Keyboard: MS-DOS Keyboard. Keyboard conventions on MS-DOS. -* Mouse: MS-DOS Mouse. Mouse conventions on MS-DOS. -* Display: MS-DOS Display. Fonts, frames and display size on MS-DOS. -* Files: MS-DOS File Names. File name conventions on MS-DOS. -* Printing: MS-DOS Printing. Printing specifics on MS-DOS. -* I18N: MS-DOS and MULE. Support for internationalization on MS-DOS. -* Processes: MS-DOS Processes. Running subprocesses on MS-DOS. -@end menu - -@node MS-DOS Keyboard -@subsection Keyboard Usage on MS-DOS - -@kindex DEL @r{(MS-DOS)} -@kindex BS @r{(MS-DOS)} - The key that is called @key{DEL} in Emacs (because that's how it is -designated on most workstations) is known as @key{BS} (backspace) on a -PC. That is why the PC-specific terminal initialization remaps the -@key{BS} key to act as @key{DEL}; the @key{DELETE} key is remapped to act -as @kbd{C-d} for the same reasons. - -@kindex C-g @r{(MS-DOS)} -@kindex C-BREAK @r{(MS-DOS)} -@cindex quitting on MS-DOS - Emacs built for MS-DOS recognizes @kbd{C-@key{BREAK}} as a quit -character, just like @kbd{C-g}. This is because Emacs cannot detect -that you have typed @kbd{C-g} until it is ready for more input. As a -consequence, you cannot use @kbd{C-g} to stop a running command -@iftex -(@pxref{Quitting,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Quitting}). -@end ifnottex -By contrast, @kbd{C-@key{BREAK}} @emph{is} detected as soon as you -type it (as @kbd{C-g} is on other systems), so it can be used to stop -a running command and for emergency escape -@iftex -(@pxref{Emergency Escape,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Emergency Escape}). -@end ifnottex - -@cindex Meta (under MS-DOS) -@cindex Hyper (under MS-DOS) -@cindex Super (under MS-DOS) -@vindex dos-super-key -@vindex dos-hyper-key - The PC keyboard maps use the left @key{ALT} key as the @key{META} key. -You have two choices for emulating the @key{SUPER} and @key{HYPER} keys: -choose either the right @key{CTRL} key or the right @key{ALT} key by -setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1 -or 2 respectively. If neither @code{dos-super-key} nor -@code{dos-hyper-key} is 1, then by default the right @key{ALT} key is -also mapped to the @key{META} key. However, if the MS-DOS international -keyboard support program @file{KEYB.COM} is installed, Emacs will -@emph{not} map the right @key{ALT} to @key{META}, since it is used for -accessing characters like @kbd{~} and @kbd{@@} on non-US keyboard -layouts; in this case, you may only use the left @key{ALT} as @key{META} -key. - -@kindex C-j @r{(MS-DOS)} -@vindex dos-keypad-mode - The variable @code{dos-keypad-mode} is a flag variable that controls -what key codes are returned by keys in the numeric keypad. You can also -define the keypad @key{ENTER} key to act like @kbd{C-j}, by putting the -following line into your @file{_emacs} file: - -@smallexample -;; @r{Make the @key{ENTER} key from the numeric keypad act as @kbd{C-j}.} -(define-key function-key-map [kp-enter] [?\C-j]) -@end smallexample - -@node MS-DOS Mouse -@subsection Mouse Usage on MS-DOS - -@cindex mouse support under MS-DOS - Emacs on MS-DOS supports a mouse (on the default terminal only). -The mouse commands work as documented, including those that use menus -and the menu bar -@iftex -(@pxref{Menu Bar,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Menu Bar}). -@end ifnottex - Scroll bars don't work in MS-DOS Emacs. PC mice usually have only -two buttons; these act as @kbd{Mouse-1} and @kbd{Mouse-2}, but if you -press both of them together, that has the effect of @kbd{Mouse-3}. If -the mouse does have 3 buttons, Emacs detects that at startup, and all -the 3 buttons function normally, as on X. - - Help strings for menu-bar and pop-up menus are displayed in the echo -area when the mouse pointer moves across the menu items. Highlighting -of mouse-sensitive text -@iftex -(@pxref{Mouse References,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Mouse References}) -@end ifnottex -is also supported. - -@cindex mouse, set number of buttons -@findex msdos-set-mouse-buttons - Some versions of mouse drivers don't report the number of mouse -buttons correctly. For example, mice with a wheel report that they -have 3 buttons, but only 2 of them are passed to Emacs; the clicks on -the wheel, which serves as the middle button, are not passed. In -these cases, you can use the @kbd{M-x msdos-set-mouse-buttons} command -to tell Emacs how many mouse buttons to expect. You could make such a -setting permanent by adding this fragment to your @file{_emacs} init -file: - -@example -;; @r{Treat the mouse like a 2-button mouse.} -(msdos-set-mouse-buttons 2) -@end example - -@cindex Windows clipboard support - Emacs built for MS-DOS supports clipboard operations when it runs on -Windows. Commands that put text on the kill ring, or yank text from -the ring, check the Windows clipboard first, just as Emacs does on the -X Window System -@iftex -(@pxref{Mouse Commands,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Mouse Commands}). -@end ifnottex -Only the primary selection and the cut buffer are supported by MS-DOS -Emacs on Windows; the secondary selection always appears as empty. - - Due to the way clipboard access is implemented by Windows, the -length of text you can put into the clipboard is limited by the amount -of free DOS memory that is available to Emacs. Usually, up to 620KB of -text can be put into the clipboard, but this limit depends on the system -configuration and is lower if you run Emacs as a subprocess of -another program. If the killed text does not fit, Emacs outputs a -message saying so, and does not put the text into the clipboard. - - Null characters also cannot be put into the Windows clipboard. If the -killed text includes null characters, Emacs does not put such text into -the clipboard, and displays in the echo area a message to that effect. - -@vindex dos-display-scancodes - The variable @code{dos-display-scancodes}, when non-@code{nil}, -directs Emacs to display the @acronym{ASCII} value and the keyboard scan code of -each keystroke; this feature serves as a complement to the -@code{view-lossage} command, for debugging. - -@node MS-DOS Display -@subsection Display on MS-DOS -@cindex faces under MS-DOS -@cindex fonts, emulating under MS-DOS - - Display on MS-DOS cannot use font variants, like bold or italic, but -it does support multiple faces, each of which can specify a foreground -and a background color. Therefore, you can get the full functionality -of Emacs packages that use fonts (such as @code{font-lock}, Enriched -Text mode, and others) by defining the relevant faces to use different -colors. Use the @code{list-colors-display} command -@iftex -(@pxref{Colors,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Colors}) -@end ifnottex -and the @code{list-faces-display} command -@iftex -(@pxref{Faces,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Faces}) -@end ifnottex -to see what colors and faces are available and what they look like. - - @xref{MS-DOS and MULE}, later in this chapter, for information on -how Emacs displays glyphs and characters that aren't supported by the -native font built into the DOS display. - -@cindex cursor shape on MS-DOS - When Emacs starts, it changes the cursor shape to a solid box. This -is for compatibility with other systems, where the box cursor is the -default in Emacs. This default shape can be changed to a bar by -specifying the @code{cursor-type} parameter in the variable -@code{default-frame-alist} -@iftex -(@pxref{Creating Frames,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Creating Frames}). -@end ifnottex -The MS-DOS terminal doesn't support a vertical-bar cursor, -so the bar cursor is horizontal, and the @code{@var{width}} parameter, -if specified by the frame parameters, actually determines its height. -For this reason, the @code{bar} and @code{hbar} cursor types produce -the same effect on MS-DOS. As an extension, the bar cursor -specification can include the starting scan line of the cursor as well -as its width, like this: - -@example - '(cursor-type bar @var{width} . @var{start}) -@end example - -@noindent -In addition, if the @var{width} parameter is negative, the cursor bar -begins at the top of the character cell. - -@cindex frames on MS-DOS - The MS-DOS terminal can only display a single frame at a time. The -Emacs frame facilities work on MS-DOS much as they do on text -terminals -@iftex -(@pxref{Frames,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Frames}). -@end ifnottex -When you run Emacs from a DOS window on MS-Windows, you can make the -visible frame smaller than the full screen, but Emacs still cannot -display more than a single frame at a time. - -@cindex frame size under MS-DOS -@findex dos-mode4350 -@findex dos-mode25 - The @code{dos-mode4350} command switches the display to 43 or 50 -lines, depending on your hardware; the @code{dos-mode25} command switches -to the default 80x25 screen size. - - By default, Emacs only knows how to set screen sizes of 80 columns by -25, 28, 35, 40, 43 or 50 rows. However, if your video adapter has -special video modes that will switch the display to other sizes, you can -have Emacs support those too. When you ask Emacs to switch the frame to -@var{n} rows by @var{m} columns dimensions, it checks if there is a -variable called @code{screen-dimensions-@var{n}x@var{m}}, and if so, -uses its value (which must be an integer) as the video mode to switch -to. (Emacs switches to that video mode by calling the BIOS @code{Set -Video Mode} function with the value of -@code{screen-dimensions-@var{n}x@var{m}} in the @code{AL} register.) -For example, suppose your adapter will switch to 66x80 dimensions when -put into video mode 85. Then you can make Emacs support this screen -size by putting the following into your @file{_emacs} file: - -@example -(setq screen-dimensions-66x80 85) -@end example - - Since Emacs on MS-DOS can only set the frame size to specific -supported dimensions, it cannot honor every possible frame resizing -request. When an unsupported size is requested, Emacs chooses the next -larger supported size beyond the specified size. For example, if you -ask for 36x80 frame, you will get 40x80 instead. - - The variables @code{screen-dimensions-@var{n}x@var{m}} are used only -when they exactly match the specified size; the search for the next -larger supported size ignores them. In the above example, even if your -VGA supports 38x80 dimensions and you define a variable -@code{screen-dimensions-38x80} with a suitable value, you will still get -40x80 screen when you ask for a 36x80 frame. If you want to get the -38x80 size in this case, you can do it by setting the variable named -@code{screen-dimensions-36x80} with the same video mode value as -@code{screen-dimensions-38x80}. - - Changing frame dimensions on MS-DOS has the effect of changing all the -other frames to the new dimensions. - -@node MS-DOS File Names -@subsection File Names on MS-DOS -@cindex file names under MS-DOS -@cindex init file, default name under MS-DOS - - On MS-DOS, file names are case-insensitive and limited to eight -characters, plus optionally a period and three more characters. Emacs -knows enough about these limitations to handle file names that were -meant for other operating systems. For instance, leading dots -@samp{.} in file names are invalid in MS-DOS, so Emacs transparently -converts them to underscores @samp{_}; thus your default init file -@iftex -(@pxref{Init File,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Init File}) -@end ifnottex -is called @file{_emacs} on MS-DOS. Excess characters before or after -the period are generally ignored by MS-DOS itself; thus, if you visit -the file @file{LongFileName.EvenLongerExtension}, you will silently -get @file{longfile.eve}, but Emacs will still display the long file -name on the mode line. Other than that, it's up to you to specify -file names which are valid under MS-DOS; the transparent conversion as -described above only works on file names built into Emacs. - -@cindex backup file names on MS-DOS - The above restrictions on the file names on MS-DOS make it almost -impossible to construct the name of a backup file -@iftex -(@pxref{Backup Names,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Backup Names}) -@end ifnottex -without losing some of the original file name characters. For -example, the name of a backup file for @file{docs.txt} is -@file{docs.tx~} even if single backup is used. - -@cindex file names under Windows 95/NT -@cindex long file names in DOS box under Windows 95/NT - If you run Emacs as a DOS application under Windows 9X, Windows ME, or -Windows 2000/XP, you can turn on support for long file names. If you do -that, Emacs doesn't truncate file names or convert them to lower case; -instead, it uses the file names that you specify, verbatim. To enable -long file name support, set the environment variable @env{LFN} to -@samp{y} before starting Emacs. Unfortunately, Windows NT doesn't allow -DOS programs to access long file names, so Emacs built for MS-DOS will -only see their short 8+3 aliases. - -@cindex @env{HOME} directory under MS-DOS - MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends -that the directory where it is installed is the value of the @env{HOME} -environment variable. That is, if your Emacs binary, -@file{emacs.exe}, is in the directory @file{c:/utils/emacs/bin}, then -Emacs acts as if @env{HOME} were set to @samp{c:/utils/emacs}. In -particular, that is where Emacs looks for the init file @file{_emacs}. -With this in mind, you can use @samp{~} in file names as an alias for -the home directory, as you would on GNU or Unix. You can also set -@env{HOME} variable in the environment before starting Emacs; its -value will then override the above default behavior. - - Emacs on MS-DOS handles the directory name @file{/dev} specially, -because of a feature in the emulator libraries of DJGPP that pretends -I/O devices have names in that directory. We recommend that you avoid -using an actual directory named @file{/dev} on any disk. - -@node MS-DOS Printing -@subsection Printing and MS-DOS - - Printing commands, such as @code{lpr-buffer} -@iftex -(@pxref{Printing,,,emacs, the Emacs Manual}) and @code{ps-print-buffer} -(@pxref{PostScript,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}) -@end ifnottex -can work on MS-DOS by sending the output to one of the printer ports, -if a Posix-style @code{lpr} program is unavailable. The same Emacs -variables control printing on all systems, but in some cases they have -different default values on MS-DOS. - -@iftex -@xref{Windows Printing,,,emacs, the Emacs Manual}, -@end iftex -@ifnottex -@xref{Windows Printing}, -@end ifnottex -for details about setting up printing to a networked printer. - - Some printers expect DOS codepage encoding of non-@acronym{ASCII} text, even -though they are connected to a Windows machine that uses a different -encoding for the same locale. For example, in the Latin-1 locale, DOS -uses codepage 850 whereas Windows uses codepage 1252. @xref{MS-DOS and -MULE}. When you print to such printers from Windows, you can use the -@kbd{C-x RET c} (@code{universal-coding-system-argument}) command before -@kbd{M-x lpr-buffer}; Emacs will then convert the text to the DOS -codepage that you specify. For example, @kbd{C-x RET c cp850-dos RET -M-x lpr-region RET} will print the region while converting it to the -codepage 850 encoding. - -@vindex dos-printer -@vindex dos-ps-printer - For backwards compatibility, the value of @code{dos-printer} -(@code{dos-ps-printer}), if it has a value, overrides the value of -@code{printer-name} (@code{ps-printer-name}), on MS-DOS. - - -@node MS-DOS and MULE -@subsection International Support on MS-DOS -@cindex international support @r{(MS-DOS)} - - Emacs on MS-DOS supports the same international character sets as it -does on GNU, Unix and other platforms -@iftex -(@pxref{International,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{International}), -@end ifnottex -including coding systems for converting between the different -character sets. However, due to incompatibilities between -MS-DOS/MS-Windows and other systems, there are several DOS-specific -aspects of this support that you should be aware of. This section -describes these aspects. - - The description below is largely specific to the MS-DOS port of -Emacs, especially where it talks about practical implications for -Emacs users. - -@table @kbd -@item M-x dos-codepage-setup -Set up Emacs display and coding systems as appropriate for the current -DOS codepage. -@end table - -@cindex codepage, MS-DOS -@cindex DOS codepages - MS-DOS is designed to support one character set of 256 characters at -any given time, but gives you a variety of character sets to choose -from. The alternative character sets are known as @dfn{DOS codepages}. -Each codepage includes all 128 @acronym{ASCII} characters, but the other 128 -characters (codes 128 through 255) vary from one codepage to another. -Each DOS codepage is identified by a 3-digit number, such as 850, 862, -etc. - - In contrast to X, which lets you use several fonts at the same time, -MS-DOS normally doesn't allow use of several codepages in a single -session. MS-DOS was designed to load a single codepage at system -startup, and require you to reboot in order to change -it@footnote{Normally, one particular codepage is burnt into the -display memory, while other codepages can be installed by modifying -system configuration files, such as @file{CONFIG.SYS}, and rebooting. -While there is third-party software that allows changing the codepage -without rebooting, we describe here how a stock MS-DOS system -behaves.}. Much the same limitation applies when you run DOS -executables on other systems such as MS-Windows. - -@vindex dos-codepage - For multibyte operation on MS-DOS, Emacs needs to know which -characters the chosen DOS codepage can display. So it queries the -system shortly after startup to get the chosen codepage number, and -stores the number in the variable @code{dos-codepage}. Some systems -return the default value 437 for the current codepage, even though the -actual codepage is different. (This typically happens when you use the -codepage built into the display hardware.) You can specify a different -codepage for Emacs to use by setting the variable @code{dos-codepage} in -your init file. - -@cindex language environment, automatic selection on @r{MS-DOS} - Multibyte Emacs supports only certain DOS codepages: those which can -display Far-Eastern scripts, like the Japanese codepage 932, and those -that encode a single ISO 8859 character set. - - The Far-Eastern codepages can directly display one of the MULE -character sets for these countries, so Emacs simply sets up to use the -appropriate terminal coding system that is supported by the codepage. -The special features described in the rest of this section mostly -pertain to codepages that encode ISO 8859 character sets. - - For the codepages that correspond to one of the ISO character sets, -Emacs knows the character set based on the codepage number. Emacs -automatically creates a coding system to support reading and writing -files that use the current codepage, and uses this coding system by -default. The name of this coding system is @code{cp@var{nnn}}, where -@var{nnn} is the codepage number.@footnote{The standard Emacs coding -systems for ISO 8859 are not quite right for the purpose, because -typically the DOS codepage does not match the standard ISO character -codes. For example, the letter @samp{@,{c}} (@samp{c} with cedilla) has -code 231 in the standard Latin-1 character set, but the corresponding -DOS codepage 850 uses code 135 for this glyph.} - -@cindex mode line @r{(MS-DOS)} - All the @code{cp@var{nnn}} coding systems use the letter @samp{D} -(for ``DOS'') as their mode-line mnemonic. Since both the terminal -coding system and the default coding system for file I/O are set to -the proper @code{cp@var{nnn}} coding system at startup, it is normal -for the mode line on MS-DOS to begin with @samp{-DD\-}. -@iftex -@xref{Mode Line,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Mode Line}. -@end ifnottex -Far-Eastern DOS terminals do not use the @code{cp@var{nnn}} coding -systems, and thus their initial mode line looks like the Emacs -default. - - Since the codepage number also indicates which script you are using, -Emacs automatically runs @code{set-language-environment} to select the -language environment for that script -@iftex -(@pxref{Language Environments,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Language Environments}). -@end ifnottex - - If a buffer contains a character belonging to some other ISO 8859 -character set, not the one that the chosen DOS codepage supports, Emacs -displays it using a sequence of @acronym{ASCII} characters. For example, if the -current codepage doesn't have a glyph for the letter @samp{@`o} (small -@samp{o} with a grave accent), it is displayed as @samp{@{`o@}}, where -the braces serve as a visual indication that this is a single character. -(This may look awkward for some non-Latin characters, such as those from -Greek or Hebrew alphabets, but it is still readable by a person who -knows the language.) Even though the character may occupy several -columns on the screen, it is really still just a single character, and -all Emacs commands treat it as one. - -@cindex MS-Windows codepages - MS-Windows provides its own codepages, which are different from the -DOS codepages for the same locale. For example, DOS codepage 850 -supports the same character set as Windows codepage 1252; DOS codepage -855 supports the same character set as Windows codepage 1251, etc. -The MS-Windows version of Emacs uses the current codepage for display -when invoked with the @samp{-nw} option. - -@node MS-DOS Processes -@subsection Subprocesses on MS-DOS - -@cindex compilation under MS-DOS -@cindex inferior processes under MS-DOS -@findex compile @r{(MS-DOS)} -@findex grep @r{(MS-DOS)} - Because MS-DOS is a single-process ``operating system'', -asynchronous subprocesses are not available. In particular, Shell -mode and its variants do not work. Most Emacs features that use -asynchronous subprocesses also don't work on MS-DOS, including -Shell mode and GUD. When in doubt, try and see; commands that -don't work output an error message saying that asynchronous processes -aren't supported. - - Compilation under Emacs with @kbd{M-x compile}, searching files with -@kbd{M-x grep} and displaying differences between files with @kbd{M-x -diff} do work, by running the inferior processes synchronously. This -means you cannot do any more editing until the inferior process -finishes. - - Spell checking also works, by means of special support for synchronous -invocation of the @code{ispell} program. This is slower than the -asynchronous invocation on other platforms - - Instead of the Shell mode, which doesn't work on MS-DOS, you can use -the @kbd{M-x eshell} command. This invokes the Eshell package that -implements a Posix-like shell entirely in Emacs Lisp. - - By contrast, Emacs compiled as a native Windows application -@strong{does} support asynchronous subprocesses. -@iftex -@xref{Windows Processes,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Windows Processes}. -@end ifnottex - -@cindex printing under MS-DOS - Printing commands, such as @code{lpr-buffer} -@iftex -(@pxref{Printing,,,emacs, the Emacs Manual}) and -@code{ps-print-buffer} (@pxref{PostScript,,,emacs, the Emacs Manual}), -work in MS-DOS by sending the output to one of the printer ports. -@xref{MS-DOS Printing,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}), -work in MS-DOS by sending the output to one of the printer ports. -@xref{MS-DOS Printing}. -@end ifnottex - - When you run a subprocess synchronously on MS-DOS, make sure the -program terminates and does not try to read keyboard input. If the -program does not terminate on its own, you will be unable to terminate -it, because MS-DOS provides no general way to terminate a process. -Pressing @kbd{C-c} or @kbd{C-@key{BREAK}} might sometimes help in these -cases. - - Accessing files on other machines is not supported on MS-DOS. Other -network-oriented commands such as sending mail, Web browsing, remote -login, etc., don't work either, unless network access is built into -MS-DOS with some network redirector. - -@cindex directory listing on MS-DOS -@vindex dired-listing-switches @r{(MS-DOS)} - Dired on MS-DOS uses the @code{ls-lisp} package -@iftex -(@pxref{ls in Lisp,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{ls in Lisp}). -@end ifnottex -Therefore, Dired on MS-DOS supports only some of the possible options -you can mention in the @code{dired-listing-switches} variable. The -options that work are @samp{-A}, @samp{-a}, @samp{-c}, @samp{-i}, -@samp{-r}, @samp{-S}, @samp{-s}, @samp{-t}, and @samp{-u}. diff --git a/doc/emacs/msdog.texi b/doc/emacs/msdog.texi deleted file mode 100644 index 96a919cfaf8..00000000000 --- a/doc/emacs/msdog.texi +++ /dev/null @@ -1,1021 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Microsoft Windows, Manifesto, Mac OS / GNUstep, Top -@appendix Emacs and Microsoft Windows/MS-DOS -@cindex Microsoft Windows -@cindex MS-Windows, Emacs peculiarities - - This section describes peculiarities of using Emacs on Microsoft -Windows. Some of these peculiarities are also relevant to Microsoft's -older MS-DOS ``operating system'' (also known as ``MS-DOG''). -However, Emacs features that are relevant @emph{only} to MS-DOS are -described in a separate -@iftex -manual (@pxref{MS-DOS,,, emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -section (@pxref{MS-DOS}). -@end ifnottex - - - The behavior of Emacs on MS-Windows is reasonably similar to what is -documented in the rest of the manual, including support for long file -names, multiple frames, scroll bars, mouse menus, and subprocesses. -However, a few special considerations apply, and they are described -here. - -@menu -* Windows Startup:: How to start Emacs on Windows. -* Text and Binary:: Text files use CRLF to terminate lines. -* Windows Files:: File-name conventions on Windows. -* ls in Lisp:: Emulation of @code{ls} for Dired. -* Windows HOME:: Where Emacs looks for your @file{.emacs} and - where it starts up. -* Windows Keyboard:: Windows-specific keyboard features. -* Windows Mouse:: Windows-specific mouse features. -* Windows Processes:: Running subprocesses on Windows. -* Windows Printing:: How to specify the printer on MS-Windows. -* Windows Fonts:: Specifying fonts on MS-Windows. -* Windows Misc:: Miscellaneous Windows features. -@ifnottex -* MS-DOS:: Using Emacs on MS-DOS. -@end ifnottex -@end menu - -@node Windows Startup -@section How to Start Emacs on MS-Windows -@cindex starting Emacs on MS-Windows - - There are several ways of starting Emacs on MS-Windows: - -@enumerate -@item -@pindex runemacs.exe -@cindex desktop shortcut, MS-Windows -@cindex start directory, MS-Windows -@cindex directory where Emacs starts on MS-Windows -From the desktop shortcut icon: either double-click the left mouse -button on the icon, or click once, then press @key{RET}. The desktop -shortcut should specify as its ``Target'' (in the ``Properties'' of -the shortcut) the full absolute file name of @file{runemacs.exe}, -@emph{not} of @file{emacs.exe}. This is because @file{runemacs.exe} -hides the console window that would have been created if the target of -the shortcut were @file{emacs.exe} (which is a console program, as far -as Windows is concerned). If you use this method, Emacs starts in the -directory specified by the shortcut. To control where that is, -right-click on the shortcut, select ``Properties'', and in the -``Shortcut'' tab modify the ``Start in'' field to your liking. - -@item -From the Command Prompt window, by typing @kbd{emacs @key{RET}} at the -prompt. The Command Prompt window where you did that will not be -available for invoking other commands until Emacs exits. In this -case, Emacs will start in the current directory of the Windows shell. - -@item -From the Command Prompt window, by typing @kbd{runemacs @key{RET}} at -the prompt. The Command Prompt window where you did that will be -immediately available for invoking other commands. In this case, -Emacs will start in the current directory of the Windows shell. - -@item -@cindex invoking Emacs from Windows Explorer -@pindex emacsclient.exe -@pindex emacsclientw.exe -Via @file{emacsclient.exe} or @file{emacsclientw.exe}, which allow you -to invoke Emacs from other programs, and to reuse a running Emacs -process for serving editing jobs required by other programs. -@xref{Emacs Server}. The difference between @file{emacsclient.exe} -and @file{emacsclientw.exe} is that the former is a console program, -while the latter is a Windows GUI program. Both programs wait for -Emacs to signal that the editing job is finished, before they exit and -return control to the program that invoked them. Which one of them to -use in each case depends on the expectations of the program that needs -editing services. If that program is itself a console (text-mode) -program, you should use @file{emacsclient.exe}, so that any of its -messages and prompts appear in the same command window as those of the -invoking program. By contrast, if the invoking program is a GUI -program, you will be better off using @file{emacsclientw.exe}, because -@file{emacsclient.exe} will pop up a command window if it is invoked -from a GUI program. A notable situation where you would want -@file{emacsclientw.exe} is when you right-click on a file in the -Windows Explorer and select ``Open With'' from the pop-up menu. Use -the @samp{--alternate-editor=} or @samp{-a} options if Emacs might not -be running (or not running as a server) when @command{emacsclient} is -invoked---that will always give you an editor. When invoked via -@command{emacsclient}, Emacs will start in the current directory of -the program that invoked @command{emacsclient}. -@end enumerate - -@cindex emacsclient, on MS-Windows -Note that, due to limitations of MS-Windows, Emacs cannot have both -GUI and text-mode frames in the same session. It also cannot open -text-mode frames on more than a single @dfn{Command Prompt} window, -because each Windows program can have only one console at any given -time. For these reasons, if you invoke @command{emacsclient} with the -@option{-c} option, and the Emacs server runs in a text-mode session, -Emacs will always create a new text-mode frame in the same -@dfn{Command Prompt} window where it was started; a GUI frame will be -created only if the server runs in a GUI session. Similarly, if you -invoke @command{emacsclient} with the @option{-t} option, Emacs will -create a GUI frame if the server runs in a GUI session, or a text-mode -frame when the session runs in text mode in a @dfn{Command Prompt} -window. @xref{emacsclient Options}. - -@node Text and Binary -@section Text Files and Binary Files -@cindex text and binary files on MS-DOS/MS-Windows - - GNU Emacs uses newline characters to separate text lines. This is the -convention used on GNU, Unix, and other Posix-compliant systems. - -@cindex end-of-line conversion on MS-DOS/MS-Windows - By contrast, MS-DOS and MS-Windows normally use carriage-return linefeed, -a two-character sequence, to separate text lines. (Linefeed is the same -character as newline.) Therefore, convenient editing of typical files -with Emacs requires conversion of these end-of-line (EOL) sequences. -And that is what Emacs normally does: it converts carriage-return -linefeed into newline when reading files, and converts newline into -carriage-return linefeed when writing files. The same mechanism that -handles conversion of international character codes does this conversion -also (@pxref{Coding Systems}). - -@cindex cursor location, on MS-DOS -@cindex point location, on MS-DOS - One consequence of this special format-conversion of most files is -that character positions as reported by Emacs (@pxref{Position Info}) do -not agree with the file size information known to the operating system. - - In addition, if Emacs recognizes from a file's contents that it uses -newline rather than carriage-return linefeed as its line separator, it -does not perform EOL conversion when reading or writing that file. -Thus, you can read and edit files from GNU and Unix systems on MS-DOS -with no special effort, and they will retain their Unix-style -end-of-line convention after you edit them. - - The mode line indicates whether end-of-line translation was used for -the current buffer. If MS-DOS end-of-line translation is in use for the -buffer, the MS-Windows build of Emacs displays a backslash @samp{\} after -the coding system mnemonic near the beginning of the mode line -(@pxref{Mode Line}). If no EOL translation was performed, the string -@samp{(Unix)} is displayed instead of the backslash, to alert you that the -file's EOL format is not the usual carriage-return linefeed. - -@cindex DOS-to-Unix conversion of files - To visit a file and specify whether it uses DOS-style or Unix-style -end-of-line, specify a coding system (@pxref{Text Coding}). For -example, @kbd{C-x @key{RET} c unix @key{RET} C-x C-f foobar.txt} -visits the file @file{foobar.txt} without converting the EOLs; if some -line ends with a carriage-return linefeed pair, Emacs will display -@samp{^M} at the end of that line. Similarly, you can direct Emacs to -save a buffer in a specified EOL format with the @kbd{C-x @key{RET} f} -command. For example, to save a buffer with Unix EOL format, type -@kbd{C-x @key{RET} f unix @key{RET} C-x C-s}. If you visit a file -with DOS EOL conversion, then save it with Unix EOL format, that -effectively converts the file to Unix EOL style, like the -@code{dos2unix} program. - -@cindex untranslated file system -@findex add-untranslated-filesystem - When you use NFS, Samba, or some other similar method to access file -systems that reside on computers using GNU or Unix systems, Emacs -should not perform end-of-line translation on any files in these file -systems---not even when you create a new file. To request this, -designate these file systems as @dfn{untranslated} file systems by -calling the function @code{add-untranslated-filesystem}. It takes one -argument: the file system name, including a drive letter and -optionally a directory. For example, - -@example -(add-untranslated-filesystem "Z:") -@end example - -@noindent -designates drive Z as an untranslated file system, and - -@example -(add-untranslated-filesystem "Z:\\foo") -@end example - -@noindent -designates directory @file{\foo} on drive Z as an untranslated file -system. - - Most often you would use @code{add-untranslated-filesystem} in your -@file{.emacs} file, or in @file{site-start.el} so that all the users at -your site get the benefit of it. - -@findex remove-untranslated-filesystem - To countermand the effect of @code{add-untranslated-filesystem}, use -the function @code{remove-untranslated-filesystem}. This function takes -one argument, which should be a string just like the one that was used -previously with @code{add-untranslated-filesystem}. - - Designating a file system as untranslated does not affect character -set conversion, only end-of-line conversion. Essentially, it directs -Emacs to create new files with the Unix-style convention of using -newline at the end of a line. @xref{Coding Systems}. - -@vindex file-name-buffer-file-type-alist -@cindex binary files, on MS-DOS/MS-Windows - Some kinds of files should not be converted at all, because their -contents are not really text. Therefore, Emacs on MS-Windows distinguishes -certain files as @dfn{binary files}. (This distinction is not part of -MS-Windows; it is made by Emacs only.) Binary files include executable -programs, compressed archives, etc. Emacs uses the file name to decide -whether to treat a file as binary: the variable -@code{file-name-buffer-file-type-alist} defines the file-name patterns -that indicate binary files. If a file name matches one of the patterns -for binary files (those whose associations are of the type -@code{(@var{pattern} . t)}, Emacs reads and writes that file using the -@code{no-conversion} coding system (@pxref{Coding Systems}) which turns -off @emph{all} coding-system conversions, not only the EOL conversion. -@code{file-name-buffer-file-type-alist} also includes file-name patterns -for files which are known to be Windows-style text files with -carriage-return linefeed EOL format, such as @file{CONFIG.SYS}; Emacs -always writes those files with Windows-style EOLs. - - If a file that belongs to an untranslated file system matches one of -the file-name patterns in @code{file-name-buffer-file-type-alist}, the -EOL conversion is determined by @code{file-name-buffer-file-type-alist}. - -@node Windows Files -@section File Names on MS-Windows -@cindex file names on MS-Windows - - MS-Windows and MS-DOS normally use a backslash, @samp{\}, to -separate name units within a file name, instead of the slash used on -other systems. Emacs on MS-DOS/MS-Windows permits use of either slash or -backslash, and also knows about drive letters in file names. - -@cindex file-name completion, on MS-Windows - On MS-DOS/MS-Windows, file names are case-insensitive, so Emacs by -default ignores letter-case in file names during completion. - -@vindex w32-get-true-file-attributes - The variable @code{w32-get-true-file-attributes} controls whether -Emacs should issue additional system calls to determine more -accurately file attributes in primitives like @code{file-attributes} -and @code{directory-files-and-attributes}. These additional calls are -needed to report correct file ownership, link counts and file types -for special files such as pipes. Without these system calls, file -ownership will be attributed to the current user, link counts will be -always reported as 1, and special files will be reported as regular -files. - - If the value of this variable is @code{local} (the default), Emacs -will issue these additional system calls only for files on local fixed -drives. Any other non-@code{nil} value means do this even for -removable and remote volumes, where this could potentially slow down -Dired and other related features. The value of @code{nil} means never -issue those system calls. Non-@code{nil} values are more useful on -NTFS volumes, which support hard links and file security, than on FAT, -FAT32, and XFAT volumes. - -@node ls in Lisp -@section Emulation of @code{ls} on MS-Windows -@cindex Dired, and MS-Windows/MS-DOS -@cindex @code{ls} emulation - - Dired normally uses the external program @code{ls} -to produce the directory listing displayed in Dired -buffers (@pxref{Dired}). However, MS-Windows and MS-DOS systems don't -come with such a program, although several ports of @sc{gnu} @code{ls} -are available. Therefore, Emacs on those systems @emph{emulates} -@code{ls} in Lisp, by using the @file{ls-lisp.el} package. While -@file{ls-lisp.el} provides a reasonably full emulation of @code{ls}, -there are some options and features peculiar to that emulation; -@iftex -for more details, see the documentation of the variables whose names -begin with @code{ls-lisp}. -@end iftex -@ifnottex -they are described in this section. - - The @code{ls} emulation supports many of the @code{ls} switches, but -it doesn't support all of them. Here's the list of the switches it -does support: @option{-A}, @option{-a}, @option{-B}, @option{-C}, -@option{-c}, @option{-G}, @option{-g}, @option{-h}, @option{-i}, @option{-n}, -@option{-R}, @option{-r}, @option{-S}, @option{-s}, @option{-t}, @option{-U}, -@option{-u}, and @option{-X}. The @option{-F} switch is partially -supported (it appends the character that classifies the file, but does -not prevent symlink following). - -@vindex ls-lisp-use-insert-directory-program - On MS-Windows and MS-DOS, @file{ls-lisp.el} is preloaded when Emacs -is built, so the Lisp emulation of @code{ls} is always used on those -platforms. If you have a ported @code{ls}, setting -@code{ls-lisp-use-insert-directory-program} to a non-@code{nil} value -will revert to using an external program named by the variable -@code{insert-directory-program}. - -@vindex ls-lisp-ignore-case - By default, @file{ls-lisp.el} uses a case-sensitive sort order for -the directory listing it produces; this is so the listing looks the -same as on other platforms. If you wish that the files be sorted in -case-insensitive order, set the variable @code{ls-lisp-ignore-case} to -a non-@code{nil} value. - -@vindex ls-lisp-dirs-first - By default, files and subdirectories are sorted together, to emulate -the behavior of @code{ls}. However, native MS-Windows/MS-DOS file -managers list the directories before the files; if you want that -behavior, customize the option @code{ls-lisp-dirs-first} to a -non-@code{nil} value. - -@vindex ls-lisp-verbosity - The variable @code{ls-lisp-verbosity} controls the file attributes -that @file{ls-lisp.el} displays. The value should be a list that -contains one or more of the symbols @code{links}, @code{uid}, and -@code{gid}. @code{links} means display the count of different file -names that are associated with (a.k.a.@: @dfn{links to}) the file's -data; this is only useful on NTFS volumes. @code{uid} means display -the numerical identifier of the user who owns the file. @code{gid} -means display the numerical identifier of the file owner's group. The -default value is @code{(links uid gid)} i.e.@: all the 3 optional -attributes are displayed. - -@vindex ls-lisp-emulation - The variable @code{ls-lisp-emulation} controls the flavor of the -@code{ls} emulation by setting the defaults for the 3 options -described above: @code{ls-lisp-ignore-case}, -@code{ls-lisp-dirs-first}, and @code{ls-lisp-verbosity}. The value of -this option can be one of the following symbols: - -@table @code -@item GNU -@itemx nil -Emulate @sc{gnu} systems; this is the default. This sets -@code{ls-lisp-ignore-case} and @code{ls-lisp-dirs-first} to -@code{nil}, and @code{ls-lisp-verbosity} to @code{(links uid gid)}. -@item UNIX -Emulate Unix systems. Like @code{GNU}, but sets -@code{ls-lisp-verbosity} to @code{(links uid)}. -@item MacOS -Emulate MacOS. Sets @code{ls-lisp-ignore-case} to @code{t}, and -@code{ls-lisp-dirs-first} and @code{ls-lisp-verbosity} to @code{nil}. -@item MS-Windows -Emulate MS-Windows. Sets @code{ls-lisp-ignore-case} and -@code{ls-lisp-dirs-first} to @code{t}, and @code{ls-lisp-verbosity} to -@code{(links)} on Windows NT/2K/XP/2K3 and to @code{nil} on Windows 9X. -Note that the default emulation is @emph{not} @code{MS-Windows}, even -on Windows, since many users of Emacs on those platforms prefer the -@sc{gnu} defaults. -@end table - -@noindent -Any other value of @code{ls-lisp-emulation} means the same as @code{GNU}. -Customizing this option calls the function @code{ls-lisp-set-options} to -update the 3 dependent options as needed. If you change the value of -this variable without using customize after @file{ls-lisp.el} is loaded -(note that it is preloaded on MS-Windows and MS-DOS), you can call that -function manually for the same result. - -@vindex ls-lisp-support-shell-wildcards - The variable @code{ls-lisp-support-shell-wildcards} controls how -file-name patterns are supported: if it is non-@code{nil} (the -default), they are treated as shell-style wildcards; otherwise they -are treated as Emacs regular expressions. - -@vindex ls-lisp-format-time-list - The variable @code{ls-lisp-format-time-list} defines how to format -the date and time of files. @emph{The value of this variable is -ignored}, unless Emacs cannot determine the current locale. (However, -if the value of @code{ls-lisp-use-localized-time-format} is -non-@code{nil}, Emacs obeys @code{ls-lisp-format-time-list} even if -the current locale is available; see below.) - -The value of @code{ls-lisp-format-time-list} is a list of 2 strings. -The first string is used if the file was modified within the current -year, while the second string is used for older files. In each of -these two strings you can use @samp{%}-sequences to substitute parts -of the time. For example: -@lisp -("%b %e %H:%M" "%b %e %Y") -@end lisp - -@noindent -Note that the strings substituted for these @samp{%}-sequences depend -on the current locale. @xref{Time Parsing,,, elisp, The Emacs Lisp -Reference Manual}, for more about format time specs. - -@vindex ls-lisp-use-localized-time-format - Normally, Emacs formats the file time stamps in either traditional -or ISO-style time format. However, if the value of the variable -@code{ls-lisp-use-localized-time-format} is non-@code{nil}, Emacs -formats file time stamps according to what -@code{ls-lisp-format-time-list} specifies. The @samp{%}-sequences in -@code{ls-lisp-format-time-list} produce locale-dependent month and day -names, which might cause misalignment of columns in Dired display. -@end ifnottex - -@node Windows HOME -@section HOME and Startup Directories on MS-Windows -@cindex @code{HOME} directory on MS-Windows - - The Windows equivalent of the @code{HOME} directory is the -@dfn{user-specific application data directory}. The actual location -depends on the Windows version; typical values are @file{C:\Documents -and Settings\@var{username}\Application Data} on Windows 2K/XP/2K3, -@file{C:\Users\@var{username}\AppData\Roaming} on Windows Vista/7/2K8, -and either @file{C:\WINDOWS\Application Data} or -@file{C:\WINDOWS\Profiles\@var{username}\Application Data} on the -older Windows 9X/ME systems. If this directory does not exist or -cannot be accessed, Emacs falls back to @file{C:\} as the default -value of @code{HOME}. - - You can override this default value of @code{HOME} by explicitly -setting the environment variable @env{HOME} to point to any directory -on your system. @env{HOME} can be set either from the command shell -prompt or from @samp{Properties} dialog of @samp{My Computer}. -@code{HOME} can also be set in the system registry, -@pxref{MS-Windows Registry}. - - For compatibility with older versions of Emacs@footnote{ -Older versions of Emacs didn't check the application data directory. -}, if there is a file named @file{.emacs} in @file{C:\}, the root -directory of drive @file{C:}, and @env{HOME} is set neither in the -environment nor in the Registry, Emacs will treat @file{C:\} as the -default @code{HOME} location, and will not look in the application -data directory, even if it exists. Note that only @file{.emacs} is -looked for in @file{C:\}; the older name @file{_emacs} (see below) is -not. This use of @file{C:\.emacs} to define @code{HOME} is -deprecated. - - Whatever the final place is, Emacs sets the internal value of the -@env{HOME} environment variable to point to it, and it will use that -location for other files and directories it normally looks for or -creates in your home directory. - - You can always find out what Emacs thinks is your home directory's -location by typing @kbd{C-x d ~/ @key{RET}}. This should present the -list of files in the home directory, and show its full name on the -first line. Likewise, to visit your init file, type @kbd{C-x C-f -~/.emacs @key{RET}} (assuming the file's name is @file{.emacs}). - -@cindex init file @file{.emacs} on MS-Windows - The home directory is where your init file is stored. It can have -any name mentioned in @ref{Init File}. - -@cindex @file{_emacs} init file, MS-Windows - Because MS-DOS does not allow file names with leading dots, and -older Windows systems made it hard to create files with such names, -the Windows port of Emacs supports an init file name @file{_emacs}, if -such a file exists in the home directory and @file{.emacs} does not. -This name is considered obsolete. - -@node Windows Keyboard -@section Keyboard Usage on MS-Windows -@cindex keyboard, MS-Windows - - This section describes the Windows-specific features related to -keyboard input in Emacs. - -@cindex MS-Windows keyboard shortcuts - Many key combinations (known as ``keyboard shortcuts'') that have -conventional uses in MS-Windows programs conflict with traditional -Emacs key bindings. (These Emacs key bindings were established years -before Microsoft was founded.) Examples of conflicts include -@kbd{C-c}, @kbd{C-x}, @kbd{C-z}, @kbd{C-a}, and @kbd{W-@key{SPC}}. -You can redefine some of them with meanings more like the MS-Windows -meanings by enabling CUA Mode (@pxref{CUA Bindings}). - -@kindex F10 @r{(MS-Windows)} -@cindex menu bar access using keyboard @r{(MS-Windows)} - The @key{F10} key on Windows activates the menu bar in a way that -makes it possible to use the menus without a mouse. In this mode, the -arrow keys traverse the menus, @key{RET} selects a highlighted menu -item, and @key{ESC} closes the menu. - -@iftex -@inforef{Windows Keyboard, , emacs}, for information about additional -Windows-specific variables in this category. -@end iftex -@ifnottex -@vindex w32-alt-is-meta -@cindex @code{Alt} key (MS-Windows) - By default, the key labeled @key{Alt} is mapped as the @key{META} -key. If you wish it to produce the @code{Alt} modifier instead, set -the variable @code{w32-alt-is-meta} to a @code{nil} value. - -@findex w32-register-hot-key -@findex w32-unregister-hot-key - MS-Windows reserves certain key combinations, such as -@kbd{Alt-@key{TAB}}, for its own use. These key combinations are -intercepted by the system before Emacs can see them. You can use the -@code{w32-register-hot-key} function to allow a key sequence to be -seen by Emacs instead of being grabbed by Windows. This functions -registers a key sequence as a @dfn{hot key}, overriding the special -meaning of that key sequence for Windows. (MS-Windows is told that -the key sequence is a hot key only when one of the Emacs windows has -focus, so that the special keys still have their usual meaning for -other Windows applications.) - - The argument to @code{w32-register-hot-key} must be a single key, -with or without modifiers, in vector form that would be acceptable to -@code{define-key}. The meta modifier is interpreted as the @key{ALT} -key if @code{w32-alt-is-meta} is @code{t} (the default), and the hyper -modifier is always interpreted as the Windows key (usually labeled -with @key{start} and the Windows logo). If the function succeeds in -registering the key sequence, it returns the hotkey ID, a number; -otherwise it returns @code{nil}. - -@kindex M-TAB@r{, (MS-Windows)} -@cindex @kbd{M-@key{TAB}} vs @kbd{Alt-@key{TAB}} (MS-Windows) -@cindex @kbd{Alt-@key{TAB}} vs @kbd{M-@key{TAB}} (MS-Windows) - For example, @code{(w32-register-hot-key [M-tab])} lets you use -@kbd{M-TAB} normally in Emacs; for instance, to complete the word or -symbol at point at top level, or to complete the current search string -against previously sought strings during incremental search. - - The function @code{w32-unregister-hot-key} reverses the effect of -@code{w32-register-hot-key} for its argument key sequence. - -@vindex w32-capslock-is-shiftlock - By default, the @key{CapsLock} key only affects normal character -keys (it converts lower-case characters to their upper-case -variants). However, if you set the variable -@code{w32-capslock-is-shiftlock} to a non-@code{nil} value, the -@key{CapsLock} key will affect non-character keys as well, as if you -pressed the @key{Shift} key while typing the non-character key. - -@vindex w32-enable-caps-lock - If the variable @code{w32-enable-caps-lock} is set to a @code{nil} -value, the @key{CapsLock} key produces the symbol @code{capslock} -instead of the shifted version of they keys. The default value is -@code{t}. - -@vindex w32-enable-num-lock -@cindex keypad keys (MS-Windows) - Similarly, if @code{w32-enable-num-lock} is @code{nil}, the -@key{NumLock} key will produce the symbol @code{kp-numlock}. The -default is @code{t}, which causes @key{NumLock} to work as expected: -toggle the meaning of the keys on the numeric keypad. -@end ifnottex - -@vindex w32-apps-modifier - The variable @code{w32-apps-modifier} controls the effect of the -@key{Apps} key (usually located between the right @key{Alt} and the -right @key{Ctrl} keys). Its value can be one of the symbols -@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control}, -or @code{shift} for the respective modifier, or @code{nil} to appear -as the key @code{apps}. The default is @code{nil}. - -@vindex w32-lwindow-modifier -@vindex w32-rwindow-modifier -@vindex w32-scroll-lock-modifier - The variable @code{w32-lwindow-modifier} determines the effect of -the left Windows key (usually labeled with @key{start} and the Windows -logo). If its value is @code{nil} (the default), the key will produce -the symbol @code{lwindow}. Setting it to one of the symbols -@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control}, -or @code{shift} will produce the respective modifier. A similar -variable @code{w32-rwindow-modifier} controls the effect of the right -Windows key, and @code{w32-scroll-lock-modifier} does the same for the -@key{ScrLock} key. If these variables are set to @code{nil}, the -right Windows key produces the symbol @code{rwindow} and @key{ScrLock} -produces the symbol @code{scroll}. - -@vindex w32-pass-alt-to-system -@cindex Windows system menu -@cindex @code{Alt} key invokes menu (Windows) - Emacs compiled as a native Windows application normally turns off -the Windows feature that tapping the @key{ALT} key invokes the Windows -menu. The reason is that the @key{ALT} serves as @key{META} in Emacs. -When using Emacs, users often press the @key{META} key temporarily and -then change their minds; if this has the effect of bringing up the -Windows menu, it alters the meaning of subsequent commands. Many -users find this frustrating. - - You can re-enable Windows's default handling of tapping the @key{ALT} -key by setting @code{w32-pass-alt-to-system} to a non-@code{nil} -value. - -@ifnottex -@vindex w32-pass-lwindow-to-system -@vindex w32-pass-rwindow-to-system - The variables @code{w32-pass-lwindow-to-system} and -@code{w32-pass-rwindow-to-system} determine whether the respective -keys are passed to Windows or swallowed by Emacs. If the value is -@code{nil}, the respective key is silently swallowed by Emacs, -otherwise it is passed to Windows. The default is @code{t} for both -of these variables. Passing each of these keys to Windows produces -its normal effect: for example, @kbd{@key{Lwindow}} opens the -@code{Start} menu, etc.@footnote{ -Some combinations of the ``Windows'' keys with other keys are caught -by Windows at a low level in a way that Emacs currently cannot prevent. -For example, @kbd{@key{Lwindow} r} always pops up the Windows -@samp{Run} dialog. Customizing the value of -@code{w32-phantom-key-code} might help in some cases, though.} - -@vindex w32-recognize-altgr -@kindex AltGr @r{(MS-Windows)} -@cindex AltGr key (MS-Windows) - The variable @code{w32-recognize-altgr} controls whether the -@key{AltGr} key (if it exists on your keyboard), or its equivalent, -the combination of the right @key{Alt} and left @key{Ctrl} keys -pressed together, is recognized as the @key{AltGr} key. The default -is @code{t}, which means these keys produce @code{AltGr}; setting it -to @code{nil} causes @key{AltGr} or the equivalent key combination to -be interpreted as the combination of @key{CTRL} and @key{META} -modifiers. -@end ifnottex - -@node Windows Mouse -@section Mouse Usage on MS-Windows -@cindex mouse, and MS-Windows - - This section describes the Windows-specific variables related to -the mouse. - -@vindex w32-mouse-button-tolerance -@cindex simulation of middle mouse button - The variable @code{w32-mouse-button-tolerance} specifies the -time interval, in milliseconds, for faking middle mouse button press -on 2-button mice. If both mouse buttons are depressed within this -time interval, Emacs generates a middle mouse button click event -instead of a double click on one of the buttons. - -@vindex w32-pass-extra-mouse-buttons-to-system - If the variable @code{w32-pass-extra-mouse-buttons-to-system} is -non-@code{nil}, Emacs passes the fourth and fifth mouse buttons to -Windows. - -@vindex w32-swap-mouse-buttons - The variable @code{w32-swap-mouse-buttons} controls which of the 3 -mouse buttons generates the @kbd{mouse-2} events. When it is -@code{nil} (the default), the middle button generates @kbd{mouse-2} -and the right button generates @kbd{mouse-3} events. If this variable -is non-@code{nil}, the roles of these two buttons are reversed. - -@node Windows Processes -@section Subprocesses on Windows 9X/ME and Windows NT/2K/XP -@cindex subprocesses on MS-Windows - -@cindex DOS applications, running from Emacs - Emacs compiled as a native Windows application (as opposed to the DOS -version) includes full support for asynchronous subprocesses. -In the Windows version, synchronous and asynchronous subprocesses work -fine on both -Windows 9X/ME and Windows NT/2K/XP as long as you run only 32-bit Windows -applications. However, when you run a DOS application in a subprocess, -you may encounter problems or be unable to run the application at all; -and if you run two DOS applications at the same time in two -subprocesses, you may have to reboot your system. - -Since the standard command interpreter (and most command line utilities) -on Windows 9X are DOS applications, these problems are significant when -using that system. But there's nothing we can do about them; only -Microsoft can fix them. - -If you run just one DOS application subprocess, the subprocess should -work as expected as long as it is ``well-behaved'' and does not perform -direct screen access or other unusual actions. If you have a CPU -monitor application, your machine will appear to be 100% busy even when -the DOS application is idle, but this is only an artifact of the way CPU -monitors measure processor load. - -You must terminate the DOS application before you start any other DOS -application in a different subprocess. Emacs is unable to interrupt or -terminate a DOS subprocess. The only way you can terminate such a -subprocess is by giving it a command that tells its program to exit. - -If you attempt to run two DOS applications at the same time in separate -subprocesses, the second one that is started will be suspended until the -first one finishes, even if either or both of them are asynchronous. - -@cindex kill DOS application -If you can go to the first subprocess, and tell it to exit, the second -subprocess should continue normally. However, if the second subprocess -is synchronous, Emacs itself will be hung until the first subprocess -finishes. If it will not finish without user input, then you have no -choice but to reboot if you are running on Windows 9X. If you are -running on Windows NT/2K/XP, you can use a process viewer application to kill -the appropriate instance of NTVDM instead (this will terminate both DOS -subprocesses). - -If you have to reboot Windows 9X in this situation, do not use the -@code{Shutdown} command on the @code{Start} menu; that usually hangs the -system. Instead, type @kbd{CTL-ALT-@key{DEL}} and then choose -@code{Shutdown}. That usually works, although it may take a few minutes -to do its job. - -@vindex w32-quote-process-args - The variable @code{w32-quote-process-args} controls how Emacs quotes -the process arguments. Non-@code{nil} means quote with the @code{"} -character. If the value is a character, Emacs uses that character to escape -any quote characters that appear; otherwise it chooses a suitable escape -character based on the type of the program. - -@ifnottex -@findex w32-shell-execute - The function @code{w32-shell-execute} can be useful for writing -customized commands that run MS-Windows applications registered to -handle a certain standard Windows operation for a specific type of -document or file. This function is a wrapper around the Windows -@code{ShellExecute} API. See the MS-Windows API documentation for -more details. -@end ifnottex - -@node Windows Printing -@section Printing and MS-Windows - - Printing commands, such as @code{lpr-buffer} (@pxref{Printing}) and -@code{ps-print-buffer} (@pxref{PostScript}) work in MS-DOS and -MS-Windows by sending the output to one of the printer ports, if a -Posix-style @code{lpr} program is unavailable. The same Emacs -variables control printing on all systems, but in some cases they have -different default values on MS-DOS and MS-Windows. - - Emacs on MS Windows attempts to determine your default printer -automatically (using the function @code{default-printer-name}). -But in some rare cases this can fail, or you may wish to use a different -printer from within Emacs. The rest of this section explains how to -tell Emacs which printer to use. - -@vindex printer-name@r{, (MS-DOS/MS-Windows)} - If you want to use your local printer, then set the Lisp variable -@code{lpr-command} to @code{""} (its default value on Windows) and -@code{printer-name} to the name of the printer port---for example, -@code{"PRN"}, the usual local printer port, or @code{"LPT2"}, or -@code{"COM1"} for a serial printer. You can also set -@code{printer-name} to a file name, in which case ``printed'' output -is actually appended to that file. If you set @code{printer-name} to -@code{"NUL"}, printed output is silently discarded (sent to the system -null device). - - You can also use a printer shared by another machine by setting -@code{printer-name} to the UNC share name for that printer---for -example, @code{"//joes_pc/hp4si"}. (It doesn't matter whether you use -forward slashes or backslashes here.) To find out the names of shared -printers, run the command @samp{net view} from the command prompt to -obtain a list of servers, and @samp{net view @var{server-name}} to see -the names of printers (and directories) shared by that server. -Alternatively, click the @samp{Network Neighborhood} icon on your -desktop, and look for machines that share their printers via the -network. - -@cindex @samp{net use}, and printing on MS-Windows -@cindex networked printers (MS-Windows) - If the printer doesn't appear in the output of @samp{net view}, or -if setting @code{printer-name} to the UNC share name doesn't produce a -hardcopy on that printer, you can use the @samp{net use} command to -connect a local print port such as @code{"LPT2"} to the networked -printer. For example, typing @kbd{net use LPT2: \\joes_pc\hp4si}@footnote{ -Note that the @samp{net use} command requires the UNC share name to be -typed with the Windows-style backslashes, while the value of -@code{printer-name} can be set with either forward- or backslashes.} -causes Windows to @dfn{capture} the @code{LPT2} port and redirect the -printed material to the printer connected to the machine @code{joes_pc}. -After this command, setting @code{printer-name} to @code{"LPT2"} -should produce the hardcopy on the networked printer. - - With some varieties of Windows network software, you can instruct -Windows to capture a specific printer port such as @code{"LPT2"}, and -redirect it to a networked printer via the @w{@code{Control -Panel->Printers}} applet instead of @samp{net use}. - - If you set @code{printer-name} to a file name, it's best to use an -absolute file name. Emacs changes the working directory according to -the default directory of the current buffer, so if the file name in -@code{printer-name} is relative, you will end up with several such -files, each one in the directory of the buffer from which the printing -was done. - - If the value of @code{printer-name} is correct, but printing does -not produce the hardcopy on your printer, it is possible that your -printer does not support printing plain text (some cheap printers omit -this functionality). In that case, try the PostScript print commands, -described below. - -@findex print-buffer @r{(MS-DOS)} -@findex print-region @r{(MS-DOS)} -@vindex lpr-headers-switches @r{(MS-DOS)} - The commands @code{print-buffer} and @code{print-region} call the -@code{pr} program, or use special switches to the @code{lpr} program, to -produce headers on each printed page. MS-DOS and MS-Windows don't -normally have these programs, so by default, the variable -@code{lpr-headers-switches} is set so that the requests to print page -headers are silently ignored. Thus, @code{print-buffer} and -@code{print-region} produce the same output as @code{lpr-buffer} and -@code{lpr-region}, respectively. If you do have a suitable @code{pr} -program (for example, from GNU Coreutils), set -@code{lpr-headers-switches} to @code{nil}; Emacs will then call -@code{pr} to produce the page headers, and print the resulting output as -specified by @code{printer-name}. - -@vindex print-region-function @r{(MS-DOS)} -@cindex lpr usage under MS-DOS -@vindex lpr-command @r{(MS-DOS)} -@vindex lpr-switches @r{(MS-DOS)} - Finally, if you do have an @code{lpr} work-alike, you can set the -variable @code{lpr-command} to @code{"lpr"}. Then Emacs will use -@code{lpr} for printing, as on other systems. (If the name of the -program isn't @code{lpr}, set @code{lpr-command} to the appropriate value.) -The variable @code{lpr-switches} has its standard meaning -when @code{lpr-command} is not @code{""}. If the variable -@code{printer-name} has a string value, it is used as the value for the -@code{-P} option to @code{lpr}, as on Unix. - -@findex ps-print-buffer @r{(MS-DOS)} -@findex ps-spool-buffer @r{(MS-DOS)} -@vindex ps-printer-name @r{(MS-DOS)} -@vindex ps-lpr-command @r{(MS-DOS)} -@vindex ps-lpr-switches @r{(MS-DOS)} - A parallel set of variables, @code{ps-lpr-command}, -@code{ps-lpr-switches}, and @code{ps-printer-name} (@pxref{PostScript -Variables}), defines how PostScript files should be printed. These -variables are used in the same way as the corresponding variables -described above for non-PostScript printing. Thus, the value of -@code{ps-printer-name} is used as the name of the device (or file) to -which PostScript output is sent, just as @code{printer-name} is used -for non-PostScript printing. (There are two distinct sets of -variables in case you have two printers attached to two different -ports, and only one of them is a PostScript printer.) - -@cindex Ghostscript, use for PostScript printing - The default value of the variable @code{ps-lpr-command} is @code{""}, -which causes PostScript output to be sent to the printer port specified -by @code{ps-printer-name}; but @code{ps-lpr-command} can also be set to -the name of a program which will accept PostScript files. Thus, if you -have a non-PostScript printer, you can set this variable to the name of -a PostScript interpreter program (such as Ghostscript). Any switches -that need to be passed to the interpreter program are specified using -@code{ps-lpr-switches}. (If the value of @code{ps-printer-name} is a -string, it will be added to the list of switches as the value for the -@code{-P} option. This is probably only useful if you are using -@code{lpr}, so when using an interpreter typically you would set -@code{ps-printer-name} to something other than a string so it is -ignored.) - - For example, to use Ghostscript for printing on the system's default -printer, put this in your @file{.emacs} file: - -@example -(setq ps-printer-name t) -(setq ps-lpr-command "D:/gs6.01/bin/gswin32c.exe") -(setq ps-lpr-switches '("-q" "-dNOPAUSE" "-dBATCH" - "-sDEVICE=mswinpr2" - "-sPAPERSIZE=a4")) -@end example - -@noindent -(This assumes that Ghostscript is installed in the -@file{D:/gs6.01} directory.) - -@node Windows Fonts -@section Specifying Fonts on MS-Windows -@cindex font specification (MS Windows) - - Starting with Emacs 23, fonts are specified by their name, size -and optional properties. The format for specifying fonts comes from the -fontconfig library used in modern Free desktops: - -@example - [Family[-PointSize]][:Option1=Value1[:Option2=Value2[...]]] -@end example - - The old XLFD based format is also supported for backwards compatibility. - -@cindex font backend selection (MS-Windows) - Emacs 23 and later supports a number of font backends. Currently, -the @code{gdi} and @code{uniscribe} backends are supported on Windows. -The @code{gdi} font backend is available on all versions of Windows, -and supports all fonts that are natively supported by Windows. The -@code{uniscribe} font backend is available on Windows 2000 and later, -and supports TrueType and OpenType fonts. Some languages requiring -complex layout can only be properly supported by the Uniscribe -backend. By default, both backends are enabled if supported, with -@code{uniscribe} taking priority over @code{gdi}. To override that -and use the GDI backend even if Uniscribe is available, invoke Emacs -with the @kbd{-xrm Emacs.fontBackend:gdi} command-line argument, or -add a @code{Emacs.fontBackend} resource with the value @code{gdi} in -the Registry under either the -@samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} or the -@samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs} key (@pxref{Resources}). - -@cindex font properties (MS Windows) -@noindent -Optional properties common to all font backends on MS-Windows are: - -@table @code - -@vindex font-weight-table @r{(MS-Windows)} -@item weight -Specifies the weight of the font. Special values @code{light}, -@code{medium}, @code{demibold}, @code{bold}, and @code{black} can be specified -without @code{weight=} (e.g., @kbd{Courier New-12:bold}). Otherwise, -the weight should be a numeric value between 100 and 900, or one of the -named weights in @code{font-weight-table}. If unspecified, a regular font -is assumed. - -@vindex font-slant-table @r{(MS-Windows)} -@item slant -Specifies whether the font is italic. Special values -@code{roman}, @code{italic} and @code{oblique} can be specified -without @code{slant=} (e.g., @kbd{Courier New-12:italic}). -Otherwise, the slant should be a numeric value, or one of the named -slants in @code{font-slant-table}. On Windows, any slant above 150 is -treated as italics, and anything below as roman. - -@item family -Specifies the font family, but normally this will be specified -at the start of the font name. - -@item pixelsize -Specifies the font size in pixels. This can be used instead -of the point size specified after the family name. - -@item adstyle -Specifies additional style information for the font. -On MS-Windows, the values @code{mono}, @code{sans}, @code{serif}, -@code{script} and @code{decorative} are recognized. These are most useful -as a fallback with the font family left unspecified. - -@vindex w32-charset-info-alist -@item registry -Specifies the character set registry that the font is -expected to cover. Most TrueType and OpenType fonts will be Unicode fonts -that cover several national character sets, but you can narrow down the -selection of fonts to those that support a particular character set by -using a specific registry from @code{w32-charset-info-alist} here. - -@item spacing -Specifies how the font is spaced. The @code{p} spacing specifies -a proportional font, and @code{m} or @code{c} specify a monospaced font. - -@item foundry -Not used on Windows, but for informational purposes and to -prevent problems with code that expects it to be set, is set internally to -@code{raster} for bitmapped fonts, @code{outline} for scalable fonts, -or @code{unknown} if the type cannot be determined as one of those. -@end table - -@cindex font properties (MS Windows gdi backend) -Options specific to @code{GDI} fonts: - -@table @code - -@cindex font scripts (MS Windows) -@cindex font Unicode subranges (MS Windows) -@item script -Specifies a Unicode subrange the font should support. - -The following scripts are recognized on Windows: @code{latin}, @code{greek}, -@code{coptic}, @code{cyrillic}, @code{armenian}, @code{hebrew}, @code{arabic}, -@code{syriac}, @code{nko}, @code{thaana}, @code{devanagari}, @code{bengali}, -@code{gurmukhi}, @code{gujarati}, @code{oriya}, @code{tamil}, @code{telugu}, -@code{kannada}, @code{malayam}, @code{sinhala}, @code{thai}, @code{lao}, -@code{tibetan}, @code{myanmar}, @code{georgian}, @code{hangul}, -@code{ethiopic}, @code{cherokee}, @code{canadian-aboriginal}, @code{ogham}, -@code{runic}, @code{khmer}, @code{mongolian}, @code{symbol}, @code{braille}, -@code{han}, @code{ideographic-description}, @code{cjk-misc}, @code{kana}, -@code{bopomofo}, @code{kanbun}, @code{yi}, @code{byzantine-musical-symbol}, -@code{musical-symbol}, and @code{mathematical}. - -@cindex font antialiasing (MS Windows) -@item antialias -Specifies the antialiasing method. The value @code{none} means no -antialiasing, @code{standard} means use standard antialiasing, -@code{subpixel} means use subpixel antialiasing (known as Cleartype on -Windows), and @code{natural} means use subpixel antialiasing with -adjusted spacing between letters. If unspecified, the font will use -the system default antialiasing. -@end table - -@node Windows Misc -@section Miscellaneous Windows-specific features - - This section describes miscellaneous Windows-specific features. - -@vindex w32-use-visible-system-caret -@cindex screen reader software, MS-Windows - The variable @code{w32-use-visible-system-caret} is a flag that -determines whether to make the system caret visible. The default when -no screen reader software is in use is @code{nil}, which means Emacs -draws its own cursor to indicate the position of point. A -non-@code{nil} value means Emacs will indicate point location with the -system caret; this facilitates use of screen reader software, and is -the default when such software is detected when running Emacs. -When this variable is non-@code{nil}, other variables affecting the -cursor display have no effect. - -@iftex -@inforef{Windows Misc, , emacs}, for information about additional -Windows-specific variables in this category. -@end iftex - -@ifnottex -@vindex w32-grab-focus-on-raise -@cindex frame focus policy, MS-Windows - The variable @code{w32-grab-focus-on-raise}, if set to a -non-@code{nil} value causes a frame to grab focus when it is raised. -The default is @code{t}, which fits well with the Windows default -click-to-focus policy. -@end ifnottex - -@ifnottex -@include msdog-xtra.texi -@end ifnottex diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi deleted file mode 100644 index b0b35bf14b5..00000000000 --- a/doc/emacs/mule.texi +++ /dev/null @@ -1,1807 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1997, 1999-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node International, Modes, Frames, Top -@chapter International Character Set Support -@c This node is referenced in the tutorial. When renaming or deleting -@c it, the tutorial needs to be adjusted. (TUTORIAL.de) -@cindex MULE -@cindex international scripts -@cindex multibyte characters -@cindex encoding of characters - -@cindex Celtic -@cindex Chinese -@cindex Cyrillic -@cindex Czech -@cindex Devanagari -@cindex Hindi -@cindex Marathi -@cindex Ethiopic -@cindex German -@cindex Greek -@cindex Hebrew -@cindex IPA -@cindex Japanese -@cindex Korean -@cindex Lao -@cindex Latin -@cindex Polish -@cindex Romanian -@cindex Slovak -@cindex Slovenian -@cindex Thai -@cindex Tibetan -@cindex Turkish -@cindex Vietnamese -@cindex Dutch -@cindex Spanish - Emacs supports a wide variety of international character sets, -including European and Vietnamese variants of the Latin alphabet, as -well as Cyrillic, Devanagari (for Hindi and Marathi), Ethiopic, Greek, -Han (for Chinese and Japanese), Hangul (for Korean), Hebrew, IPA, -Kannada, Lao, Malayalam, Tamil, Thai, Tibetan, and Vietnamese scripts. -Emacs also supports various encodings of these characters that are used by -other internationalized software, such as word processors and mailers. - - Emacs allows editing text with international characters by supporting -all the related activities: - -@itemize @bullet -@item -You can visit files with non-@acronym{ASCII} characters, save non-@acronym{ASCII} text, and -pass non-@acronym{ASCII} text between Emacs and programs it invokes (such as -compilers, spell-checkers, and mailers). Setting your language -environment (@pxref{Language Environments}) takes care of setting up the -coding systems and other options for a specific language or culture. -Alternatively, you can specify how Emacs should encode or decode text -for each command; see @ref{Text Coding}. - -@item -You can display non-@acronym{ASCII} characters encoded by the various -scripts. This works by using appropriate fonts on graphics displays -(@pxref{Defining Fontsets}), and by sending special codes to text -displays (@pxref{Terminal Coding}). If some characters are displayed -incorrectly, refer to @ref{Undisplayable Characters}, which describes -possible problems and explains how to solve them. - -@item -Characters from scripts whose natural ordering of text is from right -to left are reordered for display (@pxref{Bidirectional Editing}). -These scripts include Arabic, Hebrew, Syriac, Thaana, and a few -others. - -@item -You can insert non-@acronym{ASCII} characters or search for them. To do that, -you can specify an input method (@pxref{Select Input Method}) suitable -for your language, or use the default input method set up when you chose -your language environment. If -your keyboard can produce non-@acronym{ASCII} characters, you can select an -appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs -will accept those characters. Latin-1 characters can also be input by -using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}. - -With the X Window System, your locale should be set to an appropriate -value to make sure Emacs interprets keyboard input correctly; see -@ref{Language Environments, locales}. -@end itemize - - The rest of this chapter describes these issues in detail. - -@menu -* International Chars:: Basic concepts of multibyte characters. -* Disabling Multibyte:: Controlling whether to use multibyte characters. -* Language Environments:: Setting things up for the language you use. -* Input Methods:: Entering text characters not on your keyboard. -* Select Input Method:: Specifying your choice of input methods. -* Coding Systems:: Character set conversion when you read and - write files, and so on. -* Recognize Coding:: How Emacs figures out which conversion to use. -* Specify Coding:: Specifying a file's coding system explicitly. -* Output Coding:: Choosing coding systems for output. -* Text Coding:: Choosing conversion to use for file text. -* Communication Coding:: Coding systems for interprocess communication. -* File Name Coding:: Coding systems for file @emph{names}. -* Terminal Coding:: Specifying coding systems for converting - terminal input and output. -* Fontsets:: Fontsets are collections of fonts - that cover the whole spectrum of characters. -* Defining Fontsets:: Defining a new fontset. -* Modifying Fontsets:: Modifying an existing fontset. -* Undisplayable Characters:: When characters don't display. -* Unibyte Mode:: You can pick one European character set - to use without multibyte characters. -* Charsets:: How Emacs groups its internal character codes. -* Bidirectional Editing:: Support for right-to-left scripts. -@end menu - -@node International Chars -@section Introduction to International Character Sets - - The users of international character sets and scripts have -established many more-or-less standard coding systems for storing -files. These coding systems are typically @dfn{multibyte}, meaning -that sequences of two or more bytes are used to represent individual -non-@acronym{ASCII} characters. - -@cindex Unicode - Internally, Emacs uses its own multibyte character encoding, which -is a superset of the @dfn{Unicode} standard. This internal encoding -allows characters from almost every known script to be intermixed in a -single buffer or string. Emacs translates between the multibyte -character encoding and various other coding systems when reading and -writing files, and when exchanging data with subprocesses. - -@kindex C-h h -@findex view-hello-file -@cindex undisplayable characters -@cindex @samp{?} in display - The command @kbd{C-h h} (@code{view-hello-file}) displays the file -@file{etc/HELLO}, which illustrates various scripts by showing -how to say ``hello'' in many languages. If some characters can't be -displayed on your terminal, they appear as @samp{?} or as hollow boxes -(@pxref{Undisplayable Characters}). - - Keyboards, even in the countries where these character sets are -used, generally don't have keys for all the characters in them. You -can insert characters that your keyboard does not support, using -@kbd{C-q} (@code{quoted-insert}) or @kbd{C-x 8 @key{RET}} -(@code{ucs-insert}). @xref{Inserting Text}. Emacs also supports -various @dfn{input methods}, typically one for each script or -language, which make it easier to type characters in the script. -@xref{Input Methods}. - -@kindex C-x RET - The prefix key @kbd{C-x @key{RET}} is used for commands that pertain -to multibyte characters, coding systems, and input methods. - -@kindex C-x = -@findex what-cursor-position - The command @kbd{C-x =} (@code{what-cursor-position}) shows -information about the character at point. In addition to the -character position, which was described in @ref{Position Info}, this -command displays how the character is encoded. For instance, it -displays the following line in the echo area for the character -@samp{c}: - -@smallexample -Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53 -@end smallexample - - The four values after @samp{Char:} describe the character that -follows point, first by showing it and then by giving its character -code in decimal, octal and hex. For a non-@acronym{ASCII} multibyte -character, these are followed by @samp{file} and the character's -representation, in hex, in the buffer's coding system, if that coding -system encodes the character safely and with a single byte -(@pxref{Coding Systems}). If the character's encoding is longer than -one byte, Emacs shows @samp{file ...}. - - As a special case, if the character lies in the range 128 (0200 -octal) through 159 (0237 octal), it stands for a ``raw'' byte that -does not correspond to any specific displayable character. Such a -``character'' lies within the @code{eight-bit-control} character set, -and is displayed as an escaped octal character code. In this case, -@kbd{C-x =} shows @samp{part of display ...} instead of @samp{file}. - -@cindex character set of character at point -@cindex font of character at point -@cindex text properties at point -@cindex face at point - With a prefix argument (@kbd{C-u C-x =}), this command displays a -detailed description of the character in a window: - -@itemize @bullet -@item -The character set name, and the codes that identify the character -within that character set; @acronym{ASCII} characters are identified -as belonging to the @code{ascii} character set. - -@item -The character's syntax and categories. - -@item -The character's encodings, both internally in the buffer, and externally -if you were to save the file. - -@item -What keys to type to input the character in the current input method -(if it supports the character). - -@item -If you are running Emacs on a graphical display, the font name and -glyph code for the character. If you are running Emacs on a text -terminal, the code(s) sent to the terminal. - -@item -The character's text properties (@pxref{Text Properties,,, -elisp, the Emacs Lisp Reference Manual}), including any non-default -faces used to display the character, and any overlays containing it -(@pxref{Overlays,,, elisp, the same manual}). -@end itemize - - Here's an example showing the Latin-1 character A with grave accent, -in a buffer whose coding system is @code{utf-8-unix}: - -@smallexample - position: 1 of 1 (0%), column: 0 - character: @`A (displayed as @`A) (codepoint 192, #o300, #xc0) - preferred charset: unicode (Unicode (ISO10646)) -code point in charset: 0xC0 - syntax: w which means: word - category: .:Base, L:Left-to-right (strong), - j:Japanese, l:Latin, v:Viet - buffer code: #xC3 #x80 - file code: not encodable by coding system undecided-unix - display: by this font (glyph code) - xft:-unknown-DejaVu Sans Mono-normal-normal- - normal-*-13-*-*-*-m-0-iso10646-1 (#x82) - -Character code properties: customize what to show - name: LATIN CAPITAL LETTER A WITH GRAVE - old-name: LATIN CAPITAL LETTER A GRAVE - general-category: Lu (Letter, Uppercase) - decomposition: (65 768) ('A' '`') -@end smallexample - -@c FIXME? Does this section even belong in the user manual? -@c Seems more appropriate to the lispref? -@node Disabling Multibyte -@section Disabling Multibyte Characters - - By default, Emacs starts in multibyte mode: it stores the contents -of buffers and strings using an internal encoding that represents -non-@acronym{ASCII} characters using multi-byte sequences. Multibyte -mode allows you to use all the supported languages and scripts without -limitations. - -@cindex turn multibyte support on or off - Under very special circumstances, you may want to disable multibyte -character support, for a specific buffer. -When multibyte characters are disabled in a buffer, we call -that @dfn{unibyte mode}. In unibyte mode, each character in the -buffer has a character code ranging from 0 through 255 (0377 octal); 0 -through 127 (0177 octal) represent @acronym{ASCII} characters, and 128 -(0200 octal) through 255 (0377 octal) represent non-@acronym{ASCII} -characters. - - To edit a particular file in unibyte representation, visit it using -@code{find-file-literally}. @xref{Visiting}. You can convert a -multibyte buffer to unibyte by saving it to a file, killing the -buffer, and visiting the file again with @code{find-file-literally}. -Alternatively, you can use @kbd{C-x @key{RET} c} -(@code{universal-coding-system-argument}) and specify @samp{raw-text} -as the coding system with which to visit or save a file. @xref{Text -Coding}. Unlike @code{find-file-literally}, finding a file as -@samp{raw-text} doesn't disable format conversion, uncompression, or -auto mode selection. - -@c Not a single file in Emacs uses this feature. Is it really worth -@c mentioning in the _user_ manual? Also, this duplicates somewhat -@c "Loading Non-ASCII" from the lispref. -@cindex Lisp files, and multibyte operation -@cindex multibyte operation, and Lisp files -@cindex unibyte operation, and Lisp files -@cindex init file, and non-@acronym{ASCII} characters - Emacs normally loads Lisp files as multibyte. -This includes the Emacs initialization -file, @file{.emacs}, and the initialization files of packages -such as Gnus. However, you can specify unibyte loading for a -particular Lisp file, by adding an entry @samp{unibyte: t} in a file -local variables section (@pxref{File Variables}). Then that file is -always loaded as unibyte text. Note that this does not represent a -real @code{unibyte} variable, rather it just acts as an indicator -to Emacs in the same way as @code{coding} does (@pxref{Specify Coding}). -@ignore -@c I don't see the point of this statement: -The motivation for these conventions is that it is more reliable to -always load any particular Lisp file in the same way. -@end ignore -Note also that this feature only applies to @emph{loading} Lisp files -for evaluation, not to visiting them for editing. You can also load a -Lisp file as unibyte, on any one occasion, by typing @kbd{C-x -@key{RET} c raw-text @key{RET}} immediately before loading it. - -@c See http://debbugs.gnu.org/11226 for lack of unibyte tooltip. -@vindex enable-multibyte-characters -The buffer-local variable @code{enable-multibyte-characters} is -non-@code{nil} in multibyte buffers, and @code{nil} in unibyte ones. -The mode line also indicates whether a buffer is multibyte or not. -@xref{Mode Line}. With a graphical display, in a multibyte buffer, -the portion of the mode line that indicates the character set has a -tooltip that (amongst other things) says that the buffer is multibyte. -In a unibyte buffer, the character set indicator is absent. Thus, in -a unibyte buffer (when using a graphical display) there is normally -nothing before the indication of the visited file's end-of-line -convention (colon, backslash, etc.), unless you are using an input -method. - -@findex toggle-enable-multibyte-characters -You can turn off multibyte support in a specific buffer by invoking the -command @code{toggle-enable-multibyte-characters} in that buffer. - -@node Language Environments -@section Language Environments -@cindex language environments - - All supported character sets are supported in Emacs buffers whenever -multibyte characters are enabled; there is no need to select a -particular language in order to display its characters. -However, it is important to select a @dfn{language -environment} in order to set various defaults. Roughly speaking, the -language environment represents a choice of preferred script rather -than a choice of language. - - The language environment controls which coding systems to recognize -when reading text (@pxref{Recognize Coding}). This applies to files, -incoming mail, and any other text you read into Emacs. It may also -specify the default coding system to use when you create a file. Each -language environment also specifies a default input method. - -@findex set-language-environment -@vindex current-language-environment - To select a language environment, customize -@code{current-language-environment} or use the command @kbd{M-x -set-language-environment}. It makes no difference which buffer is -current when you use this command, because the effects apply globally -to the Emacs session. The supported language environments -(see the variable @code{language-info-alist}) include: - -@cindex Euro sign -@cindex UTF-8 -@quotation -ASCII, Belarusian, Bengali, Brazilian Portuguese, Bulgarian, Cham, -Chinese-BIG5, Chinese-CNS, Chinese-EUC-TW, Chinese-GB, Chinese-GBK, -Chinese-GB18030, Croatian, Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8, -Czech, Devanagari, Dutch, English, Esperanto, Ethiopic, French, -Georgian, German, Greek, Gujarati, Hebrew, IPA, Italian, Japanese, -Kannada, Khmer, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4, -Latin-5, Latin-6, Latin-7, Latin-8 (Celtic), Latin-9 (updated Latin-1 -with the Euro sign), Latvian, Lithuanian, Malayalam, Oriya, Polish, -Punjabi, Romanian, Russian, Sinhala, Slovak, Slovenian, Spanish, -Swedish, TaiViet, Tajik, Tamil, Telugu, Thai, Tibetan, Turkish, UTF-8 -(for a setup which prefers Unicode characters and files encoded in -UTF-8), Ukrainian, Vietnamese, Welsh, and Windows-1255 (for a setup -which prefers Cyrillic characters and files encoded in Windows-1255). -@end quotation - - To display the script(s) used by your language environment on a -graphical display, you need to have suitable fonts. -@xref{Fontsets}, for more details about setting up your fonts. - -@findex set-locale-environment -@vindex locale-language-names -@vindex locale-charset-language-names -@cindex locales - Some operating systems let you specify the character-set locale you -are using by setting the locale environment variables @env{LC_ALL}, -@env{LC_CTYPE}, or @env{LANG}. (If more than one of these is -set, the first one that is nonempty specifies your locale for this -purpose.) During startup, Emacs looks up your character-set locale's -name in the system locale alias table, matches its canonical name -against entries in the value of the variables -@code{locale-charset-language-names} and @code{locale-language-names} -(the former overrides the latter), -and selects the corresponding language environment if a match is found. -It also adjusts the display -table and terminal coding system, the locale coding system, the -preferred coding system as needed for the locale, and---last but not -least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard. - -@c This seems unlikely, doesn't it? - If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG} -environment variables while running Emacs (by using @kbd{M-x setenv}), -you may want to invoke the @code{set-locale-environment} -function afterwards to readjust the language environment from the new -locale. - -@vindex locale-preferred-coding-systems - The @code{set-locale-environment} function normally uses the preferred -coding system established by the language environment to decode system -messages. But if your locale matches an entry in the variable -@code{locale-preferred-coding-systems}, Emacs uses the corresponding -coding system instead. For example, if the locale @samp{ja_JP.PCK} -matches @code{japanese-shift-jis} in -@code{locale-preferred-coding-systems}, Emacs uses that encoding even -though it might normally use @code{japanese-iso-8bit}. - - You can override the language environment chosen at startup with -explicit use of the command @code{set-language-environment}, or with -customization of @code{current-language-environment} in your init -file. - -@kindex C-h L -@findex describe-language-environment - To display information about the effects of a certain language -environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env} -@key{RET}} (@code{describe-language-environment}). This tells you -which languages this language environment is useful for, and lists the -character sets, coding systems, and input methods that go with it. It -also shows some sample text to illustrate scripts used in this -language environment. If you give an empty input for @var{lang-env}, -this command describes the chosen language environment. -@anchor{Describe Language Environment} - -@vindex set-language-environment-hook - You can customize any language environment with the normal hook -@code{set-language-environment-hook}. The command -@code{set-language-environment} runs that hook after setting up the new -language environment. The hook functions can test for a specific -language environment by checking the variable -@code{current-language-environment}. This hook is where you should -put non-default settings for specific language environments, such as -coding systems for keyboard input and terminal output, the default -input method, etc. - -@vindex exit-language-environment-hook - Before it starts to set up the new language environment, -@code{set-language-environment} first runs the hook -@code{exit-language-environment-hook}. This hook is useful for undoing -customizations that were made with @code{set-language-environment-hook}. -For instance, if you set up a special key binding in a specific language -environment using @code{set-language-environment-hook}, you should set -up @code{exit-language-environment-hook} to restore the normal binding -for that key. - -@node Input Methods -@section Input Methods - -@cindex input methods - An @dfn{input method} is a kind of character conversion designed -specifically for interactive input. In Emacs, typically each language -has its own input method; sometimes several languages that use the same -characters can share one input method. A few languages support several -input methods. - - The simplest kind of input method works by mapping @acronym{ASCII} letters -into another alphabet; this allows you to use one other alphabet -instead of @acronym{ASCII}. The Greek and Russian input methods -work this way. - - A more powerful technique is composition: converting sequences of -characters into one letter. Many European input methods use composition -to produce a single non-@acronym{ASCII} letter from a sequence that consists of a -letter followed by accent characters (or vice versa). For example, some -methods convert the sequence @kbd{o ^} into a single accented letter. -These input methods have no special commands of their own; all they do -is compose sequences of printing characters. - - The input methods for syllabic scripts typically use mapping followed -by composition. The input methods for Thai and Korean work this way. -First, letters are mapped into symbols for particular sounds or tone -marks; then, sequences of these that make up a whole syllable are -mapped into one syllable sign. - - Chinese and Japanese require more complex methods. In Chinese input -methods, first you enter the phonetic spelling of a Chinese word (in -input method @code{chinese-py}, among others), or a sequence of -portions of the character (input methods @code{chinese-4corner} and -@code{chinese-sw}, and others). One input sequence typically -corresponds to many possible Chinese characters. You select the one -you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n}, -@kbd{C-p} (or the arrow keys), and digits, which have special meanings -in this situation. - - The possible characters are conceptually arranged in several rows, -with each row holding up to 10 alternatives. Normally, Emacs displays -just one row at a time, in the echo area; @code{(@var{i}/@var{j})} -appears at the beginning, to indicate that this is the @var{i}th row -out of a total of @var{j} rows. Type @kbd{C-n} or @kbd{C-p} to -display the next row or the previous row. - - Type @kbd{C-f} and @kbd{C-b} to move forward and backward among -the alternatives in the current row. As you do this, Emacs highlights -the current alternative with a special color; type @code{C-@key{SPC}} -to select the current alternative and use it as input. The -alternatives in the row are also numbered; the number appears before -the alternative. Typing a number selects the associated alternative -of the current row and uses it as input. - - @key{TAB} in these Chinese input methods displays a buffer showing -all the possible characters at once; then clicking @kbd{Mouse-2} on -one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b}, -@kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they -do the highlighting in the buffer showing the possible characters, -rather than in the echo area. - - In Japanese input methods, first you input a whole word using -phonetic spelling; then, after the word is in the buffer, Emacs -converts it into one or more characters using a large dictionary. One -phonetic spelling corresponds to a number of different Japanese words; -to select one of them, use @kbd{C-n} and @kbd{C-p} to cycle through -the alternatives. - - Sometimes it is useful to cut off input method processing so that the -characters you have just entered will not combine with subsequent -characters. For example, in input method @code{latin-1-postfix}, the -sequence @kbd{o ^} combines to form an @samp{o} with an accent. What if -you want to enter them as separate characters? - - One way is to type the accent twice; this is a special feature for -entering the separate letter and accent. For example, @kbd{o ^ ^} gives -you the two characters @samp{o^}. Another way is to type another letter -after the @kbd{o}---something that won't combine with that---and -immediately delete it. For example, you could type @kbd{o o @key{DEL} -^} to get separate @samp{o} and @samp{^}. - - Another method, more general but not quite as easy to type, is to use -@kbd{C-\ C-\} between two characters to stop them from combining. This -is the command @kbd{C-\} (@code{toggle-input-method}) used twice. -@ifnottex -@xref{Select Input Method}. -@end ifnottex - -@cindex incremental search, input method interference - @kbd{C-\ C-\} is especially useful inside an incremental search, -because it stops waiting for more characters to combine, and starts -searching for what you have already entered. - - To find out how to input the character after point using the current -input method, type @kbd{C-u C-x =}. @xref{Position Info}. - -@vindex input-method-verbose-flag -@vindex input-method-highlight-flag - The variables @code{input-method-highlight-flag} and -@code{input-method-verbose-flag} control how input methods explain -what is happening. If @code{input-method-highlight-flag} is -non-@code{nil}, the partial sequence is highlighted in the buffer (for -most input methods---some disable this feature). If -@code{input-method-verbose-flag} is non-@code{nil}, the list of -possible characters to type next is displayed in the echo area (but -not when you are in the minibuffer). - - Another facility for typing characters not on your keyboard is by -using @kbd{C-x 8 @key{RET}} (@code{ucs-insert}) to insert a single -character based on its Unicode name or code-point; see @ref{Inserting -Text}. - -@node Select Input Method -@section Selecting an Input Method - -@table @kbd -@item C-\ -Enable or disable use of the selected input method (@code{toggle-input-method}). - -@item C-x @key{RET} C-\ @var{method} @key{RET} -Select a new input method for the current buffer (@code{set-input-method}). - -@item C-h I @var{method} @key{RET} -@itemx C-h C-\ @var{method} @key{RET} -@findex describe-input-method -@kindex C-h I -@kindex C-h C-\ -Describe the input method @var{method} (@code{describe-input-method}). -By default, it describes the current input method (if any). This -description should give you the full details of how to use any -particular input method. - -@item M-x list-input-methods -Display a list of all the supported input methods. -@end table - -@findex set-input-method -@vindex current-input-method -@kindex C-x RET C-\ - To choose an input method for the current buffer, use @kbd{C-x -@key{RET} C-\} (@code{set-input-method}). This command reads the -input method name from the minibuffer; the name normally starts with the -language environment that it is meant to be used with. The variable -@code{current-input-method} records which input method is selected. - -@findex toggle-input-method -@kindex C-\ - Input methods use various sequences of @acronym{ASCII} characters to -stand for non-@acronym{ASCII} characters. Sometimes it is useful to -turn off the input method temporarily. To do this, type @kbd{C-\} -(@code{toggle-input-method}). To reenable the input method, type -@kbd{C-\} again. - - If you type @kbd{C-\} and you have not yet selected an input method, -it prompts you to specify one. This has the same effect as using -@kbd{C-x @key{RET} C-\} to specify an input method. - - When invoked with a numeric argument, as in @kbd{C-u C-\}, -@code{toggle-input-method} always prompts you for an input method, -suggesting the most recently selected one as the default. - -@vindex default-input-method - Selecting a language environment specifies a default input method for -use in various buffers. When you have a default input method, you can -select it in the current buffer by typing @kbd{C-\}. The variable -@code{default-input-method} specifies the default input method -(@code{nil} means there is none). - - In some language environments, which support several different input -methods, you might want to use an input method different from the -default chosen by @code{set-language-environment}. You can instruct -Emacs to select a different default input method for a certain -language environment, if you wish, by using -@code{set-language-environment-hook} (@pxref{Language Environments, -set-language-environment-hook}). For example: - -@lisp -(defun my-chinese-setup () - "Set up my private Chinese environment." - (if (equal current-language-environment "Chinese-GB") - (setq default-input-method "chinese-tonepy"))) -(add-hook 'set-language-environment-hook 'my-chinese-setup) -@end lisp - -@noindent -This sets the default input method to be @code{chinese-tonepy} -whenever you choose a Chinese-GB language environment. - -You can instruct Emacs to activate a certain input method -automatically. For example: - -@lisp -(add-hook 'text-mode-hook - (lambda () (set-input-method "german-prefix"))) -@end lisp - -@noindent -This automatically activates the input method ``german-prefix'' in -Text mode. - -@findex quail-set-keyboard-layout - Some input methods for alphabetic scripts work by (in effect) -remapping the keyboard to emulate various keyboard layouts commonly used -for those scripts. How to do this remapping properly depends on your -actual keyboard layout. To specify which layout your keyboard has, use -the command @kbd{M-x quail-set-keyboard-layout}. - -@findex quail-show-key - You can use the command @kbd{M-x quail-show-key} to show what key (or -key sequence) to type in order to input the character following point, -using the selected keyboard layout. The command @kbd{C-u C-x =} also -shows that information, in addition to other information about the -character. - -@findex list-input-methods - @kbd{M-x list-input-methods} displays a list of all the supported -input methods. The list gives information about each input method, -including the string that stands for it in the mode line. - -@node Coding Systems -@section Coding Systems -@cindex coding systems - - Users of various languages have established many more-or-less standard -coding systems for representing them. Emacs does not use these coding -systems internally; instead, it converts from various coding systems to -its own system when reading data, and converts the internal coding -system to other coding systems when writing data. Conversion is -possible in reading or writing files, in sending or receiving from the -terminal, and in exchanging data with subprocesses. - - Emacs assigns a name to each coding system. Most coding systems are -used for one language, and the name of the coding system starts with -the language name. Some coding systems are used for several -languages; their names usually start with @samp{iso}. There are also -special coding systems, such as @code{no-conversion}, @code{raw-text}, -and @code{emacs-internal}. - -@cindex international files from DOS/Windows systems - A special class of coding systems, collectively known as -@dfn{codepages}, is designed to support text encoded by MS-Windows and -MS-DOS software. The names of these coding systems are -@code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the -codepage. You can use these encodings just like any other coding -system; for example, to visit a file encoded in codepage 850, type -@kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename} -@key{RET}}. - - In addition to converting various representations of non-@acronym{ASCII} -characters, a coding system can perform end-of-line conversion. Emacs -handles three different conventions for how to separate lines in a file: -newline (``unix''), carriage-return linefeed (``dos''), and just -carriage-return (``mac''). - -@table @kbd -@item C-h C @var{coding} @key{RET} -Describe coding system @var{coding} (@code{describe-coding-system}). - -@item C-h C @key{RET} -Describe the coding systems currently in use. - -@item M-x list-coding-systems -Display a list of all the supported coding systems. -@end table - -@kindex C-h C -@findex describe-coding-system - The command @kbd{C-h C} (@code{describe-coding-system}) displays -information about particular coding systems, including the end-of-line -conversion specified by those coding systems. You can specify a coding -system name as the argument; alternatively, with an empty argument, it -describes the coding systems currently selected for various purposes, -both in the current buffer and as the defaults, and the priority list -for recognizing coding systems (@pxref{Recognize Coding}). - -@findex list-coding-systems - To display a list of all the supported coding systems, type @kbd{M-x -list-coding-systems}. The list gives information about each coding -system, including the letter that stands for it in the mode line -(@pxref{Mode Line}). - -@cindex end-of-line conversion -@cindex line endings -@cindex MS-DOS end-of-line conversion -@cindex Macintosh end-of-line conversion - Each of the coding systems that appear in this list---except for -@code{no-conversion}, which means no conversion of any kind---specifies -how and whether to convert printing characters, but leaves the choice of -end-of-line conversion to be decided based on the contents of each file. -For example, if the file appears to use the sequence carriage-return -linefeed to separate lines, DOS end-of-line conversion will be used. - - Each of the listed coding systems has three variants, which specify -exactly what to do for end-of-line conversion: - -@table @code -@item @dots{}-unix -Don't do any end-of-line conversion; assume the file uses -newline to separate lines. (This is the convention normally used -on Unix and GNU systems, and Mac OS X.) - -@item @dots{}-dos -Assume the file uses carriage-return linefeed to separate lines, and do -the appropriate conversion. (This is the convention normally used on -Microsoft systems.@footnote{It is also specified for MIME @samp{text/*} -bodies and in other network transport contexts. It is different -from the SGML reference syntax record-start/record-end format, which -Emacs doesn't support directly.}) - -@item @dots{}-mac -Assume the file uses carriage-return to separate lines, and do the -appropriate conversion. (This was the convention used on the -Macintosh system prior to OS X.) -@end table - - These variant coding systems are omitted from the -@code{list-coding-systems} display for brevity, since they are entirely -predictable. For example, the coding system @code{iso-latin-1} has -variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and -@code{iso-latin-1-mac}. - -@cindex @code{undecided}, coding system - The coding systems @code{unix}, @code{dos}, and @code{mac} are -aliases for @code{undecided-unix}, @code{undecided-dos}, and -@code{undecided-mac}, respectively. These coding systems specify only -the end-of-line conversion, and leave the character code conversion to -be deduced from the text itself. - -@cindex @code{raw-text}, coding system - The coding system @code{raw-text} is good for a file which is mainly -@acronym{ASCII} text, but may contain byte values above 127 that are -not meant to encode non-@acronym{ASCII} characters. With -@code{raw-text}, Emacs copies those byte values unchanged, and sets -@code{enable-multibyte-characters} to @code{nil} in the current buffer -so that they will be interpreted properly. @code{raw-text} handles -end-of-line conversion in the usual way, based on the data -encountered, and has the usual three variants to specify the kind of -end-of-line conversion to use. - -@cindex @code{no-conversion}, coding system - In contrast, the coding system @code{no-conversion} specifies no -character code conversion at all---none for non-@acronym{ASCII} byte values and -none for end of line. This is useful for reading or writing binary -files, tar files, and other files that must be examined verbatim. It, -too, sets @code{enable-multibyte-characters} to @code{nil}. - - The easiest way to edit a file with no conversion of any kind is with -the @kbd{M-x find-file-literally} command. This uses -@code{no-conversion}, and also suppresses other Emacs features that -might convert the file contents before you see them. @xref{Visiting}. - -@cindex @code{emacs-internal}, coding system - The coding system @code{emacs-internal} (or @code{utf-8-emacs}, -which is equivalent) means that the file contains non-@acronym{ASCII} -characters stored with the internal Emacs encoding. This coding -system handles end-of-line conversion based on the data encountered, -and has the usual three variants to specify the kind of end-of-line -conversion. - -@node Recognize Coding -@section Recognizing Coding Systems - - Whenever Emacs reads a given piece of text, it tries to recognize -which coding system to use. This applies to files being read, output -from subprocesses, text from X selections, etc. Emacs can select the -right coding system automatically most of the time---once you have -specified your preferences. - - Some coding systems can be recognized or distinguished by which byte -sequences appear in the data. However, there are coding systems that -cannot be distinguished, not even potentially. For example, there is no -way to distinguish between Latin-1 and Latin-2; they use the same byte -values with different meanings. - - Emacs handles this situation by means of a priority list of coding -systems. Whenever Emacs reads a file, if you do not specify the coding -system to use, Emacs checks the data against each coding system, -starting with the first in priority and working down the list, until it -finds a coding system that fits the data. Then it converts the file -contents assuming that they are represented in this coding system. - - The priority list of coding systems depends on the selected language -environment (@pxref{Language Environments}). For example, if you use -French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use -Czech, you probably want Latin-2 to be preferred. This is one of the -reasons to specify a language environment. - -@findex prefer-coding-system - However, you can alter the coding system priority list in detail -with the command @kbd{M-x prefer-coding-system}. This command reads -the name of a coding system from the minibuffer, and adds it to the -front of the priority list, so that it is preferred to all others. If -you use this command several times, each use adds one element to the -front of the priority list. - - If you use a coding system that specifies the end-of-line conversion -type, such as @code{iso-8859-1-dos}, what this means is that Emacs -should attempt to recognize @code{iso-8859-1} with priority, and should -use DOS end-of-line conversion when it does recognize @code{iso-8859-1}. - -@vindex file-coding-system-alist - Sometimes a file name indicates which coding system to use for the -file. The variable @code{file-coding-system-alist} specifies this -correspondence. There is a special function -@code{modify-coding-system-alist} for adding elements to this list. For -example, to read and write all @samp{.txt} files using the coding system -@code{chinese-iso-8bit}, you can execute this Lisp expression: - -@smallexample -(modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit) -@end smallexample - -@noindent -The first argument should be @code{file}, the second argument should be -a regular expression that determines which files this applies to, and -the third argument says which coding system to use for these files. - -@vindex inhibit-eol-conversion -@cindex DOS-style end-of-line display - Emacs recognizes which kind of end-of-line conversion to use based on -the contents of the file: if it sees only carriage-returns, or only -carriage-return linefeed sequences, then it chooses the end-of-line -conversion accordingly. You can inhibit the automatic use of -end-of-line conversion by setting the variable @code{inhibit-eol-conversion} -to non-@code{nil}. If you do that, DOS-style files will be displayed -with the @samp{^M} characters visible in the buffer; some people -prefer this to the more subtle @samp{(DOS)} end-of-line type -indication near the left edge of the mode line (@pxref{Mode Line, -eol-mnemonic}). - -@vindex inhibit-iso-escape-detection -@cindex escape sequences in files - By default, the automatic detection of coding system is sensitive to -escape sequences. If Emacs sees a sequence of characters that begin -with an escape character, and the sequence is valid as an ISO-2022 -code, that tells Emacs to use one of the ISO-2022 encodings to decode -the file. - - However, there may be cases that you want to read escape sequences -in a file as is. In such a case, you can set the variable -@code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code -detection ignores any escape sequences, and never uses an ISO-2022 -encoding. The result is that all escape sequences become visible in -the buffer. - - The default value of @code{inhibit-iso-escape-detection} is -@code{nil}. We recommend that you not change it permanently, only for -one specific operation. That's because some Emacs Lisp source files -in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the -coding system @code{iso-2022-7bit}, and they won't be -decoded correctly when you visit those files if you suppress the -escape sequence detection. -@c I count a grand total of 3 such files, so is the above really true? - -@vindex auto-coding-alist -@vindex auto-coding-regexp-alist - The variables @code{auto-coding-alist} and -@code{auto-coding-regexp-alist} are -the strongest way to specify the coding system for certain patterns of -file names, or for files containing certain patterns, respectively. -These variables even override @samp{-*-coding:-*-} tags in the file -itself (@pxref{Specify Coding}). For example, Emacs -uses @code{auto-coding-alist} for tar and archive files, to prevent it -from being confused by a @samp{-*-coding:-*-} tag in a member of the -archive and thinking it applies to the archive file as a whole. -@ignore -@c This describes old-style BABYL files, which are no longer relevant. -Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that -RMAIL files, whose names in general don't match any particular -pattern, are decoded correctly. -@end ignore - -@vindex auto-coding-functions - Another way to specify a coding system is with the variable -@code{auto-coding-functions}. For example, one of the builtin -@code{auto-coding-functions} detects the encoding for XML files. -Unlike the previous two, this variable does not override any -@samp{-*-coding:-*-} tag. - -@c FIXME? This seems somewhat out of place. Move to the Rmail section? -@vindex rmail-decode-mime-charset -@vindex rmail-file-coding-system - When you get new mail in Rmail, each message is translated -automatically from the coding system it is written in, as if it were a -separate file. This uses the priority list of coding systems that you -have specified. If a MIME message specifies a character set, Rmail -obeys that specification. For reading and saving Rmail files -themselves, Emacs uses the coding system specified by the variable -@code{rmail-file-coding-system}. The default value is @code{nil}, -which means that Rmail files are not translated (they are read and -written in the Emacs internal character code). - -@node Specify Coding -@section Specifying a File's Coding System - - If Emacs recognizes the encoding of a file incorrectly, you can -reread the file using the correct coding system with @kbd{C-x -@key{RET} r} (@code{revert-buffer-with-coding-system}). This command -prompts for the coding system to use. To see what coding system Emacs -actually used to decode the file, look at the coding system mnemonic -letter near the left edge of the mode line (@pxref{Mode Line}), or -type @kbd{C-h C} (@code{describe-coding-system}). - -@vindex coding - You can specify the coding system for a particular file in the file -itself, using the @w{@samp{-*-@dots{}-*-}} construct at the beginning, -or a local variables list at the end (@pxref{File Variables}). You do -this by defining a value for the ``variable'' named @code{coding}. -Emacs does not really have a variable @code{coding}; instead of -setting a variable, this uses the specified coding system for the -file. For example, @samp{-*-mode: C; coding: latin-1;-*-} specifies -use of the Latin-1 coding system, as well as C mode. When you specify -the coding explicitly in the file, that overrides -@code{file-coding-system-alist}. - -@node Output Coding -@section Choosing Coding Systems for Output - -@vindex buffer-file-coding-system - Once Emacs has chosen a coding system for a buffer, it stores that -coding system in @code{buffer-file-coding-system}. That makes it the -default for operations that write from this buffer into a file, such -as @code{save-buffer} and @code{write-region}. You can specify a -different coding system for further file output from the buffer using -@code{set-buffer-file-coding-system} (@pxref{Text Coding}). - - You can insert any character Emacs supports into any Emacs buffer, -but most coding systems can only handle a subset of these characters. -Therefore, it's possible that the characters you insert cannot be -encoded with the coding system that will be used to save the buffer. -For example, you could visit a text file in Polish, encoded in -@code{iso-8859-2}, and add some Russian words to it. When you save -that buffer, Emacs cannot use the current value of -@code{buffer-file-coding-system}, because the characters you added -cannot be encoded by that coding system. - - When that happens, Emacs tries the most-preferred coding system (set -by @kbd{M-x prefer-coding-system} or @kbd{M-x -set-language-environment}). If that coding system can safely encode -all of the characters in the buffer, Emacs uses it, and stores its -value in @code{buffer-file-coding-system}. Otherwise, Emacs displays -a list of coding systems suitable for encoding the buffer's contents, -and asks you to choose one of those coding systems. - - If you insert the unsuitable characters in a mail message, Emacs -behaves a bit differently. It additionally checks whether the -@c What determines this? -most-preferred coding system is recommended for use in MIME messages; -if not, it informs you of this fact and prompts you for another coding -system. This is so you won't inadvertently send a message encoded in -a way that your recipient's mail software will have difficulty -decoding. (You can still use an unsuitable coding system if you enter -its name at the prompt.) - -@c It seems that select-message-coding-system does this. -@c Both sendmail.el and smptmail.el call it; i.e. smtpmail.el still -@c obeys sendmail-coding-system. -@vindex sendmail-coding-system - When you send a mail message (@pxref{Sending Mail}), -Emacs has four different ways to determine the coding system to use -for encoding the message text. It tries the buffer's own value of -@code{buffer-file-coding-system}, if that is non-@code{nil}. -Otherwise, it uses the value of @code{sendmail-coding-system}, if that -is non-@code{nil}. The third way is to use the default coding system -for new files, which is controlled by your choice of language -@c i.e., default-sendmail-coding-system -environment, if that is non-@code{nil}. If all of these three values -are @code{nil}, Emacs encodes outgoing mail using the Latin-1 coding -system. -@c FIXME? Where does the Latin-1 default come in? - -@node Text Coding -@section Specifying a Coding System for File Text - - In cases where Emacs does not automatically choose the right coding -system for a file's contents, you can use these commands to specify -one: - -@table @kbd -@item C-x @key{RET} f @var{coding} @key{RET} -Use coding system @var{coding} to save or revisit the file in -the current buffer (@code{set-buffer-file-coding-system}). - -@item C-x @key{RET} c @var{coding} @key{RET} -Specify coding system @var{coding} for the immediately following -command (@code{universal-coding-system-argument}). - -@item C-x @key{RET} r @var{coding} @key{RET} -Revisit the current file using the coding system @var{coding} -(@code{revert-buffer-with-coding-system}). - -@item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET} -Convert a region that was decoded using coding system @var{wrong}, -decoding it using coding system @var{right} instead. -@end table - -@kindex C-x RET f -@findex set-buffer-file-coding-system - The command @kbd{C-x @key{RET} f} -(@code{set-buffer-file-coding-system}) sets the file coding system for -the current buffer---in other words, it says which coding system to -use when saving or reverting the visited file. You specify which -coding system using the minibuffer. If you specify a coding system -that cannot handle all of the characters in the buffer, Emacs warns -you about the troublesome characters when you actually save the -buffer. - -@cindex specify end-of-line conversion - You can also use this command to specify the end-of-line conversion -(@pxref{Coding Systems, end-of-line conversion}) for encoding the -current buffer. For example, @kbd{C-x @key{RET} f dos @key{RET}} will -cause Emacs to save the current buffer's text with DOS-style -carriage-return linefeed line endings. - -@kindex C-x RET c -@findex universal-coding-system-argument - Another way to specify the coding system for a file is when you visit -the file. First use the command @kbd{C-x @key{RET} c} -(@code{universal-coding-system-argument}); this command uses the -minibuffer to read a coding system name. After you exit the minibuffer, -the specified coding system is used for @emph{the immediately following -command}. - - So if the immediately following command is @kbd{C-x C-f}, for example, -it reads the file using that coding system (and records the coding -system for when you later save the file). Or if the immediately following -command is @kbd{C-x C-w}, it writes the file using that coding system. -When you specify the coding system for saving in this way, instead -of with @kbd{C-x @key{RET} f}, there is no warning if the buffer -contains characters that the coding system cannot handle. - - Other file commands affected by a specified coding system include -@kbd{C-x i} and @kbd{C-x C-v}, as well as the other-window variants -of @kbd{C-x C-f}. @kbd{C-x @key{RET} c} also affects commands that -start subprocesses, including @kbd{M-x shell} (@pxref{Shell}). If the -immediately following command does not use the coding system, then -@kbd{C-x @key{RET} c} ultimately has no effect. - - An easy way to visit a file with no conversion is with the @kbd{M-x -find-file-literally} command. @xref{Visiting}. - - The default value of the variable @code{buffer-file-coding-system} -specifies the choice of coding system to use when you create a new file. -It applies when you find a new file, and when you create a buffer and -then save it in a file. Selecting a language environment typically sets -this variable to a good choice of default coding system for that language -environment. - -@kindex C-x RET r -@findex revert-buffer-with-coding-system - If you visit a file with a wrong coding system, you can correct this -with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}). -This visits the current file again, using a coding system you specify. - -@findex recode-region - If a piece of text has already been inserted into a buffer using the -wrong coding system, you can redo the decoding of it using @kbd{M-x -recode-region}. This prompts you for the proper coding system, then -for the wrong coding system that was actually used, and does the -conversion. It first encodes the region using the wrong coding system, -then decodes it again using the proper coding system. - -@node Communication Coding -@section Coding Systems for Interprocess Communication - - This section explains how to specify coding systems for use -in communication with other processes. - -@table @kbd -@item C-x @key{RET} x @var{coding} @key{RET} -Use coding system @var{coding} for transferring selections to and from -other window-based applications (@code{set-selection-coding-system}). - -@item C-x @key{RET} X @var{coding} @key{RET} -Use coding system @var{coding} for transferring @emph{one} -selection---the next one---to or from another window-based application -(@code{set-next-selection-coding-system}). - -@item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET} -Use coding systems @var{input-coding} and @var{output-coding} for -subprocess input and output in the current buffer -(@code{set-buffer-process-coding-system}). -@end table - -@kindex C-x RET x -@kindex C-x RET X -@findex set-selection-coding-system -@findex set-next-selection-coding-system - The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system}) -specifies the coding system for sending selected text to other windowing -applications, and for receiving the text of selections made in other -applications. This command applies to all subsequent selections, until -you override it by using the command again. The command @kbd{C-x -@key{RET} X} (@code{set-next-selection-coding-system}) specifies the -coding system for the next selection made in Emacs or read by Emacs. - -@vindex x-select-request-type - The variable @code{x-select-request-type} specifies the data type to -request from the X Window System for receiving text selections from -other applications. If the value is @code{nil} (the default), Emacs -tries @code{UTF8_STRING} and @code{COMPOUND_TEXT}, in this order, and -uses various heuristics to choose the more appropriate of the two -results; if none of these succeed, Emacs falls back on @code{STRING}. -If the value of @code{x-select-request-type} is one of the symbols -@code{COMPOUND_TEXT}, @code{UTF8_STRING}, @code{STRING}, or -@code{TEXT}, Emacs uses only that request type. If the value is a -list of some of these symbols, Emacs tries only the request types in -the list, in order, until one of them succeeds, or until the list is -exhausted. - -@kindex C-x RET p -@findex set-buffer-process-coding-system - The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system}) -specifies the coding system for input and output to a subprocess. This -command applies to the current buffer; normally, each subprocess has its -own buffer, and thus you can use this command to specify translation to -and from a particular subprocess by giving the command in the -corresponding buffer. - - You can also use @kbd{C-x @key{RET} c} -(@code{universal-coding-system-argument}) just before the command that -runs or starts a subprocess, to specify the coding system for -communicating with that subprocess. @xref{Text Coding}. - - The default for translation of process input and output depends on the -current language environment. - -@vindex locale-coding-system -@cindex decoding non-@acronym{ASCII} keyboard input on X - The variable @code{locale-coding-system} specifies a coding system -to use when encoding and decoding system strings such as system error -messages and @code{format-time-string} formats and time stamps. That -coding system is also used for decoding non-@acronym{ASCII} keyboard -input on the X Window System. You should choose a coding system that is compatible -with the underlying system's text representation, which is normally -specified by one of the environment variables @env{LC_ALL}, -@env{LC_CTYPE}, and @env{LANG}. (The first one, in the order -specified above, whose value is nonempty is the one that determines -the text representation.) - -@node File Name Coding -@section Coding Systems for File Names - -@table @kbd -@item C-x @key{RET} F @var{coding} @key{RET} -Use coding system @var{coding} for encoding and decoding file -names (@code{set-file-name-coding-system}). -@end table - -@findex set-file-name-coding-system -@kindex C-x @key{RET} F -@cindex file names with non-@acronym{ASCII} characters - The command @kbd{C-x @key{RET} F} (@code{set-file-name-coding-system}) -specifies a coding system to use for encoding file @emph{names}. It -has no effect on reading and writing the @emph{contents} of files. - -@vindex file-name-coding-system - In fact, all this command does is set the value of the variable -@code{file-name-coding-system}. If you set the variable to a coding -system name (as a Lisp symbol or a string), Emacs encodes file names -using that coding system for all file operations. This makes it -possible to use non-@acronym{ASCII} characters in file names---or, at -least, those non-@acronym{ASCII} characters that the specified coding -system can encode. - - If @code{file-name-coding-system} is @code{nil}, Emacs uses a -default coding system determined by the selected language environment, -and stored in the @code{default-file-name-coding-system} variable. -@c FIXME? Is this correct? What is the "default language environment"? -In the default language environment, non-@acronym{ASCII} characters in -file names are not encoded specially; they appear in the file system -using the internal Emacs representation. - - @strong{Warning:} if you change @code{file-name-coding-system} (or the -language environment) in the middle of an Emacs session, problems can -result if you have already visited files whose names were encoded using -the earlier coding system and cannot be encoded (or are encoded -differently) under the new coding system. If you try to save one of -these buffers under the visited file name, saving may use the wrong file -name, or it may encounter an error. If such a problem happens, use @kbd{C-x -C-w} to specify a new file name for that buffer. - -@findex recode-file-name - If a mistake occurs when encoding a file name, use the command -@kbd{M-x recode-file-name} to change the file name's coding -system. This prompts for an existing file name, its old coding -system, and the coding system to which you wish to convert. - -@node Terminal Coding -@section Coding Systems for Terminal I/O - -@table @kbd -@item C-x @key{RET} t @var{coding} @key{RET} -Use coding system @var{coding} for terminal output -(@code{set-terminal-coding-system}). - -@item C-x @key{RET} k @var{coding} @key{RET} -Use coding system @var{coding} for keyboard input -(@code{set-keyboard-coding-system}). -@end table - -@kindex C-x RET t -@findex set-terminal-coding-system - The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system}) -specifies the coding system for terminal output. If you specify a -character code for terminal output, all characters output to the -terminal are translated into that coding system. - - This feature is useful for certain character-only terminals built to -support specific languages or character sets---for example, European -terminals that support one of the ISO Latin character sets. You need to -specify the terminal coding system when using multibyte text, so that -Emacs knows which characters the terminal can actually handle. - - By default, output to the terminal is not translated at all, unless -Emacs can deduce the proper coding system from your terminal type or -your locale specification (@pxref{Language Environments}). - -@kindex C-x RET k -@findex set-keyboard-coding-system -@vindex keyboard-coding-system - The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system}), -or the variable @code{keyboard-coding-system}, specifies the coding -system for keyboard input. Character-code translation of keyboard -input is useful for terminals with keys that send non-@acronym{ASCII} -graphic characters---for example, some terminals designed for ISO -Latin-1 or subsets of it. - - By default, keyboard input is translated based on your system locale -setting. If your terminal does not really support the encoding -implied by your locale (for example, if you find it inserts a -non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set -@code{keyboard-coding-system} to @code{nil} to turn off encoding. -You can do this by putting - -@lisp -(set-keyboard-coding-system nil) -@end lisp - -@noindent -in your init file. - - There is a similarity between using a coding system translation for -keyboard input, and using an input method: both define sequences of -keyboard input that translate into single characters. However, input -methods are designed to be convenient for interactive use by humans, and -the sequences that are translated are typically sequences of @acronym{ASCII} -printing characters. Coding systems typically translate sequences of -non-graphic characters. - -@node Fontsets -@section Fontsets -@cindex fontsets - - A font typically defines shapes for a single alphabet or script. -Therefore, displaying the entire range of scripts that Emacs supports -requires a collection of many fonts. In Emacs, such a collection is -called a @dfn{fontset}. A fontset is defined by a list of font specifications, -each assigned to handle a range of character codes, and may fall back -on another fontset for characters that are not covered by the fonts -it specifies. - -@cindex fonts for various scripts -@cindex Intlfonts package, installation - Each fontset has a name, like a font. However, while fonts are -stored in the system and the available font names are defined by the -system, fontsets are defined within Emacs itself. Once you have -defined a fontset, you can use it within Emacs by specifying its name, -anywhere that you could use a single font. Of course, Emacs fontsets -can use only the fonts that the system supports. If some characters -appear on the screen as empty boxes or hex codes, this means that the -fontset in use for them has no font for those characters. In this -case, or if the characters are shown, but not as well as you would -like, you may need to install extra fonts. Your operating system may -have optional fonts that you can install; or you can install the GNU -Intlfonts package, which includes fonts for most supported -scripts.@footnote{If you run Emacs on X, you may need to inform the X -server about the location of the newly installed fonts with commands -such as: -@c FIXME? I feel like this may be out of date. -@c Eg the intlfonts tarfile is ~ 10 years old. - -@example - xset fp+ /usr/local/share/emacs/fonts - xset fp rehash -@end example -} - - Emacs creates three fontsets automatically: the @dfn{standard -fontset}, the @dfn{startup fontset} and the @dfn{default fontset}. -@c FIXME? The doc of *standard*-fontset-spec says: -@c "You have the biggest chance to display international characters -@c with correct glyphs by using the *standard* fontset." (my emphasis) -@c See http://lists.gnu.org/archive/html/emacs-devel/2012-04/msg00430.html -The default fontset is most likely to have fonts for a wide variety of -non-@acronym{ASCII} characters, and is the default fallback for the -other two fontsets, and if you set a default font rather than fontset. -However, it does not specify font family names, so results can be -somewhat random if you use it directly. You can specify use of a -particular fontset by starting Emacs with the @samp{-fn} option. -For example, - -@example -emacs -fn fontset-standard -@end example - -@noindent -You can also specify a fontset with the @samp{Font} resource (@pxref{X -Resources}). - - If no fontset is specified for use, then Emacs uses an -@acronym{ASCII} font, with @samp{fontset-default} as a fallback for -characters the font does not cover. The standard fontset is only used if -explicitly requested, despite its name. - - A fontset does not necessarily specify a font for every character -code. If a fontset specifies no font for a certain character, or if -it specifies a font that does not exist on your system, then it cannot -display that character properly. It will display that character as a -hex code or thin space or an empty box instead. (@xref{Text Display, , -glyphless characters}, for details.) - -@node Defining Fontsets -@section Defining fontsets - -@vindex standard-fontset-spec -@vindex w32-standard-fontset-spec -@vindex ns-standard-fontset-spec -@cindex standard fontset - When running on X, Emacs creates a standard fontset automatically according to the value -of @code{standard-fontset-spec}. This fontset's name is - -@example --*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard -@end example - -@noindent -or just @samp{fontset-standard} for short. - - On GNUstep and Mac OS X, the standard fontset is created using the value of -@code{ns-standard-fontset-spec}, and on MS Windows it is -created using the value of @code{w32-standard-fontset-spec}. - -@c FIXME? How does one access these, or do anything with them? -@c Does it matter? - Bold, italic, and bold-italic variants of the standard fontset are -created automatically. Their names have @samp{bold} instead of -@samp{medium}, or @samp{i} instead of @samp{r}, or both. - -@cindex startup fontset - Emacs generates a fontset automatically, based on any default -@acronym{ASCII} font that you specify with the @samp{Font} resource or -the @samp{-fn} argument, or the default font that Emacs found when it -started. This is the @dfn{startup fontset} and its name is -@code{fontset-startup}. It does this by replacing the -@var{charset_registry} field with @samp{fontset}, and replacing -@var{charset_encoding} field with @samp{startup}, then using the -resulting string to specify a fontset. - - For instance, if you start Emacs with a font of this form, - -@c FIXME? I think this is a little misleading, because you cannot (?) -@c actually specify a font with wildcards, it has to be a complete spec. -@c Also, an X font specification of this form hasn't (?) been -@c mentioned before now, and is somewhat obsolete these days. -@c People are more likely to use a form like -@c emacs -fn "DejaVu Sans Mono-12" -@c How does any of this apply in that case? -@example -emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1" -@end example - -@noindent -Emacs generates the following fontset and uses it for the initial X -window frame: - -@example --*-courier-medium-r-normal-*-14-140-*-*-*-*-fontset-startup -@end example - - The startup fontset will use the font that you specify, or a variant -with a different registry and encoding, for all the characters that -are supported by that font, and fallback on @samp{fontset-default} for -other characters. - - With the X resource @samp{Emacs.Font}, you can specify a fontset name -just like an actual font name. But be careful not to specify a fontset -name in a wildcard resource like @samp{Emacs*Font}---that wildcard -specification matches various other resources, such as for menus, and -@c FIXME is this still true? -menus cannot handle fontsets. @xref{X Resources}. - - You can specify additional fontsets using X resources named -@samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0. -The resource value should have this form: - -@smallexample -@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}} -@end smallexample - -@noindent -@var{fontpattern} should have the form of a standard X font name (see -the previous fontset-startup example), except -for the last two fields. They should have the form -@samp{fontset-@var{alias}}. - - The fontset has two names, one long and one short. The long name is -@var{fontpattern}. The short name is @samp{fontset-@var{alias}}. You -can refer to the fontset by either name. - - The construct @samp{@var{charset}:@var{font}} specifies which font to -use (in this fontset) for one particular character set. Here, -@var{charset} is the name of a character set, and @var{font} is the -font to use for that character set. You can use this construct any -number of times in defining one fontset. - - For the other character sets, Emacs chooses a font based on -@var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values -that describe the character set. For the @acronym{ASCII} character font, -@samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}. - - In addition, when several consecutive fields are wildcards, Emacs -collapses them into a single wildcard. This is to prevent use of -auto-scaled fonts. Fonts made by scaling larger fonts are not usable -for editing, and scaling a smaller font is not also useful, because it is -better to use the smaller font in its own size, which is what Emacs -does. - - Thus if @var{fontpattern} is this, - -@example --*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 -@end example - -@noindent -the font specification for @acronym{ASCII} characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-ISO8859-1 -@end example - -@noindent -and the font specification for Chinese GB2312 characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-gb2312*-* -@end example - - You may not have any Chinese font matching the above font -specification. Most X distributions include only Chinese fonts that -have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In -such a case, @samp{Fontset-@var{n}} can be specified as: - -@smallexample -Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ - chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* -@end smallexample - -@noindent -Then, the font specifications for all but Chinese GB2312 characters have -@samp{fixed} in the @var{family} field, and the font specification for -Chinese GB2312 characters has a wild card @samp{*} in the @var{family} -field. - -@findex create-fontset-from-fontset-spec - The function that processes the fontset resource value to create the -fontset is called @code{create-fontset-from-fontset-spec}. You can also -call this function explicitly to create a fontset. - - @xref{Fonts}, for more information about font naming. - -@node Modifying Fontsets -@section Modifying Fontsets -@cindex fontsets, modifying -@findex set-fontset-font - - Fontsets do not always have to be created from scratch. If only -minor changes are required it may be easier to modify an existing -fontset. Modifying @samp{fontset-default} will also affect other -fontsets that use it as a fallback, so can be an effective way of -fixing problems with the fonts that Emacs chooses for a particular -script. - -Fontsets can be modified using the function @code{set-fontset-font}, -specifying a character, a charset, a script, or a range of characters -to modify the font for, and a font specification for the font to be -used. Some examples are: - -@example -;; Use Liberation Mono for latin-3 charset. -(set-fontset-font "fontset-default" 'iso-8859-3 - "Liberation Mono") - -;; Prefer a big5 font for han characters -(set-fontset-font "fontset-default" - 'han (font-spec :registry "big5") - nil 'prepend) - -;; Use DejaVu Sans Mono as a fallback in fontset-startup -;; before resorting to fontset-default. -(set-fontset-font "fontset-startup" nil "DejaVu Sans Mono" - nil 'append) - -;; Use MyPrivateFont for the Unicode private use area. -(set-fontset-font "fontset-default" '(#xe000 . #xf8ff) - "MyPrivateFont") - -@end example - - -@node Undisplayable Characters -@section Undisplayable Characters - - There may be some non-@acronym{ASCII} characters that your -terminal cannot display. Most text terminals support just a single -character set (use the variable @code{default-terminal-coding-system} -to tell Emacs which one, @ref{Terminal Coding}); characters that -can't be encoded in that coding system are displayed as @samp{?} by -default. - - Graphical displays can display a broader range of characters, but -you may not have fonts installed for all of them; characters that have -no font appear as a hollow box. - - If you use Latin-1 characters but your terminal can't display -Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences -instead, e.g.@: @samp{"o} for o-umlaut. Load the library -@file{iso-ascii} to do this. - -@vindex latin1-display - If your terminal can display Latin-1, you can display characters -from other European character sets using a mixture of equivalent -Latin-1 characters and @acronym{ASCII} mnemonics. Customize the variable -@code{latin1-display} to enable this. The mnemonic @acronym{ASCII} -sequences mostly correspond to those of the prefix input methods. - -@node Unibyte Mode -@section Unibyte Editing Mode - -@cindex European character sets -@cindex accented characters -@cindex ISO Latin character sets -@cindex Unibyte operation - The ISO 8859 Latin-@var{n} character sets define character codes in -the range 0240 to 0377 octal (160 to 255 decimal) to handle the -accented letters and punctuation needed by various European languages -(and some non-European ones). Note that Emacs considers bytes with -codes in this range as raw bytes, not as characters, even in a unibyte -buffer, i.e.@: if you disable multibyte characters. However, Emacs -can still handle these character codes as if they belonged to -@emph{one} of the single-byte character sets at a time. To specify -@emph{which} of these codes to use, invoke @kbd{M-x -set-language-environment} and specify a suitable language environment -such as @samp{Latin-@var{n}}. - - For more information about unibyte operation, see -@ref{Disabling Multibyte}. - -@vindex unibyte-display-via-language-environment - Emacs can also display bytes in the range 160 to 255 as readable -characters, provided the terminal or font in use supports them. This -works automatically. On a graphical display, Emacs can also display -single-byte characters through fontsets, in effect by displaying the -equivalent multibyte characters according to the current language -environment. To request this, set the variable -@code{unibyte-display-via-language-environment} to a non-@code{nil} -value. Note that setting this only affects how these bytes are -displayed, but does not change the fundamental fact that Emacs treats -them as raw bytes, not as characters. - -@cindex @code{iso-ascii} library - If your terminal does not support display of the Latin-1 character -set, Emacs can display these characters as @acronym{ASCII} sequences which at -least give you a clear idea of what the characters are. To do this, -load the library @code{iso-ascii}. Similar libraries for other -Latin-@var{n} character sets could be implemented, but have not been -so far. - -@findex standard-display-8bit -@cindex 8-bit display - Normally non-ISO-8859 characters (decimal codes between 128 and 159 -inclusive) are displayed as octal escapes. You can change this for -non-standard ``extended'' versions of ISO-8859 character sets by using the -function @code{standard-display-8bit} in the @code{disp-table} library. - - There are two ways to input single-byte non-@acronym{ASCII} -characters: - -@itemize @bullet -@cindex 8-bit input -@item -You can use an input method for the selected language environment. -@xref{Input Methods}. When you use an input method in a unibyte buffer, -the non-@acronym{ASCII} character you specify with it is converted to unibyte. - -@item -If your keyboard can generate character codes 128 (decimal) and up, -representing non-@acronym{ASCII} characters, you can type those character codes -directly. - -On a graphical display, you should not need to do anything special to -use these keys; they should simply work. On a text terminal, you -should use the command @code{M-x set-keyboard-coding-system} or customize the -variable @code{keyboard-coding-system} to specify which coding system -your keyboard uses (@pxref{Terminal Coding}). Enabling this feature -will probably require you to use @kbd{ESC} to type Meta characters; -however, on a console terminal or in @code{xterm}, you can arrange for -Meta to be converted to @kbd{ESC} and still be able type 8-bit -characters present directly on the keyboard or using @kbd{Compose} or -@kbd{AltGr} keys. @xref{User Input}. - -@kindex C-x 8 -@cindex @code{iso-transl} library -@cindex compose character -@cindex dead character -@item -For Latin-1 only, you can use the key @kbd{C-x 8} as a ``compose -character'' prefix for entry of non-@acronym{ASCII} Latin-1 printing -characters. @kbd{C-x 8} is good for insertion (in the minibuffer as -well as other buffers), for searching, and in any other context where -a key sequence is allowed. - -@kbd{C-x 8} works by loading the @code{iso-transl} library. Once that -library is loaded, the @key{ALT} modifier key, if the keyboard has -one, serves the same purpose as @kbd{C-x 8}: use @key{ALT} together -with an accent character to modify the following letter. In addition, -if the keyboard has keys for the Latin-1 ``dead accent characters'', -they too are defined to compose with the following character, once -@code{iso-transl} is loaded. - -Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations. -@end itemize - -@node Charsets -@section Charsets -@cindex charsets - - In Emacs, @dfn{charset} is short for ``character set''. Emacs -supports most popular charsets (such as @code{ascii}, -@code{iso-8859-1}, @code{cp1250}, @code{big5}, and @code{unicode}), in -addition to some charsets of its own (such as @code{emacs}, -@code{unicode-bmp}, and @code{eight-bit}). All supported characters -belong to one or more charsets. - - Emacs normally ``does the right thing'' with respect to charsets, so -that you don't have to worry about them. However, it is sometimes -helpful to know some of the underlying details about charsets. - - One example is font selection (@pxref{Fonts}). Each language -environment (@pxref{Language Environments}) defines a ``priority -list'' for the various charsets. When searching for a font, Emacs -initially attempts to find one that can display the highest-priority -charsets. For instance, in the Japanese language environment, the -charset @code{japanese-jisx0208} has the highest priority, so Emacs -tries to use a font whose @code{registry} property is -@samp{JISX0208.1983-0}. - -@findex list-charset-chars -@cindex characters in a certain charset -@findex describe-character-set - There are two commands that can be used to obtain information about -charsets. The command @kbd{M-x list-charset-chars} prompts for a -charset name, and displays all the characters in that character set. -The command @kbd{M-x describe-character-set} prompts for a charset -name, and displays information about that charset, including its -internal representation within Emacs. - -@findex list-character-sets - @kbd{M-x list-character-sets} displays a list of all supported -charsets. The list gives the names of charsets and additional -information to identity each charset; see the -@url{http://www.itscj.ipsj.or.jp/ISO-IR/, International Register of -Coded Character Sets} for more details. In this list, -charsets are divided into two categories: @dfn{normal charsets} are -listed first, followed by @dfn{supplementary charsets}. A -supplementary charset is one that is used to define another charset -(as a parent or a subset), or to provide backward-compatibility for -older Emacs versions. - - To find out which charset a character in the buffer belongs to, put -point before it and type @kbd{C-u C-x =} (@pxref{International -Chars}). - -@node Bidirectional Editing -@section Bidirectional Editing -@cindex bidirectional editing -@cindex right-to-left text - - Emacs supports editing text written in scripts, such as Arabic and -Hebrew, whose natural ordering of horizontal text for display is from -right to left. However, digits and Latin text embedded in these -scripts are still displayed left to right. It is also not uncommon to -have small portions of text in Arabic or Hebrew embedded in an otherwise -Latin document; e.g., as comments and strings in a program source -file. For these reasons, text that uses these scripts is actually -@dfn{bidirectional}: a mixture of runs of left-to-right and -right-to-left characters. - - This section describes the facilities and options provided by Emacs -for editing bidirectional text. - -@cindex logical order -@cindex visual order - Emacs stores right-to-left and bidirectional text in the so-called -@dfn{logical} (or @dfn{reading}) order: the buffer or string position -of the first character you read precedes that of the next character. -Reordering of bidirectional text into the @dfn{visual} order happens -at display time. As result, character positions no longer increase -monotonically with their positions on display. Emacs implements the -Unicode Bidirectional Algorithm described in the Unicode Standard -Annex #9, for reordering of bidirectional text for display. - -@vindex bidi-display-reordering - The buffer-local variable @code{bidi-display-reordering} controls -whether text in the buffer is reordered for display. If its value is -non-@code{nil}, Emacs reorders characters that have right-to-left -directionality when they are displayed. The default value is -@code{t}. - -@cindex base direction of paragraphs -@cindex paragraph, base direction - Each paragraph of bidirectional text can have its own @dfn{base -direction}, either right-to-left or left-to-right. (Paragraph -@c paragraph-separate etc have no influence on this? -boundaries are empty lines, i.e.@: lines consisting entirely of -whitespace characters.) Text in left-to-right paragraphs begins on -the screen at the left margin of the window and is truncated or -continued when it reaches the right margin. By contrast, text in -right-to-left paragraphs is displayed starting at the right margin and -is continued or truncated at the left margin. - -@vindex bidi-paragraph-direction - Emacs determines the base direction of each paragraph dynamically, -based on the text at the beginning of the paragraph. However, -sometimes a buffer may need to force a certain base direction for its -paragraphs. The variable @code{bidi-paragraph-direction}, if -non-@code{nil}, disables the dynamic determination of the base -direction, and instead forces all paragraphs in the buffer to have the -direction specified by its buffer-local value. The value can be either -@code{right-to-left} or @code{left-to-right}. Any other value is -interpreted as @code{nil}. - -@cindex LRM -@cindex RLM - Alternatively, you can control the base direction of a paragraph by -inserting special formatting characters in front of the paragraph. -The special character @code{RIGHT-TO-LEFT MARK}, or @sc{rlm}, forces -the right-to-left direction on the following paragraph, while -@code{LEFT-TO-RIGHT MARK}, or @sc{lrm} forces the left-to-right -direction. (You can use @kbd{C-x 8 RET} to insert these characters.) -In a GUI session, the @sc{lrm} and @sc{rlm} characters display as very -thin blank characters; on text terminals they display as blanks. - - Because characters are reordered for display, Emacs commands that -operate in the logical order or on stretches of buffer positions may -produce unusual effects. For example, @kbd{C-f} and @kbd{C-b} -commands move point in the logical order, so the cursor will sometimes -jump when point traverses reordered bidirectional text. Similarly, a -highlighted region covering a contiguous range of character positions -may look discontinuous if the region spans reordered text. This is -normal and similar to the behavior of other programs that support -bidirectional text. diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi deleted file mode 100644 index 4435590536f..00000000000 --- a/doc/emacs/package.texi +++ /dev/null @@ -1,249 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Packages -@chapter Emacs Lisp Packages -@cindex Package -@cindex Emacs Lisp package archive -@cindex Package archive -@cindex Emacs Lisp package - -Emacs includes a facility that lets you easily download and install -@dfn{packages} that implement additional features. Each package is a -separate Emacs Lisp program, sometimes including other components such -as an Info manual. - - @kbd{M-x list-packages} brings up a buffer named @file{*Packages*} -with a list of all packages. You can install or uninstall packages -via this buffer. @xref{Package Menu}. - -@findex describe-package - The command @kbd{C-h P} (@code{describe-package}) prompts for the -name of a package, and displays a help buffer describing the -attributes of the package and the features that it implements. - - By default, Emacs downloads packages from a @dfn{package archive} -maintained by the Emacs developers and hosted by the GNU project. -Optionally, you can also download packages from archives maintained by -third parties. @xref{Package Installation}. - - For information about turning an Emacs Lisp program into an -installable package, @xref{Packaging,,,elisp, The Emacs Lisp Reference -Manual}. For information about finding third-party packages and other -Emacs Lisp extensions, @xref{Packages that do not come with -Emacs,,,efaq, GNU Emacs FAQ}. - -@menu -* Package Menu:: Buffer for viewing and managing packages. -* Package Installation:: Options for package installation. -* Package Files:: Where packages are installed. -@end menu - -@node Package Menu -@section The Package Menu Buffer -@cindex package menu -@cindex built-in package -@findex list-packages - -The command @kbd{M-x list-packages} brings up the @dfn{package menu}. -This is a buffer listing all the packages that Emacs knows about, one -on each line, with the following information: - -@itemize @bullet -@item -The package name (e.g. @samp{auctex}). - -@item -The package's version number (e.g. @samp{11.86}). - -@item -The package's status---normally one of @samp{available} (can be -downloaded from the package archive), @samp{installed}, or -@samp{built-in} (included in Emacs by default). - -In some instances, the status can be @samp{held}, @samp{disabled}, or -@samp{obsolete}. @xref{Package Installation}. - -@item -A short description of the package. -@end itemize - -@noindent -The @code{list-packages} command accesses the network, to retrieve the -list of available packages from the package archive server. If the -network is unavailable, it falls back on the most recently retrieved -list. - -The following commands are available in the package menu: - -@table @kbd -@item h -Print a short message summarizing how to use the package menu -(@code{package-menu-quick-help}). - -@item ? -@itemx @key{RET} -Display a help buffer for the package on the current line -(@code{package-menu-describe-package}), similar to the help window -displayed by the @kbd{C-h P} command (@pxref{Packages}). - -@item i -Mark the package on the current line for installation -(@code{package-menu-mark-install}). If the package status is -@samp{available}, this adds an @samp{I} character to the start of the -line; typing @kbd{x} (see below) will download and install the -package. - -@item d -Mark the package on the current line for deletion -(@code{package-menu-mark-delete}). If the package status is -@samp{installed}, this adds a @samp{D} character to the start of the -line; typing @kbd{x} (see below) will delete the package. -@xref{Package Files}, for information about what package deletion -entails. - -@item u -Remove any installation or deletion mark previously added to the -current line by an @kbd{i} or @kbd{d} command. - -@item U -Mark all package with a newer available version for ``upgrading'' -(@code{package-menu-mark-upgrades}). This places an installation mark -on the new available versions, and a deletion mark on the old -installed versions. - -@item x -Download and install all packages marked with @kbd{i}, and their -dependencies; also, delete all packages marked with @kbd{d} -(@code{package-menu-execute}). This also removes the marks. - -@item r -Refresh the package list (@code{package-menu-refresh}). This fetches -the list of available packages from the package archive again, and -recomputes the package list. -@end table - -@noindent -For example, you can install a package by typing @kbd{i} on the line -listing that package, followed by @kbd{x}. - -@node Package Installation -@section Package Installation - -@findex package-install - Packages are most conveniently installed using the package menu -(@pxref{Package Menu}), but you can also use the command @kbd{M-x -package-install}. This prompts for the name of a package with the -@samp{available} status, then downloads and installs it. - -@cindex package requirements - A package may @dfn{require} certain other packages to be installed, -because it relies on functionality provided by them. When Emacs -installs such a package, it also automatically downloads and installs -any required package that is not already installed. (If a required -package is somehow unavailable, Emacs signals an error and stops -installation.) A package's requirements list is shown in its help -buffer. - -@vindex package-archives - By default, packages are downloaded from a single package archive -maintained by the Emacs developers. This is controlled by the -variable @code{package-archives}, whose value is a list of package -archives known to Emacs. Each list element must have the form -@code{(@var{id} . @var{location})}, where @var{id} is the name of a -package archive and @var{location} is the @acronym{HTTP} address or -directory name of the package archive. You can alter this list if you -wish to use third party package archives---but do so at your own risk, -and use only third parties that you think you can trust! - - Once a package is downloaded and installed, it is @dfn{loaded} into -the current Emacs session. Loading a package is not quite the same as -loading a Lisp library (@pxref{Lisp Libraries}); its effect varies -from package to package. Most packages just make some new commands -available, while others have more wide-ranging effects on the Emacs -session. For such information, consult the package's help buffer. - - By default, Emacs also automatically loads all installed packages in -subsequent Emacs sessions. This happens at startup, after processing -the init file (@pxref{Init File}). As an exception, Emacs does not -load packages at startup if invoked with the @samp{-q} or -@samp{--no-init-file} options (@pxref{Initial Options}). - -@vindex package-enable-at-startup - To disable automatic package loading, change the variable -@code{package-enable-at-startup} to @code{nil}. - -@findex package-initialize - The reason automatic package loading occurs after loading the init -file is that user options only receive their customized values after -loading the init file, including user options which affect the -packaging system. In some circumstances, you may want to load -packages explicitly in your init file (usually because some other code -in your init file depends on a package). In that case, your init file -should call the function @code{package-initialize}. It is up to you -to ensure that relevant user options, such as @code{package-load-list} -(see below), are set up prior to the @code{package-initialize} call. -You should also set @code{package-enable-at-startup} to @code{nil}, to -avoid loading the packages again after processing the init file. -Alternatively, you may choose to completely inhibit package loading at -startup, and invoke the command @kbd{M-x package-initialize} to load -your packages manually. - -@vindex package-load-list - For finer control over package loading, you can use the variable -@code{package-load-list}. Its value should be a list. A list element -of the form @code{(@var{name} @var{version})} tells Emacs to load -version @var{version} of the package named @var{name}. Here, -@var{version} should be a version string (corresponding to a specific -version of the package), or @code{t} (which means to load any -installed version), or @code{nil} (which means no version; this -``disables'' the package, preventing it from being loaded). A list -element can also be the symbol @code{all}, which means to load the -latest installed version of any package not named by the other list -elements. The default value is just @code{'(all)}. - - For example, if you set @code{package-load-list} to @code{'((muse -"3.20") all)}, then Emacs only loads version 3.20 of the @samp{muse} -package, plus any installed version of packages other than -@samp{muse}. Any other version of @samp{muse} that happens to be -installed will be ignored. The @samp{muse} package will be listed in -the package menu with the @samp{held} status. - -@node Package Files -@section Package Files and Directory Layout -@cindex package directory - -@cindex package file -@findex package-install-file - Each package is downloaded from the package archive in the form of a -single @dfn{package file}---either an Emacs Lisp source file, or a tar -file containing multiple Emacs Lisp source and other files. Package -files are automatically retrieved, processed, and disposed of by the -Emacs commands that install packages. Normally, you will not need to -deal directly with them, unless you are making a package -(@pxref{Packaging,,,elisp, The Emacs Lisp Reference Manual}). Should -you ever need to install a package directly from a package file, use -the command @kbd{M-x package-install-file}. - -@vindex package-user-dir - Once installed, the contents of a package are placed in a -subdirectory of @file{~/.emacs.d/elpa/} (you can change the name of -that directory by changing the variable @code{package-user-dir}). The -package subdirectory is named @file{@var{name}-@var{version}}, where -@var{name} is the package name and @var{version} is its version -string. - -@cindex system-wide packages -@vindex package-directory-list - In addition to @code{package-user-dir}, Emacs looks for installed -packages in the directories listed in @code{package-directory-list}. -These directories are meant for system administrators to make Emacs -packages available system-wide; Emacs itself never installs packages -there. The package subdirectories for @code{package-directory-list} -are laid out in the same way as in @code{package-user-dir}. - - Deleting a package (@pxref{Package Menu}) involves deleting the -corresponding package subdirectory. This only works for packages -installed in @code{package-user-dir}; if told to act on a package in a -system-wide package directory, the deletion command signals an error. diff --git a/doc/emacs/picture-xtra.texi b/doc/emacs/picture-xtra.texi deleted file mode 100644 index edf75f078d5..00000000000 --- a/doc/emacs/picture-xtra.texi +++ /dev/null @@ -1,289 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Picture Mode -@section Editing Pictures -@cindex pictures -@cindex making pictures out of text characters -@findex picture-mode - - To edit a picture made out of text characters (for example, a picture -of the division of a register into fields, as a comment in a program), -use the command @kbd{M-x picture-mode} to enter Picture mode. - - In Picture mode, editing is based on the @dfn{quarter-plane} model of -text, according to which the text characters lie studded on an area that -stretches infinitely far to the right and downward. The concept of the end -of a line does not exist in this model; the most you can say is where the -last nonblank character on the line is found. - - Of course, Emacs really always considers text as a sequence of -characters, and lines really do have ends. But Picture mode replaces -the most frequently-used commands with variants that simulate the -quarter-plane model of text. They do this by inserting spaces or by -converting tabs to spaces. - - Most of the basic editing commands of Emacs are redefined by Picture mode -to do essentially the same thing but in a quarter-plane way. In addition, -Picture mode defines various keys starting with the @kbd{C-c} prefix to -run special picture editing commands. - - One of these keys, @kbd{C-c C-c}, is particularly important. Often -a picture is part of a larger file that is usually edited in some -other major mode. Picture mode records the name of the previous major -mode so you can use the @kbd{C-c C-c} command -(@code{picture-mode-exit}) later to go back to that mode. @kbd{C-c -C-c} also deletes spaces from the ends of lines, unless given a -numeric argument. - - The special commands of Picture mode all work in other modes (provided -the @file{picture} library is loaded), but are not bound to keys except -in Picture mode. The descriptions below talk of moving ``one column'' -and so on, but all the picture mode commands handle numeric arguments as -their normal equivalents do. - -@vindex picture-mode-hook - Turning on Picture mode runs the hook @code{picture-mode-hook}. -Additional extensions to Picture mode can be found in -@file{artist.el}. - -@menu -* Basic Picture:: Basic concepts and simple commands of Picture Mode. -* Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. -* Tabs in Picture:: Various features for tab stops and indentation. -* Rectangles in Picture:: Clearing and superimposing rectangles. -@end menu - -@node Basic Picture -@subsection Basic Editing in Picture Mode - -@findex picture-forward-column -@findex picture-backward-column -@findex picture-move-down -@findex picture-move-up -@cindex editing in Picture mode - - Most keys do the same thing in Picture mode that they usually do, but -do it in a quarter-plane style. For example, @kbd{C-f} is rebound to -run @code{picture-forward-column}, a command which moves point one -column to the right, inserting a space if necessary so that the actual -end of the line makes no difference. @kbd{C-b} is rebound to run -@code{picture-backward-column}, which always moves point left one -column, converting a tab to multiple spaces if necessary. @kbd{C-n} and -@kbd{C-p} are rebound to run @code{picture-move-down} and -@code{picture-move-up}, which can either insert spaces or convert tabs -as necessary to make sure that point stays in exactly the same column. -@kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last -nonblank character on the line. @kbd{C-a} runs -@code{picture-beginning-of-line}. (The choice of screen model does not -affect beginnings of lines; the only extra thing this command does is -update the current picture column to 0.) - -@findex picture-newline - Insertion of text is adapted to the quarter-plane screen model -through the use of Overwrite mode -@iftex -(@pxref{Minor Modes,,, emacs, the Emacs Manual}.) -@end iftex -@ifnottex -(@pxref{Minor Modes}.) -@end ifnottex -Self-inserting characters replace existing text, column by column, -rather than pushing existing text to the right. @key{RET} runs -@code{picture-newline}, which just moves to the beginning of the -following line so that new text will replace that line. - -@findex picture-backward-clear-column -@findex picture-clear-column -@findex picture-clear-line - In Picture mode, the commands that normally delete or kill text, -instead erase text (replacing it with spaces). @key{DEL} -(@code{picture-backward-clear-column}) replaces the preceding -character with a space rather than removing it; this moves point -backwards. @kbd{C-d} (@code{picture-clear-column}) replaces the next -character or characters with spaces, but does not move point. (If you -want to clear characters to spaces and move forward over them, use -@key{SPC}.) @kbd{C-k} (@code{picture-clear-line}) really kills the -contents of lines, but does not delete the newlines from the buffer. - -@findex picture-open-line - To do actual insertion, you must use special commands. @kbd{C-o} -(@code{picture-open-line}) creates a blank line after the current -line; it never splits a line. @kbd{C-M-o} (@code{split-line}) makes -sense in Picture mode, so it is not changed. @kbd{C-j} -(@code{picture-duplicate-line}) inserts another line with the same -contents below the current line. - -@kindex C-c C-d @r{(Picture mode)} - To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d} -(which is defined as @code{delete-char}, as @kbd{C-d} is in other -modes), or one of the picture rectangle commands (@pxref{Rectangles in -Picture}). - -@node Insert in Picture -@subsection Controlling Motion after Insert - -@findex picture-movement-up -@findex picture-movement-down -@findex picture-movement-left -@findex picture-movement-right -@findex picture-movement-nw -@findex picture-movement-ne -@findex picture-movement-sw -@findex picture-movement-se -@kindex C-c < @r{(Picture mode)} -@kindex C-c > @r{(Picture mode)} -@kindex C-c ^ @r{(Picture mode)} -@kindex C-c . @r{(Picture mode)} -@kindex C-c ` @r{(Picture mode)} -@kindex C-c ' @r{(Picture mode)} -@kindex C-c / @r{(Picture mode)} -@kindex C-c \ @r{(Picture mode)} - Since ``self-inserting'' characters in Picture mode overwrite and move -point, there is no essential restriction on how point should be moved. -Normally point moves right, but you can specify any of the eight -orthogonal or diagonal directions for motion after a ``self-inserting'' -character. This is useful for drawing lines in the buffer. - -@table @kbd -@item C-c < -@itemx C-c @key{LEFT} -Move left after insertion (@code{picture-movement-left}). -@item C-c > -@itemx C-c @key{RIGHT} -Move right after insertion (@code{picture-movement-right}). -@item C-c ^ -@itemx C-c @key{UP} -Move up after insertion (@code{picture-movement-up}). -@item C-c . -@itemx C-c @key{DOWN} -Move down after insertion (@code{picture-movement-down}). -@item C-c ` -@itemx C-c @key{HOME} -Move up and left (``northwest'') after insertion (@code{picture-movement-nw}). -@item C-c ' -@itemx C-c @key{prior} -Move up and right (``northeast'') after insertion -(@code{picture-movement-ne}). -@item C-c / -@itemx C-c @key{END} -Move down and left (``southwest'') after insertion -@*(@code{picture-movement-sw}). -@item C-c \ -@itemx C-c @key{next} -Move down and right (``southeast'') after insertion -@*(@code{picture-movement-se}). -@end table - -@kindex C-c C-f @r{(Picture mode)} -@kindex C-c C-b @r{(Picture mode)} -@findex picture-motion -@findex picture-motion-reverse - Two motion commands move based on the current Picture insertion -direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the -same direction as motion after ``insertion'' currently does, while @kbd{C-c -C-b} (@code{picture-motion-reverse}) moves in the opposite direction. - -@node Tabs in Picture -@subsection Picture Mode Tabs - -@kindex M-TAB @r{(Picture mode)} -@findex picture-tab-search -@vindex picture-tab-chars - Two kinds of tab-like action are provided in Picture mode. Use -@kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing. -With no argument, it moves to a point underneath the next -``interesting'' character that follows whitespace in the previous -nonblank line. ``Next'' here means ``appearing at a horizontal position -greater than the one point starts out at''. With an argument, as in -@kbd{C-u M-@key{TAB}}, this command moves to the next such interesting -character in the current line. @kbd{M-@key{TAB}} does not change the -text; it only moves point. ``Interesting'' characters are defined by -the variable @code{picture-tab-chars}, which should define a set of -characters. The syntax for this variable is like the syntax used inside -of @samp{[@dots{}]} in a regular expression---but without the @samp{[} -and the @samp{]}. Its default value is @code{"!-~"}. - -@findex picture-tab - @key{TAB} itself runs @code{picture-tab}, which operates based on the -current tab stop settings; it is the Picture mode equivalent of -@code{tab-to-tab-stop}. Normally it just moves point, but with a numeric -argument it clears the text that it moves over. - -@kindex C-c TAB @r{(Picture mode)} -@findex picture-set-tab-stops - The context-based and tab-stop-based forms of tabbing are brought -together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}). -This command sets the tab stops to the positions which @kbd{M-@key{TAB}} -would consider significant in the current line. The use of this command, -together with @key{TAB}, can get the effect of context-based tabbing. But -@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient. - - It may be convenient to prevent use of actual tab characters in -pictures. For example, this prevents @kbd{C-x @key{TAB}} from messing -up the picture. You can do this by setting the variable -@code{indent-tabs-mode} to @code{nil}. - -@node Rectangles in Picture -@subsection Picture Mode Rectangle Commands -@cindex rectangles and Picture mode -@cindex Picture mode and rectangles - - Picture mode defines commands for working on rectangular pieces of -the text in ways that fit with the quarter-plane model. The standard -rectangle commands may also be useful. -@iftex -@xref{Rectangles,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Rectangles}. -@end ifnottex - -@table @kbd -@item C-c C-k -Clear out the region-rectangle with spaces -(@code{picture-clear-rectangle}). With a prefix argument, delete the -text. -@item C-c C-w @var{r} -Similar, but save rectangle contents in register @var{r} first -(@code{picture-clear-rectangle-to-register}). -@item C-c C-y -Copy last killed rectangle into the buffer by overwriting, with upper -left corner at point (@code{picture-yank-rectangle}). With argument, -insert instead. -@item C-c C-x @var{r} -Similar, but use the rectangle in register @var{r} -(@code{picture-yank-rectangle-from-register}). -@end table - -@kindex C-c C-k @r{(Picture mode)} -@kindex C-c C-w @r{(Picture mode)} -@findex picture-clear-rectangle -@findex picture-clear-rectangle-to-register - The picture rectangle commands @kbd{C-c C-k} -(@code{picture-clear-rectangle}) and @kbd{C-c C-w} -(@code{picture-clear-rectangle-to-register}) differ from the standard -rectangle commands in that they normally clear the rectangle instead of -deleting it; this is analogous with the way @kbd{C-d} is changed in Picture -mode. - - However, deletion of rectangles can be useful in Picture mode, so -these commands delete the rectangle if given a numeric argument. -@kbd{C-c C-k} either with or without a numeric argument saves the -rectangle for @kbd{C-c C-y}. - -@kindex C-c C-y @r{(Picture mode)} -@kindex C-c C-x @r{(Picture mode)} -@findex picture-yank-rectangle -@findex picture-yank-rectangle-from-register - The Picture mode commands for yanking rectangles differ from the -standard ones in that they overwrite instead of inserting. This is -the same way that Picture mode insertion of other text differs from -other modes. @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts -(by overwriting) the rectangle that was most recently killed, while -@kbd{C-c C-x} (@code{picture-yank-rectangle-from-register}) does -likewise for the rectangle found in a specified register. diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi deleted file mode 100644 index b7f21e8a93c..00000000000 --- a/doc/emacs/programs.texi +++ /dev/null @@ -1,1787 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Programs, Building, Text, Top -@chapter Editing Programs -@cindex Lisp editing -@cindex C editing -@cindex program editing - - This chapter describes Emacs features for facilitating editing -programs. Some of the things these features can do are: - -@itemize @bullet -@item -Find or move over top-level definitions (@pxref{Defuns}). -@item -Apply the usual indentation conventions of the language -(@pxref{Program Indent}). -@item -Balance parentheses (@pxref{Parentheses}). -@item -Insert, kill or align comments (@pxref{Comments}). -@item -Highlight program syntax (@pxref{Font Lock}). -@end itemize - -@menu -* Program Modes:: Major modes for editing programs. -* Defuns:: Commands to operate on major top-level parts - of a program. -* Program Indent:: Adjusting indentation to show the nesting. -* Parentheses:: Commands that operate on parentheses. -* Comments:: Inserting, killing, and aligning comments. -* Documentation:: Getting documentation of functions you plan to call. -* Hideshow:: Displaying blocks selectively. -* Symbol Completion:: Completion on symbol names of your program or language. -* Glasses:: Making identifiersLikeThis more readable. -* Semantic:: Suite of editing tools based on source code parsing. -* Misc for Programs:: Other Emacs features useful for editing programs. -* C Modes:: Special commands of C, C++, Objective-C, Java, - IDL, Pike and AWK modes. -* Asm Mode:: Asm mode and its special features. -@ifnottex -* Fortran:: Fortran mode and its special features. -@end ifnottex -@end menu - -@node Program Modes -@section Major Modes for Programming Languages -@cindex modes for programming languages - - Emacs has specialized major modes (@pxref{Major Modes}) for many -programming languages. A programming language mode typically -specifies the syntax of expressions, the customary rules for -indentation, how to do syntax highlighting for the language, and how -to find the beginning or end of a function definition. It often has -features for compiling and debugging programs as well. The major mode -for each language is named after the language; for instance, the major -mode for the C programming language is @code{c-mode}. - -@cindex Perl mode -@cindex Icon mode -@cindex Makefile mode -@cindex Tcl mode -@cindex CPerl mode -@cindex DSSSL mode -@cindex Octave mode -@cindex Metafont mode -@cindex Modula2 mode -@cindex Prolog mode -@cindex Python mode -@cindex Ruby mode -@cindex Simula mode -@cindex VHDL mode -@cindex M4 mode -@cindex Shell-script mode -@cindex Delphi mode -@cindex PostScript mode -@cindex Conf mode -@cindex DNS mode -@cindex Javascript mode - Emacs has programming language modes for Lisp, Scheme, the -Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Delphi, -Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont -(@TeX{}'s companion for font creation), Modula2, Objective-C, Octave, -Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, and -VHDL. An alternative mode for Perl is called CPerl mode. Modes are -also available for the scripting languages of the common GNU and Unix -shells, VMS DCL, and MS-DOS/MS-Windows @samp{BAT} files, and for -makefiles, DNS master files, and various sorts of configuration files. - - Ideally, Emacs should have a major mode for each programming -language that you might want to edit. If it doesn't have a mode for -your favorite language, the mode might be implemented in a package not -distributed with Emacs (@pxref{Packages}); or you can contribute one. - -@kindex DEL @r{(programming modes)} -@findex c-electric-backspace -@findex backward-delete-char-untabify - In most programming languages, indentation should vary from line to -line to illustrate the structure of the program. Therefore, in most -programming language modes, typing @key{TAB} updates the indentation -of the current line (@pxref{Program Indent}). Furthermore, @key{DEL} -is usually bound to @code{backward-delete-char-untabify}, which -deletes backward treating each tab as if it were the equivalent number -of spaces, so that you can delete one column of indentation without -worrying whether the whitespace consists of spaces or tabs. - -@cindex mode hook -@vindex c-mode-hook -@vindex lisp-mode-hook -@vindex emacs-lisp-mode-hook -@vindex lisp-interaction-mode-hook -@vindex scheme-mode-hook - Entering a programming language mode runs the custom Lisp functions -specified in the hook variable @code{prog-mode-hook}, followed by -those specified in the mode's own mode hook (@pxref{Major Modes}). -For instance, entering C mode runs the hooks @code{prog-mode-hook} and -@code{c-mode-hook}. @xref{Hooks}, for information about hooks. - -@ifinfo - Separate manuals are available for the modes for Ada (@pxref{Top,, -Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba -IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), and IDLWAVE -(@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}). -@end ifinfo -@ifnotinfo - The Emacs distribution contains Info manuals for the major modes for -Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE. For -Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized Emacs Features}. -@end ifnotinfo - -@node Defuns -@section Top-Level Definitions, or Defuns - - In Emacs, a major definition at the top level in the buffer, such as -a function, is called a @dfn{defun}. The name comes from Lisp, but in -Emacs we use it for all languages. - -@menu -* Left Margin Paren:: An open-paren or similar opening delimiter - starts a defun if it is at the left margin. -* Moving by Defuns:: Commands to move over or mark a major definition. -* Imenu:: Making buffer indexes as menus. -* Which Function:: Which Function mode shows which function you are in. -@end menu - -@node Left Margin Paren -@subsection Left Margin Convention - -@cindex open-parenthesis in leftmost column -@cindex ( in leftmost column - Many programming-language modes assume by default that any opening -delimiter found at the left margin is the start of a top-level -definition, or defun. Therefore, @strong{don't put an opening -delimiter at the left margin unless it should have that significance}. -For instance, never put an open-parenthesis at the left margin in a -Lisp file unless it is the start of a top-level list. - - The convention speeds up many Emacs operations, which would -otherwise have to scan back to the beginning of the buffer to analyze -the syntax of the code. - - If you don't follow this convention, not only will you have trouble -when you explicitly use the commands for motion by defuns; other -features that use them will also give you trouble. This includes the -indentation commands (@pxref{Program Indent}) and Font Lock mode -(@pxref{Font Lock}). - - The most likely problem case is when you want an opening delimiter -at the start of a line inside a string. To avoid trouble, put an -escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some -other Lisp dialects) before the opening delimiter. This will not -affect the contents of the string, but will prevent that opening -delimiter from starting a defun. Here's an example: - -@example - (insert "Foo: -\(bar) -") -@end example - - To help you catch violations of this convention, Font Lock mode -highlights confusing opening delimiters (those that ought to be -quoted) in bold red. - -@vindex open-paren-in-column-0-is-defun-start - If you need to override this convention, you can do so by setting -the variable @code{open-paren-in-column-0-is-defun-start}. -If this user option is set to @code{t} (the default), opening -parentheses or braces at column zero always start defuns. When it is -@code{nil}, defuns are found by searching for parens or braces at the -outermost level. - - Usually, you should leave this option at its default value of -@code{t}. If your buffer contains parentheses or braces in column -zero which don't start defuns, and it is somehow impractical to remove -these parentheses or braces, it might be helpful to set the option to -@code{nil}. Be aware that this might make scrolling and display in -large buffers quite sluggish. Furthermore, the parentheses and braces -must be correctly matched throughout the buffer for it to work -properly. - -@node Moving by Defuns -@subsection Moving by Defuns -@cindex defuns - - These commands move point or set up the region based on top-level -major definitions, also called @dfn{defuns}. - -@table @kbd -@item C-M-a -Move to beginning of current or preceding defun -(@code{beginning-of-defun}). -@item C-M-e -Move to end of current or following defun (@code{end-of-defun}). -@item C-M-h -Put region around whole current or following defun (@code{mark-defun}). -@end table - -@cindex move to beginning or end of function -@cindex function, move to beginning or end -@kindex C-M-a -@kindex C-M-e -@kindex C-M-h -@findex beginning-of-defun -@findex end-of-defun -@findex mark-defun - The commands to move to the beginning and end of the current defun -are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} -(@code{end-of-defun}). If you repeat one of these commands, or use a -positive numeric argument, each repetition moves to the next defun in -the direction of motion. - - @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward -@var{n} times to the next beginning of a defun. This is not exactly -the same place that @kbd{C-M-e} with argument @var{n} would move to; -the end of this defun is not usually exactly the same place as the -beginning of the following defun. (Whitespace, comments, and perhaps -declarations can separate them.) Likewise, @kbd{C-M-e} with a -negative argument moves back to an end of a defun, which is not quite -the same as @kbd{C-M-a} with a positive argument. - -@kindex C-M-h @r{(C mode)} -@findex c-mark-function - To operate on the current defun, use @kbd{C-M-h} -(@code{mark-defun}), which sets the mark at the end of the current -defun and puts point at its beginning. @xref{Marking Objects}. This -is the easiest way to get ready to kill the defun in order to move it -to a different place in the file. If you use the command while point -is between defuns, it uses the following defun. If you use the -command while the mark is already active, it sets the mark but does -not move point; furthermore, each successive use of @kbd{C-M-h} -extends the end of the region to include one more defun. - - In C mode, @kbd{C-M-h} runs the function @code{c-mark-function}, -which is almost the same as @code{mark-defun}; the difference is that -it backs up over the argument declarations, function name and returned -data type so that the entire C function is inside the region. This is -an example of how major modes adjust the standard key bindings so that -they do their standard jobs in a way better fitting a particular -language. Other major modes may replace any or all of these key -bindings for that purpose. - -@node Imenu -@subsection Imenu -@cindex index of buffer definitions -@cindex buffer definitions index - - The Imenu facility offers a way to find the major definitions in -a file by name. It is also useful in text formatter major modes, -where it treats each chapter, section, etc., as a definition. -(@xref{Tags}, for a more powerful feature that handles multiple files -together.) - -@findex imenu - If you type @kbd{M-x imenu}, it reads the name of a definition using -the minibuffer, then moves point to that definition. You can use -completion to specify the name; the command always displays the whole -list of valid names. - -@findex imenu-add-menubar-index - Alternatively, you can bind the command @code{imenu} to a mouse -click. Then it displays mouse menus for you to select a definition -name. You can also add the buffer's index to the menu bar by calling -@code{imenu-add-menubar-index}. If you want to have this menu bar -item available for all buffers in a certain major mode, you can do -this by adding @code{imenu-add-menubar-index} to its mode hook. But -if you have done that, you will have to wait a little while each time -you visit a file in that mode, while Emacs finds all the definitions -in that buffer. - -@vindex imenu-auto-rescan - When you change the contents of a buffer, if you add or delete -definitions, you can update the buffer's index based on the -new contents by invoking the @samp{*Rescan*} item in the menu. -Rescanning happens automatically if you set @code{imenu-auto-rescan} to -a non-@code{nil} value. There is no need to rescan because of small -changes in the text. - -@vindex imenu-sort-function - You can customize the way the menus are sorted by setting the -variable @code{imenu-sort-function}. By default, names are ordered as -they occur in the buffer; if you want alphabetic sorting, use the -symbol @code{imenu--sort-by-name} as the value. You can also -define your own comparison function by writing Lisp code. - - Imenu provides the information to guide Which Function mode -@ifnottex -(@pxref{Which Function}). -@end ifnottex -@iftex -(see below). -@end iftex -The Speedbar can also use it (@pxref{Speedbar}). - -@node Which Function -@subsection Which Function Mode -@cindex current function name in mode line - - Which Function mode is a global minor mode (@pxref{Minor Modes}) -which displays the current function name in the mode line, updating it -as you move around in a buffer. - -@findex which-function-mode -@vindex which-func-modes - To either enable or disable Which Function mode, use the command -@kbd{M-x which-function-mode}. Although Which Function mode is a -global minor mode, it takes effect only in certain major modes: those -listed in the variable @code{which-func-modes}. If the value of -@code{which-func-modes} is @code{t} rather than a list of modes, then -Which Function mode applies to all major modes that know how to -support it---in other words, all the major modes that support Imenu. - -@node Program Indent -@section Indentation for Programs -@cindex indentation for programs - - The best way to keep a program properly indented is to use Emacs to -reindent it as you change it. Emacs has commands to indent either a -single line, a specified number of lines, or all of the lines inside a -single parenthetical grouping. - - @xref{Indentation}, for general information about indentation. This -section describes indentation features specific to programming -language modes. - -@menu -* Basic Indent:: Indenting a single line. -* Multi-line Indent:: Commands to reindent many lines at once. -* Lisp Indent:: Specifying how each Lisp function should be indented. -* C Indent:: Extra features for indenting C and related modes. -* Custom C Indent:: Controlling indentation style for C and related modes. -@end menu - -@cindex pretty-printer - Emacs also provides a Lisp pretty-printer in the @code{pp} package, -which reformats Lisp objects with nice-looking indentation. - -@node Basic Indent -@subsection Basic Program Indentation Commands - -@table @kbd -@item @key{TAB} -Adjust indentation of current line (@code{indent-for-tab-command}). -@item C-j -Insert a newline, then adjust indentation of following line -(@code{newline-and-indent}). -@end table - -@kindex TAB @r{(programming modes)} -@findex c-indent-command -@findex indent-line-function -@findex indent-for-tab-command - The basic indentation command is @key{TAB} -(@code{indent-for-tab-command}), which was documented in -@ref{Indentation}. In programming language modes, @key{TAB} indents -the current line, based on the indentation and syntactic content of -the preceding lines; if the region is active, @key{TAB} indents each -line within the region, not just the current line. - -@kindex C-j @r{(indenting source code)} -@findex newline-and-indent - The command @kbd{C-j} (@code{newline-and-indent}), which was -documented in @ref{Indentation Commands}, does the same as @key{RET} -followed by @key{TAB}: it inserts a new line, then adjusts the line's -indentation. - - When indenting a line that starts within a parenthetical grouping, -Emacs usually places the start of the line under the preceding line -within the group, or under the text after the parenthesis. If you -manually give one of these lines a nonstandard indentation (e.g.@: for -aesthetic purposes), the lines below will follow it. - - The indentation commands for most programming language modes assume -that a open-parenthesis, open-brace or other opening delimiter at the -left margin is the start of a function. If the code you are editing -violates this assumption---even if the delimiters occur in strings or -comments---you must set @code{open-paren-in-column-0-is-defun-start} -to @code{nil} for indentation to work properly. @xref{Left Margin -Paren}. - -@node Multi-line Indent -@subsection Indenting Several Lines - - Sometimes, you may want to reindent several lines of code at a time. -One way to do this is to use the mark; when the mark is active and the -region is non-empty, @key{TAB} indents every line in the region. -Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents -every line in the region, whether or not the mark is active -(@pxref{Indentation Commands}). - - In addition, Emacs provides the following commands for indenting -large chunks of code: - -@table @kbd -@item C-M-q -Reindent all the lines within one parenthetical grouping. -@item C-u @key{TAB} -Shift an entire parenthetical grouping rigidly sideways so that its -first line is properly indented. -@item M-x indent-code-rigidly -Shift all the lines in the region rigidly sideways, but do not alter -lines that start inside comments and strings. -@end table - -@kindex C-M-q -@findex indent-pp-sexp - To reindent the contents of a single parenthetical grouping, -position point before the beginning of the grouping and type -@kbd{C-M-q}. This changes the relative indentation within the -grouping, without affecting its overall indentation (i.e.@: the -indentation of the line where the grouping starts). The function that -@kbd{C-M-q} runs depends on the major mode; it is -@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode, -etc. To correct the overall indentation as well, type @key{TAB} -first. - -@kindex C-u TAB - If you like the relative indentation within a grouping but not the -indentation of its first line, move point to that first line and type -@kbd{C-u @key{TAB}}. In Lisp, C, and some other major modes, -@key{TAB} with a numeric argument reindents the current line as usual, -then reindents by the same amount all the lines in the parenthetical -grouping starting on the current line. It is clever, though, and does -not alter lines that start inside strings. Neither does it alter C -preprocessor lines when in C mode, but it does reindent any -continuation lines that may be attached to them. - -@findex indent-code-rigidly - The command @kbd{M-x indent-code-rigidly} rigidly shifts all the -lines in the region sideways, like @code{indent-rigidly} does -(@pxref{Indentation Commands}). It doesn't alter the indentation of -lines that start inside a string, unless the region also starts inside -that string. The prefix arg specifies the number of columns to -indent. - -@node Lisp Indent -@subsection Customizing Lisp Indentation -@cindex customizing Lisp indentation - - The indentation pattern for a Lisp expression can depend on the function -called by the expression. For each Lisp function, you can choose among -several predefined patterns of indentation, or define an arbitrary one with -a Lisp program. - - The standard pattern of indentation is as follows: the second line of the -expression is indented under the first argument, if that is on the same -line as the beginning of the expression; otherwise, the second line is -indented underneath the function name. Each following line is indented -under the previous line whose nesting depth is the same. - -@vindex lisp-indent-offset - If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides -the usual indentation pattern for the second line of an expression, so that -such lines are always indented @code{lisp-indent-offset} more columns than -the containing list. - -@vindex lisp-body-indent - Certain functions override the standard pattern. Functions whose -names start with @code{def} treat the second lines as the start of -a @dfn{body}, by indenting the second line @code{lisp-body-indent} -additional columns beyond the open-parenthesis that starts the -expression. - -@cindex @code{lisp-indent-function} property - You can override the standard pattern in various ways for individual -functions, according to the @code{lisp-indent-function} property of -the function name. This is normally done for macro definitions, using -the @code{declare} construct. @xref{Defining Macros,,, elisp, the -Emacs Lisp Reference Manual}. - -@node C Indent -@subsection Commands for C Indentation - - Here are special features for indentation in C mode and related modes: - -@table @code -@item C-c C-q -@kindex C-c C-q @r{(C mode)} -@findex c-indent-defun -Reindent the current top-level function definition or aggregate type -declaration (@code{c-indent-defun}). - -@item C-M-q -@kindex C-M-q @r{(C mode)} -@findex c-indent-exp -Reindent each line in the balanced expression that follows point -(@code{c-indent-exp}). A prefix argument inhibits warning messages -about invalid syntax. - -@item @key{TAB} -@findex c-indent-command -Reindent the current line, and/or in some cases insert a tab character -(@code{c-indent-command}). - -@vindex c-tab-always-indent -If @code{c-tab-always-indent} is @code{t}, this command always reindents -the current line and does nothing else. This is the default. - -If that variable is @code{nil}, this command reindents the current line -only if point is at the left margin or in the line's indentation; -otherwise, it inserts a tab (or the equivalent number of spaces, -if @code{indent-tabs-mode} is @code{nil}). - -Any other value (not @code{nil} or @code{t}) means always reindent the -line, and also insert a tab if within a comment or a string. -@end table - - To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This -first selects the whole buffer as the region, then reindents that -region. - - To reindent the current block, use @kbd{C-M-u C-M-q}. This moves -to the front of the block and then reindents it all. - -@node Custom C Indent -@subsection Customizing C Indentation -@cindex style (for indentation) - - C mode and related modes use a flexible mechanism for customizing -indentation. C mode indents a source line in two steps: first it -classifies the line syntactically according to its contents and -context; second, it determines the indentation offset associated by -your selected @dfn{style} with the syntactic construct and adds this -onto the indentation of the @dfn{anchor statement}. - -@table @kbd -@item C-c . @key{RET} @var{style} @key{RET} -Select a predefined style @var{style} (@code{c-set-style}). -@end table - - A @dfn{style} is a named collection of customizations that can be -used in C mode and the related modes. @ref{Styles,,, ccmode, The CC -Mode Manual}, for a complete description. Emacs comes with several -predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, -@code{stroustrup}, @code{linux}, @code{python}, @code{java}, -@code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these -styles are primarily intended for one language, but any of them can be -used with any of the languages supported by these modes. To find out -what a style looks like, select it and reindent some code, e.g., by -typing @key{C-M-q} at the start of a function definition. - -@kindex C-c . @r{(C mode)} -@findex c-set-style - To choose a style for the current buffer, use the command @w{@kbd{C-c -.}}. Specify a style name as an argument (case is not significant). -This command affects the current buffer only, and it affects only -future invocations of the indentation commands; it does not reindent -the code already in the buffer. To reindent the whole buffer in the -new style, you can type @kbd{C-x h C-M-\}. - -@vindex c-default-style - You can also set the variable @code{c-default-style} to specify the -default style for various major modes. Its value should be either the -style's name (a string) or an alist, in which each element specifies -one major mode and which indentation style to use for it. For -example, - -@example -(setq c-default-style - '((java-mode . "java") - (awk-mode . "awk") - (other . "gnu"))) -@end example - -@noindent -specifies explicit choices for Java and AWK modes, and the default -@samp{gnu} style for the other C-like modes. (These settings are -actually the defaults.) This variable takes effect when you select -one of the C-like major modes; thus, if you specify a new default -style for Java mode, you can make it take effect in an existing Java -mode buffer by typing @kbd{M-x java-mode} there. - - The @code{gnu} style specifies the formatting recommended by the GNU -Project for C; it is the default, so as to encourage use of our -recommended style. - - @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and -@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more -information on customizing indentation for C and related modes, -including how to override parts of an existing style and how to define -your own styles. - -@findex c-guess -@findex c-guess-install - As an alternative to specifying a style, you can tell Emacs to guess -a style by typing @kbd{M-x c-guess} in a sample code buffer. You can -then apply the guessed style to other buffers with @kbd{M-x -c-guess-install}. @xref{Guessing the Style,,, ccmode, the CC Mode -Manual}, for details. - -@node Parentheses -@section Commands for Editing with Parentheses - -@findex check-parens -@cindex unbalanced parentheses and quotes - This section describes the commands and features that take advantage -of the parenthesis structure in a program, or help you keep it -balanced. - - When talking about these facilities, the term ``parenthesis'' also -includes braces, brackets, or whatever delimiters are defined to match -in pairs. The major mode controls which delimiters are significant, -through the syntax table (@pxref{Syntax Tables,, Syntax Tables, elisp, -The Emacs Lisp Reference Manual}). In Lisp, only parentheses count; -in C, these commands apply to braces and brackets too. - - You can use @kbd{M-x check-parens} to find any unbalanced -parentheses and unbalanced string quotes in the buffer. - -@menu -* Expressions:: Expressions with balanced parentheses. -* Moving by Parens:: Commands for moving up, down and across - in the structure of parentheses. -* Matching:: Insertion of a close-delimiter flashes matching open. -@end menu - -@node Expressions -@subsection Expressions with Balanced Parentheses - -@cindex sexp -@cindex expression -@cindex balanced expression - Each programming language mode has its own definition of a -@dfn{balanced expression}. Balanced expressions typically include -individual symbols, numbers, and string constants, as well as pieces -of code enclosed in a matching pair of delimiters. The following -commands deal with balanced expressions (in Emacs, such expressions -are referred to internally as @dfn{sexps}@footnote{The word ``sexp'' -is used to refer to an expression in Lisp.}). - -@table @kbd -@item C-M-f -Move forward over a balanced expression (@code{forward-sexp}). -@item C-M-b -Move backward over a balanced expression (@code{backward-sexp}). -@item C-M-k -Kill balanced expression forward (@code{kill-sexp}). -@item C-M-t -Transpose expressions (@code{transpose-sexps}). -@item C-M-@@ -@itemx C-M-@key{SPC} -Put mark after following expression (@code{mark-sexp}). -@end table - -@kindex C-M-f -@kindex C-M-b -@findex forward-sexp -@findex backward-sexp - To move forward over a balanced expression, use @kbd{C-M-f} -(@code{forward-sexp}). If the first significant character after point -is an opening delimiter (e.g.@: @samp{(}, @samp{[} or @samp{@{} in C), -this command moves past the matching closing delimiter. If the -character begins a symbol, string, or number, the command moves over -that. - - The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a -balanced expression---like @kbd{C-M-f}, but in the reverse direction. -If the expression is preceded by any prefix characters (single-quote, -backquote and comma, in Lisp), the command moves back over them as -well. - - @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation -the specified number of times; with a negative argument means to move -in the opposite direction. In most modes, these two commands move -across comments as if they were whitespace. Note that their keys, -@kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b}, -which move by characters (@pxref{Moving Point}), and @kbd{M-f} and -@kbd{M-b}, which move by words (@pxref{Words}). - -@cindex killing expressions -@kindex C-M-k -@findex kill-sexp - To kill a whole balanced expression, type @kbd{C-M-k} -(@code{kill-sexp}). This kills the text that @kbd{C-M-f} would move -over. - -@cindex transposition of expressions -@kindex C-M-t -@findex transpose-sexps - @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the -previous balanced expression and the next one. It is analogous to the -@kbd{C-t} command, which transposes characters (@pxref{Transpose}). -An argument to @kbd{C-M-t} serves as a repeat count, moving the -previous expression over that many following ones. A negative -argument moves the previous balanced expression backwards across those -before it. An argument of zero, rather than doing nothing, transposes -the balanced expressions ending at or after point and the mark. - -@kindex C-M-@@ -@kindex C-M-@key{SPC} -@findex mark-sexp - To operate on balanced expressions with a command which acts on the -region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}). This sets the -mark where @kbd{C-M-f} would move to. While the mark is active, each -successive call to this command extends the region by shifting the -mark by one expression. Positive or negative numeric arguments move -the mark forward or backward by the specified number of expressions. -The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}. -@xref{Marking Objects}, for more information about this and related -commands. - - In languages that use infix operators, such as C, it is not possible -to recognize all balanced expressions because there can be multiple -possibilities at a given position. For example, C mode does not treat -@samp{foo + bar} as a single expression, even though it @emph{is} one -C expression; instead, it recognizes @samp{foo} as one expression and -@samp{bar} as another, with the @samp{+} as punctuation between them. -However, C mode recognizes @samp{(foo + bar)} as a single expression, -because of the parentheses. - -@node Moving by Parens -@subsection Moving in the Parenthesis Structure - -@cindex parenthetical groupings -@cindex parentheses, moving across -@cindex matching parenthesis and braces, moving to -@cindex braces, moving across -@cindex list commands - - The following commands move over groupings delimited by parentheses -(or whatever else serves as delimiters in the language you are working -with). They ignore strings and comments, including any parentheses -within them, and also ignore parentheses that are ``quoted'' with an -escape character. These commands are mainly intended for editing -programs, but can be useful for editing any text containing -parentheses. They are referred to internally as ``list'' commands -because in Lisp these groupings are lists. - - These commands assume that the starting point is not inside a string -or a comment. If you invoke them from inside a string or comment, the -results are unreliable. - -@table @kbd -@item C-M-n -Move forward over a parenthetical group (@code{forward-list}). -@item C-M-p -Move backward over a parenthetical group (@code{backward-list}). -@item C-M-u -Move up in parenthesis structure (@code{backward-up-list}). -@item C-M-d -Move down in parenthesis structure (@code{down-list}). -@end table - -@kindex C-M-n -@kindex C-M-p -@findex forward-list -@findex backward-list - The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and -@kbd{C-M-p} (@code{backward-list}) move forward or backward over one -(or @var{n}) parenthetical groupings. - -@kindex C-M-u -@findex backward-up-list - @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the -parenthesis structure. To move @emph{up} one (or @var{n}) levels, use -@kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up -past one unmatched opening delimiter. A positive argument serves as a -repeat count; a negative argument reverses the direction of motion, so -that the command moves forward and up one or more levels. - -@kindex C-M-d -@findex down-list - To move @emph{down} in the parenthesis structure, use @kbd{C-M-d} -(@code{down-list}). In Lisp mode, where @samp{(} is the only opening -delimiter, this is nearly the same as searching for a @samp{(}. An -argument specifies the number of levels to go down. - -@node Matching -@subsection Matching Parentheses -@cindex matching parentheses -@cindex parentheses, displaying matches - - Emacs has a number of @dfn{parenthesis matching} features, which -make it easy to see how and whether parentheses (or other delimiters) -match up. - - Whenever you type a self-inserting character that is a closing -delimiter, the cursor moves momentarily to the location of the -matching opening delimiter, provided that is on the screen. If it is -not on the screen, Emacs displays some of the text near it in the echo -area. Either way, you can tell which grouping you are closing off. -If the opening delimiter and closing delimiter are mismatched---such -as in @samp{[x)}---a warning message is displayed in the echo area. - -@vindex blink-matching-paren -@vindex blink-matching-paren-distance -@vindex blink-matching-delay - Three variables control the display of matching parentheses: - -@itemize @bullet -@item -@code{blink-matching-paren} turns the feature on or off: @code{nil} -disables it, but the default is @code{t} to enable it. - -@item -@code{blink-matching-delay} says how many seconds to leave the cursor -on the matching opening delimiter, before bringing it back to the real -location of point. This may be an integer or floating-point number; -the default is 1. - -@item -@code{blink-matching-paren-distance} specifies how many characters -back to search to find the matching opening delimiter. If the match -is not found in that distance, Emacs stops scanning and nothing is -displayed. The default is 102400. -@end itemize - -@cindex Show Paren mode -@cindex highlighting matching parentheses -@findex show-paren-mode - Show Paren mode, a global minor mode, provides a more powerful kind -of automatic matching. Whenever point is before an opening delimiter -or after a closing delimiter, both that delimiter and its opposite -delimiter are highlighted. To toggle Show Paren mode, type @kbd{M-x -show-paren-mode}. - -@cindex Electric Pair mode -@cindex inserting matching parentheses -@findex electric-pair-mode - Electric Pair mode, a global minor mode, provides a way to easily -insert matching delimiters. Whenever you insert an opening delimiter, -the matching closing delimiter is automatically inserted as well, -leaving point between the two. To toggle Electric Pair mode, type -@kbd{M-x electric-pair-mode}. - -@node Comments -@section Manipulating Comments -@cindex comments - - Because comments are such an important part of programming, Emacs -provides special commands for editing and inserting comments. It can -also do spell checking on comments with Flyspell Prog mode -(@pxref{Spelling}). - - Some major modes have special rules for indenting different kinds of -comments. For example, in Lisp code, comments starting with two -semicolons are indented as if they were lines of code, while those -starting with three semicolons are supposed to be aligned to the left -margin and are often used for sectioning purposes. Emacs understand -these conventions; for instance, typing @key{TAB} on a comment line -will indent the comment to the appropriate position. - -@example -;; This function is just an example. -;;; Here either two or three semicolons are appropriate. -(defun foo (x) -;;; And now, the first part of the function: - ;; The following line adds one. - (1+ x)) ; This line adds one. -@end example - -@menu -* Comment Commands:: Inserting, killing, and aligning comments. -* Multi-Line Comments:: Commands for adding and editing multi-line comments. -* Options for Comments::Customizing the comment features. -@end menu - -@node Comment Commands -@subsection Comment Commands -@cindex indentation for comments -@cindex alignment for comments - - The following commands operate on comments: - -@table @asis -@item @kbd{M-;} -Insert or realign comment on current line; if the region is active, -comment or uncomment the region instead (@code{comment-dwim}). -@item @kbd{C-u M-;} -Kill comment on current line (@code{comment-kill}). -@item @kbd{C-x ;} -Set comment column (@code{comment-set-column}). -@item @kbd{C-M-j} -@itemx @kbd{M-j} -Like @key{RET} followed by inserting and aligning a comment -(@code{comment-indent-new-line}). @xref{Multi-Line Comments}. -@item @kbd{M-x comment-region} -@itemx @kbd{C-c C-c} (in C-like modes) -Add comment delimiters to all the lines in the region. -@end table - -@kindex M-; -@findex comment-dwim - The command to create or align a comment is @kbd{M-;} -(@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What -I Mean''; it indicates that this command can be used for many -different jobs relating to comments, depending on the situation where -you use it. - - When a region is active (@pxref{Mark}), @kbd{M-;} either adds -comment delimiters to the region, or removes them. If every line in -the region is already a comment, it ``uncomments'' each of those lines -by removing their comment delimiters. Otherwise, it adds comment -delimiters to enclose the text in the region. - - If you supply a prefix argument to @kbd{M-;} when a region is -active, that specifies the number of comment delimiters to add or -delete. A positive argument @var{n} adds @var{n} delimiters, while a -negative argument @var{-n} removes @var{n} delimiters. - - If the region is not active, and there is no existing comment on the -current line, @kbd{M-;} adds a new comment to the current line. If -the line is blank (i.e.@: empty or containing only whitespace -characters), the comment is indented to the same position where -@key{TAB} would indent to (@pxref{Basic Indent}). If the line is -non-blank, the comment is placed after the last non-whitespace -character on the line; normally, Emacs tries putting it at the column -specified by the variable @code{comment-column} (@pxref{Options for -Comments}), but if the line already extends past that column, it puts -the comment at some suitable position, usually separated from the -non-comment text by at least one space. In each case, Emacs places -point after the comment's starting delimiter, so that you can start -typing the comment text right away. - - You can also use @kbd{M-;} to align an existing comment. If a line -already contains the comment-start string, @kbd{M-;} realigns it to -the conventional alignment and moves point after the comment's -starting delimiter. As an exception, comments starting in column 0 -are not moved. Even when an existing comment is properly aligned, -@kbd{M-;} is still useful for moving directly to the start of the -comment text. - -@findex comment-kill -@kindex C-u M-; - @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any -comment on the current line, along with the whitespace before it. -Since the comment is saved to the kill ring, you can reinsert it on -another line by moving to the end of that line, doing @kbd{C-y}, and -then @kbd{M-;} to realign the comment. You can achieve the same -effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill} -(@code{comment-dwim} actually calls @code{comment-kill} as a -subroutine when it is given a prefix argument). - -@kindex C-c C-c (C mode) -@findex comment-region -@findex uncomment-region - The command @kbd{M-x comment-region} is equivalent to calling -@kbd{M-;} on an active region, except that it always acts on the -region, even if the mark is inactive. In C mode and related modes, -this command is bound to @kbd{C-c C-c}. The command @kbd{M-x -uncomment-region} uncomments each line in the region; a numeric prefix -argument specifies the number of comment delimiters to remove -(negative arguments specify the number of comment to delimiters to -add). - - For C-like modes, you can configure the exact effect of @kbd{M-;} by -setting the variables @code{c-indent-comment-alist} and -@code{c-indent-comments-syntactically-p}. For example, on a line -ending in a closing brace, @kbd{M-;} puts the comment one space after -the brace rather than at @code{comment-column}. For full details see -@ref{Comment Commands,,, ccmode, The CC Mode Manual}. - -@node Multi-Line Comments -@subsection Multiple Lines of Comments - -@kindex C-M-j -@kindex M-j -@cindex blank lines in programs -@findex comment-indent-new-line -@vindex comment-multi-line - If you are typing a comment and wish to continue it to another line, -type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}). This -breaks the current line, and inserts the necessary comment delimiters -and indentation to continue the comment. - - For languages with closing comment delimiters (e.g.@: @samp{*/} in -C), the exact behavior of @kbd{M-j} depends on the value of the -variable @code{comment-multi-line}. If the value is @code{nil}, the -command closes the comment on the old line and starts a new comment on -the new line. Otherwise, it opens a new line within the current -comment delimiters. - - When Auto Fill mode is on, going past the fill column while typing a -comment also continues the comment, in the same way as an explicit -invocation of @kbd{M-j}. - - To turn existing lines into comment lines, use @kbd{M-;} with the -region active, or use @kbd{M-x comment-region} -@ifinfo -(@pxref{Comment Commands}). -@end ifinfo -@ifnotinfo -as described in the preceding section. -@end ifnotinfo - - You can configure C Mode such that when you type a @samp{/} at the -start of a line in a multi-line block comment, this closes the -comment. Enable the @code{comment-close-slash} clean-up for this. -@xref{Clean-ups,,, ccmode, The CC Mode Manual}. - -@node Options for Comments -@subsection Options Controlling Comments - -@vindex comment-column -@kindex C-x ; -@findex comment-set-column - As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command -adds a comment to a line, it tries to place the comment at the column -specified by the buffer-local variable @code{comment-column}. You can -set either the local value or the default value of this buffer-local -variable in the usual way (@pxref{Locals}). Alternatively, you can -type @kbd{C-x ;} (@code{comment-set-column}) to set the value of -@code{comment-column} in the current buffer to the column where point -is currently located. @kbd{C-u C-x ;} sets the comment column to -match the last comment before point in the buffer, and then does a -@kbd{M-;} to align the current line's comment under the previous one. - -@vindex comment-start-skip - The comment commands recognize comments based on the regular -expression that is the value of the variable @code{comment-start-skip}. -Make sure this regexp does not match the null string. It may match more -than the comment starting delimiter in the strictest sense of the word; -for example, in C mode the value of the variable is -@c This stops M-q from breaking the line inside that @code. -@code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and -spaces after the @samp{/*} itself, and accepts C++ style comments -also. (Note that @samp{\\} is needed in Lisp syntax to include a -@samp{\} in the string, which is needed to deny the first star its -special meaning in regexp syntax. @xref{Regexp Backslash}.) - -@vindex comment-start -@vindex comment-end - When a comment command makes a new comment, it inserts the value of -@code{comment-start} as an opening comment delimiter. It also inserts -the value of @code{comment-end} after point, as a closing comment -delimiter. For example, in Lisp mode, @code{comment-start} is -@samp{";"} and @code{comment-end} is @code{""} (the empty string). In -C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is -@code{" */"}. - -@vindex comment-padding - The variable @code{comment-padding} specifies a string that the -commenting commands should insert between the comment delimiter(s) and -the comment text. The default, @samp{" "}, specifies a single space. -Alternatively, the value can be a number, which specifies that number -of spaces, or @code{nil}, which means no spaces at all. - - The variable @code{comment-multi-line} controls how @kbd{M-j} and -Auto Fill mode continue comments over multiple lines. -@xref{Multi-Line Comments}. - -@vindex comment-indent-function - The variable @code{comment-indent-function} should contain a function -that will be called to compute the alignment for a newly inserted -comment or for aligning an existing comment. It is set differently by -various major modes. The function is called with no arguments, but with -point at the beginning of the comment, or at the end of a line if a new -comment is to be inserted. It should return the column in which the -comment ought to start. For example, in Lisp mode, the indent hook -function bases its decision on how many semicolons begin an existing -comment, and on the code in the preceding lines. - -@node Documentation -@section Documentation Lookup - - Emacs provides several features you can use to look up the -documentation of functions, variables and commands that you plan to -use in your program. - -@menu -* Info Lookup:: Looking up library functions and commands in Info files. -* Man Page:: Looking up man pages of library functions and commands. -* Lisp Doc:: Looking up Emacs Lisp functions, etc. -@end menu - -@node Info Lookup -@subsection Info Documentation Lookup - -@findex info-lookup-symbol -@findex info-lookup-file -@kindex C-h S - For major modes that apply to languages which have documentation in -Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the -Info documentation for a symbol used in the program. You specify the -symbol with the minibuffer; the default is the symbol appearing in the -buffer at point. For example, in C mode this looks for the symbol in -the C Library Manual. The command only works if the appropriate -manual's Info files are installed. - - The major mode determines where to look for documentation for the -symbol---which Info files to look in, and which indices to search. -You can also use @kbd{M-x info-lookup-file} to look for documentation -for a file name. - - If you use @kbd{C-h S} in a major mode that does not support it, -it asks you to specify the ``symbol help mode''. You should enter -a command such as @code{c-mode} that would select a major -mode which @kbd{C-h S} does support. - -@node Man Page -@subsection Man Page Lookup - -@cindex man page - On Unix, the main form of on-line documentation was the @dfn{manual -page} or @dfn{man page}. In the GNU operating system, we aim to -replace man pages with better-organized manuals that you can browse -with Info (@pxref{Misc Help}). This process is not finished, so it is -still useful to read manual pages. - -@findex manual-entry - You can read the man page for an operating system command, library -function, or system call, with the @kbd{M-x man} command. This -prompts for a topic, with completion (@pxref{Completion}), and runs -the @command{man} program to format the corresponding man page. If -the system permits, it runs @command{man} asynchronously, so that you -can keep on editing while the page is being formatted. The result -goes in a buffer named @file{*Man @var{topic}*}. These buffers use a -special major mode, Man mode, that facilitates scrolling and jumping -to other manual pages. For details, type @kbd{C-h m} while in a Man -mode buffer. - -@cindex sections of manual pages - Each man page belongs to one of ten or more @dfn{sections}, each -named by a digit or by a digit and a letter. Sometimes there are man -pages with the same name in different sections. To read a man page -from a specific section, type @samp{@var{topic}(@var{section})} or -@samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts -for the topic. For example, the man page for the C library function -@code{chmod} is in section 2, but there is a shell command of the same -name, whose man page is in section 1; to view the former, type -@kbd{M-x manual-entry @key{RET} chmod(2) @key{RET}}. - -@vindex Man-switches -@kindex M-n @r{(Man mode)} -@kindex M-p @r{(Man mode)} - If you do not specify a section, @kbd{M-x man} normally displays -only the first man page found. On some systems, the @code{man} -program accepts a @samp{-a} command-line option, which tells it to -display all the man pages for the specified topic. To make use of -this, change the value of the variable @code{Man-switches} to -@samp{"-a"}. Then, in the Man mode buffer, you can type @kbd{M-n} and -@kbd{M-p} to switch between man pages in different sections. The mode -line shows how many manual pages are available. - -@findex woman -@cindex manual pages, on MS-DOS/MS-Windows - An alternative way of reading manual pages is the @kbd{M-x woman} -command. Unlike @kbd{M-x man}, it does not run any external programs -to format and display the man pages; the formatting is done by Emacs, -so it works on systems such as MS-Windows where the @command{man} -program may be unavailable. It prompts for a man page, and displays -it in a buffer named @file{*WoMan @var{section} @var{topic}}. - - @kbd{M-x woman} computes the completion list for manpages the first -time you invoke the command. With a numeric argument, it recomputes -this list; this is useful if you add or delete manual pages. - - If you type a name of a manual page and @kbd{M-x woman} finds that -several manual pages by the same name exist in different sections, it -pops up a window with possible candidates asking you to choose one of -them. - - For more information about setting up and using @kbd{M-x woman}, see -@ifinfo -@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The -WoMan Manual}. -@end ifinfo -@ifnotinfo -the WoMan Info manual, which is distributed with Emacs. -@end ifnotinfo - -@node Lisp Doc -@subsection Emacs Lisp Documentation Lookup - - When editing Emacs Lisp code, you can use the commands @kbd{C-h f} -(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) -to view the built-in documentation for the Lisp functions and -variables that you want to use. @xref{Name Help}. - -@cindex Eldoc mode -@findex eldoc-mode - Eldoc is a buffer-local minor mode that helps with looking up Lisp -documention. When it is enabled, the echo area displays some useful -information whenever there is a Lisp function or variable at point; -for a function, it shows the argument list, and for a variable it -shows the first line of the variable's documentation string. To -toggle Eldoc mode, type @kbd{M-x eldoc-mode}. Eldoc mode can be used -with the Emacs Lisp and Lisp Interaction major modes. - -@node Hideshow -@section Hideshow minor mode -@cindex Hideshow mode -@cindex mode, Hideshow - -@findex hs-minor-mode - Hideshow mode is a buffer-local minor mode that allows you to -selectively display portions of a program, which are referred to as -@dfn{blocks}. Type @kbd{M-x hs-minor-mode} to toggle this minor mode -(@pxref{Minor Modes}). - - When you use Hideshow mode to hide a block, the block disappears -from the screen, to be replaced by an ellipsis (three periods in a -row). Just what constitutes a block depends on the major mode. In C -mode and related modes, blocks are delimited by braces, while in Lisp -mode they are delimited by parentheses. Multi-line comments also -count as blocks. - - Hideshow mode provides the following commands: - -@findex hs-hide-all -@findex hs-hide-block -@findex hs-show-all -@findex hs-show-block -@findex hs-show-region -@findex hs-hide-level -@findex hs-minor-mode -@kindex C-c @@ C-h -@kindex C-c @@ C-s -@kindex C-c @@ C-M-h -@kindex C-c @@ C-M-s -@kindex C-c @@ C-r -@kindex C-c @@ C-l -@kindex S-Mouse-2 -@table @kbd -@item C-c @@ C-h -Hide the current block (@code{hs-hide-block}). -@item C-c @@ C-s -Show the current block (@code{hs-show-block}). -@item C-c @@ C-c -Either hide or show the current block (@code{hs-toggle-hiding}). -@item S-Mouse-2 -Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}). -@item C-c @@ C-M-h -Hide all top-level blocks (@code{hs-hide-all}). -@item C-c @@ C-M-s -Show all blocks in the buffer (@code{hs-show-all}). -@item C-c @@ C-l -Hide all blocks @var{n} levels below this block -(@code{hs-hide-level}). -@end table - -@vindex hs-hide-comments-when-hiding-all -@vindex hs-isearch-open -@vindex hs-special-modes-alist - These variables can be used to customize Hideshow mode: - -@table @code -@item hs-hide-comments-when-hiding-all -If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides -comments too. - -@item hs-isearch-open -This variable specifies the conditions under which incremental search -should unhide a hidden block when matching text occurs within the -block. Its value should be either @code{code} (unhide only code -blocks), @code{comment} (unhide only comments), @code{t} (unhide both -code blocks and comments), or @code{nil} (unhide neither code blocks -nor comments). The default value is @code{code}. -@end table - -@node Symbol Completion -@section Completion for Symbol Names -@cindex completion (symbol names) - - Completion is normally done in the minibuffer (@pxref{Completion}), -but you can also complete symbol names in ordinary Emacs buffers. - -@kindex M-TAB -@kindex C-M-i - In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}} -to complete the partial symbol before point. On graphical displays, -the @kbd{M-@key{TAB}} key is usually reserved by the window manager -for switching graphical windows, so you should type @kbd{C-M-i} or -@kbd{@key{ESC} @key{TAB}} instead. - -@cindex tags-based completion -@findex completion-at-point -@cindex Lisp symbol completion -@cindex completion (Lisp symbols) - In most programming language modes, @kbd{C-M-i} (or -@kbd{M-@key{TAB}}) invokes the command @code{completion-at-point}, -which generates its completion list in a flexible way. If Semantic -mode is enabled, it tries to use the Semantic parser data for -completion (@pxref{Semantic}). If Semantic mode is not enabled or -fails at performing completion, it tries to complete using the -selected tags table (@pxref{Tags}). If in Emacs Lisp mode, it -performs completion using the function, variable, or property names -defined in the current Emacs session. - - In all other respects, in-buffer symbol completion behaves like -minibuffer completion. For instance, if Emacs cannot complete to a -unique symbol, it displays a list of completion alternatives in -another window. @xref{Completion}. - - In Text mode and related modes, @kbd{M-@key{TAB}} completes words -based on the spell-checker's dictionary. @xref{Spelling}. - -@node Glasses -@section Glasses minor mode -@cindex Glasses mode -@cindex camel case -@findex mode, Glasses - - Glasses mode is a buffer-local minor mode that makes it easier to -read mixed-case (or ``CamelCase'') symbols like -@samp{unReadableSymbol}, by altering how they are displayed. By -default, it displays extra underscores between each lower-case letter -and the following capital letter. This does not alter the buffer -text, only how it is displayed. - - To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor -Modes}). When Glasses mode is enabled, the minor mode indicator -@samp{o^o} appears in the mode line. For more information about -Glasses mode, type @kbd{C-h P glasses @key{RET}}. - -@node Semantic -@section Semantic -@cindex Semantic package - -Semantic is a package that provides language-aware editing commands -based on @code{source code parsers}. This section provides a brief -description of Semantic; for full details, -@ifnottex -see @ref{Top, Semantic,, semantic, Semantic}. -@end ifnottex -@iftex -see the Semantic Info manual, which is distributed with Emacs. -@end iftex - - Most of the ``language aware'' features in Emacs, such as Font Lock -mode (@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular -expressions and syntax tables.} that usually give good results but are -never completely exact. In contrast, the parsers used by Semantic -have an exact understanding of programming language syntax. This -allows Semantic to provide search, navigation, and completion commands -that are powerful and precise. - -@cindex Semantic mode -@cindex mode, Semantic - To begin using Semantic, type @kbd{M-x semantic-mode} or click on -the menu item named @samp{Source Code Parsers (Semantic)} in the -@samp{Tools} menu. This enables Semantic mode, a global minor mode. - - When Semantic mode is enabled, Emacs automatically attempts to -parses each file you visit. Currently, Semantic understands C, C++, -Scheme, Javascript, Java, HTML, and Make. Within each parsed buffer, -the following commands are available: - -@table @kbd -@item C-c , j -@kindex C-c , j -Prompt for the name of a function defined in the current file, and -move point there (@code{semantic-complete-jump-local}). - -@item C-c , J -@kindex C-c , J -Prompt for the name of a function defined in any file Emacs has -parsed, and move point there (@code{semantic-complete-jump}). - -@item C-c , @key{SPC} -@kindex C-c , @key{SPC} -Display a list of possible completions for the symbol at point -(@code{semantic-complete-analyze-inline}). This also activates a set -of special key bindings for choosing a completion: @key{RET} accepts -the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible -completions, @key{TAB} completes as far as possible and then cycles, -and @kbd{C-g} or any other key aborts completion. - -@item C-c , l -@kindex C-c , l -Display a list of the possible completions of the symbol at point, in -another window (@code{semantic-analyze-possible-completions}). -@end table - -@noindent -In addition to the above commands, the Semantic package provides a -variety of other ways to make use of parser information. For -instance, you can use it to display a list of completions when Emacs -is idle. -@ifnottex -@xref{Top, Semantic,, semantic, Semantic}, for details. -@end ifnottex - -@node Misc for Programs -@section Other Features Useful for Editing Programs - - Some Emacs commands that aren't designed specifically for editing -programs are useful for that nonetheless. - - The Emacs commands that operate on words, sentences and paragraphs -are useful for editing code. Most symbols names contain words -(@pxref{Words}), while sentences can be found in strings and comments -(@pxref{Sentences}). As for paragraphs, they are defined in most -programming language modes to begin and end at blank lines -(@pxref{Paragraphs}). Therefore, judicious use of blank lines to make -the program clearer will also provide useful chunks of text for the -paragraph commands to work on. Auto Fill mode, if enabled in a -programming language major mode, indents the new lines which it -creates. - -@findex electric-layout-mode - Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global -minor mode that automatically inserts newlines when you type certain -characters; for example, @samp{@{}, @samp{@}} and @samp{;} in Javascript -mode. - - Apart from Hideshow mode (@pxref{Hideshow}), another way to -selectively display parts of a program is to use the selective display -feature (@pxref{Selective Display}). Programming modes often also -support Outline minor mode (@pxref{Outline Mode}), which can be used -with the Foldout package (@pxref{Foldout}). - -@ifinfo - The ``automatic typing'' features may be useful for writing programs. -@xref{Top,,Autotyping, autotype, Autotyping}. -@end ifinfo - -@node C Modes -@section C and Related Modes -@cindex C mode -@cindex Java mode -@cindex Pike mode -@cindex IDL mode -@cindex CORBA IDL mode -@cindex Objective C mode -@cindex C++ mode -@cindex AWK mode -@cindex mode, Java -@cindex mode, C -@cindex mode, C++ -@cindex mode, Objective C -@cindex mode, CORBA IDL -@cindex mode, Pike -@cindex mode, AWK - - This section gives a brief description of the special features -available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. -(These are called ``C mode and related modes''.) -@ifinfo -@xref{Top,, CC Mode, ccmode, CC Mode}, for more details. -@end ifinfo -@ifnotinfo -For more details, see the CC mode Info manual, which is distributed -with Emacs. -@end ifnotinfo - -@menu -* Motion in C:: Commands to move by C statements, etc. -* Electric C:: Colon and other chars can automatically reindent. -* Hungry Delete:: A more powerful DEL command. -* Other C Commands:: Filling comments, viewing expansion of macros, - and other neat features. -@end menu - -@node Motion in C -@subsection C Mode Motion Commands - - This section describes commands for moving point, in C mode and -related modes. - -@table @code -@item C-M-a -@itemx C-M-e -@findex c-beginning-of-defun -@findex c-end-of-defun -Move point to the beginning or end of the current function or -top-level definition. In languages with enclosing scopes (such as -C++'s classes) the @dfn{current function} is the immediate one, -possibly inside a scope. Otherwise it is the one defined by the least -enclosing braces. (By contrast, @code{beginning-of-defun} and -@code{end-of-defun} search for braces in column zero.) @xref{Moving -by Defuns}. - -@item C-c C-u -@kindex C-c C-u @r{(C mode)} -@findex c-up-conditional -Move point back to the containing preprocessor conditional, leaving the -mark behind. A prefix argument acts as a repeat count. With a negative -argument, move point forward to the end of the containing -preprocessor conditional. - -@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so -the function will stop at a @samp{#elif} when going backward, but not -when going forward. - -@item C-c C-p -@kindex C-c C-p @r{(C mode)} -@findex c-backward-conditional -Move point back over a preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move forward. - -@item C-c C-n -@kindex C-c C-n @r{(C mode)} -@findex c-forward-conditional -Move point forward across a preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move backward. - -@item M-a -@kindex M-a (C mode) -@findex c-beginning-of-statement -Move point to the beginning of the innermost C statement -(@code{c-beginning-of-statement}). If point is already at the beginning -of a statement, move to the beginning of the preceding statement. With -prefix argument @var{n}, move back @var{n} @minus{} 1 statements. - -In comments or in strings which span more than one line, this command -moves by sentences instead of statements. - -@item M-e -@kindex M-e (C mode) -@findex c-end-of-statement -Move point to the end of the innermost C statement or sentence; like -@kbd{M-a} except that it moves in the other direction -(@code{c-end-of-statement}). -@end table - -@node Electric C -@subsection Electric C Characters - - In C mode and related modes, certain printing characters are -@dfn{electric}---in addition to inserting themselves, they also -reindent the current line, and optionally also insert newlines. The -``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, -@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and -@kbd{)}. - - You might find electric indentation inconvenient if you are editing -chaotically indented code. If you are new to CC Mode, you might find -it disconcerting. You can toggle electric action with the command -@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line -after the mode name: - -@table @kbd -@item C-c C-l -@kindex C-c C-l @r{(C mode)} -@findex c-toggle-electric-state -Toggle electric action (@code{c-toggle-electric-state}). With a -positive prefix argument, this command enables electric action, with a -negative one it disables it. -@end table - - Electric characters insert newlines only when, in addition to the -electric state, the @dfn{auto-newline} feature is enabled (indicated -by @samp{/la} in the mode line after the mode name). You can turn -this feature on or off with the command @kbd{C-c C-a}: - -@table @kbd -@item C-c C-a -@kindex C-c C-a @r{(C mode)} -@findex c-toggle-auto-newline -Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a -prefix argument, this command turns the auto-newline feature on if the -argument is positive, and off if it is negative. -@end table - - Usually the CC Mode style configures the exact circumstances in -which Emacs inserts auto-newlines. You can also configure this -directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}. - -@node Hungry Delete -@subsection Hungry Delete Feature in C -@cindex hungry deletion (C Mode) - - If you want to delete an entire block of whitespace at point, you -can use @dfn{hungry deletion}. This deletes all the contiguous -whitespace either before point or after point in a single operation. -@dfn{Whitespace} here includes tabs and newlines, but not comments or -preprocessor commands. - -@table @kbd -@item C-c C-@key{DEL} -@itemx C-c @key{DEL} -@findex c-hungry-delete-backwards -@kindex C-c C-@key{DEL} (C Mode) -@kindex C-c @key{DEL} (C Mode) -Delete the entire block of whitespace preceding point (@code{c-hungry-delete-backwards}). - -@item C-c C-d -@itemx C-c C-@key{DELETE} -@itemx C-c @key{DELETE} -@findex c-hungry-delete-forward -@kindex C-c C-d (C Mode) -@kindex C-c C-@key{DELETE} (C Mode) -@kindex C-c @key{DELETE} (C Mode) -Delete the entire block of whitespace after point (@code{c-hungry-delete-forward}). -@end table - - As an alternative to the above commands, you can enable @dfn{hungry -delete mode}. When this feature is enabled (indicated by @samp{/h} in -the mode line after the mode name), a single @key{DEL} deletes all -preceding whitespace, not just one space, and a single @kbd{C-c C-d} -(but @emph{not} plain @key{DELETE}) deletes all following whitespace. - -@table @kbd -@item M-x c-toggle-hungry-state -@findex c-toggle-hungry-state -Toggle the hungry-delete feature -(@code{c-toggle-hungry-state}). With a prefix argument, -this command turns the hungry-delete feature on if the argument is -positive, and off if it is negative. -@end table - -@vindex c-hungry-delete-key - The variable @code{c-hungry-delete-key} controls whether the -hungry-delete feature is enabled. - -@node Other C Commands -@subsection Other Commands for C Mode - -@table @kbd -@item C-c C-w -@itemx M-x subword-mode -@findex subword-mode -Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word -commands recognize upper case letters in -@samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by -the flag @samp{/w} on the mode line after the mode name -(e.g. @samp{C/law}). You can even use @kbd{M-x subword-mode} in -non-CC Mode buffers. - -In the GNU project, we recommend using underscores to separate words -within an identifier in C or C++, rather than using case distinctions. - -@item M-x c-context-line-break -@findex c-context-line-break -This command inserts a line break and indents the new line in a manner -appropriate to the context. In normal code, it does the work of -@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it -additionally inserts a @samp{\} at the line break, and within comments -it's like @kbd{M-j} (@code{c-indent-new-comment-line}). - -@code{c-context-line-break} isn't bound to a key by default, but it -needs a binding to be useful. The following code will bind it to -@kbd{C-j}. We use @code{c-initialization-hook} here to make sure -the keymap is loaded before we try to change it. - -@example -(defun my-bind-clb () - (define-key c-mode-base-map "\C-j" 'c-context-line-break)) -(add-hook 'c-initialization-hook 'my-bind-clb) -@end example - -@item C-M-h -Put mark at the end of a function definition, and put point at the -beginning (@code{c-mark-function}). - -@item M-q -@kindex M-q @r{(C mode)} -@findex c-fill-paragraph -Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}). -If any part of the current line is a comment or within a comment, this -command fills the comment or the paragraph of it that point is in, -preserving the comment indentation and comment delimiters. - -@item C-c C-e -@cindex macro expansion in C -@cindex expansion of C macros -@findex c-macro-expand -@kindex C-c C-e @r{(C mode)} -Run the C preprocessor on the text in the region, and show the result, -which includes the expansion of all the macro calls -(@code{c-macro-expand}). The buffer text before the region is also -included in preprocessing, for the sake of macros defined there, but the -output from this part isn't shown. - -When you are debugging C code that uses macros, sometimes it is hard to -figure out precisely how the macros expand. With this command, you -don't have to figure it out; you can see the expansions. - -@item C-c C-\ -@findex c-backslash-region -@kindex C-c C-\ @r{(C mode)} -Insert or align @samp{\} characters at the ends of the lines of the -region (@code{c-backslash-region}). This is useful after writing or -editing a C macro definition. - -If a line already ends in @samp{\}, this command adjusts the amount of -whitespace before it. Otherwise, it inserts a new @samp{\}. However, -the last line in the region is treated specially; no @samp{\} is -inserted on that line, and any @samp{\} there is deleted. - -@item M-x cpp-highlight-buffer -@cindex preprocessor highlighting -@findex cpp-highlight-buffer -Highlight parts of the text according to its preprocessor conditionals. -This command displays another buffer named @file{*CPP Edit*}, which -serves as a graphic menu for selecting how to display particular kinds -of conditionals and their contents. After changing various settings, -click on @samp{[A]pply these settings} (or go to that buffer and type -@kbd{a}) to rehighlight the C mode buffer accordingly. - -@item C-c C-s -@findex c-show-syntactic-information -@kindex C-c C-s @r{(C mode)} -Display the syntactic information about the current source line -(@code{c-show-syntactic-information}). This information directs how -the line is indented. - -@item M-x cwarn-mode -@itemx M-x global-cwarn-mode -@findex cwarn-mode -@findex global-cwarn-mode -@vindex global-cwarn-mode -@cindex CWarn mode -@cindex suspicious constructions in C, C++ -CWarn minor mode highlights certain suspicious C and C++ constructions: - -@itemize @bullet{} -@item -Assignments inside expressions. -@item -Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} -(except after a @samp{do @dots{} while} statement); -@item -C++ functions with reference parameters. -@end itemize - -@noindent -You can enable the mode for one buffer with the command @kbd{M-x -cwarn-mode}, or for all suitable buffers with the command @kbd{M-x -global-cwarn-mode} or by customizing the variable -@code{global-cwarn-mode}. You must also enable Font Lock mode to make -it work. - -@item M-x hide-ifdef-mode -@findex hide-ifdef-mode -@cindex Hide-ifdef mode -@vindex hide-ifdef-shadow -Hide-ifdef minor mode hides selected code within @samp{#if} and -@samp{#ifdef} preprocessor blocks. If you change the variable -@code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode -``shadows'' preprocessor blocks by displaying them with a less -prominent face, instead of hiding them entirely. See the -documentation string of @code{hide-ifdef-mode} for more information. - -@item M-x ff-find-related-file -@cindex related files -@findex ff-find-related-file -@vindex ff-related-file-alist -Find a file ``related'' in a special way to the file visited by the -current buffer. Typically this will be the header file corresponding -to a C/C++ source file, or vice versa. The variable -@code{ff-related-file-alist} specifies how to compute related file -names. -@end table - -@node Asm Mode -@section Asm Mode - -@cindex Asm mode -@cindex assembler mode -Asm mode is a major mode for editing files of assembler code. It -defines these commands: - -@table @kbd -@item @key{TAB} -@code{tab-to-tab-stop}. -@item C-j -Insert a newline and then indent using @code{tab-to-tab-stop}. -@item : -Insert a colon and then remove the indentation from before the label -preceding colon. Then do @code{tab-to-tab-stop}. -@item ; -Insert or align a comment. -@end table - - The variable @code{asm-comment-char} specifies which character -starts comments in assembler syntax. - -@ifnottex -@include fortran-xtra.texi -@end ifnottex diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi deleted file mode 100644 index d02ddd64b49..00000000000 --- a/doc/emacs/regs.texi +++ /dev/null @@ -1,332 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Registers, Display, Killing, Top -@chapter Registers -@cindex registers - - Emacs @dfn{registers} are compartments where you can save text, -rectangles, positions, and other things for later use. Once you save -text or a rectangle in a register, you can copy it into the buffer -once, or many times; once you save a position in a register, you can -jump back to that position once, or many times. - - Each register has a name that consists of a single character, which -we will denote by @var{r}; @var{r} can be a letter (such as @samp{a}) -or a number (such as @samp{1}); case matters, so register @samp{a} is -not the same as register @samp{A}. - -@findex view-register - A register can store a position, a piece of text, a rectangle, a -number, a window configuration, or a file name, but only one thing at -any given time. Whatever you store in a register remains there until -you store something else in that register. To see what register -@var{r} contains, use @kbd{M-x view-register}: - -@table @kbd -@item M-x view-register @key{RET} @var{r} -Display a description of what register @var{r} contains. -@end table - - @dfn{Bookmarks} record files and positions in them, so you can -return to those positions when you look at the file again. Bookmarks -are similar in spirit to registers, so they are also documented in -this chapter. - -@menu -* Position Registers:: Saving positions in registers. -* Text Registers:: Saving text in registers. -* Rectangle Registers:: Saving rectangles in registers. -* Configuration Registers:: Saving window configurations in registers. -* Number Registers:: Numbers in registers. -* File Registers:: File names in registers. -* Bookmarks:: Bookmarks are like registers, but persistent. -@end menu - -@node Position Registers -@section Saving Positions in Registers -@cindex saving position in a register - -@table @kbd -@item C-x r @key{SPC} @var{r} -Record the position of point and the current buffer in register -@var{r} (@code{point-to-register}). -@item C-x r j @var{r} -Jump to the position and buffer saved in register @var{r} -(@code{jump-to-register}). -@end table - -@kindex C-x r SPC -@findex point-to-register - Typing @kbd{C-x r @key{SPC}} (@code{point-to-register}), followed by -a character @kbd{@var{r}}, saves both the position of point and the -current buffer in register @var{r}. The register retains this -information until you store something else in it. - -@kindex C-x r j -@findex jump-to-register - The command @kbd{C-x r j @var{r}} switches to the buffer recorded in -register @var{r}, and moves point to the recorded position. The -contents of the register are not changed, so you can jump to the saved -position any number of times. - - If you use @kbd{C-x r j} to go to a saved position, but the buffer it -was saved from has been killed, @kbd{C-x r j} tries to create the buffer -again by visiting the same file. Of course, this works only for buffers -that were visiting files. - -@node Text Registers -@section Saving Text in Registers -@cindex saving text in a register - - When you want to insert a copy of the same piece of text several -times, it may be inconvenient to yank it from the kill ring, since each -subsequent kill moves that entry further down the ring. An alternative -is to store the text in a register and later retrieve it. - -@table @kbd -@item C-x r s @var{r} -Copy region into register @var{r} (@code{copy-to-register}). -@item C-x r i @var{r} -Insert text from register @var{r} (@code{insert-register}). -@item M-x append-to-register @key{RET} @var{r} -Append region to text in register @var{r}. -@item M-x prepend-to-register @key{RET} @var{r} -Prepend region to text in register @var{r}. -@end table - -@kindex C-x r s -@findex copy-to-register - @kbd{C-x r s @var{r}} stores a copy of the text of the region into -the register named @var{r}. If the mark is inactive, Emacs first -reactivates the mark where it was last set. The mark is deactivated -at the end of this command. @xref{Mark}. @kbd{C-u C-x r s @var{r}}, -the same command with a prefix argument, copies the text into register -@var{r} and deletes the text from the buffer as well; you can think of -this as ``moving'' the region text into the register. - -@findex append-to-register -@findex prepend-to-register - @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of -the text in the region to the text already stored in the register -named @var{r}. If invoked with a prefix argument, it deletes the -region after appending it to the register. The command -@code{prepend-to-register} is similar, except that it @emph{prepends} -the region text to the text in the register instead of -@emph{appending} it. - -@kindex C-x r i -@findex insert-register - @kbd{C-x r i @var{r}} inserts in the buffer the text from register -@var{r}. Normally it leaves point before the text and sets the mark -after, without activating it. With a numeric argument, it instead -puts point after the text and the mark before. - -@node Rectangle Registers -@section Saving Rectangles in Registers -@cindex saving rectangle in a register - - A register can contain a rectangle instead of linear text. -@xref{Rectangles}, for basic information on how to specify a rectangle -in the buffer. - -@table @kbd -@findex copy-rectangle-to-register -@kindex C-x r r -@item C-x r r @var{r} -Copy the region-rectangle into register @var{r} -(@code{copy-rectangle-to-register}). With numeric argument, delete it as -well. -@item C-x r i @var{r} -Insert the rectangle stored in register @var{r} (if it contains a -rectangle) (@code{insert-register}). -@end table - - The @kbd{C-x r i @var{r}} (@code{insert-register}) command, -previously documented in @ref{Text Registers}, inserts a rectangle -rather than a text string, if the register contains a rectangle. - -@node Configuration Registers -@section Saving Window Configurations in Registers -@cindex saving window configuration in a register - -@findex window-configuration-to-register -@findex frame-configuration-to-register -@kindex C-x r w -@kindex C-x r f - You can save the window configuration of the selected frame in a -register, or even the configuration of all windows in all frames, and -restore the configuration later. @xref{Windows}, for information -about window configurations. - -@table @kbd -@item C-x r w @var{r} -Save the state of the selected frame's windows in register @var{r} -(@code{window-configuration-to-register}). -@item C-x r f @var{r} -Save the state of all frames, including all their windows, in register -@var{r} (@code{frame-configuration-to-register}). -@end table - - Use @kbd{C-x r j @var{r}} to restore a window or frame configuration. -This is the same command used to restore a cursor position. When you -restore a frame configuration, any existing frames not included in the -configuration become invisible. If you wish to delete these frames -instead, use @kbd{C-u C-x r j @var{r}}. - -@node Number Registers -@section Keeping Numbers in Registers -@cindex saving number in a register - - There are commands to store a number in a register, to insert -the number in the buffer in decimal, and to increment it. These commands -can be useful in keyboard macros (@pxref{Keyboard Macros}). - -@table @kbd -@item C-u @var{number} C-x r n @var{r} -@kindex C-x r n -@findex number-to-register -Store @var{number} into register @var{r} (@code{number-to-register}). -@item C-u @var{number} C-x r + @var{r} -@kindex C-x r + -@findex increment-register -Increment the number in register @var{r} by @var{number} -(@code{increment-register}). -@item C-x r i @var{r} -Insert the number from register @var{r} into the buffer. -@end table - - @kbd{C-x r i} is the same command used to insert any other sort of -register contents into the buffer. @kbd{C-x r +} with no numeric -argument increments the register value by 1; @kbd{C-x r n} with no -numeric argument stores zero in the register. - -@node File Registers -@section Keeping File Names in Registers -@cindex saving file name in a register - - If you visit certain file names frequently, you can visit them more -conveniently if you put their names in registers. Here's the Lisp code -used to put a file name in a register: - -@smallexample -(set-register ?@var{r} '(file . @var{name})) -@end smallexample - -@need 3000 -@noindent -For example, - -@smallexample -(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog")) -@end smallexample - -@noindent -puts the file name shown in register @samp{z}. - - To visit the file whose name is in register @var{r}, type @kbd{C-x r j -@var{r}}. (This is the same command used to jump to a position or -restore a frame configuration.) - -@node Bookmarks -@section Bookmarks -@cindex bookmarks - - @dfn{Bookmarks} are somewhat like registers in that they record -positions you can jump to. Unlike registers, they have long names, and -they persist automatically from one Emacs session to the next. The -prototypical use of bookmarks is to record ``where you were reading'' in -various files. - -@table @kbd -@item C-x r m @key{RET} -Set the bookmark for the visited file, at point. - -@item C-x r m @var{bookmark} @key{RET} -@findex bookmark-set -Set the bookmark named @var{bookmark} at point (@code{bookmark-set}). - -@item C-x r b @var{bookmark} @key{RET} -@findex bookmark-jump -Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}). - -@item C-x r l -@findex list-bookmarks -List all bookmarks (@code{list-bookmarks}). - -@item M-x bookmark-save -@findex bookmark-save -Save all the current bookmark values in the default bookmark file. -@end table - -@kindex C-x r m -@findex bookmark-set -@kindex C-x r b -@findex bookmark-jump - The prototypical use for bookmarks is to record one current position -in each of several files. So the command @kbd{C-x r m}, which sets a -bookmark, uses the visited file name as the default for the bookmark -name. If you name each bookmark after the file it points to, then you -can conveniently revisit any of those files with @kbd{C-x r b}, and move -to the position of the bookmark at the same time. - -@kindex C-x r l - To display a list of all your bookmarks in a separate buffer, type -@kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer, -you can use it to edit your bookmark definitions or annotate the -bookmarks. Type @kbd{C-h m} in the bookmark buffer for more -information about its special editing commands. - - When you kill Emacs, Emacs saves your bookmarks, if -you have changed any bookmark values. You can also save the bookmarks -at any time with the @kbd{M-x bookmark-save} command. Bookmarks are -saved to the file @file{~/.emacs.d/bookmarks} (for compatibility with -older versions of Emacs, if you have a file named @file{~/.emacs.bmk}, -that is used instead). The bookmark commands load your default -bookmark file automatically. This saving and loading is how bookmarks -persist from one Emacs session to the next. - -@vindex bookmark-save-flag - If you set the variable @code{bookmark-save-flag} to 1, each command -that sets a bookmark will also save your bookmarks; this way, you -don't lose any bookmark values even if Emacs crashes. The value, if -a number, says how many bookmark modifications should go by between -saving. If you set this variable to @code{nil}, Emacs only -saves bookmarks if you explicitly use @kbd{M-x bookmark-save}. - -@vindex bookmark-search-size - Bookmark position values are saved with surrounding context, so that -@code{bookmark-jump} can find the proper position even if the file is -modified slightly. The variable @code{bookmark-search-size} says how -many characters of context to record on each side of the bookmark's -position. - - Here are some additional commands for working with bookmarks: - -@table @kbd -@item M-x bookmark-load @key{RET} @var{filename} @key{RET} -@findex bookmark-load -Load a file named @var{filename} that contains a list of bookmark -values. You can use this command, as well as @code{bookmark-write}, to -work with other files of bookmark values in addition to your default -bookmark file. - -@item M-x bookmark-write @key{RET} @var{filename} @key{RET} -@findex bookmark-write -Save all the current bookmark values in the file @var{filename}. - -@item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET} -@findex bookmark-delete -Delete the bookmark named @var{bookmark}. - -@item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET} -@findex bookmark-insert-location -Insert in the buffer the name of the file that bookmark @var{bookmark} -points to. - -@item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET} -@findex bookmark-insert -Insert in the buffer the @emph{contents} of the file that bookmark -@var{bookmark} points to. -@end table diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi deleted file mode 100644 index 3938712a5e9..00000000000 --- a/doc/emacs/rmail.texi +++ /dev/null @@ -1,1556 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Rmail -@chapter Reading Mail with Rmail -@cindex Rmail -@cindex reading mail -@findex rmail -@findex rmail-mode -@vindex rmail-mode-hook - - Rmail is an Emacs subsystem for reading and disposing of mail that -you receive. Rmail stores mail messages in files called Rmail files. -Reading the messages in an Rmail file is done in a special major mode, -Rmail mode, which redefines most letters to run commands for managing mail. -@menu -* Basic: Rmail Basics. Basic concepts of Rmail, and simple use. -* Scroll: Rmail Scrolling. Scrolling through a message. -* Motion: Rmail Motion. Moving to another message. -* Deletion: Rmail Deletion. Deleting and expunging messages. -* Inbox: Rmail Inbox. How mail gets into the Rmail file. -* Files: Rmail Files. Using multiple Rmail files. -* Output: Rmail Output. Copying messages out to files. -* Labels: Rmail Labels. Classifying messages by labeling them. -* Attrs: Rmail Attributes. Certain standard labels, called attributes. -* Reply: Rmail Reply. Sending replies to messages you are viewing. -* Summary: Rmail Summary. Summaries show brief info on many messages. -* Sort: Rmail Sorting. Sorting messages in Rmail. -* Display: Rmail Display. How Rmail displays a message; customization. -* Coding: Rmail Coding. How Rmail handles decoding character sets. -* Editing: Rmail Editing. Editing message text and headers in Rmail. -* Digest: Rmail Digest. Extracting the messages from a digest message. -* Rot13: Rmail Rot13. Reading messages encoded in the rot13 code. -* Movemail:: More details of fetching new mail. -* Remote Mailboxes:: Retrieving mail from remote mailboxes. -* Other Mailbox Formats:: Retrieving mail from local mailboxes in - various formats. -@end menu - -@node Rmail Basics -@section Basic Concepts of Rmail - -@cindex primary Rmail file -@vindex rmail-file-name - Using Rmail in the simplest fashion, you have one Rmail file -@file{~/RMAIL} in which all of your mail is saved. It is called your -@dfn{primary Rmail file}. The command @kbd{M-x rmail} reads your primary -Rmail file, merges new mail in from your inboxes, displays the first -message you haven't read yet, and lets you begin reading. The variable -@code{rmail-file-name} specifies the name of the primary Rmail file. - - Rmail displays only one message in the Rmail file at a time. -The message that is shown is called the @dfn{current message}. Rmail -mode's special commands can do such things as delete the current -message, copy it into another file, send a reply, or move to another -message. You can also create multiple Rmail files and use Rmail to move -messages between them. - -@cindex message number - Within the Rmail file, messages are normally arranged sequentially in -order of receipt; you can specify other ways to sort them (@pxref{Rmail -Sorting}). Messages are identified by consecutive integers which are -their @dfn{message numbers}. The number of the current message is -displayed in Rmail's mode line, followed by the total number of messages -in the file. You can move to a message by specifying its message number -with the @kbd{j} key (@pxref{Rmail Motion}). - -@kindex s @r{(Rmail)} -@findex rmail-expunge-and-save - Following the usual conventions of Emacs, changes in an Rmail file -become permanent only when you save the file. You can save it with -@kbd{s} (@code{rmail-expunge-and-save}), which also expunges deleted -messages from the file first (@pxref{Rmail Deletion}). To save the -file without expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail -file after merging new mail from an inbox file (@pxref{Rmail Inbox}). - -@kindex q @r{(Rmail)} -@findex rmail-quit -@kindex b @r{(Rmail)} -@findex rmail-bury - You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges -and saves the Rmail file, then buries the Rmail buffer as well as its -summary buffer, if present (@pxref{Rmail Summary}). But there is no -need to ``exit'' formally. If you switch from Rmail to editing in -other buffers, and never switch back, you have exited. Just make sure -to save the Rmail file eventually (like any other file you have -changed). @kbd{C-x s} is a suitable way to do this (@pxref{Save -Commands}). The Rmail command @kbd{b}, @code{rmail-bury}, buries the -Rmail buffer and its summary without expunging and saving the Rmail file. - -@node Rmail Scrolling -@section Scrolling Within a Message - - When Rmail displays a message that does not fit on the screen, you -must scroll through it to read the rest. You could do this with -@kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so -frequent that it deserves to be easier. - -@table @kbd -@item @key{SPC} -Scroll forward (@code{scroll-up-command}). -@item @key{DEL} -Scroll backward (@code{scroll-down-command}). -@item . -Scroll to start of message (@code{rmail-beginning-of-message}). -@item / -Scroll to end of message (@code{rmail-end-of-message}). -@end table - -@kindex SPC @r{(Rmail)} -@kindex DEL @r{(Rmail)} - Since the most common thing to do while reading a message is to -scroll through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} -do the same as @kbd{C-v} (@code{scroll-up-command}) and @kbd{M-v} -(@code{scroll-down-command}) respectively. - -@kindex . @r{(Rmail)} -@kindex / @r{(Rmail)} -@findex rmail-beginning-of-message -@findex rmail-end-of-message - The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the -beginning of the selected message. This is not quite the same as @kbd{M-<}: -for one thing, it does not set the mark; for another, it resets the buffer -boundaries of the current message if you have changed them. Similarly, -the command @kbd{/} (@code{rmail-end-of-message}) scrolls forward to the end -of the selected message. -@c The comment about buffer boundaries is still true in mbox Rmail, if -@c less likely to be relevant. - -@node Rmail Motion -@section Moving Among Messages - - The most basic thing to do with a message is to read it. The way to -do this in Rmail is to make the message current. The usual practice is -to move sequentially through the file, since this is the order of -receipt of messages. When you enter Rmail, you are positioned at the -first message that you have not yet made current (that is, the first one -that has the @samp{unseen} attribute; @pxref{Rmail Attributes}). Move -forward to see the other new messages; move backward to re-examine old -messages. - -@table @kbd -@item n -Move to the next nondeleted message, skipping any intervening deleted -messages (@code{rmail-next-undeleted-message}). -@item p -Move to the previous nondeleted message -(@code{rmail-previous-undeleted-message}). -@item M-n -Move to the next message, including deleted messages -(@code{rmail-next-message}). -@item M-p -Move to the previous message, including deleted messages -(@code{rmail-previous-message}). -@item C-c C-n -Move to the next message with the same subject as the current one -(@code{rmail-next-same-subject}). -@item C-c C-p -Move to the previous message with the same subject as the current one -(@code{rmail-previous-same-subject}). -@item j -Move to the first message. With argument @var{n}, move to -message number @var{n} (@code{rmail-show-message}). -@item > -Move to the last message (@code{rmail-last-message}). -@item < -Move to the first message (@code{rmail-first-message}). - -@item M-s @var{regexp} @key{RET} -Move to the next message containing a match for @var{regexp} -(@code{rmail-search}). - -@item - M-s @var{regexp} @key{RET} -Move to the previous message containing a match for @var{regexp}. -@end table - -@kindex n @r{(Rmail)} -@kindex p @r{(Rmail)} -@kindex M-n @r{(Rmail)} -@kindex M-p @r{(Rmail)} -@findex rmail-next-undeleted-message -@findex rmail-previous-undeleted-message -@findex rmail-next-message -@findex rmail-previous-message - @kbd{n} and @kbd{p} are the usual way of moving among messages in -Rmail. They move through the messages sequentially, but skip over -deleted messages, which is usually what you want to do. Their command -definitions are named @code{rmail-next-undeleted-message} and -@code{rmail-previous-undeleted-message}. If you do not want to skip -deleted messages---for example, if you want to move to a message to -undelete it---use the variants @kbd{M-n} and @kbd{M-p} -(@code{rmail-next-message} and @code{rmail-previous-message}). A -numeric argument to any of these commands serves as a repeat -count. - - In Rmail, you can specify a numeric argument by typing just the -digits. You don't need to type @kbd{C-u} first. - -@kindex M-s @r{(Rmail)} -@findex rmail-search -@cindex searching in Rmail - The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of -search. The usual incremental search command @kbd{C-s} works in Rmail, -but it searches only within the current message. The purpose of -@kbd{M-s} is to search for another message. It reads a regular -expression (@pxref{Regexps}) nonincrementally, then searches starting at -the beginning of the following message for a match. It then selects -that message. If @var{regexp} is empty, @kbd{M-s} reuses the regexp -used the previous time. - - To search backward in the file for another message, give @kbd{M-s} a -negative argument. In Rmail you can do this with @kbd{- M-s}. This -begins searching from the end of the previous message. - - It is also possible to search for a message based on labels. -@xref{Rmail Labels}. - -@kindex C-c C-n @r{(Rmail)} -@kindex C-c C-p @r{(Rmail)} -@findex rmail-next-same-subject -@findex rmail-previous-same-subject - The @kbd{C-c C-n} (@code{rmail-next-same-subject}) command moves to -the next message with the same subject as the current one. A prefix -argument serves as a repeat count. With a negative argument, this -command moves backward, acting like @kbd{C-c C-p} -(@code{rmail-previous-same-subject}). When comparing subjects, these -commands ignore the prefixes typically added to the subjects of replies. - -@kindex j @r{(Rmail)} -@kindex > @r{(Rmail)} -@kindex < @r{(Rmail)} -@findex rmail-show-message -@findex rmail-last-message -@findex rmail-first-message - To move to a message specified by absolute message number, use @kbd{j} -(@code{rmail-show-message}) with the message number as argument. With -no argument, @kbd{j} selects the first message. @kbd{<} -(@code{rmail-first-message}) also selects the first message. @kbd{>} -(@code{rmail-last-message}) selects the last message. - -@node Rmail Deletion -@section Deleting Messages - -@cindex deletion (Rmail) - When you no longer need to keep a message, you can @dfn{delete} it. This -flags it as ignorable, and some Rmail commands pretend it is no longer -present; but it still has its place in the Rmail file, and still has its -message number. - -@cindex expunging (Rmail) - @dfn{Expunging} the Rmail file actually removes the deleted messages. -The remaining messages are renumbered consecutively. -@c The following is neither true (there is also unforward, sorting, -@c etc), nor especially interesting. -@c Expunging is the only action that changes the message number of any -@c message, except for undigestifying (@pxref{Rmail Digest}). - -@table @kbd -@item d -Delete the current message, and move to the next nondeleted message -(@code{rmail-delete-forward}). -@item C-d -Delete the current message, and move to the previous nondeleted -message (@code{rmail-delete-backward}). -@item u -Undelete the current message, or move back to the previous deleted -message and undelete it (@code{rmail-undelete-previous-message}). -@item x -Expunge the Rmail file (@code{rmail-expunge}). -@end table - -@kindex d @r{(Rmail)} -@kindex C-d @r{(Rmail)} -@findex rmail-delete-forward -@findex rmail-delete-backward - There are two Rmail commands for deleting messages. Both delete the -current message and select another. @kbd{d} -(@code{rmail-delete-forward}) moves to the following message, skipping -messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward}) -moves to the previous nondeleted message. If there is no nondeleted -message to move to in the specified direction, the message that was just -deleted remains current. @kbd{d} with a prefix argument is equivalent -to @kbd{C-d}. Note that the Rmail summary versions of these commands -behave slightly differently (@pxref{Rmail Summary Edit}). - -@c mention other hooks, eg show message hook? -@vindex rmail-delete-message-hook - Whenever Rmail deletes a message, it runs the hook -@code{rmail-delete-message-hook}. When the hook functions are invoked, -the message has been marked deleted, but it is still the current message -in the Rmail buffer. - -@cindex undeletion (Rmail) -@kindex x @r{(Rmail)} -@findex rmail-expunge -@kindex u @r{(Rmail)} -@findex rmail-undelete-previous-message - To make all the deleted messages finally vanish from the Rmail file, -type @kbd{x} (@code{rmail-expunge}). Until you do this, you can still -@dfn{undelete} the deleted messages. The undeletion command, @kbd{u} -(@code{rmail-undelete-previous-message}), is designed to cancel the -effect of a @kbd{d} command in most cases. It undeletes the current -message if the current message is deleted. Otherwise it moves backward -to previous messages until a deleted message is found, and undeletes -that message. - - You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} -moves back to and undeletes the message that the @kbd{d} deleted. But -this does not work when the @kbd{d} skips a few already-deleted messages -that follow the message being deleted; then the @kbd{u} command -undeletes the last of the messages that were skipped. There is no clean -way to avoid this problem. However, by repeating the @kbd{u} command, -you can eventually get back to the message that you intend to -undelete. You can also select a particular deleted message with -the @kbd{M-p} command, then type @kbd{u} to undelete it. - - A deleted message has the @samp{deleted} attribute, and as a result -@samp{deleted} appears in the mode line when the current message is -deleted. In fact, deleting or undeleting a message is nothing more than -adding or removing this attribute. @xref{Rmail Attributes}. - -@node Rmail Inbox -@section Rmail Files and Inboxes -@cindex inbox file - - When you receive mail locally, the operating system places incoming -mail for you in a file that we call your @dfn{inbox}. When you start -up Rmail, it runs a C program called @code{movemail} to copy the new -messages from your local inbox into your primary Rmail file, which -also contains other messages saved from previous Rmail sessions. It -is in this file that you actually read the mail with Rmail. This -operation is called @dfn{getting new mail}. You can get new mail at -any time in Rmail by typing @kbd{g}. - -@vindex rmail-primary-inbox-list -@cindex @env{MAIL} environment variable - The variable @code{rmail-primary-inbox-list} contains a list of the -files that are inboxes for your primary Rmail file. If you don't set -this variable explicitly, Rmail uses the @env{MAIL} environment -variable, or, as a last resort, a default inbox based on -@code{rmail-spool-directory}. The default inbox file depends on your -operating system; often it is @file{/var/mail/@var{username}}, -@file{/var/spool/mail/@var{username}}, or -@file{/usr/spool/mail/@var{username}}. - - You can specify the inbox file(s) for any Rmail file for the current -session with the command @code{set-rmail-inbox-list}; see @ref{Rmail -Files}. - - There are two reasons for having separate Rmail files and inboxes. - -@enumerate -@item -The inbox file format varies between operating systems and according to -the other mail software in use. Only one part of Rmail needs to know -about the alternatives, and it need only understand how to convert all -of them to Rmail's own format. - -@item -It is very cumbersome to access an inbox file without danger of losing -mail, because it is necessary to interlock with mail delivery. -Moreover, different operating systems use different interlocking -techniques. The strategy of moving mail out of the inbox once and for -all into a separate Rmail file avoids the need for interlocking in all -the rest of Rmail, since only Rmail operates on the Rmail file. -@end enumerate - -@c FIXME remove this in Emacs 25; won't be relevant any more. - Rmail was originally written to use the Babyl format as its internal -format. Since then, we have recognized that the usual inbox format -(@samp{mbox}) on Unix and GNU systems is adequate for the job, and so -since Emacs 23 Rmail uses that as its internal format. The Rmail file -is still separate from the inbox file, even though their format is the -same. - -@vindex rmail-preserve-inbox - When getting new mail, Rmail first copies the new mail from the -inbox file to the Rmail file; then it saves the Rmail file; then it -clears out the inbox file. This way, a system crash may cause -duplication of mail between the inbox and the Rmail file, but cannot -lose mail. If @code{rmail-preserve-inbox} is non-@code{nil}, then -Rmail does not clear out the inbox file when it gets new mail. You -may wish to set this, for example, on a portable computer you use to -check your mail via POP while traveling, so that your mail will remain -on the server and you can save it later on your workstation. - - In some cases, Rmail copies the new mail from the inbox file -indirectly. First it runs the @code{movemail} program to move the mail -from the inbox to an intermediate file called -@file{.newmail-@var{inboxname}}, in the same directory as the Rmail -file. Then Rmail merges the new mail from that file, saves the Rmail -file, and only then deletes the intermediate file. If there is a crash -at the wrong time, this file continues to exist, and Rmail will use it -again the next time it gets new mail from that inbox. - - If Rmail is unable to convert the data in -@file{.newmail-@var{inboxname}} into mbox format, it renames the file to -@file{RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the name -unique) so that Rmail will not have trouble with the data again. You -should look at the file, find whatever message confuses Rmail (probably -one that includes the control-underscore character, octal code 037), and -delete it. Then you can use @kbd{1 g} to get new mail from the -corrected file. - -@node Rmail Files -@section Multiple Rmail Files - - Rmail operates by default on your @dfn{primary Rmail file}, which is named -@file{~/RMAIL} and receives your incoming mail from your system inbox file. -But you can also have other Rmail files and edit them with Rmail. These -files can receive mail through their own inboxes, or you can move messages -into them with explicit Rmail commands (@pxref{Rmail Output}). - -@table @kbd -@item i @var{file} @key{RET} -Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}). - -@item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET} -Specify inbox file names for current Rmail file to get mail from. - -@item g -Merge new mail from current Rmail file's inboxes -(@code{rmail-get-new-mail}). - -@item C-u g @var{file} @key{RET} -Merge new mail from inbox file @var{file}. -@end table - -@kindex i @r{(Rmail)} -@findex rmail-input - To run Rmail on a file other than your primary Rmail file, you can use -the @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file -in Rmail mode. You can use @kbd{M-x rmail-input} even when not in -Rmail, but it is easier to type @kbd{C-u M-x rmail}, which does the -same thing. - - The file you read with @kbd{i} should normally be a valid mbox file. -If it is not, Rmail tries to convert its text to mbox format, and -visits the converted text in the buffer. If you save the buffer, that -converts the file. - - If you specify a file name that doesn't exist, @kbd{i} initializes a -new buffer for creating a new Rmail file. - -@vindex rmail-secondary-file-directory -@vindex rmail-secondary-file-regexp - You can also select an Rmail file from a menu. In the Classify menu, -choose the Input Rmail File item; then choose the Rmail file you want. -The variables @code{rmail-secondary-file-directory} and -@code{rmail-secondary-file-regexp} specify which files to offer in the -menu: the first variable says which directory to find them in; the -second says which files in that directory to offer (all those that match -the regular expression). If no files match, you cannot select this menu -item. These variables also apply to choosing a file for output -(@pxref{Rmail Output}). -@c FIXME matches only checked when Rmail file first visited? - -@ignore -@findex set-rmail-inbox-list - Each Rmail file can contain a list of inbox file names; you can specify -this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files} -@key{RET}}. The argument can contain any number of file names, separated -by commas. It can also be empty, which specifies that this file should -have no inboxes. Once you specify a list of inboxes in an Rmail file, -the Rmail file remembers it permanently until you specify a different list. -@end ignore - -@vindex rmail-inbox-list - The inbox files to use are specified by the variable -@code{rmail-inbox-list}, which is buffer-local in Rmail mode. As a -special exception, if you have specified no inbox files for your primary -Rmail file, it uses the @env{MAIL} environment variable, or your -standard system inbox. - -@kindex g @r{(Rmail)} -@findex rmail-get-new-mail - The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the -current Rmail file from its inboxes. If the Rmail file has no -inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail} also -merges new mail into your primary Rmail file. - - To merge mail from a file that is not the usual inbox, give the -@kbd{g} key a numeric argument, as in @kbd{C-u g}. Then it reads a file -name and merges mail from that file. The inbox file is not deleted or -changed in any way when @kbd{g} with an argument is used. This is, -therefore, a general way of merging one file of messages into another. - -@node Rmail Output -@section Copying Messages Out to Files - - These commands copy messages from an Rmail file into another file. - -@table @kbd -@item o @var{file} @key{RET} -Append a full copy of the current message to the file @var{file} -(@code{rmail-output}). - -@item C-o @var{file} @key{RET} -Append a copy of the current message, as displayed, to the file -@var{file} (@code{rmail-output-as-seen}). - -@item w @var{file} @key{RET} -Output just the message body to the file @var{file}, taking the default -file name from the message @samp{Subject} header. -@end table - -@kindex o @r{(Rmail)} -@findex rmail-output-as-seen -@kindex C-o @r{(Rmail)} -@findex rmail-output - The commands @kbd{o} and @kbd{C-o} copy the current message into a -specified file, adding it at the end. The two commands differ mainly -in how much to copy: @kbd{o} copies the full message headers, even if -they are not all visible, while @kbd{C-o} copies exactly the headers -currently displayed and no more. @xref{Rmail Display}. In addition, -@kbd{o} converts the message to Babyl format (used by Rmail in Emacs -version 22 and before) if the file is in Babyl format; @kbd{C-o} -cannot output to Babyl files at all. -@c FIXME remove BABYL mention in Emacs 25? - - If the output file is currently visited in an Emacs buffer, the -output commands append the message to that buffer. It is up to you to -save the buffer eventually in its file. - -@kindex w @r{(Rmail)} -@findex rmail-output-body-to-file - Sometimes you may receive a message whose body holds the contents of a -file. You can save the body to a file (excluding the message header) -with the @kbd{w} command (@code{rmail-output-body-to-file}). Often -these messages contain the intended file name in the @samp{Subject} -field, so the @kbd{w} command uses the @samp{Subject} field as the -default for the output file name. However, the file name is read using -the minibuffer, so you can specify a different name if you wish. - - You can also output a message to an Rmail file chosen with a menu. -In the Classify menu, choose the Output Rmail File menu item; then -choose the Rmail file you want. This outputs the current message to -that file, like the @kbd{o} command. The variables -@code{rmail-secondary-file-directory} and -@code{rmail-secondary-file-regexp} specify which files to offer in the -menu: the first variable says which directory to find them in; the -second says which files in that directory to offer (all those that -match the regular expression). If no files match, you cannot select -this menu item. - -@vindex rmail-delete-after-output - Copying a message with @kbd{o} or @kbd{C-o} gives the original copy -of the message the @samp{filed} attribute, so that @samp{filed} -appears in the mode line when such a message is current. - - If you like to keep just a single copy of every mail message, set -the variable @code{rmail-delete-after-output} to @code{t}; then the -@kbd{o}, @kbd{C-o} and @kbd{w} commands delete the original message -after copying it. (You can undelete it afterward if you wish.) - -@vindex rmail-output-file-alist - The variable @code{rmail-output-file-alist} lets you specify -intelligent defaults for the output file, based on the contents of the -current message. The value should be a list whose elements have this -form: - -@example -(@var{regexp} . @var{name-exp}) -@end example - -@noindent -If there's a match for @var{regexp} in the current message, then the -default file name for output is @var{name-exp}. If multiple elements -match the message, the first matching element decides the default file -name. The subexpression @var{name-exp} may be a string constant giving -the file name to use, or more generally it may be any Lisp expression -that returns a file name as a string. @code{rmail-output-file-alist} -applies to both @kbd{o} and @kbd{C-o}. - -@vindex rmail-automatic-folder-directives -Rmail can automatically save messages from your primary Rmail file -(the one that @code{rmail-file-name} specifies) to other files, based -on the value of the variable @code{rmail-automatic-folder-directives}. -This variable is a list of elements (@samp{directives}) that say which -messages to save where. Each directive is a list consisting of an -output file, followed by one or more pairs of a header name and a regular -expression. If a message has a header matching the specified regular -expression, that message is saved to the given file. If the directive -has more than one header entry, all must match. Rmail checks directives -when it shows a message from the file @code{rmail-file-name}, and -applies the first that matches (if any). If the output file is -@code{nil}, the message is deleted, not saved. For example, you can use -this feature to save messages from a particular address, or with a -particular subject, to a dedicated file. - -@node Rmail Labels -@section Labels -@cindex label (Rmail) -@cindex attribute (Rmail) - - Each message can have various @dfn{labels} assigned to it as a means -of classification. Each label has a name; different names are different -labels. Any given label is either present or absent on a particular -message. A few label names have standard meanings and are given to -messages automatically by Rmail when appropriate; these special labels -are called @dfn{attributes}. -@ifnottex -(@xref{Rmail Attributes}.) -@end ifnottex -All other labels are assigned only by users. - -@table @kbd -@item a @var{label} @key{RET} -Assign the label @var{label} to the current message (@code{rmail-add-label}). -@item k @var{label} @key{RET} -Remove the label @var{label} from the current message (@code{rmail-kill-label}). -@item C-M-n @var{labels} @key{RET} -Move to the next message that has one of the labels @var{labels} -(@code{rmail-next-labeled-message}). -@item C-M-p @var{labels} @key{RET} -Move to the previous message that has one of the labels @var{labels} -(@code{rmail-previous-labeled-message}). -@item l @var{labels} @key{RET} -@itemx C-M-l @var{labels} @key{RET} -Make a summary of all messages containing any of the labels @var{labels} -(@code{rmail-summary-by-labels}). -@end table - -@kindex a @r{(Rmail)} -@kindex k @r{(Rmail)} -@findex rmail-add-label -@findex rmail-kill-label - The @kbd{a} (@code{rmail-add-label}) and @kbd{k} -(@code{rmail-kill-label}) commands allow you to assign or remove any -label on the current message. If the @var{label} argument is empty, it -means to assign or remove the same label most recently assigned or -removed. - - Once you have given messages labels to classify them as you wish, there -are three ways to use the labels: in moving, in summaries, and in sorting. - -@kindex C-M-n @r{(Rmail)} -@kindex C-M-p @r{(Rmail)} -@findex rmail-next-labeled-message -@findex rmail-previous-labeled-message - @kbd{C-M-n @var{labels} @key{RET}} -(@code{rmail-next-labeled-message}) moves to the next message that has -one of the labels @var{labels}. The argument @var{labels} specifies -one or more label names, separated by commas. @kbd{C-M-p} -(@code{rmail-previous-labeled-message}) is similar, but moves -backwards to previous messages. A numeric argument to either command -serves as a repeat count. - - The command @kbd{C-M-l @var{labels} @key{RET}} -(@code{rmail-summary-by-labels}) displays a summary containing only the -messages that have at least one of a specified set of labels. The -argument @var{labels} is one or more label names, separated by commas. -@xref{Rmail Summary}, for information on summaries. - - If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or -@kbd{C-M-l} is empty, it means to use the last set of labels specified -for any of these commands. - - @xref{Rmail Sorting}, for information on sorting messages with labels. - -@node Rmail Attributes -@section Rmail Attributes - - Some labels such as @samp{deleted} and @samp{filed} have built-in -meanings, and Rmail assigns them to messages automatically at -appropriate times; these labels are called @dfn{attributes}. Here is -a list of Rmail attributes: - -@table @samp -@item unseen -Means the message has never been current. Assigned to messages when -they come from an inbox file, and removed when a message is made -current. When you start Rmail, it initially shows the first message -that has this attribute. -@item deleted -Means the message is deleted. Assigned by deletion commands and -removed by undeletion commands (@pxref{Rmail Deletion}). -@item filed -Means the message has been copied to some other file. Assigned by the -@kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}). -@item answered -Means you have mailed an answer to the message. Assigned by the @kbd{r} -command (@code{rmail-reply}). @xref{Rmail Reply}. -@item forwarded -Means you have forwarded the message. Assigned by the @kbd{f} command -(@code{rmail-forward}). @xref{Rmail Reply}. -@item edited -Means you have edited the text of the message within Rmail. -@xref{Rmail Editing}. -@item resent -Means you have resent the message. Assigned by the command @kbd{M-x -rmail-resend}. @xref{Rmail Reply}. -@item retried -Means you have retried a failed outgoing message. Assigned by the -command @kbd{M-x rmail-retry-failure}. @xref{Rmail Reply}. -@end table - - All other labels are assigned or removed only by users, and have no -standard meaning. - -@node Rmail Reply -@section Sending Replies - - Rmail has several commands to send outgoing mail. @xref{Sending -Mail}, for information on using Message mode, including certain -features meant to work with Rmail. What this section documents are -the special commands of Rmail for entering the mail buffer. Note that -the usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and -@kbd{C-x 5 m}---also work normally in Rmail mode. - -@table @kbd -@item m -Send a message (@code{rmail-mail}). -@item c -Continue editing the already started outgoing message (@code{rmail-continue}). -@item r -Send a reply to the current Rmail message (@code{rmail-reply}). -@item f -Forward the current message to other users (@code{rmail-forward}). -@item C-u f -Resend the current message to other users (@code{rmail-resend}). -@item M-m -Try sending a bounced message a second time (@code{rmail-retry-failure}). -@end table - -@kindex r @r{(Rmail)} -@findex rmail-reply -@cindex reply to a message - The most common reason to send a message while in Rmail is to reply -to the message you are reading. To do this, type @kbd{r} -(@code{rmail-reply}). This displays a mail composition buffer in -another window, much like @kbd{C-x 4 m}, but preinitializes the -@samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and -@samp{References} header fields based on the message you are replying -to. The @samp{To} field starts out as the address of the person who -sent the message you received, and the @samp{CC} field starts out with -all the other recipients of that message. - -@vindex mail-dont-reply-to-names - You can exclude certain recipients from being included automatically -in replies, using the variable @code{mail-dont-reply-to-names}. Its -value should be a regular expression; any recipients that match are -excluded from the @samp{CC} field. They are also excluded from the -@samp{To} field, unless this would leave the field empty. If this -variable is nil, then the first time you compose a reply it is -initialized to a default value that matches your own address. - - To omit the @samp{CC} field completely for a particular reply, enter -the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}. -This means to reply only to the sender of the original message. - - Once the mail composition buffer has been initialized, editing and -sending the mail goes as usual (@pxref{Sending Mail}). You can edit -the presupplied header fields if they are not what you want. You can -also use commands such as @kbd{C-c C-y}, which yanks in the message -that you are replying to (@pxref{Mail Commands}). You can also switch -to the Rmail buffer, select a different message there, switch back, -and yank the new current message. - -@kindex M-m @r{(Rmail)} -@findex rmail-retry-failure -@cindex retrying a failed message -@vindex rmail-retry-ignored-headers - Sometimes a message does not reach its destination. Mailers usually -send the failed message back to you, enclosed in a @dfn{failure -message}. The Rmail command @kbd{M-m} (@code{rmail-retry-failure}) -prepares to send the same message a second time: it sets up a -mail composition buffer with the same text and header fields as before. If -you type @kbd{C-c C-c} right away, you send the message again exactly -the same as the first time. Alternatively, you can edit the text or -headers and then send it. The variable -@code{rmail-retry-ignored-headers}, in the same format as -@code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which -headers are stripped from the failed message when retrying it. - -@kindex f @r{(Rmail)} -@findex rmail-forward -@cindex forwarding a message - Another frequent reason to send mail in Rmail is to @dfn{forward} the -current message to other users. @kbd{f} (@code{rmail-forward}) makes -this easy by preinitializing the mail composition buffer with the current -message as the text, and a subject of the form @code{[@var{from}: -@var{subject}]}, where @var{from} and @var{subject} are the sender and -subject of the original message. All you have to do is fill in the -recipients and send. When you forward a message, recipients get a -message which is ``from'' you, and which has the original message in -its contents. - -@vindex rmail-enable-mime-composing -@findex unforward-rmail-message - Rmail offers two formats for forwarded messages. The default is to -use MIME (@pxref{Rmail Display}) format. This includes the original -message as a separate part. You can use a simpler format if you -prefer, by setting the variable @code{rmail-enable-mime-composing} to -@code{nil}. In this case, Rmail just includes the original message -enclosed between two delimiter lines. It also modifies every line -that starts with a dash, by inserting @w{@samp{- }} at the start of -the line. When you receive a forwarded message in this format, if it -contains something besides ordinary text---for example, program source -code---you might find it useful to undo that transformation. You can -do this by selecting the forwarded message and typing @kbd{M-x -unforward-rmail-message}. This command extracts the original -forwarded message, deleting the inserted @w{@samp{- }} strings, and -inserts it into the Rmail file as a separate message immediately -following the current one. - -@findex rmail-resend - @dfn{Resending} is an alternative similar to forwarding; the -difference is that resending sends a message that is ``from'' the -original sender, just as it reached you---with a few added header fields -(@samp{Resent-From} and @samp{Resent-To}) to indicate that it came via -you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs -@code{rmail-forward}, which invokes @code{rmail-resend} if you provide a -numeric argument.) - -@kindex m @r{(Rmail)} -@findex rmail-mail - Use the @kbd{m} (@code{rmail-mail}) command to start editing an -outgoing message that is not a reply. It leaves the header fields empty. -Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer -accessible for @kbd{C-c C-y}, just as @kbd{r} does. -@ignore -@c Not a good idea, because it does not include Reply-To etc. -Thus, @kbd{m} can be used to reply to or forward a message; it can do -anything @kbd{r} or @kbd{f} can do. -@end ignore - -@kindex c @r{(Rmail)} -@findex rmail-continue - The @kbd{c} (@code{rmail-continue}) command resumes editing the -mail composition buffer, to finish editing an outgoing message you were -already composing, or to alter a message you have sent. - -@vindex rmail-mail-new-frame - If you set the variable @code{rmail-mail-new-frame} to a -non-@code{nil} value, then all the Rmail commands to start sending a -message create a new frame to edit it in. This frame is deleted when -you send the message. -@ignore -@c FIXME does not work with Message -> Kill Message -, or when you use the @samp{Cancel} item in the @samp{Mail} menu. -@end ignore - - All the Rmail commands to send a message use the mail-composition -method that you have chosen (@pxref{Mail Methods}). - -@node Rmail Summary -@section Summaries -@cindex summary (Rmail) - - A @dfn{summary} is a buffer containing one line per message to give -you an overview of the mail in an Rmail file. Each line shows the -message number and date, the sender, the line count, the labels, and -the subject. Moving point in the summary buffer selects messages as -you move to their summary lines. Almost all Rmail commands are valid -in the summary buffer also; when used there, they apply to the message -described by the current line of the summary. - - A summary buffer applies to a single Rmail file only; if you are -editing multiple Rmail files, each one can have its own summary buffer. -The summary buffer name is made by appending @samp{-summary} to the -Rmail buffer's name. Normally only one summary buffer is displayed at a -time. - -@menu -* Rmail Make Summary:: Making various sorts of summaries. -* Rmail Summary Edit:: Manipulating messages from the summary. -@end menu - -@node Rmail Make Summary -@subsection Making Summaries - - Here are the commands to create a summary for the current Rmail -buffer. Once the Rmail buffer has a summary, changes in the Rmail -buffer (such as deleting or expunging messages, and getting new mail) -automatically update the summary. - -@table @kbd -@item h -@itemx C-M-h -Summarize all messages (@code{rmail-summary}). -@item l @var{labels} @key{RET} -@itemx C-M-l @var{labels} @key{RET} -Summarize messages that have one or more of the specified labels -(@code{rmail-summary-by-labels}). -@item C-M-r @var{rcpts} @key{RET} -Summarize messages that match the specified recipients -(@code{rmail-summary-by-recipients}). -@item C-M-t @var{topic} @key{RET} -Summarize messages that have a match for the specified regexp -@var{topic} in their subjects (@code{rmail-summary-by-topic}). -@item C-M-s @var{regexp} @key{RET} -Summarize messages whose headers match the specified regular expression -@var{regexp} (@code{rmail-summary-by-regexp}). -@item C-M-f @var{senders} @key{RET} -Summarize messages that match the specified senders. -(@code{rmail-summary-by-senders}). -@end table - -@kindex h @r{(Rmail)} -@findex rmail-summary - The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer -for the current Rmail buffer with a summary of all the messages in the buffer. -It then displays and selects the summary buffer in another window. - -@kindex l @r{(Rmail)} -@kindex C-M-l @r{(Rmail)} -@findex rmail-summary-by-labels - @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes -a partial summary mentioning only the messages that have one or more of the -labels @var{labels}. @var{labels} should contain label names separated by -commas. - -@kindex C-M-r @r{(Rmail)} -@findex rmail-summary-by-recipients - @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients}) -makes a partial summary mentioning only the messages that have one or -more recipients matching the regular expression @var{rcpts}. You can -use commas to separate multiple regular expressions. These are matched -against the @samp{To}, @samp{From}, and @samp{CC} headers (supply a prefix -argument to exclude this header). - -@kindex C-M-t @r{(Rmail)} -@findex rmail-summary-by-topic - @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic}) -makes a partial summary mentioning only the messages whose subjects have -a match for the regular expression @var{topic}. You can use commas to -separate multiple regular expressions. With a prefix argument, the -match is against the whole message, not just the subject. - -@kindex C-M-s @r{(Rmail)} -@findex rmail-summary-by-regexp - @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp}) -makes a partial summary that mentions only the messages whose headers -(including the date and the subject lines) match the regular -expression @var{regexp}. - -@kindex C-M-f @r{(Rmail)} -@findex rmail-summary-by-senders - @kbd{C-M-f @var{senders} @key{RET}} (@code{rmail-summary-by-senders}) -makes a partial summary that mentions only the messages whose @samp{From} -fields match the regular expression @var{senders}. You can use commas to -separate multiple regular expressions. - - Note that there is only one summary buffer for any Rmail buffer; -making any kind of summary discards any previous summary. - -@vindex rmail-summary-window-size -@vindex rmail-summary-line-count-flag - The variable @code{rmail-summary-window-size} says how many lines to -use for the summary window. The variable -@code{rmail-summary-line-count-flag} controls whether the summary line -for a message should include the line count of the message. Setting -this option to nil might speed up the generation of summaries. - -@node Rmail Summary Edit -@subsection Editing in Summaries - - You can use the Rmail summary buffer to do almost anything you can do -in the Rmail buffer itself. In fact, once you have a summary buffer, -there's no need to switch back to the Rmail buffer. - - You can select and display various messages in the Rmail buffer, from -the summary buffer, just by moving point in the summary buffer to -different lines. It doesn't matter what Emacs command you use to move -point; whichever line point is on at the end of the command, that -message is selected in the Rmail buffer. - - Almost all Rmail commands work in the summary buffer as well as in the -Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current -message, @kbd{u} undeletes, and @kbd{x} expunges. (However, in the -summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u} -serves as a repeat count. A negative argument reverses the meaning of -@kbd{d} and @kbd{C-d}. Also, if there are no more undeleted messages in -the relevant direction, the delete commands go to the first or last -message, rather than staying on the current message.) @kbd{o} and -@kbd{C-o} output the current message to a FILE; @kbd{r} starts a reply -to it; etc. You can scroll the current message while remaining in the -summary buffer using @key{SPC} and @key{DEL}. -@c rmail-summary-scroll-between-messages not mentioned. - -@findex rmail-summary-undelete-many -@kbd{M-u} (@code{rmail-summary-undelete-many}) undeletes all deleted -messages in the summary. A prefix argument means to undelete that many -of the previous deleted messages. - - The Rmail commands to move between messages also work in the summary -buffer, but with a twist: they move through the set of messages included -in the summary. They also ensure the Rmail buffer appears on the screen -(unlike cursor motion commands, which update the contents of the Rmail -buffer but don't display it in a window unless it already appears). -Here is a list of these commands: - -@table @kbd -@item n -Move to next line, skipping lines saying `deleted', and select its -message (@code{rmail-summary-next-msg}). -@item p -Move to previous line, skipping lines saying `deleted', and select -its message (@code{rmail-summary-previous-msg}). -@item M-n -Move to next line and select its message (@code{rmail-summary-next-all}). -@item M-p -Move to previous line and select its message -(@code{rmail-summary-previous-all}). -@item > -Move to the last line, and select its message -(@code{rmail-summary-last-message}). -@item < -Move to the first line, and select its message -(@code{rmail-summary-first-message}). -@item j -@itemx @key{RET} -Select the message on the current line (ensuring that the Rmail buffer -appears on the screen; @code{rmail-summary-goto-msg}). With argument -@var{n}, select message number @var{n} and move to its line in the -summary buffer; this signals an error if the message is not listed in -the summary buffer. -@item M-s @var{pattern} @key{RET} -Search through messages for @var{pattern} starting with the current -message; select the message found, and move point in the summary buffer -to that message's line (@code{rmail-summary-search}). A prefix argument -acts as a repeat count; a negative argument means search backward -(equivalent to @code{rmail-summary-search-backward}.) -@item C-M-n @var{labels} @key{RET} -Move to the next message with at least one of the specified labels -(@code{rmail-summary-next-labeled-message}). @var{labels} is a -comma-separated list of labels. A prefix argument acts as a repeat -count. -@item C-M-p @var{labels} @key{RET} -Move to the previous message with at least one of the specified labels -(@code{rmail-summary-previous-labeled-message}). -@item C-c C-n @key{RET} -Move to the next message with the same subject as the current message -(@code{rmail-summary-next-same-subject}). A prefix argument acts as a -repeat count. -@item C-c C-p @key{RET} -Move to the previous message with the same subject as the current message -(@code{rmail-summary-previous-same-subject}). -@end table - -@vindex rmail-redisplay-summary - Deletion, undeletion, and getting new mail, and even selection of a -different message all update the summary buffer when you do them in the -Rmail buffer. If the variable @code{rmail-redisplay-summary} is -non-@code{nil}, these actions also bring the summary buffer back onto -the screen. - -@kindex Q @r{(Rmail summary)} -@findex rmail-summary-wipe -@kindex q @r{(Rmail summary)} -@findex rmail-summary-quit -@kindex b @r{(Rmail summary)} -@findex rmail-summary-bury - When you are finished using the summary, type @kbd{Q} -(@code{rmail-summary-wipe}) to delete the summary buffer's window. You -can also exit Rmail while in the summary: @kbd{q} -(@code{rmail-summary-quit}) deletes the summary window, then exits from -Rmail by saving the Rmail file and switching to another buffer. -Alternatively, @kbd{b} (@code{rmail-summary-bury}) simply buries the -Rmail summary and buffer. - -@node Rmail Sorting -@section Sorting the Rmail File -@cindex sorting Rmail file -@cindex Rmail file sorting - -@table @kbd -@findex rmail-sort-by-date -@item C-c C-s C-d -@itemx M-x rmail-sort-by-date -Sort messages of current Rmail buffer by date. - -@findex rmail-sort-by-subject -@item C-c C-s C-s -@itemx M-x rmail-sort-by-subject -Sort messages of current Rmail buffer by subject. - -@findex rmail-sort-by-author -@item C-c C-s C-a -@itemx M-x rmail-sort-by-author -Sort messages of current Rmail buffer by author's name. - -@findex rmail-sort-by-recipient -@item C-c C-s C-r -@itemx M-x rmail-sort-by-recipient -Sort messages of current Rmail buffer by recipient's names. - -@findex rmail-sort-by-correspondent -@item C-c C-s C-c -@itemx M-x rmail-sort-by-correspondent -Sort messages of current Rmail buffer by the name of the other -correspondent. - -@findex rmail-sort-by-lines -@item C-c C-s C-l -@itemx M-x rmail-sort-by-lines -Sort messages of current Rmail buffer by number of lines. - -@findex rmail-sort-by-labels -@item C-c C-s C-k @key{RET} @var{labels} @key{RET} -@itemx M-x rmail-sort-by-labels @key{RET} @var{labels} @key{RET} -Sort messages of current Rmail buffer by labels. The argument -@var{labels} should be a comma-separated list of labels. The order of -these labels specifies the order of messages; messages with the first -label come first, messages with the second label come second, and so on. -Messages that have none of these labels come last. -@end table - - The Rmail sort commands perform a @emph{stable sort}: if there is no -reason to prefer either one of two messages, their order remains -unchanged. You can use this to sort by more than one criterion. For -example, if you use @code{rmail-sort-by-date} and then -@code{rmail-sort-by-author}, messages from the same author appear in -order by date. - - With a prefix argument, all these commands reverse the order of -comparison. This means they sort messages from newest to oldest, from -biggest to smallest, or in reverse alphabetical order. - - The same keys in the summary buffer run similar functions; for -example, @kbd{C-c C-s C-l} runs @code{rmail-summary-sort-by-lines}. -Note that these commands always sort the whole Rmail buffer, even if the -summary is only showing a subset of messages. - - Note that you cannot undo a sort, so you may wish to save the Rmail -buffer before sorting it. - -@node Rmail Display -@section Display of Messages - - This section describes how Rmail displays mail headers, -@acronym{MIME} sections and attachments, URLs, and encrypted messages. - -@table @kbd -@item t -Toggle display of complete header (@code{rmail-toggle-header}). -@end table - -@kindex t @r{(Rmail)} -@findex rmail-toggle-header - Before displaying each message for the first time, Rmail reformats -its header, hiding uninteresting header fields to reduce clutter. The -@kbd{t} (@code{rmail-toggle-header}) command toggles this, switching -between showing the reformatted header fields and showing the -complete, original header. With a positive prefix argument, the -command shows the reformatted header; with a zero or negative prefix -argument, it shows the full header. Selecting the message again also -reformats it if necessary. - -@vindex rmail-ignored-headers -@vindex rmail-displayed-headers -@vindex rmail-nonignored-headers - The variable @code{rmail-ignored-headers} holds a regular expression -specifying the header fields to hide; any matching header line will be -hidden. The variable @code{rmail-nonignored-headers} overrides this: -any header field matching that regular expression is shown even if it -matches @code{rmail-ignored-headers} too. The variable -@code{rmail-displayed-headers} is an alternative to these two -variables; if non-@code{nil}, this should be a regular expression -specifying which headers to display (the default is @code{nil}). - -@vindex rmail-highlighted-headers - Rmail highlights certain header fields that are especially -interesting---by default, the @samp{From} and @samp{Subject} fields. -This highlighting uses the @code{rmail-highlight} face. The variable -@code{rmail-highlighted-headers} holds a regular expression specifying -the header fields to highlight; if it matches the beginning of a -header field, that whole field is highlighted. To disable this -feature, set @code{rmail-highlighted-headers} to @code{nil}. - -@cindex MIME messages (Rmail) -@vindex rmail-enable-mime - If a message is in @acronym{MIME} (Multipurpose Internet Mail -Extensions) format and contains multiple parts (@acronym{MIME} -entities), Rmail displays each part with a @dfn{tagline}. The tagline -summarizes the part's index, size, and content type. Depending on the -content type, it may also contain one or more buttons; these perform -actions such as saving the part into a file. - -@table @kbd -@findex rmail-mime-toggle-hidden -@item @key{RET} -Hide or show the @acronym{MIME} part at point -(@code{rmail-mime-toggle-hidden}). - -@findex rmail-mime-next-item -@item @key{TAB} -Move point to the next @acronym{MIME} tagline button. -(@code{rmail-mime-next-item}). - -@findex rmail-mime-previous-item -@item S-@key{TAB} -Move point to the previous @acronym{MIME} part -(@code{rmail-mime-previous-item}). - -@findex rmail-mime -@item v -@kindex v @r{(Rmail)} -Toggle between @acronym{MIME} display and raw message -(@code{rmail-mime}). -@end table - - Each plain-text @acronym{MIME} part is initially displayed -immediately after its tagline, as part of the Rmail buffer, while -@acronym{MIME} parts of other types are represented only by their -taglines, with their actual contents hidden. In either case, you can -toggle a @acronym{MIME} part between its ``displayed'' and ``hidden'' -states by typing @key{RET} anywhere in the part---or anywhere in its -tagline (except for buttons for other actions, if there are any). Type -@key{RET} (or click with the mouse) to activate a tagline button, and -@key{TAB} to cycle point between tagline buttons. - - The @kbd{v} (@code{rmail-mime}) command toggles between the default -@acronym{MIME} display described above, and a ``raw'' display showing -the undecoded @acronym{MIME} data. With a prefix argument, this -command toggles the display of only an entity at point. - - To prevent Rmail from handling MIME decoded messages, change the -variable @code{rmail-enable-mime} to @code{nil}. When this is the -case, the @kbd{v} (@code{rmail-mime}) command instead creates a -temporary buffer to display the current @acronym{MIME} message. - -@findex rmail-epa-decrypt -@cindex encrypted mails (reading in Rmail) - If the current message is an encrypted one, use the command @kbd{M-x -rmail-epa-decrypt} to decrypt it, using the EasyPG library -(@pxref{Top,, EasyPG, epa, EasyPG Assistant User's Manual}). - - You can highlight and activate URLs in the Rmail buffer using Goto -Address mode: - -@c FIXME goto-addr.el commentary says to use goto-address instead. -@example -(add-hook 'rmail-show-message-hook 'goto-address-mode) -@end example - -@noindent -Then you can browse these URLs by clicking on them with @kbd{Mouse-2} -(or @kbd{Mouse-1} quickly) or by moving to one and typing @kbd{C-c -@key{RET}}. @xref{Goto Address mode, Activating URLs, Activating URLs}. - -@node Rmail Coding -@section Rmail and Coding Systems - -@cindex decoding mail messages (Rmail) - Rmail automatically decodes messages which contain non-@acronym{ASCII} -characters, just as Emacs does with files you visit and with subprocess -output. Rmail uses the standard @samp{charset=@var{charset}} header in -the message, if any, to determine how the message was encoded by the -sender. It maps @var{charset} into the corresponding Emacs coding -system (@pxref{Coding Systems}), and uses that coding system to decode -message text. If the message header doesn't have the @samp{charset} -specification, or if @var{charset} is not recognized, -Rmail chooses the coding system with the usual Emacs heuristics and -defaults (@pxref{Recognize Coding}). - -@cindex fixing incorrectly decoded mail messages - Occasionally, a message is decoded incorrectly, either because Emacs -guessed the wrong coding system in the absence of the @samp{charset} -specification, or because the specification was inaccurate. For -example, a misconfigured mailer could send a message with a -@samp{charset=iso-8859-1} header when the message is actually encoded -in @code{koi8-r}. When you see the message text garbled, or some of -its characters displayed as hex codes or empty boxes, this may have -happened. - -@findex rmail-redecode-body - You can correct the problem by decoding the message again using the -right coding system, if you can figure out or guess which one is -right. To do this, invoke the @kbd{M-x rmail-redecode-body} command. -It reads the name of a coding system, and then redecodes the message -using the coding system you specified. If you specified the right -coding system, the result should be readable. - -@node Rmail Editing -@section Editing Within a Message - - Most of the usual Emacs key bindings are available in Rmail mode, -though a few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by -Rmail for other purposes. However, the Rmail buffer is normally read -only, and most of the letters are redefined as Rmail commands. If you -want to edit the text of a message, you must use the Rmail command -@kbd{e}. - -@table @kbd -@item e -Edit the current message as ordinary text. -@end table - -@kindex e @r{(Rmail)} -@findex rmail-edit-current-message - The @kbd{e} command (@code{rmail-edit-current-message}) switches from -Rmail mode into Rmail Edit mode, another major mode which is nearly the -same as Text mode. The mode line indicates this change. - - In Rmail Edit mode, letters insert themselves as usual and the Rmail -commands are not available. You can edit the message body and header -fields. When you are finished editing the message, type @kbd{C-c C-c} -to switch back to Rmail mode. Alternatively, you can return to Rmail -mode but cancel any editing that you have done, by typing @kbd{C-c C-]}. - -@vindex rmail-edit-mode-hook - Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then -it runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}). -Returning to ordinary Rmail mode adds the attribute @samp{edited} to -the message, if you have made any changes in it. - -@node Rmail Digest -@section Digest Messages -@cindex digest message -@cindex undigestify - - A @dfn{digest message} is a message which exists to contain and carry -several other messages. Digests are used on some mailing -lists; all the messages that arrive for the list during a period of time -such as one day are put inside a single digest which is then sent to the -subscribers. Transmitting the single digest uses less computer -time than transmitting the individual messages even though the total -size is the same, because of the per-message overhead in network mail -transmission. - -@findex undigestify-rmail-message - When you receive a digest message, the most convenient way to read it is -to @dfn{undigestify} it: to turn it back into many individual messages. -Then you can read and delete the individual messages as it suits you. -To do this, select the digest message and type the command @kbd{M-x -undigestify-rmail-message}. This extracts the submessages as separate -Rmail messages, and inserts them following the digest. The digest -message itself is flagged as deleted. - -@node Rmail Rot13 -@section Reading Rot13 Messages -@cindex rot13 code - - Mailing list messages that might offend or annoy some readers are sometimes -encoded in a simple code called @dfn{rot13}---so named because it -rotates the alphabet by 13 letters. This code is not for secrecy, as it -provides none; rather, it enables those who wish to to avoid -seeing the real text of the message. For example, a review of a film -might use rot13 to hide important plot points. - -@findex rot13-other-window - To view a buffer that uses the rot13 code, use the command @kbd{M-x -rot13-other-window}. This displays the current buffer in another window -which applies the code when displaying the text. - -@node Movemail -@section @code{movemail} program -@cindex @code{movemail} program - - Rmail uses the @code{movemail} program to move mail from your inbox to -your Rmail file (@pxref{Rmail Inbox}). When loaded for the first time, -Rmail attempts to locate the @code{movemail} program and determine its -version. There are two versions of the @code{movemail} program: the -native one, shipped with GNU Emacs (the ``emacs version'') and the one -included in GNU mailutils (the ``mailutils version'', -@pxref{movemail,,,mailutils,GNU mailutils}). They support the same -command line syntax and the same basic subset of options. However, the -Mailutils version offers additional features. - - The Emacs version of @code{movemail} is able to retrieve mail from -the usual Unix mailbox formats and from remote mailboxes using the -POP3 protocol. - - The Mailutils version is able to handle a wide set of mailbox -formats, such as plain Unix mailboxes, @code{maildir} and @code{MH} -mailboxes, etc. It is able to access remote mailboxes using the POP3 -or IMAP4 protocol, and can retrieve mail from them using a TLS -encrypted channel. It also accepts mailbox arguments in @acronym{URL} -form. The detailed description of mailbox @acronym{URL}s can be found -in @ref{URL,,,mailutils,Mailbox URL Formats}. In short, a -@acronym{URL} is: - -@smallexample -@var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name} -@end smallexample - -@noindent -where square brackets denote optional elements. - -@table @var -@item proto -Specifies the @dfn{mailbox protocol}, or @dfn{format} to -use. The exact semantics of the rest of @acronym{URL} elements depends -on the actual value of @var{proto} (see below). - -@item user -User name to access the remote mailbox. - -@item password -User password to access the remote mailbox. - -@item host-or-file-name -Hostname of the remote server for remote mailboxes or file name of a -local mailbox. -@end table - -@noindent -@var{Proto} can be one of: - -@table @code -@item mbox -Usual Unix mailbox format. In this case, neither @var{user} nor -@var{pass} are used, and @var{host-or-file-name} denotes the file name -of the mailbox file, e.g., @code{mbox://var/spool/mail/smith}. - -@item mh -A local mailbox in the @acronym{MH} format. @var{User} and -@var{pass} are not used. @var{Host-or-file-name} denotes the name of -@acronym{MH} folder, e.g., @code{mh://Mail/inbox}. - -@item maildir -A local mailbox in the @acronym{maildir} format. @var{User} and -@var{pass} are not used, and @var{host-or-file-name} denotes the name of -@code{maildir} mailbox, e.g., @code{maildir://mail/inbox}. - -@item file -Any local mailbox format. Its actual format is detected automatically -by @code{movemail}. - -@item pop -A remote mailbox to be accessed via POP3 protocol. @var{User} -specifies the remote user name to use, @var{pass} may be used to -specify the user password, @var{host-or-file-name} is the name or IP -address of the remote mail server to connect to; e.g., -@code{pop://smith:guessme@@remote.server.net}. - -@item imap -A remote mailbox to be accessed via IMAP4 protocol. @var{User} -specifies the remote user name to use, @var{pass} may be used to -specify the user password, @var{host-or-file-name} is the name or IP -address of the remote mail server to connect to; -e.g., @code{imap://smith:guessme@@remote.server.net}. -@end table - - Alternatively, you can specify the file name of the mailbox to use. -This is equivalent to specifying the @samp{file} protocol: - -@smallexample -/var/spool/mail/@var{user} @equiv{} file://var/spool/mail/@var{user} -@end smallexample - -@vindex rmail-movemail-program -@vindex rmail-movemail-search-path - The variable @code{rmail-movemail-program} controls which version of -@code{movemail} to use. If that is a string, it specifies the -absolute file name of the @code{movemail} executable. If it is -@code{nil}, Rmail searches for @code{movemail} in the directories -listed in @code{rmail-movemail-search-path}, then in @code{exec-path} -(@pxref{Shell}), then in @code{exec-directory}. - -@node Remote Mailboxes -@section Retrieving Mail from Remote Mailboxes -@pindex movemail - - Some sites use a method called POP for accessing users' inbox data -instead of storing the data in inbox files. By default, the @code{Emacs -movemail} can work with POP (unless the Emacs @code{configure} script -was run with the option @samp{--without-pop}). - -Similarly, the Mailutils @code{movemail} by default supports POP, unless -it was configured with the @samp{--disable-pop} option. - -Both versions of @code{movemail} only work with POP3, not with older -versions of POP. - -@cindex @env{MAILHOST} environment variable -@cindex POP mailboxes - No matter which flavor of @code{movemail} you use, you can specify -a POP inbox by using a POP @dfn{URL} (@pxref{Movemail}). A POP -@acronym{URL} is a ``file name'' of the form -@samp{pop://@var{username}@@@var{hostname}}, where -@var{hostname} is the host name or IP address of the remote mail -server and @var{username} is the user name on that server. -Additionally, you may specify the password in the mailbox @acronym{URL}: -@samp{pop://@var{username}:@var{password}@@@var{hostname}}. In this -case, @var{password} takes preference over the one set by -@code{rmail-remote-password} (see below). This is especially useful -if you have several remote mailboxes with different passwords. - - For backward compatibility, Rmail also supports an alternative way of -specifying remote POP mailboxes. Specifying an inbox name in the form -@samp{po:@var{username}:@var{hostname}} is equivalent to -@samp{pop://@var{username}@@@var{hostname}}. If you omit the -@var{:hostname} part, the @env{MAILHOST} environment variable specifies -the machine on which to look for the POP server. - -@c FIXME mention --with-hesiod "support Hesiod to get the POP server host"? - -@cindex IMAP mailboxes - Another method for accessing remote mailboxes is IMAP. This method is -supported only by the Mailutils @code{movemail}. To specify an IMAP -mailbox in the inbox list, use the following mailbox @acronym{URL}: -@samp{imap://@var{username}[:@var{password}]@@@var{hostname}}. The -@var{password} part is optional, as described above. - -@vindex rmail-remote-password -@vindex rmail-remote-password-required - Accessing a remote mailbox may require a password. Rmail uses the -following algorithm to retrieve it: - -@enumerate -@item -If a @var{password} is present in the mailbox URL (see above), it is -used. -@item -If the variable @code{rmail-remote-password-required} is @code{nil}, -Rmail assumes no password is required. -@item -If the variable @code{rmail-remote-password} is non-@code{nil}, its -value is used. -@item -Otherwise, Rmail will ask you for the password to use. -@end enumerate - -@vindex rmail-movemail-flags - If you need to pass additional command-line flags to @code{movemail}, -set the variable @code{rmail-movemail-flags} a list of the flags you -wish to use. Do not use this variable to pass the @samp{-p} flag to -preserve your inbox contents; use @code{rmail-preserve-inbox} instead. - -@cindex Kerberos POP authentication - The @code{movemail} program installed at your site may support -Kerberos authentication (the Emacs @code{movemail} does so if Emacs was -configured with the option @code{--with-kerberos} or -@code{--with-kerberos5}). If it is supported, it is used by default -whenever you attempt to retrieve POP mail when -@code{rmail-remote-password} and @code{rmail-remote-password-required} -are unset. - -@cindex reverse order in POP inboxes - Some POP servers store messages in reverse order. If your server does -this, and you would rather read your mail in the order in which it was -received, you can tell @code{movemail} to reverse the order of -downloaded messages by adding the @samp{-r} flag to -@code{rmail-movemail-flags}. - -@cindex TLS encryption (Rmail) - Mailutils @code{movemail} supports TLS encryption. If you wish to -use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}. - -@node Other Mailbox Formats -@section Retrieving Mail from Local Mailboxes in Various Formats - - If your incoming mail is stored on a local machine in a format other -than Unix mailbox, you will need the Mailutils @code{movemail} to -retrieve it. @xref{Movemail}, for the detailed description of -@code{movemail} versions. For example, to access mail from a inbox in -@code{maildir} format located in @file{/var/spool/mail/in}, you would -include the following in the Rmail inbox list: - -@smallexample -maildir://var/spool/mail/in -@end smallexample diff --git a/doc/emacs/screen.texi b/doc/emacs/screen.texi deleted file mode 100644 index fbea52523ba..00000000000 --- a/doc/emacs/screen.texi +++ /dev/null @@ -1,318 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Screen, User Input, Acknowledgments, Top -@chapter The Organization of the Screen -@cindex screen -@cindex frame - - On a graphical display, such as on GNU/Linux using the X Window -System, Emacs occupies a ``graphical window''. On a text terminal, -Emacs occupies the entire terminal screen. We will use the term -@dfn{frame} to mean a graphical window or terminal screen occupied by -Emacs. Emacs behaves very similarly on both kinds of frames. It -normally starts out with just one frame, but you can create additional -frames if you wish (@pxref{Frames}). - - Each frame consists of several distinct regions. At the top of the -frame is a @dfn{menu bar}, which allows you to access commands via a -series of menus. On a graphical display, directly below the menu bar -is a @dfn{tool bar}, a row of icons that perform editing commands if -you click on them. At the very bottom of the frame is an @dfn{echo -area}, where informative messages are displayed and where you enter -information when Emacs asks for it. - - The main area of the frame, below the tool bar (if one exists) and -above the echo area, is called @dfn{the window}. Henceforth in this -manual, we will use the word ``window'' in this sense. Graphical -display systems commonly use the word ``window'' with a different -meaning; but, as stated above, we refer to those ``graphical windows'' -as ``frames''. - - An Emacs window is where the @dfn{buffer}---the text you are -editing---is displayed. On a graphical display, the window possesses -a @dfn{scroll bar} on one side, which can be used to scroll through -the buffer. The last line of the window is a @dfn{mode line}. This -displays various information about what is going on in the buffer, -such as whether there are unsaved changes, the editing modes that are -in use, the current line number, and so forth. - - When you start Emacs, there is normally only one window in the -frame. However, you can subdivide this window horizontally or -vertically to create multiple windows, each of which can independently -display a buffer (@pxref{Windows}). - - At any time, one window is the @dfn{selected window}. On a -graphical display, the selected window shows a more prominent cursor -(usually solid and blinking); other windows show a less prominent -cursor (usually a hollow box). On a text terminal, there is only one -cursor, which is shown in the selected window. The buffer displayed -in the selected window is called the @dfn{current buffer}, and it is -where editing happens. Most Emacs commands implicitly apply to the -current buffer; the text displayed in unselected windows is mostly -visible for reference. If you use multiple frames on a graphical -display, selecting a particular frame selects a window in that frame. - -@menu -* Point:: The place in the text where editing commands operate. -* Echo Area:: Short messages appear at the bottom of the screen. -* Mode Line:: Interpreting the mode line. -* Menu Bar:: How to use the menu bar. -@end menu - -@node Point -@section Point -@cindex point -@cindex cursor - - The cursor in the selected window shows the location where most -editing commands take effect, which is called @dfn{point}@footnote{The -term ``point'' comes from the character @samp{.}, which was the -command in TECO (the language in which the original Emacs was written) -for accessing the editing position.}. Many Emacs commands move point -to different places in the buffer; for example, you can place point by -clicking mouse button 1 (normally the left button) at the desired -location. - - By default, the cursor in the selected window is drawn as a solid -block and appears to be @emph{on} a character, but you should think of -point as @emph{between} two characters; it is situated @emph{before} -the character under the cursor. For example, if your text looks like -@samp{frob} with the cursor over the @samp{b}, then point is between -the @samp{o} and the @samp{b}. If you insert the character @samp{!} -at that position, the result is @samp{fro!b}, with point between the -@samp{!} and the @samp{b}. Thus, the cursor remains over the -@samp{b}, as before. - - If you are editing several files in Emacs, each in its own buffer, -each buffer has its own value of point. A buffer that is not -currently displayed remembers its value of point if you later display -it again. Furthermore, if a buffer is displayed in multiple windows, -each of those windows has its own value of point. - - @xref{Cursor Display}, for options that control how Emacs displays -the cursor. - -@node Echo Area -@section The Echo Area -@cindex echo area - - The line at the very bottom of the frame is the @dfn{echo area}. It -is used to display small amounts of text for various purposes. - -@cindex echoing - The echo area is so-named because one of the things it is used for -is @dfn{echoing}, which means displaying the characters of a -multi-character command as you type. Single-character commands are -not echoed. Multi-character commands (@pxref{Keys}) are echoed if you -pause for more than a second in the middle of a command. Emacs then -echoes all the characters of the command so far, to prompt you for the -rest. Once echoing has started, the rest of the command echoes -immediately as you type it. This behavior is designed to give -confident users fast response, while giving hesitant users maximum -feedback. - -@cindex error message -@cindex echo area message - The echo area is also used to display an @dfn{error message} when a -command cannot do its job. Error messages may be accompanied by -beeping or by flashing the screen. - - Some commands display informative messages in the echo area to tell -you what the command has done, or to provide you with some specific -information. These @dfn{informative} messages, unlike error messages, -are not accompanied with a beep or flash. For example, @kbd{C-x =} -(hold down @key{CTRL} and type @kbd{x}, then let go of @key{CTRL} and -type @kbd{=}) displays a message describing the character at point, -its position in the buffer, and its current column in the window. -Commands that take a long time often display messages ending in -@samp{...} while they are working (sometimes also indicating how much -progress has been made, as a percentage), and add @samp{done} when -they are finished. - -@cindex @file{*Messages*} buffer -@cindex saved echo area messages -@cindex messages saved from echo area -@vindex message-log-max - Informative echo area messages are saved in a special buffer named -@file{*Messages*}. (We have not explained buffers yet; see -@ref{Buffers}, for more information about them.) If you miss a -message that appeared briefly on the screen, you can switch to the -@file{*Messages*} buffer to see it again. The @file{*Messages*} -buffer is limited to a certain number of lines, specified by the -variable @code{message-log-max}. (We have not explained variables -either; see @ref{Variables}, for more information about them.) Beyond -this limit, one line is deleted from the beginning whenever a new -message line is added at the end. - - @xref{Display Custom}, for options that control how Emacs uses the -echo area. - -@cindex minibuffer - The echo area is also used to display the @dfn{minibuffer}, a -special window where you can input arguments to commands, such as the -name of a file to be edited. When the minibuffer is in use, the text -displayed in the echo area begins with a @dfn{prompt string}, and the -active cursor appears within the minibuffer, which is temporarily -considered the selected window. You can always get out of the -minibuffer by typing @kbd{C-g}. @xref{Minibuffer}. - -@node Mode Line -@section The Mode Line -@cindex mode line -@cindex top level - - At the bottom of each window is a @dfn{mode line}, which describes -what is going on in the current buffer. When there is only one -window, the mode line appears right above the echo area; it is the -next-to-last line in the frame. On a graphical display, the mode line -is drawn with a 3D box appearance. Emacs also usually draws the mode -line of the selected window with a different color than that of -unselected windows, in order to make it stand out. - - The text displayed in the mode line has the following format: - -@example - @var{cs}:@var{ch}-@var{fr} @var{buf} @var{pos} @var{line} (@var{major} @var{minor}) -@end example - -@noindent -On a text terminal, this text is followed by a series of dashes -extending to the right edge of the window. These dashes are omitted -on a graphical display. - -The @var{cs} string and the colon character after it describe the -character set and newline convention used for the current buffer. -Normally, Emacs automatically handles these settings for you, but it -is sometimes useful to have this information. - - @var{cs} describes the character set of the text in the buffer -(@pxref{Coding Systems}). If it is a dash (@samp{-}), that indicates -no special character set handling (with the possible exception of -end-of-line conventions, described in the next paragraph). @samp{=} -means no conversion whatsoever, and is usually used for files -containing non-textual data. Other characters represent various -@dfn{coding systems}---for example, @samp{1} represents ISO Latin-1. - - On a text terminal, @var{cs} is preceded by two additional -characters that describe the coding systems for keyboard input and -terminal output. Furthermore, if you are using an input method, -@var{cs} is preceded by a string that identifies the input method -(@pxref{Input Methods}). - -@cindex end-of-line convention, mode-line indication - The character after @var{cs} is usually a colon. If a different -string is displayed, that indicates a nontrivial end-of-line -convention for encoding a file. Usually, lines of text are separated -by @dfn{newline characters} in a file, but two other conventions are -sometimes used. The MS-DOS convention uses a ``carriage-return'' -character followed by a ``linefeed'' character; when editing such -files, the colon changes to either a backslash (@samp{\}) or -@samp{(DOS)}, depending on the operating system. Another convention, -employed by older Macintosh systems, uses a ``carriage-return'' -character instead of a newline; when editing such files, the colon -changes to either a forward slash (@samp{/}) or @samp{(Mac)}. On some -systems, Emacs displays @samp{(Unix)} instead of the colon for files -that use newline as the line separator. - - The next element on the mode line is the string indicated by -@var{ch}. This shows two dashes (@samp{--}) if the buffer displayed -in the window has the same contents as the corresponding file on the -disk; i.e., if the buffer is ``unmodified''. If the buffer is -modified, it shows two stars (@samp{**}). For a read-only buffer, it -shows @samp{%*} if the buffer is modified, and @samp{%%} otherwise. - - The character after @var{ch} is normally a dash (@samp{-}). -However, if the default-directory for the current buffer is on a -remote machine, @samp{@@} is displayed instead (@pxref{File Names}). - - @var{fr} gives the selected frame name (@pxref{Frames}). It appears -only on text terminals. The initial frame's name is @samp{F1}. - - @var{buf} is the name of the buffer displayed in the window. -Usually, this is the same as the name of a file you are editing. -@xref{Buffers}. - - @var{pos} tells you whether there is additional text above the top -of the window, or below the bottom. If your buffer is small and all -of it is visible in the window, @var{pos} is @samp{All}. Otherwise, -it is @samp{Top} if you are looking at the beginning of the buffer, -@samp{Bot} if you are looking at the end of the buffer, or -@samp{@var{nn}%}, where @var{nn} is the percentage of the buffer above -the top of the window. With Size Indication mode, you can display the -size of the buffer as well. @xref{Optional Mode Line}. - - @var{line} is the character @samp{L} followed by the line number at -point. (You can display the current column number too, by turning on -Column Number mode. @xref{Optional Mode Line}.) - - @var{major} is the name of the @dfn{major mode} used in the buffer. -A major mode is a principal editing mode for the buffer, such as Text -mode, Lisp mode, C mode, and so forth. @xref{Major Modes}. Some -major modes display additional information after the major mode name. -For example, Compilation buffers and Shell buffers display the status -of the subprocess. - - @var{minor} is a list of some of the enabled @dfn{minor modes}, -which are optional editing modes that provide additional features on -top of the major mode. @xref{Minor Modes}. - - Some features are listed together with the minor modes whenever they -are turned on, even though they are not really minor modes. -@samp{Narrow} means that the buffer being displayed has editing -restricted to only a portion of its text (@pxref{Narrowing}). -@samp{Def} means that a keyboard macro is currently being defined -(@pxref{Keyboard Macros}). - - In addition, if Emacs is inside a recursive editing level, square -brackets (@samp{[@dots{}]}) appear around the parentheses that -surround the modes. If Emacs is in one recursive editing level within -another, double square brackets appear, and so on. Since recursive -editing levels affect Emacs globally, such square brackets appear in -the mode line of every window. @xref{Recursive Edit}. - - You can change the appearance of the mode line as well as the format -of its contents. @xref{Optional Mode Line}. In addition, the mode -line is mouse-sensitive; clicking on different parts of the mode line -performs various commands. @xref{Mode Line Mouse}. - -@node Menu Bar -@section The Menu Bar -@cindex menu bar - - Each Emacs frame normally has a @dfn{menu bar} at the top which you -can use to perform common operations. There's no need to list them -here, as you can more easily see them yourself. - -@kindex M-` -@kindex F10 -@findex tmm-menubar -@findex menu-bar-open - On a graphical display, you can use the mouse to choose a command -from the menu bar. An arrow on the right edge of a menu item means it -leads to a subsidiary menu, or @dfn{submenu}. A @samp{...} at the end -of a menu item means that the command will prompt you for further -input before it actually does anything. - - Some of the commands in the menu bar have ordinary key bindings as -well; if so, a key binding is shown in parentheses after the item -itself. To view the full command name and documentation for a menu -item, type @kbd{C-h k}, and then select the menu bar with the mouse in -the usual way (@pxref{Key Help}). - - Instead of using the mouse, you can also invoke the first menu bar -item by pressing @key{F10} (to run the command @code{menu-bar-open}). -You can then navigate the menus with the arrow keys. To activate a -selected menu item, press @key{RET}; to cancel menu navigation, press -@key{ESC}. - - On a text terminal, you can use the menu bar by typing @kbd{M-`} or -@key{F10} (these run the command @code{tmm-menubar}). This lets you -select a menu item with the keyboard. A provisional choice appears in -the echo area. You can use the up and down arrow keys to move through -the menu to different items, and then you can type @key{RET} to select -the item. Each menu item is also designated by a letter or digit -(usually the initial of some word in the item's name). This letter or -digit is separated from the item name by @samp{=>}. You can type the -item's letter or digit to select the item. diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi deleted file mode 100644 index 152ac605843..00000000000 --- a/doc/emacs/search.texi +++ /dev/null @@ -1,1372 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Search, Fixit, Display, Top -@chapter Searching and Replacement -@cindex searching -@cindex finding strings within text - - Like other editors, Emacs has commands to search for occurrences of -a string. Emacs also has commands to replace occurrences of a string -with a different string. There are also commands that do the same -thing, but search for patterns instead of fixed strings. - - You can also search multiple files under the control of a tags table -(@pxref{Tags Search}) or through the Dired @kbd{A} command -(@pxref{Operating on Files}), or ask the @code{grep} program to do it -(@pxref{Grep Searching}). - - -@menu -* Incremental Search:: Search happens as you type the string. -* Nonincremental Search:: Specify entire string and then search. -* Word Search:: Search for sequence of words. -* Regexp Search:: Search for match for a regexp. -* Regexps:: Syntax of regular expressions. -* Regexp Backslash:: Regular expression constructs starting with `\'. -* Regexp Example:: A complex regular expression explained. -* Search Case:: To ignore case while searching, or not. -* Replace:: Search, and replace some or all matches. -* Other Repeating Search:: Operating on all matches for some regexp. -@end menu - -@node Incremental Search -@section Incremental Search -@cindex incremental search -@cindex isearch - - The principal search command in Emacs is @dfn{incremental}: it -begins searching as soon as you type the first character of the search -string. As you type in the search string, Emacs shows you where the -string (as you have typed it so far) would be found. When you have -typed enough characters to identify the place you want, you can stop. -Depending on what you plan to do next, you may or may not need to -terminate the search explicitly with @key{RET}. - -@table @kbd -@item C-s -Incremental search forward (@code{isearch-forward}). -@item C-r -Incremental search backward (@code{isearch-backward}). -@end table - -@menu -* Basic Isearch:: Basic incremental search commands. -* Repeat Isearch:: Searching for the same string again. -* Error in Isearch:: When your string is not found. -* Special Isearch:: Special input in incremental search. -* Isearch Yank:: Commands that grab text into the search string - or else edit the search string. -* Isearch Scroll:: Scrolling during an incremental search. -* Isearch Minibuffer:: Incremental search of the minibuffer history. -@end menu - -@node Basic Isearch -@subsection Basics of Incremental Search - -@table @kbd -@item C-s -Begin incremental search (@code{isearch-forward}). -@item C-r -Begin reverse incremental search (@code{isearch-backward}). -@end table - -@kindex C-s -@findex isearch-forward - @kbd{C-s} (@code{isearch-forward}) starts a forward incremental -search. It reads characters from the keyboard, and moves point just -past the end of the next occurrence of those characters in the buffer. - - For instance, if you type @kbd{C-s} and then @kbd{F}, that puts the -cursor after the first @samp{F} that occurs in the buffer after the -starting point. Then if you then type @kbd{O}, the cursor moves to -just after the first @samp{FO}; the @samp{F} in that @samp{FO} might -not be the first @samp{F} previously found. After another @kbd{O}, -the cursor moves to just after the first @samp{FOO}. - -@cindex faces for highlighting search matches - At each step, Emacs highlights the @dfn{current match}---the buffer -text that matches the search string---using the @code{isearch} face -(@pxref{Faces}). The current search string is also displayed in the -echo area. - - If you make a mistake typing the search string, type @key{DEL}. -Each @key{DEL} cancels the last character of the search string. - - When you are satisfied with the place you have reached, type -@key{RET}. This stops searching, leaving the cursor where the search -brought it. Also, any command not specially meaningful in searches -stops the searching and is then executed. Thus, typing @kbd{C-a} -exits the search and then moves to the beginning of the line. -@key{RET} is necessary only if the next command you want to type is a -printing character, @key{DEL}, @key{RET}, or another character that is -special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, -@kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some others -described below). - - As a special exception, entering @key{RET} when the search string is -empty launches nonincremental search (@pxref{Nonincremental Search}). - - When you exit the incremental search, it adds the original value of -point to the mark ring, without activating the mark; you can thus use -@kbd{C-u C-@key{SPC}} to return to where you were before beginning the -search. @xref{Mark Ring}. It only does this if the mark was not -already active. - -@kindex C-r -@findex isearch-backward - To search backwards, use @kbd{C-r} (@code{isearch-backward}) instead -of @kbd{C-s} to start the search. A backward search finds matches -that end before the starting point, just as a forward search finds -matches that begin after it. - -@node Repeat Isearch -@subsection Repeating Incremental Search - - Suppose you search forward for @samp{FOO} and find a match, but not -the one you expected to find: the @samp{FOO} you were aiming for -occurs later in the buffer. In this event, type another @kbd{C-s} to -move to the next occurrence of the search string. You can repeat this -any number of times. If you overshoot, you can cancel some @kbd{C-s} -characters with @key{DEL}. Similarly, each @kbd{C-r} in a backward -incremental search repeats the backward search. - -@cindex lazy search highlighting -@vindex isearch-lazy-highlight - If you pause for a little while during incremental search, Emacs -highlights all the other possible matches for the search string that -are present on the screen. This helps you anticipate where you can -get to by typing @kbd{C-s} or @kbd{C-r} to repeat the search. The -other matches are highlighted differently from the current match, -using the customizable face @code{lazy-highlight} (@pxref{Faces}). If -you don't like this feature, you can disable it by setting -@code{isearch-lazy-highlight} to @code{nil}. - - After exiting a search, you can search for the same string again by -typing just @kbd{C-s C-s}. The first @kbd{C-s} is the key that -invokes incremental search, and the second @kbd{C-s} means ``search -again''. Similarly, @kbd{C-r C-r} searches backward for the last -search string. In determining the last search string, it doesn't -matter whether the string was searched for with @kbd{C-s} or -@kbd{C-r}. - - If you are searching forward but you realize you were looking for -something before the starting point, type @kbd{C-r} to switch to a -backward search, leaving the search string unchanged. Similarly, -@kbd{C-s} in a backward search switches to a forward search. - - If a search is failing and you ask to repeat it by typing another -@kbd{C-s}, it starts again from the beginning of the buffer. -Repeating a failing reverse search with @kbd{C-r} starts again from -the end. This is called @dfn{wrapping around}, and @samp{Wrapped} -appears in the search prompt once this has happened. If you keep on -going past the original starting point of the search, it changes to -@samp{Overwrapped}, which means that you are revisiting matches that -you have already seen. - -@cindex search ring -@kindex M-n @r{(Incremental search)} -@kindex M-p @r{(Incremental search)} - To reuse earlier search strings, use the @dfn{search ring}. The -commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a -search string to reuse. These commands leave the selected search ring -element in the minibuffer, where you can edit it. - -@kindex M-e @r{(Incremental search)} - To edit the current search string in the minibuffer without -replacing it with items from the search ring, type @kbd{M-e}. Type -@kbd{C-s} or @kbd{C-r} to finish editing the string and search for it. - -@node Error in Isearch -@subsection Errors in Incremental Search - - If your string is not found at all, the echo area says @samp{Failing -I-Search}, and the cursor moves past the place where Emacs found as -much of your string as it could. Thus, if you search for @samp{FOOT}, -and there is no @samp{FOOT}, you might see the cursor after the -@samp{FOO} in @samp{FOOL}. In the echo area, the part of the search -string that failed to match is highlighted using the face -@code{isearch-fail}. - - At this point, there are several things you can do. If your string -was mistyped, you can use @key{DEL} to erase some of it and correct -it. If you like the place you have found, you can type @key{RET} to -remain there. Or you can type @kbd{C-g}, which removes from the -search string the characters that could not be found (the @samp{T} in -@samp{FOOT}), leaving those that were found (the @samp{FOO} in -@samp{FOOT}). A second @kbd{C-g} at that point cancels the search -entirely, returning point to where it was when the search started. - -@cindex quitting (in search) -@kindex C-g @r{(Incremental search)} - The quit command, @kbd{C-g}, does special things during searches; -just what it does depends on the status of the search. If the search -has found what you specified and is waiting for input, @kbd{C-g} -cancels the entire search, moving the cursor back to where you started -the search. If @kbd{C-g} is typed when there are characters in the -search string that have not been found---because Emacs is still -searching for them, or because it has failed to find them---then the -search string characters which have not been found are discarded from -the search string. With them gone, the search is now successful and -waiting for more input, so a second @kbd{C-g} will cancel the entire -search. - -@node Special Isearch -@subsection Special Input for Incremental Search - - Some of the characters you type during incremental search have -special effects. - - If the search string you entered contains only lower-case letters, -the search is case-insensitive; as long as an upper-case letter exists -in the search string, the search becomes case-sensitive. If you -delete the upper-case character from the search string, it ceases to -have this effect. @xref{Search Case}. - - To search for a newline character, type @kbd{C-j}. - - To search for other control characters, such as @key{control-S}, -quote it by typing @kbd{C-q} first (@pxref{Inserting Text}). To -search for non-@acronym{ASCII} characters, you can either use -@kbd{C-q} and enter its octal code, or use an input method -(@pxref{Input Methods}). If an input method is enabled in the current -buffer when you start the search, you can use it in the search string -also. While typing the search string, you can toggle the input method -with the command @kbd{C-\} (@code{isearch-toggle-input-method}). You -can also turn on a non-default input method with @kbd{C-^} -(@code{isearch-toggle-specified-input-method}), which prompts for the -name of the input method. When an input method is active during -incremental search, the search prompt includes the input method -mnemonic, like this: - -@example -I-search [@var{im}]: -@end example - -@noindent -@findex isearch-toggle-input-method -@findex isearch-toggle-specified-input-method -where @var{im} is the mnemonic of the active input method. Any input -method you enable during incremental search remains enabled in the -current buffer afterwards. - -@kindex M-% @r{(Incremental search)} - Typing @kbd{M-%} in incremental search invokes @code{query-replace} -or @code{query-replace-regexp} (depending on search mode) with the -current search string used as the string to replace. @xref{Query -Replace}. - -@kindex M-TAB @r{(Incremental search)} - Typing @kbd{M-@key{TAB}} in incremental search invokes -@code{isearch-complete}, which attempts to complete the search string -using the search ring as a list of completion alternatives. -@xref{Completion}. In many operating systems, the @kbd{M-@key{TAB}} -key sequence is captured by the window manager; you then need to -rebind @code{isearch-complete} to another key sequence if you want to -use it (@pxref{Rebinding}). - -@vindex isearch-mode-map - When incremental search is active, you can type @kbd{C-h C-h} to -access interactive help options, including a list of special key -bindings. These key bindings are part of the keymap -@code{isearch-mode-map} (@pxref{Keymaps}). - -@node Isearch Yank -@subsection Isearch Yanking - -@kindex C-y @r{(Incremental search)} -@kindex M-y @r{(Incremental search)} -@findex isearch-yank-kill -@findex isearch-yank-pop - Within incremental search, @kbd{C-y} (@code{isearch-yank-kill}) -appends the current kill to the search string. @kbd{M-y} -(@code{isearch-yank-pop}), if called after @kbd{C-y}, replaces that -appended text with an earlier kill, similar to the usual @kbd{M-y} -(@code{yank-pop}) command (@pxref{Yanking}). @kbd{Mouse-2} appends -the current X selection (@pxref{Primary Selection}). - -@kindex C-w @r{(Incremental search)} -@findex isearch-yank-word-or-char - @kbd{C-w} (@code{isearch-yank-word-or-char}) appends the next -character or word at point to the search string. This is an easy way -to search for another occurrence of the text at point. (The decision -of whether to copy a character or a word is heuristic.) - -@kindex M-s C-e @r{(Incremental search)} -@findex isearch-yank-line - Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) appends the rest -of the current line to the search string. If point is already at the -end of a line, it appends the next line. - - If the search is currently case-insensitive, both @kbd{C-w} and -@kbd{M-s C-e} convert the text they copy to lower case, so that the -search remains case-insensitive. - -@kindex C-M-w @r{(Incremental search)} -@kindex C-M-y @r{(Incremental search)} -@findex isearch-del-char -@findex isearch-yank-char - @kbd{C-M-w} (@code{isearch-del-char}) deletes the last character -from the search string, and @kbd{C-M-y} (@code{isearch-yank-char}) -appends the character after point to the search string. An -alternative method to add the character after point is to enter the -minibuffer with @kbd{M-e} (@pxref{Repeat Isearch}) and type @kbd{C-f} -at the end of the search string in the minibuffer. - -@node Isearch Scroll -@subsection Scrolling During Incremental Search - -@vindex isearch-allow-scroll - Normally, scrolling commands exit incremental search. If you change -the variable @code{isearch-allow-scroll} to a non-@code{nil} value, -that enables the use of the scroll-bar, as well as keyboard scrolling -commands like @kbd{C-v}, @kbd{M-v}, and @kbd{C-l} (@pxref{Scrolling}). -This applies only to calling these commands via their bound key -sequences---typing @kbd{M-x} will still exit the search. You can give -prefix arguments to these commands in the usual way. This feature -won't let you scroll the current match out of visibility, however. - - The @code{isearch-allow-scroll} feature also affects some other -commands, such as @kbd{C-x 2} (@code{split-window-below}) and @kbd{C-x -^} (@code{enlarge-window}), which don't exactly scroll but do affect -where the text appears on the screen. It applies to any command whose -name has a non-@code{nil} @code{isearch-scroll} property. So you can -control which commands are affected by changing these properties. - - For example, to make @kbd{C-h l} usable within an incremental search -in all future Emacs sessions, use @kbd{C-h c} to find what command it -runs (@pxref{Key Help}), which is @code{view-lossage}. Then you can -put the following line in your init file (@pxref{Init File}): - -@example -(put 'view-lossage 'isearch-scroll t) -@end example - -@noindent -This feature can be applied to any command that doesn't permanently -change point, the buffer contents, the match data, the current buffer, -or the selected window and frame. The command must not itself attempt -an incremental search. - -@node Isearch Minibuffer -@subsection Searching the Minibuffer -@cindex minibuffer history, searching - -If you start an incremental search while the minibuffer is active, -Emacs searches the contents of the minibuffer. Unlike searching an -ordinary buffer, the search string is not shown in the echo area, -because that is used to display the minibuffer. - -If an incremental search fails in the minibuffer, it tries searching -the minibuffer history. @xref{Minibuffer History}. You can visualize -the minibuffer and its history as a series of ``pages'', with the -earliest history element on the first page and the current minibuffer -on the last page. A forward search, @kbd{C-s}, searches forward to -later pages; a reverse search, @kbd{C-r}, searches backwards to -earlier pages. Like in ordinary buffer search, a failing search can -wrap around, going from the last page to the first page or vice versa. - -When the current match is on a history element, that history element -is pulled into the minibuffer. If you exit the incremental search -normally (e.g. by typing @key{RET}), it remains in the minibuffer -afterwards. Canceling the search, with @kbd{C-g}, restores the -contents of the minibuffer when you began the search. - -@node Nonincremental Search -@section Nonincremental Search -@cindex nonincremental search - - Emacs also has conventional nonincremental search commands, which require -you to type the entire search string before searching begins. - -@table @kbd -@item C-s @key{RET} @var{string} @key{RET} -Search for @var{string}. -@item C-r @key{RET} @var{string} @key{RET} -Search backward for @var{string}. -@end table - - To start a nonincremental search, first type @kbd{C-s @key{RET}}. -This enters the minibuffer to read the search string; terminate the -string with @key{RET}, and then the search takes place. If the string -is not found, the search command signals an error. - -@findex search-forward -@findex search-backward - When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental -search as usual. That command is specially programmed to invoke the -command for nonincremental search, @code{search-forward}, if the -string you specify is empty. (Such an empty argument would otherwise -be useless.) @kbd{C-r @key{RET}} does likewise, invoking the command -@code{search-backward}. - -@node Word Search -@section Word Search -@cindex word search - - A @dfn{word search} finds a sequence of words without regard to the -type of punctuation between them. For instance, if you enter a search -string that consists of two words separated by a single space, the -search matches any sequence of those two words separated by one or -more spaces, newlines, or other punctuation characters. This is -particularly useful for searching text documents, because you don't -have to worry whether the words you are looking for are separated by -newlines or spaces. - -@table @kbd -@item M-s w -If incremental search is active, toggle word search mode -(@code{isearch-toggle-word}); otherwise, begin an incremental forward -word search (@code{isearch-forward-word}). -@item M-s w @key{RET} @var{words} @key{RET} -Search for @var{words}, using a forward nonincremental word search. -@item M-s w C-r @key{RET} @var{words} @key{RET} -Search backward for @var{words}, using a nonincremental word search. -@end table - -@kindex M-s w -@findex isearch-forward-word - To begin a forward incremental word search, type @kbd{M-s w}. If -incremental search is not already active, this runs the command -@code{isearch-forward-word}. If incremental search is already active -(whether a forward or backward search), @kbd{M-s w} switches to a word -search while keeping the direction of the search and the current -search string unchanged. You can toggle word search back off by -typing @kbd{M-s w} again. - -@findex word-search-forward -@findex word-search-backward - To begin a nonincremental word search, type @kbd{M-s w @key{RET}} -for a forward search, or @kbd{M-s w C-r @key{RET}} for a backward search. -These run the commands @code{word-search-forward} and -@code{word-search-backward} respectively. - - Incremental and nonincremental word searches differ slightly in the -way they find a match. In a nonincremental word search, the last word -in the search string must exactly match a whole word. In an -incremental word search, the matching is more lax: the last word in -the search string can match part of a word, so that the matching -proceeds incrementally as you type. This additional laxity does not -apply to the lazy highlight, which always matches whole words. - -@node Regexp Search -@section Regular Expression Search -@cindex regexp search -@cindex search for a regular expression - - A @dfn{regular expression} (or @dfn{regexp} for short) is a pattern -that denotes a class of alternative strings to match. Emacs -provides both incremental and nonincremental ways to search for a -match for a regexp. The syntax of regular expressions is explained in -the next section. - -@table @kbd -@item C-M-s -Begin incremental regexp search (@code{isearch-forward-regexp}). -@item C-M-r -Begin reverse incremental regexp search (@code{isearch-backward-regexp}). -@end table - -@kindex C-M-s -@findex isearch-forward-regexp -@kindex C-M-r -@findex isearch-backward-regexp - Incremental search for a regexp is done by typing @kbd{C-M-s} -(@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a -prefix argument (whose value does not matter), or by typing @kbd{M-r} -within a forward incremental search. This command reads a -search string incrementally just like @kbd{C-s}, but it treats the -search string as a regexp rather than looking for an exact match -against the text in the buffer. Each time you add text to the search -string, you make the regexp longer, and the new regexp is searched -for. To search backward for a regexp, use @kbd{C-M-r} -(@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument, -or @kbd{M-r} within a backward incremental search. - - All of the special key sequences in an ordinary incremental search -do similar things in an incremental regexp search. For instance, -typing @kbd{C-s} immediately after starting the search retrieves the -last incremental search regexp used and searches forward for it. -Incremental regexp and non-regexp searches have independent defaults. -They also have separate search rings, which you can access with -@kbd{M-p} and @kbd{M-n}. - -@vindex search-whitespace-regexp - If you type @key{SPC} in incremental regexp search, it matches any -sequence of whitespace characters, including newlines. If you want to -match just a space, type @kbd{C-q @key{SPC}}. You can control what a -bare space matches by setting the variable -@code{search-whitespace-regexp} to the desired regexp. - - In some cases, adding characters to the regexp in an incremental -regexp search can make the cursor move back and start again. For -example, if you have searched for @samp{foo} and you add @samp{\|bar}, -the cursor backs up in case the first @samp{bar} precedes the first -@samp{foo}. @xref{Regexps}. - - Forward and backward regexp search are not symmetrical, because -regexp matching in Emacs always operates forward, starting with the -beginning of the regexp. Thus, forward regexp search scans forward, -trying a forward match at each possible starting position. Backward -regexp search scans backward, trying a forward match at each possible -starting position. These search methods are not mirror images. - -@findex re-search-forward -@findex re-search-backward - Nonincremental search for a regexp is done with the commands -@code{re-search-forward} and @code{re-search-backward}. You can -invoke these with @kbd{M-x}, or by way of incremental regexp search -with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}. - - If you use the incremental regexp search commands with a prefix -argument, they perform ordinary string search, like -@code{isearch-forward} and @code{isearch-backward}. @xref{Incremental -Search}. - -@node Regexps -@section Syntax of Regular Expressions -@cindex syntax of regexps -@cindex regular expression -@cindex regexp - - This manual describes regular expression features that users -typically use. @xref{Regular Expressions,,, elisp, The Emacs Lisp -Reference Manual}, for additional features used mainly in Lisp -programs. - - Regular expressions have a syntax in which a few characters are -special constructs and the rest are @dfn{ordinary}. An ordinary -character matches that same character and nothing else. The special -characters are @samp{$^.*+?[\}. The character @samp{]} is special if -it ends a character alternative (see later). The character @samp{-} -is special inside a character alternative. Any other character -appearing in a regular expression is ordinary, unless a @samp{\} -precedes it. (When you use regular expressions in a Lisp program, -each @samp{\} must be doubled, see the example near the end of this -section.) - - For example, @samp{f} is not a special character, so it is ordinary, and -therefore @samp{f} is a regular expression that matches the string -@samp{f} and no other string. (It does @emph{not} match the string -@samp{ff}.) Likewise, @samp{o} is a regular expression that matches -only @samp{o}. (When case distinctions are being ignored, these regexps -also match @samp{F} and @samp{O}, but we consider this a generalization -of ``the same string'', rather than an exception.) - - Any two regular expressions @var{a} and @var{b} can be concatenated. -The result is a regular expression which matches a string if @var{a} -matches some amount of the beginning of that string and @var{b} -matches the rest of the string. For example, concatenating the -regular expressions @samp{f} and @samp{o} gives the regular expression -@samp{fo}, which matches only the string @samp{fo}. Still trivial. -To do something nontrivial, you need to use one of the special -characters. Here is a list of them. - -@table @asis -@item @kbd{.}@: @r{(Period)} -is a special character that matches any single character except a -newline. For example, the regular expressions @samp{a.b} matches any -three-character string that begins with @samp{a} and ends with -@samp{b}. - -@item @kbd{*} -is not a construct by itself; it is a postfix operator that means to -match the preceding regular expression repetitively any number of -times, as many times as possible. Thus, @samp{o*} matches any number -of @samp{o}s, including no @samp{o}s. - -@samp{*} always applies to the @emph{smallest} possible preceding -expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating -@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. - -The matcher processes a @samp{*} construct by matching, immediately, -as many repetitions as can be found. Then it continues with the rest -of the pattern. If that fails, backtracking occurs, discarding some -of the matches of the @samp{*}-modified construct in case that makes -it possible to match the rest of the pattern. For example, in matching -@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first -tries to match all three @samp{a}s; but the rest of the pattern is -@samp{ar} and there is only @samp{r} left to match, so this try fails. -The next alternative is for @samp{a*} to match only two @samp{a}s. -With this choice, the rest of the regexp matches successfully.@refill - -@item @kbd{+} -is a postfix operator, similar to @samp{*} except that it must match -the preceding expression at least once. Thus, @samp{ca+r} matches the -strings @samp{car} and @samp{caaaar} but not the string @samp{cr}, -whereas @samp{ca*r} matches all three strings. - -@item @kbd{?} -is a postfix operator, similar to @samp{*} except that it can match -the preceding expression either once or not at all. Thus, @samp{ca?r} -matches @samp{car} or @samp{cr}, and nothing else. - -@item @kbd{*?}, @kbd{+?}, @kbd{??} -@cindex non-greedy regexp matching -are non-@dfn{greedy} variants of the operators above. The normal -operators @samp{*}, @samp{+}, @samp{?} match as much as they can, as -long as the overall regexp can still match. With a following -@samp{?}, they will match as little as possible. - -Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a} -and the string @samp{abbbb}; but if you try to match them both against -the text @samp{abbb}, @samp{ab*} will match it all (the longest valid -match), while @samp{ab*?} will match just @samp{a} (the shortest -valid match). - -Non-greedy operators match the shortest possible string starting at a -given starting point; in a forward search, though, the earliest -possible starting point for match is always the one chosen. Thus, if -you search for @samp{a.*?$} against the text @samp{abbab} followed by -a newline, it matches the whole string. Since it @emph{can} match -starting at the first @samp{a}, it does. - -@item @kbd{\@{@var{n}\@}} -is a postfix operator specifying @var{n} repetitions---that is, the -preceding regular expression must match exactly @var{n} times in a -row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and -nothing else. - -@item @kbd{\@{@var{n},@var{m}\@}} -is a postfix operator specifying between @var{n} and @var{m} -repetitions---that is, the preceding regular expression must match at -least @var{n} times, but no more than @var{m} times. If @var{m} is -omitted, then there is no upper limit, but the preceding regular -expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is -equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to -@samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}. - -@item @kbd{[ @dots{} ]} -is a @dfn{character set}, beginning with @samp{[} and terminated by -@samp{]}. - -In the simplest case, the characters between the two brackets are what -this set can match. Thus, @samp{[ad]} matches either one @samp{a} or -one @samp{d}, and @samp{[ad]*} matches any string composed of just -@samp{a}s and @samp{d}s (including the empty string). It follows that -@samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr}, -@samp{caddaar}, etc. - -You can also include character ranges in a character set, by writing the -starting and ending characters with a @samp{-} between them. Thus, -@samp{[a-z]} matches any lower-case @acronym{ASCII} letter. Ranges may be -intermixed freely with individual characters, as in @samp{[a-z$%.]}, -which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or -period. - -You can also include certain special @dfn{character classes} in a -character set. A @samp{[:} and balancing @samp{:]} enclose a -character class inside a character alternative. For instance, -@samp{[[:alnum:]]} matches any letter or digit. @xref{Char Classes,,, -elisp, The Emacs Lisp Reference Manual}, for a list of character -classes. - -To include a @samp{]} in a character set, you must make it the first -character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To -include a @samp{-}, write @samp{-} as the first or last character of the -set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]} -and @samp{-}. - -To include @samp{^} in a set, put it anywhere but at the beginning of -the set. (At the beginning, it complements the set---see below.) - -When you use a range in case-insensitive search, you should write both -ends of the range in upper case, or both in lower case, or both should -be non-letters. The behavior of a mixed-case range such as @samp{A-z} -is somewhat ill-defined, and it may change in future Emacs versions. - -@item @kbd{[^ @dots{} ]} -@samp{[^} begins a @dfn{complemented character set}, which matches any -character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches -all characters @emph{except} @acronym{ASCII} letters and digits. - -@samp{^} is not special in a character set unless it is the first -character. The character following the @samp{^} is treated as if it -were first (in other words, @samp{-} and @samp{]} are not special there). - -A complemented character set can match a newline, unless newline is -mentioned as one of the characters not to match. This is in contrast to -the handling of regexps in programs such as @code{grep}. - -@item @kbd{^} -is a special character that matches the empty string, but only at the -beginning of a line in the text being matched. Otherwise it fails to -match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at -the beginning of a line. - -For historical compatibility reasons, @samp{^} can be used with this -meaning only at the beginning of the regular expression, or after -@samp{\(} or @samp{\|}. - -@item @kbd{$} -is similar to @samp{^} but matches only at the end of a line. Thus, -@samp{x+$} matches a string of one @samp{x} or more at the end of a line. - -For historical compatibility reasons, @samp{$} can be used with this -meaning only at the end of the regular expression, or before @samp{\)} -or @samp{\|}. - -@item @kbd{\} -has two functions: it quotes the special characters (including -@samp{\}), and it introduces additional special constructs. - -Because @samp{\} quotes special characters, @samp{\$} is a regular -expression that matches only @samp{$}, and @samp{\[} is a regular -expression that matches only @samp{[}, and so on. - -See the following section for the special constructs that begin -with @samp{\}. -@end table - - Note: for historical compatibility, special characters are treated as -ordinary ones if they are in contexts where their special meanings make no -sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is -no preceding expression on which the @samp{*} can act. It is poor practice -to depend on this behavior; it is better to quote the special character anyway, -regardless of where it appears. - -As a @samp{\} is not special inside a character alternative, it can -never remove the special meaning of @samp{-} or @samp{]}. So you -should not quote these characters when they have no special meaning -either. This would not clarify anything, since backslashes can -legitimately precede these characters where they @emph{have} special -meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), -which matches any single character except a backslash. - -@node Regexp Backslash -@section Backslash in Regular Expressions - - For the most part, @samp{\} followed by any character matches only -that character. However, there are several exceptions: two-character -sequences starting with @samp{\} that have special meanings. The -second character in the sequence is always an ordinary character when -used on its own. Here is a table of @samp{\} constructs. - -@table @kbd -@item \| -specifies an alternative. Two regular expressions @var{a} and @var{b} -with @samp{\|} in between form an expression that matches some text if -either @var{a} matches it or @var{b} matches it. It works by trying to -match @var{a}, and if that fails, by trying to match @var{b}. - -Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string.@refill - -@samp{\|} applies to the largest possible surrounding expressions. Only a -surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}.@refill - -Full backtracking capability exists to handle multiple uses of @samp{\|}. - -@item \( @dots{} \) -is a grouping construct that serves three purposes: - -@enumerate -@item -To enclose a set of @samp{\|} alternatives for other operations. -Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}. - -@item -To enclose a complicated expression for the postfix operators @samp{*}, -@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches -@samp{bananana}, etc., with any (zero or more) number of @samp{na} -strings.@refill - -@item -To record a matched substring for future reference. -@end enumerate - -This last application is not a consequence of the idea of a -parenthetical grouping; it is a separate feature that is assigned as a -second meaning to the same @samp{\( @dots{} \)} construct. In practice -there is usually no conflict between the two meanings; when there is -a conflict, you can use a ``shy'' group. - -@item \(?: @dots{} \) -@cindex shy group, in regexp -specifies a ``shy'' group that does not record the matched substring; -you can't refer back to it with @samp{\@var{d}}. This is useful -in mechanically combining regular expressions, so that you -can add groups for syntactic purposes without interfering with -the numbering of the groups that are meant to be referred to. - -@item \@var{d} -@cindex back reference, in regexp -matches the same text that matched the @var{d}th occurrence of a -@samp{\( @dots{} \)} construct. This is called a @dfn{back -reference}. - -After the end of a @samp{\( @dots{} \)} construct, the matcher remembers -the beginning and end of the text matched by that construct. Then, -later on in the regular expression, you can use @samp{\} followed by the -digit @var{d} to mean ``match the same text matched the @var{d}th time -by the @samp{\( @dots{} \)} construct''. - -The strings matching the first nine @samp{\( @dots{} \)} constructs -appearing in a regular expression are assigned numbers 1 through 9 in -the order that the open-parentheses appear in the regular expression. -So you can use @samp{\1} through @samp{\9} to refer to the text matched -by the corresponding @samp{\( @dots{} \)} constructs. - -For example, @samp{\(.*\)\1} matches any newline-free string that is -composed of two identical halves. The @samp{\(.*\)} matches the first -half, which may be anything, but the @samp{\1} that follows must match -the same exact text. - -If a particular @samp{\( @dots{} \)} construct matches more than once -(which can easily happen if it is followed by @samp{*}), only the last -match is recorded. - -@item \` -matches the empty string, but only at the beginning of the string or -buffer (or its accessible portion) being matched against. - -@item \' -matches the empty string, but only at the end of the string or buffer -(or its accessible portion) being matched against. - -@item \= -matches the empty string, but only at point. - -@item \b -matches the empty string, but only at the beginning or -end of a word. Thus, @samp{\bfoo\b} matches any occurrence of -@samp{foo} as a separate word. @samp{\bballs?\b} matches -@samp{ball} or @samp{balls} as a separate word.@refill - -@samp{\b} matches at the beginning or end of the buffer -regardless of what text appears next to it. - -@item \B -matches the empty string, but @emph{not} at the beginning or -end of a word. - -@item \< -matches the empty string, but only at the beginning of a word. -@samp{\<} matches at the beginning of the buffer only if a -word-constituent character follows. - -@item \> -matches the empty string, but only at the end of a word. @samp{\>} -matches at the end of the buffer only if the contents end with a -word-constituent character. - -@item \w -matches any word-constituent character. The syntax table determines -which characters these are. @xref{Syntax Tables,, Syntax Tables, -elisp, The Emacs Lisp Reference Manual}. - -@item \W -matches any character that is not a word-constituent. - -@item \_< -matches the empty string, but only at the beginning of a symbol. -A symbol is a sequence of one or more symbol-constituent characters. -A symbol-constituent character is a character whose syntax is either -@samp{w} or @samp{_}. @samp{\_<} matches at the beginning of the -buffer only if a symbol-constituent character follows. - -@item \_> -matches the empty string, but only at the end of a symbol. @samp{\_>} -matches at the end of the buffer only if the contents end with a -symbol-constituent character. - -@item \s@var{c} -matches any character whose syntax is @var{c}. Here @var{c} is a -character that designates a particular syntax class: thus, @samp{w} -for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.} -for ordinary punctuation, etc. @xref{Syntax Tables,, Syntax Tables, -elisp, The Emacs Lisp Reference Manual}. - -@item \S@var{c} -matches any character whose syntax is not @var{c}. - -@cindex categories of characters -@cindex characters which belong to a specific language -@findex describe-categories -@item \c@var{c} -matches any character that belongs to the category @var{c}. For -example, @samp{\cc} matches Chinese characters, @samp{\cg} matches -Greek characters, etc. For the description of the known categories, -type @kbd{M-x describe-categories @key{RET}}. - -@item \C@var{c} -matches any character that does @emph{not} belong to category -@var{c}. -@end table - - The constructs that pertain to words and syntax are controlled by -the setting of the syntax table. @xref{Syntax Tables,, Syntax Tables, -elisp, The Emacs Lisp Reference Manual}. - -@node Regexp Example -@section Regular Expression Example - - Here is an example of a regexp---similar to the regexp that Emacs -uses, by default, to recognize the end of a sentence, not including -the following space (i.e., the variable @code{sentence-end-base}): - -@example -@verbatim -[.?!][]\"')}]* -@end verbatim -@end example - -@noindent -This contains two parts in succession: a character set matching -period, @samp{?}, or @samp{!}, and a character set matching -close-brackets, quotes, or parentheses, repeated zero or more times. - -@node Search Case -@section Searching and Case - - Searches in Emacs normally ignore the case of the text they are -searching through, if you specify the text in lower case. Thus, if -you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo} -also match. Regexps, and in particular character sets, behave -likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b} or -@samp{B}.@refill - - An upper-case letter anywhere in the incremental search string makes -the search case-sensitive. Thus, searching for @samp{Foo} does not find -@samp{foo} or @samp{FOO}. This applies to regular expression search as -well as to string search. The effect ceases if you delete the -upper-case letter from the search string. - - Typing @kbd{M-c} within an incremental search toggles the case -sensitivity of that search. The effect does not extend beyond the -current incremental search to the next one, but it does override the -effect of adding or removing an upper-case letter in the current -search. - -@vindex case-fold-search - If you set the variable @code{case-fold-search} to @code{nil}, then -all letters must match exactly, including case. This is a per-buffer -variable; altering the variable normally affects only the current buffer, -unless you change its default value. @xref{Locals}. -This variable applies to nonincremental searches also, including those -performed by the replace commands (@pxref{Replace}) and the minibuffer -history matching commands (@pxref{Minibuffer History}). - - Several related variables control case-sensitivity of searching and -matching for specific commands or activities. For instance, -@code{tags-case-fold-search} controls case sensitivity for -@code{find-tag}. To find these variables, do @kbd{M-x -apropos-variable @key{RET} case-fold-search @key{RET}}. - -@node Replace -@section Replacement Commands -@cindex replacement -@cindex search-and-replace commands -@cindex string substitution -@cindex global substitution - - Emacs provides several commands for performing search-and-replace -operations. In addition to the simple @kbd{M-x replace-string} -command, there is @kbd{M-%} (@code{query-replace}), which presents -each occurrence of the pattern and asks you whether to replace it. - - The replace commands normally operate on the text from point to the -end of the buffer. When the region is active, they operate on it -instead (@pxref{Mark}). The basic replace commands replace one -@dfn{search string} (or regexp) with one @dfn{replacement string}. It -is possible to perform several replacements in parallel, using the -command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}). - -@menu -* Unconditional Replace:: Replacing all matches for a string. -* Regexp Replace:: Replacing all matches for a regexp. -* Replacement and Case:: How replacements preserve case of letters. -* Query Replace:: How to use querying. -@end menu - -@node Unconditional Replace, Regexp Replace, Replace, Replace -@subsection Unconditional Replacement -@findex replace-string - -@table @kbd -@item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} -Replace every occurrence of @var{string} with @var{newstring}. -@end table - - To replace every instance of @samp{foo} after point with @samp{bar}, -use the command @kbd{M-x replace-string} with the two arguments -@samp{foo} and @samp{bar}. Replacement happens only in the text after -point, so if you want to cover the whole buffer you must go to the -beginning first. All occurrences up to the end of the buffer are -replaced; to limit replacement to part of the buffer, activate the -region around that part. When the region is active, replacement is -limited to the region (@pxref{Mark}). - - When @code{replace-string} exits, it leaves point at the last -occurrence replaced. It adds the prior position of point (where the -@code{replace-string} command was issued) to the mark ring, without -activating the mark; use @kbd{C-u C-@key{SPC}} to move back there. -@xref{Mark Ring}. - - A prefix argument restricts replacement to matches that are -surrounded by word boundaries. - - @xref{Replacement and Case}, for details about case-sensitivity in -replace commands. - -@node Regexp Replace, Replacement and Case, Unconditional Replace, Replace -@subsection Regexp Replacement -@findex replace-regexp - - The @kbd{M-x replace-string} command replaces exact matches for a -single string. The similar command @kbd{M-x replace-regexp} replaces -any match for a specified pattern. - -@table @kbd -@item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} -Replace every match for @var{regexp} with @var{newstring}. -@end table - -@cindex back reference, in regexp replacement - In @code{replace-regexp}, the @var{newstring} need not be constant: -it can refer to all or part of what is matched by the @var{regexp}. -@samp{\&} in @var{newstring} stands for the entire match being -replaced. @samp{\@var{d}} in @var{newstring}, where @var{d} is a -digit, stands for whatever matched the @var{d}th parenthesized -grouping in @var{regexp}. (This is called a ``back reference''.) -@samp{\#} refers to the count of replacements already made in this -command, as a decimal number. In the first replacement, @samp{\#} -stands for @samp{0}; in the second, for @samp{1}; and so on. For -example, - -@example -M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET} -@end example - -@noindent -replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr} -with @samp{cddr-safe}. - -@example -M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET} -@end example - -@noindent -performs the inverse transformation. To include a @samp{\} in the -text to replace with, you must enter @samp{\\}. - - If you want to enter part of the replacement string by hand each -time, use @samp{\?} in the replacement string. Each replacement will -ask you to edit the replacement string in the minibuffer, putting -point where the @samp{\?} was. - - The remainder of this subsection is intended for specialized tasks -and requires knowledge of Lisp. Most readers can skip it. - - You can use Lisp expressions to calculate parts of the -replacement string. To do this, write @samp{\,} followed by the -expression in the replacement string. Each replacement calculates the -value of the expression and converts it to text without quoting (if -it's a string, this means using the string's contents), and uses it in -the replacement string in place of the expression itself. If the -expression is a symbol, one space in the replacement string after the -symbol name goes with the symbol name, so the value replaces them -both. - - Inside such an expression, you can use some special sequences. -@samp{\&} and @samp{\@var{n}} refer here, as usual, to the entire -match as a string, and to a submatch as a string. @var{n} may be -multiple digits, and the value of @samp{\@var{n}} is @code{nil} if -subexpression @var{n} did not match. You can also use @samp{\#&} and -@samp{\#@var{n}} to refer to those matches as numbers (this is valid -when the match or submatch has the form of a numeral). @samp{\#} here -too stands for the number of already-completed replacements. - - Repeating our example to exchange @samp{x} and @samp{y}, we can thus -do it also this way: - -@example -M-x replace-regexp @key{RET} \(x\)\|y @key{RET} -\,(if \1 "y" "x") @key{RET} -@end example - - For computing replacement strings for @samp{\,}, the @code{format} -function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs -Lisp Reference Manual}). For example, to add consecutively numbered -strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are -already occupied), you can use - -@example -M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET} -\,(format "%-72sABC%05d" \& \#) @key{RET} -@end example - -@node Replacement and Case, Query Replace, Regexp Replace, Replace -@subsection Replace Commands and Case - - If the first argument of a replace command is all lower case, the -command ignores case while searching for occurrences to -replace---provided @code{case-fold-search} is non-@code{nil}. If -@code{case-fold-search} is set to @code{nil}, case is always significant -in all searches. - -@vindex case-replace - In addition, when the @var{newstring} argument is all or partly lower -case, replacement commands try to preserve the case pattern of each -occurrence. Thus, the command - -@example -M-x replace-string @key{RET} foo @key{RET} bar @key{RET} -@end example - -@noindent -replaces a lower case @samp{foo} with a lower case @samp{bar}, an -all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with -@samp{Bar}. (These three alternatives---lower case, all caps, and -capitalized, are the only ones that @code{replace-string} can -distinguish.) - - If upper-case letters are used in the replacement string, they remain -upper case every time that text is inserted. If upper-case letters are -used in the first argument, the second argument is always substituted -exactly as given, with no case conversion. Likewise, if either -@code{case-replace} or @code{case-fold-search} is set to @code{nil}, -replacement is done without case conversion. - -@node Query Replace,, Replacement and Case, Replace -@subsection Query Replace -@cindex query replace - -@table @kbd -@item M-% @var{string} @key{RET} @var{newstring} @key{RET} -Replace some occurrences of @var{string} with @var{newstring}. -@item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET} -Replace some matches for @var{regexp} with @var{newstring}. -@end table - -@kindex M-% -@findex query-replace - If you want to change only some of the occurrences of @samp{foo} to -@samp{bar}, not all of them, use @kbd{M-%} (@code{query-replace}). -This command finds occurrences of @samp{foo} one by one, displays each -occurrence and asks you whether to replace it. Aside from querying, -@code{query-replace} works just like @code{replace-string} -(@pxref{Unconditional Replace}). In particular, it preserves case -provided @code{case-replace} is non-@code{nil}, as it normally is -(@pxref{Replacement and Case}). A numeric argument means to consider -only occurrences that are bounded by word-delimiter characters. - -@kindex C-M-% -@findex query-replace-regexp - @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}). -It works like @code{replace-regexp} except that it queries -like @code{query-replace}. - -@cindex faces for highlighting query replace - These commands highlight the current match using the face -@code{query-replace}. They highlight other matches using -@code{lazy-highlight} just like incremental search (@pxref{Incremental -Search}). By default, @code{query-replace-regexp} will show the -substituted replacement string for the current match in the -minibuffer. If you want to keep special sequences @samp{\&} and -@samp{\@var{n}} unexpanded, customize -@code{query-replace-show-replacement} variable. - - The characters you can type when you are shown a match for the string -or regexp are: - -@ignore @c Not worth it. -@kindex SPC @r{(query-replace)} -@kindex DEL @r{(query-replace)} -@kindex , @r{(query-replace)} -@kindex RET @r{(query-replace)} -@kindex . @r{(query-replace)} -@kindex ! @r{(query-replace)} -@kindex ^ @r{(query-replace)} -@kindex C-r @r{(query-replace)} -@kindex C-w @r{(query-replace)} -@kindex C-l @r{(query-replace)} -@end ignore - -@c WideCommands -@table @kbd -@item @key{SPC} -to replace the occurrence with @var{newstring}. - -@item @key{DEL} -to skip to the next occurrence without replacing this one. - -@item , @r{(Comma)} -to replace this occurrence and display the result. You are then asked -for another input character to say what to do next. Since the -replacement has already been made, @key{DEL} and @key{SPC} are -equivalent in this situation; both move to the next occurrence. - -You can type @kbd{C-r} at this point (see below) to alter the replaced -text. You can also type @kbd{C-x u} to undo the replacement; this exits -the @code{query-replace}, so if you want to do further replacement you -must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart -(@pxref{Repetition}). - -@item @key{RET} -to exit without doing any more replacements. - -@item .@: @r{(Period)} -to replace this occurrence and then exit without searching for more -occurrences. - -@item ! -to replace all remaining occurrences without asking again. - -@item ^ -to go back to the position of the previous occurrence (or what used to -be an occurrence), in case you changed it by mistake or want to -reexamine it. - -@item C-r -to enter a recursive editing level, in case the occurrence needs to be -edited rather than just replaced with @var{newstring}. When you are -done, exit the recursive editing level with @kbd{C-M-c} to proceed to -the next occurrence. @xref{Recursive Edit}. - -@item C-w -to delete the occurrence, and then enter a recursive editing level as in -@kbd{C-r}. Use the recursive edit to insert text to replace the deleted -occurrence of @var{string}. When done, exit the recursive editing level -with @kbd{C-M-c} to proceed to the next occurrence. - -@item e -to edit the replacement string in the minibuffer. When you exit the -minibuffer by typing @key{RET}, the minibuffer contents replace the -current occurrence of the pattern. They also become the new -replacement string for any further occurrences. - -@item C-l -to redisplay the screen. Then you must type another character to -specify what to do with this occurrence. - -@item C-h -to display a message summarizing these options. Then you must type -another character to specify what to do with this occurrence. -@end table - - Some other characters are aliases for the ones listed above: @kbd{y}, -@kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and -@key{RET}. - - Aside from this, any other character exits the @code{query-replace}, -and is then reread as part of a key sequence. Thus, if you type -@kbd{C-k}, it exits the @code{query-replace} and then kills to end of -line. - - To restart a @code{query-replace} once it is exited, use @kbd{C-x -@key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it -used the minibuffer to read its arguments. @xref{Repetition, C-x ESC -ESC}. - - @xref{Operating on Files}, for the Dired @kbd{Q} command which -performs query replace on selected files. See also @ref{Transforming -File Names}, for Dired commands to rename, copy, or link files by -replacing regexp matches in file names. - -@node Other Repeating Search -@section Other Search-and-Loop Commands - - Here are some other commands that find matches for a regular -expression. They all ignore case in matching, if the pattern contains -no upper-case letters and @code{case-fold-search} is non-@code{nil}. -Aside from @code{occur} and its variants, all operate on the text from -point to the end of the buffer, or on the region if it is active. - -@findex list-matching-lines -@findex occur -@findex multi-occur -@findex multi-occur-in-matching-buffers -@findex how-many -@findex flush-lines -@findex keep-lines - -@table @kbd -@item M-x multi-isearch-buffers -Prompt for one or more buffer names, ending with @key{RET}; then, -begin a multi-buffer incremental search in those buffers. (If the -search fails in one buffer, the next @kbd{C-s} tries searching the -next specified buffer, and so forth.) With a prefix argument, prompt -for a regexp and begin a multi-buffer incremental search in buffers -matching that regexp. - -@item M-x multi-isearch-buffers-regexp -This command is just like @code{multi-isearch-buffers}, except it -performs an incremental regexp search. - -@cindex Occur mode -@cindex mode, Occur -@item M-x occur -Prompt for a regexp, and display a list showing each line in the -buffer that contains a match for it. To limit the search to part of -the buffer, narrow to that part (@pxref{Narrowing}). A numeric -argument @var{n} specifies that @var{n} lines of context are to be -displayed before and after each matching line. - -@kindex RET @r{(Occur mode)} -@kindex o @r{(Occur mode)} -@kindex C-o @r{(Occur mode)} -In the @file{*Occur*} buffer, you can click on each entry, or move -point there and type @key{RET}, to visit the corresponding position in -the buffer that was searched. @kbd{o} and @kbd{C-o} display the match -in another window; @kbd{C-o} does not select it. Alternatively, you -can use the @kbd{C-x `} (@code{next-error}) command to visit the -occurrences one by one (@pxref{Compilation Mode}). - -@cindex Occur Edit mode -@cindex mode, Occur Edit -Typing @kbd{e} in the @file{*Occur*} buffer switches to Occur Edit -mode, in which edits made to the entries are also applied to the text -in the originating buffer. Type @kbd{C-c C-c} to return to Occur -mode. - -The command @kbd{M-x list-matching-lines} is a synonym for @kbd{M-x -occur}. - -@kindex M-s o -@item M-s o -Run @code{occur} using the search string of the last incremental -string search. You can also run @kbd{M-s o} when an incremental -search is active; this uses the current search string. - -@item M-x multi-occur -This command is just like @code{occur}, except it is able to search -through multiple buffers. It asks you to specify the buffer names one -by one. - -@item M-x multi-occur-in-matching-buffers -This command is similar to @code{multi-occur}, except the buffers to -search are specified by a regular expression that matches visited file -names. With a prefix argument, it uses the regular expression to -match buffer names instead. - -@item M-x how-many -Prompt for a regexp, and print the number of matches for it in the -buffer after point. If the region is active, this operates on the -region instead. - -@item M-x flush-lines -Prompt for a regexp, and delete each line that contains a match for -it, operating on the text after point. This command deletes the -current line if it contains a match starting after point. If the -region is active, it operates on the region instead; if a line -partially contained in the region contains a match entirely contained -in the region, it is deleted. - -If a match is split across lines, @code{flush-lines} deletes all those -lines. It deletes the lines before starting to look for the next -match; hence, it ignores a match starting on the same line at which -another match ended. - -@item M-x keep-lines -Prompt for a regexp, and delete each line that @emph{does not} contain -a match for it, operating on the text after point. If point is not at -the beginning of a line, this command always keeps the current line. -If the region is active, the command operates on the region instead; -it never deletes lines that are only partially contained in the region -(a newline that ends a line counts as part of that line). - -If a match is split across lines, this command keeps all those lines. -@end table diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi deleted file mode 100644 index bf2b41cdbe0..00000000000 --- a/doc/emacs/sending.texi +++ /dev/null @@ -1,691 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Sending Mail -@chapter Sending Mail -@cindex sending mail -@cindex mail -@cindex email -@cindex message - -@kindex C-x m -@findex compose-mail - To send an email message from Emacs, type @kbd{C-x m}. This -switches to a buffer named @file{*unsent mail*}, where you can edit -the text and headers of the message. When done, type @kbd{C-c C-s} or -@kbd{C-c C-c} to send it. - -@table @kbd -@item C-x m -Begin composing mail (@code{compose-mail}). -@item C-x 4 m -Likewise, in another window (@code{compose-mail-other-window}). -@item C-x 5 m -Likewise, but in a new frame (@code{compose-mail-other-frame}). -@item C-c C-s -In the mail buffer, send the message (@code{message-send}). -@item C-c C-c -In the mail buffer, send the message and bury the buffer -(@code{message-send-and-exit}). -@end table - - The mail buffer is an ordinary Emacs buffer, so you can switch to -other buffers while composing the mail. If you want to send another -mail before finishing the current one, type @kbd{C-x m} again to open -a new mail buffer whose name has a different numeric suffix -(@pxref{Misc Buffer}). If you invoke the command with a prefix -argument, @w{@kbd{C-u C-x m}}, Emacs switches back to the last mail -buffer, and asks if you want to erase the message in that buffer; if -you answer no, this lets you pick up editing the message where you -left off. - -@kindex C-x 4 m -@findex compose-mail-other-window -@kindex C-x 5 m -@findex compose-mail-other-frame - The command @kbd{C-x 4 m} (@code{compose-mail-other-window}) does -the same as @kbd{C-x m}, except it displays the mail buffer in a -different window. The command @kbd{C-x 5 m} -(@code{compose-mail-other-frame}) does it in a new frame. - - When you type @kbd{C-c C-c} or @kbd{C-c C-s} to send the mail, Emacs -may ask you how it should deliver the mail---either directly via SMTP, -or using some other method. @xref{Mail Sending}, for details. - -@menu -* Format: Mail Format. Format of a mail message. -* Headers: Mail Headers. Details of some standard mail header fields. -* Aliases: Mail Aliases. Abbreviating and grouping mail addresses. -* Commands: Mail Commands. Special commands for editing mail being composed. -* Signature: Mail Signature. Adding a signature to every message. -* Amuse: Mail Amusements. Distracting the NSA; adding fortune messages. -* Methods: Mail Methods. Using alternative mail-composition methods. -@end menu - -@node Mail Format -@section The Format of the Mail Buffer - - Here is an example of the contents of a mail buffer: - -@example -To: subotai@@example.org -CC: mongol.soldier@@example.net, rms@@gnu.org -Subject: Re: What is best in life? -From: conan@@example.org ---text follows this line-- -To crush your enemies, see them driven before you, and to hear the -lamentation of their women. -@end example - -@noindent -At the top of the mail buffer is a set of @dfn{header fields}, which -are used for specifying information about the email's recipient(s), -subject, and so on. The above buffer contains header fields for -@samp{To}, @samp{Cc}, @samp{Subject}, and @samp{From}. Some header -fields are automatically pre-initialized in the mail buffer, when -appropriate. - - The line that says @samp{--text follows this line--} separates the -header fields from the @dfn{body} (or @dfn{text}) of the message. -Everything above that line is treated as part of the headers; -everything below it is treated as the body. The delimiter line itself -does not appear in the message actually sent. - - You can insert and edit header fields using ordinary editing -commands. @xref{Header Editing}, for commands specific to editing -header fields. Certain headers, such as @samp{Date} and -@samp{Message-Id}, are normally omitted from the mail buffer and are -created automatically when the message is sent. - -@node Mail Headers -@section Mail Header Fields -@cindex headers (of mail message) - - A header field in the mail buffer starts with a field name at the -beginning of a line, terminated by a colon. Upper and lower case are -equivalent in field names. After the colon and optional whitespace -comes the contents of the field. - - You can use any name you like for a header field, but normally -people use only standard field names with accepted meanings. - -@vindex user-full-name -@vindex user-mail-address - The @samp{From} header field identifies the person sending the email -(i.e.@: you). This should be a valid mailing address, as replies are -normally sent there. The default contents of this header field are -computed from the variables @code{user-full-name} (which specifies -your full name) and @code{user-mail-address} (your email address). On -some operating systems, Emacs initializes these two variables using -environment variables (@pxref{General Variables}). If this -information is unavailable or wrong, you should customize the -variables yourself (@pxref{Easy Customization}). - -@vindex mail-from-style - The value of the variable @code{mail-from-style} specifies how to -format the contents of the @samp{From} field: - -@table @asis -@item @code{nil} -Use just the address, as in @samp{king@@grassland.com}. -@item @code{parens} -Use both address and full name, as in:@* -@samp{king@@grassland.com (Elvis Parsley)}. -@item @code{angles} -Use both address and full name, as in:@* -@samp{Elvis Parsley }. -@item any other value -Use @code{angles} normally. But if the address must be ``quoted'' to -remain syntactically valid under the @code{angles} format but not -under the @code{parens} format, use @code{parens} instead. This is -the default. -@end table - - Apart from @samp{From}, here is a table of commonly-used fields: - -@table @samp -@item To -The mailing address(es) to which the message is addressed. To list -more than one address, use commas to separate them. - -@item Subject -The subject of the message. - -@item CC -Additional mailing address(es) to send the message to. This is like -@samp{To}, except that these readers should not regard the message as -directed at them. - -@item BCC -Additional mailing address(es) to send the message to, which should -not appear in the header of the message actually sent. ``BCC'' stands -for @dfn{blind carbon copies}. - -@item FCC -The name of a file, to which a copy of the sent message should be -appended. Emacs writes the message in mbox format, unless the file is -in Babyl format (used by Rmail before Emacs 23), in which case Emacs -writes in Babyl format. If an Rmail buffer is visiting the file, -Emacs updates it accordingly. To specify more than one file, use -several @samp{FCC} fields, with one file name in each field. - -@item Reply-to -An address to which replies should be sent, instead of @samp{From}. -This is used if, for some reason, your @samp{From} address cannot -receive replies. - -@item Mail-reply-to -This field takes precedence over @samp{Reply-to}. It is used because -some mailing lists set the @samp{Reply-to} field for their own -purposes (a somewhat controversial practice). - -@item Mail-followup-to -One of more address(es) to use as default recipient(s) for follow-up -messages. This is typically used when you reply to a message from a -mailing list that you are subscribed to, and want replies to go to the -list without sending an extra copy to you. - -@item In-reply-to -An identifier for the message you are replying to. Most mail readers -use this information to group related messages together. Normally, -this header is filled in automatically when you reply to a message in -any mail program built into Emacs. - -@item References -Identifiers for previous related messages. Like @samp{In-reply-to}, -this is normally filled in automatically for you. -@end table - -@noindent -The @samp{To}, @samp{CC}, and @samp{BCC} fields can appear any number -of times, and each such header field can contain multiple addresses, -separated by commas. This way, you can specify any number of places -to send the message. These fields can also have continuation lines: -one or more lines starting with whitespace, following the starting -line of the field, are considered part of the field. Here's an -example of a @samp{To} field with a continuation line: - -@example -@group -To: foo@@example.net, this@@example.net, - bob@@example.com -@end group -@end example - -@c There is also mail-specify-envelope-from and mail-envelope-from, but -@c these are probably not topics for the Emacs manual. - -@vindex mail-default-headers - You can direct Emacs to insert certain default headers into the mail -buffer by setting the variable @code{mail-default-headers} to a -string. Then @kbd{C-x m} inserts this string into the message -headers. For example, here is how to add a @samp{Reply-to} and -@samp{FCC} header to each message: - -@smallexample -(setq mail-default-headers - "Reply-to: foo@@example.com\nFCC: ~/Mail/sent") -@end smallexample - -@noindent -If the default header fields are not appropriate for a -particular message, edit them as necessary before sending the message. - -@node Mail Aliases -@section Mail Aliases -@cindex mail aliases -@cindex @file{.mailrc} file -@cindex mailrc file -@vindex mail-personal-alias-file - - You can define @dfn{mail aliases}, which are short mnemonic names -that stand for one or more mailing addresses. By default, mail -aliases are defined in the file @file{~/.mailrc}. You can specify a -different file name to use, by setting the variable -@code{mail-personal-alias-file}. - - To define an alias in @file{.mailrc}, write a line like this: - -@example -alias @var{nick} @var{fulladdresses} -@end example - -@noindent -This means that @var{nick} should expand into @var{fulladdresses}, -where @var{fulladdresses} can be either a single address, or multiple -addresses separated with spaces. For instance, to make @code{maingnu} -stand for @code{gnu@@gnu.org} plus a local address of your own, put in -this line:@refill - -@example -alias maingnu gnu@@gnu.org local-gnu -@end example - -@noindent -If an address contains a space, quote the whole address with a pair of -double quotes, like this: - -@example -alias jsmith "John Q. Smith " -@end example - -@noindent -Note that you need not include double quotes around individual parts -of the address, such as the person's full name. Emacs puts them in if -they are needed. For instance, it inserts the above address as -@samp{"John Q. Smith" }. - - Emacs also recognizes ``include'' commands in @file{.mailrc}. They -look like this: - -@example -source @var{filename} -@end example - -@noindent -The @file{.mailrc} file is not unique to Emacs; many other -mail-reading programs use it for mail aliases, and it can contain -various other commands. However, Emacs ignores everything except -alias definitions and include commands. - -@findex mail-abbrev-insert-alias - Mail aliases expand as abbrevs---that is to say, as soon as you type -a word-separator character after an alias (@pxref{Abbrevs}). This -expansion takes place only within the @samp{To}, @samp{From}, -@samp{CC}, @samp{BCC}, and @samp{Reply-to} header fields (plus their -@samp{Resent-} variants); it does not take place in other header -fields, such as @samp{Subject}. - - You can also insert an aliased address directly, using the command -@kbd{M-x mail-abbrev-insert-alias}. This reads an alias name, with -completion, and inserts its definition at point. - -@node Mail Commands -@section Mail Commands -@cindex Message mode -@cindex mode, Message - - The default major mode for the @file{*mail*} buffer is called -Message mode. It behaves like Text mode in many ways, but provides -several additional commands on the @kbd{C-c} prefix, which make -editing a message more convenient. - - In this section, we will describe some of the most commonly-used -commands available in Message mode. -@ifnottex -Message mode also has its own manual, where its features are described -in greater detail. @xref{Top,,Message, message, Message}. -@end ifnottex - -@menu -* Mail Sending:: Commands to send the message. -* Header Editing:: Commands to move to header fields and edit them. -* Citing Mail:: Quoting a message you are replying to. -* Mail Misc:: Attachments, spell checking, etc. -@end menu - -@node Mail Sending -@subsection Mail Sending - -@table @kbd -@item C-c C-c -Send the message, and bury the mail buffer (@code{message-send-and-exit}). -@item C-c C-s -Send the message, and leave the mail buffer selected (@code{message-send}). -@end table - -@kindex C-c C-s @r{(Message mode)} -@kindex C-c C-c @r{(Message mode)} -@findex message-send -@vindex message-kill-buffer-on-exit - The usual command to send a message is @kbd{C-c C-c} -(@code{mail-send-and-exit}). This sends the message and then -``buries'' the mail buffer, putting it at the lowest priority for -reselection. If you want it to kill the mail buffer instead, change -the variable @code{message-kill-buffer-on-exit} to @code{t}. - -@findex message-send-and-exit - The command @kbd{C-c C-s} (@code{message-send}) sends the message -and leaves the buffer selected. Use this command if you want to -modify the message (perhaps with new recipients) and send it again. - -@vindex message-send-hook - Sending a message runs the hook @code{message-send-hook}. It also -marks the mail buffer as unmodified, except if the mail buffer is also -a file-visiting buffer (in that case, only saving the file does that, -and you don't get a warning if you try to send the same message -twice). - -@cindex SMTP -@cindex Feedmail -@cindex Sendmail -@cindex Mailclient -@vindex send-mail-function - The variable @code{send-mail-function} controls how the message is -delivered. Its value should be one of the following functions: - -@table @code -@item sendmail-query-once -Query for a delivery method (one of the other entries in this list), -and use that method for this message; then save the method to -@code{send-mail-function}, so that it is used for future deliveries. -This is the default, unless you have already set the variables for -sending mail via @code{smtpmail-send-it} (see below). - -@item smtpmail-send-it -Send mail using the through an external mail host, such as your -Internet service provider's outgoing SMTP mail server. If you have -not told Emacs how to contact the SMTP server, it prompts for this -information, which is saved in the @code{smtpmail-smtp-server} variable -and the file @file{~/.authinfo}. -@xref{Top,,Emacs SMTP Library, smtpmail, Sending mail via SMTP}. - -@item sendmail-send-it -Send mail using the system's default @command{sendmail} program, or -equivalent. This requires the system to be set up for delivering mail -directly via SMTP. - -@item mailclient-send-it -Pass the mail buffer on to the system's designated mail client. See -the commentary section in the file @file{mailclient.el} for details. - -@item feedmail-send-it -This is similar to @code{sendmail-send-it}, but allows you to queue -messages for later sending. See the commentary section in the file -@file{feedmail.el} for details. -@end table - -@vindex sendmail-coding-system - When you send a message containing non-@acronym{ASCII} characters, -they need to be encoded with a coding system (@pxref{Coding Systems}). -Usually the coding system is specified automatically by your chosen -language environment (@pxref{Language Environments}). You can -explicitly specify the coding system for outgoing mail by setting the -variable @code{sendmail-coding-system} (@pxref{Recognize Coding}). If -the coding system thus determined does not handle the characters in a -particular message, Emacs asks you to select the coding system to use, -showing a list of possible coding systems. - -@node Header Editing -@subsection Mail Header Editing - - Message mode provides the following special commands to move to -particular header fields and to complete addresses in headers. - -@table @kbd -@item C-c C-f C-t -Move to the @samp{To} header (@code{message-goto-to}). -@item C-c C-f C-s -Move to the @samp{Subject} header (@code{message-goto-subject}). -@item C-c C-f C-c -Move to the @samp{CC} header (@code{message-goto-cc}). -@item C-c C-f C-b -Move to the @samp{BCC} header (@code{message-goto-bcc}). -@item C-c C-f C-r -Move to the @samp{Reply-To} header (@code{message-goto-reply-to}). -@item C-c C-f C-f -Move to the @samp{Mail-Followup-To} header field -(@code{message-goto-followup-to}). -@item C-c C-f C-w -Add a new @samp{FCC} header field, with file-name completion -(@code{message-goto-fcc}). -@item C-c C-b -Move to the start of the message body (@code{message-goto-body}). -@item @key{TAB} -Complete a mailing address (@code{message-tab}). -@end table - -@kindex C-c C-f C-t @r{(Message mode)} -@findex message-goto-to -@kindex C-c C-f C-s @r{(Message mode)} -@findex message-goto-subject -@kindex C-c C-f C-c @r{(Message mode)} -@findex message-goto-cc -@kindex C-c C-f C-b @r{(Message mode)} -@findex message-goto-bcc -@kindex C-c C-f C-r @r{(Message mode)} -@findex goto-reply-to -@kindex C-c C-f C-f @r{(Message mode)} -@findex goto-followup-to -@kindex C-c C-f C-w @r{(Message mode)} -@findex message-goto-fcc - The commands to move point to particular header fields are all based -on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). If the -field in question does not exist, the command creates one (the -exception is @code{mail-fcc}, which creates a new field each time). - -@kindex C-c C-b @r{(Message mode)} -@findex mail-text - The command @kbd{C-c C-b} (@code{message-goto-body}) moves point to -just after the header separator line---that is, to the beginning of -the body. - -@findex message-tab -@kindex TAB @r{(Message mode)} - While editing a header field that contains addresses, such as -@samp{To:}, @samp{CC:} and @samp{BCC:}, you can complete an address by -typing @key{TAB} (@code{message-tab}). This attempts to insert the -full name corresponding to the address based on a couple of methods, -including EUDC, a library that recognizes a number of directory server -protocols (@pxref{Top,,EUDC,eudc, The Emacs Unified Directory -Client}). Failing that, it attempts to expand the address as a mail -alias (@pxref{Mail Aliases}). If point is on a header field that does -not take addresses, or if it is in the message body, then @key{TAB} -just inserts a tab character. - -@node Citing Mail -@subsection Citing Mail -@cindex citing mail - -@table @kbd -@item C-c C-y -Yank the selected message from the mail reader, as a citation -(@code{message-yank-original}). -@item C-c C-q -Fill each paragraph cited from another message -(@code{message-fill-yanked-message}). -@end table - -@kindex C-c C-y @r{(Message mode)} -@findex message-yank-original -@findex message-yank-prefix - You can use the command @kbd{C-c C-y} (@code{message-yank-original}) -to @dfn{cite} a message that you are replying to. This inserts the -text of that message into the mail buffer. This command works only if -the mail buffer is invoked from a mail reader running in Emacs, such -as Rmail. - - By default, Emacs inserts the string @samp{>} in front of each line -of the cited text; this prefix string is specified by the variable -@code{message-yank-prefix}. If you call @code{message-yank-original} -with a prefix argument, the citation prefix is not inserted. - -@kindex C-c C-q @r{(Message mode)} -@findex mail-fill-yanked-message - After using @kbd{C-c C-y}, you can type @kbd{C-c C-q} -(@code{message-fill-yanked-message}) to fill the paragraphs of the -cited message. One use of @kbd{C-c C-q} fills all such paragraphs, -each one individually. To fill a single paragraph of the quoted -message, use @kbd{M-q}. If filling does not automatically handle the -type of citation prefix you use, try setting the fill prefix -explicitly. @xref{Filling}. - -@vindex mail-citation-hook - You can customize mail citation through the hook -@code{mail-citation-hook}. For example, you can use the Supercite -package, which provides more flexible citation -(@pxref{Introduction,,,sc, Supercite}). - -@node Mail Misc -@subsection Mail Miscellany - -@kindex C-c C-a @r{(Message mode)} -@findex mml-attach-file -@cindex MIME -@cindex Multipurpose Internet Mail Extensions - You can @dfn{attach} a file to an outgoing message by typing -@kbd{C-c C-a} (@code{mml-attach-file}) in the mail buffer. Attaching -is done using the Multipurpose Internet Mail Extensions -(@acronym{MIME}) standard. - - The @code{mml-attach-file} command prompts for the name of the file, -and for the attachment's @dfn{content type}, @dfn{description}, and -@dfn{disposition}. The content type is normally detected -automatically; just type @key{RET} to accept the default. The -description is a single line of text that the recipient will see next -to the attachment; you may also choose to leave this empty. The -disposition is either @samp{inline} (the default), which means the -recipient will see a link to the attachment within the message body, -or @samp{attachment}, which means the link will be separate from the -body. - -@findex mail-add-attachment - The @code{mml-attach-file} command is specific to Message mode; in -Mail mode use @kbd{mail-add-attachment} instead. It will prompt only -for the name of the file, and will determine the content type and the -disposition automatically. If you want to include some description of -the attached file, type that in the message body. - - The actual contents of the attached file are not inserted into the -mail buffer. Instead, some placeholder text is inserted into the mail -buffer, like this: - -@smallexample -<#part type="text/plain" filename="~/foo.txt" disposition=inline> -<#/part> -@end smallexample - -@noindent -When you type @kbd{C-c C-c} or @kbd{C-c C-s} to send the message, the -attached file will be delivered with it. - -@findex ispell-message - While composing a message, you can do spelling correction on the -message text by typing @kbd{M-x ispell-message}. If you have yanked -an incoming message into the outgoing draft, this command skips what -was yanked, but it checks the text that you yourself inserted (it -looks for indentation or @code{mail-yank-prefix} to distinguish the -cited lines from your input). @xref{Spelling}. - -@vindex mail-mode-hook -@vindex mail-setup-hook - Turning on Message mode (which @kbd{C-x m} does automatically) runs -the normal hooks @code{text-mode-hook} and @code{message-mode-hook}. -Initializing a new outgoing message runs the normal hook -@code{message-setup-hook}; you can use this hook if you want to make -changes to the appearance of the mail buffer. @xref{Hooks}. - - The main difference between these hooks is just when they are -invoked. Whenever you type @kbd{C-x m}, @code{message-mode-hook} runs -as soon as the mail buffer is created. Then the @code{message-setup} -function inserts the default contents of the buffer. After these -default contents are inserted, @code{message-setup-hook} runs. - - If you use @kbd{C-x m} to continue an existing composition, -@code{message-mode-hook} runs immediately after switching to the mail -buffer. If the buffer is unmodified, or if you decide to erase it and -start again, @code{message-setup-hook} runs after the default contents -are inserted. - -@node Mail Signature -@section Mail Signature - -@cindex mail signature -@vindex mail-signature-file -@vindex mail-signature - You can add a standard piece of text---your @dfn{mail -signature}---to the end of every message. This signature may contain -information such as your telephone number or your physical location. -The variable @code{mail-signature} determines how Emacs handles the -mail signature. - - The default value of @code{mail-signature} is @code{t}; this means -to look for your mail signature in the file @file{~/.signature}. If -this file exists, its contents are automatically inserted into the end -of the mail buffer. You can change the signature file via the -variable @code{mail-signature-file}. - - If you change @code{mail-signature} to a string, that specifies the -text of the signature directly. - -@kindex C-c C-w @r{(Message mode)} -@findex message-insert-signature - If you change @code{mail-signature} to @code{nil}, Emacs will not -insert your mail signature automatically. You can insert your mail -signature by typing @kbd{C-c C-w} (@code{message-insert-signature}) in -the mail buffer. Emacs will look for your signature in the signature -file. - - By convention, a mail signature should be marked by a line whose -contents are @samp{-- }. If your signature lacks this prefix, it is -added for you. The remainder of your signature should be no more than -four lines. - -@node Mail Amusements -@section Mail Amusements - -@findex spook -@cindex NSA - @kbd{M-x spook} adds a line of randomly chosen keywords to an outgoing -mail message. The keywords are chosen from a list of words that suggest -you are discussing something subversive. - - The idea behind this feature is the suspicion that the -NSA@footnote{The US National Security Agency.} and other intelligence -agencies snoop on all electronic mail messages that contain keywords -suggesting they might find them interesting. (The agencies say that -they don't, but that's what they @emph{would} say.) The idea is that if -lots of people add suspicious words to their messages, the agencies will -get so busy with spurious input that they will have to give up reading -it all. Whether or not this is true, it at least amuses some people. - -@findex fortune-to-signature -@cindex fortune cookies - You can use the @code{fortune} program to put a ``fortune cookie'' -message into outgoing mail. To do this, add -@code{fortune-to-signature} to @code{mail-setup-hook}: - -@example -(add-hook 'mail-setup-hook 'fortune-to-signature) -@end example - -@noindent -You will probably need to set the variable @code{fortune-file} before -using this. - -@node Mail Methods -@section Mail-Composition Methods -@cindex mail-composition methods -@cindex Mail mode -@cindex mode, Mail - -@cindex MH mail interface -@cindex Message mode for sending mail - In this chapter we have described the usual Emacs mode for editing -and sending mail---Message mode. This is only one of several -available modes. Prior to Emacs 23.2, the default mode was Mail mode, -which is similar to Message mode in many respects but lacks features -such as MIME support. Another available mode is MH-E -(@pxref{Top,,MH-E,mh-e, The Emacs Interface to MH}). - -@vindex mail-user-agent - You can choose any of these @dfn{mail user agents} as your preferred -method for editing and sending mail. The commands @code{C-x m}, -@code{C-x 4 m} and @code{C-x 5 m} use whichever agent you have -specified; so do various other parts of Emacs that send mail, such as -the bug reporter (@pxref{Bugs}). To specify a mail user agent, -customize the variable @code{mail-user-agent}. Currently, legitimate -values include @code{message-user-agent} (Message mode) -@code{sendmail-user-agent} (Mail mode), @code{gnus-user-agent}, and -@code{mh-e-user-agent}. - - If you select a different mail-composition method, the information -in this chapter about the mail buffer and Message mode does not apply; -the other methods use a different format of text in a different -buffer, and their commands are different as well. - -@vindex read-mail-command - Similarly, to specify your preferred method for reading mail, -customize the variable @code{read-mail-command}. The default is -@code{rmail} (@pxref{Rmail}). diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi deleted file mode 100644 index 90f4732079b..00000000000 --- a/doc/emacs/text.texi +++ /dev/null @@ -1,2808 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Text, Programs, Indentation, Top -@chapter Commands for Human Languages -@cindex text -@cindex manipulating text - - This chapter describes Emacs commands that act on @dfn{text}, by -which we mean sequences of characters in a human language (as opposed -to, say, a computer programming language). These commands act in ways -that take into account the syntactic and stylistic conventions of -human languages: conventions involving words, sentences, paragraphs, -and capital letters. There are also commands for @dfn{filling}, which -means rearranging the lines of a paragraph to be approximately equal -in length. These commands, while intended primarily for editing text, -are also often useful for editing programs. - - Emacs has several major modes for editing human-language text. If -the file contains ordinary text, use Text mode, which customizes Emacs -in small ways for the syntactic conventions of text. Outline mode -provides special commands for operating on text with an outline -structure. Org mode extends Outline mode and turn Emacs into a -full-fledged organizer: you can manage TODO lists, store notes and -publish them in many formats. - -@iftex -@xref{Outline Mode}. -@end iftex - -@cindex nXML mode -@cindex mode, XML -@cindex mode, nXML -@findex nxml-mode - Emacs has other major modes for text which contains ``embedded'' -commands, such as @TeX{} and La@TeX{} (@pxref{TeX Mode}); HTML and -SGML (@pxref{HTML Mode}); XML -@ifinfo -(@pxref{Top,The nXML Mode Manual,,nxml-mode, nXML Mode}); -@end ifinfo -@ifnotinfo -(see the nXML mode Info manual, which is distributed with Emacs); -@end ifnotinfo -and Groff and Nroff (@pxref{Nroff Mode}). - -@cindex ASCII art - If you need to edit pictures made out of text characters (commonly -referred to as ``ASCII art''), use Picture mode, a special major mode -for editing such pictures. -@iftex -@xref{Picture Mode,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Picture Mode}. -@end ifnottex - -@ifinfo -@cindex skeletons -@cindex templates -@cindex autotyping -@cindex automatic typing - The ``automatic typing'' features may be useful when writing text. -@inforef{Top,The Autotype Manual,autotype}. -@end ifinfo - -@menu -* Words:: Moving over and killing words. -* Sentences:: Moving over and killing sentences. -* Paragraphs:: Moving over paragraphs. -* Pages:: Moving over pages. -* Filling:: Filling or justifying text. -* Case:: Changing the case of text. -* Text Mode:: The major modes for editing text files. -* Outline Mode:: Editing outlines. -* Org Mode:: The Emacs organizer. -* TeX Mode:: Editing TeX and LaTeX files. -* HTML Mode:: Editing HTML and SGML files. -* Nroff Mode:: Editing input to the nroff formatter. -* Enriched Text:: Editing text "enriched" with fonts, colors, etc. -* Text Based Tables:: Commands for editing text-based tables. -* Two-Column:: Splitting text columns into separate windows. -@end menu - -@node Words -@section Words -@cindex words -@cindex Meta commands and words - - Emacs defines several commands for moving over or operating on -words: - -@table @kbd -@item M-f -Move forward over a word (@code{forward-word}). -@item M-b -Move backward over a word (@code{backward-word}). -@item M-d -Kill up to the end of a word (@code{kill-word}). -@item M-@key{DEL} -Kill back to the beginning of a word (@code{backward-kill-word}). -@item M-@@ -Mark the end of the next word (@code{mark-word}). -@item M-t -Transpose two words or drag a word across others -(@code{transpose-words}). -@end table - - Notice how these keys form a series that parallels the character-based -@kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}. @kbd{M-@@} is -cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}. - -@kindex M-f -@kindex M-b -@findex forward-word -@findex backward-word - The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b} -(@code{backward-word}) move forward and backward over words. These -@key{Meta}-based key sequences are analogous to the key sequences -@kbd{C-f} and @kbd{C-b}, which move over single characters. The -analogy extends to numeric arguments, which serve as repeat counts. -@kbd{M-f} with a negative argument moves backward, and @kbd{M-b} with -a negative argument moves forward. Forward motion stops right after -the last letter of the word, while backward motion stops right before -the first letter. - -@kindex M-d -@findex kill-word - @kbd{M-d} (@code{kill-word}) kills the word after point. To be -precise, it kills everything from point to the place @kbd{M-f} would -move to. Thus, if point is in the middle of a word, @kbd{M-d} kills -just the part after point. If some punctuation comes between point -and the next word, it is killed along with the word. (If you wish to -kill only the next word but not the punctuation before it, simply do -@kbd{M-f} to get the end, and kill the word backwards with -@kbd{M-@key{DEL}}.) @kbd{M-d} takes arguments just like @kbd{M-f}. - -@findex backward-kill-word -@kindex M-DEL - @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before -point. It kills everything from point back to where @kbd{M-b} would -move to. For instance, if point is after the space in @w{@samp{FOO, -BAR}}, it kills @w{@samp{FOO, }}. If you wish to kill just -@samp{FOO}, and not the comma and the space, use @kbd{M-b M-d} instead -of @kbd{M-@key{DEL}}. - -@c Don't index M-t and transpose-words here, they are indexed in -@c fixit.texi, in the node "Transpose". -@c @kindex M-t -@c @findex transpose-words - @kbd{M-t} (@code{transpose-words}) exchanges the word before or -containing point with the following word. The delimiter characters between -the words do not move. For example, @w{@samp{FOO, BAR}} transposes into -@w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for -more on transposition. - -@kindex M-@@ -@findex mark-word - To operate on words with an operation which acts on the region, use -the command @kbd{M-@@} (@code{mark-word}). This command sets the mark -where @kbd{M-f} would move to. @xref{Marking Objects}, for more -information about this command. - - The word commands' understanding of word boundaries is controlled by -the syntax table. Any character can, for example, be declared to be a -word delimiter. @xref{Syntax Tables,, Syntax Tables, elisp, The Emacs -Lisp Reference Manual}. - - In addition, see @ref{Position Info} for the @kbd{M-=} -(@code{count-words-region}) and @kbd{M-x count-words} commands, which -count and report the number of words in the region or buffer. - -@node Sentences -@section Sentences -@cindex sentences -@cindex manipulating sentences - - The Emacs commands for manipulating sentences and paragraphs are -mostly on Meta keys, like the word-handling commands. - -@table @kbd -@item M-a -Move back to the beginning of the sentence (@code{backward-sentence}). -@item M-e -Move forward to the end of the sentence (@code{forward-sentence}). -@item M-k -Kill forward to the end of the sentence (@code{kill-sentence}). -@item C-x @key{DEL} -Kill back to the beginning of the sentence (@code{backward-kill-sentence}). -@end table - -@kindex M-a -@kindex M-e -@findex backward-sentence -@findex forward-sentence - The commands @kbd{M-a} (@code{backward-sentence}) and @kbd{M-e} -(@code{forward-sentence}) move to the beginning and end of the current -sentence, respectively. Their bindings were chosen to resemble -@kbd{C-a} and @kbd{C-e}, which move to the beginning and end of a -line. Unlike them, @kbd{M-a} and @kbd{M-e} move over successive -sentences if repeated. - - Moving backward over a sentence places point just before the first -character of the sentence; moving forward places point right after the -punctuation that ends the sentence. Neither one moves over the -whitespace at the sentence boundary. - -@kindex M-k -@findex kill-sentence - Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to -go with them, @kbd{M-a} and @kbd{M-e} have a corresponding kill -command: @kbd{M-k} (@code{kill-sentence}) kills from point to the end -of the sentence. With a positive numeric argument @var{n}, it kills -the next @var{n} sentences; with a negative argument @minus{}@var{n}, -it kills back to the beginning of the @var{n}th preceding sentence. - -@kindex C-x DEL -@findex backward-kill-sentence - The @kbd{C-x @key{DEL}} (@code{backward-kill-sentence}) kills back -to the beginning of a sentence. - - The sentence commands assume that you follow the American typist's -convention of putting two spaces at the end of a sentence. That is, a -sentence ends wherever there is a @samp{.}, @samp{?} or @samp{!} -followed by the end of a line or two spaces, with any number of -@samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in -between. A sentence also begins or ends wherever a paragraph begins -or ends. It is useful to follow this convention, because it allows -the Emacs sentence commands to distinguish between periods that end a -sentence and periods that indicate abbreviations. - -@vindex sentence-end-double-space - If you want to use just one space between sentences, you can set the -variable @code{sentence-end-double-space} to @code{nil} to make the -sentence commands stop for single spaces. However, this has a -drawback: there is no way to distinguish between periods that end -sentences and those that indicate abbreviations. For convenient and -reliable editing, we therefore recommend you follow the two-space -convention. The variable @code{sentence-end-double-space} also -affects filling (@pxref{Fill Commands}). - -@vindex sentence-end - The variable @code{sentence-end} controls how to recognize the end -of a sentence. If non-@code{nil}, its value should be a regular -expression, which is used to match the last few characters of a -sentence, together with the whitespace following the sentence -(@pxref{Regexps}). If the value is @code{nil}, the default, then -Emacs computes sentence ends according to various criteria such as the -value of @code{sentence-end-double-space}. - -@vindex sentence-end-without-period - Some languages, such as Thai, do not use periods to indicate the end -of a sentence. Set the variable @code{sentence-end-without-period} to -@code{t} in such cases. - -@node Paragraphs -@section Paragraphs -@cindex paragraphs -@cindex manipulating paragraphs - - The Emacs commands for manipulating paragraphs are also on Meta keys. - -@table @kbd -@item M-@{ -Move back to previous paragraph beginning (@code{backward-paragraph}). -@item M-@} -Move forward to next paragraph end (@code{forward-paragraph}). -@item M-h -Put point and mark around this or next paragraph (@code{mark-paragraph}). -@end table - -@kindex M-@{ -@kindex M-@} -@findex backward-paragraph -@findex forward-paragraph - @kbd{M-@{} (@code{backward-paragraph}) moves to the beginning of the -current or previous paragraph (see below for the definition of a -paragraph). @kbd{M-@}} (@code{forward-paragraph}) moves to the end of -the current or next paragraph. If there is a blank line before the -paragraph, @kbd{M-@{} moves to the blank line. - -@kindex M-h -@findex mark-paragraph - When you wish to operate on a paragraph, type @kbd{M-h} -(@code{mark-paragraph}) to set the region around it. For example, -@kbd{M-h C-w} kills the paragraph around or after point. @kbd{M-h} -puts point at the beginning and mark at the end of the paragraph point -was in. If point is between paragraphs (in a run of blank lines, or -at a boundary), @kbd{M-h} sets the region around the paragraph -following point. If there are blank lines preceding the first line of -the paragraph, one of these blank lines is included in the region. If -the region is already active, the command sets the mark without -changing point, and each subsequent @kbd{M-h} further advances the -mark by one paragraph. - - The definition of a paragraph depends on the major mode. In -Fundamental mode, as well as Text mode and related modes, a paragraph -is separated each neighboring paragraph another by one or more -@dfn{blank lines}---lines that are either empty, or consist solely of -space, tab and/or formfeed characters. In programming language modes, -paragraphs are usually defined in a similar way, so that you can use -the paragraph commands even though there are no paragraphs as such in -a program. - - Note that an indented line is @emph{not} itself a paragraph break in -Text mode. If you want indented lines to separate paragraphs, use -Paragraph-Indent Text mode instead. @xref{Text Mode}. - - If you set a fill prefix, then paragraphs are delimited by all lines -which don't start with the fill prefix. @xref{Filling}. - -@vindex paragraph-start -@vindex paragraph-separate - The precise definition of a paragraph boundary is controlled by the -variables @code{paragraph-separate} and @code{paragraph-start}. The -value of @code{paragraph-start} is a regular expression that should -match lines that either start or separate paragraphs -(@pxref{Regexps}). The value of @code{paragraph-separate} is another -regular expression that should match lines that separate paragraphs -without being part of any paragraph (for example, blank lines). Lines -that start a new paragraph and are contained in it must match only -@code{paragraph-start}, not @code{paragraph-separate}. For example, -in Fundamental mode, @code{paragraph-start} is @w{@code{"\f\\|[ -\t]*$"}}, and @code{paragraph-separate} is @w{@code{"[ \t\f]*$"}}. - -@node Pages -@section Pages - -@cindex pages -@cindex formfeed character - Within some text files, text is divided into @dfn{pages} delimited -by the @dfn{formfeed character} (@acronym{ASCII} code 12, also denoted -as @key{control-L}), which is displayed in Emacs as the escape -sequence @samp{^L} (@pxref{Text Display}). Traditionally, when such -text files are printed to hardcopy, each formfeed character forces a -page break. Most Emacs commands treat it just like any other -character, so you can insert it with @kbd{C-q C-l}, delete it with -@key{DEL}, etc. In addition, Emacs provides commands to move over -pages and operate on them. - -@table @kbd -@item M-x what-page -Display the page number of point, and the line number within that page. -@item C-x [ -Move point to previous page boundary (@code{backward-page}). -@item C-x ] -Move point to next page boundary (@code{forward-page}). -@item C-x C-p -Put point and mark around this page (or another page) (@code{mark-page}). -@item C-x l -Count the lines in this page (@code{count-lines-page}). -@end table - -@findex what-page - @kbd{M-x what-page} counts pages from the beginning of the file, and -counts lines within the page, showing both numbers in the echo area. - -@kindex C-x [ -@kindex C-x ] -@findex forward-page -@findex backward-page - The @kbd{C-x [} (@code{backward-page}) command moves point to immediately -after the previous page delimiter. If point is already right after a page -delimiter, it skips that one and stops at the previous one. A numeric -argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page}) -command moves forward past the next page delimiter. - -@kindex C-x C-p -@findex mark-page - The @kbd{C-x C-p} command (@code{mark-page}) puts point at the -beginning of the current page (after that page delimiter at the -front), and the mark at the end of the page (after the page delimiter -at the end). - - @kbd{C-x C-p C-w} is a handy way to kill a page to move it -elsewhere. If you move to another page delimiter with @kbd{C-x [} and -@kbd{C-x ]}, then yank the killed page, all the pages will be properly -delimited once again. The reason @kbd{C-x C-p} includes only the -following page delimiter in the region is to ensure that. - - A numeric argument to @kbd{C-x C-p} specifies which page to go to, -relative to the current one. Zero means the current page, one -the next page, and @minus{}1 the previous one. - -@kindex C-x l -@findex count-lines-page - The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding -where to break a page in two. It displays in the echo area the total number -of lines in the current page, and then divides it up into those preceding -the current line and those following, as in - -@example -Page has 96 (72+25) lines -@end example - -@noindent - Notice that the sum is off by one; this is correct if point is not at the -beginning of a line. - -@vindex page-delimiter - The variable @code{page-delimiter} controls where pages begin. Its -value is a regular expression that matches the beginning of a line -that separates pages (@pxref{Regexps}). The normal value of this -variable is @code{"^\f"}, which matches a formfeed character at the -beginning of a line. - -@node Filling -@section Filling Text -@cindex filling text - - @dfn{Filling} text means breaking it up into lines that fit a -specified width. Emacs does filling in two ways. In Auto Fill mode, -inserting text with self-inserting characters also automatically fills -it. There are also explicit fill commands that you can use when editing -text. - -@menu -* Auto Fill:: Auto Fill mode breaks long lines automatically. -* Fill Commands:: Commands to refill paragraphs and center lines. -* Fill Prefix:: Filling paragraphs that are indented or in a comment, etc. -* Adaptive Fill:: How Emacs can determine the fill prefix automatically. -@end menu - -@node Auto Fill -@subsection Auto Fill Mode -@cindex Auto Fill mode -@cindex mode, Auto Fill - - @dfn{Auto Fill} mode is a buffer-local minor mode (@pxref{Minor -Modes}) in which lines are broken automatically when they become too -wide. Breaking happens only when you type a @key{SPC} or @key{RET}. - -@table @kbd -@item M-x auto-fill-mode -Enable or disable Auto Fill mode. -@item @key{SPC} -@itemx @key{RET} -In Auto Fill mode, break lines when appropriate. -@end table - -@findex auto-fill-mode - The mode command @kbd{M-x auto-fill-mode} toggles Auto Fill mode in -the current buffer. With a positive numeric argument, it enables Auto -Fill mode, and with a negative argument it disables it. If -@code{auto-fill-mode} is called from Lisp with an omitted or -@code{nil} argument, it enables Auto Fill mode. To enable Auto Fill -mode automatically in certain major modes, add @code{auto-fill-mode} -to the mode hooks (@pxref{Major Modes}). When Auto Fill mode is -enabled, the mode indicator @samp{Fill} appears in the mode line -(@pxref{Mode Line}). - - Auto Fill mode breaks lines automatically at spaces whenever they -get longer than the desired width. This line breaking occurs only -when you type @key{SPC} or @key{RET}. If you wish to insert a space -or newline without permitting line-breaking, type @kbd{C-q @key{SPC}} -or @kbd{C-q C-j} respectively. Also, @kbd{C-o} inserts a newline -without line breaking. - - When Auto Fill mode breaks a line, it tries to obey the -@dfn{adaptive fill prefix}: if a fill prefix can be deduced from the -first and/or second line of the current paragraph, it is inserted into -the new line (@pxref{Adaptive Fill}). Otherwise the new line is -indented, as though you had typed @key{TAB} on it -(@pxref{Indentation}). In a programming language mode, if a line is -broken in the middle of a comment, the comment is split by inserting -new comment delimiters as appropriate. - - Auto Fill mode does not refill entire paragraphs; it breaks lines -but does not merge lines. Therefore, editing in the middle of a -paragraph can result in a paragraph that is not correctly filled. To -fill it, call the explicit fill commands -@iftex -described in the next section. -@end iftex -@ifnottex -(@pxref{Fill Commands}). -@end ifnottex - -@node Fill Commands -@subsection Explicit Fill Commands - -@table @kbd -@item M-q -Fill current paragraph (@code{fill-paragraph}). -@item C-x f -Set the fill column (@code{set-fill-column}). -@item M-x fill-region -Fill each paragraph in the region (@code{fill-region}). -@item M-x fill-region-as-paragraph -Fill the region, considering it as one paragraph. -@item M-o M-s -Center a line. -@end table - -@kindex M-q -@findex fill-paragraph - The command @kbd{M-q} (@code{fill-paragraph}) @dfn{fills} the -current paragraph. It redistributes the line breaks within the -paragraph, and deletes any excess space and tab characters occurring -within the paragraph, in such a way that the lines end up fitting -within a certain maximum width. - -@findex fill-region - Normally, @kbd{M-q} acts on the paragraph where point is, but if -point is between paragraphs, it acts on the paragraph after point. If -the region is active, it acts instead on the text in the region. You -can also call @kbd{M-x fill-region} to specifically fill the text in -the region. - -@findex fill-region-as-paragraph - @kbd{M-q} and @code{fill-region} use the usual Emacs criteria for -finding paragraph boundaries (@pxref{Paragraphs}). For more control, -you can use @kbd{M-x fill-region-as-paragraph}, which refills -everything between point and mark as a single paragraph. This command -deletes any blank lines within the region, so separate blocks of text -end up combined into one block. - -@cindex justification - A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text -as well as filling it. This means that extra spaces are inserted to -make the right margin line up exactly at the fill column. To remove -the extra spaces, use @kbd{M-q} with no argument. (Likewise for -@code{fill-region}.) - -@vindex fill-column -@kindex C-x f -@findex set-fill-column - The maximum line width for filling is specified by the buffer-local -variable @code{fill-column}. The default value (@pxref{Locals}) is -70. The easiest way to set @code{fill-column} in the current buffer -is to use the command @kbd{C-x f} (@code{set-fill-column}). With a -numeric argument, it uses that as the new fill column. With just -@kbd{C-u} as argument, it sets @code{fill-column} to the current -horizontal position of point. - -@kindex M-o M-s @r{(Text mode)} -@cindex centering -@findex center-line - The command @kbd{M-o M-s} (@code{center-line}) centers the current line -within the current fill column. With an argument @var{n}, it centers -@var{n} lines individually and moves past them. This binding is -made by Text mode and is available only in that and related modes -(@pxref{Text Mode}). - - By default, Emacs considers a period followed by two spaces or by a -newline as the end of a sentence; a period followed by just one space -indicates an abbreviation, not the end of a sentence. Accordingly, -the fill commands will not break a line after a period followed by -just one space. If you set the variable -@code{sentence-end-double-space} to @code{nil}, the fill commands will -break a line after a period followed by one space, and put just one -space after each period. @xref{Sentences}, for other effects and -possible drawbacks of this. - -@vindex colon-double-space - If the variable @code{colon-double-space} is non-@code{nil}, the -fill commands put two spaces after a colon. - -@vindex fill-nobreak-predicate - To specify additional conditions where line-breaking is not allowed, -customize the abnormal hook variable @code{fill-nobreak-predicate} -(@pxref{Hooks}). Each function in this hook is called with no -arguments, with point positioned where Emacs is considering breaking a -line. If a function returns a non-@code{nil} value, Emacs will not -break the line there. Two functions you can use are -@code{fill-single-word-nobreak-p} (don't break after the first word of -a sentence or before the last) and @code{fill-french-nobreak-p} (don't -break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}). - -@node Fill Prefix -@subsection The Fill Prefix - -@cindex fill prefix - The @dfn{fill prefix} feature allows paragraphs to be filled so that -each line starts with a special string of characters (such as a -sequence of spaces, giving an indented paragraph). You can specify a -fill prefix explicitly; otherwise, Emacs tries to deduce one -automatically (@pxref{Adaptive Fill}). - -@table @kbd -@item C-x . -Set the fill prefix (@code{set-fill-prefix}). -@item M-q -Fill a paragraph using current fill prefix (@code{fill-paragraph}). -@item M-x fill-individual-paragraphs -Fill the region, considering each change of indentation as starting a -new paragraph. -@item M-x fill-nonuniform-paragraphs -Fill the region, considering only paragraph-separator lines as starting -a new paragraph. -@end table - -@kindex C-x . -@findex set-fill-prefix - To specify a fill prefix for the current buffer, move to a line that -starts with the desired prefix, put point at the end of the prefix, -and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). (That's a period -after the @kbd{C-x}.) To turn off the fill prefix, specify an empty -prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line. - - When a fill prefix is in effect, the fill commands remove the fill -prefix from each line of the paragraph before filling, and insert it -on each line after filling. (The beginning of the first line of the -paragraph is left unchanged, since often that is intentionally -different.) Auto Fill mode also inserts the fill prefix automatically -when it makes a new line (@pxref{Auto Fill}). The @kbd{C-o} command -inserts the fill prefix on new lines it creates, when you use it at -the beginning of a line (@pxref{Blank Lines}). Conversely, the -command @kbd{M-^} deletes the prefix (if it occurs) after the newline -that it deletes (@pxref{Indentation}). - - For example, if @code{fill-column} is 40 and you set the fill prefix -to @samp{;; }, then @kbd{M-q} in the following text - -@example -;; This is an -;; example of a paragraph -;; inside a Lisp-style comment. -@end example - -@noindent -produces this: - -@example -;; This is an example of a paragraph -;; inside a Lisp-style comment. -@end example - - Lines that do not start with the fill prefix are considered to start -paragraphs, both in @kbd{M-q} and the paragraph commands; this gives -good results for paragraphs with hanging indentation (every line -indented except the first one). Lines which are blank or indented once -the prefix is removed also separate or start paragraphs; this is what -you want if you are writing multi-paragraph comments with a comment -delimiter on each line. - -@findex fill-individual-paragraphs - You can use @kbd{M-x fill-individual-paragraphs} to set the fill -prefix for each paragraph automatically. This command divides the -region into paragraphs, treating every change in the amount of -indentation as the start of a new paragraph, and fills each of these -paragraphs. Thus, all the lines in one ``paragraph'' have the same -amount of indentation. That indentation serves as the fill prefix for -that paragraph. - -@findex fill-nonuniform-paragraphs - @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides -the region into paragraphs in a different way. It considers only -paragraph-separating lines (as defined by @code{paragraph-separate}) as -starting a new paragraph. Since this means that the lines of one -paragraph may have different amounts of indentation, the fill prefix -used is the smallest amount of indentation of any of the lines of the -paragraph. This gives good results with styles that indent a paragraph's -first line more or less that the rest of the paragraph. - -@vindex fill-prefix - The fill prefix is stored in the variable @code{fill-prefix}. Its value -is a string, or @code{nil} when there is no fill prefix. This is a -per-buffer variable; altering the variable affects only the current buffer, -but there is a default value which you can change as well. @xref{Locals}. - - The @code{indentation} text property provides another way to control -the amount of indentation paragraphs receive. @xref{Enriched -Indentation}. - -@node Adaptive Fill -@subsection Adaptive Filling - -@cindex adaptive filling - The fill commands can deduce the proper fill prefix for a paragraph -automatically in certain cases: either whitespace or certain punctuation -characters at the beginning of a line are propagated to all lines of the -paragraph. - - If the paragraph has two or more lines, the fill prefix is taken from -the paragraph's second line, but only if it appears on the first line as -well. - - If a paragraph has just one line, fill commands @emph{may} take a -prefix from that line. The decision is complicated because there are -three reasonable things to do in such a case: - -@itemize @bullet -@item -Use the first line's prefix on all the lines of the paragraph. - -@item -Indent subsequent lines with whitespace, so that they line up under the -text that follows the prefix on the first line, but don't actually copy -the prefix from the first line. - -@item -Don't do anything special with the second and following lines. -@end itemize - - All three of these styles of formatting are commonly used. So the -fill commands try to determine what you would like, based on the prefix -that appears and on the major mode. Here is how. - -@vindex adaptive-fill-first-line-regexp - If the prefix found on the first line matches -@code{adaptive-fill-first-line-regexp}, or if it appears to be a -comment-starting sequence (this depends on the major mode), then the -prefix found is used for filling the paragraph, provided it would not -act as a paragraph starter on subsequent lines. - - Otherwise, the prefix found is converted to an equivalent number of -spaces, and those spaces are used as the fill prefix for the rest of the -lines, provided they would not act as a paragraph starter on subsequent -lines. - - In Text mode, and other modes where only blank lines and page -delimiters separate paragraphs, the prefix chosen by adaptive filling -never acts as a paragraph starter, so it can always be used for filling. - -@vindex adaptive-fill-mode -@vindex adaptive-fill-regexp - The variable @code{adaptive-fill-regexp} determines what kinds of line -beginnings can serve as a fill prefix: any characters at the start of -the line that match this regular expression are used. If you set the -variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is -never chosen automatically. - -@vindex adaptive-fill-function - You can specify more complex ways of choosing a fill prefix -automatically by setting the variable @code{adaptive-fill-function} to a -function. This function is called with point after the left margin of a -line, and it should return the appropriate fill prefix based on that -line. If it returns @code{nil}, @code{adaptive-fill-regexp} gets -a chance to find a prefix. - -@node Case -@section Case Conversion Commands -@cindex case conversion - - Emacs has commands for converting either a single word or any arbitrary -range of text to upper case or to lower case. - -@table @kbd -@item M-l -Convert following word to lower case (@code{downcase-word}). -@item M-u -Convert following word to upper case (@code{upcase-word}). -@item M-c -Capitalize the following word (@code{capitalize-word}). -@item C-x C-l -Convert region to lower case (@code{downcase-region}). -@item C-x C-u -Convert region to upper case (@code{upcase-region}). -@end table - -@kindex M-l -@kindex M-u -@kindex M-c -@cindex words, case conversion -@cindex converting text to upper or lower case -@cindex capitalizing words -@findex downcase-word -@findex upcase-word -@findex capitalize-word - @kbd{M-l} (@code{downcase-word}) converts the word after point to -lower case, moving past it. Thus, repeating @kbd{M-l} converts -successive words. @kbd{M-u} (@code{upcase-word}) converts to all -capitals instead, while @kbd{M-c} (@code{capitalize-word}) puts the -first letter of the word into upper case and the rest into lower case. -All these commands convert several words at once if given an argument. -They are especially convenient for converting a large amount of text -from all upper case to mixed case, because you can move through the -text using @kbd{M-l}, @kbd{M-u} or @kbd{M-c} on each word as -appropriate, occasionally using @kbd{M-f} instead to skip a word. - - When given a negative argument, the word case conversion commands apply -to the appropriate number of words before point, but do not move point. -This is convenient when you have just typed a word in the wrong case: you -can give the case conversion command and continue typing. - - If a word case conversion command is given in the middle of a word, -it applies only to the part of the word which follows point. (This is -comparable to what @kbd{M-d} (@code{kill-word}) does.) With a -negative argument, case conversion applies only to the part of the -word before point. - -@kindex C-x C-l -@kindex C-x C-u -@findex downcase-region -@findex upcase-region - The other case conversion commands are @kbd{C-x C-u} -(@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which -convert everything between point and mark to the specified case. Point and -mark do not move. - - The region case conversion commands @code{upcase-region} and -@code{downcase-region} are normally disabled. This means that they ask -for confirmation if you try to use them. When you confirm, you may -enable the command, which means it will not ask for confirmation again. -@xref{Disabling}. - -@node Text Mode -@section Text Mode -@cindex Text mode -@cindex mode, Text -@findex text-mode - - Text mode is a major mode for editing files of text in a human -language. Files which have names ending in the extension @file{.txt} -are usually opened in Text mode (@pxref{Choosing Modes}). To -explicitly switch to Text mode, type @kbd{M-x text-mode}. - - In Text mode, only blank lines and page delimiters separate -paragraphs. As a result, paragraphs can be indented, and adaptive -filling determines what indentation to use when filling a paragraph. -@xref{Adaptive Fill}. - -@kindex TAB @r{(Text mode)} - In Text mode, the @key{TAB} (@code{indent-for-tab-command}) command -usually inserts whitespace up to the next tab stop, instead of -indenting the current line. @xref{Indentation}, for details. - - Text mode turns off the features concerned with comments except when -you explicitly invoke them. It changes the syntax table so that -single-quotes are considered part of words (e.g.@: @samp{don't} is -considered one word). However, if a word starts with a single-quote, -it is treated as a prefix for the purposes of capitalization -(e.g.@: @kbd{M-c} converts @samp{'hello'} into @samp{'Hello'}, as -expected). - -@cindex Paragraph-Indent Text mode -@cindex mode, Paragraph-Indent Text -@findex paragraph-indent-text-mode -@findex paragraph-indent-minor-mode - If you indent the first lines of paragraphs, then you should use -Paragraph-Indent Text mode (@kbd{M-x paragraph-indent-text-mode}) -rather than Text mode. In that mode, you do not need to have blank -lines between paragraphs, because the first-line indentation is -sufficient to start a paragraph; however paragraphs in which every -line is indented are not supported. Use @kbd{M-x -paragraph-indent-minor-mode} to enable an equivalent minor mode for -situations where you shouldn't change the major mode---in mail -composition, for instance. - -@kindex M-TAB @r{(Text mode)} - Text mode binds @kbd{M-@key{TAB}} to @code{ispell-complete-word}. -This command performs completion of the partial word in the buffer -before point, using the spelling dictionary as the space of possible -words. @xref{Spelling}. If your window manager defines -@kbd{M-@key{TAB}} to switch windows, you can type @kbd{@key{ESC} -@key{TAB}} or @kbd{C-M-i} instead. - -@vindex text-mode-hook - Entering Text mode runs the mode hook @code{text-mode-hook} -(@pxref{Major Modes}). - - The following sections describe several major modes that are -@dfn{derived} from Text mode. These derivatives share most of the -features of Text mode described above. In particular, derivatives of -Text mode run @code{text-mode-hook} prior to running their own mode -hooks. - -@node Outline Mode -@section Outline Mode -@cindex Outline mode -@cindex mode, Outline -@cindex invisible lines - -@findex outline-mode -@findex outline-minor-mode -@vindex outline-minor-mode-prefix -@vindex outline-mode-hook - Outline mode is a major mode derived from Text mode, which is -specialized for editing outlines. It provides commands to navigate -between entries in the outline structure, and commands to make parts -of a buffer temporarily invisible, so that the outline structure may -be more easily viewed. Type @kbd{M-x outline-mode} to switch to -Outline mode. Entering Outline mode runs the hook -@code{text-mode-hook} followed by the hook @code{outline-mode-hook} -(@pxref{Hooks}). - - When you use an Outline mode command to make a line invisible -(@pxref{Outline Visibility}), the line disappears from the screen. An -ellipsis (three periods in a row) is displayed at the end of the -previous visible line, to indicate the hidden text. Multiple -consecutive invisible lines produce just one ellipsis. - - Editing commands that operate on lines, such as @kbd{C-n} and -@kbd{C-p}, treat the text of the invisible line as part of the -previous visible line. Killing the ellipsis at the end of a visible -line really kills all the following invisible text associated with the -ellipsis. - - Outline minor mode is a buffer-local minor mode which provides the -same commands as the major mode, Outline mode, but can be used in -conjunction with other major modes. You can type @kbd{M-x -outline-minor-mode} to toggle Outline minor mode in the current -buffer, or use a file-local variable setting to enable it in a -specific file (@pxref{File Variables}). - -@kindex C-c @@ @r{(Outline minor mode)} - The major mode, Outline mode, provides special key bindings on the -@kbd{C-c} prefix. Outline minor mode provides similar bindings with -@kbd{C-c @@} as the prefix; this is to reduce the conflicts with the -major mode's special commands. (The variable -@code{outline-minor-mode-prefix} controls the prefix used.) - -@menu -* Outline Format:: What the text of an outline looks like. -* Outline Motion:: Special commands for moving through outlines. -* Outline Visibility:: Commands to control what is visible. -* Outline Views:: Outlines and multiple views. -* Foldout:: Folding means zooming in on outlines. -@end menu - -@node Outline Format -@subsection Format of Outlines - -@cindex heading lines (Outline mode) -@cindex body lines (Outline mode) - Outline mode assumes that the lines in the buffer are of two types: -@dfn{heading lines} and @dfn{body lines}. A heading line represents a -topic in the outline. Heading lines start with one or more asterisk -(@samp{*}) characters; the number of asterisks determines the depth of -the heading in the outline structure. Thus, a heading line with one -@samp{*} is a major topic; all the heading lines with two @samp{*}s -between it and the next one-@samp{*} heading are its subtopics; and so -on. Any line that is not a heading line is a body line. Body lines -belong with the preceding heading line. Here is an example: - -@example -* Food -This is the body, -which says something about the topic of food. - -** Delicious Food -This is the body of the second-level header. - -** Distasteful Food -This could have -a body too, with -several lines. - -*** Dormitory Food - -* Shelter -Another first-level topic with its header line. -@end example - - A heading line together with all following body lines is called -collectively an @dfn{entry}. A heading line together with all following -deeper heading lines and their body lines is called a @dfn{subtree}. - -@vindex outline-regexp - You can customize the criterion for distinguishing heading lines by -setting the variable @code{outline-regexp}. (The recommended ways to -do this are in a major mode function or with a file local variable.) -Any line whose beginning has a match for this regexp is considered a -heading line. Matches that start within a line (not at the left -margin) do not count. - - The length of the matching text determines the level of the heading; -longer matches make a more deeply nested level. Thus, for example, if -a text formatter has commands @samp{@@chapter}, @samp{@@section} and -@samp{@@subsection} to divide the document into chapters and sections, -you could make those lines count as heading lines by setting -@code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. Note -the trick: the two words @samp{chapter} and @samp{section} are equally -long, but by defining the regexp to match only @samp{chap} we ensure -that the length of the text matched on a chapter heading is shorter, -so that Outline mode will know that sections are contained in -chapters. This works as long as no other command starts with -@samp{@@chap}. - -@vindex outline-level - You can explicitly specify a rule for calculating the level of a -heading line by setting the variable @code{outline-level}. The value -of @code{outline-level} should be a function that takes no arguments -and returns the level of the current heading. The recommended ways to -set this variable are in a major mode command or with a file local -variable. - -@node Outline Motion -@subsection Outline Motion Commands - - Outline mode provides special motion commands that move backward and -forward to heading lines. - -@table @kbd -@item C-c C-n -Move point to the next visible heading line -(@code{outline-next-visible-heading}). -@item C-c C-p -Move point to the previous visible heading line -(@code{outline-previous-visible-heading}). -@item C-c C-f -Move point to the next visible heading line at the same level -as the one point is on (@code{outline-forward-same-level}). -@item C-c C-b -Move point to the previous visible heading line at the same level -(@code{outline-backward-same-level}). -@item C-c C-u -Move point up to a lower-level (more inclusive) visible heading line -(@code{outline-up-heading}). -@end table - -@findex outline-next-visible-heading -@findex outline-previous-visible-heading -@kindex C-c C-n @r{(Outline mode)} -@kindex C-c C-p @r{(Outline mode)} - @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to -the next heading line. @kbd{C-c C-p} -(@code{outline-previous-visible-heading}) moves similarly backward. -Both accept numeric arguments as repeat counts. - -@findex outline-up-heading -@findex outline-forward-same-level -@findex outline-backward-same-level -@kindex C-c C-f @r{(Outline mode)} -@kindex C-c C-b @r{(Outline mode)} -@kindex C-c C-u @r{(Outline mode)} - The commands @kbd{C-c C-f} (@code{outline-forward-same-level}) and -@kbd{C-c C-b} (@code{outline-backward-same-level}) move from one -heading line to another visible heading at the same depth in the -outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves backward to -another heading that is less deeply nested. - -@node Outline Visibility -@subsection Outline Visibility Commands - - Outline mode provides several commands for temporarily hiding or -revealing parts of the buffer, based on the outline structure. These -commands are not undoable; their effects are simply not recorded by -the undo mechanism, so you can undo right past them (@pxref{Undo}). - - Many of these commands act on the ``current'' heading line. If -point is on a heading line, that is the current heading line; if point -is on a body line, the current heading line is the nearest preceding -header line. - -@table @kbd -@item C-c C-c -Make the current heading line's body invisible (@code{hide-entry}). -@item C-c C-e -Make the current heading line's body visible (@code{show-entry}). -@item C-c C-d -Make everything under the current heading invisible, not including the -heading itself (@code{hide-subtree}). -@item C-c C-s -Make everything under the current heading visible, including body, -subheadings, and their bodies (@code{show-subtree}). -@item C-c C-l -Make the body of the current heading line, and of all its subheadings, -invisible (@code{hide-leaves}). -@item C-c C-k -Make all subheadings of the current heading line, at all levels, -visible (@code{show-branches}). -@item C-c C-i -Make immediate subheadings (one level down) of the current heading -line visible (@code{show-children}). -@item C-c C-t -Make all body lines in the buffer invisible (@code{hide-body}). -@item C-c C-a -Make all lines in the buffer visible (@code{show-all}). -@item C-c C-q -Hide everything except the top @var{n} levels of heading lines -(@code{hide-sublevels}). -@item C-c C-o -Hide everything except for the heading or body that point is in, plus -the headings leading up from there to the top level of the outline -(@code{hide-other}). -@end table - -@findex hide-entry -@findex show-entry -@kindex C-c C-c @r{(Outline mode)} -@kindex C-c C-e @r{(Outline mode)} - The simplest of these commands are @kbd{C-c C-c} -(@code{hide-entry}), which hides the body lines directly following the -current heading line, and @kbd{C-c C-e} (@code{show-entry}), which -reveals them. Subheadings and their bodies are not affected. - -@findex hide-subtree -@findex show-subtree -@kindex C-c C-s @r{(Outline mode)} -@kindex C-c C-d @r{(Outline mode)} -@cindex subtree (Outline mode) - The commands @kbd{C-c C-d} (@code{hide-subtree}) and @kbd{C-c C-s} -(@code{show-subtree}) are more powerful. They apply to the current -heading line's @dfn{subtree}: its body, all of its subheadings, both -direct and indirect, and all of their bodies. - -@findex hide-leaves -@findex show-branches -@findex show-children -@kindex C-c C-l @r{(Outline mode)} -@kindex C-c C-k @r{(Outline mode)} -@kindex C-c C-i @r{(Outline mode)} - The command @kbd{C-c C-l} (@code{hide-leaves}) hides the body of the -current heading line as well as all the bodies in its subtree; the -subheadings themselves are left visible. The command @kbd{C-c C-k} -(@code{show-branches}) reveals the subheadings, if they had previously -been hidden (e.g.@: by @kbd{C-c C-d}). The command @kbd{C-c C-i} -(@code{show-children}) is a weaker version of this; it reveals just -the direct subheadings, i.e.@: those one level down. - -@findex hide-other -@kindex C-c C-o @r{(Outline mode)} - The command @kbd{C-c C-o} (@code{hide-other}) hides everything -except the entry that point is in, plus its parents (the headers -leading up from there to top level in the outline) and the top level -headings. - -@findex hide-body -@findex show-all -@kindex C-c C-t @r{(Outline mode)} -@kindex C-c C-a @r{(Outline mode)} -@findex hide-sublevels -@kindex C-c C-q @r{(Outline mode)} - The remaining commands affect the whole buffer. @kbd{C-c C-t} -(@code{hide-body}) makes all body lines invisible, so that you see -just the outline structure (as a special exception, it will not hide -lines at the top of the file, preceding the first header line, even -though these are technically body lines). @kbd{C-c C-a} -(@code{show-all}) makes all lines visible. @kbd{C-c C-q} -(@code{hide-sublevels}) hides all but the top level headings; with a -numeric argument @var{n}, it hides everything except the top @var{n} -levels of heading lines. - -@findex reveal-mode - When incremental search finds text that is hidden by Outline mode, -it makes that part of the buffer visible. If you exit the search at -that position, the text remains visible. You can also automatically -make text visible as you navigate in it by using Reveal mode (@kbd{M-x -reveal-mode}), a buffer-local minor mode. - -@node Outline Views -@subsection Viewing One Outline in Multiple Views - -@cindex multiple views of outline -@cindex views of an outline -@cindex outline with multiple views -@cindex indirect buffers and outlines - You can display two views of a single outline at the same time, in -different windows. To do this, you must create an indirect buffer using -@kbd{M-x make-indirect-buffer}. The first argument of this command is -the existing outline buffer name, and its second argument is the name to -use for the new indirect buffer. @xref{Indirect Buffers}. - - Once the indirect buffer exists, you can display it in a window in the -normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline -mode commands to show and hide parts of the text operate on each buffer -independently; as a result, each buffer can have its own view. If you -want more than two views on the same outline, create additional indirect -buffers. - -@node Foldout -@subsection Folding Editing - -@cindex folding editing - The Foldout package extends Outline mode and Outline minor mode with -``folding'' commands. The idea of folding is that you zoom in on a -nested portion of the outline, while hiding its relatives at higher -levels. - - Consider an Outline mode buffer with all the text and subheadings under -level-1 headings hidden. To look at what is hidden under one of these -headings, you could use @kbd{C-c C-e} (@kbd{M-x show-entry}) to expose -the body, or @kbd{C-c C-i} to expose the child (level-2) headings. - -@kindex C-c C-z -@findex foldout-zoom-subtree - With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}). -This exposes the body and child subheadings, and narrows the buffer so -that only the @w{level-1} heading, the body and the level-2 headings are -visible. Now to look under one of the level-2 headings, position the -cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body -and its level-3 child subheadings and narrows the buffer again. Zooming -in on successive subheadings can be done as much as you like. A string -in the mode line shows how deep you've gone. - - When zooming in on a heading, to see only the child subheadings specify -a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children -can be specified too (compare @kbd{M-x show-children}), e.g.@: @kbd{M-2 -C-c C-z} exposes two levels of child subheadings. Alternatively, the -body can be specified with a negative argument: @kbd{M-- C-c C-z}. The -whole subtree can be expanded, similarly to @kbd{C-c C-s} (@kbd{M-x -show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}. - - While you're zoomed in, you can still use Outline mode's exposure and -hiding functions without disturbing Foldout. Also, since the buffer is -narrowed, ``global'' editing actions will only affect text under the -zoomed-in heading. This is useful for restricting changes to a -particular chapter or section of your document. - -@kindex C-c C-x -@findex foldout-exit-fold - To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}). -This hides all the text and subheadings under the top-level heading and -returns you to the previous view of the buffer. Specifying a numeric -argument exits that many levels of folds. Specifying a zero argument -exits all folds. - - To cancel the narrowing of a fold without hiding the text and -subheadings, specify a negative argument. For example, @kbd{M--2 C-c -C-x} exits two folds and leaves the text and subheadings exposed. - - Foldout mode also provides mouse commands for entering and exiting -folds, and for showing and hiding text: - -@table @asis -@item @kbd{C-M-Mouse-1} zooms in on the heading clicked on -@itemize @w{} -@item -single click: expose body. -@item -double click: expose subheadings. -@item -triple click: expose body and subheadings. -@item -quad click: expose entire subtree. -@end itemize -@item @kbd{C-M-Mouse-2} exposes text under the heading clicked on -@itemize @w{} -@item -single click: expose body. -@item -double click: expose subheadings. -@item -triple click: expose body and subheadings. -@item -quad click: expose entire subtree. -@end itemize -@item @kbd{C-M-Mouse-3} hides text under the heading clicked on or exits fold -@itemize @w{} -@item -single click: hide subtree. -@item -double click: exit fold and hide text. -@item -triple click: exit fold without hiding text. -@item -quad click: exit all folds and hide text. -@end itemize -@end table - -@c FIXME not marked as a user variable -@vindex foldout-mouse-modifiers - You can specify different modifier keys (instead of -@kbd{Control-Meta-}) by setting @code{foldout-mouse-modifiers}; but if -you have already loaded the @file{foldout.el} library, you must reload -it in order for this to take effect. - - To use the Foldout package, you can type @kbd{M-x load-library -@key{RET} foldout @key{RET}}; or you can arrange for to do that -automatically by putting the following in your init file: - -@example -(eval-after-load "outline" '(require 'foldout)) -@end example - -@node Org Mode -@section Org Mode -@cindex organizer -@cindex planner -@findex Org mode -@findex mode, Org - -@findex org-mode - Org mode is a variant of Outline mode for using Emacs as an -organizer and/or authoring system. Files with names ending in the -extension @file{.org} are opened in Org mode (@pxref{Choosing Modes}). -To explicitly switch to Org mode, type @kbd{M-x org-mode}. - - In Org mode, as in Outline mode, each entry has a heading line that -starts with one or more @samp{*} characters. @xref{Outline Format}. -In addition, any line that begins with the @samp{#} character is -treated as a comment. - -@kindex TAB @r{(Org Mode)} -@findex org-cycle - Org mode provides commands for easily viewing and manipulating the -outline structure. The simplest of these commands is @key{TAB} -(@code{org-cycle}). If invoked on a heading line, it cycles through -the different visibility states of the subtree: (i) showing only that -heading line, (ii) showing only the heading line and the heading lines -of its direct children, if any, and (iii) showing the entire subtree. -If invoked in a body line, the global binding for @key{TAB} is -executed. - -@kindex S-TAB @r{(Org Mode)} -@findex org-shifttab - Typing @key{S-TAB} (@code{org-shifttab}) anywhere in an Org mode -buffer cycles the visibility of the entire outline structure, between -(i) showing only top-level heading lines, (ii) showing all heading -lines but no body lines, and (iii) showing everything. - -@kindex M- @r{(Org Mode)} -@kindex M- @r{(Org Mode)} -@kindex M- @r{(Org Mode)} -@kindex M- @r{(Org Mode)} -@findex org-metaup -@findex org-metadown -@findex org-metaleft -@findex org-metaright - You can move an entire entry up or down in the buffer, including its -body lines and subtree (if any), by typing @kbd{M-} -(@code{org-metaup}) or @kbd{M-} (@code{org-metadown}) on the -heading line. Similarly, you can promote or demote a heading line -with @kbd{M-} (@code{org-metaleft}) and @kbd{M-} -(@code{org-metaright}). These commands execute their global bindings -if invoked on a body line. - - The following subsections give basic instructions for using Org mode -as an organizer and as an authoring system. For details, @pxref{Top, -The Org Mode Manual, Introduction, org, The Org Manual}. - -@menu -* Org Organizer:: Managing TODO lists and agendas. -* Org Authoring:: Exporting Org buffers to various formats. -@end menu - -@node Org Organizer -@subsection Org as an organizer -@cindex TODO item -@cindex Org agenda - -@kindex C-c C-t @r{(Org Mode)} -@findex org-todo -@vindex org-todo-keywords - You can tag an Org entry as a @dfn{TODO} item by typing @kbd{C-c -C-t} (@code{org-todo}) anywhere in the entry. This adds the keyword -@samp{TODO} to the heading line. Typing @kbd{C-c C-t} again switches -the keyword to @samp{DONE}; another @kbd{C-c C-t} removes the keyword -entirely, and so forth. You can customize the keywords used by -@kbd{C-c C-t} via the variable @code{org-todo-keywords}. - -@kindex C-c C-s @r{(Org Mode)} -@kindex C-c C-d @r{(Org Mode)} -@findex org-schedule -@findex org-deadline - Apart from marking an entry as TODO, you can attach a date to it, by -typing @kbd{C-c C-s} (@code{org-schedule}) in the entry. This prompts -for a date by popping up the Emacs Calendar (@pxref{Calendar/Diary}), -and then adds the tag @samp{SCHEDULED}, together with the selected -date, beneath the heading line. The command @kbd{C-c C-d} -(@code{org-deadline}) has the same effect, except that it uses the tag -@code{DEADLINE}. - -@kindex C-c [ @r{(Org Mode)} -@findex org-agenda-file-to-front -@vindex org-agenda-files - Once you have some TODO items planned in an Org file, you can add -that file to the list of @dfn{agenda files} by typing @kbd{C-c [} -(@code{org-agenda-file-to-front}). Org mode is designed to let you -easily maintain multiple agenda files, e.g.@: for organizing different -aspects of your life. The list of agenda files is stored in the -variable @code{org-agenda-files}. - -@findex org-agenda - To view items coming from your agenda files, type @kbd{M-x -org-agenda}. This command prompts for what you want to see: a list of -things to do this week, a list of TODO items with specific keywords, -etc. -@ifnottex -@xref{Agenda Views,,,org, The Org Manual}, for details. -@end ifnottex - -@node Org Authoring -@subsection Org as an authoring system -@cindex Org exporting - -@findex org-export -@kindex C-c C-e @r{(Org mode)} - You may want to format your Org notes nicely and to prepare them for -export and publication. To export the current buffer, type @kbd{C-c -C-e} (@code{org-export}) anywhere in an Org buffer. This command -prompts for an export format; currently supported formats include -HTML, La@TeX{}, OpenDocument (@file{.odt}), and PDF. Some formats, -such as PDF, require certain system tools to be installed. - -@vindex org-publish-project-alist - To export several files at once to a specific directory, either -locally or over the network, you must define a list of projects -through the variable @code{org-publish-project-alist}. See its -documentation for details. - - Org supports a simple markup scheme for applying text formatting to -exported documents: - -@example -- This text is /emphasized/ -- This text is *in bold* -- This text is _underlined_ -- This text uses =a teletype font= - -#+begin_quote -``This is a quote.'' -#+end_quote - -#+begin_example -This is an example. -#+end_example -@end example - - For further details, see @ref{Exporting,,,org, The Org Manual} and -@ref{Publishing,,,org, The Org Manual}. - -@node TeX Mode -@section @TeX{} Mode -@cindex @TeX{} mode -@cindex La@TeX{} mode -@cindex Sli@TeX{} mode -@cindex Doc@TeX{} mode -@cindex mode, @TeX{} -@cindex mode, La@TeX{} -@cindex mode, Sli@TeX{} -@cindex mode, Doc@TeX{} -@findex tex-mode -@findex plain-tex-mode -@findex latex-mode -@findex slitex-mode -@findex doctex-mode -@findex bibtex-mode - - Emacs provides special major modes for editing files written in -@TeX{} and its related formats. @TeX{} is a powerful text formatter -written by Donald Knuth; like GNU Emacs, it is free software. -La@TeX{} is a simplified input format for @TeX{}, implemented using -@TeX{} macros. Doc@TeX{} is a special file format in which the -La@TeX{} sources are written, combining sources with documentation. -Sli@TeX{} is an obsolete special form of La@TeX{}.@footnote{It has -been replaced by the @samp{slides} document class, which comes with -La@TeX{}.} - -@vindex tex-default-mode - @TeX{} mode has four variants: Plain @TeX{} mode, La@TeX{} mode, -Doc@TeX{} mode, and Sli@TeX{} mode. These distinct major modes differ -only slightly, and are designed for editing the four different -formats. Emacs selects the appropriate mode by looking at the -contents of the buffer. (This is done by the @code{tex-mode} command, -which is normally called automatically when you visit a @TeX{}-like -file. @xref{Choosing Modes}.) If the contents are insufficient to -determine this, Emacs chooses the mode specified by the variable -@code{tex-default-mode}; its default value is @code{latex-mode}. If -Emacs does not guess right, you can select the correct variant of -@TeX{} mode using the command @kbd{M-x plain-tex-mode}, @kbd{M-x -latex-mode}, @kbd{M-x slitex-mode}, or @kbd{doctex-mode}. - - The following sections document the features of @TeX{} mode and its -variants. There are several other @TeX{}-related Emacs packages, -which are not documented in this manual: - -@itemize @bullet -@item -Bib@TeX{} mode is a major mode for Bib@TeX{} files, which are commonly -used for keeping bibliographic references for La@TeX{} documents. For -more information, see the documentation string for the command -@code{bibtex-mode}. - -@item -The Ref@TeX{} package provides a minor mode which can be used with -La@TeX{} mode to manage bibliographic references. -@ifinfo -@xref{Top,The Ref@TeX{} Manual,,reftex}. -@end ifinfo -@ifnotinfo -For more information, see the Ref@TeX{} Info manual, which is -distributed with Emacs. -@end ifnotinfo - -@item -The AUC@TeX{} package provides more advanced features for editing -@TeX{} and its related formats, including the ability to preview -@TeX{} equations within Emacs buffers. Unlike Bib@TeX{} mode and the -Ref@TeX{} package, AUC@TeX{} is not distributed with Emacs by default. -It can be downloaded via the Package Menu (@pxref{Packages}); once -installed, see -@ifinfo -@ref{Top,The AUC@TeX{} Manual,,auctex}. -@end ifinfo -@ifnotinfo -the AUC@TeX{} manual, which is included with the package. -@end ifnotinfo -@end itemize - -@menu -* TeX Editing:: Special commands for editing in TeX mode. -* LaTeX Editing:: Additional commands for LaTeX input files. -* TeX Print:: Commands for printing part of a file with TeX. -* TeX Misc:: Customization of TeX mode, and related features. -@end menu - -@node TeX Editing -@subsection @TeX{} Editing Commands - -@table @kbd -@item " -Insert, according to context, either @samp{``} or @samp{"} or -@samp{''} (@code{tex-insert-quote}). -@item C-j -Insert a paragraph break (two newlines) and check the previous -paragraph for unbalanced braces or dollar signs -(@code{tex-terminate-paragraph}). -@item M-x tex-validate-region -Check each paragraph in the region for unbalanced braces or dollar signs. -@item C-c @{ -Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}). -@item C-c @} -Move forward past the next unmatched close brace (@code{up-list}). -@end table - -@findex tex-insert-quote -@kindex " @r{(@TeX{} mode)} - In @TeX{}, the character @samp{"} is not normally used; instead, -quotations begin with @samp{``} and end with @samp{''}. @TeX{} mode -therefore binds the @kbd{"} key to the @code{tex-insert-quote} -command. This inserts @samp{``} after whitespace or an open brace, -@samp{"} after a backslash, and @samp{''} after any other character. - - As a special exception, if you type @kbd{"} when the text before -point is either @samp{``} or @samp{''}, Emacs replaces that preceding -text with a single @samp{"} character. You can therefore type -@kbd{""} to insert @samp{"}, should you ever need to do so. (You can -also use @kbd{C-q "} to insert this character.) - - In @TeX{} mode, @samp{$} has a special syntax code which attempts to -understand the way @TeX{} math mode delimiters match. When you insert a -@samp{$} that is meant to exit math mode, the position of the matching -@samp{$} that entered math mode is displayed for a second. This is the -same feature that displays the open brace that matches a close brace that -is inserted. However, there is no way to tell whether a @samp{$} enters -math mode or leaves it; so when you insert a @samp{$} that enters math -mode, the previous @samp{$} position is shown as if it were a match, even -though they are actually unrelated. - -@findex tex-insert-braces -@kindex C-c @{ @r{(@TeX{} mode)} -@findex up-list -@kindex C-c @} @r{(@TeX{} mode)} - @TeX{} uses braces as delimiters that must match. Some users prefer -to keep braces balanced at all times, rather than inserting them -singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of -braces. It leaves point between the two braces so you can insert the -text that belongs inside. Afterward, use the command @kbd{C-c @}} -(@code{up-list}) to move forward past the close brace. - -@findex tex-validate-region -@findex tex-terminate-paragraph -@kindex C-j @r{(@TeX{} mode)} - There are two commands for checking the matching of braces. -@kbd{C-j} (@code{tex-terminate-paragraph}) checks the paragraph before -point, and inserts two newlines to start a new paragraph. It outputs -a message in the echo area if any mismatch is found. @kbd{M-x -tex-validate-region} checks a region, paragraph by paragraph. The -errors are listed in an @file{*Occur*} buffer; you can use the usual -Occur mode commands in that buffer, such as @kbd{C-c C-c}, to visit a -particular mismatch (@pxref{Other Repeating Search}). - - Note that Emacs commands count square brackets and parentheses in -@TeX{} mode, not just braces. This is not strictly correct for the -purpose of checking @TeX{} syntax. However, parentheses and square -brackets are likely to be used in text as matching delimiters, and it -is useful for the various motion commands and automatic match display -to work with them. - -@node LaTeX Editing -@subsection La@TeX{} Editing Commands - - La@TeX{} mode provides a few extra features not applicable to plain -@TeX{}: - -@table @kbd -@item C-c C-o -Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position -point on a line between them (@code{tex-latex-block}). -@item C-c C-e -Close the innermost La@TeX{} block not yet closed -(@code{tex-close-latex-block}). -@end table - -@findex tex-latex-block -@kindex C-c C-o @r{(La@TeX{} mode)} - In La@TeX{} input, @samp{\begin} and @samp{\end} tags are used to -group blocks of text. To insert a block, type @kbd{C-c C-o} -(@code{tex-latex-block}). This prompts for a block type, and inserts -the appropriate matching @samp{\begin} and @samp{\end} tags, leaving a -blank line between the two and moving point there. - -@vindex latex-block-names - When entering the block type argument to @kbd{C-c C-o}, you can use -the usual completion commands (@pxref{Completion}). The default -completion list contains the standard La@TeX{} block types. If you -want additional block types for completion, customize the list -variable @code{latex-block-names}. - -@findex tex-close-latex-block -@kindex C-c C-e @r{(La@TeX{} mode)} -@findex latex-electric-env-pair-mode - In La@TeX{} input, @samp{\begin} and @samp{\end} tags must balance. -You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to insert an -@samp{\end} tag which matches the last unmatched @samp{\begin}. It -also indents the @samp{\end} to match the corresponding @samp{\begin}, -and inserts a newline after the @samp{\end} tag if point is at the -beginning of a line. The minor mode @code{latex-electric-env-pair-mode} -automatically inserts an @samp{\end} or @samp{\begin} tag for you -when you type the corresponding one. - -@node TeX Print -@subsection @TeX{} Printing Commands - - You can invoke @TeX{} as an subprocess of Emacs, supplying either -the entire contents of the buffer or just part of it (e.g.@: one -chapter of a larger document). - -@table @kbd -@item C-c C-b -Invoke @TeX{} on the entire current buffer (@code{tex-buffer}). -@item C-c C-r -Invoke @TeX{} on the current region, together with the buffer's header -(@code{tex-region}). -@item C-c C-f -Invoke @TeX{} on the current file (@code{tex-file}). - -@item C-c C-v -Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c -C-f} command (@code{tex-view}). - -@item C-c C-p -Print the output from the last @kbd{C-c C-b}, @kbd{C-c C-r}, or -@kbd{C-c C-f} command (@code{tex-print}). - -@item C-c @key{TAB} -Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}). -@item C-c C-l -Recenter the window showing output from @TeX{} so that the last line -can be seen (@code{tex-recenter-output-buffer}). -@item C-c C-k -Kill the @TeX{} subprocess (@code{tex-kill-job}). -@item C-c C-c -Invoke some other compilation command on the entire current buffer -(@code{tex-compile}). -@end table - -@findex tex-buffer -@kindex C-c C-b @r{(@TeX{} mode)} -@findex tex-view -@kindex C-c C-v @r{(@TeX{} mode)} -@findex tex-print -@kindex C-c C-p @r{(@TeX{} mode)} - To pass the current buffer through @TeX{}, type @kbd{C-c C-b} -(@code{tex-buffer}). The formatted output goes in a temporary file, -normally a @file{.dvi} file. Afterwards, you can type @kbd{C-c C-v} -(@code{tex-view}) to launch an external program, such as -@command{xdvi}, to view this output file. You can also type @kbd{C-c -C-p} (@code{tex-print}) to print a hardcopy of the output file. - -@cindex @env{TEXINPUTS} environment variable -@vindex tex-directory - By default, @kbd{C-c C-b} runs @TeX{} in the current directory. The -output of @TeX{} also goes in this directory. To run @TeX{} in a -different directory, change the variable @code{tex-directory} to the -desired directory name. If your environment variable @env{TEXINPUTS} -contains relative directory names, or if your files contains -@samp{\input} commands with relative file names, then -@code{tex-directory} @emph{must} be @code{"."} or you will get the -wrong results. Otherwise, it is safe to specify some other directory, -such as @code{"/tmp"}. - -@vindex tex-run-command -@vindex latex-run-command -@vindex tex-dvi-view-command -@vindex tex-dvi-print-command - The buffer's @TeX{} variant determines what shell command @kbd{C-c -C-b} actually runs. In Plain @TeX{} mode, it is specified by the -variable @code{tex-run-command}, which defaults to @code{"tex"}. In -La@TeX{} mode, it is specified by @code{latex-run-command}, which -defaults to @code{"latex"}. The shell command that @kbd{C-c C-v} runs -to view the @file{.dvi} output is determined by the variable -@code{tex-dvi-view-command}, regardless of the @TeX{} variant. The -shell command that @kbd{C-c C-p} runs to print the output is -determined by the variable @code{tex-dvi-print-command}. - - Normally, Emacs automatically appends the output file name to the -shell command strings described in the preceding paragraph. For -example, if @code{tex-dvi-view-command} is @code{"xdvi"}, @kbd{C-c -C-v} runs @command{xdvi @var{output-file-name}}. In some cases, -however, the file name needs to be embedded in the command, e.g.@: if -you need to provide the file name as an argument to one command whose -output is piped to another. You can specify where to put the file -name with @samp{*} in the command string. For example, - -@example -(setq tex-dvi-print-command "dvips -f * | lpr") -@end example - -@findex tex-kill-job -@kindex C-c C-k @r{(@TeX{} mode)} -@findex tex-recenter-output-buffer -@kindex C-c C-l @r{(@TeX{} mode)} - The terminal output from @TeX{}, including any error messages, -appears in a buffer called @file{*tex-shell*}. If @TeX{} gets an -error, you can switch to this buffer and feed it input (this works as -in Shell mode; @pxref{Interactive Shell}). Without switching to this -buffer you can scroll it so that its last line is visible by typing -@kbd{C-c C-l}. - - Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if -you see that its output is no longer useful. Using @kbd{C-c C-b} or -@kbd{C-c C-r} also kills any @TeX{} process still running. - -@findex tex-region -@kindex C-c C-r @r{(@TeX{} mode)} - You can also pass an arbitrary region through @TeX{} by typing -@kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because -most files of @TeX{} input contain commands at the beginning to set -parameters and define macros, without which no later part of the file -will format correctly. To solve this problem, @kbd{C-c C-r} allows -you to designate a part of the file as containing essential commands; -it is included before the specified region as part of the input to -@TeX{}. The designated part of the file is called the @dfn{header}. - -@cindex header (@TeX{} mode) - To indicate the bounds of the header in Plain @TeX{} mode, you insert two -special strings in the file. Insert @samp{%**start of header} before the -header, and @samp{%**end of header} after it. Each string must appear -entirely on one line, but there may be other text on the line before or -after. The lines containing the two strings are included in the header. -If @samp{%**start of header} does not appear within the first 100 lines of -the buffer, @kbd{C-c C-r} assumes that there is no header. - - In La@TeX{} mode, the header begins with @samp{\documentclass} or -@samp{\documentstyle} and ends with @samp{\begin@{document@}}. These -are commands that La@TeX{} requires you to use in any case, so nothing -special needs to be done to identify the header. - -@findex tex-file -@kindex C-c C-f @r{(@TeX{} mode)} - The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their -work in a temporary directory, and do not have available any of the auxiliary -files needed by @TeX{} for cross-references; these commands are generally -not suitable for running the final copy in which all of the cross-references -need to be correct. - - When you want the auxiliary files for cross references, use @kbd{C-c -C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file, -in that file's directory. Before running @TeX{}, it offers to save any -modified buffers. Generally, you need to use (@code{tex-file}) twice to -get the cross-references right. - -@vindex tex-start-options - The value of the variable @code{tex-start-options} specifies -options for the @TeX{} run. - -@vindex tex-start-commands - The value of the variable @code{tex-start-commands} specifies @TeX{} -commands for starting @TeX{}. The default value causes @TeX{} to run -in nonstop mode. To run @TeX{} interactively, set the variable to -@code{""}. - -@vindex tex-main-file - Large @TeX{} documents are often split into several files---one main -file, plus subfiles. Running @TeX{} on a subfile typically does not -work; you have to run it on the main file. In order to make -@code{tex-file} useful when you are editing a subfile, you can set the -variable @code{tex-main-file} to the name of the main file. Then -@code{tex-file} runs @TeX{} on that file. - - The most convenient way to use @code{tex-main-file} is to specify it -in a local variable list in each of the subfiles. @xref{File -Variables}. - -@findex tex-bibtex-file -@kindex C-c TAB @r{(@TeX{} mode)} -@vindex tex-bibtex-command - For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary -file for the current buffer's file. Bib@TeX{} looks up bibliographic -citations in a data base and prepares the cited references for the -bibliography section. The command @kbd{C-c @key{TAB}} -(@code{tex-bibtex-file}) runs the shell command -(@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the -current buffer's file. Generally, you need to do @kbd{C-c C-f} -(@code{tex-file}) once to generate the @samp{.aux} file, then do -@kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f} -(@code{tex-file}) twice more to get the cross-references correct. - -@findex tex-compile -@kindex C-c C-c @r{(@TeX{} mode)} - To invoke some other compilation program on the current @TeX{} -buffer, type @kbd{C-c C-c} (@code{tex-compile}). This command knows -how to pass arguments to many common programs, including -@file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}. You can -select your desired compilation program using the standard completion -keys (@pxref{Completion}). - -@node TeX Misc -@subsection @TeX{} Mode Miscellany - -@vindex tex-shell-hook -@vindex tex-mode-hook -@vindex latex-mode-hook -@vindex slitex-mode-hook -@vindex plain-tex-mode-hook - Entering any variant of @TeX{} mode runs the hooks -@code{text-mode-hook} and @code{tex-mode-hook}. Then it runs either -@code{plain-tex-mode-hook}, @code{latex-mode-hook}, or -@code{slitex-mode-hook}, whichever is appropriate. Starting the -@TeX{} shell runs the hook @code{tex-shell-hook}. @xref{Hooks}. - -@findex iso-iso2tex -@findex iso-tex2iso -@findex iso-iso2gtex -@findex iso-gtex2iso -@cindex Latin-1 @TeX{} encoding -@cindex @TeX{} encoding - The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x -iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert -between Latin-1 encoded files and @TeX{}-encoded equivalents. - -@node HTML Mode -@section SGML and HTML Modes -@cindex SGML mode -@cindex HTML mode -@cindex mode, SGML -@cindex mode, HTML -@findex sgml-mode -@findex html-mode - - The major modes for SGML and HTML provide indentation support and -commands for operating on tags. HTML mode is a slightly customized -variant of SGML mode. - -@table @kbd -@item C-c C-n -@kindex C-c C-n @r{(SGML mode)} -@findex sgml-name-char -Interactively specify a special character and insert the SGML -@samp{&}-command for that character (@code{sgml-name-char}). - -@item C-c C-t -@kindex C-c C-t @r{(SGML mode)} -@findex sgml-tag -Interactively specify a tag and its attributes (@code{sgml-tag}). -This command asks you for a tag name and for the attribute values, -then inserts both the opening tag and the closing tag, leaving point -between them. - -With a prefix argument @var{n}, the command puts the tag around the -@var{n} words already present in the buffer after point. Whenever a -region is active, it puts the tag around the region (when Transient -Mark mode is off, it does this when a numeric argument of @minus{}1 is -supplied.) - -@item C-c C-a -@kindex C-c C-a @r{(SGML mode)} -@findex sgml-attributes -Interactively insert attribute values for the current tag -(@code{sgml-attributes}). - -@item C-c C-f -@kindex C-c C-f @r{(SGML mode)} -@findex sgml-skip-tag-forward -Skip across a balanced tag group (which extends from an opening tag -through its corresponding closing tag) (@code{sgml-skip-tag-forward}). -A numeric argument acts as a repeat count. - -@item C-c C-b -@kindex C-c C-b @r{(SGML mode)} -@findex sgml-skip-tag-backward -Skip backward across a balanced tag group (which extends from an -opening tag through its corresponding closing tag) -(@code{sgml-skip-tag-backward}). A numeric argument acts as a repeat -count. - -@item C-c C-d -@kindex C-c C-d @r{(SGML mode)} -@findex sgml-delete-tag -Delete the tag at or after point, and delete the matching tag too -(@code{sgml-delete-tag}). If the tag at or after point is an opening -tag, delete the closing tag too; if it is a closing tag, delete the -opening tag too. - -@item C-c ? @var{tag} @key{RET} -@kindex C-c ? @r{(SGML mode)} -@findex sgml-tag-help -Display a description of the meaning of tag @var{tag} -(@code{sgml-tag-help}). If the argument @var{tag} is empty, describe -the tag at point. - -@item C-c / -@kindex C-c / @r{(SGML mode)} -@findex sgml-close-tag -Insert a close tag for the innermost unterminated tag -(@code{sgml-close-tag}). If called within a tag or a comment, -close it instead of inserting a close tag. - -@item C-c 8 -@kindex C-c 8 @r{(SGML mode)} -@findex sgml-name-8bit-mode -Toggle a minor mode in which Latin-1 characters insert the -corresponding SGML commands that stand for them, instead of the -characters themselves (@code{sgml-name-8bit-mode}). - -@item C-c C-v -@kindex C-c C-v @r{(SGML mode)} -@findex sgml-validate -Run a shell command (which you must specify) to validate the current -buffer as SGML (@code{sgml-validate}). - -@item C-c TAB -@kindex C-c TAB @r{(SGML mode)} -@findex sgml-tags-invisible -Toggle the visibility of existing tags in the buffer. This can be -used as a cheap preview (@code{sgml-tags-invisible}). -@end table - -@cindex nXML mode -@cindex mode, nXML -@findex nxml-mode -@cindex XML schema - The major mode for editing XML documents is called nXML mode. This -is a powerful major mode that can recognize many existing XML schema -and use them to provide completion of XML elements via -@kbd{C-@key{RET}} or @kbd{M-@key{TAB}}, as well as ``on-the-fly'' XML -validation with error highlighting. To enable nXML mode in an -existing buffer, type @kbd{M-x nxml-mode}, or, equivalently, @kbd{M-x -xml-mode}. Emacs uses nXML mode for files which have the extension -@file{.xml}. For XHTML files, which have the extension @file{.xhtml}, -Emacs uses HTML mode by default; you can make it use nXML mode by -customizing the variable @code{auto-mode-alist} (@pxref{Choosing -Modes}). -@ifinfo -nXML mode is described in its own manual: @xref{Top, nXML -Mode,,nxml-mode, nXML Mode}. -@end ifinfo -@ifnotinfo -nXML mode is described in an Info manual, which is distributed with -Emacs. -@end ifnotinfo - -@vindex sgml-xml-mode - You may choose to use the less powerful SGML mode for editing XML, -since XML is a strict subset of SGML. To enable SGML mode in an -existing buffer, type @kbd{M-x sgml-mode}. On enabling SGML mode, -Emacs examines the buffer to determine whether it is XML; if so, it -sets the variable @code{sgml-xml-mode} to a non-@code{nil} value. -This causes SGML mode's tag insertion commands, described above, to -always insert explicit closing tags as well. - -@node Nroff Mode -@section Nroff Mode - -@cindex nroff -@findex nroff-mode -@vindex nroff-mode-hook - Nroff mode, a major mode derived from Text mode, is -specialized for editing nroff files (e.g.@: Unix man pages). Type -@kbd{M-x nroff-mode} to enter this mode. Entering Nroff mode runs the -hook @code{text-mode-hook}, then @code{nroff-mode-hook} -(@pxref{Hooks}). - - In Nroff mode, nroff command lines are treated as paragraph -separators, pages are separated by @samp{.bp} commands, and comments -start with backslash-doublequote. It also defines these commands: - -@findex forward-text-line -@findex backward-text-line -@findex count-text-lines -@kindex M-n @r{(Nroff mode)} -@kindex M-p @r{(Nroff mode)} -@kindex M-? @r{(Nroff mode)} -@table @kbd -@item M-n -Move to the beginning of the next line that isn't an nroff command -(@code{forward-text-line}). An argument is a repeat count. -@item M-p -Like @kbd{M-n} but move up (@code{backward-text-line}). -@item M-? -Displays in the echo area the number of text lines (lines that are not -nroff commands) in the region (@code{count-text-lines}). -@end table - -@findex electric-nroff-mode - Electric Nroff mode is a buffer-local minor mode that can be used -with Nroff mode. To toggle this minor mode, type @kbd{M-x -electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each -time you type @key{RET} to end a line containing an nroff command that -opens a kind of grouping, the nroff command to close that grouping is -automatically inserted on the following line. - - If you use Outline minor mode with Nroff mode (@pxref{Outline -Mode}), heading lines are lines of the form @samp{.H} followed by a -number (the header level). - -@node Enriched Text -@section Enriched Text -@cindex Enriched mode -@cindex mode, Enriched -@cindex enriched text -@cindex WYSIWYG -@cindex word processing -@cindex text/enriched MIME format - - Enriched mode is a minor mode for editing formatted text files in a -WYSIWYG (``what you see is what you get'') fashion. When Enriched -mode is enabled, you can apply various formatting properties to the -text in the buffer, such as fonts and colors; upon saving the buffer, -those properties are saved together with the text, using the MIME -@samp{text/enriched} file format. - - Enriched mode is typically used with Text mode (@pxref{Text Mode}). -It is @emph{not} compatible with Font Lock mode, which is used by many -major modes, including most programming language modes, for syntax -highlighting (@pxref{Font Lock}). Unlike Enriched mode, Font Lock -mode assigns text properties automatically, based on the current -buffer contents; those properties are not saved to disk. - - The file @file{etc/enriched.doc} in the Emacs distribution serves as -an example of the features of Enriched mode. - -@menu -* Enriched Mode:: Entering and exiting Enriched mode. -* Hard and Soft Newlines:: There are two different kinds of newlines. -* Editing Format Info:: How to edit text properties. -* Enriched Faces:: Bold, italic, underline, etc. -* Enriched Indentation:: Changing the left and right margins. -* Enriched Justification:: Centering, setting text flush with the - left or right margin, etc. -* Enriched Properties:: The "special" text properties submenu. -@end menu - -@node Enriched Mode -@subsection Enriched Mode - - Enriched mode is a buffer-local minor mode (@pxref{Minor Modes}). -When you visit a file that has been saved in the @samp{text/enriched} -format, Emacs automatically enables Enriched mode, and applies the -formatting information in the file to the buffer text. When you save -a buffer with Enriched mode enabled, it is saved using the -@samp{text/enriched} format, including the formatting information. - -@findex enriched-mode - To create a new file of formatted text, visit the nonexistent file -and type @kbd{M-x enriched-mode}. This command actually toggles -Enriched mode. With a prefix argument, it enables Enriched mode if -the argument is positive, and disables Enriched mode otherwise. If -you disable Enriched mode, Emacs no longer saves the buffer using the -@samp{text/enriched} format; any formatting properties that have been -added to the buffer remain in the buffer, but they are not saved to -disk. - -@vindex enriched-translations - Enriched mode does not save all Emacs text properties, only those -specified in the variable @code{enriched-translations}. These include -properties for fonts, colors, indentation, and justification. - -@findex format-decode-buffer - If you visit a file and Emacs fails to recognize that it is in the -@samp{text/enriched} format, type @kbd{M-x format-decode-buffer}. -This command prompts for a file format, and re-reads the file in that -format. Specifying the @samp{text/enriched} format automatically -enables Enriched mode. - - To view a @samp{text/enriched} file in raw form (as plain text with -markup tags rather than formatted text), use @kbd{M-x -find-file-literally} (@pxref{Visiting}). - - @xref{Format Conversion,, Format Conversion, elisp, the Emacs Lisp -Reference Manual}, for details of how Emacs recognizes and converts -file formats like @samp{text/enriched}. @xref{Text Properties,,, -elisp, the Emacs Lisp Reference Manual}, for more information about -text properties. - -@node Hard and Soft Newlines -@subsection Hard and Soft Newlines -@cindex hard newline -@cindex soft newline -@cindex newlines, hard and soft - -@cindex use-hard-newlines - In Enriched mode, Emacs distinguishes between two different kinds of -newlines, @dfn{hard} newlines and @dfn{soft} newlines. You can also -enable or disable this feature in other buffers, by typing @kbd{M-x -use-hard-newlines}. - - Hard newlines are used to separate paragraphs, or anywhere there -needs to be a line break regardless of how the text is filled; soft -newlines are used for filling. The @key{RET} (@code{newline}) and -@kbd{C-o} (@code{open-line}) commands insert hard newlines. The fill -commands, including Auto Fill (@pxref{Auto Fill}), insert only soft -newlines and delete only soft newlines, leaving hard newlines alone. - - Thus, when editing with Enriched mode, you should not use @key{RET} -or @kbd{C-o} to break lines in the middle of filled paragraphs. Use -Auto Fill mode or explicit fill commands (@pxref{Fill Commands}) -instead. Use @key{RET} or @kbd{C-o} where line breaks should always -remain, such as in tables and lists. For such lines, you may also -want to set the justification style to @code{unfilled} -(@pxref{Enriched Justification}). - -@node Editing Format Info -@subsection Editing Format Information - - The easiest way to alter properties is with the Text Properties -menu. You can get to this menu from the Edit menu in the menu bar -(@pxref{Menu Bar}), or with @kbd{C-Mouse-2} (@pxref{Menu Mouse -Clicks}). Some of the commands in the Text Properties menu are listed -below (you can also invoke them with @kbd{M-x}): - -@table @code -@findex facemenu-remove-face-props -@item Remove Face Properties -Remove face properties from the region -(@code{facemenu-remove-face-props}). - -@findex facemenu-remove-all -@item Remove Text Properties -Remove all text properties from the region, including face properties -(@code{facemenu-remove-all}). - -@findex describe-text-properties -@cindex text properties of characters -@cindex overlays at character position -@cindex widgets at buffer position -@cindex buttons at buffer position -@item Describe Properties -List all text properties and other information about the character -following point (@code{describe-text-properties}). - -@item Display Faces -Display a list of defined faces (@code{list-faces-display}). -@xref{Faces}. - -@item Display Colors -Display a list of defined colors (@code{list-colors-display}). -@xref{Colors}. -@end table - -@noindent -The other menu entries are described in the following sections. - -@node Enriched Faces -@subsection Faces in Enriched Text - - The following commands can be used to add or remove faces -(@pxref{Faces}). Each applies to the text in the region if the mark -is active, and to the next self-inserting character if the mark is -inactive. With a prefix argument, each command applies to the next -self-inserting character even if the region is active. - -@table @kbd -@kindex M-o d @r{(Enriched mode)} -@findex facemenu-set-default -@item M-o d -Remove all @code{face} properties (@code{facemenu-set-default}). - -@kindex M-o b @r{(Enriched mode)} -@findex facemenu-set-bold -@item M-o b -Apply the @code{bold} face (@code{facemenu-set-bold}). - -@kindex M-o i @r{(Enriched mode)} -@findex facemenu-set-italic -@item M-o i -Apply the @code{italic} face (@code{facemenu-set-italic}). - -@kindex M-o l @r{(Enriched mode)} -@findex facemenu-set-bold-italic -@item M-o l -Apply the @code{bold-italic} face (@code{facemenu-set-bold-italic}). - -@kindex M-o u @r{(Enriched mode)} -@findex facemenu-set-underline -@item M-o u -Apply the @code{underline} face (@code{facemenu-set-underline}). - -@kindex M-o o @r{(Enriched mode)} -@findex facemenu-set-face -@item M-o o @var{face} @key{RET} -Apply the face @var{face} (@code{facemenu-set-face}). - -@findex facemenu-set-foreground -@item M-x facemenu-set-foreground -Prompt for a color (@pxref{Colors}), and apply it as a foreground -color. - -@findex facemenu-set-background -@item M-x facemenu-set-background -Prompt for a color, and apply it as a background color. -@end table - -@noindent -These command are also available via the Text Properties menu. - - A self-inserting character normally inherits the face properties -(and most other text properties) from the preceding character in the -buffer. If you use one of the above commands to specify the face for -the next self-inserting character, that character will not inherit the -faces properties from the preceding character, but it will still -inherit other text properties. - - Enriched mode defines two additional faces: @code{excerpt} and -@code{fixed}. These correspond to codes used in the text/enriched -file format. The @code{excerpt} face is intended for quotations; by -default, it appears the same as @code{italic}. The @code{fixed} face -specifies fixed-width text; by default, it appears the same as -@code{bold}. - -@node Enriched Indentation -@subsection Indentation in Enriched Text - - In Enriched mode, you can specify different amounts of indentation -for the right or left margin of a paragraph or a part of a paragraph. -These margins also affect fill commands such as @kbd{M-q} -(@pxref{Filling}). - - The Indentation submenu of Text Properties offers commands -for specifying indentation: - -@table @code -@kindex C-x TAB @r{(Enriched mode)} -@findex increase-left-margin -@item Indent More -Indent the region by 4 columns (@code{increase-left-margin}). In -Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if -you supply a numeric argument, that says how many columns to add to the -margin (a negative argument reduces the number of columns). - -@item Indent Less -Remove 4 columns of indentation from the region. - -@item Indent Right More -Make the text narrower by indenting 4 columns at the right margin. - -@item Indent Right Less -Remove 4 columns of indentation from the right margin. -@end table - -@vindex standard-indent - The variable @code{standard-indent} specifies how many columns these -commands should add to or subtract from the indentation. The default -value is 4. The default right margin for Enriched mode is controlled -by the variable @code{fill-column}, as usual. - -@kindex C-c [ @r{(Enriched mode)} -@kindex C-c ] @r{(Enriched mode)} -@findex set-left-margin -@findex set-right-margin - You can also type @kbd{C-c [} (@code{set-left-margin}) and @kbd{C-c -]} (@code{set-right-margin}) to set the left and right margins. You -can specify the margin width with a numeric argument; otherwise these -commands prompt for a value via the minibuffer. - - The fill prefix, if any, works in addition to the specified paragraph -indentation: @kbd{C-x .} does not include the specified indentation's -whitespace in the new value for the fill prefix, and the fill commands -look for the fill prefix after the indentation on each line. @xref{Fill -Prefix}. - -@node Enriched Justification -@subsection Justification in Enriched Text - - In Enriched mode, you can use the following commands to specify -various @dfn{justification styles} for filling. These commands apply -to the paragraph containing point, or, if the region is active, to all -paragraphs overlapping the region. - -@table @kbd -@kindex M-j l @r{(Enriched mode)} -@findex set-justification-left -@item M-j l -Align lines to the left margin (@code{set-justification-left}). - -@kindex M-j r @r{(Enriched mode)} -@findex set-justification-right -@item M-j r -Align lines to the right margin (@code{set-justification-right}). - -@kindex M-j b @r{(Enriched mode)} -@findex set-justification-full -@item M-j b -Align lines to both margins, inserting spaces in the middle of the -line to achieve this (@code{set-justification-full}). - -@kindex M-j c @r{(Enriched mode)} -@kindex M-S @r{(Enriched mode)} -@findex set-justification-center -@item M-j c -@itemx M-S -Center lines between the margins (@code{set-justification-center}). - -@kindex M-j u @r{(Enriched mode)} -@findex set-justification-none -@item M-j u -Turn off filling entirely (@code{set-justification-none}). The fill -commands do nothing on text with this setting. You can, however, -still indent the left margin. -@end table - -@vindex default-justification - You can also specify justification styles using the Justification -submenu in the Text Properties menu. - The default justification style is specified by the per-buffer -variable @code{default-justification}. Its value should be one of the -symbols @code{left}, @code{right}, @code{full}, @code{center}, or -@code{none}. - -@node Enriched Properties -@subsection Setting Other Text Properties - - The Special Properties submenu of Text Properties has entries for -adding or removing three other text properties: @code{read-only}, -(which disallows alteration of the text), @code{invisible} (which -hides text), and @code{intangible} (which disallows moving point -within the text). The @samp{Remove Special} menu item removes all of -these special properties from the text in the region. - - The @code{invisible} and @code{intangible} properties are not saved -in the @samp{text/enriched} format. - -@node Text Based Tables -@section Editing Text-based Tables -@cindex table mode -@cindex text-based tables - - The @code{table} package provides commands to easily edit text-based -tables. Here is an example of what such a table looks like: - -@smallexample -@group -+-----------------+--------------------------------+-----------------+ -| Command | Description | Key Binding | -+-----------------+--------------------------------+-----------------+ -| forward-char |Move point right N characters | C-f | -| |(left if N is negative). | | -| | | | -+-----------------+--------------------------------+-----------------+ -| backward-char |Move point left N characters | C-b | -| |(right if N is negative). | | -| | | | -+-----------------+--------------------------------+-----------------+ -@end group -@end smallexample - - When Emacs recognizes such a stretch of text as a table -(@pxref{Table Recognition}), editing the contents of each table cell -will automatically resize the table, whenever the contents become too -large to fit in the cell. You can use the commands defined in the -following sections for navigating and editing the table layout. - -@findex table-fixed-width-mode - To toggle the automatic table resizing feature, type @kbd{M-x -table-fixed-width-mode}. - -@menu -* Table Definition:: What is a text based table. -* Table Creation:: How to create a table. -* Table Recognition:: How to activate and deactivate tables. -* Cell Commands:: Cell-oriented commands in a table. -* Cell Justification:: Justifying cell contents. -* Table Rows and Columns:: Inserting and deleting rows and columns. -* Table Conversion:: Converting between plain text and tables. -* Table Misc:: Table miscellany. -@end menu - -@node Table Definition -@subsection What is a Text-based Table? -@cindex cells, for text-based tables - - A @dfn{table} consists of a rectangular text area which is divided -into @dfn{cells}. Each cell must be at least one character wide and -one character high, not counting its border lines. A cell can be -subdivided into more cells, but they cannot overlap. - - Cell border lines are drawn with three special characters, specified -by the following variables: - -@table @code -@vindex table-cell-vertical-char -@item table-cell-vertical-char -The character used for vertical lines. The default is @samp{|}. - -@vindex table-cell-horizontal-chars -@item table-cell-horizontal-chars -The characters used for horizontal lines. The default is @samp{"-="}. - -@vindex table-cell-intersection-char -@item table-cell-intersection-char -The character used for the intersection of horizontal and vertical -lines. The default is @samp{+}. -@end table - -@noindent -The following are examples of @emph{invalid} tables: - -@example - +-----+ +--+ +-++--+ - | | | | | || | - | | | | | || | - +--+ | +--+--+ +-++--+ - | | | | | | +-++--+ - | | | | | | | || | - +--+--+ +--+--+ +-++--+ - a b c -@end example - -@noindent -From left to right: - -@enumerate a -@item -Overlapped cells or non-rectangular cells are not allowed. -@item -The border must be rectangular. -@item -Cells must have a minimum width/height of one character. -@end enumerate - -@node Table Creation -@subsection Creating a Table -@cindex create a text-based table -@cindex table creation - -@findex table-insert - To create a text-based table from scratch, type @kbd{M-x -table-insert}. This command prompts for the number of table columns, -the number of table rows, cell width and cell height. The cell width -and cell height do not include the cell borders; each can be specified -as a single integer (which means each cell is given the same -width/height), or as a sequence of integers separated by spaces or -commas (which specify the width/height of the individual table -columns/rows, counting from left to right for table columns and from -top to bottom for table rows). The specified table is then inserted -at point. - - The table inserted by @kbd{M-x table-insert} contains special text -properties, which tell Emacs to treat it specially as a text-based -table. If you save the buffer to a file and visit it again later, -those properties are lost, and the table appears to Emacs as an -ordinary piece of text. See the next section, for how to convert it -back into a table. - -@node Table Recognition -@subsection Table Recognition -@cindex table recognition - -@findex table-recognize -@findex table-unrecognize - Existing text-based tables in a buffer, which lack the special text -properties applied by @kbd{M-x table-insert}, are not treated -specially as tables. To apply those text properties, type @kbd{M-x -table-recognize}. This command scans the current buffer, -@dfn{recognizes} valid table cells, and applies the relevant text -properties. Conversely, type @kbd{M-x table-unrecognize} to -@dfn{unrecognize} all tables in the current buffer, removing the -special text properties and converting tables back to plain text. - - You can also use the following commands to selectively recognize or -unrecognize tables: - -@table @kbd -@findex table-recognize-region -@item M-x table-recognize-region -Recognize tables within the current region. - -@findex table-unrecognize-region -@item M-x table-unrecognize-region -Unrecognize tables within the current region. - -@findex table-recognize-table -@item M-x table-recognize-table -Recognize the table at point and activate it. - -@findex table-unrecognize-table -@item M-x table-unrecognize-table -Deactivate the table at point. - -@findex table-recognize-cell -@item M-x table-recognize-cell -Recognize the cell at point and activate it. - -@findex table-unrecognize-cell -@item M-x table-unrecognize-cell -Deactivate the cell at point. -@end table - - @xref{Table Conversion}, for another way to recognize a table. - -@node Cell Commands -@subsection Commands for Table Cells - -@findex table-forward-cell -@findex table-backward-cell - The commands @kbd{M-x table-forward-cell} and @kbd{M-x -table-backward-cell} move point from the current cell to an adjacent -cell. The order is cyclic: when point is in the last cell of a table, -@kbd{M-x table-forward-cell} moves to the first cell. Likewise, when -point is on the first cell, @kbd{M-x table-backward-cell} moves to the -last cell. - -@findex table-span-cell - @kbd{M-x table-span-cell} prompts for a direction---right, left, -above, or below---and merges the current cell with the adjacent cell -in that direction. This command signals an error if the merge would -result in an illegitimate cell layout. - -@findex table-split-cell -@findex table-split-cell-vertically -@findex table-split-cell-horizontally -@cindex text-based tables, splitting cells -@cindex splitting table cells - @kbd{M-x table-split-cell} splits the current cell vertically or -horizontally, prompting for the direction with the minibuffer. The -commands @kbd{M-x table-split-cell-vertically} and @kbd{M-x -table-split-cell-horizontally} split in a specific direction. When -splitting vertically, the old cell contents are automatically split -between the two new cells. When splitting horizontally, you are -prompted for how to divide the cell contents, if the cell is -non-empty; the options are @samp{split} (divide the contents at -point), @samp{left} (put all the contents in the left cell), and -@samp{right} (put all the contents in the right cell). - - The following commands enlarge or shrink a cell. By default, they -resize by one row or column; if a numeric argument is supplied, that -specifies the number of rows or columns to resize by. - -@table @kbd -@findex table-heighten-cell -@item M-x table-heighten-cell -Enlarge the current cell vertically. - -@findex table-shorten-cell -@item M-x table-shorten-cell -Shrink the current cell vertically. - -@findex table-widen-cell -@item M-x table-widen-cell -Enlarge the current cell horizontally. - -@findex table-narrow-cell -@item M-x table-narrow-cell -Shrink the current cell horizontally. -@end table - -@node Cell Justification -@subsection Cell Justification -@cindex justification in text-based tables - - The command @kbd{M-x table-justify} imposes @dfn{justification} on -one or more cells in a text-based table. Justification determines how -the text in the cell is aligned, relative to the edges of the cell. -Each cell in a table can be separately justified. - -@findex table-justify - @kbd{M-x table-justify} first prompts for what to justify; the -options are @samp{cell} (just the current cell), @samp{column} (all -cells in the current table column) and @samp{row} (all cells in the -current table row). The command then prompts for the justification -style; the options are @code{left}, @code{center}, @code{right}, -@code{top}, @code{middle}, @code{bottom}, or @code{none} (meaning no -vertical justification). - - Horizontal and vertical justification styles are specified -independently, and both types can be in effect simultaneously; for -instance, you can call @kbd{M-x table-justify} twice, once to specify -@code{right} justification and once to specify @code{bottom} -justification, to align the contents of a cell to the bottom right. - -@vindex table-detect-cell-alignment - The justification style is stored in the buffer as a text property, -and is lost when you kill the buffer or exit Emacs. However, the -table recognition commands, such as @kbd{M-x table-recognize} -(@pxref{Table Recognition}), attempt to determine and re-apply each -cell's justification style, by examining its contents. To disable -this feature, change the variable @code{table-detect-cell-alignment} -to @code{nil}. - -@node Table Rows and Columns -@subsection Table Rows and Columns -@cindex inserting rows and columns in text-based tables - -@findex table-insert-row - @kbd{M-x table-insert-row} inserts a row of cells before the current -table row. The current row, together with point, is pushed down past -the new row. To insert a row after the last row at the bottom of a -table, invoke this command with point below the table, just below the -bottom edge. You can insert more than one row at a time by using a -numeric prefix argument. - -@c A numeric prefix argument specifies the number of rows to insert. - -@findex table-insert-column - Similarly, @kbd{M-x table-insert-column} inserts a column of cells -to the left of the current table column. To insert a column to the -right side of the rightmost column, invoke this command with point to -the right of the rightmost column, outside the table. A numeric -prefix argument specifies the number of columns to insert. - -@cindex deleting rows and column in text-based tables - @kbd{M-x table-delete-column} deletes the column of cells at point. -Similarly, @kbd{M-x table-delete-row} deletes the row of cells at -point. A numeric prefix argument to either command specifies the -number of columns or rows to delete. - -@node Table Conversion -@subsection Converting Between Plain Text and Tables -@cindex text to table -@cindex table to text - -@findex table-capture - The command @kbd{M-x table-capture} captures plain text in a region -and turns it into a table. Unlike @kbd{M-x table-recognize} -(@pxref{Table Recognition}), the original text does not need to have a -table appearance; it only needs to have a logical table-like -structure. - - For example, suppose we have the following numbers, which are -divided into three lines and separated horizontally by commas: - -@example -1, 2, 3, 4 -5, 6, 7, 8 -, 9, 10 -@end example - -@noindent -Invoking @kbd{M-x table-capture} on that text produces this table: - -@example -+-----+-----+-----+-----+ -|1 |2 |3 |4 | -+-----+-----+-----+-----+ -|5 |6 |7 |8 | -+-----+-----+-----+-----+ -| |9 |10 | | -+-----+-----+-----+-----+ -@end example - -@findex table-release - @kbd{M-x table-release} does the opposite: it converts a table back -to plain text, removing its cell borders. - - One application of this pair of commands is to edit a text in -layout. Look at the following three paragraphs (the latter two are -indented with header lines): - -@example -table-capture is a powerful command. -Here are some things it can do: - -Parse Cell Items Using row and column delimiter regexps, - it parses the specified text area and - extracts cell items into a table. -@end example - -@noindent -Applying @code{table-capture} to a region containing the above text, -with empty strings for the column and row delimiter regexps, creates a -table with a single cell like the following one. - -@smallexample -@group -+----------------------------------------------------------+ -|table-capture is a powerful command. | -|Here are some things it can do: | -| | -|Parse Cell Items Using row and column delimiter regexps,| -| it parses the specified text area and | -| extracts cell items into a table. | -+----------------------------------------------------------+ -@end group -@end smallexample - -@noindent -We can then use the cell splitting commands (@pxref{Cell Commands}) to -subdivide the table so that each paragraph occupies a cell: - -@smallexample -+----------------------------------------------------------+ -|table-capture is a powerful command. | -|Here are some things it can do: | -+-----------------+----------------------------------------+ -|Parse Cell Items | Using row and column delimiter regexps,| -| | it parses the specified text area and | -| | extracts cell items into a table. | -+-----------------+----------------------------------------+ -@end smallexample - -@noindent -Each cell can now be edited independently without affecting the layout -of other cells. When finished, we can invoke @kbd{M-x table-release} -to convert the table back to plain text. - -@node Table Misc -@subsection Table Miscellany - -@cindex table dimensions -@findex table-query-dimension - The command @code{table-query-dimension} reports the layout of the -table and table cell at point. Here is an example of its output: - -@smallexample -Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5 -@end smallexample - -@noindent -This indicates that the current cell is 21 characters wide and 6 lines -high, the table is 67 characters wide and 16 lines high with 2 columns -and 3 rows, and a total of 5 cells. - -@findex table-insert-sequence - @kbd{M-x table-insert-sequence} inserts a string into each cell. -Each string is a part of a sequence i.e.@: a series of increasing -integer numbers. - -@cindex table for HTML and LaTeX -@findex table-generate-source - @kbd{M-x table-generate-source} generates a table formatted for a -specific markup language. It asks for a language (which must be one -of @code{html}, @code{latex}, or @code{cals}), a destination buffer in -which to put the result, and a table caption, and then inserts the -generated table into the specified buffer. The default destination -buffer is @code{table.@var{lang}}, where @var{lang} is the language -you specified. - -@node Two-Column -@section Two-Column Editing -@cindex two-column editing -@cindex splitting columns -@cindex columns, splitting - - Two-column mode lets you conveniently edit two side-by-side columns -of text. It uses two side-by-side windows, each showing its own -buffer. There are three ways to enter two-column mode: - -@table @asis -@item @kbd{@key{F2} 2} or @kbd{C-x 6 2} -@kindex F2 2 -@kindex C-x 6 2 -@findex 2C-two-columns -Enter two-column mode with the current buffer on the left, and on the -right, a buffer whose name is based on the current buffer's name -(@code{2C-two-columns}). If the right-hand buffer doesn't already -exist, it starts out empty; the current buffer's contents are not -changed. - -This command is appropriate when the current buffer is empty or contains -just one column and you want to add another column. - -@item @kbd{@key{F2} s} or @kbd{C-x 6 s} -@kindex F2 s -@kindex C-x 6 s -@findex 2C-split -Split the current buffer, which contains two-column text, into two -buffers, and display them side by side (@code{2C-split}). The current -buffer becomes the left-hand buffer, but the text in the right-hand -column is moved into the right-hand buffer. The current column -specifies the split point. Splitting starts with the current line and -continues to the end of the buffer. - -This command is appropriate when you have a buffer that already contains -two-column text, and you wish to separate the columns temporarily. - -@item @kbd{@key{F2} b @var{buffer} @key{RET}} -@itemx @kbd{C-x 6 b @var{buffer} @key{RET}} -@kindex F2 b -@kindex C-x 6 b -@findex 2C-associate-buffer -Enter two-column mode using the current buffer as the left-hand buffer, -and using buffer @var{buffer} as the right-hand buffer -(@code{2C-associate-buffer}). -@end table - - @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which -is a string that appears on each line between the two columns. You can -specify the width of the separator with a numeric argument to -@kbd{@key{F2} s}; that many characters, before point, constitute the -separator string. By default, the width is 1, so the column separator -is the character before point. - - When a line has the separator at the proper place, @kbd{@key{F2} s} -puts the text after the separator into the right-hand buffer, and -deletes the separator. Lines that don't have the column separator at -the proper place remain unsplit; they stay in the left-hand buffer, and -the right-hand buffer gets an empty line to correspond. (This is the -way to write a line that ``spans both columns while in two-column -mode'': write it in the left-hand buffer, and put an empty line in the -right-hand buffer.) - -@kindex F2 RET -@kindex C-x 6 RET -@findex 2C-newline - The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}} -(@code{2C-newline}) inserts a newline in each of the two buffers at -corresponding positions. This is the easiest way to add a new line to -the two-column text while editing it in split buffers. - -@kindex F2 1 -@kindex C-x 6 1 -@findex 2C-merge - When you have edited both buffers as you wish, merge them with -@kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the -text from the right-hand buffer as a second column in the other buffer. -To go back to two-column editing, use @kbd{@key{F2} s}. - -@kindex F2 d -@kindex C-x 6 d -@findex 2C-dissociate - Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers, -leaving each as it stands (@code{2C-dissociate}). If the other buffer, -the one not current when you type @kbd{@key{F2} d}, is empty, -@kbd{@key{F2} d} kills it. diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi deleted file mode 100644 index 3bbdecc0176..00000000000 --- a/doc/emacs/trouble.texi +++ /dev/null @@ -1,1113 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Dealing with Common Problems - - If you type an Emacs command you did not intend, the results are often -mysterious. This chapter tells what you can do to cancel your mistake or -recover from a mysterious situation. Emacs bugs and system crashes are -also considered. -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node Quitting -@section Quitting and Aborting -@cindex quitting - -@table @kbd -@item C-g -@itemx C-@key{BREAK} @r{(MS-DOS only)} -Quit: cancel running or partially typed command. -@item C-] -Abort innermost recursive editing level and cancel the command which -invoked it (@code{abort-recursive-edit}). -@item @key{ESC} @key{ESC} @key{ESC} -Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}). -@item M-x top-level -Abort all recursive editing levels that are currently executing. -@item C-/ -@itemx C-x u -@itemx C-_ -Cancel a previously made change in the buffer contents (@code{undo}). -@end table - - There are two ways of canceling a command before it has finished: -@dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} or -@kbd{M-x top-level}. Quitting cancels a partially typed command, or -one which is still running. Aborting exits a recursive editing level -and cancels the command that invoked the recursive edit -(@pxref{Recursive Edit}). - -@cindex quitting -@kindex C-g - Quitting with @kbd{C-g} is the way to get rid of a partially typed -command, or a numeric argument that you don't want. Furthermore, if -you are in the middle of a command that is running, @kbd{C-g} stops -the command in a relatively safe way. For example, if you quit out of -a kill command that is taking a long time, either your text will -@emph{all} still be in the buffer, or it will @emph{all} be in the -kill ring, or maybe both. If the region is active, @kbd{C-g} -deactivates the mark, unless Transient Mark mode is off -(@pxref{Disabled Transient Mark}). If you are in the middle of an -incremental search, @kbd{C-g} behaves specially; it may take two -successive @kbd{C-g} characters to get out of a search. -@xref{Incremental Search}, for details. - - On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character -like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to -recognize @kbd{C-g} while a command is running, between interactions -with the user. By contrast, it @emph{is} feasible to recognize -@kbd{C-@key{BREAK}} at all times. -@iftex -@xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{MS-DOS Keyboard}. -@end ifnottex - -@findex keyboard-quit - @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t} -the instant @kbd{C-g} is typed; Emacs Lisp checks this variable -frequently, and quits if it is non-@code{nil}. @kbd{C-g} is only -actually executed as a command if you type it while Emacs is waiting for -input. In that case, the command it runs is @code{keyboard-quit}. - - On a text terminal, if you quit with @kbd{C-g} a second time before -the first @kbd{C-g} is recognized, you activate the ``emergency -escape'' feature and return to the shell. @xref{Emergency Escape}. - -@cindex NFS and quitting - There are some situations where you cannot quit. When Emacs is -waiting for the operating system to do something, quitting is -impossible unless special pains are taken for the particular system -call within Emacs where the waiting occurs. We have done this for the -system calls that users are likely to want to quit from, but it's -possible you will encounter a case not handled. In one very common -case---waiting for file input or output using NFS---Emacs itself knows -how to quit, but many NFS implementations simply do not allow user -programs to stop waiting for NFS when the NFS server is hung. - -@cindex aborting recursive edit -@findex abort-recursive-edit -@kindex C-] - Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get -out of a recursive editing level and cancel the command which invoked -it. Quitting with @kbd{C-g} does not do this, and could not do this, -because it is used to cancel a partially typed command @emph{within} the -recursive editing level. Both operations are useful. For example, if -you are in a recursive edit and type @kbd{C-u 8} to enter a numeric -argument, you can cancel that argument with @kbd{C-g} and remain in the -recursive edit. - -@findex keyboard-escape-quit -@kindex ESC ESC ESC - The sequence @kbd{@key{ESC} @key{ESC} @key{ESC}} -(@code{keyboard-escape-quit}) can either quit or abort. (We defined -it this way because @key{ESC} means ``get out'' in many PC programs.) -It can cancel a prefix argument, clear a selected region, or get out -of a Query Replace, like @kbd{C-g}. It can get out of the minibuffer -or a recursive edit, like @kbd{C-]}. It can also get out of splitting -the frame into multiple windows, as with @kbd{C-x 1}. One thing it -cannot do, however, is stop a command that is running. That's because -it executes as an ordinary command, and Emacs doesn't notice it until -it is ready for the next command. - -@findex top-level - The command @kbd{M-x top-level} is equivalent to ``enough'' -@kbd{C-]} commands to get you out of all the levels of recursive edits -that you are in; it also exits the minibuffer if it is active. -@kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level} -goes out all levels at once. Both @kbd{C-]} and @kbd{M-x top-level} -are like all other commands, and unlike @kbd{C-g}, in that they take -effect only when Emacs is ready for a command. @kbd{C-]} is an -ordinary key and has its meaning only because of its binding in the -keymap. @xref{Recursive Edit}. - - @kbd{C-/} (@code{undo}) is not strictly speaking a way of canceling -a command, but you can think of it as canceling a command that already -finished executing. @xref{Undo}, for more information about the undo -facility. - -@node Lossage, Bugs, Quitting, Top -@section Dealing with Emacs Trouble - - This section describes how to recognize and deal with situations in -which Emacs does not work as you expect, such as keyboard code mixups, -garbled displays, running out of memory, and crashes and hangs. - - @xref{Bugs}, for what to do when you think you have found a bug in -Emacs. - -@menu -* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. -* Stuck Recursive:: `[...]' in mode line around the parentheses. -* Screen Garbled:: Garbage on the screen. -* Text Garbled:: Garbage in the text. -* Memory Full:: How to cope when you run out of memory. -* After a Crash:: Recovering editing in an Emacs session that crashed. -* Emergency Escape:: What to do if Emacs stops responding. -@end menu - -@node DEL Does Not Delete -@subsection If @key{DEL} Fails to Delete -@cindex @key{DEL} vs @key{BACKSPACE} -@cindex @key{BACKSPACE} vs @key{DEL} - - Every keyboard has a large key, usually labeled @key{Backspace}, -which is ordinarily used to erase the last character that you typed. -In Emacs, this key is supposed to be equivalent to @key{DEL}. - - When Emacs starts up on a graphical display, it determines -automatically which key should be @key{DEL}. In some unusual cases, -Emacs gets the wrong information from the system, and @key{Backspace} -ends up deleting forwards instead of backwards. - - Some keyboards also have a @key{Delete} key, which is ordinarily -used to delete forwards. If this key deletes backward in Emacs, that -too suggests Emacs got the wrong information---but in the opposite -sense. - - On a text terminal, if you find that @key{Backspace} prompts for a -Help command, like @kbd{Control-h}, instead of deleting a character, -it means that key is actually sending the @key{BS} character. Emacs -ought to be treating @key{BS} as @key{DEL}, but it isn't. - -@findex normal-erase-is-backspace-mode - In all of those cases, the immediate remedy is the same: use the -command @kbd{M-x normal-erase-is-backspace-mode}. This toggles -between the two modes that Emacs supports for handling @key{DEL}, so -if Emacs starts in the wrong mode, this should switch to the right -mode. On a text terminal, if you want to ask for help when @key{BS} -is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also work, if it -sends character code 127. - - To fix the problem in every Emacs session, put one of the following -lines into your initialization file (@pxref{Init File}). For the -first case above, where @key{Backspace} deletes forwards instead of -backwards, use this line to make @key{Backspace} act as @key{DEL}: - -@lisp -(normal-erase-is-backspace-mode 0) -@end lisp - -@noindent -For the other two cases, use this line: - -@lisp -(normal-erase-is-backspace-mode 1) -@end lisp - -@vindex normal-erase-is-backspace - Another way to fix the problem for every Emacs session is to -customize the variable @code{normal-erase-is-backspace}: the value -@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is -@key{DEL}, and @code{nil} specifies the other mode. @xref{Easy -Customization}. - -@node Stuck Recursive -@subsection Recursive Editing Levels - - Recursive editing levels are important and useful features of Emacs, but -they can seem like malfunctions if you do not understand them. - - If the mode line has square brackets @samp{[@dots{}]} around the -parentheses that contain the names of the major and minor modes, you -have entered a recursive editing level. If you did not do this on -purpose, or if you don't understand what that means, you should just -get out of the recursive editing level. To do so, type @kbd{M-x -top-level}. @xref{Recursive Edit}. - -@node Screen Garbled -@subsection Garbage on the Screen - - If the text on a text terminal looks wrong, the first thing to do is -see whether it is wrong in the buffer. Type @kbd{C-l} to redisplay -the entire screen. If the screen appears correct after this, the -problem was entirely in the previous screen update. (Otherwise, see -the following section.) - - Display updating problems often result from an incorrect terminfo -entry for the terminal you are using. The file @file{etc/TERMS} in -the Emacs distribution gives the fixes for known problems of this -sort. @file{INSTALL} contains general advice for these problems in -one of its sections. If you seem to be using the right terminfo -entry, it is possible that there is a bug in the terminfo entry, or a -bug in Emacs that appears for certain terminal types. - -@node Text Garbled -@subsection Garbage in the Text - - If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l} to -see what commands you typed to produce the observed results. Then try -undoing the changes step by step using @kbd{C-x u}, until it gets back -to a state you consider correct. - - If a large portion of text appears to be missing at the beginning or -end of the buffer, check for the word @samp{Narrow} in the mode line. -If it appears, the text you don't see is probably still present, but -temporarily off-limits. To make it accessible again, type @kbd{C-x n -w}. @xref{Narrowing}. - -@node Memory Full -@subsection Running out of Memory -@cindex memory full -@cindex out of memory - - If you get the error message @samp{Virtual memory exceeded}, save -your modified buffers with @kbd{C-x s}. This method of saving them -has the smallest need for additional memory. Emacs keeps a reserve of -memory which it makes available when this error happens; that should -be enough to enable @kbd{C-x s} to complete its work. When the -reserve has been used, @samp{!MEM FULL!} appears at the beginning of -the mode line, indicating there is no more reserve. - - Once you have saved your modified buffers, you can exit this Emacs -session and start another, or you can use @kbd{M-x kill-some-buffers} -to free space in the current Emacs job. If this frees up sufficient -space, Emacs will refill its memory reserve, and @samp{!MEM FULL!} -will disappear from the mode line. That means you can safely go on -editing in the same Emacs session. - - Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run -out of memory, because the buffer menu needs a fair amount of memory -itself, and the reserve supply may not be enough. - -@node After a Crash -@subsection Recovery After a Crash - - If Emacs or the computer crashes, you can recover the files you were -editing at the time of the crash from their auto-save files. To do -this, start Emacs again and type the command @kbd{M-x recover-session}. - - This command initially displays a buffer which lists interrupted -session files, each with its date. You must choose which session to -recover from. Typically the one you want is the most recent one. Move -point to the one you choose, and type @kbd{C-c C-c}. - - Then @code{recover-session} considers each of the files that you -were editing during that session; for each such file, it asks whether -to recover that file. If you answer @kbd{y} for a file, it shows the -dates of that file and its auto-save file, then asks once again -whether to recover that file. For the second question, you must -confirm with @kbd{yes}. If you do, Emacs visits the file but gets the -text from the auto-save file. - - When @code{recover-session} is done, the files you've chosen to -recover are present in Emacs buffers. You should then save them. Only -this---saving them---updates the files themselves. - - As a last resort, if you had buffers with content which were not -associated with any files, or if the autosave was not recent enough to -have recorded important changes, you can use the -@file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to -retrieve them from a core dump--provided that a core dump was saved, -and that the Emacs executable was not stripped of its debugging -symbols. - - As soon as you get the core dump, rename it to another name such as -@file{core.emacs}, so that another crash won't overwrite it. - - To use this script, run @code{gdb} with the file name of your Emacs -executable and the file name of the core dump, e.g. @samp{gdb -/usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the -recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}. -Then type the command @code{ybuffer-list} to see which buffers are -available. For each buffer, it lists a buffer number. To save a -buffer, use @code{ysave-buffer}; you specify the buffer number, and -the file name to write that buffer into. You should use a file name -which does not already exist; if the file does exist, the script does -not make a backup of its old contents. - -@node Emergency Escape -@subsection Emergency Escape - - On text terminals, the @dfn{emergency escape} feature suspends Emacs -immediately if you type @kbd{C-g} a second time before Emacs can -actually respond to the first one by quitting. This is so you can -always get out of GNU Emacs no matter how badly it might be hung. -When things are working properly, Emacs recognizes and handles the -first @kbd{C-g} so fast that the second one won't trigger emergency -escape. However, if some problem prevents Emacs from handling the -first @kbd{C-g} properly, then the second one will get you back to the -shell. - - When you resume Emacs after a suspension caused by emergency escape, -it asks two questions before going back to what it had been doing: - -@example -Auto-save? (y or n) -Abort (and dump core)? (y or n) -@end example - -@noindent -Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. - - Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of -all modified buffers in which auto-saving is enabled. Saying @kbd{n} -skips this. - - Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to -crash, dumping core. This is to enable a wizard to figure out why -Emacs was failing to quit in the first place. Execution does not -continue after a core dump. - - If you answer this question @kbd{n}, Emacs execution resumes. With -luck, Emacs will ultimately do the requested quit. If not, each -subsequent @kbd{C-g} invokes emergency escape again. - - If Emacs is not really hung, just slow, you may invoke the double -@kbd{C-g} feature without really meaning to. Then just resume and -answer @kbd{n} to both questions, and you will get back to the former -state. The quit you requested will happen by and by. - - Emergency escape is active only for text terminals. On graphical -displays, you can use the mouse to kill Emacs or switch to another -program. - - On MS-DOS, you must type @kbd{C-@key{BREAK}} (twice) to cause -emergency escape---but there are cases where it won't work, when -system call hangs or when Emacs is stuck in a tight loop in C code. - -@node Bugs, Contributing, Lossage, Top -@section Reporting Bugs - -@cindex bugs - If you think you have found a bug in Emacs, please report it. We -cannot promise to fix it, or always to agree that it is a bug, but we -certainly want to hear about it. The same applies for new features -you would like to see added. The following sections will help you to -construct an effective bug report. - -@menu -* Known Problems:: How to read about known problems and bugs. -* Criteria: Bug Criteria. Have you really found a bug? -* Understanding Bug Reporting:: How to report a bug effectively. -* Checklist:: Steps to follow for a good bug report. -* Sending Patches:: How to send a patch for GNU Emacs. -@end menu - -@node Known Problems -@subsection Reading Existing Bug Reports and Known Problems - - Before reporting a bug, if at all possible please check to see if it -is already known about. Indeed, it may already have been fixed in a -later release of Emacs, or in the development version. Here is a list -of the main places you can read about known issues: - -@itemize -@item -The @file{etc/PROBLEMS} file; type @kbd{C-h C-p} to read it. This -file contains a list of particularly well-known issues that have been -encountered in compiling, installing and running Emacs. Often, there -are suggestions for workarounds and solutions. - -@item -Some additional user-level problems can be found in @ref{Bugs and -problems, , Bugs and problems, efaq, GNU Emacs FAQ}. - -@cindex bug tracker -@item -The GNU Bug Tracker at @url{http://debbugs.gnu.org}. Emacs bugs are -filed in the tracker under the @samp{emacs} package. The tracker -records information about the status of each bug, the initial bug -report, and the follow-up messages by the bug reporter and Emacs -developers. You can search for bugs by subject, severity, and other -criteria. - -@cindex debbugs package -Instead of browsing the bug tracker as a webpage, you can browse it -from Emacs using the @code{debbugs} package, which can be downloaded -via the Package Menu (@pxref{Packages}). This package provides the -command @kbd{M-x debbugs-gnu} to list bugs, and @kbd{M-x -debbugs-gnu-search} to search for a specific bug. - -@item -The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup -@samp{gnu.emacs.bug}). You can read the list archives at -@url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. This list -works as a ``mirror'' of the Emacs bug reports and follow-up messages -which are sent to the bug tracker. It also contains old bug reports -from before the bug tracker was introduced (in early 2008). - -If you like, you can subscribe to the list. Be aware that its purpose -is to provide the Emacs maintainers with information about bugs and -feature requests, so reports may contain fairly large amounts of data; -spectators should not complain about this. - -@item -The @samp{emacs-pretest-bug} mailing list. This list is no longer -used, and is mainly of historical interest. At one time, it was used -for bug reports in development (i.e., not yet released) versions of -Emacs. You can read the archives for 2003 to mid 2007 at -@url{http://lists.gnu.org/archive/html/emacs-pretest-bug/}. Nowadays, -it is an alias for @samp{bug-gnu-emacs}. - -@item -The @samp{emacs-devel} mailing list. Sometimes people report bugs to -this mailing list. This is not the main purpose of the list, however, -and it is much better to send bug reports to the bug list. You should -not feel obliged to read this list before reporting a bug. - -@end itemize - - -@node Bug Criteria -@subsection When Is There a Bug - - If Emacs accesses an invalid memory location (``segmentation -fault''), or exits with an operating system error message that -indicates a problem in the program (as opposed to something like -``disk full''), then it is certainly a bug. - - If the Emacs display does not correspond properly to the contents of -the buffer, then it is a bug. But you should check that features like -buffer narrowing (@pxref{Narrowing}), which can hide parts of the -buffer or change how it is displayed, are not responsible. - - Taking forever to complete a command can be a bug, but you must make -sure that it is really Emacs's fault. Some commands simply take a -long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then -@kbd{C-h l} to see whether the input Emacs received was what you -intended to type; if the input was such that you @emph{know} it should -have been processed quickly, report a bug. If you don't know whether -the command should take a long time, find out by looking in the manual -or by asking for assistance. - - If a command you are familiar with causes an Emacs error message in a -case where its usual definition ought to be reasonable, it is probably a -bug. - - If a command does the wrong thing, that is a bug. But be sure you -know for certain what it ought to have done. If you aren't familiar -with the command, it might actually be working right. If in doubt, -read the command's documentation (@pxref{Name Help}). - - A command's intended definition may not be the best possible -definition for editing with. This is a very important sort of -problem, but it is also a matter of judgment. Also, it is easy to -come to such a conclusion out of ignorance of some of the existing -features. It is probably best not to complain about such a problem -until you have checked the documentation in the usual ways, feel -confident that you understand it, and know for certain that what you -want is not available. Ask other Emacs users, too. If you are not -sure what the command is supposed to do after a careful reading of the -manual, check the index and glossary for any terms that may be -unclear. - - If after careful rereading of the manual you still do not understand -what the command should do, that indicates a bug in the manual, which -you should report. The manual's job is to make everything clear to -people who are not Emacs experts---including you. It is just as -important to report documentation bugs as program bugs. - - If the built-in documentation for a function or variable disagrees -with the manual, one of them must be wrong; that is a bug. - -@node Understanding Bug Reporting -@subsection Understanding Bug Reporting - -@findex emacs-version - When you decide that there is a bug, it is important to report it -and to report it in a way which is useful. What is most useful is an -exact description of what commands you type, starting with the shell -command to run Emacs, until the problem happens. - - The most important principle in reporting a bug is to report -@emph{facts}. Hypotheses and verbal descriptions are no substitute -for the detailed raw data. Reporting the facts is straightforward, -but many people strain to posit explanations and report them instead -of the facts. If the explanations are based on guesses about how -Emacs is implemented, they will be useless; meanwhile, lacking the -facts, we will have no real information about the bug. If you want to -actually @emph{debug} the problem, and report explanations that are -more than guesses, that is useful---but please include the raw facts -as well. - - For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh -@key{RET}}, visiting a file which (you know) happens to be rather -large, and Emacs displays @samp{I feel pretty today}. The bug report -would need to provide all that information. You should not assume -that the problem is due to the size of the file and say, ``I visited a -large file, and Emacs displayed @samp{I feel pretty today}.'' This is -what we mean by ``guessing explanations''. The problem might be due -to the fact that there is a @samp{z} in the file name. If this is so, -then when we got your report, we would try out the problem with some -``large file'', probably with no @samp{z} in its name, and not see any -problem. There is no way we could guess that we should try visiting a -file with a @samp{z} in its name. - - You should not even say ``visit a file'' instead of @kbd{C-x C-f}. -Similarly, rather than saying ``if I have three characters on the -line'', say ``after I type @kbd{@key{RET} A B C @key{RET} C-p}'', if -that is the way you entered the text. - - If possible, try quickly to reproduce the bug by invoking Emacs with -@command{emacs -Q} (so that Emacs starts with no initial -customizations; @pxref{Initial Options}), and repeating the steps that -you took to trigger the bug. If you can reproduce the bug this way, -that rules out bugs in your personal customizations. Then your bug -report should begin by stating that you started Emacs with -@command{emacs -Q}, followed by the exact sequence of steps for -reproducing the bug. If possible, inform us of the exact contents of -any file that is needed to reproduce the bug. - - Some bugs are not reproducible from @command{emacs -Q}; some are not -easily reproducible at all. In that case, you should report what you -have---but, as before, please stick to the raw facts about what you -did to trigger the bug the first time. - -@node Checklist -@subsection Checklist for Bug Reports - -@cindex reporting bugs - - Before reporting a bug, first try to see if the problem has already -been reported (@pxref{Known Problems}). - -If you are able to, try the latest release of Emacs to see if the -problem has already been fixed. Even better is to try the latest -development version. We recognize that this is not easy for some -people, so do not feel that you absolutely must do this before making -a report. - -@findex report-emacs-bug - The best way to write a bug report for Emacs is to use the command -@kbd{M-x report-emacs-bug}. This sets up a mail buffer -(@pxref{Sending Mail}) and automatically inserts @emph{some} of the -essential information. However, it cannot supply all the necessary -information; you should still read and follow the guidelines below, so -you can enter the other crucial information by hand before you send -the message. You may feel that some of the information inserted by -@kbd{M-x report-emacs-bug} is not relevant, but unless you are -absolutely sure it is best to leave it, so that the developers can -decide for themselves. - -When you have finished writing your report, type @kbd{C-c C-c} and it -will be sent to the Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}. -(If you want to suggest an improvement or new feature, use the same -address.) If you cannot send mail from inside Emacs, you can copy the -text of your report to your normal mail client (if your system -supports it, you can type @kbd{C-c m} to have Emacs do this for you) -and send it to that address. Or you can simply send an email to that -address describing the problem. - -Your report will be sent to the @samp{bug-gnu-emacs} mailing list, and -stored in the GNU Bug Tracker at @url{http://debbugs.gnu.org}. Please -include a valid reply email address, in case we need to ask you for -more information about your report. Submissions are moderated, so -there may be a delay before your report appears. - -You do not need to know how the Gnu Bug Tracker works in order to -report a bug, but if you want to, you can read the tracker's online -documentation to see the various features you can use. - -All mail sent to the @samp{bug-gnu-emacs} mailing list is also -gatewayed to the @samp{gnu.emacs.bug} newsgroup. The reverse is also -true, but we ask you not to post bug reports (or replies) via the -newsgroup. It can make it much harder to contact you if we need to ask -for more information, and it does not integrate well with the bug -tracker. - -If your data is more than 500,000 bytes, please don't include it -directly in the bug report; instead, offer to send it on request, or -make it available by ftp and say where. - - To enable maintainers to investigate a bug, your report -should include all these things: - -@itemize @bullet -@item -The version number of Emacs. Without this, we won't know whether there is any -point in looking for the bug in the current version of GNU Emacs. - -@kbd{M-x report-emacs-bug} includes this information automatically, -but if you are not using that command for your report you can get the -version number by typing @kbd{M-x emacs-version @key{RET}}. If that -command does not work, you probably have something other than GNU -Emacs, so you will have to report the bug somewhere else. - -@item -The type of machine you are using, and the operating system name and -version number (again, automatically included by @kbd{M-x -report-emacs-bug}). @kbd{M-x emacs-version @key{RET}} provides this -information too. Copy its output from the @file{*Messages*} buffer, -so that you get it all and get it accurately. - -@item -The operands given to the @code{configure} command when Emacs was -installed (automatically included by @kbd{M-x report-emacs-bug}). - -@item -A complete list of any modifications you have made to the Emacs source. -(We may not have time to investigate the bug unless it happens in an -unmodified Emacs. But if you've made modifications and you don't tell -us, you are sending us on a wild goose chase.) - -Be precise about these changes. A description in English is not -enough---send a context diff for them. - -Adding files of your own, or porting to another machine, is a -modification of the source. - -@item -Details of any other deviations from the standard procedure for installing -GNU Emacs. - -@item -The complete text of any files needed to reproduce the bug. - - If you can tell us a way to cause the problem without visiting any files, -please do so. This makes it much easier to debug. If you do need files, -make sure you arrange for us to see their exact contents. For example, it -can matter whether there are spaces at the ends of lines, or a -newline after the last line in the buffer (nothing ought to care whether -the last line is terminated, but try telling the bugs that). - -@item -The precise commands we need to type to reproduce the bug. If at all -possible, give a full recipe for an Emacs started with the @samp{-Q} -option (@pxref{Initial Options}). This bypasses your personal -customizations. - -@findex open-dribble-file -@cindex dribble file -@cindex logging keystrokes -One way to record the input to Emacs precisely is to write a dribble -file. To start the file, use the @kbd{M-x open-dribble-file -@key{RET}} command. From then on, Emacs copies all your input to the -specified dribble file until the Emacs process is killed. - -@item -@findex open-termscript -@cindex termscript file -@cindex @env{TERM} environment variable -For possible display bugs, the terminal type (the value of environment -variable @env{TERM}), the complete termcap entry for the terminal from -@file{/etc/termcap} (since that file is not identical on all machines), -and the output that Emacs actually sent to the terminal. - -The way to collect the terminal output is to execute the Lisp expression - -@example -(open-termscript "~/termscript") -@end example - -@noindent -using @kbd{M-:} or from the @file{*scratch*} buffer just after -starting Emacs. From then on, Emacs copies all terminal output to the -specified termscript file as well, until the Emacs process is killed. -If the problem happens when Emacs starts up, put this expression into -your Emacs initialization file so that the termscript file will be -open when Emacs displays the screen for the first time. - -Be warned: it is often difficult, and sometimes impossible, to fix a -terminal-dependent bug without access to a terminal of the type that -stimulates the bug. - -@item -If non-@acronym{ASCII} text or internationalization is relevant, the locale that -was current when you started Emacs. On GNU/Linux and Unix systems, or -if you use a Posix-style shell such as Bash, you can use this shell -command to view the relevant values: - -@smallexample -echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \ - LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG -@end smallexample - -Alternatively, use the @command{locale} command, if your system has it, -to display your locale settings. - -You can use the @kbd{M-!} command to execute these commands from -Emacs, and then copy the output from the @file{*Messages*} buffer into -the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL -@key{RET}} will display the value of @code{LC_ALL} in the echo area, and -you can copy its output from the @file{*Messages*} buffer. - -@item -A description of what behavior you observe that you believe is -incorrect. For example, ``The Emacs process gets a fatal signal'', or, -``The resulting text is as follows, which I think is wrong.'' - -Of course, if the bug is that Emacs gets a fatal signal, then one can't -miss it. But if the bug is incorrect text, the maintainer might fail to -notice what is wrong. Why leave it to chance? - -Even if the problem you experience is a fatal signal, you should still -say so explicitly. Suppose something strange is going on, such as, your -copy of the source is out of sync, or you have encountered a bug in the -C library on your system. (This has happened!) Your copy might crash -and the copy here might not. If you @emph{said} to expect a crash, then -when Emacs here fails to crash, we would know that the bug was not -happening. If you don't say to expect a crash, then we would not know -whether the bug was happening---we would not be able to draw any -conclusion from our observations. - -@item -If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual -fails to describe the actual behavior of Emacs, or that the text is -confusing, copy in the text from the online manual which you think is -at fault. If the section is small, just the section name is enough. - -@item -If the manifestation of the bug is an Emacs error message, it is -important to report the precise text of the error message, and a -backtrace showing how the Lisp program in Emacs arrived at the error. - -To get the error message text accurately, copy it from the -@file{*Messages*} buffer into the bug report. Copy all of it, not just -part. - -@findex toggle-debug-on-error -@pindex Edebug -To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error} -before the error happens (that is to say, you must give that command -and then make the bug happen). This causes the error to start the Lisp -debugger, which shows you a backtrace. Copy the text of the -debugger's backtrace into the bug report. @xref{Debugger,, The Lisp -Debugger, elisp, the Emacs Lisp Reference Manual}, for information on -debugging Emacs Lisp programs with the Edebug package. - -This use of the debugger is possible only if you know how to make the -bug happen again. If you can't make it happen again, at least copy -the whole error message. - -@vindex debug-on-quit -If Emacs appears to be stuck in an infinite loop or in a very long -operation, typing @kbd{C-g} with the variable @code{debug-on-quit} -non-@code{nil} will start the Lisp debugger and show a backtrace. -This backtrace is useful for debugging such long loops, so if you can -produce it, copy it into the bug report. - -@vindex debug-on-event -If you cannot get Emacs to respond to @kbd{C-g} (e.g., because -@code{inhibit-quit} is set), then you can try sending the signal -specified by @code{debug-on-event} (default SIGUSR2) from outside -Emacs to cause it to enter the debugger. - -@item -Check whether any programs you have loaded into the Lisp world, -including your initialization file, set any variables that may affect -the functioning of Emacs. Also, see whether the problem happens in a -freshly started Emacs without loading your initialization file (start -Emacs with the @code{-Q} switch to prevent loading the init files). -If the problem does @emph{not} occur then, you must report the precise -contents of any programs that you must load into the Lisp world in -order to cause the problem to occur. - -@item -If the problem does depend on an init file or other Lisp programs that -are not part of the standard Emacs system, then you should make sure it -is not a bug in those programs by complaining to their maintainers -first. After they verify that they are using Emacs in a way that is -supposed to work, they should report the bug. - -@item -If you wish to mention something in the GNU Emacs source, show the line -of code with a few lines of context. Don't just give a line number. - -The line numbers in the development sources don't match those in your -sources. It would take extra work for the maintainers to determine what -code is in your version at a given line number, and we could not be -certain. - -@item -Additional information from a C debugger such as GDB might enable -someone to find a problem on a machine which he does not have available. -If you don't know how to use GDB, please read the GDB manual---it is not -very long, and using GDB is easy. You can find the GDB distribution, -including the GDB manual in online form, in most of the same places you -can find the Emacs distribution. To run Emacs under GDB, you should -switch to the @file{src} subdirectory in which Emacs was compiled, then -do @samp{gdb emacs}. It is important for the directory @file{src} to be -current so that GDB will read the @file{.gdbinit} file in this -directory. - -However, you need to think when you collect the additional information -if you want it to show what causes the bug. - -@cindex backtrace for bug reports -For example, many people send just a backtrace, but that is not very -useful by itself. A simple backtrace with arguments often conveys -little about what is happening inside GNU Emacs, because most of the -arguments listed in the backtrace are pointers to Lisp objects. The -numeric values of these pointers have no significance whatever; all that -matters is the contents of the objects they point to (and most of the -contents are themselves pointers). - -@findex debug_print -To provide useful information, you need to show the values of Lisp -objects in Lisp notation. Do this for each variable which is a Lisp -object, in several stack frames near the bottom of the stack. Look at -the source to see which variables are Lisp objects, because the debugger -thinks of them as integers. - -To show a variable's value in Lisp syntax, first print its value, then -use the user-defined GDB command @code{pr} to print the Lisp object in -Lisp syntax. (If you must use another debugger, call the function -@code{debug_print} with the object as an argument.) The @code{pr} -command is defined by the file @file{.gdbinit}, and it works only if you -are debugging a running process (not with a core dump). - -To make Lisp errors stop Emacs and return to GDB, put a breakpoint at -@code{Fsignal}. - -For a short listing of Lisp functions running, type the GDB -command @code{xbacktrace}. - -The file @file{.gdbinit} defines several other commands that are useful -for examining the data types and contents of Lisp objects. Their names -begin with @samp{x}. These commands work at a lower level than -@code{pr}, and are less convenient, but they may work even when -@code{pr} does not, such as when debugging a core dump or when Emacs has -had a fatal signal. - -@cindex debugging Emacs, tricks and techniques -More detailed advice and other useful techniques for debugging Emacs -are available in the file @file{etc/DEBUG} in the Emacs distribution. -That file also includes instructions for investigating problems -whereby Emacs stops responding (many people assume that Emacs is -``hung'', whereas in fact it might be in an infinite loop). - -To find the file @file{etc/DEBUG} in your Emacs installation, use the -directory name stored in the variable @code{data-directory}. -@end itemize - -Here are some things that are not necessary in a bug report: - -@itemize @bullet -@item -A description of the envelope of the bug---this is not necessary for a -reproducible bug. - -Often people who encounter a bug spend a lot of time investigating -which changes to the input file will make the bug go away and which -changes will not affect it. - -This is often time-consuming and not very useful, because the way we -will find the bug is by running a single example under the debugger -with breakpoints, not by pure deduction from a series of examples. -You might as well save time by not searching for additional examples. -It is better to send the bug report right away, go back to editing, -and find another bug to report. - -Of course, if you can find a simpler example to report @emph{instead} of -the original one, that is a convenience. Errors in the output will be -easier to spot, running under the debugger will take less time, etc. - -However, simplification is not vital; if you can't do this or don't have -time to try, please report the bug with your original test case. - -@item -A core dump file. - -Debugging the core dump might be useful, but it can only be done on -your machine, with your Emacs executable. Therefore, sending the core -dump file to the Emacs maintainers won't be useful. Above all, don't -include the core file in an email bug report! Such a large message -can be extremely inconvenient. - -@item -A system-call trace of Emacs execution. - -System-call traces are very useful for certain special kinds of -debugging, but in most cases they give little useful information. It is -therefore strange that many people seem to think that @emph{the} way to -report information about a crash is to send a system-call trace. Perhaps -this is a habit formed from experience debugging programs that don't -have source code or debugging symbols. - -In most programs, a backtrace is normally far, far more informative than -a system-call trace. Even in Emacs, a simple backtrace is generally -more informative, though to give full information you should supplement -the backtrace by displaying variable values and printing them as Lisp -objects with @code{pr} (see above). - -@item -A patch for the bug. - -A patch for the bug is useful if it is a good one. But don't omit the -other information that a bug report needs, such as the test case, on the -assumption that a patch is sufficient. We might see problems with your -patch and decide to fix the problem another way, or we might not -understand it at all. And if we can't understand what bug you are -trying to fix, or why your patch should be an improvement, we mustn't -install it. - -@ifnottex -@xref{Sending Patches}, for guidelines on how to make it easy for us to -understand and install your patches. -@end ifnottex - -@item -A guess about what the bug is or what it depends on. - -Such guesses are usually wrong. Even experts can't guess right about -such things without first using the debugger to find the facts. -@end itemize - -@node Sending Patches -@subsection Sending Patches for GNU Emacs - -@cindex sending patches for GNU Emacs -@cindex patches, sending - If you would like to write bug fixes or improvements for GNU Emacs, -that is very helpful. When you send your changes, please follow these -guidelines to make it easy for the maintainers to use them. If you -don't follow these guidelines, your information might still be useful, -but using it will take extra work. Maintaining GNU Emacs is a lot of -work in the best of circumstances, and we can't keep up unless you do -your best to help. - -@itemize @bullet -@item -Send an explanation with your changes of what problem they fix or what -improvement they bring about. For a fix for an existing bug, it is -best to reply to the relevant discussion on the @samp{bug-gnu-emacs} -list, or the bug entry in the GNU Bug Tracker at -@url{http://debbugs.gnu.org}. Explain why your change fixes the bug. - -@item -Always include a proper bug report for the problem you think you have -fixed. We need to convince ourselves that the change is right before -installing it. Even if it is correct, we might have trouble -understanding it if we don't have a way to reproduce the problem. - -@item -Include all the comments that are appropriate to help people reading the -source in the future understand why this change was needed. - -@item -Don't mix together changes made for different reasons. -Send them @emph{individually}. - -If you make two changes for separate reasons, then we might not want to -install them both. We might want to install just one. If you send them -all jumbled together in a single set of diffs, we have to do extra work -to disentangle them---to figure out which parts of the change serve -which purpose. If we don't have time for this, we might have to ignore -your changes entirely. - -If you send each change as soon as you have written it, with its own -explanation, then two changes never get tangled up, and we can consider -each one properly without any extra work to disentangle them. - -@item -Send each change as soon as that change is finished. Sometimes people -think they are helping us by accumulating many changes to send them all -together. As explained above, this is absolutely the worst thing you -could do. - -Since you should send each change separately, you might as well send it -right away. That gives us the option of installing it immediately if it -is important. - -@item -Use @samp{diff -c} to make your diffs. Diffs without context are hard -to install reliably. More than that, they are hard to study; we must -always study a patch to decide whether we want to install it. Unidiff -format is better than contextless diffs, but not as easy to read as -@samp{-c} format. - -If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when -making diffs of C code. This shows the name of the function that each -change occurs in. - -@item -Avoid any ambiguity as to which is the old version and which is the new. -Please make the old version the first argument to diff, and the new -version the second argument. And please give one version or the other a -name that indicates whether it is the old version or your new changed -one. - -@item -Write the change log entries for your changes. This is both to save us -the extra work of writing them, and to help explain your changes so we -can understand them. - -The purpose of the change log is to show people where to find what was -changed. So you need to be specific about what functions you changed; -in large functions, it's often helpful to indicate where within the -function the change was. - -On the other hand, once you have shown people where to find the change, -you need not explain its purpose in the change log. Thus, if you add a -new function, all you need to say about it is that it is new. If you -feel that the purpose needs explaining, it probably does---but put the -explanation in comments in the code. It will be more useful there. - -Please read the @file{ChangeLog} files in the @file{src} and -@file{lisp} directories to see what sorts of information to put in, -and to learn the style that we use. @xref{Change Log}. - -@item -When you write the fix, keep in mind that we can't install a change that -would break other systems. Please think about what effect your change -will have if compiled on another type of system. - -Sometimes people send fixes that @emph{might} be an improvement in -general---but it is hard to be sure of this. It's hard to install -such changes because we have to study them very carefully. Of course, -a good explanation of the reasoning by which you concluded the change -was correct can help convince us. - -The safest changes are changes to the configuration files for a -particular machine. These are safe because they can't create new bugs -on other machines. - -Please help us keep up with the workload by designing the patch in a -form that is clearly safe to install. -@end itemize - -@node Contributing, Service, Bugs, Top -@section Contributing to Emacs Development -@cindex contributing to Emacs - -If you would like to help pretest Emacs releases to assure they work -well, or if you would like to work on improving Emacs, please contact -the maintainers at @email{emacs-devel@@gnu.org}. A pretester -should be prepared to investigate bugs as well as report them. If you'd -like to work on improving Emacs, please ask for suggested projects or -suggest your own ideas. - -If you have already written an improvement, please tell us about it. If -you have not yet started work, it is useful to contact -@email{emacs-devel@@gnu.org} before you start; it might be -possible to suggest ways to make your extension fit in better with the -rest of Emacs. - -The development version of Emacs can be downloaded from the -repository where it is actively maintained by a group of developers. -See the Emacs project page -@url{http://savannah.gnu.org/projects/emacs/} for details. - -For more information on how to contribute, see the @file{etc/CONTRIBUTE} -file in the Emacs distribution. - -@node Service, Copying, Contributing, Top -@section How To Get Help with GNU Emacs - -If you need help installing, using or changing GNU Emacs, there are two -ways to find it: - -@itemize @bullet -@item -Send a message to the mailing list -@email{help-gnu-emacs@@gnu.org}, or post your request on -newsgroup @code{gnu.emacs.help}. (This mailing list and newsgroup -interconnect, so it does not matter which one you use.) - -@item -Look in the service directory for someone who might help you for a fee. -The service directory is found in the file named @file{etc/SERVICE} in the -Emacs distribution. -@end itemize - -@ifnottex -@lowersections -@end ifnottex diff --git a/doc/emacs/vc-xtra.texi b/doc/emacs/vc-xtra.texi deleted file mode 100644 index f04f939cced..00000000000 --- a/doc/emacs/vc-xtra.texi +++ /dev/null @@ -1,25 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included in emacs-xtra.texi when producing the printed -@c version. -@iftex -@node Advanced VC Usage -@section Advanced VC Usage - - Commonly used features of Emacs's version control (VC) support are -described in the main Emacs manual (@pxref{Version Control,,,emacs, -the Emacs Manual}). This chapter describes more advanced VC usage. - -@menu -* Remote Repositories:: Efficient access to remote VCS servers. -* Revision Tags:: Symbolic names for revisions. -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. -@end menu -@end iftex - -@iftex -@include vc1-xtra.texi -@end iftex diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi deleted file mode 100644 index cd5ed206dd6..00000000000 --- a/doc/emacs/vc1-xtra.texi +++ /dev/null @@ -1,447 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2012 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in vc-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). - -@node Miscellaneous VC -@subsection Miscellaneous Commands and Features of VC - - This section explains the less-frequently-used features of VC. - -@menu -* Change Logs and VC:: Generating a change log file from log entries. -* VC Delete/Rename:: Deleting and renaming version-controlled files. -* Revision Tags:: Symbolic names for revisions. -* Version Headers:: Inserting version control headers into working files. -@end menu - -@node Change Logs and VC -@subsubsection Change Logs and VC - - If you use RCS or CVS for a program with a @file{ChangeLog} file -@iftex -(@pxref{Change Log,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Change Log}), -@end ifnottex -you can generate change log entries from the version control log -entries of previous commits. - - Note that this only works with RCS or CVS. This procedure would be -particularly incorrect on a modern changeset-based version control -system, where changes to the @file{ChangeLog} file would normally be -committed as part of a changeset. In that case, you should write the -change log entries first, then pull them into the @samp{*vc-log*} -buffer when you commit -@iftex -(@pxref{Log Buffer,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Log Buffer}). -@end ifnottex - -@table @kbd -@item C-x v a -@kindex C-x v a -@findex vc-update-change-log -Visit the current directory's @file{ChangeLog} file and, for -registered files in that directory, create new entries for versions -committed since the most recent change log entry -(@code{vc-update-change-log}). - -@item C-u C-x v a -As above, but only find entries for the current buffer's file. -@end table - - For example, suppose the first line of @file{ChangeLog} is dated -1999-04-10, and that the only check-in since then was by Nathaniel -Bowditch to @file{rcs2log} on 1999-05-22 with log entry @samp{Ignore -log messages that start with `#'.}. Then @kbd{C-x v a} inserts this -@file{ChangeLog} entry: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-05-22 Nathaniel Bowditch - - * rcs2log: Ignore log messages that start with `#'. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - -@noindent -If the version control log entry specifies a function name (in -parenthesis at the beginning of a line), that is reflected in the -@file{ChangeLog} entry. For example, if a log entry for @file{vc.el} -is @samp{(vc-do-command): Check call-process status.}, the -@file{ChangeLog} entry is: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-05-06 Nathaniel Bowditch - - * vc.el (vc-do-command): Check call-process status. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - - When @kbd{C-x v a} adds several change log entries at once, it -groups related log entries together if they all are checked in by the -same author at nearly the same time. If the log entries for several -such files all have the same text, it coalesces them into a single -entry. - -@node VC Delete/Rename -@subsubsection Deleting and Renaming Version-Controlled Files -@cindex renaming version-controlled files - -@table @kbd -@item M-x vc-delete-file -Prompt for a file name, delete the file from the working tree, and -schedule the deletion for committing. - -@item M-x vc-rename-file -Prompt for two file names, @var{VAR} and @var{OLD}, rename them in the -working tree, and schedule the renaming for committing. -@end table - -@findex vc-delete-file - If you wish to delete a version-controlled file, use the command -@kbd{M-x vc-delete-file}. This prompts for the file name, and deletes -it via the version control system. The file is removed from the -working tree, and in the VC Directory buffer -@iftex -(@pxref{VC Directory Mode,,, emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{VC Directory Mode}), -@end ifnottex -it is displayed with the @samp{removed} status. When you commit it, -the deletion takes effect in the repository. - -@findex vc-rename-file - To rename a version-controlled file, type @kbd{M-x vc-rename-file}. -This prompts for two arguments: the name of the file you wish to -rename, and the new name; then it performs the renaming via the -version control system. The renaming takes effect immediately in the -working tree, and takes effect in the repository when you commit the -renamed file. - - On modern version control systems that have built-in support for -renaming, the renamed file retains the full change history of the -original file. On CVS and older version control systems, the -@code{vc-rename-file} command actually works by creating a copy of the -old file under the new name, registering it, and deleting the old -file. In this case, the change history is not preserved. - -@node Revision Tags -@subsubsection Revision Tags -@cindex revision tag -@cindex tags for version control - - Most version control systems allow you to apply a @dfn{revision tag} -to a specific version of a version-controlled tree. On modern -changeset-based version control systems, a revision tag is simply a -symbolic name for a particular revision. On older file-based systems -like CVS, each tag is added to the entire set of version-controlled -files, allowing them to be handled as a unit. Revision tags are -commonly used to identify releases that are distributed to users. - - There are two basic commands for tags; one makes a tag with a given -name, the other retrieves a named tag. - -@table @code -@kindex C-x v s -@findex vc-create-tag -@item C-x v s @var{name} @key{RET} -Define the working revision of every registered file in or under the -current directory as a tag named @var{name} -(@code{vc-create-tag}). - -@kindex C-x v r -@findex vc-retrieve-tag -@item C-x v r @var{name} @key{RET} -For all registered files at or below the current directory level, -retrieve the tagged revision @var{name}. This command will switch to a -branch if @var{name} is a branch name and your VCS distinguishes -branches from tags. (@code{vc-retrieve-tag}). - -This command reports an error if any files are locked at or below the -current directory, without changing anything; this is to avoid -overwriting work in progress. -@end table - - You can give a tag or branch name as an argument to @kbd{C-x v =} or -@kbd{C-x v ~} -@iftex -(@pxref{Old Revisions,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Old Revisions}). -@end ifnottex -Thus, you can use it to compare a tagged version against the current files, -or two tagged versions against each other. - - On SCCS, VC implements tags itself; these tags are visible only -through VC. Most later systems (including CVS, Subversion, bzr, git, -and hg) have a native tag facility, and VC uses it where available; -those tags will be visible even when you bypass VC. - - In a file-oriented VCS, when you rename a registered file you need -to rename its master along with it; the command @code{vc-rename-file} -will do this automatically. If you are using SCCS, you must also -update the records of the tag, to mention the file by its new name -(@code{vc-rename-file} does this, too). An old tag that refers to a -master file that no longer exists under the recorded name is invalid; -VC can no longer retrieve it. It would be beyond the scope of this -manual to explain enough about RCS and SCCS to explain how to update -the tags by hand. Using @code{vc-rename-file} makes the tag remain -valid for retrieval, but it does not solve all problems. For example, -some of the files in your program probably refer to others by name. -At the very least, the makefile probably mentions the file that you -renamed. If you retrieve an old tag, the renamed file is retrieved -under its new name, which is not the name that the makefile expects. -So the program won't really work as retrieved. - -@node Version Headers -@subsubsection Inserting Version Control Headers - - On Subversion, CVS, RCS, and SCCS, you can put certain special -strings called @dfn{version headers} into a work file. When the file -is committed, the version control system automatically puts the -revision number, the name of the user who made the commit, and other -relevant information into the version header. - -@vindex vc-consult-headers - VC does not normally use the information in the version headers. As -an exception, when using RCS, Emacs uses the version header, if there -is one, to determine the file version, since it is often more reliable -than the RCS master file. To inhibit using the version header this -way, change the variable @code{vc-consult-headers} to @code{nil}. - -@kindex C-x v h -@findex vc-insert-headers -@vindex vc-@var{backend}-header - To insert a suitable header string into the current buffer, type -@kbd{C-x v h} (@code{vc-insert-headers}). This command works only on -Subversion, CVS, RCS, and SCCS. The variable -@code{vc-@var{backend}-header} contains the list of keywords to insert -into the version header; for instance, CVS uses @code{vc-cvs-header}, -whose default value is @code{'("\$Id\$")}. (The extra backslashes -prevent the string constant from being interpreted as a header, if the -Emacs Lisp file defining it is maintained with version control.) The -@kbd{C-x v h} command inserts each keyword in the list on a new line -at point, surrounded by tabs, and inside comment delimiters if -necessary. - -@vindex vc-static-header-alist - The variable @code{vc-static-header-alist} specifies further strings -to add based on the name of the buffer. Its value should be a list of -elements of the form @code{(@var{regexp} . @var{format})}. Whenever -@var{regexp} matches the buffer name, @var{format} is also inserted as -part of the version header. A @samp{%s} in @var{format} is replaced -with the file's version control type. - -@node Customizing VC -@subsection Customizing VC - -@vindex vc-handled-backends - The variable @code{vc-handled-backends} determines which version -control systems VC should handle. The default value is @code{(RCS CVS -SVN SCCS Bzr Git Hg Mtn Arch)}, so it contains all the version systems -that are currently supported. If you want VC to ignore one or more of -these systems, exclude its name from the list. To disable VC -entirely, set this variable to @code{nil}. - - The order of systems in the list is significant: when you visit a -file registered in more than one system, VC uses the system that comes -first in @code{vc-handled-backends} by default. The order is also -significant when you register a file for the first time -@iftex -(@pxref{Registering,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Registering}). -@end ifnottex - -@menu -* General VC Options:: Options that apply to multiple back ends. -* RCS and SCCS:: Options for RCS and SCCS. -* CVS Options:: Options for CVS. -@end menu - -@node General VC Options -@subsubsection General Options - -@vindex vc-make-backup-files - Emacs normally does not save backup files for source files that are -maintained with version control. If you want to make backup files even -for files that use version control, set the variable -@code{vc-make-backup-files} to a non-@code{nil} value. - -@vindex vc-follow-symlinks -@cindex symbolic links (and version control) - Editing a version-controlled file through a symbolic link may cause -unexpected results, if you are unaware that the underlying file is -version-controlled. The variable @code{vc-follow-symlinks} controls -what Emacs does if you try to visit a symbolic link pointing to a -version-controlled file. If the value is @code{ask} (the default), -Emacs asks for confirmation. If it is @code{nil}, Emacs just displays -a warning message. If it is @code{t}, Emacs automatically follows the -link and visits the real file instead. - -@vindex vc-suppress-confirm - If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v} -and @kbd{C-x v i} can save the current buffer without asking, and -@kbd{C-x v u} also operates without asking for confirmation. - -@vindex vc-command-messages - VC mode does much of its work by running the shell commands for the -appropriate version control system. If @code{vc-command-messages} is -non-@code{nil}, VC displays messages to indicate which shell commands -it runs, and additional messages when the commands finish. - -@vindex vc-path - You can specify additional directories to search for version control -programs by setting the variable @code{vc-path}. These directories -are searched before the usual search path. It is rarely necessary to -set this variable, because VC normally finds the proper files -automatically. - -@node RCS and SCCS -@subsubsection Options for RCS and SCCS - -@cindex non-strict locking (RCS) -@cindex locking, non-strict (RCS) - By default, RCS uses locking to coordinate the activities of several -users, but there is a mode called @dfn{non-strict locking} in which -you can check-in changes without locking the file first. Use -@samp{rcs -U} to switch to non-strict locking for a particular file, -see the @code{rcs} manual page for details. - - When deducing the version control state of an RCS file, VC first -looks for an RCS version header string in the file (@pxref{Version -Headers}). If there is no header string, VC normally looks at the -file permissions of the work file; this is fast. But there might be -situations when the file permissions cannot be trusted. In this case -the master file has to be consulted, which is rather expensive. Also -the master file can only tell you @emph{if} there's any lock on the -file, but not whether your work file really contains that locked -version. - -@vindex vc-consult-headers - You can tell VC not to use version headers to determine the file -status by setting @code{vc-consult-headers} to @code{nil}. VC then -always uses the file permissions (if it is supposed to trust them), or -else checks the master file. - -@vindex vc-mistrust-permissions - You can specify the criterion for whether to trust the file -permissions by setting the variable @code{vc-mistrust-permissions}. -Its value can be @code{t} (always mistrust the file permissions and -check the master file), @code{nil} (always trust the file -permissions), or a function of one argument which makes the decision. -The argument is the directory name of the @file{RCS} subdirectory. A -non-@code{nil} value from the function says to mistrust the file -permissions. If you find that the file permissions of work files are -changed erroneously, set @code{vc-mistrust-permissions} to @code{t}. -Then VC always checks the master file to determine the file's status. - - VC determines the version control state of files under SCCS much as -with RCS. It does not consider SCCS version headers, though. Thus, -the variable @code{vc-mistrust-permissions} affects SCCS use, but -@code{vc-consult-headers} does not. - -@node CVS Options -@subsubsection Options specific for CVS - -@vindex vc-cvs-global-switches - You can specify additional command line options to pass to all CVS -operations in the variable @code{vc-cvs-global-switches}. These -switches are inserted immediately after the @code{cvs} command, before -the name of the operation to invoke. - -@vindex vc-stay-local -@vindex vc-cvs-stay-local -@cindex remote repositories (CVS) - When using a CVS repository on a remote machine, VC can try keeping -network interactions to a minimum. This is controlled by the variable -@code{vc-cvs-stay-local}. There is another variable, -@code{vc-stay-local}, which enables the feature also for other back -ends that support it, including CVS. In the following, we will talk -only about @code{vc-cvs-stay-local}, but everything applies to -@code{vc-stay-local} as well. - - If @code{vc-cvs-stay-local} is @code{t} (the default), VC determines -the version control status of each file using only the entry in the -local CVS subdirectory and the information returned by previous CVS -commands. As a consequence, if you have modified a file and somebody -else has checked in other changes, you will not be notified of the -conflict until you try to commit. - - If you change @code{vc-cvs-stay-local} to @code{nil}, VC queries the -remote repository @emph{before} it decides what to do in -@code{vc-next-action} (@kbd{C-x v v}), just as it does for local -repositories. - - You can also set @code{vc-cvs-stay-local} to a regular expression -that is matched against the repository host name; VC then stays local -only for repositories from hosts that match the pattern. - -@cindex automatic version backups - When using a remote repository, Emacs normally makes @dfn{automatic -version backups} of the original versions of each edited file. These -local backups are made whenever you save the first changes to a file, -and they are removed after you commit your changes to the repository. -(Note that these are not the same as ordinary Emacs backup files; -@iftex -@pxref{Backup,,,emacs, the Emacs Manual}.) -@end iftex -@ifnottex -@pxref{Backup}.) -@end ifnottex -Commands like @kbd{C-x v =} and @kbd{C-x v u} make use of automatic -version backups, if possible, to avoid having to access the network. - - Setting @code{vc-cvs-stay-local} to @code{nil} disables the making -of automatic version backups. - -@cindex manual version backups - Automatic version backups have names of the form -@w{@code{@var{file}.~@var{version}.~}}. This is similar to the name -that @kbd{C-x v ~} saves old versions to -@iftex -(@pxref{Old Revisions,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Old Revisions}), -@end ifnottex -except for the additional dot (@samp{.}) after the version. The -relevant VC commands can use both kinds of version backups. The main -difference is that the ``manual'' version backups made by @kbd{C-x v -~} are not deleted automatically when you commit. - -@cindex locking (CVS) - CVS does not use locking by default, but there are ways to enable -locking-like behavior using its @env{CVSREAD} or @dfn{watch} feature; -see the CVS documentation for details. If that case, you can use -@kbd{C-x v v} in Emacs to toggle locking, as you would for a -locking-based version control system -@iftex -(@pxref{VC With A Locking VCS,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{VC With A Locking VCS}). -@end ifnottex diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi deleted file mode 100644 index 72e01a368a1..00000000000 --- a/doc/emacs/windows.texi +++ /dev/null @@ -1,469 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Windows, Frames, Buffers, Top -@chapter Multiple Windows -@cindex windows in Emacs -@cindex multiple windows in Emacs - - Emacs can split a frame into two or many windows. Multiple windows -can display parts of different buffers, or different parts of one -buffer. Multiple frames always imply multiple windows, because each -frame has its own set of windows. Each window belongs to one and only -one frame. - -@menu -* Basic Window:: Introduction to Emacs windows. -* Split Window:: New windows are made by splitting existing windows. -* Other Window:: Moving to another window or doing something to it. -* Pop Up Window:: Finding a file or buffer in another window. -* Change Window:: Deleting windows and changing their sizes. -* Displaying Buffers:: How Emacs picks a window for displaying a buffer. -* Window Convenience:: Convenience functions for window handling. -@end menu - -@node Basic Window -@section Concepts of Emacs Windows - - Each Emacs window displays one Emacs buffer at any time. A single -buffer may appear in more than one window; if it does, any changes in -its text are displayed in all the windows where it appears. But these -windows can show different parts of the buffer, because each window -has its own value of point. - -@cindex selected window - At any time, one Emacs window is the @dfn{selected window}; the -buffer this window is displaying is the current buffer. On graphical -displays, the point is indicated by a solid blinking cursor in the -selected window, and by a hollow box in non-selected windows. On text -terminals, the cursor is drawn only in the selected window. -@xref{Cursor Display}. - - Commands to move point affect the value of point for the selected -Emacs window only. They do not change the value of point in other -Emacs windows, even those showing the same buffer. The same is true -for buffer-switching commands such as @kbd{C-x b}; they do not affect -other windows at all. However, there are other commands such as -@kbd{C-x 4 b} that select a different window and switch buffers in it. -Also, all commands that display information in a window, including -(for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b} -(@code{list-buffers}), work by switching buffers in a nonselected -window without affecting the selected window. - - When multiple windows show the same buffer, they can have different -regions, because they can have different values of point. However, -they all have the same value for the mark, because each buffer has -only one mark position. - - Each window has its own mode line, which displays the buffer name, -modification status and major and minor modes of the buffer that is -displayed in the window. The selected window's mode line appears in a -different color. @xref{Mode Line}, for details. - -@node Split Window -@section Splitting Windows - -@table @kbd -@item C-x 2 -Split the selected window into two windows, one above the other -(@code{split-window-below}). -@item C-x 3 -Split the selected window into two windows, positioned side by side -(@code{split-window-right}). -@item C-Mouse-2 -In the mode line of a window, split that window. -@end table - -@kindex C-x 2 -@findex split-window-below - @kbd{C-x 2} (@code{split-window-below}) splits the selected window -into two windows, one above the other. After splitting, the selected -window is the upper one, and the newly split-off window is below. -Both windows have the same value of point as before, and display the -same portion of the buffer (or as close to it as possible). If -necessary, the windows are scrolled to keep point on-screen. By -default, the two windows each get half the height of the original -window. A positive numeric argument specifies how many lines to give -to the top window; a negative numeric argument specifies how many -lines to give to the bottom window. - -@vindex split-window-keep-point - If you change the variable @code{split-window-keep-point} to -@code{nil}, @kbd{C-x 2} instead adjusts the portion of the buffer -displayed by the two windows, as well as the value of point in each -window, in order to keep the text on the screen as close as possible -to what it was before; furthermore, if point was in the lower half of -the original window, the bottom window is selected instead of the -upper one. - -@kindex C-x 3 -@findex split-window-right - @kbd{C-x 3} (@code{split-window-right}) splits the selected window -into two side-by-side windows. The left window is the selected one; -the right window displays the same portion of the same buffer, and has -the same value of point. A positive numeric argument specifies how -many columns to give the left window; a negative numeric argument -specifies how many columns to give the right window. - -@vindex truncate-partial-width-windows - When you split a window with @kbd{C-x 3}, each resulting window -occupies less than the full width of the frame. If it becomes too -narrow, the buffer may be difficult to read if continuation lines are -in use (@pxref{Continuation Lines}). Therefore, Emacs automatically -switches to line truncation if the window width becomes narrower than -50 columns. This truncation occurs regardless of the value of the -variable @code{truncate-lines} (@pxref{Line Truncation}); it is -instead controlled by the variable -@code{truncate-partial-width-windows}. If the value of this variable -is a positive integer (the default is 50), that specifies the minimum -width for a partial-width window before automatic line truncation -occurs; if the value is @code{nil}, automatic line truncation is -disabled; and for any other non-@code{nil} value, Emacs truncates -lines in every partial-width window regardless of its width. - - On text terminals, side-by-side windows are separated by a vertical -divider which is drawn using the @code{vertical-border} face. - -@kindex C-Mouse-2 @r{(mode line)} -@kindex C-Mouse-2 @r{(scroll bar)} - If you click @kbd{C-Mouse-2} in the mode line of a window, that -splits the window, putting a vertical divider where you click. -Depending on how Emacs is compiled, you can also split a window by -clicking @kbd{C-Mouse-2} in the scroll bar, which puts a horizontal -divider where you click (this feature does not work when Emacs uses -GTK+ scroll bars). - -@node Other Window -@section Using Other Windows - -@table @kbd -@item C-x o -Select another window (@code{other-window}). -@item C-M-v -Scroll the next window (@code{scroll-other-window}). -@item Mouse-1 -@kbd{Mouse-1}, in the text area of a window, selects the window and -moves point to the position clicked. Clicking in the mode line -selects the window without moving point in it. -@end table - -@kindex C-x o -@findex other-window -With the keyboard, you can switch windows by typing @kbd{C-x o} -(@code{other-window}). That is an @kbd{o}, for ``other'', not a zero. -When there are more than two windows, this command moves through all the -windows in a cyclic order, generally top to bottom and left to right. -After the rightmost and bottommost window, it goes back to the one at -the upper left corner. A numeric argument means to move several steps -in the cyclic order of windows. A negative argument moves around the -cycle in the opposite order. When the minibuffer is active, the -minibuffer is the last window in the cycle; you can switch from the -minibuffer window to one of the other windows, and later switch back and -finish supplying the minibuffer argument that is requested. -@xref{Minibuffer Edit}. - -@kindex C-M-v -@findex scroll-other-window - The usual scrolling commands (@pxref{Display}) apply to the selected -window only, but there is one command to scroll the next window. -@kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that -@kbd{C-x o} would select. It takes arguments, positive and negative, -like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the help -window associated with the minibuffer, if any, rather than the next -window in the standard cyclic order; @pxref{Minibuffer Edit}.) - -@vindex mouse-autoselect-window - If you set @code{mouse-autoselect-window} to a non-@code{nil} value, -moving the mouse over a different window selects that window. This -feature is off by default. - -@node Pop Up Window -@section Displaying in Another Window - -@cindex selecting buffers in other windows -@kindex C-x 4 - @kbd{C-x 4} is a prefix key for a variety of commands that switch to -a buffer in a different window---either another existing window, or a -new window created by splitting the selected window. @xref{Window -Choice}, for how Emacs picks or creates the window to use. - -@table @kbd -@findex switch-to-buffer-other-window -@item C-x 4 b @var{bufname} @key{RET} -Select buffer @var{bufname} in another window -(@code{switch-to-buffer-other-window}). - -@findex display-buffer -@item C-x 4 C-o @var{bufname} @key{RET} -@kindex C-x 4 C-o -Display buffer @var{bufname} in some window, without trying to select -it (@code{display-buffer}). @xref{Displaying Buffers}, for details -about how the window is chosen. - -@findex find-file-other-window -@item C-x 4 f @var{filename} @key{RET} -Visit file @var{filename} and select its buffer in another window -(@code{find-file-other-window}). @xref{Visiting}. - -@findex dired-other-window -@item C-x 4 d @var{directory} @key{RET} -Select a Dired buffer for directory @var{directory} in another window -(@code{dired-other-window}). @xref{Dired}. - -@findex mail-other-window -@item C-x 4 m -Start composing a mail message, similar to @kbd{C-x m} (@pxref{Sending -Mail}), but in another window (@code{mail-other-window}). - -@findex find-tag-other-window -@item C-x 4 . -Find a tag in the current tags table, similar to @kbd{M-.} -(@pxref{Tags}), but in another window (@code{find-tag-other-window}). -@item C-x 4 r @var{filename} @key{RET} -Visit file @var{filename} read-only, and select its buffer in another -window (@code{find-file-read-only-other-window}). @xref{Visiting}. -@end table - -@node Change Window -@section Deleting and Rearranging Windows - -@table @kbd -@item C-x 0 -Delete the selected window (@code{delete-window}). -@item C-x 1 -Delete all windows in the selected frame except the selected window -(@code{delete-other-windows}). -@item C-x 4 0 -Delete the selected window and kill the buffer that was showing in it -(@code{kill-buffer-and-window}). The last character in this key -sequence is a zero. -@item C-x ^ -Make selected window taller (@code{enlarge-window}). -@item C-x @} -Make selected window wider (@code{enlarge-window-horizontally}). -@item C-x @{ -Make selected window narrower (@code{shrink-window-horizontally}). -@item C-x - -Shrink this window if its buffer doesn't need so many lines -(@code{shrink-window-if-larger-than-buffer}). -@item C-x + -Make all windows the same height (@code{balance-windows}). -@end table - -@kindex C-x 0 -@findex delete-window - To delete the selected window, type @kbd{C-x 0} -(@code{delete-window}). (That is a zero.) Once a window is deleted, -the space that it occupied is given to an adjacent window (but not the -minibuffer window, even if that is active at the time). Deleting the -window has no effect on the buffer it used to display; the buffer -continues to exist, and you can still switch to with @kbd{C-x b}. - -@findex kill-buffer-and-window -@kindex C-x 4 0 - @kbd{C-x 4 0} (@code{kill-buffer-and-window}) is a stronger command -than @kbd{C-x 0}; it kills the current buffer and then deletes the -selected window. - -@kindex C-x 1 -@findex delete-other-windows - @kbd{C-x 1} (@code{delete-other-windows}) deletes all the windows, -@emph{except} the selected one; the selected window expands to use the -whole frame. (This command cannot be used while the minibuffer window -is active; attempting to do so signals an error.) - -@kindex C-x ^ -@findex enlarge-window -@kindex C-x @} -@vindex window-min-height - The command @kbd{C-x ^} (@code{enlarge-window}) makes the selected -window one line taller, taking space from a vertically adjacent window -without changing the height of the frame. With a positive numeric -argument, this command increases the window height by that many lines; -with a negative argument, it reduces the height by that many lines. -If there are no vertically adjacent windows (i.e. the window is at the -full frame height), that signals an error. The command also signals -an error if you attempt to reduce the height of any window below a -certain minimum number of lines, specified by the variable -@code{window-min-height} (the default is 4). - -@findex enlarge-window-horizontally -@findex shrink-window-horizontally -@vindex window-min-width - Similarly, @kbd{C-x @}} (@code{enlarge-window-horizontally}) makes -the selected window wider, and @kbd{C-x @{} -(@code{shrink-window-horizontally}) makes it narrower. These commands -signal an error if you attempt to reduce the width of any window below -a certain minimum number of columns, specified by the variable -@code{window-min-width} (the default is 10). - -@kindex C-x - -@findex shrink-window-if-larger-than-buffer - @kbd{C-x -} (@code{shrink-window-if-larger-than-buffer}) reduces the -height of the selected window, if it is taller than necessary to show -the whole text of the buffer it is displaying. It gives the extra -lines to other windows in the frame. - -@kindex C-x + -@findex balance-windows - You can also use @kbd{C-x +} (@code{balance-windows}) to even out the -heights of all the windows in the selected frame. - - Mouse clicks on the mode line provide another way to change window -heights and to delete windows. @xref{Mode Line Mouse}. - -@node Displaying Buffers -@section Displaying a Buffer in a Window - - It is a common Emacs operation to display or ``pop up'' some buffer -in response to a user command. There are several different ways in -which commands do this. - - Many commands, like @kbd{C-x C-f} (@code{find-file}), display the -buffer by ``taking over'' the selected window, expecting that the -user's attention will be diverted to that buffer. These commands -usually work by calling @code{switch-to-buffer} internally -(@pxref{Select Buffer}). - -@findex display-buffer - Some commands try to display ``intelligently'', trying not to take -over the selected window, e.g. by splitting off a new window and -displaying the desired buffer there. Such commands, which include the -various help commands (@pxref{Help}), work by calling -@code{display-buffer} internally. @xref{Window Choice}, for details. - - Other commands do the same as @code{display-buffer}, and -additionally select the displaying window so that you can begin -editing its buffer. The command @kbd{C-x `} (@code{next-error}) is -one example (@pxref{Compilation Mode}). Such commands work by calling -the function @code{pop-to-buffer} internally. @xref{Switching -Buffers,,Switching to a Buffer in a Window, elisp, The Emacs Lisp -Reference Manual}. - - Commands with names ending in @code{-other-window} behave like -@code{display-buffer}, except that they never display in the selected -window. Several of these commands are bound in the @kbd{C-x 4} prefix -key (@pxref{Pop Up Window}). - - Commands with names ending in @code{-other-frame} behave like -@code{display-buffer}, except that they (i) never display in the -selected window and (ii) prefer to create a new frame to display the -desired buffer instead of splitting a window---as though the variable -@code{pop-up-frames} is set to @code{t} (@pxref{Window Choice}). -Several of these commands are bound in the @kbd{C-x 5} prefix key. - -@menu -* Window Choice:: How @code{display-buffer} works. -@end menu - -@node Window Choice -@subsection How @code{display-buffer} works -@findex display-buffer - -The @code{display-buffer} command (as well as commands that call it -internally) chooses a window to display by following the steps given -below. @xref{Choosing Window,,Choosing a Window for Display, elisp, -The Emacs Lisp Reference Manual}, for details about how to alter this -sequence of steps. - -@itemize -@vindex same-window-buffer-names -@vindex same-window-regexps -@item -First, check if the buffer should be displayed in the selected window -regardless of other considerations. You can tell Emacs to do this by -adding the desired buffer's name to the list -@code{same-window-buffer-names}, or adding a matching regular -expression to the list @code{same-window-regexps}. By default, these -variables are @code{nil}, so this step is skipped. - -@vindex display-buffer-reuse-frames -@item -Otherwise, if the buffer is already displayed in an existing window, -``reuse'' that window. Normally, only windows on the selected frame -are considered, but windows on other frames are also reusable if you -change @code{display-buffer-reuse-frames} to @code{t}, or if you -change @code{pop-up-frames} (see below) to @code{t}. - -@item -Otherwise, if you specified that the buffer should be displayed in a -special frame by customizing @code{special-display-buffer-names} or -@code{special-display-regexps}, do so. @xref{Choosing Window -Options,,, elisp, The Emacs Lisp Reference Manual}. - -@vindex pop-up-frames -@item -Otherwise, optionally create a new frame and display the buffer there. -By default, this step is skipped. To enable it, change the variable -@code{pop-up-frames} to a non-@code{nil} value. The special value -@code{graphic-only} means to do this only on graphical displays. - -@item -Otherwise, try to create a new window by splitting the selected -window, and display the buffer in that new window. - -@vindex split-height-threshold -@vindex split-width-threshold -The split can be either vertical or horizontal, depending on the -variables @code{split-height-threshold} and -@code{split-width-threshold}. These variables should have integer -values. If @code{split-height-threshold} is smaller than the selected -window's height, the split puts the new window below. Otherwise, if -@code{split-width-threshold} is smaller than the window's width, the -split puts the new window on the right. If neither condition holds, -Emacs tries to split so that the new window is below---but only if the -window was not split before (to avoid excessive splitting). - -@item -Otherwise, display the buffer in an existing window on the selected -frame. - -@item -If all the above methods fail for whatever reason, create a new frame -and display the buffer there. -@end itemize - -@node Window Convenience -@section Convenience Features for Window Handling - -@findex winner-mode -@cindex Winner mode -@cindex mode, Winner -@cindex undoing window configuration changes -@cindex window configuration changes, undoing - Winner mode is a global minor mode that records the changes in the -window configuration (i.e. how the frames are partitioned into -windows), so that you can ``undo'' them. You can toggle Winner mode -with @kbd{M-x winner-mode}, or by customizing the variable -@code{winner-mode}. When the mode is enabled, @kbd{C-c left} -(@code{winner-undo}) undoes the last window configuration change. If -you change your mind while undoing, you can redo the changes you had -undone using @kbd{C-c right} (@code{M-x winner-redo}). - - Follow mode (@kbd{M-x follow-mode}) synchronizes several windows on -the same buffer so that they always display adjacent sections of that -buffer. @xref{Follow Mode}. - -@cindex Windmove package -@cindex directional window selection -@findex windmove-right -@findex windmove-default-keybindings - The Windmove package defines commands for moving directionally -between neighboring windows in a frame. @kbd{M-x windmove-right} -selects the window immediately to the right of the currently selected -one, and similarly for the ``left'', ``up'', and ``down'' -counterparts. @kbd{M-x windmove-default-keybindings} binds these -commands to @kbd{S-right} etc.; doing so disables shift selection for -those keys (@pxref{Shift Selection}). - - The command @kbd{M-x compare-windows} lets you compare the text -shown in different windows. @xref{Comparing Files}. - -@vindex scroll-all-mode -@cindex scrolling windows together -@cindex Scroll-all mode -@cindex mode, Scroll-all - Scroll All mode (@kbd{M-x scroll-all-mode}) is a global minor mode -that causes scrolling commands and point motion commands to apply to -every single window. diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi deleted file mode 100644 index b99c98d84e0..00000000000 --- a/doc/emacs/xresources.texi +++ /dev/null @@ -1,821 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1987, 1993-1995, 1997, 2001-2012 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node X Resources, Antinews, Emacs Invocation, Top -@appendix X Options and Resources - - You can customize some X-related aspects of Emacs behavior using X -resources, as is usual for programs that use X. - - When Emacs is compiled with GTK+ support, the appearance of various -graphical widgets, such as the menu-bar, scroll-bar, and dialog boxes, -is determined by -@ifnottex -``GTK resources'', which we will also describe. -@end ifnottex -@iftex -``GTK resources''. -@end iftex -When Emacs is built without GTK+ support, the appearance of these -widgets is determined by additional X resources. - - On MS-Windows, you can customize some of the same aspects using the -system registry (@pxref{MS-Windows Registry}). - -@menu -* Resources:: Using X resources with Emacs (in general). -* Table of Resources:: Table of specific X resources that affect Emacs. -* Lucid Resources:: X resources for Lucid menus. -* LessTif Resources:: X resources for LessTif and Motif menus. -* GTK resources:: Resources for GTK widgets. -@end menu - -@node Resources -@appendixsec X Resources -@cindex resources -@cindex X resources -@cindex @file{~/.Xdefaults} file -@cindex @file{~/.Xresources} file - - Programs running under the X Window System organize their user -options under a hierarchy of classes and resources. You can specify -default values for these options in your @dfn{X resource file}, -usually named @file{~/.Xdefaults} or @file{~/.Xresources}. Changes in -this file do not take effect immediately, because the X server stores -its own list of resources; to update it, use the command -@command{xrdb}---for instance, @samp{xrdb ~/.Xdefaults}. - -@cindex registry, setting resources (MS-Windows) - (MS-Windows systems do not support X resource files; on such systems, -Emacs looks for X resources in the Windows Registry, first under the -key @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs}, which affects only -the current user and override the system-wide settings, and then under -the key @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}, which affects -all users of the system. The menu and scroll bars are native widgets -on MS-Windows, so they are only customizable via the system-wide -settings in the Display Control Panel. You can also set resources -using the @samp{-xrm} command line option, as explained below.) - - Each line in the X resource file specifies a value for one option or -for a collection of related options. The order in which the lines -appear in the file does not matter. Each resource specification -consists of a @dfn{program name} and a @dfn{resource name}. Case -distinctions are significant in each of these names. Here is an -example: - -@example -emacs.cursorColor: dark green -@end example - - The program name is the name of the executable file to which the -resource applies. For Emacs, this is normally @samp{emacs}. To -specify a definition that applies to all instances of Emacs, -regardless of the name of the Emacs executable, use @samp{Emacs}. - - The resource name is the name of a program setting. For instance, -Emacs recognizes a @samp{cursorColor} resource that controls the color -of the text cursor. - - Resources are grouped into named classes. For instance, the -@samp{Foreground} class contains the @samp{cursorColor}, -@samp{foreground} and @samp{pointerColor} resources (@pxref{Table of -Resources}). Instead of using a resource name, you can use a class -name to specify the default value for all resources in that class, -like this: - -@example -emacs.Foreground: dark green -@end example - - Emacs does not process X resources at all if you set the variable -@code{inhibit-x-resources} to a non-@code{nil} value. If you invoke -Emacs with the @samp{-Q} (or @samp{--quick}) command-line option, -@code{inhibit-x-resources} is automatically set to @code{t} -(@pxref{Initial Options}). - -@ifnottex - In addition, you can use the following command-line options to -override the X resources file: - -@table @samp -@item -name @var{name} -@opindex --name -@itemx --name=@var{name} -@cindex resource name, command-line argument -This option sets the program name of the initial Emacs frame to -@var{name}. It also sets the title of the initial frame to -@var{name}. This option does not affect subsequent frames. - -If you don't specify this option, the default is to use the Emacs -executable's name as the program name. - -For consistency, @samp{-name} also specifies the name to use for other -resource values that do not belong to any particular frame. - -The resources that name Emacs invocations also belong to a class, -named @samp{Emacs}. If you write @samp{Emacs} instead of -@samp{emacs}, the resource applies to all frames in all Emacs jobs, -regardless of frame titles and regardless of the name of the -executable file. - -@item -xrm @var{resource-values} -@opindex --xrm -@itemx --xrm=@var{resource-values} -@cindex resource values, command-line argument -This option specifies X resource values for the present Emacs job. - -@var{resource-values} should have the same format that you would use -inside a file of X resources. To include multiple resource -specifications in @var{resource-values}, put a newline between them, -just as you would in a file. You can also use @samp{#include -"@var{filename}"} to include a file full of resource specifications. -Resource values specified with @samp{-xrm} take precedence over all -other resource specifications. -@end table -@end ifnottex - -@node Table of Resources -@appendixsec Table of X Resources for Emacs - - This table lists the X resource names that Emacs recognizes, -excluding those that control the appearance of graphical widgets like -the menu bar: - -@table @asis -@item @code{background} (class @code{Background}) -Background color (@pxref{Colors}). - -@item @code{bitmapIcon} (class @code{BitmapIcon}) -Tell the window manager to display the Emacs icon if @samp{on}; don't -do so if @samp{off}. @xref{Icons X}, for a description of the icon. - -@ifnottex -@item @code{borderColor} (class @code{BorderColor}) -Color of the frame's external border. This has no effect if Emacs is -compiled with GTK+ support. - -@item @code{borderWidth} (class @code{BorderWidth}) -Width of the frame's external border, in pixels. This has no effect -if Emacs is compiled with GTK+ support. -@end ifnottex - -@item @code{cursorColor} (class @code{Foreground}) -Text cursor color. If this resource is specified when Emacs starts -up, Emacs sets its value as the background color of the @code{cursor} -face (@pxref{Faces}). - -@item @code{cursorBlink} (class @code{CursorBlink}) -If the value of this resource is @samp{off} or @samp{false} or -@samp{0} at startup, Emacs disables Blink Cursor mode (@pxref{Cursor -Display}). - -@item @code{font} (class @code{Font}) -Font name for the @code{default} face (@pxref{Fonts}). You can also -specify a fontset name (@pxref{Fontsets}). - -@item @code{fontBackend} (class @code{FontBackend}) -Comma-delimited list of backend(s) to use for drawing fonts, in order -of precedence. For instance, the value @samp{x,xft} tells Emacs to -draw fonts using the X core font driver, falling back on the Xft font -driver if that fails. Normally, you should leave this resource unset, -in which case Emacs tries using all available font backends. - -@item @code{foreground} (class @code{Foreground}) -Default foreground color for text. - -@item @code{geometry} (class @code{Geometry}) -Window size and position. The value should be a size and position -specification, of the same form as in the @samp{-g} or -@samp{--geometry} command-line option (@pxref{Window Size X}). - -The size applies to all frames in the Emacs session, but the position -applies only to the initial Emacs frame (or, in the case of a resource -for a specific frame name, only that frame). - - -Be careful not to specify this resource as @samp{emacs*geometry}, as -that may affect individual menus as well as the main Emacs frame. - -@item @code{fullscreen} (class @code{Fullscreen}) -The desired fullscreen size. The value can be one of @code{fullboth}, -@code{maximized}, @code{fullwidth} or @code{fullheight}, which -correspond to the command-line options @samp{-fs}, @samp{-mm}, -@samp{-fw}, and @samp{-fh} (@pxref{Window Size X}). Note that this -applies to the initial frame only. - -@ifnottex -@item @code{iconName} (class @code{Title}) -Name to display in the icon. - -@item @code{internalBorder} (class @code{BorderWidth}) -Width of the internal frame border, in pixels. -@end ifnottex - -@item @code{lineSpacing} (class @code{LineSpacing}) -@cindex line spacing -Additional space between lines, in pixels. - -@item @code{menuBar} (class @code{MenuBar}) -@cindex menu bar -If the value of this resource is @samp{off} or @samp{false} or -@samp{0}, Emacs disables Menu Bar mode at startup (@pxref{Menu Bars}). - -@ifnottex -@item @code{minibuffer} (class @code{Minibuffer}) -If @samp{none}, Emacs will not make a minibuffer in this frame; it -will use a separate minibuffer frame instead. - -@item @code{paneFont} (class @code{Font}) -@cindex font for menus -Font name for menu pane titles, in non-toolkit versions of Emacs. -@end ifnottex - -@item @code{pointerColor} (class @code{Foreground}) -Color of the mouse cursor. This has no effect in many graphical -desktop environments, as they do not let Emacs change the mouse cursor -this way. - -@ifnottex -@item @code{privateColormap} (class @code{PrivateColormap}) -If @samp{on}, use a private color map, in the case where the ``default -visual'' of class PseudoColor and Emacs is using it. - -@item @code{reverseVideo} (class @code{ReverseVideo}) -Switch foreground and background default colors if @samp{on}, use colors as -specified if @samp{off}. - -@item @code{screenGamma} (class @code{ScreenGamma}) -@cindex gamma correction -Gamma correction for colors, equivalent to the frame parameter -@code{screen-gamma}. - -@item @code{scrollBarWidth} (class @code{ScrollBarWidth}) -@cindex scrollbar width -The scroll bar width in pixels, equivalent to the frame parameter -@code{scroll-bar-width}. Do not set this resource if Emacs is -compiled with GTK+ support. -@end ifnottex - -@ifnottex -@item @code{selectionFont} (class @code{SelectionFont}) -Font name for pop-up menu items, in non-toolkit versions of Emacs. (For -toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif -Resources}.) - -@item @code{selectionTimeout} (class @code{SelectionTimeout}) -Number of milliseconds to wait for a selection reply. -If the selection owner doesn't reply in this time, we give up. -A value of 0 means wait as long as necessary. - -@item @code{synchronous} (class @code{Synchronous}) -@cindex debugging X problems -@cindex synchronous X mode -Run Emacs in synchronous mode if @samp{on}. Synchronous mode is -useful for debugging X problems. -@end ifnottex - -@item @code{title} (class @code{Title}) -Name to display in the title bar of the initial Emacs frame. - -@item @code{toolBar} (class @code{ToolBar}) -@cindex tool bar -If the value of this resource is @samp{off} or @samp{false} or -@samp{0}, Emacs disables Tool Bar mode at startup (@pxref{Tool Bars}). - -@item @code{useXIM} (class @code{UseXIM}) -@cindex XIM -@cindex X input methods -@cindex input methods, X -Disable use of X input methods (XIM) if @samp{false} or @samp{off}. -This is only relevant if your Emacs is built with XIM support. It -might be useful to turn off XIM on slow X client/server links. - -@item @code{verticalScrollBars} (class @code{ScrollBars}) -Give frames scroll bars if @samp{on}; don't have scroll bars if -@samp{off}. - -@ifnottex -@item @code{visualClass} (class @code{VisualClass}) -The @dfn{visual class} for X color display. If specified, the value -should start with one of @samp{TrueColor}, @samp{PseudoColor}, -@samp{DirectColor}, @samp{StaticColor}, @samp{GrayScale}, and -@samp{StaticGray}, followed by @samp{-@var{depth}}, where @var{depth} -is the number of color planes. -@end ifnottex -@end table - - You can also use X resources to customize individual Emacs faces -(@pxref{Faces}). For example, setting the resource -@samp{@var{face}.attributeForeground} is equivalent to customizing the -@samp{foreground} attribute of the face @var{face}. However, we -recommend customizing faces from within Emacs, instead of using X -resources. @xref{Face Customization}. - -@ifnottex -@node Lucid Resources -@appendixsec Lucid Menu And Dialog X Resources -@cindex Menu X Resources (Lucid widgets) -@cindex Dialog X Resources (Lucid widgets) -@cindex Lucid Widget X Resources - - If Emacs is compiled with the X toolkit support using Lucid widgets, -you can use X resources to customize the appearance of the menu bar, -pop-up menus, and dialog boxes. The resources for the menu bar fall -in the @samp{pane.menubar} class (following, as always, either the -name of the Emacs executable or @samp{Emacs} for all Emacs -invocations). The resources for the pop-up menu are in the -@samp{menu*} class. The resources for dialog boxes are in the -@samp{dialog*} class. - - For example, to display menu bar entries with the @samp{Courier-12} -font (@pxref{Fonts}), write this: - -@example -Emacs.pane.menubar.font: Courier-12 -@end example - -@noindent -Lucid widgets can display multilingual text in your locale. To enable -this, specify a @code{fontSet} resource instead of a @code{font} -resource. @xref{Fontsets}. If both @code{font} and @code{fontSet} -resources are specified, the @code{fontSet} resource is used. - -Here is a list of resources for menu bars, pop-up menus, and dialogs: - -@table @code -@item font -Font for menu item text. -@item fontSet -Fontset for menu item text. -@item foreground -Foreground color. -@item background -Background color. -@item buttonForeground -Foreground color for a selected item. -@ifnottex -@item horizontalSpacing -Horizontal spacing in pixels between items. Default is 3. -@item verticalSpacing -Vertical spacing in pixels between items. Default is 2. -@item arrowSpacing -Horizontal spacing between the arrow (which indicates a submenu) and -the associated text. Default is 10. -@item shadowThickness -Thickness of shadow lines for 3D buttons, arrows, and other graphical -elements. Default is 1. -@end ifnottex -@item margin -Margin of the menu bar, in characters. Default is 1. -@end table - -@node LessTif Resources -@appendixsec LessTif Menu X Resources -@cindex Menu X Resources (LessTif widgets) -@cindex LessTif Widget X Resources - - If Emacs is compiled with the X toolkit support using LessTif or -Motif widgets, you can use X resources to customize the appearance of -the menu bar, pop-up menus, and dialog boxes. However, the resources -are organized differently from Lucid widgets. - - The resource names for the menu bar are in the @samp{pane.menubar} -class, and they must be specified in this form: - -@smallexample -Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value} -@end smallexample - -@noindent -For pop-up menus, the resources are in the @samp{menu*} class, instead -of @samp{pane.menubar}. For dialog boxes, they are in @samp{dialog}. -In each case, each individual menu string is a subwidget; the -subwidget's name is the same as the menu item string. For example, -the @samp{File} menu in the menu bar is a subwidget named -@samp{emacs.pane.menubar.File}. - - Typically, you want to specify the same resources for the whole menu -bar. To do this, use @samp{*} instead of a specific subwidget name. -For example, to specify the font @samp{8x16} for all menu bar items, -including submenus, write this: - -@smallexample -Emacs.pane.menubar.*.fontList: 8x16 -@end smallexample - - Each item in a submenu also has its own name for X resources; for -example, the @samp{File} submenu has an item named @samp{Save (current -buffer)}. A resource specification for a submenu item looks like -this: - -@smallexample -Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value} -@end smallexample - -@noindent -For example, here's how to specify the font for the @samp{Save (current -buffer)} item: - -@smallexample -Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16 -@end smallexample - -@noindent -For an item in a second-level submenu, such as @samp{Complete Word} -under @samp{Spell Checking} under @samp{Tools}, the resource fits this -template: - -@smallexample -Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value} -@end smallexample - -@noindent -For example, - -@smallexample -Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value} -@end smallexample - -@noindent -(This should be one long line.) - - If you want the submenu items to look different from the menu bar -itself, you must first specify the resource for all of them, then -override the value for submenus alone. Here is an example: - -@smallexample -Emacs.pane.menubar.*.fontList: 8x16 -Emacs.pane.menubar.popup_*.fontList: 8x16 -@end smallexample - - To specify resources for the LessTif file-selection box, use -@samp{fsb*}, like this: - -@example -Emacs.fsb*.fontList: 8x16 -@end example - - Here is a list of resources for LessTif menu bars and pop-up menus: - -@table @code -@item armColor -The color to show in an armed button. -@item fontList -The font to use. -@item marginBottom -@itemx marginHeight -@itemx marginLeft -@itemx marginRight -@itemx marginTop -@itemx marginWidth -Amount of space to leave around the item, within the border. -@item borderWidth -The width of the border around the menu item, on all sides. -@item shadowThickness -The width of the border shadow. -@item bottomShadowColor -The color for the border shadow, on the bottom and the right. -@item topShadowColor -The color for the border shadow, on the top and the left. -@end table -@end ifnottex - -@node GTK resources -@appendixsec GTK resources -@cindex GTK+ resources -@cindex resource files for GTK -@cindex @file{~/.gtkrc-2.0} file -@cindex @file{~/.emacs.d/gtkrc} file - - If Emacs is compiled with GTK+ toolkit support, the simplest way to -customize its GTK+ widgets (e.g.@: menus, dialogs, tool bars and -scroll bars) is to choose an appropriate GTK+ theme, for example with -the GNOME theme selector. - - In GTK+ version 2, you can also use @dfn{GTK+ resources} to -customize the appearance of GTK+ widgets used by Emacs. These -resources are specified in either the file @file{~/.emacs.d/gtkrc} -(for Emacs-specific GTK+ resources), or @file{~/.gtkrc-2.0} (for -general GTK+ resources). We recommend using @file{~/.emacs.d/gtkrc}, -since GTK+ seems to ignore @file{~/.gtkrc-2.0} when running GConf with -GNOME. Note, however, that some GTK themes may override -customizations in @file{~/.emacs.d/gtkrc}; there is nothing we can do -about this. GTK+ resources do not affect aspects of Emacs unrelated -to GTK+ widgets, such as fonts and colors in the main Emacs window; -those are governed by normal X resources (@pxref{Resources}). - - The following sections describe how to customize GTK+ resources for -Emacs. For details about GTK+ resources, see the GTK+ API document at -@uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}. - - In GTK+ version 3, GTK+ resources have been replaced by a completely -different system. The appearance of GTK+ widgets is now determined by -CSS-like style files: @file{gtk-3.0/gtk.css} in the GTK+ installation -directory, and @file{~/.themes/@var{theme}/gtk-3.0/gtk.css} for local -style settings (where @var{theme} is the name of the current GTK+ -theme). Therefore, the description of GTK+ resources in this section -does not apply to GTK+ 3. For details about the GTK+ 3 styling -system, see -@uref{http://developer.gnome.org/gtk3/3.0/GtkCssProvider.html}. - -@menu -* GTK Resource Basics:: Basic usage of GTK+ resources. -* GTK Widget Names:: How GTK+ widgets are named. -* GTK Names in Emacs:: GTK widgets used by Emacs. -* GTK styles:: What can be customized in a GTK widget. -@end menu - -@node GTK Resource Basics -@appendixsubsec GTK Resource Basics - - In a GTK+ 2 resource file (usually @file{~/.emacs.d/gtkrc}), the -simplest kinds of resource settings simply assign a value to a -variable. For example, putting the following line in the resource -file changes the font on all GTK+ widgets to @samp{courier-12}: - -@smallexample -gtk-font-name = "courier 12" -@end smallexample - -@noindent -Note that in this case the font name must be supplied as a GTK font -pattern (also called a @dfn{Pango font name}), not as a -Fontconfig-style font name or XLFD. @xref{Fonts}. - - To customize widgets you first define a @dfn{style}, and then apply -the style to the widgets. Here is an example that sets the font for -menus (@samp{#} characters indicate comments): - -@smallexample -# @r{Define the style @samp{my_style}.} -style "my_style" -@{ - font_name = "helvetica bold 14" -@} - -# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{my_style}.} -widget "*emacs-menuitem*" style "my_style" -@end smallexample - -@noindent -The widget name in this example contains wildcards, so the style is -applied to all widgets matching @samp{*emacs-menuitem*}. The widgets -are named by the way they are contained, from the outer widget to the -inner widget. Here is another example that applies @samp{my_style} -specifically to the Emacs menu bar: - -@smallexample -widget "Emacs.pane.menubar.*" style "my_style" -@end smallexample - - Here is a more elaborate example, showing how to change the parts of -the scroll bar: - -@smallexample -style "scroll" -@{ - fg[NORMAL] = "red"@ @ @ @ @ # @r{Arrow color.} - bg[NORMAL] = "yellow"@ @ # @r{Thumb and background around arrow.} - bg[ACTIVE] = "blue"@ @ @ @ # @r{Trough color.} - bg[PRELIGHT] = "white"@ # @r{Thumb color when the mouse is over it.} -@} - -widget "*verticalScrollBar*" style "scroll" -@end smallexample - -@node GTK Widget Names -@appendixsubsec GTK widget names -@cindex GTK widget names - - A GTK+ widget is specified by a @dfn{widget name} and a @dfn{widget -class}. The widget name refers to a specific widget -(e.g.@: @samp{emacs-menuitem}), while the widget class refers to a -collection of similar widgets (e.g.@: @samp{GtkMenuItem}). A widget -always has a class, but need not have a name. - - @dfn{Absolute names} are sequences of widget names or widget -classes, corresponding to hierarchies of widgets embedded within -other widgets. For example, if a @code{GtkWindow} named @code{top} -contains a @code{GtkVBox} named @code{box}, which in turn contains -a @code{GtkMenuBar} called @code{menubar}, the absolute class name -of the menu-bar widget is @code{GtkWindow.GtkVBox.GtkMenuBar}, and -its absolute widget name is @code{top.box.menubar}. - - GTK+ resource files can contain two types of commands for specifying -widget appearances: - -@table @code -@item widget -specifies a style for widgets based on the class name, or just the -class. - -@item widget_class -specifies a style for widgets based on the class name. -@end table - -@noindent -See the previous subsection for examples of using the @code{widget} -command; the @code{widget_class} command is used similarly. Note that -the widget name/class and the style must be enclosed in double-quotes, -and these commands must be at the top level in the GTK+ resource file. - - As previously noted, you may specify a widget name or class with -shell wildcard syntax: @samp{*} matches zero or more characters and -@samp{?} matches one character. This example assigns a style to all -widgets: - -@smallexample -widget "*" style "my_style" -@end smallexample - -@node GTK Names in Emacs -@appendixsubsec GTK Widget Names in Emacs -@cindex GTK widget names -@cindex GTK widget classes - - The GTK+ widgets used by an Emacs frame are listed below: - -@table @asis -@item @code{Emacs} (class @code{GtkWindow}) -@table @asis -@item @code{pane} (class @code{GtkVBox}) -@table @asis -@item @code{menubar} (class @code{GtkMenuBar}) -@table @asis -@item [menu item widgets] -@end table -@item [unnamed widget] (class @code{GtkHandleBox}) -@table @asis -@item @code{emacs-toolbar} (class @code{GtkToolbar}) -@table @asis -@item [tool bar item widgets] -@end table -@end table -@item @code{emacs} (class @code{GtkFixed}) -@table @asis -@item @code{verticalScrollBar} (class @code{GtkVScrollbar}) -@end table -@end table -@end table -@end table - -@noindent -The contents of Emacs windows are drawn in the @code{emacs} widget. -Note that even if there are multiple Emacs windows, each scroll bar -widget is named @code{verticalScrollBar}. - - For example, here are two different ways to set the menu bar style: - -@smallexample -widget "Emacs.pane.menubar.*" style "my_style" -widget_class "GtkWindow.GtkVBox.GtkMenuBar.*" style "my_style" -@end smallexample - - For GTK+ dialogs, Emacs uses a widget named @code{emacs-dialog}, of -class @code{GtkDialog}. For file selection, Emacs uses a widget named -@code{emacs-filedialog}, of class @code{GtkFileSelection}. - - Because the widgets for pop-up menus and dialogs are free-standing -windows and not ``contained'' in the @code{Emacs} widget, their GTK+ -absolute names do not start with @samp{Emacs}. To customize these -widgets, use wildcards like this: - -@smallexample -widget "*emacs-dialog*" style "my_dialog_style" -widget "*emacs-filedialog* style "my_file_style" -widget "*emacs-menuitem* style "my_menu_style" -@end smallexample - - If you want to apply a style to all menus in Emacs, use this: - -@smallexample -widget_class "*Menu*" style "my_menu_style" -@end smallexample - -@node GTK styles -@appendixsubsec GTK styles -@cindex GTK styles - - Here is an example of two GTK+ style declarations: - -@smallexample -pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" - -style "default" -@{ - font_name = "helvetica 12" - - bg[NORMAL] = @{ 0.83, 0.80, 0.73 @} - bg[SELECTED] = @{ 0.0, 0.55, 0.55 @} - bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @} - bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @} - bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @} - - fg[NORMAL] = "black" - fg[SELECTED] = @{ 0.9, 0.9, 0.9 @} - fg[ACTIVE] = "black" - fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @} - - base[INSENSITIVE] = "#777766" - text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @} - - bg_pixmap[NORMAL] = "background.xpm" - bg_pixmap[INSENSITIVE] = "background.xpm" - bg_pixmap[ACTIVE] = "background.xpm" - bg_pixmap[PRELIGHT] = "" - -@} - -style "ruler" = "default" -@{ - font_name = "helvetica 8" -@} - -@end smallexample - - The style @samp{ruler} inherits from @samp{default}. This way you can build -on existing styles. The syntax for fonts and colors is described below. - - As this example shows, it is possible to specify several values for -foreground and background depending on the widget's @dfn{state}. The -possible states are: - -@table @code -@item NORMAL -This is the default state for widgets. -@item ACTIVE -This is the state for a widget that is ready to do something. It is -also for the trough of a scroll bar, i.e.@: @code{bg[ACTIVE] = "red"} -sets the scroll bar trough to red. Buttons that have been pressed but -not released yet (``armed'') are in this state. -@item PRELIGHT -This is the state for a widget that can be manipulated, when the mouse -pointer is over it---for example when the mouse is over the thumb in -the scroll bar or over a menu item. When the mouse is over a button -that is not pressed, the button is in this state. -@item SELECTED -This is the state for data that has been selected by the user. It can -be selected text or items selected in a list. This state is not used -in Emacs. -@item INSENSITIVE -This is the state for widgets that are visible, but they can not be -manipulated in the usual way---for example, buttons that can't be -pressed, and disabled menu items. To display disabled menu items in -yellow, use @code{fg[INSENSITIVE] = "yellow"}. -@end table - - Here are the things that can go in a style declaration: - -@table @code -@item bg[@var{state}] = @var{color} -This specifies the background color for the widget. Note that -editable text doesn't use @code{bg}; it uses @code{base} instead. - -@item base[@var{state}] = @var{color} -This specifies the background color for editable text. In Emacs, this -color is used for the background of the text fields in the file -dialog. - -@item bg_pixmap[@var{state}] = "@var{pixmap}" -This specifies an image background (instead of a background color). -@var{pixmap} should be the image file name. GTK can use a number of -image file formats, including XPM, XBM, GIF, JPEG and PNG. If you -want a widget to use the same image as its parent, use -@samp{}. If you don't want any image, use @samp{}. -@samp{} is the way to cancel a background image inherited from a -parent style. - -You can't specify the file by its absolute file name. GTK looks for -the pixmap file in directories specified in @code{pixmap_path}. -@code{pixmap_path} is a colon-separated list of directories within -double quotes, specified at the top level in a @file{gtkrc} file -(i.e.@: not inside a style definition; see example above): - -@smallexample -pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" -@end smallexample - -@item fg[@var{state}] = @var{color} -This specifies the foreground color for widgets to use. It is the -color of text in menus and buttons, and the color for the arrows in -the scroll bar. For editable text, use @code{text}. - -@item text[@var{state}] = @var{color} -This is the color for editable text. In Emacs, this color is used for the -text fields in the file dialog. - -@item font_name = "@var{font}" -This specifies the font for text in the widget. @var{font} is a -GTK-style (or Pango) font name, like @samp{Sans Italic 10}. -@xref{Fonts}. The names are case insensitive. -@end table - - There are three ways to specify a color: a color name, an RGB -triplet, or a GTK-style RGB triplet. @xref{Colors}, for a description -of color names and RGB triplets. Color names should be enclosed with -double quotes, e.g.@: @samp{"red"}. RGB triplets should be written -without double quotes, e.g.@: @samp{#ff0000}. GTK-style RGB triplets -have the form @w{@code{@{ @var{r}, @var{g}, @var{b} @}}}, where -@var{r}, @var{g} and @var{b} are either integers in the range 0-65535 -or floats in the range 0.0-1.0. diff --git a/doc/lispintro/ChangeLog b/doc/lispintro/ChangeLog deleted file mode 100644 index 76397c3ee89..00000000000 --- a/doc/lispintro/ChangeLog +++ /dev/null @@ -1,535 +0,0 @@ -2012-06-01 Chong Yidong - - * Version 24.1 released. - -2012-05-04 Glenn Morris - - * emacs-lisp-intro.texi (Making Errors): Don't mention Emacs 20. - (Void Function, Wrong Type of Argument, Recursion with list) - (Simple Extension): Assume a non-ancient Emacs. - (Void Variable, Switching Buffers): Improve page breaks. - -2012-05-03 Glenn Morris - - * emacs-lisp-intro.texi: Update GNU Press contact details. - -2012-04-28 Glenn Morris - - * emacs-lisp-intro.texi (Syntax): Reword to avoid underfull hbox. - -2012-04-07 Glenn Morris - - * Makefile.in: Replace non-portable use of $< in ordinary rules. - -2012-02-28 Glenn Morris - - * emacs-lisp-intro.texi: Standardize possessive apostrophe usage. - -2012-02-17 Glenn Morris - - * emacs-lisp-intro.texi (Design @value{COUNT-WORDS}, Syntax) - (count-words-in-defun): Fix cross-refs to Emacs manual. - -2012-01-28 Andreas Schwab - - * emacs-lisp-intro.texi (Top): Move setting of COUNT-WORDS outside - of @menu. (Bug#10628) - -2012-01-19 Juanma Barranquero - - * emacs-lisp-intro.texi (count-words-in-defun): - Add missing parenthesis (bug#10544). - -2012-01-17 Glenn Morris - - * emacs-lisp-intro.texi (re-search-forward): Fix typo. - -2011-11-24 Juanma Barranquero - - * makefile.w32-in: Update dependencies. - -2011-11-16 Juanma Barranquero - - * emacs-lisp-intro.texi (etags): Fix typo. - -2011-03-07 Chong Yidong - - * Version 23.3 released. - -2011-02-19 Eli Zaretskii - - * emacs-lisp-intro.texi: Sync @dircategory with ../../info/dir. - -2011-01-23 Werner Lemberg - - * Makefile.in (MAKEINFO): Now controlled by `configure'. - (MAKEINFO_OPTS): New variable. Use it where appropriate. - (ENVADD): New variable to control texi2dvi and texi2pdf. - -2010-11-13 Glenn Morris - - * emacs-lisp-intro.texi: Rename the `count-words-region' example, - since there is now a standard command of that name. - -2010-10-11 Glenn Morris - - * Makefile.in (.dvi.ps): Remove unnecessary suffix rule. - (.PHONY): Add ps. - (ps, emacs-lisp-intro.ps): New targets. - (clean): Delete ps file. - (MAKEINFO): Use --force like the other doc/ Makefiles do. - Add explicit -I$srcdir. - -2010-10-09 Glenn Morris - - * Makefile.in (VPATH): Remove. - (infodir): Make it absolute. - (mkinfodir, $(infodir)/eintr, infoclean): No need to cd $srcdir. - - * Makefile.in (dist): Anchor regexps. - - * Makefile.in (${infodir}/eintr, emacs-lisp-intro.dvi) - (emacs-lisp-intro.pdf, emacs-lisp-intro.html): Use $<. - - * Makefile.in (infoclean): Remove harmless, long-standing error. - - * Makefile.in ($(infodir)): Delete rule. - (mkinfodir): New. - ($(infodir)/eintr): Use $mkinfodir instead of infodir. - -2010-10-09 Glenn Morris - - * Makefile.in (.PHONY): Declare info, dvi, html, pdf, dist. - -2010-10-07 Glenn Morris - - * Makefile.in (version): New, set by configure. - (clean): Delete dist tar file. - (dist): Use version in tar name. - -2010-10-06 Glenn Morris - - * Makefile.in (SHELL): Use /bin/sh, like every other Makefile.in. - (INFO_SOURCES, INFO_TARGETS, DVI_TARGETS): Remove variables. - ($(infodir), html, pdf, infoclean, dist): New rules. - (${infodir}/eintr): Ensure $infodir exists. Use $@. - (emacs-lisp-intro.dvi, emacs-lisp-intro.pdf, emacs-lisp-intro.html): - Use $^. - (.PHONY): Declare clean rules. - (mostlyclean): Delete more temp files. - (clean): Delete specific dvi, pdf and html files. - (maintainer-clean): Use infoclean. - (.NOEXPORT): Remove, unused by any other Makefile.in. - -2010-09-21 Glenn Morris - - * cons-1.eps, cons-2.eps, cons-2a.eps, cons-3.eps, cons-4.eps: - * cons-5.eps, lambda-1.eps, lambda-2.eps, lambda-3.eps: - Add first line EPSF magic comment. (Bug#7064) - -2010-06-23 Glenn Morris - - * emacs-lisp-intro.texi: Untabify. - -2010-05-07 Chong Yidong - - * Version 23.2 released. - -2010-03-10 Chong Yidong - - * Branch for 23.2. - -2010-02-16 Glenn Morris - - * emacs-lisp-intro.texi: Fix typo in name of `find-tag' command. - -2010-02-01 Stefan Monnier - - * emacs-lisp-intro.texi (Text and Auto-fill, Mode Line): - Avoid obsolete special default variables like default-major-mode. - -2009-12-09 David Robinow (tiny change) - - * makefile.w32-in: Use parenthesis for macros for nmake compatibility. - -2009-12-03 Glenn Morris - - * emacs-lisp-intro.texi (Free Software and Free Manuals): - Update URL, and remove duplicate text. - -2009-10-28 Robert J. Chassell - - * emacs-lisp-intro.texi: Don't change urlcolor or linkcolor in tex - output (not needed and does not work with recent texinfo.tex). - Bump edition number. - -2009-10-27 Robert J. Chassell - - * emacs-lisp-intro.texi: Bump edition number. - -2009-10-27 Glenn Morris - - * cons-1.pdf, cons-2.pdf, cons-2a.pdf, cons-3.pdf, cons-4.pdf: - * cons-5.pdf, drawers.pdf, lambda-1.pdf, lambda-2.pdf, lambda-3.pdf: - New files, generated from .eps versions with epstopdf. - * README: Add copyright information for PDF images. - - * Makefile.in (TEXI2PDF): New variable. - (emacs-lisp-intro.pdf): New target. - - * makefile.w32-in (texinfodir, TEXI2PDF): New variables. - (ENVADD): Add -I$texinfodir. - (emacs-lisp-intro.pdf): New target. - -2009-07-28 Chong Yidong - - * emacs-lisp-intro.texi (Simple Extension): Bump emacs versions in - examples. - -2009-07-10 Glenn Morris - - * emacs-lisp-intro.texi (Top): Add missing @detailmenu entry. - -2009-07-09 Glenn Morris - - * Makefile.in (texinfodir): Rename from usermanualdir, and update. - -2009-07-06 Glenn Morris - - * emacs-lisp-intro.texi (defvar and asterisk): Minor rephrasing. - -2009-06-21 Chong Yidong - - * Branch for 23.1. - -2009-06-14 Chong Yidong - - * emacs-lisp-intro.texi (edebug): Fix typo. - -2009-02-22 Karl Berry - - * emacs-lisp-intro.texi (Default Configuration): Fix dup word "by by". - -2009-02-20 Juanma Barranquero - - * emacs-lisp-intro.texi (current-kill, Code for current-kill) - (Body of current-kill): Remove duplicate words. - -2008-11-19 Glenn Morris - - * doclicense.texi: New file. - * emacs-lisp-intro.texi: Relicense under FDL 1.3 or later. - Include doclicense.texi rather than having license in the file itself. - -2008-10-16 Sean Sieger (tiny change) - - * emacs-lisp-intro.texi (Recursion with list): Fix typo. - -2008-10-04 Karl Berry - - * emacs-lisp-intro.texi: Apply similar formatting changes as for - the emacs and lispref manuals, to save pages. A couple minor - rewordings and reformatting of code to avoid overfull and - underfull lines. - (edition-number): Bump to 3.08. - (update-date): Bump to 4 October 2008. - -2008-06-20 Eli Zaretskii - - * makefile.w32-in (distclean): Remove makefile. - -2008-06-16 Glenn Morris - - * Makefile.am, Makefile.old, aclocal.m4, configure, configure.in: - * install-sh, missing, mkinstalldirs: Remove obsolete files. - -2008-05-13 Chong Yidong - - * emacs-lisp-intro.texi (Lisp Atoms): Rephrase "in addition" to - avoid confusion with addition operation discussed in previous - paragraph. - -2008-01-31 Robert J. Chassell - - * emacs-lisp-intro.texi: Update back cover text. - -2007-09-12 Robert J. Chassell - - * emacs-lisp-intro.texi: Add email address to Thank You correctly. - -2007-09-06 Romain Francoise - - * Makefile.in (maintainer-clean): Delete info files. - -2007-09-06 Glenn Morris - - Move from lispintro/ to doc/lispintro/. - * Makefile.in (infodir): Go up one more level. - (usermanualdir): Change from ../man to ../emacs. - * makefile.w32-in (infodir, ENVADD): Go up one more level. - * emacs-lisp-intro.texi (setfilename): Go up one more level. - -2007-07-30 Robert J. Chassell - - * emacs-lisp-intro.texi: Fix typo on line 5173, change `thee' to - `these'. - -2007-07-25 Glenn Morris - - * Relicense all FSF files to GPLv3 or later. - -2007-06-02 Chong Yidong - - * Version 22.1 released. - -2007-01-30 Robert J. Chassell - - * emacs-lisp-intro.texi (else): Rephrase message of first - if-then-else example so it is right both in itself and in the - "true" case of the expression, which asks whether 4 is greater - than 5. - -2006-11-27 Andreas Schwab - - * Makefile.in (usermanualdir): Define. - (emacs-lisp-intro.dvi): Pass -I options to texi2dvi instead of - using TEXINPUTS. - - * emacs-lisp-intro.texi: Input texinfo instead of ../man/texinfo - to fix building outside source directory. - -2006-11-09 Robert J. Chassell - - * emacs-lisp-intro.texi: Copy descriptions from detailed master - menu to menus within body. - - * emacs-lisp-intro.texi (at the beginning): Add `other shell - commands' to produce additional output formats; total is now ten. - (A Loop with an Incrementing Counter, and others): Ensure Info - menus will appear in short windows. - (Disentangle beginning-of-buffer): Replace `version 21' with `more - recent versions'. - (Simple Extension): Show how to handle multiple versions by adding - an alternative with a test of `>= 21'. - -2006-11-06 Robert J. Chassell - - * emacs-lisp-intro.texi: Finish minor changes seen from DVI output. - Replace 22.1.100 with 22.1.1. - (current-kill): Mention functions that directly or indirectly call - `kill-new', which sets `kill-ring-yank-pointer'. - (Understanding current-kill): Change `lasted' to `last'. Remove - extraneous parenthesis. Reword item about returning `car' of list. - (yank): Remove mention of `rotate-yank-pointer'. - (Y Axis Element): Add comment regarding replacement of blank space. - (print-Y-axis Penultimate): Explain that `print-graph' will pass - `height-of-top-line' so `print-Y-axis' does not have a bug. - -2006-11-05 Robert J. Chassell - - * emacs-lisp-intro.texi: Yet more minor changes: - (defcustom): Said that `:options' is usually for a hook. Remove - extraneous space in parenthetical remark concerning - `text-mode-hook-identify'. At end, mention other defines, too. - (Beginning a .emacs File): Reverse words about comments so they - parallel numbers of listed semi-colons. - (Text and Auto-fill): Remove extraneous blank line in example. - (Mail Aliases): Remove extraneous blank line in example. - (Keybindings): Reformat as needed with `key' rather than `kbd'. - (Keybindings, Miscellaneous, Mode Line): For small book format, start - section name on top of new page. - (Simple Extension): Replace longer expression with - `emacs-major-version'. Remove comment about `number-to-string' - function. - (Miscellaneous): Add filename option, `-H', to `grep' example. - (debug, debug-on-entry): Replace `GNU Emacs 22' with `a recent - GNU Emacs'. - (edebug): More properly state where to place point for 'M-x - edebug-defun'. - - * emacs-lisp-intro.texi: More minor changes. - Center images for TeX output. - (kill-new function): Remove indentation for sentence talking about - momentarily skipping code. - (cons & search-fwd Review): Document @code{funcall}. Document - @code{re-search-forward} with existing @code{search-forward}. - Reference chapter on regular expression searches. - (Recursion with list): Specify a more recent version as being Emacs. - (Recursion with list, Every, recursive-graph-body-print): Change - `if ... progn' expression to `when'. - (Recursive triangle function): For printing in small book, ensure - section name is not last on bottom of preceding page. - (Keep): Remove extraneous space in function definition example. - (sentence-end): Specify `in English' for glyphs that end a sentence. - Note that in GNU Emacs 22, the name refers to both a variable and a - function. - (fwd-sentence while loops): Write a function as one, not as a form. - (fwd-para let): Add `which' to sentence with `parstart' and `parsep'. - (etags): Move sentences involving `find-tag' and sources. State - location of Emacs `src' directory. - (Design count-words-region): Better explain two backslashes in a row. - (Find a File): Fix grammar; add a `to' and write `to visit'. Change - `named' to `selected'. - (lengths-list-file): Remove extraneous parenthesis from reference. - (lengths-list-many-files): Explain `expand-file-name' better. - (Files List): Rephrase sentence regarding Lisp sources directory - -2006-11-04 Robert J. Chassell - - * emacs-lisp-intro.texi: Replace 22.0.100 with 22.1.100. - (defcustom): Note that the value set by defconst is a variable. - (Buffer Size & Locations): Parenthetical remark about evaluation. - (Finding More): Change text to include C sources by inference. - - * emacs-lisp-intro.texi: Minor fixes. - Replace all tabs with eight spaces each so printed text looks correct. - Remove extraneous comma in a printed node name produced by `ref'. - (insert-buffer): Add a missing beginning parenthesis. - (beginning-of-buffer): Add `beginning of' to note about accessible - portion. - (narrow Exercise): Write closing parenthesis at end of correct - paragraph. - (zap-to-char): Remove extraneous `a' from first sentence. - (Complete zap-to-char): Remove two extraneous sentences. - (zap-to-char body): Move sentences on documentation two nodes earlier. - (Lisp macro): Add definition of `unless' macro. - (last-command & this-command): Remove comment that `we have not yet - seen' the @code{eq} function. - (kill-append function): Reformat `kill-append' function definition so - it prints well. - (kill-new function): Indent the sentence beginning `notice'. Replace - `the same as' with `similar to'. Repair typo. Remove obsolete - references to `yank' and `yank-pop. End section with a note that `we - will digress into C.' - -2006-11-02 Robert J. Chassell - - * emacs-lisp-intro.texi (kill-ring-yank-pointer): Revert addition - of extraneous quotation mark to rotate-yank-pointer. - -2006-11-01 Juri Linkov - - * emacs-lisp-intro.texi: Fix unbalanced quotes. - -2006-10-31 Robert J. Chassell - - * emacs-lisp-intro.texi: Revised text for kill-region, - copy-region-as-kill, kill-append, kill-new, forward-sentence, - forward-paragraph, find-file, current-kill, yank, and yank-pop. - Removed INSTALL MANIFEST from the directory since those files are - now irrelevant. Updated Info file in ../info. Changed numbering - so is now Revised Third Edition and this instance's edition-number - is 3.00. Did not update ISBN number. - - * emacs-lisp-intro.texi: Remove version reference for X colors. - Document `='. Remove mention that :eval was new in 21. Updated - instance's edition-number to 3.01. - -2006-10-30 Robert J. Chassell - - * emacs-lisp-intro.texi: Many changes since it turned out that - many `simple' functions were rewritten. Changes to the text - regarding zap-to-char, mark-whole-buffer, append-to-buffer, - copy-to-buffer, beginning-of-buffer, what-line, and possibly - others. (I have not reviewed all yet.) This instance does build - for Info and TeX. - -2006-10-29 Chong Yidong - - * Makefile.in: Use relative paths to avoid advertising filesystem - contents during compilation. - -2006-08-21 Robert J. Chassell - - * emacs-lisp-intro.texi: Deleted in directory copy of texinfo.tex - and pointed towards ../man/texinfo.tex so only one file - needs updating. Added comment of what to do when building on own. - - * texinfo.tex: Changed to version 2006-02-13.16 - to enable a DVI build using the more recent versions of TeX. - -2006-05-25 David Kastrup - - * emacs-lisp-intro.texi (setcar): Replace an antelope rather than - a giraffe with a hippopotamus. - -2006-05-19 Thien-Thi Nguyen - - * emacs-lisp-intro.texi (Digression concerning error): Fix typo. - -2005-09-16 Romain Francoise - - * emacs-lisp-intro.texi (GNU Free Documentation License): - Specify GFDL version 1.2. - -2005-07-30 Eli Zaretskii - - * makefile.w32-in (info): Don't run install-info. - ($(infodir)/dir): New target, produced by running install-info. - -2005-07-04 Lute Kamstra - - Update FSF's address in GPL notices. - - * emacs-lisp-intro.texi: Update FSF's address. - -2004-04-23 Juanma Barranquero - - * makefile.w32-in: Add "-*- makefile -*-" mode tag. - -2004-02-29 Juanma Barranquero - - * makefile.w32-in (mostlyclean, clean, maintainer-clean): - Use $(DEL) instead of rm, and ignore exit code. - -2003-11-16 Kevin Ryde - - * emacs-lisp-intro.texi: [CVS commitment by ] - Corrections to cross references. - (Interactive Options): elisp "interactive" -> "Using Interactive". - (defvar and asterisk): Remove emacs "Edit Options" reference, - edit-options is no longer described in the emacs manual. - (Lists diagrammed): elisp "List Type" -> "Cons Cell Type". - -2003-09-03 Peter Runestig - - * makefile.w32-in: New file. - -2001-11-29 Eli Zaretskii - - * emacs-lisp-intro.texi (Index): @ignore extraneous text. - Use @dircategory and @direntry to define the DIR entry. - -2001-11-25 Robert J. Chassell - - * emacs-lisp-intro.texi: Move @contents to the beginning of the - file. Set the size to @smallbook. - -2001-11-24 Eli Zaretskii - - * Makefile.in: New file. - - * README: Update. - - * *.eps: Rename to avoid clashes in DOS 8+3 namespace. - -;; Local Variables: -;; coding: utf-8 -;; End: - - Copyright (C) 2001-2012 Free Software Foundation, Inc. - - This file is part of GNU Emacs. - - GNU Emacs is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - GNU Emacs is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNU Emacs. If not, see . diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in deleted file mode 100644 index c638dd6135f..00000000000 --- a/doc/lispintro/Makefile.in +++ /dev/null @@ -1,101 +0,0 @@ -#### Makefile for the Emacs Lisp Introduction manual - -# Copyright (C) 1994-1999, 2001-2012 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -SHELL = /bin/sh - -srcdir = @srcdir@ -version=@version@ - -infodir = $(srcdir)/../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc - -MAKEINFO = @MAKEINFO@ -MAKEINFO_OPTS = --force -I $(srcdir) -TEXI2DVI = texi2dvi -TEXI2PDF = texi2pdf -DVIPS = dvips - -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" - -mkinfodir = @test -d ${infodir} || mkdir ${infodir} || test -d ${infodir} - -.PHONY: info dvi html pdf ps - -info: ${infodir}/eintr - -dvi: emacs-lisp-intro.dvi -html: emacs-lisp-intro.html -pdf: emacs-lisp-intro.pdf -ps: emacs-lisp-intro.ps - -# The file name eintr must fit within 5 characters, to allow for -# -NN extensions to fit into DOS 8+3 limits without clashing. -# Note: "<" is not portable in ordinary make rules. -${infodir}/eintr: ${srcdir}/emacs-lisp-intro.texi - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) -o $@ ${srcdir}/emacs-lisp-intro.texi - -emacs-lisp-intro.dvi: ${srcdir}/emacs-lisp-intro.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-lisp-intro.texi - -emacs-lisp-intro.ps: emacs-lisp-intro.dvi - $(DVIPS) -o $@ emacs-lisp-intro.dvi - -emacs-lisp-intro.pdf: ${srcdir}/emacs-lisp-intro.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-lisp-intro.texi - -emacs-lisp-intro.html: ${srcdir}/emacs-lisp-intro.texi - $(MAKEINFO) $(MAKEINFO_OPTS) --html -o $@ ${srcdir}/emacs-lisp-intro.texi - -.PHONY: mostlyclean clean distclean maintainer-clean infoclean - -mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs - -clean: mostlyclean - rm -f emacs-lisp-intro.dvi emacs-lisp-intro.pdf emacs-lisp-intro.ps - rm -rf emacs-lisp-intro.html/ - rm -f emacs-lispintro-${version}.tar* - -distclean: clean - -infoclean: - -cd $(infodir) && rm -f eintr eintr-[1-9] - -maintainer-clean: distclean infoclean - -.PHONY: dist - -dist: - rm -rf emacs-lispintro-${version} - mkdir emacs-lispintro-${version} - cp ${srcdir}/*.texi ${srcdir}/*.eps ${srcdir}/*.pdf \ - ${texinfodir}/texinfo.tex \ - ${srcdir}/ChangeLog* ${srcdir}/README emacs-lispintro-${version}/ - sed -e 's/@sr[c]dir@/./' -e 's/^\(texinfodir *=\).*/\1 ./' \ - -e 's/^\(infodir *=\).*/\1 ./' -e 's/^\(clean:.*\)/\1 infoclean/' \ - -e "s/@ver[s]ion@/${version}/" \ - ${srcdir}/Makefile.in > emacs-lispintro-${version}/Makefile - tar -cf emacs-lispintro-${version}.tar emacs-lispintro-${version} - rm -rf emacs-lispintro-${version} - -### Makefile ends here diff --git a/doc/lispintro/README b/doc/lispintro/README deleted file mode 100644 index d81a6bc2a3a..00000000000 --- a/doc/lispintro/README +++ /dev/null @@ -1,82 +0,0 @@ -Copyright (C) 2001-2012 Free Software Foundation, Inc. -See the end of the file for license conditions. - - -This directory contains the source of the "Introduction to Programming -in Emacs Lisp" written by Robert J. Chassell, bob@gnu.org. This -manual is an elementary introduction to programming in Emacs Lisp for -people who are not programmers, and who are not necessarily interested -in programming, but who do want to customize or extend their computing -environment. - -This third edition of 2006 Oct 31 updates the previous editions to GNU -Emacs 22. - -The Texinfo source file `emacs-lisp-intro.texi', formats without -reported error using `pdfeTeXk', Version 3.141592-1.21a-2.2 (Web2C -7.5.4) and texinfo.tex version 2006-08-26.17 started by `texi2dvi' -version 4.8, and with `makeinfo' version 4.8. - -This directory contains the following Encapsulated PostScript figures: - - cons-1.eps, cons-2.eps, cons-2a.eps, cons-3.eps, cons-4.eps, cons-5.eps - drawers.eps, lambda-1.eps, lambda-2.eps, lambda-3.eps - -See the beginning of the `emacs-lisp-intro.texi' file for appropriate -settings. These figures are not necessary; they are merely nice to -look at --- without them you get the same figures printed with ASCII -characters. - -Whether and how you print PostScript depends on your site. You not -only need to set 'print-postscript-figures' before creating the .dvi -file, but then must convert the .dvi file to .ps with a 'dvips' or -equivalent command. - -On some systems you will see an error message when `psfig.tex' is -loaded for the last two .eps files: - - ! No room for a new \write . - -If this happens, try `epsf.tex' instead of `psfig.tex', or try typing -RET at the error; the formatting may continue successfully. - -Or else find the section that says: - - @c !!! Clear print-postscript-figures if the computer formatting this - @c document is too small and cannot handle all the diagrams and figures. - @c clear print-postscript-figures - -and change the file so it reads: @clear print-postscript-figures -This will prevent TeX from attempting to load the last few .eps files. - -You will find additional instructions on formatting in the beginning -of the Texinfo file 'emacs-lisp-intro.texi'. Best Wishes! - -2006 Oct 31 -Robert J. Chassell, bob@gnu.org - - - -COPYRIGHT AND LICENSE INFORMATION FOR IMAGE FILES - -The PostScript images (*.eps) contain copyright and license information -in their headers. The PDF versions were automatically generated using -the epstopdf utility, and are subject to the same conditions as their -EPS counterparts. - - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/doc/lispintro/cons-1.eps b/doc/lispintro/cons-1.eps deleted file mode 100644 index d17082f5ac7..00000000000 --- a/doc/lispintro/cons-1.eps +++ /dev/null @@ -1,578 +0,0 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%BoundingBox: 35 711 289 757 -%%Title: cons-cell-diagram1 -%%CreationDate: Wed Mar 8 14:26:58 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) - -% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 35 711 289 757 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% BOX -gsave - 1.415 setmiterlimit - newpath - 66 66 moveto 130 66 lineto 130 98 lineto 66 98 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 98 66 moveto - 98 98 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 114 82 moveto - 0 80 atan dup cos 8 mul 194 exch sub - exch sin 8 mul 82 exch sub lineto - stroke -grestore -gsave - newpath - 194 82 8 3 80 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 146 136 moveto (rose) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 82 82 moveto - 82 131 lineto - 0 48 atan dup cos 8 mul 130 exch sub - exch sin 8 mul 131 exch sub lineto - stroke -grestore -gsave - newpath - 130 131 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 199 66 moveto 263 66 lineto 263 98 lineto 199 98 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 231 66 moveto - 231 98 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 247 82 moveto - 0 93 atan dup cos 8 mul 340 exch sub - exch sin 8 mul 82 exch sub lineto - stroke -grestore -gsave - newpath - 340 82 8 3 93 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 279 136 moveto (violet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 215 82 moveto - 215 131 lineto - 0 48 atan dup cos 8 mul 263 exch sub - exch sin 8 mul 131 exch sub lineto - stroke -grestore -gsave - newpath - 263 131 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 342 64 moveto 406 64 lineto 406 96 lineto 342 96 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 373 64 moveto - 373 96 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 389 81 moveto - 0 48 atan dup cos 8 mul 437 exch sub - exch sin 8 mul 81 exch sub lineto - stroke -grestore -gsave - newpath - 437 81 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 421 135 moveto (buttercup) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 357 81 moveto - 357 130 lineto - 0 48 atan dup cos 8 mul 405 exch sub - exch sin 8 mul 130 exch sub lineto - stroke -grestore -gsave - newpath - 405 130 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 449 87 moveto (nil) show - grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:26:58 1995 diff --git a/doc/lispintro/cons-1.pdf b/doc/lispintro/cons-1.pdf deleted file mode 100644 index 2ee86b12311..00000000000 --- a/doc/lispintro/cons-1.pdf +++ /dev/null @@ -1,71 +0,0 @@ -%PDF-1.3 -%Ç쏢 -5 0 obj -<> -stream -xœ“ËNÃ0E÷󳄍ñøí-bÕEi¾€*EE ¥/ø}lÇvݖnªH‰æú:¾s2Ù"g„<^ù¹áéÍâÇ43Bã/S¤q„kàø -‚XЅvÌj”†#9Ž»Á1ÁÓ²’iy,u¶Á%|R¤ÊãMSGÇ°ê—$播fÊ9À -¶@©̏åˆÏ]hÇ¡g:šºL]*Ë(ædAáa·Ù÷Ý'¼t0¢ó³smeÚ2€”æ¬^€t­c,îuƒç)fjgÒÞFéÕ´^Y¡I\Í5Y5YvF“BëL_;*É"ÜI’Â@ø¡ üYo†þPa:=…®ç¡â#îTì¡áI$|#ÕSˆ–ú)é°#²üš'ف*Íãs­éH'S-µJñâèÙ*ixÃÁ7\2BNµ%vÍø¿¸°]3žVÐ÷ãáÐï–ÇïӀ}‘¢(6vrN¶uèϋÆ1V‡©cßˆ8D&d§ä_ë¡fžÃՊâendstream -endobj -6 0 obj -390 -endobj -4 0 obj -<> -/Contents 5 0 R ->> -endobj -3 0 obj -<< /Type /Pages /Kids [ -4 0 R -] /Count 1 ->> -endobj -1 0 obj -<> -endobj -7 0 obj -<>endobj -9 0 obj -<> -endobj -10 0 obj -<> -endobj -8 0 obj -<> -endobj -2 0 obj -<>endobj -xref -0 11 -0000000000 65535 f -0000000702 00000 n -0000000912 00000 n -0000000643 00000 n -0000000494 00000 n -0000000015 00000 n -0000000475 00000 n -0000000750 00000 n -0000000850 00000 n -0000000791 00000 n -0000000820 00000 n -trailer -<< /Size 11 /Root 1 0 R /Info 2 0 R -/ID [(ª@}`&¿ÆÈ'S©‚Ü)(ª@}`&¿ÆÈ'S©‚Ü)] ->> -startxref -1023 -%%EOF diff --git a/doc/lispintro/cons-2.eps b/doc/lispintro/cons-2.eps deleted file mode 100644 index bd227a14c03..00000000000 --- a/doc/lispintro/cons-2.eps +++ /dev/null @@ -1,600 +0,0 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%BoundingBox: 15 712 321 775 -%%Title: cons-cell-diagram2 -%%CreationDate: Wed Mar 8 14:26:39 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) - -% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 15 712 321 775 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 32 47 moveto (bouquet) show - grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 122 65 moveto 186 65 lineto 186 97 lineto 122 97 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 154 65 moveto - 154 97 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 170 81 moveto - 0 80 atan dup cos 8 mul 250 exch sub - exch sin 8 mul 81 exch sub lineto - stroke -grestore -gsave - newpath - 250 81 8 3 80 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 202 135 moveto (rose) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 138 81 moveto - 138 130 lineto - 0 48 atan dup cos 8 mul 186 exch sub - exch sin 8 mul 130 exch sub lineto - stroke -grestore -gsave - newpath - 186 130 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 255 65 moveto 319 65 lineto 319 97 lineto 255 97 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 287 65 moveto - 287 97 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 303 81 moveto - 0 93 atan dup cos 8 mul 396 exch sub - exch sin 8 mul 81 exch sub lineto - stroke -grestore -gsave - newpath - 396 81 8 3 93 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 335 135 moveto (violet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 271 81 moveto - 271 130 lineto - 0 48 atan dup cos 8 mul 319 exch sub - exch sin 8 mul 130 exch sub lineto - stroke -grestore -gsave - newpath - 319 130 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 398 63 moveto 462 63 lineto 462 95 lineto 398 95 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 429 63 moveto - 429 95 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 445 80 moveto - 0 48 atan dup cos 8 mul 493 exch sub - exch sin 8 mul 80 exch sub lineto - stroke -grestore -gsave - newpath - 493 80 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 477 134 moveto (buttercup) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 413 80 moveto - 413 129 lineto - 0 48 atan dup cos 8 mul 461 exch sub - exch sin 8 mul 129 exch sub lineto - stroke -grestore -gsave - newpath - 461 129 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 505 86 moveto (nil) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 66 53 moveto - 66 81 lineto - 0 46 atan dup cos 8 mul 112 exch sub - exch sin 8 mul 81 exch sub lineto - stroke -grestore -gsave - newpath - 112 81 8 3 46 0 tgifarrowtip - closepath fill -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:26:39 1995 diff --git a/doc/lispintro/cons-2.pdf b/doc/lispintro/cons-2.pdf deleted file mode 100644 index c26906f6f86cb89d237c16510dd5e82ae719ba37..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1399 zcmZuxe@qi+7~Ui#=F3zTrAku5H#U}*rQThy*Oq}Dk+u%CQhLpFbag512h^3GyE{xJ zvH@9Gh7K03L}X0#4}VXiZrO~T(Fuyd40TcrE^KpT(F9EpH^`h}-&YEq#rx;(p7(v8 zdw)FN<=D+u4YQmDIafwo4*(9*P$=I73JR#TC|D_1K|Mwsl+_=Qkq9Ykz#}6w@(Mm= zG66{zk*6AjzU<`t94W7)MaI*We>GlvDP?pZw~t?VV_U#*#6r~v!tvj#$q-|pCN%od`rwiLq#>j*0=7@5M%Xc=U_+#T2ueF0^ z-2*@W{Z0PYErZ+FfB0RRbTOCNH!u8R+nMh_(Cj(h3{RJiY}omE>sZ;t^>>*^?C)^A z$!c2Q#vHuKtA;JI(d~c7V>+d*8Ve33QL|tIgUL>{q#;{3SC(F= z-JMz6bbg0>L1tEN*2i@xC%lKR2DYcy6QwlGa+Bq_re#X;#^p=ut-q%p`LXE91~GchAgoNpd3gNYD6!RuzBpF;N_9*qOiRnnfKWLjFUFA`N2-VRq) z36d;%MgL|Q8X0amtySZZ;u9+Sg`gRaU1fe#OVfD_t<^I|R>$aZ+$Q**ADZnmB%%sH zLxutL>;?54$8xX&&R_->4}e@SIE&@!=3;sS?ma1w)8bJkVKjp+kc4q$s7aW?I5*Gu zJWPwNp2RhB|KrM{#~(l<{_#PI_tzraFQgoTfXzg92dUy. - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 15 702 300 767 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 32 62 moveto (bouquet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 64 80 moveto - 64 120 lineto - 0 49 atan dup cos 8 mul 113 exch sub - exch sin 8 mul 120 exch sub lineto - stroke -grestore -gsave - newpath - 113 120 8 3 49 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 128 110 moveto (car) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 128 142 moveto (rose) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 192 110 moveto (cdr) show - grestore - -% OVAL -gsave - newpath 207 124 4 4 tgifellipse stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 217 123 moveto - 0 38 atan dup cos 8 mul 255 exch sub - exch sin 8 mul 123 exch sub lineto - stroke -grestore -gsave - newpath - 255 123 8 3 38 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 268 111 moveto (car) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 264 143 moveto (violet) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 332 111 moveto (cdr) show - grestore - -% OVAL -gsave - newpath 347 125 4 4 tgifellipse stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 357 124 moveto - 0 38 atan dup cos 8 mul 395 exch sub - exch sin 8 mul 124 exch sub lineto - stroke -grestore -gsave - newpath - 395 124 8 3 38 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 408 112 moveto (car) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 408 136 moveto (butter-) show - 408 153 moveto (cup) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 496 113 moveto (cdr) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 495 137 moveto (nil) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 178 86 moveto - 178 157 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 485 84 moveto - 485 157 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 327 85 moveto - 327 157 lineto - stroke -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 120 86 moveto 234 86 lineto 234 157 lineto 120 157 lineto - closepath stroke - 1 setmiterlimit -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 257 85 moveto 371 85 lineto 371 157 lineto 257 157 lineto - closepath stroke - 1 setmiterlimit -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 397 84 moveto 531 84 lineto 531 157 lineto 397 157 lineto - closepath stroke - 1 setmiterlimit -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Tue Mar 14 15:09:30 1995 diff --git a/doc/lispintro/cons-2a.pdf b/doc/lispintro/cons-2a.pdf deleted file mode 100644 index c159e8b9d82a20fc18c928aea9591ff493eb2df3..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1504 zcmZuxdr%a09JhyB>uJ~^M4A2IJUu{fANSyRhyur5N1oi=9fBTL9(Q|ibnG&_iyn{U zSvK^7A;6+3CMgsoh#AMi0<2NIQHU&ajHs9}=A@Bv7{RE?ehUW#vH$G;KHu->v){*O zSEN^|cj6K$BI^6&tq&17zyO_*jl{&Ddr2yj%K{3B7*Ms-#gPm^)h;VXsz@7cCu3s~ zmSae34&r{V*3?f8VS?`QP|jS~5tj6}$g);&&UK7BT6#_Qn&3|7XP&7UVW{VDrKPO5 zT6^^GZ#7r9=d91V+*9yoO~Ji@yW>e}*K)9wuqCq*?3o@+c7m{Js1 z_;lF=Kj?1V_PQf2hsXXJX`Ydt)NB%*xc~UQ@Lh#B#b8bA_I%bJEmnn}40$Q__*Wsx zt=G1BI?oG_`yZHOjOT;1>+34}o{^@m(?0gX_rpa+L&L@T?(3)B+a@Q!NMCb$LYHK! zl%^l72{zk=21-NZGeIR6>!+(r0`_hQxtZQV?bAu(G-odPgXoqMGsIIn!+KbgHdSz@ z^McdteYUCWjVnLK3sWYF>JF{@w1Ro`Y}cmMrn-`Vh$GRHzm|`*UdTS+o!G3I2=f+C z^(6#_e2{j(=lQLvj|_Y{C~teR>%okVYdlx|yt|QU(BDGb2{bC6*sps1&#*l;FCtT~ z))G-WhMU#7Rqc%IotUJJ;k_d%B}dLy?fa;A6gB?d)ZbSBlPFW@8tVvdlnhw!p30|l z{J+^a?afYzIpx;8FBzMpZfEJ<6^8a*rVWQ25uap#*FF%CmKstua{ZqU8L>KON5#*V zdQ*aCx`w!6znA?+KOY(2pZ`#4tkyOd*YHZqjWR)euIs4NFwWxzEOHb)?MD% z<~X>%$Frq;tXeJpWov0nOYtf)Fp;F}K4-uu-c7uR_`94?B0fmAXf#uPE{W=`nIx(s z?M`bv?FMEHh6$w{DC8Cd#u$>~fRuM4f*MGc&SPvO3q7i5Xq%Db%qVm*Kux5ZgXxKG zPGjVtPeJ4yLrp_A&Py5)=vp)Zo}nNMc(>0&zM}Xy%()+m!K%P)Su8-GbJ|&8M);x) zhy_4}JYJGl^HK2ys*jmq<*Y6`b6#Su_{IE)rTL3RBWSW-2k_WfpD^Ep?~61*j!H7^eQurg_oHV6^V;8HU2n>tFF+zbWr7~Or<2u^Da%iDX zH$yrQ4B$9|EnIN@a;Y3Rz&xgu!7cI^pyn|glm8FHB9w3+OY<;=6n3->!*FPUWtako zyIO`Rm2j5Ju*j7#0. - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: -1 691 324 757 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% BOX -gsave - 1.415 setmiterlimit - newpath - 128 102 moveto 192 102 lineto 192 134 lineto 128 134 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 160 102 moveto - 160 134 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 176 124 moveto - 0 80 atan dup cos 8 mul 256 exch sub - exch sin 8 mul 124 exch sub lineto - stroke -grestore -gsave - newpath - 256 124 8 3 80 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 208 172 moveto (rose) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 144 118 moveto - 144 167 lineto - 0 48 atan dup cos 8 mul 192 exch sub - exch sin 8 mul 167 exch sub lineto - stroke -grestore -gsave - newpath - 192 167 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 261 102 moveto 325 102 lineto 325 134 lineto 261 134 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 293 102 moveto - 293 134 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 309 118 moveto - 0 93 atan dup cos 8 mul 402 exch sub - exch sin 8 mul 118 exch sub lineto - stroke -grestore -gsave - newpath - 402 118 8 3 93 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 341 172 moveto (violet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 277 118 moveto - 277 167 lineto - 0 48 atan dup cos 8 mul 325 exch sub - exch sin 8 mul 167 exch sub lineto - stroke -grestore -gsave - newpath - 325 167 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 404 100 moveto 468 100 lineto 468 132 lineto 404 132 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 435 100 moveto - 435 132 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 451 117 moveto - 0 48 atan dup cos 8 mul 499 exch sub - exch sin 8 mul 117 exch sub lineto - stroke -grestore -gsave - newpath - 499 117 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 483 171 moveto (buttercup) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 419 117 moveto - 419 166 lineto - 0 48 atan dup cos 8 mul 467 exch sub - exch sin 8 mul 166 exch sub lineto - stroke -grestore -gsave - newpath - 467 166 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 511 123 moveto (nil) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 131 80 moveto (flowers) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 210 75 moveto - 237 75 lineto - 237 113 lineto - 0 18 atan dup cos 8 mul 255 exch sub - exch sin 8 mul 113 exch sub lineto - stroke -grestore -gsave - newpath - 255 113 8 3 18 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 2 80 moveto (bouquet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 81 77 moveto - 108 77 lineto - 108 115 lineto - 0 18 atan dup cos 8 mul 126 exch sub - exch sin 8 mul 115 exch sub lineto - stroke -grestore -gsave - newpath - 126 115 8 3 18 0 tgifarrowtip - closepath fill -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:25:41 1995 diff --git a/doc/lispintro/cons-3.pdf b/doc/lispintro/cons-3.pdf deleted file mode 100644 index 91046d06e9c52c7691697b131715e3354a0a65f8..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1475 zcmZuxeM}Q)9G=OtEvF$Oj!tCwj-?Yu>D{$lTRs8~3dpduw3uZgxI$lOwf6AtI;t}p zfsIThBa3V!V98)0!jvrpH|lhJxXGlb5td~PMk7kx0wch}R5WAn3k3#x|J>d4`#sP5 z`*`leI(1SwEtM1Eo{920f&mm@bM_N4G2||2%NNW*fe<~JWU&g617wobC_pvLWlb

(wC|2onM;wc`@qnA;9SGHjHYMmUBwv#GokuNwI9_wDw_jKWYVs4svmB*dggxZ zo9Wr;d}qt%#`z7I>C&e+b*8>9Eq!x1@LuEe(3Ip|pV4eb*^5oTX*&OGsC^|nUAAqH zUAkM*%QO`>zi`0v@!!OhyS|fa`L@l!PTQA$x++mEX-ppgQGc9C8|dF(#!R<`&8$Cj zwDp4Ne(R9-wyWVet7mBMhm1zl7acrutvXw-)SNg!s=XRK*Y>j6aLdrLlaAZ=Y?_qp zFFp~o{Yu4_%b#C#2Z-bom1k$BKIy%q6K($L$d74t3Gn2#3Tw*jy|JS~<<;&Ee@Vc@ zn+b5QGma|?O7{FB9CwAbA50K;+ucPYVX~WkXRpssp1$+I|D_u~DX+CgKk`)$S>~gH zwBs#1ej4u`x%aVZEFAwhX z`OJ3r>Ze-2o>OkKq`qZ+&8yj-$Z<{;HXRapzox1>@9-s2peV-GA!2{;6Z6n!@~$5} zVas5n;5$RngcpifaZ|?O0!ZqN`H<8=lf@X%IzT3c!g3h{6pAbY#W-jafE?S6AoY-E z?OZP8kr8zqn`?kVCW)*H$PDNZPeq*kW^bZo3w828})?DR?k)ATDU3r#IWRfKAF6u)|d@kSovG2qHM3*;7xBr!se z278WxSAaW4=Pq?5TVbOyo9wxe3rRHSK(d+T1wNOv6bL{?Gg3+xibjgQcEQ5h)M)G> z>L?jSMbeZ^L965uv;xI7tm(<2Vhg{HPPPyRoyz!@!8$f2JoAPtry z5cLa4J. - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 6 681 355 758 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% POLY/OPEN-SPLINE -gsave - newpath - 274 102 moveto - 274 134 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 289 122 moveto - 0 56 atan dup cos 8 mul 345 exch sub - exch sin 8 mul 122 exch sub lineto - stroke -grestore -gsave - newpath - 345 122 8 3 56 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 350 100 moveto 414 100 lineto 414 132 lineto 350 132 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 382 100 moveto - 382 132 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 397 114 moveto - 0 59 atan dup cos 8 mul 456 exch sub - exch sin 8 mul 114 exch sub lineto - stroke -grestore -gsave - newpath - 456 114 8 3 59 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 430 170 moveto (violet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 366 116 moveto - 366 165 lineto - 0 48 atan dup cos 8 mul 414 exch sub - exch sin 8 mul 165 exch sub lineto - stroke -grestore -gsave - newpath - 414 165 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 219 78 moveto (flowers) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 298 73 moveto - 325 73 lineto - 325 111 lineto - 0 18 atan dup cos 8 mul 343 exch sub - exch sin 8 mul 111 exch sub lineto - stroke -grestore -gsave - newpath - 343 111 8 3 18 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 459 95 moveto 523 95 lineto 523 127 lineto 459 127 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 490 95 moveto - 490 127 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 506 112 moveto - 0 48 atan dup cos 8 mul 554 exch sub - exch sin 8 mul 112 exch sub lineto - stroke -grestore -gsave - newpath - 554 112 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 566 118 moveto (nil) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 538 151 moveto (buttercup) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 474 109 moveto - 474 146 lineto - 0 48 atan dup cos 8 mul 522 exch sub - exch sin 8 mul 146 exch sub lineto - stroke -grestore -gsave - newpath - 522 146 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 244 102 moveto 308 102 lineto 308 134 lineto 244 134 lineto - closepath stroke - 1 setmiterlimit -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 324 189 moveto (rose) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 260 117 moveto - 260 184 lineto - 0 48 atan dup cos 8 mul 308 exch sub - exch sin 8 mul 184 exch sub lineto - stroke -grestore -gsave - newpath - 308 184 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 146 101 moveto 210 101 lineto 210 133 lineto 146 133 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 177 101 moveto - 177 133 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 193 118 moveto - 0 48 atan dup cos 8 mul 241 exch sub - exch sin 8 mul 118 exch sub lineto - stroke -grestore -gsave - newpath - 241 118 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 187 178 moveto (lily) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 163 118 moveto - 163 171 lineto - 0 18 atan dup cos 8 mul 181 exch sub - exch sin 8 mul 171 exch sub lineto - stroke -grestore -gsave - newpath - 181 171 8 3 18 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 16 78 moveto (bouquet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 95 73 moveto - 122 73 lineto - 122 111 lineto - 0 18 atan dup cos 8 mul 140 exch sub - exch sin 8 mul 111 exch sub lineto - stroke -grestore -gsave - newpath - 140 111 8 3 18 0 tgifarrowtip - closepath fill -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:25:06 1995 diff --git a/doc/lispintro/cons-4.pdf b/doc/lispintro/cons-4.pdf deleted file mode 100644 index 1165ef03de51bde98e7400700a887fc608f981e8..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1587 zcmY!laBp~n!G=6{e{1j2>6SX}UwNA6aF=W5z6GjpmlXSY z+`91a{Y3dq`5BQdCsq3TRerzlxaOF}8Z_NM{{7}3KXgwWPk$I{5VwzOLj23!!cldC z4+KOO-fP?RgfSw%(e)13hlMR(>1(>KvcHwmu#2)2>iJb`FDnvuywM`|q|PJ9hN1`D zOP6dsa#JAm=T)JA(~q|qC~UqMarT~QvE1)xaTXFCVT`hJ8}8=I$X+VHdNBL{_N&gz zuWft5zP`C()#5j&Yp2aOTcUbuNloD`f$z^0c$bFuF|OCqovpL3?(MhJ-<}?R=2>&E zL;957)#|zVUn==6IA$!n?b5N4Gd-@ds&(^>E0g#1m^p-mn0g8|Wp0t5_V@L-A2yZj zD|!WjR;?8L>@mk9&23tv&sT=tV6kuxQ9~UXH;3;q?wJ^qz=0L^B3jc7;O}7^G)k(ZBwAK zpK9B*)Qn~3wo`Jv?^~xG;Ap?Hd+ST%9(T2~Q$+)6eSWp~OZK--ycjp#RCur53T1cg zu#%g)``Z`2h@Q;D#dD$My|`LNxc`%|CF_)d-rgz~+1mQQg6VZ+@pgMzztxg27p;DD zCQ|s!%@2_hGm2Fc-p;%_r*rF{;!`F3^9*yX)z9?)VCGm~bUHOJ1)AJ|EKm{!B}_1F zXv_r_GC`!?kjjEo{eZ;uRDIvnl*~k@{0fC=1E93AiKT+Mc`O%Dt|&FHM8O!8yt(v) zQj7CTi;`1|feAmLC_gzkwIo^}m^BpiLsBbBfXZDfO5B4>fQeth5~9N`AE?_9WMmK* zFe~Ug1NlG$ixogw2rLA36vzfhmI4|Ebd>_wS;Y$a-kB-I3ej93M+b4mDgaF=1sMr4 z4XV`;t`(}&Ik6-$CqEr#1jO+O_2#JR5sv24_Yd$@FtoFS8VvFSG@A#RbAhx4Axr^# z3MOm8Wq~RS;zA{z5{pwo!2oi3QD$lp*pd1m5ib4U(xehl6o7mTv=`BrDDRt}f?W#k&x)edG%f=LLqjeDI8ZP%H8nO>NK=4`SsDSO3&Mrq0qF7=Nf@h6dQg41q}mU7ZP%-jbrk%$(FB zV4hHz{06CE}hyVZp diff --git a/doc/lispintro/cons-5.eps b/doc/lispintro/cons-5.eps deleted file mode 100644 index 214c4059e32..00000000000 --- a/doc/lispintro/cons-5.eps +++ /dev/null @@ -1,622 +0,0 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%BoundingBox: 15 680 305 764 -%%Title: cons-cell-diagram5 -%%CreationDate: Wed Mar 8 14:27:28 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) - -% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 15 680 305 764 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% POLY/OPEN-SPLINE -gsave - newpath - 156 105 moveto - 156 137 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 171 125 moveto - 0 56 atan dup cos 8 mul 227 exch sub - exch sin 8 mul 125 exch sub lineto - stroke -grestore -gsave - newpath - 227 125 8 3 56 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 232 103 moveto 296 103 lineto 296 135 lineto 232 135 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 264 103 moveto - 264 135 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 279 117 moveto - 0 59 atan dup cos 8 mul 338 exch sub - exch sin 8 mul 117 exch sub lineto - stroke -grestore -gsave - newpath - 338 117 8 3 59 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 289 172 moveto (a different piece of text) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 248 119 moveto - 248 168 lineto - 0 29 atan dup cos 8 mul 277 exch sub - exch sin 8 mul 168 exch sub lineto - stroke -grestore -gsave - newpath - 277 168 8 3 29 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 147 66 moveto (kill-ring-yank-pointer) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 207 76 moveto - 207 114 lineto - 0 18 atan dup cos 8 mul 225 exch sub - exch sin 8 mul 114 exch sub lineto - stroke -grestore -gsave - newpath - 225 114 8 3 18 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 341 98 moveto 405 98 lineto 405 130 lineto 341 130 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 372 98 moveto - 372 130 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 388 115 moveto - 0 48 atan dup cos 8 mul 436 exch sub - exch sin 8 mul 115 exch sub lineto - stroke -grestore -gsave - newpath - 436 115 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 448 121 moveto (nil) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 397 154 moveto (yet more text) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 356 112 moveto - 356 149 lineto - 0 35 atan dup cos 8 mul 391 exch sub - exch sin 8 mul 149 exch sub lineto - stroke -grestore -gsave - newpath - 391 149 8 3 35 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 126 105 moveto 190 105 lineto 190 137 lineto 126 137 lineto - closepath stroke - 1 setmiterlimit -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 206 192 moveto (some text) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 142 120 moveto - 142 187 lineto - 0 48 atan dup cos 8 mul 190 exch sub - exch sin 8 mul 187 exch sub lineto - stroke -grestore -gsave - newpath - 190 187 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 32 66 moveto (kill-ring) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 65 81 moveto - 65 121 lineto - 0 51 atan dup cos 8 mul 116 exch sub - exch sin 8 mul 121 exch sub lineto - stroke -grestore -gsave - newpath - 116 121 8 3 51 0 tgifarrowtip - closepath fill -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:27:28 1995 diff --git a/doc/lispintro/cons-5.pdf b/doc/lispintro/cons-5.pdf deleted file mode 100644 index b9e713f2dac7aaf285cba703f78e16f1c387eb2e..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1511 zcmZuxeNYs27#5wvc9g-1lmM9@C3#4?yZ3!|0VCXTe4oeh6%yUY9xTu;?JjU4B;A-g zh@hy9C7le76gU|}86eEy6!9@QAmM~YNi%TT7-C2R12WKW;ebH*pSykD_j&expWn0V zs}51_#rFvi-_EhJYD5GuKo5JNGcVW5meKmfw9 zG@<(tu~c5r_Lzq-*VajYOQegwxnT0Ws;=4-;`vW*p55YGUCG<{+gxFDL0B$>TZ?S{ zZ|CJTjlN^w!s~2n@ZK~tHT27XbN{W)Q46kBfg=klX(5PDtf}2@3%g4466;EKKUH~c zU?v(jp8GYZs72M>QB^$fs*|g!@5%Yf(70etgPYj(14LM{X}?J%k8@8zN(Zi#d48q8 zQX;CG6B!eKzUbxFo#0=#bK3ZyY(uqfdpsJhRZM$lM!!{IcmHcT`1^r_ zeL_=U`}T$+YeUz;+fCg*XIgg8%3Xrn{+$dT?wG$jFc~yB|0MsY#V62ZbcfS6f&U*K z!JGXgsyAOhX{}d`?{OJQI6eC5{lVkZ)%%Githdgs)ZSJ)aA)sG!J~l74+h5{%X>51 zvaU1g^cxda`**!f_nd#%8$7qQoP5~&<&QPw!#nQZ_RNgew0~~2vVL<5vI!)!zh>O_ z(OH9&HNtrQLU&`(vD>+!yH1a$X0je-wYom)ha{C}=jFpma$DysTOS|mnacY!{Fb2k z*;s-{Z^TiNAo^7KyIOGQdQ7%0T4$&y?bCDptQXQ`)#8?^)cL)c39Nbw%=v9bZ2+#VfmK zGwS4kKBCC6`6UhCt9I=Y7w)Y0shM%UslW>ev(XU|_>YSf7bfmkB#R~ix&xF2BxA75mtjCEOhI6cCd@1laFIk%4Z%=3w1Hq?Sk*LTh$Yx$6vi2# zTEfD@c7=rvjb&kAfozGPq#zsTBsB<(FB%N*p&$de*e^nkp|~e3y#`PWP6ZanVgMRJ z8X1s`a6@a56aW=+I7v>;LB&_74rZ{9)n!p>%Mwe&ul7sU_OA|&pfTzwfCmIPgt;9Y zuck(Va5T-T%HmSXRVgA}Tjg#Y#REEq;B4R~r%8fd91`Ua1dYwnv)mDI8^h-=Z^U0^ zLz|5`27=}(V$~otonlzVK$F=lkm90!7~cJ}7+;J_1wvc` z>rs^P#if-!Ei_?5Fo5F-wsHZnNF)#e6IjNiLTCqf0rN73W1{CUOah~`t`8Fn;Tf&v zVi*o1unrUR;pXcwsSFyw4wJnI6F|?`_lf_. - -/tgifdict 53 dict def -tgifdict begin - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/TGEL % tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/TGMAX - { exch dup 3 1 roll exch dup 3 1 roll gt { pop } { exch pop } ifelse - } def -/TGMIN - { exch dup 3 1 roll exch dup 3 1 roll lt { pop } { exch pop } ifelse - } def -/TGSW { stringwidth pop } def - -/bd { bind def } bind def - -/GS { gsave } bd -/GR { grestore } bd -/NP { newpath } bd -/CP { closepath } bd -/CHP { charpath } bd -/CT { curveto } bd -/L { lineto } bd -/RL { rlineto } bd -/M { moveto } bd -/RM { rmoveto } bd -/S { stroke } bd -/F { fill } bd -/TR { translate } bd -/RO { rotate } bd -/SC { scale } bd -/MU { mul } bd -/DI { div } bd -/DU { dup } bd -/NE { neg } bd -/AD { add } bd -/SU { sub } bd -/PO { pop } bd -/EX { exch } bd -/CO { concat } bd -/CL { clip } bd -/EC { eoclip } bd -/EF { eofill } bd -/IM { image } bd -/IMM { imagemask } bd -/ARY { array } bd -/SG { setgray } bd -/RG { setrgbcolor } bd -/SD { setdash } bd -/W { setlinewidth } bd -/SM { setmiterlimit } bd -/SLC { setlinecap } bd -/SLJ { setlinejoin } bd -/SH { show } bd -/FF { findfont } bd -/MS { makefont setfont } bd -/AR { arcto 4 {pop} repeat } bd -/CURP { currentpoint } bd -/FLAT { flattenpath strokepath clip newpath } bd -/TGSM { tgiforigctm setmatrix } def -/TGRM { savematrix setmatrix } def - -end - -%%EndProlog -%%Page: 1 1 - -%%PageBoundingBox: 34 577 324 778 -tgifdict begin -/tgifsavedpage save def - -1 SM -1 W - -0 SG - -72 0 MU 72 11 MU TR -72 128 DI 100.000 MU 100 DI DU NE SC - -GS - -/tgiforigctm matrix currentmatrix def - -% BOX -0 SG -GS - 10 SM - GS - NP 64 104 M 255 104 L 255 360 L 64 360 L CP - S - GR -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 65 296 M - 254 296 L - TGSM - 1 W - S -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 63 233 M - 255 233 L - TGSM - 1 W - S -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 63 169 M - 255 169 L - TGSM - 1 W - S -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 251 362 M - 251 361 L - 251 379 L - 244 379 L - 229 361 L - TGSM - 1 W - S -GR - -% OVAL -0 SG -GS - GS - NP 160 72 10 6 TGEL - S - GR -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 63 104 M - 128 64 L - 138 69 L - TGSM - 1 W - S -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 255 103 M - 190 63 L - 180 68 L - TGSM - 1 W - S -GR - -% TEXT -NP -0 SG - GS - 1 W - 160 152 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (symbol name) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (symbol name) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 160 41 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (Chest of Drawers) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (Chest of Drawers) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 41 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (Contents of Drawers) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 160 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (bouquet) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 220 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - ([none]) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 279 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (\(rose violet buttercup\)) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 337 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - ([not described here]) SH - GR - GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 68 362 M - 68 361 L - 68 379 L - 75 379 L - 90 361 L - TGSM - 1 W - S -GR - -% TEXT -NP -0 SG - GS - 1 W - 158 132 M - GS - GS - 0 - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 345 139 M - GS - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (map to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 350 259 M - GS - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (map to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 159 213 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (symbol definition) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (symbol definition) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 159 195 M - GS - GS - 0 - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 160 276 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (variable name) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (variable name) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 158 260 M - GS - GS - 0 - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 160 339 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (property list) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (property list) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 158 323 M - GS - GS - 0 - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) SH - GR - GR - -GR -tgifsavedpage restore -end -showpage - -%%Trailer -%MatchingCreationDate: Fri Sep 14 17:40:57 2001 -%%DocumentFonts: NewCenturySchlbk-Roman -%%+ Courier -%%EOF diff --git a/doc/lispintro/drawers.pdf b/doc/lispintro/drawers.pdf deleted file mode 100644 index ca7e0ff1629d4977f6a1cf835e160f22e6bc4075..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3906 zcmb_fc{o&U8!r)!LbfR7Btp@dGh-I<$`X<#W+8@ZjMEs)40DFGP%2s^X(3rcWvwW$ zq|#eN2??Pj3DKK1>QhpE=SYisulM`so4MwibME`O@8{m0^ZOkw$JJK)&>uz66 zI*tV30fDCv&e#~VgZW&MH$X-uG|-CYCxV3lXywNi!K-18zza4p!670c%=X8HB%Pq! zBZ+vql3tg-3-5R3fP1f!`$ZWIi|PYxh546~9zyNY9F~5$d0l>!5s%yQ0_blDyBTU6 z-Yzd5+Tcp+>#S8DXy1Vm&fVemG(ixl+p^dLdf<3Df+p^q=17p zGuRMvUzFOb;~ zFeAJ09$bCY?^3)AKwNIn8I{ZCas}kdTYlOVrtjn)P#+yJgP~ zjx*%mDH@eF$uc(z#+4U^suMzWpOA>*S+23iNWN9>-nB1g4ii}|S5FajKSz5Se7Oa! zkaXF*>Wma!qw?vs(Z=;#`loTM#n&8N<)hiC9d_y+dmFRWX*qBG$jgS8ZgfRumr}9M zulZ|<`l8+~K`eTWN^o7y(bm+~fFwLIqQv)&y_SZB(VXncrE+^xnnO$4`aWr#rUa?U zXcR_voL*bqmJLPy=cvW=g*#T=EWNp?;tM$UPC!lAjNL(`hcMr3a>~#vY%;NVocPBZ z;3h=|KZcgEH2?-3*<2X3hrM`gb3q8e!lP<}A^O8Z9ynAfg!v+Xh>bN4q``TgF3H64?1xy5n0H7_;3jtU-ENmLi13*0lVJ?3%#kQI}hF>i$*dn%{fcwqG z*XVz2MVY$(N7OiQoufSfnV3w*G?B!lXBq{E+0lNunaJv!mWrcdT95|eaS&F+pBMhf z4WtKoim<9l4pD;!-SjC^U=P{gsd!?K5Y?hsBrIl^+mD+TT);8XQ}Rc6JRWG zNnCRQ>bg%X5WTIgS#YHqC!IJlTD2RlimQ_^%ZiYRe_2Unz7-A70D2C|&|RsDH+Phk zeLS-vVeOu!%VU&n&k?el^*5Y9uKP-=n0B!)OZrtpy6fB04<6t1X7-En63LTa7JH1^H) zO2M+SW0b&*}-B#(dozQ#?trJP7@Lo_6=pqnvEQhth9^V<>A^L->rH0 z5i`TdPa@XgY&_FyR&;`6kHMIAT*6p(Scj}wGJflPz0EOqyRDobF)y$CEAQ6X)hwIf zO56B*PVrgsEAn@l7UjsQY!k+4iz?D}j-M>>*RSMy+D4v~qqL2Pcbfw-3A2gfxLEf> ziP$QIzak*HkdBW}J(}t}Uf1SEGZ}$tm(-MEpY*TXSJqPZrRG$g^5tXQb$xo|x0$Z^ zfzP_l^r9oRjQFbwTbGz2r-xGGD(B^oy_kGGwbyN_j`R(MvB`w7CVzHEHmXN#ZxbZ>w@d~wLkE0Y4h7WiL zwJ_T~vPKNvNsY>?{ViH7b0pC(N1@be*kt=OOZQK@g8bp0YdiDnyYv>o5^dVoI=2N` z>=z&I;SQ~knm40j?EEor&Sf2`eCdm$*7=!CtU*@|Vosa_FO?i`$hsj7d=bPJb= zGu?Wwoyx$|lq+L0BdH}LRE>ROo$-{}4q0cx*ZY;Oz*o|wJ>8-q8@F~CdYU?8P5?yxe?j^>_OLh!Q z3;S%W0uG-1kW#0YjzI%Rlt8YhjbeJ3=!$p7V+J>Lok^lB>rr9XY=&eq&U7Xk5 zFcqXbFa@6+jl4HnsW{rX7Wb4qZ%)0s}|5YLLlP!bp{aKKr_|XM?n4!6NVLiopAkXI_-`YX`Jig3+ z=*4_W)*jQ2_A1NxkT+2;hm78JCpm96KT{xN%&n{r4L8qa>Rg!5Dr)p8^1ZNOr9*s@ zL&+^WVT}6wP_6g7U%lv>^~_GJb#AIH9Nd`Z=SxErt#1t0hs0JN?a6no_OLfPRh5{% ztl_~kZwfDXA(f9DkN;CjRylFlaha}``J96X&zcK&`(83nQu{+|-2Fb-38$_@Qy}t_M3bcI zRtyTK!uJFSU=Rb5@YHWei2=@D>XcoP&g0=^SrAPhWkSz@N>Z@V6R9I6_{4NFW3ZCx8wEu*sdQctS*E;msBT zL;`5Xp1g)2GU&qd5_uym9D#xb{V!kKzvwW#|AU@H!pM+;fdN3Gpg;V#9f=S|MX)cG zY6y@~%tv)NY|Yoz24o^Yq#9!EhL19N9-oV*#W&+4yzlo@K>bIlu|iE&`g^s0)N!JC z4s3rI{NL3#N2wXg%=8I(0zf5G0Sb}gfsqC-0vO;xGlYYYG*pQ4D|Wydn8)>=yv4S| zbeJU$v_WYRk7LH?`oU;PLAnU`cLpFLdTGx?5Hz!iegP03EdYo$6eV~%ARpv_0?-Q# z0AWxFBA^K5fo#wpL;~0xSa%`~^o0i|qMp!%f8sqD>zm9UWs6=x99XDhNp}RSy#o@^ah_nJv&_%aHUyejP0e>~h9(7i)B;fIe5S~DWs6+#Zg6i!BUjMB6&elSN@Md&Q zAQBFZfARy6NhBf(*bID=8A9kJVjqD2O-3YQy`Cz=Q%Pv|evwh|zuDsP*!29ej*QOH zuQEe2I(<{u5y*yU!KTWH(C_gPD5T%^KwE^e(W$l&p7;+k?Bq>dM<7$s&U}-Jglx2V zLi8OL0O`DKD03$PAWa}ZDK^$k0JPz6764xfJZQ5TVCl>_D9%W@)Lr^vwn1f|>>> -@set smallbook -@ifset smallbook -@smallbook -@clear largebook -@end ifset -@set print-postscript-figures -@c set largebook -@c clear print-postscript-figures -@c --------- - -@comment %**end of header - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 - -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@set edition-number 3.10 -@set update-date 28 October 2009 - -@ignore - ## Summary of shell commands to create various output formats: - - pushd /usr/local/src/emacs/lispintro/ - ## pushd /u/intro/ - - ## Info output - makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi - - ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/usr/local/src/emacs/info/eintr")) - - ## DVI output - texi2dvi emacs-lisp-intro.texi - - ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi & - - ## HTML output - makeinfo --html --no-split --verbose emacs-lisp-intro.texi - - ## galeon emacs-lisp-intro.html - - ## Plain text output - makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ - --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi - - popd - -# as user `root' -# insert thumbdrive - mtusb # mount -v -t ext3 /dev/sda /mnt - cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi - umtusb # umount -v /mnt -# remove thumbdrive - - ## Other shell commands - - pushd /usr/local/src/emacs/lispintro/ - ## pushd /u/intro/ - - ## PDF - texi2dvi --pdf emacs-lisp-intro.texi - # xpdf emacs-lisp-intro.pdf & - - ## DocBook -- note file extension - makeinfo --docbook --no-split --paragraph-indent=0 \ - --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi - - ## XML with a Texinfo DTD -- note file extension - makeinfo --xml --no-split --paragraph-indent=0 \ - --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi - - ## PostScript (needs DVI) - # gv emacs-lisp-intro.ps & - # Create DVI if we lack it - # texi2dvi emacs-lisp-intro.texi - dvips emacs-lisp-intro.dvi -o emacs-lisp-intro.ps - - ## RTF (needs HTML) - # Use OpenOffice to view RTF - # Create HTML if we lack it - # makeinfo --no-split --html emacs-lisp-intro.texi - /usr/local/src/html2rtf.pl emacs-lisp-intro.html - - ## LaTeX (needs RTF) - /usr/bin/rtf2latex emacs-lisp-intro.rtf - - popd - -@end ignore - -@c ================ Included Figures ================ - -@c Set print-postscript-figures if you print PostScript figures. -@c If you clear this, the ten figures will be printed as ASCII diagrams. -@c (This is not relevant to Info, since Info only handles ASCII.) -@c Your site may require editing changes to print PostScript; in this -@c case, search for `print-postscript-figures' and make appropriate changes. - -@c ================ How to Create an Info file ================ - -@c If you have `makeinfo' installed, run the following command - -@c makeinfo emacs-lisp-intro.texi - -@c or, if you want a single, large Info file, and no paragraph indents: -@c makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi - -@c After creating the Info file, edit your Info `dir' file, if the -@c `dircategory' section below does not enable your system to -@c install the manual automatically. -@c (The `dir' file is often in the `/usr/local/share/info/' directory.) - -@c ================ How to Create an HTML file ================ - -@c To convert to HTML format -@c makeinfo --html --no-split --verbose emacs-lisp-intro.texi - -@c ================ How to Print a Book in Various Sizes ================ - -@c This book can be printed in any of three different sizes. -@c In the above header, set @-commands appropriately. - -@c 7 by 9.25 inches: -@c @smallbook -@c @clear largebook - -@c 8.5 by 11 inches: -@c @c smallbook -@c @set largebook - -@c European A4 size paper: -@c @c smallbook -@c @afourpaper -@c @set largebook - -@c ================ How to Typeset and Print ================ - -@c If you do not include PostScript figures, run either of the -@c following command sequences, or similar commands suited to your -@c system: - -@c texi2dvi emacs-lisp-intro.texi -@c lpr -d emacs-lisp-intro.dvi - -@c or else: - -@c tex emacs-lisp-intro.texi -@c texindex emacs-lisp-intro.?? -@c tex emacs-lisp-intro.texi -@c lpr -d emacs-lisp-intro.dvi - -@c If you include the PostScript figures, and you have old software, -@c you may need to convert the .dvi file to a .ps file before -@c printing. Run either of the following command sequences, or one -@c similar: -@c -@c dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps -@c -@c or else: -@c -@c postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps -@c - -@c (Note: if you edit the book so as to change the length of the -@c table of contents, you may have to change the value of `pageno' below.) - -@c ================ End of Formatting Sections ================ - -@c For next or subsequent edition: -@c create function using with-output-to-temp-buffer -@c create a major mode, with keymaps -@c run an asynchronous process, like grep or diff - -@c For 8.5 by 11 inch format: do not use such a small amount of -@c whitespace between paragraphs as smallbook format -@ifset largebook -@tex -\global\parskip 6pt plus 1pt -@end tex -@end ifset - -@c For all sized formats: print within-book cross -@c reference with ``...'' rather than [...] - -@c This works with the texinfo.tex file, version 2003-05-04.08, -@c in the Texinfo version 4.6 of the 2003 Jun 13 distribution. - -@tex -\if \xrefprintnodename - \global\def\xrefprintnodename#1{\unskip, ``#1''} - \else - \global\def\xrefprintnodename#1{ ``#1''} -\fi -% \global\def\xrefprintnodename#1{, ``#1''} -@end tex - -@c ---------------------------------------------------- - -@dircategory GNU Emacs Lisp -@direntry -* Emacs Lisp Intro: (eintr). - A simple introduction to Emacs Lisp programming. -@end direntry - -@copying -This is an @cite{Introduction to Programming in Emacs Lisp}, for -people who are not programmers. -@sp 1 -Edition @value{edition-number}, @value{update-date} -@sp 1 -Copyright @copyright{} 1990-1995, 1997, 2001-2012 Free Software Foundation, Inc. -@sp 1 - -@iftex -Published by the:@* - -GNU Press, @hfill @uref{http://www.fsf.org/campaigns/gnu-press/}@* -a division of the @hfill email: @email{sales@@fsf.org}@* -Free Software Foundation, Inc. @hfill Tel: +1 (617) 542-5942@* -51 Franklin Street, Fifth Floor @hfill Fax: +1 (617) 542-2652@* -Boston, MA 02110-1301 USA -@end iftex - -@ifnottex -Published by the: - -@example -GNU Press, http://www.fsf.org/campaigns/gnu-press/ -a division of the email: sales@@fsf.org -Free Software Foundation, Inc. Tel: +1 (617) 542-5942 -51 Franklin Street, Fifth Floor Fax: +1 (617) 542-2652 -Boston, MA 02110-1301 USA -@end example -@end ifnottex - -@sp 1 -@c Printed copies are available from @uref{http://shop.fsf.org/} for $35 each.@* -ISBN 1-882114-43-4 - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; there -being no Invariant Section, with the Front-Cover Texts being ``A GNU -Manual'', and with the Back-Cover Texts as in (a) below. A copy of -the license is included in the section entitled ``GNU Free -Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to -copy and modify this GNU manual. Buying copies from the FSF -supports it in developing GNU and promoting software freedom.'' -@end copying - -@c half title; two lines here, so do not use `shorttitlepage' -@tex -{\begingroup% - \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}% - \endgroup}% -{\begingroup\hbox{}\vskip 0.25in \chaprm% - \centerline{Programming in Emacs Lisp}% - \endgroup\page\hbox{}\page} -@end tex - -@titlepage -@sp 6 -@center @titlefont{An Introduction to} -@sp 2 -@center @titlefont{Programming in Emacs Lisp} -@sp 2 -@center Revised Third Edition -@sp 4 -@center by Robert J. Chassell - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@iftex -@headings off -@evenheading @thispage @| @| @thischapter -@oddheading @thissection @| @| @thispage -@end iftex - -@ifnothtml -@c Keep T.O.C. short by tightening up for largebook -@ifset largebook -@tex -\global\parskip 2pt plus 1pt -\global\advance\baselineskip by -1pt -@end tex -@end ifset -@end ifnothtml - -@shortcontents -@contents - -@ifnottex -@node Top, Preface, (dir), (dir) -@top An Introduction to Programming in Emacs Lisp - -@insertcopying - -This master menu first lists each chapter and index; then it lists -every node in every chapter. -@end ifnottex - -@c >>>> Set pageno appropriately <<<< - -@c The first page of the Preface is a roman numeral; it is the first -@c right handed page after the Table of Contents; hence the following -@c setting must be for an odd negative number. - -@c iftex -@c global@pageno = -11 -@c end iftex - -@set COUNT-WORDS count-words-example -@c Length of variable name chosen so that things still line up when expanded. - -@menu -* Preface:: What to look for. -* List Processing:: What is Lisp? -* Practicing Evaluation:: Running several programs. -* Writing Defuns:: How to write function definitions. -* Buffer Walk Through:: Exploring a few buffer-related functions. -* More Complex:: A few, even more complex functions. -* Narrowing & Widening:: Restricting your and Emacs attention to - a region. -* car cdr & cons:: Fundamental functions in Lisp. -* Cutting & Storing Text:: Removing text and saving it. -* List Implementation:: How lists are implemented in the computer. -* Yanking:: Pasting stored text. -* Loops & Recursion:: How to repeat a process. -* Regexp Search:: Regular expression searches. -* Counting Words:: A review of repetition and regexps. -* Words in a defun:: Counting words in a @code{defun}. -* Readying a Graph:: A prototype graph printing function. -* Emacs Initialization:: How to write a @file{.emacs} file. -* Debugging:: How to run the Emacs Lisp debuggers. -* Conclusion:: Now you have the basics. -* the-the:: An appendix: how to find reduplicated words. -* Kill Ring:: An appendix: how the kill ring works. -* Full Graph:: How to create a graph with labeled axes. -* Free Software and Free Manuals:: -* GNU Free Documentation License:: -* Index:: -* About the Author:: - -@detailmenu - --- The Detailed Node Listing --- - -Preface - -* Why:: Why learn Emacs Lisp? -* On Reading this Text:: Read, gain familiarity, pick up habits.... -* Who You Are:: For whom this is written. -* Lisp History:: -* Note for Novices:: You can read this as a novice. -* Thank You:: - -List Processing - -* Lisp Lists:: What are lists? -* Run a Program:: Any list in Lisp is a program ready to run. -* Making Errors:: Generating an error message. -* Names & Definitions:: Names of symbols and function definitions. -* Lisp Interpreter:: What the Lisp interpreter does. -* Evaluation:: Running a program. -* Variables:: Returning a value from a variable. -* Arguments:: Passing information to a function. -* set & setq:: Setting the value of a variable. -* Summary:: The major points. -* Error Message Exercises:: - -Lisp Lists - -* Numbers Lists:: List have numbers, other lists, in them. -* Lisp Atoms:: Elemental entities. -* Whitespace in Lists:: Formatting lists to be readable. -* Typing Lists:: How GNU Emacs helps you type lists. - -The Lisp Interpreter - -* Complications:: Variables, Special forms, Lists within. -* Byte Compiling:: Specially processing code for speed. - -Evaluation - -* How the Interpreter Acts:: Returns and Side Effects... -* Evaluating Inner Lists:: Lists within lists... - -Variables - -* fill-column Example:: -* Void Function:: The error message for a symbol - without a function. -* Void Variable:: The error message for a symbol without a value. - -Arguments - -* Data types:: Types of data passed to a function. -* Args as Variable or List:: An argument can be the value - of a variable or list. -* Variable Number of Arguments:: Some functions may take a - variable number of arguments. -* Wrong Type of Argument:: Passing an argument of the wrong type - to a function. -* message:: A useful function for sending messages. - -Setting the Value of a Variable - -* Using set:: Setting values. -* Using setq:: Setting a quoted value. -* Counting:: Using @code{setq} to count. - -Practicing Evaluation - -* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} - causes evaluation. -* Buffer Names:: Buffers and files are different. -* Getting Buffers:: Getting a buffer itself, not merely its name. -* Switching Buffers:: How to change to another buffer. -* Buffer Size & Locations:: Where point is located and the size of - the buffer. -* Evaluation Exercise:: - -How To Write Function Definitions - -* Primitive Functions:: -* defun:: The @code{defun} special form. -* Install:: Install a function definition. -* Interactive:: Making a function interactive. -* Interactive Options:: Different options for @code{interactive}. -* Permanent Installation:: Installing code permanently. -* let:: Creating and initializing local variables. -* if:: What if? -* else:: If--then--else expressions. -* Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. -* Review:: -* defun Exercises:: - -Install a Function Definition - -* Effect of installation:: -* Change a defun:: How to change a function definition. - -Make a Function Interactive - -* Interactive multiply-by-seven:: An overview. -* multiply-by-seven in detail:: The interactive version. - -@code{let} - -* Prevent confusion:: -* Parts of let Expression:: -* Sample let Expression:: -* Uninitialized let Variables:: - -The @code{if} Special Form - -* if in more detail:: -* type-of-animal in detail:: An example of an @code{if} expression. - -Truth and Falsehood in Emacs Lisp - -* nil explained:: @code{nil} has two meanings. - -@code{save-excursion} - -* Point and mark:: A review of various locations. -* Template for save-excursion:: - -A Few Buffer--Related Functions - -* Finding More:: How to find more information. -* simplified-beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. -* append-to-buffer:: Uses @code{save-excursion} and - @code{insert-buffer-substring}. -* Buffer Related Review:: Review. -* Buffer Exercises:: - -The Definition of @code{mark-whole-buffer} - -* mark-whole-buffer overview:: -* Body of mark-whole-buffer:: Only three lines of code. - -The Definition of @code{append-to-buffer} - -* append-to-buffer overview:: -* append interactive:: A two part interactive expression. -* append-to-buffer body:: Incorporates a @code{let} expression. -* append save-excursion:: How the @code{save-excursion} works. - -A Few More Complex Functions - -* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. -* insert-buffer:: Read-only, and with @code{or}. -* beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* Second Buffer Related Review:: -* optional Exercise:: - -The Definition of @code{insert-buffer} - -* insert-buffer code:: -* insert-buffer interactive:: When you can read, but not write. -* insert-buffer body:: The body has an @code{or} and a @code{let}. -* if & or:: Using an @code{if} instead of an @code{or}. -* Insert or:: How the @code{or} expression works. -* Insert let:: Two @code{save-excursion} expressions. -* New insert-buffer:: - -The Interactive Expression in @code{insert-buffer} - -* Read-only buffer:: When a buffer cannot be modified. -* b for interactive:: An existing buffer or else its name. - -Complete Definition of @code{beginning-of-buffer} - -* Optional Arguments:: -* beginning-of-buffer opt arg:: Example with optional argument. -* beginning-of-buffer complete:: - -@code{beginning-of-buffer} with an Argument - -* Disentangle beginning-of-buffer:: -* Large buffer case:: -* Small buffer case:: - -Narrowing and Widening - -* Narrowing advantages:: The advantages of narrowing -* save-restriction:: The @code{save-restriction} special form. -* what-line:: The number of the line that point is on. -* narrow Exercise:: - -@code{car}, @code{cdr}, @code{cons}: Fundamental Functions - -* Strange Names:: An historical aside: why the strange names? -* car & cdr:: Functions for extracting part of a list. -* cons:: Constructing a list. -* nthcdr:: Calling @code{cdr} repeatedly. -* nth:: -* setcar:: Changing the first element of a list. -* setcdr:: Changing the rest of a list. -* cons Exercise:: - -@code{cons} - -* Build a list:: -* length:: How to find the length of a list. - -Cutting and Storing Text - -* Storing Text:: Text is stored in a list. -* zap-to-char:: Cutting out text up to a character. -* kill-region:: Cutting text out of a region. -* copy-region-as-kill:: A definition for copying text. -* Digression into C:: Minor note on C programming language macros. -* defvar:: How to give a variable an initial value. -* cons & search-fwd Review:: -* search Exercises:: - -@code{zap-to-char} - -* Complete zap-to-char:: The complete implementation. -* zap-to-char interactive:: A three part interactive expression. -* zap-to-char body:: A short overview. -* search-forward:: How to search for a string. -* progn:: The @code{progn} special form. -* Summing up zap-to-char:: Using @code{point} and @code{search-forward}. - -@code{kill-region} - -* Complete kill-region:: The function definition. -* condition-case:: Dealing with a problem. -* Lisp macro:: - -@code{copy-region-as-kill} - -* Complete copy-region-as-kill:: The complete function definition. -* copy-region-as-kill body:: The body of @code{copy-region-as-kill}. - -The Body of @code{copy-region-as-kill} - -* last-command & this-command:: -* kill-append function:: -* kill-new function:: - -Initializing a Variable with @code{defvar} - -* See variable current value:: -* defvar and asterisk:: - -How Lists are Implemented - -* Lists diagrammed:: -* Symbols as Chest:: Exploring a powerful metaphor. -* List Exercise:: - -Yanking Text Back - -* Kill Ring Overview:: -* kill-ring-yank-pointer:: The kill ring is a list. -* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. - -Loops and Recursion - -* while:: Causing a stretch of code to repeat. -* dolist dotimes:: -* Recursion:: Causing a function to call itself. -* Looping exercise:: - -@code{while} - -* Looping with while:: Repeat so long as test returns true. -* Loop Example:: A @code{while} loop that uses a list. -* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. -* Incrementing Loop:: A loop with an incrementing counter. -* Incrementing Loop Details:: -* Decrementing Loop:: A loop with a decrementing counter. - -Details of an Incrementing Loop - -* Incrementing Example:: Counting pebbles in a triangle. -* Inc Example parts:: The parts of the function definition. -* Inc Example altogether:: Putting the function definition together. - -Loop with a Decrementing Counter - -* Decrementing Example:: More pebbles on the beach. -* Dec Example parts:: The parts of the function definition. -* Dec Example altogether:: Putting the function definition together. - -Save your time: @code{dolist} and @code{dotimes} - -* dolist:: -* dotimes:: - -Recursion - -* Building Robots:: Same model, different serial number ... -* Recursive Definition Parts:: Walk until you stop ... -* Recursion with list:: Using a list as the test whether to recurse. -* Recursive triangle function:: -* Recursion with cond:: -* Recursive Patterns:: Often used templates. -* No Deferment:: Don't store up work ... -* No deferment solution:: - -Recursion in Place of a Counter - -* Recursive Example arg of 1 or 2:: -* Recursive Example arg of 3 or 4:: - -Recursive Patterns - -* Every:: -* Accumulate:: -* Keep:: - -Regular Expression Searches - -* sentence-end:: The regular expression for @code{sentence-end}. -* re-search-forward:: Very similar to @code{search-forward}. -* forward-sentence:: A straightforward example of regexp search. -* forward-paragraph:: A somewhat complex example. -* etags:: How to create your own @file{TAGS} table. -* Regexp Review:: -* re-search Exercises:: - -@code{forward-sentence} - -* Complete forward-sentence:: -* fwd-sentence while loops:: Two @code{while} loops. -* fwd-sentence re-search:: A regular expression search. - -@code{forward-paragraph}: a Goldmine of Functions - -* forward-paragraph in brief:: Key parts of the function definition. -* fwd-para let:: The @code{let*} expression. -* fwd-para while:: The forward motion @code{while} loop. - -Counting: Repetition and Regexps - -* Why Count Words:: -* @value{COUNT-WORDS}:: Use a regexp, but find a problem. -* recursive-count-words:: Start with case of no words in region. -* Counting Exercise:: - -The @code{@value{COUNT-WORDS}} Function - -* Design @value{COUNT-WORDS}:: The definition using a @code{while} loop. -* Whitespace Bug:: The Whitespace Bug in @code{@value{COUNT-WORDS}}. - -Counting Words in a @code{defun} - -* Divide and Conquer:: -* Words and Symbols:: What to count? -* Syntax:: What constitutes a word or symbol? -* count-words-in-defun:: Very like @code{@value{COUNT-WORDS}}. -* Several defuns:: Counting several defuns in a file. -* Find a File:: Do you want to look at a file? -* lengths-list-file:: A list of the lengths of many definitions. -* Several files:: Counting in definitions in different files. -* Several files recursively:: Recursively counting in different files. -* Prepare the data:: Prepare the data for display in a graph. - -Count Words in @code{defuns} in Different Files - -* lengths-list-many-files:: Return a list of the lengths of defuns. -* append:: Attach one list to another. - -Prepare the Data for Display in a Graph - -* Data for Display in Detail:: -* Sorting:: Sorting lists. -* Files List:: Making a list of files. -* Counting function definitions:: - -Readying a Graph - -* Columns of a graph:: -* graph-body-print:: How to print the body of a graph. -* recursive-graph-body-print:: -* Printed Axes:: -* Line Graph Exercise:: - -Your @file{.emacs} File - -* Default Configuration:: -* Site-wide Init:: You can write site-wide init files. -* defcustom:: Emacs will write code for you. -* Beginning a .emacs File:: How to write a @code{.emacs file}. -* Text and Auto-fill:: Automatically wrap lines. -* Mail Aliases:: Use abbreviations for email addresses. -* Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. -* Keymaps:: More about key binding. -* Loading Files:: Load (i.e., evaluate) files automatically. -* Autoload:: Make functions available. -* Simple Extension:: Define a function; bind it to a key. -* X11 Colors:: Colors in X. -* Miscellaneous:: -* Mode Line:: How to customize your mode line. - -Debugging - -* debug:: How to use the built-in debugger. -* debug-on-entry:: Start debugging when you call a function. -* debug-on-quit:: Start debugging when you quit with @kbd{C-g}. -* edebug:: How to use Edebug, a source level debugger. -* Debugging Exercises:: - -Handling the Kill Ring - -* What the Kill Ring Does:: -* current-kill:: -* yank:: Paste a copy of a clipped element. -* yank-pop:: Insert element pointed to. -* ring file:: - -The @code{current-kill} Function - -* Code for current-kill:: -* Understanding current-kill:: - -@code{current-kill} in Outline - -* Body of current-kill:: -* Digression concerning error:: How to mislead humans, but not computers. -* Determining the Element:: - -A Graph with Labeled Axes - -* Labeled Example:: -* print-graph Varlist:: @code{let} expression in @code{print-graph}. -* print-Y-axis:: Print a label for the vertical axis. -* print-X-axis:: Print a horizontal label. -* Print Whole Graph:: The function to print a complete graph. - -The @code{print-Y-axis} Function - -* print-Y-axis in Detail:: -* Height of label:: What height for the Y axis? -* Compute a Remainder:: How to compute the remainder of a division. -* Y Axis Element:: Construct a line for the Y axis. -* Y-axis-column:: Generate a list of Y axis labels. -* print-Y-axis Penultimate:: A not quite final version. - -The @code{print-X-axis} Function - -* Similarities differences:: Much like @code{print-Y-axis}, but not exactly. -* X Axis Tic Marks:: Create tic marks for the horizontal axis. - -Printing the Whole Graph - -* The final version:: A few changes. -* Test print-graph:: Run a short test. -* Graphing words in defuns:: Executing the final code. -* lambda:: How to write an anonymous function. -* mapcar:: Apply a function to elements of a list. -* Another Bug:: Yet another bug @dots{} most insidious. -* Final printed graph:: The graph itself! - -@end detailmenu -@end menu - -@node Preface, List Processing, Top, Top -@comment node-name, next, previous, up -@unnumbered Preface - -Most of the GNU Emacs integrated environment is written in the programming -language called Emacs Lisp. The code written in this programming -language is the software---the sets of instructions---that tell the -computer what to do when you give it commands. Emacs is designed so -that you can write new code in Emacs Lisp and easily install it as an -extension to the editor. - -(GNU Emacs is sometimes called an ``extensible editor'', but it does -much more than provide editing capabilities. It is better to refer to -Emacs as an ``extensible computing environment''. However, that -phrase is quite a mouthful. It is easier to refer to Emacs simply as -an editor. Moreover, everything you do in Emacs---find the Mayan date -and phases of the moon, simplify polynomials, debug code, manage -files, read letters, write books---all these activities are kinds of -editing in the most general sense of the word.) - -@menu -* Why:: Why learn Emacs Lisp? -* On Reading this Text:: Read, gain familiarity, pick up habits.... -* Who You Are:: For whom this is written. -* Lisp History:: -* Note for Novices:: You can read this as a novice. -* Thank You:: -@end menu - -@node Why, On Reading this Text, Preface, Preface -@ifnottex -@unnumberedsec Why Study Emacs Lisp? -@end ifnottex - -Although Emacs Lisp is usually thought of in association only with Emacs, -it is a full computer programming language. You can use Emacs Lisp as -you would any other programming language. - -Perhaps you want to understand programming; perhaps you want to extend -Emacs; or perhaps you want to become a programmer. This introduction to -Emacs Lisp is designed to get you started: to guide you in learning the -fundamentals of programming, and more importantly, to show you how you -can teach yourself to go further. - -@node On Reading this Text, Who You Are, Why, Preface -@comment node-name, next, previous, up -@unnumberedsec On Reading this Text - -All through this document, you will see little sample programs you can -run inside of Emacs. If you read this document in Info inside of GNU -Emacs, you can run the programs as they appear. (This is easy to do and -is explained when the examples are presented.) Alternatively, you can -read this introduction as a printed book while sitting beside a computer -running Emacs. (This is what I like to do; I like printed books.) If -you don't have a running Emacs beside you, you can still read this book, -but in this case, it is best to treat it as a novel or as a travel guide -to a country not yet visited: interesting, but not the same as being -there. - -Much of this introduction is dedicated to walkthroughs or guided tours -of code used in GNU Emacs. These tours are designed for two purposes: -first, to give you familiarity with real, working code (code you use -every day); and, second, to give you familiarity with the way Emacs -works. It is interesting to see how a working environment is -implemented. -Also, I -hope that you will pick up the habit of browsing through source code. -You can learn from it and mine it for ideas. Having GNU Emacs is like -having a dragon's cave of treasures. - -In addition to learning about Emacs as an editor and Emacs Lisp as a -programming language, the examples and guided tours will give you an -opportunity to get acquainted with Emacs as a Lisp programming -environment. GNU Emacs supports programming and provides tools that -you will want to become comfortable using, such as @kbd{M-.} (the key -which invokes the @code{find-tag} command). You will also learn about -buffers and other objects that are part of the environment. -Learning about these features of Emacs is like learning new routes -around your home town. - -@ignore -In addition, I have written several programs as extended examples. -Although these are examples, the programs are real. I use them. -Other people use them. You may use them. Beyond the fragments of -programs used for illustrations, there is very little in here that is -`just for teaching purposes'; what you see is used. This is a great -advantage of Emacs Lisp: it is easy to learn to use it for work. -@end ignore - -Finally, I hope to convey some of the skills for using Emacs to -learn aspects of programming that you don't know. You can often use -Emacs to help you understand what puzzles you or to find out how to do -something new. This self-reliance is not only a pleasure, but an -advantage. - -@node Who You Are, Lisp History, On Reading this Text, Preface -@comment node-name, next, previous, up -@unnumberedsec For Whom This is Written - -This text is written as an elementary introduction for people who are -not programmers. If you are a programmer, you may not be satisfied with -this primer. The reason is that you may have become expert at reading -reference manuals and be put off by the way this text is organized. - -An expert programmer who reviewed this text said to me: - -@quotation -@i{I prefer to learn from reference manuals. I ``dive into'' each -paragraph, and ``come up for air'' between paragraphs.} - -@i{When I get to the end of a paragraph, I assume that that subject is -done, finished, that I know everything I need (with the -possible exception of the case when the next paragraph starts talking -about it in more detail). I expect that a well written reference manual -will not have a lot of redundancy, and that it will have excellent -pointers to the (one) place where the information I want is.} -@end quotation - -This introduction is not written for this person! - -Firstly, I try to say everything at least three times: first, to -introduce it; second, to show it in context; and third, to show it in a -different context, or to review it. - -Secondly, I hardly ever put all the information about a subject in one -place, much less in one paragraph. To my way of thinking, that imposes -too heavy a burden on the reader. Instead I try to explain only what -you need to know at the time. (Sometimes I include a little extra -information so you won't be surprised later when the additional -information is formally introduced.) - -When you read this text, you are not expected to learn everything the -first time. Frequently, you need only make, as it were, a `nodding -acquaintance' with some of the items mentioned. My hope is that I have -structured the text and given you enough hints that you will be alert to -what is important, and concentrate on it. - -You will need to ``dive into'' some paragraphs; there is no other way -to read them. But I have tried to keep down the number of such -paragraphs. This book is intended as an approachable hill, rather than -as a daunting mountain. - -This introduction to @cite{Programming in Emacs Lisp} has a companion -document, -@iftex -@cite{The GNU Emacs Lisp Reference Manual}. -@end iftex -@ifnottex -@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU -Emacs Lisp Reference Manual}. -@end ifnottex -The reference manual has more detail than this introduction. In the -reference manual, all the information about one topic is concentrated -in one place. You should turn to it if you are like the programmer -quoted above. And, of course, after you have read this -@cite{Introduction}, you will find the @cite{Reference Manual} useful -when you are writing your own programs. - -@node Lisp History, Note for Novices, Who You Are, Preface -@unnumberedsec Lisp History -@cindex Lisp history - -Lisp was first developed in the late 1950s at the Massachusetts -Institute of Technology for research in artificial intelligence. The -great power of the Lisp language makes it superior for other purposes as -well, such as writing editor commands and integrated environments. - -@cindex Maclisp -@cindex Common Lisp -GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT -in the 1960s. It is somewhat inspired by Common Lisp, which became a -standard in the 1980s. However, Emacs Lisp is much simpler than Common -Lisp. (The standard Emacs distribution contains an optional extensions -file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) - -@node Note for Novices, Thank You, Lisp History, Preface -@comment node-name, next, previous, up -@unnumberedsec A Note for Novices - -If you don't know GNU Emacs, you can still read this document -profitably. However, I recommend you learn Emacs, if only to learn to -move around your computer screen. You can teach yourself how to use -Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This -means you press and release the @key{CTRL} key and the @kbd{h} at the -same time, and then press and release @kbd{t}.) - -Also, I often refer to one of Emacs's standard commands by listing the -keys which you press to invoke the command and then giving the name of -the command in parentheses, like this: @kbd{M-C-\} -(@code{indent-region}). What this means is that the -@code{indent-region} command is customarily invoked by typing -@kbd{M-C-\}. (You can, if you wish, change the keys that are typed to -invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, , -Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your -@key{META} key, @key{CTRL} key and @key{\} key all at the same time. -(On many modern keyboards the @key{META} key is labeled -@key{ALT}.) -Sometimes a combination like this is called a keychord, since it is -similar to the way you play a chord on a piano. If your keyboard does -not have a @key{META} key, the @key{ESC} key prefix is used in place -of it. In this case, @kbd{M-C-\} means that you press and release your -@key{ESC} key and then type the @key{CTRL} key and the @key{\} key at -the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key -along with the key that is labeled @key{ALT} and, at the same time, -press the @key{\} key. - -In addition to typing a lone keychord, you can prefix what you type -with @kbd{C-u}, which is called the `universal argument'. The -@kbd{C-u} keychord passes an argument to the subsequent command. -Thus, to indent a region of plain text by 6 spaces, mark the region, -and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number, -Emacs either passes the number 4 to the command or otherwise runs the -command differently than it would otherwise.) @xref{Arguments, , -Numeric Arguments, emacs, The GNU Emacs Manual}. - -If you are reading this in Info using GNU Emacs, you can read through -this whole document just by pressing the space bar, @key{SPC}. -(To learn about Info, type @kbd{C-h i} and then select Info.) - -A note on terminology: when I use the word Lisp alone, I often am -referring to the various dialects of Lisp in general, but when I speak -of Emacs Lisp, I am referring to GNU Emacs Lisp in particular. - -@node Thank You, , Note for Novices, Preface -@comment node-name, next, previous, up -@unnumberedsec Thank You - -My thanks to all who helped me with this book. My especial thanks to -@r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland -McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@: -Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both -@w{Philip Johnson} and @w{David Stampe} for their patient -encouragement. My mistakes are my own. - -@flushright -Robert J. Chassell -@email{bob@@gnu.org} -@end flushright - -@c ================ Beginning of main text ================ - -@c Start main text on right-hand (verso) page - -@tex -\par\vfill\supereject -\headings off -\ifodd\pageno - \par\vfill\supereject -\else - \par\vfill\supereject - \page\hbox{}\page - \par\vfill\supereject -\fi -@end tex - -@c Note: this resetting of the page number back to 1 causes TeX to gripe -@c about already having seen page numbers 1-4 before (in the preface): -@c pdfTeX warning (ext4): destination with the same identifier (name{1}) -@c has been already used, duplicate ignored -@c I guess that is harmless (what happens if a later part of the text -@c makes a link to something in the first 4 pages though?). -@c Note that eg the Emacs manual has a preface, but does not bother -@c resetting the page numbers back to 1 after that. -@iftex -@headings off -@evenheading @thispage @| @| @thischapter -@oddheading @thissection @| @| @thispage -@global@pageno = 1 -@end iftex - -@node List Processing, Practicing Evaluation, Preface, Top -@comment node-name, next, previous, up -@chapter List Processing - -To the untutored eye, Lisp is a strange programming language. In Lisp -code there are parentheses everywhere. Some people even claim that -the name stands for `Lots of Isolated Silly Parentheses'. But the -claim is unwarranted. Lisp stands for LISt Processing, and the -programming language handles @emph{lists} (and lists of lists) by -putting them between parentheses. The parentheses mark the boundaries -of the list. Sometimes a list is preceded by a single apostrophe or -quotation mark, @samp{'}@footnote{The single apostrophe or quotation -mark is an abbreviation for the function @code{quote}; you need not -think about functions now; functions are defined in @ref{Making -Errors, , Generate an Error Message}.} Lists are the basis of Lisp. - -@menu -* Lisp Lists:: What are lists? -* Run a Program:: Any list in Lisp is a program ready to run. -* Making Errors:: Generating an error message. -* Names & Definitions:: Names of symbols and function definitions. -* Lisp Interpreter:: What the Lisp interpreter does. -* Evaluation:: Running a program. -* Variables:: Returning a value from a variable. -* Arguments:: Passing information to a function. -* set & setq:: Setting the value of a variable. -* Summary:: The major points. -* Error Message Exercises:: -@end menu - -@node Lisp Lists, Run a Program, List Processing, List Processing -@comment node-name, next, previous, up -@section Lisp Lists -@cindex Lisp Lists - -In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}. -This list is preceded by a single apostrophe. It could just as well be -written as follows, which looks more like the kind of list you are likely -to be familiar with: - -@smallexample -@group -'(rose - violet - daisy - buttercup) -@end group -@end smallexample - -@noindent -The elements of this list are the names of the four different flowers, -separated from each other by whitespace and surrounded by parentheses, -like flowers in a field with a stone wall around them. -@cindex Flowers in a field - -@menu -* Numbers Lists:: List have numbers, other lists, in them. -* Lisp Atoms:: Elemental entities. -* Whitespace in Lists:: Formatting lists to be readable. -* Typing Lists:: How GNU Emacs helps you type lists. -@end menu - -@node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists -@ifnottex -@unnumberedsubsec Numbers, Lists inside of Lists -@end ifnottex - -Lists can also have numbers in them, as in this list: @code{(+ 2 2)}. -This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each -separated by whitespace. - -In Lisp, both data and programs are represented the same way; that is, -they are both lists of words, numbers, or other lists, separated by -whitespace and surrounded by parentheses. (Since a program looks like -data, one program may easily serve as data for another; this is a very -powerful feature of Lisp.) (Incidentally, these two parenthetical -remarks are @emph{not} Lisp lists, because they contain @samp{;} and -@samp{.} as punctuation marks.) - -@need 1200 -Here is another list, this time with a list inside of it: - -@smallexample -'(this list has (a list inside of it)) -@end smallexample - -The components of this list are the words @samp{this}, @samp{list}, -@samp{has}, and the list @samp{(a list inside of it)}. The interior -list is made up of the words @samp{a}, @samp{list}, @samp{inside}, -@samp{of}, @samp{it}. - -@node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists -@comment node-name, next, previous, up -@subsection Lisp Atoms -@cindex Lisp Atoms - -In Lisp, what we have been calling words are called @dfn{atoms}. This -term comes from the historical meaning of the word atom, which means -`indivisible'. As far as Lisp is concerned, the words we have been -using in the lists cannot be divided into any smaller parts and still -mean the same thing as part of a program; likewise with numbers and -single character symbols like @samp{+}. On the other hand, unlike an -ancient atom, a list can be split into parts. (@xref{car cdr & cons, -, @code{car} @code{cdr} & @code{cons} Fundamental Functions}.) - -In a list, atoms are separated from each other by whitespace. They can be -right next to a parenthesis. - -@cindex @samp{empty list} defined -Technically speaking, a list in Lisp consists of parentheses surrounding -atoms separated by whitespace or surrounding other lists or surrounding -both atoms and other lists. A list can have just one atom in it or -have nothing in it at all. A list with nothing in it looks like this: -@code{()}, and is called the @dfn{empty list}. Unlike anything else, an -empty list is considered both an atom and a list at the same time. - -@cindex Symbolic expressions, introduced -@cindex @samp{expression} defined -@cindex @samp{form} defined -The printed representation of both atoms and lists are called -@dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}. -The word @dfn{expression} by itself can refer to either the printed -representation, or to the atom or list as it is held internally in the -computer. Often, people use the term @dfn{expression} -indiscriminately. (Also, in many texts, the word @dfn{form} is used -as a synonym for expression.) - -Incidentally, the atoms that make up our universe were named such when -they were thought to be indivisible; but it has been found that physical -atoms are not indivisible. Parts can split off an atom or it can -fission into two parts of roughly equal size. Physical atoms were named -prematurely, before their truer nature was found. In Lisp, certain -kinds of atom, such as an array, can be separated into parts; but the -mechanism for doing this is different from the mechanism for splitting a -list. As far as list operations are concerned, the atoms of a list are -unsplittable. - -As in English, the meanings of the component letters of a Lisp atom -are different from the meaning the letters make as a word. For -example, the word for the South American sloth, the @samp{ai}, is -completely different from the two words, @samp{a}, and @samp{i}. - -There are many kinds of atom in nature but only a few in Lisp: for -example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such -as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have -listed in the examples above are all symbols. In everyday Lisp -conversation, the word ``atom'' is not often used, because programmers -usually try to be more specific about what kind of atom they are dealing -with. Lisp programming is mostly about symbols (and sometimes numbers) -within lists. (Incidentally, the preceding three word parenthetical -remark is a proper list in Lisp, since it consists of atoms, which in -this case are symbols, separated by whitespace and enclosed by -parentheses, without any non-Lisp punctuation.) - -@need 1250 -Text between double quotation marks---even sentences or -paragraphs---is also an atom. Here is an example: -@cindex Text between double quotation marks - -@smallexample -'(this list includes "text between quotation marks.") -@end smallexample - -@cindex @samp{string} defined -@noindent -In Lisp, all of the quoted text including the punctuation mark and the -blank spaces is a single atom. This kind of atom is called a -@dfn{string} (for `string of characters') and is the sort of thing that -is used for messages that a computer can print for a human to read. -Strings are a different kind of atom than numbers or symbols and are -used differently. - -@node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists -@comment node-name, next, previous, up -@subsection Whitespace in Lists -@cindex Whitespace in lists - -@need 1200 -The amount of whitespace in a list does not matter. From the point of view -of the Lisp language, - -@smallexample -@group -'(this list - looks like this) -@end group -@end smallexample - -@need 800 -@noindent -is exactly the same as this: - -@smallexample -'(this list looks like this) -@end smallexample - -Both examples show what to Lisp is the same list, the list made up of -the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and -@samp{this} in that order. - -Extra whitespace and newlines are designed to make a list more readable -by humans. When Lisp reads the expression, it gets rid of all the extra -whitespace (but it needs to have at least one space between atoms in -order to tell them apart.) - -Odd as it seems, the examples we have seen cover almost all of what Lisp -lists look like! Every other list in Lisp looks more or less like one -of these examples, except that the list may be longer and more complex. -In brief, a list is between parentheses, a string is between quotation -marks, a symbol looks like a word, and a number looks like a number. -(For certain situations, square brackets, dots and a few other special -characters may be used; however, we will go quite far without them.) - -@node Typing Lists, , Whitespace in Lists, Lisp Lists -@comment node-name, next, previous, up -@subsection GNU Emacs Helps You Type Lists -@cindex Help typing lists -@cindex Formatting help - -When you type a Lisp expression in GNU Emacs using either Lisp -Interaction mode or Emacs Lisp mode, you have available to you several -commands to format the Lisp expression so it is easy to read. For -example, pressing the @key{TAB} key automatically indents the line the -cursor is on by the right amount. A command to properly indent the -code in a region is customarily bound to @kbd{M-C-\}. Indentation is -designed so that you can see which elements of a list belong to which -list---elements of a sub-list are indented more than the elements of -the enclosing list. - -In addition, when you type a closing parenthesis, Emacs momentarily -jumps the cursor back to the matching opening parenthesis, so you can -see which one it is. This is very useful, since every list you type -in Lisp must have its closing parenthesis match its opening -parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs -Manual}, for more information about Emacs's modes.) - -@node Run a Program, Making Errors, Lisp Lists, List Processing -@comment node-name, next, previous, up -@section Run a Program -@cindex Run a program -@cindex Program, running one - -@cindex @samp{evaluate} defined -A list in Lisp---any list---is a program ready to run. If you run it -(for which the Lisp jargon is @dfn{evaluate}), the computer will do one -of three things: do nothing except return to you the list itself; send -you an error message; or, treat the first symbol in the list as a -command to do something. (Usually, of course, it is the last of these -three things that you really want!) - -@c use code for the single apostrophe, not samp. -The single apostrophe, @code{'}, that I put in front of some of the -example lists in preceding sections is called a @dfn{quote}; when it -precedes a list, it tells Lisp to do nothing with the list, other than -take it as it is written. But if there is no quote preceding a list, -the first item of the list is special: it is a command for the computer -to obey. (In Lisp, these commands are called @emph{functions}.) The list -@code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp -understands that the @code{+} is an instruction to do something with the -rest of the list: add the numbers that follow. - -@need 1250 -If you are reading this inside of GNU Emacs in Info, here is how you can -evaluate such a list: place your cursor immediately after the right -hand parenthesis of the following list and then type @kbd{C-x C-e}: - -@smallexample -(+ 2 2) -@end smallexample - -@c use code for the number four, not samp. -@noindent -You will see the number @code{4} appear in the echo area. (In the -jargon, what you have just done is ``evaluate the list.'' The echo area -is the line at the bottom of the screen that displays or ``echoes'' -text.) Now try the same thing with a quoted list: place the cursor -right after the following list and type @kbd{C-x C-e}: - -@smallexample -'(this is a quoted list) -@end smallexample - -@noindent -You will see @code{(this is a quoted list)} appear in the echo area. - -@cindex Lisp interpreter, explained -@cindex Interpreter, Lisp, explained -In both cases, what you are doing is giving a command to the program -inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the -interpreter a command to evaluate the expression. The name of the Lisp -interpreter comes from the word for the task done by a human who comes -up with the meaning of an expression---who ``interprets'' it. - -You can also evaluate an atom that is not part of a list---one that is -not surrounded by parentheses; again, the Lisp interpreter translates -from the humanly readable expression to the language of the computer. -But before discussing this (@pxref{Variables}), we will discuss what the -Lisp interpreter does when you make an error. - -@node Making Errors, Names & Definitions, Run a Program, List Processing -@comment node-name, next, previous, up -@section Generate an Error Message -@cindex Generate an error message -@cindex Error message generation - -Partly so you won't worry if you do it accidentally, we will now give -a command to the Lisp interpreter that generates an error message. -This is a harmless activity; and indeed, we will often try to generate -error messages intentionally. Once you understand the jargon, error -messages can be informative. Instead of being called ``error'' -messages, they should be called ``help'' messages. They are like -signposts to a traveler in a strange country; deciphering them can be -hard, but once understood, they can point the way. - -The error message is generated by a built-in GNU Emacs debugger. We -will `enter the debugger'. You get out of the debugger by typing @code{q}. - -What we will do is evaluate a list that is not quoted and does not -have a meaningful command as its first element. Here is a list almost -exactly the same as the one we just used, but without the single-quote -in front of it. Position the cursor right after it and type @kbd{C-x -C-e}: - -@smallexample -(this is an unquoted list) -@end smallexample - -@ignore -@noindent -What you see depends on which version of Emacs you are running. GNU -Emacs version 22 provides more information than version 20 and before. -First, the more recent result of generating an error; then the -earlier, version 20 result. - -@need 1250 -@noindent -In GNU Emacs version 22, a @file{*Backtrace*} window will open up and -you will see the following in it: -@end ignore - -A @file{*Backtrace*} window will open up and you should see the -following in it: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function this) - (this is an unquoted list) - eval((this is an unquoted list)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@need 1200 -@noindent -Your cursor will be in this window (you may have to wait a few seconds -before it becomes visible). To quit the debugger and make the -debugger window go away, type: - -@smallexample -q -@end smallexample - -@noindent -Please type @kbd{q} right now, so you become confident that you can -get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter -it. - -@cindex @samp{function} defined -Based on what we already know, we can almost read this error message. - -You read the @file{*Backtrace*} buffer from the bottom up; it tells -you what Emacs did. When you typed @kbd{C-x C-e}, you made an -interactive call to the command @code{eval-last-sexp}. @code{eval} is -an abbreviation for `evaluate' and @code{sexp} is an abbreviation for -`symbolic expression'. The command means `evaluate last symbolic -expression', which is the expression just before your cursor. - -Each line above tells you what the Lisp interpreter evaluated next. -The most recent action is at the top. The buffer is called the -@file{*Backtrace*} buffer because it enables you to track Emacs -backwards. - -@need 800 -At the top of the @file{*Backtrace*} buffer, you see the line: - -@smallexample -Debugger entered--Lisp error: (void-function this) -@end smallexample - -@noindent -The Lisp interpreter tried to evaluate the first atom of the list, the -word @samp{this}. It is this action that generated the error message -@samp{void-function this}. - -The message contains the words @samp{void-function} and @samp{this}. - -@cindex @samp{function} defined -The word @samp{function} was mentioned once before. It is a very -important word. For our purposes, we can define it by saying that a -@dfn{function} is a set of instructions to the computer that tell the -computer to do something. - -Now we can begin to understand the error message: @samp{void-function -this}. The function (that is, the word @samp{this}) does not have a -definition of any set of instructions for the computer to carry out. - -The slightly odd word, @samp{void-function}, is designed to cover the -way Emacs Lisp is implemented, which is that when a symbol does not -have a function definition attached to it, the place that should -contain the instructions is `void'. - -On the other hand, since we were able to add 2 plus 2 successfully, by -evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must -have a set of instructions for the computer to obey and those -instructions must be to add the numbers that follow the @code{+}. - -It is possible to prevent Emacs entering the debugger in cases like -this. We do not explain how to do that here, but we will mention what -the result looks like, because you may encounter a similar situation -if there is a bug in some Emacs code that you are using. In such -cases, you will see only one line of error message; it will appear in -the echo area and look like this: - -@smallexample -Symbol's function definition is void:@: this -@end smallexample - -@noindent -@ignore -(Also, your terminal may beep at you---some do, some don't; and others -blink. This is just a device to get your attention.) -@end ignore -The message goes away as soon as you type a key, even just to -move the cursor. - -We know the meaning of the word @samp{Symbol}. It refers to the first -atom of the list, the word @samp{this}. The word @samp{function} -refers to the instructions that tell the computer what to do. -(Technically, the symbol tells the computer where to find the -instructions, but this is a complication we can ignore for the -moment.) - -The error message can be understood: @samp{Symbol's function -definition is void:@: this}. The symbol (that is, the word -@samp{this}) lacks instructions for the computer to carry out. - -@node Names & Definitions, Lisp Interpreter, Making Errors, List Processing -@comment node-name, next, previous, up -@section Symbol Names and Function Definitions -@cindex Symbol names - -We can articulate another characteristic of Lisp based on what we have -discussed so far---an important characteristic: a symbol, like -@code{+}, is not itself the set of instructions for the computer to -carry out. Instead, the symbol is used, perhaps temporarily, as a way -of locating the definition or set of instructions. What we see is the -name through which the instructions can be found. Names of people -work the same way. I can be referred to as @samp{Bob}; however, I am -not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the -consciousness consistently associated with a particular life-form. -The name is not me, but it can be used to refer to me. - -In Lisp, one set of instructions can be attached to several names. -For example, the computer instructions for adding numbers can be -linked to the symbol @code{plus} as well as to the symbol @code{+} -(and are in some dialects of Lisp). Among humans, I can be referred -to as @samp{Robert} as well as @samp{Bob} and by other words as well. - -On the other hand, a symbol can have only one function definition -attached to it at a time. Otherwise, the computer would be confused as -to which definition to use. If this were the case among people, only -one person in the world could be named @samp{Bob}. However, the function -definition to which the name refers can be changed readily. -(@xref{Install, , Install a Function Definition}.) - -Since Emacs Lisp is large, it is customary to name symbols in a way -that identifies the part of Emacs to which the function belongs. -Thus, all the names for functions that deal with Texinfo start with -@samp{texinfo-} and those for functions that deal with reading mail -start with @samp{rmail-}. - -@node Lisp Interpreter, Evaluation, Names & Definitions, List Processing -@comment node-name, next, previous, up -@section The Lisp Interpreter -@cindex Lisp interpreter, what it does -@cindex Interpreter, what it does - -Based on what we have seen, we can now start to figure out what the -Lisp interpreter does when we command it to evaluate a list. -First, it looks to see whether there is a quote before the list; if -there is, the interpreter just gives us the list. On the other -hand, if there is no quote, the interpreter looks at the first element -in the list and sees whether it has a function definition. If it does, -the interpreter carries out the instructions in the function definition. -Otherwise, the interpreter prints an error message. - -This is how Lisp works. Simple. There are added complications which we -will get to in a minute, but these are the fundamentals. Of course, to -write Lisp programs, you need to know how to write function definitions -and attach them to names, and how to do this without confusing either -yourself or the computer. - -@menu -* Complications:: Variables, Special forms, Lists within. -* Byte Compiling:: Specially processing code for speed. -@end menu - -@node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter -@ifnottex -@unnumberedsubsec Complications -@end ifnottex - -Now, for the first complication. In addition to lists, the Lisp -interpreter can evaluate a symbol that is not quoted and does not have -parentheses around it. The Lisp interpreter will attempt to determine -the symbol's value as a @dfn{variable}. This situation is described -in the section on variables. (@xref{Variables}.) - -@cindex Special form -The second complication occurs because some functions are unusual and do -not work in the usual manner. Those that don't are called @dfn{special -forms}. They are used for special jobs, like defining a function, and -there are not many of them. In the next few chapters, you will be -introduced to several of the more important special forms. - -The third and final complication is this: if the function that the -Lisp interpreter is looking at is not a special form, and if it is part -of a list, the Lisp interpreter looks to see whether the list has a list -inside of it. If there is an inner list, the Lisp interpreter first -figures out what it should do with the inside list, and then it works on -the outside list. If there is yet another list embedded inside the -inner list, it works on that one first, and so on. It always works on -the innermost list first. The interpreter works on the innermost list -first, to evaluate the result of that list. The result may be -used by the enclosing expression. - -Otherwise, the interpreter works left to right, from one expression to -the next. - -@node Byte Compiling, , Complications, Lisp Interpreter -@subsection Byte Compiling -@cindex Byte compiling - -One other aspect of interpreting: the Lisp interpreter is able to -interpret two kinds of entity: humanly readable code, on which we will -focus exclusively, and specially processed code, called @dfn{byte -compiled} code, which is not humanly readable. Byte compiled code -runs faster than humanly readable code. - -You can transform humanly readable code into byte compiled code by -running one of the compile commands such as @code{byte-compile-file}. -Byte compiled code is usually stored in a file that ends with a -@file{.elc} extension rather than a @file{.el} extension. You will -see both kinds of file in the @file{emacs/lisp} directory; the files -to read are those with @file{.el} extensions. - -As a practical matter, for most things you might do to customize or -extend Emacs, you do not need to byte compile; and I will not discuss -the topic here. @xref{Byte Compilation, , Byte Compilation, elisp, -The GNU Emacs Lisp Reference Manual}, for a full description of byte -compilation. - -@node Evaluation, Variables, Lisp Interpreter, List Processing -@comment node-name, next, previous, up -@section Evaluation -@cindex Evaluation - -When the Lisp interpreter works on an expression, the term for the -activity is called @dfn{evaluation}. We say that the interpreter -`evaluates the expression'. I've used this term several times before. -The word comes from its use in everyday language, `to ascertain the -value or amount of; to appraise', according to @cite{Webster's New -Collegiate Dictionary}. - -@menu -* How the Interpreter Acts:: Returns and Side Effects... -* Evaluating Inner Lists:: Lists within lists... -@end menu - -@node How the Interpreter Acts, Evaluating Inner Lists, Evaluation, Evaluation -@ifnottex -@unnumberedsubsec How the Lisp Interpreter Acts -@end ifnottex - -@cindex @samp{returned value} explained -After evaluating an expression, the Lisp interpreter will most likely -@dfn{return} the value that the computer produces by carrying out the -instructions it found in the function definition, or perhaps it will -give up on that function and produce an error message. (The interpreter -may also find itself tossed, so to speak, to a different function or it -may attempt to repeat continually what it is doing for ever and ever in -what is called an `infinite loop'. These actions are less common; and -we can ignore them.) Most frequently, the interpreter returns a value. - -@cindex @samp{side effect} defined -At the same time the interpreter returns a value, it may do something -else as well, such as move a cursor or copy a file; this other kind of -action is called a @dfn{side effect}. Actions that we humans think are -important, such as printing results, are often ``side effects'' to the -Lisp interpreter. The jargon can sound peculiar, but it turns out that -it is fairly easy to learn to use side effects. - -In summary, evaluating a symbolic expression most commonly causes the -Lisp interpreter to return a value and perhaps carry out a side effect; -or else produce an error. - -@node Evaluating Inner Lists, , How the Interpreter Acts, Evaluation -@comment node-name, next, previous, up -@subsection Evaluating Inner Lists -@cindex Inner list evaluation -@cindex Evaluating inner lists - -If evaluation applies to a list that is inside another list, the outer -list may use the value returned by the first evaluation as information -when the outer list is evaluated. This explains why inner expressions -are evaluated first: the values they return are used by the outer -expressions. - -@need 1250 -We can investigate this process by evaluating another addition example. -Place your cursor after the following expression and type @kbd{C-x C-e}: - -@smallexample -(+ 2 (+ 3 3)) -@end smallexample - -@noindent -The number 8 will appear in the echo area. - -What happens is that the Lisp interpreter first evaluates the inner -expression, @code{(+ 3 3)}, for which the value 6 is returned; then it -evaluates the outer expression as if it were written @code{(+ 2 6)}, which -returns the value 8. Since there are no more enclosing expressions to -evaluate, the interpreter prints that value in the echo area. - -Now it is easy to understand the name of the command invoked by the -keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The -letters @code{sexp} are an abbreviation for `symbolic expression', and -@code{eval} is an abbreviation for `evaluate'. The command means -`evaluate last symbolic expression'. - -As an experiment, you can try evaluating the expression by putting the -cursor at the beginning of the next line immediately following the -expression, or inside the expression. - -@need 800 -Here is another copy of the expression: - -@smallexample -(+ 2 (+ 3 3)) -@end smallexample - -@noindent -If you place the cursor at the beginning of the blank line that -immediately follows the expression and type @kbd{C-x C-e}, you will -still get the value 8 printed in the echo area. Now try putting the -cursor inside the expression. If you put it right after the next to -last parenthesis (so it appears to sit on top of the last parenthesis), -you will get a 6 printed in the echo area! This is because the command -evaluates the expression @code{(+ 3 3)}. - -Now put the cursor immediately after a number. Type @kbd{C-x C-e} and -you will get the number itself. In Lisp, if you evaluate a number, you -get the number itself---this is how numbers differ from symbols. If you -evaluate a list starting with a symbol like @code{+}, you will get a -value returned that is the result of the computer carrying out the -instructions in the function definition attached to that name. If a -symbol by itself is evaluated, something different happens, as we will -see in the next section. - -@node Variables, Arguments, Evaluation, List Processing -@comment node-name, next, previous, up -@section Variables -@cindex Variables - -In Emacs Lisp, a symbol can have a value attached to it just as it can -have a function definition attached to it. The two are different. -The function definition is a set of instructions that a computer will -obey. A value, on the other hand, is something, such as number or a -name, that can vary (which is why such a symbol is called a variable). -The value of a symbol can be any expression in Lisp, such as a symbol, -number, list, or string. A symbol that has a value is often called a -@dfn{variable}. - -A symbol can have both a function definition and a value attached to -it at the same time. Or it can have just one or the other. -The two are separate. This is somewhat similar -to the way the name Cambridge can refer to the city in Massachusetts -and have some information attached to the name as well, such as -``great programming center''. - -@ignore -(Incidentally, in Emacs Lisp, a symbol can have two -other things attached to it, too: a property list and a documentation -string; these are discussed later.) -@end ignore - -Another way to think about this is to imagine a symbol as being a chest -of drawers. The function definition is put in one drawer, the value in -another, and so on. What is put in the drawer holding the value can be -changed without affecting the contents of the drawer holding the -function definition, and vice-verse. - -@menu -* fill-column Example:: -* Void Function:: The error message for a symbol - without a function. -* Void Variable:: The error message for a symbol without a value. -@end menu - -@node fill-column Example, Void Function, Variables, Variables -@ifnottex -@unnumberedsubsec @code{fill-column}, an Example Variable -@end ifnottex - -@findex fill-column, @r{an example variable} -@cindex Example variable, @code{fill-column} -@cindex Variable, example of, @code{fill-column} -The variable @code{fill-column} illustrates a symbol with a value -attached to it: in every GNU Emacs buffer, this symbol is set to some -value, usually 72 or 70, but sometimes to some other value. To find the -value of this symbol, evaluate it by itself. If you are reading this in -Info inside of GNU Emacs, you can do this by putting the cursor after -the symbol and typing @kbd{C-x C-e}: - -@smallexample -fill-column -@end smallexample - -@noindent -After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo -area. This is the value for which @code{fill-column} is set for me as I -write this. It may be different for you in your Info buffer. Notice -that the value returned as a variable is printed in exactly the same way -as the value returned by a function carrying out its instructions. From -the point of view of the Lisp interpreter, a value returned is a value -returned. What kind of expression it came from ceases to matter once -the value is known. - -A symbol can have any value attached to it or, to use the jargon, we can -@dfn{bind} the variable to a value: to a number, such as 72; to a -string, @code{"such as this"}; to a list, such as @code{(spruce pine -oak)}; we can even bind a variable to a function definition. - -A symbol can be bound to a value in several ways. @xref{set & setq, , -Setting the Value of a Variable}, for information about one way to do -this. - -@node Void Function, Void Variable, fill-column Example, Variables -@comment node-name, next, previous, up -@subsection Error Message for a Symbol Without a Function -@cindex Symbol without function error -@cindex Error for symbol without function - -When we evaluated @code{fill-column} to find its value as a variable, -we did not place parentheses around the word. This is because we did -not intend to use it as a function name. - -If @code{fill-column} were the first or only element of a list, the -Lisp interpreter would attempt to find the function definition -attached to it. But @code{fill-column} has no function definition. -Try evaluating this: - -@smallexample -(fill-column) -@end smallexample - -@need 1250 -@noindent -You will create a @file{*Backtrace*} buffer that says: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function fill-column) - (fill-column) - eval((fill-column)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -(Remember, to quit the debugger and make the debugger window go away, -type @kbd{q} in the @file{*Backtrace*} buffer.) - -@ignore -@need 800 -In GNU Emacs 20 and before, you will produce an error message that says: - -@smallexample -Symbol's function definition is void:@: fill-column -@end smallexample - -@noindent -(The message will go away as soon as you move the cursor or type -another key.) -@end ignore - -@node Void Variable, , Void Function, Variables -@comment node-name, next, previous, up -@subsection Error Message for a Symbol Without a Value -@cindex Symbol without value error -@cindex Error for symbol without value - -If you attempt to evaluate a symbol that does not have a value bound to -it, you will receive an error message. You can see this by -experimenting with our 2 plus 2 addition. In the following expression, -put your cursor right after the @code{+}, before the first number 2, -type @kbd{C-x C-e}: - -@smallexample -(+ 2 2) -@end smallexample - -@need 1500 -@noindent -In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that -says: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-variable +) - eval(+) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -(Again, you can quit the debugger by -typing @kbd{q} in the @file{*Backtrace*} buffer.) - -This backtrace is different from the very first error message we saw, -which said, @samp{Debugger entered--Lisp error: (void-function this)}. -In this case, the function does not have a value as a variable; while -in the other error message, the function (the word `this') did not -have a definition. - -In this experiment with the @code{+}, what we did was cause the Lisp -interpreter to evaluate the @code{+} and look for the value of the -variable instead of the function definition. We did this by placing the -cursor right after the symbol rather than after the parenthesis of the -enclosing list as we did before. As a consequence, the Lisp interpreter -evaluated the preceding s-expression, which in this case was -@code{+} by itself. - -Since @code{+} does not have a value bound to it, just the function -definition, the error message reported that the symbol's value as a -variable was void. - -@ignore -@need 800 -In GNU Emacs version 20 and before, your error message will say: - -@example -Symbol's value as variable is void:@: + -@end example - -@noindent -The meaning is the same as in GNU Emacs 22. -@end ignore - -@node Arguments, set & setq, Variables, List Processing -@comment node-name, next, previous, up -@section Arguments -@cindex Arguments -@cindex Passing information to functions - -To see how information is passed to functions, let's look again at -our old standby, the addition of two plus two. In Lisp, this is written -as follows: - -@smallexample -(+ 2 2) -@end smallexample - -If you evaluate this expression, the number 4 will appear in your echo -area. What the Lisp interpreter does is add the numbers that follow -the @code{+}. - -@cindex @samp{argument} defined -The numbers added by @code{+} are called the @dfn{arguments} of the -function @code{+}. These numbers are the information that is given to -or @dfn{passed} to the function. - -The word `argument' comes from the way it is used in mathematics and -does not refer to a disputation between two people; instead it refers to -the information presented to the function, in this case, to the -@code{+}. In Lisp, the arguments to a function are the atoms or lists -that follow the function. The values returned by the evaluation of -these atoms or lists are passed to the function. Different functions -require different numbers of arguments; some functions require none at -all.@footnote{It is curious to track the path by which the word `argument' -came to have two different meanings, one in mathematics and the other in -everyday English. According to the @cite{Oxford English Dictionary}, -the word derives from the Latin for @samp{to make clear, prove}; thus it -came to mean, by one thread of derivation, `the evidence offered as -proof', which is to say, `the information offered', which led to its -meaning in Lisp. But in the other thread of derivation, it came to mean -`to assert in a manner against which others may make counter -assertions', which led to the meaning of the word as a disputation. -(Note here that the English word has two different definitions attached -to it at the same time. By contrast, in Emacs Lisp, a symbol cannot -have two different function definitions at the same time.)} - -@menu -* Data types:: Types of data passed to a function. -* Args as Variable or List:: An argument can be the value - of a variable or list. -* Variable Number of Arguments:: Some functions may take a - variable number of arguments. -* Wrong Type of Argument:: Passing an argument of the wrong type - to a function. -* message:: A useful function for sending messages. -@end menu - -@node Data types, Args as Variable or List, Arguments, Arguments -@comment node-name, next, previous, up -@subsection Arguments' Data Types -@cindex Data types -@cindex Types of data -@cindex Arguments' data types - -The type of data that should be passed to a function depends on what -kind of information it uses. The arguments to a function such as -@code{+} must have values that are numbers, since @code{+} adds numbers. -Other functions use different kinds of data for their arguments. - -@need 1250 -@findex concat -For example, the @code{concat} function links together or unites two or -more strings of text to produce a string. The arguments are strings. -Concatenating the two character strings @code{abc}, @code{def} produces -the single string @code{abcdef}. This can be seen by evaluating the -following: - -@smallexample -(concat "abc" "def") -@end smallexample - -@noindent -The value produced by evaluating this expression is @code{"abcdef"}. - -A function such as @code{substring} uses both a string and numbers as -arguments. The function returns a part of the string, a substring of -the first argument. This function takes three arguments. Its first -argument is the string of characters, the second and third arguments are -numbers that indicate the beginning and end of the substring. The -numbers are a count of the number of characters (including spaces and -punctuation) from the beginning of the string. - -@need 800 -For example, if you evaluate the following: - -@smallexample -(substring "The quick brown fox jumped." 16 19) -@end smallexample - -@noindent -you will see @code{"fox"} appear in the echo area. The arguments are the -string and the two numbers. - -Note that the string passed to @code{substring} is a single atom even -though it is made up of several words separated by spaces. Lisp counts -everything between the two quotation marks as part of the string, -including the spaces. You can think of the @code{substring} function as -a kind of `atom smasher' since it takes an otherwise indivisible atom -and extracts a part. However, @code{substring} is only able to extract -a substring from an argument that is a string, not from another type of -atom such as a number or symbol. - -@node Args as Variable or List, Variable Number of Arguments, Data types, Arguments -@comment node-name, next, previous, up -@subsection An Argument as the Value of a Variable or List - -An argument can be a symbol that returns a value when it is evaluated. -For example, when the symbol @code{fill-column} by itself is evaluated, -it returns a number. This number can be used in an addition. - -@need 1250 -Position the cursor after the following expression and type @kbd{C-x -C-e}: - -@smallexample -(+ 2 fill-column) -@end smallexample - -@noindent -The value will be a number two more than what you get by evaluating -@code{fill-column} alone. For me, this is 74, because my value of -@code{fill-column} is 72. - -As we have just seen, an argument can be a symbol that returns a value -when evaluated. In addition, an argument can be a list that returns a -value when it is evaluated. For example, in the following expression, -the arguments to the function @code{concat} are the strings -@w{@code{"The "}} and @w{@code{" red foxes."}} and the list -@code{(number-to-string (+ 2 fill-column))}. - -@c For GNU Emacs 22, need number-to-string -@smallexample -(concat "The " (number-to-string (+ 2 fill-column)) " red foxes.") -@end smallexample - -@noindent -If you evaluate this expression---and if, as with my Emacs, -@code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will -appear in the echo area. (Note that you must put spaces after the -word @samp{The} and before the word @samp{red} so they will appear in -the final string. The function @code{number-to-string} converts the -integer that the addition function returns to a string. -@code{number-to-string} is also known as @code{int-to-string}.) - -@node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments -@comment node-name, next, previous, up -@subsection Variable Number of Arguments -@cindex Variable number of arguments -@cindex Arguments, variable number of - -Some functions, such as @code{concat}, @code{+} or @code{*}, take any -number of arguments. (The @code{*} is the symbol for multiplication.) -This can be seen by evaluating each of the following expressions in -the usual way. What you will see in the echo area is printed in this -text after @samp{@result{}}, which you may read as `evaluates to'. - -@need 1250 -In the first set, the functions have no arguments: - -@smallexample -@group -(+) @result{} 0 - -(*) @result{} 1 -@end group -@end smallexample - -@need 1250 -In this set, the functions have one argument each: - -@smallexample -@group -(+ 3) @result{} 3 - -(* 3) @result{} 3 -@end group -@end smallexample - -@need 1250 -In this set, the functions have three arguments each: - -@smallexample -@group -(+ 3 4 5) @result{} 12 - -(* 3 4 5) @result{} 60 -@end group -@end smallexample - -@node Wrong Type of Argument, message, Variable Number of Arguments, Arguments -@comment node-name, next, previous, up -@subsection Using the Wrong Type Object as an Argument -@cindex Wrong type of argument -@cindex Argument, wrong type of - -When a function is passed an argument of the wrong type, the Lisp -interpreter produces an error message. For example, the @code{+} -function expects the values of its arguments to be numbers. As an -experiment we can pass it the quoted symbol @code{hello} instead of a -number. Position the cursor after the following expression and type -@kbd{C-x C-e}: - -@smallexample -(+ 2 'hello) -@end smallexample - -@noindent -When you do this you will generate an error message. What has happened -is that @code{+} has tried to add the 2 to the value returned by -@code{'hello}, but the value returned by @code{'hello} is the symbol -@code{hello}, not a number. Only numbers can be added. So @code{+} -could not carry out its addition. - -@need 1250 -You will create and enter a @file{*Backtrace*} buffer that says: - -@noindent -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: - (wrong-type-argument number-or-marker-p hello) - +(2 hello) - eval((+ 2 (quote hello))) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@need 1250 -As usual, the error message tries to be helpful and makes sense after you -learn how to read it.@footnote{@code{(quote hello)} is an expansion of -the abbreviation @code{'hello}.} - -The first part of the error message is straightforward; it says -@samp{wrong type argument}. Next comes the mysterious jargon word -@w{@samp{number-or-marker-p}}. This word is trying to tell you what -kind of argument the @code{+} expected. - -The symbol @code{number-or-marker-p} says that the Lisp interpreter is -trying to determine whether the information presented it (the value of -the argument) is a number or a marker (a special object representing a -buffer position). What it does is test to see whether the @code{+} is -being given numbers to add. It also tests to see whether the -argument is something called a marker, which is a specific feature of -Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers. -When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command, -its position is kept as a marker. The mark can be considered a -number---the number of characters the location is from the beginning -of the buffer.) In Emacs Lisp, @code{+} can be used to add the -numeric value of marker positions as numbers. - -The @samp{p} of @code{number-or-marker-p} is the embodiment of a -practice started in the early days of Lisp programming. The @samp{p} -stands for `predicate'. In the jargon used by the early Lisp -researchers, a predicate refers to a function to determine whether some -property is true or false. So the @samp{p} tells us that -@code{number-or-marker-p} is the name of a function that determines -whether it is true or false that the argument supplied is a number or -a marker. Other Lisp symbols that end in @samp{p} include @code{zerop}, -a function that tests whether its argument has the value of zero, and -@code{listp}, a function that tests whether its argument is a list. - -Finally, the last part of the error message is the symbol @code{hello}. -This is the value of the argument that was passed to @code{+}. If the -addition had been passed the correct type of object, the value passed -would have been a number, such as 37, rather than a symbol like -@code{hello}. But then you would not have got the error message. - -@ignore -@need 1250 -In GNU Emacs version 20 and before, the echo area displays an error -message that says: - -@smallexample -Wrong type argument:@: number-or-marker-p, hello -@end smallexample - -This says, in different words, the same as the top line of the -@file{*Backtrace*} buffer. -@end ignore - -@node message, , Wrong Type of Argument, Arguments -@comment node-name, next, previous, up -@subsection The @code{message} Function -@findex message - -Like @code{+}, the @code{message} function takes a variable number of -arguments. It is used to send messages to the user and is so useful -that we will describe it here. - -@need 1250 -A message is printed in the echo area. For example, you can print a -message in your echo area by evaluating the following list: - -@smallexample -(message "This message appears in the echo area!") -@end smallexample - -The whole string between double quotation marks is a single argument -and is printed @i{in toto}. (Note that in this example, the message -itself will appear in the echo area within double quotes; that is -because you see the value returned by the @code{message} function. In -most uses of @code{message} in programs that you write, the text will -be printed in the echo area as a side-effect, without the quotes. -@xref{multiply-by-seven in detail, , @code{multiply-by-seven} in -detail}, for an example of this.) - -However, if there is a @samp{%s} in the quoted string of characters, the -@code{message} function does not print the @samp{%s} as such, but looks -to the argument that follows the string. It evaluates the second -argument and prints the value at the location in the string where the -@samp{%s} is. - -@need 1250 -You can see this by positioning the cursor after the following -expression and typing @kbd{C-x C-e}: - -@smallexample -(message "The name of this buffer is: %s." (buffer-name)) -@end smallexample - -@noindent -In Info, @code{"The name of this buffer is: *info*."} will appear in the -echo area. The function @code{buffer-name} returns the name of the -buffer as a string, which the @code{message} function inserts in place -of @code{%s}. - -To print a value as an integer, use @samp{%d} in the same way as -@samp{%s}. For example, to print a message in the echo area that -states the value of the @code{fill-column}, evaluate the following: - -@smallexample -(message "The value of fill-column is %d." fill-column) -@end smallexample - -@noindent -On my system, when I evaluate this list, @code{"The value of -fill-column is 72."} appears in my echo area@footnote{Actually, you -can use @code{%s} to print a number. It is non-specific. @code{%d} -prints only the part of a number left of a decimal point, and not -anything that is not a number.}. - -If there is more than one @samp{%s} in the quoted string, the value of -the first argument following the quoted string is printed at the -location of the first @samp{%s} and the value of the second argument is -printed at the location of the second @samp{%s}, and so on. - -@need 1250 -For example, if you evaluate the following, - -@smallexample -@group -(message "There are %d %s in the office!" - (- fill-column 14) "pink elephants") -@end group -@end smallexample - -@noindent -a rather whimsical message will appear in your echo area. On my system -it says, @code{"There are 58 pink elephants in the office!"}. - -The expression @code{(- fill-column 14)} is evaluated and the resulting -number is inserted in place of the @samp{%d}; and the string in double -quotes, @code{"pink elephants"}, is treated as a single argument and -inserted in place of the @samp{%s}. (That is to say, a string between -double quotes evaluates to itself, like a number.) - -Finally, here is a somewhat complex example that not only illustrates -the computation of a number, but also shows how you can use an -expression within an expression to generate the text that is substituted -for @samp{%s}: - -@smallexample -@group -(message "He saw %d %s" - (- fill-column 32) - (concat "red " - (substring - "The quick brown foxes jumped." 16 21) - " leaping.")) -@end group -@end smallexample - -In this example, @code{message} has three arguments: the string, -@code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and -the expression beginning with the function @code{concat}. The value -resulting from the evaluation of @code{(- fill-column 32)} is inserted -in place of the @samp{%d}; and the value returned by the expression -beginning with @code{concat} is inserted in place of the @samp{%s}. - -When your fill column is 70 and you evaluate the expression, the -message @code{"He saw 38 red foxes leaping."} appears in your echo -area. - -@node set & setq, Summary, Arguments, List Processing -@comment node-name, next, previous, up -@section Setting the Value of a Variable -@cindex Variable, setting value -@cindex Setting value of variable - -@cindex @samp{bind} defined -There are several ways by which a variable can be given a value. One of -the ways is to use either the function @code{set} or the function -@code{setq}. Another way is to use @code{let} (@pxref{let}). (The -jargon for this process is to @dfn{bind} a variable to a value.) - -The following sections not only describe how @code{set} and @code{setq} -work but also illustrate how arguments are passed. - -@menu -* Using set:: Setting values. -* Using setq:: Setting a quoted value. -* Counting:: Using @code{setq} to count. -@end menu - -@node Using set, Using setq, set & setq, set & setq -@comment node-name, next, previous, up -@subsection Using @code{set} -@findex set - -To set the value of the symbol @code{flowers} to the list @code{'(rose -violet daisy buttercup)}, evaluate the following expression by -positioning the cursor after the expression and typing @kbd{C-x C-e}. - -@smallexample -(set 'flowers '(rose violet daisy buttercup)) -@end smallexample - -@noindent -The list @code{(rose violet daisy buttercup)} will appear in the echo -area. This is what is @emph{returned} by the @code{set} function. As a -side effect, the symbol @code{flowers} is bound to the list; that is, -the symbol @code{flowers}, which can be viewed as a variable, is given -the list as its value. (This process, by the way, illustrates how a -side effect to the Lisp interpreter, setting the value, can be the -primary effect that we humans are interested in. This is because every -Lisp function must return a value if it does not get an error, but it -will only have a side effect if it is designed to have one.) - -After evaluating the @code{set} expression, you can evaluate the symbol -@code{flowers} and it will return the value you just set. Here is the -symbol. Place your cursor after it and type @kbd{C-x C-e}. - -@smallexample -flowers -@end smallexample - -@noindent -When you evaluate @code{flowers}, the list -@code{(rose violet daisy buttercup)} appears in the echo area. - -Incidentally, if you evaluate @code{'flowers}, the variable with a quote -in front of it, what you will see in the echo area is the symbol itself, -@code{flowers}. Here is the quoted symbol, so you can try this: - -@smallexample -'flowers -@end smallexample - -Note also, that when you use @code{set}, you need to quote both -arguments to @code{set}, unless you want them evaluated. Since we do -not want either argument evaluated, neither the variable -@code{flowers} nor the list @code{(rose violet daisy buttercup)}, both -are quoted. (When you use @code{set} without quoting its first -argument, the first argument is evaluated before anything else is -done. If you did this and @code{flowers} did not have a value -already, you would get an error message that the @samp{Symbol's value -as variable is void}; on the other hand, if @code{flowers} did return -a value after it was evaluated, the @code{set} would attempt to set -the value that was returned. There are situations where this is the -right thing for the function to do; but such situations are rare.) - -@node Using setq, Counting, Using set, set & setq -@comment node-name, next, previous, up -@subsection Using @code{setq} -@findex setq - -As a practical matter, you almost always quote the first argument to -@code{set}. The combination of @code{set} and a quoted first argument -is so common that it has its own name: the special form @code{setq}. -This special form is just like @code{set} except that the first argument -is quoted automatically, so you don't need to type the quote mark -yourself. Also, as an added convenience, @code{setq} permits you to set -several different variables to different values, all in one expression. - -To set the value of the variable @code{carnivores} to the list -@code{'(lion tiger leopard)} using @code{setq}, the following expression -is used: - -@smallexample -(setq carnivores '(lion tiger leopard)) -@end smallexample - -@noindent -This is exactly the same as using @code{set} except the first argument -is automatically quoted by @code{setq}. (The @samp{q} in @code{setq} -means @code{quote}.) - -@need 1250 -With @code{set}, the expression would look like this: - -@smallexample -(set 'carnivores '(lion tiger leopard)) -@end smallexample - -Also, @code{setq} can be used to assign different values to -different variables. The first argument is bound to the value -of the second argument, the third argument is bound to the value of the -fourth argument, and so on. For example, you could use the following to -assign a list of trees to the symbol @code{trees} and a list of herbivores -to the symbol @code{herbivores}: - -@smallexample -@group -(setq trees '(pine fir oak maple) - herbivores '(gazelle antelope zebra)) -@end group -@end smallexample - -@noindent -(The expression could just as well have been on one line, but it might -not have fit on a page; and humans find it easier to read nicely -formatted lists.) - -Although I have been using the term `assign', there is another way of -thinking about the workings of @code{set} and @code{setq}; and that is to -say that @code{set} and @code{setq} make the symbol @emph{point} to the -list. This latter way of thinking is very common and in forthcoming -chapters we shall come upon at least one symbol that has `pointer' as -part of its name. The name is chosen because the symbol has a value, -specifically a list, attached to it; or, expressed another way, -the symbol is set to ``point'' to the list. - -@node Counting, , Using setq, set & setq -@comment node-name, next, previous, up -@subsection Counting -@cindex Counting - -Here is an example that shows how to use @code{setq} in a counter. You -might use this to count how many times a part of your program repeats -itself. First set a variable to zero; then add one to the number each -time the program repeats itself. To do this, you need a variable that -serves as a counter, and two expressions: an initial @code{setq} -expression that sets the counter variable to zero; and a second -@code{setq} expression that increments the counter each time it is -evaluated. - -@smallexample -@group -(setq counter 0) ; @r{Let's call this the initializer.} - -(setq counter (+ counter 1)) ; @r{This is the incrementer.} - -counter ; @r{This is the counter.} -@end group -@end smallexample - -@noindent -(The text following the @samp{;} are comments. @xref{Change a -defun, , Change a Function Definition}.) - -If you evaluate the first of these expressions, the initializer, -@code{(setq counter 0)}, and then evaluate the third expression, -@code{counter}, the number @code{0} will appear in the echo area. If -you then evaluate the second expression, the incrementer, @code{(setq -counter (+ counter 1))}, the counter will get the value 1. So if you -again evaluate @code{counter}, the number @code{1} will appear in the -echo area. Each time you evaluate the second expression, the value of -the counter will be incremented. - -When you evaluate the incrementer, @code{(setq counter (+ counter 1))}, -the Lisp interpreter first evaluates the innermost list; this is the -addition. In order to evaluate this list, it must evaluate the variable -@code{counter} and the number @code{1}. When it evaluates the variable -@code{counter}, it receives its current value. It passes this value and -the number @code{1} to the @code{+} which adds them together. The sum -is then returned as the value of the inner list and passed to the -@code{setq} which sets the variable @code{counter} to this new value. -Thus, the value of the variable, @code{counter}, is changed. - -@node Summary, Error Message Exercises, set & setq, List Processing -@comment node-name, next, previous, up -@section Summary - -Learning Lisp is like climbing a hill in which the first part is the -steepest. You have now climbed the most difficult part; what remains -becomes easier as you progress onwards. - -@need 1000 -In summary, - -@itemize @bullet - -@item -Lisp programs are made up of expressions, which are lists or single atoms. - -@item -Lists are made up of zero or more atoms or inner lists, separated by whitespace and -surrounded by parentheses. A list can be empty. - -@item -Atoms are multi-character symbols, like @code{forward-paragraph}, single -character symbols like @code{+}, strings of characters between double -quotation marks, or numbers. - -@item -A number evaluates to itself. - -@item -A string between double quotes also evaluates to itself. - -@item -When you evaluate a symbol by itself, its value is returned. - -@item -When you evaluate a list, the Lisp interpreter looks at the first symbol -in the list and then at the function definition bound to that symbol. -Then the instructions in the function definition are carried out. - -@item -A single quotation mark, -@ifinfo -' -@end ifinfo -@ifnotinfo -@code{'} -@end ifnotinfo -, tells the Lisp interpreter that it should -return the following expression as written, and not evaluate it as it -would if the quote were not there. - -@item -Arguments are the information passed to a function. The arguments to a -function are computed by evaluating the rest of the elements of the list -of which the function is the first element. - -@item -A function always returns a value when it is evaluated (unless it gets -an error); in addition, it may also carry out some action called a -``side effect''. In many cases, a function's primary purpose is to -create a side effect. -@end itemize - -@node Error Message Exercises, , Summary, List Processing -@comment node-name, next, previous, up -@section Exercises - -A few simple exercises: - -@itemize @bullet -@item -Generate an error message by evaluating an appropriate symbol that is -not within parentheses. - -@item -Generate an error message by evaluating an appropriate symbol that is -between parentheses. - -@item -Create a counter that increments by two rather than one. - -@item -Write an expression that prints a message in the echo area when -evaluated. -@end itemize - -@node Practicing Evaluation, Writing Defuns, List Processing, Top -@comment node-name, next, previous, up -@chapter Practicing Evaluation -@cindex Practicing evaluation -@cindex Evaluation practice - -Before learning how to write a function definition in Emacs Lisp, it is -useful to spend a little time evaluating various expressions that have -already been written. These expressions will be lists with the -functions as their first (and often only) element. Since some of the -functions associated with buffers are both simple and interesting, we -will start with those. In this section, we will evaluate a few of -these. In another section, we will study the code of several other -buffer-related functions, to see how they were written. - -@menu -* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} - causes evaluation. -* Buffer Names:: Buffers and files are different. -* Getting Buffers:: Getting a buffer itself, not merely its name. -* Switching Buffers:: How to change to another buffer. -* Buffer Size & Locations:: Where point is located and the size of - the buffer. -* Evaluation Exercise:: -@end menu - -@node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation -@ifnottex -@unnumberedsec How to Evaluate -@end ifnottex - -@i{Whenever you give an editing command} to Emacs Lisp, such as the -command to move the cursor or to scroll the screen, @i{you are evaluating -an expression,} the first element of which is a function. @i{This is -how Emacs works.} - -@cindex @samp{interactive function} defined -@cindex @samp{command} defined -When you type keys, you cause the Lisp interpreter to evaluate an -expression and that is how you get your results. Even typing plain text -involves evaluating an Emacs Lisp function, in this case, one that uses -@code{self-insert-command}, which simply inserts the character you -typed. The functions you evaluate by typing keystrokes are called -@dfn{interactive} functions, or @dfn{commands}; how you make a function -interactive will be illustrated in the chapter on how to write function -definitions. @xref{Interactive, , Making a Function Interactive}. - -In addition to typing keyboard commands, we have seen a second way to -evaluate an expression: by positioning the cursor after a list and -typing @kbd{C-x C-e}. This is what we will do in the rest of this -section. There are other ways to evaluate an expression as well; these -will be described as we come to them. - -Besides being used for practicing evaluation, the functions shown in the -next few sections are important in their own right. A study of these -functions makes clear the distinction between buffers and files, how to -switch to a buffer, and how to determine a location within it. - -@node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation -@comment node-name, next, previous, up -@section Buffer Names -@findex buffer-name -@findex buffer-file-name - -The two functions, @code{buffer-name} and @code{buffer-file-name}, show -the difference between a file and a buffer. When you evaluate the -following expression, @code{(buffer-name)}, the name of the buffer -appears in the echo area. When you evaluate @code{(buffer-file-name)}, -the name of the file to which the buffer refers appears in the echo -area. Usually, the name returned by @code{(buffer-name)} is the same as -the name of the file to which it refers, and the name returned by -@code{(buffer-file-name)} is the full path-name of the file. - -A file and a buffer are two different entities. A file is information -recorded permanently in the computer (unless you delete it). A buffer, -on the other hand, is information inside of Emacs that will vanish at -the end of the editing session (or when you kill the buffer). Usually, -a buffer contains information that you have copied from a file; we say -the buffer is @dfn{visiting} that file. This copy is what you work on -and modify. Changes to the buffer do not change the file, until you -save the buffer. When you save the buffer, the buffer is copied to the file -and is thus saved permanently. - -@need 1250 -If you are reading this in Info inside of GNU Emacs, you can evaluate -each of the following expressions by positioning the cursor after it and -typing @kbd{C-x C-e}. - -@example -@group -(buffer-name) - -(buffer-file-name) -@end group -@end example - -@noindent -When I do this in Info, the value returned by evaluating -@code{(buffer-name)} is @file{"*info*"}, and the value returned by -evaluating @code{(buffer-file-name)} is @file{nil}. - -On the other hand, while I am writing this document, the value -returned by evaluating @code{(buffer-name)} is -@file{"introduction.texinfo"}, and the value returned by evaluating -@code{(buffer-file-name)} is -@file{"/gnu/work/intro/introduction.texinfo"}. - -@cindex @code{nil}, history of word -The former is the name of the buffer and the latter is the name of the -file. In Info, the buffer name is @file{"*info*"}. Info does not -point to any file, so the result of evaluating -@code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is -from the Latin word for `nothing'; in this case, it means that the -buffer is not associated with any file. (In Lisp, @code{nil} is also -used to mean `false' and is a synonym for the empty list, @code{()}.) - -When I am writing, the name of my buffer is -@file{"introduction.texinfo"}. The name of the file to which it -points is @file{"/gnu/work/intro/introduction.texinfo"}. - -(In the expressions, the parentheses tell the Lisp interpreter to -treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as -functions; without the parentheses, the interpreter would attempt to -evaluate the symbols as variables. @xref{Variables}.) - -In spite of the distinction between files and buffers, you will often -find that people refer to a file when they mean a buffer and vice-verse. -Indeed, most people say, ``I am editing a file,'' rather than saying, -``I am editing a buffer which I will soon save to a file.'' It is -almost always clear from context what people mean. When dealing with -computer programs, however, it is important to keep the distinction in mind, -since the computer is not as smart as a person. - -@cindex Buffer, history of word -The word `buffer', by the way, comes from the meaning of the word as a -cushion that deadens the force of a collision. In early computers, a -buffer cushioned the interaction between files and the computer's -central processing unit. The drums or tapes that held a file and the -central processing unit were pieces of equipment that were very -different from each other, working at their own speeds, in spurts. The -buffer made it possible for them to work together effectively. -Eventually, the buffer grew from being an intermediary, a temporary -holding place, to being the place where work is done. This -transformation is rather like that of a small seaport that grew into a -great city: once it was merely the place where cargo was warehoused -temporarily before being loaded onto ships; then it became a business -and cultural center in its own right. - -Not all buffers are associated with files. For example, a -@file{*scratch*} buffer does not visit any file. Similarly, a -@file{*Help*} buffer is not associated with any file. - -In the old days, when you lacked a @file{~/.emacs} file and started an -Emacs session by typing the command @code{emacs} alone, without naming -any files, Emacs started with the @file{*scratch*} buffer visible. -Nowadays, you will see a splash screen. You can follow one of the -commands suggested on the splash screen, visit a file, or press the -spacebar to reach the @file{*scratch*} buffer. - -If you switch to the @file{*scratch*} buffer, type -@code{(buffer-name)}, position the cursor after it, and then type -@kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"} -will be returned and will appear in the echo area. @code{"*scratch*"} -is the name of the buffer. When you type @code{(buffer-file-name)} in -the @file{*scratch*} buffer and evaluate that, @code{nil} will appear -in the echo area, just as it does when you evaluate -@code{(buffer-file-name)} in Info. - -Incidentally, if you are in the @file{*scratch*} buffer and want the -value returned by an expression to appear in the @file{*scratch*} -buffer itself rather than in the echo area, type @kbd{C-u C-x C-e} -instead of @kbd{C-x C-e}. This causes the value returned to appear -after the expression. The buffer will look like this: - -@smallexample -(buffer-name)"*scratch*" -@end smallexample - -@noindent -You cannot do this in Info since Info is read-only and it will not allow -you to change the contents of the buffer. But you can do this in any -buffer you can edit; and when you write code or documentation (such as -this book), this feature is very useful. - -@node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation -@comment node-name, next, previous, up -@section Getting Buffers -@findex current-buffer -@findex other-buffer -@cindex Getting a buffer - -The @code{buffer-name} function returns the @emph{name} of the buffer; -to get the buffer @emph{itself}, a different function is needed: the -@code{current-buffer} function. If you use this function in code, what -you get is the buffer itself. - -A name and the object or entity to which the name refers are different -from each other. You are not your name. You are a person to whom -others refer by name. If you ask to speak to George and someone hands you -a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r}, -@samp{g}, and @samp{e} written on it, you might be amused, but you would -not be satisfied. You do not want to speak to the name, but to the -person to whom the name refers. A buffer is similar: the name of the -scratch buffer is @file{*scratch*}, but the name is not the buffer. To -get a buffer itself, you need to use a function such as -@code{current-buffer}. - -However, there is a slight complication: if you evaluate -@code{current-buffer} in an expression on its own, as we will do here, -what you see is a printed representation of the name of the buffer -without the contents of the buffer. Emacs works this way for two -reasons: the buffer may be thousands of lines long---too long to be -conveniently displayed; and, another buffer may have the same contents -but a different name, and it is important to distinguish between them. - -@need 800 -Here is an expression containing the function: - -@smallexample -(current-buffer) -@end smallexample - -@noindent -If you evaluate this expression in Info in Emacs in the usual way, -@file{#} will appear in the echo area. The special -format indicates that the buffer itself is being returned, rather than -just its name. - -Incidentally, while you can type a number or symbol into a program, you -cannot do that with the printed representation of a buffer: the only way -to get a buffer itself is with a function such as @code{current-buffer}. - -A related function is @code{other-buffer}. This returns the most -recently selected buffer other than the one you are in currently, not -a printed representation of its name. If you have recently switched -back and forth from the @file{*scratch*} buffer, @code{other-buffer} -will return that buffer. - -@need 800 -You can see this by evaluating the expression: - -@smallexample -(other-buffer) -@end smallexample - -@noindent -You should see @file{#} appear in the echo area, or -the name of whatever other buffer you switched back from most -recently@footnote{Actually, by default, if the buffer from which you -just switched is visible to you in another window, @code{other-buffer} -will choose the most recent buffer that you cannot see; this is a -subtlety that I often forget.}. - -@node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation -@comment node-name, next, previous, up -@section Switching Buffers -@findex switch-to-buffer -@findex set-buffer -@cindex Switching to a buffer - -The @code{other-buffer} function actually provides a buffer when it is -used as an argument to a function that requires one. We can see this -by using @code{other-buffer} and @code{switch-to-buffer} to switch to a -different buffer. - -But first, a brief introduction to the @code{switch-to-buffer} -function. When you switched back and forth from Info to the -@file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most -likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or -rather, to save typing, you probably only typed @kbd{RET} if the -default buffer was @file{*scratch*}, or if it was different, then you -typed just part of the name, such as @code{*sc}, pressed your -@kbd{TAB} key to cause it to expand to the full name, and then typed -@kbd{RET}.} when prompted in the minibuffer for the name of -the buffer to which you wanted to switch. The keystrokes, @kbd{C-x -b}, cause the Lisp interpreter to evaluate the interactive function -@code{switch-to-buffer}. As we said before, this is how Emacs works: -different keystrokes call or run different functions. For example, -@kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls -@code{forward-sentence}, and so on. - -By writing @code{switch-to-buffer} in an expression, and giving it a -buffer to switch to, we can switch buffers just the way @kbd{C-x b} -does: - -@smallexample -(switch-to-buffer (other-buffer)) -@end smallexample - -@noindent -The symbol @code{switch-to-buffer} is the first element of the list, -so the Lisp interpreter will treat it as a function and carry out the -instructions that are attached to it. But before doing that, the -interpreter will note that @code{other-buffer} is inside parentheses -and work on that symbol first. @code{other-buffer} is the first (and -in this case, the only) element of this list, so the Lisp interpreter -calls or runs the function. It returns another buffer. Next, the -interpreter runs @code{switch-to-buffer}, passing to it, as an -argument, the other buffer, which is what Emacs will switch to. If -you are reading this in Info, try this now. Evaluate the expression. -(To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this -expression will move you to your most recent other buffer that you -cannot see. If you really want to go to your most recently selected -buffer, even if you can still see it, you need to evaluate the -following more complex expression: - -@smallexample -(switch-to-buffer (other-buffer (current-buffer) t)) -@end smallexample - -@c noindent -In this case, the first argument to @code{other-buffer} tells it which -buffer to skip---the current one---and the second argument tells -@code{other-buffer} it is OK to switch to a visible buffer. -In regular use, @code{switch-to-buffer} takes you to an invisible -window since you would most likely use @kbd{C-x o} (@code{other-window}) -to go to another visible buffer.} - -In the programming examples in later sections of this document, you will -see the function @code{set-buffer} more often than -@code{switch-to-buffer}. This is because of a difference between -computer programs and humans: humans have eyes and expect to see the -buffer on which they are working on their computer terminals. This is -so obvious, it almost goes without saying. However, programs do not -have eyes. When a computer program works on a buffer, that buffer does -not need to be visible on the screen. - -@code{switch-to-buffer} is designed for humans and does two different -things: it switches the buffer to which Emacs's attention is directed; and -it switches the buffer displayed in the window to the new buffer. -@code{set-buffer}, on the other hand, does only one thing: it switches -the attention of the computer program to a different buffer. The buffer -on the screen remains unchanged (of course, normally nothing happens -there until the command finishes running). - -@cindex @samp{call} defined -Also, we have just introduced another jargon term, the word @dfn{call}. -When you evaluate a list in which the first symbol is a function, you -are calling that function. The use of the term comes from the notion of -the function as an entity that can do something for you if you `call' -it---just as a plumber is an entity who can fix a leak if you call him -or her. - -@node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation -@comment node-name, next, previous, up -@section Buffer Size and the Location of Point -@cindex Size of buffer -@cindex Buffer size -@cindex Point location -@cindex Location of point - -Finally, let's look at several rather simple functions, -@code{buffer-size}, @code{point}, @code{point-min}, and -@code{point-max}. These give information about the size of a buffer and -the location of point within it. - -The function @code{buffer-size} tells you the size of the current -buffer; that is, the function returns a count of the number of -characters in the buffer. - -@smallexample -(buffer-size) -@end smallexample - -@noindent -You can evaluate this in the usual way, by positioning the -cursor after the expression and typing @kbd{C-x C-e}. - -@cindex @samp{point} defined -In Emacs, the current position of the cursor is called @dfn{point}. -The expression @code{(point)} returns a number that tells you where the -cursor is located as a count of the number of characters from the -beginning of the buffer up to point. - -@need 1250 -You can see the character count for point in this buffer by evaluating -the following expression in the usual way: - -@smallexample -(point) -@end smallexample - -@noindent -As I write this, the value of @code{point} is 65724. The @code{point} -function is frequently used in some of the examples later in this -book. - -@need 1250 -The value of point depends, of course, on its location within the -buffer. If you evaluate point in this spot, the number will be larger: - -@smallexample -(point) -@end smallexample - -@noindent -For me, the value of point in this location is 66043, which means that -there are 319 characters (including spaces) between the two -expressions. (Doubtless, you will see different numbers, since I will -have edited this since I first evaluated point.) - -@cindex @samp{narrowing} defined -The function @code{point-min} is somewhat similar to @code{point}, but -it returns the value of the minimum permissible value of point in the -current buffer. This is the number 1 unless @dfn{narrowing} is in -effect. (Narrowing is a mechanism whereby you can restrict yourself, -or a program, to operations on just a part of a buffer. -@xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the -function @code{point-max} returns the value of the maximum permissible -value of point in the current buffer. - -@node Evaluation Exercise, , Buffer Size & Locations, Practicing Evaluation -@section Exercise - -Find a file with which you are working and move towards its middle. -Find its buffer name, file name, length, and your position in the file. - -@node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top -@comment node-name, next, previous, up -@chapter How To Write Function Definitions -@cindex Definition writing -@cindex Function definition writing -@cindex Writing a function definition - -When the Lisp interpreter evaluates a list, it looks to see whether the -first symbol on the list has a function definition attached to it; or, -put another way, whether the symbol points to a function definition. If -it does, the computer carries out the instructions in the definition. A -symbol that has a function definition is called, simply, a function -(although, properly speaking, the definition is the function and the -symbol refers to it.) - -@menu -* Primitive Functions:: -* defun:: The @code{defun} special form. -* Install:: Install a function definition. -* Interactive:: Making a function interactive. -* Interactive Options:: Different options for @code{interactive}. -* Permanent Installation:: Installing code permanently. -* let:: Creating and initializing local variables. -* if:: What if? -* else:: If--then--else expressions. -* Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. -* Review:: -* defun Exercises:: -@end menu - -@node Primitive Functions, defun, Writing Defuns, Writing Defuns -@ifnottex -@unnumberedsec An Aside about Primitive Functions -@end ifnottex -@cindex Primitive functions -@cindex Functions, primitive - -@cindex C language primitives -@cindex Primitives written in C -All functions are defined in terms of other functions, except for a few -@dfn{primitive} functions that are written in the C programming -language. When you write functions' definitions, you will write them in -Emacs Lisp and use other functions as your building blocks. Some of the -functions you will use will themselves be written in Emacs Lisp (perhaps -by you) and some will be primitives written in C. The primitive -functions are used exactly like those written in Emacs Lisp and behave -like them. They are written in C so we can easily run GNU Emacs on any -computer that has sufficient power and can run C. - -Let me re-emphasize this: when you write code in Emacs Lisp, you do not -distinguish between the use of functions written in C and the use of -functions written in Emacs Lisp. The difference is irrelevant. I -mention the distinction only because it is interesting to know. Indeed, -unless you investigate, you won't know whether an already-written -function is written in Emacs Lisp or C. - -@node defun, Install, Primitive Functions, Writing Defuns -@comment node-name, next, previous, up -@section The @code{defun} Special Form -@findex defun -@cindex Special form of @code{defun} - -@cindex @samp{function definition} defined -In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to -it that tells the computer what to do when the function is called. -This code is called the @dfn{function definition} and is created by -evaluating a Lisp expression that starts with the symbol @code{defun} -(which is an abbreviation for @emph{define function}). Because -@code{defun} does not evaluate its arguments in the usual way, it is -called a @dfn{special form}. - -In subsequent sections, we will look at function definitions from the -Emacs source code, such as @code{mark-whole-buffer}. In this section, -we will describe a simple function definition so you can see how it -looks. This function definition uses arithmetic because it makes for a -simple example. Some people dislike examples using arithmetic; however, -if you are such a person, do not despair. Hardly any of the code we -will study in the remainder of this introduction involves arithmetic or -mathematics. The examples mostly involve text in one way or another. - -A function definition has up to five parts following the word -@code{defun}: - -@enumerate -@item -The name of the symbol to which the function definition should be -attached. - -@item -A list of the arguments that will be passed to the function. If no -arguments will be passed to the function, this is an empty list, -@code{()}. - -@item -Documentation describing the function. (Technically optional, but -strongly recommended.) - -@item -Optionally, an expression to make the function interactive so you can -use it by typing @kbd{M-x} and then the name of the function; or by -typing an appropriate key or keychord. - -@cindex @samp{body} defined -@item -The code that instructs the computer what to do: the @dfn{body} of the -function definition. -@end enumerate - -It is helpful to think of the five parts of a function definition as -being organized in a template, with slots for each part: - -@smallexample -@group -(defun @var{function-name} (@var{arguments}@dots{}) - "@var{optional-documentation}@dots{}" - (interactive @var{argument-passing-info}) ; @r{optional} - @var{body}@dots{}) -@end group -@end smallexample - -As an example, here is the code for a function that multiplies its -argument by 7. (This example is not interactive. @xref{Interactive, -, Making a Function Interactive}, for that information.) - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) -@end group -@end smallexample - -This definition begins with a parenthesis and the symbol @code{defun}, -followed by the name of the function. - -@cindex @samp{argument list} defined -The name of the function is followed by a list that contains the -arguments that will be passed to the function. This list is called -the @dfn{argument list}. In this example, the list has only one -element, the symbol, @code{number}. When the function is used, the -symbol will be bound to the value that is used as the argument to the -function. - -Instead of choosing the word @code{number} for the name of the argument, -I could have picked any other name. For example, I could have chosen -the word @code{multiplicand}. I picked the word `number' because it -tells what kind of value is intended for this slot; but I could just as -well have chosen the word `multiplicand' to indicate the role that the -value placed in this slot will play in the workings of the function. I -could have called it @code{foogle}, but that would have been a bad -choice because it would not tell humans what it means. The choice of -name is up to the programmer and should be chosen to make the meaning of -the function clear. - -Indeed, you can choose any name you wish for a symbol in an argument -list, even the name of a symbol used in some other function: the name -you use in an argument list is private to that particular definition. -In that definition, the name refers to a different entity than any use -of the same name outside the function definition. Suppose you have a -nick-name `Shorty' in your family; when your family members refer to -`Shorty', they mean you. But outside your family, in a movie, for -example, the name `Shorty' refers to someone else. Because a name in an -argument list is private to the function definition, you can change the -value of such a symbol inside the body of a function without changing -its value outside the function. The effect is similar to that produced -by a @code{let} expression. (@xref{let, , @code{let}}.) - -@ignore -Note also that we discuss the word `number' in two different ways: as a -symbol that appears in the code, and as the name of something that will -be replaced by a something else during the evaluation of the function. -In the first case, @code{number} is a symbol, not a number; it happens -that within the function, it is a variable who value is the number in -question, but our primary interest in it is as a symbol. On the other -hand, when we are talking about the function, our interest is that we -will substitute a number for the word @var{number}. To keep this -distinction clear, we use different typography for the two -circumstances. When we talk about this function, or about how it works, -we refer to this number by writing @var{number}. In the function -itself, we refer to it by writing @code{number}. -@end ignore - -The argument list is followed by the documentation string that -describes the function. This is what you see when you type -@w{@kbd{C-h f}} and the name of a function. Incidentally, when you -write a documentation string like this, you should make the first line -a complete sentence since some commands, such as @code{apropos}, print -only the first line of a multi-line documentation string. Also, you -should not indent the second line of a documentation string, if you -have one, because that looks odd when you use @kbd{C-h f} -(@code{describe-function}). The documentation string is optional, but -it is so useful, it should be included in almost every function you -write. - -@findex * @r{(multiplication)} -The third line of the example consists of the body of the function -definition. (Most functions' definitions, of course, are longer than -this.) In this function, the body is the list, @code{(* 7 number)}, which -says to multiply the value of @var{number} by 7. (In Emacs Lisp, -@code{*} is the function for multiplication, just as @code{+} is the -function for addition.) - -When you use the @code{multiply-by-seven} function, the argument -@code{number} evaluates to the actual number you want used. Here is an -example that shows how @code{multiply-by-seven} is used; but don't try -to evaluate this yet! - -@smallexample -(multiply-by-seven 3) -@end smallexample - -@noindent -The symbol @code{number}, specified in the function definition in the -next section, is given or ``bound to'' the value 3 in the actual use of -the function. Note that although @code{number} was inside parentheses -in the function definition, the argument passed to the -@code{multiply-by-seven} function is not in parentheses. The -parentheses are written in the function definition so the computer can -figure out where the argument list ends and the rest of the function -definition begins. - -If you evaluate this example, you are likely to get an error message. -(Go ahead, try it!) This is because we have written the function -definition, but not yet told the computer about the definition---we have -not yet installed (or `loaded') the function definition in Emacs. -Installing a function is the process that tells the Lisp interpreter the -definition of the function. Installation is described in the next -section. - -@node Install, Interactive, defun, Writing Defuns -@comment node-name, next, previous, up -@section Install a Function Definition -@cindex Install a Function Definition -@cindex Definition installation -@cindex Function definition installation - -If you are reading this inside of Info in Emacs, you can try out the -@code{multiply-by-seven} function by first evaluating the function -definition and then evaluating @code{(multiply-by-seven 3)}. A copy of -the function definition follows. Place the cursor after the last -parenthesis of the function definition and type @kbd{C-x C-e}. When you -do this, @code{multiply-by-seven} will appear in the echo area. (What -this means is that when a function definition is evaluated, the value it -returns is the name of the defined function.) At the same time, this -action installs the function definition. - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) -@end group -@end smallexample - -@noindent -By evaluating this @code{defun}, you have just installed -@code{multiply-by-seven} in Emacs. The function is now just as much a -part of Emacs as @code{forward-word} or any other editing function you -use. (@code{multiply-by-seven} will stay installed until you quit -Emacs. To reload code automatically whenever you start Emacs, see -@ref{Permanent Installation, , Installing Code Permanently}.) - -@menu -* Effect of installation:: -* Change a defun:: How to change a function definition. -@end menu - -@node Effect of installation, Change a defun, Install, Install -@ifnottex -@unnumberedsubsec The effect of installation -@end ifnottex - -You can see the effect of installing @code{multiply-by-seven} by -evaluating the following sample. Place the cursor after the following -expression and type @kbd{C-x C-e}. The number 21 will appear in the -echo area. - -@smallexample -(multiply-by-seven 3) -@end smallexample - -If you wish, you can read the documentation for the function by typing -@kbd{C-h f} (@code{describe-function}) and then the name of the -function, @code{multiply-by-seven}. When you do this, a -@file{*Help*} window will appear on your screen that says: - -@smallexample -@group -multiply-by-seven is a Lisp function. -(multiply-by-seven NUMBER) - -Multiply NUMBER by seven. -@end group -@end smallexample - -@noindent -(To return to a single window on your screen, type @kbd{C-x 1}.) - -@node Change a defun, , Effect of installation, Install -@comment node-name, next, previous, up -@subsection Change a Function Definition -@cindex Changing a function definition -@cindex Function definition, how to change -@cindex Definition, how to change - -If you want to change the code in @code{multiply-by-seven}, just rewrite -it. To install the new version in place of the old one, evaluate the -function definition again. This is how you modify code in Emacs. It is -very simple. - -As an example, you can change the @code{multiply-by-seven} function to -add the number to itself seven times instead of multiplying the number -by seven. It produces the same answer, but by a different path. At -the same time, we will add a comment to the code; a comment is text -that the Lisp interpreter ignores, but that a human reader may find -useful or enlightening. The comment is that this is the ``second -version''. - -@smallexample -@group -(defun multiply-by-seven (number) ; @r{Second version.} - "Multiply NUMBER by seven." - (+ number number number number number number number)) -@end group -@end smallexample - -@cindex Comments in Lisp code -The comment follows a semicolon, @samp{;}. In Lisp, everything on a -line that follows a semicolon is a comment. The end of the line is the -end of the comment. To stretch a comment over two or more lines, begin -each line with a semicolon. - -@xref{Beginning a .emacs File, , Beginning a @file{.emacs} -File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp -Reference Manual}, for more about comments. - -You can install this version of the @code{multiply-by-seven} function by -evaluating it in the same way you evaluated the first function: place -the cursor after the last parenthesis and type @kbd{C-x C-e}. - -In summary, this is how you write code in Emacs Lisp: you write a -function; install it; test it; and then make fixes or enhancements and -install it again. - -@node Interactive, Interactive Options, Install, Writing Defuns -@comment node-name, next, previous, up -@section Make a Function Interactive -@cindex Interactive functions -@findex interactive - -You make a function interactive by placing a list that begins with -the special form @code{interactive} immediately after the -documentation. A user can invoke an interactive function by typing -@kbd{M-x} and then the name of the function; or by typing the keys to -which it is bound, for example, by typing @kbd{C-n} for -@code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}. - -Interestingly, when you call an interactive function interactively, -the value returned is not automatically displayed in the echo area. -This is because you often call an interactive function for its side -effects, such as moving forward by a word or line, and not for the -value returned. If the returned value were displayed in the echo area -each time you typed a key, it would be very distracting. - -@menu -* Interactive multiply-by-seven:: An overview. -* multiply-by-seven in detail:: The interactive version. -@end menu - -@node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive -@ifnottex -@unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview -@end ifnottex - -Both the use of the special form @code{interactive} and one way to -display a value in the echo area can be illustrated by creating an -interactive version of @code{multiply-by-seven}. - -@need 1250 -Here is the code: - -@smallexample -@group -(defun multiply-by-seven (number) ; @r{Interactive version.} - "Multiply NUMBER by seven." - (interactive "p") - (message "The result is %d" (* 7 number))) -@end group -@end smallexample - -@noindent -You can install this code by placing your cursor after it and typing -@kbd{C-x C-e}. The name of the function will appear in your echo area. -Then, you can use this code by typing @kbd{C-u} and a number and then -typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase -@samp{The result is @dots{}} followed by the product will appear in the -echo area. - -Speaking more generally, you invoke a function like this in either of two -ways: - -@enumerate -@item -By typing a prefix argument that contains the number to be passed, and -then typing @kbd{M-x} and the name of the function, as with -@kbd{C-u 3 M-x forward-sentence}; or, - -@item -By typing whatever key or keychord the function is bound to, as with -@kbd{C-u 3 M-e}. -@end enumerate - -@noindent -Both the examples just mentioned work identically to move point forward -three sentences. (Since @code{multiply-by-seven} is not bound to a key, -it could not be used as an example of key binding.) - -(@xref{Keybindings, , Some Keybindings}, to learn how to bind a command -to a key.) - -A prefix argument is passed to an interactive function by typing the -@key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by -typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you -type @kbd{C-u} without a number, it defaults to 4). - -@node multiply-by-seven in detail, , Interactive multiply-by-seven, Interactive -@comment node-name, next, previous, up -@subsection An Interactive @code{multiply-by-seven} - -Let's look at the use of the special form @code{interactive} and then at -the function @code{message} in the interactive version of -@code{multiply-by-seven}. You will recall that the function definition -looks like this: - -@smallexample -@group -(defun multiply-by-seven (number) ; @r{Interactive version.} - "Multiply NUMBER by seven." - (interactive "p") - (message "The result is %d" (* 7 number))) -@end group -@end smallexample - -In this function, the expression, @code{(interactive "p")}, is a list of -two elements. The @code{"p"} tells Emacs to pass the prefix argument to -the function and use its value for the argument of the function. - -@need 1000 -The argument will be a number. This means that the symbol -@code{number} will be bound to a number in the line: - -@smallexample -(message "The result is %d" (* 7 number)) -@end smallexample - -@need 1250 -@noindent -For example, if your prefix argument is 5, the Lisp interpreter will -evaluate the line as if it were: - -@smallexample -(message "The result is %d" (* 7 5)) -@end smallexample - -@noindent -(If you are reading this in GNU Emacs, you can evaluate this expression -yourself.) First, the interpreter will evaluate the inner list, which -is @code{(* 7 5)}. This returns a value of 35. Next, it -will evaluate the outer list, passing the values of the second and -subsequent elements of the list to the function @code{message}. - -As we have seen, @code{message} is an Emacs Lisp function especially -designed for sending a one line message to a user. (@xref{message, , -The @code{message} function}.) In summary, the @code{message} -function prints its first argument in the echo area as is, except for -occurrences of @samp{%d} or @samp{%s} (and various other %-sequences -which we have not mentioned). When it sees a control sequence, the -function looks to the second or subsequent arguments and prints the -value of the argument in the location in the string where the control -sequence is located. - -In the interactive @code{multiply-by-seven} function, the control string -is @samp{%d}, which requires a number, and the value returned by -evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35 -is printed in place of the @samp{%d} and the message is @samp{The result -is 35}. - -(Note that when you call the function @code{multiply-by-seven}, the -message is printed without quotes, but when you call @code{message}, the -text is printed in double quotes. This is because the value returned by -@code{message} is what appears in the echo area when you evaluate an -expression whose first element is @code{message}; but when embedded in a -function, @code{message} prints the text as a side effect without -quotes.) - -@node Interactive Options, Permanent Installation, Interactive, Writing Defuns -@comment node-name, next, previous, up -@section Different Options for @code{interactive} -@cindex Options for @code{interactive} -@cindex Interactive options - -In the example, @code{multiply-by-seven} used @code{"p"} as the -argument to @code{interactive}. This argument told Emacs to interpret -your typing either @kbd{C-u} followed by a number or @key{META} -followed by a number as a command to pass that number to the function -as its argument. Emacs has more than twenty characters predefined for -use with @code{interactive}. In almost every case, one of these -options will enable you to pass the right information interactively to -a function. (@xref{Interactive Codes, , Code Characters for -@code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.) - -@need 1250 -Consider the function @code{zap-to-char}. Its interactive expression -is - -@smallexample -(interactive "p\ncZap to char: ") -@end smallexample - -The first part of the argument to @code{interactive} is @samp{p}, with -which you are already familiar. This argument tells Emacs to -interpret a `prefix', as a number to be passed to the function. You -can specify a prefix either by typing @kbd{C-u} followed by a number -or by typing @key{META} followed by a number. The prefix is the -number of specified characters. Thus, if your prefix is three and the -specified character is @samp{x}, then you will delete all the text up -to and including the third next @samp{x}. If you do not set a prefix, -then you delete all the text up to and including the specified -character, but no more. - -The @samp{c} tells the function the name of the character to which to delete. - -More formally, a function with two or more arguments can have -information passed to each argument by adding parts to the string that -follows @code{interactive}. When you do this, the information is -passed to each argument in the same order it is specified in the -@code{interactive} list. In the string, each part is separated from -the next part by a @samp{\n}, which is a newline. For example, you -can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }. -This causes Emacs to pass the value of the prefix argument (if there -is one) and the character. - -In this case, the function definition looks like the following, where -@code{arg} and @code{char} are the symbols to which @code{interactive} -binds the prefix argument and the specified character: - -@smallexample -@group -(defun @var{name-of-function} (arg char) - "@var{documentation}@dots{}" - (interactive "p\ncZap to char: ") - @var{body-of-function}@dots{}) -@end group -@end smallexample - -@noindent -(The space after the colon in the prompt makes it look better when you -are prompted. @xref{copy-to-buffer, , The Definition of -@code{copy-to-buffer}}, for an example.) - -When a function does not take arguments, @code{interactive} does not -require any. Such a function contains the simple expression -@code{(interactive)}. The @code{mark-whole-buffer} function is like -this. - -Alternatively, if the special letter-codes are not right for your -application, you can pass your own arguments to @code{interactive} as -a list. - -@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}, -for an example. @xref{Using Interactive, , Using @code{Interactive}, -elisp, The GNU Emacs Lisp Reference Manual}, for a more complete -explanation about this technique. - -@node Permanent Installation, let, Interactive Options, Writing Defuns -@comment node-name, next, previous, up -@section Install Code Permanently -@cindex Install code permanently -@cindex Permanent code installation -@cindex Code installation - -When you install a function definition by evaluating it, it will stay -installed until you quit Emacs. The next time you start a new session -of Emacs, the function will not be installed unless you evaluate the -function definition again. - -At some point, you may want to have code installed automatically -whenever you start a new session of Emacs. There are several ways of -doing this: - -@itemize @bullet -@item -If you have code that is just for yourself, you can put the code for the -function definition in your @file{.emacs} initialization file. When you -start Emacs, your @file{.emacs} file is automatically evaluated and all -the function definitions within it are installed. -@xref{Emacs Initialization, , Your @file{.emacs} File}. - -@item -Alternatively, you can put the function definitions that you want -installed in one or more files of their own and use the @code{load} -function to cause Emacs to evaluate and thereby install each of the -functions in the files. -@xref{Loading Files, , Loading Files}. - -@item -Thirdly, if you have code that your whole site will use, it is usual -to put it in a file called @file{site-init.el} that is loaded when -Emacs is built. This makes the code available to everyone who uses -your machine. (See the @file{INSTALL} file that is part of the Emacs -distribution.) -@end itemize - -Finally, if you have code that everyone who uses Emacs may want, you -can post it on a computer network or send a copy to the Free Software -Foundation. (When you do this, please license the code and its -documentation under a license that permits other people to run, copy, -study, modify, and redistribute the code and which protects you from -having your work taken from you.) If you send a copy of your code to -the Free Software Foundation, and properly protect yourself and -others, it may be included in the next release of Emacs. In large -part, this is how Emacs has grown over the past years, by donations. - -@node let, if, Permanent Installation, Writing Defuns -@comment node-name, next, previous, up -@section @code{let} -@findex let - -The @code{let} expression is a special form in Lisp that you will need -to use in most function definitions. - -@code{let} is used to attach or bind a symbol to a value in such a way -that the Lisp interpreter will not confuse the variable with a -variable of the same name that is not part of the function. - -To understand why the @code{let} special form is necessary, consider -the situation in which you own a home that you generally refer to as -`the house', as in the sentence, ``The house needs painting.'' If you -are visiting a friend and your host refers to `the house', he is -likely to be referring to @emph{his} house, not yours, that is, to a -different house. - -If your friend is referring to his house and you think he is referring -to your house, you may be in for some confusion. The same thing could -happen in Lisp if a variable that is used inside of one function has -the same name as a variable that is used inside of another function, -and the two are not intended to refer to the same value. The -@code{let} special form prevents this kind of confusion. - -@menu -* Prevent confusion:: -* Parts of let Expression:: -* Sample let Expression:: -* Uninitialized let Variables:: -@end menu - -@node Prevent confusion, Parts of let Expression, let, let -@ifnottex -@unnumberedsubsec @code{let} Prevents Confusion -@end ifnottex - -@cindex @samp{local variable} defined -@cindex @samp{variable, local}, defined -The @code{let} special form prevents confusion. @code{let} creates a -name for a @dfn{local variable} that overshadows any use of the same -name outside the @code{let} expression. This is like understanding -that whenever your host refers to `the house', he means his house, not -yours. (Symbols used in argument lists work the same way. -@xref{defun, , The @code{defun} Special Form}.) - -Local variables created by a @code{let} expression retain their value -@emph{only} within the @code{let} expression itself (and within -expressions called within the @code{let} expression); the local -variables have no effect outside the @code{let} expression. - -Another way to think about @code{let} is that it is like a @code{setq} -that is temporary and local. The values set by @code{let} are -automatically undone when the @code{let} is finished. The setting -only affects expressions that are inside the bounds of the @code{let} -expression. In computer science jargon, we would say ``the binding of -a symbol is visible only in functions called in the @code{let} form; -in Emacs Lisp, scoping is dynamic, not lexical.'' - -@code{let} can create more than one variable at once. Also, -@code{let} gives each variable it creates an initial value, either a -value specified by you, or @code{nil}. (In the jargon, this is called -`binding the variable to the value'.) After @code{let} has created -and bound the variables, it executes the code in the body of the -@code{let}, and returns the value of the last expression in the body, -as the value of the whole @code{let} expression. (`Execute' is a jargon -term that means to evaluate a list; it comes from the use of the word -meaning `to give practical effect to' (@cite{Oxford English -Dictionary}). Since you evaluate an expression to perform an action, -`execute' has evolved as a synonym to `evaluate'.) - -@node Parts of let Expression, Sample let Expression, Prevent confusion, let -@comment node-name, next, previous, up -@subsection The Parts of a @code{let} Expression -@cindex @code{let} expression, parts of -@cindex Parts of @code{let} expression - -@cindex @samp{varlist} defined -A @code{let} expression is a list of three parts. The first part is -the symbol @code{let}. The second part is a list, called a -@dfn{varlist}, each element of which is either a symbol by itself or a -two-element list, the first element of which is a symbol. The third -part of the @code{let} expression is the body of the @code{let}. The -body usually consists of one or more lists. - -@need 800 -A template for a @code{let} expression looks like this: - -@smallexample -(let @var{varlist} @var{body}@dots{}) -@end smallexample - -@noindent -The symbols in the varlist are the variables that are given initial -values by the @code{let} special form. Symbols by themselves are given -the initial value of @code{nil}; and each symbol that is the first -element of a two-element list is bound to the value that is returned -when the Lisp interpreter evaluates the second element. - -Thus, a varlist might look like this: @code{(thread (needles 3))}. In -this case, in a @code{let} expression, Emacs binds the symbol -@code{thread} to an initial value of @code{nil}, and binds the symbol -@code{needles} to an initial value of 3. - -When you write a @code{let} expression, what you do is put the -appropriate expressions in the slots of the @code{let} expression -template. - -If the varlist is composed of two-element lists, as is often the case, -the template for the @code{let} expression looks like this: - -@smallexample -@group -(let ((@var{variable} @var{value}) - (@var{variable} @var{value}) - @dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -@node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let -@comment node-name, next, previous, up -@subsection Sample @code{let} Expression -@cindex Sample @code{let} expression -@cindex @code{let} expression sample - -The following expression creates and gives initial values -to the two variables @code{zebra} and @code{tiger}. The body of the -@code{let} expression is a list which calls the @code{message} function. - -@smallexample -@group -(let ((zebra 'stripes) - (tiger 'fierce)) - (message "One kind of animal has %s and another is %s." - zebra tiger)) -@end group -@end smallexample - -Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}. - -The two variables are @code{zebra} and @code{tiger}. Each variable is -the first element of a two-element list and each value is the second -element of its two-element list. In the varlist, Emacs binds the -variable @code{zebra} to the value @code{stripes}@footnote{According -to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras -become impossibly dangerous as they grow older'' but the claim here is -that they do not become fierce like a tiger. (1997, W. W. Norton and -Co., ISBN 0-393-03894-2, page 171)}, and binds the -variable @code{tiger} to the value @code{fierce}. In this example, -both values are symbols preceded by a quote. The values could just as -well have been another list or a string. The body of the @code{let} -follows after the list holding the variables. In this example, the -body is a list that uses the @code{message} function to print a string -in the echo area. - -@need 1500 -You may evaluate the example in the usual fashion, by placing the -cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do -this, the following will appear in the echo area: - -@smallexample -"One kind of animal has stripes and another is fierce." -@end smallexample - -As we have seen before, the @code{message} function prints its first -argument, except for @samp{%s}. In this example, the value of the variable -@code{zebra} is printed at the location of the first @samp{%s} and the -value of the variable @code{tiger} is printed at the location of the -second @samp{%s}. - -@node Uninitialized let Variables, , Sample let Expression, let -@comment node-name, next, previous, up -@subsection Uninitialized Variables in a @code{let} Statement -@cindex Uninitialized @code{let} variables -@cindex @code{let} variables uninitialized - -If you do not bind the variables in a @code{let} statement to specific -initial values, they will automatically be bound to an initial value of -@code{nil}, as in the following expression: - -@smallexample -@group -(let ((birch 3) - pine - fir - (oak 'some)) - (message - "Here are %d variables with %s, %s, and %s value." - birch pine fir oak)) -@end group -@end smallexample - -@noindent -Here, the varlist is @code{((birch 3) pine fir (oak 'some))}. - -@need 1250 -If you evaluate this expression in the usual way, the following will -appear in your echo area: - -@smallexample -"Here are 3 variables with nil, nil, and some value." -@end smallexample - -@noindent -In this example, Emacs binds the symbol @code{birch} to the number 3, -binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds -the symbol @code{oak} to the value @code{some}. - -Note that in the first part of the @code{let}, the variables @code{pine} -and @code{fir} stand alone as atoms that are not surrounded by -parentheses; this is because they are being bound to @code{nil}, the -empty list. But @code{oak} is bound to @code{some} and so is a part of -the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the -number 3 and so is in a list with that number. (Since a number -evaluates to itself, the number does not need to be quoted. Also, the -number is printed in the message using a @samp{%d} rather than a -@samp{%s}.) The four variables as a group are put into a list to -delimit them from the body of the @code{let}. - -@node if, else, let, Writing Defuns -@comment node-name, next, previous, up -@section The @code{if} Special Form -@findex if -@cindex Conditional with @code{if} - -A third special form, in addition to @code{defun} and @code{let}, is the -conditional @code{if}. This form is used to instruct the computer to -make decisions. You can write function definitions without using -@code{if}, but it is used often enough, and is important enough, to be -included here. It is used, for example, in the code for the -function @code{beginning-of-buffer}. - -The basic idea behind an @code{if}, is that ``@emph{if} a test is true, -@emph{then} an expression is evaluated.'' If the test is not true, the -expression is not evaluated. For example, you might make a decision -such as, ``if it is warm and sunny, then go to the beach!'' - -@menu -* if in more detail:: -* type-of-animal in detail:: An example of an @code{if} expression. -@end menu - -@node if in more detail, type-of-animal in detail, if, if -@ifnottex -@unnumberedsubsec @code{if} in more detail -@end ifnottex - -@cindex @samp{if-part} defined -@cindex @samp{then-part} defined -An @code{if} expression written in Lisp does not use the word `then'; -the test and the action are the second and third elements of the list -whose first element is @code{if}. Nonetheless, the test part of an -@code{if} expression is often called the @dfn{if-part} and the second -argument is often called the @dfn{then-part}. - -Also, when an @code{if} expression is written, the true-or-false-test -is usually written on the same line as the symbol @code{if}, but the -action to carry out if the test is true, the ``then-part'', is written -on the second and subsequent lines. This makes the @code{if} -expression easier to read. - -@smallexample -@group -(if @var{true-or-false-test} - @var{action-to-carry-out-if-test-is-true}) -@end group -@end smallexample - -@noindent -The true-or-false-test will be an expression that -is evaluated by the Lisp interpreter. - -Here is an example that you can evaluate in the usual manner. The test -is whether the number 5 is greater than the number 4. Since it is, the -message @samp{5 is greater than 4!} will be printed. - -@smallexample -@group -(if (> 5 4) ; @r{if-part} - (message "5 is greater than 4!")) ; @r{then-part} -@end group -@end smallexample - -@noindent -(The function @code{>} tests whether its first argument is greater than -its second argument and returns true if it is.) -@findex > (greater than) - -Of course, in actual use, the test in an @code{if} expression will not -be fixed for all time as it is by the expression @code{(> 5 4)}. -Instead, at least one of the variables used in the test will be bound to -a value that is not known ahead of time. (If the value were known ahead -of time, we would not need to run the test!) - -For example, the value may be bound to an argument of a function -definition. In the following function definition, the character of the -animal is a value that is passed to the function. If the value bound to -@code{characteristic} is @code{fierce}, then the message, @samp{It's a -tiger!} will be printed; otherwise, @code{nil} will be returned. - -@smallexample -@group -(defun type-of-animal (characteristic) - "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger." - (if (equal characteristic 'fierce) - (message "It's a tiger!"))) -@end group -@end smallexample - -@need 1500 -@noindent -If you are reading this inside of GNU Emacs, you can evaluate the -function definition in the usual way to install it in Emacs, and then you -can evaluate the following two expressions to see the results: - -@smallexample -@group -(type-of-animal 'fierce) - -(type-of-animal 'zebra) - -@end group -@end smallexample - -@c Following sentences rewritten to prevent overfull hbox. -@noindent -When you evaluate @code{(type-of-animal 'fierce)}, you will see the -following message printed in the echo area: @code{"It's a tiger!"}; and -when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil} -printed in the echo area. - -@node type-of-animal in detail, , if in more detail, if -@comment node-name, next, previous, up -@subsection The @code{type-of-animal} Function in Detail - -Let's look at the @code{type-of-animal} function in detail. - -The function definition for @code{type-of-animal} was written by filling -the slots of two templates, one for a function definition as a whole, and -a second for an @code{if} expression. - -@need 1250 -The template for every function that is not interactive is: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - @var{body}@dots{}) -@end group -@end smallexample - -@need 800 -The parts of the function that match this template look like this: - -@smallexample -@group -(defun type-of-animal (characteristic) - "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger." - @var{body: the} @code{if} @var{expression}) -@end group -@end smallexample - -The name of function is @code{type-of-animal}; it is passed the value -of one argument. The argument list is followed by a multi-line -documentation string. The documentation string is included in the -example because it is a good habit to write documentation string for -every function definition. The body of the function definition -consists of the @code{if} expression. - -@need 800 -The template for an @code{if} expression looks like this: - -@smallexample -@group -(if @var{true-or-false-test} - @var{action-to-carry-out-if-the-test-returns-true}) -@end group -@end smallexample - -@need 1250 -In the @code{type-of-animal} function, the code for the @code{if} -looks like this: - -@smallexample -@group -(if (equal characteristic 'fierce) - (message "It's a tiger!"))) -@end group -@end smallexample - -@need 800 -Here, the true-or-false-test is the expression: - -@smallexample -(equal characteristic 'fierce) -@end smallexample - -@noindent -In Lisp, @code{equal} is a function that determines whether its first -argument is equal to its second argument. The second argument is the -quoted symbol @code{'fierce} and the first argument is the value of the -symbol @code{characteristic}---in other words, the argument passed to -this function. - -In the first exercise of @code{type-of-animal}, the argument -@code{fierce} is passed to @code{type-of-animal}. Since @code{fierce} -is equal to @code{fierce}, the expression, @code{(equal characteristic -'fierce)}, returns a value of true. When this happens, the @code{if} -evaluates the second argument or then-part of the @code{if}: -@code{(message "It's tiger!")}. - -On the other hand, in the second exercise of @code{type-of-animal}, the -argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra} -is not equal to @code{fierce}, so the then-part is not evaluated and -@code{nil} is returned by the @code{if} expression. - -@node else, Truth & Falsehood, if, Writing Defuns -@comment node-name, next, previous, up -@section If--then--else Expressions -@cindex Else - -An @code{if} expression may have an optional third argument, called -the @dfn{else-part}, for the case when the true-or-false-test returns -false. When this happens, the second argument or then-part of the -overall @code{if} expression is @emph{not} evaluated, but the third or -else-part @emph{is} evaluated. You might think of this as the cloudy -day alternative for the decision ``if it is warm and sunny, then go to -the beach, else read a book!''. - -The word ``else'' is not written in the Lisp code; the else-part of an -@code{if} expression comes after the then-part. In the written Lisp, the -else-part is usually written to start on a line of its own and is -indented less than the then-part: - -@smallexample -@group -(if @var{true-or-false-test} - @var{action-to-carry-out-if-the-test-returns-true} - @var{action-to-carry-out-if-the-test-returns-false}) -@end group -@end smallexample - -For example, the following @code{if} expression prints the message @samp{4 -is not greater than 5!} when you evaluate it in the usual way: - -@smallexample -@group -(if (> 4 5) ; @r{if-part} - (message "4 falsely greater than 5!") ; @r{then-part} - (message "4 is not greater than 5!")) ; @r{else-part} -@end group -@end smallexample - -@noindent -Note that the different levels of indentation make it easy to -distinguish the then-part from the else-part. (GNU Emacs has several -commands that automatically indent @code{if} expressions correctly. -@xref{Typing Lists, , GNU Emacs Helps You Type Lists}.) - -We can extend the @code{type-of-animal} function to include an -else-part by simply incorporating an additional part to the @code{if} -expression. - -@need 1500 -You can see the consequences of doing this if you evaluate the following -version of the @code{type-of-animal} function definition to install it -and then evaluate the two subsequent expressions to pass different -arguments to the function. - -@smallexample -@group -(defun type-of-animal (characteristic) ; @r{Second version.} - "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger; -else say it's not fierce." - (if (equal characteristic 'fierce) - (message "It's a tiger!") - (message "It's not fierce!"))) -@end group -@end smallexample -@sp 1 - -@smallexample -@group -(type-of-animal 'fierce) - -(type-of-animal 'zebra) - -@end group -@end smallexample - -@c Following sentence rewritten to prevent overfull hbox. -@noindent -When you evaluate @code{(type-of-animal 'fierce)}, you will see the -following message printed in the echo area: @code{"It's a tiger!"}; but -when you evaluate @code{(type-of-animal 'zebra)}, you will see -@code{"It's not fierce!"}. - -(Of course, if the @var{characteristic} were @code{ferocious}, the -message @code{"It's not fierce!"} would be printed; and it would be -misleading! When you write code, you need to take into account the -possibility that some such argument will be tested by the @code{if} -and write your program accordingly.) - -@node Truth & Falsehood, save-excursion, else, Writing Defuns -@comment node-name, next, previous, up -@section Truth and Falsehood in Emacs Lisp -@cindex Truth and falsehood in Emacs Lisp -@cindex Falsehood and truth in Emacs Lisp -@findex nil - -There is an important aspect to the truth test in an @code{if} -expression. So far, we have spoken of `true' and `false' as values of -predicates as if they were new kinds of Emacs Lisp objects. In fact, -`false' is just our old friend @code{nil}. Anything else---anything -at all---is `true'. - -The expression that tests for truth is interpreted as @dfn{true} -if the result of evaluating it is a value that is not @code{nil}. In -other words, the result of the test is considered true if the value -returned is a number such as 47, a string such as @code{"hello"}, or a -symbol (other than @code{nil}) such as @code{flowers}, or a list (so -long as it is not empty), or even a buffer! - -@menu -* nil explained:: @code{nil} has two meanings. -@end menu - -@node nil explained, , Truth & Falsehood, Truth & Falsehood -@ifnottex -@unnumberedsubsec An explanation of @code{nil} -@end ifnottex - -Before illustrating a test for truth, we need an explanation of @code{nil}. - -In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the -empty list. Second, it means false and is the value returned when a -true-or-false-test tests false. @code{nil} can be written as an empty -list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is -concerned, @code{()} and @code{nil} are the same. Humans, however, tend -to use @code{nil} for false and @code{()} for the empty list. - -In Emacs Lisp, any value that is not @code{nil}---is not the empty -list---is considered true. This means that if an evaluation returns -something that is not an empty list, an @code{if} expression will test -true. For example, if a number is put in the slot for the test, it -will be evaluated and will return itself, since that is what numbers -do when evaluated. In this conditional, the @code{if} expression will -test true. The expression tests false only when @code{nil}, an empty -list, is returned by evaluating the expression. - -You can see this by evaluating the two expressions in the following examples. - -In the first example, the number 4 is evaluated as the test in the -@code{if} expression and returns itself; consequently, the then-part -of the expression is evaluated and returned: @samp{true} appears in -the echo area. In the second example, the @code{nil} indicates false; -consequently, the else-part of the expression is evaluated and -returned: @samp{false} appears in the echo area. - -@smallexample -@group -(if 4 - 'true - 'false) -@end group - -@group -(if nil - 'true - 'false) -@end group -@end smallexample - -@need 1250 -Incidentally, if some other useful value is not available for a test that -returns true, then the Lisp interpreter will return the symbol @code{t} -for true. For example, the expression @code{(> 5 4)} returns @code{t} -when evaluated, as you can see by evaluating it in the usual way: - -@smallexample -(> 5 4) -@end smallexample - -@need 1250 -@noindent -On the other hand, this function returns @code{nil} if the test is false. - -@smallexample -(> 4 5) -@end smallexample - -@node save-excursion, Review, Truth & Falsehood, Writing Defuns -@comment node-name, next, previous, up -@section @code{save-excursion} -@findex save-excursion -@cindex Region, what it is -@cindex Preserving point, mark, and buffer -@cindex Point, mark, buffer preservation -@findex point -@findex mark - -The @code{save-excursion} function is the fourth and final special form -that we will discuss in this chapter. - -In Emacs Lisp programs used for editing, the @code{save-excursion} -function is very common. It saves the location of point and mark, -executes the body of the function, and then restores point and mark to -their previous positions if their locations were changed. Its primary -purpose is to keep the user from being surprised and disturbed by -unexpected movement of point or mark. - -@menu -* Point and mark:: A review of various locations. -* Template for save-excursion:: -@end menu - -@node Point and mark, Template for save-excursion, save-excursion, save-excursion -@ifnottex -@unnumberedsubsec Point and Mark -@end ifnottex - -Before discussing @code{save-excursion}, however, it may be useful -first to review what point and mark are in GNU Emacs. @dfn{Point} is -the current location of the cursor. Wherever the cursor -is, that is point. More precisely, on terminals where the cursor -appears to be on top of a character, point is immediately before the -character. In Emacs Lisp, point is an integer. The first character in -a buffer is number one, the second is number two, and so on. The -function @code{point} returns the current position of the cursor as a -number. Each buffer has its own value for point. - -The @dfn{mark} is another position in the buffer; its value can be set -with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If -a mark has been set, you can use the command @kbd{C-x C-x} -(@code{exchange-point-and-mark}) to cause the cursor to jump to the mark -and set the mark to be the previous position of point. In addition, if -you set another mark, the position of the previous mark is saved in the -mark ring. Many mark positions can be saved this way. You can jump the -cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more -times. - -The part of the buffer between point and mark is called @dfn{the -region}. Numerous commands work on the region, including -@code{center-region}, @code{count-lines-region}, @code{kill-region}, and -@code{print-region}. - -The @code{save-excursion} special form saves the locations of point and -mark and restores those positions after the code within the body of the -special form is evaluated by the Lisp interpreter. Thus, if point were -in the beginning of a piece of text and some code moved point to the end -of the buffer, the @code{save-excursion} would put point back to where -it was before, after the expressions in the body of the function were -evaluated. - -In Emacs, a function frequently moves point as part of its internal -workings even though a user would not expect this. For example, -@code{count-lines-region} moves point. To prevent the user from being -bothered by jumps that are both unexpected and (from the user's point of -view) unnecessary, @code{save-excursion} is often used to keep point and -mark in the location expected by the user. The use of -@code{save-excursion} is good housekeeping. - -To make sure the house stays clean, @code{save-excursion} restores the -values of point and mark even if something goes wrong in the code inside -of it (or, to be more precise and to use the proper jargon, ``in case of -abnormal exit''). This feature is very helpful. - -In addition to recording the values of point and mark, -@code{save-excursion} keeps track of the current buffer, and restores -it, too. This means you can write code that will change the buffer and -have @code{save-excursion} switch you back to the original buffer. -This is how @code{save-excursion} is used in @code{append-to-buffer}. -(@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) - -@node Template for save-excursion, , Point and mark, save-excursion -@comment node-name, next, previous, up -@subsection Template for a @code{save-excursion} Expression - -@need 800 -The template for code using @code{save-excursion} is simple: - -@smallexample -@group -(save-excursion - @var{body}@dots{}) -@end group -@end smallexample - -@noindent -The body of the function is one or more expressions that will be -evaluated in sequence by the Lisp interpreter. If there is more than -one expression in the body, the value of the last one will be returned -as the value of the @code{save-excursion} function. The other -expressions in the body are evaluated only for their side effects; and -@code{save-excursion} itself is used only for its side effect (which -is restoring the positions of point and mark). - -@need 1250 -In more detail, the template for a @code{save-excursion} expression -looks like this: - -@smallexample -@group -(save-excursion - @var{first-expression-in-body} - @var{second-expression-in-body} - @var{third-expression-in-body} - @dots{} - @var{last-expression-in-body}) -@end group -@end smallexample - -@noindent -An expression, of course, may be a symbol on its own or a list. - -In Emacs Lisp code, a @code{save-excursion} expression often occurs -within the body of a @code{let} expression. It looks like this: - -@smallexample -@group -(let @var{varlist} - (save-excursion - @var{body}@dots{})) -@end group -@end smallexample - -@node Review, defun Exercises, save-excursion, Writing Defuns -@comment node-name, next, previous, up -@section Review - -In the last few chapters we have introduced a fair number of functions -and special forms. Here they are described in brief, along with a few -similar functions that have not been mentioned yet. - -@table @code -@item eval-last-sexp -Evaluate the last symbolic expression before the current location of -point. The value is printed in the echo area unless the function is -invoked with an argument; in that case, the output is printed in the -current buffer. This command is normally bound to @kbd{C-x C-e}. - -@item defun -Define function. This special form has up to five parts: the name, -a template for the arguments that will be passed to the function, -documentation, an optional interactive declaration, and the body of the -definition. - -@need 1250 -For example, in an early version of Emacs, the function definition was -as follows. (It is slightly more complex now that it seeks the first -non-whitespace character rather than the first visible character.) - -@smallexample -@group -(defun back-to-indentation () - "Move point to first visible character on line." - (interactive) - (beginning-of-line 1) - (skip-chars-forward " \t")) -@end group -@end smallexample - -@ignore -In GNU Emacs 22, - -(defun backward-to-indentation (&optional arg) - "Move backward ARG lines and position at first nonblank character." - (interactive "p") - (forward-line (- (or arg 1))) - (skip-chars-forward " \t")) - -(defun back-to-indentation () - "Move point to the first non-whitespace character on this line." - (interactive) - (beginning-of-line 1) - (skip-syntax-forward " " (line-end-position)) - ;; Move back over chars that have whitespace syntax but have the p flag. - (backward-prefix-chars)) -@end ignore - -@item interactive -Declare to the interpreter that the function can be used -interactively. This special form may be followed by a string with one -or more parts that pass the information to the arguments of the -function, in sequence. These parts may also tell the interpreter to -prompt for information. Parts of the string are separated by -newlines, @samp{\n}. - -@need 1000 -Common code characters are: - -@table @code -@item b -The name of an existing buffer. - -@item f -The name of an existing file. - -@item p -The numeric prefix argument. (Note that this `p' is lower case.) - -@item r -Point and the mark, as two numeric arguments, smallest first. This -is the only code letter that specifies two successive arguments -rather than one. -@end table - -@xref{Interactive Codes, , Code Characters for @samp{interactive}, -elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of -code characters. - -@item let -Declare that a list of variables is for use within the body of the -@code{let} and give them an initial value, either @code{nil} or a -specified value; then evaluate the rest of the expressions in the body -of the @code{let} and return the value of the last one. Inside the -body of the @code{let}, the Lisp interpreter does not see the values of -the variables of the same names that are bound outside of the -@code{let}. - -@need 1250 -For example, - -@smallexample -@group -(let ((foo (buffer-name)) - (bar (buffer-size))) - (message - "This buffer is %s and has %d characters." - foo bar)) -@end group -@end smallexample - -@item save-excursion -Record the values of point and mark and the current buffer before -evaluating the body of this special form. Restore the values of point -and mark and buffer afterward. - -@need 1250 -For example, - -@smallexample -@group -(message "We are %d characters into this buffer." - (- (point) - (save-excursion - (goto-char (point-min)) (point)))) -@end group -@end smallexample - -@item if -Evaluate the first argument to the function; if it is true, evaluate -the second argument; else evaluate the third argument, if there is one. - -The @code{if} special form is called a @dfn{conditional}. There are -other conditionals in Emacs Lisp, but @code{if} is perhaps the most -commonly used. - -@need 1250 -For example, - -@smallexample -@group -(if (= 22 emacs-major-version) - (message "This is version 22 Emacs") - (message "This is not version 22 Emacs")) -@end group -@end smallexample - -@need 1250 -@item < -@itemx > -@itemx <= -@itemx >= -The @code{<} function tests whether its first argument is smaller than -its second argument. A corresponding function, @code{>}, tests whether -the first argument is greater than the second. Likewise, @code{<=} -tests whether the first argument is less than or equal to the second and -@code{>=} tests whether the first argument is greater than or equal to -the second. In all cases, both arguments must be numbers or markers -(markers indicate positions in buffers). - -@need 800 -@item = -The @code{=} function tests whether two arguments, both numbers or -markers, are equal. - -@need 1250 -@item equal -@itemx eq -Test whether two objects are the same. @code{equal} uses one meaning -of the word `same' and @code{eq} uses another: @code{equal} returns -true if the two objects have a similar structure and contents, such as -two copies of the same book. On the other hand, @code{eq}, returns -true if both arguments are actually the same object. -@findex equal -@findex eq - -@need 1250 -@item string< -@itemx string-lessp -@itemx string= -@itemx string-equal -The @code{string-lessp} function tests whether its first argument is -smaller than the second argument. A shorter, alternative name for the -same function (a @code{defalias}) is @code{string<}. - -The arguments to @code{string-lessp} must be strings or symbols; the -ordering is lexicographic, so case is significant. The print names of -symbols are used instead of the symbols themselves. - -@cindex @samp{empty string} defined -An empty string, @samp{""}, a string with no characters in it, is -smaller than any string of characters. - -@code{string-equal} provides the corresponding test for equality. Its -shorter, alternative name is @code{string=}. There are no string test -functions that correspond to @var{>}, @code{>=}, or @code{<=}. - -@item message -Print a message in the echo area. The first argument is a string that -can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of -arguments that follow the string. The argument used by @samp{%s} must -be a string or a symbol; the argument used by @samp{%d} must be a -number. The argument used by @samp{%c} must be an @sc{ascii} code -number; it will be printed as the character with that @sc{ascii} code. -(Various other %-sequences have not been mentioned.) - -@item setq -@itemx set -The @code{setq} function sets the value of its first argument to the -value of the second argument. The first argument is automatically -quoted by @code{setq}. It does the same for succeeding pairs of -arguments. Another function, @code{set}, takes only two arguments and -evaluates both of them before setting the value returned by its first -argument to the value returned by its second argument. - -@item buffer-name -Without an argument, return the name of the buffer, as a string. - -@itemx buffer-file-name -Without an argument, return the name of the file the buffer is -visiting. - -@item current-buffer -Return the buffer in which Emacs is active; it may not be -the buffer that is visible on the screen. - -@item other-buffer -Return the most recently selected buffer (other than the buffer passed -to @code{other-buffer} as an argument and other than the current -buffer). - -@item switch-to-buffer -Select a buffer for Emacs to be active in and display it in the current -window so users can look at it. Usually bound to @kbd{C-x b}. - -@item set-buffer -Switch Emacs's attention to a buffer on which programs will run. Don't -alter what the window is showing. - -@item buffer-size -Return the number of characters in the current buffer. - -@item point -Return the value of the current position of the cursor, as an -integer counting the number of characters from the beginning of the -buffer. - -@item point-min -Return the minimum permissible value of point in -the current buffer. This is 1, unless narrowing is in effect. - -@item point-max -Return the value of the maximum permissible value of point in the -current buffer. This is the end of the buffer, unless narrowing is in -effect. -@end table - -@need 1500 -@node defun Exercises, , Review, Writing Defuns -@section Exercises - -@itemize @bullet -@item -Write a non-interactive function that doubles the value of its -argument, a number. Make that function interactive. - -@item -Write a function that tests whether the current value of -@code{fill-column} is greater than the argument passed to the function, -and if so, prints an appropriate message. -@end itemize - -@node Buffer Walk Through, More Complex, Writing Defuns, Top -@comment node-name, next, previous, up -@chapter A Few Buffer--Related Functions - -In this chapter we study in detail several of the functions used in GNU -Emacs. This is called a ``walk-through''. These functions are used as -examples of Lisp code, but are not imaginary examples; with the -exception of the first, simplified function definition, these functions -show the actual code used in GNU Emacs. You can learn a great deal from -these definitions. The functions described here are all related to -buffers. Later, we will study other functions. - -@menu -* Finding More:: How to find more information. -* simplified-beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. -* append-to-buffer:: Uses @code{save-excursion} and - @code{insert-buffer-substring}. -* Buffer Related Review:: Review. -* Buffer Exercises:: -@end menu - -@node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through -@section Finding More Information - -@findex describe-function, @r{introduced} -@cindex Find function documentation -In this walk-through, I will describe each new function as we come to -it, sometimes in detail and sometimes briefly. If you are interested, -you can get the full documentation of any Emacs Lisp function at any -time by typing @kbd{C-h f} and then the name of the function (and then -@key{RET}). Similarly, you can get the full documentation for a -variable by typing @kbd{C-h v} and then the name of the variable (and -then @key{RET}). - -@cindex Find source of function -@c In version 22, tells location both of C and of Emacs Lisp -Also, @code{describe-function} will tell you the location of the -function definition. - -Put point into the name of the file that contains the function and -press the @key{RET} key. In this case, @key{RET} means -@code{push-button} rather than `return' or `enter'. Emacs will take -you directly to the function definition. - -@ignore -Not In version 22 - -If you move point over the file name and press -the @key{RET} key, which in this case means @code{help-follow} rather -than `return' or `enter', Emacs will take you directly to the function -definition. -@end ignore - -More generally, if you want to see a function in its original source -file, you can use the @code{find-tag} function to jump to it. -@code{find-tag} works with a wide variety of languages, not just -Lisp, and C, and it works with non-programming text as well. For -example, @code{find-tag} will jump to the various nodes in the -Texinfo source file of this document. -The @code{find-tag} function depends on `tags tables' that record -the locations of the functions, variables, and other items to which -@code{find-tag} jumps. - -To use the @code{find-tag} command, type @kbd{M-.} (i.e., press the -period key while holding down the @key{META} key, or else type the -@key{ESC} key and then type the period key), and then, at the prompt, -type in the name of the function whose source code you want to see, -such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will -switch buffers and display the source code for the function on your -screen. To switch back to your current buffer, type @kbd{C-x b -@key{RET}}. (On some keyboards, the @key{META} key is labeled -@key{ALT}.) - -@c !!! 22.1.1 tags table location in this paragraph -@cindex TAGS table, specifying -@findex find-tag -Depending on how the initial default values of your copy of Emacs are -set, you may also need to specify the location of your `tags table', -which is a file called @file{TAGS}. For example, if you are -interested in Emacs sources, the tags table you will most likely want, -if it has already been created for you, will be in a subdirectory of -the @file{/usr/local/share/emacs/} directory; thus you would use the -@code{M-x visit-tags-table} command and specify a pathname such as -@file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table -has not already been created, you will have to create it yourself. It -will be in a file such as @file{/usr/local/src/emacs/src/TAGS}. - -@need 1250 -To create a @file{TAGS} file in a specific directory, switch to that -directory in Emacs using @kbd{M-x cd} command, or list the directory -with @kbd{C-x d} (@code{dired}). Then run the compile command, with -@w{@code{etags *.el}} as the command to execute: - -@smallexample -M-x compile RET etags *.el RET -@end smallexample - -For more information, see @ref{etags, , Create Your Own @file{TAGS} File}. - -After you become more familiar with Emacs Lisp, you will find that you will -frequently use @code{find-tag} to navigate your way around source code; -and you will create your own @file{TAGS} tables. - -@cindex Library, as term for `file' -Incidentally, the files that contain Lisp code are conventionally -called @dfn{libraries}. The metaphor is derived from that of a -specialized library, such as a law library or an engineering library, -rather than a general library. Each library, or file, contains -functions that relate to a particular topic or activity, such as -@file{abbrev.el} for handling abbreviations and other typing -shortcuts, and @file{help.el} for on-line help. (Sometimes several -libraries provide code for a single activity, as the various -@file{rmail@dots{}} files provide code for reading electronic mail.) -In @cite{The GNU Emacs Manual}, you will see sentences such as ``The -@kbd{C-h p} command lets you search the standard Emacs Lisp libraries -by topic keywords.'' - -@node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through -@comment node-name, next, previous, up -@section A Simplified @code{beginning-of-buffer} Definition -@findex simplified-beginning-of-buffer - -The @code{beginning-of-buffer} command is a good function to start with -since you are likely to be familiar with it and it is easy to -understand. Used as an interactive command, @code{beginning-of-buffer} -moves the cursor to the beginning of the buffer, leaving the mark at the -previous position. It is generally bound to @kbd{M-<}. - -In this section, we will discuss a shortened version of the function -that shows how it is most frequently used. This shortened function -works as written, but it does not contain the code for a complex option. -In another section, we will describe the entire function. -(@xref{beginning-of-buffer, , Complete Definition of -@code{beginning-of-buffer}}.) - -Before looking at the code, let's consider what the function -definition has to contain: it must include an expression that makes -the function interactive so it can be called by typing @kbd{M-x -beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it -must include code to leave a mark at the original position in the -buffer; and it must include code to move the cursor to the beginning -of the buffer. - -@need 1250 -Here is the complete text of the shortened version of the function: - -@smallexample -@group -(defun simplified-beginning-of-buffer () - "Move point to the beginning of the buffer; -leave mark at previous position." - (interactive) - (push-mark) - (goto-char (point-min))) -@end group -@end smallexample - -Like all function definitions, this definition has five parts following -the special form @code{defun}: - -@enumerate -@item -The name: in this example, @code{simplified-beginning-of-buffer}. - -@item -A list of the arguments: in this example, an empty list, @code{()}, - -@item -The documentation string. - -@item -The interactive expression. - -@item -The body. -@end enumerate - -@noindent -In this function definition, the argument list is empty; this means that -this function does not require any arguments. (When we look at the -definition for the complete function, we will see that it may be passed -an optional argument.) - -The interactive expression tells Emacs that the function is intended to -be used interactively. In this example, @code{interactive} does not have -an argument because @code{simplified-beginning-of-buffer} does not -require one. - -@need 800 -The body of the function consists of the two lines: - -@smallexample -@group -(push-mark) -(goto-char (point-min)) -@end group -@end smallexample - -The first of these lines is the expression, @code{(push-mark)}. When -this expression is evaluated by the Lisp interpreter, it sets a mark at -the current position of the cursor, wherever that may be. The position -of this mark is saved in the mark ring. - -The next line is @code{(goto-char (point-min))}. This expression -jumps the cursor to the minimum point in the buffer, that is, to the -beginning of the buffer (or to the beginning of the accessible portion -of the buffer if it is narrowed. @xref{Narrowing & Widening, , -Narrowing and Widening}.) - -The @code{push-mark} command sets a mark at the place where the cursor -was located before it was moved to the beginning of the buffer by the -@code{(goto-char (point-min))} expression. Consequently, you can, if -you wish, go back to where you were originally by typing @kbd{C-x C-x}. - -That is all there is to the function definition! - -@findex describe-function -When you are reading code such as this and come upon an unfamiliar -function, such as @code{goto-char}, you can find out what it does by -using the @code{describe-function} command. To use this command, type -@kbd{C-h f} and then type in the name of the function and press -@key{RET}. The @code{describe-function} command will print the -function's documentation string in a @file{*Help*} window. For -example, the documentation for @code{goto-char} is: - -@smallexample -@group -Set point to POSITION, a number or marker. -Beginning of buffer is position (point-min), end is (point-max). -@end group -@end smallexample - -@noindent -The function's one argument is the desired position. - -@noindent -(The prompt for @code{describe-function} will offer you the symbol -under or preceding the cursor, so you can save typing by positioning -the cursor right over or after the function and then typing @kbd{C-h f -@key{RET}}.) - -The @code{end-of-buffer} function definition is written in the same way as -the @code{beginning-of-buffer} definition except that the body of the -function contains the expression @code{(goto-char (point-max))} in place -of @code{(goto-char (point-min))}. - -@node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through -@comment node-name, next, previous, up -@section The Definition of @code{mark-whole-buffer} -@findex mark-whole-buffer - -The @code{mark-whole-buffer} function is no harder to understand than the -@code{simplified-beginning-of-buffer} function. In this case, however, -we will look at the complete function, not a shortened version. - -The @code{mark-whole-buffer} function is not as commonly used as the -@code{beginning-of-buffer} function, but is useful nonetheless: it -marks a whole buffer as a region by putting point at the beginning and -a mark at the end of the buffer. It is generally bound to @kbd{C-x -h}. - -@menu -* mark-whole-buffer overview:: -* Body of mark-whole-buffer:: Only three lines of code. -@end menu - -@node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer -@ifnottex -@unnumberedsubsec An overview of @code{mark-whole-buffer} -@end ifnottex - -@need 1250 -In GNU Emacs 22, the code for the complete function looks like this: - -@smallexample -@group -(defun mark-whole-buffer () - "Put point at beginning and mark at end of buffer. -You probably should not use this function in Lisp programs; -it is usually a mistake for a Lisp function to use any subroutine -that uses or sets the mark." - (interactive) - (push-mark (point)) - (push-mark (point-max) nil t) - (goto-char (point-min))) -@end group -@end smallexample - -@need 1250 -Like all other functions, the @code{mark-whole-buffer} function fits -into the template for a function definition. The template looks like -this: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (@var{interactive-expression}@dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -Here is how the function works: the name of the function is -@code{mark-whole-buffer}; it is followed by an empty argument list, -@samp{()}, which means that the function does not require arguments. -The documentation comes next. - -The next line is an @code{(interactive)} expression that tells Emacs -that the function will be used interactively. These details are similar -to the @code{simplified-beginning-of-buffer} function described in the -previous section. - -@need 1250 -@node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer -@comment node-name, next, previous, up -@subsection Body of @code{mark-whole-buffer} - -The body of the @code{mark-whole-buffer} function consists of three -lines of code: - -@c GNU Emacs 22 -@smallexample -@group -(push-mark (point)) -(push-mark (point-max) nil t) -(goto-char (point-min)) -@end group -@end smallexample - -The first of these lines is the expression, @code{(push-mark (point))}. - -This line does exactly the same job as the first line of the body of -the @code{simplified-beginning-of-buffer} function, which is written -@code{(push-mark)}. In both cases, the Lisp interpreter sets a mark -at the current position of the cursor. - -I don't know why the expression in @code{mark-whole-buffer} is written -@code{(push-mark (point))} and the expression in -@code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps -whoever wrote the code did not know that the arguments for -@code{push-mark} are optional and that if @code{push-mark} is not -passed an argument, the function automatically sets mark at the -location of point by default. Or perhaps the expression was written -so as to parallel the structure of the next line. In any case, the -line causes Emacs to determine the position of point and set a mark -there. - -In earlier versions of GNU Emacs, the next line of -@code{mark-whole-buffer} was @code{(push-mark (point-max))}. This -expression sets a mark at the point in the buffer that has the highest -number. This will be the end of the buffer (or, if the buffer is -narrowed, the end of the accessible portion of the buffer. -@xref{Narrowing & Widening, , Narrowing and Widening}, for more about -narrowing.) After this mark has been set, the previous mark, the one -set at point, is no longer set, but Emacs remembers its position, just -as all other recent marks are always remembered. This means that you -can, if you wish, go back to that position by typing @kbd{C-u -C-@key{SPC}} twice. - -@need 1250 -In GNU Emacs 22, the @code{(point-max)} is slightly more complicated. -The line reads - -@smallexample -(push-mark (point-max) nil t) -@end smallexample - -@noindent -The expression works nearly the same as before. It sets a mark at the -highest numbered place in the buffer that it can. However, in this -version, @code{push-mark} has two additional arguments. The second -argument to @code{push-mark} is @code{nil}. This tells the function -it @emph{should} display a message that says `Mark set' when it pushes -the mark. The third argument is @code{t}. This tells -@code{push-mark} to activate the mark when Transient Mark mode is -turned on. Transient Mark mode highlights the currently active -region. It is often turned off. - -Finally, the last line of the function is @code{(goto-char -(point-min)))}. This is written exactly the same way as it is written -in @code{beginning-of-buffer}. The expression moves the cursor to -the minimum point in the buffer, that is, to the beginning of the buffer -(or to the beginning of the accessible portion of the buffer). As a -result of this, point is placed at the beginning of the buffer and mark -is set at the end of the buffer. The whole buffer is, therefore, the -region. - -@node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through -@comment node-name, next, previous, up -@section The Definition of @code{append-to-buffer} -@findex append-to-buffer - -The @code{append-to-buffer} command is more complex than the -@code{mark-whole-buffer} command. What it does is copy the region -(that is, the part of the buffer between point and mark) from the -current buffer to a specified buffer. - -@menu -* append-to-buffer overview:: -* append interactive:: A two part interactive expression. -* append-to-buffer body:: Incorporates a @code{let} expression. -* append save-excursion:: How the @code{save-excursion} works. -@end menu - -@node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer -@ifnottex -@unnumberedsubsec An Overview of @code{append-to-buffer} -@end ifnottex - -@findex insert-buffer-substring -The @code{append-to-buffer} command uses the -@code{insert-buffer-substring} function to copy the region. -@code{insert-buffer-substring} is described by its name: it takes a -string of characters from part of a buffer, a ``substring'', and -inserts them into another buffer. - -Most of @code{append-to-buffer} is -concerned with setting up the conditions for -@code{insert-buffer-substring} to work: the code must specify both the -buffer to which the text will go, the window it comes from and goes -to, and the region that will be copied. - -@need 1250 -Here is the complete text of the function: - -@smallexample -@group -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. -@end group - -@group -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer - (current-buffer) t)) - (region-beginning) (region-end))) -@end group -@group - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end group -@end smallexample - -The function can be understood by looking at it as a series of -filled-in templates. - -The outermost template is for the function definition. In this -function, it looks like this (with several slots filled in): - -@smallexample -@group -(defun append-to-buffer (buffer start end) - "@var{documentation}@dots{}" - (interactive @dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -The first line of the function includes its name and three arguments. -The arguments are the @code{buffer} to which the text will be copied, and -the @code{start} and @code{end} of the region in the current buffer that -will be copied. - -The next part of the function is the documentation, which is clear and -complete. As is conventional, the three arguments are written in -upper case so you will notice them easily. Even better, they are -described in the same order as in the argument list. - -Note that the documentation distinguishes between a buffer and its -name. (The function can handle either.) - -@node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer -@comment node-name, next, previous, up -@subsection The @code{append-to-buffer} Interactive Expression - -Since the @code{append-to-buffer} function will be used interactively, -the function must have an @code{interactive} expression. (For a -review of @code{interactive}, see @ref{Interactive, , Making a -Function Interactive}.) The expression reads as follows: - -@smallexample -@group -(interactive - (list (read-buffer - "Append to buffer: " - (other-buffer (current-buffer) t)) - (region-beginning) - (region-end))) -@end group -@end smallexample - -@noindent -This expression is not one with letters standing for parts, as -described earlier. Instead, it starts a list with these parts: - -The first part of the list is an expression to read the name of a -buffer and return it as a string. That is @code{read-buffer}. The -function requires a prompt as its first argument, @samp{"Append to -buffer: "}. Its second argument tells the command what value to -provide if you don't specify anything. - -In this case that second argument is an expression containing the -function @code{other-buffer}, an exception, and a @samp{t}, standing -for true. - -The first argument to @code{other-buffer}, the exception, is yet -another function, @code{current-buffer}. That is not going to be -returned. The second argument is the symbol for true, @code{t}. that -tells @code{other-buffer} that it may show visible buffers (except in -this case, it will not show the current buffer, which makes sense). - -@need 1250 -The expression looks like this: - -@smallexample -(other-buffer (current-buffer) t) -@end smallexample - -The second and third arguments to the @code{list} expression are -@code{(region-beginning)} and @code{(region-end)}. These two -functions specify the beginning and end of the text to be appended. - -@need 1250 -Originally, the command used the letters @samp{B} and @samp{r}. -The whole @code{interactive} expression looked like this: - -@smallexample -(interactive "BAppend to buffer:@: \nr") -@end smallexample - -@noindent -But when that was done, the default value of the buffer switched to -was invisible. That was not wanted. - -(The prompt was separated from the second argument with a newline, -@samp{\n}. It was followed by an @samp{r} that told Emacs to bind the -two arguments that follow the symbol @code{buffer} in the function's -argument list (that is, @code{start} and @code{end}) to the values of -point and mark. That argument worked fine.) - -@node append-to-buffer body, append save-excursion, append interactive, append-to-buffer -@comment node-name, next, previous, up -@subsection The Body of @code{append-to-buffer} - -@ignore -in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el - -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. - -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) - (region-beginning) (region-end))) - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - -The body of the @code{append-to-buffer} function begins with @code{let}. - -As we have seen before (@pxref{let, , @code{let}}), the purpose of a -@code{let} expression is to create and give initial values to one or -more variables that will only be used within the body of the -@code{let}. This means that such a variable will not be confused with -any variable of the same name outside the @code{let} expression. - -We can see how the @code{let} expression fits into the function as a -whole by showing a template for @code{append-to-buffer} with the -@code{let} expression in outline: - -@smallexample -@group -(defun append-to-buffer (buffer start end) - "@var{documentation}@dots{}" - (interactive @dots{}) - (let ((@var{variable} @var{value})) - @var{body}@dots{}) -@end group -@end smallexample - -The @code{let} expression has three elements: - -@enumerate -@item -The symbol @code{let}; - -@item -A varlist containing, in this case, a single two-element list, -@code{(@var{variable} @var{value})}; - -@item -The body of the @code{let} expression. -@end enumerate - -@need 800 -In the @code{append-to-buffer} function, the varlist looks like this: - -@smallexample -(oldbuf (current-buffer)) -@end smallexample - -@noindent -In this part of the @code{let} expression, the one variable, -@code{oldbuf}, is bound to the value returned by the -@code{(current-buffer)} expression. The variable, @code{oldbuf}, is -used to keep track of the buffer in which you are working and from -which you will copy. - -The element or elements of a varlist are surrounded by a set of -parentheses so the Lisp interpreter can distinguish the varlist from -the body of the @code{let}. As a consequence, the two-element list -within the varlist is surrounded by a circumscribing set of parentheses. -The line looks like this: - -@smallexample -@group -(let ((oldbuf (current-buffer))) - @dots{} ) -@end group -@end smallexample - -@noindent -The two parentheses before @code{oldbuf} might surprise you if you did -not realize that the first parenthesis before @code{oldbuf} marks the -boundary of the varlist and the second parenthesis marks the beginning -of the two-element list, @code{(oldbuf (current-buffer))}. - -@node append save-excursion, , append-to-buffer body, append-to-buffer -@comment node-name, next, previous, up -@subsection @code{save-excursion} in @code{append-to-buffer} - -The body of the @code{let} expression in @code{append-to-buffer} -consists of a @code{save-excursion} expression. - -The @code{save-excursion} function saves the locations of point and -mark, and restores them to those positions after the expressions in the -body of the @code{save-excursion} complete execution. In addition, -@code{save-excursion} keeps track of the original buffer, and -restores it. This is how @code{save-excursion} is used in -@code{append-to-buffer}. - -@need 1500 -@cindex Indentation for formatting -@cindex Formatting convention -Incidentally, it is worth noting here that a Lisp function is normally -formatted so that everything that is enclosed in a multi-line spread is -indented more to the right than the first symbol. In this function -definition, the @code{let} is indented more than the @code{defun}, and -the @code{save-excursion} is indented more than the @code{let}, like -this: - -@smallexample -@group -(defun @dots{} - @dots{} - @dots{} - (let@dots{} - (save-excursion - @dots{} -@end group -@end smallexample - -@need 1500 -@noindent -This formatting convention makes it easy to see that the lines in -the body of the @code{save-excursion} are enclosed by the parentheses -associated with @code{save-excursion}, just as the -@code{save-excursion} itself is enclosed by the parentheses associated -with the @code{let}: - -@smallexample -@group -(let ((oldbuf (current-buffer))) - (save-excursion - @dots{} - (set-buffer @dots{}) - (insert-buffer-substring oldbuf start end) - @dots{})) -@end group -@end smallexample - -@need 1200 -The use of the @code{save-excursion} function can be viewed as a process -of filling in the slots of a template: - -@smallexample -@group -(save-excursion - @var{first-expression-in-body} - @var{second-expression-in-body} - @dots{} - @var{last-expression-in-body}) -@end group -@end smallexample - -@need 1200 -@noindent -In this function, the body of the @code{save-excursion} contains only -one expression, the @code{let*} expression. You know about a -@code{let} function. The @code{let*} function is different. It has a -@samp{*} in its name. It enables Emacs to set each variable in its -varlist in sequence, one after another. - -Its critical feature is that variables later in the varlist can make -use of the values to which Emacs set variables earlier in the varlist. -@xref{fwd-para let, , The @code{let*} expression}. - -We will skip functions like @code{let*} and focus on two: the -@code{set-buffer} function and the @code{insert-buffer-substring} -function. - -@need 1250 -In the old days, the @code{set-buffer} expression was simply - -@smallexample -(set-buffer (get-buffer-create buffer)) -@end smallexample - -@need 1250 -@noindent -but now it is - -@smallexample -(set-buffer append-to) -@end smallexample - -@noindent -@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier -on in the @code{let*} expression. That extra binding would not be -necessary except for that @code{append-to} is used later in the -varlist as an argument to @code{get-buffer-window-list}. - -@ignore -in GNU Emacs 22 - - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - -The @code{append-to-buffer} function definition inserts text from the -buffer in which you are currently to a named buffer. It happens that -@code{insert-buffer-substring} copies text from another buffer to the -current buffer, just the reverse---that is why the -@code{append-to-buffer} definition starts out with a @code{let} that -binds the local symbol @code{oldbuf} to the value returned by -@code{current-buffer}. - -@need 1250 -The @code{insert-buffer-substring} expression looks like this: - -@smallexample -(insert-buffer-substring oldbuf start end) -@end smallexample - -@noindent -The @code{insert-buffer-substring} function copies a string -@emph{from} the buffer specified as its first argument and inserts the -string into the present buffer. In this case, the argument to -@code{insert-buffer-substring} is the value of the variable created -and bound by the @code{let}, namely the value of @code{oldbuf}, which -was the current buffer when you gave the @code{append-to-buffer} -command. - -After @code{insert-buffer-substring} has done its work, -@code{save-excursion} will restore the action to the original buffer -and @code{append-to-buffer} will have done its job. - -@need 800 -Written in skeletal form, the workings of the body look like this: - -@smallexample -@group -(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) - (save-excursion ; @r{Keep track of buffer.} - @var{change-buffer} - @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}) - - @var{change-back-to-original-buffer-when-finished} -@var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished} -@end group -@end smallexample - -In summary, @code{append-to-buffer} works as follows: it saves the -value of the current buffer in the variable called @code{oldbuf}. It -gets the new buffer (creating one if need be) and switches Emacs's -attention to it. Using the value of @code{oldbuf}, it inserts the -region of text from the old buffer into the new buffer; and then using -@code{save-excursion}, it brings you back to your original buffer. - -In looking at @code{append-to-buffer}, you have explored a fairly -complex function. It shows how to use @code{let} and -@code{save-excursion}, and how to change to and come back from another -buffer. Many function definitions use @code{let}, -@code{save-excursion}, and @code{set-buffer} this way. - -@node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through -@comment node-name, next, previous, up -@section Review - -Here is a brief summary of the various functions discussed in this chapter. - -@table @code -@item describe-function -@itemx describe-variable -Print the documentation for a function or variable. -Conventionally bound to @kbd{C-h f} and @kbd{C-h v}. - -@item find-tag -Find the file containing the source for a function or variable and -switch buffers to it, positioning point at the beginning of the item. -Conventionally bound to @kbd{M-.} (that's a period following the -@key{META} key). - -@item save-excursion -Save the location of point and mark and restore their values after the -arguments to @code{save-excursion} have been evaluated. Also, remember -the current buffer and return to it. - -@item push-mark -Set mark at a location and record the value of the previous mark on the -mark ring. The mark is a location in the buffer that will keep its -relative position even if text is added to or removed from the buffer. - -@item goto-char -Set point to the location specified by the value of the argument, which -can be a number, a marker, or an expression that returns the number of -a position, such as @code{(point-min)}. - -@item insert-buffer-substring -Copy a region of text from a buffer that is passed to the function as -an argument and insert the region into the current buffer. - -@item mark-whole-buffer -Mark the whole buffer as a region. Normally bound to @kbd{C-x h}. - -@item set-buffer -Switch the attention of Emacs to another buffer, but do not change the -window being displayed. Used when the program rather than a human is -to work on a different buffer. - -@item get-buffer-create -@itemx get-buffer -Find a named buffer or create one if a buffer of that name does not -exist. The @code{get-buffer} function returns @code{nil} if the named -buffer does not exist. -@end table - -@need 1500 -@node Buffer Exercises, , Buffer Related Review, Buffer Walk Through -@section Exercises - -@itemize @bullet -@item -Write your own @code{simplified-end-of-buffer} function definition; -then test it to see whether it works. - -@item -Use @code{if} and @code{get-buffer} to write a function that prints a -message telling you whether a buffer exists. - -@item -Using @code{find-tag}, find the source for the @code{copy-to-buffer} -function. -@end itemize - -@node More Complex, Narrowing & Widening, Buffer Walk Through, Top -@comment node-name, next, previous, up -@chapter A Few More Complex Functions - -In this chapter, we build on what we have learned in previous chapters -by looking at more complex functions. The @code{copy-to-buffer} -function illustrates use of two @code{save-excursion} expressions in -one definition, while the @code{insert-buffer} function illustrates -use of an asterisk in an @code{interactive} expression, use of -@code{or}, and the important distinction between a name and the object -to which the name refers. - -@menu -* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. -* insert-buffer:: Read-only, and with @code{or}. -* beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* Second Buffer Related Review:: -* optional Exercise:: -@end menu - -@node copy-to-buffer, insert-buffer, More Complex, More Complex -@comment node-name, next, previous, up -@section The Definition of @code{copy-to-buffer} -@findex copy-to-buffer - -After understanding how @code{append-to-buffer} works, it is easy to -understand @code{copy-to-buffer}. This function copies text into a -buffer, but instead of adding to the second buffer, it replaces all the -previous text in the second buffer. - -@need 800 -The body of @code{copy-to-buffer} looks like this, - -@smallexample -@group -@dots{} -(interactive "BCopy to buffer: \nr") -(let ((oldbuf (current-buffer))) - (with-current-buffer (get-buffer-create buffer) - (barf-if-buffer-read-only) - (erase-buffer) - (save-excursion - (insert-buffer-substring oldbuf start end))))) -@end group -@end smallexample - -The @code{copy-to-buffer} function has a simpler @code{interactive} -expression than @code{append-to-buffer}. - -@need 800 -The definition then says - -@smallexample -(with-current-buffer (get-buffer-create buffer) @dots{} -@end smallexample - -First, look at the earliest inner expression; that is evaluated first. -That expression starts with @code{get-buffer-create buffer}. The -function tells the computer to use the buffer with the name specified -as the one to which you are copying, or if such a buffer does not -exist, to create it. Then, the @code{with-current-buffer} function -evaluates its body with that buffer temporarily current. - -(This demonstrates another way to shift the computer's attention but -not the user's. The @code{append-to-buffer} function showed how to do -the same with @code{save-excursion} and @code{set-buffer}. -@code{with-current-buffer} is a newer, and arguably easier, -mechanism.) - -The @code{barf-if-buffer-read-only} function sends you an error -message saying the buffer is read-only if you cannot modify it. - -The next line has the @code{erase-buffer} function as its sole -contents. That function erases the buffer. - -Finally, the last two lines contain the @code{save-excursion} -expression with @code{insert-buffer-substring} as its body. -The @code{insert-buffer-substring} expression copies the text from -the buffer you are in (and you have not seen the computer shift its -attention, so you don't know that that buffer is now called -@code{oldbuf}). - -Incidentally, this is what is meant by `replacement'. To replace text, -Emacs erases the previous text and then inserts new text. - -@need 1250 -In outline, the body of @code{copy-to-buffer} looks like this: - -@smallexample -@group -(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) - (@var{with-the-buffer-you-are-copying-to} - (@var{but-do-not-erase-or-copy-to-a-read-only-buffer}) - (erase-buffer) - (save-excursion - @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}))) -@end group -@end smallexample - -@node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex -@comment node-name, next, previous, up -@section The Definition of @code{insert-buffer} -@findex insert-buffer - -@code{insert-buffer} is yet another buffer-related function. This -command copies another buffer @emph{into} the current buffer. It is the -reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they -copy a region of text @emph{from} the current buffer to another buffer. - -Here is a discussion based on the original code. The code was -simplified in 2003 and is harder to understand. - -(@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see -a discussion of the new body.) - -In addition, this code illustrates the use of @code{interactive} with a -buffer that might be @dfn{read-only} and the important distinction -between the name of an object and the object actually referred to. - -@menu -* insert-buffer code:: -* insert-buffer interactive:: When you can read, but not write. -* insert-buffer body:: The body has an @code{or} and a @code{let}. -* if & or:: Using an @code{if} instead of an @code{or}. -* Insert or:: How the @code{or} expression works. -* Insert let:: Two @code{save-excursion} expressions. -* New insert-buffer:: -@end menu - -@node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer -@ifnottex -@unnumberedsubsec The Code for @code{insert-buffer} -@end ifnottex - -@need 800 -Here is the earlier code: - -@smallexample -@group -(defun insert-buffer (buffer) - "Insert after point the contents of BUFFER. -Puts mark after the inserted text. -BUFFER may be a buffer or a buffer name." - (interactive "*bInsert buffer:@: ") -@end group -@group - (or (bufferp buffer) - (setq buffer (get-buffer buffer))) - (let (start end newmark) - (save-excursion - (save-excursion - (set-buffer buffer) - (setq start (point-min) end (point-max))) -@end group -@group - (insert-buffer-substring buffer start end) - (setq newmark (point))) - (push-mark newmark))) -@end group -@end smallexample - -@need 1200 -As with other function definitions, you can use a template to see an -outline of the function: - -@smallexample -@group -(defun insert-buffer (buffer) - "@var{documentation}@dots{}" - (interactive "*bInsert buffer:@: ") - @var{body}@dots{}) -@end group -@end smallexample - -@node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer -@comment node-name, next, previous, up -@subsection The Interactive Expression in @code{insert-buffer} -@findex interactive, @r{example use of} - -In @code{insert-buffer}, the argument to the @code{interactive} -declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert -buffer:@: }. - -@menu -* Read-only buffer:: When a buffer cannot be modified. -* b for interactive:: An existing buffer or else its name. -@end menu - -@node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive -@comment node-name, next, previous, up -@unnumberedsubsubsec A Read-only Buffer -@cindex Read-only buffer -@cindex Asterisk for read-only buffer -@findex * @r{for read-only buffer} - -The asterisk is for the situation when the current buffer is a -read-only buffer---a buffer that cannot be modified. If -@code{insert-buffer} is called when the current buffer is read-only, a -message to this effect is printed in the echo area and the terminal -may beep or blink at you; you will not be permitted to insert anything -into current buffer. The asterisk does not need to be followed by a -newline to separate it from the next argument. - -@node b for interactive, , Read-only buffer, insert-buffer interactive -@comment node-name, next, previous, up -@unnumberedsubsubsec @samp{b} in an Interactive Expression - -The next argument in the interactive expression starts with a lower -case @samp{b}. (This is different from the code for -@code{append-to-buffer}, which uses an upper-case @samp{B}. -@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) -The lower-case @samp{b} tells the Lisp interpreter that the argument -for @code{insert-buffer} should be an existing buffer or else its -name. (The upper-case @samp{B} option provides for the possibility -that the buffer does not exist.) Emacs will prompt you for the name -of the buffer, offering you a default buffer, with name completion -enabled. If the buffer does not exist, you receive a message that -says ``No match''; your terminal may beep at you as well. - -The new and simplified code generates a list for @code{interactive}. -It uses the @code{barf-if-buffer-read-only} and @code{read-buffer} -functions with which we are already familiar and the @code{progn} -special form with which we are not. (It will be described later.) - -@node insert-buffer body, if & or, insert-buffer interactive, insert-buffer -@comment node-name, next, previous, up -@subsection The Body of the @code{insert-buffer} Function - -The body of the @code{insert-buffer} function has two major parts: an -@code{or} expression and a @code{let} expression. The purpose of the -@code{or} expression is to ensure that the argument @code{buffer} is -bound to a buffer and not just the name of a buffer. The body of the -@code{let} expression contains the code which copies the other buffer -into the current buffer. - -@need 1250 -In outline, the two expressions fit into the @code{insert-buffer} -function like this: - -@smallexample -@group -(defun insert-buffer (buffer) - "@var{documentation}@dots{}" - (interactive "*bInsert buffer:@: ") - (or @dots{} - @dots{} -@end group -@group - (let (@var{varlist}) - @var{body-of-}@code{let}@dots{} ) -@end group -@end smallexample - -To understand how the @code{or} expression ensures that the argument -@code{buffer} is bound to a buffer and not to the name of a buffer, it -is first necessary to understand the @code{or} function. - -Before doing this, let me rewrite this part of the function using -@code{if} so that you can see what is done in a manner that will be familiar. - -@node if & or, Insert or, insert-buffer body, insert-buffer -@comment node-name, next, previous, up -@subsection @code{insert-buffer} With an @code{if} Instead of an @code{or} - -The job to be done is to make sure the value of @code{buffer} is a -buffer itself and not the name of a buffer. If the value is the name, -then the buffer itself must be got. - -You can imagine yourself at a conference where an usher is wandering -around holding a list with your name on it and looking for you: the -usher is ``bound'' to your name, not to you; but when the usher finds -you and takes your arm, the usher becomes ``bound'' to you. - -@need 800 -In Lisp, you might describe this situation like this: - -@smallexample -@group -(if (not (holding-on-to-guest)) - (find-and-take-arm-of-guest)) -@end group -@end smallexample - -We want to do the same thing with a buffer---if we do not have the -buffer itself, we want to get it. - -@need 1200 -Using a predicate called @code{bufferp} that tells us whether we have a -buffer (rather than its name), we can write the code like this: - -@smallexample -@group -(if (not (bufferp buffer)) ; @r{if-part} - (setq buffer (get-buffer buffer))) ; @r{then-part} -@end group -@end smallexample - -@noindent -Here, the true-or-false-test of the @code{if} expression is -@w{@code{(not (bufferp buffer))}}; and the then-part is the expression -@w{@code{(setq buffer (get-buffer buffer))}}. - -In the test, the function @code{bufferp} returns true if its argument is -a buffer---but false if its argument is the name of the buffer. (The -last character of the function name @code{bufferp} is the character -@samp{p}; as we saw earlier, such use of @samp{p} is a convention that -indicates that the function is a predicate, which is a term that means -that the function will determine whether some property is true or false. -@xref{Wrong Type of Argument, , Using the Wrong Type Object as an -Argument}.) - -@need 1200 -The function @code{not} precedes the expression @code{(bufferp buffer)}, -so the true-or-false-test looks like this: - -@smallexample -(not (bufferp buffer)) -@end smallexample - -@noindent -@code{not} is a function that returns true if its argument is false -and false if its argument is true. So if @code{(bufferp buffer)} -returns true, the @code{not} expression returns false and vice-verse: -what is ``not true'' is false and what is ``not false'' is true. - -Using this test, the @code{if} expression works as follows: when the -value of the variable @code{buffer} is actually a buffer rather than -its name, the true-or-false-test returns false and the @code{if} -expression does not evaluate the then-part. This is fine, since we do -not need to do anything to the variable @code{buffer} if it really is -a buffer. - -On the other hand, when the value of @code{buffer} is not a buffer -itself, but the name of a buffer, the true-or-false-test returns true -and the then-part of the expression is evaluated. In this case, the -then-part is @code{(setq buffer (get-buffer buffer))}. This -expression uses the @code{get-buffer} function to return an actual -buffer itself, given its name. The @code{setq} then sets the variable -@code{buffer} to the value of the buffer itself, replacing its previous -value (which was the name of the buffer). - -@node Insert or, Insert let, if & or, insert-buffer -@comment node-name, next, previous, up -@subsection The @code{or} in the Body - -The purpose of the @code{or} expression in the @code{insert-buffer} -function is to ensure that the argument @code{buffer} is bound to a -buffer and not just to the name of a buffer. The previous section shows -how the job could have been done using an @code{if} expression. -However, the @code{insert-buffer} function actually uses @code{or}. -To understand this, it is necessary to understand how @code{or} works. - -@findex or -An @code{or} function can have any number of arguments. It evaluates -each argument in turn and returns the value of the first of its -arguments that is not @code{nil}. Also, and this is a crucial feature -of @code{or}, it does not evaluate any subsequent arguments after -returning the first non-@code{nil} value. - -@need 800 -The @code{or} expression looks like this: - -@smallexample -@group -(or (bufferp buffer) - (setq buffer (get-buffer buffer))) -@end group -@end smallexample - -@noindent -The first argument to @code{or} is the expression @code{(bufferp buffer)}. -This expression returns true (a non-@code{nil} value) if the buffer is -actually a buffer, and not just the name of a buffer. In the @code{or} -expression, if this is the case, the @code{or} expression returns this -true value and does not evaluate the next expression---and this is fine -with us, since we do not want to do anything to the value of -@code{buffer} if it really is a buffer. - -On the other hand, if the value of @code{(bufferp buffer)} is @code{nil}, -which it will be if the value of @code{buffer} is the name of a buffer, -the Lisp interpreter evaluates the next element of the @code{or} -expression. This is the expression @code{(setq buffer (get-buffer -buffer))}. This expression returns a non-@code{nil} value, which -is the value to which it sets the variable @code{buffer}---and this -value is a buffer itself, not the name of a buffer. - -The result of all this is that the symbol @code{buffer} is always -bound to a buffer itself rather than to the name of a buffer. All -this is necessary because the @code{set-buffer} function in a -following line only works with a buffer itself, not with the name to a -buffer. - -@need 1250 -Incidentally, using @code{or}, the situation with the usher would be -written like this: - -@smallexample -(or (holding-on-to-guest) (find-and-take-arm-of-guest)) -@end smallexample - -@node Insert let, New insert-buffer, Insert or, insert-buffer -@comment node-name, next, previous, up -@subsection The @code{let} Expression in @code{insert-buffer} - -After ensuring that the variable @code{buffer} refers to a buffer itself -and not just to the name of a buffer, the @code{insert-buffer function} -continues with a @code{let} expression. This specifies three local -variables, @code{start}, @code{end}, and @code{newmark} and binds them -to the initial value @code{nil}. These variables are used inside the -remainder of the @code{let} and temporarily hide any other occurrence of -variables of the same name in Emacs until the end of the @code{let}. - -@need 1200 -The body of the @code{let} contains two @code{save-excursion} -expressions. First, we will look at the inner @code{save-excursion} -expression in detail. The expression looks like this: - -@smallexample -@group -(save-excursion - (set-buffer buffer) - (setq start (point-min) end (point-max))) -@end group -@end smallexample - -@noindent -The expression @code{(set-buffer buffer)} changes Emacs's attention -from the current buffer to the one from which the text will copied. -In that buffer, the variables @code{start} and @code{end} are set to -the beginning and end of the buffer, using the commands -@code{point-min} and @code{point-max}. Note that we have here an -illustration of how @code{setq} is able to set two variables in the -same expression. The first argument of @code{setq} is set to the -value of its second, and its third argument is set to the value of its -fourth. - -After the body of the inner @code{save-excursion} is evaluated, the -@code{save-excursion} restores the original buffer, but @code{start} and -@code{end} remain set to the values of the beginning and end of the -buffer from which the text will be copied. - -@need 1250 -The outer @code{save-excursion} expression looks like this: - -@smallexample -@group -(save-excursion - (@var{inner-}@code{save-excursion}@var{-expression} - (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end}) - (insert-buffer-substring buffer start end) - (setq newmark (point))) -@end group -@end smallexample - -@noindent -The @code{insert-buffer-substring} function copies the text -@emph{into} the current buffer @emph{from} the region indicated by -@code{start} and @code{end} in @code{buffer}. Since the whole of the -second buffer lies between @code{start} and @code{end}, the whole of -the second buffer is copied into the buffer you are editing. Next, -the value of point, which will be at the end of the inserted text, is -recorded in the variable @code{newmark}. - -After the body of the outer @code{save-excursion} is evaluated, point -and mark are relocated to their original places. - -However, it is convenient to locate a mark at the end of the newly -inserted text and locate point at its beginning. The @code{newmark} -variable records the end of the inserted text. In the last line of -the @code{let} expression, the @code{(push-mark newmark)} expression -function sets a mark to this location. (The previous location of the -mark is still accessible; it is recorded on the mark ring and you can -go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is -located at the beginning of the inserted text, which is where it was -before you called the insert function, the position of which was saved -by the first @code{save-excursion}. - -@need 1250 -The whole @code{let} expression looks like this: - -@smallexample -@group -(let (start end newmark) - (save-excursion - (save-excursion - (set-buffer buffer) - (setq start (point-min) end (point-max))) - (insert-buffer-substring buffer start end) - (setq newmark (point))) - (push-mark newmark)) -@end group -@end smallexample - -Like the @code{append-to-buffer} function, the @code{insert-buffer} -function uses @code{let}, @code{save-excursion}, and -@code{set-buffer}. In addition, the function illustrates one way to -use @code{or}. All these functions are building blocks that we will -find and use again and again. - -@node New insert-buffer, , Insert let, insert-buffer -@comment node-name, next, previous, up -@subsection New Body for @code{insert-buffer} -@findex insert-buffer, new version body -@findex new version body for insert-buffer - -The body in the GNU Emacs 22 version is more confusing than the original. - -@need 1250 -It consists of two expressions, - -@smallexample -@group - (push-mark - (save-excursion - (insert-buffer-substring (get-buffer buffer)) - (point))) - - nil -@end group -@end smallexample - -@noindent -except, and this is what confuses novices, very important work is done -inside the @code{push-mark} expression. - -The @code{get-buffer} function returns a buffer with the name -provided. You will note that the function is @emph{not} called -@code{get-buffer-create}; it does not create a buffer if one does not -already exist. The buffer returned by @code{get-buffer}, an existing -buffer, is passed to @code{insert-buffer-substring}, which inserts the -whole of the buffer (since you did not specify anything else). - -The location into which the buffer is inserted is recorded by -@code{push-mark}. Then the function returns @code{nil}, the value of -its last command. Put another way, the @code{insert-buffer} function -exists only to produce a side effect, inserting another buffer, not to -return any value. - -@node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex -@comment node-name, next, previous, up -@section Complete Definition of @code{beginning-of-buffer} -@findex beginning-of-buffer - -The basic structure of the @code{beginning-of-buffer} function has -already been discussed. (@xref{simplified-beginning-of-buffer, , A -Simplified @code{beginning-of-buffer} Definition}.) -This section describes the complex part of the definition. - -As previously described, when invoked without an argument, -@code{beginning-of-buffer} moves the cursor to the beginning of the -buffer (in truth, the beginning of the accessible portion of the -buffer), leaving the mark at the previous position. However, when the -command is invoked with a number between one and ten, the function -considers that number to be a fraction of the length of the buffer, -measured in tenths, and Emacs moves the cursor that fraction of the -way from the beginning of the buffer. Thus, you can either call this -function with the key command @kbd{M-<}, which will move the cursor to -the beginning of the buffer, or with a key command such as @kbd{C-u 7 -M-<} which will move the cursor to a point 70% of the way through the -buffer. If a number bigger than ten is used for the argument, it -moves to the end of the buffer. - -The @code{beginning-of-buffer} function can be called with or without an -argument. The use of the argument is optional. - -@menu -* Optional Arguments:: -* beginning-of-buffer opt arg:: Example with optional argument. -* beginning-of-buffer complete:: -@end menu - -@node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer -@subsection Optional Arguments - -Unless told otherwise, Lisp expects that a function with an argument in -its function definition will be called with a value for that argument. -If that does not happen, you get an error and a message that says -@samp{Wrong number of arguments}. - -@cindex Optional arguments -@cindex Keyword -@findex optional -However, optional arguments are a feature of Lisp: a particular -@dfn{keyword} is used to tell the Lisp interpreter that an argument is -optional. The keyword is @code{&optional}. (The @samp{&} in front of -@samp{optional} is part of the keyword.) In a function definition, if -an argument follows the keyword @code{&optional}, no value need be -passed to that argument when the function is called. - -@need 1200 -The first line of the function definition of @code{beginning-of-buffer} -therefore looks like this: - -@smallexample -(defun beginning-of-buffer (&optional arg) -@end smallexample - -@need 1250 -In outline, the whole function looks like this: - -@smallexample -@group -(defun beginning-of-buffer (&optional arg) - "@var{documentation}@dots{}" - (interactive "P") - (or (@var{is-the-argument-a-cons-cell} arg) - (and @var{are-both-transient-mark-mode-and-mark-active-true}) - (push-mark)) - (let (@var{determine-size-and-set-it}) - (goto-char - (@var{if-there-is-an-argument} - @var{figure-out-where-to-go} - @var{else-go-to} - (point-min)))) - @var{do-nicety} -@end group -@end smallexample - -The function is similar to the @code{simplified-beginning-of-buffer} -function except that the @code{interactive} expression has @code{"P"} -as an argument and the @code{goto-char} function is followed by an -if-then-else expression that figures out where to put the cursor if -there is an argument that is not a cons cell. - -(Since I do not explain a cons cell for many more chapters, please -consider ignoring the function @code{consp}. @xref{List -Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type, -, Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference -Manual}.) - -The @code{"P"} in the @code{interactive} expression tells Emacs to -pass a prefix argument, if there is one, to the function in raw form. -A prefix argument is made by typing the @key{META} key followed by a -number, or by typing @kbd{C-u} and then a number. (If you don't type -a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase -@code{"p"} in the @code{interactive} expression causes the function to -convert a prefix arg to a number.) - -The true-or-false-test of the @code{if} expression looks complex, but -it is not: it checks whether @code{arg} has a value that is not -@code{nil} and whether it is a cons cell. (That is what @code{consp} -does; it checks whether its argument is a cons cell.) If @code{arg} -has a value that is not @code{nil} (and is not a cons cell), which -will be the case if @code{beginning-of-buffer} is called with a -numeric argument, then this true-or-false-test will return true and -the then-part of the @code{if} expression will be evaluated. On the -other hand, if @code{beginning-of-buffer} is not called with an -argument, the value of @code{arg} will be @code{nil} and the else-part -of the @code{if} expression will be evaluated. The else-part is -simply @code{point-min}, and when this is the outcome, the whole -@code{goto-char} expression is @code{(goto-char (point-min))}, which -is how we saw the @code{beginning-of-buffer} function in its -simplified form. - -@node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer -@subsection @code{beginning-of-buffer} with an Argument - -When @code{beginning-of-buffer} is called with an argument, an -expression is evaluated which calculates what value to pass to -@code{goto-char}. This expression is rather complicated at first sight. -It includes an inner @code{if} expression and much arithmetic. It looks -like this: - -@smallexample -@group -(if (> (buffer-size) 10000) - ;; @r{Avoid overflow for large buffer sizes!} - (* (prefix-numeric-value arg) - (/ size 10)) - (/ - (+ 10 - (* - size (prefix-numeric-value arg))) 10))) -@end group -@end smallexample - -@menu -* Disentangle beginning-of-buffer:: -* Large buffer case:: -* Small buffer case:: -@end menu - -@node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg -@ifnottex -@unnumberedsubsubsec Disentangle @code{beginning-of-buffer} -@end ifnottex - -Like other complex-looking expressions, the conditional expression -within @code{beginning-of-buffer} can be disentangled by looking at it -as parts of a template, in this case, the template for an if-then-else -expression. In skeletal form, the expression looks like this: - -@smallexample -@group -(if (@var{buffer-is-large} - @var{divide-buffer-size-by-10-and-multiply-by-arg} - @var{else-use-alternate-calculation} -@end group -@end smallexample - -The true-or-false-test of this inner @code{if} expression checks the -size of the buffer. The reason for this is that the old version 18 -Emacs used numbers that are no bigger than eight million or so and in -the computation that followed, the programmer feared that Emacs might -try to use over-large numbers if the buffer were large. The term -`overflow', mentioned in the comment, means numbers that are over -large. More recent versions of Emacs use larger numbers, but this -code has not been touched, if only because people now look at buffers -that are far, far larger than ever before. - -There are two cases: if the buffer is large and if it is not. - -@node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg -@comment node-name, next, previous, up -@unnumberedsubsubsec What happens in a large buffer - -In @code{beginning-of-buffer}, the inner @code{if} expression tests -whether the size of the buffer is greater than 10,000 characters. To do -this, it uses the @code{>} function and the computation of @code{size} -that comes from the let expression. - -In the old days, the function @code{buffer-size} was used. Not only -was that function called several times, it gave the size of the whole -buffer, not the accessible part. The computation makes much more -sense when it handles just the accessible part. (@xref{Narrowing & -Widening, , Narrowing and Widening}, for more information on focusing -attention to an `accessible' part.) - -@need 800 -The line looks like this: - -@smallexample -(if (> size 10000) -@end smallexample - -@need 1200 -@noindent -When the buffer is large, the then-part of the @code{if} expression is -evaluated. It reads like this (after formatting for easy reading): - -@smallexample -@group -(* - (prefix-numeric-value arg) - (/ size 10)) -@end group -@end smallexample - -@noindent -This expression is a multiplication, with two arguments to the function -@code{*}. - -The first argument is @code{(prefix-numeric-value arg)}. When -@code{"P"} is used as the argument for @code{interactive}, the value -passed to the function as its argument is passed a ``raw prefix -argument'', and not a number. (It is a number in a list.) To perform -the arithmetic, a conversion is necessary, and -@code{prefix-numeric-value} does the job. - -@findex / @r{(division)} -@cindex Division -The second argument is @code{(/ size 10)}. This expression divides -the numeric value by ten --- the numeric value of the size of the -accessible portion of the buffer. This produces a number that tells -how many characters make up one tenth of the buffer size. (In Lisp, -@code{/} is used for division, just as @code{*} is used for -multiplication.) - -@need 1200 -In the multiplication expression as a whole, this amount is multiplied -by the value of the prefix argument---the multiplication looks like this: - -@smallexample -@group -(* @var{numeric-value-of-prefix-arg} - @var{number-of-characters-in-one-tenth-of-the-accessible-buffer}) -@end group -@end smallexample - -@noindent -If, for example, the prefix argument is @samp{7}, the one-tenth value -will be multiplied by 7 to give a position 70% of the way through. - -@need 1200 -The result of all this is that if the accessible portion of the buffer -is large, the @code{goto-char} expression reads like this: - -@smallexample -@group -(goto-char (* (prefix-numeric-value arg) - (/ size 10))) -@end group -@end smallexample - -This puts the cursor where we want it. - -@node Small buffer case, , Large buffer case, beginning-of-buffer opt arg -@comment node-name, next, previous, up -@unnumberedsubsubsec What happens in a small buffer - -If the buffer contains fewer than 10,000 characters, a slightly -different computation is performed. You might think this is not -necessary, since the first computation could do the job. However, in -a small buffer, the first method may not put the cursor on exactly the -desired line; the second method does a better job. - -@need 800 -The code looks like this: - -@c Keep this on one line. -@smallexample -(/ (+ 10 (* size (prefix-numeric-value arg))) 10)) -@end smallexample - -@need 1200 -@noindent -This is code in which you figure out what happens by discovering how the -functions are embedded in parentheses. It is easier to read if you -reformat it with each expression indented more deeply than its -enclosing expression: - -@smallexample -@group - (/ - (+ 10 - (* - size - (prefix-numeric-value arg))) - 10)) -@end group -@end smallexample - -@need 1200 -@noindent -Looking at parentheses, we see that the innermost operation is -@code{(prefix-numeric-value arg)}, which converts the raw argument to -a number. In the following expression, this number is multiplied by -the size of the accessible portion of the buffer: - -@smallexample -(* size (prefix-numeric-value arg)) -@end smallexample - -@noindent -This multiplication creates a number that may be larger than the size of -the buffer---seven times larger if the argument is 7, for example. Ten -is then added to this number and finally the large number is divided by -ten to provide a value that is one character larger than the percentage -position in the buffer. - -The number that results from all this is passed to @code{goto-char} and -the cursor is moved to that point. - -@need 1500 -@node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer -@comment node-name, next, previous, up -@subsection The Complete @code{beginning-of-buffer} - -@need 1000 -Here is the complete text of the @code{beginning-of-buffer} function: -@sp 1 - -@c In GNU Emacs 22 -@smallexample -@group -(defun beginning-of-buffer (&optional arg) - "Move point to the beginning of the buffer; -leave mark at previous position. -With \\[universal-argument] prefix, -do not set mark at previous position. -With numeric arg N, -put point N/10 of the way from the beginning. - -If the buffer is narrowed, -this command uses the beginning and size -of the accessible part of the buffer. -@end group - -@group -Don't use this command in Lisp programs! -\(goto-char (point-min)) is faster -and avoids clobbering the mark." - (interactive "P") - (or (consp arg) - (and transient-mark-mode mark-active) - (push-mark)) -@end group -@group - (let ((size (- (point-max) (point-min)))) - (goto-char (if (and arg (not (consp arg))) - (+ (point-min) - (if (> size 10000) - ;; Avoid overflow for large buffer sizes! - (* (prefix-numeric-value arg) - (/ size 10)) - (/ (+ 10 (* size (prefix-numeric-value arg))) - 10))) - (point-min)))) - (if arg (forward-line 1))) -@end group -@end smallexample - -@ignore -From before GNU Emacs 22 -@smallexample -@group -(defun beginning-of-buffer (&optional arg) - "Move point to the beginning of the buffer; -leave mark at previous position. -With arg N, put point N/10 of the way -from the true beginning. -@end group -@group -Don't use this in Lisp programs! -\(goto-char (point-min)) is faster -and does not set the mark." - (interactive "P") - (push-mark) -@end group -@group - (goto-char - (if arg - (if (> (buffer-size) 10000) - ;; @r{Avoid overflow for large buffer sizes!} - (* (prefix-numeric-value arg) - (/ (buffer-size) 10)) -@end group -@group - (/ (+ 10 (* (buffer-size) - (prefix-numeric-value arg))) - 10)) - (point-min))) - (if arg (forward-line 1))) -@end group -@end smallexample -@end ignore - -@noindent -Except for two small points, the previous discussion shows how this -function works. The first point deals with a detail in the -documentation string, and the second point concerns the last line of -the function. - -@need 800 -In the documentation string, there is reference to an expression: - -@smallexample -\\[universal-argument] -@end smallexample - -@noindent -A @samp{\\} is used before the first square bracket of this -expression. This @samp{\\} tells the Lisp interpreter to substitute -whatever key is currently bound to the @samp{[@dots{}]}. In the case -of @code{universal-argument}, that is usually @kbd{C-u}, but it might -be different. (@xref{Documentation Tips, , Tips for Documentation -Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more -information.) - -@need 1200 -Finally, the last line of the @code{beginning-of-buffer} command says -to move point to the beginning of the next line if the command is -invoked with an argument: - -@smallexample -(if arg (forward-line 1))) -@end smallexample - -@noindent -This puts the cursor at the beginning of the first line after the -appropriate tenths position in the buffer. This is a flourish that -means that the cursor is always located @emph{at least} the requested -tenths of the way through the buffer, which is a nicety that is, -perhaps, not necessary, but which, if it did not occur, would be sure -to draw complaints. - -On the other hand, it also means that if you specify the command with -a @kbd{C-u}, but without a number, that is to say, if the `raw prefix -argument' is simply a cons cell, then the command puts you at the -beginning of the second line @dots{} I don't know whether this is -intended or whether no one has dealt with the code to avoid this -happening. - -@node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex -@comment node-name, next, previous, up -@section Review - -Here is a brief summary of some of the topics covered in this chapter. - -@table @code -@item or -Evaluate each argument in sequence, and return the value of the first -argument that is not @code{nil}; if none return a value that is not -@code{nil}, return @code{nil}. In brief, return the first true value -of the arguments; return a true value if one @emph{or} any of the -others are true. - -@item and -Evaluate each argument in sequence, and if any are @code{nil}, return -@code{nil}; if none are @code{nil}, return the value of the last -argument. In brief, return a true value only if all the arguments are -true; return a true value if one @emph{and} each of the others is -true. - -@item &optional -A keyword used to indicate that an argument to a function definition -is optional; this means that the function can be evaluated without the -argument, if desired. - -@item prefix-numeric-value -Convert the `raw prefix argument' produced by @code{(interactive -"P")} to a numeric value. - -@item forward-line -Move point forward to the beginning of the next line, or if the argument -is greater than one, forward that many lines. If it can't move as far -forward as it is supposed to, @code{forward-line} goes forward as far as -it can and then returns a count of the number of additional lines it was -supposed to move but couldn't. - -@item erase-buffer -Delete the entire contents of the current buffer. - -@item bufferp -Return @code{t} if its argument is a buffer; otherwise return @code{nil}. -@end table - -@node optional Exercise, , Second Buffer Related Review, More Complex -@section @code{optional} Argument Exercise - -Write an interactive function with an optional argument that tests -whether its argument, a number, is greater than or equal to, or else, -less than the value of @code{fill-column}, and tells you which, in a -message. However, if you do not pass an argument to the function, use -56 as a default value. - -@node Narrowing & Widening, car cdr & cons, More Complex, Top -@comment node-name, next, previous, up -@chapter Narrowing and Widening -@cindex Focusing attention (narrowing) -@cindex Narrowing -@cindex Widening - -Narrowing is a feature of Emacs that makes it possible for you to focus -on a specific part of a buffer, and work without accidentally changing -other parts. Narrowing is normally disabled since it can confuse -novices. - -@menu -* Narrowing advantages:: The advantages of narrowing -* save-restriction:: The @code{save-restriction} special form. -* what-line:: The number of the line that point is on. -* narrow Exercise:: -@end menu - -@node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening -@ifnottex -@unnumberedsec The Advantages of Narrowing -@end ifnottex - -With narrowing, the rest of a buffer is made invisible, as if it weren't -there. This is an advantage if, for example, you want to replace a word -in one part of a buffer but not in another: you narrow to the part you want -and the replacement is carried out only in that section, not in the rest -of the buffer. Searches will only work within a narrowed region, not -outside of one, so if you are fixing a part of a document, you can keep -yourself from accidentally finding parts you do not need to fix by -narrowing just to the region you want. -(The key binding for @code{narrow-to-region} is @kbd{C-x n n}.) - -However, narrowing does make the rest of the buffer invisible, which -can scare people who inadvertently invoke narrowing and think they -have deleted a part of their file. Moreover, the @code{undo} command -(which is usually bound to @kbd{C-x u}) does not turn off narrowing -(nor should it), so people can become quite desperate if they do not -know that they can return the rest of a buffer to visibility with the -@code{widen} command. -(The key binding for @code{widen} is @kbd{C-x n w}.) - -Narrowing is just as useful to the Lisp interpreter as to a human. -Often, an Emacs Lisp function is designed to work on just part of a -buffer; or conversely, an Emacs Lisp function needs to work on all of a -buffer that has been narrowed. The @code{what-line} function, for -example, removes the narrowing from a buffer, if it has any narrowing -and when it has finished its job, restores the narrowing to what it was. -On the other hand, the @code{count-lines} function, which is called by -@code{what-line}, uses narrowing to restrict itself to just that portion -of the buffer in which it is interested and then restores the previous -situation. - -@node save-restriction, what-line, Narrowing advantages, Narrowing & Widening -@comment node-name, next, previous, up -@section The @code{save-restriction} Special Form -@findex save-restriction - -In Emacs Lisp, you can use the @code{save-restriction} special form to -keep track of whatever narrowing is in effect, if any. When the Lisp -interpreter meets with @code{save-restriction}, it executes the code -in the body of the @code{save-restriction} expression, and then undoes -any changes to narrowing that the code caused. If, for example, the -buffer is narrowed and the code that follows @code{save-restriction} -gets rid of the narrowing, @code{save-restriction} returns the buffer -to its narrowed region afterwards. In the @code{what-line} command, -any narrowing the buffer may have is undone by the @code{widen} -command that immediately follows the @code{save-restriction} command. -Any original narrowing is restored just before the completion of the -function. - -@need 1250 -The template for a @code{save-restriction} expression is simple: - -@smallexample -@group -(save-restriction - @var{body}@dots{} ) -@end group -@end smallexample - -@noindent -The body of the @code{save-restriction} is one or more expressions that -will be evaluated in sequence by the Lisp interpreter. - -Finally, a point to note: when you use both @code{save-excursion} and -@code{save-restriction}, one right after the other, you should use -@code{save-excursion} outermost. If you write them in reverse order, -you may fail to record narrowing in the buffer to which Emacs switches -after calling @code{save-excursion}. Thus, when written together, -@code{save-excursion} and @code{save-restriction} should be written -like this: - -@smallexample -@group -(save-excursion - (save-restriction - @var{body}@dots{})) -@end group -@end smallexample - -In other circumstances, when not written together, the -@code{save-excursion} and @code{save-restriction} special forms must -be written in the order appropriate to the function. - -@need 1250 -For example, - -@smallexample -@group - (save-restriction - (widen) - (save-excursion - @var{body}@dots{})) -@end group -@end smallexample - -@ignore -Emacs 22 -/usr/local/src/emacs/lisp/simple.el - -(defun what-line () - "Print the current buffer line number and narrowed line number of point." - (interactive) - (let ((start (point-min)) - (n (line-number-at-pos))) - (if (= start 1) - (message "Line %d" n) - (save-excursion - (save-restriction - (widen) - (message "line %d (narrowed line %d)" - (+ n (line-number-at-pos start) -1) n)))))) - -(defun line-number-at-pos (&optional pos) - "Return (narrowed) buffer line number at position POS. -If POS is nil, use current buffer location. -Counting starts at (point-min), so the value refers -to the contents of the accessible portion of the buffer." - (let ((opoint (or pos (point))) start) - (save-excursion - (goto-char (point-min)) - (setq start (point)) - (goto-char opoint) - (forward-line 0) - (1+ (count-lines start (point)))))) - -(defun count-lines (start end) - "Return number of lines between START and END. -This is usually the number of newlines between them, -but can be one more if START is not equal to END -and the greater of them is not at the start of a line." - (save-excursion - (save-restriction - (narrow-to-region start end) - (goto-char (point-min)) - (if (eq selective-display t) - (save-match-data - (let ((done 0)) - (while (re-search-forward "[\n\C-m]" nil t 40) - (setq done (+ 40 done))) - (while (re-search-forward "[\n\C-m]" nil t 1) - (setq done (+ 1 done))) - (goto-char (point-max)) - (if (and (/= start end) - (not (bolp))) - (1+ done) - done))) - (- (buffer-size) (forward-line (buffer-size))))))) -@end ignore - -@node what-line, narrow Exercise, save-restriction, Narrowing & Widening -@comment node-name, next, previous, up -@section @code{what-line} -@findex what-line -@cindex Widening, example of - -The @code{what-line} command tells you the number of the line in which -the cursor is located. The function illustrates the use of the -@code{save-restriction} and @code{save-excursion} commands. Here is the -original text of the function: - -@smallexample -@group -(defun what-line () - "Print the current line number (in the buffer) of point." - (interactive) - (save-restriction - (widen) - (save-excursion - (beginning-of-line) - (message "Line %d" - (1+ (count-lines 1 (point))))))) -@end group -@end smallexample - -(In recent versions of GNU Emacs, the @code{what-line} function has -been expanded to tell you your line number in a narrowed buffer as -well as your line number in a widened buffer. The recent version is -more complex than the version shown here. If you feel adventurous, -you might want to look at it after figuring out how this version -works. You will probably need to use @kbd{C-h f} -(@code{describe-function}). The newer version uses a conditional to -determine whether the buffer has been narrowed. - -(Also, it uses @code{line-number-at-pos}, which among other simple -expressions, such as @code{(goto-char (point-min))}, moves point to -the beginning of the current line with @code{(forward-line 0)} rather -than @code{beginning-of-line}.) - -The @code{what-line} function as shown here has a documentation line -and is interactive, as you would expect. The next two lines use the -functions @code{save-restriction} and @code{widen}. - -The @code{save-restriction} special form notes whatever narrowing is in -effect, if any, in the current buffer and restores that narrowing after -the code in the body of the @code{save-restriction} has been evaluated. - -The @code{save-restriction} special form is followed by @code{widen}. -This function undoes any narrowing the current buffer may have had -when @code{what-line} was called. (The narrowing that was there is -the narrowing that @code{save-restriction} remembers.) This widening -makes it possible for the line counting commands to count from the -beginning of the buffer. Otherwise, they would have been limited to -counting within the accessible region. Any original narrowing is -restored just before the completion of the function by the -@code{save-restriction} special form. - -The call to @code{widen} is followed by @code{save-excursion}, which -saves the location of the cursor (i.e., of point) and of the mark, and -restores them after the code in the body of the @code{save-excursion} -uses the @code{beginning-of-line} function to move point. - -(Note that the @code{(widen)} expression comes between the -@code{save-restriction} and @code{save-excursion} special forms. When -you write the two @code{save- @dots{}} expressions in sequence, write -@code{save-excursion} outermost.) - -@need 1200 -The last two lines of the @code{what-line} function are functions to -count the number of lines in the buffer and then print the number in the -echo area. - -@smallexample -@group -(message "Line %d" - (1+ (count-lines 1 (point))))))) -@end group -@end smallexample - -The @code{message} function prints a one-line message at the bottom of -the Emacs screen. The first argument is inside of quotation marks and -is printed as a string of characters. However, it may contain a -@samp{%d} expression to print a following argument. @samp{%d} prints -the argument as a decimal, so the message will say something such as -@samp{Line 243}. - -@need 1200 -The number that is printed in place of the @samp{%d} is computed by the -last line of the function: - -@smallexample -(1+ (count-lines 1 (point))) -@end smallexample - -@ignore -GNU Emacs 22 - -(defun count-lines (start end) - "Return number of lines between START and END. -This is usually the number of newlines between them, -but can be one more if START is not equal to END -and the greater of them is not at the start of a line." - (save-excursion - (save-restriction - (narrow-to-region start end) - (goto-char (point-min)) - (if (eq selective-display t) - (save-match-data - (let ((done 0)) - (while (re-search-forward "[\n\C-m]" nil t 40) - (setq done (+ 40 done))) - (while (re-search-forward "[\n\C-m]" nil t 1) - (setq done (+ 1 done))) - (goto-char (point-max)) - (if (and (/= start end) - (not (bolp))) - (1+ done) - done))) - (- (buffer-size) (forward-line (buffer-size))))))) -@end ignore - -@noindent -What this does is count the lines from the first position of the -buffer, indicated by the @code{1}, up to @code{(point)}, and then add -one to that number. (The @code{1+} function adds one to its -argument.) We add one to it because line 2 has only one line before -it, and @code{count-lines} counts only the lines @emph{before} the -current line. - -After @code{count-lines} has done its job, and the message has been -printed in the echo area, the @code{save-excursion} restores point and -mark to their original positions; and @code{save-restriction} restores -the original narrowing, if any. - -@node narrow Exercise, , what-line, Narrowing & Widening -@section Exercise with Narrowing - -Write a function that will display the first 60 characters of the -current buffer, even if you have narrowed the buffer to its latter -half so that the first line is inaccessible. Restore point, mark, and -narrowing. For this exercise, you need to use a whole potpourri of -functions, including @code{save-restriction}, @code{widen}, -@code{goto-char}, @code{point-min}, @code{message}, and -@code{buffer-substring}. - -@cindex Properties, mention of @code{buffer-substring-no-properties} -(@code{buffer-substring} is a previously unmentioned function you will -have to investigate yourself; or perhaps you will have to use -@code{buffer-substring-no-properties} or -@code{filter-buffer-substring} @dots{}, yet other functions. Text -properties are a feature otherwise not discussed here. @xref{Text -Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference -Manual}.) - -Additionally, do you really need @code{goto-char} or @code{point-min}? -Or can you write the function without them? - -@node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top -@comment node-name, next, previous, up -@chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions -@findex car, @r{introduced} -@findex cdr, @r{introduced} - -In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental -functions. The @code{cons} function is used to construct lists, and -the @code{car} and @code{cdr} functions are used to take them apart. - -In the walk through of the @code{copy-region-as-kill} function, we -will see @code{cons} as well as two variants on @code{cdr}, -namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.) - -@menu -* Strange Names:: An historical aside: why the strange names? -* car & cdr:: Functions for extracting part of a list. -* cons:: Constructing a list. -* nthcdr:: Calling @code{cdr} repeatedly. -* nth:: -* setcar:: Changing the first element of a list. -* setcdr:: Changing the rest of a list. -* cons Exercise:: -@end menu - -@node Strange Names, car & cdr, car cdr & cons, car cdr & cons -@ifnottex -@unnumberedsec Strange Names -@end ifnottex - -The name of the @code{cons} function is not unreasonable: it is an -abbreviation of the word `construct'. The origins of the names for -@code{car} and @code{cdr}, on the other hand, are esoteric: @code{car} -is an acronym from the phrase `Contents of the Address part of the -Register'; and @code{cdr} (pronounced `could-er') is an acronym from -the phrase `Contents of the Decrement part of the Register'. These -phrases refer to specific pieces of hardware on the very early -computer on which the original Lisp was developed. Besides being -obsolete, the phrases have been completely irrelevant for more than 25 -years to anyone thinking about Lisp. Nonetheless, although a few -brave scholars have begun to use more reasonable names for these -functions, the old terms are still in use. In particular, since the -terms are used in the Emacs Lisp source code, we will use them in this -introduction. - -@node car & cdr, cons, Strange Names, car cdr & cons -@comment node-name, next, previous, up -@section @code{car} and @code{cdr} - -The @sc{car} of a list is, quite simply, the first item in the list. -Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is -@code{rose}. - -@need 1200 -If you are reading this in Info in GNU Emacs, you can see this by -evaluating the following: - -@smallexample -(car '(rose violet daisy buttercup)) -@end smallexample - -@noindent -After evaluating the expression, @code{rose} will appear in the echo -area. - -Clearly, a more reasonable name for the @code{car} function would be -@code{first} and this is often suggested. - -@code{car} does not remove the first item from the list; it only reports -what it is. After @code{car} has been applied to a list, the list is -still the same as it was. In the jargon, @code{car} is -`non-destructive'. This feature turns out to be important. - -The @sc{cdr} of a list is the rest of the list, that is, the -@code{cdr} function returns the part of the list that follows the -first item. Thus, while the @sc{car} of the list @code{'(rose violet -daisy buttercup)} is @code{rose}, the rest of the list, the value -returned by the @code{cdr} function, is @code{(violet daisy -buttercup)}. - -@need 800 -You can see this by evaluating the following in the usual way: - -@smallexample -(cdr '(rose violet daisy buttercup)) -@end smallexample - -@noindent -When you evaluate this, @code{(violet daisy buttercup)} will appear in -the echo area. - -Like @code{car}, @code{cdr} does not remove any elements from the -list---it just returns a report of what the second and subsequent -elements are. - -Incidentally, in the example, the list of flowers is quoted. If it were -not, the Lisp interpreter would try to evaluate the list by calling -@code{rose} as a function. In this example, we do not want to do that. - -Clearly, a more reasonable name for @code{cdr} would be @code{rest}. - -(There is a lesson here: when you name new functions, consider very -carefully what you are doing, since you may be stuck with the names -for far longer than you expect. The reason this document perpetuates -these names is that the Emacs Lisp source code uses them, and if I did -not use them, you would have a hard time reading the code; but do, -please, try to avoid using these terms yourself. The people who come -after you will be grateful to you.) - -When @code{car} and @code{cdr} are applied to a list made up of symbols, -such as the list @code{(pine fir oak maple)}, the element of the list -returned by the function @code{car} is the symbol @code{pine} without -any parentheses around it. @code{pine} is the first element in the -list. However, the @sc{cdr} of the list is a list itself, @code{(fir -oak maple)}, as you can see by evaluating the following expressions in -the usual way: - -@smallexample -@group -(car '(pine fir oak maple)) - -(cdr '(pine fir oak maple)) -@end group -@end smallexample - -On the other hand, in a list of lists, the first element is itself a -list. @code{car} returns this first element as a list. For example, -the following list contains three sub-lists, a list of carnivores, a -list of herbivores and a list of sea mammals: - -@smallexample -@group -(car '((lion tiger cheetah) - (gazelle antelope zebra) - (whale dolphin seal))) -@end group -@end smallexample - -@noindent -In this example, the first element or @sc{car} of the list is the list of -carnivores, @code{(lion tiger cheetah)}, and the rest of the list is -@code{((gazelle antelope zebra) (whale dolphin seal))}. - -@smallexample -@group -(cdr '((lion tiger cheetah) - (gazelle antelope zebra) - (whale dolphin seal))) -@end group -@end smallexample - -It is worth saying again that @code{car} and @code{cdr} are -non-destructive---that is, they do not modify or change lists to which -they are applied. This is very important for how they are used. - -Also, in the first chapter, in the discussion about atoms, I said that -in Lisp, ``certain kinds of atom, such as an array, can be separated -into parts; but the mechanism for doing this is different from the -mechanism for splitting a list. As far as Lisp is concerned, the -atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The -@code{car} and @code{cdr} functions are used for splitting lists and -are considered fundamental to Lisp. Since they cannot split or gain -access to the parts of an array, an array is considered an atom. -Conversely, the other fundamental function, @code{cons}, can put -together or construct a list, but not an array. (Arrays are handled -by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU -Emacs Lisp Reference Manual}.) - -@node cons, nthcdr, car & cdr, car cdr & cons -@comment node-name, next, previous, up -@section @code{cons} -@findex cons, @r{introduced} - -The @code{cons} function constructs lists; it is the inverse of -@code{car} and @code{cdr}. For example, @code{cons} can be used to make -a four element list from the three element list, @code{(fir oak maple)}: - -@smallexample -(cons 'pine '(fir oak maple)) -@end smallexample - -@need 800 -@noindent -After evaluating this list, you will see - -@smallexample -(pine fir oak maple) -@end smallexample - -@noindent -appear in the echo area. @code{cons} causes the creation of a new -list in which the element is followed by the elements of the original -list. - -We often say that `@code{cons} puts a new element at the beginning of -a list; it attaches or pushes elements onto the list', but this -phrasing can be misleading, since @code{cons} does not change an -existing list, but creates a new one. - -Like @code{car} and @code{cdr}, @code{cons} is non-destructive. - -@menu -* Build a list:: -* length:: How to find the length of a list. -@end menu - -@node Build a list, length, cons, cons -@ifnottex -@unnumberedsubsec Build a list -@end ifnottex - -@code{cons} must have a list to attach to.@footnote{Actually, you can -@code{cons} an element to an atom to produce a dotted pair. Dotted -pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted -Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You -cannot start from absolutely nothing. If you are building a list, you -need to provide at least an empty list at the beginning. Here is a -series of @code{cons} expressions that build up a list of flowers. If -you are reading this in Info in GNU Emacs, you can evaluate each of -the expressions in the usual way; the value is printed in this text -after @samp{@result{}}, which you may read as `evaluates to'. - -@smallexample -@group -(cons 'buttercup ()) - @result{} (buttercup) -@end group - -@group -(cons 'daisy '(buttercup)) - @result{} (daisy buttercup) -@end group - -@group -(cons 'violet '(daisy buttercup)) - @result{} (violet daisy buttercup) -@end group - -@group -(cons 'rose '(violet daisy buttercup)) - @result{} (rose violet daisy buttercup) -@end group -@end smallexample - -@noindent -In the first example, the empty list is shown as @code{()} and a list -made up of @code{buttercup} followed by the empty list is constructed. -As you can see, the empty list is not shown in the list that was -constructed. All that you see is @code{(buttercup)}. The empty list is -not counted as an element of a list because there is nothing in an empty -list. Generally speaking, an empty list is invisible. - -The second example, @code{(cons 'daisy '(buttercup))} constructs a new, -two element list by putting @code{daisy} in front of @code{buttercup}; -and the third example constructs a three element list by putting -@code{violet} in front of @code{daisy} and @code{buttercup}. - -@node length, , Build a list, cons -@comment node-name, next, previous, up -@subsection Find the Length of a List: @code{length} -@findex length - -You can find out how many elements there are in a list by using the Lisp -function @code{length}, as in the following examples: - -@smallexample -@group -(length '(buttercup)) - @result{} 1 -@end group - -@group -(length '(daisy buttercup)) - @result{} 2 -@end group - -@group -(length (cons 'violet '(daisy buttercup))) - @result{} 3 -@end group -@end smallexample - -@noindent -In the third example, the @code{cons} function is used to construct a -three element list which is then passed to the @code{length} function as -its argument. - -@need 1200 -We can also use @code{length} to count the number of elements in an -empty list: - -@smallexample -@group -(length ()) - @result{} 0 -@end group -@end smallexample - -@noindent -As you would expect, the number of elements in an empty list is zero. - -An interesting experiment is to find out what happens if you try to find -the length of no list at all; that is, if you try to call @code{length} -without giving it an argument, not even an empty list: - -@smallexample -(length ) -@end smallexample - -@need 800 -@noindent -What you see, if you evaluate this, is the error message - -@smallexample -Lisp error: (wrong-number-of-arguments length 0) -@end smallexample - -@noindent -This means that the function receives the wrong number of -arguments, zero, when it expects some other number of arguments. In -this case, one argument is expected, the argument being a list whose -length the function is measuring. (Note that @emph{one} list is -@emph{one} argument, even if the list has many elements inside it.) - -The part of the error message that says @samp{length} is the name of -the function. - -@ignore -@code{length} is still a subroutine, but you need C-h f to discover that. - -In an earlier version: - This is written with a special notation, @samp{# (length string) 0) - (if yank-handler - (put-text-property 0 (length string) - 'yank-handler yank-handler string)) - (if yank-handler - (signal 'args-out-of-range - (list string "yank-handler specified for empty string")))) -@end group -@group - (if (fboundp 'menu-bar-update-yank-menu) - (menu-bar-update-yank-menu string (and replace (car kill-ring)))) -@end group -@group - (if (and replace kill-ring) - (setcar kill-ring string) - (push string kill-ring) - (if (> (length kill-ring) kill-ring-max) - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) -@end group -@group - (setq kill-ring-yank-pointer kill-ring) - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end group -@end smallexample -@ignore -was: -(defun kill-new (string &optional replace) - "Make STRING the latest kill in the kill ring. -Set the kill-ring-yank pointer to point to it. -If `interprogram-cut-function' is non-nil, apply it to STRING. -Optional second argument REPLACE non-nil means that STRING will replace -the front of the kill ring, rather than being added to the list." - (and (fboundp 'menu-bar-update-yank-menu) - (menu-bar-update-yank-menu string (and replace (car kill-ring)))) - (if (and replace kill-ring) - (setcar kill-ring string) - (setq kill-ring (cons string kill-ring)) - (if (> (length kill-ring) kill-ring-max) - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) - (setq kill-ring-yank-pointer kill-ring) - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end ignore - -(Notice that the function is not interactive.) - -As usual, we can look at this function in parts. - -The function definition has an optional @code{yank-handler} argument, -which when invoked tells the function how to deal with properties -added to the text, such as `bold' or `italics'. We will skip that. - -@need 1200 -The first line of the documentation makes sense: - -@smallexample -Make STRING the latest kill in the kill ring. -@end smallexample - -@noindent -Let's skip over the rest of the documentation for the moment. - -@noindent -Also, let's skip over the initial @code{if} expression and those lines -of code involving @code{menu-bar-update-yank-menu}. We will explain -them below. - -@need 1200 -The critical lines are these: - -@smallexample -@group - (if (and replace kill-ring) - ;; @r{then} - (setcar kill-ring string) -@end group -@group - ;; @r{else} - (push string kill-ring) -@end group -@group - (setq kill-ring (cons string kill-ring)) - (if (> (length kill-ring) kill-ring-max) - ;; @r{avoid overly long kill ring} - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) -@end group -@group - (setq kill-ring-yank-pointer kill-ring) - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end group -@end smallexample - -The conditional test is @w{@code{(and replace kill-ring)}}. -This will be true when two conditions are met: the kill ring has -something in it, and the @code{replace} variable is true. - -@need 1250 -When the @code{kill-append} function sets @code{replace} to be true -and when the kill ring has at least one item in it, the @code{setcar} -expression is executed: - -@smallexample -(setcar kill-ring string) -@end smallexample - -The @code{setcar} function actually changes the first element of the -@code{kill-ring} list to the value of @code{string}. It replaces the -first element. - -@need 1250 -On the other hand, if the kill ring is empty, or replace is false, the -else-part of the condition is executed: - -@smallexample -(push string kill-ring) -@end smallexample - -@noindent -@need 1250 -@code{push} puts its first argument onto the second. It is similar to -the older - -@smallexample -(setq kill-ring (cons string kill-ring)) -@end smallexample - -@noindent -@need 1250 -or the newer - -@smallexample -(add-to-list kill-ring string) -@end smallexample - -@noindent -When it is false, the expression first constructs a new version of the -kill ring by prepending @code{string} to the existing kill ring as a -new element (that is what the @code{push} does). Then it executes a -second @code{if} clause. This second @code{if} clause keeps the kill -ring from growing too long. - -Let's look at these two expressions in order. - -The @code{push} line of the else-part sets the new value of the kill -ring to what results from adding the string being killed to the old -kill ring. - -We can see how this works with an example. - -@need 800 -First, - -@smallexample -(setq example-list '("here is a clause" "another clause")) -@end smallexample - -@need 1200 -@noindent -After evaluating this expression with @kbd{C-x C-e}, you can evaluate -@code{example-list} and see what it returns: - -@smallexample -@group -example-list - @result{} ("here is a clause" "another clause") -@end group -@end smallexample - -@need 1200 -@noindent -Now, we can add a new element on to this list by evaluating the -following expression: -@findex push, @r{example} - -@smallexample -(push "a third clause" example-list) -@end smallexample - -@need 800 -@noindent -When we evaluate @code{example-list}, we find its value is: - -@smallexample -@group -example-list - @result{} ("a third clause" "here is a clause" "another clause") -@end group -@end smallexample - -@noindent -Thus, the third clause is added to the list by @code{push}. - -@need 1200 -Now for the second part of the @code{if} clause. This expression -keeps the kill ring from growing too long. It looks like this: - -@smallexample -@group -(if (> (length kill-ring) kill-ring-max) - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)) -@end group -@end smallexample - -The code checks whether the length of the kill ring is greater than -the maximum permitted length. This is the value of -@code{kill-ring-max} (which is 60, by default). If the length of the -kill ring is too long, then this code sets the last element of the -kill ring to @code{nil}. It does this by using two functions, -@code{nthcdr} and @code{setcdr}. - -We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}). -It sets the @sc{cdr} of a list, just as @code{setcar} sets the -@sc{car} of a list. In this case, however, @code{setcdr} will not be -setting the @sc{cdr} of the whole kill ring; the @code{nthcdr} -function is used to cause it to set the @sc{cdr} of the next to last -element of the kill ring---this means that since the @sc{cdr} of the -next to last element is the last element of the kill ring, it will set -the last element of the kill ring. - -@findex nthcdr, @r{example} -The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a -list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr} -@dots{} It does this @var{N} times and returns the results. -(@xref{nthcdr, , @code{nthcdr}}.) - -@findex setcdr, @r{example} -Thus, if we had a four element list that was supposed to be three -elements long, we could set the @sc{cdr} of the next to last element -to @code{nil}, and thereby shorten the list. (If you set the last -element to some other value than @code{nil}, which you could do, then -you would not have shortened the list. @xref{setcdr, , -@code{setcdr}}.) - -You can see shortening by evaluating the following three expressions -in turn. First set the value of @code{trees} to @code{(maple oak pine -birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil} -and then find the value of @code{trees}: - -@smallexample -@group -(setq trees '(maple oak pine birch)) - @result{} (maple oak pine birch) -@end group - -@group -(setcdr (nthcdr 2 trees) nil) - @result{} nil - -trees - @result{} (maple oak pine) -@end group -@end smallexample - -@noindent -(The value returned by the @code{setcdr} expression is @code{nil} since -that is what the @sc{cdr} is set to.) - -To repeat, in @code{kill-new}, the @code{nthcdr} function takes the -@sc{cdr} a number of times that is one less than the maximum permitted -size of the kill ring and @code{setcdr} sets the @sc{cdr} of that -element (which will be the rest of the elements in the kill ring) to -@code{nil}. This prevents the kill ring from growing too long. - -@need 800 -The next to last expression in the @code{kill-new} function is - -@smallexample -(setq kill-ring-yank-pointer kill-ring) -@end smallexample - -The @code{kill-ring-yank-pointer} is a global variable that is set to be -the @code{kill-ring}. - -Even though the @code{kill-ring-yank-pointer} is called a -@samp{pointer}, it is a variable just like the kill ring. However, the -name has been chosen to help humans understand how the variable is used. - -@need 1200 -Now, to return to an early expression in the body of the function: - -@smallexample -@group - (if (fboundp 'menu-bar-update-yank-menu) - (menu-bar-update-yank-menu string (and replace (car kill-ring)))) -@end group -@end smallexample - -@noindent -It starts with an @code{if} expression - -In this case, the expression tests first to see whether -@code{menu-bar-update-yank-menu} exists as a function, and if so, -calls it. The @code{fboundp} function returns true if the symbol it -is testing has a function definition that `is not void'. If the -symbol's function definition were void, we would receive an error -message, as we did when we created errors intentionally (@pxref{Making -Errors, , Generate an Error Message}). - -@noindent -The then-part contains an expression whose first element is the -function @code{and}. - -@findex and -The @code{and} special form evaluates each of its arguments until one -of the arguments returns a value of @code{nil}, in which case the -@code{and} expression returns @code{nil}; however, if none of the -arguments returns a value of @code{nil}, the value resulting from -evaluating the last argument is returned. (Since such a value is not -@code{nil}, it is considered true in Emacs Lisp.) In other words, an -@code{and} expression returns a true value only if all its arguments -are true. (@xref{Second Buffer Related Review}.) - -The expression determines whether the second argument to -@code{menu-bar-update-yank-menu} is true or not. -@ignore - ;; If we're supposed to be extending an existing string, and that - ;; string really is at the front of the menu, then update it in place. -@end ignore - -@code{menu-bar-update-yank-menu} is one of the functions that make it -possible to use the `Select and Paste' menu in the Edit item of a menu -bar; using a mouse, you can look at the various pieces of text you -have saved and select one piece to paste. - -The last expression in the @code{kill-new} function adds the newly -copied string to whatever facility exists for copying and pasting -among different programs running in a windowing system. In the X -Windowing system, for example, the @code{x-select-text} function takes -the string and stores it in memory operated by X. You can paste the -string in another program, such as an Xterm. - -@need 1200 -The expression looks like this: - -@smallexample -@group - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end group -@end smallexample - -If an @code{interprogram-cut-function} exists, then Emacs executes -@code{funcall}, which in turn calls its first argument as a function -and passes the remaining arguments to it. (Incidentally, as far as I -can see, this @code{if} expression could be replaced by an @code{and} -expression similar to the one in the first part of the function.) - -We are not going to discuss windowing systems and other programs -further, but merely note that this is a mechanism that enables GNU -Emacs to work easily and well with other programs. - -This code for placing text in the kill ring, either concatenated with -an existing element or as a new element, leads us to the code for -bringing back text that has been cut out of the buffer---the yank -commands. However, before discussing the yank commands, it is better -to learn how lists are implemented in a computer. This will make -clear such mysteries as the use of the term `pointer'. But before -that, we will digress into C. - -@ignore -@c is this true in Emacs 22? Does not seems to be - - (If the @w{@code{(< end beg))}} -expression is true, @code{kill-append} prepends the string to the just -previously clipped text. For a detailed discussion, see -@ref{kill-append function, , The @code{kill-append} function}.) - -If you then yank back the text, i.e., `paste' it, you get both -pieces of text at once. That way, if you delete two words in a row, -and then yank them back, you get both words, in their proper order, -with one yank. (The @w{@code{(< end beg))}} expression makes sure the -order is correct.) - -On the other hand, if the previous command is not @code{kill-region}, -then the @code{kill-new} function is called, which adds the text to -the kill ring as the latest item, and sets the -@code{kill-ring-yank-pointer} variable to point to it. -@end ignore -@ignore - -@c Evidently, changed for Emacs 22. The zap-to-char command does not -@c use the delete-and-extract-region function - -2006 Oct 26, the Digression into C is now OK but should come after -copy-region-as-kill and filter-buffer-substring - -2006 Oct 24 -In Emacs 22, -copy-region-as-kill is short, 12 lines, and uses -filter-buffer-substring, which is longer, 39 lines -and has delete-and-extract-region in it. -delete-and-extract-region is written in C. - -see Initializing a Variable with @code{defvar} -@end ignore - -@node Digression into C, defvar, copy-region-as-kill, Cutting & Storing Text -@comment node-name, next, previous, up -@section Digression into C -@findex delete-and-extract-region -@cindex C, a digression into -@cindex Digression into C - -The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, , -@code{copy-region-as-kill}}) uses the @code{filter-buffer-substring} -function, which in turn uses the @code{delete-and-extract-region} -function. It removes the contents of a region and you cannot get them -back. - -Unlike the other code discussed here, the -@code{delete-and-extract-region} function is not written in Emacs -Lisp; it is written in C and is one of the primitives of the GNU Emacs -system. Since it is very simple, I will digress briefly from Lisp and -describe it here. - -@c GNU Emacs 22 in /usr/local/src/emacs/src/editfns.c -@c the DEFUN for buffer-substring-no-properties - -@need 1500 -Like many of the other Emacs primitives, -@code{delete-and-extract-region} is written as an instance of a C -macro, a macro being a template for code. The complete macro looks -like this: - -@smallexample -@group -DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties, - Sbuffer_substring_no_properties, 2, 2, 0, - doc: /* Return the characters of part of the buffer, -without the text properties. -The two arguments START and END are character positions; -they can be in either order. */) - (start, end) - Lisp_Object start, end; -@{ - register int b, e; - - validate_region (&start, &end); - b = XINT (start); - e = XINT (end); - - return make_buffer_string (b, e, 0); -@} -@end group -@end smallexample - -Without going into the details of the macro writing process, let me -point out that this macro starts with the word @code{DEFUN}. The word -@code{DEFUN} was chosen since the code serves the same purpose as -@code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in -@file{emacs/src/lisp.h}.) - -The word @code{DEFUN} is followed by seven parts inside of -parentheses: - -@itemize @bullet -@item -The first part is the name given to the function in Lisp, -@code{delete-and-extract-region}. - -@item -The second part is the name of the function in C, -@code{Fdelete_and_extract_region}. By convention, it starts with -@samp{F}. Since C does not use hyphens in names, underscores are used -instead. - -@item -The third part is the name for the C constant structure that records -information on this function for internal use. It is the name of the -function in C but begins with an @samp{S} instead of an @samp{F}. - -@item -The fourth and fifth parts specify the minimum and maximum number of -arguments the function can have. This function demands exactly 2 -arguments. - -@item -The sixth part is nearly like the argument that follows the -@code{interactive} declaration in a function written in Lisp: a letter -followed, perhaps, by a prompt. The only difference from the Lisp is -when the macro is called with no arguments. Then you write a @code{0} -(which is a `null string'), as in this macro. - -If you were to specify arguments, you would place them between -quotation marks. The C macro for @code{goto-char} includes -@code{"NGoto char: "} in this position to indicate that the function -expects a raw prefix, in this case, a numerical location in a buffer, -and provides a prompt. - -@item -The seventh part is a documentation string, just like the one for a -function written in Emacs Lisp, except that every newline must be -written explicitly as @samp{\n} followed by a backslash and carriage -return. - -@need 1000 -Thus, the first two lines of documentation for @code{goto-char} are -written like this: - -@smallexample -@group - "Set point to POSITION, a number or marker.\n\ -Beginning of buffer is position (point-min), end is (point-max)." -@end group -@end smallexample -@end itemize - -@need 1200 -In a C macro, the formal parameters come next, with a statement of -what kind of object they are, followed by what might be called the `body' -of the macro. For @code{delete-and-extract-region} the `body' -consists of the following four lines: - -@smallexample -@group -validate_region (&start, &end); -if (XINT (start) == XINT (end)) - return build_string (""); -return del_range_1 (XINT (start), XINT (end), 1, 1); -@end group -@end smallexample - -The @code{validate_region} function checks whether the values -passed as the beginning and end of the region are the proper type and -are within range. If the beginning and end positions are the same, -then return and empty string. - -The @code{del_range_1} function actually deletes the text. It is a -complex function we will not look into. It updates the buffer and -does other things. However, it is worth looking at the two arguments -passed to @code{del_range}. These are @w{@code{XINT (start)}} and -@w{@code{XINT (end)}}. - -As far as the C language is concerned, @code{start} and @code{end} are -two integers that mark the beginning and end of the region to be -deleted@footnote{More precisely, and requiring more expert knowledge -to understand, the two integers are of type `Lisp_Object', which can -also be a C union instead of an integer type.}. - -In early versions of Emacs, these two numbers were thirty-two bits -long, but the code is slowly being generalized to handle other -lengths. Three of the available bits are used to specify the type of -information; the remaining bits are used as `content'. - -@samp{XINT} is a C macro that extracts the relevant number from the -longer collection of bits; the three other bits are discarded. - -@need 800 -The command in @code{delete-and-extract-region} looks like this: - -@smallexample -del_range_1 (XINT (start), XINT (end), 1, 1); -@end smallexample - -@noindent -It deletes the region between the beginning position, @code{start}, -and the ending position, @code{end}. - -From the point of view of the person writing Lisp, Emacs is all very -simple; but hidden underneath is a great deal of complexity to make it -all work. - -@node defvar, cons & search-fwd Review, Digression into C, Cutting & Storing Text -@comment node-name, next, previous, up -@section Initializing a Variable with @code{defvar} -@findex defvar -@cindex Initializing a variable -@cindex Variable initialization - -@ignore -2006 Oct 24 -In Emacs 22, -copy-region-as-kill is short, 12 lines, and uses -filter-buffer-substring, which is longer, 39 lines -and has delete-and-extract-region in it. -delete-and-extract-region is written in C. - -see Initializing a Variable with @code{defvar} - -@end ignore - -The @code{copy-region-as-kill} function is written in Emacs Lisp. Two -functions within it, @code{kill-append} and @code{kill-new}, copy a -region in a buffer and save it in a variable called the -@code{kill-ring}. This section describes how the @code{kill-ring} -variable is created and initialized using the @code{defvar} special -form. - -(Again we note that the term @code{kill-ring} is a misnomer. The text -that is clipped out of the buffer can be brought back; it is not a ring -of corpses, but a ring of resurrectable text.) - -In Emacs Lisp, a variable such as the @code{kill-ring} is created and -given an initial value by using the @code{defvar} special form. The -name comes from ``define variable''. - -The @code{defvar} special form is similar to @code{setq} in that it sets -the value of a variable. It is unlike @code{setq} in two ways: first, -it only sets the value of the variable if the variable does not already -have a value. If the variable already has a value, @code{defvar} does -not override the existing value. Second, @code{defvar} has a -documentation string. - -(Another special form, @code{defcustom}, is designed for variables -that people customize. It has more features than @code{defvar}. -(@xref{defcustom, , Setting Variables with @code{defcustom}}.) - -@menu -* See variable current value:: -* defvar and asterisk:: -@end menu - -@node See variable current value, defvar and asterisk, defvar, defvar -@ifnottex -@unnumberedsubsec Seeing the Current Value of a Variable -@end ifnottex - -You can see the current value of a variable, any variable, by using -the @code{describe-variable} function, which is usually invoked by -typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring} -(followed by @key{RET}) when prompted, you will see what is in your -current kill ring---this may be quite a lot! Conversely, if you have -been doing nothing this Emacs session except read this document, you -may have nothing in it. Also, you will see the documentation for -@code{kill-ring}: - -@smallexample -@group -Documentation: -List of killed text sequences. -Since the kill ring is supposed to interact nicely with cut-and-paste -facilities offered by window systems, use of this variable should -@end group -@group -interact nicely with `interprogram-cut-function' and -`interprogram-paste-function'. The functions `kill-new', -`kill-append', and `current-kill' are supposed to implement this -interaction; you may want to use them instead of manipulating the kill -ring directly. -@end group -@end smallexample - -@need 800 -The kill ring is defined by a @code{defvar} in the following way: - -@smallexample -@group -(defvar kill-ring nil - "List of killed text sequences. -@dots{}") -@end group -@end smallexample - -@noindent -In this variable definition, the variable is given an initial value of -@code{nil}, which makes sense, since if you have saved nothing, you want -nothing back if you give a @code{yank} command. The documentation -string is written just like the documentation string of a @code{defun}. -As with the documentation string of the @code{defun}, the first line of -the documentation should be a complete sentence, since some commands, -like @code{apropos}, print only the first line of documentation. -Succeeding lines should not be indented; otherwise they look odd when -you use @kbd{C-h v} (@code{describe-variable}). - -@node defvar and asterisk, , See variable current value, defvar -@subsection @code{defvar} and an asterisk -@findex defvar @r{for a user customizable variable} -@findex defvar @r{with an asterisk} - -In the past, Emacs used the @code{defvar} special form both for -internal variables that you would not expect a user to change and for -variables that you do expect a user to change. Although you can still -use @code{defvar} for user customizable variables, please use -@code{defcustom} instead, since that special form provides a path into -the Customization commands. (@xref{defcustom, , Specifying Variables -using @code{defcustom}}.) - -When you specified a variable using the @code{defvar} special form, -you could distinguish a variable that a user might want to change from -others by typing an asterisk, @samp{*}, in the first column of its -documentation string. For example: - -@smallexample -@group -(defvar shell-command-default-error-buffer nil - "*Buffer name for `shell-command' @dots{} error output. -@dots{} ") -@end group -@end smallexample - -@findex set-variable -@noindent -You could (and still can) use the @code{set-variable} command to -change the value of @code{shell-command-default-error-buffer} -temporarily. However, options set using @code{set-variable} are set -only for the duration of your editing session. The new values are not -saved between sessions. Each time Emacs starts, it reads the original -value, unless you change the value within your @file{.emacs} file, -either by setting it manually or by using @code{customize}. -@xref{Emacs Initialization, , Your @file{.emacs} File}. - -For me, the major use of the @code{set-variable} command is to suggest -variables that I might want to set in my @file{.emacs} file. There -are now more than 700 such variables --- far too many to remember -readily. Fortunately, you can press @key{TAB} after calling the -@code{M-x set-variable} command to see the list of variables. -(@xref{Examining, , Examining and Setting Variables, emacs, -The GNU Emacs Manual}.) - -@need 1250 -@node cons & search-fwd Review, search Exercises, defvar, Cutting & Storing Text -@comment node-name, next, previous, up -@section Review - -Here is a brief summary of some recently introduced functions. - -@table @code -@item car -@itemx cdr -@code{car} returns the first element of a list; @code{cdr} returns the -second and subsequent elements of a list. - -@need 1250 -For example: - -@smallexample -@group -(car '(1 2 3 4 5 6 7)) - @result{} 1 -(cdr '(1 2 3 4 5 6 7)) - @result{} (2 3 4 5 6 7) -@end group -@end smallexample - -@item cons -@code{cons} constructs a list by prepending its first argument to its -second argument. - -@need 1250 -For example: - -@smallexample -@group -(cons 1 '(2 3 4)) - @result{} (1 2 3 4) -@end group -@end smallexample - -@item funcall -@code{funcall} evaluates its first argument as a function. It passes -its remaining arguments to its first argument. - -@item nthcdr -Return the result of taking @sc{cdr} `n' times on a list. -@iftex -The -@tex -$n^{th}$ -@end tex -@code{cdr}. -@end iftex -The `rest of the rest', as it were. - -@need 1250 -For example: - -@smallexample -@group -(nthcdr 3 '(1 2 3 4 5 6 7)) - @result{} (4 5 6 7) -@end group -@end smallexample - -@item setcar -@itemx setcdr -@code{setcar} changes the first element of a list; @code{setcdr} -changes the second and subsequent elements of a list. - -@need 1250 -For example: - -@smallexample -@group -(setq triple '(1 2 3)) - -(setcar triple '37) - -triple - @result{} (37 2 3) - -(setcdr triple '("foo" "bar")) - -triple - @result{} (37 "foo" "bar") -@end group -@end smallexample - -@item progn -Evaluate each argument in sequence and then return the value of the -last. - -@need 1250 -For example: - -@smallexample -@group -(progn 1 2 3 4) - @result{} 4 -@end group -@end smallexample - -@item save-restriction -Record whatever narrowing is in effect in the current buffer, if any, -and restore that narrowing after evaluating the arguments. - -@item search-forward -Search for a string, and if the string is found, move point. With a -regular expression, use the similar @code{re-search-forward}. -(@xref{Regexp Search, , Regular Expression Searches}, for an -explanation of regular expression patterns and searches.) - -@need 1250 -@noindent -@code{search-forward} and @code{re-search-forward} take four -arguments: - -@enumerate -@item -The string or regular expression to search for. - -@item -Optionally, the limit of the search. - -@item -Optionally, what to do if the search fails, return @code{nil} or an -error message. - -@item -Optionally, how many times to repeat the search; if negative, the -search goes backwards. -@end enumerate - -@item kill-region -@itemx delete-and-extract-region -@itemx copy-region-as-kill - -@code{kill-region} cuts the text between point and mark from the -buffer and stores that text in the kill ring, so you can get it back -by yanking. - -@code{copy-region-as-kill} copies the text between point and mark into -the kill ring, from which you can get it by yanking. The function -does not cut or remove the text from the buffer. -@end table - -@code{delete-and-extract-region} removes the text between point and -mark from the buffer and throws it away. You cannot get it back. -(This is not an interactive command.) - -@need 1500 -@node search Exercises, , cons & search-fwd Review, Cutting & Storing Text -@section Searching Exercises - -@itemize @bullet -@item -Write an interactive function that searches for a string. If the -search finds the string, leave point after it and display a message -that says ``Found!''. (Do not use @code{search-forward} for the name -of this function; if you do, you will overwrite the existing version of -@code{search-forward} that comes with Emacs. Use a name such as -@code{test-search} instead.) - -@item -Write a function that prints the third element of the kill ring in the -echo area, if any; if the kill ring does not contain a third element, -print an appropriate message. -@end itemize - -@node List Implementation, Yanking, Cutting & Storing Text, Top -@comment node-name, next, previous, up -@chapter How Lists are Implemented -@cindex Lists in a computer - -In Lisp, atoms are recorded in a straightforward fashion; if the -implementation is not straightforward in practice, it is, nonetheless, -straightforward in theory. The atom @samp{rose}, for example, is -recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s}, -@samp{e}. A list, on the other hand, is kept differently. The mechanism -is equally simple, but it takes a moment to get used to the idea. A -list is kept using a series of pairs of pointers. In the series, the -first pointer in each pair points to an atom or to another list, and the -second pointer in each pair points to the next pair, or to the symbol -@code{nil}, which marks the end of the list. - -A pointer itself is quite simply the electronic address of what is -pointed to. Hence, a list is kept as a series of electronic addresses. - -@menu -* Lists diagrammed:: -* Symbols as Chest:: Exploring a powerful metaphor. -* List Exercise:: -@end menu - -@node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation -@ifnottex -@unnumberedsec Lists diagrammed -@end ifnottex - -For example, the list @code{(rose violet buttercup)} has three elements, -@samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the -electronic address of @samp{rose} is recorded in a segment of computer -memory along with the address that gives the electronic address of where -the atom @samp{violet} is located; and that address (the one that tells -where @samp{violet} is located) is kept along with an address that tells -where the address for the atom @samp{buttercup} is located. - -@need 1200 -This sounds more complicated than it is and is easier seen in a diagram: - -@c clear print-postscript-figures -@c !!! cons-cell-diagram #1 -@ifnottex -@smallexample -@group - ___ ___ ___ ___ ___ ___ - |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-1} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group - ___ ___ ___ ___ ___ ___ - |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -In the diagram, each box represents a word of computer memory that -holds a Lisp object, usually in the form of a memory address. The boxes, -i.e.@: the addresses, are in pairs. Each arrow points to what the address -is the address of, either an atom or another pair of addresses. The -first box is the electronic address of @samp{rose} and the arrow points -to @samp{rose}; the second box is the address of the next pair of boxes, -the first part of which is the address of @samp{violet} and the second -part of which is the address of the next pair. The very last box -points to the symbol @code{nil}, which marks the end of the list. - -@need 1200 -When a variable is set to a list with a function such as @code{setq}, -it stores the address of the first box in the variable. Thus, -evaluation of the expression - -@smallexample -(setq bouquet '(rose violet buttercup)) -@end smallexample - -@need 1250 -@noindent -creates a situation like this: - -@c cons-cell-diagram #2 -@ifnottex -@smallexample -@group -bouquet - | - | ___ ___ ___ ___ ___ ___ - --> |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-2} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -bouquet - | - | ___ ___ ___ ___ ___ ___ - --> |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -In this example, the symbol @code{bouquet} holds the address of the first -pair of boxes. - -@need 1200 -This same list can be illustrated in a different sort of box notation -like this: - -@c cons-cell-diagram #2a -@ifnottex -@smallexample -@group -bouquet - | - | -------------- --------------- ---------------- - | | car | cdr | | car | cdr | | car | cdr | - -->| rose | o------->| violet | o------->| butter- | nil | - | | | | | | | cup | | - -------------- --------------- ---------------- -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-2a} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -bouquet - | - | -------------- --------------- ---------------- - | | car | cdr | | car | cdr | | car | cdr | - -->| rose | o------->| violet | o------->| butter- | nil | - | | | | | | | cup | | - -------------- --------------- ---------------- -@end group -@end smallexample -@end iftex -@end ifclear - -(Symbols consist of more than pairs of addresses, but the structure of -a symbol is made up of addresses. Indeed, the symbol @code{bouquet} -consists of a group of address-boxes, one of which is the address of -the printed word @samp{bouquet}, a second of which is the address of a -function definition attached to the symbol, if any, a third of which -is the address of the first pair of address-boxes for the list -@code{(rose violet buttercup)}, and so on. Here we are showing that -the symbol's third address-box points to the first pair of -address-boxes for the list.) - -If a symbol is set to the @sc{cdr} of a list, the list itself is not -changed; the symbol simply has an address further down the list. (In -the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus, -evaluation of the following expression - -@smallexample -(setq flowers (cdr bouquet)) -@end smallexample - -@need 800 -@noindent -produces this: - -@c cons-cell-diagram #3 -@ifnottex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ | ___ ___ ___ ___ - --> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-3} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ | ___ ___ ___ ___ - --> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -@noindent -The value of @code{flowers} is @code{(violet buttercup)}, which is -to say, the symbol @code{flowers} holds the address of the pair of -address-boxes, the first of which holds the address of @code{violet}, -and the second of which holds the address of @code{buttercup}. - -A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted -pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp -Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair -Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more -information about cons cells and dotted pairs. - -@need 1200 -The function @code{cons} adds a new pair of addresses to the front of -a series of addresses like that shown above. For example, evaluating -the expression - -@smallexample -(setq bouquet (cons 'lily bouquet)) -@end smallexample - -@need 1500 -@noindent -produces: - -@c cons-cell-diagram #4 -@ifnottex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ ___ ___ | ___ ___ ___ ___ - --> | | | | | | --> | | | | | | - |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil - | | | | - | | | | - --> lily --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-4} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ ___ ___ | ___ ___ ___ ___ - --> | | | | | | --> | | | | | | - |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil - | | | | - | | | | - --> lily --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -@need 1200 -@noindent -However, this does not change the value of the symbol -@code{flowers}, as you can see by evaluating the following, - -@smallexample -(eq (cdr (cdr bouquet)) flowers) -@end smallexample - -@noindent -which returns @code{t} for true. - -Until it is reset, @code{flowers} still has the value -@code{(violet buttercup)}; that is, it has the address of the cons -cell whose first address is of @code{violet}. Also, this does not -alter any of the pre-existing cons cells; they are all still there. - -Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address -of the next cons cell in the series; to get the @sc{car} of a list, -you get the address of the first element of the list; to @code{cons} a -new element on a list, you add a new cons cell to the front of the list. -That is all there is to it! The underlying structure of Lisp is -brilliantly simple! - -And what does the last address in a series of cons cells refer to? It -is the address of the empty list, of @code{nil}. - -In summary, when a Lisp variable is set to a value, it is provided with -the address of the list to which the variable refers. - -@node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation -@section Symbols as a Chest of Drawers -@cindex Symbols as a Chest of Drawers -@cindex Chest of Drawers, metaphor for a symbol -@cindex Drawers, Chest of, metaphor for a symbol - -In an earlier section, I suggested that you might imagine a symbol as -being a chest of drawers. The function definition is put in one -drawer, the value in another, and so on. What is put in the drawer -holding the value can be changed without affecting the contents of the -drawer holding the function definition, and vice-verse. - -Actually, what is put in each drawer is the address of the value or -function definition. It is as if you found an old chest in the attic, -and in one of its drawers you found a map giving you directions to -where the buried treasure lies. - -(In addition to its name, symbol definition, and variable value, a -symbol has a `drawer' for a @dfn{property list} which can be used to -record other information. Property lists are not discussed here; see -@ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp -Reference Manual}.) - -@need 1500 -Here is a fanciful representation: - -@c chest-of-drawers diagram -@ifnottex -@sp 1 -@smallexample -@group - Chest of Drawers Contents of Drawers - - __ o0O0o __ - / \ - --------------------- - | directions to | [map to] - | symbol name | bouquet - | | - +---------------------+ - | directions to | - | symbol definition | [none] - | | - +---------------------+ - | directions to | [map to] - | variable value | (rose violet buttercup) - | | - +---------------------+ - | directions to | - | property list | [not described here] - | | - +---------------------+ - |/ \| -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{drawers} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@sp 1 -@smallexample -@group - Chest of Drawers Contents of Drawers - - __ o0O0o __ - / \ - --------------------- - | directions to | [map to] - | symbol name | bouquet - | | - +---------------------+ - | directions to | - | symbol definition | [none] - | | - +---------------------+ - | directions to | [map to] - | variable value | (rose violet buttercup) - | | - +---------------------+ - | directions to | - | property list | [not described here] - | | - +---------------------+ - |/ \| -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -@node List Exercise, , Symbols as Chest, List Implementation -@section Exercise - -Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two -more flowers on to this list and set this new list to -@code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish. -What does the @code{more-flowers} list now contain? - -@node Yanking, Loops & Recursion, List Implementation, Top -@comment node-name, next, previous, up -@chapter Yanking Text Back -@findex yank -@cindex Text retrieval -@cindex Retrieving text -@cindex Pasting text - -Whenever you cut text out of a buffer with a `kill' command in GNU Emacs, -you can bring it back with a `yank' command. The text that is cut out of -the buffer is put in the kill ring and the yank commands insert the -appropriate contents of the kill ring back into a buffer (not necessarily -the original buffer). - -A simple @kbd{C-y} (@code{yank}) command inserts the first item from -the kill ring into the current buffer. If the @kbd{C-y} command is -followed immediately by @kbd{M-y}, the first element is replaced by -the second element. Successive @kbd{M-y} commands replace the second -element with the third, fourth, or fifth element, and so on. When the -last element in the kill ring is reached, it is replaced by the first -element and the cycle is repeated. (Thus the kill ring is called a -`ring' rather than just a `list'. However, the actual data structure -that holds the text is a list. -@xref{Kill Ring, , Handling the Kill Ring}, for the details of how the -list is handled as a ring.) - -@menu -* Kill Ring Overview:: -* kill-ring-yank-pointer:: The kill ring is a list. -* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. -@end menu - -@node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking -@comment node-name, next, previous, up -@section Kill Ring Overview -@cindex Kill ring overview - -The kill ring is a list of textual strings. This is what it looks like: - -@smallexample -("some text" "a different piece of text" "yet more text") -@end smallexample - -If this were the contents of my kill ring and I pressed @kbd{C-y}, the -string of characters saying @samp{some text} would be inserted in this -buffer where my cursor is located. - -The @code{yank} command is also used for duplicating text by copying it. -The copied text is not cut from the buffer, but a copy of it is put on the -kill ring and is inserted by yanking it back. - -Three functions are used for bringing text back from the kill ring: -@code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop}, -which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer}, -which is used by the two other functions. - -These functions refer to the kill ring through a variable called the -@code{kill-ring-yank-pointer}. Indeed, the insertion code for both the -@code{yank} and @code{yank-pop} functions is: - -@smallexample -(insert (car kill-ring-yank-pointer)) -@end smallexample - -@noindent -(Well, no more. In GNU Emacs 22, the function has been replaced by -@code{insert-for-yank} which calls @code{insert-for-yank-1} -repetitively for each @code{yank-handler} segment. In turn, -@code{insert-for-yank-1} strips text properties from the inserted text -according to @code{yank-excluded-properties}. Otherwise, it is just -like @code{insert}. We will stick with plain @code{insert} since it -is easier to understand.) - -To begin to understand how @code{yank} and @code{yank-pop} work, it is -first necessary to look at the @code{kill-ring-yank-pointer} variable. - -@node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking -@comment node-name, next, previous, up -@section The @code{kill-ring-yank-pointer} Variable - -@code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is -a variable. It points to something by being bound to the value of what -it points to, like any other Lisp variable. - -@need 1000 -Thus, if the value of the kill ring is: - -@smallexample -("some text" "a different piece of text" "yet more text") -@end smallexample - -@need 1250 -@noindent -and the @code{kill-ring-yank-pointer} points to the second clause, the -value of @code{kill-ring-yank-pointer} is: - -@smallexample -("a different piece of text" "yet more text") -@end smallexample - -As explained in the previous chapter (@pxref{List Implementation}), the -computer does not keep two different copies of the text being pointed to -by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The -words ``a different piece of text'' and ``yet more text'' are not -duplicated. Instead, the two Lisp variables point to the same pieces of -text. Here is a diagram: - -@c cons-cell-diagram #5 -@ifnottex -@smallexample -@group -kill-ring kill-ring-yank-pointer - | | - | ___ ___ | ___ ___ ___ ___ - ---> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - | | --> "yet more text" - | | - | --> "a different piece of text" - | - --> "some text" -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-5} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -kill-ring kill-ring-yank-pointer - | | - | ___ ___ | ___ ___ ___ ___ - ---> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - | | --> "yet more text" - | | - | --> "a different piece of text - | - --> "some text" -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -Both the variable @code{kill-ring} and the variable -@code{kill-ring-yank-pointer} are pointers. But the kill ring itself is -usually described as if it were actually what it is composed of. The -@code{kill-ring} is spoken of as if it were the list rather than that it -points to the list. Conversely, the @code{kill-ring-yank-pointer} is -spoken of as pointing to a list. - -These two ways of talking about the same thing sound confusing at first but -make sense on reflection. The kill ring is generally thought of as the -complete structure of data that holds the information of what has recently -been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer} -on the other hand, serves to indicate---that is, to `point to'---that part -of the kill ring of which the first element (the @sc{car}) will be -inserted. - -@ignore -In GNU Emacs 22, the @code{kill-new} function calls - -@code{(setq kill-ring-yank-pointer kill-ring)} - -(defun rotate-yank-pointer (arg) - "Rotate the yanking point in the kill ring. -With argument, rotate that many kills forward (or backward, if negative)." - (interactive "p") - (current-kill arg)) - -(defun current-kill (n &optional do-not-move) - "Rotate the yanking point by N places, and then return that kill. -If N is zero, `interprogram-paste-function' is set, and calling it -returns a string, then that string is added to the front of the -kill ring and returned as the latest kill. -If optional arg DO-NOT-MOVE is non-nil, then don't actually move the -yanking point; just return the Nth kill forward." - (let ((interprogram-paste (and (= n 0) - interprogram-paste-function - (funcall interprogram-paste-function)))) - (if interprogram-paste - (progn - ;; Disable the interprogram cut function when we add the new - ;; text to the kill ring, so Emacs doesn't try to own the - ;; selection, with identical text. - (let ((interprogram-cut-function nil)) - (kill-new interprogram-paste)) - interprogram-paste) - (or kill-ring (error "Kill ring is empty")) - (let ((ARGth-kill-element - (nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) - (car ARGth-kill-element))))) - -@end ignore - -@need 1500 -@node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking -@section Exercises with @code{yank} and @code{nthcdr} - -@itemize @bullet -@item -Using @kbd{C-h v} (@code{describe-variable}), look at the value of -your kill ring. Add several items to your kill ring; look at its -value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way -around the kill ring. How many items were in your kill ring? Find -the value of @code{kill-ring-max}. Was your kill ring full, or could -you have kept more blocks of text within it? - -@item -Using @code{nthcdr} and @code{car}, construct a series of expressions -to return the first, second, third, and fourth elements of a list. -@end itemize - -@node Loops & Recursion, Regexp Search, Yanking, Top -@comment node-name, next, previous, up -@chapter Loops and Recursion -@cindex Loops and recursion -@cindex Recursion and loops -@cindex Repetition (loops) - -Emacs Lisp has two primary ways to cause an expression, or a series of -expressions, to be evaluated repeatedly: one uses a @code{while} -loop, and the other uses @dfn{recursion}. - -Repetition can be very valuable. For example, to move forward four -sentences, you need only write a program that will move forward one -sentence and then repeat the process four times. Since a computer does -not get bored or tired, such repetitive action does not have the -deleterious effects that excessive or the wrong kinds of repetition can -have on humans. - -People mostly write Emacs Lisp functions using @code{while} loops and -their kin; but you can use recursion, which provides a very powerful -way to think about and then to solve problems@footnote{You can write -recursive functions to be frugal or wasteful of mental or computer -resources; as it happens, methods that people find easy---that are -frugal of `mental resources'---sometimes use considerable computer -resources. Emacs was designed to run on machines that we now consider -limited and its default settings are conservative. You may want to -increase the values of @code{max-specpdl-size} and -@code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to -15 and 30 times their default value.}. - -@menu -* while:: Causing a stretch of code to repeat. -* dolist dotimes:: -* Recursion:: Causing a function to call itself. -* Looping exercise:: -@end menu - -@node while, dolist dotimes, Loops & Recursion, Loops & Recursion -@comment node-name, next, previous, up -@section @code{while} -@cindex Loops -@findex while - -The @code{while} special form tests whether the value returned by -evaluating its first argument is true or false. This is similar to what -the Lisp interpreter does with an @code{if}; what the interpreter does -next, however, is different. - -In a @code{while} expression, if the value returned by evaluating the -first argument is false, the Lisp interpreter skips the rest of the -expression (the @dfn{body} of the expression) and does not evaluate it. -However, if the value is true, the Lisp interpreter evaluates the body -of the expression and then again tests whether the first argument to -@code{while} is true or false. If the value returned by evaluating the -first argument is again true, the Lisp interpreter again evaluates the -body of the expression. - -@need 1200 -The template for a @code{while} expression looks like this: - -@smallexample -@group -(while @var{true-or-false-test} - @var{body}@dots{}) -@end group -@end smallexample - -@menu -* Looping with while:: Repeat so long as test returns true. -* Loop Example:: A @code{while} loop that uses a list. -* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. -* Incrementing Loop:: A loop with an incrementing counter. -* Incrementing Loop Details:: -* Decrementing Loop:: A loop with a decrementing counter. -@end menu - -@node Looping with while, Loop Example, while, while -@ifnottex -@unnumberedsubsec Looping with @code{while} -@end ifnottex - -So long as the true-or-false-test of the @code{while} expression -returns a true value when it is evaluated, the body is repeatedly -evaluated. This process is called a loop since the Lisp interpreter -repeats the same thing again and again, like an airplane doing a loop. -When the result of evaluating the true-or-false-test is false, the -Lisp interpreter does not evaluate the rest of the @code{while} -expression and `exits the loop'. - -Clearly, if the value returned by evaluating the first argument to -@code{while} is always true, the body following will be evaluated -again and again @dots{} and again @dots{} forever. Conversely, if the -value returned is never true, the expressions in the body will never -be evaluated. The craft of writing a @code{while} loop consists of -choosing a mechanism such that the true-or-false-test returns true -just the number of times that you want the subsequent expressions to -be evaluated, and then have the test return false. - -The value returned by evaluating a @code{while} is the value of the -true-or-false-test. An interesting consequence of this is that a -@code{while} loop that evaluates without error will return @code{nil} -or false regardless of whether it has looped 1 or 100 times or none at -all. A @code{while} expression that evaluates successfully never -returns a true value! What this means is that @code{while} is always -evaluated for its side effects, which is to say, the consequences of -evaluating the expressions within the body of the @code{while} loop. -This makes sense. It is not the mere act of looping that is desired, -but the consequences of what happens when the expressions in the loop -are repeatedly evaluated. - -@node Loop Example, print-elements-of-list, Looping with while, while -@comment node-name, next, previous, up -@subsection A @code{while} Loop and a List - -A common way to control a @code{while} loop is to test whether a list -has any elements. If it does, the loop is repeated; but if it does not, -the repetition is ended. Since this is an important technique, we will -create a short example to illustrate it. - -A simple way to test whether a list has elements is to evaluate the -list: if it has no elements, it is an empty list and will return the -empty list, @code{()}, which is a synonym for @code{nil} or false. On -the other hand, a list with elements will return those elements when it -is evaluated. Since Emacs Lisp considers as true any value that is not -@code{nil}, a list that returns elements will test true in a -@code{while} loop. - -@need 1200 -For example, you can set the variable @code{empty-list} to @code{nil} by -evaluating the following @code{setq} expression: - -@smallexample -(setq empty-list ()) -@end smallexample - -@noindent -After evaluating the @code{setq} expression, you can evaluate the -variable @code{empty-list} in the usual way, by placing the cursor after -the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your -echo area: - -@smallexample -empty-list -@end smallexample - -On the other hand, if you set a variable to be a list with elements, the -list will appear when you evaluate the variable, as you can see by -evaluating the following two expressions: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -animals -@end group -@end smallexample - -Thus, to create a @code{while} loop that tests whether there are any -items in the list @code{animals}, the first part of the loop will be -written like this: - -@smallexample -@group -(while animals - @dots{} -@end group -@end smallexample - -@noindent -When the @code{while} tests its first argument, the variable -@code{animals} is evaluated. It returns a list. So long as the list -has elements, the @code{while} considers the results of the test to be -true; but when the list is empty, it considers the results of the test -to be false. - -To prevent the @code{while} loop from running forever, some mechanism -needs to be provided to empty the list eventually. An oft-used -technique is to have one of the subsequent forms in the @code{while} -expression set the value of the list to be the @sc{cdr} of the list. -Each time the @code{cdr} function is evaluated, the list will be made -shorter, until eventually only the empty list will be left. At this -point, the test of the @code{while} loop will return false, and the -arguments to the @code{while} will no longer be evaluated. - -For example, the list of animals bound to the variable @code{animals} -can be set to be the @sc{cdr} of the original list with the -following expression: - -@smallexample -(setq animals (cdr animals)) -@end smallexample - -@noindent -If you have evaluated the previous expressions and then evaluate this -expression, you will see @code{(giraffe lion tiger)} appear in the echo -area. If you evaluate the expression again, @code{(lion tiger)} will -appear in the echo area. If you evaluate it again and yet again, -@code{(tiger)} appears and then the empty list, shown by @code{nil}. - -A template for a @code{while} loop that uses the @code{cdr} function -repeatedly to cause the true-or-false-test eventually to test false -looks like this: - -@smallexample -@group -(while @var{test-whether-list-is-empty} - @var{body}@dots{} - @var{set-list-to-cdr-of-list}) -@end group -@end smallexample - -This test and use of @code{cdr} can be put together in a function that -goes through a list and prints each element of the list on a line of its -own. - -@node print-elements-of-list, Incrementing Loop, Loop Example, while -@subsection An Example: @code{print-elements-of-list} -@findex print-elements-of-list - -The @code{print-elements-of-list} function illustrates a @code{while} -loop with a list. - -@cindex @file{*scratch*} buffer -The function requires several lines for its output. If you are -reading this in a recent instance of GNU Emacs, -@c GNU Emacs 21, GNU Emacs 22, or a later version, -you can evaluate the following expression inside of Info, as usual. - -If you are using an earlier version of Emacs, you need to copy the -necessary expressions to your @file{*scratch*} buffer and evaluate -them there. This is because the echo area had only one line in the -earlier versions. - -You can copy the expressions by marking the beginning of the region -with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to -the end of the region and then copying the region using @kbd{M-w} -(@code{kill-ring-save}, which calls @code{copy-region-as-kill} and -then provides visual feedback). In the @file{*scratch*} -buffer, you can yank the expressions back by typing @kbd{C-y} -(@code{yank}). - -After you have copied the expressions to the @file{*scratch*} buffer, -evaluate each expression in turn. Be sure to evaluate the last -expression, @code{(print-elements-of-list animals)}, by typing -@kbd{C-u C-x C-e}, that is, by giving an argument to -@code{eval-last-sexp}. This will cause the result of the evaluation -to be printed in the @file{*scratch*} buffer instead of being printed -in the echo area. (Otherwise you will see something like this in your -echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which -each @samp{^J} stands for a `newline'.) - -@need 1500 -In a recent instance of GNU Emacs, you can evaluate these expressions -directly in the Info buffer, and the echo area will grow to show the -results. - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun print-elements-of-list (list) - "Print each element of LIST on a line of its own." - (while list - (print (car list)) - (setq list (cdr list)))) - -(print-elements-of-list animals) -@end group -@end smallexample - -@need 1200 -@noindent -When you evaluate the three expressions in sequence, you will see -this: - -@smallexample -@group -gazelle - -giraffe - -lion - -tiger -nil -@end group -@end smallexample - -Each element of the list is printed on a line of its own (that is what -the function @code{print} does) and then the value returned by the -function is printed. Since the last expression in the function is the -@code{while} loop, and since @code{while} loops always return -@code{nil}, a @code{nil} is printed after the last element of the list. - -@node Incrementing Loop, Incrementing Loop Details, print-elements-of-list, while -@comment node-name, next, previous, up -@subsection A Loop with an Incrementing Counter - -A loop is not useful unless it stops when it ought. Besides -controlling a loop with a list, a common way of stopping a loop is to -write the first argument as a test that returns false when the correct -number of repetitions are complete. This means that the loop must -have a counter---an expression that counts how many times the loop -repeats itself. - -@node Incrementing Loop Details, Decrementing Loop, Incrementing Loop, while -@ifnottex -@unnumberedsubsec Details of an Incrementing Loop -@end ifnottex - -The test for a loop with an incrementing counter can be an expression -such as @code{(< count desired-number)} which returns @code{t} for -true if the value of @code{count} is less than the -@code{desired-number} of repetitions and @code{nil} for false if the -value of @code{count} is equal to or is greater than the -@code{desired-number}. The expression that increments the count can -be a simple @code{setq} such as @code{(setq count (1+ count))}, where -@code{1+} is a built-in function in Emacs Lisp that adds 1 to its -argument. (The expression @w{@code{(1+ count)}} has the same result -as @w{@code{(+ count 1)}}, but is easier for a human to read.) - -@need 1250 -The template for a @code{while} loop controlled by an incrementing -counter looks like this: - -@smallexample -@group -@var{set-count-to-initial-value} -(while (< count desired-number) ; @r{true-or-false-test} - @var{body}@dots{} - (setq count (1+ count))) ; @r{incrementer} -@end group -@end smallexample - -@noindent -Note that you need to set the initial value of @code{count}; usually it -is set to 1. - -@menu -* Incrementing Example:: Counting pebbles in a triangle. -* Inc Example parts:: The parts of the function definition. -* Inc Example altogether:: Putting the function definition together. -@end menu - -@node Incrementing Example, Inc Example parts, Incrementing Loop Details, Incrementing Loop Details -@unnumberedsubsubsec Example with incrementing counter - -Suppose you are playing on the beach and decide to make a triangle of -pebbles, putting one pebble in the first row, two in the second row, -three in the third row and so on, like this: - -@sp 1 -@c pebble diagram -@ifnottex -@smallexample -@group - * - * * - * * * - * * * * -@end group -@end smallexample -@end ifnottex -@iftex -@smallexample -@group - @bullet{} - @bullet{} @bullet{} - @bullet{} @bullet{} @bullet{} - @bullet{} @bullet{} @bullet{} @bullet{} -@end group -@end smallexample -@end iftex -@sp 1 - -@noindent -(About 2500 years ago, Pythagoras and others developed the beginnings of -number theory by considering questions such as this.) - -Suppose you want to know how many pebbles you will need to make a -triangle with 7 rows? - -Clearly, what you need to do is add up the numbers from 1 to 7. There -are two ways to do this; start with the smallest number, one, and add up -the list in sequence, 1, 2, 3, 4 and so on; or start with the largest -number and add the list going down: 7, 6, 5, 4 and so on. Because both -mechanisms illustrate common ways of writing @code{while} loops, we will -create two examples, one counting up and the other counting down. In -this first example, we will start with 1 and add 2, 3, 4 and so on. - -If you are just adding up a short list of numbers, the easiest way to do -it is to add up all the numbers at once. However, if you do not know -ahead of time how many numbers your list will have, or if you want to be -prepared for a very long list, then you need to design your addition so -that what you do is repeat a simple process many times instead of doing -a more complex process once. - -For example, instead of adding up all the pebbles all at once, what you -can do is add the number of pebbles in the first row, 1, to the number -in the second row, 2, and then add the total of those two rows to the -third row, 3. Then you can add the number in the fourth row, 4, to the -total of the first three rows; and so on. - -The critical characteristic of the process is that each repetitive -action is simple. In this case, at each step we add only two numbers, -the number of pebbles in the row and the total already found. This -process of adding two numbers is repeated again and again until the last -row has been added to the total of all the preceding rows. In a more -complex loop the repetitive action might not be so simple, but it will -be simpler than doing everything all at once. - -@node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop Details -@unnumberedsubsubsec The parts of the function definition - -The preceding analysis gives us the bones of our function definition: -first, we will need a variable that we can call @code{total} that will -be the total number of pebbles. This will be the value returned by -the function. - -Second, we know that the function will require an argument: this -argument will be the total number of rows in the triangle. It can be -called @code{number-of-rows}. - -Finally, we need a variable to use as a counter. We could call this -variable @code{counter}, but a better name is @code{row-number}. That -is because what the counter does in this function is count rows, and a -program should be written to be as understandable as possible. - -When the Lisp interpreter first starts evaluating the expressions in the -function, the value of @code{total} should be set to zero, since we have -not added anything to it. Then the function should add the number of -pebbles in the first row to the total, and then add the number of -pebbles in the second to the total, and then add the number of -pebbles in the third row to the total, and so on, until there are no -more rows left to add. - -Both @code{total} and @code{row-number} are used only inside the -function, so they can be declared as local variables with @code{let} -and given initial values. Clearly, the initial value for @code{total} -should be 0. The initial value of @code{row-number} should be 1, -since we start with the first row. This means that the @code{let} -statement will look like this: - -@smallexample -@group - (let ((total 0) - (row-number 1)) - @var{body}@dots{}) -@end group -@end smallexample - -After the internal variables are declared and bound to their initial -values, we can begin the @code{while} loop. The expression that serves -as the test should return a value of @code{t} for true so long as the -@code{row-number} is less than or equal to the @code{number-of-rows}. -(If the expression tests true only so long as the row number is less -than the number of rows in the triangle, the last row will never be -added to the total; hence the row number has to be either less than or -equal to the number of rows.) - -@need 1500 -@findex <= @r{(less than or equal)} -Lisp provides the @code{<=} function that returns true if the value of -its first argument is less than or equal to the value of its second -argument and false otherwise. So the expression that the @code{while} -will evaluate as its test should look like this: - -@smallexample -(<= row-number number-of-rows) -@end smallexample - -The total number of pebbles can be found by repeatedly adding the number -of pebbles in a row to the total already found. Since the number of -pebbles in the row is equal to the row number, the total can be found by -adding the row number to the total. (Clearly, in a more complex -situation, the number of pebbles in the row might be related to the row -number in a more complicated way; if this were the case, the row number -would be replaced by the appropriate expression.) - -@smallexample -(setq total (+ total row-number)) -@end smallexample - -@noindent -What this does is set the new value of @code{total} to be equal to the -sum of adding the number of pebbles in the row to the previous total. - -After setting the value of @code{total}, the conditions need to be -established for the next repetition of the loop, if there is one. This -is done by incrementing the value of the @code{row-number} variable, -which serves as a counter. After the @code{row-number} variable has -been incremented, the true-or-false-test at the beginning of the -@code{while} loop tests whether its value is still less than or equal to -the value of the @code{number-of-rows} and if it is, adds the new value -of the @code{row-number} variable to the @code{total} of the previous -repetition of the loop. - -@need 1200 -The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the -@code{row-number} variable can be incremented with this expression: - -@smallexample -(setq row-number (1+ row-number)) -@end smallexample - -@node Inc Example altogether, , Inc Example parts, Incrementing Loop Details -@unnumberedsubsubsec Putting the function definition together - -We have created the parts for the function definition; now we need to -put them together. - -@need 800 -First, the contents of the @code{while} expression: - -@smallexample -@group -(while (<= row-number number-of-rows) ; @r{true-or-false-test} - (setq total (+ total row-number)) - (setq row-number (1+ row-number))) ; @r{incrementer} -@end group -@end smallexample - -Along with the @code{let} expression varlist, this very nearly -completes the body of the function definition. However, it requires -one final element, the need for which is somewhat subtle. - -The final touch is to place the variable @code{total} on a line by -itself after the @code{while} expression. Otherwise, the value returned -by the whole function is the value of the last expression that is -evaluated in the body of the @code{let}, and this is the value -returned by the @code{while}, which is always @code{nil}. - -This may not be evident at first sight. It almost looks as if the -incrementing expression is the last expression of the whole function. -But that expression is part of the body of the @code{while}; it is the -last element of the list that starts with the symbol @code{while}. -Moreover, the whole of the @code{while} loop is a list within the body -of the @code{let}. - -@need 1250 -In outline, the function will look like this: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (let (@var{varlist}) - (while (@var{true-or-false-test}) - @var{body-of-while}@dots{} ) - @dots{} )) ; @r{Need final expression here.} -@end group -@end smallexample - -The result of evaluating the @code{let} is what is going to be returned -by the @code{defun} since the @code{let} is not embedded within any -containing list, except for the @code{defun} as a whole. However, if -the @code{while} is the last element of the @code{let} expression, the -function will always return @code{nil}. This is not what we want! -Instead, what we want is the value of the variable @code{total}. This -is returned by simply placing the symbol as the last element of the list -starting with @code{let}. It gets evaluated after the preceding -elements of the list are evaluated, which means it gets evaluated after -it has been assigned the correct value for the total. - -It may be easier to see this by printing the list starting with -@code{let} all on one line. This format makes it evident that the -@var{varlist} and @code{while} expressions are the second and third -elements of the list starting with @code{let}, and the @code{total} is -the last element: - -@smallexample -@group -(let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total) -@end group -@end smallexample - -@need 1200 -Putting everything together, the @code{triangle} function definition -looks like this: - -@smallexample -@group -(defun triangle (number-of-rows) ; @r{Version with} - ; @r{ incrementing counter.} - "Add up the number of pebbles in a triangle. -The first row has one pebble, the second row two pebbles, -the third row three pebbles, and so on. -The argument is NUMBER-OF-ROWS." -@end group -@group - (let ((total 0) - (row-number 1)) - (while (<= row-number number-of-rows) - (setq total (+ total row-number)) - (setq row-number (1+ row-number))) - total)) -@end group -@end smallexample - -@need 1200 -After you have installed @code{triangle} by evaluating the function, you -can try it out. Here are two examples: - -@smallexample -@group -(triangle 4) - -(triangle 7) -@end group -@end smallexample - -@noindent -The sum of the first four numbers is 10 and the sum of the first seven -numbers is 28. - -@node Decrementing Loop, , Incrementing Loop Details, while -@comment node-name, next, previous, up -@subsection Loop with a Decrementing Counter - -Another common way to write a @code{while} loop is to write the test -so that it determines whether a counter is greater than zero. So long -as the counter is greater than zero, the loop is repeated. But when -the counter is equal to or less than zero, the loop is stopped. For -this to work, the counter has to start out greater than zero and then -be made smaller and smaller by a form that is evaluated -repeatedly. - -The test will be an expression such as @code{(> counter 0)} which -returns @code{t} for true if the value of @code{counter} is greater -than zero, and @code{nil} for false if the value of @code{counter} is -equal to or less than zero. The expression that makes the number -smaller and smaller can be a simple @code{setq} such as @code{(setq -counter (1- counter))}, where @code{1-} is a built-in function in -Emacs Lisp that subtracts 1 from its argument. - -@need 1250 -The template for a decrementing @code{while} loop looks like this: - -@smallexample -@group -(while (> counter 0) ; @r{true-or-false-test} - @var{body}@dots{} - (setq counter (1- counter))) ; @r{decrementer} -@end group -@end smallexample - -@menu -* Decrementing Example:: More pebbles on the beach. -* Dec Example parts:: The parts of the function definition. -* Dec Example altogether:: Putting the function definition together. -@end menu - -@node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop -@unnumberedsubsubsec Example with decrementing counter - -To illustrate a loop with a decrementing counter, we will rewrite the -@code{triangle} function so the counter decreases to zero. - -This is the reverse of the earlier version of the function. In this -case, to find out how many pebbles are needed to make a triangle with -3 rows, add the number of pebbles in the third row, 3, to the number -in the preceding row, 2, and then add the total of those two rows to -the row that precedes them, which is 1. - -Likewise, to find the number of pebbles in a triangle with 7 rows, add -the number of pebbles in the seventh row, 7, to the number in the -preceding row, which is 6, and then add the total of those two rows to -the row that precedes them, which is 5, and so on. As in the previous -example, each addition only involves adding two numbers, the total of -the rows already added up and the number of pebbles in the row that is -being added to the total. This process of adding two numbers is -repeated again and again until there are no more pebbles to add. - -We know how many pebbles to start with: the number of pebbles in the -last row is equal to the number of rows. If the triangle has seven -rows, the number of pebbles in the last row is 7. Likewise, we know how -many pebbles are in the preceding row: it is one less than the number in -the row. - -@node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop -@unnumberedsubsubsec The parts of the function definition - -We start with three variables: the total number of rows in the -triangle; the number of pebbles in a row; and the total number of -pebbles, which is what we want to calculate. These variables can be -named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and -@code{total}, respectively. - -Both @code{total} and @code{number-of-pebbles-in-row} are used only -inside the function and are declared with @code{let}. The initial -value of @code{total} should, of course, be zero. However, the -initial value of @code{number-of-pebbles-in-row} should be equal to -the number of rows in the triangle, since the addition will start with -the longest row. - -@need 1250 -This means that the beginning of the @code{let} expression will look -like this: - -@smallexample -@group -(let ((total 0) - (number-of-pebbles-in-row number-of-rows)) - @var{body}@dots{}) -@end group -@end smallexample - -The total number of pebbles can be found by repeatedly adding the number -of pebbles in a row to the total already found, that is, by repeatedly -evaluating the following expression: - -@smallexample -(setq total (+ total number-of-pebbles-in-row)) -@end smallexample - -@noindent -After the @code{number-of-pebbles-in-row} is added to the @code{total}, -the @code{number-of-pebbles-in-row} should be decremented by one, since -the next time the loop repeats, the preceding row will be -added to the total. - -The number of pebbles in a preceding row is one less than the number of -pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be -used to compute the number of pebbles in the preceding row. This can be -done with the following expression: - -@smallexample -@group -(setq number-of-pebbles-in-row - (1- number-of-pebbles-in-row)) -@end group -@end smallexample - -Finally, we know that the @code{while} loop should stop making repeated -additions when there are no pebbles in a row. So the test for -the @code{while} loop is simply: - -@smallexample -(while (> number-of-pebbles-in-row 0) -@end smallexample - -@node Dec Example altogether, , Dec Example parts, Decrementing Loop -@unnumberedsubsubsec Putting the function definition together - -We can put these expressions together to create a function definition -that works. However, on examination, we find that one of the local -variables is unneeded! - -@need 1250 -The function definition looks like this: - -@smallexample -@group -;;; @r{First subtractive version.} -(defun triangle (number-of-rows) - "Add up the number of pebbles in a triangle." - (let ((total 0) - (number-of-pebbles-in-row number-of-rows)) - (while (> number-of-pebbles-in-row 0) - (setq total (+ total number-of-pebbles-in-row)) - (setq number-of-pebbles-in-row - (1- number-of-pebbles-in-row))) - total)) -@end group -@end smallexample - -As written, this function works. - -However, we do not need @code{number-of-pebbles-in-row}. - -@cindex Argument as local variable -When the @code{triangle} function is evaluated, the symbol -@code{number-of-rows} will be bound to a number, giving it an initial -value. That number can be changed in the body of the function as if -it were a local variable, without any fear that such a change will -effect the value of the variable outside of the function. This is a -very useful characteristic of Lisp; it means that the variable -@code{number-of-rows} can be used anywhere in the function where -@code{number-of-pebbles-in-row} is used. - -@need 800 -Here is a second version of the function written a bit more cleanly: - -@smallexample -@group -(defun triangle (number) ; @r{Second version.} - "Return sum of numbers 1 through NUMBER inclusive." - (let ((total 0)) - (while (> number 0) - (setq total (+ total number)) - (setq number (1- number))) - total)) -@end group -@end smallexample - -In brief, a properly written @code{while} loop will consist of three parts: - -@enumerate -@item -A test that will return false after the loop has repeated itself the -correct number of times. - -@item -An expression the evaluation of which will return the value desired -after being repeatedly evaluated. - -@item -An expression to change the value passed to the true-or-false-test so -that the test returns false after the loop has repeated itself the right -number of times. -@end enumerate - -@node dolist dotimes, Recursion, while, Loops & Recursion -@comment node-name, next, previous, up -@section Save your time: @code{dolist} and @code{dotimes} - -In addition to @code{while}, both @code{dolist} and @code{dotimes} -provide for looping. Sometimes these are quicker to write than the -equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, , -Macros, elisp, The GNU Emacs Lisp Reference Manual}. ) - -@code{dolist} works like a @code{while} loop that `@sc{cdr}s down a -list': @code{dolist} automatically shortens the list each time it -loops---takes the @sc{cdr} of the list---and binds the @sc{car} of -each shorter version of the list to the first of its arguments. - -@code{dotimes} loops a specific number of times: you specify the number. - -@menu -* dolist:: -* dotimes:: -@end menu - -@node dolist, dotimes, dolist dotimes, dolist dotimes -@unnumberedsubsubsec The @code{dolist} Macro -@findex dolist - -Suppose, for example, you want to reverse a list, so that -``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''. - -@need 1250 -In practice, you would use the @code{reverse} function, like this: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(reverse animals) -@end group -@end smallexample - -@need 800 -@noindent -Here is how you could reverse the list using a @code{while} loop: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun reverse-list-with-while (list) - "Using while, reverse the order of LIST." - (let (value) ; make sure list starts empty - (while list - (setq value (cons (car list) value)) - (setq list (cdr list))) - value)) - -(reverse-list-with-while animals) -@end group -@end smallexample - -@need 800 -@noindent -And here is how you could use the @code{dolist} macro: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun reverse-list-with-dolist (list) - "Using dolist, reverse the order of LIST." - (let (value) ; make sure list starts empty - (dolist (element list value) - (setq value (cons element value))))) - -(reverse-list-with-dolist animals) -@end group -@end smallexample - -@need 1250 -@noindent -In Info, you can place your cursor after the closing parenthesis of -each expression and type @kbd{C-x C-e}; in each case, you should see - -@smallexample -(tiger lion giraffe gazelle) -@end smallexample - -@noindent -in the echo area. - -For this example, the existing @code{reverse} function is obviously best. -The @code{while} loop is just like our first example (@pxref{Loop -Example, , A @code{while} Loop and a List}). The @code{while} first -checks whether the list has elements; if so, it constructs a new list -by adding the first element of the list to the existing list (which in -the first iteration of the loop is @code{nil}). Since the second -element is prepended in front of the first element, and the third -element is prepended in front of the second element, the list is reversed. - -In the expression using a @code{while} loop, -the @w{@code{(setq list (cdr list))}} -expression shortens the list, so the @code{while} loop eventually -stops. In addition, it provides the @code{cons} expression with a new -first element by creating a new and shorter list at each repetition of -the loop. - -The @code{dolist} expression does very much the same as the -@code{while} expression, except that the @code{dolist} macro does some -of the work you have to do when writing a @code{while} expression. - -Like a @code{while} loop, a @code{dolist} loops. What is different is -that it automatically shortens the list each time it loops --- it -`@sc{cdr}s down the list' on its own --- and it automatically binds -the @sc{car} of each shorter version of the list to the first of its -arguments. - -In the example, the @sc{car} of each shorter version of the list is -referred to using the symbol @samp{element}, the list itself is called -@samp{list}, and the value returned is called @samp{value}. The -remainder of the @code{dolist} expression is the body. - -The @code{dolist} expression binds the @sc{car} of each shorter -version of the list to @code{element} and then evaluates the body of -the expression; and repeats the loop. The result is returned in -@code{value}. - -@node dotimes, , dolist, dolist dotimes -@unnumberedsubsubsec The @code{dotimes} Macro -@findex dotimes - -The @code{dotimes} macro is similar to @code{dolist}, except that it -loops a specific number of times. - -The first argument to @code{dotimes} is assigned the numbers 0, 1, 2 -and so forth each time around the loop, and the value of the third -argument is returned. You need to provide the value of the second -argument, which is how many times the macro loops. - -@need 1250 -For example, the following binds the numbers from 0 up to, but not -including, the number 3 to the first argument, @var{number}, and then -constructs a list of the three numbers. (The first number is 0, the -second number is 1, and the third number is 2; this makes a total of -three numbers in all, starting with zero as the first number.) - -@smallexample -@group -(let (value) ; otherwise a value is a void variable - (dotimes (number 3 value) - (setq value (cons number value)))) - -@result{} (2 1 0) -@end group -@end smallexample - -@noindent -@code{dotimes} returns @code{value}, so the way to use -@code{dotimes} is to operate on some expression @var{number} number of -times and then return the result, either as a list or an atom. - -@need 1250 -Here is an example of a @code{defun} that uses @code{dotimes} to add -up the number of pebbles in a triangle. - -@smallexample -@group -(defun triangle-using-dotimes (number-of-rows) - "Using dotimes, add up the number of pebbles in a triangle." -(let ((total 0)) ; otherwise a total is a void variable - (dotimes (number number-of-rows total) - (setq total (+ total (1+ number)))))) - -(triangle-using-dotimes 4) -@end group -@end smallexample - -@node Recursion, Looping exercise, dolist dotimes, Loops & Recursion -@comment node-name, next, previous, up -@section Recursion -@cindex Recursion - -A recursive function contains code that tells the Lisp interpreter to -call a program that runs exactly like itself, but with slightly -different arguments. The code runs exactly the same because it has -the same name. However, even though the program has the same name, it -is not the same entity. It is different. In the jargon, it is a -different `instance'. - -Eventually, if the program is written correctly, the `slightly -different arguments' will become sufficiently different from the first -arguments that the final instance will stop. - -@menu -* Building Robots:: Same model, different serial number ... -* Recursive Definition Parts:: Walk until you stop ... -* Recursion with list:: Using a list as the test whether to recurse. -* Recursive triangle function:: -* Recursion with cond:: -* Recursive Patterns:: Often used templates. -* No Deferment:: Don't store up work ... -* No deferment solution:: -@end menu - -@node Building Robots, Recursive Definition Parts, Recursion, Recursion -@comment node-name, next, previous, up -@subsection Building Robots: Extending the Metaphor -@cindex Building robots -@cindex Robots, building - -It is sometimes helpful to think of a running program as a robot that -does a job. In doing its job, a recursive function calls on a second -robot to help it. The second robot is identical to the first in every -way, except that the second robot helps the first and has been -passed different arguments than the first. - -In a recursive function, the second robot may call a third; and the -third may call a fourth, and so on. Each of these is a different -entity; but all are clones. - -Since each robot has slightly different instructions---the arguments -will differ from one robot to the next---the last robot should know -when to stop. - -Let's expand on the metaphor in which a computer program is a robot. - -A function definition provides the blueprints for a robot. When you -install a function definition, that is, when you evaluate a -@code{defun} special form, you install the necessary equipment to -build robots. It is as if you were in a factory, setting up an -assembly line. Robots with the same name are built according to the -same blueprints. So they have, as it were, the same `model number', -but a different `serial number'. - -We often say that a recursive function `calls itself'. What we mean -is that the instructions in a recursive function cause the Lisp -interpreter to run a different function that has the same name and -does the same job as the first, but with different arguments. - -It is important that the arguments differ from one instance to the -next; otherwise, the process will never stop. - -@node Recursive Definition Parts, Recursion with list, Building Robots, Recursion -@comment node-name, next, previous, up -@subsection The Parts of a Recursive Definition -@cindex Parts of a Recursive Definition -@cindex Recursive Definition Parts - -A recursive function typically contains a conditional expression which -has three parts: - -@enumerate -@item -A true-or-false-test that determines whether the function is called -again, here called the @dfn{do-again-test}. - -@item -The name of the function. When this name is called, a new instance of -the function---a new robot, as it were---is created and told what to do. - -@item -An expression that returns a different value each time the function is -called, here called the @dfn{next-step-expression}. Consequently, the -argument (or arguments) passed to the new instance of the function -will be different from that passed to the previous instance. This -causes the conditional expression, the @dfn{do-again-test}, to test -false after the correct number of repetitions. -@end enumerate - -Recursive functions can be much simpler than any other kind of -function. Indeed, when people first start to use them, they often look -so mysteriously simple as to be incomprehensible. Like riding a -bicycle, reading a recursive function definition takes a certain knack -which is hard at first but then seems simple. - -@need 1200 -There are several different common recursive patterns. A very simple -pattern looks like this: - -@smallexample -@group -(defun @var{name-of-recursive-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (if @var{do-again-test} - @var{body}@dots{} - (@var{name-of-recursive-function} - @var{next-step-expression}))) -@end group -@end smallexample - -Each time a recursive function is evaluated, a new instance of it is -created and told what to do. The arguments tell the instance what to do. - -An argument is bound to the value of the next-step-expression. Each -instance runs with a different value of the next-step-expression. - -The value in the next-step-expression is used in the do-again-test. - -The value returned by the next-step-expression is passed to the new -instance of the function, which evaluates it (or some -transmogrification of it) to determine whether to continue or stop. -The next-step-expression is designed so that the do-again-test returns -false when the function should no longer be repeated. - -The do-again-test is sometimes called the @dfn{stop condition}, -since it stops the repetitions when it tests false. - -@node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion -@comment node-name, next, previous, up -@subsection Recursion with a List - -The example of a @code{while} loop that printed the elements of a list -of numbers can be written recursively. Here is the code, including -an expression to set the value of the variable @code{animals} to a list. - -If you are reading this in Info in Emacs, you can evaluate this -expression directly in Info. Otherwise, you must copy the example -to the @file{*scratch*} buffer and evaluate each expression there. -Use @kbd{C-u C-x C-e} to evaluate the -@code{(print-elements-recursively animals)} expression so that the -results are printed in the buffer; otherwise the Lisp interpreter will -try to squeeze the results into the one line of the echo area. - -Also, place your cursor immediately after the last closing parenthesis -of the @code{print-elements-recursively} function, before the comment. -Otherwise, the Lisp interpreter will try to evaluate the comment. - -@findex print-elements-recursively -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun print-elements-recursively (list) - "Print each element of LIST on a line of its own. -Uses recursion." - (when list ; @r{do-again-test} - (print (car list)) ; @r{body} - (print-elements-recursively ; @r{recursive call} - (cdr list)))) ; @r{next-step-expression} - -(print-elements-recursively animals) -@end group -@end smallexample - -The @code{print-elements-recursively} function first tests whether -there is any content in the list; if there is, the function prints the -first element of the list, the @sc{car} of the list. Then the -function `invokes itself', but gives itself as its argument, not the -whole list, but the second and subsequent elements of the list, the -@sc{cdr} of the list. - -Put another way, if the list is not empty, the function invokes -another instance of code that is similar to the initial code, but is a -different thread of execution, with different arguments than the first -instance. - -Put in yet another way, if the list is not empty, the first robot -assembles a second robot and tells it what to do; the second robot is -a different individual from the first, but is the same model. - -When the second evaluation occurs, the @code{when} expression is -evaluated and if true, prints the first element of the list it -receives as its argument (which is the second element of the original -list). Then the function `calls itself' with the @sc{cdr} of the list -it is invoked with, which (the second time around) is the @sc{cdr} of -the @sc{cdr} of the original list. - -Note that although we say that the function `calls itself', what we -mean is that the Lisp interpreter assembles and instructs a new -instance of the program. The new instance is a clone of the first, -but is a separate individual. - -Each time the function `invokes itself', it invokes itself on a -shorter version of the original list. It creates a new instance that -works on a shorter list. - -Eventually, the function invokes itself on an empty list. It creates -a new instance whose argument is @code{nil}. The conditional expression -tests the value of @code{list}. Since the value of @code{list} is -@code{nil}, the @code{when} expression tests false so the then-part is -not evaluated. The function as a whole then returns @code{nil}. - -@need 1200 -When you evaluate the expression @code{(print-elements-recursively -animals)} in the @file{*scratch*} buffer, you see this result: - -@smallexample -@group -gazelle - -giraffe - -lion - -tiger -nil -@end group -@end smallexample - -@need 2000 -@node Recursive triangle function, Recursion with cond, Recursion with list, Recursion -@comment node-name, next, previous, up -@subsection Recursion in Place of a Counter -@findex triangle-recursively - -@need 1200 -The @code{triangle} function described in a previous section can also -be written recursively. It looks like this: - -@smallexample -@group -(defun triangle-recursively (number) - "Return the sum of the numbers 1 through NUMBER inclusive. -Uses recursion." - (if (= number 1) ; @r{do-again-test} - 1 ; @r{then-part} - (+ number ; @r{else-part} - (triangle-recursively ; @r{recursive call} - (1- number))))) ; @r{next-step-expression} - -(triangle-recursively 7) -@end group -@end smallexample - -@noindent -You can install this function by evaluating it and then try it by -evaluating @code{(triangle-recursively 7)}. (Remember to put your -cursor immediately after the last parenthesis of the function -definition, before the comment.) The function evaluates to 28. - -To understand how this function works, let's consider what happens in the -various cases when the function is passed 1, 2, 3, or 4 as the value of -its argument. - -@menu -* Recursive Example arg of 1 or 2:: -* Recursive Example arg of 3 or 4:: -@end menu - -@node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function -@ifnottex -@unnumberedsubsubsec An argument of 1 or 2 -@end ifnottex - -First, what happens if the value of the argument is 1? - -The function has an @code{if} expression after the documentation -string. It tests whether the value of @code{number} is equal to 1; if -so, Emacs evaluates the then-part of the @code{if} expression, which -returns the number 1 as the value of the function. (A triangle with -one row has one pebble in it.) - -Suppose, however, that the value of the argument is 2. In this case, -Emacs evaluates the else-part of the @code{if} expression. - -@need 1200 -The else-part consists of an addition, the recursive call to -@code{triangle-recursively} and a decrementing action; and it looks like -this: - -@smallexample -(+ number (triangle-recursively (1- number))) -@end smallexample - -When Emacs evaluates this expression, the innermost expression is -evaluated first; then the other parts in sequence. Here are the steps -in detail: - -@table @i -@item Step 1 @w{ } Evaluate the innermost expression. - -The innermost expression is @code{(1- number)} so Emacs decrements the -value of @code{number} from 2 to 1. - -@item Step 2 @w{ } Evaluate the @code{triangle-recursively} function. - -The Lisp interpreter creates an individual instance of -@code{triangle-recursively}. It does not matter that this function is -contained within itself. Emacs passes the result Step 1 as the -argument used by this instance of the @code{triangle-recursively} -function - -In this case, Emacs evaluates @code{triangle-recursively} with an -argument of 1. This means that this evaluation of -@code{triangle-recursively} returns 1. - -@item Step 3 @w{ } Evaluate the value of @code{number}. - -The variable @code{number} is the second element of the list that -starts with @code{+}; its value is 2. - -@item Step 4 @w{ } Evaluate the @code{+} expression. - -The @code{+} expression receives two arguments, the first -from the evaluation of @code{number} (Step 3) and the second from the -evaluation of @code{triangle-recursively} (Step 2). - -The result of the addition is the sum of 2 plus 1, and the number 3 is -returned, which is correct. A triangle with two rows has three -pebbles in it. -@end table - -@node Recursive Example arg of 3 or 4, , Recursive Example arg of 1 or 2, Recursive triangle function -@unnumberedsubsubsec An argument of 3 or 4 - -Suppose that @code{triangle-recursively} is called with an argument of -3. - -@table @i -@item Step 1 @w{ } Evaluate the do-again-test. - -The @code{if} expression is evaluated first. This is the do-again -test and returns false, so the else-part of the @code{if} expression -is evaluated. (Note that in this example, the do-again-test causes -the function to call itself when it tests false, not when it tests -true.) - -@item Step 2 @w{ } Evaluate the innermost expression of the else-part. - -The innermost expression of the else-part is evaluated, which decrements -3 to 2. This is the next-step-expression. - -@item Step 3 @w{ } Evaluate the @code{triangle-recursively} function. - -The number 2 is passed to the @code{triangle-recursively} function. - -We already know what happens when Emacs evaluates @code{triangle-recursively} with -an argument of 2. After going through the sequence of actions described -earlier, it returns a value of 3. So that is what will happen here. - -@item Step 4 @w{ } Evaluate the addition. - -3 will be passed as an argument to the addition and will be added to the -number with which the function was called, which is 3. -@end table - -@noindent -The value returned by the function as a whole will be 6. - -Now that we know what will happen when @code{triangle-recursively} is -called with an argument of 3, it is evident what will happen if it is -called with an argument of 4: - -@quotation -@need 800 -In the recursive call, the evaluation of - -@smallexample -(triangle-recursively (1- 4)) -@end smallexample - -@need 800 -@noindent -will return the value of evaluating - -@smallexample -(triangle-recursively 3) -@end smallexample - -@noindent -which is 6 and this value will be added to 4 by the addition in the -third line. -@end quotation - -@noindent -The value returned by the function as a whole will be 10. - -Each time @code{triangle-recursively} is evaluated, it evaluates a -version of itself---a different instance of itself---with a smaller -argument, until the argument is small enough so that it does not -evaluate itself. - -Note that this particular design for a recursive function -requires that operations be deferred. - -Before @code{(triangle-recursively 7)} can calculate its answer, it -must call @code{(triangle-recursively 6)}; and before -@code{(triangle-recursively 6)} can calculate its answer, it must call -@code{(triangle-recursively 5)}; and so on. That is to say, the -calculation that @code{(triangle-recursively 7)} makes must be -deferred until @code{(triangle-recursively 6)} makes its calculation; -and @code{(triangle-recursively 6)} must defer until -@code{(triangle-recursively 5)} completes; and so on. - -If each of these instances of @code{triangle-recursively} are thought -of as different robots, the first robot must wait for the second to -complete its job, which must wait until the third completes, and so -on. - -There is a way around this kind of waiting, which we will discuss in -@ref{No Deferment, , Recursion without Deferments}. - -@node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion -@comment node-name, next, previous, up -@subsection Recursion Example Using @code{cond} -@findex cond - -The version of @code{triangle-recursively} described earlier is written -with the @code{if} special form. It can also be written using another -special form called @code{cond}. The name of the special form -@code{cond} is an abbreviation of the word @samp{conditional}. - -Although the @code{cond} special form is not used as often in the -Emacs Lisp sources as @code{if}, it is used often enough to justify -explaining it. - -@need 800 -The template for a @code{cond} expression looks like this: - -@smallexample -@group -(cond - @var{body}@dots{}) -@end group -@end smallexample - -@noindent -where the @var{body} is a series of lists. - -@need 800 -Written out more fully, the template looks like this: - -@smallexample -@group -(cond - (@var{first-true-or-false-test} @var{first-consequent}) - (@var{second-true-or-false-test} @var{second-consequent}) - (@var{third-true-or-false-test} @var{third-consequent}) - @dots{}) -@end group -@end smallexample - -When the Lisp interpreter evaluates the @code{cond} expression, it -evaluates the first element (the @sc{car} or true-or-false-test) of -the first expression in a series of expressions within the body of the -@code{cond}. - -If the true-or-false-test returns @code{nil} the rest of that -expression, the consequent, is skipped and the true-or-false-test of the -next expression is evaluated. When an expression is found whose -true-or-false-test returns a value that is not @code{nil}, the -consequent of that expression is evaluated. The consequent can be one -or more expressions. If the consequent consists of more than one -expression, the expressions are evaluated in sequence and the value of -the last one is returned. If the expression does not have a consequent, -the value of the true-or-false-test is returned. - -If none of the true-or-false-tests test true, the @code{cond} expression -returns @code{nil}. - -@need 1250 -Written using @code{cond}, the @code{triangle} function looks like this: - -@smallexample -@group -(defun triangle-using-cond (number) - (cond ((<= number 0) 0) - ((= number 1) 1) - ((> number 1) - (+ number (triangle-using-cond (1- number)))))) -@end group -@end smallexample - -@noindent -In this example, the @code{cond} returns 0 if the number is less than or -equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+ -number (triangle-using-cond (1- number)))} if the number is greater than -1. - -@node Recursive Patterns, No Deferment, Recursion with cond, Recursion -@comment node-name, next, previous, up -@subsection Recursive Patterns -@cindex Recursive Patterns - -Here are three common recursive patterns. Each involves a list. -Recursion does not need to involve lists, but Lisp is designed for lists -and this provides a sense of its primal capabilities. - -@menu -* Every:: -* Accumulate:: -* Keep:: -@end menu - -@node Every, Accumulate, Recursive Patterns, Recursive Patterns -@comment node-name, next, previous, up -@unnumberedsubsubsec Recursive Pattern: @emph{every} -@cindex Every, type of recursive pattern -@cindex Recursive pattern: every - -In the @code{every} recursive pattern, an action is performed on every -element of a list. - -@need 1500 -The basic pattern is: - -@itemize @bullet -@item -If a list be empty, return @code{nil}. -@item -Else, act on the beginning of the list (the @sc{car} of the list) - @itemize @minus - @item - through a recursive call by the function on the rest (the - @sc{cdr}) of the list, - @item - and, optionally, combine the acted-on element, using @code{cons}, - with the results of acting on the rest. - @end itemize -@end itemize - -@need 1500 -Here is example: - -@smallexample -@group -(defun square-each (numbers-list) - "Square each of a NUMBERS LIST, recursively." - (if (not numbers-list) ; do-again-test - nil - (cons - (* (car numbers-list) (car numbers-list)) - (square-each (cdr numbers-list))))) ; next-step-expression -@end group - -@group -(square-each '(1 2 3)) - @result{} (1 4 9) -@end group -@end smallexample - -@need 1200 -@noindent -If @code{numbers-list} is empty, do nothing. But if it has content, -construct a list combining the square of the first number in the list -with the result of the recursive call. - -(The example follows the pattern exactly: @code{nil} is returned if -the numbers' list is empty. In practice, you would write the -conditional so it carries out the action when the numbers' list is not -empty.) - -The @code{print-elements-recursively} function (@pxref{Recursion with -list, , Recursion with a List}) is another example of an @code{every} -pattern, except in this case, rather than bring the results together -using @code{cons}, we print each element of output. - -@need 1250 -The @code{print-elements-recursively} function looks like this: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) -@end group - -@group -(defun print-elements-recursively (list) - "Print each element of LIST on a line of its own. -Uses recursion." - (when list ; @r{do-again-test} - (print (car list)) ; @r{body} - (print-elements-recursively ; @r{recursive call} - (cdr list)))) ; @r{next-step-expression} - -(print-elements-recursively animals) -@end group -@end smallexample - -@need 1500 -The pattern for @code{print-elements-recursively} is: - -@itemize @bullet -@item -When the list is empty, do nothing. -@item -But when the list has at least one element, - @itemize @minus - @item - act on the beginning of the list (the @sc{car} of the list), - @item - and make a recursive call on the rest (the @sc{cdr}) of the list. - @end itemize -@end itemize - -@node Accumulate, Keep, Every, Recursive Patterns -@comment node-name, next, previous, up -@unnumberedsubsubsec Recursive Pattern: @emph{accumulate} -@cindex Accumulate, type of recursive pattern -@cindex Recursive pattern: accumulate - -Another recursive pattern is called the @code{accumulate} pattern. In -the @code{accumulate} recursive pattern, an action is performed on -every element of a list and the result of that action is accumulated -with the results of performing the action on the other elements. - -This is very like the `every' pattern using @code{cons}, except that -@code{cons} is not used, but some other combiner. - -@need 1500 -The pattern is: - -@itemize @bullet -@item -If a list be empty, return zero or some other constant. -@item -Else, act on the beginning of the list (the @sc{car} of the list), - @itemize @minus - @item - and combine that acted-on element, using @code{+} or - some other combining function, with - @item - a recursive call by the function on the rest (the @sc{cdr}) of the list. - @end itemize -@end itemize - -@need 1500 -Here is an example: - -@smallexample -@group -(defun add-elements (numbers-list) - "Add the elements of NUMBERS-LIST together." - (if (not numbers-list) - 0 - (+ (car numbers-list) (add-elements (cdr numbers-list))))) -@end group - -@group -(add-elements '(1 2 3 4)) - @result{} 10 -@end group -@end smallexample - -@xref{Files List, , Making a List of Files}, for an example of the -accumulate pattern. - -@node Keep, , Accumulate, Recursive Patterns -@comment node-name, next, previous, up -@unnumberedsubsubsec Recursive Pattern: @emph{keep} -@cindex Keep, type of recursive pattern -@cindex Recursive pattern: keep - -A third recursive pattern is called the @code{keep} pattern. -In the @code{keep} recursive pattern, each element of a list is tested; -the element is acted on and the results are kept only if the element -meets a criterion. - -Again, this is very like the `every' pattern, except the element is -skipped unless it meets a criterion. - -@need 1500 -The pattern has three parts: - -@itemize @bullet -@item -If a list be empty, return @code{nil}. -@item -Else, if the beginning of the list (the @sc{car} of the list) passes - a test - @itemize @minus - @item - act on that element and combine it, using @code{cons} with - @item - a recursive call by the function on the rest (the @sc{cdr}) of the list. - @end itemize -@item -Otherwise, if the beginning of the list (the @sc{car} of the list) fails -the test - @itemize @minus - @item - skip on that element, - @item - and, recursively call the function on the rest (the @sc{cdr}) of the list. - @end itemize -@end itemize - -@need 1500 -Here is an example that uses @code{cond}: - -@smallexample -@group -(defun keep-three-letter-words (word-list) - "Keep three letter words in WORD-LIST." - (cond - ;; First do-again-test: stop-condition - ((not word-list) nil) - - ;; Second do-again-test: when to act - ((eq 3 (length (symbol-name (car word-list)))) - ;; combine acted-on element with recursive call on shorter list - (cons (car word-list) (keep-three-letter-words (cdr word-list)))) - - ;; Third do-again-test: when to skip element; - ;; recursively call shorter list with next-step expression - (t (keep-three-letter-words (cdr word-list))))) -@end group - -@group -(keep-three-letter-words '(one two three four five six)) - @result{} (one two six) -@end group -@end smallexample - -It goes without saying that you need not use @code{nil} as the test for -when to stop; and you can, of course, combine these patterns. - -@node No Deferment, No deferment solution, Recursive Patterns, Recursion -@subsection Recursion without Deferments -@cindex Deferment in recursion -@cindex Recursion without Deferments - -Let's consider again what happens with the @code{triangle-recursively} -function. We will find that the intermediate calculations are -deferred until all can be done. - -@need 800 -Here is the function definition: - -@smallexample -@group -(defun triangle-recursively (number) - "Return the sum of the numbers 1 through NUMBER inclusive. -Uses recursion." - (if (= number 1) ; @r{do-again-test} - 1 ; @r{then-part} - (+ number ; @r{else-part} - (triangle-recursively ; @r{recursive call} - (1- number))))) ; @r{next-step-expression} -@end group -@end smallexample - -What happens when we call this function with a argument of 7? - -The first instance of the @code{triangle-recursively} function adds -the number 7 to the value returned by a second instance of -@code{triangle-recursively}, an instance that has been passed an -argument of 6. That is to say, the first calculation is: - -@smallexample -(+ 7 (triangle-recursively 6)) -@end smallexample - -@noindent -The first instance of @code{triangle-recursively}---you may want to -think of it as a little robot---cannot complete its job. It must hand -off the calculation for @code{(triangle-recursively 6)} to a second -instance of the program, to a second robot. This second individual is -completely different from the first one; it is, in the jargon, a -`different instantiation'. Or, put another way, it is a different -robot. It is the same model as the first; it calculates triangle -numbers recursively; but it has a different serial number. - -And what does @code{(triangle-recursively 6)} return? It returns the -number 6 added to the value returned by evaluating -@code{triangle-recursively} with an argument of 5. Using the robot -metaphor, it asks yet another robot to help it. - -@need 800 -Now the total is: - -@smallexample -(+ 7 6 (triangle-recursively 5)) -@end smallexample - -@need 800 -And what happens next? - -@smallexample -(+ 7 6 5 (triangle-recursively 4)) -@end smallexample - -Each time @code{triangle-recursively} is called, except for the last -time, it creates another instance of the program---another robot---and -asks it to make a calculation. - -@need 800 -Eventually, the full addition is set up and performed: - -@smallexample -(+ 7 6 5 4 3 2 1) -@end smallexample - -This design for the function defers the calculation of the first step -until the second can be done, and defers that until the third can be -done, and so on. Each deferment means the computer must remember what -is being waited on. This is not a problem when there are only a few -steps, as in this example. But it can be a problem when there are -more steps. - -@node No deferment solution, , No Deferment, Recursion -@subsection No Deferment Solution -@cindex No deferment solution -@cindex Defermentless solution -@cindex Solution without deferment - -The solution to the problem of deferred operations is to write in a -manner that does not defer operations@footnote{The phrase @dfn{tail -recursive} is used to describe such a process, one that uses -`constant space'.}. This requires -writing to a different pattern, often one that involves writing two -function definitions, an `initialization' function and a `helper' -function. - -The `initialization' function sets up the job; the `helper' function -does the work. - -@need 1200 -Here are the two function definitions for adding up numbers. They are -so simple, I find them hard to understand. - -@smallexample -@group -(defun triangle-initialization (number) - "Return the sum of the numbers 1 through NUMBER inclusive. -This is the `initialization' component of a two function -duo that uses recursion." - (triangle-recursive-helper 0 0 number)) -@end group -@end smallexample - -@smallexample -@group -(defun triangle-recursive-helper (sum counter number) - "Return SUM, using COUNTER, through NUMBER inclusive. -This is the `helper' component of a two function duo -that uses recursion." - (if (> counter number) - sum - (triangle-recursive-helper (+ sum counter) ; @r{sum} - (1+ counter) ; @r{counter} - number))) ; @r{number} -@end group -@end smallexample - -@need 1250 -Install both function definitions by evaluating them, then call -@code{triangle-initialization} with 2 rows: - -@smallexample -@group -(triangle-initialization 2) - @result{} 3 -@end group -@end smallexample - -The `initialization' function calls the first instance of the `helper' -function with three arguments: zero, zero, and a number which is the -number of rows in the triangle. - -The first two arguments passed to the `helper' function are -initialization values. These values are changed when -@code{triangle-recursive-helper} invokes new instances.@footnote{The -jargon is mildly confusing: @code{triangle-recursive-helper} uses a -process that is iterative in a procedure that is recursive. The -process is called iterative because the computer need only record the -three values, @code{sum}, @code{counter}, and @code{number}; the -procedure is recursive because the function `calls itself'. On the -other hand, both the process and the procedure used by -@code{triangle-recursively} are called recursive. The word -`recursive' has different meanings in the two contexts.} - -Let's see what happens when we have a triangle that has one row. (This -triangle will have one pebble in it!) - -@need 1200 -@code{triangle-initialization} will call its helper with -the arguments @w{@code{0 0 1}}. That function will run the conditional -test whether @code{(> counter number)}: - -@smallexample -(> 0 1) -@end smallexample - -@need 1200 -@noindent -and find that the result is false, so it will invoke -the else-part of the @code{if} clause: - -@smallexample -@group - (triangle-recursive-helper - (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} - (1+ counter) ; @r{increment counter} @result{} @r{counter} - number) ; @r{number stays the same} -@end group -@end smallexample - -@need 800 -@noindent -which will first compute: - -@smallexample -@group -(triangle-recursive-helper (+ 0 0) ; @r{sum} - (1+ 0) ; @r{counter} - 1) ; @r{number} -@exdent which is: - -(triangle-recursive-helper 0 1 1) -@end group -@end smallexample - -Again, @code{(> counter number)} will be false, so again, the Lisp -interpreter will evaluate @code{triangle-recursive-helper}, creating a -new instance with new arguments. - -@need 800 -This new instance will be; - -@smallexample -@group - (triangle-recursive-helper - (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} - (1+ counter) ; @r{increment counter} @result{} @r{counter} - number) ; @r{number stays the same} - -@exdent which is: - -(triangle-recursive-helper 1 2 1) -@end group -@end smallexample - -In this case, the @code{(> counter number)} test will be true! So the -instance will return the value of the sum, which will be 1, as -expected. - -Now, let's pass @code{triangle-initialization} an argument -of 2, to find out how many pebbles there are in a triangle with two rows. - -That function calls @code{(triangle-recursive-helper 0 0 2)}. - -@need 800 -In stages, the instances called will be: - -@smallexample -@group - @r{sum counter number} -(triangle-recursive-helper 0 1 2) - -(triangle-recursive-helper 1 2 2) - -(triangle-recursive-helper 3 3 2) -@end group -@end smallexample - -When the last instance is called, the @code{(> counter number)} test -will be true, so the instance will return the value of @code{sum}, -which will be 3. - -This kind of pattern helps when you are writing functions that can use -many resources in a computer. - -@need 1500 -@node Looping exercise, , Recursion, Loops & Recursion -@section Looping Exercise - -@itemize @bullet -@item -Write a function similar to @code{triangle} in which each row has a -value which is the square of the row number. Use a @code{while} loop. - -@item -Write a function similar to @code{triangle} that multiplies instead of -adds the values. - -@item -Rewrite these two functions recursively. Rewrite these functions -using @code{cond}. - -@c comma in printed title causes problem in Info cross reference -@item -Write a function for Texinfo mode that creates an index entry at the -beginning of a paragraph for every @samp{@@dfn} within the paragraph. -(In a Texinfo file, @samp{@@dfn} marks a definition. This book is -written in Texinfo.) - -Many of the functions you will need are described in two of the -previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing -Text}, and @ref{Yanking, , Yanking Text Back}. If you use -@code{forward-paragraph} to put the index entry at the beginning of -the paragraph, you will have to use @w{@kbd{C-h f}} -(@code{describe-function}) to find out how to make the command go -backwards. - -For more information, see -@ifinfo -@ref{Indicating, , Indicating Definitions, texinfo}. -@end ifinfo -@ifhtml -@ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to -a Texinfo manual in the current directory. Or, if you are on the -Internet, see -@uref{http://www.gnu.org/software/texinfo/manual/texinfo/} -@end ifhtml -@iftex -``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU -Documentation Format}. -@end iftex -@end itemize - -@node Regexp Search, Counting Words, Loops & Recursion, Top -@comment node-name, next, previous, up -@chapter Regular Expression Searches -@cindex Searches, illustrating -@cindex Regular expression searches -@cindex Patterns, searching for -@cindex Motion by sentence and paragraph -@cindex Sentences, movement by -@cindex Paragraphs, movement by - -Regular expression searches are used extensively in GNU Emacs. The -two functions, @code{forward-sentence} and @code{forward-paragraph}, -illustrate these searches well. They use regular expressions to find -where to move point. The phrase `regular expression' is often written -as `regexp'. - -Regular expression searches are described in @ref{Regexp Search, , -Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in -@ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference -Manual}. In writing this chapter, I am presuming that you have at -least a mild acquaintance with them. The major point to remember is -that regular expressions permit you to search for patterns as well as -for literal strings of characters. For example, the code in -@code{forward-sentence} searches for the pattern of possible -characters that could mark the end of a sentence, and moves point to -that spot. - -Before looking at the code for the @code{forward-sentence} function, it -is worth considering what the pattern that marks the end of a sentence -must be. The pattern is discussed in the next section; following that -is a description of the regular expression search function, -@code{re-search-forward}. The @code{forward-sentence} function -is described in the section following. Finally, the -@code{forward-paragraph} function is described in the last section of -this chapter. @code{forward-paragraph} is a complex function that -introduces several new features. - -@menu -* sentence-end:: The regular expression for @code{sentence-end}. -* re-search-forward:: Very similar to @code{search-forward}. -* forward-sentence:: A straightforward example of regexp search. -* forward-paragraph:: A somewhat complex example. -* etags:: How to create your own @file{TAGS} table. -* Regexp Review:: -* re-search Exercises:: -@end menu - -@node sentence-end, re-search-forward, Regexp Search, Regexp Search -@comment node-name, next, previous, up -@section The Regular Expression for @code{sentence-end} -@findex sentence-end - -The symbol @code{sentence-end} is bound to the pattern that marks the -end of a sentence. What should this regular expression be? - -Clearly, a sentence may be ended by a period, a question mark, or an -exclamation mark. Indeed, in English, only clauses that end with one -of those three characters should be considered the end of a sentence. -This means that the pattern should include the character set: - -@smallexample -[.?!] -@end smallexample - -However, we do not want @code{forward-sentence} merely to jump to a -period, a question mark, or an exclamation mark, because such a character -might be used in the middle of a sentence. A period, for example, is -used after abbreviations. So other information is needed. - -According to convention, you type two spaces after every sentence, but -only one space after a period, a question mark, or an exclamation mark in -the body of a sentence. So a period, a question mark, or an exclamation -mark followed by two spaces is a good indicator of an end of sentence. -However, in a file, the two spaces may instead be a tab or the end of a -line. This means that the regular expression should include these three -items as alternatives. - -@need 800 -This group of alternatives will look like this: - -@smallexample -@group -\\($\\| \\| \\) - ^ ^^ - TAB SPC -@end group -@end smallexample - -@noindent -Here, @samp{$} indicates the end of the line, and I have pointed out -where the tab and two spaces are inserted in the expression. Both are -inserted by putting the actual characters into the expression. - -Two backslashes, @samp{\\}, are required before the parentheses and -vertical bars: the first backslash quotes the following backslash in -Emacs; and the second indicates that the following character, the -parenthesis or the vertical bar, is special. - -@need 1000 -Also, a sentence may be followed by one or more carriage returns, like -this: - -@smallexample -@group -[ -]* -@end group -@end smallexample - -@noindent -Like tabs and spaces, a carriage return is inserted into a regular -expression by inserting it literally. The asterisk indicates that the -@key{RET} is repeated zero or more times. - -But a sentence end does not consist only of a period, a question mark or -an exclamation mark followed by appropriate space: a closing quotation -mark or a closing brace of some kind may precede the space. Indeed more -than one such mark or brace may precede the space. These require a -expression that looks like this: - -@smallexample -[]\"')@}]* -@end smallexample - -In this expression, the first @samp{]} is the first character in the -expression; the second character is @samp{"}, which is preceded by a -@samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last -three characters are @samp{'}, @samp{)}, and @samp{@}}. - -All this suggests what the regular expression pattern for matching the -end of a sentence should be; and, indeed, if we evaluate -@code{sentence-end} we find that it returns the following value: - -@smallexample -@group -sentence-end - @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[ -]*" -@end group -@end smallexample - -@noindent -(Well, not in GNU Emacs 22; that is because of an effort to make the -process simpler and to handle more glyphs and languages. When the -value of @code{sentence-end} is @code{nil}, then use the value defined -by the function @code{sentence-end}. (Here is a use of the difference -between a value and a function in Emacs Lisp.) The function returns a -value constructed from the variables @code{sentence-end-base}, -@code{sentence-end-double-space}, @code{sentence-end-without-period}, -and @code{sentence-end-without-space}. The critical variable is -@code{sentence-end-base}; its global value is similar to the one -described above but it also contains two additional quotation marks. -These have differing degrees of curliness. The -@code{sentence-end-without-period} variable, when true, tells Emacs -that a sentence may end without a period, such as text in Thai.) - -@ignore -@noindent -(Note that here the @key{TAB}, two spaces, and @key{RET} are shown -literally in the pattern.) - -This regular expression can be deciphered as follows: - -@table @code -@item [.?!] -The first part of the pattern is the three characters, a period, a question -mark and an exclamation mark, within square brackets. The pattern must -begin with one or other of these characters. - -@item []\"')@}]* -The second part of the pattern is the group of closing braces and -quotation marks, which can appear zero or more times. These may follow -the period, question mark or exclamation mark. In a regular expression, -the backslash, @samp{\}, followed by the double quotation mark, -@samp{"}, indicates the class of string-quote characters. Usually, the -double quotation mark is the only character in this class. The -asterisk, @samp{*}, indicates that the items in the previous group (the -group surrounded by square brackets, @samp{[]}) may be repeated zero or -more times. - -@item \\($\\| \\| \\) -The third part of the pattern is one or other of: either the end of a -line, or two blank spaces, or a tab. The double back-slashes are used -to prevent Emacs from reading the parentheses and vertical bars as part -of the search pattern; the parentheses are used to mark the group and -the vertical bars are used to indicated that the patterns to either side -of them are alternatives. The dollar sign is used to indicate the end -of a line and both the two spaces and the tab are each inserted as is to -indicate what they are. - -@item [@key{RET}]* -Finally, the last part of the pattern indicates that the end of the line -or the whitespace following the period, question mark or exclamation -mark may, but need not, be followed by one or more carriage returns. In -the pattern, the carriage return is inserted as an actual carriage -return between square brackets but here it is shown as @key{RET}. -@end table -@end ignore - -@node re-search-forward, forward-sentence, sentence-end, Regexp Search -@comment node-name, next, previous, up -@section The @code{re-search-forward} Function -@findex re-search-forward - -The @code{re-search-forward} function is very like the -@code{search-forward} function. (@xref{search-forward, , The -@code{search-forward} Function}.) - -@code{re-search-forward} searches for a regular expression. If the -search is successful, it leaves point immediately after the last -character in the target. If the search is backwards, it leaves point -just before the first character in the target. You may tell -@code{re-search-forward} to return @code{t} for true. (Moving point -is therefore a `side effect'.) - -Like @code{search-forward}, the @code{re-search-forward} function takes -four arguments: - -@enumerate -@item -The first argument is the regular expression that the function searches -for. The regular expression will be a string between quotation marks. - -@item -The optional second argument limits how far the function will search; it is a -bound, which is specified as a position in the buffer. - -@item -The optional third argument specifies how the function responds to -failure: @code{nil} as the third argument causes the function to -signal an error (and print a message) when the search fails; any other -value causes it to return @code{nil} if the search fails and @code{t} -if the search succeeds. - -@item -The optional fourth argument is the repeat count. A negative repeat -count causes @code{re-search-forward} to search backwards. -@end enumerate - -@need 800 -The template for @code{re-search-forward} looks like this: - -@smallexample -@group -(re-search-forward "@var{regular-expression}" - @var{limit-of-search} - @var{what-to-do-if-search-fails} - @var{repeat-count}) -@end group -@end smallexample - -The second, third, and fourth arguments are optional. However, if you -want to pass a value to either or both of the last two arguments, you -must also pass a value to all the preceding arguments. Otherwise, the -Lisp interpreter will mistake which argument you are passing the value -to. - -@need 1200 -In the @code{forward-sentence} function, the regular expression will be -the value of the variable @code{sentence-end}. In simple form, that is: - -@smallexample -@group -"[.?!][]\"')@}]*\\($\\| \\| \\)[ -]*" -@end group -@end smallexample - -@noindent -The limit of the search will be the end of the paragraph (since a -sentence cannot go beyond a paragraph). If the search fails, the -function will return @code{nil}; and the repeat count will be provided -by the argument to the @code{forward-sentence} function. - -@node forward-sentence, forward-paragraph, re-search-forward, Regexp Search -@comment node-name, next, previous, up -@section @code{forward-sentence} -@findex forward-sentence - -The command to move the cursor forward a sentence is a straightforward -illustration of how to use regular expression searches in Emacs Lisp. -Indeed, the function looks longer and more complicated than it is; this -is because the function is designed to go backwards as well as forwards; -and, optionally, over more than one sentence. The function is usually -bound to the key command @kbd{M-e}. - -@menu -* Complete forward-sentence:: -* fwd-sentence while loops:: Two @code{while} loops. -* fwd-sentence re-search:: A regular expression search. -@end menu - -@node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence -@ifnottex -@unnumberedsubsec Complete @code{forward-sentence} function definition -@end ifnottex - -@need 1250 -Here is the code for @code{forward-sentence}: - -@c in GNU Emacs 22 -@smallexample -@group -(defun forward-sentence (&optional arg) - "Move forward to next `sentence-end'. With argument, repeat. -With negative argument, move backward repeatedly to `sentence-beginning'. - -The variable `sentence-end' is a regular expression that matches ends of -sentences. Also, every paragraph boundary terminates sentences as well." -@end group -@group - (interactive "p") - (or arg (setq arg 1)) - (let ((opoint (point)) - (sentence-end (sentence-end))) - (while (< arg 0) - (let ((pos (point)) - (par-beg (save-excursion (start-of-paragraph-text) (point)))) - (if (and (re-search-backward sentence-end par-beg t) - (or (< (match-end 0) pos) - (re-search-backward sentence-end par-beg t))) - (goto-char (match-end 0)) - (goto-char par-beg))) - (setq arg (1+ arg))) -@end group -@group - (while (> arg 0) - (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) - (if (re-search-forward sentence-end par-end t) - (skip-chars-backward " \t\n") - (goto-char par-end))) - (setq arg (1- arg))) - (constrain-to-field nil opoint t))) -@end group -@end smallexample - -@ignore -GNU Emacs 21 -@smallexample -@group -(defun forward-sentence (&optional arg) - "Move forward to next sentence-end. With argument, repeat. -With negative argument, move backward repeatedly to sentence-beginning. -Sentence ends are identified by the value of sentence-end -treated as a regular expression. Also, every paragraph boundary -terminates sentences as well." -@end group -@group - (interactive "p") - (or arg (setq arg 1)) - (while (< arg 0) - (let ((par-beg - (save-excursion (start-of-paragraph-text) (point)))) - (if (re-search-backward - (concat sentence-end "[^ \t\n]") par-beg t) - (goto-char (1- (match-end 0))) - (goto-char par-beg))) - (setq arg (1+ arg))) - (while (> arg 0) - (let ((par-end - (save-excursion (end-of-paragraph-text) (point)))) - (if (re-search-forward sentence-end par-end t) - (skip-chars-backward " \t\n") - (goto-char par-end))) - (setq arg (1- arg)))) -@end group -@end smallexample -@end ignore - -The function looks long at first sight and it is best to look at its -skeleton first, and then its muscle. The way to see the skeleton is to -look at the expressions that start in the left-most columns: - -@smallexample -@group -(defun forward-sentence (&optional arg) - "@var{documentation}@dots{}" - (interactive "p") - (or arg (setq arg 1)) - (let ((opoint (point)) (sentence-end (sentence-end))) - (while (< arg 0) - (let ((pos (point)) - (par-beg (save-excursion (start-of-paragraph-text) (point)))) - @var{rest-of-body-of-while-loop-when-going-backwards} - (while (> arg 0) - (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) - @var{rest-of-body-of-while-loop-when-going-forwards} - @var{handle-forms-and-equivalent} -@end group -@end smallexample - -This looks much simpler! The function definition consists of -documentation, an @code{interactive} expression, an @code{or} -expression, a @code{let} expression, and @code{while} loops. - -Let's look at each of these parts in turn. - -We note that the documentation is thorough and understandable. - -The function has an @code{interactive "p"} declaration. This means -that the processed prefix argument, if any, is passed to the -function as its argument. (This will be a number.) If the function -is not passed an argument (it is optional) then the argument -@code{arg} will be bound to 1. - -When @code{forward-sentence} is called non-interactively without an -argument, @code{arg} is bound to @code{nil}. The @code{or} expression -handles this. What it does is either leave the value of @code{arg} as -it is, but only if @code{arg} is bound to a value; or it sets the -value of @code{arg} to 1, in the case when @code{arg} is bound to -@code{nil}. - -Next is a @code{let}. That specifies the values of two local -variables, @code{point} and @code{sentence-end}. The local value of -point, from before the search, is used in the -@code{constrain-to-field} function which handles forms and -equivalents. The @code{sentence-end} variable is set by the -@code{sentence-end} function. - -@node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence -@unnumberedsubsec The @code{while} loops - -Two @code{while} loops follow. The first @code{while} has a -true-or-false-test that tests true if the prefix argument for -@code{forward-sentence} is a negative number. This is for going -backwards. The body of this loop is similar to the body of the second -@code{while} clause, but it is not exactly the same. We will skip -this @code{while} loop and concentrate on the second @code{while} -loop. - -@need 1500 -The second @code{while} loop is for moving point forward. Its skeleton -looks like this: - -@smallexample -@group -(while (> arg 0) ; @r{true-or-false-test} - (let @var{varlist} - (if (@var{true-or-false-test}) - @var{then-part} - @var{else-part} - (setq arg (1- arg)))) ; @code{while} @r{loop decrementer} -@end group -@end smallexample - -The @code{while} loop is of the decrementing kind. -(@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It -has a true-or-false-test that tests true so long as the counter (in -this case, the variable @code{arg}) is greater than zero; and it has a -decrementer that subtracts 1 from the value of the counter every time -the loop repeats. - -If no prefix argument is given to @code{forward-sentence}, which is -the most common way the command is used, this @code{while} loop will -run once, since the value of @code{arg} will be 1. - -The body of the @code{while} loop consists of a @code{let} expression, -which creates and binds a local variable, and has, as its body, an -@code{if} expression. - -@need 1250 -The body of the @code{while} loop looks like this: - -@smallexample -@group -(let ((par-end - (save-excursion (end-of-paragraph-text) (point)))) - (if (re-search-forward sentence-end par-end t) - (skip-chars-backward " \t\n") - (goto-char par-end))) -@end group -@end smallexample - -The @code{let} expression creates and binds the local variable -@code{par-end}. As we shall see, this local variable is designed to -provide a bound or limit to the regular expression search. If the -search fails to find a proper sentence ending in the paragraph, it will -stop on reaching the end of the paragraph. - -But first, let us examine how @code{par-end} is bound to the value of -the end of the paragraph. What happens is that the @code{let} sets the -value of @code{par-end} to the value returned when the Lisp interpreter -evaluates the expression - -@smallexample -@group -(save-excursion (end-of-paragraph-text) (point)) -@end group -@end smallexample - -@noindent -In this expression, @code{(end-of-paragraph-text)} moves point to the -end of the paragraph, @code{(point)} returns the value of point, and then -@code{save-excursion} restores point to its original position. Thus, -the @code{let} binds @code{par-end} to the value returned by the -@code{save-excursion} expression, which is the position of the end of -the paragraph. (The @code{end-of-paragraph-text} function uses -@code{forward-paragraph}, which we will discuss shortly.) - -@need 1200 -Emacs next evaluates the body of the @code{let}, which is an @code{if} -expression that looks like this: - -@smallexample -@group -(if (re-search-forward sentence-end par-end t) ; @r{if-part} - (skip-chars-backward " \t\n") ; @r{then-part} - (goto-char par-end))) ; @r{else-part} -@end group -@end smallexample - -The @code{if} tests whether its first argument is true and if so, -evaluates its then-part; otherwise, the Emacs Lisp interpreter -evaluates the else-part. The true-or-false-test of the @code{if} -expression is the regular expression search. - -It may seem odd to have what looks like the `real work' of -the @code{forward-sentence} function buried here, but this is a common -way this kind of operation is carried out in Lisp. - -@node fwd-sentence re-search, , fwd-sentence while loops, forward-sentence -@unnumberedsubsec The regular expression search - -The @code{re-search-forward} function searches for the end of the -sentence, that is, for the pattern defined by the @code{sentence-end} -regular expression. If the pattern is found---if the end of the sentence is -found---then the @code{re-search-forward} function does two things: - -@enumerate -@item -The @code{re-search-forward} function carries out a side effect, which -is to move point to the end of the occurrence found. - -@item -The @code{re-search-forward} function returns a value of true. This is -the value received by the @code{if}, and means that the search was -successful. -@end enumerate - -@noindent -The side effect, the movement of point, is completed before the -@code{if} function is handed the value returned by the successful -conclusion of the search. - -When the @code{if} function receives the value of true from a successful -call to @code{re-search-forward}, the @code{if} evaluates the then-part, -which is the expression @code{(skip-chars-backward " \t\n")}. This -expression moves backwards over any blank spaces, tabs or carriage -returns until a printed character is found and then leaves point after -the character. Since point has already been moved to the end of the -pattern that marks the end of the sentence, this action leaves point -right after the closing printed character of the sentence, which is -usually a period. - -On the other hand, if the @code{re-search-forward} function fails to -find a pattern marking the end of the sentence, the function returns -false. The false then causes the @code{if} to evaluate its third -argument, which is @code{(goto-char par-end)}: it moves point to the -end of the paragraph. - -(And if the text is in a form or equivalent, and point may not move -fully, then the @code{constrain-to-field} function comes into play.) - -Regular expression searches are exceptionally useful and the pattern -illustrated by @code{re-search-forward}, in which the search is the -test of an @code{if} expression, is handy. You will see or write code -incorporating this pattern often. - -@node forward-paragraph, etags, forward-sentence, Regexp Search -@comment node-name, next, previous, up -@section @code{forward-paragraph}: a Goldmine of Functions -@findex forward-paragraph - -@ignore -@c in GNU Emacs 22 -(defun forward-paragraph (&optional arg) - "Move forward to end of paragraph. -With argument ARG, do it ARG times; -a negative argument ARG = -N means move backward N paragraphs. - -A line which `paragraph-start' matches either separates paragraphs -\(if `paragraph-separate' matches it also) or is the first line of a paragraph. -A paragraph end is the beginning of a line which is not part of the paragraph -to which the end of the previous line belongs, or the end of the buffer. -Returns the count of paragraphs left to move." - (interactive "p") - (or arg (setq arg 1)) - (let* ((opoint (point)) - (fill-prefix-regexp - (and fill-prefix (not (equal fill-prefix "")) - (not paragraph-ignore-fill-prefix) - (regexp-quote fill-prefix))) - ;; Remove ^ from paragraph-start and paragraph-sep if they are there. - ;; These regexps shouldn't be anchored, because we look for them - ;; starting at the left-margin. This allows paragraph commands to - ;; work normally with indented text. - ;; This hack will not find problem cases like "whatever\\|^something". - (parstart (if (and (not (equal "" paragraph-start)) - (equal ?^ (aref paragraph-start 0))) - (substring paragraph-start 1) - paragraph-start)) - (parsep (if (and (not (equal "" paragraph-separate)) - (equal ?^ (aref paragraph-separate 0))) - (substring paragraph-separate 1) - paragraph-separate)) - (parsep - (if fill-prefix-regexp - (concat parsep "\\|" - fill-prefix-regexp "[ \t]*$") - parsep)) - ;; This is used for searching. - (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)")) - start found-start) - (while (and (< arg 0) (not (bobp))) - (if (and (not (looking-at parsep)) - (re-search-backward "^\n" (max (1- (point)) (point-min)) t) - (looking-at parsep)) - (setq arg (1+ arg)) - (setq start (point)) - ;; Move back over paragraph-separating lines. - (forward-char -1) (beginning-of-line) - (while (and (not (bobp)) - (progn (move-to-left-margin) - (looking-at parsep))) - (forward-line -1)) - (if (bobp) - nil - (setq arg (1+ arg)) - ;; Go to end of the previous (non-separating) line. - (end-of-line) - ;; Search back for line that starts or separates paragraphs. - (if (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart. - (let (multiple-lines) - (while (and (progn (beginning-of-line) (not (bobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (looking-at fill-prefix-regexp)) - (unless (= (point) start) - (setq multiple-lines t)) - (forward-line -1)) - (move-to-left-margin) - ;; This deleted code caused a long hanging-indent line - ;; not to be filled together with the following lines. - ;; ;; Don't move back over a line before the paragraph - ;; ;; which doesn't start with fill-prefix - ;; ;; unless that is the only line we've moved over. - ;; (and (not (looking-at fill-prefix-regexp)) - ;; multiple-lines - ;; (forward-line 1)) - (not (bobp))) - (while (and (re-search-backward sp-parstart nil 1) - (setq found-start t) - ;; Found a candidate, but need to check if it is a - ;; REAL parstart. - (progn (setq start (point)) - (move-to-left-margin) - (not (looking-at parsep))) - (not (and (looking-at parstart) - (or (not use-hard-newlines) - (bobp) - (get-text-property - (1- start) 'hard))))) - (setq found-start nil) - (goto-char start)) - found-start) - ;; Found one. - (progn - ;; Move forward over paragraph separators. - ;; We know this cannot reach the place we started - ;; because we know we moved back over a non-separator. - (while (and (not (eobp)) - (progn (move-to-left-margin) - (looking-at parsep))) - (forward-line 1)) - ;; If line before paragraph is just margin, back up to there. - (end-of-line 0) - (if (> (current-column) (current-left-margin)) - (forward-char 1) - (skip-chars-backward " \t") - (if (not (bolp)) - (forward-line 1)))) - ;; No starter or separator line => use buffer beg. - (goto-char (point-min)))))) - - (while (and (> arg 0) (not (eobp))) - ;; Move forward over separator lines... - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (looking-at parsep)) - (forward-line 1)) - (unless (eobp) (setq arg (1- arg))) - ;; ... and one more line. - (forward-line 1) - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart. - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) - (if (< (point) (point-max)) - (goto-char start)))) - (constrain-to-field nil opoint t) - ;; Return the number of steps that could not be done. - arg)) -@end ignore - -The @code{forward-paragraph} function moves point forward to the end -of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a -number of functions that are important in themselves, including -@code{let*}, @code{match-beginning}, and @code{looking-at}. - -The function definition for @code{forward-paragraph} is considerably -longer than the function definition for @code{forward-sentence} -because it works with a paragraph, each line of which may begin with a -fill prefix. - -A fill prefix consists of a string of characters that are repeated at -the beginning of each line. For example, in Lisp code, it is a -convention to start each line of a paragraph-long comment with -@samp{;;; }. In Text mode, four blank spaces make up another common -fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , , -emacs, The GNU Emacs Manual}, for more information about fill -prefixes.) - -The existence of a fill prefix means that in addition to being able to -find the end of a paragraph whose lines begin on the left-most -column, the @code{forward-paragraph} function must be able to find the -end of a paragraph when all or many of the lines in the buffer begin -with the fill prefix. - -Moreover, it is sometimes practical to ignore a fill prefix that -exists, especially when blank lines separate paragraphs. -This is an added complication. - -@menu -* forward-paragraph in brief:: Key parts of the function definition. -* fwd-para let:: The @code{let*} expression. -* fwd-para while:: The forward motion @code{while} loop. -@end menu - -@node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph -@ifnottex -@unnumberedsubsec Shortened @code{forward-paragraph} function definition -@end ifnottex - -Rather than print all of the @code{forward-paragraph} function, we -will only print parts of it. Read without preparation, the function -can be daunting! - -@need 800 -In outline, the function looks like this: - -@smallexample -@group -(defun forward-paragraph (&optional arg) - "@var{documentation}@dots{}" - (interactive "p") - (or arg (setq arg 1)) - (let* - @var{varlist} - (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code} - @dots{} - (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code} - @dots{} -@end group -@end smallexample - -The first parts of the function are routine: the function's argument -list consists of one optional argument. Documentation follows. - -The lower case @samp{p} in the @code{interactive} declaration means -that the processed prefix argument, if any, is passed to the function. -This will be a number, and is the repeat count of how many paragraphs -point will move. The @code{or} expression in the next line handles -the common case when no argument is passed to the function, which occurs -if the function is called from other code rather than interactively. -This case was described earlier. (@xref{forward-sentence, The -@code{forward-sentence} function}.) Now we reach the end of the -familiar part of this function. - -@node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph -@unnumberedsubsec The @code{let*} expression - -The next line of the @code{forward-paragraph} function begins a -@code{let*} expression. This is a different than @code{let}. The -symbol is @code{let*} not @code{let}. - -The @code{let*} special form is like @code{let} except that Emacs sets -each variable in sequence, one after another, and variables in the -latter part of the varlist can make use of the values to which Emacs -set variables in the earlier part of the varlist. - -@ignore -( refappend save-excursion, , code save-excursion in code append-to-buffer .) -@end ignore - -(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.) - -In the @code{let*} expression in this function, Emacs binds a total of -seven variables: @code{opoint}, @code{fill-prefix-regexp}, -@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and -@code{found-start}. - -The variable @code{parsep} appears twice, first, to remove instances -of @samp{^}, and second, to handle fill prefixes. - -The variable @code{opoint} is just the value of @code{point}. As you -can guess, it is used in a @code{constrain-to-field} expression, just -as in @code{forward-sentence}. - -The variable @code{fill-prefix-regexp} is set to the value returned by -evaluating the following list: - -@smallexample -@group -(and fill-prefix - (not (equal fill-prefix "")) - (not paragraph-ignore-fill-prefix) - (regexp-quote fill-prefix)) -@end group -@end smallexample - -@noindent -This is an expression whose first element is the @code{and} special form. - -As we learned earlier (@pxref{kill-new function, , The @code{kill-new} -function}), the @code{and} special form evaluates each of its -arguments until one of the arguments returns a value of @code{nil}, in -which case the @code{and} expression returns @code{nil}; however, if -none of the arguments returns a value of @code{nil}, the value -resulting from evaluating the last argument is returned. (Since such -a value is not @code{nil}, it is considered true in Lisp.) In other -words, an @code{and} expression returns a true value only if all its -arguments are true. -@findex and - -In this case, the variable @code{fill-prefix-regexp} is bound to a -non-@code{nil} value only if the following four expressions produce a -true (i.e., a non-@code{nil}) value when they are evaluated; otherwise, -@code{fill-prefix-regexp} is bound to @code{nil}. - -@table @code -@item fill-prefix -When this variable is evaluated, the value of the fill prefix, if any, -is returned. If there is no fill prefix, this variable returns -@code{nil}. - -@item (not (equal fill-prefix "") -This expression checks whether an existing fill prefix is an empty -string, that is, a string with no characters in it. An empty string is -not a useful fill prefix. - -@item (not paragraph-ignore-fill-prefix) -This expression returns @code{nil} if the variable -@code{paragraph-ignore-fill-prefix} has been turned on by being set to a -true value such as @code{t}. - -@item (regexp-quote fill-prefix) -This is the last argument to the @code{and} special form. If all the -arguments to the @code{and} are true, the value resulting from -evaluating this expression will be returned by the @code{and} expression -and bound to the variable @code{fill-prefix-regexp}, -@end table - -@findex regexp-quote -@noindent -The result of evaluating this @code{and} expression successfully is that -@code{fill-prefix-regexp} will be bound to the value of -@code{fill-prefix} as modified by the @code{regexp-quote} function. -What @code{regexp-quote} does is read a string and return a regular -expression that will exactly match the string and match nothing else. -This means that @code{fill-prefix-regexp} will be set to a value that -will exactly match the fill prefix if the fill prefix exists. -Otherwise, the variable will be set to @code{nil}. - -The next two local variables in the @code{let*} expression are -designed to remove instances of @samp{^} from @code{parstart} and -@code{parsep}, the local variables which indicate the paragraph start -and the paragraph separator. The next expression sets @code{parsep} -again. That is to handle fill prefixes. - -This is the setting that requires the definition call @code{let*} -rather than @code{let}. The true-or-false-test for the @code{if} -depends on whether the variable @code{fill-prefix-regexp} evaluates to -@code{nil} or some other value. - -If @code{fill-prefix-regexp} does not have a value, Emacs evaluates -the else-part of the @code{if} expression and binds @code{parsep} to -its local value. (@code{parsep} is a regular expression that matches -what separates paragraphs.) - -But if @code{fill-prefix-regexp} does have a value, Emacs evaluates -the then-part of the @code{if} expression and binds @code{parsep} to a -regular expression that includes the @code{fill-prefix-regexp} as part -of the pattern. - -Specifically, @code{parsep} is set to the original value of the -paragraph separate regular expression concatenated with an alternative -expression that consists of the @code{fill-prefix-regexp} followed by -optional whitespace to the end of the line. The whitespace is defined -by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the -regexp as an alternative to @code{parsep}. - -According to a comment in the code, the next local variable, -@code{sp-parstart}, is used for searching, and then the final two, -@code{start} and @code{found-start}, are set to @code{nil}. - -Now we get into the body of the @code{let*}. The first part of the body -of the @code{let*} deals with the case when the function is given a -negative argument and is therefore moving backwards. We will skip this -section. - -@node fwd-para while, , fwd-para let, forward-paragraph -@unnumberedsubsec The forward motion @code{while} loop - -The second part of the body of the @code{let*} deals with forward -motion. It is a @code{while} loop that repeats itself so long as the -value of @code{arg} is greater than zero. In the most common use of -the function, the value of the argument is 1, so the body of the -@code{while} loop is evaluated exactly once, and the cursor moves -forward one paragraph. - -@ignore -(while (and (> arg 0) (not (eobp))) - - ;; Move forward over separator lines... - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (looking-at parsep)) - (forward-line 1)) - (unless (eobp) (setq arg (1- arg))) - ;; ... and one more line. - (forward-line 1) - - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart. - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) - - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) - - (if (< (point) (point-max)) - (goto-char start)))) -@end ignore - -This part handles three situations: when point is between paragraphs, -when there is a fill prefix and when there is no fill prefix. - -@need 800 -The @code{while} loop looks like this: - -@smallexample -@group -;; @r{going forwards and not at the end of the buffer} -(while (and (> arg 0) (not (eobp))) - - ;; @r{between paragraphs} - ;; Move forward over separator lines... - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (looking-at parsep)) - (forward-line 1)) - ;; @r{This decrements the loop} - (unless (eobp) (setq arg (1- arg))) - ;; ... and one more line. - (forward-line 1) -@end group - -@group - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart; - ;; we go forward line by line - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) -@end group - -@group - ;; There is no fill prefix; - ;; we go forward character by character - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) -@end group - -@group - ;; and if there is no fill prefix and if we are not at the end, - ;; go to whatever was found in the regular expression search - ;; for sp-parstart - (if (< (point) (point-max)) - (goto-char start)))) -@end group -@end smallexample - -@findex eobp -We can see that this is a decrementing counter @code{while} loop, -using the expression @code{(setq arg (1- arg))} as the decrementer. -That expression is not far from the @code{while}, but is hidden in -another Lisp macro, an @code{unless} macro. Unless we are at the end -of the buffer --- that is what the @code{eobp} function determines; it -is an abbreviation of @samp{End Of Buffer P} --- we decrease the value -of @code{arg} by one. - -(If we are at the end of the buffer, we cannot go forward any more and -the next loop of the @code{while} expression will test false since the -test is an @code{and} with @code{(not (eobp))}. The @code{not} -function means exactly as you expect; it is another name for -@code{null}, a function that returns true when its argument is false.) - -Interestingly, the loop count is not decremented until we leave the -space between paragraphs, unless we come to the end of buffer or stop -seeing the local value of the paragraph separator. - -That second @code{while} also has a @code{(move-to-left-margin)} -expression. The function is self-explanatory. It is inside a -@code{progn} expression and not the last element of its body, so it is -only invoked for its side effect, which is to move point to the left -margin of the current line. - -@findex looking-at -The @code{looking-at} function is also self-explanatory; it returns -true if the text after point matches the regular expression given as -its argument. - -The rest of the body of the loop looks difficult at first, but makes -sense as you come to understand it. - -@need 800 -First consider what happens if there is a fill prefix: - -@smallexample -@group - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart; - ;; we go forward line by line - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) -@end group -@end smallexample - -@noindent -This expression moves point forward line by line so long -as four conditions are true: - -@enumerate -@item -Point is not at the end of the buffer. - -@item -We can move to the left margin of the text and are -not at the end of the buffer. - -@item -The text following point does not separate paragraphs. - -@item -The pattern following point is the fill prefix regular expression. -@end enumerate - -The last condition may be puzzling, until you remember that point was -moved to the beginning of the line early in the @code{forward-paragraph} -function. This means that if the text has a fill prefix, the -@code{looking-at} function will see it. - -@need 1250 -Consider what happens when there is no fill prefix. - -@smallexample -@group - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) -@end group -@end smallexample - -@noindent -This @code{while} loop has us searching forward for -@code{sp-parstart}, which is the combination of possible whitespace -with a the local value of the start of a paragraph or of a paragraph -separator. (The latter two are within an expression starting -@code{\(?:} so that they are not referenced by the -@code{match-beginning} function.) - -@need 800 -The two expressions, - -@smallexample -@group -(setq start (match-beginning 0)) -(goto-char start) -@end group -@end smallexample - -@noindent -mean go to the start of the text matched by the regular expression -search. - -The @code{(match-beginning 0)} expression is new. It returns a number -specifying the location of the start of the text that was matched by -the last search. - -The @code{match-beginning} function is used here because of a -characteristic of a forward search: a successful forward search, -regardless of whether it is a plain search or a regular expression -search, moves point to the end of the text that is found. In this -case, a successful search moves point to the end of the pattern for -@code{sp-parstart}. - -However, we want to put point at the end of the current paragraph, not -somewhere else. Indeed, since the search possibly includes the -paragraph separator, point may end up at the beginning of the next one -unless we use an expression that includes @code{match-beginning}. - -@findex match-beginning -When given an argument of 0, @code{match-beginning} returns the -position that is the start of the text matched by the most recent -search. In this case, the most recent search looks for -@code{sp-parstart}. The @code{(match-beginning 0)} expression returns -the beginning position of that pattern, rather than the end position -of that pattern. - -(Incidentally, when passed a positive number as an argument, the -@code{match-beginning} function returns the location of point at that -parenthesized expression in the last search unless that parenthesized -expression begins with @code{\(?:}. I don't know why @code{\(?:} -appears here since the argument is 0.) - -@need 1250 -The last expression when there is no fill prefix is - -@smallexample -@group -(if (< (point) (point-max)) - (goto-char start)))) -@end group -@end smallexample - -@noindent -This says that if there is no fill prefix and if we are not at the -end, point should move to the beginning of whatever was found by the -regular expression search for @code{sp-parstart}. - -The full definition for the @code{forward-paragraph} function not only -includes code for going forwards, but also code for going backwards. - -If you are reading this inside of GNU Emacs and you want to see the -whole function, you can type @kbd{C-h f} (@code{describe-function}) -and the name of the function. This gives you the function -documentation and the name of the library containing the function's -source. Place point over the name of the library and press the RET -key; you will be taken directly to the source. (Be sure to install -your sources! Without them, you are like a person who tries to drive -a car with his eyes shut!) - -@node etags, Regexp Review, forward-paragraph, Regexp Search -@section Create Your Own @file{TAGS} File -@findex etags -@cindex @file{TAGS} file, create own - -Besides @kbd{C-h f} (@code{describe-function}), another way to see the -source of a function is to type @kbd{M-.} (@code{find-tag}) and the -name of the function when prompted for it. This is a good habit to -get into. The @kbd{M-.} (@code{find-tag}) command takes you directly -to the source for a function, variable, or node. The function depends -on tags tables to tell it where to go. - -If the @code{find-tag} function first asks you for the name of a -@file{TAGS} table, give it the name of a @file{TAGS} file such as -@file{/usr/local/src/emacs/src/TAGS}. (The exact path to your -@file{TAGS} file depends on how your copy of Emacs was installed. I -just told you the location that provides both my C and my Emacs Lisp -sources.) - -You can also create your own @file{TAGS} file for directories that -lack one. - -You often need to build and install tags tables yourself. They are -not built automatically. A tags table is called a @file{TAGS} file; -the name is in upper case letters. - -You can create a @file{TAGS} file by calling the @code{etags} program -that comes as a part of the Emacs distribution. Usually, @code{etags} -is compiled and installed when Emacs is built. (@code{etags} is not -an Emacs Lisp function or a part of Emacs; it is a C program.) - -@need 1250 -To create a @file{TAGS} file, first switch to the directory in which -you want to create the file. In Emacs you can do this with the -@kbd{M-x cd} command, or by visiting a file in the directory, or by -listing the directory with @kbd{C-x d} (@code{dired}). Then run the -compile command, with @w{@code{etags *.el}} as the command to execute - -@smallexample -M-x compile RET etags *.el RET -@end smallexample - -@noindent -to create a @file{TAGS} file for Emacs Lisp. - -For example, if you have a large number of files in your -@file{~/emacs} directory, as I do---I have 137 @file{.el} files in it, -of which I load 12---you can create a @file{TAGS} file for the Emacs -Lisp files in that directory. - -@need 1250 -The @code{etags} program takes all the usual shell `wildcards'. For -example, if you have two directories for which you want a single -@file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where -@file{../elisp/} is the second directory: - -@smallexample -M-x compile RET etags *.el ../elisp/*.el RET -@end smallexample - -@need 1250 -Type - -@smallexample -M-x compile RET etags --help RET -@end smallexample - -@noindent -to see a list of the options accepted by @code{etags} as well as a -list of supported languages. - -The @code{etags} program handles more than 20 languages, including -Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java, -LaTeX, Pascal, Perl, PostScript, Python, TeX, Texinfo, makefiles, and -most assemblers. The program has no switches for specifying the -language; it recognizes the language in an input file according to its -file name and contents. - -@file{etags} is very helpful when you are writing code yourself and -want to refer back to functions you have already written. Just run -@code{etags} again at intervals as you write new functions, so they -become part of the @file{TAGS} file. - -If you think an appropriate @file{TAGS} file already exists for what -you want, but do not know where it is, you can use the @code{locate} -program to attempt to find it. - -Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list -for you the full path names of all your @file{TAGS} files. On my -system, this command lists 34 @file{TAGS} files. On the other hand, a -`plain vanilla' system I recently installed did not contain any -@file{TAGS} files. - -If the tags table you want has been created, you can use the @code{M-x -visit-tags-table} command to specify it. Otherwise, you will need to -create the tag table yourself and then use @code{M-x -visit-tags-table}. - -@subsubheading Building Tags in the Emacs sources -@cindex Building Tags in the Emacs sources -@cindex Tags in the Emacs sources -@findex make tags - -The GNU Emacs sources come with a @file{Makefile} that contains a -sophisticated @code{etags} command that creates, collects, and merges -tags tables from all over the Emacs sources and puts the information -into one @file{TAGS} file in the @file{src/} directory. (The -@file{src/} directory is below the top level of your Emacs directory.) - -@need 1250 -To build this @file{TAGS} file, go to the top level of your Emacs -source directory and run the compile command @code{make tags}: - -@smallexample -M-x compile RET make tags RET -@end smallexample - -@noindent -(The @code{make tags} command works well with the GNU Emacs sources, -as well as with some other source packages.) - -For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs -Manual}. - -@node Regexp Review, re-search Exercises, etags, Regexp Search -@comment node-name, next, previous, up -@section Review - -Here is a brief summary of some recently introduced functions. - -@table @code -@item while -Repeatedly evaluate the body of the expression so long as the first -element of the body tests true. Then return @code{nil}. (The -expression is evaluated only for its side effects.) - -@need 1250 -For example: - -@smallexample -@group -(let ((foo 2)) - (while (> foo 0) - (insert (format "foo is %d.\n" foo)) - (setq foo (1- foo)))) - - @result{} foo is 2. - foo is 1. - nil -@end group -@end smallexample - -@noindent -(The @code{insert} function inserts its arguments at point; the -@code{format} function returns a string formatted from its arguments -the way @code{message} formats its arguments; @code{\n} produces a new -line.) - -@item re-search-forward -Search for a pattern, and if the pattern is found, move point to rest -just after it. - -@noindent -Takes four arguments, like @code{search-forward}: - -@enumerate -@item -A regular expression that specifies the pattern to search for. -(Remember to put quotation marks around this argument!) - -@item -Optionally, the limit of the search. - -@item -Optionally, what to do if the search fails, return @code{nil} or an -error message. - -@item -Optionally, how many times to repeat the search; if negative, the -search goes backwards. -@end enumerate - -@item let* -Bind some variables locally to particular values, -and then evaluate the remaining arguments, returning the value of the -last one. While binding the local variables, use the local values of -variables bound earlier, if any. - -@need 1250 -For example: - -@smallexample -@group -(let* ((foo 7) - (bar (* 3 foo))) - (message "`bar' is %d." bar)) - @result{} `bar' is 21. -@end group -@end smallexample - -@item match-beginning -Return the position of the start of the text found by the last regular -expression search. - -@item looking-at -Return @code{t} for true if the text after point matches the argument, -which should be a regular expression. - -@item eobp -Return @code{t} for true if point is at the end of the accessible part -of a buffer. The end of the accessible part is the end of the buffer -if the buffer is not narrowed; it is the end of the narrowed part if -the buffer is narrowed. -@end table - -@need 1500 -@node re-search Exercises, , Regexp Review, Regexp Search -@section Exercises with @code{re-search-forward} - -@itemize @bullet -@item -Write a function to search for a regular expression that matches two -or more blank lines in sequence. - -@item -Write a function to search for duplicated words, such as `the the'. -@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs -Manual}, for information on how to write a regexp (a regular -expression) to match a string that is composed of two identical -halves. You can devise several regexps; some are better than others. -The function I use is described in an appendix, along with several -regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}. -@end itemize - -@node Counting Words, Words in a defun, Regexp Search, Top -@chapter Counting: Repetition and Regexps -@cindex Repetition for word counting -@cindex Regular expressions for word counting - -Repetition and regular expression searches are powerful tools that you -often use when you write code in Emacs Lisp. This chapter illustrates -the use of regular expression searches through the construction of -word count commands using @code{while} loops and recursion. - -@menu -* Why Count Words:: -* @value{COUNT-WORDS}:: Use a regexp, but find a problem. -* recursive-count-words:: Start with case of no words in region. -* Counting Exercise:: -@end menu - -@node Why Count Words, @value{COUNT-WORDS}, Counting Words, Counting Words -@ifnottex -@unnumberedsec Counting words -@end ifnottex - -The standard Emacs distribution contains functions for counting the -number of lines and words within a region. - -Certain types of writing ask you to count words. Thus, if you write -an essay, you may be limited to 800 words; if you write a novel, you -may discipline yourself to write 1000 words a day. It seems odd, but -for a long time, Emacs lacked a word count command. Perhaps people used -Emacs mostly for code or types of documentation that did not require -word counts; or perhaps they restricted themselves to the operating -system word count command, @code{wc}. Alternatively, people may have -followed the publishers' convention and computed a word count by -dividing the number of characters in a document by five. - -There are many ways to implement a command to count words. Here are -some examples, which you may wish to compare with the standard Emacs -command, @code{count-words-region}. - -@node @value{COUNT-WORDS}, recursive-count-words, Why Count Words, Counting Words -@comment node-name, next, previous, up -@section The @code{@value{COUNT-WORDS}} Function -@findex @value{COUNT-WORDS} - -A word count command could count words in a line, paragraph, region, -or buffer. What should the command cover? You could design the -command to count the number of words in a complete buffer. However, -the Emacs tradition encourages flexibility---you may want to count -words in just a section, rather than all of a buffer. So it makes -more sense to design the command to count the number of words in a -region. Once you have a command to count words in a region, you can, -if you wish, count words in a whole buffer by marking it with -@w{@kbd{C-x h}} (@code{mark-whole-buffer}). - -Clearly, counting words is a repetitive act: starting from the -beginning of the region, you count the first word, then the second -word, then the third word, and so on, until you reach the end of the -region. This means that word counting is ideally suited to recursion -or to a @code{while} loop. - -@menu -* Design @value{COUNT-WORDS}:: The definition using a @code{while} loop. -* Whitespace Bug:: The Whitespace Bug in @code{@value{COUNT-WORDS}}. -@end menu - -@node Design @value{COUNT-WORDS}, Whitespace Bug, @value{COUNT-WORDS}, @value{COUNT-WORDS} -@ifnottex -@unnumberedsubsec Designing @code{@value{COUNT-WORDS}} -@end ifnottex - -First, we will implement the word count command with a @code{while} -loop, then with recursion. The command will, of course, be -interactive. - -@need 800 -The template for an interactive function definition is, as always: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (@var{interactive-expression}@dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -What we need to do is fill in the slots. - -The name of the function should be self-explanatory and similar to the -existing @code{count-lines-region} name. This makes the name easier -to remember. @code{count-words-region} is the obvious choice. Since -that name is now used for the standard Emacs command to count words, we -will name our implementation @code{@value{COUNT-WORDS}}. - -The function counts words within a region. This means that the -argument list must contain symbols that are bound to the two -positions, the beginning and end of the region. These two positions -can be called @samp{beginning} and @samp{end} respectively. The first -line of the documentation should be a single sentence, since that is -all that is printed as documentation by a command such as -@code{apropos}. The interactive expression will be of the form -@samp{(interactive "r")}, since that will cause Emacs to pass the -beginning and end of the region to the function's argument list. All -this is routine. - -The body of the function needs to be written to do three tasks: -first, to set up conditions under which the @code{while} loop can -count words, second, to run the @code{while} loop, and third, to send -a message to the user. - -When a user calls @code{@value{COUNT-WORDS}}, point may be at the -beginning or the end of the region. However, the counting process -must start at the beginning of the region. This means we will want -to put point there if it is not already there. Executing -@code{(goto-char beginning)} ensures this. Of course, we will want to -return point to its expected position when the function finishes its -work. For this reason, the body must be enclosed in a -@code{save-excursion} expression. - -The central part of the body of the function consists of a -@code{while} loop in which one expression jumps point forward word by -word, and another expression counts those jumps. The true-or-false-test -of the @code{while} loop should test true so long as point should jump -forward, and false when point is at the end of the region. - -We could use @code{(forward-word 1)} as the expression for moving point -forward word by word, but it is easier to see what Emacs identifies as a -`word' if we use a regular expression search. - -A regular expression search that finds the pattern for which it is -searching leaves point after the last character matched. This means -that a succession of successful word searches will move point forward -word by word. - -As a practical matter, we want the regular expression search to jump -over whitespace and punctuation between words as well as over the -words themselves. A regexp that refuses to jump over interword -whitespace would never jump more than one word! This means that -the regexp should include the whitespace and punctuation that follows -a word, if any, as well as the word itself. (A word may end a buffer -and not have any following whitespace or punctuation, so that part of -the regexp must be optional.) - -Thus, what we want for the regexp is a pattern defining one or more -word constituent characters followed, optionally, by one or more -characters that are not word constituents. The regular expression for -this is: - -@smallexample -\w+\W* -@end smallexample - -@noindent -The buffer's syntax table determines which characters are and are not -word constituents. For more information about syntax, -@pxref{Syntax Tables, , Syntax Tables, elisp, The GNU Emacs Lisp -Reference Manual}. - -@need 800 -The search expression looks like this: - -@smallexample -(re-search-forward "\\w+\\W*") -@end smallexample - -@noindent -(Note that paired backslashes precede the @samp{w} and @samp{W}. A -single backslash has special meaning to the Emacs Lisp interpreter. -It indicates that the following character is interpreted differently -than usual. For example, the two characters, @samp{\n}, stand for -@samp{newline}, rather than for a backslash followed by @samp{n}. Two -backslashes in a row stand for an ordinary, `unspecial' backslash, so -Emacs Lisp interpreter ends of seeing a single backslash followed by a -letter. So it discovers the letter is special.) - -We need a counter to count how many words there are; this variable -must first be set to 0 and then incremented each time Emacs goes -around the @code{while} loop. The incrementing expression is simply: - -@smallexample -(setq count (1+ count)) -@end smallexample - -Finally, we want to tell the user how many words there are in the -region. The @code{message} function is intended for presenting this -kind of information to the user. The message has to be phrased so -that it reads properly regardless of how many words there are in the -region: we don't want to say that ``there are 1 words in the region''. -The conflict between singular and plural is ungrammatical. We can -solve this problem by using a conditional expression that evaluates -different messages depending on the number of words in the region. -There are three possibilities: no words in the region, one word in the -region, and more than one word. This means that the @code{cond} -special form is appropriate. - -@need 1500 -All this leads to the following function definition: - -@smallexample -@group -;;; @r{First version; has bugs!} -(defun @value{COUNT-WORDS} (beginning end) - "Print number of words in the region. -Words are defined as at least one word-constituent -character followed by at least one character that -is not a word-constituent. The buffer's syntax -table determines which characters these are." - (interactive "r") - (message "Counting words in region ... ") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (save-excursion - (goto-char beginning) - (let ((count 0)) -@end group - -@group -;;; @r{2. Run the} while @r{loop.} - (while (< (point) end) - (re-search-forward "\\w+\\W*") - (setq count (1+ count))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message - "The region does NOT have any words.")) - ((= 1 count) - (message - "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -@noindent -As written, the function works, but not in all circumstances. - -@node Whitespace Bug, , Design @value{COUNT-WORDS}, @value{COUNT-WORDS} -@comment node-name, next, previous, up -@subsection The Whitespace Bug in @code{@value{COUNT-WORDS}} - -The @code{@value{COUNT-WORDS}} command described in the preceding -section has two bugs, or rather, one bug with two manifestations. -First, if you mark a region containing only whitespace in the middle -of some text, the @code{@value{COUNT-WORDS}} command tells you that the -region contains one word! Second, if you mark a region containing -only whitespace at the end of the buffer or the accessible portion of -a narrowed buffer, the command displays an error message that looks -like this: - -@smallexample -Search failed: "\\w+\\W*" -@end smallexample - -If you are reading this in Info in GNU Emacs, you can test for these -bugs yourself. - -First, evaluate the function in the usual manner to install it. -@ifinfo -Here is a copy of the definition. Place your cursor after the closing -parenthesis and type @kbd{C-x C-e} to install it. - -@smallexample -@group -;; @r{First version; has bugs!} -(defun @value{COUNT-WORDS} (beginning end) - "Print number of words in the region. -Words are defined as at least one word-constituent character followed -by at least one character that is not a word-constituent. The buffer's -syntax table determines which characters these are." -@end group -@group - (interactive "r") - (message "Counting words in region ... ") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (save-excursion - (goto-char beginning) - (let ((count 0)) -@end group - -@group -;;; @r{2. Run the} while @r{loop.} - (while (< (point) end) - (re-search-forward "\\w+\\W*") - (setq count (1+ count))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message "The region does NOT have any words.")) - ((= 1 count) (message "The region has 1 word.")) - (t (message "The region has %d words." count)))))) -@end group -@end smallexample -@end ifinfo - -@need 1000 -If you wish, you can also install this keybinding by evaluating it: - -@smallexample -(global-set-key "\C-c=" '@value{COUNT-WORDS}) -@end smallexample - -To conduct the first test, set mark and point to the beginning and end -of the following line and then type @kbd{C-c =} (or @kbd{M-x -@value{COUNT-WORDS}} if you have not bound @kbd{C-c =}): - -@smallexample - one two three -@end smallexample - -@noindent -Emacs will tell you, correctly, that the region has three words. - -Repeat the test, but place mark at the beginning of the line and place -point just @emph{before} the word @samp{one}. Again type the command -@kbd{C-c =} (or @kbd{M-x @value{COUNT-WORDS}}). Emacs should tell you -that the region has no words, since it is composed only of the -whitespace at the beginning of the line. But instead Emacs tells you -that the region has one word! - -For the third test, copy the sample line to the end of the -@file{*scratch*} buffer and then type several spaces at the end of the -line. Place mark right after the word @samp{three} and point at the -end of line. (The end of the line will be the end of the buffer.) -Type @kbd{C-c =} (or @kbd{M-x @value{COUNT-WORDS}}) as you did before. -Again, Emacs should tell you that the region has no words, since it is -composed only of the whitespace at the end of the line. Instead, -Emacs displays an error message saying @samp{Search failed}. - -The two bugs stem from the same problem. - -Consider the first manifestation of the bug, in which the command -tells you that the whitespace at the beginning of the line contains -one word. What happens is this: The @code{M-x @value{COUNT-WORDS}} -command moves point to the beginning of the region. The @code{while} -tests whether the value of point is smaller than the value of -@code{end}, which it is. Consequently, the regular expression search -looks for and finds the first word. It leaves point after the word. -@code{count} is set to one. The @code{while} loop repeats; but this -time the value of point is larger than the value of @code{end}, the -loop is exited; and the function displays a message saying the number -of words in the region is one. In brief, the regular expression -search looks for and finds the word even though it is outside -the marked region. - -In the second manifestation of the bug, the region is whitespace at -the end of the buffer. Emacs says @samp{Search failed}. What happens -is that the true-or-false-test in the @code{while} loop tests true, so -the search expression is executed. But since there are no more words -in the buffer, the search fails. - -In both manifestations of the bug, the search extends or attempts to -extend outside of the region. - -The solution is to limit the search to the region---this is a fairly -simple action, but as you may have come to expect, it is not quite as -simple as you might think. - -As we have seen, the @code{re-search-forward} function takes a search -pattern as its first argument. But in addition to this first, -mandatory argument, it accepts three optional arguments. The optional -second argument bounds the search. The optional third argument, if -@code{t}, causes the function to return @code{nil} rather than signal -an error if the search fails. The optional fourth argument is a -repeat count. (In Emacs, you can see a function's documentation by -typing @kbd{C-h f}, the name of the function, and then @key{RET}.) - -In the @code{@value{COUNT-WORDS}} definition, the value of the end of -the region is held by the variable @code{end} which is passed as an -argument to the function. Thus, we can add @code{end} as an argument -to the regular expression search expression: - -@smallexample -(re-search-forward "\\w+\\W*" end) -@end smallexample - -However, if you make only this change to the @code{@value{COUNT-WORDS}} -definition and then test the new version of the definition on a -stretch of whitespace, you will receive an error message saying -@samp{Search failed}. - -What happens is this: the search is limited to the region, and fails -as you expect because there are no word-constituent characters in the -region. Since it fails, we receive an error message. But we do not -want to receive an error message in this case; we want to receive the -message that "The region does NOT have any words." - -The solution to this problem is to provide @code{re-search-forward} -with a third argument of @code{t}, which causes the function to return -@code{nil} rather than signal an error if the search fails. - -However, if you make this change and try it, you will see the message -``Counting words in region ... '' and @dots{} you will keep on seeing -that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}). - -Here is what happens: the search is limited to the region, as before, -and it fails because there are no word-constituent characters in the -region, as expected. Consequently, the @code{re-search-forward} -expression returns @code{nil}. It does nothing else. In particular, -it does not move point, which it does as a side effect if it finds the -search target. After the @code{re-search-forward} expression returns -@code{nil}, the next expression in the @code{while} loop is evaluated. -This expression increments the count. Then the loop repeats. The -true-or-false-test tests true because the value of point is still less -than the value of end, since the @code{re-search-forward} expression -did not move point. @dots{} and the cycle repeats @dots{} - -The @code{@value{COUNT-WORDS}} definition requires yet another -modification, to cause the true-or-false-test of the @code{while} loop -to test false if the search fails. Put another way, there are two -conditions that must be satisfied in the true-or-false-test before the -word count variable is incremented: point must still be within the -region and the search expression must have found a word to count. - -Since both the first condition and the second condition must be true -together, the two expressions, the region test and the search -expression, can be joined with an @code{and} special form and embedded in -the @code{while} loop as the true-or-false-test, like this: - -@smallexample -(and (< (point) end) (re-search-forward "\\w+\\W*" end t)) -@end smallexample - -@c colon in printed section title causes problem in Info cross reference -@c also trouble with an overfull hbox -@iftex -@noindent -(For information about @code{and}, see -@ref{kill-new function, , The @code{kill-new} function}.) -@end iftex -@ifinfo -@noindent -(@xref{kill-new function, , The @code{kill-new} function}, for -information about @code{and}.) -@end ifinfo - -The @code{re-search-forward} expression returns @code{t} if the search -succeeds and as a side effect moves point. Consequently, as words are -found, point is moved through the region. When the search expression -fails to find another word, or when point reaches the end of the -region, the true-or-false-test tests false, the @code{while} loop -exits, and the @code{@value{COUNT-WORDS}} function displays one or -other of its messages. - -After incorporating these final changes, the @code{@value{COUNT-WORDS}} -works without bugs (or at least, without bugs that I have found!). -Here is what it looks like: - -@smallexample -@group -;;; @r{Final version:} @code{while} -(defun @value{COUNT-WORDS} (beginning end) - "Print number of words in the region." - (interactive "r") - (message "Counting words in region ... ") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (save-excursion - (let ((count 0)) - (goto-char beginning) -@end group - -@group -;;; @r{2. Run the} while @r{loop.} - (while (and (< (point) end) - (re-search-forward "\\w+\\W*" end t)) - (setq count (1+ count))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message - "The region does NOT have any words.")) - ((= 1 count) - (message - "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -@node recursive-count-words, Counting Exercise, @value{COUNT-WORDS}, Counting Words -@comment node-name, next, previous, up -@section Count Words Recursively -@cindex Count words recursively -@cindex Recursively counting words -@cindex Words, counted recursively - -You can write the function for counting words recursively as well as -with a @code{while} loop. Let's see how this is done. - -First, we need to recognize that the @code{@value{COUNT-WORDS}} -function has three jobs: it sets up the appropriate conditions for -counting to occur; it counts the words in the region; and it sends a -message to the user telling how many words there are. - -If we write a single recursive function to do everything, we will -receive a message for every recursive call. If the region contains 13 -words, we will receive thirteen messages, one right after the other. -We don't want this! Instead, we must write two functions to do the -job, one of which (the recursive function) will be used inside of the -other. One function will set up the conditions and display the -message; the other will return the word count. - -Let us start with the function that causes the message to be displayed. -We can continue to call this @code{@value{COUNT-WORDS}}. - -This is the function that the user will call. It will be interactive. -Indeed, it will be similar to our previous versions of this -function, except that it will call @code{recursive-count-words} to -determine how many words are in the region. - -@need 1250 -We can readily construct a template for this function, based on our -previous versions: - -@smallexample -@group -;; @r{Recursive version; uses regular expression search} -(defun @value{COUNT-WORDS} (beginning end) - "@var{documentation}@dots{}" - (@var{interactive-expression}@dots{}) -@end group -@group - -;;; @r{1. Set up appropriate conditions.} - (@var{explanatory message}) - (@var{set-up functions}@dots{} -@end group -@group - -;;; @r{2. Count the words.} - @var{recursive call} -@end group -@group - -;;; @r{3. Send a message to the user.} - @var{message providing word count})) -@end group -@end smallexample - -The definition looks straightforward, except that somehow the count -returned by the recursive call must be passed to the message -displaying the word count. A little thought suggests that this can be -done by making use of a @code{let} expression: we can bind a variable -in the varlist of a @code{let} expression to the number of words in -the region, as returned by the recursive call; and then the -@code{cond} expression, using binding, can display the value to the -user. - -Often, one thinks of the binding within a @code{let} expression as -somehow secondary to the `primary' work of a function. But in this -case, what you might consider the `primary' job of the function, -counting words, is done within the @code{let} expression. - -@need 1250 -Using @code{let}, the function definition looks like this: - -@smallexample -@group -(defun @value{COUNT-WORDS} (beginning end) - "Print number of words in the region." - (interactive "r") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (message "Counting words in region ... ") - (save-excursion - (goto-char beginning) -@end group - -@group -;;; @r{2. Count the words.} - (let ((count (recursive-count-words end))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message - "The region does NOT have any words.")) - ((= 1 count) - (message - "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -Next, we need to write the recursive counting function. - -A recursive function has at least three parts: the `do-again-test', the -`next-step-expression', and the recursive call. - -The do-again-test determines whether the function will or will not be -called again. Since we are counting words in a region and can use a -function that moves point forward for every word, the do-again-test -can check whether point is still within the region. The do-again-test -should find the value of point and determine whether point is before, -at, or after the value of the end of the region. We can use the -@code{point} function to locate point. Clearly, we must pass the -value of the end of the region to the recursive counting function as an -argument. - -In addition, the do-again-test should also test whether the search finds a -word. If it does not, the function should not call itself again. - -The next-step-expression changes a value so that when the recursive -function is supposed to stop calling itself, it stops. More -precisely, the next-step-expression changes a value so that at the -right time, the do-again-test stops the recursive function from -calling itself again. In this case, the next-step-expression can be -the expression that moves point forward, word by word. - -The third part of a recursive function is the recursive call. - -Somewhere, also, we also need a part that does the `work' of the -function, a part that does the counting. A vital part! - -@need 1250 -But already, we have an outline of the recursive counting function: - -@smallexample -@group -(defun recursive-count-words (region-end) - "@var{documentation}@dots{}" - @var{do-again-test} - @var{next-step-expression} - @var{recursive call}) -@end group -@end smallexample - -Now we need to fill in the slots. Let's start with the simplest cases -first: if point is at or beyond the end of the region, there cannot -be any words in the region, so the function should return zero. -Likewise, if the search fails, there are no words to count, so the -function should return zero. - -On the other hand, if point is within the region and the search -succeeds, the function should call itself again. - -@need 800 -Thus, the do-again-test should look like this: - -@smallexample -@group -(and (< (point) region-end) - (re-search-forward "\\w+\\W*" region-end t)) -@end group -@end smallexample - -Note that the search expression is part of the do-again-test---the -function returns @code{t} if its search succeeds and @code{nil} if it -fails. (@xref{Whitespace Bug, , The Whitespace Bug in -@code{@value{COUNT-WORDS}}}, for an explanation of how -@code{re-search-forward} works.) - -The do-again-test is the true-or-false test of an @code{if} clause. -Clearly, if the do-again-test succeeds, the then-part of the @code{if} -clause should call the function again; but if it fails, the else-part -should return zero since either point is outside the region or the -search failed because there were no words to find. - -But before considering the recursive call, we need to consider the -next-step-expression. What is it? Interestingly, it is the search -part of the do-again-test. - -In addition to returning @code{t} or @code{nil} for the -do-again-test, @code{re-search-forward} moves point forward as a side -effect of a successful search. This is the action that changes the -value of point so that the recursive function stops calling itself -when point completes its movement through the region. Consequently, -the @code{re-search-forward} expression is the next-step-expression. - -@need 1200 -In outline, then, the body of the @code{recursive-count-words} -function looks like this: - -@smallexample -@group -(if @var{do-again-test-and-next-step-combined} - ;; @r{then} - @var{recursive-call-returning-count} - ;; @r{else} - @var{return-zero}) -@end group -@end smallexample - -How to incorporate the mechanism that counts? - -If you are not used to writing recursive functions, a question like -this can be troublesome. But it can and should be approached -systematically. - -We know that the counting mechanism should be associated in some way -with the recursive call. Indeed, since the next-step-expression moves -point forward by one word, and since a recursive call is made for -each word, the counting mechanism must be an expression that adds one -to the value returned by a call to @code{recursive-count-words}. - -@need 800 -Consider several cases: - -@itemize @bullet -@item -If there are two words in the region, the function should return -a value resulting from adding one to the value returned when it counts -the first word, plus the number returned when it counts the remaining -words in the region, which in this case is one. - -@item -If there is one word in the region, the function should return -a value resulting from adding one to the value returned when it counts -that word, plus the number returned when it counts the remaining -words in the region, which in this case is zero. - -@item -If there are no words in the region, the function should return zero. -@end itemize - -From the sketch we can see that the else-part of the @code{if} returns -zero for the case of no words. This means that the then-part of the -@code{if} must return a value resulting from adding one to the value -returned from a count of the remaining words. - -@need 1200 -The expression will look like this, where @code{1+} is a function that -adds one to its argument. - -@smallexample -(1+ (recursive-count-words region-end)) -@end smallexample - -@need 1200 -The whole @code{recursive-count-words} function will then look like -this: - -@smallexample -@group -(defun recursive-count-words (region-end) - "@var{documentation}@dots{}" - -;;; @r{1. do-again-test} - (if (and (< (point) region-end) - (re-search-forward "\\w+\\W*" region-end t)) -@end group - -@group -;;; @r{2. then-part: the recursive call} - (1+ (recursive-count-words region-end)) - -;;; @r{3. else-part} - 0)) -@end group -@end smallexample - -@need 1250 -Let's examine how this works: - -If there are no words in the region, the else part of the @code{if} -expression is evaluated and consequently the function returns zero. - -If there is one word in the region, the value of point is less than -the value of @code{region-end} and the search succeeds. In this case, -the true-or-false-test of the @code{if} expression tests true, and the -then-part of the @code{if} expression is evaluated. The counting -expression is evaluated. This expression returns a value (which will -be the value returned by the whole function) that is the sum of one -added to the value returned by a recursive call. - -Meanwhile, the next-step-expression has caused point to jump over the -first (and in this case only) word in the region. This means that -when @code{(recursive-count-words region-end)} is evaluated a second -time, as a result of the recursive call, the value of point will be -equal to or greater than the value of region end. So this time, -@code{recursive-count-words} will return zero. The zero will be added -to one, and the original evaluation of @code{recursive-count-words} -will return one plus zero, which is one, which is the correct amount. - -Clearly, if there are two words in the region, the first call to -@code{recursive-count-words} returns one added to the value returned -by calling @code{recursive-count-words} on a region containing the -remaining word---that is, it adds one to one, producing two, which is -the correct amount. - -Similarly, if there are three words in the region, the first call to -@code{recursive-count-words} returns one added to the value returned -by calling @code{recursive-count-words} on a region containing the -remaining two words---and so on and so on. - -@need 1250 -@noindent -With full documentation the two functions look like this: - -@need 1250 -@noindent -The recursive function: - -@findex recursive-count-words -@smallexample -@group -(defun recursive-count-words (region-end) - "Number of words between point and REGION-END." -@end group - -@group -;;; @r{1. do-again-test} - (if (and (< (point) region-end) - (re-search-forward "\\w+\\W*" region-end t)) -@end group - -@group -;;; @r{2. then-part: the recursive call} - (1+ (recursive-count-words region-end)) - -;;; @r{3. else-part} - 0)) -@end group -@end smallexample - -@need 800 -@noindent -The wrapper: - -@smallexample -@group -;;; @r{Recursive version} -(defun @value{COUNT-WORDS} (beginning end) - "Print number of words in the region. -@end group - -@group -Words are defined as at least one word-constituent -character followed by at least one character that is -not a word-constituent. The buffer's syntax table -determines which characters these are." -@end group -@group - (interactive "r") - (message "Counting words in region ... ") - (save-excursion - (goto-char beginning) - (let ((count (recursive-count-words end))) -@end group -@group - (cond ((zerop count) - (message - "The region does NOT have any words.")) -@end group -@group - ((= 1 count) - (message "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -@node Counting Exercise, , recursive-count-words, Counting Words -@section Exercise: Counting Punctuation - -Using a @code{while} loop, write a function to count the number of -punctuation marks in a region---period, comma, semicolon, colon, -exclamation mark, and question mark. Do the same using recursion. - -@node Words in a defun, Readying a Graph, Counting Words, Top -@chapter Counting Words in a @code{defun} -@cindex Counting words in a @code{defun} -@cindex Word counting in a @code{defun} - -Our next project is to count the number of words in a function -definition. Clearly, this can be done using some variant of -@code{@value{COUNT-WORDS}}. @xref{Counting Words, , Counting Words: -Repetition and Regexps}. If we are just going to count the words in -one definition, it is easy enough to mark the definition with the -@kbd{C-M-h} (@code{mark-defun}) command, and then call -@code{@value{COUNT-WORDS}}. - -However, I am more ambitious: I want to count the words and symbols in -every definition in the Emacs sources and then print a graph that -shows how many functions there are of each length: how many contain 40 -to 49 words or symbols, how many contain 50 to 59 words or symbols, -and so on. I have often been curious how long a typical function is, -and this will tell. - -@menu -* Divide and Conquer:: -* Words and Symbols:: What to count? -* Syntax:: What constitutes a word or symbol? -* count-words-in-defun:: Very like @code{@value{COUNT-WORDS}}. -* Several defuns:: Counting several defuns in a file. -* Find a File:: Do you want to look at a file? -* lengths-list-file:: A list of the lengths of many definitions. -* Several files:: Counting in definitions in different files. -* Several files recursively:: Recursively counting in different files. -* Prepare the data:: Prepare the data for display in a graph. -@end menu - -@node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun -@ifnottex -@unnumberedsec Divide and Conquer -@end ifnottex - -Described in one phrase, the histogram project is daunting; but -divided into numerous small steps, each of which we can take one at a -time, the project becomes less fearsome. Let us consider what the -steps must be: - -@itemize @bullet -@item -First, write a function to count the words in one definition. This -includes the problem of handling symbols as well as words. - -@item -Second, write a function to list the numbers of words in each function -in a file. This function can use the @code{count-words-in-defun} -function. - -@item -Third, write a function to list the numbers of words in each function -in each of several files. This entails automatically finding the -various files, switching to them, and counting the words in the -definitions within them. - -@item -Fourth, write a function to convert the list of numbers that we -created in step three to a form that will be suitable for printing as -a graph. - -@item -Fifth, write a function to print the results as a graph. -@end itemize - -This is quite a project! But if we take each step slowly, it will not -be difficult. - -@node Words and Symbols, Syntax, Divide and Conquer, Words in a defun -@section What to Count? -@cindex Words and symbols in defun - -When we first start thinking about how to count the words in a -function definition, the first question is (or ought to be) what are -we going to count? When we speak of `words' with respect to a Lisp -function definition, we are actually speaking, in large part, of -`symbols'. For example, the following @code{multiply-by-seven} -function contains the five symbols @code{defun}, -@code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In -addition, in the documentation string, it contains the four words -@samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The -symbol @samp{number} is repeated, so the definition contains a total -of ten words and symbols. - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) -@end group -@end smallexample - -@noindent -However, if we mark the @code{multiply-by-seven} definition with -@kbd{C-M-h} (@code{mark-defun}), and then call -@code{@value{COUNT-WORDS}} on it, we will find that -@code{@value{COUNT-WORDS}} claims the definition has eleven words, not -ten! Something is wrong! - -The problem is twofold: @code{@value{COUNT-WORDS}} does not count the -@samp{*} as a word, and it counts the single symbol, -@code{multiply-by-seven}, as containing three words. The hyphens are -treated as if they were interword spaces rather than intraword -connectors: @samp{multiply-by-seven} is counted as if it were written -@samp{multiply by seven}. - -The cause of this confusion is the regular expression search within -the @code{@value{COUNT-WORDS}} definition that moves point forward word -by word. In the canonical version of @code{@value{COUNT-WORDS}}, the -regexp is: - -@smallexample -"\\w+\\W*" -@end smallexample - -@noindent -This regular expression is a pattern defining one or more word -constituent characters possibly followed by one or more characters -that are not word constituents. What is meant by `word constituent -characters' brings us to the issue of syntax, which is worth a section -of its own. - -@node Syntax, count-words-in-defun, Words and Symbols, Words in a defun -@section What Constitutes a Word or Symbol? -@cindex Syntax categories and tables - -Emacs treats different characters as belonging to different -@dfn{syntax categories}. For example, the regular expression, -@samp{\\w+}, is a pattern specifying one or more @emph{word -constituent} characters. Word constituent characters are members of -one syntax category. Other syntax categories include the class of -punctuation characters, such as the period and the comma, and the -class of whitespace characters, such as the blank space and the tab -character. (For more information, @pxref{Syntax Tables, , Syntax -Tables, elisp, The GNU Emacs Lisp Reference Manual}.) - -Syntax tables specify which characters belong to which categories. -Usually, a hyphen is not specified as a `word constituent character'. -Instead, it is specified as being in the `class of characters that are -part of symbol names but not words.' This means that the -@code{@value{COUNT-WORDS}} function treats it in the same way it treats -an interword white space, which is why @code{@value{COUNT-WORDS}} -counts @samp{multiply-by-seven} as three words. - -There are two ways to cause Emacs to count @samp{multiply-by-seven} as -one symbol: modify the syntax table or modify the regular expression. - -We could redefine a hyphen as a word constituent character by -modifying the syntax table that Emacs keeps for each mode. This -action would serve our purpose, except that a hyphen is merely the -most common character within symbols that is not typically a word -constituent character; there are others, too. - -Alternatively, we can redefine the regexp used in the -@code{@value{COUNT-WORDS}} definition so as to include symbols. This -procedure has the merit of clarity, but the task is a little tricky. - -@need 1200 -The first part is simple enough: the pattern must match ``at least one -character that is a word or symbol constituent''. Thus: - -@smallexample -"\\(\\w\\|\\s_\\)+" -@end smallexample - -@noindent -The @samp{\\(} is the first part of the grouping construct that -includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated -by the @samp{\\|}. The @samp{\\w} matches any word-constituent -character and the @samp{\\s_} matches any character that is part of a -symbol name but not a word-constituent character. The @samp{+} -following the group indicates that the word or symbol constituent -characters must be matched at least once. - -However, the second part of the regexp is more difficult to design. -What we want is to follow the first part with ``optionally one or more -characters that are not constituents of a word or symbol''. At first, -I thought I could define this with the following: - -@smallexample -"\\(\\W\\|\\S_\\)*" -@end smallexample - -@noindent -The upper case @samp{W} and @samp{S} match characters that are -@emph{not} word or symbol constituents. Unfortunately, this -expression matches any character that is either not a word constituent -or not a symbol constituent. This matches any character! - -I then noticed that every word or symbol in my test region was -followed by white space (blank space, tab, or newline). So I tried -placing a pattern to match one or more blank spaces after the pattern -for one or more word or symbol constituents. This failed, too. Words -and symbols are often separated by whitespace, but in actual code -parentheses may follow symbols and punctuation may follow words. So -finally, I designed a pattern in which the word or symbol constituents -are followed optionally by characters that are not white space and -then followed optionally by white space. - -@need 800 -Here is the full regular expression: - -@smallexample -"\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" -@end smallexample - -@node count-words-in-defun, Several defuns, Syntax, Words in a defun -@section The @code{count-words-in-defun} Function -@cindex Counting words in a @code{defun} - -We have seen that there are several ways to write a -@code{count-words-region} function. To write a -@code{count-words-in-defun}, we need merely adapt one of these -versions. - -The version that uses a @code{while} loop is easy to understand, so I -am going to adapt that. Because @code{count-words-in-defun} will be -part of a more complex program, it need not be interactive and it need -not display a message but just return the count. These considerations -simplify the definition a little. - -On the other hand, @code{count-words-in-defun} will be used within a -buffer that contains function definitions. Consequently, it is -reasonable to ask that the function determine whether it is called -when point is within a function definition, and if it is, to return -the count for that definition. This adds complexity to the -definition, but saves us from needing to pass arguments to the -function. - -@need 1250 -These considerations lead us to prepare the following template: - -@smallexample -@group -(defun count-words-in-defun () - "@var{documentation}@dots{}" - (@var{set up}@dots{} - (@var{while loop}@dots{}) - @var{return count}) -@end group -@end smallexample - -@noindent -As usual, our job is to fill in the slots. - -First, the set up. - -We are presuming that this function will be called within a buffer -containing function definitions. Point will either be within a -function definition or not. For @code{count-words-in-defun} to work, -point must move to the beginning of the definition, a counter must -start at zero, and the counting loop must stop when point reaches the -end of the definition. - -The @code{beginning-of-defun} function searches backwards for an -opening delimiter such as a @samp{(} at the beginning of a line, and -moves point to that position, or else to the limit of the search. In -practice, this means that @code{beginning-of-defun} moves point to the -beginning of an enclosing or preceding function definition, or else to -the beginning of the buffer. We can use @code{beginning-of-defun} to -place point where we wish to start. - -The @code{while} loop requires a counter to keep track of the words or -symbols being counted. A @code{let} expression can be used to create -a local variable for this purpose, and bind it to an initial value of zero. - -The @code{end-of-defun} function works like @code{beginning-of-defun} -except that it moves point to the end of the definition. -@code{end-of-defun} can be used as part of an expression that -determines the position of the end of the definition. - -The set up for @code{count-words-in-defun} takes shape rapidly: first -we move point to the beginning of the definition, then we create a -local variable to hold the count, and finally, we record the position -of the end of the definition so the @code{while} loop will know when to stop -looping. - -@need 1250 -The code looks like this: - -@smallexample -@group -(beginning-of-defun) -(let ((count 0) - (end (save-excursion (end-of-defun) (point)))) -@end group -@end smallexample - -@noindent -The code is simple. The only slight complication is likely to concern -@code{end}: it is bound to the position of the end of the definition -by a @code{save-excursion} expression that returns the value of point -after @code{end-of-defun} temporarily moves it to the end of the -definition. - -The second part of the @code{count-words-in-defun}, after the set up, -is the @code{while} loop. - -The loop must contain an expression that jumps point forward word by -word and symbol by symbol, and another expression that counts the -jumps. The true-or-false-test for the @code{while} loop should test -true so long as point should jump forward, and false when point is at -the end of the definition. We have already redefined the regular -expression for this, so the loop is straightforward: - -@smallexample -@group -(while (and (< (point) end) - (re-search-forward - "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t)) - (setq count (1+ count))) -@end group -@end smallexample - -The third part of the function definition returns the count of words -and symbols. This part is the last expression within the body of the -@code{let} expression, and can be, very simply, the local variable -@code{count}, which when evaluated returns the count. - -@need 1250 -Put together, the @code{count-words-in-defun} definition looks like this: - -@findex count-words-in-defun -@smallexample -@group -(defun count-words-in-defun () - "Return the number of words and symbols in a defun." - (beginning-of-defun) - (let ((count 0) - (end (save-excursion (end-of-defun) (point)))) -@end group -@group - (while - (and (< (point) end) - (re-search-forward - "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" - end t)) - (setq count (1+ count))) - count)) -@end group -@end smallexample - -How to test this? The function is not interactive, but it is easy to -put a wrapper around the function to make it interactive; we can use -almost the same code as for the recursive version of -@code{@value{COUNT-WORDS}}: - -@smallexample -@group -;;; @r{Interactive version.} -(defun count-words-defun () - "Number of words and symbols in a function definition." - (interactive) - (message - "Counting words and symbols in function definition ... ") -@end group -@group - (let ((count (count-words-in-defun))) - (cond - ((zerop count) - (message - "The definition does NOT have any words or symbols.")) -@end group -@group - ((= 1 count) - (message - "The definition has 1 word or symbol.")) - (t - (message - "The definition has %d words or symbols." count))))) -@end group -@end smallexample - -@need 800 -@noindent -Let's re-use @kbd{C-c =} as a convenient keybinding: - -@smallexample -(global-set-key "\C-c=" 'count-words-defun) -@end smallexample - -Now we can try out @code{count-words-defun}: install both -@code{count-words-in-defun} and @code{count-words-defun}, and set the -keybinding, and then place the cursor within the following definition: - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) - @result{} 10 -@end group -@end smallexample - -@noindent -Success! The definition has 10 words and symbols. - -The next problem is to count the numbers of words and symbols in -several definitions within a single file. - -@node Several defuns, Find a File, count-words-in-defun, Words in a defun -@section Count Several @code{defuns} Within a File - -A file such as @file{simple.el} may have a hundred or more function -definitions within it. Our long term goal is to collect statistics on -many files, but as a first step, our immediate goal is to collect -statistics on one file. - -The information will be a series of numbers, each number being the -length of a function definition. We can store the numbers in a list. - -We know that we will want to incorporate the information regarding one -file with information about many other files; this means that the -function for counting definition lengths within one file need only -return the list of lengths. It need not and should not display any -messages. - -The word count commands contain one expression to jump point forward -word by word and another expression to count the jumps. The function -to return the lengths of definitions can be designed to work the same -way, with one expression to jump point forward definition by -definition and another expression to construct the lengths' list. - -This statement of the problem makes it elementary to write the -function definition. Clearly, we will start the count at the -beginning of the file, so the first command will be @code{(goto-char -(point-min))}. Next, we start the @code{while} loop; and the -true-or-false test of the loop can be a regular expression search for -the next function definition---so long as the search succeeds, point -is moved forward and then the body of the loop is evaluated. The body -needs an expression that constructs the lengths' list. @code{cons}, -the list construction command, can be used to create the list. That -is almost all there is to it. - -@need 800 -Here is what this fragment of code looks like: - -@smallexample -@group -(goto-char (point-min)) -(while (re-search-forward "^(defun" nil t) - (setq lengths-list - (cons (count-words-in-defun) lengths-list))) -@end group -@end smallexample - -What we have left out is the mechanism for finding the file that -contains the function definitions. - -In previous examples, we either used this, the Info file, or we -switched back and forth to some other buffer, such as the -@file{*scratch*} buffer. - -Finding a file is a new process that we have not yet discussed. - -@node Find a File, lengths-list-file, Several defuns, Words in a defun -@comment node-name, next, previous, up -@section Find a File -@cindex Find a File - -To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file}) -command. This command is almost, but not quite right for the lengths -problem. - -@need 1200 -Let's look at the source for @code{find-file}: - -@smallexample -@group -(defun find-file (filename) - "Edit file FILENAME. -Switch to a buffer visiting file FILENAME, -creating one if none already exists." - (interactive "FFind file: ") - (switch-to-buffer (find-file-noselect filename))) -@end group -@end smallexample - -@noindent -(The most recent version of the @code{find-file} function definition -permits you to specify optional wildcards to visit multiple files; that -makes the definition more complex and we will not discuss it here, -since it is not relevant. You can see its source using either -@kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).) - -@ignore -In Emacs 22 -(defun find-file (filename &optional wildcards) - "Edit file FILENAME. -Switch to a buffer visiting file FILENAME, -creating one if none already exists. -Interactively, the default if you just type RET is the current directory, -but the visited file name is available through the minibuffer history: -type M-n to pull it into the minibuffer. - -Interactively, or if WILDCARDS is non-nil in a call from Lisp, -expand wildcards (if any) and visit multiple files. You can -suppress wildcard expansion by setting `find-file-wildcards' to nil. - -To visit a file without any kind of conversion and without -automatically choosing a major mode, use \\[find-file-literally]." - (interactive (find-file-read-args "Find file: " nil)) - (let ((value (find-file-noselect filename nil nil wildcards))) - (if (listp value) - (mapcar 'switch-to-buffer (nreverse value)) - (switch-to-buffer value)))) -@end ignore - -The definition I am showing possesses short but complete documentation -and an interactive specification that prompts you for a file name when -you use the command interactively. The body of the definition -contains two functions, @code{find-file-noselect} and -@code{switch-to-buffer}. - -According to its documentation as shown by @kbd{C-h f} (the -@code{describe-function} command), the @code{find-file-noselect} -function reads the named file into a buffer and returns the buffer. -(Its most recent version includes an optional wildcards argument, -too, as well as another to read a file literally and an other you -suppress warning messages. These optional arguments are irrelevant.) - -However, the @code{find-file-noselect} function does not select the -buffer in which it puts the file. Emacs does not switch its attention -(or yours if you are using @code{find-file-noselect}) to the selected -buffer. That is what @code{switch-to-buffer} does: it switches the -buffer to which Emacs attention is directed; and it switches the -buffer displayed in the window to the new buffer. We have discussed -buffer switching elsewhere. (@xref{Switching Buffers}.) - -In this histogram project, we do not need to display each file on the -screen as the program determines the length of each definition within -it. Instead of employing @code{switch-to-buffer}, we can work with -@code{set-buffer}, which redirects the attention of the computer -program to a different buffer but does not redisplay it on the screen. -So instead of calling on @code{find-file} to do the job, we must write -our own expression. - -The task is easy: use @code{find-file-noselect} and @code{set-buffer}. - -@node lengths-list-file, Several files, Find a File, Words in a defun -@section @code{lengths-list-file} in Detail - -The core of the @code{lengths-list-file} function is a @code{while} -loop containing a function to move point forward `defun by defun' and -a function to count the number of words and symbols in each defun. -This core must be surrounded by functions that do various other tasks, -including finding the file, and ensuring that point starts out at the -beginning of the file. The function definition looks like this: -@findex lengths-list-file - -@smallexample -@group -(defun lengths-list-file (filename) - "Return list of definitions' lengths within FILE. -The returned list is a list of numbers. -Each number is the number of words or -symbols in one function definition." -@end group -@group - (message "Working on `%s' ... " filename) - (save-excursion - (let ((buffer (find-file-noselect filename)) - (lengths-list)) - (set-buffer buffer) - (setq buffer-read-only t) - (widen) - (goto-char (point-min)) - (while (re-search-forward "^(defun" nil t) - (setq lengths-list - (cons (count-words-in-defun) lengths-list))) - (kill-buffer buffer) - lengths-list))) -@end group -@end smallexample - -@noindent -The function is passed one argument, the name of the file on which it -will work. It has four lines of documentation, but no interactive -specification. Since people worry that a computer is broken if they -don't see anything going on, the first line of the body is a -message. - -The next line contains a @code{save-excursion} that returns Emacs's -attention to the current buffer when the function completes. This is -useful in case you embed this function in another function that -presumes point is restored to the original buffer. - -In the varlist of the @code{let} expression, Emacs finds the file and -binds the local variable @code{buffer} to the buffer containing the -file. At the same time, Emacs creates @code{lengths-list} as a local -variable. - -Next, Emacs switches its attention to the buffer. - -In the following line, Emacs makes the buffer read-only. Ideally, -this line is not necessary. None of the functions for counting words -and symbols in a function definition should change the buffer. -Besides, the buffer is not going to be saved, even if it were changed. -This line is entirely the consequence of great, perhaps excessive, -caution. The reason for the caution is that this function and those -it calls work on the sources for Emacs and it is inconvenient if they -are inadvertently modified. It goes without saying that I did not -realize a need for this line until an experiment went awry and started -to modify my Emacs source files @dots{} - -Next comes a call to widen the buffer if it is narrowed. This -function is usually not needed---Emacs creates a fresh buffer if none -already exists; but if a buffer visiting the file already exists Emacs -returns that one. In this case, the buffer may be narrowed and must -be widened. If we wanted to be fully `user-friendly', we would -arrange to save the restriction and the location of point, but we -won't. - -The @code{(goto-char (point-min))} expression moves point to the -beginning of the buffer. - -Then comes a @code{while} loop in which the `work' of the function is -carried out. In the loop, Emacs determines the length of each -definition and constructs a lengths' list containing the information. - -Emacs kills the buffer after working through it. This is to save -space inside of Emacs. My version of GNU Emacs 19 contained over 300 -source files of interest; GNU Emacs 22 contains over a thousand source -files. Another function will apply @code{lengths-list-file} to each -of the files. - -Finally, the last expression within the @code{let} expression is the -@code{lengths-list} variable; its value is returned as the value of -the whole function. - -You can try this function by installing it in the usual fashion. Then -place your cursor after the following expression and type @kbd{C-x -C-e} (@code{eval-last-sexp}). - -@c !!! 22.1.1 lisp sources location here -@smallexample -(lengths-list-file - "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el") -@end smallexample - -@noindent -(You may need to change the pathname of the file; the one here is for -GNU Emacs version 22.1.1. To change the expression, copy it to -the @file{*scratch*} buffer and edit it. - -@need 1200 -@noindent -(Also, to see the full length of the list, rather than a truncated -version, you may have to evaluate the following: - -@smallexample -(custom-set-variables '(eval-expression-print-length nil)) -@end smallexample - -@noindent -(@xref{defcustom, , Specifying Variables using @code{defcustom}}. -Then evaluate the @code{lengths-list-file} expression.) - -@need 1200 -The lengths' list for @file{debug.el} takes less than a second to -produce and looks like this in GNU Emacs 22: - -@smallexample -(83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587) -@end smallexample - -@need 1500 -(Using my old machine, the version 19 lengths' list for @file{debug.el} -took seven seconds to produce and looked like this: - -@smallexample -(75 41 80 62 20 45 44 68 45 12 34 235) -@end smallexample - -(The newer version of @file{debug.el} contains more defuns than the -earlier one; and my new machine is much faster than the old one.) - -Note that the length of the last definition in the file is first in -the list. - -@node Several files, Several files recursively, lengths-list-file, Words in a defun -@section Count Words in @code{defuns} in Different Files - -In the previous section, we created a function that returns a list of -the lengths of each definition in a file. Now, we want to define a -function to return a master list of the lengths of the definitions in -a list of files. - -Working on each of a list of files is a repetitious act, so we can use -either a @code{while} loop or recursion. - -@menu -* lengths-list-many-files:: Return a list of the lengths of defuns. -* append:: Attach one list to another. -@end menu - -@node lengths-list-many-files, append, Several files, Several files -@ifnottex -@unnumberedsubsec Determine the lengths of @code{defuns} -@end ifnottex - -The design using a @code{while} loop is routine. The argument passed -the function is a list of files. As we saw earlier (@pxref{Loop -Example}), you can write a @code{while} loop so that the body of the -loop is evaluated if such a list contains elements, but to exit the -loop if the list is empty. For this design to work, the body of the -loop must contain an expression that shortens the list each time the -body is evaluated, so that eventually the list is empty. The usual -technique is to set the value of the list to the value of the @sc{cdr} -of the list each time the body is evaluated. - -@need 800 -The template looks like this: - -@smallexample -@group -(while @var{test-whether-list-is-empty} - @var{body}@dots{} - @var{set-list-to-cdr-of-list}) -@end group -@end smallexample - -Also, we remember that a @code{while} loop returns @code{nil} (the -result of evaluating the true-or-false-test), not the result of any -evaluation within its body. (The evaluations within the body of the -loop are done for their side effects.) However, the expression that -sets the lengths' list is part of the body---and that is the value -that we want returned by the function as a whole. To do this, we -enclose the @code{while} loop within a @code{let} expression, and -arrange that the last element of the @code{let} expression contains -the value of the lengths' list. (@xref{Incrementing Example, , Loop -Example with an Incrementing Counter}.) - -@findex lengths-list-many-files -@need 1250 -These considerations lead us directly to the function itself: - -@smallexample -@group -;;; @r{Use @code{while} loop.} -(defun lengths-list-many-files (list-of-files) - "Return list of lengths of defuns in LIST-OF-FILES." -@end group -@group - (let (lengths-list) - -;;; @r{true-or-false-test} - (while list-of-files - (setq lengths-list - (append - lengths-list - -;;; @r{Generate a lengths' list.} - (lengths-list-file - (expand-file-name (car list-of-files))))) -@end group - -@group -;;; @r{Make files' list shorter.} - (setq list-of-files (cdr list-of-files))) - -;;; @r{Return final value of lengths' list.} - lengths-list)) -@end group -@end smallexample - -@code{expand-file-name} is a built-in function that converts a file -name to the absolute, long, path name form. The function employs the -name of the directory in which the function is called. - -@c !!! 22.1.1 lisp sources location here -@need 1500 -Thus, if @code{expand-file-name} is called on @code{debug.el} when -Emacs is visiting the -@file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory, - -@smallexample -debug.el -@end smallexample - -@need 800 -@noindent -becomes - -@c !!! 22.1.1 lisp sources location here -@smallexample -/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el -@end smallexample - -The only other new element of this function definition is the as yet -unstudied function @code{append}, which merits a short section for -itself. - -@node append, , lengths-list-many-files, Several files -@subsection The @code{append} Function - -@need 800 -The @code{append} function attaches one list to another. Thus, - -@smallexample -(append '(1 2 3 4) '(5 6 7 8)) -@end smallexample - -@need 800 -@noindent -produces the list - -@smallexample -(1 2 3 4 5 6 7 8) -@end smallexample - -This is exactly how we want to attach two lengths' lists produced by -@code{lengths-list-file} to each other. The results contrast with -@code{cons}, - -@smallexample -(cons '(1 2 3 4) '(5 6 7 8)) -@end smallexample - -@need 1250 -@noindent -which constructs a new list in which the first argument to @code{cons} -becomes the first element of the new list: - -@smallexample -((1 2 3 4) 5 6 7 8) -@end smallexample - -@node Several files recursively, Prepare the data, Several files, Words in a defun -@section Recursively Count Words in Different Files - -Besides a @code{while} loop, you can work on each of a list of files -with recursion. A recursive version of @code{lengths-list-many-files} -is short and simple. - -The recursive function has the usual parts: the `do-again-test', the -`next-step-expression', and the recursive call. The `do-again-test' -determines whether the function should call itself again, which it -will do if the @code{list-of-files} contains any remaining elements; -the `next-step-expression' resets the @code{list-of-files} to the -@sc{cdr} of itself, so eventually the list will be empty; and the -recursive call calls itself on the shorter list. The complete -function is shorter than this description! -@findex recursive-lengths-list-many-files - -@smallexample -@group -(defun recursive-lengths-list-many-files (list-of-files) - "Return list of lengths of each defun in LIST-OF-FILES." - (if list-of-files ; @r{do-again-test} - (append - (lengths-list-file - (expand-file-name (car list-of-files))) - (recursive-lengths-list-many-files - (cdr list-of-files))))) -@end group -@end smallexample - -@noindent -In a sentence, the function returns the lengths' list for the first of -the @code{list-of-files} appended to the result of calling itself on -the rest of the @code{list-of-files}. - -Here is a test of @code{recursive-lengths-list-many-files}, along with -the results of running @code{lengths-list-file} on each of the files -individually. - -Install @code{recursive-lengths-list-many-files} and -@code{lengths-list-file}, if necessary, and then evaluate the -following expressions. You may need to change the files' pathnames; -those here work when this Info file and the Emacs sources are located -in their customary places. To change the expressions, copy them to -the @file{*scratch*} buffer, edit them, and then evaluate them. - -The results are shown after the @samp{@result{}}. (These results are -for files from Emacs version 22.1.1; files from other versions of -Emacs may produce different results.) - -@c !!! 22.1.1 lisp sources location here -@smallexample -@group -(cd "/usr/local/share/emacs/22.1.1/") - -(lengths-list-file "./lisp/macros.el") - @result{} (283 263 480 90) -@end group - -@group -(lengths-list-file "./lisp/mail/mailalias.el") - @result{} (38 32 29 95 178 180 321 218 324) -@end group - -@group -(lengths-list-file "./lisp/makesum.el") - @result{} (85 181) -@end group - -@group - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mail/mailalias.el" - "./lisp/makesum.el")) - @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181) -@end group -@end smallexample - -The @code{recursive-lengths-list-many-files} function produces the -output we want. - -The next step is to prepare the data in the list for display in a graph. - -@node Prepare the data, , Several files recursively, Words in a defun -@section Prepare the Data for Display in a Graph - -The @code{recursive-lengths-list-many-files} function returns a list -of numbers. Each number records the length of a function definition. -What we need to do now is transform this data into a list of numbers -suitable for generating a graph. The new list will tell how many -functions definitions contain less than 10 words and -symbols, how many contain between 10 and 19 words and symbols, how -many contain between 20 and 29 words and symbols, and so on. - -In brief, we need to go through the lengths' list produced by the -@code{recursive-lengths-list-many-files} function and count the number -of defuns within each range of lengths, and produce a list of those -numbers. - -@menu -* Data for Display in Detail:: -* Sorting:: Sorting lists. -* Files List:: Making a list of files. -* Counting function definitions:: -@end menu - -@node Data for Display in Detail, Sorting, Prepare the data, Prepare the data -@ifnottex -@unnumberedsubsec The Data for Display in Detail -@end ifnottex - -Based on what we have done before, we can readily foresee that it -should not be too hard to write a function that `@sc{cdr}s' down the -lengths' list, looks at each element, determines which length range it -is in, and increments a counter for that range. - -However, before beginning to write such a function, we should consider -the advantages of sorting the lengths' list first, so the numbers are -ordered from smallest to largest. First, sorting will make it easier -to count the numbers in each range, since two adjacent numbers will -either be in the same length range or in adjacent ranges. Second, by -inspecting a sorted list, we can discover the highest and lowest -number, and thereby determine the largest and smallest length range -that we will need. - -@node Sorting, Files List, Data for Display in Detail, Prepare the data -@subsection Sorting Lists -@findex sort - -Emacs contains a function to sort lists, called (as you might guess) -@code{sort}. The @code{sort} function takes two arguments, the list -to be sorted, and a predicate that determines whether the first of -two list elements is ``less'' than the second. - -As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong -Type Object as an Argument}), a predicate is a function that -determines whether some property is true or false. The @code{sort} -function will reorder a list according to whatever property the -predicate uses; this means that @code{sort} can be used to sort -non-numeric lists by non-numeric criteria---it can, for example, -alphabetize a list. - -@need 1250 -The @code{<} function is used when sorting a numeric list. For example, - -@smallexample -(sort '(4 8 21 17 33 7 21 7) '<) -@end smallexample - -@need 800 -@noindent -produces this: - -@smallexample -(4 7 7 8 17 21 21 33) -@end smallexample - -@noindent -(Note that in this example, both the arguments are quoted so that the -symbols are not evaluated before being passed to @code{sort} as -arguments.) - -Sorting the list returned by the -@code{recursive-lengths-list-many-files} function is straightforward; -it uses the @code{<} function: - -@ignore -2006 Oct 29 -In GNU Emacs 22, eval -(progn - (cd "/usr/local/share/emacs/22.0.50/") - (sort - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mail/mailalias.el" - "./lisp/makesum.el")) - '<)) - -@end ignore - -@smallexample -@group -(sort - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mailalias.el" - "./lisp/makesum.el")) - '<) -@end group -@end smallexample - -@need 800 -@noindent -which produces: - -@smallexample -(29 32 38 85 90 95 178 180 181 218 263 283 321 324 480) -@end smallexample - -@noindent -(Note that in this example, the first argument to @code{sort} is not -quoted, since the expression must be evaluated so as to produce the -list that is passed to @code{sort}.) - -@node Files List, Counting function definitions, Sorting, Prepare the data -@subsection Making a List of Files - -The @code{recursive-lengths-list-many-files} function requires a list -of files as its argument. For our test examples, we constructed such -a list by hand; but the Emacs Lisp source directory is too large for -us to do for that. Instead, we will write a function to do the job -for us. In this function, we will use both a @code{while} loop and a -recursive call. - -@findex directory-files -We did not have to write a function like this for older versions of -GNU Emacs, since they placed all the @samp{.el} files in one -directory. Instead, we were able to use the @code{directory-files} -function, which lists the names of files that match a specified -pattern within a single directory. - -However, recent versions of Emacs place Emacs Lisp files in -sub-directories of the top level @file{lisp} directory. This -re-arrangement eases navigation. For example, all the mail related -files are in a @file{lisp} sub-directory called @file{mail}. But at -the same time, this arrangement forces us to create a file listing -function that descends into the sub-directories. - -@findex files-in-below-directory -We can create this function, called @code{files-in-below-directory}, -using familiar functions such as @code{car}, @code{nthcdr}, and -@code{substring} in conjunction with an existing function called -@code{directory-files-and-attributes}. This latter function not only -lists all the filenames in a directory, including the names -of sub-directories, but also their attributes. - -To restate our goal: to create a function that will enable us -to feed filenames to @code{recursive-lengths-list-many-files} -as a list that looks like this (but with more elements): - -@smallexample -@group -("./lisp/macros.el" - "./lisp/mail/rmail.el" - "./lisp/makesum.el") -@end group -@end smallexample - -The @code{directory-files-and-attributes} function returns a list of -lists. Each of the lists within the main list consists of 13 -elements. The first element is a string that contains the name of the -file -- which, in GNU/Linux, may be a `directory file', that is to -say, a file with the special attributes of a directory. The second -element of the list is @code{t} for a directory, a string -for symbolic link (the string is the name linked to), or @code{nil}. - -For example, the first @samp{.el} file in the @file{lisp/} directory -is @file{abbrev.el}. Its name is -@file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a -directory or a symbolic link. - -@need 1000 -This is how @code{directory-files-and-attributes} lists that file and -its attributes: - -@smallexample -@group -("abbrev.el" -nil -1 -1000 -100 -@end group -@group -(17733 259) -(17491 28834) -(17596 62124) -13157 -"-rw-rw-r--" -@end group -@group -nil -2971624 -773) -@end group -@end smallexample - -@need 1200 -On the other hand, @file{mail/} is a directory within the @file{lisp/} -directory. The beginning of its listing looks like this: - -@smallexample -@group -("mail" -t -@dots{} -) -@end group -@end smallexample - -(To learn about the different attributes, look at the documentation of -@code{file-attributes}. Bear in mind that the @code{file-attributes} -function does not list the filename, so its first element is -@code{directory-files-and-attributes}'s second element.) - -We will want our new function, @code{files-in-below-directory}, to -list the @samp{.el} files in the directory it is told to check, and in -any directories below that directory. - -This gives us a hint on how to construct -@code{files-in-below-directory}: within a directory, the function -should add @samp{.el} filenames to a list; and if, within a directory, -the function comes upon a sub-directory, it should go into that -sub-directory and repeat its actions. - -However, we should note that every directory contains a name that -refers to itself, called @file{.}, (``dot'') and a name that refers to -its parent directory, called @file{..} (``double dot''). (In -@file{/}, the root directory, @file{..} refers to itself, since -@file{/} has no parent.) Clearly, we do not want our -@code{files-in-below-directory} function to enter those directories, -since they always lead us, directly or indirectly, to the current -directory. - -Consequently, our @code{files-in-below-directory} function must do -several tasks: - -@itemize @bullet -@item -Check to see whether it is looking at a filename that ends in -@samp{.el}; and if so, add its name to a list. - -@item -Check to see whether it is looking at a filename that is the name of a -directory; and if so, - -@itemize @minus -@item -Check to see whether it is looking at @file{.} or @file{..}; and if -so skip it. - -@item -Or else, go into that directory and repeat the process. -@end itemize -@end itemize - -Let's write a function definition to do these tasks. We will use a -@code{while} loop to move from one filename to another within a -directory, checking what needs to be done; and we will use a recursive -call to repeat the actions on each sub-directory. The recursive -pattern is `accumulate' -(@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}), -using @code{append} as the combiner. - -@ignore -(directory-files "/usr/local/src/emacs/lisp/" t "\\.el$") -(shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'") - -(directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$") -(shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'") -@end ignore - -@c /usr/local/share/emacs/22.1.1/lisp/ - -@need 800 -Here is the function: - -@smallexample -@group -(defun files-in-below-directory (directory) - "List the .el files in DIRECTORY and in its sub-directories." - ;; Although the function will be used non-interactively, - ;; it will be easier to test if we make it interactive. - ;; The directory will have a name such as - ;; "/usr/local/share/emacs/22.1.1/lisp/" - (interactive "DDirectory name: ") -@end group -@group - (let (el-files-list - (current-directory-list - (directory-files-and-attributes directory t))) - ;; while we are in the current directory - (while current-directory-list -@end group -@group - (cond - ;; check to see whether filename ends in `.el' - ;; and if so, append its name to a list. - ((equal ".el" (substring (car (car current-directory-list)) -3)) - (setq el-files-list - (cons (car (car current-directory-list)) el-files-list))) -@end group -@group - ;; check whether filename is that of a directory - ((eq t (car (cdr (car current-directory-list)))) - ;; decide whether to skip or recurse - (if - (equal "." - (substring (car (car current-directory-list)) -1)) - ;; then do nothing since filename is that of - ;; current directory or parent, "." or ".." - () -@end group -@group - ;; else descend into the directory and repeat the process - (setq el-files-list - (append - (files-in-below-directory - (car (car current-directory-list))) - el-files-list))))) - ;; move to the next filename in the list; this also - ;; shortens the list so the while loop eventually comes to an end - (setq current-directory-list (cdr current-directory-list))) - ;; return the filenames - el-files-list)) -@end group -@end smallexample - -@c (files-in-below-directory "/usr/local/src/emacs/lisp/") -@c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") - -The @code{files-in-below-directory} @code{directory-files} function -takes one argument, the name of a directory. - -@need 1250 -Thus, on my system, - -@c (length (files-in-below-directory "/usr/local/src/emacs/lisp/")) - -@c !!! 22.1.1 lisp sources location here -@smallexample -@group -(length - (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")) -@end group -@end smallexample - -@noindent -tells me that in and below my Lisp sources directory are 1031 -@samp{.el} files. - -@code{files-in-below-directory} returns a list in reverse alphabetical -order. An expression to sort the list in alphabetical order looks -like this: - -@smallexample -@group -(sort - (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") - 'string-lessp) -@end group -@end smallexample - -@ignore -(defun test () - "Test how long it takes to find lengths of all sorted elisp defuns." - (insert "\n" (current-time-string) "\n") - (sit-for 0) - (sort - (recursive-lengths-list-many-files - (files-in-below-directory "/usr/local/src/emacs/lisp/")) - '<) - (insert (format "%s" (current-time-string)))) -@end ignore - -@node Counting function definitions, , Files List, Prepare the data -@subsection Counting function definitions - -Our immediate goal is to generate a list that tells us how many -function definitions contain fewer than 10 words and symbols, how many -contain between 10 and 19 words and symbols, how many contain between -20 and 29 words and symbols, and so on. - -With a sorted list of numbers, this is easy: count how many elements -of the list are smaller than 10, then, after moving past the numbers -just counted, count how many are smaller than 20, then, after moving -past the numbers just counted, count how many are smaller than 30, and -so on. Each of the numbers, 10, 20, 30, 40, and the like, is one -larger than the top of that range. We can call the list of such -numbers the @code{top-of-ranges} list. - -@need 1200 -If we wished, we could generate this list automatically, but it is -simpler to write a list manually. Here it is: -@vindex top-of-ranges - -@smallexample -@group -(defvar top-of-ranges - '(10 20 30 40 50 - 60 70 80 90 100 - 110 120 130 140 150 - 160 170 180 190 200 - 210 220 230 240 250 - 260 270 280 290 300) - "List specifying ranges for `defuns-per-range'.") -@end group -@end smallexample - -To change the ranges, we edit this list. - -Next, we need to write the function that creates the list of the -number of definitions within each range. Clearly, this function must -take the @code{sorted-lengths} and the @code{top-of-ranges} lists -as arguments. - -The @code{defuns-per-range} function must do two things again and -again: it must count the number of definitions within a range -specified by the current top-of-range value; and it must shift to the -next higher value in the @code{top-of-ranges} list after counting the -number of definitions in the current range. Since each of these -actions is repetitive, we can use @code{while} loops for the job. -One loop counts the number of definitions in the range defined by the -current top-of-range value, and the other loop selects each of the -top-of-range values in turn. - -Several entries of the @code{sorted-lengths} list are counted for each -range; this means that the loop for the @code{sorted-lengths} list -will be inside the loop for the @code{top-of-ranges} list, like a -small gear inside a big gear. - -The inner loop counts the number of definitions within the range. It -is a simple counting loop of the type we have seen before. -(@xref{Incrementing Loop, , A loop with an incrementing counter}.) -The true-or-false test of the loop tests whether the value from the -@code{sorted-lengths} list is smaller than the current value of the -top of the range. If it is, the function increments the counter and -tests the next value from the @code{sorted-lengths} list. - -@need 1250 -The inner loop looks like this: - -@smallexample -@group -(while @var{length-element-smaller-than-top-of-range} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) -@end group -@end smallexample - -The outer loop must start with the lowest value of the -@code{top-of-ranges} list, and then be set to each of the succeeding -higher values in turn. This can be done with a loop like this: - -@smallexample -@group -(while top-of-ranges - @var{body-of-loop}@dots{} - (setq top-of-ranges (cdr top-of-ranges))) -@end group -@end smallexample - -@need 1200 -Put together, the two loops look like this: - -@smallexample -@group -(while top-of-ranges - - ;; @r{Count the number of elements within the current range.} - (while @var{length-element-smaller-than-top-of-range} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) - - ;; @r{Move to next range.} - (setq top-of-ranges (cdr top-of-ranges))) -@end group -@end smallexample - -In addition, in each circuit of the outer loop, Emacs should record -the number of definitions within that range (the value of -@code{number-within-range}) in a list. We can use @code{cons} for -this purpose. (@xref{cons, , @code{cons}}.) - -The @code{cons} function works fine, except that the list it -constructs will contain the number of definitions for the highest -range at its beginning and the number of definitions for the lowest -range at its end. This is because @code{cons} attaches new elements -of the list to the beginning of the list, and since the two loops are -working their way through the lengths' list from the lower end first, -the @code{defuns-per-range-list} will end up largest number first. -But we will want to print our graph with smallest values first and the -larger later. The solution is to reverse the order of the -@code{defuns-per-range-list}. We can do this using the -@code{nreverse} function, which reverses the order of a list. -@findex nreverse - -@need 800 -For example, - -@smallexample -(nreverse '(1 2 3 4)) -@end smallexample - -@need 800 -@noindent -produces: - -@smallexample -(4 3 2 1) -@end smallexample - -Note that the @code{nreverse} function is ``destructive''---that is, -it changes the list to which it is applied; this contrasts with the -@code{car} and @code{cdr} functions, which are non-destructive. In -this case, we do not want the original @code{defuns-per-range-list}, -so it does not matter that it is destroyed. (The @code{reverse} -function provides a reversed copy of a list, leaving the original list -as is.) -@findex reverse - -@need 1250 -Put all together, the @code{defuns-per-range} looks like this: - -@smallexample -@group -(defun defuns-per-range (sorted-lengths top-of-ranges) - "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." - (let ((top-of-range (car top-of-ranges)) - (number-within-range 0) - defuns-per-range-list) -@end group - -@group - ;; @r{Outer loop.} - (while top-of-ranges -@end group - -@group - ;; @r{Inner loop.} - (while (and - ;; @r{Need number for numeric test.} - (car sorted-lengths) - (< (car sorted-lengths) top-of-range)) -@end group - -@group - ;; @r{Count number of definitions within current range.} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) - - ;; @r{Exit inner loop but remain within outer loop.} -@end group - -@group - (setq defuns-per-range-list - (cons number-within-range defuns-per-range-list)) - (setq number-within-range 0) ; @r{Reset count to zero.} -@end group - -@group - ;; @r{Move to next range.} - (setq top-of-ranges (cdr top-of-ranges)) - ;; @r{Specify next top of range value.} - (setq top-of-range (car top-of-ranges))) -@end group - -@group - ;; @r{Exit outer loop and count the number of defuns larger than} - ;; @r{ the largest top-of-range value.} - (setq defuns-per-range-list - (cons - (length sorted-lengths) - defuns-per-range-list)) -@end group - -@group - ;; @r{Return a list of the number of definitions within each range,} - ;; @r{ smallest to largest.} - (nreverse defuns-per-range-list))) -@end group -@end smallexample - -@need 1200 -@noindent -The function is straightforward except for one subtle feature. The -true-or-false test of the inner loop looks like this: - -@smallexample -@group -(and (car sorted-lengths) - (< (car sorted-lengths) top-of-range)) -@end group -@end smallexample - -@need 800 -@noindent -instead of like this: - -@smallexample -(< (car sorted-lengths) top-of-range) -@end smallexample - -The purpose of the test is to determine whether the first item in the -@code{sorted-lengths} list is less than the value of the top of the -range. - -The simple version of the test works fine unless the -@code{sorted-lengths} list has a @code{nil} value. In that case, the -@code{(car sorted-lengths)} expression function returns -@code{nil}. The @code{<} function cannot compare a number to -@code{nil}, which is an empty list, so Emacs signals an error and -stops the function from attempting to continue to execute. - -The @code{sorted-lengths} list always becomes @code{nil} when the -counter reaches the end of the list. This means that any attempt to -use the @code{defuns-per-range} function with the simple version of -the test will fail. - -We solve the problem by using the @code{(car sorted-lengths)} -expression in conjunction with the @code{and} expression. The -@code{(car sorted-lengths)} expression returns a non-@code{nil} -value so long as the list has at least one number within it, but -returns @code{nil} if the list is empty. The @code{and} expression -first evaluates the @code{(car sorted-lengths)} expression, and -if it is @code{nil}, returns false @emph{without} evaluating the -@code{<} expression. But if the @code{(car sorted-lengths)} -expression returns a non-@code{nil} value, the @code{and} expression -evaluates the @code{<} expression, and returns that value as the value -of the @code{and} expression. - -@c colon in printed section title causes problem in Info cross reference -This way, we avoid an error. -@iftex -@noindent -(For information about @code{and}, see -@ref{kill-new function, , The @code{kill-new} function}.) -@end iftex -@ifinfo -@noindent -(@xref{kill-new function, , The @code{kill-new} function}, for -information about @code{and}.) -@end ifinfo - -Here is a short test of the @code{defuns-per-range} function. First, -evaluate the expression that binds (a shortened) -@code{top-of-ranges} list to the list of values, then evaluate the -expression for binding the @code{sorted-lengths} list, and then -evaluate the @code{defuns-per-range} function. - -@smallexample -@group -;; @r{(Shorter list than we will use later.)} -(setq top-of-ranges - '(110 120 130 140 150 - 160 170 180 190 200)) - -(setq sorted-lengths - '(85 86 110 116 122 129 154 176 179 200 265 300 300)) - -(defuns-per-range sorted-lengths top-of-ranges) -@end group -@end smallexample - -@need 800 -@noindent -The list returned looks like this: - -@smallexample -(2 2 2 0 0 1 0 2 0 0 4) -@end smallexample - -@noindent -Indeed, there are two elements of the @code{sorted-lengths} list -smaller than 110, two elements between 110 and 119, two elements -between 120 and 129, and so on. There are four elements with a value -of 200 or larger. - -@c The next step is to turn this numbers' list into a graph. -@node Readying a Graph, Emacs Initialization, Words in a defun, Top -@chapter Readying a Graph -@cindex Readying a graph -@cindex Graph prototype -@cindex Prototype graph -@cindex Body of graph - -Our goal is to construct a graph showing the numbers of function -definitions of various lengths in the Emacs lisp sources. - -As a practical matter, if you were creating a graph, you would -probably use a program such as @code{gnuplot} to do the job. -(@code{gnuplot} is nicely integrated into GNU Emacs.) In this case, -however, we create one from scratch, and in the process we will -re-acquaint ourselves with some of what we learned before and learn -more. - -In this chapter, we will first write a simple graph printing function. -This first definition will be a @dfn{prototype}, a rapidly written -function that enables us to reconnoiter this unknown graph-making -territory. We will discover dragons, or find that they are myth. -After scouting the terrain, we will feel more confident and enhance -the function to label the axes automatically. - -@menu -* Columns of a graph:: -* graph-body-print:: How to print the body of a graph. -* recursive-graph-body-print:: -* Printed Axes:: -* Line Graph Exercise:: -@end menu - -@node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph -@ifnottex -@unnumberedsec Printing the Columns of a Graph -@end ifnottex - -Since Emacs is designed to be flexible and work with all kinds of -terminals, including character-only terminals, the graph will need to -be made from one of the `typewriter' symbols. An asterisk will do; as -we enhance the graph-printing function, we can make the choice of -symbol a user option. - -We can call this function @code{graph-body-print}; it will take a -@code{numbers-list} as its only argument. At this stage, we will not -label the graph, but only print its body. - -The @code{graph-body-print} function inserts a vertical column of -asterisks for each element in the @code{numbers-list}. The height of -each line is determined by the value of that element of the -@code{numbers-list}. - -Inserting columns is a repetitive act; that means that this function can -be written either with a @code{while} loop or recursively. - -Our first challenge is to discover how to print a column of asterisks. -Usually, in Emacs, we print characters onto a screen horizontally, -line by line, by typing. We have two routes we can follow: write our -own column-insertion function or discover whether one exists in Emacs. - -To see whether there is one in Emacs, we can use the @kbd{M-x apropos} -command. This command is like the @kbd{C-h a} (@code{command-apropos}) -command, except that the latter finds only those functions that are -commands. The @kbd{M-x apropos} command lists all symbols that match -a regular expression, including functions that are not interactive. -@findex apropos - -What we want to look for is some command that prints or inserts -columns. Very likely, the name of the function will contain either -the word `print' or the word `insert' or the word `column'. -Therefore, we can simply type @kbd{M-x apropos RET -print\|insert\|column RET} and look at the result. On my system, this -command once too takes quite some time, and then produced a list of 79 -functions and variables. Now it does not take much time at all and -produces a list of 211 functions and variables. Scanning down the -list, the only function that looks as if it might do the job is -@code{insert-rectangle}. - -@need 1200 -Indeed, this is the function we want; its documentation says: - -@smallexample -@group -insert-rectangle: -Insert text of RECTANGLE with upper left corner at point. -RECTANGLE's first line is inserted at point, -its second line is inserted at a point vertically under point, etc. -RECTANGLE should be a list of strings. -After this command, the mark is at the upper left corner -and point is at the lower right corner. -@end group -@end smallexample - -We can run a quick test, to make sure it does what we expect of it. - -Here is the result of placing the cursor after the -@code{insert-rectangle} expression and typing @kbd{C-u C-x C-e} -(@code{eval-last-sexp}). The function inserts the strings -@samp{"first"}, @samp{"second"}, and @samp{"third"} at and below -point. Also the function returns @code{nil}. - -@smallexample -@group -(insert-rectangle '("first" "second" "third"))first - second - thirdnil -@end group -@end smallexample - -@noindent -Of course, we won't be inserting the text of the -@code{insert-rectangle} expression itself into the buffer in which we -are making the graph, but will call the function from our program. We -shall, however, have to make sure that point is in the buffer at the -place where the @code{insert-rectangle} function will insert its -column of strings. - -If you are reading this in Info, you can see how this works by -switching to another buffer, such as the @file{*scratch*} buffer, -placing point somewhere in the buffer, typing @kbd{M-:}, typing the -@code{insert-rectangle} expression into the minibuffer at the prompt, -and then typing @key{RET}. This causes Emacs to evaluate the -expression in the minibuffer, but to use as the value of point the -position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the -keybinding for @code{eval-expression}. Also, @code{nil} does not -appear in the @file{*scratch*} buffer since the expression is -evaluated in the minibuffer.) - -We find when we do this that point ends up at the end of the last -inserted line---that is to say, this function moves point as a -side-effect. If we were to repeat the command, with point at this -position, the next insertion would be below and to the right of the -previous insertion. We don't want this! If we are going to make a -bar graph, the columns need to be beside each other. - -So we discover that each cycle of the column-inserting @code{while} -loop must reposition point to the place we want it, and that place -will be at the top, not the bottom, of the column. Moreover, we -remember that when we print a graph, we do not expect all the columns -to be the same height. This means that the top of each column may be -at a different height from the previous one. We cannot simply -reposition point to the same line each time, but moved over to the -right---or perhaps we can@dots{} - -We are planning to make the columns of the bar graph out of asterisks. -The number of asterisks in the column is the number specified by the -current element of the @code{numbers-list}. We need to construct a -list of asterisks of the right length for each call to -@code{insert-rectangle}. If this list consists solely of the requisite -number of asterisks, then we will have position point the right number -of lines above the base for the graph to print correctly. This could -be difficult. - -Alternatively, if we can figure out some way to pass -@code{insert-rectangle} a list of the same length each time, then we -can place point on the same line each time, but move it over one -column to the right for each new column. If we do this, however, some -of the entries in the list passed to @code{insert-rectangle} must be -blanks rather than asterisks. For example, if the maximum height of -the graph is 5, but the height of the column is 3, then -@code{insert-rectangle} requires an argument that looks like this: - -@smallexample -(" " " " "*" "*" "*") -@end smallexample - -This last proposal is not so difficult, so long as we can determine -the column height. There are two ways for us to specify the column -height: we can arbitrarily state what it will be, which would work -fine for graphs of that height; or we can search through the list of -numbers and use the maximum height of the list as the maximum height -of the graph. If the latter operation were difficult, then the former -procedure would be easiest, but there is a function built into Emacs -that determines the maximum of its arguments. We can use that -function. The function is called @code{max} and it returns the -largest of all its arguments, which must be numbers. Thus, for -example, - -@smallexample -(max 3 4 6 5 7 3) -@end smallexample - -@noindent -returns 7. (A corresponding function called @code{min} returns the -smallest of all its arguments.) -@findex max -@findex min - -However, we cannot simply call @code{max} on the @code{numbers-list}; -the @code{max} function expects numbers as its argument, not a list of -numbers. Thus, the following expression, - -@smallexample -(max '(3 4 6 5 7 3)) -@end smallexample - -@need 800 -@noindent -produces the following error message; - -@smallexample -Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3) -@end smallexample - -@findex apply -We need a function that passes a list of arguments to a function. -This function is @code{apply}. This function `applies' its first -argument (a function) to its remaining arguments, the last of which -may be a list. - -@need 1250 -For example, - -@smallexample -(apply 'max 3 4 7 3 '(4 8 5)) -@end smallexample - -@noindent -returns 8. - -(Incidentally, I don't know how you would learn of this function -without a book such as this. It is possible to discover other -functions, like @code{search-forward} or @code{insert-rectangle}, by -guessing at a part of their names and then using @code{apropos}. Even -though its base in metaphor is clear---`apply' its first argument to -the rest---I doubt a novice would come up with that particular word -when using @code{apropos} or other aid. Of course, I could be wrong; -after all, the function was first named by someone who had to invent -it.) - -The second and subsequent arguments to @code{apply} are optional, so -we can use @code{apply} to call a function and pass the elements of a -list to it, like this, which also returns 8: - -@smallexample -(apply 'max '(4 8 5)) -@end smallexample - -This latter way is how we will use @code{apply}. The -@code{recursive-lengths-list-many-files} function returns a numbers' -list to which we can apply @code{max} (we could also apply @code{max} to -the sorted numbers' list; it does not matter whether the list is -sorted or not.) - -@need 800 -Hence, the operation for finding the maximum height of the graph is this: - -@smallexample -(setq max-graph-height (apply 'max numbers-list)) -@end smallexample - -Now we can return to the question of how to create a list of strings -for a column of the graph. Told the maximum height of the graph -and the number of asterisks that should appear in the column, the -function should return a list of strings for the -@code{insert-rectangle} command to insert. - -Each column is made up of asterisks or blanks. Since the function is -passed the value of the height of the column and the number of -asterisks in the column, the number of blanks can be found by -subtracting the number of asterisks from the height of the column. -Given the number of blanks and the number of asterisks, two -@code{while} loops can be used to construct the list: - -@smallexample -@group -;;; @r{First version.} -(defun column-of-graph (max-graph-height actual-height) - "Return list of strings that is one column of a graph." - (let ((insert-list nil) - (number-of-top-blanks - (- max-graph-height actual-height))) -@end group - -@group - ;; @r{Fill in asterisks.} - (while (> actual-height 0) - (setq insert-list (cons "*" insert-list)) - (setq actual-height (1- actual-height))) -@end group - -@group - ;; @r{Fill in blanks.} - (while (> number-of-top-blanks 0) - (setq insert-list (cons " " insert-list)) - (setq number-of-top-blanks - (1- number-of-top-blanks))) -@end group - -@group - ;; @r{Return whole list.} - insert-list)) -@end group -@end smallexample - -If you install this function and then evaluate the following -expression you will see that it returns the list as desired: - -@smallexample -(column-of-graph 5 3) -@end smallexample - -@need 800 -@noindent -returns - -@smallexample -(" " " " "*" "*" "*") -@end smallexample - -As written, @code{column-of-graph} contains a major flaw: the symbols -used for the blank and for the marked entries in the column are -`hard-coded' as a space and asterisk. This is fine for a prototype, -but you, or another user, may wish to use other symbols. For example, -in testing the graph function, you many want to use a period in place -of the space, to make sure the point is being repositioned properly -each time the @code{insert-rectangle} function is called; or you might -want to substitute a @samp{+} sign or other symbol for the asterisk. -You might even want to make a graph-column that is more than one -display column wide. The program should be more flexible. The way to -do that is to replace the blank and the asterisk with two variables -that we can call @code{graph-blank} and @code{graph-symbol} and define -those variables separately. - -Also, the documentation is not well written. These considerations -lead us to the second version of the function: - -@smallexample -@group -(defvar graph-symbol "*" - "String used as symbol in graph, usually an asterisk.") -@end group - -@group -(defvar graph-blank " " - "String used as blank in graph, usually a blank space. -graph-blank must be the same number of columns wide -as graph-symbol.") -@end group -@end smallexample - -@noindent -(For an explanation of @code{defvar}, see -@ref{defvar, , Initializing a Variable with @code{defvar}}.) - -@smallexample -@group -;;; @r{Second version.} -(defun column-of-graph (max-graph-height actual-height) - "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols. - -@end group -@group -The graph-symbols are contiguous entries at the end -of the list. -The list will be inserted as one column of a graph. -The strings are either graph-blank or graph-symbol." -@end group - -@group - (let ((insert-list nil) - (number-of-top-blanks - (- max-graph-height actual-height))) -@end group - -@group - ;; @r{Fill in @code{graph-symbols}.} - (while (> actual-height 0) - (setq insert-list (cons graph-symbol insert-list)) - (setq actual-height (1- actual-height))) -@end group - -@group - ;; @r{Fill in @code{graph-blanks}.} - (while (> number-of-top-blanks 0) - (setq insert-list (cons graph-blank insert-list)) - (setq number-of-top-blanks - (1- number-of-top-blanks))) - - ;; @r{Return whole list.} - insert-list)) -@end group -@end smallexample - -If we wished, we could rewrite @code{column-of-graph} a third time to -provide optionally for a line graph as well as for a bar graph. This -would not be hard to do. One way to think of a line graph is that it -is no more than a bar graph in which the part of each bar that is -below the top is blank. To construct a column for a line graph, the -function first constructs a list of blanks that is one shorter than -the value, then it uses @code{cons} to attach a graph symbol to the -list; then it uses @code{cons} again to attach the `top blanks' to -the list. - -It is easy to see how to write such a function, but since we don't -need it, we will not do it. But the job could be done, and if it were -done, it would be done with @code{column-of-graph}. Even more -important, it is worth noting that few changes would have to be made -anywhere else. The enhancement, if we ever wish to make it, is -simple. - -Now, finally, we come to our first actual graph printing function. -This prints the body of a graph, not the labels for the vertical and -horizontal axes, so we can call this @code{graph-body-print}. - -@node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph -@section The @code{graph-body-print} Function -@findex graph-body-print - -After our preparation in the preceding section, the -@code{graph-body-print} function is straightforward. The function -will print column after column of asterisks and blanks, using the -elements of a numbers' list to specify the number of asterisks in each -column. This is a repetitive act, which means we can use a -decrementing @code{while} loop or recursive function for the job. In -this section, we will write the definition using a @code{while} loop. - -The @code{column-of-graph} function requires the height of the graph -as an argument, so we should determine and record that as a local variable. - -This leads us to the following template for the @code{while} loop -version of this function: - -@smallexample -@group -(defun graph-body-print (numbers-list) - "@var{documentation}@dots{}" - (let ((height @dots{} - @dots{})) -@end group - -@group - (while numbers-list - @var{insert-columns-and-reposition-point} - (setq numbers-list (cdr numbers-list))))) -@end group -@end smallexample - -@noindent -We need to fill in the slots of the template. - -Clearly, we can use the @code{(apply 'max numbers-list)} expression to -determine the height of the graph. - -The @code{while} loop will cycle through the @code{numbers-list} one -element at a time. As it is shortened by the @code{(setq numbers-list -(cdr numbers-list))} expression, the @sc{car} of each instance of the -list is the value of the argument for @code{column-of-graph}. - -At each cycle of the @code{while} loop, the @code{insert-rectangle} -function inserts the list returned by @code{column-of-graph}. Since -the @code{insert-rectangle} function moves point to the lower right of -the inserted rectangle, we need to save the location of point at the -time the rectangle is inserted, move back to that position after the -rectangle is inserted, and then move horizontally to the next place -from which @code{insert-rectangle} is called. - -If the inserted columns are one character wide, as they will be if -single blanks and asterisks are used, the repositioning command is -simply @code{(forward-char 1)}; however, the width of a column may be -greater than one. This means that the repositioning command should be -written @code{(forward-char symbol-width)}. The @code{symbol-width} -itself is the length of a @code{graph-blank} and can be found using -the expression @code{(length graph-blank)}. The best place to bind -the @code{symbol-width} variable to the value of the width of graph -column is in the varlist of the @code{let} expression. - -@need 1250 -These considerations lead to the following function definition: - -@smallexample -@group -(defun graph-body-print (numbers-list) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values." - - (let ((height (apply 'max numbers-list)) - (symbol-width (length graph-blank)) - from-position) -@end group - -@group - (while numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) - (goto-char from-position) - (forward-char symbol-width) -@end group -@group - ;; @r{Draw graph column by column.} - (sit-for 0) - (setq numbers-list (cdr numbers-list))) -@end group -@group - ;; @r{Place point for X axis labels.} - (forward-line height) - (insert "\n") -)) -@end group -@end smallexample - -@noindent -The one unexpected expression in this function is the -@w{@code{(sit-for 0)}} expression in the @code{while} loop. This -expression makes the graph printing operation more interesting to -watch than it would be otherwise. The expression causes Emacs to -`sit' or do nothing for a zero length of time and then redraw the -screen. Placed here, it causes Emacs to redraw the screen column by -column. Without it, Emacs would not redraw the screen until the -function exits. - -We can test @code{graph-body-print} with a short list of numbers. - -@enumerate -@item -Install @code{graph-symbol}, @code{graph-blank}, -@code{column-of-graph}, which are in -@iftex -@ref{Readying a Graph, , Readying a Graph}, -@end iftex -@ifinfo -@ref{Columns of a graph}, -@end ifinfo -and @code{graph-body-print}. - -@need 800 -@item -Copy the following expression: - -@smallexample -(graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3)) -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the graph to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the @code{graph-body-print} expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the @code{graph-body-print} expression. -@end enumerate - -@need 800 -Emacs will print a graph like this: - -@smallexample -@group - * - * ** - * **** - *** **** - ********* * - ************ - ************* -@end group -@end smallexample - -@node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph -@section The @code{recursive-graph-body-print} Function -@findex recursive-graph-body-print - -The @code{graph-body-print} function may also be written recursively. -The recursive solution is divided into two parts: an outside `wrapper' -that uses a @code{let} expression to determine the values of several -variables that need only be found once, such as the maximum height of -the graph, and an inside function that is called recursively to print -the graph. - -@need 1250 -The `wrapper' is uncomplicated: - -@smallexample -@group -(defun recursive-graph-body-print (numbers-list) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values." - (let ((height (apply 'max numbers-list)) - (symbol-width (length graph-blank)) - from-position) - (recursive-graph-body-print-internal - numbers-list - height - symbol-width))) -@end group -@end smallexample - -The recursive function is a little more difficult. It has four parts: -the `do-again-test', the printing code, the recursive call, and the -`next-step-expression'. The `do-again-test' is a @code{when} -expression that determines whether the @code{numbers-list} contains -any remaining elements; if it does, the function prints one column of -the graph using the printing code and calls itself again. The -function calls itself again according to the value produced by the -`next-step-expression' which causes the call to act on a shorter -version of the @code{numbers-list}. - -@smallexample -@group -(defun recursive-graph-body-print-internal - (numbers-list height symbol-width) - "Print a bar graph. -Used within recursive-graph-body-print function." -@end group - -@group - (when numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) -@end group -@group - (goto-char from-position) - (forward-char symbol-width) - (sit-for 0) ; @r{Draw graph column by column.} - (recursive-graph-body-print-internal - (cdr numbers-list) height symbol-width))) -@end group -@end smallexample - -@need 1250 -After installation, this expression can be tested; here is a sample: - -@smallexample -(recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1)) -@end smallexample - -@need 800 -Here is what @code{recursive-graph-body-print} produces: - -@smallexample -@group - * - ** * - **** * - **** *** - * ********* - ************ - ************* -@end group -@end smallexample - -Either of these two functions, @code{graph-body-print} or -@code{recursive-graph-body-print}, create the body of a graph. - -@node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph -@section Need for Printed Axes - -A graph needs printed axes, so you can orient yourself. For a do-once -project, it may be reasonable to draw the axes by hand using Emacs's -Picture mode; but a graph drawing function may be used more than once. - -For this reason, I have written enhancements to the basic -@code{print-graph-body} function that automatically print labels for -the horizontal and vertical axes. Since the label printing functions -do not contain much new material, I have placed their description in -an appendix. @xref{Full Graph, , A Graph with Labeled Axes}. - -@node Line Graph Exercise, , Printed Axes, Readying a Graph -@section Exercise - -Write a line graph version of the graph printing functions. - -@node Emacs Initialization, Debugging, Readying a Graph, Top -@chapter Your @file{.emacs} File -@cindex @file{.emacs} file -@cindex Customizing your @file{.emacs} file -@cindex Initialization file - -``You don't have to like Emacs to like it'' -- this seemingly -paradoxical statement is the secret of GNU Emacs. The plain, `out of -the box' Emacs is a generic tool. Most people who use it, customize -it to suit themselves. - -GNU Emacs is mostly written in Emacs Lisp; this means that by writing -expressions in Emacs Lisp you can change or extend Emacs. - -@menu -* Default Configuration:: -* Site-wide Init:: You can write site-wide init files. -* defcustom:: Emacs will write code for you. -* Beginning a .emacs File:: How to write a @code{.emacs file}. -* Text and Auto-fill:: Automatically wrap lines. -* Mail Aliases:: Use abbreviations for email addresses. -* Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. -* Keymaps:: More about key binding. -* Loading Files:: Load (i.e., evaluate) files automatically. -* Autoload:: Make functions available. -* Simple Extension:: Define a function; bind it to a key. -* X11 Colors:: Colors in X. -* Miscellaneous:: -* Mode Line:: How to customize your mode line. -@end menu - -@node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization -@ifnottex -@unnumberedsec Emacs's Default Configuration -@end ifnottex - -There are those who appreciate Emacs's default configuration. After -all, Emacs starts you in C mode when you edit a C file, starts you in -Fortran mode when you edit a Fortran file, and starts you in -Fundamental mode when you edit an unadorned file. This all makes -sense, if you do not know who is going to use Emacs. Who knows what a -person hopes to do with an unadorned file? Fundamental mode is the -right default for such a file, just as C mode is the right default for -editing C code. (Enough programming languages have syntaxes -that enable them to share or nearly share features, so C mode is -now provided by CC mode, the `C Collection'.) - -But when you do know who is going to use Emacs---you, -yourself---then it makes sense to customize Emacs. - -For example, I seldom want Fundamental mode when I edit an -otherwise undistinguished file; I want Text mode. This is why I -customize Emacs: so it suits me. - -You can customize and extend Emacs by writing or adapting a -@file{~/.emacs} file. This is your personal initialization file; its -contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You -may also add @file{.el} to @file{~/.emacs} and call it a -@file{~/.emacs.el} file. In the past, you were forbidden to type the -extra keystrokes that the name @file{~/.emacs.el} requires, but now -you may. The new format is consistent with the Emacs Lisp file -naming conventions; the old format saves typing.} - -A @file{~/.emacs} file contains Emacs Lisp code. You can write this -code yourself; or you can use Emacs's @code{customize} feature to write -the code for you. You can combine your own expressions and -auto-written Customize expressions in your @file{.emacs} file. - -(I myself prefer to write my own expressions, except for those, -particularly fonts, that I find easier to manipulate using the -@code{customize} command. I combine the two methods.) - -Most of this chapter is about writing expressions yourself. It -describes a simple @file{.emacs} file; for more information, see -@ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and -@ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference -Manual}. - -@node Site-wide Init, defcustom, Default Configuration, Emacs Initialization -@section Site-wide Initialization Files - -@cindex @file{default.el} init file -@cindex @file{site-init.el} init file -@cindex @file{site-load.el} init file -In addition to your personal initialization file, Emacs automatically -loads various site-wide initialization files, if they exist. These -have the same form as your @file{.emacs} file, but are loaded by -everyone. - -Two site-wide initialization files, @file{site-load.el} and -@file{site-init.el}, are loaded into Emacs and then `dumped' if a -`dumped' version of Emacs is created, as is most common. (Dumped -copies of Emacs load more quickly. However, once a file is loaded and -dumped, a change to it does not lead to a change in Emacs unless you -load it yourself or re-dump Emacs. @xref{Building Emacs, , Building -Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the -@file{INSTALL} file.) - -Three other site-wide initialization files are loaded automatically -each time you start Emacs, if they exist. These are -@file{site-start.el}, which is loaded @emph{before} your @file{.emacs} -file, and @file{default.el}, and the terminal type file, which are both -loaded @emph{after} your @file{.emacs} file. - -Settings and definitions in your @file{.emacs} file will overwrite -conflicting settings and definitions in a @file{site-start.el} file, -if it exists; but the settings and definitions in a @file{default.el} -or terminal type file will overwrite those in your @file{.emacs} file. -(You can prevent interference from a terminal type file by setting -@code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A -Simple Extension}.) - -@c Rewritten to avoid overfull hbox. -The @file{INSTALL} file that comes in the distribution contains -descriptions of the @file{site-init.el} and @file{site-load.el} files. - -The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files -control loading. These files are in the @file{lisp} directory of the -Emacs distribution and are worth perusing. - -The @file{loaddefs.el} file contains a good many suggestions as to -what to put into your own @file{.emacs} file, or into a site-wide -initialization file. - -@node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization -@section Specifying Variables using @code{defcustom} -@findex defcustom - -You can specify variables using @code{defcustom} so that you and -others can then use Emacs's @code{customize} feature to set their -values. (You cannot use @code{customize} to write function -definitions; but you can write @code{defuns} in your @file{.emacs} -file. Indeed, you can write any Lisp expression in your @file{.emacs} -file.) - -The @code{customize} feature depends on the @code{defcustom} special -form. Although you can use @code{defvar} or @code{setq} for variables -that users set, the @code{defcustom} special form is designed for the -job. - -You can use your knowledge of @code{defvar} for writing the -first three arguments for @code{defcustom}. The first argument to -@code{defcustom} is the name of the variable. The second argument is -the variable's initial value, if any; and this value is set only if -the value has not already been set. The third argument is the -documentation. - -The fourth and subsequent arguments to @code{defcustom} specify types -and options; these are not featured in @code{defvar}. (These -arguments are optional.) - -Each of these arguments consists of a keyword followed by a value. -Each keyword starts with the colon character @samp{:}. - -@need 1250 -For example, the customizable user option variable -@code{text-mode-hook} looks like this: - -@smallexample -@group -(defcustom text-mode-hook nil - "Normal hook run when entering Text mode and many related modes." - :type 'hook - :options '(turn-on-auto-fill flyspell-mode) - :group 'data) -@end group -@end smallexample - -@noindent -The name of the variable is @code{text-mode-hook}; it has no default -value; and its documentation string tells you what it does. - -The @code{:type} keyword tells Emacs the kind of data to which -@code{text-mode-hook} should be set and how to display the value in a -Customization buffer. - -The @code{:options} keyword specifies a suggested list of values for -the variable. Usually, @code{:options} applies to a hook. -The list is only a suggestion; it is not exclusive; a person who sets -the variable may set it to other values; the list shown following the -@code{:options} keyword is intended to offer convenient choices to a -user. - -Finally, the @code{:group} keyword tells the Emacs Customization -command in which group the variable is located. This tells where to -find it. - -The @code{defcustom} function recognizes more than a dozen keywords. -For more information, see @ref{Customization, , Writing Customization -Definitions, elisp, The GNU Emacs Lisp Reference Manual}. - -Consider @code{text-mode-hook} as an example. - -There are two ways to customize this variable. You can use the -customization command or write the appropriate expressions yourself. - -@need 800 -Using the customization command, you can type: - -@smallexample -M-x customize -@end smallexample - -@noindent -and find that the group for editing files of data is called `data'. -Enter that group. Text Mode Hook is the first member. You can click -on its various options, such as @code{turn-on-auto-fill}, to set the -values. After you click on the button to - -@smallexample -Save for Future Sessions -@end smallexample - -@noindent -Emacs will write an expression into your @file{.emacs} file. -It will look like this: - -@smallexample -@group -(custom-set-variables - ;; custom-set-variables was added by Custom. - ;; If you edit it by hand, you could mess it up, so be careful. - ;; Your init file should contain only one such instance. - ;; If there is more than one, they won't work right. - '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify)))) -@end group -@end smallexample - -@noindent -(The @code{text-mode-hook-identify} function tells -@code{toggle-text-mode-auto-fill} which buffers are in Text mode. -It comes on automatically.) - -The @code{custom-set-variables} function works somewhat differently -than a @code{setq}. While I have never learned the differences, I -modify the @code{custom-set-variables} expressions in my @file{.emacs} -file by hand: I make the changes in what appears to me to be a -reasonable manner and have not had any problems. Others prefer to use -the Customization command and let Emacs do the work for them. - -Another @code{custom-set-@dots{}} function is @code{custom-set-faces}. -This function sets the various font faces. Over time, I have set a -considerable number of faces. Some of the time, I re-set them using -@code{customize}; other times, I simply edit the -@code{custom-set-faces} expression in my @file{.emacs} file itself. - -The second way to customize your @code{text-mode-hook} is to set it -yourself in your @file{.emacs} file using code that has nothing to do -with the @code{custom-set-@dots{}} functions. - -@need 800 -When you do this, and later use @code{customize}, you will see a -message that says - -@smallexample -CHANGED outside Customize; operating on it here may be unreliable. -@end smallexample - -@need 800 -This message is only a warning. If you click on the button to - -@smallexample -Save for Future Sessions -@end smallexample - -@noindent -Emacs will write a @code{custom-set-@dots{}} expression near the end -of your @file{.emacs} file that will be evaluated after your -hand-written expression. It will, therefore, overrule your -hand-written expression. No harm will be done. When you do this, -however, be careful to remember which expression is active; if you -forget, you may confuse yourself. - -So long as you remember where the values are set, you will have no -trouble. In any event, the values are always set in your -initialization file, which is usually called @file{.emacs}. - -I myself use @code{customize} for hardly anything. Mostly, I write -expressions myself. - -@findex defsubst -@findex defconst -Incidentally, to be more complete concerning defines: @code{defsubst} -defines an inline function. The syntax is just like that of -@code{defun}. @code{defconst} defines a symbol as a constant. The -intent is that neither programs nor users should ever change a value -set by @code{defconst}. (You can change it; the value set is a -variable; but please do not.) - -@node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization -@section Beginning a @file{.emacs} File -@cindex @file{.emacs} file, beginning of - -When you start Emacs, it loads your @file{.emacs} file unless you tell -it not to by specifying @samp{-q} on the command line. (The -@code{emacs -q} command gives you a plain, out-of-the-box Emacs.) - -A @file{.emacs} file contains Lisp expressions. Often, these are no -more than expressions to set values; sometimes they are function -definitions. - -@xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs -Manual}, for a short description of initialization files. - -This chapter goes over some of the same ground, but is a walk among -extracts from a complete, long-used @file{.emacs} file---my own. - -The first part of the file consists of comments: reminders to myself. -By now, of course, I remember these things, but when I started, I did -not. - -@need 1200 -@smallexample -@group -;;;; Bob's .emacs file -; Robert J. Chassell -; 26 September 1985 -@end group -@end smallexample - -@noindent -Look at that date! I started this file a long time ago. I have been -adding to it ever since. - -@smallexample -@group -; Each section in this file is introduced by a -; line beginning with four semicolons; and each -; entry is introduced by a line beginning with -; three semicolons. -@end group -@end smallexample - -@noindent -This describes the usual conventions for comments in Emacs Lisp. -Everything on a line that follows a semicolon is a comment. Two, -three, and four semicolons are used as subsection and section markers. -(@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for -more about comments.) - -@smallexample -@group -;;;; The Help Key -; Control-h is the help key; -; after typing control-h, type a letter to -; indicate the subject about which you want help. -; For an explanation of the help facility, -; type control-h two times in a row. -@end group -@end smallexample - -@noindent -Just remember: type @kbd{C-h} two times for help. - -@smallexample -@group -; To find out about any mode, type control-h m -; while in that mode. For example, to find out -; about mail mode, enter mail mode and then type -; control-h m. -@end group -@end smallexample - -@noindent -`Mode help', as I call this, is very helpful. Usually, it tells you -all you need to know. - -Of course, you don't need to include comments like these in your -@file{.emacs} file. I included them in mine because I kept forgetting -about Mode help or the conventions for comments---but I was able to -remember to look here to remind myself. - -@node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization -@section Text and Auto Fill Mode - -Now we come to the part that `turns on' Text mode and -Auto Fill mode. - -@smallexample -@group -;;; Text mode and Auto Fill mode -;; The next two lines put Emacs into Text mode -;; and Auto Fill mode, and are for writers who -;; want to start writing prose rather than code. -(setq-default major-mode 'text-mode) -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end group -@end smallexample - -Here is the first part of this @file{.emacs} file that does something -besides remind a forgetful human! - -The first of the two lines in parentheses tells Emacs to turn on Text -mode when you find a file, @emph{unless} that file should go into some -other mode, such as C mode. - -@cindex Per-buffer, local variables list -@cindex Local variables list, per-buffer, -@cindex Automatic mode selection -@cindex Mode selection, automatic -When Emacs reads a file, it looks at the extension to the file name, -if any. (The extension is the part that comes after a @samp{.}.) If -the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns -on C mode. Also, Emacs looks at first nonblank line of the file; if -the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs -possesses a list of extensions and specifications that it uses -automatically. In addition, Emacs looks near the last page for a -per-buffer, ``local variables list'', if any. - -@ifinfo -@xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU -Emacs Manual}. - -@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs -Manual}. -@end ifinfo -@iftex -See sections ``How Major Modes are Chosen'' and ``Local Variables in -Files'' in @cite{The GNU Emacs Manual}. -@end iftex - -Now, back to the @file{.emacs} file. - -@need 800 -Here is the line again; how does it work? - -@cindex Text Mode turned on -@smallexample -(setq major-mode 'text-mode) -@end smallexample - -@noindent -This line is a short, but complete Emacs Lisp expression. - -We are already familiar with @code{setq}. It sets the following variable, -@code{major-mode}, to the subsequent value, which is @code{text-mode}. -The single quote mark before @code{text-mode} tells Emacs to deal directly -with the @code{text-mode} symbol, not with whatever it might stand for. -@xref{set & setq, , Setting the Value of a Variable}, -for a reminder of how @code{setq} works. -The main point is that there is no difference between the procedure you -use to set a value in your @file{.emacs} file and the procedure you use -anywhere else in Emacs. - -@need 800 -Here is the next line: - -@cindex Auto Fill mode turned on -@findex add-hook -@smallexample -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end smallexample - -@noindent -In this line, the @code{add-hook} command adds -@code{turn-on-auto-fill} to the variable. - -@code{turn-on-auto-fill} is the name of a program, that, you guessed -it!, turns on Auto Fill mode. - -Every time Emacs turns on Text mode, Emacs runs the commands `hooked' -onto Text mode. So every time Emacs turns on Text mode, Emacs also -turns on Auto Fill mode. - -In brief, the first line causes Emacs to enter Text mode when you edit a -file, unless the file name extension, a first non-blank line, or local -variables to tell Emacs otherwise. - -Text mode among other actions, sets the syntax table to work -conveniently for writers. In Text mode, Emacs considers an apostrophe -as part of a word like a letter; but Emacs does not consider a period -or a space as part of a word. Thus, @kbd{M-f} moves you over -@samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after -the @samp{t} of @samp{it's}. - -The second line causes Emacs to turn on Auto Fill mode when it turns -on Text mode. In Auto Fill mode, Emacs automatically breaks a line -that is too wide and brings the excessively wide part of the line down -to the next line. Emacs breaks lines between words, not within them. - -When Auto Fill mode is turned off, lines continue to the right as you -type them. Depending on how you set the value of -@code{truncate-lines}, the words you type either disappear off the -right side of the screen, or else are shown, in a rather ugly and -unreadable manner, as a continuation line on the screen. - -@need 1250 -In addition, in this part of my @file{.emacs} file, I tell the Emacs -fill commands to insert two spaces after a colon: - -@smallexample -(setq colon-double-space t) -@end smallexample - -@node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization -@section Mail Aliases - -Here is a @code{setq} that `turns on' mail aliases, along with more -reminders. - -@smallexample -@group -;;; Mail mode -; To enter mail mode, type `C-x m' -; To enter RMAIL (for reading mail), -; type `M-x rmail' -(setq mail-aliases t) -@end group -@end smallexample - -@cindex Mail aliases -@noindent -This @code{setq} command sets the value of the variable -@code{mail-aliases} to @code{t}. Since @code{t} means true, the line -says, in effect, ``Yes, use mail aliases.'' - -Mail aliases are convenient short names for long email addresses or -for lists of email addresses. The file where you keep your `aliases' -is @file{~/.mailrc}. You write an alias like this: - -@smallexample -alias geo george@@foobar.wiz.edu -@end smallexample - -@noindent -When you write a message to George, address it to @samp{geo}; the -mailer will automatically expand @samp{geo} to the full address. - -@node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization -@section Indent Tabs Mode -@cindex Tabs, preventing -@findex indent-tabs-mode - -By default, Emacs inserts tabs in place of multiple spaces when it -formats a region. (For example, you might indent many lines of text -all at once with the @code{indent-region} command.) Tabs look fine on -a terminal or with ordinary printing, but they produce badly indented -output when you use @TeX{} or Texinfo since @TeX{} ignores tabs. - -@need 1250 -The following turns off Indent Tabs mode: - -@smallexample -@group -;;; Prevent Extraneous Tabs -(setq-default indent-tabs-mode nil) -@end group -@end smallexample - -Note that this line uses @code{setq-default} rather than the -@code{setq} command that we have seen before. The @code{setq-default} -command sets values only in buffers that do not have their own local -values for the variable. - -@ifinfo -@xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}. - -@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs -Manual}. -@end ifinfo -@iftex -See sections ``Tabs vs.@: Spaces'' and ``Local Variables in -Files'' in @cite{The GNU Emacs Manual}. -@end iftex - -@need 1700 -@node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization -@section Some Keybindings - -Now for some personal keybindings: - -@smallexample -@group -;;; Compare windows -(global-set-key "\C-cw" 'compare-windows) -@end group -@end smallexample - -@findex compare-windows -@code{compare-windows} is a nifty command that compares the text in -your current window with text in the next window. It makes the -comparison by starting at point in each window, moving over text in -each window as far as they match. I use this command all the time. - -This also shows how to set a key globally, for all modes. - -@cindex Setting a key globally -@cindex Global set key -@cindex Key setting globally -@findex global-set-key -The command is @code{global-set-key}. It is followed by the -keybinding. In a @file{.emacs} file, the keybinding is written as -shown: @code{\C-c} stands for `control-c', which means `press the -control key and the @key{c} key at the same time'. The @code{w} means -`press the @key{w} key'. The keybinding is surrounded by double -quotation marks. In documentation, you would write this as -@w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as -@kbd{M-c}, rather than a @key{CTRL} key, you would write -@w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, , -Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for -details.) - -The command invoked by the keys is @code{compare-windows}. Note that -@code{compare-windows} is preceded by a single quote; otherwise, Emacs -would first try to evaluate the symbol to determine its value. - -These three things, the double quotation marks, the backslash before -the @samp{C}, and the single quote mark are necessary parts of -keybinding that I tend to forget. Fortunately, I have come to -remember that I should look at my existing @file{.emacs} file, and -adapt what is there. - -As for the keybinding itself: @kbd{C-c w}. This combines the prefix -key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This -set of keys, @kbd{C-c} followed by a single character, is strictly -reserved for individuals' own use. (I call these `own' keys, since -these are for my own use.) You should always be able to create such a -keybinding for your own use without stomping on someone else's -keybinding. If you ever write an extension to Emacs, please avoid -taking any of these keys for public use. Create a key like @kbd{C-c -C-w} instead. Otherwise, we will run out of `own' keys. - -@need 1250 -Here is another keybinding, with a comment: - -@smallexample -@group -;;; Keybinding for `occur' -; I use occur a lot, so let's bind it to a key: -(global-set-key "\C-co" 'occur) -@end group -@end smallexample - -@findex occur -The @code{occur} command shows all the lines in the current buffer -that contain a match for a regular expression. Matching lines are -shown in a buffer called @file{*Occur*}. That buffer serves as a menu -to jump to occurrences. - -@findex global-unset-key -@cindex Unbinding key -@cindex Key unbinding -@need 1250 -Here is how to unbind a key, so it does not -work: - -@smallexample -@group -;;; Unbind `C-x f' -(global-unset-key "\C-xf") -@end group -@end smallexample - -There is a reason for this unbinding: I found I inadvertently typed -@w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a -file, as I intended, I accidentally set the width for filled text, -almost always to a width I did not want. Since I hardly ever reset my -default width, I simply unbound the key. - -@findex list-buffers, @r{rebound} -@findex buffer-menu, @r{bound to key} -@need 1250 -The following rebinds an existing key: - -@smallexample -@group -;;; Rebind `C-x C-b' for `buffer-menu' -(global-set-key "\C-x\C-b" 'buffer-menu) -@end group -@end smallexample - -By default, @kbd{C-x C-b} runs the -@code{list-buffers} command. This command lists -your buffers in @emph{another} window. Since I -almost always want to do something in that -window, I prefer the @code{buffer-menu} -command, which not only lists the buffers, -but moves point into that window. - -@node Keymaps, Loading Files, Keybindings, Emacs Initialization -@section Keymaps -@cindex Keymaps -@cindex Rebinding keys - -Emacs uses @dfn{keymaps} to record which keys call which commands. -When you use @code{global-set-key} to set the keybinding for a single -command in all parts of Emacs, you are specifying the keybinding in -@code{current-global-map}. - -Specific modes, such as C mode or Text mode, have their own keymaps; -the mode-specific keymaps override the global map that is shared by -all buffers. - -The @code{global-set-key} function binds, or rebinds, the global -keymap. For example, the following binds the key @kbd{C-x C-b} to the -function @code{buffer-menu}: - -@smallexample -(global-set-key "\C-x\C-b" 'buffer-menu) -@end smallexample - -Mode-specific keymaps are bound using the @code{define-key} function, -which takes a specific keymap as an argument, as well as the key and -the command. For example, my @file{.emacs} file contains the -following expression to bind the @code{texinfo-insert-@@group} command -to @kbd{C-c C-c g}: - -@smallexample -@group -(define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group) -@end group -@end smallexample - -@noindent -The @code{texinfo-insert-@@group} function itself is a little extension -to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I -use this command all the time and prefer to type the three strokes -@kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}. -(@samp{@@group} and its matching @samp{@@end group} are commands that -keep all enclosed text together on one page; many multi-line examples -in this book are surrounded by @samp{@@group @dots{} @@end group}.) - -@need 1250 -Here is the @code{texinfo-insert-@@group} function definition: - -@smallexample -@group -(defun texinfo-insert-@@group () - "Insert the string @@group in a Texinfo buffer." - (interactive) - (beginning-of-line) - (insert "@@group\n")) -@end group -@end smallexample - -(Of course, I could have used Abbrev mode to save typing, rather than -write a function to insert a word; but I prefer key strokes consistent -with other Texinfo mode key bindings.) - -You will see numerous @code{define-key} expressions in -@file{loaddefs.el} as well as in the various mode libraries, such as -@file{cc-mode.el} and @file{lisp-mode.el}. - -@xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs -Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp -Reference Manual}, for more information about keymaps. - -@node Loading Files, Autoload, Keymaps, Emacs Initialization -@section Loading Files -@cindex Loading files -@c findex load - -Many people in the GNU Emacs community have written extensions to -Emacs. As time goes by, these extensions are often included in new -releases. For example, the Calendar and Diary packages are now part -of the standard GNU Emacs, as is Calc. - -You can use a @code{load} command to evaluate a complete file and -thereby install all the functions and variables in the file into Emacs. -For example: - -@c (auto-compression-mode t) - -@smallexample -(load "~/emacs/slowsplit") -@end smallexample - -This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it -exists, the faster, byte compiled @file{slowsplit.elc} file from the -@file{emacs} sub-directory of your home directory. The file contains -the function @code{split-window-quietly}, which John Robinson wrote in -1989. - -The @code{split-window-quietly} function splits a window with the -minimum of redisplay. I installed it in 1989 because it worked well -with the slow 1200 baud terminals I was then using. Nowadays, I only -occasionally come across such a slow connection, but I continue to use -the function because I like the way it leaves the bottom half of a -buffer in the lower of the new windows and the top half in the upper -window. - -@need 1250 -To replace the key binding for the default -@code{split-window-vertically}, you must also unset that key and bind -the keys to @code{split-window-quietly}, like this: - -@smallexample -@group -(global-unset-key "\C-x2") -(global-set-key "\C-x2" 'split-window-quietly) -@end group -@end smallexample - -@vindex load-path -If you load many extensions, as I do, then instead of specifying the -exact location of the extension file, as shown above, you can specify -that directory as part of Emacs's @code{load-path}. Then, when Emacs -loads a file, it will search that directory as well as its default -list of directories. (The default list is specified in @file{paths.h} -when Emacs is built.) - -@need 1250 -The following command adds your @file{~/emacs} directory to the -existing load path: - -@smallexample -@group -;;; Emacs Load Path -(setq load-path (cons "~/emacs" load-path)) -@end group -@end smallexample - -Incidentally, @code{load-library} is an interactive interface to the -@code{load} function. The complete function looks like this: - -@findex load-library -@smallexample -@group -(defun load-library (library) - "Load the library named LIBRARY. -This is an interface to the function `load'." - (interactive - (list (completing-read "Load library: " - (apply-partially 'locate-file-completion-table - load-path - (get-load-suffixes))))) - (load library)) -@end group -@end smallexample - -The name of the function, @code{load-library}, comes from the use of -`library' as a conventional synonym for `file'. The source for the -@code{load-library} command is in the @file{files.el} library. - -Another interactive command that does a slightly different job is -@code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for -Emacs, emacs, The GNU Emacs Manual}, for information on the -distinction between @code{load-library} and this command. - -@node Autoload, Simple Extension, Loading Files, Emacs Initialization -@section Autoloading -@findex autoload - -Instead of installing a function by loading the file that contains it, -or by evaluating the function definition, you can make the function -available but not actually install it until it is first called. This -is called @dfn{autoloading}. - -When you execute an autoloaded function, Emacs automatically evaluates -the file that contains the definition, and then calls the function. - -Emacs starts quicker with autoloaded functions, since their libraries -are not loaded right away; but you need to wait a moment when you -first use such a function, while its containing file is evaluated. - -Rarely used functions are frequently autoloaded. The -@file{loaddefs.el} library contains hundreds of autoloaded functions, -from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may -come to use a `rare' function frequently. When you do, you should -load that function's file with a @code{load} expression in your -@file{.emacs} file. - -In my @file{.emacs} file, I load 14 libraries that contain functions -that would otherwise be autoloaded. (Actually, it would have been -better to include these files in my `dumped' Emacs, but I forgot. -@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp -Reference Manual}, and the @file{INSTALL} file for more about -dumping.) - -You may also want to include autoloaded expressions in your @file{.emacs} -file. @code{autoload} is a built-in function that takes up to five -arguments, the final three of which are optional. The first argument -is the name of the function to be autoloaded; the second is the name -of the file to be loaded. The third argument is documentation for the -function, and the fourth tells whether the function can be called -interactively. The fifth argument tells what type of -object---@code{autoload} can handle a keymap or macro as well as a -function (the default is a function). - -@need 800 -Here is a typical example: - -@smallexample -@group -(autoload 'html-helper-mode - "html-helper-mode" "Edit HTML documents" t) -@end group -@end smallexample - -@noindent -(@code{html-helper-mode} is an older alternative to @code{html-mode}, -which is a standard part of the distribution.) - -@noindent -This expression autoloads the @code{html-helper-mode} function. It -takes it from the @file{html-helper-mode.el} file (or from the byte -compiled version @file{html-helper-mode.elc}, if that exists.) The -file must be located in a directory specified by @code{load-path}. -The documentation says that this is a mode to help you edit documents -written in the HyperText Markup Language. You can call this mode -interactively by typing @kbd{M-x html-helper-mode}. (You need to -duplicate the function's regular documentation in the autoload -expression because the regular function is not yet loaded, so its -documentation is not available.) - -@xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference -Manual}, for more information. - -@node Simple Extension, X11 Colors, Autoload, Emacs Initialization -@section A Simple Extension: @code{line-to-top-of-window} -@findex line-to-top-of-window -@cindex Simple extension in @file{.emacs} file - -Here is a simple extension to Emacs that moves the line point is on to -the top of the window. I use this all the time, to make text easier -to read. - -You can put the following code into a separate file and then load it -from your @file{.emacs} file, or you can include it within your -@file{.emacs} file. - -@need 1250 -Here is the definition: - -@smallexample -@group -;;; Line to top of window; -;;; replace three keystroke sequence C-u 0 C-l -(defun line-to-top-of-window () - "Move the line point is on to top of window." - (interactive) - (recenter 0)) -@end group -@end smallexample - -@need 1250 -Now for the keybinding. - -Nowadays, function keys as well as mouse button events and -non-@sc{ascii} characters are written within square brackets, without -quotation marks. (In Emacs version 18 and before, you had to write -different function key bindings for each different make of terminal.) - -I bind @code{line-to-top-of-window} to my @key{F6} function key like -this: - -@smallexample -(global-set-key [f6] 'line-to-top-of-window) -@end smallexample - -For more information, see @ref{Init Rebinding, , Rebinding Keys in -Your Init File, emacs, The GNU Emacs Manual}. - -@cindex Conditional 'twixt two versions of Emacs -@cindex Version of Emacs, choosing -@cindex Emacs version, choosing -If you run two versions of GNU Emacs, such as versions 22 and 23, and -use one @file{.emacs} file, you can select which code to evaluate with -the following conditional: - -@smallexample -@group -(cond - ((= 22 emacs-major-version) - ;; evaluate version 22 code - ( @dots{} )) - ((= 23 emacs-major-version) - ;; evaluate version 23 code - ( @dots{} ))) -@end group -@end smallexample - -For example, recent versions blink -their cursors by default. I hate such blinking, as well as other -features, so I placed the following in my @file{.emacs} -file@footnote{When I start instances of Emacs that do not load my -@file{.emacs} file or any site file, I also turn off blinking: - -@smallexample -emacs -q --no-site-file -eval '(blink-cursor-mode nil)' - -@exdent Or nowadays, using an even more sophisticated set of options, - -emacs -Q - D -@end smallexample -}: - -@smallexample -@group -(when (>= emacs-major-version 21) - (blink-cursor-mode 0) - ;; Insert newline when you press `C-n' (next-line) - ;; at the end of the buffer - (setq next-line-add-newlines t) -@end group -@group - ;; Turn on image viewing - (auto-image-file-mode t) -@end group -@group - ;; Turn on menu bar (this bar has text) - ;; (Use numeric argument to turn on) - (menu-bar-mode 1) -@end group -@group - ;; Turn off tool bar (this bar has icons) - ;; (Use numeric argument to turn on) - (tool-bar-mode nil) -@end group -@group - ;; Turn off tooltip mode for tool bar - ;; (This mode causes icon explanations to pop up) - ;; (Use numeric argument to turn on) - (tooltip-mode nil) - ;; If tooltips turned on, make tips appear promptly - (setq tooltip-delay 0.1) ; default is 0.7 second - ) -@end group -@end smallexample - -@node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization -@section X11 Colors - -You can specify colors when you use Emacs with the MIT X Windowing -system. - -I dislike the default colors and specify my own. - -@need 1250 -Here are the expressions in my @file{.emacs} -file that set values: - -@smallexample -@group -;; Set cursor color -(set-cursor-color "white") - -;; Set mouse color -(set-mouse-color "white") - -;; Set foreground and background -(set-foreground-color "white") -(set-background-color "darkblue") -@end group - -@group -;;; Set highlighting colors for isearch and drag -(set-face-foreground 'highlight "white") -(set-face-background 'highlight "blue") -@end group - -@group -(set-face-foreground 'region "cyan") -(set-face-background 'region "blue") -@end group - -@group -(set-face-foreground 'secondary-selection "skyblue") -(set-face-background 'secondary-selection "darkblue") -@end group - -@group -;; Set calendar highlighting colors -(setq calendar-load-hook - '(lambda () - (set-face-foreground 'diary-face "skyblue") - (set-face-background 'holiday-face "slate blue") - (set-face-foreground 'holiday-face "white"))) -@end group -@end smallexample - -The various shades of blue soothe my eye and prevent me from seeing -the screen flicker. - -Alternatively, I could have set my specifications in various X -initialization files. For example, I could set the foreground, -background, cursor, and pointer (i.e., mouse) colors in my -@file{~/.Xresources} file like this: - -@smallexample -@group -Emacs*foreground: white -Emacs*background: darkblue -Emacs*cursorColor: white -Emacs*pointerColor: white -@end group -@end smallexample - -In any event, since it is not part of Emacs, I set the root color of -my X window in my @file{~/.xinitrc} file, like this@footnote{I also -run more modern window managers, such as Enlightenment, Gnome, or KDE; -in those cases, I often specify an image rather than a plain color.}: - -@smallexample -xsetroot -solid Navy -fg white & -@end smallexample - -@need 1700 -@node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization -@section Miscellaneous Settings for a @file{.emacs} File - -@need 1250 -Here are a few miscellaneous settings: -@sp 1 - -@itemize @minus -@item -Set the shape and color of the mouse cursor: - -@smallexample -@group -; Cursor shapes are defined in -; `/usr/include/X11/cursorfont.h'; -; for example, the `target' cursor is number 128; -; the `top_left_arrow' cursor is number 132. -@end group - -@group -(let ((mpointer (x-get-resource "*mpointer" - "*emacs*mpointer"))) - ;; If you have not set your mouse pointer - ;; then set it, otherwise leave as is: - (if (eq mpointer nil) - (setq mpointer "132")) ; top_left_arrow -@end group -@group - (setq x-pointer-shape (string-to-int mpointer)) - (set-mouse-color "white")) -@end group -@end smallexample - -@item -Or you can set the values of a variety of features in an alist, like -this: - -@smallexample -@group -(setq-default - default-frame-alist - '((cursor-color . "white") - (mouse-color . "white") - (foreground-color . "white") - (background-color . "DodgerBlue4") - ;; (cursor-type . bar) - (cursor-type . box) -@end group -@group - (tool-bar-lines . 0) - (menu-bar-lines . 1) - (width . 80) - (height . 58) - (font . - "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1") - )) -@end group -@end smallexample - -@item -Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL} -into @kbd{@key{CTRL}-h}.@* -(Some older keyboards needed this, although I have not seen the -problem recently.) - -@smallexample -@group -;; Translate `C-h' to . -; (keyboard-translate ?\C-h ?\C-?) - -;; Translate to `C-h'. -(keyboard-translate ?\C-? ?\C-h) -@end group -@end smallexample - -@item Turn off a blinking cursor! - -@smallexample -@group -(if (fboundp 'blink-cursor-mode) - (blink-cursor-mode -1)) -@end group -@end smallexample - -@noindent -or start GNU Emacs with the command @code{emacs -nbc}. - -@need 1250 -@item When using `grep'@* -@samp{-i}@w{ } Ignore case distinctions@* -@samp{-n}@w{ } Prefix each line of output with line number@* -@samp{-H}@w{ } Print the filename for each match.@* -@samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-} - -@smallexample -(setq grep-command "grep -i -nH -e ") -@end smallexample - -@ignore -@c Evidently, no longer needed in GNU Emacs 22 - -item Automatically uncompress compressed files when visiting them - -smallexample -(load "uncompress") -end smallexample - -@end ignore - -@item Find an existing buffer, even if it has a different name@* -This avoids problems with symbolic links. - -@smallexample -(setq find-file-existing-other-name t) -@end smallexample - -@item Set your language environment and default input method - -@smallexample -@group -(set-language-environment "latin-1") -;; Remember you can enable or disable multilingual text input -;; with the @code{toggle-input-method'} (@kbd{C-\}) command -(setq default-input-method "latin-1-prefix") -@end group -@end smallexample - -If you want to write with Chinese `GB' characters, set this instead: - -@smallexample -@group -(set-language-environment "Chinese-GB") -(setq default-input-method "chinese-tonepy") -@end group -@end smallexample -@end itemize - -@subsubheading Fixing Unpleasant Key Bindings -@cindex Key bindings, fixing -@cindex Bindings, key, fixing unpleasant - -Some systems bind keys unpleasantly. Sometimes, for example, the -@key{CTRL} key appears in an awkward spot rather than at the far left -of the home row. - -Usually, when people fix these sorts of keybindings, they do not -change their @file{~/.emacs} file. Instead, they bind the proper keys -on their consoles with the @code{loadkeys} or @code{install-keymap} -commands in their boot script and then include @code{xmodmap} commands -in their @file{.xinitrc} or @file{.Xsession} file for X Windows. - -@need 1250 -@noindent -For a boot script: - -@smallexample -@group -loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz -@exdent or -install-keymap emacs2 -@end group -@end smallexample - -@need 1250 -@noindent -For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps -Lock} key is at the far left of the home row: - -@smallexample -@group -# Bind the key labeled `Caps Lock' to `Control' -# (Such a broken user interface suggests that keyboard manufacturers -# think that computers are typewriters from 1885.) - -xmodmap -e "clear Lock" -xmodmap -e "add Control = Caps_Lock" -@end group -@end smallexample - -@need 1250 -@noindent -In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT} -key to a @key{META} key: - -@smallexample -@group -# Some ill designed keyboards have a key labeled ALT and no Meta -xmodmap -e "keysym Alt_L = Meta_L Alt_L" -@end group -@end smallexample - -@need 1700 -@node Mode Line, , Miscellaneous, Emacs Initialization -@section A Modified Mode Line -@vindex mode-line-format -@cindex Mode line format - -Finally, a feature I really like: a modified mode line. - -When I work over a network, I forget which machine I am using. Also, -I tend to I lose track of where I am, and which line point is on. - -So I reset my mode line to look like this: - -@smallexample --:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top -@end smallexample - -I am visiting a file called @file{foo.texi}, on my machine -@file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in -Texinfo mode, and am at the top of the buffer. - -@need 1200 -My @file{.emacs} file has a section that looks like this: - -@smallexample -@group -;; Set a Mode Line that tells me which machine, which directory, -;; and which line I am on, plus the other customary information. -(setq-default mode-line-format - (quote - (#("-" 0 1 - (help-echo - "mouse-1: select window, mouse-2: delete others ...")) - mode-line-mule-info - mode-line-modified - mode-line-frame-identification - " " -@end group -@group - mode-line-buffer-identification - " " - (:eval (substring - (system-name) 0 (string-match "\\..+" (system-name)))) - ":" - default-directory - #(" " 0 1 - (help-echo - "mouse-1: select window, mouse-2: delete others ...")) - (line-number-mode " Line %l ") - global-mode-string -@end group -@group - #(" %[(" 0 6 - (help-echo - "mouse-1: select window, mouse-2: delete others ...")) - (:eval (mode-line-mode-name)) - mode-line-process - minor-mode-alist - #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...))) - ")%] " - (-3 . "%P") - ;; "-%-" - ))) -@end group -@end smallexample - -@noindent -Here, I redefine the default mode line. Most of the parts are from -the original; but I make a few changes. I set the @emph{default} mode -line format so as to permit various modes, such as Info, to override -it. - -Many elements in the list are self-explanatory: -@code{mode-line-modified} is a variable that tells whether the buffer -has been modified, @code{mode-name} tells the name of the mode, and so -on. However, the format looks complicated because of two features we -have not discussed. - -@cindex Properties, in mode line example -The first string in the mode line is a dash or hyphen, @samp{-}. In -the old days, it would have been specified simply as @code{"-"}. But -nowadays, Emacs can add properties to a string, such as highlighting -or, as in this case, a help feature. If you place your mouse cursor -over the hyphen, some help information appears (By default, you must -wait seven-tenths of a second before the information appears. You can -change that timing by changing the value of @code{tooltip-delay}.) - -@need 1000 -The new string format has a special syntax: - -@smallexample -#("-" 0 1 (help-echo "mouse-1: select window, ...")) -@end smallexample - -@noindent -The @code{#(} begins a list. The first element of the list is the -string itself, just one @samp{-}. The second and third -elements specify the range over which the fourth element applies. A -range starts @emph{after} a character, so a zero means the range -starts just before the first character; a 1 means that the range ends -just after the first character. The third element is the property for -the range. It consists of a property list, a -property name, in this case, @samp{help-echo}, followed by a value, in this -case, a string. The second, third, and fourth elements of this new -string format can be repeated. - -@xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp -Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format, -elisp, The GNU Emacs Lisp Reference Manual}, for more information. - -@code{mode-line-buffer-identification} -displays the current buffer name. It is a list -beginning @code{(#("%12b" 0 4 @dots{}}. -The @code{#(} begins the list. - -The @samp{"%12b"} displays the current buffer name, using the -@code{buffer-name} function with which we are familiar; the `12' -specifies the maximum number of characters that will be displayed. -When a name has fewer characters, whitespace is added to fill out to -this number. (Buffer names can and often should be longer than 12 -characters; this length works well in a typical 80 column wide -window.) - -@code{:eval} says to evaluate the following form and use the result as -a string to display. In this case, the expression displays the first -component of the full system name. The end of the first component is -a @samp{.} (`period'), so I use the @code{string-match} function to -tell me the length of the first component. The substring from the -zeroth character to that length is the name of the machine. - -@need 1250 -This is the expression: - -@smallexample -@group -(:eval (substring - (system-name) 0 (string-match "\\..+" (system-name)))) -@end group -@end smallexample - -@samp{%[} and @samp{%]} cause a pair of square brackets -to appear for each recursive editing level. @samp{%n} says `Narrow' -when narrowing is in effect. @samp{%P} tells you the percentage of -the buffer that is above the bottom of the window, or `Top', `Bottom', -or `All'. (A lower case @samp{p} tell you the percentage above the -@emph{top} of the window.) @samp{%-} inserts enough dashes to fill -out the line. - -Remember, ``You don't have to like Emacs to like it'' --- your own -Emacs can have different colors, different commands, and different -keys than a default Emacs. - -On the other hand, if you want to bring up a plain `out of the box' -Emacs, with no customization, type: - -@smallexample -emacs -q -@end smallexample - -@noindent -This will start an Emacs that does @emph{not} load your -@file{~/.emacs} initialization file. A plain, default Emacs. Nothing -more. - -@node Debugging, Conclusion, Emacs Initialization, Top -@chapter Debugging -@cindex debugging - -GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The -first is built into the internals of Emacs and is always with you; -the second requires that you instrument a function before you can use it. - -Both debuggers are described extensively in @ref{Debugging, , -Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}. -In this chapter, I will walk through a short example of each. - -@menu -* debug:: How to use the built-in debugger. -* debug-on-entry:: Start debugging when you call a function. -* debug-on-quit:: Start debugging when you quit with @kbd{C-g}. -* edebug:: How to use Edebug, a source level debugger. -* Debugging Exercises:: -@end menu - -@node debug, debug-on-entry, Debugging, Debugging -@section @code{debug} -@findex debug - -Suppose you have written a function definition that is intended to -return the sum of the numbers 1 through a given number. (This is the -@code{triangle} function discussed earlier. @xref{Decrementing -Example, , Example with Decrementing Counter}, for a discussion.) -@c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.) - -However, your function definition has a bug. You have mistyped -@samp{1=} for @samp{1-}. Here is the broken definition: - -@findex triangle-bugged -@smallexample -@group -(defun triangle-bugged (number) - "Return sum of numbers 1 through NUMBER inclusive." - (let ((total 0)) - (while (> number 0) - (setq total (+ total number)) - (setq number (1= number))) ; @r{Error here.} - total)) -@end group -@end smallexample - -If you are reading this in Info, you can evaluate this definition in -the normal fashion. You will see @code{triangle-bugged} appear in the -echo area. - -@need 1250 -Now evaluate the @code{triangle-bugged} function with an -argument of 4: - -@smallexample -(triangle-bugged 4) -@end smallexample - -@noindent -In a recent GNU Emacs, you will create and enter a @file{*Backtrace*} -buffer that says: - -@noindent -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function 1=) - (1= number) - (setq number (1= number)) - (while (> number 0) (setq total (+ total number)) - (setq number (1= number))) - (let ((total 0)) (while (> number 0) (setq total ...) - (setq number ...)) total) - triangle-bugged(4) -@end group -@group - eval((triangle-bugged 4)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -(I have reformatted this example slightly; the debugger does not fold -long lines. As usual, you can quit the debugger by typing @kbd{q} in -the @file{*Backtrace*} buffer.) - -In practice, for a bug as simple as this, the `Lisp error' line will -tell you what you need to know to correct the definition. The -function @code{1=} is `void'. - -@ignore -@need 800 -In GNU Emacs 20 and before, you will see: - -@smallexample -Symbol's function definition is void:@: 1= -@end smallexample - -@noindent -which has the same meaning as the @file{*Backtrace*} buffer line in -version 21. -@end ignore - -However, suppose you are not quite certain what is going on? -You can read the complete backtrace. - -In this case, you need to run a recent GNU Emacs, which automatically -starts the debugger that puts you in the @file{*Backtrace*} buffer; or -else, you need to start the debugger manually as described below. - -Read the @file{*Backtrace*} buffer from the bottom up; it tells you -what Emacs did that led to the error. Emacs made an interactive call -to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation -of the @code{triangle-bugged} expression. Each line above tells you -what the Lisp interpreter evaluated next. - -@need 1250 -The third line from the top of the buffer is - -@smallexample -(setq number (1= number)) -@end smallexample - -@noindent -Emacs tried to evaluate this expression; in order to do so, it tried -to evaluate the inner expression shown on the second line from the -top: - -@smallexample -(1= number) -@end smallexample - -@need 1250 -@noindent -This is where the error occurred; as the top line says: - -@smallexample -Debugger entered--Lisp error: (void-function 1=) -@end smallexample - -@noindent -You can correct the mistake, re-evaluate the function definition, and -then run your test again. - -@node debug-on-entry, debug-on-quit, debug, Debugging -@section @code{debug-on-entry} -@findex debug-on-entry - -A recent GNU Emacs starts the debugger automatically when your -function has an error. - -@ignore -GNU Emacs version 20 and before did not; it simply -presented you with an error message. You had to start the debugger -manually. -@end ignore - -Incidentally, you can start the debugger manually for all versions of -Emacs; the advantage is that the debugger runs even if you do not have -a bug in your code. Sometimes your code will be free of bugs! - -You can enter the debugger when you call the function by calling -@code{debug-on-entry}. - -@need 1250 -@noindent -Type: - -@smallexample -M-x debug-on-entry RET triangle-bugged RET -@end smallexample - -@need 1250 -@noindent -Now, evaluate the following: - -@smallexample -(triangle-bugged 5) -@end smallexample - -@noindent -All versions of Emacs will create a @file{*Backtrace*} buffer and tell -you that it is beginning to evaluate the @code{triangle-bugged} -function: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--entering a function: -* triangle-bugged(5) - eval((triangle-bugged 5)) -@end group -@group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate -the first expression in @code{triangle-bugged}; the buffer will look -like this: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--beginning evaluation of function call form: -* (let ((total 0)) (while (> number 0) (setq total ...) - (setq number ...)) total) -* triangle-bugged(5) - eval((triangle-bugged 5)) -@end group -@group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -Now, type @kbd{d} again, eight times, slowly. Each time you type -@kbd{d}, Emacs will evaluate another expression in the function -definition. - -@need 1750 -Eventually, the buffer will look like this: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--beginning evaluation of function call form: -* (setq number (1= number)) -* (while (> number 0) (setq total (+ total number)) - (setq number (1= number))) -@group -@end group -* (let ((total 0)) (while (> number 0) (setq total ...) - (setq number ...)) total) -* triangle-bugged(5) - eval((triangle-bugged 5)) -@group -@end group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@need 1500 -@noindent -Finally, after you type @kbd{d} two more times, Emacs will reach the -error, and the top two lines of the @file{*Backtrace*} buffer will look -like this: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function 1=) -* (1= number) -@dots{} ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -By typing @kbd{d}, you were able to step through the function. - -You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this -quits the trace, but does not cancel @code{debug-on-entry}. - -@findex cancel-debug-on-entry -To cancel the effect of @code{debug-on-entry}, call -@code{cancel-debug-on-entry} and the name of the function, like this: - -@smallexample -M-x cancel-debug-on-entry RET triangle-bugged RET -@end smallexample - -@noindent -(If you are reading this in Info, cancel @code{debug-on-entry} now.) - -@node debug-on-quit, edebug, debug-on-entry, Debugging -@section @code{debug-on-quit} and @code{(debug)} - -In addition to setting @code{debug-on-error} or calling @code{debug-on-entry}, -there are two other ways to start @code{debug}. - -@findex debug-on-quit -You can start @code{debug} whenever you type @kbd{C-g} -(@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to -@code{t}. This is useful for debugging infinite loops. - -@need 1500 -@cindex @code{(debug)} in code -Or, you can insert a line that says @code{(debug)} into your code -where you want the debugger to start, like this: - -@smallexample -@group -(defun triangle-bugged (number) - "Return sum of numbers 1 through NUMBER inclusive." - (let ((total 0)) - (while (> number 0) - (setq total (+ total number)) - (debug) ; @r{Start debugger.} - (setq number (1= number))) ; @r{Error here.} - total)) -@end group -@end smallexample - -The @code{debug} function is described in detail in @ref{Debugger, , -The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}. - -@node edebug, Debugging Exercises, debug-on-quit, Debugging -@section The @code{edebug} Source Level Debugger -@cindex Source level debugger -@findex edebug - -Edebug is a source level debugger. Edebug normally displays the -source of the code you are debugging, with an arrow at the left that -shows which line you are currently executing. - -You can walk through the execution of a function, line by line, or run -quickly until reaching a @dfn{breakpoint} where execution stops. - -Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs -Lisp Reference Manual}. - -@need 1250 -Here is a bugged function definition for @code{triangle-recursively}. -@xref{Recursive triangle function, , Recursion in place of a counter}, -for a review of it. - -@smallexample -@group -(defun triangle-recursively-bugged (number) - "Return sum of numbers 1 through NUMBER inclusive. -Uses recursion." - (if (= number 1) - 1 - (+ number - (triangle-recursively-bugged - (1= number))))) ; @r{Error here.} -@end group -@end smallexample - -@noindent -Normally, you would install this definition by positioning your cursor -after the function's closing parenthesis and typing @kbd{C-x C-e} -(@code{eval-last-sexp}) or else by positioning your cursor within the -definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default, -the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp -Interaction mode.) - -@need 1500 -However, to prepare this function definition for Edebug, you must -first @dfn{instrument} the code using a different command. You can do -this by positioning your cursor within or just after the definition -and typing - -@smallexample -M-x edebug-defun RET -@end smallexample - -@noindent -This will cause Emacs to load Edebug automatically if it is not -already loaded, and properly instrument the function. - -After instrumenting the function, place your cursor after the -following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}): - -@smallexample -(triangle-recursively-bugged 3) -@end smallexample - -@noindent -You will be jumped back to the source for -@code{triangle-recursively-bugged} and the cursor positioned at the -beginning of the @code{if} line of the function. Also, you will see -an arrowhead at the left hand side of that line. The arrowhead marks -the line where the function is executing. (In the following examples, -we show the arrowhead with @samp{=>}; in a windowing system, you may -see the arrowhead as a solid triangle in the window `fringe'.) - -@smallexample -=>@point{}(if (= number 1) -@end smallexample - -@noindent -@iftex -In the example, the location of point is displayed with a star, -@samp{@point{}} (in Info, it is displayed as @samp{-!-}). -@end iftex -@ifnottex -In the example, the location of point is displayed as @samp{@point{}} -(in a printed book, it is displayed with a five pointed star). -@end ifnottex - -If you now press @key{SPC}, point will move to the next expression to -be executed; the line will look like this: - -@smallexample -=>(if @point{}(= number 1) -@end smallexample - -@noindent -As you continue to press @key{SPC}, point will move from expression to -expression. At the same time, whenever an expression returns a value, -that value will be displayed in the echo area. For example, after you -move point past @code{number}, you will see the following: - -@smallexample -Result: 3 (#o3, #x3, ?\C-c) -@end smallexample - -@noindent -This means the value of @code{number} is 3, which is octal three, -hexadecimal three, and @sc{ascii} `control-c' (the third letter of the -alphabet, in case you need to know this information). - -You can continue moving through the code until you reach the line with -the error. Before evaluation, that line looks like this: - -@smallexample -=> @point{}(1= number))))) ; @r{Error here.} -@end smallexample - -@need 1250 -@noindent -When you press @key{SPC} once again, you will produce an error message -that says: - -@smallexample -Symbol's function definition is void:@: 1= -@end smallexample - -@noindent -This is the bug. - -Press @kbd{q} to quit Edebug. - -To remove instrumentation from a function definition, simply -re-evaluate it with a command that does not instrument it. -For example, you could place your cursor after the definition's -closing parenthesis and type @kbd{C-x C-e}. - -Edebug does a great deal more than walk with you through a function. -You can set it so it races through on its own, stopping only at an -error or at specified stopping points; you can cause it to display the -changing values of various expressions; you can find out how many -times a function is called, and more. - -Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs -Lisp Reference Manual}. - -@need 1500 -@node Debugging Exercises, , edebug, Debugging -@section Debugging Exercises - -@itemize @bullet -@item -Install the @code{@value{COUNT-WORDS}} function and then cause it to -enter the built-in debugger when you call it. Run the command on a -region containing two words. You will need to press @kbd{d} a -remarkable number of times. On your system, is a `hook' called after -the command finishes? (For information on hooks, see @ref{Command -Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference -Manual}.) - -@item -Copy @code{@value{COUNT-WORDS}} into the @file{*scratch*} buffer, -instrument the function for Edebug, and walk through its execution. -The function does not need to have a bug, although you can introduce -one if you wish. If the function lacks a bug, the walk-through -completes without problems. - -@item -While running Edebug, type @kbd{?} to see a list of all the Edebug commands. -(The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@: -@kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix -for commands made outside of the Edebug debugging buffer.) - -@item -In the Edebug debugging buffer, use the @kbd{p} -(@code{edebug-bounce-point}) command to see where in the region the -@code{@value{COUNT-WORDS}} is working. - -@item -Move point to some spot further down the function and then type the -@kbd{h} (@code{edebug-goto-here}) command to jump to that location. - -@item -Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to -walk through the function on its own; use an upper case @kbd{T} for -@code{edebug-Trace-fast-mode}. - -@item -Set a breakpoint, then run Edebug in Trace mode until it reaches the -stopping point. -@end itemize - -@node Conclusion, the-the, Debugging, Top -@chapter Conclusion - -We have now reached the end of this Introduction. You have now -learned enough about programming in Emacs Lisp to set values, to write -simple @file{.emacs} files for yourself and your friends, and write -simple customizations and extensions to Emacs. - -This is a place to stop. Or, if you wish, you can now go onward, and -teach yourself. - -You have learned some of the basic nuts and bolts of programming. But -only some. There are a great many more brackets and hinges that are -easy to use that we have not touched. - -A path you can follow right now lies among the sources to GNU Emacs -and in -@ifnotinfo -@cite{The GNU Emacs Lisp Reference Manual}. -@end ifnotinfo -@ifinfo -@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU -Emacs Lisp Reference Manual}. -@end ifinfo - -The Emacs Lisp sources are an adventure. When you read the sources and -come across a function or expression that is unfamiliar, you need to -figure out or find out what it does. - -Go to the Reference Manual. It is a thorough, complete, and fairly -easy-to-read description of Emacs Lisp. It is written not only for -experts, but for people who know what you know. (The @cite{Reference -Manual} comes with the standard GNU Emacs distribution. Like this -introduction, it comes as a Texinfo source file, so you can read it -on-line and as a typeset, printed book.) - -Go to the other on-line help that is part of GNU Emacs: the on-line -documentation for all functions and variables, and @code{find-tag}, -the program that takes you to sources. - -Here is an example of how I explore the sources. Because of its name, -@file{simple.el} is the file I looked at first, a long time ago. As -it happens some of the functions in @file{simple.el} are complicated, -or at least look complicated at first sight. The @code{open-line} -function, for example, looks complicated. - -You may want to walk through this function slowly, as we did with the -@code{forward-sentence} function. (@xref{forward-sentence, The -@code{forward-sentence} function}.) Or you may want to skip that -function and look at another, such as @code{split-line}. You don't -need to read all the functions. According to -@code{count-words-in-defun}, the @code{split-line} function contains -102 words and symbols. - -Even though it is short, @code{split-line} contains expressions -we have not studied: @code{skip-chars-forward}, @code{indent-to}, -@code{current-column} and @code{insert-and-inherit}. - -Consider the @code{skip-chars-forward} function. (It is part of the -function definition for @code{back-to-indentation}, which is shown in -@ref{Review, , Review}.) - -In GNU Emacs, you can find out more about @code{skip-chars-forward} by -typing @kbd{C-h f} (@code{describe-function}) and the name of the -function. This gives you the function documentation. - -You may be able to guess what is done by a well named function such as -@code{indent-to}; or you can look it up, too. Incidentally, the -@code{describe-function} function itself is in @file{help.el}; it is -one of those long, but decipherable functions. You can look up -@code{describe-function} using the @kbd{C-h f} command! - -In this instance, since the code is Lisp, the @file{*Help*} buffer -contains the name of the library containing the function's source. -You can put point over the name of the library and press the RET key, -which in this situation is bound to @code{help-follow}, and be taken -directly to the source, in the same way as @kbd{M-.} -(@code{find-tag}). - -The definition for @code{describe-function} illustrates how to -customize the @code{interactive} expression without using the standard -character codes; and it shows how to create a temporary buffer. - -(The @code{indent-to} function is written in C rather than Emacs Lisp; -it is a `built-in' function. @code{help-follow} takes you to its -source as does @code{find-tag}, when properly set up.) - -You can look at a function's source using @code{find-tag}, which is -bound to @kbd{M-.} Finally, you can find out what the Reference -Manual has to say by visiting the manual in Info, and typing @kbd{i} -(@code{Info-index}) and the name of the function, or by looking up the -function in the index to a printed copy of the manual. - -Similarly, you can find out what is meant by -@code{insert-and-inherit}. - -Other interesting source files include @file{paragraphs.el}, -@file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el} -file includes short, easily understood functions as well as longer -ones. The @file{loaddefs.el} file contains the many standard -autoloads and many keymaps. I have never looked at it all; only at -parts. @file{loadup.el} is the file that loads the standard parts of -Emacs; it tells you a great deal about how Emacs is built. -(@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp -Reference Manual}, for more about building.) - -As I said, you have learned some nuts and bolts; however, and very -importantly, we have hardly touched major aspects of programming; I -have said nothing about how to sort information, except to use the -predefined @code{sort} function; I have said nothing about how to store -information, except to use variables and lists; I have said nothing -about how to write programs that write programs. These are topics for -another, and different kind of book, a different kind of learning. - -What you have done is learn enough for much practical work with GNU -Emacs. What you have done is get started. This is the end of a -beginning. - -@c ================ Appendix ================ - -@node the-the, Kill Ring, Conclusion, Top -@appendix The @code{the-the} Function -@findex the-the -@cindex Duplicated words function -@cindex Words, duplicated - -Sometimes when you you write text, you duplicate words---as with ``you -you'' near the beginning of this sentence. I find that most -frequently, I duplicate ``the''; hence, I call the function for -detecting duplicated words, @code{the-the}. - -@need 1250 -As a first step, you could use the following regular expression to -search for duplicates: - -@smallexample -\\(\\w+[ \t\n]+\\)\\1 -@end smallexample - -@noindent -This regexp matches one or more word-constituent characters followed -by one or more spaces, tabs, or newlines. However, it does not detect -duplicated words on different lines, since the ending of the first -word, the end of the line, is different from the ending of the second -word, a space. (For more information about regular expressions, see -@ref{Regexp Search, , Regular Expression Searches}, as well as -@ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs -Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp, -The GNU Emacs Lisp Reference Manual}.) - -You might try searching just for duplicated word-constituent -characters but that does not work since the pattern detects doubles -such as the two occurrences of `th' in `with the'. - -Another possible regexp searches for word-constituent characters -followed by non-word-constituent characters, reduplicated. Here, -@w{@samp{\\w+}} matches one or more word-constituent characters and -@w{@samp{\\W*}} matches zero or more non-word-constituent characters. - -@smallexample -\\(\\(\\w+\\)\\W*\\)\\1 -@end smallexample - -@noindent -Again, not useful. - -Here is the pattern that I use. It is not perfect, but good enough. -@w{@samp{\\b}} matches the empty string, provided it is at the beginning -or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of -any characters that are @emph{not} an @@-sign, space, newline, or tab. - -@smallexample -\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b -@end smallexample - -One can write more complicated expressions, but I found that this -expression is good enough, so I use it. - -Here is the @code{the-the} function, as I include it in my -@file{.emacs} file, along with a handy global key binding: - -@smallexample -@group -(defun the-the () - "Search forward for for a duplicated word." - (interactive) - (message "Searching for for duplicated words ...") - (push-mark) -@end group -@group - ;; This regexp is not perfect - ;; but is fairly good over all: - (if (re-search-forward - "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move) - (message "Found duplicated word.") - (message "End of buffer"))) -@end group - -@group -;; Bind `the-the' to C-c \ -(global-set-key "\C-c\\" 'the-the) -@end group -@end smallexample - -@sp 1 -Here is test text: - -@smallexample -@group -one two two three four five -five six seven -@end group -@end smallexample - -You can substitute the other regular expressions shown above in the -function definition and try each of them on this list. - -@node Kill Ring, Full Graph, the-the, Top -@appendix Handling the Kill Ring -@cindex Kill ring handling -@cindex Handling the kill ring -@cindex Ring, making a list like a - -The kill ring is a list that is transformed into a ring by the -workings of the @code{current-kill} function. The @code{yank} and -@code{yank-pop} commands use the @code{current-kill} function. - -This appendix describes the @code{current-kill} function as well as -both the @code{yank} and the @code{yank-pop} commands, but first, -consider the workings of the kill ring. - -@menu -* What the Kill Ring Does:: -* current-kill:: -* yank:: Paste a copy of a clipped element. -* yank-pop:: Insert element pointed to. -* ring file:: -@end menu - -@node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring -@ifnottex -@unnumberedsec What the Kill Ring Does -@end ifnottex - -@need 1250 -The kill ring has a default maximum length of sixty items; this number -is too large for an explanation. Instead, set it to four. Please -evaluate the following: - -@smallexample -@group -(setq old-kill-ring-max kill-ring-max) -(setq kill-ring-max 4) -@end group -@end smallexample - -@noindent -Then, please copy each line of the following indented example into the -kill ring. You may kill each line with @kbd{C-k} or mark it and copy -it with @kbd{M-w}. - -@noindent -(In a read-only buffer, such as the @file{*info*} buffer, the kill -command, @kbd{C-k} (@code{kill-line}), will not remove the text, -merely copy it to the kill ring. However, your machine may beep at -you. Alternatively, for silence, you may copy the region of each line -with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark -each line for this command to succeed, but it does not matter at which -end you put point or mark.) - -@need 1250 -@noindent -Please invoke the calls in order, so that five elements attempt to -fill the kill ring: - -@smallexample -@group -first some text -second piece of text -third line -fourth line of text -fifth bit of text -@end group -@end smallexample - -@need 1250 -@noindent -Then find the value of @code{kill-ring} by evaluating - -@smallexample -kill-ring -@end smallexample - -@need 800 -@noindent -It is: - -@smallexample -@group -("fifth bit of text" "fourth line of text" -"third line" "second piece of text") -@end group -@end smallexample - -@noindent -The first element, @samp{first some text}, was dropped. - -@need 1250 -To return to the old value for the length of the kill ring, evaluate: - -@smallexample -(setq kill-ring-max old-kill-ring-max) -@end smallexample - -@node current-kill, yank, What the Kill Ring Does, Kill Ring -@comment node-name, next, previous, up -@appendixsec The @code{current-kill} Function -@findex current-kill - -The @code{current-kill} function changes the element in the kill ring -to which @code{kill-ring-yank-pointer} points. (Also, the -@code{kill-new} function sets @code{kill-ring-yank-pointer} to point -to the latest element of the kill ring. The @code{kill-new} -function is used directly or indirectly by @code{kill-append}, -@code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line}, -and @code{kill-region}.) - -@menu -* Code for current-kill:: -* Understanding current-kill:: -@end menu - -@node Code for current-kill, Understanding current-kill, current-kill, current-kill -@ifnottex -@unnumberedsubsec The code for @code{current-kill} -@end ifnottex - - -@need 1500 -The @code{current-kill} function is used by @code{yank} and by -@code{yank-pop}. Here is the code for @code{current-kill}: - -@smallexample -@group -(defun current-kill (n &optional do-not-move) - "Rotate the yanking point by N places, and then return that kill. -If N is zero, `interprogram-paste-function' is set, and calling it -returns a string, then that string is added to the front of the -kill ring and returned as the latest kill. -@end group -@group -If optional arg DO-NOT-MOVE is non-nil, then don't actually move the -yanking point; just return the Nth kill forward." - (let ((interprogram-paste (and (= n 0) - interprogram-paste-function - (funcall interprogram-paste-function)))) -@end group -@group - (if interprogram-paste - (progn - ;; Disable the interprogram cut function when we add the new - ;; text to the kill ring, so Emacs doesn't try to own the - ;; selection, with identical text. - (let ((interprogram-cut-function nil)) - (kill-new interprogram-paste)) - interprogram-paste) -@end group -@group - (or kill-ring (error "Kill ring is empty")) - (let ((ARGth-kill-element - (nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) - (car ARGth-kill-element))))) -@end group -@end smallexample - -Remember also that the @code{kill-new} function sets -@code{kill-ring-yank-pointer} to the latest element of the kill -ring, which means that all the functions that call it set the value -indirectly: @code{kill-append}, @code{copy-region-as-kill}, -@code{kill-ring-save}, @code{kill-line}, and @code{kill-region}. - -@need 1500 -Here is the line in @code{kill-new}, which is explained in -@ref{kill-new function, , The @code{kill-new} function}. - -@smallexample -(setq kill-ring-yank-pointer kill-ring) -@end smallexample - -@node Understanding current-kill, , Code for current-kill, current-kill -@ifnottex -@unnumberedsubsec @code{current-kill} in Outline -@end ifnottex - -The @code{current-kill} function looks complex, but as usual, it can -be understood by taking it apart piece by piece. First look at it in -skeletal form: - -@smallexample -@group -(defun current-kill (n &optional do-not-move) - "Rotate the yanking point by N places, and then return that kill." - (let @var{varlist} - @var{body}@dots{}) -@end group -@end smallexample - -This function takes two arguments, one of which is optional. It has a -documentation string. It is @emph{not} interactive. - -@menu -* Body of current-kill:: -* Digression concerning error:: How to mislead humans, but not computers. -* Determining the Element:: -@end menu - -@node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill -@ifnottex -@unnumberedsubsubsec The Body of @code{current-kill} -@end ifnottex - -The body of the function definition is a @code{let} expression, which -itself has a body as well as a @var{varlist}. - -The @code{let} expression declares a variable that will be only usable -within the bounds of this function. This variable is called -@code{interprogram-paste} and is for copying to another program. It -is not for copying within this instance of GNU Emacs. Most window -systems provide a facility for interprogram pasting. Sadly, that -facility usually provides only for the last element. Most windowing -systems have not adopted a ring of many possibilities, even though -Emacs has provided it for decades. - -The @code{if} expression has two parts, one if there exists -@code{interprogram-paste} and one if not. - -@need 2000 -Let us consider the `if not' or else-part of the @code{current-kill} -function. (The then-part uses the @code{kill-new} function, which -we have already described. @xref{kill-new function, , The -@code{kill-new} function}.) - -@smallexample -@group -(or kill-ring (error "Kill ring is empty")) -(let ((ARGth-kill-element - (nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) - (car ARGth-kill-element)) -@end group -@end smallexample - -@noindent -The code first checks whether the kill ring has content; otherwise it -signals an error. - -@need 1000 -Note that the @code{or} expression is very similar to testing length -with an @code{if}: - -@findex zerop -@findex error -@smallexample -@group -(if (zerop (length kill-ring)) ; @r{if-part} - (error "Kill ring is empty")) ; @r{then-part} - ;; No else-part -@end group -@end smallexample - -@noindent -If there is not anything in the kill ring, its length must be zero and -an error message sent to the user: @samp{Kill ring is empty}. The -@code{current-kill} function uses an @code{or} expression which is -simpler. But an @code{if} expression reminds us what goes on. - -This @code{if} expression uses the function @code{zerop} which returns -true if the value it is testing is zero. When @code{zerop} tests -true, the then-part of the @code{if} is evaluated. The then-part is a -list starting with the function @code{error}, which is a function that -is similar to the @code{message} function -(@pxref{message, , The @code{message} Function}) in that -it prints a one-line message in the echo area. However, in addition -to printing a message, @code{error} also stops evaluation of the -function within which it is embedded. This means that the rest of the -function will not be evaluated if the length of the kill ring is zero. - -Then the @code{current-kill} function selects the element to return. -The selection depends on the number of places that @code{current-kill} -rotates and on where @code{kill-ring-yank-pointer} points. - -Next, either the optional @code{do-not-move} argument is true or the -current value of @code{kill-ring-yank-pointer} is set to point to the -list. Finally, another expression returns the first element of the -list even if the @code{do-not-move} argument is true. - -@node Digression concerning error, Determining the Element, Body of current-kill, Understanding current-kill -@ifnottex -@unnumberedsubsubsec Digression about the word `error' -@end ifnottex - -In my opinion, it is slightly misleading, at least to humans, to use -the term `error' as the name of the @code{error} function. A better -term would be `cancel'. Strictly speaking, of course, you cannot -point to, much less rotate a pointer to a list that has no length, so -from the point of view of the computer, the word `error' is correct. -But a human expects to attempt this sort of thing, if only to find out -whether the kill ring is full or empty. This is an act of -exploration. - -From the human point of view, the act of exploration and discovery is -not necessarily an error, and therefore should not be labeled as one, -even in the bowels of a computer. As it is, the code in Emacs implies -that a human who is acting virtuously, by exploring his or her -environment, is making an error. This is bad. Even though the computer -takes the same steps as it does when there is an `error', a term such as -`cancel' would have a clearer connotation. - -@node Determining the Element, , Digression concerning error, Understanding current-kill -@ifnottex -@unnumberedsubsubsec Determining the Element -@end ifnottex - -Among other actions, the else-part of the @code{if} expression sets -the value of @code{kill-ring-yank-pointer} to -@code{ARGth-kill-element} when the kill ring has something in it and -the value of @code{do-not-move} is @code{nil}. - -@need 800 -The code looks like this: - -@smallexample -@group -(nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) -@end group -@end smallexample - -This needs some examination. Unless it is not supposed to move the -pointer, the @code{current-kill} function changes where -@code{kill-ring-yank-pointer} points. -That is what the -@w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}} -expression does. Also, clearly, @code{ARGth-kill-element} is being -set to be equal to some @sc{cdr} of the kill ring, using the -@code{nthcdr} function that is described in an earlier section. -(@xref{copy-region-as-kill}.) How does it do this? - -As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function -works by repeatedly taking the @sc{cdr} of a list---it takes the -@sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{} - -@need 800 -The two following expressions produce the same result: - -@smallexample -@group -(setq kill-ring-yank-pointer (cdr kill-ring)) - -(setq kill-ring-yank-pointer (nthcdr 1 kill-ring)) -@end group -@end smallexample - -However, the @code{nthcdr} expression is more complicated. It uses -the @code{mod} function to determine which @sc{cdr} to select. - -(You will remember to look at inner functions first; indeed, we will -have to go inside the @code{mod}.) - -The @code{mod} function returns the value of its first argument modulo -the second; that is to say, it returns the remainder after dividing -the first argument by the second. The value returned has the same -sign as the second argument. - -@need 800 -Thus, - -@smallexample -@group -(mod 12 4) - @result{} 0 ;; @r{because there is no remainder} -(mod 13 4) - @result{} 1 -@end group -@end smallexample - -@need 1250 -In this case, the first argument is often smaller than the second. -That is fine. - -@smallexample -@group -(mod 0 4) - @result{} 0 -(mod 1 4) - @result{} 1 -@end group -@end smallexample - -We can guess what the @code{-} function does. It is like @code{+} but -subtracts instead of adds; the @code{-} function subtracts its second -argument from its first. Also, we already know what the @code{length} -function does (@pxref{length}). It returns the length of a list. - -And @code{n} is the name of the required argument to the -@code{current-kill} function. - -@need 1250 -So when the first argument to @code{nthcdr} is zero, the @code{nthcdr} -expression returns the whole list, as you can see by evaluating the -following: - -@smallexample -@group -;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four} -;; @r{and} (mod (- 0 4) 4) @result{} 0 -(nthcdr (mod (- 0 4) 4) - '("fourth line of text" - "third line" - "second piece of text" - "first some text")) -@end group -@end smallexample - -@need 1250 -When the first argument to the @code{current-kill} function is one, -the @code{nthcdr} expression returns the list without its first -element. - -@smallexample -@group -(nthcdr (mod (- 1 4) 4) - '("fourth line of text" - "third line" - "second piece of text" - "first some text")) -@end group -@end smallexample - -@cindex @samp{global variable} defined -@cindex @samp{variable, global}, defined -Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer} -are @dfn{global variables}. That means that any expression in Emacs -Lisp can access them. They are not like the local variables set by -@code{let} or like the symbols in an argument list. -Local variables can only be accessed -within the @code{let} that defines them or the function that specifies -them in an argument list (and within expressions called by them). - -@ignore -@c texi2dvi fails when the name of the section is within ifnottex ... -(@xref{Prevent confusion, , @code{let} Prevents Confusion}, and -@ref{defun, , The @code{defun} Special Form}.) -@end ignore - -@node yank, yank-pop, current-kill, Kill Ring -@comment node-name, next, previous, up -@appendixsec @code{yank} -@findex yank - -After learning about @code{current-kill}, the code for the -@code{yank} function is almost easy. - -The @code{yank} function does not use the -@code{kill-ring-yank-pointer} variable directly. It calls -@code{insert-for-yank} which calls @code{current-kill} which sets the -@code{kill-ring-yank-pointer} variable. - -@need 1250 -The code looks like this: - -@c in GNU Emacs 22 -@smallexample -@group -(defun yank (&optional arg) - "Reinsert (\"paste\") the last stretch of killed text. -More precisely, reinsert the stretch of killed text most recently -killed OR yanked. Put point at end, and set mark at beginning. -With just \\[universal-argument] as argument, same but put point at -beginning (and mark at end). With argument N, reinsert the Nth most -recently killed stretch of killed text. - -When this command inserts killed text into the buffer, it honors -`yank-excluded-properties' and `yank-handler' as described in the -doc string for `insert-for-yank-1', which see. - -See also the command \\[yank-pop]." -@end group -@group - (interactive "*P") - (setq yank-window-start (window-start)) - ;; If we don't get all the way thru, make last-command indicate that - ;; for the following command. - (setq this-command t) - (push-mark (point)) -@end group -@group - (insert-for-yank (current-kill (cond - ((listp arg) 0) - ((eq arg '-) -2) - (t (1- arg))))) - (if (consp arg) - ;; This is like exchange-point-and-mark, - ;; but doesn't activate the mark. - ;; It is cleaner to avoid activation, even though the command - ;; loop would deactivate the mark because we inserted text. - (goto-char (prog1 (mark t) - (set-marker (mark-marker) (point) (current-buffer))))) -@end group -@group - ;; If we do get all the way thru, make this-command indicate that. - (if (eq this-command t) - (setq this-command 'yank)) - nil) -@end group -@end smallexample - -The key expression is @code{insert-for-yank}, which inserts the string -returned by @code{current-kill}, but removes some text properties from -it. - -However, before getting to that expression, the function sets the value -of @code{yank-window-start} to the position returned by the -@code{(window-start)} expression, the position at which the display -currently starts. The @code{yank} function also sets -@code{this-command} and pushes the mark. - -After it yanks the appropriate element, if the optional argument is a -@sc{cons} rather than a number or nothing, it puts point at beginning -of the yanked text and mark at its end. - -(The @code{prog1} function is like @code{progn} but returns the value -of its first argument rather than the value of its last argument. Its -first argument is forced to return the buffer's mark as an integer. -You can see the documentation for these functions by placing point -over them in this buffer and then typing @kbd{C-h f} -(@code{describe-function}) followed by a @kbd{RET}; the default is the -function.) - -The last part of the function tells what to do when it succeeds. - -@node yank-pop, ring file, yank, Kill Ring -@comment node-name, next, previous, up -@appendixsec @code{yank-pop} -@findex yank-pop - -After understanding @code{yank} and @code{current-kill}, you know how -to approach the @code{yank-pop} function. Leaving out the -documentation to save space, it looks like this: - -@c GNU Emacs 22 -@smallexample -@group -(defun yank-pop (&optional arg) - "@dots{}" - (interactive "*p") - (if (not (eq last-command 'yank)) - (error "Previous command was not a yank")) -@end group -@group - (setq this-command 'yank) - (unless arg (setq arg 1)) - (let ((inhibit-read-only t) - (before (< (point) (mark t)))) -@end group -@group - (if before - (funcall (or yank-undo-function 'delete-region) (point) (mark t)) - (funcall (or yank-undo-function 'delete-region) (mark t) (point))) - (setq yank-undo-function nil) -@end group -@group - (set-marker (mark-marker) (point) (current-buffer)) - (insert-for-yank (current-kill arg)) - ;; Set the window start back where it was in the yank command, - ;; if possible. - (set-window-start (selected-window) yank-window-start t) -@end group -@group - (if before - ;; This is like exchange-point-and-mark, - ;; but doesn't activate the mark. - ;; It is cleaner to avoid activation, even though the command - ;; loop would deactivate the mark because we inserted text. - (goto-char (prog1 (mark t) - (set-marker (mark-marker) - (point) - (current-buffer)))))) - nil) -@end group -@end smallexample - -The function is interactive with a small @samp{p} so the prefix -argument is processed and passed to the function. The command can -only be used after a previous yank; otherwise an error message is -sent. This check uses the variable @code{last-command} which is set -by @code{yank} and is discussed elsewhere. -(@xref{copy-region-as-kill}.) - -The @code{let} clause sets the variable @code{before} to true or false -depending whether point is before or after mark and then the region -between point and mark is deleted. This is the region that was just -inserted by the previous yank and it is this text that will be -replaced. - -@code{funcall} calls its first argument as a function, passing -remaining arguments to it. The first argument is whatever the -@code{or} expression returns. The two remaining arguments are the -positions of point and mark set by the preceding @code{yank} command. - -There is more, but that is the hardest part. - -@node ring file, , yank-pop, Kill Ring -@comment node-name, next, previous, up -@appendixsec The @file{ring.el} File -@cindex @file{ring.el} file - -Interestingly, GNU Emacs posses a file called @file{ring.el} that -provides many of the features we just discussed. But functions such -as @code{kill-ring-yank-pointer} do not use this library, possibly -because they were written earlier. - -@node Full Graph, Free Software and Free Manuals, Kill Ring, Top -@appendix A Graph with Labeled Axes - -Printed axes help you understand a graph. They convey scale. In an -earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we -wrote the code to print the body of a graph. Here we write the code -for printing and labeling vertical and horizontal axes, along with the -body itself. - -@menu -* Labeled Example:: -* print-graph Varlist:: @code{let} expression in @code{print-graph}. -* print-Y-axis:: Print a label for the vertical axis. -* print-X-axis:: Print a horizontal label. -* Print Whole Graph:: The function to print a complete graph. -@end menu - -@node Labeled Example, print-graph Varlist, Full Graph, Full Graph -@ifnottex -@unnumberedsec Labeled Example Graph -@end ifnottex - -Since insertions fill a buffer to the right and below point, the new -graph printing function should first print the Y or vertical axis, -then the body of the graph, and finally the X or horizontal axis. -This sequence lays out for us the contents of the function: - -@enumerate -@item -Set up code. - -@item -Print Y axis. - -@item -Print body of graph. - -@item -Print X axis. -@end enumerate - -@need 800 -Here is an example of how a finished graph should look: - -@smallexample -@group - 10 - - * - * * - * ** - * *** - 5 - * ******* - * *** ******* - ************* - *************** - 1 - **************** - | | | | - 1 5 10 15 -@end group -@end smallexample - -@noindent -In this graph, both the vertical and the horizontal axes are labeled -with numbers. However, in some graphs, the horizontal axis is time -and would be better labeled with months, like this: - -@smallexample -@group - 5 - * - * ** * - ******* - ********** ** - 1 - ************** - | ^ | - Jan June Jan -@end group -@end smallexample - -Indeed, with a little thought, we can easily come up with a variety of -vertical and horizontal labeling schemes. Our task could become -complicated. But complications breed confusion. Rather than permit -this, it is better choose a simple labeling scheme for our first -effort, and to modify or replace it later. - -@need 1200 -These considerations suggest the following outline for the -@code{print-graph} function: - -@smallexample -@group -(defun print-graph (numbers-list) - "@var{documentation}@dots{}" - (let ((height @dots{} - @dots{})) -@end group -@group - (print-Y-axis height @dots{} ) - (graph-body-print numbers-list) - (print-X-axis @dots{} ))) -@end group -@end smallexample - -We can work on each part of the @code{print-graph} function definition -in turn. - -@node print-graph Varlist, print-Y-axis, Labeled Example, Full Graph -@comment node-name, next, previous, up -@appendixsec The @code{print-graph} Varlist -@cindex @code{print-graph} varlist - -In writing the @code{print-graph} function, the first task is to write -the varlist in the @code{let} expression. (We will leave aside for the -moment any thoughts about making the function interactive or about the -contents of its documentation string.) - -The varlist should set several values. Clearly, the top of the label -for the vertical axis must be at least the height of the graph, which -means that we must obtain this information here. Note that the -@code{print-graph-body} function also requires this information. There -is no reason to calculate the height of the graph in two different -places, so we should change @code{print-graph-body} from the way we -defined it earlier to take advantage of the calculation. - -Similarly, both the function for printing the X axis labels and the -@code{print-graph-body} function need to learn the value of the width of -each symbol. We can perform the calculation here and change the -definition for @code{print-graph-body} from the way we defined it in the -previous chapter. - -The length of the label for the horizontal axis must be at least as long -as the graph. However, this information is used only in the function -that prints the horizontal axis, so it does not need to be calculated here. - -These thoughts lead us directly to the following form for the varlist -in the @code{let} for @code{print-graph}: - -@smallexample -@group -(let ((height (apply 'max numbers-list)) ; @r{First version.} - (symbol-width (length graph-blank))) -@end group -@end smallexample - -@noindent -As we shall see, this expression is not quite right. - -@need 2000 -@node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph -@comment node-name, next, previous, up -@appendixsec The @code{print-Y-axis} Function -@cindex Axis, print vertical -@cindex Y axis printing -@cindex Vertical axis printing -@cindex Print vertical axis - -The job of the @code{print-Y-axis} function is to print a label for -the vertical axis that looks like this: - -@smallexample -@group - 10 - - - - - - 5 - - - - - 1 - -@end group -@end smallexample - -@noindent -The function should be passed the height of the graph, and then should -construct and insert the appropriate numbers and marks. - -@menu -* print-Y-axis in Detail:: -* Height of label:: What height for the Y axis? -* Compute a Remainder:: How to compute the remainder of a division. -* Y Axis Element:: Construct a line for the Y axis. -* Y-axis-column:: Generate a list of Y axis labels. -* print-Y-axis Penultimate:: A not quite final version. -@end menu - -@node print-Y-axis in Detail, Height of label, print-Y-axis, print-Y-axis -@ifnottex -@unnumberedsubsec The @code{print-Y-axis} Function in Detail -@end ifnottex - -It is easy enough to see in the figure what the Y axis label should -look like; but to say in words, and then to write a function -definition to do the job is another matter. It is not quite true to -say that we want a number and a tic every five lines: there are only -three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4), -but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8, -and 9). It is better to say that we want a number and a tic mark on -the base line (number 1) and then that we want a number and a tic on -the fifth line from the bottom and on every line that is a multiple of -five. - -@node Height of label, Compute a Remainder, print-Y-axis in Detail, print-Y-axis -@ifnottex -@unnumberedsubsec What height should the label be? -@end ifnottex - -The next issue is what height the label should be? Suppose the maximum -height of tallest column of the graph is seven. Should the highest -label on the Y axis be @samp{5 -}, and should the graph stick up above -the label? Or should the highest label be @samp{7 -}, and mark the peak -of the graph? Or should the highest label be @code{10 -}, which is a -multiple of five, and be higher than the topmost value of the graph? - -The latter form is preferred. Most graphs are drawn within rectangles -whose sides are an integral number of steps long---5, 10, 15, and so -on for a step distance of five. But as soon as we decide to use a -step height for the vertical axis, we discover that the simple -expression in the varlist for computing the height is wrong. The -expression is @code{(apply 'max numbers-list)}. This returns the -precise height, not the maximum height plus whatever is necessary to -round up to the nearest multiple of five. A more complex expression -is required. - -As usual in cases like this, a complex problem becomes simpler if it is -divided into several smaller problems. - -First, consider the case when the highest value of the graph is an -integral multiple of five---when it is 5, 10, 15, or some higher -multiple of five. We can use this value as the Y axis height. - -A fairly simply way to determine whether a number is a multiple of -five is to divide it by five and see if the division results in a -remainder. If there is no remainder, the number is a multiple of -five. Thus, seven divided by five has a remainder of two, and seven -is not an integral multiple of five. Put in slightly different -language, more reminiscent of the classroom, five goes into seven -once, with a remainder of two. However, five goes into ten twice, -with no remainder: ten is an integral multiple of five. - -@node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis -@appendixsubsec Side Trip: Compute a Remainder - -@findex % @r{(remainder function)} -@cindex Remainder function, @code{%} -In Lisp, the function for computing a remainder is @code{%}. The -function returns the remainder of its first argument divided by its -second argument. As it happens, @code{%} is a function in Emacs Lisp -that you cannot discover using @code{apropos}: you find nothing if you -type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to -learn of the existence of @code{%} is to read about it in a book such -as this or in the Emacs Lisp sources. - -You can try the @code{%} function by evaluating the following two -expressions: - -@smallexample -@group -(% 7 5) - -(% 10 5) -@end group -@end smallexample - -@noindent -The first expression returns 2 and the second expression returns 0. - -To test whether the returned value is zero or some other number, we -can use the @code{zerop} function. This function returns @code{t} if -its argument, which must be a number, is zero. - -@smallexample -@group -(zerop (% 7 5)) - @result{} nil - -(zerop (% 10 5)) - @result{} t -@end group -@end smallexample - -Thus, the following expression will return @code{t} if the height -of the graph is evenly divisible by five: - -@smallexample -(zerop (% height 5)) -@end smallexample - -@noindent -(The value of @code{height}, of course, can be found from @code{(apply -'max numbers-list)}.) - -On the other hand, if the value of @code{height} is not a multiple of -five, we want to reset the value to the next higher multiple of five. -This is straightforward arithmetic using functions with which we are -already familiar. First, we divide the value of @code{height} by five -to determine how many times five goes into the number. Thus, five -goes into twelve twice. If we add one to this quotient and multiply by -five, we will obtain the value of the next multiple of five that is -larger than the height. Five goes into twelve twice. Add one to two, -and multiply by five; the result is fifteen, which is the next multiple -of five that is higher than twelve. The Lisp expression for this is: - -@smallexample -(* (1+ (/ height 5)) 5) -@end smallexample - -@noindent -For example, if you evaluate the following, the result is 15: - -@smallexample -(* (1+ (/ 12 5)) 5) -@end smallexample - -All through this discussion, we have been using `five' as the value -for spacing labels on the Y axis; but we may want to use some other -value. For generality, we should replace `five' with a variable to -which we can assign a value. The best name I can think of for this -variable is @code{Y-axis-label-spacing}. - -@need 1250 -Using this term, and an @code{if} expression, we produce the -following: - -@smallexample -@group -(if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing)) -@end group -@end smallexample - -@noindent -This expression returns the value of @code{height} itself if the height -is an even multiple of the value of the @code{Y-axis-label-spacing} or -else it computes and returns a value of @code{height} that is equal to -the next higher multiple of the value of the @code{Y-axis-label-spacing}. - -We can now include this expression in the @code{let} expression of the -@code{print-graph} function (after first setting the value of -@code{Y-axis-label-spacing}): -@vindex Y-axis-label-spacing - -@smallexample -@group -(defvar Y-axis-label-spacing 5 - "Number of lines from one Y axis label to next.") -@end group - -@group -@dots{} -(let* ((height (apply 'max numbers-list)) - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height -@end group -@group - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) - (symbol-width (length graph-blank)))) -@dots{} -@end group -@end smallexample - -@noindent -(Note use of the @code{let*} function: the initial value of height is -computed once by the @code{(apply 'max numbers-list)} expression and -then the resulting value of @code{height} is used to compute its -final value. @xref{fwd-para let, , The @code{let*} expression}, for -more about @code{let*}.) - -@node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis -@appendixsubsec Construct a Y Axis Element - -When we print the vertical axis, we want to insert strings such as -@w{@samp{5 -}} and @w{@samp{10 - }} every five lines. -Moreover, we want the numbers and dashes to line up, so shorter -numbers must be padded with leading spaces. If some of the strings -use two digit numbers, the strings with single digit numbers must -include a leading blank space before the number. - -@findex number-to-string -To figure out the length of the number, the @code{length} function is -used. But the @code{length} function works only with a string, not with -a number. So the number has to be converted from being a number to -being a string. This is done with the @code{number-to-string} function. -For example, - -@smallexample -@group -(length (number-to-string 35)) - @result{} 2 - -(length (number-to-string 100)) - @result{} 3 -@end group -@end smallexample - -@noindent -(@code{number-to-string} is also called @code{int-to-string}; you will -see this alternative name in various sources.) - -In addition, in each label, each number is followed by a string such -as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker. -This variable is defined with @code{defvar}: - -@vindex Y-axis-tic -@smallexample -@group -(defvar Y-axis-tic " - " - "String that follows number in a Y axis label.") -@end group -@end smallexample - -The length of the Y label is the sum of the length of the Y axis tic -mark and the length of the number of the top of the graph. - -@smallexample -(length (concat (number-to-string height) Y-axis-tic))) -@end smallexample - -This value will be calculated by the @code{print-graph} function in -its varlist as @code{full-Y-label-width} and passed on. (Note that we -did not think to include this in the varlist when we first proposed it.) - -To make a complete vertical axis label, a tic mark is concatenated -with a number; and the two together may be preceded by one or more -spaces depending on how long the number is. The label consists of -three parts: the (optional) leading spaces, the number, and the tic -mark. The function is passed the value of the number for the specific -row, and the value of the width of the top line, which is calculated -(just once) by @code{print-graph}. - -@smallexample -@group -(defun Y-axis-element (number full-Y-label-width) - "Construct a NUMBERed label element. -A numbered element looks like this ` 5 - ', -and is padded as needed so all line up with -the element for the largest number." -@end group -@group - (let* ((leading-spaces - (- full-Y-label-width - (length - (concat (number-to-string number) - Y-axis-tic))))) -@end group -@group - (concat - (make-string leading-spaces ? ) - (number-to-string number) - Y-axis-tic))) -@end group -@end smallexample - -The @code{Y-axis-element} function concatenates together the leading -spaces, if any; the number, as a string; and the tic mark. - -To figure out how many leading spaces the label will need, the -function subtracts the actual length of the label---the length of the -number plus the length of the tic mark---from the desired label width. - -@findex make-string -Blank spaces are inserted using the @code{make-string} function. This -function takes two arguments: the first tells it how long the string -will be and the second is a symbol for the character to insert, in a -special format. The format is a question mark followed by a blank -space, like this, @samp{? }. @xref{Character Type, , Character Type, -elisp, The GNU Emacs Lisp Reference Manual}, for a description of the -syntax for characters. (Of course, you might want to replace the -blank space by some other character @dots{} You know what to do.) - -The @code{number-to-string} function is used in the concatenation -expression, to convert the number to a string that is concatenated -with the leading spaces and the tic mark. - -@node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis -@appendixsubsec Create a Y Axis Column - -The preceding functions provide all the tools needed to construct a -function that generates a list of numbered and blank strings to insert -as the label for the vertical axis: - -@findex Y-axis-column -@smallexample -@group -(defun Y-axis-column (height width-of-label) - "Construct list of Y axis labels and blank strings. -For HEIGHT of line above base and WIDTH-OF-LABEL." - (let (Y-axis) -@group -@end group - (while (> height 1) - (if (zerop (% height Y-axis-label-spacing)) - ;; @r{Insert label.} - (setq Y-axis - (cons - (Y-axis-element height width-of-label) - Y-axis)) -@group -@end group - ;; @r{Else, insert blanks.} - (setq Y-axis - (cons - (make-string width-of-label ? ) - Y-axis))) - (setq height (1- height))) - ;; @r{Insert base line.} - (setq Y-axis - (cons (Y-axis-element 1 width-of-label) Y-axis)) - (nreverse Y-axis))) -@end group -@end smallexample - -In this function, we start with the value of @code{height} and -repetitively subtract one from its value. After each subtraction, we -test to see whether the value is an integral multiple of the -@code{Y-axis-label-spacing}. If it is, we construct a numbered label -using the @code{Y-axis-element} function; if not, we construct a -blank label using the @code{make-string} function. The base line -consists of the number one followed by a tic mark. - -@need 2000 -@node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis -@appendixsubsec The Not Quite Final Version of @code{print-Y-axis} - -The list constructed by the @code{Y-axis-column} function is passed to -the @code{print-Y-axis} function, which inserts the list as a column. - -@findex print-Y-axis -@smallexample -@group -(defun print-Y-axis (height full-Y-label-width) - "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH. -Height must be the maximum height of the graph. -Full width is the width of the highest label element." -;; Value of height and full-Y-label-width -;; are passed by `print-graph'. -@end group -@group - (let ((start (point))) - (insert-rectangle - (Y-axis-column height full-Y-label-width)) - ;; @r{Place point ready for inserting graph.} - (goto-char start) - ;; @r{Move point forward by value of} full-Y-label-width - (forward-char full-Y-label-width))) -@end group -@end smallexample - -The @code{print-Y-axis} uses the @code{insert-rectangle} function to -insert the Y axis labels created by the @code{Y-axis-column} function. -In addition, it places point at the correct position for printing the body of -the graph. - -You can test @code{print-Y-axis}: - -@enumerate -@item -Install - -@smallexample -@group -Y-axis-label-spacing -Y-axis-tic -Y-axis-element -Y-axis-column -print-Y-axis -@end group -@end smallexample - -@item -Copy the following expression: - -@smallexample -(print-Y-axis 12 5) -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the axis labels to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the @code{graph-body-print} expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the expression. -@end enumerate - -Emacs will print labels vertically, the top one being @w{@samp{10 -@w{ -}}}. (The @code{print-graph} function will pass the value of -@code{height-of-top-line}, which in this case will end up as 15, -thereby getting rid of what might appear as a bug.) - -@need 2000 -@node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph -@appendixsec The @code{print-X-axis} Function -@cindex Axis, print horizontal -@cindex X axis printing -@cindex Print horizontal axis -@cindex Horizontal axis printing - -X axis labels are much like Y axis labels, except that the ticks are on a -line above the numbers. Labels should look like this: - -@smallexample -@group - | | | | - 1 5 10 15 -@end group -@end smallexample - -The first tic is under the first column of the graph and is preceded by -several blank spaces. These spaces provide room in rows above for the Y -axis labels. The second, third, fourth, and subsequent ticks are all -spaced equally, according to the value of @code{X-axis-label-spacing}. - -The second row of the X axis consists of numbers, preceded by several -blank spaces and also separated according to the value of the variable -@code{X-axis-label-spacing}. - -The value of the variable @code{X-axis-label-spacing} should itself be -measured in units of @code{symbol-width}, since you may want to change -the width of the symbols that you are using to print the body of the -graph without changing the ways the graph is labeled. - -@menu -* Similarities differences:: Much like @code{print-Y-axis}, but not exactly. -* X Axis Tic Marks:: Create tic marks for the horizontal axis. -@end menu - -@node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis -@ifnottex -@unnumberedsubsec Similarities and differences -@end ifnottex - -The @code{print-X-axis} function is constructed in more or less the -same fashion as the @code{print-Y-axis} function except that it has -two lines: the line of tic marks and the numbers. We will write a -separate function to print each line and then combine them within the -@code{print-X-axis} function. - -This is a three step process: - -@enumerate -@item -Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}. - -@item -Write a function to print the X numbers, @code{print-X-axis-numbered-line}. - -@item -Write a function to print both lines, the @code{print-X-axis} function, -using @code{print-X-axis-tic-line} and -@code{print-X-axis-numbered-line}. -@end enumerate - -@node X Axis Tic Marks, , Similarities differences, print-X-axis -@appendixsubsec X Axis Tic Marks - -The first function should print the X axis tic marks. We must specify -the tic marks themselves and their spacing: - -@smallexample -@group -(defvar X-axis-label-spacing - (if (boundp 'graph-blank) - (* 5 (length graph-blank)) 5) - "Number of units from one X axis label to next.") -@end group -@end smallexample - -@noindent -(Note that the value of @code{graph-blank} is set by another -@code{defvar}. The @code{boundp} predicate checks whether it has -already been set; @code{boundp} returns @code{nil} if it has not. If -@code{graph-blank} were unbound and we did not use this conditional -construction, in a recent GNU Emacs, we would enter the debugger and -see an error message saying @samp{@w{Debugger entered--Lisp error:} -@w{(void-variable graph-blank)}}.) - -@need 1200 -Here is the @code{defvar} for @code{X-axis-tic-symbol}: - -@smallexample -@group -(defvar X-axis-tic-symbol "|" - "String to insert to point to a column in X axis.") -@end group -@end smallexample - -@need 1250 -The goal is to make a line that looks like this: - -@smallexample - | | | | -@end smallexample - -The first tic is indented so that it is under the first column, which is -indented to provide space for the Y axis labels. - -A tic element consists of the blank spaces that stretch from one tic to -the next plus a tic symbol. The number of blanks is determined by the -width of the tic symbol and the @code{X-axis-label-spacing}. - -@need 1250 -The code looks like this: - -@smallexample -@group -;;; X-axis-tic-element -@dots{} -(concat - (make-string - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol) -@dots{} -@end group -@end smallexample - -Next, we determine how many blanks are needed to indent the first tic -mark to the first column of the graph. This uses the value of -@code{full-Y-label-width} passed it by the @code{print-graph} function. - -@need 1250 -The code to make @code{X-axis-leading-spaces} -looks like this: - -@smallexample -@group -;; X-axis-leading-spaces -@dots{} -(make-string full-Y-label-width ? ) -@dots{} -@end group -@end smallexample - -We also need to determine the length of the horizontal axis, which is -the length of the numbers list, and the number of ticks in the horizontal -axis: - -@smallexample -@group -;; X-length -@dots{} -(length numbers-list) -@end group - -@group -;; tic-width -@dots{} -(* symbol-width X-axis-label-spacing) -@end group - -@group -;; number-of-X-ticks -(if (zerop (% (X-length tic-width))) - (/ (X-length tic-width)) - (1+ (/ (X-length tic-width)))) -@end group -@end smallexample - -@need 1250 -All this leads us directly to the function for printing the X axis tic line: - -@findex print-X-axis-tic-line -@smallexample -@group -(defun print-X-axis-tic-line - (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) - "Print ticks for X axis." - (insert X-axis-leading-spaces) - (insert X-axis-tic-symbol) ; @r{Under first column.} -@end group -@group - ;; @r{Insert second tic in the right spot.} - (insert (concat - (make-string - (- (* symbol-width X-axis-label-spacing) - ;; @r{Insert white space up to second tic symbol.} - (* 2 (length X-axis-tic-symbol))) - ? ) - X-axis-tic-symbol)) -@end group -@group - ;; @r{Insert remaining ticks.} - (while (> number-of-X-tics 1) - (insert X-axis-tic-element) - (setq number-of-X-tics (1- number-of-X-tics)))) -@end group -@end smallexample - -The line of numbers is equally straightforward: - -@need 1250 -First, we create a numbered element with blank spaces before each number: - -@findex X-axis-element -@smallexample -@group -(defun X-axis-element (number) - "Construct a numbered X axis element." - (let ((leading-spaces - (- (* symbol-width X-axis-label-spacing) - (length (number-to-string number))))) - (concat (make-string leading-spaces ? ) - (number-to-string number)))) -@end group -@end smallexample - -Next, we create the function to print the numbered line, starting with -the number ``1'' under the first column: - -@findex print-X-axis-numbered-line -@smallexample -@group -(defun print-X-axis-numbered-line - (number-of-X-tics X-axis-leading-spaces) - "Print line of X-axis numbers" - (let ((number X-axis-label-spacing)) - (insert X-axis-leading-spaces) - (insert "1") -@end group -@group - (insert (concat - (make-string - ;; @r{Insert white space up to next number.} - (- (* symbol-width X-axis-label-spacing) 2) - ? ) - (number-to-string number))) -@end group -@group - ;; @r{Insert remaining numbers.} - (setq number (+ number X-axis-label-spacing)) - (while (> number-of-X-tics 1) - (insert (X-axis-element number)) - (setq number (+ number X-axis-label-spacing)) - (setq number-of-X-tics (1- number-of-X-tics))))) -@end group -@end smallexample - -Finally, we need to write the @code{print-X-axis} that uses -@code{print-X-axis-tic-line} and -@code{print-X-axis-numbered-line}. - -The function must determine the local values of the variables used by both -@code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and -then it must call them. Also, it must print the carriage return that -separates the two lines. - -The function consists of a varlist that specifies five local variables, -and calls to each of the two line printing functions: - -@findex print-X-axis -@smallexample -@group -(defun print-X-axis (numbers-list) - "Print X axis labels to length of NUMBERS-LIST." - (let* ((leading-spaces - (make-string full-Y-label-width ? )) -@end group -@group - ;; symbol-width @r{is provided by} graph-body-print - (tic-width (* symbol-width X-axis-label-spacing)) - (X-length (length numbers-list)) -@end group -@group - (X-tic - (concat - (make-string -@end group -@group - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) -@end group -@group - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol)) -@end group -@group - (tic-number - (if (zerop (% X-length tic-width)) - (/ X-length tic-width) - (1+ (/ X-length tic-width))))) -@end group -@group - (print-X-axis-tic-line tic-number leading-spaces X-tic) - (insert "\n") - (print-X-axis-numbered-line tic-number leading-spaces))) -@end group -@end smallexample - -@need 1250 -You can test @code{print-X-axis}: - -@enumerate -@item -Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing}, -@code{print-X-axis-tic-line}, as well as @code{X-axis-element}, -@code{print-X-axis-numbered-line}, and @code{print-X-axis}. - -@item -Copy the following expression: - -@smallexample -@group -(progn - (let ((full-Y-label-width 5) - (symbol-width 1)) - (print-X-axis - '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16)))) -@end group -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the axis labels to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the test expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the expression. -@end enumerate - -@need 1250 -Emacs will print the horizontal axis like this: -@sp 1 - -@smallexample -@group - | | | | | - 1 5 10 15 20 -@end group -@end smallexample - -@node Print Whole Graph, , print-X-axis, Full Graph -@appendixsec Printing the Whole Graph -@cindex Printing the whole graph -@cindex Whole graph printing -@cindex Graph, printing all - -Now we are nearly ready to print the whole graph. - -The function to print the graph with the proper labels follows the -outline we created earlier (@pxref{Full Graph, , A Graph with Labeled -Axes}), but with additions. - -@need 1250 -Here is the outline: - -@smallexample -@group -(defun print-graph (numbers-list) - "@var{documentation}@dots{}" - (let ((height @dots{} - @dots{})) -@end group -@group - (print-Y-axis height @dots{} ) - (graph-body-print numbers-list) - (print-X-axis @dots{} ))) -@end group -@end smallexample - -@menu -* The final version:: A few changes. -* Test print-graph:: Run a short test. -* Graphing words in defuns:: Executing the final code. -* lambda:: How to write an anonymous function. -* mapcar:: Apply a function to elements of a list. -* Another Bug:: Yet another bug @dots{} most insidious. -* Final printed graph:: The graph itself! -@end menu - -@node The final version, Test print-graph, Print Whole Graph, Print Whole Graph -@ifnottex -@unnumberedsubsec Changes for the Final Version -@end ifnottex - -The final version is different from what we planned in two ways: -first, it contains additional values calculated once in the varlist; -second, it carries an option to specify the labels' increment per row. -This latter feature turns out to be essential; otherwise, a graph may -have more rows than fit on a display or on a sheet of paper. - -@need 1500 -This new feature requires a change to the @code{Y-axis-column} -function, to add @code{vertical-step} to it. The function looks like -this: - -@findex Y-axis-column @r{Final version.} -@smallexample -@group -;;; @r{Final version.} -(defun Y-axis-column - (height width-of-label &optional vertical-step) - "Construct list of labels for Y axis. -HEIGHT is maximum height of graph. -WIDTH-OF-LABEL is maximum width of label. -VERTICAL-STEP, an option, is a positive integer -that specifies how much a Y axis label increments -for each line. For example, a step of 5 means -that each line is five units of the graph." -@end group -@group - (let (Y-axis - (number-per-line (or vertical-step 1))) - (while (> height 1) - (if (zerop (% height Y-axis-label-spacing)) -@end group -@group - ;; @r{Insert label.} - (setq Y-axis - (cons - (Y-axis-element - (* height number-per-line) - width-of-label) - Y-axis)) -@end group -@group - ;; @r{Else, insert blanks.} - (setq Y-axis - (cons - (make-string width-of-label ? ) - Y-axis))) - (setq height (1- height))) -@end group -@group - ;; @r{Insert base line.} - (setq Y-axis (cons (Y-axis-element - (or vertical-step 1) - width-of-label) - Y-axis)) - (nreverse Y-axis))) -@end group -@end smallexample - -The values for the maximum height of graph and the width of a symbol -are computed by @code{print-graph} in its @code{let} expression; so -@code{graph-body-print} must be changed to accept them. - -@findex graph-body-print @r{Final version.} -@smallexample -@group -;;; @r{Final version.} -(defun graph-body-print (numbers-list height symbol-width) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -HEIGHT is maximum height of graph. -SYMBOL-WIDTH is number of each column." -@end group -@group - (let (from-position) - (while numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) - (goto-char from-position) - (forward-char symbol-width) -@end group -@group - ;; @r{Draw graph column by column.} - (sit-for 0) - (setq numbers-list (cdr numbers-list))) - ;; @r{Place point for X axis labels.} - (forward-line height) - (insert "\n"))) -@end group -@end smallexample - -@need 1250 -Finally, the code for the @code{print-graph} function: - -@findex print-graph @r{Final version.} -@smallexample -@group -;;; @r{Final version.} -(defun print-graph - (numbers-list &optional vertical-step) - "Print labeled bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -@end group - -@group -Optionally, VERTICAL-STEP, a positive integer, -specifies how much a Y axis label increments for -each line. For example, a step of 5 means that -each row is five units." -@end group -@group - (let* ((symbol-width (length graph-blank)) - ;; @code{height} @r{is both the largest number} - ;; @r{and the number with the most digits.} - (height (apply 'max numbers-list)) -@end group -@group - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) -@end group -@group - (vertical-step (or vertical-step 1)) - (full-Y-label-width - (length -@end group -@group - (concat - (number-to-string - (* height-of-top-line vertical-step)) - Y-axis-tic)))) -@end group - -@group - (print-Y-axis - height-of-top-line full-Y-label-width vertical-step) -@end group -@group - (graph-body-print - numbers-list height-of-top-line symbol-width) - (print-X-axis numbers-list))) -@end group -@end smallexample - -@node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph -@appendixsubsec Testing @code{print-graph} - -@need 1250 -We can test the @code{print-graph} function with a short list of numbers: - -@enumerate -@item -Install the final versions of @code{Y-axis-column}, -@code{graph-body-print}, and @code{print-graph} (in addition to the -rest of the code.) - -@item -Copy the following expression: - -@smallexample -(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1)) -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the axis labels to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the test expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the expression. -@end enumerate - -@need 1250 -Emacs will print a graph that looks like this: - -@smallexample -@group -10 - - - - * - ** * - 5 - **** * - **** *** - * ********* - ************ - 1 - ************* - - | | | | - 1 5 10 15 -@end group -@end smallexample - -@need 1200 -On the other hand, if you pass @code{print-graph} a -@code{vertical-step} value of 2, by evaluating this expression: - -@smallexample -(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2) -@end smallexample - -@need 1250 -@noindent -The graph looks like this: - -@smallexample -@group -20 - - - - * - ** * -10 - **** * - **** *** - * ********* - ************ - 2 - ************* - - | | | | - 1 5 10 15 -@end group -@end smallexample - -@noindent -(A question: is the `2' on the bottom of the vertical axis a bug or a -feature? If you think it is a bug, and should be a `1' instead, (or -even a `0'), you can modify the sources.) - -@node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph -@appendixsubsec Graphing Numbers of Words and Symbols - -Now for the graph for which all this code was written: a graph that -shows how many function definitions contain fewer than 10 words and -symbols, how many contain between 10 and 19 words and symbols, how -many contain between 20 and 29 words and symbols, and so on. - -This is a multi-step process. First make sure you have loaded all the -requisite code. - -@need 1500 -It is a good idea to reset the value of @code{top-of-ranges} in case -you have set it to some different value. You can evaluate the -following: - -@smallexample -@group -(setq top-of-ranges - '(10 20 30 40 50 - 60 70 80 90 100 - 110 120 130 140 150 - 160 170 180 190 200 - 210 220 230 240 250 - 260 270 280 290 300) -@end group -@end smallexample - -@noindent -Next create a list of the number of words and symbols in each range. - -@need 1500 -@noindent -Evaluate the following: - -@smallexample -@group -(setq list-for-graph - (defuns-per-range - (sort - (recursive-lengths-list-many-files - (directory-files "/usr/local/emacs/lisp" - t ".+el$")) - '<) - top-of-ranges)) -@end group -@end smallexample - -@noindent -On my old machine, this took about an hour. It looked though 303 Lisp -files in my copy of Emacs version 19.23. After all that computing, -the @code{list-for-graph} had this value: - -@smallexample -@group -(537 1027 955 785 594 483 349 292 224 199 166 120 116 99 -90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220) -@end group -@end smallexample - -@noindent -This means that my copy of Emacs had 537 function definitions with -fewer than 10 words or symbols in them, 1,027 function definitions -with 10 to 19 words or symbols in them, 955 function definitions with -20 to 29 words or symbols in them, and so on. - -Clearly, just by looking at this list we can see that most function -definitions contain ten to thirty words and symbols. - -Now for printing. We do @emph{not} want to print a graph that is -1,030 lines high @dots{} Instead, we should print a graph that is -fewer than twenty-five lines high. A graph that height can be -displayed on almost any monitor, and easily printed on a sheet of paper. - -This means that each value in @code{list-for-graph} must be reduced to -one-fiftieth its present value. - -Here is a short function to do just that, using two functions we have -not yet seen, @code{mapcar} and @code{lambda}. - -@smallexample -@group -(defun one-fiftieth (full-range) - "Return list, each number one-fiftieth of previous." - (mapcar '(lambda (arg) (/ arg 50)) full-range)) -@end group -@end smallexample - -@node lambda, mapcar, Graphing words in defuns, Print Whole Graph -@appendixsubsec A @code{lambda} Expression: Useful Anonymity -@cindex Anonymous function -@findex lambda - -@code{lambda} is the symbol for an anonymous function, a function -without a name. Every time you use an anonymous function, you need to -include its whole body. - -@need 1250 -@noindent -Thus, - -@smallexample -(lambda (arg) (/ arg 50)) -@end smallexample - -@noindent -is a function definition that says `return the value resulting from -dividing whatever is passed to me as @code{arg} by 50'. - -@need 1200 -Earlier, for example, we had a function @code{multiply-by-seven}; it -multiplied its argument by 7. This function is similar, except it -divides its argument by 50; and, it has no name. The anonymous -equivalent of @code{multiply-by-seven} is: - -@smallexample -(lambda (number) (* 7 number)) -@end smallexample - -@noindent -(@xref{defun, , The @code{defun} Special Form}.) - -@need 1250 -@noindent -If we want to multiply 3 by 7, we can write: - -@c !!! Clear print-postscript-figures if the computer formatting this -@c document is too small and cannot handle all the diagrams and figures. -@c clear print-postscript-figures -@c set print-postscript-figures -@c lambda example diagram #1 -@ifnottex -@smallexample -@group -(multiply-by-seven 3) - \_______________/ ^ - | | - function argument -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{lambda-1} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -(multiply-by-seven 3) - \_______________/ ^ - | | - function argument -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -This expression returns 21. - -@need 1250 -@noindent -Similarly, we can write: - -@c lambda example diagram #2 -@ifnottex -@smallexample -@group -((lambda (number) (* 7 number)) 3) - \____________________________/ ^ - | | - anonymous function argument -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{lambda-2} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -((lambda (number) (* 7 number)) 3) - \____________________________/ ^ - | | - anonymous function argument -@end group -@end smallexample -@end iftex -@end ifclear - -@need 1250 -@noindent -If we want to divide 100 by 50, we can write: - -@c lambda example diagram #3 -@ifnottex -@smallexample -@group -((lambda (arg) (/ arg 50)) 100) - \______________________/ \_/ - | | - anonymous function argument -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{lambda-3} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -((lambda (arg) (/ arg 50)) 100) - \______________________/ \_/ - | | - anonymous function argument -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -This expression returns 2. The 100 is passed to the function, which -divides that number by 50. - -@xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs -Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda -expressions derive from the Lambda Calculus. - -@node mapcar, Another Bug, lambda, Print Whole Graph -@appendixsubsec The @code{mapcar} Function -@findex mapcar - -@code{mapcar} is a function that calls its first argument with each -element of its second argument, in turn. The second argument must be -a sequence. - -The @samp{map} part of the name comes from the mathematical phrase, -`mapping over a domain', meaning to apply a function to each of the -elements in a domain. The mathematical phrase is based on the -metaphor of a surveyor walking, one step at a time, over an area he is -mapping. And @samp{car}, of course, comes from the Lisp notion of the -first of a list. - -@need 1250 -@noindent -For example, - -@smallexample -@group -(mapcar '1+ '(2 4 6)) - @result{} (3 5 7) -@end group -@end smallexample - -@noindent -The function @code{1+} which adds one to its argument, is executed on -@emph{each} element of the list, and a new list is returned. - -Contrast this with @code{apply}, which applies its first argument to -all the remaining. -(@xref{Readying a Graph, , Readying a Graph}, for a explanation of -@code{apply}.) - -@need 1250 -In the definition of @code{one-fiftieth}, the first argument is the -anonymous function: - -@smallexample -(lambda (arg) (/ arg 50)) -@end smallexample - -@noindent -and the second argument is @code{full-range}, which will be bound to -@code{list-for-graph}. - -@need 1250 -The whole expression looks like this: - -@smallexample -(mapcar '(lambda (arg) (/ arg 50)) full-range)) -@end smallexample - -@xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs -Lisp Reference Manual}, for more about @code{mapcar}. - -Using the @code{one-fiftieth} function, we can generate a list in -which each element is one-fiftieth the size of the corresponding -element in @code{list-for-graph}. - -@smallexample -@group -(setq fiftieth-list-for-graph - (one-fiftieth list-for-graph)) -@end group -@end smallexample - -@need 1250 -The resulting list looks like this: - -@smallexample -@group -(10 20 19 15 11 9 6 5 4 3 3 2 2 -1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4) -@end group -@end smallexample - -@noindent -This, we are almost ready to print! (We also notice the loss of -information: many of the higher ranges are 0, meaning that fewer than -50 defuns had that many words or symbols---but not necessarily meaning -that none had that many words or symbols.) - -@node Another Bug, Final printed graph, mapcar, Print Whole Graph -@appendixsubsec Another Bug @dots{} Most Insidious -@cindex Bug, most insidious type -@cindex Insidious type of bug - -I said `almost ready to print'! Of course, there is a bug in the -@code{print-graph} function @dots{} It has a @code{vertical-step} -option, but not a @code{horizontal-step} option. The -@code{top-of-range} scale goes from 10 to 300 by tens. But the -@code{print-graph} function will print only by ones. - -This is a classic example of what some consider the most insidious -type of bug, the bug of omission. This is not the kind of bug you can -find by studying the code, for it is not in the code; it is an omitted -feature. Your best actions are to try your program early and often; -and try to arrange, as much as you can, to write code that is easy to -understand and easy to change. Try to be aware, whenever you can, -that whatever you have written, @emph{will} be rewritten, if not soon, -eventually. A hard maxim to follow. - -It is the @code{print-X-axis-numbered-line} function that needs the -work; and then the @code{print-X-axis} and the @code{print-graph} -functions need to be adapted. Not much needs to be done; there is one -nicety: the numbers ought to line up under the tic marks. This takes -a little thought. - -@need 1250 -Here is the corrected @code{print-X-axis-numbered-line}: - -@smallexample -@group -(defun print-X-axis-numbered-line - (number-of-X-tics X-axis-leading-spaces - &optional horizontal-step) - "Print line of X-axis numbers" - (let ((number X-axis-label-spacing) - (horizontal-step (or horizontal-step 1))) -@end group -@group - (insert X-axis-leading-spaces) - ;; @r{Delete extra leading spaces.} - (delete-char - (- (1- - (length (number-to-string horizontal-step))))) - (insert (concat - (make-string -@end group -@group - ;; @r{Insert white space.} - (- (* symbol-width - X-axis-label-spacing) - (1- - (length - (number-to-string horizontal-step))) - 2) - ? ) - (number-to-string - (* number horizontal-step)))) -@end group -@group - ;; @r{Insert remaining numbers.} - (setq number (+ number X-axis-label-spacing)) - (while (> number-of-X-tics 1) - (insert (X-axis-element - (* number horizontal-step))) - (setq number (+ number X-axis-label-spacing)) - (setq number-of-X-tics (1- number-of-X-tics))))) -@end group -@end smallexample - -@need 1500 -If you are reading this in Info, you can see the new versions of -@code{print-X-axis} @code{print-graph} and evaluate them. If you are -reading this in a printed book, you can see the changed lines here -(the full text is too much to print). - -@iftex -@smallexample -@group -(defun print-X-axis (numbers-list horizontal-step) - @dots{} - (print-X-axis-numbered-line - tic-number leading-spaces horizontal-step)) -@end group -@end smallexample - -@smallexample -@group -(defun print-graph - (numbers-list - &optional vertical-step horizontal-step) - @dots{} - (print-X-axis numbers-list horizontal-step)) -@end group -@end smallexample -@end iftex - -@ifnottex -@smallexample -@group -(defun print-X-axis (numbers-list horizontal-step) - "Print X axis labels to length of NUMBERS-LIST. -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." -@end group -@group -;; Value of symbol-width and full-Y-label-width -;; are passed by `print-graph'. - (let* ((leading-spaces - (make-string full-Y-label-width ? )) - ;; symbol-width @r{is provided by} graph-body-print - (tic-width (* symbol-width X-axis-label-spacing)) - (X-length (length numbers-list)) -@end group -@group - (X-tic - (concat - (make-string - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) -@end group -@group - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol)) - (tic-number - (if (zerop (% X-length tic-width)) - (/ X-length tic-width) - (1+ (/ X-length tic-width))))) -@end group - -@group - (print-X-axis-tic-line - tic-number leading-spaces X-tic) - (insert "\n") - (print-X-axis-numbered-line - tic-number leading-spaces horizontal-step))) -@end group -@end smallexample - -@smallexample -@group -(defun print-graph - (numbers-list &optional vertical-step horizontal-step) - "Print labeled bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -@end group - -@group -Optionally, VERTICAL-STEP, a positive integer, -specifies how much a Y axis label increments for -each line. For example, a step of 5 means that -each row is five units. -@end group - -@group -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." - (let* ((symbol-width (length graph-blank)) - ;; @code{height} @r{is both the largest number} - ;; @r{and the number with the most digits.} - (height (apply 'max numbers-list)) -@end group -@group - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) -@end group -@group - (vertical-step (or vertical-step 1)) - (full-Y-label-width - (length - (concat - (number-to-string - (* height-of-top-line vertical-step)) - Y-axis-tic)))) -@end group -@group - (print-Y-axis - height-of-top-line full-Y-label-width vertical-step) - (graph-body-print - numbers-list height-of-top-line symbol-width) - (print-X-axis numbers-list horizontal-step))) -@end group -@end smallexample -@end ifnottex - -@c qqq -@ignore -Graphing Definitions Re-listed - -@need 1250 -Here are all the graphing definitions in their final form: - -@smallexample -@group -(defvar top-of-ranges - '(10 20 30 40 50 - 60 70 80 90 100 - 110 120 130 140 150 - 160 170 180 190 200 - 210 220 230 240 250) - "List specifying ranges for `defuns-per-range'.") -@end group - -@group -(defvar graph-symbol "*" - "String used as symbol in graph, usually an asterisk.") -@end group - -@group -(defvar graph-blank " " - "String used as blank in graph, usually a blank space. -graph-blank must be the same number of columns wide -as graph-symbol.") -@end group - -@group -(defvar Y-axis-tic " - " - "String that follows number in a Y axis label.") -@end group - -@group -(defvar Y-axis-label-spacing 5 - "Number of lines from one Y axis label to next.") -@end group - -@group -(defvar X-axis-tic-symbol "|" - "String to insert to point to a column in X axis.") -@end group - -@group -(defvar X-axis-label-spacing - (if (boundp 'graph-blank) - (* 5 (length graph-blank)) 5) - "Number of units from one X axis label to next.") -@end group -@end smallexample - -@smallexample -@group -(defun count-words-in-defun () - "Return the number of words and symbols in a defun." - (beginning-of-defun) - (let ((count 0) - (end (save-excursion (end-of-defun) (point)))) -@end group - -@group - (while - (and (< (point) end) - (re-search-forward - "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" - end t)) - (setq count (1+ count))) - count)) -@end group -@end smallexample - -@smallexample -@group -(defun lengths-list-file (filename) - "Return list of definitions' lengths within FILE. -The returned list is a list of numbers. -Each number is the number of words or -symbols in one function definition." -@end group - -@group - (message "Working on `%s' ... " filename) - (save-excursion - (let ((buffer (find-file-noselect filename)) - (lengths-list)) - (set-buffer buffer) - (setq buffer-read-only t) - (widen) - (goto-char (point-min)) -@end group - -@group - (while (re-search-forward "^(defun" nil t) - (setq lengths-list - (cons (count-words-in-defun) lengths-list))) - (kill-buffer buffer) - lengths-list))) -@end group -@end smallexample - -@smallexample -@group -(defun lengths-list-many-files (list-of-files) - "Return list of lengths of defuns in LIST-OF-FILES." - (let (lengths-list) -;;; @r{true-or-false-test} - (while list-of-files - (setq lengths-list - (append - lengths-list -@end group -@group -;;; @r{Generate a lengths' list.} - (lengths-list-file - (expand-file-name (car list-of-files))))) -;;; @r{Make files' list shorter.} - (setq list-of-files (cdr list-of-files))) -;;; @r{Return final value of lengths' list.} - lengths-list)) -@end group -@end smallexample - -@smallexample -@group -(defun defuns-per-range (sorted-lengths top-of-ranges) - "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." - (let ((top-of-range (car top-of-ranges)) - (number-within-range 0) - defuns-per-range-list) -@end group - -@group - ;; @r{Outer loop.} - (while top-of-ranges - - ;; @r{Inner loop.} - (while (and - ;; @r{Need number for numeric test.} - (car sorted-lengths) - (< (car sorted-lengths) top-of-range)) - - ;; @r{Count number of definitions within current range.} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) -@end group - -@group - ;; @r{Exit inner loop but remain within outer loop.} - - (setq defuns-per-range-list - (cons number-within-range defuns-per-range-list)) - (setq number-within-range 0) ; @r{Reset count to zero.} - - ;; @r{Move to next range.} - (setq top-of-ranges (cdr top-of-ranges)) - ;; @r{Specify next top of range value.} - (setq top-of-range (car top-of-ranges))) -@end group - -@group - ;; @r{Exit outer loop and count the number of defuns larger than} - ;; @r{ the largest top-of-range value.} - (setq defuns-per-range-list - (cons - (length sorted-lengths) - defuns-per-range-list)) - - ;; @r{Return a list of the number of definitions within each range,} - ;; @r{ smallest to largest.} - (nreverse defuns-per-range-list))) -@end group -@end smallexample - -@smallexample -@group -(defun column-of-graph (max-graph-height actual-height) - "Return list of MAX-GRAPH-HEIGHT strings; -ACTUAL-HEIGHT are graph-symbols. -The graph-symbols are contiguous entries at the end -of the list. -The list will be inserted as one column of a graph. -The strings are either graph-blank or graph-symbol." -@end group - -@group - (let ((insert-list nil) - (number-of-top-blanks - (- max-graph-height actual-height))) - - ;; @r{Fill in @code{graph-symbols}.} - (while (> actual-height 0) - (setq insert-list (cons graph-symbol insert-list)) - (setq actual-height (1- actual-height))) -@end group - -@group - ;; @r{Fill in @code{graph-blanks}.} - (while (> number-of-top-blanks 0) - (setq insert-list (cons graph-blank insert-list)) - (setq number-of-top-blanks - (1- number-of-top-blanks))) - - ;; @r{Return whole list.} - insert-list)) -@end group -@end smallexample - -@smallexample -@group -(defun Y-axis-element (number full-Y-label-width) - "Construct a NUMBERed label element. -A numbered element looks like this ` 5 - ', -and is padded as needed so all line up with -the element for the largest number." -@end group -@group - (let* ((leading-spaces - (- full-Y-label-width - (length - (concat (number-to-string number) - Y-axis-tic))))) -@end group -@group - (concat - (make-string leading-spaces ? ) - (number-to-string number) - Y-axis-tic))) -@end group -@end smallexample - -@smallexample -@group -(defun print-Y-axis - (height full-Y-label-width &optional vertical-step) - "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH. -Height must be the maximum height of the graph. -Full width is the width of the highest label element. -Optionally, print according to VERTICAL-STEP." -@end group -@group -;; Value of height and full-Y-label-width -;; are passed by `print-graph'. - (let ((start (point))) - (insert-rectangle - (Y-axis-column height full-Y-label-width vertical-step)) -@end group -@group - ;; @r{Place point ready for inserting graph.} - (goto-char start) - ;; @r{Move point forward by value of} full-Y-label-width - (forward-char full-Y-label-width))) -@end group -@end smallexample - -@smallexample -@group -(defun print-X-axis-tic-line - (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) - "Print ticks for X axis." - (insert X-axis-leading-spaces) - (insert X-axis-tic-symbol) ; @r{Under first column.} -@end group -@group - ;; @r{Insert second tic in the right spot.} - (insert (concat - (make-string - (- (* symbol-width X-axis-label-spacing) - ;; @r{Insert white space up to second tic symbol.} - (* 2 (length X-axis-tic-symbol))) - ? ) - X-axis-tic-symbol)) -@end group -@group - ;; @r{Insert remaining ticks.} - (while (> number-of-X-tics 1) - (insert X-axis-tic-element) - (setq number-of-X-tics (1- number-of-X-tics)))) -@end group -@end smallexample - -@smallexample -@group -(defun X-axis-element (number) - "Construct a numbered X axis element." - (let ((leading-spaces - (- (* symbol-width X-axis-label-spacing) - (length (number-to-string number))))) - (concat (make-string leading-spaces ? ) - (number-to-string number)))) -@end group -@end smallexample - -@smallexample -@group -(defun graph-body-print (numbers-list height symbol-width) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -HEIGHT is maximum height of graph. -SYMBOL-WIDTH is number of each column." -@end group -@group - (let (from-position) - (while numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) - (goto-char from-position) - (forward-char symbol-width) -@end group -@group - ;; @r{Draw graph column by column.} - (sit-for 0) - (setq numbers-list (cdr numbers-list))) - ;; @r{Place point for X axis labels.} - (forward-line height) - (insert "\n"))) -@end group -@end smallexample - -@smallexample -@group -(defun Y-axis-column - (height width-of-label &optional vertical-step) - "Construct list of labels for Y axis. -HEIGHT is maximum height of graph. -WIDTH-OF-LABEL is maximum width of label. -@end group -@group -VERTICAL-STEP, an option, is a positive integer -that specifies how much a Y axis label increments -for each line. For example, a step of 5 means -that each line is five units of the graph." - (let (Y-axis - (number-per-line (or vertical-step 1))) -@end group -@group - (while (> height 1) - (if (zerop (% height Y-axis-label-spacing)) - ;; @r{Insert label.} - (setq Y-axis - (cons - (Y-axis-element - (* height number-per-line) - width-of-label) - Y-axis)) -@end group -@group - ;; @r{Else, insert blanks.} - (setq Y-axis - (cons - (make-string width-of-label ? ) - Y-axis))) - (setq height (1- height))) -@end group -@group - ;; @r{Insert base line.} - (setq Y-axis (cons (Y-axis-element - (or vertical-step 1) - width-of-label) - Y-axis)) - (nreverse Y-axis))) -@end group -@end smallexample - -@smallexample -@group -(defun print-X-axis-numbered-line - (number-of-X-tics X-axis-leading-spaces - &optional horizontal-step) - "Print line of X-axis numbers" - (let ((number X-axis-label-spacing) - (horizontal-step (or horizontal-step 1))) -@end group -@group - (insert X-axis-leading-spaces) - ;; line up number - (delete-char (- (1- (length (number-to-string horizontal-step))))) - (insert (concat - (make-string - ;; @r{Insert white space up to next number.} - (- (* symbol-width X-axis-label-spacing) - (1- (length (number-to-string horizontal-step))) - 2) - ? ) - (number-to-string (* number horizontal-step)))) -@end group -@group - ;; @r{Insert remaining numbers.} - (setq number (+ number X-axis-label-spacing)) - (while (> number-of-X-tics 1) - (insert (X-axis-element (* number horizontal-step))) - (setq number (+ number X-axis-label-spacing)) - (setq number-of-X-tics (1- number-of-X-tics))))) -@end group -@end smallexample - -@smallexample -@group -(defun print-X-axis (numbers-list horizontal-step) - "Print X axis labels to length of NUMBERS-LIST. -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." -@end group -@group -;; Value of symbol-width and full-Y-label-width -;; are passed by `print-graph'. - (let* ((leading-spaces - (make-string full-Y-label-width ? )) - ;; symbol-width @r{is provided by} graph-body-print - (tic-width (* symbol-width X-axis-label-spacing)) - (X-length (length numbers-list)) -@end group -@group - (X-tic - (concat - (make-string - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) -@end group -@group - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol)) - (tic-number - (if (zerop (% X-length tic-width)) - (/ X-length tic-width) - (1+ (/ X-length tic-width))))) -@end group - -@group - (print-X-axis-tic-line - tic-number leading-spaces X-tic) - (insert "\n") - (print-X-axis-numbered-line - tic-number leading-spaces horizontal-step))) -@end group -@end smallexample - -@smallexample -@group -(defun one-fiftieth (full-range) - "Return list, each number of which is 1/50th previous." - (mapcar '(lambda (arg) (/ arg 50)) full-range)) -@end group -@end smallexample - -@smallexample -@group -(defun print-graph - (numbers-list &optional vertical-step horizontal-step) - "Print labeled bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -@end group - -@group -Optionally, VERTICAL-STEP, a positive integer, -specifies how much a Y axis label increments for -each line. For example, a step of 5 means that -each row is five units. -@end group - -@group -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." - (let* ((symbol-width (length graph-blank)) - ;; @code{height} @r{is both the largest number} - ;; @r{and the number with the most digits.} - (height (apply 'max numbers-list)) -@end group -@group - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) -@end group -@group - (vertical-step (or vertical-step 1)) - (full-Y-label-width - (length - (concat - (number-to-string - (* height-of-top-line vertical-step)) - Y-axis-tic)))) -@end group -@group - - (print-Y-axis - height-of-top-line full-Y-label-width vertical-step) - (graph-body-print - numbers-list height-of-top-line symbol-width) - (print-X-axis numbers-list horizontal-step))) -@end group -@end smallexample -@c qqq -@end ignore - -@page -@node Final printed graph, , Another Bug, Print Whole Graph -@appendixsubsec The Printed Graph - -When made and installed, you can call the @code{print-graph} command -like this: -@sp 1 - -@smallexample -@group -(print-graph fiftieth-list-for-graph 50 10) -@end group -@end smallexample -@sp 1 - -@noindent -Here is the graph: -@sp 2 - -@smallexample -@group -1000 - * - ** - ** - ** - ** - 750 - *** - *** - *** - *** - **** - 500 - ***** - ****** - ****** - ****** - ******* - 250 - ******** - ********* * - *********** * - ************* * - 50 - ***************** * * - | | | | | | | | - 10 50 100 150 200 250 300 350 -@end group -@end smallexample - -@sp 2 - -@noindent -The largest group of functions contain 10 -- 19 words and symbols each. - -@node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top -@appendix Free Software and Free Manuals - -@strong{by Richard M. Stallman} -@sp 1 - -The biggest deficiency in free operating systems is not in the -software---it is the lack of good free manuals that we can include in -these systems. Many of our most important programs do not come with -full manuals. Documentation is an essential part of any software -package; when an important free software package does not come with a -free manual, that is a major gap. We have many such gaps today. - -Once upon a time, many years ago, I thought I would learn Perl. I got -a copy of a free manual, but I found it hard to read. When I asked -Perl users about alternatives, they told me that there were better -introductory manuals---but those were not free. - -Why was this? The authors of the good manuals had written them for -O'Reilly Associates, which published them with restrictive terms---no -copying, no modification, source files not available---which exclude -them from the free software community. - -That wasn't the first time this sort of thing has happened, and (to -our community's great loss) it was far from the last. Proprietary -manual publishers have enticed a great many authors to restrict their -manuals since then. Many times I have heard a GNU user eagerly tell me -about a manual that he is writing, with which he expects to help the -GNU project---and then had my hopes dashed, as he proceeded to explain -that he had signed a contract with a publisher that would restrict it -so that we cannot use it. - -Given that writing good English is a rare skill among programmers, we -can ill afford to lose manuals this way. - -Free documentation, like free software, is a matter of freedom, not -price. The problem with these manuals was not that O'Reilly Associates -charged a price for printed copies---that in itself is fine. The Free -Software Foundation @uref{http://shop.fsf.org, sells printed copies} of -free @uref{http://www.gnu.org/doc/doc.html, GNU manuals}, too. -But GNU manuals are available in source code form, while these manuals -are available only on paper. GNU manuals come with permission to copy -and modify; the Perl manuals do not. These restrictions are the -problems. - -The criterion for a free manual is pretty much the same as for free -software: it is a matter of giving all users certain -freedoms. Redistribution (including commercial redistribution) must be -permitted, so that the manual can accompany every copy of the program, -on-line or on paper. Permission for modification is crucial too. - -As a general rule, I don't believe that it is essential for people to -have permission to modify all sorts of articles and books. The issues -for writings are not necessarily the same as those for software. For -example, I don't think you or I are obliged to give permission to -modify articles like this one, which describe our actions and our -views. - -But there is a particular reason why the freedom to modify is crucial -for documentation for free software. When people exercise their right -to modify the software, and add or change its features, if they are -conscientious they will change the manual too---so they can provide -accurate and usable documentation with the modified program. A manual -which forbids programmers to be conscientious and finish the job, or -more precisely requires them to write a new manual from scratch if -they change the program, does not fill our community's needs. - -While a blanket prohibition on modification is unacceptable, some -kinds of limits on the method of modification pose no problem. For -example, requirements to preserve the original author's copyright -notice, the distribution terms, or the list of authors, are ok. It is -also no problem to require modified versions to include notice that -they were modified, even to have entire sections that may not be -deleted or changed, as long as these sections deal with nontechnical -topics. (Some GNU manuals have them.) - -These kinds of restrictions are not a problem because, as a practical -matter, they don't stop the conscientious programmer from adapting the -manual to fit the modified program. In other words, they don't block -the free software community from making full use of the manual. - -However, it must be possible to modify all the technical content of -the manual, and then distribute the result in all the usual media, -through all the usual channels; otherwise, the restrictions do block -the community, the manual is not free, and so we need another manual. - -Unfortunately, it is often hard to find someone to write another -manual when a proprietary manual exists. The obstacle is that many -users think that a proprietary manual is good enough---so they don't -see the need to write a free manual. They do not see that the free -operating system has a gap that needs filling. - -Why do users think that proprietary manuals are good enough? Some have -not considered the issue. I hope this article will do something to -change that. - -Other users consider proprietary manuals acceptable for the same -reason so many people consider proprietary software acceptable: they -judge in purely practical terms, not using freedom as a -criterion. These people are entitled to their opinions, but since -those opinions spring from values which do not include freedom, they -are no guide for those of us who do value freedom. - -Please spread the word about this issue. We continue to lose manuals -to proprietary publishing. If we spread the word that proprietary -manuals are not sufficient, perhaps the next person who wants to help -GNU by writing documentation will realize, before it is too late, that -he must above all make it free. - -We can also encourage commercial publishers to sell free, copylefted -manuals instead of proprietary ones. One way you can help this is to -check the distribution terms of a manual before you buy it, and prefer -copylefted manuals to non-copylefted ones. - -@sp 2 -@noindent -Note: The Free Software Foundation maintains a page on its Web site -that lists free books available from other publishers:@* -@uref{http://www.gnu.org/doc/other-free-books.html} - -@node GNU Free Documentation License, Index, Free Software and Free Manuals, Top -@appendix GNU Free Documentation License - -@cindex FDL, GNU Free Documentation License -@include doclicense.texi - -@node Index, About the Author, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Index - -@ignore -MENU ENTRY: NODE NAME. -@end ignore - -@printindex cp - -@iftex -@c Place biographical information on right-hand (verso) page - -@tex -\par\vfill\supereject -\ifodd\pageno - \global\evenheadline={\hfil} \global\evenfootline={\hfil} - \global\oddheadline={\hfil} \global\oddfootline={\hfil} - %\page\hbox{}\page -\else -% \par\vfill\supereject - \global\evenheadline={\hfil} \global\evenfootline={\hfil} - \global\oddheadline={\hfil} \global\oddfootline={\hfil} - %\page\hbox{}%\page - %\page\hbox{}%\page -\fi -@end tex - -@c page -@w{ } - -@c ================ Biographical information ================ - -@w{ } -@sp 8 -@center About the Author -@sp 1 -@end iftex - -@ifnottex -@node About the Author, , Index, Top -@unnumbered About the Author -@end ifnottex - -@quotation -Robert J. Chassell has worked with GNU Emacs since 1985. He writes -and edits, teaches Emacs and Emacs Lisp, and speaks throughout the -world on software freedom. Chassell was a founding Director and -Treasurer of the Free Software Foundation, Inc. He is co-author of -the @cite{Texinfo} manual, and has edited more than a dozen other -books. He graduated from Cambridge University, in England. He has an -abiding interest in social and economic history and flies his own -airplane. -@end quotation - -@c @page -@c @w{ } -@c -@c @c Prevent page number on blank verso, so eject it first. -@c @tex -@c \par\vfill\supereject -@c @end tex - -@c @iftex -@c @headings off -@c @evenheading @thispage @| @| @thistitle -@c @oddheading @| @| @thispage -@c @end iftex - -@bye diff --git a/doc/lispintro/lambda-1.eps b/doc/lispintro/lambda-1.eps deleted file mode 100644 index 42f8d54264c..00000000000 --- a/doc/lispintro/lambda-1.eps +++ /dev/null @@ -1,465 +0,0 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%BoundingBox: 33 710 173 759 -%%Title: lambda-diagram1 -%%CreationDate: Wed Mar 8 14:31:53 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) - -% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 33 710 173 759 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 63 75 moveto (\(multiply-by-seven 3\)) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 80 80 moveto - 96 96 lineto - 224 96 lineto - 240 80 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 264 119 moveto - -22 0 atan dup cos 8 mul 264 exch sub - exch sin 8 mul 97 exch sub lineto - stroke -grestore -gsave - newpath - 264 97 8 3 0 -22 tgifarrowtip - closepath fill -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 160 103 moveto - 160 119 lineto - stroke -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 112 139 moveto (function) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 224 139 moveto (argument) show - grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:31:53 1995 diff --git a/doc/lispintro/lambda-1.pdf b/doc/lispintro/lambda-1.pdf deleted file mode 100644 index 158d6fd2276..00000000000 --- a/doc/lispintro/lambda-1.pdf +++ /dev/null @@ -1,69 +0,0 @@ -%PDF-1.3 -%Ç쏢 -5 0 obj -<> -stream -xœ•PMkÃ0 ½ëWè˜âYr<;×ÁvèæۺҐg횴ôßÏÎGéu!KïéI¼#JA(ã[réááÍ`s‰/!8M\RéñÉ’ÅBèGÖèj˜g YäÊhT…°É.ñc7´‡îš}_³Su®zT»4u{xv°-¢Æ%H¼†hX¢2=pXÈVb…Z$¸ƒw ÒIËIÁÏ%s!â 7œM>5"nHX{G!RVßujÐAœóU3Vë†(ù3ÂÑêæÃGR}9´?}š‘±Vpž|ý6£¯ú!ýt›ÙŒ-üxuVendstream -endobj -6 0 obj -236 -endobj -4 0 obj -<> -/Contents 5 0 R ->> -endobj -3 0 obj -<< /Type /Pages /Kids [ -4 0 R -] /Count 1 ->> -endobj -1 0 obj -<> -endobj -7 0 obj -<>endobj -9 0 obj -<> -endobj -10 0 obj -<> -endobj -8 0 obj -<> -endobj -2 0 obj -<>endobj -xref -0 11 -0000000000 65535 f -0000000548 00000 n -0000000758 00000 n -0000000489 00000 n -0000000340 00000 n -0000000015 00000 n -0000000321 00000 n -0000000596 00000 n -0000000696 00000 n -0000000637 00000 n -0000000666 00000 n -trailer -<< /Size 11 /Root 1 0 R /Info 2 0 R -/ID [(4Ðä@7‡måèbW9¨Áë)(4Ðä@7‡måèbW9¨Áë)] ->> -startxref -869 -%%EOF diff --git a/doc/lispintro/lambda-2.eps b/doc/lispintro/lambda-2.eps deleted file mode 100644 index ab9e8a85820..00000000000 --- a/doc/lispintro/lambda-2.eps +++ /dev/null @@ -1,465 +0,0 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%BoundingBox: 33 730 240 777 -%%Title: lambda-diagram2 -%%CreationDate: Wed Mar 8 14:33:09 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) - -% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 33 730 240 777 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 63 43 moveto (\(\(lambda \(number\) \(* 7 number\)\) 3\)) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 80 48 moveto - 96 64 lineto - 336 64 lineto - 353 49 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 395 85 moveto - -21 0 atan dup cos 8 mul 395 exch sub - exch sin 8 mul 64 exch sub lineto - stroke -grestore -gsave - newpath - 395 64 8 3 0 -21 tgifarrowtip - closepath fill -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 208 69 moveto - 208 85 lineto - stroke -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 112 102 moveto (anonymous function) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 344 102 moveto (argument) show - grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:33:09 1995 diff --git a/doc/lispintro/lambda-2.pdf b/doc/lispintro/lambda-2.pdf deleted file mode 100644 index 33f3e0d25a07f285453146ff93e750d2508988a1..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1225 zcmZuxOH30{6!jB-FStNK7lJ-NjS!A=iuQdqb# z#vlGQl2{g^ZVZXV1S1imMk7`OabXCWs6-RgNR$|KA^zSgrPa!8X5P8?o_Fs#H=}b| z?d!P>2B7O3J=qR;$U>!NAK0{s*^WX1yce1XA~JS4h>;2zdr-p2ihPP6Su8-qDw66! zBzoTEsJqW*^?uy_zBOya^XqWi$Lg%P8}XC+=PMl-pJs0yU)}O^BJNl`)Hwgr+7BP% zgV|T%xp=5^;n>(nZ1aH!fp5!CY}q~QRq3*^&YClQ;!vrlqqsG&;5_@n^K3_CTiXmz zzsV@wu8R%4$+Y0IQmxiyQ6C4VsLor=}%Q9DCAG7 zK)$GQR4@A0^LmhkjA>DKH8mi{B?S=UKz>;&RU**KlCYjNL!-G8keG@>7#gVRfDw_V zgjFBXh#xLh@wpN9GQ=^+>_QPt(rpo3?#9FuSTtE-S4cHSDMdgWV#>&w5NeP*n}Cu{ z(Hkb6CS;^5m}pCbOoi;%pcl}lMNkO|Lzq%hwqz-nDos|FNmvRhfhmf~=F|D+fAiB# z1IFocK+a-G64M!y+b5a_cjS&FzBadle09K2>hOP~i9ttiF&)N|qkWO2|rNFR&KtS+FS)kP#JyEEDw( zGFwBn3Z&ALP2XyT-h#Ko;miGIy!1r0k)Pe=tS. - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 33 728 211 777 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 63 43 moveto (\(\(lambda \(arg\) \(/ arg 50\)\) 100\)) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 80 48 moveto - 96 64 lineto - 284 64 lineto - 299 48 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 354 86 moveto - -25 0 atan dup cos 8 mul 354 exch sub - exch sin 8 mul 61 exch sub lineto - stroke -grestore -gsave - newpath - 354 61 8 3 0 -25 tgifarrowtip - closepath fill -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 199 70 moveto - 199 86 lineto - stroke -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 101 106 moveto (anonymous function) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 293 106 moveto (argument) show - grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:33:49 1995 diff --git a/doc/lispintro/lambda-3.pdf b/doc/lispintro/lambda-3.pdf deleted file mode 100644 index 6b54c9440ab..00000000000 --- a/doc/lispintro/lambda-3.pdf +++ /dev/null @@ -1,69 +0,0 @@ -%PDF-1.3 -%Ç쏢 -5 0 obj -<> -stream -xœ•PMO„0½Ï¯˜ãrp¶Ó/ÊÕʘxXå&…¬¡u—ÿ½S` WÓL^çõõuúN¨ˆQ¥µbaÿ”cw…÷Rœ€g®ÐD¼-E° çµÃ²…å.£&kr‡¦ Àé$®’Õ×ñí½ÆjWuU&¸GÙ¡SU&-+Á¬ü„»à(y~‹å£ÔX+4¹ÂZÐAa/œÏÉ]ã˜B˜E=<{Ï$ì|‚øG褓é¶"]ø™Kª<덊½µd†i!¥j»š_‰õµäý¯À̒”M$¯—]=ŒÃO§3¶ÓÐ\ŽãÝØÂsHùMñc¸d¯åÃ×~B©ašendstream -endobj -6 0 obj -258 -endobj -4 0 obj -<> -/Contents 5 0 R ->> -endobj -3 0 obj -<< /Type /Pages /Kids [ -4 0 R -] /Count 1 ->> -endobj -1 0 obj -<> -endobj -7 0 obj -<>endobj -9 0 obj -<> -endobj -10 0 obj -<> -endobj -8 0 obj -<> -endobj -2 0 obj -<>endobj -xref -0 11 -0000000000 65535 f -0000000570 00000 n -0000000780 00000 n -0000000511 00000 n -0000000362 00000 n -0000000015 00000 n -0000000343 00000 n -0000000618 00000 n -0000000718 00000 n -0000000659 00000 n -0000000688 00000 n -trailer -<< /Size 11 /Root 1 0 R /Info 2 0 R -/ID [(ß vFÙ ¶y¹¤l%t­)(ß vFÙ ¶y¹¤l%t­)] ->> -startxref -891 -%%EOF diff --git a/doc/lispintro/makefile.w32-in b/doc/lispintro/makefile.w32-in deleted file mode 100644 index a8aaf43096e..00000000000 --- a/doc/lispintro/makefile.w32-in +++ /dev/null @@ -1,79 +0,0 @@ -#### -*- Makefile -*- for the Emacs Lisp Introduction manual. - -# Copyright (C) 2003-2012 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -srcdir = . - -infodir = $(srcdir)/../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc - -INFO_SOURCES = $(srcdir)/emacs-lisp-intro.texi $(srcdir)/doclicense.texi -# The file name eintr must fit within 5 characters, to allow for -# -NN extensions to fit into DOS 8+3 limits without clashing -INFO_TARGETS = $(infodir)/eintr -DVI_TARGETS = emacs-lisp-intro.dvi - -MAKEINFO = makeinfo -INSTALL_INFO = install-info -TEXI2DVI = texi2dvi -TEXI2PDF = texi2pdf -DVIPS = dvips -ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) -I$(srcdir) -I$(texinfodir)" /C - -.SUFFIXES: .dvi .ps .texi - -info: $(INFO_TARGETS) - -$(infodir)/dir: - $(INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) - -dvi: $(DVI_TARGETS) - -$(infodir)/eintr: $(INFO_SOURCES) - $(MAKEINFO) -o $@ $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.dvi: $(INFO_SOURCES) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.pdf: $(INFO_SOURCES) - $(ENVADD) $(TEXI2PDF) $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.html: $(INFO_SOURCES) - $(MAKEINFO) --html -o $@ $(srcdir)/emacs-lisp-intro.texi - -.dvi.ps: - $(DVIPS) $< -o $@ - -mostlyclean: - - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr *.tp - -clean: mostlyclean - - $(DEL) *.dvi $(infodir)/eintr* - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc - -# Tell versions [3.59,3.63) of GNU make to not export all variables. -# Otherwise a system limit (for SysV at least) may be exceeded. -.NOEXPORT: diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog deleted file mode 100644 index 077c8f94af1..00000000000 --- a/doc/lispref/ChangeLog +++ /dev/null @@ -1,11075 +0,0 @@ -2012-06-01 Chong Yidong - - * Version 24.1 released. - -2012-05-15 Chong Yidong - - * functions.texi (Obsolete Functions): Fix doc for - set-advertised-calling-convention. - - * modes.texi (Mode Help): Fix describe-mode. - - * display.texi (Face Functions): Fix define-obsolete-face-alias. - - * variables.texi (Variable Aliases): Fix make-obsolete-variable. - -2012-05-15 Martin Rudalics - - * commands.texi (Recursive Editing): recursive-edit is a - command. - - * compile.texi (Docs and Compilation): - byte-compile-dynamic-docstrings is an option. - - * debugging.texi (Invoking the Debugger): debug is a command. - - * display.texi (Progress): progress-reporter-update and - progress-reporter-force-update have VALUE argument optional. - (Animated Images): Use non-@code{nil} instead of non-nil. - - * files.texi (Format Conversion Round-Trip): Use non-@code{nil} - instead of non-nil. - - * frames.texi (Creating Frames): make-frame is a command. - (Input Focus): select-frame is a command. - (Pointer Shape): void-text-area-pointer is an option. - - * help.texi (Describing Characters): read-kbd-macro is a - command. - (Help Functions): describe-prefix-bindings is a command. - - * markers.texi (Creating Markers): Both arguments of copy-marker - are optional. - - * minibuf.texi (Reading File Names): Use @kbd instead of @code. - - * modes.texi (Mode Line Variables): mode-line-remote and - mode-line-client are not options. - (Imenu): imenu-add-to-menubar is a command. - (SMIE Indentation Helpers): Use non-@code{nil} instead of - non-nil. - - * os.texi (Sound Output): play-sound-file is a command. - - * package.texi (Package Archives): Use @key{RET} instead of - @kbd{RET}. - - * processes.texi (Signals to Processes): Use @key{RET} instead - of @code{RET}. - (Signals to Processes): signal-process is a command. - - * text.texi (Clickable Text): Use @key{RET} instead of - @kbd{RET}. - (Base 64): base64-encode-string is not a command while - base64-decode-region is. - - * windows.texi (Switching Buffers): pop-to-buffer is a command. - -2012-05-08 Glenn Morris - - * Makefile.in (clean, mostlyclean): Add some more vol1/2 items. - - * two-volume.make (emacsdir): New. - (tex): Add directory with emacsver.texi to TEXINPUTS. - -2012-05-05 Glenn Morris - - * minibuf.texi (Minibuffer History, Basic Completion): - Tweak page breaks. - - * internals.texi (Garbage Collection, Memory Usage) - (Writing Emacs Primitives): Tweak page breaks. - - * streams.texi (Output Variables): Improve page break. - - * edebug.texi (Edebug Display Update): Improve page break. - - * compile.texi (Disassembly): Condense the examples. - - * eval.texi, functions.texi, loading.texi, macros.texi: - Where possible, use example rather than smallexample. - - * symbols.texi: Where possible, use example rather than smallexample. - (Symbol Components): Fix typo. - (Other Plists): Tweak page break. - - * sequences.texi (Arrays): Tweak page breaks. - - * customize.texi: Where possible, use example rather than smallexample. - (Common Keywords, Variable Definitions, Applying Customizations) - (Custom Themes): Tweak page breaks. - - * control.texi: Where possible, use example rather than smallexample. - (Sequencing, Conditionals, Signaling Errors, Handling Errors): - Tweak page breaks. - -2012-05-04 Glenn Morris - - * lists.texi (List-related Predicates, List Variables): - Tweak page-breaks. - (Sets And Lists): Convert inforef to xref. - - * text.texi (Auto Filling): Don't mention Emacs 19. - - * commands.texi (Event Input Misc): Don't mention unread-command-char. - * numbers.texi (Predicates on Numbers): Don't mention Emacs 18. - - * objects.texi (Process Type, Overlay Type): Tweak page-breaks. - - * intro.texi (Caveats): Copyedit. - (Lisp History): Convert inforef to xref. - (Lisp History, Printing Notation, Version Info): Improve page-breaks. - - * elisp.texi (DATE): Forgot to change the month in 2012-04-21 change. - -2012-05-01 Glenn Morris - - * elisp.texi (@copying): - * intro.texi (Introduction): Only print VERSION in the TeX version. - -2012-04-29 Chong Yidong - - * text.texi (Change Hooks): Minor fix for after-change-functions. - -2012-04-28 Glenn Morris - - * package.texi (Packaging Basics): - * loading.texi (Autoload): - * files.texi (Magic File Names): - Reword to remove/reduce some overly long/short lines. - -2012-04-26 Glenn Morris - - * elisp.texi, vol1.texi, vol2.texi: Some fixes for detailed menu. - * modes.texi (Major Modes, Auto-Indentation): - * buffers.texi (Buffers): Some fixes for menu descriptions. - -2012-04-26 Stefan Monnier - - * functions.texi (Simple Lambda, Argument List): - * eval.texi (Function Indirection): Avoid deprecated form. - -2012-04-26 Glenn Morris - - * book-spine.texi, elisp.texi, vol1.texi, vol2.texi: - Add "et al." to authors. - - * buffers.texi, commands.texi, compile.texi, control.texi: - * customize.texi, display.texi, eval.texi, files.texi, frames.texi: - * hash.texi, help.texi, intro.texi, keymaps.texi, lists.texi: - * modes.texi, numbers.texi, objects.texi, streams.texi: - * symbols.texi, syntax.texi, text.texi, tips.texi, variables.texi: - Use Texinfo recommended convention for quotes+punctuation. - -2012-04-23 Chong Yidong - - * keymaps.texi (Scanning Keymaps): Fix description of NO-REMAP arg - to where-is-internal (Bug#10872). - -2012-04-21 Glenn Morris - - * macros.texi (Indenting Macros): Fix typo. - - * windows.texi (Basic Windows, Windows and Frames, Window Sizes) - (Resizing Windows, Deleting Windows, Selecting Windows) - (Choosing Window Options, Horizontal Scrolling) - (Cyclic Window Ordering, Window History, Dedicated Windows) - (Quitting Windows, Window Configurations, Textual Scrolling): - (Coordinates and Windows, Window Configurations) - (Window Parameters, Window Hooks): Copyedits. - (Splitting Windows, Deleting Windows): - Fix ignore-window-parameters logic. - (Selecting Windows, Choosing Window Options): Markup fixes. - (Window Start and End): Remove pointless example. - Remove cross-reference to deleted count-lines content. - (Textual Scrolling): Mention recenter-redisplay, recenter-top-bottom, - and recenter-positions. Remove recenter example. - - * elisp.texi, vol1.texi, vol2.texi: Bump VERSION and DATE. - - * minibuf.texi (Intro to Minibuffers): - Tweak discussion of resizing minibuffer window. - -2012-04-20 Chong Yidong - - * processes.texi (Asynchronous Processes): Mention nil argument to - start-process. - -2012-04-20 Glenn Morris - - * minibuf.texi (Basic Completion): No need to describe obarrays here. - Don't mention obsolete `nospace' argument of all-completions. - (Minibuffer Completion, Completion Commands, Reading File Names) - (Completion Variables): Copyedits. - (Completion Commands): Mention parent keymaps. - Remove obsolete minibuffer-local-filename-must-match-map. - (High-Level Completion): Remove read-variable's almost - word-for-word duplication of read-command. - * elisp.texi, vol1.texi, vol2.texi, minibuf.texi (Completion): - Update "High-Level Completion" description. - -2012-04-19 Glenn Morris - - * minibuf.texi (Minibuffers): - * elisp.texi, vol1.texi, vol2.texi: Fix minibuffer subsection order. - - * minibuf.texi: Standardize metasyntactic variables ("history", etc). - Use Texinfo-recommended form of quote+punctuation. - (Intro to Minibuffers): First minibuffer is #1, not #0. - Mention minibuffer-inactive-mode. - (Text from Minibuffer): Copyedits. - (Minibuffer History, Programmed Completion): Fix @var usage. - (Object from Minibuffer): Remove overly pedantic para. - (Minibuffer History): Copyedits. Add face-name-history. - (Initial Input, Yes-or-No Queries, Multiple Queries) - (Minibuffer Windows, Minibuffer Misc): Copyedits. - (Yes-or-No Queries): Tweak example. - (Minibuffer Commands): Add next-complete-history-element. - (Minibuffer Misc): Mention minibuffer-message-timeout, and - minibuffer-inactive-mode. - -2012-04-18 Glenn Morris - - * processes.texi (Serial Ports, Byte Packing, Bindat Spec) - (Bindat Functions): Copyedits. - -2012-04-18 Christopher Schmidt - - * files.texi (Saving Buffers): Document `visit and `visit-save' - values of require-final-newline. - -2012-04-18 Glenn Morris - - * processes.texi (Output from Processes, Filter Functions): - Mention waiting-for-user-input-p. - (Sentinels, Query Before Exit, System Processes, Transaction Queues): - (Network Servers, Datagrams, Network Processes, Network Options) - (Network Feature Testing, Serial Ports): Copyedits. - (Network): Add encrypted network overview paragraph. - Cross-reference the Emacs-GnuTLS manual. Use @acronym. - -2012-04-17 Chong Yidong - - * help.texi (Keys in Documentation): Mention :advertised-binding. - - * keymaps.texi (Menu Bar): Move most of the :advertised-binding - description to help.texi. - -2012-04-16 Glenn Morris - - * processes.texi (Process Information, Input to Processes) - (Signals to Processes, Output from Processes, Process Buffers) - (Filter Functions, Decoding Output): Copyedits. - (Accepting Output): Discourage use of `millisec' argument. - -2012-04-15 Glenn Morris - - * processes.texi (Processes, Subprocess Creation, Shell Arguments): - (Synchronous Processes, Asynchronous Processes, Deleting Processes): - Copyedits. - (Subprocess Creation): Discourage modifying exec-path directly. - (Synchronous Processes, Asynchronous Processes): - Update some example output. - (Process Information): Fix typo. - (Bindat Spec): Use Texinfo-recommended form of quote+punctuation. - -2012-04-14 Glenn Morris - - * anti.texi (Antinews): Copyedits. Don't @dfn anything here. - open-network-stream does exist in Emacs 23, but is simpler. - -2012-04-13 Chong Yidong - - * customize.texi (Custom Themes): Also document load-theme etc. - -2012-04-12 Chong Yidong - - * customize.texi (Applying Customizations): - (Custom Themes): New nodes. - - * display.texi (Defining Faces): Reference custom-set-faces. - - * modes.texi (Defining Minor Modes, Defining Minor Modes): - * os.texi (Startup Summary): Copyedits. - -2012-04-12 Glenn Morris - - * loading.texi (Loading Non-ASCII): "unibyte:" can also be at the end. - -2012-04-10 Glenn Morris - - * strings.texi (Case Tables): - * objects.texi (General Escape Syntax): - * keymaps.texi (Key Sequences): Use @acronym with "ASCII". - - * buffers.texi, compile.texi, customize.texi, debugging.texi: - * display.texi, edebug.texi, eval.texi, help.texi, intro.texi: - * keymaps.texi, minibuf.texi, modes.texi, os.texi, processes.texi: - * text.texi: Use @file for buffers, per the Texinfo manual. - - * compile.texi (Compiler Errors): Add missing space in buffer name. - -2012-04-08 Chong Yidong - - * processes.texi (Query Before Exit): Remove obsolete function - process-kill-without-query (Bug#11190). - -2012-04-08 Glenn Morris - - * files.texi, frames.texi, loading.texi, os.texi, processes.texi: - Use @env for environment variables. - -2012-04-07 Glenn Morris - - * Makefile.in: Replace non-portable use of $< in ordinary rules. - -2012-04-06 Chong Yidong - - * minibuf.texi (Programmed Completion): Document metadata method. - (Completion Variables): Document completion-category-overrides. - -2012-04-05 Chong Yidong - - * anti.texi (Antinews): Rewrite for Emacs 23. - -2012-04-04 Chong Yidong - - * minibuf.texi (Programmed Completion): Remove obsolete variable - completion-annotate-function. - (Completion Variables): Rename from Completion Styles. Document - completion-extra-properties. Document completion-styles-alist - change. - (Reading File Names): minibuffer-local-filename-must-match-map is - not used anymore. - (Minibuffer Completion): Document completing-read-function. - (Completion in Buffers): completion-at-point-functions can return - properties recognized in completion-extra-properties. - - * display.texi (Delayed Warnings): New node. - - * os.texi (Notifications): Copyedits. - -2012-04-04 Glenn Morris - - * os.texi (Notifications): Copyedits. - -2012-04-03 Michael Albinus - - * os.texi (Terminal-Specific): Fix typo. - (Notifications): New section. - - * elisp.texi (Top): - * vol1.texi (Top): - * vol2.texi (Top): Add "Notifications" and "Dynamic Libraries" - menu entries. - -2012-04-01 Chong Yidong - - * files.texi (Kinds of Files): file-subdir-of-p renamed to - file-in-directory-p. - -2012-03-31 Glenn Morris - - * edebug.texi (Instrumenting Macro Calls): - Mention defining macros at instrumentation time. - (Edebug Options): Mention edebug-unwrap-results. - -2012-03-31 Eli Zaretskii - - * text.texi (Special Properties): Clarify the description of the - effect of integer values of the 'cursor' property on cursor - position. See the discussions in bug#11068 for more details and - context. - -2012-03-31 Glenn Morris - - * edebug.texi (Edebug Eval, Specification List, Edebug Options): - Copyedits. - -2012-03-30 Chong Yidong - - * display.texi (Image Formats): Add imagemagick type. - (Image Descriptors): Mention how they are used. - (ImageMagick Images): Clarify role of imagemagick-register-types. - (Character Display): Don't mention glyph tables. - (Display Tables): Use make-glyph-code in example. - (Glyphs): Avoid "simple glyph code" terminology. Note that glyph - tables are semi-obsolete. De-document create-glyph. - (Glyphless Chars): Note that display tables override this. - (Bidirectional Display): Copyedits. Introduce "bidirectional - reordering" terminology, and use it. - -2012-03-30 Glenn Morris - - * edebug.texi (Jumping): Give name of `i' binding. - -2012-03-28 Glenn Morris - - * searching.texi (Regular Expressions, Regexp Special): - (Regexp Backslash, Regexp Example, Regexp Functions, Regexp Search): - (Simple Match Data, Saving Match Data, Standard Regexps): Copyedits. - (Regexp Special): Mention collation. - Clarify char classes with an example. - (Regexp Functions): Mention regexp-opt is not guaranteed. - Mention regexp-opt-charset. - (Regexp Search): Recommend against looking-back. - (Search and Replace): Use Texinfo recommended quote convention. - Add more query-replace-map items. List multi-query-replace-map items. - -2012-03-27 Martin Rudalics - - * windows.texi (Window History): Describe new option - switch-to-visible-buffer. - -2012-03-27 Glenn Morris - - * searching.texi (String Search): Add xref to Emacs manual. - Copyedits. Mention the function word-search-regexp. - (Searching and Case): Add xref to Emacs manual. Copyedits. - - * processes.texi (Network Servers): Standardize apostrophe usage. - - * os.texi (System Environment): Copyedits. Remove some examples - that do not seem useful. Mention setenv third arg. - tty-erase-char does not seem to be nil under a window-system. - (User Identification): Copyedits. - Remove some examples that do not seem useful. - -2012-03-26 Glenn Morris - - * os.texi (Startup Summary): Copyedits. Fix startup screen logic. - (Init File): Copyedits. - (Command-Line Arguments): Copyedits. Do not mention argv alias. - (Killing Emacs): Copyedits. - (Suspending Emacs): Copyedits. Mention not very relevant with GUIs. - Shorten the example, use more standard shell prompts. - -2012-03-25 Chong Yidong - - * display.texi (Fringes): Note that fringes are shown on graphical - displays only. - (Fringe Size/Pos, Fringe Bitmaps, Making Buttons): Clarifications. - (Replacing Specs): Clarify example. - (Manipulating Buttons): Note that button-at can return a marker. - (Buttons): Minor rewrite. - (Character Display): New node. Consolidate all character display - related nodes into its subsections. - (Usual Display): Character 127 is also affected by ctl-arrow. - (Display Tables): Improve example. - -2012-03-22 Glenn Morris - - * strings.texi (Text Comparison): Mention string-prefix-p. - -2012-03-21 Chong Yidong - - * display.texi (The Echo Area): Add xref to Output Streams. - (Displaying Messages): Improve doc of message. - (Echo Area Customization, Invisible Text): Copyedits. - (Invisible Text): Mention that spec comparison is done with eq. - (Width): Improve doc of char-width. - (Faces): Recommend using symbol instead of string for face name. - Minor clarifications. - (Defining Faces): Copyedits. Update face example. - (Attribute Functions): Mark set-face-foreground etc as commands. - (Face Remapping): Mention text-scale-adjust. Clarify - face-remapping-alist and related docs. - (Face Functions): Don't document make-face or copy-face. - -2012-03-20 Chong Yidong - - * display.texi (Forcing Redisplay): Various rewrites to reflect - new value of redisplay-dont-pause. - (Truncation): Copyedits. - -2012-03-20 Glenn Morris - - * os.texi (Startup Summary): Don't mention initial-buffer-choice = t. - Add summary table of some relevant command-line options. - -2012-03-18 Chong Yidong - - * internals.texi (Building Emacs, Garbage Collection): Copyedits. - (Writing Emacs Primitives): Re-organize discussion of functions - with variable Lisp arguments are handled. Delete an obsolete - remark, previously tagged as FIXME. - - * os.texi (Idle Timers): Minor clarification. - (Idle Timers): Link to Time of Day for description of time list. - -2012-03-18 Glenn Morris - - * os.texi (System Interface): Flow control was removed. - (Startup Summary): General update. - (Init File): Don't mention compiling it. - -2012-03-17 Chong Yidong - - * os.texi (Startup Summary): Mention package loading. - (Init File): Don't refer to .emacs in section title. Copyedits. - (Terminal-Specific): Give a realistic example. - (Command-Line Arguments): Reference Entering Emacs instead of - repeating the spiel about not restarting Emacs. - (Time of Day): Discuss time representation at beginning of node. - (Sound Output): Copyedits. - - * package.texi (Packaging Basics): Document package-initialize. - -2012-03-17 Eli Zaretskii - - * frames.texi (Initial Parameters): Add an index entry for - minibuffer-only frame. - -2012-03-16 Glenn Morris - - * modes.texi (Major Mode Conventions): Mention the strange - relationship between View mode and special modes. (Bug#10650) - -2012-03-11 Chong Yidong - - * windows.texi (Window Configurations): save-window-excursion is - now a macro. - - * display.texi (Temporary Displays): with-output-to-temp-buffer is - now a macro. - - * text.texi (Fields): Minor copyedit. - -2012-03-10 Eli Zaretskii - - * strings.texi (String Basics): - * sequences.texi (Sequence Functions): Mention that `length' is - not appropriate for computing the string width on display; add a - cross-reference to the description of `string-width'. (Bug#10978) - - * eval.texi (Autoloading): Minor change of wording. - -2012-03-10 Chong Yidong - - * loading.texi (Autoload): Explicitly state which forms are - processed specially (Bug#7783). - - * keymaps.texi (Mouse Menus): Describe non-toolkit behavior as the - non-default situation. Describe one-submenu exception (Bug#7695). - - * nonascii.texi (Character Properties): Copyedits. - -2012-03-08 Chong Yidong - - * text.texi (Mode-Specific Indent): Document new behavior of - indent-for-tab-command. Document tab-always-indent. - (Special Properties): Copyedits. - (Checksum/Hash): Improve secure-hash doc. Do not recommend MD5. - (Parsing HTML/XML): Rename from Parsing HTML. Update doc of - libxml-parse-html-region. - -2012-03-07 Glenn Morris - - * markers.texi (The Region): Briefly mention use-empty-active-region - and region-active-p. - (Overview of Markers): Reword garbage collection, add cross-ref. - (The Mark): Tiny clarification re command loop and activate-mark-hook. - -2012-03-07 Chong Yidong - - * text.texi (Buffer Contents): Don't duplicate explanation of - region arguments from Text node. Put doc of obsolete var - buffer-substring-filters back, since it is referred to. - (Low-Level Kill Ring): Yank now uses clipboard instead of primary - selection by default. - - * markers.texi (The Mark): Fix typo. - (The Region): Copyedits. - -2012-03-07 Glenn Morris - - * markers.texi (Overview of Markers): Copyedits. - (Creating Markers): Update approximate example buffer size. - (The Mark): Don't mention uninteresting return values. - -2012-03-05 Chong Yidong - - * positions.texi (Text Lines): Document count-words. - -2012-03-04 Chong Yidong - - * frames.texi (Frames): Remove little-used "terminal frame" and - "window frame" terminology. - (Frame Parameters, Font and Color Parameters, Initial Parameters) - (Size and Position, Visibility of Frames): Callers changed. - (Frames): Clarify which terminals in framep are graphical. - (Initial Parameters): --geometry is not the only option which adds - to initial-frame-alist. - (Position Parameters): Note that icon-left and icon-top are for - old window managers only. - (Size Parameters): Sizes are in characters even on graphical - displays. - (Management Parameters): Note that window-id and outer-window-id - can't really be changed, and that auto-raise isn't always obeyed. - (Cursor Parameters): Document cursor-type explicitly. - (Size and Position): The aliases set-screen-height and - set-screen-width have been deleted. - (Visibility of Frames): Mention "minimization". - - * os.texi (Startup Summary): Minor clarifications. - (Startup Summary, Suspending Emacs): Standardize on "text - terminal" terminology. - - * windows.texi (Basic Windows, Coordinates and Windows) - (Coordinates and Windows): - * display.texi (Refresh Screen, Line Height, Face Attributes) - (Overlay Arrow, Beeping, Glyphless Chars): Likewise. - -2012-03-04 Glenn Morris - - * abbrevs.texi: Small copyedits throughout. - (Abbrev Mode): Remove this section, folding it into the top-level. - (Abbrev Tables): Don't mention irrelevant return values. - (Abbrev Expansion): Add cross-ref for wrapper hooks. - (Standard Abbrev Tables): Emacs Lisp mode now has its own table. - (Abbrev Table Properties): Update nil :regexp description. - -2012-03-03 Glenn Morris - - * internals.texi: Change @appendix section commands to @section. - (Building Emacs): Say less about CANNOT_DUMP platforms. - Replace deleted eval-at-startup with custom-initialize-delay. - (Pure Storage): Small changes. - (Memory Usage): Copyedit. - (Writing Emacs Primitives): Update Fcoordinates_in_window_p and For - example definitions. Give examples of things with non-nil - interactive args. Mention eval_sub. Remove old info about - strings and GCPRO. Mention cus-start.el. - (Buffer Internals, Window Internals, Process Internals): - Misc small updates and fixes for fields. - - * tips.texi: Copyedits. - (Coding Conventions): Mention autoloads. - Combine partially duplicated macro items. Fix xref. - Refer to Library Headers for copyright notice. - (Programming Tips): edit-options is long-obsolete. - (Compilation Tips): Mention loading bytecomp for byte-compile props. - (Warning Tips): Mention declare-function. - (Documentation Tips): Remove old info. - (Comment Tips): Mention comment-dwim, not indent-for-comment. - (Library Headers): General update. - -2012-03-02 Glenn Morris - - * backups.texi (Reverting): Un-duplicate revert-buffer-in-progress-p, - and relocate entry. Mention buffer-stale-function. - - * elisp.texi, vol1.texi, vol2.texi: Standardize some menu entries. - - * hooks.texi (Standard Hooks): General update. - Put related hooks together. Add and remove items. - * commands.texi (Keyboard Macros): Remove cross-ref to Standard Hooks. - * modes.texi (Hooks): Tweak cross-ref description. - -2012-03-01 Michael Albinus - - * files.texi (Kinds of Files): The return value of file-equal-p is - unspecified, if FILE1 or FILE2 does not exist. - -2012-03-01 Glenn Morris - - * hooks.texi (Standard Hooks): Remove mode-specific hooks. - - * maps.texi (Standard Keymaps): General update. - Remove mode-specific maps, talk about the more general keymaps. - * help.texi (Help Functions): Add vindex for Helper-help-map. - * keymaps.texi (Active Keymaps): Minor rephrasing. - -2012-02-29 Glenn Morris - - * elisp.texi, vol1.texi, vol2.texi: Use "" quotes in menus. - -2012-02-28 Thierry Volpiatto - - * files.texi (Kinds of Files): Rename files-equal-p to file-equal-p. - Update changed behavior of file-subdir-of-p. - -2012-02-28 Glenn Morris - - * advice.texi, anti.texi, display.texi, elisp.texi: - * processes.texi, variables.texi, vol1.texi, vol2.texi: - Standardize possessive apostrophe usage. - - * locals.texi: Remove file. - * elisp.texi, vol1.texi, vol2.texi: Don't include locals.texi. - Remove menu entry. - * errors.texi, maps.texi: Adjust node pointers. - * internals.texi (Buffer Internals): Remove cross-refs to locals.texi. - * makefile.w32-in (srcs): - * Makefile.in (srcs): Remove locals.texi. - - * frames.texi (Mouse Position): Fix cross-ref. - -2012-02-27 Chong Yidong - - * buffers.texi (Creating Buffers): Clarify that - generate-new-buffer uses generate-new-buffer-names. - (Killing Buffers): Remove bogus example duplicating buffer-live-p. - - * files.texi (Directory Names): Index entry for file name abbreviations. - (Relative File Names, File Name Expansion): Refer to it. - (Locating Files): Move locate-user-emacs-file documentation to - Standard File Names. - (Standard File Names): Add locate-user-emacs-file; update examples. - -2012-02-26 Michael Albinus - - * files.texi (Magic File Names): Add files-equal-p and file-subdir-of-p. - -2012-02-26 Chong Yidong - - * files.texi (Kinds of Files): Improve documentation of - files-equal-p and file-subdir-of-p. - -2012-02-26 Glenn Morris - - * intro.texi (Acknowledgements): Small changes. - -2012-02-25 Glenn Morris - - * errors.texi: Don't try to list _all_ the error symbols. - Add circular-list, cl-assertion-failed, compression-error. - * elisp.texi, vol1.texi, vol2.texi: - * control.texi (Error Symbols): Tweak "Standard Errors" description. - -2012-02-25 Thierry Volpiatto - - * files.texi (files-equal-p, file-subdir-of-p): New, - add initial documentation. - -2012-02-25 Chong Yidong - - * files.texi (File Attributes): Document file-selinux-context. - (Changing Files): Link to it. - (Changing Files): Document set-file-selinux-context. - - * backups.texi (Making Backups): Return value of backup-buffer is - changed. Mention default value of backup-directory-alist. - (Rename or Copy): Note that backup-by-copying-when-mismatch is t. - (Auto-Saving): New minor mode behavior for auto-save-mode. - (Reverting): Add defvar for revert-buffer-in-progress-p. - - * searching.texi (Regexp Backslash): Add index entry (Bug#10869). - -2012-02-24 Glenn Morris - - * errors.texi (Standard Errors): Mention dbus-error. - For arith-error sub-classes, just use one cross-ref. - -2012-02-23 Alan Mackenzie - - * modes.texi (Defining Minor Modes): Document the new keyword - :after-hook. - -2012-02-21 Chong Yidong - - * files.texi (Files): Mention magic file names as arguments. - (Reading from Files): Copyedits. - (File Attributes): Mention how to change file modes. - (Changing Files): Use standard "file permissions" terminology. - Add xref to File Attributes node. - (Locating Files): Document locate-user-emacs-file. - (Unique File Names): Recommend against using make-temp-name. - -2012-02-19 Chong Yidong - - * help.texi (Documentation, Documentation Basics, Help Functions): - Minor clarifications. - (Accessing Documentation): Clarify what documentation-property is - for. Add xref to Keys in Documentation. - - * tips.texi (Documentation Tips): Don't recommend using * in - docstrings. - - * macros.texi (Defining Macros): - * modes.texi (Derived Modes): Say "documentation string" instead - of docstring. - -2012-02-18 Chong Yidong - - * modes.texi (Tabulated List Mode): New node. - (Basic Major Modes): Add xref to it. - - * processes.texi (Process Information): Mention Process Menu mode. - -2012-02-17 Chong Yidong - - * syntax.texi (Motion via Parsing): Doc fix for scan-lists. - -2012-02-17 Glenn Morris - - * hooks.texi (Standard Hooks): Fix cross-ref to Emacs manual. - -2012-02-16 Chong Yidong - - * syntax.texi (Syntax Tables, Syntax Descriptors) - (Syntax Table Functions): Copyedits. - (Syntax Basics): Don't repeat the material in the preceding node. - (Syntax Class Table): Use a table. - (Syntax Properties): Document syntax-propertize-function and - syntax-propertize-extend-region-functions. - (Motion via Parsing): Clarify scan-lists. Fix indentation. - (Parser State): Update for the new "c" comment style. Fix - description of item 7 (comment style). - - * modes.texi (Minor Modes): Update how mode commands should treat - arguments now. - (Mode Line Basics): Clarify force-mode-line-update. - (Mode Line Top): Note that the example is not realistic. - (Mode Line Variables, Mode Line Data, %-Constructs, Header Lines) - (Emulating Mode Line): Use "mode line" instead of "mode-line", and - "mode line construct" instead of "mode line specification". - (Syntactic Font Lock): Remove mention of obsolete variable - font-lock-syntactic-keywords. - (Setting Syntax Properties): Node deleted. - (Font Lock Mode): Note that Font Lock mode is a minor mode. - (Font Lock Basics): Note that syntactic fontification falls back - on `syntax-table'. - (Search-based Fontification): Emphasize that font-lock-keywords - should not be set directly. - (Faces for Font Lock): Avoid some confusing terminology. - (Syntactic Font Lock): Minor clarifications. Add xref to - Syntactic Font Lock node. - -2012-02-15 Chong Yidong - - * minibuf.texi (Basic Completion): Define "completion table". - Move completion-in-region to Completion in Buffers node. - (Completion Commands): Use "completion table" terminology. - (Completion in Buffers): New node. - - * modes.texi (Hooks): add-hook can be used for abnormal hooks too. - (Setting Hooks): Update minor mode usage example. - (Major Mode Conventions): Note that completion-at-point-functions - should be altered locally. Add xref to Completion in Buffers. - Remove duplicate tip about auto-mode-alist. - (Minor Modes): Rewrite introduction. - (Minor Mode Conventions): Copyedits. Don't recommend - variable-only minor modes since few minor modes are like that. - -2012-02-15 Glenn Morris - - * processes.texi (Network): Document open-network-stream :parameters. - -2012-02-14 Chong Yidong - - * keymaps.texi (Format of Keymaps): The CACHE component of keymaps - was removed on 2009-09-10. Update lisp-mode-map example. - (Inheritance and Keymaps): Minor clarification. - (Searching Keymaps): Remove out-of-place enumeration. - (Key Lookup): Remove unnecessary example (one was already given in - Format of Keymaps). - (Changing Key Bindings): Update suppress-keymap example. - (Menu Bar, Tool Bar): Copyedits. - (Tool Bar): Update tool-bar-map example. - -2012-02-12 Chong Yidong - - * debugging.texi (Debugger Commands): Continuing is now allowed - for errors. - -2012-02-11 Chong Yidong - - * display.texi (Fringe Indicators): Add xref to Fringe Bitmaps. - Move the list of standard bitmaps there. - (Fringe Cursors): Rewrite for clarity. - (Fringe Bitmaps): Consolidate the list of standard bitmaps here. - - * commands.texi (Command Overview): Mention read-key. - (Using Interactive, Interactive Call): Minor clarifications. - (Function Keys, Click Events): Avoid "input stream" terminology. - (Click Events): Add xref to Window Sizes and Accessing Mouse. - Clarify column and row components. - (Accessing Mouse): Add xref to Click Events. Minor fixes. - (Special Events): Copyedits. - - * streams.texi (Input Streams): De-document get-file-char. - (Output Variables): Don't refer to old backquote syntax. - - * debugging.texi (Debugging): Copyedits. Describe testcover, ERT. - (Error Debugging): Note that debug-ignored-errors overrides list - values of debug-on-error too. Add xref to Signaling Errors. Note - that debug-on-signal is not customizable. Mention - condition-case-unless-debug. - (Compilation Errors): Node deleted. - - * compile.texi (Compiler Errors): Move a paragraph here from - deleted node Compilation Errors. - -2012-02-10 Leo Liu - - * control.texi (Handling Errors): Change condition-case-no-debug - to condition-case-unless-debug. - -2012-02-10 Chong Yidong - - * advice.texi (Defining Advice): Clarify ad-unadvise. - (Activation of Advice): Specifying the ACTIVATE flag in defadvice - is not abnormal. - (Advising Primitives): Node deleted; ad-define-subr-args has been - removed. - - * compile.texi (Speed of Byte-Code): Use float-time in example. - (Compilation Functions): Note that the log uses Compilation mode. - Don't discuss the contents of byte-code function object here. - (Compilation Functions): De-document internal function byte-code. - (Docs and Compilation): Minor clarifications. - - * objects.texi (Byte-Code Type): Add xref to Byte-Code Function - Objects. - -2012-02-10 Glenn Morris - - * text.texi (Checksum/Hash): Rename node from MD5 Checksum. - Mention secure-hash. - * elisp.texi, vol1.texi, vol2.texi: Update menu entry. - -2012-02-10 Chong Yidong - - * loading.texi (Loading): Don't emphasize "library" terminology. - (Library Search): load-path is not a user option. Mention role of - -L option and packages. Improve examples. - (Loading Non-ASCII): Don't mention unibyte Emacs, which is - obsolete. - (Autoload): Minor clarifications. - -2012-02-10 Glenn Morris - - * files.texi (Magic File Names): Tweak remote-file-name-inhibit-cache. - - * modes.texi (Basic Major Modes): Mention tabulated-list-mode. - -2012-02-08 Glenn Morris - - * loading.texi (Named Features): Update the require example. - -2012-02-07 Glenn Morris - - * modes.texi (Defining Minor Modes): - Expand on args of defined minor modes. - -2012-02-07 Chong Yidong - - * variables.texi (Creating Buffer-Local): Minor clarification - to buffer-local-variables doc (Bug#10715). - -2012-02-07 Glenn Morris - - * display.texi (ImageMagick Images): General update. - Move most details of imagemagick-render-type to the variable's doc. - -2012-02-06 Glenn Morris - - * keymaps.texi (Tool Bar): Mention separators. - (Inheritance and Keymaps): - Mention make-composed-keymap and multiple inheritance. - - * modes.texi (Running Hooks): Mention run-hook-wrapped. - - * control.texi (Handling Errors): - Mention condition-case-no-debug and with-demoted-errors. - -2012-02-05 Chong Yidong - - * customize.texi (Common Keywords): Minor clarifications. - Document custom-unlispify-remove-prefixes. - (Variable Definitions): Backquotes in defcustom seem to work fine - now. Various other copyedits. - (Simple Types): Copyedits. Document color selector. - (Composite Types): Copyedits. - (Splicing into Lists): Clarifications. - - * eval.texi (Backquote): Move from macros.texi. - - * macros.texi (Expansion): Minor clarification. - (Backquote): Move node to eval.texi. - (Defining Macros): Move an example from Backquote node. - (Argument Evaluation): No need to mention Pascal. - (Indenting Macros): Add xref to Defining Macros. - -2012-02-05 Glenn Morris - - * debugging.texi (Error Debugging): Mention debug-on-event default. - -2012-02-04 Glenn Morris - - * backups.texi (Reverting): Mention revert-buffer-in-progress-p. - - * debugging.texi (Error Debugging): Mention debug-on-event. - * commands.texi (Misc Events): Mention sigusr1,2 and debugging. - - * modes.texi (Running Hooks): Try to clarify with-wrapper-hook. - - * text.texi (Buffer Contents): - Update filter-buffer-substring description. - -2012-02-04 Chong Yidong - - * functions.texi (What Is a Function): Add closures. Mention - "return value" terminology. Add xref for command-execute. Remove - unused "keystroke command" terminology. - (Lambda Expressions): Give a different example than in the - following subsection. Add xref to Anonymous Functions. - (Function Documentation): Remove gratuitous markup. - (Function Names): Move introductory text to `What Is a Function'. - (Defining Functions): Fix defun argument spec. - (Anonymous Functions): Document lambda macro explicitly. Mention - effects on lexical binding. - (Function Cells): Downplay direct usage of fset. - (Closures): New node. - (Inline Functions): Remove "open-code" terminology. - (Declaring Functions): Minor tweak; .m is not C code. - - * variables.texi (Variables): Don't refer to "global value". - (Local Variables, Void Variables): Copyedits. - (Lexical Binding): Minor clarification of example. - (File Local Variables): Mention :safe and :risky defcustom args. - (Lexical Binding): Add xref to Closures node. - -2012-02-04 Glenn Morris - - * minibuf.texi (High-Level Completion): Updates for read-color. - -2012-02-03 Glenn Morris - - * display.texi (GIF Images): Mention animation. - Remove commented-out old example of animation. - (Animated Images): New subsection. - * elisp.texi (Top): - * vol1.texi (Top): - * vol2.texi (Top): Add Animated Images menu entry. - - * display.texi (Image Formats): Remove oddly specific information - on versions of image libraries. - (GIF Images, TIFF Images): Minor rephrasing. - -2012-02-02 Glenn Morris - - * processes.texi (Synchronous Processes): - Mention call-process's :file gets overwritten. - - * commands.texi (Reading One Event): - * help.texi (Help Functions): Document read-char-choice. - - * hooks.texi (Standard Hooks): - * modes.texi (Keymaps and Minor Modes): - * text.texi (Commands for Insertion): Document post-self-insert-hook. - - * hooks.texi (Standard Hooks): Add prog-mode-hook. - - * hooks.texi (Standard Hooks): - * modes.texi (Major Mode Conventions, Mode Hooks): - Document change-major-mode-after-body-hook. - -2012-02-01 Glenn Morris - - * modes.texi (Defining Minor Modes): - Mention disabling global minor modes on a per-major-mode basis. - -2012-01-31 Chong Yidong - - * syntax.texi (Parsing Expressions): Clarify intro (Bug#10657). - (Parser State): Remove unnecessary statement (Bug#10661). - - * eval.texi (Intro Eval): Add footnote about "sexp" terminology. - -2012-01-31 Glenn Morris - - * modes.texi (Defining Minor Modes): - Document define-minor-mode's new :variable keyword. - -2012-01-29 Chong Yidong - - * syntax.texi (Syntax Class Table): Tweak description of newline - char syntax (Bug#9619). - - * numbers.texi (Predicates on Numbers): Fix wholenump/natnump - description (Bug#10189). - -2012-01-29 Glenn Morris - - * files.texi (Changing Files): Document SELinux support. - - * windows.texi (Window Sizes): Fix typo. - -2012-01-28 Chong Yidong - - * display.texi (Fringe Indicators): Clarify fringe-indicator-alist - doc (Bug#8568). - - * frames.texi (Input Focus): Add NORECORD arg to - select-frame-set-input-focus. Clarify its role in select-frame. - - * text.texi (Transposition): We don't use transpose-region as an - internal subroutine (Bug#3249). - - * modes.texi (Example Major Modes): Update Lisp example code to - current sources. Delete the old non-derived-major-mode example, - which has diverged badly from current sources. - -2012-01-27 Glenn Morris - - * makefile.w32-in (texinputdir): Fix (presumed) typo. - (VERSION, manual): Remove, unused. - -2012-01-27 Chong Yidong - - * commands.texi (Command Overview): Minor clarification (Bug#10384). - -2012-01-26 Chong Yidong - - * searching.texi (String Search): Document negative repeat count - (Bug#10507). - -2012-01-26 Glenn Morris - - * variables.texi (Using Lexical Binding): - Mention that lexical-binding should be set in the first line. - -2012-01-26 Lars Ingebrigtsen - - * macros.texi (Defining Macros): Don't claim that `declare' only - affects Edebug and indentation. - -2012-01-25 Lars Ingebrigtsen - - * macros.texi (Defining Macros): Slight `declare' fixup. - -2012-01-25 Glenn Morris - - * makefile.w32-in (texinputdir): - * Makefile.in (ENVADD): Add $emacsdir. (Bug#10603) - -2012-01-24 Chong Yidong - - * variables.texi (Variables, Local Variables, Void Variables): - Edit to make the descriptions less specific to dynamic binding. - (Local Variables): Default max-specpdl-size is now 1300. - (Defining Variables): Edits for lexical scoping. Delete - information about starting docstrings with *. De-document - user-variable-p. - (Tips for Defining): Remove an unimportant discussion of quitting - in the middle of a load. - (Accessing Variables, Setting Variables): Discuss lexical binding. - (Variable Scoping): Rewrite. - (Scope, Extent, Impl of Scope): Nodes deleted. - (Dynamic Binding): New node, with material from Scope, Extent, and - Impl of Scope nodes. - (Dynamic Binding Tips): Rename from Using Scoping. - (Lexical Binding): Rewrite. - (Using Lexical Binding): Rename from Converting to Lexical - Binding. Convert to subsection. - - * customize.texi (Variable Definitions): Add custom-variable-p. - Move user-variable-p documentation here. - -2012-01-23 Chong Yidong - - * strings.texi (Text Comparison): Minor qualification. - - * lists.texi (Cons Cells): Copyedits. - (List Elements): Mention push. - (List Variables): Mention pop. - (Rings): Move to sequences.texi. - - * sequences.texi (Sequence Functions): Don't repeat the - introduction already given in the parent. - (Vectors): Copyedits. - (Rings): Move from lists.texi. Note that this is specific to the - ring package. - - * symbols.texi (Definitions, Symbol Components): Mention variable - scoping issues. - (Plists and Alists): Copyedits. - - * eval.texi (Intro Eval, Symbol Forms): Minor tweaks for - correctness with lexical scoping. - (Eval): Copyedits. - -2012-01-21 Chong Yidong - - * intro.texi (A Sample Function Description): Special notation - used for macros too. - - * objects.texi (Ctl-Char Syntax, Other Char Bits): Copyedits. - (Symbol Type): Add xref for keyword symbols. - (Sequence Type): Clarify differences between sequence types. - (Cons Cell Type): Add "linked list" index entry. - (Non-ASCII in Strings): Copyedits. - (Equality Predicates): Symbols with same name need not be eq. - - * numbers.texi (Float Basics): Document isnan, copysign, frexp and - ldexp. Move float-e and float-pi to Math Functions node. - -2012-01-21 Glenn Morris - - * modes.texi (Auto Major Mode): - * variables.texi (File Local Variables): - Mention inhibit-local-variables-regexps. - -2012-01-19 Martin Rudalics - - * windows.texi (Window Configurations): Rewrite references to - persistent window parameters. - (Window Parameters): Fix description of persistent window - parameters. - -2012-01-16 Juanma Barranquero - - * windows.texi (Window Parameters): Use @pxref. - -2012-01-16 Martin Rudalics - - * windows.texi (Window Configurations, Window Parameters): - Describe persistent window parameters. - -2011-12-27 Stefan Monnier - - * variables.texi (Creating Buffer-Local): Warn against misuses of - make-variable-buffer-local (bug#10258). - -2012-01-07 Lars Magne Ingebrigtsen - - * macros.texi (Defining Macros): Document `doc-string' (bug#9668). - -2012-01-06 Chong Yidong - - * variables.texi (Directory Local Variables): Document - hack-dir-local-variables-non-file-buffer. - -2012-01-06 Glenn Morris - - * maps.texi (Standard Keymaps): Refer to Info-edit by name - rather than by keybinding. - -2011-12-29 Juanma Barranquero - - * frames.texi (Font and Color Parameters): Add @pxref. - -2011-12-29 Daniel Colascione - - * frames.texi (Font and Color Parameters): - Document w32 font backends (bug#10399). - -2011-12-28 Paul Eggert - - * files.texi (File Attributes, Changing Files): - Use a more-natural notation for octal numbers. - -2011-12-23 Juanma Barranquero - - * variables.texi (Variables with Restricted Values): - Change reference to variable (bug#10354). - -2011-12-13 Martin Rudalics - - * windows.texi (Splitting Windows): Use t instead of non-nil - when describing window-combination-resize. - -2011-12-05 Stefan Monnier - - * text.texi (Special Properties): Warn against `intangible' properties - (bug#10222). - -2011-11-26 Eli Zaretskii - - * display.texi (Truncation): - * text.texi (Special Properties): Describe what a stretch-glyph is - instead of using that term without explanation. Make the - cross-references more accurate. - - * display.texi (Usual Display): Update the description, - cross-references, and indexing related to display of control - characters and raw bytes. - -2011-11-25 Martin Rudalics - - * windows.texi (Splitting Windows): Fix description of - window-combination-limit. Suggested by Eli Zaretskii. - -2011-11-23 Chong Yidong - - * windows.texi (Window Sizes): Move window-top-line, - window-left-column, and window-*-pixel-edges to Coordinates and - Windows node. - (Coordinates and Windows): Restore window-edges doc. - -2011-11-21 Martin Rudalics - - * windows.texi (Windows and Frames, Splitting Windows): - Fix typos. - -2011-11-21 Chong Yidong - - * windows.texi (Splitting Windows): Fix error in documentation of - window-combination-limit. - (Cyclic Window Ordering): Minor fixes to next-window, - one-window-p, and get-lru-window docs. Don't document - window-list-1. - (Buffers and Windows): Copyedits. - (Choosing Window): Document special handling of special-display-*. - (Choosing Window Options): Fix display-buffer-reuse-frames doc. - Don't document even-window-heights, which is going away. - Clarify which options are obeyed by which action functions. - -2011-11-20 Stefan Monnier - - * display.texi (Invisible Text): Clarify point adjustment (bug#10072). - -2011-11-20 Martin Rudalics - - * windows.texi (Resizing Windows, Splitting Windows): - Remove term "status" when talking about combination limits. - -2011-11-20 Juanma Barranquero - - * compile.texi (Compiler Errors): - * help.texi (Help Functions): Fix typos. - -2011-11-19 Chong Yidong - - * windows.texi (Splitting Windows): Clarify role of window - parameters in split-window. Shorten the example. - (Deleting Windows): Rewrite intro to handle internal windows. - Fix delete-windows-on doc. - (Selecting Windows): Copyedits. - -2011-11-17 Martin Rudalics - - * windows.texi (Resizing Windows, Splitting Windows) - (Deleting Windows): Use term window-combination-resize instead - of window-splits. - -2011-11-16 Martin Rudalics - - * windows.texi (Resizing Windows, Splitting Windows): - Rename occurrences of window-nest to window-combination-limit. - -2011-11-14 Juanma Barranquero - - * intro.texi (Lisp History): Fix typo. - -2011-11-12 Martin Rudalics - - * windows.texi (Splitting Windows, Deleting Windows): - Remove references to splits status of windows. - -2011-11-10 Glenn Morris - - * buffers.texi (Read Only Buffers): Expand a bit on why - toggle-read-only should only be used interactively. (Bug#7292) - -2011-11-09 Chong Yidong - - * windows.texi (Window Sizes): Document window-pixel-edges, - window-inside-pixel-edges, window-absolute-pixel-edges, and - window-inside-absolute-pixel-edges. - (Resizing Windows): shrink-window-if-larger-than-buffer works on - non-full-width windows. - -2011-11-09 Martin Rudalics - - * windows.texi (Resizing Windows): Rewrite documentation of - window-resizable. - -2011-11-09 Chong Yidong - - * windows.texi (Splitting Windows): Simplify example. - -2011-11-08 Chong Yidong - - * windows.texi (Window Sizes): Copyedits. Document - window-text-height. Remove window-min-height and window-min-width - discussion, referring instead to Emacs manual. - (Splitting Windows, Resizing Windows): Add xref to Emacs manual. - (Resizing Windows): Simplify introduction. Don't document - enlarge-window, shrink-window, enlarge-window-horizontally, and - shrink-window-horizontally; they are no longer preferred for - calling from Lisp, and are already documented in the Emacs manual. - -2011-11-07 Glenn Morris - - * windows.texi (Choosing Window): Fix keybinding typo. - -2011-11-07 Martin Rudalics - - * windows.texi (Resizing Windows, Splitting Windows) - (Window Configurations): Use "child window" instead of - "subwindow". - -2011-11-06 Chong Yidong - - * windows.texi (Basic Windows): Clarify various definitions. - Treat window-normalize-* as internal; don't document them. - (Windows and Frames): Various clarifications, e.g. non-live - windows also belong to frames. Fix window-list description. - Simplify window nesting example. - (Splitting Windows, Window Configurations): - Use split-window-below. - -2011-11-04 Eli Zaretskii - - * windows.texi (Window Sizes): Mention in the doc string that the - return values of `window-body-height' and `window-body-width' are - in frame's canonical units. (Bug#9949) - -2011-10-30 Martin Rudalics - - * windows.texi (Windows and Frames): Remove "iso-" infix from - documentation of window-iso-combined-p. - -2011-10-26 Chong Yidong - - * modes.texi (Running Hooks): Document with-wrapper-hook. - -2011-10-18 Chong Yidong - - * display.texi (Glyphless Chars): New node. - -2011-10-13 Chong Yidong - - * text.texi (Yanking): Document yank-excluded-properties. - - * package.texi (Packaging Basics): The commentary should say how - to begin using the package. - -2011-10-11 Martin Rudalics - - * windows.texi (Deleting Windows): Mention which window gets - selected when deleting the selected window. - -2011-10-09 Martin Rudalics - - * buffers.texi (The Buffer List): Describe how bury-buffer deals - with the selected window. - * windows.texi (Buffers and Windows): Reformulate text on how - replace-buffer-in-windows deals with a window. - (Quitting Windows): Describe how quit-window deals with a - standalone frame. Describe new option frame-auto-hide-function. - -2011-10-08 Glenn Morris - - * symbols.texi (Other Plists): Markup fix. (Bug#9702) - - * positions.texi (Excursions): Update warning message. - -2011-10-05 Chong Yidong - - * display.texi (Low-Level Font, Face Attributes, Font Lookup): - Fix Emacs manual xref (Bug#9675). - -2011-10-01 Chong Yidong - - * windows.texi (Textual Scrolling): Document scroll-up-command, - scroll-down-command, scroll-error-top-bottom, and the - scroll-command symbol property. - (Display Action Functions): Fix description of - display-buffer-pop-up-window. - -2011-09-28 Juanma Barranquero - - * windows.texi (Splitting Windows): Fix typos. - -2011-09-25 Martin Rudalics - - * windows.texi (Windows and Frames, Display Action Functions) - (Switching Buffers): Fix some typos. - (Buffers and Windows): Remove reference to window-auto-delete. - Reword description of replace-buffer-in-windows. - (Window History): Fix some typos and refer to frame local buffer - list. - (Quitting Windows): New node. - (Window Configurations): Add descriptions of window-state-get - and window-state-put. - (Window Parameters): Describe variable ignore-window-parameters. - Sketch some window parameters currently in use. - * elisp.texi (Top): Update node listing. - -2011-09-25 Chong Yidong - - * windows.texi (Display Action Functions) - (Choosing Window Options): New nodes. - -2011-09-24 Chong Yidong - - * windows.texi (Window History): New node. Move text here from - Buffers and Windows. - (Switching Buffers): Rename from Displaying Buffers, since we - don't document display-buffer here; callers changed. - Document FORCE-SAME-WINDOW arg to switch-to-buffer and - switch-to-buffer-other-frame. Delete duplicate - replace-buffer-in-windows doc. - (Choosing Window): Document display actions. - -2011-09-24 Eli Zaretskii - - * display.texi (Forcing Redisplay): Update the description of - redisplay-dont-pause due to change in the default value. - -2011-09-23 Martin Rudalics - - * frames.texi (Frames and Windows): Move section and rename to - Windows and Frames in windows.texi. - * windows.texi (Windows): Restructure. - (Basic Windows): Rewrite. Explain live and internal windows and - normalization functions. - (Windows and Frames): Move section here from frames.texi. - Describe subwindows, window combinations, window tree, and - corresponding functions including window-list here. - (Window Sizes): Rename section from Size of Window and move it - up in chapter. Describe total and body sizes and the - corresponding functions. Explain new semantics of - window-min-height/-width. - (Resizing Windows): Move section up in chapter. Describe new - resize functions. - (Splitting Windows): Describe new behavior of split-window, - split-window-above-each-other and split-window-side-by-side. - Provide examples. Describe window-nest and window-splits - options. - (Deleting Windows): Minor rewrite. - (Selecting Windows): Minor rewrite. - Describe frame-selected-window and set-frame-selected-window here. - (Cyclic Window Ordering): Minor rewrite. - Describe window-list-1. - (Buffers and Windows): Rewrite. Explain a window's previous and - next buffers and the corresponding functions. - (Window Tree): Merge into Windows and Frames section. - * elisp.texi (Top): Update node listings for frames and windows - sections. - -2011-09-21 Stefan Monnier - - * display.texi (Face Functions): `face-list' returns faces (bug#9564). - -2011-09-19 Lars Magne Ingebrigtsen - - * errors.texi (Standard Errors): Remove apparent placeholder text - (bug#9491). - -2011-09-18 Chong Yidong - - * frames.texi (Management Parameters): Fix description of - icon-type parameter. - -2011-09-17 Chong Yidong - - * tips.texi (Key Binding Conventions): Don't bind a key sequence - ending in C-g. Suggested by Edward O'Connor. - -2011-09-17 Eli Zaretskii - - * numbers.texi (Integer Basics): Add indexing for - most-positive-fixnum and most-negative-fixnum. (Bug#9525) - -2011-09-14 Dani Moncayo (tiny change) - - * lists.texi (Sets And Lists): Fix typo. (Bug#9393) - -2011-09-11 Juanma Barranquero - - * processes.texi (Network Servers): Clarify what the process - buffer is used for (bug#9233). - -2011-08-30 Dani Moncayo (tiny change) - - * lists.texi (Building Lists): Fix typo. - -2011-08-30 Chong Yidong - - * display.texi (Basic Faces): New node. Document new faces. - - * modes.texi (Major Mode Conventions): Move some text there. - (Mode Help): Remove major-mode var, duplicated in Major Modes. - -2011-08-29 Chong Yidong - - * modes.texi (Basic Major Modes): New node. Callers updated. - (Major Modes): Document fundamental-mode and major-mode. - (Major Mode Basics): Node deleted; text moved to Major Modes. - (Derived Modes): Document derived-mode-p. - -2011-08-28 Chong Yidong - - * files.texi (Changing Files, Create/Delete Dirs): Document new - arguments for delete-file, delete-directory, and copy-directory. - (Visiting Functions): Remove view-file; it is documented in the - Emacs manual. - - * frames.texi (Layout Parameters): The defaults for the - menu-bar-lines and tool-bar-lines parameters depend on the mode. - - * display.texi (Progress): Document spinner functionality. - - * os.texi (Killing Emacs): Note that kill-emacs can be called by - operating system signals. Refer to save-buffers-kill-terminal - instead of save-buffers-kill-emacs. - - * objects.texi (Symbol Type): Document ## print representation. - -2011-08-25 Eli Zaretskii - - * display.texi (Specified Space): Mention that `space' specs - influence bidi reordering. - (Bidirectional Display): Explain how to use `(space . PROPS)' for - separating fields with bidirectional content. - -2011-08-24 Eli Zaretskii - - * display.texi (Bidirectional Display): Document return value in - buffers that are not bidi-reordered for display, and in unibyte - buffers. - -2011-08-23 Eli Zaretskii - - * nonascii.texi (Character Properties): Document the values for - unassigned codepoints. - -2011-08-18 Eli Zaretskii - - * nonascii.texi (Character Properties): Document use of - `bidi-class' and `mirroring' properties as part of reordering. - Provide cross-references to "Bidirectional Display". - - * display.texi (Bidirectional Display): Document the pitfalls of - concatenating strings with bidirectional content, with possible - solutions. Document bidi-string-mark-left-to-right. - Mention paragraph direction in modes that inherit from prog-mode. - Document use of `bidi-class' and `mirroring' properties as part of - reordering. - -2011-08-16 Eli Zaretskii - - * modes.texi (Major Mode Conventions): Improve the documentation - of `mode-class' `special' modes. - - * nonascii.texi (Character Properties): Document the `mirroring' - property. Add index entries. - - * syntax.texi (Categories): Add an example of defining a new - category and category table. - - * searching.texi (Regexp Backslash): Document how to display - existing categories. Mention the possibility of adding - categories, and add an xref to where this is described. Add an - index entry. - -2011-08-09 Chong Yidong - - * text.texi (Special Properties): - * display.texi (Overlay Properties): Note that mouse-face cannot - change the text size (Bug#8530). - -2011-08-08 Chong Yidong - - * os.texi (Time of Day): Remove set-time-zone-rule, and recommend - using setenv instead. - -2011-07-28 Eli Zaretskii - - * display.texi (Bidirectional Display): Document the fact that - bidi-display-reordering is t by default. - -2011-07-23 Eli Zaretskii - - * display.texi (Bidirectional Display): New section. - -2011-07-16 Lars Magne Ingebrigtsen - Tim Cross (tiny change) - Glenn Morris - - * keymaps.texi (Toolkit Differences): New node. (Bug#8176) - -2011-07-15 Andreas Schwab - - * help.texi (Keys in Documentation): Revert last change. - -2011-07-15 Lars Magne Ingebrigtsen - - * help.texi (Keys in Documentation): Clarify that \= only quotes - the next character, and doesn't affect longer sequences in - particular (bug#8935). - - * debugging.texi (Using Debugger): - Mention @code{eval-expression-debug-on-error} (bug#8549). - -2011-07-14 Eli Zaretskii - - * display.texi (Other Display Specs): Document that `left-fringe' - and `right-fringe' display specifications are of the "replacing" - kind. - -2011-07-14 Lars Magne Ingebrigtsen - - * help.texi (Documentation Basics): Add a link to the Function - Documentation node (bug#6580). - -2011-07-13 Lars Magne Ingebrigtsen - - * keymaps.texi (Menu Bar): Mention :visible and :enable - (bug#6344). Text by Drew Adams. - - * modes.texi (Running Hooks): Mention buffer-local hook variables - (bug#6218). - - * objects.texi (General Escape Syntax): "a with grave accent" is - ?xe0, not ?x8e0 (bug#5259). - -2011-07-12 Chong Yidong - - * display.texi (Face Attributes, Font Selection): Add references - to the Fonts node in the Emacs manual (Bug#4178). - -2011-07-12 Chong Yidong - - * display.texi (Window Systems): `window-system' is - terminal-local. - - * frames.texi (Frame Parameters, Parameter Access): Don't mention - frame-local variables. - - * variables.texi (Buffer-Local Variables): Don't mention obsolete - frame-local variables. - (Frame-Local Variables): Node deleted. - - * elisp.texi (Top): Update node listing. - -2011-07-12 Lars Magne Ingebrigtsen - - * elisp.texi: Change "inferiors" to "subnodes" in three places - (bug#3523). - -2011-07-11 Chong Yidong - - * frames.texi (Window System Selections): Discussion of - x-select-enable-clipboard moved to Emacs manual. - -2011-07-11 Deniz Dogan - - * commands.texi (Prefix Command Arguments): Remove excessive - apostrophe. - -2011-07-11 Lars Magne Ingebrigtsen - - * syntax.texi (Syntax Descriptors): Clarify that the ". 23" syntax - description is a string (bug#3313). - - * frames.texi (Display Feature Testing): Try to explain what all - the visual classes mean (bug#3042). - -2011-07-10 Lars Magne Ingebrigtsen - - * modes.texi (Mode Line Variables): Document `mode-line-remote' - and `mode-line-client' (bug#2974). - - * text.texi (Insertion): Clarify marker movements (bug#1651). - Text from Drew Adams. - -2011-07-07 Lars Magne Ingebrigtsen - - * text.texi (Special Properties): Clarify the format of `face' - (bug#1375). - - * commands.texi (Interactive Call): Add a `call-interactively' - example (bug#1010). - -2011-07-06 Lars Magne Ingebrigtsen - - * functions.texi (Calling Functions): Link to the "Interactive - Call" node (bug#1001). - -2011-07-06 Chong Yidong - - * customize.texi (Composite Types): Move alist and plist to here - from Simple Types (Bug#7545). - - * elisp.texi (Top): Update menu description. - - * display.texi (Face Attributes): Document negative line widths - (Bug#6113). - -2011-07-03 Tobias C. Rittweiler (tiny change) - - * searching.texi (Match Data): Note that match data can be - overwritten by most functions (bug#2499). - -2011-07-03 Lars Magne Ingebrigtsen - - * strings.texi (Formatting Strings): Clarify what the "-" and "0" - flags mean (bug#6659). - - * functions.texi (What Is a Function): Document the autoload - object (bug#6496). - -2011-07-02 Lars Magne Ingebrigtsen - - * customize.texi (Variable Definitions): Clarify that SETFUNCTION - is only used in the Customize user interface (bug#6089). - - * display.texi (Showing Images): Mention the point of sliced - images (bug#7836). - -2011-07-02 Eli Zaretskii - - * variables.texi (Defining Variables, Void Variables) - (Constant Variables): Fix incorrect usage of @kindex. - -2011-07-02 Lars Magne Ingebrigtsen - - * variables.texi (Defining Variables): Add an index entry for - `set-variable' (bug#7262). - (Defining Variables): Use @findex for functions. - - * frames.texi (Basic Parameters): Document the `explicit-name' - parameter (bug#6951). - - * customize.texi (Type Keywords): Clarify that :value provides a - default value for all types (bug#7386). - - * streams.texi (Output Functions): Document `pp'. - -2011-06-25 Chong Yidong - - * keymaps.texi (Searching Keymaps): - * display.texi (Overlay Properties): Fix errors in 2011-05-29 - change. Suggested by Johan BockgÃ¥rd. - -2011-06-15 Chong Yidong - - * text.texi (Special Properties): Clarify role of font-lock-face. - -2011-06-15 Lars Magne Ingebrigtsen - - * processes.texi (Process Information): Rename `process-alive-p' - to `process-live-p' for consistency with other `-live-p' functions. - -2011-06-03 Paul Eggert - - Document wide integers better. - * files.texi (File Attributes): Document ino_t values better. - ino_t values no longer map to anything larger than a single cons. - * numbers.texi (Integer Basics, Integer Basics, Arithmetic Operations): - (Bitwise Operations): - * objects.texi (Integer Type): Use a binary notation that is a bit easier - to read, and that will port better if 62-bits becomes the default. - Fix or remove incorrect examples. - * os.texi (Time Conversion): Document time_t values better. - -2011-05-31 Lars Magne Ingebrigtsen - - * processes.texi (Process Information): - Document `process-alive-p'. - -2011-05-29 Chong Yidong - - * help.texi (Accessing Documentation): - * display.texi (Pixel Specification): - * processes.texi (Serial Ports, Serial Ports): - * nonascii.texi (Character Properties, Default Coding Systems): - * text.texi (Changing Properties, Special Properties): - * windows.texi (Window Start and End): - * modes.texi (SMIE Indentation Example, SMIE Tricks): - * keymaps.texi (Searching Keymaps, Tool Bar): - * minibuf.texi (Basic Completion): - * compile.texi (Eval During Compile): - * strings.texi (Formatting Strings): Tweaks to avoid overflowing - 7x9 paper in printed manual. - - * lists.texi (Sets And Lists): Fix misplaced text. - -2011-05-29 Chong Yidong - - * keymaps.texi (Remapping Commands): Emphasize that the keymap - needs to be active (Bug#8350). - -2011-05-28 Chong Yidong - - * minibuf.texi (Reading File Names): Clarify (Bug#8480). - - * tips.texi (Coding Conventions): Remove antediluvian filename - limit recommendation (Bug#8538). - -2011-05-27 Glenn Morris - - * modes.texi (Auto Major Mode): Update for set-auto-mode changes. - -2011-05-26 Glenn Morris - - * variables.texi (File Local Variables): - Update hack-local-variables `mode-only' return value. - Add some more details on what this function does in the other case. - -2011-05-19 Glenn Morris - - * lists.texi (Sets And Lists): Mention cl provides union etc. - -2011-05-19 Nix - - * windows.texi (Displaying Buffers): pop-to-buffer is not a command. - - * text.texi (Parsing HTML): Update for function name changes. - - * syntax.texi (Syntax Flags): Small fix. - - * keymaps.texi (Active Keymaps): Typo fix. - (Changing Key Bindings): Grammar fix. - - * frames.texi (Minibuffers and Frames): Grammar fix. - (Window System Selections): x-select-enable-clipboard now defaults to t. - - * customize.texi (Common Keywords): - * display.texi (Abstract Display): - * modes.texi (Auto-Indentation): - * nonascii.texi (Converting Representations): Typo fixes. - - * control.texi (Examples of Catch): Call it "goto" not "go to". - -2011-05-14 Eli Zaretskii - - * nonascii.texi (Character Properties): Fix inconsistencies with - implementation. - - * text.texi (Special Properties): Move @defvar's out of the - @table. (Bug#8652) - -2011-05-12 Glenn Morris - - * display.texi (Image Descriptors): Fix typo. (Bug#8495) - -2011-05-12 Stefan Monnier - - * modes.texi (Region to Refontify): Rename from "Region to Fontify". - (Multiline Font Lock): - * vol2.texi (Top): - * vol1.texi (Top): - * elisp.texi (Top): Update menu accordingly. - -2011-05-12 Drew Adams - - * modes.texi (Region to Fontify): Fix typo. - -2011-05-10 Jim Meyering - - * minibuf.texi: Fix typo "in in -> in". - -2011-05-06 Paul Eggert - - * numbers.texi (Integer Basics): Large integers are treated as floats. - -2011-04-30 Lars Magne Ingebrigtsen - - * processes.texi (Synchronous Processes): Document the (:file - "/file-name") syntax for `call-process'. - -2011-04-23 Juanma Barranquero - - * windows.texi (Choosing Window): Fix typo. - -2011-04-23 Chong Yidong - - * frames.texi (Layout Parameters): Note the difference between - querying and setting parameters for left-fringe and right-fringe - (Bug#6930). - -2011-03-21 Stefan Monnier - - * minibuf.texi (Basic Completion): Be a bit more precise about the - valid kinds of completion tables. - (Programmed Completion): Remove obsolete text about lambda expressions - not being valid completion tables. - -2011-03-19 Chong Yidong - - * positions.texi (Excursions): Explain the "save-excursion - defeated by set-buffer" warning. - - * buffers.texi (Current Buffer): Copyedits. Don't recommend using - save-excursion. Suggested by Uday S Reddy. - -2011-04-01 Stefan Monnier - - * variables.texi (Defining Variables): Mention the new meaning of `defvar'. - (Lexical Binding): New sub-section. - - * eval.texi (Eval): Discourage the use of `eval'. - Document its new `lexical' argument. - -2011-03-28 Stefan Monnier - - * commands.texi (Command Overview): `post-command-hook' is not reset to - nil any more. - -2011-03-19 Stefan Monnier - - * strings.texi (String Conversion): Don't mention - string-make-(uni|multi)byte (bug#8262). - * nonascii.texi (Converting Representations): Fix up range. - * keymaps.texi (Key Binding Commands): Update code point, avoid - "unibyte character" and remove mention of unibyte bindings. - -2011-03-10 Eli Zaretskii - - * modes.texi (Operator Precedence Grammars): Don't use characters - outside ISO-8859-1. - -2011-03-09 Eli Zaretskii - - * intro.texi (Acknowledgements): Convert to ISO-8859-1 encoding. - - * makefile.w32-in (MAKEINFO_OPTS): Add --enable-encoding. - -2011-03-08 Glenn Morris - - * Makefile.in (MAKEINFO_OPTS): Add --enable-encoding. - * intro.texi (Acknowledgements): Names to UTF-8. - * elisp.texi: Set documentencoding. - -2011-03-07 Chong Yidong - - * Version 23.3 released. - -2011-03-06 Chong Yidong - - * package.texi: Update index keywords. - (Package Archives): New node contents. Document package-x.el. - -2011-03-06 Juanma Barranquero - - * makefile.w32-in (srcs): Add package.texi. - -2011-03-06 Chong Yidong - - * package.texi (Packaging, Packaging Basics, Simple Packages) - (Multi-file Packages): Expand and clarify. - (Package Archives): Temporary placeholder node. - - * elisp.texi (Top): Update node listing. - - * Makefile.in (srcs): Add package.texi. - -2011-03-05 Chong Yidong - - * processes.texi (Synchronous Processes): Minor clarification - (Bug#8149). - -2011-03-03 Glenn Morris - - * files.texi (Truenames): Minor clarification. (Bug#2341) - -2011-03-01 Glenn Morris - - * variables.texi (Directory Local Variables): - Mention `(subdirs . nil)' alist element. - -2011-02-28 Glenn Morris - - * variables.texi (Directory Local Variables): Mention the optional - mtime argument of dir-locals-set-directory-class. (Bug#3577) - -2011-02-27 Chong Yidong - - * minibuf.texi (Minibuffer History): Clarify discussion of - minibuffer history lists (Bug#8085). - -2011-02-19 Eli Zaretskii - - * elisp.texi: Sync @dircategory with ../../info/dir. - - * files.texi (Visiting Functions): Document find-file-literally, - both the command and the variable. - - * variables.texi (Creating Buffer-Local): Explain the meaning of - permanent local variables. - - * files.texi (Visiting Functions): Document find-file-literally, - both the command and the variable. - - * variables.texi (Creating Buffer-Local): Explain the meaning of - permanent local variables. - -2011-02-19 Glenn Morris - - * keymaps.texi (Remapping Commands): Mention how to undo it. - -2011-02-09 Reuben Thomas - - * loading.texi (Hooks for Loading): Remove unnecessary advice - about eval-after-load (Bug#7986). - -2011-02-05 Chong Yidong - - * commands.texi (Accessing Mouse): Note that a header line is not - included in the row of posn-col-row. - -2011-02-02 Chong Yidong - - * modes.texi (Major Mode Conventions): Add face guidelines. - (Faces for Font Lock): List faces in order of prominence. - -2011-02-01 Paul Eggert - - format-time-string now supports subsecond time stamp resolution - * os.texi (Time Parsing): Document %N. - -2011-01-28 Chong Yidong - - * vol1.texi (Top): - * vol2.texi (Top): - * elisp.texi (Top): - * display.texi (Display Property): Shorten the menu description of - the "Other Display Specs" node (Bug#7816). - - * keymaps.texi (Defining Menus): Add "menu item" and "extended - menu item" concept index entries (Bug#7805). - -2011-01-29 Eli Zaretskii - - * makefile.w32-in (texinfodir): New variable. - (usermanualdir): Remove as redundant with $(emacsdir). - (MAKEINFO): Remove options, leave only program name. - (MAKEINFO_OPTS): New variable. - (texinputdir, $(infodir)/elisp): Use $(MAKEINFO_OPTS). - -2011-01-25 Chong Yidong - Richard Kim - - * loading.texi (Library Search): Document list-load-path-shadows - (Bug#7757). - -2011-01-25 Chong Yidong - - * searching.texi (Regexp Special): Remove outdated discussion of - character sets (Bug#7780). - - * frames.texi (Pop-Up Menus): Document where menu title comes - from (Bug#7684). - -2011-01-25 Glenn Morris - - * display.texi (Making Buttons): Mention limitation of text buttons. - -2011-01-23 Werner Lemberg - - * Makefile.in (MAKEINFO): Now controlled by `configure'. - (MAKEINFO_OPTS): New variable. Use it where appropriate. - (ENVADD): New variable to control texi2dvi and texi2pdf. - -2011-01-15 Chong Yidong - - * files.texi (Directory Names): Move directory-abbrev-alist doc to - Emacs manual. - -2011-01-15 Eli Zaretskii - - * files.texi (Directory Names): Explain why FROM in - directory-abbrev-alist should begin with \`. (Bug#7777) - -2011-01-11 Stefan Monnier - - * loading.texi (Hooks for Loading): Adjust doc of eval-after-load. - -2011-01-02 Eli Zaretskii - - * modes.texi (Emulating Mode Line): Fix last change. - -2011-01-02 Eli Zaretskii - - * modes.texi (Emulating Mode Line): Update documentation of - format-mode-line according to changes that fixed bug #7587. - -2010-12-18 Stefan Monnier - - * modes.texi (Derived Modes): Mention prog-mode. - - * keymaps.texi (Simple Menu Items, Extended Menu Items): Remove mention - of the key-binding-data cache since we don't use it any more. - -2010-12-13 Eli Zaretskii - - * processes.texi (Shell Arguments): - * strings.texi (Creating Strings): Don't mention "shell commands"; - make it explicit that `split-string-and-unquote' and - `combine-and-quote-strings' are mainly for working with arguments - to call-process and start-process. - - * processes.texi (Shell Arguments): Fix documentation of - `split-string-and-unquote'. Add indexing. (Bug#7563) - -2010-12-13 Stefan Monnier - - * modes.texi (Auto-Indentation): New section to document SMIE. - (Major Mode Conventions): - * text.texi (Mode-Specific Indent): Refer to it. - -2010-12-13 Eli Zaretskii - - * display.texi (Other Display Specs): Document left-fringe and - right-fringe display specs. - -2010-12-13 Stefan Monnier - - * backups.texi (Making Backups): - * modes.texi (Example Major Modes): Use recommended coding style. - (Major Mode Basics, Derived Modes): Encourge more strongly use of - define-derived-mode. Mention completion-at-point-functions. - -2010-12-13 Chong Yidong - - * nonascii.texi (Converting Representations): - Document byte-to-string. - -2010-12-08 Glenn Morris - - * buffers.texi (Modification Time): - verify-visited-file-modtime now defaults to the current buffer. - -2010-11-27 Chong Yidong - - * nonascii.texi (Converting Representations): Document byte-to-string. - - * strings.texi (Creating Strings): Don't mention semi-obsolete - function char-to-string. - (String Conversion): Shorten discussion of semi-obsolete function - string-to-char. Link to Converting Representations. - - * objects.texi (Symbol Type): - * text.texi (Near Point): - * help.texi (Help Functions): - * functions.texi (Mapping Functions): Use string instead of - char-to-string in examples. - -2010-11-27 Chong Yidong - - * text.texi (Kill Functions, Kill Functions) - (Low-Level Kill Ring, Low-Level Kill Ring): Remove obsolete - YANK-HANDLER args. - - * symbols.texi (Creating Symbols): Using unintern without an - obarray arg is now obsolete. - - * numbers.texi (Float Basics): Document float-e and float-pi. - - * variables.texi (Defining Variables): Change "pi" example to - "float-pi". - -2010-11-26 Eli Zaretskii - - * commands.texi (Click Events): Document the values of X, Y and - COL, ROW in the event's position, when the click is on the header - or mode line, on the fringes, or in the margins. - -2010-11-17 Eli Zaretskii - - * customize.texi (Composite Types): Lower-case index entry. - - * loading.texi (How Programs Do Loading): - Document load-file-name. (Bug#7346) - -2010-11-17 Glenn Morris - - * text.texi (Kill Functions, Low-Level Kill Ring): Small fixes. - -2010-11-13 Eli Zaretskii - - * display.texi (Usual Display): Characters with no fonts are not - necessarily displayed as empty boxes. - -2010-10-31 Glenn Morris - - * maps.texi (Standard Keymaps): Update File menu description. - -2010-10-28 Glenn Morris - - * Makefile.in (elisp.dvi, elisp.pdf): Also include $emacsdir. - -2010-10-24 Eli Zaretskii - - * display.texi (Window Systems): Deprecate use of window-system as - a predicate. - -2010-10-23 Glenn Morris - - * help.texi (Documentation Basics): Remove mentions of digest-doc and - sorted-doc. - -2010-10-15 Eli Zaretskii - - * os.texi (Dynamic Libraries): New node, with slightly modified - text deleted from "Image Formats". - (System Interface): Add @menu entry for "Dynamic Libraries". - - * display.texi (Image Formats): Remove description of - image-library-alist. (Renamed in revno 101949.) - -2010-10-12 Glenn Morris - - * book-spine.texinfo: Rename to book-spine.texi. - -2010-10-11 Glenn Morris - - * Makefile.in (MAKEINFO): Add explicit -I$srcdir. - - * Makefile.in (DVIPS): New variable. - (.PHONY): Add html, ps. - (html, elisp.html, ps, elisp.ps): New targets. - (clean): Delete html, ps files. - ($(infodir)/elisp): Remove unnecessary includes. - -2010-10-09 Eli Zaretskii - - * makefile.w32-in (emacsdir): New variable. - (srcs): Add emacsver.texi. - ($(infodir)/elisp, elisp.dvi): Add -I$(emacsdir). - -2010-10-09 Glenn Morris - - * Makefile.in (VPATH): Remove. - (infodir): Make it absolute. - (mkinfodir, $(infodir)/elisp, infoclean): No need to cd $srcdir. - - * Makefile.in (dist): Anchor regexps. - - * Makefile.in (srcs): Put elisp.texi first. - ($(infodir)/elisp, elisp.dvi, elisp.pdf): Use $<. - - * Makefile.in (infoclean): Remove harmless, long-standing error. - - * Makefile.in ($(infodir)): Delete rule. - (mkinfodir): New. - ($(infodir)/elisp): Use $mkinfodir instead of infodir. - - * Makefile.in (dist): Remove reference to emacsver.texi.in. - Also copy emacsver.texi, and edit $emacsdir. - -2010-10-09 Glenn Morris - - * Makefile.in (emacsdir): New variable. - (MAKEINFO): Add -I $emacsdir. - (dist): Copy emacsver.texi. - (srcs): Add emacsver.texi. - - * book-spine.texinfo, elisp.texi, vol2.texi, vol1.texi: - Set EMACSVER by including emacsver.texi. - - * Makefile.in (.PHONY): Declare info, dvi, pdf, dist. - -2010-10-07 Glenn Morris - - * Makefile.in (version): New, set by configure. - (clean): Delete dist tar file. - (dist): Use version in tar name. - -2010-10-06 Glenn Morris - - * Makefile.in: Rearrange to more closely resemble doc/emacs/Makefile. - (INSTALL_INFO): Remove unused variable. - (mostlyclean, infoclean, dist): New rules. - (clean): Delete dvi and pdf files. - (maintainer-clean): Remove elisp.oaux, use infoclean. - ($(infodir)): Add parallel build workaround. - -2010-10-04 Glenn Morris - - * Makefile.in (dvi, pdf, $(infodir)): New targets. - ($(infodir)/elisp): Ensure target directory exists. Use $@. - Fix -I typo. - (clean): No 'make.out' or 'core' files. - (.PHONY): Declare clean rules. - (maintainer-clean): Delete pdf file. Guard against cd failures. - -2010-10-03 Glenn Morris - - * files.texi (File Name Components): Remove ignored section about - deleted variable directory-sep-char. - -2010-10-03 Michael Albinus - - * files.texi (Magic File Names): New defopt - remote-file-name-inhibit-cache. - -2010-10-02 Glenn Morris - - * os.texi (Killing Emacs): Hook now runs in batch mode. - -2010-09-18 Stefan Monnier - - * text.texi (Special Properties): Clarify when modification-hooks run. - -2010-09-11 Stefan Monnier - - * syntax.texi (Syntax Flags): Document new `c' flag. - -2010-09-09 Glenn Morris - - * display.texi (ImageMagick Images): General cleanup. - -2010-09-06 Alexander Klimov (tiny change) - - * files.texi (Directory Names): Use \` rather than ^. - -2010-09-02 Jan Djärv - - * text.texi (Low-Level Kill Ring): - * frames.texi (Window System Selections): Remove cut buffer - documentation. - -2010-08-28 Eli Zaretskii - - * display.texi (Fringe Size/Pos): Add a cross-reference to "Layout - Parameters", where the default fringe width is described. - - * frames.texi (Window Frame Parameters, Basic Parameters) - (Position Parameters, Layout Parameters, Management Parameters) - (Cursor Parameters, Font and Color Parameters): Add indexing for - frame parameters. (Bug#6929) - -2010-08-25 Tom Tromey - - * vol2.texi (Top): Update. - * vol1.texi (Top): Update. - * tips.texi (Library Headers): Mention Package-Version and - Package-Requires. - * package.texi: New file. - * os.texi (System Interface): Update pointers. - * elisp.texi (Top): Link to new nodes. Include package.texi. - * anti.texi (Antinews): Update pointers. - -2010-08-25 Eli Zaretskii - - * processes.texi (Filter Functions): Fix last change. - -2010-08-24 Markus Triska - - * processes.texi (Filter Functions): Use `buffer-live-p' instead - of `buffer-name' in the main text as well as in the example - (Bug#3098). - -2010-08-22 Chong Yidong - - * nonascii.texi (Text Representations): - * loading.texi (Loading Non-ASCII): - * compile.texi (Byte Compilation): Don't mention obsolete - --unibyte command-line argument. - -2010-08-22 Chong Yidong - - * modes.texi (Defining Minor Modes): Doc fix (Bug#6880). - -2010-08-22 Chong Yidong - - * objects.texi (Bool-Vector Type): Minor definition tweak (Bug#6878). - -2010-08-20 Eli Zaretskii - - * commands.texi (Misc Events): Add cross-references to where - POSITION of a mouse event is described in detail. - -2010-08-08 Christoph Scholtes - - * control.texi (Handling Errors) : Fix arg name. - -2010-08-08 Juanma Barranquero - - * modes.texi (Defining Minor Modes): Use C-backspace, not C-delete. - Suggested by Å těpán Němec . - -2010-08-08 Juanma Barranquero - - * minibuf.texi (High-Level Completion): Document args of - `read-buffer-function' (bug#5625). - -2010-07-29 Jan Djärv - - * frames.texi (Layout Parameters): Add doc for tool-bar-position. - -2010-07-29 Michael Albinus - - * processes.texi (Process Information): Explain process property - `remote-tty'. - -2010-07-27 Juanma Barranquero - - * modes.texi (Defining Minor Modes): Use C-delete in examples, - instead of "\C-\^?" (bug#6334). - - * text.texi (Special Properties): Fix typo. - -2010-07-09 Eli Zaretskii - - * internals.texi (Writing Emacs Primitives): Adapt to ANSI C - calling sequences, which are now the standard. - -2010-06-24 Chong Yidong - - * text.texi (Undo): Clarify command loop behavior (Bug#2433). - - * commands.texi (Command Overview): Mention undo-boundary call. - -2010-06-23 Glenn Morris - - * abbrevs.texi, commands.texi, compile.texi, debugging.texi: - * display.texi, edebug.texi, elisp.texi, eval.texi, files.texi: - * frames.texi, functions.texi, internals.texi, keymaps.texi: - * loading.texi, minibuf.texi, numbers.texi, os.texi, processes.texi: - * searching.texi, sequences.texi, strings.texi, syntax.texi: - * text.texi, tips.texi, vol1.texi, vol2.texi, windows.texi: - Untabify Texinfo files. - -2010-06-20 Chong Yidong - - * modes.texi (Minor Mode Conventions): Fix typo (Bug#6477). - -2010-06-19 Chong Yidong - - * errors.texi (Standard Errors): Remove unnecessary markup (Bug#6461). - -2010-06-02 Chong Yidong - - * searching.texi (Regexp Special): Remove obsolete information - about matching non-ASCII characters, and suggest using char - classes (Bug#6283). - -2010-05-30 Juanma Barranquero - - * minibuf.texi (Basic Completion): Add missing "@end defun". - -2010-05-30 Stefan Monnier - - * minibuf.texi (Basic Completion): Document completion-boundaries. - (Programmed Completion): Document the new fourth method for boundaries. - -2010-05-22 Chong Yidong - - * display.texi (Image Cache): Update documentation about image caching. - -2010-05-08 Å těpán Němec (tiny change) - - * windows.texi (Textual Scrolling): - * tips.texi (Coding Conventions): - * minibuf.texi (Minibuffer History): - * maps.texi (Standard Keymaps): - * loading.texi (Where Defined): - * edebug.texi (Instrumenting): Fix typos. - -2010-05-08 Chong Yidong - - * keymaps.texi (Menu Bar): Document :advertised-binding property. - - * functions.texi (Obsolete Functions): - Document set-advertised-calling-convention. - - * minibuf.texi (Basic Completion): Document completion-in-region. - (Programmed Completion): Document completion-annotate-function. - - * commands.texi (Reading One Event): Document read-key. - (Distinguish Interactive): Document KIND arg to - called-interactively-p. Delete obsolete interactive-p. - - * elisp.texi (Top): Update node description. - -2010-05-08 Eli Zaretskii - - * nonascii.texi (Character Properties): - Document unicode-category-table. Add an index entry for Unicode - general category. - -2010-05-07 Chong Yidong - - * Version 23.2 released. - -2010-04-20 Juanma Barranquero - - * locals.texi (Standard Buffer-Local Variables): - Remove @ignore'd reference to `direction-reversed'. - -2010-04-14 Juri Linkov - - Fix @deffn without category. - - * abbrevs.texi (Abbrev Expansion): Replace @deffn with @defun - for `abbrev-insert'. - - * buffers.texi (Indirect Buffers): Add category `Command' - to @deffn of `clone-indirect-buffer'. - - * windows.texi (Cyclic Window Ordering): Replace @deffn with @defun - for `next-window' and `previous-window'. Add category `Command' - to @deffn of `pop-to-buffer'. - -2010-04-01 Chong Yidong - - * nonascii.texi (Text Representations): Don't mark - enable-multibyte-characters as a user option. - -2010-03-31 Eli Zaretskii - - * control.texi (Handling Errors): How to re-throw a signal caught - by condition-case. - -2010-03-26 Chong Yidong - - * loading.texi (Hooks for Loading): Document after-load-functions. - Copyedits. - -2010-03-24 Arni Magnusson (tiny change) - - * frames.texi (Cursor Parameters): Fix typo. (Bug#5760) - -2010-03-24 Chong Yidong - - * processes.texi (Network Processes): Document seqpacket type. - -2010-03-20 Dan Nicolaescu - - * os.texi (System Environment): Do not mention lynxos. - -2010-03-10 Chong Yidong - - * Branch for 23.2. - -2010-03-06 Chong Yidong - - * objects.texi (Integer Type): Take note of the read syntax - exception for numbers that cannot fit in the integer type. - -2010-03-03 Glenn Morris - - * numbers.texi (Integer Basics, Bitwise Operations): - * objects.texi (Integer Type): Update for integers now being 30-bit. - -2010-02-27 Chong Yidong - - * display.texi (Low-Level Font): Document :otf font-spec property. - -2010-02-01 Stefan Monnier - - * display.texi (Line Height): Avoid obsolete special default variables - like default-major-mode. - -2010-01-28 Alan Mackenzie - - * display.texi (Auto Faces): Say fontification-functions is called - whether or not Font Lock is enabled. Tidy up the wording a bit. - -2010-01-17 Chong Yidong - - * elisp.texi: Remove duplicate edition information (Bug#5407). - -2010-01-17 Juanma Barranquero - - * two.el (volume-header-toc-markup): Fix typos in docstring. - -2010-01-04 Stefan Monnier - - Avoid dubious uses of save-excursions. - * positions.texi (Excursions): Recommend the use of - save-current-buffer if applicable. - * text.texi (Clickable Text): Fix the example code which used - save-excursion in a naive way which sometimes preserves point and - sometimes not. - * variables.texi (Creating Buffer-Local): - * os.texi (Session Management): - * display.texi (GIF Images): - * control.texi (Cleanups): Use (save|with)-current-buffer. - -2010-01-02 Eli Zaretskii - - * modes.texi (Example Major Modes): Fix indentation. (Bug#5195) - -2010-01-02 Chong Yidong - - * nonascii.texi (Text Representations, Character Codes) - (Converting Representations, Explicit Encoding) - (Translation of Characters): Use hex notation consistently. - (Character Sets): Fix map-charset-chars doc (Bug#5197). - -2010-01-01 Chong Yidong - - * loading.texi (Where Defined): Make it clearer that these are - loaded files (Bug#5068). - -2009-12-29 Chong Yidong - - * minibuf.texi (Completion Styles): Document `initials' style. - -2009-12-25 Chong Yidong - - * frames.texi (Resources): Describe inhibit-x-resources. - (Size Parameters): Copyedit. - - * hash.texi (Creating Hash): - * objects.texi (Hash Table Type): Document the new hash table - printed representation. - - * minibuf.texi (Basic Completion): 4th arg to all-completions is - obsolete. - - * processes.texi (Process Buffers): - Document process-kill-buffer-query-function. - -2009-12-05 Glenn Morris - - * hooks.texi (Standard Hooks): Remove diary-display-hook, replaced by - diary-display-function, and no longer recommended to be a hook. - Update for changes in the names of calendar and diary hooks. - diary-print-entries-hook has changed section. - -2009-11-28 Eli Zaretskii - - * text.texi (Special Properties): More accurate description of - what the `cursor' property does. - -2009-11-26 Kevin Ryde - - * commands.texi (Misc Events): vindex mouse-wheel-up-event and - mouse-wheel-down-event, the closest thing to a definition for them. - * os.texi (Startup Summary): vindex inhibit-startup-message and - inhibit-splash-screen. - (Command-Line Arguments): vindex argv. - (Suspending Emacs): vindex suspend-tty-functions and - resume-tty-functions. Don't want to index every hook, but having - the programming ones is helpful. - -2009-11-14 Chong Yidong - - * commands.texi (Motion Events): Fix typo (Bug#4907). - -2009-11-08 Chong Yidong - - * searching.texi (Char Classes): Note that [:upper:] and [:lower:] - are affected by case-fold-search (Bug#4483). - -2009-11-02 Chong Yidong - - * minibuf.texi (Reading File Names): Note that read-file-name may - use a graphical file dialog. - -2009-10-31 Glenn Morris - - * nonascii.texi (User-Chosen Coding Systems): Minor reword. (Bug#4817) - -2009-10-16 Kevin Ryde - - * files.texi (Magic File Names): Add @vindex file-name-handler-alist, - in particular so `info-lookup-symbol' can find its docs. - -2009-10-16 Chong Yidong - - * variables.texi (Constant Variables): Distinguish from defconst - variables. - (Defining Variables): Add cindex. - -2009-10-15 Chong Yidong - - * os.texi (Time of Day): Clarify that the microsecond part is - ignored (Bug#4637). - -2009-10-11 Glenn Morris - - * frames.texi (Size and Position): Clarify what is included in the frame - height. (Bug#4535) - -2009-10-10 Glenn Morris - - * windows.texi (Size of Window): The relationship between window and - frame heights is not so simple. (Bug#4535) - Mention window-full-height-p. - -2009-10-07 Stefan Monnier - - * positions.texi (Text Lines): Remove goto-line, since it shouldn't be - used from Lisp. - -2009-10-07 Eli Zaretskii - - * files.texi (Directory Names) : - Document that root home directories are not replaced with "~". - -2009-10-06 Eli Zaretskii - - * text.texi (Special Properties): Document the meaning of the - `cursor' text property whose value is an integer. - -2009-10-05 Michael Albinus - - * files.texi (Magic File Names): Add `copy-directory'. - -2009-10-05 Eli Zaretskii - - * files.texi (File Attributes): Fix description of file - attributes. (Bug#4638) Update attributes of files.texi example to - be more representative. - -2009-10-05 Michael Albinus - - * files.texi (Create/Delete Dirs): New command copy-directory. - -2009-10-04 Juanma Barranquero - - * anti.texi (Antinews): - * macros.texi (Indenting Macros): - * strings.texi (Creating Strings, Case Conversion): - Remove duplicate words. - -2009-10-01 Michael Albinus - - * files.texi (Create/Delete Dirs): delete-directory has an - optional parameter RECURSIVE. - -2009-10-01 Stefan Monnier - - * buffers.texi (Swapping Text): Minor clarification. - -2009-10-01 Glenn Morris - - * functions.texi (Declaring Functions): Mention that we also search for - ".m" files in the src/ directory. - -2009-09-25 David Engster - - * display.texi (Managing Overlays): Document copy-overlay (Bug#4549). - -2009-09-22 Glenn Morris - - * internals.texi (Building Emacs): Mention preloaded-file-list. - -2009-09-14 Alan Mackenzie - - * os.texi (Terminal Output): Put "@code{}" around "stdout". - -2009-09-13 Chong Yidong - - * functions.texi (Anonymous Functions): Rearrange discussion, - giving usage of unquoted lambda forms first. Mention that - `function' and `#'' are no longer required (Bug#4290). - -2009-09-11 Alan Mackenzie - - * os.texi (Terminal Output): Document `send-string-to-terminal' in - batch mode. - -2009-09-01 Glenn Morris - - * display.texi (Face Functions): Mention define-obsolete-face-alias. - -2009-08-26 Ulrich Mueller - - * nonascii.texi (Character Codes): Fix typos. - -2009-08-25 Michael Albinus - - * processes.texi (Synchronous Processes): New defvar - process-file-side-effects. - -2009-08-25 Glenn Morris - - * display.texi (Fontsets): Fix typo. - - * files.texi (Format Conversion Round-Trip): Mention nil regexp. - -2009-08-19 Stefan Monnier - - * processes.texi (Asynchronous Processes): Adjust arglist of - start-process-shell-command and start-file-process-shell-command. - -2009-08-15 Chong Yidong - - * advice.texi (Argument Access in Advice): Note that argument - positions are zero-based (Bug#3932). - - * commands.texi (Distinguish Interactive): Minor copyedit. - - * display.texi (Face Attributes): Add xref to Displaying Faces for - explanation of "underlying face". - - * customize.texi (Common Keywords): Add xref to Loading. - - * loading.texi (How Programs Do Loading): Add xref to Lisp - Libraries node in the Emacs manual. - -2009-08-13 Chong Yidong - - * objects.texi (Meta-Char Syntax): Add xref to Strings of Events. - -2009-07-18 Chong Yidong - - * processes.texi (Shell Arguments): Copyedits. - -2009-07-18 Glenn Morris - - * loading.texi (Repeated Loading): Fix typo. - -2009-07-16 Richard Stallman - - * buffers.texi (Swapping Text): Recommend setting - write-region-annotate-functions and buffer-saved-size. - - * backups.texi (Auto-Saving): Document buffer-saved-size = -2. - -2009-07-15 Glenn Morris - - * edebug.texi: Minor re-phrasings throughout. - (Edebug Execution Modes): Sit-for affects continue mode too. - (Jumping): Use `forward-sexp' rather than its keybinding. - (Edebug Misc): Fix Q binding. - (Edebug Eval): Remove cl version. - (Printing in Edebug): Clarify print-length etc. - (Instrumenting Macro Calls): Defopt edebug-eval-macro-args. - (Specification List): Remove edebug-unwrap findex entry. - (Specification Examples): defmacro is actually not the same as defun. - Escape "`" in example. - -2009-07-15 Chong Yidong - - * markers.texi (The Mark): Document optional arg to - deactivate-mark. - -2009-07-11 Kevin Ryde - - * hooks.texi (Standard Hooks): Fix cross-references. - - * loading.texi (Named Features): Refer to eval-after-load. - -2009-07-11 Glenn Morris - - * Makefile.in (TEXI2PDF): New. - (elisp.pdf): New target. - - * searching.texi (Regexp Backslash): Fix typo. - - * elisp.texi (Top): Display copyright notice at start of non-TeX. - -2009-07-10 Glenn Morris - - * elisp.texi, vol1.texi, vol2.texi: Update @detailmenu. - - * customize.texi (Customization Types): - * display.texi (Abstract Display): - * objects.texi (Character Type, String Type): - Merge in some menu descriptions from elisp.texi. - - * hash.texi (Hash Tables): - * modes.texi (Multiline Font Lock): - End menu description with period. - -2009-07-09 Glenn Morris - - * back.texi: Don't hard-code texinfo location. - - * two-volume.make (texinfodir): New, with location of texinfo.tex. - (tex): Add texinfodir to TEXINPUTS. - (elisp1med-init, elisp2med-init): Use texinfodir. - - * Makefile.in (texinfodir): Rename from usermanualdir, and update. - (clean): Add two-volume.make intermediate files. - - * elisp.texi, vol1.texi, vol2.texi: - Use a DATE variable with the publication date, and update it. - Fix antinews menu description. - - * vol1.texi, vol2.texi: Update VERSION to match elisp.texi. - Update the detailed node listing to match elisp.texi. - - * README: Update edition to match elisp.texi. - - * objects.texi (General Escape Syntax): - * nonascii.texi (Character Sets): - Use consistent case for "Unicode Standard". - - * anti.texi (Antinews): - * customize.texi (Variable Definitions): - * functions.texi (Declaring Functions): - * nonascii.texi (Character Properties): - * processes.texi (Serial Ports): - * text.texi (Special Properties): - * tips.texi (Coding Conventions): - Minor rearrangements to improve TeX line-filling. - - * commands.texi (Using Interactive): Fix cross-reference. - -2009-07-01 Jan Djärv - - * frames.texi (Management Parameters): Mention sticky. - -2009-07-01 Andreas Schwab - - * help.texi (Help Functions): Fix description of help-buffer and - help-setup-xref to use @defun instead of @deffn. - -2009-07-01 Jan Djärv - - * frames.texi (Size Parameters): Mention maximized for fullscreen. - -2009-06-24 Chong Yidong - - * display.texi (Window Systems): Add ns to the list. - -2009-06-21 Chong Yidong - - * Branch for 23.1. - -2009-06-17 Martin Rudalics - - * windows.texi (Dedicated Windows): Fix typo. - (Resizing Windows): Replace @defun by @deffn. - -2009-06-17 Glenn Morris - - * variables.texi (Directory Local Variables): - Update for 2009-04-11 name-change of dir-locals-directory-alist. - -2009-06-09 Kenichi Handa - - * nonascii.texi (Character Sets): State clearly that FROM and TO - are codepoints of CHARSET. - -2009-06-07 Chong Yidong - - * minibuf.texi (Reading File Names): Fix introductory text. - Suggested by stan@derbycityprints.com. - (High-Level Completion): Fix typo. - -2009-05-28 Chong Yidong - - * frames.texi (Text Terminal Colors): Multi-tty is already - implemented, but tty-local colors are not. - -2009-05-27 Chong Yidong - - * hooks.texi (Standard Hooks): Remove mention of obsolete - redisplay-end-trigger-functions. - - * internals.texi (Window Internals): Remove mention of obsolete - redisplay-end-trigger-functions. - -2009-05-21 Martin Rudalics - - * abbrevs.texi (Abbrev Mode): abbrev-mode is an option. - - * backups.texi (Making Backups): backup-directory-alist and - make-backup-file-name-function are options. - (Auto-Saving): auto-save-list-file-prefix is an option. - - * buffers.texi (Killing Buffers): buffer-offer-save is an - option. - - * display.texi (Refresh Screen): no-redraw-on-reenter is an - option. - (Echo Area Customization): echo-keystrokes is an option. - (Selective Display): selective-display-ellipses is an option. - (Temporary Displays): temp-buffer-show-function is an option. - (Face Attributes): underline-minimum-offset and x-bitmap-file-path - are options. - (Font Selection): face-font-family-alternatives, - face-font-selection-order, face-font-registry-alternatives, and - scalable-fonts-allowed are options. - (Fringe Indicators): indicate-buffer-boundaries is an option. - (Fringe Cursors): overflow-newline-into-fringe is an option. - (Scroll Bars): scroll-bar-mode is an option. - - * eval.texi (Eval): max-lisp-eval-depth is an option. - - * files.texi (Visiting Functions): find-file-hook is an option. - (Directory Names): directory-abbrev-alist is an option. - (Unique File Names): temporary-file-directory and - small-temporary-file-directory are options. - - * frames.texi (Initial Parameters): initial-frame-alist, - minibuffer-frame-alist and default-frame-alist are options. - (Cursor Parameters): blink-cursor-alist and - cursor-in-non-selected-windows ar options. - (Window System Selections): selection-coding-system is an - option. - (Display Feature Testing): display-mm-dimensions-alist is an - option. - - * help.texi (Help Functions): help-char and help-event-list are - options. - - * keymaps.texi (Functions for Key Lookup): meta-prefix-char is - an option. - - * minibuf.texi (Minibuffer History): history-length and - history-delete-duplicates are options. - (High-Level Completion): read-buffer-function and - read-buffer-completion-ignore-case are options. - (Reading File Names): read-file-name-completion-ignore-case is - an option. - - * modes.texi (Mode Line Top): mode-line-format is an option. - (Mode Line Variables): mode-line-position and mode-line-modes - are options. - - * nonascii.texi (Text Representations): - enable-multibyte-characters is an option. - (Default Coding Systems): auto-coding-regexp-alist, - file-coding-system-alist, auto-coding-alist and - auto-coding-functions are options. - (Specifying Coding Systems): inhibit-eol-conversion is an - option. - - * os.texi (Init File): site-run-file is an option. - (System Environment): mail-host-address is an option. - (User Identification): user-mail-address is an option. - (Terminal Output): baud-rate is an option. - - * positions.texi (Word Motion): words-include-escapes is an - option. - - * searching.texi (Standard Regexps): page-delimiter, - paragraph-separate, paragraph-separate and sentence-end are - options. - - * text.texi (Margins): left-margin and fill-nobreak-predicate - are options. - - * variables.texi (Local Variables): max-specpdl-size is an - option. - - * windows.texi (Choosing Window): - split-window-preferred-function, special-display-function and - display-buffer-function are options. - -2009-05-20 Chong Yidong - - Fix errors spotted by Martin Rudalics. - - * syntax.texi (Position Parse): Document rationale for ignored - arguments to syntax-ppss-flush-cache. - - * processes.texi (Input to Processes): Mark PROCESS arg to - process-running-child-p as optional. - (Network Options): Document NO-ERROR arg to - set-network-process-option. - - * buffers.texi (Indirect Buffers): Mark clone-indirect-buffer as a - command. - - * searching.texi (POSIX Regexps): Mark posix-search-forward and - posix-search-backward as commands. - - * os.texi (Killing Emacs): Mark kill-emacs as a command. - (Suspending Emacs): Mark suspend-emacs as a command. - (Processor Run Time): Mark emacs-uptime and emacs-init-time as - commands. - (Terminal Output): Remove obsolete function baud-rate. - Document TERMINAL arg for send-string-to-terminal. - - * nonascii.texi (Terminal I/O Encoding): Document TERMINAL arg for - terminal-coding-system and set-terminal-coding-system. - (Explicit Encoding): Mark DESTINATION arg of decode-coding-region - as optional. - (Character Sets): Document RESTRICTION arg of char-charset. - (Character Codes): Mark POS argument to get-byte as optional. - - * minibuf.texi (Minibuffer Misc): Document ARGS arg for - minibuffer-message. - - * files.texi (Create/Delete Dirs): Mark make-directory and - delete-directory as commands. - - * abbrevs.texi (Abbrev Tables): Fix arglist for make-abbrev-table. - - * text.texi (Base 64): Mark base64-decode-string and - base64-encode-string as commands. - (Columns): Mark move-to-column as a command. - (Mode-Specific Indent): Document RIGID arg to - indent-for-tab-command. - (Region Indent): Mark TO-COLUMN arg to indent-region as optional. - Mark indent-code-rigidly as a command. - (Substitution): Mark translate-region as a command. - - * frames.texi (Size and Position): Remove obsolete functions - screen-height and screen-width. - -2009-05-19 Chong Yidong - - * windows.texi (Cyclic Window Ordering, Cyclic Window Ordering) - (Displaying Buffers, Resizing Windows): Correct mistakes; - next-window, previous-window, and pop-to-buffer are not commands, - and fit-window-to-buffer" is a command. (Pointed out by Martin - Rudalics.) - -2009-05-17 Richard M Stallman - - * modes.texi (Precalculated Fontification): Clarify text. - -2009-05-17 Martin Rudalics - - * windows.texi (Selecting Windows): Clarify descriptions of - with-selected-window and get-lru-window. - (Cyclic Window Ordering): Refer to particular frame when talking - about how splitting affects the ordering. - (Displaying Buffers): Fix descriptions of switch-to-buffer and - switch-to-buffer-other-window. Explain how setting of - display-buffer-reuse-frames affects pop-to-buffer. - (Choosing Window): Clarify some details in descriptions of - display-buffer-reuse-frames, pop-up-frames, and - pop-up-frame-function. - (Dedicated Windows): Clarify some details. - (Textual Scrolling): Replace term vscroll by term vertical - scroll position. - (Vertical Scrolling): Fix typo. - (Window Hooks): Relate text on jit-lock-register to window - scrolling and size changes. - -2009-05-14 Chong Yidong - - * frames.texi (Initial Parameters): Clarify what the initial - minibuffer frame is. - (Buffer Parameters): Note that the minibuffer parameter can not be - altered. - - * anti.texi (Antinews): Copyedits. Rearrange some entries. - Document display-buffer changes. - -2009-05-13 Chong Yidong - - * anti.texi (Antinews): Rewrite for Emacs 22. - - * abbrevs.texi (Abbrevs): Add xref to Creating Symbols when - obarrays are first mentioned. Define "system abbrev" more - prominently, and add it to the index. - (Abbrev Mode, Abbrev Tables, Defining Abbrevs, Abbrev Properties): - Copyedits. - (Abbrev Expansion): Document abbrev-insert. - -2009-05-12 Chong Yidong - - * frames.texi (Font and Color Parameters): Rename from Color - Parameters. Document font-backend parameter. - - * vol2.texi (Top): Update node listing. - * vol1.texi (Top): Update node listing. - * elisp.texi (Top): Update node listing. - -2009-05-11 Martin Rudalics - - * windows.texi (Choosing Window): Don't explicitly refer to - split-window-sensibly's window argument in descriptions of - split-height-threshold and split-width-threshold. - -2009-05-10 Martin Rudalics - - * windows.texi (Choosing Window): Fix rewrite of window - splitting section. - -2009-05-09 Eli Zaretskii - - * nonascii.texi (Default Coding Systems): - Document find-auto-coding, set-auto-coding, and auto-coding-alist. - Add indexing. - (Lisp and Coding Systems): Add index entries. - -2009-05-09 Martin Rudalics - - * windows.texi (Choosing Window): Describe split-window-sensibly - and rewrite section on window splitting accordingly. - (Textual Scrolling): Replace `...' by @code{...}. - -2009-05-04 Chong Yidong - - * hooks.texi (Standard Hooks): Add abbrev-expand-functions. - Remove obsoleted pre-abbrev-expand-hook. - - * locals.texi (Standard Buffer-Local Variables): Consolidate table - entries. - - * internals.texi (Object Internals): Don't assume 32-bit machines - are the norm. - (Buffer Internals): Consolidate table entries for readability. - (Window Internals): Synch field names to window.h. - (Process Internals): Synch field names to process.h. - -2009-04-29 Chong Yidong - - * variables.texi (File Local Variables): Note that read-circle is - bound to nil when reading file-local variables. - - * streams.texi (Input Functions): Document read-circle. - (Output Variables): Add xref to Circular Objects. - -2009-04-25 Chong Yidong - - * tips.texi (Coding Conventions): Copyedits. Add xref to Named - Features and Coding System Basics. Node that "p" stands for - "predicate". Recommend utf-8-emacs instead of emacs-mule. - (Key Binding Conventions): Emacs does use S-down-mouse-1, for - mouse-appearance-menu. - (Programming Tips): Add xref to Progress. - -2009-04-22 Chong Yidong - - * os.texi (Command-Line Arguments): - Document command-line-args-left. - (Suspending Emacs): Adapt text to multi-tty case. Document use of - terminal objects for tty arguments. - (Startup Summary): Add xref to Session Management. - (Session Management): Mention emacs-session-restore. Copyedits. - -2009-04-20 Chong Yidong - - * os.texi (Startup Summary): Copyedits. The init file is not - necessarily named .emacs now. Document initial-buffer-choice and - initial-scratch-message. Note where Emacs exits in batch mode. - Document inhibit-splash-screen as an alias. - (Init File): Be neutral about which init file name to use. - -2009-04-16 Chong Yidong - - * os.texi (System Interface): Fix Texinfo usage. - -2009-04-15 Chong Yidong - - * searching.texi (Regexp Backslash): Also refer to shy groups as - non-capturing or unnumbered groups. - (Regexp Functions): Add cross-reference to Regexp Backslash. - - * display.texi (Truncation): Overlays can use line-prefix and - wrap-prefix too. - (Overlay Properties): Document wrap-prefix and line-prefix. - (Face Attributes): Document underline-minimum-offset. - (Face Remapping): Copyedits. - (Low-Level Font): Copyedits. - (Image Cache): Note that the image cache is shared between frames. - (Line Height): Emphasize that line-spacing only takes effect on - graphical terminals. - -2009-04-13 Chong Yidong - - * display.texi (Refresh Screen): Note that a passage about screen - refreshing is text terminal only. - (Forcing Redisplay): Delete misleading comment---sit-for calls - redisplay, not the other way around. - (Truncation): Note new values of truncate-partial-width-windows. - Copyedits. - (Invisible Text): Document invisible-p. - -2009-04-11 Eli Zaretskii - - * display.texi (Overlays): Overlays don't scale well. See - http://lists.gnu.org/archive/html/emacs-devel/2009-04/msg00243.html. - -2009-04-10 Chong Yidong - - * syntax.texi (Syntax Table Functions): Document cons cell - argument for modify-syntax-entry. - (Categories): Document cons cell argument for - modify-category-entry. - - * searching.texi (String Search): Document word-search-forward-lax - and word-search-backward-lax. - (Searching and Case): Describe isearch behavior more precisely. - - * keymaps.texi (Tool Bar): Mention that some platforms do not - support multi-line toolbars. Suggested by Stephen Eglen. - - * frames.texi (Layout Parameters): Mention that Nextstep also - allows only one tool-bar line. Suggested by Stephen Eglen. - - * nonascii.texi (Text Representations): Copyedits. - (Coding System Basics): Also mention utf-8-emacs. - (Converting Representations, Selecting a Representation) - (Scanning Charsets, Translation of Characters, Encoding and I/O): - Copyedits. - (Character Codes): Mention role of codepoints 1114112 to 4194175. - -2009-04-09 Chong Yidong - - * text.texi (Yank Commands): Note that yank uses push-mark. - (Filling): Clarify REGION argument of fill-paragraph. - Document fill-forward-paragraph-function. - (Special Properties): Remove "new in Emacs 22" declaration. - (Clickable Text): Merge with Links and Mouse-1 node. - - * display.texi (Button Properties, Button Buffer Commands): - Change xref to Clickable Text. - - * tips.texi (Key Binding Conventions): Change xref to Clickable - Text. - - * elisp.texi (Top): Update node listing. - -2009-04-05 Chong Yidong - - * markers.texi (The Mark): Copyedits. Improve description of - handle-shift-selection. - (The Region): Move use-region-p here from The Mark. - - * positions.texi (Screen Lines): Document (cols . lines) argument - for vertical-motion. - -2009-04-04 Chong Yidong - - * frames.texi (Frames): Clean up introduction. Document `ns' - return value for framep. - (Creating Frames): Note how the terminal is chosen. - (Multiple Terminals, Multiple Displays): Merge into a single node. - (Color Parameters): Fix typo. - - * variables.texi (Local Variables, Buffer-Local Variables) - (Creating Buffer-Local): Change link to Multiple Terminals. - - * os.texi (X11 Keysyms): Change link to Multiple Terminals. - - * keymaps.texi (Controlling Active Maps): Change link to Multiple - Terminals. - - * commands.texi (Command Loop Info, Keyboard Macros): Change link - to Multiple Terminals. - - * elisp.texi (Top): Update node listing. - * vol2.texi (Top): Update node listing. - * vol1.texi (Top): Update node listing. - - * buffers.texi (Current Buffer): Note that the append-to-buffer - example is no longer in synch with the latest code. Tie the two - examples together. - - * files.texi (File Attributes): Move note about MS-DOS from - Changing Files to File Attributes. - (Create/Delete Dirs): Note that mkdir is an alias for this. - -2009-04-01 Markus Triska - - * processes.texi (Filter Functions): Suggest how to handle output - batches. - -2009-03-30 Chong Yidong - - * help.texi (Accessing Documentation): Update example to use - help-setup-xref and with-help-window. - (Help Functions): Remove print-help-return-message, which is - semi-obsolete due to with-help-window. Document help-buffer and - help-setup-xref. - -2009-03-29 Chong Yidong - - * help.texi (Accessing Documentation, Help Functions): - Remove information about long-obsolete Emacs versions. - - * modes.texi (Mode Line Variables): The default values of the mode - line variables are now more complicated. - -2009-03-28 Chong Yidong - - * modes.texi (Major Mode Conventions): Note that specialness is - inherited. - (Derived Modes): Note that define-derive-mode sets the mode-class - property. - - * keymaps.texi (Prefix Keys): The M-g prefix key is now named - goto-map. Add search-map to the list. - -2009-03-27 Eli Zaretskii - - * os.texi (System Environment): Update the list of system-type - values. - - * markers.texi (The Mark) : Update for - removal of the optional argument DEACTIVATE. - -2009-03-25 Chong Yidong - - * commands.texi (Focus Events): Most X window managers don't use - focus-follows-mouse nowadays. - -2009-03-24 Chong Yidong - - * commands.texi (Defining Commands): Clarify introduction. - (Using Interactive): Not that interactive can be put in a symbol - property. - (Interactive Call): Note that a symbol with a non-nil - interactive-form property satisfies commandp. - -2009-03-23 Juanma Barranquero - - * minibuf.texi (Intro to Minibuffers): Fix typos. - -2009-03-23 Chong Yidong - - * minibuf.texi (Intro to Minibuffers): Remove long-obsolete info - about minibuffers in old Emacs versions. Copyedits. - Emphasize that enable-recursive-minibuffers defaults to nil. - (Text from Minibuffer): Simplify introduction. - -2009-03-22 Alan Mackenzie - - * commands.texi (Using Interactive): Clarify string argument to - `interactive' - even promptless elements need \n separators. - -2009-03-18 Chong Yidong - - * minibuf.texi (Completion Styles): New node. - - * elisp.texi (Top): Update node listing. - -2009-03-17 Chong Yidong - - * minibuf.texi (Basic Completion): Note that - read-file-name-completion-ignore-case and - read-buffer-completion-ignore-case can override - completion-ignore-case. - (Minibuffer Completion): Document completing-read changes. - (Completion Commands): Avoid mentioning partial completion mode. - Document minibuffer-completion-confirm changes, and - minibuffer-confirm-exit-commands. - (High-Level Completion): Document new require-match behavior for - read-buffer. Document read-buffer-completion-ignore-case. - (Reading File Names): Document new require-match behavior for - read-file-name. - -2009-03-14 Chong Yidong - - * debugging.texi (Error Debugging): Don't mislead the reader into - thinking that debug-on-error enters debugger for C-f at EOB. - (Error Debugging): Setting debug-on-init within the init file - works, and has for some time. - -2009-03-13 Kenichi Handa - - * display.texi (Fontsets): Update the description. - -2009-03-13 Chong Yidong - - * advice.texi (Advising Primitives): Link to What Is a Function. - -2009-03-12 Chong Yidong - - * compile.texi (Speed of Byte-Code): Update example. - (Disassembly): Update examples. - - * loading.texi (Repeated Loading): Simplify examples. - - * customize.texi (Common Keywords): It's not necessary to use :tag - to remove hyphens, as custom-unlispify-tag-name does it - automatically. - (Variable Definitions): Link to File Local Variables. - Document customized-value symbol property. - (Customization Types): Move menu to end of node. - -2009-03-10 Chong Yidong - - * macros.texi (Compiling Macros): Omit misleading sentence, which - implied that macros can only be used in the same file they are - defined. - (Backquote): Remove obsolete information about Emacs 19. - -2009-03-05 John Foerch (tiny change) - - * display.texi (Display Margins): Fix paren typo. - -2009-02-27 Chong Yidong - - * elisp.texi (Top): Update node listing. - - * variables.texi (Variables): Clarify introduction. - (Global Variables): Mention that setq is a special form. - (Local Variables): Use active voice. - (Tips for Defining): Mention marking variables as safe. - (Buffer-Local Variables): Mention terminal-local and frame-local - variables together. - (File Local Variables): Copyedits. - (Frame-Local Variables): Note that they are not really useful. - (Future Local Variables): Node deleted. - - * objects.texi (General Escape Syntax): Update explanation of - Unicode escape syntax. - -2009-02-23 Chong Yidong - - * control.texi (Control Structures): Add cindex entry for "textual - order". - - * eval.texi (Intro Eval): Copyedits. Standardize on "form" - instead of "expression" throughout. - (Function Indirection): Copyedits. Use active voice. - (Eval): The default value of max-lisp-eval-depth is now 400. - -2009-02-23 Miles Bader - - * processes.texi (System Processes): Rename `system-process-attributes' - to `process-attributes'. - -2009-02-22 Chong Yidong - - * symbols.texi (Property Lists): Emphasize that property lists are - not restricted to symbol cells. - (Other Plists): Copyedit. - - * sequences.texi (Sequences Arrays Vectors): Make introduction - more concise. - (Arrays): Mention char-tables and bool-vectors too. - (Vectors): Don't repeat information given in Arrays node. Link to - nodes that explain the vector usage examples. - (Char-Tables): Note that char-table elements can have arbitrary - type. Explain effect of omitted char-table-extra-slots property. - Link to Property Lists node. - -2009-02-22 Chong Yidong - - * lists.texi (Building Lists): Remove obsolete Emacs 20 usage of - `append'. - (List Elements): Copyedits. - - * sequences.texi (Vector Functions): Remove obsolete Emacs 20 use - of `vconcat'. - - * strings.texi (Creating Strings): Copyedits. Remove obsolete - Emacs 20 usage of `concat'. - (Case Conversion): Copyedits. - -2009-02-21 Chong Yidong - - * objects.texi (Lisp Data Types, Syntax for Strings, Buffer Type): - Minor edits. - (Frame Configuration Type): Emphasize that it is not primitive. - (Font Type): New node. - (Type Predicates): Add fontp; type-of now recognizes font object - types. - - * intro.texi (Version Info): Update version numbers in examples. - (Acknowledgements): List more contributors. - - * elisp.texi: Bump version number to 3.0. - (Top): Link to Font Type node. - -2009-02-20 Juanma Barranquero - - * modes.texi (Major Mode Conventions): Remove duplicate words. - (Customizing Keywords): Fix typo. - -2009-02-14 Eli Zaretskii - - * nonascii.texi (User-Chosen Coding Systems): Document that - select-safe-coding-system suggests raw-text if there are raw bytes - in the region. - (Explicit Encoding): Warn not to use `undecided' when encoding. - -2009-02-11 Glenn Morris - - * frames.texi (Visibility of Frames): Mention the effect multiple - workspaces/desktops can have on visibility. - -2009-02-07 Eli Zaretskii - - * text.texi (Commands for Insertion): - * commands.texi (Event Mod): - * keymaps.texi (Searching Keymaps): - * nonascii.texi (Translation of Characters): - Reinstate documentation of translation-table-for-input. - (Explicit Encoding): Document the `charset' text property produced - by decode-coding-region and decode-coding-string. - -2009-01-27 Alan Mackenzie - - * modes.texi (Search-based Fontification): Correct a typo. - -2009-01-25 Juanma Barranquero - - * abbrevs.texi (Abbrev Table Properties): Fix typo. - Reported by Seweryn Kokot . (Bug#2039) - -2009-01-24 Eli Zaretskii - - * display.texi (Window Systems): Document the value of - `initial-window-system' under --daemon. - - * os.texi (System Environment): Remove description of the - `environment' function which has been deleted. - -2009-01-22 Dan Nicolaescu - - * frames.texi (Multiple Displays): Remove documentation for - removed function make-frame-on-tty. - -2009-01-22 Chong Yidong - - * files.texi (Format Conversion Piecemeal): Clarify behavior of - write-region-annotate-functions. - Document write-region-post-annotation-function. - -2009-01-19 Chong Yidong - - * display.texi (Font Lookup): Document WIDTH argument of - x-list-fonts. - -2009-01-17 Eli Zaretskii - - * maps.texi (Standard Keymaps): Rename function-key-map to - local-function-key-map. - - * keymaps.texi (Translation Keymaps): Rename function-key-map to - local-function-key-map. - - * nonascii.texi (Terminal I/O Encoding): `keyboard-coding-system' - and `set-keyboard-coding-system' now accept an optional terminal - argument. - - * commands.texi (Event Mod): `keyboard-translate-table' is now - terminal-local. - (Function Keys): Rename function-key-map to - local-function-key-map. - - * elisp.texi (Top): Make @detailmenu be consistent with changes in - frames.texi. - - * hooks.texi (Standard Hooks): Document `delete-frame-functions' - `delete-terminal-functions', `suspend-tty-functions' and - `resume-tty-functions'. - - * frames.texi (Frames): Document `frame-terminal' and - `terminal-live-p'. - (Multiple Displays): Document `make-frame-on-tty'. - (Multiple Terminals): Document `terminal-list', `delete-terminal', - `terminal-name', and `get-device-terminal'. - (Terminal Parameters): Document `terminal-parameters', - `terminal-parameter', and `set-terminal-parameter'. - - * os.texi (System Environment): Document `environment' and - `initial-environment'. - (Suspending Emacs): Update for multi-tty; document - `suspend-tty', `resume-tty', and `controlling-tty-p'. - - * nonascii.texi (Coding System Basics): More accurate description - of `raw-text'. - -2009-01-12 Juanma Barranquero - - * display.texi (Low-Level Font): Fix typo. - -2009-01-10 Chong Yidong - - * elisp.texi (Top): Update node listing. - - * display.texi (PostScript Images): Node deleted. - -2009-01-10 Eli Zaretskii - - * processes.texi (Decoding Output): Document that null bytes force - no-conversion for reading process output. - - * files.texi (Reading from Files): Document that null bytes force - no-conversion when visiting files. - - * processes.texi (Serial Ports): Improve wording, suggested by RMS. - - * nonascii.texi (Lisp and Coding Systems): - Document inhibit-null-byte-detection and inhibit-iso-escape-detection. - (Character Properties): Improve wording. - -2009-01-09 Chong Yidong - - * display.texi (Font Lookup): Remove obsolete function - x-font-family-list. x-list-fonts accepts Fontconfig/GTK syntax. - (Low-Level Font): Rename from Fonts, move to end of Faces section. - (Font Selection): Reorder order of variable descriptions. - Minor clarifications. - - * elisp.texi (Top): Update node listing. - -2009-01-09 Glenn Morris - - * commands.texi (Command Loop Info): Say that last-command-char and - last-input-char are obsolete aliases. - - * edebug.texi (Edebug Recursive Edit): Remove separate references to - last-input-char and last-command-char, since they are just aliases for - last-input-event and last-command-event. - - * minibuf.texi (Minibuffer Commands): Use last-command-event rather than - last-command-char. - -2009-01-08 Chong Yidong - - * elisp.texi: Update node listing. - - * display.texi (Faces): Put Font Selection node after Auto Faces. - (Face Attributes): Don't link to Font Lookup. - Document font-family-list. - (Fonts): New node. - -2009-01-08 Jason Rumney - - * frames.texi (Pointer Shape): Clarify that only X supports - changing the standard pointer shapes. (Bug#1485) - -2009-01-08 Chong Yidong - - * display.texi (Attribute Functions): Note that a function value - :height is relative, and that compatibility functions work by - calling set-face-attribute. - (Displaying Faces): Reorder list in order of increasing priority. - (Face Remapping): New node. Content moved here from Displaying - Faces. - (Glyphs): Link to Face Functions. - -2009-01-08 Chong Yidong - - * display.texi (Faces): Don't discuss face id here. facep does - not return t. - (Defining Faces): Minor clarification. - (Face Attributes): Rearrange items to match docstring of - set-face-attribute. Add :foundry attribute. Document new role of - :font attribute. Texinfo usage fix. - (Attribute Functions): Copyedits. - (Face Functions): Note that face number is seldom used. - -2009-01-05 Richard M Stallman - - * strings.texi (Predicates for Strings): Minor clarification. - - * functions.texi (Function Safety): Texinfo usage fix. - -2009-01-04 Eduard Wiebe (tiny patch) - - * objects.texi (General Escape Syntax): Fix typo. - -2009-01-03 Martin Rudalics - - * windows.texi (Choosing Window): Say that pop-up-frame-alist - works via the default value of pop-up-frame-function. - -2009-01-02 Eli Zaretskii - - * processes.texi (System Processes): Document the `time' and - `ctime' attributes of `system-process-attributes'. - -2009-01-01 Chong Yidong - - * display.texi (Face Attributes): Clarify :height attribute. - -2008-12-31 Martin Rudalics - - * buffers.texi (The Buffer List): Clarify what moves a buffer to - the front of the buffer list. Add entries for `last-buffer' and - `unbury-buffer'. - -2008-12-27 Eli Zaretskii - - * elisp.texi (Top): Add @detailmenu items for "Multiple Terminals" - and its subsections. - - * frames.texi (Multiple Terminals, Low-level Terminal) - (Terminal Parameters, Frames on Other TTY devices): New sections. - (Frames): Add an xref to "Multiple Terminals". - - * elisp.texi (Top): Add @detailmenu item for "Terminal Type". - - * objects.texi (Terminal Type): New node. - (Editing Types): Add it to the menu. - - * elisp.texi (Top): Add a @detailmenu item for "Directory Local - Variables". - - * variables.texi (Directory Local Variables): New node. - (Variables): Add a menu item for it. - - * loading.texi (Autoload): Document `generate-autoload-cookie' and - `generated-autoload-file'. - -2008-12-20 Eli Zaretskii - - * os.texi (Startup Summary): Add xref to documentation of - `initial-window-system'. - - * display.texi (Window Systems): Document `window-system' the - function. The variable `window-system' is now frame-local. - Document `initial-window-system'. - -2008-12-19 Martin Rudalics - - * windows.texi (Windows): Rewrite description of - fit-window-to-buffer. - -2008-12-13 Glenn Morris - - * modes.texi (Font Lock Basics): Fix level description. (Bug#1534) - (Levels of Font Lock): Refer to font-lock-maximum-decoration. - -2008-12-12 Glenn Morris - - * debugging.texi (Error Debugging): Refer forwards to - eval-expression-debug-on-error. - -2008-12-05 Eli Zaretskii - - * strings.texi (String Basics): Only unibyte strings that - represent key sequences hold 8-bit raw bytes. - - * nonascii.texi (Coding System Basics): Rewrite @ignore'd - paragraph to speak about `undecided'. - (Character Properties): Don't explain the meaning of each - property; instead, identify their Unicode Standard names. - (Character Sets): Document `map-charset-chars'. - -2008-12-02 Glenn Morris - - * files.texi (Format Conversion Round-Trip): Rewrite format-write-file - section yet again. - -2008-11-29 Eli Zaretskii - - * nonascii.texi (Character Properties): New Section. - (Specifying Coding Systems): Document - `coding-system-priority-list', `set-coding-system-priority', and - `with-coding-priority'. - (Lisp and Coding Systems): Document `check-coding-systems-region' - and `coding-system-charset-list'. - (Coding System Basics): Document `coding-system-aliases'. - - * elisp.texi (Top): Add a @detailmenu entry for "Character - Properties". - - * objects.texi (Character Type): Correct the range of Emacs - characters. Add an @xref to "Character Codes". - - * strings.texi (String Basics): Add an @xref to "Character Codes". - - * numbers.texi (Integer Basics): Add an @xref to `max-char'. - - * nonascii.texi (Explicit Encoding): Update for Emacs 23. - (Character Codes): Document `max-char'. - -2008-11-28 Eli Zaretskii - - * nonascii.texi (Text Representations, Converting Representations) - (Character Sets, Scanning Charsets, Translation of Characters): - Make text more accurate. - -2008-11-28 Glenn Morris - - * files.texi (Format Conversion Round-Trip): Improve previous change. - -2008-11-26 Chong Yidong - - * modes.texi (Auto Major Mode): Fix example. - -2008-11-25 Glenn Morris - - * control.texi (Signaling Errors): Fix `wrong-type-argument' name. - - * files.texi (Format Conversion Round-Trip): - Use active voice for previous change. - -2008-11-25 Chong Yidong - - * os.texi (Processor Run Time): - * processes.texi (Transaction Queues): - * markers.texi (The Mark): - * windows.texi (Choosing Window, Selecting Windows): - * files.texi (Changing Files, Magic File Names): - * commands.texi (Key Sequence Input): - * functions.texi (Declaring Functions): - * strings.texi (Predicates for Strings): - * intro.texi (nil and t): Fix typos (pointed out by Drew Adams). - -2008-11-24 Chong Yidong - - * help.texi (Accessing Documentation): Update example. - - * variables.texi (Defining Variables): Note that `*' is not - necessary if defcustom is used. - -2008-11-22 Eli Zaretskii - - * elisp.texi (Top): Remove "Chars and Bytes" and "Splitting - Characters" from @detailmenu. - - * nonascii.texi (Character Codes, Character Sets) - (Scanning Charsets, Translation of Characters): Update for Emacs 23. - (Chars and Bytes, Splitting Characters): Sections removed. - -2008-11-22 Lute Kamstra - - * positions.texi (Text Lines): Update goto-line documentation. - -2008-11-21 Martin Rudalics - - * frames.texi (Frames): Fix typo, add cross references, reword. - (Initial Parameters): Reword special-display-frame-alist text. - (Frames and Windows): Reword. Describe argument norecord for - set-frame-selected-window. - (Input Focus): Describe argument norecord for select-frame. - Remove comment on MS-Windows behavior for focus-follows-mouse. - (Raising and Lowering): Mention windows-frames dichotomy in - metaphor. - - * windows.texi (Displaying Buffers, Vertical Scrolling) - (Horizontal Scrolling): Fix indenting and rewording issues - introduced with 2008-11-07 change. - -2008-11-20 Glenn Morris - - * files.texi (Format Conversion Round-Trip): Mention `preserve' - element of `format-alist'. - -2008-11-19 Glenn Morris - - * doclicense.texi: Update to FDL 1.3. - * elisp.texi, vol1.texi, vol2.texi: Relicense under FDL 1.3 or later. - -2008-11-18 Chong Yidong - - * windows.texi (Window Hooks): Remove *-end-trigger-functions - vars, which are obsolete. Mention jit-lock-register. - - * modes.texi (Other Font Lock Variables): - Document jit-lock-register and jit-lock-unregister. - - * frames.texi (Color Parameters): Document alpha parameter. - -2008-11-16 Martin Rudalics - - * windows.texi (Splitting Windows, Deleting Windows) - (Selecting Windows, Cyclic Window Ordering) - (Buffers and Windows, Displaying Buffers, Choosing Window) - (Dedicated Windows, Window Point, Window Start and End) - (Textual Scrolling, Vertical Scrolling, Horizontal Scrolling) - (Size of Window, Resizing Windows, Window Configurations) - (Window Parameters): Avoid @var at beginning of sentences and - reword accordingly. - -2008-11-11 Lute Kamstra - - * files.texi (File Name Components): Fix file-name-extension - documentation. - -2008-11-11 Juanma Barranquero - - * frames.texi (Basic Parameters): Remove display-environment-variable - and term-environment-variable. - -2008-11-08 Eli Zaretskii - - * windows.texi (Basic Windows, Splitting Windows) - (Deleting Windows, Selecting Windows, Cyclic Window Ordering) - (Buffers and Windows, Displaying Buffers, Dedicated Windows) - (Resizing Windows, Window Configurations, Window Parameters): - Fix wording and markup. - -2008-11-07 Martin Rudalics - - * windows.texi (Windows): Update entries. - (Basic Windows): Remove listing of attributes. Reword. - (Splitting Windows, Deleting Windows): Reword. - (Selecting Windows, Cyclic Window Ordering): Reword with special - emphasis on order of recently selected windows and buffer list. - (Buffers and Windows, Choosing Window): Reword with special - emphasis on dedicated windows. - (Displaying Buffers): Reword. For switch-to-buffer mention that - it may fall back on pop-to-buffer. For other-window try to - explain how it treats the cyclic ordering of windows. - (Dedicated Windows): New node and section discussing dedicated - windows and associated functions. - (Window Point): Add entry for window-point-insertion-type. Reword. - (Window Start and End): Rename node and section title. Reword. - (Textual Scrolling, Vertical Scrolling, Horizontal Scrolling): - Minor rewording. - (Size of Window): Reword, in particular text on window-width. - (Resizing Windows): Reword. Add text on balancing windows. - (Window Configurations): Reword. Mention window parameters. - (Window Parameters): New node and section on window parameters. - (Window Hooks): Reword. Mention that - window-configuration-change-hook is run "buffer-locally". - * elisp.texi (Top): Update Windows entries in @detailmenu - section. - -2008-11-04 Juanma Barranquero - - * searching.texi (Regexp Search): Fix typo. - -2008-11-03 Seweryn Kokot (tiny change) - - * searching.texi (Regexp Search): Document GREEDY arg. - (Simple Match Data): Fix return value. - -2008-11-01 Eli Zaretskii - - * nonascii.texi (Text Representations): Rewrite to make consistent - with Emacs 23 internal representation of characters. - Document `unibyte-string'. - -2008-10-28 Chong Yidong - - * processes.texi (Process Information): Note that process-status - does not accept buffer names. - -2008-10-27 Seweryn Kokot (tiny change) - - * positions.texi (Skipping Characters): Correct return value of - skip-chars-forward. - -2008-10-25 Martin Rudalics - - * windows.texi (Deleting Windows): Update documentation of - delete-windows-on. - (Buffers and Windows): Update documentations of - get-buffer-window and get-buffer-window-list. - (Displaying Buffers): Update documentation of - replace-buffer-in-windows. - - * buffers.texi (Current Buffer): Reword set-buffer and - with-current-buffer documentations. - (Creating Buffers): Reword documentation of get-buffer-create. - -2008-10-23 Martin Rudalics - - * buffers.texi (Current Buffer): Reword documentation of - set-buffer. - (Buffer Names): Reword documentation of buffer-name. - (The Buffer List): For bury-buffer explain what happens with the - buffer's window. - (Creating Buffers): Say that get-buffer-create's arg is called - buffer-or-name. - -2008-10-22 Chong Yidong - - * advice.texi (Computed Advice): Explain what DEFINITION is. - - * nonascii.texi (Character Codes): Remove obsolete function - char-valid-p, and document characterp instead. - -2008-10-22 Martin Rudalics - - * windows.texi (Displaying Buffers): Reword documentation of - pop-to-buffer. - (Choosing Window): Rewrite documentation of display-buffer and - its options. - - * buffers.texi (Killing Buffers): Update documentation of - kill-buffer. - -2008-10-21 Eli Zaretskii - - * processes.texi (Serial Ports): Fix wording and improve markup. - - * searching.texi (Regexp Search): Document `string-match-p' and - `looking-at-p'. - (POSIX Regexps): Add an xref for "non-greedy". - (Regexp Special): Add @cindex entry for "non-greedy". - - * display.texi (Attribute Functions): Document `face-all-attributes'. - (Image Cache) : Minor wording fixes. - - * frames.texi (Color Names): Add an xref to `read-color'. - - * minibuf.texi (High-Level Completion): Document `read-color'. - - * elisp.texi (Top): Add "Swapping Text" to @detailmenu. - - * positions.texi (Narrowing): Add an xref to "Swapping Text". - - * buffers.texi (Swapping Text): New section, documents - `buffer-swap-text'. - -2008-10-21 Martin Rudalics - - * windows.texi (Resizing Windows): Minor wording fix. - -2008-10-20 Eli Zaretskii - - * processes.texi (Shell Arguments): Document `split-string-and-unquote' - and `combine-and-quote-strings'. - - * strings.texi (Creating Strings): Add xrefs for them. - -2008-10-19 Eli Zaretskii - - * elisp.texi (Top): Make descriptive text for "Reading File Names" - match the corresponding menu in minibuf.texi. - - * minibuf.texi (Reading File Names): Document `read-shell-command' - and `minibuffer-local-shell-command-map'. - -2008-10-19 Martin Rudalics - - * windows.texi (Resizing Windows): Remove var{} around "window" in - documentation of enlarge-window. - Rewrite documentation of window-min-height and window-min-width. - -2008-10-19 Eli Zaretskii - - * functions.texi (Calling Functions): Document `apply-partially'. - - * hooks.texi (Standard Hooks): Mention - `before-hack-local-variables-hook' and `hack-local-variables-hook'. - - * variables.texi (File Local Variables): Document - `file-local-variables-alist', `before-hack-local-variables-hook' - and `hack-local-variables-hook'. - - * processes.texi (Synchronous Processes): Document `process-lines'. - - * customize.texi (Variable Definitions): - Document `custom-reevaluate-setting'. - -2008-10-18 Martin Rudalics - - * windows.texi (Choosing Window, Deleting Windows) - (Displaying Buffers): Expand documentation of dedicated windows. - -2008-10-18 Eli Zaretskii - - * files.texi (Changing Files): Document symbolic input of file - modes to `set-file-modes'. Document `read-file-modes' and - `file-modes-symbolic-to-number'. - - * maps.texi (Standard Keymaps): Document `multi-query-replace-map' - and `search-map'. - - * searching.texi (Search and Replace): - Document `replace-search-function' and `replace-re-search-function'. - Document `multi-query-replace-map'. - - * minibuf.texi (Text from Minibuffer): Document `read-regexp'. - (Completion Commands, Reading File Names): - Rename `minibuffer-local-must-match-filename-map' to - `minibuffer-local-filename-must-match-map'. - (Minibuffer Completion): The `require-match' argument to - `completing-read' can now have the value `confirm-only'. - - * windows.texi (Displaying Buffers): Minor wording fix. - (Choosing Window): `split-height-threshold' can now be nil. - Document `split-width-threshold'. `pop-up-frames' can have the - value `graphic-only'. - -2008-10-17 Eli Zaretskii - - * os.texi (Startup Summary): Document `before-init-time' and - `after-init-time'. Document `initial-window-system' and - `window-system-initialization-alist'. Document reading the - abbrevs file. Document the call to `server-start' under --daemon. - Rearrange a bit to be consistent with the code flow. - (Processor Run Time): Document `emacs-uptime' and `emacs-init-time'. - (Time Parsing): Document `format-seconds'. - -2008-10-17 Martin Rudalics - - * windows.texi (Basic Windows, Splitting Windows): Fix whitespace - and reword. - -2008-10-16 Eli Zaretskii - - * markers.texi (The Mark): Document use-region-p. - -2008-10-15 Eli Zaretskii - - * internals.texi (Writing Emacs Primitives): The interactive spec - of a primitive can be a Lisp form. - - * markers.texi (The Mark): Document the `lambda' and `(only . OLD)' - values of transient-mark-mode. Document handle-shift-selection. - - * commands.texi (Using Interactive, Interactive Codes): Document `^'. - (Interactive Examples): Show an example of `^'. - (Key Sequence Input): Document this-command-keys-shift-translated. - (Defining Commands, Using Interactive): The interactive-form of a - function can be added via its symbol's property. - - * positions.texi (List Motion): beginning-of-defun-function can - now accept an argument. - - * text.texi (Low-Level Kill Ring): interprogram-paste-function can - now return a list of strings. - - * control.texi (Handling Errors): Document ignore-errors. - - * frames.texi (Creating Frames): Document frame-inherited-parameters. - (Parameter Access): Document set-frame-parameter. - - * variables.texi (Creating Buffer-Local): Add an xref to "Setting - Hooks" for the effect of kill-all-local-variables on local hook - functions. - - * modes.texi (Major Mode Conventions, Mode Line Variables): - `mode-name' need not be a string. xref to "Mode Line Data" for - details, and to "Emulating Mode Line" for computing a string - value. - -2008-10-14 Eli Zaretskii - - * processes.texi (System Processes): New section. - (Processes, Signals to Processes): Add xrefs to it. - - * objects.texi (Editing Types): A `process' is a subprocess of - Emacs, not just any process running on the OS. - - * elisp.texi (Top): Adjust the @detailmenu for the above two - changes. - - * sequences.texi (Char-Tables): Remove documentation of - set-char-table-default, which has no effect since Emacs 23. - : Don't mention generic - characters and charsets. Add a cons cell as a possible argument. - - * nonascii.texi (Splitting Characters) - (Translation of Characters): Don't mention generic characters. - - * display.texi (Fontsets): Don't mention generic characters. - - * sequences.texi (Char-Tables): `map-char-table' can now call its - argument FUNCTION with a cons cell as KEY. - -2008-10-13 Eli Zaretskii - - * objects.texi (Primitive Function Type): Move "@cindex special - forms" from here... - - * eval.texi (Special Forms): ...to here. - - * functions.texi (What Is a Function): `functionp' returns nil for - special forms. Add an xref. - - * elisp.texi (Top): Add a @detailmenu entry for "Frame-Local - Variables". - - * variables.texi (Frame-Local Variables): New section. - (Buffer-Local Variables): Add an xref to it. - (Intro to Buffer-Local, Creating Buffer-Local): A variable cannot - have both frame-local and buffer-local binding. - - * frames.texi (Frames): Mention multiple tty frames. - (Frame Parameters, Parameter Access): Mention frame-local variable - bindings. - -2008-09-20 Glenn Morris - - * display.texi (Defining Faces): Recommend against face variables. - -2008-09-16 Juanma Barranquero - - * display.texi (Echo Area Customization): Fix typo. - -2008-09-09 Juanma Barranquero - - * loading.texi (Where Defined): Add `defface' item. - -2008-09-06 Martin Rudalics - - * loading.texi (Where Defined): Fix description of symbol-file. - -2008-08-26 Jason Rumney - - * display.texi (TIFF Images): New section describing :index property. - -2008-08-23 Chong Yidong - - * display.texi (Temporary Displays): Remove unnecessary comment - about usage of temp-buffer-show-hook. - -2008-08-05 Chong Yidong - - * symbols.texi (Other Plists): Fix incorrect example. - Suggested by Florian Beck. - -2008-07-31 Juanma Barranquero - - * os.texi: Fix previous change. - -2008-07-31 Dan Nicolaescu - - * os.texi: - * intro.texi: - * files.texi: Remove VMS support. - -2008-07-27 Dan Nicolaescu - - * os.texi: - * frames.texi: - * display.texi: Remove mentions of Mac Carbon. - -2008-07-01 Miles Bader - - * text.texi (Special Properties): - * display.texi (Truncation): Add wrap-prefix and line-prefix. - -2008-06-28 Johan BockgÃ¥rd - - * display.texi (Other Image Types): Fix copy/paste error; say - "PBM", not "XBM". - -2008-06-26 Dan Nicolaescu - - * os.texi: Remove references to obsolete systems. - -2008-06-20 Eli Zaretskii - - * makefile.w32-in (distclean): Remove makefile. - -2008-06-17 Glenn Morris - - * Makefile.in (emacsver, miscmanualdir, VERSION, manual, install) - (elisp, dist): Remove rules and variables that are obsolete now - the lisp manual is no longer distributed separately. - -2008-06-16 Glenn Morris - - * configure, configure.in, mkinstalldirs: Remove unused files. - - * book-spine.texinfo: Set version to 23.0.60. - * vol1.texi (EMACSVER): - * vol2.texi (EMACSVER): Set to 23.0.60. - - * elisp.texi, vol1.texi, vol2.texi: Update Back-Cover Text - as per maintain.info. - -2008-06-15 Glenn Morris - - * makefile.w32-in (manual): Use "23" rather than "21". - - * Makefile.in (emacsver): New, set by configure. - (manual): Use emacsver. - - * intro.texi: Report bugs using M-x report-emacs-bug. - - * elisp.texi (EMACSVER): Remove duplicate, outdated setting. - -2008-06-13 Daniel Engeler - - * elisp.texi, internals.texi, processes.texi: Add documentation - about serial port access. - -2008-06-05 Miles Bader - - * display.texi (Displaying Faces): Update to reflect function - renamings in face-remap.el. - -2008-06-05 Juanma Barranquero - - * display.texi (Fontsets): Fix typos. - -2008-06-03 Miles Bader - - * display.texi (Displaying Faces): Add add-relative-face-remapping, - remove-relative-face-remapping, set-base-face-remapping, - and set-default-base-face-remapping. - -2008-06-01 Miles Bader - - * display.texi (Displaying Faces): Add face-remapping-alist. - -2008-05-30 Stefan Monnier - - * tips.texi (Coding Conventions): Do not encourage the use of "-flag" - variable names. - -2008-05-03 Eric S. Raymond - - * keymaps.texi: Clarify that (current-local-map) and - (current-global-map) return references, not copies. - -2008-05-02 Juri Linkov - - * minibuf.texi (Text from Minibuffer): Document a list of - default values for `read-from-minibuffer'. - -2008-04-24 Juanma Barranquero - - * nonascii.texi (Translation of Characters): Fix previous change. - -2008-04-20 Chong Yidong - - * display.texi (Overlay Properties): Clarify role of underlying - textprop and overlay keymaps for display strings. - - * keymaps.texi (Active Keymaps): Ditto. - -2008-04-19 Stefan Monnier - - * minibuf.texi (Programmed Completion): - Replace dynamic-completion-table with the new completion-table-dynamic. - -2008-04-07 Chong Yidong - - * intro.texi (Some Terms): Change "fonts in this manual" index - entry to "typographic conventions". - -2008-04-05 Eli Zaretskii - - * objects.texi (Text Props and Strings): Add indexing for read - syntax of text properties. - -2008-03-25 Stefan Monnier - - * processes.texi (Decoding Output): Remove process-filter-multibyte - functions. - -2008-03-15 Martin Rudalics - - * display.texi (Finding Overlays): Say that empty overlays at - the end of the buffer are reported too. - -2008-03-13 Glenn Morris - - * elisp.texi (EMACSVER): Set to 23.0.60. - -2008-02-26 Chong Yidong - - * strings.texi (Formatting Strings): Treat - and 0 as flag characters. - -2008-02-22 Glenn Morris - - * frames.texi (Position Parameters): Clarify the description of - `left' and `top', using information from "Geometry". - (Geometry): Give a pointer to "Position Parameters", rather than - repeating information. - -2008-02-11 Glenn Morris - - * objects.texi (Equality Predicates): No longer talk about "two" - functions. - -2008-02-11 Lawrence Mitchell (tiny change) - - * objects.texi (Equality Predicates): Add defun for - equal-including-properties. - -2008-02-10 Glenn Morris - - * objects.texi (Equality Predicates): - Mention equal-including-properties. - -2008-02-07 Richard Stallman - - * windows.texi (Window Start): Mention the feature of moving - window-start to start of line. - -2008-02-07 Jan Djärv - - * keymaps.texi (Tool Bar): Document rtl property. - -2008-01-27 Thien-Thi Nguyen - - * display.texi (Button Types): - For define-button-type, clarify type of NAME. - -2008-01-19 Martin Rudalics - - * buffers.texi (Buffer Modification): Fix typo. - -2008-01-06 Dan Nicolaescu - - * os.texi (System Environment): Remove references to OSes that are - not supported anymore. - -2008-01-05 Dan Nicolaescu - - * os.texi (System Environment): Remove mention for Masscomp. - -2008-01-04 Richard Stallman - - * display.texi (Faces): Don't talk about internal face vector as arg - to facep. - - * customize.texi (Type Keywords): Fix previous change. - - * text.texi (Links and Mouse-1): Fix xref for commands.texi change. - * elisp.texi (Top): Fix menu for commands.texi change. - -2007-12-30 Richard Stallman - - * commands.texi (Accessing Mouse): Rename from Accessing Events. - (Accessing Scroll): New node broken out of Accessing Mouse. - -2007-12-28 Richard Stallman - - * frames.texi (Size Parameters): Fix typo. - (Basic Parameters): For `title', refer to title bar. - (Size and Position): Explain meaning of frame pixel width and height. - -2007-12-23 Richard Stallman - - * customize.texi (Type Keywords): Uncomment :validate and clarify it. - Improve some of the commented-out keywords' text too. - -2007-12-14 Martin Rudalics - - * nonascii.texi (Encoding and I/O): Reword to avoid saying - "visit the current buffer". - - * os.texi (System Interface): Fix typo. - -2007-12-04 Richard Stallman - - * objects.texi (Symbol Type): Fix typo. - -2007-12-03 Richard Stallman - - * hooks.texi (Standard Hooks): Add link to Hooks for Loading. - -2007-12-01 Glenn Morris - - * functions.texi (Declaring Functions): Improve previous change. - -2007-11-30 Glenn Morris - - * functions.texi (Declaring Functions): Add optional fourth - argument of declare-function, and setting third argument to `t'. - -2007-11-29 Richard Stallman - - * customize.texi (Composite Types): Document `group' type. - -2007-11-29 Glenn Morris - - * functions.texi (Declaring Functions): Add findex. - Mention `external' files. - -2007-11-26 Juanma Barranquero - - * functions.texi (Declaring Functions): Fix directive. - -2007-11-25 Richard Stallman - - * help.texi (Help Functions): Clean up last change. - - * advice.texi (Preactivation, Activation of Advice): Minor cleanup. - - * loading.texi (Named Features): Minor cleanup. - - * macros.texi (Eval During Expansion): Minor cleanup. - - * variables.texi (Variable Aliases): Minor cleanup. - -2007-11-24 Richard Stallman - - * functions.texi (Declaring Functions): Clarify previous change. - - * compile.texi (Compiler Errors): Clarify previous change. - -2007-11-24 Richard Stallman - - * display.texi (Refresh Screen, Forcing Redisplay): - Clarify the text and move items around. - -2007-11-24 Glenn Morris - - * functions.texi (Declaring Functions): New section. - * compile.texi (Compiler Errors): Mention declaring functions, - defvar with no initvalue, and byte-compile-warnings. - -2007-11-15 Martin Rudalics - - * vol1.texi (Top): Remove Frame-Local Variables from Node Listing. - * vol2.texi (Top): Remove Frame-Local Variables from Node Listing. - -2007-11-13 Martin Rudalics - - * help.texi (Help Functions): Document new macro `with-help-window'. - -2007-11-10 Paul Pogonyshev - - * searching.texi (Replacing Match): Describe new - `match-substitute-replacement'. - -2007-10-31 Richard Stallman - - * strings.texi (Creating Strings): Null strings from concat not unique. - -2007-10-26 Richard Stallman - - * objects.texi (Equality Predicates): Null strings are uniquified. - - * minibuf.texi: Minor clarifications in previous change. - -2007-10-25 Glenn Morris - - * customize.texi (Variable Definitions): Add :risky and :safe keywords. - -2007-10-24 Richard Stallman - - * elisp.texi (Top): Delete Frame-Local Variables from subnode menu. - - * variables.texi (Frame-Local Variables): Node deleted. - (Variables): Delete Frame-Local Variables from menu. - (Local Variables, Buffer-Local Variables, Intro to Buffer-Local) - (Default Value): Don't mention frame-local vars. - - * os.texi (Idle Timers): current-idle-time returns nil if not idle. - - * loading.texi (Unloading): Document FEATURE-unload-function - instead of FEATURE-unload-hook. - - * frames.texi (Multiple Displays): Don't mention frame-local vars. - -2007-10-22 Juri Linkov - - * minibuf.texi (Text from Minibuffer, Minibuffer Completion) - (High-Level Completion): Document a list of default value strings - in the DEFAULT argument, for which minibuffer functions return the - first element. - -2007-10-17 Juri Linkov - - * text.texi (Filling): Update arguments of fill-paragraph. - fill-paragraph operates on the active region in Transient Mark mode. - Remove fill-paragraph-or-region. - -2007-10-13 Karl Berry - - * elisp.texi (@dircategory): Move to after @copying, - since we want @copying as close as possible to the beginning of - the output. - -2007-10-12 Richard Stallman - - * elisp.texi (Top): Add Distinguish Interactive to subnode menu. - - * commands.texi (Distinguish Interactive): New node, - broken out from Interactive Call and rewritten. - (Command Loop): Put Distinguish Interactive in menu. - -2007-10-09 Richard Stallman - - * text.texi (Examining Properties): Mention overlay priority. - - * display.texi (Display Margins): Correct the description - of margin display specifications. - (Replacing Specs): New subnode broken out of Display Property. - -2007-10-06 Juri Linkov - - * text.texi (Filling): Document fill-paragraph-or-region. - -2007-10-05 Juanma Barranquero - - * display.texi (Auto Faces): Fix typo. - -2007-10-02 Richard Stallman - - * display.texi (Display Property): Explain some display specs - don't let you move point in. - - * frames.texi (Cursor Parameters): - Describe cursor-in-non-selected-windows here. Explain more values. - - * windows.texi (Basic Windows): Don't describe - cursor-in-non-selected-windows here. - -2007-10-01 Eli Zaretskii - - * processes.texi (Misc Network): Note that these functions are - supported only on some systems. - -2007-10-01 Richard Stallman - - * display.texi (Overlay Properties): Explain nil as priority. - Explain that conflicts are unpredictable if not resolved by - priorities. - -2007-09-23 Richard Stallman - - * macros.texi (Backquote): Minor clarification. - -2007-09-19 Richard Stallman - - * display.texi (Display Property): Explain multiple display specs. - Clarify when they work in parallel and when one overrides. - Fix error in example. - -2007-09-06 Glenn Morris - - Move from lispref/ to doc/lispref/. Change all setfilename - commands to use ../../info. - * Makefile.in (infodir): Go up one more level. - (usermanualdir): Change from ../man to ../emacs. - (miscmanualdir): New. - (dist): Use new variable miscmanualdir. - * makefile.w32-in (infodir, texinputdir): Go up one more level. - (usermanualdir): Change from ../man to ../emacs. - -2007-08-30 Martin Rudalics - - * commands.texi (Command Loop Info): Advise against changing - most variables described here. Explain new variable - last-repeatable-command. - -2007-08-29 Glenn Morris - - * elisp.texi (EMACSVER): Increase to 23.0.50. - -2007-08-29 Dan Nicolaescu - - * frames.texi (Basic Parameters): Add display-environment-variable - and term-environment-variable. - -2007-08-28 Juri Linkov - - * display.texi (Image Formats, Other Image Types): Add SVG. - -2007-08-28 Juri Linkov - - * display.texi (Images): Move formats-related text to new node - "Image Formats". - (Image Formats): New node. - -2007-08-27 Richard Stallman - - * windows.texi (Window Configurations): Clarify what - a window configuration saves. - -2007-08-25 Richard Stallman - - * display.texi (Images): Delete redundant @findex. - -2007-08-16 Stefan Monnier - - * text.texi (Change Hooks): (after|before)-change-functions are no - longer bound to nil while running; rather inhibit-modification-hooks - is t. - -2007-08-16 Richard Stallman - - * processes.texi (Asynchronous Processes): - Clarify doc of start-file-process. - -2007-08-08 Martin Rudalics - - * modes.texi (Example Major Modes): Fix typo. - -2007-08-08 Glenn Morris - - * intro.texi (nil and t): Do not use `iff' in documentation. - - * tips.texi (Documentation Tips): Recommend against `iff'. - -2007-08-07 Chong Yidong - - * display.texi (Image Cache): Document image-refresh. - -2007-08-06 Martin Rudalics - - * windows.texi (Size of Window): Document window-full-width-p. - -2007-07-25 Glenn Morris - - * gpl.texi (GPL): Replace license with GPLv3. - - * Relicense all FSF files to GPLv3 or later. - -2007-07-24 Michael Albinus - - * processes.texi (Synchronous Processes): - Add `process-file-shell-command'. - (Asynchronous Processes): Mention restricted use of - `process-filter' and `process-sentinel' in - `start-file-process'. Add `start-file-process-shell-command'. - -2007-07-17 Michael Albinus - - * files.texi (Magic File Names): Introduce optional parameter - IDENTIFICATION for `file-remote-p'. - -2007-07-16 Richard Stallman - - * display.texi (Defining Faces): Fix previous change. - -2007-07-14 Richard Stallman - - * control.texi (Handling Errors): Document `debug' in handler list. - -2007-07-10 Richard Stallman - - * display.texi (Defining Faces): Explain C-M-x feature for defface. - -2007-07-09 Richard Stallman - - * files.texi (Magic File Names): Rewrite previous change. - -2007-07-08 Michael Albinus - - * files.texi (Magic File Names): Introduce optional parameter - CONNECTED for `file-remote-p'. - -2007-07-07 Michael Albinus - - * processes.texi (Asynchronous Processes): - * files.texi (Magic File Names): Add `start-file-process'. - -2007-06-27 Richard Stallman - - * files.texi (Format Conversion Piecemeal): - Clarify `after-insert-file-functions' calling convention. - -2007-06-27 Michael Albinus - - * files.texi (Magic File Names): Remove `dired-call-process'. - Add `process-file'. - -2007-06-27 Kenichi Handa - - * text.texi (Special Properties): Fix description about - `composition' property. - -2007-06-26 Kenichi Handa - - * nonascii.texi (Default Coding Systems): Document about the - return value `undecided'. - -2007-06-25 David Kastrup - - * keymaps.texi (Active Keymaps): Document new POSITION argument of - `current-active-maps'. - -2007-06-24 Karl Berry - - * elisp.texi, vol1.texi, vol2.texi: New Back-Cover Text. - -2007-06-15 Juanma Barranquero - - * display.texi (Overlay Arrow): Doc fix. - -2007-06-14 Karl Berry - - * anti.texi (Antinews): Typo. - -2007-06-14 Chong Yidong - - * display.texi (Image Cache): Document image-refresh. - -2007-06-12 Karl Berry - - * vol1.texi, vol2.texi, two-volume-cross-refs.txt: Update. - * two-volume.make: New file. - * .cvsignore: Ignore two-volume files. - -2007-06-12 Tom Tromey - - * os.texi (Init File): Document user-emacs-directory. - -2007-06-03 Nick Roberts - - * commands.texi (Click Events): Describe width and height when - object is nil. - -2007-05-30 Nick Roberts - - * commands.texi (Click Events): Layout more logically. - Describe width and height. - (Drag Events, Motion Events): Update to new format for position. - -2007-06-02 Richard Stallman - - * frames.texi (Color Parameters): Add xref to (emacs)Standard Faces. - -2007-06-02 Chong Yidong - - * Version 22.1 released. - -2007-06-01 Stefan Monnier - - * text.texi (Special Properties): Correct meaning of fontified face. - -2007-05-30 Richard Stallman - - * text.texi (Special Properties): Add link to Adjusting Point. - -2007-05-12 Richard Stallman - - * text.texi (Margins): indent-to-left-margin is not the default. - (Mode-Specific Indent): For indent-line-function, the default - is indent-relative. - - * modes.texi (Example Major Modes): Explain last line of text-mode - is redundant. - -2007-05-10 Richard Stallman - - * keymaps.texi (Scanning Keymaps): Update where-is-internal example. - - * help.texi (Keys in Documentation): Add reference to - Documentation Tips. - - * files.texi (Format Conversion): TO-FN gets three arguments. - - * modes.texi (Auto Major Mode): Document file-start-mode-alist. - -2007-05-10 Thien-Thi Nguyen - - * elisp.texi (Top): Remove "Saving Properties" from detailed menu. - * files.texi (Format Conversion): Expand intro; add menu. - (Format Conversion Overview, Format Conversion Round-Trip) - (Format Conversion Piecemeal): New nodes/subsections. - * hooks.texi: Xref "Format Conversion" , not "Saving Properties". - * text.texi (Text Properties): Remove "Saving Properties" from menu. - (Saving Properties): Delete node/subsection. - -2007-05-07 Karl Berry - - * elisp.texi (EMACSVER): Back to 22. - -2007-05-06 Richard Stallman - - * processes.texi (Accepting Output): Revert most of previous change. - -2007-05-05 Richard Stallman - - * processes.texi (Accepting Output): accept-process-output - uses microseconds, not milliseconds. But that arg is obsolete. - -2007-05-04 Karl Berry - - * elisp.texi (EMACSVER) [smallbook]: 22.1, not 22. - -2007-05-04 Eli Zaretskii - - * tips.texi (Documentation Tips): Rearrange items to place the - more important ones first. Add an index entry for hyperlinks. - -2007-05-03 Karl Berry - - * elisp.texi (\urlcolor, \linkcolor) [smallbook]: \Black for printing. - (EMACSVER) [smallbook]: 22 for printed version. - - * control.texi (Signaling Errors) : texinfo.tex is fixed, - so restore anchor to normal position after defun. Found by Kevin Ryde. - -2007-04-26 Glenn Morris - - * elisp.texi (EMACSVER): Increase to 22.1.50. - -2007-04-28 Karl Berry - - * elisp.texi: Improve line breaks on copyright page, - similar layout to emacs manual, 8.5x11 by default. - -2007-04-24 Richard Stallman - - * text.texi (Special Properties): Add xref to Overlay Properties. - - * display.texi (Overlay Properties): Add xref to Special Properties. - -2007-04-22 Richard Stallman - - * keymaps.texi (Extended Menu Items): Move the info about - format with cached keyboard binding. - -2007-04-21 Richard Stallman - - * text.texi (Special Properties): Clarify previous change. - - * files.texi (File Name Expansion): Clarify previous change. - - * display.texi (Attribute Functions): Fix example for - face-attribute-relative-p. - -2007-04-19 Kenichi Handa - - * text.texi (Special Properties): Document composition property. - -2007-04-19 Glenn Morris - - * files.texi (File Name Expansion): Mention "superroot". - -2007-04-15 Chong Yidong - - * frames.texi (Multiple Displays): Add note about "multi-monitor" - setups. - (Display Feature Testing): Note that display refers to all - physical monitors for multi-monitor setups. - -2007-04-14 Richard Stallman - - * lists.texi (Sets And Lists): Clarify `delete' examples. - Remove spurious xref to same node. - Clarify xref for add-to-list. - -2007-04-12 Nick Roberts - - * keymaps.texi (Format of Keymaps): Remove spurious ")" from - value of lisp-mode-map. - -2007-04-11 Karl Berry - - * anti.texi (Antinews): - * display.texi (Overlay Properties, Defining Images): - * processes.texi (Synchronous Processes, Sentinels): - * syntax.texi (Syntax Table Internals): - * searching.texi (Regexp Special): - * nonascii.texi (Default Coding Systems): - * text.texi (Special Properties): - * minibuf.texi (Basic Completion): Wording to improve breaks in - 8.5x11 format. - * elisp.texi (smallbook): New @set to more easily switch between - smallbook and 8.5x11. - -2007-04-11 Richard Stallman - - * text.texi (Lazy Properties): Minor fix. - -2007-04-08 Karl Berry - - * symbols.texi (Plists and Alists): Period after "vs" in index entries. - * macros.texi (Backquote): Downcase Backquote in index entries for - consistency. - -2007-04-08 Richard Stallman - - * text.texi (Adaptive Fill): Just describe default, - don't show it (since it contains non-ASCII chars). - -2007-04-07 Karl Berry - - * text.texi (Adaptive Fill) [@iftex]: Omit binary characters in - adaptive-fill-regexp's value, since they are not in the standard - TeX fonts. - -2007-04-07 Guanpeng Xu - - * display.texi (Defining Faces): Fix example. - -2007-04-07 Karl Berry - - * display.texi (Button Buffer Commands): Improve page break. - -2007-04-07 Richard Stallman - - * advice.texi (Activation of Advice): Remove redundant index entry. - - * backups.texi: Improve index entries. Remove redundant ones. - - * compile.texi (Byte Compilation): Improve index entry. - - * hash.texi (Creating Hash): Improve index entry. - - * symbols.texi (Definitions): Improve index entry. - - * edebug.texi: Improve index entries. Remove redundant/useless ones. - - * maps.texi (Standard Keymaps): Remove useless index entry. - - * help.texi (Documentation Basics): Remove redundant index entries. - - * customize.texi: Improve index entries. - Remove redundant/useless ones. - - * locals.texi (Standard Buffer-Local Variables): Clarify intro text. - - * streams.texi (Output Variables): Improve index entry. - - * abbrevs.texi (Abbrevs): Remove useless index entry. - - * macros.texi (Expansion): Remove useless index entry. - - * text.texi: Improve index entries. Remove redundant/useless ones. - (Text Properties, Examining Properties) - (Special Properties): Use "property category" instead of "category" - to refer to the `category' property. - - * positions.texi: Improve index entries. Remove useless one. - - * lists.texi: Improve index entries. Remove redundant/useless ones. - - * os.texi: Improve index entries. - (Timers): Fix previous change. - - * buffers.texi: Improve index entries. - (Modification Time): Get rid of term "obsolete buffer". - - * debugging.texi: Improve index entries. - (Test Coverage): Add xref to other test coverage ftr. - - * eval.texi: Improve index entry. Remove redundant ones. - - * numbers.texi: Improve index entries. Remove redundant/useless ones. - - * files.texi: Improve index entries. Remove redundant/useless ones. - - * objects.texi: Improve index entries. - - * processes.texi: Improve index entries. - - * modes.texi: Improve index entry. Remove redundant one. - - * nonascii.texi: Improve index entries. - - * internals.texi: Improve index entries. - - * syntax.texi: Improve index entries. - - * keymaps.texi (Active Keymaps): Improve index entries. - - * commands.texi: Improve index entries. Remove redundant/useless ones. - - * frames.texi: Improve index entries. Remove redundant/useless ones. - - * markers.texi: Improve index entries. Remove redundant ones. - - * tips.texi: Improve index entries. - - * loading.texi (Unloading): Improve index entry. - - * variables.texi: Improve index entries. Remove redundant one. - - * sequences.texi: Improve index entry. - - * display.texi: Improve index entries. Remove redundant ones. - - * windows.texi: Improve index entries. - - * searching.texi: Improve index entries. Remove redundant one. - - * strings.texi (Case Tables): Improve last change. - -2007-04-04 Chong Yidong - - * strings.texi (Case Tables): Document with-case-table and - ascii-case-table. - -2007-04-03 Karl Berry - - * processes.texi (Network): Reword to improve page break. - -2007-04-03 Eli Zaretskii - - * functions.texi (Inline Functions): Describe more disadvantages - of defsubst, and make advice against it stronger. - -2007-04-02 Karl Berry - - * backups.texi (Backup Names): Avoid widow words. - * modes.texi (Example Major Modes): Align last comment. - -2007-04-01 Chong Yidong - - * keymaps.texi (Remapping Commands): Document new arg to - command-remapping. - -2007-04-01 Karl Berry - - * processes.texi (Low-Level Network): Typo. - * loading.texi (Hooks for Loading): Avoid double "the". - * keymaps.texi (Key Sequences): No double "and". - (Changing Key Bindings): Shorten to improve line break. - -2007-03-31 Glenn Morris - - * os.texi (Timers): Fix description of run-at-time TIME formats. - -2007-03-31 Richard Stallman - - * display.texi (Invisible Text): Correct buffer-invisibility-spec - regarding ellipsis. - -2007-03-31 Eli Zaretskii - - * intro.texi (nil and t): - * symbols.texi (Plists and Alists): - * variables.texi (Variable Aliases, Constant Variables): - * functions.texi (Defining Functions): - * advice.texi (Advising Primitives): - * debugging.texi (Syntax Errors, Compilation Errors): - * minibuf.texi (Minibuffer Windows): - * commands.texi (Adjusting Point): - * modes.texi (Syntactic Font Lock, Faces for Font Lock) - (Auto Major Mode, Major Mode Conventions): - * help.texi (Describing Characters): - * files.texi (Create/Delete Dirs, Information about Files) - (File Locks, Writing to Files, Reading from Files) - (Saving Buffers): - * windows.texi (Resizing Windows, Cyclic Window Ordering): - * frames.texi (Finding All Frames): - * positions.texi (Buffer End, Motion): - * markers.texi (The Region): - * text.texi (Deletion, Near Point): - * display.texi (Displaying Messages, Truncation): - * os.texi (Processor Run Time): - * tips.texi (Key Binding Conventions, Programming Tips) - (Warning Tips, Documentation Tips, Comment Tips): - * internals.texi (Memory Usage): Improve indexing. - - * variables.texi (Frame-Local Variables): - * functions.texi (Argument List): - * loading.texi (Library Search): - * streams.texi (Output Variables): - * keymaps.texi (Translation Keymaps, Searching Keymaps): - * searching.texi (Replacing Match, Search and Replace): - * processes.texi (Byte Packing, Decoding Output) - (Accepting Output, Network Servers, Shell Arguments): - * display.texi (Abstract Display, Image Cache, Scroll Bars): - * windows.texi (Window Point, Window Start): - * frames.texi (Management Parameters, Frame Parameters, Frame Titles): - * commands.texi (Reading Input, Keyboard Events): - * minibuf.texi (Reading File Names, Minibuffer Completion) - (Recursive Mini): - * positions.texi (List Motion): - * hash.texi (Hash Tables, Creating Hash, Defining Hash): - * numbers.texi (Arithmetic Operations, Math Functions) - (Predicates on Numbers, Comparison of Numbers): - (Numeric Conversions): - * locals.texi (Standard Buffer-Local Variables): - * maps.texi (Standard Keymaps): - * os.texi (User Identification, System Environment, Recording Input) - (X11 Keysyms): - * nonascii.texi (Non-ASCII Characters, Splitting Characters): - * backups.texi (Backups and Auto-Saving): - * customize.texi (Customization, Group Definitions) - (Variable Definitions): - * compile.texi (Byte Compilation): Improve index entries. - -2007-03-31 Karl Berry - - * macros.texi (Defining Macros): Avoid widow syllable. - -2007-03-31 Eli Zaretskii - - * elisp.texi (Top): Postscript -> PostScript. - - * display.texi (Images, Postscript Images): Postscript -> PostScript. - -2007-03-31 Markus Triska - - * internals.texi (Writing Emacs Primitives): Untabify `For'. - -2007-03-30 Karl Berry - - * lists.texi (List-related Predicates): Remove spurious @need. - (Setcdr): Use @smallexample to improve page break. - (Association Lists) : Reword to improve page break. - - * strings.texi (String Conversion): Insert blank line to improve - page break. - - * numbers.texi (Random Numbers): Use @minus{}. - (Math Functions): Use @minus{}. - - * intro.texi (Acknowledgements): Avoid line breaks before middle - initials. - -2007-03-24 Eli Zaretskii - - * errors.texi (Standard Errors): Add an index entry. - -2007-03-19 Richard Stallman - - * os.texi (Recording Input): recent-keys now gives 300 keys. - -2007-03-12 Glenn Morris - - * os.texi: Replace "daylight savings" with "daylight saving" - throughout. - -2007-03-05 Richard Stallman - - * variables.texi (File Local Variables): - Update enable-local-variables values. - -2007-03-04 Richard Stallman - - * syntax.texi (Control Parsing): Minor clarification. - - * strings.texi (Formatting Strings): Clarify width, precision, flags. - - * sequences.texi (Sequence Functions): Move string-bytes away, - add xref. - - * nonascii.texi (Text Representations): Move string-bytes here. - - * modes.texi (Major Mode Conventions): Fundamental mode is exception. - - * minibuf.texi (Basic Completion): Minor clarification. - - * markers.texi (The Mark): Clarify existence vs activation of mark. - Other cleanup. - - * display.texi (Finding Overlays): Write better example. - - * compile.texi (Eval During Compile): Clarify putting macros - in eval-when-compile. - -2007-02-25 Vinicius Jose Latorre (tiny change) - - * loading.texi (How Programs Do Loading): Fix anchor position at - load-read-function definition doc. - -2007-02-21 Kim F. Storm - - * strings.texi (Text Comparison): Mention that assoc-string - converts symbols to strings before testing. - -2007-02-17 Kim F. Storm - - * processes.texi (Bindat Spec): Vector types can have optional - element type. - (Bindat Examples): Fix example. Add vector with element type. - -2007-02-16 Andreas Schwab - - * strings.texi (Formatting Strings): Document '+' flag. - -2007-02-15 Juanma Barranquero - - * strings.texi (Modifying Strings): Clarify that `clear-string' - always converts the string to unibyte. - -2007-02-14 Kim F. Storm - - * display.texi (Glyphs): Add make-glyph-code, glyph-char, glyph-face. - Rewrite glyph code description to refer to these functions. - Remove details of encoding face number and char into integer code. - -2007-02-03 Alan Mackenzie - - * loading.texi (Hooks for Loading): Make the description of - `eval-after-load' more detailed, and amend the description of - after-load-alist, in accordance with changes from 2006-05. - -2007-02-03 Chong Yidong - - * modes.texi (Defining Minor Modes): Document that a :require - keyword or similar may be required to make saved customization - variables work. - -2007-02-03 Eli Zaretskii - - * elisp.texi (Top): Make the detailed menu headers compliant with - Texinfo guidelines and with what texnfo-upd.el expects. - Add comments to prevent people from inadvertently modifying the key - parts needed by `texinfo-multiple-files-update'. - -2007-02-02 Eli Zaretskii - - * elisp.texi (Top): Update the top-level menus. - - * syntax.texi (Categories): Add index entries. - -2007-02-01 Juanma Barranquero - - * display.texi (Attribute Functions): Fix name and description of - the UNDERLINE arg of `set-face-underline-p'. - -2007-01-29 Eli Zaretskii - - * elisp.texi (Top): Add "Standard Errors", "Standard Buffer-Local - Variables", and "Standard Keymaps" to the detailed menu. - - * variables.texi (Future Local Variables): Add index entry. - -2007-01-28 Richard Stallman - - * tips.texi (Coding Conventions): Clarify the tip about macros - that define a function or a variable. - - * files.texi (File Attributes): UID and GID can be floats. - (Magic File Names): Explain why deferring all operations to - the standard handler does not work. - -2007-01-23 Martin Rudalics - - * backups.texi (Reverting): Use "buffer" instead of "file" - when talking about major and minor modes. - -2007-01-21 Richard Stallman - - * help.texi (Documentation): Add xref to Documentation Tips. - -2007-01-14 Juanma Barranquero - - * tips.texi (Coding Conventions): Fix typos. - -2007-01-05 Richard Stallman - - * modes.texi (Defining Minor Modes): Fix previous change. - -2007-01-03 Richard Stallman - - * customize.texi (Variable Definitions, Customization Types): - Don't use * in doc string for defcustom. - -2007-01-02 Richard Stallman - - * variables.texi (Variable Aliases): Clarify that aliases vars - always have the same value. - - * processes.texi (Bindat Spec): Fix Texinfo usage. - - * modes.texi (Defining Minor Modes): Explain effect of command - defined with define-global-minor-mode on new buffers. - -2006-12-30 Kim F. Storm - - * keymaps.texi (Tool Bar): Describe `grow-only' value of - `auto-resize-tool-bars'. - -2006-12-30 Richard Stallman - - * keymaps.texi (Active Keymaps): Fix previous change. - -2006-12-30 Nick Roberts - - * keymaps.texi (Active Keymaps): Make xref to lookup-key. - -2006-12-30 Kim F. Storm - - * processes.texi (Bindat Spec): Clarify using field names in - length specifications. - -2006-12-29 Kim F. Storm - - * processes.texi (Bindat Spec): Explain eval forms and lengths better. - Add count and index variables for eval forms in repeat blocks. - -2006-12-24 Richard Stallman - - * customize.texi (Variable Definitions): - Document new name custom-add-frequent-value. - -2006-12-19 Kim F. Storm - - * commands.texi (Misc Events): User signals now result in sigusr1 - and sigusr2 events which are handled through special-event-map. - (Special Events): User signals and drag-n-drop are special. - -2006-12-17 Richard Stallman - - * loading.texi (Named Features): Explain subfeatures better. - - * customize.texi: Use "option" only for user options. - For the keyword values inside defcustom etc, say "keywords". - For :options value's elements, say "elements". - :group should not be omitted. - - * syntax.texi (Parsing Expressions): Split up node. - (Motion via Parsing, Position Parse, Parser State) - (Low-Level Parsing, Control Parsing): New subnodes. - (Parser State): Document syntax-ppss-toplevel-pos. - - * positions.texi (List Motion): Punctuation fix. - - * files.texi (File Name Completion): Document PREDICATE arg - to file-name-completion. - -2006-12-16 Eli Zaretskii - - * internals.texi (Building Emacs, Writing Emacs Primitives): - Add index entries. - -2006-12-11 Richard Stallman - - * modes.texi (Font Lock Basics): Explain how nil for font-lock-defaults - affects face menu. Explain how to make it non-nil without enabling - any fontification. - -2006-12-10 Chong Yidong - - * modes.texi (Font Lock Basics): Document nil value of - font-lock-defaults. - -2006-12-10 Glenn Morris - - * abbrevs.texi (Defining Abbrevs): Mention `define-abbrev' 'force - value for system-flag argument. Abbrev tables may not be empty - when major modes are loaded. - -2006-12-08 Juanma Barranquero - - * makefile.w32-in (maintainer-clean): Partially revert last - change; delete "elisp-?" and "elisp-??" instead of "elisp-*" - to protect elisp-covers.texi. - -2006-12-07 Juanma Barranquero - - * makefile.w32-in (maintainer-clean): Depend on `distclean'. - Don't remove elisp* info files; they are already deleted by the - `clean' and `distclean' targets, and they are in the $(infodir) - directory, not the current one. - -2006-12-04 Kim F. Storm - - * commands.texi (Misc Events): Update signal events. - (Event Examples): Add signal example. - -2006-11-29 Richard Stallman - - * frames.texi (Visibility of Frames): Explain visible windows - can be covered by others. Add xref for raise-frame. - -2006-11-28 Richard Stallman - - * searching.texi (Regexp Special): Update when ^ is special. - -2006-11-27 Eli Zaretskii - - * customize.texi (Customization, Common Keywords) - (Group Definitions, Variable Definitions, Composite Types) - (Type Keywords, Customization Types): Add index entries for - various customization keywords. - -2006-11-23 Stefan Monnier - - * modes.texi (Multiline Font Lock): Rephrase some parts for clarity. - -2006-11-10 Jan Djärv - - * frames.texi (Window System Selections): Remove clipboard from - description of selection-coding-system. - -2006-11-06 Richard Stallman - - * lists.texi (List Variables): Document COMPARE-FN. - - * keymaps.texi: Avoid use of "binding" to mean a relation; - use it only to refer to the meaning associated with a key. - (Keymaps): Change menu node description. - - * elisp.texi (Top): Change menu node description. - - * display.texi (Managing Overlays): Document overlay-recenter. - -2006-10-29 Chong Yidong - - * Makefile.in: Use relative paths to avoid advertising filesystem - contents during compilation. - -2006-10-23 Kim F. Storm - - * commands.texi (Event Input Misc): Update unread-command-events. - -2006-10-23 Nick Roberts - - * lists.texi (Sets And Lists): Fix typos. - -2006-10-18 Juanma Barranquero - - * control.texi (Processing of Errors): Use @var for an argument, - not @code. - -2006-10-16 Richard Stallman - - * edebug.texi (Edebug Recursive Edit): Minor cleanup. - - * keymaps.texi (Format of Keymaps): Show all the keymap element - patterns that result from menu items. - (Key Lookup): Minor cleanups. - - * modes.texi (Precalculated Fontification): Don't say that - not setting font-lock-defaults avoids loading font-lock. - - * help.texi (Documentation): Move xref to Emacs Manual here. - (Documentation Basics): From here. - Also doc emacs-lisp-docstring-fill-column. - - * elisp.texi: Update version and ISBN. - - * commands.texi (Interactive Call): Clarify KEYS arg to - call-interactively is a vector. - (Command Loop Info): Delete anchor in this-command-keys. - Add anchor in this-command-keys-vector. - (Recursive Editing): Document how recursive-edit - handles the current buffer. - -2006-10-13 Chong Yidong - - * frames.texi (Frame Titles): %c and %l are ignored in - frame-title-format. - -2006-10-11 Richard Stallman - - * keymaps.texi (Key Sequences): Clarify use of kbd. - -2006-10-10 Kim F. Storm - - * lists.texi (Sets And Lists): Add memql. - -2006-10-03 Richard Stallman - - * searching.texi (Char Classes): Document :multibyte: and :unibyte:. - Clarify :ascii: and :nonascii:. - -2006-09-29 Juri Linkov - - * modes.texi (%-Constructs): Reorder coding systems in the - documentation of %z to the real order displayed in the modeline. - -2006-09-25 Richard Stallman - - * os.texi (Timers): Describe timer-max-repeats. - -2006-09-25 Chong Yidong - - * os.texi (Timers): Mention with-local-quit. - -2006-09-24 Richard Stallman - - * searching.texi (Searching and Matching): Mention property search. - - * commands.texi (Command Loop Info): Explain how read-event affects - this-command-keys. - -2006-09-20 Richard Stallman - - * os.texi (Timers): Clarify about REPEAT when timer is delayed. - - * windows.texi (Window Start): Minor cleanups. - -2006-09-20 Kim F. Storm - - * windows.texi (Window Start): pos-visible-in-window-p allows - specifying t for position to mean "end of window". - Add window-line-height. - - * anti.texi (Antinews): Mention window-line-height. - -2006-09-19 David Kastrup - - * keymaps.texi (Searching Keymaps): Small clarification. - -2006-09-18 Richard Stallman - - * keymaps.texi (Creating Keymaps): Explain that keymap prompt strings - cause keyboard menus. - (Menu Keymaps): Likewise. - (Defining Menus, Keyboard Menus): Clarify. - - * text.texi (Fields): Clarify explanation of constrain-to-field. - -2006-09-16 Eli Zaretskii - - * variables.texi (Tips for Defining): Fix a typo. - -2006-09-15 Richard Stallman - - * keymaps.texi (Remapping Commands, Searching Keymaps) - (Active Keymaps): Clean up previous change. - -2006-09-15 Jay Belanger - - * gpl.texi: Replace "Library Public License" by "Lesser Public - License" throughout. - -2006-09-15 David Kastrup - - * keymaps.texi (Active Keymaps): Adapt description to use - `get-char-property' instead `get-text-property'. Explain how - mouse events change this. Explain the new optional argument of - `key-binding' and its mouse-dependent lookup. - (Searching Keymaps): Adapt description similarly. - (Remapping Commands): Explain the new optional argument of - `command-remapping'. - -2006-09-14 Richard Stallman - - * keymaps.texi (Searching Keymaps): Clarification. - (Active Keymaps): Refer to Searching Keymaps instead of duplication. - -2006-09-13 Richard Stallman - - * objects.texi (Character Type): Node split. - Add xref to Describing Characters. - (Basic Char Syntax, General Escape Syntax) - (Ctl-Char Syntax, Meta-Char Syntax): New subnodes. - -2006-09-11 Richard Stallman - - * display.texi (Display Table Format): Wording clarification. - (Glyphs): Clarifications. - -2006-09-10 Chong Yidong - - * keymaps.texi (Active Keymaps): Mention that key-binding checks - local maps. - -2006-09-10 Kim F. Storm - - * display.texi (Forcing Redisplay): Document return value of - function redisplay. - -2006-09-09 Richard Stallman - - * windows.texi (Window Hooks): Explain limits of - window-scroll-functions. - - * display.texi (Fringe Indicators): Update for last change in - indicate-buffer-boundaries. - -2006-09-08 Richard Stallman - - * processes.texi (Bindat Spec): Suggest names ending in -bindat-spec. - -2006-09-06 Kim F. Storm - - * frames.texi (Display Feature Testing): display-mm-dimensions-alist. - - * windows.texi (Window Start): Update pos-visible-in-window-p. - -2006-09-04 Richard Stallman - - * processes.texi (Accepting Output): Explain SECONDS=0 for - accept-process-output. - - * os.texi (Idle Timers): Explain why timer functions should not - loop until (input-pending-p). - -2006-09-02 Eli Zaretskii - - * makefile.w32-in (usermanualdir): New variable. - (elisp.dvi): Use it. - -2006-09-01 Eli Zaretskii - - * buffers.texi (Buffer Modification): Fix last change. - -2006-09-01 Chong Yidong - - * buffers.texi (Buffer Modification): - Document buffer-chars-modified-tick. - -2006-08-31 Richard Stallman - - * modes.texi (Syntactic Font Lock): Mention specific faces once again. - -2006-08-31 Richard Bielawski (tiny change) - - * modes.texi (Syntactic Font Lock): - Mention font-lock-syntactic-face-function - instead of specific faces. - -2006-08-29 Chong Yidong - - * display.texi (Images): Add xrref to display-images-p. - -2006-08-28 Kenichi Handa - - * nonascii.texi (Lisp and Coding Systems): Fix description of - detect-coding-region. - -2006-08-27 Michael Olson - - * processes.texi (Transaction Queues): Remove stray quote - character. - -2006-08-25 Richard Stallman - - * os.texi (Idle Timers): run-with-idle-timer allows Lisp time value. - Add xref. - -2006-08-24 Chong Yidong - - * os.texi (Timers): Avoid waiting inside timers. - -2006-08-21 Lute Kamstra - - * Makefile.in: Use ../man/texinfo.tex to build elisp.dvi. - -2006-08-20 Richard Stallman - - * os.texi (Idle Timers): New node, split out from Timers. - Document current-idle-time. - * commands.texi (Reading One Event): Update xref. - * elisp.texi (Top): Update subnode menu. - -2006-08-16 Richard Stallman - - * keymaps.texi (Extended Menu Items): Show format of cached - bindings in extended menu items. - - * customize.texi (Variable Definitions): Explain when the - standard value expression is evaluated. - -2006-08-15 Chong Yidong - - * commands.texi (Reading One Event): Explain idleness in - `read-event'. - -2006-08-12 Chong Yidong - - * text.texi (Near Point): Say "cursor" not "terminal cursor". - (Commands for Insertion): Remove split-line since it's not - relevant for Lisp programming. - (Yank Commands): Rewrite introduction. - (Undo): Clarify. - (Maintaining Undo): Clarify. Document undo-ask-before-discard. - (Filling): Remove redundant comment. Clarify return value of - current-justification. - (Margins): Minor clarifications. - (Adaptive Fill): Update default value of adaptive-fill-regexp. - (Sorting): Update definition of sort-lines. - (Columns): Clarify behavior of sort-columns. - (Indent Tabs): Link to Tab Stops in Emacs manual. - (Special Properties): Clarify. - (Clickable Text): Mention Buttons package. - -2006-08-12 Kevin Ryde - - * os.texi (Time Parsing): Add %z to description of - format-time-string, as per docstring. Add cross reference to - glibc manual for strftime. - -2006-08-08 Richard Stallman - - * modes.texi: Clean up wording in previous change. - -2006-08-07 Chong Yidong - - * modes.texi (Hooks): Clarify. - (Major Mode Basics): Mention define-derived-mode explicitly. - (Major Mode Conventions): Rebinding RET is OK for some modes. - Mention change-major-mode-hook and after-change-major-mode-hook. - (Example Major Modes): Move to end of Modes section. - (Mode Line Basics): Clarify. - (Mode Line Data): Mention help-echo and local-map in strings. - Explain reason for treatment of non-risky variables. - (Properties in Mode): Clarify. - (Faces for Font Lock): Add font-lock-negation-char-face. - -2006-08-04 Eli Zaretskii - - * strings.texi (Formatting Strings): Warn against arbitrary - strings as first arg to `format'. - -2006-07-31 Thien-Thi Nguyen - - * text.texi (Clickable Text): Mention `help-echo' text property. - Update intro, examples and associated explanations. - -2006-07-31 Richard Stallman - - * commands.texi: Update xrefs. - (Event Mod): New node, cut out from old Translating Input. - - * maps.texi: Update xrefs. - - * keymaps.texi (Translation Keymaps): New node. - Update xrefs from Translating Input to Translation Keymaps. - - * elisp.texi (Top): Update subnode menu. - - * display.texi (Face Functions): Fix explanations of FRAME=t or nil. - - * os.texi (System Interface): Fix menu descriptions of some nodes. - (Translating Input): Node deleted. - -2006-07-31 Nick Roberts - - * modes.texi (Minor Mode Conventions): Update xref for add-to-list. - - * lists.texi (Sets And Lists): Likewise. - -2006-07-30 Thien-Thi Nguyen - - * text.texi (Fields): Mention POS - requirement when narrowing is in effect. - -2006-07-28 Richard Stallman - - * display.texi (Face Attributes): Simplify wording. - (Attribute Functions): Clarify meaning of new-frame default - attribute settings. - - * customize.texi (Common Keywords): Document how to use - :package-version in a package not in Emacs. - -2006-07-28 Kim F. Storm - - * commands.texi (Reading One Event): Fix last change. - -2006-07-26 Chong Yidong - - * commands.texi (Reading One Event): Document SECONDS argument for - read-event, read-char, and read-char-exclusive. - -2006-07-25 Stefan Monnier - - * modes.texi (Multiline Font Lock): Can't use jit-lock-defer-multiline - to ensure correct identification. - -2006-07-24 Richard Stallman - - * text.texi (Clickable Text): Clarify. - - * sequences.texi (Vector Functions): Delete duplicate xref. - - * objects.texi (Function Type): Clarify. - - * modes.texi (Keymaps and Minor Modes): List punct chars for minor - modes. - - * lists.texi (List Variables): New node. - Material moved from other nodes. - - * variables.texi (Setting Variables): add-to-list and - add-to-ordered-list moved to List Variables node. - -2006-07-23 Thien-Thi Nguyen - - * text.texi (Links and Mouse-1): - For mouse-on-link-p, expand on arg POS. - -2006-07-21 Kim F. Storm - - * display.texi (Forcing Redisplay): Don't mention systems which - don't support sub-second timers for redisplay-preemption-period. - - * os.texi (Terminal Output): Clarify text vs graphical terminal. - -2006-07-21 Eli Zaretskii - - * frames.texi (Input Focus): Document that focus-follows-mouse has - no effect on MS-Windows. - -2006-07-18 Richard Stallman - - * display.texi (Forcing Redisplay): Cleanups in previous change. - - * processes.texi (Low-Level Network): Make menu more convenient. - -2006-07-18 Kim F. Storm - - * display.texi (Forcing Redisplay): redisplay-preemption-period - only used on window systems. Add xref to Terminal Output. - - * os.texi (Terminal Output): baud-rate only controls preemption on - non-window systems. Add xref to Forcing Redisplay. - - * processes.texi (Low-Level Network): Rename node "Make Network" - to "Network Processes". - -2006-07-18 Karl Berry - - * variables.texi, functions.texi, customize.texi, loading.texi: - * edebug.texi, minibuf.texi: Fix page breaks through chapter 20. - -2006-07-17 Chong Yidong - - * commands.texi (Waiting): Document batch-mode sit-for behavior. - -2006-07-17 Richard Stallman - - * eval.texi, elisp.texi, text.texi: Use real doublequote inside menus. - Put period and comma inside quotes. - - * loading.texi, markers.texi: Use real doublequote inside menus. - - * windows.texi: Put point and comma inside quotes. - (Textual Scrolling): Use @samp for error message. - - * variables.texi, tips.texi, syntax.texi, symbols.texi: - * strings.texi, streams.texi, processes.texi, os.texi: - * objects.texi, numbers.texi, modes.texi, minibuf.texi: - * lists.texi, keymaps.texi, intro.texi, hash.texi, internals.texi: - * gpl.texi, functions.texi, files.texi, frames.texi, doclicense.texi: - * display.texi, control.texi, commands.texi, buffers.texi, anti.texi: - Put point and comma inside quotes. - - * control.texi (Processing of Errors): Add command-error-function. - - * variables.texi (File Local Variables): Clarify that - file local variables make buffer-local bindings. - - * modes.texi (Syntactic Font Lock): Give default for - font-lock-syntax-table. - -2006-07-17 Nick Roberts - - * text.texi (Special Properties): Clean up previous change. - -2006-07-16 Karl Berry - - * objects.texi, numbers.texi, strings.texi, lists.texi, hash.texi: - * control.texi: Fix bad page breaks through chapter 10 (control). - - * anti.texi (Antinews): Reorder face-attribute fns to avoid - underfull hbox. - -2006-07-15 Nick Roberts - - * text.texi (Special Properties): Describe fontified text property - in relation to a character (not text). - -2006-07-15 Kim F. Storm - - * maps.texi (Standard Keymaps): Add xref for minibuffer maps. - Add apropos-mode-map, custom-mode-map, esc-map, global-map, - grep-mode-map, help-map, help-mode-map, kmacro-map, and tool-bar-map. - - * anti.texi (Antinews): Mention redisplay function. - The kbd macro existed, but was not documented, before 22.x. - Function pos-visible-in-window-p is not new in 22.x, just enhanced. - -2006-07-14 Nick Roberts - - * display.texi (Displaying Messages): Add anchor. - - * frames.texi (Dialog Boxes): Use it. - -2006-07-12 Richard Stallman - - * objects.texi (Frame Type): Explain nature of frames better. - - * frames.texi (Frames): Explain nature of frames better. - -2006-07-12 Ken Manheimer - - * tips.texi (Coding Conventions): Explain why use cl at compile time. - -2006-07-12 YAMAMOTO Mitsuharu - - * frames.texi (Window System Selections): Mention scrap support for Mac. - Default value of x-select-enable-clipboard is t on Mac. - - * os.texi (Getting Out): Suspending is not allowed on Mac, either. - -2006-07-11 Kim F. Storm - - * display.texi (Forcing Redisplay): Add `redisplay' function. - Don't mention (sit-for -1) -- use (redisplay t) instead. - - * commands.texi (Waiting): (sit-for -1) is no longer special. - (sit-for 0) is equivalent to (redisplay). - Iconifying/deiconifying no longer makes sit-for return. - -2006-07-10 Nick Roberts - - * display.texi (Buttons): Fix typo. - - * index.texi, elisp.texi (New Symbols): Comment node out. - -2006-07-09 Richard Stallman - - * display.texi (Truncation): Clean up previous change. - -2006-07-08 Richard Stallman - - * commands.texi (Interactive Call): Use 3 as prefix in example - for execute-extended-command. - - * display.texi (Attribute Functions): Move paragraph about - compatibility with Emacs < 21. - -2006-07-09 Kim F. Storm - - * display.texi (Refresh Screen): Clarify force-window-update. - (Truncation): "Normally" indicated by fringe arrows. - -2006-07-08 Eli Zaretskii - - * windows.texi (Textual Scrolling, Resizing Windows): - * variables.texi (Constant Variables): - * text.texi (Buffer Contents, Deletion, Changing Properties) - (Property Search, Special Properties, Sticky Properties) - (Links and Mouse-1, Fields, Change Hooks): - * syntax.texi (Syntax Table Functions, Parsing Expressions) - (Categories): - * symbols.texi (Other Plists): - * streams.texi (Output Variables): - * processes.texi (Input to Processes, Query Before Exit): - * positions.texi (Word Motion, Text Lines, List Motion): - * os.texi (Init File, System Environment, Sound Output) - (Session Management): - * nonascii.texi (Text Representations, Character Sets) - (Chars and Bytes, Locales): - * modes.texi (Defining Minor Modes, Header Lines): - * minibuf.texi (Minibuffer Contents): - * markers.texi (Information from Markers): - * lists.texi (List Elements, Building Lists, Association Lists): - * keymaps.texi (Tool Bar): - * hash.texi (Creating Hash, Hash Access, Defining Hash, Other Hash): - * functions.texi (What Is a Function, Mapping Functions): - * frames.texi (Creating Frames, Parameter Access, Pointer Shape) - (Color Names, Text Terminal Colors, Display Feature Testing): - * files.texi (Visiting Functions, File Name Components) - (Unique File Names, Contents of Directories): - * display.texi (Forcing Redisplay, Displaying Messages) - (Temporary Displays, Font Selection, Auto Faces) - (Font Lookup, Fringe Indicators, Display Margins) - (Image Descriptors, Showing Images, Image Cache, Button Types) - (Making Buttons, Manipulating Buttons, Button Buffer Commands) - (Display Table Format, Glyphs): - * control.texi (Iteration): - * commands.texi (Command Loop Info, Adjusting Point): - * backups.texi (Making Backups, Auto-Saving): - Remove @tindex entries. - -2006-07-07 Kim F. Storm - - * display.texi (Fringe Cursors): Fix typo. - (Customizing Bitmaps): Fix define-fringe-bitmap entry. - (Overlay Arrow): Default is overlay-arrow fringe indicator. - -2006-07-05 Richard Stallman - - * text.texi (Buffer Contents): Add example of text props - in result of buffer-substring. - (Text Properties): Explain better about use of specific property names. - (Property Search): Some cleanups; reorder some functions. - - * keymaps.texi (Changing Key Bindings): Cleanup. - Add xref to Key Binding Conventions. - - * display.texi (Attribute Functions): Add examples for - face-attribute-relative-p. - - * tips.texi (Coding Conventions): Cleanup last change. - -2006-07-05 Karl Berry - - * elisp.texi: Use @fonttextsize 10pt, a la emacs.texi. - Remove @setchapternewpage odd. - Result is 1013 pages, down from 1100. - - * anti.texi, customize.texi, display.texi, internals.texi: - * minibuf.texi, modes.texi, tips.texi: - Fix overfull/underfull boxes. - -2006-07-05 Thien-Thi Nguyen - - * edebug.texi (Instrumenting): - Add Edebug-specific findex for eval-buffer. - * loading.texi (Loading): - Replace eval-current-buffer with eval-buffer. - -2006-06-30 Nick Roberts - - * locals.texi (Standard Buffer-Local Variables): Update the list - of variables. - -2006-06-26 Nick Roberts - - * files.texi (File Name Completion): Point user to the node - "Reading File Names". - -2006-06-24 Eli Zaretskii - - * files.texi (Contents of Directories): Document case-insensitive - behavior on respective filesystems. - - * objects.texi (Character Type): Document that Emacs signals an - error for unsupported Unicode characters specified as \uNNNN. - -2006-06-19 Richard Stallman - - * processes.texi (Bindat Spec): Clarify previous change. - -2006-06-16 Richard Stallman - - * tips.texi (Coding Conventions): Better explain conventions - for definition constructs. - - * text.texi (Special Properties): String value of `read-only' - serves as the error message. - - * objects.texi (Character Type): Clarify prev. change. - (Non-ASCII in Strings): Mention \u and \U. - - * commands.texi (Using Interactive): Explain problem of - markers, etc., in command-history. - -2006-06-14 Kim F. Storm - - * commands.texi (Waiting): Negative arg to sit-for forces - redisplay even if input is pending. - - * display.texi (Forcing Redisplay): Use (sit-for -1) to force a - redisplay. Remove incorrect example of binding redisplay-dont-pause - around (sit-for 0). - -2006-06-13 Richard Stallman - - * display.texi (Forcing Redisplay): Clarify previous change. - -2006-06-13 Romain Francoise - - * display.texi (Forcing Redisplay): Fix typo. - -2006-06-13 Kim F. Storm - - * display.texi (Forcing Redisplay): Add redisplay-preemption-period. - -2006-06-10 Luc Teirlinck - - * tips.texi (Coding Conventions): Add `@end itemize'. - -2006-06-10 Richard Stallman - - * tips.texi (Coding Conventions): Explain use of coding systems - to ensure one decoding for strings. - -2006-06-09 Aidan Kehoe - - * objects.texi (Character Type): Describe the \uABCD and \U00ABCDEF - syntax. - -2006-06-07 Eli Zaretskii - - * display.texi (Font Selection): Remove description of - clear-face-cache. - - * compile.texi (Eval During Compile): Fix a typo. Add index - entries for possible uses of eval-when-compile. - -2006-06-04 Thien-Thi Nguyen - - * display.texi (Abstract Display): Fix typo. - -2006-06-03 Eli Zaretskii - - * minibuf.texi (Minibuffer History) : - Reword variable's description. - -2006-06-01 Richard Stallman - - * windows.texi (Splitting Windows): Clarify splitting nonselected - window. - -2006-05-31 Juri Linkov - - * minibuf.texi (Minibuffer History): Add history-add-new-input. - -2006-05-30 Richard Stallman - - * display.texi (Line Height): Fix errors in description of - default line height and line-height property. - - * nonascii.texi (Default Coding Systems): Further clarification. - -2006-05-29 Luc Teirlinck - - * internals.texi (Pure Storage): Mention that an overflow in pure - space causes a memory leak. - (Garbage Collection): If there was an overflow in pure space, - `garbage-collect' returns nil. - -2006-05-30 Eli Zaretskii - - * nonascii.texi (Default Coding Systems): Fix it some more. - -2006-05-29 Eli Zaretskii - - * nonascii.texi (Default Coding Systems): Fix last change. - -2006-05-29 Kenichi Handa - - * nonascii.texi (find-operation-coding-system): Describe the new - argument format (FILENAME . BUFFER). - -2006-05-28 Richard Stallman - - * tips.texi (Coding Conventions): Better explain reasons not to - advise other packages or use `eval-after-load'. - -2006-05-29 Kim F. Storm - - * processes.texi (Bindat Functions): Rename `pos' and `raw-data' to - `bindat-idx' and `bindat-raw' for clarity. - -2006-05-27 Thien-Thi Nguyen - - * processes.texi (Bindat Spec): Expand on `repeat' handler. - - * display.texi (Display): Add "Abstract Display" to menu. - (Abstract Display, Abstract Display Functions) - (Abstract Display Example): New nodes. - * elisp.texi (Top): Add "Abstract Display" to menu. - -2006-05-27 Chong Yidong - - * keymaps.texi (Key Sequences): Link to input events definition. - (Format of Keymaps): Delete material duplicated in Keymap Basics. - - * files.texi (Changing Files): Document updated argument list for - copy-file. - -2006-05-27 Thien-Thi Nguyen - - * processes.texi (Bindat Functions): Explain term "total length". - Use it in bindat-length and bindat-pack descriptions. - -2006-05-26 Eli Zaretskii - - * tips.texi (Coding Conventions): Advise against using - eval-after-load in packages. Add an index entry. - -2006-05-25 Juri Linkov - - * minibuf.texi (Text from Minibuffer): Undocument keep-all. - - * modes.texi (%-Constructs): Add %e, %z, %Z. - -2006-05-25 Richard Stallman - - * elisp.texi (Top): Update subnode menu. - - * keymaps.texi (Keymap Basics): New node, split out of Key Sequences. - (Keymaps): Update menu. - -2006-05-25 Chong Yidong - - * keymaps.texi (Key Sequences): Some clarifications. - -2006-05-25 Thien-Thi Nguyen - - * processes.texi (Bindat Functions): Say "unibyte string" - explicitly for bindat-unpack and bindat-pack descriptions. - (Bindat Examples): Don't call `string-make-unibyte' in example. - -2006-05-25 Chong Yidong - - * keymaps.texi (Key Sequences): Rename from Keymap Terminology. - Explain string and vector representations of key sequences. - - * keymaps.texi (Changing Key Bindings): - * commands.texi (Interactive Codes): - * help.texi (Describing Characters): Refer to it. - -2006-05-23 Luc Teirlinck - - * frames.texi (Pointer Shape): @end table -> @end defvar. - -2006-05-22 Richard Stallman - - * elisp.texi (Top): Update subnode menus. - - * frames.texi (Pointer Shape): Node renamed from Pointer Shapes. - Contents rewritten; material from old Pointer Shape node moved here. - - * display.texi (Pointer Shape): Node deleted. - (Image Descriptors): Minor cleanup. - -2006-05-21 Richard Stallman - - * syntax.texi (Parsing Expressions): Update info on which STATE - elements are ignored. - -2006-05-19 Luc Teirlinck - - * hooks.texi (Standard Hooks): Correct typo. - - * gpl.texi (GPL): ifinfo -> ifnottex. - -2006-05-19 Michael Ernst (tiny change) - - * searching.texi (Simple Match Data): Warn about match data being - set anew by every search. - -2006-05-17 Richard Stallman - - * minibuf.texi (Minibuffer History): Clarify. - - * searching.texi (Regexp Special): Clarify nested regexp warning. - -2006-05-16 Kim F. Storm - - * minibuf.texi (Minibuffer History): Update add-to-history. - -2006-05-15 Oliver Scholz (tiny change) - - * nonascii.texi (Explicit Encoding): - Fix typo (encoding<->decoding). - -2006-05-14 Richard Stallman - - * buffers.texi (Creating Buffers): Cleanup. - - * files.texi (Visiting Functions): Rewrite in find-file-noselect. - -2006-05-13 Eli Zaretskii - - * buffers.texi (Current Buffer): Document that with-temp-buffer - disables undo. - - * os.texi (Terminal-Specific): More accurate description of how - Emacs searches for the terminal-specific libraries. - -2006-05-12 Eli Zaretskii - - * hooks.texi (Standard Hooks) [iftex]: Convert @xref's to - emacs-xtra to @inforef's. - - * text.texi (Undo): Document that undo is turned off in buffers - whose names begin with a space. - - * buffers.texi (Buffer Names): Add index entries for buffers whose - names begin with a space. - (Creating Buffers): Document that undo is turned off in buffers - whose names begin with a space. - - * files.texi (Visiting Functions, Reading from Files) - (Saving Buffers): Mention code and EOL conversions by file I/O - primitives and subroutines. - - * nonascii.texi (Lisp and Coding Systems): - Document coding-system-eol-type. Add index entries for eol conversion. - - * display.texi (Defining Faces): Mention `mac', and add an xref to - where window-system is described. - -2006-05-10 Richard Stallman - - * internals.texi (Writing Emacs Primitives): Clarify GCPRO rules. - -2006-05-10 Reiner Steib - - * variables.texi (File Local Variables): Recommend to quote lambda - expressions in safe-local-variable property. - -2006-05-09 Richard Stallman - - * variables.texi (File Local Variables): - Document safe-local-eval-forms and safe-local-eval-function. - -2006-05-07 Kim F. Storm - - * minibuf.texi (Minibuffer History): Remove keep-dups arg - from add-to-history. - -2006-05-07 Romain Francoise - - * commands.texi (Event Input Misc): - * compile.texi (Eval During Compile): - * internals.texi (Buffer Internals): - * minibuf.texi (Initial Input): - * nonascii.texi (Scanning Charsets): - * numbers.texi (Comparison of Numbers): - * windows.texi (Textual Scrolling, Vertical Scrolling): - Fix various typos. - -2006-05-06 Eli Zaretskii - - * hooks.texi (Standard Hooks): Replace inforef to emacs-xtra by - conditional xref's to either emacs or emacs-xtra, depending on - @iftex/@ifnottex. - - * minibuf.texi (Minibuffer History): Document add-to-history. - -2006-05-05 Eli Zaretskii - - * internals.texi (Pure Storage): Mention the pure overflow message - at startup. - -2006-05-05 Johan BockgÃ¥rd - - * keymaps.texi (Active Keymaps): Fix pseudo-Lisp syntax. - (Searching Keymaps): Fix pseudo-Lisp description of keymap - search. - -2006-05-01 Richard Stallman - - * intro.texi (nil and t): Clarify. - - * variables.texi (File Local Variables): Suggest using booleanp. - -2006-05-01 Juanma Barranquero - - * objects.texi (Type Predicates): Fix typos. - -2006-05-01 Stefan Monnier - - * intro.texi (nil and t): Add booleanp. - - * objects.texi (Type Predicates): Add links for booleanp and - string-or-null-p. - -2006-04-29 Richard Stallman - - * modes.texi (Multiline Font Lock): Rename from - Multi line Font Lock Elements. Much clarification. - (Font Lock Multiline, Region to Fontify): Much clarification. - -2006-04-29 Stefan Monnier - - * variables.texi (File Local Variables): Remove the special case t for - safe-local-variable. - -2006-04-26 Richard Stallman - - * syntax.texi (Parsing Expressions): Minor cleanup. - -2006-04-18 Richard Stallman - - * tips.texi (Coding Conventions): Explain when the package's - prefix should appear later on (not at the start of the name). - - * searching.texi (String Search): Clarify effect of NOERROR. - - * modes.texi (Imenu): Clarify what special items do. - - * hooks.texi (Standard Hooks): Delete text about old hook names. - -2006-04-17 Romain Francoise - - * variables.texi (Local Variables): Update the default value of - `max-specpdl-size'. - -2006-04-15 Michael Olson - - * processes.texi (Transaction Queues): Mention the new optional - `delay-question' argument for `tq-enqueue'. - -2006-04-13 Bill Wohler - - * customize.texi (Common Keywords): Use dotted notation for - :package-version value. Specify its values. Improve documentation - for customize-package-emacs-version-alist. - -2006-04-12 Bill Wohler - - * customize.texi (Common Keywords): Move description of - customize-package-emacs-version-alist to @defvar. - -2006-04-10 Bill Wohler - - * customize.texi (Common Keywords): Add :package-version. - -2006-04-10 Kim F. Storm - - * text.texi (Buffer Contents): Add NOPROPS arg to - filter-buffer-substring. - -2006-04-08 Kevin Ryde - - * os.texi (Command-Line Arguments): Update xref to emacs manual - "Command Arguments" -> "Emacs Invocation", per change there. - -2006-04-08 Thien-Thi Nguyen - - * display.texi (Other Display Specs): Arrange a @code{DOTTED-LIST} to - be on one line to help makeinfo not render two spaces after the dot. - -2006-04-07 Reiner Steib - - * strings.texi (Predicates for Strings): Add string-or-null-p. - -2006-03-28 Kim F. Storm - - * processes.texi (Accepting Output): Remove obsolete (and incorrect) - remarks about systems that don't support fractional seconds. - -2006-03-25 Karl Berry - - * elisp.texi: Use @copyright{} instead of (C), and do not indent - the year list. - -2006-03-21 Nick Roberts - - * display.texi (Fringe Indicators): Fix typos. - -2006-03-19 Luc Teirlinck - - * tips.texi (Documentation Tips): One can now also write `program' - in front of a quoted symbol in a docstring to prevent making a - hyperlink. - -2006-03-19 Alan Mackenzie - - * text.texi (Special Properties): Clarify `fontified' property. - -2006-03-16 Richard Stallman - - * display.texi (Defining Images): Minor cleanup. - -2006-03-16 Bill Wohler - - * display.texi (Defining Images): In image-load-path-for-library, - prefer user's images. - -2006-03-15 Stefan Monnier - - * modes.texi (Region to Fontify): Remove font-lock-lines-before. - -2006-03-15 Bill Wohler - - * display.texi (Defining Images): Fix example in - image-load-path-for-library by not recommending that one binds - image-load-path. Just defvar it to placate compiler and only use - it if previously defined. - -2006-03-14 Bill Wohler - - * display.texi (Defining Images): In image-load-path-for-library, - always return list of directories. Update example. - -2006-03-14 Alan Mackenzie - - * modes.texi: New node, "Region to Fontify" (for Font Lock). - This describes font-lock-extend-region-function. - ("Other Font Lock Variables"): Move "font-lock-lines-before" to - the new node "Region to Fontify". - -2006-03-13 Richard Stallman - - * display.texi (Invisible Text): The impossible position is - now before the invisible text, not after. - (Defining Images): Clean up last change. - -2006-03-11 Bill Wohler - - * display.texi (Defining Images): Add image-load-path-for-library. - -2006-03-11 Luc Teirlinck - - * text.texi (Adaptive Fill): Fix Texinfo usage. - - * strings.texi (Creating Strings): Fix Texinfo usage. - - * searching.texi (Regexp Special): Use @samp for regular - expressions that are not in Lisp syntax. - -2006-03-08 Luc Teirlinck - - * searching.texi (Regexp Special): Put remark between parentheses - to avoid misreading. - -2006-03-07 Luc Teirlinck - - * searching.texi (Syntax of Regexps): More accurately describe - which characters are special in which situations. - (Regexp Special): Recommend _not_ to quote `]' or `-' when they - are not special. Describe in detail when `[' and `]' are special. - (Regexp Backslash): Plenty of regexps with unbalanced square - brackets are valid, so reword that statement. - -2006-03-02 Kim F. Storm - - * keymaps.texi (Tool Bar): Add tool-bar-border. - -2006-02-28 Luc Teirlinck - - * loading.texi (Load Suffixes): Rephrase last paragraph. Fix typos. - -2006-02-27 Luc Teirlinck - - * elisp.texi (Top): Include "Load Suffixes" in the detailed menu. - - * files.texi (Locating Files): Suggest additional values for the - SUFFIXES arg of `locate-file'. Update pxref. - - * loading.texi (Loading): Include new node "Load Suffixes" in menu. - (How Programs Do Loading): Discuss the effects of Auto Compression - mode on `load'. - (Load Suffixes): New node. - (Library Search): Delete description of `load-suffixes'; it was - moved to "Load Suffixes". - (Autoload, Named Features): Mention `load-suffixes'. - -2006-02-21 Giorgos Keramidas (tiny change) - - * display.texi (Fringe Indicators, Fringe Cursors): Fix typos. - - * windows.texi (Window Tree): Fix typo. - -2006-02-20 Kim F. Storm - - * display.texi (Fringe Indicators): New section. - Move indicate-empty-lines, indicate-buffer-boundaries, and - default-indicate-buffer-boundaries here. - Add fringe-indicator-alist and default-fringes-indicator-alist. - Add list of logical fringe indicator symbols. - Update list of standard bitmap names. - (Fringe Cursors): New section. - Move overflow-newline-into-fringe here. - Add fringe-cursor-alist and default-fringes-cursor-alist. - Add list of fringe cursor symbols. - -2006-02-20 Juanma Barranquero - - * commands.texi (Using Interactive): Fix reference to node - "Minibuffers". - -2006-02-19 Richard M. Stallman - - * minibuf.texi (High-Level Completion): - Add xref to read-input-method-name. - - * files.texi (Relative File Names): Move file-relative-name here. - (File Name Expansion): From here. Minor clarifications. - - * commands.texi (Using Interactive): Add xrefs about reading input. - Clarify remarks about that moving point and mark. - Put string case before list case. - -2006-02-16 Johan BockgÃ¥rd - - * display.texi (Other Display Specs, Image Descriptors): - Revert erroneous changes. The previous description of - image-descriptors as `(image . PROPS)' was correct. - -2006-02-14 Richard M. Stallman - - * variables.texi (File Local Variables): Clarifications. - -2006-02-14 Juanma Barranquero - - * variables.texi (File Local Variables): Use @code for a cons - cell, not @var. - -2006-02-13 Chong Yidong - - * variables.texi (File Local Variables): Document new file local - variable behavior. - -2006-02-10 Kim F. Storm - - * eval.texi (Function Indirection): Add NOERROR to indirect-function. - -2006-02-08 Juanma Barranquero - - * modes.texi (%-Constructs): Remove obsolete info about - `global-mode-string'. - -2006-02-07 Richard M. Stallman - - * commands.texi (Prefix Command Arguments): Minor cleanup. - - * display.texi: "Graphical display", not window system. - - * functions.texi (What Is a Function): Fix xref. - - * keymaps.texi (Key Lookup): Clarify wrt commands vs other functions. - (Changing Key Bindings): Clarify when remapping is better than - substitute-key-definition. - -2006-02-02 Richard M. Stallman - - * minibuf.texi (Basic Completion): Completion alists are risky. - - * keymaps.texi (Active Keymaps): Clarifications. - (Searching Keymaps): New node. - (Keymaps): Update menu. - - * frames.texi (Layout Parameters): Minor clarification. - (Drag and Drop): New node. - (Frames): Update menu. - -2006-01-29 Chong Yidong - - * display.texi (Other Display Specs, Image Descriptors): - Image description is a list, not a cons cell. - -2006-01-28 Luc Teirlinck - - * lists.texi (Cons Cells): Minor correction (the cdr of a dotted - list is not necessarily a list). - -2006-01-27 Eli Zaretskii - - * frames.texi (Layout Parameters): border-width and - internal-border-width belong to the frame, not the window. - -2006-01-19 Richard M. Stallman - - * nonascii.texi (Translation of Characters): Search cmds use - translation-table-for-input. Automatically made local. - - * markers.texi (Overview of Markers): Count insertion type - as one of a marker's attributes. - - * keymaps.texi (Controlling Active Maps): New node, split out of - Active Keymaps. - (Keymaps): Menu updated. - (Active Keymaps): Give pseudocode to explain how the active - maps are searched. current-active-maps and key-binding moved here. - (Functions for Key Lookup): current-active-maps and key-binding moved. - Clarifications. - (Searching the Keymaps): New subnode. - - * elisp.texi (Top): Menu clarification. - - * display.texi (Other Display Specs): Delete duplicate entry for - just a string as display spec. Move text about recursive display - specs on such a string. - - * commands.texi (Key Sequence Input): Clarify. - Move num-nonmacro-input-events out. - (Reading One Event): num-nonmacro-input-events moved here. - -2006-01-14 Nick Roberts - - * advice.texi (Simple Advice): Update example to fit argument - change in previous-line. - -2006-01-05 Richard M. Stallman - - * markers.texi (The Mark): Fix in `mark'. - -2006-01-04 Richard M. Stallman - - * processes.texi (Misc Network, Make Network): Minor cleanups. - -2006-01-04 Kim F. Storm - - * processes.texi (Make Network): Add IPv6 addresses and handling. - (Network Feature Testing): Mention (:family ipv6). - (Misc Network): Add IPv6 formats to format-network-address. - -2005-12-30 Richard M. Stallman - - * text.texi (Changing Properties): - Don't use return value of set-text-properties. - -2005-12-29 Luc Teirlinck - - * modes.texi (Mode Line Format): Correct typo in menu. - -2005-12-29 Richard M. Stallman - - * modes.texi (Mode Line Top): New node. - (Mode Line Data): Some text moved to new node. - Explain the data structure more concretely. - (Mode Line Basics): Clarifications. - (Mode Line Variables): Clarify intro paragraph. - (%-Constructs): Clarify intro paragraph. - (Mode Line Format): Update menu. - -2005-12-28 Luc Teirlinck - - * minibuf.texi (Basic Completion): Update lazy-completion-table - examples for removal of ARGS argument. - -2005-12-23 Richard M. Stallman - - * text.texi (Undo): Restore some explanation from the version - that was deleted. - -2005-12-23 Eli Zaretskii - - * text.texi (Undo): Remove duplicate descriptions of `apply - funname' and `apply delta' elements of the undo list. - -2005-12-20 Richard M. Stallman - - * help.texi (Help Functions): Update documentation of `apropos'. - -2005-12-20 Luc Teirlinck - - * customize.texi (Type Keywords): Delete xref to "Text help-echo", - because it is confusing. If the :help-echo keyword is a function, - it is not directly used as the :help-echo overlay property, as the - xref seems to suggest (it does not take the appropriate args). - -2005-12-19 Luc Teirlinck - - * customize.texi (Common Keywords): Fix Texinfo usage. - (Group Definitions, Variable Definitions): Update for new - conventions for using `*' in docstrings. - - * tips.texi (Documentation Tips): Update for new conventions for - using `*' in docstrings. - -2005-12-16 Richard M. Stallman - - * minibuf.texi (Minibuffer Contents): Minor cleanup. - -2005-12-16 Juri Linkov - - * minibuf.texi (Minibuffer Contents): Add minibuffer-completion-contents. - -2005-12-14 Romain Francoise - - * modes.texi (Customizing Keywords): Rename `append' to `how'. - Fix typo. - -2005-12-11 Juri Linkov - - * minibuf.texi (Completion Commands): Add mention of read-file-name - for filename completion keymaps. - (Reading File Names): Add mention of filename completion keymaps - for read-file-name and xref to `Completion Commands'. - -2005-12-10 Richard M. Stallman - - * customize.texi (Common Keywords): State caveats for use of :tag. - -2005-12-08 Richard M. Stallman - - * minibuf.texi (Intro to Minibuffers): Replace list of local maps - with xrefs and better explanation. - (Completion Commands): Add the filename completion maps. - - * objects.texi (Character Type): Clarify that \s is not space - if a dash follows. - -2005-12-05 Richard M. Stallman - - * windows.texi (Resizing Windows): Delete preserve-before args. - -2005-12-05 Stefan Monnier - - * keymaps.texi (Format of Keymaps): Remove mention of a quirk - in full keymaps, since the quirk has been fixed. - -2005-12-03 Eli Zaretskii - - * hooks.texi (Standard Hooks): Add index entries. - Mention `compilation-finish-functions'. - -2005-11-27 Richard M. Stallman - - * windows.texi (Resizing Windows): Add adjust-window-trailing-edge. - -2005-11-21 Juri Linkov - - * customize.texi (Common Keywords): Update links types - custom-manual and url-link. Add link types emacs-library-link, - file-link, function-link, variable-link, custom-group-link. - -2005-11-20 Chong Yidong - - * display.texi: Revert 2005-11-20 change. - -2005-11-20 Thien-Thi Nguyen - - * processes.texi (Bindat Functions): - Say "third" to refer to zero-based index "2". - -2005-11-18 Luc Teirlinck - - * loading.texi (Library Search): Update the default value of - `load-suffixes'. - -2005-11-17 Chong Yidong - - * display.texi (Attribute Functions): Mention :ignore-defface. - -2005-11-16 Stefan Monnier - - * modes.texi (Minor Mode Conventions): Use custom-set-minor-mode. - (Minor Mode Conventions): Mention the use of a hook. - -2005-11-06 Richard M. Stallman - - * files.texi (Magic File Names): find-file-name-handler checks the - `operations' property of the handler. - -2005-11-03 Richard M. Stallman - - * variables.texi (Frame-Local Variables): Small clarification. - -2005-10-29 Chong Yidong - - * os.texi (Init File): Document ~/.emacs.d/init.el. - -2005-10-29 Richard M. Stallman - - * internals.texi (Garbage Collection): Document memory-full. - -2005-10-28 Bill Wohler - - * tips.texi (Documentation Tips): Help mode now creates hyperlinks - for URLs. - -2005-10-28 Richard M. Stallman - - * minibuf.texi (Completion Commands): Clean up prev change. - -2005-10-26 Kevin Ryde - - * compile.texi (Eval During Compile): Explain recommended uses - of eval-when-compile and eval-and-compile. - -2005-10-27 Masatake YAMATO - - * minibuf.texi (Completion Commands): - Write about new optional argument for `display-completion-list'. - -2005-10-23 Richard M. Stallman - - * display.texi (Overlay Arrow): Clarify about local bindings of - overlay-arrow-position. - -2005-10-22 Eli Zaretskii - - * internals.texi (Building Emacs): Fix last change. - -2005-10-22 Richard M. Stallman - - * internals.texi (Building Emacs): Document eval-at-startup. - -2005-10-21 Richard M. Stallman - - * loading.texi (Where Defined): load-history contains abs file names. - symbol-file returns abs file names. - -2005-10-19 Kim F. Storm - - * display.texi (Showing Images): Add max-image-size integer value. - -2005-10-18 Chong Yidong - - * display.texi (Showing Images): Document max-image-size. - -2005-10-17 Richard M. Stallman - - * commands.texi (Quitting): Minor clarification. - - * processes.texi (Sentinels): Clarify about output and quitting. - (Filter Functions): Mention with-local-quit. - -2005-10-17 Juri Linkov - - * buffers.texi (Current Buffer): - * commands.texi (Event Input Misc): - * compile.texi (Eval During Compile, Compiler Errors): - * customize.texi (Group Definitions): - * display.texi (Progress, Defining Faces): - * files.texi (Writing to Files): - * modes.texi (Mode Hooks, Defining Minor Modes): - * streams.texi (Output Functions): - * syntax.texi (Syntax Table Functions): - * text.texi (Change Hooks): - Replace `...' with `@dots{}' in `@defmac' and `@defspec'. - - * commands.texi (Quitting): Replace arg `forms' with `body' in - `with-local-quit'. - - * positions.texi (Excursions): Replace arg `forms' with `body' in - `save-excursion'. - -2005-10-08 Kim F. Storm - - * windows.texi (Window Tree): Rename window-split-tree to window-tree. - Rename manual section accordingly. - -2005-10-04 Kim F. Storm - - * windows.texi (Window Split Tree): New section describing - new function window-split-tree function. - -2005-10-03 Nick Roberts - - * display.texi (Fringe Size/Pos): Simplify and add detail. - -2005-09-30 Romain Francoise - - * minibuf.texi (High-Level Completion): Explain that the prompt - given to `read-buffer' should end with a colon and a space. - Update usage examples. - -2005-09-29 Juri Linkov - - * display.texi (Displaying Messages): Rename argument name - `string' to `format-string' in functions `message', `message-box', - `message-or-box'. - -2005-09-26 Chong Yidong - - * errors.texi (Standard Errors): Correct xrefs. - -2005-09-18 Chong Yidong - - * display.texi (Defining Images): Update documentation for - `image-load-path'. - -2005-09-17 Richard M. Stallman - - * display.texi (Defining Images): Clean up previous change. - -2005-09-16 Romain Francoise - - * elisp.texi: Specify GFDL version 1.2. - - * doclicense.texi (GNU Free Documentation License): Update to - version 1.2. - -2005-09-15 Chong Yidong - - * display.texi (Defining Images): Document `image-load-path'. - -2005-09-15 Richard M. Stallman - - * objects.texi (Printed Representation): Minor cleanup. - (Box Diagrams): Minor fix. - (Cons Cell Type): Move (...) index item here. - (Box Diagrams): From here. - (Array Type): Minor fix. - (Type Predicates): Delete index "predicates". - (Hash Table Type): Clarify xref. - (Dotted Pair Notation): Minor fix. - -2005-09-10 Chong Yidong - - * files.texi (Saving Buffers): Fix typo. - -2005-09-08 Richard M. Stallman - - * tips.texi (Programming Tips): Correct the "default" prompt spec. - -2005-09-08 Chong Yidong - - * locals.texi (Standard Buffer-Local Variables): Don't include - mode variables for minor modes. - Fix xrefs for buffer-display-count, buffer-display-table, - buffer-offer-save, buffer-saved-size, cache-long-line-scans, - enable-multibyte-characters, fill-column, header-line-format, - left-fringe-width, left-margin, and right-fringe-width. - - * hooks.texi (Standard Hooks): All hooks should conform to the - standard naming convention now. - Fix xref for `echo-area-clear-hook'. - - * display.texi (Usual Display): Note that indicate-empty-lines and - tab-width are buffer-local. - - * files.texi (Saving Buffers): Add xref to `Killing Buffers'. - - * modes.texi (Mode Help): Note that major-mode is buffer-local. - - * nonascii.texi (Encoding and I/O): Note that - buffer-file-coding-system is buffer-local. - - * positions.texi (List Motion): Note that defun-prompt-regexp is - buffer-local. - - * text.texi (Auto Filling): Note that auto-fill-function is - buffer-local. - (Undo): Note that buffer-undo-list is buffer-local. - - * windows.texi (Buffers and Windows): - Document buffer-display-count. - -2005-09-06 Richard M. Stallman - - * tips.texi (Coding Conventions): Sometimes it is ok to put the - package prefix elsewhere than at the start of the name. - -2005-09-03 Richard M. Stallman - - * tips.texi (Programming Tips): Add conventions for minibuffer - questions and prompts. - -2005-09-03 Joshua Varner (tiny change) - - * intro.texi (nil and t): Minor cleanup. - Delete spurious mention of keyword symbols. - (Evaluation Notation): Add index entry. - (A Sample Function Description): Minor cleanup. - (A Sample Variable Description): Not all vars can be set. - -2005-09-03 Thien-Thi Nguyen - - * text.texi (Buffer Contents): Use "\n" in examples' result strings. - - (Insertion): Document precise type of `insert-char' arg COUNT. - -2005-09-02 Stefan Monnier - - * modes.texi (Other Font Lock Variables): Sync the default of - font-lock-lines-before. - -2005-08-31 Michael Albinus - - * files.texi (Magic File Names): Add `make-auto-save-file-name'. - -2005-08-29 Richard M. Stallman - - * elisp.texi (Top): Update subnode menu. - - * searching.texi (Searching and Matching): Move node. - Rearrange contents and add overall explanation. - (Searching and Case): Move node. - (Searching and Matching): Update menu. - -2005-08-27 Eli Zaretskii - - * os.texi (Startup Summary): Fix the description of the initial - startup message display. - -2005-08-25 Richard M. Stallman - - * searching.texi (Search and Replace): Add replace-regexp-in-string. - -2005-08-25 Emilio C. Lopes - - * display.texi (Finding Overlays): Fix `find-overlay-prop' in - `next-overlay-change' example. - -2005-08-22 Juri Linkov - - * display.texi (Attribute Functions): Add set-face-inverse-video-p. - Fix invert-face. Fix args of face-background. - - * display.texi (Standard Faces): Delete node. - (Faces): Add xref to `(emacs)Standard Faces'. - (Displaying Faces): Fix xref to `Standard Faces'. - - * modes.texi (Mode Line Data): Fix xref to Standard Faces. - -2005-08-20 Alan Mackenzie - - * buffers.texi (The Buffer List): Clarify the manipulation of the - buffer list. - -2005-08-14 Richard M. Stallman - - * modes.texi (Auto Major Mode): interpreter-mode-alist key is not - a regexp. - -2005-08-11 Richard M. Stallman - - * elisp.texi (Top): Update subnode lists. - - * display.texi (Inverse Video): Node deleted. - - * tips.texi (Key Binding Conventions, Programming Tips, Warning Tips): - New nodes split out of Coding Conventions. - - * searching.texi (Regular Expressions): Document re-builder. - - * os.texi (Time Parsing): New node split out of Time Conversion. - - * processes.texi (Misc Network, Network Feature Testing) - (Network Options, Make Network): New nodes split out of - Low-Level Network. - -2005-08-09 Richard M. Stallman - - * frames.texi (Geometry): New node, split from Size and Position. - (Frame Parameters): Refer to Geometry. - - * buffers.texi (The Buffer List): Fix xrefs. - - * windows.texi (Splitting Windows): Fix xref. - - * frames.texi (Layout Parameters): Add xref. - - * display.texi (Line Height, Scroll Bars): Fix xrefs. - - * keymaps.texi (Menu Bar): Fix xref. - - * locals.texi (Standard Buffer-Local Variables): Fix xref. - - * modes.texi (%-Constructs): Fix xref. - - * frames.texi (Window Frame Parameters): Node split up. - (Basic Parameters, Position Parameters, Size Parameters) - (Layout Parameters, Buffer Parameters, Management Parameters) - (Cursor Parameters, Color Parameters): New subnodes. - -2005-08-09 Luc Teirlinck - - * positions.texi (Screen Lines): Update xref for previous change - in minibuf.texi. - - * minibuf.texi (Intro to Minibuffers): Update pxref for previous - change in minibuf.texi. - -2005-08-09 Richard M. Stallman - - * tips.texi (Coding Conventions): Minor cleanup. - - * modes.texi (Defining Minor Modes): Explain when init-value - can be non-nil. - - * elisp.texi (Top): Update submenu for Minibuffer. - - * minibuf.texi (Minibuffer Misc): Node split up. - (Minibuffer Commands, Minibuffer Windows, Minibuffer Contents) - (Recursive Mini): New nodes split out from Minibuffer Misc. - (Minibuffer Misc): Document max-mini-window-height. - - * hash.texi (Defining Hash): Delete stray paren in example. - - * display.texi (Echo Area Customization): Don't define - max-mini-window-height here; xref instead. - - * commands.texi (Event Input Misc): Update while-no-input. - - * advice.texi (Advising Functions): Explain when to use advice - and when to use a hook. - -2005-07-30 Eli Zaretskii - - * makefile.w32-in (info): Don't run install-info. - ($(infodir)/dir): New target, produced by running install-info. - -2005-07-27 Luc Teirlinck - - * modes.texi (Defining Minor Modes): The keyword for the initial - value is :init-value, not :initial-value. - -2005-07-23 Eli Zaretskii - - * loading.texi (Autoload): Make the `doctor' example be consistent - with what's in current loaddefs.el. Describe the "fn" magic in - the usage portion of the doc string. - -2005-07-22 Richard M. Stallman - - * internals.texi (Garbage Collection): Clarify previous change. - -2005-07-21 Stefan Monnier - - * internals.texi (Garbage Collection): Add gc-cons-percentage. - -2005-07-18 Juri Linkov - - * commands.texi (Accessing Events): - * frames.texi (Text Terminal Colors, Resources): - * markers.texi (The Mark): - * modes.texi (Defining Minor Modes): - Delete duplicate duplicate words. - -2005-07-16 Richard M. Stallman - - * display.texi (Managing Overlays): Clarify make-overlay - args for insertion types. - -2005-07-13 Luc Teirlinck - - * customize.texi (Variable Definitions): - Add `custom-initialize-safe-set' and `custom-initialize-safe-default'. - `standard-value' is a list too. - (Defining New Types): Use @key{RET} instead of @key{ret}. - -2005-07-13 Francis Litterio (tiny change) - - * os.texi (Translating Input): Fix typo. - -2005-07-08 Richard M. Stallman - - * README: Update edition number and size estimate. - - * elisp.texi (VERSION): Set to 2.9. - -2005-07-07 Richard M. Stallman - - * book-spine.texinfo: Update Emacs version. - - * display.texi (Inverse Video): Delete mode-line-inverse-video. - -2005-07-06 Richard M. Stallman - - * searching.texi (Regexp Search): Clarify what re-search-forward - does when the search fails. - -2005-07-05 Lute Kamstra - - * Update FSF's address in GPL notices. - - * doclicense.texi (GNU Free Documentation License): - * gpl.texi (GPL): - * tips.texi (Coding Conventions, Library Headers): - * vol1.texi: - * vol2.texi: Update FSF's address. - -2005-07-04 Richard M. Stallman - - * hooks.texi (Standard Hooks): Add occur-hook. - -2005-07-03 Luc Teirlinck - - * display.texi (The Echo Area): Correct menu. - -2005-07-03 Richard M. Stallman - - * elisp.texi (Top): Update subnode menu for Display. - - * display.texi (Displaying Messages): New node, with most - of what was in The Echo Area. - (Progress): Move under The Echo Area. - (Logging Messages): New node with new text. - (Echo Area Customization): New node, the rest of what was - in The Echo Area. Document message-truncate-lines with @defvar. - (Display): Update menu. - - * windows.texi (Textual Scrolling): Doc 3 values for - scroll-preserve-screen-position. - - * text.texi (Special Properties): Change hook functions - should bind inhibit-modification-hooks around altering buffer text. - - * keymaps.texi (Key Binding Commands): Call binding BINDING - rather than DEFINITION. - -2005-06-29 Juanma Barranquero - - * variables.texi (Defining Variables): `user-variable-p' returns t - for aliases of user options, nil for alias loops. - -2005-06-28 Richard M. Stallman - - * keymaps.texi (Creating Keymaps): Put make-sparse-keymap before - make-keymap. - -2005-06-27 Luc Teirlinck - - * variables.texi (Setting Variables): Correct and clarify - description of `add-to-ordered-list'. - -2005-06-26 Richard M. Stallman - - * display.texi (Faces): Minor cleanup. - -2005-06-25 Luc Teirlinck - - * display.texi (Faces): `facep' returns t for strings that are - face names. - -2005-06-25 Richard M. Stallman - - * objects.texi (Equality Predicates): Clarify meaning of equal. - - * windows.texi (Selecting Windows): save-selected-window - and with-selected-window save and restore the current buffer. - -2005-06-24 Richard M. Stallman - - * numbers.texi (Float Basics): Explain how to test for NaN, - and printing the sign of NaNs. - -2005-06-24 Eli Zaretskii - - * makefile.w32-in (MAKEINFO): Use --force. - -2005-06-23 Richard M. Stallman - - * display.texi (Face Functions): Correct Texinfo usage. - -2005-06-23 Luc Teirlinck - - * lists.texi (Rings): `ring-elements' now returns the elements of - RING in order. - -2005-06-23 Juanma Barranquero - - * markers.texi (The Mark): Texinfo usage fix. - -2005-06-23 Kim F. Storm - - * searching.texi (Entire Match Data): Remove evaporate option for - match-data. Do not mention evaporate option for set-match-data. - -2005-06-22 Glenn Morris - - * display.texi (Face Functions): Mention face aliases. - -2005-06-21 Richard M. Stallman - - * anti.texi (Antinews): Texinfo usage fix. - -2005-06-21 Karl Berry - - * elisp.texi: Use @copying. - - * elisp.texi: Put @summarycontents and @contents before the Top - node, instead of the end of the file, so that the contents appear - in the right place in the dvi/pdf output. - -2005-06-21 Juri Linkov - - * display.texi (Defining Faces): Add `customized-face'. - -2005-06-20 Kim F. Storm - - * variables.texi (Setting Variables): Any type of element can be - given order in add-to-ordered-list. Compare elements with eq. - - * lists.texi (Rearrangement): Sort predicate may just return non-nil. - -2005-06-20 Karl Berry - - * syntax.texi (Syntax Flags): Make last column very slightly wider - to avoid "generic comment" breaking on two lines and causing an - underfull box. - -2005-06-19 Luc Teirlinck - - * lists.texi (Rings): Various minor clarifications and corrections. - -2005-06-18 Richard M. Stallman - - * functions.texi (Obsolete Functions): Simplify. - - * variables.texi (Variable Aliases): Simplify. - - * anti.texi, backups.texi, compile.texi, customization.texi: - * debugging.texi, display.texi, edebug.texi, errors.texi, frames.texi: - * functions.texi, help.texi, keymaps.texi, modes.texi, nonascii.texi: - * os.texi, processes.texi, searching.texi, strings.texi, text.texi: - * variables.texi: Fix formatting ugliness. - - * elisp.texi: Add links to Rings and Byte Packing. - Update version and copyright years. - - * minibuf.texi: Fix formatting ugliness. - (Completion Commands): Move keymap vars to the end - and vars completing-read binds to the top. - -2005-06-17 Luc Teirlinck - - * processes.texi: Fix typos. - (Bindat Spec): Correct Texinfo error. - (Byte Packing): Fix ungrammatical sentence. - -2005-06-17 Thien-Thi Nguyen - - * lists.texi (Rings): New node. - (Lists): Add it to menu. - - * processes.texi (Byte Packing): New node. - (Processes): Add it to menu. - -2005-06-17 Richard M. Stallman - - * syntax.texi (Parsing Expressions): Fix texinfo usage. - - * help.texi (Documentation Basics): Explain the xref to - Documentation Tips. - - * debugging.texi (Debugger Commands): Minor fix. - -2005-06-16 Luc Teirlinck - - * edebug.texi (Instrumenting): Eliminate duplicate link. - (Specification List): Replace references to "below", referring to - a later node, with one @ref to that node. - - * os.texi (Timers): Timers should save and restore the match data - if they change it. - - * debugging.texi (Debugger Commands): Mention that the Lisp - debugger can not step through primitive functions. - -2005-06-16 Juanma Barranquero - - * functions.texi (Obsolete Functions): Update argument names of - `make-obsolete' and `define-obsolete-function-alias'. - - * variables.texi (Variable Aliases): Update argument names of - `defvaralias', `make-obsolete-variable' and - `define-obsolete-variable-alias'. - -2005-06-15 Kim F. Storm - - * searching.texi (Entire Match Data): Rephrase warnings about - evaporate arg to match-data and set-match-data. - -2005-06-14 Luc Teirlinck - - * elisp.texi (Top): Update detailed menu. - - * edebug.texi (Edebug): Update menu. - (Instrumenting): Update xrefs. - (Edebug Execution Modes): Correct xref. - (Jumping): Clarify description of `h' command. - Eliminate redundant @ref. - (Breaks): New node. - (Breakpoints): Is now a subsubsection. - (Global Break Condition): Mention `C-x X X'. - (Edebug Views): Clarify `v' and `p'. Mention `C-x X w'. - (Trace Buffer): Clarify STRING arg of `edebug-tracing'. - (Edebug Display Update): Correct pxref. - (Edebug and Macros): New node. - (Instrumenting Macro Calls): Is now a subsubsection. - Neither arg of `def-edebug-spec' is evaluated. - (Instrumenting Macro Calls): Mention `edebug-eval-macro-args'. - (Specification Examples): Fix typo. - -2005-06-14 Lute Kamstra - - * debugging.texi (Function Debugging): Primitives can break on - entry too. - -2005-06-14 Kim F. Storm - - * variables.texi (Setting Variables): Add add-to-ordered-list. - -2005-06-13 Stefan Monnier - - * syntax.texi (Parsing Expressions): Document aux functions and vars of - syntax-ppss: syntax-ppss-flush-cache and syntax-begin-function. - -2005-06-13 Lute Kamstra - - * text.texi (Special Properties): Fix cross reference. - -2005-06-11 Luc Teirlinck - - * debugging.texi (Function Debugging): Delete mention of empty - string argument to `cancel-debug-on-entry'. Delete inaccurate - description of the return value of that command. - -2005-06-11 Alan Mackenzie - - * text.texi (Adaptive Fill): Amplify the description of - fill-context-prefix. - -2005-06-10 Luc Teirlinck - - * syntax.texi (Parsing Expressions): Fix Texinfo error. - -2005-06-10 Stefan Monnier - - * syntax.texi (Parsing Expressions): Document syntax-ppss. - -2005-06-10 Luc Teirlinck - - * debugging.texi (Error Debugging): Minor rewording. - (Function Debugging): FUNCTION-NAME arg to `cancel-debug-on-entry' - is optional. - -2005-06-10 Lute Kamstra - - * elisp.texi: Use EMACSVER to refer to the current version of Emacs. - (Top): Give it a title. Correct version number. Give the - detailed node listing a more prominent header. - * intro.texi: Don't set VERSION here a second time. - Mention Emacs's version too. - * anti.texi (Antinews): Use EMACSVER to refer to the current - version of Emacs. - -2005-06-09 Kim F. Storm - - * searching.texi (Entire Match Data): Explain new `reseat' argument to - match-data and set-match-data. - -2005-06-08 Richard M. Stallman - - * searching.texi (Entire Match Data): Clarify when match-data - returns markers and when integers. - - * display.texi (Defining Faces): Explain that face name should not - end in `-face'. - - * modes.texi (Mode Line Data): Minor cleanup. - (Customizing Keywords): Node split out of Search-based Fontification. - Add example of using font-lock-add-keywords from a hook. - Clarify when MODE should be non-nil, and when nil. - -2005-06-06 Richard M. Stallman - - * modes.texi (Mode Line Data): Explain what happens when the car - of a list is a void symbol. - (Search-based Fontification): Explain MODE arg to - font-lock-add-keywords and warn about calls from major modes. - -2005-06-08 Juri Linkov - - * display.texi (Standard Faces): Add `shadow' face. - -2005-05-29 Luc Teirlinck - - * modes.texi (Major Mode Conventions): A derived mode only needs - to put the call to the parent mode inside `delay-mode-hooks'. - -2005-05-29 Richard M. Stallman - - * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook is - new, and what that implies. Clarify. - - * files.texi (Locating Files): Clean up the text. - - * frames.texi (Window Frame Parameters): Document user-size. - Shorten entry for top by referring to left. - -2005-05-26 Richard M. Stallman - - * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook - is new, and what the implications are. Other clarifications. - -2005-05-24 Richard M. Stallman - - * frames.texi (Dialog Boxes): Minor fixes. - -2005-05-25 Masatake YAMATO - - * display.texi (Standard Faces): Write about `mode-line-highlight'. - -2005-05-24 Luc Teirlinck - - * frames.texi (Dialog Boxes): HEADER argument to `x-popup-dialog' - is optional. - -2005-05-24 Nick Roberts - - * frames.texi (Dialog Boxes): Describe new optional argument. - -2005-05-23 Lute Kamstra - - * modes.texi (Font Lock Basics, Syntactic Font Lock): Recommend - syntax-begin-function over font-lock-beginning-of-syntax-function. - -2005-05-21 Luc Teirlinck - - * minibuf.texi (Reading File Names): Update description of - `read-directory-name'. - - * modes.texi (Derived Modes): Clarify :group keyword. - -2005-05-21 Eli Zaretskii - - * files.texi (Locating Files): New subsection. - Describe locate-file and executable-find. - -2005-05-21 Kevin Ryde - - * frames.texi (Initial Parameters): Update cross reference to - "Emacs Invocation". - -2005-05-19 Luc Teirlinck - - * keymaps.texi (Active Keymaps): Add anchor. - - * modes.texi (Hooks): Delete confusing and unnecessary sentence. - (Major Mode Conventions): Refer to `Auto Major Mode' in more - appropriate place. - (Derived Modes): Small clarifications. - (Minor Mode Conventions, Keymaps and Minor Modes): - Replace references to nodes with references to anchors. - (Mode Line Data): Warn that `(:eval FORM)' should not load any files. - Clarify description of lists whose first element is an integer. - (Mode Line Variables): Add anchor. - (%-Constructs): Clarify description of integer after %. - (Emulating Mode Line): Describe nil value for FACE. - -2005-05-18 Luc Teirlinck - - * modes.texi (Derived Modes): Correct references to non-existing - variable standard-syntax-table. - -2005-05-17 Lute Kamstra - - * modes.texi (Defining Minor Modes): Mention the mode hook. - -2005-05-15 Kim F. Storm - - * processes.texi (Network): Remove open-network-stream-nowait. - (Network Servers): Remove open-network-stream-server. - -2005-05-15 Luc Teirlinck - - * elisp.texi (Top): Update detailed menu. - - * variables.texi: Reorder nodes. - (Variables): Update menu. - (File Local Variables): Do not refer to the `-*-' line as - a "local variables list". Add pxref. - -2005-05-14 Luc Teirlinck - - * elisp.texi (Top): Update detailed menu for node changes. - - * modes.texi (Modes): Update Menu. - (Hooks): Move to beginning of chapter. - Most minor modes run mode hooks too. - `add-hook' can handle void hooks or hooks whose value is a single - function. - (Major Modes): Update Menu. - (Major Mode Basics): New node, split off from `Major Modes'. - (Major Mode Conventions): Correct xref. Explain how to handle - auto-mode-alist if the major mode command has an autoload cookie. - (Auto Major Mode): Major update. Add magic-mode-alist. - (Derived Modes): Major update. - (Mode Line Format): Update Menu. - (Mode Line Basics): New node, split off from `Mode Line Format'. - - * loading.texi (Autoload): Mention `autoload cookie' as synonym - for `magic autoload comment'. Add index entries and anchor. - -2005-05-14 Richard M. Stallman - - * tips.texi (Coding Conventions): Explain how important it is - that just loading certain files not change Emacs behavior. - - * modes.texi (Defining Minor Modes): Define define-global-minor-mode. - -2005-05-12 Lute Kamstra - - * modes.texi (Generic Modes): Update. - (Major Modes): Refer to node "Generic Modes". - - * elisp.texi (Top): Update to the current structure of the manual. - * processes.texi (Processes): Add menu description. - * customize.texi (Customization): Add menu descriptions. - -2005-05-11 Thien-Thi Nguyen - - * processes.texi (Signals to Processes) - (Low-Level Network): Fix typos. - -2005-05-11 Lute Kamstra - - * elisp.texi (Top): Add some nodes from the chapter "Major and - Minor Modes" to the detailed node listing. - -2005-05-10 Richard M. Stallman - - * keymaps.texi (Extended Menu Items): Menu item filter functions - can be called at any time. - -2005-05-08 Luc Teirlinck - - * variables.texi (File Local Variables): `(hack-local-variables t)' - now also checks whether a mode is specified in the local variables - list. - -2005-05-05 Kevin Ryde - - * display.texi (The Echo Area): Correct format function cross - reference. - -2005-05-05 Luc Teirlinck - - * variables.texi (Variable Aliases): Change description of - `define-obsolete-variable-alias'. - - * functions.texi (Functions): Add "Obsolete Functions" to menu. - (Defining Functions): Add xref. - (Obsolete Functions): New node. - (Function Safety): Standardize capitalization of section title. - - * frames.texi (Pop-Up Menus): Complete description of `x-popup-menu'. - (Dialog Boxes): Complete description of `x-popup-dialog'. - -2005-05-04 Richard M. Stallman - - * commands.texi (Interactive Codes): Fix Texinfo usage. - Document U more clearly. - -2005-05-01 Luc Teirlinck - - * variables.texi (Variable Aliases): `make-obsolete-variable' is a - function and not a macro. - - * frames.texi (Pop-Up Menus): Correct and clarify description of - `x-popup-menu'. - (Dialog Boxes): Clarify description of `x-popup-dialog'. - -2005-05-01 Richard M. Stallman - - * edebug.texi (Checking Whether to Stop): Fix previous change. - -2005-05-01 Luc Teirlinck - - * display.texi: Fix typos and Texinfo usage. - - * edebug.texi (Checking Whether to Stop): executing-macro -> - executing-kbd-macro. - -2005-05-01 Richard M. Stallman - - * display.texi (Invisible Text): Correct add-to-invisibility-spec. - -2005-04-30 Richard M. Stallman - - * files.texi (Magic File Names): Document `operations' property. - -2005-04-29 Lute Kamstra - - * modes.texi (Generic Modes): New node. - (Major Modes): Add it to the menu. - (Derived Modes): Add "derived mode" to concept index. - -2005-04-28 Lute Kamstra - - * modes.texi (Defining Minor Modes): Fix previous change. - (Font Lock Mode): Simplify. - (Font Lock Basics): Say that font-lock-defaults is buffer-local - when set and that some parts are optional. Add cross references. - (Search-based Fontification): Say how to specify font-lock-keywords. - Add cross references. Add font-lock-multiline to index. - Move font-lock-keywords-case-fold-search here from node "Other Font - Lock Variables". Document font-lock-add-keywords and - font-lock-remove-keywords. - (Other Font Lock Variables): Move font-lock-keywords-only, - font-lock-syntax-table, font-lock-beginning-of-syntax-function, - and font-lock-syntactic-face-function to node "Syntactic Font - Lock". Move font-lock-keywords-case-fold-search to node - "Search-based Fontification". Document font-lock-inhibit-thing-lock - and font-lock-{,un}fontify-{buffer,region}-function. - (Precalculated Fontification): Remove reference to deleted variable - font-lock-core-only. - (Faces for Font Lock): Add font-lock-comment-delimiter-face. - (Syntactic Font Lock): Add intro. Move font-lock-keywords-only, - font-lock-syntax-table, font-lock-beginning-of-syntax-function, - and font-lock-syntactic-face-function here from node "Other Font - Lock Variables". Move font-lock-syntactic-keywords to "Setting - Syntax Properties". Add cross references. - (Setting Syntax Properties): New node. - Move font-lock-syntactic-keywords here from "Syntactic Font Lock". - * syntax.texi (Syntax Properties): Add cross reference. - * hooks.texi (Standard Hooks): Add Font-Lock hooks. - -2005-04-26 Richard M. Stallman - - * display.texi (Defining Faces): - Document `default' elements of defface spec. - - * modes.texi (Major Mode Conventions): Explain customizing ElDoc mode. - - * variables.texi (Variable Aliases): Clarify text. - -2005-04-25 Chong Yidong - - * windows.texi (Window Hooks): Remove reference to obsolete Lazy Lock. - -2005-04-25 Luc Teirlinck - - * hooks.texi (Standard Hooks): Most minor modes have mode hooks too. - -2005-04-24 Eli Zaretskii - - * syntax.texi (Syntax Table Internals): Elaborate documentation of - syntax-after and syntax-class. - - * files.texi (Changing Files): Fix last change's cross-reference. - (Unique File Names): Don't mention "numbers" in the documentation - of make-temp-file and make-temp-name. - -2005-04-23 Richard M. Stallman - - * files.texi (Changing Files): Document MUSTBENEW arg in copy-file. - -2005-04-22 Nick Roberts - - * windows.texi (Cyclic Window Ordering): Clarify window-list. - -2005-04-22 Nick Roberts - - * variables.texi (Variable Aliases): Describe make-obsolete-variable - and define-obsolete-variable-alias. - -2005-04-22 Kim F. Storm - - * symbols.texi (Symbol Plists): Remove safe-get, as get is now safe. - (Other Plists): Remove safe-plist-get, as plist-get is now safe. - -2005-04-21 Lute Kamstra - - * lists.texi (Association Lists): Document rassq-delete-all. - -2005-04-19 Richard M. Stallman - - * modes.texi (Search-based Fontification): Explain that - facespec is an expression to be evaluated. - -2005-04-19 Kevin Ryde - - * streams.texi (Output Functions): Fix xref. - * strings.texi (String Conversion): Fix xref. - -2005-04-19 Kim F. Storm - - * symbols.texi (Symbol Plists): Add safe-get. - Mention that `get' may signal an error. - -2005-04-18 Nick Roberts - - * customize.texi (Variable Definitions): Replace tooltip-mode - example with save-place. - -2005-04-17 Richard M. Stallman - - * buffers.texi (Indirect Buffers): Clarify. - - * positions.texi (Positions): Clarify converting marker to integer. - - * strings.texi (String Basics): Mention string-match; clarify. - -2005-04-08 Lute Kamstra - - * modes.texi (Search-based Fontification): Fix cross references. - Use consistent terminology. Document anchored highlighting. - -2005-04-05 Lute Kamstra - - * modes.texi (Defining Minor Modes): Document :group keyword - argument and its default value. - -2005-04-03 Lute Kamstra - - * hooks.texi (Standard Hooks): Add some hooks. Add cross - references and/or descriptions. Delete major mode hooks; mention - them as a category instead. Rename or delete obsolete hooks. - -2005-04-02 Richard M. Stallman - - * nonascii.texi (Coding System Basics): Another wording cleanup. - -2005-04-01 Richard M. Stallman - - * nonascii.texi (Coding System Basics): Clarify previous change. - -2005-04-01 Kenichi Handa - - * nonascii.texi (Coding System Basics): Describe about roundtrip - identity of coding systems. - -2005-03-29 Chong Yidong - - * text.texi (Buffer Contents): Add filter-buffer-substring and - buffer-substring-filters. - -2005-03-26 Chong Yidong - - * anti.texi (Antinews): Mention `G' interactive code. - - * tips.texi (Compilation Tips): Mention benchmark.el. - -2005-03-27 Luc Teirlinck - - * modes.texi (Other Font Lock Variables): `font-lock-fontify-block' - is now bound to M-o M-o. - - * keymaps.texi (Prefix Keys): `facemenu-keymap' is now on M-o. - -2005-03-26 Glenn Morris - - * calendar.texi: Delete file (and move contents to emacs-xtra.texi - in the Emacs Manual). - * Makefile.in (srcs): Remove calendar.texi. - * makefile.w32-in (srcs): Remove calendar.texi. - * display.texi (Display): Change name of next node. - * os.texi (System In): Change name of previous node. - * elisp.texi (Top): Remove Calendar references. - * vol1.texi (Top): Remove Calendar references. - * vol2.texi (Top): Remove Calendar references. - -2005-03-25 Richard M. Stallman - - * display.texi (Standard Faces, Fringe Bitmaps, Customizing Bitmaps): - Cleanup previous change. - -2005-03-25 Chong Yidong - - * display.texi (Face Attributes): Faces earlier in an :inherit - list take precedence. - (Scroll Bars): Fix description of vertical-scroll-bars. - Document frame-current-scroll-bars and window-current-scroll-bars. - - * markers.texi (The Mark): Document temporary Transient Mark mode. - - * minibuf.texi (Reading File Names): - Document read-file-name-completion-ignore-case. - - * positions.texi (Screen Lines): Document nil for width argument - to compute-motion. - -2005-03-23 Kim F. Storm - - * display.texi (Standard Faces): Other faces used in the fringe - implicitly inherits from the fringe face. - (Fringe Bitmaps): FACE in right-fringe and left-fringe display - properties implicitly inherits from fringe face. - (Customizing Bitmaps): Likewise for set-fringe-bitmap-face. - -2005-03-20 Chong Yidong - - * display.texi (Invisible Text): State default value of - line-move-ignore-invisible. - (Managing Overlays): Document remove-overlays. - (Standard Faces): Document escape-glyph face. - - * minibuf.texi (Reading File Names): Document read-file-name-function. - - * modes.texi (Other Font Lock Variables): - Document font-lock-lines-before. - - * positions.texi (Skipping Characters): skip-chars-forward allows - character classes. - -2005-03-18 Lute Kamstra - - * edebug.texi (Instrumenting Macro Calls): Fix another typo. - -2005-03-17 Richard M. Stallman - - * text.texi (Undo): Document extensible undo entries. - - * searching.texi (String Search, Regexp Search): Cleanups. - - * nonascii.texi (Character Codes): Minor fix. - - * display.texi (Display Property): Explain the significance - of having text properties that are eq. - (Other Display Specs): Explain string as display spec. - - * commands.texi (Interactive Codes): Document G option. - -2005-03-17 Chong Yidong - - * text.texi (Filling): Add sentence-end-without-period and - sentence-end-without-space. - (Changing Properties): Minor fix. - - * anti.texi: Total rewrite. - -2005-03-15 Lute Kamstra - - * edebug.texi (Instrumenting Macro Calls): Fix typos. - -2005-03-08 Kim F. Storm - - * display.texi (Specified Space): Property :width is support on - non-graphic terminals, :height is not. - -2005-03-07 Richard M. Stallman - - * display.texi (Overlay Arrow, Fringe Bitmaps, Customizing Bitmaps): - Now subnodes of Fringes. - (Overlay Arrow): Document overlay-arrow-variable-list. - (Fringe Size/Pos): New node, broken out of Fringes. - (Display): Explain clearing vs redisplay better. - (Truncation): Clarify use of bitmaps. - (The Echo Area): Clarify the uses of the echo area. - Add max-mini-window-height. - (Progress): Clarify. - (Invisible Text): Explain that main loop moves point out. - (Selective Display): Say "hidden", not "invisible". - (Managing Overlays): Move up. Describe relation to Undo here. - (Overlay Properties): Clarify intro. - (Finding Overlays): Explain return values when nothing found. - (Width): truncate-string-to-width has added arg. - (Displaying Faces): Clarify and update mode line face handling. - (Face Functions): Minor cleanup. - (Conditional Display): Merge into Other Display Specs. - (Pixel Specification, Other Display Specs): Minor cleanups. - (Images, Image Descriptors): Minor cleanups. - (GIF Images): Patents have expired. - (Showing Images): Explain default text for insert-image. - (Manipulating Button Types): Merge into Manipulating Buttons. - (Making Buttons): Explain return values. - (Button Buffer Commands): Add xref. - (Inverse Video): Update mode-line-inverse-video. - (Display Table Format): Clarify. - (Active Display Table): Give defaults for window-display-table. - - * calendar.texi (Calendar Customizing): calendar-holiday-marker - and calendar-today-marker are strings, not chars. - (Holiday Customizing): Minor fix. - - * internals.texi (Writing Emacs Primitives): Update `or' example. - Update limit on # args of subr. - - * edebug.texi (Using Edebug): Arrow is in fringe. - (Instrumenting): Arg to eval-defun works without loading edebug. - (Edebug Execution Modes): Add xref. - - * customize.texi (Common Keywords): Clarify :require. - Mention :version here. - (Variable Definitions, Group Definitions): Not here. - (Variable Definitions): Clarify symbol arg to :initialize and :set fns. - -2005-03-07 Chong Yidong - * nonascii.texi (Text Representations): Clarify position-bytes. - (Character Sets): Add list-charset-chars. - (Scanning Charsets): Add charset-after. - (Encoding and I/O): Minor fix. - -2005-03-06 Richard M. Stallman - - * windows.texi (Vertical Scrolling): Get rid of "Emacs 21". - (Resizing Windows): Likewise. - - * text.texi (Change Hooks): Get rid of "Emacs 21". - - * strings.texi (Formatting Strings): Get rid of "Emacs 21". - - * streams.texi (Output Variables): Get rid of "Emacs 21". - - * searching.texi (Regexp Special, Char Classes): Get rid of "Emacs 21". - - * os.texi (Translating Input): Replace flow-control example - with a less obsolete example that uses `keyboard-translate'. - - * objects.texi (Hash Table Type, Circular Objects): - Get rid of "Emacs 21". - - * modes.texi (Mode Line Format): Get rid of "Emacs 21". - (Mode Line Data, Properties in Mode, Header Lines): Likewise. - - * minibuf.texi (Minibuffer Misc): Get rid of "Emacs 21". - - * lists.texi (List Elements, Building Lists): Get rid of "Emacs 21". - - * keymaps.texi (Menu Separators, Tool Bar): Get rid of "Emacs 21". - (Menu Bar): Fix when menu-bar-update-hook is called. - - * hash.texi (Hash Tables): Get rid of "Emacs 21". - - * frames.texi (Text Terminal Colors): Get rid of "Emacs 21", - and make it read better. - - * files.texi (Writing to Files): Get rid of "Emacs 21". - (Unique File Names): Likewise. - - * elisp.texi: Update Emacs version to 22. - - * display.texi (Forcing Redisplay): Get rid of "Emacs 21". - (Overlay Properties, Face Attributes): Likewise. - (Managing Overlays): Fix punctuation. - (Attribute Functions): Clarify set-face-font; get rid of - info about old Emacs versions. - (Auto Faces, Font Lookup, Display Property, Images): - Get rid of "Emacs 21". - - * calendar.texi (Calendar Customizing): Get rid of "Emacs 21". - -2005-03-05 Richard M. Stallman - - * debugging.texi (Error Debugging): Remove stack-trace-on-error. - -2005-03-04 Lute Kamstra - - * debugging.texi (Error Debugging): Document stack-trace-on-error. - -2005-03-03 Lute Kamstra - - * edebug.texi (Instrumenting Macro Calls): Fix typo. - -2005-03-01 Lute Kamstra - - * debugging.texi (Debugger Commands): Update `j'. - -2005-02-28 Lute Kamstra - - * debugging.texi (Debugging): Fix typo. - (Error Debugging): Document eval-expression-debug-on-error. - (Function Debugging): Update example. - (Using Debugger): Mention starred stack frames. - (Debugger Commands): Document `j' and `l'. - (Invoking the Debugger): `d' and `j' exit recursive edit too. - Update the messages that the debugger displays. - (Internals of Debugger): Add cross reference. Update example. - (Excess Open): Minor improvement. - (Excess Close): Minor improvement. - -2005-02-26 Richard M. Stallman - - * tips.texi (Coding Conventions): Clarify. - Put all the major mode key reservations together. - Mention the Mouse-1 => Mouse-2 conventions. - - * syntax.texi (Syntax Class Table): Clarify. - (Syntax Table Functions): syntax-after moved from here. - (Syntax Table Internals): syntax-after moved to here. - (Parsing Expressions): Update info on number of values - and what's meaningful in the STATE argument. - (Categories): Fix typo. - - * sequences.texi (Arrays): Cleanup. - (Char-Tables): Clarify. - - * processes.texi (Deleting Processes): Cleanups, add xref. - (Subprocess Creation): Explain nil in exec-path. Cleanup. - (Process Information): set-process-coding-system, some args optional. - (Input to Processes): Explain various types for PROCESS args. - Rename them from PROCESS-NAME to PROCESS. - (Signals to Processes): Likewise. - (Decoding Output): Cleanup. - (Query Before Exit): Clarify. - - * os.texi (Startup Summary): Correct the options; add missing ones. - (Terminal Output, Batch Mode): Clarify. - (Flow Control): Node deleted. - - * markers.texi (The Mark): Clarify. - - * macros.texi (Expansion): Cleanup. - (Indenting Macros): indent-spec allows ints, not floats. - - * keymaps.texi (Keymaps): Clarify. - (Format of Keymaps): Update lisp-mode-map example. - (Active Keymaps, Key Lookup): Clarify. - (Changing Key Bindings): Add xref to `kbd'. - (Key Binding Commands, Simple Menu Items): Clarify. - (Mouse Menus, Menu Bar): Clarify. - (Menu Example): Replace print example with menu-bar-replace-menu. - - * help.texi (Documentation Basics): Add function-documentation prop. - - * elisp.texi (Top): Don't refer to Flow Control node. - - * commands.texi (Command Overview): Improve xrefs. - (Adjusting Point): Adjusting point applies to intangible and invis. - (Key Sequence Input): Doc extra read-key-sequence args. - Likewise for read-key-sequence-vector. - - * backups.texi (Rename or Copy): Minor fix. - (Numbered Backups): For version-control, say the default. - (Auto-Saving): make-auto-save-file-name example is simplified. - - * advice.texi (Advising Functions): Don't imply one part of Emacs - should advise another part. Markup changes. - (Defining Advice): Move transitional para. - (Activation of Advice): Cleanup. - Explain if COMPILE is nil or negative. - - * abbrevs.texi (Abbrev Expansion): Clarify, fix typo. - -2005-02-24 Lute Kamstra - - * modes.texi (Defining Minor Modes): Explain that INIT-VALUE, - LIGHTER, and KEYMAP can be omitted when KEYWORD-ARGS are used. - -2005-02-23 Lute Kamstra - - * modes.texi (Defining Minor Modes): define-minor-mode can be used - to define global minor modes as well. - - * display.texi (Managing Overlays): overlay-buffer returns nil for - deleted overlays. - -2005-02-22 Kim F. Storm - - * minibuf.texi (Basic Completion): Allow symbols in addition to - strings in try-completion and all-completions. - -2005-02-14 Lute Kamstra - - * elisp.texi (Top): Remove reference to deleted node. - - * lists.texi (Lists): Remove reference to deleted node. - (Cons Cells): Fix typo. - - * loading.texi (Where Defined): Fix typo. - -2005-02-14 Richard M. Stallman - - * variables.texi (Creating Buffer-Local): change-major-mode-hook - is useful for discarding some minor modes. - - * symbols.texi (Symbol Components): Reorder examples. - - * streams.texi (Input Functions): State standard-input default. - (Output Variables): State standard-output default. - - * objects.texi (Printed Representation): Clarify read syntax vs print. - (Floating Point Type): Explain meaning better. - (Symbol Type): Explain uniqueness better. - (Cons Cell Type): Explain empty list sooner. CAR and CDR later. - List examples sooner. - (Box Diagrams): New subnode broken out. - Some examples moved from old Lists as Boxes node. - (Dotted Pair Notation): Clarify intro. - (Array Type): Clarify. - (Type Predicates): Add hash-table-p. - - * numbers.texi (Integer Basics): Clarify radix explanation. - (Predicates on Numbers): Minor clarification. - (Comparison of Numbers): Minor clarification. Clarify eql. - Typos in min, max. - (Math Functions): Clarify overflow in expt. - - * minibuf.texi (Text from Minibuffer): Minor clarification. - Mention arrow keys. - - * loading.texi (Autoload): defun's doc string overrides autoload's - doc string. - (Repeated Loading): Modernize "add to list" examples. - (Where Defined): Finish updating table of load-history elts. - - * lists.texi (List-related Predicates): Minor wording improvement. - (Lists as Boxes): Node deleted. - (Building Lists): Explain trivial cases of number-sequence. - - * hash.texi (Hash Tables): Add desc to menu items. - (Creating Hash): Explain "full" means "make larger". - (Hash Access): Any object can be a key. - State value of maphash. - - * functions.texi (What Is a Function): Wording cleanup. - (Function Documentation): Minor cleanup. - Explain purpose of calling convention at end of doc string. - (Function Names): Wording cleanup. - (Calling Functions): Wording cleanup. - Explain better how funcall calls the function. - (Function Cells): Delete example of saving and redefining function. - - * control.texi (Combining Conditions): Wording cleanup. - (Iteration): dolist and dotimes bind VAR locally. - (Cleanups): Xref to Atomic Changes. - - * compile.texi (Byte Compilation): Delete 19.29 info. - (Compilation Functions): Macros' difficulties don't affect defsubst. - (Docs and Compilation): Delete 19.29 info. - -2005-02-10 Richard M. Stallman - - * objects.texi (Symbol Type): Minor correction. - -2005-02-06 Lute Kamstra - - * modes.texi (Example Major Modes): Fix typos. - -2005-02-06 Richard M. Stallman - - * text.texi (Margins): fill-nobreak-predicate can be one function. - - * strings.texi (Modifying Strings): clear-string can make unibyte. - (Formatting Strings): format gives error if values missing. - - * positions.texi (Character Motion): Mention default arg - for forward-char. backward-char refers to forward-char. - (Word Motion): Mention default arg for forward-word. - (Buffer End Motion): Mention default arg for beginning-of-buffer. - Simplify end-of-buffer. - (Text Lines): Mention default arg for forward-line. - (List Motion): Mention default arg for beginning/end-of-defun. - (Skipping Characters): Minor fixes in explaining character-set. - - * modes.texi (Major Mode Conventions): Mention "system abbrevs". - Mode inheritance applies only when default-major-mode is nil. - Clarifications. - (Example Major Modes): Update Text mode and Lisp mode examples. - (Minor Mode Conventions): Mention define-minor-mode at top. - (Defining Minor Modes): In Hungry example, don't define C-M-DEL. - (Mode Line Format): Update mode line face display info. - (Properties in Mode): Mention effect of risky vars. - (Imenu): Define imenu-add-to-menubar. - (Font Lock Mode): Add descriptions to menu lines. - (Faces for Font Lock): Add font-lock-doc-face. - -2005-02-05 Lute Kamstra - - * text.texi (Maintaining Undo): Remove obsolete function. - -2005-02-05 Eli Zaretskii - - * frames.texi (Color Names): Add pointer to the X docs about RGB - color specifications. Improve indexing. - (Text Terminal Colors): Replace the description of RGB values by - an xref to "Color Names". - -2005-02-03 Richard M. Stallman - - * windows.texi (Basic Windows): Add cursor-in-non-selected-windows. - Clarify. - (Selecting Windows): Clarify save-selected-window. - (Cyclic Window Ordering): Clarify walk-windows. - (Window Point): Clarify. - (Window Start): Add comment to example. - (Resizing Windows): Add `interactive' specs in examples. - Document fit-window-to-buffer. - - * text.texi (User-Level Deletion): just-one-space takes numeric arg. - (Undo, Maintaining Undo): Clarify last change. - (Sorting): In sort-numeric-fields, explain about octal and hex. - Mention sort-numeric-base. - (Format Properties): Add xref for hard newlines. - - * frames.texi (Window Frame Parameters): Explain pixel=char on tty. - (Pop-Up Menus): Fix typo. - (Color Names): Explain all types of color names. - Explain color-values on B&W terminal. - (Text Terminal Colors): Explain "rgb values" are lists. Fix arg names. - - * files.texi (File Locks): Not supported on MS systems. - (Testing Accessibility): Clarify. - - * edebug.texi (Printing in Edebug): Fix edebug-print-circle. - (Coverage Testing): Fix typo. - - * commands.texi (Misc Events): Remove stray space. - - * buffers.texi (Buffer Names): Clarify generate-new-buffer-name. - (Modification Time): Clarify when visited-file-modtime returns 0. - (The Buffer List): Clarify bury-buffer. - (Killing Buffers): Clarify. - (Indirect Buffers): Add clone-indirect-buffer. - -2005-02-02 Matt Hodges - - * edebug.texi (Printing in Edebug): Fix default value of - edebug-print-circle. - (Coverage Testing): Fix displayed frequency count data. - -2005-02-02 Luc Teirlinck - - * text.texi (Maintaining Undo): Add `undo-outer-limit'. - -2005-02-02 Kim F. Storm - - * text.texi (Undo) : Describe `apply' elements. - -2005-01-29 Eli Zaretskii - - * commands.texi (Misc Events): Describe the help-echo event. - - * text.texi (Special Properties) : Use `pos' - consistently in description of the help-echo property. - Use @code{nil} instead of @var{nil}. - - * display.texi (Overlay Properties): Fix the index entry for - help-echo overlay property. - - * customize.texi (Type Keywords): Uncomment the xref to the - help-echo property documentation. - -2005-01-23 Kim F. Storm - - * windows.texi (Window Start): Fix `pos-visible-in-window-p' - return value. Third element FULLY replaced by PARTIAL which - specifies number of invisible pixels if row is only partially visible. - (Textual Scrolling): Mention auto-window-vscroll. - (Vertical Scrolling): New defvar auto-window-vscroll. - -2005-01-16 Luc Teirlinck - - * keymaps.texi (Changing Key Bindings): `suppress-keymap' now uses - command remapping. - -2005-01-15 Richard M. Stallman - - * display.texi (Defining Images): Mention DATA-P arg of create-image. - -2005-01-14 Kim F. Storm - - * commands.texi (Accessing Events): Add WHOLE arg to posn-at-x-y. - - * text.texi (Links and Mouse-1): Fix string and vector item. - -2005-01-13 Richard M. Stallman - - * keymaps.texi (Active Keymaps): Rewrite the text, and update the - descriptions of overriding-local-map and overriding-terminal-local-map. - - * text.texi (Links and Mouse-1): Clarify text. - -2005-01-13 Kim F. Storm - - * modes.texi (Emulating Mode Line): Update format-mode-line entry. - -2005-01-13 Francis Litterio (tiny change) - - * keymaps.texi (Active Keymaps): Fix overriding-local-map description. - -2005-01-12 Kim F. Storm - - * text.texi (Links and Mouse-1): Rename section from Enabling - Mouse-1 to Following Links. Change xrefs. - Add examples for define-button-type and define-widget. - - * display.texi (Button Properties, Button Buffer Commands): - Clarify mouse-1 and follow-link functionality. - -2005-01-12 Richard M. Stallman - - * text.texi (Enabling Mouse-1 to Follow Links): Redo prev. change. - - * display.texi (Beeping): Fix Texinfo usage. - - * modes.texi (Emulating Mode Line): Doc FACE arg in format-header-line. - -2005-01-11 Kim F. Storm - - * display.texi (Button Properties, Button Buffer Commands): - Mention mouse-1 binding. Add follow-link keyword. - - * text.texi (Text Properties): Add "Enable Mouse-1" to submenu. - (Enabling Mouse-1 to Follow Links): New subsection. - -2005-01-06 Richard M. Stallman - - * text.texi (Special Properties): Minor change. - - * os.texi (Timers): Clarify previous change. - - * modes.texi (Emulating Mode Line): format-mode-line requires 1 arg. - -2005-01-01 Luc Teirlinck - - * display.texi (Face Attributes): Correct xref to renamed node. - -2005-01-01 Richard M. Stallman - - * display.texi (Face Attributes): Describe hex color specs. - -2004-12-31 Richard M. Stallman - - * os.texi (Timers): Update previous change. - -2004-12-30 Kim F. Storm - - * display.texi (Line Height): Total line-height is now specified - in line-height property of form (HEIGHT TOTAL). Swap (FACE . RATIO) - in cons cells. (nil . RATIO) is relative to actual line height. - Use line-height `t' instead of `0' to get minimum height. - -2004-12-29 Richard M. Stallman - - * os.texi (Timers): Discuss timers vs editing the buffer and undo. - -2004-12-28 Richard M. Stallman - - * commands.texi (Quitting): Clarify value of with-local-quit. - - * elisp.texi (Top): Fix previous change. - - * loading.texi (Loading): Fix previous change. - -2004-12-27 Richard M. Stallman - - * Makefile.in (MAKEINFO): Specify --force. - - * buffers.texi (Killing Buffers): Add buffer-save-without-query. - - * modes.texi (Emulating Mode Line): Document format's BUFFER arg. - - * display.texi (Line Height): Further clarify. - - * elisp.texi (Top): Update Loading submenu. - - * loading.texi (Where Defined): New node. - (Unloading): load-history moved to Where Defined. - -2004-12-21 Richard M. Stallman - - * commands.texi (Event Input Misc): Add while-no-input. - -2004-12-11 Richard M. Stallman - - * display.texi (Line Height): Rewrite text for clarity. - -2004-12-11 Kim F. Storm - - * display.texi (Display): Add node "Line Height" to menu. - (Line Height): New node. Move full description of line-spacing - and line-height text properties here from text.texi. - (Scroll Bars): Add vertical-scroll-bar variable. - - * frames.texi (Window Frame Parameters): Remove line-height defvar. - - * locals.texi (Standard Buffer-Local Variables): Fix xref for - line-spacing and vertical-scroll-bar. - - * text.texi (Special Properties): Just mention line-spacing and - line-height here, add xref to new "Line Height" node. - -2004-12-09 Thien-Thi Nguyen - - * frames.texi (Window Frame Parameters): New @defvar for `line-spacing'. - - * locals.texi (Standard Buffer-Local Variables): - Add @xref for `line-spacing'. - -2004-12-05 Richard M. Stallman - - * Makefile.in (maintainer-clean): Remove the info files - in $(infodir) where they are created. - -2004-12-03 Richard M. Stallman - - * windows.texi (Selecting Windows): get-lru-window and - get-largest-window don't consider dedicated windows. - - * text.texi (Undo): Document undo-in-progress. - -2004-11-26 Richard M. Stallman - - * locals.texi (Standard Buffer-Local Variables): Undo prev change. - Remove a few vars that are not always buffer-local. - -2004-11-24 Luc Teirlinck - - * locals.texi (Standard Buffer-Local Variables): Comment out - xref's to non-existent node `Yet to be written'. - -2004-11-24 Richard M. Stallman - - * processes.texi (Synchronous Processes): Grammar fix. - - * numbers.texi (Comparison of Numbers): Add eql. - - * locals.texi (Standard Buffer-Local Variables): Add many vars. - - * intro.texi (Printing Notation): Fix previous change. - - * display.texi (Customizing Bitmaps): Move indicate-buffer-boundaries - and default-indicate-buffer-boundaries from here. - (Usual Display): To here. - (Scroll Bars): Add scroll-bar-mode and scroll-bar-width. - (Usual Display): Move tab-width up. - - * customize.texi (Variable Definitions): - Replace show-paren-mode example with tooltip-mode. - (Simple Types, Composite Types, Defining New Types): - Minor cleanups. - -2004-11-21 Jesper Harder - - * processes.texi (Synchronous Processes, Output from Processes): - Markup fix. - -2004-11-20 Richard M. Stallman - - * positions.texi (Skipping Characters): skip-chars-forward - now handles char classes. - - * intro.texi (Printing Notation): Avoid confusion of `print' - when explaining @print. - - * macros.texi (Argument Evaluation): Fix 1st `for' expansion example. - - * display.texi (Display Table Format): Minor fix. - - * streams.texi (Output Functions): Fix print example. - - * Makefile.in (elisp): New target. - (dist): Depend on $(infodir)/elisp, not elisp. - Copy the info files from $(infodir). - - * minibuf.texi (Text from Minibuffer): Document KEEP-ALL arg in - read-from-minibuffer. - - * searching.texi (Regexp Search): Rename that to search-spaces-regexp. - -2004-11-19 Richard M. Stallman - - * searching.texi (Regexp Search): Add search-whitespace-regexp. - -2004-11-19 CHENG Gao (tiny change) - - * tips.texi (Coding Conventions): Fix typo. - -2004-11-16 Richard M. Stallman - - * tips.texi (Coding Conventions): Separate defvar and require - methods to avoid warnings. Use require only when there are many - functions and variables from that package. - - * minibuf.texi (Minibuffer Completion): When ignoring case, - predicate must not be case-sensitive. - - * debugging.texi (Function Debugging, Explicit Debug): Clarified. - (Test Coverage): Don't talk about "splotches". Clarified. - -2004-11-16 Thien-Thi Nguyen - - * frames.texi (Window Frame Parameters): Fix typo. - -2004-11-15 Kim F. Storm - - * symbols.texi (Other Plists): Note that plist-get may signal error. - Add safe-plist-get. - -2004-11-15 Thien-Thi Nguyen - - * modes.texi (Font Lock Basics): Fix typo. - -2004-11-08 Richard M. Stallman - - * syntax.texi (Syntax Table Functions): Add syntax-after. - -2004-11-06 Lars Brinkhoff - - * os.texi (Processor Run Time): New section documenting - get-internal-run-time. - -2004-11-06 Eli Zaretskii - - * Makefile.in (install, maintainer-clean): Don't use "elisp-*" as - it nukes elisp-cover.texi. - (dist): Change elisp-[0-9] to elisp-[1-9], as there could be no - elisp-0 etc. - -2004-11-05 Luc Teirlinck - - * commands.texi (Keyboard Macros): Document `append' return value - of `defining-kbd-macro'. - -2004-11-01 Richard M. Stallman - - * commands.texi (Interactive Call): Add called-interactively-p. - -2004-10-29 Simon Josefsson - - * minibuf.texi (Reading a Password): Revert. - -2004-10-28 Richard M. Stallman - - * frames.texi (Display Feature Testing): Explain about "vendor". - -2004-10-27 Richard M. Stallman - - * commands.texi (Interactive Codes): `N' uses numeric prefix, - not raw. Clarify `n'. - (Interactive Call): Rewrite interactive-p, focusing on when - and how to use it. - (Misc Events): Clarify previous change. - - * advice.texi (Simple Advice): Clarify what job the example does. - (Around-Advice): Clarify ad-do-it. - (Activation of Advice): An option of ad-default-compilation-action - is `never', not `nil'. - -2004-10-26 Kim F. Storm - - * commands.texi (Interactive Codes): Add U code letter. - -2004-10-25 Simon Josefsson - - * minibuf.texi (Reading a Password): Add. - -2004-10-24 Jason Rumney - - * commands.texi (Misc Events): Remove mouse-wheel. Add wheel-up - and wheel-down. - -2004-10-24 Kai Grossjohann - - * processes.texi (Synchronous Processes): Document process-file. - -2004-10-22 Kenichi Handa - - * text.texi (translate-region): Document that it accepts also a - char-table. - -2004-10-22 David Ponce - - * windows.texi (Resizing Windows): Document the `preserve-before' - argument of the functions `enlarge-window' and `shrink-window'. - -2004-10-19 Jason Rumney - - * makefile.w32-in (elisp): Change order of arguments to makeinfo. - -2004-10-09 Luc Teirlinck - - * text.texi (Filling): Add anchor for definition of - `sentence-end-double-space'. - - * searching.texi (Regexp Example): Update description of how - Emacs currently recognizes the end of a sentence. - (Standard Regexps): Update definition of the variable - `sentence-end'. Add definition of the function `sentence-end'. - -2004-10-08 Paul Pogonyshev - - * display.texi (Progress): New node. - -2004-10-05 Kim F. Storm - - * display.texi (Fringe Bitmaps): Update fringe-bitmaps-at-pos. - -2004-09-29 Kim F. Storm - - * display.texi (Fringe Bitmaps): Use symbols rather than numbers - to identify bitmaps. Remove -fringe-bitmap suffix for standard - fringe bitmap symbols, as they now have their own namespace. - (Customizing Bitmaps) : Clarify bit ordering - vs. pixels. Signal error if no free bitmap slots. - (Pixel Specification): Change IMAGE to @var{image}. - -2004-09-28 Richard M. Stallman - - * text.texi (Special Properties): Clarify line-spacing and line-height. - - * searching.texi (Regexp Search): Add looking-back. - -2004-09-25 Luc Teirlinck - - * display.texi: Correct typos. - (Image Descriptors): Correct xref's. - -2004-09-25 Richard M. Stallman - - * text.texi (Special Properties): Cleanups in `cursor'. - Rewrites in `line-height' and `line-spacing'; exchange them. - - * display.texi (Fringes): Rewrite previous change. - (Fringe Bitmaps): Merge text from Display Fringe Bitmaps. Rewrite. - (Display Fringe Bitmaps): Node deleted, text moved. - (Customizing Bitmaps): Split off from Fringe Bitmaps. Rewrite. - (Scroll Bars): Clarify set-window-scroll-bars. - (Pointer Shape): Rewrite. - (Specified Space): Clarify :align-to, etc. - (Pixel Specification): Use @var. Clarify new text. - (Other Display Specs): Clarify `slice'. - (Image Descriptors): Cleanups. - (Showing Images): Cleanups. - -2004-09-24 Luc Teirlinck - - * hooks.texi (Standard Hooks): Add `after-change-major-mode-hook'. - - * modes.texi: Various minor changes in addition to: - (Major Mode Conventions): Final call to `run-mode-hooks' should - not be inside the `delay-mode-hooks' form. - (Mode Hooks): New node. - (Hooks): Delete obsolete example. - Move definitions of `run-mode-hooks' and `delay-mode-hooks' to new - node "Mode Hooks". - -2004-09-22 Luc Teirlinck - - * display.texi: Correct various typos. - (Display): Rename node "Pointer Shapes" to "Pointer - Shape". (There is already a node called "Pointer Shapes" in - frames.texi.) - (Images): Remove non-existent node "Image Slices" from menu. - -2004-09-23 Kim F. Storm - - * text.texi (Special Properties): Add `cursor', `pointer', - `line-height', and `line-spacing' properties. - - * display.texi (Display): Add 'Fringe Bitmaps' and 'Pointer - Shapes' to menu. - (Standard Faces): Doc fix for fringe face. - (Fringes): Add `overflow-newline-into-fringe' and - 'indicate-buffer-boundaries'. - (Fringe Bitmaps, Pointer Shapes): New nodes. - (Display Property): Add 'Pixel Specification' and 'Display Fringe - Bitmaps' to menu. - (Specified Space): Describe pixel width and height. - (Pixel Specification): New node. - (Other Display Specs): Add `slice' property. - (Display Fringe Bitmaps): New node. - (Images): Add 'Image Slices' to menu. - (Image Descriptors): Add `:pointer' and `:map' properties. - (Showing Images): Add slice arg to `insert-image'. - Add 'insert-sliced-image'. - -2004-09-20 Richard M. Stallman - - * commands.texi (Key Sequence Input): - Clarify downcasing in read-key-sequence. - -2004-09-08 Juri Linkov - - * minibuf.texi (Minibuffer History): Add `history-delete-duplicates'. - -2004-09-07 Luc Teirlinck - - * locals.texi (Standard Buffer-Local Variables): - Add `buffer-auto-save-file-format'. - * internals.texi (Buffer Internals): Describe new - auto_save_file_format field of the buffer structure. - * files.texi (Format Conversion): `auto-save-file-format' has been - renamed `buffer-auto-save-file-format'. - -2004-08-27 Luc Teirlinck - - * abbrevs.texi (Abbrev Expansion): `abbrev-start-location' can be - an integer or a marker. - (Abbrev Expansion): Replace example for `pre-abbrev-expand-hook'. - -2004-08-22 Richard M. Stallman - - * modes.texi (Major Mode Conventions): Discuss rebinding of - standard key bindings. - -2004-08-18 Kim F. Storm - - * processes.texi (Accepting Output): Add `just-this-one' arg to - `accept-process-output'. - (Output from Processes): New var `process-adaptive-read-buffering'. - -2004-08-10 Luc Teirlinck - - * keymaps.texi: Various changes in addition to: - (Keymap Terminology): `kbd' uses same syntax as Edit Macro mode. - Give more varied examples for `kbd'. - (Creating Keymaps): Char tables have slots for all characters - without modifiers. - (Active Keymaps): `overriding-local-map' and - `overriding-terminal-local-map' also override text property and - overlay keymaps. - (Functions for Key Lookup): Mention OLP arg to `current-active-maps'. - (Scanning Keymaps): `accessible-keymaps' uses `[]' instead of `""' - to denote a prefix of no events. - `map-keymap' includes parent's bindings _recursively_. - Clarify and correct description of `where-is-internal'. - Mention BUFFER-OR-NAME arg to `describe-bindings'. - (Menu Example): For menus intended for use with the keyboard, the - menu items should be bound to characters or real function keys. - -2004-08-08 Luc Teirlinck - - * objects.texi (Character Type): Reposition `@anchor' to prevent - double space inside sentence in Info. - - * hooks.texi (Standard Hooks): `disabled-command-hook' has been - renamed to `disabled-command-function'. - * commands.texi (Key Sequence Input): Remove unnecessary anchor. - (Command Loop Info): Replace reference to it. - (Disabling Commands): `disabled-command-hook' has been renamed to - `disabled-command-function'. - -2004-08-07 Luc Teirlinck - - * os.texi (Translating Input): Only non-prefix bindings in - `key-translation-map' override actual key bindings. Warn about - possible indirect effect of actual key bindings on non-prefix - bindings in `key-translation-map'. - -2004-08-06 Luc Teirlinck - - * minibuf.texi (High-Level Completion): Add anchor for definition - of `read-variable'. - - * commands.texi: Various changes in addition to: - (Using Interactive): Clarify description of `interactive-form'. - (Interactive Call): Mention default for KEYS argument to - `call-interactively'. - (Command Loop Info): Clarify description of `this-command-keys'. - Mention KEEP-RECORD argument to `clear-this-command-keys'. - Value of `last-event-frame' can be `macro'. - (Repeat Events): `double-click-fuzz' is also used to distinguish - clicks and drags. - (Classifying Events): Clarify descriptions of `event-modifiers' - `event-basic-type' and `event-convert-list'. - (Accessing Events): `posn-timestamp' takes POSITION argument. - (Quoted Character Input): Clarify description of - `read-quoted-char' and fix example. - (Quitting): Add `with-local-quit'. - (Disabling Commands): Correct and clarify descriptions of - `enable-command' and `disable-command'. - Mention what happens if `disabled-command-hook' is nil. - (Keyboard Macros): Mention LOOPFUNC arg to `execute-kbd-macro'. - Describe `executing-kbd-macro' instead of obsolete `executing-macro'. - -2004-07-24 Luc Teirlinck - - * frames.texi: Various changes in addition to: - (Creating Frames): Expand and clarify description of `make-frame'. - (Window Frame Parameters): Either none or both of the `icon-left' - and `icon-top' parameters must be specified. Put descriptions of - `menu-bar-lines' and `toolbar-lines' closer together and change - them accordingly. - (Frame Titles): `multiple-frames' is not guaranteed to be accurate - except while processing `frame-title-format' or `icon-title-format'. - (Deleting Frames): Correct description of `delete-frame'. - Non-nil return values of `frame-live-p' are like those of `framep'. - (Frames and Windows): Mention return value of - `set-frame-selected-window'. - (Visibility of Frames): Mention `force' argument to - `make-frame-invisible'. `frame-visible-p' returns t for all - frames on text-only terminals. - (Frame Configurations): Restoring a frame configuration does not - restore deleted frames. - (Window System Selections): `x-set-selection' returns DATA. - (Resources): Add example. - (Display Feature Testing): Clarify descriptions of - `display-pixel-height', `display-pixel-width', `x-server-version' - and `x-server-vendor'. - - * windows.texi (Choosing Window): Add anchor. - * minibuf.texi (Minibuffer Misc): Add anchor. - -2004-07-23 John Paul Wallington - - * macros.texi (Defining Macros): Declaration keyword for setting - Edebug spec is `debug' not `edebug'. - -2004-07-19 Luc Teirlinck - - * windows.texi: Various small changes in addition to: - (Window Point): Mention return value of `set-window-point'. - (Window Start): `pos-visible-in-window-p' disregards horizontal - scrolling. Explain return value if PARTIALLY is non-nil. - (Vertical Scrolling): Mention PIXELS-P argument to `window-vscroll' - and `set-window-vscroll'. - (Size of Window): The argument WINDOW to `window-inside-edges', - `window-pixel-edges' and `window-inside-pixel-edges' is optional. - (Resizing Windows): Explain return value of - `shrink-window-if-larger-than-buffer'. - `window-size-fixed' automatically becomes buffer local when set. - (Window Configurations): Explain return value of - `set-window-configuration'. - - * minibuf.texi (Minibuffer Misc): Add anchor for - `minibuffer-scroll-window'. - - * positions.texi (Text Lines): Add anchor for `count-lines'. - -2004-07-17 Richard M. Stallman - - * display.texi (Overlay Properties): Adding `evaporate' prop - deletes empty overlay immediately. - - * abbrevs.texi (Abbrev Expansion): Clarify pre-abbrev-expand-hook, - fix example. - -2004-07-16 Jim Blandy - - * searching.texi (Regexp Backslash): Document new \_< and \_> - operators. - -2004-07-16 Juanma Barranquero - - * display.texi (Images): Fix Texinfo usage. - -2004-07-14 Luc Teirlinck - - * buffers.texi (Modification Time): `visited-file-modtime' now - returns a list of two integers, instead of a cons. - -2004-07-13 Luc Teirlinck - - * windows.texi: Various changes in addition to: - (Splitting Windows): Add `split-window-keep-point'. - -2004-07-09 Richard M. Stallman - - * frames.texi (Input Focus): Minor fix. - -2004-07-07 Luc Teirlinck - - * frames.texi (Input Focus): Clarify descriptions of - `select-frame-set-input-focus' and `select-frame'. - -2004-07-06 Luc Teirlinck - - * os.texi: Various small changes in addition to: - (Killing Emacs): Expand and clarify description of - `kill-emacs-query-functions' and `kill-emacs-hook'. - (System Environment): Expand and clarify description of `getenv' - and `setenv'. - (Timers): Clarify description of `run-at-time'. - (Translating Input): Correct description of - `extra-keyboard-modifiers'. - (Flow Control): Correct description of `enable-flow-control'. - -2004-07-06 Thien-Thi Nguyen - - * os.texi: Update copyright. - (Session Management): Grammar fix. - Clarify which Emacs does the restarting. - Use @samp for *scratch* buffer. - -2004-07-04 Alan Mackenzie - - * frames.texi (Input Focus): Add documentation for - `select-frame-set-input-focus'. Replace refs to non-existent - `switch-frame' with `select-frame'. Minor corrections and tidying - up of text-only terminal stuff. - -2004-07-02 Richard M. Stallman - - * files.texi (Saving Buffers): Cleanup write-contents-function. - (Magic File Names): Cleanup file-remote-p. - -2004-07-02 Kai Großjohann - - * files.texi (Magic File Names): `file-remote-p' returns an - identifier of the remote system, not just t. - -2004-07-02 David Kastrup - - * searching.texi (Entire Match Data): Add explanation about new - match-data behavior when @var{integers} is non-nil. - -2004-06-24 Richard M. Stallman - - * commands.texi (Misc Events): Describe usr1-signal, usr2-signal event. - - * customize.texi (Variable Definitions): Note about doc strings - and :set. - - * keymaps.texi (Keymap Terminology): Document `kbd'. - (Changing Key Bindings, Key Binding Commands): Use kbd in examples. - - * display.texi (Invisible Text): Setting buffer-invisibility-spec - makes it buffer-local. - - * files.texi (Saving Buffers): Correct previous change. - - * commands.texi (Accessing Events): - Clarify posn-col-row and posn-actual-col-row. - -2004-06-24 David Ponce - - * commands.texi (Accessing Events): New functions - posn-at-point and posn-at-x-y. Add example to posn-x-y. - -2004-06-23 Luc Teirlinck - - * lists.texi, files.texi, processes.texi, macros.texi, hash.texi: - * frames.texi, buffers.texi, backups.texi, variables.texi: - * loading.texi, eval.texi, functions.texi, control.texi: - * symbols.texi, minibuf.texi: Reposition @anchor's. - - * help.texi: Various small changes in addition to the following. - (Describing Characters): Describe PREFIX argument to - `key-description'. Correct and clarify definition of - `text-char-description'. Describe NEED-VECTOR argument to - `read-kbd-macro'. - (Help Functions): Clarify definition of `apropos'. - -2004-06-23 Lars Hansen - - * files.texi (Saving Buffers): Correct description of - `write-contents-functions'. - -2004-06-21 Juanma Barranquero - - * display.texi (Images): Remove redundant @vindex directives. - Rewrite `image-library-alist' doc in active voice. - -2004-06-14 Juanma Barranquero - - * display.texi (Images): Document new delayed library loading, - variable `image-library-alist' and (existing but undocumented) - function `image-type-available-p'. - -2004-06-05 Richard M. Stallman - - * minibuf.texi (Minibuffer Completion): For INITIAL arg, - refer the user to the Initial Input node. - (Text from Minibuffer): Likewise. - (Initial Input): New node. Document this feature - and say it is mostly deprecated. - -2004-05-30 Richard M. Stallman - - * loading.texi (Named Features): Clarify return value - and meaning of NOERROR. - - * variables.texi (File Local Variables): Minor cleanup. - -2004-05-30 Michael Albinus - - * files.texi (Magic File Names): Add `file-remote-p' as operation - of file name handlers. - -2004-05-29 Richard M. Stallman - - * modes.texi (Minor Mode Conventions): (-) has no special meaning - as arg to a minor mode command. - -2004-05-22 Richard M. Stallman - - * syntax.texi (Syntax Class Table): Word syntax not just for English. - - * streams.texi (Output Variables): Doc float-output-format. - - * searching.texi (Regexp Special): Nested repetition can be infloop. - - * eval.texi (Eval): Increasing max-lisp-eval-depth can cause - real stack overflow. - - * compile.texi: Minor cleanups. - -2004-05-22 Luc Teirlinck - - * lists.texi (Cons Cells): Explain dotted lists, true lists, - circular lists. - (List Elements): Explain handling of circular and dotted lists. - -2004-05-19 Thien-Thi Nguyen - - * modes.texi (Search-based Fontification): Fix typo. - -2004-05-10 Juanma Barranquero - - * modes.texi (Mode Line Variables): Fix description of - global-mode-string, which is now after which-func-mode, not the - buffer name. - -2004-05-07 Lars Hansen - - * modes.texi (Desktop Save Mode): Add. - (Modes): Add menu entry Desktop Save Mode. - - * hooks.texi: Add desktop-after-read-hook, - desktop-no-desktop-file-hook and desktop-save-hook. - - * locals.texi: Add desktop-save-buffer. - -2004-04-30 Jesper Harder - - * display.texi: emacs -> Emacs. - -2004-04-27 Matthew Mundell - - * files.texi (Changing Files): Document set-file-times. - -2004-04-23 Juanma Barranquero - - * makefile.w32-in: Add "-*- makefile -*-" mode tag. - -2004-04-18 Jesper Harder - - * tips.texi (Coding Conventions): defopt -> defcustom. - -2004-04-16 Luc Teirlinck - - * sequences.texi: Various clarifications. - -2004-04-14 Luc Teirlinck - - * buffers.texi (Read Only Buffers): Mention optional ARG to - `toggle-read-only'. - -2004-04-14 Nick Roberts - - * windows.texi (Selecting Windows): Note that get-lru-window - returns a full-width window if possible. - -2004-04-13 Luc Teirlinck - - * buffers.texi: Various changes in addition to: - (Buffer File Name): Add `find-buffer-visiting'. - (Buffer Modification): Mention optional ARG to `not-modified'. - (Indirect Buffers): Mention optional CLONE argument to - `make-indirect-buffer'. - - * files.texi: Various changes in addition to: - (Visiting Functions): `find-file-hook' is now a normal hook. - (File Name Expansion): Explain difference between the way that - `expand-file-name' and `file-truename' treat `..'. - (Contents of Directories): Mention optional ID-FORMAT argument to - `directory-files-and-attributes'. - (Format Conversion): Mention new optional CONFIRM argument to - `format-write-file'. - -2004-04-12 Miles Bader - - * macros.texi (Expansion): Add description of `macroexpand-all'. - -2004-04-05 Jesper Harder - - * variables.texi (Variable Aliases): - Mention cyclic-variable-indirection. - - * errors.texi (Standard Errors): Ditto. - -2004-04-04 Luc Teirlinck - - * backups.texi: Various small changes in addition to: - (Making Backups): Mention return value of `backup-buffer'. - (Auto-Saving): Mention optional FORCE argument to - `delete-auto-save-file-if-necessary'. - (Reverting): Mention optional PRESERVE-MODES argument to - `revert-buffer'. Correct description of `revert-buffer-function'. - -2004-03-22 Juri Linkov - - * sequences.texi (Sequence Functions): Replace xref to `Vectors' - with `Vector Functions'. - - * text.texi (Sorting): Add missing quote. - -2004-03-14 Luc Teirlinck - - * intro.texi (Lisp History): Replace xref to `cl' manual with - inforef. - -2004-03-12 Richard M. Stallman - - * intro.texi (Version Info): Add arg to emacs-version. - (Lisp History): Change xref to CL manual. - -2004-03-09 Luc Teirlinck - - * minibuf.texi (Completion Commands): Add xref to Emacs manual - for Partial Completion mode. - -2004-03-07 Thien-Thi Nguyen - - * customize.texi: Fix typo. Remove eol whitespace. - -2004-03-04 Richard M. Stallman - - * processes.texi: Fix typos. - - * lists.texi (Building Lists): Minor clarification. - - * hash.texi (Creating Hash): Correct the meaning of t for WEAK - in make-hash-table. - -2004-02-29 Juanma Barranquero - - * makefile.w32-in (clean, maintainer-clean): Use $(DEL) instead of - rm, and ignore exit code. - -2004-02-27 Dan Nicolaescu - - * display.texi (Defining Faces): Add description for min-colors. - Update example. - -2004-02-23 Luc Teirlinck - - * abbrevs.texi: Various corrections and clarifications in addition - to the following: - (Abbrev Tables): Delete add-abbrev (as suggested by RMS). - -2004-02-22 Matthew Mundell (tiny change) - - * calendar.texi (Holiday Customizing): Quote arg of holiday-sexp. - -2004-02-21 Luc Teirlinck - - * text.texi: Various small changes in addition to the following: - (User-Level Deletion): Mention optional BACKWARD-ONLY argument - to delete-horizontal-space. - (Kill Functions, Yanking, Low-Level Kill Ring): Clarify and correct - description of yank-handler text property at various places. - - * frames.texi (Window System Selections): Add anchor. - - * syntax.texi (Syntax Table Functions): Clarify and correct - descriptions of make-syntax-table and copy-syntax-table. - (Motion and Syntax): Clarify SYNTAXES argument to - skip-syntax-forward. - (Parsing Expressions): Mention that the return value of - parse-partial-sexp is currently a list of ten rather than nine - elements. - (Categories): Various corrections and clarifications. - -2004-02-17 Luc Teirlinck - - * markers.texi (Marker Insertion Types): Minor change. - - * locals.texi (Standard Buffer-Local Variables): - * commands.texi (Interactive Codes, Using Interactive): - * functions.texi (Related Topics): Fix xrefs. - -2004-02-16 Luc Teirlinck - - * lists.texi (Sets And Lists): Update description of delete-dups. - -2004-02-16 Jesper Harder (tiny change) - - * keymaps.texi (Tool Bar): tool-bar-item => tool-bar-button. - -2004-02-16 Jan Djärv - - * frames.texi (Parameter Access): frame-parameters arg is optional. - modify-frame-parameters handles nil for FRAME. - (Window Frame Parameters): menu-bar-lines and tool-bar-lines - are all-or-nothing for certain toolkits. - Mention parameter wait-for-wm. - (Frames and Windows): In frame-first-window and frame-selected-window - the arg is optional. - (Input Focus): In redirect-frame-focus the second arg is optional. - (Window System Selections): Mention selection type CLIPBOARD. - Mention data-type UTF8_STRING. - Mention numbering of cut buffers. - (Resources): Describe x-resource-name. - -2004-02-16 Richard M. Stallman - - * windows.texi (Buffers and Windows): Delete false table - about all-frames. - - * syntax.texi (Parsing Expressions): Delete old caveat - about parse-sexp-ignore-comments. - - * streams.texi (Output Variables): Add print-quoted. - - * lists.texi (Building Lists): Minor cleanup. - - * hash.texi (Creating Hash): Correct and clarify doc of WEAK values. - - * display.texi (Overlays): Explain overlays use markers. - (Managing Overlays): Explain front-advance and rear-advance - in more detail. - - * loading.texi (Unloading): Document unload-feature-special-hooks. - Get rid of fns-NNN.el file. - -2004-02-16 Matthew Mundell (tiny change) - - * help.texi (Describing Characters): Fix text-char-description - example output. - - * edebug.texi (Using Edebug): Fix example. - - * debugging.texi (Internals of Debugger): Fix return value. - - * files.texi (Changing Files): Fix argname. - - * calendar.texi: Fix parens, and default values. - - * display.texi, frames.texi, internals.texi, modes.texi: Minor fixes. - * nonascii.texi, objects.texi, os.texi: Minor fixes. - * searching.texi, text.texi, tips.texi, windows.texi: Minor fixes. - - * positions.texi (Text Lines): Don't add -1 in current-line. - -2004-02-16 Richard M. Stallman - - * compile.texi (Compiler Errors): if-boundp feature applies to cond. - -2004-02-16 Jesper Harder (tiny change) - - * processes.texi (Low-Level Network): Fix a typo. - -2004-02-12 Kim F. Storm - - * display.texi (Fringes): Use consistent wording. - Note that window-fringe's window arg is optional. - (Scroll Bars): Use consistent wording. - -2004-02-11 Luc Teirlinck - - * tips.texi (Comment Tips): Document the new conventions for - commenting out code. - -2004-02-07 Jan Djärv - - * positions.texi (Text Lines): Add missing end defun. - -2004-02-07 Kim F. Storm - - * positions.texi (Text Lines): Add line-number-at-pos. - -2004-02-06 John Paul Wallington - - * display.texi (Button Properties, Button Buffer Commands): - mouse-2 invokes button, not down-mouse-1. - -2004-02-04 Jason Rumney - - * makefile.w32-in: Sync with Makefile.in changes. - -2004-02-03 Luc Teirlinck - - * minibuf.texi (Text from Minibuffer): Various corrections and - clarifications. - (Object from Minibuffer): Correct Lisp description of - read-minibuffer. - (Minibuffer History): Clarify description of cons values for - HISTORY arguments. - (Basic Completion): Various corrections and clarifications. - Add completion-regexp-list. - (Minibuffer Completion): Correct and clarify description of - completing-read. - (Completion Commands): Mention Partial Completion mode. - Various other minor changes. - (High-Level Completion): Various corrections and clarifications. - (Reading File Names): Ditto. - (Minibuffer Misc): Ditto. - -2004-01-26 Luc Teirlinck - - * strings.texi (Text Comparison): assoc-string also matches - elements of alists that are strings instead of conses. - (Formatting Strings): Standardize Texinfo usage. Update index - entries. - -2004-01-20 Luc Teirlinck - - * lists.texi (Sets And Lists): Add delete-dups. - -2004-01-15 Luc Teirlinck - - * edebug.texi (Instrumenting Macro Calls): `declare' is not a - special form. - * macros.texi (Defining Macros): Update description of `declare', - which now is a macro. - (Wrong Time): Fix typos. - -2004-01-14 Luc Teirlinck - - * compile.texi (Compilation Functions): Expand descriptions of - `compile-defun', `byte-compile-file', `byte-recompile-directory' - and `batch-byte-compile'. In particular, mention and describe - all optional arguments. - (Disassembly): Correct and clarify the description of `disassemble'. - -2004-01-11 Luc Teirlinck - - * searching.texi: Various small changes in addition to the - following. - (Regexp Example): Adapt to new value of `sentence-end'. - (Regexp Functions): The PAREN argument to `regexp-opt' can be - `words'. - (Search and Replace): Add usage note for `perform-replace'. - (Entire Match Data): Mention INTEGERS and REUSE arguments to - `match-data'. - (Standard Regexps): Update for new values of `paragraph-start' - and `sentence-end'. - -2004-01-07 Luc Teirlinck - - * files.texi (Saving Buffers): Clarify descriptions of - `write-contents-functions' and `before-save-hook'. - Make the defvar's for `before-save-hook' and `after-save-hook' - into defopt's. - -2004-01-07 Kim F. Storm - - * commands.texi (Click Events): Describe new image and - width/height elements of click events. - (Accessing Events): Add posn-string, posn-image, and - posn-object-width-height. Change posn-object to return either - image or string object. - -2004-01-01 Simon Josefsson - - * hooks.texi (Standard Hooks): Add before-save-hook. - * files.texi (Saving Buffers): Likewise. - -2004-01-03 Richard M. Stallman - - * frames.texi (Frames and Windows): Delete frame-root-window. - -2004-01-03 Luc Teirlinck - - * eval.texi, hash.texi, help.texi, symbols.texi: Add anchors. - - * functions.texi: Various small changes in addition to the - following. - (What Is a Function): `functionp' returns nil for macros. - Clarify behavior of this and following functions for symbol arguments. - (Function Documentation): Add `\' in front of (fn @var{arglist}) - and explain why. - (Defining Functions): Mention DOCSTRING argument to `defalias'. - Add anchor. - (Mapping Functions): Add anchor. Unquote nil in mapcar* example. - -2004-01-01 Miles Bader - - * display.texi (Buttons): New section. - -2003-12-31 Andreas Schwab - - * numbers.texi (Math Functions): sqrt reports a domain-error - error. - (Float Basics): Use `(/ 0.0 0.0)' instead of `(sqrt -1.0)'. - -2003-12-30 Luc Teirlinck - - * tips.texi (Documentation Tips): Update item on hyperlinks in - documentation strings. - - * errors.texi (Standard Errors): Various small corrections and - additions. - - * control.texi: Various small changes in addition to the - following. - (Signaling Errors): Provide some more details on how `signal' - constructs the error message. Add anchor to the definition of - `signal'. - (Error Symbols): Describe special treatment of `quit'. - (Cleanups): Rename BODY argument of `unwind-protect' to BODY-FORM - to emphasize that it has to be a single form. - - * buffers.texi: Add anchor. - -2003-12-29 Richard M. Stallman - - * windows.texi (Choosing Window): Add same-window-p, special-display-p. - (Window Configurations): Add window-configuration-frame. - - * variables.texi (Creating Buffer-Local): Add local-variable-if-set-p. - - * text.texi (Examining Properties): Add get-char-property-and-overlay. - Change arg name in get-char-property. - (Special Properties): Update handling of keymap property. - - * strings.texi (Modifying Strings): Add clear-string. - (Text Comparison): Add assoc-string and remove - assoc-ignore-case, assoc-ignore-representation. - - * os.texi (Time of Day): Add set-time-zone-rule. - - * numbers.texi (Math Functions): asin, acos, log, log10 - report domain-error errors. - - * nonascii.texi (Converting Representations): - Add multibyte-char-to-unibyte and unibyte-char-to-multibyte. - (Encoding and I/O): Add file-name-coding-system. - - * modes.texi (Search-based Fontification): Explain that - face specs are symbols with face names as values. - - * minibuf.texi (Minibuffer Misc): Add set-minibuffer-window. - - * lists.texi (Building Lists): remq moved elsewhere. - (Sets And Lists): remq moved here. - (Association Lists): Refer to assoc-string. - - * internals.texi (Garbage Collection): Add memory-use-counts. - - * frames.texi (Frames and Windows): Add set-frame-selected-window - and frame-root-window. - - * files.texi (Contents of Directories): - Add directory-files-and-attributes. - - * display.texi (Refresh Screen): Add force-window-update. - (Invisible Text): Explain about moving point out of invis text. - (Overlay Properties): Add overlay-properties. - (Managing Overlays): Add overlayp. - (GIF Images): Invalid image number displays a hollow box. - - * buffers.texi (Buffer Modification): Add restore-buffer-modified-p. - (Killing Buffers): Add buffer-live-p. - -2003-12-25 Markus Rost - - * display.texi (Fringes): Fix typo "set-buffer-window". - -2003-12-24 Luc Teirlinck - - * display.texi, eval.texi, help.texi, internals.texi, loading.texi: - * nonascii.texi, processes.texi, tips.texi, variables.texi: - Add or change various xrefs and anchors. - - * commands.texi: Replace all occurrences of @acronym{CAR} with - @sc{car}, for consistency with the rest of the Elisp manual. - `car' and `cdr' are historically acronyms, but are no longer - widely thought of as such. - - * internals.texi (Pure Storage): Mention that `purecopy' does not - copy text properties. - (Object Internals): Now 29 bits are used (in most implementations) - to address Lisp objects. - - * variables.texi (Variables with Restricted Values): New node. - - * objects.texi (Lisp Data Types): Mention that certain variables - can only take on a restricted set of values and add an xref to - the new node "Variables with Restricted Values". - - * eval.texi (Function Indirection): Describe the errors that - `indirect-function' can signal. - (Eval): Clarify the descriptions of `eval-region' and `values'. - Describe `eval-buffer' instead of `eval-current-buffer' and - mention `eval-current-buffer' as an alias for `current-buffer'. - Correct the description and mention all optional arguments. - - * nonascii.texi: Various small changes in addition to the - following. - (Converting Representations): Clarify behavior of - `string-make-multibyte' and `string-to-multibyte' for unibyte all - ASCII arguments. - (Character Sets): Document the variable `charset-list' and adapt - the definition of the function `charset-list' accordingly. - (Translation of Characters): Clarify use of generic characters in - `make-translation-table'. Clarify and correct the description of - the use of translation tables in encoding and decoding. - (User-Chosen Coding Systems): Correct and clarify the description - of `select-safe-coding-system'. - (Default Coding Systems): Clarify description of - `file-coding-system-alist'. - -2003-11-30 Luc Teirlinck - - * strings.texi (Text Comparison): Correctly describe when two - strings are `equal'. Combine and clarify descriptions of - `assoc-ignore-case' and `assoc-ignore-representation'. - - * objects.texi (Non-ASCII in Strings): Clarify description of - when a string is unibyte or multibyte. - (Bool-Vector Type): Update examples. - (Equality Predicates): Correctly describe when two strings are - `equal'. - -2003-11-29 Luc Teirlinck - - * lists.texi (Building Lists): `append' no longer accepts integer - arguments. Update the description of `number-sequence' to reflect - recent changes. - (Sets And Lists): Describe `member-ignore-case' after `member'. - -2003-11-27 Kim F. Storm - - * commands.texi (Click Events): Click object may be an images. - Describe (dx . dy) element of click positions. - (Accessing Events): Remove duplicate posn-timestamp. - New functions posn-object and posn-object-x-y. - -2003-11-23 Kim F. Storm - - * commands.texi (Click Events): Describe enhancements to event - position lists, including new text-pos and (col . row) items. - Mention left-fringe and right-fringe area events. - (Accessing Events): New functions posn-area and - posn-actual-col-row. Mention posn-timestamp. Mention that - posn-point in non-text area still returns buffer position. - Clarify posn-col-row. - -2003-11-21 Lars Hansen - - * files.texi (File Attributes): Describe new parameter ID-FORMAT. - * anti.texi (File Attributes): Describe removed parameter - ID-FORMAT. - -2003-11-20 Luc Teirlinck - - * positions.texi (Positions): Mention that, if a marker is used as - a position, its buffer is ignored. - - * markers.texi (Overview of Markers): Mention it here too. - -2003-11-12 Luc Teirlinck - - * numbers.texi (Numeric Conversions): Not just `floor', but also - `truncate', `ceiling' and `round' accept optional argument DIVISOR. - -2003-11-10 Luc Teirlinck - - * markers.texi (Creating Markers): Specify insertion type of - created markers. Add xref to `Marker Insertion Types'. - Second argument to `copy-marker' is optional. - (Marker Insertion Types): Mention that most markers are created - with insertion type nil. - (The Mark): Correctly describe when `mark' signals an error. - (The Region): Correctly describe when `region-beginning' and - `region-end' signal an error. - -2003-11-08 Luc Teirlinck - - * hash.texi (Creating Hash): Clarify description of `eql'. - `makehash' is obsolete. - (Hash Access): Add Common Lisp notes for `remhash' and `clrhash'. - - * positions.texi (Point): Change description of `buffer-end', so - that it is also correct for floating point arguments. - (List Motion): Correct argument lists of `beginning-of-defun' and - `end-of-defun'. - (Excursions): Add xref to `Marker Insertion Types'. - (Narrowing): Argument to `narrow-to-page' is optional. - -2003-11-06 Luc Teirlinck - - * streams.texi (Output Streams): Clarify behavior of point for - marker output streams. - -2003-11-04 Luc Teirlinck - - * variables.texi (Defining Variables): Second argument to - `defconst' is not optional. - (Setting Variables): Mention optional argument APPEND to - `add-to-list'. - (Creating Buffer-Local): Expand description of - `make-variable-buffer-local'. - (Frame-Local Variables): Expand description of - `make-variable-frame-local'. - (Variable Aliases): Correct description of optional argument - DOCSTRING to `defvaralias'. Mention return value of - `defvaralias'. - (File Local Variables): Add xref to `File variables' in Emacs - Manual. Correct description of `hack-local-variables'. Mention - `safe-local-variable' property. Mention optional second argument - to `risky-local-variable-p'. - -2003-11-03 Luc Teirlinck - - * symbols.texi (Symbol Plists): Mention return value of `setplist'. - -2003-11-02 Jesper Harder (tiny change) - - * lispref/anti.texi, lispref/backups.texi, lispref/commands.texi - lispref/customize.texi, lispref/display.texi, lispref/files.texi, - lispref/internals.texi, lispref/keymaps.texi, lispref/loading.texi, - lispref/modes.texi, lispref/nonascii.texi, lispref/numbers.texi, - lispref/objects.texi, lispref/os.texi, lispref/positions.texi, - lispref/processes.texi, lispref/searching.texi, - lispref/sequences.texi, lispref/streams.texi, lispref/strings.texi, - lispref/syntax.texi, lispref/text.texi: Replace @sc{foo} with - @acronym{FOO}. - -2003-10-27 Luc Teirlinck - - * strings.texi (Creating Strings): Argument START to `substring' - can not be `nil'. Expand description of - `substring-no-properties'. Correct description of `split-string', - especially with respect to empty matches. Prevent very bad line - break in definition of `split-string-default-separators'. - (Text Comparison): `string=' and `string<' also accept symbols as - arguments. - (String Conversion): More completely describe argument BASE in - `string-to-number'. - (Formatting Strings): `%s' and `%S' in `format' do require - corresponding object. Clarify behavior of numeric prefix after - `%' in `format'. - (Case Conversion): The argument to `upcase-initials' can be a - character. - -2003-10-27 Kenichi Handa - - * display.texi (Fontsets): Fix texinfo usage. - -2003-10-25 Kenichi Handa - - * display.texi (Fontsets): Add description of the function - set-fontset-font. - -2003-10-23 Luc Teirlinck - - * display.texi (Temporary Displays): Add xref to `Documentation - Tips'. - - * functions.texi (Function Safety): Use inforef instead of pxref - for SES. - -2003-10-23 Andreas Schwab - - * Makefile.in (TEX, texinputdir): Don't define. - (TEXI2DVI): Define. - (srcs): Remove $(srcdir)/index.perm and $(srcdir)/index.unperm, - add $(srcdir)/index.texi. - ($(infodir)/elisp): Remove index.texi dependency. - (elisp.dvi): Likewise. Use $(TEXI2DVI). - (index.texi): Remove target. - (dist): Don't link $(srcdir)/permute-index. - (clean): Don't remove index.texi. - - * permute-index, index.perm: Remove. - * index.texi: Rename from index.unperm. - -2003-10-22 Luc Teirlinck - - * tips.texi (Documentation Tips): Document new behavior for face - and variable hyperlinks in Help mode. - -2003-10-21 Luc Teirlinck - - * objects.texi (Integer Type): Update for extra bit of integer range. - (Character Type): Ditto. - -2003-10-16 Eli Zaretskii - - * numbers.texi (Integer Basics): Add index entries for reading - numbers in hex, octal, and binary. - -2003-10-16 Lute Kamstra - - * modes.texi (Mode Line Format): Mention force-mode-line-update's - argument. - -2003-10-13 Luc Teirlinck - - * windows.texi (Choosing Window): Fix typo. - * edebug.texi (Edebug Execution Modes): Fix typo. - -2003-10-13 Richard M. Stallman - - * windows.texi (Basic Windows): A window has fringe settings, - display margins and scroll-bar settings. - (Splitting Windows): Doc split-window return value. - Clean up one-window-p. - (Selecting Windows): Fix typo. - (Cyclic Window Ordering): Explain frame as ALL-FRAMES in next-window. - (Buffers and Windows): In set-window-buffer, explain effect - on fringe settings and scroll bar settings. - (Displaying Buffers): In pop-to-buffer, explain nil as buffer arg. - (Choosing Window): Use defopt for pop-up-frame-function. - For special-display-buffer-names, explain same-window and same-frame. - Clarify window-dedicated-p return value. - (Textual Scrolling): scroll-up and scroll-down can get an error. - (Horizontal Scrolling): Clarify auto-hscroll-mode. - Clarify set-window-hscroll. - (Size of Window): Don't mention tool bar in window-height. - (Coordinates and Windows): Explain what coordinates-in-window-p - returns for fringes and display margins. - (Window Configurations): Explain saving fringes, etc. - - * tips.texi (Library Headers): Clean up Documentation. - - * syntax.texi (Parsing Expressions): Clean up forward-comment - and parse-sexp-lookup-properties. - - * sequences.texi (Sequence Functions): sequencep accepts bool-vectors. - - * os.texi (System Environment): Clean up text for load-average errors. - - * modes.texi (Hooks): Don't explain local hook details at front. - Clarify run-hooks and run-hook-with-args a little. - Clean up add-hook and remove-hook. - - * edebug.texi (Edebug Execution Modes): Clarify t. - Document edebug-sit-for-seconds. - (Coverage Testing): Document C-x X = and =. - (Instrumenting Macro Calls): Fix typo. - (Specification List): Don't index the specification keywords. - -2003-10-10 Kim F. Storm - - * processes.texi (Network): Introduce make-network-process. - -2003-10-09 Luc Teirlinck - - * tips.texi (Library Headers): Fix typo. - -2003-10-07 Juri Linkov - - * modes.texi (Imenu): Mention imenu-create-index-function's - default value. Explain submenus better. - -2003-10-07 Lute Kamstra - - * modes.texi (Faces for Font Lock): Fix typo. - (Hooks): Explain how buffer-local hook variables can refer to - global hook variables. - Various minor clarifications. - -2003-10-06 Lute Kamstra - - * tips.texi (Coding Conventions): Mention naming conventions for - hooks. - -2003-10-05 Luc Teirlinck - - * loading.texi (Library Search): Correct default value of - load-suffixes. - (Named Features): Fix typo. - -2003-10-05 Richard M. Stallman - - * loading.texi (Named Features): In `provide', - say how to test for subfeatures. - (Unloading): In unload-feature, use new var name - unload-feature-special-hooks. - -2003-10-03 Lute Kamstra - - * modes.texi (Major Mode Conventions): Mention third way to set up - Imenu. - (Imenu): A number of small fixes. - Delete documentation of internal variable imenu--index-alist. - Document the return value format of imenu-create-index-function - functions. - -2003-09-30 Richard M. Stallman - - * processes.texi (Network): Say what stopped datagram connections do. - - * lists.texi (Association Lists): Clarify `assq-delete-all'. - - * display.texi (Overlay Properties): Clarify `evaporate' property. - -2003-09-29 Lute Kamstra - - * modes.texi (Mode Line Data): Explain when symbols in mode-line - constructs should be marked as risky. - Change cons cell into proper list. - (Mode Line Variables): Change cons cell into proper list. - -2003-09-26 Lute Kamstra - - * modes.texi (Mode Line Data): Document the :propertize construct. - (Mode Line Variables): Reorder the descriptions of the variables - to match their order in the default mode-line-format. - Describe the new variables mode-line-position and mode-line-modes. - Update the default values of mode-line-frame-identification, - minor-mode-alist, and default-mode-line-format. - (Properties in Mode): Mention the :propertize construct. - -2003-09-26 Richard M. Stallman - - * buffers.texi, commands.texi, debugging.texi, eval.texi: - * loading.texi, minibuf.texi, text.texi, variables.texi: - Avoid @strong{Note:}. - -2003-09-26 Richard M. Stallman - - * keymaps.texi (Remapping Commands): Fix typo. - -2003-09-23 Luc Teirlinck - - * processes.texi (Low-Level Network): Fix typo. - -2003-09-23 Kim F. Storm - - * processes.texi (Network, Network Servers): Fix typos. - (Low-Level Network): Add timeout value for :server keyword. - Add new option keywords to make-network-process. - Add set-network-process-options. - Explain how to test availability of network options. - -2003-09-19 Richard M. Stallman - - * text.texi (Motion by Indent): Arg to - backward-to-indentation and forward-to-indentation is optional. - - * strings.texi (Creating Strings): Add substring-no-properties. - - * processes.texi - (Process Information): Add list-processes arg QUERY-ONLY. - Delete process-contact from here. - Add new status values for process-status. - Add process-get, process-put, process-plist, set-process-plist. - (Synchronous Processes): Add call-process-shell-command. - (Signals to Processes): signal-process allows process objects. - (Network): Complete rewrite. - (Network Servers, Datagrams, Low-Level Network): New nodes. - - * positions.texi (Word Motion): forward-word, backward-word - arg is optional. Reword. - - * abbrevs.texi (Defining Abbrevs): Index no-self-insert. - - * variables.texi (Creating Buffer-Local): - Delete duplicate definition of buffer-local-value. - (File Local Variables): Explain about discarding text props. - -2003-09-11 Richard M. Stallman - - * minibuf.texi (Intro to Minibuffers): Explain that the minibuffer - changes variables that record input events. - (Minibuffer Misc): Add minibuffer-selected-window. - - * lists.texi (Building Lists): Add copy-tree. - - * display.texi (Fontsets): Add char-displayable-p. - (Scroll Bars): New node. - -2003-09-08 Lute Kamstra - - * modes.texi (%-Constructs): Document new `%i' and `%I' - constructs. - -2003-09-03 Peter Runestig - - * makefile.w32-in: New file. - -2003-08-29 Richard M. Stallman - - * display.texi (Overlay Properties): Clarify how priorities - affect use of the properties. - -2003-08-19 Luc Teirlinck - - * customize.texi (Type Keywords): Correct the description of - `:help-echo' in the case where `motion-doc' is a function. - -2003-08-14 John Paul Wallington - - * modes.texi (Emulating Mode Line): Subsection, not section. - -2003-08-13 Richard M. Stallman - - * elisp.texi (Top): Update subnode lists in menu. - - * text.texi (Insertion): Add insert-buffer-substring-no-properties. - (Kill Functions): kill-region has new arg yank-handler. - (Yanking): New node. - (Yank Commands): Add yank-undo-function. - (Low-Level Kill Ring): - kill-new and kill-append have new arg yank-handler. - (Changing Properties): Add remove-list-of-text-properties. - (Atomic Changes): New node. - - * symbols.texi (Other Plists): Add lax-plist-get, lax-plist-put. - - * streams.texi (Output Variables): Add eval-expression-print-length - and eval-expression-print-level. - - * os.texi (Time Conversion): For encode-time, explain limits on year. - - * objects.texi (Character Type): Define anchor "modifier bits". - - * modes.texi (Emulating Mode Line): New node. - (Search-based Fontification): Font Lock uses font-lock-face property. - (Other Font Lock Variables): Likewise. - - * keymaps.texi (Format of Keymaps): Keymaps contain char tables, - not vectors. - (Active Keymaps): Add emulation-mode-map-alists. - (Functions for Key Lookup): key-binding has new arg no-remap. - (Remapping Commands): New node. - (Scanning Keymaps): where-is-internal has new arg no-remap. - (Tool Bar): Add tool-bar-local-item-from-menu. - Clarify when to use tool-bar-add-item-from-menu. - - * commands.texi (Interactive Call): commandp has new arg. - (Command Loop Info): Add this-original-command. - -2003-08-06 John Paul Wallington - - * compile.texi (Compiler Errors): Say `@end defmac' after `@defmac'. - - * display.texi (Warning Basics): Fix typo. - (Fringes): Add closing curly bracket and fix typo. - - * elisp.texi (Top): Fix typo. - -2003-08-05 Richard M. Stallman - - * elisp.texi: Update lists of subnodes. - - * windows.texi (Buffers and Windows): set-window-buffer has new arg. - - * variables.texi (Local Variables): Use lc for example variable names. - - * tips.texi (Library Headers): Explain where to put -*-. - - * strings.texi (Creating Strings): Fix xref for vconcat. - - * sequences.texi (Vector Functions): - vconcat no longer allows integer args. - - * minibuf.texi (Reading File Names): read-file-name has new - arg PREDICATE. New function read-directory-name. - - * macros.texi (Defining Macros): Give definition of `declare'. - (Indenting Macros): New node. - - * frames.texi (Parameter Access): Add modify-all-frames-parameters. - (Window Frame Parameters): Make separate table of parameters - that are coupled with specific face attributes. - (Deleting Frames): delete-frame-hooks renamed to - delete-frame-functions. - - * files.texi (Magic File Names): Add file-remote-p. - Clarify file-local-copy. - - * edebug.texi (Instrumenting Macro Calls): Don't define `declare' - here; instead xref Defining Macros. - - * display.texi (Warnings): New node, and subnodes. - (Fringes): New node. - - * debugging.texi (Test Coverage): New node. - - * compile.texi (Compiler Errors): Explain with-no-warnings - and other ways to suppress warnings. - - * commands.texi (Interactive Call): Minor clarification. - - * buffers.texi (Buffer File Name): set-visited-file-name - renames the buffer too. - - * abbrevs.texi (Abbrev Tables): Add copy-abbrev-table. - -2003-07-24 Markus Rost - - * abbrevs.texi (Abbrev Expansion): Use \s syntax in example. - -2003-07-22 Markus Rost - - * internals.texi (Garbage Collection): Fix previous change. - -2003-07-22 Richard M. Stallman - - * files.texi (Truenames): Add LIMIT arg to file-chase-links. - - * display.texi (Width): Use \s syntax in example. - (Font Selection): Add face-font-rescale-alist. - - * modes.texi (Imenu): Add xref to Emacs Manual node on Imenu. - Remove spurious indent in example. - - * lists.texi (Building Lists): Add number-sequence. - - * internals.texi (Garbage Collection): Add gcs-done, gc-elapsed. - - * functions.texi (Function Documentation): Explain how to - show calling convention explicitly in the doc string. - - * windows.texi (Selecting Windows): save-selected-window saves - selected window of each frame. - (Window Configurations): Minor change. - - * syntax.texi (Syntax Table Functions): Use \s syntax in examples. - - * streams.texi (Output Variables): Add print-continuous-numbering - and print-number-table. - - * processes.texi (Decoding Output): New node. - - * os.texi (Time Conversion): decode-time arg is optional. - - * objects.texi (Character Type): Don't use space as example for \. - Make list of char names and \-sequences correspond. - Explain that \s is not used in strings. `\ ' needs space after. - - * nonascii.texi (Converting Representations): Add string-to-multibyte. - (Translation of Characters): Add translation-table-for-input. - (Default Coding Systems): Add auto-coding-functions. - (Explicit Encoding): Add decode-coding-inserted-region. - (Locales): Add locale-info. - - * minibuf.texi (Basic Completion): Describe test-completion. - Collections can be lists of strings. - Clean up lazy-completion-table. - (Programmed Completion): Mention test-completion. - Clarify why lambda expressions are not accepted. - (Minibuffer Misc): Describe minibufferp. - -2003-07-14 Richard M. Stallman - - * buffers.texi (Killing Buffers): kill-buffer-hook is perm local. - - * windows.texi (Selecting Windows): New arg to select-window. - (Selecting Windows): Add with-selected-window. - (Size of Window): Add window-inside-edges, etc. - - * internals.texi (Garbage Collection): Add post-gc-hook. - - * processes.texi (Subprocess Creation): Add exec-suffixes. - - * keymaps.texi (Functions for Key Lookup): Add current-active-maps. - (Scanning Keymaps): Add map-keymaps. - (Defining Menus): Add keymap-prompt. - - * numbers.texi (Integer Basics): Add most-positive-fixnum, - most-negative-fixnum. - - * compile.texi (Byte Compilation): Explain no-byte-compile. - (Compiler Errors): New node. - - * os.texi (User Identification): user-uid, user-real-uid - can return float. - - * modes.texi (Major Mode Conventions): Explain about run-mode-hooks - and about derived modes. - (Minor Modes): Add minor-mode-list. - (Defining Minor Modes): Keyword args for define-minor-mode. - (Search-based Fontification): Explain managing other properties. - (Other Font Lock Variables): Add font-lock-extra-managed-props. - (Faces for Font Lock): Add font-lock-preprocessor-face. - (Hooks): Add run-mode-hooks and delay-mode-hooks. - - * variables.texi (Creating Buffer-Local): Add buffer-local-value. - (Variable Aliases): Clarify defvaralias. - - * loading.texi (Library Search): Add load-suffixes. - - * minibuf.texi (Basic Completion): Add lazy-completion-table. - (Programmed Completion): Add dynamic-completion-table. - - * files.texi (Changing Files): copy-file allows dir as NEWNAME. - (Magic File Names): Specify precedence order of handlers. - - * commands.texi (Command Overview): Emacs server runs pre-command-hook - and post-command-hook. - (Waiting): New calling convention for sit-for. - - * text.texi (Special Properties): local-map and keymap properties - apply based on their stickiness. - -2003-07-07 Richard M. Stallman - - * modes.texi (Minor Mode Conventions): Specify only some kinds - of list values as args to minor modes. - - * files.texi (File Name Expansion): Warn about iterative use - of substitute-in-file-name. - - * advice.texi (Activation of Advice): Clean up previous change. - -2003-07-06 Markus Rost - - * advice.texi (Activation of Advice): Note that ad-start-advice is - turned on by default. - -2003-06-30 Richard M. Stallman - - * text.texi (Buffer Contents): Document current-word. - (Change Hooks): Not called for *Messages*. - - * functions.texi (Defining Functions): Explain about redefining - primitives. - (Function Safety): Rename. Minor changes. - Comment out the detailed criteria for what is safe. - -2003-06-22 Andreas Schwab - - * objects.texi (Symbol Type): Fix description of examples. - -2003-06-16 Andreas Schwab - - * hash.texi (Creating Hash): Fix description of :weakness. - -2003-06-13 Kai Großjohann - - * files.texi (Changing Files): copy-file copies file modes, too. - -2003-05-28 Richard M. Stallman - - * strings.texi (Creating Strings): Clarify split-string. - -2003-05-22 Stephen J. Turnbull - - * strings.texi (Creating Strings): Update split-string specification - and examples. - -2003-05-19 Richard M. Stallman - - * elisp.texi: Correct invariant section names. - -2003-04-20 Richard M. Stallman - - * os.texi (Timers): Explain about timers and quitting. - -2003-04-19 Richard M. Stallman - - * internals.texi (Writing Emacs Primitives): Strings are - no longer special for GCPROs. Mention GCPRO5, GCPRO6. - Explain GCPRO convention for varargs function args. - -2003-04-16 Richard M. Stallman - - * minibuf.texi (Minibuffer Misc): Document fn minibuffer-message. - -2003-04-08 Richard M. Stallman - - * files.texi (Kinds of Files): Correct return value of file-symlink-p. - -2003-02-13 Kim F. Storm - - * objects.texi (Character Type): New \s escape for space. - -2003-01-31 Joe Buehler - - * os.texi (System Environment): Add cygwin system-type. - -2003-01-25 Richard M. Stallman - - * keymaps.texi: Document that a symbol can act as a keymap. - -2003-01-13 Richard M. Stallman - - * text.texi (Changing Properties): Say string indices are origin-0. - - * positions.texi (Screen Lines) : - Correct order of elts in return value. - - * keymaps.texi (Changing Key Bindings) : Mention - how to define a default binding. - -2002-12-07 Markus Rost - - * loading.texi (Unloading): Fix recent change for load-history. - - * customize.texi (Simple Types): Clarify description of custom - type 'number. Describe new custom type 'float. - -2002-12-04 Markus Rost - - * variables.texi (File Local Variables): Fix typo. - -2002-10-23 Kai Großjohann - - From Michael Albinus . - - * README: Target for Info file is `make info'. - - * files.texi (File Name Components): Fix typos in - `file-name-sans-extension'. - (Magic File Names): Complete list of operations for magic file - name handlers. - -2002-09-16 Jonathan Yavner - - * variables.texi (File Local Variables): New function - risky-local-variable-p. - -2002-09-15 Jonathan Yavner - - * functions.texi (Function safety): New node about unsafep. - -2002-08-05 Per Abrahamsen - - * customize.texi (Splicing into Lists): Fix example. - Reported by Fabrice Bauzac . - -2002-06-17 Juanma Barranquero - - * frames.texi (Display Feature Testing): Fix typo. - -2002-06-12 Andreas Schwab - - * frames.texi (Initial Parameters, Resources): Fix references to - the Emacs manual. - -2002-05-13 Kim F. Storm - - * variables.texi (Intro to Buffer-Local): Updated warning and - example relating to changing buffer inside let. - -2002-03-10 Jan Djärv - - * os.texi (Session Management): New node about X Session management. - -2002-01-18 Eli Zaretskii - - * elisp.texi (VERSION): Set to 2.9. Update the version of Emacs - to which the manual corresponds, and the copyright years. - - * Makefile.in (VERSION): Set to 2.9. - -2001-11-29 Eli Zaretskii - - * elisp.texi: Change the category in @dircategory to "Emacs", to - make it consistent with info/dir. - -2001-11-25 Miles Bader - - * text.texi (Fields): Describe new `limit' arg in - field-beginning/field-end. - -2001-11-17 Eli Zaretskii - - * permute-index: Don't depend on csh-specific features. - Replace the interpreter name with /bin/sh. - - * two-volume-cross-refs.txt: New file. - * two.el: New file. - * spellfile: New file. - -2001-11-16 Eli Zaretskii - - * permute-index: New file. - - * vol1.texi, vol2.texi: Renamed from elisp-vol1.texi and - elisp-vol2.texi, respectively, to avoid file-name clashes in DOS - 8+3 restricted namespace. - - * Makefile.in (infodir): Define relative to $(srcdir). - ($(infodir)/elisp): Don't chdir into $(srcdir), but add it to the - include directories list via -I switch to makeinfo. - (index.texi): Use cp if both hard and symbolic links fail. - -2001-11-10 Eli Zaretskii - - * Makefile.in (distclean): Add. - - The following changes make ELisp manual part of the Emacs - distribution: - - * Makefile.in: Add Copyright notice. - (prefix): Remove. - (infodir): Change value to "../info". - (VPATH): New variable. - (MAKE): Don't define. - (texmacrodir): Don't define. - (texinputdir): Append the existing value of TEXINPUTS. - ($(infodir)/elisp): Instead of just "elisp". Reformat the - command to be compatible with man/Makefile.in, and to put the - output into ../info. - (info): Add target. - (installall): Target removed. - -2001-10-31 Pavel Janík - - * tips.texi (Coding Conventions): Fix typo. - -2001-10-23 Gerd Moellmann - - * Makefile.in (srcs): Add gpl.texi and doclicense.texi. - -2001-10-22 Eli Zaretskii - - * files.texi (File Name Components): Update the description of - file-name-sans-extension and file-name-extension, as they now - ignore leading dots. - -2001-10-20 Gerd Moellmann - - * (Version 21.1 released.) - -2001-10-19 Miles Bader - - * positions.texi (Text Lines): Describe behavior of - `beginning-of-line'/`end-of-line' in the presence of field properties. - -2001-10-17 Gerd Moellmann - - * Makefile.in (VERSION): Set to 2.8. - (manual): Use `manual-21'. - - * elisp.texi (VERSION): Add and use it where the version - number was used. Set it to 2.8. - - * intro.texi: Likewise. - -2001-10-13 Eli Zaretskii - - * files.texi (File Name Completion): Document the significance of - a trailing slash in elements of completion-ignored-extensions. - -2001-10-06 Miles Bader - - * variables.texi (Variable Aliases): It's `@defmac', not `@defmacro'. - -2001-10-04 Gerd Moellmann - - * variables.texi (Variable Aliases): New node. - -2001-10-04 Gerd Moellmann - - * Branch for 21.1. - -2001-10-02 Miles Bader - - * minibuf.texi (Minibuffer Misc): Add entries for - `minibuffer-contents', `minibuffer-contents-no-properties', and - `delete-minibuffer-contents'. - Correct description for `minibuffer-prompt-end'. - - * text.texi (Property Search): Correct descriptions of - `next-char-property-change' and `previous-char-property-change'. - Add entries for `next-single-char-property-change' and - `previous-single-char-property-change'. - Make operand names a bit more consistent. - -2001-09-30 Eli Zaretskii - - * frames.texi (Finding All Frames): Document that next-frame and - previous-frame are local to current terminal. - -2001-09-26 Eli Zaretskii - - * keymaps.texi (Creating Keymaps): Fix the description of the - result of make-keymap. - -2001-09-23 Eli Zaretskii - - * display.texi (Font Lookup, Attribute Functions) - (Image Descriptors): Add cross-references to the definition of - selected frame. - - * buffers.texi (The Buffer List): Add cross-references to the - definition of selected frame. - - * frames.texi (Input Focus): Clarify which frame is _the_ selected - frame at any given time. - (Multiple Displays, Size and Position): Add a cross-reference to - the definition of the selected frame. - -2001-09-08 Eli Zaretskii - - * strings.texi (String Conversion) : Document - that a float is returned for integers that are too large. - - * frames.texi (Mouse Position): Document mouse-position-function. - (Display Feature Testing): Document display-images-p. - (Window Frame Parameters): Document the cursor-type variable. - - * numbers.texi (Integer Basics): Document CL style read syntax for - integers in bases other than 10. - - * positions.texi (List Motion): - Document open-paren-in-column-0-is-defun-start. - - * lists.texi (Sets And Lists): Document member-ignore-case. - - * internals.texi (Garbage Collection): Document the used and free - strings report. - (Memory Usage): Document strings-consed. - - * os.texi (Time of Day): Document float-time. - (Recording Input): Document that clear-this-command-keys clears - the vector to be returned by recent-keys. - - * keymaps.texi (Scanning Keymaps) : The - argument keymap can be a list. - - * nonascii.texi (User-Chosen Coding Systems) - : Document the new argument - accept-default-p and the variable - select-safe-coding-system-accept-default-p. Tell what happens if - buffer-file-coding-system is undecided. - (Default Coding Systems): Document auto-coding-regexp-alist. - - * display.texi (The Echo Area) : Document - message-truncate-lines. - (Glyphs): Document that the glyph table is unused on windowed - displays. - - * help.texi (Describing Characters) : - Document the new argument no-angles. - (Accessing Documentation) : Document that - a non-string property is evaluated. - : Document that the function-documentation property - is looked for. - - * windows.texi (Selecting Windows): Document some-window. - - * text.texi (MD5 Checksum): New node, documents the md5 primitive. - - * hooks.texi (Standard Hooks): Add kbd-macro-termination-hook and - apropos-mode-hook. - - * commands.texi (Using Interactive): Document interactive-form. - (Keyboard Macros): Document kbd-macro-termination-hook. - (Command Loop Info): Document that clear-this-command-keys clears - the vector to be returned by recent-keys. - -2001-09-04 Werner LEMBERG - - * Makefile.in (srcdir, texinputdir): New variables. - (srcs, index.texi, install): Use $(srcdir). - (.PHONY): Remove elisp.dvi. - (elisp): Use -I switch for makeinfo. - (elisp.dvi): Use $(srcdir) and $(texinputdir). - (installall, dist): Use $(srcdir). - Fix path to texinfo.tex. - (maintainer-clean): Add elisp.dvi and elisp.oaux. - -2001-08-30 Gerd Moellmann - - * display.texi (Conditional Display): Adjust to API change. - - * configure: New file. - -2001-07-30 Gerd Moellmann - - * commands.texi (Repeat Events): Add description of - double-click-fuzz. - -2001-05-08 Stefan Monnier - - * syntax.texi (Syntax Class Table): Add the missing designator for - comment and string fences. - (Syntax Properties): Add a xref to syntax table internals. - (Syntax Table Internals): Document string-to-syntax. - -2001-05-07 Gerd Moellmann - - * Makefile.in (install): Use install-info command line options - like in Emacs' Makefile.in. - -2000-12-09 Miles Bader - - * windows.texi (Window Start): Update documentation for - `pos-visible-in-window-p'. - -2000-11-12 Stefan Monnier - - * lists.texi (Building Lists): Add footnote to explain how to add - to the end of a list. - -2000-10-25 Gerd Moellmann - - * files.texi (Visiting Functions): Typos. - -2000-10-25 Kenichi Handa - - * files.texi (Visiting Functions): Return value of - find-file-noselect may be a list of buffers if wildcards are used. - -2000-10-24 Miles Bader - - * display.texi (Defining Faces): Document `graphic' display type - in face specs. - -2000-10-18 Kai Großjohann - - * hooks.texi (Standard Hooks): Replace obsolete - `after-make-frame-hook' with `after-make-frame-functions'. - - * frames.texi (Creating Frames): Ditto. - - * variables.texi (Future Local Variables): Ditto. - -2000-10-16 Gerd Moellmann - - * display.texi (Other Image Types): Add description of :foreground - and :background properties of mono PBM images. - -2000-08-17 Werner LEMBERG - - * .cvsignore: New file. - -2000-01-05 Gerd Moellmann - - * tindex.pl: New script. - -1999-12-03 Dave Love - - * Makefile.in (MAKEINFO): New parameter. - -1999-09-17 Richard Stallman - - * Makefile.in (srcs): Add hash.texi. - (VERSION): Update to 20.6. - -1999-09-13 Richard Stallman - - * Makefile.in (index.texi): If cannot make a symlink, make a hard link. - -1998-08-29 Karl Heuer - - * configure.in: New file. - * Makefile.in: Renamed from Makefile. - (prefix, infodir): Use value obtained from configure. - (emacslibdir): Obsolete variable deleted. - (dist): Distribute configure.in, configure, Makefile.in. - -1998-06-12 Richard Stallman - - * Makefile (INSTALL_INFO): New variable. - (install): Run install-info. - -1998-05-09 Richard Stallman - - * Makefile (elisp.dvi): Add missing backslash. - -1998-05-02 Richard Stallman - - * Makefile (elisp.dvi): Don't depend on texindex or on elisp.tps. - Run texindex without `./'. Always run texindex on elisp.tp. - (elisp.tps): Target deleted. - -1998-04-05 Richard Stallman - - * Makefile (srcs): Add nonascii.texi and customize.texi. - (dist): Start by deleting `temp'. - -1998-02-17 Richard Stallman - - * Makefile (makeinfo, texindex): Targets deleted. - (makeinfo.o, texindex.o): Targets deleted. - (clean, dist): Don't do anything with them or with getopt*. - -1998-01-30 Richard Stallman - - * Makefile (SHELL): Defined. - -1998-01-27 Richard Stallman - - * Makefile (elisp.tps): New target. - (elisp.dvi): Depend on elisp.tps. - -1996-04-03 Karl Heuer - - * README: Update phone number. - - * Makefile (elisp): Make this be the default target. - Depend on makeinfo.c instead of makeinfo. - (install): Don't depend on elisp.dvi, since we don't install that. - Use mkinstalldirs. - (dist): Add mkinstalldirs. - -1995-06-19 Richard Stallman - - * Makefile (VERSION): Update version number. - (maintainer-clean): Rename from realclean. - -1995-06-07 Karl Heuer - - * Makefile (realclean): New target. - (elisp): Remove any old elisp-* files first. - -1993-11-23 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) - - * Makefile (VERSION): New variable. - (dist): Make packaged directory name `elisp-manual-19-$(VERSION)'. - Compressed file suffix should be `.gz', not `.z'. - -1993-11-22 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (elisp): Depend on makeinfo. - -1993-11-19 Noah Friedman (friedman@gnu.ai.mit.edu) - - * Makefile (srcs): Add anti.texi. - -1993-05-28 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (infodir, prefix): New vars. - (install): Use infodir. - (emacsinfodir): Delete. - -1993-05-27 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (srcs): Add calendar.texi. - - * Makefile (dist): Copy texindex.c and makeinfo.c. - Limit elisp-* files to those with one or two digits. - -1993-05-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (dist): Change to use Gzip instead of compress. - -1993-04-23 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * loading.texi (Unloading): define-function changed back to - defalias. It may not stay this way, but at least it's - consistent with the known-good version of the code patch. - -1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) - - * modes.texi (Hooks): Document new optional arg of add-hook. - -1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * variables.texi: Document nil initial value of buffer-local variables. - - * tips.texi: Add new section on standard library headers. - -1993-02-27 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (srcs): Add frame.texi to the list of sources. - -1993-02-23 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (dist): Don't bother excluding autosave files; they'll - never make it into the temp directory anyway, and the hash marks - in the name are problematic for make and the Bourne shell. - (srcs): - -1993-02-12 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (dist): Don't include backup files or autosave files in - the distribution tar file. - -1991-11-26 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (srcs): Add index.perm. - (elisp.dvi): Remove erroneous shell comment. - Expect output of permute-index in permuted.fns. - Save old elisp.aux in elisp.oaux. - (clean): Add index.texi to be deleted. - -1990-08-11 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - - * Makefile (elisp.dvi, index.texi): Use shell if instead of ifdef. - -1990-06-26 David Lawrence (tale@geech) - - * files.texi: Noted that completion-ignored-extensions is ignored - when making *Completions*. - -1990-06-08 Jay Fenlason (hack@ai.mit.edu) - - * Makefile make dist now depends on elisp.dvi, since it tries - to include it in the dist file. - -1990-03-28 Jim Kingdon (kingdon@mole.ai.mit.edu) - - * functions.texinfo (Mapping Functions): Add missing quote. - -1989-06-19 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - - * texinfo.tex (frenchspacing): Use decimal codes for char to be set. - (defunargs): Turn off \hyphenchar of \sl font temporarily. - -1989-05-10 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * @result{}, @expansion{}, @print{}, @quiv{}, @point{}, - and @error{} are the terms now being used. The files in the - directory have been changed to reflect this. - - * All instances of @indentedresultt{} have been changed to - ` @result{}', using 5 spaces at the beginning of the line. - -1989-04-24 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * @result{}, @expandsto{}, @prints{}, @quiv{}, @error{}, and the - experimental @indentedresult{}, @indentedexpandsto{} are part of - the texinfo.tex in this directory. These TeX macros are not - stable yet. - -1989-04-17 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * texinfo.tex: Temporarily added - \let\result=\dblarrow - \def\error{{\it ERROR} \longdblarrow} - We need to do this better soon. - -1989-04-11 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * Applied Karl Berry's patches to *.texinfo files, but not to - texinfo.tex; those diffs are in `berry-texinfo-tex-diffs'. (Karl's - new title page format is also not applied, since it requires - texinfo.tex changes.) - - * Cleaned up `Makefile' and defined the `emacslibdir' directory - for the Project GNU development environment. - -;; Local Variables: -;; coding: utf-8 -;; End: - - Copyright (C) 1998-2012 Free Software Foundation, Inc. - - This file is part of GNU Emacs. - - GNU Emacs is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - GNU Emacs is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNU Emacs. If not, see . diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in deleted file mode 100644 index efd5e39a0eb..00000000000 --- a/doc/lispref/Makefile.in +++ /dev/null @@ -1,164 +0,0 @@ -# Makefile for the GNU Emacs Lisp Reference Manual. - -# Copyright (C) 1990-1996, 1998-2012 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -SHELL = /bin/sh - -# Standard configure variables. -srcdir = @srcdir@ - -version=@version@ - -infodir = $(srcdir)/../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc -# Directory with emacsver.texi. -emacsdir = $(srcdir)/../emacs - -MAKEINFO = @MAKEINFO@ -MAKEINFO_OPTS = --force --enable-encoding -I $(emacsdir) -I $(srcdir) -TEXI2DVI = texi2dvi -TEXI2PDF = texi2pdf -DVIPS = dvips - -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" - -# List of all the texinfo files in the manual: - -srcs = \ - $(srcdir)/elisp.texi \ - $(emacsdir)/emacsver.texi \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/advice.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/back.texi \ - $(srcdir)/backups.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/compile.texi \ - $(srcdir)/control.texi \ - $(srcdir)/customize.texi \ - $(srcdir)/debugging.texi \ - $(srcdir)/display.texi \ - $(srcdir)/edebug.texi \ - $(srcdir)/errors.texi \ - $(srcdir)/eval.texi \ - $(srcdir)/files.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/functions.texi \ - $(srcdir)/hash.texi \ - $(srcdir)/help.texi \ - $(srcdir)/hooks.texi \ - $(srcdir)/internals.texi \ - $(srcdir)/intro.texi \ - $(srcdir)/keymaps.texi \ - $(srcdir)/lists.texi \ - $(srcdir)/loading.texi \ - $(srcdir)/macros.texi \ - $(srcdir)/maps.texi \ - $(srcdir)/markers.texi \ - $(srcdir)/minibuf.texi \ - $(srcdir)/modes.texi \ - $(srcdir)/nonascii.texi \ - $(srcdir)/numbers.texi \ - $(srcdir)/objects.texi \ - $(srcdir)/os.texi \ - $(srcdir)/package.texi \ - $(srcdir)/positions.texi \ - $(srcdir)/processes.texi \ - $(srcdir)/searching.texi \ - $(srcdir)/sequences.texi \ - $(srcdir)/streams.texi \ - $(srcdir)/strings.texi \ - $(srcdir)/symbols.texi \ - $(srcdir)/syntax.texi \ - $(srcdir)/text.texi \ - $(srcdir)/tips.texi \ - $(srcdir)/variables.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/index.texi \ - $(srcdir)/gpl.texi \ - $(srcdir)/doclicense.texi - -mkinfodir = @test -d ${infodir} || mkdir ${infodir} || test -d ${infodir} - -.PHONY: info dvi pdf ps - -info: $(infodir)/elisp -dvi: elisp.dvi -html: elisp.html -pdf: elisp.pdf -ps: elisp.ps - -## Note: "<" is not portable in ordinary make rules. -$(infodir)/elisp: $(srcs) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) -o $@ $(srcdir)/elisp.texi - -elisp.dvi: $(srcs) - $(ENVADD) $(TEXI2DVI) $(srcdir)/elisp.texi - -elisp.html: $(srcs) - $(MAKEINFO) $(MAKEINFO_OPTS) --html -o $@ $(srcdir)/elisp.texi - -elisp.ps: elisp.dvi - $(DVIPS) -o $@ elisp.dvi - -elisp.pdf: $(srcs) - $(ENVADD) $(TEXI2PDF) $(srcdir)/elisp.texi - -.PHONY: mostlyclean clean distclean maintainer-clean infoclean - -## [12] stuff is from two-volume.make. -mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs - rm -f elisp[12]* vol[12].tmp - -clean: mostlyclean - rm -f elisp.dvi elisp.pdf elisp.ps - rm -f vol[12].dvi vol[12].pdf vol[12].ps - rm -rf elisp.html - rm -f emacs-lispref-${version}.tar* - -distclean: clean - -infoclean: - -cd $(infodir) && rm -f elisp elisp-[1-9] elisp-[1-9][0-9] - -maintainer-clean: distclean infoclean - -.PHONY: dist - -## Note this excludes the two-volume stuff. -dist: - rm -rf emacs-lispref-${version} - mkdir emacs-lispref-${version} - cp ${srcdir}/*.texi ${texinfodir}/texinfo.tex \ - $(emacsdir)/emacsver.texi ${srcdir}/ChangeLog* \ - ${srcdir}/README emacs-lispref-${version}/ - sed -e 's/@sr[c]dir@/./' -e 's/^\(texinfodir *=\).*/\1 ./' \ - -e 's/^\(emacsdir *=\).*/\1 ./' \ - -e 's/^\(infodir *=\).*/\1 ./' -e 's/^\(clean:.*\)/\1 infoclean/' \ - -e "s/@ver[s]ion@/${version}/" \ - ${srcdir}/Makefile.in > emacs-lispref-${version}/Makefile - tar -cf emacs-lispref-${version}.tar emacs-lispref-${version} - rm -rf emacs-lispref-${version} - -### Makefile ends here diff --git a/doc/lispref/README b/doc/lispref/README deleted file mode 100644 index 0230f4718c8..00000000000 --- a/doc/lispref/README +++ /dev/null @@ -1,48 +0,0 @@ -Copyright (C) 2001-2012 Free Software Foundation, Inc. -*- outline -*- -See the end of the file for license conditions. - - -README for the Emacs Lisp Reference Manual. - -* This directory contains the texinfo source files for the Emacs Lisp -Reference Manual. - -* Report bugs in the Lisp Manual (or in Emacs) using M-x report-emacs-bug. -To ask questions, use the help-gnu-emacs mailing list. - -* The Emacs Lisp Reference Manual is quite large. It totals around -1100 pages in smallbook format; the info files total around 3.0 megabytes. - -* You can format this manual for Info, for printing hardcopy using TeX, -or for HTML. - -* You can buy nicely printed copies from the Free Software Foundation. -Buying a manual from the Free Software Foundation helps support our GNU -development work. See . -(At time of writing, this manual is out of print.) - -* The master file for formatting this manual for Tex is called `elisp.texi'. -It contains @include commands to include all the chapters that make up -the manual. - -* This distribution contains a Makefile that you can use with GNU Make. - -** To make an Info file, you need to install Texinfo, then run `make info'. - -** Use `make elisp.pdf' or `make elisp.html' to create PDF or HTML versions. - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi deleted file mode 100644 index a64e8a0bd51..00000000000 --- a/doc/lispref/abbrevs.texi +++ /dev/null @@ -1,501 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/abbrevs -@node Abbrevs, Processes, Syntax Tables, Top -@chapter Abbrevs and Abbrev Expansion -@cindex abbrev -@c @cindex abbrev table Redundant with "abbrev". - - An abbreviation or @dfn{abbrev} is a string of characters that may be -expanded to a longer string. The user can insert the abbrev string and -find it replaced automatically with the expansion of the abbrev. This -saves typing. - - The set of abbrevs currently in effect is recorded in an @dfn{abbrev -table}. Each buffer has a local abbrev table, but normally all buffers -in the same major mode share one abbrev table. There is also a global -abbrev table. Normally both are used. - - An abbrev table is represented as an obarray. @xref{Creating -Symbols}, for information about obarrays. Each abbreviation is -represented by a symbol in the obarray. The symbol's name is the -abbreviation; its value is the expansion; its function definition is -the hook function for performing the expansion (@pxref{Defining -Abbrevs}); and its property list cell contains various additional -properties, including the use count and the number of times the -abbreviation has been expanded (@pxref{Abbrev Properties}). - -@cindex system abbrev - Certain abbrevs, called @dfn{system abbrevs}, are defined by a major -mode instead of the user. A system abbrev is identified by its -non-@code{nil} @code{:system} property (@pxref{Abbrev Properties}). -When abbrevs are saved to an abbrev file, system abbrevs are omitted. -@xref{Abbrev Files}. - - Because the symbols used for abbrevs are not interned in the usual -obarray, they will never appear as the result of reading a Lisp -expression; in fact, normally they are never used except by the code -that handles abbrevs. Therefore, it is safe to use them in a -nonstandard way. - - If the minor mode Abbrev mode is enabled, the buffer-local variable -@code{abbrev-mode} is non-@code{nil}, and abbrevs are automatically -expanded in the buffer. For the user-level commands for abbrevs, see -@ref{Abbrevs,, Abbrev Mode, emacs, The GNU Emacs Manual}. - -@menu -* Tables: Abbrev Tables. Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Files: Abbrev Files. Saving abbrevs in files. -* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. -* Abbrev Properties:: How to read and set abbrev properties. - Which properties have which effect. -* Abbrev Table Properties:: How to read and set abbrev table properties. - Which properties have which effect. -@end menu - -@node Abbrev Tables, Defining Abbrevs, Abbrevs, Abbrevs -@section Abbrev Tables - - This section describes how to create and manipulate abbrev tables. - -@defun make-abbrev-table &optional props -This function creates and returns a new, empty abbrev table---an -obarray containing no symbols. It is a vector filled with zeros. -@var{props} is a property list that is applied to the new table -(@pxref{Abbrev Table Properties}). -@end defun - -@defun abbrev-table-p object -This function returns a non-@code{nil} value if @var{object} is an -abbrev table. -@end defun - -@defun clear-abbrev-table abbrev-table -This function undefines all the abbrevs in @var{abbrev-table}, leaving -it empty. -@c Don't see why this needs saying. -@c It always returns @code{nil}. -@end defun - -@defun copy-abbrev-table abbrev-table -This function returns a copy of @var{abbrev-table}---a new abbrev -table containing the same abbrev definitions. It does @emph{not} copy -any property lists; only the names, values, and functions. -@end defun - -@defun define-abbrev-table tabname definitions &optional docstring &rest props -This function defines @var{tabname} (a symbol) as an abbrev table -name, i.e., as a variable whose value is an abbrev table. It defines -abbrevs in the table according to @var{definitions}, a list of -elements of the form @code{(@var{abbrevname} @var{expansion} -[@var{hook}] [@var{props}...])}. These elements are passed as -arguments to @code{define-abbrev}. @c The return value is always @code{nil}. - -The optional string @var{docstring} is the documentation string of the -variable @var{tabname}. The property list @var{props} is applied to -the abbrev table (@pxref{Abbrev Table Properties}). - -If this function is called more than once for the same @var{tabname}, -subsequent calls add the definitions in @var{definitions} to -@var{tabname}, rather than overwriting the entire original contents. -(A subsequent call only overrides abbrevs explicitly redefined or -undefined in @var{definitions}.) -@end defun - -@defvar abbrev-table-name-list -This is a list of symbols whose values are abbrev tables. -@code{define-abbrev-table} adds the new abbrev table name to this list. -@end defvar - -@defun insert-abbrev-table-description name &optional human -This function inserts before point a description of the abbrev table -named @var{name}. The argument @var{name} is a symbol whose value is an -abbrev table. @c The return value is always @code{nil}. - -If @var{human} is non-@code{nil}, the description is human-oriented. -System abbrevs are listed and identified as such. Otherwise the -description is a Lisp expression---a call to @code{define-abbrev-table} -that would define @var{name} as it is currently defined, but without -the system abbrevs. (The mode or package using @var{name} is supposed -to add these to @var{name} separately.) -@end defun - -@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs -@comment node-name, next, previous, up -@section Defining Abbrevs - - @code{define-abbrev} is the low-level basic function for defining an -abbrev in an abbrev table. - - When a major mode defines a system abbrev, it should call -@code{define-abbrev} and specify @code{t} for the @code{:system} -property. Be aware that any saved non-``system'' abbrevs are restored -at startup, i.e. before some major modes are loaded. Therefore, major -modes should not assume that their abbrev tables are empty when they -are first loaded. - -@defun define-abbrev abbrev-table name expansion &optional hook &rest props -This function defines an abbrev named @var{name}, in -@var{abbrev-table}, to expand to @var{expansion} and call @var{hook}, -with properties @var{props} (@pxref{Abbrev Properties}). The return -value is @var{name}. The @code{:system} property in @var{props} is -treated specially here: if it has the value @code{force}, then it will -overwrite an existing definition even for a non-``system'' abbrev of -the same name. - -@var{name} should be a string. The argument @var{expansion} is -normally the desired expansion (a string), or @code{nil} to undefine -the abbrev. If it is anything but a string or @code{nil}, then the -abbreviation ``expands'' solely by running @var{hook}. - -The argument @var{hook} is a function or @code{nil}. If @var{hook} is -non-@code{nil}, then it is called with no arguments after the abbrev is -replaced with @var{expansion}; point is located at the end of -@var{expansion} when @var{hook} is called. - -@cindex @code{no-self-insert} property -If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert} -property is non-@code{nil}, @var{hook} can explicitly control whether -to insert the self-inserting input character that triggered the -expansion. If @var{hook} returns non-@code{nil} in this case, that -inhibits insertion of the character. By contrast, if @var{hook} -returns @code{nil}, @code{expand-abbrev} (or @code{abbrev-insert}) -also returns @code{nil}, as if expansion had not really occurred. - -Normally, @code{define-abbrev} sets the variable -@code{abbrevs-changed} to @code{t}, if it actually changes the abbrev. -This is so that some commands will offer to save the abbrevs. It -does not do this for a system abbrev, since those aren't saved anyway. -@end defun - -@defopt only-global-abbrevs -If this variable is non-@code{nil}, it means that the user plans to use -global abbrevs only. This tells the commands that define mode-specific -abbrevs to define global ones instead. This variable does not alter the -behavior of the functions in this section; it is examined by their -callers. -@end defopt - -@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs -@section Saving Abbrevs in Files - - A file of saved abbrev definitions is actually a file of Lisp code. -The abbrevs are saved in the form of a Lisp program to define the same -abbrev tables with the same contents. Therefore, you can load the file -with @code{load} (@pxref{How Programs Do Loading}). However, the -function @code{quietly-read-abbrev-file} is provided as a more -convenient interface. Emacs automatically calls this function at -startup. - - User-level facilities such as @code{save-some-buffers} can save -abbrevs in a file automatically, under the control of variables -described here. - -@defopt abbrev-file-name -This is the default file name for reading and saving abbrevs. -@end defopt - -@defun quietly-read-abbrev-file &optional filename -This function reads abbrev definitions from a file named @var{filename}, -previously written with @code{write-abbrev-file}. If @var{filename} is -omitted or @code{nil}, the file specified in @code{abbrev-file-name} is -used. - -As the name implies, this function does not display any messages. -@c It returns @code{nil}. -@end defun - -@defopt save-abbrevs -A non-@code{nil} value for @code{save-abbrevs} means that Emacs should -offer to save abbrevs (if any have changed) when files are saved. If -the value is @code{silently}, Emacs saves the abbrevs without asking -the user. @code{abbrev-file-name} specifies the file to save the -abbrevs in. -@end defopt - -@defvar abbrevs-changed -This variable is set non-@code{nil} by defining or altering any -abbrevs (except system abbrevs). This serves as a flag for various -Emacs commands to offer to save your abbrevs. -@end defvar - -@deffn Command write-abbrev-file &optional filename -Save all abbrev definitions (except system abbrevs), for all abbrev -tables listed in @code{abbrev-table-name-list}, in the file -@var{filename}, in the form of a Lisp program that when loaded will -define the same abbrevs. If @var{filename} is @code{nil} or omitted, -@code{abbrev-file-name} is used. This function returns @code{nil}. -@end deffn - -@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs -@comment node-name, next, previous, up -@section Looking Up and Expanding Abbreviations - - Abbrevs are usually expanded by certain interactive commands, -including @code{self-insert-command}. This section describes the -subroutines used in writing such commands, as well as the variables they -use for communication. - -@defun abbrev-symbol abbrev &optional table -This function returns the symbol representing the abbrev named -@var{abbrev}. It returns @code{nil} if that abbrev is not -defined. The optional second argument @var{table} is the abbrev table -in which to look it up. If @var{table} is @code{nil}, this function -tries first the current buffer's local abbrev table, and second the -global abbrev table. -@end defun - -@defun abbrev-expansion abbrev &optional table -This function returns the string that @var{abbrev} would expand into (as -defined by the abbrev tables used for the current buffer). It returns -@code{nil} if @var{abbrev} is not a valid abbrev. -The optional argument @var{table} specifies the abbrev table to use, -as in @code{abbrev-symbol}. -@end defun - -@deffn Command expand-abbrev -This command expands the abbrev before point, if any. If point does not -follow an abbrev, this command does nothing. The command returns the -abbrev symbol if it did expansion, @code{nil} otherwise. - -If the abbrev symbol has a hook function that is a symbol whose -@code{no-self-insert} property is non-@code{nil}, and if the hook -function returns @code{nil} as its value, then @code{expand-abbrev} -returns @code{nil} even though expansion did occur. -@end deffn - -@defun abbrev-insert abbrev &optional name start end -This function inserts the abbrev expansion of @code{abbrev}, replacing -the text between @code{start} and @code{end}. If @code{start} is -omitted, it defaults to point. @code{name}, if non-@code{nil}, should -be the name by which this abbrev was found (a string); it is used to -figure out whether to adjust the capitalization of the expansion. The -function returns @code{abbrev} if the abbrev was successfully -inserted. -@end defun - -@deffn Command abbrev-prefix-mark &optional arg -This command marks the current location of point as the beginning of -an abbrev. The next call to @code{expand-abbrev} will use the text -from here to point (where it is then) as the abbrev to expand, rather -than using the previous word as usual. - -First, this command expands any abbrev before point, unless @var{arg} -is non-@code{nil}. (Interactively, @var{arg} is the prefix argument.) -Then it inserts a hyphen before point, to indicate the start of the -next abbrev to be expanded. The actual expansion removes the hyphen. -@end deffn - -@defopt abbrev-all-caps -When this is set non-@code{nil}, an abbrev entered entirely in upper -case is expanded using all upper case. Otherwise, an abbrev entered -entirely in upper case is expanded by capitalizing each word of the -expansion. -@end defopt - -@defvar abbrev-start-location -The value of this variable is a buffer position (an integer or a marker) -for @code{expand-abbrev} to use as the start of the next abbrev to be -expanded. The value can also be @code{nil}, which means to use the -word before point instead. @code{abbrev-start-location} is set to -@code{nil} each time @code{expand-abbrev} is called. This variable is -also set by @code{abbrev-prefix-mark}. -@end defvar - -@defvar abbrev-start-location-buffer -The value of this variable is the buffer for which -@code{abbrev-start-location} has been set. Trying to expand an abbrev -in any other buffer clears @code{abbrev-start-location}. This variable -is set by @code{abbrev-prefix-mark}. -@end defvar - -@defvar last-abbrev -This is the @code{abbrev-symbol} of the most recent abbrev expanded. This -information is left by @code{expand-abbrev} for the sake of the -@code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding -Abbrevs, emacs, The GNU Emacs Manual}). -@end defvar - -@defvar last-abbrev-location -This is the location of the most recent abbrev expanded. This contains -information left by @code{expand-abbrev} for the sake of the -@code{unexpand-abbrev} command. -@end defvar - -@defvar last-abbrev-text -This is the exact expansion text of the most recent abbrev expanded, -after case conversion (if any). Its value is @code{nil} if the abbrev -has already been unexpanded. This contains information left by -@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command. -@end defvar - -@defvar abbrev-expand-functions -This is a wrapper hook (@pxref{Running Hooks}) run around the -@code{expand-abbrev} function. Each function on this hook is called -with a single argument: a function that performs the normal abbrev -expansion. The hook function can hence do anything it wants before -and after performing the expansion. It can also choose not to call -its argument, thus overriding the default behavior; or it may even -call it several times. The function should return the abbrev symbol -if expansion took place. -@end defvar - - The following sample code shows a simple use of -@code{abbrev-expand-functions}. It assumes that @code{foo-mode} is a -mode for editing certain files in which lines that start with @samp{#} -are comments. You want to use Text mode abbrevs for those lines. The -regular local abbrev table, @code{foo-mode-abbrev-table} is -appropriate for all other lines. @xref{Standard Abbrev Tables}, for the -definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. - -@smallexample -(defun foo-mode-abbrev-expand-function (expand) - (if (not (save-excursion (forward-line 0) (eq (char-after) ?#))) - ;; Performs normal expansion. - (funcall expand) - ;; We're inside a comment: use the text-mode abbrevs. - (let ((local-abbrev-table text-mode-abbrev-table)) - (funcall expand)))) - -(add-hook 'foo-mode-hook - #'(lambda () - (add-hook 'abbrev-expand-functions - 'foo-mode-abbrev-expand-function - nil t))) -@end smallexample - -@node Standard Abbrev Tables, Abbrev Properties, Abbrev Expansion, Abbrevs -@comment node-name, next, previous, up -@section Standard Abbrev Tables - - Here we list the variables that hold the abbrev tables for the -preloaded major modes of Emacs. - -@defvar global-abbrev-table -This is the abbrev table for mode-independent abbrevs. The abbrevs -defined in it apply to all buffers. Each buffer may also have a local -abbrev table, whose abbrev definitions take precedence over those in the -global table. -@end defvar - -@defvar local-abbrev-table -The value of this buffer-local variable is the (mode-specific) -abbreviation table of the current buffer. It can also be a list of -such tables. -@end defvar - -@defvar abbrev-minor-mode-table-alist -The value of this variable is a list of elements of the form -@code{(@var{mode} . @var{abbrev-table})} where @var{mode} is the name -of a variable: if the variable is bound to a non-@code{nil} value, -then the @var{abbrev-table} is active, otherwise it is ignored. -@var{abbrev-table} can also be a list of abbrev tables. -@end defvar - -@defvar fundamental-mode-abbrev-table -This is the local abbrev table used in Fundamental mode; in other words, -it is the local abbrev table in all buffers in Fundamental mode. -@end defvar - -@defvar text-mode-abbrev-table -This is the local abbrev table used in Text mode. -@end defvar - -@defvar lisp-mode-abbrev-table -This is the local abbrev table used in Lisp mode. It is the parent -of the local abbrev table used in Emacs Lisp mode. @xref{Abbrev Table -Properties}. -@end defvar - -@node Abbrev Properties, Abbrev Table Properties, Standard Abbrev Tables, Abbrevs -@section Abbrev Properties - -Abbrevs have properties, some of which influence the way they work. -You can provide them as arguments to @code{define-abbrev}, and -manipulate them with the following functions: - -@defun abbrev-put abbrev prop val -Set the property @var{prop} of @var{abbrev} to value @var{val}. -@end defun - -@defun abbrev-get abbrev prop -Return the property @var{prop} of @var{abbrev}, or @code{nil} if the -abbrev has no such property. -@end defun - -The following properties have special meanings: - -@table @code -@item :count -This property counts the number of times the abbrev has -been expanded. If not explicitly set, it is initialized to 0 by -@code{define-abbrev}. - -@item :system -If non-@code{nil}, this property marks the abbrev as a system abbrev. -Such abbrevs are not saved (@pxref{Abbrev Files}). - -@item :enable-function -If non-@code{nil}, this property should be a function of no -arguments which returns @code{nil} if the abbrev should not be used -and @code{t} otherwise. - -@item :case-fixed -If non-@code{nil}, this property indicates that the case of the -abbrev's name is significant and should only match a text with the -same pattern of capitalization. It also disables the code that -modifies the capitalization of the expansion. -@end table - -@node Abbrev Table Properties, , Abbrev Properties, Abbrevs -@section Abbrev Table Properties - -Like abbrevs, abbrev tables have properties, some of which influence -the way they work. You can provide them as arguments to -@code{define-abbrev-table}, and manipulate them with the functions: - -@defun abbrev-table-put table prop val -Set the property @var{prop} of abbrev table @var{table} to value @var{val}. -@end defun - -@defun abbrev-table-get table prop -Return the property @var{prop} of abbrev table @var{table}, or @code{nil} -if the abbrev has no such property. -@end defun - -The following properties have special meaning: - -@table @code -@item :enable-function -This is like the @code{:enable-function} abbrev property except that -it applies to all abbrevs in the table. It is used before even trying -to find the abbrev before point, so it can dynamically modify the -abbrev table. - -@item :case-fixed -This is like the @code{:case-fixed} abbrev property except that it -applies to all abbrevs in the table. - -@item :regexp -If non-@code{nil}, this property is a regular expression that -indicates how to extract the name of the abbrev before point, before -looking it up in the table. When the regular expression matches -before point, the abbrev name is expected to be in submatch 1. -If this property is @code{nil}, the default is to use -@code{backward-word} and @code{forward-word} to find the name. This -property allows the use of abbrevs whose name contains characters of -non-word syntax. - -@item :parents -This property holds a list of tables from which to inherit -other abbrevs. - -@item :abbrev-table-modiff -This property holds a counter incremented each time a new abbrev is -added to the table. - -@end table diff --git a/doc/lispref/advice.texi b/doc/lispref/advice.texi deleted file mode 100644 index a2f59b2ddc9..00000000000 --- a/doc/lispref/advice.texi +++ /dev/null @@ -1,749 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/advising -@node Advising Functions, Debugging, Byte Compilation, Top -@chapter Advising Emacs Lisp Functions -@cindex advising functions - - The @dfn{advice} feature lets you add to the existing definition of -a function, by @dfn{advising the function}. This is a cleaner method -for a library to customize functions defined within Emacs---cleaner -than redefining the whole function. - -@cindex piece of advice - Each function can have multiple @dfn{pieces of advice}, each of -which can be separately defined and then @dfn{enabled} or -@dfn{disabled}. All the enabled pieces of advice for any given -function actually take effect when you @dfn{activate advice} for that -function, or when you define or redefine the function. Note that -enabling a piece of advice and activating advice for a function are -not the same thing. - - Advice is useful for altering the behavior of existing calls to an -existing function. If you want the new behavior for new function -calls or new key bindings, you should define a new function or -command, and have it use the existing function as a subroutine. - - Advising a function can cause confusion in debugging, since people -who debug calls to the original function may not notice that it has -been modified with advice. Therefore, if you have the possibility to -change the code of that function to run a hook, please solve the -problem that way. Advice should be reserved for the cases where you -cannot get the function changed. In particular, Emacs's own source -files should not put advice on functions in Emacs. There are -currently a few exceptions to this convention, but we aim to correct -them. - - Unless you know what you are doing, do @emph{not} advise a primitive -(@pxref{What Is a Function}). Some primitives are used by the advice -mechanism; advising them could cause an infinite recursion. Also, -many primitives are called directly from C code. Calls to the -primitive from Lisp code will take note of the advice, but calls from -C code will ignore the advice. - -@menu -* Simple Advice:: A simple example to explain the basics of advice. -* Defining Advice:: Detailed description of @code{defadvice}. -* Around-Advice:: Wrapping advice around a function's definition. -* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. -* Activation of Advice:: Advice doesn't do anything until you activate it. -* Enabling Advice:: You can enable or disable each piece of advice. -* Preactivation:: Preactivation is a way of speeding up the - loading of compiled advice. -* Argument Access in Advice:: How advice can access the function's arguments. -* Combined Definition:: How advice is implemented. -@end menu - -@node Simple Advice -@section A Simple Advice Example - - The command @code{next-line} moves point down vertically one or more -lines; it is the standard binding of @kbd{C-n}. When used on the last -line of the buffer, this command inserts a newline to create a line to -move to if @code{next-line-add-newlines} is non-@code{nil} (its default -is @code{nil}.) - - Suppose you wanted to add a similar feature to @code{previous-line}, -which would insert a new line at the beginning of the buffer for the -command to move to (when @code{next-line-add-newlines} is -non-@code{nil}). How could you do this? - - You could do it by redefining the whole function, but that is not -modular. The advice feature provides a cleaner alternative: you can -effectively add your code to the existing function definition, without -actually changing or even seeing that definition. Here is how to do -this: - -@example -(defadvice previous-line (before next-line-at-end - (&optional arg try-vscroll)) - "Insert an empty line when moving up from the top line." - (if (and next-line-add-newlines (= arg 1) - (save-excursion (beginning-of-line) (bobp))) - (progn - (beginning-of-line) - (newline)))) -@end example - - This expression defines a @dfn{piece of advice} for the function -@code{previous-line}. This piece of advice is named -@code{next-line-at-end}, and the symbol @code{before} says that it is -@dfn{before-advice} which should run before the regular definition of -@code{previous-line}. @code{(&optional arg try-vscroll)} specifies -how the advice code can refer to the function's arguments. - - When this piece of advice runs, it creates an additional line, in the -situation where that is appropriate, but does not move point to that -line. This is the correct way to write the advice, because the normal -definition will run afterward and will move back to the newly inserted -line. - - Defining the advice doesn't immediately change the function -@code{previous-line}. That happens when you @dfn{activate} the advice, -like this: - -@example -(ad-activate 'previous-line) -@end example - -@noindent -This is what actually begins to use the advice that has been defined so -far for the function @code{previous-line}. Henceforth, whenever that -function is run, whether invoked by the user with @kbd{C-p} or -@kbd{M-x}, or called from Lisp, it runs the advice first, and its -regular definition second. - - This example illustrates before-advice, which is one @dfn{class} of -advice: it runs before the function's base definition. There are two -other advice classes: @dfn{after-advice}, which runs after the base -definition, and @dfn{around-advice}, which lets you specify an -expression to wrap around the invocation of the base definition. - -@node Defining Advice -@section Defining Advice -@cindex defining advice -@cindex advice, defining - - To define a piece of advice, use the macro @code{defadvice}. A call -to @code{defadvice} has the following syntax, which is based on the -syntax of @code{defun} and @code{defmacro}, but adds more: - -@findex defadvice -@example -(defadvice @var{function} (@var{class} @var{name} - @r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]} - @var{flags}...) - @r{[}@var{documentation-string}@r{]} - @r{[}@var{interactive-form}@r{]} - @var{body-forms}...) -@end example - -@noindent -Here, @var{function} is the name of the function (or macro or special -form) to be advised. From now on, we will write just ``function'' when -describing the entity being advised, but this always includes macros and -special forms. - - In place of the argument list in an ordinary definition, an advice -definition calls for several different pieces of information. - -@cindex class of advice -@cindex before-advice -@cindex after-advice -@cindex around-advice -@var{class} specifies the @dfn{class} of the advice---one of @code{before}, -@code{after}, or @code{around}. Before-advice runs before the function -itself; after-advice runs after the function itself; around-advice is -wrapped around the execution of the function itself. After-advice and -around-advice can override the return value by setting -@code{ad-return-value}. - -@defvar ad-return-value -While advice is executing, after the function's original definition has -been executed, this variable holds its return value, which will -ultimately be returned to the caller after finishing all the advice. -After-advice and around-advice can arrange to return some other value -by storing it in this variable. -@end defvar - -The argument @var{name} is the name of the advice, a non-@code{nil} -symbol. The advice name uniquely identifies one piece of advice, within all -the pieces of advice in a particular class for a particular -@var{function}. The name allows you to refer to the piece of -advice---to redefine it, or to enable or disable it. - -The optional @var{position} specifies where, in the current list of -advice of the specified @var{class}, this new advice should be placed. -It should be either @code{first}, @code{last} or a number that specifies -a zero-based position (@code{first} is equivalent to 0). If no position -is specified, the default is @code{first}. Position values outside the -range of existing positions in this class are mapped to the beginning or -the end of the range, whichever is closer. The @var{position} value is -ignored when redefining an existing piece of advice. - -The optional @var{arglist} can be used to define the argument list for -the sake of advice. This becomes the argument list of the combined -definition that is generated in order to run the advice (@pxref{Combined -Definition}). Therefore, the advice expressions can use the argument -variables in this list to access argument values. - -The argument list used in advice need not be the same as the argument -list used in the original function, but must be compatible with it, so -that it can handle the ways the function is actually called. If two -pieces of advice for a function both specify an argument list, they must -specify the same argument list. - -@xref{Argument Access in Advice}, for more information about argument -lists and advice, and a more flexible way for advice to access the -arguments. - -The remaining elements, @var{flags}, are symbols that specify further -information about how to use this piece of advice. Here are the valid -symbols and their meanings: - -@table @code -@item activate -Activate the advice for @var{function} now. Changes in a function's -advice always take effect the next time you activate advice for the -function; this flag says to do so, for @var{function}, immediately after -defining this piece of advice. - -@cindex forward advice -This flag has no immediate effect if @var{function} itself is not defined yet (a -situation known as @dfn{forward advice}), because it is impossible to -activate an undefined function's advice. However, defining -@var{function} will automatically activate its advice. - -@item protect -Protect this piece of advice against non-local exits and errors in -preceding code and advice. Protecting advice places it as a cleanup in -an @code{unwind-protect} form, so that it will execute even if the -previous code gets an error or uses @code{throw}. @xref{Cleanups}. - -@item compile -Compile the combined definition that is used to run the advice. This -flag is ignored unless @code{activate} is also specified. -@xref{Combined Definition}. - -@item disable -Initially disable this piece of advice, so that it will not be used -unless subsequently explicitly enabled. @xref{Enabling Advice}. - -@item preactivate -Activate advice for @var{function} when this @code{defadvice} is -compiled or macroexpanded. This generates a compiled advised definition -according to the current advice state, which will be used during -activation if appropriate. @xref{Preactivation}. - -This is useful only if this @code{defadvice} is byte-compiled. -@end table - -The optional @var{documentation-string} serves to document this piece of -advice. When advice is active for @var{function}, the documentation for -@var{function} (as returned by @code{documentation}) combines the -documentation strings of all the advice for @var{function} with the -documentation string of its original function definition. - -The optional @var{interactive-form} form can be supplied to change the -interactive behavior of the original function. If more than one piece -of advice has an @var{interactive-form}, then the first one (the one -with the smallest position) found among all the advice takes precedence. - -The possibly empty list of @var{body-forms} specifies the body of the -advice. The body of an advice can access or change the arguments, the -return value, the binding environment, and perform any other kind of -side effect. - -@strong{Warning:} When you advise a macro, keep in mind that macros are -expanded when a program is compiled, not when a compiled program is run. -All subroutines used by the advice need to be available when the byte -compiler expands the macro. - -@deffn Command ad-unadvise function -This command deletes all pieces of advice from @var{function}. -@end deffn - -@deffn Command ad-unadvise-all -This command deletes all pieces of advice from all functions. -@end deffn - -@node Around-Advice -@section Around-Advice - - Around-advice lets you ``wrap'' a Lisp expression ``around'' the -original function definition. You specify where the original function -definition should go by means of the special symbol @code{ad-do-it}. -Where this symbol occurs inside the around-advice body, it is replaced -with a @code{progn} containing the forms of the surrounded code. Here -is an example: - -@example -(defadvice foo (around foo-around) - "Ignore case in `foo'." - (let ((case-fold-search t)) - ad-do-it)) -@end example - -@noindent -Its effect is to make sure that case is ignored in -searches when the original definition of @code{foo} is run. - -@defvar ad-do-it -This is not really a variable, rather a place-holder that looks like a -variable. You use it in around-advice to specify the place to run the -function's original definition and other ``earlier'' around-advice. -@end defvar - -If the around-advice does not use @code{ad-do-it}, then it does not run -the original function definition. This provides a way to override the -original definition completely. (It also overrides lower-positioned -pieces of around-advice). - -If the around-advice uses @code{ad-do-it} more than once, the original -definition is run at each place. In this way, around-advice can execute -the original definition (and lower-positioned pieces of around-advice) -several times. Another way to do that is by using @code{ad-do-it} -inside of a loop. - -@node Computed Advice -@section Computed Advice - -The macro @code{defadvice} resembles @code{defun} in that the code for -the advice, and all other information about it, are explicitly stated in -the source code. You can also create advice whose details are computed, -using the function @code{ad-add-advice}. - -@defun ad-add-advice function advice class position -Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to -@var{function} in class @var{class}. The argument @var{advice} has -this form: - -@example -(@var{name} @var{protected} @var{enabled} @var{definition}) -@end example - -@noindent -Here, @var{protected} and @var{enabled} are flags; if @var{protected} -is non-@code{nil}, the advice is protected against non-local exits -(@pxref{Defining Advice}), and if @var{enabled} is @code{nil} the -advice is initially disabled (@pxref{Enabling Advice}). -@var{definition} should have the form - -@example -(advice . @var{lambda}) -@end example - -@noindent -where @var{lambda} is a lambda expression; this lambda expression is -called in order to perform the advice. @xref{Lambda Expressions}. - -If the @var{function} argument to @code{ad-add-advice} already has one -or more pieces of advice in the specified @var{class}, then -@var{position} specifies where in the list to put the new piece of -advice. The value of @var{position} can either be @code{first}, -@code{last}, or a number (counting from 0 at the beginning of the -list). Numbers outside the range are mapped to the beginning or the -end of the range, whichever is closer. The @var{position} value is -ignored when redefining an existing piece of advice. - -If @var{function} already has a piece of @var{advice} with the same -name, then the position argument is ignored and the old advice is -replaced with the new one. -@end defun - -@node Activation of Advice -@section Activation of Advice -@cindex activating advice -@cindex advice, activating - -By default, advice does not take effect when you define it---only when -you @dfn{activate} advice for the function. However, the advice will -be activated automatically if you define or redefine the function -later. You can request the activation of advice for a function when -you define the advice, by specifying the @code{activate} flag in the -@code{defadvice}; or you can activate the advice separately by calling -the function @code{ad-activate} or one of the other activation -commands listed below. - -Separating the activation of advice from the act of defining it permits -you to add several pieces of advice to one function efficiently, without -redefining the function over and over as each advice is added. More -importantly, it permits defining advice for a function before that -function is actually defined. - -When a function's advice is first activated, the function's original -definition is saved, and all enabled pieces of advice for that function -are combined with the original definition to make a new definition. -(Pieces of advice that are currently disabled are not used; see -@ref{Enabling Advice}.) This definition is installed, and optionally -byte-compiled as well, depending on conditions described below. - -In all of the commands to activate advice, if @var{compile} is -@code{t} (or anything but @code{nil} or a negative number), the -command also compiles the combined definition which implements the -advice. If it is @code{nil} or a negative number, what happens -depends on @code{ad-default-compilation-action} as described below. - -@deffn Command ad-activate function &optional compile -This command activates all the advice defined for @var{function}. -@end deffn - - Activating advice does nothing if @var{function}'s advice is already -active. But if there is new advice, added since the previous time you -activated advice for @var{function}, it activates the new advice. - -@deffn Command ad-deactivate function -This command deactivates the advice for @var{function}. -@cindex deactivating advice -@c @cindex advice, deactivating "advice, activating" is just above -@end deffn - -@deffn Command ad-update function &optional compile -This command activates the advice for @var{function} -if its advice is already activated. This is useful -if you change the advice. -@end deffn - -@deffn Command ad-activate-all &optional compile -This command activates the advice for all functions. -@end deffn - -@deffn Command ad-deactivate-all -This command deactivates the advice for all functions. -@end deffn - -@deffn Command ad-update-all &optional compile -This command activates the advice for all functions -whose advice is already activated. This is useful -if you change the advice of some functions. -@end deffn - -@deffn Command ad-activate-regexp regexp &optional compile -This command activates all pieces of advice whose names match -@var{regexp}. More precisely, it activates all advice for any function -which has at least one piece of advice that matches @var{regexp}. -@end deffn - -@deffn Command ad-deactivate-regexp regexp -This command deactivates all pieces of advice whose names match -@var{regexp}. More precisely, it deactivates all advice for any -function which has at least one piece of advice that matches -@var{regexp}. -@end deffn - -@deffn Command ad-update-regexp regexp &optional compile -This command activates pieces of advice whose names match @var{regexp}, -but only those for functions whose advice is already activated. -@cindex reactivating advice - -Reactivating a function's advice is useful for putting into effect all -the changes that have been made in its advice (including enabling and -disabling specific pieces of advice; @pxref{Enabling Advice}) since the -last time it was activated. -@end deffn - -@deffn Command ad-start-advice -Turn on automatic advice activation when a function is defined or -redefined. This is the default mode. -@end deffn - -@deffn Command ad-stop-advice -Turn off automatic advice activation when a function is defined or -redefined. -@end deffn - -@defopt ad-default-compilation-action -This variable controls whether to compile the combined definition -that results from activating advice for a function. - -A value of @code{always} specifies to compile unconditionally. -A value of @code{never} specifies never compile the advice. - -A value of @code{maybe} specifies to compile if the byte compiler is -already loaded. A value of @code{like-original} specifies to compile -the advice if the original definition of the advised function is -compiled or a built-in function. - -This variable takes effect only if the @var{compile} argument of -@code{ad-activate} (or any of the above functions) did not force -compilation. -@end defopt - - If the advised definition was constructed during ``preactivation'' -(@pxref{Preactivation}), then that definition must already be compiled, -because it was constructed during byte-compilation of the file that -contained the @code{defadvice} with the @code{preactivate} flag. - -@node Enabling Advice -@section Enabling and Disabling Advice -@cindex enabling advice -@cindex advice, enabling and disabling -@cindex disabling advice - - Each piece of advice has a flag that says whether it is enabled or -not. By enabling or disabling a piece of advice, you can turn it on -and off without having to undefine and redefine it. For example, here is -how to disable a particular piece of advice named @code{my-advice} for -the function @code{foo}: - -@example -(ad-disable-advice 'foo 'before 'my-advice) -@end example - - This function by itself only changes the enable flag for a piece of -advice. To make the change take effect in the advised definition, you -must activate the advice for @code{foo} again: - -@example -(ad-activate 'foo) -@end example - -@deffn Command ad-disable-advice function class name -This command disables the piece of advice named @var{name} in class -@var{class} on @var{function}. -@end deffn - -@deffn Command ad-enable-advice function class name -This command enables the piece of advice named @var{name} in class -@var{class} on @var{function}. -@end deffn - - You can also disable many pieces of advice at once, for various -functions, using a regular expression. As always, the changes take real -effect only when you next reactivate advice for the functions in -question. - -@deffn Command ad-disable-regexp regexp -This command disables all pieces of advice whose names match -@var{regexp}, in all classes, on all functions. -@end deffn - -@deffn Command ad-enable-regexp regexp -This command enables all pieces of advice whose names match -@var{regexp}, in all classes, on all functions. -@end deffn - -@node Preactivation -@section Preactivation -@cindex preactivating advice -@cindex advice, preactivating - - Constructing a combined definition to execute advice is moderately -expensive. When a library advises many functions, this can make loading -the library slow. In that case, you can use @dfn{preactivation} to -construct suitable combined definitions in advance. - - To use preactivation, specify the @code{preactivate} flag when you -define the advice with @code{defadvice}. This @code{defadvice} call -creates a combined definition which embodies this piece of advice -(whether enabled or not) plus any other currently enabled advice for the -same function, and the function's own definition. If the -@code{defadvice} is compiled, that compiles the combined definition -also. - - When the function's advice is subsequently activated, if the enabled -advice for the function matches what was used to make this combined -definition, then the existing combined definition is used, thus avoiding -the need to construct one. Thus, preactivation never causes wrong -results---but it may fail to do any good, if the enabled advice at the -time of activation doesn't match what was used for preactivation. - - Here are some symptoms that can indicate that a preactivation did not -work properly, because of a mismatch. - -@itemize @bullet -@item -Activation of the advised -function takes longer than usual. -@item -The byte compiler gets -loaded while an advised function gets activated. -@item -@code{byte-compile} is included in the value of @code{features} even -though you did not ever explicitly use the byte compiler. -@end itemize - -Compiled preactivated advice works properly even if the function itself -is not defined until later; however, the function needs to be defined -when you @emph{compile} the preactivated advice. - -There is no elegant way to find out why preactivated advice is not being -used. What you can do is to trace the function -@code{ad-cache-id-verification-code} (with the function -@code{trace-function-background}) before the advised function's advice -is activated. After activation, check the value returned by -@code{ad-cache-id-verification-code} for that function: @code{verified} -means that the preactivated advice was used, while other values give -some information about why they were considered inappropriate. - - @strong{Warning:} There is one known case that can make preactivation -fail, in that a preconstructed combined definition is used even though -it fails to match the current state of advice. This can happen when two -packages define different pieces of advice with the same name, in the -same class, for the same function. But you should avoid that anyway. - -@node Argument Access in Advice -@section Argument Access in Advice - - The simplest way to access the arguments of an advised function in the -body of a piece of advice is to use the same names that the function -definition uses. To do this, you need to know the names of the argument -variables of the original function. - - While this simple method is sufficient in many cases, it has a -disadvantage: it is not robust, because it hard-codes the argument names -into the advice. If the definition of the original function changes, -the advice might break. - - Another method is to specify an argument list in the advice itself. -This avoids the need to know the original function definition's argument -names, but it has a limitation: all the advice on any particular -function must use the same argument list, because the argument list -actually used for all the advice comes from the first piece of advice -for that function. - - A more robust method is to use macros that are translated into the -proper access forms at activation time, i.e., when constructing the -advised definition. Access macros access actual arguments by their -(zero-based) position, regardless of how these actual arguments get -distributed onto the argument variables of a function. This is robust -because in Emacs Lisp the meaning of an argument is strictly -determined by its position in the argument list. - -@defmac ad-get-arg position -This returns the actual argument that was supplied at @var{position}. -@end defmac - -@defmac ad-get-args position -This returns the list of actual arguments supplied starting at -@var{position}. -@end defmac - -@defmac ad-set-arg position value -This sets the value of the actual argument at @var{position} to -@var{value} -@end defmac - -@defmac ad-set-args position value-list -This sets the list of actual arguments starting at @var{position} to -@var{value-list}. -@end defmac - - Now an example. Suppose the function @code{foo} is defined as - -@example -(defun foo (x y &optional z &rest r) ...) -@end example - -@noindent -and is then called with - -@example -(foo 0 1 2 3 4 5 6) -@end example - -@noindent -which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is -@code{(3 4 5 6)} within the body of @code{foo}. Here is what -@code{ad-get-arg} and @code{ad-get-args} return in this case: - -@example -(ad-get-arg 0) @result{} 0 -(ad-get-arg 1) @result{} 1 -(ad-get-arg 2) @result{} 2 -(ad-get-arg 3) @result{} 3 -(ad-get-args 2) @result{} (2 3 4 5 6) -(ad-get-args 4) @result{} (4 5 6) -@end example - - Setting arguments also makes sense in this example: - -@example -(ad-set-arg 5 "five") -@end example - -@noindent -has the effect of changing the sixth argument to @code{"five"}. If this -happens in advice executed before the body of @code{foo} is run, then -@var{r} will be @code{(3 4 "five" 6)} within that body. - - Here is an example of setting a tail of the argument list: - -@example -(ad-set-args 0 '(5 4 3 2 1 0)) -@end example - -@noindent -If this happens in advice executed before the body of @code{foo} is run, -then within that body, @var{x} will be 5, @var{y} will be 4, @var{z} -will be 3, and @var{r} will be @code{(2 1 0)} inside the body of -@code{foo}. - - These argument constructs are not really implemented as Lisp macros. -Instead they are implemented specially by the advice mechanism. - -@node Combined Definition -@section The Combined Definition - - Suppose that a function has @var{n} pieces of before-advice -(numbered from 0 through @var{n}@minus{}1), @var{m} pieces of -around-advice and @var{k} pieces of after-advice. Assuming no piece -of advice is protected, the combined definition produced to implement -the advice for a function looks like this: - -@example -(lambda @var{arglist} - @r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]} - (let (ad-return-value) - @r{before-0-body-form}... - .... - @r{before-@var{n}@minus{}1-body-form}... - @r{around-0-body-form}... - @r{around-1-body-form}... - .... - @r{around-@var{m}@minus{}1-body-form}... - (setq ad-return-value - @r{apply original definition to @var{arglist}}) - @r{end-of-around-@var{m}@minus{}1-body-form}... - .... - @r{end-of-around-1-body-form}... - @r{end-of-around-0-body-form}... - @r{after-0-body-form}... - .... - @r{after-@var{k}@minus{}1-body-form}... - ad-return-value)) -@end example - -Macros are redefined as macros, which means adding @code{macro} to -the beginning of the combined definition. - -The interactive form is present if the original function or some piece -of advice specifies one. When an interactive primitive function is -advised, advice uses a special method: it calls the primitive with -@code{call-interactively} so that it will read its own arguments. -In this case, the advice cannot access the arguments. - -The body forms of the various advice in each class are assembled -according to their specified order. The forms of around-advice @var{l} -are included in one of the forms of around-advice @var{l} @minus{} 1. - -The innermost part of the around advice onion is - -@display -apply original definition to @var{arglist} -@end display - -@noindent -whose form depends on the type of the original function. The variable -@code{ad-return-value} is set to whatever this returns. The variable is -visible to all pieces of advice, which can access and modify it before -it is actually returned from the advised function. - -The semantic structure of advised functions that contain protected -pieces of advice is the same. The only difference is that -@code{unwind-protect} forms ensure that the protected advice gets -executed even if some previous piece of advice had an error or a -non-local exit. If any around-advice is protected, then the whole -around-advice onion is protected as a result. diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi deleted file mode 100644 index 59f8f91c855..00000000000 --- a/doc/lispref/anti.texi +++ /dev/null @@ -1,141 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2002-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. - -@c This node must have no pointers. - -@node Antinews, GNU Free Documentation License, Packaging, Top -@appendix Emacs 23 Antinews -@c Update the elisp.texi, vol1.texi, vol2.texi Antinews menu entries -@c with the above version number. - -For those users who live backwards in time, here is information about -downgrading to Emacs version 23.4. We hope you will enjoy the greater -simplicity that results from the absence of many Emacs @value{EMACSVER} -features. - -@section Old Lisp Features in Emacs 23 - -@itemize @bullet -@item -Support for lexical scoping has been removed; all variables are -dynamically scoped. The @code{lexical-binding} variable has been -removed, and so has the @var{lexical} argument to @code{eval}. The -@code{defvar} and @code{defconst} forms no longer mark variables as -dynamic, since all variables are dynamic. - -Having only dynamic binding follows the spirit of Emacs extensibility, -for it allows any Emacs code to access any defined variable with a -minimum of fuss. But @xref{Dynamic Binding Tips}, for tips to avoid -making your programs hard to understand. - -@item -Calling a minor mode function from Lisp with a nil or omitted argument -does not enable the minor mode unconditionally; instead, it toggles -the minor mode---which is the straightforward thing to do, since that -is the behavior when invoked interactively. One downside is that it -is more troublesome to enable minor modes from hooks; you have to do -something like - -@example -(add-hook 'foo-hook (lambda () (bar-mode 1))) -@end example - -@noindent -or define @code{turn-on-bar-mode} and call that from the hook. - -@item -The @code{prog-mode} dummy major mode has been removed. Instead of -using it as a crutch to meet programming mode conventions, you should -explicitly ensure that your mode follows those conventions. -@xref{Major Mode Conventions}. - -@item -Emacs no longer supports bidirectional display and editing. Since -there is no need to worry about the insertion of right-to-left text -messing up how lines and paragraphs are displayed, the function -@code{bidi-string-mark-left-to-right} has been removed; so have many -other functions and variables related to bidirectional display. -Unicode directionality characters like @code{U+200E} ("left-to-right -mark") have no special effect on display. - -@item -Emacs windows now have most of their internal state hidden from Lisp. -Internal windows are no longer visible to Lisp; functions such as -@code{window-parent}, window parameters related to window arrangement, -and window-local buffer lists have all been removed. Functions for -resizing windows can delete windows if they become too small. - -The ``action function'' feature for controlling buffer display has -been removed, including @code{display-buffer-overriding-action} and -related variables, as well as the @var{action} argument to -@code{display-buffer} and other functions. The way to -programmatically control how Emacs chooses a window to display a -buffer is to bind the right combination of -@code{special-display-regexps}, @code{pop-up-frames}, and other -variables. - -@item -The standard completion interface has been simplified, eliminating the -@code{completion-extra-properties} variable, the @code{metadata} -action flag for completion functions, and the concept of -``completion categories''. Lisp programmers may now find the choice -of methods for tuning completion less bewildering, but if a package -finds the streamlined interface insufficient for its needs, it must -implement its own specialized completion feature. - -@item -@code{copy-directory} now behaves the same whether or not the -destination is an existing directory: if the destination exists, the -@emph{contents} of the first directory are copied into it (with -subdirectories handled recursively), rather than copying the first -directory into a subdirectory. - -@item -The @var{trash} arguments for @code{delete-file} and -@code{delete-directory} have been removed. The variable -@code{delete-by-moving-to-trash} must now be used with care; whenever -it is non-@code{nil}, all calls to @code{delete-file} or -@code{delete-directory} use the trash. - -@item -Because Emacs no longer supports SELinux file contexts, the -@var{preserve-selinux-context} argument to @code{copy-file} has been -removed. The return value of @code{backup-buffer} no longer has an -entry for the SELinux file context. - -@item -For mouse click input events in the text area, the Y pixel coordinate -in the @var{position} list (@pxref{Click Events}) now counts from the -top of the header line, if there is one, rather than the top of the -text area. - -@item -Bindings in menu keymaps (@pxref{Format of Keymaps}) now sometimes get -an additional @var{cache} entry in their definitions, like this: - -@example -(@var{type} @var{item-name} @var{cache} . @var{binding}) -@end example - -@noindent -The @var{cache} entry is used internally by Emacs to record equivalent -keyboard key sequences for invoking the same command; Lisp programs -should never use it. -@c Not really NEWS-worthy then... - -@item -The @code{gnutls} library has been removed, and the function -@code{open-network-stream} correspondingly simplified. -Lisp programs that want an encrypted network connection must now call -external utilities such as @command{starttls} or @command{gnutls-cli}. - -@item -Tool bars can no longer display separators, which frees up several -pixels of space on each graphical frame. - -@item -As part of the ongoing quest for simplicity, many other functions and -variables have been eliminated. -@end itemize diff --git a/doc/lispref/back.texi b/doc/lispref/back.texi deleted file mode 100644 index 75c244ae1dd..00000000000 --- a/doc/lispref/back.texi +++ /dev/null @@ -1,37 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@c -@c %**start of header -@setfilename back-cover -@settitle GNU Emacs Lisp Reference Manual -@c %**end of header -. -@sp 7 -@center @titlefont {GNU Emacs Lisp} -@sp 1 - -@quotation - Most of the GNU Emacs text editor is written in the programming -language called Emacs Lisp. You can write new code in Emacs Lisp and -install it as an extension to the editor. However, Emacs Lisp is more -than a mere ``extension language''; it is a full computer programming -language in its own right. You can use it as you would any other -programming language. - - Because Emacs Lisp is designed for use in an editor, it has special -features for scanning and parsing text as well as features for handling -files, buffers, displays, subprocesses, and so on. Emacs Lisp is -closely integrated with the editing facilities; thus, editing commands -are functions that can also conveniently be called from Lisp programs, -and parameters for customization are ordinary Lisp variables. - - This manual describes Emacs Lisp. Generally speaking, the earlier -chapters describe features of Emacs Lisp that have counterparts in -many programming languages, and later chapters describe features that -are peculiar to Emacs Lisp or relate specifically to editing. -@end quotation - -@hfil -@bye diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi deleted file mode 100644 index a1c5f20f28c..00000000000 --- a/doc/lispref/backups.texi +++ /dev/null @@ -1,774 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/backups -@node Backups and Auto-Saving, Buffers, Files, Top -@chapter Backups and Auto-Saving -@cindex backups and auto-saving - - Backup files and auto-save files are two methods by which Emacs tries -to protect the user from the consequences of crashes or of the user's -own errors. Auto-saving preserves the text from earlier in the current -editing session; backup files preserve file contents prior to the -current session. - -@menu -* Backup Files:: How backup files are made; how their names are chosen. -* Auto-Saving:: How auto-save files are made; how their names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize what it does. -@end menu - -@node Backup Files -@section Backup Files -@cindex backup file - - A @dfn{backup file} is a copy of the old contents of a file you are -editing. Emacs makes a backup file the first time you save a buffer -into its visited file. Thus, normally, the backup file contains the -contents of the file as it was before the current editing session. -The contents of the backup file normally remain unchanged once it -exists. - - Backups are usually made by renaming the visited file to a new name. -Optionally, you can specify that backup files should be made by copying -the visited file. This choice makes a difference for files with -multiple names; it also can affect whether the edited file remains owned -by the original owner or becomes owned by the user editing it. - - By default, Emacs makes a single backup file for each file edited. -You can alternatively request numbered backups; then each new backup -file gets a new name. You can delete old numbered backups when you -don't want them any more, or Emacs can delete them automatically. - -@menu -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. -@end menu - -@node Making Backups -@subsection Making Backup Files - -@defun backup-buffer - This function makes a backup of the file visited by the current -buffer, if appropriate. It is called by @code{save-buffer} before -saving the buffer the first time. - -If a backup was made by renaming, the return value is a cons cell of -the form (@var{modes} @var{context} @var{backupname}), where -@var{modes} are the mode bits of the original file, as returned by -@code{file-modes} (@pxref{File Attributes,, Other Information about -Files}), @var{context} is a list describing the original file's -SELinux context (@pxref{File Attributes}), and @var{backupname} is the -name of the backup. In all other cases, that is, if a backup was made -by copying or if no backup was made, this function returns @code{nil}. -@end defun - -@defvar buffer-backed-up - This buffer-local variable says whether this buffer's file has -been backed up on account of this buffer. If it is non-@code{nil}, -the backup file has been written. Otherwise, the file should be backed -up when it is next saved (if backups are enabled). This is a -permanent local; @code{kill-all-local-variables} does not alter@tie{}it. -@end defvar - -@defopt make-backup-files -This variable determines whether or not to make backup files. If it -is non-@code{nil}, then Emacs creates a backup of each file when it is -saved for the first time---provided that @code{backup-inhibited} -is @code{nil} (see below). - -The following example shows how to change the @code{make-backup-files} -variable only in the Rmail buffers and not elsewhere. Setting it -@code{nil} stops Emacs from making backups of these files, which may -save disk space. (You would put this code in your init file.) - -@smallexample -@group -(add-hook 'rmail-mode-hook - (lambda () - (set (make-local-variable 'make-backup-files) nil))) -@end group -@end smallexample -@end defopt - -@defvar backup-enable-predicate -This variable's value is a function to be called on certain occasions to -decide whether a file should have backup files. The function receives -one argument, an absolute file name to consider. If the function returns -@code{nil}, backups are disabled for that file. Otherwise, the other -variables in this section say whether and how to make backups. - -@findex normal-backup-enable-predicate -The default value is @code{normal-backup-enable-predicate}, which checks -for files in @code{temporary-file-directory} and -@code{small-temporary-file-directory}. -@end defvar - -@defvar backup-inhibited -If this variable is non-@code{nil}, backups are inhibited. It records -the result of testing @code{backup-enable-predicate} on the visited file -name. It can also coherently be used by other mechanisms that inhibit -backups based on which file is visited. For example, VC sets this -variable non-@code{nil} to prevent making backups for files managed -with a version control system. - -This is a permanent local, so that changing the major mode does not lose -its value. Major modes should not set this variable---they should set -@code{make-backup-files} instead. -@end defvar - -@defopt backup-directory-alist -This variable's value is an alist of filename patterns and backup -directory names. Each element looks like -@smallexample -(@var{regexp} . @var{directory}) -@end smallexample - -@noindent -Backups of files with names matching @var{regexp} will be made in -@var{directory}. @var{directory} may be relative or absolute. If it is -absolute, so that all matching files are backed up into the same -directory, the file names in this directory will be the full name of the -file backed up with all directory separators changed to @samp{!} to -prevent clashes. This will not work correctly if your filesystem -truncates the resulting name. - -For the common case of all backups going into one directory, the alist -should contain a single element pairing @samp{"."} with the appropriate -directory name. - -If this variable is @code{nil} (the default), or it fails to match a -filename, the backup is made in the original file's directory. - -On MS-DOS filesystems without long names this variable is always -ignored. -@end defopt - -@defopt make-backup-file-name-function -This variable's value is a function to use for making backups instead -of the default @code{make-backup-file-name}. A value of @code{nil} -gives the default @code{make-backup-file-name} behavior. -@xref{Backup Names,, Naming Backup Files}. - -This could be buffer-local to do something special for specific -files. If you define it, you may need to change -@code{backup-file-name-p} and @code{file-name-sans-versions} too. -@end defopt - - -@node Rename or Copy -@subsection Backup by Renaming or by Copying? -@cindex backup files, rename or copy - - There are two ways that Emacs can make a backup file: - -@itemize @bullet -@item -Emacs can rename the original file so that it becomes a backup file, and -then write the buffer being saved into a new file. After this -procedure, any other names (i.e., hard links) of the original file now -refer to the backup file. The new file is owned by the user doing the -editing, and its group is the default for new files written by the user -in that directory. - -@item -Emacs can copy the original file into a backup file, and then overwrite -the original file with new contents. After this procedure, any other -names (i.e., hard links) of the original file continue to refer to the -current (updated) version of the file. The file's owner and group will -be unchanged. -@end itemize - - The first method, renaming, is the default. - - The variable @code{backup-by-copying}, if non-@code{nil}, says to use -the second method, which is to copy the original file and overwrite it -with the new buffer contents. The variable @code{file-precious-flag}, -if non-@code{nil}, also has this effect (as a sideline of its main -significance). @xref{Saving Buffers}. - -@defopt backup-by-copying -If this variable is non-@code{nil}, Emacs always makes backup files by -copying. The default is @code{nil}. -@end defopt - - The following three variables, when non-@code{nil}, cause the second -method to be used in certain special cases. They have no effect on the -treatment of files that don't fall into the special cases. - -@defopt backup-by-copying-when-linked -If this variable is non-@code{nil}, Emacs makes backups by copying for -files with multiple names (hard links). The default is @code{nil}. - -This variable is significant only if @code{backup-by-copying} is -@code{nil}, since copying is always used when that variable is -non-@code{nil}. -@end defopt - -@defopt backup-by-copying-when-mismatch -If this variable is non-@code{nil} (the default), Emacs makes backups -by copying in cases where renaming would change either the owner or -the group of the file. - -The value has no effect when renaming would not alter the owner or -group of the file; that is, for files which are owned by the user and -whose group matches the default for a new file created there by the -user. - -This variable is significant only if @code{backup-by-copying} is -@code{nil}, since copying is always used when that variable is -non-@code{nil}. -@end defopt - -@defopt backup-by-copying-when-privileged-mismatch -This variable, if non-@code{nil}, specifies the same behavior as -@code{backup-by-copying-when-mismatch}, but only for certain user-id -values: namely, those less than or equal to a certain number. You set -this variable to that number. - -Thus, if you set @code{backup-by-copying-when-privileged-mismatch} -to 0, backup by copying is done for the superuser only, -when necessary to prevent a change in the owner of the file. - -The default is 200. -@end defopt - -@node Numbered Backups -@subsection Making and Deleting Numbered Backup Files - - If a file's name is @file{foo}, the names of its numbered backup -versions are @file{foo.~@var{v}~}, for various integers @var{v}, like -this: @file{foo.~1~}, @file{foo.~2~}, @file{foo.~3~}, @dots{}, -@file{foo.~259~}, and so on. - -@defopt version-control -This variable controls whether to make a single non-numbered backup -file or multiple numbered backups. - -@table @asis -@item @code{nil} -Make numbered backups if the visited file already has numbered backups; -otherwise, do not. This is the default. - -@item @code{never} -Do not make numbered backups. - -@item @var{anything else} -Make numbered backups. -@end table -@end defopt - - The use of numbered backups ultimately leads to a large number of -backup versions, which must then be deleted. Emacs can do this -automatically or it can ask the user whether to delete them. - -@defopt kept-new-versions -The value of this variable is the number of newest versions to keep -when a new numbered backup is made. The newly made backup is included -in the count. The default value is@tie{}2. -@end defopt - -@defopt kept-old-versions -The value of this variable is the number of oldest versions to keep -when a new numbered backup is made. The default value is@tie{}2. -@end defopt - - If there are backups numbered 1, 2, 3, 5, and 7, and both of these -variables have the value 2, then the backups numbered 1 and 2 are kept -as old versions and those numbered 5 and 7 are kept as new versions; -backup version 3 is excess. The function @code{find-backup-file-name} -(@pxref{Backup Names}) is responsible for determining which backup -versions to delete, but does not delete them itself. - -@defopt delete-old-versions -If this variable is @code{t}, then saving a file deletes excess -backup versions silently. If it is @code{nil}, that means -to ask for confirmation before deleting excess backups. -Otherwise, they are not deleted at all. -@end defopt - -@defopt dired-kept-versions -This variable specifies how many of the newest backup versions to keep -in the Dired command @kbd{.} (@code{dired-clean-directory}). That's the -same thing @code{kept-new-versions} specifies when you make a new backup -file. The default is@tie{}2. -@end defopt - -@node Backup Names -@subsection Naming Backup Files - - The functions in this section are documented mainly because you can -customize the naming conventions for backup files by redefining them. -If you change one, you probably need to change the rest. - -@defun backup-file-name-p filename -This function returns a non-@code{nil} value if @var{filename} is a -possible name for a backup file. It just checks the name, not whether -a file with the name @var{filename} exists. - -@smallexample -@group -(backup-file-name-p "foo") - @result{} nil -@end group -@group -(backup-file-name-p "foo~") - @result{} 3 -@end group -@end smallexample - -The standard definition of this function is as follows: - -@smallexample -@group -(defun backup-file-name-p (file) - "Return non-nil if FILE is a backup file \ -name (numeric or not)..." - (string-match "~\\'" file)) -@end group -@end smallexample - -@noindent -Thus, the function returns a non-@code{nil} value if the file name ends -with a @samp{~}. (We use a backslash to split the documentation -string's first line into two lines in the text, but produce just one -line in the string itself.) - -This simple expression is placed in a separate function to make it easy -to redefine for customization. -@end defun - -@defun make-backup-file-name filename -This function returns a string that is the name to use for a -non-numbered backup file for file @var{filename}. On Unix, this is just -@var{filename} with a tilde appended. - -The standard definition of this function, on most operating systems, is -as follows: - -@smallexample -@group -(defun make-backup-file-name (file) - "Create the non-numeric backup file name for FILE..." - (concat file "~")) -@end group -@end smallexample - -You can change the backup-file naming convention by redefining this -function. The following example redefines @code{make-backup-file-name} -to prepend a @samp{.} in addition to appending a tilde: - -@smallexample -@group -(defun make-backup-file-name (filename) - (expand-file-name - (concat "." (file-name-nondirectory filename) "~") - (file-name-directory filename))) -@end group - -@group -(make-backup-file-name "backups.texi") - @result{} ".backups.texi~" -@end group -@end smallexample - -Some parts of Emacs, including some Dired commands, assume that backup -file names end with @samp{~}. If you do not follow that convention, it -will not cause serious problems, but these commands may give -less-than-desirable results. -@end defun - -@defun find-backup-file-name filename -This function computes the file name for a new backup file for -@var{filename}. It may also propose certain existing backup files for -deletion. @code{find-backup-file-name} returns a list whose @sc{car} is -the name for the new backup file and whose @sc{cdr} is a list of backup -files whose deletion is proposed. The value can also be @code{nil}, -which means not to make a backup. - -Two variables, @code{kept-old-versions} and @code{kept-new-versions}, -determine which backup versions should be kept. This function keeps -those versions by excluding them from the @sc{cdr} of the value. -@xref{Numbered Backups}. - -In this example, the value says that @file{~rms/foo.~5~} is the name -to use for the new backup file, and @file{~rms/foo.~3~} is an ``excess'' -version that the caller should consider deleting now. - -@smallexample -@group -(find-backup-file-name "~rms/foo") - @result{} ("~rms/foo.~5~" "~rms/foo.~3~") -@end group -@end smallexample -@end defun - -@c Emacs 19 feature -@defun file-newest-backup filename -This function returns the name of the most recent backup file for -@var{filename}, or @code{nil} if that file has no backup files. - -Some file comparison commands use this function so that they can -automatically compare a file with its most recent backup. -@end defun - -@node Auto-Saving -@section Auto-Saving -@c @cindex auto-saving Lots of symbols starting with auto-save here. - - Emacs periodically saves all files that you are visiting; this is -called @dfn{auto-saving}. Auto-saving prevents you from losing more -than a limited amount of work if the system crashes. By default, -auto-saves happen every 300 keystrokes, or after around 30 seconds of -idle time. @xref{Auto Save, Auto Save, Auto-Saving: Protection Against -Disasters, emacs, The GNU Emacs Manual}, for information on auto-save -for users. Here we describe the functions used to implement auto-saving -and the variables that control them. - -@defvar buffer-auto-save-file-name -This buffer-local variable is the name of the file used for -auto-saving the current buffer. It is @code{nil} if the buffer -should not be auto-saved. - -@example -@group -buffer-auto-save-file-name - @result{} "/xcssun/users/rms/lewis/#backups.texi#" -@end group -@end example -@end defvar - -@deffn Command auto-save-mode arg -When used interactively without an argument, this command is a toggle -switch: it turns on auto-saving of the current buffer if it is off, -and vice versa. When called from Lisp with no argument, it turns -auto-saving on. With an argument @var{arg}, it turns auto-saving on -if the value of @var{arg} is @code{t}, a nonempty list, or a positive -integer; otherwise, it turns auto-saving off. -@end deffn - -@defun auto-save-file-name-p filename -This function returns a non-@code{nil} value if @var{filename} is a -string that could be the name of an auto-save file. It assumes -the usual naming convention for auto-save files: a name that -begins and ends with hash marks (@samp{#}) is a possible auto-save file -name. The argument @var{filename} should not contain a directory part. - -@example -@group -(make-auto-save-file-name) - @result{} "/xcssun/users/rms/lewis/#backups.texi#" -@end group -@group -(auto-save-file-name-p "#backups.texi#") - @result{} 0 -@end group -@group -(auto-save-file-name-p "backups.texi") - @result{} nil -@end group -@end example - -The standard definition of this function is as follows: - -@example -@group -(defun auto-save-file-name-p (filename) - "Return non-nil if FILENAME can be yielded by..." - (string-match "^#.*#$" filename)) -@end group -@end example - -This function exists so that you can customize it if you wish to -change the naming convention for auto-save files. If you redefine it, -be sure to redefine the function @code{make-auto-save-file-name} -correspondingly. -@end defun - -@defun make-auto-save-file-name -This function returns the file name to use for auto-saving the current -buffer. This is just the file name with hash marks (@samp{#}) prepended -and appended to it. This function does not look at the variable -@code{auto-save-visited-file-name} (described below); callers of this -function should check that variable first. - -@example -@group -(make-auto-save-file-name) - @result{} "/xcssun/users/rms/lewis/#backups.texi#" -@end group -@end example - -Here is a simplified version of the standard definition of this -function: - -@example -@group -(defun make-auto-save-file-name () - "Return file name to use for auto-saves \ -of current buffer.." - (if buffer-file-name -@end group -@group - (concat - (file-name-directory buffer-file-name) - "#" - (file-name-nondirectory buffer-file-name) - "#") - (expand-file-name - (concat "#%" (buffer-name) "#")))) -@end group -@end example - -This exists as a separate function so that you can redefine it to -customize the naming convention for auto-save files. Be sure to -change @code{auto-save-file-name-p} in a corresponding way. -@end defun - -@defopt auto-save-visited-file-name -If this variable is non-@code{nil}, Emacs auto-saves buffers in -the files they are visiting. That is, the auto-save is done in the same -file that you are editing. Normally, this variable is @code{nil}, so -auto-save files have distinct names that are created by -@code{make-auto-save-file-name}. - -When you change the value of this variable, the new value does not take -effect in an existing buffer until the next time auto-save mode is -reenabled in it. If auto-save mode is already enabled, auto-saves -continue to go in the same file name until @code{auto-save-mode} is -called again. -@end defopt - -@defun recent-auto-save-p -This function returns @code{t} if the current buffer has been -auto-saved since the last time it was read in or saved. -@end defun - -@defun set-buffer-auto-saved -This function marks the current buffer as auto-saved. The buffer will -not be auto-saved again until the buffer text is changed again. The -function returns @code{nil}. -@end defun - -@defopt auto-save-interval -The value of this variable specifies how often to do auto-saving, in -terms of number of input events. Each time this many additional input -events are read, Emacs does auto-saving for all buffers in which that is -enabled. Setting this to zero disables autosaving based on the -number of characters typed. -@end defopt - -@defopt auto-save-timeout -The value of this variable is the number of seconds of idle time that -should cause auto-saving. Each time the user pauses for this long, -Emacs does auto-saving for all buffers in which that is enabled. (If -the current buffer is large, the specified timeout is multiplied by a -factor that increases as the size increases; for a million-byte -buffer, the factor is almost 4.) - -If the value is zero or @code{nil}, then auto-saving is not done as a -result of idleness, only after a certain number of input events as -specified by @code{auto-save-interval}. -@end defopt - -@defvar auto-save-hook -This normal hook is run whenever an auto-save is about to happen. -@end defvar - -@defopt auto-save-default -If this variable is non-@code{nil}, buffers that are visiting files -have auto-saving enabled by default. Otherwise, they do not. -@end defopt - -@deffn Command do-auto-save &optional no-message current-only -This function auto-saves all buffers that need to be auto-saved. It -saves all buffers for which auto-saving is enabled and that have been -changed since the previous auto-save. - -If any buffers are auto-saved, @code{do-auto-save} normally displays a -message saying @samp{Auto-saving...} in the echo area while -auto-saving is going on. However, if @var{no-message} is -non-@code{nil}, the message is inhibited. - -If @var{current-only} is non-@code{nil}, only the current buffer -is auto-saved. -@end deffn - -@defun delete-auto-save-file-if-necessary &optional force -This function deletes the current buffer's auto-save file if -@code{delete-auto-save-files} is non-@code{nil}. It is called every -time a buffer is saved. - -Unless @var{force} is non-@code{nil}, this function only deletes the -file if it was written by the current Emacs session since the last -true save. -@end defun - -@defopt delete-auto-save-files -This variable is used by the function -@code{delete-auto-save-file-if-necessary}. If it is non-@code{nil}, -Emacs deletes auto-save files when a true save is done (in the visited -file). This saves disk space and unclutters your directory. -@end defopt - -@defun rename-auto-save-file -This function adjusts the current buffer's auto-save file name if the -visited file name has changed. It also renames an existing auto-save -file, if it was made in the current Emacs session. If the visited -file name has not changed, this function does nothing. -@end defun - -@defvar buffer-saved-size -The value of this buffer-local variable is the length of the current -buffer, when it was last read in, saved, or auto-saved. This is -used to detect a substantial decrease in size, and turn off auto-saving -in response. - -If it is @minus{}1, that means auto-saving is temporarily shut off in -this buffer due to a substantial decrease in size. Explicitly saving -the buffer stores a positive value in this variable, thus reenabling -auto-saving. Turning auto-save mode off or on also updates this -variable, so that the substantial decrease in size is forgotten. - -If it is @minus{}2, that means this buffer should disregard changes in -buffer size; in particular, it should not shut off auto-saving -temporarily due to changes in buffer size. -@end defvar - -@defvar auto-save-list-file-name -This variable (if non-@code{nil}) specifies a file for recording the -names of all the auto-save files. Each time Emacs does auto-saving, it -writes two lines into this file for each buffer that has auto-saving -enabled. The first line gives the name of the visited file (it's empty -if the buffer has none), and the second gives the name of the auto-save -file. - -When Emacs exits normally, it deletes this file; if Emacs crashes, you -can look in the file to find all the auto-save files that might contain -work that was otherwise lost. The @code{recover-session} command uses -this file to find them. - -The default name for this file specifies your home directory and starts -with @samp{.saves-}. It also contains the Emacs process @acronym{ID} and the -host name. -@end defvar - -@defopt auto-save-list-file-prefix -After Emacs reads your init file, it initializes -@code{auto-save-list-file-name} (if you have not already set it -non-@code{nil}) based on this prefix, adding the host name and process -ID. If you set this to @code{nil} in your init file, then Emacs does -not initialize @code{auto-save-list-file-name}. -@end defopt - -@node Reverting -@section Reverting - - If you have made extensive changes to a file and then change your mind -about them, you can get rid of them by reading in the previous version -of the file with the @code{revert-buffer} command. @xref{Reverting, , -Reverting a Buffer, emacs, The GNU Emacs Manual}. - -@deffn Command revert-buffer &optional ignore-auto noconfirm preserve-modes -This command replaces the buffer text with the text of the visited -file on disk. This action undoes all changes since the file was visited -or saved. - -By default, if the latest auto-save file is more recent than the visited -file, and the argument @var{ignore-auto} is @code{nil}, -@code{revert-buffer} asks the user whether to use that auto-save -instead. When you invoke this command interactively, @var{ignore-auto} -is @code{t} if there is no numeric prefix argument; thus, the -interactive default is not to check the auto-save file. - -Normally, @code{revert-buffer} asks for confirmation before it changes -the buffer; but if the argument @var{noconfirm} is non-@code{nil}, -@code{revert-buffer} does not ask for confirmation. - -Normally, this command reinitializes the buffer's major and minor modes -using @code{normal-mode}. But if @var{preserve-modes} is -non-@code{nil}, the modes remain unchanged. - -Reverting tries to preserve marker positions in the buffer by using the -replacement feature of @code{insert-file-contents}. If the buffer -contents and the file contents are identical before the revert -operation, reverting preserves all the markers. If they are not -identical, reverting does change the buffer; in that case, it preserves -the markers in the unchanged text (if any) at the beginning and end of -the buffer. Preserving any additional markers would be problematical. -@end deffn - -@defvar revert-buffer-in-progress-p -@code{revert-buffer} binds this variable to a non-@code{nil} value -while it is working. -@end defvar - -You can customize how @code{revert-buffer} does its work by setting -the variables described in the rest of this section. - -@defopt revert-without-query -This variable holds a list of files that should be reverted without -query. The value is a list of regular expressions. If the visited file -name matches one of these regular expressions, and the file has changed -on disk but the buffer is not modified, then @code{revert-buffer} -reverts the file without asking the user for confirmation. -@end defopt - - Some major modes customize @code{revert-buffer} by making -buffer-local bindings for these variables: - -@defvar revert-buffer-function -@anchor{Definition of revert-buffer-function} -The value of this variable is the function to use to revert this -buffer. If non-@code{nil}, it should be a function with two optional -arguments to do the work of reverting. The two optional arguments, -@var{ignore-auto} and @var{noconfirm}, are the arguments that -@code{revert-buffer} received. If the value is @code{nil}, reverting -works the usual way. - -Modes such as Dired mode, in which the text being edited does not -consist of a file's contents but can be regenerated in some other -fashion, can give this variable a buffer-local value that is a function to -regenerate the contents. -@end defvar - -@defvar revert-buffer-insert-file-contents-function -The value of this variable, if non-@code{nil}, specifies the function to use to -insert the updated contents when reverting this buffer. The function -receives two arguments: first the file name to use; second, @code{t} if -the user has asked to read the auto-save file. - -The reason for a mode to set this variable instead of -@code{revert-buffer-function} is to avoid duplicating or replacing the -rest of what @code{revert-buffer} does: asking for confirmation, -clearing the undo list, deciding the proper major mode, and running the -hooks listed below. -@end defvar - -@defvar before-revert-hook -This normal hook is run by @code{revert-buffer} before -inserting the modified contents---but only if -@code{revert-buffer-function} is @code{nil}. -@end defvar - -@defvar after-revert-hook -This normal hook is run by @code{revert-buffer} after inserting -the modified contents---but only if @code{revert-buffer-function} is -@code{nil}. -@end defvar - -@c FIXME? Move this section from arevert-xtra to here? -@defvar buffer-stale-function -The value of this variable, if non-@code{nil}, specifies a function -to call to check whether a non-file buffer needs reverting -@iftex -(@pxref{Supporting additional buffers,,, emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Supporting additional buffers,,, emacs}). -@end ifnottex -@end defvar - diff --git a/doc/lispref/book-spine.texi b/doc/lispref/book-spine.texi deleted file mode 100644 index 721416316d2..00000000000 --- a/doc/lispref/book-spine.texi +++ /dev/null @@ -1,27 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename book-spine -@settitle book-spine -@c %**end of header - -@include emacsver.texi - -@c need dot in text so first space command works! -. -@sp 7 - -@center @titlefont{GNU Emacs Lisp Reference Manual} -@sp 5 -@center GNU -@center Emacs Version @value{EMACSVER} -@center for Unix Users -@sp 5 - -@center by -@center Bil Lewis, -@center Dan LaLiberte, -@center the GNU Manual Group, -@center et al. -@sp 5 -@center Free Software Foundation -@bye diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi deleted file mode 100644 index fa0cb117772..00000000000 --- a/doc/lispref/buffers.texi +++ /dev/null @@ -1,1238 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/buffers -@node Buffers, Windows, Backups and Auto-Saving, Top -@chapter Buffers -@cindex buffer - - A @dfn{buffer} is a Lisp object containing text to be edited. Buffers -are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. While several buffers may -exist at one time, only one buffer is designated the @dfn{current -buffer} at any time. Most editing commands act on the contents of the -current buffer. Each buffer, including the current buffer, may or may -not be displayed in any windows. - -@menu -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so that primitives will access its contents. -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - "behind Emacs's back". -* Read Only Buffers:: Modifying text is not allowed in a read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Indirect Buffers:: An indirect buffer shares text with some other buffer. -* Swapping Text:: Swapping text between two buffers. -* Buffer Gap:: The gap in the buffer. -@end menu - -@node Buffer Basics -@comment node-name, next, previous, up -@section Buffer Basics - -@ifnottex - A @dfn{buffer} is a Lisp object containing text to be edited. Buffers -are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. Although several buffers -normally exist, only one buffer is designated the @dfn{current -buffer} at any time. Most editing commands act on the contents of the -current buffer. Each buffer, including the current buffer, may or may -not be displayed in any windows. -@end ifnottex - - Buffers in Emacs editing are objects that have distinct names and hold -text that can be edited. Buffers appear to Lisp programs as a special -data type. You can think of the contents of a buffer as a string that -you can extend; insertions and deletions may occur in any part of the -buffer. @xref{Text}. - - A Lisp buffer object contains numerous pieces of information. Some of -this information is directly accessible to the programmer through -variables, while other information is accessible only through -special-purpose functions. For example, the visited file name is -directly accessible through a variable, while the value of point is -accessible only through a primitive function. - - Buffer-specific information that is directly accessible is stored in -@dfn{buffer-local} variable bindings, which are variable values that are -effective only in a particular buffer. This feature allows each buffer -to override the values of certain variables. Most major modes override -variables such as @code{fill-column} or @code{comment-column} in this -way. For more information about buffer-local variables and functions -related to them, see @ref{Buffer-Local Variables}. - - For functions and variables related to visiting files in buffers, see -@ref{Visiting Files} and @ref{Saving Buffers}. For functions and -variables related to the display of buffers in windows, see -@ref{Buffers and Windows}. - -@defun bufferp object -This function returns @code{t} if @var{object} is a buffer, -@code{nil} otherwise. -@end defun - -@node Current Buffer -@section The Current Buffer -@cindex selecting a buffer -@cindex changing to another buffer -@cindex current buffer - - There are, in general, many buffers in an Emacs session. At any -time, one of them is designated the @dfn{current buffer}---the buffer -in which most editing takes place. Most of the primitives for -examining or changing text operate implicitly on the current buffer -(@pxref{Text}). - - Normally, the buffer displayed in the selected window is the current -buffer, but this is not always so: a Lisp program can temporarily -designate any buffer as current in order to operate on its contents, -without changing what is displayed on the screen. The most basic -function for designating a current buffer is @code{set-buffer}. - -@defun current-buffer -This function returns the current buffer. - -@example -@group -(current-buffer) - @result{} # -@end group -@end example -@end defun - -@defun set-buffer buffer-or-name -This function makes @var{buffer-or-name} the current buffer. -@var{buffer-or-name} must be an existing buffer or the name of an -existing buffer. The return value is the buffer made current. - -This function does not display the buffer in any window, so the user -cannot necessarily see the buffer. But Lisp programs will now operate -on it. -@end defun - - When an editing command returns to the editor command loop, Emacs -automatically calls @code{set-buffer} on the buffer shown in the -selected window. This is to prevent confusion: it ensures that the -buffer that the cursor is in, when Emacs reads a command, is the -buffer to which that command applies (@pxref{Command Loop}). Thus, -you should not use @code{set-buffer} to switch visibly to a different -buffer; for that, use the functions described in @ref{Switching -Buffers}. - - When writing a Lisp function, do @emph{not} rely on this behavior of -the command loop to restore the current buffer after an operation. -Editing commands can also be called as Lisp functions by other -programs, not just from the command loop; it is convenient for the -caller if the subroutine does not change which buffer is current -(unless, of course, that is the subroutine's purpose). - - To operate temporarily on another buffer, put the @code{set-buffer} -within a @code{save-current-buffer} form. Here, as an example, is a -simplified version of the command @code{append-to-buffer}: - -@example -@group -(defun append-to-buffer (buffer start end) - "Append the text of the region to BUFFER." - (interactive "BAppend to buffer: \nr") - (let ((oldbuf (current-buffer))) - (save-current-buffer - (set-buffer (get-buffer-create buffer)) - (insert-buffer-substring oldbuf start end)))) -@end group -@end example - -@noindent -Here, we bind a local variable to record the current buffer, and then -@code{save-current-buffer} arranges to make it current again later. -Next, @code{set-buffer} makes the specified buffer current, and -@code{insert-buffer-substring} copies the string from the original -buffer to the specified (and now current) buffer. - - Alternatively, we can use the @code{with-current-buffer} macro: - -@example -@group -(defun append-to-buffer (buffer start end) - "Append the text of the region to BUFFER." - (interactive "BAppend to buffer: \nr") - (let ((oldbuf (current-buffer))) - (with-current-buffer (get-buffer-create buffer) - (insert-buffer-substring oldbuf start end)))) -@end group -@end example - - In either case, if the buffer appended to happens to be displayed in -some window, the next redisplay will show how its text has changed. -If it is not displayed in any window, you will not see the change -immediately on the screen. The command causes the buffer to become -current temporarily, but does not cause it to be displayed. - - If you make local bindings (with @code{let} or function arguments) -for a variable that may also have buffer-local bindings, make sure -that the same buffer is current at the beginning and at the end of the -local binding's scope. Otherwise you might bind it in one buffer and -unbind it in another! - - Do not rely on using @code{set-buffer} to change the current buffer -back, because that won't do the job if a quit happens while the wrong -buffer is current. For instance, in the previous example, it would -have been wrong to do this: - -@example -@group - (let ((oldbuf (current-buffer))) - (set-buffer (get-buffer-create buffer)) - (insert-buffer-substring oldbuf start end) - (set-buffer oldbuf)) -@end group -@end example - -@noindent -Using @code{save-current-buffer} or @code{with-current-buffer}, as we -did, correctly handles quitting, errors, and @code{throw}, as well as -ordinary evaluation. - -@defspec save-current-buffer body@dots{} -The @code{save-current-buffer} special form saves the identity of the -current buffer, evaluates the @var{body} forms, and finally restores -that buffer as current. The return value is the value of the last -form in @var{body}. The current buffer is restored even in case of an -abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). - -If the buffer that used to be current has been killed by the time of -exit from @code{save-current-buffer}, then it is not made current again, -of course. Instead, whichever buffer was current just before exit -remains current. -@end defspec - -@defmac with-current-buffer buffer-or-name body@dots{} -The @code{with-current-buffer} macro saves the identity of the current -buffer, makes @var{buffer-or-name} current, evaluates the @var{body} -forms, and finally restores the current buffer. @var{buffer-or-name} -must specify an existing buffer or the name of an existing buffer. - -The return value is the value of the last form in @var{body}. The -current buffer is restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). -@end defmac - -@defmac with-temp-buffer body@dots{} -@anchor{Definition of with-temp-buffer} -The @code{with-temp-buffer} macro evaluates the @var{body} forms -with a temporary buffer as the current buffer. It saves the identity of -the current buffer, creates a temporary buffer and makes it current, -evaluates the @var{body} forms, and finally restores the previous -current buffer while killing the temporary buffer. By default, undo -information (@pxref{Undo}) is not recorded in the buffer created by -this macro (but @var{body} can enable that, if needed). - -The return value is the value of the last form in @var{body}. You can -return the contents of the temporary buffer by using -@code{(buffer-string)} as the last form. - -The current buffer is restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). - -See also @code{with-temp-file} in @ref{Definition of with-temp-file,, -Writing to Files}. -@end defmac - -@node Buffer Names -@section Buffer Names -@cindex buffer names - - Each buffer has a unique name, which is a string. Many of the -functions that work on buffers accept either a buffer or a buffer name -as an argument. Any argument called @var{buffer-or-name} is of this -sort, and an error is signaled if it is neither a string nor a buffer. -Any argument called @var{buffer} must be an actual buffer -object, not a name. - -@cindex hidden buffers -@cindex buffers without undo information - Buffers that are ephemeral and generally uninteresting to the user -have names starting with a space, so that the @code{list-buffers} and -@code{buffer-menu} commands don't mention them (but if such a buffer -visits a file, it @strong{is} mentioned). A name starting with -space also initially disables recording undo information; see -@ref{Undo}. - -@defun buffer-name &optional buffer -This function returns the name of @var{buffer} as a string. -@var{buffer} defaults to the current buffer. - -If @code{buffer-name} returns @code{nil}, it means that @var{buffer} -has been killed. @xref{Killing Buffers}. - -@example -@group -(buffer-name) - @result{} "buffers.texi" -@end group - -@group -(setq foo (get-buffer "temp")) - @result{} # -@end group -@group -(kill-buffer foo) - @result{} nil -@end group -@group -(buffer-name foo) - @result{} nil -@end group -@group -foo - @result{} # -@end group -@end example -@end defun - -@deffn Command rename-buffer newname &optional unique -This function renames the current buffer to @var{newname}. An error -is signaled if @var{newname} is not a string. - -@c Emacs 19 feature -Ordinarily, @code{rename-buffer} signals an error if @var{newname} is -already in use. However, if @var{unique} is non-@code{nil}, it modifies -@var{newname} to make a name that is not in use. Interactively, you can -make @var{unique} non-@code{nil} with a numeric prefix argument. -(This is how the command @code{rename-uniquely} is implemented.) - -This function returns the name actually given to the buffer. -@end deffn - -@defun get-buffer buffer-or-name -This function returns the buffer specified by @var{buffer-or-name}. -If @var{buffer-or-name} is a string and there is no buffer with that -name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it -is returned as given; that is not very useful, so the argument is usually -a name. For example: - -@example -@group -(setq b (get-buffer "lewis")) - @result{} # -@end group -@group -(get-buffer b) - @result{} # -@end group -@group -(get-buffer "Frazzle-nots") - @result{} nil -@end group -@end example - -See also the function @code{get-buffer-create} in @ref{Creating Buffers}. -@end defun - -@c Emacs 19 feature -@defun generate-new-buffer-name starting-name &optional ignore -This function returns a name that would be unique for a new buffer---but -does not create the buffer. It starts with @var{starting-name}, and -produces a name not currently in use for any buffer by appending a -number inside of @samp{<@dots{}>}. It starts at 2 and keeps -incrementing the number until it is not the name of an existing buffer. - -If the optional second argument @var{ignore} is non-@code{nil}, it -should be a string, a potential buffer name. It means to consider -that potential buffer acceptable, if it is tried, even it is the name -of an existing buffer (which would normally be rejected). Thus, if -buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and -@samp{foo<4>} exist, - -@example -(generate-new-buffer-name "foo") - @result{} "foo<5>" -(generate-new-buffer-name "foo" "foo<3>") - @result{} "foo<3>" -(generate-new-buffer-name "foo" "foo<6>") - @result{} "foo<5>" -@end example - -See the related function @code{generate-new-buffer} in @ref{Creating -Buffers}. -@end defun - -@node Buffer File Name -@section Buffer File Name -@cindex visited file -@cindex buffer file name -@cindex file name of buffer - - The @dfn{buffer file name} is the name of the file that is visited in -that buffer. When a buffer is not visiting a file, its buffer file name -is @code{nil}. Most of the time, the buffer name is the same as the -nondirectory part of the buffer file name, but the buffer file name and -the buffer name are distinct and can be set independently. -@xref{Visiting Files}. - -@defun buffer-file-name &optional buffer -This function returns the absolute file name of the file that -@var{buffer} is visiting. If @var{buffer} is not visiting any file, -@code{buffer-file-name} returns @code{nil}. If @var{buffer} is not -supplied, it defaults to the current buffer. - -@example -@group -(buffer-file-name (other-buffer)) - @result{} "/usr/user/lewis/manual/files.texi" -@end group -@end example -@end defun - -@defvar buffer-file-name -This buffer-local variable contains the name of the file being visited -in the current buffer, or @code{nil} if it is not visiting a file. It -is a permanent local variable, unaffected by -@code{kill-all-local-variables}. - -@example -@group -buffer-file-name - @result{} "/usr/user/lewis/manual/buffers.texi" -@end group -@end example - -It is risky to change this variable's value without doing various other -things. Normally it is better to use @code{set-visited-file-name} (see -below); some of the things done there, such as changing the buffer name, -are not strictly necessary, but others are essential to avoid confusing -Emacs. -@end defvar - -@defvar buffer-file-truename -This buffer-local variable holds the abbreviated truename of the file -visited in the current buffer, or @code{nil} if no file is visited. -It is a permanent local, unaffected by -@code{kill-all-local-variables}. @xref{Truenames}, and -@ref{abbreviate-file-name}. -@end defvar - -@defvar buffer-file-number -This buffer-local variable holds the file number and directory device -number of the file visited in the current buffer, or @code{nil} if no -file or a nonexistent file is visited. It is a permanent local, -unaffected by @code{kill-all-local-variables}. - -The value is normally a list of the form @code{(@var{filenum} -@var{devnum})}. This pair of numbers uniquely identifies the file among -all files accessible on the system. See the function -@code{file-attributes}, in @ref{File Attributes}, for more information -about them. - -If @code{buffer-file-name} is the name of a symbolic link, then both -numbers refer to the recursive target. -@end defvar - -@defun get-file-buffer filename -This function returns the buffer visiting file @var{filename}. If -there is no such buffer, it returns @code{nil}. The argument -@var{filename}, which must be a string, is expanded (@pxref{File Name -Expansion}), then compared against the visited file names of all live -buffers. Note that the buffer's @code{buffer-file-name} must match -the expansion of @var{filename} exactly. This function will not -recognize other names for the same file. - -@example -@group -(get-file-buffer "buffers.texi") - @result{} # -@end group -@end example - -In unusual circumstances, there can be more than one buffer visiting -the same file name. In such cases, this function returns the first -such buffer in the buffer list. -@end defun - -@defun find-buffer-visiting filename &optional predicate -This is like @code{get-file-buffer}, except that it can return any -buffer visiting the file @emph{possibly under a different name}. That -is, the buffer's @code{buffer-file-name} does not need to match the -expansion of @var{filename} exactly, it only needs to refer to the -same file. If @var{predicate} is non-@code{nil}, it should be a -function of one argument, a buffer visiting @var{filename}. The -buffer is only considered a suitable return value if @var{predicate} -returns non-@code{nil}. If it can not find a suitable buffer to -return, @code{find-buffer-visiting} returns @code{nil}. -@end defun - -@deffn Command set-visited-file-name filename &optional no-query along-with-file -If @var{filename} is a non-empty string, this function changes the -name of the file visited in the current buffer to @var{filename}. (If the -buffer had no visited file, this gives it one.) The @emph{next time} -the buffer is saved it will go in the newly-specified file. - -This command marks the buffer as modified, since it does not (as far -as Emacs knows) match the contents of @var{filename}, even if it -matched the former visited file. It also renames the buffer to -correspond to the new file name, unless the new name is already in -use. - -If @var{filename} is @code{nil} or the empty string, that stands for -``no visited file''. In this case, @code{set-visited-file-name} marks -the buffer as having no visited file, without changing the buffer's -modified flag. - -Normally, this function asks the user for confirmation if there -already is a buffer visiting @var{filename}. If @var{no-query} is -non-@code{nil}, that prevents asking this question. If there already -is a buffer visiting @var{filename}, and the user confirms or -@var{query} is non-@code{nil}, this function makes the new buffer name -unique by appending a number inside of @samp{<@dots{}>} to @var{filename}. - -If @var{along-with-file} is non-@code{nil}, that means to assume that -the former visited file has been renamed to @var{filename}. In this -case, the command does not change the buffer's modified flag, nor the -buffer's recorded last file modification time as reported by -@code{visited-file-modtime} (@pxref{Modification Time}). If -@var{along-with-file} is @code{nil}, this function clears the recorded -last file modification time, after which @code{visited-file-modtime} -returns zero. - -When the function @code{set-visited-file-name} is called -interactively, it prompts for @var{filename} in the minibuffer. -@end deffn - -@defvar list-buffers-directory -This buffer-local variable specifies a string to display in a buffer -listing where the visited file name would go, for buffers that don't -have a visited file name. Dired buffers use this variable. -@end defvar - -@node Buffer Modification -@section Buffer Modification -@cindex buffer modification -@cindex modification flag (of buffer) - - Emacs keeps a flag called the @dfn{modified flag} for each buffer, to -record whether you have changed the text of the buffer. This flag is -set to @code{t} whenever you alter the contents of the buffer, and -cleared to @code{nil} when you save it. Thus, the flag shows whether -there are unsaved changes. The flag value is normally shown in the mode -line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving -Buffers}) and auto-saving (@pxref{Auto-Saving}). - - Some Lisp programs set the flag explicitly. For example, the function -@code{set-visited-file-name} sets the flag to @code{t}, because the text -does not match the newly-visited file, even if it is unchanged from the -file formerly visited. - - The functions that modify the contents of buffers are described in -@ref{Text}. - -@defun buffer-modified-p &optional buffer -This function returns @code{t} if the buffer @var{buffer} has been modified -since it was last read in from a file or saved, or @code{nil} -otherwise. If @var{buffer} is not supplied, the current buffer -is tested. -@end defun - -@defun set-buffer-modified-p flag -This function marks the current buffer as modified if @var{flag} is -non-@code{nil}, or as unmodified if the flag is @code{nil}. - -Another effect of calling this function is to cause unconditional -redisplay of the mode line for the current buffer. In fact, the -function @code{force-mode-line-update} works by doing this: - -@example -@group -(set-buffer-modified-p (buffer-modified-p)) -@end group -@end example -@end defun - -@defun restore-buffer-modified-p flag -Like @code{set-buffer-modified-p}, but does not force redisplay -of mode lines. -@end defun - -@deffn Command not-modified &optional arg -This command marks the current buffer as unmodified, and not needing -to be saved. If @var{arg} is non-@code{nil}, it marks the buffer as -modified, so that it will be saved at the next suitable occasion. -Interactively, @var{arg} is the prefix argument. - -Don't use this function in programs, since it prints a message in the -echo area; use @code{set-buffer-modified-p} (above) instead. -@end deffn - -@defun buffer-modified-tick &optional buffer -This function returns @var{buffer}'s modification-count. This is a -counter that increments every time the buffer is modified. If -@var{buffer} is @code{nil} (or omitted), the current buffer is used. -The counter can wrap around occasionally. -@end defun - -@defun buffer-chars-modified-tick &optional buffer -This function returns @var{buffer}'s character-change modification-count. -Changes to text properties leave this counter unchanged; however, each -time text is inserted or removed from the buffer, the counter is reset -to the value that would be returned by @code{buffer-modified-tick}. -By comparing the values returned by two @code{buffer-chars-modified-tick} -calls, you can tell whether a character change occurred in that buffer -in between the calls. If @var{buffer} is @code{nil} (or omitted), the -current buffer is used. -@end defun - -@node Modification Time -@comment node-name, next, previous, up -@section Buffer Modification Time -@cindex comparing file modification time -@cindex modification time of buffer - - Suppose that you visit a file and make changes in its buffer, and -meanwhile the file itself is changed on disk. At this point, saving the -buffer would overwrite the changes in the file. Occasionally this may -be what you want, but usually it would lose valuable information. Emacs -therefore checks the file's modification time using the functions -described below before saving the file. (@xref{File Attributes}, -for how to examine a file's modification time.) - -@defun verify-visited-file-modtime &optional buffer -This function compares what @var{buffer} (by default, the -current-buffer) has recorded for the modification time of its visited -file against the actual modification time of the file as recorded by the -operating system. The two should be the same unless some other process -has written the file since Emacs visited or saved it. - -The function returns @code{t} if the last actual modification time and -Emacs's recorded modification time are the same, @code{nil} otherwise. -It also returns @code{t} if the buffer has no recorded last -modification time, that is if @code{visited-file-modtime} would return -zero. - -It always returns @code{t} for buffers that are not visiting a file, -even if @code{visited-file-modtime} returns a non-zero value. For -instance, it always returns @code{t} for dired buffers. It returns -@code{t} for buffers that are visiting a file that does not exist and -never existed, but @code{nil} for file-visiting buffers whose file has -been deleted. -@end defun - -@defun clear-visited-file-modtime -This function clears out the record of the last modification time of -the file being visited by the current buffer. As a result, the next -attempt to save this buffer will not complain of a discrepancy in -file modification times. - -This function is called in @code{set-visited-file-name} and other -exceptional places where the usual test to avoid overwriting a changed -file should not be done. -@end defun - -@c Emacs 19 feature -@defun visited-file-modtime -This function returns the current buffer's recorded last file -modification time, as a list of the form @code{(@var{high} @var{low})}. -(This is the same format that @code{file-attributes} uses to return -time values; see @ref{File Attributes}.) - -If the buffer has no recorded last modification time, this function -returns zero. This case occurs, for instance, if the buffer is not -visiting a file or if the time has been explicitly cleared by -@code{clear-visited-file-modtime}. Note, however, that -@code{visited-file-modtime} returns a list for some non-file buffers -too. For instance, in a Dired buffer listing a directory, it returns -the last modification time of that directory, as recorded by Dired. - -For a new buffer visiting a not yet existing file, @var{high} is -@minus{}1 and @var{low} is 65535, that is, -@ifnottex -@w{2**16 - 1.} -@end ifnottex -@tex -@math{2^{16}-1}. -@end tex -@end defun - -@c Emacs 19 feature -@defun set-visited-file-modtime &optional time -This function updates the buffer's record of the last modification time -of the visited file, to the value specified by @var{time} if @var{time} -is not @code{nil}, and otherwise to the last modification time of the -visited file. - -If @var{time} is neither @code{nil} nor zero, it should have the form -@code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in -either case containing two integers, each of which holds 16 bits of the -time. - -This function is useful if the buffer was not read from the file -normally, or if the file itself has been changed for some known benign -reason. -@end defun - -@defun ask-user-about-supersession-threat filename -This function is used to ask a user how to proceed after an attempt to -modify an buffer visiting file @var{filename} when the file is newer -than the buffer text. Emacs detects this because the modification -time of the file on disk is newer than the last save-time of the -buffer. This means some other program has probably altered the file. - -@kindex file-supersession -Depending on the user's answer, the function may return normally, in -which case the modification of the buffer proceeds, or it may signal a -@code{file-supersession} error with data @code{(@var{filename})}, in which -case the proposed buffer modification is not allowed. - -This function is called automatically by Emacs on the proper -occasions. It exists so you can customize Emacs by redefining it. -See the file @file{userlock.el} for the standard definition. - -See also the file locking mechanism in @ref{File Locks}. -@end defun - -@node Read Only Buffers -@section Read-Only Buffers -@cindex read-only buffer -@cindex buffer, read-only - - If a buffer is @dfn{read-only}, then you cannot change its contents, -although you may change your view of the contents by scrolling and -narrowing. - - Read-only buffers are used in two kinds of situations: - -@itemize @bullet -@item -A buffer visiting a write-protected file is normally read-only. - -Here, the purpose is to inform the user that editing the buffer with the -aim of saving it in the file may be futile or undesirable. The user who -wants to change the buffer text despite this can do so after clearing -the read-only flag with @kbd{C-x C-q}. - -@item -Modes such as Dired and Rmail make buffers read-only when altering the -contents with the usual editing commands would probably be a mistake. - -The special commands of these modes bind @code{buffer-read-only} to -@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to -@code{t} around the places where they themselves change the text. -@end itemize - -@defvar buffer-read-only -This buffer-local variable specifies whether the buffer is read-only. -The buffer is read-only if this variable is non-@code{nil}. -@end defvar - -@defvar inhibit-read-only -If this variable is non-@code{nil}, then read-only buffers and, -depending on the actual value, some or all read-only characters may be -modified. Read-only characters in a buffer are those that have -non-@code{nil} @code{read-only} properties (either text properties or -overlay properties). @xref{Special Properties}, for more information -about text properties. @xref{Overlays}, for more information about -overlays and their properties. - -If @code{inhibit-read-only} is @code{t}, all @code{read-only} character -properties have no effect. If @code{inhibit-read-only} is a list, then -@code{read-only} character properties have no effect if they are members -of the list (comparison is done with @code{eq}). -@end defvar - -@deffn Command toggle-read-only &optional arg -This command toggles whether the current buffer is read-only. It is -intended for interactive use; do not use it in programs (it may have -side-effects, such as enabling View mode, and does not affect -read-only text properties). To change the read-only state of a buffer in -a program, explicitly set @code{buffer-read-only} to the proper value. -To temporarily ignore a read-only state, bind @code{inhibit-read-only}. - -If @var{arg} is non-@code{nil}, it should be a raw prefix argument. -@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if -the numeric value of that prefix argument is positive and to -@code{nil} otherwise. @xref{Prefix Command Arguments}. -@end deffn - -@defun barf-if-buffer-read-only -This function signals a @code{buffer-read-only} error if the current -buffer is read-only. @xref{Using Interactive}, for another way to -signal an error if the current buffer is read-only. -@end defun - -@node The Buffer List -@section The Buffer List -@cindex buffer list - - The @dfn{buffer list} is a list of all live buffers. The order of the -buffers in this list is based primarily on how recently each buffer has -been displayed in a window. Several functions, notably -@code{other-buffer}, use this ordering. A buffer list displayed for the -user also follows this order. - - Creating a buffer adds it to the end of the buffer list, and killing -a buffer removes it from that list. A buffer moves to the front of -this list whenever it is chosen for display in a window -(@pxref{Switching Buffers}) or a window displaying it is selected -(@pxref{Selecting Windows}). A buffer moves to the end of the list -when it is buried (see @code{bury-buffer}, below). There are no -functions available to the Lisp programmer which directly manipulate -the buffer list. - - In addition to the fundamental buffer list just described, Emacs -maintains a local buffer list for each frame, in which the buffers that -have been displayed (or had their windows selected) in that frame come -first. (This order is recorded in the frame's @code{buffer-list} frame -parameter; see @ref{Buffer Parameters}.) Buffers never displayed in -that frame come afterward, ordered according to the fundamental buffer -list. - -@defun buffer-list &optional frame -This function returns the buffer list, including all buffers, even those -whose names begin with a space. The elements are actual buffers, not -their names. - -If @var{frame} is a frame, this returns @var{frame}'s local buffer list. -If @var{frame} is @code{nil} or omitted, the fundamental buffer list is -used: the buffers appear in order of most recent display or selection, -regardless of which frames they were displayed on. - -@example -@group -(buffer-list) - @result{} (# - # # - # #) -@end group - -@group -;; @r{Note that the name of the minibuffer} -;; @r{begins with a space!} -(mapcar (function buffer-name) (buffer-list)) - @result{} ("buffers.texi" " *Minibuf-1*" - "buffer.c" "*Help*" "TAGS") -@end group -@end example -@end defun - - The list returned by @code{buffer-list} is constructed specifically; -it is not an internal Emacs data structure, and modifying it has no -effect on the order of buffers. If you want to change the order of -buffers in the fundamental buffer list, here is an easy way: - -@example -(defun reorder-buffer-list (new-list) - (while new-list - (bury-buffer (car new-list)) - (setq new-list (cdr new-list)))) -@end example - - With this method, you can specify any order for the list, but there is -no danger of losing a buffer or adding something that is not a valid -live buffer. - - To change the order or value of a specific frame's buffer list, set -that frame's @code{buffer-list} parameter with -@code{modify-frame-parameters} (@pxref{Parameter Access}). - -@defun other-buffer &optional buffer visible-ok frame -This function returns the first buffer in the buffer list other than -@var{buffer}. Usually, this is the buffer appearing in the most -recently selected window (in frame @var{frame} or else the selected -frame, @pxref{Input Focus}), aside from @var{buffer}. Buffers whose -names start with a space are not considered at all. - -If @var{buffer} is not supplied (or if it is not a live buffer), then -@code{other-buffer} returns the first buffer in the selected frame's -local buffer list. (If @var{frame} is non-@code{nil}, it returns the -first buffer in @var{frame}'s local buffer list instead.) - -If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, -then @code{other-buffer} uses that predicate to decide which buffers to -consider. It calls the predicate once for each buffer, and if the value -is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. - -@c Emacs 19 feature -If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning -a buffer visible in any window on any visible frame, except as a last -resort. If @var{visible-ok} is non-@code{nil}, then it does not matter -whether a buffer is displayed somewhere or not. - -If no suitable buffer exists, the buffer @file{*scratch*} is returned -(and created, if necessary). -@end defun - -@defun last-buffer &optional buffer visible-ok frame -This function returns the last buffer in @var{frame}'s buffer list other -than @var{BUFFER}. If @var{frame} is omitted or @code{nil}, it uses the -selected frame's buffer list. - -The argument @var{visible-ok} is handled as with @code{other-buffer}, -see above. If no suitable buffer can be found, the buffer -@file{*scratch*} is returned. -@end defun - -@deffn Command bury-buffer &optional buffer-or-name -This command puts @var{buffer-or-name} at the end of the buffer list, -without changing the order of any of the other buffers on the list. -This buffer therefore becomes the least desirable candidate for -@code{other-buffer} to return. The argument can be either a buffer -itself or the name of one. - -This functions operates on each frame's @code{buffer-list} parameter as -well as the fundamental buffer list; therefore, the buffer that you bury -will come last in the value of @code{(buffer-list @var{frame})} and in -the value of @code{(buffer-list)}. In addition, it also puts the buffer -at the end of the list of buffer of the selected window (@pxref{Window -History}) provided it is shown in that window. - -If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the -current buffer. In addition, if the current buffer is displayed in the -selected window, this makes sure that the window is either deleted or -another buffer is shown in it. More precisely, if the window is -dedicated (@pxref{Dedicated Windows}) and there are other windows on its -frame, the window is deleted. If the window is both dedicated and the -only window on its frame's terminal, the function specified by -@code{frame-auto-hide-function} (@pxref{Quitting Windows}) will deal -with the window. If the window is not dedicated to its buffer, it calls -@code{switch-to-prev-buffer} (@pxref{Window History}) to show another -buffer in that window. If @var{buffer-or-name} is displayed in some -other window, it remains displayed there. - -To replace a buffer in all the windows that display it, use -@code{replace-buffer-in-windows}, @xref{Buffers and Windows}. -@end deffn - -@deffn Command unbury-buffer -This command switches to the last buffer in the local buffer list of -the selected frame. More precisely, it calls the function -@code{switch-to-buffer} (@pxref{Switching Buffers}), to display the -buffer returned by @code{last-buffer} (see above), in the selected -window. -@end deffn - - -@node Creating Buffers -@section Creating Buffers -@cindex creating buffers -@cindex buffers, creating - - This section describes the two primitives for creating buffers. -@code{get-buffer-create} creates a buffer if it finds no existing buffer -with the specified name; @code{generate-new-buffer} always creates a new -buffer and gives it a unique name. - - Other functions you can use to create buffers include -@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and -@code{create-file-buffer} (@pxref{Visiting Files}). Starting a -subprocess can also create a buffer (@pxref{Processes}). - -@defun get-buffer-create buffer-or-name -This function returns a buffer named @var{buffer-or-name}. The buffer -returned does not become the current buffer---this function does not -change which buffer is current. - -@var{buffer-or-name} must be either a string or an existing buffer. If -it is a string and a live buffer with that name already exists, -@code{get-buffer-create} returns that buffer. If no such buffer exists, -it creates a new buffer. If @var{buffer-or-name} is a buffer instead of -a string, it is returned as given, even if it is dead. - -@example -@group -(get-buffer-create "foo") - @result{} # -@end group -@end example - -The major mode for a newly created buffer is set to Fundamental mode. -(The default value of the variable @code{major-mode} is handled at a higher -level; see @ref{Auto Major Mode}.) If the name begins with a space, the -buffer initially disables undo information recording (@pxref{Undo}). -@end defun - -@defun generate-new-buffer name -This function returns a newly created, empty buffer, but does not make -it current. The name of the buffer is generated by passing @var{name} -to the function @code{generate-new-buffer-name} (@pxref{Buffer -Names}). Thus, if there is no buffer named @var{name}, then that is -the name of the new buffer; if that name is in use, a suffix of the -form @samp{<@var{n}>}, where @var{n} is an integer, is appended to -@var{name}. - -An error is signaled if @var{name} is not a string. - -@example -@group -(generate-new-buffer "bar") - @result{} # -@end group -@group -(generate-new-buffer "bar") - @result{} #> -@end group -@group -(generate-new-buffer "bar") - @result{} #> -@end group -@end example - -The major mode for the new buffer is set to Fundamental mode. The default -value of the variable @code{major-mode} is handled at a higher level. -@xref{Auto Major Mode}. -@end defun - -@node Killing Buffers -@section Killing Buffers -@cindex killing buffers -@cindex buffers, killing - - @dfn{Killing a buffer} makes its name unknown to Emacs and makes the -memory space it occupied available for other use. - - The buffer object for the buffer that has been killed remains in -existence as long as anything refers to it, but it is specially marked -so that you cannot make it current or display it. Killed buffers retain -their identity, however; if you kill two distinct buffers, they remain -distinct according to @code{eq} although both are dead. - - If you kill a buffer that is current or displayed in a window, Emacs -automatically selects or displays some other buffer instead. This -means that killing a buffer can change the current buffer. Therefore, -when you kill a buffer, you should also take the precautions -associated with changing the current buffer (unless you happen to know -that the buffer being killed isn't current). @xref{Current Buffer}. - - If you kill a buffer that is the base buffer of one or more indirect -@iftex -buffers, -@end iftex -@ifnottex -buffers (@pxref{Indirect Buffers}), -@end ifnottex -the indirect buffers are automatically killed as well. - -@cindex live buffer - The @code{buffer-name} of a buffer is @code{nil} if, and only if, -the buffer is killed. A buffer that has not been killed is called a -@dfn{live} buffer. To test whether a buffer is live or killed, use -the function @code{buffer-live-p} (see below). - -@deffn Command kill-buffer &optional buffer-or-name -This function kills the buffer @var{buffer-or-name}, freeing all its -memory for other uses or to be returned to the operating system. If -@var{buffer-or-name} is @code{nil} or omitted, it kills the current -buffer. - -Any processes that have this buffer as the @code{process-buffer} are -sent the @code{SIGHUP} (``hangup'') signal, which normally causes them -to terminate. @xref{Signals to Processes}. - -If the buffer is visiting a file and contains unsaved changes, -@code{kill-buffer} asks the user to confirm before the buffer is killed. -It does this even if not called interactively. To prevent the request -for confirmation, clear the modified flag before calling -@code{kill-buffer}. @xref{Buffer Modification}. - -This function calls @code{replace-buffer-in-windows} for cleaning up -all windows currently displaying the buffer to be killed. - -Killing a buffer that is already dead has no effect. - -This function returns @code{t} if it actually killed the buffer. It -returns @code{nil} if the user refuses to confirm or if -@var{buffer-or-name} was already dead. - -@smallexample -(kill-buffer "foo.unchanged") - @result{} t -(kill-buffer "foo.changed") - ----------- Buffer: Minibuffer ---------- -Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} ----------- Buffer: Minibuffer ---------- - - @result{} t -@end smallexample -@end deffn - -@defvar kill-buffer-query-functions -After confirming unsaved changes, @code{kill-buffer} calls the functions -in the list @code{kill-buffer-query-functions}, in order of appearance, -with no arguments. The buffer being killed is the current buffer when -they are called. The idea of this feature is that these functions will -ask for confirmation from the user. If any of them returns @code{nil}, -@code{kill-buffer} spares the buffer's life. -@end defvar - -@defvar kill-buffer-hook -This is a normal hook run by @code{kill-buffer} after asking all the -questions it is going to ask, just before actually killing the buffer. -The buffer to be killed is current when the hook functions run. -@xref{Hooks}. This variable is a permanent local, so its local binding -is not cleared by changing major modes. -@end defvar - -@defopt buffer-offer-save -This variable, if non-@code{nil} in a particular buffer, tells -@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the -second optional argument to that function is @code{t}) to offer to -save that buffer, just as they offer to save file-visiting buffers. -@xref{Definition of save-some-buffers}. The variable -@code{buffer-offer-save} automatically becomes buffer-local when set -for any reason. @xref{Buffer-Local Variables}. -@end defopt - -@defvar buffer-save-without-query -This variable, if non-@code{nil} in a particular buffer, tells -@code{save-buffers-kill-emacs} and @code{save-some-buffers} to save -this buffer (if it's modified) without asking the user. The variable -automatically becomes buffer-local when set for any reason. -@end defvar - -@defun buffer-live-p object -This function returns @code{t} if @var{object} is a live buffer (a -buffer which has not been killed), @code{nil} otherwise. -@end defun - -@node Indirect Buffers -@section Indirect Buffers -@cindex indirect buffers -@cindex base buffer - - An @dfn{indirect buffer} shares the text of some other buffer, which -is called the @dfn{base buffer} of the indirect buffer. In some ways it -is the analogue, for buffers, of a symbolic link among files. The base -buffer may not itself be an indirect buffer. - - The text of the indirect buffer is always identical to the text of its -base buffer; changes made by editing either one are visible immediately -in the other. This includes the text properties as well as the characters -themselves. - - In all other respects, the indirect buffer and its base buffer are -completely separate. They have different names, independent values of -point, independent narrowing, independent markers and overlays (though -inserting or deleting text in either buffer relocates the markers and -overlays for both), independent major modes, and independent -buffer-local variable bindings. - - An indirect buffer cannot visit a file, but its base buffer can. If -you try to save the indirect buffer, that actually saves the base -buffer. - - Killing an indirect buffer has no effect on its base buffer. Killing -the base buffer effectively kills the indirect buffer in that it cannot -ever again be the current buffer. - -@deffn Command make-indirect-buffer base-buffer name &optional clone -This creates and returns an indirect buffer named @var{name} whose -base buffer is @var{base-buffer}. The argument @var{base-buffer} may -be a live buffer or the name (a string) of an existing buffer. If -@var{name} is the name of an existing buffer, an error is signaled. - -If @var{clone} is non-@code{nil}, then the indirect buffer originally -shares the ``state'' of @var{base-buffer} such as major mode, minor -modes, buffer local variables and so on. If @var{clone} is omitted -or @code{nil} the indirect buffer's state is set to the default state -for new buffers. - -If @var{base-buffer} is an indirect buffer, its base buffer is used as -the base for the new buffer. If, in addition, @var{clone} is -non-@code{nil}, the initial state is copied from the actual base -buffer, not from @var{base-buffer}. -@end deffn - -@deffn Command clone-indirect-buffer newname display-flag &optional norecord -This function creates and returns a new indirect buffer that shares -the current buffer's base buffer and copies the rest of the current -buffer's attributes. (If the current buffer is not indirect, it is -used as the base buffer.) - -If @var{display-flag} is non-@code{nil}, that means to display the new -buffer by calling @code{pop-to-buffer}. If @var{norecord} is -non-@code{nil}, that means not to put the new buffer to the front of -the buffer list. -@end deffn - -@defun buffer-base-buffer &optional buffer -This function returns the base buffer of @var{buffer}, which defaults -to the current buffer. If @var{buffer} is not indirect, the value is -@code{nil}. Otherwise, the value is another buffer, which is never an -indirect buffer. -@end defun - -@node Swapping Text -@section Swapping Text Between Two Buffers -@cindex swap text between buffers -@cindex virtual buffers - - Specialized modes sometimes need to let the user access from the -same buffer several vastly different types of text. For example, you -may need to display a summary of the buffer text, in addition to -letting the user access the text itself. - - This could be implemented with multiple buffers (kept in sync when -the user edits the text), or with narrowing (@pxref{Narrowing}). But -these alternatives might sometimes become tedious or prohibitively -expensive, especially if each type of text requires expensive -buffer-global operations in order to provide correct display and -editing commands. - - Emacs provides another facility for such modes: you can quickly swap -buffer text between two buffers with @code{buffer-swap-text}. This -function is very fast because it doesn't move any text, it only -changes the internal data structures of the buffer object to point to -a different chunk of text. Using it, you can pretend that a group of -two or more buffers are actually a single virtual buffer that holds -the contents of all the individual buffers together. - -@defun buffer-swap-text buffer -This function swaps the text of the current buffer and that of its -argument @var{buffer}. It signals an error if one of the two buffers -is an indirect buffer (@pxref{Indirect Buffers}) or is a base buffer -of an indirect buffer. - -All the buffer properties that are related to the buffer text are -swapped as well: the positions of point and mark, all the markers, the -overlays, the text properties, the undo list, the value of the -@code{enable-multibyte-characters} flag (@pxref{Text Representations, -enable-multibyte-characters}), etc. -@end defun - - If you use @code{buffer-swap-text} on a file-visiting buffer, you -should set up a hook to save the buffer's original text rather than -what it was swapped with. @code{write-region-annotate-functions} -works for this purpose. You should probably set -@code{buffer-saved-size} to @minus{}2 in the buffer, so that changes -in the text it is swapped with will not interfere with auto-saving. - -@node Buffer Gap -@section The Buffer Gap - - Emacs buffers are implemented using an invisible @dfn{gap} to make -insertion and deletion faster. Insertion works by filling in part of -the gap, and deletion adds to the gap. Of course, this means that the -gap must first be moved to the locus of the insertion or deletion. -Emacs moves the gap only when you try to insert or delete. This is why -your first editing command in one part of a large buffer, after -previously editing in another far-away part, sometimes involves a -noticeable delay. - - This mechanism works invisibly, and Lisp code should never be affected -by the gap's current location, but these functions are available for -getting information about the gap status. - -@defun gap-position -This function returns the current gap position in the current buffer. -@end defun - -@defun gap-size -This function returns the current gap size of the current buffer. -@end defun - diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi deleted file mode 100644 index a6dfbe2f8ee..00000000000 --- a/doc/lispref/commands.texi +++ /dev/null @@ -1,3437 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/commands -@node Command Loop, Keymaps, Minibuffers, Top -@chapter Command Loop -@cindex editor command loop -@cindex command loop - - When you run Emacs, it enters the @dfn{editor command loop} almost -immediately. This loop reads key sequences, executes their definitions, -and displays the results. In this chapter, we describe how these things -are done, and the subroutines that allow Lisp programs to do them. - -@menu -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Distinguish Interactive:: Making a command distinguish interactive calls. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Adjusting Point:: Adjustment of point after a command. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Special Events:: Events processed immediately and individually. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. -@end menu - -@node Command Overview -@section Command Loop Overview - - The first thing the command loop must do is read a key sequence, -which is a sequence of input events that translates into a command. -It does this by calling the function @code{read-key-sequence}. Lisp -programs can also call this function (@pxref{Key Sequence Input}). -They can also read input at a lower level with @code{read-key} or -@code{read-event} (@pxref{Reading One Event}), or discard pending -input with @code{discard-input} (@pxref{Event Input Misc}). - - The key sequence is translated into a command through the currently -active keymaps. @xref{Key Lookup}, for information on how this is done. -The result should be a keyboard macro or an interactively callable -function. If the key is @kbd{M-x}, then it reads the name of another -command, which it then calls. This is done by the command -@code{execute-extended-command} (@pxref{Interactive Call}). - - Prior to executing the command, Emacs runs @code{undo-boundary} to -create an undo boundary. @xref{Maintaining Undo}. - - To execute a command, Emacs first reads its arguments by calling -@code{command-execute} (@pxref{Interactive Call}). For commands -written in Lisp, the @code{interactive} specification says how to read -the arguments. This may use the prefix argument (@pxref{Prefix -Command Arguments}) or may read with prompting in the minibuffer -(@pxref{Minibuffers}). For example, the command @code{find-file} has -an @code{interactive} specification which says to read a file name -using the minibuffer. The function body of @code{find-file} does not -use the minibuffer, so if you call @code{find-file} as a function from -Lisp code, you must supply the file name string as an ordinary Lisp -function argument. - - If the command is a keyboard macro (i.e.@: a string or vector), -Emacs executes it using @code{execute-kbd-macro} (@pxref{Keyboard -Macros}). - -@defvar pre-command-hook -This normal hook is run by the editor command loop before it executes -each command. At that time, @code{this-command} contains the command -that is about to run, and @code{last-command} describes the previous -command. @xref{Command Loop Info}. -@end defvar - -@defvar post-command-hook -This normal hook is run by the editor command loop after it executes -each command (including commands terminated prematurely by quitting or -by errors). At that time, @code{this-command} refers to the command -that just ran, and @code{last-command} refers to the command before -that. - -This hook is also run when Emacs first enters the command loop (at -which point @code{this-command} and @code{last-command} are both -@code{nil}). -@end defvar - - Quitting is suppressed while running @code{pre-command-hook} and -@code{post-command-hook}. If an error happens while executing one of -these hooks, it does not terminate execution of the hook; instead -the error is silenced and the function in which the error occurred -is removed from the hook. - - A request coming into the Emacs server (@pxref{Emacs Server,,, -emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard -command does. - -@node Defining Commands -@section Defining Commands -@cindex defining commands -@cindex commands, defining -@cindex functions, making them interactive -@cindex interactive function - - The special form @code{interactive} turns a Lisp function into a -command. The @code{interactive} form must be located at top-level in -the function body (usually as the first form in the body), or in the -@code{interactive-form} property of the function symbol. When the -@code{interactive} form is located in the function body, it does -nothing when actually executed. Its presence serves as a flag, which -tells the Emacs command loop that the function can be called -interactively. The argument of the @code{interactive} form controls -the reading of arguments for an interactive call. - -@menu -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. -@end menu - -@node Using Interactive -@subsection Using @code{interactive} -@cindex arguments, interactive entry - - This section describes how to write the @code{interactive} form that -makes a Lisp function an interactively-callable command, and how to -examine a command's @code{interactive} form. - -@defspec interactive arg-descriptor -This special form declares that a function is a command, and that it -may therefore be called interactively (via @kbd{M-x} or by entering a -key sequence bound to it). The argument @var{arg-descriptor} declares -how to compute the arguments to the command when the command is called -interactively. - -A command may be called from Lisp programs like any other function, but -then the caller supplies the arguments and @var{arg-descriptor} has no -effect. - -@cindex @code{interactive-form}, function property -The @code{interactive} form must be located at top-level in the -function body, or in the function symbol's @code{interactive-form} -property (@pxref{Symbol Plists}). It has its effect because the -command loop looks for it before calling the function -(@pxref{Interactive Call}). Once the function is called, all its body -forms are executed; at this time, if the @code{interactive} form -occurs within the body, the form simply returns @code{nil} without -even evaluating its argument. - -By convention, you should put the @code{interactive} form in the -function body, as the first top-level form. If there is an -@code{interactive} form in both the @code{interactive-form} symbol -property and the function body, the former takes precedence. The -@code{interactive-form} symbol property can be used to add an -interactive form to an existing function, or change how its arguments -are processed interactively, without redefining the function. -@end defspec - -There are three possibilities for the argument @var{arg-descriptor}: - -@itemize @bullet -@item -It may be omitted or @code{nil}; then the command is called with no -arguments. This leads quickly to an error if the command requires one -or more arguments. - -@item -It may be a string; its contents are a sequence of elements separated -by newlines, one for each argument@footnote{Some elements actually -supply two arguments.}. Each element consists of a code character -(@pxref{Interactive Codes}) optionally followed by a prompt (which -some code characters use and some ignore). Here is an example: - -@smallexample -(interactive "P\nbFrobnicate buffer: ") -@end smallexample - -@noindent -The code letter @samp{P} sets the command's first argument to the raw -command prefix (@pxref{Prefix Command Arguments}). @samp{bFrobnicate -buffer: } prompts the user with @samp{Frobnicate buffer: } to enter -the name of an existing buffer, which becomes the second and final -argument. - -@c Emacs 19 feature -The prompt string can use @samp{%} to include previous argument values -(starting with the first argument) in the prompt. This is done using -@code{format} (@pxref{Formatting Strings}). For example, here is how -you could read the name of an existing buffer followed by a new name to -give to that buffer: - -@smallexample -@group -(interactive "bBuffer to rename: \nsRename buffer %s to: ") -@end group -@end smallexample - -@cindex @samp{*} in @code{interactive} -@cindex read-only buffers in interactive -If @samp{*} appears at the beginning of the string, then an error is -signaled if the buffer is read-only. - -@cindex @samp{@@} in @code{interactive} -@c Emacs 19 feature -If @samp{@@} appears at the beginning of the string, and if the key -sequence used to invoke the command includes any mouse events, then -the window associated with the first of those events is selected -before the command is run. - -@cindex @samp{^} in @code{interactive} -@cindex shift-selection, and @code{interactive} spec -If @samp{^} appears at the beginning of the string, and if the command -was invoked through @dfn{shift-translation}, set the mark and activate -the region temporarily, or extend an already active region, before the -command is run. If the command was invoked without shift-translation, -and the region is temporarily active, deactivate the region before the -command is run. Shift-translation is controlled on the user level by -@code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU -Emacs Manual}. - -You can use @samp{*}, @samp{@@}, and @code{^} together; the order does -not matter. Actual reading of arguments is controlled by the rest of -the prompt string (starting with the first character that is not -@samp{*}, @samp{@@}, or @samp{^}). - -@item -It may be a Lisp expression that is not a string; then it should be a -form that is evaluated to get a list of arguments to pass to the -command. Usually this form will call various functions to read input -from the user, most often through the minibuffer (@pxref{Minibuffers}) -or directly from the keyboard (@pxref{Reading Input}). - -Providing point or the mark as an argument value is also common, but -if you do this @emph{and} read input (whether using the minibuffer or -not), be sure to get the integer values of point or the mark after -reading. The current buffer may be receiving subprocess output; if -subprocess output arrives while the command is waiting for input, it -could relocate point and the mark. - -Here's an example of what @emph{not} to do: - -@smallexample -(interactive - (list (region-beginning) (region-end) - (read-string "Foo: " nil 'my-history))) -@end smallexample - -@noindent -Here's how to avoid the problem, by examining point and the mark after -reading the keyboard input: - -@smallexample -(interactive - (let ((string (read-string "Foo: " nil 'my-history))) - (list (region-beginning) (region-end) string))) -@end smallexample - -@strong{Warning:} the argument values should not include any data -types that can't be printed and then read. Some facilities save -@code{command-history} in a file to be read in the subsequent -sessions; if a command's arguments contain a data type that prints -using @samp{#<@dots{}>} syntax, those facilities won't work. - -There are, however, a few exceptions: it is ok to use a limited set of -expressions such as @code{(point)}, @code{(mark)}, -@code{(region-beginning)}, and @code{(region-end)}, because Emacs -recognizes them specially and puts the expression (rather than its -value) into the command history. To see whether the expression you -wrote is one of these exceptions, run the command, then examine -@code{(car command-history)}. -@end itemize - -@cindex examining the @code{interactive} form -@defun interactive-form function -This function returns the @code{interactive} form of @var{function}. -If @var{function} is an interactively callable function -(@pxref{Interactive Call}), the value is the command's -@code{interactive} form @code{(interactive @var{spec})}, which -specifies how to compute its arguments. Otherwise, the value is -@code{nil}. If @var{function} is a symbol, its function definition is -used. -@end defun - -@node Interactive Codes -@comment node-name, next, previous, up -@subsection Code Characters for @code{interactive} -@cindex interactive code description -@cindex description for interactive codes -@cindex codes, interactive, description of -@cindex characters for interactive codes - - The code character descriptions below contain a number of key words, -defined here as follows: - -@table @b -@item Completion -@cindex interactive completion -Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name -completion because the argument is read using @code{completing-read} -(@pxref{Completion}). @kbd{?} displays a list of possible completions. - -@item Existing -Require the name of an existing object. An invalid name is not -accepted; the commands to exit the minibuffer do not exit if the current -input is not valid. - -@item Default -@cindex default argument string -A default value of some sort is used if the user enters no text in the -minibuffer. The default depends on the code character. - -@item No I/O -This code letter computes an argument without reading any input. -Therefore, it does not use a prompt string, and any prompt string you -supply is ignored. - -Even though the code letter doesn't use a prompt string, you must follow -it with a newline if it is not the last code character in the string. - -@item Prompt -A prompt immediately follows the code character. The prompt ends either -with the end of the string or with a newline. - -@item Special -This code character is meaningful only at the beginning of the -interactive string, and it does not look for a prompt or a newline. -It is a single, isolated character. -@end table - -@cindex reading interactive arguments - Here are the code character descriptions for use with @code{interactive}: - -@table @samp -@item * -Signal an error if the current buffer is read-only. Special. - -@item @@ -Select the window mentioned in the first mouse event in the key -sequence that invoked this command. Special. - -@item ^ -If the command was invoked through shift-translation, set the mark and -activate the region temporarily, or extend an already active region, -before the command is run. If the command was invoked without -shift-translation, and the region is temporarily active, deactivate -the region before the command is run. Special. - -@item a -A function name (i.e., a symbol satisfying @code{fboundp}). Existing, -Completion, Prompt. - -@item b -The name of an existing buffer. By default, uses the name of the -current buffer (@pxref{Buffers}). Existing, Completion, Default, -Prompt. - -@item B -A buffer name. The buffer need not exist. By default, uses the name of -a recently used buffer other than the current buffer. Completion, -Default, Prompt. - -@item c -A character. The cursor does not move into the echo area. Prompt. - -@item C -A command name (i.e., a symbol satisfying @code{commandp}). Existing, -Completion, Prompt. - -@item d -@cindex position argument -The position of point, as an integer (@pxref{Point}). No I/O. - -@item D -A directory name. The default is the current default directory of the -current buffer, @code{default-directory} (@pxref{File Name Expansion}). -Existing, Completion, Default, Prompt. - -@item e -The first or next mouse event in the key sequence that invoked the command. -More precisely, @samp{e} gets events that are lists, so you can look at -the data in the lists. @xref{Input Events}. No I/O. - -You can use @samp{e} more than once in a single command's interactive -specification. If the key sequence that invoked the command has -@var{n} events that are lists, the @var{n}th @samp{e} provides the -@var{n}th such event. Events that are not lists, such as function keys -and @acronym{ASCII} characters, do not count where @samp{e} is concerned. - -@item f -A file name of an existing file (@pxref{File Names}). The default -directory is @code{default-directory}. Existing, Completion, Default, -Prompt. - -@item F -A file name. The file need not exist. Completion, Default, Prompt. - -@item G -A file name. The file need not exist. If the user enters just a -directory name, then the value is just that directory name, with no -file name within the directory added. Completion, Default, Prompt. - -@item i -An irrelevant argument. This code always supplies @code{nil} as -the argument's value. No I/O. - -@item k -A key sequence (@pxref{Key Sequences}). This keeps reading events -until a command (or undefined command) is found in the current key -maps. The key sequence argument is represented as a string or vector. -The cursor does not move into the echo area. Prompt. - -If @samp{k} reads a key sequence that ends with a down-event, it also -reads and discards the following up-event. You can get access to that -up-event with the @samp{U} code character. - -This kind of input is used by commands such as @code{describe-key} and -@code{global-set-key}. - -@item K -A key sequence, whose definition you intend to change. This works like -@samp{k}, except that it suppresses, for the last input event in the key -sequence, the conversions that are normally used (when necessary) to -convert an undefined key into a defined one. - -@item m -@cindex marker argument -The position of the mark, as an integer. No I/O. - -@item M -Arbitrary text, read in the minibuffer using the current buffer's input -method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU -Emacs Manual}). Prompt. - -@item n -A number, read with the minibuffer. If the input is not a number, the -user has to try again. @samp{n} never uses the prefix argument. -Prompt. - -@item N -The numeric prefix argument; but if there is no prefix argument, read -a number as with @kbd{n}. The value is always a number. @xref{Prefix -Command Arguments}. Prompt. - -@item p -@cindex numeric prefix argument usage -The numeric prefix argument. (Note that this @samp{p} is lower case.) -No I/O. - -@item P -@cindex raw prefix argument usage -The raw prefix argument. (Note that this @samp{P} is upper case.) No -I/O. - -@item r -@cindex region argument -Point and the mark, as two numeric arguments, smallest first. This is -the only code letter that specifies two successive arguments rather than -one. No I/O. - -@item s -Arbitrary text, read in the minibuffer and returned as a string -(@pxref{Text from Minibuffer}). Terminate the input with either -@kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of -these characters in the input.) Prompt. - -@item S -An interned symbol whose name is read in the minibuffer. Any whitespace -character terminates the input. (Use @kbd{C-q} to include whitespace in -the string.) Other characters that normally terminate a symbol (e.g., -parentheses and brackets) do not do so here. Prompt. - -@item U -A key sequence or @code{nil}. Can be used after a @samp{k} or -@samp{K} argument to get the up-event that was discarded (if any) -after @samp{k} or @samp{K} read a down-event. If no up-event has been -discarded, @samp{U} provides @code{nil} as the argument. No I/O. - -@item v -A variable declared to be a user option (i.e., satisfying the -predicate @code{user-variable-p}). This reads the variable using -@code{read-variable}. @xref{Definition of read-variable}. Existing, -Completion, Prompt. - -@item x -A Lisp object, specified with its read syntax, terminated with a -@kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from -Minibuffer}. Prompt. - -@item X -@cindex evaluated expression argument -A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates -the form so that its value becomes the argument for the command. -Prompt. - -@item z -A coding system name (a symbol). If the user enters null input, the -argument value is @code{nil}. @xref{Coding Systems}. Completion, -Existing, Prompt. - -@item Z -A coding system name (a symbol)---but only if this command has a prefix -argument. With no prefix argument, @samp{Z} provides @code{nil} as the -argument value. Completion, Existing, Prompt. -@end table - -@node Interactive Examples -@comment node-name, next, previous, up -@subsection Examples of Using @code{interactive} -@cindex examples of using @code{interactive} -@cindex @code{interactive}, examples of using - - Here are some examples of @code{interactive}: - -@example -@group -(defun foo1 () ; @r{@code{foo1} takes no arguments,} - (interactive) ; @r{just moves forward two words.} - (forward-word 2)) - @result{} foo1 -@end group - -@group -(defun foo2 (n) ; @r{@code{foo2} takes one argument,} - (interactive "^p") ; @r{which is the numeric prefix.} - ; @r{under @code{shift-select-mode},} - ; @r{will activate or extend region.} - (forward-word (* 2 n))) - @result{} foo2 -@end group - -@group -(defun foo3 (n) ; @r{@code{foo3} takes one argument,} - (interactive "nCount:") ; @r{which is read with the Minibuffer.} - (forward-word (* 2 n))) - @result{} foo3 -@end group - -@group -(defun three-b (b1 b2 b3) - "Select three existing buffers. -Put them into three windows, selecting the last one." -@end group - (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:") - (delete-other-windows) - (split-window (selected-window) 8) - (switch-to-buffer b1) - (other-window 1) - (split-window (selected-window) 8) - (switch-to-buffer b2) - (other-window 1) - (switch-to-buffer b3)) - @result{} three-b -@group -(three-b "*scratch*" "declarations.texi" "*mail*") - @result{} nil -@end group -@end example - -@node Interactive Call -@section Interactive Call -@cindex interactive call - - After the command loop has translated a key sequence into a command, -it invokes that command using the function @code{command-execute}. If -the command is a function, @code{command-execute} calls -@code{call-interactively}, which reads the arguments and calls the -command. You can also call these functions yourself. - - Note that the term ``command'', in this context, refers to an -interactively callable function (or function-like object), or a -keyboard macro. It does not refer to the key sequence used to invoke -a command (@pxref{Keymaps}). - -@defun commandp object &optional for-call-interactively -This function returns @code{t} if @var{object} is a command. -Otherwise, it returns @code{nil}. - -Commands include strings and vectors (which are treated as keyboard -macros), lambda expressions that contain a top-level -@code{interactive} form (@pxref{Using Interactive}), byte-code -function objects made from such lambda expressions, autoload objects -that are declared as interactive (non-@code{nil} fourth argument to -@code{autoload}), and some primitive functions. Also, a symbol is -considered a command if it has a non-@code{nil} -@code{interactive-form} property, or if its function definition -satisfies @code{commandp}. - -If @var{for-call-interactively} is non-@code{nil}, then -@code{commandp} returns @code{t} only for objects that -@code{call-interactively} could call---thus, not for keyboard macros. - -See @code{documentation} in @ref{Accessing Documentation}, for a -realistic example of using @code{commandp}. -@end defun - -@defun call-interactively command &optional record-flag keys -This function calls the interactively callable function @var{command}, -providing arguments according to its interactive calling specifications. -It returns whatever @var{command} returns. - -If, for instance, you have a function with the following signature: - -@example -(defun foo (begin end) - (interactive "r") - ...) -@end example - -then saying - -@example -(call-interactively 'foo) -@end example - -will call @code{foo} with the region (@code{point} and @code{mark}) as -the arguments. - -An error is signaled if @var{command} is not a function or if it -cannot be called interactively (i.e., is not a command). Note that -keyboard macros (strings and vectors) are not accepted, even though -they are considered commands, because they are not functions. If -@var{command} is a symbol, then @code{call-interactively} uses its -function definition. - -@cindex record command history -If @var{record-flag} is non-@code{nil}, then this command and its -arguments are unconditionally added to the list @code{command-history}. -Otherwise, the command is added only if it uses the minibuffer to read -an argument. @xref{Command History}. - -The argument @var{keys}, if given, should be a vector which specifies -the sequence of events to supply if the command inquires which events -were used to invoke it. If @var{keys} is omitted or @code{nil}, the -default is the return value of @code{this-command-keys-vector}. -@xref{Definition of this-command-keys-vector}. -@end defun - -@defun command-execute command &optional record-flag keys special -@cindex keyboard macro execution -This function executes @var{command}. The argument @var{command} must -satisfy the @code{commandp} predicate; i.e., it must be an interactively -callable function or a keyboard macro. - -A string or vector as @var{command} is executed with -@code{execute-kbd-macro}. A function is passed to -@code{call-interactively} (see above), along with the -@var{record-flag} and @var{keys} arguments. - -If @var{command} is a symbol, its function definition is used in its -place. A symbol with an @code{autoload} definition counts as a -command if it was declared to stand for an interactively callable -function. Such a definition is handled by loading the specified -library and then rechecking the definition of the symbol. - -The argument @var{special}, if given, means to ignore the prefix -argument and not clear it. This is used for executing special events -(@pxref{Special Events}). -@end defun - -@deffn Command execute-extended-command prefix-argument -@cindex read command name -This function reads a command name from the minibuffer using -@code{completing-read} (@pxref{Completion}). Then it uses -@code{command-execute} to call the specified command. Whatever that -command returns becomes the value of @code{execute-extended-command}. - -@cindex execute with prefix argument -If the command asks for a prefix argument, it receives the value -@var{prefix-argument}. If @code{execute-extended-command} is called -interactively, the current raw prefix argument is used for -@var{prefix-argument}, and thus passed on to whatever command is run. - -@c !!! Should this be @kindex? -@cindex @kbd{M-x} -@code{execute-extended-command} is the normal definition of @kbd{M-x}, -so it uses the string @w{@samp{M-x }} as a prompt. (It would be better -to take the prompt from the events used to invoke -@code{execute-extended-command}, but that is painful to implement.) A -description of the value of the prefix argument, if any, also becomes -part of the prompt. - -@example -@group -(execute-extended-command 3) ----------- Buffer: Minibuffer ---------- -3 M-x forward-word RET ----------- Buffer: Minibuffer ---------- - @result{} t -@end group -@end example -@end deffn - -@node Distinguish Interactive -@section Distinguish Interactive Calls - - Sometimes a command should display additional visual feedback (such -as an informative message in the echo area) for interactive calls -only. There are three ways to do this. The recommended way to test -whether the function was called using @code{call-interactively} is to -give it an optional argument @code{print-message} and use the -@code{interactive} spec to make it non-@code{nil} in interactive -calls. Here's an example: - -@example -(defun foo (&optional print-message) - (interactive "p") - (when print-message - (message "foo"))) -@end example - -@noindent -We use @code{"p"} because the numeric prefix argument is never -@code{nil}. Defined in this way, the function does display the -message when called from a keyboard macro. - - The above method with the additional argument is usually best, -because it allows callers to say ``treat this call as interactive''. -But you can also do the job by testing @code{called-interactively-p}. - -@defun called-interactively-p kind -This function returns @code{t} when the calling function was called -using @code{call-interactively}. - -The argument @var{kind} should be either the symbol @code{interactive} -or the symbol @code{any}. If it is @code{interactive}, then -@code{called-interactively-p} returns @code{t} only if the call was -made directly by the user---e.g., if the user typed a key sequence -bound to the calling function, but @emph{not} if the user ran a -keyboard macro that called the function (@pxref{Keyboard Macros}). If -@var{kind} is @code{any}, @code{called-interactively-p} returns -@code{t} for any kind of interactive call, including keyboard macros. - -If in doubt, use @code{any}; the only known proper use of -@code{interactive} is if you need to decide whether to display a -helpful message while a function is running. - -A function is never considered to be called interactively if it was -called via Lisp evaluation (or with @code{apply} or @code{funcall}). -@end defun - -@noindent -Here is an example of using @code{called-interactively-p}: - -@example -@group -(defun foo () - (interactive) - (when (called-interactively-p 'any) - (message "Interactive!") - 'foo-called-interactively)) -@end group - -@group -;; @r{Type @kbd{M-x foo}.} - @print{} Interactive! -@end group - -@group -(foo) - @result{} nil -@end group -@end example - -@noindent -Here is another example that contrasts direct and indirect calls to -@code{called-interactively-p}. - -@example -@group -(defun bar () - (interactive) - (message "%s" (list (foo) (called-interactively-p 'any)))) -@end group - -@group -;; @r{Type @kbd{M-x bar}.} - @print{} (nil t) -@end group -@end example - -@node Command Loop Info -@comment node-name, next, previous, up -@section Information from the Command Loop - -The editor command loop sets several Lisp variables to keep status -records for itself and for commands that are run. With the exception of -@code{this-command} and @code{last-command} it's generally a bad idea to -change any of these variables in a Lisp program. - -@defvar last-command -This variable records the name of the previous command executed by the -command loop (the one before the current command). Normally the value -is a symbol with a function definition, but this is not guaranteed. - -The value is copied from @code{this-command} when a command returns to -the command loop, except when the command has specified a prefix -argument for the following command. - -This variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Terminals}. -@end defvar - -@defvar real-last-command -This variable is set up by Emacs just like @code{last-command}, -but never altered by Lisp programs. -@end defvar - -@defvar last-repeatable-command -This variable stores the most recently executed command that was not -part of an input event. This is the command @code{repeat} will try to -repeat, @xref{Repeating,,, emacs, The GNU Emacs Manual}. -@end defvar - -@defvar this-command -@cindex current command -This variable records the name of the command now being executed by -the editor command loop. Like @code{last-command}, it is normally a symbol -with a function definition. - -The command loop sets this variable just before running a command, and -copies its value into @code{last-command} when the command finishes -(unless the command specified a prefix argument for the following -command). - -@cindex kill command repetition -Some commands set this variable during their execution, as a flag for -whatever command runs next. In particular, the functions for killing text -set @code{this-command} to @code{kill-region} so that any kill commands -immediately following will know to append the killed text to the -previous kill. -@end defvar - -If you do not want a particular command to be recognized as the previous -command in the case where it got an error, you must code that command to -prevent this. One way is to set @code{this-command} to @code{t} at the -beginning of the command, and set @code{this-command} back to its proper -value at the end, like this: - -@example -(defun foo (args@dots{}) - (interactive @dots{}) - (let ((old-this-command this-command)) - (setq this-command t) - @r{@dots{}do the work@dots{}} - (setq this-command old-this-command))) -@end example - -@noindent -We do not bind @code{this-command} with @code{let} because that would -restore the old value in case of error---a feature of @code{let} which -in this case does precisely what we want to avoid. - -@defvar this-original-command -This has the same value as @code{this-command} except when command -remapping occurs (@pxref{Remapping Commands}). In that case, -@code{this-command} gives the command actually run (the result of -remapping), and @code{this-original-command} gives the command that -was specified to run but remapped into another command. -@end defvar - -@defun this-command-keys -This function returns a string or vector containing the key sequence -that invoked the present command, plus any previous commands that -generated the prefix argument for this command. Any events read by the -command using @code{read-event} without a timeout get tacked on to the end. - -However, if the command has called @code{read-key-sequence}, it -returns the last read key sequence. @xref{Key Sequence Input}. The -value is a string if all events in the sequence were characters that -fit in a string. @xref{Input Events}. - -@example -@group -(this-command-keys) -;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} - @result{} "^U^X^E" -@end group -@end example -@end defun - -@defun this-command-keys-vector -@anchor{Definition of this-command-keys-vector} -Like @code{this-command-keys}, except that it always returns the events -in a vector, so you don't need to deal with the complexities of storing -input events in a string (@pxref{Strings of Events}). -@end defun - -@defun clear-this-command-keys &optional keep-record -This function empties out the table of events for -@code{this-command-keys} to return. Unless @var{keep-record} is -non-@code{nil}, it also empties the records that the function -@code{recent-keys} (@pxref{Recording Input}) will subsequently return. -This is useful after reading a password, to prevent the password from -echoing inadvertently as part of the next command in certain cases. -@end defun - -@defvar last-nonmenu-event -This variable holds the last input event read as part of a key sequence, -not counting events resulting from mouse menus. - -One use of this variable is for telling @code{x-popup-menu} where to pop -up a menu. It is also used internally by @code{y-or-n-p} -(@pxref{Yes-or-No Queries}). -@end defvar - -@defvar last-command-event -@defvarx last-command-char -This variable is set to the last input event that was read by the -command loop as part of a command. The principal use of this variable -is in @code{self-insert-command}, which uses it to decide which -character to insert. - -@example -@group -last-command-event -;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} - @result{} 5 -@end group -@end example - -@noindent -The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}. - -The alias @code{last-command-char} is obsolete. -@end defvar - -@c Emacs 19 feature -@defvar last-event-frame -This variable records which frame the last input event was directed to. -Usually this is the frame that was selected when the event was -generated, but if that frame has redirected input focus to another -frame, the value is the frame to which the event was redirected. -@xref{Input Focus}. - -If the last event came from a keyboard macro, the value is @code{macro}. -@end defvar - -@node Adjusting Point -@section Adjusting Point After Commands -@cindex adjusting point -@cindex invisible/intangible text, and point -@cindex @code{display} property, and point display -@cindex @code{composition} property, and point display - - It is not easy to display a value of point in the middle of a -sequence of text that has the @code{display}, @code{composition} or -is invisible. Therefore, after a command finishes and returns to the -command loop, if point is within such a sequence, the command loop -normally moves point to the edge of the sequence. - - A command can inhibit this feature by setting the variable -@code{disable-point-adjustment}: - -@defvar disable-point-adjustment -If this variable is non-@code{nil} when a command returns to the -command loop, then the command loop does not check for those text -properties, and does not move point out of sequences that have them. - -The command loop sets this variable to @code{nil} before each command, -so if a command sets it, the effect applies only to that command. -@end defvar - -@defvar global-disable-point-adjustment -If you set this variable to a non-@code{nil} value, the feature of -moving point out of these sequences is completely turned off. -@end defvar - -@node Input Events -@section Input Events -@cindex events -@cindex input events - -The Emacs command loop reads a sequence of @dfn{input events} that -represent keyboard or mouse activity. The events for keyboard activity -are characters or symbols; mouse events are always lists. This section -describes the representation and meaning of input events in detail. - -@defun eventp object -This function returns non-@code{nil} if @var{object} is an input event -or event type. - -Note that any symbol might be used as an event or an event type. -@code{eventp} cannot distinguish whether a symbol is intended by Lisp -code to be used as an event. Instead, it distinguishes whether the -symbol has actually been used in an event that has been read as input in -the current Emacs session. If a symbol has not yet been so used, -@code{eventp} returns @code{nil}. -@end defun - -@menu -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. - Event types. -* Accessing Mouse:: Functions to extract info from mouse events. -* Accessing Scroll:: Functions to get info from scroll bar events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. -@end menu - -@node Keyboard Events -@subsection Keyboard Events -@cindex keyboard events - -There are two kinds of input you can get from the keyboard: ordinary -keys, and function keys. Ordinary keys correspond to characters; the -events they generate are represented in Lisp as characters. The event -type of a character event is the character itself (an integer); see -@ref{Classifying Events}. - -@cindex modifier bits (of input character) -@cindex basic code (of input character) -An input character event consists of a @dfn{basic code} between 0 and -524287, plus any or all of these @dfn{modifier bits}: - -@table @asis -@item meta -The -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -bit in the character code indicates a character -typed with the meta key held down. - -@item control -The -@tex -@math{2^{26}} -@end tex -@ifnottex -2**26 -@end ifnottex -bit in the character code indicates a non-@acronym{ASCII} -control character. - -@sc{ascii} control characters such as @kbd{C-a} have special basic -codes of their own, so Emacs needs no special bit to indicate them. -Thus, the code for @kbd{C-a} is just 1. - -But if you type a control combination not in @acronym{ASCII}, such as -@kbd{%} with the control key, the numeric value you get is the code -for @kbd{%} plus -@tex -@math{2^{26}} -@end tex -@ifnottex -2**26 -@end ifnottex -(assuming the terminal supports non-@acronym{ASCII} -control characters). - -@item shift -The -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit in the character code indicates an @acronym{ASCII} control -character typed with the shift key held down. - -For letters, the basic code itself indicates upper versus lower case; -for digits and punctuation, the shift key selects an entirely different -character with a different basic code. In order to keep within the -@acronym{ASCII} character set whenever possible, Emacs avoids using the -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit for those characters. - -However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from -@kbd{C-a}, so Emacs uses the -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit in @kbd{C-A} and not in -@kbd{C-a}. - -@item hyper -The -@tex -@math{2^{24}} -@end tex -@ifnottex -2**24 -@end ifnottex -bit in the character code indicates a character -typed with the hyper key held down. - -@item super -The -@tex -@math{2^{23}} -@end tex -@ifnottex -2**23 -@end ifnottex -bit in the character code indicates a character -typed with the super key held down. - -@item alt -The -@tex -@math{2^{22}} -@end tex -@ifnottex -2**22 -@end ifnottex -bit in the character code indicates a character typed with the alt key -held down. (The key labeled @key{Alt} on most keyboards is actually -treated as the meta key, not this.) -@end table - - It is best to avoid mentioning specific bit numbers in your program. -To test the modifier bits of a character, use the function -@code{event-modifiers} (@pxref{Classifying Events}). When making key -bindings, you can use the read syntax for characters with modifier bits -(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with -@code{define-key}, you can use lists such as @code{(control hyper ?x)} to -specify the characters (@pxref{Changing Key Bindings}). The function -@code{event-convert-list} converts such a list into an event type -(@pxref{Classifying Events}). - -@node Function Keys -@subsection Function Keys - -@cindex function keys -Most keyboards also have @dfn{function keys}---keys that have names or -symbols that are not characters. Function keys are represented in -Emacs Lisp as symbols; the symbol's name is the function key's label, -in lower case. For example, pressing a key labeled @key{F1} generates -an input event represented by the symbol @code{f1}. - -The event type of a function key event is the event symbol itself. -@xref{Classifying Events}. - -Here are a few special cases in the symbol-naming convention for -function keys: - -@table @asis -@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete} -These keys correspond to common @acronym{ASCII} control characters that have -special keys on most keyboards. - -In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the -terminal can distinguish between them, Emacs conveys the distinction to -Lisp programs by representing the former as the integer 9, and the -latter as the symbol @code{tab}. - -Most of the time, it's not useful to distinguish the two. So normally -@code{local-function-key-map} (@pxref{Translation Keymaps}) is set up -to map @code{tab} into 9. Thus, a key binding for character code 9 -(the character @kbd{C-i}) also applies to @code{tab}. Likewise for -the other symbols in this group. The function @code{read-char} -likewise converts these events into characters. - -In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace} -converts into the character code 127 (@key{DEL}), not into code 8 -(@key{BS}). This is what most users prefer. - -@item @code{left}, @code{up}, @code{right}, @code{down} -Cursor arrow keys -@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{} -Keypad keys (to the right of the regular keyboard). -@item @code{kp-0}, @code{kp-1}, @dots{} -Keypad keys with digits. -@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} -Keypad PF keys. -@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down} -Keypad arrow keys. Emacs normally translates these into the -corresponding non-keypad keys @code{home}, @code{left}, @dots{} -@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete} -Additional keypad duplicates of keys ordinarily found elsewhere. Emacs -normally translates these into the like-named non-keypad keys. -@end table - -You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER}, -@key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to -represent them is with prefixes in the symbol name: - -@table @samp -@item A- -The alt modifier. -@item C- -The control modifier. -@item H- -The hyper modifier. -@item M- -The meta modifier. -@item S- -The shift modifier. -@item s- -The super modifier. -@end table - -Thus, the symbol for the key @key{F3} with @key{META} held down is -@code{M-f3}. When you use more than one prefix, we recommend you -write them in alphabetical order; but the order does not matter in -arguments to the key-binding lookup and modification functions. - -@node Mouse Events -@subsection Mouse Events - -Emacs supports four kinds of mouse events: click events, drag events, -button-down events, and motion events. All mouse events are represented -as lists. The @sc{car} of the list is the event type; this says which -mouse button was involved, and which modifier keys were used with it. -The event type can also distinguish double or triple button presses -(@pxref{Repeat Events}). The rest of the list elements give position -and time information. - -For key lookup, only the event type matters: two events of the same type -necessarily run the same command. The command can access the full -values of these events using the @samp{e} interactive code. -@xref{Interactive Codes}. - -A key sequence that starts with a mouse event is read using the keymaps -of the buffer in the window that the mouse was in, not the current -buffer. This does not imply that clicking in a window selects that -window or its buffer---that is entirely under the control of the command -binding of the key sequence. - -@node Click Events -@subsection Click Events -@cindex click event -@cindex mouse click event - -When the user presses a mouse button and releases it at the same -location, that generates a @dfn{click} event. All mouse click event -share the same format: - -@example -(@var{event-type} @var{position} @var{click-count}) -@end example - -@table @asis -@item @var{event-type} -This is a symbol that indicates which mouse button was used. It is -one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the -buttons are numbered left to right. - -You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-}, -@samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift -and super, just as you would with function keys. - -This symbol also serves as the event type of the event. Key bindings -describe events by their types; thus, if there is a key binding for -@code{mouse-1}, that binding would apply to all events whose -@var{event-type} is @code{mouse-1}. - -@item @var{position} -This is the position where the mouse click occurred. The actual -format of @var{position} depends on what part of a window was clicked -on. - -For mouse click events in the text area, mode line, header line, or in -the marginal areas, @var{position} has this form: - -@example -(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} - @var{object} @var{text-pos} (@var{col} . @var{row}) - @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height})) -@end example - -@noindent -The meanings of these list elements are documented below. -@xref{Accessing Mouse}, for functions that let you easily access these -elements. - -@table @asis -@item @var{window} -This is the window in which the click occurred. - -@item @var{pos-or-area} -This is the buffer position of the character clicked on in the text -area, or if clicked outside the text area, it is the window area in -which the click occurred. It is one of the symbols @code{mode-line}, -@code{header-line}, @code{vertical-line}, @code{left-margin}, -@code{right-margin}, @code{left-fringe}, or @code{right-fringe}. - -In one special case, @var{pos-or-area} is a list containing a symbol -(one of the symbols listed above) instead of just the symbol. This -happens after the imaginary prefix keys for the event are registered -by Emacs. @xref{Key Sequence Input}. - -@item @var{x}, @var{y} -These are the relative pixel coordinates of the click. For clicks in -the text area of a window, the coordinate origin @code{(0 . 0)} is -taken to be the top left corner of the text area. @xref{Window -Sizes}. For clicks in a mode line or header line, the coordinate -origin is the top left corner of the window itself. For fringes, -margins, and the vertical border, @var{x} does not have meaningful -data. For fringes and margins, @var{y} is relative to the bottom edge -of the header line. In all cases, the @var{x} and @var{y} coordinates -increase rightward and downward respectively. - -@item @var{timestamp} -This is the time at which the event occurred, in milliseconds. - -@item @var{object} -This is either @code{nil} if there is no string-type text property at -the click position, or a cons cell of the form (@var{string} -. @var{string-pos}) if there is one: - -@table @asis -@item @var{string} -The string which was clicked on, including any properties. - -@item @var{string-pos} -The position in the string where the click occurred. -@end table - -@item @var{text-pos} -For clicks on a marginal area or on a fringe, this is the buffer -position of the first visible character in the corresponding line in -the window. For other events, it is the current buffer position in -the window. - -@item @var{col}, @var{row} -These are the actual column and row coordinate numbers of the glyph -under the @var{x}, @var{y} position. If @var{x} lies beyond the last -column of actual text on its line, @var{col} is reported by adding -fictional extra columns that have the default character width. Row 0 -is taken to be the header line if the window has one, or the topmost -row of the text area otherwise. Column 0 is taken to be the leftmost -column of the text area for clicks on a window text area, or the -leftmost mode line or header line column for clicks there. For clicks -on fringes or vertical borders, these have no meaningful data. For -clicks on margins, @var{col} is measured from the left edge of the -margin area and @var{row} is measured from the top of the margin area. - -@item @var{image} -This is the image object on which the click occurred. It is either -@code{nil} if there is no image at the position clicked on, or it is -an image object as returned by @code{find-image} if click was in an image. - -@item @var{dx}, @var{dy} -These are the pixel coordinates of the click, relative to -the top left corner of @var{object}, which is @code{(0 . 0)}. If -@var{object} is @code{nil}, the coordinates are relative to the top -left corner of the character glyph clicked on. - -@item @var{width}, @var{height} -These are the pixel width and height of @var{object} or, if this is -@code{nil}, those of the character glyph clicked on. -@end table - -@sp 1 -For mouse clicks on a scroll-bar, @var{position} has this form: - -@example -(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part}) -@end example - -@table @asis -@item @var{window} -This is the window whose scroll-bar was clicked on. - -@item @var{area} -This is the scroll bar where the click occurred. It is one of the -symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}. - -@item @var{portion} -This is the distance of the click from the top or left end of -the scroll bar. - -@item @var{whole} -This is the length of the entire scroll bar. - -@item @var{timestamp} -This is the time at which the event occurred, in milliseconds. - -@item @var{part} -This is the part of the scroll-bar which was clicked on. It is one -of the symbols @code{above-handle}, @code{handle}, @code{below-handle}, -@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}. -@end table - -@item @var{click-count} -This is the number of rapid repeated presses so far of the same mouse -button. @xref{Repeat Events}. -@end table - -@node Drag Events -@subsection Drag Events -@cindex drag event -@cindex mouse drag event - -With Emacs, you can have a drag event without even changing your -clothes. A @dfn{drag event} happens every time the user presses a mouse -button and then moves the mouse to a different character position before -releasing the button. Like all mouse events, drag events are -represented in Lisp as lists. The lists record both the starting mouse -position and the final position, like this: - -@example -(@var{event-type} - (@var{window1} START-POSITION) - (@var{window2} END-POSITION)) -@end example - -For a drag event, the name of the symbol @var{event-type} contains the -prefix @samp{drag-}. For example, dragging the mouse with button 2 -held down generates a @code{drag-mouse-2} event. The second and third -elements of the event give the starting and ending position of the -drag. They have the same form as @var{position} in a click event -(@pxref{Click Events}) that is not on the scroll bar part of the -window. You can access the second element of any mouse event in the -same way, with no need to distinguish drag events from others. - -The @samp{drag-} prefix follows the modifier key prefixes such as -@samp{C-} and @samp{M-}. - -If @code{read-key-sequence} receives a drag event that has no key -binding, and the corresponding click event does have a binding, it -changes the drag event into a click event at the drag's starting -position. This means that you don't have to distinguish between click -and drag events unless you want to. - -@node Button-Down Events -@subsection Button-Down Events -@cindex button-down event - -Click and drag events happen when the user releases a mouse button. -They cannot happen earlier, because there is no way to distinguish a -click from a drag until the button is released. - -If you want to take action as soon as a button is pressed, you need to -handle @dfn{button-down} events.@footnote{Button-down is the -conservative antithesis of drag.} These occur as soon as a button is -pressed. They are represented by lists that look exactly like click -events (@pxref{Click Events}), except that the @var{event-type} symbol -name contains the prefix @samp{down-}. The @samp{down-} prefix follows -modifier key prefixes such as @samp{C-} and @samp{M-}. - -The function @code{read-key-sequence} ignores any button-down events -that don't have command bindings; therefore, the Emacs command loop -ignores them too. This means that you need not worry about defining -button-down events unless you want them to do something. The usual -reason to define a button-down event is so that you can track mouse -motion (by reading motion events) until the button is released. -@xref{Motion Events}. - -@node Repeat Events -@subsection Repeat Events -@cindex repeat events -@cindex double-click events -@cindex triple-click events -@cindex mouse events, repeated - -If you press the same mouse button more than once in quick succession -without moving the mouse, Emacs generates special @dfn{repeat} mouse -events for the second and subsequent presses. - -The most common repeat events are @dfn{double-click} events. Emacs -generates a double-click event when you click a button twice; the event -happens when you release the button (as is normal for all click -events). - -The event type of a double-click event contains the prefix -@samp{double-}. Thus, a double click on the second mouse button with -@key{meta} held down comes to the Lisp program as -@code{M-double-mouse-2}. If a double-click event has no binding, the -binding of the corresponding ordinary click event is used to execute -it. Thus, you need not pay attention to the double click feature -unless you really want to. - -When the user performs a double click, Emacs generates first an ordinary -click event, and then a double-click event. Therefore, you must design -the command binding of the double click event to assume that the -single-click command has already run. It must produce the desired -results of a double click, starting from the results of a single click. - -This is convenient, if the meaning of a double click somehow ``builds -on'' the meaning of a single click---which is recommended user interface -design practice for double clicks. - -If you click a button, then press it down again and start moving the -mouse with the button held down, then you get a @dfn{double-drag} event -when you ultimately release the button. Its event type contains -@samp{double-drag} instead of just @samp{drag}. If a double-drag event -has no binding, Emacs looks for an alternate binding as if the event -were an ordinary drag. - -Before the double-click or double-drag event, Emacs generates a -@dfn{double-down} event when the user presses the button down for the -second time. Its event type contains @samp{double-down} instead of just -@samp{down}. If a double-down event has no binding, Emacs looks for an -alternate binding as if the event were an ordinary button-down event. -If it finds no binding that way either, the double-down event is -ignored. - -To summarize, when you click a button and then press it again right -away, Emacs generates a down event and a click event for the first -click, a double-down event when you press the button again, and finally -either a double-click or a double-drag event. - -If you click a button twice and then press it again, all in quick -succession, Emacs generates a @dfn{triple-down} event, followed by -either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of -these events contain @samp{triple} instead of @samp{double}. If any -triple event has no binding, Emacs uses the binding that it would use -for the corresponding double event. - -If you click a button three or more times and then press it again, the -events for the presses beyond the third are all triple events. Emacs -does not have separate event types for quadruple, quintuple, etc.@: -events. However, you can look at the event list to find out precisely -how many times the button was pressed. - -@defun event-click-count event -This function returns the number of consecutive button presses that led -up to @var{event}. If @var{event} is a double-down, double-click or -double-drag event, the value is 2. If @var{event} is a triple event, -the value is 3 or greater. If @var{event} is an ordinary mouse event -(not a repeat event), the value is 1. -@end defun - -@defopt double-click-fuzz -To generate repeat events, successive mouse button presses must be at -approximately the same screen position. The value of -@code{double-click-fuzz} specifies the maximum number of pixels the -mouse may be moved (horizontally or vertically) between two successive -clicks to make a double-click. - -This variable is also the threshold for motion of the mouse to count -as a drag. -@end defopt - -@defopt double-click-time -To generate repeat events, the number of milliseconds between -successive button presses must be less than the value of -@code{double-click-time}. Setting @code{double-click-time} to -@code{nil} disables multi-click detection entirely. Setting it to -@code{t} removes the time limit; Emacs then detects multi-clicks by -position only. -@end defopt - -@node Motion Events -@subsection Motion Events -@cindex motion event -@cindex mouse motion events - -Emacs sometimes generates @dfn{mouse motion} events to describe motion -of the mouse without any button activity. Mouse motion events are -represented by lists that look like this: - -@example -(mouse-movement POSITION) -@end example - -The second element of the list describes the current position of the -mouse, just as in a click event (@pxref{Click Events}). - -The special form @code{track-mouse} enables generation of motion events -within its body. Outside of @code{track-mouse} forms, Emacs does not -generate events for mere motion of the mouse, and these events do not -appear. @xref{Mouse Tracking}. - -@node Focus Events -@subsection Focus Events -@cindex focus event - -Window systems provide general ways for the user to control which window -gets keyboard input. This choice of window is called the @dfn{focus}. -When the user does something to switch between Emacs frames, that -generates a @dfn{focus event}. The normal definition of a focus event, -in the global keymap, is to select a new frame within Emacs, as the user -would expect. @xref{Input Focus}. - -Focus events are represented in Lisp as lists that look like this: - -@example -(switch-frame @var{new-frame}) -@end example - -@noindent -where @var{new-frame} is the frame switched to. - -Some X window managers are set up so that just moving the mouse into a -window is enough to set the focus there. Usually, there is no need -for a Lisp program to know about the focus change until some other -kind of input arrives. Emacs generates a focus event only when the -user actually types a keyboard key or presses a mouse button in the -new frame; just moving the mouse between frames does not generate a -focus event. - -A focus event in the middle of a key sequence would garble the -sequence. So Emacs never generates a focus event in the middle of a key -sequence. If the user changes focus in the middle of a key -sequence---that is, after a prefix key---then Emacs reorders the events -so that the focus event comes either before or after the multi-event key -sequence, and not within it. - -@node Misc Events -@subsection Miscellaneous System Events - -A few other event types represent occurrences within the system. - -@table @code -@cindex @code{delete-frame} event -@item (delete-frame (@var{frame})) -This kind of event indicates that the user gave the window manager -a command to delete a particular window, which happens to be an Emacs frame. - -The standard definition of the @code{delete-frame} event is to delete @var{frame}. - -@cindex @code{iconify-frame} event -@item (iconify-frame (@var{frame})) -This kind of event indicates that the user iconified @var{frame} using -the window manager. Its standard definition is @code{ignore}; since the -frame has already been iconified, Emacs has no work to do. The purpose -of this event type is so that you can keep track of such events if you -want to. - -@cindex @code{make-frame-visible} event -@item (make-frame-visible (@var{frame})) -This kind of event indicates that the user deiconified @var{frame} using -the window manager. Its standard definition is @code{ignore}; since the -frame has already been made visible, Emacs has no work to do. - -@cindex @code{wheel-up} event -@cindex @code{wheel-down} event -@item (wheel-up @var{position}) -@item (wheel-down @var{position}) -These kinds of event are generated by moving a mouse wheel. Their -usual meaning is a kind of scroll or zoom. - -The element @var{position} is a list describing the position of the -event, in the same format as used in a mouse-click event (@pxref{Click -Events}). - -@vindex mouse-wheel-up-event -@vindex mouse-wheel-down-event -This kind of event is generated only on some kinds of systems. On some -systems, @code{mouse-4} and @code{mouse-5} are used instead. For -portable code, use the variables @code{mouse-wheel-up-event} and -@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine -what event types to expect for the mouse wheel. - -@cindex @code{drag-n-drop} event -@item (drag-n-drop @var{position} @var{files}) -This kind of event is generated when a group of files is -selected in an application outside of Emacs, and then dragged and -dropped onto an Emacs frame. - -The element @var{position} is a list describing the position of the -event, in the same format as used in a mouse-click event (@pxref{Click -Events}), and @var{files} is the list of file names that were dragged -and dropped. The usual way to handle this event is by visiting these -files. - -This kind of event is generated, at present, only on some kinds of -systems. - -@cindex @code{help-echo} event -@item help-echo -This kind of event is generated when a mouse pointer moves onto a -portion of buffer text which has a @code{help-echo} text property. -The generated event has this form: - -@example -(help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos}) -@end example - -@noindent -The precise meaning of the event parameters and the way these -parameters are used to display the help-echo text are described in -@ref{Text help-echo}. - -@cindex @code{sigusr1} event -@cindex @code{sigusr2} event -@cindex user signals -@item sigusr1 -@itemx sigusr2 -These events are generated when the Emacs process receives -the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no -additional data because signals do not carry additional information. -They can be useful for debugging (@pxref{Error Debugging}). - -To catch a user signal, bind the corresponding event to an interactive -command in the @code{special-event-map} (@pxref{Active Keymaps}). -The command is called with no arguments, and the specific signal event is -available in @code{last-input-event}. For example: - -@smallexample -(defun sigusr-handler () - (interactive) - (message "Caught signal %S" last-input-event)) - -(define-key special-event-map [sigusr1] 'sigusr-handler) -@end smallexample - -To test the signal handler, you can make Emacs send a signal to itself: - -@smallexample -(signal-process (emacs-pid) 'sigusr1) -@end smallexample -@end table - - If one of these events arrives in the middle of a key sequence---that -is, after a prefix key---then Emacs reorders the events so that this -event comes either before or after the multi-event key sequence, not -within it. - -@node Event Examples -@subsection Event Examples - -If the user presses and releases the left mouse button over the same -location, that generates a sequence of events like this: - -@smallexample -(down-mouse-1 (# 2613 (0 . 38) -864320)) -(mouse-1 (# 2613 (0 . 38) -864180)) -@end smallexample - -While holding the control key down, the user might hold down the -second mouse button, and drag the mouse from one line to the next. -That produces two events, as shown here: - -@smallexample -(C-down-mouse-2 (# 3440 (0 . 27) -731219)) -(C-drag-mouse-2 (# 3440 (0 . 27) -731219) - (# 3510 (0 . 28) -729648)) -@end smallexample - -While holding down the meta and shift keys, the user might press the -second mouse button on the window's mode line, and then drag the mouse -into another window. That produces a pair of events like these: - -@smallexample -(M-S-down-mouse-2 (# mode-line (33 . 31) -457844)) -(M-S-drag-mouse-2 (# mode-line (33 . 31) -457844) - (# 161 (33 . 3) - -453816)) -@end smallexample - -To handle a SIGUSR1 signal, define an interactive function, and -bind it to the @code{signal usr1} event sequence: - -@smallexample -(defun usr1-handler () - (interactive) - (message "Got USR1 signal")) -(global-set-key [signal usr1] 'usr1-handler) -@end smallexample - -@node Classifying Events -@subsection Classifying Events -@cindex event type - - Every event has an @dfn{event type}, which classifies the event for -key binding purposes. For a keyboard event, the event type equals the -event value; thus, the event type for a character is the character, and -the event type for a function key symbol is the symbol itself. For -events that are lists, the event type is the symbol in the @sc{car} of -the list. Thus, the event type is always a symbol or a character. - - Two events of the same type are equivalent where key bindings are -concerned; thus, they always run the same command. That does not -necessarily mean they do the same things, however, as some commands look -at the whole event to decide what to do. For example, some commands use -the location of a mouse event to decide where in the buffer to act. - - Sometimes broader classifications of events are useful. For example, -you might want to ask whether an event involved the @key{META} key, -regardless of which other key or mouse button was used. - - The functions @code{event-modifiers} and @code{event-basic-type} are -provided to get such information conveniently. - -@defun event-modifiers event -This function returns a list of the modifiers that @var{event} has. The -modifiers are symbols; they include @code{shift}, @code{control}, -@code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition, -the modifiers list of a mouse event symbol always contains one of -@code{click}, @code{drag}, and @code{down}. For double or triple -events, it also contains @code{double} or @code{triple}. - -The argument @var{event} may be an entire event object, or just an -event type. If @var{event} is a symbol that has never been used in an -event that has been read as input in the current Emacs session, then -@code{event-modifiers} can return @code{nil}, even when @var{event} -actually has modifiers. - -Here are some examples: - -@example -(event-modifiers ?a) - @result{} nil -(event-modifiers ?A) - @result{} (shift) -(event-modifiers ?\C-a) - @result{} (control) -(event-modifiers ?\C-%) - @result{} (control) -(event-modifiers ?\C-\S-a) - @result{} (control shift) -(event-modifiers 'f5) - @result{} nil -(event-modifiers 's-f5) - @result{} (super) -(event-modifiers 'M-S-f5) - @result{} (meta shift) -(event-modifiers 'mouse-1) - @result{} (click) -(event-modifiers 'down-mouse-1) - @result{} (down) -@end example - -The modifiers list for a click event explicitly contains @code{click}, -but the event symbol name itself does not contain @samp{click}. -@end defun - -@defun event-basic-type event -This function returns the key or mouse button that @var{event} -describes, with all modifiers removed. The @var{event} argument is as -in @code{event-modifiers}. For example: - -@example -(event-basic-type ?a) - @result{} 97 -(event-basic-type ?A) - @result{} 97 -(event-basic-type ?\C-a) - @result{} 97 -(event-basic-type ?\C-\S-a) - @result{} 97 -(event-basic-type 'f5) - @result{} f5 -(event-basic-type 's-f5) - @result{} f5 -(event-basic-type 'M-S-f5) - @result{} f5 -(event-basic-type 'down-mouse-1) - @result{} mouse-1 -@end example -@end defun - -@defun mouse-movement-p object -This function returns non-@code{nil} if @var{object} is a mouse movement -event. -@end defun - -@defun event-convert-list list -This function converts a list of modifier names and a basic event type -to an event type which specifies all of them. The basic event type -must be the last element of the list. For example, - -@example -(event-convert-list '(control ?a)) - @result{} 1 -(event-convert-list '(control meta ?a)) - @result{} -134217727 -(event-convert-list '(control super f1)) - @result{} C-s-f1 -@end example -@end defun - -@node Accessing Mouse -@subsection Accessing Mouse Events -@cindex mouse events, data in - - This section describes convenient functions for accessing the data in -a mouse button or motion event. - - These two functions return the starting or ending position of a -mouse-button event, as a list of this form (@pxref{Click Events}): - -@example -(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} - @var{object} @var{text-pos} (@var{col} . @var{row}) - @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height})) -@end example - -@defun event-start event -This returns the starting position of @var{event}. - -If @var{event} is a click or button-down event, this returns the -location of the event. If @var{event} is a drag event, this returns the -drag's starting position. -@end defun - -@defun event-end event -This returns the ending position of @var{event}. - -If @var{event} is a drag event, this returns the position where the user -released the mouse button. If @var{event} is a click or button-down -event, the value is actually the starting position, which is the only -position such events have. -@end defun - -@cindex mouse position list, accessing - These functions take a position list as described above, and -return various parts of it. - -@defun posn-window position -Return the window that @var{position} is in. -@end defun - -@defun posn-area position -Return the window area recorded in @var{position}. It returns @code{nil} -when the event occurred in the text area of the window; otherwise, it -is a symbol identifying the area in which the event occurred. -@end defun - -@defun posn-point position -Return the buffer position in @var{position}. When the event occurred -in the text area of the window, in a marginal area, or on a fringe, -this is an integer specifying a buffer position. Otherwise, the value -is undefined. -@end defun - -@defun posn-x-y position -Return the pixel-based x and y coordinates in @var{position}, as a -cons cell @code{(@var{x} . @var{y})}. These coordinates are relative -to the window given by @code{posn-window}. - -This example shows how to convert the window-relative coordinates in -the text area of a window into frame-relative coordinates: - -@example -(defun frame-relative-coordinates (position) - "Return frame-relative coordinates from POSITION. -POSITION is assumed to lie in a window text area." - (let* ((x-y (posn-x-y position)) - (window (posn-window position)) - (edges (window-inside-pixel-edges window))) - (cons (+ (car x-y) (car edges)) - (+ (cdr x-y) (cadr edges))))) -@end example -@end defun - -@defun posn-col-row position -This function returns a cons cell @code{(@var{col} . @var{row})}, -containing the estimated column and row corresponding to buffer -position @var{position}. The return value is given in units of the -frame's default character width and height, as computed from the -@var{x} and @var{y} values corresponding to @var{position}. (So, if -the actual characters have non-default sizes, the actual row and -column may differ from these computed values.) - -Note that @var{row} is counted from the top of the text area. If the -window possesses a header line (@pxref{Header Lines}), it is -@emph{not} counted as the first line. -@end defun - -@defun posn-actual-col-row position -Return the actual row and column in @var{position}, as a cons cell -@code{(@var{col} . @var{row})}. The values are the actual row and -column numbers in the window. @xref{Click Events}, for details. It -returns @code{nil} if @var{position} does not include actual positions -values. -@end defun - -@defun posn-string position -Return the string object in @var{position}, either @code{nil}, or a -cons cell @code{(@var{string} . @var{string-pos})}. -@end defun - -@defun posn-image position -Return the image object in @var{position}, either @code{nil}, or an -image @code{(image ...)}. -@end defun - -@defun posn-object position -Return the image or string object in @var{position}, either -@code{nil}, an image @code{(image ...)}, or a cons cell -@code{(@var{string} . @var{string-pos})}. -@end defun - -@defun posn-object-x-y position -Return the pixel-based x and y coordinates relative to the upper left -corner of the object in @var{position} as a cons cell @code{(@var{dx} -. @var{dy})}. If the @var{position} is a buffer position, return the -relative position in the character at that position. -@end defun - -@defun posn-object-width-height position -Return the pixel width and height of the object in @var{position} as a -cons cell @code{(@var{width} . @var{height})}. If the @var{position} -is a buffer position, return the size of the character at that position. -@end defun - -@cindex timestamp of a mouse event -@defun posn-timestamp position -Return the timestamp in @var{position}. This is the time at which the -event occurred, in milliseconds. -@end defun - - These functions compute a position list given particular buffer -position or screen position. You can access the data in this position -list with the functions described above. - -@defun posn-at-point &optional pos window -This function returns a position list for position @var{pos} in -@var{window}. @var{pos} defaults to point in @var{window}; -@var{window} defaults to the selected window. - -@code{posn-at-point} returns @code{nil} if @var{pos} is not visible in -@var{window}. -@end defun - -@defun posn-at-x-y x y &optional frame-or-window whole -This function returns position information corresponding to pixel -coordinates @var{x} and @var{y} in a specified frame or window, -@var{frame-or-window}, which defaults to the selected window. -The coordinates @var{x} and @var{y} are relative to the -frame or window used. -If @var{whole} is @code{nil}, the coordinates are relative -to the window text area, otherwise they are relative to -the entire window area including scroll bars, margins and fringes. -@end defun - -@node Accessing Scroll -@subsection Accessing Scroll Bar Events -@cindex scroll bar events, data in - - These functions are useful for decoding scroll bar events. - -@defun scroll-bar-event-ratio event -This function returns the fractional vertical position of a scroll bar -event within the scroll bar. The value is a cons cell -@code{(@var{portion} . @var{whole})} containing two integers whose ratio -is the fractional position. -@end defun - -@defun scroll-bar-scale ratio total -This function multiplies (in effect) @var{ratio} by @var{total}, -rounding the result to an integer. The argument @var{ratio} is not a -number, but rather a pair @code{(@var{num} . @var{denom})}---typically a -value returned by @code{scroll-bar-event-ratio}. - -This function is handy for scaling a position on a scroll bar into a -buffer position. Here's how to do that: - -@example -(+ (point-min) - (scroll-bar-scale - (posn-x-y (event-start event)) - (- (point-max) (point-min)))) -@end example - -Recall that scroll bar events have two integers forming a ratio, in place -of a pair of x and y coordinates. -@end defun - -@node Strings of Events -@subsection Putting Keyboard Events in Strings -@cindex keyboard events in strings -@cindex strings with keyboard events - - In most of the places where strings are used, we conceptualize the -string as containing text characters---the same kind of characters found -in buffers or files. Occasionally Lisp programs use strings that -conceptually contain keyboard characters; for example, they may be key -sequences or keyboard macro definitions. However, storing keyboard -characters in a string is a complex matter, for reasons of historical -compatibility, and it is not always possible. - - We recommend that new programs avoid dealing with these complexities -by not storing keyboard events in strings. Here is how to do that: - -@itemize @bullet -@item -Use vectors instead of strings for key sequences, when you plan to use -them for anything other than as arguments to @code{lookup-key} and -@code{define-key}. For example, you can use -@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and -@code{this-command-keys-vector} instead of @code{this-command-keys}. - -@item -Use vectors to write key sequence constants containing meta characters, -even when passing them directly to @code{define-key}. - -@item -When you have to look at the contents of a key sequence that might be a -string, use @code{listify-key-sequence} (@pxref{Event Input Misc}) -first, to convert it to a list. -@end itemize - - The complexities stem from the modifier bits that keyboard input -characters can include. Aside from the Meta modifier, none of these -modifier bits can be included in a string, and the Meta modifier is -allowed only in special cases. - - The earliest GNU Emacs versions represented meta characters as codes -in the range of 128 to 255. At that time, the basic character codes -ranged from 0 to 127, so all keyboard character codes did fit in a -string. Many Lisp programs used @samp{\M-} in string constants to stand -for meta characters, especially in arguments to @code{define-key} and -similar functions, and key sequences and sequences of events were always -represented as strings. - - When we added support for larger basic character codes beyond 127, and -additional modifier bits, we had to change the representation of meta -characters. Now the flag that represents the Meta modifier in a -character is -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -and such numbers cannot be included in a string. - - To support programs with @samp{\M-} in string constants, there are -special rules for including certain meta characters in a string. -Here are the rules for interpreting a string as a sequence of input -characters: - -@itemize @bullet -@item -If the keyboard character value is in the range of 0 to 127, it can go -in the string unchanged. - -@item -The meta variants of those characters, with codes in the range of -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -to -@tex -@math{2^{27} + 127}, -@end tex -@ifnottex -2**27+127, -@end ifnottex -can also go in the string, but you must change their -numeric values. You must set the -@tex -@math{2^{7}} -@end tex -@ifnottex -2**7 -@end ifnottex -bit instead of the -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -bit, resulting in a value between 128 and 255. Only a unibyte string -can include these codes. - -@item -Non-@acronym{ASCII} characters above 256 can be included in a multibyte string. - -@item -Other keyboard character events cannot fit in a string. This includes -keyboard events in the range of 128 to 255. -@end itemize - - Functions such as @code{read-key-sequence} that construct strings of -keyboard input characters follow these rules: they construct vectors -instead of strings, when the events won't fit in a string. - - When you use the read syntax @samp{\M-} in a string, it produces a -code in the range of 128 to 255---the same code that you get if you -modify the corresponding keyboard event to put it in the string. Thus, -meta events in strings work consistently regardless of how they get into -the strings. - - However, most programs would do well to avoid these issues by -following the recommendations at the beginning of this section. - -@node Reading Input -@section Reading Input -@cindex read input -@cindex keyboard input - - The editor command loop reads key sequences using the function -@code{read-key-sequence}, which uses @code{read-event}. These and other -functions for event input are also available for use in Lisp programs. -See also @code{momentary-string-display} in @ref{Temporary Displays}, -and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for -functions and variables for controlling terminal input modes and -debugging terminal input. - - For higher-level input facilities, see @ref{Minibuffers}. - -@menu -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. -@end menu - -@node Key Sequence Input -@subsection Key Sequence Input -@cindex key sequence input - - The command loop reads input a key sequence at a time, by calling -@code{read-key-sequence}. Lisp programs can also call this function; -for example, @code{describe-key} uses it to read the key to describe. - -@defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop -This function reads a key sequence and returns it as a string or -vector. It keeps reading events until it has accumulated a complete key -sequence; that is, enough to specify a non-prefix command using the -currently active keymaps. (Remember that a key sequence that starts -with a mouse event is read using the keymaps of the buffer in the -window that the mouse was in, not the current buffer.) - -If the events are all characters and all can fit in a string, then -@code{read-key-sequence} returns a string (@pxref{Strings of Events}). -Otherwise, it returns a vector, since a vector can hold all kinds of -events---characters, symbols, and lists. The elements of the string or -vector are the events in the key sequence. - -Reading a key sequence includes translating the events in various -ways. @xref{Translation Keymaps}. - -The argument @var{prompt} is either a string to be displayed in the -echo area as a prompt, or @code{nil}, meaning not to display a prompt. -The argument @var{continue-echo}, if non-@code{nil}, means to echo -this key as a continuation of the previous key. - -Normally any upper case event is converted to lower case if the -original event is undefined and the lower case equivalent is defined. -The argument @var{dont-downcase-last}, if non-@code{nil}, means do not -convert the last event to lower case. This is appropriate for reading -a key sequence to be defined. - -The argument @var{switch-frame-ok}, if non-@code{nil}, means that this -function should process a @code{switch-frame} event if the user -switches frames before typing anything. If the user switches frames -in the middle of a key sequence, or at the start of the sequence but -@var{switch-frame-ok} is @code{nil}, then the event will be put off -until after the current key sequence. - -The argument @var{command-loop}, if non-@code{nil}, means that this -key sequence is being read by something that will read commands one -after another. It should be @code{nil} if the caller will read just -one key sequence. - -In the following example, Emacs displays the prompt @samp{?} in the -echo area, and then the user types @kbd{C-x C-f}. - -@example -(read-key-sequence "?") - -@group ----------- Echo Area ---------- -?@kbd{C-x C-f} ----------- Echo Area ---------- - - @result{} "^X^F" -@end group -@end example - -The function @code{read-key-sequence} suppresses quitting: @kbd{C-g} -typed while reading with this function works like any other character, -and does not set @code{quit-flag}. @xref{Quitting}. -@end defun - -@defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop -This is like @code{read-key-sequence} except that it always -returns the key sequence as a vector, never as a string. -@xref{Strings of Events}. -@end defun - -@cindex upper case key sequence -@cindex downcasing in @code{lookup-key} -@cindex shift-translation -If an input character is upper-case (or has the shift modifier) and -has no key binding, but its lower-case equivalent has one, then -@code{read-key-sequence} converts the character to lower case. Note -that @code{lookup-key} does not perform case conversion in this way. - -@vindex this-command-keys-shift-translated -When reading input results in such a @dfn{shift-translation}, Emacs -sets the variable @code{this-command-keys-shift-translated} to a -non-@code{nil} value. Lisp programs can examine this variable if they -need to modify their behavior when invoked by shift-translated keys. -For example, the function @code{handle-shift-selection} examines the -value of this variable to determine how to activate or deactivate the -region (@pxref{The Mark, handle-shift-selection}). - -The function @code{read-key-sequence} also transforms some mouse events. -It converts unbound drag events into click events, and discards unbound -button-down events entirely. It also reshuffles focus events and -miscellaneous window events so that they never appear in a key sequence -with any other events. - -@cindex @code{header-line} prefix key -@cindex @code{mode-line} prefix key -@cindex @code{vertical-line} prefix key -@cindex @code{horizontal-scroll-bar} prefix key -@cindex @code{vertical-scroll-bar} prefix key -@cindex @code{menu-bar} prefix key -@cindex mouse events, in special parts of frame -When mouse events occur in special parts of a window, such as a mode -line or a scroll bar, the event type shows nothing special---it is the -same symbol that would normally represent that combination of mouse -button and modifier keys. The information about the window part is kept -elsewhere in the event---in the coordinates. But -@code{read-key-sequence} translates this information into imaginary -``prefix keys'', all of which are symbols: @code{header-line}, -@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line}, -@code{vertical-line}, and @code{vertical-scroll-bar}. You can define -meanings for mouse clicks in special window parts by defining key -sequences using these imaginary prefix keys. - -For example, if you call @code{read-key-sequence} and then click the -mouse on the window's mode line, you get two events, like this: - -@example -(read-key-sequence "Click on the mode line: ") - @result{} [mode-line - (mouse-1 - (# mode-line - (40 . 63) 5959987))] -@end example - -@defvar num-input-keys -@c Emacs 19 feature -This variable's value is the number of key sequences processed so far in -this Emacs session. This includes key sequences read from the terminal -and key sequences read from keyboard macros being executed. -@end defvar - -@node Reading One Event -@subsection Reading One Event -@cindex reading a single event -@cindex event, reading only one - - The lowest level functions for command input are @code{read-event}, -@code{read-char}, and @code{read-char-exclusive}. - -@defun read-event &optional prompt inherit-input-method seconds -This function reads and returns the next event of command input, waiting -if necessary until an event is available. Events can come directly from -the user or from a keyboard macro. - -If the optional argument @var{prompt} is non-@code{nil}, it should be a -string to display in the echo area as a prompt. Otherwise, -@code{read-event} does not display any message to indicate it is waiting -for input; instead, it prompts by echoing: it displays descriptions of -the events that led to or were read by the current command. @xref{The -Echo Area}. - -If @var{inherit-input-method} is non-@code{nil}, then the current input -method (if any) is employed to make it possible to enter a -non-@acronym{ASCII} character. Otherwise, input method handling is disabled -for reading this event. - -If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event} -moves the cursor temporarily to the echo area, to the end of any message -displayed there. Otherwise @code{read-event} does not move the cursor. - -If @var{seconds} is non-@code{nil}, it should be a number specifying -the maximum time to wait for input, in seconds. If no input arrives -within that time, @code{read-event} stops waiting and returns -@code{nil}. A floating-point value for @var{seconds} means to wait -for a fractional number of seconds. Some systems support only a whole -number of seconds; on these systems, @var{seconds} is rounded down. -If @var{seconds} is @code{nil}, @code{read-event} waits as long as -necessary for input to arrive. - -If @var{seconds} is @code{nil}, Emacs is considered idle while waiting -for user input to arrive. Idle timers---those created with -@code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this -period. However, if @var{seconds} is non-@code{nil}, the state of -idleness remains unchanged. If Emacs is non-idle when -@code{read-event} is called, it remains non-idle throughout the -operation of @code{read-event}; if Emacs is idle (which can happen if -the call happens inside an idle timer), it remains idle. - -If @code{read-event} gets an event that is defined as a help character, -then in some cases @code{read-event} processes the event directly without -returning. @xref{Help Functions}. Certain other events, called -@dfn{special events}, are also processed directly within -@code{read-event} (@pxref{Special Events}). - -Here is what happens if you call @code{read-event} and then press the -right-arrow function key: - -@example -@group -(read-event) - @result{} right -@end group -@end example -@end defun - -@defun read-char &optional prompt inherit-input-method seconds -This function reads and returns a character of command input. If the -user generates an event which is not a character (i.e. a mouse click or -function key event), @code{read-char} signals an error. The arguments -work as in @code{read-event}. - -In the first example, the user types the character @kbd{1} (@acronym{ASCII} -code 49). The second example shows a keyboard macro definition that -calls @code{read-char} from the minibuffer using @code{eval-expression}. -@code{read-char} reads the keyboard macro's very next character, which -is @kbd{1}. Then @code{eval-expression} displays its return value in -the echo area. - -@example -@group -(read-char) - @result{} 49 -@end group - -@group -;; @r{We assume here you use @kbd{M-:} to evaluate this.} -(symbol-function 'foo) - @result{} "^[:(read-char)^M1" -@end group -@group -(execute-kbd-macro 'foo) - @print{} 49 - @result{} nil -@end group -@end example -@end defun - -@defun read-char-exclusive &optional prompt inherit-input-method seconds -This function reads and returns a character of command input. If the -user generates an event which is not a character, -@code{read-char-exclusive} ignores it and reads another event, until it -gets a character. The arguments work as in @code{read-event}. -@end defun - - None of the above functions suppress quitting. - -@defvar num-nonmacro-input-events -This variable holds the total number of input events received so far -from the terminal---not counting those generated by keyboard macros. -@end defvar - - We emphasize that, unlike @code{read-key-sequence}, the functions -@code{read-event}, @code{read-char}, and @code{read-char-exclusive} do -not perform the translations described in @ref{Translation Keymaps}. -If you wish to read a single key taking these translations into -account, use the function @code{read-key}: - -@defun read-key &optional prompt -This function reads a single key. It is ``intermediate'' between -@code{read-key-sequence} and @code{read-event}. Unlike the former, it -reads a single key, not a key sequence. Unlike the latter, it does -not return a raw event, but decodes and translates the user input -according to @code{input-decode-map}, @code{local-function-key-map}, -and @code{key-translation-map} (@pxref{Translation Keymaps}). - -The argument @var{prompt} is either a string to be displayed in the -echo area as a prompt, or @code{nil}, meaning not to display a prompt. -@end defun - -@defun read-char-choice prompt chars &optional inhibit-quit -This function uses @code{read-key} to read and return a single -character. It ignores any input that is not a member of @var{chars}, -a list of accepted characters. Optionally, it will also ignore -keyboard-quit events while it is waiting for valid input. If you bind -@code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value -while calling @code{read-char-choice}, then pressing @code{help-char} -causes it to evaluate @code{help-form} and display the result. It -then continues to wait for a valid input character, or keyboard-quit. -@end defun - -@node Event Mod -@subsection Modifying and Translating Input Events - - Emacs modifies every event it reads according to -@code{extra-keyboard-modifiers}, then translates it through -@code{keyboard-translate-table} (if applicable), before returning it -from @code{read-event}. - -@c Emacs 19 feature -@defvar extra-keyboard-modifiers -This variable lets Lisp programs ``press'' the modifier keys on the -keyboard. The value is a character. Only the modifiers of the -character matter. Each time the user types a keyboard key, it is -altered as if those modifier keys were held down. For instance, if -you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all -keyboard input characters typed during the scope of the binding will -have the control and meta modifiers applied to them. The character -@code{?\C-@@}, equivalent to the integer 0, does not count as a control -character for this purpose, but as a character with no modifiers. -Thus, setting @code{extra-keyboard-modifiers} to zero cancels any -modification. - -When using a window system, the program can ``press'' any of the -modifier keys in this way. Otherwise, only the @key{CTL} and @key{META} -keys can be virtually pressed. - -Note that this variable applies only to events that really come from -the keyboard, and has no effect on mouse events or any other events. -@end defvar - -@defvar keyboard-translate-table -This terminal-local variable is the translate table for keyboard -characters. It lets you reshuffle the keys on the keyboard without -changing any command bindings. Its value is normally a char-table, or -else @code{nil}. (It can also be a string or vector, but this is -considered obsolete.) - -If @code{keyboard-translate-table} is a char-table -(@pxref{Char-Tables}), then each character read from the keyboard is -looked up in this char-table. If the value found there is -non-@code{nil}, then it is used instead of the actual input character. - -Note that this translation is the first thing that happens to a -character after it is read from the terminal. Record-keeping features -such as @code{recent-keys} and dribble files record the characters after -translation. - -Note also that this translation is done before the characters are -supplied to input methods (@pxref{Input Methods}). Use -@code{translation-table-for-input} (@pxref{Translation of Characters}), -if you want to translate characters after input methods operate. -@end defvar - -@defun keyboard-translate from to -This function modifies @code{keyboard-translate-table} to translate -character code @var{from} into character code @var{to}. It creates -the keyboard translate table if necessary. -@end defun - - Here's an example of using the @code{keyboard-translate-table} to -make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste -operations: - -@example -(keyboard-translate ?\C-x 'control-x) -(keyboard-translate ?\C-c 'control-c) -(keyboard-translate ?\C-v 'control-v) -(global-set-key [control-x] 'kill-region) -(global-set-key [control-c] 'kill-ring-save) -(global-set-key [control-v] 'yank) -@end example - -@noindent -On a graphical terminal that supports extended @acronym{ASCII} input, -you can still get the standard Emacs meanings of one of those -characters by typing it with the shift key. That makes it a different -character as far as keyboard translation is concerned, but it has the -same usual meaning. - - @xref{Translation Keymaps}, for mechanisms that translate event sequences -at the level of @code{read-key-sequence}. - -@node Invoking the Input Method -@subsection Invoking the Input Method - - The event-reading functions invoke the current input method, if any -(@pxref{Input Methods}). If the value of @code{input-method-function} -is non-@code{nil}, it should be a function; when @code{read-event} reads -a printing character (including @key{SPC}) with no modifier bits, it -calls that function, passing the character as an argument. - -@defvar input-method-function -If this is non-@code{nil}, its value specifies the current input method -function. - -@strong{Warning:} don't bind this variable with @code{let}. It is often -buffer-local, and if you bind it around reading input (which is exactly -when you @emph{would} bind it), switching buffers asynchronously while -Emacs is waiting will cause the value to be restored in the wrong -buffer. -@end defvar - - The input method function should return a list of events which should -be used as input. (If the list is @code{nil}, that means there is no -input, so @code{read-event} waits for another event.) These events are -processed before the events in @code{unread-command-events} -(@pxref{Event Input Misc}). Events -returned by the input method function are not passed to the input method -function again, even if they are printing characters with no modifier -bits. - - If the input method function calls @code{read-event} or -@code{read-key-sequence}, it should bind @code{input-method-function} to -@code{nil} first, to prevent recursion. - - The input method function is not called when reading the second and -subsequent events of a key sequence. Thus, these characters are not -subject to input method processing. The input method function should -test the values of @code{overriding-local-map} and -@code{overriding-terminal-local-map}; if either of these variables is -non-@code{nil}, the input method should put its argument into a list and -return that list with no further processing. - -@node Quoted Character Input -@subsection Quoted Character Input -@cindex quoted character input - - You can use the function @code{read-quoted-char} to ask the user to -specify a character, and allow the user to specify a control or meta -character conveniently, either literally or as an octal character code. -The command @code{quoted-insert} uses this function. - -@defun read-quoted-char &optional prompt -@cindex octal character input -@cindex control characters, reading -@cindex nonprinting characters, reading -This function is like @code{read-char}, except that if the first -character read is an octal digit (0-7), it reads any number of octal -digits (but stopping if a non-octal digit is found), and returns the -character represented by that numeric character code. If the -character that terminates the sequence of octal digits is @key{RET}, -it is discarded. Any other terminating character is used as input -after this function returns. - -Quitting is suppressed when the first character is read, so that the -user can enter a @kbd{C-g}. @xref{Quitting}. - -If @var{prompt} is supplied, it specifies a string for prompting the -user. The prompt string is always displayed in the echo area, followed -by a single @samp{-}. - -In the following example, the user types in the octal number 177 (which -is 127 in decimal). - -@example -(read-quoted-char "What character") - -@group ----------- Echo Area ---------- -What character @kbd{1 7 7}- ----------- Echo Area ---------- - - @result{} 127 -@end group -@end example -@end defun - -@need 2000 -@node Event Input Misc -@subsection Miscellaneous Event Input Features - -This section describes how to ``peek ahead'' at events without using -them up, how to check for pending input, and how to discard pending -input. See also the function @code{read-passwd} (@pxref{Reading a -Password}). - -@defvar unread-command-events -@cindex next input -@cindex peeking at input -This variable holds a list of events waiting to be read as command -input. The events are used in the order they appear in the list, and -removed one by one as they are used. - -The variable is needed because in some cases a function reads an event -and then decides not to use it. Storing the event in this variable -causes it to be processed normally, by the command loop or by the -functions to read command input. - -@cindex prefix argument unreading -For example, the function that implements numeric prefix arguments reads -any number of digits. When it finds a non-digit event, it must unread -the event so that it can be read normally by the command loop. -Likewise, incremental search uses this feature to unread events with no -special meaning in a search, because these events should exit the search -and then execute normally. - -The reliable and easy way to extract events from a key sequence so as -to put them in @code{unread-command-events} is to use -@code{listify-key-sequence} (see below). - -Normally you add events to the front of this list, so that the events -most recently unread will be reread first. - -Events read from this list are not normally added to the current -command's key sequence (as returned by e.g. @code{this-command-keys}), -as the events will already have been added once as they were read for -the first time. An element of the form @code{(@code{t} . @var{event})} -forces @var{event} to be added to the current command's key sequence. -@end defvar - -@defun listify-key-sequence key -This function converts the string or vector @var{key} to a list of -individual events, which you can put in @code{unread-command-events}. -@end defun - -@ignore -@defvar unread-command-char -This variable holds a character to be read as command input. -A value of -1 means ``empty''. - -This variable is mostly obsolete now that you can use -@code{unread-command-events} instead; it exists only to support programs -written for Emacs versions 18 and earlier. -@end defvar -@end ignore - -@defun input-pending-p -@cindex waiting for command key input -This function determines whether any command input is currently -available to be read. It returns immediately, with value @code{t} if -there is available input, @code{nil} otherwise. On rare occasions it -may return @code{t} when no input is available. -@end defun - -@defvar last-input-event -@defvarx last-input-char -This variable records the last terminal input event read, whether -as part of a command or explicitly by a Lisp program. - -In the example below, the Lisp program reads the character @kbd{1}, -@acronym{ASCII} code 49. It becomes the value of @code{last-input-event}, -while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate -this expression) remains the value of @code{last-command-event}. - -@example -@group -(progn (print (read-char)) - (print last-command-event) - last-input-event) - @print{} 49 - @print{} 5 - @result{} 49 -@end group -@end example - -The alias @code{last-input-char} is obsolete. -@end defvar - -@defmac while-no-input body@dots{} -This construct runs the @var{body} forms and returns the value of the -last one---but only if no input arrives. If any input arrives during -the execution of the @var{body} forms, it aborts them (working much -like a quit). The @code{while-no-input} form returns @code{nil} if -aborted by a real quit, and returns @code{t} if aborted by arrival of -other input. - -If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil}, -arrival of input during those parts won't cause an abort until -the end of that part. - -If you want to be able to distinguish all possible values computed -by @var{body} from both kinds of abort conditions, write the code -like this: - -@example -(while-no-input - (list - (progn . @var{body}))) -@end example -@end defmac - -@defun discard-input -@cindex flushing input -@cindex discarding input -@cindex keyboard macro, terminating -This function discards the contents of the terminal input buffer and -cancels any keyboard macro that might be in the process of definition. -It returns @code{nil}. - -In the following example, the user may type a number of characters right -after starting the evaluation of the form. After the @code{sleep-for} -finishes sleeping, @code{discard-input} discards any characters typed -during the sleep. - -@example -(progn (sleep-for 2) - (discard-input)) - @result{} nil -@end example -@end defun - -@node Special Events -@section Special Events - -@cindex special events -Certain @dfn{special events} are handled at a very low level---as soon -as they are read. The @code{read-event} function processes these -events itself, and never returns them. Instead, it keeps waiting for -the first event that is not special and returns that one. - - Special events do not echo, they are never grouped into key -sequences, and they never appear in the value of -@code{last-command-event} or @code{(this-command-keys)}. They do not -discard a numeric argument, they cannot be unread with -@code{unread-command-events}, they may not appear in a keyboard macro, -and they are not recorded in a keyboard macro while you are defining -one. - - Special events do, however, appear in @code{last-input-event} -immediately after they are read, and this is the way for the event's -definition to find the actual event. - - The events types @code{iconify-frame}, @code{make-frame-visible}, -@code{delete-frame}, @code{drag-n-drop}, and user signals like -@code{sigusr1} are normally handled in this way. The keymap which -defines how to handle special events---and which events are -special---is in the variable @code{special-event-map} (@pxref{Active -Keymaps}). - -@node Waiting -@section Waiting for Elapsed Time or Input -@cindex waiting - - The wait functions are designed to wait for a certain amount of time -to pass or until there is input. For example, you may wish to pause in -the middle of a computation to allow the user time to view the display. -@code{sit-for} pauses and updates the screen, and returns immediately if -input comes in, while @code{sleep-for} pauses without updating the -screen. - -@defun sit-for seconds &optional nodisp -This function performs redisplay (provided there is no pending input -from the user), then waits @var{seconds} seconds, or until input is -available. The usual purpose of @code{sit-for} is to give the user -time to read text that you display. The value is @code{t} if -@code{sit-for} waited the full time with no input arriving -(@pxref{Event Input Misc}). Otherwise, the value is @code{nil}. - -The argument @var{seconds} need not be an integer. If it is a floating -point number, @code{sit-for} waits for a fractional number of seconds. -Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. - -The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)}, -i.e. it requests a redisplay, without any delay, if there is no pending input. -@xref{Forcing Redisplay}. - -If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not -redisplay, but it still returns as soon as input is available (or when -the timeout elapses). - -In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be -interrupted, even by input from the standard input descriptor. It is -thus equivalent to @code{sleep-for}, which is described below. - -It is also possible to call @code{sit-for} with three arguments, -as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})}, -but that is considered obsolete. -@end defun - -@defun sleep-for seconds &optional millisec -This function simply pauses for @var{seconds} seconds without updating -the display. It pays no attention to available input. It returns -@code{nil}. - -The argument @var{seconds} need not be an integer. If it is a floating -point number, @code{sleep-for} waits for a fractional number of seconds. -Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. - -The optional argument @var{millisec} specifies an additional waiting -period measured in milliseconds. This adds to the period specified by -@var{seconds}. If the system doesn't support waiting fractions of a -second, you get an error if you specify nonzero @var{millisec}. - -Use @code{sleep-for} when you wish to guarantee a delay. -@end defun - - @xref{Time of Day}, for functions to get the current time. - -@node Quitting -@section Quitting -@cindex @kbd{C-g} -@cindex quitting -@cindex interrupt Lisp functions - - Typing @kbd{C-g} while a Lisp function is running causes Emacs to -@dfn{quit} whatever it is doing. This means that control returns to the -innermost active command loop. - - Typing @kbd{C-g} while the command loop is waiting for keyboard input -does not cause a quit; it acts as an ordinary input character. In the -simplest case, you cannot tell the difference, because @kbd{C-g} -normally runs the command @code{keyboard-quit}, whose effect is to quit. -However, when @kbd{C-g} follows a prefix key, they combine to form an -undefined key. The effect is to cancel the prefix key as well as any -prefix argument. - - In the minibuffer, @kbd{C-g} has a different definition: it aborts out -of the minibuffer. This means, in effect, that it exits the minibuffer -and then quits. (Simply quitting would return to the command loop -@emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit -directly when the command reader is reading input is so that its meaning -can be redefined in the minibuffer in this way. @kbd{C-g} following a -prefix key is not redefined in the minibuffer, and it has its normal -effect of canceling the prefix key and prefix argument. This too -would not be possible if @kbd{C-g} always quit directly. - - When @kbd{C-g} does directly quit, it does so by setting the variable -@code{quit-flag} to @code{t}. Emacs checks this variable at appropriate -times and quits if it is not @code{nil}. Setting @code{quit-flag} -non-@code{nil} in any way thus causes a quit. - - At the level of C code, quitting cannot happen just anywhere; only at the -special places that check @code{quit-flag}. The reason for this is -that quitting at other places might leave an inconsistency in Emacs's -internal state. Because quitting is delayed until a safe place, quitting -cannot make Emacs crash. - - Certain functions such as @code{read-key-sequence} or -@code{read-quoted-char} prevent quitting entirely even though they wait -for input. Instead of quitting, @kbd{C-g} serves as the requested -input. In the case of @code{read-key-sequence}, this serves to bring -about the special behavior of @kbd{C-g} in the command loop. In the -case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used -to quote a @kbd{C-g}. - -@cindex preventing quitting - You can prevent quitting for a portion of a Lisp function by binding -the variable @code{inhibit-quit} to a non-@code{nil} value. Then, -although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the -usual result of this---a quit---is prevented. Eventually, -@code{inhibit-quit} will become @code{nil} again, such as when its -binding is unwound at the end of a @code{let} form. At that time, if -@code{quit-flag} is still non-@code{nil}, the requested quit happens -immediately. This behavior is ideal when you wish to make sure that -quitting does not happen within a ``critical section'' of the program. - -@cindex @code{read-quoted-char} quitting - In some functions (such as @code{read-quoted-char}), @kbd{C-g} is -handled in a special way that does not involve quitting. This is done -by reading the input with @code{inhibit-quit} bound to @code{t}, and -setting @code{quit-flag} to @code{nil} before @code{inhibit-quit} -becomes @code{nil} again. This excerpt from the definition of -@code{read-quoted-char} shows how this is done; it also shows that -normal quitting is permitted after the first character of input. - -@example -(defun read-quoted-char (&optional prompt) - "@dots{}@var{documentation}@dots{}" - (let ((message-log-max nil) done (first t) (code 0) char) - (while (not done) - (let ((inhibit-quit first) - @dots{}) - (and prompt (message "%s-" prompt)) - (setq char (read-event)) - (if inhibit-quit (setq quit-flag nil))) - @r{@dots{}set the variable @code{code}@dots{}}) - code)) -@end example - -@defvar quit-flag -If this variable is non-@code{nil}, then Emacs quits immediately, unless -@code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets -@code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}. -@end defvar - -@defvar inhibit-quit -This variable determines whether Emacs should quit when @code{quit-flag} -is set to a value other than @code{nil}. If @code{inhibit-quit} is -non-@code{nil}, then @code{quit-flag} has no special effect. -@end defvar - -@defmac with-local-quit body@dots{} -This macro executes @var{body} forms in sequence, but allows quitting, at -least locally, within @var{body} even if @code{inhibit-quit} was -non-@code{nil} outside this construct. It returns the value of the -last form in @var{body}, unless exited by quitting, in which case -it returns @code{nil}. - -If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit}, -it only executes the @var{body}, and setting @code{quit-flag} causes -a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so -that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag} -triggers a special kind of local quit. This ends the execution of -@var{body} and exits the @code{with-local-quit} body with -@code{quit-flag} still non-@code{nil}, so that another (ordinary) quit -will happen as soon as that is allowed. If @code{quit-flag} is -already non-@code{nil} at the beginning of @var{body}, the local quit -happens immediately and the body doesn't execute at all. - -This macro is mainly useful in functions that can be called from -timers, process filters, process sentinels, @code{pre-command-hook}, -@code{post-command-hook}, and other places where @code{inhibit-quit} is -normally bound to @code{t}. -@end defmac - -@deffn Command keyboard-quit -This function signals the @code{quit} condition with @code{(signal 'quit -nil)}. This is the same thing that quitting does. (See @code{signal} -in @ref{Errors}.) -@end deffn - - You can specify a character other than @kbd{C-g} to use for quitting. -See the function @code{set-input-mode} in @ref{Terminal Input}. - -@node Prefix Command Arguments -@section Prefix Command Arguments -@cindex prefix argument -@cindex raw prefix argument -@cindex numeric prefix argument - - Most Emacs commands can use a @dfn{prefix argument}, a number -specified before the command itself. (Don't confuse prefix arguments -with prefix keys.) The prefix argument is at all times represented by a -value, which may be @code{nil}, meaning there is currently no prefix -argument. Each command may use the prefix argument or ignore it. - - There are two representations of the prefix argument: @dfn{raw} and -@dfn{numeric}. The editor command loop uses the raw representation -internally, and so do the Lisp variables that store the information, but -commands can request either representation. - - Here are the possible values of a raw prefix argument: - -@itemize @bullet -@item -@code{nil}, meaning there is no prefix argument. Its numeric value is -1, but numerous commands make a distinction between @code{nil} and the -integer 1. - -@item -An integer, which stands for itself. - -@item -A list of one element, which is an integer. This form of prefix -argument results from one or a succession of @kbd{C-u}s with no -digits. The numeric value is the integer in the list, but some -commands make a distinction between such a list and an integer alone. - -@item -The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was -typed, without following digits. The equivalent numeric value is -@minus{}1, but some commands make a distinction between the integer -@minus{}1 and the symbol @code{-}. -@end itemize - -We illustrate these possibilities by calling the following function with -various prefixes: - -@example -@group -(defun display-prefix (arg) - "Display the value of the raw prefix arg." - (interactive "P") - (message "%s" arg)) -@end group -@end example - -@noindent -Here are the results of calling @code{display-prefix} with various -raw prefix arguments: - -@example - M-x display-prefix @print{} nil - -C-u M-x display-prefix @print{} (4) - -C-u C-u M-x display-prefix @print{} (16) - -C-u 3 M-x display-prefix @print{} 3 - -M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)} - -C-u - M-x display-prefix @print{} - - -M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)} - -C-u - 7 M-x display-prefix @print{} -7 - -M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)} -@end example - - Emacs uses two variables to store the prefix argument: -@code{prefix-arg} and @code{current-prefix-arg}. Commands such as -@code{universal-argument} that set up prefix arguments for other -commands store them in @code{prefix-arg}. In contrast, -@code{current-prefix-arg} conveys the prefix argument to the current -command, so setting it has no effect on the prefix arguments for future -commands. - - Normally, commands specify which representation to use for the prefix -argument, either numeric or raw, in the @code{interactive} specification. -(@xref{Using Interactive}.) Alternatively, functions may look at the -value of the prefix argument directly in the variable -@code{current-prefix-arg}, but this is less clean. - -@defun prefix-numeric-value arg -This function returns the numeric meaning of a valid raw prefix argument -value, @var{arg}. The argument may be a symbol, a number, or a list. -If it is @code{nil}, the value 1 is returned; if it is @code{-}, the -value @minus{}1 is returned; if it is a number, that number is returned; -if it is a list, the @sc{car} of that list (which should be a number) is -returned. -@end defun - -@defvar current-prefix-arg -This variable holds the raw prefix argument for the @emph{current} -command. Commands may examine it directly, but the usual method for -accessing it is with @code{(interactive "P")}. -@end defvar - -@defvar prefix-arg -The value of this variable is the raw prefix argument for the -@emph{next} editing command. Commands such as @code{universal-argument} -that specify prefix arguments for the following command work by setting -this variable. -@end defvar - -@defvar last-prefix-arg -The raw prefix argument value used by the previous command. -@end defvar - - The following commands exist to set up prefix arguments for the -following command. Do not call them for any other reason. - -@deffn Command universal-argument -This command reads input and specifies a prefix argument for the -following command. Don't call this command yourself unless you know -what you are doing. -@end deffn - -@deffn Command digit-argument arg -This command adds to the prefix argument for the following command. The -argument @var{arg} is the raw prefix argument as it was before this -command; it is used to compute the updated prefix argument. Don't call -this command yourself unless you know what you are doing. -@end deffn - -@deffn Command negative-argument arg -This command adds to the numeric argument for the next command. The -argument @var{arg} is the raw prefix argument as it was before this -command; its value is negated to form the new prefix argument. Don't -call this command yourself unless you know what you are doing. -@end deffn - -@node Recursive Editing -@section Recursive Editing -@cindex recursive command loop -@cindex recursive editing level -@cindex command loop, recursive - - The Emacs command loop is entered automatically when Emacs starts up. -This top-level invocation of the command loop never exits; it keeps -running as long as Emacs does. Lisp programs can also invoke the -command loop. Since this makes more than one activation of the command -loop, we call it @dfn{recursive editing}. A recursive editing level has -the effect of suspending whatever command invoked it and permitting the -user to do arbitrary editing before resuming that command. - - The commands available during recursive editing are the same ones -available in the top-level editing loop and defined in the keymaps. -Only a few special commands exit the recursive editing level; the others -return to the recursive editing level when they finish. (The special -commands for exiting are always available, but they do nothing when -recursive editing is not in progress.) - - All command loops, including recursive ones, set up all-purpose error -handlers so that an error in a command run from the command loop will -not exit the loop. - -@cindex minibuffer input - Minibuffer input is a special kind of recursive editing. It has a few -special wrinkles, such as enabling display of the minibuffer and the -minibuffer window, but fewer than you might suppose. Certain keys -behave differently in the minibuffer, but that is only because of the -minibuffer's local map; if you switch windows, you get the usual Emacs -commands. - -@cindex @code{throw} example -@kindex exit -@cindex exit recursive editing -@cindex aborting - To invoke a recursive editing level, call the function -@code{recursive-edit}. This function contains the command loop; it also -contains a call to @code{catch} with tag @code{exit}, which makes it -possible to exit the recursive editing level by throwing to @code{exit} -(@pxref{Catch and Throw}). If you throw a value other than @code{t}, -then @code{recursive-edit} returns normally to the function that called -it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. -Throwing a @code{t} value causes @code{recursive-edit} to quit, so that -control returns to the command loop one level up. This is called -@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). - - Most applications should not use recursive editing, except as part of -using the minibuffer. Usually it is more convenient for the user if you -change the major mode of the current buffer temporarily to a special -major mode, which should have a command to go back to the previous mode. -(The @kbd{e} command in Rmail uses this technique.) Or, if you wish to -give the user different text to edit ``recursively'', create and select -a new buffer in a special mode. In this mode, define a command to -complete the processing and go back to the previous buffer. (The -@kbd{m} command in Rmail does this.) - - Recursive edits are useful in debugging. You can insert a call to -@code{debug} into a function definition as a sort of breakpoint, so that -you can look around when the function gets there. @code{debug} invokes -a recursive edit but also provides the other features of the debugger. - - Recursive editing levels are also used when you type @kbd{C-r} in -@code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}). - -@deffn Command recursive-edit -@cindex suspend evaluation -This function invokes the editor command loop. It is called -automatically by the initialization of Emacs, to let the user begin -editing. When called from a Lisp program, it enters a recursive editing -level. - -If the current buffer is not the same as the selected window's buffer, -@code{recursive-edit} saves and restores the current buffer. Otherwise, -if you switch buffers, the buffer you switched to is current after -@code{recursive-edit} returns. - -In the following example, the function @code{simple-rec} first -advances point one word, then enters a recursive edit, printing out a -message in the echo area. The user can then do any editing desired, and -then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}. - -@example -(defun simple-rec () - (forward-word 1) - (message "Recursive edit in progress") - (recursive-edit) - (forward-word 1)) - @result{} simple-rec -(simple-rec) - @result{} nil -@end example -@end deffn - -@deffn Command exit-recursive-edit -This function exits from the innermost recursive edit (including -minibuffer input). Its definition is effectively @code{(throw 'exit -nil)}. -@end deffn - -@deffn Command abort-recursive-edit -This function aborts the command that requested the innermost recursive -edit (including minibuffer input), by signaling @code{quit} -after exiting the recursive edit. Its definition is effectively -@code{(throw 'exit t)}. @xref{Quitting}. -@end deffn - -@deffn Command top-level -This function exits all recursive editing levels; it does not return a -value, as it jumps completely out of any computation directly back to -the main command loop. -@end deffn - -@defun recursion-depth -This function returns the current depth of recursive edits. When no -recursive edit is active, it returns 0. -@end defun - -@node Disabling Commands -@section Disabling Commands -@cindex disabled command - - @dfn{Disabling a command} marks the command as requiring user -confirmation before it can be executed. Disabling is used for commands -which might be confusing to beginning users, to prevent them from using -the commands by accident. - -@kindex disabled - The low-level mechanism for disabling a command is to put a -non-@code{nil} @code{disabled} property on the Lisp symbol for the -command. These properties are normally set up by the user's -init file (@pxref{Init File}) with Lisp expressions such as this: - -@example -(put 'upcase-region 'disabled t) -@end example - -@noindent -For a few commands, these properties are present by default (you can -remove them in your init file if you wish). - - If the value of the @code{disabled} property is a string, the message -saying the command is disabled includes that string. For example: - -@example -(put 'delete-region 'disabled - "Text deleted this way cannot be yanked back!\n") -@end example - - @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on -what happens when a disabled command is invoked interactively. -Disabling a command has no effect on calling it as a function from Lisp -programs. - -@deffn Command enable-command command -Allow @var{command} (a symbol) to be executed without special -confirmation from now on, and alter the user's init file (@pxref{Init -File}) so that this will apply to future sessions. -@end deffn - -@deffn Command disable-command command -Require special confirmation to execute @var{command} from now on, and -alter the user's init file so that this will apply to future sessions. -@end deffn - -@defvar disabled-command-function -The value of this variable should be a function. When the user -invokes a disabled command interactively, this function is called -instead of the disabled command. It can use @code{this-command-keys} -to determine what the user typed to run the command, and thus find the -command itself. - -The value may also be @code{nil}. Then all commands work normally, -even disabled ones. - -By default, the value is a function that asks the user whether to -proceed. -@end defvar - -@node Command History -@section Command History -@cindex command history -@cindex complex command -@cindex history of commands - - The command loop keeps a history of the complex commands that have -been executed, to make it convenient to repeat these commands. A -@dfn{complex command} is one for which the interactive argument reading -uses the minibuffer. This includes any @kbd{M-x} command, any -@kbd{M-:} command, and any command whose @code{interactive} -specification reads an argument from the minibuffer. Explicit use of -the minibuffer during the execution of the command itself does not cause -the command to be considered complex. - -@defvar command-history -This variable's value is a list of recent complex commands, each -represented as a form to evaluate. It continues to accumulate all -complex commands for the duration of the editing session, but when it -reaches the maximum size (@pxref{Minibuffer History}), the oldest -elements are deleted as new ones are added. - -@example -@group -command-history -@result{} ((switch-to-buffer "chistory.texi") - (describe-key "^X^[") - (visit-tags-table "~/emacs/src/") - (find-tag "repeat-complex-command")) -@end group -@end example -@end defvar - - This history list is actually a special case of minibuffer history -(@pxref{Minibuffer History}), with one special twist: the elements are -expressions rather than strings. - - There are a number of commands devoted to the editing and recall of -previous commands. The commands @code{repeat-complex-command}, and -@code{list-command-history} are described in the user manual -(@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the -minibuffer, the usual minibuffer history commands are available. - -@node Keyboard Macros -@section Keyboard Macros -@cindex keyboard macros - - A @dfn{keyboard macro} is a canned sequence of input events that can -be considered a command and made the definition of a key. The Lisp -representation of a keyboard macro is a string or vector containing the -events. Don't confuse keyboard macros with Lisp macros -(@pxref{Macros}). - -@defun execute-kbd-macro kbdmacro &optional count loopfunc -This function executes @var{kbdmacro} as a sequence of events. If -@var{kbdmacro} is a string or vector, then the events in it are executed -exactly as if they had been input by the user. The sequence is -@emph{not} expected to be a single key sequence; normally a keyboard -macro definition consists of several key sequences concatenated. - -If @var{kbdmacro} is a symbol, then its function definition is used in -place of @var{kbdmacro}. If that is another symbol, this process repeats. -Eventually the result should be a string or vector. If the result is -not a symbol, string, or vector, an error is signaled. - -The argument @var{count} is a repeat count; @var{kbdmacro} is executed that -many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is -executed once. If it is 0, @var{kbdmacro} is executed over and over until it -encounters an error or a failing search. - -If @var{loopfunc} is non-@code{nil}, it is a function that is called, -without arguments, prior to each iteration of the macro. If -@var{loopfunc} returns @code{nil}, then this stops execution of the macro. - -@xref{Reading One Event}, for an example of using @code{execute-kbd-macro}. -@end defun - -@defvar executing-kbd-macro -This variable contains the string or vector that defines the keyboard -macro that is currently executing. It is @code{nil} if no macro is -currently executing. A command can test this variable so as to behave -differently when run from an executing macro. Do not set this variable -yourself. -@end defvar - -@defvar defining-kbd-macro -This variable is non-@code{nil} if and only if a keyboard macro is -being defined. A command can test this variable so as to behave -differently while a macro is being defined. The value is -@code{append} while appending to the definition of an existing macro. -The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and -@code{end-kbd-macro} set this variable---do not set it yourself. - -The variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Terminals}. -@end defvar - -@defvar last-kbd-macro -This variable is the definition of the most recently defined keyboard -macro. Its value is a string or vector, or @code{nil}. - -The variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Terminals}. -@end defvar - -@defvar kbd-macro-termination-hook -This normal hook is run when a keyboard macro terminates, regardless -of what caused it to terminate (reaching the macro end or an error -which ended the macro prematurely). -@end defvar diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi deleted file mode 100644 index 032ba052484..00000000000 --- a/doc/lispref/compile.texi +++ /dev/null @@ -1,742 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/compile -@node Byte Compilation, Advising Functions, Loading, Top -@chapter Byte Compilation -@cindex byte compilation -@cindex byte-code -@cindex compilation (Emacs Lisp) - - Emacs Lisp has a @dfn{compiler} that translates functions written -in Lisp into a special representation called @dfn{byte-code} that can be -executed more efficiently. The compiler replaces Lisp function -definitions with byte-code. When a byte-code function is called, its -definition is evaluated by the @dfn{byte-code interpreter}. - - Because the byte-compiled code is evaluated by the byte-code -interpreter, instead of being executed directly by the machine's -hardware (as true compiled code is), byte-code is completely -transportable from machine to machine without recompilation. It is not, -however, as fast as true compiled code. - - In general, any version of Emacs can run byte-compiled code produced -by recent earlier versions of Emacs, but the reverse is not true. - -@vindex no-byte-compile - If you do not want a Lisp file to be compiled, ever, put a file-local -variable binding for @code{no-byte-compile} into it, like this: - -@example -;; -*-no-byte-compile: t; -*- -@end example - -@menu -* Speed of Byte-Code:: An example of speedup from byte compilation. -* Compilation Functions:: Byte compilation functions. -* Docs and Compilation:: Dynamic loading of documentation strings. -* Dynamic Loading:: Dynamic loading of individual functions. -* Eval During Compile:: Code to be evaluated when you compile. -* Compiler Errors:: Handling compiler error messages. -* Byte-Code Objects:: The data type used for byte-compiled functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. -@end menu - -@node Speed of Byte-Code -@section Performance of Byte-Compiled Code - - A byte-compiled function is not as efficient as a primitive function -written in C, but runs much faster than the version written in Lisp. -Here is an example: - -@example -@group -(defun silly-loop (n) - "Return the time, in seconds, to run N iterations of a loop." - (let ((t1 (float-time))) - (while (> (setq n (1- n)) 0)) - (- (float-time) t1))) -@result{} silly-loop -@end group - -@group -(silly-loop 50000000) -@result{} 10.235304117202759 -@end group - -@group -(byte-compile 'silly-loop) -@result{} @r{[Compiled code not shown]} -@end group - -@group -(silly-loop 50000000) -@result{} 3.705854892730713 -@end group -@end example - - In this example, the interpreted code required 10 seconds to run, -whereas the byte-compiled code required less than 4 seconds. These -results are representative, but actual results may vary. - -@node Compilation Functions -@comment node-name, next, previous, up -@section Byte-Compilation Functions -@cindex compilation functions - - You can byte-compile an individual function or macro definition with -the @code{byte-compile} function. You can compile a whole file with -@code{byte-compile-file}, or several files with -@code{byte-recompile-directory} or @code{batch-byte-compile}. - - Sometimes, the byte compiler produces warning and/or error messages -(@pxref{Compiler Errors}, for details). These messages are recorded -in a buffer called @file{*Compile-Log*}, which uses Compilation mode. -@xref{Compilation Mode,,,emacs, The GNU Emacs Manual}. - -@cindex macro compilation - Be careful when writing macro calls in files that you intend to -byte-compile. Since macro calls are expanded when they are compiled, -the macros need to be loaded into Emacs or the byte compiler will not -do the right thing. The usual way to handle this is with -@code{require} forms which specify the files containing the needed -macro definitions (@pxref{Named Features}). Normally, the -byte compiler does not evaluate the code that it is compiling, but it -handles @code{require} forms specially, by loading the specified -libraries. To avoid loading the macro definition files when someone -@emph{runs} the compiled program, write @code{eval-when-compile} -around the @code{require} calls (@pxref{Eval During Compile}). For -more details, @xref{Compiling Macros}. - - Inline (@code{defsubst}) functions are less troublesome; if you -compile a call to such a function before its definition is known, the -call will still work right, it will just run slower. - -@defun byte-compile symbol -This function byte-compiles the function definition of @var{symbol}, -replacing the previous definition with the compiled one. The function -definition of @var{symbol} must be the actual code for the function; -@code{byte-compile} does not handle function indirection. The return -value is the byte-code function object which is the compiled -definition of @var{symbol} (@pxref{Byte-Code Objects}). - -@example -@group -(defun factorial (integer) - "Compute factorial of INTEGER." - (if (= 1 integer) 1 - (* integer (factorial (1- integer))))) -@result{} factorial -@end group - -@group -(byte-compile 'factorial) -@result{} -#[(integer) - "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" - [integer 1 * factorial] - 4 "Compute factorial of INTEGER."] -@end group -@end example - -If @var{symbol}'s definition is a byte-code function object, -@code{byte-compile} does nothing and returns @code{nil}. It does not -``compile the symbol's definition again'', since the original -(non-compiled) code has already been replaced in the symbol's function -cell by the byte-compiled code. - -The argument to @code{byte-compile} can also be a @code{lambda} -expression. In that case, the function returns the corresponding -compiled code but does not store it anywhere. -@end defun - -@deffn Command compile-defun &optional arg -This command reads the defun containing point, compiles it, and -evaluates the result. If you use this on a defun that is actually a -function definition, the effect is to install a compiled version of that -function. - -@code{compile-defun} normally displays the result of evaluation in the -echo area, but if @var{arg} is non-@code{nil}, it inserts the result -in the current buffer after the form it compiled. -@end deffn - -@deffn Command byte-compile-file filename &optional load -This function compiles a file of Lisp code named @var{filename} into a -file of byte-code. The output file's name is made by changing the -@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in -@samp{.el}, it adds @samp{.elc} to the end of @var{filename}. - -Compilation works by reading the input file one form at a time. If it -is a definition of a function or macro, the compiled function or macro -definition is written out. Other forms are batched together, then each -batch is compiled, and written so that its compiled code will be -executed when the file is read. All comments are discarded when the -input file is read. - -This command returns @code{t} if there were no errors and @code{nil} -otherwise. When called interactively, it prompts for the file name. - -If @var{load} is non-@code{nil}, this command loads the compiled file -after compiling it. Interactively, @var{load} is the prefix argument. - -@example -@group -% ls -l push* --rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el -@end group - -@group -(byte-compile-file "~/emacs/push.el") - @result{} t -@end group - -@group -% ls -l push* --rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el --rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc -@end group -@end example -@end deffn - -@deffn Command byte-recompile-directory directory &optional flag force -@cindex library compilation -This command recompiles every @samp{.el} file in @var{directory} (or -its subdirectories) that needs recompilation. A file needs -recompilation if a @samp{.elc} file exists but is older than the -@samp{.el} file. - -When a @samp{.el} file has no corresponding @samp{.elc} file, -@var{flag} says what to do. If it is @code{nil}, this command ignores -these files. If @var{flag} is 0, it compiles them. If it is neither -@code{nil} nor 0, it asks the user whether to compile each such file, -and asks about each subdirectory as well. - -Interactively, @code{byte-recompile-directory} prompts for -@var{directory} and @var{flag} is the prefix argument. - -If @var{force} is non-@code{nil}, this command recompiles every -@samp{.el} file that has a @samp{.elc} file. - -The returned value is unpredictable. -@end deffn - -@defun batch-byte-compile &optional noforce -This function runs @code{byte-compile-file} on files specified on the -command line. This function must be used only in a batch execution of -Emacs, as it kills Emacs on completion. An error in one file does not -prevent processing of subsequent files, but no output file will be -generated for it, and the Emacs process will terminate with a nonzero -status code. - -If @var{noforce} is non-@code{nil}, this function does not recompile -files that have an up-to-date @samp{.elc} file. - -@example -% emacs -batch -f batch-byte-compile *.el -@end example -@end defun - -@node Docs and Compilation -@section Documentation Strings and Compilation -@cindex dynamic loading of documentation - - Functions and variables loaded from a byte-compiled file access their -documentation strings dynamically from the file whenever needed. This -saves space within Emacs, and makes loading faster because the -documentation strings themselves need not be processed while loading the -file. Actual access to the documentation strings becomes slower as a -result, but this normally is not enough to bother users. - - Dynamic access to documentation strings does have drawbacks: - -@itemize @bullet -@item -If you delete or move the compiled file after loading it, Emacs can no -longer access the documentation strings for the functions and variables -in the file. - -@item -If you alter the compiled file (such as by compiling a new version), -then further access to documentation strings in this file will -probably give nonsense results. -@end itemize - -@noindent -These problems normally occur only if you build Emacs yourself and use -it from the directory where you built it, and you happen to edit -and/or recompile the Lisp source files. They can be easily cured by -reloading each file after recompiling it. - -@cindex @samp{#@@@var{count}} -@cindex @samp{#$} - The dynamic documentation string feature writes compiled files that -use a special Lisp reader construct, @samp{#@@@var{count}}. This -construct skips the next @var{count} characters. It also uses the -@samp{#$} construct, which stands for ``the name of this file, as a -string''. It is usually best not to use these constructs in Lisp source -files, since they are not designed to be clear to humans reading the -file. - - You can disable the dynamic documentation string feature at compile -time by setting @code{byte-compile-dynamic-docstrings} to @code{nil}; -this is useful mainly if you expect to change the file, and you want -Emacs processes that have already loaded it to keep working when the -file changes. You can do this globally, or for one source file by -specifying a file-local binding for the variable. One way to do that -is by adding this string to the file's first line: - -@example --*-byte-compile-dynamic-docstrings: nil;-*- -@end example - -@defopt byte-compile-dynamic-docstrings -If this is non-@code{nil}, the byte compiler generates compiled files -that are set up for dynamic loading of documentation strings. -@end defopt - -@node Dynamic Loading -@section Dynamic Loading of Individual Functions - -@cindex dynamic loading of functions -@cindex lazy loading - When you compile a file, you can optionally enable the @dfn{dynamic -function loading} feature (also known as @dfn{lazy loading}). With -dynamic function loading, loading the file doesn't fully read the -function definitions in the file. Instead, each function definition -contains a place-holder which refers to the file. The first time each -function is called, it reads the full definition from the file, to -replace the place-holder. - - The advantage of dynamic function loading is that loading the file -becomes much faster. This is a good thing for a file which contains -many separate user-callable functions, if using one of them does not -imply you will probably also use the rest. A specialized mode which -provides many keyboard commands often has that usage pattern: a user may -invoke the mode, but use only a few of the commands it provides. - - The dynamic loading feature has certain disadvantages: - -@itemize @bullet -@item -If you delete or move the compiled file after loading it, Emacs can no -longer load the remaining function definitions not already loaded. - -@item -If you alter the compiled file (such as by compiling a new version), -then trying to load any function not already loaded will usually yield -nonsense results. -@end itemize - - These problems will never happen in normal circumstances with -installed Emacs files. But they are quite likely to happen with Lisp -files that you are changing. The easiest way to prevent these problems -is to reload the new compiled file immediately after each recompilation. - - The byte compiler uses the dynamic function loading feature if the -variable @code{byte-compile-dynamic} is non-@code{nil} at compilation -time. Do not set this variable globally, since dynamic loading is -desirable only for certain files. Instead, enable the feature for -specific source files with file-local variable bindings. For example, -you could do it by writing this text in the source file's first line: - -@example --*-byte-compile-dynamic: t;-*- -@end example - -@defvar byte-compile-dynamic -If this is non-@code{nil}, the byte compiler generates compiled files -that are set up for dynamic function loading. -@end defvar - -@defun fetch-bytecode function -If @var{function} is a byte-code function object, this immediately -finishes loading the byte code of @var{function} from its -byte-compiled file, if it is not fully loaded already. Otherwise, -it does nothing. It always returns @var{function}. -@end defun - -@node Eval During Compile -@section Evaluation During Compilation - - These features permit you to write code to be evaluated during -compilation of a program. - -@defspec eval-and-compile body@dots{} -This form marks @var{body} to be evaluated both when you compile the -containing code and when you run it (whether compiled or not). - -You can get a similar result by putting @var{body} in a separate file -and referring to that file with @code{require}. That method is -preferable when @var{body} is large. Effectively @code{require} is -automatically @code{eval-and-compile}, the package is loaded both when -compiling and executing. - -@code{autoload} is also effectively @code{eval-and-compile} too. It's -recognized when compiling, so uses of such a function don't produce -``not known to be defined'' warnings. - -Most uses of @code{eval-and-compile} are fairly sophisticated. - -If a macro has a helper function to build its result, and that macro -is used both locally and outside the package, then -@code{eval-and-compile} should be used to get the helper both when -compiling and then later when running. - -If functions are defined programmatically (with @code{fset} say), then -@code{eval-and-compile} can be used to have that done at compile-time -as well as run-time, so calls to those functions are checked (and -warnings about ``not known to be defined'' suppressed). -@end defspec - -@defspec eval-when-compile body@dots{} -This form marks @var{body} to be evaluated at compile time but not when -the compiled program is loaded. The result of evaluation by the -compiler becomes a constant which appears in the compiled program. If -you load the source file, rather than compiling it, @var{body} is -evaluated normally. - -@cindex compile-time constant -If you have a constant that needs some calculation to produce, -@code{eval-when-compile} can do that at compile-time. For example, - -@lisp -(defvar my-regexp - (eval-when-compile (regexp-opt '("aaa" "aba" "abb")))) -@end lisp - -@cindex macros, at compile time -If you're using another package, but only need macros from it (the -byte compiler will expand those), then @code{eval-when-compile} can be -used to load it for compiling, but not executing. For example, - -@lisp -(eval-when-compile - (require 'my-macro-package)) -@end lisp - -The same sort of thing goes for macros and @code{defsubst} functions -defined locally and only for use within the file. They are needed for -compiling the file, but in most cases they are not needed for -execution of the compiled file. For example, - -@lisp -(eval-when-compile - (unless (fboundp 'some-new-thing) - (defmacro 'some-new-thing () - (compatibility code)))) -@end lisp - -@noindent -This is often good for code that's only a fallback for compatibility -with other versions of Emacs. - -@strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common -Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the -Common Lisp @samp{#.} reader macro (but not when interpreting) is closer -to what @code{eval-when-compile} does. -@end defspec - -@node Compiler Errors -@section Compiler Errors -@cindex compiler errors - - Byte compilation outputs all errors and warnings into the buffer -@file{*Compile-Log*}. The messages include file names and line -numbers that identify the location of the problem. The usual Emacs -commands for operating on compiler diagnostics work properly on these -messages. - - When an error is due to invalid syntax in the program, the byte -compiler might get confused about the errors' exact location. One way -to investigate is to switch to the buffer @w{@file{ *Compiler Input*}}. -(This buffer name starts with a space, so it does not show up in -@kbd{M-x list-buffers}.) This buffer contains the program being -compiled, and point shows how far the byte compiler was able to read; -the cause of the error might be nearby. @xref{Syntax Errors}, for -some tips for locating syntax errors. - - When the byte compiler warns about functions that were used but not -defined, it always reports the line number for the end of the file, -not the locations where the missing functions were called. To find -the latter, you must search for the function names. - - You can suppress the compiler warning for calling an undefined -function @var{func} by conditionalizing the function call on an -@code{fboundp} test, like this: - -@example -(if (fboundp '@var{func}) ...(@var{func} ...)...) -@end example - -@noindent -The call to @var{func} must be in the @var{then-form} of the -@code{if}, and @var{func} must appear quoted in the call to -@code{fboundp}. (This feature operates for @code{cond} as well.) - - You can tell the compiler that a function is defined using -@code{declare-function} (@pxref{Declaring Functions}). Likewise, you -can tell the compiler that a variable is defined using @code{defvar} -with no initial value. - - You can suppress the compiler warning for a specific use of an -undefined variable @var{variable} by conditionalizing its use on a -@code{boundp} test, like this: - -@example -(if (boundp '@var{variable}) ...@var{variable}...) -@end example - -@noindent -The reference to @var{variable} must be in the @var{then-form} of the -@code{if}, and @var{variable} must appear quoted in the call to -@code{boundp}. - - You can suppress any and all compiler warnings within a certain -expression using the construct @code{with-no-warnings}: - -@c This is implemented with a defun, but conceptually it is -@c a special form. - -@defspec with-no-warnings body@dots{} -In execution, this is equivalent to @code{(progn @var{body}...)}, -but the compiler does not issue warnings for anything that occurs -inside @var{body}. - -We recommend that you use this construct around the smallest -possible piece of code, to avoid missing possible warnings other than -one you intend to suppress. -@end defspec - - More precise control of warnings is possible by setting the variable -@code{byte-compile-warnings}. - -@node Byte-Code Objects -@section Byte-Code Function Objects -@cindex compiled function -@cindex byte-code function - - Byte-compiled functions have a special data type: they are -@dfn{byte-code function objects}. Whenever such an object appears as -a function to be called, Emacs uses the byte-code interpreter to -execute the byte-code. - - Internally, a byte-code function object is much like a vector; its -elements can be accessed using @code{aref}. Its printed -representation is like that for a vector, with an additional @samp{#} -before the opening @samp{[}. It must have at least four elements; -there is no maximum number, but only the first six elements have any -normal use. They are: - -@table @var -@item arglist -The list of argument symbols. - -@item byte-code -The string containing the byte-code instructions. - -@item constants -The vector of Lisp objects referenced by the byte code. These include -symbols used as function names and variable names. - -@item stacksize -The maximum stack size this function needs. - -@item docstring -The documentation string (if any); otherwise, @code{nil}. The value may -be a number or a list, in case the documentation string is stored in a -file. Use the function @code{documentation} to get the real -documentation string (@pxref{Accessing Documentation}). - -@item interactive -The interactive spec (if any). This can be a string or a Lisp -expression. It is @code{nil} for a function that isn't interactive. -@end table - -Here's an example of a byte-code function object, in printed -representation. It is the definition of the command -@code{backward-sexp}. - -@example -#[(&optional arg) - "^H\204^F^@@\301^P\302^H[!\207" - [arg 1 forward-sexp] - 2 - 254435 - "^p"] -@end example - - The primitive way to create a byte-code object is with -@code{make-byte-code}: - -@defun make-byte-code &rest elements -This function constructs and returns a byte-code function object -with @var{elements} as its elements. -@end defun - - You should not try to come up with the elements for a byte-code -function yourself, because if they are inconsistent, Emacs may crash -when you call the function. Always leave it to the byte compiler to -create these objects; it makes the elements consistent (we hope). - -@node Disassembly -@section Disassembled Byte-Code -@cindex disassembled byte-code - - People do not write byte-code; that job is left to the byte -compiler. But we provide a disassembler to satisfy a cat-like -curiosity. The disassembler converts the byte-compiled code into -human-readable form. - - The byte-code interpreter is implemented as a simple stack machine. -It pushes values onto a stack of its own, then pops them off to use them -in calculations whose results are themselves pushed back on the stack. -When a byte-code function returns, it pops a value off the stack and -returns it as the value of the function. - - In addition to the stack, byte-code functions can use, bind, and set -ordinary Lisp variables, by transferring values between variables and -the stack. - -@deffn Command disassemble object &optional buffer-or-name -This command displays the disassembled code for @var{object}. In -interactive use, or if @var{buffer-or-name} is @code{nil} or omitted, -the output goes in a buffer named @file{*Disassemble*}. If -@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the -name of an existing buffer. Then the output goes there, at point, and -point is left before the output. - -The argument @var{object} can be a function name, a lambda expression -or a byte-code object. If it is a lambda expression, @code{disassemble} -compiles it and disassembles the resulting compiled code. -@end deffn - - Here are two examples of using the @code{disassemble} function. We -have added explanatory comments to help you relate the byte-code to the -Lisp source; these do not appear in the output of @code{disassemble}. - -@example -@group -(defun factorial (integer) - "Compute factorial of an integer." - (if (= 1 integer) 1 - (* integer (factorial (1- integer))))) - @result{} factorial -@end group - -@group -(factorial 4) - @result{} 24 -@end group - -@group -(disassemble 'factorial) - @print{} byte-code for factorial: - doc: Compute factorial of an integer. - args: (integer) -@end group - -@group -0 varref integer ; @r{Get the value of @code{integer} and} - ; @r{push it onto the stack.} -1 constant 1 ; @r{Push 1 onto stack.} -@end group -@group -2 eqlsign ; @r{Pop top two values off stack, compare} - ; @r{them, and push result onto stack.} -@end group -@group -3 goto-if-nil 1 ; @r{Pop and test top of stack;} - ; @r{if @code{nil}, go to 1, else continue.} -6 constant 1 ; @r{Push 1 onto top of stack.} -7 return ; @r{Return the top element of the stack.} -@end group -@group -8:1 varref integer ; @r{Push value of @code{integer} onto stack.} -9 constant factorial ; @r{Push @code{factorial} onto stack.} -10 varref integer ; @r{Push value of @code{integer} onto stack.} -11 sub1 ; @r{Pop @code{integer}, decrement value,} - ; @r{push new value onto stack.} -12 call 1 ; @r{Call function @code{factorial} using first} - ; @r{(i.e. top) stack element as argument;} - ; @r{push returned value onto stack.} -@end group -@group -13 mult ; @r{Pop top two values off stack, multiply} - ; @r{them, and push result onto stack.} -14 return ; @r{Return the top element of the stack.} -@end group -@end example - -The @code{silly-loop} function is somewhat more complex: - -@example -@group -(defun silly-loop (n) - "Return time before and after N iterations of a loop." - (let ((t1 (current-time-string))) - (while (> (setq n (1- n)) - 0)) - (list t1 (current-time-string)))) - @result{} silly-loop -@end group - -@group -(disassemble 'silly-loop) - @print{} byte-code for silly-loop: - doc: Return time before and after N iterations of a loop. - args: (n) -@end group - -@group -0 constant current-time-string ; @r{Push @code{current-time-string}} - ; @r{onto top of stack.} -@end group -@group -1 call 0 ; @r{Call @code{current-time-string} with no} - ; @r{argument, push result onto stack.} -@end group -@group -2 varbind t1 ; @r{Pop stack and bind @code{t1} to popped value.} -@end group -@group -3:1 varref n ; @r{Get value of @code{n} from the environment} - ; @r{and push the value on the stack.} -4 sub1 ; @r{Subtract 1 from top of stack.} -@end group -@group -5 dup ; @r{Duplicate top of stack; i.e. copy the top} - ; @r{of the stack and push copy onto stack.} -6 varset n ; @r{Pop the top of the stack,} - ; @r{and bind @code{n} to the value.} - -;; @r{(In effect, the sequence @code{dup varset} copies the top of the stack} -;; @r{into the value of @code{n} without popping it.)} -@end group - -@group -7 constant 0 ; @r{Push 0 onto stack.} -8 gtr ; @r{Pop top two values off stack,} - ; @r{test if @var{n} is greater than 0} - ; @r{and push result onto stack.} -@end group -@group -9 goto-if-not-nil 1 ; @r{Goto 1 if @code{n} > 0} - ; @r{(this continues the while loop)} - ; @r{else continue.} -@end group -@group -12 varref t1 ; @r{Push value of @code{t1} onto stack.} -13 constant current-time-string ; @r{Push @code{current-time-string}} - ; @r{onto the top of the stack.} -14 call 0 ; @r{Call @code{current-time-string} again.} -@end group -@group -15 unbind 1 ; @r{Unbind @code{t1} in local environment.} -16 list2 ; @r{Pop top two elements off stack, create a} - ; @r{list of them, and push it onto stack.} -17 return ; @r{Return value of the top of stack.} -@end group -@end example - diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi deleted file mode 100644 index 95b70e87c93..00000000000 --- a/doc/lispref/control.texi +++ /dev/null @@ -1,1333 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/control -@node Control Structures, Variables, Evaluation, Top -@chapter Control Structures -@cindex special forms for control structures -@cindex control structures - - A Lisp program consists of a set of @dfn{expressions}, or -@dfn{forms} (@pxref{Forms}). We control the order of execution of -these forms by enclosing them in @dfn{control structures}. Control -structures are special forms which control when, whether, or how many -times to execute the forms they contain. - -@cindex textual order - The simplest order of execution is sequential execution: first form -@var{a}, then form @var{b}, and so on. This is what happens when you -write several forms in succession in the body of a function, or at top -level in a file of Lisp code---the forms are executed in the order -written. We call this @dfn{textual order}. For example, if a function -body consists of two forms @var{a} and @var{b}, evaluation of the -function evaluates first @var{a} and then @var{b}. The result of -evaluating @var{b} becomes the value of the function. - - Explicit control structures make possible an order of execution other -than sequential. - - Emacs Lisp provides several kinds of control structure, including -other varieties of sequencing, conditionals, iteration, and (controlled) -jumps---all discussed below. The built-in control structures are -special forms since their subforms are not necessarily evaluated or not -evaluated sequentially. You can use macros to define your own control -structure constructs (@pxref{Macros}). - -@menu -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. -@end menu - -@node Sequencing -@section Sequencing - - Evaluating forms in the order they appear is the most common way -control passes from one form to another. In some contexts, such as in a -function body, this happens automatically. Elsewhere you must use a -control structure construct to do this: @code{progn}, the simplest -control construct of Lisp. - - A @code{progn} special form looks like this: - -@example -@group -(progn @var{a} @var{b} @var{c} @dots{}) -@end group -@end example - -@noindent -and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in -that order. These forms are called the @dfn{body} of the @code{progn} form. -The value of the last form in the body becomes the value of the entire -@code{progn}. @code{(progn)} returns @code{nil}. - -@cindex implicit @code{progn} - In the early days of Lisp, @code{progn} was the only way to execute -two or more forms in succession and use the value of the last of them. -But programmers found they often needed to use a @code{progn} in the -body of a function, where (at that time) only one form was allowed. So -the body of a function was made into an ``implicit @code{progn}'': -several forms are allowed just as in the body of an actual @code{progn}. -Many other control structures likewise contain an implicit @code{progn}. -As a result, @code{progn} is not used as much as it was many years ago. -It is needed now most often inside an @code{unwind-protect}, @code{and}, -@code{or}, or in the @var{then}-part of an @code{if}. - -@defspec progn forms@dots{} -This special form evaluates all of the @var{forms}, in textual -order, returning the result of the final form. - -@example -@group -(progn (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The third form" -@end group -@end example -@end defspec - - Two other constructs likewise evaluate a series of forms but return -different values: - -@defspec prog1 form1 forms@dots{} -This special form evaluates @var{form1} and all of the @var{forms}, in -textual order, returning the result of @var{form1}. - -@example -@group -(prog1 (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The first form" -@end group -@end example - -Here is a way to remove the first element from a list in the variable -@code{x}, then return the value of that former element: - -@example -(prog1 (car x) (setq x (cdr x))) -@end example -@end defspec - -@defspec prog2 form1 form2 forms@dots{} -This special form evaluates @var{form1}, @var{form2}, and all of the -following @var{forms}, in textual order, returning the result of -@var{form2}. - -@example -@group -(prog2 (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The second form" -@end group -@end example -@end defspec - -@node Conditionals -@section Conditionals -@cindex conditional evaluation - - Conditional control structures choose among alternatives. Emacs Lisp -has four conditional forms: @code{if}, which is much the same as in -other languages; @code{when} and @code{unless}, which are variants of -@code{if}; and @code{cond}, which is a generalized case statement. - -@defspec if condition then-form else-forms@dots{} -@code{if} chooses between the @var{then-form} and the @var{else-forms} -based on the value of @var{condition}. If the evaluated @var{condition} is -non-@code{nil}, @var{then-form} is evaluated and the result returned. -Otherwise, the @var{else-forms} are evaluated in textual order, and the -value of the last one is returned. (The @var{else} part of @code{if} is -an example of an implicit @code{progn}. @xref{Sequencing}.) - -If @var{condition} has the value @code{nil}, and no @var{else-forms} are -given, @code{if} returns @code{nil}. - -@code{if} is a special form because the branch that is not selected is -never evaluated---it is ignored. Thus, in this example, -@code{true} is not printed because @code{print} is never called: - -@example -@group -(if nil - (print 'true) - 'very-false) -@result{} very-false -@end group -@end example -@end defspec - -@defmac when condition then-forms@dots{} -This is a variant of @code{if} where there are no @var{else-forms}, -and possibly several @var{then-forms}. In particular, - -@example -(when @var{condition} @var{a} @var{b} @var{c}) -@end example - -@noindent -is entirely equivalent to - -@example -(if @var{condition} (progn @var{a} @var{b} @var{c}) nil) -@end example -@end defmac - -@defmac unless condition forms@dots{} -This is a variant of @code{if} where there is no @var{then-form}: - -@example -(unless @var{condition} @var{a} @var{b} @var{c}) -@end example - -@noindent -is entirely equivalent to - -@example -(if @var{condition} nil - @var{a} @var{b} @var{c}) -@end example -@end defmac - -@defspec cond clause@dots{} -@code{cond} chooses among an arbitrary number of alternatives. Each -@var{clause} in the @code{cond} must be a list. The @sc{car} of this -list is the @var{condition}; the remaining elements, if any, the -@var{body-forms}. Thus, a clause looks like this: - -@example -(@var{condition} @var{body-forms}@dots{}) -@end example - -@code{cond} tries the clauses in textual order, by evaluating the -@var{condition} of each clause. If the value of @var{condition} is -non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its -@var{body-forms}, and the value of the last of @var{body-forms} becomes -the value of the @code{cond}. The remaining clauses are ignored. - -If the value of @var{condition} is @code{nil}, the clause ``fails'', so -the @code{cond} moves on to the following clause, trying its -@var{condition}. - -If every @var{condition} evaluates to @code{nil}, so that every clause -fails, @code{cond} returns @code{nil}. - -A clause may also look like this: - -@example -(@var{condition}) -@end example - -@noindent -Then, if @var{condition} is non-@code{nil} when tested, the value of -@var{condition} becomes the value of the @code{cond} form. - -The following example has four clauses, which test for the cases where -the value of @code{x} is a number, string, buffer and symbol, -respectively: - -@example -@group -(cond ((numberp x) x) - ((stringp x) x) - ((bufferp x) - (setq temporary-hack x) ; @r{multiple body-forms} - (buffer-name x)) ; @r{in one clause} - ((symbolp x) (symbol-value x))) -@end group -@end example - -Often we want to execute the last clause whenever none of the previous -clauses was successful. To do this, we use @code{t} as the -@var{condition} of the last clause, like this: @code{(t -@var{body-forms})}. The form @code{t} evaluates to @code{t}, which is -never @code{nil}, so this clause never fails, provided the @code{cond} -gets to it at all. For example: - -@example -@group -(setq a 5) -(cond ((eq a 'hack) 'foo) - (t "default")) -@result{} "default" -@end group -@end example - -@noindent -This @code{cond} expression returns @code{foo} if the value of @code{a} -is @code{hack}, and returns the string @code{"default"} otherwise. -@end defspec - -Any conditional construct can be expressed with @code{cond} or with -@code{if}. Therefore, the choice between them is a matter of style. -For example: - -@example -@group -(if @var{a} @var{b} @var{c}) -@equiv{} -(cond (@var{a} @var{b}) (t @var{c})) -@end group -@end example - -@node Combining Conditions -@section Constructs for Combining Conditions - - This section describes three constructs that are often used together -with @code{if} and @code{cond} to express complicated conditions. The -constructs @code{and} and @code{or} can also be used individually as -kinds of multiple conditional constructs. - -@defun not condition -This function tests for the falsehood of @var{condition}. It returns -@code{t} if @var{condition} is @code{nil}, and @code{nil} otherwise. -The function @code{not} is identical to @code{null}, and we recommend -using the name @code{null} if you are testing for an empty list. -@end defun - -@defspec and conditions@dots{} -The @code{and} special form tests whether all the @var{conditions} are -true. It works by evaluating the @var{conditions} one by one in the -order written. - -If any of the @var{conditions} evaluates to @code{nil}, then the result -of the @code{and} must be @code{nil} regardless of the remaining -@var{conditions}; so @code{and} returns @code{nil} right away, ignoring -the remaining @var{conditions}. - -If all the @var{conditions} turn out non-@code{nil}, then the value of -the last of them becomes the value of the @code{and} form. Just -@code{(and)}, with no @var{conditions}, returns @code{t}, appropriate -because all the @var{conditions} turned out non-@code{nil}. (Think -about it; which one did not?) - -Here is an example. The first condition returns the integer 1, which is -not @code{nil}. Similarly, the second condition returns the integer 2, -which is not @code{nil}. The third condition is @code{nil}, so the -remaining condition is never evaluated. - -@example -@group -(and (print 1) (print 2) nil (print 3)) - @print{} 1 - @print{} 2 -@result{} nil -@end group -@end example - -Here is a more realistic example of using @code{and}: - -@example -@group -(if (and (consp foo) (eq (car foo) 'x)) - (message "foo is a list starting with x")) -@end group -@end example - -@noindent -Note that @code{(car foo)} is not executed if @code{(consp foo)} returns -@code{nil}, thus avoiding an error. - -@code{and} expressions can also be written using either @code{if} or -@code{cond}. Here's how: - -@example -@group -(and @var{arg1} @var{arg2} @var{arg3}) -@equiv{} -(if @var{arg1} (if @var{arg2} @var{arg3})) -@equiv{} -(cond (@var{arg1} (cond (@var{arg2} @var{arg3})))) -@end group -@end example -@end defspec - -@defspec or conditions@dots{} -The @code{or} special form tests whether at least one of the -@var{conditions} is true. It works by evaluating all the -@var{conditions} one by one in the order written. - -If any of the @var{conditions} evaluates to a non-@code{nil} value, then -the result of the @code{or} must be non-@code{nil}; so @code{or} returns -right away, ignoring the remaining @var{conditions}. The value it -returns is the non-@code{nil} value of the condition just evaluated. - -If all the @var{conditions} turn out @code{nil}, then the @code{or} -expression returns @code{nil}. Just @code{(or)}, with no -@var{conditions}, returns @code{nil}, appropriate because all the -@var{conditions} turned out @code{nil}. (Think about it; which one -did not?) - -For example, this expression tests whether @code{x} is either -@code{nil} or the integer zero: - -@example -(or (eq x nil) (eq x 0)) -@end example - -Like the @code{and} construct, @code{or} can be written in terms of -@code{cond}. For example: - -@example -@group -(or @var{arg1} @var{arg2} @var{arg3}) -@equiv{} -(cond (@var{arg1}) - (@var{arg2}) - (@var{arg3})) -@end group -@end example - -You could almost write @code{or} in terms of @code{if}, but not quite: - -@example -@group -(if @var{arg1} @var{arg1} - (if @var{arg2} @var{arg2} - @var{arg3})) -@end group -@end example - -@noindent -This is not completely equivalent because it can evaluate @var{arg1} or -@var{arg2} twice. By contrast, @code{(or @var{arg1} @var{arg2} -@var{arg3})} never evaluates any argument more than once. -@end defspec - -@node Iteration -@section Iteration -@cindex iteration -@cindex recursion - - Iteration means executing part of a program repetitively. For -example, you might want to repeat some computation once for each element -of a list, or once for each integer from 0 to @var{n}. You can do this -in Emacs Lisp with the special form @code{while}: - -@defspec while condition forms@dots{} -@code{while} first evaluates @var{condition}. If the result is -non-@code{nil}, it evaluates @var{forms} in textual order. Then it -reevaluates @var{condition}, and if the result is non-@code{nil}, it -evaluates @var{forms} again. This process repeats until @var{condition} -evaluates to @code{nil}. - -There is no limit on the number of iterations that may occur. The loop -will continue until either @var{condition} evaluates to @code{nil} or -until an error or @code{throw} jumps out of it (@pxref{Nonlocal Exits}). - -The value of a @code{while} form is always @code{nil}. - -@example -@group -(setq num 0) - @result{} 0 -@end group -@group -(while (< num 4) - (princ (format "Iteration %d." num)) - (setq num (1+ num))) - @print{} Iteration 0. - @print{} Iteration 1. - @print{} Iteration 2. - @print{} Iteration 3. - @result{} nil -@end group -@end example - -To write a ``repeat...until'' loop, which will execute something on each -iteration and then do the end-test, put the body followed by the -end-test in a @code{progn} as the first argument of @code{while}, as -shown here: - -@example -@group -(while (progn - (forward-line 1) - (not (looking-at "^$")))) -@end group -@end example - -@noindent -This moves forward one line and continues moving by lines until it -reaches an empty line. It is peculiar in that the @code{while} has no -body, just the end test (which also does the real work of moving point). -@end defspec - - The @code{dolist} and @code{dotimes} macros provide convenient ways to -write two common kinds of loops. - -@defmac dolist (var list [result]) body@dots{} -This construct executes @var{body} once for each element of -@var{list}, binding the variable @var{var} locally to hold the current -element. Then it returns the value of evaluating @var{result}, or -@code{nil} if @var{result} is omitted. For example, here is how you -could use @code{dolist} to define the @code{reverse} function: - -@example -(defun reverse (list) - (let (value) - (dolist (elt list value) - (setq value (cons elt value))))) -@end example -@end defmac - -@defmac dotimes (var count [result]) body@dots{} -This construct executes @var{body} once for each integer from 0 -(inclusive) to @var{count} (exclusive), binding the variable @var{var} -to the integer for the current iteration. Then it returns the value -of evaluating @var{result}, or @code{nil} if @var{result} is omitted. -Here is an example of using @code{dotimes} to do something 100 times: - -@example -(dotimes (i 100) - (insert "I will not obey absurd orders\n")) -@end example -@end defmac - -@node Nonlocal Exits -@section Nonlocal Exits -@cindex nonlocal exits - - A @dfn{nonlocal exit} is a transfer of control from one point in a -program to another remote point. Nonlocal exits can occur in Emacs Lisp -as a result of errors; you can also use them under explicit control. -Nonlocal exits unbind all variable bindings made by the constructs being -exited. - -@menu -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an error happens. -@end menu - -@node Catch and Throw -@subsection Explicit Nonlocal Exits: @code{catch} and @code{throw} - - Most control constructs affect only the flow of control within the -construct itself. The function @code{throw} is the exception to this -rule of normal program execution: it performs a nonlocal exit on -request. (There are other exceptions, but they are for error handling -only.) @code{throw} is used inside a @code{catch}, and jumps back to -that @code{catch}. For example: - -@example -@group -(defun foo-outer () - (catch 'foo - (foo-inner))) - -(defun foo-inner () - @dots{} - (if x - (throw 'foo t)) - @dots{}) -@end group -@end example - -@noindent -The @code{throw} form, if executed, transfers control straight back to -the corresponding @code{catch}, which returns immediately. The code -following the @code{throw} is not executed. The second argument of -@code{throw} is used as the return value of the @code{catch}. - - The function @code{throw} finds the matching @code{catch} based on the -first argument: it searches for a @code{catch} whose first argument is -@code{eq} to the one specified in the @code{throw}. If there is more -than one applicable @code{catch}, the innermost one takes precedence. -Thus, in the above example, the @code{throw} specifies @code{foo}, and -the @code{catch} in @code{foo-outer} specifies the same symbol, so that -@code{catch} is the applicable one (assuming there is no other matching -@code{catch} in between). - - Executing @code{throw} exits all Lisp constructs up to the matching -@code{catch}, including function calls. When binding constructs such as -@code{let} or function calls are exited in this way, the bindings are -unbound, just as they are when these constructs exit normally -(@pxref{Local Variables}). Likewise, @code{throw} restores the buffer -and position saved by @code{save-excursion} (@pxref{Excursions}), and -the narrowing status saved by @code{save-restriction} and the window -selection saved by @code{save-window-excursion} (@pxref{Window -Configurations}). It also runs any cleanups established with the -@code{unwind-protect} special form when it exits that form -(@pxref{Cleanups}). - - The @code{throw} need not appear lexically within the @code{catch} -that it jumps to. It can equally well be called from another function -called within the @code{catch}. As long as the @code{throw} takes place -chronologically after entry to the @code{catch}, and chronologically -before exit from it, it has access to that @code{catch}. This is why -@code{throw} can be used in commands such as @code{exit-recursive-edit} -that throw back to the editor command loop (@pxref{Recursive Editing}). - -@cindex CL note---only @code{throw} in Emacs -@quotation -@b{Common Lisp note:} Most other versions of Lisp, including Common Lisp, -have several ways of transferring control nonsequentially: @code{return}, -@code{return-from}, and @code{go}, for example. Emacs Lisp has only -@code{throw}. -@end quotation - -@defspec catch tag body@dots{} -@cindex tag on run time stack -@code{catch} establishes a return point for the @code{throw} function. -The return point is distinguished from other such return points by -@var{tag}, which may be any Lisp object except @code{nil}. The argument -@var{tag} is evaluated normally before the return point is established. - -With the return point in effect, @code{catch} evaluates the forms of the -@var{body} in textual order. If the forms execute normally (without -error or nonlocal exit) the value of the last body form is returned from -the @code{catch}. - -If a @code{throw} is executed during the execution of @var{body}, -specifying the same value @var{tag}, the @code{catch} form exits -immediately; the value it returns is whatever was specified as the -second argument of @code{throw}. -@end defspec - -@defun throw tag value -The purpose of @code{throw} is to return from a return point previously -established with @code{catch}. The argument @var{tag} is used to choose -among the various existing return points; it must be @code{eq} to the value -specified in the @code{catch}. If multiple return points match @var{tag}, -the innermost one is used. - -The argument @var{value} is used as the value to return from that -@code{catch}. - -@kindex no-catch -If no return point is in effect with tag @var{tag}, then a @code{no-catch} -error is signaled with data @code{(@var{tag} @var{value})}. -@end defun - -@node Examples of Catch -@subsection Examples of @code{catch} and @code{throw} - - One way to use @code{catch} and @code{throw} is to exit from a doubly -nested loop. (In most languages, this would be done with a ``goto''.) -Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j} -varying from 0 to 9: - -@example -@group -(defun search-foo () - (catch 'loop - (let ((i 0)) - (while (< i 10) - (let ((j 0)) - (while (< j 10) - (if (foo i j) - (throw 'loop (list i j))) - (setq j (1+ j)))) - (setq i (1+ i)))))) -@end group -@end example - -@noindent -If @code{foo} ever returns non-@code{nil}, we stop immediately and return a -list of @var{i} and @var{j}. If @code{foo} always returns @code{nil}, the -@code{catch} returns normally, and the value is @code{nil}, since that -is the result of the @code{while}. - - Here are two tricky examples, slightly different, showing two -return points at once. First, two return points with the same tag, -@code{hack}: - -@example -@group -(defun catch2 (tag) - (catch tag - (throw 'hack 'yes))) -@result{} catch2 -@end group - -@group -(catch 'hack - (print (catch2 'hack)) - 'no) -@print{} yes -@result{} no -@end group -@end example - -@noindent -Since both return points have tags that match the @code{throw}, it goes to -the inner one, the one established in @code{catch2}. Therefore, -@code{catch2} returns normally with value @code{yes}, and this value is -printed. Finally the second body form in the outer @code{catch}, which is -@code{'no}, is evaluated and returned from the outer @code{catch}. - - Now let's change the argument given to @code{catch2}: - -@example -@group -(catch 'hack - (print (catch2 'quux)) - 'no) -@result{} yes -@end group -@end example - -@noindent -We still have two return points, but this time only the outer one has -the tag @code{hack}; the inner one has the tag @code{quux} instead. -Therefore, @code{throw} makes the outer @code{catch} return the value -@code{yes}. The function @code{print} is never called, and the -body-form @code{'no} is never evaluated. - -@node Errors -@subsection Errors -@cindex errors - - When Emacs Lisp attempts to evaluate a form that, for some reason, -cannot be evaluated, it @dfn{signals} an @dfn{error}. - - When an error is signaled, Emacs's default reaction is to print an -error message and terminate execution of the current command. This is -the right thing to do in most cases, such as if you type @kbd{C-f} at -the end of the buffer. - - In complicated programs, simple termination may not be what you want. -For example, the program may have made temporary changes in data -structures, or created temporary buffers that should be deleted before -the program is finished. In such cases, you would use -@code{unwind-protect} to establish @dfn{cleanup expressions} to be -evaluated in case of error. (@xref{Cleanups}.) Occasionally, you may -wish the program to continue execution despite an error in a subroutine. -In these cases, you would use @code{condition-case} to establish -@dfn{error handlers} to recover control in case of error. - - Resist the temptation to use error handling to transfer control from -one part of the program to another; use @code{catch} and @code{throw} -instead. @xref{Catch and Throw}. - -@menu -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. -@end menu - -@node Signaling Errors -@subsubsection How to Signal an Error -@cindex signaling errors - - @dfn{Signaling} an error means beginning error processing. Error -processing normally aborts all or part of the running program and -returns to a point that is set up to handle the error -(@pxref{Processing of Errors}). Here we describe how to signal an -error. - - Most errors are signaled ``automatically'' within Lisp primitives -which you call for other purposes, such as if you try to take the -@sc{car} of an integer or move forward a character at the end of the -buffer. You can also signal errors explicitly with the functions -@code{error} and @code{signal}. - - Quitting, which happens when the user types @kbd{C-g}, is not -considered an error, but it is handled almost like an error. -@xref{Quitting}. - - Every error specifies an error message, one way or another. The -message should state what is wrong (``File does not exist''), not how -things ought to be (``File must exist''). The convention in Emacs -Lisp is that error messages should start with a capital letter, but -should not end with any sort of punctuation. - -@defun error format-string &rest args -This function signals an error with an error message constructed by -applying @code{format} (@pxref{Formatting Strings}) to -@var{format-string} and @var{args}. - -These examples show typical uses of @code{error}: - -@example -@group -(error "That is an error -- try something else") - @error{} That is an error -- try something else -@end group - -@group -(error "You have committed %d errors" 10) - @error{} You have committed 10 errors -@end group -@end example - -@code{error} works by calling @code{signal} with two arguments: the -error symbol @code{error}, and a list containing the string returned by -@code{format}. - -@strong{Warning:} If you want to use your own string as an error message -verbatim, don't just write @code{(error @var{string})}. If @var{string} -contains @samp{%}, it will be interpreted as a format specifier, with -undesirable results. Instead, use @code{(error "%s" @var{string})}. -@end defun - -@defun signal error-symbol data -@anchor{Definition of signal} -This function signals an error named by @var{error-symbol}. The -argument @var{data} is a list of additional Lisp objects relevant to -the circumstances of the error. - -The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol -bearing a property @code{error-conditions} whose value is a list of -condition names. This is how Emacs Lisp classifies different sorts of -errors. @xref{Error Symbols}, for a description of error symbols, -error conditions and condition names. - -If the error is not handled, the two arguments are used in printing -the error message. Normally, this error message is provided by the -@code{error-message} property of @var{error-symbol}. If @var{data} is -non-@code{nil}, this is followed by a colon and a comma separated list -of the unevaluated elements of @var{data}. For @code{error}, the -error message is the @sc{car} of @var{data} (that must be a string). -Subcategories of @code{file-error} are handled specially. - -The number and significance of the objects in @var{data} depends on -@var{error-symbol}. For example, with a @code{wrong-type-argument} error, -there should be two objects in the list: a predicate that describes the type -that was expected, and the object that failed to fit that type. - -Both @var{error-symbol} and @var{data} are available to any error -handlers that handle the error: @code{condition-case} binds a local -variable to a list of the form @code{(@var{error-symbol} .@: -@var{data})} (@pxref{Handling Errors}). - -The function @code{signal} never returns. -@c (though in older Emacs versions it sometimes could). - -@example -@group -(signal 'wrong-number-of-arguments '(x y)) - @error{} Wrong number of arguments: x, y -@end group - -@group -(signal 'no-such-error '("My unknown error condition")) - @error{} peculiar error: "My unknown error condition" -@end group -@end example -@end defun - -@cindex CL note---no continuable errors -@quotation -@b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp -concept of continuable errors. -@end quotation - -@node Processing of Errors -@subsubsection How Emacs Processes Errors - -When an error is signaled, @code{signal} searches for an active -@dfn{handler} for the error. A handler is a sequence of Lisp -expressions designated to be executed if an error happens in part of the -Lisp program. If the error has an applicable handler, the handler is -executed, and control resumes following the handler. The handler -executes in the environment of the @code{condition-case} that -established it; all functions called within that @code{condition-case} -have already been exited, and the handler cannot return to them. - -If there is no applicable handler for the error, it terminates the -current command and returns control to the editor command loop. (The -command loop has an implicit handler for all kinds of errors.) The -command loop's handler uses the error symbol and associated data to -print an error message. You can use the variable -@code{command-error-function} to control how this is done: - -@defvar command-error-function -This variable, if non-@code{nil}, specifies a function to use to -handle errors that return control to the Emacs command loop. The -function should take three arguments: @var{data}, a list of the same -form that @code{condition-case} would bind to its variable; -@var{context}, a string describing the situation in which the error -occurred, or (more often) @code{nil}; and @var{caller}, the Lisp -function which called the primitive that signaled the error. -@end defvar - -@cindex @code{debug-on-error} use -An error that has no explicit handler may call the Lisp debugger. The -debugger is enabled if the variable @code{debug-on-error} (@pxref{Error -Debugging}) is non-@code{nil}. Unlike error handlers, the debugger runs -in the environment of the error, so that you can examine values of -variables precisely as they were at the time of the error. - -@node Handling Errors -@subsubsection Writing Code to Handle Errors -@cindex error handler -@cindex handling errors - - The usual effect of signaling an error is to terminate the command -that is running and return immediately to the Emacs editor command loop. -You can arrange to trap errors occurring in a part of your program by -establishing an error handler, with the special form -@code{condition-case}. A simple example looks like this: - -@example -@group -(condition-case nil - (delete-file filename) - (error nil)) -@end group -@end example - -@noindent -This deletes the file named @var{filename}, catching any error and -returning @code{nil} if an error occurs. (You can use the macro -@code{ignore-errors} for a simple case like this; see below.) - - The @code{condition-case} construct is often used to trap errors that -are predictable, such as failure to open a file in a call to -@code{insert-file-contents}. It is also used to trap errors that are -totally unpredictable, such as when the program evaluates an expression -read from the user. - - The second argument of @code{condition-case} is called the -@dfn{protected form}. (In the example above, the protected form is a -call to @code{delete-file}.) The error handlers go into effect when -this form begins execution and are deactivated when this form returns. -They remain in effect for all the intervening time. In particular, they -are in effect during the execution of functions called by this form, in -their subroutines, and so on. This is a good thing, since, strictly -speaking, errors can be signaled only by Lisp primitives (including -@code{signal} and @code{error}) called by the protected form, not by the -protected form itself. - - The arguments after the protected form are handlers. Each handler -lists one or more @dfn{condition names} (which are symbols) to specify -which errors it will handle. The error symbol specified when an error -is signaled also defines a list of condition names. A handler applies -to an error if they have any condition names in common. In the example -above, there is one handler, and it specifies one condition name, -@code{error}, which covers all errors. - - The search for an applicable handler checks all the established handlers -starting with the most recently established one. Thus, if two nested -@code{condition-case} forms offer to handle the same error, the inner of -the two gets to handle it. - - If an error is handled by some @code{condition-case} form, this -ordinarily prevents the debugger from being run, even if -@code{debug-on-error} says this error should invoke the debugger. - - If you want to be able to debug errors that are caught by a -@code{condition-case}, set the variable @code{debug-on-signal} to a -non-@code{nil} value. You can also specify that a particular handler -should let the debugger run first, by writing @code{debug} among the -conditions, like this: - -@example -@group -(condition-case nil - (delete-file filename) - ((debug error) nil)) -@end group -@end example - -@noindent -The effect of @code{debug} here is only to prevent -@code{condition-case} from suppressing the call to the debugger. Any -given error will invoke the debugger only if @code{debug-on-error} and -the other usual filtering mechanisms say it should. @xref{Error Debugging}. - -@defmac condition-case-unless-debug var protected-form handlers@dots{} -The macro @code{condition-case-unless-debug} provides another way to -handle debugging of such forms. It behaves exactly like -@code{condition-case}, unless the variable @code{debug-on-error} is -non-@code{nil}, in which case it does not handle any errors at all. -@end defmac - - Once Emacs decides that a certain handler handles the error, it -returns control to that handler. To do so, Emacs unbinds all variable -bindings made by binding constructs that are being exited, and -executes the cleanups of all @code{unwind-protect} forms that are -being exited. Once control arrives at the handler, the body of the -handler executes normally. - - After execution of the handler body, execution returns from the -@code{condition-case} form. Because the protected form is exited -completely before execution of the handler, the handler cannot resume -execution at the point of the error, nor can it examine variable -bindings that were made within the protected form. All it can do is -clean up and proceed. - - Error signaling and handling have some resemblance to @code{throw} and -@code{catch} (@pxref{Catch and Throw}), but they are entirely separate -facilities. An error cannot be caught by a @code{catch}, and a -@code{throw} cannot be handled by an error handler (though using -@code{throw} when there is no suitable @code{catch} signals an error -that can be handled). - -@defspec condition-case var protected-form handlers@dots{} -This special form establishes the error handlers @var{handlers} around -the execution of @var{protected-form}. If @var{protected-form} executes -without error, the value it returns becomes the value of the -@code{condition-case} form; in this case, the @code{condition-case} has -no effect. The @code{condition-case} form makes a difference when an -error occurs during @var{protected-form}. - -Each of the @var{handlers} is a list of the form @code{(@var{conditions} -@var{body}@dots{})}. Here @var{conditions} is an error condition name -to be handled, or a list of condition names (which can include @code{debug} -to allow the debugger to run before the handler); @var{body} is one or more -Lisp expressions to be executed when this handler handles an error. -Here are examples of handlers: - -@example -@group -(error nil) - -(arith-error (message "Division by zero")) - -((arith-error file-error) - (message - "Either division by zero or failure to open a file")) -@end group -@end example - -Each error that occurs has an @dfn{error symbol} that describes what -kind of error it is. The @code{error-conditions} property of this -symbol is a list of condition names (@pxref{Error Symbols}). Emacs -searches all the active @code{condition-case} forms for a handler that -specifies one or more of these condition names; the innermost matching -@code{condition-case} handles the error. Within this -@code{condition-case}, the first applicable handler handles the error. - -After executing the body of the handler, the @code{condition-case} -returns normally, using the value of the last form in the handler body -as the overall value. - -@cindex error description -The argument @var{var} is a variable. @code{condition-case} does not -bind this variable when executing the @var{protected-form}, only when it -handles an error. At that time, it binds @var{var} locally to an -@dfn{error description}, which is a list giving the particulars of the -error. The error description has the form @code{(@var{error-symbol} -. @var{data})}. The handler can refer to this list to decide what to -do. For example, if the error is for failure opening a file, the file -name is the second element of @var{data}---the third element of the -error description. - -If @var{var} is @code{nil}, that means no variable is bound. Then the -error symbol and associated data are not available to the handler. - -@cindex rethrow a signal -Sometimes it is necessary to re-throw a signal caught by -@code{condition-case}, for some outer-level handler to catch. Here's -how to do that: - -@example - (signal (car err) (cdr err)) -@end example - -@noindent -where @code{err} is the error description variable, the first argument -to @code{condition-case} whose error condition you want to re-throw. -@xref{Definition of signal}. -@end defspec - -@defun error-message-string error-descriptor -This function returns the error message string for a given error -descriptor. It is useful if you want to handle an error by printing the -usual error message for that error. @xref{Definition of signal}. -@end defun - -@cindex @code{arith-error} example -Here is an example of using @code{condition-case} to handle the error -that results from dividing by zero. The handler displays the error -message (but without a beep), then returns a very large number. - -@example -@group -(defun safe-divide (dividend divisor) - (condition-case err - ;; @r{Protected form.} - (/ dividend divisor) -@end group -@group - ;; @r{The handler.} - (arith-error ; @r{Condition.} - ;; @r{Display the usual message for this error.} - (message "%s" (error-message-string err)) - 1000000))) -@result{} safe-divide -@end group - -@group -(safe-divide 5 0) - @print{} Arithmetic error: (arith-error) -@result{} 1000000 -@end group -@end example - -@noindent -The handler specifies condition name @code{arith-error} so that it -will handle only division-by-zero errors. Other kinds of errors will -not be handled (by this @code{condition-case}). Thus: - -@example -@group -(safe-divide nil 3) - @error{} Wrong type argument: number-or-marker-p, nil -@end group -@end example - - Here is a @code{condition-case} that catches all kinds of errors, -including those from @code{error}: - -@example -@group -(setq baz 34) - @result{} 34 -@end group - -@group -(condition-case err - (if (eq baz 35) - t - ;; @r{This is a call to the function @code{error}.} - (error "Rats! The variable %s was %s, not 35" 'baz baz)) - ;; @r{This is the handler; it is not a form.} - (error (princ (format "The error was: %s" err)) - 2)) -@print{} The error was: (error "Rats! The variable baz was 34, not 35") -@result{} 2 -@end group -@end example - -@defmac ignore-errors body@dots{} -This construct executes @var{body}, ignoring any errors that occur -during its execution. If the execution is without error, -@code{ignore-errors} returns the value of the last form in @var{body}; -otherwise, it returns @code{nil}. - -Here's the example at the beginning of this subsection rewritten using -@code{ignore-errors}: - -@example -@group - (ignore-errors - (delete-file filename)) -@end group -@end example -@end defmac - -@defmac with-demoted-errors body@dots{} -This macro is like a milder version of @code{ignore-errors}. Rather -than suppressing errors altogether, it converts them into messages. -Use this form around code that is not expected to signal errors, but -should be robust if one does occur. Note that this macro uses -@code{condition-case-unless-debug} rather than @code{condition-case}. -@end defmac - -@node Error Symbols -@subsubsection Error Symbols and Condition Names -@cindex error symbol -@cindex error name -@cindex condition name -@cindex user-defined error -@kindex error-conditions - - When you signal an error, you specify an @dfn{error symbol} to specify -the kind of error you have in mind. Each error has one and only one -error symbol to categorize it. This is the finest classification of -errors defined by the Emacs Lisp language. - - These narrow classifications are grouped into a hierarchy of wider -classes called @dfn{error conditions}, identified by @dfn{condition -names}. The narrowest such classes belong to the error symbols -themselves: each error symbol is also a condition name. There are also -condition names for more extensive classes, up to the condition name -@code{error} which takes in all kinds of errors (but not @code{quit}). -Thus, each error has one or more condition names: @code{error}, the -error symbol if that is distinct from @code{error}, and perhaps some -intermediate classifications. - - In order for a symbol to be an error symbol, it must have an -@code{error-conditions} property which gives a list of condition names. -This list defines the conditions that this kind of error belongs to. -(The error symbol itself, and the symbol @code{error}, should always be -members of this list.) Thus, the hierarchy of condition names is -defined by the @code{error-conditions} properties of the error symbols. -Because quitting is not considered an error, the value of the -@code{error-conditions} property of @code{quit} is just @code{(quit)}. - -@cindex peculiar error - In addition to the @code{error-conditions} list, the error symbol -should have an @code{error-message} property whose value is a string to -be printed when that error is signaled but not handled. If the -error symbol has no @code{error-message} property or if the -@code{error-message} property exists, but is not a string, the error -message @samp{peculiar error} is used. @xref{Definition of signal}. - - Here is how we define a new error symbol, @code{new-error}: - -@example -@group -(put 'new-error - 'error-conditions - '(error my-own-errors new-error)) -@result{} (error my-own-errors new-error) -@end group -@group -(put 'new-error 'error-message "A new error") -@result{} "A new error" -@end group -@end example - -@noindent -This error has three condition names: @code{new-error}, the narrowest -classification; @code{my-own-errors}, which we imagine is a wider -classification; and @code{error}, which is the widest of all. - - The error string should start with a capital letter but it should -not end with a period. This is for consistency with the rest of Emacs. - - Naturally, Emacs will never signal @code{new-error} on its own; only -an explicit call to @code{signal} (@pxref{Definition of signal}) in -your code can do this: - -@example -@group -(signal 'new-error '(x y)) - @error{} A new error: x, y -@end group -@end example - - This error can be handled through any of the three condition names. -This example handles @code{new-error} and any other errors in the class -@code{my-own-errors}: - -@example -@group -(condition-case foo - (bar nil t) - (my-own-errors nil)) -@end group -@end example - - The significant way that errors are classified is by their condition -names---the names used to match errors with handlers. An error symbol -serves only as a convenient way to specify the intended error message -and list of condition names. It would be cumbersome to give -@code{signal} a list of condition names rather than one error symbol. - - By contrast, using only error symbols without condition names would -seriously decrease the power of @code{condition-case}. Condition names -make it possible to categorize errors at various levels of generality -when you write an error handler. Using error symbols alone would -eliminate all but the narrowest level of classification. - - @xref{Standard Errors}, for a list of the main error symbols -and their conditions. - -@node Cleanups -@subsection Cleaning Up from Nonlocal Exits - - The @code{unwind-protect} construct is essential whenever you -temporarily put a data structure in an inconsistent state; it permits -you to make the data consistent again in the event of an error or -throw. (Another more specific cleanup construct that is used only for -changes in buffer contents is the atomic change group; @ref{Atomic -Changes}.) - -@defspec unwind-protect body-form cleanup-forms@dots{} -@cindex cleanup forms -@cindex protected forms -@cindex error cleanup -@cindex unwinding -@code{unwind-protect} executes @var{body-form} with a guarantee that -the @var{cleanup-forms} will be evaluated if control leaves -@var{body-form}, no matter how that happens. @var{body-form} may -complete normally, or execute a @code{throw} out of the -@code{unwind-protect}, or cause an error; in all cases, the -@var{cleanup-forms} will be evaluated. - -If @var{body-form} finishes normally, @code{unwind-protect} returns the -value of @var{body-form}, after it evaluates the @var{cleanup-forms}. -If @var{body-form} does not finish, @code{unwind-protect} does not -return any value in the normal sense. - -Only @var{body-form} is protected by the @code{unwind-protect}. If any -of the @var{cleanup-forms} themselves exits nonlocally (via a -@code{throw} or an error), @code{unwind-protect} is @emph{not} -guaranteed to evaluate the rest of them. If the failure of one of the -@var{cleanup-forms} has the potential to cause trouble, then protect -it with another @code{unwind-protect} around that form. - -The number of currently active @code{unwind-protect} forms counts, -together with the number of local variable bindings, against the limit -@code{max-specpdl-size} (@pxref{Definition of max-specpdl-size,, Local -Variables}). -@end defspec - - For example, here we make an invisible buffer for temporary use, and -make sure to kill it before finishing: - -@example -@group -(let ((buffer (get-buffer-create " *temp*"))) - (with-current-buffer buffer - (unwind-protect - @var{body-form} - (kill-buffer buffer)))) -@end group -@end example - -@noindent -You might think that we could just as well write @code{(kill-buffer -(current-buffer))} and dispense with the variable @code{buffer}. -However, the way shown above is safer, if @var{body-form} happens to -get an error after switching to a different buffer! (Alternatively, -you could write a @code{save-current-buffer} around @var{body-form}, -to ensure that the temporary buffer becomes current again in time to -kill it.) - - Emacs includes a standard macro called @code{with-temp-buffer} which -expands into more or less the code shown above (@pxref{Definition of -with-temp-buffer,, Current Buffer}). Several of the macros defined in -this manual use @code{unwind-protect} in this way. - -@findex ftp-login - Here is an actual example derived from an FTP package. It creates a -process (@pxref{Processes}) to try to establish a connection to a remote -machine. As the function @code{ftp-login} is highly susceptible to -numerous problems that the writer of the function cannot anticipate, it -is protected with a form that guarantees deletion of the process in the -event of failure. Otherwise, Emacs might fill up with useless -subprocesses. - -@example -@group -(let ((win nil)) - (unwind-protect - (progn - (setq process (ftp-setup-buffer host file)) - (if (setq win (ftp-login process host user password)) - (message "Logged in") - (error "Ftp login failed"))) - (or win (and process (delete-process process))))) -@end group -@end example - - This example has a small bug: if the user types @kbd{C-g} to -quit, and the quit happens immediately after the function -@code{ftp-setup-buffer} returns but before the variable @code{process} is -set, the process will not be killed. There is no easy way to fix this bug, -but at least it is very unlikely. diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi deleted file mode 100644 index be224987d29..00000000000 --- a/doc/lispref/customize.texi +++ /dev/null @@ -1,1420 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1997-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/customize -@node Customization, Loading, Macros, Top -@chapter Customization Settings - -@cindex customization item - This chapter describes how to declare customizable variables and -customization groups for classifying them. We use the term -@dfn{customization item} to include customizable variables, -customization groups, as well as faces. - - @xref{Defining Faces}, for the @code{defface} macro, which is used -for declaring customizable faces. - -@menu -* Common Keywords:: Common keyword arguments for all kinds of - customization declarations. -* Group Definitions:: Writing customization group definitions. -* Variable Definitions:: Declaring user options. -* Customization Types:: Specifying the type of a user option. -* Applying Customizations:: Functions to apply customization settings. -* Custom Themes:: Writing Custom themes. -@end menu - -@node Common Keywords -@section Common Item Keywords - -@cindex customization keywords - The customization declarations that we will describe in the next few -sections (@code{defcustom}, @code{defgroup}, etc.) all accept keyword -arguments for specifying various information. This section describes -keywords that apply to all types of customization declarations. - - All of these keywords, except @code{:tag}, can be used more than once -in a given item. Each use of the keyword has an independent effect. -The keyword @code{:tag} is an exception because any given item can only -display one name. - -@table @code -@item :tag @var{label} -@kindex tag@r{, customization keyword} -Use @var{label}, a string, instead of the item's name, to label the -item in customization menus and buffers. @strong{Don't use a tag -which is substantially different from the item's real name; that would -cause confusion.} - -@kindex group@r{, customization keyword} -@item :group @var{group} -Put this customization item in group @var{group}. When you use -@code{:group} in a @code{defgroup}, it makes the new group a subgroup of -@var{group}. - -If you use this keyword more than once, you can put a single item into -more than one group. Displaying any of those groups will show this -item. Please don't overdo this, since the result would be annoying. - -@item :link @var{link-data} -@kindex link@r{, customization keyword} -Include an external link after the documentation string for this item. -This is a sentence containing an active field which references some -other documentation. - -There are several alternatives you can use for @var{link-data}: - -@table @code -@item (custom-manual @var{info-node}) -Link to an Info node; @var{info-node} is a string which specifies the -node name, as in @code{"(emacs)Top"}. The link appears as -@samp{[Manual]} in the customization buffer and enters the built-in -Info reader on @var{info-node}. - -@item (info-link @var{info-node}) -Like @code{custom-manual} except that the link appears -in the customization buffer with the Info node name. - -@item (url-link @var{url}) -Link to a web page; @var{url} is a string which specifies the -@acronym{URL}. The link appears in the customization buffer as -@var{url} and invokes the WWW browser specified by -@code{browse-url-browser-function}. - -@item (emacs-commentary-link @var{library}) -Link to the commentary section of a library; @var{library} is a string -which specifies the library name. - -@item (emacs-library-link @var{library}) -Link to an Emacs Lisp library file; @var{library} is a string which -specifies the library name. - -@item (file-link @var{file}) -Link to a file; @var{file} is a string which specifies the name of the -file to visit with @code{find-file} when the user invokes this link. - -@item (function-link @var{function}) -Link to the documentation of a function; @var{function} is a string -which specifies the name of the function to describe with -@code{describe-function} when the user invokes this link. - -@item (variable-link @var{variable}) -Link to the documentation of a variable; @var{variable} is a string -which specifies the name of the variable to describe with -@code{describe-variable} when the user invokes this link. - -@item (custom-group-link @var{group}) -Link to another customization group. Invoking it creates a new -customization buffer for @var{group}. -@end table - -You can specify the text to use in the customization buffer by adding -@code{:tag @var{name}} after the first element of the @var{link-data}; -for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to -the Emacs manual which appears in the buffer as @samp{foo}. - -You can use this keyword more than once, to add multiple links. - -@item :load @var{file} -@kindex load@r{, customization keyword} -Load file @var{file} (a string) before displaying this customization -item (@pxref{Loading}). Loading is done with @code{load}, and only if -the file is not already loaded. - -@item :require @var{feature} -@kindex require@r{, customization keyword} -Execute @code{(require '@var{feature})} when your saved customizations -set the value of this item. @var{feature} should be a symbol. - -The most common reason to use @code{:require} is when a variable enables -a feature such as a minor mode, and just setting the variable won't have -any effect unless the code which implements the mode is loaded. - -@item :version @var{version} -@kindex version@r{, customization keyword} -This keyword specifies that the item was first introduced in Emacs -version @var{version}, or that its default value was changed in that -version. The value @var{version} must be a string. - -@item :package-version '(@var{package} . @var{version}) -@kindex package-version@r{, customization keyword} -This keyword specifies that the item was first introduced in -@var{package} version @var{version}, or that its meaning or default -value was changed in that version. This keyword takes priority over -@code{:version}. - -@var{package} should be the official name of the package, as a symbol -(e.g.@: @code{MH-E}). @var{version} should be a string. If the -package @var{package} is released as part of Emacs, @var{package} and -@var{version} should appear in the value of -@code{customize-package-emacs-version-alist}. -@end table - -Packages distributed as part of Emacs that use the -@code{:package-version} keyword must also update the -@code{customize-package-emacs-version-alist} variable. - -@defvar customize-package-emacs-version-alist -This alist provides a mapping for the versions of Emacs that are -associated with versions of a package listed in the -@code{:package-version} keyword. Its elements are: - -@example -(@var{package} (@var{pversion} . @var{eversion})@dots{}) -@end example - -For each @var{package}, which is a symbol, there are one or more -elements that contain a package version @var{pversion} with an -associated Emacs version @var{eversion}. These versions are strings. -For example, the MH-E package updates this alist with the following: - -@c Must be small else too wide. -@c FIXME obviously this is out of date (in the code). -@smallexample -(add-to-list 'customize-package-emacs-version-alist - '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1") - ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1") - ("7.4" . "22.1") ("8.0" . "22.1"))) -@end smallexample - -The value of @var{package} needs to be unique and it needs to match -the @var{package} value appearing in the @code{:package-version} -keyword. Since the user might see the value in an error message, a good -choice is the official name of the package, such as MH-E or Gnus. -@end defvar - -@node Group Definitions -@section Defining Customization Groups -@cindex define customization group -@cindex customization groups, defining - - Each Emacs Lisp package should have one main customization group which -contains all the options, faces and other groups in the package. If the -package has a small number of options and faces, use just one group and -put everything in it. When there are more than twelve or so options and -faces, then you should structure them into subgroups, and put the -subgroups under the package's main customization group. It is OK to -put some of the options and faces in the package's main group alongside -the subgroups. - - The package's main or only group should be a member of one or more of -the standard customization groups. (To display the full list of them, -use @kbd{M-x customize}.) Choose one or more of them (but not too -many), and add your group to each of them using the @code{:group} -keyword. - - The way to declare new customization groups is with @code{defgroup}. - -@defmac defgroup group members doc [keyword value]@dots{} -Declare @var{group} as a customization group containing @var{members}. -Do not quote the symbol @var{group}. The argument @var{doc} specifies -the documentation string for the group. - -The argument @var{members} is a list specifying an initial set of -customization items to be members of the group. However, most often -@var{members} is @code{nil}, and you specify the group's members by -using the @code{:group} keyword when defining those members. - -If you want to specify group members through @var{members}, each element -should have the form @code{(@var{name} @var{widget})}. Here @var{name} -is a symbol, and @var{widget} is a widget type for editing that symbol. -Useful widgets are @code{custom-variable} for a variable, -@code{custom-face} for a face, and @code{custom-group} for a group. - -When you introduce a new group into Emacs, use the @code{:version} -keyword in the @code{defgroup}; then you need not use it for -the individual members of the group. - -In addition to the common keywords (@pxref{Common Keywords}), you can -also use this keyword in @code{defgroup}: - -@table @code -@item :prefix @var{prefix} -@kindex prefix@r{, @code{defgroup} keyword} -If the name of an item in the group starts with @var{prefix}, and the -customizable variable @code{custom-unlispify-remove-prefixes} is -non-@code{nil}, the item's tag will omit @var{prefix}. A group can -have any number of prefixes. -@end table -@end defmac - -@defopt custom-unlispify-remove-prefixes -If this variable is non-@code{nil}, the prefixes specified by a -group's @code{:prefix} keyword are omitted from tag names, whenever -the user customizes the group. - -The default value is @code{nil}, i.e.@: the prefix-discarding feature -is disabled. This is because discarding prefixes often leads to -confusing names for options and faces. -@end defopt - -@node Variable Definitions -@section Defining Customization Variables -@cindex define customization options -@cindex customization variables, how to define - -@defmac defcustom option standard doc [keyword value]@dots{} -This macro declares @var{option} as a user option (i.e.@: a -customizable variable). You should not quote @var{option}. - -The argument @var{standard} is an expression that specifies the -standard value for @var{option}. Evaluating the @code{defcustom} form -evaluates @var{standard}, but does not necessarily install the -standard value. If @var{option} already has a default value, -@code{defcustom} does not change it. If the user has saved a -customization for @var{option}, @code{defcustom} installs the user's -customized value as @var{option}'s default value. If neither of those -cases applies, @code{defcustom} installs the result of evaluating -@var{standard} as the default value. - -The expression @var{standard} can be evaluated at various other times, -too---whenever the customization facility needs to know @var{option}'s -standard value. So be sure to use an expression which is harmless to -evaluate at any time. - -The argument @var{doc} specifies the documentation string for the -variable. - -Every @code{defcustom} should specify @code{:group} at least once. - -When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp -mode (@code{eval-defun}), a special feature of @code{eval-defun} -arranges to set the variable unconditionally, without testing whether -its value is void. (The same feature applies to @code{defvar}.) -@xref{Defining Variables}. - -If you put a @code{defcustom} in a pre-loaded Emacs Lisp file -(@pxref{Building Emacs}), the standard value installed at dump time -might be incorrect, e.g.@: because another variable that it depends on -has not been assigned the right value yet. In that case, use -@code{custom-reevaluate-setting}, described below, to re-evaluate the -standard value after Emacs starts up. -@end defmac - - @code{defcustom} accepts the following additional keywords: - -@table @code -@item :type @var{type} -Use @var{type} as the data type for this option. It specifies which -values are legitimate, and how to display the value. -@xref{Customization Types}, for more information. - -@item :options @var{value-list} -@kindex options@r{, @code{defcustom} keyword} -Specify the list of reasonable values for use in this -option. The user is not restricted to using only these values, but they -are offered as convenient alternatives. - -This is meaningful only for certain types, currently including -@code{hook}, @code{plist} and @code{alist}. See the definition of the -individual types for a description of how to use @code{:options}. - -@item :set @var{setfunction} -@kindex set@r{, @code{defcustom} keyword} -Specify @var{setfunction} as the way to change the value of this -option when using the Customize interface. The function -@var{setfunction} should take two arguments, a symbol (the option -name) and the new value, and should do whatever is necessary to update -the value properly for this option (which may not mean simply setting -the option as a Lisp variable). The default for @var{setfunction} is -@code{set-default}. - -If you specify this keyword, the variable's documentation string -should describe how to do the same job in hand-written Lisp code. - -@item :get @var{getfunction} -@kindex get@r{, @code{defcustom} keyword} -Specify @var{getfunction} as the way to extract the value of this -option. The function @var{getfunction} should take one argument, a -symbol, and should return whatever customize should use as the -``current value'' for that symbol (which need not be the symbol's Lisp -value). The default is @code{default-value}. - -You have to really understand the workings of Custom to use -@code{:get} correctly. It is meant for values that are treated in -Custom as variables but are not actually stored in Lisp variables. It -is almost surely a mistake to specify @var{getfunction} for a value -that really is stored in a Lisp variable. - -@item :initialize @var{function} -@kindex initialize@r{, @code{defcustom} keyword} -@var{function} should be a function used to initialize the variable -when the @code{defcustom} is evaluated. It should take two arguments, -the option name (a symbol) and the value. Here are some predefined -functions meant for use in this way: - -@table @code -@item custom-initialize-set -Use the variable's @code{:set} function to initialize the variable, but -do not reinitialize it if it is already non-void. - -@item custom-initialize-default -Like @code{custom-initialize-set}, but use the function -@code{set-default} to set the variable, instead of the variable's -@code{:set} function. This is the usual choice for a variable whose -@code{:set} function enables or disables a minor mode; with this choice, -defining the variable will not call the minor mode function, but -customizing the variable will do so. - -@item custom-initialize-reset -Always use the @code{:set} function to initialize the variable. If -the variable is already non-void, reset it by calling the @code{:set} -function using the current value (returned by the @code{:get} method). -This is the default @code{:initialize} function. - -@item custom-initialize-changed -Use the @code{:set} function to initialize the variable, if it is -already set or has been customized; otherwise, just use -@code{set-default}. - -@item custom-initialize-safe-set -@itemx custom-initialize-safe-default -These functions behave like @code{custom-initialize-set} -(@code{custom-initialize-default}, respectively), but catch errors. -If an error occurs during initialization, they set the variable to -@code{nil} using @code{set-default}, and signal no error. - -These functions are meant for options defined in pre-loaded files, -where the @var{standard} expression may signal an error because some -required variable or function is not yet defined. The value normally -gets updated in @file{startup.el}, ignoring the value computed by -@code{defcustom}. After startup, if one unsets the value and -reevaluates the @code{defcustom}, the @var{standard} expression can be -evaluated without error. -@end table - -@item :risky @var{value} -@kindex risky@r{, @code{defcustom} keyword} -Set the variable's @code{risky-local-variable} property to -@var{value} (@pxref{File Local Variables}). - -@item :safe @var{function} -@kindex safe@r{, @code{defcustom} keyword} -Set the variable's @code{safe-local-variable} property to -@var{function} (@pxref{File Local Variables}). - -@item :set-after @var{variables} -@kindex set-after@r{, @code{defcustom} keyword} -When setting variables according to saved customizations, make sure to -set the variables @var{variables} before this one; i.e., delay -setting this variable until after those others have been handled. Use -@code{:set-after} if setting this variable won't work properly unless -those other variables already have their intended values. -@end table - - It is useful to specify the @code{:require} keyword for an option -that ``turns on'' a certain feature. This causes Emacs to load the -feature, if it is not already loaded, whenever the option is set. -@xref{Common Keywords}. Here is an example, from the library -@file{saveplace.el}: - -@example -(defcustom save-place nil - "Non-nil means automatically save place in each file..." - :type 'boolean - :require 'saveplace - :group 'save-place) -@end example - -If a customization item has a type such as @code{hook} or -@code{alist}, which supports @code{:options}, you can add additional -values to the list from outside the @code{defcustom} declaration by -calling @code{custom-add-frequent-value}. For example, if you define a -function @code{my-lisp-mode-initialization} intended to be called from -@code{emacs-lisp-mode-hook}, you might want to add that to the list of -reasonable values for @code{emacs-lisp-mode-hook}, but not by editing -its definition. You can do it thus: - -@example -(custom-add-frequent-value 'emacs-lisp-mode-hook - 'my-lisp-mode-initialization) -@end example - -@defun custom-add-frequent-value symbol value -For the customization option @var{symbol}, add @var{value} to the -list of reasonable values. - -The precise effect of adding a value depends on the customization type -of @var{symbol}. -@end defun - -Internally, @code{defcustom} uses the symbol property -@code{standard-value} to record the expression for the standard value, -@code{saved-value} to record the value saved by the user with the -customization buffer, and @code{customized-value} to record the value -set by the user with the customization buffer, but not saved. -@xref{Property Lists}. These properties are lists, the car of which -is an expression that evaluates to the value. - -@defun custom-reevaluate-setting symbol -This function re-evaluates the standard value of @var{symbol}, which -should be a user option declared via @code{defcustom}. If the -variable was customized, this function re-evaluates the saved value -instead. Then it sets the user option to that value (using the -option's @code{:set} property if that is defined). - -This is useful for customizable options that are defined before their -value could be computed correctly. For example, during startup Emacs -calls this function for some user options that were defined in -pre-loaded Emacs Lisp files, but whose initial values depend on -information available only at run-time. -@end defun - -@defun custom-variable-p arg -This function returns non-@code{nil} if @var{arg} is a customizable -variable. A customizable variable is either a variable that has a -@code{standard-value} or @code{custom-autoload} property (usually -meaning it was declared with @code{defcustom}), or an alias for -another customizable variable. -@end defun - -@defun user-variable-p arg -This function is like @code{custom-variable-p}, except it also returns -@code{t} if the first character of the variable's documentation string -is the character @samp{*}. That is an obsolete way of indicating a -user option, so for most purposes you may consider -@code{user-variable-p} as equivalent to @code{custom-variable-p}. -@end defun - -@node Customization Types -@section Customization Types - -@cindex customization types - When you define a user option with @code{defcustom}, you must specify -its @dfn{customization type}. That is a Lisp object which describes (1) -which values are legitimate and (2) how to display the value in the -customization buffer for editing. - -@kindex type@r{, @code{defcustom} keyword} - You specify the customization type in @code{defcustom} with the -@code{:type} keyword. The argument of @code{:type} is evaluated, but -only once when the @code{defcustom} is executed, so it isn't useful -for the value to vary. Normally we use a quoted constant. For -example: - -@example -(defcustom diff-command "diff" - "The command to use to run diff." - :type '(string) - :group 'diff) -@end example - - In general, a customization type is a list whose first element is a -symbol, one of the customization type names defined in the following -sections. After this symbol come a number of arguments, depending on -the symbol. Between the type symbol and its arguments, you can -optionally write keyword-value pairs (@pxref{Type Keywords}). - - Some type symbols do not use any arguments; those are called -@dfn{simple types}. For a simple type, if you do not use any -keyword-value pairs, you can omit the parentheses around the type -symbol. For example just @code{string} as a customization type is -equivalent to @code{(string)}. - - All customization types are implemented as widgets; see @ref{Top, , -Introduction, widget, The Emacs Widget Library}, for details. - -@menu -* Simple Types:: Simple customization types: sexp, integer, etc. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. -@end menu - -@node Simple Types -@subsection Simple Types - - This section describes all the simple customization types. For -several of these customization types, the customization widget -provides inline completion with @kbd{C-M-i} or @kbd{M-@key{TAB}}. - -@table @code -@item sexp -The value may be any Lisp object that can be printed and read back. -You can use @code{sexp} as a fall-back for any option, if you don't -want to take the time to work out a more specific type to use. - -@item integer -The value must be an integer. - -@item number -The value must be a number (floating point or integer). - -@item float -The value must be a floating point number. - -@item string -The value must be a string. The customization buffer shows the string -without delimiting @samp{"} characters or @samp{\} quotes. - -@item regexp -Like @code{string} except that the string must be a valid regular -expression. - -@item character -The value must be a character code. A character code is actually an -integer, but this type shows the value by inserting the character in the -buffer, rather than by showing the number. - -@item file -The value must be a file name. The widget provides completion. - -@item (file :must-match t) -The value must be a file name for an existing file. The widget -provides completion. - -@item directory -The value must be a directory name. The widget provides completion. - -@item hook -The value must be a list of functions. This customization type is -used for hook variables. You can use the @code{:options} keyword in a -hook variable's @code{defcustom} to specify a list of functions -recommended for use in the hook; @xref{Variable Definitions}. - -@item symbol -The value must be a symbol. It appears in the customization buffer as -the symbol name. The widget provides completion. - -@item function -The value must be either a lambda expression or a function name. The -widget provides completion for function names. - -@item variable -The value must be a variable name. The widget provides completion. - -@item face -The value must be a symbol which is a face name. The widget provides -completion. - -@item boolean -The value is boolean---either @code{nil} or @code{t}. Note that by -using @code{choice} and @code{const} together (see the next section), -you can specify that the value must be @code{nil} or @code{t}, but also -specify the text to describe each value in a way that fits the specific -meaning of the alternative. - -@item coding-system -The value must be a coding-system name, and you can do completion with -@kbd{M-@key{TAB}}. - -@item color -The value must be a valid color name. The widget provides completion -for color names, as well as a sample and a button for selecting a -color name from a list of color names shown in a @file{*Colors*} -buffer. -@end table - -@node Composite Types -@subsection Composite Types -@cindex composite types (customization) - - When none of the simple types is appropriate, you can use composite -types, which build new types from other types or from specified data. -The specified types or data are called the @dfn{arguments} of the -composite type. The composite type normally looks like this: - -@example -(@var{constructor} @var{arguments}@dots{}) -@end example - -@noindent -but you can also add keyword-value pairs before the arguments, like -this: - -@example -(@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{}) -@end example - - Here is a table of constructors and how to use them to write -composite types: - -@table @code -@item (cons @var{car-type} @var{cdr-type}) -The value must be a cons cell, its @sc{car} must fit @var{car-type}, and -its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string -symbol)} is a customization type which matches values such as -@code{("foo" . foo)}. - -In the customization buffer, the @sc{car} and @sc{cdr} are displayed -and edited separately, each according to their specified type. - -@item (list @var{element-types}@dots{}) -The value must be a list with exactly as many elements as the -@var{element-types} given; and each element must fit the -corresponding @var{element-type}. - -For example, @code{(list integer string function)} describes a list of -three elements; the first element must be an integer, the second a -string, and the third a function. - -In the customization buffer, each element is displayed and edited -separately, according to the type specified for it. - -@item (group @var{element-types}@dots{}) -This works like @code{list} except for the formatting -of text in the Custom buffer. @code{list} labels each -element value with its tag; @code{group} does not. - -@item (vector @var{element-types}@dots{}) -Like @code{list} except that the value must be a vector instead of a -list. The elements work the same as in @code{list}. - -@item (alist :key-type @var{key-type} :value-type @var{value-type}) -The value must be a list of cons-cells, the @sc{car} of each cell -representing a key of customization type @var{key-type}, and the -@sc{cdr} of the same cell representing a value of customization type -@var{value-type}. The user can add and delete key/value pairs, and -edit both the key and the value of each pair. - -If omitted, @var{key-type} and @var{value-type} default to -@code{sexp}. - -The user can add any key matching the specified key type, but you can -give some keys a preferential treatment by specifying them with the -@code{:options} (see @ref{Variable Definitions}). The specified keys -will always be shown in the customize buffer (together with a suitable -value), with a checkbox to include or exclude or disable the key/value -pair from the alist. The user will not be able to edit the keys -specified by the @code{:options} keyword argument. - -The argument to the @code{:options} keywords should be a list of -specifications for reasonable keys in the alist. Ordinarily, they are -simply atoms, which stand for themselves. For example: - -@example -:options '("foo" "bar" "baz") -@end example - -@noindent -specifies that there are three ``known'' keys, namely @code{"foo"}, -@code{"bar"} and @code{"baz"}, which will always be shown first. - -You may want to restrict the value type for specific keys, for -example, the value associated with the @code{"bar"} key can only be an -integer. You can specify this by using a list instead of an atom in -the list. The first element will specify the key, like before, while -the second element will specify the value type. For example: - -@example -:options '("foo" ("bar" integer) "baz") -@end example - -Finally, you may want to change how the key is presented. By default, -the key is simply shown as a @code{const}, since the user cannot change -the special keys specified with the @code{:options} keyword. However, -you may want to use a more specialized type for presenting the key, like -@code{function-item} if you know it is a symbol with a function binding. -This is done by using a customization type specification instead of a -symbol for the key. - -@example -:options '("foo" ((function-item some-function) integer) - "baz") -@end example - -Many alists use lists with two elements, instead of cons cells. For -example, - -@example -(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) - "Each element is a list of the form (KEY VALUE).") -@end example - -@noindent -instead of - -@example -(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) - "Each element is a cons-cell (KEY . VALUE).") -@end example - -Because of the way lists are implemented on top of cons cells, you can -treat @code{list-alist} in the example above as a cons cell alist, where -the value type is a list with a single element containing the real -value. - -@example -(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) - "Each element is a list of the form (KEY VALUE)." - :type '(alist :value-type (group integer))) -@end example - -The @code{group} widget is used here instead of @code{list} only because -the formatting is better suited for the purpose. - -Similarly, you can have alists with more values associated with each -key, using variations of this trick: - -@example -(defcustom person-data '(("brian" 50 t) - ("dorith" 55 nil) - ("ken" 52 t)) - "Alist of basic info about people. -Each element has the form (NAME AGE MALE-FLAG)." - :type '(alist :value-type (group integer boolean))) -@end example - -@item (plist :key-type @var{key-type} :value-type @var{value-type}) -This customization type is similar to @code{alist} (see above), except -that (i) the information is stored as a property list, -(@pxref{Property Lists}), and (ii) @var{key-type}, if omitted, -defaults to @code{symbol} rather than @code{sexp}. - -@item (choice @var{alternative-types}@dots{}) -The value must fit one of @var{alternative-types}. For example, -@code{(choice integer string)} allows either an integer or a string. - -In the customization buffer, the user selects an alternative -using a menu, and can then edit the value in the usual way for that -alternative. - -Normally the strings in this menu are determined automatically from the -choices; however, you can specify different strings for the menu by -including the @code{:tag} keyword in the alternatives. For example, if -an integer stands for a number of spaces, while a string is text to use -verbatim, you might write the customization type this way, - -@example -(choice (integer :tag "Number of spaces") - (string :tag "Literal text")) -@end example - -@noindent -so that the menu offers @samp{Number of spaces} and @samp{Literal text}. - -In any alternative for which @code{nil} is not a valid value, other than -a @code{const}, you should specify a valid default for that alternative -using the @code{:value} keyword. @xref{Type Keywords}. - -If some values are covered by more than one of the alternatives, -customize will choose the first alternative that the value fits. This -means you should always list the most specific types first, and the -most general last. Here's an example of proper usage: - -@example -(choice (const :tag "Off" nil) - symbol (sexp :tag "Other")) -@end example - -@noindent -This way, the special value @code{nil} is not treated like other -symbols, and symbols are not treated like other Lisp expressions. - -@item (radio @var{element-types}@dots{}) -This is similar to @code{choice}, except that the choices are displayed -using `radio buttons' rather than a menu. This has the advantage of -displaying documentation for the choices when applicable and so is often -a good choice for a choice between constant functions -(@code{function-item} customization types). - -@item (const @var{value}) -The value must be @var{value}---nothing else is allowed. - -The main use of @code{const} is inside of @code{choice}. For example, -@code{(choice integer (const nil))} allows either an integer or -@code{nil}. - -@code{:tag} is often used with @code{const}, inside of @code{choice}. -For example, - -@example -(choice (const :tag "Yes" t) - (const :tag "No" nil) - (const :tag "Ask" foo)) -@end example - -@noindent -describes a variable for which @code{t} means yes, @code{nil} means no, -and @code{foo} means ``ask''. - -@item (other @var{value}) -This alternative can match any Lisp value, but if the user chooses this -alternative, that selects the value @var{value}. - -The main use of @code{other} is as the last element of @code{choice}. -For example, - -@example -(choice (const :tag "Yes" t) - (const :tag "No" nil) - (other :tag "Ask" foo)) -@end example - -@noindent -describes a variable for which @code{t} means yes, @code{nil} means no, -and anything else means ``ask''. If the user chooses @samp{Ask} from -the menu of alternatives, that specifies the value @code{foo}; but any -other value (not @code{t}, @code{nil} or @code{foo}) displays as -@samp{Ask}, just like @code{foo}. - -@item (function-item @var{function}) -Like @code{const}, but used for values which are functions. This -displays the documentation string as well as the function name. -The documentation string is either the one you specify with -@code{:doc}, or @var{function}'s own documentation string. - -@item (variable-item @var{variable}) -Like @code{const}, but used for values which are variable names. This -displays the documentation string as well as the variable name. The -documentation string is either the one you specify with @code{:doc}, or -@var{variable}'s own documentation string. - -@item (set @var{types}@dots{}) -The value must be a list, and each element of the list must match one of -the @var{types} specified. - -This appears in the customization buffer as a checklist, so that each of -@var{types} may have either one corresponding element or none. It is -not possible to specify two different elements that match the same one -of @var{types}. For example, @code{(set integer symbol)} allows one -integer and/or one symbol in the list; it does not allow multiple -integers or multiple symbols. As a result, it is rare to use -nonspecific types such as @code{integer} in a @code{set}. - -Most often, the @var{types} in a @code{set} are @code{const} types, as -shown here: - -@example -(set (const :bold) (const :italic)) -@end example - -Sometimes they describe possible elements in an alist: - -@example -(set (cons :tag "Height" (const height) integer) - (cons :tag "Width" (const width) integer)) -@end example - -@noindent -That lets the user specify a height value optionally -and a width value optionally. - -@item (repeat @var{element-type}) -The value must be a list and each element of the list must fit the type -@var{element-type}. This appears in the customization buffer as a -list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding -more elements or removing elements. - -@item (restricted-sexp :match-alternatives @var{criteria}) -This is the most general composite type construct. The value may be -any Lisp object that satisfies one of @var{criteria}. @var{criteria} -should be a list, and each element should be one of these -possibilities: - -@itemize @bullet -@item -A predicate---that is, a function of one argument that has no side -effects, and returns either @code{nil} or non-@code{nil} according to -the argument. Using a predicate in the list says that objects for which -the predicate returns non-@code{nil} are acceptable. - -@item -A quoted constant---that is, @code{'@var{object}}. This sort of element -in the list says that @var{object} itself is an acceptable value. -@end itemize - -For example, - -@example -(restricted-sexp :match-alternatives - (integerp 't 'nil)) -@end example - -@noindent -allows integers, @code{t} and @code{nil} as legitimate values. - -The customization buffer shows all legitimate values using their read -syntax, and the user edits them textually. -@end table - - Here is a table of the keywords you can use in keyword-value pairs -in a composite type: - -@table @code -@item :tag @var{tag} -Use @var{tag} as the name of this alternative, for user communication -purposes. This is useful for a type that appears inside of a -@code{choice}. - -@item :match-alternatives @var{criteria} -@kindex match-alternatives@r{, customization keyword} -Use @var{criteria} to match possible values. This is used only in -@code{restricted-sexp}. - -@item :args @var{argument-list} -@kindex args@r{, customization keyword} -Use the elements of @var{argument-list} as the arguments of the type -construct. For instance, @code{(const :args (foo))} is equivalent to -@code{(const foo)}. You rarely need to write @code{:args} explicitly, -because normally the arguments are recognized automatically as -whatever follows the last keyword-value pair. -@end table - -@node Splicing into Lists -@subsection Splicing into Lists - - The @code{:inline} feature lets you splice a variable number of -elements into the middle of a @code{list} or @code{vector} -customization type. You use it by adding @code{:inline t} to a type -specification which is contained in a @code{list} or @code{vector} -specification. - - Normally, each entry in a @code{list} or @code{vector} type -specification describes a single element type. But when an entry -contains @code{:inline t}, the value it matches is merged directly -into the containing sequence. For example, if the entry matches a -list with three elements, those become three elements of the overall -sequence. This is analogous to @samp{,@@} in a backquote construct -(@pxref{Backquote}). - - For example, to specify a list whose first element must be @code{baz} -and whose remaining arguments should be zero or more of @code{foo} and -@code{bar}, use this customization type: - -@example -(list (const baz) (set :inline t (const foo) (const bar))) -@end example - -@noindent -This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)} -and @code{(baz foo bar)}. - - When the element-type is a @code{choice}, you use @code{:inline} not -in the @code{choice} itself, but in (some of) the alternatives of the -@code{choice}. For example, to match a list which must start with a -file name, followed either by the symbol @code{t} or two strings, use -this customization type: - -@example -(list file - (choice (const t) - (list :inline t string string))) -@end example - -@noindent -If the user chooses the first alternative in the choice, then the -overall list has two elements and the second element is @code{t}. If -the user chooses the second alternative, then the overall list has three -elements and the second and third must be strings. - -@node Type Keywords -@subsection Type Keywords - -You can specify keyword-argument pairs in a customization type after the -type name symbol. Here are the keywords you can use, and their -meanings: - -@table @code -@item :value @var{default} -Provide a default value. - -If @code{nil} is not a valid value for the alternative, then it is -essential to specify a valid default with @code{:value}. - -If you use this for a type that appears as an alternative inside of -@code{choice}; it specifies the default value to use, at first, if and -when the user selects this alternative with the menu in the -customization buffer. - -Of course, if the actual value of the option fits this alternative, it -will appear showing the actual value, not @var{default}. - -@item :format @var{format-string} -@kindex format@r{, customization keyword} -This string will be inserted in the buffer to represent the value -corresponding to the type. The following @samp{%} escapes are available -for use in @var{format-string}: - -@table @samp -@item %[@var{button}%] -Display the text @var{button} marked as a button. The @code{:action} -attribute specifies what the button will do if the user invokes it; -its value is a function which takes two arguments---the widget which -the button appears in, and the event. - -There is no way to specify two different buttons with different -actions. - -@item %@{@var{sample}%@} -Show @var{sample} in a special face specified by @code{:sample-face}. - -@item %v -Substitute the item's value. How the value is represented depends on -the kind of item, and (for variables) on the customization type. - -@item %d -Substitute the item's documentation string. - -@item %h -Like @samp{%d}, but if the documentation string is more than one line, -add an active field to control whether to show all of it or just the -first line. - -@item %t -Substitute the tag here. You specify the tag with the @code{:tag} -keyword. - -@item %% -Display a literal @samp{%}. -@end table - -@item :action @var{action} -@kindex action@r{, customization keyword} -Perform @var{action} if the user clicks on a button. - -@item :button-face @var{face} -@kindex button-face@r{, customization keyword} -Use the face @var{face} (a face name or a list of face names) for button -text displayed with @samp{%[@dots{}%]}. - -@item :button-prefix @var{prefix} -@itemx :button-suffix @var{suffix} -@kindex button-prefix@r{, customization keyword} -@kindex button-suffix@r{, customization keyword} -These specify the text to display before and after a button. -Each can be: - -@table @asis -@item @code{nil} -No text is inserted. - -@item a string -The string is inserted literally. - -@item a symbol -The symbol's value is used. -@end table - -@item :tag @var{tag} -Use @var{tag} (a string) as the tag for the value (or part of the value) -that corresponds to this type. - -@item :doc @var{doc} -@kindex doc@r{, customization keyword} -Use @var{doc} as the documentation string for this value (or part of the -value) that corresponds to this type. In order for this to work, you -must specify a value for @code{:format}, and use @samp{%d} or @samp{%h} -in that value. - -The usual reason to specify a documentation string for a type is to -provide more information about the meanings of alternatives inside a -@code{:choice} type or the parts of some other composite type. - -@item :help-echo @var{motion-doc} -@kindex help-echo@r{, customization keyword} -When you move to this item with @code{widget-forward} or -@code{widget-backward}, it will display the string @var{motion-doc} in -the echo area. In addition, @var{motion-doc} is used as the mouse -@code{help-echo} string and may actually be a function or form evaluated -to yield a help string. If it is a function, it is called with one -argument, the widget. - -@item :match @var{function} -@kindex match@r{, customization keyword} -Specify how to decide whether a value matches the type. The -corresponding value, @var{function}, should be a function that accepts -two arguments, a widget and a value; it should return non-@code{nil} if -the value is acceptable. - -@item :validate @var{function} -Specify a validation function for input. @var{function} takes a -widget as an argument, and should return @code{nil} if the widget's -current value is valid for the widget. Otherwise, it should return -the widget containing the invalid data, and set that widget's -@code{:error} property to a string explaining the error. - -@ignore -@item :indent @var{columns} -Indent this item by @var{columns} columns. The indentation is used for -@samp{%n}, and automatically for group names, for checklists and radio -buttons, and for editable lists. It affects the whole of the -item except for the first line. - -@item :offset @var{extra} -Indent the subitems of this item @var{extra} columns more than this -item itself. By default, subitems are indented the same as their -parent. - -@item :extra-offset @var{n} -Add @var{n} extra spaces to this item's indentation, compared to its -parent's indentation. - -@item :notify @var{function} -Call @var{function} each time the item or a subitem is changed. The -function gets two or three arguments. The first argument is the item -itself, the second argument is the item that was changed, and the -third argument is the event leading to the change, if any. - -@item :menu-tag @var{tag-string} -Use @var{tag-string} in the menu when the widget is used as an option -in a @code{menu-choice} widget. - -@item :menu-tag-get -A function used for finding the tag when the widget is used as an option -in a @code{menu-choice} widget. By default, the tag used will be either the -@code{:menu-tag} or @code{:tag} property if present, or the @code{princ} -representation of the @code{:value} property if not. - -@item :tab-order -Specify the order in which widgets are traversed with -@code{widget-forward} or @code{widget-backward}. This is only partially -implemented. - -@enumerate a -@item -Widgets with tabbing order @code{-1} are ignored. - -@item -(Unimplemented) When on a widget with tabbing order @var{n}, go to the -next widget in the buffer with tabbing order @var{n+1} or @code{nil}, -whichever comes first. - -@item -When on a widget with no tabbing order specified, go to the next widget -in the buffer with a positive tabbing order, or @code{nil} -@end enumerate - -@item :parent -The parent of a nested widget (e.g., a @code{menu-choice} item or an -element of a @code{editable-list} widget). - -@item :sibling-args -This keyword is only used for members of a @code{radio-button-choice} or -@code{checklist}. The value should be a list of extra keyword -arguments, which will be used when creating the @code{radio-button} or -@code{checkbox} associated with this item. -@end ignore -@end table - -@node Defining New Types -@subsection Defining New Types - -In the previous sections we have described how to construct elaborate -type specifications for @code{defcustom}. In some cases you may want -to give such a type specification a name. The obvious case is when -you are using the same type for many user options: rather than repeat -the specification for each option, you can give the type specification -a name, and use that name each @code{defcustom}. The other case is -when a user option's value is a recursive data structure. To make it -possible for a datatype to refer to itself, it needs to have a name. - -Since custom types are implemented as widgets, the way to define a new -customize type is to define a new widget. We are not going to describe -the widget interface here in details, see @ref{Top, , Introduction, -widget, The Emacs Widget Library}, for that. Instead we are going to -demonstrate the minimal functionality needed for defining new customize -types by a simple example. - -@example -(define-widget 'binary-tree-of-string 'lazy - "A binary tree made of cons-cells and strings." - :offset 4 - :tag "Node" - :type '(choice (string :tag "Leaf" :value "") - (cons :tag "Interior" - :value ("" . "") - binary-tree-of-string - binary-tree-of-string))) - -(defcustom foo-bar "" - "Sample variable holding a binary tree of strings." - :type 'binary-tree-of-string) -@end example - -The function to define a new widget is called @code{define-widget}. The -first argument is the symbol we want to make a new widget type. The -second argument is a symbol representing an existing widget, the new -widget is going to be defined in terms of difference from the existing -widget. For the purpose of defining new customization types, the -@code{lazy} widget is perfect, because it accepts a @code{:type} keyword -argument with the same syntax as the keyword argument to -@code{defcustom} with the same name. The third argument is a -documentation string for the new widget. You will be able to see that -string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string -@key{RET}} command. - -After these mandatory arguments follow the keyword arguments. The most -important is @code{:type}, which describes the data type we want to match -with this widget. Here a @code{binary-tree-of-string} is described as -being either a string, or a cons-cell whose car and cdr are themselves -both @code{binary-tree-of-string}. Note the reference to the widget -type we are currently in the process of defining. The @code{:tag} -attribute is a string to name the widget in the user interface, and the -@code{:offset} argument is there to ensure that child nodes are -indented four spaces relative to the parent node, making the tree -structure apparent in the customization buffer. - -The @code{defcustom} shows how the new widget can be used as an ordinary -customization type. - -The reason for the name @code{lazy} is that the other composite -widgets convert their inferior widgets to internal form when the -widget is instantiated in a buffer. This conversion is recursive, so -the inferior widgets will convert @emph{their} inferior widgets. If -the data structure is itself recursive, this conversion is an infinite -recursion. The @code{lazy} widget prevents the recursion: it convert -its @code{:type} argument only when needed. - -@node Applying Customizations -@section Applying Customizations - -The following functions are responsible for installing the user's -customization settings for variables and faces, respectively. When -the user invokes @samp{Save for future sessions} in the Customize -interface, that takes effect by writing a @code{custom-set-variables} -and/or a @code{custom-set-faces} form into the custom file, to be -evaluated the next time Emacs starts. - -@defun custom-set-variables &rest args -This function installs the variable customizations specified by -@var{args}. Each argument in @var{args} should have the form - -@example -(@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]]) -@end example - -@noindent -@var{var} is a variable name (a symbol), and @var{expression} is an -expression which evaluates to the desired customized value. - -If the @code{defcustom} form for @var{var} has been evaluated prior to -this @code{custom-set-variables} call, @var{expression} is immediately -evaluated, and the variable's value is set to the result. Otherwise, -@var{expression} is stored into the variable's @code{saved-value} -property, to be evaluated when the relevant @code{defcustom} is called -(usually when the library defining that variable is loaded into -Emacs). - -The @var{now}, @var{request}, and @var{comment} entries are for -internal use only, and may be omitted. @var{now}, if non-@code{nil}, -means to set the variable's value now, even if the variable's -@code{defcustom} form has not been evaluated. @var{request} is a list -of features to be loaded immediately (@pxref{Named Features}). -@var{comment} is a string describing the customization. -@end defun - -@defun custom-set-faces &rest args -This function installs the face customizations specified by -@var{args}. Each argument in @var{args} should have the form - -@example -(@var{face} @var{spec} [@var{now} [@var{comment}]]) -@end example - -@noindent -@var{face} is a face name (a symbol), and @var{spec} is the customized -face specification for that face (@pxref{Defining Faces}). - -The @var{now} and @var{comment} entries are for internal use only, and -may be omitted. @var{now}, if non-@code{nil}, means to install the -face specification now, even if the @code{defface} form has not been -evaluated. @var{comment} is a string describing the customization. -@end defun - -@node Custom Themes -@section Custom Themes - - @dfn{Custom themes} are collections of settings that can be enabled -or disabled as a unit. @xref{Custom Themes,,, emacs, The GNU Emacs -Manual}. Each Custom theme is defined by an Emacs Lisp source file, -which should follow the conventions described in this section. -(Instead of writing a Custom theme by hand, you can also create one -using a Customize-like interface; @pxref{Creating Custom Themes,,, -emacs, The GNU Emacs Manual}.) - - A Custom theme file should be named @file{@var{foo}-theme.el}, where -@var{foo} is the theme name. The first Lisp form in the file should -be a call to @code{deftheme}, and the last form should be a call to -@code{provide-theme}. - -@defmac deftheme theme &optional doc -This macro declares @var{theme} (a symbol) as the name of a Custom -theme. The optional argument @var{doc} should be a string describing -the theme; this is the description shown when the user invokes the -@code{describe-theme} command or types @kbd{?} in the @samp{*Custom -Themes*} buffer. - -Two special theme names are disallowed (using them causes an error): -@code{user} is a ``dummy'' theme that stores the user's direct -customization settings, and @code{changed} is a ``dummy'' theme that -stores changes made outside of the Customize system. -@end defmac - -@defmac provide-theme theme -This macro declares that the theme named @var{theme} has been fully -specified. -@end defmac - - In between @code{deftheme} and @code{provide-theme} are Lisp forms -specifying the theme settings: usually a call to -@code{custom-theme-set-variables} and/or a call to -@code{custom-theme-set-faces}. - -@defun custom-theme-set-variables theme &rest args -This function specifies the Custom theme @var{theme}'s variable -settings. @var{theme} should be a symbol. Each argument in -@var{args} should be a list of the form - -@example -(@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]]) -@end example - -@noindent -where the list entries have the same meanings as in -@code{custom-set-variables}. @xref{Applying Customizations}. -@end defun - -@defun custom-theme-set-faces theme &rest args -This function specifies the Custom theme @var{theme}'s face settings. -@var{theme} should be a symbol. Each argument in @var{args} should be -a list of the form - -@example -(@var{face} @var{spec} [@var{now} [@var{comment}]]) -@end example - -@noindent -where the list entries have the same meanings as in -@code{custom-set-faces}. @xref{Applying Customizations}. -@end defun - - In theory, a theme file can also contain other Lisp forms, which -would be evaluated when loading the theme, but that is ``bad form''. -To protect against loading themes containing malicious code, Emacs -displays the source file and asks for confirmation from the user -before loading any non-built-in theme for the first time. - - The following functions are useful for programmatically enabling and -disabling themes: - -@defun custom-theme-p theme -This function return a non-@code{nil} value if @var{theme} (a symbol) -is the name of a Custom theme (i.e.@: a Custom theme which has been -loaded into Emacs, whether or not the theme is enabled). Otherwise, -it returns @code{nil}. -@end defun - -@deffn Command load-theme theme &optional no-confirm no-enable -This function loads the Custom theme named @var{theme} from its source -file, looking for the source file in the directories specified by the -variable @code{custom-theme-load-path}. @xref{Custom Themes,,, emacs, -The GNU Emacs Manual}. It also @dfn{enables} the theme (unless the -optional argument @var{no-enable} is non-@code{nil}), causing its -variable and face settings to take effect. It prompts the user for -confirmation before loading the theme, unless the optional argument -@var{no-confirm} is non-@code{nil}. -@end deffn - -@deffn Command enable-theme theme -This function enables the Custom theme named @var{theme}. It signals -an error if no such theme has been loaded. -@end deffn - -@deffn Command disable-theme theme -This function disables the Custom theme named @var{theme}. The theme -remains loaded, so that a subsequent call to @code{enable-theme} will -re-enable it. -@end deffn diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi deleted file mode 100644 index 885766bd1cc..00000000000 --- a/doc/lispref/debugging.texi +++ /dev/null @@ -1,794 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/debugging -@node Debugging, Read and Print, Advising Functions, Top -@chapter Debugging Lisp Programs - - There are several ways to find and investigate problems in an Emacs -Lisp program. - -@itemize @bullet -@item -If a problem occurs when you run the program, you can use the built-in -Emacs Lisp debugger to suspend the Lisp evaluator, and examine and/or -alter its internal state. - -@item -You can use Edebug, a source-level debugger for Emacs Lisp. - -@item -If a syntactic problem is preventing Lisp from even reading the -program, you can locate it using Lisp editing commands. - -@item -You can look at the error and warning messages produced by the byte -compiler when it compiles the program. @xref{Compiler Errors}. - -@item -You can use the Testcover package to perform coverage testing on the -program. - -@item -You can use the ERT package to write regression tests for the program. -@xref{Top,the ERT manual,, ERT, ERT: Emacs Lisp Regression Testing}. -@end itemize - - Other useful tools for debugging input and output problems are the -dribble file (@pxref{Terminal Input}) and the @code{open-termscript} -function (@pxref{Terminal Output}). - -@menu -* Debugger:: A debugger for the Emacs Lisp evaluator. -* Edebug:: A source-level Emacs Lisp debugger. -* Syntax Errors:: How to find syntax errors. -* Test Coverage:: Ensuring you have tested all branches in your code. -@end menu - -@node Debugger -@section The Lisp Debugger -@cindex debugger for Emacs Lisp -@cindex Lisp debugger -@cindex break - - The ordinary @dfn{Lisp debugger} provides the ability to suspend -evaluation of a form. While evaluation is suspended (a state that is -commonly known as a @dfn{break}), you may examine the run time stack, -examine the values of local or global variables, or change those values. -Since a break is a recursive edit, all the usual editing facilities of -Emacs are available; you can even run programs that will enter the -debugger recursively. @xref{Recursive Editing}. - -@menu -* Error Debugging:: Entering the debugger when an error happens. -* Infinite Loops:: Stopping and debugging a program that doesn't exit. -* Function Debugging:: Entering it when a certain function is called. -* Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. -* Debugger Commands:: Commands used while in the debugger. -* Invoking the Debugger:: How to call the function @code{debug}. -* Internals of Debugger:: Subroutines of the debugger, and global variables. -@end menu - -@node Error Debugging -@subsection Entering the Debugger on an Error -@cindex error debugging -@cindex debugging errors - - The most important time to enter the debugger is when a Lisp error -happens. This allows you to investigate the immediate causes of the -error. - - However, entry to the debugger is not a normal consequence of an -error. Many commands signal Lisp errors when invoked inappropriately, -and during ordinary editing it would be very inconvenient to enter the -debugger each time this happens. So if you want errors to enter the -debugger, set the variable @code{debug-on-error} to non-@code{nil}. -(The command @code{toggle-debug-on-error} provides an easy way to do -this.) - -@defopt debug-on-error -This variable determines whether the debugger is called when an error -is signaled and not handled. If @code{debug-on-error} is @code{t}, -all kinds of errors call the debugger, except those listed in -@code{debug-ignored-errors} (see below). If it is @code{nil}, none -call the debugger. - -The value can also be a list of error conditions (@pxref{Signaling -Errors}). Then the debugger is called only for error conditions in -this list (except those also listed in @code{debug-ignored-errors}). -For example, if you set @code{debug-on-error} to the list -@code{(void-variable)}, the debugger is only called for errors about a -variable that has no value. - -Note that @code{eval-expression-debug-on-error} overrides this -variable in some cases; see below. - -When this variable is non-@code{nil}, Emacs does not create an error -handler around process filter functions and sentinels. Therefore, -errors in these functions also invoke the debugger. @xref{Processes}. -@end defopt - -@defopt debug-ignored-errors -This variable specifies errors which should not enter the debugger, -regardless of the value of @code{debug-on-error}. Its value is a list -of error condition symbols and/or regular expressions. If the error -has any of those condition symbols, or if the error message matches -any of the regular expressions, then that error does not enter the -debugger. - -The normal value of this variable lists several errors that happen -often during editing but rarely result from bugs in Lisp programs. -However, ``rarely'' is not ``never''; if your program fails with an -error that matches this list, you may try changing this list to debug -the error. The easiest way is usually to set -@code{debug-ignored-errors} to @code{nil}. -@end defopt - -@defopt eval-expression-debug-on-error -If this variable has a non-@code{nil} value (the default), running the -command @code{eval-expression} causes @code{debug-on-error} to be -temporarily bound to to @code{t}. @xref{Lisp Eval,, Evaluating -Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}. - -If @code{eval-expression-debug-on-error} is @code{nil}, then the value -of @code{debug-on-error} is not changed during @code{eval-expression}. -@end defopt - -@defvar debug-on-signal -Normally, errors caught by @code{condition-case} never invoke the -debugger. The @code{condition-case} gets a chance to handle the error -before the debugger gets a chance. - -If you change @code{debug-on-signal} to a non-@code{nil} value, the -debugger gets the first chance at every error, regardless of the -presence of @code{condition-case}. (To invoke the debugger, the error -must still fulfill the criteria specified by @code{debug-on-error} and -@code{debug-ignored-errors}.) - -@strong{Warning:} Setting this variable to non-@code{nil} may have -annoying effects. Various parts of Emacs catch errors in the normal -course of affairs, and you may not even realize that errors happen -there. If you need to debug code wrapped in @code{condition-case}, -consider using @code{condition-case-unless-debug} (@pxref{Handling -Errors}). -@end defvar - -@defopt debug-on-event -If you set @code{debug-on-event} to a special event (@pxref{Special -Events}), Emacs will try to enter the debugger as soon as it receives -this event, bypassing @code{special-event-map}. At present, the only -supported values correspond to the signals @code{SIGUSR1} and -@code{SIGUSR2} (this is the default). This can be helpful when -@code{inhibit-quit} is set and Emacs is not otherwise responding. -@end defopt - - To debug an error that happens during loading of the init -file, use the option @samp{--debug-init}. This binds -@code{debug-on-error} to @code{t} while loading the init file, and -bypasses the @code{condition-case} which normally catches errors in the -init file. - -@node Infinite Loops -@subsection Debugging Infinite Loops -@cindex infinite loops -@cindex loops, infinite -@cindex quitting from infinite loop -@cindex stopping an infinite loop - - When a program loops infinitely and fails to return, your first -problem is to stop the loop. On most operating systems, you can do -this with @kbd{C-g}, which causes a @dfn{quit}. @xref{Quitting}. - - Ordinary quitting gives no information about why the program was -looping. To get more information, you can set the variable -@code{debug-on-quit} to non-@code{nil}. Once you have the debugger -running in the middle of the infinite loop, you can proceed from the -debugger using the stepping commands. If you step through the entire -loop, you may get enough information to solve the problem. - - Quitting with @kbd{C-g} is not considered an error, and -@code{debug-on-error} has no effect on the handling of @kbd{C-g}. -Likewise, @code{debug-on-quit} has no effect on errors. - -@defopt debug-on-quit -This variable determines whether the debugger is called when -@code{quit} is signaled and not handled. If @code{debug-on-quit} is -non-@code{nil}, then the debugger is called whenever you quit (that -is, type @kbd{C-g}). If @code{debug-on-quit} is @code{nil} (the -default), then the debugger is not called when you quit. -@end defopt - -@node Function Debugging -@subsection Entering the Debugger on a Function Call -@cindex function call debugging -@cindex debugging specific functions - - To investigate a problem that happens in the middle of a program, one -useful technique is to enter the debugger whenever a certain function is -called. You can do this to the function in which the problem occurs, -and then step through the function, or you can do this to a function -called shortly before the problem, step quickly over the call to that -function, and then step through its caller. - -@deffn Command debug-on-entry function-name -This function requests @var{function-name} to invoke the debugger each -time it is called. It works by inserting the form -@code{(implement-debug-on-entry)} into the function definition as the -first form. - -Any function or macro defined as Lisp code may be set to break on -entry, regardless of whether it is interpreted code or compiled code. -If the function is a command, it will enter the debugger when called -from Lisp and when called interactively (after the reading of the -arguments). You can also set debug-on-entry for primitive functions -(i.e., those written in C) this way, but it only takes effect when the -primitive is called from Lisp code. Debug-on-entry is not allowed for -special forms. - -When @code{debug-on-entry} is called interactively, it prompts for -@var{function-name} in the minibuffer. If the function is already set -up to invoke the debugger on entry, @code{debug-on-entry} does nothing. -@code{debug-on-entry} always returns @var{function-name}. - -@strong{Warning:} if you redefine a function after using -@code{debug-on-entry} on it, the code to enter the debugger is -discarded by the redefinition. In effect, redefining the function -cancels the break-on-entry feature for that function. - -Here's an example to illustrate use of this function: - -@example -@group -(defun fact (n) - (if (zerop n) 1 - (* n (fact (1- n))))) - @result{} fact -@end group -@group -(debug-on-entry 'fact) - @result{} fact -@end group -@group -(fact 3) -@end group - -@group ------- Buffer: *Backtrace* ------ -Debugger entered--entering a function: -* fact(3) - eval((fact 3)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ------- Buffer: *Backtrace* ------ -@end group - -@group -(symbol-function 'fact) - @result{} (lambda (n) - (debug (quote debug)) - (if (zerop n) 1 (* n (fact (1- n))))) -@end group -@end example -@end deffn - -@deffn Command cancel-debug-on-entry &optional function-name -This function undoes the effect of @code{debug-on-entry} on -@var{function-name}. When called interactively, it prompts for -@var{function-name} in the minibuffer. If @var{function-name} is -omitted or @code{nil}, it cancels break-on-entry for all functions. -Calling @code{cancel-debug-on-entry} does nothing to a function which is -not currently set up to break on entry. -@end deffn - -@node Explicit Debug -@subsection Explicit Entry to the Debugger - - You can cause the debugger to be called at a certain point in your -program by writing the expression @code{(debug)} at that point. To do -this, visit the source file, insert the text @samp{(debug)} at the -proper place, and type @kbd{C-M-x} (@code{eval-defun}, a Lisp mode key -binding). @strong{Warning:} if you do this for temporary debugging -purposes, be sure to undo this insertion before you save the file! - - The place where you insert @samp{(debug)} must be a place where an -additional form can be evaluated and its value ignored. (If the value -of @code{(debug)} isn't ignored, it will alter the execution of the -program!) The most common suitable places are inside a @code{progn} or -an implicit @code{progn} (@pxref{Sequencing}). - -@node Using Debugger -@subsection Using the Debugger - - When the debugger is entered, it displays the previously selected -buffer in one window and a buffer named @file{*Backtrace*} in another -window. The backtrace buffer contains one line for each level of Lisp -function execution currently going on. At the beginning of this buffer -is a message describing the reason that the debugger was invoked (such -as the error message and associated data, if it was invoked due to an -error). - - The backtrace buffer is read-only and uses a special major mode, -Debugger mode, in which letters are defined as debugger commands. The -usual Emacs editing commands are available; thus, you can switch windows -to examine the buffer that was being edited at the time of the error, -switch buffers, visit files, or do any other sort of editing. However, -the debugger is a recursive editing level (@pxref{Recursive Editing}) -and it is wise to go back to the backtrace buffer and exit the debugger -(with the @kbd{q} command) when you are finished with it. Exiting -the debugger gets out of the recursive edit and kills the backtrace -buffer. - - When the debugger has been entered, the @code{debug-on-error} -variable is temporarily set according to -@code{eval-expression-debug-on-error}. If the latter variable is -non-@code{nil}, @code{debug-on-error} will temporarily be set to -@code{t}. This means that any further errors that occur while doing a -debugging session will (by default) trigger another backtrace. If -this is not want you want, you can either set -@code{eval-expression-debug-on-error} to @code{nil}, or set -@code{debug-on-error} to @code{nil} in @code{debugger-mode-hook}. - -@cindex current stack frame - The backtrace buffer shows you the functions that are executing and -their argument values. It also allows you to specify a stack frame by -moving point to the line describing that frame. (A stack frame is the -place where the Lisp interpreter records information about a particular -invocation of a function.) The frame whose line point is on is -considered the @dfn{current frame}. Some of the debugger commands -operate on the current frame. If a line starts with a star, that means -that exiting that frame will call the debugger again. This is useful -for examining the return value of a function. - - If a function name is underlined, that means the debugger knows -where its source code is located. You can click with the mouse on -that name, or move to it and type @key{RET}, to visit the source code. - - The debugger itself must be run byte-compiled, since it makes -assumptions about how many stack frames are used for the debugger -itself. These assumptions are false if the debugger is running -interpreted. - -@node Debugger Commands -@subsection Debugger Commands -@cindex debugger command list - - The debugger buffer (in Debugger mode) provides special commands in -addition to the usual Emacs commands. The most important use of -debugger commands is for stepping through code, so that you can see -how control flows. The debugger can step through the control -structures of an interpreted function, but cannot do so in a -byte-compiled function. If you would like to step through a -byte-compiled function, replace it with an interpreted definition of -the same function. (To do this, visit the source for the function and -type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger -to step through a primitive function. - - Here is a list of Debugger mode commands: - -@table @kbd -@item c -Exit the debugger and continue execution. This resumes execution of -the program as if the debugger had never been entered (aside from any -side-effects that you caused by changing variable values or data -structures while inside the debugger). - -@item d -Continue execution, but enter the debugger the next time any Lisp -function is called. This allows you to step through the -subexpressions of an expression, seeing what values the subexpressions -compute, and what else they do. - -The stack frame made for the function call which enters the debugger in -this way will be flagged automatically so that the debugger will be -called again when the frame is exited. You can use the @kbd{u} command -to cancel this flag. - -@item b -Flag the current frame so that the debugger will be entered when the -frame is exited. Frames flagged in this way are marked with stars -in the backtrace buffer. - -@item u -Don't enter the debugger when the current frame is exited. This -cancels a @kbd{b} command on that frame. The visible effect is to -remove the star from the line in the backtrace buffer. - -@item j -Flag the current frame like @kbd{b}. Then continue execution like -@kbd{c}, but temporarily disable break-on-entry for all functions that -are set up to do so by @code{debug-on-entry}. - -@item e -Read a Lisp expression in the minibuffer, evaluate it, and print the -value in the echo area. The debugger alters certain important -variables, and the current buffer, as part of its operation; @kbd{e} -temporarily restores their values from outside the debugger, so you can -examine and change them. This makes the debugger more transparent. By -contrast, @kbd{M-:} does nothing special in the debugger; it shows you -the variable values within the debugger. - -@item R -Like @kbd{e}, but also save the result of evaluation in the -buffer @file{*Debugger-record*}. - -@item q -Terminate the program being debugged; return to top-level Emacs -command execution. - -If the debugger was entered due to a @kbd{C-g} but you really want -to quit, and not debug, use the @kbd{q} command. - -@item r -Return a value from the debugger. The value is computed by reading an -expression with the minibuffer and evaluating it. - -The @kbd{r} command is useful when the debugger was invoked due to exit -from a Lisp call frame (as requested with @kbd{b} or by entering the -frame with @kbd{d}); then the value specified in the @kbd{r} command is -used as the value of that frame. It is also useful if you call -@code{debug} and use its return value. Otherwise, @kbd{r} has the same -effect as @kbd{c}, and the specified return value does not matter. - -You can't use @kbd{r} when the debugger was entered due to an error. - -@item l -Display a list of functions that will invoke the debugger when called. -This is a list of functions that are set to break on entry by means of -@code{debug-on-entry}. @strong{Warning:} if you redefine such a -function and thus cancel the effect of @code{debug-on-entry}, it may -erroneously show up in this list. -@end table - -@node Invoking the Debugger -@subsection Invoking the Debugger - - Here we describe in full detail the function @code{debug} that is used -to invoke the debugger. - -@deffn Command debug &rest debugger-args -This function enters the debugger. It switches buffers to a buffer -named @file{*Backtrace*} (or @file{*Backtrace*<2>} if it is the second -recursive entry to the debugger, etc.), and fills it with information -about the stack of Lisp function calls. It then enters a recursive -edit, showing the backtrace buffer in Debugger mode. - -The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit -the recursive edit; then @code{debug} switches back to the previous -buffer and returns to whatever called @code{debug}. This is the only -way the function @code{debug} can return to its caller. - -The use of the @var{debugger-args} is that @code{debug} displays the -rest of its arguments at the top of the @file{*Backtrace*} buffer, so -that the user can see them. Except as described below, this is the -@emph{only} way these arguments are used. - -However, certain values for first argument to @code{debug} have a -special significance. (Normally, these values are used only by the -internals of Emacs, and not by programmers calling @code{debug}.) Here -is a table of these special values: - -@table @code -@item lambda -@cindex @code{lambda} in debug -A first argument of @code{lambda} means @code{debug} was called -because of entry to a function when @code{debug-on-next-call} was -non-@code{nil}. The debugger displays @samp{Debugger -entered--entering a function:} as a line of text at the top of the -buffer. - -@item debug -@code{debug} as first argument means @code{debug} was called because -of entry to a function that was set to debug on entry. The debugger -displays the string @samp{Debugger entered--entering a function:}, -just as in the @code{lambda} case. It also marks the stack frame for -that function so that it will invoke the debugger when exited. - -@item t -When the first argument is @code{t}, this indicates a call to -@code{debug} due to evaluation of a function call form when -@code{debug-on-next-call} is non-@code{nil}. The debugger displays -@samp{Debugger entered--beginning evaluation of function call form:} -as the top line in the buffer. - -@item exit -When the first argument is @code{exit}, it indicates the exit of a -stack frame previously marked to invoke the debugger on exit. The -second argument given to @code{debug} in this case is the value being -returned from the frame. The debugger displays @samp{Debugger -entered--returning value:} in the top line of the buffer, followed by -the value being returned. - -@item error -@cindex @code{error} in debug -When the first argument is @code{error}, the debugger indicates that -it is being entered because an error or @code{quit} was signaled and -not handled, by displaying @samp{Debugger entered--Lisp error:} -followed by the error signaled and any arguments to @code{signal}. -For example, - -@example -@group -(let ((debug-on-error t)) - (/ 1 0)) -@end group - -@group ------- Buffer: *Backtrace* ------ -Debugger entered--Lisp error: (arith-error) - /(1 0) -... ------- Buffer: *Backtrace* ------ -@end group -@end example - -If an error was signaled, presumably the variable -@code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled, -then presumably the variable @code{debug-on-quit} is non-@code{nil}. - -@item nil -Use @code{nil} as the first of the @var{debugger-args} when you want -to enter the debugger explicitly. The rest of the @var{debugger-args} -are printed on the top line of the buffer. You can use this feature to -display messages---for example, to remind yourself of the conditions -under which @code{debug} is called. -@end table -@end deffn - -@node Internals of Debugger -@subsection Internals of the Debugger - - This section describes functions and variables used internally by the -debugger. - -@defvar debugger -The value of this variable is the function to call to invoke the -debugger. Its value must be a function of any number of arguments, or, -more typically, the name of a function. This function should invoke -some kind of debugger. The default value of the variable is -@code{debug}. - -The first argument that Lisp hands to the function indicates why it -was called. The convention for arguments is detailed in the description -of @code{debug} (@pxref{Invoking the Debugger}). -@end defvar - -@deffn Command backtrace -@cindex run time stack -@cindex call stack -This function prints a trace of Lisp function calls currently active. -This is the function used by @code{debug} to fill up the -@file{*Backtrace*} buffer. It is written in C, since it must have access -to the stack to determine which function calls are active. The return -value is always @code{nil}. - -In the following example, a Lisp expression calls @code{backtrace} -explicitly. This prints the backtrace to the stream -@code{standard-output}, which, in this case, is the buffer -@samp{backtrace-output}. - -Each line of the backtrace represents one function call. The line shows -the values of the function's arguments if they are all known; if they -are still being computed, the line says so. The arguments of special -forms are elided. - -@smallexample -@group -(with-output-to-temp-buffer "backtrace-output" - (let ((var 1)) - (save-excursion - (setq var (eval '(progn - (1+ var) - (list 'testing (backtrace)))))))) - - @result{} (testing nil) -@end group - -@group ------------ Buffer: backtrace-output ------------ - backtrace() - (list ...computing arguments...) -@end group - (progn ...) - eval((progn (1+ var) (list (quote testing) (backtrace)))) - (setq ...) - (save-excursion ...) - (let ...) - (with-output-to-temp-buffer ...) - eval((with-output-to-temp-buffer ...)) - eval-last-sexp-1(nil) -@group - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ------------ Buffer: backtrace-output ------------ -@end group -@end smallexample -@end deffn - -@defvar debug-on-next-call -@cindex @code{eval}, and debugging -@cindex @code{apply}, and debugging -@cindex @code{funcall}, and debugging -If this variable is non-@code{nil}, it says to call the debugger before -the next @code{eval}, @code{apply} or @code{funcall}. Entering the -debugger sets @code{debug-on-next-call} to @code{nil}. - -The @kbd{d} command in the debugger works by setting this variable. -@end defvar - -@defun backtrace-debug level flag -This function sets the debug-on-exit flag of the stack frame @var{level} -levels down the stack, giving it the value @var{flag}. If @var{flag} is -non-@code{nil}, this will cause the debugger to be entered when that -frame later exits. Even a nonlocal exit through that frame will enter -the debugger. - -This function is used only by the debugger. -@end defun - -@defvar command-debug-status -This variable records the debugging status of the current interactive -command. Each time a command is called interactively, this variable is -bound to @code{nil}. The debugger can set this variable to leave -information for future debugger invocations during the same command -invocation. - -The advantage of using this variable rather than an ordinary global -variable is that the data will never carry over to a subsequent command -invocation. -@end defvar - -@defun backtrace-frame frame-number -The function @code{backtrace-frame} is intended for use in Lisp -debuggers. It returns information about what computation is happening -in the stack frame @var{frame-number} levels down. - -If that frame has not evaluated the arguments yet, or is a special -form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}. - -If that frame has evaluated its arguments and called its function -already, the return value is @code{(t @var{function} -@var{arg-values}@dots{})}. - -In the return value, @var{function} is whatever was supplied as the -@sc{car} of the evaluated list, or a @code{lambda} expression in the -case of a macro call. If the function has a @code{&rest} argument, that -is represented as the tail of the list @var{arg-values}. - -If @var{frame-number} is out of range, @code{backtrace-frame} returns -@code{nil}. -@end defun - -@include edebug.texi - -@node Syntax Errors -@section Debugging Invalid Lisp Syntax -@cindex debugging invalid Lisp syntax - - The Lisp reader reports invalid syntax, but cannot say where the real -problem is. For example, the error ``End of file during parsing'' in -evaluating an expression indicates an excess of open parentheses (or -square brackets). The reader detects this imbalance at the end of the -file, but it cannot figure out where the close parenthesis should have -been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close -parenthesis or missing open parenthesis, but does not say where the -missing parenthesis belongs. How, then, to find what to change? - - If the problem is not simply an imbalance of parentheses, a useful -technique is to try @kbd{C-M-e} at the beginning of each defun, and see -if it goes to the place where that defun appears to end. If it does -not, there is a problem in that defun. - -@cindex unbalanced parentheses -@cindex parenthesis mismatch, debugging - However, unmatched parentheses are the most common syntax errors in -Lisp, and we can give further advice for those cases. (In addition, -just moving point through the code with Show Paren mode enabled might -find the mismatch.) - -@menu -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. -@end menu - -@node Excess Open -@subsection Excess Open Parentheses - - The first step is to find the defun that is unbalanced. If there is -an excess open parenthesis, the way to do this is to go to the end of -the file and type @kbd{C-u C-M-u}. This will move you to the -beginning of the first defun that is unbalanced. - - The next step is to determine precisely what is wrong. There is no -way to be sure of this except by studying the program, but often the -existing indentation is a clue to where the parentheses should have -been. The easiest way to use this clue is to reindent with @kbd{C-M-q} -and see what moves. @strong{But don't do this yet!} Keep reading, -first. - - Before you do this, make sure the defun has enough close parentheses. -Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest -of the file until the end. So move to the end of the defun and insert a -close parenthesis there. Don't use @kbd{C-M-e} to move there, since -that too will fail to work until the defun is balanced. - - Now you can go to the beginning of the defun and type @kbd{C-M-q}. -Usually all the lines from a certain point to the end of the function -will shift to the right. There is probably a missing close parenthesis, -or a superfluous open parenthesis, near that point. (However, don't -assume this is true; study the code to make sure.) Once you have found -the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old -indentation is probably appropriate to the intended parentheses. - - After you think you have fixed the problem, use @kbd{C-M-q} again. If -the old indentation actually fit the intended nesting of parentheses, -and you have put back those parentheses, @kbd{C-M-q} should not change -anything. - -@node Excess Close -@subsection Excess Close Parentheses - - To deal with an excess close parenthesis, first go to the beginning -of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first -unbalanced defun. - - Then find the actual matching close parenthesis by typing @kbd{C-M-f} -at the beginning of that defun. This will leave you somewhere short of -the place where the defun ought to end. It is possible that you will -find a spurious close parenthesis in that vicinity. - - If you don't see a problem at that point, the next thing to do is to -type @kbd{C-M-q} at the beginning of the defun. A range of lines will -probably shift left; if so, the missing open parenthesis or spurious -close parenthesis is probably near the first of those lines. (However, -don't assume this is true; study the code to make sure.) Once you have -found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the -old indentation is probably appropriate to the intended parentheses. - - After you think you have fixed the problem, use @kbd{C-M-q} again. If -the old indentation actually fits the intended nesting of parentheses, -and you have put back those parentheses, @kbd{C-M-q} should not change -anything. - -@node Test Coverage -@section Test Coverage -@cindex coverage testing - -@findex testcover-start -@findex testcover-mark-all -@findex testcover-next-mark - You can do coverage testing for a file of Lisp code by loading the -@code{testcover} library and using the command @kbd{M-x -testcover-start @key{RET} @var{file} @key{RET}} to instrument the -code. Then test your code by calling it one or more times. Then use -the command @kbd{M-x testcover-mark-all} to display colored highlights -on the code to show where coverage is insufficient. The command -@kbd{M-x testcover-next-mark} will move point forward to the next -highlighted spot. - - Normally, a red highlight indicates the form was never completely -evaluated; a brown highlight means it always evaluated to the same -value (meaning there has been little testing of what is done with the -result). However, the red highlight is skipped for forms that can't -possibly complete their evaluation, such as @code{error}. The brown -highlight is skipped for forms that are expected to always evaluate to -the same value, such as @code{(setq x 14)}. - - For difficult cases, you can add do-nothing macros to your code to -give advice to the test coverage tool. - -@defmac 1value form -Evaluate @var{form} and return its value, but inform coverage testing -that @var{form}'s value should always be the same. -@end defmac - -@defmac noreturn form -Evaluate @var{form}, informing coverage testing that @var{form} should -never return. If it ever does return, you get a run-time error. -@end defmac - - Edebug also has a coverage testing feature (@pxref{Coverage -Testing}). These features partly duplicate each other, and it would -be cleaner to combine them. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi deleted file mode 100644 index 9110d6962e4..00000000000 --- a/doc/lispref/display.texi +++ /dev/null @@ -1,6422 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/display -@node Display, System Interface, Processes, Top -@chapter Emacs Display - - This chapter describes a number of features related to the display -that Emacs presents to the user. - -@menu -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Forcing Redisplay:: Forcing redisplay. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Displaying messages at the bottom of the screen. -* Warnings:: Displaying warning messages for the user. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* Temporary Displays:: Displays that go away automatically. -* Overlays:: Use overlays to highlight parts of the buffer. -* Width:: How wide a character or string is on the screen. -* Line Height:: Controlling the height of lines. -* Faces:: A face defines a graphics style for text characters: - font, colors, etc. -* Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. -* Display Property:: Enabling special display features. -* Images:: Displaying images in Emacs buffers. -* Buttons:: Adding clickable buttons to Emacs buffers. -* Abstract Display:: Emacs's Widget for Object Collections. -* Blinking:: How Emacs shows the matching open parenthesis. -* Character Display:: How Emacs displays individual characters. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. -* Bidirectional Display:: Display of bidirectional scripts, such as - Arabic and Farsi. -@end menu - -@node Refresh Screen -@section Refreshing the Screen - - The function @code{redraw-frame} clears and redisplays the entire -contents of a given frame (@pxref{Frames}). This is useful if the -screen is corrupted. - -@defun redraw-frame frame -This function clears and redisplays frame @var{frame}. -@end defun - - Even more powerful is @code{redraw-display}: - -@deffn Command redraw-display -This function clears and redisplays all visible frames. -@end deffn - - In Emacs, processing user input takes priority over redisplay. If -you call these functions when input is available, they don't redisplay -immediately, but the requested redisplay does happen -eventually---after all the input has been processed. - - On text terminals, suspending and resuming Emacs normally also -refreshes the screen. Some terminal emulators record separate -contents for display-oriented programs such as Emacs and for ordinary -sequential display. If you are using such a terminal, you might want -to inhibit the redisplay on resumption. - -@defopt no-redraw-on-reenter -@cindex suspend (cf. @code{no-redraw-on-reenter}) -@cindex resume (cf. @code{no-redraw-on-reenter}) -This variable controls whether Emacs redraws the entire screen after it -has been suspended and resumed. Non-@code{nil} means there is no need -to redraw, @code{nil} means redrawing is needed. The default is @code{nil}. -@end defopt - -@node Forcing Redisplay -@section Forcing Redisplay -@cindex forcing redisplay - - Emacs normally tries to redisplay the screen whenever it waits for -input. With the following function, you can request an immediate -attempt to redisplay, in the middle of Lisp code, without actually -waiting for input. - -@defun redisplay &optional force -This function tries immediately to redisplay. The optional argument -@var{force}, if non-@code{nil}, forces the redisplay to be performed, -instead of being preempted, even if input is pending and the variable -@code{redisplay-dont-pause} is @code{nil} (see below). If -@code{redisplay-dont-pause} is non-@code{nil} (the default), this -function redisplays in any case, i.e.@: @var{force} does nothing. - -The function returns @code{t} if it actually tried to redisplay, and -@code{nil} otherwise. A value of @code{t} does not mean that -redisplay proceeded to completion; it could have been preempted by -newly arriving input. -@end defun - -@defvar redisplay-dont-pause -If this variable is @code{nil}, arriving input events preempt -redisplay; Emacs avoids starting a redisplay, and stops any redisplay -that is in progress, until the input has been processed. In -particular, @code{(redisplay)} returns @code{nil} without actually -redisplaying, if there is pending input. - -The default value is @code{t}, which means that pending input does not -preempt redisplay. -@end defvar - -@defvar redisplay-preemption-period -If @code{redisplay-dont-pause} is @code{nil}, this variable specifies -how many seconds Emacs waits between checks for new input during -redisplay; if input arrives during this interval, redisplay stops and -the input is processed. The default value is 0.1; if the value is -@code{nil}, Emacs does not check for input during redisplay. - -This variable has no effect when @code{redisplay-dont-pause} is -non-@code{nil} (the default). -@end defvar - - Although @code{redisplay} tries immediately to redisplay, it does -not change how Emacs decides which parts of its frame(s) to redisplay. -By contrast, the following function adds certain windows to the -pending redisplay work (as if their contents had completely changed), -but does not immediately try to perform redisplay. - -@defun force-window-update &optional object -This function forces some or all windows to be updated the next time -Emacs does a redisplay. If @var{object} is a window, that window is -to be updated. If @var{object} is a buffer or buffer name, all -windows displaying that buffer are to be updated. If @var{object} is -@code{nil} (or omitted), all windows are to be updated. - -This function does not do a redisplay immediately; Emacs does that as -it waits for input, or when the function @code{redisplay} is called. -@end defun - -@node Truncation -@section Truncation -@cindex line wrapping -@cindex line truncation -@cindex continuation lines -@cindex @samp{$} in display -@cindex @samp{\} in display - - When a line of text extends beyond the right edge of a window, Emacs -can @dfn{continue} the line (make it ``wrap'' to the next screen -line), or @dfn{truncate} the line (limit it to one screen line). The -additional screen lines used to display a long text line are called -@dfn{continuation} lines. Continuation is not the same as filling; -continuation happens on the screen only, not in the buffer contents, -and it breaks a line precisely at the right margin, not at a word -boundary. @xref{Filling}. - - On a graphical display, tiny arrow images in the window fringes -indicate truncated and continued lines (@pxref{Fringes}). On a text -terminal, a @samp{$} in the rightmost column of the window indicates -truncation; a @samp{\} on the rightmost column indicates a line that -``wraps''. (The display table can specify alternate characters to use -for this; @pxref{Display Tables}). - -@defopt truncate-lines -If this buffer-local variable is non-@code{nil}, lines that extend -beyond the right edge of the window are truncated; otherwise, they are -continued. As a special exception, the variable -@code{truncate-partial-width-windows} takes precedence in -@dfn{partial-width} windows (i.e.@: windows that do not occupy the -entire frame width). -@end defopt - -@defopt truncate-partial-width-windows -This variable controls line truncation in @dfn{partial-width} windows. -A partial-width window is one that does not occupy the entire frame -width (@pxref{Splitting Windows}). If the value is @code{nil}, line -truncation is determined by the variable @code{truncate-lines} (see -above). If the value is an integer @var{n}, lines are truncated if -the partial-width window has fewer than @var{n} columns, regardless of -the value of @code{truncate-lines}; if the partial-width window has -@var{n} or more columns, line truncation is determined by -@code{truncate-lines}. For any other non-@code{nil} value, lines are -truncated in every partial-width window, regardless of the value of -@code{truncate-lines}. -@end defopt - - When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in -a window, that forces truncation. - -@defvar wrap-prefix -If this buffer-local variable is non-@code{nil}, it defines a -@dfn{wrap prefix} which Emacs displays at the start of every -continuation line. (If lines are truncated, @code{wrap-prefix} is -never used.) Its value may be a string or an image (@pxref{Other -Display Specs}), or a stretch of whitespace such as specified by the -@code{:width} or @code{:align-to} display properties (@pxref{Specified -Space}). The value is interpreted in the same way as a @code{display} -text property. @xref{Display Property}. - -A wrap prefix may also be specified for regions of text, using the -@code{wrap-prefix} text or overlay property. This takes precedence -over the @code{wrap-prefix} variable. @xref{Special Properties}. -@end defvar - -@defvar line-prefix -If this buffer-local variable is non-@code{nil}, it defines a -@dfn{line prefix} which Emacs displays at the start of every -non-continuation line. Its value may be a string or an image -(@pxref{Other Display Specs}), or a stretch of whitespace such as -specified by the @code{:width} or @code{:align-to} display properties -(@pxref{Specified Space}). The value is interpreted in the same way -as a @code{display} text property. @xref{Display Property}. - -A line prefix may also be specified for regions of text using the -@code{line-prefix} text or overlay property. This takes precedence -over the @code{line-prefix} variable. @xref{Special Properties}. -@end defvar - - If your buffer contains @emph{very} long lines, and you use -continuation to display them, computing the continuation lines can -make redisplay slow. The column computation and indentation functions -also become slow. Then you might find it advisable to set -@code{cache-long-line-scans} to @code{t}. - -@defvar cache-long-line-scans -If this variable is non-@code{nil}, various indentation and motion -functions, and Emacs redisplay, cache the results of scanning the -buffer, and consult the cache to avoid rescanning regions of the buffer -unless they are modified. - -Turning on the cache slows down processing of short lines somewhat. - -This variable is automatically buffer-local in every buffer. -@end defvar - -@node The Echo Area -@section The Echo Area -@cindex error display -@cindex echo area - - The @dfn{echo area} is used for displaying error messages -(@pxref{Errors}), for messages made with the @code{message} primitive, -and for echoing keystrokes. It is not the same as the minibuffer, -despite the fact that the minibuffer appears (when active) in the same -place on the screen as the echo area. @xref{Minibuffer,, The -Minibuffer, emacs, The GNU Emacs Manual}. - - Apart from the functions documented in this section, you can print -Lisp objects to the echo area by specifying @code{t} as the output -stream. @xref{Output Streams}. - -@menu -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. -@end menu - -@node Displaying Messages -@subsection Displaying Messages in the Echo Area -@cindex display message in echo area - - This section describes the standard functions for displaying -messages in the echo area. - -@defun message format-string &rest arguments -This function displays a message in the echo area. -@var{format-string} is a format string, and @var{arguments} are the -objects for its format specifications, like in the @code{format} -function (@pxref{Formatting Strings}). The resulting formatted string -is displayed in the echo area; if it contains @code{face} text -properties, it is displayed with the specified faces (@pxref{Faces}). -The string is also added to the @file{*Messages*} buffer, but without -text properties (@pxref{Logging Messages}). - -In batch mode, the message is printed to the standard error stream, -followed by a newline. - -If @var{format-string} is @code{nil} or the empty string, -@code{message} clears the echo area; if the echo area has been -expanded automatically, this brings it back to its normal size. If -the minibuffer is active, this brings the minibuffer contents back -onto the screen immediately. - -@example -@group -(message "Minibuffer depth is %d." - (minibuffer-depth)) - @print{} Minibuffer depth is 0. -@result{} "Minibuffer depth is 0." -@end group - -@group ----------- Echo Area ---------- -Minibuffer depth is 0. ----------- Echo Area ---------- -@end group -@end example - -To automatically display a message in the echo area or in a pop-buffer, -depending on its size, use @code{display-message-or-buffer} (see below). -@end defun - -@defmac with-temp-message message &rest body -This construct displays a message in the echo area temporarily, during -the execution of @var{body}. It displays @var{message}, executes -@var{body}, then returns the value of the last body form while restoring -the previous echo area contents. -@end defmac - -@defun message-or-box format-string &rest arguments -This function displays a message like @code{message}, but may display it -in a dialog box instead of the echo area. If this function is called in -a command that was invoked using the mouse---more precisely, if -@code{last-nonmenu-event} (@pxref{Command Loop Info}) is either -@code{nil} or a list---then it uses a dialog box or pop-up menu to -display the message. Otherwise, it uses the echo area. (This is the -same criterion that @code{y-or-n-p} uses to make a similar decision; see -@ref{Yes-or-No Queries}.) - -You can force use of the mouse or of the echo area by binding -@code{last-nonmenu-event} to a suitable value around the call. -@end defun - -@defun message-box format-string &rest arguments -@anchor{message-box} -This function displays a message like @code{message}, but uses a dialog -box (or a pop-up menu) whenever that is possible. If it is impossible -to use a dialog box or pop-up menu, because the terminal does not -support them, then @code{message-box} uses the echo area, like -@code{message}. -@end defun - -@defun display-message-or-buffer message &optional buffer-name not-this-window frame -This function displays the message @var{message}, which may be either a -string or a buffer. If it is shorter than the maximum height of the -echo area, as defined by @code{max-mini-window-height}, it is displayed -in the echo area, using @code{message}. Otherwise, -@code{display-buffer} is used to show it in a pop-up buffer. - -Returns either the string shown in the echo area, or when a pop-up -buffer is used, the window used to display it. - -If @var{message} is a string, then the optional argument -@var{buffer-name} is the name of the buffer used to display it when a -pop-up buffer is used, defaulting to @file{*Message*}. In the case -where @var{message} is a string and displayed in the echo area, it is -not specified whether the contents are inserted into the buffer anyway. - -The optional arguments @var{not-this-window} and @var{frame} are as for -@code{display-buffer}, and only used if a buffer is displayed. -@end defun - -@defun current-message -This function returns the message currently being displayed in the -echo area, or @code{nil} if there is none. -@end defun - -@node Progress -@subsection Reporting Operation Progress -@cindex progress reporting - - When an operation can take a while to finish, you should inform the -user about the progress it makes. This way the user can estimate -remaining time and clearly see that Emacs is busy working, not hung. -A convenient way to do this is to use a @dfn{progress reporter}. - - Here is a working example that does nothing useful: - -@smallexample -(let ((progress-reporter - (make-progress-reporter "Collecting mana for Emacs..." - 0 500))) - (dotimes (k 500) - (sit-for 0.01) - (progress-reporter-update progress-reporter k)) - (progress-reporter-done progress-reporter)) -@end smallexample - -@defun make-progress-reporter message &optional min-value max-value current-value min-change min-time -This function creates and returns a progress reporter object, which -you will use as an argument for the other functions listed below. The -idea is to precompute as much data as possible to make progress -reporting very fast. - -When this progress reporter is subsequently used, it will display -@var{message} in the echo area, followed by progress percentage. -@var{message} is treated as a simple string. If you need it to depend -on a filename, for instance, use @code{format} before calling this -function. - -The arguments @var{min-value} and @var{max-value} should be numbers -standing for the starting and final states of the operation. For -instance, an operation that ``scans'' a buffer should set these to the -results of @code{point-min} and @code{point-max} correspondingly. -@var{max-value} should be greater than @var{min-value}. - -Alternatively, you can set @var{min-value} and @var{max-value} to -@code{nil}. In that case, the progress reporter does not report -process percentages; it instead displays a ``spinner'' that rotates a -notch each time you update the progress reporter. - -If @var{min-value} and @var{max-value} are numbers, you can give the -argument @var{current-value} a numerical value specifying the initial -progress; if omitted, this defaults to @var{min-value}. - -The remaining arguments control the rate of echo area updates. The -progress reporter will wait for at least @var{min-change} more -percents of the operation to be completed before printing next -message; the default is one percent. @var{min-time} specifies the -minimum time in seconds to pass between successive prints; the default -is 0.2 seconds. (On some operating systems, the progress reporter may -handle fractions of seconds with varying precision). - -This function calls @code{progress-reporter-update}, so the first -message is printed immediately. -@end defun - -@defun progress-reporter-update reporter &optional value -This function does the main work of reporting progress of your -operation. It displays the message of @var{reporter}, followed by -progress percentage determined by @var{value}. If percentage is zero, -or close enough according to the @var{min-change} and @var{min-time} -arguments, then it is omitted from the output. - -@var{reporter} must be the result of a call to -@code{make-progress-reporter}. @var{value} specifies the current -state of your operation and must be between @var{min-value} and -@var{max-value} (inclusive) as passed to -@code{make-progress-reporter}. For instance, if you scan a buffer, -then @var{value} should be the result of a call to @code{point}. - -This function respects @var{min-change} and @var{min-time} as passed -to @code{make-progress-reporter} and so does not output new messages -on every invocation. It is thus very fast and normally you should not -try to reduce the number of calls to it: resulting overhead will most -likely negate your effort. -@end defun - -@defun progress-reporter-force-update reporter &optional value new-message -This function is similar to @code{progress-reporter-update} except -that it prints a message in the echo area unconditionally. - -The first two arguments have the same meaning as for -@code{progress-reporter-update}. Optional @var{new-message} allows -you to change the message of the @var{reporter}. Since this functions -always updates the echo area, such a change will be immediately -presented to the user. -@end defun - -@defun progress-reporter-done reporter -This function should be called when the operation is finished. It -prints the message of @var{reporter} followed by word ``done'' in the -echo area. - -You should always call this function and not hope for -@code{progress-reporter-update} to print ``100%''. Firstly, it may -never print it, there are many good reasons for this not to happen. -Secondly, ``done'' is more explicit. -@end defun - -@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{} -This is a convenience macro that works the same way as @code{dotimes} -does, but also reports loop progress using the functions described -above. It allows you to save some typing. - -You can rewrite the example in the beginning of this node using -this macro this way: - -@example -(dotimes-with-progress-reporter - (k 500) - "Collecting some mana for Emacs..." - (sit-for 0.01)) -@end example -@end defmac - -@node Logging Messages -@subsection Logging Messages in @file{*Messages*} -@cindex logging echo-area messages - - Almost all the messages displayed in the echo area are also recorded -in the @file{*Messages*} buffer so that the user can refer back to -them. This includes all the messages that are output with -@code{message}. - -@defopt message-log-max -This variable specifies how many lines to keep in the @file{*Messages*} -buffer. The value @code{t} means there is no limit on how many lines to -keep. The value @code{nil} disables message logging entirely. Here's -how to display a message and prevent it from being logged: - -@example -(let (message-log-max) - (message @dots{})) -@end example -@end defopt - - To make @file{*Messages*} more convenient for the user, the logging -facility combines successive identical messages. It also combines -successive related messages for the sake of two cases: question -followed by answer, and a series of progress messages. - - A ``question followed by an answer'' means two messages like the -ones produced by @code{y-or-n-p}: the first is @samp{@var{question}}, -and the second is @samp{@var{question}...@var{answer}}. The first -message conveys no additional information beyond what's in the second, -so logging the second message discards the first from the log. - - A ``series of progress messages'' means successive messages like -those produced by @code{make-progress-reporter}. They have the form -@samp{@var{base}...@var{how-far}}, where @var{base} is the same each -time, while @var{how-far} varies. Logging each message in the series -discards the previous one, provided they are consecutive. - - The functions @code{make-progress-reporter} and @code{y-or-n-p} -don't have to do anything special to activate the message log -combination feature. It operates whenever two consecutive messages -are logged that share a common prefix ending in @samp{...}. - -@node Echo Area Customization -@subsection Echo Area Customization - - These variables control details of how the echo area works. - -@defvar cursor-in-echo-area -This variable controls where the cursor appears when a message is -displayed in the echo area. If it is non-@code{nil}, then the cursor -appears at the end of the message. Otherwise, the cursor appears at -point---not in the echo area at all. - -The value is normally @code{nil}; Lisp programs bind it to @code{t} -for brief periods of time. -@end defvar - -@defvar echo-area-clear-hook -This normal hook is run whenever the echo area is cleared---either by -@code{(message nil)} or for any other reason. -@end defvar - -@defopt echo-keystrokes -This variable determines how much time should elapse before command -characters echo. Its value must be an integer or floating point number, -which specifies the -number of seconds to wait before echoing. If the user types a prefix -key (such as @kbd{C-x}) and then delays this many seconds before -continuing, the prefix key is echoed in the echo area. (Once echoing -begins in a key sequence, all subsequent characters in the same key -sequence are echoed immediately.) - -If the value is zero, then command input is not echoed. -@end defopt - -@defvar message-truncate-lines -Normally, displaying a long message resizes the echo area to display -the entire message. But if the variable @code{message-truncate-lines} -is non-@code{nil}, the echo area does not resize, and the message is -truncated to fit it. -@end defvar - - The variable @code{max-mini-window-height}, which specifies the -maximum height for resizing minibuffer windows, also applies to the -echo area (which is really a special use of the minibuffer window; -@pxref{Minibuffer Misc}). - -@node Warnings -@section Reporting Warnings -@cindex warnings - - @dfn{Warnings} are a facility for a program to inform the user of a -possible problem, but continue running. - -@menu -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize their warnings. -* Warning Options:: Variables users set to control display of warnings. -* Delayed Warnings:: Deferring a warning until the end of a command. -@end menu - -@node Warning Basics -@subsection Warning Basics -@cindex severity level - - Every warning has a textual message, which explains the problem for -the user, and a @dfn{severity level} which is a symbol. Here are the -possible severity levels, in order of decreasing severity, and their -meanings: - -@table @code -@item :emergency -A problem that will seriously impair Emacs operation soon -if you do not attend to it promptly. -@item :error -A report of data or circumstances that are inherently wrong. -@item :warning -A report of data or circumstances that are not inherently wrong, but -raise suspicion of a possible problem. -@item :debug -A report of information that may be useful if you are debugging. -@end table - - When your program encounters invalid input data, it can either -signal a Lisp error by calling @code{error} or @code{signal} or report -a warning with severity @code{:error}. Signaling a Lisp error is the -easiest thing to do, but it means the program cannot continue -processing. If you want to take the trouble to implement a way to -continue processing despite the bad data, then reporting a warning of -severity @code{:error} is the right way to inform the user of the -problem. For instance, the Emacs Lisp byte compiler can report an -error that way and continue compiling other functions. (If the -program signals a Lisp error and then handles it with -@code{condition-case}, the user won't see the error message; it could -show the message to the user by reporting it as a warning.) - -@cindex warning type - Each warning has a @dfn{warning type} to classify it. The type is a -list of symbols. The first symbol should be the custom group that you -use for the program's user options. For example, byte compiler -warnings use the warning type @code{(bytecomp)}. You can also -subcategorize the warnings, if you wish, by using more symbols in the -list. - -@defun display-warning type message &optional level buffer-name -This function reports a warning, using @var{message} as the message -and @var{type} as the warning type. @var{level} should be the -severity level, with @code{:warning} being the default. - -@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer -for logging the warning. By default, it is @file{*Warnings*}. -@end defun - -@defun lwarn type level message &rest args -This function reports a warning using the value of @code{(format -@var{message} @var{args}...)} as the message. In other respects it is -equivalent to @code{display-warning}. -@end defun - -@defun warn message &rest args -This function reports a warning using the value of @code{(format -@var{message} @var{args}...)} as the message, @code{(emacs)} as the -type, and @code{:warning} as the severity level. It exists for -compatibility only; we recommend not using it, because you should -specify a specific warning type. -@end defun - -@node Warning Variables -@subsection Warning Variables - - Programs can customize how their warnings appear by binding -the variables described in this section. - -@defvar warning-levels -This list defines the meaning and severity order of the warning -severity levels. Each element defines one severity level, -and they are arranged in order of decreasing severity. - -Each element has the form @code{(@var{level} @var{string} -@var{function})}, where @var{level} is the severity level it defines. -@var{string} specifies the textual description of this level. -@var{string} should use @samp{%s} to specify where to put the warning -type information, or it can omit the @samp{%s} so as not to include -that information. - -The optional @var{function}, if non-@code{nil}, is a function to call -with no arguments, to get the user's attention. - -Normally you should not change the value of this variable. -@end defvar - -@defvar warning-prefix-function -If non-@code{nil}, the value is a function to generate prefix text for -warnings. Programs can bind the variable to a suitable function. -@code{display-warning} calls this function with the warnings buffer -current, and the function can insert text in it. That text becomes -the beginning of the warning message. - -The function is called with two arguments, the severity level and its -entry in @code{warning-levels}. It should return a list to use as the -entry (this value need not be an actual member of -@code{warning-levels}). By constructing this value, the function can -change the severity of the warning, or specify different handling for -a given severity level. - -If the variable's value is @code{nil} then there is no function -to call. -@end defvar - -@defvar warning-series -Programs can bind this variable to @code{t} to say that the next -warning should begin a series. When several warnings form a series, -that means to leave point on the first warning of the series, rather -than keep moving it for each warning so that it appears on the last one. -The series ends when the local binding is unbound and -@code{warning-series} becomes @code{nil} again. - -The value can also be a symbol with a function definition. That is -equivalent to @code{t}, except that the next warning will also call -the function with no arguments with the warnings buffer current. The -function can insert text which will serve as a header for the series -of warnings. - -Once a series has begun, the value is a marker which points to the -buffer position in the warnings buffer of the start of the series. - -The variable's normal value is @code{nil}, which means to handle -each warning separately. -@end defvar - -@defvar warning-fill-prefix -When this variable is non-@code{nil}, it specifies a fill prefix to -use for filling each warning's text. -@end defvar - -@defvar warning-type-format -This variable specifies the format for displaying the warning type -in the warning message. The result of formatting the type this way -gets included in the message under the control of the string in the -entry in @code{warning-levels}. The default value is @code{" (%s)"}. -If you bind it to @code{""} then the warning type won't appear at -all. -@end defvar - -@node Warning Options -@subsection Warning Options - - These variables are used by users to control what happens -when a Lisp program reports a warning. - -@defopt warning-minimum-level -This user option specifies the minimum severity level that should be -shown immediately to the user. The default is @code{:warning}, which -means to immediately display all warnings except @code{:debug} -warnings. -@end defopt - -@defopt warning-minimum-log-level -This user option specifies the minimum severity level that should be -logged in the warnings buffer. The default is @code{:warning}, which -means to log all warnings except @code{:debug} warnings. -@end defopt - -@defopt warning-suppress-types -This list specifies which warning types should not be displayed -immediately for the user. Each element of the list should be a list -of symbols. If its elements match the first elements in a warning -type, then that warning is not displayed immediately. -@end defopt - -@defopt warning-suppress-log-types -This list specifies which warning types should not be logged in the -warnings buffer. Each element of the list should be a list of -symbols. If it matches the first few elements in a warning type, then -that warning is not logged. -@end defopt - -@node Delayed Warnings -@subsection Delayed Warnings - -Sometimes, you may wish to avoid showing a warning while a command is -running, and only show it only after the end of the command. You can -use the variable @code{delayed-warnings-list} for this. - -@defvar delayed-warnings-list -The value of this variable is a list of warnings to be displayed after -the current command has finished. Each element must be a list - -@smallexample -(@var{type} @var{message} [@var{level} [@var{buffer-name}]]) -@end smallexample - -@noindent -with the same form, and the same meanings, as the argument list of -@code{display-warning} (@pxref{Warning Basics}). Immediately after -running @code{post-command-hook} (@pxref{Command Overview}), the Emacs -command loop displays all the warnings specified by this variable, -then resets it to @code{nil}. -@end defvar - - Programs which need to further customize the delayed warnings -mechanism can change the variable @code{delayed-warnings-hook}: - -@defvar delayed-warnings-hook -This is a normal hook which is run by the Emacs command loop, after -@code{post-command-hook}, in order to to process and display delayed -warnings. - -Its default value is a list of two functions: - -@smallexample -(collapse-delayed-warnings display-delayed-warnings) -@end smallexample - -@findex collapse-delayed-warnings -@findex display-delayed-warnings -@noindent -The function @code{collapse-delayed-warnings} iterates through -@code{delayed-warnings-list}, removing repeated entries. The function -@code{display-delayed-warnings} calls @code{display-warning} on each -of the entries in @code{delayed-warnings-list}, in turn, and then sets -@code{delayed-warnings-list} to @code{nil}. -@end defvar - -@node Invisible Text -@section Invisible Text - -@cindex invisible text -You can make characters @dfn{invisible}, so that they do not appear on -the screen, with the @code{invisible} property. This can be either a -text property (@pxref{Text Properties}) or an overlay property -(@pxref{Overlays}). Cursor motion also partly ignores these -characters; if the command loop finds that point is inside a range of -invisible text after a command, it relocates point to the other side -of the text. - -In the simplest case, any non-@code{nil} @code{invisible} property makes -a character invisible. This is the default case---if you don't alter -the default value of @code{buffer-invisibility-spec}, this is how the -@code{invisible} property works. You should normally use @code{t} -as the value of the @code{invisible} property if you don't plan -to set @code{buffer-invisibility-spec} yourself. - -More generally, you can use the variable @code{buffer-invisibility-spec} -to control which values of the @code{invisible} property make text -invisible. This permits you to classify the text into different subsets -in advance, by giving them different @code{invisible} values, and -subsequently make various subsets visible or invisible by changing the -value of @code{buffer-invisibility-spec}. - -Controlling visibility with @code{buffer-invisibility-spec} is -especially useful in a program to display the list of entries in a -database. It permits the implementation of convenient filtering -commands to view just a part of the entries in the database. Setting -this variable is very fast, much faster than scanning all the text in -the buffer looking for properties to change. - -@defvar buffer-invisibility-spec -This variable specifies which kinds of @code{invisible} properties -actually make a character invisible. Setting this variable makes it -buffer-local. - -@table @asis -@item @code{t} -A character is invisible if its @code{invisible} property is -non-@code{nil}. This is the default. - -@item a list -Each element of the list specifies a criterion for invisibility; if a -character's @code{invisible} property fits any one of these criteria, -the character is invisible. The list can have two kinds of elements: - -@table @code -@item @var{atom} -A character is invisible if its @code{invisible} property value is -@var{atom} or if it is a list with @var{atom} as a member; comparison -is done with @code{eq}. - -@item (@var{atom} . t) -A character is invisible if its @code{invisible} property value is -@var{atom} or if it is a list with @var{atom} as a member; comparison -is done with @code{eq}. Moreover, a sequence of such characters -displays as an ellipsis. -@end table -@end table -@end defvar - - Two functions are specifically provided for adding elements to -@code{buffer-invisibility-spec} and removing elements from it. - -@defun add-to-invisibility-spec element -This function adds the element @var{element} to -@code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec} -was @code{t}, it changes to a list, @code{(t)}, so that text whose -@code{invisible} property is @code{t} remains invisible. -@end defun - -@defun remove-from-invisibility-spec element -This removes the element @var{element} from -@code{buffer-invisibility-spec}. This does nothing if @var{element} -is not in the list. -@end defun - - A convention for use of @code{buffer-invisibility-spec} is that a -major mode should use the mode's own name as an element of -@code{buffer-invisibility-spec} and as the value of the -@code{invisible} property: - -@example -;; @r{If you want to display an ellipsis:} -(add-to-invisibility-spec '(my-symbol . t)) -;; @r{If you don't want ellipsis:} -(add-to-invisibility-spec 'my-symbol) - -(overlay-put (make-overlay beginning end) - 'invisible 'my-symbol) - -;; @r{When done with the invisibility:} -(remove-from-invisibility-spec '(my-symbol . t)) -;; @r{Or respectively:} -(remove-from-invisibility-spec 'my-symbol) -@end example - - You can check for invisibility using the following function: - -@defun invisible-p pos-or-prop -If @var{pos-or-prop} is a marker or number, this function returns a -non-@code{nil} value if the text at that position is invisible. - -If @var{pos-or-prop} is any other kind of Lisp object, that is taken -to mean a possible value of the @code{invisible} text or overlay -property. In that case, this function returns a non-@code{nil} value -if that value would cause text to become invisible, based on the -current value of @code{buffer-invisibility-spec}. -@end defun - -@vindex line-move-ignore-invisible - Ordinarily, functions that operate on text or move point do not care -whether the text is invisible. The user-level line motion commands -ignore invisible newlines if @code{line-move-ignore-invisible} is -non-@code{nil} (the default), but only because they are explicitly -programmed to do so. - - However, if a command ends with point inside or at the boundary of -invisible text, the main editing loop relocates point to one of the -two ends of the invisible text. Emacs chooses the direction of -relocation so that it is the same as the overall movement direction of -the command; if in doubt, it prefers a position where an inserted char -would not inherit the @code{invisible} property. Additionally, if the -text is not replaced by an ellipsis and the command only moved within -the invisible text, then point is moved one extra character so as to -try and reflect the command's movement by a visible movement of the -cursor. - - Thus, if the command moved point back to an invisible range (with the usual -stickiness), Emacs moves point back to the beginning of that range. If the -command moved point forward into an invisible range, Emacs moves point forward -to the first visible character that follows the invisible text and then forward -one more character. - - Incremental search can make invisible overlays visible temporarily -and/or permanently when a match includes invisible text. To enable -this, the overlay should have a non-@code{nil} -@code{isearch-open-invisible} property. The property value should be a -function to be called with the overlay as an argument. This function -should make the overlay visible permanently; it is used when the match -overlaps the overlay on exit from the search. - - During the search, such overlays are made temporarily visible by -temporarily modifying their invisible and intangible properties. If you -want this to be done differently for a certain overlay, give it an -@code{isearch-open-invisible-temporary} property which is a function. -The function is called with two arguments: the first is the overlay, and -the second is @code{nil} to make the overlay visible, or @code{t} to -make it invisible again. - -@node Selective Display -@section Selective Display -@c @cindex selective display Duplicates selective-display - - @dfn{Selective display} refers to a pair of related features for -hiding certain lines on the screen. - - The first variant, explicit selective display, is designed for use -in a Lisp program: it controls which lines are hidden by altering the -text. This kind of hiding in some ways resembles the effect of the -@code{invisible} property (@pxref{Invisible Text}), but the two -features are different and do not work the same way. - - In the second variant, the choice of lines to hide is made -automatically based on indentation. This variant is designed to be a -user-level feature. - - The way you control explicit selective display is by replacing a -newline (control-j) with a carriage return (control-m). The text that -was formerly a line following that newline is now hidden. Strictly -speaking, it is temporarily no longer a line at all, since only -newlines can separate lines; it is now part of the previous line. - - Selective display does not directly affect editing commands. For -example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly -into hidden text. However, the replacement of newline characters with -carriage return characters affects some editing commands. For -example, @code{next-line} skips hidden lines, since it searches only -for newlines. Modes that use selective display can also define -commands that take account of the newlines, or that control which -parts of the text are hidden. - - When you write a selectively displayed buffer into a file, all the -control-m's are output as newlines. This means that when you next read -in the file, it looks OK, with nothing hidden. The selective display -effect is seen only within Emacs. - -@defvar selective-display -This buffer-local variable enables selective display. This means that -lines, or portions of lines, may be made hidden. - -@itemize @bullet -@item -If the value of @code{selective-display} is @code{t}, then the character -control-m marks the start of hidden text; the control-m, and the rest -of the line following it, are not displayed. This is explicit selective -display. - -@item -If the value of @code{selective-display} is a positive integer, then -lines that start with more than that many columns of indentation are not -displayed. -@end itemize - -When some portion of a buffer is hidden, the vertical movement -commands operate as if that portion did not exist, allowing a single -@code{next-line} command to skip any number of hidden lines. -However, character movement commands (such as @code{forward-char}) do -not skip the hidden portion, and it is possible (if tricky) to insert -or delete text in an hidden portion. - -In the examples below, we show the @emph{display appearance} of the -buffer @code{foo}, which changes with the value of -@code{selective-display}. The @emph{contents} of the buffer do not -change. - -@example -@group -(setq selective-display nil) - @result{} nil - ----------- Buffer: foo ---------- -1 on this column - 2on this column - 3n this column - 3n this column - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group - -@group -(setq selective-display 2) - @result{} 2 - ----------- Buffer: foo ---------- -1 on this column - 2on this column - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group -@end example -@end defvar - -@defopt selective-display-ellipses -If this buffer-local variable is non-@code{nil}, then Emacs displays -@samp{@dots{}} at the end of a line that is followed by hidden text. -This example is a continuation of the previous one. - -@example -@group -(setq selective-display-ellipses t) - @result{} t - ----------- Buffer: foo ---------- -1 on this column - 2on this column ... - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group -@end example - -You can use a display table to substitute other text for the ellipsis -(@samp{@dots{}}). @xref{Display Tables}. -@end defopt - -@node Temporary Displays -@section Temporary Displays - - Temporary displays are used by Lisp programs to put output into a -buffer and then present it to the user for perusal rather than for -editing. Many help commands use this feature. - -@defmac with-output-to-temp-buffer buffer-name forms@dots{} -This function executes @var{forms} while arranging to insert any output -they print into the buffer named @var{buffer-name}, which is first -created if necessary, and put into Help mode. Finally, the buffer is -displayed in some window, but not selected. - -If the @var{forms} do not change the major mode in the output buffer, -so that it is still Help mode at the end of their execution, then -@code{with-output-to-temp-buffer} makes this buffer read-only at the -end, and also scans it for function and variable names to make them -into clickable cross-references. @xref{Docstring hyperlinks, , Tips -for Documentation Strings}, in particular the item on hyperlinks in -documentation strings, for more details. - -The string @var{buffer-name} specifies the temporary buffer, which -need not already exist. The argument must be a string, not a buffer. -The buffer is erased initially (with no questions asked), and it is -marked as unmodified after @code{with-output-to-temp-buffer} exits. - -@code{with-output-to-temp-buffer} binds @code{standard-output} to the -temporary buffer, then it evaluates the forms in @var{forms}. Output -using the Lisp output functions within @var{forms} goes by default to -that buffer (but screen display and messages in the echo area, although -they are ``output'' in the general sense of the word, are not affected). -@xref{Output Functions}. - -Several hooks are available for customizing the behavior -of this construct; they are listed below. - -The value of the last form in @var{forms} is returned. - -@example -@group ----------- Buffer: foo ---------- - This is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(with-output-to-temp-buffer "foo" - (print 20) - (print standard-output)) -@result{} # - ----------- Buffer: foo ---------- -20 - -# - ----------- Buffer: foo ---------- -@end group -@end example -@end defmac - -@defopt temp-buffer-show-function -If this variable is non-@code{nil}, @code{with-output-to-temp-buffer} -calls it as a function to do the job of displaying a help buffer. The -function gets one argument, which is the buffer it should display. - -It is a good idea for this function to run @code{temp-buffer-show-hook} -just as @code{with-output-to-temp-buffer} normally would, inside of -@code{save-selected-window} and with the chosen window and buffer -selected. -@end defopt - -@defvar temp-buffer-setup-hook -This normal hook is run by @code{with-output-to-temp-buffer} before -evaluating @var{body}. When the hook runs, the temporary buffer is -current. This hook is normally set up with a function to put the -buffer in Help mode. -@end defvar - -@defvar temp-buffer-show-hook -This normal hook is run by @code{with-output-to-temp-buffer} after -displaying the temporary buffer. When the hook runs, the temporary buffer -is current, and the window it was displayed in is selected. -@end defvar - -@defun momentary-string-display string position &optional char message -This function momentarily displays @var{string} in the current buffer at -@var{position}. It has no effect on the undo list or on the buffer's -modification status. - -The momentary display remains until the next input event. If the next -input event is @var{char}, @code{momentary-string-display} ignores it -and returns. Otherwise, that event remains buffered for subsequent use -as input. Thus, typing @var{char} will simply remove the string from -the display, while typing (say) @kbd{C-f} will remove the string from -the display and later (presumably) move point forward. The argument -@var{char} is a space by default. - -The return value of @code{momentary-string-display} is not meaningful. - -If the string @var{string} does not contain control characters, you can -do the same job in a more general way by creating (and then subsequently -deleting) an overlay with a @code{before-string} property. -@xref{Overlay Properties}. - -If @var{message} is non-@code{nil}, it is displayed in the echo area -while @var{string} is displayed in the buffer. If it is @code{nil}, a -default message says to type @var{char} to continue. - -In this example, point is initially located at the beginning of the -second line: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of foo. -@point{}Second line. ----------- Buffer: foo ---------- -@end group - -@group -(momentary-string-display - "**** Important Message! ****" - (point) ?\r - "Type RET when done reading") -@result{} t -@end group - -@group ----------- Buffer: foo ---------- -This is the contents of foo. -**** Important Message! ****Second line. ----------- Buffer: foo ---------- - ----------- Echo Area ---------- -Type RET when done reading ----------- Echo Area ---------- -@end group -@end example -@end defun - -@node Overlays -@section Overlays -@cindex overlays - -You can use @dfn{overlays} to alter the appearance of a buffer's text on -the screen, for the sake of presentation features. An overlay is an -object that belongs to a particular buffer, and has a specified -beginning and end. It also has properties that you can examine and set; -these affect the display of the text within the overlay. - -@cindex scalability of overlays -The visual effect of an overlay is the same as of the corresponding -text property (@pxref{Text Properties}). However, due to a different -implementation, overlays generally don't scale well (many operations -take a time that is proportional to the number of overlays in the -buffer). If you need to affect the visual appearance of many portions -in the buffer, we recommend using text properties. - -An overlay uses markers to record its beginning and end; thus, -editing the text of the buffer adjusts the beginning and end of each -overlay so that it stays with the text. When you create the overlay, -you can specify whether text inserted at the beginning should be -inside the overlay or outside, and likewise for the end of the overlay. - -@menu -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. -@end menu - -@node Managing Overlays -@subsection Managing Overlays - - This section describes the functions to create, delete and move -overlays, and to examine their contents. Overlay changes are not -recorded in the buffer's undo list, since the overlays are not -part of the buffer's contents. - -@defun overlayp object -This function returns @code{t} if @var{object} is an overlay. -@end defun - -@defun make-overlay start end &optional buffer front-advance rear-advance -This function creates and returns an overlay that belongs to -@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start} -and @var{end} must specify buffer positions; they may be integers or -markers. If @var{buffer} is omitted, the overlay is created in the -current buffer. - -The arguments @var{front-advance} and @var{rear-advance} specify the -marker insertion type for the start of the overlay and for the end of -the overlay, respectively. @xref{Marker Insertion Types}. If they -are both @code{nil}, the default, then the overlay extends to include -any text inserted at the beginning, but not text inserted at the end. -If @var{front-advance} is non-@code{nil}, text inserted at the -beginning of the overlay is excluded from the overlay. If -@var{rear-advance} is non-@code{nil}, text inserted at the end of the -overlay is included in the overlay. -@end defun - -@defun overlay-start overlay -This function returns the position at which @var{overlay} starts, -as an integer. -@end defun - -@defun overlay-end overlay -This function returns the position at which @var{overlay} ends, -as an integer. -@end defun - -@defun overlay-buffer overlay -This function returns the buffer that @var{overlay} belongs to. It -returns @code{nil} if @var{overlay} has been deleted. -@end defun - -@defun delete-overlay overlay -This function deletes @var{overlay}. The overlay continues to exist as -a Lisp object, and its property list is unchanged, but it ceases to be -attached to the buffer it belonged to, and ceases to have any effect on -display. - -A deleted overlay is not permanently disconnected. You can give it a -position in a buffer again by calling @code{move-overlay}. -@end defun - -@defun move-overlay overlay start end &optional buffer -This function moves @var{overlay} to @var{buffer}, and places its bounds -at @var{start} and @var{end}. Both arguments @var{start} and @var{end} -must specify buffer positions; they may be integers or markers. - -If @var{buffer} is omitted, @var{overlay} stays in the same buffer it -was already associated with; if @var{overlay} was deleted, it goes into -the current buffer. - -The return value is @var{overlay}. - -This is the only valid way to change the endpoints of an overlay. Do -not try modifying the markers in the overlay by hand, as that fails to -update other vital data structures and can cause some overlays to be -``lost''. -@end defun - -@defun remove-overlays &optional start end name value -This function removes all the overlays between @var{start} and -@var{end} whose property @var{name} has the value @var{value}. It can -move the endpoints of the overlays in the region, or split them. - -If @var{name} is omitted or @code{nil}, it means to delete all overlays in -the specified region. If @var{start} and/or @var{end} are omitted or -@code{nil}, that means the beginning and end of the buffer respectively. -Therefore, @code{(remove-overlays)} removes all the overlays in the -current buffer. -@end defun - -@defun copy-overlay overlay -This function returns a copy of @var{overlay}. The copy has the same -endpoints and properties as @var{overlay}. However, the marker -insertion type for the start of the overlay and for the end of the -overlay are set to their default values (@pxref{Marker Insertion -Types}). -@end defun - - Here are some examples: - -@example -;; @r{Create an overlay.} -(setq foo (make-overlay 1 10)) - @result{} # -(overlay-start foo) - @result{} 1 -(overlay-end foo) - @result{} 10 -(overlay-buffer foo) - @result{} # -;; @r{Give it a property we can check later.} -(overlay-put foo 'happy t) - @result{} t -;; @r{Verify the property is present.} -(overlay-get foo 'happy) - @result{} t -;; @r{Move the overlay.} -(move-overlay foo 5 20) - @result{} # -(overlay-start foo) - @result{} 5 -(overlay-end foo) - @result{} 20 -;; @r{Delete the overlay.} -(delete-overlay foo) - @result{} nil -;; @r{Verify it is deleted.} -foo - @result{} # -;; @r{A deleted overlay has no position.} -(overlay-start foo) - @result{} nil -(overlay-end foo) - @result{} nil -(overlay-buffer foo) - @result{} nil -;; @r{Undelete the overlay.} -(move-overlay foo 1 20) - @result{} # -;; @r{Verify the results.} -(overlay-start foo) - @result{} 1 -(overlay-end foo) - @result{} 20 -(overlay-buffer foo) - @result{} # -;; @r{Moving and deleting the overlay does not change its properties.} -(overlay-get foo 'happy) - @result{} t -@end example - - Emacs stores the overlays of each buffer in two lists, divided -around an arbitrary ``center position''. One list extends backwards -through the buffer from that center position, and the other extends -forwards from that center position. The center position can be anywhere -in the buffer. - -@defun overlay-recenter pos -This function recenters the overlays of the current buffer around -position @var{pos}. That makes overlay lookup faster for positions -near @var{pos}, but slower for positions far away from @var{pos}. -@end defun - - A loop that scans the buffer forwards, creating overlays, can run -faster if you do @code{(overlay-recenter (point-max))} first. - -@node Overlay Properties -@subsection Overlay Properties - - Overlay properties are like text properties in that the properties that -alter how a character is displayed can come from either source. But in -most respects they are different. @xref{Text Properties}, for comparison. - - Text properties are considered a part of the text; overlays and -their properties are specifically considered not to be part of the -text. Thus, copying text between various buffers and strings -preserves text properties, but does not try to preserve overlays. -Changing a buffer's text properties marks the buffer as modified, -while moving an overlay or changing its properties does not. Unlike -text property changes, overlay property changes are not recorded in -the buffer's undo list. - - Since more than one overlay can specify a property value for the -same character, Emacs lets you specify a priority value of each -overlay. You should not make assumptions about which overlay will -prevail when there is a conflict and they have the same priority. - - These functions read and set the properties of an overlay: - -@defun overlay-get overlay prop -This function returns the value of property @var{prop} recorded in -@var{overlay}, if any. If @var{overlay} does not record any value for -that property, but it does have a @code{category} property which is a -symbol, that symbol's @var{prop} property is used. Otherwise, the value -is @code{nil}. -@end defun - -@defun overlay-put overlay prop value -This function sets the value of property @var{prop} recorded in -@var{overlay} to @var{value}. It returns @var{value}. -@end defun - -@defun overlay-properties overlay -This returns a copy of the property list of @var{overlay}. -@end defun - - See also the function @code{get-char-property} which checks both -overlay properties and text properties for a given character. -@xref{Examining Properties}. - - Many overlay properties have special meanings; here is a table -of them: - -@table @code -@item priority -@kindex priority @r{(overlay property)} -This property's value (which should be a non-negative integer number) -determines the priority of the overlay. No priority, or @code{nil}, -means zero. - -The priority matters when two or more overlays cover the same -character and both specify the same property; the one whose -@code{priority} value is larger overrides the other. For the -@code{face} property, the higher priority overlay's value does not -completely override the other value; instead, its face attributes -override the face attributes of the lower priority @code{face} -property. - -Currently, all overlays take priority over text properties. Please -avoid using negative priority values, as we have not yet decided just -what they should mean. - -@item window -@kindex window @r{(overlay property)} -If the @code{window} property is non-@code{nil}, then the overlay -applies only on that window. - -@item category -@kindex category @r{(overlay property)} -If an overlay has a @code{category} property, we call it the -@dfn{category} of the overlay. It should be a symbol. The properties -of the symbol serve as defaults for the properties of the overlay. - -@item face -@kindex face @r{(overlay property)} -This property controls the way text is displayed---for example, which -font and which colors. @xref{Faces}, for more information. - -In the simplest case, the value is a face name. It can also be a list; -then each element can be any of these possibilities: - -@itemize @bullet -@item -A face name (a symbol or string). - -@item -A property list of face attributes. This has the form (@var{keyword} -@var{value} @dots{}), where each @var{keyword} is a face attribute -name and @var{value} is a meaningful value for that attribute. With -this feature, you do not need to create a face each time you want to -specify a particular attribute for certain text. @xref{Face -Attributes}. - -@item -A cons cell, of the form @code{(foreground-color . @var{color-name})} -or @code{(background-color . @var{color-name})}. These elements -specify just the foreground color or just the background color. - -@code{(foreground-color . @var{color-name})} has the same effect as -@code{(:foreground @var{color-name})}; likewise for the background. -@end itemize - -@item mouse-face -@kindex mouse-face @r{(overlay property)} -This property is used instead of @code{face} when the mouse is within -the range of the overlay. However, Emacs ignores all face attributes -from this property that alter the text size (e.g. @code{:height}, -@code{:weight}, and @code{:slant}). Those attributes are always the -same as in the unhighlighted text. - -@item display -@kindex display @r{(overlay property)} -This property activates various features that change the -way text is displayed. For example, it can make text appear taller -or shorter, higher or lower, wider or narrower, or replaced with an image. -@xref{Display Property}. - -@item help-echo -@kindex help-echo @r{(overlay property)} -If an overlay has a @code{help-echo} property, then when you move the -mouse onto the text in the overlay, Emacs displays a help string in the -echo area, or in the tooltip window. For details see @ref{Text -help-echo}. - -@item modification-hooks -@kindex modification-hooks @r{(overlay property)} -This property's value is a list of functions to be called if any -character within the overlay is changed or if text is inserted strictly -within the overlay. - -The hook functions are called both before and after each change. -If the functions save the information they receive, and compare notes -between calls, they can determine exactly what change has been made -in the buffer text. - -When called before a change, each function receives four arguments: the -overlay, @code{nil}, and the beginning and end of the text range to be -modified. - -When called after a change, each function receives five arguments: the -overlay, @code{t}, the beginning and end of the text range just -modified, and the length of the pre-change text replaced by that range. -(For an insertion, the pre-change length is zero; for a deletion, that -length is the number of characters deleted, and the post-change -beginning and end are equal.) - -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. - -Text properties also support the @code{modification-hooks} property, -but the details are somewhat different (@pxref{Special Properties}). - -@item insert-in-front-hooks -@kindex insert-in-front-hooks @r{(overlay property)} -This property's value is a list of functions to be called before and -after inserting text right at the beginning of the overlay. The calling -conventions are the same as for the @code{modification-hooks} functions. - -@item insert-behind-hooks -@kindex insert-behind-hooks @r{(overlay property)} -This property's value is a list of functions to be called before and -after inserting text right at the end of the overlay. The calling -conventions are the same as for the @code{modification-hooks} functions. - -@item invisible -@kindex invisible @r{(overlay property)} -The @code{invisible} property can make the text in the overlay -invisible, which means that it does not appear on the screen. -@xref{Invisible Text}, for details. - -@item intangible -@kindex intangible @r{(overlay property)} -The @code{intangible} property on an overlay works just like the -@code{intangible} text property. @xref{Special Properties}, for details. - -@item isearch-open-invisible -This property tells incremental search how to make an invisible overlay -visible, permanently, if the final match overlaps it. @xref{Invisible -Text}. - -@item isearch-open-invisible-temporary -This property tells incremental search how to make an invisible overlay -visible, temporarily, during the search. @xref{Invisible Text}. - -@item before-string -@kindex before-string @r{(overlay property)} -This property's value is a string to add to the display at the beginning -of the overlay. The string does not appear in the buffer in any -sense---only on the screen. - -@item after-string -@kindex after-string @r{(overlay property)} -This property's value is a string to add to the display at the end of -the overlay. The string does not appear in the buffer in any -sense---only on the screen. - -@item line-prefix -This property specifies a display spec to prepend to each -non-continuation line at display-time. @xref{Truncation}. - -@item wrap-prefix -This property specifies a display spec to prepend to each continuation -line at display-time. @xref{Truncation}. - -@item evaporate -@kindex evaporate @r{(overlay property)} -If this property is non-@code{nil}, the overlay is deleted automatically -if it becomes empty (i.e., if its length becomes zero). If you give -an empty overlay a non-@code{nil} @code{evaporate} property, that deletes -it immediately. - -@item local-map -@cindex keymap of character (and overlays) -@kindex local-map @r{(overlay property)} -If this property is non-@code{nil}, it specifies a keymap for a portion -of the text. The property's value replaces the buffer's local map, when -the character after point is within the overlay. @xref{Active Keymaps}. - -@item keymap -@kindex keymap @r{(overlay property)} -The @code{keymap} property is similar to @code{local-map} but overrides the -buffer's local map (and the map specified by the @code{local-map} -property) rather than replacing it. -@end table - -The @code{local-map} and @code{keymap} properties do not affect a -string displayed by the @code{before-string}, @code{after-string}, or -@code{display} properties. This is only relevant for mouse clicks and -other mouse events that fall on the string, since point is never on -the string. To bind special mouse events for the string, assign it a -@code{local-map} or @code{keymap} text property. @xref{Special -Properties}. - -@node Finding Overlays -@subsection Searching for Overlays - -@defun overlays-at pos -This function returns a list of all the overlays that cover the -character at position @var{pos} in the current buffer. The list is in -no particular order. An overlay contains position @var{pos} if it -begins at or before @var{pos}, and ends after @var{pos}. - -To illustrate usage, here is a Lisp function that returns a list of the -overlays that specify property @var{prop} for the character at point: - -@smallexample -(defun find-overlays-specifying (prop) - (let ((overlays (overlays-at (point))) - found) - (while overlays - (let ((overlay (car overlays))) - (if (overlay-get overlay prop) - (setq found (cons overlay found)))) - (setq overlays (cdr overlays))) - found)) -@end smallexample -@end defun - -@defun overlays-in beg end -This function returns a list of the overlays that overlap the region -@var{beg} through @var{end}. ``Overlap'' means that at least one -character is contained within the overlay and also contained within the -specified region; however, empty overlays are included in the result if -they are located at @var{beg}, strictly between @var{beg} and @var{end}, -or at @var{end} when @var{end} denotes the position at the end of the -buffer. -@end defun - -@defun next-overlay-change pos -This function returns the buffer position of the next beginning or end -of an overlay, after @var{pos}. If there is none, it returns -@code{(point-max)}. -@end defun - -@defun previous-overlay-change pos -This function returns the buffer position of the previous beginning or -end of an overlay, before @var{pos}. If there is none, it returns -@code{(point-min)}. -@end defun - - As an example, here's a simplified (and inefficient) version of the -primitive function @code{next-single-char-property-change} -(@pxref{Property Search}). It searches forward from position -@var{pos} for the next position where the value of a given property -@code{prop}, as obtained from either overlays or text properties, -changes. - -@smallexample -(defun next-single-char-property-change (position prop) - (save-excursion - (goto-char position) - (let ((propval (get-char-property (point) prop))) - (while (and (not (eobp)) - (eq (get-char-property (point) prop) propval)) - (goto-char (min (next-overlay-change (point)) - (next-single-property-change (point) prop))))) - (point))) -@end smallexample - -@node Width -@section Width - -Since not all characters have the same width, these functions let you -check the width of a character. @xref{Primitive Indent}, and -@ref{Screen Lines}, for related functions. - -@defun char-width char -This function returns the width in columns of the character -@var{char}, if it were displayed in the current buffer (i.e.@: taking -into account the buffer's display table, if any; @pxref{Display -Tables}). The width of a tab character is usually @code{tab-width} -(@pxref{Usual Display}). -@end defun - -@defun string-width string -This function returns the width in columns of the string @var{string}, -if it were displayed in the current buffer and the selected window. -@end defun - -@defun truncate-string-to-width string width &optional start-column padding ellipsis -This function returns the part of @var{string} that fits within -@var{width} columns, as a new string. - -If @var{string} does not reach @var{width}, then the result ends where -@var{string} ends. If one multi-column character in @var{string} -extends across the column @var{width}, that character is not included in -the result. Thus, the result can fall short of @var{width} but cannot -go beyond it. - -The optional argument @var{start-column} specifies the starting column. -If this is non-@code{nil}, then the first @var{start-column} columns of -the string are omitted from the value. If one multi-column character in -@var{string} extends across the column @var{start-column}, that -character is not included. - -The optional argument @var{padding}, if non-@code{nil}, is a padding -character added at the beginning and end of the result string, to extend -it to exactly @var{width} columns. The padding character is used at the -end of the result if it falls short of @var{width}. It is also used at -the beginning of the result if one multi-column character in -@var{string} extends across the column @var{start-column}. - -If @var{ellipsis} is non-@code{nil}, it should be a string which will -replace the end of @var{str} (including any padding) if it extends -beyond @var{end-column}, unless the display width of @var{str} is -equal to or less than the display width of @var{ellipsis}. If -@var{ellipsis} is non-@code{nil} and not a string, it stands for -@code{"..."}. - -@example -(truncate-string-to-width "\tab\t" 12 4) - @result{} "ab" -(truncate-string-to-width "\tab\t" 12 4 ?\s) - @result{} " ab " -@end example -@end defun - -@node Line Height -@section Line Height -@cindex line height - - The total height of each display line consists of the height of the -contents of the line, plus optional additional vertical line spacing -above or below the display line. - - The height of the line contents is the maximum height of any -character or image on that display line, including the final newline -if there is one. (A display line that is continued doesn't include a -final newline.) That is the default line height, if you do nothing to -specify a greater height. (In the most common case, this equals the -height of the default frame font.) - - There are several ways to explicitly specify a larger line height, -either by specifying an absolute height for the display line, or by -specifying vertical space. However, no matter what you specify, the -actual line height can never be less than the default. - -@kindex line-height @r{(text property)} - A newline can have a @code{line-height} text or overlay property -that controls the total height of the display line ending in that -newline. - - If the property value is @code{t}, the newline character has no -effect on the displayed height of the line---the visible contents -alone determine the height. This is useful for tiling small images -(or image slices) without adding blank areas between the images. - - If the property value is a list of the form @code{(@var{height} -@var{total})}, that adds extra space @emph{below} the display line. -First Emacs uses @var{height} as a height spec to control extra space -@emph{above} the line; then it adds enough space @emph{below} the line -to bring the total line height up to @var{total}. In this case, the -other ways to specify the line spacing are ignored. - - Any other kind of property value is a height spec, which translates -into a number---the specified line height. There are several ways to -write a height spec; here's how each of them translates into a number: - -@table @code -@item @var{integer} -If the height spec is a positive integer, the height value is that integer. -@item @var{float} -If the height spec is a float, @var{float}, the numeric height value -is @var{float} times the frame's default line height. -@item (@var{face} . @var{ratio}) -If the height spec is a cons of the format shown, the numeric height -is @var{ratio} times the height of face @var{face}. @var{ratio} can -be any type of number, or @code{nil} which means a ratio of 1. -If @var{face} is @code{t}, it refers to the current face. -@item (nil . @var{ratio}) -If the height spec is a cons of the format shown, the numeric height -is @var{ratio} times the height of the contents of the line. -@end table - - Thus, any valid height spec determines the height in pixels, one way -or another. If the line contents' height is less than that, Emacs -adds extra vertical space above the line to achieve the specified -total height. - - If you don't specify the @code{line-height} property, the line's -height consists of the contents' height plus the line spacing. -There are several ways to specify the line spacing for different -parts of Emacs text. - - On graphical terminals, you can specify the line spacing for all -lines in a frame, using the @code{line-spacing} frame parameter -(@pxref{Layout Parameters}). However, if the default value of -@code{line-spacing} is non-@code{nil}, it overrides the -frame's @code{line-spacing} parameter. An integer value specifies the -number of pixels put below lines. A floating point number specifies -the spacing relative to the frame's default line height. - -@vindex line-spacing - You can specify the line spacing for all lines in a buffer via the -buffer-local @code{line-spacing} variable. An integer value specifies -the number of pixels put below lines. A floating point number -specifies the spacing relative to the default frame line height. This -overrides line spacings specified for the frame. - -@kindex line-spacing @r{(text property)} - Finally, a newline can have a @code{line-spacing} text or overlay -property that overrides the default frame line spacing and the buffer -local @code{line-spacing} variable, for the display line ending in -that newline. - - One way or another, these mechanisms specify a Lisp value for the -spacing of each line. The value is a height spec, and it translates -into a Lisp value as described above. However, in this case the -numeric height value specifies the line spacing, rather than the line -height. - - On text terminals, the line spacing cannot be altered. - -@node Faces -@section Faces -@cindex faces - - A @dfn{face} is a collection of graphical @dfn{attributes} for -displaying text: font, foreground color, background color, optional -underlining, and so on. Faces control how Emacs displays text in -buffers, as well as other parts of the frame such as the mode line. -@xref{Standard Faces,,, emacs, The GNU Emacs Manual}, for the list of -faces Emacs normally comes with. - -@cindex face id - For most purposes, you refer to a face in Lisp programs using its -@dfn{face name}, which is usually a Lisp symbol. For backward -compatibility, a face name can also be a string, which is equivalent -to a Lisp symbol of the same name. - -@defun facep object -This function returns a non-@code{nil} value if @var{object} is a Lisp -symbol or string that names a face. Otherwise, it returns @code{nil}. -@end defun - - By default, each face name corresponds to the same set of attributes -in all frames. But you can also assign a face name a special set of -attributes in one frame (@pxref{Attribute Functions}). - -@menu -* Defining Faces:: How to define a face. -* Face Attributes:: What is in a face? -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for a character. -* Face Remapping:: Remapping faces to alternative definitions. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Basic Faces:: Faces that are defined by default. -* Font Selection:: Finding the best available font for a face. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. -* Low-Level Font:: Lisp representation for character display fonts. -@end menu - -@node Defining Faces -@subsection Defining Faces - - The @code{defface} macro defines a face and specifies its default -appearance. The user can subsequently customize the face using the -Customize interface (@pxref{Customization}). - -@defmac defface face spec doc [keyword value]@dots{} -This macro declares @var{face} as a customizable face whose default -attributes are given by @var{spec}. You should not quote the symbol -@var{face}, and it should not end in @samp{-face} (that would be -redundant). The argument @var{doc} is a documentation string for the -face. The additional @var{keyword} arguments have the same meanings -as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}). - -When @code{defface} executes, it defines the face according to -@var{spec}, then uses any customizations that were read from the -init file (@pxref{Init File}) to override that specification. - -When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs -Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun} -overrides any customizations of the face. This way, the face reflects -exactly what the @code{defface} says. - -@cindex face specification -The @var{spec} argument is a @dfn{face specification}, which states -how the face should appear on different kinds of terminals. It should -be an alist whose elements each have the form @code{(@var{display} -@var{atts})}. @var{display} specifies a class of terminals (see -below), while @var{atts} is a property list of face attributes and -their values, specifying the appearance of the face on matching -terminals -@iftex -(see the next section for details about face attributes). -@end iftex -@ifnottex -(@pxref{Face Attributes}, for details about face attributes). -@end ifnottex - -The @var{display} part of an element of @var{spec} determines which -frames the element matches. If more than one element of @var{spec} -matches a given frame, the first element that matches is the one used -for that frame. There are three possibilities for @var{display}: - -@table @asis -@item @code{default} -This element of @var{spec} doesn't match any frames; instead, it -specifies defaults that apply to all frames. This kind of element, if -used, must be the first element of @var{spec}. Each of the following -elements can override any or all of these defaults. - -@item @code{t} -This element of @var{spec} matches all frames. Therefore, any -subsequent elements of @var{spec} are never used. Normally -@code{t} is used in the last (or only) element of @var{spec}. - -@item a list -If @var{display} is a list, each element should have the form -@code{(@var{characteristic} @var{value}@dots{})}. Here -@var{characteristic} specifies a way of classifying frames, and the -@var{value}s are possible classifications which @var{display} should -apply to. Here are the possible values of @var{characteristic}: - -@table @code -@item type -The kind of window system the frame uses---either @code{graphic} (any -graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console), -@code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} -(a non-graphics-capable display). -@xref{Window Systems, window-system}. - -@item class -What kinds of colors the frame supports---either @code{color}, -@code{grayscale}, or @code{mono}. - -@item background -The kind of background---either @code{light} or @code{dark}. - -@item min-colors -An integer that represents the minimum number of colors the frame -should support. This matches a frame if its -@code{display-color-cells} value is at least the specified integer. - -@item supports -Whether or not the frame can display the face attributes given in -@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face -Attribute Testing}, for more information on exactly how this testing -is done. -@end table - -If an element of @var{display} specifies more than one @var{value} for a -given @var{characteristic}, any of those values is acceptable. If -@var{display} has more than one element, each element should specify a -different @var{characteristic}; then @emph{each} characteristic of the -frame must match one of the @var{value}s specified for it in -@var{display}. -@end table -@end defmac - - Here's how the standard face @code{highlight} is defined: - -@example -(defface highlight - '((((class color) (min-colors 88) (background light)) - :background "darkseagreen2") - (((class color) (min-colors 88) (background dark)) - :background "darkolivegreen") - (((class color) (min-colors 16) (background light)) - :background "darkseagreen2") - (((class color) (min-colors 16) (background dark)) - :background "darkolivegreen") - (((class color) (min-colors 8)) - :background "green" :foreground "black") - (t :inverse-video t)) - "Basic face for highlighting." - :group 'basic-faces) -@end example - - Internally, Emacs stores the face's default specification in its -@code{face-defface-spec} symbol property (@pxref{Property Lists}). -The @code{saved-face} property stores the face specification saved by -the user, using the customization buffer; the @code{customized-face} -property stores the face specification customized for the current -session, but not saved; and the @code{theme-face} property stores an -alist associating the active customization settings and Custom themes -with their specifications for that face. The face's documentation -string is stored in the @code{face-documentation} property. But -normally you should not try to set any of these properties directly. -@xref{Applying Customizations}, for the @code{custom-set-faces} -function, which is used to apply customized face settings. - - People are sometimes tempted to create variables whose values -specify a face to use. In the vast majority of cases, this is not -necessary; it is preferable to simply use faces directly. - -@defopt frame-background-mode -This option, if non-@code{nil}, specifies the background type to use for -interpreting face definitions. If it is @code{dark}, then Emacs treats -all frames as if they had a dark background, regardless of their actual -background colors. If it is @code{light}, then Emacs treats all frames -as if they had a light background. -@end defopt - -@node Face Attributes -@subsection Face Attributes -@cindex face attributes - - The effect of using a face is determined by a fixed set of @dfn{face -attributes}. This table lists all the face attributes, their possible -values, and their effects. You can specify more than one face for a -given piece of text; Emacs merges the attributes of all the faces to -determine how to display the text. @xref{Displaying Faces}. - - In addition to the values given below, each face attribute can also -have the value @code{unspecified}. This special value means the face -doesn't specify that attribute. In face merging, when the first face -fails to specify a particular attribute, the next face gets a chance. -However, the @code{default} face must specify all attributes. - - Some of these attributes are meaningful only on certain kinds of -displays. If your display cannot handle a certain attribute, the -attribute is ignored. - -@table @code -@item :family -Font family or fontset (a string). @xref{Fonts,,, emacs, The GNU -Emacs Manual}. If you specify a font family name, the wild-card -characters @samp{*} and @samp{?} are allowed. The function -@code{font-family-list}, described below, returns a list of available -family names. @xref{Fontsets}, for information about fontsets. - -@item :foundry -The name of the @dfn{font foundry} for the font family specified by -the @code{:family} attribute (a string). The wild-card characters -@samp{*} and @samp{?} are allowed. @xref{Fonts,,, emacs, The GNU -Emacs Manual}. - -@item :width -Relative proportionate character width, also known as the character -set width. This should be one of the symbols @code{ultra-condensed}, -@code{extra-condensed}, @code{condensed}, @code{semi-condensed}, -@code{normal}, @code{semi-expanded}, @code{expanded}, -@code{extra-expanded}, or @code{ultra-expanded}. - -@item :height -The height of the font. In the simplest case, this is an integer in -units of 1/10 point. - -The value can also be a floating point number or a function, which -specifies the height relative to an @dfn{underlying face} (i.e., a -face that has a lower priority in the list described in -@ref{Displaying Faces}). If the value is a floating point number, -that specifies the amount by which to scale the height of the -underlying face. If the value is a function, that function is called -with one argument, the height of the underlying face, and returns the -height of the new face. If the function is passed an integer -argument, it must return an integer. - -The height of the default face must be specified using an integer; -floating point and function values are not allowed. - -@item :weight -Font weight---one of the symbols (from densest to faintest) -@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold}, -@code{normal}, @code{semi-light}, @code{light}, @code{extra-light}, or -@code{ultra-light}. On text terminals which support -variable-brightness text, any weight greater than normal is displayed -as extra bright, and any weight less than normal is displayed as -half-bright. - -@item :slant -Font slant---one of the symbols @code{italic}, @code{oblique}, -@code{normal}, @code{reverse-italic}, or @code{reverse-oblique}. On -text terminals that support variable-brightness text, slanted text is -displayed as half-bright. - -@item :foreground -Foreground color, a string. The value can be a system-defined color -name, or a hexadecimal color specification. @xref{Color Names}. On -black-and-white displays, certain shades of gray are implemented by -stipple patterns. - -@item :background -Background color, a string. The value can be a system-defined color -name, or a hexadecimal color specification. @xref{Color Names}. - -@item :underline -Whether or not characters should be underlined, and in what color. If -the value is @code{t}, underlining uses the foreground color of the -face. If the value is a string, underlining uses that color. The -value @code{nil} means do not underline. - -@item :overline -Whether or not characters should be overlined, and in what color. -The value is used like that of @code{:underline}. - -@item :strike-through -Whether or not characters should be strike-through, and in what -color. The value is used like that of @code{:underline}. - -@item :box -Whether or not a box should be drawn around characters, its color, the -width of the box lines, and 3D appearance. Here are the possible -values of the @code{:box} attribute, and what they mean: - -@table @asis -@item @code{nil} -Don't draw a box. - -@item @code{t} -Draw a box with lines of width 1, in the foreground color. - -@item @var{color} -Draw a box with lines of width 1, in color @var{color}. - -@item @code{(:line-width @var{width} :color @var{color} :style @var{style})} -This way you can explicitly specify all aspects of the box. The value -@var{width} specifies the width of the lines to draw; it defaults to -1. A negative width @var{-n} means to draw a line of width @var{n} -that occupies the space of the underlying text, thus avoiding any -increase in the character height or width. - -The value @var{color} specifies the color to draw with. The default is -the foreground color of the face for simple boxes, and the background -color of the face for 3D boxes. - -The value @var{style} specifies whether to draw a 3D box. If it is -@code{released-button}, the box looks like a 3D button that is not being -pressed. If it is @code{pressed-button}, the box looks like a 3D button -that is being pressed. If it is @code{nil} or omitted, a plain 2D box -is used. -@end table - -@item :inverse-video -Whether or not characters should be displayed in inverse video. The -value should be @code{t} (yes) or @code{nil} (no). - -@item :stipple -The background stipple, a bitmap. - -The value can be a string; that should be the name of a file containing -external-format X bitmap data. The file is found in the directories -listed in the variable @code{x-bitmap-file-path}. - -Alternatively, the value can specify the bitmap directly, with a list -of the form @code{(@var{width} @var{height} @var{data})}. Here, -@var{width} and @var{height} specify the size in pixels, and -@var{data} is a string containing the raw bits of the bitmap, row by -row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes -in the string (which should be a unibyte string for best results). -This means that each row always occupies at least one whole byte. - -If the value is @code{nil}, that means use no stipple pattern. - -Normally you do not need to set the stipple attribute, because it is -used automatically to handle certain shades of gray. - -@item :font -The font used to display the face. Its value should be a font object. -@xref{Font Selection}, for information about font objects. - -When specifying this attribute using @code{set-face-attribute} -(@pxref{Attribute Functions}), you may also supply a font spec, a font -entity, or a string. Emacs converts such values to an appropriate -font object, and stores that font object as the actual attribute -value. If you specify a string, the contents of the string should be -a font name (@pxref{Fonts,,, emacs, The GNU Emacs Manual}); if the -font name is an XLFD containing wildcards, Emacs chooses the first -font matching those wildcards. Specifying this attribute also changes -the values of the @code{:family}, @code{:foundry}, @code{:width}, -@code{:height}, @code{:weight}, and @code{:slant} attributes. - -@item :inherit -The name of a face from which to inherit attributes, or a list of face -names. Attributes from inherited faces are merged into the face like -an underlying face would be, with higher priority than underlying -faces (@pxref{Displaying Faces}). If a list of faces is used, -attributes from faces earlier in the list override those from later -faces. -@end table - -For compatibility with Emacs 20, you can also specify values for two -``fake'' face attributes: @code{:bold} and @code{:italic}. Their -values must be either @code{t} or @code{nil}; a value of -@code{unspecified} is not allowed. Setting @code{:bold} to @code{t} -is equivalent to setting the @code{:weight} attribute to @code{bold}, -and setting it to @code{nil} is equivalent to setting @code{:weight} -to @code{normal}. Setting @code{:italic} to @code{t} is equivalent to -setting the @code{:slant} attribute to @code{italic}, and setting it -to @code{nil} is equivalent to setting @code{:slant} to @code{normal}. - -@defun font-family-list &optional frame -This function returns a list of available font family names. The -optional argument @var{frame} specifies the frame on which the text is -to be displayed; if it is @code{nil}, the selected frame is used. -@end defun - -@defopt underline-minimum-offset -This variable specifies the minimum distance between the baseline and -the underline, in pixels, when displaying underlined text. -@end defopt - -@defopt x-bitmap-file-path -This variable specifies a list of directories for searching -for bitmap files, for the @code{:stipple} attribute. -@end defopt - -@defun bitmap-spec-p object -This returns @code{t} if @var{object} is a valid bitmap specification, -suitable for use with @code{:stipple} (see above). It returns -@code{nil} otherwise. -@end defun - -@node Attribute Functions -@subsection Face Attribute Functions - - This section describes the functions for accessing and modifying the -attributes of an existing face. - -@defun set-face-attribute face frame &rest arguments -This function sets one or more attributes of @var{face} for -@var{frame}. The attributes you specify this way override whatever -the @code{defface} says. - -The extra arguments @var{arguments} specify the attributes to set, and -the values for them. They should consist of alternating attribute -names (such as @code{:family} or @code{:underline}) and values. Thus, - -@example -(set-face-attribute 'foo nil - :width 'extended - :weight 'bold) -@end example - -@noindent -sets the attribute @code{:width} to @code{extended} and the attribute -@code{:weight} to @code{bold}. - -If @var{frame} is @code{t}, this function sets the default attributes -for new frames. Default attribute values specified this way override -the @code{defface} for newly created frames. - -If @var{frame} is @code{nil}, this function sets the attributes for -all existing frames, and the default for new frames. -@end defun - -@defun face-attribute face attribute &optional frame inherit -This returns the value of the @var{attribute} attribute of @var{face} -on @var{frame}. If @var{frame} is @code{nil}, that means the selected -frame (@pxref{Input Focus}). - -If @var{frame} is @code{t}, this returns whatever new-frames default -value you previously specified with @code{set-face-attribute} for the -@var{attribute} attribute of @var{face}. If you have not specified -one, it returns @code{nil}. - -If @var{inherit} is @code{nil}, only attributes directly defined by -@var{face} are considered, so the return value may be -@code{unspecified}, or a relative value. If @var{inherit} is -non-@code{nil}, @var{face}'s definition of @var{attribute} is merged -with the faces specified by its @code{:inherit} attribute; however the -return value may still be @code{unspecified} or relative. If -@var{inherit} is a face or a list of faces, then the result is further -merged with that face (or faces), until it becomes specified and -absolute. - -To ensure that the return value is always specified and absolute, use -a value of @code{default} for @var{inherit}; this will resolve any -unspecified or relative values by merging with the @code{default} face -(which is always completely specified). - -For example, - -@example -(face-attribute 'bold :weight) - @result{} bold -@end example -@end defun - -@defun face-attribute-relative-p attribute value -This function returns non-@code{nil} if @var{value}, when used as the -value of the face attribute @var{attribute}, is relative. This means -it would modify, rather than completely override, any value that comes -from a subsequent face in the face list or that is inherited from -another face. - -@code{unspecified} is a relative value for all attributes. For -@code{:height}, floating point and function values are also relative. - -For example: - -@example -(face-attribute-relative-p :height 2.0) - @result{} t -@end example -@end defun - -@defun face-all-attributes face &optional frame -This function returns an alist of attributes of @var{face}. The -elements of the result are name-value pairs of the form -@w{@code{(@var{attr-name} . @var{attr-value})}}. Optional argument -@var{frame} specifies the frame whose definition of @var{face} to -return; if omitted or @code{nil}, the returned value describes the -default attributes of @var{face} for newly created frames. -@end defun - -@defun merge-face-attribute attribute value1 value2 -If @var{value1} is a relative value for the face attribute -@var{attribute}, returns it merged with the underlying value -@var{value2}; otherwise, if @var{value1} is an absolute value for the -face attribute @var{attribute}, returns @var{value1} unchanged. -@end defun - - The following commands and functions mostly provide compatibility -with old versions of Emacs. They work by calling -@code{set-face-attribute}. Values of @code{t} and @code{nil} for -their @var{frame} argument are handled just like -@code{set-face-attribute} and @code{face-attribute}. The commands -read their arguments using the minibuffer, if called interactively. - -@deffn Command set-face-foreground face color &optional frame -@deffnx Command set-face-background face color &optional frame -These set the @code{:foreground} attribute (or @code{:background} -attribute, respectively) of @var{face} to @var{color}. -@end deffn - -@deffn Command set-face-stipple face pattern &optional frame -This sets the @code{:stipple} attribute of @var{face} to -@var{pattern}. -@end deffn - -@deffn Command set-face-font face font &optional frame -This sets the @code{:font} attribute of @var{face} to @var{font}. -@end deffn - -@defun set-face-bold-p face bold-p &optional frame -This sets the @code{:weight} attribute of @var{face} to @var{normal} -if @var{bold-p} is @code{nil}, and to @var{bold} otherwise. -@end defun - -@defun set-face-italic-p face italic-p &optional frame -This sets the @code{:slant} attribute of @var{face} to @var{normal} if -@var{italic-p} is @code{nil}, and to @var{italic} otherwise. -@end defun - -@defun set-face-underline-p face underline &optional frame -This sets the @code{:underline} attribute of @var{face} to -@var{underline}. -@end defun - -@defun set-face-inverse-video-p face inverse-video-p &optional frame -This sets the @code{:inverse-video} attribute of @var{face} to -@var{inverse-video-p}. -@end defun - -@deffn Command invert-face face &optional frame -This swaps the foreground and background colors of face @var{face}. -@end deffn - - The following functions examine the attributes of a face. If you -don't specify @var{frame}, they refer to the selected frame; @code{t} -refers to the default data for new frames. They return the symbol -@code{unspecified} if the face doesn't define any value for that -attribute. - -@defun face-foreground face &optional frame inherit -@defunx face-background face &optional frame inherit -These functions return the foreground color (or background color, -respectively) of face @var{face}, as a string. - -If @var{inherit} is @code{nil}, only a color directly defined by the face is -returned. If @var{inherit} is non-@code{nil}, any faces specified by its -@code{:inherit} attribute are considered as well, and if @var{inherit} -is a face or a list of faces, then they are also considered, until a -specified color is found. To ensure that the return value is always -specified, use a value of @code{default} for @var{inherit}. -@end defun - -@defun face-stipple face &optional frame inherit -This function returns the name of the background stipple pattern of face -@var{face}, or @code{nil} if it doesn't have one. - -If @var{inherit} is @code{nil}, only a stipple directly defined by the -face is returned. If @var{inherit} is non-@code{nil}, any faces -specified by its @code{:inherit} attribute are considered as well, and -if @var{inherit} is a face or a list of faces, then they are also -considered, until a specified stipple is found. To ensure that the -return value is always specified, use a value of @code{default} for -@var{inherit}. -@end defun - -@defun face-font face &optional frame -This function returns the name of the font of face @var{face}. -@end defun - -@defun face-bold-p face &optional frame -This function returns a non-@code{nil} value if the @code{:weight} -attribute of @var{face} is bolder than normal (i.e., one of -@code{semi-bold}, @code{bold}, @code{extra-bold}, or -@code{ultra-bold}). Otherwise, it returns @code{nil}. -@end defun - -@defun face-italic-p face &optional frame -This function returns a non-@code{nil} value if the @code{:slant} -attribute of @var{face} is @code{italic} or @code{oblique}, and -@code{nil} otherwise. -@end defun - -@defun face-underline-p face &optional frame -This function returns the @code{:underline} attribute of face @var{face}. -@end defun - -@defun face-inverse-video-p face &optional frame -This function returns the @code{:inverse-video} attribute of face @var{face}. -@end defun - -@node Displaying Faces -@subsection Displaying Faces - - Here is how Emacs determines the face to use for displaying any -given piece of text: - -@itemize @bullet -@item -If the text consists of a special glyph, the glyph can specify a -particular face. @xref{Glyphs}. - -@item -If the text lies within an active region, Emacs highlights it using -the @code{region} face. @xref{Standard Faces,,, emacs, The GNU Emacs -Manual}. - -@item -If the text lies within an overlay with a non-@code{nil} @code{face} -property, Emacs applies the face or face attributes specified by that -property. If the overlay has a @code{mouse-face} property and the -mouse is ``near enough'' to the overlay, Emacs applies the face or -face attributes specified by the @code{mouse-face} property instead. -@xref{Overlay Properties}. - -When multiple overlays cover one character, an overlay with higher -priority overrides those with lower priority. @xref{Overlays}. - -@item -If the text contains a @code{face} or @code{mouse-face} property, -Emacs applies the specified faces and face attributes. @xref{Special -Properties}. (This is how Font Lock mode faces are applied. -@xref{Font Lock Mode}.) - -@item -If the text lies within the mode line of the selected window, Emacs -applies the @code{mode-line} face. For the mode line of a -non-selected window, Emacs applies the @code{mode-line-inactive} face. -For a header line, Emacs applies the @code{header-line} face. - -@item -If any given attribute has not been specified during the preceding -steps, Emacs applies the attribute of the @code{default} face. -@end itemize - - If these various sources together specify more than one face for a -particular character, Emacs merges the attributes of the various faces -specified. For each attribute, Emacs tries using the above order -(i.e.@: first the face of any special glyph; then the face for region -highlighting, if appropriate; and so on). - -@node Face Remapping -@subsection Face Remapping - - The variable @code{face-remapping-alist} is used for buffer-local or -global changes in the appearance of a face. For instance, it is used -to implement the @code{text-scale-adjust} command (@pxref{Text -Scale,,, emacs, The GNU Emacs Manual}). - -@defvar face-remapping-alist -The value of this variable is an alist whose elements have the form -@code{(@var{face} . @var{remapping})}. This causes Emacs to display -any text having the face @var{face} with @var{remapping}, rather than -the ordinary definition of @var{face}. @var{remapping} may be any -face specification suitable for a @code{face} text property: either a -face name, or a property list of attribute/value pairs, or a list in -which each element is either a face name or a property list -(@pxref{Special Properties}). - -If @code{face-remapping-alist} is buffer-local, its local value takes -effect only within that buffer. - -Two points bear emphasizing: - -@enumerate -@item -@var{remapping} serves as the complete specification for the remapped -face---it replaces the normal definition of @var{face}, instead of -modifying it. - -@item -If @var{remapping} references the same face name @var{face}, either -directly or via the @code{:inherit} attribute of some other face in -@var{remapping}, that reference uses the normal definition of -@var{face}. In other words, the remapping cannot be recursive. - -For instance, if the @code{mode-line} face is remapped using this -entry in @code{face-remapping-alist}: -@example -(mode-line italic mode-line) -@end example -@noindent -then the new definition of the @code{mode-line} face inherits from the -@code{italic} face, and the @emph{normal} (non-remapped) definition of -@code{mode-line} face. -@end enumerate -@end defvar - - The following functions implement a higher-level interface to -@code{face-remapping-alist}. Most Lisp code should use these -functions instead of setting @code{face-remapping-alist} directly, to -avoid trampling on remappings applied elsewhere. These functions are -intended for buffer-local remappings, so they all make -@code{face-remapping-alist} buffer-local as a side-effect. They manage -@code{face-remapping-alist} entries of the form - -@example - (@var{face} @var{relative-spec-1} @var{relative-spec-2} @var{...} @var{base-spec}) -@end example - -@noindent -where, as explained above, each of the @var{relative-spec-N} and -@var{base-spec} is either a face name, or a property list of -attribute/value pairs. Each of the @dfn{relative remapping} entries, -@var{relative-spec-N}, is managed by the -@code{face-remap-add-relative} and @code{face-remap-remove-relative} -functions; these are intended for simple modifications like changing -the text size. The @dfn{base remapping} entry, @var{base-spec}, has -the lowest priority and is managed by the @code{face-remap-set-base} -and @code{face-remap-reset-base} functions; it is intended for major -modes to remap faces in the buffers they control. - -@defun face-remap-add-relative face &rest specs -This functions adds the face specifications in @var{specs} as relative -remappings for face @var{face} in the current buffer. The remaining -arguments, @var{specs}, should form either a list of face names, or a -property list of attribute/value pairs. - -The return value is a Lisp object that serves as a ``cookie''; you can -pass this object as an argument to @code{face-remap-remove-relative} -if you need to remove the remapping later. - -@example -;; Remap the `escape-glyph' face into a combination -;; of the `highlight' and `italic' faces: -(face-remap-add-relative 'escape-glyph 'highlight 'italic) - -;; Increase the size of the `default' face by 50%: -(face-remap-add-relative 'default :height 1.5) -@end example -@end defun - -@defun face-remap-remove-relative cookie -This function removes a relative remapping previously added by -@code{face-remap-add-relative}. @var{cookie} should be the Lisp -object returned by @code{face-remap-add-relative} when the remapping -was added. -@end defun - -@defun face-remap-set-base face &rest specs -This function sets the base remapping of @var{face} in the current -buffer to @var{specs}. If @var{specs} is empty, the default base -remapping is restored, similar to calling @code{face-remap-reset-base} -(see below); note that this is different from @var{specs} containing a -single value @code{nil}, which has the opposite result (the global -definition of @var{face} is ignored). - -This overwrites the default @var{base-spec}, which inherits the global -face definition, so it is up to the caller to add such inheritance if -so desired. -@end defun - -@defun face-remap-reset-base face -This function sets the base remapping of @var{face} to its default -value, which inherits from @var{face}'s global definition. -@end defun - -@node Face Functions -@subsection Functions for Working with Faces - - Here are additional functions for creating and working with faces. - -@defun face-list -This function returns a list of all defined face names. -@end defun - -@defun face-id face -This function returns the @dfn{face number} of face @var{face}. This -is a number that uniquely identifies a face at low levels within -Emacs. It is seldom necessary to refer to a face by its face number. -@end defun - -@defun face-documentation face -This function returns the documentation string of face @var{face}, or -@code{nil} if none was specified for it. -@end defun - -@defun face-equal face1 face2 &optional frame -This returns @code{t} if the faces @var{face1} and @var{face2} have the -same attributes for display. -@end defun - -@defun face-differs-from-default-p face &optional frame -This returns non-@code{nil} if the face @var{face} displays -differently from the default face. -@end defun - -@cindex face alias -A @dfn{face alias} provides an equivalent name for a face. You can -define a face alias by giving the alias symbol the @code{face-alias} -property, with a value of the target face name. The following example -makes @code{modeline} an alias for the @code{mode-line} face. - -@example -(put 'modeline 'face-alias 'mode-line) -@end example - -@defmac define-obsolete-face-alias obsolete-face current-face when -This macro defines @code{obsolete-face} as an alias for -@var{current-face}, and also marks it as obsolete, indicating that it -may be removed in future. @var{when} should be a string indicating -when @code{obsolete-face} was made obsolete (usually a version number -string). -@end defmac - -@node Auto Faces -@subsection Automatic Face Assignment -@cindex automatic face assignment -@cindex faces, automatic choice - - This hook is used for automatically assigning faces to text in the -buffer. It is part of the implementation of Jit-Lock mode, used by -Font-Lock. - -@defvar fontification-functions -This variable holds a list of functions that are called by Emacs -redisplay as needed, just before doing redisplay. They are called even -when Font Lock Mode isn't enabled. When Font Lock Mode is enabled, this -variable usually holds just one function, @code{jit-lock-function}. - -The functions are called in the order listed, with one argument, a -buffer position @var{pos}. Collectively they should attempt to assign -faces to the text in the current buffer starting at @var{pos}. - -The functions should record the faces they assign by setting the -@code{face} property. They should also add a non-@code{nil} -@code{fontified} property to all the text they have assigned faces to. -That property tells redisplay that faces have been assigned to that text -already. - -It is probably a good idea for the functions to do nothing if the -character after @var{pos} already has a non-@code{nil} @code{fontified} -property, but this is not required. If one function overrides the -assignments made by a previous one, the properties after the last -function finishes are the ones that really matter. - -For efficiency, we recommend writing these functions so that they -usually assign faces to around 400 to 600 characters at each call. -@end defvar - -@node Basic Faces -@subsection Basic Faces - -If your Emacs Lisp program needs to assign some faces to text, it is -often a good idea to use certain existing faces or inherit from them, -rather than defining entirely new faces. This way, if other users -have customized the basic faces to give Emacs a certain look, your -program will ``fit in'' without additional customization. - - Some of the basic faces defined in Emacs are listed below. In -addition to these, you might want to make use of the Font Lock faces -for syntactic highlighting, if highlighting is not already handled by -Font Lock mode, or if some Font Lock faces are not in use. -@xref{Faces for Font Lock}. - -@table @code -@item default -The default face, whose attributes are all specified. All other faces -implicitly inherit from it: any unspecified attribute defaults to the -attribute on this face (@pxref{Face Attributes}). - -@item bold -@itemx italic -@itemx bold-italic -@itemx underline -@itemx fixed-pitch -@itemx variable-pitch -These have the attributes indicated by their names (e.g. @code{bold} -has a bold @code{:weight} attribute), with all other attributes -unspecified (and so given by @code{default}). - -@item shadow -For ``dimmed out'' text. For example, it is used for the ignored -part of a filename in the minibuffer (@pxref{Minibuffer File,, -Minibuffers for File Names, emacs, The GNU Emacs Manual}). - -@item link -@itemx link-visited -For clickable text buttons that send the user to a different -buffer or ``location''. - -@item highlight -For stretches of text that should temporarily stand out. For example, -it is commonly assigned to the @code{mouse-face} property for cursor -highlighting (@pxref{Special Properties}). - -@item match -For text matching a search command. - -@item error -@itemx warning -@itemx success -For text concerning errors, warnings, or successes. For example, -these are used for messages in @file{*Compilation*} buffers. -@end table - -@node Font Selection -@subsection Font Selection - - Before Emacs can draw a character on a graphical display, it must -select a @dfn{font} for that character@footnote{In this context, the -term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock -Mode}).}. @xref{Fonts,,, emacs, The GNU Emacs Manual}. Normally, -Emacs automatically chooses a font based on the faces assigned to that -character---specifically, the face attributes @code{:family}, -@code{:weight}, @code{:slant}, and @code{:width} (@pxref{Face -Attributes}). The choice of font also depends on the character to be -displayed; some fonts can only display a limited set of characters. -If no available font exactly fits the requirements, Emacs looks for -the @dfn{closest matching font}. The variables in this section -control how Emacs makes this selection. - -@defopt face-font-family-alternatives -If a given family is specified but does not exist, this variable -specifies alternative font families to try. Each element should have -this form: - -@example -(@var{family} @var{alternate-families}@dots{}) -@end example - -If @var{family} is specified but not available, Emacs will try the other -families given in @var{alternate-families}, one by one, until it finds a -family that does exist. -@end defopt - -@defopt face-font-selection-order -If there is no font that exactly matches all desired face attributes -(@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}), -this variable specifies the order in which these attributes should be -considered when selecting the closest matching font. The value should -be a list containing those four attribute symbols, in order of -decreasing importance. The default is @code{(:width :height :weight -:slant)}. - -Font selection first finds the best available matches for the first -attribute in the list; then, among the fonts which are best in that -way, it searches for the best matches in the second attribute, and so -on. - -The attributes @code{:weight} and @code{:width} have symbolic values in -a range centered around @code{normal}. Matches that are more extreme -(farther from @code{normal}) are somewhat preferred to matches that are -less extreme (closer to @code{normal}); this is designed to ensure that -non-normal faces contrast with normal ones, whenever possible. - -One example of a case where this variable makes a difference is when the -default font has no italic equivalent. With the default ordering, the -@code{italic} face will use a non-italic font that is similar to the -default one. But if you put @code{:slant} before @code{:height}, the -@code{italic} face will use an italic font, even if its height is not -quite right. -@end defopt - -@defopt face-font-registry-alternatives -This variable lets you specify alternative font registries to try, if a -given registry is specified and doesn't exist. Each element should have -this form: - -@example -(@var{registry} @var{alternate-registries}@dots{}) -@end example - -If @var{registry} is specified but not available, Emacs will try the -other registries given in @var{alternate-registries}, one by one, -until it finds a registry that does exist. -@end defopt - - Emacs can make use of scalable fonts, but by default it does not use -them. - -@defopt scalable-fonts-allowed -This variable controls which scalable fonts to use. A value of -@code{nil}, the default, means do not use scalable fonts. @code{t} -means to use any scalable font that seems appropriate for the text. - -Otherwise, the value must be a list of regular expressions. Then a -scalable font is enabled for use if its name matches any regular -expression in the list. For example, - -@example -(setq scalable-fonts-allowed '("muleindian-2$")) -@end example - -@noindent -allows the use of scalable fonts with registry @code{muleindian-2}. -@end defopt - -@defvar face-font-rescale-alist -This variable specifies scaling for certain faces. Its value should -be a list of elements of the form - -@example -(@var{fontname-regexp} . @var{scale-factor}) -@end example - -If @var{fontname-regexp} matches the font name that is about to be -used, this says to choose a larger similar font according to the -factor @var{scale-factor}. You would use this feature to normalize -the font size if certain fonts are bigger or smaller than their -nominal heights and widths would suggest. -@end defvar - -@node Font Lookup -@subsection Looking Up Fonts - -@defun x-list-fonts name &optional reference-face frame maximum width -This function returns a list of available font names that match -@var{name}. @var{name} should be a string containing a font name in -either the Fontconfig, GTK, or XLFD format (@pxref{Fonts,,, emacs, The -GNU Emacs Manual}). Within an XLFD string, wildcard characters may be -used: the @samp{*} character matches any substring, and the @samp{?} -character matches any single character. Case is ignored when matching -font names. - -If the optional arguments @var{reference-face} and @var{frame} are -specified, the returned list includes only fonts that are the same -size as @var{reference-face} (a face name) currently is on the frame -@var{frame}. - -The optional argument @var{maximum} sets a limit on how many fonts to -return. If it is non-@code{nil}, then the return value is truncated -after the first @var{maximum} matching fonts. Specifying a small -value for @var{maximum} can make this function much faster, in cases -where many fonts match the pattern. - -The optional argument @var{width} specifies a desired font width. If -it is non-@code{nil}, the function only returns those fonts whose -characters are (on average) @var{width} times as wide as -@var{reference-face}. -@end defun - -@defun x-family-fonts &optional family frame -This function returns a list describing the available fonts for family -@var{family} on @var{frame}. If @var{family} is omitted or @code{nil}, -this list applies to all families, and therefore, it contains all -available fonts. Otherwise, @var{family} must be a string; it may -contain the wildcards @samp{?} and @samp{*}. - -The list describes the display that @var{frame} is on; if @var{frame} is -omitted or @code{nil}, it applies to the selected frame's display -(@pxref{Input Focus}). - -Each element in the list is a vector of the following form: - -@example -[@var{family} @var{width} @var{point-size} @var{weight} @var{slant} - @var{fixed-p} @var{full} @var{registry-and-encoding}] -@end example - -The first five elements correspond to face attributes; if you -specify these attributes for a face, it will use this font. - -The last three elements give additional information about the font. -@var{fixed-p} is non-@code{nil} if the font is fixed-pitch. -@var{full} is the full name of the font, and -@var{registry-and-encoding} is a string giving the registry and -encoding of the font. -@end defun - -@defvar font-list-limit -This variable specifies maximum number of fonts to consider in font -matching. The function @code{x-family-fonts} will not return more than -that many fonts, and font selection will consider only that many fonts -when searching a matching font for face attributes. The default is -currently 100. -@end defvar - -@node Fontsets -@subsection Fontsets - - A @dfn{fontset} is a list of fonts, each assigned to a range of -character codes. An individual font cannot display the whole range of -characters that Emacs supports, but a fontset can. Fontsets have names, -just as fonts do, and you can use a fontset name in place of a font name -when you specify the ``font'' for a frame or a face. Here is -information about defining a fontset under Lisp program control. - -@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror -This function defines a new fontset according to the specification -string @var{fontset-spec}. The string should have this format: - -@smallexample -@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}} -@end smallexample - -@noindent -Whitespace characters before and after the commas are ignored. - -The first part of the string, @var{fontpattern}, should have the form of -a standard X font name, except that the last two fields should be -@samp{fontset-@var{alias}}. - -The new fontset has two names, one long and one short. The long name is -@var{fontpattern} in its entirety. The short name is -@samp{fontset-@var{alias}}. You can refer to the fontset by either -name. If a fontset with the same name already exists, an error is -signaled, unless @var{noerror} is non-@code{nil}, in which case this -function does nothing. - -If optional argument @var{style-variant-p} is non-@code{nil}, that says -to create bold, italic and bold-italic variants of the fontset as well. -These variant fontsets do not have a short name, only a long one, which -is made by altering @var{fontpattern} to indicate the bold or italic -status. - -The specification string also says which fonts to use in the fontset. -See below for the details. -@end defun - - The construct @samp{@var{charset}:@var{font}} specifies which font to -use (in this fontset) for one particular character set. Here, -@var{charset} is the name of a character set, and @var{font} is the font -to use for that character set. You can use this construct any number of -times in the specification string. - - For the remaining character sets, those that you don't specify -explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces -@samp{fontset-@var{alias}} with a value that names one character set. -For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced -with @samp{ISO8859-1}. - - In addition, when several consecutive fields are wildcards, Emacs -collapses them into a single wildcard. This is to prevent use of -auto-scaled fonts. Fonts made by scaling larger fonts are not usable -for editing, and scaling a smaller font is not useful because it is -better to use the smaller font in its own size, which Emacs does. - - Thus if @var{fontpattern} is this, - -@example --*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 -@end example - -@noindent -the font specification for @acronym{ASCII} characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-ISO8859-1 -@end example - -@noindent -and the font specification for Chinese GB2312 characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-gb2312*-* -@end example - - You may not have any Chinese font matching the above font -specification. Most X distributions include only Chinese fonts that -have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In -such a case, @samp{Fontset-@var{n}} can be specified as below: - -@smallexample -Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ - chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* -@end smallexample - -@noindent -Then, the font specifications for all but Chinese GB2312 characters have -@samp{fixed} in the @var{family} field, and the font specification for -Chinese GB2312 characters has a wild card @samp{*} in the @var{family} -field. - -@defun set-fontset-font name character font-spec &optional frame add -This function modifies the existing fontset @var{name} to use the font -matching with @var{font-spec} for the character @var{character}. - -If @var{name} is @code{nil}, this function modifies the fontset of the -selected frame or that of @var{frame} if @var{frame} is not -@code{nil}. - -If @var{name} is @code{t}, this function modifies the default -fontset, whose short name is @samp{fontset-default}. - -@var{character} may be a cons; @code{(@var{from} . @var{to})}, where -@var{from} and @var{to} are character codepoints. In that case, use -@var{font-spec} for all characters in the range @var{from} and @var{to} -(inclusive). - -@var{character} may be a charset. In that case, use -@var{font-spec} for all character in the charsets. - -@var{character} may be a script name. In that case, use -@var{font-spec} for all character in the charsets. - -@var{font-spec} may be a cons; @code{(@var{family} . @var{registry})}, -where @var{family} is a family name of a font (possibly including a -foundry name at the head), @var{registry} is a registry name of a font -(possibly including an encoding name at the tail). - -@var{font-spec} may be a font name string. - -The optional argument @var{add}, if non-@code{nil}, specifies how to -add @var{font-spec} to the font specifications previously set. If it -is @code{prepend}, @var{font-spec} is prepended. If it is -@code{append}, @var{font-spec} is appended. By default, -@var{font-spec} overrides the previous settings. - -For instance, this changes the default fontset to use a font of which -family name is @samp{Kochi Gothic} for all characters belonging to -the charset @code{japanese-jisx0208}. - -@smallexample -(set-fontset-font t 'japanese-jisx0208 - (font-spec :family "Kochi Gothic")) -@end smallexample -@end defun - -@defun char-displayable-p char -This function returns @code{t} if Emacs ought to be able to display -@var{char}. More precisely, if the selected frame's fontset has a -font to display the character set that @var{char} belongs to. - -Fontsets can specify a font on a per-character basis; when the fontset -does that, this function's value may not be accurate. -@end defun - -@node Low-Level Font -@subsection Low-Level Font Representation - - Normally, it is not necessary to manipulate fonts directly. In case -you need to do so, this section explains how. - - In Emacs Lisp, fonts are represented using three different Lisp -object types: @dfn{font objects}, @dfn{font specs}, and @dfn{font -entities}. - -@defun fontp object &optional type -Return @code{t} if @var{object} is a font object, font spec, or font -entity. Otherwise, return @code{nil}. - -The optional argument @var{type}, if non-@code{nil}, determines the -exact type of Lisp object to check for. In that case, @var{type} -should be one of @code{font-object}, @code{font-spec}, or -@code{font-entity}. -@end defun - - A font object is a Lisp object that represents a font that Emacs has -@dfn{opened}. Font objects cannot be modified in Lisp, but they can -be inspected. - -@defun font-at position &optional window string -Return the font object that is being used to display the character at -position @var{position} in the window @var{window}. If @var{window} -is @code{nil}, it defaults to the selected window. If @var{string} is -@code{nil}, @var{position} specifies a position in the current buffer; -otherwise, @var{string} should be a string, and @var{position} -specifies a position in that string. -@end defun - - A font spec is a Lisp object that contains a set of specifications -that can be used to find a font. More than one font may match the -specifications in a font spec. - -@defun font-spec &rest arguments -Return a new font spec using the specifications in @var{arguments}, -which should come in @code{property}-@code{value} pairs. The possible -specifications are as follows: - -@table @code -@item :name -The font name (a string), in either XLFD, Fontconfig, or GTK format. -@xref{Fonts,,, emacs, The GNU Emacs Manual}. - -@item :family -@itemx :foundry -@itemx :weight -@itemx :slant -@itemx :width -These have the same meanings as the face attributes of the same name. -@xref{Face Attributes}. - -@item :size -The font size---either a non-negative integer that specifies the pixel -size, or a floating point number that specifies the point size. - -@item :adstyle -Additional typographic style information for the font, such as -@samp{sans}. The value should be a string or a symbol. - -@item :registry -The charset registry and encoding of the font, such as -@samp{iso8859-1}. The value should be a string or a symbol. - -@item :script -The script that the font must support (a symbol). - -@item :otf -The font must be an OpenType font that supports these OpenType -features, provided Emacs is compiled with support for @samp{libotf} (a -library for performing complex text layout in certain scripts). The -value must be a list of the form - -@smallexample -@code{(@var{script-tag} @var{langsys-tag} @var{gsub} @var{gpos})} -@end smallexample - -where @var{script-tag} is the OpenType script tag symbol; -@var{langsys-tag} is the OpenType language system tag symbol, or -@code{nil} to use the default language system; @code{gsub} is a list -of OpenType GSUB feature tag symbols, or @code{nil} if none is -required; and @code{gpos} is a list of OpenType GPOS feature tag -symbols, or @code{nil} if none is required. If @code{gsub} or -@code{gpos} is a list, a @code{nil} element in that list means that -the font must not match any of the remaining tag symbols. The -@code{gpos} element may be omitted. -@end table -@end defun - -@defun font-put font-spec property value -Set the font property @var{property} in the font-spec @var{font-spec} -to @var{value}. -@end defun - - A font entity is a reference to a font that need not be open. Its -properties are intermediate between a font object and a font spec: -like a font object, and unlike a font spec, it refers to a single, -specific font. Unlike a font object, creating a font entity does not -load the contents of that font into computer memory. - -@defun find-font font-spec &optional frame -This function returns a font entity that best matches the font spec -@var{font-spec} on frame @var{frame}. If @var{frame} is @code{nil}, -it defaults to the selected frame. -@end defun - -@defun list-fonts font-spec &optional frame num prefer -This function returns a list of all font entities that match the font -spec @var{font-spec}. - -The optional argument @var{frame}, if non-@code{nil}, specifies the -frame on which the fonts are to be displayed. The optional argument -@var{num}, if non-@code{nil}, should be an integer that specifies the -maximum length of the returned list. The optional argument -@var{prefer}, if non-@code{nil}, should be another font spec, which is -used to control the order of the returned list; the returned font -entities are sorted in order of decreasing ``closeness'' to that font -spec. -@end defun - - If you call @code{set-face-attribute} and pass a font spec, font -entity, or font name string as the value of the @code{:font} -attribute, Emacs opens the best ``matching'' font that is available -for display. It then stores the corresponding font object as the -actual value of the @code{:font} attribute for that face. - - The following functions can be used to obtain information about a -font. For these functions, the @var{font} argument can be a font -object, a font entity, or a font spec. - -@defun font-get font property -This function returns the value of the font property @var{property} -for @var{font}. - -If @var{font} is a font spec and the font spec does not specify -@var{property}, the return value is @code{nil}. If @var{font} is a -font object or font entity, the value for the @var{:script} property -may be a list of scripts supported by the font. -@end defun - -@defun font-face-attributes font &optional frame -This function returns a list of face attributes corresponding to -@var{font}. The optional argument @var{frame} specifies the frame on -which the font is to be displayed. If it is @code{nil}, the selected -frame is used. The return value has the form - -@smallexample -(:family @var{family} :height @var{height} :weight @var{weight} - :slant @var{slant} :width @var{width}) -@end smallexample - -where the values of @var{family}, @var{height}, @var{weight}, -@var{slant}, and @var{width} are face attribute values. Some of these -key-attribute pairs may be omitted from the list if they are not -specified by @var{font}. -@end defun - -@defun font-xlfd-name font &optional fold-wildcards -This function returns the XLFD (X Logical Font Descriptor), a string, -matching @var{font}. @xref{Fonts,,, emacs, The GNU Emacs Manual}, for -information about XLFDs. If the name is too long for an XLFD (which -can contain at most 255 characters), the function returns @code{nil}. - -If the optional argument @var{fold-wildcards} is non-@code{nil}, -consecutive wildcards in the XLFD are folded into one. -@end defun - -@node Fringes -@section Fringes -@cindex fringes - - On graphical displays, Emacs draws @dfn{fringes} next to each -window: thin vertical strips down the sides which can display bitmaps -indicating truncation, continuation, horizontal scrolling, and so on. - -@menu -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. -@end menu - -@node Fringe Size/Pos -@subsection Fringe Size and Position - - The following buffer-local variables control the position and width -of fringes in windows showing that buffer. - -@defvar fringes-outside-margins -The fringes normally appear between the display margins and the window -text. If the value is non-@code{nil}, they appear outside the display -margins. @xref{Display Margins}. -@end defvar - -@defvar left-fringe-width -This variable, if non-@code{nil}, specifies the width of the left -fringe in pixels. A value of @code{nil} means to use the left fringe -width from the window's frame. -@end defvar - -@defvar right-fringe-width -This variable, if non-@code{nil}, specifies the width of the right -fringe in pixels. A value of @code{nil} means to use the right fringe -width from the window's frame. -@end defvar - - Any buffer which does not specify values for these variables uses -the values specified by the @code{left-fringe} and @code{right-fringe} -frame parameters (@pxref{Layout Parameters}). - - The above variables actually take effect via the function -@code{set-window-buffer} (@pxref{Buffers and Windows}), which calls -@code{set-window-fringes} as a subroutine. If you change one of these -variables, the fringe display is not updated in existing windows -showing the buffer, unless you call @code{set-window-buffer} again in -each affected window. You can also use @code{set-window-fringes} to -control the fringe display in individual windows. - -@defun set-window-fringes window left &optional right outside-margins -This function sets the fringe widths of window @var{window}. -If @var{window} is @code{nil}, the selected window is used. - -The argument @var{left} specifies the width in pixels of the left -fringe, and likewise @var{right} for the right fringe. A value of -@code{nil} for either one stands for the default width. If -@var{outside-margins} is non-@code{nil}, that specifies that fringes -should appear outside of the display margins. -@end defun - -@defun window-fringes &optional window -This function returns information about the fringes of a window -@var{window}. If @var{window} is omitted or @code{nil}, the selected -window is used. The value has the form @code{(@var{left-width} -@var{right-width} @var{outside-margins})}. -@end defun - - -@node Fringe Indicators -@subsection Fringe Indicators -@cindex fringe indicators -@cindex indicators, fringe - - @dfn{Fringe indicators} are tiny icons displayed in the window -fringe to indicate truncated or continued lines, buffer boundaries, -etc. - -@defopt indicate-empty-lines -@cindex fringes, and empty line indication -When this is non-@code{nil}, Emacs displays a special glyph in the -fringe of each empty line at the end of the buffer, on graphical -displays. @xref{Fringes}. This variable is automatically -buffer-local in every buffer. -@end defopt - -@defopt indicate-buffer-boundaries -This buffer-local variable controls how the buffer boundaries and -window scrolling are indicated in the window fringes. - -Emacs can indicate the buffer boundaries---that is, the first and last -line in the buffer---with angle icons when they appear on the screen. -In addition, Emacs can display an up-arrow in the fringe to show -that there is text above the screen, and a down-arrow to show -there is text below the screen. - -There are three kinds of basic values: - -@table @asis -@item @code{nil} -Don't display any of these fringe icons. -@item @code{left} -Display the angle icons and arrows in the left fringe. -@item @code{right} -Display the angle icons and arrows in the right fringe. -@item any non-alist -Display the angle icons in the left fringe -and don't display the arrows. -@end table - -Otherwise the value should be an alist that specifies which fringe -indicators to display and where. Each element of the alist should -have the form @code{(@var{indicator} . @var{position})}. Here, -@var{indicator} is one of @code{top}, @code{bottom}, @code{up}, -@code{down}, and @code{t} (which covers all the icons not yet -specified), while @var{position} is one of @code{left}, @code{right} -and @code{nil}. - -For example, @code{((top . left) (t . right))} places the top angle -bitmap in left fringe, and the bottom angle bitmap as well as both -arrow bitmaps in right fringe. To show the angle bitmaps in the left -fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}. -@end defopt - -@defvar fringe-indicator-alist -This buffer-local variable specifies the mapping from logical fringe -indicators to the actual bitmaps displayed in the window fringes. The -value is an alist of elements @code{(@var{indicator} -. @var{bitmaps})}, where @var{indicator} specifies a logical indicator -type and @var{bitmaps} specifies the fringe bitmaps to use for that -indicator. - - Each @var{indicator} should be one of the following symbols: - -@table @asis -@item @code{truncation}, @code{continuation}. -Used for truncation and continuation lines. - -@item @code{up}, @code{down}, @code{top}, @code{bottom}, @code{top-bottom} -Used when @code{indicate-buffer-boundaries} is non-@code{nil}: -@code{up} and @code{down} indicate a buffer boundary lying above or -below the window edge; @code{top} and @code{bottom} indicate the -topmost and bottommost buffer text line; and @code{top-bottom} -indicates where there is just one line of text in the buffer. - -@item @code{empty-line} -Used to indicate empty lines when @code{indicate-empty-lines} is -non-@code{nil}. - -@item @code{overlay-arrow} -Used for overlay arrows (@pxref{Overlay Arrow}). -@c Is this used anywhere? -@c @item Unknown bitmap indicator: -@c @code{unknown}. -@end table - - Each @var{bitmaps} value may be a list of symbols @code{(@var{left} -@var{right} [@var{left1} @var{right1}])}. The @var{left} and -@var{right} symbols specify the bitmaps shown in the left and/or right -fringe, for the specific indicator. @var{left1} and @var{right1} are -specific to the @code{bottom} and @code{top-bottom} indicators, and -are used to indicate that the last text line has no final newline. -Alternatively, @var{bitmaps} may be a single symbol which is used in -both left and right fringes. - - @xref{Fringe Bitmaps}, for a list of standard bitmap symbols and how -to define your own. In addition, @code{nil} represents the empty -bitmap (i.e.@: an indicator that is not shown). - - When @code{fringe-indicator-alist} has a buffer-local value, and -there is no bitmap defined for a logical indicator, or the bitmap is -@code{t}, the corresponding value from the default value of -@code{fringe-indicator-alist} is used. -@end defvar - -@node Fringe Cursors -@subsection Fringe Cursors -@cindex fringe cursors -@cindex cursor, fringe - - When a line is exactly as wide as the window, Emacs displays the -cursor in the right fringe instead of using two lines. Different -bitmaps are used to represent the cursor in the fringe depending on -the current buffer's cursor type. - -@defopt overflow-newline-into-fringe -If this is non-@code{nil}, lines exactly as wide as the window (not -counting the final newline character) are not continued. Instead, -when point is at the end of the line, the cursor appears in the right -fringe. -@end defopt - -@defvar fringe-cursor-alist -This variable specifies the mapping from logical cursor type to the -actual fringe bitmaps displayed in the right fringe. The value is an -alist where each element has the form @code{(@var{cursor-type} -. @var{bitmap})}, which means to use the fringe bitmap @var{bitmap} to -display cursors of type @var{cursor-type}. - -Each @var{cursor-type} should be one of @code{box}, @code{hollow}, -@code{bar}, @code{hbar}, or @code{hollow-small}. The first four have -the same meanings as in the @code{cursor-type} frame parameter -(@pxref{Cursor Parameters}). The @code{hollow-small} type is used -instead of @code{hollow} when the normal @code{hollow-rectangle} -bitmap is too tall to fit on a specific display line. - -Each @var{bitmap} should be a symbol specifying the fringe bitmap to -be displayed for that logical cursor type. -@iftex -See the next subsection for details. -@end iftex -@ifnottex -@xref{Fringe Bitmaps}. -@end ifnottex - -When @code{fringe-cursor-alist} has a buffer-local value, and there is -no bitmap defined for a cursor type, the corresponding value from the -default value of @code{fringes-indicator-alist} is used. -@end defvar - -@node Fringe Bitmaps -@subsection Fringe Bitmaps -@cindex fringe bitmaps -@cindex bitmaps, fringe - - The @dfn{fringe bitmaps} are the actual bitmaps which represent the -logical fringe indicators for truncated or continued lines, buffer -boundaries, overlay arrows, etc. Each bitmap is represented by a -symbol. -@iftex -These symbols are referred to by the variables -@code{fringe-indicator-alist} and @code{fringe-cursor-alist}, -described in the previous subsections. -@end iftex -@ifnottex -These symbols are referred to by the variable -@code{fringe-indicator-alist}, which maps fringe indicators to bitmaps -(@pxref{Fringe Indicators}), and the variable -@code{fringe-cursor-alist}, which maps fringe cursors to bitmaps -(@pxref{Fringe Cursors}). -@end ifnottex - - Lisp programs can also directly display a bitmap in the left or -right fringe, by using a @code{display} property for one of the -characters appearing in the line (@pxref{Other Display Specs}). Such -a display specification has the form - -@example -(@var{fringe} @var{bitmap} [@var{face}]) -@end example - -@noindent -@var{fringe} is either the symbol @code{left-fringe} or -@code{right-fringe}. @var{bitmap} is a symbol identifying the bitmap -to display. The optional @var{face} names a face whose foreground -color is used to display the bitmap; this face is automatically merged -with the @code{fringe} face. - - Here is a list of the standard fringe bitmaps defined in Emacs, and -how they are currently used in Emacs (via -@code{fringe-indicator-alist} and @code{fringe-cursor-alist}): - -@table @asis -@item @code{left-arrow}, @code{right-arrow} -Used to indicate truncated lines. - -@item @code{left-curly-arrow}, @code{right-curly-arrow} -Used to indicate continued lines. - -@item @code{right-triangle}, @code{left-triangle} -The former is used by overlay arrows. The latter is unused. - -@item @code{up-arrow}, @code{down-arrow}, @code{top-left-angle} @code{top-right-angle} -@itemx @code{bottom-left-angle}, @code{bottom-right-angle} -@itemx @code{top-right-angle}, @code{top-left-angle} -@itemx @code{left-bracket}, @code{right-bracket}, @code{top-right-angle}, @code{top-left-angle} -Used to indicate buffer boundaries. - -@item @code{filled-rectangle}, @code{hollow-rectangle} -@itemx @code{filled-square}, @code{hollow-square} -@itemx @code{vertical-bar}, @code{horizontal-bar} -Used for different types of fringe cursors. - -@item @code{empty-line}, @code{question-mark} -Unused. -@end table - -@noindent -The next subsection describes how to define your own fringe bitmaps. - -@defun fringe-bitmaps-at-pos &optional pos window -This function returns the fringe bitmaps of the display line -containing position @var{pos} in window @var{window}. The return -value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left} -is the symbol for the fringe bitmap in the left fringe (or @code{nil} -if no bitmap), @var{right} is similar for the right fringe, and @var{ov} -is non-@code{nil} if there is an overlay arrow in the left fringe. - -The value is @code{nil} if @var{pos} is not visible in @var{window}. -If @var{window} is @code{nil}, that stands for the selected window. -If @var{pos} is @code{nil}, that stands for the value of point in -@var{window}. -@end defun - -@node Customizing Bitmaps -@subsection Customizing Fringe Bitmaps - -@defun define-fringe-bitmap bitmap bits &optional height width align -This function defines the symbol @var{bitmap} as a new fringe bitmap, -or replaces an existing bitmap with that name. - -The argument @var{bits} specifies the image to use. It should be -either a string or a vector of integers, where each element (an -integer) corresponds to one row of the bitmap. Each bit of an integer -corresponds to one pixel of the bitmap, where the low bit corresponds -to the rightmost pixel of the bitmap. - -The height is normally the length of @var{bits}. However, you -can specify a different height with non-@code{nil} @var{height}. The width -is normally 8, but you can specify a different width with non-@code{nil} -@var{width}. The width must be an integer between 1 and 16. - -The argument @var{align} specifies the positioning of the bitmap -relative to the range of rows where it is used; the default is to -center the bitmap. The allowed values are @code{top}, @code{center}, -or @code{bottom}. - -The @var{align} argument may also be a list @code{(@var{align} -@var{periodic})} where @var{align} is interpreted as described above. -If @var{periodic} is non-@code{nil}, it specifies that the rows in -@code{bits} should be repeated enough times to reach the specified -height. -@end defun - -@defun destroy-fringe-bitmap bitmap -This function destroy the fringe bitmap identified by @var{bitmap}. -If @var{bitmap} identifies a standard fringe bitmap, it actually -restores the standard definition of that bitmap, instead of -eliminating it entirely. -@end defun - -@defun set-fringe-bitmap-face bitmap &optional face -This sets the face for the fringe bitmap @var{bitmap} to @var{face}. -If @var{face} is @code{nil}, it selects the @code{fringe} face. The -bitmap's face controls the color to draw it in. - -@var{face} is merged with the @code{fringe} face, so normally -@var{face} should specify only the foreground color. -@end defun - -@node Overlay Arrow -@subsection The Overlay Arrow -@c @cindex overlay arrow Duplicates variable names - - The @dfn{overlay arrow} is useful for directing the user's attention -to a particular line in a buffer. For example, in the modes used for -interface to debuggers, the overlay arrow indicates the line of code -about to be executed. This feature has nothing to do with -@dfn{overlays} (@pxref{Overlays}). - -@defvar overlay-arrow-string -This variable holds the string to display to call attention to a -particular line, or @code{nil} if the arrow feature is not in use. -On a graphical display the contents of the string are ignored; instead a -glyph is displayed in the fringe area to the left of the display area. -@end defvar - -@defvar overlay-arrow-position -This variable holds a marker that indicates where to display the overlay -arrow. It should point at the beginning of a line. On a non-graphical -display the arrow text -appears at the beginning of that line, overlaying any text that would -otherwise appear. Since the arrow is usually short, and the line -usually begins with indentation, normally nothing significant is -overwritten. - -The overlay-arrow string is displayed in any given buffer if the value -of @code{overlay-arrow-position} in that buffer points into that -buffer. Thus, it is possible to display multiple overlay arrow strings -by creating buffer-local bindings of @code{overlay-arrow-position}. -However, it is usually cleaner to use -@code{overlay-arrow-variable-list} to achieve this result. -@c !!! overlay-arrow-position: but the overlay string may remain in the display -@c of some other buffer until an update is required. This should be fixed -@c now. Is it? -@end defvar - - You can do a similar job by creating an overlay with a -@code{before-string} property. @xref{Overlay Properties}. - - You can define multiple overlay arrows via the variable -@code{overlay-arrow-variable-list}. - -@defvar overlay-arrow-variable-list -This variable's value is a list of variables, each of which specifies -the position of an overlay arrow. The variable -@code{overlay-arrow-position} has its normal meaning because it is on -this list. -@end defvar - -Each variable on this list can have properties -@code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that -specify an overlay arrow string (for text terminals) or fringe bitmap -(for graphical terminals) to display at the corresponding overlay -arrow position. If either property is not set, the default -@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator -is used. - -@node Scroll Bars -@section Scroll Bars -@cindex scroll bars - -Normally the frame parameter @code{vertical-scroll-bars} controls -whether the windows in the frame have vertical scroll bars, and -whether they are on the left or right. The frame parameter -@code{scroll-bar-width} specifies how wide they are (@code{nil} -meaning the default). @xref{Layout Parameters}. - -@defun frame-current-scroll-bars &optional frame -This function reports the scroll bar type settings for frame -@var{frame}. The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}, where -@var{vertical-type} is either @code{left}, @code{right}, or @code{nil} -(which means no scroll bar.) @var{horizontal-type} is meant to -specify the horizontal scroll bar type, but since they are not -implemented, it is always @code{nil}. -@end defun - -@vindex vertical-scroll-bar - You can enable or disable scroll bars for a particular buffer, -by setting the variable @code{vertical-scroll-bar}. This variable -automatically becomes buffer-local when set. The possible values are -@code{left}, @code{right}, @code{t}, which means to use the -frame's default, and @code{nil} for no scroll bar. - - You can also control this for individual windows. Call the function -@code{set-window-scroll-bars} to specify what to do for a specific window: - -@defun set-window-scroll-bars window width &optional vertical-type horizontal-type -This function sets the width and type of scroll bars for window -@var{window}. - -@var{width} specifies the scroll bar width in pixels (@code{nil} means -use the width specified for the frame). @var{vertical-type} specifies -whether to have a vertical scroll bar and, if so, where. The possible -values are @code{left}, @code{right} and @code{nil}, just like the -values of the @code{vertical-scroll-bars} frame parameter. - -The argument @var{horizontal-type} is meant to specify whether and -where to have horizontal scroll bars, but since they are not -implemented, it has no effect. If @var{window} is @code{nil}, the -selected window is used. -@end defun - -@defun window-scroll-bars &optional window -Report the width and type of scroll bars specified for @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a list of the form @code{(@var{width} -@var{cols} @var{vertical-type} @var{horizontal-type})}. The value -@var{width} is the value that was specified for the width (which may -be @code{nil}); @var{cols} is the number of columns that the scroll -bar actually occupies. - -@var{horizontal-type} is not actually meaningful. -@end defun - -If you don't specify these values for a window with -@code{set-window-scroll-bars}, the buffer-local variables -@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being -displayed control the window's vertical scroll bars. The function -@code{set-window-buffer} examines these variables. If you change them -in a buffer that is already visible in a window, you can make the -window take note of the new values by calling @code{set-window-buffer} -specifying the same buffer that is already displayed. - -@defopt scroll-bar-mode -This variable, always local in all buffers, controls whether and where -to put scroll bars in windows displaying the buffer. The possible values -are @code{nil} for no scroll bar, @code{left} to put a scroll bar on -the left, and @code{right} to put a scroll bar on the right. -@end defopt - -@defun window-current-scroll-bars &optional window -This function reports the scroll bar type for window @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike -@code{window-scroll-bars}, this reports the scroll bar type actually -used, once frame defaults and @code{scroll-bar-mode} are taken into -account. -@end defun - -@defvar scroll-bar-width -This variable, always local in all buffers, specifies the width of the -buffer's scroll bars, measured in pixels. A value of @code{nil} means -to use the value specified by the frame. -@end defvar - -@node Display Property -@section The @code{display} Property -@cindex display specification -@kindex display @r{(text property)} - - The @code{display} text property (or overlay property) is used to -insert images into text, and to control other aspects of how text -displays. The value of the @code{display} property should be a -display specification, or a list or vector containing several display -specifications. Display specifications in the same @code{display} -property value generally apply in parallel to the text they cover. - - If several sources (overlays and/or a text property) specify values -for the @code{display} property, only one of the values takes effect, -following the rules of @code{get-char-property}. @xref{Examining -Properties}. - - The rest of this section describes several kinds of -display specifications and what they mean. - -@menu -* Replacing Specs:: Display specs that replace the text. -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; adjusting the height, - spacing, and other properties of text. -* Display Margins:: Displaying text or images to the side of the main text. -@end menu - -@node Replacing Specs -@subsection Display Specs That Replace The Text - - Some kinds of display specifications specify something to display -instead of the text that has the property. These are called -@dfn{replacing} display specifications. Emacs does not allow the user -to interactively move point into the middle of buffer text that is -replaced in this way. - - If a list of display specifications includes more than one replacing -display specification, the first overrides the rest. Replacing -display specifications make most other display specifications -irrelevant, since those don't apply to the replacement. - - For replacing display specifications, ``the text that has the -property'' means all the consecutive characters that have the same -Lisp object as their @code{display} property; these characters are -replaced as a single unit. If two characters have different Lisp -objects as their @code{display} properties (i.e.@: objects which are -not @code{eq}), they are handled separately. - - Here is an example which illustrates this point. A string serves as -a replacing display specification, which replaces the text that has -the property with the specified string (@pxref{Other Display Specs}). -Consider the following function: - -@smallexample -(defun foo () - (dotimes (i 5) - (let ((string (concat "A")) - (start (+ i i (point-min)))) - (put-text-property start (1+ start) 'display string) - (put-text-property start (+ 2 start) 'display string)))) -@end smallexample - -@noindent -This function gives each of the first ten characters in the buffer a -@code{display} property which is a string @code{"A"}, but they don't -all get the same string object. The first two characters get the same -string object, so they are replaced with one @samp{A}; the fact that -the display property was assigned in two separate calls to -@code{put-text-property} is irrelevant. Similarly, the next two -characters get a second string (@code{concat} creates a new string -object), so they are replaced with one @samp{A}; and so on. Thus, the -ten characters appear as five A's. - -@node Specified Space -@subsection Specified Spaces -@cindex spaces, specified height or width -@cindex variable-width spaces - - To display a space of specified width and/or height, use a display -specification of the form @code{(space . @var{props})}, where -@var{props} is a property list (a list of alternating properties and -values). You can put this property on one or more consecutive -characters; a space of the specified height and width is displayed in -place of @emph{all} of those characters. These are the properties you -can use in @var{props} to specify the weight of the space: - -@table @code -@item :width @var{width} -If @var{width} is an integer or floating point number, it specifies -that the space width should be @var{width} times the normal character -width. @var{width} can also be a @dfn{pixel width} specification -(@pxref{Pixel Specification}). - -@item :relative-width @var{factor} -Specifies that the width of the stretch should be computed from the -first character in the group of consecutive characters that have the -same @code{display} property. The space width is the width of that -character, multiplied by @var{factor}. - -@item :align-to @var{hpos} -Specifies that the space should be wide enough to reach @var{hpos}. -If @var{hpos} is a number, it is measured in units of the normal -character width. @var{hpos} can also be a @dfn{pixel width} -specification (@pxref{Pixel Specification}). -@end table - - You should use one and only one of the above properties. You can -also specify the height of the space, with these properties: - -@table @code -@item :height @var{height} -Specifies the height of the space. -If @var{height} is an integer or floating point number, it specifies -that the space height should be @var{height} times the normal character -height. The @var{height} may also be a @dfn{pixel height} specification -(@pxref{Pixel Specification}). - -@item :relative-height @var{factor} -Specifies the height of the space, multiplying the ordinary height -of the text having this display specification by @var{factor}. - -@item :ascent @var{ascent} -If the value of @var{ascent} is a non-negative number no greater than -100, it specifies that @var{ascent} percent of the height of the space -should be considered as the ascent of the space---that is, the part -above the baseline. The ascent may also be specified in pixel units -with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}). - -@end table - - Don't use both @code{:height} and @code{:relative-height} together. - - The @code{:width} and @code{:align-to} properties are supported on -non-graphic terminals, but the other space properties in this section -are not. - - Note that space properties are treated as paragraph separators for -the purposes of reordering bidirectional text for display. -@xref{Bidirectional Display}, for the details. - -@node Pixel Specification -@subsection Pixel Specification for Spaces -@cindex spaces, pixel specification - - The value of the @code{:width}, @code{:align-to}, @code{:height}, -and @code{:ascent} properties can be a special kind of expression that -is evaluated during redisplay. The result of the evaluation is used -as an absolute number of pixels. - - The following expressions are supported: - -@smallexample -@group - @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form} - @var{num} ::= @var{integer} | @var{float} | @var{symbol} - @var{unit} ::= in | mm | cm | width | height -@end group -@group - @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin - | scroll-bar | text - @var{pos} ::= left | center | right - @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...) - @var{op} ::= + | - -@end group -@end smallexample - - The form @var{num} specifies a fraction of the default frame font -height or width. The form @code{(@var{num})} specifies an absolute -number of pixels. If @var{num} is a symbol, @var{symbol}, its -buffer-local variable binding is used. - - The @code{in}, @code{mm}, and @code{cm} units specify the number of -pixels per inch, millimeter, and centimeter, respectively. The -@code{width} and @code{height} units correspond to the default width -and height of the current face. An image specification @code{image} -corresponds to the width or height of the image. - - The elements @code{left-fringe}, @code{right-fringe}, -@code{left-margin}, @code{right-margin}, @code{scroll-bar}, and -@code{text} specify to the width of the corresponding area of the -window. - - The @code{left}, @code{center}, and @code{right} positions can be -used with @code{:align-to} to specify a position relative to the left -edge, center, or right edge of the text area. - - Any of the above window elements (except @code{text}) can also be -used with @code{:align-to} to specify that the position is relative to -the left edge of the given area. Once the base offset for a relative -position has been set (by the first occurrence of one of these -symbols), further occurrences of these symbols are interpreted as the -width of the specified area. For example, to align to the center of -the left-margin, use - -@example -:align-to (+ left-margin (0.5 . left-margin)) -@end example - - If no specific base offset is set for alignment, it is always relative -to the left edge of the text area. For example, @samp{:align-to 0} in a -header-line aligns with the first text column in the text area. - - A value of the form @code{(@var{num} . @var{expr})} stands for the -product of the values of @var{num} and @var{expr}. For example, -@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 . -@var{image})} specifies half the width (or height) of the specified -image. - - The form @code{(+ @var{expr} ...)} adds up the value of the -expressions. The form @code{(- @var{expr} ...)} negates or subtracts -the value of the expressions. - -@node Other Display Specs -@subsection Other Display Specifications - - Here are the other sorts of display specifications that you can use -in the @code{display} text property. - -@table @code -@item @var{string} -Display @var{string} instead of the text that has this property. - -Recursive display specifications are not supported---@var{string}'s -@code{display} properties, if any, are not used. - -@item (image . @var{image-props}) -This kind of display specification is an image descriptor (@pxref{Images}). -When used as a display specification, it means to display the image -instead of the text that has the display specification. - -@item (slice @var{x} @var{y} @var{width} @var{height}) -This specification together with @code{image} specifies a @dfn{slice} -(a partial area) of the image to display. The elements @var{y} and -@var{x} specify the top left corner of the slice, within the image; -@var{width} and @var{height} specify the width and height of the -slice. Integer values are numbers of pixels. A floating point number -in the range 0.0--1.0 stands for that fraction of the width or height -of the entire image. - -@item ((margin nil) @var{string}) -A display specification of this form means to display @var{string} -instead of the text that has the display specification, at the same -position as that text. It is equivalent to using just @var{string}, -but it is done as a special case of marginal display (@pxref{Display -Margins}). - -@item (left-fringe @var{bitmap} @r{[}@var{face}@r{]}) -@itemx (right-fringe @var{bitmap} @r{[}@var{face}@r{]}) -This display specification on any character of a line of text causes -the specified @var{bitmap} be displayed in the left or right fringes -for that line, instead of the characters that have the display -specification. The optional @var{face} specifies the colors to be -used for the bitmap. @xref{Fringe Bitmaps}, for the details. - -@item (space-width @var{factor}) -This display specification affects all the space characters within the -text that has the specification. It displays all of these spaces -@var{factor} times as wide as normal. The element @var{factor} should -be an integer or float. Characters other than spaces are not affected -at all; in particular, this has no effect on tab characters. - -@item (height @var{height}) -This display specification makes the text taller or shorter. -Here are the possibilities for @var{height}: - -@table @asis -@item @code{(+ @var{n})} -This means to use a font that is @var{n} steps larger. A ``step'' is -defined by the set of available fonts---specifically, those that match -what was otherwise specified for this text, in all attributes except -height. Each size for which a suitable font is available counts as -another step. @var{n} should be an integer. - -@item @code{(- @var{n})} -This means to use a font that is @var{n} steps smaller. - -@item a number, @var{factor} -A number, @var{factor}, means to use a font that is @var{factor} times -as tall as the default font. - -@item a symbol, @var{function} -A symbol is a function to compute the height. It is called with the -current height as argument, and should return the new height to use. - -@item anything else, @var{form} -If the @var{height} value doesn't fit the previous possibilities, it is -a form. Emacs evaluates it to get the new height, with the symbol -@code{height} bound to the current specified font height. -@end table - -@item (raise @var{factor}) -This kind of display specification raises or lowers the text -it applies to, relative to the baseline of the line. - -@var{factor} must be a number, which is interpreted as a multiple of the -height of the affected text. If it is positive, that means to display -the characters raised. If it is negative, that means to display them -lower down. - -If the text also has a @code{height} display specification, that does -not affect the amount of raising or lowering, which is based on the -faces used for the text. -@end table - -@c We put all the `@code{(when ...)}' on one line to encourage -@c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot -@c was at eol; the info file ended up w/ two spaces rendered after it. - You can make any display specification conditional. To do that, -package it in another list of the form -@code{(when @var{condition} . @var{spec})}. -Then the specification @var{spec} applies only when -@var{condition} evaluates to a non-@code{nil} value. During the -evaluation, @code{object} is bound to the string or buffer having the -conditional @code{display} property. @code{position} and -@code{buffer-position} are bound to the position within @code{object} -and the buffer position where the @code{display} property was found, -respectively. Both positions can be different when @code{object} is a -string. - -@node Display Margins -@subsection Displaying in the Margins -@cindex display margins -@cindex margins, display - - A buffer can have blank areas called @dfn{display margins} on the -left and on the right. Ordinary text never appears in these areas, -but you can put things into the display margins using the -@code{display} property. There is currently no way to make text or -images in the margin mouse-sensitive. - - The way to display something in the margins is to specify it in a -margin display specification in the @code{display} property of some -text. This is a replacing display specification, meaning that the -text you put it on does not get displayed; the margin display appears, -but that text does not. - - A margin display specification looks like @code{((margin -right-margin) @var{spec})} or @code{((margin left-margin) @var{spec})}. -Here, @var{spec} is another display specification that says what to -display in the margin. Typically it is a string of text to display, -or an image descriptor. - - To display something in the margin @emph{in association with} -certain buffer text, without altering or preventing the display of -that text, put a @code{before-string} property on the text and put the -margin display specification on the contents of the before-string. - - Before the display margins can display anything, you must give -them a nonzero width. The usual way to do that is to set these -variables: - -@defvar left-margin-width -This variable specifies the width of the left margin. -It is buffer-local in all buffers. -@end defvar - -@defvar right-margin-width -This variable specifies the width of the right margin. -It is buffer-local in all buffers. -@end defvar - - Setting these variables does not immediately affect the window. These -variables are checked when a new buffer is displayed in the window. -Thus, you can make changes take effect by calling -@code{set-window-buffer}. - - You can also set the margin widths immediately. - -@defun set-window-margins window left &optional right -This function specifies the margin widths for window @var{window}. -The argument @var{left} controls the left margin and -@var{right} controls the right margin (default @code{0}). -@end defun - -@defun window-margins &optional window -This function returns the left and right margins of @var{window} -as a cons cell of the form @code{(@var{left} . @var{right})}. -If @var{window} is @code{nil}, the selected window is used. -@end defun - -@node Images -@section Images -@cindex images in buffers - - To display an image in an Emacs buffer, you must first create an image -descriptor, then use it as a display specifier in the @code{display} -property of text that is displayed (@pxref{Display Property}). - - Emacs is usually able to display images when it is run on a -graphical terminal. Images cannot be displayed in a text terminal, on -certain graphical terminals that lack the support for this, or if -Emacs is compiled without image support. You can use the function -@code{display-images-p} to determine if images can in principle be -displayed (@pxref{Display Feature Testing}). - -@menu -* Image Formats:: Supported image formats. -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* GIF Images:: Special features for GIF format. -* TIFF Images:: Special features for TIFF format. -* PostScript Images:: Special features for PostScript format. -* ImageMagick Images:: Special features available through ImageMagick. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once it is defined. -* Animated Images:: Some image formats can be animated. -* Image Cache:: Internal mechanisms of image display. -@end menu - -@node Image Formats -@subsection Image Formats -@cindex image formats -@cindex image types - - Emacs can display a number of different image formats. Some of -these image formats are supported only if particular support libraries -are installed. On some platforms, Emacs can load support libraries on -demand; if so, the variable @code{dynamic-library-alist} can be used -to modify the set of known names for these dynamic libraries. -@xref{Dynamic Libraries}. - - Supported image formats (and the required support libraries) include -PBM and XBM (which do not depend on support libraries and are always -available), XPM (@code{libXpm}), GIF (@code{libgif} or -@code{libungif}), PostScript (@code{gs}), JPEG (@code{libjpeg}), TIFF -(@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}). - - Each of these image formats is associated with an @dfn{image type -symbol}. The symbols for the above formats are, respectively, -@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{postscript}, -@code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. - - Furthermore, if you build Emacs with ImageMagick -(@code{libMagickWand}) support, Emacs can display any image format -that ImageMagick can. @xref{ImageMagick Images}. All images -displayed via ImageMagick have type symbol @code{imagemagick}. - -@defvar image-types -This variable contains a list of type symbols for image formats which -are potentially supported in the current configuration. - -``Potentially'' means that Emacs knows about the image types, not -necessarily that they can be used (for example, they could depend on -unavailable dynamic libraries). To know which image types are really -available, use @code{image-type-available-p}. -@end defvar - -@defun image-type-available-p type -This function returns non-@code{nil} if images of type @var{type} can -be loaded and displayed. @var{type} must be an image type symbol. - -For image types whose support libraries are statically linked, this -function always returns @code{t}. For image types whose support -libraries are dynamically loaded, it returns @code{t} if the library -could be loaded and @code{nil} otherwise. -@end defun - -@node Image Descriptors -@subsection Image Descriptors -@cindex image descriptor - - An @dfn{image descriptor} is a list which specifies the underlying -data for an image, and how to display it. It is typically used as the -value of a @code{display} overlay or text property (@pxref{Other -Display Specs}); but @xref{Showing Images}, for convenient helper -functions to insert images into buffers. - - Each image descriptor has the form @code{(image . @var{props})}, -where @var{props} is a property list of alternating keyword symbols -and values, including at least the pair @code{:type @var{TYPE}} which -specifies the image type. - - The following is a list of properties that are meaningful for all -image types (there are also properties which are meaningful only for -certain image types, as documented in the following subsections): - -@table @code -@item :type @var{type} -The image type. -@ifnottex -@xref{Image Formats}. -@end ifnottex -Every image descriptor must include this property. - -@item :file @var{file} -This says to load the image from file @var{file}. If @var{file} is -not an absolute file name, it is expanded in @code{data-directory}. - -@item :data @var{data} -This specifies the raw image data. Each image descriptor must have -either @code{:data} or @code{:file}, but not both. - -For most image types, the value of a @code{:data} property should be a -string containing the image data. Some image types do not support -@code{:data}; for some others, @code{:data} alone is not enough, so -you need to use other image properties along with @code{:data}. See -the following subsections for details. - -@item :margin @var{margin} -This specifies how many pixels to add as an extra margin around the -image. The value, @var{margin}, must be a non-negative number, or a -pair @code{(@var{x} . @var{y})} of such numbers. If it is a pair, -@var{x} specifies how many pixels to add horizontally, and @var{y} -specifies how many pixels to add vertically. If @code{:margin} is not -specified, the default is zero. - -@item :ascent @var{ascent} -This specifies the amount of the image's height to use for its -ascent---that is, the part above the baseline. The value, -@var{ascent}, must be a number in the range 0 to 100, or the symbol -@code{center}. - -If @var{ascent} is a number, that percentage of the image's height is -used for its ascent. - -If @var{ascent} is @code{center}, the image is vertically centered -around a centerline which would be the vertical centerline of text drawn -at the position of the image, in the manner specified by the text -properties and overlays that apply to the image. - -If this property is omitted, it defaults to 50. - -@item :relief @var{relief} -This adds a shadow rectangle around the image. The value, -@var{relief}, specifies the width of the shadow lines, in pixels. If -@var{relief} is negative, shadows are drawn so that the image appears -as a pressed button; otherwise, it appears as an unpressed button. - -@item :conversion @var{algorithm} -This specifies a conversion algorithm that should be applied to the -image before it is displayed; the value, @var{algorithm}, specifies -which algorithm. - -@table @code -@item laplace -@itemx emboss -Specifies the Laplace edge detection algorithm, which blurs out small -differences in color while highlighting larger differences. People -sometimes consider this useful for displaying the image for a -``disabled'' button. - -@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust}) -Specifies a general edge-detection algorithm. @var{matrix} must be -either a nine-element list or a nine-element vector of numbers. A pixel -at position @math{x/y} in the transformed image is computed from -original pixels around that position. @var{matrix} specifies, for each -pixel in the neighborhood of @math{x/y}, a factor with which that pixel -will influence the transformed pixel; element @math{0} specifies the -factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for -the pixel at @math{x/y-1} etc., as shown below: -@iftex -@tex -$$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr - x-1/y & x/y & x+1/y \cr - x-1/y+1& x/y+1 & x+1/y+1 \cr}$$ -@end tex -@end iftex -@ifnottex -@display - (x-1/y-1 x/y-1 x+1/y-1 - x-1/y x/y x+1/y - x-1/y+1 x/y+1 x+1/y+1) -@end display -@end ifnottex - -The resulting pixel is computed from the color intensity of the color -resulting from summing up the RGB values of surrounding pixels, -multiplied by the specified factors, and dividing that sum by the sum -of the factors' absolute values. - -Laplace edge-detection currently uses a matrix of -@iftex -@tex -$$\pmatrix{1 & 0 & 0 \cr - 0& 0 & 0 \cr - 0 & 0 & -1 \cr}$$ -@end tex -@end iftex -@ifnottex -@display - (1 0 0 - 0 0 0 - 0 0 -1) -@end display -@end ifnottex - -Emboss edge-detection uses a matrix of -@iftex -@tex -$$\pmatrix{ 2 & -1 & 0 \cr - -1 & 0 & 1 \cr - 0 & 1 & -2 \cr}$$ -@end tex -@end iftex -@ifnottex -@display - ( 2 -1 0 - -1 0 1 - 0 1 -2) -@end display -@end ifnottex - -@item disabled -Specifies transforming the image so that it looks ``disabled''. -@end table - -@item :mask @var{mask} -If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build -a clipping mask for the image, so that the background of a frame is -visible behind the image. If @var{bg} is not specified, or if @var{bg} -is @code{t}, determine the background color of the image by looking at -the four corners of the image, assuming the most frequently occurring -color from the corners is the background color of the image. Otherwise, -@var{bg} must be a list @code{(@var{red} @var{green} @var{blue})} -specifying the color to assume for the background of the image. - -If @var{mask} is @code{nil}, remove a mask from the image, if it has -one. Images in some formats include a mask which can be removed by -specifying @code{:mask nil}. - -@item :pointer @var{shape} -This specifies the pointer shape when the mouse pointer is over this -image. @xref{Pointer Shape}, for available pointer shapes. - -@item :map @var{map} -This associates an image map of @dfn{hot spots} with this image. - -An image map is an alist where each element has the format -@code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified -as either a rectangle, a circle, or a polygon. - -A rectangle is a cons -@code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))} -which specifies the pixel coordinates of the upper left and bottom right -corners of the rectangle area. - -A circle is a cons -@code{(circle . ((@var{x0} . @var{y0}) . @var{r}))} -which specifies the center and the radius of the circle; @var{r} may -be a float or integer. - -A polygon is a cons -@code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])} -where each pair in the vector describes one corner in the polygon. - -When the mouse pointer lies on a hot-spot area of an image, the -@var{plist} of that hot-spot is consulted; if it contains a @code{help-echo} -property, that defines a tool-tip for the hot-spot, and if it contains -a @code{pointer} property, that defines the shape of the mouse cursor when -it is on the hot-spot. -@xref{Pointer Shape}, for available pointer shapes. - -When you click the mouse when the mouse pointer is over a hot-spot, an -event is composed by combining the @var{id} of the hot-spot with the -mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's -@var{id} is @code{area4}. -@end table - -@defun image-mask-p spec &optional frame -This function returns @code{t} if image @var{spec} has a mask bitmap. -@var{frame} is the frame on which the image will be displayed. -@var{frame} @code{nil} or omitted means to use the selected frame -(@pxref{Input Focus}). -@end defun - -@node XBM Images -@subsection XBM Images -@cindex XBM - - To use XBM format, specify @code{xbm} as the image type. This image -format doesn't require an external library, so images of this type are -always supported. - - Additional image properties supported for the @code{xbm} image type are: - -@table @code -@item :foreground @var{foreground} -The value, @var{foreground}, should be a string specifying the image -foreground color, or @code{nil} for the default color. This color is -used for each pixel in the XBM that is 1. The default is the frame's -foreground color. - -@item :background @var{background} -The value, @var{background}, should be a string specifying the image -background color, or @code{nil} for the default color. This color is -used for each pixel in the XBM that is 0. The default is the frame's -background color. -@end table - - If you specify an XBM image using data within Emacs instead of an -external file, use the following three properties: - -@table @code -@item :data @var{data} -The value, @var{data}, specifies the contents of the image. -There are three formats you can use for @var{data}: - -@itemize @bullet -@item -A vector of strings or bool-vectors, each specifying one line of the -image. Do specify @code{:height} and @code{:width}. - -@item -A string containing the same byte sequence as an XBM file would contain. -You must not specify @code{:height} and @code{:width} in this case, -because omitting them is what indicates the data has the format of an -XBM file. The file contents specify the height and width of the image. - -@item -A string or a bool-vector containing the bits of the image (plus perhaps -some extra bits at the end that will not be used). It should contain at -least @var{width} * @code{height} bits. In this case, you must specify -@code{:height} and @code{:width}, both to indicate that the string -contains just the bits rather than a whole XBM file, and to specify the -size of the image. -@end itemize - -@item :width @var{width} -The value, @var{width}, specifies the width of the image, in pixels. - -@item :height @var{height} -The value, @var{height}, specifies the height of the image, in pixels. -@end table - -@node XPM Images -@subsection XPM Images -@cindex XPM - - To use XPM format, specify @code{xpm} as the image type. The -additional image property @code{:color-symbols} is also meaningful with -the @code{xpm} image type: - -@table @code -@item :color-symbols @var{symbols} -The value, @var{symbols}, should be an alist whose elements have the -form @code{(@var{name} . @var{color})}. In each element, @var{name} is -the name of a color as it appears in the image file, and @var{color} -specifies the actual color to use for displaying that name. -@end table - -@node GIF Images -@subsection GIF Images -@cindex GIF - - For GIF images, specify image type @code{gif}. - -@table @code -@item :index @var{index} -You can use @code{:index} to specify image number @var{index} from a -GIF file that contains more than one image. If the GIF file doesn't -contain an image with the specified index, the image displays as a -hollow box. GIF files with more than one image can be animated, -@pxref{Animated Images}. -@end table - -@node TIFF Images -@subsection TIFF Images -@cindex TIFF - - For TIFF images, specify image type @code{tiff}. - -@table @code -@item :index @var{index} -You can use @code{:index} to specify image number @var{index} from a -TIFF file that contains more than one image. If the TIFF file doesn't -contain an image with the specified index, the image displays as a -hollow box. -@end table - -@node PostScript Images -@subsection PostScript Images -@cindex postscript images - - To use PostScript for an image, specify image type @code{postscript}. -This works only if you have Ghostscript installed. You must always use -these three properties: - -@table @code -@item :pt-width @var{width} -The value, @var{width}, specifies the width of the image measured in -points (1/72 inch). @var{width} must be an integer. - -@item :pt-height @var{height} -The value, @var{height}, specifies the height of the image in points -(1/72 inch). @var{height} must be an integer. - -@item :bounding-box @var{box} -The value, @var{box}, must be a list or vector of four integers, which -specifying the bounding box of the PostScript image, analogous to the -@samp{BoundingBox} comment found in PostScript files. - -@example -%%BoundingBox: 22 171 567 738 -@end example -@end table - -@node ImageMagick Images -@subsection ImageMagick Images -@cindex ImageMagick images -@cindex images, support for more formats - - If you build Emacs with ImageMagick support, you can use the -ImageMagick library to load many image formats. The image type symbol -for images loaded via ImageMagick is @code{imagemagick}, regardless of -the actual underlying image format. - -@defun imagemagick-types -This function returns a list of image file extensions supported by the -current ImageMagick installation. -@end defun - - By default, Emacs does not use ImageMagick to display images in -Image mode, e.g.@: when visiting such files with @kbd{C-x C-f}. This -feature is enabled by calling @code{imagemagick-register-types}. - -@defun imagemagick-register-types -This function enables using Image mode to visit image files supported -by ImageMagick. @xref{File Conveniences,,, emacs, The GNU Emacs -Manual}. It also causes @code{create-image} and other helper -functions to associate such file names with the @code{imagemagick} -image type (@pxref{Defining Images}). - -All image file extensions supported by ImageMagick are registered, -except those specified in @code{imagemagick-types-inhibit}. If Emacs -was not compiled with ImageMagick support, this function does nothing. -@end defun - -@defopt imagemagick-types-inhibit -This variable specifies a list of image types that should @emph{not} -be registered by @code{imagemagick-register-types}. Each entry in -this list should be one of the symbols returned by -@code{imagemagick-types}. The default value lists several file types -that are considered ``images'' by ImageMagick, but which should not be -considered as images by Emacs, including C files and HTML files. -@end defopt - -@ignore -@c I don't know what this means. I suspect it means eg loading jpg -@c images via libjpeg or ImageMagick. But it doesn't work. -@c If you don't have libjpeg support compiled in, you cannot -@c view jpeg images, even if you have imagemagick support: -@c http://debbugs.gnu.org/9045 -@c And if you have both compiled in, then you always get -@c the libjpeg version: -@c http://debbugs.gnu.org/10746 -There may be overlap between image loaders in your Emacs installation, -and you may prefer to use a different one for a given image type -(which loader will be used in practice depends on the priority of the -loaders). -For example, if you never want to use the ImageMagick loader to view -JPEG files, add @code{JPG} to this list. -@end ignore - - Images loaded with ImageMagick support the following additional -image descriptor properties: - -@table @code -@item :width, :height -The @code{:width} and @code{:height} keywords are used for scaling the -image. If only one of them is specified, the other one will be -calculated so as to preserve the aspect ratio. If both are specified, -aspect ratio may not be preserved. - -@item :rotation -Specifies a rotation angle in degrees. - -@item :index -@c Doesn't work: http://debbugs.gnu.org/7978 -This has the same meaning as it does for GIF images (@pxref{GIF Images}), -i.e. it specifies which image to view inside an image bundle file format -such as DJVM. You can use the @code{image-metadata} function to -retrieve the total number of images in an image bundle. -@end table - -@node Other Image Types -@subsection Other Image Types -@cindex PBM - - For PBM images, specify image type @code{pbm}. Color, gray-scale and -monochromatic images are supported. For mono PBM images, two additional -image properties are supported. - -@table @code -@item :foreground @var{foreground} -The value, @var{foreground}, should be a string specifying the image -foreground color, or @code{nil} for the default color. This color is -used for each pixel in the PBM that is 1. The default is the frame's -foreground color. - -@item :background @var{background} -The value, @var{background}, should be a string specifying the image -background color, or @code{nil} for the default color. This color is -used for each pixel in the PBM that is 0. The default is the frame's -background color. -@end table - - For JPEG images, specify image type @code{jpeg}. - - For TIFF images, specify image type @code{tiff}. - - For PNG images, specify image type @code{png}. - - For SVG images, specify image type @code{svg}. - -@node Defining Images -@subsection Defining Images - - The functions @code{create-image}, @code{defimage} and -@code{find-image} provide convenient ways to create image descriptors. - -@defun create-image file-or-data &optional type data-p &rest props -This function creates and returns an image descriptor which uses the -data in @var{file-or-data}. @var{file-or-data} can be a file name or -a string containing the image data; @var{data-p} should be @code{nil} -for the former case, non-@code{nil} for the latter case. - -The optional argument @var{type} is a symbol specifying the image type. -If @var{type} is omitted or @code{nil}, @code{create-image} tries to -determine the image type from the file's first few bytes, or else -from the file's name. - -The remaining arguments, @var{props}, specify additional image -properties---for example, - -@example -(create-image "foo.xpm" 'xpm nil :heuristic-mask t) -@end example - -The function returns @code{nil} if images of this type are not -supported. Otherwise it returns an image descriptor. -@end defun - -@defmac defimage symbol specs &optional doc -This macro defines @var{symbol} as an image name. The arguments -@var{specs} is a list which specifies how to display the image. -The third argument, @var{doc}, is an optional documentation string. - -Each argument in @var{specs} has the form of a property list, and each -one should specify at least the @code{:type} property and either the -@code{:file} or the @code{:data} property. The value of @code{:type} -should be a symbol specifying the image type, the value of -@code{:file} is the file to load the image from, and the value of -@code{:data} is a string containing the actual image data. Here is an -example: - -@example -(defimage test-image - ((:type xpm :file "~/test1.xpm") - (:type xbm :file "~/test1.xbm"))) -@end example - -@code{defimage} tests each argument, one by one, to see if it is -usable---that is, if the type is supported and the file exists. The -first usable argument is used to make an image descriptor which is -stored in @var{symbol}. - -If none of the alternatives will work, then @var{symbol} is defined -as @code{nil}. -@end defmac - -@defun find-image specs -This function provides a convenient way to find an image satisfying one -of a list of image specifications @var{specs}. - -Each specification in @var{specs} is a property list with contents -depending on image type. All specifications must at least contain the -properties @code{:type @var{type}} and either @w{@code{:file @var{file}}} -or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying -the image type, e.g.@: @code{xbm}, @var{file} is the file to load the -image from, and @var{data} is a string containing the actual image data. -The first specification in the list whose @var{type} is supported, and -@var{file} exists, is used to construct the image specification to be -returned. If no specification is satisfied, @code{nil} is returned. - -The image is looked for in @code{image-load-path}. -@end defun - -@defvar image-load-path -This variable's value is a list of locations in which to search for -image files. If an element is a string or a variable symbol whose -value is a string, the string is taken to be the name of a directory -to search. If an element is a variable symbol whose value is a list, -that is taken to be a list of directory names to search. - -The default is to search in the @file{images} subdirectory of the -directory specified by @code{data-directory}, then the directory -specified by @code{data-directory}, and finally in the directories in -@code{load-path}. Subdirectories are not automatically included in -the search, so if you put an image file in a subdirectory, you have to -supply the subdirectory name explicitly. For example, to find the -image @file{images/foo/bar.xpm} within @code{data-directory}, you -should specify the image as follows: - -@example -(defimage foo-image '((:type xpm :file "foo/bar.xpm"))) -@end example -@end defvar - -@defun image-load-path-for-library library image &optional path no-error -This function returns a suitable search path for images used by the -Lisp package @var{library}. - -The function searches for @var{image} first using @code{image-load-path}, -excluding @file{@code{data-directory}/images}, and then in -@code{load-path}, followed by a path suitable for @var{library}, which -includes @file{../../etc/images} and @file{../etc/images} relative to -the library file itself, and finally in -@file{@code{data-directory}/images}. - -Then this function returns a list of directories which contains first -the directory in which @var{image} was found, followed by the value of -@code{load-path}. If @var{path} is given, it is used instead of -@code{load-path}. - -If @var{no-error} is non-@code{nil} and a suitable path can't be -found, don't signal an error. Instead, return a list of directories as -before, except that @code{nil} appears in place of the image directory. - -Here is an example of using @code{image-load-path-for-library}: - -@example -(defvar image-load-path) ; shush compiler -(let* ((load-path (image-load-path-for-library - "mh-e" "mh-logo.xpm")) - (image-load-path (cons (car load-path) - image-load-path))) - (mh-tool-bar-folder-buttons-init)) -@end example -@end defun - -@node Showing Images -@subsection Showing Images - - You can use an image descriptor by setting up the @code{display} -property yourself, but it is easier to use the functions in this -section. - -@defun insert-image image &optional string area slice -This function inserts @var{image} in the current buffer at point. The -value @var{image} should be an image descriptor; it could be a value -returned by @code{create-image}, or the value of a symbol defined with -@code{defimage}. The argument @var{string} specifies the text to put -in the buffer to hold the image. If it is omitted or @code{nil}, -@code{insert-image} uses @code{" "} by default. - -The argument @var{area} specifies whether to put the image in a margin. -If it is @code{left-margin}, the image appears in the left margin; -@code{right-margin} specifies the right margin. If @var{area} is -@code{nil} or omitted, the image is displayed at point within the -buffer's text. - -The argument @var{slice} specifies a slice of the image to insert. If -@var{slice} is @code{nil} or omitted the whole image is inserted. -Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width} -@var{height})} which specifies the @var{x} and @var{y} positions and -@var{width} and @var{height} of the image area to insert. Integer -values are in units of pixels. A floating point number in the range -0.0--1.0 stands for that fraction of the width or height of the entire -image. - -Internally, this function inserts @var{string} in the buffer, and gives -it a @code{display} property which specifies @var{image}. @xref{Display -Property}. -@end defun - -@cindex slice, image -@cindex image slice -@defun insert-sliced-image image &optional string area rows cols -This function inserts @var{image} in the current buffer at point, like -@code{insert-image}, but splits the image into @var{rows}x@var{cols} -equally sized slices. - -If an image is inserted ``sliced'', Emacs displays each slice as a -separate image, and allow more intuitive scrolling up/down, instead of -jumping up/down the entire image when paging through a buffer that -displays (large) images. -@end defun - -@defun put-image image pos &optional string area -This function puts image @var{image} in front of @var{pos} in the -current buffer. The argument @var{pos} should be an integer or a -marker. It specifies the buffer position where the image should appear. -The argument @var{string} specifies the text that should hold the image -as an alternative to the default. - -The argument @var{image} must be an image descriptor, perhaps returned -by @code{create-image} or stored by @code{defimage}. - -The argument @var{area} specifies whether to put the image in a margin. -If it is @code{left-margin}, the image appears in the left margin; -@code{right-margin} specifies the right margin. If @var{area} is -@code{nil} or omitted, the image is displayed at point within the -buffer's text. - -Internally, this function creates an overlay, and gives it a -@code{before-string} property containing text that has a @code{display} -property whose value is the image. (Whew!) -@end defun - -@defun remove-images start end &optional buffer -This function removes images in @var{buffer} between positions -@var{start} and @var{end}. If @var{buffer} is omitted or @code{nil}, -images are removed from the current buffer. - -This removes only images that were put into @var{buffer} the way -@code{put-image} does it, not images that were inserted with -@code{insert-image} or in other ways. -@end defun - -@defun image-size spec &optional pixels frame -This function returns the size of an image as a pair -@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image -specification. @var{pixels} non-@code{nil} means return sizes -measured in pixels, otherwise return sizes measured in canonical -character units (fractions of the width/height of the frame's default -font). @var{frame} is the frame on which the image will be displayed. -@var{frame} null or omitted means use the selected frame (@pxref{Input -Focus}). -@end defun - -@defvar max-image-size -This variable is used to define the maximum size of image that Emacs -will load. Emacs will refuse to load (and display) any image that is -larger than this limit. - -If the value is an integer, it directly specifies the maximum -image height and width, measured in pixels. If it is a floating -point number, it specifies the maximum image height and width -as a ratio to the frame height and width. If the value is -non-numeric, there is no explicit limit on the size of images. - -The purpose of this variable is to prevent unreasonably large images -from accidentally being loaded into Emacs. It only takes effect the -first time an image is loaded. Once an image is placed in the image -cache, it can always be displayed, even if the value of -@var{max-image-size} is subsequently changed (@pxref{Image Cache}). -@end defvar - -@node Animated Images -@subsection Animated Images - -@cindex animation -@cindex image animation -Some image files can contain more than one image. This can be used to -create animation. Currently, Emacs only supports animated GIF files. -The following functions related to animated images are available. - -@defun image-animated-p image -This function returns non-@code{nil} if @var{image} can be animated. -The actual return value is a cons @code{(@var{nimages} . @var{delay})}, -where @var{nimages} is the number of frames and @var{delay} is the -delay in seconds between them. -@end defun - -@defun image-animate image &optional index limit -This function animates @var{image}. The optional integer @var{index} -specifies the frame from which to start (default 0). The optional -argument @var{limit} controls the length of the animation. If omitted -or @code{nil}, the image animates once only; if @code{t} it loops -forever; if a number animation stops after that many seconds. -@end defun - -@noindent Animation operates by means of a timer. Note that Emacs imposes a -minimum frame delay of 0.01 seconds. - -@defun image-animate-timer image -This function returns the timer responsible for animating @var{image}, -if there is one. -@end defun - - -@node Image Cache -@subsection Image Cache -@cindex image cache - - Emacs caches images so that it can display them again more -efficiently. When Emacs displays an image, it searches the image -cache for an existing image specification @code{equal} to the desired -specification. If a match is found, the image is displayed from the -cache. Otherwise, Emacs loads the image normally. - -@defun image-flush spec &optional frame -This function removes the image with specification @var{spec} from the -image cache of frame @var{frame}. Image specifications are compared -using @code{equal}. If @var{frame} is @code{nil}, it defaults to the -selected frame. If @var{frame} is @code{t}, the image is flushed on -all existing frames. - -In Emacs's current implementation, each graphical terminal possesses an -image cache, which is shared by all the frames on that terminal -(@pxref{Multiple Terminals}). Thus, refreshing an image in one frame -also refreshes it in all other frames on the same terminal. -@end defun - - One use for @code{image-flush} is to tell Emacs about a change in an -image file. If an image specification contains a @code{:file} -property, the image is cached based on the file's contents when the -image is first displayed. Even if the file subsequently changes, -Emacs continues displaying the old version of the image. Calling -@code{image-flush} flushes the image from the cache, forcing Emacs to -re-read the file the next time it needs to display that image. - - Another use for @code{image-flush} is for memory conservation. If -your Lisp program creates a large number of temporary images over a -period much shorter than @code{image-cache-eviction-delay} (see -below), you can opt to flush unused images yourself, instead of -waiting for Emacs to do it automatically. - -@defun clear-image-cache &optional filter -This function clears an image cache, removing all the images stored in -it. If @var{filter} is omitted or @code{nil}, it clears the cache for -the selected frame. If @var{filter} is a frame, it clears the cache -for that frame. If @var{filter} is @code{t}, all image caches are -cleared. Otherwise, @var{filter} is taken to be a file name, and all -images associated with that file name are removed from all image -caches. -@end defun - -If an image in the image cache has not been displayed for a specified -period of time, Emacs removes it from the cache and frees the -associated memory. - -@defvar image-cache-eviction-delay -This variable specifies the number of seconds an image can remain in -the cache without being displayed. When an image is not displayed for -this length of time, Emacs removes it from the image cache. - -Under some circumstances, if the number of images in the cache grows -too large, the actual eviction delay may be shorter than this. - -If the value is @code{nil}, Emacs does not remove images from the cache -except when you explicitly clear it. This mode can be useful for -debugging. -@end defvar - -@node Buttons -@section Buttons -@cindex buttons in buffers -@cindex clickable buttons in buffers - - The Button package defines functions for inserting and manipulating -@dfn{buttons} that can be activated with the mouse or via keyboard -commands. These buttons are typically used for various kinds of -hyperlinks. - - A button is essentially a set of text or overlay properties, -attached to a stretch of text in a buffer. These properties are -called @dfn{button properties}. One of these properties, the -@dfn{action property}, specifies a function which is called when the -user invokes the button using the keyboard or the mouse. The action -function may examine the button and use its other properties as -desired. - - In some ways, the Button package duplicates the functionality in the -Widget package. @xref{Top, , Introduction, widget, The Emacs Widget -Library}. The advantage of the Button package is that it is faster, -smaller, and simpler to program. From the point of view of the user, -the interfaces produced by the two packages are very similar. - -@menu -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. -@end menu - -@node Button Properties -@subsection Button Properties -@cindex button properties - - Each button has an associated list of properties defining its -appearance and behavior, and other arbitrary properties may be used -for application specific purposes. The following properties have -special meaning to the Button package: - -@table @code -@item action -@kindex action @r{(button property)} -The function to call when the user invokes the button, which is passed -the single argument @var{button}. By default this is @code{ignore}, -which does nothing. - -@item mouse-action -@kindex mouse-action @r{(button property)} -This is similar to @code{action}, and when present, will be used -instead of @code{action} for button invocations resulting from -mouse-clicks (instead of the user hitting @key{RET}). If not -present, mouse-clicks use @code{action} instead. - -@item face -@kindex face @r{(button property)} -This is an Emacs face controlling how buttons of this type are -displayed; by default this is the @code{button} face. - -@item mouse-face -@kindex mouse-face @r{(button property)} -This is an additional face which controls appearance during -mouse-overs (merged with the usual button face); by default this is -the usual Emacs @code{highlight} face. - -@item keymap -@kindex keymap @r{(button property)} -The button's keymap, defining bindings active within the button -region. By default this is the usual button region keymap, stored -in the variable @code{button-map}, which defines @key{RET} and -@key{mouse-2} to invoke the button. - -@item type -@kindex type @r{(button property)} -The button type. @xref{Button Types}. - -@item help-echo -@kindex help-index @r{(button property)} -A string displayed by the Emacs tool-tip help system; by default, -@code{"mouse-2, RET: Push this button"}. - -@item follow-link -@kindex follow-link @r{(button property)} -The follow-link property, defining how a @key{Mouse-1} click behaves -on this button, @xref{Clickable Text}. - -@item button -@kindex button @r{(button property)} -All buttons have a non-@code{nil} @code{button} property, which may be useful -in finding regions of text that comprise buttons (which is what the -standard button functions do). -@end table - - There are other properties defined for the regions of text in a -button, but these are not generally interesting for typical uses. - -@node Button Types -@subsection Button Types -@cindex button types - - Every button has a @dfn{button type}, which defines default values -for the button's properties. Button types are arranged in a -hierarchy, with specialized types inheriting from more general types, -so that it's easy to define special-purpose types of buttons for -specific tasks. - -@defun define-button-type name &rest properties -Define a `button type' called @var{name} (a symbol). -The remaining arguments -form a sequence of @var{property value} pairs, specifying default -property values for buttons with this type (a button's type may be set -by giving it a @code{type} property when creating the button, using -the @code{:type} keyword argument). - -In addition, the keyword argument @code{:supertype} may be used to -specify a button-type from which @var{name} inherits its default -property values. Note that this inheritance happens only when -@var{name} is defined; subsequent changes to a supertype are not -reflected in its subtypes. -@end defun - - Using @code{define-button-type} to define default properties for -buttons is not necessary---buttons without any specified type use the -built-in button-type @code{button}---but it is encouraged, since -doing so usually makes the resulting code clearer and more efficient. - -@node Making Buttons -@subsection Making Buttons -@cindex making buttons - - Buttons are associated with a region of text, using an overlay or -text properties to hold button-specific information, all of which are -initialized from the button's type (which defaults to the built-in -button type @code{button}). Like all Emacs text, the appearance of -the button is governed by the @code{face} property; by default (via -the @code{face} property inherited from the @code{button} button-type) -this is a simple underline, like a typical web-page link. - - For convenience, there are two sorts of button-creation functions, -those that add button properties to an existing region of a buffer, -called @code{make-...button}, and those that also insert the button -text, called @code{insert-...button}. - - The button-creation functions all take the @code{&rest} argument -@var{properties}, which should be a sequence of @var{property value} -pairs, specifying properties to add to the button; see @ref{Button -Properties}. In addition, the keyword argument @code{:type} may be -used to specify a button-type from which to inherit other properties; -see @ref{Button Types}. Any properties not explicitly specified -during creation will be inherited from the button's type (if the type -defines such a property). - - The following functions add a button using an overlay -(@pxref{Overlays}) to hold the button properties: - -@defun make-button beg end &rest properties -This makes a button from @var{beg} to @var{end} in the -current buffer, and returns it. -@end defun - -@defun insert-button label &rest properties -This insert a button with the label @var{label} at point, -and returns it. -@end defun - - The following functions are similar, but using text properties -(@pxref{Text Properties}) to hold the button properties. Such buttons -do not add markers to the buffer, so editing in the buffer does not -slow down if there is an extremely large numbers of buttons. However, -if there is an existing face text property on the text (e.g.@: a face -assigned by Font Lock mode), the button face may not be visible. Both -of these functions return the starting position of the new button. - -@defun make-text-button beg end &rest properties -This makes a button from @var{beg} to @var{end} in the current buffer, -using text properties. -@end defun - -@defun insert-text-button label &rest properties -This inserts a button with the label @var{label} at point, using text -properties. -@end defun - -@node Manipulating Buttons -@subsection Manipulating Buttons -@cindex manipulating buttons - -These are functions for getting and setting properties of buttons. -Often these are used by a button's invocation function to determine -what to do. - -Where a @var{button} parameter is specified, it means an object -referring to a specific button, either an overlay (for overlay -buttons), or a buffer-position or marker (for text property buttons). -Such an object is passed as the first argument to a button's -invocation function when it is invoked. - -@defun button-start button -Return the position at which @var{button} starts. -@end defun - -@defun button-end button -Return the position at which @var{button} ends. -@end defun - -@defun button-get button prop -Get the property of button @var{button} named @var{prop}. -@end defun - -@defun button-put button prop val -Set @var{button}'s @var{prop} property to @var{val}. -@end defun - -@defun button-activate button &optional use-mouse-action -Call @var{button}'s @code{action} property (i.e., invoke it). If -@var{use-mouse-action} is non-@code{nil}, try to invoke the button's -@code{mouse-action} property instead of @code{action}; if the button -has no @code{mouse-action} property, use @code{action} as normal. -@end defun - -@defun button-label button -Return @var{button}'s text label. -@end defun - -@defun button-type button -Return @var{button}'s button-type. -@end defun - -@defun button-has-type-p button type -Return @code{t} if @var{button} has button-type @var{type}, or one of -@var{type}'s subtypes. -@end defun - -@defun button-at pos -Return the button at position @var{pos} in the current buffer, or -@code{nil}. If the button at @var{pos} is a text property button, the -return value is a marker pointing to @var{pos}. -@end defun - -@defun button-type-put type prop val -Set the button-type @var{type}'s @var{prop} property to @var{val}. -@end defun - -@defun button-type-get type prop -Get the property of button-type @var{type} named @var{prop}. -@end defun - -@defun button-type-subtype-p type supertype -Return @code{t} if button-type @var{type} is a subtype of @var{supertype}. -@end defun - -@node Button Buffer Commands -@subsection Button Buffer Commands -@cindex button buffer commands - -These are commands and functions for locating and operating on -buttons in an Emacs buffer. - -@code{push-button} is the command that a user uses to actually `push' -a button, and is bound by default in the button itself to @key{RET} -and to @key{mouse-2} using a local keymap in the button's overlay or -text properties. Commands that are useful outside the buttons itself, -such as @code{forward-button} and @code{backward-button} are -additionally available in the keymap stored in -@code{button-buffer-map}; a mode which uses buttons may want to use -@code{button-buffer-map} as a parent keymap for its keymap. - -If the button has a non-@code{nil} @code{follow-link} property, and -@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click -will also activate the @code{push-button} command. -@xref{Clickable Text}. - -@deffn Command push-button &optional pos use-mouse-action -Perform the action specified by a button at location @var{pos}. -@var{pos} may be either a buffer position or a mouse-event. If -@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a -mouse-event (@pxref{Mouse Events}), try to invoke the button's -@code{mouse-action} property instead of @code{action}; if the button -has no @code{mouse-action} property, use @code{action} as normal. -@var{pos} defaults to point, except when @code{push-button} is invoked -interactively as the result of a mouse-event, in which case, the mouse -event's position is used. If there's no button at @var{pos}, do -nothing and return @code{nil}, otherwise return @code{t}. -@end deffn - -@deffn Command forward-button n &optional wrap display-message -Move to the @var{n}th next button, or @var{n}th previous button if -@var{n} is negative. If @var{n} is zero, move to the start of any -button at point. If @var{wrap} is non-@code{nil}, moving past either -end of the buffer continues from the other end. If -@var{display-message} is non-@code{nil}, the button's help-echo string -is displayed. Any button with a non-@code{nil} @code{skip} property -is skipped over. Returns the button found. -@end deffn - -@deffn Command backward-button n &optional wrap display-message -Move to the @var{n}th previous button, or @var{n}th next button if -@var{n} is negative. If @var{n} is zero, move to the start of any -button at point. If @var{wrap} is non-@code{nil}, moving past either -end of the buffer continues from the other end. If -@var{display-message} is non-@code{nil}, the button's help-echo string -is displayed. Any button with a non-@code{nil} @code{skip} property -is skipped over. Returns the button found. -@end deffn - -@defun next-button pos &optional count-current -@defunx previous-button pos &optional count-current -Return the next button after (for @code{next-button} or before (for -@code{previous-button}) position @var{pos} in the current buffer. If -@var{count-current} is non-@code{nil}, count any button at @var{pos} -in the search, instead of starting at the next button. -@end defun - -@node Abstract Display -@section Abstract Display -@cindex ewoc -@cindex display, abstract -@cindex display, arbitrary objects -@cindex model/view/controller -@cindex view part, model/view/controller - - The Ewoc package constructs buffer text that represents a structure -of Lisp objects, and updates the text to follow changes in that -structure. This is like the ``view'' component in the -``model/view/controller'' design paradigm. - - An @dfn{ewoc} is a structure that organizes information required to -construct buffer text that represents certain Lisp data. The buffer -text of the ewoc has three parts, in order: first, fixed @dfn{header} -text; next, textual descriptions of a series of data elements (Lisp -objects that you specify); and last, fixed @dfn{footer} text. -Specifically, an ewoc contains information on: - -@itemize @bullet -@item -The buffer which its text is generated in. - -@item -The text's start position in the buffer. - -@item -The header and footer strings. - -@item -A doubly-linked chain of @dfn{nodes}, each of which contains: - -@itemize -@item -A @dfn{data element}, a single Lisp object. - -@item -Links to the preceding and following nodes in the chain. -@end itemize - -@item -A @dfn{pretty-printer} function which is responsible for -inserting the textual representation of a data -element value into the current buffer. -@end itemize - - Typically, you define an ewoc with @code{ewoc-create}, and then pass -the resulting ewoc structure to other functions in the Ewoc package to -build nodes within it, and display it in the buffer. Once it is -displayed in the buffer, other functions determine the correspondence -between buffer positions and nodes, move point from one node's textual -representation to another, and so forth. @xref{Abstract Display -Functions}. - - A node @dfn{encapsulates} a data element much the way a variable -holds a value. Normally, encapsulation occurs as a part of adding a -node to the ewoc. You can retrieve the data element value and place a -new value in its place, like so: - -@lisp -(ewoc-data @var{node}) -@result{} value - -(ewoc-set-data @var{node} @var{new-value}) -@result{} @var{new-value} -@end lisp - -@noindent -You can also use, as the data element value, a Lisp object (list or -vector) that is a container for the ``real'' value, or an index into -some other structure. The example (@pxref{Abstract Display Example}) -uses the latter approach. - - When the data changes, you will want to update the text in the -buffer. You can update all nodes by calling @code{ewoc-refresh}, or -just specific nodes using @code{ewoc-invalidate}, or all nodes -satisfying a predicate using @code{ewoc-map}. Alternatively, you can -delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter}, -and add new nodes in their place. Deleting a node from an ewoc deletes -its associated textual description from buffer, as well. - -@menu -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. -@end menu - -@node Abstract Display Functions -@subsection Abstract Display Functions - - In this subsection, @var{ewoc} and @var{node} stand for the -structures described above (@pxref{Abstract Display}), while -@var{data} stands for an arbitrary Lisp object used as a data element. - -@defun ewoc-create pretty-printer &optional header footer nosep -This constructs and returns a new ewoc, with no nodes (and thus no data -elements). @var{pretty-printer} should be a function that takes one -argument, a data element of the sort you plan to use in this ewoc, and -inserts its textual description at point using @code{insert} (and never -@code{insert-before-markers}, because that would interfere with the -Ewoc package's internal mechanisms). - -Normally, a newline is automatically inserted after the header, -the footer and every node's textual description. If @var{nosep} -is non-@code{nil}, no newline is inserted. This may be useful for -displaying an entire ewoc on a single line, for example, or for -making nodes ``invisible'' by arranging for @var{pretty-printer} -to do nothing for those nodes. - -An ewoc maintains its text in the buffer that is current when -you create it, so switch to the intended buffer before calling -@code{ewoc-create}. -@end defun - -@defun ewoc-buffer ewoc -This returns the buffer where @var{ewoc} maintains its text. -@end defun - -@defun ewoc-get-hf ewoc -This returns a cons cell @code{(@var{header} . @var{footer})} -made from @var{ewoc}'s header and footer. -@end defun - -@defun ewoc-set-hf ewoc header footer -This sets the header and footer of @var{ewoc} to the strings -@var{header} and @var{footer}, respectively. -@end defun - -@defun ewoc-enter-first ewoc data -@defunx ewoc-enter-last ewoc data -These add a new node encapsulating @var{data}, putting it, respectively, -at the beginning or end of @var{ewoc}'s chain of nodes. -@end defun - -@defun ewoc-enter-before ewoc node data -@defunx ewoc-enter-after ewoc node data -These add a new node encapsulating @var{data}, adding it to -@var{ewoc} before or after @var{node}, respectively. -@end defun - -@defun ewoc-prev ewoc node -@defunx ewoc-next ewoc node -These return, respectively, the previous node and the next node of @var{node} -in @var{ewoc}. -@end defun - -@defun ewoc-nth ewoc n -This returns the node in @var{ewoc} found at zero-based index @var{n}. -A negative @var{n} means count from the end. @code{ewoc-nth} returns -@code{nil} if @var{n} is out of range. -@end defun - -@defun ewoc-data node -This extracts the data encapsulated by @var{node} and returns it. -@end defun - -@defun ewoc-set-data node data -This sets the data encapsulated by @var{node} to @var{data}. -@end defun - -@defun ewoc-locate ewoc &optional pos guess -This determines the node in @var{ewoc} which contains point (or -@var{pos} if specified), and returns that node. If @var{ewoc} has no -nodes, it returns @code{nil}. If @var{pos} is before the first node, -it returns the first node; if @var{pos} is after the last node, it returns -the last node. The optional third arg @var{guess} -should be a node that is likely to be near @var{pos}; this doesn't -alter the result, but makes the function run faster. -@end defun - -@defun ewoc-location node -This returns the start position of @var{node}. -@end defun - -@defun ewoc-goto-prev ewoc arg -@defunx ewoc-goto-next ewoc arg -These move point to the previous or next, respectively, @var{arg}th node -in @var{ewoc}. @code{ewoc-goto-prev} does not move if it is already at -the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next} -moves past the last node, returning @code{nil}. Excepting this special -case, these functions return the node moved to. -@end defun - -@defun ewoc-goto-node ewoc node -This moves point to the start of @var{node} in @var{ewoc}. -@end defun - -@defun ewoc-refresh ewoc -This function regenerates the text of @var{ewoc}. It works by -deleting the text between the header and the footer, i.e., all the -data elements' representations, and then calling the pretty-printer -function for each node, one by one, in order. -@end defun - -@defun ewoc-invalidate ewoc &rest nodes -This is similar to @code{ewoc-refresh}, except that only @var{nodes} in -@var{ewoc} are updated instead of the entire set. -@end defun - -@defun ewoc-delete ewoc &rest nodes -This deletes each node in @var{nodes} from @var{ewoc}. -@end defun - -@defun ewoc-filter ewoc predicate &rest args -This calls @var{predicate} for each data element in @var{ewoc} and -deletes those nodes for which @var{predicate} returns @code{nil}. -Any @var{args} are passed to @var{predicate}. -@end defun - -@defun ewoc-collect ewoc predicate &rest args -This calls @var{predicate} for each data element in @var{ewoc} -and returns a list of those elements for which @var{predicate} -returns non-@code{nil}. The elements in the list are ordered -as in the buffer. Any @var{args} are passed to @var{predicate}. -@end defun - -@defun ewoc-map map-function ewoc &rest args -This calls @var{map-function} for each data element in @var{ewoc} and -updates those nodes for which @var{map-function} returns non-@code{nil}. -Any @var{args} are passed to @var{map-function}. -@end defun - -@node Abstract Display Example -@subsection Abstract Display Example - - Here is a simple example using functions of the ewoc package to -implement a ``color components display'', an area in a buffer that -represents a vector of three integers (itself representing a 24-bit RGB -value) in various ways. - -@example -(setq colorcomp-ewoc nil - colorcomp-data nil - colorcomp-mode-map nil - colorcomp-labels ["Red" "Green" "Blue"]) - -(defun colorcomp-pp (data) - (if data - (let ((comp (aref colorcomp-data data))) - (insert (aref colorcomp-labels data) "\t: #x" - (format "%02X" comp) " " - (make-string (ash comp -2) ?#) "\n")) - (let ((cstr (format "#%02X%02X%02X" - (aref colorcomp-data 0) - (aref colorcomp-data 1) - (aref colorcomp-data 2))) - (samp " (sample text) ")) - (insert "Color\t: " - (propertize samp 'face - `(foreground-color . ,cstr)) - (propertize samp 'face - `(background-color . ,cstr)) - "\n")))) - -(defun colorcomp (color) - "Allow fiddling with COLOR in a new buffer. -The buffer is in Color Components mode." - (interactive "sColor (name or #RGB or #RRGGBB): ") - (when (string= "" color) - (setq color "green")) - (unless (color-values color) - (error "No such color: %S" color)) - (switch-to-buffer - (generate-new-buffer (format "originally: %s" color))) - (kill-all-local-variables) - (setq major-mode 'colorcomp-mode - mode-name "Color Components") - (use-local-map colorcomp-mode-map) - (erase-buffer) - (buffer-disable-undo) - (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8)) - (color-values color)))) - (ewoc (ewoc-create 'colorcomp-pp - "\nColor Components\n\n" - (substitute-command-keys - "\n\\@{colorcomp-mode-map@}")))) - (set (make-local-variable 'colorcomp-data) data) - (set (make-local-variable 'colorcomp-ewoc) ewoc) - (ewoc-enter-last ewoc 0) - (ewoc-enter-last ewoc 1) - (ewoc-enter-last ewoc 2) - (ewoc-enter-last ewoc nil))) -@end example - -@cindex controller part, model/view/controller - This example can be extended to be a ``color selection widget'' (in -other words, the controller part of the ``model/view/controller'' -design paradigm) by defining commands to modify @code{colorcomp-data} -and to ``finish'' the selection process, and a keymap to tie it all -together conveniently. - -@smallexample -(defun colorcomp-mod (index limit delta) - (let ((cur (aref colorcomp-data index))) - (unless (= limit cur) - (aset colorcomp-data index (+ cur delta))) - (ewoc-invalidate - colorcomp-ewoc - (ewoc-nth colorcomp-ewoc index) - (ewoc-nth colorcomp-ewoc -1)))) - -(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1)) -(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1)) -(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1)) -(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1)) -(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1)) -(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1)) - -(defun colorcomp-copy-as-kill-and-exit () - "Copy the color components into the kill ring and kill the buffer. -The string is formatted #RRGGBB (hash followed by six hex digits)." - (interactive) - (kill-new (format "#%02X%02X%02X" - (aref colorcomp-data 0) - (aref colorcomp-data 1) - (aref colorcomp-data 2))) - (kill-buffer nil)) - -(setq colorcomp-mode-map - (let ((m (make-sparse-keymap))) - (suppress-keymap m) - (define-key m "i" 'colorcomp-R-less) - (define-key m "o" 'colorcomp-R-more) - (define-key m "k" 'colorcomp-G-less) - (define-key m "l" 'colorcomp-G-more) - (define-key m "," 'colorcomp-B-less) - (define-key m "." 'colorcomp-B-more) - (define-key m " " 'colorcomp-copy-as-kill-and-exit) - m)) -@end smallexample - -Note that we never modify the data in each node, which is fixed when the -ewoc is created to be either @code{nil} or an index into the vector -@code{colorcomp-data}, the actual color components. - -@node Blinking -@section Blinking Parentheses -@cindex parenthesis matching -@cindex blinking parentheses -@cindex balancing parentheses - - This section describes the mechanism by which Emacs shows a matching -open parenthesis when the user inserts a close parenthesis. - -@defvar blink-paren-function -The value of this variable should be a function (of no arguments) to -be called whenever a character with close parenthesis syntax is inserted. -The value of @code{blink-paren-function} may be @code{nil}, in which -case nothing is done. -@end defvar - -@defopt blink-matching-paren -If this variable is @code{nil}, then @code{blink-matching-open} does -nothing. -@end defopt - -@defopt blink-matching-paren-distance -This variable specifies the maximum distance to scan for a matching -parenthesis before giving up. -@end defopt - -@defopt blink-matching-delay -This variable specifies the number of seconds for the cursor to remain -at the matching parenthesis. A fraction of a second often gives -good results, but the default is 1, which works on all systems. -@end defopt - -@deffn Command blink-matching-open -This function is the default value of @code{blink-paren-function}. It -assumes that point follows a character with close parenthesis syntax and -moves the cursor momentarily to the matching opening character. If that -character is not already on the screen, it displays the character's -context in the echo area. To avoid long delays, this function does not -search farther than @code{blink-matching-paren-distance} characters. - -Here is an example of calling this function explicitly. - -@smallexample -@group -(defun interactive-blink-matching-open () - "Indicate momentarily the start of sexp before point." - (interactive) -@end group -@group - (let ((blink-matching-paren-distance - (buffer-size)) - (blink-matching-paren t)) - (blink-matching-open))) -@end group -@end smallexample -@end deffn - -@node Character Display -@section Character Display - - This section describes how characters are actually displayed by -Emacs. Typically, a character is displayed as a @dfn{glyph} (a -graphical symbol which occupies one character position on the screen), -whose appearance corresponds to the character itself. For example, -the character @samp{a} (character code 97) is displayed as @samp{a}. -Some characters, however, are displayed specially. For example, the -formfeed character (character code 12) is usually displayed as a -sequence of two glyphs, @samp{^L}, while the newline character -(character code 10) starts a new screen line. - - You can modify how each character is displayed by defining a -@dfn{display table}, which maps each character code into a sequence of -glyphs. @xref{Display Tables}. - -@menu -* Usual Display:: The usual conventions for displaying characters. -* Display Tables:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. -* Glyphless Chars:: How glyphless characters are drawn. -@end menu - -@node Usual Display -@subsection Usual Display Conventions - - Here are the conventions for displaying each character code (in the -absence of a display table, which can override these -@iftex -conventions). -@end iftex -@ifnottex -conventions; @pxref{Display Tables}). -@end ifnottex - -@cindex printable ASCII characters -@itemize @bullet -@item -The @dfn{printable @acronym{ASCII} characters}, character codes 32 -through 126 (consisting of numerals, English letters, and symbols like -@samp{#}) are displayed literally. - -@item -The tab character (character code 9) displays as whitespace stretching -up to the next tab stop column. @xref{Text Display,,, emacs, The GNU -Emacs Manual}. The variable @code{tab-width} controls the number of -spaces per tab stop (see below). - -@item -The newline character (character code 10) has a special effect: it -ends the preceding line and starts a new line. - -@cindex ASCII control characters -@item -The non-printable @dfn{@acronym{ASCII} control characters}---character -codes 0 through 31, as well as the @key{DEL} character (character code -127)---display in one of two ways according to the variable -@code{ctl-arrow}. If this variable is non-@code{nil} (the default), -these characters are displayed as sequences of two glyphs, where the -first glyph is @samp{^} (a display table can specify a glyph to use -instead of @samp{^}); e.g.@: the @key{DEL} character is displayed as -@samp{^?}. - -If @code{ctl-arrow} is @code{nil}, these characters are displayed as -octal escapes (see below). - -This rule also applies to carriage return (character code 13), if that -character appears in the buffer. But carriage returns usually do not -appear in buffer text; they are eliminated as part of end-of-line -conversion (@pxref{Coding System Basics}). - -@cindex octal escapes -@item -@dfn{Raw bytes} are non-@acronym{ASCII} characters with codes 128 -through 255 (@pxref{Text Representations}). These characters display -as @dfn{octal escapes}: sequences of four glyphs, where the first -glyph is the @acronym{ASCII} code for @samp{\}, and the others are -digit characters representing the character code in octal. (A display -table can specify a glyph to use instead of @samp{\}.) - -@item -Each non-@acronym{ASCII} character with code above 255 is displayed -literally, if the terminal supports it. If the terminal does not -support it, the character is said to be @dfn{glyphless}, and it is -usually displayed using a placeholder glyph. For example, if a -graphical terminal has no font for a character, Emacs usually displays -a box containing the character code in hexadecimal. @xref{Glyphless -Chars}. -@end itemize - - The above display conventions apply even when there is a display -table, for any character whose entry in the active display table is -@code{nil}. Thus, when you set up a display table, you need only -specify the characters for which you want special behavior. - - The following variables affect how certain characters are displayed -on the screen. Since they change the number of columns the characters -occupy, they also affect the indentation functions. They also affect -how the mode line is displayed; if you want to force redisplay of the -mode line using the new values, call the function -@code{force-mode-line-update} (@pxref{Mode Line Format}). - -@defopt ctl-arrow -@cindex control characters in display -This buffer-local variable controls how control characters are -displayed. If it is non-@code{nil}, they are displayed as a caret -followed by the character: @samp{^A}. If it is @code{nil}, they are -displayed as octal escapes: a backslash followed by three octal -digits, as in @samp{\001}. -@end defopt - -@defopt tab-width -The value of this buffer-local variable is the spacing between tab -stops used for displaying tab characters in Emacs buffers. The value -is in units of columns, and the default is 8. Note that this feature -is completely independent of the user-settable tab stops used by the -command @code{tab-to-tab-stop}. @xref{Indent Tabs}. -@end defopt - -@node Display Tables -@subsection Display Tables - -@cindex display table - A display table is a special-purpose char-table -(@pxref{Char-Tables}), with @code{display-table} as its subtype, which -is used to override the usual character display conventions. This -section describes how to make, inspect, and assign elements to a -display table object. - -@defun make-display-table -This creates and returns a display table. The table initially has -@code{nil} in all elements. -@end defun - - The ordinary elements of the display table are indexed by character -codes; the element at index @var{c} says how to display the character -code @var{c}. The value should be @code{nil} (which means to display -the character @var{c} according to the usual display conventions; -@pxref{Usual Display}), or a vector of glyph codes (which means to -display the character @var{c} as those glyphs; @pxref{Glyphs}). - - @strong{Warning:} if you use the display table to change the display -of newline characters, the whole buffer will be displayed as one long -``line''. - - The display table also has six ``extra slots'' which serve special -purposes. Here is a table of their meanings; @code{nil} in any slot -means to use the default for that slot, as stated below. - -@table @asis -@item 0 -The glyph for the end of a truncated screen line (the default for this -is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses -arrows in the fringes to indicate truncation, so the display table has -no effect. - -@item 1 -The glyph for the end of a continued line (the default is @samp{\}). -On graphical terminals, Emacs uses curved arrows in the fringes to -indicate continuation, so the display table has no effect. - -@item 2 -The glyph for indicating a character displayed as an octal character -code (the default is @samp{\}). - -@item 3 -The glyph for indicating a control character (the default is @samp{^}). - -@item 4 -A vector of glyphs for indicating the presence of invisible lines (the -default is @samp{...}). @xref{Selective Display}. - -@item 5 -The glyph used to draw the border between side-by-side windows (the -default is @samp{|}). @xref{Splitting Windows}. This takes effect only -when there are no scroll bars; if scroll bars are supported and in use, -a scroll bar separates the two windows. -@end table - - For example, here is how to construct a display table that mimics -the effect of setting @code{ctl-arrow} to a non-@code{nil} value -(@pxref{Glyphs}, for the function @code{make-glyph-code}): - -@example -(setq disptab (make-display-table)) -(dotimes (i 32) - (or (= i ?\t) - (= i ?\n) - (aset disptab i - (vector (make-glyph-code ?^ 'escape-glyph) - (make-glyph-code (+ i 64) 'escape-glyph))))) -(aset disptab 127 - (vector (make-glyph-code ?^ 'escape-glyph) - (make-glyph-code ?? 'escape-glyph))))) -@end example - -@defun display-table-slot display-table slot -This function returns the value of the extra slot @var{slot} of -@var{display-table}. The argument @var{slot} may be a number from 0 to -5 inclusive, or a slot name (symbol). Valid symbols are -@code{truncation}, @code{wrap}, @code{escape}, @code{control}, -@code{selective-display}, and @code{vertical-border}. -@end defun - -@defun set-display-table-slot display-table slot value -This function stores @var{value} in the extra slot @var{slot} of -@var{display-table}. The argument @var{slot} may be a number from 0 to -5 inclusive, or a slot name (symbol). Valid symbols are -@code{truncation}, @code{wrap}, @code{escape}, @code{control}, -@code{selective-display}, and @code{vertical-border}. -@end defun - -@defun describe-display-table display-table -This function displays a description of the display table -@var{display-table} in a help buffer. -@end defun - -@deffn Command describe-current-display-table -This command displays a description of the current display table in a -help buffer. -@end deffn - -@node Active Display Table -@subsection Active Display Table -@cindex active display table - - Each window can specify a display table, and so can each buffer. -The window's display table, if there is one, takes precedence over the -buffer's display table. If neither exists, Emacs tries to use the -standard display table; if that is @code{nil}, Emacs uses the usual -character display conventions (@pxref{Usual Display}). - - Note that display tables affect how the mode line is displayed, so -if you want to force redisplay of the mode line using a new display -table, call @code{force-mode-line-update} (@pxref{Mode Line Format}). - -@defun window-display-table &optional window -This function returns @var{window}'s display table, or @code{nil} if -there is none. The default for @var{window} is the selected window. -@end defun - -@defun set-window-display-table window table -This function sets the display table of @var{window} to @var{table}. -The argument @var{table} should be either a display table or -@code{nil}. -@end defun - -@defvar buffer-display-table -This variable is automatically buffer-local in all buffers; its value -specifies the buffer's display table. If it is @code{nil}, there is -no buffer display table. -@end defvar - -@defvar standard-display-table -The value of this variable is the standard display table, which is -used when Emacs is displaying a buffer in a window with neither a -window display table nor a buffer display table defined. Its default -is @code{nil}. -@end defvar - -The @file{disp-table} library defines several functions for changing -the standard display table. - -@node Glyphs -@subsection Glyphs -@cindex glyph - - A @dfn{glyph} is a graphical symbol which occupies a single -character position on the screen. Each glyph is represented in Lisp -as a @dfn{glyph code}, which specifies a character and optionally a -face to display it in (@pxref{Faces}). The main use of glyph codes is -as the entries of display tables (@pxref{Display Tables}). The -following functions are used to manipulate glyph codes: - -@defun make-glyph-code char &optional face -This function returns a glyph code representing char @var{char} with -face @var{face}. If @var{face} is omitted or @code{nil}, the glyph -uses the default face; in that case, the glyph code is an integer. If -@var{face} is non-@code{nil}, the glyph code is not necessarily an -integer object. -@end defun - -@defun glyph-char glyph -This function returns the character of glyph code @var{glyph}. -@end defun - -@defun glyph-face glyph -This function returns face of glyph code @var{glyph}, or @code{nil} if -@var{glyph} uses the default face. -@end defun - -@ifnottex - You can set up a @dfn{glyph table} to change how glyph codes are -actually displayed on text terminals. This feature is semi-obsolete; -use @code{glyphless-char-display} instead (@pxref{Glyphless Chars}). - -@defvar glyph-table -The value of this variable, if non-@code{nil}, is the current glyph -table. It takes effect only on character terminals; on graphical -displays, all glyphs are displayed literally. The glyph table should -be a vector whose @var{g}th element specifies how to display glyph -code @var{g}, where @var{g} is the glyph code for a glyph whose face -is unspecified. Each element should be one of the following: - -@table @asis -@item @code{nil} -Display this glyph literally. - -@item a string -Display this glyph by sending the specified string to the terminal. - -@item a glyph code -Display the specified glyph code instead. -@end table - -Any integer glyph code greater than or equal to the length of the -glyph table is displayed literally. -@end defvar -@end ifnottex - -@node Glyphless Chars -@subsection Glyphless Character Display -@cindex glyphless characters - - @dfn{Glyphless characters} are characters which are displayed in a -special way, e.g.@: as a box containing a hexadecimal code, instead of -being displayed literally. These include characters which are -explicitly defined to be glyphless, as well as characters for which -there is no available font (on a graphical display), and characters -which cannot be encoded by the terminal's coding system (on a text -terminal). - -@defvar glyphless-char-display -The value of this variable is a char-table which defines glyphless -characters and how they are displayed. Each entry must be one of the -following display methods: - -@table @asis -@item @code{nil} -Display the character in the usual way. - -@item @code{zero-width} -Don't display the character. - -@item @code{thin-space} -Display a thin space, 1-pixel wide on graphical displays, or -1-character wide on text terminals. - -@item @code{empty-box} -Display an empty box. - -@item @code{hex-code} -Display a box containing the Unicode codepoint of the character, in -hexadecimal notation. - -@item an @acronym{ASCII} string -Display a box containing that string. - -@item a cons cell @code{(@var{graphical} . @var{text})} -Display with @var{graphical} on graphical displays, and with -@var{text} on text terminals. Both @var{graphical} and @var{text} -must be one of the display methods described above. -@end table - -@noindent -The @code{thin-space}, @code{empty-box}, @code{hex-code}, and -@acronym{ASCII} string display methods are drawn with the -@code{glyphless-char} face. - -The char-table has one extra slot, which determines how to display any -character that cannot be displayed with any available font, or cannot -be encoded by the terminal's coding system. Its value should be one -of the above display methods, except @code{zero-width} or a cons cell. - -If a character has a non-@code{nil} entry in an active display table, -the display table takes effect; in this case, Emacs does not consult -@code{glyphless-char-display} at all. -@end defvar - -@defopt glyphless-char-display-control -This user option provides a convenient way to set -@code{glyphless-char-display} for groups of similar characters. Do -not set its value directly from Lisp code; the value takes effect only -via a custom @code{:set} function (@pxref{Variable Definitions}), -which updates @code{glyphless-char-display}. - -Its value should be an alist of elements @code{(@var{group} -. @var{method})}, where @var{group} is a symbol specifying a group of -characters, and @var{method} is a symbol specifying how to display -them. - -@var{group} should be one of the following: - -@table @code -@item c0-control -@acronym{ASCII} control characters @code{U+0000} to @code{U+001F}, -excluding the newline and tab characters (normally displayed as escape -sequences like @samp{^A}; @pxref{Text Display,, How Text Is Displayed, -emacs, The GNU Emacs Manual}). - -@item c1-control -Non-@acronym{ASCII}, non-printing characters @code{U+0080} to -@code{U+009F} (normally displayed as octal escape sequences like -@samp{\230}). - -@item format-control -Characters of Unicode General Category `Cf', such as @samp{U+200E} -(Left-to-Right Mark), but excluding characters that have graphic -images, such as @samp{U+00AD} (Soft Hyphen). - -@item no-font -Characters for there is no suitable font, or which cannot be encoded -by the terminal's coding system. -@end table - -@c FIXME: this can also be `acronym', but that's not currently -@c completely implemented; it applies only to the format-control -@c group, and only works if the acronym is in `char-acronym-table'. -The @var{method} symbol should be one of @code{zero-width}, -@code{thin-space}, @code{empty-box}, or @code{hex-code}. These have -the same meanings as in @code{glyphless-char-display}, above. -@end defopt - -@node Beeping -@section Beeping -@cindex bell - - This section describes how to make Emacs ring the bell (or blink the -screen) to attract the user's attention. Be conservative about how -often you do this; frequent bells can become irritating. Also be -careful not to use just beeping when signaling an error is more -appropriate (@pxref{Errors}). - -@defun ding &optional do-not-terminate -@cindex keyboard macro termination -This function beeps, or flashes the screen (see @code{visible-bell} below). -It also terminates any keyboard macro currently executing unless -@var{do-not-terminate} is non-@code{nil}. -@end defun - -@defun beep &optional do-not-terminate -This is a synonym for @code{ding}. -@end defun - -@defopt visible-bell -This variable determines whether Emacs should flash the screen to -represent a bell. Non-@code{nil} means yes, @code{nil} means no. -This is effective on graphical displays, and on text terminals -provided the terminal's Termcap entry defines the visible bell -capability (@samp{vb}). -@end defopt - -@defvar ring-bell-function -If this is non-@code{nil}, it specifies how Emacs should ``ring the -bell''. Its value should be a function of no arguments. If this is -non-@code{nil}, it takes precedence over the @code{visible-bell} -variable. -@end defvar - -@node Window Systems -@section Window Systems - - Emacs works with several window systems, most notably the X Window -System. Both Emacs and X use the term ``window'', but use it -differently. An Emacs frame is a single window as far as X is -concerned; the individual Emacs windows are not known to X at all. - -@defvar window-system -This terminal-local variable tells Lisp programs what window system -Emacs is using for displaying the frame. The possible values are - -@table @code -@item x -@cindex X Window System -Emacs is displaying the frame using X. -@item w32 -Emacs is displaying the frame using native MS-Windows GUI. -@item ns -Emacs is displaying the frame using the Nextstep interface (used on -GNUstep and Mac OS X). -@item pc -Emacs is displaying the frame using MS-DOS direct screen writes. -@item nil -Emacs is displaying the frame on a character-based terminal. -@end table -@end defvar - -@defvar initial-window-system -This variable holds the value of @code{window-system} used for the -first frame created by Emacs during startup. (When Emacs is invoked -with the @option{--daemon} option, it does not create any initial -frames, so @code{initial-window-system} is @code{nil}. @xref{Initial -Options, daemon,, emacs, The GNU Emacs Manual}.) -@end defvar - -@defun window-system &optional frame -This function returns a symbol whose name tells what window system is -used for displaying @var{frame} (which defaults to the currently -selected frame). The list of possible symbols it returns is the same -one documented for the variable @code{window-system} above. -@end defun - - Do @emph{not} use @code{window-system} and -@code{initial-window-system} as predicates or boolean flag variables, -if you want to write code that works differently on text terminals and -graphic displays. That is because @code{window-system} is not a good -indicator of Emacs capabilities on a given display type. Instead, use -@code{display-graphic-p} or any of the other @code{display-*-p} -predicates described in @ref{Display Feature Testing}. - -@defvar window-setup-hook -This variable is a normal hook which Emacs runs after handling the -initialization files. Emacs runs this hook after it has completed -loading your init file, the default initialization file (if -any), and the terminal-specific Lisp code, and running the hook -@code{term-setup-hook}. - -This hook is used for internal purposes: setting up communication with -the window system, and creating the initial window. Users should not -interfere with it. -@end defvar - -@node Bidirectional Display -@section Bidirectional Display -@cindex bidirectional display -@cindex right-to-left text - - Emacs can display text written in scripts, such as Arabic, Farsi, -and Hebrew, whose natural ordering for horizontal text display runs -from right to left. Furthermore, segments of Latin script and digits -embedded in right-to-left text are displayed left-to-right, while -segments of right-to-left script embedded in left-to-right text -(e.g.@: Arabic or Hebrew text in comments or strings in a program -source file) are appropriately displayed right-to-left. We call such -mixtures of left-to-right and right-to-left text @dfn{bidirectional -text}. This section describes the facilities and options for editing -and displaying bidirectional text. - -@cindex logical order -@cindex reading order -@cindex visual order -@cindex unicode bidirectional algorithm -@cindex bidirectional reordering - Text is stored in Emacs buffers and strings in @dfn{logical} (or -@dfn{reading}) order, i.e.@: the order in which a human would read -each character. In right-to-left and bidirectional text, the order in -which characters are displayed on the screen (called @dfn{visual -order}) is not the same as logical order; the characters' screen -positions do not increase monotonically with string or buffer -position. In performing this @dfn{bidirectional reordering}, Emacs -follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}), -which is described in Annex #9 of the Unicode standard -(@url{http://www.unicode.org/reports/tr9/}). Emacs provides a ``Full -Bidirectionality'' class implementation of the @acronym{UBA}. - -@defvar bidi-display-reordering -If the value of this buffer-local variable is non-@code{nil} (the -default), Emacs performs bidirectional reordering for display. The -reordering affects buffer text, as well as display strings and overlay -strings from text and overlay properties in the buffer (@pxref{Overlay -Properties}, and @pxref{Display Property}). If the value is -@code{nil}, Emacs does not perform bidirectional reordering in the -buffer. - -The default value of @code{bidi-display-reordering} controls the -reordering of strings which are not directly supplied by a buffer, -including the text displayed in mode lines (@pxref{Mode Line Format}) -and header lines (@pxref{Header Lines}). -@end defvar - -@cindex unibyte buffers, and bidi reordering - Emacs never reorders the text of a unibyte buffer, even if -@code{bidi-display-reordering} is non-@code{nil} in the buffer. This -is because unibyte buffers contain raw bytes, not characters, and thus -lack the directionality properties required for reordering. -Therefore, to test whether text in a buffer will be reordered for -display, it is not enough to test the value of -@code{bidi-display-reordering} alone. The correct test is this: - -@example - (if (and enable-multibyte-characters - bidi-display-reordering) - ;; Buffer is being reordered for display - ) -@end example - - However, unibyte display and overlay strings @emph{are} reordered if -their parent buffer is reordered. This is because plain-@sc{ascii} -strings are stored by Emacs as unibyte strings. If a unibyte display -or overlay string includes non-@sc{ascii} characters, these characters -are assumed to have left-to-right direction. - -@cindex display properties, and bidi reordering of text - Text covered by @code{display} text properties, by overlays with -@code{display} properties whose value is a string, and by any other -properties that replace buffer text, is treated as a single unit when -it is reordered for display. That is, the entire chunk of text -covered by these properties is reordered together. Moreover, the -bidirectional properties of the characters in such a chunk of text are -ignored, and Emacs reorders them as if they were replaced with a -single character @code{U+FFFC}, known as the @dfn{Object Replacement -Character}. This means that placing a display property over a portion -of text may change the way that the surrounding text is reordered for -display. To prevent this unexpected effect, always place such -properties on text whose directionality is identical with text that -surrounds it. - -@cindex base direction of a paragraph - Each paragraph of bidirectional text has a @dfn{base direction}, -either right-to-left or left-to-right. Left-to-right paragraphs are -displayed beginning at the left margin of the window, and are -truncated or continued when the text reaches the right margin. -Right-to-left paragraphs are displayed beginning at the right margin, -and are continued or truncated at the left margin. - - By default, Emacs determines the base direction of each paragraph by -looking at the text at its beginning. The precise method of -determining the base direction is specified by the @acronym{UBA}; in a -nutshell, the first character in a paragraph that has an explicit -directionality determines the base direction of the paragraph. -However, sometimes a buffer may need to force a certain base direction -for its paragraphs. For example, buffers containing program source -code should force all paragraphs to be displayed left-to-right. You -can use following variable to do this: - -@defvar bidi-paragraph-direction -If the value of this buffer-local variable is the symbol -@code{right-to-left} or @code{left-to-right}, all paragraphs in the -buffer are assumed to have that specified direction. Any other value -is equivalent to @code{nil} (the default), which means to determine -the base direction of each paragraph from its contents. - -@cindex @code{prog-mode}, and @code{bidi-paragraph-direction} -Modes for program source code should set this to @code{left-to-right}. -Prog mode does this by default, so modes derived from Prog mode do not -need to set this explicitly (@pxref{Basic Major Modes}). -@end defvar - -@defun current-bidi-paragraph-direction &optional buffer -This function returns the paragraph direction at point in the named -@var{buffer}. The returned value is a symbol, either -@code{left-to-right} or @code{right-to-left}. If @var{buffer} is -omitted or @code{nil}, it defaults to the current buffer. If the -buffer-local value of the variable @code{bidi-paragraph-direction} is -non-@code{nil}, the returned value will be identical to that value; -otherwise, the returned value reflects the paragraph direction -determined dynamically by Emacs. For buffers whose value of -@code{bidi-display-reordering} is @code{nil} as well as unibyte -buffers, this function always returns @code{left-to-right}. -@end defun - -@cindex layout on display, and bidirectional text -@cindex jumbled display of bidirectional text -@cindex concatenating bidirectional strings - Bidirectional reordering can have surprising and unpleasant effects -when two strings with bidirectional content are juxtaposed in a -buffer, or otherwise programmatically concatenated into a string of -text. A typical problematic case is when a buffer consists of -sequences of text ``fields'' separated by whitespace or punctuation -characters, like Buffer Menu mode or Rmail Summary Mode. Because the -punctuation characters used as separators have @dfn{weak -directionality}, they take on the directionality of surrounding text. -As result, a numeric field that follows a field with bidirectional -content can be displayed @emph{to the left} of the preceding field, -messing up the expected layout. There are several ways to avoid this -problem: - -@itemize @minus -@item -Append the special character @code{U+200E}, LEFT-TO-RIGHT MARK, or -@acronym{LRM}, to the end of each field that may have bidirectional -content, or prepend it to the beginning of the following field. The -function @code{bidi-string-mark-left-to-right}, described below, comes -in handy for this purpose. (In a right-to-left paragraph, use -@code{U+200F}, RIGHT-TO-LEFT MARK, or @acronym{RLM}, instead.) This -is one of the solutions recommended by the UBA. - -@item -Include the tab character in the field separator. The tab character -plays the role of @dfn{segment separator} in bidirectional reordering, -causing the text on either side to be reordered separately. - -@cindex @code{space} display spec, and bidirectional text -@item -Separate fields with a @code{display} property or overlay with a -property value of the form @code{(space . PROPS)} (@pxref{Specified -Space}). Emacs treats this display specification as a @dfn{paragraph -separator}, and reorders the text on either side separately. -@end itemize - -@defun bidi-string-mark-left-to-right string -This function returns its argument @var{string}, possibly modified, -such that the result can be safely concatenated with another string, -or juxtaposed with another string in a buffer, without disrupting the -relative layout of this string and the next one on display. If the -string returned by this function is displayed as part of a -left-to-right paragraph, it will always appear on display to the left -of the text that follows it. The function works by examining the -characters of its argument, and if any of those characters could cause -reordering on display, the function appends the @acronym{LRM} -character to the string. The appended @acronym{LRM} character is made -invisible by giving it an @code{invisible} text property of @code{t} -(@pxref{Invisible Text}). -@end defun - - The reordering algorithm uses the bidirectional properties of the -characters stored as their @code{bidi-class} property -(@pxref{Character Properties}). Lisp programs can change these -properties by calling the @code{put-char-code-property} function. -However, doing this requires a thorough understanding of the -@acronym{UBA}, and is therefore not recommended. Any changes to the -bidirectional properties of a character have global effect: they -affect all Emacs frames and windows. - - Similarly, the @code{mirroring} property is used to display the -appropriate mirrored character in the reordered text. Lisp programs -can affect the mirrored display by changing this property. Again, any -such changes affect all of Emacs display. diff --git a/doc/lispref/doclicense.texi b/doc/lispref/doclicense.texi deleted file mode 100644 index 0c2d47827a9..00000000000 --- a/doc/lispref/doclicense.texi +++ /dev/null @@ -1,510 +0,0 @@ -@c -*-texinfo-*- -@c The GNU Free Documentation License. -@node GNU Free Documentation License, GPL, Antinews, Top - -@appendix GNU Free Documentation License -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008, 2009 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input -format, @acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML}, -PostScript or @acronym{PDF} designed for human modification. Examples -of transparent image formats include @acronym{PNG}, @acronym{XCF} and -@acronym{JPG}. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, @acronym{SGML} or -@acronym{XML} for which the @acronym{DTD} and/or processing tools are -not generally available, and the machine-generated @acronym{HTML}, -PostScript or @acronym{PDF} produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.'' line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi deleted file mode 100644 index e97e90f947b..00000000000 --- a/doc/lispref/edebug.texi +++ /dev/null @@ -1,1633 +0,0 @@ -@comment -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1992-1994, 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. - -@c This file can also be used by an independent Edebug User -@c Manual in which case the Edebug node below should be used -@c with the following links to the Bugs section and to the top level: - -@c , Bugs and Todo List, Top, Top - -@node Edebug, Syntax Errors, Debugger, Debugging -@section Edebug -@cindex Edebug debugging facility - - Edebug is a source-level debugger for Emacs Lisp programs, with which -you can: - -@itemize @bullet -@item -Step through evaluation, stopping before and after each expression. - -@item -Set conditional or unconditional breakpoints. - -@item -Stop when a specified condition is true (the global break event). - -@item -Trace slow or fast, stopping briefly at each stop point, or -at each breakpoint. - -@item -Display expression results and evaluate expressions as if outside of -Edebug. - -@item -Automatically re-evaluate a list of expressions and -display their results each time Edebug updates the display. - -@item -Output trace information on function calls and returns. - -@item -Stop when an error occurs. - -@item -Display a backtrace, omitting Edebug's own frames. - -@item -Specify argument evaluation for macros and defining forms. - -@item -Obtain rudimentary coverage testing and frequency counts. -@end itemize - -The first three sections below should tell you enough about Edebug to -start using it. - -@menu -* Using Edebug:: Introduction to use of Edebug. -* Instrumenting:: You must instrument your code - in order to debug it with Edebug. -* Modes: Edebug Execution Modes. Execution modes, stopping more or less often. -* Jumping:: Commands to jump to a specified place. -* Misc: Edebug Misc. Miscellaneous commands. -* Breaks:: Setting breakpoints to make the program stop. -* Trapping Errors:: Trapping errors with Edebug. -* Views: Edebug Views. Views inside and outside of Edebug. -* Eval: Edebug Eval. Evaluating expressions within Edebug. -* Eval List:: Expressions whose values are displayed - each time you enter Edebug. -* Printing in Edebug:: Customization of printing. -* Trace Buffer:: How to produce trace output in a buffer. -* Coverage Testing:: How to test evaluation coverage. -* The Outside Context:: Data that Edebug saves and restores. -* Edebug and Macros:: Specifying how to handle macro calls. -* Options: Edebug Options. Option variables for customizing Edebug. -@end menu - -@node Using Edebug -@subsection Using Edebug - - To debug a Lisp program with Edebug, you must first @dfn{instrument} -the Lisp code that you want to debug. A simple way to do this is to -first move point into the definition of a function or macro and then do -@kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument). See -@ref{Instrumenting}, for alternative ways to instrument code. - - Once a function is instrumented, any call to the function activates -Edebug. Depending on which Edebug execution mode you have selected, -activating Edebug may stop execution and let you step through the -function, or it may update the display and continue execution while -checking for debugging commands. The default execution mode is step, -which stops execution. @xref{Edebug Execution Modes}. - - Within Edebug, you normally view an Emacs buffer showing the source of -the Lisp code you are debugging. This is referred to as the @dfn{source -code buffer}, and it is temporarily read-only. - - An arrow in the left fringe indicates the line where the function is -executing. Point initially shows where within the line the function is -executing, but this ceases to be true if you move point yourself. - - If you instrument the definition of @code{fac} (shown below) and then -execute @code{(fac 3)}, here is what you would normally see. Point is -at the open-parenthesis before @code{if}. - -@example -(defun fac (n) -=>@point{}(if (< 0 n) - (* n (fac (1- n))) - 1)) -@end example - -@cindex stop points -The places within a function where Edebug can stop execution are called -@dfn{stop points}. These occur both before and after each subexpression -that is a list, and also after each variable reference. -Here we use periods to show the stop points in the function -@code{fac}: - -@example -(defun fac (n) - .(if .(< 0 n.). - .(* n. .(fac .(1- n.).).). - 1).) -@end example - -The special commands of Edebug are available in the source code buffer -in addition to the commands of Emacs Lisp mode. For example, you can -type the Edebug command @key{SPC} to execute until the next stop point. -If you type @key{SPC} once after entry to @code{fac}, here is the -display you will see: - -@example -(defun fac (n) -=>(if @point{}(< 0 n) - (* n (fac (1- n))) - 1)) -@end example - -When Edebug stops execution after an expression, it displays the -expression's value in the echo area. - -Other frequently used commands are @kbd{b} to set a breakpoint at a stop -point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to -exit Edebug and return to the top-level command loop. Type @kbd{?} to -display a list of all Edebug commands. - -@node Instrumenting -@subsection Instrumenting for Edebug - - In order to use Edebug to debug Lisp code, you must first -@dfn{instrument} the code. Instrumenting code inserts additional code -into it, to invoke Edebug at the proper places. - -@kindex C-M-x -@findex eval-defun (Edebug) - When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a -prefix argument on a function definition, it instruments the -definition before evaluating it. (This does not modify the source -code itself.) If the variable @code{edebug-all-defs} is -non-@code{nil}, that inverts the meaning of the prefix argument: in -this case, @kbd{C-M-x} instruments the definition @emph{unless} it has -a prefix argument. The default value of @code{edebug-all-defs} is -@code{nil}. The command @kbd{M-x edebug-all-defs} toggles the value -of the variable @code{edebug-all-defs}. - -@findex eval-region @r{(Edebug)} -@findex eval-buffer @r{(Edebug)} -@findex eval-current-buffer @r{(Edebug)} - If @code{edebug-all-defs} is non-@code{nil}, then the commands -@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer} -also instrument any definitions they evaluate. Similarly, -@code{edebug-all-forms} controls whether @code{eval-region} should -instrument @emph{any} form, even non-defining forms. This doesn't apply -to loading or evaluations in the minibuffer. The command @kbd{M-x -edebug-all-forms} toggles this option. - -@findex edebug-eval-top-level-form - Another command, @kbd{M-x edebug-eval-top-level-form}, is available to -instrument any top-level form regardless of the values of -@code{edebug-all-defs} and @code{edebug-all-forms}. - - While Edebug is active, the command @kbd{I} -(@code{edebug-instrument-callee}) instruments the definition of the -function or macro called by the list form after point, if it is not already -instrumented. This is possible only if Edebug knows where to find the -source for that function; for this reason, after loading Edebug, -@code{eval-region} records the position of every definition it -evaluates, even if not instrumenting it. See also the @kbd{i} command -(@pxref{Jumping}), which steps into the call after instrumenting the -function. - - Edebug knows how to instrument all the standard special forms, -@code{interactive} forms with an expression argument, anonymous lambda -expressions, and other defining forms. However, Edebug cannot determine -on its own what a user-defined macro will do with the arguments of a -macro call, so you must provide that information using Edebug -specifications; for details, @pxref{Edebug and Macros}. - - When Edebug is about to instrument code for the first time in a -session, it runs the hook @code{edebug-setup-hook}, then sets it to -@code{nil}. You can use this to load Edebug specifications -associated with a package you are using, but only when you use Edebug. - -@findex eval-expression @r{(Edebug)} - To remove instrumentation from a definition, simply re-evaluate its -definition in a way that does not instrument. There are two ways of -evaluating forms that never instrument them: from a file with -@code{load}, and from the minibuffer with @code{eval-expression} -(@kbd{M-:}). - - If Edebug detects a syntax error while instrumenting, it leaves point -at the erroneous code and signals an @code{invalid-read-syntax} error. -@c FIXME? I can't see that it "leaves point at the erroneous code". - - @xref{Edebug Eval}, for other evaluation functions available -inside of Edebug. - -@node Edebug Execution Modes -@subsection Edebug Execution Modes - -@cindex Edebug execution modes -Edebug supports several execution modes for running the program you are -debugging. We call these alternatives @dfn{Edebug execution modes}; do -not confuse them with major or minor modes. The current Edebug execution mode -determines how far Edebug continues execution before stopping---whether -it stops at each stop point, or continues to the next breakpoint, for -example---and how much Edebug displays the progress of the evaluation -before it stops. - -Normally, you specify the Edebug execution mode by typing a command to -continue the program in a certain mode. Here is a table of these -commands; all except for @kbd{S} resume execution of the program, at -least for a certain distance. - -@table @kbd -@item S -Stop: don't execute any more of the program, but wait for more -Edebug commands (@code{edebug-stop}). -@c FIXME Does not work. http://debbugs.gnu.org/9764 - -@item @key{SPC} -Step: stop at the next stop point encountered (@code{edebug-step-mode}). - -@item n -Next: stop at the next stop point encountered after an expression -(@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in -@ref{Jumping}. - -@item t -Trace: pause (normally one second) at each Edebug stop point -(@code{edebug-trace-mode}). - -@item T -Rapid trace: update the display at each stop point, but don't actually -pause (@code{edebug-Trace-fast-mode}). - -@item g -Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}. - -@item c -Continue: pause one second at each breakpoint, and then continue -(@code{edebug-continue-mode}). - -@item C -Rapid continue: move point to each breakpoint, but don't pause -(@code{edebug-Continue-fast-mode}). - -@item G -Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You -can still stop the program by typing @kbd{S}, or any editing command. -@end table - -In general, the execution modes earlier in the above list run the -program more slowly or stop sooner than the modes later in the list. - -While executing or tracing, you can interrupt the execution by typing -any Edebug command. Edebug stops the program at the next stop point and -then executes the command you typed. For example, typing @kbd{t} during -execution switches to trace mode at the next stop point. You can use -@kbd{S} to stop execution without doing anything else. - -If your function happens to read input, a character you type intending -to interrupt execution may be read by the function instead. You can -avoid such unintended results by paying attention to when your program -wants input. - -@cindex keyboard macros (Edebug) -Keyboard macros containing the commands in this section do not -completely work: exiting from Edebug, to resume the program, loses track -of the keyboard macro. This is not easy to fix. Also, defining or -executing a keyboard macro outside of Edebug does not affect commands -inside Edebug. This is usually an advantage. See also the -@code{edebug-continue-kbd-macro} option in @ref{Edebug Options}. - -When you enter a new Edebug level, the initial execution mode comes -from the value of the variable @code{edebug-initial-mode} -(@pxref{Edebug Options}). By default, this specifies step mode. Note -that you may reenter the same Edebug level several times if, for -example, an instrumented function is called several times from one -command. - -@defopt edebug-sit-for-seconds -This option specifies how many seconds to wait between execution steps -in trace mode or continue mode. The default is 1 second. -@end defopt - -@node Jumping -@subsection Jumping - - The commands described in this section execute until they reach a -specified location. All except @kbd{i} make a temporary breakpoint to -establish the place to stop, then switch to go mode. Any other -breakpoint reached before the intended stop point will also stop -execution. @xref{Breakpoints}, for the details on breakpoints. - - These commands may fail to work as expected in case of nonlocal exit, -as that can bypass the temporary breakpoint where you expected the -program to stop. - -@table @kbd -@item h -Proceed to the stop point near where point is (@code{edebug-goto-here}). - -@item f -Run the program for one expression -(@code{edebug-forward-sexp}). - -@item o -Run the program until the end of the containing sexp (@code{edebug-step-out}). - -@item i -Step into the function or macro called by the form after point -(@code{edebug-step-in}). -@end table - -The @kbd{h} command proceeds to the stop point at or after the current -location of point, using a temporary breakpoint. - -The @kbd{f} command runs the program forward over one expression. More -precisely, it sets a temporary breakpoint at the position that -@code{forward-sexp} would reach, then executes in go mode so that -the program will stop at breakpoints. - -With a prefix argument @var{n}, the temporary breakpoint is placed -@var{n} sexps beyond point. If the containing list ends before @var{n} -more elements, then the place to stop is after the containing -expression. - -You must check that the position @code{forward-sexp} finds is a place -that the program will really get to. In @code{cond}, for example, -this may not be true. - -For flexibility, the @kbd{f} command does @code{forward-sexp} starting -at point, rather than at the stop point. If you want to execute one -expression @emph{from the current stop point}, first type @kbd{w} -(@code{edebug-where}) to move point there, and then type @kbd{f}. - -The @kbd{o} command continues ``out of'' an expression. It places a -temporary breakpoint at the end of the sexp containing point. If the -containing sexp is a function definition itself, @kbd{o} continues until -just before the last sexp in the definition. If that is where you are -now, it returns from the function and then stops. In other words, this -command does not exit the currently executing function unless you are -positioned after the last sexp. - -The @kbd{i} command steps into the function or macro called by the list -form after point, and stops at its first stop point. Note that the form -need not be the one about to be evaluated. But if the form is a -function call about to be evaluated, remember to use this command before -any of the arguments are evaluated, since otherwise it will be too late. - -The @kbd{i} command instruments the function or macro it's supposed to -step into, if it isn't instrumented already. This is convenient, but keep -in mind that the function or macro remains instrumented unless you explicitly -arrange to deinstrument it. - -@node Edebug Misc -@subsection Miscellaneous Edebug Commands - - Some miscellaneous Edebug commands are described here. - -@table @kbd -@item ? -Display the help message for Edebug (@code{edebug-help}). - -@item C-] -Abort one level back to the previous command level -(@code{abort-recursive-edit}). - -@item q -Return to the top level editor command loop (@code{top-level}). This -exits all recursive editing levels, including all levels of Edebug -activity. However, instrumented code protected with -@code{unwind-protect} or @code{condition-case} forms may resume -debugging. - -@item Q -Like @kbd{q}, but don't stop even for protected code -(@code{edebug-top-level-nonstop}). - -@item r -Redisplay the most recently known expression result in the echo area -(@code{edebug-previous-result}). - -@item d -Display a backtrace, excluding Edebug's own functions for clarity -(@code{edebug-backtrace}). - -You cannot use debugger commands in the backtrace buffer in Edebug as -you would in the standard debugger. - -The backtrace buffer is killed automatically when you continue -execution. -@end table - -You can invoke commands from Edebug that activate Edebug again -recursively. Whenever Edebug is active, you can quit to the top level -with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can -display a backtrace of all the pending evaluations with @kbd{d}. - -@node Breaks -@subsection Breaks - -Edebug's step mode stops execution when the next stop point is reached. -There are three other ways to stop Edebug execution once it has started: -breakpoints, the global break condition, and source breakpoints. - -@menu -* Breakpoints:: Breakpoints at stop points. -* Global Break Condition:: Breaking on an event. -* Source Breakpoints:: Embedding breakpoints in source code. -@end menu - -@node Breakpoints -@subsubsection Edebug Breakpoints - -@cindex breakpoints (Edebug) -While using Edebug, you can specify @dfn{breakpoints} in the program you -are testing: these are places where execution should stop. You can set a -breakpoint at any stop point, as defined in @ref{Using Edebug}. For -setting and unsetting breakpoints, the stop point that is affected is -the first one at or after point in the source code buffer. Here are the -Edebug commands for breakpoints: - -@table @kbd -@item b -Set a breakpoint at the stop point at or after point -(@code{edebug-set-breakpoint}). If you use a prefix argument, the -breakpoint is temporary---it turns off the first time it stops the -program. - -@item u -Unset the breakpoint (if any) at the stop point at or after -point (@code{edebug-unset-breakpoint}). - -@item x @var{condition} @key{RET} -Set a conditional breakpoint which stops the program only if -evaluating @var{condition} produces a non-@code{nil} value -(@code{edebug-set-conditional-breakpoint}). With a prefix argument, -the breakpoint is temporary. - -@item B -Move point to the next breakpoint in the current definition -(@code{edebug-next-breakpoint}). -@end table - -While in Edebug, you can set a breakpoint with @kbd{b} and unset one -with @kbd{u}. First move point to the Edebug stop point of your choice, -then type @kbd{b} or @kbd{u} to set or unset a breakpoint there. -Unsetting a breakpoint where none has been set has no effect. - -Re-evaluating or reinstrumenting a definition removes all of its -previous breakpoints. - -A @dfn{conditional breakpoint} tests a condition each time the program -gets there. Any errors that occur as a result of evaluating the -condition are ignored, as if the result were @code{nil}. To set a -conditional breakpoint, use @kbd{x}, and specify the condition -expression in the minibuffer. Setting a conditional breakpoint at a -stop point that has a previously established conditional breakpoint puts -the previous condition expression in the minibuffer so you can edit it. - -You can make a conditional or unconditional breakpoint -@dfn{temporary} by using a prefix argument with the command to set the -breakpoint. When a temporary breakpoint stops the program, it is -automatically unset. - -Edebug always stops or pauses at a breakpoint, except when the Edebug -mode is Go-nonstop. In that mode, it ignores breakpoints entirely. - -To find out where your breakpoints are, use the @kbd{B} command, which -moves point to the next breakpoint following point, within the same -function, or to the first breakpoint if there are no following -breakpoints. This command does not continue execution---it just moves -point in the buffer. - -@node Global Break Condition -@subsubsection Global Break Condition - -@cindex stopping on events -@cindex global break condition - A @dfn{global break condition} stops execution when a specified -condition is satisfied, no matter where that may occur. Edebug -evaluates the global break condition at every stop point; if it -evaluates to a non-@code{nil} value, then execution stops or pauses -depending on the execution mode, as if a breakpoint had been hit. If -evaluating the condition gets an error, execution does not stop. - -@findex edebug-set-global-break-condition - The condition expression is stored in -@code{edebug-global-break-condition}. You can specify a new expression -using the @kbd{X} command from the source code buffer while Edebug is -active, or using @kbd{C-x X X} from any buffer at any time, as long as -Edebug is loaded (@code{edebug-set-global-break-condition}). - - The global break condition is the simplest way to find where in your -code some event occurs, but it makes code run much more slowly. So you -should reset the condition to @code{nil} when not using it. - -@node Source Breakpoints -@subsubsection Source Breakpoints - -@findex edebug -@cindex source breakpoints - All breakpoints in a definition are forgotten each time you -reinstrument it. If you wish to make a breakpoint that won't be -forgotten, you can write a @dfn{source breakpoint}, which is simply a -call to the function @code{edebug} in your source code. You can, of -course, make such a call conditional. For example, in the @code{fac} -function, you can insert the first line as shown below, to stop when the -argument reaches zero: - -@example -(defun fac (n) - (if (= n 0) (edebug)) - (if (< 0 n) - (* n (fac (1- n))) - 1)) -@end example - - When the @code{fac} definition is instrumented and the function is -called, the call to @code{edebug} acts as a breakpoint. Depending on -the execution mode, Edebug stops or pauses there. - - If no instrumented code is being executed when @code{edebug} is called, -that function calls @code{debug}. -@c This may not be a good idea anymore. - -@node Trapping Errors -@subsection Trapping Errors - - Emacs normally displays an error message when an error is signaled and -not handled with @code{condition-case}. While Edebug is active and -executing instrumented code, it normally responds to all unhandled -errors. You can customize this with the options @code{edebug-on-error} -and @code{edebug-on-quit}; see @ref{Edebug Options}. - - When Edebug responds to an error, it shows the last stop point -encountered before the error. This may be the location of a call to a -function which was not instrumented, and within which the error actually -occurred. For an unbound variable error, the last known stop point -might be quite distant from the offending variable reference. In that -case, you might want to display a full backtrace (@pxref{Edebug Misc}). - -@c Edebug should be changed for the following: -- dan - If you change @code{debug-on-error} or @code{debug-on-quit} while -Edebug is active, these changes will be forgotten when Edebug becomes -inactive. Furthermore, during Edebug's recursive edit, these variables -are bound to the values they had outside of Edebug. - -@node Edebug Views -@subsection Edebug Views - - These Edebug commands let you view aspects of the buffer and window -status as they were before entry to Edebug. The outside window -configuration is the collection of windows and contents that were in -effect outside of Edebug. - -@table @kbd -@item v -Switch to viewing the outside window configuration -(@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug. - -@item p -Temporarily display the outside current buffer with point at its -outside position (@code{edebug-bounce-point}), pausing for one second -before returning to Edebug. With a prefix argument @var{n}, pause for -@var{n} seconds instead. - -@item w -Move point back to the current stop point in the source code buffer -(@code{edebug-where}). - -If you use this command in a different window displaying the same -buffer, that window will be used instead to display the current -definition in the future. - -@item W -@c Its function is not simply to forget the saved configuration -- dan -Toggle whether Edebug saves and restores the outside window -configuration (@code{edebug-toggle-save-windows}). - -With a prefix argument, @code{W} only toggles saving and restoring of -the selected window. To specify a window that is not displaying the -source code buffer, you must use @kbd{C-x X W} from the global keymap. -@end table - - You can view the outside window configuration with @kbd{v} or just -bounce to the point in the current buffer with @kbd{p}, even if -it is not normally displayed. - - After moving point, you may wish to jump back to the stop point. -You can do that with @kbd{w} from a source code buffer. You can jump -back to the stop point in the source code buffer from any buffer using -@kbd{C-x X w}. - - Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the -saved outside window configuration---so that even if you turn saving -back @emph{on}, the current window configuration remains unchanged when -you next exit Edebug (by continuing the program). However, the -automatic redisplay of @file{*edebug*} and @file{*edebug-trace*} may -conflict with the buffers you wish to see unless you have enough windows -open. - -@node Edebug Eval -@subsection Evaluation - - While within Edebug, you can evaluate expressions as if Edebug -were not running. Edebug tries to be invisible to the expression's -evaluation and printing. Evaluation of expressions that cause side -effects will work as expected, except for changes to data that Edebug -explicitly saves and restores. @xref{The Outside Context}, for details -on this process. - -@table @kbd -@item e @var{exp} @key{RET} -Evaluate expression @var{exp} in the context outside of Edebug -(@code{edebug-eval-expression}). That is, Edebug tries to minimize its -interference with the evaluation. - -@item M-: @var{exp} @key{RET} -Evaluate expression @var{exp} in the context of Edebug itself -(@code{eval-expression}). - -@item C-x C-e -Evaluate the expression before point, in the context outside of Edebug -(@code{edebug-eval-last-sexp}). -@end table - -@cindex lexical binding (Edebug) - Edebug supports evaluation of expressions containing references to -lexically bound symbols created by the following constructs in -@file{cl.el}: @code{lexical-let}, @code{macrolet}, and -@code{symbol-macrolet}. -@c FIXME? What about lexical-binding = t? - -@node Eval List -@subsection Evaluation List Buffer - - You can use the @dfn{evaluation list buffer}, called @file{*edebug*}, to -evaluate expressions interactively. You can also set up the -@dfn{evaluation list} of expressions to be evaluated automatically each -time Edebug updates the display. - -@table @kbd -@item E -Switch to the evaluation list buffer @file{*edebug*} -(@code{edebug-visit-eval-list}). -@end table - - In the @file{*edebug*} buffer you can use the commands of Lisp -Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs -Manual}) as well as these special commands: - -@table @kbd -@item C-j -Evaluate the expression before point, in the outside context, and insert -the value in the buffer (@code{edebug-eval-print-last-sexp}). - -@item C-x C-e -Evaluate the expression before point, in the context outside of Edebug -(@code{edebug-eval-last-sexp}). - -@item C-c C-u -Build a new evaluation list from the contents of the buffer -(@code{edebug-update-eval-list}). - -@item C-c C-d -Delete the evaluation list group that point is in -(@code{edebug-delete-eval-item}). - -@item C-c C-w -Switch back to the source code buffer at the current stop point -(@code{edebug-where}). -@end table - - You can evaluate expressions in the evaluation list window with -@kbd{C-j} or @kbd{C-x C-e}, just as you would in @file{*scratch*}; -but they are evaluated in the context outside of Edebug. - - The expressions you enter interactively (and their results) are lost -when you continue execution; but you can set up an @dfn{evaluation list} -consisting of expressions to be evaluated each time execution stops. - -@cindex evaluation list group - To do this, write one or more @dfn{evaluation list groups} in the -evaluation list buffer. An evaluation list group consists of one or -more Lisp expressions. Groups are separated by comment lines. - - The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the -evaluation list, scanning the buffer and using the first expression of -each group. (The idea is that the second expression of the group is the -value previously computed and displayed.) - - Each entry to Edebug redisplays the evaluation list by inserting each -expression in the buffer, followed by its current value. It also -inserts comment lines so that each expression becomes its own group. -Thus, if you type @kbd{C-c C-u} again without changing the buffer text, -the evaluation list is effectively unchanged. - - If an error occurs during an evaluation from the evaluation list, -the error message is displayed in a string as if it were the result. -Therefore, expressions using variables that are not currently valid do -not interrupt your debugging. - - Here is an example of what the evaluation list window looks like after -several expressions have been added to it: - -@smallexample -(current-buffer) -# -;--------------------------------------------------------------- -(selected-window) -# -;--------------------------------------------------------------- -(point) -196 -;--------------------------------------------------------------- -bad-var -"Symbol's value as variable is void: bad-var" -;--------------------------------------------------------------- -(recursion-depth) -0 -;--------------------------------------------------------------- -this-command -eval-last-sexp -;--------------------------------------------------------------- -@end smallexample - -To delete a group, move point into it and type @kbd{C-c C-d}, or simply -delete the text for the group and update the evaluation list with -@kbd{C-c C-u}. To add a new expression to the evaluation list, insert -the expression at a suitable place, insert a new comment line, then type -@kbd{C-c C-u}. You need not insert dashes in the comment line---its -contents don't matter. - -After selecting @file{*edebug*}, you can return to the source code -buffer with @kbd{C-c C-w}. The @file{*edebug*} buffer is killed when -you continue execution, and recreated next time it is needed. - -@node Printing in Edebug -@subsection Printing in Edebug - -@cindex printing (Edebug) -@cindex printing circular structures -@pindex cust-print - If an expression in your program produces a value containing circular -list structure, you may get an error when Edebug attempts to print it. - - One way to cope with circular structure is to set @code{print-length} -or @code{print-level} to truncate the printing. Edebug does this for -you; it binds @code{print-length} and @code{print-level} to the values -of the variables @code{edebug-print-length} and -@code{edebug-print-level} (so long as they have non-@code{nil} -values). @xref{Output Variables}. - -@defopt edebug-print-length -If non-@code{nil}, Edebug binds @code{print-length} to this value while -printing results. The default value is @code{50}. -@end defopt - -@defopt edebug-print-level -If non-@code{nil}, Edebug binds @code{print-level} to this value while -printing results. The default value is @code{50}. -@end defopt - - You can also print circular structures and structures that share -elements more informatively by binding @code{print-circle} -to a non-@code{nil} value. - - Here is an example of code that creates a circular structure: - -@example -(setq a '(x y)) -(setcar a a) -@end example - -@noindent -Custom printing prints this as @samp{Result: #1=(#1# y)}. The -@samp{#1=} notation labels the structure that follows it with the label -@samp{1}, and the @samp{#1#} notation references the previously labeled -structure. This notation is used for any shared elements of lists or -vectors. - -@defopt edebug-print-circle -If non-@code{nil}, Edebug binds @code{print-circle} to this value while -printing results. The default value is @code{t}. -@end defopt - - Other programs can also use custom printing; see @file{cust-print.el} -for details. - -@node Trace Buffer -@subsection Trace Buffer -@cindex trace buffer - - Edebug can record an execution trace, storing it in a buffer named -@file{*edebug-trace*}. This is a log of function calls and returns, -showing the function names and their arguments and values. To enable -trace recording, set @code{edebug-trace} to a non-@code{nil} value. - - Making a trace buffer is not the same thing as using trace execution -mode (@pxref{Edebug Execution Modes}). - - When trace recording is enabled, each function entry and exit adds -lines to the trace buffer. A function entry record consists of -@samp{::::@{}, followed by the function name and argument values. A -function exit record consists of @samp{::::@}}, followed by the function -name and result of the function. - - The number of @samp{:}s in an entry shows its recursion depth. You -can use the braces in the trace buffer to find the matching beginning or -end of function calls. - -@findex edebug-print-trace-before -@findex edebug-print-trace-after - You can customize trace recording for function entry and exit by -redefining the functions @code{edebug-print-trace-before} and -@code{edebug-print-trace-after}. - -@defmac edebug-tracing string body@dots{} -This macro requests additional trace information around the execution -of the @var{body} forms. The argument @var{string} specifies text -to put in the trace buffer, after the @samp{@{} or @samp{@}}. All -the arguments are evaluated, and @code{edebug-tracing} returns the -value of the last form in @var{body}. -@end defmac - -@defun edebug-trace format-string &rest format-args -This function inserts text in the trace buffer. It computes the text -with @code{(apply 'format @var{format-string} @var{format-args})}. -It also appends a newline to separate entries. -@end defun - - @code{edebug-tracing} and @code{edebug-trace} insert lines in the -trace buffer whenever they are called, even if Edebug is not active. -Adding text to the trace buffer also scrolls its window to show the last -lines inserted. - -@node Coverage Testing -@subsection Coverage Testing - -@cindex coverage testing (Edebug) -@cindex frequency counts -@cindex performance analysis - Edebug provides rudimentary coverage testing and display of execution -frequency. - - Coverage testing works by comparing the result of each expression with -the previous result; each form in the program is considered ``covered'' -if it has returned two different values since you began testing coverage -in the current Emacs session. Thus, to do coverage testing on your -program, execute it under various conditions and note whether it behaves -correctly; Edebug will tell you when you have tried enough different -conditions that each form has returned two different values. - - Coverage testing makes execution slower, so it is only done if -@code{edebug-test-coverage} is non-@code{nil}. Frequency counting is -performed for all executions of an instrumented function, even if the -execution mode is Go-nonstop, and regardless of whether coverage testing -is enabled. - -@kindex C-x X = -@findex edebug-temp-display-freq-count - Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both -the coverage information and the frequency counts for a definition. -Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same -information temporarily, only until you type another key. - -@deffn Command edebug-display-freq-count -This command displays the frequency count data for each line of the -current definition. - -It inserts frequency counts as comment lines after each line of code. -You can undo all insertions with one @code{undo} command. The counts -appear under the @samp{(} before an expression or the @samp{)} after -an expression, or on the last character of a variable. To simplify -the display, a count is not shown if it is equal to the count of an -earlier expression on the same line. - -The character @samp{=} following the count for an expression says that -the expression has returned the same value each time it was evaluated. -In other words, it is not yet ``covered'' for coverage testing purposes. - -To clear the frequency count and coverage data for a definition, -simply reinstrument it with @code{eval-defun}. -@end deffn - -For example, after evaluating @code{(fac 5)} with a source -breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when -the breakpoint is reached, the frequency data looks like this: - -@example -(defun fac (n) - (if (= n 0) (edebug)) -;#6 1 = =5 - (if (< 0 n) -;#5 = - (* n (fac (1- n))) -;# 5 0 - 1)) -;# 0 -@end example - -The comment lines show that @code{fac} was called 6 times. The -first @code{if} statement returned 5 times with the same result each -time; the same is true of the condition on the second @code{if}. -The recursive call of @code{fac} did not return at all. - - -@node The Outside Context -@subsection The Outside Context - -Edebug tries to be transparent to the program you are debugging, but it -does not succeed completely. Edebug also tries to be transparent when -you evaluate expressions with @kbd{e} or with the evaluation list -buffer, by temporarily restoring the outside context. This section -explains precisely what context Edebug restores, and how Edebug fails to -be completely transparent. - -@menu -* Checking Whether to Stop:: When Edebug decides what to do. -* Edebug Display Update:: When Edebug updates the display. -* Edebug Recursive Edit:: When Edebug stops execution. -@end menu - -@node Checking Whether to Stop -@subsubsection Checking Whether to Stop - -Whenever Edebug is entered, it needs to save and restore certain data -before even deciding whether to make trace information or stop the -program. - -@itemize @bullet -@item -@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both -increased to reduce Edebug's impact on the stack. You could, however, -still run out of stack space when using Edebug. - -@item -The state of keyboard macro execution is saved and restored. While -Edebug is active, @code{executing-kbd-macro} is bound to @code{nil} -unless @code{edebug-continue-kbd-macro} is non-@code{nil}. -@end itemize - - -@node Edebug Display Update -@subsubsection Edebug Display Update - -@c This paragraph is not filled, because LaLiberte's conversion script -@c needs an xref to be on just one line. -When Edebug needs to display something (e.g., in trace mode), it saves -the current window configuration from ``outside'' Edebug -(@pxref{Window Configurations}). When you exit Edebug, it restores -the previous window configuration. - -Emacs redisplays only when it pauses. Usually, when you continue -execution, the program re-enters Edebug at a breakpoint or after -stepping, without pausing or reading input in between. In such cases, -Emacs never gets a chance to redisplay the ``outside'' configuration. -Consequently, what you see is the same window configuration as the last -time Edebug was active, with no interruption. - -Entry to Edebug for displaying something also saves and restores the -following data (though some of them are deliberately not restored if an -error or quit signal occurs). - -@itemize @bullet -@item -@cindex current buffer point and mark (Edebug) -Which buffer is current, and the positions of point and the mark in the -current buffer, are saved and restored. - -@item -@cindex window configuration (Edebug) -The outside window configuration is saved and restored if -@code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}). - -The window configuration is not restored on error or quit, but the -outside selected window @emph{is} reselected even on error or quit in -case a @code{save-excursion} is active. If the value of -@code{edebug-save-windows} is a list, only the listed windows are saved -and restored. - -The window start and horizontal scrolling of the source code buffer are -not restored, however, so that the display remains coherent within Edebug. - -@item -The value of point in each displayed buffer is saved and restored if -@code{edebug-save-displayed-buffer-points} is non-@code{nil}. - -@item -The variables @code{overlay-arrow-position} and -@code{overlay-arrow-string} are saved and restored, so you can safely -invoke Edebug from the recursive edit elsewhere in the same buffer. - -@item -@code{cursor-in-echo-area} is locally bound to @code{nil} so that -the cursor shows up in the window. -@end itemize - -@node Edebug Recursive Edit -@subsubsection Edebug Recursive Edit - -When Edebug is entered and actually reads commands from the user, it -saves (and later restores) these additional data: - -@itemize @bullet -@item -The current match data. @xref{Match Data}. - -@item -The variables @code{last-command}, @code{this-command}, -@code{last-input-event}, @code{last-command-event}, -@code{last-event-frame}, @code{last-nonmenu-event}, and -@code{track-mouse}. Commands used within Edebug do not affect these -variables outside of Edebug. - -Executing commands within Edebug can change the key sequence that -would be returned by @code{this-command-keys}, and there is no way to -reset the key sequence from Lisp. - -Edebug cannot save and restore the value of -@code{unread-command-events}. Entering Edebug while this variable has a -nontrivial value can interfere with execution of the program you are -debugging. - -@item -Complex commands executed while in Edebug are added to the variable -@code{command-history}. In rare cases this can alter execution. - -@item -Within Edebug, the recursion depth appears one deeper than the recursion -depth outside Edebug. This is not true of the automatically updated -evaluation list window. - -@item -@code{standard-output} and @code{standard-input} are bound to @code{nil} -by the @code{recursive-edit}, but Edebug temporarily restores them during -evaluations. - -@item -The state of keyboard macro definition is saved and restored. While -Edebug is active, @code{defining-kbd-macro} is bound to -@code{edebug-continue-kbd-macro}. -@end itemize - -@node Edebug and Macros -@subsection Edebug and Macros - -To make Edebug properly instrument expressions that call macros, some -extra care is needed. This subsection explains the details. - -@menu -* Instrumenting Macro Calls:: The basic problem. -* Specification List:: How to specify complex patterns of evaluation. -* Backtracking:: What Edebug does when matching fails. -* Specification Examples:: To help understand specifications. -@end menu - -@node Instrumenting Macro Calls -@subsubsection Instrumenting Macro Calls - - When Edebug instruments an expression that calls a Lisp macro, it needs -additional information about the macro to do the job properly. This is -because there is no a-priori way to tell which subexpressions of the -macro call are forms to be evaluated. (Evaluation may occur explicitly -in the macro body, or when the resulting expansion is evaluated, or any -time later.) - - Therefore, you must define an Edebug specification for each macro -that Edebug will encounter, to explain the format of calls to that -macro. To do this, add a @code{debug} declaration to the macro -definition. Here is a simple example that shows the specification for -the @code{for} example macro (@pxref{Argument Evaluation}). - -@smallexample -(defmacro for (var from init to final do &rest body) - "Execute a simple \"for\" loop. -For example, (for i from 1 to 10 do (print i))." - (declare (debug (symbolp "from" form "to" form "do" &rest form))) - ...) -@end smallexample - - The Edebug specification says which parts of a call to the macro are -forms to be evaluated. For simple macros, the specification -often looks very similar to the formal argument list of the macro -definition, but specifications are much more general than macro -arguments. @xref{Defining Macros}, for more explanation of -the @code{declare} form. - -@c See eg http://debbugs.gnu.org/10577 -@c FIXME Maybe there should be an Edebug option to get it to -@c automatically load the entire source file containing the function -@c being instrumented. That would avoid this. - Take care to ensure that the specifications are known to Edebug when -you instrument code. If you are instrumenting a function from a file -that uses @code{eval-when-compile} to require another file containing -macro definitions, you may need to explicitly load that file. - - You can also define an edebug specification for a macro separately -from the macro definition with @code{def-edebug-spec}. Adding -@code{debug} declarations is preferred, and more convenient, for macro -definitions in Lisp, but @code{def-edebug-spec} makes it possible to -define Edebug specifications for special forms implemented in C. - -@deffn Macro def-edebug-spec macro specification -Specify which expressions of a call to macro @var{macro} are forms to be -evaluated. @var{specification} should be the edebug specification. -Neither argument is evaluated. - -The @var{macro} argument can actually be any symbol, not just a macro -name. -@end deffn - -Here is a table of the possibilities for @var{specification} and how each -directs processing of arguments. - -@table @asis -@item @code{t} -All arguments are instrumented for evaluation. - -@item @code{0} -None of the arguments is instrumented. - -@item a symbol -The symbol must have an Edebug specification, which is used instead. -This indirection is repeated until another kind of specification is -found. This allows you to inherit the specification from another macro. - -@item a list -The elements of the list describe the types of the arguments of a -calling form. The possible elements of a specification list are -described in the following sections. -@end table - -If a macro has no Edebug specification, neither through a @code{debug} -declaration nor through a @code{def-edebug-spec} call, the variable -@code{edebug-eval-macro-args} comes into play. - -@defopt edebug-eval-macro-args -This controls the way Edebug treats macro arguments with no explicit -Edebug specification. If it is @code{nil} (the default), none of the -arguments is instrumented for evaluation. Otherwise, all arguments -are instrumented. -@end defopt - -@node Specification List -@subsubsection Specification List - -@cindex Edebug specification list -A @dfn{specification list} is required for an Edebug specification if -some arguments of a macro call are evaluated while others are not. Some -elements in a specification list match one or more arguments, but others -modify the processing of all following elements. The latter, called -@dfn{specification keywords}, are symbols beginning with @samp{&} (such -as @code{&optional}). - -A specification list may contain sublists, which match arguments that are -themselves lists, or it may contain vectors used for grouping. Sublists -and groups thus subdivide the specification list into a hierarchy of -levels. Specification keywords apply only to the remainder of the -sublist or group they are contained in. - -When a specification list involves alternatives or repetition, matching -it against an actual macro call may require backtracking. For more -details, @pxref{Backtracking}. - -Edebug specifications provide the power of regular expression matching, -plus some context-free grammar constructs: the matching of sublists with -balanced parentheses, recursive processing of forms, and recursion via -indirect specifications. - -Here's a table of the possible elements of a specification list, with -their meanings (see @ref{Specification Examples}, for the referenced -examples): - -@table @code -@item sexp -A single unevaluated Lisp object, which is not instrumented. -@c an "expression" is not necessarily intended for evaluation. - -@item form -A single evaluated expression, which is instrumented. - -@item place -@c I can't see that this index entry is useful without any explanation. -@c @findex edebug-unwrap -A place to store a value, as in the Common Lisp @code{setf} construct. - -@item body -Short for @code{&rest form}. See @code{&rest} below. - -@item function-form -A function form: either a quoted function symbol, a quoted lambda -expression, or a form (that should evaluate to a function symbol or -lambda expression). This is useful when an argument that's a lambda -expression might be quoted with @code{quote} rather than -@code{function}, since it instruments the body of the lambda expression -either way. - -@item lambda-expr -A lambda expression with no quoting. - -@item &optional -@c @kindex &optional @r{(Edebug)} -All following elements in the specification list are optional; as soon -as one does not match, Edebug stops matching at this level. - -To make just a few elements optional, followed by non-optional elements, -use @code{[&optional @var{specs}@dots{}]}. To specify that several -elements must all match or none, use @code{&optional -[@var{specs}@dots{}]}. See the @code{defun} example. - -@item &rest -@c @kindex &rest @r{(Edebug)} -All following elements in the specification list are repeated zero or -more times. In the last repetition, however, it is not a problem if the -expression runs out before matching all of the elements of the -specification list. - -To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}. -To specify several elements that must all match on every repetition, use -@code{&rest [@var{specs}@dots{}]}. - -@item &or -@c @kindex &or @r{(Edebug)} -Each of the following elements in the specification list is an -alternative. One of the alternatives must match, or the @code{&or} -specification fails. - -Each list element following @code{&or} is a single alternative. To -group two or more list elements as a single alternative, enclose them in -@code{[@dots{}]}. - -@item ¬ -@c @kindex ¬ @r{(Edebug)} -Each of the following elements is matched as alternatives as if by using -@code{&or}, but if any of them match, the specification fails. If none -of them match, nothing is matched, but the @code{¬} specification -succeeds. - -@c FIXME &key? - -@item &define -@c @kindex &define @r{(Edebug)} -Indicates that the specification is for a defining form. The defining -form itself is not instrumented (that is, Edebug does not stop before and -after the defining form), but forms inside it typically will be -instrumented. The @code{&define} keyword should be the first element in -a list specification. - -@item nil -This is successful when there are no more arguments to match at the -current argument list level; otherwise it fails. See sublist -specifications and the backquote example. - -@item gate -@cindex preventing backtracking -No argument is matched but backtracking through the gate is disabled -while matching the remainder of the specifications at this level. This -is primarily used to generate more specific syntax error messages. See -@ref{Backtracking}, for more details. Also see the @code{let} example. - -@item @var{other-symbol} -@cindex indirect specifications -Any other symbol in a specification list may be a predicate or an -indirect specification. - -If the symbol has an Edebug specification, this @dfn{indirect -specification} should be either a list specification that is used in -place of the symbol, or a function that is called to process the -arguments. The specification may be defined with @code{def-edebug-spec} -just as for macros. See the @code{defun} example. - -Otherwise, the symbol should be a predicate. The predicate is called -with the argument, and if the predicate returns @code{nil}, the -specification fails and the argument is not instrumented. - -Some suitable predicates include @code{symbolp}, @code{integerp}, -@code{stringp}, @code{vectorp}, and @code{atom}. - -@item [@var{elements}@dots{}] -@cindex [@dots{}] (Edebug) -A vector of elements groups the elements into a single @dfn{group -specification}. Its meaning has nothing to do with vectors. - -@item "@var{string}" -The argument should be a symbol named @var{string}. This specification -is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name -of @var{symbol} is the @var{string}, but the string form is preferred. - -@item (vector @var{elements}@dots{}) -The argument should be a vector whose elements must match the -@var{elements} in the specification. See the backquote example. - -@item (@var{elements}@dots{}) -Any other list is a @dfn{sublist specification} and the argument must be -a list whose elements match the specification @var{elements}. - -@cindex dotted lists (Edebug) -A sublist specification may be a dotted list and the corresponding list -argument may then be a dotted list. Alternatively, the last @sc{cdr} of a -dotted list specification may be another sublist specification (via a -grouping or an indirect specification, e.g., @code{(spec . [(more -specs@dots{})])}) whose elements match the non-dotted list arguments. -This is useful in recursive specifications such as in the backquote -example. Also see the description of a @code{nil} specification -above for terminating such recursion. - -Note that a sublist specification written as @code{(specs . nil)} -is equivalent to @code{(specs)}, and @code{(specs . -(sublist-elements@dots{}))} is equivalent to @code{(specs -sublist-elements@dots{})}. -@end table - -@c Need to document extensions with &symbol and :symbol - -Here is a list of additional specifications that may appear only after -@code{&define}. See the @code{defun} example. - -@table @code -@item name -The argument, a symbol, is the name of the defining form. - -A defining form is not required to have a name field; and it may have -multiple name fields. - -@item :name -This construct does not actually match an argument. The element -following @code{:name} should be a symbol; it is used as an additional -name component for the definition. You can use this to add a unique, -static component to the name of the definition. It may be used more -than once. - -@item arg -The argument, a symbol, is the name of an argument of the defining form. -However, lambda-list keywords (symbols starting with @samp{&}) -are not allowed. - -@item lambda-list -@cindex lambda-list (Edebug) -This matches a lambda list---the argument list of a lambda expression. - -@item def-body -The argument is the body of code in a definition. This is like -@code{body}, described above, but a definition body must be instrumented -with a different Edebug call that looks up information associated with -the definition. Use @code{def-body} for the highest level list of forms -within the definition. - -@item def-form -The argument is a single, highest-level form in a definition. This is -like @code{def-body}, except it is used to match a single form rather than -a list of forms. As a special case, @code{def-form} also means that -tracing information is not output when the form is executed. See the -@code{interactive} example. -@end table - -@node Backtracking -@subsubsection Backtracking in Specifications - -@cindex backtracking -@cindex syntax error (Edebug) -If a specification fails to match at some point, this does not -necessarily mean a syntax error will be signaled; instead, -@dfn{backtracking} will take place until all alternatives have been -exhausted. Eventually every element of the argument list must be -matched by some element in the specification, and every required element -in the specification must match some argument. - -When a syntax error is detected, it might not be reported until much -later, after higher-level alternatives have been exhausted, and with the -point positioned further from the real error. But if backtracking is -disabled when an error occurs, it can be reported immediately. Note -that backtracking is also reenabled automatically in several situations; -when a new alternative is established by @code{&optional}, -@code{&rest}, or @code{&or}, or at the start of processing a sublist, -group, or indirect specification. The effect of enabling or disabling -backtracking is limited to the remainder of the level currently being -processed and lower levels. - -Backtracking is disabled while matching any of the -form specifications (that is, @code{form}, @code{body}, @code{def-form}, and -@code{def-body}). These specifications will match any form so any error -must be in the form itself rather than at a higher level. - -Backtracking is also disabled after successfully matching a quoted -symbol or string specification, since this usually indicates a -recognized construct. But if you have a set of alternative constructs that -all begin with the same symbol, you can usually work around this -constraint by factoring the symbol out of the alternatives, e.g., -@code{["foo" &or [first case] [second case] ...]}. - -Most needs are satisfied by these two ways that backtracking is -automatically disabled, but occasionally it is useful to explicitly -disable backtracking by using the @code{gate} specification. This is -useful when you know that no higher alternatives could apply. See the -example of the @code{let} specification. - -@node Specification Examples -@subsubsection Specification Examples - -It may be easier to understand Edebug specifications by studying -the examples provided here. - -A @code{let} special form has a sequence of bindings and a body. Each -of the bindings is either a symbol or a sublist with a symbol and -optional expression. In the specification below, notice the @code{gate} -inside of the sublist to prevent backtracking once a sublist is found. - -@ignore -@c FIXME? The actual definition in edebug.el looks like this (and always -@c has AFAICS). In fact, nothing in edebug.el uses gate. So maybe -@c this is just an example for illustration? -(def-edebug-spec let - ((&rest - &or (symbolp &optional form) symbolp) - body)) -@end ignore -@example -(def-edebug-spec let - ((&rest - &or symbolp (gate symbolp &optional form)) - body)) -@end example - -Edebug uses the following specifications for @code{defun} and the -associated argument list and @code{interactive} specifications. It is -necessary to handle interactive forms specially since an expression -argument is actually evaluated outside of the function body. (The -specification for @code{defmacro} is very similar to that for -@code{defun}, but allows for the @code{declare} statement.) - -@smallexample -(def-edebug-spec defun - (&define name lambda-list - [&optional stringp] ; @r{Match the doc string, if present.} - [&optional ("interactive" interactive)] - def-body)) - -(def-edebug-spec lambda-list - (([&rest arg] - [&optional ["&optional" arg &rest arg]] - &optional ["&rest" arg] - ))) - -(def-edebug-spec interactive - (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}} -@end smallexample - -The specification for backquote below illustrates how to match -dotted lists and use @code{nil} to terminate recursion. It also -illustrates how components of a vector may be matched. (The actual -specification defined by Edebug is a little different, and does not -support dotted lists because doing so causes very deep recursion that -could fail.) - -@smallexample -(def-edebug-spec \` (backquote-form)) ; @r{Alias just for clarity.} - -(def-edebug-spec backquote-form - (&or ([&or "," ",@@"] &or ("quote" backquote-form) form) - (backquote-form . [&or nil backquote-form]) - (vector &rest backquote-form) - sexp)) -@end smallexample - - -@node Edebug Options -@subsection Edebug Options - - These options affect the behavior of Edebug: -@c Previously defopt'd: -@c edebug-sit-for-seconds, edebug-print-length, edebug-print-level -@c edebug-print-circle, edebug-eval-macro-args - -@defopt edebug-setup-hook -Functions to call before Edebug is used. Each time it is set to a new -value, Edebug will call those functions once and then -reset @code{edebug-setup-hook} to @code{nil}. You could use this to -load up Edebug specifications associated with a package you are using, -but only when you also use Edebug. -@xref{Instrumenting}. -@end defopt - -@defopt edebug-all-defs -If this is non-@code{nil}, normal evaluation of defining forms such as -@code{defun} and @code{defmacro} instruments them for Edebug. This -applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer}, -and @code{eval-current-buffer}. - -Use the command @kbd{M-x edebug-all-defs} to toggle the value of this -option. @xref{Instrumenting}. -@end defopt - -@defopt edebug-all-forms -If this is non-@code{nil}, the commands @code{eval-defun}, -@code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer} -instrument all forms, even those that don't define anything. -This doesn't apply to loading or evaluations in the minibuffer. - -Use the command @kbd{M-x edebug-all-forms} to toggle the value of this -option. @xref{Instrumenting}. -@end defopt - -@defopt edebug-save-windows -If this is non-@code{nil}, Edebug saves and restores the window -configuration. That takes some time, so if your program does not care -what happens to the window configurations, it is better to set this -variable to @code{nil}. - -If the value is a list, only the listed windows are saved and -restored. - -You can use the @kbd{W} command in Edebug to change this variable -interactively. @xref{Edebug Display Update}. -@end defopt - -@defopt edebug-save-displayed-buffer-points -If this is non-@code{nil}, Edebug saves and restores point in all -displayed buffers. - -Saving and restoring point in other buffers is necessary if you are -debugging code that changes the point of a buffer that is displayed in -a non-selected window. If Edebug or the user then selects the window, -point in that buffer will move to the window's value of point. - -Saving and restoring point in all buffers is expensive, since it -requires selecting each window twice, so enable this only if you need -it. @xref{Edebug Display Update}. -@end defopt - -@defopt edebug-initial-mode -If this variable is non-@code{nil}, it specifies the initial execution -mode for Edebug when it is first activated. Possible values are -@code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace}, -@code{Trace-fast}, @code{continue}, and @code{Continue-fast}. - -The default value is @code{step}. -@xref{Edebug Execution Modes}. -@end defopt - -@defopt edebug-trace -If this is non-@code{nil}, trace each function entry and exit. -Tracing output is displayed in a buffer named @file{*edebug-trace*}, one -function entry or exit per line, indented by the recursion level. - -Also see @code{edebug-tracing}, in @ref{Trace Buffer}. -@end defopt - -@defopt edebug-test-coverage -If non-@code{nil}, Edebug tests coverage of all expressions debugged. -@xref{Coverage Testing}. -@end defopt - -@defopt edebug-continue-kbd-macro -If non-@code{nil}, continue defining or executing any keyboard macro -that is executing outside of Edebug. Use this with caution since it is not -debugged. -@xref{Edebug Execution Modes}. -@end defopt - -@defopt edebug-unwrap-results -If non-@code{nil}, Edebug tries to remove any of its own -instrumentation when showing the results of expressions. This is -relevant when debugging macros where the results of expressions are -themselves instrumented expressions. As a very artificial example, -suppose that the example function @code{fac} has been instrumented, -and consider a macro of the form: - -@c FIXME find a less silly example. -@smallexample -(defmacro test () "Edebug example." - (if (symbol-function 'fac) - @dots{})) -@end smallexample - -If you instrument the @code{test} macro and step through it, then by -default the result of the @code{symbol-function} call has numerous -@code{edebug-after} and @code{edebug-before} forms, which can make it -difficult to see the ``actual'' result. If -@code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove -these forms from the result. -@end defopt - -@defopt edebug-on-error -Edebug binds @code{debug-on-error} to this value, if -@code{debug-on-error} was previously @code{nil}. @xref{Trapping -Errors}. -@end defopt - -@defopt edebug-on-quit -Edebug binds @code{debug-on-quit} to this value, if -@code{debug-on-quit} was previously @code{nil}. @xref{Trapping -Errors}. -@end defopt - - If you change the values of @code{edebug-on-error} or -@code{edebug-on-quit} while Edebug is active, their values won't be used -until the @emph{next} time Edebug is invoked via a new command. -@c Not necessarily a deeper command level. -@c A new command is not precisely true, but that is close enough -- dan - -@defopt edebug-global-break-condition -If non-@code{nil}, an expression to test for at every stop point. If -the result is non-@code{nil}, then break. Errors are ignored. -@xref{Global Break Condition}. -@end defopt diff --git a/doc/lispref/elisp-covers.texi b/doc/lispref/elisp-covers.texi deleted file mode 100644 index b2cc5a9adf2..00000000000 --- a/doc/lispref/elisp-covers.texi +++ /dev/null @@ -1,252 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@c -@comment %**start of header -@setfilename covers.info -@settitle GNU Emacs Lisp Reference Manual -@comment %**end of header - -@titlepage -@c ================ Volume 1 ================ -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 2 ================ -@w{ } -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, -@center Dan LaLiberte, and -@center the GNU Manual Group - -@page -@c ================ Volume 1 with baseline skip 16pt ================ - -@tex -\global\baselineskip = 16pt -@end tex - -16 pts baseline skip: - -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 1 with baseline skip 18pt ================ - -@tex -\global\baselineskip = 18pt -@end tex - -18 pts baseline skip, with 15pts between sections - -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@tex -\global\baselineskip = 15pt -@end tex - -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, -@center Dan LaLiberte, and -@center the GNU Manual Group - -@page -@c ================ Volume 1 with more baseline skip 24 pts ================ - -@tex -\global\baselineskip = 24pt -@end tex - -24 pts baseline skip: - -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 2 with more baseline skip 18 pts ================ - -@tex -\global\baselineskip = 18pt -@end tex - -18 pts baseline skip: - -@w{ } -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 2 with more baseline skip 24 pts ================ - -@tex -\global\baselineskip = 24pt -@end tex - -24 pts baseline skip: - -@w{ } -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - - -@page -@c ================ Spine 1 ================ - -@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 1}} -@sp 4 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 4 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@sp 4 -@author The GNU Emacs Lisp Reference Manual --- Vol. 1 -@sp 3 -@author FSF - -@author - -@page -@c ================ Spine 2 ================ - -@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 2}} -@sp 4 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 4 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - - -@sp 4 -@author The GNU Emacs Lisp Reference Manual --- Vol. 2 -@sp 3 -@author FSF - -@end titlepage -@bye diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi deleted file mode 100644 index 5e0356ff1ff..00000000000 --- a/doc/lispref/elisp.texi +++ /dev/null @@ -1,1552 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename elisp -@settitle GNU Emacs Lisp Reference Manual -@c %**end of header - -@c Version of the manual and of Emacs. -@c Please remember to update these in vol1.texi and vol2.texi as well. -@c (See comments for EDITION in emacs.texi) -@set VERSION 3.1 -@include emacsver.texi -@set DATE May 2012 - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. The manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@c @smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@c Combine indices. -@synindex cp fn -@syncodeindex vr fn -@syncodeindex ky fn -@syncodeindex pg fn -@c We use the "type index" to index new functions and variables. -@c @syncodeindex tp fn - -@copying -@iftex -This is edition @value{VERSION} of the @cite{GNU Emacs Lisp Reference Manual},@* -@end iftex -@ifnottex -This is the @cite{GNU Emacs Lisp Reference Manual} -@end ifnottex -corresponding to Emacs version @value{EMACSVER}. - -Copyright @copyright{} 1990-1996, 1998-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License,'' with the -Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the -section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@documentencoding ISO-8859-1 - -@dircategory GNU Emacs Lisp -@direntry -* Elisp: (elisp). The Emacs Lisp Reference Manual. -@end direntry - -@titlepage -@title GNU Emacs Lisp Reference Manual -@subtitle For Emacs Version @value{EMACSVER} -@subtitle Revision @value{VERSION}, @value{DATE} - -@author by Bil Lewis, Dan LaLiberte, Richard Stallman, -@author the GNU Manual Group, et al. -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 -Published by the Free Software Foundation @* -51 Franklin St, Fifth Floor @* -Boston, MA 02110-1301 @* -USA @* -ISBN 1-882114-74-4 - -@sp 2 -Cover art by Etienne Suvasa. -@end titlepage - - -@c Print the tables of contents -@summarycontents -@contents - - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top Emacs Lisp - -@insertcopying -@end ifnottex - -@c Copy any updates to vol1.texi and vol2.texi. -@menu -* Introduction:: Introduction and conventions used. - -* Lisp Data Types:: Data types of objects in Emacs Lisp. -* Numbers:: Numbers and arithmetic functions. -* Strings and Characters:: Strings, and functions that work on them. -* Lists:: Lists, cons cells, and related functions. -* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. - Certain functions act on any kind of sequence. - The description of vectors is here as well. -* Hash Tables:: Very fast lookup-tables. -* Symbols:: Symbols represent names, uniquely. - -* Evaluation:: How Lisp expressions are evaluated. -* Control Structures:: Conditionals, loops, nonlocal exits. -* Variables:: Using symbols in programs to stand for values. -* Functions:: A function is a Lisp program - that can be invoked from other functions. -* Macros:: Macros are a way to extend the Lisp language. -* Customization:: Making variables and faces customizable. - -* Loading:: Reading files of Lisp code into Lisp. -* Byte Compilation:: Compilation makes programs run faster. -* Advising Functions:: Adding to the definition of a function. -* Debugging:: Tools and tips for debugging Lisp programs. - -* Read and Print:: Converting Lisp objects to text and back. -* Minibuffers:: Using the minibuffer to read input. -* Command Loop:: How the editor command loop works, - and how you can call its subroutines. -* Keymaps:: Defining the bindings from keys to commands. -* Modes:: Defining major and minor modes. -* Documentation:: Writing and using documentation strings. - -* Files:: Accessing files. -* Backups and Auto-Saving:: Controlling how backups and auto-save - files are made. -* Buffers:: Creating and using buffer objects. -* Windows:: Manipulating windows and displaying buffers. -* Frames:: Making multiple system-level windows. -* Positions:: Buffer positions and motion functions. -* Markers:: Markers represent positions and update - automatically when the text is changed. - -* Text:: Examining and changing text in buffers. -* Non-ASCII Characters:: Non-ASCII text in buffers and strings. -* Searching and Matching:: Searching buffers for strings or regexps. -* Syntax Tables:: The syntax table controls word and list parsing. -* Abbrevs:: How Abbrev mode works, and its data structures. - -* Processes:: Running and communicating with subprocesses. -* Display:: Features for controlling the screen display. -* System Interface:: Getting the user id, system type, environment - variables, and other such things. - -* Packaging:: Preparing Lisp code for distribution. - -Appendices - -* Antinews:: Info for users downgrading to Emacs 23. -* GNU Free Documentation License:: The license for this documentation. -* GPL:: Conditions for copying and changing GNU Emacs. -* Tips:: Advice and coding conventions for Emacs Lisp. -* GNU Emacs Internals:: Building and dumping Emacs; - internal data structures. -* Standard Errors:: List of some standard error symbols. -* Standard Keymaps:: List of some standard keymaps. -* Standard Hooks:: List of some standard hook variables. - -* Index:: Index including concepts, functions, variables, - and other terms. - -@ignore -* New Symbols:: New functions and variables in Emacs @value{EMACSVER}. -@end ignore - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. -@c Copy any updates to vol1.texi and vol2.texi. - -@detailmenu - --- The Detailed Node Listing --- - --------------------------------- - -Here are other nodes that are subnodes of those already listed, -mentioned here so you can get to them in one step: - -Introduction - -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Version Info:: Which Emacs version is running? -* Acknowledgements:: The authors, editors, and sponsors of this manual. - -Conventions - -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use when examples print text. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. - -Format of Descriptions - -* A Sample Function Description:: A description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, @code{electric-future-map}. - -Lisp Data Types - -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Circular Objects:: Read syntax for circular structure. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. - -Programming Types - -* Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Symbol Type:: A multi-use object that refers to a function, - variable, or property list, and has a unique identity. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Char-Table Type:: One-dimensional sparse arrays indexed by characters. -* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. -* Hash Table Type:: Super-fast lookup tables. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. - -Character Type - -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. - -Cons Cell and List Types - -* Box Diagrams:: Drawing pictures of lists. -* Dotted Pair Notation:: A general syntax for cons cells. -* Association List Type:: A specially constructed list. - -String Type - -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. - -Editing Types - -* Buffer Type:: The basic object of editing. -* Marker Type:: A position in a buffer. -* Window Type:: Buffers are displayed in windows. -* Frame Type:: Windows subdivide frames. -* Terminal Type:: A terminal device displays frames. -* Window Configuration Type:: Recording the way a frame is subdivided. -* Frame Configuration Type:: Recording the status of all frames. -* Process Type:: A subprocess of Emacs running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Overlay Type:: How an overlay is represented. -* Font Type:: Fonts for displaying text. - -Numbers - -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating point numbers. -* Bitwise Operations:: Logical and, or, not, shifting. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. - -Strings and Characters - -* String Basics:: Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Modifying Strings:: Altering the contents of an existing string. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting to and from characters and strings. -* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. -* Case Conversion:: Case conversion functions. -* Case Tables:: Customizing case conversion. - -Lists - -* Cons Cells:: How lists are made out of cons cells. -* List-related Predicates:: Is this object a list? Comparing two lists. -* List Elements:: Extracting the pieces of a list. -* Building Lists:: Creating list structure. -* List Variables:: Modifying lists stored in variables. -* Modifying Lists:: Storing new pieces into an existing list. -* Sets And Lists:: A list can represent a finite mathematical set. -* Association Lists:: A list can represent a finite relation or mapping. - -Modifying Existing List Structure - -* Setcar:: Replacing an element in a list. -* Setcdr:: Replacing part of the list backbone. - This can be used to remove or add elements. -* Rearrangement:: Reordering the elements in a list; combining lists. - -Sequences, Arrays, and Vectors - -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Special characteristics of Emacs Lisp vectors. -* Vector Functions:: Functions specifically for vectors. -* Char-Tables:: How to work with char-tables. -* Bool-Vectors:: How to work with bool-vectors. -* Rings:: Managing a fixed-size ring of objects. - -Hash Tables - -* Creating Hash:: Functions to create hash tables. -* Hash Access:: Reading and writing the hash table contents. -* Defining Hash:: Defining new comparison methods. -* Other Hash:: Miscellaneous. - -Symbols - -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list - for recording miscellaneous information. - -Property Lists - -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. - -Evaluation - -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in - the program). -* Backquote:: Easier construction of list structure. -* Eval:: How to invoke the Lisp interpreter explicitly. - -Kinds of Forms - -* Self-Evaluating Forms:: Forms that evaluate to themselves. -* Symbol Forms:: Symbols evaluate as variables. -* Classifying Lists:: How to distinguish various sorts of list forms. -* Function Indirection:: When a symbol appears as the car of a list, - we find the real function via the symbol. -* Function Forms:: Forms that call functions. -* Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, - most of them extremely important. -* Autoloading:: Functions set up to load files - containing their real definitions. - -Control Structures - -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. - -Nonlocal Exits - -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an - error happens. - -Errors - -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. - -Variables - -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Tips for Defining:: Things you should think about when you - define a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. -* File Local Variables:: Handling local variable lists in files. -* Directory Local Variables:: Local variables common to all files in a - directory. -* Variable Aliases:: Variables that are aliases for other variables. -* Variables with Restricted Values:: Non-constant variables whose value can - @emph{not} be an arbitrary Lisp object. - -Scoping Rules for Variable Bindings - -* Dynamic Binding:: The default for binding local variables in Emacs. -* Dynamic Binding Tips:: Avoiding problems with dynamic binding. -* Lexical Binding:: A different type of local variable binding. -* Using Lexical Binding:: How to enable lexical binding. - -Buffer-Local Variables - -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own buffer-local values. - -Functions - -* What Is a Function:: Lisp functions vs. primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Closures:: Functions that enclose a lexical environment. -* Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Defining functions that the compiler - will expand inline. -* Declaring Functions:: Telling the compiler that a function is defined. -* Function Safety:: Determining whether a function is safe to call. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how - functions work. - -Lambda Expressions - -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. - -Macros - -* Simple Macro:: A basic example. -* Expansion:: How, when and why macros are expanded. -* Compiling Macros:: How macros are expanded by the compiler. -* Defining Macros:: How to write a macro definition. -* Problems with Macros:: Don't evaluate the macro arguments too many times. - Don't hide the user's variables. -* Indenting Macros:: Specifying how to indent macro calls. - -Common Problems Using Macros - -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. - -Customization Settings - -* Common Keywords:: Common keyword arguments for all kinds of - customization declarations. -* Group Definitions:: Writing customization group definitions. -* Variable Definitions:: Declaring user options. -* Customization Types:: Specifying the type of a user option. -* Applying Customizations:: Functions to apply customization settings. -* Custom Themes:: Writing Custom themes. - -Customization Types - -* Simple Types:: Simple customization types: sexp, integer, etc. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. - -Loading - -* How Programs Do Loading:: The @code{load} function and others. -* Load Suffixes:: Details about the suffixes that @code{load} tries. -* Library Search:: Finding a library to load. -* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. -* Autoload:: Setting up a function to autoload. -* Repeated Loading:: Precautions about loading a file twice. -* Named Features:: Loading a library if it isn't already loaded. -* Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. -* Hooks for Loading:: Providing code to be run when - particular libraries are loaded. - -Byte Compilation - -* Speed of Byte-Code:: An example of speedup from byte compilation. -* Compilation Functions:: Byte compilation functions. -* Docs and Compilation:: Dynamic loading of documentation strings. -* Dynamic Loading:: Dynamic loading of individual functions. -* Eval During Compile:: Code to be evaluated when you compile. -* Compiler Errors:: Handling compiler error messages. -* Byte-Code Objects:: The data type used for byte-compiled functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. - -Advising Emacs Lisp Functions - -* Simple Advice:: A simple example to explain the basics of advice. -* Defining Advice:: Detailed description of @code{defadvice}. -* Around-Advice:: Wrapping advice around a function's definition. -* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. -* Activation of Advice:: Advice doesn't do anything until you activate it. -* Enabling Advice:: You can enable or disable each piece of advice. -* Preactivation:: Preactivation is a way of speeding up the - loading of compiled advice. -* Argument Access in Advice:: How advice can access the function's arguments. -* Combined Definition:: How advice is implemented. - -Debugging Lisp Programs - -* Debugger:: A debugger for the Emacs Lisp evaluator. -* Edebug:: A source-level Emacs Lisp debugger. -* Syntax Errors:: How to find syntax errors. -* Test Coverage:: Ensuring you have tested all branches in your code. - -The Lisp Debugger - -* Error Debugging:: Entering the debugger when an error happens. -* Infinite Loops:: Stopping and debugging a program that doesn't exit. -* Function Debugging:: Entering it when a certain function is called. -* Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. -* Debugger Commands:: Commands used while in the debugger. -* Invoking the Debugger:: How to call the function @code{debug}. -* Internals of Debugger:: Subroutines of the debugger, and global variables. - -Edebug - -* Using Edebug:: Introduction to use of Edebug. -* Instrumenting:: You must instrument your code - in order to debug it with Edebug. -* Edebug Execution Modes:: Execution modes, stopping more or less often. -* Jumping:: Commands to jump to a specified place. -* Edebug Misc:: Miscellaneous commands. -* Breaks:: Setting breakpoints to make the program stop. -* Trapping Errors:: Trapping errors with Edebug. -* Edebug Views:: Views inside and outside of Edebug. -* Edebug Eval:: Evaluating expressions within Edebug. -* Eval List:: Expressions whose values are displayed - each time you enter Edebug. -* Printing in Edebug:: Customization of printing. -* Trace Buffer:: How to produce trace output in a buffer. -* Coverage Testing:: How to test evaluation coverage. -* The Outside Context:: Data that Edebug saves and restores. -* Edebug and Macros:: Specifying how to handle macro calls. -* Edebug Options:: Option variables for customizing Edebug. - -Breaks - -* Breakpoints:: Breakpoints at stop points. -* Global Break Condition:: Breaking on an event. -* Source Breakpoints:: Embedding breakpoints in source code. - -The Outside Context - -* Checking Whether to Stop::When Edebug decides what to do. -* Edebug Display Update:: When Edebug updates the display. -* Edebug Recursive Edit:: When Edebug stops execution. - -Edebug and Macros - -* Instrumenting Macro Calls::The basic problem. -* Specification List:: How to specify complex patterns of evaluation. -* Backtracking:: What Edebug does when matching fails. -* Specification Examples:: To help understand specifications. - -Debugging Invalid Lisp Syntax - -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. - -Reading and Printing Lisp Objects - -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as - input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as - output streams. -* Output Functions:: Functions to print Lisp objects as text. -* Output Variables:: Variables that control what the printing - functions do. - -Minibuffers - -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. -* Initial Input:: Specifying initial contents for the minibuffer. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Reading a Password:: Reading a password from the terminal. -* Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Windows:: Operating on the special minibuffer windows. -* Minibuffer Contents:: How such commands access the minibuffer text. -* Recursive Mini:: Whether recursive entry to minibuffer is allowed. -* Minibuffer Misc:: Various customization hooks and variables. - -Completion - -* Basic Completion:: Low-level functions for completing strings. -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer names, variable names, etc.). -* Reading File Names:: Using completion to read file names and - shell commands. -* Completion Variables:: Variables controlling completion behavior. -* Programmed Completion:: Writing your own completion function. -* Completion in Buffers:: Completing text in ordinary buffers. - -Command Loop - -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Distinguish Interactive:: Making a command distinguish interactive calls. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Adjusting Point:: Adjustment of point after a command. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Special Events:: Events processed immediately and individually. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. - -Defining Commands - -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. - -Input Events - -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. - Event types. -* Accessing Mouse:: Functions to extract info from mouse events. -* Accessing Scroll:: Functions to get info from scroll bar events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. - -Reading Input - -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. - -Keymaps - -* Key Sequences:: Key sequences as Lisp objects. -* Keymap Basics:: Basic concepts of keymaps. -* Format of Keymaps:: What a keymap looks like as a Lisp object. -* Creating Keymaps:: Functions to create and copy keymaps. -* Inheritance and Keymaps:: How one keymap can inherit the bindings - of another keymap. -* Prefix Keys:: Defining a key with a keymap as its definition. -* Active Keymaps:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A minor mode can also override them. -* Key Lookup:: Finding a key's binding in one keymap. -* Functions for Key Lookup:: How to request key lookup. -* Changing Key Bindings:: Redefining a key in a keymap. -* Remapping Commands:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* Key Binding Commands:: Interactive interfaces for redefining keys. -* Scanning Keymaps:: Looking through all keymaps, for printing help. -* Menu Keymaps:: Defining a menu as a keymap. - -Menu Keymaps - -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. - -Defining Menus - -* Simple Menu Items:: A simple kind of menu key binding, - limited in capabilities. -* Extended Menu Items:: More powerful menu item definitions - let you specify keywords to enable - various features. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. -* Toolkit Differences:: Not all toolkits provide the same features. - -Major and Minor Modes - -* Hooks:: How to use hooks; how to write code that provides hooks. -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Imenu:: Providing a menu of definitions made in a buffer. -* Font Lock Mode:: How modes can highlight text according to syntax. -* Auto-Indentation:: How to teach Emacs to indent for a major mode. -* Desktop Save Mode:: How modes can have buffer state saved between - Emacs sessions. - -Hooks - -* Running Hooks:: How to run a hook. -* Setting Hooks:: How to put functions on a hook, or remove them. - -Major Modes - -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. -* Derived Modes:: Defining a new major mode based on another major - mode. -* Basic Major Modes:: Modes that other modes are often derived from. -* Mode Hooks:: Hooks run at the end of major mode functions. -* Tabulated List Mode:: Parent mode for buffers containing tabulated data. -* Generic Modes:: Defining a simple major mode that supports - comment syntax and Font Lock mode. -* Example Major Modes:: Text mode and Lisp modes. - -Minor Modes - -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -* Defining Minor Modes:: A convenient facility for defining minor modes. - -Mode Line Format - -* Mode Line Basics:: Basic ideas of mode line control. -* Mode Line Data:: The data structure that controls the mode line. -* Mode Line Top:: The top level variable, mode-line-format. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. -* Properties in Mode:: Using text properties in the mode line. -* Header Lines:: Like a mode line, but at the top. -* Emulating Mode Line:: Formatting text as the mode line would. - -Font Lock Mode - -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. - -Multiline Font Lock Constructs - -* Font Lock Multiline:: Marking multiline chunks with a text property. -* Region to Refontify:: Controlling which region gets refontified - after a buffer change. - -Automatic Indentation of code - -* SMIE:: A simple minded indentation engine. - -Simple Minded Indentation Engine - -* SMIE setup:: SMIE setup and features. -* Operator Precedence Grammars:: A very simple parsing technique. -* SMIE Grammar:: Defining the grammar of a language. -* SMIE Lexer:: Defining tokens. -* SMIE Tricks:: Working around the parser's limitations. -* SMIE Indentation:: Specifying indentation rules. -* SMIE Indentation Helpers:: Helper functions for indentation rules. -* SMIE Indentation Example:: Sample indentation rules. - -Documentation - -* Documentation Basics:: Where doc strings are defined and stored. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. - -Files - -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing Files:: Renaming files, changing permissions, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Special handling for certain file names. -* Format Conversion:: Conversion to and from various file formats. - -Visiting Files - -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. - -Information about Files - -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A symbolic link? -* Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: How large is it? Any other names? Etc. -* Locating Files:: How to find a file in standard places. - -File Names - -* File Name Components:: The directory part of a file name, and the rest. -* Relative File Names:: Some file names are relative to a current directory. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. -* Standard File Names:: If your package uses a fixed file name, - how to handle various operating systems simply. - -File Format Conversion - -* Format Conversion Overview:: @code{insert-file-contents} and @code{write-region}. -* Format Conversion Round-Trip:: Using @code{format-alist}. -* Format Conversion Piecemeal:: Specifying non-paired conversion. - -Backups and Auto-Saving - -* Backup Files:: How backup files are made; how their names - are chosen. -* Auto-Saving:: How auto-save files are made; how their - names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize - what it does. - -Backup Files - -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file - or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. - -Buffers - -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so that primitives will access its contents. -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file - is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - "behind Emacs's back". -* Read Only Buffers:: Modifying text is not allowed in a - read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Indirect Buffers:: An indirect buffer shares text with some - other buffer. -* Swapping Text:: Swapping text between two buffers. -* Buffer Gap:: The gap in the buffer. - -Windows - -* Basic Windows:: Basic information on using windows. -* Windows and Frames:: Relating windows to the frame they appear on. -* Window Sizes:: Accessing a window's size. -* Resizing Windows:: Changing the sizes of windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Switching Buffers:: Higher-level functions for switching to a buffer. -* Choosing Window:: How to choose a window for displaying a buffer. -* Display Action Functions:: Subroutines for @code{display-buffer}. -* Choosing Window Options:: Extra options affecting how buffers are displayed. -* Window History:: Each window remembers the buffers displayed in it. -* Dedicated Windows:: How to avoid displaying another buffer in - a specific window. -* Quitting Windows:: How to restore the state prior to displaying a - buffer. -* Window Point:: Each window has its own location of point. -* Window Start and End:: Buffer positions indicating which text is - on-screen in a window. -* Textual Scrolling:: Moving text up and down through the window. -* Vertical Scrolling:: Moving the contents up and down on the window. -* Horizontal Scrolling:: Moving the contents sideways on the window. -* Coordinates and Windows:: Converting coordinates to windows. -* Window Configurations:: Saving and restoring the state of the screen. -* Window Parameters:: Associating additional information with windows. -* Window Hooks:: Hooks for scrolling, window size changes, - redisplay going past a certain point, - or window configuration changes. - -Frames - -* Creating Frames:: Creating additional frames. -* Multiple Terminals:: Displaying on several different devices. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Terminal Parameters:: Parameters common for all frames on terminal. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other windows; - lowering it makes the others hide it. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shape:: Specifying the shape of the mouse pointer. -* Window System Selections::Transferring text to and from other X clients. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* Color Names:: Getting the definitions of color names. -* Text Terminal Colors:: Defining colors for text terminals. -* Resources:: Getting resource values from the server. -* Display Feature Testing:: Determining the features of a terminal. - -Frame Parameters - -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. - -Window Frame Parameters - -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Font and Color Parameters:: Fonts and colors for the frame text. - -Positions - -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. - -Motion - -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. - -Markers - -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers::Finding the marker's buffer or character position. -* Marker Insertion Types:: Two ways a marker can relocate when you - insert where it points. -* Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How "the mark" is implemented with a marker. -* The Region:: How to access "the region". - -Text - -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* Comparing Text:: Comparing substrings of buffers. -* Insertion:: Adding new text to a buffer. -* Commands for Insertion:: User-level commands to insert text. -* Deletion:: Removing text from a buffer. -* User-Level Deletion:: User-level commands to delete text. -* The Kill Ring:: Where removed text sometimes is saved for - later use. -* Undo:: Undoing changes to the text of a buffer. -* Maintaining Undo:: How to enable and disable undo information. - How to control how much information is kept. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix - from context. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Sorting:: Functions for sorting parts of the buffer. -* Columns:: Computing horizontal positions, and using them. -* Indentation:: Functions to insert or adjust indentation. -* Case Changes:: Case conversion of parts of the buffer. -* Text Properties:: Assigning Lisp property lists to text characters. -* Substitution:: Replacing a given character wherever it appears. -* Transposition:: Swapping two portions of a buffer. -* Registers:: How registers are implemented. Accessing - the text or position stored in a register. -* Base 64:: Conversion to or from base 64 encoding. -* Checksum/Hash:: Computing cryptographic hashes. -* Parsing HTML/XML:: Parsing HTML and XML. -* Atomic Changes:: Installing several buffer changes "atomically". -* Change Hooks:: Supplying functions to be run when text is changed. - -The Kill Ring - -* Kill Ring Concepts:: What text looks like in the kill ring. -* Kill Functions:: Functions that kill text. -* Yanking:: How yanking is done. -* Yank Commands:: Commands that access the kill ring. -* Low-Level Kill Ring:: Functions and variables for kill ring access. -* Internals of Kill Ring:: Variables that hold kill ring data. - -Indentation - -* Primitive Indent:: Functions used to count and insert indentation. -* Mode-Specific Indent:: Customize indentation for different modes. -* Region Indent:: Indent all the lines in a region. -* Relative Indent:: Indent the current line based on previous lines. -* Indent Tabs:: Adjustable, typewriter-like tab stops. -* Motion by Indent:: Move to first non-blank character. - -Text Properties - -* Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. -* Format Properties:: Properties for representing formatting of text. -* Sticky Properties:: How inserted text gets properties from - neighboring text. -* Lazy Properties:: Computing text properties in a lazy fashion - only when text is examined. -* Clickable Text:: Using text properties to make regions of text - do something when you click on them. -* Fields:: The @code{field} property defines - fields within the buffer. -* Not Intervals:: Why text properties do not use - Lisp-visible text intervals. - -Non-@acronym{ASCII} Characters - -* Text Representations:: How Emacs represents text. -* Converting Representations:: Converting unibyte to multibyte and vice versa. -* Selecting a Representation:: Treating a byte sequence as unibyte or multi. -* Character Codes:: How unibyte and multibyte relate to - codes of individual characters. -* Character Properties:: Character attributes that define their - behavior and handling. -* Character Sets:: The space of possible character codes - is divided into various character sets. -* Scanning Charsets:: Which character sets are used in a buffer? -* Translation of Characters:: Translation tables are used for conversion. -* Coding Systems:: Coding systems are conversions for saving files. -* Input Methods:: Input methods allow users to enter various - non-ASCII characters without special keyboards. -* Locales:: Interacting with the POSIX locale. - -Coding Systems - -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -* MS-DOS File Types:: How DOS "text" and "binary" files - relate to coding systems. - -Searching and Matching - -* String Search:: Search for an exact match. -* Searching and Case:: Case-independent or case-significant searching. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Match Data:: Finding out which part of the text matched, - after a string or regexp search. -* Search and Replace:: Commands that loop, searching and replacing. -* Standard Regexps:: Useful regexps for finding sentences, pages,... - -Regular Expressions - -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. -* Regexp Functions:: Functions for operating on regular expressions. - -Syntax of Regular Expressions - -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. - -The Match Data - -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. - -Syntax Tables - -* Syntax Basics:: Basic concepts of syntax tables. -* Syntax Descriptors:: How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Syntax Properties:: Overriding syntax with text properties. -* Motion and Syntax:: Moving over characters with certain syntaxes. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. -* Categories:: Another way of classifying character syntax. - -Syntax Descriptors - -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. - -Parsing Expressions - -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. - -Abbrevs and Abbrev Expansion - -* Abbrev Tables:: Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Abbrev Files:: Saving abbrevs in files. -* Abbrev Expansion:: Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. -* Abbrev Properties:: How to read and set abbrev properties. - Which properties have which effect. -* Abbrev Table Properties:: How to read and set abbrev table properties. - Which properties have which effect. - -Processes - -* Subprocess Creation:: Functions that start subprocesses. -* Shell Arguments:: Quoting an argument to pass it to a shell. -* Synchronous Processes:: Details of using synchronous subprocesses. -* Asynchronous Processes:: Starting up an asynchronous subprocess. -* Deleting Processes:: Eliminating an asynchronous subprocess. -* Process Information:: Accessing run-status and other attributes. -* Input to Processes:: Sending input to an asynchronous subprocess. -* Signals to Processes:: Stopping, continuing or interrupting - an asynchronous subprocess. -* Output from Processes:: Collecting output from an asynchronous subprocess. -* Sentinels:: Sentinels run when process run-status changes. -* Query Before Exit:: Whether to query if exiting will kill a process. -* System Processes:: Accessing other processes running on your system. -* Transaction Queues:: Transaction-based communication with subprocesses. -* Network:: Opening network connections. -* Network Servers:: Network servers let Emacs accept net connections. -* Datagrams:: UDP network connections. -* Low-Level Network:: Lower-level but more general function - to create connections and servers. -* Misc Network:: Additional relevant functions for net connections. -* Serial Ports:: Communicating with serial ports. -* Byte Packing:: Using bindat to pack and unpack binary data. - -Receiving Output from Processes - -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Decoding Output:: Filters can get unibyte or multibyte strings. -* Accepting Output:: How to wait until process output arrives. - -Low-Level Network Access - -* Network Processes:: Using @code{make-network-process}. -* Network Options:: Further control over network connections. -* Network Feature Testing:: Determining which network features work on - the machine you are using. - -Packing and Unpacking Byte Arrays - -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! - -Emacs Display - -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Forcing Redisplay:: Forcing redisplay. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Displaying messages at the bottom of the screen. -* Warnings:: Displaying warning messages for the user. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* Temporary Displays:: Displays that go away automatically. -* Overlays:: Use overlays to highlight parts of the buffer. -* Width:: How wide a character or string is on the screen. -* Line Height:: Controlling the height of lines. -* Faces:: A face defines a graphics style - for text characters: font, colors, etc. -* Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. -* Display Property:: Enabling special display features. -* Images:: Displaying images in Emacs buffers. -* Buttons:: Adding clickable buttons to Emacs buffers. -* Abstract Display:: Emacs's Widget for Object Collections. -* Blinking:: How Emacs shows the matching open parenthesis. -* Character Display:: How Emacs displays individual characters. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. -* Bidirectional Display:: Display of bidirectional scripts, such as - Arabic and Farsi. - -The Echo Area - -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. - -Reporting Warnings - -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize - their warnings. -* Warning Options:: Variables users set to control display of warnings. -* Delayed Warnings:: Deferring a warning until the end of a command. - -Overlays - -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. - -Faces - -* Defining Faces:: How to define a face. -* Face Attributes:: What is in a face? -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for - a character. -* Face Remapping:: Remapping faces to alternative definitions. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Basic Faces:: Faces that are defined by default. -* Font Selection:: Finding the best available font for a face. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. -* Low-Level Font:: Lisp representation for character display fonts. - -Fringes - -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. - -The @code{display} Property - -* Replacing Specs:: Display specs that replace the text. -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; adjusting the height, - spacing, and other properties of text. -* Display Margins:: Displaying text or images to the side of - the main text. - -Images - -* Image Formats:: Supported image formats. -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* GIF Images:: Special features for GIF format. -* TIFF Images:: Special features for TIFF format. -* PostScript Images:: Special features for PostScript format. -* ImageMagick Images:: Special features available through ImageMagick. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once - it is defined. -* Animated Images:: Some image formats can be animated. -* Image Cache:: Internal mechanisms of image display. - -Buttons - -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. - -Abstract Display - -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. - -Character Display - -* Usual Display:: The usual conventions for displaying characters. -* Display Tables:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. -* Glyphless Chars:: How glyphless characters are drawn. - -Operating System Interface - -* Starting Up:: Customizing Emacs startup processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* User Identification:: Finding the name and user id of the user. -* Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to - calendrical data and vice versa. -* Time Parsing:: Converting a time from numeric form to text - and vice versa. -* Processor Run Time:: Getting the run time used by Emacs. -* Time Calculations:: Adding, subtracting, comparing times, etc. -* Timers:: Setting a timer to call a function at a - certain time. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording terminal input. -* Terminal Output:: Controlling and recording terminal output. -* Sound Output:: Playing sounds on the computer's speaker. -* X11 Keysyms:: Operating on key symbols for X Windows. -* Batch Mode:: Running Emacs without terminal interaction. -* Session Management:: Saving and restoring state with - X Session Management. -* Notifications:: Desktop notifications. -* Dynamic Libraries:: On-demand loading of support libraries. - -Starting Up Emacs - -* Startup Summary:: Sequence of actions Emacs performs at startup. -* Init File:: Details on reading the init file. -* Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command-Line Arguments:: How command-line arguments are processed, - and how you can customize them. - -Getting Out of Emacs - -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. - -Terminal Input - -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. - -Preparing Lisp code for distribution - -* Packaging Basics:: The basic concepts of Emacs Lisp packages. -* Simple Packages:: How to package a single .el file. -* Multi-file Packages:: How to package multiple files. -* Package Archives:: Maintaining package archives. - -Tips and Conventions - -* Coding Conventions:: Conventions for clean and robust programs. -* Key Binding Conventions:: Which keys should be bound by which programs. -* Programming Tips:: Making Emacs code fit smoothly in Emacs. -* Compilation Tips:: Making compiled code run fast. -* Warning Tips:: Turning off compiler warnings. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. - -GNU Emacs Internals - -* Building Emacs:: How the dumped Emacs is made. -* Pure Storage:: Kludge to make preloaded Lisp functions shareable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Memory Usage:: Info about total size of Lisp objects made so far. -* Writing Emacs Primitives:: Writing C code for Emacs. -* Object Internals:: Data formats of buffers, windows, processes. - -Object Internals - -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end detailmenu -@end menu - -@include intro.texi -@include objects.texi -@include numbers.texi -@include strings.texi - -@include lists.texi -@include sequences.texi -@include hash.texi -@include symbols.texi -@include eval.texi - -@include control.texi -@include variables.texi -@include functions.texi -@include macros.texi - -@include customize.texi -@include loading.texi -@include compile.texi -@include advice.texi - -@c This includes edebug.texi. -@include debugging.texi -@include streams.texi -@include minibuf.texi -@include commands.texi - -@include keymaps.texi -@include modes.texi -@include help.texi -@include files.texi - -@include backups.texi -@include buffers.texi -@include windows.texi -@include frames.texi - -@include positions.texi -@include markers.texi -@include text.texi -@include nonascii.texi - -@include searching.texi -@include syntax.texi -@include abbrevs.texi -@include processes.texi - -@include display.texi -@include os.texi - -@include package.texi - -@c MOVE to Emacs Manual: include misc-modes.texi - -@c appendices - -@c REMOVE this: include non-hacker.texi - -@include anti.texi -@include doclicense.texi -@include gpl.texi -@include tips.texi -@include internals.texi -@include errors.texi -@include maps.texi -@include hooks.texi - -@include index.texi - -@ignore -@node New Symbols, , Index, Top -@unnumbered New Symbols Since the Previous Edition - -@printindex tp -@end ignore - -@bye - - -These words prevent "local variables" above from confusing Emacs. diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi deleted file mode 100644 index 76ab8b235f5..00000000000 --- a/doc/lispref/errors.texi +++ /dev/null @@ -1,238 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/errors -@node Standard Errors, Standard Keymaps, GNU Emacs Internals, Top -@appendix Standard Errors -@cindex standard errors - - Here is a list of the more important error symbols in standard Emacs, -grouped by concept. The list includes each symbol's message (on the -@code{error-message} property of the symbol) and a cross reference to a -description of how the error can occur. - - Each error symbol has an @code{error-conditions} property that is a -list of symbols. Normally this list includes the error symbol itself -and the symbol @code{error}. Occasionally it includes additional -symbols, which are intermediate classifications, narrower than -@code{error} but broader than a single error symbol. For example, all -the errors in accessing files have the condition @code{file-error}. If -we do not say here that a certain error symbol has additional error -conditions, that means it has none. - - As a special exception, the error symbol @code{quit} does not have the -condition @code{error}, because quitting is not considered an error. - -@c You can grep for "(put 'foo 'error-conditions ...) to find -@c examples defined in Lisp. Eg soap-client.el, sasl.el. - Most of these error symbols are defined in C (mainly @file{data.c}), -but some are defined in Lisp. For example, the file @file{userlock.el} -defines the @code{file-locked} and @code{file-supersession} errors. -Several of the specialized Lisp libraries distributed with Emacs -define their own error symbols. We do not attempt to list of all -those here. - - @xref{Errors}, for an explanation of how errors are generated and -handled. - -@table @code -@item error -@code{"error"}@* -@xref{Errors}. - -@item quit -@code{"Quit"}@* -@xref{Quitting}. - -@item args-out-of-range -@code{"Args out of range"}@* -This happens when trying to access an element beyond the range of a -sequence or buffer.@* -@xref{Sequences Arrays Vectors}, @xref{Text}. - -@item arith-error -@code{"Arithmetic error"}@* -@xref{Arithmetic Operations}. - -@item beginning-of-buffer -@code{"Beginning of buffer"}@* -@xref{Character Motion}. - -@item buffer-read-only -@code{"Buffer is read-only"}@* -@xref{Read Only Buffers}. - -@item circular-list -@code{"List contains a loop"}@* -This happens when some operations (e.g. resolving face names) -encounter circular structures.@* -@xref{Circular Objects}. - -@item cl-assertion-failed -@code{"Assertion failed"}@* -This happens when the @code{assert} macro fails a test.@* -@xref{Assertions,,, cl, Common Lisp Extensions}. - -@item coding-system-error -@code{"Invalid coding system"}@* -@xref{Lisp and Coding Systems}. - -@item cyclic-function-indirection -@code{"Symbol's chain of function indirections contains a loop"}@* -@xref{Function Indirection}. - -@item cyclic-variable-indirection -@code{"Symbol's chain of variable indirections contains a loop"}@* -@xref{Variable Aliases}. - -@item dbus-error -@code{"D-Bus error"}@* -This is only defined if Emacs was compiled with D-Bus support.@* -@xref{Errors and Events,,, dbus, D-Bus integration in Emacs}. - -@item end-of-buffer -@code{"End of buffer"}@* -@xref{Character Motion}. - -@item end-of-file -@code{"End of file during parsing"}@* -Note that this is not a subcategory of @code{file-error}, -because it pertains to the Lisp reader, not to file I/O.@* -@xref{Input Functions}. - -@item file-already-exists -This is a subcategory of @code{file-error}.@* -@xref{Writing to Files}. - -@item file-date-error -This is a subcategory of @code{file-error}. It occurs when -@code{copy-file} tries and fails to set the last-modification time of -the output file.@* -@xref{Changing Files}. - -@item file-error -We do not list the error-strings of this error and its subcategories, -because the error message is normally constructed from the data items -alone when the error condition @code{file-error} is present. Thus, -the error-strings are not very relevant. However, these error symbols -do have @code{error-message} properties, and if no data is provided, -the @code{error-message} property @emph{is} used.@* -@xref{Files}. - -@c jka-compr.el -@item compression-error -This is a subcategory of @code{file-error}, which results from -problems handling a compressed file.@* -@xref{How Programs Do Loading}. - -@c userlock.el -@item file-locked -This is a subcategory of @code{file-error}.@* -@xref{File Locks}. - -@c userlock.el -@item file-supersession -This is a subcategory of @code{file-error}.@* -@xref{Modification Time}. - -@c net/ange-ftp.el -@item ftp-error -This is a subcategory of @code{file-error}, which results from problems -in accessing a remote file using ftp.@* -@xref{Remote Files,,, emacs, The GNU Emacs Manual}. - -@item invalid-function -@code{"Invalid function"}@* -@xref{Function Indirection}. - -@item invalid-read-syntax -@code{"Invalid read syntax"}@* -@xref{Printed Representation}. - -@item invalid-regexp -@code{"Invalid regexp"}@* -@xref{Regular Expressions}. - -@c simple.el -@item mark-inactive -@code{"The mark is not active now"}@* -@xref{The Mark}. - -@item no-catch -@code{"No catch for tag"}@* -@xref{Catch and Throw}. - -@ignore -@c Not actually used for anything? Probably definition should be removed. -@item protected-field -@code{"Attempt to modify a protected field"} -@end ignore - -@item scan-error -@code{"Scan error"}@* -This happens when certain syntax-parsing functions -find invalid syntax or mismatched parentheses.@* -@xref{List Motion}, and @ref{Parsing Expressions}. - -@item search-failed -@code{"Search failed"}@* -@xref{Searching and Matching}. - -@item setting-constant -@code{"Attempt to set a constant symbol"}@* -The values of the symbols @code{nil} and @code{t}, -and any symbols that start with @samp{:}, -may not be changed.@* -@xref{Constant Variables, , Variables that Never Change}. - -@c simple.el -@item text-read-only -@code{"Text is read-only"}@* -This is a subcategory of @code{buffer-read-only}.@* -@xref{Special Properties}. - -@item undefined-color -@code{"Undefined color"}@* -@xref{Color Names}. - -@item void-function -@code{"Symbol's function definition is void"}@* -@xref{Function Cells}. - -@item void-variable -@code{"Symbol's value as variable is void"}@* -@xref{Accessing Variables}. - -@item wrong-number-of-arguments -@code{"Wrong number of arguments"}@* -@xref{Classifying Lists}. - -@item wrong-type-argument -@code{"Wrong type argument"}@* -@xref{Type Predicates}. -@end table - - The following kinds of error, which are classified as special cases of -@code{arith-error}, can occur on certain systems for invalid use of -mathematical functions. @xref{Math Functions}. - -@table @code -@item domain-error -@code{"Arithmetic domain error"} - -@item overflow-error -@code{"Arithmetic overflow error"}@* -This is a subcategory of @code{domain-error}. - -@item range-error -@code{"Arithmetic range error"} - -@item singularity-error -@code{"Arithmetic singularity error"}@* -This is a subcategory of @code{domain-error}. - -@item underflow-error -@code{"Arithmetic underflow error"}@* -This is a subcategory of @code{domain-error}. -@end table diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi deleted file mode 100644 index 342c79e48e8..00000000000 --- a/doc/lispref/eval.texi +++ /dev/null @@ -1,866 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/eval -@node Evaluation, Control Structures, Symbols, Top -@chapter Evaluation -@cindex evaluation -@cindex interpreter -@cindex interpreter -@cindex value of expression - - The @dfn{evaluation} of expressions in Emacs Lisp is performed by the -@dfn{Lisp interpreter}---a program that receives a Lisp object as input -and computes its @dfn{value as an expression}. How it does this depends -on the data type of the object, according to rules described in this -chapter. The interpreter runs automatically to evaluate portions of -your program, but can also be called explicitly via the Lisp primitive -function @code{eval}. - -@ifnottex -@menu -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in the program). -* Backquote:: Easier construction of list structure. -* Eval:: How to invoke the Lisp interpreter explicitly. -@end menu - -@node Intro Eval -@section Introduction to Evaluation - - The Lisp interpreter, or evaluator, is the part of Emacs that -computes the value of an expression that is given to it. When a -function written in Lisp is called, the evaluator computes the value -of the function by evaluating the expressions in the function body. -Thus, running any Lisp program really means running the Lisp -interpreter. -@end ifnottex - -@cindex form -@cindex expression -@cindex S-expression - A Lisp object that is intended for evaluation is called a @dfn{form} -or @dfn{expression}@footnote{It is sometimes also referred to as an -@dfn{S-expression} or @dfn{sexp}, but we generally do not use this -terminology in this manual.}. The fact that forms are data objects -and not merely text is one of the fundamental differences between -Lisp-like languages and typical programming languages. Any object can -be evaluated, but in practice only numbers, symbols, lists and strings -are evaluated very often. - - In subsequent sections, we will describe the details of what -evaluation means for each kind of form. - - It is very common to read a Lisp form and then evaluate the form, -but reading and evaluation are separate activities, and either can be -performed alone. Reading per se does not evaluate anything; it -converts the printed representation of a Lisp object to the object -itself. It is up to the caller of @code{read} to specify whether this -object is a form to be evaluated, or serves some entirely different -purpose. @xref{Input Functions}. - -@cindex recursive evaluation - Evaluation is a recursive process, and evaluating a form often -involves evaluating parts within that form. For instance, when you -evaluate a @dfn{function call} form such as @code{(car x)}, Emacs -first evaluates the argument (the subform @code{x}). After evaluating -the argument, Emacs @dfn{executes} the function (@code{car}), and if -the function is written in Lisp, execution works by evaluating the -@dfn{body} of the function (in this example, however, @code{car} is -not a Lisp function; it is a primitive function implemented in C). -@xref{Functions}, for more information about functions and function -calls. - -@cindex environment - Evaluation takes place in a context called the @dfn{environment}, -which consists of the current values and bindings of all Lisp -variables (@pxref{Variables}).@footnote{This definition of -``environment'' is specifically not intended to include all the data -that can affect the result of a program.} Whenever a form refers to a -variable without creating a new binding for it, the variable evaluates -to the value given by the current environment. Evaluating a form may -also temporarily alter the environment by binding variables -(@pxref{Local Variables}). - -@cindex side effect - Evaluating a form may also make changes that persist; these changes -are called @dfn{side effects}. An example of a form that produces a -side effect is @code{(setq foo 1)}. - - Do not confuse evaluation with command key interpretation. The -editor command loop translates keyboard input into a command (an -interactively callable function) using the active keymaps, and then -uses @code{call-interactively} to execute that command. Executing the -command usually involves evaluation, if the command is written in -Lisp; however, this step is not considered a part of command key -interpretation. @xref{Command Loop}. - -@node Forms -@section Kinds of Forms - - A Lisp object that is intended to be evaluated is called a -@dfn{form} (or an @dfn{expression}). How Emacs evaluates a form -depends on its data type. Emacs has three different kinds of form -that are evaluated differently: symbols, lists, and ``all other -types''. This section describes all three kinds, one by one, starting -with the ``all other types'' which are self-evaluating forms. - -@menu -* Self-Evaluating Forms:: Forms that evaluate to themselves. -* Symbol Forms:: Symbols evaluate as variables. -* Classifying Lists:: How to distinguish various sorts of list forms. -* Function Indirection:: When a symbol appears as the car of a list, - we find the real function via the symbol. -* Function Forms:: Forms that call functions. -* Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, - most of them extremely important. -* Autoloading:: Functions set up to load files - containing their real definitions. -@end menu - -@node Self-Evaluating Forms -@subsection Self-Evaluating Forms -@cindex vector evaluation -@cindex literal evaluation -@cindex self-evaluating form - - A @dfn{self-evaluating form} is any form that is not a list or -symbol. Self-evaluating forms evaluate to themselves: the result of -evaluation is the same object that was evaluated. Thus, the number 25 -evaluates to 25, and the string @code{"foo"} evaluates to the string -@code{"foo"}. Likewise, evaluating a vector does not cause evaluation -of the elements of the vector---it returns the same vector with its -contents unchanged. - -@example -@group -'123 ; @r{A number, shown without evaluation.} - @result{} 123 -@end group -@group -123 ; @r{Evaluated as usual---result is the same.} - @result{} 123 -@end group -@group -(eval '123) ; @r{Evaluated ``by hand''---result is the same.} - @result{} 123 -@end group -@group -(eval (eval '123)) ; @r{Evaluating twice changes nothing.} - @result{} 123 -@end group -@end example - - It is common to write numbers, characters, strings, and even vectors -in Lisp code, taking advantage of the fact that they self-evaluate. -However, it is quite unusual to do this for types that lack a read -syntax, because there's no way to write them textually. It is possible -to construct Lisp expressions containing these types by means of a Lisp -program. Here is an example: - -@example -@group -;; @r{Build an expression containing a buffer object.} -(setq print-exp (list 'print (current-buffer))) - @result{} (print #) -@end group -@group -;; @r{Evaluate it.} -(eval print-exp) - @print{} # - @result{} # -@end group -@end example - -@node Symbol Forms -@subsection Symbol Forms -@cindex symbol evaluation - - When a symbol is evaluated, it is treated as a variable. The result -is the variable's value, if it has one. If the symbol has no value as -a variable, the Lisp interpreter signals an error. For more -information on the use of variables, see @ref{Variables}. - - In the following example, we set the value of a symbol with -@code{setq}. Then we evaluate the symbol, and get back the value that -@code{setq} stored. - -@example -@group -(setq a 123) - @result{} 123 -@end group -@group -(eval 'a) - @result{} 123 -@end group -@group -a - @result{} 123 -@end group -@end example - - The symbols @code{nil} and @code{t} are treated specially, so that the -value of @code{nil} is always @code{nil}, and the value of @code{t} is -always @code{t}; you cannot set or bind them to any other values. Thus, -these two symbols act like self-evaluating forms, even though -@code{eval} treats them like any other symbol. A symbol whose name -starts with @samp{:} also self-evaluates in the same way; likewise, -its value ordinarily cannot be changed. @xref{Constant Variables}. - -@node Classifying Lists -@subsection Classification of List Forms -@cindex list form evaluation - - A form that is a nonempty list is either a function call, a macro -call, or a special form, according to its first element. These three -kinds of forms are evaluated in different ways, described below. The -remaining list elements constitute the @dfn{arguments} for the function, -macro, or special form. - - The first step in evaluating a nonempty list is to examine its first -element. This element alone determines what kind of form the list is -and how the rest of the list is to be processed. The first element is -@emph{not} evaluated, as it would be in some Lisp dialects such as -Scheme. - -@node Function Indirection -@subsection Symbol Function Indirection -@cindex symbol function indirection -@cindex indirection for functions -@cindex void function - - If the first element of the list is a symbol then evaluation -examines the symbol's function cell, and uses its contents instead of -the original symbol. If the contents are another symbol, this -process, called @dfn{symbol function indirection}, is repeated until -it obtains a non-symbol. @xref{Function Names}, for more information -about symbol function indirection. - - One possible consequence of this process is an infinite loop, in the -event that a symbol's function cell refers to the same symbol. Or a -symbol may have a void function cell, in which case the subroutine -@code{symbol-function} signals a @code{void-function} error. But if -neither of these things happens, we eventually obtain a non-symbol, -which ought to be a function or other suitable object. - -@kindex invalid-function - More precisely, we should now have a Lisp function (a lambda -expression), a byte-code function, a primitive function, a Lisp macro, -a special form, or an autoload object. Each of these types is a case -described in one of the following sections. If the object is not one -of these types, Emacs signals an @code{invalid-function} error. - - The following example illustrates the symbol indirection process. We -use @code{fset} to set the function cell of a symbol and -@code{symbol-function} to get the function cell contents -(@pxref{Function Cells}). Specifically, we store the symbol @code{car} -into the function cell of @code{first}, and the symbol @code{first} into -the function cell of @code{erste}. - -@example -@group -;; @r{Build this function cell linkage:} -;; ------------- ----- ------- ------- -;; | # | <-- | car | <-- | first | <-- | erste | -;; ------------- ----- ------- ------- -@end group -@group -(symbol-function 'car) - @result{} # -@end group -@group -(fset 'first 'car) - @result{} car -@end group -@group -(fset 'erste 'first) - @result{} first -@end group -@group -(erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.} - @result{} 1 -@end group -@end example - - By contrast, the following example calls a function without any symbol -function indirection, because the first element is an anonymous Lisp -function, not a symbol. - -@example -@group -((lambda (arg) (erste arg)) - '(1 2 3)) - @result{} 1 -@end group -@end example - -@noindent -Executing the function itself evaluates its body; this does involve -symbol function indirection when calling @code{erste}. - - This form is rarely used and is now deprecated. Instead, you should write it -as: - -@example -@group -(funcall (lambda (arg) (erste arg)) - '(1 2 3)) -@end group -@end example -or just -@example -@group -(let ((arg '(1 2 3))) (erste arg)) -@end group -@end example - - The built-in function @code{indirect-function} provides an easy way to -perform symbol function indirection explicitly. - -@c Emacs 19 feature -@defun indirect-function function &optional noerror -@anchor{Definition of indirect-function} -This function returns the meaning of @var{function} as a function. If -@var{function} is a symbol, then it finds @var{function}'s function -definition and starts over with that value. If @var{function} is not a -symbol, then it returns @var{function} itself. - -This function signals a @code{void-function} error if the final symbol -is unbound and optional argument @var{noerror} is @code{nil} or -omitted. Otherwise, if @var{noerror} is non-@code{nil}, it returns -@code{nil} if the final symbol is unbound. - -It signals a @code{cyclic-function-indirection} error if there is a -loop in the chain of symbols. - -Here is how you could define @code{indirect-function} in Lisp: - -@example -(defun indirect-function (function) - (if (symbolp function) - (indirect-function (symbol-function function)) - function)) -@end example -@end defun - -@node Function Forms -@subsection Evaluation of Function Forms -@cindex function form evaluation -@cindex function call - - If the first element of a list being evaluated is a Lisp function -object, byte-code object or primitive function object, then that list is -a @dfn{function call}. For example, here is a call to the function -@code{+}: - -@example -(+ 1 x) -@end example - - The first step in evaluating a function call is to evaluate the -remaining elements of the list from left to right. The results are the -actual argument values, one value for each list element. The next step -is to call the function with this list of arguments, effectively using -the function @code{apply} (@pxref{Calling Functions}). If the function -is written in Lisp, the arguments are used to bind the argument -variables of the function (@pxref{Lambda Expressions}); then the forms -in the function body are evaluated in order, and the value of the last -body form becomes the value of the function call. - -@node Macro Forms -@subsection Lisp Macro Evaluation -@cindex macro call evaluation - - If the first element of a list being evaluated is a macro object, then -the list is a @dfn{macro call}. When a macro call is evaluated, the -elements of the rest of the list are @emph{not} initially evaluated. -Instead, these elements themselves are used as the arguments of the -macro. The macro definition computes a replacement form, called the -@dfn{expansion} of the macro, to be evaluated in place of the original -form. The expansion may be any sort of form: a self-evaluating -constant, a symbol, or a list. If the expansion is itself a macro call, -this process of expansion repeats until some other sort of form results. - - Ordinary evaluation of a macro call finishes by evaluating the -expansion. However, the macro expansion is not necessarily evaluated -right away, or at all, because other programs also expand macro calls, -and they may or may not evaluate the expansions. - - Normally, the argument expressions are not evaluated as part of -computing the macro expansion, but instead appear as part of the -expansion, so they are computed when the expansion is evaluated. - - For example, given a macro defined as follows: - -@example -@group -(defmacro cadr (x) - (list 'car (list 'cdr x))) -@end group -@end example - -@noindent -an expression such as @code{(cadr (assq 'handler list))} is a macro -call, and its expansion is: - -@example -(car (cdr (assq 'handler list))) -@end example - -@noindent -Note that the argument @code{(assq 'handler list)} appears in the -expansion. - -@xref{Macros}, for a complete description of Emacs Lisp macros. - -@node Special Forms -@subsection Special Forms -@cindex special forms -@cindex evaluation of special forms - - A @dfn{special form} is a primitive function specially marked so that -its arguments are not all evaluated. Most special forms define control -structures or perform variable bindings---things which functions cannot -do. - - Each special form has its own rules for which arguments are evaluated -and which are used without evaluation. Whether a particular argument is -evaluated may depend on the results of evaluating other arguments. - - Here is a list, in alphabetical order, of all of the special forms in -Emacs Lisp with a reference to where each is described. - -@table @code -@item and -@pxref{Combining Conditions} - -@item catch -@pxref{Catch and Throw} - -@item cond -@pxref{Conditionals} - -@item condition-case -@pxref{Handling Errors} - -@item defconst -@pxref{Defining Variables} - -@item defmacro -@pxref{Defining Macros} - -@item defun -@pxref{Defining Functions} - -@item defvar -@pxref{Defining Variables} - -@item function -@pxref{Anonymous Functions} - -@item if -@pxref{Conditionals} - -@item interactive -@pxref{Interactive Call} - -@item let -@itemx let* -@pxref{Local Variables} - -@item or -@pxref{Combining Conditions} - -@item prog1 -@itemx prog2 -@itemx progn -@pxref{Sequencing} - -@item quote -@pxref{Quoting} - -@item save-current-buffer -@pxref{Current Buffer} - -@item save-excursion -@pxref{Excursions} - -@item save-restriction -@pxref{Narrowing} - -@item save-window-excursion -@pxref{Window Configurations} - -@item setq -@pxref{Setting Variables} - -@item setq-default -@pxref{Creating Buffer-Local} - -@item track-mouse -@pxref{Mouse Tracking} - -@item unwind-protect -@pxref{Nonlocal Exits} - -@item while -@pxref{Iteration} - -@item with-output-to-temp-buffer -@pxref{Temporary Displays} -@end table - -@cindex CL note---special forms compared -@quotation -@b{Common Lisp note:} Here are some comparisons of special forms in -GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and -@code{catch} are special forms in both Emacs Lisp and Common Lisp. -@code{defun} is a special form in Emacs Lisp, but a macro in Common -Lisp. @code{save-excursion} is a special form in Emacs Lisp, but -doesn't exist in Common Lisp. @code{throw} is a special form in -Common Lisp (because it must be able to throw multiple values), but it -is a function in Emacs Lisp (which doesn't have multiple -values).@refill -@end quotation - -@node Autoloading -@subsection Autoloading - - The @dfn{autoload} feature allows you to call a function or macro -whose function definition has not yet been loaded into Emacs. It -specifies which file contains the definition. When an autoload object -appears as a symbol's function definition, calling that symbol as a -function automatically loads the specified file; then it calls the -real definition loaded from that file. The way to arrange for an -autoload object to appear as a symbol's function definition is -described in @ref{Autoload}. - -@node Quoting -@section Quoting - - The special form @code{quote} returns its single argument, as written, -without evaluating it. This provides a way to include constant symbols -and lists, which are not self-evaluating objects, in a program. (It is -not necessary to quote self-evaluating objects such as numbers, strings, -and vectors.) - -@defspec quote object -This special form returns @var{object}, without evaluating it. -@end defspec - -@cindex @samp{'} for quoting -@cindex quoting using apostrophe -@cindex apostrophe for quoting -Because @code{quote} is used so often in programs, Lisp provides a -convenient read syntax for it. An apostrophe character (@samp{'}) -followed by a Lisp object (in read syntax) expands to a list whose first -element is @code{quote}, and whose second element is the object. Thus, -the read syntax @code{'x} is an abbreviation for @code{(quote x)}. - -Here are some examples of expressions that use @code{quote}: - -@example -@group -(quote (+ 1 2)) - @result{} (+ 1 2) -@end group -@group -(quote foo) - @result{} foo -@end group -@group -'foo - @result{} foo -@end group -@group -''foo - @result{} (quote foo) -@end group -@group -'(quote foo) - @result{} (quote foo) -@end group -@group -['foo] - @result{} [(quote foo)] -@end group -@end example - - Other quoting constructs include @code{function} (@pxref{Anonymous -Functions}), which causes an anonymous lambda expression written in Lisp -to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote -only part of a list, while computing and substituting other parts. - -@node Backquote -@section Backquote -@cindex backquote (list substitution) -@cindex ` (list substitution) -@findex ` - - @dfn{Backquote constructs} allow you to quote a list, but -selectively evaluate elements of that list. In the simplest case, it -is identical to the special form @code{quote} -@iftex -@end iftex -@ifnottex -(described in the previous section; @pxref{Quoting}). -@end ifnottex -For example, these two forms yield identical results: - -@example -@group -`(a list of (+ 2 3) elements) - @result{} (a list of (+ 2 3) elements) -@end group -@group -'(a list of (+ 2 3) elements) - @result{} (a list of (+ 2 3) elements) -@end group -@end example - -@findex , @r{(with backquote)} - The special marker @samp{,} inside of the argument to backquote -indicates a value that isn't constant. The Emacs Lisp evaluator -evaluates the argument of @samp{,}, and puts the value in the list -structure: - -@example -@group -`(a list of ,(+ 2 3) elements) - @result{} (a list of 5 elements) -@end group -@end example - -@noindent -Substitution with @samp{,} is allowed at deeper levels of the list -structure also. For example: - -@example -@group -`(1 2 (3 ,(+ 4 5))) - @result{} (1 2 (3 9)) -@end group -@end example - -@findex ,@@ @r{(with backquote)} -@cindex splicing (with backquote) - You can also @dfn{splice} an evaluated value into the resulting list, -using the special marker @samp{,@@}. The elements of the spliced list -become elements at the same level as the other elements of the resulting -list. The equivalent code without using @samp{`} is often unreadable. -Here are some examples: - -@example -@group -(setq some-list '(2 3)) - @result{} (2 3) -@end group -@group -(cons 1 (append some-list '(4) some-list)) - @result{} (1 2 3 4 2 3) -@end group -@group -`(1 ,@@some-list 4 ,@@some-list) - @result{} (1 2 3 4 2 3) -@end group - -@group -(setq list '(hack foo bar)) - @result{} (hack foo bar) -@end group -@group -(cons 'use - (cons 'the - (cons 'words (append (cdr list) '(as elements))))) - @result{} (use the words foo bar as elements) -@end group -@group -`(use the words ,@@(cdr list) as elements) - @result{} (use the words foo bar as elements) -@end group -@end example - - -@node Eval -@section Eval - - Most often, forms are evaluated automatically, by virtue of their -occurrence in a program being run. On rare occasions, you may need to -write code that evaluates a form that is computed at run time, such as -after reading a form from text being edited or getting one from a -property list. On these occasions, use the @code{eval} function. -Often @code{eval} is not needed and something else should be used instead. -For example, to get the value of a variable, while @code{eval} works, -@code{symbol-value} is preferable; or rather than store expressions -in a property list that then need to go through @code{eval}, it is better to -store functions instead that are then passed to @code{funcall}. - - The functions and variables described in this section evaluate forms, -specify limits to the evaluation process, or record recently returned -values. Loading a file also does evaluation (@pxref{Loading}). - - It is generally cleaner and more flexible to store a function in a -data structure, and call it with @code{funcall} or @code{apply}, than -to store an expression in the data structure and evaluate it. Using -functions provides the ability to pass information to them as -arguments. - -@defun eval form &optional lexical -This is the basic function for evaluating an expression. It evaluates -@var{form} in the current environment and returns the result. How the -evaluation proceeds depends on the type of the object (@pxref{Forms}). - -The argument @var{lexical}, if non-@code{nil}, means to evaluate -@var{form} using lexical scoping rules for variables, instead of the -default dynamic scoping rules. @xref{Lexical Binding}. - -Since @code{eval} is a function, the argument expression that appears -in a call to @code{eval} is evaluated twice: once as preparation before -@code{eval} is called, and again by the @code{eval} function itself. -Here is an example: - -@example -@group -(setq foo 'bar) - @result{} bar -@end group -@group -(setq bar 'baz) - @result{} baz -;; @r{Here @code{eval} receives argument @code{foo}} -(eval 'foo) - @result{} bar -;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}} -(eval foo) - @result{} baz -@end group -@end example - -The number of currently active calls to @code{eval} is limited to -@code{max-lisp-eval-depth} (see below). -@end defun - -@deffn Command eval-region start end &optional stream read-function -@anchor{Definition of eval-region} -This function evaluates the forms in the current buffer in the region -defined by the positions @var{start} and @var{end}. It reads forms from -the region and calls @code{eval} on them until the end of the region is -reached, or until an error is signaled and not handled. - -By default, @code{eval-region} does not produce any output. However, -if @var{stream} is non-@code{nil}, any output produced by output -functions (@pxref{Output Functions}), as well as the values that -result from evaluating the expressions in the region are printed using -@var{stream}. @xref{Output Streams}. - -If @var{read-function} is non-@code{nil}, it should be a function, -which is used instead of @code{read} to read expressions one by one. -This function is called with one argument, the stream for reading -input. You can also use the variable @code{load-read-function} -(@pxref{Definition of load-read-function,, How Programs Do Loading}) -to specify this function, but it is more robust to use the -@var{read-function} argument. - -@code{eval-region} does not move point. It always returns @code{nil}. -@end deffn - -@cindex evaluation of buffer contents -@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print -This is similar to @code{eval-region}, but the arguments provide -different optional features. @code{eval-buffer} operates on the -entire accessible portion of buffer @var{buffer-or-name}. -@var{buffer-or-name} can be a buffer, a buffer name (a string), or -@code{nil} (or omitted), which means to use the current buffer. -@var{stream} is used as in @code{eval-region}, unless @var{stream} is -@code{nil} and @var{print} non-@code{nil}. In that case, values that -result from evaluating the expressions are still discarded, but the -output of the output functions is printed in the echo area. -@var{filename} is the file name to use for @code{load-history} -(@pxref{Unloading}), and defaults to @code{buffer-file-name} -(@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil}, -@code{read} converts strings to unibyte whenever possible. - -@findex eval-current-buffer -@code{eval-current-buffer} is an alias for this command. -@end deffn - -@defopt max-lisp-eval-depth -@anchor{Definition of max-lisp-eval-depth} -This variable defines the maximum depth allowed in calls to @code{eval}, -@code{apply}, and @code{funcall} before an error is signaled (with error -message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). - -This limit, with the associated error when it is exceeded, is one way -Emacs Lisp avoids infinite recursion on an ill-defined function. If -you increase the value of @code{max-lisp-eval-depth} too much, such -code can cause stack overflow instead. -@cindex Lisp nesting error - -The depth limit counts internal uses of @code{eval}, @code{apply}, and -@code{funcall}, such as for calling the functions mentioned in Lisp -expressions, and recursive evaluation of function call arguments and -function body forms, as well as explicit calls in Lisp code. - -The default value of this variable is 400. If you set it to a value -less than 100, Lisp will reset it to 100 if the given value is -reached. Entry to the Lisp debugger increases the value, if there is -little room left, to make sure the debugger itself has room to -execute. - -@code{max-specpdl-size} provides another limit on nesting. -@xref{Definition of max-specpdl-size,, Local Variables}. -@end defopt - -@defvar values -The value of this variable is a list of the values returned by all the -expressions that were read, evaluated, and printed from buffers -(including the minibuffer) by the standard Emacs commands which do -this. (Note that this does @emph{not} include evaluation in -@file{*ielm*} buffers, nor evaluation using @kbd{C-j} in -@code{lisp-interaction-mode}.) The elements are ordered most recent -first. - -@example -@group -(setq x 1) - @result{} 1 -@end group -@group -(list 'A (1+ 2) auto-save-default) - @result{} (A 3 t) -@end group -@group -values - @result{} ((A 3 t) 1 @dots{}) -@end group -@end example - -This variable is useful for referring back to values of forms recently -evaluated. It is generally a bad idea to print the value of -@code{values} itself, since this may be very long. Instead, examine -particular elements, like this: - -@example -@group -;; @r{Refer to the most recent evaluation result.} -(nth 0 values) - @result{} (A 3 t) -@end group -@group -;; @r{That put a new element on,} -;; @r{so all elements move back one.} -(nth 1 values) - @result{} (A 3 t) -@end group -@group -;; @r{This gets the element that was next-to-most-recent} -;; @r{before this example.} -(nth 3 values) - @result{} 1 -@end group -@end example -@end defvar diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi deleted file mode 100644 index f558089a205..00000000000 --- a/doc/lispref/files.texi +++ /dev/null @@ -1,3276 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/files -@node Files, Backups and Auto-Saving, Documentation, Top -@comment node-name, next, previous, up -@chapter Files - - This chapter describes the Emacs Lisp functions and variables to -find, create, view, save, and otherwise work with files and file -directories. A few other file-related functions are described in -@ref{Buffers}, and those related to backups and auto-saving are -described in @ref{Backups and Auto-Saving}. - - Many of the file functions take one or more arguments that are file -names. A file name is actually a string. Most of these functions -expand file name arguments by calling @code{expand-file-name}, so that -@file{~} is handled correctly, as are relative file names (including -@samp{../}). @xref{File Name Expansion}. - - In addition, certain @dfn{magic} file names are handled specially. -For example, when a remote file name is specified, Emacs accesses the -file over the network via an appropriate protocol (@pxref{Remote -Files,, Remote Files, emacs, The GNU Emacs Manual}). This handling is -done at a very low level, so you may assume that all the functions -described in this chapter accept magic file names as file name -arguments, except where noted. @xref{Magic File Names}, for details. - - When file I/O functions signal Lisp errors, they usually use the -condition @code{file-error} (@pxref{Handling Errors}). The error -message is in most cases obtained from the operating system, according -to locale @code{system-message-locale}, and decoded using coding system -@code{locale-coding-system} (@pxref{Locales}). - -@menu -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing Files:: Renaming files, changing permissions, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Special handling for certain file names. -* Format Conversion:: Conversion to and from various file formats. -@end menu - -@node Visiting Files -@section Visiting Files -@cindex finding files -@cindex visiting files - - Visiting a file means reading a file into a buffer. Once this is -done, we say that the buffer is @dfn{visiting} that file, and call the -file ``the visited file'' of the buffer. - - A file and a buffer are two different things. A file is information -recorded permanently in the computer (unless you delete it). A buffer, -on the other hand, is information inside of Emacs that will vanish at -the end of the editing session (or when you kill the buffer). Usually, -a buffer contains information that you have copied from a file; then we -say the buffer is visiting that file. The copy in the buffer is what -you modify with editing commands. Such changes to the buffer do not -change the file; therefore, to make the changes permanent, you must -@dfn{save} the buffer, which means copying the altered buffer contents -back into the file. - - In spite of the distinction between files and buffers, people often -refer to a file when they mean a buffer and vice-versa. Indeed, we say, -``I am editing a file'', rather than, ``I am editing a buffer that I -will soon save as a file of the same name''. Humans do not usually need -to make the distinction explicit. When dealing with a computer program, -however, it is good to keep the distinction in mind. - -@menu -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. -@end menu - -@node Visiting Functions -@subsection Functions for Visiting Files - - This section describes the functions normally used to visit files. -For historical reasons, these functions have names starting with -@samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for -functions and variables that access the visited file name of a buffer or -that find an existing buffer by its visited file name. - - In a Lisp program, if you want to look at the contents of a file but -not alter it, the fastest way is to use @code{insert-file-contents} in a -temporary buffer. Visiting the file is not necessary and takes longer. -@xref{Reading from Files}. - -@deffn Command find-file filename &optional wildcards -This command selects a buffer visiting the file @var{filename}, -using an existing buffer if there is one, and otherwise creating a -new buffer and reading the file into it. It also returns that buffer. - -Aside from some technical details, the body of the @code{find-file} -function is basically equivalent to: - -@smallexample -(switch-to-buffer (find-file-noselect filename nil nil wildcards)) -@end smallexample - -@noindent -(See @code{switch-to-buffer} in @ref{Switching Buffers}.) - -If @var{wildcards} is non-@code{nil}, which is always true in an -interactive call, then @code{find-file} expands wildcard characters in -@var{filename} and visits all the matching files. - -When @code{find-file} is called interactively, it prompts for -@var{filename} in the minibuffer. -@end deffn - -@deffn Command find-file-literally filename -This command visits @var{filename}, like @code{find-file} does, but it -does not perform any format conversions (@pxref{Format Conversion}), -character code conversions (@pxref{Coding Systems}), or end-of-line -conversions (@pxref{Coding System Basics, End of line conversion}). -The buffer visiting the file is made unibyte, and its major mode is -Fundamental mode, regardless of the file name. File local variable -specifications in the file (@pxref{File Local Variables}) are -ignored, and automatic decompression and adding a newline at the end -of the file due to @code{require-final-newline} (@pxref{Saving -Buffers, require-final-newline}) are also disabled. - -Note that if Emacs already has a buffer visiting the same file -non-literally, it will not visit the same file literally, but instead -just switch to the existing buffer. If you want to be sure of -accessing a file's contents literally, you should create a temporary -buffer and then read the file contents into it using -@code{insert-file-contents-literally} (@pxref{Reading from Files}). -@end deffn - -@defun find-file-noselect filename &optional nowarn rawfile wildcards -This function is the guts of all the file-visiting functions. It -returns a buffer visiting the file @var{filename}. You may make the -buffer current or display it in a window if you wish, but this -function does not do so. - -The function returns an existing buffer if there is one; otherwise it -creates a new buffer and reads the file into it. When -@code{find-file-noselect} uses an existing buffer, it first verifies -that the file has not changed since it was last visited or saved in -that buffer. If the file has changed, this function asks the user -whether to reread the changed file. If the user says @samp{yes}, any -edits previously made in the buffer are lost. - -Reading the file involves decoding the file's contents (@pxref{Coding -Systems}), including end-of-line conversion, and format conversion -(@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil}, -then @code{find-file-noselect} expands wildcard characters in -@var{filename} and visits all the matching files. - -This function displays warning or advisory messages in various peculiar -cases, unless the optional argument @var{nowarn} is non-@code{nil}. For -example, if it needs to create a buffer, and there is no file named -@var{filename}, it displays the message @samp{(New file)} in the echo -area, and leaves the buffer empty. - -The @code{find-file-noselect} function normally calls -@code{after-find-file} after reading the file (@pxref{Subroutines of -Visiting}). That function sets the buffer major mode, parses local -variables, warns the user if there exists an auto-save file more recent -than the file just visited, and finishes by running the functions in -@code{find-file-hook}. - -If the optional argument @var{rawfile} is non-@code{nil}, then -@code{after-find-file} is not called, and the -@code{find-file-not-found-functions} are not run in case of failure. -What's more, a non-@code{nil} @var{rawfile} value suppresses coding -system conversion and format conversion. - -The @code{find-file-noselect} function usually returns the buffer that -is visiting the file @var{filename}. But, if wildcards are actually -used and expanded, it returns a list of buffers that are visiting the -various files. - -@example -@group -(find-file-noselect "/etc/fstab") - @result{} # -@end group -@end example -@end defun - -@deffn Command find-file-other-window filename &optional wildcards -This command selects a buffer visiting the file @var{filename}, but -does so in a window other than the selected window. It may use -another existing window or split a window; see @ref{Switching -Buffers}. - -When this command is called interactively, it prompts for -@var{filename}. -@end deffn - -@deffn Command find-file-read-only filename &optional wildcards -This command selects a buffer visiting the file @var{filename}, like -@code{find-file}, but it marks the buffer as read-only. @xref{Read Only -Buffers}, for related functions and variables. - -When this command is called interactively, it prompts for -@var{filename}. -@end deffn - -@defopt find-file-wildcards -If this variable is non-@code{nil}, then the various @code{find-file} -commands check for wildcard characters and visit all the files that -match them (when invoked interactively or when their @var{wildcards} -argument is non-@code{nil}). If this option is @code{nil}, then -the @code{find-file} commands ignore their @var{wildcards} argument -and never treat wildcard characters specially. -@end defopt - -@defopt find-file-hook -The value of this variable is a list of functions to be called after a -file is visited. The file's local-variables specification (if any) will -have been processed before the hooks are run. The buffer visiting the -file is current when the hook functions are run. - -This variable is a normal hook. @xref{Hooks}. -@end defopt - -@defvar find-file-not-found-functions -The value of this variable is a list of functions to be called when -@code{find-file} or @code{find-file-noselect} is passed a nonexistent -file name. @code{find-file-noselect} calls these functions as soon as -it detects a nonexistent file. It calls them in the order of the list, -until one of them returns non-@code{nil}. @code{buffer-file-name} is -already set up. - -This is not a normal hook because the values of the functions are -used, and in many cases only some of the functions are called. -@end defvar - -@defvar find-file-literally -This buffer-local variable, if set to a non-@code{nil} value, makes -@code{save-buffer} behave as if the buffer were visiting its file -literally, i.e. without conversions of any kind. The command -@code{find-file-literally} sets this variable's local value, but other -equivalent functions and commands can do that as well, e.g.@: to avoid -automatic addition of a newline at the end of the file. This variable -is permanent local, so it is unaffected by changes of major modes. -@end defvar - -@node Subroutines of Visiting -@comment node-name, next, previous, up -@subsection Subroutines of Visiting - - The @code{find-file-noselect} function uses two important subroutines -which are sometimes useful in user Lisp code: @code{create-file-buffer} -and @code{after-find-file}. This section explains how to use them. - -@defun create-file-buffer filename -This function creates a suitably named buffer for visiting -@var{filename}, and returns it. It uses @var{filename} (sans directory) -as the name if that name is free; otherwise, it appends a string such as -@samp{<2>} to get an unused name. See also @ref{Creating Buffers}. - -@strong{Please note:} @code{create-file-buffer} does @emph{not} -associate the new buffer with a file and does not select the buffer. -It also does not use the default major mode. - -@example -@group -(create-file-buffer "foo") - @result{} # -@end group -@group -(create-file-buffer "foo") - @result{} #> -@end group -@group -(create-file-buffer "foo") - @result{} #> -@end group -@end example - -This function is used by @code{find-file-noselect}. -It uses @code{generate-new-buffer} (@pxref{Creating Buffers}). -@end defun - -@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes -This function sets the buffer major mode, and parses local variables -(@pxref{Auto Major Mode}). It is called by @code{find-file-noselect} -and by the default revert function (@pxref{Reverting}). - -@cindex new file message -@cindex file open error -If reading the file got an error because the file does not exist, but -its directory does exist, the caller should pass a non-@code{nil} value -for @var{error}. In that case, @code{after-find-file} issues a warning: -@samp{(New file)}. For more serious errors, the caller should usually not -call @code{after-find-file}. - -If @var{warn} is non-@code{nil}, then this function issues a warning -if an auto-save file exists and is more recent than the visited file. - -If @var{noauto} is non-@code{nil}, that says not to enable or disable -Auto-Save mode. The mode remains enabled if it was enabled before. - -If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that -means this call was from @code{revert-buffer}. This has no direct -effect, but some mode functions and hook functions check the value -of this variable. - -If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's -major mode, don't process local variables specifications in the file, -and don't run @code{find-file-hook}. This feature is used by -@code{revert-buffer} in some cases. - -The last thing @code{after-find-file} does is call all the functions -in the list @code{find-file-hook}. -@end defun - -@node Saving Buffers -@section Saving Buffers -@cindex saving buffers - - When you edit a file in Emacs, you are actually working on a buffer -that is visiting that file---that is, the contents of the file are -copied into the buffer and the copy is what you edit. Changes to the -buffer do not change the file until you @dfn{save} the buffer, which -means copying the contents of the buffer into the file. - -@deffn Command save-buffer &optional backup-option -This function saves the contents of the current buffer in its visited -file if the buffer has been modified since it was last visited or saved. -Otherwise it does nothing. - -@code{save-buffer} is responsible for making backup files. Normally, -@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup -file only if this is the first save since visiting the file. Other -values for @var{backup-option} request the making of backup files in -other circumstances: - -@itemize @bullet -@item -With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the -@code{save-buffer} function marks this version of the file to be -backed up when the buffer is next saved. - -@item -With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the -@code{save-buffer} function unconditionally backs up the previous -version of the file before saving it. - -@item -With an argument of 0, unconditionally do @emph{not} make any backup file. -@end itemize -@end deffn - -@deffn Command save-some-buffers &optional save-silently-p pred -@anchor{Definition of save-some-buffers} -This command saves some modified file-visiting buffers. Normally it -asks the user about each buffer. But if @var{save-silently-p} is -non-@code{nil}, it saves all the file-visiting buffers without querying -the user. - -The optional @var{pred} argument controls which buffers to ask about -(or to save silently if @var{save-silently-p} is non-@code{nil}). -If it is @code{nil}, that means to ask only about file-visiting buffers. -If it is @code{t}, that means also offer to save certain other non-file -buffers---those that have a non-@code{nil} buffer-local value of -@code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says -@samp{yes} to saving a non-file buffer is asked to specify the file -name to use. The @code{save-buffers-kill-emacs} function passes the -value @code{t} for @var{pred}. - -If @var{pred} is neither @code{t} nor @code{nil}, then it should be -a function of no arguments. It will be called in each buffer to decide -whether to offer to save that buffer. If it returns a non-@code{nil} -value in a certain buffer, that means do offer to save that buffer. -@end deffn - -@deffn Command write-file filename &optional confirm -@anchor{Definition of write-file} -This function writes the current buffer into file @var{filename}, makes -the buffer visit that file, and marks it not modified. Then it renames -the buffer based on @var{filename}, appending a string like @samp{<2>} -if necessary to make a unique buffer name. It does most of this work by -calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and -@code{save-buffer}. - -If @var{confirm} is non-@code{nil}, that means to ask for confirmation -before overwriting an existing file. Interactively, confirmation is -required, unless the user supplies a prefix argument. - -If @var{filename} is an existing directory, or a symbolic link to one, -@code{write-file} uses the name of the visited file, in directory -@var{filename}. If the buffer is not visiting a file, it uses the -buffer name instead. -@end deffn - - Saving a buffer runs several hooks. It also performs format -conversion (@pxref{Format Conversion}). - -@defvar write-file-functions -The value of this variable is a list of functions to be called before -writing out a buffer to its visited file. If one of them returns -non-@code{nil}, the file is considered already written and the rest of -the functions are not called, nor is the usual code for writing the file -executed. - -If a function in @code{write-file-functions} returns non-@code{nil}, it -is responsible for making a backup file (if that is appropriate). -To do so, execute the following code: - -@example -(or buffer-backed-up (backup-buffer)) -@end example - -You might wish to save the file modes value returned by -@code{backup-buffer} and use that (if non-@code{nil}) to set the mode -bits of the file that you write. This is what @code{save-buffer} -normally does. @xref{Making Backups,, Making Backup Files}. - -The hook functions in @code{write-file-functions} are also responsible -for encoding the data (if desired): they must choose a suitable coding -system and end-of-line conversion (@pxref{Lisp and Coding Systems}), -perform the encoding (@pxref{Explicit Encoding}), and set -@code{last-coding-system-used} to the coding system that was used -(@pxref{Encoding and I/O}). - -If you set this hook locally in a buffer, it is assumed to be -associated with the file or the way the contents of the buffer were -obtained. Thus the variable is marked as a permanent local, so that -changing the major mode does not alter a buffer-local value. On the -other hand, calling @code{set-visited-file-name} will reset it. -If this is not what you want, you might like to use -@code{write-contents-functions} instead. - -Even though this is not a normal hook, you can use @code{add-hook} and -@code{remove-hook} to manipulate the list. @xref{Hooks}. -@end defvar - -@c Emacs 19 feature -@defvar write-contents-functions -This works just like @code{write-file-functions}, but it is intended -for hooks that pertain to the buffer's contents, not to the particular -visited file or its location. Such hooks are usually set up by major -modes, as buffer-local bindings for this variable. This variable -automatically becomes buffer-local whenever it is set; switching to a -new major mode always resets this variable, but calling -@code{set-visited-file-name} does not. - -If any of the functions in this hook returns non-@code{nil}, the file -is considered already written and the rest are not called and neither -are the functions in @code{write-file-functions}. -@end defvar - -@defopt before-save-hook -This normal hook runs before a buffer is saved in its visited file, -regardless of whether that is done normally or by one of the hooks -described above. For instance, the @file{copyright.el} program uses -this hook to make sure the file you are saving has the current year in -its copyright notice. -@end defopt - -@c Emacs 19 feature -@defopt after-save-hook -This normal hook runs after a buffer has been saved in its visited file. -One use of this hook is in Fast Lock mode; it uses this hook to save the -highlighting information in a cache file. -@end defopt - -@defopt file-precious-flag -If this variable is non-@code{nil}, then @code{save-buffer} protects -against I/O errors while saving by writing the new file to a temporary -name instead of the name it is supposed to have, and then renaming it to -the intended name after it is clear there are no errors. This procedure -prevents problems such as a lack of disk space from resulting in an -invalid file. - -As a side effect, backups are necessarily made by copying. @xref{Rename -or Copy}. Yet, at the same time, saving a precious file always breaks -all hard links between the file you save and other file names. - -Some modes give this variable a non-@code{nil} buffer-local value -in particular buffers. -@end defopt - -@defopt require-final-newline -This variable determines whether files may be written out that do -@emph{not} end with a newline. If the value of the variable is -@code{t}, then @code{save-buffer} silently adds a newline at the end -of the buffer whenever it does not already end in one. If the value -is @code{visit}, Emacs adds a missing newline just after it visits the -file. If the value is @code{visit-save}, Emacs adds a missing newline -both on visiting and on saving. For any other non-@code{nil} value, -@code{save-buffer} asks the user whether to add a newline each time -the case arises. - -If the value of the variable is @code{nil}, then @code{save-buffer} -doesn't add newlines at all. @code{nil} is the default value, but a few -major modes set it to @code{t} in particular buffers. -@end defopt - - See also the function @code{set-visited-file-name} (@pxref{Buffer File -Name}). - -@node Reading from Files -@comment node-name, next, previous, up -@section Reading from Files -@cindex reading from files - - You can copy a file from the disk and insert it into a buffer -using the @code{insert-file-contents} function. Don't use the user-level -command @code{insert-file} in a Lisp program, as that sets the mark. - -@defun insert-file-contents filename &optional visit beg end replace -This function inserts the contents of file @var{filename} into the -current buffer after point. It returns a list of the absolute file name -and the length of the data inserted. An error is signaled if -@var{filename} is not the name of a file that can be read. - -This function checks the file contents against the defined file -formats, and converts the file contents if appropriate and also calls -the functions in the list @code{after-insert-file-functions}. -@xref{Format Conversion}. Normally, one of the functions in the -@code{after-insert-file-functions} list determines the coding system -(@pxref{Coding Systems}) used for decoding the file's contents, -including end-of-line conversion. However, if the file contains null -bytes, it is by default visited without any code conversions. -@xref{Lisp and Coding Systems, inhibit-null-byte-detection}. - -If @var{visit} is non-@code{nil}, this function additionally marks the -buffer as unmodified and sets up various fields in the buffer so that it -is visiting the file @var{filename}: these include the buffer's visited -file name and its last save file modtime. This feature is used by -@code{find-file-noselect} and you probably should not use it yourself. - -If @var{beg} and @var{end} are non-@code{nil}, they should be integers -specifying the portion of the file to insert. In this case, @var{visit} -must be @code{nil}. For example, - -@example -(insert-file-contents filename nil 0 500) -@end example - -@noindent -inserts the first 500 characters of a file. - -If the argument @var{replace} is non-@code{nil}, it means to replace the -contents of the buffer (actually, just the accessible portion) with the -contents of the file. This is better than simply deleting the buffer -contents and inserting the whole file, because (1) it preserves some -marker positions and (2) it puts less data in the undo list. - -It is possible to read a special file (such as a FIFO or an I/O device) -with @code{insert-file-contents}, as long as @var{replace} and -@var{visit} are @code{nil}. -@end defun - -@defun insert-file-contents-literally filename &optional visit beg end replace -This function works like @code{insert-file-contents} except that it -does not run @code{find-file-hook}, and does not do format decoding, -character code conversion, automatic uncompression, and so on. -@end defun - -If you want to pass a file name to another process so that another -program can read the file, use the function @code{file-local-copy}; see -@ref{Magic File Names}. - -@node Writing to Files -@comment node-name, next, previous, up -@section Writing to Files -@cindex writing to files - - You can write the contents of a buffer, or part of a buffer, directly -to a file on disk using the @code{append-to-file} and -@code{write-region} functions. Don't use these functions to write to -files that are being visited; that could cause confusion in the -mechanisms for visiting. - -@deffn Command append-to-file start end filename -This function appends the contents of the region delimited by -@var{start} and @var{end} in the current buffer to the end of file -@var{filename}. If that file does not exist, it is created. This -function returns @code{nil}. - -An error is signaled if @var{filename} specifies a nonwritable file, -or a nonexistent file in a directory where files cannot be created. - -When called from Lisp, this function is completely equivalent to: - -@example -(write-region start end filename t) -@end example -@end deffn - -@deffn Command write-region start end filename &optional append visit lockname mustbenew -This function writes the region delimited by @var{start} and @var{end} -in the current buffer into the file specified by @var{filename}. - -If @var{start} is @code{nil}, then the command writes the entire buffer -contents (@emph{not} just the accessible portion) to the file and -ignores @var{end}. - -@c Emacs 19 feature -If @var{start} is a string, then @code{write-region} writes or appends -that string, rather than text from the buffer. @var{end} is ignored in -this case. - -If @var{append} is non-@code{nil}, then the specified text is appended -to the existing file contents (if any). If @var{append} is an -integer, @code{write-region} seeks to that byte offset from the start -of the file and writes the data from there. - -If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks -for confirmation if @var{filename} names an existing file. If -@var{mustbenew} is the symbol @code{excl}, then @code{write-region} -does not ask for confirmation, but instead it signals an error -@code{file-already-exists} if the file already exists. - -The test for an existing file, when @var{mustbenew} is @code{excl}, uses -a special system feature. At least for files on a local disk, there is -no chance that some other program could create a file of the same name -before Emacs does, without Emacs's noticing. - -If @var{visit} is @code{t}, then Emacs establishes an association -between the buffer and the file: the buffer is then visiting that file. -It also sets the last file modification time for the current buffer to -@var{filename}'s modtime, and marks the buffer as not modified. This -feature is used by @code{save-buffer}, but you probably should not use -it yourself. - -@c Emacs 19 feature -If @var{visit} is a string, it specifies the file name to visit. This -way, you can write the data to one file (@var{filename}) while recording -the buffer as visiting another file (@var{visit}). The argument -@var{visit} is used in the echo area message and also for file locking; -@var{visit} is stored in @code{buffer-file-name}. This feature is used -to implement @code{file-precious-flag}; don't use it yourself unless you -really know what you're doing. - -The optional argument @var{lockname}, if non-@code{nil}, specifies the -file name to use for purposes of locking and unlocking, overriding -@var{filename} and @var{visit} for that purpose. - -The function @code{write-region} converts the data which it writes to -the appropriate file formats specified by @code{buffer-file-format} -and also calls the functions in the list -@code{write-region-annotate-functions}. -@xref{Format Conversion}. - -Normally, @code{write-region} displays the message @samp{Wrote -@var{filename}} in the echo area. If @var{visit} is neither @code{t} -nor @code{nil} nor a string, then this message is inhibited. This -feature is useful for programs that use files for internal purposes, -files that the user does not need to know about. -@end deffn - -@defmac with-temp-file file body@dots{} -@anchor{Definition of with-temp-file} -The @code{with-temp-file} macro evaluates the @var{body} forms with a -temporary buffer as the current buffer; then, at the end, it writes the -buffer contents into file @var{file}. It kills the temporary buffer -when finished, restoring the buffer that was current before the -@code{with-temp-file} form. Then it returns the value of the last form -in @var{body}. - -The current buffer is restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). - -See also @code{with-temp-buffer} in @ref{Definition of -with-temp-buffer,, The Current Buffer}. -@end defmac - -@node File Locks -@section File Locks -@cindex file locks -@cindex lock file - - When two users edit the same file at the same time, they are likely -to interfere with each other. Emacs tries to prevent this situation -from arising by recording a @dfn{file lock} when a file is being -modified. (File locks are not implemented on Microsoft systems.) -Emacs can then detect the first attempt to modify a buffer visiting a -file that is locked by another Emacs job, and ask the user what to do. -The file lock is really a file, a symbolic link with a special name, -stored in the same directory as the file you are editing. - - When you access files using NFS, there may be a small probability that -you and another user will both lock the same file ``simultaneously''. -If this happens, it is possible for the two users to make changes -simultaneously, but Emacs will still warn the user who saves second. -Also, the detection of modification of a buffer visiting a file changed -on disk catches some cases of simultaneous editing; see -@ref{Modification Time}. - -@defun file-locked-p filename -This function returns @code{nil} if the file @var{filename} is not -locked. It returns @code{t} if it is locked by this Emacs process, and -it returns the name of the user who has locked it if it is locked by -some other job. - -@example -@group -(file-locked-p "foo") - @result{} nil -@end group -@end example -@end defun - -@defun lock-buffer &optional filename -This function locks the file @var{filename}, if the current buffer is -modified. The argument @var{filename} defaults to the current buffer's -visited file. Nothing is done if the current buffer is not visiting a -file, or is not modified, or if the system does not support locking. -@end defun - -@defun unlock-buffer -This function unlocks the file being visited in the current buffer, -if the buffer is modified. If the buffer is not modified, then -the file should not be locked, so this function does nothing. It also -does nothing if the current buffer is not visiting a file, or if the -system does not support locking. -@end defun - - File locking is not supported on some systems. On systems that do not -support it, the functions @code{lock-buffer}, @code{unlock-buffer} and -@code{file-locked-p} do nothing and return @code{nil}. - -@defun ask-user-about-lock file other-user -This function is called when the user tries to modify @var{file}, but it -is locked by another user named @var{other-user}. The default -definition of this function asks the user to say what to do. The value -this function returns determines what Emacs does next: - -@itemize @bullet -@item -A value of @code{t} says to grab the lock on the file. Then -this user may edit the file and @var{other-user} loses the lock. - -@item -A value of @code{nil} says to ignore the lock and let this -user edit the file anyway. - -@item -@kindex file-locked -This function may instead signal a @code{file-locked} error, in which -case the change that the user was about to make does not take place. - -The error message for this error looks like this: - -@example -@error{} File is locked: @var{file} @var{other-user} -@end example - -@noindent -where @code{file} is the name of the file and @var{other-user} is the -name of the user who has locked the file. -@end itemize - -If you wish, you can replace the @code{ask-user-about-lock} function -with your own version that makes the decision in another way. The code -for its usual definition is in @file{userlock.el}. -@end defun - -@node Information about Files -@section Information about Files -@cindex file, information about - - The functions described in this section all operate on strings that -designate file names. With a few exceptions, all the functions have -names that begin with the word @samp{file}. These functions all -return information about actual files or directories, so their -arguments must all exist as actual files or directories unless -otherwise noted. - -@menu -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A symbolic link? -* Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: How large is it? Any other names? Etc. -* Locating Files:: How to find a file in standard places. -@end menu - -@node Testing Accessibility -@comment node-name, next, previous, up -@subsection Testing Accessibility -@cindex accessibility of a file -@cindex file accessibility - - These functions test for permission to access a file in specific -ways. Unless explicitly stated otherwise, they recursively follow -symbolic links for their file name arguments, at all levels (at the -level of the file itself and at all levels of parent directories). - -@defun file-exists-p filename -This function returns @code{t} if a file named @var{filename} appears -to exist. This does not mean you can necessarily read the file, only -that you can find out its attributes. (On Unix and GNU/Linux, this is -true if the file exists and you have execute permission on the -containing directories, regardless of the permissions of the file -itself.) - -If the file does not exist, or if fascist access control policies -prevent you from finding the attributes of the file, this function -returns @code{nil}. - -Directories are files, so @code{file-exists-p} returns @code{t} when -given a directory name. However, symbolic links are treated -specially; @code{file-exists-p} returns @code{t} for a symbolic link -name only if the target file exists. -@end defun - -@defun file-readable-p filename -This function returns @code{t} if a file named @var{filename} exists -and you can read it. It returns @code{nil} otherwise. - -@example -@group -(file-readable-p "files.texi") - @result{} t -@end group -@group -(file-exists-p "/usr/spool/mqueue") - @result{} t -@end group -@group -(file-readable-p "/usr/spool/mqueue") - @result{} nil -@end group -@end example -@end defun - -@c Emacs 19 feature -@defun file-executable-p filename -This function returns @code{t} if a file named @var{filename} exists and -you can execute it. It returns @code{nil} otherwise. On Unix and -GNU/Linux, if the file is a directory, execute permission means you can -check the existence and attributes of files inside the directory, and -open those files if their modes permit. -@end defun - -@defun file-writable-p filename -This function returns @code{t} if the file @var{filename} can be written -or created by you, and @code{nil} otherwise. A file is writable if the -file exists and you can write it. It is creatable if it does not exist, -but the specified directory does exist and you can write in that -directory. - -In the third example below, @file{foo} is not writable because the -parent directory does not exist, even though the user could create such -a directory. - -@example -@group -(file-writable-p "~/foo") - @result{} t -@end group -@group -(file-writable-p "/foo") - @result{} nil -@end group -@group -(file-writable-p "~/no-such-dir/foo") - @result{} nil -@end group -@end example -@end defun - -@c Emacs 19 feature -@defun file-accessible-directory-p dirname -This function returns @code{t} if you have permission to open existing -files in the directory whose name as a file is @var{dirname}; -otherwise (or if there is no such directory), it returns @code{nil}. -The value of @var{dirname} may be either a directory name (such as -@file{/foo/}) or the file name of a file which is a directory -(such as @file{/foo}, without the final slash). - -Example: after the following, - -@example -(file-accessible-directory-p "/foo") - @result{} nil -@end example - -@noindent -we can deduce that any attempt to read a file in @file{/foo/} will -give an error. -@end defun - -@defun access-file filename string -This function opens file @var{filename} for reading, then closes it and -returns @code{nil}. However, if the open fails, it signals an error -using @var{string} as the error message text. -@end defun - -@defun file-ownership-preserved-p filename -This function returns @code{t} if deleting the file @var{filename} and -then creating it anew would keep the file's owner unchanged. It also -returns @code{t} for nonexistent files. - -If @var{filename} is a symbolic link, then, unlike the other functions -discussed here, @code{file-ownership-preserved-p} does @emph{not} -replace @var{filename} with its target. However, it does recursively -follow symbolic links at all levels of parent directories. -@end defun - -@defun file-newer-than-file-p filename1 filename2 -@cindex file age -@cindex file modification time -This function returns @code{t} if the file @var{filename1} is -newer than file @var{filename2}. If @var{filename1} does not -exist, it returns @code{nil}. If @var{filename1} does exist, but -@var{filename2} does not, it returns @code{t}. - -In the following example, assume that the file @file{aug-19} was written -on the 19th, @file{aug-20} was written on the 20th, and the file -@file{no-file} doesn't exist at all. - -@example -@group -(file-newer-than-file-p "aug-19" "aug-20") - @result{} nil -@end group -@group -(file-newer-than-file-p "aug-20" "aug-19") - @result{} t -@end group -@group -(file-newer-than-file-p "aug-19" "no-file") - @result{} t -@end group -@group -(file-newer-than-file-p "no-file" "aug-19") - @result{} nil -@end group -@end example - -You can use @code{file-attributes} to get a file's last modification -time as a list of two numbers. @xref{File Attributes}. -@end defun - -@node Kinds of Files -@comment node-name, next, previous, up -@subsection Distinguishing Kinds of Files - - This section describes how to distinguish various kinds of files, such -as directories, symbolic links, and ordinary files. - -@defun file-symlink-p filename -@cindex file symbolic links -If the file @var{filename} is a symbolic link, the -@code{file-symlink-p} function returns the (non-recursive) link target -as a string. (Determining the file name that the link points to from -the target is nontrivial.) First, this function recursively follows -symbolic links at all levels of parent directories. - -If the file @var{filename} is not a symbolic link (or there is no such file), -@code{file-symlink-p} returns @code{nil}. - -@example -@group -(file-symlink-p "foo") - @result{} nil -@end group -@group -(file-symlink-p "sym-link") - @result{} "foo" -@end group -@group -(file-symlink-p "sym-link2") - @result{} "sym-link" -@end group -@group -(file-symlink-p "/bin") - @result{} "/pub/bin" -@end group -@end example - -@c !!! file-symlink-p: should show output of ls -l for comparison -@end defun - -The next two functions recursively follow symbolic links at -all levels for @var{filename}. - -@defun file-directory-p filename -This function returns @code{t} if @var{filename} is the name of an -existing directory, @code{nil} otherwise. - -@example -@group -(file-directory-p "~rms") - @result{} t -@end group -@group -(file-directory-p "~rms/lewis/files.texi") - @result{} nil -@end group -@group -(file-directory-p "~rms/lewis/no-such-file") - @result{} nil -@end group -@group -(file-directory-p "$HOME") - @result{} nil -@end group -@group -(file-directory-p - (substitute-in-file-name "$HOME")) - @result{} t -@end group -@end example -@end defun - -@defun file-regular-p filename -This function returns @code{t} if the file @var{filename} exists and is -a regular file (not a directory, named pipe, terminal, or -other I/O device). -@end defun - -@defun file-equal-p file1 file2 -This function returns @code{t} if the files @var{file1} and -@var{file2} name the same file. If @var{file1} or @var{file2} does -not exist, the return value is unspecified. -@end defun - -@defun file-in-directory-p file dir -This function returns @code{t} if @var{file} is a file in directory -@var{dir}, or in a subdirectory of @var{dir}. It also returns -@code{t} if @var{file} and @var{dir} are the same directory. It -compares the @code{file-truename} values of the two directories -(@pxref{Truenames}). If @var{dir} does not name an existing -directory, the return value is @code{nil}. -@end defun - -@node Truenames -@subsection Truenames -@cindex truename (of file) - - The @dfn{truename} of a file is the name that you get by following -symbolic links at all levels until none remain, then simplifying away -@samp{.}@: and @samp{..}@: appearing as name components. This results -in a sort of canonical name for the file. A file does not always have a -unique truename; the number of distinct truenames a file has is equal to -the number of hard links to the file. However, truenames are useful -because they eliminate symbolic links as a cause of name variation. - -@defun file-truename filename -This function returns the truename of the file @var{filename}. If the -argument is not an absolute file name, this function first expands it -against @code{default-directory}. - -This function does not expand environment variables. Only -@code{substitute-in-file-name} does that. @xref{Definition of -substitute-in-file-name}. - -If you may need to follow symbolic links preceding @samp{..}@: -appearing as a name component, you should make sure to call -@code{file-truename} without prior direct or indirect calls to -@code{expand-file-name}, as otherwise the file name component -immediately preceding @samp{..} will be ``simplified away'' before -@code{file-truename} is called. To eliminate the need for a call to -@code{expand-file-name}, @code{file-truename} handles @samp{~} in the -same way that @code{expand-file-name} does. @xref{File Name -Expansion,, Functions that Expand Filenames}. -@end defun - -@defun file-chase-links filename &optional limit -This function follows symbolic links, starting with @var{filename}, -until it finds a file name which is not the name of a symbolic link. -Then it returns that file name. This function does @emph{not} follow -symbolic links at the level of parent directories. - -If you specify a number for @var{limit}, then after chasing through -that many links, the function just returns what it has even if that is -still a symbolic link. -@end defun - - To illustrate the difference between @code{file-chase-links} and -@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to -the directory @file{/home/foo}, and @file{/home/foo/hello} is an -ordinary file (or at least, not a symbolic link) or nonexistent. Then -we would have: - -@example -(file-chase-links "/usr/foo/hello") - ;; @r{This does not follow the links in the parent directories.} - @result{} "/usr/foo/hello" -(file-truename "/usr/foo/hello") - ;; @r{Assuming that @file{/home} is not a symbolic link.} - @result{} "/home/foo/hello" -@end example - - @xref{Buffer File Name}, for related information. - -@node File Attributes -@comment node-name, next, previous, up -@subsection Other Information about Files - - This section describes the functions for getting detailed -information about a file, other than its contents. This information -includes the mode bits that control access permissions, the owner and -group numbers, the number of names, the inode number, the size, and -the times of access and modification. - -@defun file-modes filename -@cindex file permissions -@cindex permissions, file -@cindex file attributes -@cindex file modes -This function returns the @dfn{mode bits} describing the @dfn{file -permissions} of @var{filename}, as an integer. It recursively follows -symbolic links in @var{filename} at all levels. If @var{filename} -does not exist, the return value is @code{nil}. - -@xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils} -Manual}, for a description of mode bits. If the low-order bit is 1, -then the file is executable by all users, if the second-lowest-order -bit is 1, then the file is writable by all users, etc. The highest -value returnable is 4095 (7777 octal), meaning that everyone has read, -write, and execute permission, that the @acronym{SUID} bit is set for -both others and group, and that the sticky bit is set. - -@example -@group -(file-modes "~/junk/diffs") - @result{} 492 ; @r{Decimal integer.} -@end group -@group -(format "%o" 492) - @result{} "754" ; @r{Convert to octal.} -@end group - -@group -(set-file-modes "~/junk/diffs" #o666) - @result{} nil -@end group - -@group -% ls -l diffs - -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs -@end group -@end example - -@xref{Changing Files}, for functions that change file permissions, -such as @code{set-file-modes}. - -@cindex MS-DOS and file modes -@cindex file modes and MS-DOS -@strong{MS-DOS note:} On MS-DOS, there is no such thing as an -``executable'' file mode bit. So @code{file-modes} considers a file -executable if its name ends in one of the standard executable -extensions, such as @file{.com}, @file{.bat}, @file{.exe}, and some -others. Files that begin with the Unix-standard @samp{#!} signature, -such as shell and Perl scripts, are also considered executable. -Directories are also reported as executable, for compatibility with -Unix. These conventions are also followed by @code{file-attributes}, -below. -@end defun - - If the @var{filename} argument to the next two functions is a -symbolic link, then these function do @emph{not} replace it with its -target. However, they both recursively follow symbolic links at all -levels of parent directories. - -@defun file-nlinks filename -This functions returns the number of names (i.e., hard links) that -file @var{filename} has. If the file does not exist, then this function -returns @code{nil}. Note that symbolic links have no effect on this -function, because they are not considered to be names of the files they -link to. - -@example -@group -% ls -l foo* --rw-rw-rw- 2 rms 4 Aug 19 01:27 foo --rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1 -@end group - -@group -(file-nlinks "foo") - @result{} 2 -@end group -@group -(file-nlinks "doesnt-exist") - @result{} nil -@end group -@end example -@end defun - -@defun file-attributes filename &optional id-format -@anchor{Definition of file-attributes} -This function returns a list of attributes of file @var{filename}. If -the specified file cannot be opened, it returns @code{nil}. -The optional parameter @var{id-format} specifies the preferred format -of attributes @acronym{UID} and @acronym{GID} (see below)---the -valid values are @code{'string} and @code{'integer}. The latter is -the default, but we plan to change that, so you should specify a -non-@code{nil} value for @var{id-format} if you use the returned -@acronym{UID} or @acronym{GID}. - -The elements of the list, in order, are: - -@enumerate 0 -@item -@code{t} for a directory, a string for a symbolic link (the name -linked to), or @code{nil} for a text file. - -@c Wordy so as to prevent an overfull hbox. --rjc 15mar92 -@item -The number of names the file has. Alternate names, also known as hard -links, can be created by using the @code{add-name-to-file} function -(@pxref{Changing Files}). - -@item -The file's @acronym{UID}, normally as a string. However, if it does -not correspond to a named user, the value is an integer or a floating -point number. - -@item -The file's @acronym{GID}, likewise. - -@item -The time of last access, as a list of two integers. -The first integer has the high-order 16 bits of time, -the second has the low 16 bits. (This is similar to the -value of @code{current-time}; see @ref{Time of Day}.) Note that on -some FAT-based filesystems, only the date of last access is recorded, -so this time will always hold the midnight of the day of last access. - -@cindex modification time of file -@item -The time of last modification as a list of two integers (as above). -This is the last time when the file's contents were modified. - -@item -The time of last status change as a list of two integers (as above). -This is the time of the last change to the file's access mode bits, -its owner and group, and other information recorded in the filesystem -for the file, beyond the file's contents. - -@item -The size of the file in bytes. If the size is too large to fit in a -Lisp integer, this is a floating point number. - -@item -The file's modes, as a string of ten letters or dashes, -as in @samp{ls -l}. - -@item -@code{t} if the file's @acronym{GID} would change if file were -deleted and recreated; @code{nil} otherwise. - -@item -The file's inode number. If possible, this is an integer. If the -inode number is too large to be represented as an integer in Emacs -Lisp but dividing it by @math{2^16} yields a representable integer, -then the value has the -form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16 -bits. If the inode number is too wide for even that, the value is of the form -@code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds -the high bits, @var{middle} the middle 24 bits, and @var{low} the low -16 bits. - -@item -The filesystem number of the device that the file is on. Depending on -the magnitude of the value, this can be either an integer or a cons -cell, in the same manner as the inode number. This element and the -file's inode number together give enough information to distinguish -any two files on the system---no two files can have the same values -for both of these numbers. -@end enumerate - -For example, here are the file attributes for @file{files.texi}: - -@example -@group -(file-attributes "files.texi" 'string) - @result{} (nil 1 "lh" "users" - (19145 42977) - (19141 59576) - (18340 17300) - 122295 "-rw-rw-rw-" - nil (5888 2 . 43978) - (15479 . 46724)) -@end group -@end example - -@noindent -and here is how the result is interpreted: - -@table @code -@item nil -is neither a directory nor a symbolic link. - -@item 1 -has only one name (the name @file{files.texi} in the current default -directory). - -@item "lh" -is owned by the user with name "lh". - -@item "users" -is in the group with name "users". - -@item (19145 42977) -was last accessed on Oct 5 2009, at 10:01:37. - -@item (19141 59576) -last had its contents modified on Oct 2 2009, at 13:49:12. - -@item (18340 17300) -last had its status changed on Feb 2 2008, at 12:19:00. - -@item 122295 -is 122295 bytes long. (It may not contain 122295 characters, though, -if some of the bytes belong to multibyte sequences, and also if the -end-of-line format is CR-LF.) - -@item "-rw-rw-rw-" -has a mode of read and write access for the owner, group, and world. - -@item nil -would retain the same @acronym{GID} if it were recreated. - -@item (5888 2 . 43978) -has an inode number of 6473924464520138. - -@item (15479 . 46724) -is on the file-system device whose number is 1014478468. -@end table -@end defun - -@cindex SELinux context - SELinux is a Linux kernel feature which provides more sophisticated -file access controls than ordinary ``Unix-style'' file permissions. -If Emacs has been compiled with SELinux support on a system with -SELinux enabled, you can use the function @code{file-selinux-context} -to retrieve a file's SELinux security context. For the function -@code{set-file-selinux-context}, see @ref{Changing Files}. - -@defun file-selinux-context filename -This function returns the SELinux security context of the file -@var{filename}. This return value is a list of the form -@code{(@var{user} @var{role} @var{type} @var{range})}, whose elements -are the context's user, role, type, and range respectively, as Lisp -strings. See the SELinux documentation for details about what these -actually mean. - -If the file does not exist or is inaccessible, or if the system does -not support SELinux, or if Emacs was not compiled with SELinux -support, then the return value is @code{(nil nil nil nil)}. -@end defun - -@node Locating Files -@subsection How to Locate Files in Standard Places -@cindex locate file in path -@cindex find file in path - - This section explains how to search for a file in a list of -directories (a @dfn{path}), or for an executable file in the standard -list of executable file directories. - - To search for a user-specific configuration file, @xref{Standard -File Names}, for the @code{locate-user-emacs-file} function. - -@defun locate-file filename path &optional suffixes predicate -This function searches for a file whose name is @var{filename} in a -list of directories given by @var{path}, trying the suffixes in -@var{suffixes}. If it finds such a file, it returns the file's -absolute file name (@pxref{Relative File Names}); otherwise it returns -@code{nil}. - -The optional argument @var{suffixes} gives the list of file-name -suffixes to append to @var{filename} when searching. -@code{locate-file} tries each possible directory with each of these -suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there -are no suffixes, and @var{filename} is used only as-is. Typical -values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess -Creation}), @code{load-suffixes}, @code{load-file-rep-suffixes} and -the return value of the function @code{get-load-suffixes} (@pxref{Load -Suffixes}). - -Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess -Creation}) when looking for executable programs, or @code{load-path} -(@pxref{Library Search}) when looking for Lisp files. If -@var{filename} is absolute, @var{path} has no effect, but the suffixes -in @var{suffixes} are still tried. - -The optional argument @var{predicate}, if non-@code{nil}, specifies a -predicate function for testing whether a candidate file is suitable. -The predicate is passed the candidate file name as its single -argument. If @var{predicate} is @code{nil} or omitted, -@code{locate-file} uses @code{file-readable-p} as the predicate. -@xref{Kinds of Files}, for other useful predicates, e.g.@: -@code{file-executable-p} and @code{file-directory-p}. - -For compatibility, @var{predicate} can also be one of the symbols -@code{executable}, @code{readable}, @code{writable}, @code{exists}, or -a list of one or more of these symbols. -@end defun - -@defun executable-find program -This function searches for the executable file of the named -@var{program} and returns the absolute file name of the executable, -including its file-name extensions, if any. It returns @code{nil} if -the file is not found. The functions searches in all the directories -in @code{exec-path}, and tries all the file-name extensions in -@code{exec-suffixes} (@pxref{Subprocess Creation}). -@end defun - -@node Changing Files -@section Changing File Names and Attributes -@c @cindex renaming files Duplicates rename-file -@cindex copying files -@cindex deleting files -@cindex linking files -@cindex setting modes of files - - The functions in this section rename, copy, delete, link, and set -the modes (permissions) of files. - - In the functions that have an argument @var{newname}, if a file by the -name of @var{newname} already exists, the actions taken depend on the -value of the argument @var{ok-if-already-exists}: - -@itemize @bullet -@item -Signal a @code{file-already-exists} error if -@var{ok-if-already-exists} is @code{nil}. - -@item -Request confirmation if @var{ok-if-already-exists} is a number. - -@item -Replace the old file without confirmation if @var{ok-if-already-exists} -is any other value. -@end itemize - -The next four commands all recursively follow symbolic links at all -levels of parent directories for their first argument, but, if that -argument is itself a symbolic link, then only @code{copy-file} -replaces it with its (recursive) target. - -@deffn Command add-name-to-file oldname newname &optional ok-if-already-exists -@cindex file with multiple names -@cindex file hard link -This function gives the file named @var{oldname} the additional name -@var{newname}. This means that @var{newname} becomes a new ``hard -link'' to @var{oldname}. - -In the first part of the following example, we list two files, -@file{foo} and @file{foo3}. - -@example -@group -% ls -li fo* -81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo -84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 -@end group -@end example - -Now we create a hard link, by calling @code{add-name-to-file}, then list -the files again. This shows two names for one file, @file{foo} and -@file{foo2}. - -@example -@group -(add-name-to-file "foo" "foo2") - @result{} nil -@end group - -@group -% ls -li fo* -81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo -81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 -84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 -@end group -@end example - -Finally, we evaluate the following: - -@example -(add-name-to-file "foo" "foo3" t) -@end example - -@noindent -and list the files again. Now there are three names -for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old -contents of @file{foo3} are lost. - -@example -@group -(add-name-to-file "foo1" "foo3") - @result{} nil -@end group - -@group -% ls -li fo* -81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo -81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 -81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3 -@end group -@end example - -This function is meaningless on operating systems where multiple names -for one file are not allowed. Some systems implement multiple names -by copying the file instead. - -See also @code{file-nlinks} in @ref{File Attributes}. -@end deffn - -@deffn Command rename-file filename newname &optional ok-if-already-exists -This command renames the file @var{filename} as @var{newname}. - -If @var{filename} has additional names aside from @var{filename}, it -continues to have those names. In fact, adding the name @var{newname} -with @code{add-name-to-file} and then deleting @var{filename} has the -same effect as renaming, aside from momentary intermediate states. -@end deffn - -@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid preserve-selinux -This command copies the file @var{oldname} to @var{newname}. An -error is signaled if @var{oldname} does not exist. If @var{newname} -names a directory, it copies @var{oldname} into that directory, -preserving its final name component. - -If @var{time} is non-@code{nil}, then this function gives the new file -the same last-modified time that the old one has. (This works on only -some operating systems.) If setting the time gets an error, -@code{copy-file} signals a @code{file-date-error} error. In an -interactive call, a prefix argument specifies a non-@code{nil} value -for @var{time}. - -This function copies the file modes, too. - -If argument @var{preserve-uid-gid} is @code{nil}, we let the operating -system decide the user and group ownership of the new file (this is -usually set to the user running Emacs). If @var{preserve-uid-gid} is -non-@code{nil}, we attempt to copy the user and group ownership of the -file. This works only on some operating systems, and only if you have -the correct permissions to do so. - -If the optional argument @var{preserve-selinux} is non-@code{nil}, and -Emacs has been compiled with SELinux support, this function attempts -to copy the file's SELinux context (@pxref{File Attributes}). -@end deffn - -@deffn Command make-symbolic-link filename newname &optional ok-if-exists -@pindex ln -@kindex file-already-exists -This command makes a symbolic link to @var{filename}, named -@var{newname}. This is like the shell command @samp{ln -s -@var{filename} @var{newname}}. - -This function is not available on systems that don't support symbolic -links. -@end deffn - -@cindex trash -@vindex delete-by-moving-to-trash -@deffn Command delete-file filename &optional trash -@pindex rm -This command deletes the file @var{filename}. If the file has -multiple names, it continues to exist under the other names. If -@var{filename} is a symbolic link, @code{delete-file} deletes only the -symbolic link and not its target (though it does follow symbolic links -at all levels of parent directories). - -A suitable kind of @code{file-error} error is signaled if the file -does not exist, or is not deletable. (On Unix and GNU/Linux, a file -is deletable if its directory is writable.) - -If the optional argument @var{trash} is non-@code{nil} and the -variable @code{delete-by-moving-to-trash} is non-@code{nil}, this -command moves the file into the system Trash instead of deleting it. -@xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU -Emacs Manual}. When called interactively, @var{trash} is @code{t} if -no prefix argument is given, and @code{nil} otherwise. - -See also @code{delete-directory} in @ref{Create/Delete Dirs}. -@end deffn - -@cindex file permissions, setting -@cindex permissions, file -@cindex file modes, setting -@deffn Command set-file-modes filename mode -This function sets the @dfn{file mode} (or @dfn{file permissions}) of -@var{filename} to @var{mode}. It recursively follows symbolic links -at all levels for @var{filename}. - -If called non-interactively, @var{mode} must be an integer. Only the -lowest 12 bits of the integer are used; on most systems, only the -lowest 9 bits are meaningful. You can use the Lisp construct for -octal numbers to enter @var{mode}. For example, - -@example -(set-file-modes #o644) -@end example - -@noindent -specifies that the file should be readable and writable for its owner, -readable for group members, and readable for all other users. -@xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils} -Manual}, for a description of mode bit specifications. - -Interactively, @var{mode} is read from the minibuffer using -@code{read-file-modes} (see below), which lets the user type in either -an integer or a string representing the permissions symbolically. - -@xref{File Attributes}, for the function @code{file-modes}, which -returns the permissions of a file. -@end deffn - -@defun set-default-file-modes mode -@cindex umask -This function sets the default file permissions for new files created -by Emacs and its subprocesses. Every file created with Emacs -initially has these permissions, or a subset of them -(@code{write-region} will not grant execute permissions even if the -default file permissions allow execution). On Unix and GNU/Linux, the -default permissions are given by the bitwise complement of the -``umask'' value. - -The argument @var{mode} should be an integer which specifies the -permissions, similar to @code{set-file-modes} above. Only the lowest -9 bits are meaningful. - -The default file permissions have no effect when you save a modified -version of an existing file; saving a file preserves its existing -permissions. -@end defun - -@defun default-file-modes -This function returns the default file permissions, as an integer. -@end defun - -@defun read-file-modes &optional prompt base-file -This function reads a set of file mode bits from the minibuffer. The -first optional argument @var{prompt} specifies a non-default prompt. -Second second optional argument @var{base-file} is the name of a file -on whose permissions to base the mode bits that this function returns, -if what the user types specifies mode bits relative to permissions of -an existing file. - -If user input represents an octal number, this function returns that -number. If it is a complete symbolic specification of mode bits, as -in @code{"u=rwx"}, the function converts it to the equivalent numeric -value using @code{file-modes-symbolic-to-number} and returns the -result. If the specification is relative, as in @code{"o+g"}, then -the permissions on which the specification is based are taken from the -mode bits of @var{base-file}. If @var{base-file} is omitted or -@code{nil}, the function uses @code{0} as the base mode bits. The -complete and relative specifications can be combined, as in -@code{"u+r,g+rx,o+r,g-w"}. @xref{File Permissions,,, coreutils, The -@sc{gnu} @code{Coreutils} Manual}, for a description of file mode -specifications. -@end defun - -@defun file-modes-symbolic-to-number modes &optional base-modes -This function converts a symbolic file mode specification in -@var{modes} into the equivalent integer value. If the symbolic -specification is based on an existing file, that file's mode bits are -taken from the optional argument @var{base-modes}; if that argument is -omitted or @code{nil}, it defaults to 0, i.e.@: no access rights at -all. -@end defun - -@defun set-file-times filename &optional time -This function sets the access and modification times of @var{filename} -to @var{time}. The return value is @code{t} if the times are successfully -set, otherwise it is @code{nil}. @var{time} defaults to the current -time and must be in the format returned by @code{current-time} -(@pxref{Time of Day}). -@end defun - -@defun set-file-selinux-context filename context -This function sets the SELinux security context of the file -@var{filename} to @var{context}. @xref{File Attributes}, for a brief -description of SELinux contexts. The @var{context} argument should be -a list @code{(@var{user} @var{role} @var{type} @var{range})}, like the -return value of @code{file-selinux-context}. The function does -nothing if SELinux is disabled, or if Emacs was compiled without -SELinux support. -@end defun - -@node File Names -@section File Names -@cindex file names - - Files are generally referred to by their names, in Emacs as elsewhere. -File names in Emacs are represented as strings. The functions that -operate on a file all expect a file name argument. - - In addition to operating on files themselves, Emacs Lisp programs -often need to operate on file names; i.e., to take them apart and to use -part of a name to construct related file names. This section describes -how to manipulate file names. - - The functions in this section do not actually access files, so they -can operate on file names that do not refer to an existing file or -directory. - - On MS-DOS and MS-Windows, these functions (like the function that -actually operate on files) accept MS-DOS or MS-Windows file-name syntax, -where backslashes separate the components, as well as Unix syntax; but -they always return Unix syntax. This enables Lisp programs to specify -file names in Unix syntax and work properly on all systems without -change. - -@menu -* File Name Components:: The directory part of a file name, and the rest. -* Relative File Names:: Some file names are relative to a current directory. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. -* Standard File Names:: If your package uses a fixed file name, - how to handle various operating systems simply. -@end menu - -@node File Name Components -@subsection File Name Components -@cindex directory part (of file name) -@cindex nondirectory part (of file name) -@cindex version number (in file name) - - The operating system groups files into directories. To specify a -file, you must specify the directory and the file's name within that -directory. Therefore, Emacs considers a file name as having two main -parts: the @dfn{directory name} part, and the @dfn{nondirectory} part -(or @dfn{file name within the directory}). Either part may be empty. -Concatenating these two parts reproduces the original file name. - - On most systems, the directory part is everything up to and including -the last slash (backslash is also allowed in input on MS-DOS or -MS-Windows); the nondirectory part is the rest. - - For some purposes, the nondirectory part is further subdivided into -the name proper and the @dfn{version number}. On most systems, only -backup files have version numbers in their names. - -@defun file-name-directory filename -This function returns the directory part of @var{filename}, as a -directory name (@pxref{Directory Names}), or @code{nil} if -@var{filename} does not include a directory part. - -On GNU and Unix systems, a string returned by this function always -ends in a slash. On MS-DOS it can also end in a colon. - -@example -@group -(file-name-directory "lewis/foo") ; @r{Unix example} - @result{} "lewis/" -@end group -@group -(file-name-directory "foo") ; @r{Unix example} - @result{} nil -@end group -@end example -@end defun - -@defun file-name-nondirectory filename -This function returns the nondirectory part of @var{filename}. - -@example -@group -(file-name-nondirectory "lewis/foo") - @result{} "foo" -@end group -@group -(file-name-nondirectory "foo") - @result{} "foo" -@end group -@group -(file-name-nondirectory "lewis/") - @result{} "" -@end group -@end example -@end defun - -@defun file-name-sans-versions filename &optional keep-backup-version -This function returns @var{filename} with any file version numbers, -backup version numbers, or trailing tildes discarded. - -If @var{keep-backup-version} is non-@code{nil}, then true file version -numbers understood as such by the file system are discarded from the -return value, but backup version numbers are kept. - -@example -@group -(file-name-sans-versions "~rms/foo.~1~") - @result{} "~rms/foo" -@end group -@group -(file-name-sans-versions "~rms/foo~") - @result{} "~rms/foo" -@end group -@group -(file-name-sans-versions "~rms/foo") - @result{} "~rms/foo" -@end group -@end example -@end defun - -@defun file-name-extension filename &optional period -This function returns @var{filename}'s final ``extension'', if any, -after applying @code{file-name-sans-versions} to remove any -version/backup part. The extension, in a file name, is the part that -follows the last @samp{.} in the last name component (minus any -version/backup part). - -This function returns @code{nil} for extensionless file names such as -@file{foo}. It returns @code{""} for null extensions, as in -@file{foo.}. If the last component of a file name begins with a -@samp{.}, that @samp{.} doesn't count as the beginning of an -extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not -@samp{.emacs}. - -If @var{period} is non-@code{nil}, then the returned value includes -the period that delimits the extension, and if @var{filename} has no -extension, the value is @code{""}. -@end defun - -@defun file-name-sans-extension filename -This function returns @var{filename} minus its extension, if any. The -version/backup part, if present, is only removed if the file has an -extension. For example, - -@example -(file-name-sans-extension "foo.lose.c") - @result{} "foo.lose" -(file-name-sans-extension "big.hack/foo") - @result{} "big.hack/foo" -(file-name-sans-extension "/my/home/.emacs") - @result{} "/my/home/.emacs" -(file-name-sans-extension "/my/home/.emacs.el") - @result{} "/my/home/.emacs" -(file-name-sans-extension "~/foo.el.~3~") - @result{} "~/foo" -(file-name-sans-extension "~/foo.~3~") - @result{} "~/foo.~3~" -@end example - -Note that the @samp{.~3~} in the two last examples is the backup part, -not an extension. -@end defun - - -@node Relative File Names -@subsection Absolute and Relative File Names -@cindex absolute file name -@cindex relative file name - - All the directories in the file system form a tree starting at the -root directory. A file name can specify all the directory names -starting from the root of the tree; then it is called an -@dfn{absolute} file name. Or it can specify the position of the file -in the tree relative to a default directory; then it is called a -@dfn{relative} file name. On Unix and GNU/Linux, an absolute file -name starts with a @samp{/} or a @samp{~} -(@pxref{abbreviate-file-name}), and a relative one does not. On -MS-DOS and MS-Windows, an absolute file name starts with a slash or a -backslash, or with a drive specification @samp{@var{x}:/}, where -@var{x} is the @dfn{drive letter}. - -@defun file-name-absolute-p filename -This function returns @code{t} if file @var{filename} is an absolute -file name, @code{nil} otherwise. - -@example -@group -(file-name-absolute-p "~rms/foo") - @result{} t -@end group -@group -(file-name-absolute-p "rms/foo") - @result{} nil -@end group -@group -(file-name-absolute-p "/user/rms/foo") - @result{} t -@end group -@end example -@end defun - - Given a possibly relative file name, you can convert it to an -absolute name using @code{expand-file-name} (@pxref{File Name -Expansion}). This function converts absolute file names to relative -names: - -@defun file-relative-name filename &optional directory -This function tries to return a relative name that is equivalent to -@var{filename}, assuming the result will be interpreted relative to -@var{directory} (an absolute directory name or directory file name). -If @var{directory} is omitted or @code{nil}, it defaults to the -current buffer's default directory. - -On some operating systems, an absolute file name begins with a device -name. On such systems, @var{filename} has no relative equivalent based -on @var{directory} if they start with two different device names. In -this case, @code{file-relative-name} returns @var{filename} in absolute -form. - -@example -(file-relative-name "/foo/bar" "/foo/") - @result{} "bar" -(file-relative-name "/foo/bar" "/hack/") - @result{} "../foo/bar" -@end example -@end defun - -@node Directory Names -@comment node-name, next, previous, up -@subsection Directory Names -@cindex directory name -@cindex file name of directory - - A @dfn{directory name} is the name of a directory. A directory is -actually a kind of file, so it has a file name, which is related to -the directory name but not identical to it. (This is not quite the -same as the usual Unix terminology.) These two different names for -the same entity are related by a syntactic transformation. On GNU and -Unix systems, this is simple: a directory name ends in a slash, -whereas the directory's name as a file lacks that slash. On MS-DOS -the relationship is more complicated. - - The difference between a directory name and its name as a file is -subtle but crucial. When an Emacs variable or function argument is -described as being a directory name, a file name of a directory is not -acceptable. When @code{file-name-directory} returns a string, that is -always a directory name. - - The following two functions convert between directory names and file -names. They do nothing special with environment variable substitutions -such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}. - -@defun file-name-as-directory filename -This function returns a string representing @var{filename} in a form -that the operating system will interpret as the name of a directory. On -most systems, this means appending a slash to the string (if it does not -already end in one). - -@example -@group -(file-name-as-directory "~rms/lewis") - @result{} "~rms/lewis/" -@end group -@end example -@end defun - -@defun directory-file-name dirname -This function returns a string representing @var{dirname} in a form that -the operating system will interpret as the name of a file. On most -systems, this means removing the final slash (or backslash) from the -string. - -@example -@group -(directory-file-name "~lewis/") - @result{} "~lewis" -@end group -@end example -@end defun - - Given a directory name, you can combine it with a relative file name -using @code{concat}: - -@example -(concat @var{dirname} @var{relfile}) -@end example - -@noindent -Be sure to verify that the file name is relative before doing that. -If you use an absolute file name, the results could be syntactically -invalid or refer to the wrong file. - - If you want to use a directory file name in making such a -combination, you must first convert it to a directory name using -@code{file-name-as-directory}: - -@example -(concat (file-name-as-directory @var{dirfile}) @var{relfile}) -@end example - -@noindent -Don't try concatenating a slash by hand, as in - -@example -;;; @r{Wrong!} -(concat @var{dirfile} "/" @var{relfile}) -@end example - -@noindent -because this is not portable. Always use -@code{file-name-as-directory}. - - To convert a directory name to its abbreviation, use this -function: - -@cindex file name abbreviations -@cindex abbreviated file names -@defun abbreviate-file-name filename -@anchor{abbreviate-file-name} -This function returns an abbreviated form of @var{filename}. It -applies the abbreviations specified in @code{directory-abbrev-alist} -(@pxref{File Aliases,,File Aliases, emacs, The GNU Emacs Manual}), -then substitutes @samp{~} for the user's home directory if the -argument names a file in the home directory or one of its -subdirectories. If the home directory is a root directory, it is not -replaced with @samp{~}, because this does not make the result shorter -on many systems. - -You can use this function for directory names and for file names, -because it recognizes abbreviations even as part of the name. -@end defun - -@node File Name Expansion -@subsection Functions that Expand Filenames -@cindex expansion of file names - - @dfn{Expanding} a file name means converting a relative file name to -an absolute one. Since this is done relative to a default directory, -you must specify the default directory name as well as the file name -to be expanded. It also involves expanding abbreviations like -@file{~/} -@ifnottex -(@pxref{abbreviate-file-name}), -@end ifnottex -and eliminating redundancies like @file{./} and @file{@var{name}/../}. - -@defun expand-file-name filename &optional directory -This function converts @var{filename} to an absolute file name. If -@var{directory} is supplied, it is the default directory to start with -if @var{filename} is relative. (The value of @var{directory} should -itself be an absolute directory name or directory file name; it may -start with @samp{~}.) Otherwise, the current buffer's value of -@code{default-directory} is used. For example: - -@example -@group -(expand-file-name "foo") - @result{} "/xcssun/users/rms/lewis/foo" -@end group -@group -(expand-file-name "../foo") - @result{} "/xcssun/users/rms/foo" -@end group -@group -(expand-file-name "foo" "/usr/spool/") - @result{} "/usr/spool/foo" -@end group -@group -(expand-file-name "$HOME/foo") - @result{} "/xcssun/users/rms/lewis/$HOME/foo" -@end group -@end example - -If the part of the combined file name before the first slash is -@samp{~}, it expands to the value of the @env{HOME} environment -variable (usually your home directory). If the part before the first -slash is @samp{~@var{user}} and if @var{user} is a valid login name, -it expands to @var{user}'s home directory. - -Filenames containing @samp{.} or @samp{..} are simplified to their -canonical form: - -@example -@group -(expand-file-name "bar/../foo") - @result{} "/xcssun/users/rms/lewis/foo" -@end group -@end example - -In some cases, a leading @samp{..} component can remain in the output: - -@example -@group -(expand-file-name "../home" "/") - @result{} "/../home" -@end group -@end example - -@noindent -This is for the sake of filesystems that have the concept of a -``superroot'' above the root directory @file{/}. On other filesystems, -@file{/../} is interpreted exactly the same as @file{/}. - -Note that @code{expand-file-name} does @emph{not} expand environment -variables; only @code{substitute-in-file-name} does that. - -Note also that @code{expand-file-name} does not follow symbolic links -at any level. This results in a difference between the way -@code{file-truename} and @code{expand-file-name} treat @samp{..}. -Assuming that @samp{/tmp/bar} is a symbolic link to the directory -@samp{/tmp/foo/bar} we get: - -@example -@group -(file-truename "/tmp/bar/../myfile") - @result{} "/tmp/foo/myfile" -@end group -@group -(expand-file-name "/tmp/bar/../myfile") - @result{} "/tmp/myfile" -@end group -@end example - -If you may need to follow symbolic links preceding @samp{..}, you -should make sure to call @code{file-truename} without prior direct or -indirect calls to @code{expand-file-name}. @xref{Truenames}. -@end defun - -@defvar default-directory -The value of this buffer-local variable is the default directory for the -current buffer. It should be an absolute directory name; it may start -with @samp{~}. This variable is buffer-local in every buffer. - -@code{expand-file-name} uses the default directory when its second -argument is @code{nil}. - -The value is always a string ending with a slash. - -@example -@group -default-directory - @result{} "/user/lewis/manual/" -@end group -@end example -@end defvar - -@defun substitute-in-file-name filename -@anchor{Definition of substitute-in-file-name} -This function replaces environment variable references in -@var{filename} with the environment variable values. Following -standard Unix shell syntax, @samp{$} is the prefix to substitute an -environment variable value. If the input contains @samp{$$}, that is -converted to @samp{$}; this gives the user a way to ``quote'' a -@samp{$}. - -The environment variable name is the series of alphanumeric characters -(including underscores) that follow the @samp{$}. If the character following -the @samp{$} is a @samp{@{}, then the variable name is everything up to the -matching @samp{@}}. - -Calling @code{substitute-in-file-name} on output produced by -@code{substitute-in-file-name} tends to give incorrect results. For -instance, use of @samp{$$} to quote a single @samp{$} won't work -properly, and @samp{$} in an environment variable's value could lead -to repeated substitution. Therefore, programs that call this function -and put the output where it will be passed to this function need to -double all @samp{$} characters to prevent subsequent incorrect -results. - -@c Wordy to avoid overfull hbox. --rjc 15mar92 -Here we assume that the environment variable @env{HOME}, which holds -the user's home directory name, has value @samp{/xcssun/users/rms}. - -@example -@group -(substitute-in-file-name "$HOME/foo") - @result{} "/xcssun/users/rms/foo" -@end group -@end example - -After substitution, if a @samp{~} or a @samp{/} appears immediately -after another @samp{/}, the function discards everything before it (up -through the immediately preceding @samp{/}). - -@example -@group -(substitute-in-file-name "bar/~/foo") - @result{} "~/foo" -@end group -@group -(substitute-in-file-name "/usr/local/$HOME/foo") - @result{} "/xcssun/users/rms/foo" - ;; @r{@file{/usr/local/} has been discarded.} -@end group -@end example - -@end defun - -@node Unique File Names -@subsection Generating Unique File Names - - Some programs need to write temporary files. Here is the usual way to -construct a name for such a file: - -@example -(make-temp-file @var{name-of-application}) -@end example - -@noindent -The job of @code{make-temp-file} is to prevent two different users or -two different jobs from trying to use the exact same file name. - -@defun make-temp-file prefix &optional dir-flag suffix -This function creates a temporary file and returns its name. Emacs -creates the temporary file's name by adding to @var{prefix} some -random characters that are different in each Emacs job. The result is -guaranteed to be a newly created empty file. On MS-DOS, this function -can truncate the @var{string} prefix to fit into the 8+3 file-name -limits. If @var{prefix} is a relative file name, it is expanded -against @code{temporary-file-directory}. - -@example -@group -(make-temp-file "foo") - @result{} "/tmp/foo232J6v" -@end group -@end example - -When @code{make-temp-file} returns, the file has been created and is -empty. At that point, you should write the intended contents into the -file. - -If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an -empty directory instead of an empty file. It returns the file name, -not the directory name, of that directory. @xref{Directory Names}. - -If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at -the end of the file name. - -To prevent conflicts among different libraries running in the same -Emacs, each Lisp program that uses @code{make-temp-file} should have its -own @var{prefix}. The number added to the end of @var{prefix} -distinguishes between the same application running in different Emacs -jobs. Additional added characters permit a large number of distinct -names even in one Emacs job. -@end defun - - The default directory for temporary files is controlled by the -variable @code{temporary-file-directory}. This variable gives the user -a uniform way to specify the directory for all temporary files. Some -programs use @code{small-temporary-file-directory} instead, if that is -non-@code{nil}. To use it, you should expand the prefix against -the proper directory before calling @code{make-temp-file}. - -@defopt temporary-file-directory -@cindex @env{TMPDIR} environment variable -@cindex @env{TMP} environment variable -@cindex @env{TEMP} environment variable -This variable specifies the directory name for creating temporary files. -Its value should be a directory name (@pxref{Directory Names}), but it -is good for Lisp programs to cope if the value is a directory's file -name instead. Using the value as the second argument to -@code{expand-file-name} is a good way to achieve that. - -The default value is determined in a reasonable way for your operating -system; it is based on the @env{TMPDIR}, @env{TMP} and @env{TEMP} -environment variables, with a fall-back to a system-dependent name if -none of these variables is defined. - -Even if you do not use @code{make-temp-file} to create the temporary -file, you should still use this variable to decide which directory to -put the file in. However, if you expect the file to be small, you -should use @code{small-temporary-file-directory} first if that is -non-@code{nil}. -@end defopt - -@defopt small-temporary-file-directory -This variable specifies the directory name for -creating certain temporary files, which are likely to be small. - -If you want to write a temporary file which is likely to be small, you -should compute the directory like this: - -@example -(make-temp-file - (expand-file-name @var{prefix} - (or small-temporary-file-directory - temporary-file-directory))) -@end example -@end defopt - -@defun make-temp-name base-name -This function generates a string that can be used as a unique file -name. The name starts with @var{base-name}, and has several random -characters appended to it, which are different in each Emacs job. It -is like @code{make-temp-file} except that (i) it just constructs a -name, and does not create a file, and (ii) @var{base-name} should be -an absolute file name (on MS-DOS, this function can truncate -@var{base-name} to fit into the 8+3 file-name limits). - -@strong{Warning:} In most cases, you should not use this function; use -@code{make-temp-file} instead! This function is susceptible to a race -condition, between the @code{make-temp-name} call and the creation of -the file, which in some cases may cause a security hole. -@end defun - -@node File Name Completion -@subsection File Name Completion -@cindex file name completion subroutines -@cindex completion, file name - - This section describes low-level subroutines for completing a file -name. For higher level functions, see @ref{Reading File Names}. - -@defun file-name-all-completions partial-filename directory -This function returns a list of all possible completions for a file -whose name starts with @var{partial-filename} in directory -@var{directory}. The order of the completions is the order of the files -in the directory, which is unpredictable and conveys no useful -information. - -The argument @var{partial-filename} must be a file name containing no -directory part and no slash (or backslash on some systems). The current -buffer's default directory is prepended to @var{directory}, if -@var{directory} is not absolute. - -In the following example, suppose that @file{~rms/lewis} is the current -default directory, and has five files whose names begin with @samp{f}: -@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and -@file{file.c.~2~}.@refill - -@example -@group -(file-name-all-completions "f" "") - @result{} ("foo" "file~" "file.c.~2~" - "file.c.~1~" "file.c") -@end group - -@group -(file-name-all-completions "fo" "") - @result{} ("foo") -@end group -@end example -@end defun - -@defun file-name-completion filename directory &optional predicate -This function completes the file name @var{filename} in directory -@var{directory}. It returns the longest prefix common to all file names -in directory @var{directory} that start with @var{filename}. If -@var{predicate} is non-@code{nil} then it ignores possible completions -that don't satisfy @var{predicate}, after calling that function -with one argument, the expanded absolute file name. - -If only one match exists and @var{filename} matches it exactly, the -function returns @code{t}. The function returns @code{nil} if directory -@var{directory} contains no name starting with @var{filename}. - -In the following example, suppose that the current default directory -has five files whose names begin with @samp{f}: @file{foo}, -@file{file~}, @file{file.c}, @file{file.c.~1~}, and -@file{file.c.~2~}.@refill - -@example -@group -(file-name-completion "fi" "") - @result{} "file" -@end group - -@group -(file-name-completion "file.c.~1" "") - @result{} "file.c.~1~" -@end group - -@group -(file-name-completion "file.c.~1~" "") - @result{} t -@end group - -@group -(file-name-completion "file.c.~3" "") - @result{} nil -@end group -@end example -@end defun - -@defopt completion-ignored-extensions -@code{file-name-completion} usually ignores file names that end in any -string in this list. It does not ignore them when all the possible -completions end in one of these suffixes. This variable has no effect -on @code{file-name-all-completions}.@refill - -A typical value might look like this: - -@example -@group -completion-ignored-extensions - @result{} (".o" ".elc" "~" ".dvi") -@end group -@end example - -If an element of @code{completion-ignored-extensions} ends in a slash -@samp{/}, it signals a directory. The elements which do @emph{not} end -in a slash will never match a directory; thus, the above value will not -filter out a directory named @file{foo.elc}. -@end defopt - -@node Standard File Names -@subsection Standard File Names - - Sometimes, an Emacs Lisp program needs to specify a standard file -name for a particular use---typically, to hold configuration data -specified by the current user. Usually, such files should be located -in the directory specified by @code{user-emacs-directory}, which is -@file{~/.emacs.d} by default (@pxref{Init File}). For example, abbrev -definitions are stored by default in @file{~/.emacs.d/abbrev_defs}. -The easiest way to specify such a file name is to use the function -@code{locate-user-emacs-file}. - -@defun locate-user-emacs-file base-name &optional old-name -This function returns an absolute file name for an Emacs-specific -configuration or data file. The argument @file{base-name} should be a -relative file name. The return value is the absolute name of a file -in the directory specified by @code{user-emacs-directory}; if that -directory does not exist, this function creates it. - -If the optional argument @var{old-name} is non-@code{nil}, it -specifies a file in the user's home directory, -@file{~/@var{old-name}}. If such a file exists, the return value is -the absolute name of that file, instead of the file specified by -@var{base-name}. This argument is intended to be used by Emacs -packages to provide backward compatibility. For instance, prior to -the introduction of @code{user-emacs-directory}, the abbrev file was -located in @file{~/.abbrev_defs}. Here is the definition of -@code{abbrev-file-name}: - -@example -(defcustom abbrev-file-name - (locate-user-emacs-file "abbrev_defs" ".abbrev_defs") - "Default name of file from which to read abbrevs." - @dots{} - :type 'file) -@end example -@end defun - - A lower-level function for standardizing file names, which -@code{locate-user-emacs-file} uses as a subroutine, is -@code{convert-standard-filename}. - -@defun convert-standard-filename filename -This function returns a file name based on @var{filename}, which fits -the conventions of the current operating system. - -On GNU and Unix systems, this simply returns @var{filename}. On other -operating systems, it may enforce system-specific file name -conventions; for example, on MS-DOS this function performs a variety -of changes to enforce MS-DOS file name limitations, including -converting any leading @samp{.} to @samp{_} and truncating to three -characters after the @samp{.}. - -The recommended way to use this function is to specify a name which -fits the conventions of GNU and Unix systems, and pass it to -@code{convert-standard-filename}. -@end defun - -@node Contents of Directories -@section Contents of Directories -@cindex directory-oriented functions -@cindex file names in directory - - A directory is a kind of file that contains other files entered under -various names. Directories are a feature of the file system. - - Emacs can list the names of the files in a directory as a Lisp list, -or display the names in a buffer using the @code{ls} shell command. In -the latter case, it can optionally display information about each file, -depending on the options passed to the @code{ls} command. - -@defun directory-files directory &optional full-name match-regexp nosort -This function returns a list of the names of the files in the directory -@var{directory}. By default, the list is in alphabetical order. - -If @var{full-name} is non-@code{nil}, the function returns the files' -absolute file names. Otherwise, it returns the names relative to -the specified directory. - -If @var{match-regexp} is non-@code{nil}, this function returns only -those file names that contain a match for that regular expression---the -other file names are excluded from the list. On case-insensitive -filesystems, the regular expression matching is case-insensitive. - -@c Emacs 19 feature -If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort -the list, so you get the file names in no particular order. Use this if -you want the utmost possible speed and don't care what order the files -are processed in. If the order of processing is visible to the user, -then the user will probably be happier if you do sort the names. - -@example -@group -(directory-files "~lewis") - @result{} ("#foo#" "#foo.el#" "." ".." - "dired-mods.el" "files.texi" - "files.texi.~1~") -@end group -@end example - -An error is signaled if @var{directory} is not the name of a directory -that can be read. -@end defun - -@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format -This is similar to @code{directory-files} in deciding which files -to report on and how to report their names. However, instead -of returning a list of file names, it returns for each file a -list @code{(@var{filename} . @var{attributes})}, where @var{attributes} -is what @code{file-attributes} would return for that file. -The optional argument @var{id-format} has the same meaning as the -corresponding argument to @code{file-attributes} (@pxref{Definition -of file-attributes}). -@end defun - -@defun file-expand-wildcards pattern &optional full -This function expands the wildcard pattern @var{pattern}, returning -a list of file names that match it. - -If @var{pattern} is written as an absolute file name, -the values are absolute also. - -If @var{pattern} is written as a relative file name, it is interpreted -relative to the current default directory. The file names returned are -normally also relative to the current default directory. However, if -@var{full} is non-@code{nil}, they are absolute. -@end defun - -@defun insert-directory file switches &optional wildcard full-directory-p -This function inserts (in the current buffer) a directory listing for -directory @var{file}, formatted with @code{ls} according to -@var{switches}. It leaves point after the inserted text. -@var{switches} may be a string of options, or a list of strings -representing individual options. - -The argument @var{file} may be either a directory name or a file -specification including wildcard characters. If @var{wildcard} is -non-@code{nil}, that means treat @var{file} as a file specification with -wildcards. - -If @var{full-directory-p} is non-@code{nil}, that means the directory -listing is expected to show the full contents of a directory. You -should specify @code{t} when @var{file} is a directory and switches do -not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to -describe a directory itself as a file, rather than showing its -contents.) - -On most systems, this function works by running a directory listing -program whose name is in the variable @code{insert-directory-program}. -If @var{wildcard} is non-@code{nil}, it also runs the shell specified by -@code{shell-file-name}, to expand the wildcards. - -MS-DOS and MS-Windows systems usually lack the standard Unix program -@code{ls}, so this function emulates the standard Unix program @code{ls} -with Lisp code. - -As a technical detail, when @var{switches} contains the long -@samp{--dired} option, @code{insert-directory} treats it specially, -for the sake of dired. However, the normally equivalent short -@samp{-D} option is just passed on to @code{insert-directory-program}, -as any other option. -@end defun - -@defvar insert-directory-program -This variable's value is the program to run to generate a directory listing -for the function @code{insert-directory}. It is ignored on systems -which generate the listing with Lisp code. -@end defvar - -@node Create/Delete Dirs -@section Creating, Copying and Deleting Directories -@cindex creating, copying and deleting directories -@c Emacs 19 features - - Most Emacs Lisp file-manipulation functions get errors when used on -files that are directories. For example, you cannot delete a directory -with @code{delete-file}. These special functions exist to create and -delete directories. - -@findex mkdir -@deffn Command make-directory dirname &optional parents -This command creates a directory named @var{dirname}. If -@var{parents} is non-@code{nil}, as is always the case in an -interactive call, that means to create the parent directories first, -if they don't already exist. - -@code{mkdir} is an alias for this. -@end deffn - -@deffn Command copy-directory dirname newname &optional keep-time parents copy-contents -This command copies the directory named @var{dirname} to -@var{newname}. If @var{newname} names an existing directory, -@var{dirname} will be copied to a subdirectory there. - -It always sets the file modes of the copied files to match the -corresponding original file. - -The third argument @var{keep-time} non-@code{nil} means to preserve the -modification time of the copied files. A prefix arg makes -@var{keep-time} non-@code{nil}. - -The fourth argument @var{parents} says whether to -create parent directories if they don't exist. Interactively, -this happens by default. - -The fifth argument @var{copy-contents}, if non-@code{nil}, means to -copy the contents of @var{dirname} directly into @var{newname} if the -latter is an existing directory, instead of copying @var{dirname} into -it as a subdirectory. -@end deffn - -@cindex trash -@vindex delete-by-moving-to-trash -@deffn Command delete-directory dirname &optional recursive trash -This command deletes the directory named @var{dirname}. The function -@code{delete-file} does not work for files that are directories; you -must use @code{delete-directory} for them. If @var{recursive} is -@code{nil}, and the directory contains any files, -@code{delete-directory} signals an error. - -@code{delete-directory} only follows symbolic links at the level of -parent directories. - -If the optional argument @var{trash} is non-@code{nil} and the -variable @code{delete-by-moving-to-trash} is non-@code{nil}, this -command moves the file into the system Trash instead of deleting it. -@xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU -Emacs Manual}. When called interactively, @var{trash} is @code{t} if -no prefix argument is given, and @code{nil} otherwise. -@end deffn - -@node Magic File Names -@section Making Certain File Names ``Magic'' -@cindex magic file names - - You can implement special handling for certain file names. This is -called making those names @dfn{magic}. The principal use for this -feature is in implementing remote file names (@pxref{Remote Files,, -Remote Files, emacs, The GNU Emacs Manual}). - - To define a kind of magic file name, you must supply a regular -expression to define the class of names (all those that match the -regular expression), plus a handler that implements all the primitive -Emacs file operations for file names that match. - -@vindex file-name-handler-alist - The variable @code{file-name-handler-alist} holds a list of handlers, -together with regular expressions that determine when to apply each -handler. Each element has this form: - -@example -(@var{regexp} . @var{handler}) -@end example - -@noindent -All the Emacs primitives for file access and file name transformation -check the given file name against @code{file-name-handler-alist}. If -the file name matches @var{regexp}, the primitives handle that file by -calling @var{handler}. - - The first argument given to @var{handler} is the name of the -primitive, as a symbol; the remaining arguments are the arguments that -were passed to that primitive. (The first of these arguments is most -often the file name itself.) For example, if you do this: - -@example -(file-exists-p @var{filename}) -@end example - -@noindent -and @var{filename} has handler @var{handler}, then @var{handler} is -called like this: - -@example -(funcall @var{handler} 'file-exists-p @var{filename}) -@end example - - When a function takes two or more arguments that must be file names, -it checks each of those names for a handler. For example, if you do -this: - -@example -(expand-file-name @var{filename} @var{dirname}) -@end example - -@noindent -then it checks for a handler for @var{filename} and then for a handler -for @var{dirname}. In either case, the @var{handler} is called like -this: - -@example -(funcall @var{handler} 'expand-file-name @var{filename} @var{dirname}) -@end example - -@noindent -The @var{handler} then needs to figure out whether to handle -@var{filename} or @var{dirname}. - - If the specified file name matches more than one handler, the one -whose match starts last in the file name gets precedence. This rule -is chosen so that handlers for jobs such as uncompression are handled -first, before handlers for jobs such as remote file access. - - Here are the operations that a magic file name handler gets to handle: - -@ifnottex -@noindent -@code{access-file}, @code{add-name-to-file}, -@code{byte-compiler-base-file-name},@* -@code{copy-directory}, @code{copy-file}, -@code{delete-directory}, @code{delete-file}, -@code{diff-latest-backup-file}, -@code{directory-file-name}, -@code{directory-files}, -@code{directory-files-and-attributes}, -@code{dired-compress-file}, @code{dired-uncache},@* -@code{expand-file-name}, -@code{file-accessible-directory-p}, -@code{file-attributes}, -@code{file-directory-p}, -@code{file-executable-p}, @code{file-exists-p}, -@code{file-local-copy}, @code{file-remote-p}, -@code{file-modes}, @code{file-name-all-completions}, -@code{file-name-as-directory}, -@code{file-name-completion}, -@code{file-name-directory}, -@code{file-name-nondirectory}, -@code{file-name-sans-versions}, @code{file-newer-than-file-p}, -@code{file-ownership-preserved-p}, -@code{file-readable-p}, @code{file-regular-p}, @code{file-in-directory-p}, -@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, -@code{file-equal-p}, @code{find-backup-file-name}, -@c Not sure why it was here: @code{find-file-noselect},@* -@code{get-file-buffer}, -@code{insert-directory}, -@code{insert-file-contents},@* -@code{load}, -@code{make-auto-save-file-name}, -@code{make-directory}, -@code{make-directory-internal}, -@code{make-symbolic-link},@* -@code{process-file}, -@code{rename-file}, @code{set-file-modes}, @code{set-file-times}, -@code{set-visited-file-modtime}, @code{shell-command}, -@code{start-file-process}, -@code{substitute-in-file-name},@* -@code{unhandled-file-name-directory}, -@code{vc-registered}, -@code{verify-visited-file-modtime},@* -@code{write-region}. -@end ifnottex -@iftex -@noindent -@flushleft -@code{access-file}, @code{add-name-to-file}, -@code{byte-com@discretionary{}{}{}piler-base-file-name}, -@code{copy-directory}, @code{copy-file}, -@code{delete-directory}, @code{delete-file}, -@code{diff-latest-backup-file}, -@code{directory-file-name}, -@code{directory-files}, -@code{directory-files-and-at@discretionary{}{}{}tributes}, -@code{dired-compress-file}, @code{dired-uncache}, -@code{expand-file-name}, -@code{file-accessible-direc@discretionary{}{}{}tory-p}, -@code{file-attributes}, -@code{file-direct@discretionary{}{}{}ory-p}, -@code{file-executable-p}, @code{file-exists-p}, -@code{file-local-copy}, @code{file-remote-p}, -@code{file-modes}, @code{file-name-all-completions}, -@code{file-name-as-directory}, -@code{file-name-completion}, -@code{file-name-directory}, -@code{file-name-nondirec@discretionary{}{}{}tory}, -@code{file-name-sans-versions}, @code{file-newer-than-file-p}, -@code{file-ownership-pre@discretionary{}{}{}served-p}, -@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, -@code{file-truename}, @code{file-writable-p}, -@code{find-backup-file-name}, -@c Not sure why it was here: @code{find-file-noselect}, -@code{get-file-buffer}, -@code{insert-directory}, -@code{insert-file-contents}, -@code{load}, @code{make-direc@discretionary{}{}{}tory}, -@code{make-direc@discretionary{}{}{}tory-internal}, -@code{make-symbolic-link}, -@code{process-file}, -@code{rename-file}, @code{set-file-modes}, -@code{set-visited-file-modtime}, @code{shell-command}, -@code{start-file-process}, -@code{substitute-in-file-name}, -@code{unhandled-file-name-directory}, -@code{vc-regis@discretionary{}{}{}tered}, -@code{verify-visited-file-modtime}, -@code{write-region}. -@end flushleft -@end iftex - - Handlers for @code{insert-file-contents} typically need to clear the -buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the -@var{visit} argument is non-@code{nil}. This also has the effect of -unlocking the buffer if it is locked. - - The handler function must handle all of the above operations, and -possibly others to be added in the future. It need not implement all -these operations itself---when it has nothing special to do for a -certain operation, it can reinvoke the primitive, to handle the -operation ``in the usual way''. It should always reinvoke the primitive -for an operation it does not recognize. Here's one way to do this: - -@smallexample -(defun my-file-handler (operation &rest args) - ;; @r{First check for the specific operations} - ;; @r{that we have special handling for.} - (cond ((eq operation 'insert-file-contents) @dots{}) - ((eq operation 'write-region) @dots{}) - @dots{} - ;; @r{Handle any operation we don't know about.} - (t (let ((inhibit-file-name-handlers - (cons 'my-file-handler - (and (eq inhibit-file-name-operation operation) - inhibit-file-name-handlers))) - (inhibit-file-name-operation operation)) - (apply operation args))))) -@end smallexample - - When a handler function decides to call the ordinary Emacs primitive for -the operation at hand, it needs to prevent the primitive from calling -the same handler once again, thus leading to an infinite recursion. The -example above shows how to do this, with the variables -@code{inhibit-file-name-handlers} and -@code{inhibit-file-name-operation}. Be careful to use them exactly as -shown above; the details are crucial for proper behavior in the case of -multiple handlers, and for operations that have two file names that may -each have handlers. - -@kindex safe-magic (@r{property}) - Handlers that don't really do anything special for actual access to the -file---such as the ones that implement completion of host names for -remote file names---should have a non-@code{nil} @code{safe-magic} -property. For instance, Emacs normally ``protects'' directory names -it finds in @code{PATH} from becoming magic, if they look like magic -file names, by prefixing them with @samp{/:}. But if the handler that -would be used for them has a non-@code{nil} @code{safe-magic} -property, the @samp{/:} is not added. - -@kindex operations (@r{property}) - A file name handler can have an @code{operations} property to -declare which operations it handles in a nontrivial way. If this -property has a non-@code{nil} value, it should be a list of -operations; then only those operations will call the handler. This -avoids inefficiency, but its main purpose is for autoloaded handler -functions, so that they won't be loaded except when they have real -work to do. - - Simply deferring all operations to the usual primitives does not -work. For instance, if the file name handler applies to -@code{file-exists-p}, then it must handle @code{load} itself, because -the usual @code{load} code won't work properly in that case. However, -if the handler uses the @code{operations} property to say it doesn't -handle @code{file-exists-p}, then it need not handle @code{load} -nontrivially. - -@defvar inhibit-file-name-handlers -This variable holds a list of handlers whose use is presently inhibited -for a certain operation. -@end defvar - -@defvar inhibit-file-name-operation -The operation for which certain handlers are presently inhibited. -@end defvar - -@defun find-file-name-handler file operation -This function returns the handler function for file name @var{file}, -or @code{nil} if there is none. The argument @var{operation} should -be the operation to be performed on the file---the value you will pass -to the handler as its first argument when you call it. If -@var{operation} equals @code{inhibit-file-name-operation}, or if it is -not found in the @code{operations} property of the handler, this -function returns @code{nil}. -@end defun - -@defun file-local-copy filename -This function copies file @var{filename} to an ordinary non-magic file -on the local machine, if it isn't on the local machine already. Magic -file names should handle the @code{file-local-copy} operation if they -refer to files on other machines. A magic file name that is used for -other purposes than remote file access should not handle -@code{file-local-copy}; then this function will treat the file as -local. - -If @var{filename} is local, whether magic or not, this function does -nothing and returns @code{nil}. Otherwise it returns the file name -of the local copy file. -@end defun - -@defun file-remote-p filename &optional identification connected -This function tests whether @var{filename} is a remote file. If -@var{filename} is local (not remote), the return value is @code{nil}. -If @var{filename} is indeed remote, the return value is a string that -identifies the remote system. - -This identifier string can include a host name and a user name, as -well as characters designating the method used to access the remote -system. For example, the remote identifier string for the filename -@code{/sudo::/some/file} is @code{/sudo:root@@localhost:}. - -If @code{file-remote-p} returns the same identifier for two different -filenames, that means they are stored on the same file system and can -be accessed locally with respect to each other. This means, for -example, that it is possible to start a remote process accessing both -files at the same time. Implementers of file handlers need to ensure -this principle is valid. - -@var{identification} specifies which part of the identifier shall be -returned as string. @var{identification} can be the symbol -@code{method}, @code{user} or @code{host}; any other value is handled -like @code{nil} and means to return the complete identifier string. -In the example above, the remote @code{user} identifier string would -be @code{root}. - -If @var{connected} is non-@code{nil}, this function returns @code{nil} -even if @var{filename} is remote, if Emacs has no network connection -to its host. This is useful when you want to avoid the delay of -making connections when they don't exist. -@end defun - -@defun unhandled-file-name-directory filename -This function returns the name of a directory that is not magic. It -uses the directory part of @var{filename} if that is not magic. For a -magic file name, it invokes the file name handler, which therefore -decides what value to return. If @var{filename} is not accessible -from a local process, then the file name handler should indicate it by -returning @code{nil}. - -This is useful for running a subprocess; every subprocess must have a -non-magic directory to serve as its current directory, and this function -is a good way to come up with one. -@end defun - -@defopt remote-file-name-inhibit-cache -The attributes of remote files can be cached for better performance. If -they are changed outside of Emacs's control, the cached values become -invalid, and must be reread. - -When this variable is set to @code{nil}, cached values are never -expired. Use this setting with caution, only if you are sure nothing -other than Emacs ever changes the remote files. If it is set to -@code{t}, cached values are never used. This is the safest value, but -could result in performance degradation. - -A compromise is to set it to a positive number. This means that -cached values are used for that amount of seconds since they were -cached. If a remote file is checked regularly, it might be a good -idea to let-bind this variable to a value less than the time period -between consecutive checks. For example: - -@example -(defun display-time-file-nonempty-p (file) - (let ((remote-file-name-inhibit-cache - (- display-time-interval 5))) - (and (file-exists-p file) - (< 0 (nth 7 (file-attributes (file-chase-links file))))))) -@end example -@end defopt - -@node Format Conversion -@section File Format Conversion - -@cindex file format conversion -@cindex encoding file formats -@cindex decoding file formats -@cindex text properties in files -@cindex saving text properties - Emacs performs several steps to convert the data in a buffer (text, -text properties, and possibly other information) to and from a -representation suitable for storing into a file. This section describes -the fundamental functions that perform this @dfn{format conversion}, -namely @code{insert-file-contents} for reading a file into a buffer, -and @code{write-region} for writing a buffer into a file. - -@menu -* Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}. -* Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}. -* Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion. -@end menu - -@node Format Conversion Overview -@subsection Overview -@noindent -The function @code{insert-file-contents}: - -@itemize -@item initially, inserts bytes from the file into the buffer; -@item decodes bytes to characters as appropriate; -@item processes formats as defined by entries in @code{format-alist}; and -@item calls functions in @code{after-insert-file-functions}. -@end itemize - -@noindent -The function @code{write-region}: - -@itemize -@item initially, calls functions in @code{write-region-annotate-functions}; -@item processes formats as defined by entries in @code{format-alist}; -@item encodes characters to bytes as appropriate; and -@item modifies the file with the bytes. -@end itemize - - This shows the symmetry of the lowest-level operations; reading and -writing handle things in opposite order. The rest of this section -describes the two facilities surrounding the three variables named -above, as well as some related functions. @ref{Coding Systems}, for -details on character encoding and decoding. - -@node Format Conversion Round-Trip -@subsection Round-Trip Specification - - The most general of the two facilities is controlled by the variable -@code{format-alist}, a list of @dfn{file format} specifications, which -describe textual representations used in files for the data in an Emacs -buffer. The descriptions for reading and writing are paired, which is -why we call this ``round-trip'' specification -(@pxref{Format Conversion Piecemeal}, for non-paired specification). - -@defvar format-alist -This list contains one format definition for each defined file format. -Each format definition is a list of this form: - -@example -(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve}) -@end example -@end defvar - -@cindex format definition -@noindent -Here is what the elements in a format definition mean: - -@table @var -@item name -The name of this format. - -@item doc-string -A documentation string for the format. - -@item regexp -A regular expression which is used to recognize files represented in -this format. If @code{nil}, the format is never applied automatically. - -@item from-fn -A shell command or function to decode data in this format (to convert -file data into the usual Emacs data representation). - -A shell command is represented as a string; Emacs runs the command as a -filter to perform the conversion. - -If @var{from-fn} is a function, it is called with two arguments, @var{begin} -and @var{end}, which specify the part of the buffer it should convert. -It should convert the text by editing it in place. Since this can -change the length of the text, @var{from-fn} should return the modified -end position. - -One responsibility of @var{from-fn} is to make sure that the beginning -of the file no longer matches @var{regexp}. Otherwise it is likely to -get called again. - -@item to-fn -A shell command or function to encode data in this format---that is, to -convert the usual Emacs data representation into this format. - -If @var{to-fn} is a string, it is a shell command; Emacs runs the -command as a filter to perform the conversion. - -If @var{to-fn} is a function, it is called with three arguments: -@var{begin} and @var{end}, which specify the part of the buffer it -should convert, and @var{buffer}, which specifies which buffer. There -are two ways it can do the conversion: - -@itemize @bullet -@item -By editing the buffer in place. In this case, @var{to-fn} should -return the end-position of the range of text, as modified. - -@item -By returning a list of annotations. This is a list of elements of the -form @code{(@var{position} . @var{string})}, where @var{position} is an -integer specifying the relative position in the text to be written, and -@var{string} is the annotation to add there. The list must be sorted in -order of position when @var{to-fn} returns it. - -When @code{write-region} actually writes the text from the buffer to the -file, it intermixes the specified annotations at the corresponding -positions. All this takes place without modifying the buffer. -@end itemize - -@item modify -A flag, @code{t} if the encoding function modifies the buffer, and -@code{nil} if it works by returning a list of annotations. - -@item mode-fn -A minor-mode function to call after visiting a file converted from this -format. The function is called with one argument, the integer 1; -that tells a minor-mode function to enable the mode. - -@item preserve -A flag, @code{t} if @code{format-write-file} should not remove this format -from @code{buffer-file-format}. -@end table - -The function @code{insert-file-contents} automatically recognizes file -formats when it reads the specified file. It checks the text of the -beginning of the file against the regular expressions of the format -definitions, and if it finds a match, it calls the decoding function for -that format. Then it checks all the known formats over again. -It keeps checking them until none of them is applicable. - -Visiting a file, with @code{find-file-noselect} or the commands that use -it, performs conversion likewise (because it calls -@code{insert-file-contents}); it also calls the mode function for each -format that it decodes. It stores a list of the format names in the -buffer-local variable @code{buffer-file-format}. - -@defvar buffer-file-format -This variable states the format of the visited file. More precisely, -this is a list of the file format names that were decoded in the course -of visiting the current buffer's file. It is always buffer-local in all -buffers. -@end defvar - -When @code{write-region} writes data into a file, it first calls the -encoding functions for the formats listed in @code{buffer-file-format}, -in the order of appearance in the list. - -@deffn Command format-write-file file format &optional confirm -This command writes the current buffer contents into the file @var{file} -in a format based on @var{format}, which is a list of format names. It -constructs the actual format starting from @var{format}, then appending -any elements from the value of @code{buffer-file-format} with a -non-@code{nil} @var{preserve} flag (see above), if they are not already -present in @var{format}. It then updates @code{buffer-file-format} with -this format, making it the default for future saves. Except for the -@var{format} argument, this command is similar to @code{write-file}. In -particular, @var{confirm} has the same meaning and interactive treatment -as the corresponding argument to @code{write-file}. @xref{Definition of -write-file}. -@end deffn - -@deffn Command format-find-file file format -This command finds the file @var{file}, converting it according to -format @var{format}. It also makes @var{format} the default if the -buffer is saved later. - -The argument @var{format} is a list of format names. If @var{format} is -@code{nil}, no conversion takes place. Interactively, typing just -@key{RET} for @var{format} specifies @code{nil}. -@end deffn - -@deffn Command format-insert-file file format &optional beg end -This command inserts the contents of file @var{file}, converting it -according to format @var{format}. If @var{beg} and @var{end} are -non-@code{nil}, they specify which part of the file to read, as in -@code{insert-file-contents} (@pxref{Reading from Files}). - -The return value is like what @code{insert-file-contents} returns: a -list of the absolute file name and the length of the data inserted -(after conversion). - -The argument @var{format} is a list of format names. If @var{format} is -@code{nil}, no conversion takes place. Interactively, typing just -@key{RET} for @var{format} specifies @code{nil}. -@end deffn - -@defvar buffer-auto-save-file-format -This variable specifies the format to use for auto-saving. Its value is -a list of format names, just like the value of -@code{buffer-file-format}; however, it is used instead of -@code{buffer-file-format} for writing auto-save files. If the value -is @code{t}, the default, auto-saving uses the same format as a -regular save in the same buffer. This variable is always buffer-local -in all buffers. -@end defvar - -@node Format Conversion Piecemeal -@subsection Piecemeal Specification - - In contrast to the round-trip specification described in the previous -subsection (@pxref{Format Conversion Round-Trip}), you can use the variables -@code{after-insert-file-functions} and @code{write-region-annotate-functions} -to separately control the respective reading and writing conversions. - - Conversion starts with one representation and produces another -representation. When there is only one conversion to do, there is no -conflict about what to start with. However, when there are multiple -conversions involved, conflict may arise when two conversions need to -start with the same data. - - This situation is best understood in the context of converting text -properties during @code{write-region}. For example, the character at -position 42 in a buffer is @samp{X} with a text property @code{foo}. If -the conversion for @code{foo} is done by inserting into the buffer, say, -@samp{FOO:}, then that changes the character at position 42 from -@samp{X} to @samp{F}. The next conversion will start with the wrong -data straight away. - - To avoid conflict, cooperative conversions do not modify the buffer, -but instead specify @dfn{annotations}, a list of elements of the form -@code{(@var{position} . @var{string})}, sorted in order of increasing -@var{position}. - - If there is more than one conversion, @code{write-region} merges their -annotations destructively into one sorted list. Later, when the text -from the buffer is actually written to the file, it intermixes the -specified annotations at the corresponding positions. All this takes -place without modifying the buffer. - -@c ??? What about ``overriding'' conversions like those allowed -@c ??? for `write-region-annotate-functions', below? --ttn - - In contrast, when reading, the annotations intermixed with the text -are handled immediately. @code{insert-file-contents} sets point to -the beginning of some text to be converted, then calls the conversion -functions with the length of that text. These functions should always -return with point at the beginning of the inserted text. This -approach makes sense for reading because annotations removed by the -first converter can't be mistakenly processed by a later converter. -Each conversion function should scan for the annotations it -recognizes, remove the annotation, modify the buffer text (to set a -text property, for example), and return the updated length of the -text, as it stands after those changes. The value returned by one -function becomes the argument to the next function. - -@defvar write-region-annotate-functions -A list of functions for @code{write-region} to call. Each function in -the list is called with two arguments: the start and end of the region -to be written. These functions should not alter the contents of the -buffer. Instead, they should return annotations. - -As a special case, a function may return with a different buffer -current. Emacs takes this to mean that the current buffer contains -altered text to be output. It therefore changes the @var{start} and -@var{end} arguments of the @code{write-region} call, giving them the -values of @code{point-min} and @code{point-max} in the new buffer, -respectively. It also discards all previous annotations, because they -should have been dealt with by this function. -@end defvar - -@defvar write-region-post-annotation-function -The value of this variable, if non-@code{nil}, should be a function. -This function is called, with no arguments, after @code{write-region} -has completed. - -If any function in @code{write-region-annotate-functions} returns with -a different buffer current, Emacs calls -@code{write-region-post-annotation-function} more than once. Emacs -calls it with the last buffer that was current, and again with the -buffer before that, and so on back to the original buffer. - -Thus, a function in @code{write-region-annotate-functions} can create -a buffer, give this variable the local value of @code{kill-buffer} in -that buffer, set up the buffer with altered text, and make the buffer -current. The buffer will be killed after @code{write-region} is done. -@end defvar - -@defvar after-insert-file-functions -Each function in this list is called by @code{insert-file-contents} -with one argument, the number of characters inserted, and with point -at the beginning of the inserted text. Each function should leave -point unchanged, and return the new character count describing the -inserted text as modified by the function. -@c ??? The docstring mentions a handler from `file-name-handler-alist' -@c "intercepting" `insert-file-contents'. Hmmm. --ttn -@end defvar - - We invite users to write Lisp programs to store and retrieve text -properties in files, using these hooks, and thus to experiment with -various data formats and find good ones. Eventually we hope users -will produce good, general extensions we can install in Emacs. - - We suggest not trying to handle arbitrary Lisp objects as text property -names or values---because a program that general is probably difficult -to write, and slow. Instead, choose a set of possible data types that -are reasonably flexible, and not too hard to encode. diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi deleted file mode 100644 index 29c3dcad404..00000000000 --- a/doc/lispref/frames.texi +++ /dev/null @@ -1,2443 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/frames -@node Frames, Positions, Windows, Top -@chapter Frames -@cindex frame - - A @dfn{frame} is a screen object that contains one or more Emacs -windows (@pxref{Windows}). It is the kind of object called a -``window'' in the terminology of graphical environments; but we can't -call it a ``window'' here, because Emacs uses that word in a different -way. In Emacs Lisp, a @dfn{frame object} is a Lisp object that -represents a frame on the screen. @xref{Frame Type}. - - A frame initially contains a single main window and/or a minibuffer -window; you can subdivide the main window vertically or horizontally -into smaller windows. @xref{Splitting Windows}. - -@cindex terminal - A @dfn{terminal} is a display device capable of displaying one or -more Emacs frames. In Emacs Lisp, a @dfn{terminal object} is a Lisp -object that represents a terminal. @xref{Terminal Type}. - -@cindex text terminal -@cindex graphical terminal -@cindex graphical display - There are two classes of terminals: @dfn{text terminals} and -@dfn{graphical terminals}. Text terminals are non-graphics-capable -displays, including @command{xterm} and other terminal emulators. On -a text terminal, each Emacs frame occupies the terminal's entire -screen; although you can create additional frames and switch between -them, the terminal only shows one frame at a time. Graphical -terminals, on the other hand, are managed by graphical display systems -such as the X Window System, which allow Emacs to show multiple frames -simultaneously on the same display. - - On GNU and Unix systems, you can create additional frames on any -available terminal, within a single Emacs session, regardless of -whether Emacs was started on a text or graphical terminal. Emacs can -display on both graphical and text terminals simultaneously. This -comes in handy, for instance, when you connect to the same session -from several remote locations. @xref{Multiple Terminals}. - -@defun framep object -This predicate returns a non-@code{nil} value if @var{object} is a -frame, and @code{nil} otherwise. For a frame, the value indicates which -kind of display the frame uses: - -@table @code -@item t -The frame is displayed on a text terminal. -@item x -The frame is displayed on an X graphical terminal. -@item w32 -The frame is displayed on a MS-Windows graphical terminal. -@item ns -The frame is displayed on a GNUstep or Macintosh Cocoa graphical -terminal. -@item pc -The frame is displayed on an MS-DOS terminal. -@end table -@end defun - -@defun frame-terminal &optional frame -This function returns the terminal object that displays @var{frame}. -If @var{frame} is @code{nil} or unspecified, it defaults to the -selected frame. -@end defun - -@defun terminal-live-p object -This predicate returns a non-@code{nil} value if @var{object} is a -terminal that is live (i.e.@: not deleted), and @code{nil} otherwise. -For live terminals, the return value indicates what kind of frames are -displayed on that terminal; the list of possible values is the same as -for @code{framep} above. -@end defun - -@menu -* Creating Frames:: Creating additional frames. -* Multiple Terminals:: Displaying on several different devices. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Terminal Parameters:: Parameters common for all frames on terminal. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other windows; - lowering it makes the others hide it. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shape:: Specifying the shape of the mouse pointer. -* Window System Selections:: Transferring text to and from other X clients. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* Color Names:: Getting the definitions of color names. -* Text Terminal Colors:: Defining colors for text terminals. -* Resources:: Getting resource values from the server. -* Display Feature Testing:: Determining the features of a terminal. -@end menu - -@node Creating Frames -@section Creating Frames - -To create a new frame, call the function @code{make-frame}. - -@deffn Command make-frame &optional alist -This function creates and returns a new frame, displaying the current -buffer. - -The @var{alist} argument is an alist that specifies frame parameters -for the new frame. @xref{Frame Parameters}. If you specify the -@code{terminal} parameter in @var{alist}, the new frame is created on -that terminal. Otherwise, if you specify the @code{window-system} -frame parameter in @var{alist}, that determines whether the frame -should be displayed on a text terminal or a graphical terminal. -@xref{Window Systems}. If neither is specified, the new frame is -created in the same terminal as the selected frame. - -Any parameters not mentioned in @var{alist} default to the values in -the alist @code{default-frame-alist} (@pxref{Initial Parameters}); -parameters not specified there default from the X resources or its -equivalent on your operating system (@pxref{X Resources,, X Resources, -emacs, The GNU Emacs Manual}). After the frame is created, Emacs -applies any parameters listed in @code{frame-inherited-parameters} -(see below) and not present in the argument, taking the values from -the frame that was selected when @code{make-frame} was called. - -This function itself does not make the new frame the selected frame. -@xref{Input Focus}. The previously selected frame remains selected. -On graphical terminals, however, the windowing system may select the -new frame for its own reasons. -@end deffn - -@defvar before-make-frame-hook -A normal hook run by @code{make-frame} before it creates the frame. -@end defvar - -@defvar after-make-frame-functions -An abnormal hook run by @code{make-frame} after it creates the frame. -Each function in @code{after-make-frame-functions} receives one argument, the -frame just created. -@end defvar - -@defvar frame-inherited-parameters -This variable specifies the list of frame parameters that a newly -created frame inherits from the currently selected frame. For each -parameter (a symbol) that is an element in the list and is not present -in the argument to @code{make-frame}, the function sets the value of -that parameter in the created frame to its value in the selected -frame. -@end defvar - -@node Multiple Terminals -@section Multiple Terminals -@cindex multiple terminals -@cindex multi-tty -@cindex multiple X displays -@cindex displays, multiple - - Emacs represents each terminal as a @dfn{terminal object} data type -(@pxref{Terminal Type}). On GNU and Unix systems, Emacs can use -multiple terminals simultaneously in each session. On other systems, -it can only use a single terminal. Each terminal object has the -following attributes: - -@itemize @bullet -@item -The name of the device used by the terminal (e.g.@: @samp{:0.0} or -@file{/dev/tty}). - -@item -The terminal and keyboard coding systems used on the terminal. -@xref{Terminal I/O Encoding}. - -@item -The kind of display associated with the terminal. This is the symbol -returned by the function @code{terminal-live-p} (i.e.@: @code{x}, -@code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}. - -@item -A list of terminal parameters. @xref{Terminal Parameters}. -@end itemize - - There is no primitive for creating terminal objects. Emacs creates -them as needed, such as when you call @code{make-frame-on-display} -(described below). - -@defun terminal-name &optional terminal -This function returns the file name of the device used by -@var{terminal}. If @var{terminal} is omitted or @code{nil}, it -defaults to the selected frame's terminal. @var{terminal} can also be -a frame, meaning that frame's terminal. -@end defun - -@defun terminal-list -This function returns a list of all live terminal objects. -@end defun - -@defun get-device-terminal device -This function returns a terminal whose device name is given by -@var{device}. If @var{device} is a string, it can be either the file -name of a terminal device, or the name of an X display of the form -@samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is a -frame, this function returns that frame's terminal; @code{nil} means -the selected frame. Finally, if @var{device} is a terminal object -that represents a live terminal, that terminal is returned. The -function signals an error if its argument is none of the above. -@end defun - -@defun delete-terminal &optional terminal force -This function deletes all frames on @var{terminal} and frees the -resources used by it. It runs the abnormal hook -@code{delete-terminal-functions}, passing @var{terminal} as the -argument to each function. - -If @var{terminal} is omitted or @code{nil}, it defaults to the -selected frame's terminal. @var{terminal} can also be a frame, -meaning that frame's terminal. - -Normally, this function signals an error if you attempt to delete the -sole active terminal, but if @var{force} is non-@code{nil}, you are -allowed to do so. Emacs automatically calls this function when the -last frame on a terminal is deleted (@pxref{Deleting Frames}). -@end defun - -@defvar delete-terminal-functions -An abnormal hook run by @code{delete-terminal}. Each function -receives one argument, the @var{terminal} argument passed to -@code{delete-terminal}. Due to technical details, the functions may -be called either just before the terminal is deleted, or just -afterwards. -@end defvar - -@cindex terminal-local variables - A few Lisp variables are @dfn{terminal-local}; that is, they have a -separate binding for each terminal. The binding in effect at any time -is the one for the terminal that the currently selected frame belongs -to. These variables include @code{default-minibuffer-frame}, -@code{defining-kbd-macro}, @code{last-kbd-macro}, and -@code{system-key-alist}. They are always terminal-local, and can -never be buffer-local (@pxref{Buffer-Local Variables}). - - On GNU and Unix systems, each X display is a separate graphical -terminal. When Emacs is started from within the X window system, it -uses the X display specified by the @env{DISPLAY} environment -variable, or by the @samp{--display} option (@pxref{Initial Options,,, -emacs, The GNU Emacs Manual}). Emacs can connect to other X displays -via the command @code{make-frame-on-display}. Each X display has its -own selected frame and its own minibuffer windows; however, only one -of those frames is ``@emph{the} selected frame'' at any given moment -(@pxref{Input Focus}). Emacs can even connect to other text -terminals, by interacting with the @command{emacsclient} program. -@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. - - A single X server can handle more than one display. Each X display -has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}. -The first two parts, @var{host} and @var{server}, identify the X -server; the third part, @var{screen}, identifies a screen number on -that X server. When you use two or more screens belonging to one -server, Emacs knows by the similarity in their names that they share a -single keyboard. - - On some ``multi-monitor'' setups, a single X display outputs to more -than one physical monitor. Currently, there is no way for Emacs to -distinguish between the different physical monitors. - -@deffn Command make-frame-on-display display &optional parameters -This function creates and returns a new frame on @var{display}, taking -the other frame parameters from the alist @var{parameters}. -@var{display} should be the name of an X display (a string). - -Before creating the frame, this function ensures that Emacs is ``set -up'' to display graphics. For instance, if Emacs has not processed X -resources (e.g.@: if it was started on a text terminal), it does so at -this time. In all other respects, this function behaves like -@code{make-frame} (@pxref{Creating Frames}). -@end deffn - -@defun x-display-list -This function returns a list that indicates which X displays Emacs has -a connection to. The elements of the list are strings, and each one -is a display name. -@end defun - -@defun x-open-connection display &optional xrm-string must-succeed -This function opens a connection to the X display @var{display}, -without creating a frame on that display. Normally, Emacs Lisp -programs need not call this function, as @code{make-frame-on-display} -calls it automatically. The only reason for calling it is to check -whether communication can be established with a given X display. - -The optional argument @var{xrm-string}, if not @code{nil}, is a string -of resource names and values, in the same format used in the -@file{.Xresources} file. @xref{X Resources,, X Resources, emacs, The -GNU Emacs Manual}. These values apply to all Emacs frames created on -this display, overriding the resource values recorded in the X server. -Here's an example of what this string might look like: - -@example -"*BorderWidth: 3\n*InternalBorder: 2\n" -@end example - -If @var{must-succeed} is non-@code{nil}, failure to open the connection -terminates Emacs. Otherwise, it is an ordinary Lisp error. -@end defun - -@defun x-close-connection display -This function closes the connection to display @var{display}. Before -you can do this, you must first delete all the frames that were open -on that display (@pxref{Deleting Frames}). -@end defun - -@node Frame Parameters -@section Frame Parameters -@cindex frame parameters - - A frame has many parameters that control its appearance and behavior. -Just what parameters a frame has depends on what display mechanism it -uses. - - Frame parameters exist mostly for the sake of graphical displays. -Most frame parameters have no effect when applied to a frame on a text -terminal; only the @code{height}, @code{width}, @code{name}, -@code{title}, @code{menu-bar-lines}, @code{buffer-list} and -@code{buffer-predicate} parameters do something special. If the -terminal supports colors, the parameters @code{foreground-color}, -@code{background-color}, @code{background-mode} and -@code{display-type} are also meaningful. If the terminal supports -frame transparency, the parameter @code{alpha} is also meaningful. - -@menu -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. -@end menu - -@node Parameter Access -@subsection Access to Frame Parameters - -These functions let you read and change the parameter values of a -frame. - -@defun frame-parameter frame parameter -This function returns the value of the parameter @var{parameter} (a -symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the -selected frame's parameter. If @var{frame} has no setting for -@var{parameter}, this function returns @code{nil}. -@end defun - -@defun frame-parameters &optional frame -The function @code{frame-parameters} returns an alist listing all the -parameters of @var{frame} and their values. If @var{frame} is -@code{nil} or omitted, this returns the selected frame's parameters -@end defun - -@defun modify-frame-parameters frame alist -This function alters the parameters of frame @var{frame} based on the -elements of @var{alist}. Each element of @var{alist} has the form -@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a -parameter. If you don't mention a parameter in @var{alist}, its value -doesn't change. If @var{frame} is @code{nil}, it defaults to the selected -frame. -@end defun - -@defun set-frame-parameter frame parm value -This function sets the frame parameter @var{parm} to the specified -@var{value}. If @var{frame} is @code{nil}, it defaults to the -selected frame. -@end defun - -@defun modify-all-frames-parameters alist -This function alters the frame parameters of all existing frames -according to @var{alist}, then modifies @code{default-frame-alist} -(and, if necessary, @code{initial-frame-alist}) to apply the same -parameter values to frames that will be created henceforth. -@end defun - -@node Initial Parameters -@subsection Initial Frame Parameters - -You can specify the parameters for the initial startup frame by -setting @code{initial-frame-alist} in your init file (@pxref{Init -File}). - -@defopt initial-frame-alist -This variable's value is an alist of parameter values used when -creating the initial frame. You can set this variable to specify the -appearance of the initial frame without altering subsequent frames. -Each element has the form: - -@example -(@var{parameter} . @var{value}) -@end example - -Emacs creates the initial frame before it reads your init -file. After reading that file, Emacs checks @code{initial-frame-alist}, -and applies the parameter settings in the altered value to the already -created initial frame. - -If these settings affect the frame geometry and appearance, you'll see -the frame appear with the wrong ones and then change to the specified -ones. If that bothers you, you can specify the same geometry and -appearance with X resources; those do take effect before the frame is -created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. - -X resource settings typically apply to all frames. If you want to -specify some X resources solely for the sake of the initial frame, and -you don't want them to apply to subsequent frames, here's how to achieve -this. Specify parameters in @code{default-frame-alist} to override the -X resources for subsequent frames; then, to prevent these from affecting -the initial frame, specify the same parameters in -@code{initial-frame-alist} with values that match the X resources. -@end defopt - -If these parameters specify a separate @dfn{minibuffer-only frame} with -@code{(minibuffer . nil)}, and you have not created one, Emacs creates -one for you. - -@cindex minibuffer-only frame -@defopt minibuffer-frame-alist -This variable's value is an alist of parameter values used when -creating an initial minibuffer-only frame. This is the -minibuffer-only frame that Emacs creates if @code{initial-frame-alist} -specifies a frame with no minibuffer. -@end defopt - -@defopt default-frame-alist -This is an alist specifying default values of frame parameters for all -Emacs frames---the first frame, and subsequent frames. When using the X -Window System, you can get the same results by means of X resources -in many cases. - -Setting this variable does not affect existing frames. -@end defopt - -Functions that display a buffer in a separate frame can override the -default parameters by supplying their own parameters. @xref{Definition -of special-display-frame-alist}. - -If you invoke Emacs with command-line options that specify frame -appearance, those options take effect by adding elements to either -@code{initial-frame-alist} or @code{default-frame-alist}. Options -which affect just the initial frame, such as @samp{-geometry} and -@samp{--maximized}, add to @code{initial-frame-alist}; the others add -to @code{default-frame-alist}. @pxref{Emacs Invocation,, Command Line -Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}. - -@node Window Frame Parameters -@subsection Window Frame Parameters -@cindex frame parameters for windowed displays - - Just what parameters a frame has depends on what display mechanism -it uses. This section describes the parameters that have special -meanings on some or all kinds of terminals. Of these, @code{name}, -@code{title}, @code{height}, @code{width}, @code{buffer-list} and -@code{buffer-predicate} provide meaningful information in terminal -frames, and @code{tty-color-mode} is meaningful only for frames on -text terminals. - -@menu -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Font and Color Parameters:: Fonts and colors for the frame text. -@end menu - -@node Basic Parameters -@subsubsection Basic Parameters - - These frame parameters give the most basic information about the -frame. @code{title} and @code{name} are meaningful on all terminals. - -@table @code -@vindex display, a frame parameter -@item display -The display on which to open this frame. It should be a string of the -form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the -@env{DISPLAY} environment variable. - -@vindex display-type, a frame parameter -@item display-type -This parameter describes the range of possible colors that can be used -in this frame. Its value is @code{color}, @code{grayscale} or -@code{mono}. - -@vindex title, a frame parameter -@item title -If a frame has a non-@code{nil} title, it appears in the window -system's title bar at the top of the frame, and also in the mode line -of windows in that frame if @code{mode-line-frame-identification} uses -@samp{%F} (@pxref{%-Constructs}). This is normally the case when -Emacs is not using a window system, and can only display one frame at -a time. @xref{Frame Titles}. - -@vindex name, a frame parameter -@item name -The name of the frame. The frame name serves as a default for the frame -title, if the @code{title} parameter is unspecified or @code{nil}. If -you don't specify a name, Emacs sets the frame name automatically -(@pxref{Frame Titles}). - -If you specify the frame name explicitly when you create the frame, the -name is also used (instead of the name of the Emacs executable) when -looking up X resources for the frame. - -@item explicit-name -If the frame name was specified explicitly when the frame was created, -this parameter will be that name. If the frame wasn't explicitly -named, this parameter will be @code{nil}. -@end table - -@node Position Parameters -@subsubsection Position Parameters -@cindex window position on display - - Position parameters' values are normally measured in pixels, but on -text terminals they count characters or lines instead. - -@table @code -@vindex left, a frame parameter -@item left -The position, in pixels, of the left (or right) edge of the frame with -respect to the left (or right) edge of the screen. The value may be: - -@table @asis -@item an integer -A positive integer relates the left edge of the frame to the left edge -of the screen. A negative integer relates the right frame edge to the -right screen edge. - -@item @code{(+ @var{pos})} -This specifies the position of the left frame edge relative to the left -screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen. - -@item @code{(- @var{pos})} -This specifies the position of the right frame edge relative to the right -screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen. -@end table - -Some window managers ignore program-specified positions. If you want to -be sure the position you specify is not ignored, specify a -non-@code{nil} value for the @code{user-position} parameter as well. - -@vindex top, a frame parameter -@item top -The screen position of the top (or bottom) edge, in pixels, with respect -to the top (or bottom) edge of the screen. It works just like -@code{left}, except vertically instead of horizontally. - -@vindex icon-left, a frame parameter -@item icon-left -The screen position of the left edge of the frame's icon, in pixels, -counting from the left edge of the screen. This takes effect when the -frame is iconified, if the window manager supports this feature. If -you specify a value for this parameter, then you must also specify a -value for @code{icon-top} and vice versa. - -@vindex icon-top, a frame parameter -@item icon-top -The screen position of the top edge of the frame's icon, in pixels, -counting from the top edge of the screen. This takes effect when the -frame is iconified, if the window manager supports this feature. - -@vindex user-position, a frame parameter -@item user-position -When you create a frame and specify its screen position with the -@code{left} and @code{top} parameters, use this parameter to say whether -the specified position was user-specified (explicitly requested in some -way by a human user) or merely program-specified (chosen by a program). -A non-@code{nil} value says the position was user-specified. - -@cindex window positions and window managers -Window managers generally heed user-specified positions, and some heed -program-specified positions too. But many ignore program-specified -positions, placing the window in a default fashion or letting the user -place it with the mouse. Some window managers, including @code{twm}, -let the user specify whether to obey program-specified positions or -ignore them. - -When you call @code{make-frame}, you should specify a non-@code{nil} -value for this parameter if the values of the @code{left} and @code{top} -parameters represent the user's stated preference; otherwise, use -@code{nil}. -@end table - -@node Size Parameters -@subsubsection Size Parameters -@cindex window size on display - - Frame parameters specify frame sizes in character units. On -graphical displays, the @code{default} face determines the actual -pixel sizes of these character units (@pxref{Face Attributes}). - -@table @code -@vindex height, a frame parameter -@item height -The height of the frame contents, in characters. (To get the height in -pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.) - -@vindex width, a frame parameter -@item width -The width of the frame contents, in characters. (To get the width in -pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.) - -@vindex user-size, a frame parameter -@item user-size -This does for the size parameters @code{height} and @code{width} what -the @code{user-position} parameter (@pxref{Position Parameters, -user-position}) does for the position parameters @code{top} and -@code{left}. - -@cindex full-screen frames -@vindex fullscreen, a frame parameter -@item fullscreen -Specify that width, height or both shall be maximized. The value -@code{fullwidth} specifies that width shall be as wide as possible. -The value @code{fullheight} specifies that height shall be as tall as -possible. The value @code{fullboth} specifies that both the width and -the height shall be set to the size of the screen. The value -@code{maximized} specifies that the frame shall be maximized. The -difference between @code{maximized} and @code{fullboth} is that the -former still has window manager decorations while the latter really -covers the whole screen. -@end table - -@node Layout Parameters -@subsubsection Layout Parameters -@cindex layout parameters of frames -@cindex frame layout parameters - - These frame parameters enable or disable various parts of the -frame, or control their sizes. - -@table @code -@vindex border-width, a frame parameter -@item border-width -The width in pixels of the frame's border. - -@vindex internal-border-width, a frame parameter -@item internal-border-width -The distance in pixels between text (or fringe) and the frame's border. - -@vindex vertical-scroll-bars, a frame parameter -@item vertical-scroll-bars -Whether the frame has scroll bars for vertical scrolling, and which side -of the frame they should be on. The possible values are @code{left}, -@code{right}, and @code{nil} for no scroll bars. - -@ignore -@vindex horizontal-scroll-bars, a frame parameter -@item horizontal-scroll-bars -Whether the frame has scroll bars for horizontal scrolling -(non-@code{nil} means yes). Horizontal scroll bars are not currently -implemented. -@end ignore - -@vindex scroll-bar-width, a frame parameter -@item scroll-bar-width -The width of vertical scroll bars, in pixels, or @code{nil} meaning to -use the default width. - -@vindex left-fringe, a frame parameter -@vindex right-fringe, a frame parameter -@item left-fringe -@itemx right-fringe -The default width of the left and right fringes of windows in this -frame (@pxref{Fringes}). If either of these is zero, that effectively -removes the corresponding fringe. - -When you use @code{frame-parameter} to query the value of either of -these two frame parameters, the return value is always an integer. -When using @code{set-frame-parameter}, passing a @code{nil} value -imposes an actual default value of 8 pixels. - -The combined fringe widths must add up to an integral number of -columns, so the actual default fringe widths for the frame, as -reported by @code{frame-parameter}, may be larger than what you -specify. Any extra width is distributed evenly between the left and -right fringe. However, you can force one fringe or the other to a -precise width by specifying that width as a negative integer. If both -widths are negative, only the left fringe gets the specified width. - -@vindex menu-bar-lines frame parameter -@item menu-bar-lines -The number of lines to allocate at the top of the frame for a menu -bar. The default is 1 if Menu Bar mode is enabled, and 0 otherwise. -@xref{Menu Bars,,,emacs, The GNU Emacs Manual}. - -@vindex tool-bar-lines frame parameter -@item tool-bar-lines -The number of lines to use for the tool bar. The default is 1 if Tool -Bar mode is enabled, and 0 otherwise. @xref{Tool Bars,,,emacs, The -GNU Emacs Manual}. - -@vindex tool-bar-position frame parameter -@item tool-bar-position -The position of the tool bar. Currently only for the GTK tool bar. -Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}. -The default is @code{top}. - -@vindex line-spacing, a frame parameter -@item line-spacing -Additional space to leave below each text line, in pixels (a positive -integer). @xref{Line Height}, for more information. -@end table - -@node Buffer Parameters -@subsubsection Buffer Parameters - - These frame parameters, meaningful on all kinds of terminals, deal -with which buffers have been, or should, be displayed in the frame. - -@table @code -@vindex minibuffer, a frame parameter -@item minibuffer -Whether this frame has its own minibuffer. The value @code{t} means -yes, @code{nil} means no, @code{only} means this frame is just a -minibuffer. If the value is a minibuffer window (in some other -frame), the frame uses that minibuffer. - -This frame parameter takes effect when the frame is created, and can -not be changed afterwards. - -@vindex buffer-predicate, a frame parameter -@item buffer-predicate -The buffer-predicate function for this frame. The function -@code{other-buffer} uses this predicate (from the selected frame) to -decide which buffers it should consider, if the predicate is not -@code{nil}. It calls the predicate with one argument, a buffer, once for -each buffer; if the predicate returns a non-@code{nil} value, it -considers that buffer. - -@vindex buffer-list, a frame parameter -@item buffer-list -A list of buffers that have been selected in this frame, ordered -most-recently-selected first. - -@vindex unsplittable, a frame parameter -@item unsplittable -If non-@code{nil}, this frame's window is never split automatically. -@end table - -@node Management Parameters -@subsubsection Window Management Parameters -@cindex window manager interaction, and frame parameters - - The following frame parameters control various aspects of the -frame's interaction with the window manager. They have no effect on -text terminals. - -@table @code -@vindex visibility, a frame parameter -@item visibility -The state of visibility of the frame. There are three possibilities: -@code{nil} for invisible, @code{t} for visible, and @code{icon} for -iconified. @xref{Visibility of Frames}. - -@vindex auto-raise, a frame parameter -@item auto-raise -If non-@code{nil}, Emacs automatically raises the frame when it is -selected. Some window managers do not allow this. - -@vindex auto-lower, a frame parameter -@item auto-lower -If non-@code{nil}, Emacs automatically lowers the frame when it is -deselected. Some window managers do not allow this. - -@vindex icon-type, a frame parameter -@item icon-type -The type of icon to use for this frame. If the value is a string, -that specifies a file containing a bitmap to use; @code{nil} specifies -no icon (in which case the window manager decides what to show); any -other non-@code{nil} value specifies the default Emacs icon. - -@vindex icon-name, a frame parameter -@item icon-name -The name to use in the icon for this frame, when and if the icon -appears. If this is @code{nil}, the frame's title is used. - -@vindex window-id, a frame parameter -@item window-id -The ID number which the graphical display uses for this frame. Emacs -assigns this parameter when the frame is created; changing the -parameter has no effect on the actual ID number. - -@vindex outer-window-id, a frame parameter -@item outer-window-id -The ID number of the outermost window-system window in which the frame -exists. As with @code{window-id}, changing this parameter has no -actual effect. - -@vindex wait-for-wm, a frame parameter -@item wait-for-wm -If non-@code{nil}, tell Xt to wait for the window manager to confirm -geometry changes. Some window managers, including versions of Fvwm2 -and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to -prevent hanging with those window managers. - -@vindex sticky, a frame parameter -@item sticky -If non-@code{nil}, the frame is visible on all virtual desktops on systems -with virtual desktops. - -@ignore -@vindex parent-id, a frame parameter -@item parent-id -@c ??? Not yet working. -The X window number of the window that should be the parent of this one. -Specifying this lets you create an Emacs window inside some other -application's window. (It is not certain this will be implemented; try -it and see if it works.) -@end ignore -@end table - -@node Cursor Parameters -@subsubsection Cursor Parameters -@cindex cursor, and frame parameters - - This frame parameter controls the way the cursor looks. - -@table @code -@vindex cursor-type, a frame parameter -@item cursor-type -How to display the cursor. Legitimate values are: - -@table @code -@item box -Display a filled box. (This is the default.) -@item hollow -Display a hollow box. -@item nil -Don't display a cursor. -@item bar -Display a vertical bar between characters. -@item (bar . @var{width}) -Display a vertical bar @var{width} pixels wide between characters. -@item hbar -Display a horizontal bar. -@item (hbar . @var{height}) -Display a horizontal bar @var{height} pixels high. -@end table -@end table - -@vindex cursor-type -The @code{cursor-type} frame parameter may be overridden by the -variables @code{cursor-type} and -@code{cursor-in-non-selected-windows}: - -@defvar cursor-type -This buffer-local variable controls how the cursor looks in a selected -window showing the buffer. If its value is @code{t}, that means to -use the cursor specified by the @code{cursor-type} frame parameter. -Otherwise, the value should be one of the cursor types listed above, -and it overrides the @code{cursor-type} frame parameter. -@end defvar - -@defopt cursor-in-non-selected-windows -This buffer-local variable controls how the cursor looks in a window -that is not selected. It supports the same values as the -@code{cursor-type} frame parameter; also, @code{nil} means don't -display a cursor in nonselected windows, and @code{t} (the default) -means use a standard modification of the usual cursor type (solid box -becomes hollow box, and bar becomes a narrower bar). -@end defopt - -@defopt blink-cursor-alist -This variable specifies how to blink the cursor. Each element has the -form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor -type equals @var{on-state} (comparing using @code{equal}), the -corresponding @var{off-state} specifies what the cursor looks like -when it blinks ``off''. Both @var{on-state} and @var{off-state} -should be suitable values for the @code{cursor-type} frame parameter. - -There are various defaults for how to blink each type of cursor, if -the type is not mentioned as an @var{on-state} here. Changes in this -variable do not take effect immediately, only when you specify the -@code{cursor-type} frame parameter. -@end defopt - -@node Font and Color Parameters -@subsubsection Font and Color Parameters -@cindex font and color, frame parameters - - These frame parameters control the use of fonts and colors. - -@table @code -@vindex font-backend, a frame parameter -@item font-backend -A list of symbols, specifying the @dfn{font backends} to use for -drawing fonts in the frame, in order of priority. On X, there are -currently two available font backends: @code{x} (the X core font -driver) and @code{xft} (the Xft font driver). On Windows, there are -currently two available font backends: @code{gdi} and -@code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs -Manual}). On other systems, there is only one available font backend, -so it does not make sense to modify this frame parameter. - -@vindex background-mode, a frame parameter -@item background-mode -This parameter is either @code{dark} or @code{light}, according -to whether the background color is a light one or a dark one. - -@vindex tty-color-mode, a frame parameter -@item tty-color-mode -@cindex standard colors for character terminals -This parameter overrides the terminal's color support as given by the -system's terminal capabilities database in that this parameter's value -specifies the color mode to use on a text terminal. The value can be -either a symbol or a number. A number specifies the number of colors -to use (and, indirectly, what commands to issue to produce each -color). For example, @code{(tty-color-mode . 8)} specifies use of the -ANSI escape sequences for 8 standard text colors. A value of -1 turns -off color support. - -If the parameter's value is a symbol, it specifies a number through -the value of @code{tty-color-mode-alist}, and the associated number is -used instead. - -@vindex screen-gamma, a frame parameter -@item screen-gamma -@cindex gamma correction -If this is a number, Emacs performs ``gamma correction'' which adjusts -the brightness of all colors. The value should be the screen gamma of -your display, a floating point number. - -Usual PC monitors have a screen gamma of 2.2, so color values in -Emacs, and in X windows generally, are calibrated to display properly -on a monitor with that gamma value. If you specify 2.2 for -@code{screen-gamma}, that means no correction is needed. Other values -request correction, designed to make the corrected colors appear on -your screen the way they would have appeared without correction on an -ordinary monitor with a gamma value of 2.2. - -If your monitor displays colors too light, you should specify a -@code{screen-gamma} value smaller than 2.2. This requests correction -that makes colors darker. A screen gamma value of 1.5 may give good -results for LCD color displays. - -@vindex alpha, a frame parameter -@item alpha -@cindex opacity, frame -@cindex transparency, frame -@vindex frame-alpha-lower-limit -This parameter specifies the opacity of the frame, on graphical -displays that support variable opacity. It should be an integer -between 0 and 100, where 0 means completely transparent and 100 means -completely opaque. It can also have a @code{nil} value, which tells -Emacs not to set the frame opacity (leaving it to the window manager). - -To prevent the frame from disappearing completely from view, the -variable @code{frame-alpha-lower-limit} defines a lower opacity limit. -If the value of the frame parameter is less than the value of this -variable, Emacs uses the latter. By default, -@code{frame-alpha-lower-limit} is 20. - -The @code{alpha} frame parameter can also be a cons cell -@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the -opacity of the frame when it is selected, and @samp{inactive} is the -opacity when it is not selected. -@end table - -The following frame parameters are semi-obsolete in that they are -automatically equivalent to particular face attributes of particular -faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}): - -@table @code -@vindex font, a frame parameter -@item font -The name of the font for displaying text in the frame. This is a -string, either a valid font name for your system or the name of an Emacs -fontset (@pxref{Fontsets}). It is equivalent to the @code{font} -attribute of the @code{default} face. - -@vindex foreground-color, a frame parameter -@item foreground-color -The color to use for the image of a character. It is equivalent to -the @code{:foreground} attribute of the @code{default} face. - -@vindex background-color, a frame parameter -@item background-color -The color to use for the background of characters. It is equivalent to -the @code{:background} attribute of the @code{default} face. - -@vindex mouse-color, a frame parameter -@item mouse-color -The color for the mouse pointer. It is equivalent to the @code{:background} -attribute of the @code{mouse} face. - -@vindex cursor-color, a frame parameter -@item cursor-color -The color for the cursor that shows point. It is equivalent to the -@code{:background} attribute of the @code{cursor} face. - -@vindex border-color, a frame parameter -@item border-color -The color for the border of the frame. It is equivalent to the -@code{:background} attribute of the @code{border} face. - -@vindex scroll-bar-foreground, a frame parameter -@item scroll-bar-foreground -If non-@code{nil}, the color for the foreground of scroll bars. It is -equivalent to the @code{:foreground} attribute of the -@code{scroll-bar} face. - -@vindex scroll-bar-background, a frame parameter -@item scroll-bar-background -If non-@code{nil}, the color for the background of scroll bars. It is -equivalent to the @code{:background} attribute of the -@code{scroll-bar} face. -@end table - -@node Size and Position -@subsection Frame Size And Position -@cindex size of frame -@cindex screen size -@cindex frame size -@cindex resize frame - - You can read or change the size and position of a frame using the -frame parameters @code{left}, @code{top}, @code{height}, and -@code{width}. Whatever geometry parameters you don't specify are chosen -by the window manager in its usual fashion. - - Here are some special features for working with sizes and positions. -(For the precise meaning of ``selected frame'' used by these functions, -see @ref{Input Focus}.) - -@defun set-frame-position frame left top -This function sets the position of the top left corner of @var{frame} to -@var{left} and @var{top}. These arguments are measured in pixels, and -normally count from the top left corner of the screen. - -Negative parameter values position the bottom edge of the window up from -the bottom edge of the screen, or the right window edge to the left of -the right edge of the screen. It would probably be better if the values -were always counted from the left and top, so that negative arguments -would position the frame partly off the top or left edge of the screen, -but it seems inadvisable to change that now. -@end defun - -@defun frame-height &optional frame -@defunx frame-width &optional frame -These functions return the height and width of @var{frame}, measured in -lines and columns. If you don't supply @var{frame}, they use the -selected frame. -@end defun - -@defun frame-pixel-height &optional frame -@defunx frame-pixel-width &optional frame -These functions return the height and width of the main display area -of @var{frame}, measured in pixels. If you don't supply @var{frame}, -they use the selected frame. For a text terminal, the results are in -characters rather than pixels. - -These values include the internal borders, and windows' scroll bars -and fringes (which belong to individual windows, not to the frame -itself). The exact value of the heights depends on the window-system -and toolkit in use. With GTK+, the height does not include any tool -bar or menu bar. With the Motif or Lucid toolkits, it includes the -tool bar but not the menu bar. In a graphical version with no -toolkit, it includes both the tool bar and menu bar. For a text -terminal, the result includes the menu bar. -@end defun - -@defun frame-char-height &optional frame -@defunx frame-char-width &optional frame -These functions return the height and width of a character in -@var{frame}, measured in pixels. The values depend on the choice of -font. If you don't supply @var{frame}, these functions use the selected -frame. -@end defun - -@defun set-frame-size frame cols rows -This function sets the size of @var{frame}, measured in characters; -@var{cols} and @var{rows} specify the new width and height. - -To set the size based on values measured in pixels, use -@code{frame-char-height} and @code{frame-char-width} to convert -them to units of characters. -@end defun - -@defun set-frame-height frame lines &optional pretend -This function resizes @var{frame} to a height of @var{lines} lines. The -sizes of existing windows in @var{frame} are altered proportionally to -fit. - -If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines} -lines of output in @var{frame}, but does not change its value for the -actual height of the frame. This is only useful on text terminals. -Using a smaller height than the terminal actually implements may be -useful to reproduce behavior observed on a smaller screen, or if the -terminal malfunctions when using its whole screen. Setting the frame -height ``for real'' does not always work, because knowing the correct -actual size may be necessary for correct cursor positioning on -text terminals. -@end defun - -@defun set-frame-width frame width &optional pretend -This function sets the width of @var{frame}, measured in characters. -The argument @var{pretend} has the same meaning as in -@code{set-frame-height}. -@end defun - -@node Geometry -@subsection Geometry - - Here's how to examine the data in an X-style window geometry -specification: - -@defun x-parse-geometry geom -@cindex geometry specification -The function @code{x-parse-geometry} converts a standard X window -geometry string to an alist that you can use as part of the argument to -@code{make-frame}. - -The alist describes which parameters were specified in @var{geom}, and -gives the values specified for them. Each element looks like -@code{(@var{parameter} . @var{value})}. The possible @var{parameter} -values are @code{left}, @code{top}, @code{width}, and @code{height}. - -For the size parameters, the value must be an integer. The position -parameter names @code{left} and @code{top} are not totally accurate, -because some values indicate the position of the right or bottom edges -instead. The @var{value} possibilities for the position parameters are: -an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})}; -as previously described (@pxref{Position Parameters}). - -Here is an example: - -@example -(x-parse-geometry "35x70+0-0") - @result{} ((height . 70) (width . 35) - (top - 0) (left . 0)) -@end example -@end defun - -@node Terminal Parameters -@section Terminal Parameters -@cindex terminal parameters - - Each terminal has a list of associated parameters. These -@dfn{terminal parameters} are mostly a convenient way of storage for -terminal-local variables, but some terminal parameters have a special -meaning. - - This section describes functions to read and change the parameter values -of a terminal. They all accept as their argument either a terminal or -a frame; the latter means use that frame's terminal. An argument of -@code{nil} means the selected frame's terminal. - -@defun terminal-parameters &optional terminal -This function returns an alist listing all the parameters of -@var{terminal} and their values. -@end defun - -@defun terminal-parameter terminal parameter -This function returns the value of the parameter @var{parameter} (a -symbol) of @var{terminal}. If @var{terminal} has no setting for -@var{parameter}, this function returns @code{nil}. -@end defun - -@defun set-terminal-parameter terminal parameter value -This function sets the parameter @var{parm} of @var{terminal} to the -specified @var{value}, and returns the previous value of that -parameter. -@end defun - -Here's a list of a few terminal parameters that have a special -meaning: - -@table @code -@item background-mode -The classification of the terminal's background color, either -@code{light} or @code{dark}. -@item normal-erase-is-backspace -Value is either 1 or 0, depending on whether -@code{normal-erase-is-backspace-mode} is turned on or off on this -terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}. -@item terminal-initted -After the terminal is initialized, this is set to the -terminal-specific initialization function. -@end table - -@node Frame Titles -@section Frame Titles -@cindex frame title - - Every frame has a @code{name} parameter; this serves as the default -for the frame title which window systems typically display at the top of -the frame. You can specify a name explicitly by setting the @code{name} -frame property. - - Normally you don't specify the name explicitly, and Emacs computes the -frame name automatically based on a template stored in the variable -@code{frame-title-format}. Emacs recomputes the name each time the -frame is redisplayed. - -@defvar frame-title-format -This variable specifies how to compute a name for a frame when you have -not explicitly specified one. The variable's value is actually a mode -line construct, just like @code{mode-line-format}, except that the -@samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line -Data}. -@end defvar - -@defvar icon-title-format -This variable specifies how to compute the name for an iconified frame, -when you have not explicitly specified the frame title. This title -appears in the icon itself. -@end defvar - -@defvar multiple-frames -This variable is set automatically by Emacs. Its value is @code{t} when -there are two or more frames (not counting minibuffer-only frames or -invisible frames). The default value of @code{frame-title-format} uses -@code{multiple-frames} so as to put the buffer name in the frame title -only when there is more than one frame. - -The value of this variable is not guaranteed to be accurate except -while processing @code{frame-title-format} or -@code{icon-title-format}. -@end defvar - -@node Deleting Frames -@section Deleting Frames -@cindex deleting frames - - A @dfn{live frame} is one that has not been deleted. When a frame -is deleted, it is removed from its terminal display, although it may -continue to exist as a Lisp object until there are no more references -to it. - -@deffn Command delete-frame &optional frame force -@vindex delete-frame-functions -This function deletes the frame @var{frame}. Unless @var{frame} is a -tooltip, it first runs the hook @code{delete-frame-functions} (each -function gets one argument, @var{frame}). By default, @var{frame} is -the selected frame. - -A frame cannot be deleted if its minibuffer is used by other frames. -Normally, you cannot delete a frame if all other frames are invisible, -but if @var{force} is non-@code{nil}, then you are allowed to do so. -@end deffn - -@defun frame-live-p frame -The function @code{frame-live-p} returns non-@code{nil} if the frame -@var{frame} has not been deleted. The possible non-@code{nil} return -values are like those of @code{framep}. @xref{Frames}. -@end defun - - Some window managers provide a command to delete a window. These work -by sending a special message to the program that operates the window. -When Emacs gets one of these commands, it generates a -@code{delete-frame} event, whose normal definition is a command that -calls the function @code{delete-frame}. @xref{Misc Events}. - -@node Finding All Frames -@section Finding All Frames -@cindex frames, scanning all - -@defun frame-list -This function returns a list of all the live frames, i.e.@: those that -have not been deleted. It is analogous to @code{buffer-list} for -buffers, and includes frames on all terminals. The list that you get -is newly created, so modifying the list doesn't have any effect on the -internals of Emacs. -@end defun - -@defun visible-frame-list -This function returns a list of just the currently visible frames. -@xref{Visibility of Frames}. Frames on text terminals always count as -``visible'', even though only the selected one is actually displayed. -@end defun - -@defun next-frame &optional frame minibuf -This function lets you cycle conveniently through all the frames on -the current display from an arbitrary starting point. It returns the -``next'' frame after @var{frame} in the cycle. If @var{frame} is -omitted or @code{nil}, it defaults to the selected frame (@pxref{Input -Focus}). - -The second argument, @var{minibuf}, says which frames to consider: - -@table @asis -@item @code{nil} -Exclude minibuffer-only frames. -@item @code{visible} -Consider all visible frames. -@item 0 -Consider all visible or iconified frames. -@item a window -Consider only the frames using that particular window as their -minibuffer. -@item anything else -Consider all frames. -@end table -@end defun - -@defun previous-frame &optional frame minibuf -Like @code{next-frame}, but cycles through all frames in the opposite -direction. -@end defun - - See also @code{next-window} and @code{previous-window}, in @ref{Cyclic -Window Ordering}. - -@node Minibuffers and Frames -@section Minibuffers and Frames - -Normally, each frame has its own minibuffer window at the bottom, which -is used whenever that frame is selected. If the frame has a minibuffer, -you can get it with @code{minibuffer-window} (@pxref{Definition of -minibuffer-window}). - -However, you can also create a frame with no minibuffer. Such a frame -must use the minibuffer window of some other frame. When you create the -frame, you can explicitly specify the minibuffer window to use (in some -other frame). If you don't, then the minibuffer is found in the frame -which is the value of the variable @code{default-minibuffer-frame}. Its -value should be a frame that does have a minibuffer. - -If you use a minibuffer-only frame, you might want that frame to raise -when you enter the minibuffer. If so, set the variable -@code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}. - -@defvar default-minibuffer-frame -This variable specifies the frame to use for the minibuffer window, by -default. It does not affect existing frames. It is always local to -the current terminal and cannot be buffer-local. @xref{Multiple -Terminals}. -@end defvar - -@node Input Focus -@section Input Focus -@cindex input focus -@c @cindex selected frame Duplicates selected-frame - -At any time, one frame in Emacs is the @dfn{selected frame}. The selected -window always resides on the selected frame. - -When Emacs displays its frames on several terminals (@pxref{Multiple -Terminals}), each terminal has its own selected frame. But only one -of these is ``@emph{the} selected frame'': it's the frame that belongs -to the terminal from which the most recent input came. That is, when -Emacs runs a command that came from a certain terminal, the selected -frame is the one of that terminal. Since Emacs runs only a single -command at any given time, it needs to consider only one selected -frame at a time; this frame is what we call @dfn{the selected frame} -in this manual. The display on which the selected frame is shown is -the @dfn{selected frame's display}. - -@defun selected-frame -This function returns the selected frame. -@end defun - -Some window systems and window managers direct keyboard input to the -window object that the mouse is in; others require explicit clicks or -commands to @dfn{shift the focus} to various window objects. Either -way, Emacs automatically keeps track of which frame has the focus. To -explicitly switch to a different frame from a Lisp function, call -@code{select-frame-set-input-focus}. - -Lisp programs can also switch frames ``temporarily'' by calling the -function @code{select-frame}. This does not alter the window system's -concept of focus; rather, it escapes from the window manager's control -until that control is somehow reasserted. - -When using a text terminal, only one frame can be displayed at a time -on the terminal, so after a call to @code{select-frame}, the next -redisplay actually displays the newly selected frame. This frame -remains selected until a subsequent call to @code{select-frame}. Each -frame on a text terminal has a number which appears in the mode line -before the buffer name (@pxref{Mode Line Variables}). - -@defun select-frame-set-input-focus frame &optional norecord -This function selects @var{frame}, raises it (should it happen to be -obscured by other frames) and tries to give it the X server's focus. -On a text terminal, the next redisplay displays the new frame on the -entire terminal screen. The optional argument @var{norecord} has the -same meaning as for @code{select-frame} (see below). The return value -of this function is not significant. -@end defun - -@deffn Command select-frame frame &optional norecord -This function selects frame @var{frame}, temporarily disregarding the -focus of the X server if any. The selection of @var{frame} lasts until -the next time the user does something to select a different frame, or -until the next time this function is called. (If you are using a -window system, the previously selected frame may be restored as the -selected frame after return to the command loop, because it still may -have the window system's input focus.) - -The specified @var{frame} becomes the selected frame, and its terminal -becomes the selected terminal. This function then calls -@code{select-window} as a subroutine, passing the window selected -within @var{frame} as its first argument and @var{norecord} as its -second argument (hence, if @var{norecord} is non-@code{nil}, this -avoids changing the order of recently selected windows nor the buffer -list). @xref{Selecting Windows}. - -This function returns @var{frame}, or @code{nil} if @var{frame} has -been deleted. - -In general, you should never use @code{select-frame} in a way that -could switch to a different terminal without switching back when -you're done. -@end deffn - -Emacs cooperates with the window system by arranging to select frames as -the server and window manager request. It does so by generating a -special kind of input event, called a @dfn{focus} event, when -appropriate. The command loop handles a focus event by calling -@code{handle-switch-frame}. @xref{Focus Events}. - -@deffn Command handle-switch-frame frame -This function handles a focus event by selecting frame @var{frame}. - -Focus events normally do their job by invoking this command. -Don't call it for any other reason. -@end deffn - -@defun redirect-frame-focus frame &optional focus-frame -This function redirects focus from @var{frame} to @var{focus-frame}. -This means that @var{focus-frame} will receive subsequent keystrokes and -events intended for @var{frame}. After such an event, the value of -@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame -events specifying @var{frame} will instead select @var{focus-frame}. - -If @var{focus-frame} is omitted or @code{nil}, that cancels any existing -redirection for @var{frame}, which therefore once again receives its own -events. - -One use of focus redirection is for frames that don't have minibuffers. -These frames use minibuffers on other frames. Activating a minibuffer -on another frame redirects focus to that frame. This puts the focus on -the minibuffer's frame, where it belongs, even though the mouse remains -in the frame that activated the minibuffer. - -Selecting a frame can also change focus redirections. Selecting frame -@code{bar}, when @code{foo} had been selected, changes any redirections -pointing to @code{foo} so that they point to @code{bar} instead. This -allows focus redirection to work properly when the user switches from -one frame to another using @code{select-window}. - -This means that a frame whose focus is redirected to itself is treated -differently from a frame whose focus is not redirected. -@code{select-frame} affects the former but not the latter. - -The redirection lasts until @code{redirect-frame-focus} is called to -change it. -@end defun - -@defopt focus-follows-mouse -This option is how you inform Emacs whether the window manager transfers -focus when the user moves the mouse. Non-@code{nil} says that it does. -When this is so, the command @code{other-frame} moves the mouse to a -position consistent with the new selected frame. -@end defopt - -@node Visibility of Frames -@section Visibility of Frames -@cindex visible frame -@cindex invisible frame -@cindex iconified frame -@cindex minimized frame -@cindex frame visibility - -A frame on a graphical display may be @dfn{visible}, @dfn{invisible}, -or @dfn{iconified}. If it is visible, its contents are displayed in -the usual manner. If it is iconified, its contents are not displayed, -but there is a little icon somewhere to bring the frame back into view -(some window managers refer to this state as @dfn{minimized} rather -than @dfn{iconified}, but from Emacs' point of view they are the same -thing). If a frame is invisible, it is not displayed at all. - - Visibility is meaningless on text terminals, since only the selected -one is actually displayed in any case. - -@defun frame-visible-p frame -This function returns the visibility status of frame @var{frame}. The -value is @code{t} if @var{frame} is visible, @code{nil} if it is -invisible, and @code{icon} if it is iconified. - -On a text terminal, all frames are considered visible, whether they -are currently being displayed or not. -@end defun - -@deffn Command iconify-frame &optional frame -This function iconifies frame @var{frame}. If you omit @var{frame}, it -iconifies the selected frame. -@end deffn - -@deffn Command make-frame-visible &optional frame -This function makes frame @var{frame} visible. If you omit -@var{frame}, it makes the selected frame visible. This does not raise -the frame, but you can do that with @code{raise-frame} if you wish -(@pxref{Raising and Lowering}). -@end deffn - -@deffn Command make-frame-invisible &optional frame force -This function makes frame @var{frame} invisible. If you omit -@var{frame}, it makes the selected frame invisible. - -Unless @var{force} is non-@code{nil}, this function refuses to make -@var{frame} invisible if all other frames are invisible.. -@end deffn - - The visibility status of a frame is also available as a frame -parameter. You can read or change it as such. @xref{Management -Parameters}. The user can also iconify and deiconify frames with the -window manager. This happens below the level at which Emacs can exert -any control, but Emacs does provide events that you can use to keep -track of such changes. @xref{Misc Events}. - -@node Raising and Lowering -@section Raising and Lowering Frames - - Most window systems use a desktop metaphor. Part of this metaphor is -the idea that windows are stacked in a notional third dimension -perpendicular to the screen surface, and thus ordered from ``highest'' -to ``lowest''. Where two windows overlap, the one higher up covers -the one underneath. Even a window at the bottom of the stack can be -seen if no other window overlaps it. - -@c @cindex raising a frame redundant with raise-frame -@cindex lowering a frame - A window's place in this ordering is not fixed; in fact, users tend -to change the order frequently. @dfn{Raising} a window means moving -it ``up'', to the top of the stack. @dfn{Lowering} a window means -moving it to the bottom of the stack. This motion is in the notional -third dimension only, and does not change the position of the window -on the screen. - - With Emacs, frames constitute the windows in the metaphor sketched -above. You can raise and lower frames using these functions: - -@deffn Command raise-frame &optional frame -This function raises frame @var{frame} (default, the selected frame). -If @var{frame} is invisible or iconified, this makes it visible. -@end deffn - -@deffn Command lower-frame &optional frame -This function lowers frame @var{frame} (default, the selected frame). -@end deffn - -@defopt minibuffer-auto-raise -If this is non-@code{nil}, activation of the minibuffer raises the frame -that the minibuffer window is in. -@end defopt - -You can also enable auto-raise (raising automatically when a frame is -selected) or auto-lower (lowering automatically when it is deselected) -for any frame using frame parameters. @xref{Management Parameters}. - -@node Frame Configurations -@section Frame Configurations -@cindex frame configuration - - A @dfn{frame configuration} records the current arrangement of frames, -all their properties, and the window configuration of each one. -(@xref{Window Configurations}.) - -@defun current-frame-configuration -This function returns a frame configuration list that describes -the current arrangement of frames and their contents. -@end defun - -@defun set-frame-configuration configuration &optional nodelete -This function restores the state of frames described in -@var{configuration}. However, this function does not restore deleted -frames. - -Ordinarily, this function deletes all existing frames not listed in -@var{configuration}. But if @var{nodelete} is non-@code{nil}, the -unwanted frames are iconified instead. -@end defun - -@node Mouse Tracking -@section Mouse Tracking -@cindex mouse tracking -@c @cindex tracking the mouse Duplicates track-mouse - - Sometimes it is useful to @dfn{track} the mouse, which means to display -something to indicate where the mouse is and move the indicator as the -mouse moves. For efficient mouse tracking, you need a way to wait until -the mouse actually moves. - - The convenient way to track the mouse is to ask for events to represent -mouse motion. Then you can wait for motion by waiting for an event. In -addition, you can easily handle any other sorts of events that may -occur. That is useful, because normally you don't want to track the -mouse forever---only until some other event, such as the release of a -button. - -@defspec track-mouse body@dots{} -This special form executes @var{body}, with generation of mouse motion -events enabled. Typically, @var{body} would use @code{read-event} to -read the motion events and modify the display accordingly. @xref{Motion -Events}, for the format of mouse motion events. - -The value of @code{track-mouse} is that of the last form in @var{body}. -You should design @var{body} to return when it sees the up-event that -indicates the release of the button, or whatever kind of event means -it is time to stop tracking. -@end defspec - -The usual purpose of tracking mouse motion is to indicate on the screen -the consequences of pushing or releasing a button at the current -position. - -In many cases, you can avoid the need to track the mouse by using -the @code{mouse-face} text property (@pxref{Special Properties}). -That works at a much lower level and runs more smoothly than -Lisp-level mouse tracking. - -@ignore -@c These are not implemented yet. - -These functions change the screen appearance instantaneously. The -effect is transient, only until the next ordinary Emacs redisplay. That -is OK for mouse tracking, since it doesn't make sense for mouse tracking -to change the text, and the body of @code{track-mouse} normally reads -the events itself and does not do redisplay. - -@defun x-contour-region window beg end -This function draws lines to make a box around the text from @var{beg} -to @var{end}, in window @var{window}. -@end defun - -@defun x-uncontour-region window beg end -This function erases the lines that would make a box around the text -from @var{beg} to @var{end}, in window @var{window}. Use it to remove -a contour that you previously made by calling @code{x-contour-region}. -@end defun - -@defun x-draw-rectangle frame left top right bottom -This function draws a hollow rectangle on frame @var{frame} with the -specified edge coordinates, all measured in pixels from the inside top -left corner. It uses the cursor color, the one used for indicating the -location of point. -@end defun - -@defun x-erase-rectangle frame left top right bottom -This function erases a hollow rectangle on frame @var{frame} with the -specified edge coordinates, all measured in pixels from the inside top -left corner. Erasure means redrawing the text and background that -normally belong in the specified rectangle. -@end defun -@end ignore - -@node Mouse Position -@section Mouse Position -@cindex mouse position -@cindex position of mouse - - The functions @code{mouse-position} and @code{set-mouse-position} -give access to the current position of the mouse. - -@defun mouse-position -This function returns a description of the position of the mouse. The -value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x} -and @var{y} are integers giving the position in characters relative to -the top left corner of the inside of @var{frame}. -@end defun - -@defvar mouse-position-function -If non-@code{nil}, the value of this variable is a function for -@code{mouse-position} to call. @code{mouse-position} calls this -function just before returning, with its normal return value as the -sole argument, and it returns whatever this function returns to it. - -This abnormal hook exists for the benefit of packages like -@file{xt-mouse.el} that need to do mouse handling at the Lisp level. -@end defvar - -@defun set-mouse-position frame x y -This function @dfn{warps the mouse} to position @var{x}, @var{y} in -frame @var{frame}. The arguments @var{x} and @var{y} are integers, -giving the position in characters relative to the top left corner of the -inside of @var{frame}. If @var{frame} is not visible, this function -does nothing. The return value is not significant. -@end defun - -@defun mouse-pixel-position -This function is like @code{mouse-position} except that it returns -coordinates in units of pixels rather than units of characters. -@end defun - -@defun set-mouse-pixel-position frame x y -This function warps the mouse like @code{set-mouse-position} except that -@var{x} and @var{y} are in units of pixels rather than units of -characters. These coordinates are not required to be within the frame. - -If @var{frame} is not visible, this function does nothing. The return -value is not significant. -@end defun - -@defun frame-pointer-visible-p &optional frame -This predicate function returns non-@code{nil} if the mouse pointer -displayed on @var{frame} is visible; otherwise it returns @code{nil}. -@var{frame} omitted or @code{nil} means the selected frame. This is -useful when @code{make-pointer-invisible} is set to @code{t}: it -allows to know if the pointer has been hidden. -@xref{Mouse Avoidance,,,emacs, The Emacs Manual}. -@end defun - -@need 3000 - -@node Pop-Up Menus -@section Pop-Up Menus - - When using a window system, a Lisp program can pop up a menu so that -the user can choose an alternative with the mouse. - -@defun x-popup-menu position menu -This function displays a pop-up menu and returns an indication of -what selection the user makes. - -The argument @var{position} specifies where on the screen to put the -top left corner of the menu. It can be either a mouse button event -(which says to put the menu where the user actuated the button) or a -list of this form: - -@example -((@var{xoffset} @var{yoffset}) @var{window}) -@end example - -@noindent -where @var{xoffset} and @var{yoffset} are coordinates, measured in -pixels, counting from the top left corner of @var{window}. @var{window} -may be a window or a frame. - -If @var{position} is @code{t}, it means to use the current mouse -position. If @var{position} is @code{nil}, it means to precompute the -key binding equivalents for the keymaps specified in @var{menu}, -without actually displaying or popping up the menu. - -The argument @var{menu} says what to display in the menu. It can be a -keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the -return value is the list of events corresponding to the user's choice. -This list has more than one element if the choice occurred in a -submenu. (Note that @code{x-popup-menu} does not actually execute the -command bound to that sequence of events.) On toolkits that support -menu titles, the title is taken from the prompt string of @var{menu} -if @var{menu} is a keymap, or from the prompt string of the first -keymap in @var{menu} if it is a list of keymaps (@pxref{Defining -Menus}). - -Alternatively, @var{menu} can have the following form: - -@example -(@var{title} @var{pane1} @var{pane2}...) -@end example - -@noindent -where each pane is a list of form - -@example -(@var{title} @var{item1} @var{item2}...) -@end example - -Each item should normally be a cons cell @code{(@var{line} . @var{value})}, -where @var{line} is a string, and @var{value} is the value to return if -that @var{line} is chosen. An item can also be a string; this makes a -non-selectable line in the menu. - -If the user gets rid of the menu without making a valid choice, for -instance by clicking the mouse away from a valid choice or by typing -keyboard input, then this normally results in a quit and -@code{x-popup-menu} does not return. But if @var{position} is a mouse -button event (indicating that the user invoked the menu with the -mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}. -@end defun - - @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu -if you could do the job with a prefix key defined with a menu keymap. -If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h -a} can see the individual items in that menu and provide help for them. -If instead you implement the menu by defining a command that calls -@code{x-popup-menu}, the help facilities cannot know what happens inside -that command, so they cannot give any help for the menu's items. - - The menu bar mechanism, which lets you switch between submenus by -moving the mouse, cannot look within the definition of a command to see -that it calls @code{x-popup-menu}. Therefore, if you try to implement a -submenu using @code{x-popup-menu}, it cannot work with the menu bar in -an integrated fashion. This is why all menu bar submenus are -implemented with menu keymaps within the parent menu, and never with -@code{x-popup-menu}. @xref{Menu Bar}. - - If you want a menu bar submenu to have contents that vary, you should -still use a menu keymap to implement it. To make the contents vary, add -a hook function to @code{menu-bar-update-hook} to update the contents of -the menu keymap as necessary. - -@node Dialog Boxes -@section Dialog Boxes -@cindex dialog boxes - - A dialog box is a variant of a pop-up menu---it looks a little -different, it always appears in the center of a frame, and it has just -one level and one or more buttons. The main use of dialog boxes is -for asking questions that the user can answer with ``yes'', ``no'', -and a few other alternatives. With a single button, they can also -force the user to acknowledge important information. The functions -@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the -keyboard, when called from commands invoked by mouse clicks. - -@defun x-popup-dialog position contents &optional header -This function displays a pop-up dialog box and returns an indication of -what selection the user makes. The argument @var{contents} specifies -the alternatives to offer; it has this format: - -@example -(@var{title} (@var{string} . @var{value})@dots{}) -@end example - -@noindent -which looks like the list that specifies a single pane for -@code{x-popup-menu}. - -The return value is @var{value} from the chosen alternative. - -As for @code{x-popup-menu}, an element of the list may be just a -string instead of a cons cell @code{(@var{string} . @var{value})}. -That makes a box that cannot be selected. - -If @code{nil} appears in the list, it separates the left-hand items from -the right-hand items; items that precede the @code{nil} appear on the -left, and items that follow the @code{nil} appear on the right. If you -don't include a @code{nil} in the list, then approximately half the -items appear on each side. - -Dialog boxes always appear in the center of a frame; the argument -@var{position} specifies which frame. The possible values are as in -@code{x-popup-menu}, but the precise coordinates or the individual -window don't matter; only the frame matters. - -If @var{header} is non-@code{nil}, the frame title for the box is -@samp{Information}, otherwise it is @samp{Question}. The former is used -for @code{message-box} (@pxref{message-box}). - -In some configurations, Emacs cannot display a real dialog box; so -instead it displays the same items in a pop-up menu in the center of the -frame. - -If the user gets rid of the dialog box without making a valid choice, -for instance using the window manager, then this produces a quit and -@code{x-popup-dialog} does not return. -@end defun - -@node Pointer Shape -@section Pointer Shape -@cindex pointer shape -@cindex mouse pointer shape - - You can specify the mouse pointer style for particular text or -images using the @code{pointer} text property, and for images with the -@code{:pointer} and @code{:map} image properties. The values you can -use in these properties are @code{text} (or @code{nil}), @code{arrow}, -@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and -@code{hourglass}. @code{text} stands for the usual mouse pointer -style used over text. - - Over void parts of the window (parts that do not correspond to any -of the buffer contents), the mouse pointer usually uses the -@code{arrow} style, but you can specify a different style (one of -those above) by setting @code{void-text-area-pointer}. - -@defopt void-text-area-pointer -This variable specifies the mouse pointer style for void text areas. -These include the areas after the end of a line or below the last line -in the buffer. The default is to use the @code{arrow} (non-text) -pointer style. -@end defopt - - When using X, you can specify what the @code{text} pointer style -really looks like by setting the variable @code{x-pointer-shape}. - -@defvar x-pointer-shape -This variable specifies the pointer shape to use ordinarily in the -Emacs frame, for the @code{text} pointer style. -@end defvar - -@defvar x-sensitive-text-pointer-shape -This variable specifies the pointer shape to use when the mouse -is over mouse-sensitive text. -@end defvar - - These variables affect newly created frames. They do not normally -affect existing frames; however, if you set the mouse color of a -frame, that also installs the current value of those two variables. -@xref{Font and Color Parameters}. - - The values you can use, to specify either of these pointer shapes, are -defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos -@key{RET} x-pointer @key{RET}} to see a list of them. - -@node Window System Selections -@section Window System Selections -@cindex selection (for window systems) -@cindex clipboard -@cindex primary selection -@cindex secondary selection - - In the X window system, data can be transferred between different -applications by means of @dfn{selections}. X defines an arbitrary -number of @dfn{selection types}, each of which can store its own data; -however, only three are commonly used: the @dfn{clipboard}, -@dfn{primary selection}, and @dfn{secondary selection}. @xref{Cut and -Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs -commands that make use of these selections. This section documents -the low-level functions for reading and setting X selections. - -@deffn Command x-set-selection type data -This function sets an X selection. It takes two arguments: a -selection type @var{type}, and the value to assign to it, @var{data}. - -@var{type} should be a symbol; it is usually one of @code{PRIMARY}, -@code{SECONDARY} or @code{CLIPBOARD}. These are symbols with -upper-case names, in accord with X Window System conventions. If -@var{type} is @code{nil}, that stands for @code{PRIMARY}. - -If @var{data} is @code{nil}, it means to clear out the selection. -Otherwise, @var{data} may be a string, a symbol, an integer (or a cons -of two integers or list of two integers), an overlay, or a cons of two -markers pointing to the same buffer. An overlay or a pair of markers -stands for text in the overlay or between the markers. The argument -@var{data} may also be a vector of valid non-vector selection values. - -This function returns @var{data}. -@end deffn - -@defun x-get-selection &optional type data-type -This function accesses selections set up by Emacs or by other X -clients. It takes two optional arguments, @var{type} and -@var{data-type}. The default for @var{type}, the selection type, is -@code{PRIMARY}. - -The @var{data-type} argument specifies the form of data conversion to -use, to convert the raw data obtained from another X client into Lisp -data. Meaningful values include @code{TEXT}, @code{STRING}, -@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE}, -@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME}, -@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS}, -@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and -@code{INTEGER}. (These are symbols with upper-case names in accord -with X conventions.) The default for @var{data-type} is -@code{STRING}. -@end defun - -@defopt selection-coding-system -This variable specifies the coding system to use when reading and -writing selections or the clipboard. @xref{Coding -Systems}. The default is @code{compound-text-with-extensions}, which -converts to the text representation that X11 normally uses. -@end defopt - -@cindex clipboard support (for MS-Windows) -When Emacs runs on MS-Windows, it does not implement X selections in -general, but it does support the clipboard. @code{x-get-selection} -and @code{x-set-selection} on MS-Windows support the text data type -only; if the clipboard holds other types of data, Emacs treats the -clipboard as empty. - -@node Drag and Drop -@section Drag and Drop - -@vindex x-dnd-test-function -@vindex x-dnd-known-types - When a user drags something from another application over Emacs, that other -application expects Emacs to tell it if Emacs can handle the data that is -dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine -what to reply. The default value is @code{x-dnd-default-test-function} -which accepts drops if the type of the data to be dropped is present in -@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or -@code{x-dnd-known-types} if you want Emacs to accept or reject drops based -on some other criteria. - -@vindex x-dnd-types-alist - If you want to change the way Emacs handles drop of different types -or add a new type, customize @code{x-dnd-types-alist}. This requires -detailed knowledge of what types other applications use for drag and -drop. - -@vindex dnd-protocol-alist - When an URL is dropped on Emacs it may be a file, but it may also be -another URL type (ftp, http, etc.). Emacs first checks -@code{dnd-protocol-alist} to determine what to do with the URL. If -there is no match there and if @code{browse-url-browser-function} is -an alist, Emacs looks for a match there. If no match is found the -text for the URL is inserted. If you want to alter Emacs behavior, -you can customize these variables. - -@node Color Names -@section Color Names - -@cindex color names -@cindex specify color -@cindex numerical RGB color specification - A color name is text (usually in a string) that specifies a color. -Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc., -are allowed; use @kbd{M-x list-colors-display} to see a list of -defined names. You can also specify colors numerically in forms such -as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where -@var{r} specifies the red level, @var{g} specifies the green level, -and @var{b} specifies the blue level. You can use either one, two, -three, or four hex digits for @var{r}; then you must use the same -number of hex digits for all @var{g} and @var{b} as well, making -either 3, 6, 9 or 12 hex digits in all. (See the documentation of the -X Window System for more details about numerical RGB specification of -colors.) - - These functions provide a way to determine which color names are -valid, and what they look like. In some cases, the value depends on the -@dfn{selected frame}, as described below; see @ref{Input Focus}, for the -meaning of the term ``selected frame''. - - To read user input of color names with completion, use -@code{read-color} (@pxref{High-Level Completion, read-color}). - -@defun color-defined-p color &optional frame -This function reports whether a color name is meaningful. It returns -@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says -which frame's display to ask about; if @var{frame} is omitted or -@code{nil}, the selected frame is used. - -Note that this does not tell you whether the display you are using -really supports that color. When using X, you can ask for any defined -color on any kind of display, and you will get some result---typically, -the closest it can do. To determine whether a frame can really display -a certain color, use @code{color-supported-p} (see below). - -@findex x-color-defined-p -This function used to be called @code{x-color-defined-p}, -and that name is still supported as an alias. -@end defun - -@defun defined-colors &optional frame -This function returns a list of the color names that are defined -and supported on frame @var{frame} (default, the selected frame). -If @var{frame} does not support colors, the value is @code{nil}. - -@findex x-defined-colors -This function used to be called @code{x-defined-colors}, -and that name is still supported as an alias. -@end defun - -@defun color-supported-p color &optional frame background-p -This returns @code{t} if @var{frame} can really display the color -@var{color} (or at least something close to it). If @var{frame} is -omitted or @code{nil}, the question applies to the selected frame. - -Some terminals support a different set of colors for foreground and -background. If @var{background-p} is non-@code{nil}, that means you are -asking whether @var{color} can be used as a background; otherwise you -are asking whether it can be used as a foreground. - -The argument @var{color} must be a valid color name. -@end defun - -@defun color-gray-p color &optional frame -This returns @code{t} if @var{color} is a shade of gray, as defined on -@var{frame}'s display. If @var{frame} is omitted or @code{nil}, the -question applies to the selected frame. If @var{color} is not a valid -color name, this function returns @code{nil}. -@end defun - -@defun color-values color &optional frame -@cindex rgb value -This function returns a value that describes what @var{color} should -ideally look like on @var{frame}. If @var{color} is defined, the -value is a list of three integers, which give the amount of red, the -amount of green, and the amount of blue. Each integer ranges in -principle from 0 to 65535, but some displays may not use the full -range. This three-element list is called the @dfn{rgb values} of the -color. - -If @var{color} is not defined, the value is @code{nil}. - -@example -(color-values "black") - @result{} (0 0 0) -(color-values "white") - @result{} (65280 65280 65280) -(color-values "red") - @result{} (65280 0 0) -(color-values "pink") - @result{} (65280 49152 51968) -(color-values "hungry") - @result{} nil -@end example - -The color values are returned for @var{frame}'s display. If -@var{frame} is omitted or @code{nil}, the information is returned for -the selected frame's display. If the frame cannot display colors, the -value is @code{nil}. - -@findex x-color-values -This function used to be called @code{x-color-values}, -and that name is still supported as an alias. -@end defun - -@node Text Terminal Colors -@section Text Terminal Colors -@cindex colors on text terminals - - Text terminals usually support only a small number of colors, and -the computer uses small integers to select colors on the terminal. -This means that the computer cannot reliably tell what the selected -color looks like; instead, you have to inform your application which -small integers correspond to which colors. However, Emacs does know -the standard set of colors and will try to use them automatically. - - The functions described in this section control how terminal colors -are used by Emacs. - - Several of these functions use or return @dfn{rgb values}, described -in @ref{Color Names}. - - These functions accept a display (either a frame or the name of a -terminal) as an optional argument. We hope in the future to make -Emacs support different colors on different text terminals; then this -argument will specify which terminal to operate on (the default being -the selected frame's terminal; @pxref{Input Focus}). At present, -though, the @var{frame} argument has no effect. - -@defun tty-color-define name number &optional rgb frame -This function associates the color name @var{name} with -color number @var{number} on the terminal. - -The optional argument @var{rgb}, if specified, is an rgb value, a list -of three numbers that specify what the color actually looks like. -If you do not specify @var{rgb}, then this color cannot be used by -@code{tty-color-approximate} to approximate other colors, because -Emacs will not know what it looks like. -@end defun - -@defun tty-color-clear &optional frame -This function clears the table of defined colors for a text terminal. -@end defun - -@defun tty-color-alist &optional frame -This function returns an alist recording the known colors supported by -a text terminal. - -Each element has the form @code{(@var{name} @var{number} . @var{rgb})} -or @code{(@var{name} @var{number})}. Here, @var{name} is the color -name, @var{number} is the number used to specify it to the terminal. -If present, @var{rgb} is a list of three color values (for red, green, -and blue) that says what the color actually looks like. -@end defun - -@defun tty-color-approximate rgb &optional frame -This function finds the closest color, among the known colors -supported for @var{display}, to that described by the rgb value -@var{rgb} (a list of color values). The return value is an element of -@code{tty-color-alist}. -@end defun - -@defun tty-color-translate color &optional frame -This function finds the closest color to @var{color} among the known -colors supported for @var{display} and returns its index (an integer). -If the name @var{color} is not defined, the value is @code{nil}. -@end defun - -@node Resources -@section X Resources - -This section describes some of the functions and variables for -querying and using X resources, or their equivalent on your operating -system. @xref{X Resources,, X Resources, emacs, The GNU Emacs -Manual}, for more information about X resources. - -@defun x-get-resource attribute class &optional component subclass -The function @code{x-get-resource} retrieves a resource value from the X -Window defaults database. - -Resources are indexed by a combination of a @dfn{key} and a @dfn{class}. -This function searches using a key of the form -@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name -under which Emacs was invoked), and using @samp{Emacs.@var{class}} as -the class. - -The optional arguments @var{component} and @var{subclass} add to the key -and the class, respectively. You must specify both of them or neither. -If you specify them, the key is -@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is -@samp{Emacs.@var{class}.@var{subclass}}. -@end defun - -@defvar x-resource-class -This variable specifies the application name that @code{x-get-resource} -should look up. The default value is @code{"Emacs"}. You can examine X -resources for application names other than ``Emacs'' by binding this -variable to some other string, around a call to @code{x-get-resource}. -@end defvar - -@defvar x-resource-name -This variable specifies the instance name that @code{x-get-resource} -should look up. The default value is the name Emacs was invoked with, -or the value specified with the @samp{-name} or @samp{-rn} switches. -@end defvar - -To illustrate some of the above, suppose that you have the line: - -@example -xterm.vt100.background: yellow -@end example - -@noindent -in your X resources file (whose name is usually @file{~/.Xdefaults} -or @file{~/.Xresources}). Then: - -@example -@group -(let ((x-resource-class "XTerm") (x-resource-name "xterm")) - (x-get-resource "vt100.background" "VT100.Background")) - @result{} "yellow" -@end group -@group -(let ((x-resource-class "XTerm") (x-resource-name "xterm")) - (x-get-resource "background" "VT100" "vt100" "Background")) - @result{} "yellow" -@end group -@end example - -@defvar inhibit-x-resources -If this variable is non-@code{nil}, Emacs does not look up X -resources, and X resources do not have any effect when creating new -frames. -@end defvar - -@node Display Feature Testing -@section Display Feature Testing -@cindex display feature testing - - The functions in this section describe the basic capabilities of a -particular display. Lisp programs can use them to adapt their behavior -to what the display can do. For example, a program that ordinarily uses -a popup menu could use the minibuffer if popup menus are not supported. - - The optional argument @var{display} in these functions specifies which -display to ask the question about. It can be a display name, a frame -(which designates the display that frame is on), or @code{nil} (which -refers to the selected frame's display, @pxref{Input Focus}). - - @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to -obtain information about displays. - -@defun display-popup-menus-p &optional display -This function returns @code{t} if popup menus are supported on -@var{display}, @code{nil} if not. Support for popup menus requires that -the mouse be available, since the user cannot choose menu items without -a mouse. -@end defun - -@defun display-graphic-p &optional display -This function returns @code{t} if @var{display} is a graphic display -capable of displaying several frames and several different fonts at -once. This is true for displays that use a window system such as X, -and false for text terminals. -@end defun - -@defun display-mouse-p &optional display -@cindex mouse, availability -This function returns @code{t} if @var{display} has a mouse available, -@code{nil} if not. -@end defun - -@defun display-color-p &optional display -@findex x-display-color-p -This function returns @code{t} if the screen is a color screen. -It used to be called @code{x-display-color-p}, and that name -is still supported as an alias. -@end defun - -@defun display-grayscale-p &optional display -This function returns @code{t} if the screen can display shades of gray. -(All color displays can do this.) -@end defun - -@defun display-supports-face-attributes-p attributes &optional display -@anchor{Display Face Attribute Testing} -This function returns non-@code{nil} if all the face attributes in -@var{attributes} are supported (@pxref{Face Attributes}). - -The definition of `supported' is somewhat heuristic, but basically -means that a face containing all the attributes in @var{attributes}, -when merged with the default face for display, can be represented in a -way that's - -@enumerate -@item -different in appearance than the default face, and - -@item -`close in spirit' to what the attributes specify, if not exact. -@end enumerate - -Point (2) implies that a @code{:weight black} attribute will be -satisfied by any display that can display bold, as will -@code{:foreground "yellow"} as long as some yellowish color can be -displayed, but @code{:slant italic} will @emph{not} be satisfied by -the tty display code's automatic substitution of a `dim' face for -italic. -@end defun - -@defun display-selections-p &optional display -This function returns @code{t} if @var{display} supports selections. -Windowed displays normally support selections, but they may also be -supported in some other cases. -@end defun - -@defun display-images-p &optional display -This function returns @code{t} if @var{display} can display images. -Windowed displays ought in principle to handle images, but some -systems lack the support for that. On a display that does not support -images, Emacs cannot display a tool bar. -@end defun - -@defun display-screens &optional display -This function returns the number of screens associated with the display. -@end defun - -@defun display-pixel-height &optional display -This function returns the height of the screen in pixels. -On a character terminal, it gives the height in characters. - -For graphical terminals, note that on ``multi-monitor'' setups this -refers to the pixel width for all physical monitors associated with -@var{display}. @xref{Multiple Terminals}. -@end defun - -@defun display-pixel-width &optional display -This function returns the width of the screen in pixels. -On a character terminal, it gives the width in characters. - -For graphical terminals, note that on ``multi-monitor'' setups this -refers to the pixel width for all physical monitors associated with -@var{display}. @xref{Multiple Terminals}. -@end defun - -@defun display-mm-height &optional display -This function returns the height of the screen in millimeters, -or @code{nil} if Emacs cannot get that information. -@end defun - -@defun display-mm-width &optional display -This function returns the width of the screen in millimeters, -or @code{nil} if Emacs cannot get that information. -@end defun - -@defopt display-mm-dimensions-alist -This variable allows the user to specify the dimensions of graphical -displays returned by @code{display-mm-height} and -@code{display-mm-width} in case the system provides incorrect values. -@end defopt - -@defun display-backing-store &optional display -This function returns the backing store capability of the display. -Backing store means recording the pixels of windows (and parts of -windows) that are not exposed, so that when exposed they can be -displayed very quickly. - -Values can be the symbols @code{always}, @code{when-mapped}, or -@code{not-useful}. The function can also return @code{nil} -when the question is inapplicable to a certain kind of display. -@end defun - -@defun display-save-under &optional display -This function returns non-@code{nil} if the display supports the -SaveUnder feature. That feature is used by pop-up windows -to save the pixels they obscure, so that they can pop down -quickly. -@end defun - -@defun display-planes &optional display -This function returns the number of planes the display supports. -This is typically the number of bits per pixel. -For a tty display, it is log to base two of the number of colors supported. -@end defun - -@defun display-visual-class &optional display -This function returns the visual class for the screen. The value is -one of the symbols @code{static-gray} (a limited, unchangeable number -of grays), @code{gray-scale} (a full range of grays), -@code{static-color} (a limited, unchangeable number of colors), -@code{pseudo-color} (a limited number of colors), @code{true-color} (a -full range of colors), and @code{direct-color} (a full range of -colors). -@end defun - -@defun display-color-cells &optional display -This function returns the number of color cells the screen supports. -@end defun - - These functions obtain additional information specifically -about X displays. - -@defun x-server-version &optional display -This function returns the list of version numbers of the X server -running the display. The value is a list of three integers: the major -and minor version numbers of the X protocol, and the -distributor-specific release number of the X server software itself. -@end defun - -@defun x-server-vendor &optional display -This function returns the ``vendor'' that provided the X server -software (as a string). Really this means whoever distributes the X -server. - -When the developers of X labeled software distributors as -``vendors'', they showed their false assumption that no system could -ever be developed and distributed noncommercially. -@end defun - -@ignore -@defvar x-no-window-manager -This variable's value is @code{t} if no X window manager is in use. -@end defvar -@end ignore - -@ignore -@item -The functions @code{x-pixel-width} and @code{x-pixel-height} return the -width and height of an X Window frame, measured in pixels. -@end ignore diff --git a/doc/lispref/front-cover-1.texi b/doc/lispref/front-cover-1.texi deleted file mode 100644 index 56d0f2b1c2d..00000000000 --- a/doc/lispref/front-cover-1.texi +++ /dev/null @@ -1,52 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename front1.info -@settitle GNU Emacs Lisp Reference Manual -@smallbook -@comment %**end of header - -@titlepage -. -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19.29 -@center for Unix Users -@center Edition 2.4, June 1995 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group -@page -. -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19.29 -@center for Unix Users -@center Edition 2.4, June 1995 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@end titlepage -@bye diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi deleted file mode 100644 index 1d37b1b220e..00000000000 --- a/doc/lispref/functions.texi +++ /dev/null @@ -1,1482 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/functions -@node Functions, Macros, Variables, Top -@chapter Functions - - A Lisp program is composed mainly of Lisp functions. This chapter -explains what functions are, how they accept arguments, and how to -define them. - -@menu -* What Is a Function:: Lisp functions vs. primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Closures:: Functions that enclose a lexical environment. -* Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Functions that the compiler will expand inline. -* Declaring Functions:: Telling the compiler that a function is defined. -* Function Safety:: Determining whether a function is safe to call. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how functions work. -@end menu - -@node What Is a Function -@section What Is a Function? - -@cindex return value -@cindex value of function -@cindex argument - In a general sense, a function is a rule for carrying out a -computation given input values called @dfn{arguments}. The result of -the computation is called the @dfn{value} or @dfn{return value} of the -function. The computation can also have side effects, such as lasting -changes in the values of variables or the contents of data structures. - - In most computer languages, every function has a name. But in Lisp, -a function in the strictest sense has no name: it is an object which -can @emph{optionally} be associated with a symbol (e.g.@: @code{car}) -that serves as the function name. @xref{Function Names}. When a -function has been given a name, we usually also refer to that symbol -as a ``function'' (e.g.@: we refer to ``the function @code{car}''). -In this manual, the distinction between a function name and the -function object itself is usually unimportant, but we will take note -wherever it is relevant. - - Certain function-like objects, called @dfn{special forms} and -@dfn{macros}, also accept arguments to carry out computations. -However, as explained below, these are not considered functions in -Emacs Lisp. - - Here are important terms for functions and function-like objects: - -@table @dfn -@item lambda expression -A function (in the strict sense, i.e.@: a function object) which is -written in Lisp. These are described in the following section. -@ifnottex -@xref{Lambda Expressions}. -@end ifnottex - -@item primitive -@cindex primitive -@cindex subr -@cindex built-in function -A function which is callable from Lisp but is actually written in C. -Primitives are also called @dfn{built-in functions}, or @dfn{subrs}. -Examples include functions like @code{car} and @code{append}. In -addition, all special forms (see below) are also considered -primitives. - -Usually, a function is implemented as a primitive because it is a -fundamental part of Lisp (e.g.@: @code{car}), or because it provides a -low-level interface to operating system services, or because it needs -to run fast. Unlike functions defined in Lisp, primitives can be -modified or added only by changing the C sources and recompiling -Emacs. See @ref{Writing Emacs Primitives}. - -@item special form -A primitive that is like a function but does not evaluate all of its -arguments in the usual way. It may evaluate only some of the -arguments, or may evaluate them in an unusual order, or several times. -Examples include @code{if}, @code{and}, and @code{while}. -@xref{Special Forms}. - -@item macro -@cindex macro -A construct defined in Lisp, which differs from a function in that it -translates a Lisp expression into another expression which is to be -evaluated instead of the original expression. Macros enable Lisp -programmers to do the sorts of things that special forms can do. -@xref{Macros}. - -@item command -@cindex command -An object which can be invoked via the @code{command-execute} -primitive, usually due to the user typing in a key sequence -@dfn{bound} to that command. @xref{Interactive Call}. A command is -usually a function; if the function is written in Lisp, it is made -into a command by an @code{interactive} form in the function -definition (@pxref{Defining Commands}). Commands that are functions -can also be called from Lisp expressions, just like other functions. - -Keyboard macros (strings and vectors) are commands also, even though -they are not functions. @xref{Keyboard Macros}. We say that a symbol -is a command if its function cell contains a command (@pxref{Symbol -Components}); such a @dfn{named command} can be invoked with -@kbd{M-x}. - -@item closure -A function object that is much like a lambda expression, except that -it also encloses an ``environment'' of lexical variable bindings. -@xref{Closures}. - -@item byte-code function -A function that has been compiled by the byte compiler. -@xref{Byte-Code Type}. - -@item autoload object -@cindex autoload object -A place-holder for a real function. If the autoload object is called, -Emacs loads the file containing the definition of the real function, -and then calls the real function. @xref{Autoload}. -@end table - - You can use the function @code{functionp} to test if an object is a -function: - -@defun functionp object -This function returns @code{t} if @var{object} is any kind of -function, i.e.@: can be passed to @code{funcall}. Note that -@code{functionp} returns @code{t} for symbols that are function names, -and returns @code{nil} for special forms. -@end defun - -@noindent -Unlike @code{functionp}, the next three functions do @emph{not} treat -a symbol as its function definition. - -@defun subrp object -This function returns @code{t} if @var{object} is a built-in function -(i.e., a Lisp primitive). - -@example -@group -(subrp 'message) ; @r{@code{message} is a symbol,} - @result{} nil ; @r{not a subr object.} -@end group -@group -(subrp (symbol-function 'message)) - @result{} t -@end group -@end example -@end defun - -@defun byte-code-function-p object -This function returns @code{t} if @var{object} is a byte-code -function. For example: - -@example -@group -(byte-code-function-p (symbol-function 'next-line)) - @result{} t -@end group -@end example -@end defun - -@defun subr-arity subr -This function provides information about the argument list of a -primitive, @var{subr}. The returned value is a pair -@code{(@var{min} . @var{max})}. @var{min} is the minimum number of -args. @var{max} is the maximum number or the symbol @code{many}, for a -function with @code{&rest} arguments, or the symbol @code{unevalled} if -@var{subr} is a special form. -@end defun - -@node Lambda Expressions -@section Lambda Expressions -@cindex lambda expression - - A lambda expression is a function object written in Lisp. Here is -an example: - -@example -(lambda (x) - "Return the hyperbolic cosine of X." - (* 0.5 (+ (exp x) (exp (- x))))) -@end example - -@noindent -In Emacs Lisp, such a list is valid as an expression---it evaluates to -itself. But its main use is not to be evaluated as an expression, but -to be called as a function. - - A lambda expression, by itself, has no name; it is an @dfn{anonymous -function}. Although lambda expressions can be used this way -(@pxref{Anonymous Functions}), they are more commonly associated with -symbols to make @dfn{named functions} (@pxref{Function Names}). -Before going into these details, the following subsections describe -the components of a lambda expression and what they do. - -@menu -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. -@end menu - -@node Lambda Components -@subsection Components of a Lambda Expression - - A lambda expression is a list that looks like this: - -@example -(lambda (@var{arg-variables}@dots{}) - [@var{documentation-string}] - [@var{interactive-declaration}] - @var{body-forms}@dots{}) -@end example - -@cindex lambda list - The first element of a lambda expression is always the symbol -@code{lambda}. This indicates that the list represents a function. The -reason functions are defined to start with @code{lambda} is so that -other lists, intended for other uses, will not accidentally be valid as -functions. - - The second element is a list of symbols---the argument variable names. -This is called the @dfn{lambda list}. When a Lisp function is called, -the argument values are matched up against the variables in the lambda -list, which are given local bindings with the values provided. -@xref{Local Variables}. - - The documentation string is a Lisp string object placed within the -function definition to describe the function for the Emacs help -facilities. @xref{Function Documentation}. - - The interactive declaration is a list of the form @code{(interactive -@var{code-string})}. This declares how to provide arguments if the -function is used interactively. Functions with this declaration are called -@dfn{commands}; they can be called using @kbd{M-x} or bound to a key. -Functions not intended to be called in this way should not have interactive -declarations. @xref{Defining Commands}, for how to write an interactive -declaration. - -@cindex body of function - The rest of the elements are the @dfn{body} of the function: the Lisp -code to do the work of the function (or, as a Lisp programmer would say, -``a list of Lisp forms to evaluate''). The value returned by the -function is the value returned by the last element of the body. - -@node Simple Lambda -@subsection A Simple Lambda Expression Example - - Consider the following example: - -@example -(lambda (a b c) (+ a b c)) -@end example - -@noindent -We can call this function by passing it to @code{funcall}, like this: - -@example -@group -(funcall (lambda (a b c) (+ a b c)) - 1 2 3) -@end group -@end example - -@noindent -This call evaluates the body of the lambda expression with the variable -@code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3. -Evaluation of the body adds these three numbers, producing the result 6; -therefore, this call to the function returns the value 6. - - Note that the arguments can be the results of other function calls, as in -this example: - -@example -@group -(funcall (lambda (a b c) (+ a b c)) - 1 (* 2 3) (- 5 4)) -@end group -@end example - -@noindent -This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5 -4)} from left to right. Then it applies the lambda expression to the -argument values 1, 6 and 1 to produce the value 8. - - As these examples show, you can use a form with a lambda expression -as its @sc{car} to make local variables and give them values. In the -old days of Lisp, this technique was the only way to bind and -initialize local variables. But nowadays, it is clearer to use the -special form @code{let} for this purpose (@pxref{Local Variables}). -Lambda expressions are mainly used as anonymous functions for passing -as arguments to other functions (@pxref{Anonymous Functions}), or -stored as symbol function definitions to produce named functions -(@pxref{Function Names}). - -@node Argument List -@subsection Other Features of Argument Lists -@kindex wrong-number-of-arguments -@cindex argument binding -@cindex binding arguments -@cindex argument lists, features - - Our simple sample function, @code{(lambda (a b c) (+ a b c))}, -specifies three argument variables, so it must be called with three -arguments: if you try to call it with only two arguments or four -arguments, you get a @code{wrong-number-of-arguments} error. - - It is often convenient to write a function that allows certain -arguments to be omitted. For example, the function @code{substring} -accepts three arguments---a string, the start index and the end -index---but the third argument defaults to the @var{length} of the -string if you omit it. It is also convenient for certain functions to -accept an indefinite number of arguments, as the functions @code{list} -and @code{+} do. - -@cindex optional arguments -@cindex rest arguments -@kindex &optional -@kindex &rest - To specify optional arguments that may be omitted when a function -is called, simply include the keyword @code{&optional} before the optional -arguments. To specify a list of zero or more extra arguments, include the -keyword @code{&rest} before one final argument. - - Thus, the complete syntax for an argument list is as follows: - -@example -@group -(@var{required-vars}@dots{} - @r{[}&optional @var{optional-vars}@dots{}@r{]} - @r{[}&rest @var{rest-var}@r{]}) -@end group -@end example - -@noindent -The square brackets indicate that the @code{&optional} and @code{&rest} -clauses, and the variables that follow them, are optional. - - A call to the function requires one actual argument for each of the -@var{required-vars}. There may be actual arguments for zero or more of -the @var{optional-vars}, and there cannot be any actual arguments beyond -that unless the lambda list uses @code{&rest}. In that case, there may -be any number of extra actual arguments. - - If actual arguments for the optional and rest variables are omitted, -then they always default to @code{nil}. There is no way for the -function to distinguish between an explicit argument of @code{nil} and -an omitted argument. However, the body of the function is free to -consider @code{nil} an abbreviation for some other meaningful value. -This is what @code{substring} does; @code{nil} as the third argument to -@code{substring} means to use the length of the string supplied. - -@cindex CL note---default optional arg -@quotation -@b{Common Lisp note:} Common Lisp allows the function to specify what -default value to use when an optional argument is omitted; Emacs Lisp -always uses @code{nil}. Emacs Lisp does not support ``supplied-p'' -variables that tell you whether an argument was explicitly passed. -@end quotation - - For example, an argument list that looks like this: - -@example -(a b &optional c d &rest e) -@end example - -@noindent -binds @code{a} and @code{b} to the first two actual arguments, which are -required. If one or two more arguments are provided, @code{c} and -@code{d} are bound to them respectively; any arguments after the first -four are collected into a list and @code{e} is bound to that list. If -there are only two arguments, @code{c} is @code{nil}; if two or three -arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e} -is @code{nil}. - - There is no way to have required arguments following optional -ones---it would not make sense. To see why this must be so, suppose -that @code{c} in the example were optional and @code{d} were required. -Suppose three actual arguments are given; which variable would the -third argument be for? Would it be used for the @var{c}, or for -@var{d}? One can argue for both possibilities. Similarly, it makes -no sense to have any more arguments (either required or optional) -after a @code{&rest} argument. - - Here are some examples of argument lists and proper calls: - -@example -(funcall (lambda (n) (1+ n)) ; @r{One required:} - 1) ; @r{requires exactly one argument.} - @result{} 2 -(funcall (lambda (n &optional n1) ; @r{One required and one optional:} - (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.} - 1 2) - @result{} 3 -(funcall (lambda (n &rest ns) ; @r{One required and one rest:} - (+ n (apply '+ ns))) ; @r{1 or more arguments.} - 1 2 3 4 5) - @result{} 15 -@end example - -@node Function Documentation -@subsection Documentation Strings of Functions -@cindex documentation of function - - A lambda expression may optionally have a @dfn{documentation string} -just after the lambda list. This string does not affect execution of -the function; it is a kind of comment, but a systematized comment -which actually appears inside the Lisp world and can be used by the -Emacs help facilities. @xref{Documentation}, for how the -documentation string is accessed. - - It is a good idea to provide documentation strings for all the -functions in your program, even those that are called only from within -your program. Documentation strings are like comments, except that they -are easier to access. - - The first line of the documentation string should stand on its own, -because @code{apropos} displays just this first line. It should consist -of one or two complete sentences that summarize the function's purpose. - - The start of the documentation string is usually indented in the -source file, but since these spaces come before the starting -double-quote, they are not part of the string. Some people make a -practice of indenting any additional lines of the string so that the -text lines up in the program source. @emph{That is a mistake.} The -indentation of the following lines is inside the string; what looks -nice in the source code will look ugly when displayed by the help -commands. - - You may wonder how the documentation string could be optional, since -there are required components of the function that follow it (the body). -Since evaluation of a string returns that string, without any side effects, -it has no effect if it is not the last form in the body. Thus, in -practice, there is no confusion between the first form of the body and the -documentation string; if the only body form is a string then it serves both -as the return value and as the documentation. - - The last line of the documentation string can specify calling -conventions different from the actual function arguments. Write -text like this: - -@example -\(fn @var{arglist}) -@end example - -@noindent -following a blank line, at the beginning of the line, with no newline -following it inside the documentation string. (The @samp{\} is used -to avoid confusing the Emacs motion commands.) The calling convention -specified in this way appears in help messages in place of the one -derived from the actual arguments of the function. - - This feature is particularly useful for macro definitions, since the -arguments written in a macro definition often do not correspond to the -way users think of the parts of the macro call. - -@node Function Names -@section Naming a Function -@cindex function definition -@cindex named function -@cindex function name - - A symbol can serve as the name of a function. This happens when the -symbol's @dfn{function cell} (@pxref{Symbol Components}) contains a -function object (e.g.@: a lambda expression). Then the symbol itself -becomes a valid, callable function, equivalent to the function object -in its function cell. - - The contents of the function cell are also called the symbol's -@dfn{function definition}. The procedure of using a symbol's function -definition in place of the symbol is called @dfn{symbol function -indirection}; see @ref{Function Indirection}. If you have not given a -symbol a function definition, its function cell is said to be -@dfn{void}, and it cannot be used as a function. - - In practice, nearly all functions have names, and are referred to by -their names. You can create a named Lisp function by defining a -lambda expression and putting it in a function cell (@pxref{Function -Cells}). However, it is more common to use the @code{defun} special -form, described in the next section. -@ifnottex -@xref{Defining Functions}. -@end ifnottex - - We give functions names because it is convenient to refer to them by -their names in Lisp expressions. Also, a named Lisp function can -easily refer to itself---it can be recursive. Furthermore, primitives -can only be referred to textually by their names, since primitive -function objects (@pxref{Primitive Function Type}) have no read -syntax. - - A function need not have a unique name. A given function object -@emph{usually} appears in the function cell of only one symbol, but -this is just a convention. It is easy to store it in several symbols -using @code{fset}; then each of the symbols is a valid name for the -same function. - - Note that a symbol used as a function name may also be used as a -variable; these two uses of a symbol are independent and do not -conflict. (This is not the case in some dialects of Lisp, like -Scheme.) - -@node Defining Functions -@section Defining Functions -@cindex defining a function - - We usually give a name to a function when it is first created. This -is called @dfn{defining a function}, and it is done with the -@code{defun} special form. - -@defspec defun name argument-list body-forms... -@code{defun} is the usual way to define new Lisp functions. It -defines the symbol @var{name} as a function that looks like this: - -@example -(lambda @var{argument-list} . @var{body-forms}) -@end example - -@code{defun} stores this lambda expression in the function cell of -@var{name}. It returns the value @var{name}, but usually we ignore this -value. - -As described previously, @var{argument-list} is a list of argument -names and may include the keywords @code{&optional} and @code{&rest}. -Also, the first two of the @var{body-forms} may be a documentation -string and an interactive declaration. @xref{Lambda Components}. - -Here are some examples: - -@example -@group -(defun foo () 5) - @result{} foo -@end group -@group -(foo) - @result{} 5 -@end group - -@group -(defun bar (a &optional b &rest c) - (list a b c)) - @result{} bar -@end group -@group -(bar 1 2 3 4 5) - @result{} (1 2 (3 4 5)) -@end group -@group -(bar 1) - @result{} (1 nil nil) -@end group -@group -(bar) -@error{} Wrong number of arguments. -@end group - -@group -(defun capitalize-backwards () - "Upcase the last letter of the word at point." - (interactive) - (backward-word 1) - (forward-word 1) - (backward-char 1) - (capitalize-word 1)) - @result{} capitalize-backwards -@end group -@end example - -Be careful not to redefine existing functions unintentionally. -@code{defun} redefines even primitive functions such as @code{car} -without any hesitation or notification. Emacs does not prevent you -from doing this, because redefining a function is sometimes done -deliberately, and there is no way to distinguish deliberate -redefinition from unintentional redefinition. -@end defspec - -@cindex function aliases -@defun defalias name definition &optional docstring -@anchor{Definition of defalias} -This special form defines the symbol @var{name} as a function, with -definition @var{definition} (which can be any valid Lisp function). -It returns @var{definition}. - -If @var{docstring} is non-@code{nil}, it becomes the function -documentation of @var{name}. Otherwise, any documentation provided by -@var{definition} is used. - -The proper place to use @code{defalias} is where a specific function -name is being defined---especially where that name appears explicitly in -the source file being loaded. This is because @code{defalias} records -which file defined the function, just like @code{defun} -(@pxref{Unloading}). - -By contrast, in programs that manipulate function definitions for other -purposes, it is better to use @code{fset}, which does not keep such -records. @xref{Function Cells}. -@end defun - - You cannot create a new primitive function with @code{defun} or -@code{defalias}, but you can use them to change the function definition of -any symbol, even one such as @code{car} or @code{x-popup-menu} whose -normal definition is a primitive. However, this is risky: for -instance, it is next to impossible to redefine @code{car} without -breaking Lisp completely. Redefining an obscure function such as -@code{x-popup-menu} is less dangerous, but it still may not work as -you expect. If there are calls to the primitive from C code, they -call the primitive's C definition directly, so changing the symbol's -definition will have no effect on them. - - See also @code{defsubst}, which defines a function like @code{defun} -and tells the Lisp compiler to perform inline expansion on it. -@xref{Inline Functions}. - -@node Calling Functions -@section Calling Functions -@cindex function invocation -@cindex calling a function - - Defining functions is only half the battle. Functions don't do -anything until you @dfn{call} them, i.e., tell them to run. Calling a -function is also known as @dfn{invocation}. - - The most common way of invoking a function is by evaluating a list. -For example, evaluating the list @code{(concat "a" "b")} calls the -function @code{concat} with arguments @code{"a"} and @code{"b"}. -@xref{Evaluation}, for a description of evaluation. - - When you write a list as an expression in your program, you specify -which function to call, and how many arguments to give it, in the text -of the program. Usually that's just what you want. Occasionally you -need to compute at run time which function to call. To do that, use -the function @code{funcall}. When you also need to determine at run -time how many arguments to pass, use @code{apply}. - -@defun funcall function &rest arguments -@code{funcall} calls @var{function} with @var{arguments}, and returns -whatever @var{function} returns. - -Since @code{funcall} is a function, all of its arguments, including -@var{function}, are evaluated before @code{funcall} is called. This -means that you can use any expression to obtain the function to be -called. It also means that @code{funcall} does not see the -expressions you write for the @var{arguments}, only their values. -These values are @emph{not} evaluated a second time in the act of -calling @var{function}; the operation of @code{funcall} is like the -normal procedure for calling a function, once its arguments have -already been evaluated. - -The argument @var{function} must be either a Lisp function or a -primitive function. Special forms and macros are not allowed, because -they make sense only when given the ``unevaluated'' argument -expressions. @code{funcall} cannot provide these because, as we saw -above, it never knows them in the first place. - -@example -@group -(setq f 'list) - @result{} list -@end group -@group -(funcall f 'x 'y 'z) - @result{} (x y z) -@end group -@group -(funcall f 'x 'y '(z)) - @result{} (x y (z)) -@end group -@group -(funcall 'and t nil) -@error{} Invalid function: # -@end group -@end example - -Compare these examples with the examples of @code{apply}. -@end defun - -@defun apply function &rest arguments -@code{apply} calls @var{function} with @var{arguments}, just like -@code{funcall} but with one difference: the last of @var{arguments} is a -list of objects, which are passed to @var{function} as separate -arguments, rather than a single list. We say that @code{apply} -@dfn{spreads} this list so that each individual element becomes an -argument. - -@code{apply} returns the result of calling @var{function}. As with -@code{funcall}, @var{function} must either be a Lisp function or a -primitive function; special forms and macros do not make sense in -@code{apply}. - -@example -@group -(setq f 'list) - @result{} list -@end group -@group -(apply f 'x 'y 'z) -@error{} Wrong type argument: listp, z -@end group -@group -(apply '+ 1 2 '(3 4)) - @result{} 10 -@end group -@group -(apply '+ '(1 2 3 4)) - @result{} 10 -@end group - -@group -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end group -@end example - -For an interesting example of using @code{apply}, see @ref{Definition -of mapcar}. -@end defun - -@cindex partial application of functions -@cindex currying - Sometimes it is useful to fix some of the function's arguments at -certain values, and leave the rest of arguments for when the function -is actually called. The act of fixing some of the function's -arguments is called @dfn{partial application} of the function@footnote{ -This is related to, but different from @dfn{currying}, which -transforms a function that takes multiple arguments in such a way that -it can be called as a chain of functions, each one with a single -argument.}. -The result is a new function that accepts the rest of -arguments and calls the original function with all the arguments -combined. - - Here's how to do partial application in Emacs Lisp: - -@defun apply-partially func &rest args -This function returns a new function which, when called, will call -@var{func} with the list of arguments composed from @var{args} and -additional arguments specified at the time of the call. If @var{func} -accepts @var{n} arguments, then a call to @code{apply-partially} with -@w{@code{@var{m} < @var{n}}} arguments will produce a new function of -@w{@code{@var{n} - @var{m}}} arguments. - -Here's how we could define the built-in function @code{1+}, if it -didn't exist, using @code{apply-partially} and @code{+}, another -built-in function: - -@example -@group -(defalias '1+ (apply-partially '+ 1) - "Increment argument by one.") -@end group -@group -(1+ 10) - @result{} 11 -@end group -@end example -@end defun - -@cindex functionals - It is common for Lisp functions to accept functions as arguments or -find them in data structures (especially in hook variables and property -lists) and call them using @code{funcall} or @code{apply}. Functions -that accept function arguments are often called @dfn{functionals}. - - Sometimes, when you call a functional, it is useful to supply a no-op -function as the argument. Here are two different kinds of no-op -function: - -@defun identity arg -This function returns @var{arg} and has no side effects. -@end defun - -@defun ignore &rest args -This function ignores any arguments and returns @code{nil}. -@end defun - - Some functions are user-visible @dfn{commands}, which can be called -interactively (usually by a key sequence). It is possible to invoke -such a command exactly as though it was called interactively, by using -the @code{call-interactively} function. @xref{Interactive Call}. - -@node Mapping Functions -@section Mapping Functions -@cindex mapping functions - - A @dfn{mapping function} applies a given function (@emph{not} a -special form or macro) to each element of a list or other collection. -Emacs Lisp has several such functions; this section describes -@code{mapcar}, @code{mapc}, and @code{mapconcat}, which map over a -list. @xref{Definition of mapatoms}, for the function @code{mapatoms} -which maps over the symbols in an obarray. @xref{Definition of -maphash}, for the function @code{maphash} which maps over key/value -associations in a hash table. - - These mapping functions do not allow char-tables because a char-table -is a sparse array whose nominal range of indices is very large. To map -over a char-table in a way that deals properly with its sparse nature, -use the function @code{map-char-table} (@pxref{Char-Tables}). - -@defun mapcar function sequence -@anchor{Definition of mapcar} -@code{mapcar} applies @var{function} to each element of @var{sequence} -in turn, and returns a list of the results. - -The argument @var{sequence} can be any kind of sequence except a -char-table; that is, a list, a vector, a bool-vector, or a string. The -result is always a list. The length of the result is the same as the -length of @var{sequence}. For example: - -@example -@group -(mapcar 'car '((a b) (c d) (e f))) - @result{} (a c e) -(mapcar '1+ [1 2 3]) - @result{} (2 3 4) -(mapcar 'string "abc") - @result{} ("a" "b" "c") -@end group - -@group -;; @r{Call each function in @code{my-hooks}.} -(mapcar 'funcall my-hooks) -@end group - -@group -(defun mapcar* (function &rest args) - "Apply FUNCTION to successive cars of all ARGS. -Return the list of results." - ;; @r{If no list is exhausted,} - (if (not (memq nil args)) - ;; @r{apply function to @sc{car}s.} - (cons (apply function (mapcar 'car args)) - (apply 'mapcar* function - ;; @r{Recurse for rest of elements.} - (mapcar 'cdr args))))) -@end group - -@group -(mapcar* 'cons '(a b c) '(1 2 3 4)) - @result{} ((a . 1) (b . 2) (c . 3)) -@end group -@end example -@end defun - -@defun mapc function sequence -@code{mapc} is like @code{mapcar} except that @var{function} is used for -side-effects only---the values it returns are ignored, not collected -into a list. @code{mapc} always returns @var{sequence}. -@end defun - -@defun mapconcat function sequence separator -@code{mapconcat} applies @var{function} to each element of -@var{sequence}: the results, which must be strings, are concatenated. -Between each pair of result strings, @code{mapconcat} inserts the string -@var{separator}. Usually @var{separator} contains a space or comma or -other suitable punctuation. - -The argument @var{function} must be a function that can take one -argument and return a string. The argument @var{sequence} can be any -kind of sequence except a char-table; that is, a list, a vector, a -bool-vector, or a string. - -@example -@group -(mapconcat 'symbol-name - '(The cat in the hat) - " ") - @result{} "The cat in the hat" -@end group - -@group -(mapconcat (function (lambda (x) (format "%c" (1+ x)))) - "HAL-8000" - "") - @result{} "IBM.9111" -@end group -@end example -@end defun - -@node Anonymous Functions -@section Anonymous Functions -@cindex anonymous function - - Although functions are usually defined with @code{defun} and given -names at the same time, it is sometimes convenient to use an explicit -lambda expression---an @dfn{anonymous function}. Anonymous functions -are valid wherever function names are. They are often assigned as -variable values, or as arguments to functions; for instance, you might -pass one as the @var{function} argument to @code{mapcar}, which -applies that function to each element of a list (@pxref{Mapping -Functions}). @xref{describe-symbols example}, for a realistic example -of this. - - When defining a lambda expression that is to be used as an anonymous -function, you can in principle use any method to construct the list. -But typically you should use the @code{lambda} macro, or the -@code{function} special form, or the @code{#'} read syntax: - -@defmac lambda args body... -This macro returns an anonymous function with argument list @var{args} -and body forms given by @var{body}. In effect, this macro makes -@code{lambda} forms ``self-quoting'': evaluating a form whose @sc{car} -is @code{lambda} yields the form itself: - -@example -(lambda (x) (* x x)) - @result{} (lambda (x) (* x x)) -@end example - -The @code{lambda} form has one other effect: it tells the Emacs -evaluator and byte-compiler that its argument is a function, by using -@code{function} as a subroutine (see below). -@end defmac - -@defspec function function-object -@cindex function quoting -This special form returns @var{function-object} without evaluating it. -In this, it is similar to @code{quote} (@pxref{Quoting}). But unlike -@code{quote}, it also serves as a note to the Emacs evaluator and -byte-compiler that @var{function-object} is intended to be used as a -function. Assuming @var{function-object} is a valid lambda -expression, this has two effects: - -@itemize -@item -When the code is byte-compiled, @var{function-object} is compiled into -a byte-code function object (@pxref{Byte Compilation}). - -@item -When lexical binding is enabled, @var{function-object} is converted -into a closure. @xref{Closures}. -@end itemize -@end defspec - -@cindex @samp{#'} syntax -The read syntax @code{#'} is a short-hand for using @code{function}. -The following forms are all equivalent: - -@example -(lambda (x) (* x x)) -(function (lambda (x) (* x x))) -#'(lambda (x) (* x x)) -@end example - - In the following example, we define a @code{change-property} -function that takes a function as its third argument, followed by a -@code{double-property} function that makes use of -@code{change-property} by passing it an anonymous function: - -@example -@group -(defun change-property (symbol prop function) - (let ((value (get symbol prop))) - (put symbol prop (funcall function value)))) -@end group - -@group -(defun double-property (symbol prop) - (change-property symbol prop (lambda (x) (* 2 x)))) -@end group -@end example - -@noindent -Note that we do not quote the @code{lambda} form. - - If you compile the above code, the anonymous function is also -compiled. This would not happen if, say, you had constructed the -anonymous function by quoting it as a list: - -@example -@group -(defun double-property (symbol prop) - (change-property symbol prop '(lambda (x) (* 2 x)))) -@end group -@end example - -@noindent -In that case, the anonymous function is kept as a lambda expression in -the compiled code. The byte-compiler cannot assume this list is a -function, even though it looks like one, since it does not know that -@code{change-property} intends to use it as a function. - -@node Function Cells -@section Accessing Function Cell Contents - - The @dfn{function definition} of a symbol is the object stored in the -function cell of the symbol. The functions described here access, test, -and set the function cell of symbols. - - See also the function @code{indirect-function}. @xref{Definition of -indirect-function}. - -@defun symbol-function symbol -@kindex void-function -This returns the object in the function cell of @var{symbol}. If the -symbol's function cell is void, a @code{void-function} error is -signaled. - -This function does not check that the returned object is a legitimate -function. - -@example -@group -(defun bar (n) (+ n 2)) - @result{} bar -@end group -@group -(symbol-function 'bar) - @result{} (lambda (n) (+ n 2)) -@end group -@group -(fset 'baz 'bar) - @result{} bar -@end group -@group -(symbol-function 'baz) - @result{} bar -@end group -@end example -@end defun - -@cindex void function cell - If you have never given a symbol any function definition, we say that -that symbol's function cell is @dfn{void}. In other words, the function -cell does not have any Lisp object in it. If you try to call such a symbol -as a function, it signals a @code{void-function} error. - - Note that void is not the same as @code{nil} or the symbol -@code{void}. The symbols @code{nil} and @code{void} are Lisp objects, -and can be stored into a function cell just as any other object can be -(and they can be valid functions if you define them in turn with -@code{defun}). A void function cell contains no object whatsoever. - - You can test the voidness of a symbol's function definition with -@code{fboundp}. After you have given a symbol a function definition, you -can make it void once more using @code{fmakunbound}. - -@defun fboundp symbol -This function returns @code{t} if the symbol has an object in its -function cell, @code{nil} otherwise. It does not check that the object -is a legitimate function. -@end defun - -@defun fmakunbound symbol -This function makes @var{symbol}'s function cell void, so that a -subsequent attempt to access this cell will cause a -@code{void-function} error. It returns @var{symbol}. (See also -@code{makunbound}, in @ref{Void Variables}.) - -@example -@group -(defun foo (x) x) - @result{} foo -@end group -@group -(foo 1) - @result{}1 -@end group -@group -(fmakunbound 'foo) - @result{} foo -@end group -@group -(foo 1) -@error{} Symbol's function definition is void: foo -@end group -@end example -@end defun - -@defun fset symbol definition -This function stores @var{definition} in the function cell of -@var{symbol}. The result is @var{definition}. Normally -@var{definition} should be a function or the name of a function, but -this is not checked. The argument @var{symbol} is an ordinary evaluated -argument. - -The primary use of this function is as a subroutine by constructs that -define or alter functions, like @code{defadvice} (@pxref{Advising -Functions}). (If @code{defun} were not a primitive, it could be -written as a Lisp macro using @code{fset}.) You can also use it to -give a symbol a function definition that is not a list, e.g.@: a -keyboard macro (@pxref{Keyboard Macros}): - -@example -;; @r{Define a named keyboard macro.} -(fset 'kill-two-lines "\^u2\^k") - @result{} "\^u2\^k" -@end example - -It you wish to use @code{fset} to make an alternate name for a -function, consider using @code{defalias} instead. @xref{Definition of -defalias}. -@end defun - -@node Closures -@section Closures - - As explained in @ref{Variable Scoping}, Emacs can optionally enable -lexical binding of variables. When lexical binding is enabled, any -named function that you create (e.g.@: with @code{defun}), as well as -any anonymous function that you create using the @code{lambda} macro -or the @code{function} special form or the @code{#'} syntax -(@pxref{Anonymous Functions}), is automatically converted into a -closure. - - A closure is a function that also carries a record of the lexical -environment that existed when the function was defined. When it is -invoked, any lexical variable references within its definition use the -retained lexical environment. In all other respects, closures behave -much like ordinary functions; in particular, they can be called in the -same way as ordinary functions. - - @xref{Lexical Binding}, for an example of using a closure. - - Currently, an Emacs Lisp closure object is represented by a list -with the symbol @code{closure} as the first element, a list -representing the lexical environment as the second element, and the -argument list and body forms as the remaining elements: - -@example -;; @r{lexical binding is enabled.} -(lambda (x) (* x x)) - @result{} (closure (t) (x) (* x x)) -@end example - -@noindent -However, the fact that the internal structure of a closure is -``exposed'' to the rest of the Lisp world is considered an internal -implementation detail. For this reason, we recommend against directly -examining or altering the structure of closure objects. - -@node Obsolete Functions -@section Declaring Functions Obsolete - -You can use @code{make-obsolete} to declare a function obsolete. This -indicates that the function may be removed at some stage in the future. - -@defun make-obsolete obsolete-name current-name &optional when -This function makes the byte compiler warn that the function -@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the -warning message says to use @var{current-name} instead of -@var{obsolete-name}. @var{current-name} does not need to be an alias for -@var{obsolete-name}; it can be a different function with similar -functionality. If @var{current-name} is a string, it is the warning -message. - -If provided, @var{when} should be a string indicating when the function -was first made obsolete---for example, a date or a release number. -@end defun - -You can define a function as an alias and declare it obsolete at the -same time using the macro @code{define-obsolete-function-alias}: - -@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring -This macro marks the function @var{obsolete-name} obsolete and also -defines it as an alias for the function @var{current-name}. It is -equivalent to the following: - -@example -(defalias @var{obsolete-name} @var{current-name} @var{docstring}) -(make-obsolete @var{obsolete-name} @var{current-name} @var{when}) -@end example -@end defmac - -In addition, you can mark a certain a particular calling convention -for a function as obsolete: - -@defun set-advertised-calling-convention function signature when -This function specifies the argument list @var{signature} as the -correct way to call @var{function}. This causes the Emacs byte -compiler to issue a warning whenever it comes across an Emacs Lisp -program that calls @var{function} any other way (however, it will -still allow the code to be byte compiled). @var{when} should be a -string indicating when the variable was first made obsolete (usually a -version number string). - -For instance, in old versions of Emacs the @code{sit-for} function -accepted three arguments, like this - -@example - (sit-for seconds milliseconds nodisp) -@end example - -However, calling @code{sit-for} this way is considered obsolete -(@pxref{Waiting}). The old calling convention is deprecated like -this: - -@example -(set-advertised-calling-convention - 'sit-for '(seconds &optional nodisp) "22.1") -@end example -@end defun - -@node Inline Functions -@section Inline Functions -@cindex inline functions - -@defmac defsubst name argument-list body-forms... -Define an inline function. The syntax is exactly the same as -@code{defun} (@pxref{Defining Functions}). -@end defmac - - You can define an @dfn{inline function} by using @code{defsubst} -instead of @code{defun}. An inline function works just like an -ordinary function except for one thing: when you byte-compile a call -to the function (@pxref{Byte Compilation}), the function's definition -is expanded into the caller. - - Making a function inline often makes its function calls run faster. -But it also has disadvantages. For one thing, it reduces flexibility; -if you change the definition of the function, calls already inlined -still use the old definition until you recompile them. - - Another disadvantage is that making a large function inline can -increase the size of compiled code both in files and in memory. Since -the speed advantage of inline functions is greatest for small -functions, you generally should not make large functions inline. - - Also, inline functions do not behave well with respect to debugging, -tracing, and advising (@pxref{Advising Functions}). Since ease of -debugging and the flexibility of redefining functions are important -features of Emacs, you should not make a function inline, even if it's -small, unless its speed is really crucial, and you've timed the code -to verify that using @code{defun} actually has performance problems. - - It's possible to define a macro to expand into the same code that an -inline function would execute (@pxref{Macros}). But the macro would -be limited to direct use in expressions---a macro cannot be called -with @code{apply}, @code{mapcar} and so on. Also, it takes some work -to convert an ordinary function into a macro. To convert it into an -inline function is easy; just replace @code{defun} with -@code{defsubst}. Since each argument of an inline function is -evaluated exactly once, you needn't worry about how many times the -body uses the arguments, as you do for macros. - - After an inline function is defined, its inline expansion can be -performed later on in the same file, just like macros. - -@node Declaring Functions -@section Telling the Compiler that a Function is Defined -@cindex function declaration -@cindex declaring functions -@findex declare-function - -Byte-compiling a file often produces warnings about functions that the -compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this -indicates a real problem, but usually the functions in question are -defined in other files which would be loaded if that code is run. For -example, byte-compiling @file{fortran.el} used to warn: - -@example -In end of data: -fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known - to be defined. -@end example - -In fact, @code{gud-find-c-expr} is only used in the function that -Fortran mode uses for the local value of -@code{gud-find-expr-function}, which is a callback from GUD; if it is -called, the GUD functions will be loaded. When you know that such a -warning does not indicate a real problem, it is good to suppress the -warning. That makes new warnings which might mean real problems more -visible. You do that with @code{declare-function}. - -All you need to do is add a @code{declare-function} statement before the -first use of the function in question: - -@example -(declare-function gud-find-c-expr "gud.el" nil) -@end example - -This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the -@samp{.el} can be omitted). The compiler takes for granted that that file -really defines the function, and does not check. - - The optional third argument specifies the argument list of -@code{gud-find-c-expr}. In this case, it takes no arguments -(@code{nil} is different from not specifying a value). In other -cases, this might be something like @code{(file &optional overwrite)}. -You don't have to specify the argument list, but if you do the -byte compiler can check that the calls match the declaration. - -@defmac declare-function function file &optional arglist fileonly -Tell the byte compiler to assume that @var{function} is defined, with -arguments @var{arglist}, and that the definition should come from the -file @var{file}. @var{fileonly} non-@code{nil} means only check that -@var{file} exists, not that it actually defines @var{function}. -@end defmac - - To verify that these functions really are declared where -@code{declare-function} says they are, use @code{check-declare-file} -to check all @code{declare-function} calls in one source file, or use -@code{check-declare-directory} check all the files in and under a -certain directory. - - These commands find the file that ought to contain a function's -definition using @code{locate-library}; if that finds no file, they -expand the definition file name relative to the directory of the file -that contains the @code{declare-function} call. - - You can also say that a function is a primitive by specifying a file -name ending in @samp{.c} or @samp{.m}. This is useful only when you -call a primitive that is defined only on certain systems. Most -primitives are always defined, so they will never give you a warning. - - Sometimes a file will optionally use functions from an external package. -If you prefix the filename in the @code{declare-function} statement with -@samp{ext:}, then it will be checked if it is found, otherwise skipped -without error. - - There are some function definitions that @samp{check-declare} does not -understand (e.g. @code{defstruct} and some other macros). In such cases, -you can pass a non-@code{nil} @var{fileonly} argument to -@code{declare-function}, meaning to only check that the file exists, not -that it actually defines the function. Note that to do this without -having to specify an argument list, you should set the @var{arglist} -argument to @code{t} (because @code{nil} means an empty argument list, as -opposed to an unspecified one). - -@node Function Safety -@section Determining whether a Function is Safe to Call -@cindex function safety -@cindex safety of functions - -Some major modes such as SES call functions that are stored in user -files. (@inforef{Top, ,ses}, for more information on SES.) User -files sometimes have poor pedigrees---you can get a spreadsheet from -someone you've just met, or you can get one through email from someone -you've never met. So it is risky to call a function whose source code -is stored in a user file until you have determined that it is safe. - -@defun unsafep form &optional unsafep-vars -Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or -returns a list that describes why it might be unsafe. The argument -@var{unsafep-vars} is a list of symbols known to have temporary -bindings at this point; it is mainly used for internal recursive -calls. The current buffer is an implicit argument, which provides a -list of buffer-local bindings. -@end defun - -Being quick and simple, @code{unsafep} does a very light analysis and -rejects many Lisp expressions that are actually safe. There are no -known cases where @code{unsafep} returns @code{nil} for an unsafe -expression. However, a ``safe'' Lisp expression can return a string -with a @code{display} property, containing an associated Lisp -expression to be executed after the string is inserted into a buffer. -This associated expression can be a virus. In order to be safe, you -must delete properties from all strings calculated by user code before -inserting them into buffers. - -@ignore -What is a safe Lisp expression? Basically, it's an expression that -calls only built-in functions with no side effects (or only innocuous -ones). Innocuous side effects include displaying messages and -altering non-risky buffer-local variables (but not global variables). - -@table @dfn -@item Safe expression -@itemize -@item -An atom or quoted thing. -@item -A call to a safe function (see below), if all its arguments are -safe expressions. -@item -One of the special forms @code{and}, @code{catch}, @code{cond}, -@code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn}, -@code{while}, and @code{unwind-protect}], if all its arguments are -safe. -@item -A form that creates temporary bindings (@code{condition-case}, -@code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or -@code{let*}), if all args are safe and the symbols to be bound are not -explicitly risky (see @pxref{File Local Variables}). -@item -An assignment using @code{add-to-list}, @code{setq}, @code{push}, or -@code{pop}, if all args are safe and the symbols to be assigned are -not explicitly risky and they already have temporary or buffer-local -bindings. -@item -One of [apply, mapc, mapcar, mapconcat] if the first argument is a -safe explicit lambda and the other args are safe expressions. -@end itemize - -@item Safe function -@itemize -@item -A lambda containing safe expressions. -@item -A symbol on the list @code{safe-functions}, so the user says it's safe. -@item -A symbol with a non-@code{nil} @code{side-effect-free} property. -@item -A symbol with a non-@code{nil} @code{safe-function} property. The -value @code{t} indicates a function that is safe but has innocuous -side effects. Other values will someday indicate functions with -classes of side effects that are not always safe. -@end itemize - -The @code{side-effect-free} and @code{safe-function} properties are -provided for built-in functions and for low-level functions and macros -defined in @file{subr.el}. You can assign these properties for the -functions you write. -@end table -@end ignore - -@node Related Topics -@section Other Topics Related to Functions - - Here is a table of several functions that do things related to -function calling and function definitions. They are documented -elsewhere, but we provide cross references here. - -@table @code -@item apply -See @ref{Calling Functions}. - -@item autoload -See @ref{Autoload}. - -@item call-interactively -See @ref{Interactive Call}. - -@item called-interactively-p -See @ref{Distinguish Interactive}. - -@item commandp -See @ref{Interactive Call}. - -@item documentation -See @ref{Accessing Documentation}. - -@item eval -See @ref{Eval}. - -@item funcall -See @ref{Calling Functions}. - -@item function -See @ref{Anonymous Functions}. - -@item ignore -See @ref{Calling Functions}. - -@item indirect-function -See @ref{Function Indirection}. - -@item interactive -See @ref{Using Interactive}. - -@item interactive-p -See @ref{Distinguish Interactive}. - -@item mapatoms -See @ref{Creating Symbols}. - -@item mapcar -See @ref{Mapping Functions}. - -@item map-char-table -See @ref{Char-Tables}. - -@item mapconcat -See @ref{Mapping Functions}. - -@item undefined -See @ref{Functions for Key Lookup}. -@end table diff --git a/doc/lispref/gpl.texi b/doc/lispref/gpl.texi deleted file mode 100644 index 244f3330d44..00000000000 --- a/doc/lispref/gpl.texi +++ /dev/null @@ -1,723 +0,0 @@ -@c -*-texinfo-*- -@setfilename ../../info/gpl - -@node GPL, Tips, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@appendix GNU General Public License -@c The GNU General Public License. -@center Version 3, 29 June 2007 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. -@end display - -@heading Preamble - -The GNU General Public License is a free, copyleft license for -software and other kinds of works. - -The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom -to share and change all versions of a program---to make sure it remains -free software for all its users. We, the Free Software Foundation, -use the GNU General Public License for most of our software; it -applies also to any other work released this way by its authors. You -can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - -To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you -have certain responsibilities if you distribute copies of the -software, or if you modify it: responsibilities to respect the freedom -of others. - -For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, -receive or can get the source code. And you must show them these -terms so they know their rights. - -Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - -For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - -Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the -manufacturer can do so. This is fundamentally incompatible with the -aim of protecting users' freedom to change the software. The -systematic pattern of such abuse occurs in the area of products for -individuals to use, which is precisely where it is most unacceptable. -Therefore, we have designed this version of the GPL to prohibit the -practice for those products. If such problems arise substantially in -other domains, we stand ready to extend this provision to those -domains in future versions of the GPL, as needed to protect the -freedom of users. - -Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish -to avoid the special danger that patents applied to a free program -could make it effectively proprietary. To prevent this, the GPL -assures that patents cannot be used to render the program non-free. - -The precise terms and conditions for copying, distribution and -modification follow. - -@heading TERMS AND CONDITIONS - -@enumerate 0 -@item Definitions. - -``This License'' refers to version 3 of the GNU General Public License. - -``Copyright'' also means copyright-like laws that apply to other kinds -of works, such as semiconductor masks. - -``The Program'' refers to any copyrightable work licensed under this -License. Each licensee is addressed as ``you''. ``Licensees'' and -``recipients'' may be individuals or organizations. - -To ``modify'' a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of -an exact copy. The resulting work is called a ``modified version'' of -the earlier work or a work ``based on'' the earlier work. - -A ``covered work'' means either the unmodified Program or a work based -on the Program. - -To ``propagate'' a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - -To ``convey'' a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user -through a computer network, with no transfer of a copy, is not -conveying. - -An interactive user interface displays ``Appropriate Legal Notices'' to -the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - -@item Source Code. - -The ``source code'' for a work means the preferred form of the work for -making modifications to it. ``Object code'' means any non-source form -of a work. - -A ``Standard Interface'' means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - -The ``System Libraries'' of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -``Major Component'', in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - -The ``Corresponding Source'' for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - -The Corresponding Source need not include anything that users can -regenerate automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same -work. - -@item Basic Permissions. - -All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - -You may make, run and propagate covered works that you do not convey, -without conditions so long as your license otherwise remains in force. -You may convey covered works to others for the sole purpose of having -them make modifications exclusively for you, or provide you with -facilities for running those works, provided that you comply with the -terms of this License in conveying all material for which you do not -control copyright. Those thus making or running the covered works for -you must do so exclusively on your behalf, under your direction and -control, on terms that prohibit them from making any copies of your -copyrighted material outside their relationship with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - -@item Protecting Users' Legal Rights From Anti-Circumvention Law. - -No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such -circumvention is effected by exercising rights under this License with -respect to the covered work, and you disclaim any intention to limit -operation or modification of the work as a means of enforcing, against -the work's users, your or third parties' legal rights to forbid -circumvention of technological measures. - -@item Conveying Verbatim Copies. - -You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - -@item Conveying Modified Source Versions. - -You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these -conditions: - -@enumerate a -@item -The work must carry prominent notices stating that you modified it, -and giving a relevant date. - -@item -The work must carry prominent notices stating that it is released -under this License and any conditions added under section 7. This -requirement modifies the requirement in section 4 to ``keep intact all -notices''. - -@item -You must license the entire work, as a whole, under this License to -anyone who comes into possession of a copy. This License will -therefore apply, along with any applicable section 7 additional terms, -to the whole of the work, and all its parts, regardless of how they -are packaged. This License gives no permission to license the work in -any other way, but it does not invalidate such permission if you have -separately received it. - -@item -If the work has interactive user interfaces, each must display -Appropriate Legal Notices; however, if the Program has interactive -interfaces that do not display Appropriate Legal Notices, your work -need not make them do so. -@end enumerate - -A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -``aggregate'' if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -@item Conveying Non-Source Forms. - -You may convey a covered work in object code form under the terms of -sections 4 and 5, provided that you also convey the machine-readable -Corresponding Source under the terms of this License, in one of these -ways: - -@enumerate a -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by the -Corresponding Source fixed on a durable physical medium customarily -used for software interchange. - -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by a written -offer, valid for at least three years and valid for as long as you -offer spare parts or customer support for that product model, to give -anyone who possesses the object code either (1) a copy of the -Corresponding Source for all the software in the product that is -covered by this License, on a durable physical medium customarily used -for software interchange, for a price no more than your reasonable -cost of physically performing this conveying of source, or (2) access -to copy the Corresponding Source from a network server at no charge. - -@item -Convey individual copies of the object code with a copy of the written -offer to provide the Corresponding Source. This alternative is -allowed only occasionally and noncommercially, and only if you -received the object code with such an offer, in accord with subsection -6b. - -@item -Convey the object code by offering access from a designated place -(gratis or for a charge), and offer equivalent access to the -Corresponding Source in the same way through the same place at no -further charge. You need not require recipients to copy the -Corresponding Source along with the object code. If the place to copy -the object code is a network server, the Corresponding Source may be -on a different server (operated by you or a third party) that supports -equivalent copying facilities, provided you maintain clear directions -next to the object code saying where to find the Corresponding Source. -Regardless of what server hosts the Corresponding Source, you remain -obligated to ensure that it is available for as long as needed to -satisfy these requirements. - -@item -Convey the object code using peer-to-peer transmission, provided you -inform other peers where the object code and Corresponding Source of -the work are being offered to the general public at no charge under -subsection 6d. - -@end enumerate - -A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - -A ``User Product'' is either (1) a ``consumer product'', which means any -tangible personal property which is normally used for personal, -family, or household purposes, or (2) anything designed or sold for -incorporation into a dwelling. In determining whether a product is a -consumer product, doubtful cases shall be resolved in favor of -coverage. For a particular product received by a particular user, -``normally used'' refers to a typical or common use of that class of -product, regardless of the status of the particular user or of the way -in which the particular user actually uses, or expects or is expected -to use, the product. A product is a consumer product regardless of -whether the product has substantial commercial, industrial or -non-consumer uses, unless such uses represent the only significant -mode of use of the product. - -``Installation Information'' for a User Product means any methods, -procedures, authorization keys, or other information required to -install and execute modified versions of a covered work in that User -Product from a modified version of its Corresponding Source. The -information must suffice to ensure that the continued functioning of -the modified object code is in no case prevented or interfered with -solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - -The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or -updates for a work that has been modified or installed by the -recipient, or for the User Product in which it has been modified or -installed. Access to a network may be denied when the modification -itself materially and adversely affects the operation of the network -or violates the rules and protocols for communication across the -network. - -Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - -@item Additional Terms. - -``Additional permissions'' are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - -Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders -of that material) supplement the terms of this License with terms: - -@enumerate a -@item -Disclaiming warranty or limiting liability differently from the terms -of sections 15 and 16 of this License; or - -@item -Requiring preservation of specified reasonable legal notices or author -attributions in that material or in the Appropriate Legal Notices -displayed by works containing it; or - -@item -Prohibiting misrepresentation of the origin of that material, or -requiring that modified versions of such material be marked in -reasonable ways as different from the original version; or - -@item -Limiting the use for publicity purposes of names of licensors or -authors of the material; or - -@item -Declining to grant rights under trademark law for use of some trade -names, trademarks, or service marks; or - -@item -Requiring indemnification of licensors and authors of that material by -anyone who conveys the material (or modified versions of it) with -contractual assumptions of liability to the recipient, for any -liability that these contractual assumptions directly impose on those -licensors and authors. -@end enumerate - -All other non-permissive additional terms are considered ``further -restrictions'' within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; the -above requirements apply either way. - -@item Termination. - -You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - -@item Acceptance Not Required for Having Copies. - -You are not required to accept this License in order to receive or run -a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - -@item Automatic Licensing of Downstream Recipients. - -Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - -An ``entity transaction'' is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - -You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - -@item Patents. - -A ``contributor'' is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's ``contributor version''. - -A contributor's ``essential patent claims'' are all patent claims owned -or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, ``control'' includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - -In the following three paragraphs, a ``patent license'' is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To ``grant'' such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - -If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. ``Knowingly relying'' means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - -If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - -A patent license is ``discriminatory'' if it does not include within the -scope of its coverage, prohibits the exercise of, or is conditioned on -the non-exercise of one or more of the rights that are specifically -granted under this License. You may not convey a covered work if you -are a party to an arrangement with a third party that is in the -business of distributing software, under which you make payment to the -third party based on the extent of your activity of conveying the -work, and under which the third party grants, to any of the parties -who would receive the covered work from you, a discriminatory patent -license (a) in connection with copies of the covered work conveyed by -you (or copies made from those copies), or (b) primarily for and in -connection with specific products or compilations that contain the -covered work, unless you entered into that arrangement, or that patent -license was granted, prior to 28 March 2007. - -Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - -@item No Surrender of Others' Freedom. - -If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey -a covered work so as to satisfy simultaneously your obligations under -this License and any other pertinent obligations, then as a -consequence you may not convey it at all. For example, if you agree -to terms that obligate you to collect a royalty for further conveying -from those to whom you convey the Program, the only way you could -satisfy both those terms and this License would be to refrain entirely -from conveying the Program. - -@item Use with the GNU Affero General Public License. - -Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - -@item Revised Versions of this License. - -The Free Software Foundation may publish revised and/or new versions -of the GNU General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies that a certain numbered version of the GNU General Public -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that numbered version or -of any later version published by the Free Software Foundation. If -the Program does not specify a version number of the GNU General -Public License, you may choose any version ever published by the Free -Software Foundation. - -If the Program specifies that a proxy can decide which future versions -of the GNU General Public License can be used, that proxy's public -statement of acceptance of a version permanently authorizes you to -choose that version for the Program. - -Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - -@item Disclaimer of Warranty. - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT -WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND -PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -@item Limitation of Liability. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR -CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT -NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR -LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM -TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER -PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -@item Interpretation of Sections 15 and 16. - -If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - -@end enumerate - -@heading END OF TERMS AND CONDITIONS - -@heading How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or (at -your option) any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see @url{http://www.gnu.org/licenses/}. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - -@smallexample -@var{program} Copyright (C) @var{year} @var{name of author} -This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. -This is free software, and you are welcome to redistribute it -under certain conditions; type @samp{show c} for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, your -program's commands might be different; for a GUI interface, you would -use an ``about box''. - -You should also get your employer (if you work as a programmer) or school, -if any, to sign a ``copyright disclaimer'' for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -@url{http://www.gnu.org/licenses/}. - -The GNU General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use -the GNU Lesser General Public License instead of this License. But -first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi deleted file mode 100644 index 94d9e6e4485..00000000000 --- a/doc/lispref/hash.texi +++ /dev/null @@ -1,356 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/hash -@node Hash Tables, Symbols, Sequences Arrays Vectors, Top -@chapter Hash Tables -@cindex hash tables -@cindex lookup tables - - A hash table is a very fast kind of lookup table, somewhat like an -alist (@pxref{Association Lists}) in that it maps keys to -corresponding values. It differs from an alist in these ways: - -@itemize @bullet -@item -Lookup in a hash table is extremely fast for large tables---in fact, the -time required is essentially @emph{independent} of how many elements are -stored in the table. For smaller tables (a few tens of elements) -alists may still be faster because hash tables have a more-or-less -constant overhead. - -@item -The correspondences in a hash table are in no particular order. - -@item -There is no way to share structure between two hash tables, -the way two alists can share a common tail. -@end itemize - - Emacs Lisp provides a general-purpose hash table data type, along -with a series of functions for operating on them. Hash tables have a -special printed representation, which consists of @samp{#s} followed -by a list specifying the hash table properties and contents. -@xref{Creating Hash}. (Note that the term ``hash notation'', which -refers to the initial @samp{#} character used in the printed -representations of objects with no read representation, has nothing to -do with the term ``hash table''. @xref{Printed Representation}.) - - Obarrays are also a kind of hash table, but they are a different type -of object and are used only for recording interned symbols -(@pxref{Creating Symbols}). - -@menu -* Creating Hash:: Functions to create hash tables. -* Hash Access:: Reading and writing the hash table contents. -* Defining Hash:: Defining new comparison methods. -* Other Hash:: Miscellaneous. -@end menu - -@node Creating Hash -@section Creating Hash Tables -@cindex creating hash tables - - The principal function for creating a hash table is -@code{make-hash-table}. - -@defun make-hash-table &rest keyword-args -This function creates a new hash table according to the specified -arguments. The arguments should consist of alternating keywords -(particular symbols recognized specially) and values corresponding to -them. - -Several keywords make sense in @code{make-hash-table}, but the only two -that you really need to know about are @code{:test} and @code{:weakness}. - -@table @code -@item :test @var{test} -This specifies the method of key lookup for this hash table. The -default is @code{eql}; @code{eq} and @code{equal} are other -alternatives: - -@table @code -@item eql -Keys which are numbers are ``the same'' if they are @code{equal}, that -is, if they are equal in value and either both are integers or both -are floating point numbers; otherwise, two distinct objects are never -``the same''. - -@item eq -Any two distinct Lisp objects are ``different'' as keys. - -@item equal -Two Lisp objects are ``the same'', as keys, if they are equal -according to @code{equal}. -@end table - -You can use @code{define-hash-table-test} (@pxref{Defining Hash}) to -define additional possibilities for @var{test}. - -@item :weakness @var{weak} -The weakness of a hash table specifies whether the presence of a key or -value in the hash table preserves it from garbage collection. - -The value, @var{weak}, must be one of @code{nil}, @code{key}, -@code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t} -which is an alias for @code{key-and-value}. If @var{weak} is @code{key} -then the hash table does not prevent its keys from being collected as -garbage (if they are not referenced anywhere else); if a particular key -does get collected, the corresponding association is removed from the -hash table. - -If @var{weak} is @code{value}, then the hash table does not prevent -values from being collected as garbage (if they are not referenced -anywhere else); if a particular value does get collected, the -corresponding association is removed from the hash table. - -If @var{weak} is @code{key-and-value} or @code{t}, both the key and -the value must be live in order to preserve the association. Thus, -the hash table does not protect either keys or values from garbage -collection; if either one is collected as garbage, that removes the -association. - -If @var{weak} is @code{key-or-value}, either the key or -the value can preserve the association. Thus, associations are -removed from the hash table when both their key and value would be -collected as garbage (if not for references from weak hash tables). - -The default for @var{weak} is @code{nil}, so that all keys and values -referenced in the hash table are preserved from garbage collection. - -@item :size @var{size} -This specifies a hint for how many associations you plan to store in the -hash table. If you know the approximate number, you can make things a -little more efficient by specifying it this way. If you specify too -small a size, the hash table will grow automatically when necessary, but -doing that takes some extra time. - -The default size is 65. - -@item :rehash-size @var{rehash-size} -When you add an association to a hash table and the table is ``full'', -it grows automatically. This value specifies how to make the hash table -larger, at that time. - -If @var{rehash-size} is an integer, it should be positive, and the hash -table grows by adding that much to the nominal size. If -@var{rehash-size} is a floating point number, it had better be greater -than 1, and the hash table grows by multiplying the old size by that -number. - -The default value is 1.5. - -@item :rehash-threshold @var{threshold} -This specifies the criterion for when the hash table is ``full'' (so -it should be made larger). The value, @var{threshold}, should be a -positive floating point number, no greater than 1. The hash table is -``full'' whenever the actual number of entries exceeds this fraction -of the nominal size. The default for @var{threshold} is 0.8. -@end table -@end defun - -@defun makehash &optional test -This is equivalent to @code{make-hash-table}, but with a different style -argument list. The argument @var{test} specifies the method -of key lookup. - -This function is obsolete. Use @code{make-hash-table} instead. -@end defun - -You can also create a new hash table using the printed representation -for hash tables. The Lisp reader can read this printed -representation, provided each element in the specified hash table has -a valid read syntax (@pxref{Printed Representation}). For instance, -the following specifies a new hash table containing the keys -@code{key1} and @code{key2} (both symbols) associated with @code{val1} -(a symbol) and @code{300} (a number) respectively. - -@example -#s(hash-table size 30 data (key1 val1 key2 300)) -@end example - -@noindent -The printed representation for a hash table consists of @samp{#s} -followed by a list beginning with @samp{hash-table}. The rest of the -list should consist of zero or more property-value pairs specifying -the hash table's properties and initial contents. The properties and -values are read literally. Valid property names are @code{size}, -@code{test}, @code{weakness}, @code{rehash-size}, -@code{rehash-threshold}, and @code{data}. The @code{data} property -should be a list of key-value pairs for the initial contents; the -other properties have the same meanings as the matching -@code{make-hash-table} keywords (@code{:size}, @code{:test}, etc.), -described above. - -Note that you cannot specify a hash table whose initial contents -include objects that have no read syntax, such as buffers and frames. -Such objects may be added to the hash table after it is created. - -@node Hash Access -@section Hash Table Access - - This section describes the functions for accessing and storing -associations in a hash table. In general, any Lisp object can be used -as a hash key, unless the comparison method imposes limits. Any Lisp -object can also be used as the value. - -@defun gethash key table &optional default -This function looks up @var{key} in @var{table}, and returns its -associated @var{value}---or @var{default}, if @var{key} has no -association in @var{table}. -@end defun - -@defun puthash key value table -This function enters an association for @var{key} in @var{table}, with -value @var{value}. If @var{key} already has an association in -@var{table}, @var{value} replaces the old associated value. -@end defun - -@defun remhash key table -This function removes the association for @var{key} from @var{table}, if -there is one. If @var{key} has no association, @code{remhash} does -nothing. - -@b{Common Lisp note:} In Common Lisp, @code{remhash} returns -non-@code{nil} if it actually removed an association and @code{nil} -otherwise. In Emacs Lisp, @code{remhash} always returns @code{nil}. -@end defun - -@defun clrhash table -This function removes all the associations from hash table @var{table}, -so that it becomes empty. This is also called @dfn{clearing} the hash -table. - -@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty -@var{table}. In Emacs Lisp, it returns @code{nil}. -@end defun - -@defun maphash function table -@anchor{Definition of maphash} -This function calls @var{function} once for each of the associations in -@var{table}. The function @var{function} should accept two -arguments---a @var{key} listed in @var{table}, and its associated -@var{value}. @code{maphash} returns @code{nil}. -@end defun - -@node Defining Hash -@section Defining Hash Comparisons -@cindex hash code -@cindex define hash comparisons - - You can define new methods of key lookup by means of -@code{define-hash-table-test}. In order to use this feature, you need -to understand how hash tables work, and what a @dfn{hash code} means. - - You can think of a hash table conceptually as a large array of many -slots, each capable of holding one association. To look up a key, -@code{gethash} first computes an integer, the hash code, from the key. -It reduces this integer modulo the length of the array, to produce an -index in the array. Then it looks in that slot, and if necessary in -other nearby slots, to see if it has found the key being sought. - - Thus, to define a new method of key lookup, you need to specify both a -function to compute the hash code from a key, and a function to compare -two keys directly. - -@defun define-hash-table-test name test-fn hash-fn -This function defines a new hash table test, named @var{name}. - -After defining @var{name} in this way, you can use it as the @var{test} -argument in @code{make-hash-table}. When you do that, the hash table -will use @var{test-fn} to compare key values, and @var{hash-fn} to compute -a ``hash code'' from a key value. - -The function @var{test-fn} should accept two arguments, two keys, and -return non-@code{nil} if they are considered ``the same''. - -The function @var{hash-fn} should accept one argument, a key, and return -an integer that is the ``hash code'' of that key. For good results, the -function should use the whole range of integer values for hash codes, -including negative integers. - -The specified functions are stored in the property list of @var{name} -under the property @code{hash-table-test}; the property value's form is -@code{(@var{test-fn} @var{hash-fn})}. -@end defun - -@defun sxhash obj -This function returns a hash code for Lisp object @var{obj}. -This is an integer which reflects the contents of @var{obj} -and the other Lisp objects it points to. - -If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash -@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer. - -If the two objects are not equal, the values returned by @code{sxhash} -are usually different, but not always; once in a rare while, by luck, -you will encounter two distinct-looking objects that give the same -result from @code{sxhash}. -@end defun - - This example creates a hash table whose keys are strings that are -compared case-insensitively. - -@example -(defun case-fold-string= (a b) - (compare-strings a nil nil b nil nil t)) -(defun case-fold-string-hash (a) - (sxhash (upcase a))) - -(define-hash-table-test 'case-fold - 'case-fold-string= 'case-fold-string-hash) - -(make-hash-table :test 'case-fold) -@end example - - Here is how you could define a hash table test equivalent to the -predefined test value @code{equal}. The keys can be any Lisp object, -and equal-looking objects are considered the same key. - -@example -(define-hash-table-test 'contents-hash 'equal 'sxhash) - -(make-hash-table :test 'contents-hash) -@end example - -@node Other Hash -@section Other Hash Table Functions - - Here are some other functions for working with hash tables. - -@defun hash-table-p table -This returns non-@code{nil} if @var{table} is a hash table object. -@end defun - -@defun copy-hash-table table -This function creates and returns a copy of @var{table}. Only the table -itself is copied---the keys and values are shared. -@end defun - -@defun hash-table-count table -This function returns the actual number of entries in @var{table}. -@end defun - -@defun hash-table-test table -This returns the @var{test} value that was given when @var{table} was -created, to specify how to hash and compare keys. See -@code{make-hash-table} (@pxref{Creating Hash}). -@end defun - -@defun hash-table-weakness table -This function returns the @var{weak} value that was specified for hash -table @var{table}. -@end defun - -@defun hash-table-rehash-size table -This returns the rehash size of @var{table}. -@end defun - -@defun hash-table-rehash-threshold table -This returns the rehash threshold of @var{table}. -@end defun - -@defun hash-table-size table -This returns the current nominal size of @var{table}. -@end defun diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi deleted file mode 100644 index 16a2caf03b4..00000000000 --- a/doc/lispref/help.texi +++ /dev/null @@ -1,727 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/help -@node Documentation, Files, Modes, Top -@chapter Documentation -@cindex documentation strings - - GNU Emacs has convenient built-in help facilities, most of which -derive their information from documentation strings associated with -functions and variables. This chapter describes how to access -documentation strings in Lisp programs. @xref{Documentation Tips}, -for how to write good documentation strings. - - Note that the documentation strings for Emacs are not the same thing -as the Emacs manual. Manuals have their own source files, written in -the Texinfo language; documentation strings are specified in the -definitions of the functions and variables they apply to. A collection -of documentation strings is not sufficient as a manual because a good -manual is not organized in that fashion; it is organized in terms of -topics of discussion. - - For commands to display documentation strings, see @ref{Help, , -Help, emacs, The GNU Emacs Manual}. - -@menu -* Documentation Basics:: Where doc strings are defined and stored. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. -@end menu - -@node Documentation Basics -@comment node-name, next, previous, up -@section Documentation Basics -@cindex documentation conventions -@cindex writing a documentation string -@cindex string, writing a doc string - - A documentation string is written using the Lisp syntax for strings, -with double-quote characters surrounding the text of the string. This -is because it really is a Lisp string object. The string serves as -documentation when it is written in the proper place in the definition -of a function or variable. In a function definition, the documentation -string follows the argument list. In a variable definition, the -documentation string follows the initial value of the variable. - - When you write a documentation string, make the first line a -complete sentence (or two complete sentences) that briefly describes -what the function or variable does. Some commands, such as -@code{apropos}, show only the first line of a multi-line documentation -string. Also, you should not indent the second line of a -documentation string, if it has one, because that looks odd when you -use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v} -(@code{describe-variable}) to view the documentation string. There -are many other conventions for documentation strings; see -@ref{Documentation Tips}. - - Documentation strings can contain several special substrings, which -stand for key bindings to be looked up in the current keymaps when the -documentation is displayed. This allows documentation strings to refer -to the keys for related commands and be accurate even when a user -rearranges the key bindings. (@xref{Keys in Documentation}.) - -@vindex emacs-lisp-docstring-fill-column - Emacs Lisp mode fills documentation strings to the width -specified by @code{emacs-lisp-docstring-fill-column}. - - Exactly where a documentation string is stored depends on how its -function or variable was defined or loaded into memory: - -@itemize @bullet -@item -@kindex function-documentation -When you define a function (@pxref{Lambda Expressions}, and -@pxref{Function Documentation}), the documentation string is stored in -the function definition itself. You can also put function -documentation in the @code{function-documentation} property of a -function name. That is useful for function definitions which can't -hold a documentation string, such as keyboard macros. - -@item -@kindex variable-documentation -When you define a variable with a @code{defvar} or related form -(@pxref{Defining Variables}), the documentation is stored in the -variable's @code{variable-documentation} property. - -@cindex @file{DOC-@var{version}} (documentation) file -@item -To save memory, the documentation for preloaded functions and -variables (including primitive functions and autoloaded functions) is -not kept in memory, but in the file -@file{emacs/etc/DOC-@var{version}}, where @var{version} is the Emacs -version number (@pxref{Version Info}). - -@item -When a function or variable is loaded from a byte-compiled file during -the Emacs session, its documentation string is not loaded into memory. -Instead, Emacs looks it up in the byte-compiled file as needed. -@xref{Docs and Compilation}. -@end itemize - -@noindent -Regardless of where the documentation string is stored, you can -retrieve it using the @code{documentation} or -@code{documentation-property} function, described in the next section. - -@node Accessing Documentation -@section Access to Documentation Strings - -@defun documentation-property symbol property &optional verbatim -This function returns the documentation string recorded in -@var{symbol}'s property list under property @var{property}. It is -most often used to look up the documentation strings of variables, for -which @var{property} is @code{variable-documentation}. However, it -can also be used to look up other kinds of documentation, such as for -customization groups (but for function documentation, use the -@code{documentation} command, below). - -If the value recorded in the property list refers to a documentation -string stored in a @file{DOC-@var{version}} file or a byte-compiled -file, it looks up that string and returns it. If the property value -isn't @code{nil}, isn't a string, and doesn't refer to text in a file, -then it is evaluated as a Lisp expression to obtain a string. - -The last thing this function does is pass the string through -@code{substitute-command-keys} to substitute actual key bindings -(@pxref{Keys in Documentation}). However, it skips this step if -@var{verbatim} is non-@code{nil}. - -@smallexample -@group -(documentation-property 'command-line-processed - 'variable-documentation) - @result{} "Non-nil once command line has been processed" -@end group -@group -(symbol-plist 'command-line-processed) - @result{} (variable-documentation 188902) -@end group -@group -(documentation-property 'emacs 'group-documentation) - @result{} "Customization of the One True Editor." -@end group -@end smallexample -@end defun - -@defun documentation function &optional verbatim -This function returns the documentation string of @var{function}. It -handles macros, named keyboard macros, and special forms, as well as -ordinary functions. - -If @var{function} is a symbol, this function first looks for the -@code{function-documentation} property of that symbol; if that has a -non-@code{nil} value, the documentation comes from that value (if the -value is not a string, it is evaluated). If @var{function} is not a -symbol, or if it has no @code{function-documentation} property, then -@code{documentation} extracts the documentation string from the actual -function definition, reading it from a file if called for. - -Finally, unless @var{verbatim} is non-@code{nil}, it calls -@code{substitute-command-keys} so as to return a value containing the -actual (current) key bindings. - -The function @code{documentation} signals a @code{void-function} error -if @var{function} has no function definition. However, it is OK if -the function definition has no documentation string. In that case, -@code{documentation} returns @code{nil}. -@end defun - -@defun face-documentation face -This function returns the documentation string of @var{face} as a -face. -@end defun - -@c Wordy to prevent overfull hboxes. --rjc 15mar92 -Here is an example of using the two functions, @code{documentation} and -@code{documentation-property}, to display the documentation strings for -several symbols in a @file{*Help*} buffer. - -@anchor{describe-symbols example} -@smallexample -@group -(defun describe-symbols (pattern) - "Describe the Emacs Lisp symbols matching PATTERN. -All symbols that have PATTERN in their name are described -in the `*Help*' buffer." - (interactive "sDescribe symbols matching: ") - (let ((describe-func - (function - (lambda (s) -@end group -@group - ;; @r{Print description of symbol.} - (if (fboundp s) ; @r{It is a function.} - (princ - (format "%s\t%s\n%s\n\n" s - (if (commandp s) - (let ((keys (where-is-internal s))) - (if keys - (concat - "Keys: " - (mapconcat 'key-description - keys " ")) - "Keys: none")) - "Function") -@end group -@group - (or (documentation s) - "not documented")))) - - (if (boundp s) ; @r{It is a variable.} -@end group -@group - (princ - (format "%s\t%s\n%s\n\n" s - (if (user-variable-p s) - "Option " "Variable") -@end group -@group - (or (documentation-property - s 'variable-documentation) - "not documented"))))))) - sym-list) -@end group - -@group - ;; @r{Build a list of symbols that match pattern.} - (mapatoms (function - (lambda (sym) - (if (string-match pattern (symbol-name sym)) - (setq sym-list (cons sym sym-list)))))) -@end group - -@group - ;; @r{Display the data.} - (help-setup-xref (list 'describe-symbols pattern) (interactive-p)) - (with-help-window (help-buffer) - (mapcar describe-func (sort sym-list 'string<))))) -@end group -@end smallexample - - The @code{describe-symbols} function works like @code{apropos}, -but provides more information. - -@smallexample -@group -(describe-symbols "goal") - ----------- Buffer: *Help* ---------- -goal-column Option -Semipermanent goal column for vertical motion, as set by @dots{} -@end group -@c Do not blithely break or fill these lines. -@c That makes them incorrect. - -@group -set-goal-column Keys: C-x C-n -Set the current horizontal position as a goal for C-n and C-p. -@end group -@c DO NOT put a blank line here! That is factually inaccurate! -@group -Those commands will move to this position in the line moved to -rather than trying to keep the same horizontal position. -With a non-nil argument, clears out the goal column -so that C-n and C-p resume vertical motion. -The goal column is stored in the variable `goal-column'. -@end group - -@group -temporary-goal-column Variable -Current goal column for vertical motion. -It is the column where point was -at the start of current run of vertical motion commands. -When the `track-eol' feature is doing its job, the value is 9999. ----------- Buffer: *Help* ---------- -@end group -@end smallexample - -@anchor{Definition of Snarf-documentation} -@defun Snarf-documentation filename -This function is used when building Emacs, just before the runnable -Emacs is dumped. It finds the positions of the documentation strings -stored in the file @var{filename}, and records those positions into -memory in the function definitions and variable property lists. -@xref{Building Emacs}. - -Emacs reads the file @var{filename} from the @file{emacs/etc} directory. -When the dumped Emacs is later executed, the same file will be looked -for in the directory @code{doc-directory}. Usually @var{filename} is -@code{"DOC-@var{version}"}. -@end defun - -@defvar doc-directory -This variable holds the name of the directory which should contain the -file @code{"DOC-@var{version}"} that contains documentation strings for -built-in and preloaded functions and variables. - -In most cases, this is the same as @code{data-directory}. They may be -different when you run Emacs from the directory where you built it, -without actually installing it. @xref{Definition of data-directory}. -@end defvar - -@node Keys in Documentation -@section Substituting Key Bindings in Documentation -@cindex documentation, keys in -@cindex keys in documentation strings -@cindex substituting keys in documentation - - When documentation strings refer to key sequences, they should use the -current, actual key bindings. They can do so using certain special text -sequences described below. Accessing documentation strings in the usual -way substitutes current key binding information for these special -sequences. This works by calling @code{substitute-command-keys}. You -can also call that function yourself. - - Here is a list of the special sequences and what they mean: - -@table @code -@item \[@var{command}] -stands for a key sequence that will invoke @var{command}, or @samp{M-x -@var{command}} if @var{command} has no key bindings. - -@item \@{@var{mapvar}@} -stands for a summary of the keymap which is the value of the variable -@var{mapvar}. The summary is made using @code{describe-bindings}. - -@item \<@var{mapvar}> -stands for no text itself. It is used only for a side effect: it -specifies @var{mapvar}'s value as the keymap for any following -@samp{\[@var{command}]} sequences in this documentation string. - -@item \= -quotes the following character and is discarded; thus, @samp{\=\[} puts -@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the -output. -@end table - -@strong{Please note:} Each @samp{\} must be doubled when written in a -string in Emacs Lisp. - -@defun substitute-command-keys string -This function scans @var{string} for the above special sequences and -replaces them by what they stand for, returning the result as a string. -This permits display of documentation that refers accurately to the -user's own customized key bindings. - -@cindex advertised binding -If a command has multiple bindings, this function normally uses the -first one it finds. You can specify one particular key binding by -assigning an @code{:advertised-binding} symbol property to the -command, like this: - -@smallexample -(put 'undo :advertised-binding [?\C-/]) -@end smallexample - -@noindent -The @code{:advertised-binding} property also affects the binding shown -in menu items (@pxref{Menu Bar}). The property is ignored if it -specifies a key binding that the command does not actually have. -@end defun - - Here are examples of the special sequences: - -@smallexample -@group -(substitute-command-keys - "To abort recursive edit, type: \\[abort-recursive-edit]") -@result{} "To abort recursive edit, type: C-]" -@end group - -@group -(substitute-command-keys - "The keys that are defined for the minibuffer here are: - \\@{minibuffer-local-must-match-map@}") -@result{} "The keys that are defined for the minibuffer here are: -@end group - -? minibuffer-completion-help -SPC minibuffer-complete-word -TAB minibuffer-complete -C-j minibuffer-complete-and-exit -RET minibuffer-complete-and-exit -C-g abort-recursive-edit -" - -@group -(substitute-command-keys - "To abort a recursive edit from the minibuffer, type\ -\\\\[abort-recursive-edit].") -@result{} "To abort a recursive edit from the minibuffer, type C-g." -@end group -@end smallexample - - There are other special conventions for the text in documentation -strings---for instance, you can refer to functions, variables, and -sections of this manual. @xref{Documentation Tips}, for details. - -@node Describing Characters -@section Describing Characters for Help Messages -@cindex describe characters and events - - These functions convert events, key sequences, or characters to -textual descriptions. These descriptions are useful for including -arbitrary text characters or key sequences in messages, because they -convert non-printing and whitespace characters to sequences of printing -characters. The description of a non-whitespace printing character is -the character itself. - -@defun key-description sequence &optional prefix -@cindex Emacs event standard notation -This function returns a string containing the Emacs standard notation -for the input events in @var{sequence}. If @var{prefix} is -non-@code{nil}, it is a sequence of input events leading up to -@var{sequence} and is included in the return value. Both arguments -may be strings, vectors or lists. @xref{Input Events}, for more -information about valid events. - -@smallexample -@group -(key-description [?\M-3 delete]) - @result{} "M-3 " -@end group -@group -(key-description [delete] "\M-3") - @result{} "M-3 " -@end group -@end smallexample - - See also the examples for @code{single-key-description}, below. -@end defun - -@defun single-key-description event &optional no-angles -@cindex event printing -@cindex character printing -@cindex control character printing -@cindex meta character printing -This function returns a string describing @var{event} in the standard -Emacs notation for keyboard input. A normal printing character -appears as itself, but a control character turns into a string -starting with @samp{C-}, a meta character turns into a string starting -with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC}, -@samp{TAB}, etc. A function key symbol appears inside angle brackets -@samp{<@dots{}>}. An event that is a list appears as the name of the -symbol in the @sc{car} of the list, inside angle brackets. - -If the optional argument @var{no-angles} is non-@code{nil}, the angle -brackets around function keys and event symbols are omitted; this is -for compatibility with old versions of Emacs which didn't use the -brackets. - -@smallexample -@group -(single-key-description ?\C-x) - @result{} "C-x" -@end group -@group -(key-description "\C-x \M-y \n \t \r \f123") - @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3" -@end group -@group -(single-key-description 'delete) - @result{} "" -@end group -@group -(single-key-description 'C-mouse-1) - @result{} "" -@end group -@group -(single-key-description 'C-mouse-1 t) - @result{} "C-mouse-1" -@end group -@end smallexample -@end defun - -@defun text-char-description character -This function returns a string describing @var{character} in the -standard Emacs notation for characters that appear in text---like -@code{single-key-description}, except that control characters are -represented with a leading caret (which is how control characters in -Emacs buffers are usually displayed). Another difference is that -@code{text-char-description} recognizes the 2**7 bit as the Meta -character, whereas @code{single-key-description} uses the 2**27 bit -for Meta. - -@smallexample -@group -(text-char-description ?\C-c) - @result{} "^C" -@end group -@group -(text-char-description ?\M-m) - @result{} "\xed" -@end group -@group -(text-char-description ?\C-\M-m) - @result{} "\x8d" -@end group -@group -(text-char-description (+ 128 ?m)) - @result{} "M-m" -@end group -@group -(text-char-description (+ 128 ?\C-m)) - @result{} "M-^M" -@end group -@end smallexample -@end defun - -@deffn Command read-kbd-macro string &optional need-vector -This function is used mainly for operating on keyboard macros, but it -can also be used as a rough inverse for @code{key-description}. You -call it with a string containing key descriptions, separated by spaces; -it returns a string or vector containing the corresponding events. -(This may or may not be a single valid key sequence, depending on what -events you use; @pxref{Key Sequences}.) If @var{need-vector} is -non-@code{nil}, the return value is always a vector. -@end deffn - -@node Help Functions -@section Help Functions - - Emacs provides a variety of on-line help functions, all accessible to -the user as subcommands of the prefix @kbd{C-h}. For more information -about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here -we describe some program-level interfaces to the same information. - -@deffn Command apropos pattern &optional do-all -This function finds all ``meaningful'' symbols whose names contain a -match for the apropos pattern @var{pattern}. An apropos pattern is -either a word to match, a space-separated list of words of which at -least two must match, or a regular expression (if any special regular -expression characters occur). A symbol is ``meaningful'' if it has a -definition as a function, variable, or face, or has properties. - -The function returns a list of elements that look like this: - -@example -(@var{symbol} @var{score} @var{function-doc} @var{variable-doc} - @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc}) -@end example - -Here, @var{score} is an integer measure of how important the symbol -seems to be as a match. Each of the remaining elements is a -documentation string, or @code{nil}, for @var{symbol} as a function, -variable, etc. - -It also displays the symbols in a buffer named @file{*Apropos*}, each -with a one-line description taken from the beginning of its -documentation string. - -If @var{do-all} is non-@code{nil}, or if the user option -@code{apropos-do-all} is non-@code{nil}, then @code{apropos} also -shows key bindings for the functions that are found; it also shows -@emph{all} interned symbols, not just meaningful ones (and it lists -them in the return value as well). -@end deffn - -@defvar help-map -The value of this variable is a local keymap for characters following the -Help key, @kbd{C-h}. -@end defvar - -@deffn {Prefix Command} help-command -This symbol is not a function; its function definition cell holds the -keymap known as @code{help-map}. It is defined in @file{help.el} as -follows: - -@smallexample -@group -(define-key global-map (string help-char) 'help-command) -(fset 'help-command help-map) -@end group -@end smallexample -@end deffn - -@defopt help-char -The value of this variable is the help character---the character that -Emacs recognizes as meaning Help. By default, its value is 8, which -stands for @kbd{C-h}. When Emacs reads this character, if -@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that -expression, and displays the result in a window if it is a string. - -Usually the value of @code{help-form} is @code{nil}. Then the -help character has no special meaning at the level of command input, and -it becomes part of a key sequence in the normal way. The standard key -binding of @kbd{C-h} is a prefix key for several general-purpose help -features. - -The help character is special after prefix keys, too. If it has no -binding as a subcommand of the prefix key, it runs -@code{describe-prefix-bindings}, which displays a list of all the -subcommands of the prefix key. -@end defopt - -@defopt help-event-list -The value of this variable is a list of event types that serve as -alternative ``help characters''. These events are handled just like the -event specified by @code{help-char}. -@end defopt - -@defvar help-form -If this variable is non-@code{nil}, its value is a form to evaluate -whenever the character @code{help-char} is read. If evaluating the form -produces a string, that string is displayed. - -A command that calls @code{read-event}, @code{read-char-choice}, or -@code{read-char} probably should bind @code{help-form} to a -non-@code{nil} expression while it does input. (The time when you -should not do this is when @kbd{C-h} has some other meaning.) -Evaluating this expression should result in a string that explains -what the input is for and how to enter it properly. - -Entry to the minibuffer binds this variable to the value of -@code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}). -@end defvar - -@defvar prefix-help-command -This variable holds a function to print help for a prefix key. The -function is called when the user types a prefix key followed by the help -character, and the help character has no binding after that prefix. The -variable's default value is @code{describe-prefix-bindings}. -@end defvar - -@deffn Command describe-prefix-bindings -This function calls @code{describe-bindings} to display a list of all -the subcommands of the prefix key of the most recent key sequence. The -prefix described consists of all but the last event of that key -sequence. (The last event is, presumably, the help character.) -@end deffn - - The following two functions are meant for modes that want to provide -help without relinquishing control, such as the ``electric'' modes. -Their names begin with @samp{Helper} to distinguish them from the -ordinary help functions. - -@deffn Command Helper-describe-bindings -This command pops up a window displaying a help buffer containing a -listing of all of the key bindings from both the local and global keymaps. -It works by calling @code{describe-bindings}. -@end deffn - -@deffn Command Helper-help -This command provides help for the current mode. It prompts the user -in the minibuffer with the message @samp{Help (Type ? for further -options)}, and then provides assistance in finding out what the key -bindings are, and what the mode is intended for. It returns @code{nil}. - -@vindex Helper-help-map -This can be customized by changing the map @code{Helper-help-map}. -@end deffn - -@defvar data-directory -@anchor{Definition of data-directory} -This variable holds the name of the directory in which Emacs finds -certain documentation and text files that come with Emacs. -@end defvar - -@defun help-buffer -This function returns the name of the help buffer, which is normally -@file{*Help*}; if such a buffer does not exist, it is first created. -@end defun - -@defmac with-help-window buffer-name body@dots{} -This macro evaluates the @var{body} forms, inserting any output they -produce into a buffer named @var{buffer-name} like -@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}). -(Usually, @var{buffer-name} should be the value returned by the -function @code{help-buffer}.) It also puts the specified buffer into -Help mode and displays a message telling the user how to quit and -scroll the help window. -@end defmac - -@defun help-setup-xref item interactive-p -This function updates the cross reference data in the @file{*Help*} -buffer, which is used to regenerate the help information when the user -clicks on the @samp{Back} or @samp{Forward} buttons. Most commands -that use the @file{*Help*} buffer should invoke this function before -clearing the buffer. The @var{item} argument should have the form -@code{(@var{function} . @var{args})}, where @var{function} is a function -to call, with argument list @var{args}, to regenerate the help buffer. -The @var{interactive-p} argument is non-@code{nil} if the calling -command was invoked interactively; in that case, the stack of items -for the @file{*Help*} buffer's @samp{Back} buttons is cleared. -@end defun - -@xref{describe-symbols example}, for an example of using -@code{help-buffer}, @code{with-help-window}, and -@code{help-setup-xref}. - -@defmac make-help-screen fname help-line help-text help-map -This macro defines a help command named @var{fname} that acts like a -prefix key that shows a list of the subcommands it offers. - -When invoked, @var{fname} displays @var{help-text} in a window, then -reads and executes a key sequence according to @var{help-map}. The -string @var{help-text} should describe the bindings available in -@var{help-map}. - -The command @var{fname} is defined to handle a few events itself, by -scrolling the display of @var{help-text}. When @var{fname} reads one of -those special events, it does the scrolling and then reads another -event. When it reads an event that is not one of those few, and which -has a binding in @var{help-map}, it executes that key's binding and -then returns. - -The argument @var{help-line} should be a single-line summary of the -alternatives in @var{help-map}. In the current version of Emacs, this -argument is used only if you set the option @code{three-step-help} to -@code{t}. - -This macro is used in the command @code{help-for-help} which is the -binding of @kbd{C-h C-h}. -@end defmac - -@defopt three-step-help -If this variable is non-@code{nil}, commands defined with -@code{make-help-screen} display their @var{help-line} strings in the -echo area at first, and display the longer @var{help-text} strings only -if the user types the help character again. -@end defopt - diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi deleted file mode 100644 index 0d29c25c8b1..00000000000 --- a/doc/lispref/hooks.texi +++ /dev/null @@ -1,285 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1998, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/hooks -@node Standard Hooks, Index, Standard Keymaps, Top -@appendix Standard Hooks -@cindex standard hooks -@cindex hook variables, list of - -The following is a list of some hook variables that let you provide -functions to be called from within Emacs on suitable occasions. - -Most of these variables have names ending with @samp{-hook}. They are -@dfn{normal hooks}, run by means of @code{run-hooks}. The value of such -a hook is a list of functions; the functions are called with no -arguments and their values are completely ignored. The recommended way -to put a new function on such a hook is to call @code{add-hook}. -@xref{Hooks}, for more information about using hooks. - -The variables whose names end in @samp{-hooks} or @samp{-functions} are -usually @dfn{abnormal hooks}; their values are lists of functions, but -these functions are called in a special way (they are passed arguments, -or their values are used). The variables whose names end in -@samp{-function} have single functions as their values. - -This is not an exhaustive list, it only covers the more general hooks. -For example, every major mode defines a hook named -@samp{@var{modename}-mode-hook}. The major mode command runs this -normal hook with @code{run-mode-hooks} as the very last thing it does. -@xref{Mode Hooks}. Most minor modes have mode hooks too. - -A special feature allows you to specify expressions to evaluate if and -when a file is loaded (@pxref{Hooks for Loading}). That feature is -not exactly a hook, but does a similar job. - -@c We need to xref to where each hook is documented or else document it here. -@c Add vindex for anything not indexed elsewhere. -@c This list is in alphabetical order, grouped by topic. -@c TODO It should probably be more thoroughly ordered by topic. - -@table @code -@item activate-mark-hook -@itemx deactivate-mark-hook -@xref{The Mark}. - -@item after-change-functions -@itemx before-change-functions -@itemx first-change-hook -@xref{Change Hooks}. - -@item after-change-major-mode-hook -@itemx change-major-mode-after-body-hook -@xref{Mode Hooks}. - -@item after-init-hook -@itemx before-init-hook -@itemx emacs-startup-hook -@xref{Init File}. - -@item after-insert-file-functions -@itemx write-region-annotate-functions -@itemx write-region-post-annotation-function -@xref{Format Conversion}. - -@item after-make-frame-functions -@itemx before-make-frame-hook -@xref{Creating Frames}. - -@c Not general enough? -@ignore -@item after-revert-hook -@itemx before-revert-hook -@itemx buffer-stale-function -@itemx revert-buffer-function -@itemx revert-buffer-insert-file-contents-function -@xref{Reverting}. -@end ignore - -@item after-save-hook -@itemx before-save-hook -@itemx write-contents-functions -@itemx write-file-functions -@xref{Saving Buffers}. - -@item after-setting-font-hook -@vindex after-setting-font-hook -Hook run after a frame's font changes. - -@item auto-save-hook -@xref{Auto-Saving}. - -@item before-hack-local-variables-hook -@itemx hack-local-variables-hook -@xref{File Local Variables}. - -@item buffer-access-fontify-functions -@xref{Lazy Properties}. - -@item buffer-list-update-hook -@vindex buffer-list-update-hook -Hook run when the buffer list changes. - -@item buffer-quit-function -@vindex buffer-quit-function -Function to call to ``quit'' the current buffer. - -@item change-major-mode-hook -@xref{Creating Buffer-Local}. - -@item command-line-functions -@xref{Command-Line Arguments}. - -@item delayed-warnings-hook -@vindex delayed-warnings-hook -The command loop runs this soon after @code{post-command-hook} (q.v.). - -@item delete-frame-functions -@xref{Deleting Frames}. - -@item delete-terminal-functions -@xref{Multiple Terminals}. - -@ignore -@item disabled-command-function -@xref{Disabling Commands}. -@end ignore - -@item display-buffer-function -@itemx pop-up-frame-function -@itemx special-display-function -@itemx split-window-preferred-function -@xref{Choosing Window Options}. - -@item echo-area-clear-hook -@xref{Echo Area Customization}. - -@item find-file-hook -@itemx find-file-not-found-functions -@xref{Visiting Functions}. - -@item font-lock-extend-after-change-region-function -@xref{Region to Refontify}. - -@item font-lock-extend-region-functions -@xref{Multiline Font Lock}. - -@item font-lock-fontify-buffer-function -@itemx font-lock-fontify-region-function -@itemx font-lock-mark-block-function -@itemx font-lock-unfontify-buffer-function -@itemx font-lock-unfontify-region-function -@xref{Other Font Lock Variables}. - -@item fontification-functions -@xref{Auto Faces,, Automatic Face Assignment}. - -@item frame-auto-hide-function -@xref{Quitting Windows}. - -@item kill-buffer-hook -@itemx kill-buffer-query-functions -@xref{Killing Buffers}. - -@item kill-emacs-hook -@itemx kill-emacs-query-functions -@xref{Killing Emacs}. - -@item menu-bar-update-hook -@xref{Menu Bar}. - -@item minibuffer-setup-hook -@itemx minibuffer-exit-hook -@xref{Minibuffer Misc}. - -@item mouse-leave-buffer-hook -@vindex mouse-leave-buffer-hook -Hook run when about to switch windows with a mouse command. - -@item mouse-position-function -@xref{Mouse Position}. - -@item post-command-hook -@itemx pre-command-hook -@xref{Command Overview}. - -@item post-gc-hook -@xref{Garbage Collection}. - -@item post-self-insert-hook -@xref{Keymaps and Minor Modes}. - -@ignore -@item prog-mode-hook -@itemx special-mode-hook -@vindex special-mode-hook -@xref{Basic Major Modes}. -@end ignore - -@item suspend-hook -@itemx suspend-resume-hook -@itemx suspend-tty-functions -@itemx resume-tty-functions -@xref{Suspending Emacs}. - -@item syntax-begin-function -@itemx syntax-propertize-extend-region-functions -@itemx syntax-propertize-function -@itemx font-lock-syntactic-face-function -@xref{Syntactic Font Lock}. @xref{Syntax Properties}. - -@item temp-buffer-setup-hook -@itemx temp-buffer-show-function -@itemx temp-buffer-show-hook -@xref{Temporary Displays}. - -@item term-setup-hook -@xref{Terminal-Specific}. - -@item window-configuration-change-hook -@itemx window-scroll-functions -@itemx window-size-change-functions -@xref{Window Hooks}. - -@item window-setup-hook -@xref{Window Systems}. - -@item window-text-change-functions -@vindex window-text-change-functions -Functions to call in redisplay when text in the window might change. - -@end table - -@ignore -Some -hook, -function, -functions from preloaded Lisp or C files that -I thought did not need to be mentioned here: - -Lisp: -after-load-functions -auto-coding-functions -choose-completion-string-functions -completing-read-function -completion-annotate-function -completion-at-point-functions -completion-in-region-functions -completion-list-insert-choice-function -describe-current-input-method-function -filter-buffer-substring-functions -font-lock-function -inactivate-current-input-method-function -menu-bar-select-buffer-function -read-file-name-function -replace-re-search-function -replace-search-function -yank-undo-function - -C hooks: -kbd-macro-termination-hook -signal-hook-function - -C functions: -redisplay-end-trigger-functions -x-lost-selection-functions -x-sent-selection-functions - -C function: -auto-composition-function -auto-fill-function -command-error-function -compose-chars-after-function -composition-function-table -deferred-action-function -input-method-function -load-read-function -load-source-file-function -macro-declaration-function -read-buffer-function -ring-bell-function -select-safe-coding-system-function -set-auto-coding-function -show-help-function -signal-hook-function -undo-outer-limit-function - -@end ignore diff --git a/doc/lispref/index.texi b/doc/lispref/index.texi deleted file mode 100644 index 6cdadf94491..00000000000 --- a/doc/lispref/index.texi +++ /dev/null @@ -1,29 +0,0 @@ -@c -*-texinfo-*- -@setfilename ../../info/index - -@c Indexing guidelines - -@c I assume that all indexes will be combined. -@c Therefore, if a generated findex and permutations -@c cover the ways an index user would look up the entry, -@c then no cindex is added. -@c Concept index (cindex) entries will also be permuted. Therefore, they -@c have no commas and few irrelevant connectives in them. - -@c I tried to include words in a cindex that give the context of the entry, -@c particularly if there is more than one entry for the same concept. -@c For example, "nil in keymap" -@c Similarly for explicit findex and vindex entries, e.g. "print example". - -@c Error codes are given cindex entries, e.g. "end-of-file error". - -@c pindex is used for .el files and Unix programs - -@node Index, , Standard Hooks, Top -@unnumbered Index - -@c Print the indices - -@printindex fn - - diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi deleted file mode 100644 index eb9d81f196f..00000000000 --- a/doc/lispref/internals.texi +++ /dev/null @@ -1,1406 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/internals -@node GNU Emacs Internals, Standard Errors, Tips, Top -@comment node-name, next, previous, up -@appendix GNU Emacs Internals - -This chapter describes how the runnable Emacs executable is dumped with -the preloaded Lisp libraries in it, how storage is allocated, and some -internal aspects of GNU Emacs that may be of interest to C programmers. - -@menu -* Building Emacs:: How the dumped Emacs is made. -* Pure Storage:: Kludge to make preloaded Lisp functions shareable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Memory Usage:: Info about total size of Lisp objects made so far. -* Writing Emacs Primitives:: Writing C code for Emacs. -* Object Internals:: Data formats of buffers, windows, processes. -@end menu - -@node Building Emacs -@section Building Emacs -@cindex building Emacs -@pindex temacs - - This section explains the steps involved in building the Emacs -executable. You don't have to know this material to build and install -Emacs, since the makefiles do all these things automatically. This -information is pertinent to Emacs developers. - - Compilation of the C source files in the @file{src} directory -produces an executable file called @file{temacs}, also called a -@dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and -I/O routines, but not the editing commands. - -@cindex @file{loadup.el} - The command @w{@command{temacs -l loadup}} would run @file{temacs} -and direct it to load @file{loadup.el}. The @code{loadup} library -loads additional Lisp libraries, which set up the normal Emacs editing -environment. After this step, the Emacs executable is no longer -@dfn{bare}. - -@cindex dumping Emacs - Because it takes some time to load the standard Lisp files, the -@file{temacs} executable usually isn't run directly by users. -Instead, as one of the last steps of building Emacs, the command -@samp{temacs -batch -l loadup dump} is run. The special @samp{dump} -argument causes @command{temacs} to dump out an executable program, -called @file{emacs}, which has all the standard Lisp files preloaded. -(The @samp{-batch} argument prevents @file{temacs} from trying to -initialize any of its data on the terminal, so that the tables of -terminal information are empty in the dumped Emacs.) - -@cindex preloaded Lisp files -@vindex preloaded-file-list - The dumped @file{emacs} executable (also called a @dfn{pure} Emacs) -is the one which is installed. The variable -@code{preloaded-file-list} stores a list of the Lisp files preloaded -into the dumped Emacs. If you port Emacs to a new operating system, -and are not able to implement dumping, then Emacs must load -@file{loadup.el} each time it starts. - -@cindex @file{site-load.el} - You can specify additional files to preload by writing a library named -@file{site-load.el} that loads them. You may need to rebuild Emacs -with an added definition - -@example -#define SITELOAD_PURESIZE_EXTRA @var{n} -@end example - -@noindent -to make @var{n} added bytes of pure space to hold the additional files; -see @file{src/puresize.h}. -(Try adding increments of 20000 until it is big enough.) However, the -advantage of preloading additional files decreases as machines get -faster. On modern machines, it is usually not advisable. - - After @file{loadup.el} reads @file{site-load.el}, it finds the -documentation strings for primitive and preloaded functions (and -variables) in the file @file{etc/DOC} where they are stored, by -calling @code{Snarf-documentation} (@pxref{Definition of -Snarf-documentation,, Accessing Documentation}). - -@cindex @file{site-init.el} -@cindex preloading additional functions and variables - You can specify other Lisp expressions to execute just before dumping -by putting them in a library named @file{site-init.el}. This file is -executed after the documentation strings are found. - - If you want to preload function or variable definitions, there are -three ways you can do this and make their documentation strings -accessible when you subsequently run Emacs: - -@itemize @bullet -@item -Arrange to scan these files when producing the @file{etc/DOC} file, -and load them with @file{site-load.el}. - -@item -Load the files with @file{site-init.el}, then copy the files into the -installation directory for Lisp files when you install Emacs. - -@item -Specify a @code{nil} value for @code{byte-compile-dynamic-docstrings} -as a local variable in each of these files, and load them with either -@file{site-load.el} or @file{site-init.el}. (This method has the -drawback that the documentation strings take up space in Emacs all the -time.) -@end itemize - - It is not advisable to put anything in @file{site-load.el} or -@file{site-init.el} that would alter any of the features that users -expect in an ordinary unmodified Emacs. If you feel you must override -normal features for your site, do it with @file{default.el}, so that -users can override your changes if they wish. @xref{Startup Summary}. - - In a package that can be preloaded, it is sometimes necessary (or -useful) to delay certain evaluations until Emacs subsequently starts -up. The vast majority of such cases relate to the values of -customizable variables. For example, @code{tutorial-directory} is a -variable defined in @file{startup.el}, which is preloaded. The default -value is set based on @code{data-directory}. The variable needs to -access the value of @code{data-directory} when Emacs starts, not when -it is dumped, because the Emacs executable has probably been installed -in a different location since it was dumped. - -@defun custom-initialize-delay symbol value -This function delays the initialization of @var{symbol} to the next -Emacs start. You normally use this function by specifying it as the -@code{:initialize} property of a customizable variable. (The argument -@var{value} is unused, and is provided only for compatibility with the -form Custom expects.) -@end defun - -In the unlikely event that you need a more general functionality than -@code{custom-initialize-delay} provides, you can use -@code{before-init-hook} (@pxref{Startup Summary}). - -@defun dump-emacs to-file from-file -@cindex unexec -This function dumps the current state of Emacs into an executable file -@var{to-file}. It takes symbols from @var{from-file} (this is normally -the executable file @file{temacs}). - -If you want to use this function in an Emacs that was already dumped, -you must run Emacs with @samp{-batch}. -@end defun - -@node Pure Storage -@section Pure Storage -@cindex pure storage - - Emacs Lisp uses two kinds of storage for user-created Lisp objects: -@dfn{normal storage} and @dfn{pure storage}. Normal storage is where -all the new data created during an Emacs session are kept -(@pxref{Garbage Collection}). Pure storage is used for certain data -in the preloaded standard Lisp files---data that should never change -during actual use of Emacs. - - Pure storage is allocated only while @command{temacs} is loading the -standard preloaded Lisp libraries. In the file @file{emacs}, it is -marked as read-only (on operating systems that permit this), so that -the memory space can be shared by all the Emacs jobs running on the -machine at once. Pure storage is not expandable; a fixed amount is -allocated when Emacs is compiled, and if that is not sufficient for -the preloaded libraries, @file{temacs} allocates dynamic memory for -the part that didn't fit. The resulting image will work, but garbage -collection (@pxref{Garbage Collection}) is disabled in this situation, -causing a memory leak. Such an overflow normally won't happen unless -you try to preload additional libraries or add features to the -standard ones. Emacs will display a warning about the overflow when -it starts. If this happens, you should increase the compilation -parameter @code{SYSTEM_PURESIZE_EXTRA} in the file -@file{src/puresize.h} and rebuild Emacs. - -@defun purecopy object -This function makes a copy in pure storage of @var{object}, and returns -it. It copies a string by simply making a new string with the same -characters, but without text properties, in pure storage. It -recursively copies the contents of vectors and cons cells. It does -not make copies of other objects such as symbols, but just returns -them unchanged. It signals an error if asked to copy markers. - -This function is a no-op except while Emacs is being built and dumped; -it is usually called only in preloaded Lisp files. -@end defun - -@defvar pure-bytes-used -The value of this variable is the number of bytes of pure storage -allocated so far. Typically, in a dumped Emacs, this number is very -close to the total amount of pure storage available---if it were not, -we would preallocate less. -@end defvar - -@defvar purify-flag -This variable determines whether @code{defun} should make a copy of the -function definition in pure storage. If it is non-@code{nil}, then the -function definition is copied into pure storage. - -This flag is @code{t} while loading all of the basic functions for -building Emacs initially (allowing those functions to be shareable and -non-collectible). Dumping Emacs as an executable always writes -@code{nil} in this variable, regardless of the value it actually has -before and after dumping. - -You should not change this flag in a running Emacs. -@end defvar - -@node Garbage Collection -@section Garbage Collection - -@cindex memory allocation - When a program creates a list or the user defines a new function -(such as by loading a library), that data is placed in normal storage. -If normal storage runs low, then Emacs asks the operating system to -allocate more memory. Different types of Lisp objects, such as -symbols, cons cells, markers, etc., are segregated in distinct blocks -in memory. (Vectors, long strings, buffers and certain other editing -types, which are fairly large, are allocated in individual blocks, one -per object, while small strings are packed into blocks of 8k bytes.) - -@cindex garbage collection - It is quite common to use some storage for a while, then release it -by (for example) killing a buffer or deleting the last pointer to an -object. Emacs provides a @dfn{garbage collector} to reclaim this -abandoned storage. The garbage collector operates by finding and -marking all Lisp objects that are still accessible to Lisp programs. -To begin with, it assumes all the symbols, their values and associated -function definitions, and any data presently on the stack, are -accessible. Any objects that can be reached indirectly through other -accessible objects are also accessible. - - When marking is finished, all objects still unmarked are garbage. No -matter what the Lisp program or the user does, it is impossible to refer -to them, since there is no longer a way to reach them. Their space -might as well be reused, since no one will miss them. The second -(``sweep'') phase of the garbage collector arranges to reuse them. - -@c ??? Maybe add something describing weak hash tables here? - -@cindex free list - The sweep phase puts unused cons cells onto a @dfn{free list} -for future allocation; likewise for symbols and markers. It compacts -the accessible strings so they occupy fewer 8k blocks; then it frees the -other 8k blocks. Vectors, buffers, windows, and other large objects are -individually allocated and freed using @code{malloc} and @code{free}. - -@cindex CL note---allocate more storage -@quotation -@b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not -call the garbage collector when the free list is empty. Instead, it -simply requests the operating system to allocate more storage, and -processing continues until @code{gc-cons-threshold} bytes have been -used. - -This means that you can make sure that the garbage collector will not -run during a certain portion of a Lisp program by calling the garbage -collector explicitly just before it (provided that portion of the -program does not use so much space as to force a second garbage -collection). -@end quotation - -@deffn Command garbage-collect -This command runs a garbage collection, and returns information on -the amount of space in use. (Garbage collection can also occur -spontaneously if you use more than @code{gc-cons-threshold} bytes of -Lisp data since the previous garbage collection.) - -@code{garbage-collect} returns a list containing the following -information: - -@example -@group -((@var{used-conses} . @var{free-conses}) - (@var{used-syms} . @var{free-syms}) -@end group - (@var{used-miscs} . @var{free-miscs}) - @var{used-string-chars} - @var{used-vector-slots} - (@var{used-floats} . @var{free-floats}) - (@var{used-intervals} . @var{free-intervals}) - (@var{used-strings} . @var{free-strings})) -@end example - -Here is an example: - -@example -@group -(garbage-collect) - @result{} ((106886 . 13184) (9769 . 0) - (7731 . 4651) 347543 121628 - (31 . 94) (1273 . 168) - (25474 . 3569)) -@end group -@end example - -Here is a table explaining each element: - -@table @var -@item used-conses -The number of cons cells in use. - -@item free-conses -The number of cons cells for which space has been obtained from the -operating system, but that are not currently being used. - -@item used-syms -The number of symbols in use. - -@item free-syms -The number of symbols for which space has been obtained from the -operating system, but that are not currently being used. - -@item used-miscs -The number of miscellaneous objects in use. These include markers and -overlays, plus certain objects not visible to users. - -@item free-miscs -The number of miscellaneous objects for which space has been obtained -from the operating system, but that are not currently being used. - -@item used-string-chars -The total size of all strings, in characters. - -@item used-vector-slots -The total number of elements of existing vectors. - -@item used-floats -The number of floats in use. - -@item free-floats -The number of floats for which space has been obtained from the -operating system, but that are not currently being used. - -@item used-intervals -The number of intervals in use. Intervals are an internal -data structure used for representing text properties. - -@item free-intervals -The number of intervals for which space has been obtained -from the operating system, but that are not currently being used. - -@item used-strings -The number of strings in use. - -@item free-strings -The number of string headers for which the space was obtained from the -operating system, but which are currently not in use. (A string -object consists of a header and the storage for the string text -itself; the latter is only allocated when the string is created.) -@end table - -If there was overflow in pure space (@pxref{Pure Storage}), -@code{garbage-collect} returns @code{nil}, because a real garbage -collection cannot be done. -@end deffn - -@defopt garbage-collection-messages -If this variable is non-@code{nil}, Emacs displays a message at the -beginning and end of garbage collection. The default value is -@code{nil}. -@end defopt - -@defvar post-gc-hook -This is a normal hook that is run at the end of garbage collection. -Garbage collection is inhibited while the hook functions run, so be -careful writing them. -@end defvar - -@defopt gc-cons-threshold -The value of this variable is the number of bytes of storage that must -be allocated for Lisp objects after one garbage collection in order to -trigger another garbage collection. A cons cell counts as eight bytes, -a string as one byte per character plus a few bytes of overhead, and so -on; space allocated to the contents of buffers does not count. Note -that the subsequent garbage collection does not happen immediately when -the threshold is exhausted, but only the next time the Lisp evaluator is -called. - -The initial threshold value is 800,000. If you specify a larger -value, garbage collection will happen less often. This reduces the -amount of time spent garbage collecting, but increases total memory use. -You may want to do this when running a program that creates lots of -Lisp data. - -You can make collections more frequent by specifying a smaller value, -down to 10,000. A value less than 10,000 will remain in effect only -until the subsequent garbage collection, at which time -@code{garbage-collect} will set the threshold back to 10,000. -@end defopt - -@defopt gc-cons-percentage -The value of this variable specifies the amount of consing before a -garbage collection occurs, as a fraction of the current heap size. -This criterion and @code{gc-cons-threshold} apply in parallel, and -garbage collection occurs only when both criteria are satisfied. - -As the heap size increases, the time to perform a garbage collection -increases. Thus, it can be desirable to do them less frequently in -proportion. -@end defopt - - The value returned by @code{garbage-collect} describes the amount of -memory used by Lisp data, broken down by data type. By contrast, the -function @code{memory-limit} provides information on the total amount of -memory Emacs is currently using. - -@defun memory-limit -This function returns the address of the last byte Emacs has allocated, -divided by 1024. We divide the value by 1024 to make sure it fits in a -Lisp integer. - -You can use this to get a general idea of how your actions affect the -memory usage. -@end defun - -@defvar memory-full -This variable is @code{t} if Emacs is nearly out of memory for Lisp -objects, and @code{nil} otherwise. -@end defvar - -@defun memory-use-counts -This returns a list of numbers that count the number of objects -created in this Emacs session. Each of these counters increments for -a certain kind of object. See the documentation string for details. -@end defun - -@defvar gcs-done -This variable contains the total number of garbage collections -done so far in this Emacs session. -@end defvar - -@defvar gc-elapsed -This variable contains the total number of seconds of elapsed time -during garbage collection so far in this Emacs session, as a floating -point number. -@end defvar - -@node Memory Usage -@section Memory Usage -@cindex memory usage - - These functions and variables give information about the total amount -of memory allocation that Emacs has done, broken down by data type. -Note the difference between these and the values returned by -@code{garbage-collect}; those count objects that currently exist, but -these count the number or size of all allocations, including those for -objects that have since been freed. - -@defvar cons-cells-consed -The total number of cons cells that have been allocated so far -in this Emacs session. -@end defvar - -@defvar floats-consed -The total number of floats that have been allocated so far -in this Emacs session. -@end defvar - -@defvar vector-cells-consed -The total number of vector cells that have been allocated so far -in this Emacs session. -@end defvar - -@defvar symbols-consed -The total number of symbols that have been allocated so far -in this Emacs session. -@end defvar - -@defvar string-chars-consed -The total number of string characters that have been allocated so far -in this session. -@end defvar - -@defvar misc-objects-consed -The total number of miscellaneous objects that have been allocated so -far in this session. These include markers and overlays, plus -certain objects not visible to users. -@end defvar - -@defvar intervals-consed -The total number of intervals that have been allocated so far -in this Emacs session. -@end defvar - -@defvar strings-consed -The total number of strings that have been allocated so far in this -Emacs session. -@end defvar - -@node Writing Emacs Primitives -@section Writing Emacs Primitives -@cindex primitive function internals -@cindex writing Emacs primitives - - Lisp primitives are Lisp functions implemented in C. The details of -interfacing the C function so that Lisp can call it are handled by a few -C macros. The only way to really understand how to write new C code is -to read the source, but we can explain some things here. - - An example of a special form is the definition of @code{or}, from -@file{eval.c}. (An ordinary function would have the same general -appearance.) - -@cindex garbage collection protection -@smallexample -@group -DEFUN ("or", For, Sor, 0, UNEVALLED, 0, - doc: /* Eval args until one of them yields non-nil, then return -that value. -The remaining args are not evalled at all. -If all args return nil, return nil. -@end group -@group -usage: (or CONDITIONS ...) */) - (Lisp_Object args) -@{ - register Lisp_Object val = Qnil; - struct gcpro gcpro1; -@end group - -@group - GCPRO1 (args); -@end group - -@group - while (CONSP (args)) - @{ - val = eval_sub (XCAR (args)); - if (!NILP (val)) - break; - args = XCDR (args); - @} -@end group - -@group - UNGCPRO; - return val; -@} -@end group -@end smallexample - -@cindex @code{DEFUN}, C macro to define Lisp primitives - Let's start with a precise explanation of the arguments to the -@code{DEFUN} macro. Here is a template for them: - -@example -DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc}) -@end example - -@table @var -@item lname -This is the name of the Lisp symbol to define as the function name; in -the example above, it is @code{or}. - -@item fname -This is the C function name for this function. This is the name that -is used in C code for calling the function. The name is, by -convention, @samp{F} prepended to the Lisp name, with all dashes -(@samp{-}) in the Lisp name changed to underscores. Thus, to call -this function from C code, call @code{For}. - -@item sname -This is a C variable name to use for a structure that holds the data for -the subr object that represents the function in Lisp. This structure -conveys the Lisp symbol name to the initialization routine that will -create the symbol and store the subr object as its definition. By -convention, this name is always @var{fname} with @samp{F} replaced with -@samp{S}. - -@item min -This is the minimum number of arguments that the function requires. The -function @code{or} allows a minimum of zero arguments. - -@item max -This is the maximum number of arguments that the function accepts, if -there is a fixed maximum. Alternatively, it can be @code{UNEVALLED}, -indicating a special form that receives unevaluated arguments, or -@code{MANY}, indicating an unlimited number of evaluated arguments (the -equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY} are -macros. If @var{max} is a number, it must be more than @var{min} but -less than 8. - -@item interactive -This is an interactive specification, a string such as might be used as -the argument of @code{interactive} in a Lisp function. In the case of -@code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be -called interactively. A value of @code{""} indicates a function that -should receive no arguments when called interactively. If the value -begins with a @samp{(}, the string is evaluated as a Lisp form. -For examples of the last two forms, see @code{widen} and -@code{narrow-to-region} in @file{editfns.c}. - -@item doc -This is the documentation string. It uses C comment syntax rather -than C string syntax because comment syntax requires nothing special -to include multiple lines. The @samp{doc:} identifies the comment -that follows as the documentation string. The @samp{/*} and @samp{*/} -delimiters that begin and end the comment are not part of the -documentation string. - -If the last line of the documentation string begins with the keyword -@samp{usage:}, the rest of the line is treated as the argument list -for documentation purposes. This way, you can use different argument -names in the documentation string from the ones used in the C code. -@samp{usage:} is required if the function has an unlimited number of -arguments. - -All the usual rules for documentation strings in Lisp code -(@pxref{Documentation Tips}) apply to C code documentation strings -too. -@end table - - After the call to the @code{DEFUN} macro, you must write the -argument list for the C function, including the types for the -arguments. If the primitive accepts a fixed maximum number of Lisp -arguments, there must be one C argument for each Lisp argument, and -each argument must be of type @code{Lisp_Object}. (Various macros and -functions for creating values of type @code{Lisp_Object} are declared -in the file @file{lisp.h}.) If the primitive has no upper limit on -the number of Lisp arguments, it must have exactly two C arguments: -the first is the number of Lisp arguments, and the second is the -address of a block containing their values. These have types -@code{int} and @w{@code{Lisp_Object *}} respectively. - -@cindex @code{GCPRO} and @code{UNGCPRO} -@cindex protect C variables from garbage collection - Within the function @code{For} itself, note the use of the macros -@code{GCPRO1} and @code{UNGCPRO}. These macros are defined for the -sake of the few platforms which do not use Emacs' default -stack-marking garbage collector. The @code{GCPRO1} macro ``protects'' -a variable from garbage collection, explicitly informing the garbage -collector that that variable and all its contents must be as -accessible. GC protection is necessary in any function which can -perform Lisp evaluation by calling @code{eval_sub} or @code{Feval} as -a subroutine, either directly or indirectly. - - It suffices to ensure that at least one pointer to each object is -GC-protected. Thus, a particular local variable can do without -protection if it is certain that the object it points to will be -preserved by some other pointer (such as another local variable that -has a @code{GCPRO}). Otherwise, the local variable needs a -@code{GCPRO}. - - The macro @code{GCPRO1} protects just one local variable. If you -want to protect two variables, use @code{GCPRO2} instead; repeating -@code{GCPRO1} will not work. Macros @code{GCPRO3}, @code{GCPRO4}, -@code{GCPRO5}, and @code{GCPRO6} also exist. All these macros -implicitly use local variables such as @code{gcpro1}; you must declare -these explicitly, with type @code{struct gcpro}. Thus, if you use -@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}. - - @code{UNGCPRO} cancels the protection of the variables that are -protected in the current function. It is necessary to do this -explicitly. - - You must not use C initializers for static or global variables unless -the variables are never written once Emacs is dumped. These variables -with initializers are allocated in an area of memory that becomes -read-only (on certain operating systems) as a result of dumping Emacs. -@xref{Pure Storage}. - -@cindex @code{defsubr}, Lisp symbol for a primitive - Defining the C function is not enough to make a Lisp primitive -available; you must also create the Lisp symbol for the primitive and -store a suitable subr object in its function cell. The code looks like -this: - -@example -defsubr (&@var{sname}); -@end example - -@noindent -Here @var{sname} is the name you used as the third argument to @code{DEFUN}. - - If you add a new primitive to a file that already has Lisp primitives -defined in it, find the function (near the end of the file) named -@code{syms_of_@var{something}}, and add the call to @code{defsubr} -there. If the file doesn't have this function, or if you create a new -file, add to it a @code{syms_of_@var{filename}} (e.g., -@code{syms_of_myfile}). Then find the spot in @file{emacs.c} where all -of these functions are called, and add a call to -@code{syms_of_@var{filename}} there. - -@anchor{Defining Lisp variables in C} -@vindex byte-boolean-vars -@cindex defining Lisp variables in C -@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL} - The function @code{syms_of_@var{filename}} is also the place to define -any C variables that are to be visible as Lisp variables. -@code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible -in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int} -visible in Lisp with a value that is always an integer. -@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp -with a value that is either @code{t} or @code{nil}. Note that variables -defined with @code{DEFVAR_BOOL} are automatically added to the list -@code{byte-boolean-vars} used by the byte compiler. - -@cindex defining customization variables in C - If you want to make a Lisp variables that is defined in C behave -like one declared with @code{defcustom}, add an appropriate entry to -@file{cus-start.el}. - -@cindex @code{staticpro}, protection from GC - If you define a file-scope C variable of type @code{Lisp_Object}, -you must protect it from garbage-collection by calling @code{staticpro} -in @code{syms_of_@var{filename}}, like this: - -@example -staticpro (&@var{variable}); -@end example - - Here is another example function, with more complicated arguments. -This comes from the code in @file{window.c}, and it demonstrates the use -of macros and functions to manipulate Lisp objects. - -@smallexample -@group -DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p, - Scoordinates_in_window_p, 2, 2, 0, - doc: /* Return non-nil if COORDINATES are in WINDOW. - ... -@end group -@group - or `right-margin' is returned. */) - (register Lisp_Object coordinates, Lisp_Object window) -@{ - struct window *w; - struct frame *f; - int x, y; - Lisp_Object lx, ly; -@end group - -@group - CHECK_LIVE_WINDOW (window); - w = XWINDOW (window); - f = XFRAME (w->frame); - CHECK_CONS (coordinates); - lx = Fcar (coordinates); - ly = Fcdr (coordinates); - CHECK_NUMBER_OR_FLOAT (lx); - CHECK_NUMBER_OR_FLOAT (ly); - x = FRAME_PIXEL_X_FROM_CANON_X (f, lx) + FRAME_INTERNAL_BORDER_WIDTH(f); - y = FRAME_PIXEL_Y_FROM_CANON_Y (f, ly) + FRAME_INTERNAL_BORDER_WIDTH(f); -@end group - -@group - switch (coordinates_in_window (w, x, y)) - @{ - case ON_NOTHING: /* NOT in window at all. */ - return Qnil; -@end group - - ... - -@group - case ON_MODE_LINE: /* In mode line of window. */ - return Qmode_line; -@end group - - ... - -@group - case ON_SCROLL_BAR: /* On scroll-bar of window. */ - /* Historically we are supposed to return nil in this case. */ - return Qnil; -@end group - -@group - default: - abort (); - @} -@} -@end group -@end smallexample - - Note that C code cannot call functions by name unless they are defined -in C. The way to call a function written in Lisp is to use -@code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since -the Lisp function @code{funcall} accepts an unlimited number of -arguments, in C it takes two: the number of Lisp-level arguments, and a -one-dimensional array containing their values. The first Lisp-level -argument is the Lisp function to call, and the rest are the arguments to -pass to it. Since @code{Ffuncall} can call the evaluator, you must -protect pointers from garbage collection around the call to -@code{Ffuncall}. - - The C functions @code{call0}, @code{call1}, @code{call2}, and so on, -provide handy ways to call a Lisp function conveniently with a fixed -number of arguments. They work by calling @code{Ffuncall}. - - @file{eval.c} is a very good file to look through for examples; -@file{lisp.h} contains the definitions for some important macros and -functions. - - If you define a function which is side-effect free, update the code -in @file{byte-opt.el} that binds @code{side-effect-free-fns} and -@code{side-effect-and-error-free-fns} so that the compiler optimizer -knows about it. - -@node Object Internals -@section Object Internals -@cindex object internals - -@c FIXME Is this still true? Does --with-wide-int affect anything? - GNU Emacs Lisp manipulates many different types of data. The actual -data are stored in a heap and the only access that programs have to it -is through pointers. Each pointer is 32 bits wide on 32-bit machines, -and 64 bits wide on 64-bit machines; three of these bits are used for -the tag that identifies the object's type, and the remainder are used -to address the object. - - Because Lisp objects are represented as tagged pointers, it is always -possible to determine the Lisp data type of any object. The C data type -@code{Lisp_Object} can hold any Lisp object of any data type. Ordinary -variables have type @code{Lisp_Object}, which means they can hold any -type of Lisp value; you can determine the actual data type only at run -time. The same is true for function arguments; if you want a function -to accept only a certain type of argument, you must check the type -explicitly using a suitable predicate (@pxref{Type Predicates}). -@cindex type checking internals - -@menu -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end menu - -@node Buffer Internals -@subsection Buffer Internals -@cindex internals, of buffer -@cindex buffer internals - - Two structures (see @file{buffer.h}) are used to represent buffers -in C. The @code{buffer_text} structure contains fields describing the -text of a buffer; the @code{buffer} structure holds other fields. In -the case of indirect buffers, two or more @code{buffer} structures -reference the same @code{buffer_text} structure. - -Here are some of the fields in @code{struct buffer_text}: - -@table @code -@item beg -The address of the buffer contents. - -@item gpt -@itemx gpt_byte -The character and byte positions of the buffer gap. @xref{Buffer -Gap}. - -@item z -@itemx z_byte -The character and byte positions of the end of the buffer text. - -@item gap_size -The size of buffer's gap. @xref{Buffer Gap}. - -@item modiff -@itemx save_modiff -@itemx chars_modiff -@itemx overlay_modiff -These fields count the number of buffer-modification events performed -in this buffer. @code{modiff} is incremented after each -buffer-modification event, and is never otherwise changed; -@code{save_modiff} contains the value of @code{modiff} the last time -the buffer was visited or saved; @code{chars_modiff} counts only -modifications to the characters in the buffer, ignoring all other -kinds of changes; and @code{overlay_modiff} counts only modifications -to the overlays. - -@item beg_unchanged -@itemx end_unchanged -The number of characters at the start and end of the text that are -known to be unchanged since the last complete redisplay. - -@item unchanged_modified -@itemx overlay_unchanged_modified -The values of @code{modiff} and @code{overlay_modiff}, respectively, -after the last complete redisplay. If their current values match -@code{modiff} or @code{overlay_modiff}, that means -@code{beg_unchanged} and @code{end_unchanged} contain no useful -information. - -@item markers -The markers that refer to this buffer. This is actually a single -marker, and successive elements in its marker @code{chain} are the other -markers referring to this buffer text. - -@item intervals -The interval tree which records the text properties of this buffer. -@end table - -Some of the fields of @code{struct buffer} are: - -@table @code -@item header -A @code{struct vectorlike_header} structure where @code{header.next} -points to the next buffer, in the chain of all buffers (including -killed buffers). This chain is used only for garbage collection, in -order to collect killed buffers properly. Note that vectors, and most -kinds of objects allocated as vectors, are all on one chain, but -buffers are on a separate chain of their own. - -@item own_text -A @code{struct buffer_text} structure that ordinarily holds the buffer -contents. In indirect buffers, this field is not used. - -@item text -A pointer to the @code{buffer_text} structure for this buffer. In an -ordinary buffer, this is the @code{own_text} field above. In an -indirect buffer, this is the @code{own_text} field of the base buffer. - -@item pt -@itemx pt_byte -The character and byte positions of point in a buffer. - -@item begv -@itemx begv_byte -The character and byte positions of the beginning of the accessible -range of text in the buffer. - -@item zv -@itemx zv_byte -The character and byte positions of the end of the accessible range of -text in the buffer. - -@item base_buffer -In an indirect buffer, this points to the base buffer. In an ordinary -buffer, it is null. - -@item local_flags -This field contains flags indicating that certain variables are local -in this buffer. Such variables are declared in the C code using -@code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored -in fields in the buffer structure itself. (Some of these fields are -described in this table.) - -@item modtime -The modification time of the visited file. It is set when the file is -written or read. Before writing the buffer into a file, this field is -compared to the modification time of the file to see if the file has -changed on disk. @xref{Buffer Modification}. - -@item auto_save_modified -The time when the buffer was last auto-saved. - -@item last_window_start -The @code{window-start} position in the buffer as of the last time the -buffer was displayed in a window. - -@item clip_changed -This flag indicates that narrowing has changed in the buffer. -@xref{Narrowing}. - -@item prevent_redisplay_optimizations_p -This flag indicates that redisplay optimizations should not be used to -display this buffer. - -@item overlay_center -This field holds the current overlay center position. @xref{Managing -Overlays}. - -@item overlays_before -@itemx overlays_after -These fields hold, respectively, a list of overlays that end at or -before the current overlay center, and a list of overlays that end -after the current overlay center. @xref{Managing Overlays}. -@code{overlays_before} is sorted in order of decreasing end position, -and @code{overlays_after} is sorted in order of increasing beginning -position. - -@c FIXME? the following are now all Lisp_Object BUFFER_INTERNAL_FIELD (foo). - -@item name -A Lisp string that names the buffer. It is guaranteed to be unique. -@xref{Buffer Names}. - -@item save_length -The length of the file this buffer is visiting, when last read or -saved. This and other fields concerned with saving are not kept in -the @code{buffer_text} structure because indirect buffers are never -saved. - -@item directory -The directory for expanding relative file names. This is the value of -the buffer-local variable @code{default-directory} (@pxref{File Name Expansion}). - -@item filename -The name of the file visited in this buffer, or @code{nil}. This is -the value of the buffer-local variable @code{buffer-file-name} -(@pxref{Buffer File Name}). - -@item undo_list -@itemx backed_up -@itemx auto_save_file_name -@itemx auto_save_file_format -@itemx read_only -@itemx file_format -@itemx file_truename -@itemx invisibility_spec -@itemx display_count -@itemx display_time -These fields store the values of Lisp variables that are automatically -buffer-local (@pxref{Buffer-Local Variables}), whose corresponding -variable names have the additional prefix @code{buffer-} and have -underscores replaced with dashes. For instance, @code{undo_list} -stores the value of @code{buffer-undo-list}. - -@item mark -The mark for the buffer. The mark is a marker, hence it is also -included on the list @code{markers}. @xref{The Mark}. - -@item local_var_alist -The association list describing the buffer-local variable bindings of -this buffer, not including the built-in buffer-local bindings that -have special slots in the buffer object. (Those slots are omitted -from this table.) @xref{Buffer-Local Variables}. - -@item major_mode -Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}. - -@item mode_name -Pretty name of the major mode, e.g., @code{"Lisp"}. - -@item keymap -@itemx abbrev_table -@itemx syntax_table -@itemx category_table -@itemx display_table -These fields store the buffer's local keymap (@pxref{Keymaps}), abbrev -table (@pxref{Abbrev Tables}), syntax table (@pxref{Syntax Tables}), -category table (@pxref{Categories}), and display table (@pxref{Display -Tables}). - -@item downcase_table -@itemx upcase_table -@itemx case_canon_table -These fields store the conversion tables for converting text to lower -case, upper case, and for canonicalizing text for case-fold search. -@xref{Case Tables}. - -@item minor_modes -An alist of the minor modes of this buffer. - -@item pt_marker -@itemx begv_marker -@itemx zv_marker -These fields are only used in an indirect buffer, or in a buffer that -is the base of an indirect buffer. Each holds a marker that records -@code{pt}, @code{begv}, and @code{zv} respectively, for this buffer -when the buffer is not current. - -@item mode_line_format -@itemx header_line_format -@itemx case_fold_search -@itemx tab_width -@itemx fill_column -@itemx left_margin -@itemx auto_fill_function -@itemx truncate_lines -@itemx word_wrap -@itemx ctl_arrow -@itemx bidi_display_reordering -@itemx bidi_paragraph_direction -@itemx selective_display -@itemx selective_display_ellipses -@itemx overwrite_mode -@itemx abbrev_mode -@itemx mark_active -@itemx enable_multibyte_characters -@itemx buffer_file_coding_system -@itemx cache_long_line_scans -@itemx point_before_scroll -@itemx left_fringe_width -@itemx right_fringe_width -@itemx fringes_outside_margins -@itemx scroll_bar_width -@itemx indicate_empty_lines -@itemx indicate_buffer_boundaries -@itemx fringe_indicator_alist -@itemx fringe_cursor_alist -@itemx scroll_up_aggressively -@itemx scroll_down_aggressively -@itemx cursor_type -@itemx cursor_in_non_selected_windows -These fields store the values of Lisp variables that are automatically -buffer-local (@pxref{Buffer-Local Variables}), whose corresponding -variable names have underscores replaced with dashes. For instance, -@code{mode_line_format} stores the value of @code{mode-line-format}. - -@item last_selected_window -This is the last window that was selected with this buffer in it, or @code{nil} -if that window no longer displays this buffer. -@end table - -@node Window Internals -@subsection Window Internals -@cindex internals, of window -@cindex window internals - - The fields of a window (for a complete list, see the definition of -@code{struct window} in @file{window.h}) include: - -@table @code -@item frame -The frame that this window is on. - -@item mini_p -Non-@code{nil} if this window is a minibuffer window. - -@item parent -Internally, Emacs arranges windows in a tree; each group of siblings has -a parent window whose area includes all the siblings. This field points -to a window's parent. - -Parent windows do not display buffers, and play little role in display -except to shape their child windows. Emacs Lisp programs usually have -no access to the parent windows; they operate on the windows at the -leaves of the tree, which actually display buffers. - -@item hchild -@itemx vchild -These fields contain the window's leftmost child and its topmost child -respectively. @code{hchild} is used if the window is subdivided -horizontally by child windows, and @code{vchild} if it is subdivided -vertically. In a live window, only one of @code{hchild}, @code{vchild}, -and @code{buffer} (q.v.) is non-@code{nil}. - -@item next -@itemx prev -The next sibling and previous sibling of this window. @code{next} is -@code{nil} if the window is the right-most or bottom-most in its group; -@code{prev} is @code{nil} if it is the left-most or top-most in its -group. - -@item left_col -The left-hand edge of the window, measured in columns, relative to the -leftmost column in the frame (column 0). - -@item top_line -The top edge of the window, measured in lines, relative to the topmost -line in the frame (line 0). - -@item total_cols -@itemx total_lines -The width and height of the window, measured in columns and lines -respectively. The width includes the scroll bar and fringes, and/or -the separator line on the right of the window (if any). - -@item buffer -The buffer that the window is displaying. - -@item start -A marker pointing to the position in the buffer that is the first -character displayed in the window. - -@item pointm -@cindex window point internals -This is the value of point in the current buffer when this window is -selected; when it is not selected, it retains its previous value. - -@item force_start -If this flag is non-@code{nil}, it says that the window has been -scrolled explicitly by the Lisp program. This affects what the next -redisplay does if point is off the screen: instead of scrolling the -window to show the text around point, it moves point to a location that -is on the screen. - -@item frozen_window_start_p -This field is set temporarily to 1 to indicate to redisplay that -@code{start} of this window should not be changed, even if point -gets invisible. - -@item start_at_line_beg -Non-@code{nil} means current value of @code{start} was the beginning of a line -when it was chosen. - -@item use_time -This is the last time that the window was selected. The function -@code{get-lru-window} uses this field. - -@item sequence_number -A unique number assigned to this window when it was created. - -@item last_modified -The @code{modiff} field of the window's buffer, as of the last time -a redisplay completed in this window. - -@item last_overlay_modified -The @code{overlay_modiff} field of the window's buffer, as of the last -time a redisplay completed in this window. - -@item last_point -The buffer's value of point, as of the last time a redisplay completed -in this window. - -@item last_had_star -A non-@code{nil} value means the window's buffer was ``modified'' when the -window was last updated. - -@item vertical_scroll_bar -This window's vertical scroll bar. - -@item left_margin_cols -@itemx right_margin_cols -The widths of the left and right margins in this window. A value of -@code{nil} means no margin. - -@item left_fringe_width -@itemx right_fringe_width -The widths of the left and right fringes in this window. A value of -@code{nil} or @code{t} means use the values of the frame. - -@item fringes_outside_margins -A non-@code{nil} value means the fringes outside the display margins; -othersize they are between the margin and the text. - -@item window_end_pos -This is computed as @code{z} minus the buffer position of the last glyph -in the current matrix of the window. The value is only valid if -@code{window_end_valid} is not @code{nil}. - -@item window_end_bytepos -The byte position corresponding to @code{window_end_pos}. - -@item window_end_vpos -The window-relative vertical position of the line containing -@code{window_end_pos}. - -@item window_end_valid -This field is set to a non-@code{nil} value if @code{window_end_pos} is truly -valid. This is @code{nil} if nontrivial redisplay is pre-empted, since in that -case the display that @code{window_end_pos} was computed for did not get -onto the screen. - -@item cursor -A structure describing where the cursor is in this window. - -@item last_cursor -The value of @code{cursor} as of the last redisplay that finished. - -@item phys_cursor -A structure describing where the cursor of this window physically is. - -@item phys_cursor_type -@c FIXME What is this? -@c itemx phys_cursor_ascent -@itemx phys_cursor_height -@itemx phys_cursor_width -The type, height, and width of the cursor that was last displayed on -this window. - -@item phys_cursor_on_p -This field is non-zero if the cursor is physically on. - -@item cursor_off_p -Non-zero means the cursor in this window is logically off. This is -used for blinking the cursor. - -@item last_cursor_off_p -This field contains the value of @code{cursor_off_p} as of the time of -the last redisplay. - -@item must_be_updated_p -This is set to 1 during redisplay when this window must be updated. - -@item hscroll -This is the number of columns that the display in the window is scrolled -horizontally to the left. Normally, this is 0. - -@item vscroll -Vertical scroll amount, in pixels. Normally, this is 0. - -@item dedicated -Non-@code{nil} if this window is dedicated to its buffer. - -@item display_table -The window's display table, or @code{nil} if none is specified for it. - -@item update_mode_line -Non-@code{nil} means this window's mode line needs to be updated. - -@item base_line_number -The line number of a certain position in the buffer, or @code{nil}. -This is used for displaying the line number of point in the mode line. - -@item base_line_pos -The position in the buffer for which the line number is known, or -@code{nil} meaning none is known. If it is a buffer, don't display -the line number as long as the window shows that buffer. - -@item region_showing -If the region (or part of it) is highlighted in this window, this field -holds the mark position that made one end of that region. Otherwise, -this field is @code{nil}. - -@item column_number_displayed -The column number currently displayed in this window's mode line, or @code{nil} -if column numbers are not being displayed. - -@item current_matrix -@itemx desired_matrix -Glyph matrices describing the current and desired display of this window. -@end table - -@node Process Internals -@subsection Process Internals -@cindex internals, of process -@cindex process internals - - The fields of a process (for a complete list, see the definition of -@code{struct Lisp_Process} in @file{process.h}) include: - -@table @code -@item name -A string, the name of the process. - -@item command -A list containing the command arguments that were used to start this -process. For a network or serial process, it is @code{nil} if the -process is running or @code{t} if the process is stopped. - -@item filter -If non-@code{nil}, a function used to accept output from the process -instead of a buffer. - -@item sentinel -If non-@code{nil}, a function called whenever the state of the process -changes. - -@item buffer -The associated buffer of the process. - -@item pid -An integer, the operating system's process @acronym{ID}. -Pseudo-processes such as network or serial connections use a value of 0. - -@item childp -A flag, @code{t} if this is really a child process. For a network or -serial connection, it is a plist based on the arguments to -@code{make-network-process} or @code{make-serial-process}. - -@item mark -A marker indicating the position of the end of the last output from this -process inserted into the buffer. This is often but not always the end -of the buffer. - -@item kill_without_query -If this is non-zero, killing Emacs while this process is still running -does not ask for confirmation about killing the process. - -@item raw_status -The raw process status, as returned by the @code{wait} system call. - -@item status -The process status, as @code{process-status} should return it. - -@item tick -@itemx update_tick -If these two fields are not equal, a change in the status of the process -needs to be reported, either by running the sentinel or by inserting a -message in the process buffer. - -@item pty_flag -Non-@code{nil} if communication with the subprocess uses a @acronym{PTY}; -@code{nil} if it uses a pipe. - -@item infd -The file descriptor for input from the process. - -@item outfd -The file descriptor for output to the process. - -@item tty_name -The name of the terminal that the subprocess is using, -or @code{nil} if it is using pipes. - -@item decode_coding_system -Coding-system for decoding the input from this process. - -@item decoding_buf -A working buffer for decoding. - -@item decoding_carryover -Size of carryover in decoding. - -@item encode_coding_system -Coding-system for encoding the output to this process. - -@item encoding_buf -A working buffer for encoding. - -@item inherit_coding_system_flag -Flag to set @code{coding-system} of the process buffer from the -coding system used to decode process output. - -@item type -Symbol indicating the type of process: @code{real}, @code{network}, -@code{serial}. - -@end table - -@c FIXME Mention src/globals.h somewhere in this file? diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi deleted file mode 100644 index c221286fece..00000000000 --- a/doc/lispref/intro.texi +++ /dev/null @@ -1,553 +0,0 @@ -@c -*-coding: iso-latin-1-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/intro - -@node Introduction, Lisp Data Types, Top, Top -@comment node-name, next, previous, up -@chapter Introduction - - Most of the GNU Emacs text editor is written in the programming -language called Emacs Lisp. You can write new code in Emacs Lisp and -install it as an extension to the editor. However, Emacs Lisp is more -than a mere ``extension language''; it is a full computer programming -language in its own right. You can use it as you would any other -programming language. - - Because Emacs Lisp is designed for use in an editor, it has special -features for scanning and parsing text as well as features for handling -files, buffers, displays, subprocesses, and so on. Emacs Lisp is -closely integrated with the editing facilities; thus, editing commands -are functions that can also conveniently be called from Lisp programs, -and parameters for customization are ordinary Lisp variables. - - This manual attempts to be a full description of Emacs Lisp. For a -beginner's introduction to Emacs Lisp, see @cite{An Introduction to -Emacs Lisp Programming}, by Bob Chassell, also published by the Free -Software Foundation. This manual presumes considerable familiarity with -the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this -basic information. - - Generally speaking, the earlier chapters describe features of Emacs -Lisp that have counterparts in many programming languages, and later -chapters describe features that are peculiar to Emacs Lisp or relate -specifically to editing. - - This is -@iftex -edition @value{VERSION} of -@end iftex -the @cite{GNU Emacs Lisp Reference Manual}, -corresponding to Emacs version @value{EMACSVER}. - -@menu -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Version Info:: Which Emacs version is running? -* Acknowledgements:: The authors, editors, and sponsors of this manual. -@end menu - -@node Caveats -@section Caveats -@cindex bugs in this manual - - This manual has gone through numerous drafts. It is nearly complete -but not flawless. There are a few topics that are not covered, either -because we consider them secondary (such as most of the individual -modes) or because they are yet to be written. Because we are not able -to deal with them completely, we have left out several parts -intentionally. - - The manual should be fully correct in what it does cover, and it is -therefore open to criticism on anything it says---from specific examples -and descriptive text, to the ordering of chapters and sections. If -something is confusing, or you find that you have to look at the sources -or experiment to learn something not covered in the manual, then perhaps -the manual should be fixed. Please let us know. - -@iftex - As you use this manual, we ask that you mark pages with corrections so -you can later look them up and send them to us. If you think of a simple, -real-life example for a function or group of functions, please make an -effort to write it up and send it in. Please reference any comments to -the chapter name, section name, and function name, as appropriate, since -page numbers and chapter and section numbers will change and we may have -trouble finding the text you are talking about. Also state the version -of the edition you are criticizing. -@end iftex -@ifnottex - -As you use this manual, we ask that you send corrections as soon as you -find them. If you think of a simple, real life example for a function -or group of functions, please make an effort to write it up and send it -in. Please reference any comments to the node name and function or -variable name, as appropriate. Also state the number of the edition -you are criticizing. -@end ifnottex - -@cindex bugs -@cindex suggestions -Please send comments and corrections using @kbd{M-x report-emacs-bug}. - -@node Lisp History -@section Lisp History -@cindex Lisp history - - Lisp (LISt Processing language) was first developed in the late 1950s -at the Massachusetts Institute of Technology for research in artificial -intelligence. The great power of the Lisp language makes it ideal -for other purposes as well, such as writing editing commands. - -@cindex Maclisp -@cindex Common Lisp - Dozens of Lisp implementations have been built over the years, each -with its own idiosyncrasies. Many of them were inspired by Maclisp, -which was written in the 1960s at MIT's Project MAC. Eventually the -implementers of the descendants of Maclisp came together and developed a -standard for Lisp systems, called Common Lisp. In the meantime, Gerry -Sussman and Guy Steele at MIT developed a simplified but very powerful -dialect of Lisp, called Scheme. - - GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common -Lisp. If you know Common Lisp, you will notice many similarities. -However, many features of Common Lisp have been omitted or -simplified in order to reduce the memory requirements of GNU Emacs. -Sometimes the simplifications are so drastic that a Common Lisp user -might be very confused. We will occasionally point out how GNU Emacs -Lisp differs from Common Lisp. If you don't know Common Lisp, don't -worry about it; this manual is self-contained. - -@pindex cl - A certain amount of Common Lisp emulation is available via the -@file{cl} library. @xref{Top,, Overview, cl, Common Lisp Extensions}. - - Emacs Lisp is not at all influenced by Scheme; but the GNU project has -an implementation of Scheme, called Guile. We use it in all new GNU -software that calls for extensibility. - -@node Conventions -@section Conventions - -This section explains the notational conventions that are used in this -manual. You may want to skip this section and refer back to it later. - -@menu -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use when examples print text. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. -@end menu - -@node Some Terms -@subsection Some Terms - - Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp -printer'' refer to those routines in Lisp that convert textual -representations of Lisp objects into actual Lisp objects, and vice -versa. @xref{Printed Representation}, for more details. You, the -person reading this manual, are thought of as ``the programmer'' and are -addressed as ``you''. ``The user'' is the person who uses Lisp -programs, including those you write. - -@cindex typographic conventions - Examples of Lisp code are formatted like this: @code{(list 1 2 3)}. -Names that represent metasyntactic variables, or arguments to a function -being described, are formatted like this: @var{first-number}. - -@node nil and t -@subsection @code{nil} and @code{t} -@cindex truth value -@cindex boolean - -@cindex @code{nil} -@cindex false - In Emacs Lisp, the symbol @code{nil} has three separate meanings: it -is a symbol with the name @samp{nil}; it is the logical truth value -@var{false}; and it is the empty list---the list of zero elements. -When used as a variable, @code{nil} always has the value @code{nil}. - - As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are -identical: they stand for the same object, the symbol @code{nil}. The -different ways of writing the symbol are intended entirely for human -readers. After the Lisp reader has read either @samp{()} or @samp{nil}, -there is no way to determine which representation was actually written -by the programmer. - - In this manual, we write @code{()} when we wish to emphasize that it -means the empty list, and we write @code{nil} when we wish to emphasize -that it means the truth value @var{false}. That is a good convention to use -in Lisp programs also. - -@example -(cons 'foo ()) ; @r{Emphasize the empty list} -(setq foo-flag nil) ; @r{Emphasize the truth value @var{false}} -@end example - -@cindex @code{t} -@cindex true - In contexts where a truth value is expected, any non-@code{nil} value -is considered to be @var{true}. However, @code{t} is the preferred way -to represent the truth value @var{true}. When you need to choose a -value which represents @var{true}, and there is no other basis for -choosing, use @code{t}. The symbol @code{t} always has the value -@code{t}. - - In Emacs Lisp, @code{nil} and @code{t} are special symbols that always -evaluate to themselves. This is so that you do not need to quote them -to use them as constants in a program. An attempt to change their -values results in a @code{setting-constant} error. @xref{Constant -Variables}. - -@defun booleanp object -Return non-@code{nil} if @var{object} is one of the two canonical -boolean values: @code{t} or @code{nil}. -@end defun - -@node Evaluation Notation -@subsection Evaluation Notation -@cindex evaluation notation -@cindex documentation notation -@cindex notation - - A Lisp expression that you can evaluate is called a @dfn{form}. -Evaluating a form always produces a result, which is a Lisp object. In -the examples in this manual, this is indicated with @samp{@result{}}: - -@example -(car '(1 2)) - @result{} 1 -@end example - -@noindent -You can read this as ``@code{(car '(1 2))} evaluates to 1''. - - When a form is a macro call, it expands into a new form for Lisp to -evaluate. We show the result of the expansion with -@samp{@expansion{}}. We may or may not show the result of the -evaluation of the expanded form. - -@example -(third '(a b c)) - @expansion{} (car (cdr (cdr '(a b c)))) - @result{} c -@end example - - Sometimes to help describe one form we show another form that -produces identical results. The exact equivalence of two forms is -indicated with @samp{@equiv{}}. - -@example -(make-sparse-keymap) @equiv{} (list 'keymap) -@end example - -@node Printing Notation -@subsection Printing Notation -@cindex printing notation - - Many of the examples in this manual print text when they are -evaluated. If you execute example code in a Lisp Interaction buffer -(such as the buffer @file{*scratch*}), the printed text is inserted into -the buffer. If you execute the example by other means (such as by -evaluating the function @code{eval-region}), the printed text is -displayed in the echo area. - - Examples in this manual indicate printed text with @samp{@print{}}, -irrespective of where that text goes. The value returned by -evaluating the form follows on a separate line with -@samp{@result{}}. - -@example -@group -(progn (prin1 'foo) (princ "\n") (prin1 'bar)) - @print{} foo - @print{} bar - @result{} bar -@end group -@end example - -@node Error Messages -@subsection Error Messages -@cindex error message notation - - Some examples signal errors. This normally displays an error message -in the echo area. We show the error message on a line starting with -@samp{@error{}}. Note that @samp{@error{}} itself does not appear in -the echo area. - -@example -(+ 23 'x) -@error{} Wrong type argument: number-or-marker-p, x -@end example - -@node Buffer Text Notation -@subsection Buffer Text Notation -@cindex buffer text notation - - Some examples describe modifications to the contents of a buffer, by -showing the ``before'' and ``after'' versions of the text. These -examples show the contents of the buffer in question between two lines -of dashes containing the buffer name. In addition, @samp{@point{}} -indicates the location of point. (The symbol for point, of course, is -not part of the text in the buffer; it indicates the place -@emph{between} two characters where point is currently located.) - -@example ----------- Buffer: foo ---------- -This is the @point{}contents of foo. ----------- Buffer: foo ---------- - -(insert "changed ") - @result{} nil ----------- Buffer: foo ---------- -This is the changed @point{}contents of foo. ----------- Buffer: foo ---------- -@end example - -@node Format of Descriptions -@subsection Format of Descriptions -@cindex description format - - Functions, variables, macros, commands, user options, and special -forms are described in this manual in a uniform format. The first -line of a description contains the name of the item followed by its -arguments, if any. -@ifnottex -The category---function, variable, or whatever---appears at the -beginning of the line. -@end ifnottex -@iftex -The category---function, variable, or whatever---is printed next to the -right margin. -@end iftex -The description follows on succeeding lines, sometimes with examples. - -@menu -* A Sample Function Description:: A description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, - @code{electric-future-map}. -@end menu - -@node A Sample Function Description -@subsubsection A Sample Function Description -@cindex function descriptions -@cindex command descriptions -@cindex macro descriptions -@cindex special form descriptions - - In a function description, the name of the function being described -appears first. It is followed on the same line by a list of argument -names. These names are also used in the body of the description, to -stand for the values of the arguments. - - The appearance of the keyword @code{&optional} in the argument list -indicates that the subsequent arguments may be omitted (omitted -arguments default to @code{nil}). Do not write @code{&optional} when -you call the function. - - The keyword @code{&rest} (which must be followed by a single -argument name) indicates that any number of arguments can follow. The -single argument name following @code{&rest} will receive, as its -value, a list of all the remaining arguments passed to the function. -Do not write @code{&rest} when you call the function. - - Here is a description of an imaginary function @code{foo}: - -@defun foo integer1 &optional integer2 &rest integers -The function @code{foo} subtracts @var{integer1} from @var{integer2}, -then adds all the rest of the arguments to the result. If @var{integer2} -is not supplied, then the number 19 is used by default. - -@example -(foo 1 5 3 9) - @result{} 16 -(foo 5) - @result{} 14 -@end example - -@need 1500 -More generally, - -@example -(foo @var{w} @var{x} @var{y}@dots{}) -@equiv{} -(+ (- @var{x} @var{w}) @var{y}@dots{}) -@end example -@end defun - - Any argument whose name contains the name of a type (e.g., -@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that -type. A plural of a type (such as @var{buffers}) often means a list of -objects of that type. Arguments named @var{object} may be of any type. -(@xref{Lisp Data Types}, for a list of Emacs object types.) Arguments -with other sorts of names (e.g., @var{new-file}) are discussed -specifically in the description of the function. In some sections, -features common to the arguments of several functions are described at -the beginning. - - @xref{Lambda Expressions}, for a more complete description of optional -and rest arguments. - - Command, macro, and special form descriptions have the same format, -but the word `Function' is replaced by `Command', `Macro', or `Special -Form', respectively. Commands are simply functions that may be called -interactively; macros process their arguments differently from functions -(the arguments are not evaluated), but are presented the same way. - - The descriptions of macros and special forms use a more complex -notation to specify optional and repeated arguments, because they can -break the argument list down into separate arguments in more -complicated ways. @samp{@r{[}@var{optional-arg}@r{]}} means that -@var{optional-arg} is optional and @samp{@var{repeated-args}@dots{}} -stands for zero or more arguments. Parentheses are used when several -arguments are grouped into additional levels of list structure. Here -is an example: - -@defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} -This imaginary special form implements a loop that executes the -@var{body} forms and then increments the variable @var{var} on each -iteration. On the first iteration, the variable has the value -@var{from}; on subsequent iterations, it is incremented by one (or by -@var{inc} if that is given). The loop exits before executing @var{body} -if @var{var} equals @var{to}. Here is an example: - -@example -(count-loop (i 0 10) - (prin1 i) (princ " ") - (prin1 (aref vector i)) - (terpri)) -@end example - -If @var{from} and @var{to} are omitted, @var{var} is bound to -@code{nil} before the loop begins, and the loop exits if @var{var} is -non-@code{nil} at the beginning of an iteration. Here is an example: - -@example -(count-loop (done) - (if (pending) - (fixit) - (setq done t))) -@end example - -In this special form, the arguments @var{from} and @var{to} are -optional, but must both be present or both absent. If they are present, -@var{inc} may optionally be specified as well. These arguments are -grouped with the argument @var{var} into a list, to distinguish them -from @var{body}, which includes all remaining elements of the form. -@end defspec - -@node A Sample Variable Description -@subsubsection A Sample Variable Description -@cindex variable descriptions -@cindex option descriptions - - A @dfn{variable} is a name that can hold a value. Although nearly -all variables can be set by the user, certain variables exist -specifically so that users can change them; these are called @dfn{user -options}. Ordinary variables and user options are described using a -format like that for functions except that there are no arguments. - - Here is a description of the imaginary @code{electric-future-map} -variable.@refill - -@defvar electric-future-map -The value of this variable is a full keymap used by Electric Command -Future mode. The functions in this map allow you to edit commands you -have not yet thought about executing. -@end defvar - - User option descriptions have the same format, but `Variable' is -replaced by `User Option'. - -@node Version Info -@section Version Information - - These facilities provide information about which version of Emacs is -in use. - -@deffn Command emacs-version &optional here -This function returns a string describing the version of Emacs that is -running. It is useful to include this string in bug reports. - -@smallexample -@group -(emacs-version) - @result{} "GNU Emacs 23.1 (i686-pc-linux-gnu, GTK+ Version 2.14.4) - of 2009-06-01 on cyd.mit.edu" -@end group -@end smallexample - -If @var{here} is non-@code{nil}, it inserts the text in the buffer -before point, and returns @code{nil}. When this function is called -interactively, it prints the same information in the echo area, but -giving a prefix argument makes @var{here} non-@code{nil}. -@end deffn - -@defvar emacs-build-time -The value of this variable indicates the time at which Emacs was -built. It is a list of three integers, like the value of -@code{current-time} (@pxref{Time of Day}). - -@example -@group -emacs-build-time - @result{} (18846 52016 156039) -@end group -@end example -@end defvar - -@defvar emacs-version -The value of this variable is the version of Emacs being run. It is a -string such as @code{"23.1.1"}. The last number in this string is not -really part of the Emacs release version number; it is incremented -each time you build Emacs in any given directory. A value with four -numeric components, such as @code{"22.0.91.1"}, indicates an -unreleased test version. -@end defvar - -@defvar emacs-major-version -The major version number of Emacs, as an integer. For Emacs version -23.1, the value is 23. -@end defvar - -@defvar emacs-minor-version -The minor version number of Emacs, as an integer. For Emacs version -23.1, the value is 1. -@end defvar - -@node Acknowledgements -@section Acknowledgements - - This manual was originally written by Robert Krawitz, Bil Lewis, Dan -LaLiberte, Richard@tie{}M. Stallman and Chris Welty, the volunteers of -the GNU manual group, in an effort extending over several years. -Robert@tie{}J. Chassell helped to review and edit the manual, with the -support of the Defense Advanced Research Projects Agency, ARPA Order -6082, arranged by Warren@tie{}A. Hunt, Jr.@: of Computational Logic, -Inc. Additional sections have since been written by Miles Bader, Lars -Brinkhoff, Chong Yidong, Kenichi Handa, Lute Kamstra, Juri Linkov, -Glenn Morris, Thien-Thi Nguyen, Dan Nicolaescu, Martin Rudalics, Kim -F. Storm, Luc Teirlinck, and Eli Zaretskii, and others. - - Corrections were supplied by Drew Adams, Juanma Barranquero, Karl -Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David Boyes, Alan -Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch, David -A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf Fassel, -Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow, Jesper -Harder, George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak -Kirman, Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, -K. Richard Magill, Brian Marick, Roland McGrath, Stefan Monnier, Skip -Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potorti, -Friedrich Pukelsheim, Arnold D. Robbins, Raul Rockwell, Jason Rumney, -Per Starbäck, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, Bill -Trost, Rickard Westman, Jean White, Eduard Wiebe, Matthew Wilding, -Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn. - - For a more complete list of contributors, please see the relevant -ChangeLog file in the Emacs sources. diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi deleted file mode 100644 index 2cec68719b6..00000000000 --- a/doc/lispref/keymaps.texi +++ /dev/null @@ -1,2813 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/keymaps -@node Keymaps, Modes, Command Loop, Top -@chapter Keymaps -@cindex keymap - - The command bindings of input events are recorded in data structures -called @dfn{keymaps}. Each entry in a keymap associates (or -@dfn{binds}) an individual event type, either to another keymap or to -a command. When an event type is bound to a keymap, that keymap is -used to look up the next input event; this continues until a command -is found. The whole process is called @dfn{key lookup}. - -@menu -* Key Sequences:: Key sequences as Lisp objects. -* Keymap Basics:: Basic concepts of keymaps. -* Format of Keymaps:: What a keymap looks like as a Lisp object. -* Creating Keymaps:: Functions to create and copy keymaps. -* Inheritance and Keymaps:: How one keymap can inherit the bindings - of another keymap. -* Prefix Keys:: Defining a key with a keymap as its definition. -* Active Keymaps:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A minor mode can also override them. -* Key Lookup:: Finding a key's binding in one keymap. -* Functions for Key Lookup:: How to request key lookup. -* Changing Key Bindings:: Redefining a key in a keymap. -* Remapping Commands:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* Key Binding Commands:: Interactive interfaces for redefining keys. -* Scanning Keymaps:: Looking through all keymaps, for printing help. -* Menu Keymaps:: Defining a menu as a keymap. -@end menu - -@node Key Sequences -@section Key Sequences -@cindex key -@cindex keystroke -@cindex key sequence - - A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one -or more input events that form a unit. Input events include -characters, function keys, and mouse actions (@pxref{Input Events}). -The Emacs Lisp representation for a key sequence is a string or -vector. Unless otherwise stated, any Emacs Lisp function that accepts -a key sequence as an argument can handle both representations. - - In the string representation, alphanumeric characters ordinarily -stand for themselves; for example, @code{"a"} represents @kbd{a} -and @code{"2"} represents @kbd{2}. Control character events are -prefixed by the substring @code{"\C-"}, and meta characters by -@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}. -In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events -are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and -@code{"\d"} respectively. The string representation of a complete key -sequence is the concatenation of the string representations of the -constituent events; thus, @code{"\C-xl"} represents the key sequence -@kbd{C-x l}. - - Key sequences containing function keys, mouse button events, or -non-@acronym{ASCII} characters such as @kbd{C-=} or @kbd{H-a} cannot be -represented as strings; they have to be represented as vectors. - - In the vector representation, each element of the vector represents -an input event, in its Lisp form. @xref{Input Events}. For example, -the vector @code{[?\C-x ?l]} represents the key sequence @kbd{C-x l}. - - For examples of key sequences written in string and vector -representations, @ref{Init Rebinding,,, emacs, The GNU Emacs Manual}. - -@defmac kbd keyseq-text -This macro converts the text @var{keyseq-text} (a string constant) -into a key sequence (a string or vector constant). The contents of -@var{keyseq-text} should describe the key sequence using almost the same -syntax used in this manual. More precisely, it uses the same syntax -that Edit Macro mode uses for editing keyboard macros (@pxref{Edit -Keyboard Macro,,, emacs, The GNU Emacs Manual}); you must surround -function key names with @samp{<@dots{}>}. - -@example -(kbd "C-x") @result{} "\C-x" -(kbd "C-x C-f") @result{} "\C-x\C-f" -(kbd "C-x 4 C-f") @result{} "\C-x4\C-f" -(kbd "X") @result{} "X" -(kbd "RET") @result{} "\^M" -(kbd "C-c SPC") @result{} "\C-c@ " -(kbd " SPC") @result{} [f1 32] -(kbd "C-M-") @result{} [C-M-down] -@end example - -This macro is not meant for use with arguments that vary---only -with string constants. -@end defmac - -@node Keymap Basics -@section Keymap Basics -@cindex key binding -@cindex binding of a key -@cindex complete key -@cindex undefined key - - A keymap is a Lisp data structure that specifies @dfn{key bindings} -for various key sequences. - - A single keymap directly specifies definitions for individual -events. When a key sequence consists of a single event, its binding -in a keymap is the keymap's definition for that event. The binding of -a longer key sequence is found by an iterative process: first find the -definition of the first event (which must itself be a keymap); then -find the second event's definition in that keymap, and so on until all -the events in the key sequence have been processed. - - If the binding of a key sequence is a keymap, we call the key sequence -a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because -no more events can be added to it). If the binding is @code{nil}, -we call the key @dfn{undefined}. Examples of prefix keys are @kbd{C-c}, -@kbd{C-x}, and @kbd{C-x 4}. Examples of defined complete keys are -@kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}. Examples of undefined complete -keys are @kbd{C-x C-g}, and @kbd{C-c 3}. @xref{Prefix Keys}, for more -details. - - The rule for finding the binding of a key sequence assumes that the -intermediate bindings (found for the events before the last) are all -keymaps; if this is not so, the sequence of events does not form a -unit---it is not really one key sequence. In other words, removing one -or more events from the end of any valid key sequence must always yield -a prefix key. For example, @kbd{C-f C-n} is not a key sequence; -@kbd{C-f} is not a prefix key, so a longer sequence starting with -@kbd{C-f} cannot be a key sequence. - - The set of possible multi-event key sequences depends on the bindings -for prefix keys; therefore, it can be different for different keymaps, -and can change when bindings are changed. However, a one-event sequence -is always a key sequence, because it does not depend on any prefix keys -for its well-formedness. - - At any time, several primary keymaps are @dfn{active}---that is, in -use for finding key bindings. These are the @dfn{global map}, which is -shared by all buffers; the @dfn{local keymap}, which is usually -associated with a specific major mode; and zero or more @dfn{minor mode -keymaps}, which belong to currently enabled minor modes. (Not all minor -modes have keymaps.) The local keymap bindings shadow (i.e., take -precedence over) the corresponding global bindings. The minor mode -keymaps shadow both local and global keymaps. @xref{Active Keymaps}, -for details. - -@node Format of Keymaps -@section Format of Keymaps -@cindex format of keymaps -@cindex keymap format -@cindex full keymap -@cindex sparse keymap - - Each keymap is a list whose @sc{car} is the symbol @code{keymap}. The -remaining elements of the list define the key bindings of the keymap. -A symbol whose function definition is a keymap is also a keymap. Use -the function @code{keymapp} (see below) to test whether an object is a -keymap. - - Several kinds of elements may appear in a keymap, after the symbol -@code{keymap} that begins it: - -@table @code -@item (@var{type} .@: @var{binding}) -This specifies one binding, for events of type @var{type}. Each -ordinary binding applies to events of a particular @dfn{event type}, -which is always a character or a symbol. @xref{Classifying Events}. -In this kind of binding, @var{binding} is a command. - -@item (@var{type} @var{item-name} .@: @var{binding}) -This specifies a binding which is also a simple menu item that -displays as @var{item-name} in the menu. @xref{Simple Menu Items}. - -@item (@var{type} @var{item-name} @var{help-string} .@: @var{binding}) -This is a simple menu item with help string @var{help-string}. - -@item (@var{type} menu-item .@: @var{details}) -This specifies a binding which is also an extended menu item. This -allows use of other features. @xref{Extended Menu Items}. - -@item (t .@: @var{binding}) -@cindex default key binding -This specifies a @dfn{default key binding}; any event not bound by other -elements of the keymap is given @var{binding} as its binding. Default -bindings allow a keymap to bind all possible event types without having -to enumerate all of them. A keymap that has a default binding -completely masks any lower-precedence keymap, except for events -explicitly bound to @code{nil} (see below). - -@item @var{char-table} -If an element of a keymap is a char-table, it counts as holding -bindings for all character events with no modifier bits -(@pxref{modifier bits}): element @var{n} is the binding for the -character with code @var{n}. This is a compact way to record lots of -bindings. A keymap with such a char-table is called a @dfn{full -keymap}. Other keymaps are called @dfn{sparse keymaps}. - -@item @var{string} -@cindex keymap prompt string -@cindex overall prompt string -@cindex prompt string of keymap -Aside from elements that specify bindings for keys, a keymap can also -have a string as an element. This is called the @dfn{overall prompt -string} and makes it possible to use the keymap as a menu. -@xref{Defining Menus}. -@end table - -When the binding is @code{nil}, it doesn't constitute a definition -but it does take precedence over a default binding or a binding in the -parent keymap. On the other hand, a binding of @code{nil} does -@emph{not} override lower-precedence keymaps; thus, if the local map -gives a binding of @code{nil}, Emacs uses the binding from the -global map. - -@cindex meta characters lookup - Keymaps do not directly record bindings for the meta characters. -Instead, meta characters are regarded for purposes of key lookup as -sequences of two characters, the first of which is @key{ESC} (or -whatever is currently the value of @code{meta-prefix-char}). Thus, the -key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its -global binding is found at the slot for @kbd{a} in @code{esc-map} -(@pxref{Prefix Keys}). - - This conversion applies only to characters, not to function keys or -other input events; thus, @kbd{M-@key{end}} has nothing to do with -@kbd{@key{ESC} @key{end}}. - - Here as an example is the local keymap for Lisp mode, a sparse -keymap. It defines bindings for @key{DEL}, @kbd{C-c C-z}, -@kbd{C-M-q}, and @kbd{C-M-x} (the actual value also contains a menu -binding, which is omitted here for the sake of brevity). - -@example -@group -lisp-mode-map -@result{} -@end group -@group -(keymap - (3 keymap - ;; @kbd{C-c C-z} - (26 . run-lisp)) -@end group -@group - (27 keymap - ;; @r{@kbd{C-M-x}, treated as @kbd{@key{ESC} C-x}} - (24 . lisp-send-defun)) -@end group -@group - ;; @r{This part is inherited from @code{lisp-mode-shared-map}.} - keymap - ;; @key{DEL} - (127 . backward-delete-char-untabify) -@end group -@group - (27 keymap - ;; @r{@kbd{C-M-q}, treated as @kbd{@key{ESC} C-q}} - (17 . indent-sexp))) -@end group -@end example - -@defun keymapp object -This function returns @code{t} if @var{object} is a keymap, @code{nil} -otherwise. More precisely, this function tests for a list whose -@sc{car} is @code{keymap}, or for a symbol whose function definition -satisfies @code{keymapp}. - -@example -@group -(keymapp '(keymap)) - @result{} t -@end group -@group -(fset 'foo '(keymap)) -(keymapp 'foo) - @result{} t -@end group -@group -(keymapp (current-global-map)) - @result{} t -@end group -@end example -@end defun - -@node Creating Keymaps -@section Creating Keymaps -@cindex creating keymaps - - Here we describe the functions for creating keymaps. - -@defun make-sparse-keymap &optional prompt -This function creates and returns a new sparse keymap with no entries. -(A sparse keymap is the kind of keymap you usually want.) The new -keymap does not contain a char-table, unlike @code{make-keymap}, and -does not bind any events. - -@example -@group -(make-sparse-keymap) - @result{} (keymap) -@end group -@end example - -If you specify @var{prompt}, that becomes the overall prompt string -for the keymap. You should specify this only for menu keymaps -(@pxref{Defining Menus}). A keymap with an overall prompt string will -always present a mouse menu or a keyboard menu if it is active for -looking up the next input event. Don't specify an overall prompt string -for the main map of a major or minor mode, because that would cause -the command loop to present a keyboard menu every time. -@end defun - -@defun make-keymap &optional prompt -This function creates and returns a new full keymap. That keymap -contains a char-table (@pxref{Char-Tables}) with slots for all -characters without modifiers. The new keymap initially binds all -these characters to @code{nil}, and does not bind any other kind of -event. The argument @var{prompt} specifies a -prompt string, as in @code{make-sparse-keymap}. - -@example -@group -(make-keymap) - @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap]) -@end group -@end example - -A full keymap is more efficient than a sparse keymap when it holds -lots of bindings; for just a few, the sparse keymap is better. -@end defun - -@defun copy-keymap keymap -This function returns a copy of @var{keymap}. Any keymaps that -appear directly as bindings in @var{keymap} are also copied recursively, -and so on to any number of levels. However, recursive copying does not -take place when the definition of a character is a symbol whose function -definition is a keymap; the same symbol appears in the new copy. -@c Emacs 19 feature - -@example -@group -(setq map (copy-keymap (current-local-map))) -@result{} (keymap -@end group -@group - ;; @r{(This implements meta characters.)} - (27 keymap - (83 . center-paragraph) - (115 . center-line)) - (9 . tab-to-tab-stop)) -@end group - -@group -(eq map (current-local-map)) - @result{} nil -@end group -@group -(equal map (current-local-map)) - @result{} t -@end group -@end example -@end defun - -@node Inheritance and Keymaps -@section Inheritance and Keymaps -@cindex keymap inheritance -@cindex inheriting a keymap's bindings - - A keymap can inherit the bindings of another keymap, which we call the -@dfn{parent keymap}. Such a keymap looks like this: - -@example -(keymap @var{elements}@dots{} . @var{parent-keymap}) -@end example - -@noindent -The effect is that this keymap inherits all the bindings of -@var{parent-keymap}, whatever they may be at the time a key is looked up, -but can add to them or override them with @var{elements}. - -If you change the bindings in @var{parent-keymap} using -@code{define-key} or other key-binding functions, these changed -bindings are visible in the inheriting keymap, unless shadowed by the -bindings made by @var{elements}. The converse is not true: if you use -@code{define-key} to change bindings in the inheriting keymap, these -changes are recorded in @var{elements}, but have no effect on -@var{parent-keymap}. - -The proper way to construct a keymap with a parent is to use -@code{set-keymap-parent}; if you have code that directly constructs a -keymap with a parent, please convert the program to use -@code{set-keymap-parent} instead. - -@defun keymap-parent keymap -This returns the parent keymap of @var{keymap}. If @var{keymap} -has no parent, @code{keymap-parent} returns @code{nil}. -@end defun - -@defun set-keymap-parent keymap parent -This sets the parent keymap of @var{keymap} to @var{parent}, and returns -@var{parent}. If @var{parent} is @code{nil}, this function gives -@var{keymap} no parent at all. - -If @var{keymap} has submaps (bindings for prefix keys), they too receive -new parent keymaps that reflect what @var{parent} specifies for those -prefix keys. -@end defun - - Here is an example showing how to make a keymap that inherits -from @code{text-mode-map}: - -@example -(let ((map (make-sparse-keymap))) - (set-keymap-parent map text-mode-map) - map) -@end example - - A non-sparse keymap can have a parent too, but this is not very -useful. A non-sparse keymap always specifies something as the binding -for every numeric character code without modifier bits, even if it is -@code{nil}, so these character's bindings are never inherited from -the parent keymap. - -@cindex keymap inheritance from multiple maps - Sometimes you want to make a keymap that inherits from more than one -map. You can use the function @code{make-composed-keymap} for this. - -@defun make-composed-keymap maps &optional parent -This function returns a new keymap composed of the existing keymap(s) -@var{maps}, and optionally inheriting from a parent keymap -@var{parent}. @var{maps} can be a single keymap or a list of more -than one. When looking up a key in the resulting new map, Emacs -searches in each of the @var{maps} in turn, and then in @var{parent}, -stopping at the first match. A @code{nil} binding in any one of -@var{maps} overrides any binding in @var{parent}, but it does not -override any non-@code{nil} binding in any other of the @var{maps}. -@end defun - -@noindent For example, here is how Emacs sets the parent of -@code{help-mode-map}, such that it inherits from both -@code{button-buffer-map} and @code{special-mode-map}: - -@example -(defvar help-mode-map - (let ((map (make-sparse-keymap))) - (set-keymap-parent map (make-composed-keymap button-buffer-map - special-mode-map)) - ... map) ... ) -@end example - - -@node Prefix Keys -@section Prefix Keys -@cindex prefix key - - A @dfn{prefix key} is a key sequence whose binding is a keymap. The -keymap defines what to do with key sequences that extend the prefix key. -For example, @kbd{C-x} is a prefix key, and it uses a keymap that is -also stored in the variable @code{ctl-x-map}. This keymap defines -bindings for key sequences starting with @kbd{C-x}. - - Some of the standard Emacs prefix keys use keymaps that are -also found in Lisp variables: - -@itemize @bullet -@item -@vindex esc-map -@findex ESC-prefix -@code{esc-map} is the global keymap for the @key{ESC} prefix key. Thus, -the global definitions of all meta characters are actually found here. -This map is also the function definition of @code{ESC-prefix}. - -@item -@cindex @kbd{C-h} -@code{help-map} is the global keymap for the @kbd{C-h} prefix key. - -@item -@cindex @kbd{C-c} -@vindex mode-specific-map -@code{mode-specific-map} is the global keymap for the prefix key -@kbd{C-c}. This map is actually global, not mode-specific, but its name -provides useful information about @kbd{C-c} in the output of @kbd{C-h b} -(@code{display-bindings}), since the main use of this prefix key is for -mode-specific bindings. - -@item -@cindex @kbd{C-x} -@vindex ctl-x-map -@findex Control-X-prefix -@code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key. -This map is found via the function cell of the symbol -@code{Control-X-prefix}. - -@item -@cindex @kbd{C-x @key{RET}} -@vindex mule-keymap -@code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}} -prefix key. - -@item -@cindex @kbd{C-x 4} -@vindex ctl-x-4-map -@code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix -key. - -@item -@cindex @kbd{C-x 5} -@vindex ctl-x-5-map -@code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix -key. - -@item -@cindex @kbd{C-x 6} -@vindex 2C-mode-map -@code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix -key. - -@item -@cindex @kbd{C-x v} -@vindex vc-prefix-map -@code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix -key. - -@item -@cindex @kbd{M-g} -@vindex goto-map -@code{goto-map} is the global keymap used for the @kbd{M-g} prefix -key. - -@item -@cindex @kbd{M-s} -@vindex search-map -@code{search-map} is the global keymap used for the @kbd{M-s} prefix -key. - -@item -@cindex @kbd{M-o} -@vindex facemenu-keymap -@code{facemenu-keymap} is the global keymap used for the @kbd{M-o} -prefix key. - -@item -The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x -@key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps that have -no special names. -@end itemize - - The keymap binding of a prefix key is used for looking up the event -that follows the prefix key. (It may instead be a symbol whose function -definition is a keymap. The effect is the same, but the symbol serves -as a name for the prefix key.) Thus, the binding of @kbd{C-x} is the -symbol @code{Control-X-prefix}, whose function cell holds the keymap -for @kbd{C-x} commands. (The same keymap is also the value of -@code{ctl-x-map}.) - - Prefix key definitions can appear in any active keymap. The -definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix -keys appear in the global map, so these prefix keys are always -available. Major and minor modes can redefine a key as a prefix by -putting a prefix key definition for it in the local map or the minor -mode's map. @xref{Active Keymaps}. - - If a key is defined as a prefix in more than one active map, then its -various definitions are in effect merged: the commands defined in the -minor mode keymaps come first, followed by those in the local map's -prefix definition, and then by those from the global map. - - In the following example, we make @kbd{C-p} a prefix key in the local -keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}. Then -the binding for @kbd{C-p C-f} is the function @code{find-file}, just -like @kbd{C-x C-f}. The key sequence @kbd{C-p 6} is not found in any -active keymap. - -@example -@group -(use-local-map (make-sparse-keymap)) - @result{} nil -@end group -@group -(local-set-key "\C-p" ctl-x-map) - @result{} nil -@end group -@group -(key-binding "\C-p\C-f") - @result{} find-file -@end group - -@group -(key-binding "\C-p6") - @result{} nil -@end group -@end example - -@defun define-prefix-command symbol &optional mapvar prompt -@cindex prefix command -@anchor{Definition of define-prefix-command} -This function prepares @var{symbol} for use as a prefix key's binding: -it creates a sparse keymap and stores it as @var{symbol}'s function -definition. Subsequently binding a key sequence to @var{symbol} will -make that key sequence into a prefix key. The return value is @code{symbol}. - -This function also sets @var{symbol} as a variable, with the keymap as -its value. But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar} -as a variable instead. - -If @var{prompt} is non-@code{nil}, that becomes the overall prompt -string for the keymap. The prompt string should be given for menu keymaps -(@pxref{Defining Menus}). -@end defun - -@node Active Keymaps -@section Active Keymaps -@cindex active keymap -@cindex global keymap -@cindex local keymap - - Emacs normally contains many keymaps; at any given time, just a few -of them are @dfn{active}, meaning that they participate in the -interpretation of user input. All the active keymaps are used -together to determine what command to execute when a key is entered. - - Normally the active keymaps are the @code{keymap} property keymap, -the keymaps of any enabled minor modes, the current buffer's local -keymap, and the global keymap, in that order. Emacs searches for each -input key sequence in all these keymaps. @xref{Searching Keymaps}, -for more details of this procedure. - - When the key sequence starts with a mouse event (optionally preceded -by a symbolic prefix), the active keymaps are determined based on the -position in that event. If the event happened on a string embedded -with a @code{display}, @code{before-string}, or @code{after-string} -property (@pxref{Special Properties}), the non-@code{nil} map -properties of the string override those of the buffer (if the -underlying buffer text contains map properties in its text properties -or overlays, they are ignored). - - The @dfn{global keymap} holds the bindings of keys that are defined -regardless of the current buffer, such as @kbd{C-f}. The variable -@code{global-map} holds this keymap, which is always active. - - Each buffer may have another keymap, its @dfn{local keymap}, which -may contain new or overriding definitions for keys. The current -buffer's local keymap is always active except when -@code{overriding-local-map} overrides it. The @code{local-map} text -or overlay property can specify an alternative local keymap for certain -parts of the buffer; see @ref{Special Properties}. - - Each minor mode can have a keymap; if it does, the keymap is active -when the minor mode is enabled. Modes for emulation can specify -additional active keymaps through the variable -@code{emulation-mode-map-alists}. - - The highest precedence normal keymap comes from the @code{keymap} -text or overlay property. If that is non-@code{nil}, it is the first -keymap to be processed, in normal circumstances. - - However, there are also special ways for programs to substitute -other keymaps for some of those. The variable -@code{overriding-local-map}, if non-@code{nil}, specifies a keymap -that replaces all the usual active keymaps except the global keymap. -Another way to do this is with @code{overriding-terminal-local-map}; -it operates on a per-terminal basis. These variables are documented -below. - -@cindex major mode keymap - Since every buffer that uses the same major mode normally uses the -same local keymap, you can think of the keymap as local to the mode. A -change to the local keymap of a buffer (using @code{local-set-key}, for -example) is seen also in the other buffers that share that keymap. - - The local keymaps that are used for Lisp mode and some other major -modes exist even if they have not yet been used. These local keymaps are -the values of variables such as @code{lisp-mode-map}. For most major -modes, which are less frequently used, the local keymap is constructed -only when the mode is used for the first time in a session. - - The minibuffer has local keymaps, too; they contain various completion -and exit commands. @xref{Intro to Minibuffers}. - - Emacs has other keymaps that are used in a different way---translating -events within @code{read-key-sequence}. @xref{Translation Keymaps}. - - @xref{Standard Keymaps}, for a list of some standard keymaps. - -@defun current-active-maps &optional olp position -This returns the list of active keymaps that would be used by the -command loop in the current circumstances to look up a key sequence. -Normally it ignores @code{overriding-local-map} and -@code{overriding-terminal-local-map}, but if @var{olp} is non-@code{nil} -then it pays attention to them. @var{position} can optionally be either -an event position as returned by @code{event-start} or a buffer -position, and may change the keymaps as described for -@code{key-binding}. -@end defun - -@defun key-binding key &optional accept-defaults no-remap position -This function returns the binding for @var{key} according to the -current active keymaps. The result is @code{nil} if @var{key} is -undefined in the keymaps. - -The argument @var{accept-defaults} controls checking for default -bindings, as in @code{lookup-key} (@pxref{Functions for Key Lookup}). - -When commands are remapped (@pxref{Remapping Commands}), -@code{key-binding} normally processes command remappings so as to -return the remapped command that will actually be executed. However, -if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores -remappings and returns the binding directly specified for @var{key}. - -If @var{key} starts with a mouse event (perhaps following a prefix -event), the maps to be consulted are determined based on the event's -position. Otherwise, they are determined based on the value of point. -However, you can override either of them by specifying @var{position}. -If @var{position} is non-@code{nil}, it should be either a buffer -position or an event position like the value of @code{event-start}. -Then the maps consulted are determined based on @var{position}. - -An error is signaled if @var{key} is not a string or a vector. - -@example -@group -(key-binding "\C-x\C-f") - @result{} find-file -@end group -@end example -@end defun - -@node Searching Keymaps -@section Searching the Active Keymaps -@cindex searching active keymaps for keys - - After translation of event subsequences (@pxref{Translation -Keymaps}) Emacs looks for them in the active keymaps. Here is a -pseudo-Lisp description of the order and conditions for searching -them: - -@lisp -(or (cond - (overriding-terminal-local-map - (@var{find-in} overriding-terminal-local-map)) - (overriding-local-map - (@var{find-in} overriding-local-map)) - ((or (@var{find-in} (get-char-property (point) 'keymap)) - (@var{find-in-any} emulation-mode-map-alists) - (@var{find-in-any} minor-mode-overriding-map-alist) - (@var{find-in-any} minor-mode-map-alist) - (if (get-text-property (point) 'local-map) - (@var{find-in} (get-char-property (point) 'local-map)) - (@var{find-in} (current-local-map)))))) - (@var{find-in} (current-global-map))) -@end lisp - -@noindent -@var{find-in} and @var{find-in-any} are pseudo functions that search -in one keymap and in an alist of keymaps, respectively. (Searching a -single keymap for a binding is called @dfn{key lookup}; see @ref{Key -Lookup}.) If the key sequence starts with a mouse event, or a -symbolic prefix event followed by a mouse event, that event's position -is used instead of point and the current buffer. Mouse events on an -embedded string use non-@code{nil} text properties from that string -instead of the buffer. - - When a match is found (@pxref{Key Lookup}), if the binding in the -keymap is a function, the search is over. However if the keymap entry -is a symbol with a value or a string, Emacs replaces the input key -sequences with the variable's value or the string, and restarts the -search of the active keymaps. - - The function finally found might also be remapped. @xref{Remapping -Commands}. - -@node Controlling Active Maps -@section Controlling the Active Keymaps - -@defvar global-map -This variable contains the default global keymap that maps Emacs -keyboard input to commands. The global keymap is normally this -keymap. The default global keymap is a full keymap that binds -@code{self-insert-command} to all of the printing characters. - -It is normal practice to change the bindings in the global keymap, but you -should not assign this variable any value other than the keymap it starts -out with. -@end defvar - -@defun current-global-map -This function returns the current global keymap. This is the same as -the value of @code{global-map} unless you change one or the other. -The return value is a reference, not a copy; if you use -@code{define-key} or other functions on it you will alter global -bindings. - -@example -@group -(current-global-map) -@result{} (keymap [set-mark-command beginning-of-line @dots{} - delete-backward-char]) -@end group -@end example -@end defun - -@defun current-local-map -This function returns the current buffer's local keymap, or @code{nil} -if it has none. In the following example, the keymap for the -@file{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap -in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse -keymap. - -@example -@group -(current-local-map) -@result{} (keymap - (10 . eval-print-last-sexp) - (9 . lisp-indent-line) - (127 . backward-delete-char-untabify) -@end group -@group - (27 keymap - (24 . eval-defun) - (17 . indent-sexp))) -@end group -@end example -@end defun - -@code{current-local-map} returns a reference to the local keymap, not -a copy of it; if you use @code{define-key} or other functions on it -you will alter local bindings. - -@defun current-minor-mode-maps -This function returns a list of the keymaps of currently enabled minor modes. -@end defun - -@defun use-global-map keymap -This function makes @var{keymap} the new current global keymap. It -returns @code{nil}. - -It is very unusual to change the global keymap. -@end defun - -@defun use-local-map keymap -This function makes @var{keymap} the new local keymap of the current -buffer. If @var{keymap} is @code{nil}, then the buffer has no local -keymap. @code{use-local-map} returns @code{nil}. Most major mode -commands use this function. -@end defun - -@c Emacs 19 feature -@defvar minor-mode-map-alist -@anchor{Definition of minor-mode-map-alist} -This variable is an alist describing keymaps that may or may not be -active according to the values of certain variables. Its elements look -like this: - -@example -(@var{variable} . @var{keymap}) -@end example - -The keymap @var{keymap} is active whenever @var{variable} has a -non-@code{nil} value. Typically @var{variable} is the variable that -enables or disables a minor mode. @xref{Keymaps and Minor Modes}. - -Note that elements of @code{minor-mode-map-alist} do not have the same -structure as elements of @code{minor-mode-alist}. The map must be the -@sc{cdr} of the element; a list with the map as the second element will -not do. The @sc{cdr} can be either a keymap (a list) or a symbol whose -function definition is a keymap. - -When more than one minor mode keymap is active, the earlier one in -@code{minor-mode-map-alist} takes priority. But you should design -minor modes so that they don't interfere with each other. If you do -this properly, the order will not matter. - -See @ref{Keymaps and Minor Modes}, for more information about minor -modes. See also @code{minor-mode-key-binding} (@pxref{Functions for Key -Lookup}). -@end defvar - -@defvar minor-mode-overriding-map-alist -This variable allows major modes to override the key bindings for -particular minor modes. The elements of this alist look like the -elements of @code{minor-mode-map-alist}: @code{(@var{variable} -. @var{keymap})}. - -If a variable appears as an element of -@code{minor-mode-overriding-map-alist}, the map specified by that -element totally replaces any map specified for the same variable in -@code{minor-mode-map-alist}. - -@code{minor-mode-overriding-map-alist} is automatically buffer-local in -all buffers. -@end defvar - -@defvar overriding-local-map -If non-@code{nil}, this variable holds a keymap to use instead of the -buffer's local keymap, any text property or overlay keymaps, and any -minor mode keymaps. This keymap, if specified, overrides all other -maps that would have been active, except for the current global map. -@end defvar - -@defvar overriding-terminal-local-map -If non-@code{nil}, this variable holds a keymap to use instead of -@code{overriding-local-map}, the buffer's local keymap, text property -or overlay keymaps, and all the minor mode keymaps. - -This variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Terminals}. It is used to implement -incremental search mode. -@end defvar - -@defvar overriding-local-map-menu-flag -If this variable is non-@code{nil}, the value of -@code{overriding-local-map} or @code{overriding-terminal-local-map} can -affect the display of the menu bar. The default value is @code{nil}, so -those map variables have no effect on the menu bar. - -Note that these two map variables do affect the execution of key -sequences entered using the menu bar, even if they do not affect the -menu bar display. So if a menu bar key sequence comes in, you should -clear the variables before looking up and executing that key sequence. -Modes that use the variables would typically do this anyway; normally -they respond to events that they do not handle by ``unreading'' them and -exiting. -@end defvar - -@defvar special-event-map -This variable holds a keymap for special events. If an event type has a -binding in this keymap, then it is special, and the binding for the -event is run directly by @code{read-event}. @xref{Special Events}. -@end defvar - -@defvar emulation-mode-map-alists -This variable holds a list of keymap alists to use for emulations -modes. It is intended for modes or packages using multiple minor-mode -keymaps. Each element is a keymap alist which has the same format and -meaning as @code{minor-mode-map-alist}, or a symbol with a variable -binding which is such an alist. The ``active'' keymaps in each alist -are used before @code{minor-mode-map-alist} and -@code{minor-mode-overriding-map-alist}. -@end defvar - -@node Key Lookup -@section Key Lookup -@cindex key lookup -@cindex keymap entry - - @dfn{Key lookup} is the process of finding the binding of a key -sequence from a given keymap. The execution or use of the binding is -not part of key lookup. - - Key lookup uses just the event type of each event in the key sequence; -the rest of the event is ignored. In fact, a key sequence used for key -lookup may designate a mouse event with just its types (a symbol) -instead of the entire event (a list). @xref{Input Events}. Such -a ``key sequence'' is insufficient for @code{command-execute} to run, -but it is sufficient for looking up or rebinding a key. - - When the key sequence consists of multiple events, key lookup -processes the events sequentially: the binding of the first event is -found, and must be a keymap; then the second event's binding is found in -that keymap, and so on until all the events in the key sequence are used -up. (The binding thus found for the last event may or may not be a -keymap.) Thus, the process of key lookup is defined in terms of a -simpler process for looking up a single event in a keymap. How that is -done depends on the type of object associated with the event in that -keymap. - - Let's use the term @dfn{keymap entry} to describe the value found by -looking up an event type in a keymap. (This doesn't include the item -string and other extra elements in a keymap element for a menu item, because -@code{lookup-key} and other key lookup functions don't include them in -the returned value.) While any Lisp object may be stored in a keymap -as a keymap entry, not all make sense for key lookup. Here is a table -of the meaningful types of keymap entries: - -@table @asis -@item @code{nil} -@cindex @code{nil} in keymap -@code{nil} means that the events used so far in the lookup form an -undefined key. When a keymap fails to mention an event type at all, and -has no default binding, that is equivalent to a binding of @code{nil} -for that event type. - -@item @var{command} -@cindex command in keymap -The events used so far in the lookup form a complete key, -and @var{command} is its binding. @xref{What Is a Function}. - -@item @var{array} -@cindex string in keymap -The array (either a string or a vector) is a keyboard macro. The events -used so far in the lookup form a complete key, and the array is its -binding. See @ref{Keyboard Macros}, for more information. - -@item @var{keymap} -@cindex keymap in keymap -The events used so far in the lookup form a prefix key. The next -event of the key sequence is looked up in @var{keymap}. - -@item @var{list} -@cindex list in keymap -The meaning of a list depends on what it contains: - -@itemize @bullet -@item -If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list -is a keymap, and is treated as a keymap (see above). - -@item -@cindex @code{lambda} in keymap -If the @sc{car} of @var{list} is @code{lambda}, then the list is a -lambda expression. This is presumed to be a function, and is treated -as such (see above). In order to execute properly as a key binding, -this function must be a command---it must have an @code{interactive} -specification. @xref{Defining Commands}. - -@item -If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event -type, then this is an @dfn{indirect entry}: - -@example -(@var{othermap} . @var{othertype}) -@end example - -When key lookup encounters an indirect entry, it looks up instead the -binding of @var{othertype} in @var{othermap} and uses that. - -This feature permits you to define one key as an alias for another key. -For example, an entry whose @sc{car} is the keymap called @code{esc-map} -and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global -binding of @kbd{Meta-@key{SPC}}, whatever that may be''. -@end itemize - -@item @var{symbol} -@cindex symbol in keymap -The function definition of @var{symbol} is used in place of -@var{symbol}. If that too is a symbol, then this process is repeated, -any number of times. Ultimately this should lead to an object that is -a keymap, a command, or a keyboard macro. A list is allowed if it is a -keymap or a command, but indirect entries are not understood when found -via symbols. - -Note that keymaps and keyboard macros (strings and vectors) are not -valid functions, so a symbol with a keymap, string, or vector as its -function definition is invalid as a function. It is, however, valid as -a key binding. If the definition is a keyboard macro, then the symbol -is also valid as an argument to @code{command-execute} -(@pxref{Interactive Call}). - -@cindex @code{undefined} in keymap -The symbol @code{undefined} is worth special mention: it means to treat -the key as undefined. Strictly speaking, the key is defined, and its -binding is the command @code{undefined}; but that command does the same -thing that is done automatically for an undefined key: it rings the bell -(by calling @code{ding}) but does not signal an error. - -@cindex preventing prefix key -@code{undefined} is used in local keymaps to override a global key -binding and make the key ``undefined'' locally. A local binding of -@code{nil} would fail to do this because it would not override the -global binding. - -@item @var{anything else} -If any other type of object is found, the events used so far in the -lookup form a complete key, and the object is its binding, but the -binding is not executable as a command. -@end table - - In short, a keymap entry may be a keymap, a command, a keyboard -macro, a symbol that leads to one of them, or an indirection or -@code{nil}. - -@node Functions for Key Lookup -@section Functions for Key Lookup - - Here are the functions and variables pertaining to key lookup. - -@defun lookup-key keymap key &optional accept-defaults -This function returns the definition of @var{key} in @var{keymap}. All -the other functions described in this chapter that look up keys use -@code{lookup-key}. Here are examples: - -@example -@group -(lookup-key (current-global-map) "\C-x\C-f") - @result{} find-file -@end group -@group -(lookup-key (current-global-map) (kbd "C-x C-f")) - @result{} find-file -@end group -@group -(lookup-key (current-global-map) "\C-x\C-f12345") - @result{} 2 -@end group -@end example - -If the string or vector @var{key} is not a valid key sequence according -to the prefix keys specified in @var{keymap}, it must be ``too long'' -and have extra events at the end that do not fit into a single key -sequence. Then the value is a number, the number of events at the front -of @var{key} that compose a complete key. - -@c Emacs 19 feature -If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key} -considers default bindings as well as bindings for the specific events -in @var{key}. Otherwise, @code{lookup-key} reports only bindings for -the specific sequence @var{key}, ignoring default bindings except when -you explicitly ask about them. (To do this, supply @code{t} as an -element of @var{key}; see @ref{Format of Keymaps}.) - -If @var{key} contains a meta character (not a function key), that -character is implicitly replaced by a two-character sequence: the value -of @code{meta-prefix-char}, followed by the corresponding non-meta -character. Thus, the first example below is handled by conversion into -the second example. - -@example -@group -(lookup-key (current-global-map) "\M-f") - @result{} forward-word -@end group -@group -(lookup-key (current-global-map) "\ef") - @result{} forward-word -@end group -@end example - -Unlike @code{read-key-sequence}, this function does not modify the -specified events in ways that discard information (@pxref{Key Sequence -Input}). In particular, it does not convert letters to lower case and -it does not change drag events to clicks. -@end defun - -@deffn Command undefined -Used in keymaps to undefine keys. It calls @code{ding}, but does -not cause an error. -@end deffn - -@defun local-key-binding key &optional accept-defaults -This function returns the binding for @var{key} in the current -local keymap, or @code{nil} if it is undefined there. - -@c Emacs 19 feature -The argument @var{accept-defaults} controls checking for default bindings, -as in @code{lookup-key} (above). -@end defun - -@defun global-key-binding key &optional accept-defaults -This function returns the binding for command @var{key} in the -current global keymap, or @code{nil} if it is undefined there. - -@c Emacs 19 feature -The argument @var{accept-defaults} controls checking for default bindings, -as in @code{lookup-key} (above). -@end defun - -@c Emacs 19 feature -@defun minor-mode-key-binding key &optional accept-defaults -This function returns a list of all the active minor mode bindings of -@var{key}. More precisely, it returns an alist of pairs -@code{(@var{modename} . @var{binding})}, where @var{modename} is the -variable that enables the minor mode, and @var{binding} is @var{key}'s -binding in that mode. If @var{key} has no minor-mode bindings, the -value is @code{nil}. - -If the first binding found is not a prefix definition (a keymap or a -symbol defined as a keymap), all subsequent bindings from other minor -modes are omitted, since they would be completely shadowed. Similarly, -the list omits non-prefix bindings that follow prefix bindings. - -The argument @var{accept-defaults} controls checking for default -bindings, as in @code{lookup-key} (above). -@end defun - -@defopt meta-prefix-char -@cindex @key{ESC} -This variable is the meta-prefix character code. It is used for -translating a meta character to a two-character sequence so it can be -looked up in a keymap. For useful results, the value should be a -prefix event (@pxref{Prefix Keys}). The default value is 27, which is -the @acronym{ASCII} code for @key{ESC}. - -As long as the value of @code{meta-prefix-char} remains 27, key lookup -translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined -as the @code{backward-word} command. However, if you were to set -@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will -translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the -@code{switch-to-buffer} command. (Don't actually do this!) Here is an -illustration of what would happen: - -@smallexample -@group -meta-prefix-char ; @r{The default value.} - @result{} 27 -@end group -@group -(key-binding "\M-b") - @result{} backward-word -@end group -@group -?\C-x ; @r{The print representation} - @result{} 24 ; @r{of a character.} -@end group -@group -(setq meta-prefix-char 24) - @result{} 24 -@end group -@group -(key-binding "\M-b") - @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is} - ; @r{like typing @kbd{C-x b}.} - -(setq meta-prefix-char 27) ; @r{Avoid confusion!} - @result{} 27 ; @r{Restore the default value!} -@end group -@end smallexample - -This translation of one event into two happens only for characters, not -for other kinds of input events. Thus, @kbd{M-@key{F1}}, a function -key, is not converted into @kbd{@key{ESC} @key{F1}}. -@end defopt - -@node Changing Key Bindings -@section Changing Key Bindings -@cindex changing key bindings -@cindex rebinding - - The way to rebind a key is to change its entry in a keymap. If you -change a binding in the global keymap, the change is effective in all -buffers (though it has no direct effect in buffers that shadow the -global binding with a local one). If you change the current buffer's -local map, that usually affects all buffers using the same major mode. -The @code{global-set-key} and @code{local-set-key} functions are -convenient interfaces for these operations (@pxref{Key Binding -Commands}). You can also use @code{define-key}, a more general -function; then you must explicitly specify the map to change. - - When choosing the key sequences for Lisp programs to rebind, please -follow the Emacs conventions for use of various keys (@pxref{Key -Binding Conventions}). - -@cindex meta character key constants -@cindex control character key constants - In writing the key sequence to rebind, it is good to use the special -escape sequences for control and meta characters (@pxref{String Type}). -The syntax @samp{\C-} means that the following character is a control -character and @samp{\M-} means that the following character is a meta -character. Thus, the string @code{"\M-x"} is read as containing a -single @kbd{M-x}, @code{"\C-f"} is read as containing a single -@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as -containing a single @kbd{C-M-x}. You can also use this escape syntax in -vectors, as well as others that aren't allowed in strings; one example -is @samp{[?\C-\H-x home]}. @xref{Character Type}. - - The key definition and lookup functions accept an alternate syntax for -event types in a key sequence that is a vector: you can use a list -containing modifier names plus one base event (a character or function -key name). For example, @code{(control ?a)} is equivalent to -@code{?\C-a} and @code{(hyper control left)} is equivalent to -@code{C-H-left}. One advantage of such lists is that the precise -numeric codes for the modifier bits don't appear in compiled files. - - The functions below signal an error if @var{keymap} is not a keymap, -or if @var{key} is not a string or vector representing a key sequence. -You can use event types (symbols) as shorthand for events that are -lists. The @code{kbd} macro (@pxref{Key Sequences}) is a convenient -way to specify the key sequence. - -@defun define-key keymap key binding -This function sets the binding for @var{key} in @var{keymap}. (If -@var{key} is more than one event long, the change is actually made -in another keymap reached from @var{keymap}.) The argument -@var{binding} can be any Lisp object, but only certain types are -meaningful. (For a list of meaningful types, see @ref{Key Lookup}.) -The value returned by @code{define-key} is @var{binding}. - -If @var{key} is @code{[t]}, this sets the default binding in -@var{keymap}. When an event has no binding of its own, the Emacs -command loop uses the keymap's default binding, if there is one. - -@cindex invalid prefix key error -@cindex key sequence error -Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap) -or undefined; otherwise an error is signaled. If some prefix of -@var{key} is undefined, then @code{define-key} defines it as a prefix -key so that the rest of @var{key} can be defined as specified. - -If there was previously no binding for @var{key} in @var{keymap}, the -new binding is added at the beginning of @var{keymap}. The order of -bindings in a keymap makes no difference for keyboard input, but it -does matter for menu keymaps (@pxref{Menu Keymaps}). -@end defun - - This example creates a sparse keymap and makes a number of -bindings in it: - -@smallexample -@group -(setq map (make-sparse-keymap)) - @result{} (keymap) -@end group -@group -(define-key map "\C-f" 'forward-char) - @result{} forward-char -@end group -@group -map - @result{} (keymap (6 . forward-char)) -@end group - -@group -;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.} -(define-key map (kbd "C-x f") 'forward-word) - @result{} forward-word -@end group -@group -map -@result{} (keymap - (24 keymap ; @kbd{C-x} - (102 . forward-word)) ; @kbd{f} - (6 . forward-char)) ; @kbd{C-f} -@end group - -@group -;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.} -(define-key map (kbd "C-p") ctl-x-map) -;; @code{ctl-x-map} -@result{} [nil @dots{} find-file @dots{} backward-kill-sentence] -@end group - -@group -;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.} -(define-key map (kbd "C-p C-f") 'foo) -@result{} 'foo -@end group -@group -map -@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.} - (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence]) - (24 keymap - (102 . forward-word)) - (6 . forward-char)) -@end group -@end smallexample - -@noindent -Note that storing a new binding for @kbd{C-p C-f} actually works by -changing an entry in @code{ctl-x-map}, and this has the effect of -changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the -default global map. - - The function @code{substitute-key-definition} scans a keymap for -keys that have a certain binding and rebinds them with a different -binding. Another feature which is cleaner and can often produce the -same results to remap one command into another (@pxref{Remapping -Commands}). - -@defun substitute-key-definition olddef newdef keymap &optional oldmap -@cindex replace bindings -This function replaces @var{olddef} with @var{newdef} for any keys in -@var{keymap} that were bound to @var{olddef}. In other words, -@var{olddef} is replaced with @var{newdef} wherever it appears. The -function returns @code{nil}. - -For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with -standard bindings: - -@smallexample -@group -(substitute-key-definition - 'find-file 'find-file-read-only (current-global-map)) -@end group -@end smallexample - -@c Emacs 19 feature -If @var{oldmap} is non-@code{nil}, that changes the behavior of -@code{substitute-key-definition}: the bindings in @var{oldmap} determine -which keys to rebind. The rebindings still happen in @var{keymap}, not -in @var{oldmap}. Thus, you can change one map under the control of the -bindings in another. For example, - -@smallexample -(substitute-key-definition - 'delete-backward-char 'my-funny-delete - my-map global-map) -@end smallexample - -@noindent -puts the special deletion command in @code{my-map} for whichever keys -are globally bound to the standard deletion command. - -Here is an example showing a keymap before and after substitution: - -@smallexample -@group -(setq map '(keymap - (?1 . olddef-1) - (?2 . olddef-2) - (?3 . olddef-1))) -@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1)) -@end group - -@group -(substitute-key-definition 'olddef-1 'newdef map) -@result{} nil -@end group -@group -map -@result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef)) -@end group -@end smallexample -@end defun - -@defun suppress-keymap keymap &optional nodigits -@cindex @code{self-insert-command} override -This function changes the contents of the full keymap @var{keymap} by -remapping @code{self-insert-command} to the command @code{undefined} -(@pxref{Remapping Commands}). This has the effect of undefining all -printing characters, thus making ordinary insertion of text impossible. -@code{suppress-keymap} returns @code{nil}. - -If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines -digits to run @code{digit-argument}, and @kbd{-} to run -@code{negative-argument}. Otherwise it makes them undefined like the -rest of the printing characters. - -@cindex yank suppression -@cindex @code{quoted-insert} suppression -The @code{suppress-keymap} function does not make it impossible to -modify a buffer, as it does not suppress commands such as @code{yank} -and @code{quoted-insert}. To prevent any modification of a buffer, make -it read-only (@pxref{Read Only Buffers}). - -Since this function modifies @var{keymap}, you would normally use it -on a newly created keymap. Operating on an existing keymap -that is used for some other purpose is likely to cause trouble; for -example, suppressing @code{global-map} would make it impossible to use -most of Emacs. - -This function can be used to initialize the local keymap of a major -mode for which insertion of text is not desirable. But usually such a -mode should be derived from @code{special-mode} (@pxref{Basic Major -Modes}); then its keymap will automatically inherit from -@code{special-mode-map}, which is already suppressed. Here is how -@code{special-mode-map} is defined: - -@smallexample -@group -(defvar special-mode-map - (let ((map (make-sparse-keymap))) - (suppress-keymap map) - (define-key map "q" 'quit-window) - @dots{} - map)) -@end group -@end smallexample -@end defun - -@node Remapping Commands -@section Remapping Commands -@cindex remapping commands - - A special kind of key binding can be used to @dfn{remap} one command -to another, without having to refer to the key sequence(s) bound to -the original command. To use this feature, make a key binding for a -key sequence that starts with the dummy event @code{remap}, followed -by the command name you want to remap; for the binding, specify the -new definition (usually a command name, but possibly any other valid -definition for a key binding). - - For example, suppose My mode provides a special command -@code{my-kill-line}, which should be invoked instead of -@code{kill-line}. To establish this, its mode keymap should contain -the following remapping: - -@smallexample -(define-key my-mode-map [remap kill-line] 'my-kill-line) -@end smallexample - -@noindent -Then, whenever @code{my-mode-map} is active, if the user types -@kbd{C-k} (the default global key sequence for @code{kill-line}) Emacs -will instead run @code{my-kill-line}. - - Note that remapping only takes place through active keymaps; for -example, putting a remapping in a prefix keymap like @code{ctl-x-map} -typically has no effect, as such keymaps are not themselves active. -In addition, remapping only works through a single level; in the -following example, - -@smallexample -(define-key my-mode-map [remap kill-line] 'my-kill-line) -(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line) -@end smallexample - -@noindent -@code{kill-line} is @emph{not} remapped to @code{my-other-kill-line}. -Instead, if an ordinary key binding specifies @code{kill-line}, it is -remapped to @code{my-kill-line}; if an ordinary binding specifies -@code{my-kill-line}, it is remapped to @code{my-other-kill-line}. - -To undo the remapping of a command, remap it to @code{nil}; e.g. - -@smallexample -(define-key my-mode-map [remap kill-line] nil) -@end smallexample - -@defun command-remapping command &optional position keymaps -This function returns the remapping for @var{command} (a symbol), -given the current active keymaps. If @var{command} is not remapped -(which is the usual situation), or not a symbol, the function returns -@code{nil}. @code{position} can optionally specify a buffer position -or an event position to determine the keymaps to use, as in -@code{key-binding}. - -If the optional argument @code{keymaps} is non-@code{nil}, it -specifies a list of keymaps to search in. This argument is ignored if -@code{position} is non-@code{nil}. -@end defun - -@node Translation Keymaps -@section Keymaps for Translating Sequences of Events -@cindex keymaps for translating events - - This section describes keymaps that are used during reading a key -sequence, to translate certain event sequences into others. -@code{read-key-sequence} checks every subsequence of the key sequence -being read, as it is read, against @code{input-decode-map}, then -@code{local-function-key-map}, and then against @code{key-translation-map}. - -@defvar input-decode-map -This variable holds a keymap that describes the character sequences sent -by function keys on an ordinary character terminal. This keymap has the -same structure as other keymaps, but is used differently: it specifies -translations to make while reading key sequences, rather than bindings -for key sequences. - -If @code{input-decode-map} ``binds'' a key sequence @var{k} to a vector -@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a -key sequence, it is replaced with the events in @var{v}. - -For example, VT100 terminals send @kbd{@key{ESC} O P} when the -keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate -that sequence of events into the single event @code{pf1}. We accomplish -this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in -@code{input-decode-map}, when using a VT100. - -Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c -@key{ESC} O P}; later the function @code{read-key-sequence} translates -this back into @kbd{C-c @key{PF1}}, which it returns as the vector -@code{[?\C-c pf1]}. - -The value of @code{input-decode-map} is usually set up automatically -according to the terminal's Terminfo or Termcap entry, but sometimes -those need help from terminal-specific Lisp files. Emacs comes with -terminal-specific files for many common terminals; their main purpose is -to make entries in @code{input-decode-map} beyond those that can be -deduced from Termcap and Terminfo. @xref{Terminal-Specific}. -@end defvar - -@defvar local-function-key-map -This variable holds a keymap similar to @code{input-decode-map} except -that it describes key sequences which should be translated to -alternative interpretations that are usually preferred. It applies -after @code{input-decode-map} and before @code{key-translation-map}. - -Entries in @code{local-function-key-map} are ignored if they conflict -with bindings made in the minor mode, local, or global keymaps. I.e. -the remapping only applies if the original key sequence would -otherwise not have any binding. - -@code{local-function-key-map} inherits from @code{function-key-map}, -but the latter should not be used directly. -@end defvar - -@defvar key-translation-map -This variable is another keymap used just like @code{input-decode-map} -to translate input events into other events. It differs from -@code{input-decode-map} in that it goes to work after -@code{local-function-key-map} is finished rather than before; it -receives the results of translation by @code{local-function-key-map}. - -Just like @code{input-decode-map}, but unlike -@code{local-function-key-map}, this keymap is applied regardless of -whether the input key-sequence has a normal binding. Note however -that actual key bindings can have an effect on -@code{key-translation-map}, even though they are overridden by it. -Indeed, actual key bindings override @code{local-function-key-map} and -thus may alter the key sequence that @code{key-translation-map} -receives. Clearly, it is better to avoid this type of situation. - -The intent of @code{key-translation-map} is for users to map one -character set to another, including ordinary characters normally bound -to @code{self-insert-command}. -@end defvar - -@cindex key translation function -You can use @code{input-decode-map}, @code{local-function-key-map}, or -@code{key-translation-map} for more than simple aliases, by using a -function, instead of a key sequence, as the ``translation'' of a key. -Then this function is called to compute the translation of that key. - -The key translation function receives one argument, which is the prompt -that was specified in @code{read-key-sequence}---or @code{nil} if the -key sequence is being read by the editor command loop. In most cases -you can ignore the prompt value. - -If the function reads input itself, it can have the effect of altering -the event that follows. For example, here's how to define @kbd{C-c h} -to turn the character that follows into a Hyper character: - -@example -@group -(defun hyperify (prompt) - (let ((e (read-event))) - (vector (if (numberp e) - (logior (lsh 1 24) e) - (if (memq 'hyper (event-modifiers e)) - e - (add-event-modifier "H-" e)))))) - -(defun add-event-modifier (string e) - (let ((symbol (if (symbolp e) e (car e)))) - (setq symbol (intern (concat string - (symbol-name symbol)))) -@end group -@group - (if (symbolp e) - symbol - (cons symbol (cdr e))))) - -(define-key local-function-key-map "\C-ch" 'hyperify) -@end group -@end example - - If you have enabled keyboard character set decoding using -@code{set-keyboard-coding-system}, decoding is done after the -translations listed above. @xref{Terminal I/O Encoding}. However, in -future Emacs versions, character set decoding may be done at an -earlier stage. - -@node Key Binding Commands -@section Commands for Binding Keys - - This section describes some convenient interactive interfaces for -changing key bindings. They work by calling @code{define-key}. - - People often use @code{global-set-key} in their init files -(@pxref{Init File}) for simple customization. For example, - -@smallexample -(global-set-key (kbd "C-x C-\\") 'next-line) -@end smallexample - -@noindent -or - -@smallexample -(global-set-key [?\C-x ?\C-\\] 'next-line) -@end smallexample - -@noindent -or - -@smallexample -(global-set-key [(control ?x) (control ?\\)] 'next-line) -@end smallexample - -@noindent -redefines @kbd{C-x C-\} to move down a line. - -@smallexample -(global-set-key [M-mouse-1] 'mouse-set-point) -@end smallexample - -@noindent -redefines the first (leftmost) mouse button, entered with the Meta key, to -set point where you click. - -@cindex non-@acronym{ASCII} text in keybindings - Be careful when using non-@acronym{ASCII} text characters in Lisp -specifications of keys to bind. If these are read as multibyte text, as -they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you -must type the keys as multibyte too. For instance, if you use this: - -@smallexample -(global-set-key "@"o" 'my-function) ; bind o-umlaut -@end smallexample - -@noindent -or - -@smallexample -(global-set-key ?@"o 'my-function) ; bind o-umlaut -@end smallexample - -@noindent -and your language environment is multibyte Latin-1, these commands -actually bind the multibyte character with code 246, not the byte -code 246 (@kbd{M-v}) sent by a Latin-1 terminal. In order to use this -binding, you need to teach Emacs how to decode the keyboard by using an -appropriate input method (@pxref{Input Methods, , Input Methods, emacs, The GNU -Emacs Manual}). - -@deffn Command global-set-key key binding -This function sets the binding of @var{key} in the current global map -to @var{binding}. - -@smallexample -@group -(global-set-key @var{key} @var{binding}) -@equiv{} -(define-key (current-global-map) @var{key} @var{binding}) -@end group -@end smallexample -@end deffn - -@deffn Command global-unset-key key -@cindex unbinding keys -This function removes the binding of @var{key} from the current -global map. - -One use of this function is in preparation for defining a longer key -that uses @var{key} as a prefix---which would not be allowed if -@var{key} has a non-prefix binding. For example: - -@smallexample -@group -(global-unset-key "\C-l") - @result{} nil -@end group -@group -(global-set-key "\C-l\C-l" 'redraw-display) - @result{} nil -@end group -@end smallexample - -This function is implemented simply using @code{define-key}: - -@smallexample -@group -(global-unset-key @var{key}) -@equiv{} -(define-key (current-global-map) @var{key} nil) -@end group -@end smallexample -@end deffn - -@deffn Command local-set-key key binding -This function sets the binding of @var{key} in the current local -keymap to @var{binding}. - -@smallexample -@group -(local-set-key @var{key} @var{binding}) -@equiv{} -(define-key (current-local-map) @var{key} @var{binding}) -@end group -@end smallexample -@end deffn - -@deffn Command local-unset-key key -This function removes the binding of @var{key} from the current -local map. - -@smallexample -@group -(local-unset-key @var{key}) -@equiv{} -(define-key (current-local-map) @var{key} nil) -@end group -@end smallexample -@end deffn - -@node Scanning Keymaps -@section Scanning Keymaps - - This section describes functions used to scan all the current keymaps -for the sake of printing help information. - -@defun accessible-keymaps keymap &optional prefix -This function returns a list of all the keymaps that can be reached (via -zero or more prefix keys) from @var{keymap}. The value is an -association list with elements of the form @code{(@var{key} .@: -@var{map})}, where @var{key} is a prefix key whose definition in -@var{keymap} is @var{map}. - -The elements of the alist are ordered so that the @var{key} increases -in length. The first element is always @code{([] .@: @var{keymap})}, -because the specified keymap is accessible from itself with a prefix of -no events. - -If @var{prefix} is given, it should be a prefix key sequence; then -@code{accessible-keymaps} includes only the submaps whose prefixes start -with @var{prefix}. These elements look just as they do in the value of -@code{(accessible-keymaps)}; the only difference is that some elements -are omitted. - -In the example below, the returned alist indicates that the key -@key{ESC}, which is displayed as @samp{^[}, is a prefix key whose -definition is the sparse keymap @code{(keymap (83 .@: center-paragraph) -(115 .@: foo))}. - -@smallexample -@group -(accessible-keymaps (current-local-map)) -@result{}(([] keymap - (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.} - (83 . center-paragraph) - (115 . center-line)) - (9 . tab-to-tab-stop)) -@end group - -@group - ("^[" keymap - (83 . center-paragraph) - (115 . foo))) -@end group -@end smallexample - -In the following example, @kbd{C-h} is a prefix key that uses a sparse -keymap starting with @code{(keymap (118 . describe-variable)@dots{})}. -Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of -the variable @code{ctl-x-4-map}. The event @code{mode-line} is one of -several dummy events used as prefixes for mouse actions in special parts -of a window. - -@smallexample -@group -(accessible-keymaps (current-global-map)) -@result{} (([] keymap [set-mark-command beginning-of-line @dots{} - delete-backward-char]) -@end group -@group - ("^H" keymap (118 . describe-variable) @dots{} - (8 . help-for-help)) -@end group -@group - ("^X" keymap [x-flush-mouse-queue @dots{} - backward-kill-sentence]) -@end group -@group - ("^[" keymap [mark-sexp backward-sexp @dots{} - backward-kill-word]) -@end group - ("^X4" keymap (15 . display-buffer) @dots{}) -@group - ([mode-line] keymap - (S-mouse-2 . mouse-split-window-horizontally) @dots{})) -@end group -@end smallexample - -@noindent -These are not all the keymaps you would see in actuality. -@end defun - -@defun map-keymap function keymap -The function @code{map-keymap} calls @var{function} once -for each binding in @var{keymap}. It passes two arguments, -the event type and the value of the binding. If @var{keymap} -has a parent, the parent's bindings are included as well. -This works recursively: if the parent has itself a parent, then the -grandparent's bindings are also included and so on. - -This function is the cleanest way to examine all the bindings -in a keymap. -@end defun - -@defun where-is-internal command &optional keymap firstonly noindirect no-remap -This function is a subroutine used by the @code{where-is} command -(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list -of all key sequences (of any length) that are bound to @var{command} in a -set of keymaps. - -The argument @var{command} can be any object; it is compared with all -keymap entries using @code{eq}. - -If @var{keymap} is @code{nil}, then the maps used are the current active -keymaps, disregarding @code{overriding-local-map} (that is, pretending -its value is @code{nil}). If @var{keymap} is a keymap, then the -maps searched are @var{keymap} and the global keymap. If @var{keymap} -is a list of keymaps, only those keymaps are searched. - -Usually it's best to use @code{overriding-local-map} as the expression -for @var{keymap}. Then @code{where-is-internal} searches precisely -the keymaps that are active. To search only the global map, pass the -value @code{(keymap)} (an empty keymap) as @var{keymap}. - -If @var{firstonly} is @code{non-ascii}, then the value is a single -vector representing the first key sequence found, rather than a list of -all possible key sequences. If @var{firstonly} is @code{t}, then the -value is the first key sequence, except that key sequences consisting -entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII} -characters) are preferred to all other key sequences and that the -return value can never be a menu binding. - -If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't -follow indirect keymap bindings. This makes it possible to search for -an indirect definition itself. - -The fifth argument, @var{no-remap}, determines how this function -treats command remappings (@pxref{Remapping Commands}). There are two -cases of interest: - -@table @asis -@item If a command @var{other-command} is remapped to @var{command}: -If @var{no-remap} is @code{nil}, find the bindings for -@var{other-command} and treat them as though they are also bindings -for @var{command}. If @var{no-remap} is non-@code{nil}, include the -vector @code{[remap @var{other-command}]} in the list of possible key -sequences, instead of finding those bindings. - -@item If @var{command} is remapped to @var{other-command}: -If @var{no-remap} is @code{nil}, return the bindings for -@var{other-command} rather than @var{command}. If @var{no-remap} is -non-@code{nil}, return the bindings for @var{command}, ignoring the -fact that it is remapped. -@end table -@end defun - -@deffn Command describe-bindings &optional prefix buffer-or-name -This function creates a listing of all current key bindings, and -displays it in a buffer named @file{*Help*}. The text is grouped by -modes---minor modes first, then the major mode, then global bindings. - -If @var{prefix} is non-@code{nil}, it should be a prefix key; then the -listing includes only keys that start with @var{prefix}. - -The listing describes meta characters as @key{ESC} followed by the -corresponding non-meta character. - -When several characters with consecutive @acronym{ASCII} codes have the -same definition, they are shown together, as -@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to -know the @acronym{ASCII} codes to understand which characters this means. -For example, in the default global map, the characters @samp{@key{SPC} -..@: ~} are described by a single line. @key{SPC} is @acronym{ASCII} 32, -@kbd{~} is @acronym{ASCII} 126, and the characters between them include all -the normal printing characters, (e.g., letters, digits, punctuation, -etc.@:); all these characters are bound to @code{self-insert-command}. - -If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a -buffer name. Then @code{describe-bindings} lists that buffer's bindings, -instead of the current buffer's. -@end deffn - -@node Menu Keymaps -@section Menu Keymaps -@cindex menu keymaps - -A keymap can operate as a menu as well as defining bindings for -keyboard keys and mouse buttons. Menus are usually actuated with the -mouse, but they can function with the keyboard also. If a menu keymap -is active for the next input event, that activates the keyboard menu -feature. - -@menu -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. -@end menu - -@node Defining Menus -@subsection Defining Menus -@cindex defining menus -@cindex menu prompt string -@cindex prompt string (of menu) -@cindex menu item - -A keymap acts as a menu if it has an @dfn{overall prompt string}, -which is a string that appears as an element of the keymap. -(@xref{Format of Keymaps}.) The string should describe the purpose of -the menu's commands. Emacs displays the overall prompt string as the -menu title in some cases, depending on the toolkit (if any) used for -displaying menus.@footnote{It is required for menus which do not use a -toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the -overall prompt string. - -The easiest way to construct a keymap with a prompt string is to -specify the string as an argument when you call @code{make-keymap}, -@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or -@code{define-prefix-command} (@pxref{Definition of -define-prefix-command}). If you do not want the keymap to operate as -a menu, don't specify a prompt string for it. - -@defun keymap-prompt keymap -This function returns the overall prompt string of @var{keymap}, -or @code{nil} if it has none. -@end defun - -The menu's items are the bindings in the keymap. Each binding -associates an event type to a definition, but the event types have no -significance for the menu appearance. (Usually we use pseudo-events, -symbols that the keyboard cannot generate, as the event types for menu -item bindings.) The menu is generated entirely from the bindings that -correspond in the keymap to these events. - -The order of items in the menu is the same as the order of bindings in -the keymap. Since @code{define-key} puts new bindings at the front, you -should define the menu items starting at the bottom of the menu and -moving to the top, if you care about the order. When you add an item to -an existing menu, you can specify its position in the menu using -@code{define-key-after} (@pxref{Modifying Menus}). - -@menu -* Simple Menu Items:: A simple kind of menu key binding, - limited in capabilities. -* Extended Menu Items:: More powerful menu item definitions - let you specify keywords to enable - various features. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. -* Toolkit Differences:: Not all toolkits provide the same features. -@end menu - - -@node Simple Menu Items -@subsubsection Simple Menu Items - - The simpler (and original) way to define a menu item is to bind some -event type (it doesn't matter what event type) to a binding like this: - -@example -(@var{item-string} . @var{real-binding}) -@end example - -@noindent -The @sc{car}, @var{item-string}, is the string to be displayed in the -menu. It should be short---preferably one to three words. It should -describe the action of the command it corresponds to. Note that not -all graphical toolkits can display non-@acronym{ASCII} text in menus -(it will work for keyboard menus and will work to a large extent with -the GTK+ toolkit). - - You can also supply a second string, called the help string, as follows: - -@example -(@var{item-string} @var{help} . @var{real-binding}) -@end example - -@noindent -@var{help} specifies a ``help-echo'' string to display while the mouse -is on that item in the same way as @code{help-echo} text properties -(@pxref{Help display}). - - As far as @code{define-key} is concerned, @var{item-string} and -@var{help-string} are part of the event's binding. However, -@code{lookup-key} returns just @var{real-binding}, and only -@var{real-binding} is used for executing the key. - - If @var{real-binding} is @code{nil}, then @var{item-string} appears in -the menu but cannot be selected. - - If @var{real-binding} is a symbol and has a non-@code{nil} -@code{menu-enable} property, that property is an expression that -controls whether the menu item is enabled. Every time the keymap is -used to display a menu, Emacs evaluates the expression, and it enables -the menu item only if the expression's value is non-@code{nil}. When a -menu item is disabled, it is displayed in a ``fuzzy'' fashion, and -cannot be selected. - - The menu bar does not recalculate which items are enabled every time you -look at a menu. This is because the X toolkit requires the whole tree -of menus in advance. To force recalculation of the menu bar, call -@code{force-mode-line-update} (@pxref{Mode Line Format}). - -@node Extended Menu Items -@subsubsection Extended Menu Items -@kindex menu-item -@cindex extended menu item - - An extended-format menu item is a more flexible and also cleaner -alternative to the simple format. You define an event type with a -binding that's a list starting with the symbol @code{menu-item}. -For a non-selectable string, the binding looks like this: - -@example -(menu-item @var{item-name}) -@end example - -@noindent -A string starting with two or more dashes specifies a separator line; -see @ref{Menu Separators}. - - To define a real menu item which can be selected, the extended format -binding looks like this: - -@example -(menu-item @var{item-name} @var{real-binding} - . @var{item-property-list}) -@end example - -@noindent -Here, @var{item-name} is an expression which evaluates to the menu item -string. Thus, the string need not be a constant. The third element, -@var{real-binding}, is the command to execute. The tail of the list, -@var{item-property-list}, has the form of a property list which contains -other information. - - Here is a table of the properties that are supported: - -@table @code -@item :enable @var{form} -The result of evaluating @var{form} determines whether the item is -enabled (non-@code{nil} means yes). If the item is not enabled, -you can't really click on it. - -@item :visible @var{form} -The result of evaluating @var{form} determines whether the item should -actually appear in the menu (non-@code{nil} means yes). If the item -does not appear, then the menu is displayed as if this item were -not defined at all. - -@item :help @var{help} -The value of this property, @var{help}, specifies a ``help-echo'' string -to display while the mouse is on that item. This is displayed in the -same way as @code{help-echo} text properties (@pxref{Help display}). -Note that this must be a constant string, unlike the @code{help-echo} -property for text and overlays. - -@item :button (@var{type} . @var{selected}) -This property provides a way to define radio buttons and toggle buttons. -The @sc{car}, @var{type}, says which: it should be @code{:toggle} or -@code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the -result of evaluating it says whether this button is currently selected. - -A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off'' -according to the value of @var{selected}. The command itself should -toggle @var{selected}, setting it to @code{t} if it is @code{nil}, -and to @code{nil} if it is @code{t}. Here is how the menu item -to toggle the @code{debug-on-error} flag is defined: - -@example -(menu-item "Debug on Error" toggle-debug-on-error - :button (:toggle - . (and (boundp 'debug-on-error) - debug-on-error))) -@end example - -@noindent -This works because @code{toggle-debug-on-error} is defined as a command -which toggles the variable @code{debug-on-error}. - -@dfn{Radio buttons} are a group of menu items, in which at any time one -and only one is ``selected''. There should be a variable whose value -says which one is selected at any time. The @var{selected} form for -each radio button in the group should check whether the variable has the -right value for selecting that button. Clicking on the button should -set the variable so that the button you clicked on becomes selected. - -@item :key-sequence @var{key-sequence} -This property specifies which key sequence is likely to be bound to the -same command invoked by this menu item. If you specify the right key -sequence, that makes preparing the menu for display run much faster. - -If you specify the wrong key sequence, it has no effect; before Emacs -displays @var{key-sequence} in the menu, it verifies that -@var{key-sequence} is really equivalent to this menu item. - -@item :key-sequence nil -This property indicates that there is normally no key binding which is -equivalent to this menu item. Using this property saves time in -preparing the menu for display, because Emacs does not need to search -the keymaps for a keyboard equivalent for this menu item. - -However, if the user has rebound this item's definition to a key -sequence, Emacs ignores the @code{:keys} property and finds the keyboard -equivalent anyway. - -@item :keys @var{string} -This property specifies that @var{string} is the string to display -as the keyboard equivalent for this menu item. You can use -the @samp{\\[...]} documentation construct in @var{string}. - -@item :filter @var{filter-fn} -This property provides a way to compute the menu item dynamically. -The property value @var{filter-fn} should be a function of one argument; -when it is called, its argument will be @var{real-binding}. The -function should return the binding to use instead. - -Emacs can call this function at any time that it does redisplay or -operates on menu data structures, so you should write it so it can -safely be called at any time. -@end table - -@node Menu Separators -@subsubsection Menu Separators -@cindex menu separators - - A menu separator is a kind of menu item that doesn't display any -text---instead, it divides the menu into subparts with a horizontal line. -A separator looks like this in the menu keymap: - -@example -(menu-item @var{separator-type}) -@end example - -@noindent -where @var{separator-type} is a string starting with two or more dashes. - - In the simplest case, @var{separator-type} consists of only dashes. -That specifies the default kind of separator. (For compatibility, -@code{""} and @code{-} also count as separators.) - - Certain other values of @var{separator-type} specify a different -style of separator. Here is a table of them: - -@table @code -@item "--no-line" -@itemx "--space" -An extra vertical space, with no actual line. - -@item "--single-line" -A single line in the menu's foreground color. - -@item "--double-line" -A double line in the menu's foreground color. - -@item "--single-dashed-line" -A single dashed line in the menu's foreground color. - -@item "--double-dashed-line" -A double dashed line in the menu's foreground color. - -@item "--shadow-etched-in" -A single line with a 3D sunken appearance. This is the default, -used separators consisting of dashes only. - -@item "--shadow-etched-out" -A single line with a 3D raised appearance. - -@item "--shadow-etched-in-dash" -A single dashed line with a 3D sunken appearance. - -@item "--shadow-etched-out-dash" -A single dashed line with a 3D raised appearance. - -@item "--shadow-double-etched-in" -Two lines with a 3D sunken appearance. - -@item "--shadow-double-etched-out" -Two lines with a 3D raised appearance. - -@item "--shadow-double-etched-in-dash" -Two dashed lines with a 3D sunken appearance. - -@item "--shadow-double-etched-out-dash" -Two dashed lines with a 3D raised appearance. -@end table - - You can also give these names in another style, adding a colon after -the double-dash and replacing each single dash with capitalization of -the following word. Thus, @code{"--:singleLine"}, is equivalent to -@code{"--single-line"}. - - You can use a longer form to specify keywords such as @code{:enable} -and @code{:visible} for a menu separator: - -@code{(menu-item @var{separator-type} nil . @var{item-property-list})} - -For example: - -@example -(menu-item "--" nil :visible (boundp 'foo)) -@end example - - Some systems and display toolkits don't really handle all of these -separator types. If you use a type that isn't supported, the menu -displays a similar kind of separator that is supported. - -@node Alias Menu Items -@subsubsection Alias Menu Items - - Sometimes it is useful to make menu items that use the ``same'' -command but with different enable conditions. The best way to do this -in Emacs now is with extended menu items; before that feature existed, -it could be done by defining alias commands and using them in menu -items. Here's an example that makes two aliases for -@code{toggle-read-only} and gives them different enable conditions: - -@example -(defalias 'make-read-only 'toggle-read-only) -(put 'make-read-only 'menu-enable '(not buffer-read-only)) -(defalias 'make-writable 'toggle-read-only) -(put 'make-writable 'menu-enable 'buffer-read-only) -@end example - -When using aliases in menus, often it is useful to display the -equivalent key bindings for the ``real'' command name, not the aliases -(which typically don't have any key bindings except for the menu -itself). To request this, give the alias symbol a non-@code{nil} -@code{menu-alias} property. Thus, - -@example -(put 'make-read-only 'menu-alias t) -(put 'make-writable 'menu-alias t) -@end example - -@noindent -causes menu items for @code{make-read-only} and @code{make-writable} to -show the keyboard bindings for @code{toggle-read-only}. - -@node Toolkit Differences -@subsubsection Toolkit Differences - -The various toolkits with which you can build Emacs do not all support -the same set of features for menus. Some code works as expected with -one toolkit, but not under another. - -One example is menu actions or buttons in a top-level menu bar. The -following works with the Lucid toolkit or on MS Windows, but not with -GTK or Nextstep, where clicking on the item has no effect. - -@example -(defun menu-action-greet () - (interactive) - (message "Hello Emacs User!")) - -(defun top-level-menu () - (interactive) - (define-key lisp-interaction-mode-map [menu-bar m] - '(menu-item "Action Button" menu-action-greet))) -@end example - -@node Mouse Menus -@subsection Menus and the Mouse - - The usual way to make a menu keymap produce a menu is to make it the -definition of a prefix key. (A Lisp program can explicitly pop up a -menu and receive the user's choice---see @ref{Pop-Up Menus}.) - - If the prefix key ends with a mouse event, Emacs handles the menu keymap -by popping up a visible menu, so that the user can select a choice with -the mouse. When the user clicks on a menu item, the event generated is -whatever character or symbol has the binding that brought about that -menu item. (A menu item may generate a series of events if the menu has -multiple levels or comes from the menu bar.) - - It's often best to use a button-down event to trigger the menu. Then -the user can select a menu item by releasing the button. - -@cindex submenu - If the menu keymap contains a binding to a nested keymap, the nested -keymap specifies a @dfn{submenu}. There will be a menu item, labeled -by the nested keymap's item string, and clicking on this item -automatically pops up the specified submenu. As a special exception, -if the menu keymap contains a single nested keymap and no other menu -items, the menu shows the contents of the nested keymap directly, not -as a submenu. - - However, if Emacs is compiled without X toolkit support, submenus -are not supported. Each nested keymap is shown as a menu item, but -clicking on it does not automatically pop up the submenu. If you wish -to imitate the effect of submenus, you can do that by giving a nested -keymap an item string which starts with @samp{@@}. This causes Emacs -to display the nested keymap using a separate @dfn{menu pane}; the -rest of the item string after the @samp{@@} is the pane label. If -Emacs is compiled without X toolkit support, menu panes are not used; -in that case, a @samp{@@} at the beginning of an item string is -omitted when the menu label is displayed, and has no other effect. - -@node Keyboard Menus -@subsection Menus and the Keyboard - - When a prefix key ending with a keyboard event (a character or -function key) has a definition that is a menu keymap, the keymap -operates as a keyboard menu; the user specifies the next event by -choosing a menu item with the keyboard. - - Emacs displays the keyboard menu with the map's overall prompt -string, followed by the alternatives (the item strings of the map's -bindings), in the echo area. If the bindings don't all fit at once, -the user can type @key{SPC} to see the next line of alternatives. -Successive uses of @key{SPC} eventually get to the end of the menu and -then cycle around to the beginning. (The variable -@code{menu-prompt-more-char} specifies which character is used for -this; @key{SPC} is the default.) - - When the user has found the desired alternative from the menu, he or -she should type the corresponding character---the one whose binding is -that alternative. - -@defvar menu-prompt-more-char -This variable specifies the character to use to ask to see -the next line of a menu. Its initial value is 32, the code -for @key{SPC}. -@end defvar - -@node Menu Example -@subsection Menu Example -@cindex menu definition example - - Here is a complete example of defining a menu keymap. It is the -definition of the @samp{Replace} submenu in the @samp{Edit} menu in -the menu bar, and it uses the extended menu item format -(@pxref{Extended Menu Items}). First we create the keymap, and give -it a name: - -@smallexample -(defvar menu-bar-replace-menu (make-sparse-keymap "Replace")) -@end smallexample - -@noindent -Next we define the menu items: - -@smallexample -(define-key menu-bar-replace-menu [tags-repl-continue] - '(menu-item "Continue Replace" tags-loop-continue - :help "Continue last tags replace operation")) -(define-key menu-bar-replace-menu [tags-repl] - '(menu-item "Replace in tagged files" tags-query-replace - :help "Interactively replace a regexp in all tagged files")) -(define-key menu-bar-replace-menu [separator-replace-tags] - '(menu-item "--")) -;; @r{@dots{}} -@end smallexample - -@noindent -Note the symbols which the bindings are ``made for''; these appear -inside square brackets, in the key sequence being defined. In some -cases, this symbol is the same as the command name; sometimes it is -different. These symbols are treated as ``function keys'', but they are -not real function keys on the keyboard. They do not affect the -functioning of the menu itself, but they are ``echoed'' in the echo area -when the user selects from the menu, and they appear in the output of -@code{where-is} and @code{apropos}. - - The menu in this example is intended for use with the mouse. If a -menu is intended for use with the keyboard, that is, if it is bound to -a key sequence ending with a keyboard event, then the menu items -should be bound to characters or ``real'' function keys, that can be -typed with the keyboard. - - The binding whose definition is @code{("--")} is a separator line. -Like a real menu item, the separator has a key symbol, in this case -@code{separator-replace-tags}. If one menu has two separators, they -must have two different key symbols. - - Here is how we make this menu appear as an item in the parent menu: - -@example -(define-key menu-bar-edit-menu [replace] - (list 'menu-item "Replace" menu-bar-replace-menu)) -@end example - -@noindent -Note that this incorporates the submenu keymap, which is the value of -the variable @code{menu-bar-replace-menu}, rather than the symbol -@code{menu-bar-replace-menu} itself. Using that symbol in the parent -menu item would be meaningless because @code{menu-bar-replace-menu} is -not a command. - - If you wanted to attach the same replace menu to a mouse click, you -can do it this way: - -@example -(define-key global-map [C-S-down-mouse-1] - menu-bar-replace-menu) -@end example - -@node Menu Bar -@subsection The Menu Bar -@cindex menu bar - - On graphical displays, there is usually a @dfn{menu bar} at the top -of each frame. @xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu -bar items are subcommands of the fake ``function key'' -@code{menu-bar}, as defined in the active keymaps. - - To add an item to the menu bar, invent a fake ``function key'' of your -own (let's call it @var{key}), and make a binding for the key sequence -@code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap, -so that pressing a button on the menu bar item leads to another menu. - - When more than one active keymap defines the same ``function key'' -for the menu bar, the item appears just once. If the user clicks on -that menu bar item, it brings up a single, combined menu containing -all the subcommands of that item---the global subcommands, the local -subcommands, and the minor mode subcommands. - - The variable @code{overriding-local-map} is normally ignored when -determining the menu bar contents. That is, the menu bar is computed -from the keymaps that would be active if @code{overriding-local-map} -were @code{nil}. @xref{Active Keymaps}. - - Here's an example of setting up a menu bar item: - -@example -@group -;; @r{Make a menu keymap (with a prompt string)} -;; @r{and make it the menu bar item's definition.} -(define-key global-map [menu-bar words] - (cons "Words" (make-sparse-keymap "Words"))) -@end group - -@group -;; @r{Define specific subcommands in this menu.} -(define-key global-map - [menu-bar words forward] - '("Forward word" . forward-word)) -@end group -@group -(define-key global-map - [menu-bar words backward] - '("Backward word" . backward-word)) -@end group -@end example - - A local keymap can cancel a menu bar item made by the global keymap by -rebinding the same fake function key with @code{undefined} as the -binding. For example, this is how Dired suppresses the @samp{Edit} menu -bar item: - -@example -(define-key dired-mode-map [menu-bar edit] 'undefined) -@end example - -@noindent -Here, @code{edit} is the fake function key used by the global map for -the @samp{Edit} menu bar item. The main reason to suppress a global -menu bar item is to regain space for mode-specific items. - -@defvar menu-bar-final-items -Normally the menu bar shows global items followed by items defined by the -local maps. - -This variable holds a list of fake function keys for items to display at -the end of the menu bar rather than in normal sequence. The default -value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears -at the end of the menu bar, following local menu items. -@end defvar - -@defvar menu-bar-update-hook -This normal hook is run by redisplay to update the menu bar contents, -before redisplaying the menu bar. You can use it to update submenus -whose contents should vary. Since this hook is run frequently, we -advise you to ensure that the functions it calls do not take much time -in the usual case. -@end defvar - -Next to every menu bar item, Emacs displays a key binding that runs -the same command (if such a key binding exists). This serves as a -convenient hint for users who do not know the key binding. If a -command has multiple bindings, Emacs normally displays the first one -it finds. You can specify one particular key binding by assigning an -@code{:advertised-binding} symbol property to the command. @xref{Keys -in Documentation}. - -@node Tool Bar -@subsection Tool bars -@cindex tool bar - - A @dfn{tool bar} is a row of clickable icons at the top of a frame, -just below the menu bar. @xref{Tool Bars,,,emacs, The GNU Emacs -Manual}. - - On each frame, the frame parameter @code{tool-bar-lines} controls -how many lines' worth of height to reserve for the tool bar. A zero -value suppresses the tool bar. If the value is nonzero, and -@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands -and contracts automatically as needed to hold the specified contents. -If the value is @code{grow-only}, the tool bar expands automatically, -but does not contract automatically. - - The tool bar contents are controlled by a menu keymap attached to a -fake ``function key'' called @code{tool-bar} (much like the way the menu -bar is controlled). So you define a tool bar item using -@code{define-key}, like this: - -@example -(define-key global-map [tool-bar @var{key}] @var{item}) -@end example - -@noindent -where @var{key} is a fake ``function key'' to distinguish this item from -other items, and @var{item} is a menu item key binding (@pxref{Extended -Menu Items}), which says how to display this item and how it behaves. - - The usual menu keymap item properties, @code{:visible}, -@code{:enable}, @code{:button}, and @code{:filter}, are useful in -tool bar bindings and have their normal meanings. The @var{real-binding} -in the item must be a command, not a keymap; in other words, it does not -work to define a tool bar icon as a prefix key. - - The @code{:help} property specifies a ``help-echo'' string to display -while the mouse is on that item. This is displayed in the same way as -@code{help-echo} text properties (@pxref{Help display}). - - In addition, you should use the @code{:image} property; -this is how you specify the image to display in the tool bar: - -@table @code -@item :image @var{image} -@var{images} is either a single image specification or a vector of four -image specifications. If you use a vector of four, -one of them is used, depending on circumstances: - -@table @asis -@item item 0 -Used when the item is enabled and selected. -@item item 1 -Used when the item is enabled and deselected. -@item item 2 -Used when the item is disabled and selected. -@item item 3 -Used when the item is disabled and deselected. -@end table -@end table - -If @var{image} is a single image specification, Emacs draws the tool bar -button in disabled state by applying an edge-detection algorithm to the -image. - -The @code{:rtl} property specifies an alternative image to use for -right-to-left languages. Only the GTK+ version of Emacs supports this -at present. - -Like the menu bar, the tool bar can display separators (@pxref{Menu -Separators}). Tool bar separators are vertical rather than -horizontal, though, and only a single style is supported. They are -represented in the tool bar keymap by @code{(menu-item "--")} entries; -properties like @code{:visible} are not supported for tool bar -separators. Separators are rendered natively in GTK+ and Nextstep -tool bars; in the other cases, they are rendered using an image of a -vertical line. - -The default tool bar is defined so that items specific to editing do not -appear for major modes whose command symbol has a @code{mode-class} -property of @code{special} (@pxref{Major Mode Conventions}). Major -modes may add items to the global bar by binding @code{[tool-bar -@var{foo}]} in their local map. It makes sense for some major modes to -replace the default tool bar items completely, since not many can be -accommodated conveniently, and the default bindings make this easy by -using an indirection through @code{tool-bar-map}. - -@defvar tool-bar-map -By default, the global map binds @code{[tool-bar]} as follows: - -@example -(global-set-key [tool-bar] - `(menu-item ,(purecopy "tool bar") ignore - :filter tool-bar-make-keymap)) -@end example - -@noindent -The function @code{tool-bar-make-keymap}, in turn, derives the actual -tool bar map dynamically from the value of the variable -@code{tool-bar-map}. Hence, you should normally adjust the default -(global) tool bar by changing that map. Some major modes, such as -Info mode, completely replace the global tool bar by making -@code{tool-bar-map} buffer-local and setting it to a different keymap. -@end defvar - -There are two convenience functions for defining tool bar items, as -follows. - -@defun tool-bar-add-item icon def key &rest props -This function adds an item to the tool bar by modifying -@code{tool-bar-map}. The image to use is defined by @var{icon}, which -is the base name of an XPM, XBM or PBM image file to be located by -@code{find-image}. Given a value @samp{"exit"}, say, @file{exit.xpm}, -@file{exit.pbm} and @file{exit.xbm} would be searched for in that order -on a color display. On a monochrome display, the search order is -@samp{.pbm}, @samp{.xbm} and @samp{.xpm}. The binding to use is the -command @var{def}, and @var{key} is the fake function key symbol in the -prefix keymap. The remaining arguments @var{props} are additional -property list elements to add to the menu item specification. - -To define items in some local map, bind @code{tool-bar-map} with -@code{let} around calls of this function: -@example -(defvar foo-tool-bar-map - (let ((tool-bar-map (make-sparse-keymap))) - (tool-bar-add-item @dots{}) - @dots{} - tool-bar-map)) -@end example -@end defun - -@defun tool-bar-add-item-from-menu command icon &optional map &rest props -This function is a convenience for defining tool bar items which are -consistent with existing menu bar bindings. The binding of -@var{command} is looked up in the menu bar in @var{map} (default -@code{global-map}) and modified to add an image specification for -@var{icon}, which is found in the same way as by -@code{tool-bar-add-item}. The resulting binding is then placed in -@code{tool-bar-map}, so use this function only for global tool bar -items. - -@var{map} must contain an appropriate keymap bound to -@code{[menu-bar]}. The remaining arguments @var{props} are additional -property list elements to add to the menu item specification. -@end defun - -@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props -This function is used for making non-global tool bar items. Use it -like @code{tool-bar-add-item-from-menu} except that @var{in-map} -specifies the local map to make the definition in. The argument -@var{from-map} is like the @var{map} argument of -@code{tool-bar-add-item-from-menu}. -@end defun - -@defvar auto-resize-tool-bars -If this variable is non-@code{nil}, the tool bar automatically resizes to -show all defined tool bar items---but not larger than a quarter of the -frame's height. - -If the value is @code{grow-only}, the tool bar expands automatically, -but does not contract automatically. To contract the tool bar, the -user has to redraw the frame by entering @kbd{C-l}. - -If Emacs is built with GTK or Nextstep, the tool bar can only show one -line, so this variable has no effect. -@end defvar - -@defvar auto-raise-tool-bar-buttons -If this variable is non-@code{nil}, tool bar items display -in raised form when the mouse moves over them. -@end defvar - -@defvar tool-bar-button-margin -This variable specifies an extra margin to add around tool bar items. -The value is an integer, a number of pixels. The default is 4. -@end defvar - -@defvar tool-bar-button-relief -This variable specifies the shadow width for tool bar items. -The value is an integer, a number of pixels. The default is 1. -@end defvar - -@defvar tool-bar-border -This variable specifies the height of the border drawn below the tool -bar area. An integer value specifies height as a number of pixels. -If the value is one of @code{internal-border-width} (the default) or -@code{border-width}, the tool bar border height corresponds to the -corresponding frame parameter. -@end defvar - - You can define a special meaning for clicking on a tool bar item with -the shift, control, meta, etc., modifiers. You do this by setting up -additional items that relate to the original item through the fake -function keys. Specifically, the additional items should use the -modified versions of the same fake function key used to name the -original item. - - Thus, if the original item was defined this way, - -@example -(define-key global-map [tool-bar shell] - '(menu-item "Shell" shell - :image (image :type xpm :file "shell.xpm"))) -@end example - -@noindent -then here is how you can define clicking on the same tool bar image with -the shift modifier: - -@example -(define-key global-map [tool-bar S-shell] 'some-command) -@end example - -@xref{Function Keys}, for more information about how to add modifiers to -function keys. - -@node Modifying Menus -@subsection Modifying Menus - - When you insert a new item in an existing menu, you probably want to -put it in a particular place among the menu's existing items. If you -use @code{define-key} to add the item, it normally goes at the front of -the menu. To put it elsewhere in the menu, use @code{define-key-after}: - -@defun define-key-after map key binding &optional after -Define a binding in @var{map} for @var{key}, with value @var{binding}, -just like @code{define-key}, but position the binding in @var{map} after -the binding for the event @var{after}. The argument @var{key} should be -of length one---a vector or string with just one element. But -@var{after} should be a single event type---a symbol or a character, not -a sequence. The new binding goes after the binding for @var{after}. If -@var{after} is @code{t} or is omitted, then the new binding goes last, at -the end of the keymap. However, new bindings are added before any -inherited keymap. - -Here is an example: - -@example -(define-key-after my-menu [drink] - '("Drink" . drink-command) 'eat) -@end example - -@noindent -makes a binding for the fake function key @key{DRINK} and puts it -right after the binding for @key{EAT}. - -Here is how to insert an item called @samp{Work} in the @samp{Signals} -menu of Shell mode, after the item @code{break}: - -@example -(define-key-after - (lookup-key shell-mode-map [menu-bar signals]) - [work] '("Work" . work-command) 'break) -@end example -@end defun diff --git a/doc/lispref/lay-flat.texi b/doc/lispref/lay-flat.texi deleted file mode 100644 index 73e2adbc03a..00000000000 --- a/doc/lispref/lay-flat.texi +++ /dev/null @@ -1,43 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@c -@comment %**start of header -@setfilename inner-covers.info -@settitle Inner Covers -@smallbook -@comment %**end of header - -@headings off - -@w{ } -@sp 4 -@tex -\center {\secfonts \rm Lay-Flat Binding} -@end tex -@sp 2 - -We have bound this manual using a new @dfn{lay-flat} binding -technology. This type of binding allows you to open a soft cover book -so that it ``lays flat'' on a table without creasing the binding. - -In order to make the book lay flat properly, you need to ``crack'' the -binding. To do this, divide the book into two sections and bend it so -that the front and back covers meet. Do not worry; the pages are -sewn and glued to the binding, and will not fall out easily. -The outer cardboard binding itself is designed so that it will not -break or crease as an ordinary paperback binding will. Bend the book -several times in this manner, dividing it in a different place each -time and pressing the pages flat and open. With use, the binding will -become flexible and the pages will lay flat without needing to be -pushed or held down. - -@page - - -@tex -\center {\secfonts \rm Notes} -@end tex - -@bye diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi deleted file mode 100644 index a894d93a4a0..00000000000 --- a/doc/lispref/lists.texi +++ /dev/null @@ -1,1803 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/lists -@node Lists, Sequences Arrays Vectors, Strings and Characters, Top -@chapter Lists -@cindex lists -@cindex element (of list) - - A @dfn{list} represents a sequence of zero or more elements (which may -be any Lisp objects). The important difference between lists and -vectors is that two or more lists can share part of their structure; in -addition, you can insert or delete elements in a list without copying -the whole list. - -@menu -* Cons Cells:: How lists are made out of cons cells. -* List-related Predicates:: Is this object a list? Comparing two lists. -* List Elements:: Extracting the pieces of a list. -* Building Lists:: Creating list structure. -* List Variables:: Modifying lists stored in variables. -* Modifying Lists:: Storing new pieces into an existing list. -* Sets And Lists:: A list can represent a finite mathematical set. -* Association Lists:: A list can represent a finite relation or mapping. -@end menu - -@node Cons Cells -@section Lists and Cons Cells -@cindex lists and cons cells - - Lists in Lisp are not a primitive data type; they are built up from -@dfn{cons cells} (@pxref{Cons Cell Type}). A cons cell is a data -object that represents an ordered pair. That is, it has two slots, -and each slot @dfn{holds}, or @dfn{refers to}, some Lisp object. One -slot is known as the @sc{car}, and the other is known as the @sc{cdr}. -(These names are traditional; see @ref{Cons Cell Type}.) @sc{cdr} is -pronounced ``could-er''. - - We say that ``the @sc{car} of this cons cell is'' whatever object -its @sc{car} slot currently holds, and likewise for the @sc{cdr}. - - A list is a series of cons cells ``chained together'', so that each -cell refers to the next one. There is one cons cell for each element -of the list. By convention, the @sc{car}s of the cons cells hold the -elements of the list, and the @sc{cdr}s are used to chain the list -(this asymmetry between @sc{car} and @sc{cdr} is entirely a matter of -convention; at the level of cons cells, the @sc{car} and @sc{cdr} -slots have similar properties). Hence, the @sc{cdr} slot of each cons -cell in a list refers to the following cons cell. - -@cindex true list - Also by convention, the @sc{cdr} of the last cons cell in a list is -@code{nil}. We call such a @code{nil}-terminated structure a -@dfn{true list}. In Emacs Lisp, the symbol @code{nil} is both a -symbol and a list with no elements. For convenience, the symbol -@code{nil} is considered to have @code{nil} as its @sc{cdr} (and also -as its @sc{car}). - - Hence, the @sc{cdr} of a true list is always a true list. The -@sc{cdr} of a nonempty true list is a true list containing all the -elements except the first. - -@cindex dotted list -@cindex circular list - If the @sc{cdr} of a list's last cons cell is some value other than -@code{nil}, we call the structure a @dfn{dotted list}, since its -printed representation would use dotted pair notation (@pxref{Dotted -Pair Notation}). There is one other possibility: some cons cell's -@sc{cdr} could point to one of the previous cons cells in the list. -We call that structure a @dfn{circular list}. - - For some purposes, it does not matter whether a list is true, -circular or dotted. If a program doesn't look far enough down the -list to see the @sc{cdr} of the final cons cell, it won't care. -However, some functions that operate on lists demand true lists and -signal errors if given a dotted list. Most functions that try to find -the end of a list enter infinite loops if given a circular list. - -@cindex list structure - Because most cons cells are used as part of lists, we refer to any -structure made out of cons cells as a @dfn{list structure}. - -@node List-related Predicates -@section Predicates on Lists - - The following predicates test whether a Lisp object is an atom, -whether it is a cons cell or is a list, or whether it is the -distinguished object @code{nil}. (Many of these predicates can be -defined in terms of the others, but they are used so often that it is -worth having them.) - -@defun consp object -This function returns @code{t} if @var{object} is a cons cell, @code{nil} -otherwise. @code{nil} is not a cons cell, although it @emph{is} a list. -@end defun - -@defun atom object -This function returns @code{t} if @var{object} is an atom, @code{nil} -otherwise. All objects except cons cells are atoms. The symbol -@code{nil} is an atom and is also a list; it is the only Lisp object -that is both. - -@example -(atom @var{object}) @equiv{} (not (consp @var{object})) -@end example -@end defun - -@defun listp object -This function returns @code{t} if @var{object} is a cons cell or -@code{nil}. Otherwise, it returns @code{nil}. - -@example -@group -(listp '(1)) - @result{} t -@end group -@group -(listp '()) - @result{} t -@end group -@end example -@end defun - -@defun nlistp object -This function is the opposite of @code{listp}: it returns @code{t} if -@var{object} is not a list. Otherwise, it returns @code{nil}. - -@example -(listp @var{object}) @equiv{} (not (nlistp @var{object})) -@end example -@end defun - -@defun null object -This function returns @code{t} if @var{object} is @code{nil}, and -returns @code{nil} otherwise. This function is identical to @code{not}, -but as a matter of clarity we use @code{null} when @var{object} is -considered a list and @code{not} when it is considered a truth value -(see @code{not} in @ref{Combining Conditions}). - -@example -@group -(null '(1)) - @result{} nil -@end group -@group -(null '()) - @result{} t -@end group -@end example -@end defun - - -@node List Elements -@section Accessing Elements of Lists -@cindex list elements - -@defun car cons-cell -This function returns the value referred to by the first slot of the -cons cell @var{cons-cell}. In other words, it returns the @sc{car} of -@var{cons-cell}. - -As a special case, if @var{cons-cell} is @code{nil}, this function -returns @code{nil}. Therefore, any list is a valid argument. An -error is signaled if the argument is not a cons cell or @code{nil}. - -@example -@group -(car '(a b c)) - @result{} a -@end group -@group -(car '()) - @result{} nil -@end group -@end example -@end defun - -@defun cdr cons-cell -This function returns the value referred to by the second slot of the -cons cell @var{cons-cell}. In other words, it returns the @sc{cdr} of -@var{cons-cell}. - -As a special case, if @var{cons-cell} is @code{nil}, this function -returns @code{nil}; therefore, any list is a valid argument. An error -is signaled if the argument is not a cons cell or @code{nil}. - -@example -@group -(cdr '(a b c)) - @result{} (b c) -@end group -@group -(cdr '()) - @result{} nil -@end group -@end example -@end defun - -@defun car-safe object -This function lets you take the @sc{car} of a cons cell while avoiding -errors for other data types. It returns the @sc{car} of @var{object} if -@var{object} is a cons cell, @code{nil} otherwise. This is in contrast -to @code{car}, which signals an error if @var{object} is not a list. - -@example -@group -(car-safe @var{object}) -@equiv{} -(let ((x @var{object})) - (if (consp x) - (car x) - nil)) -@end group -@end example -@end defun - -@defun cdr-safe object -This function lets you take the @sc{cdr} of a cons cell while -avoiding errors for other data types. It returns the @sc{cdr} of -@var{object} if @var{object} is a cons cell, @code{nil} otherwise. -This is in contrast to @code{cdr}, which signals an error if -@var{object} is not a list. - -@example -@group -(cdr-safe @var{object}) -@equiv{} -(let ((x @var{object})) - (if (consp x) - (cdr x) - nil)) -@end group -@end example -@end defun - -@defmac pop listname -This macro is a way of examining the @sc{car} of a list, -and taking it off the list, all at once. - -It operates on the list which is stored in the symbol @var{listname}. -It removes this element from the list by setting @var{listname} -to the @sc{cdr} of its old value---but it also returns the @sc{car} -of that list, which is the element being removed. - -@example -x - @result{} (a b c) -(pop x) - @result{} a -x - @result{} (b c) -@end example - -@noindent -For the @code{pop} macro, which removes an element from a list, -@xref{List Variables}. -@end defmac - -@defun nth n list -@anchor{Definition of nth} -This function returns the @var{n}th element of @var{list}. Elements -are numbered starting with zero, so the @sc{car} of @var{list} is -element number zero. If the length of @var{list} is @var{n} or less, -the value is @code{nil}. - -If @var{n} is negative, @code{nth} returns the first element of -@var{list}. - -@example -@group -(nth 2 '(1 2 3 4)) - @result{} 3 -@end group -@group -(nth 10 '(1 2 3 4)) - @result{} nil -@end group -@group -(nth -3 '(1 2 3 4)) - @result{} 1 - -(nth n x) @equiv{} (car (nthcdr n x)) -@end group -@end example - -The function @code{elt} is similar, but applies to any kind of sequence. -For historical reasons, it takes its arguments in the opposite order. -@xref{Sequence Functions}. -@end defun - -@defun nthcdr n list -This function returns the @var{n}th @sc{cdr} of @var{list}. In other -words, it skips past the first @var{n} links of @var{list} and returns -what follows. - -If @var{n} is zero or negative, @code{nthcdr} returns all of -@var{list}. If the length of @var{list} is @var{n} or less, -@code{nthcdr} returns @code{nil}. - -@example -@group -(nthcdr 1 '(1 2 3 4)) - @result{} (2 3 4) -@end group -@group -(nthcdr 10 '(1 2 3 4)) - @result{} nil -@end group -@group -(nthcdr -3 '(1 2 3 4)) - @result{} (1 2 3 4) -@end group -@end example -@end defun - -@defun last list &optional n -This function returns the last link of @var{list}. The @code{car} of -this link is the list's last element. If @var{list} is null, -@code{nil} is returned. If @var{n} is non-@code{nil}, the -@var{n}th-to-last link is returned instead, or the whole of @var{list} -if @var{n} is bigger than @var{list}'s length. -@end defun - -@defun safe-length list -@anchor{Definition of safe-length} -This function returns the length of @var{list}, with no risk of either -an error or an infinite loop. It generally returns the number of -distinct cons cells in the list. However, for circular lists, -the value is just an upper bound; it is often too large. - -If @var{list} is not @code{nil} or a cons cell, @code{safe-length} -returns 0. -@end defun - - The most common way to compute the length of a list, when you are not -worried that it may be circular, is with @code{length}. @xref{Sequence -Functions}. - -@defun caar cons-cell -This is the same as @code{(car (car @var{cons-cell}))}. -@end defun - -@defun cadr cons-cell -This is the same as @code{(car (cdr @var{cons-cell}))} -or @code{(nth 1 @var{cons-cell})}. -@end defun - -@defun cdar cons-cell -This is the same as @code{(cdr (car @var{cons-cell}))}. -@end defun - -@defun cddr cons-cell -This is the same as @code{(cdr (cdr @var{cons-cell}))} -or @code{(nthcdr 2 @var{cons-cell})}. -@end defun - -@defun butlast x &optional n -This function returns the list @var{x} with the last element, -or the last @var{n} elements, removed. If @var{n} is greater -than zero it makes a copy of the list so as not to damage the -original list. In general, @code{(append (butlast @var{x} @var{n}) -(last @var{x} @var{n}))} will return a list equal to @var{x}. -@end defun - -@defun nbutlast x &optional n -This is a version of @code{butlast} that works by destructively -modifying the @code{cdr} of the appropriate element, rather than -making a copy of the list. -@end defun - -@node Building Lists -@comment node-name, next, previous, up -@section Building Cons Cells and Lists -@cindex cons cells -@cindex building lists - - Many functions build lists, as lists reside at the very heart of Lisp. -@code{cons} is the fundamental list-building function; however, it is -interesting to note that @code{list} is used more times in the source -code for Emacs than @code{cons}. - -@defun cons object1 object2 -This function is the most basic function for building new list -structure. It creates a new cons cell, making @var{object1} the -@sc{car}, and @var{object2} the @sc{cdr}. It then returns the new -cons cell. The arguments @var{object1} and @var{object2} may be any -Lisp objects, but most often @var{object2} is a list. - -@example -@group -(cons 1 '(2)) - @result{} (1 2) -@end group -@group -(cons 1 '()) - @result{} (1) -@end group -@group -(cons 1 2) - @result{} (1 . 2) -@end group -@end example - -@cindex consing -@code{cons} is often used to add a single element to the front of a -list. This is called @dfn{consing the element onto the list}. -@footnote{There is no strictly equivalent way to add an element to -the end of a list. You can use @code{(append @var{listname} (list -@var{newelt}))}, which creates a whole new list by copying @var{listname} -and adding @var{newelt} to its end. Or you can use @code{(nconc -@var{listname} (list @var{newelt}))}, which modifies @var{listname} -by following all the @sc{cdr}s and then replacing the terminating -@code{nil}. Compare this to adding an element to the beginning of a -list with @code{cons}, which neither copies nor modifies the list.} -For example: - -@example -(setq list (cons newelt list)) -@end example - -Note that there is no conflict between the variable named @code{list} -used in this example and the function named @code{list} described below; -any symbol can serve both purposes. -@end defun - -@defun list &rest objects -This function creates a list with @var{objects} as its elements. The -resulting list is always @code{nil}-terminated. If no @var{objects} -are given, the empty list is returned. - -@example -@group -(list 1 2 3 4 5) - @result{} (1 2 3 4 5) -@end group -@group -(list 1 2 '(3 4 5) 'foo) - @result{} (1 2 (3 4 5) foo) -@end group -@group -(list) - @result{} nil -@end group -@end example -@end defun - -@defun make-list length object -This function creates a list of @var{length} elements, in which each -element is @var{object}. Compare @code{make-list} with -@code{make-string} (@pxref{Creating Strings}). - -@example -@group -(make-list 3 'pigs) - @result{} (pigs pigs pigs) -@end group -@group -(make-list 0 'pigs) - @result{} nil -@end group -@group -(setq l (make-list 3 '(a b))) - @result{} ((a b) (a b) (a b)) -(eq (car l) (cadr l)) - @result{} t -@end group -@end example -@end defun - -@defun append &rest sequences -@cindex copying lists -This function returns a list containing all the elements of -@var{sequences}. The @var{sequences} may be lists, vectors, -bool-vectors, or strings, but the last one should usually be a list. -All arguments except the last one are copied, so none of the arguments -is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join -lists with no copying.) - -More generally, the final argument to @code{append} may be any Lisp -object. The final argument is not copied or converted; it becomes the -@sc{cdr} of the last cons cell in the new list. If the final argument -is itself a list, then its elements become in effect elements of the -result list. If the final element is not a list, the result is a -dotted list since its final @sc{cdr} is not @code{nil} as required -in a true list. -@end defun - - Here is an example of using @code{append}: - -@example -@group -(setq trees '(pine oak)) - @result{} (pine oak) -(setq more-trees (append '(maple birch) trees)) - @result{} (maple birch pine oak) -@end group - -@group -trees - @result{} (pine oak) -more-trees - @result{} (maple birch pine oak) -@end group -@group -(eq trees (cdr (cdr more-trees))) - @result{} t -@end group -@end example - - You can see how @code{append} works by looking at a box diagram. The -variable @code{trees} is set to the list @code{(pine oak)} and then the -variable @code{more-trees} is set to the list @code{(maple birch pine -oak)}. However, the variable @code{trees} continues to refer to the -original list: - -@smallexample -@group -more-trees trees -| | -| --- --- --- --- -> --- --- --- --- - --> | | |--> | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- --- --- - | | | | - | | | | - --> maple -->birch --> pine --> oak -@end group -@end smallexample - - An empty sequence contributes nothing to the value returned by -@code{append}. As a consequence of this, a final @code{nil} argument -forces a copy of the previous argument: - -@example -@group -trees - @result{} (pine oak) -@end group -@group -(setq wood (append trees nil)) - @result{} (pine oak) -@end group -@group -wood - @result{} (pine oak) -@end group -@group -(eq wood trees) - @result{} nil -@end group -@end example - -@noindent -This once was the usual way to copy a list, before the function -@code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}. - - Here we show the use of vectors and strings as arguments to @code{append}: - -@example -@group -(append [a b] "cd" nil) - @result{} (a b 99 100) -@end group -@end example - - With the help of @code{apply} (@pxref{Calling Functions}), we can append -all the lists in a list of lists: - -@example -@group -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end group -@end example - - If no @var{sequences} are given, @code{nil} is returned: - -@example -@group -(append) - @result{} nil -@end group -@end example - - Here are some examples where the final argument is not a list: - -@example -(append '(x y) 'z) - @result{} (x y . z) -(append '(x y) [z]) - @result{} (x y . [z]) -@end example - -@noindent -The second example shows that when the final argument is a sequence but -not a list, the sequence's elements do not become elements of the -resulting list. Instead, the sequence becomes the final @sc{cdr}, like -any other non-list final argument. - -@defun reverse list -This function creates a new list whose elements are the elements of -@var{list}, but in reverse order. The original argument @var{list} is -@emph{not} altered. - -@example -@group -(setq x '(1 2 3 4)) - @result{} (1 2 3 4) -@end group -@group -(reverse x) - @result{} (4 3 2 1) -x - @result{} (1 2 3 4) -@end group -@end example -@end defun - -@defun copy-tree tree &optional vecp -This function returns a copy of the tree @code{tree}. If @var{tree} is a -cons cell, this makes a new cons cell with the same @sc{car} and -@sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the -same way. - -Normally, when @var{tree} is anything other than a cons cell, -@code{copy-tree} simply returns @var{tree}. However, if @var{vecp} is -non-@code{nil}, it copies vectors too (and operates recursively on -their elements). -@end defun - -@defun number-sequence from &optional to separation -This returns a list of numbers starting with @var{from} and -incrementing by @var{separation}, and ending at or just before -@var{to}. @var{separation} can be positive or negative and defaults -to 1. If @var{to} is @code{nil} or numerically equal to @var{from}, -the value is the one-element list @code{(@var{from})}. If @var{to} is -less than @var{from} with a positive @var{separation}, or greater than -@var{from} with a negative @var{separation}, the value is @code{nil} -because those arguments specify an empty sequence. - -If @var{separation} is 0 and @var{to} is neither @code{nil} nor -numerically equal to @var{from}, @code{number-sequence} signals an -error, since those arguments specify an infinite sequence. - -All arguments can be integers or floating point numbers. However, -floating point arguments can be tricky, because floating point -arithmetic is inexact. For instance, depending on the machine, it may -quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns -the one element list @code{(0.4)}, whereas -@code{(number-sequence 0.4 0.8 0.2)} returns a list with three -elements. The @var{n}th element of the list is computed by the exact -formula @code{(+ @var{from} (* @var{n} @var{separation}))}. Thus, if -one wants to make sure that @var{to} is included in the list, one can -pass an expression of this exact type for @var{to}. Alternatively, -one can replace @var{to} with a slightly larger value (or a slightly -more negative value if @var{separation} is negative). - -Some examples: - -@example -(number-sequence 4 9) - @result{} (4 5 6 7 8 9) -(number-sequence 9 4 -1) - @result{} (9 8 7 6 5 4) -(number-sequence 9 4 -2) - @result{} (9 7 5) -(number-sequence 8) - @result{} (8) -(number-sequence 8 5) - @result{} nil -(number-sequence 5 8 -1) - @result{} nil -(number-sequence 1.5 6 2) - @result{} (1.5 3.5 5.5) -@end example -@end defun - -@node List Variables -@section Modifying List Variables - - These functions, and one macro, provide convenient ways -to modify a list which is stored in a variable. - -@defmac push newelt listname -This macro provides an alternative way to write -@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}. - -@example -(setq l '(a b)) - @result{} (a b) -(push 'c l) - @result{} (c a b) -l - @result{} (c a b) -@end example - -@noindent -For the @code{pop} macro, which removes the first element from a list, -@xref{List Elements}. -@end defmac - - Two functions modify lists that are the values of variables. - -@defun add-to-list symbol element &optional append compare-fn -This function sets the variable @var{symbol} by consing @var{element} -onto the old value, if @var{element} is not already a member of that -value. It returns the resulting list, whether updated or not. The -value of @var{symbol} had better be a list already before the call. -@code{add-to-list} uses @var{compare-fn} to compare @var{element} -against existing list members; if @var{compare-fn} is @code{nil}, it -uses @code{equal}. - -Normally, if @var{element} is added, it is added to the front of -@var{symbol}, but if the optional argument @var{append} is -non-@code{nil}, it is added at the end. - -The argument @var{symbol} is not implicitly quoted; @code{add-to-list} -is an ordinary function, like @code{set} and unlike @code{setq}. Quote -the argument yourself if that is what you want. -@end defun - -Here's a scenario showing how to use @code{add-to-list}: - -@example -(setq foo '(a b)) - @result{} (a b) - -(add-to-list 'foo 'c) ;; @r{Add @code{c}.} - @result{} (c a b) - -(add-to-list 'foo 'b) ;; @r{No effect.} - @result{} (c a b) - -foo ;; @r{@code{foo} was changed.} - @result{} (c a b) -@end example - - An equivalent expression for @code{(add-to-list '@var{var} -@var{value})} is this: - -@example -(or (member @var{value} @var{var}) - (setq @var{var} (cons @var{value} @var{var}))) -@end example - -@defun add-to-ordered-list symbol element &optional order -This function sets the variable @var{symbol} by inserting -@var{element} into the old value, which must be a list, at the -position specified by @var{order}. If @var{element} is already a -member of the list, its position in the list is adjusted according -to @var{order}. Membership is tested using @code{eq}. -This function returns the resulting list, whether updated or not. - -The @var{order} is typically a number (integer or float), and the -elements of the list are sorted in non-decreasing numerical order. - -@var{order} may also be omitted or @code{nil}. Then the numeric order -of @var{element} stays unchanged if it already has one; otherwise, -@var{element} has no numeric order. Elements without a numeric list -order are placed at the end of the list, in no particular order. - -Any other value for @var{order} removes the numeric order of @var{element} -if it already has one; otherwise, it is equivalent to @code{nil}. - -The argument @var{symbol} is not implicitly quoted; -@code{add-to-ordered-list} is an ordinary function, like @code{set} -and unlike @code{setq}. Quote the argument yourself if necessary. - -The ordering information is stored in a hash table on @var{symbol}'s -@code{list-order} property. -@end defun - -Here's a scenario showing how to use @code{add-to-ordered-list}: - -@example -(setq foo '()) - @result{} nil - -(add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.} - @result{} (a) - -(add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.} - @result{} (a c) - -(add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.} - @result{} (a b c) - -(add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.} - @result{} (a c b) - -(add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.} - @result{} (a c b d) - -(add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}. - @result{} (a c b e d) - -foo ;; @r{@code{foo} was changed.} - @result{} (a c b e d) -@end example - -@node Modifying Lists -@section Modifying Existing List Structure -@cindex destructive list operations - - You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the -primitives @code{setcar} and @code{setcdr}. We call these ``destructive'' -operations because they change existing list structure. - -@cindex CL note---@code{rplaca} vs @code{setcar} -@quotation -@findex rplaca -@findex rplacd -@b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and -@code{rplacd} to alter list structure; they change structure the same -way as @code{setcar} and @code{setcdr}, but the Common Lisp functions -return the cons cell while @code{setcar} and @code{setcdr} return the -new @sc{car} or @sc{cdr}. -@end quotation - -@menu -* Setcar:: Replacing an element in a list. -* Setcdr:: Replacing part of the list backbone. - This can be used to remove or add elements. -* Rearrangement:: Reordering the elements in a list; combining lists. -@end menu - -@node Setcar -@subsection Altering List Elements with @code{setcar} - - Changing the @sc{car} of a cons cell is done with @code{setcar}. When -used on a list, @code{setcar} replaces one element of a list with a -different element. - -@defun setcar cons object -This function stores @var{object} as the new @sc{car} of @var{cons}, -replacing its previous @sc{car}. In other words, it changes the -@sc{car} slot of @var{cons} to refer to @var{object}. It returns the -value @var{object}. For example: - -@example -@group -(setq x '(1 2)) - @result{} (1 2) -@end group -@group -(setcar x 4) - @result{} 4 -@end group -@group -x - @result{} (4 2) -@end group -@end example -@end defun - - When a cons cell is part of the shared structure of several lists, -storing a new @sc{car} into the cons changes one element of each of -these lists. Here is an example: - -@example -@group -;; @r{Create two lists that are partly shared.} -(setq x1 '(a b c)) - @result{} (a b c) -(setq x2 (cons 'z (cdr x1))) - @result{} (z b c) -@end group - -@group -;; @r{Replace the @sc{car} of a shared link.} -(setcar (cdr x1) 'foo) - @result{} foo -x1 ; @r{Both lists are changed.} - @result{} (a foo c) -x2 - @result{} (z foo c) -@end group - -@group -;; @r{Replace the @sc{car} of a link that is not shared.} -(setcar x1 'baz) - @result{} baz -x1 ; @r{Only one list is changed.} - @result{} (baz foo c) -x2 - @result{} (z foo c) -@end group -@end example - - Here is a graphical depiction of the shared structure of the two lists -in the variables @code{x1} and @code{x2}, showing why replacing @code{b} -changes them both: - -@example -@group - --- --- --- --- --- --- -x1---> | | |----> | | |--> | | |--> nil - --- --- --- --- --- --- - | --> | | - | | | | - --> a | --> b --> c - | - --- --- | -x2--> | | |-- - --- --- - | - | - --> z -@end group -@end example - - Here is an alternative form of box diagram, showing the same relationship: - -@example -@group -x1: - -------------- -------------- -------------- -| car | cdr | | car | cdr | | car | cdr | -| a | o------->| b | o------->| c | nil | -| | | -->| | | | | | - -------------- | -------------- -------------- - | -x2: | - -------------- | -| car | cdr | | -| z | o---- -| | | - -------------- -@end group -@end example - -@node Setcdr -@subsection Altering the CDR of a List - - The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}: - -@defun setcdr cons object -This function stores @var{object} as the new @sc{cdr} of @var{cons}, -replacing its previous @sc{cdr}. In other words, it changes the -@sc{cdr} slot of @var{cons} to refer to @var{object}. It returns the -value @var{object}. -@end defun - - Here is an example of replacing the @sc{cdr} of a list with a -different list. All but the first element of the list are removed in -favor of a different sequence of elements. The first element is -unchanged, because it resides in the @sc{car} of the list, and is not -reached via the @sc{cdr}. - -@example -@group -(setq x '(1 2 3)) - @result{} (1 2 3) -@end group -@group -(setcdr x '(4)) - @result{} (4) -@end group -@group -x - @result{} (1 4) -@end group -@end example - - You can delete elements from the middle of a list by altering the -@sc{cdr}s of the cons cells in the list. For example, here we delete -the second element, @code{b}, from the list @code{(a b c)}, by changing -the @sc{cdr} of the first cons cell: - -@example -@group -(setq x1 '(a b c)) - @result{} (a b c) -(setcdr x1 (cdr (cdr x1))) - @result{} (c) -x1 - @result{} (a c) -@end group -@end example - - Here is the result in box notation: - -@smallexample -@group - -------------------- - | | - -------------- | -------------- | -------------- -| car | cdr | | | car | cdr | -->| car | cdr | -| a | o----- | b | o-------->| c | nil | -| | | | | | | | | - -------------- -------------- -------------- -@end group -@end smallexample - -@noindent -The second cons cell, which previously held the element @code{b}, still -exists and its @sc{car} is still @code{b}, but it no longer forms part -of this list. - - It is equally easy to insert a new element by changing @sc{cdr}s: - -@example -@group -(setq x1 '(a b c)) - @result{} (a b c) -(setcdr x1 (cons 'd (cdr x1))) - @result{} (d b c) -x1 - @result{} (a d b c) -@end group -@end example - - Here is this result in box notation: - -@smallexample -@group - -------------- ------------- ------------- -| car | cdr | | car | cdr | | car | cdr | -| a | o | -->| b | o------->| c | nil | -| | | | | | | | | | | - --------- | -- | ------------- ------------- - | | - ----- -------- - | | - | --------------- | - | | car | cdr | | - -->| d | o------ - | | | - --------------- -@end group -@end smallexample - -@node Rearrangement -@subsection Functions that Rearrange Lists -@cindex rearrangement of lists -@cindex modification of lists - - Here are some functions that rearrange lists ``destructively'' by -modifying the @sc{cdr}s of their component cons cells. We call these -functions ``destructive'' because they chew up the original lists passed -to them as arguments, relinking their cons cells to form a new list that -is the returned value. - -@ifnottex - See @code{delq}, in @ref{Sets And Lists}, for another function -that modifies cons cells. -@end ifnottex -@iftex - The function @code{delq} in the following section is another example -of destructive list manipulation. -@end iftex - -@defun nconc &rest lists -@cindex concatenating lists -@cindex joining lists -This function returns a list containing all the elements of @var{lists}. -Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are -@emph{not} copied. Instead, the last @sc{cdr} of each of the -@var{lists} is changed to refer to the following list. The last of the -@var{lists} is not altered. For example: - -@example -@group -(setq x '(1 2 3)) - @result{} (1 2 3) -@end group -@group -(nconc x '(4 5)) - @result{} (1 2 3 4 5) -@end group -@group -x - @result{} (1 2 3 4 5) -@end group -@end example - - Since the last argument of @code{nconc} is not itself modified, it is -reasonable to use a constant list, such as @code{'(4 5)}, as in the -above example. For the same reason, the last argument need not be a -list: - -@example -@group -(setq x '(1 2 3)) - @result{} (1 2 3) -@end group -@group -(nconc x 'z) - @result{} (1 2 3 . z) -@end group -@group -x - @result{} (1 2 3 . z) -@end group -@end example - -However, the other arguments (all but the last) must be lists. - -A common pitfall is to use a quoted constant list as a non-last -argument to @code{nconc}. If you do this, your program will change -each time you run it! Here is what happens: - -@smallexample -@group -(defun add-foo (x) ; @r{We want this function to add} - (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.} -@end group - -@group -(symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo)) x)) -@end group - -@group -(setq xx (add-foo '(1 2))) ; @r{It seems to work.} - @result{} (foo 1 2) -@end group -@group -(setq xy (add-foo '(3 4))) ; @r{What happened?} - @result{} (foo 1 2 3 4) -@end group -@group -(eq xx xy) - @result{} t -@end group - -@group -(symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x))) -@end group -@end smallexample -@end defun - -@defun nreverse list -@cindex reversing a list - This function reverses the order of the elements of @var{list}. -Unlike @code{reverse}, @code{nreverse} alters its argument by reversing -the @sc{cdr}s in the cons cells forming the list. The cons cell that -used to be the last one in @var{list} becomes the first cons cell of the -value. - - For example: - -@example -@group -(setq x '(a b c)) - @result{} (a b c) -@end group -@group -x - @result{} (a b c) -(nreverse x) - @result{} (c b a) -@end group -@group -;; @r{The cons cell that was first is now last.} -x - @result{} (a) -@end group -@end example - - To avoid confusion, we usually store the result of @code{nreverse} -back in the same variable which held the original list: - -@example -(setq x (nreverse x)) -@end example - - Here is the @code{nreverse} of our favorite example, @code{(a b c)}, -presented graphically: - -@smallexample -@group -@r{Original list head:} @r{Reversed list:} - ------------- ------------- ------------ -| car | cdr | | car | cdr | | car | cdr | -| a | nil |<-- | b | o |<-- | c | o | -| | | | | | | | | | | | | - ------------- | --------- | - | -------- | - - | | | | - ------------- ------------ -@end group -@end smallexample -@end defun - -@defun sort list predicate -@cindex stable sort -@cindex sorting lists -This function sorts @var{list} stably, though destructively, and -returns the sorted list. It compares elements using @var{predicate}. A -stable sort is one in which elements with equal sort keys maintain their -relative order before and after the sort. Stability is important when -successive sorts are used to order elements according to different -criteria. - -The argument @var{predicate} must be a function that accepts two -arguments. It is called with two elements of @var{list}. To get an -increasing order sort, the @var{predicate} should return non-@code{nil} if the -first element is ``less than'' the second, or @code{nil} if not. - -The comparison function @var{predicate} must give reliable results for -any given pair of arguments, at least within a single call to -@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is -less than @var{b}, @var{b} must not be less than @var{a}. It must be -@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b} -is less than @var{c}, then @var{a} must be less than @var{c}. If you -use a comparison function which does not meet these requirements, the -result of @code{sort} is unpredictable. - -The destructive aspect of @code{sort} is that it rearranges the cons -cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort -function would create new cons cells to store the elements in their -sorted order. If you wish to make a sorted copy without destroying the -original, copy it first with @code{copy-sequence} and then sort. - -Sorting does not change the @sc{car}s of the cons cells in @var{list}; -the cons cell that originally contained the element @code{a} in -@var{list} still has @code{a} in its @sc{car} after sorting, but it now -appears in a different position in the list due to the change of -@sc{cdr}s. For example: - -@example -@group -(setq nums '(1 3 2 6 5 4 0)) - @result{} (1 3 2 6 5 4 0) -@end group -@group -(sort nums '<) - @result{} (0 1 2 3 4 5 6) -@end group -@group -nums - @result{} (1 2 3 4 5 6) -@end group -@end example - -@noindent -@strong{Warning}: Note that the list in @code{nums} no longer contains -0; this is the same cons cell that it was before, but it is no longer -the first one in the list. Don't assume a variable that formerly held -the argument now holds the entire sorted list! Instead, save the result -of @code{sort} and use that. Most often we store the result back into -the variable that held the original list: - -@example -(setq nums (sort nums '<)) -@end example - -@xref{Sorting}, for more functions that perform sorting. -See @code{documentation} in @ref{Accessing Documentation}, for a -useful example of @code{sort}. -@end defun - -@node Sets And Lists -@section Using Lists as Sets -@cindex lists as sets -@cindex sets - - A list can represent an unordered mathematical set---simply consider a -value an element of a set if it appears in the list, and ignore the -order of the list. To form the union of two sets, use @code{append} (as -long as you don't mind having duplicate elements). You can remove -@code{equal} duplicates using @code{delete-dups}. Other useful -functions for sets include @code{memq} and @code{delq}, and their -@code{equal} versions, @code{member} and @code{delete}. - -@cindex CL note---lack @code{union}, @code{intersection} -@quotation -@b{Common Lisp note:} Common Lisp has functions @code{union} (which -avoids duplicate elements) and @code{intersection} for set operations. -Although standard GNU Emacs Lisp does not have them, the @file{cl} -library provides versions. @xref{Top,, Overview, cl, Common Lisp Extensions}. -@end quotation - -@defun memq object list -@cindex membership in a list -This function tests to see whether @var{object} is a member of -@var{list}. If it is, @code{memq} returns a list starting with the -first occurrence of @var{object}. Otherwise, it returns @code{nil}. -The letter @samp{q} in @code{memq} says that it uses @code{eq} to -compare @var{object} against the elements of the list. For example: - -@example -@group -(memq 'b '(a b c b a)) - @result{} (b c b a) -@end group -@group -(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} - @result{} nil -@end group -@end example -@end defun - -@defun delq object list -@cindex deleting list elements -This function destructively removes all elements @code{eq} to -@var{object} from @var{list}. The letter @samp{q} in @code{delq} says -that it uses @code{eq} to compare @var{object} against the elements of -the list, like @code{memq} and @code{remq}. -@end defun - -When @code{delq} deletes elements from the front of the list, it does so -simply by advancing down the list and returning a sublist that starts -after those elements: - -@example -@group -(delq 'a '(a b c)) @equiv{} (cdr '(a b c)) -@end group -@end example - -When an element to be deleted appears in the middle of the list, -removing it involves changing the @sc{cdr}s (@pxref{Setcdr}). - -@example -@group -(setq sample-list '(a b c (4))) - @result{} (a b c (4)) -@end group -@group -(delq 'a sample-list) - @result{} (b c (4)) -@end group -@group -sample-list - @result{} (a b c (4)) -@end group -@group -(delq 'c sample-list) - @result{} (a b (4)) -@end group -@group -sample-list - @result{} (a b (4)) -@end group -@end example - -Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to -splice out the third element, but @code{(delq 'a sample-list)} does not -splice anything---it just returns a shorter list. Don't assume that a -variable which formerly held the argument @var{list} now has fewer -elements, or that it still holds the original list! Instead, save the -result of @code{delq} and use that. Most often we store the result back -into the variable that held the original list: - -@example -(setq flowers (delq 'rose flowers)) -@end example - -In the following example, the @code{(4)} that @code{delq} attempts to match -and the @code{(4)} in the @code{sample-list} are not @code{eq}: - -@example -@group -(delq '(4) sample-list) - @result{} (a c (4)) -@end group -@end example - -If you want to delete elements that are @code{equal} to a given value, -use @code{delete} (see below). - -@defun remq object list -This function returns a copy of @var{list}, with all elements removed -which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq} -says that it uses @code{eq} to compare @var{object} against the elements -of @code{list}. - -@example -@group -(setq sample-list '(a b c a b c)) - @result{} (a b c a b c) -@end group -@group -(remq 'a sample-list) - @result{} (b c b c) -@end group -@group -sample-list - @result{} (a b c a b c) -@end group -@end example -@end defun - -@defun memql object list -The function @code{memql} tests to see whether @var{object} is a member -of @var{list}, comparing members with @var{object} using @code{eql}, -so floating point elements are compared by value. -If @var{object} is a member, @code{memql} returns a list starting with -its first occurrence in @var{list}. Otherwise, it returns @code{nil}. - -Compare this with @code{memq}: - -@example -@group -(memql 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are @code{eql}.} - @result{} (1.2 1.3) -@end group -@group -(memq 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are not @code{eq}.} - @result{} nil -@end group -@end example -@end defun - -The following three functions are like @code{memq}, @code{delq} and -@code{remq}, but use @code{equal} rather than @code{eq} to compare -elements. @xref{Equality Predicates}. - -@defun member object list -The function @code{member} tests to see whether @var{object} is a member -of @var{list}, comparing members with @var{object} using @code{equal}. -If @var{object} is a member, @code{member} returns a list starting with -its first occurrence in @var{list}. Otherwise, it returns @code{nil}. - -Compare this with @code{memq}: - -@example -@group -(member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.} - @result{} ((2)) -@end group -@group -(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} - @result{} nil -@end group -@group -;; @r{Two strings with the same contents are @code{equal}.} -(member "foo" '("foo" "bar")) - @result{} ("foo" "bar") -@end group -@end example -@end defun - -@defun delete object sequence -If @code{sequence} is a list, this function destructively removes all -elements @code{equal} to @var{object} from @var{sequence}. For lists, -@code{delete} is to @code{delq} as @code{member} is to @code{memq}: it -uses @code{equal} to compare elements with @var{object}, like -@code{member}; when it finds an element that matches, it cuts the -element out just as @code{delq} would. - -If @code{sequence} is a vector or string, @code{delete} returns a copy -of @code{sequence} with all elements @code{equal} to @code{object} -removed. - -For example: - -@example -@group -(setq l '((2) (1) (2))) -(delete '(2) l) - @result{} ((1)) -l - @result{} ((2) (1)) -;; @r{If you want to change @code{l} reliably,} -;; @r{write @code{(setq l (delete '(2) l))}.} -@end group -@group -(setq l '((2) (1) (2))) -(delete '(1) l) - @result{} ((2) (2)) -l - @result{} ((2) (2)) -;; @r{In this case, it makes no difference whether you set @code{l},} -;; @r{but you should do so for the sake of the other case.} -@end group -@group -(delete '(2) [(2) (1) (2)]) - @result{} [(1)] -@end group -@end example -@end defun - -@defun remove object sequence -This function is the non-destructive counterpart of @code{delete}. It -returns a copy of @code{sequence}, a list, vector, or string, with -elements @code{equal} to @code{object} removed. For example: - -@example -@group -(remove '(2) '((2) (1) (2))) - @result{} ((1)) -@end group -@group -(remove '(2) [(2) (1) (2)]) - @result{} [(1)] -@end group -@end example -@end defun - -@quotation -@b{Common Lisp note:} The functions @code{member}, @code{delete} and -@code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common -Lisp. The Common Lisp versions do not use @code{equal} to compare -elements. -@end quotation - -@defun member-ignore-case object list -This function is like @code{member}, except that @var{object} should -be a string and that it ignores differences in letter-case and text -representation: upper-case and lower-case letters are treated as -equal, and unibyte strings are converted to multibyte prior to -comparison. -@end defun - -@defun delete-dups list -This function destructively removes all @code{equal} duplicates from -@var{list}, stores the result in @var{list} and returns it. Of -several @code{equal} occurrences of an element in @var{list}, -@code{delete-dups} keeps the first one. -@end defun - - See also the function @code{add-to-list}, in @ref{List Variables}, -for a way to add an element to a list stored in a variable and used as a -set. - -@node Association Lists -@section Association Lists -@cindex association list -@cindex alist - - An @dfn{association list}, or @dfn{alist} for short, records a mapping -from keys to values. It is a list of cons cells called -@dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the -@sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key'' -is not related to the term ``key sequence''; it means a value used to -look up an item in a table. In this case, the table is the alist, and -the alist associations are the items.} - - Here is an example of an alist. The key @code{pine} is associated with -the value @code{cones}; the key @code{oak} is associated with -@code{acorns}; and the key @code{maple} is associated with @code{seeds}. - -@example -@group -((pine . cones) - (oak . acorns) - (maple . seeds)) -@end group -@end example - - Both the values and the keys in an alist may be any Lisp objects. -For example, in the following alist, the symbol @code{a} is -associated with the number @code{1}, and the string @code{"b"} is -associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of -the alist element: - -@example -((a . 1) ("b" 2 3)) -@end example - - Sometimes it is better to design an alist to store the associated -value in the @sc{car} of the @sc{cdr} of the element. Here is an -example of such an alist: - -@example -((rose red) (lily white) (buttercup yellow)) -@end example - -@noindent -Here we regard @code{red} as the value associated with @code{rose}. One -advantage of this kind of alist is that you can store other related -information---even a list of other items---in the @sc{cdr} of the -@sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see -below) to find the element containing a given value. When neither of -these considerations is important, the choice is a matter of taste, as -long as you are consistent about it for any given alist. - - The same alist shown above could be regarded as having the -associated value in the @sc{cdr} of the element; the value associated -with @code{rose} would be the list @code{(red)}. - - Association lists are often used to record information that you might -otherwise keep on a stack, since new associations may be added easily to -the front of the list. When searching an association list for an -association with a given key, the first one found is returned, if there -is more than one. - - In Emacs Lisp, it is @emph{not} an error if an element of an -association list is not a cons cell. The alist search functions simply -ignore such elements. Many other versions of Lisp signal errors in such -cases. - - Note that property lists are similar to association lists in several -respects. A property list behaves like an association list in which -each key can occur only once. @xref{Property Lists}, for a comparison -of property lists and association lists. - -@defun assoc key alist -This function returns the first association for @var{key} in -@var{alist}, comparing @var{key} against the alist elements using -@code{equal} (@pxref{Equality Predicates}). It returns @code{nil} if no -association in @var{alist} has a @sc{car} @code{equal} to @var{key}. -For example: - -@smallexample -(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) - @result{} ((pine . cones) (oak . acorns) (maple . seeds)) -(assoc 'oak trees) - @result{} (oak . acorns) -(cdr (assoc 'oak trees)) - @result{} acorns -(assoc 'birch trees) - @result{} nil -@end smallexample - -Here is another example, in which the keys and values are not symbols: - -@smallexample -(setq needles-per-cluster - '((2 "Austrian Pine" "Red Pine") - (3 "Pitch Pine") - (5 "White Pine"))) - -(cdr (assoc 3 needles-per-cluster)) - @result{} ("Pitch Pine") -(cdr (assoc 2 needles-per-cluster)) - @result{} ("Austrian Pine" "Red Pine") -@end smallexample -@end defun - - The function @code{assoc-string} is much like @code{assoc} except -that it ignores certain differences between strings. @xref{Text -Comparison}. - -@defun rassoc value alist -This function returns the first association with value @var{value} in -@var{alist}. It returns @code{nil} if no association in @var{alist} has -a @sc{cdr} @code{equal} to @var{value}. - -@code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of -each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assoc}'', finding the key for a given value. -@end defun - -@defun assq key alist -This function is like @code{assoc} in that it returns the first -association for @var{key} in @var{alist}, but it makes the comparison -using @code{eq} instead of @code{equal}. @code{assq} returns @code{nil} -if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}. -This function is used more often than @code{assoc}, since @code{eq} is -faster than @code{equal} and most alists use symbols as keys. -@xref{Equality Predicates}. - -@smallexample -(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) - @result{} ((pine . cones) (oak . acorns) (maple . seeds)) -(assq 'pine trees) - @result{} (pine . cones) -@end smallexample - -On the other hand, @code{assq} is not usually useful in alists where the -keys may not be symbols: - -@smallexample -(setq leaves - '(("simple leaves" . oak) - ("compound leaves" . horsechestnut))) - -(assq "simple leaves" leaves) - @result{} nil -(assoc "simple leaves" leaves) - @result{} ("simple leaves" . oak) -@end smallexample -@end defun - -@defun rassq value alist -This function returns the first association with value @var{value} in -@var{alist}. It returns @code{nil} if no association in @var{alist} has -a @sc{cdr} @code{eq} to @var{value}. - -@code{rassq} is like @code{assq} except that it compares the @sc{cdr} of -each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assq}'', finding the key for a given value. - -For example: - -@smallexample -(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) - -(rassq 'acorns trees) - @result{} (oak . acorns) -(rassq 'spores trees) - @result{} nil -@end smallexample - -@code{rassq} cannot search for a value stored in the @sc{car} -of the @sc{cdr} of an element: - -@smallexample -(setq colors '((rose red) (lily white) (buttercup yellow))) - -(rassq 'white colors) - @result{} nil -@end smallexample - -In this case, the @sc{cdr} of the association @code{(lily white)} is not -the symbol @code{white}, but rather the list @code{(white)}. This -becomes clearer if the association is written in dotted pair notation: - -@smallexample -(lily white) @equiv{} (lily . (white)) -@end smallexample -@end defun - -@defun assoc-default key alist &optional test default -This function searches @var{alist} for a match for @var{key}. For each -element of @var{alist}, it compares the element (if it is an atom) or -the element's @sc{car} (if it is a cons) against @var{key}, by calling -@var{test} with two arguments: the element or its @sc{car}, and -@var{key}. The arguments are passed in that order so that you can get -useful results using @code{string-match} with an alist that contains -regular expressions (@pxref{Regexp Search}). If @var{test} is omitted -or @code{nil}, @code{equal} is used for comparison. - -If an alist element matches @var{key} by this criterion, -then @code{assoc-default} returns a value based on this element. -If the element is a cons, then the value is the element's @sc{cdr}. -Otherwise, the return value is @var{default}. - -If no alist element matches @var{key}, @code{assoc-default} returns -@code{nil}. -@end defun - -@defun copy-alist alist -@cindex copying alists -This function returns a two-level deep copy of @var{alist}: it creates a -new copy of each association, so that you can alter the associations of -the new alist without changing the old one. - -@smallexample -@group -(setq needles-per-cluster - '((2 . ("Austrian Pine" "Red Pine")) - (3 . ("Pitch Pine")) -@end group - (5 . ("White Pine")))) -@result{} -((2 "Austrian Pine" "Red Pine") - (3 "Pitch Pine") - (5 "White Pine")) - -(setq copy (copy-alist needles-per-cluster)) -@result{} -((2 "Austrian Pine" "Red Pine") - (3 "Pitch Pine") - (5 "White Pine")) - -(eq needles-per-cluster copy) - @result{} nil -(equal needles-per-cluster copy) - @result{} t -(eq (car needles-per-cluster) (car copy)) - @result{} nil -(cdr (car (cdr needles-per-cluster))) - @result{} ("Pitch Pine") -@group -(eq (cdr (car (cdr needles-per-cluster))) - (cdr (car (cdr copy)))) - @result{} t -@end group -@end smallexample - - This example shows how @code{copy-alist} makes it possible to change -the associations of one copy without affecting the other: - -@smallexample -@group -(setcdr (assq 3 copy) '("Martian Vacuum Pine")) -(cdr (assq 3 needles-per-cluster)) - @result{} ("Pitch Pine") -@end group -@end smallexample -@end defun - -@defun assq-delete-all key alist -This function deletes from @var{alist} all the elements whose @sc{car} -is @code{eq} to @var{key}, much as if you used @code{delq} to delete -each such element one by one. It returns the shortened alist, and -often modifies the original list structure of @var{alist}. For -correct results, use the return value of @code{assq-delete-all} rather -than looking at the saved value of @var{alist}. - -@example -(setq alist '((foo 1) (bar 2) (foo 3) (lose 4))) - @result{} ((foo 1) (bar 2) (foo 3) (lose 4)) -(assq-delete-all 'foo alist) - @result{} ((bar 2) (lose 4)) -alist - @result{} ((foo 1) (bar 2) (lose 4)) -@end example -@end defun - -@defun rassq-delete-all value alist -This function deletes from @var{alist} all the elements whose @sc{cdr} -is @code{eq} to @var{value}. It returns the shortened alist, and -often modifies the original list structure of @var{alist}. -@code{rassq-delete-all} is like @code{assq-delete-all} except that it -compares the @sc{cdr} of each @var{alist} association instead of the -@sc{car}. -@end defun diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi deleted file mode 100644 index 93cc7a4598c..00000000000 --- a/doc/lispref/loading.texi +++ /dev/null @@ -1,1003 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/loading -@node Loading, Byte Compilation, Customization, Top -@chapter Loading -@cindex loading -@cindex library -@cindex Lisp library - - Loading a file of Lisp code means bringing its contents into the -Lisp environment in the form of Lisp objects. Emacs finds and opens -the file, reads the text, evaluates each form, and then closes the -file. Such a file is also called a @dfn{Lisp library}. - - The load functions evaluate all the expressions in a file just -as the @code{eval-buffer} function evaluates all the -expressions in a buffer. The difference is that the load functions -read and evaluate the text in the file as found on disk, not the text -in an Emacs buffer. - -@cindex top-level form - The loaded file must contain Lisp expressions, either as source code -or as byte-compiled code. Each form in the file is called a -@dfn{top-level form}. There is no special format for the forms in a -loadable file; any form in a file may equally well be typed directly -into a buffer and evaluated there. (Indeed, most code is tested this -way.) Most often, the forms are function definitions and variable -definitions. - -@menu -* How Programs Do Loading:: The @code{load} function and others. -* Load Suffixes:: Details about the suffixes that @code{load} tries. -* Library Search:: Finding a library to load. -* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. -* Autoload:: Setting up a function to autoload. -* Repeated Loading:: Precautions about loading a file twice. -* Named Features:: Loading a library if it isn't already loaded. -* Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. -* Hooks for Loading:: Providing code to be run when - particular libraries are loaded. -@end menu - -@node How Programs Do Loading -@section How Programs Do Loading - - Emacs Lisp has several interfaces for loading. For example, -@code{autoload} creates a placeholder object for a function defined in a -file; trying to call the autoloading function loads the file to get the -function's real definition (@pxref{Autoload}). @code{require} loads a -file if it isn't already loaded (@pxref{Named Features}). Ultimately, -all these facilities call the @code{load} function to do the work. - -@defun load filename &optional missing-ok nomessage nosuffix must-suffix -This function finds and opens a file of Lisp code, evaluates all the -forms in it, and closes the file. - -To find the file, @code{load} first looks for a file named -@file{@var{filename}.elc}, that is, for a file whose name is -@var{filename} with the extension @samp{.elc} appended. If such a -file exists, it is loaded. If there is no file by that name, then -@code{load} looks for a file named @file{@var{filename}.el}. If that -file exists, it is loaded. Finally, if neither of those names is -found, @code{load} looks for a file named @var{filename} with nothing -appended, and loads it if it exists. (The @code{load} function is not -clever about looking at @var{filename}. In the perverse case of a -file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will -indeed find it.) - -If Auto Compression mode is enabled, as it is by default, then if -@code{load} can not find a file, it searches for a compressed version -of the file before trying other file names. It decompresses and loads -it if it exists. It looks for compressed versions by appending each -of the suffixes in @code{jka-compr-load-suffixes} to the file name. -The value of this variable must be a list of strings. Its standard -value is @code{(".gz")}. - -If the optional argument @var{nosuffix} is non-@code{nil}, then -@code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In -this case, you must specify the precise file name you want, except -that, if Auto Compression mode is enabled, @code{load} will still use -@code{jka-compr-load-suffixes} to find compressed versions. By -specifying the precise file name and using @code{t} for -@var{nosuffix}, you can prevent file names like @file{foo.el.el} from -being tried. - -If the optional argument @var{must-suffix} is non-@code{nil}, then -@code{load} insists that the file name used must end in either -@samp{.el} or @samp{.elc} (possibly extended with a compression -suffix), unless it contains an explicit directory name. - -If @var{filename} is a relative file name, such as @file{foo} or -@file{baz/foo.bar}, @code{load} searches for the file using the variable -@code{load-path}. It appends @var{filename} to each of the directories -listed in @code{load-path}, and loads the first file it finds whose name -matches. The current default directory is tried only if it is specified -in @code{load-path}, where @code{nil} stands for the default directory. -@code{load} tries all three possible suffixes in the first directory in -@code{load-path}, then all three suffixes in the second directory, and -so on. @xref{Library Search}. - -Whatever the name under which the file is eventually found, and the -directory where Emacs found it, Emacs sets the value of the variable -@code{load-file-name} to that file's name. - -If you get a warning that @file{foo.elc} is older than @file{foo.el}, it -means you should consider recompiling @file{foo.el}. @xref{Byte -Compilation}. - -When loading a source file (not compiled), @code{load} performs -character set translation just as Emacs would do when visiting the file. -@xref{Coding Systems}. - -Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear -in the echo area during loading unless @var{nomessage} is -non-@code{nil}. - -@cindex load errors -Any unhandled errors while loading a file terminate loading. If the -load was done for the sake of @code{autoload}, any function definitions -made during the loading are undone. - -@kindex file-error -If @code{load} can't find the file to load, then normally it signals the -error @code{file-error} (with @samp{Cannot open load file -@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then -@code{load} just returns @code{nil}. - -You can use the variable @code{load-read-function} to specify a function -for @code{load} to use instead of @code{read} for reading expressions. -See below. - -@code{load} returns @code{t} if the file loads successfully. -@end defun - -@deffn Command load-file filename -This command loads the file @var{filename}. If @var{filename} is a -relative file name, then the current default directory is assumed. -This command does not use @code{load-path}, and does not append -suffixes. However, it does look for compressed versions (if Auto -Compression Mode is enabled). Use this command if you wish to specify -precisely the file name to load. -@end deffn - -@deffn Command load-library library -This command loads the library named @var{library}. It is equivalent to -@code{load}, except for the way it reads its argument interactively. -@xref{Lisp Libraries,,,emacs, The GNU Emacs Manual}. -@end deffn - -@defvar load-in-progress -This variable is non-@code{nil} if Emacs is in the process of loading a -file, and it is @code{nil} otherwise. -@end defvar - -@defvar load-file-name -When Emacs is in the process of loading a file, this variable's value -is the name of that file, as Emacs found it during the search -described earlier in this section. -@end defvar - -@defvar load-read-function -@anchor{Definition of load-read-function} -@c do not allow page break at anchor; work around Texinfo deficiency. -This variable specifies an alternate expression-reading function for -@code{load} and @code{eval-region} to use instead of @code{read}. -The function should accept one argument, just as @code{read} does. - -Normally, the variable's value is @code{nil}, which means those -functions should use @code{read}. - -Instead of using this variable, it is cleaner to use another, newer -feature: to pass the function as the @var{read-function} argument to -@code{eval-region}. @xref{Definition of eval-region,, Eval}. -@end defvar - - For information about how @code{load} is used in building Emacs, see -@ref{Building Emacs}. - -@node Load Suffixes -@section Load Suffixes -We now describe some technical details about the exact suffixes that -@code{load} tries. - -@defvar load-suffixes -This is a list of suffixes indicating (compiled or source) Emacs Lisp -files. It should not include the empty string. @code{load} uses -these suffixes in order when it appends Lisp suffixes to the specified -file name. The standard value is @code{(".elc" ".el")} which produces -the behavior described in the previous section. -@end defvar - -@defvar load-file-rep-suffixes -This is a list of suffixes that indicate representations of the same -file. This list should normally start with the empty string. -When @code{load} searches for a file it appends the suffixes in this -list, in order, to the file name, before searching for another file. - -Enabling Auto Compression mode appends the suffixes in -@code{jka-compr-load-suffixes} to this list and disabling Auto -Compression mode removes them again. The standard value of -@code{load-file-rep-suffixes} if Auto Compression mode is disabled is -@code{("")}. Given that the standard value of -@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value -of @code{load-file-rep-suffixes} if Auto Compression mode is enabled -is @code{("" ".gz")}. -@end defvar - -@defun get-load-suffixes -This function returns the list of all suffixes that @code{load} should -try, in order, when its @var{must-suffix} argument is non-@code{nil}. -This takes both @code{load-suffixes} and @code{load-file-rep-suffixes} -into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes} -and @code{load-file-rep-suffixes} all have their standard values, this -function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto -Compression mode is enabled and @code{(".elc" ".el")} if Auto -Compression mode is disabled. -@end defun - -To summarize, @code{load} normally first tries the suffixes in the -value of @code{(get-load-suffixes)} and then those in -@code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil}, -it skips the former group, and if @var{must-suffix} is non-@code{nil}, -it skips the latter group. - -@node Library Search -@section Library Search -@cindex library search -@cindex find library - - When Emacs loads a Lisp library, it searches for the library -in a list of directories specified by the variable @code{load-path}. - -@defvar load-path -@cindex @env{EMACSLOADPATH} environment variable -The value of this variable is a list of directories to search when -loading files with @code{load}. Each element is a string (which must be -a directory name) or @code{nil} (which stands for the current working -directory). -@end defvar - - Each time Emacs starts up, it sets up the value of @code{load-path} -in several steps. First, it initializes @code{load-path} to the -directories specified by the environment variable @env{EMACSLOADPATH}, -if that exists. The syntax of @env{EMACSLOADPATH} is the same as used -for @code{PATH}; directory names are separated by @samp{:} (or -@samp{;}, on some operating systems), and @samp{.} stands for the -current default directory. Here is an example of how to set -@env{EMACSLOADPATH} variable from @command{sh}: - -@example -export EMACSLOADPATH -EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp -@end example - -@noindent -Here is how to set it from @code{csh}: - -@example -setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp -@end example - - If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs -initializes @code{load-path} with the following two directories: - -@example -"/usr/local/share/emacs/@var{version}/site-lisp" -@end example - -@noindent -and - -@example -"/usr/local/share/emacs/site-lisp" -@end example - -@noindent -The first one is for locally installed packages for a particular Emacs -version; the second is for locally installed packages meant for use -with all installed Emacs versions. - - If you run Emacs from the directory where it was built---that is, an -executable that has not been formally installed---Emacs puts two more -directories in @code{load-path}. These are the @code{lisp} and -@code{site-lisp} subdirectories of the main build directory. (Both -are represented as absolute file names.) - - Next, Emacs ``expands'' the initial list of directories in -@code{load-path} by adding the subdirectories of those directories. -Both immediate subdirectories and subdirectories multiple levels down -are added. But it excludes subdirectories whose names do not start -with a letter or digit, and subdirectories named @file{RCS} or -@file{CVS}, and subdirectories containing a file named -@file{.nosearch}. - - Next, Emacs adds any extra load directory that you specify using the -@samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The -GNU Emacs Manual}). It also adds the directories where optional -packages are installed, if any (@pxref{Packaging Basics}). - - It is common to add code to one's init file (@pxref{Init File}) to -add one or more directories to @code{load-path}. For example: - -@example -(push "~/.emacs.d/lisp" load-path) -@end example - - Dumping Emacs uses a special value of @code{load-path}. If the -value of @code{load-path} at the end of dumping is unchanged (that is, -still the same special value), the dumped Emacs switches to the -ordinary @code{load-path} value when it starts up, as described above. -But if @code{load-path} has any other value at the end of dumping, -that value is used for execution of the dumped Emacs also. - -@deffn Command locate-library library &optional nosuffix path interactive-call -This command finds the precise file name for library @var{library}. It -searches for the library in the same way @code{load} does, and the -argument @var{nosuffix} has the same meaning as in @code{load}: don't -add suffixes @samp{.elc} or @samp{.el} to the specified name -@var{library}. - -If the @var{path} is non-@code{nil}, that list of directories is used -instead of @code{load-path}. - -When @code{locate-library} is called from a program, it returns the file -name as a string. When the user runs @code{locate-library} -interactively, the argument @var{interactive-call} is @code{t}, and this -tells @code{locate-library} to display the file name in the echo area. -@end deffn - -@cindex shadowed Lisp files -@deffn Command list-load-path-shadows &optional stringp -This command shows a list of @dfn{shadowed} Emacs Lisp files. A -shadowed file is one that will not normally be loaded, despite being -in a directory on @code{load-path}, due to the existence of another -similarly-named file in a directory earlier on @code{load-path}. - -For instance, suppose @code{load-path} is set to - -@example - ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp") -@end example - -@noindent -and that both these directories contain a file named @file{foo.el}. -Then @code{(require 'foo)} never loads the file in the second -directory. Such a situation might indicate a problem in the way Emacs -was installed. - -When called from Lisp, this function prints a message listing the -shadowed files, instead of displaying them in a buffer. If the -optional argument @code{stringp} is non-@code{nil}, it instead returns -the shadowed files as a string. -@end deffn - -@node Loading Non-ASCII -@section Loading Non-@acronym{ASCII} Characters - - When Emacs Lisp programs contain string constants with non-@acronym{ASCII} -characters, these can be represented within Emacs either as unibyte -strings or as multibyte strings (@pxref{Text Representations}). Which -representation is used depends on how the file is read into Emacs. If -it is read with decoding into multibyte representation, the text of the -Lisp program will be multibyte text, and its string constants will be -multibyte strings. If a file containing Latin-1 characters (for -example) is read without decoding, the text of the program will be -unibyte text, and its string constants will be unibyte strings. -@xref{Coding Systems}. - - In most Emacs Lisp programs, the fact that non-@acronym{ASCII} -strings are multibyte strings should not be noticeable, since -inserting them in unibyte buffers converts them to unibyte -automatically. However, if this does make a difference, you can force -a particular Lisp file to be interpreted as unibyte by writing -@samp{unibyte: t} in a local variables section. With -that designator, the file will unconditionally be interpreted as -unibyte, even in an ordinary multibyte Emacs session. This can matter -when making keybindings to non-@acronym{ASCII} characters written as -@code{?v@var{literal}}. - -@node Autoload -@section Autoload -@cindex autoload - - The @dfn{autoload} facility allows you to register the existence of -a function or macro, but put off loading the file that defines it. -The first call to the function automatically reads the proper file, in -order to install the real definition and other associated code, then -runs the real definition as if it had been loaded all along. - - There are two ways to set up an autoloaded function: by calling -@code{autoload}, and by writing a special ``magic'' comment in the -source before the real definition. @code{autoload} is the low-level -primitive for autoloading; any Lisp program can call @code{autoload} at -any time. Magic comments are the most convenient way to make a function -autoload, for packages installed along with Emacs. These comments do -nothing on their own, but they serve as a guide for the command -@code{update-file-autoloads}, which constructs calls to @code{autoload} -and arranges to execute them when Emacs is built. - -@defun autoload function filename &optional docstring interactive type -This function defines the function (or macro) named @var{function} so as -to load automatically from @var{filename}. The string @var{filename} -specifies the file to load to get the real definition of @var{function}. - -If @var{filename} does not contain either a directory name, or the -suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding -one of these suffixes, and it will not load from a file whose name is -just @var{filename} with no added suffix. (The variable -@code{load-suffixes} specifies the exact required suffixes.) - -The argument @var{docstring} is the documentation string for the -function. Specifying the documentation string in the call to -@code{autoload} makes it possible to look at the documentation without -loading the function's real definition. Normally, this should be -identical to the documentation string in the function definition -itself. If it isn't, the function definition's documentation string -takes effect when it is loaded. - -If @var{interactive} is non-@code{nil}, that says @var{function} can be -called interactively. This lets completion in @kbd{M-x} work without -loading @var{function}'s real definition. The complete interactive -specification is not given here; it's not needed unless the user -actually calls @var{function}, and when that happens, it's time to load -the real definition. - -You can autoload macros and keymaps as well as ordinary functions. -Specify @var{type} as @code{macro} if @var{function} is really a macro. -Specify @var{type} as @code{keymap} if @var{function} is really a -keymap. Various parts of Emacs need to know this information without -loading the real definition. - -An autoloaded keymap loads automatically during key lookup when a prefix -key's binding is the symbol @var{function}. Autoloading does not occur -for other kinds of access to the keymap. In particular, it does not -happen when a Lisp program gets the keymap from the value of a variable -and calls @code{define-key}; not even if the variable name is the same -symbol @var{function}. - -@cindex function cell in autoload -If @var{function} already has a non-void function definition that is not -an autoload object, @code{autoload} does nothing and returns @code{nil}. -If the function cell of @var{function} is void, or is already an autoload -object, then it is defined as an autoload object like this: - -@example -(autoload @var{filename} @var{docstring} @var{interactive} @var{type}) -@end example - -For example, - -@example -@group -(symbol-function 'run-prolog) - @result{} (autoload "prolog" 169681 t nil) -@end group -@end example - -@noindent -In this case, @code{"prolog"} is the name of the file to load, 169681 -refers to the documentation string in the -@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}), -@code{t} means the function is interactive, and @code{nil} that it is -not a macro or a keymap. -@end defun - -@cindex autoload errors - The autoloaded file usually contains other definitions and may require -or provide one or more features. If the file is not completely loaded -(due to an error in the evaluation of its contents), any function -definitions or @code{provide} calls that occurred during the load are -undone. This is to ensure that the next attempt to call any function -autoloading from this file will try again to load the file. If not for -this, then some of the functions in the file might be defined by the -aborted load, but fail to work properly for the lack of certain -subroutines not loaded successfully because they come later in the file. - - If the autoloaded file fails to define the desired Lisp function or -macro, then an error is signaled with data @code{"Autoloading failed to -define function @var{function-name}"}. - -@findex update-file-autoloads -@findex update-directory-autoloads -@cindex magic autoload comment -@cindex autoload cookie -@anchor{autoload cookie} - A magic autoload comment (often called an @dfn{autoload cookie}) -consists of @samp{;;;###autoload}, on a line by itself, -just before the real definition of the function in its -autoloadable source file. The command @kbd{M-x update-file-autoloads} -writes a corresponding @code{autoload} call into @file{loaddefs.el}. -(The string that serves as the autoload cookie and the name of the -file generated by @code{update-file-autoloads} can be changed from the -above defaults, see below.) -Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}. -@kbd{M-x update-directory-autoloads} is even more powerful; it updates -autoloads for all files in the current directory. - - The same magic comment can copy any kind of form into -@file{loaddefs.el}. The form following the magic comment is copied -verbatim, @emph{except} if it is one of the forms which the autoload -facility handles specially (e.g.@: by conversion into an -@code{autoload} call). The forms which are not copied verbatim are -the following: - -@table @asis -@item Definitions for function or function-like objects: -@code{defun} and @code{defmacro}; also @code{defun*} and -@code{defmacro*} (@pxref{Argument Lists,,,cl,CL Manual}), and -@code{define-overloadable-function} (see the commentary in -@file{mode-local.el}). - -@item Definitions for major or minor modes: -@code{define-minor-mode}, @code{define-globalized-minor-mode}, -@code{define-generic-mode}, @code{easy-mmode-define-minor-mode}, -@code{easy-mmode-define-global-mode}, @code{define-compilation-mode}, -@code{define-derived-mode}, and @code{define-global-minor-mode}. - -@item Other definition types: -@code{defcustom}, @code{defgroup}, @code{defclass} -(@pxref{Top,EIEIO,,eieio,EIEIO}), and @code{define-skeleton} (see the -commentary in @file{skeleton.el}). -@end table - - You can also use a magic comment to execute a form at build time -@emph{without} executing it when the file itself is loaded. To do this, -write the form @emph{on the same line} as the magic comment. Since it -is in a comment, it does nothing when you load the source file; but -@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where -it is executed while building Emacs. - - The following example shows how @code{doctor} is prepared for -autoloading with a magic comment: - -@example -;;;###autoload -(defun doctor () - "Switch to *doctor* buffer and start giving psychotherapy." - (interactive) - (switch-to-buffer "*doctor*") - (doctor-mode)) -@end example - -@noindent -Here's what that produces in @file{loaddefs.el}: - -@example -(autoload (quote doctor) "doctor" "\ -Switch to *doctor* buffer and start giving psychotherapy. - -\(fn)" t nil) -@end example - -@noindent -@cindex @code{fn} in function's documentation string -The backslash and newline immediately following the double-quote are a -convention used only in the preloaded uncompiled Lisp files such as -@file{loaddefs.el}; they tell @code{make-docfile} to put the -documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. -See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)} -in the usage part of the documentation string is replaced with the -function's name when the various help functions (@pxref{Help -Functions}) display it. - - If you write a function definition with an unusual macro that is not -one of the known and recognized function definition methods, use of an -ordinary magic autoload comment would copy the whole definition into -@code{loaddefs.el}. That is not desirable. You can put the desired -@code{autoload} call into @code{loaddefs.el} instead by writing this: - -@example -;;;###autoload (autoload 'foo "myfile") -(mydefunmacro foo - ...) -@end example - - You can use a non-default string as the autoload cookie and have the -corresponding autoload calls written into a file whose name is -different from the default @file{loaddefs.el}. Emacs provides two -variables to control this: - -@defvar generate-autoload-cookie -The value of this variable should be a string whose syntax is a Lisp -comment. @kbd{M-x update-file-autoloads} copies the Lisp form that -follows the cookie into the autoload file it generates. The default -value of this variable is @code{";;;###autoload"}. -@end defvar - -@defvar generated-autoload-file -The value of this variable names an Emacs Lisp file where the autoload -calls should go. The default value is @file{loaddefs.el}, but you can -override that, e.g., in the ``Local Variables'' section of a -@file{.el} file (@pxref{File Local Variables}). The autoload file is -assumed to contain a trailer starting with a formfeed character. -@end defvar - -@node Repeated Loading -@section Repeated Loading -@cindex repeated loading - - You can load a given file more than once in an Emacs session. For -example, after you have rewritten and reinstalled a function definition -by editing it in a buffer, you may wish to return to the original -version; you can do this by reloading the file it came from. - - When you load or reload files, bear in mind that the @code{load} and -@code{load-library} functions automatically load a byte-compiled file -rather than a non-compiled file of similar name. If you rewrite a file -that you intend to save and reinstall, you need to byte-compile the new -version; otherwise Emacs will load the older, byte-compiled file instead -of your newer, non-compiled file! If that happens, the message -displayed when loading the file includes, @samp{(compiled; note, source is -newer)}, to remind you to recompile it. - - When writing the forms in a Lisp library file, keep in mind that the -file might be loaded more than once. For example, think about whether -each variable should be reinitialized when you reload the library; -@code{defvar} does not change the value if the variable is already -initialized. (@xref{Defining Variables}.) - - The simplest way to add an element to an alist is like this: - -@example -(push '(leif-mode " Leif") minor-mode-alist) -@end example - -@noindent -But this would add multiple elements if the library is reloaded. To -avoid the problem, use @code{add-to-list} (@pxref{List Variables}): - -@example -(add-to-list 'minor-mode-alist '(leif-mode " Leif")) -@end example - - Occasionally you will want to test explicitly whether a library has -already been loaded. If the library uses @code{provide} to provide a -named feature, you can use @code{featurep} earlier in the file to test -whether the @code{provide} call has been executed before (@pxref{Named -Features}). Alternatively, you could use something like this: - -@example -(defvar foo-was-loaded nil) - -(unless foo-was-loaded - @var{execute-first-time-only} - (setq foo-was-loaded t)) -@end example - -@noindent - -@node Named Features -@section Features -@cindex features -@cindex requiring features -@cindex providing features - - @code{provide} and @code{require} are an alternative to -@code{autoload} for loading files automatically. They work in terms of -named @dfn{features}. Autoloading is triggered by calling a specific -function, but a feature is loaded the first time another program asks -for it by name. - - A feature name is a symbol that stands for a collection of functions, -variables, etc. The file that defines them should @dfn{provide} the -feature. Another program that uses them may ensure they are defined by -@dfn{requiring} the feature. This loads the file of definitions if it -hasn't been loaded already. - -@cindex load error with require - To require the presence of a feature, call @code{require} with the -feature name as argument. @code{require} looks in the global variable -@code{features} to see whether the desired feature has been provided -already. If not, it loads the feature from the appropriate file. This -file should call @code{provide} at the top level to add the feature to -@code{features}; if it fails to do so, @code{require} signals an error. - - For example, in @file{idlwave.el}, the definition for -@code{idlwave-complete-filename} includes the following code: - -@example -(defun idlwave-complete-filename () - "Use the comint stuff to complete a file name." - (require 'comint) - (let* ((comint-file-name-chars "~/A-Za-z0-9+@:_.$#%=@{@}\\-") - (comint-completion-addsuffix nil) - ...) - (comint-dynamic-complete-filename))) -@end example - -@noindent -The expression @code{(require 'comint)} loads the file @file{comint.el} -if it has not yet been loaded, ensuring that -@code{comint-dynamic-complete-filename} is defined. Features are -normally named after the files that provide them, so that -@code{require} need not be given the file name. (Note that it is -important that the @code{require} statement be outside the body of the -@code{let}. Loading a library while its variables are let-bound can -have unintended consequences, namely the variables becoming unbound -after the let exits.) - -The @file{comint.el} file contains the following top-level expression: - -@example -(provide 'comint) -@end example - -@noindent -This adds @code{comint} to the global @code{features} list, so that -@code{(require 'comint)} will henceforth know that nothing needs to be -done. - -@cindex byte-compiling @code{require} - When @code{require} is used at top level in a file, it takes effect -when you byte-compile that file (@pxref{Byte Compilation}) as well as -when you load it. This is in case the required package contains macros -that the byte compiler must know about. It also avoids byte compiler -warnings for functions and variables defined in the file loaded with -@code{require}. - - Although top-level calls to @code{require} are evaluated during -byte compilation, @code{provide} calls are not. Therefore, you can -ensure that a file of definitions is loaded before it is byte-compiled -by including a @code{provide} followed by a @code{require} for the same -feature, as in the following example. - -@example -@group -(provide 'my-feature) ; @r{Ignored by byte compiler,} - ; @r{evaluated by @code{load}.} -(require 'my-feature) ; @r{Evaluated by byte compiler.} -@end group -@end example - -@noindent -The compiler ignores the @code{provide}, then processes the -@code{require} by loading the file in question. Loading the file does -execute the @code{provide} call, so the subsequent @code{require} call -does nothing when the file is loaded. - -@defun provide feature &optional subfeatures -This function announces that @var{feature} is now loaded, or being -loaded, into the current Emacs session. This means that the facilities -associated with @var{feature} are or will be available for other Lisp -programs. - -The direct effect of calling @code{provide} is if not already in -@var{features} then to add @var{feature} to the front of that list and -call any @code{eval-after-load} code waiting for it (@pxref{Hooks for -Loading}). The argument @var{feature} must be a symbol. -@code{provide} returns @var{feature}. - -If provided, @var{subfeatures} should be a list of symbols indicating -a set of specific subfeatures provided by this version of -@var{feature}. You can test the presence of a subfeature using -@code{featurep}. The idea of subfeatures is that you use them when a -package (which is one @var{feature}) is complex enough to make it -useful to give names to various parts or functionalities of the -package, which might or might not be loaded, or might or might not be -present in a given version. @xref{Network Feature Testing}, for -an example. - -@example -features - @result{} (bar bish) - -(provide 'foo) - @result{} foo -features - @result{} (foo bar bish) -@end example - -When a file is loaded to satisfy an autoload, and it stops due to an -error in the evaluation of its contents, any function definitions or -@code{provide} calls that occurred during the load are undone. -@xref{Autoload}. -@end defun - -@defun require feature &optional filename noerror -This function checks whether @var{feature} is present in the current -Emacs session (using @code{(featurep @var{feature})}; see below). The -argument @var{feature} must be a symbol. - -If the feature is not present, then @code{require} loads @var{filename} -with @code{load}. If @var{filename} is not supplied, then the name of -the symbol @var{feature} is used as the base file name to load. -However, in this case, @code{require} insists on finding @var{feature} -with an added @samp{.el} or @samp{.elc} suffix (possibly extended with -a compression suffix); a file whose name is just @var{feature} won't -be used. (The variable @code{load-suffixes} specifies the exact -required Lisp suffixes.) - -If @var{noerror} is non-@code{nil}, that suppresses errors from actual -loading of the file. In that case, @code{require} returns @code{nil} -if loading the file fails. Normally, @code{require} returns -@var{feature}. - -If loading the file succeeds but does not provide @var{feature}, -@code{require} signals an error, @samp{Required feature @var{feature} -was not provided}. -@end defun - -@defun featurep feature &optional subfeature -This function returns @code{t} if @var{feature} has been provided in -the current Emacs session (i.e.@:, if @var{feature} is a member of -@code{features}.) If @var{subfeature} is non-@code{nil}, then the -function returns @code{t} only if that subfeature is provided as well -(i.e.@: if @var{subfeature} is a member of the @code{subfeature} -property of the @var{feature} symbol.) -@end defun - -@defvar features -The value of this variable is a list of symbols that are the features -loaded in the current Emacs session. Each symbol was put in this list -with a call to @code{provide}. The order of the elements in the -@code{features} list is not significant. -@end defvar - -@node Where Defined -@section Which File Defined a Certain Symbol - -@defun symbol-file symbol &optional type -This function returns the name of the file that defined @var{symbol}. -If @var{type} is @code{nil}, then any kind of definition is acceptable. -If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that -specifies function definition, variable definition, or face definition -only. - -The value is normally an absolute file name. It can also be @code{nil}, -if the definition is not associated with any file. If @var{symbol} -specifies an autoloaded function, the value can be a relative file name -without extension. -@end defun - - The basis for @code{symbol-file} is the data in the variable -@code{load-history}. - -@defvar load-history -The value of this variable is an alist that associates the names of -loaded library files with the names of the functions and variables -they defined, as well as the features they provided or required. - -Each element in this alist describes one loaded library (including -libraries that are preloaded at startup). It is a list whose @sc{car} -is the absolute file name of the library (a string). The rest of the -list elements have these forms: - -@table @code -@item @var{var} -The symbol @var{var} was defined as a variable. -@item (defun . @var{fun}) -The function @var{fun} was defined. -@item (t . @var{fun}) -The function @var{fun} was previously an autoload before this library -redefined it as a function. The following element is always -@code{(defun . @var{fun})}, which represents defining @var{fun} as a -function. -@item (autoload . @var{fun}) -The function @var{fun} was defined as an autoload. -@item (defface . @var{face}) -The face @var{face} was defined. -@item (require . @var{feature}) -The feature @var{feature} was required. -@item (provide . @var{feature}) -The feature @var{feature} was provided. -@end table - -The value of @code{load-history} may have one element whose @sc{car} is -@code{nil}. This element describes definitions made with -@code{eval-buffer} on a buffer that is not visiting a file. -@end defvar - - The command @code{eval-region} updates @code{load-history}, but does so -by adding the symbols defined to the element for the file being visited, -rather than replacing that element. @xref{Eval}. - -@node Unloading -@section Unloading -@cindex unloading packages - -@c Emacs 19 feature - You can discard the functions and variables loaded by a library to -reclaim memory for other Lisp objects. To do this, use the function -@code{unload-feature}: - -@deffn Command unload-feature feature &optional force -This command unloads the library that provided feature @var{feature}. -It undefines all functions, macros, and variables defined in that -library with @code{defun}, @code{defalias}, @code{defsubst}, -@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}. -It then restores any autoloads formerly associated with those symbols. -(Loading saves these in the @code{autoload} property of the symbol.) - -Before restoring the previous definitions, @code{unload-feature} runs -@code{remove-hook} to remove functions in the library from certain -hooks. These hooks include variables whose names end in @samp{hook} -or @samp{-hooks}, plus those listed in -@code{unload-feature-special-hooks}, as well as -@code{auto-mode-alist}. This is to prevent Emacs from ceasing to -function because important hooks refer to functions that are no longer -defined. - -Standard unloading activities also undoes ELP profiling of functions -in that library, unprovides any features provided by the library, and -cancels timers held in variables defined by the library. - -@vindex @var{feature}-unload-function -If these measures are not sufficient to prevent malfunction, a library -can define an explicit unloader named @code{@var{feature}-unload-function}. -If that symbol is defined as a function, @code{unload-feature} calls -it with no arguments before doing anything else. It can do whatever -is appropriate to unload the library. If it returns @code{nil}, -@code{unload-feature} proceeds to take the normal unload actions. -Otherwise it considers the job to be done. - -Ordinarily, @code{unload-feature} refuses to unload a library on which -other loaded libraries depend. (A library @var{a} depends on library -@var{b} if @var{a} contains a @code{require} for @var{b}.) If the -optional argument @var{force} is non-@code{nil}, dependencies are -ignored and you can unload any library. -@end deffn - - The @code{unload-feature} function is written in Lisp; its actions are -based on the variable @code{load-history}. - -@defvar unload-feature-special-hooks -This variable holds a list of hooks to be scanned before unloading a -library, to remove functions defined in the library. -@end defvar - -@node Hooks for Loading -@section Hooks for Loading -@cindex loading hooks -@cindex hooks for loading - -You can ask for code to be executed each time Emacs loads a library, -by using the variable @code{after-load-functions}: - -@defvar after-load-functions -This abnormal hook is run after loading a file. Each function in the -hook is called with a single argument, the absolute filename of the -file that was just loaded. -@end defvar - -If you want code to be executed when a @emph{particular} library is -loaded, use the function @code{eval-after-load}: - -@defun eval-after-load library form -This function arranges to evaluate @var{form} at the end of loading -the file @var{library}, each time @var{library} is loaded. If -@var{library} is already loaded, it evaluates @var{form} right away. -Don't forget to quote @var{form}! - -You don't need to give a directory or extension in the file name -@var{library}. Normally, you just give a bare file name, like this: - -@example -(eval-after-load "edebug" '(def-edebug-spec c-point t)) -@end example - -To restrict which files can trigger the evaluation, include a -directory or an extension or both in @var{library}. Only a file whose -absolute true name (i.e., the name with all symbolic links chased out) -matches all the given name components will match. In the following -example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory -@code{..../foo/bar} will trigger the evaluation, but not -@file{my_inst.el}: - -@example -(eval-after-load "foo/bar/my_inst.elc" @dots{}) -@end example - -@var{library} can also be a feature (i.e.@: a symbol), in which case -@var{form} is evaluated at the end of any file where -@code{(provide @var{library})} is called. - -An error in @var{form} does not undo the load, but does prevent -execution of the rest of @var{form}. -@end defun - -Normally, well-designed Lisp programs should not use -@code{eval-after-load}. If you need to examine and set the variables -defined in another library (those meant for outside use), you can do -it immediately---there is no need to wait until the library is loaded. -If you need to call functions defined by that library, you should load -the library, preferably with @code{require} (@pxref{Named Features}). - -@defvar after-load-alist -This variable stores an alist built by @code{eval-after-load}, -containing the expressions to evaluate when certain libraries are -loaded. Each element looks like this: - -@example -(@var{regexp-or-feature} @var{forms}@dots{}) -@end example - -The key @var{regexp-or-feature} is either a regular expression or a -symbol, and the value is a list of forms. The forms are evaluated -when the key matches the absolute true name or feature name of the -library being loaded. -@end defvar diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi deleted file mode 100644 index 5cdcfae1e50..00000000000 --- a/doc/lispref/macros.texi +++ /dev/null @@ -1,659 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/macros -@node Macros, Customization, Functions, Top -@chapter Macros -@cindex macros - - @dfn{Macros} enable you to define new control constructs and other -language features. A macro is defined much like a function, but instead -of telling how to compute a value, it tells how to compute another Lisp -expression which will in turn compute the value. We call this -expression the @dfn{expansion} of the macro. - - Macros can do this because they operate on the unevaluated expressions -for the arguments, not on the argument values as functions do. They can -therefore construct an expansion containing these argument expressions -or parts of them. - - If you are using a macro to do something an ordinary function could -do, just for the sake of speed, consider using an inline function -instead. @xref{Inline Functions}. - -@menu -* Simple Macro:: A basic example. -* Expansion:: How, when and why macros are expanded. -* Compiling Macros:: How macros are expanded by the compiler. -* Defining Macros:: How to write a macro definition. -* Problems with Macros:: Don't evaluate the macro arguments too many times. - Don't hide the user's variables. -* Indenting Macros:: Specifying how to indent macro calls. -@end menu - -@node Simple Macro -@section A Simple Example of a Macro - - Suppose we would like to define a Lisp construct to increment a -variable value, much like the @code{++} operator in C. We would like to -write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}. -Here's a macro definition that does the job: - -@findex inc -@example -@group -(defmacro inc (var) - (list 'setq var (list '1+ var))) -@end group -@end example - - When this is called with @code{(inc x)}, the argument @var{var} is the -symbol @code{x}---@emph{not} the @emph{value} of @code{x}, as it would -be in a function. The body of the macro uses this to construct the -expansion, which is @code{(setq x (1+ x))}. Once the macro definition -returns this expansion, Lisp proceeds to evaluate it, thus incrementing -@code{x}. - -@node Expansion -@section Expansion of a Macro Call -@cindex expansion of macros -@cindex macro call - - A macro call looks just like a function call in that it is a list which -starts with the name of the macro. The rest of the elements of the list -are the arguments of the macro. - - Evaluation of the macro call begins like evaluation of a function call -except for one crucial difference: the macro arguments are the actual -expressions appearing in the macro call. They are not evaluated before -they are given to the macro definition. By contrast, the arguments of a -function are results of evaluating the elements of the function call -list. - - Having obtained the arguments, Lisp invokes the macro definition just -as a function is invoked. The argument variables of the macro are bound -to the argument values from the macro call, or to a list of them in the -case of a @code{&rest} argument. And the macro body executes and -returns its value just as a function body does. - - The second crucial difference between macros and functions is that -the value returned by the macro body is an alternate Lisp expression, -also known as the @dfn{expansion} of the macro. The Lisp interpreter -proceeds to evaluate the expansion as soon as it comes back from the -macro. - - Since the expansion is evaluated in the normal manner, it may contain -calls to other macros. It may even be a call to the same macro, though -this is unusual. - - You can see the expansion of a given macro call by calling -@code{macroexpand}. - -@defun macroexpand form &optional environment -@cindex macro expansion -This function expands @var{form}, if it is a macro call. If the result -is another macro call, it is expanded in turn, until something which is -not a macro call results. That is the value returned by -@code{macroexpand}. If @var{form} is not a macro call to begin with, it -is returned as given. - -Note that @code{macroexpand} does not look at the subexpressions of -@var{form} (although some macro definitions may do so). Even if they -are macro calls themselves, @code{macroexpand} does not expand them. - -The function @code{macroexpand} does not expand calls to inline functions. -Normally there is no need for that, since a call to an inline function is -no harder to understand than a call to an ordinary function. - -If @var{environment} is provided, it specifies an alist of macro -definitions that shadow the currently defined macros. Byte compilation -uses this feature. - -@example -@group -(defmacro inc (var) - (list 'setq var (list '1+ var))) - @result{} inc -@end group - -@group -(macroexpand '(inc r)) - @result{} (setq r (1+ r)) -@end group - -@group -(defmacro inc2 (var1 var2) - (list 'progn (list 'inc var1) (list 'inc var2))) - @result{} inc2 -@end group - -@group -(macroexpand '(inc2 r s)) - @result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.} -@end group -@end example -@end defun - - -@defun macroexpand-all form &optional environment -@code{macroexpand-all} expands macros like @code{macroexpand}, but -will look for and expand all macros in @var{form}, not just at the -top-level. If no macros are expanded, the return value is @code{eq} -to @var{form}. - -Repeating the example used for @code{macroexpand} above with -@code{macroexpand-all}, we see that @code{macroexpand-all} @emph{does} -expand the embedded calls to @code{inc}: - -@example -(macroexpand-all '(inc2 r s)) - @result{} (progn (setq r (1+ r)) (setq s (1+ s))) -@end example - -@end defun - -@node Compiling Macros -@section Macros and Byte Compilation -@cindex byte-compiling macros - - You might ask why we take the trouble to compute an expansion for a -macro and then evaluate the expansion. Why not have the macro body -produce the desired results directly? The reason has to do with -compilation. - - When a macro call appears in a Lisp program being compiled, the Lisp -compiler calls the macro definition just as the interpreter would, and -receives an expansion. But instead of evaluating this expansion, it -compiles the expansion as if it had appeared directly in the program. -As a result, the compiled code produces the value and side effects -intended for the macro, but executes at full compiled speed. This would -not work if the macro body computed the value and side effects -itself---they would be computed at compile time, which is not useful. - - In order for compilation of macro calls to work, the macros must -already be defined in Lisp when the calls to them are compiled. The -compiler has a special feature to help you do this: if a file being -compiled contains a @code{defmacro} form, the macro is defined -temporarily for the rest of the compilation of that file. - - Byte-compiling a file also executes any @code{require} calls at -top-level in the file, so you can ensure that necessary macro -definitions are available during compilation by requiring the files -that define them (@pxref{Named Features}). To avoid loading the macro -definition files when someone @emph{runs} the compiled program, write -@code{eval-when-compile} around the @code{require} calls (@pxref{Eval -During Compile}). - -@node Defining Macros -@section Defining Macros - - A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should -be a function; expansion of the macro works by applying the function -(with @code{apply}) to the list of unevaluated argument-expressions -from the macro call. - - It is possible to use an anonymous Lisp macro just like an anonymous -function, but this is never done, because it does not make sense to pass -an anonymous macro to functionals such as @code{mapcar}. In practice, -all Lisp macros have names, and they are usually defined with the -special form @code{defmacro}. - -@defspec defmacro name argument-list body-forms@dots{} -@code{defmacro} defines the symbol @var{name} as a macro that looks -like this: - -@example -(macro lambda @var{argument-list} . @var{body-forms}) -@end example - -(Note that the @sc{cdr} of this list is a function---a lambda expression.) -This macro object is stored in the function cell of @var{name}. The -value returned by evaluating the @code{defmacro} form is @var{name}, but -usually we ignore this value. - -The shape and meaning of @var{argument-list} is the same as in a -function, and the keywords @code{&rest} and @code{&optional} may be used -(@pxref{Argument List}). Macros may have a documentation string, but -any @code{interactive} declaration is ignored since macros cannot be -called interactively. -@end defspec - - Macros often need to construct large list structures from a mixture -of constants and nonconstant parts. To make this easier, use the -@samp{`} syntax (@pxref{Backquote}). For example: - -@example -@example -@group -(defmacro t-becomes-nil (variable) - `(if (eq ,variable t) - (setq ,variable nil))) -@end group - -@group -(t-becomes-nil foo) - @equiv{} (if (eq foo t) (setq foo nil)) -@end group -@end example -@end example - - The body of a macro definition can include a @code{declare} form, -which can specify how @key{TAB} should indent macro calls, and how to -step through them for Edebug. - -@defmac declare @var{specs}@dots{} -@anchor{Definition of declare} -A @code{declare} form is used in a macro definition to specify various -additional information about it. The following specifications are -currently supported: - -@table @code -@item (debug @var{edebug-form-spec}) -Specify how to step through macro calls for Edebug. -@xref{Instrumenting Macro Calls}. - -@item (indent @var{indent-spec}) -Specify how to indent calls to this macro. @xref{Indenting Macros}, -for more details. - -@item (doc-string @var{number}) -Specify which element of the macro is the documentation string, if -any. -@end table - -A @code{declare} form only has its special effect in the body of a -@code{defmacro} form if it immediately follows the documentation -string, if present, or the argument list otherwise. (Strictly -speaking, @emph{several} @code{declare} forms can follow the -documentation string or argument list, but since a @code{declare} form -can have several @var{specs}, they can always be combined into a -single form.) When used at other places in a @code{defmacro} form, or -outside a @code{defmacro} form, @code{declare} just returns @code{nil} -without evaluating any @var{specs}. -@end defmac - - No macro absolutely needs a @code{declare} form, because that form -has no effect on how the macro expands, on what the macro means in the -program. It only affects the secondary features listed above. - -@node Problems with Macros -@section Common Problems Using Macros - - Macro expansion can have counterintuitive consequences. This -section describes some important consequences that can lead to -trouble, and rules to follow to avoid trouble. - -@menu -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. -@end menu - -@node Wrong Time -@subsection Wrong Time - - The most common problem in writing macros is doing some of the -real work prematurely---while expanding the macro, rather than in the -expansion itself. For instance, one real package had this macro -definition: - -@example -(defmacro my-set-buffer-multibyte (arg) - (if (fboundp 'set-buffer-multibyte) - (set-buffer-multibyte arg))) -@end example - -With this erroneous macro definition, the program worked fine when -interpreted but failed when compiled. This macro definition called -@code{set-buffer-multibyte} during compilation, which was wrong, and -then did nothing when the compiled package was run. The definition -that the programmer really wanted was this: - -@example -(defmacro my-set-buffer-multibyte (arg) - (if (fboundp 'set-buffer-multibyte) - `(set-buffer-multibyte ,arg))) -@end example - -@noindent -This macro expands, if appropriate, into a call to -@code{set-buffer-multibyte} that will be executed when the compiled -program is actually run. - -@node Argument Evaluation -@subsection Evaluating Macro Arguments Repeatedly - - When defining a macro you must pay attention to the number of times -the arguments will be evaluated when the expansion is executed. The -following macro (used to facilitate iteration) illustrates the -problem. This macro allows us to write a ``for'' loop construct. - -@findex for -@example -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple \"for\" loop. -For example, (for i from 1 to 10 do (print i))." - (list 'let (list (list var init)) - (cons 'while (cons (list '<= var final) - (append body (list (list 'inc var))))))) -@end group -@result{} for - -@group -(for i from 1 to 3 do - (setq square (* i i)) - (princ (format "\n%d %d" i square))) -@expansion{} -@end group -@group -(let ((i 1)) - (while (<= i 3) - (setq square (* i i)) - (princ (format "\n%d %d" i square)) - (inc i))) -@end group -@group - - @print{}1 1 - @print{}2 4 - @print{}3 9 -@result{} nil -@end group -@end example - -@noindent -The arguments @code{from}, @code{to}, and @code{do} in this macro are -``syntactic sugar''; they are entirely ignored. The idea is that you -will write noise words (such as @code{from}, @code{to}, and @code{do}) -in those positions in the macro call. - -Here's an equivalent definition simplified through use of backquote: - -@example -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple \"for\" loop. -For example, (for i from 1 to 10 do (print i))." - `(let ((,var ,init)) - (while (<= ,var ,final) - ,@@body - (inc ,var)))) -@end group -@end example - -Both forms of this definition (with backquote and without) suffer from -the defect that @var{final} is evaluated on every iteration. If -@var{final} is a constant, this is not a problem. If it is a more -complex form, say @code{(long-complex-calculation x)}, this can slow -down the execution significantly. If @var{final} has side effects, -executing it more than once is probably incorrect. - -@cindex macro argument evaluation -A well-designed macro definition takes steps to avoid this problem by -producing an expansion that evaluates the argument expressions exactly -once unless repeated evaluation is part of the intended purpose of the -macro. Here is a correct expansion for the @code{for} macro: - -@example -@group -(let ((i 1) - (max 3)) - (while (<= i max) - (setq square (* i i)) - (princ (format "%d %d" i square)) - (inc i))) -@end group -@end example - -Here is a macro definition that creates this expansion: - -@example -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple for loop: (for i from 1 to 10 do (print i))." - `(let ((,var ,init) - (max ,final)) - (while (<= ,var max) - ,@@body - (inc ,var)))) -@end group -@end example - - Unfortunately, this fix introduces another problem, -described in the following section. - -@node Surprising Local Vars -@subsection Local Variables in Macro Expansions - -@ifnottex - In the previous section, the definition of @code{for} was fixed as -follows to make the expansion evaluate the macro arguments the proper -number of times: - -@example -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple for loop: (for i from 1 to 10 do (print i))." -@end group -@group - `(let ((,var ,init) - (max ,final)) - (while (<= ,var max) - ,@@body - (inc ,var)))) -@end group -@end example -@end ifnottex - - The new definition of @code{for} has a new problem: it introduces a -local variable named @code{max} which the user does not expect. This -causes trouble in examples such as the following: - -@example -@group -(let ((max 0)) - (for x from 0 to 10 do - (let ((this (frob x))) - (if (< max this) - (setq max this))))) -@end group -@end example - -@noindent -The references to @code{max} inside the body of the @code{for}, which -are supposed to refer to the user's binding of @code{max}, really access -the binding made by @code{for}. - -The way to correct this is to use an uninterned symbol instead of -@code{max} (@pxref{Creating Symbols}). The uninterned symbol can be -bound and referred to just like any other symbol, but since it is -created by @code{for}, we know that it cannot already appear in the -user's program. Since it is not interned, there is no way the user can -put it into the program later. It will never appear anywhere except -where put by @code{for}. Here is a definition of @code{for} that works -this way: - -@example -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple for loop: (for i from 1 to 10 do (print i))." - (let ((tempvar (make-symbol "max"))) - `(let ((,var ,init) - (,tempvar ,final)) - (while (<= ,var ,tempvar) - ,@@body - (inc ,var))))) -@end group -@end example - -@noindent -This creates an uninterned symbol named @code{max} and puts it in the -expansion instead of the usual interned symbol @code{max} that appears -in expressions ordinarily. - -@node Eval During Expansion -@subsection Evaluating Macro Arguments in Expansion - - Another problem can happen if the macro definition itself -evaluates any of the macro argument expressions, such as by calling -@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the -user's variables, you may have trouble if the user happens to use a -variable with the same name as one of the macro arguments. Inside the -macro body, the macro argument binding is the most local binding of this -variable, so any references inside the form being evaluated do refer to -it. Here is an example: - -@example -@group -(defmacro foo (a) - (list 'setq (eval a) t)) - @result{} foo -@end group -@group -(setq x 'b) -(foo x) @expansion{} (setq b t) - @result{} t ; @r{and @code{b} has been set.} -;; @r{but} -(setq a 'c) -(foo a) @expansion{} (setq a t) - @result{} t ; @r{but this set @code{a}, not @code{c}.} - -@end group -@end example - - It makes a difference whether the user's variable is named @code{a} or -@code{x}, because @code{a} conflicts with the macro argument variable -@code{a}. - - Another problem with calling @code{eval} in a macro definition is that -it probably won't do what you intend in a compiled program. The -byte compiler runs macro definitions while compiling the program, when -the program's own computations (which you might have wished to access -with @code{eval}) don't occur and its local variable bindings don't -exist. - - To avoid these problems, @strong{don't evaluate an argument expression -while computing the macro expansion}. Instead, substitute the -expression into the macro expansion, so that its value will be computed -as part of executing the expansion. This is how the other examples in -this chapter work. - -@node Repeated Expansion -@subsection How Many Times is the Macro Expanded? - - Occasionally problems result from the fact that a macro call is -expanded each time it is evaluated in an interpreted function, but is -expanded only once (during compilation) for a compiled function. If the -macro definition has side effects, they will work differently depending -on how many times the macro is expanded. - - Therefore, you should avoid side effects in computation of the -macro expansion, unless you really know what you are doing. - - One special kind of side effect can't be avoided: constructing Lisp -objects. Almost all macro expansions include constructed lists; that is -the whole point of most macros. This is usually safe; there is just one -case where you must be careful: when the object you construct is part of a -quoted constant in the macro expansion. - - If the macro is expanded just once, in compilation, then the object is -constructed just once, during compilation. But in interpreted -execution, the macro is expanded each time the macro call runs, and this -means a new object is constructed each time. - - In most clean Lisp code, this difference won't matter. It can matter -only if you perform side-effects on the objects constructed by the macro -definition. Thus, to avoid trouble, @strong{avoid side effects on -objects constructed by macro definitions}. Here is an example of how -such side effects can get you into trouble: - -@lisp -@group -(defmacro empty-object () - (list 'quote (cons nil nil))) -@end group - -@group -(defun initialize (condition) - (let ((object (empty-object))) - (if condition - (setcar object condition)) - object)) -@end group -@end lisp - -@noindent -If @code{initialize} is interpreted, a new list @code{(nil)} is -constructed each time @code{initialize} is called. Thus, no side effect -survives between calls. If @code{initialize} is compiled, then the -macro @code{empty-object} is expanded during compilation, producing a -single ``constant'' @code{(nil)} that is reused and altered each time -@code{initialize} is called. - -One way to avoid pathological cases like this is to think of -@code{empty-object} as a funny kind of constant, not as a memory -allocation construct. You wouldn't use @code{setcar} on a constant such -as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)} -either. - -@node Indenting Macros -@section Indenting Macros - - Within a macro definition, you can use the @code{declare} form -(@pxref{Defining Macros}) to specify how @key{TAB} should indent -calls to the macro. An indentation specification is written like this: - -@example -(declare (indent @var{indent-spec})) -@end example - -@noindent -Here are the possibilities for @var{indent-spec}: - -@table @asis -@item @code{nil} -This is the same as no property---use the standard indentation pattern. -@item @code{defun} -Handle this function like a @samp{def} construct: treat the second -line as the start of a @dfn{body}. -@item an integer, @var{number} -The first @var{number} arguments of the function are -@dfn{distinguished} arguments; the rest are considered the body -of the expression. A line in the expression is indented according to -whether the first argument on it is distinguished or not. If the -argument is part of the body, the line is indented @code{lisp-body-indent} -more columns than the open-parenthesis starting the containing -expression. If the argument is distinguished and is either the first -or second argument, it is indented @emph{twice} that many extra columns. -If the argument is distinguished and not the first or second argument, -the line uses the standard pattern. -@item a symbol, @var{symbol} -@var{symbol} should be a function name; that function is called to -calculate the indentation of a line within this expression. The -function receives two arguments: - -@table @asis -@item @var{state} -The value returned by @code{parse-partial-sexp} (a Lisp primitive for -indentation and nesting computation) when it parses up to the -beginning of this line. -@item @var{pos} -The position at which the line being indented begins. -@end table - -@noindent -It should return either a number, which is the number of columns of -indentation for that line, or a list whose car is such a number. The -difference between returning a number and returning a list is that a -number says that all following lines at the same nesting level should -be indented just like this one; a list says that following lines might -call for different indentations. This makes a difference when the -indentation is being computed by @kbd{C-M-q}; if the value is a -number, @kbd{C-M-q} need not recalculate indentation for the following -lines until the end of the list. -@end table diff --git a/doc/lispref/makefile.w32-in b/doc/lispref/makefile.w32-in deleted file mode 100644 index 0a4aea2d7e0..00000000000 --- a/doc/lispref/makefile.w32-in +++ /dev/null @@ -1,127 +0,0 @@ -# -*- Makefile -*- for the GNU Emacs Lisp Reference Manual. - -# Copyright (C) 2003-2012 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -# Standard configure variables. -srcdir = . - -infodir = $(srcdir)/../../info - -# Directory with emacsver.texi. -emacsdir = $(srcdir)/../emacs -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc - -# Redefine `TEX' if `tex' does not invoke plain TeX. For example: -# TEX=platex -TEX=tex -INSTALL_INFO = install-info -MAKEINFO = makeinfo -MAKEINFO_OPTS = --force --enable-encoding -I$(srcdir) -I$(emacsdir) - -# The environment variable and its value to add $(srcdir) to the path -# searched for TeX input files. -texinputdir = $(srcdir)\..\..\nt\envadd.bat \ - "TEXINPUTS=$(srcdir);$(texinfodir);$(emacsdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) $(MAKEINFO_OPTS)" /C - -# List of all the texinfo files in the manual: - -srcs = \ - $(emacsdir)/emacsver.texi \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/advice.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/back.texi \ - $(srcdir)/backups.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/compile.texi \ - $(srcdir)/control.texi \ - $(srcdir)/customize.texi \ - $(srcdir)/debugging.texi \ - $(srcdir)/display.texi \ - $(srcdir)/edebug.texi \ - $(srcdir)/elisp.texi \ - $(srcdir)/errors.texi \ - $(srcdir)/eval.texi \ - $(srcdir)/files.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/functions.texi \ - $(srcdir)/hash.texi \ - $(srcdir)/help.texi \ - $(srcdir)/hooks.texi \ - $(srcdir)/internals.texi \ - $(srcdir)/intro.texi \ - $(srcdir)/keymaps.texi \ - $(srcdir)/lists.texi \ - $(srcdir)/loading.texi \ - $(srcdir)/macros.texi \ - $(srcdir)/maps.texi \ - $(srcdir)/markers.texi \ - $(srcdir)/minibuf.texi \ - $(srcdir)/modes.texi \ - $(srcdir)/nonascii.texi \ - $(srcdir)/numbers.texi \ - $(srcdir)/objects.texi \ - $(srcdir)/os.texi \ - $(srcdir)/package.texi \ - $(srcdir)/positions.texi \ - $(srcdir)/processes.texi \ - $(srcdir)/searching.texi \ - $(srcdir)/sequences.texi \ - $(srcdir)/streams.texi \ - $(srcdir)/strings.texi \ - $(srcdir)/symbols.texi \ - $(srcdir)/syntax.texi \ - $(srcdir)/text.texi \ - $(srcdir)/tips.texi \ - $(srcdir)/variables.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/index.texi \ - $(srcdir)/gpl.texi \ - $(srcdir)/doclicense.texi - - -.PHONY: clean - -# The info file is named `elisp'. - -info: $(infodir)/elisp - -$(infodir)/dir: - $(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/elisp - -$(infodir)/elisp: $(srcs) - $(MAKEINFO) $(MAKEINFO_OPTS) -o $(infodir)/elisp $(srcdir)/elisp.texi - -elisp.dvi: $(srcs) - $(texinputdir) $(TEX) $(srcdir)/elisp.texi - -clean: - - $(DEL) *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \ - *.vr *.vrs *.pg *.pgs *.ky *.kys - - $(DEL) make.out core - - $(DEL) $(infodir)/elisp* - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) elisp elisp-? elisp-?? elisp.dvi elisp.oaux diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi deleted file mode 100644 index b303562028b..00000000000 --- a/doc/lispref/maps.texi +++ /dev/null @@ -1,199 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/maps -@node Standard Keymaps, Standard Hooks, Standard Errors, Top -@appendix Standard Keymaps -@cindex keymaps, standard - -In this section we list some of the more general keymaps. Many of -these exist when Emacs is first started, but some are loaded only when -the respective feature is accessed. - -There are many other, more specialized, maps than these; in particular -those associated with major and minor modes. The minibuffer uses -several keymaps (@pxref{Completion Commands}). For more details on -keymaps, @pxref{Keymaps}. - -@c Don't list individual major mode keymaps here, only more general things. -@c Only add vindex for things not covered elsewhere in this manual. -@c Don't add xrefs to things covered in {Keymaps}. -@table @code -@item 2C-mode-map -A sparse keymap for subcommands of the prefix @kbd{C-x 6}.@* -@xref{Two-Column,, Two-Column Editing, emacs, The GNU Emacs Manual}. - -@item abbrev-map -@vindex abbrev-map -A sparse keymap for subcommands of the prefix @kbd{C-x a}.@* -@xref{Defining Abbrevs,,, emacs, The GNU Emacs Manual}. - -@item button-buffer-map -A sparse keymap useful for buffers containing buffers.@* -You may want to use this as a parent keymap. @xref{Buttons}. - -@item button-map -A sparse keymap used by buttons. - -@item ctl-x-4-map -A sparse keymap for subcommands of the prefix @kbd{C-x 4}. - -@item ctl-x-5-map -A sparse keymap for subcommands of the prefix @kbd{C-x 5}. - -@item ctl-x-map -A full keymap for @kbd{C-x} commands. - -@item ctl-x-r-map -@vindex ctl-x-r-map -A sparse keymap for subcommands of the prefix @kbd{C-x r}.@* -@xref{Registers,,, emacs, The GNU Emacs Manual}. - -@item esc-map -A full keymap for @kbd{ESC} (or @kbd{Meta}) commands. - -@item facemenu-keymap -A sparse keymap used for the @kbd{M-o} prefix key. - -@item function-key-map -The parent keymap of all @code{local-function-key-map} (q.v.) instances. - -@ignore -@c Doesn't exist. -@item fundamental-mode-map -@vindex fundamental-mode-map -The sparse keymap for Fundamental mode.@* -It is empty and should not be changed. -@end ignore - -@item global-map -The full keymap containing default global key bindings.@* -Modes should not modify the Global map. - -@item goto-map -A sparse keymap used for the @kbd{M-g} prefix key. - -@item help-map -A sparse keymap for the keys following the help character @kbd{C-h}.@* -@xref{Help Functions}. - -@item Helper-help-map -A full keymap used by the help utility package.@* -It has the same keymap in its value cell and in its function cell. - -@item input-decode-map -The keymap for translating keypad and function keys.@* -If there are none, then it contains an empty sparse keymap. -@xref{Translation Keymaps}. - -@item key-translation-map -A keymap for translating keys. This one overrides ordinary key -bindings, unlike @code{local-function-key-map}. @xref{Translation -Keymaps}. - -@item kmacro-keymap -@vindex kmacro-keymap -A sparse keymap for keys that follows the @kbd{C-x C-k} prefix search.@* -@xref{Keyboard Macros,,, emacs, The GNU Emacs Manual}. - -@item local-function-key-map -The keymap for translating key sequences to preferred alternatives.@* -If there are none, then it contains an empty sparse keymap. -@xref{Translation Keymaps}. - -@item menu-bar-file-menu -@itemx menu-bar-edit-menu -@itemx menu-bar-options-menu -@itemx global-buffers-menu-map -@itemx menu-bar-tools-menu -@itemx menu-bar-help-menu -@cindex menu bar keymaps -@vindex menu-bar-file-menu -@vindex menu-bar-options-menu -@vindex global-buffers-menu-map -@vindex menu-bar-tools-menu -@vindex menu-bar-help-menu -These keymaps display the main, top-level menus in the menu bar.@* -Some of them contain sub-menus. For example, the Edit menu contains -@code{menu-bar-search-menu}, etc. @xref{Menu Bar}. -@ignore -TODO list all submenus? -There are probably too many, and it would not be useful to do so, eg: -The Edit menu includes @code{yank-menu}, @code{menu-bar-search-menu}, -@code{menu-bar-replace-menu}, @code{menu-bar-goto-menu}, -@code{menu-bar-bookmark-map}, and @code{facemenu-menu}. -There is also mule-menu-keymap, set-coding-system-map, -setup-language-environment-map, describe-language-environment-map, -menu-bar-epatch-menu, menu-bar-ediff-merge-menu, menu-bar-ediff-menu, etc. -@end ignore - -@item minibuffer-inactive-mode-map -A full keymap used in the minibuffer when it is not active.@* -@xref{Minibuffer Edit,, Editing in the Minibuffer, emacs, The GNU Emacs Manual}. - -@item mode-line-coding-system-map -@itemx mode-line-input-method-map -@itemx mode-line-column-line-number-mode-map -@vindex mode-line-coding-system-map -@vindex mode-line-input-method-map -@vindex mode-line-column-line-number-mode-map -These keymaps control various areas of the mode line.@* -@xref{Mode Line Format}. - -@item mode-specific-map -The keymap for characters following @kbd{C-c}. Note, this is in the -global map. This map is not actually mode-specific: its name was chosen -to be informative in @kbd{C-h b} (@code{display-bindings}), -where it describes the main use of the @kbd{C-c} prefix key. - -@c FIXME - don't mention this one? -@item mouse-appearance-menu-map -@vindex mouse-appearance-menu-map -A sparse keymap used for the @kbd{S-mouse-1} key. - -@item mule-keymap -The global keymap used for the @kbd{C-x @key{RET}} prefix key. - -@item narrow-map -@vindex narrow-map -A sparse keymap for subcommands of the prefix @kbd{C-x n}. - -@item prog-mode-map -The keymap used by Prog mode.@* -@xref{Basic Major Modes}. - -@item query-replace-map -@itemx multi-query-replace-map -A sparse keymap used for responses in @code{query-replace} and related -commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}. The functions -that use this map do not support prefix keys; they look up one event at a -time. @code{multi-query-replace-map} extends @code{query-replace-map} -for multi-buffer replacements. @xref{Search and Replace, query-replace-map}. - -@item search-map -A sparse keymap that provides global bindings for search-related commands. - -@item special-mode-map -The keymap used by Special mode.@* -@xref{Basic Major Modes}. - -@item tool-bar-map -The keymap defining the contents of the tool bar.@* -@xref{Tool Bar}. - -@item universal-argument-map -@vindex universal-argument-map -A sparse keymap used while processing @kbd{C-u}.@* -@xref{Prefix Command Arguments}. - -@item vc-prefix-map -The global keymap used for the @kbd{C-x v} prefix key. - -@item x-alternatives-map -@vindex x-alternatives-map -@findex x-setup-function-keys -A sparse keymap used to map certain keys under graphical frames.@* -The function @code{x-setup-function-keys} uses this. - -@end table diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi deleted file mode 100644 index 1e8829396a7..00000000000 --- a/doc/lispref/markers.texi +++ /dev/null @@ -1,695 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/markers -@node Markers, Text, Positions, Top -@chapter Markers -@cindex markers - - A @dfn{marker} is a Lisp object used to specify a position in a buffer -relative to the surrounding text. A marker changes its offset from the -beginning of the buffer automatically whenever text is inserted or -deleted, so that it stays with the two characters on either side of it. - -@menu -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers:: Finding the marker's buffer or character position. -* Marker Insertion Types:: Two ways a marker can relocate when you - insert where it points. -* Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How "the mark" is implemented with a marker. -* The Region:: How to access "the region". -@end menu - -@node Overview of Markers -@section Overview of Markers - - A marker specifies a buffer and a position in that buffer. A -marker can be used to represent a position in functions that -require one, just as an integer could be used. In that case, the -marker's buffer is normally ignored. Of course, a marker used in this -way usually points to a position in the buffer that the function -operates on, but that is entirely the programmer's responsibility. -@xref{Positions}, for a complete description of positions. - - A marker has three attributes: the marker position, the marker -buffer, and the insertion type. The marker position is an integer -that is equivalent (at a given time) to the marker as a position in -that buffer. But the marker's position value can change during -the life of the marker, and often does. Insertion and deletion of -text in the buffer relocate the marker. The idea is that a marker -positioned between two characters remains between those two characters -despite insertion and deletion elsewhere in the buffer. Relocation -changes the integer equivalent of the marker. - -@cindex marker relocation - Deleting text around a marker's position leaves the marker between the -characters immediately before and after the deleted text. Inserting -text at the position of a marker normally leaves the marker either in -front of or after the new text, depending on the marker's @dfn{insertion -type} (@pxref{Marker Insertion Types})---unless the insertion is done -with @code{insert-before-markers} (@pxref{Insertion}). - -@cindex marker garbage collection - Insertion and deletion in a buffer must check all the markers and -relocate them if necessary. This slows processing in a buffer with a -large number of markers. For this reason, it is a good idea to make a -marker point nowhere if you are sure you don't need it any more. -Markers that can no longer be accessed are eventually removed -(@pxref{Garbage Collection}). - -@cindex markers as numbers - Because it is common to perform arithmetic operations on a marker -position, most of these operations (including @code{+} and -@code{-}) accept markers as arguments. In such cases, the marker -stands for its current position. - -Here are examples of creating markers, setting markers, and moving point -to markers: - -@example -@group -;; @r{Make a new marker that initially does not point anywhere:} -(setq m1 (make-marker)) - @result{} # -@end group - -@group -;; @r{Set @code{m1} to point between the 99th and 100th characters} -;; @r{in the current buffer:} -(set-marker m1 100) - @result{} # -@end group - -@group -;; @r{Now insert one character at the beginning of the buffer:} -(goto-char (point-min)) - @result{} 1 -(insert "Q") - @result{} nil -@end group - -@group -;; @r{@code{m1} is updated appropriately.} -m1 - @result{} # -@end group - -@group -;; @r{Two markers that point to the same position} -;; @r{are not @code{eq}, but they are @code{equal}.} -(setq m2 (copy-marker m1)) - @result{} # -(eq m1 m2) - @result{} nil -(equal m1 m2) - @result{} t -@end group - -@group -;; @r{When you are finished using a marker, make it point nowhere.} -(set-marker m1 nil) - @result{} # -@end group -@end example - -@node Predicates on Markers -@section Predicates on Markers - - You can test an object to see whether it is a marker, or whether it is -either an integer or a marker. The latter test is useful in connection -with the arithmetic functions that work with both markers and integers. - -@defun markerp object -This function returns @code{t} if @var{object} is a marker, @code{nil} -otherwise. Note that integers are not markers, even though many -functions will accept either a marker or an integer. -@end defun - -@defun integer-or-marker-p object -This function returns @code{t} if @var{object} is an integer or a marker, -@code{nil} otherwise. -@end defun - -@defun number-or-marker-p object -This function returns @code{t} if @var{object} is a number (either -integer or floating point) or a marker, @code{nil} otherwise. -@end defun - -@node Creating Markers -@section Functions that Create Markers - - When you create a new marker, you can make it point nowhere, or point -to the present position of point, or to the beginning or end of the -accessible portion of the buffer, or to the same place as another given -marker. - -The next four functions all return markers with insertion type -@code{nil}. @xref{Marker Insertion Types}. - -@defun make-marker -This function returns a newly created marker that does not point -anywhere. - -@example -@group -(make-marker) - @result{} # -@end group -@end example -@end defun - -@defun point-marker -This function returns a new marker that points to the present position -of point in the current buffer. @xref{Point}. For an example, see -@code{copy-marker}, below. -@end defun - -@defun point-min-marker -This function returns a new marker that points to the beginning of the -accessible portion of the buffer. This will be the beginning of the -buffer unless narrowing is in effect. @xref{Narrowing}. -@end defun - -@defun point-max-marker -This function returns a new marker that points to the end of the -accessible portion of the buffer. This will be the end of the buffer -unless narrowing is in effect. @xref{Narrowing}. - -Here are examples of this function and @code{point-min-marker}, shown in -a buffer containing a version of the source file for the text of this -chapter. - -@example -@group -(point-min-marker) - @result{} # -(point-max-marker) - @result{} # -@end group - -@group -(narrow-to-region 100 200) - @result{} nil -@end group -@group -(point-min-marker) - @result{} # -@end group -@group -(point-max-marker) - @result{} # -@end group -@end example -@end defun - -@defun copy-marker &optional marker-or-integer insertion-type -If passed a marker as its argument, @code{copy-marker} returns a -new marker that points to the same place and the same buffer as does -@var{marker-or-integer}. If passed an integer as its argument, -@code{copy-marker} returns a new marker that points to position -@var{marker-or-integer} in the current buffer. - -The new marker's insertion type is specified by the argument -@var{insertion-type}. @xref{Marker Insertion Types}. - -If passed an integer argument less than 1, @code{copy-marker} returns a -new marker that points to the beginning of the current buffer. If -passed an integer argument greater than the length of the buffer, -@code{copy-marker} returns a new marker that points to the end of the -buffer. - -@example -@group -(copy-marker 0) - @result{} # -@end group - -@group -(copy-marker 90000) - @result{} # -@end group -@end example - -An error is signaled if @var{marker} is neither a marker nor an -integer. -@end defun - - Two distinct markers are considered @code{equal} (even though not -@code{eq}) to each other if they have the same position and buffer, or -if they both point nowhere. - -@example -@group -(setq p (point-marker)) - @result{} # -@end group - -@group -(setq q (copy-marker p)) - @result{} # -@end group - -@group -(eq p q) - @result{} nil -@end group - -@group -(equal p q) - @result{} t -@end group -@end example - -@node Information from Markers -@section Information from Markers - - This section describes the functions for accessing the components of a -marker object. - -@defun marker-position marker -This function returns the position that @var{marker} points to, or -@code{nil} if it points nowhere. -@end defun - -@defun marker-buffer marker -This function returns the buffer that @var{marker} points into, or -@code{nil} if it points nowhere. - -@example -@group -(setq m (make-marker)) - @result{} # -@end group -@group -(marker-position m) - @result{} nil -@end group -@group -(marker-buffer m) - @result{} nil -@end group - -@group -(set-marker m 3770 (current-buffer)) - @result{} # -@end group -@group -(marker-buffer m) - @result{} # -@end group -@group -(marker-position m) - @result{} 3770 -@end group -@end example -@end defun - -@defun buffer-has-markers-at position -This function returns @code{t} if one or more markers -point at position @var{position} in the current buffer. -@end defun - -@node Marker Insertion Types -@section Marker Insertion Types - -@cindex insertion type of a marker - When you insert text directly at the place where a marker points, -there are two possible ways to relocate that marker: it can point before -the inserted text, or point after it. You can specify which one a given -marker should do by setting its @dfn{insertion type}. Note that use of -@code{insert-before-markers} ignores markers' insertion types, always -relocating a marker to point after the inserted text. - -@defun set-marker-insertion-type marker type -This function sets the insertion type of marker @var{marker} to -@var{type}. If @var{type} is @code{t}, @var{marker} will advance when -text is inserted at its position. If @var{type} is @code{nil}, -@var{marker} does not advance when text is inserted there. -@end defun - -@defun marker-insertion-type marker -This function reports the current insertion type of @var{marker}. -@end defun - -Most functions that create markers, without an argument allowing to -specify the insertion type, create them with insertion type -@code{nil}. Also, the mark has, by default, insertion type -@code{nil}. - -@node Moving Markers -@section Moving Marker Positions - - This section describes how to change the position of an existing -marker. When you do this, be sure you know whether the marker is used -outside of your program, and, if so, what effects will result from -moving it---otherwise, confusing things may happen in other parts of -Emacs. - -@defun set-marker marker position &optional buffer -This function moves @var{marker} to @var{position} -in @var{buffer}. If @var{buffer} is not provided, it defaults to -the current buffer. - -If @var{position} is less than 1, @code{set-marker} moves @var{marker} -to the beginning of the buffer. If @var{position} is greater than the -size of the buffer, @code{set-marker} moves marker to the end of the -buffer. If @var{position} is @code{nil} or a marker that points -nowhere, then @var{marker} is set to point nowhere. - -The value returned is @var{marker}. - -@example -@group -(setq m (point-marker)) - @result{} # -@end group -@group -(set-marker m 55) - @result{} # -@end group -@group -(setq b (get-buffer "foo")) - @result{} # -@end group -@group -(set-marker m 0 b) - @result{} # -@end group -@end example -@end defun - -@defun move-marker marker position &optional buffer -This is another name for @code{set-marker}. -@end defun - -@node The Mark -@section The Mark -@cindex mark, the -@cindex mark ring - - Each buffer has a special marker, which is designated @dfn{the -mark}. When a buffer is newly created, this marker exists but does -not point anywhere; this means that the mark ``doesn't exist'' in that -buffer yet. Subsequent commands can set the mark. - - The mark specifies a position to bound a range of text for many -commands, such as @code{kill-region} and @code{indent-rigidly}. These -commands typically act on the text between point and the mark, which -is called the @dfn{region}. If you are writing a command that -operates on the region, don't examine the mark directly; instead, use -@code{interactive} with the @samp{r} specification. This provides the -values of point and the mark as arguments to the command in an -interactive call, but permits other Lisp programs to specify arguments -explicitly. @xref{Interactive Codes}. - - Some commands set the mark as a side-effect. Commands should do -this only if it has a potential use to the user, and never for their -own internal purposes. For example, the @code{replace-regexp} command -sets the mark to the value of point before doing any replacements, -because this enables the user to move back there conveniently after -the replace is finished. - - Once the mark ``exists'' in a buffer, it normally never ceases to -exist. However, it may become @dfn{inactive}, if Transient Mark mode -is enabled. The buffer-local variable @code{mark-active}, if -non-@code{nil}, means that the mark is active. A command can call the -function @code{deactivate-mark} to deactivate the mark directly, or it -can request deactivation of the mark upon return to the editor command -loop by setting the variable @code{deactivate-mark} to a -non-@code{nil} value. - - If Transient Mark mode is enabled, certain editing commands that -normally apply to text near point, apply instead to the region when -the mark is active. This is the main motivation for using Transient -Mark mode. (Another is that this enables highlighting of the region -when the mark is active. @xref{Display}.) - - In addition to the mark, each buffer has a @dfn{mark ring} which is a -list of markers containing previous values of the mark. When editing -commands change the mark, they should normally save the old value of the -mark on the mark ring. The variable @code{mark-ring-max} specifies the -maximum number of entries in the mark ring; once the list becomes this -long, adding a new element deletes the last element. - - There is also a separate global mark ring, but that is used only in a -few particular user-level commands, and is not relevant to Lisp -programming. So we do not describe it here. - -@defun mark &optional force -@cindex current buffer mark -This function returns the current buffer's mark position as an integer, -or @code{nil} if no mark has ever been set in this buffer. - -If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is -@code{nil}, @code{mark} signals an error if the mark is inactive. -However, if @var{force} is non-@code{nil}, then @code{mark} disregards -inactivity of the mark, and returns the mark position (or @code{nil}) -anyway. -@end defun - -@defun mark-marker -This function returns the marker that represents the current buffer's -mark. It is not a copy, it is the marker used internally. Therefore, -changing this marker's position will directly affect the buffer's -mark. Don't do that unless that is the effect you want. - -@example -@group -(setq m (mark-marker)) - @result{} # -@end group -@group -(set-marker m 100) - @result{} # -@end group -@group -(mark-marker) - @result{} # -@end group -@end example - -Like any marker, this marker can be set to point at any buffer you -like. If you make it point at any buffer other than the one of which -it is the mark, it will yield perfectly consistent, but rather odd, -results. We recommend that you not do it! -@end defun - -@defun set-mark position -This function sets the mark to @var{position}, and activates the mark. -The old value of the mark is @emph{not} pushed onto the mark ring. - -@strong{Please note:} Use this function only if you want the user to -see that the mark has moved, and you want the previous mark position to -be lost. Normally, when a new mark is set, the old one should go on the -@code{mark-ring}. For this reason, most applications should use -@code{push-mark} and @code{pop-mark}, not @code{set-mark}. - -Novice Emacs Lisp programmers often try to use the mark for the wrong -purposes. The mark saves a location for the user's convenience. An -editing command should not alter the mark unless altering the mark is -part of the user-level functionality of the command. (And, in that -case, this effect should be documented.) To remember a location for -internal use in the Lisp program, store it in a Lisp variable. For -example: - -@example -@group -(let ((beg (point))) - (forward-line 1) - (delete-region beg (point))). -@end group -@end example -@end defun - -@defun push-mark &optional position nomsg activate -This function sets the current buffer's mark to @var{position}, and -pushes a copy of the previous mark onto @code{mark-ring}. If -@var{position} is @code{nil}, then the value of point is used. -@c Doesn't seem relevant. -@c @code{push-mark} returns @code{nil}. - -The function @code{push-mark} normally @emph{does not} activate the -mark. To do that, specify @code{t} for the argument @var{activate}. - -A @samp{Mark set} message is displayed unless @var{nomsg} is -non-@code{nil}. -@end defun - -@defun pop-mark -This function pops off the top element of @code{mark-ring} and makes -that mark become the buffer's actual mark. This does not move point in -the buffer, and it does nothing if @code{mark-ring} is empty. It -deactivates the mark. -@c -@c Seems even less relevant. -@c The return value is not meaningful. -@end defun - -@defopt transient-mark-mode -This variable, if non-@code{nil}, enables Transient Mark mode. In -Transient Mark mode, every buffer-modifying primitive sets -@code{deactivate-mark}. As a consequence, most commands that modify -the buffer also deactivate the mark. - -When Transient Mark mode is enabled and the mark is active, many -commands that normally apply to the text near point instead apply to -the region. Such commands should use the function @code{use-region-p} -to test whether they should operate on the region. @xref{The Region}. - -Lisp programs can set @code{transient-mark-mode} to non-@code{nil}, -non-@code{t} values to enable Transient Mark mode temporarily. If the -value is @code{lambda}, Transient Mark mode is automatically turned -off after any action, such as buffer modification, that would normally -deactivate the mark. If the value is @w{@code{(only . @var{oldval})}}, -then @code{transient-mark-mode} is set to the value @var{oldval} after -any subsequent command that moves point and is not shift-translated -(@pxref{Key Sequence Input, shift-translation}), or after any other -action that would normally deactivate the mark. -@end defopt - -@defopt mark-even-if-inactive -If this is non-@code{nil}, Lisp programs and the Emacs user can use the -mark even when it is inactive. This option affects the behavior of -Transient Mark mode. When the option is non-@code{nil}, deactivation of -the mark turns off region highlighting, but commands that use the mark -behave as if the mark were still active. -@end defopt - -@defvar deactivate-mark -If an editor command sets this variable non-@code{nil}, then the editor -command loop deactivates the mark after the command returns (if -Transient Mark mode is enabled). All the primitives that change the -buffer set @code{deactivate-mark}, to deactivate the mark when the -command is finished. - -To write Lisp code that modifies the buffer without causing -deactivation of the mark at the end of the command, bind -@code{deactivate-mark} to @code{nil} around the code that does the -modification. For example: - -@example -(let (deactivate-mark) - (insert " ")) -@end example -@end defvar - -@defun deactivate-mark &optional force -If Transient Mark mode is enabled or @var{force} is non-@code{nil}, -this function deactivates the mark and runs the normal hook -@code{deactivate-mark-hook}. Otherwise, it does nothing. -@end defun - -@defvar mark-active -The mark is active when this variable is non-@code{nil}. This -variable is always buffer-local in each buffer. Do @emph{not} use the -value of this variable to decide whether a command that normally -operates on text near point should operate on the region instead. Use -the function @code{use-region-p} for that (@pxref{The Region}). -@end defvar - -@defvar activate-mark-hook -@defvarx deactivate-mark-hook -These normal hooks are run, respectively, when the mark becomes active -and when it becomes inactive. The hook @code{activate-mark-hook} is -also run at the end of the command loop if the mark is active and it -is possible that the region may have changed. -@ignore -This piece of command_loop_1, run unless deactivating the mark: - if (current_buffer != prev_buffer || MODIFF != prev_modiff) - { - Lisp_Object hook = intern ("activate-mark-hook"); - Frun_hooks (1, &hook); - } -@end ignore -@end defvar - -@defun handle-shift-selection -This function implements the ``shift-selection'' behavior of -point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs -Manual}. It is called automatically by the Emacs command loop -whenever a command with a @samp{^} character in its @code{interactive} -spec is invoked, before the command itself is executed -(@pxref{Interactive Codes, ^}). - -If @code{shift-select-mode} is non-@code{nil} and the current command -was invoked via shift translation (@pxref{Key Sequence Input, -shift-translation}), this function sets the mark and temporarily -activates the region, unless the region was already temporarily -activated in this way. Otherwise, if the region has been activated -temporarily, it deactivates the mark and restores the variable -@code{transient-mark-mode} to its earlier value. -@end defun - -@defvar mark-ring -The value of this buffer-local variable is the list of saved former -marks of the current buffer, most recent first. - -@example -@group -mark-ring -@result{} (# - # - @dots{}) -@end group -@end example -@end defvar - -@defopt mark-ring-max -The value of this variable is the maximum size of @code{mark-ring}. If -more marks than this are pushed onto the @code{mark-ring}, -@code{push-mark} discards an old mark when it adds a new one. -@end defopt - -@c There is also global-mark-ring-max, but this chapter explicitly -@c does not talk about the global mark. - -@node The Region -@section The Region -@cindex region (between point and mark) - - The text between point and the mark is known as @dfn{the region}. -Various functions operate on text delimited by point and the mark, but -only those functions specifically related to the region itself are -described here. - -The next two functions signal an error if the mark does not point -anywhere. If Transient Mark mode is enabled and -@code{mark-even-if-inactive} is @code{nil}, they also signal an error -if the mark is inactive. - -@defun region-beginning -This function returns the position of the beginning of the region (as -an integer). This is the position of either point or the mark, -whichever is smaller. -@end defun - -@defun region-end -This function returns the position of the end of the region (as an -integer). This is the position of either point or the mark, whichever is -larger. -@end defun - - Instead of using @code{region-beginning} and @code{region-end}, a -command designed to operate on a region should normally use -@code{interactive} with the @samp{r} specification to find the -beginning and end of the region. This lets other Lisp programs -specify the bounds explicitly as arguments. @xref{Interactive Codes}. - -@defun use-region-p -This function returns @code{t} if Transient Mark mode is enabled, the -mark is active, and there is a valid region in the buffer. This -function is intended to be used by commands that operate on the -region, instead of on text near point, when the mark is active. - -A region is valid if it has a non-zero size, or if the user option -@code{use-empty-active-region} is non-@code{nil} (by default, it is -@code{nil}). The function @code{region-active-p} is similar to -@code{use-region-p}, but considers all regions as valid. In most -cases, you should not use @code{region-active-p}, since if the region -is empty it is often more appropriate to operate on point. -@end defun - diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi deleted file mode 100644 index 7b4e589a704..00000000000 --- a/doc/lispref/minibuf.texi +++ /dev/null @@ -1,2346 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/minibuf -@node Minibuffers, Command Loop, Read and Print, Top -@chapter Minibuffers -@cindex arguments, reading -@cindex complex arguments -@cindex minibuffer - - A @dfn{minibuffer} is a special buffer that Emacs commands use to -read arguments more complicated than the single numeric prefix -argument. These arguments include file names, buffer names, and -command names (as in @kbd{M-x}). The minibuffer is displayed on the -bottom line of the frame, in the same place as the echo area -(@pxref{The Echo Area}), but only while it is in use for reading an -argument. - -@menu -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. -* Initial Input:: Specifying initial contents for the minibuffer. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Reading a Password:: Reading a password from the terminal. -* Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Windows:: Operating on the special minibuffer windows. -* Minibuffer Contents:: How such commands access the minibuffer text. -* Recursive Mini:: Whether recursive entry to minibuffer is allowed. -* Minibuffer Misc:: Various customization hooks and variables. -@end menu - -@node Intro to Minibuffers -@section Introduction to Minibuffers - - In most ways, a minibuffer is a normal Emacs buffer. Most operations -@emph{within} a buffer, such as editing commands, work normally in a -minibuffer. However, many operations for managing buffers do not apply -to minibuffers. The name of a minibuffer always has the form @w{@samp{ -*Minibuf-@var{number}*}}, and it cannot be changed. Minibuffers are -displayed only in special windows used only for minibuffers; these -windows always appear at the bottom of a frame. (Sometimes frames have -no minibuffer window, and sometimes a special kind of frame contains -nothing but a minibuffer window; see @ref{Minibuffers and Frames}.) - - The text in the minibuffer always starts with the @dfn{prompt string}, -the text that was specified by the program that is using the minibuffer -to tell the user what sort of input to type. This text is marked -read-only so you won't accidentally delete or change it. It is also -marked as a field (@pxref{Fields}), so that certain motion functions, -including @code{beginning-of-line}, @code{forward-word}, -@code{forward-sentence}, and @code{forward-paragraph}, stop at the -boundary between the prompt and the actual text. - -@c See http://debbugs.gnu.org/11276 - The minibuffer's window is normally a single line; it grows -automatically if the contents require more space. Whilst it is -active, you can explicitly resize it temporarily with the window -sizing commands; it reverts to its normal size when the minibuffer is -exited. When the minibuffer is not active, you can resize it -permanently by using the window sizing commands in the frame's other -window, or dragging the mode line with the mouse. (Due to details of -the current implementation, for this to work @code{resize-mini-windows} -must be @code{nil}.) If the frame contains just a minibuffer, you can -change the minibuffer's size by changing the frame's size. - - Use of the minibuffer reads input events, and that alters the values -of variables such as @code{this-command} and @code{last-command} -(@pxref{Command Loop Info}). Your program should bind them around the -code that uses the minibuffer, if you do not want that to change them. - - Under some circumstances, a command can use a minibuffer even if -there is an active minibuffer; such a minibuffer is called a -@dfn{recursive minibuffer}. The first minibuffer is named -@w{@samp{ *Minibuf-1*}}. Recursive minibuffers are named by -incrementing the number at the end of the name. (The names begin with -a space so that they won't show up in normal buffer lists.) Of -several recursive minibuffers, the innermost (or most recently -entered) is the active minibuffer. We usually call this ``the'' -minibuffer. You can permit or forbid recursive minibuffers by setting -the variable @code{enable-recursive-minibuffers}, or by putting -properties of that name on command symbols (@xref{Recursive Mini}.) - - Like other buffers, a minibuffer uses a local keymap -(@pxref{Keymaps}) to specify special key bindings. The function that -invokes the minibuffer also sets up its local map according to the job -to be done. @xref{Text from Minibuffer}, for the non-completion -minibuffer local maps. @xref{Completion Commands}, for the minibuffer -local maps for completion. - -@cindex inactive minibuffer - When a minibuffer is inactive, its major mode is -@code{minibuffer-inactive-mode}, with keymap -@code{minibuffer-inactive-mode-map}. This is only really useful if -the minibuffer is in a separate frame. @xref{Minibuffers and Frames}. - - When Emacs is running in batch mode, any request to read from the -minibuffer actually reads a line from the standard input descriptor that -was supplied when Emacs was started. - -@node Text from Minibuffer -@section Reading Text Strings with the Minibuffer - - The most basic primitive for minibuffer input is -@code{read-from-minibuffer}, which can be used to read either a string -or a Lisp object in textual form. The function @code{read-regexp} is -used for reading regular expressions (@pxref{Regular Expressions}), -which are a special kind of string. There are also specialized -functions for reading commands, variables, file names, etc.@: -(@pxref{Completion}). - - In most cases, you should not call minibuffer input functions in the -middle of a Lisp function. Instead, do all minibuffer input as part of -reading the arguments for a command, in the @code{interactive} -specification. @xref{Defining Commands}. - -@defun read-from-minibuffer prompt &optional initial keymap read history default inherit-input-method -This function is the most general way to get input from the -minibuffer. By default, it accepts arbitrary text and returns it as a -string; however, if @var{read} is non-@code{nil}, then it uses -@code{read} to convert the text into a Lisp object (@pxref{Input -Functions}). - -The first thing this function does is to activate a minibuffer and -display it with @var{prompt} (which must be a string) as the -prompt. Then the user can edit text in the minibuffer. - -When the user types a command to exit the minibuffer, -@code{read-from-minibuffer} constructs the return value from the text in -the minibuffer. Normally it returns a string containing that text. -However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer} -reads the text and returns the resulting Lisp object, unevaluated. -(@xref{Input Functions}, for information about reading.) - -The argument @var{default} specifies default values to make available -through the history commands. It should be a string, a list of -strings, or @code{nil}. The string or strings become the minibuffer's -``future history'', available to the user with @kbd{M-n}. - -If @var{read} is non-@code{nil}, then @var{default} is also used -as the input to @code{read}, if the user enters empty input. -If @var{default} is a list of strings, the first string is used as the input. -If @var{default} is @code{nil}, empty input results in an @code{end-of-file} error. -However, in the usual case (where @var{read} is @code{nil}), -@code{read-from-minibuffer} ignores @var{default} when the user enters -empty input and returns an empty string, @code{""}. In this respect, -it differs from all the other minibuffer input functions in this chapter. - -If @var{keymap} is non-@code{nil}, that keymap is the local keymap to -use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the -value of @code{minibuffer-local-map} is used as the keymap. Specifying -a keymap is the most important way to customize the minibuffer for -various applications such as completion. - -The argument @var{history} specifies a history list variable to use -for saving the input and for history commands used in the minibuffer. -It defaults to @code{minibuffer-history}. You can optionally specify -a starting position in the history list as well. @xref{Minibuffer History}. - -If the variable @code{minibuffer-allow-text-properties} is -non-@code{nil}, then the string that is returned includes whatever text -properties were present in the minibuffer. Otherwise all the text -properties are stripped when the value is returned. - -If the argument @var{inherit-input-method} is non-@code{nil}, then the -minibuffer inherits the current input method (@pxref{Input Methods}) and -the setting of @code{enable-multibyte-characters} (@pxref{Text -Representations}) from whichever buffer was current before entering the -minibuffer. - -Use of @var{initial} is mostly deprecated; we recommend using -a non-@code{nil} value only in conjunction with specifying a cons cell -for @var{history}. @xref{Initial Input}. -@end defun - -@defun read-string prompt &optional initial history default inherit-input-method -This function reads a string from the minibuffer and returns it. The -arguments @var{prompt}, @var{initial}, @var{history} and -@var{inherit-input-method} are used as in @code{read-from-minibuffer}. -The keymap used is @code{minibuffer-local-map}. - -The optional argument @var{default} is used as in -@code{read-from-minibuffer}, except that, if non-@code{nil}, it also -specifies a default value to return if the user enters null input. As -in @code{read-from-minibuffer} it should be a string, a list of -strings, or @code{nil}, which is equivalent to an empty string. When -@var{default} is a string, that string is the default value. When it -is a list of strings, the first string is the default value. (All -these strings are available to the user in the ``future minibuffer -history''.) - -This function works by calling the -@code{read-from-minibuffer} function: - -@smallexample -@group -(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit}) -@equiv{} -(let ((value - (read-from-minibuffer @var{prompt} @var{initial} nil nil - @var{history} @var{default} @var{inherit}))) - (if (and (equal value "") @var{default}) - (if (consp @var{default}) (car @var{default}) @var{default}) - value)) -@end group -@end smallexample -@end defun - -@defun read-regexp prompt &optional default -This function reads a regular expression as a string from the -minibuffer and returns it. The argument @var{prompt} is used as in -@code{read-from-minibuffer}. The keymap used is -@code{minibuffer-local-map}, and @code{regexp-history} is used as the -history list (@pxref{Minibuffer History, regexp-history}). - -The optional argument @var{default} specifies a default value to -return if the user enters null input; it should be a string, or -@code{nil}, which is equivalent to an empty string. - -In addition, @code{read-regexp} collects a few useful candidates for -input and passes them to @code{read-from-minibuffer}, to make them -available to the user as the ``future minibuffer history list'' -(@pxref{Minibuffer History, future list,, emacs, The GNU Emacs -Manual}). These candidates are: - -@itemize @minus -@item -The word or symbol at point. -@item -The last regexp used in an incremental search. -@item -The last string used in an incremental search. -@item -The last string or pattern used in query-replace commands. -@end itemize - -This function works by calling the @code{read-from-minibuffer} -function, after computing the list of defaults as described above. -@end defun - -@defvar minibuffer-allow-text-properties -If this variable is @code{nil}, then @code{read-from-minibuffer} -and @code{read-string} strip all text properties from the minibuffer -input before returning it. However, -@code{read-no-blanks-input} (see below), as well as -@code{read-minibuffer} and related functions (@pxref{Object from -Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all -functions that do minibuffer input with completion, discard text -properties unconditionally, regardless of the value of this variable. -@end defvar - -@defvar minibuffer-local-map -This -@anchor{Definition of minibuffer-local-map} -@c avoid page break at anchor; work around Texinfo deficiency -is the default local keymap for reading from the minibuffer. By -default, it makes the following bindings: - -@table @asis -@item @kbd{C-j} -@code{exit-minibuffer} - -@item @key{RET} -@code{exit-minibuffer} - -@item @kbd{C-g} -@code{abort-recursive-edit} - -@item @kbd{M-n} -@itemx @key{DOWN} -@code{next-history-element} - -@item @kbd{M-p} -@itemx @key{UP} -@code{previous-history-element} - -@item @kbd{M-s} -@code{next-matching-history-element} - -@item @kbd{M-r} -@code{previous-matching-history-element} - -@ignore -@c Does not seem worth/appropriate mentioning. -@item @kbd{C-@key{TAB}} -@code{file-cache-minibuffer-complete} -@end ignore -@end table -@end defvar - -@c In version 18, initial is required -@c Emacs 19 feature -@defun read-no-blanks-input prompt &optional initial inherit-input-method -This function reads a string from the minibuffer, but does not allow -whitespace characters as part of the input: instead, those characters -terminate the input. The arguments @var{prompt}, @var{initial}, and -@var{inherit-input-method} are used as in @code{read-from-minibuffer}. - -This is a simplified interface to the @code{read-from-minibuffer} -function, and passes the value of the @code{minibuffer-local-ns-map} -keymap as the @var{keymap} argument for that function. Since the keymap -@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is} -possible to put a space into the string, by quoting it. - -This function discards text properties, regardless of the value of -@code{minibuffer-allow-text-properties}. - -@smallexample -@group -(read-no-blanks-input @var{prompt} @var{initial}) -@equiv{} -(let (minibuffer-allow-text-properties) - (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)) -@end group -@end smallexample -@end defun - -@c Slightly unfortunate name, suggesting it might be related to the -@c Nextstep port... -@defvar minibuffer-local-ns-map -This built-in variable is the keymap used as the minibuffer local keymap -in the function @code{read-no-blanks-input}. By default, it makes the -following bindings, in addition to those of @code{minibuffer-local-map}: - -@table @asis -@item @key{SPC} -@cindex @key{SPC} in minibuffer -@code{exit-minibuffer} - -@item @key{TAB} -@cindex @key{TAB} in minibuffer -@code{exit-minibuffer} - -@item @kbd{?} -@cindex @kbd{?} in minibuffer -@code{self-insert-and-exit} -@end table -@end defvar - -@node Object from Minibuffer -@section Reading Lisp Objects with the Minibuffer - - This section describes functions for reading Lisp objects with the -minibuffer. - -@defun read-minibuffer prompt &optional initial -This function reads a Lisp object using the minibuffer, and returns it -without evaluating it. The arguments @var{prompt} and @var{initial} are -used as in @code{read-from-minibuffer}. - -This is a simplified interface to the -@code{read-from-minibuffer} function: - -@smallexample -@group -(read-minibuffer @var{prompt} @var{initial}) -@equiv{} -(let (minibuffer-allow-text-properties) - (read-from-minibuffer @var{prompt} @var{initial} nil t)) -@end group -@end smallexample - -Here is an example in which we supply the string @code{"(testing)"} as -initial input: - -@smallexample -@group -(read-minibuffer - "Enter an expression: " (format "%s" '(testing))) - -;; @r{Here is how the minibuffer is displayed:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Enter an expression: (testing)@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -The user can type @key{RET} immediately to use the initial input as a -default, or can edit the input. -@end defun - -@defun eval-minibuffer prompt &optional initial -This function reads a Lisp expression using the minibuffer, evaluates -it, then returns the result. The arguments @var{prompt} and -@var{initial} are used as in @code{read-from-minibuffer}. - -This function simply evaluates the result of a call to -@code{read-minibuffer}: - -@smallexample -@group -(eval-minibuffer @var{prompt} @var{initial}) -@equiv{} -(eval (read-minibuffer @var{prompt} @var{initial})) -@end group -@end smallexample -@end defun - -@defun edit-and-eval-command prompt form -This function reads a Lisp expression in the minibuffer, evaluates it, -then returns the result. The difference between this command and -@code{eval-minibuffer} is that here the initial @var{form} is not -optional and it is treated as a Lisp object to be converted to printed -representation rather than as a string of text. It is printed with -@code{prin1}, so if it is a string, double-quote characters (@samp{"}) -appear in the initial text. @xref{Output Functions}. - -In the following example, we offer the user an expression with initial -text that is already a valid form: - -@smallexample -@group -(edit-and-eval-command "Please edit: " '(forward-word 1)) - -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Please edit: (forward-word 1)@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -Typing @key{RET} right away would exit the minibuffer and evaluate the -expression, thus moving point forward one word. -@end defun - -@node Minibuffer History -@section Minibuffer History -@cindex minibuffer history -@cindex history list - - A @dfn{minibuffer history list} records previous minibuffer inputs -so the user can reuse them conveniently. It is a variable whose value -is a list of strings (previous inputs), most recent first. - - There are many separate minibuffer history lists, used for different -kinds of inputs. It's the Lisp programmer's job to specify the right -history list for each use of the minibuffer. - - You specify a minibuffer history list with the optional @var{history} -argument to @code{read-from-minibuffer} or @code{completing-read}. -Here are the possible values for it: - -@table @asis -@item @var{variable} -Use @var{variable} (a symbol) as the history list. - -@item (@var{variable} . @var{startpos}) -Use @var{variable} (a symbol) as the history list, and assume that the -initial history position is @var{startpos} (a nonnegative integer). - -Specifying 0 for @var{startpos} is equivalent to just specifying the -symbol @var{variable}. @code{previous-history-element} will display -the most recent element of the history list in the minibuffer. If you -specify a positive @var{startpos}, the minibuffer history functions -behave as if @code{(elt @var{variable} (1- @var{startpos}))} were the -history element currently shown in the minibuffer. - -For consistency, you should also specify that element of the history -as the initial minibuffer contents, using the @var{initial} argument -to the minibuffer input function (@pxref{Initial Input}). -@end table - - If you don't specify @var{history}, then the default history list -@code{minibuffer-history} is used. For other standard history lists, -see below. You can also create your own history list variable; just -initialize it to @code{nil} before the first use. - - Both @code{read-from-minibuffer} and @code{completing-read} add new -elements to the history list automatically, and provide commands to -allow the user to reuse items on the list. The only thing your program -needs to do to use a history list is to initialize it and to pass its -name to the input functions when you wish. But it is safe to modify the -list by hand when the minibuffer input functions are not using it. - - Emacs functions that add a new element to a history list can also -delete old elements if the list gets too long. The variable -@code{history-length} specifies the maximum length for most history -lists. To specify a different maximum length for a particular history -list, put the length in the @code{history-length} property of the -history list symbol. The variable @code{history-delete-duplicates} -specifies whether to delete duplicates in history. - -@defun add-to-history history-var newelt &optional maxelt keep-all -This function adds a new element @var{newelt}, if it isn't the empty -string, to the history list stored in the variable @var{history-var}, -and returns the updated history list. It limits the list length to -the value of @var{maxelt} (if non-@code{nil}) or @code{history-length} -(described below). The possible values of @var{maxelt} have the same -meaning as the values of @code{history-length}. - -Normally, @code{add-to-history} removes duplicate members from the -history list if @code{history-delete-duplicates} is non-@code{nil}. -However, if @var{keep-all} is non-@code{nil}, that says not to remove -duplicates, and to add @var{newelt} to the list even if it is empty. -@end defun - -@defvar history-add-new-input -If the value of this variable is @code{nil}, standard functions that -read from the minibuffer don't add new elements to the history list. -This lets Lisp programs explicitly manage input history by using -@code{add-to-history}. The default value is @code{t}. -@end defvar - -@defopt history-length -The value of this variable specifies the maximum length for all -history lists that don't specify their own maximum lengths. If the -value is @code{t}, that means there is no maximum (don't delete old -elements). If a history list variable's symbol has a non-@code{nil} -@code{history-length} property, it overrides this variable for that -particular history list. -@end defopt - -@defopt history-delete-duplicates -If the value of this variable is @code{t}, that means when adding a -new history element, all previous identical elements are deleted. -@end defopt - - Here are some of the standard minibuffer history list variables: - -@defvar minibuffer-history -The default history list for minibuffer history input. -@end defvar - -@defvar query-replace-history -A history list for arguments to @code{query-replace} (and similar -arguments to other commands). -@end defvar - -@defvar file-name-history -A history list for file-name arguments. -@end defvar - -@defvar buffer-name-history -A history list for buffer-name arguments. -@end defvar - -@defvar regexp-history -A history list for regular expression arguments. -@end defvar - -@defvar extended-command-history -A history list for arguments that are names of extended commands. -@end defvar - -@defvar shell-command-history -A history list for arguments that are shell commands. -@end defvar - -@defvar read-expression-history -A history list for arguments that are Lisp expressions to evaluate. -@end defvar - -@defvar face-name-history -A history list for arguments that are faces. -@end defvar - -@c Less common: coding-system-history, input-method-history, -@c command-history, grep-history, grep-find-history, -@c read-envvar-name-history, setenv-history, yes-or-no-p-history. - -@node Initial Input -@section Initial Input - -Several of the functions for minibuffer input have an argument called -@var{initial}. This is a mostly-deprecated -feature for specifying that the minibuffer should start out with -certain text, instead of empty as usual. - -If @var{initial} is a string, the minibuffer starts out containing the -text of the string, with point at the end, when the user starts to -edit the text. If the user simply types @key{RET} to exit the -minibuffer, it will use the initial input string to determine the -value to return. - -@strong{We discourage use of a non-@code{nil} value for -@var{initial}}, because initial input is an intrusive interface. -History lists and default values provide a much more convenient method -to offer useful default inputs to the user. - -There is just one situation where you should specify a string for an -@var{initial} argument. This is when you specify a cons cell for the -@var{history} argument. @xref{Minibuffer History}. - -@var{initial} can also be a cons cell of the form @code{(@var{string} -. @var{position})}. This means to insert @var{string} in the -minibuffer but put point at @var{position} within the string's text. - -As a historical accident, @var{position} was implemented -inconsistently in different functions. In @code{completing-read}, -@var{position}'s value is interpreted as origin-zero; that is, a value -of 0 means the beginning of the string, 1 means after the first -character, etc. In @code{read-minibuffer}, and the other -non-completion minibuffer input functions that support this argument, -1 means the beginning of the string, 2 means after the first character, -etc. - -Use of a cons cell as the value for @var{initial} arguments is deprecated. - -@node Completion -@section Completion -@cindex completion - - @dfn{Completion} is a feature that fills in the rest of a name -starting from an abbreviation for it. Completion works by comparing the -user's input against a list of valid names and determining how much of -the name is determined uniquely by what the user has typed. For -example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then -@c "This is the sort of English up with which I will not put." -type the first few letters of the name of the buffer to which you wish -to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs -extends the name as far as it can. - - Standard Emacs commands offer completion for names of symbols, files, -buffers, and processes; with the functions in this section, you can -implement completion for other kinds of names. - - The @code{try-completion} function is the basic primitive for -completion: it returns the longest determined completion of a given -initial string, with a given set of strings to match against. - - The function @code{completing-read} provides a higher-level interface -for completion. A call to @code{completing-read} specifies how to -determine the list of valid names. The function then activates the -minibuffer with a local keymap that binds a few keys to commands useful -for completion. Other functions provide convenient simple interfaces -for reading certain kinds of names with completion. - -@menu -* Basic Completion:: Low-level functions for completing strings. -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer names, variable names, etc.). -* Reading File Names:: Using completion to read file names and - shell commands. -* Completion Variables:: Variables controlling completion behavior. -* Programmed Completion:: Writing your own completion function. -* Completion in Buffers:: Completing text in ordinary buffers. -@end menu - -@node Basic Completion -@subsection Basic Completion Functions - - The following completion functions have nothing in themselves to do -with minibuffers. We describe them here to keep them near the -higher-level completion features that do use the minibuffer. - -@defun try-completion string collection &optional predicate -This function returns the longest common substring of all possible -completions of @var{string} in @var{collection}. - -@cindex completion table -The @var{collection} argument is called the @dfn{completion table}. -Its value must be a list of strings, an alist whose keys are strings -or symbols, an obarray, a hash table, or a completion function. - -Completion compares @var{string} against each of the permissible -completions specified by @var{collection}. If no permissible -completions match, @code{try-completion} returns @code{nil}. If there -is just one matching completion, and the match is exact, it returns -@code{t}. Otherwise, it returns the longest initial sequence common -to all possible matching completions. - -If @var{collection} is an alist (@pxref{Association Lists}), the -permissible completions are the elements of the alist that are either -strings, or conses whose @sc{car} is a string or symbol. -Symbols are converted to strings using @code{symbol-name}. Other -elements of the alist are ignored. (Remember that in Emacs Lisp, the -elements of alists do not @emph{have} to be conses.) In particular, a -list of strings is allowed, even though we usually do not -think of such lists as alists. - -@cindex obarray in completion -If @var{collection} is an obarray (@pxref{Creating Symbols}), the names -of all symbols in the obarray form the set of permissible completions. - -If @var{collection} is a hash table, then the keys that are strings -are the possible completions. Other keys are ignored. - -You can also use a function as @var{collection}. Then the function is -solely responsible for performing completion; @code{try-completion} -returns whatever this function returns. The function is called with -three arguments: @var{string}, @var{predicate} and @code{nil} (the -third argument is so that the same function can be used -in @code{all-completions} and do the appropriate thing in either -case). @xref{Programmed Completion}. - -If the argument @var{predicate} is non-@code{nil}, then it must be a -function of one argument, unless @var{collection} is a hash table, in -which case it should be a function of two arguments. It is used to -test each possible match, and the match is accepted only if -@var{predicate} returns non-@code{nil}. The argument given to -@var{predicate} is either a string or a cons cell (the @sc{car} of -which is a string) from the alist, or a symbol (@emph{not} a symbol -name) from the obarray. If @var{collection} is a hash table, -@var{predicate} is called with two arguments, the string key and the -associated value. - -In addition, to be acceptable, a completion must also match all the -regular expressions in @code{completion-regexp-list}. (Unless -@var{collection} is a function, in which case that function has to -handle @code{completion-regexp-list} itself.) - -In the first of the following examples, the string @samp{foo} is -matched by three of the alist @sc{car}s. All of the matches begin with -the characters @samp{fooba}, so that is the result. In the second -example, there is only one possible match, and it is exact, so the -return value is @code{t}. - -@smallexample -@group -(try-completion - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) - @result{} "fooba" -@end group - -@group -(try-completion "foo" '(("barfoo" 2) ("foo" 3))) - @result{} t -@end group -@end smallexample - -In the following example, numerous symbols begin with the characters -@samp{forw}, and all of them begin with the word @samp{forward}. In -most of the symbols, this is followed with a @samp{-}, but not in all, -so no more than @samp{forward} can be completed. - -@smallexample -@group -(try-completion "forw" obarray) - @result{} "forward" -@end group -@end smallexample - -Finally, in the following example, only two of the three possible -matches pass the predicate @code{test} (the string @samp{foobaz} is -too short). Both of those begin with the string @samp{foobar}. - -@smallexample -@group -(defun test (s) - (> (length (car s)) 6)) - @result{} test -@end group -@group -(try-completion - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - 'test) - @result{} "foobar" -@end group -@end smallexample -@end defun - -@c Removed obsolete argument nospace. -@defun all-completions string collection &optional predicate -This function returns a list of all possible completions of -@var{string}. The arguments to this function -@c (aside from @var{nospace}) -are the same as those of @code{try-completion}, and it -uses @code{completion-regexp-list} in the same way that -@code{try-completion} does. - -@ignore -The optional argument @var{nospace} is obsolete. If it is -non-@code{nil}, completions that start with a space are ignored unless -@var{string} starts with a space. -@end ignore - -If @var{collection} is a function, it is called with three arguments: -@var{string}, @var{predicate} and @code{t}; then @code{all-completions} -returns whatever the function returns. @xref{Programmed Completion}. - -Here is an example, using the function @code{test} shown in the -example for @code{try-completion}: - -@smallexample -@group -(defun test (s) - (> (length (car s)) 6)) - @result{} test -@end group - -@group -(all-completions - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - 'test) - @result{} ("foobar1" "foobar2") -@end group -@end smallexample -@end defun - -@defun test-completion string collection &optional predicate -@anchor{Definition of test-completion} -This function returns non-@code{nil} if @var{string} is a valid -completion alternative specified by @var{collection} and -@var{predicate}. The arguments are the same as in -@code{try-completion}. For instance, if @var{collection} is a list of -strings, this is true if @var{string} appears in the list and -@var{predicate} is satisfied. - -This function uses @code{completion-regexp-list} in the same -way that @code{try-completion} does. - -If @var{predicate} is non-@code{nil} and if @var{collection} contains -several strings that are equal to each other, as determined by -@code{compare-strings} according to @code{completion-ignore-case}, -then @var{predicate} should accept either all or none of them. -Otherwise, the return value of @code{test-completion} is essentially -unpredictable. - -If @var{collection} is a function, it is called with three arguments, -the values @var{string}, @var{predicate} and @code{lambda}; whatever -it returns, @code{test-completion} returns in turn. -@end defun - -@defun completion-boundaries string collection predicate suffix -This function returns the boundaries of the field on which @var{collection} -will operate, assuming that @var{string} holds the text before point -and @var{suffix} holds the text after point. - -Normally completion operates on the whole string, so for all normal -collections, this will always return @code{(0 . (length -@var{suffix}))}. But more complex completion such as completion on -files is done one field at a time. For example, completion of -@code{"/usr/sh"} will include @code{"/usr/share/"} but not -@code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists. -Also @code{all-completions} on @code{"/usr/sh"} will not include -@code{"/usr/share/"} but only @code{"share/"}. So if @var{string} is -@code{"/usr/sh"} and @var{suffix} is @code{"e/doc"}, -@code{completion-boundaries} will return @code{(5 . 1)} which tells us -that the @var{collection} will only return completion information that -pertains to the area after @code{"/usr/"} and before @code{"/doc"}. -@end defun - -If you store a completion alist in a variable, you should mark the -variable as ``risky'' by giving it a non-@code{nil} -@code{risky-local-variable} property. @xref{File Local Variables}. - -@defvar completion-ignore-case -If the value of this variable is non-@code{nil}, case is not -considered significant in completion. Within @code{read-file-name}, -this variable is overridden by -@code{read-file-name-completion-ignore-case} (@pxref{Reading File -Names}); within @code{read-buffer}, it is overridden by -@code{read-buffer-completion-ignore-case} (@pxref{High-Level -Completion}). -@end defvar - -@defvar completion-regexp-list -This is a list of regular expressions. The completion functions only -consider a completion acceptable if it matches all regular expressions -in this list, with @code{case-fold-search} (@pxref{Searching and Case}) -bound to the value of @code{completion-ignore-case}. -@end defvar - -@defmac lazy-completion-table var fun -This macro provides a way to initialize the variable @var{var} as a -collection for completion in a lazy way, not computing its actual -contents until they are first needed. You use this macro to produce a -value that you store in @var{var}. The actual computation of the -proper value is done the first time you do completion using @var{var}. -It is done by calling @var{fun} with no arguments. The -value @var{fun} returns becomes the permanent value of @var{var}. - -Here is an example: - -@smallexample -(defvar foo (lazy-completion-table foo make-my-alist)) -@end smallexample -@end defmac - -@node Minibuffer Completion -@subsection Completion and the Minibuffer -@cindex minibuffer completion -@cindex reading from minibuffer with completion - - This section describes the basic interface for reading from the -minibuffer with completion. - -@defun completing-read prompt collection &optional predicate require-match initial history default inherit-input-method -This function reads a string in the minibuffer, assisting the user by -providing completion. It activates the minibuffer with prompt -@var{prompt}, which must be a string. - -The actual completion is done by passing the completion table -@var{collection} and the completion predicate @var{predicate} to the -function @code{try-completion} (@pxref{Basic Completion}). This -happens in certain commands bound in the local keymaps used for -completion. Some of these commands also call @code{test-completion}. -Thus, if @var{predicate} is non-@code{nil}, it should be compatible -with @var{collection} and @code{completion-ignore-case}. -@xref{Definition of test-completion}. - -The value of the optional argument @var{require-match} determines how -the user may exit the minibuffer: - -@itemize @bullet -@item -If @code{nil}, the usual minibuffer exit commands work regardless of -the input in the minibuffer. - -@item -If @code{t}, the usual minibuffer exit commands won't exit unless the -input completes to an element of @var{collection}. - -@item -If @code{confirm}, the user can exit with any input, but is asked for -confirmation if the input is not an element of @var{collection}. - -@item -If @code{confirm-after-completion}, the user can exit with any input, -but is asked for confirmation if the preceding command was a -completion command (i.e., one of the commands in -@code{minibuffer-confirm-exit-commands}) and the resulting input is -not an element of @var{collection}. @xref{Completion Commands}. - -@item -Any other value of @var{require-match} behaves like @code{t}, except -that the exit commands won't exit if it performs completion. -@end itemize - -However, empty input is always permitted, regardless of the value of -@var{require-match}; in that case, @code{completing-read} returns the -first element of @var{default}, if it is a list; @code{""}, if -@var{default} is @code{nil}; or @var{default}. The string or strings -in @var{default} are also available to the user through the history -commands. - -The function @code{completing-read} uses -@code{minibuffer-local-completion-map} as the keymap if -@var{require-match} is @code{nil}, and uses -@code{minibuffer-local-must-match-map} if @var{require-match} is -non-@code{nil}. @xref{Completion Commands}. - -The argument @var{history} specifies which history list variable to use for -saving the input and for minibuffer history commands. It defaults to -@code{minibuffer-history}. @xref{Minibuffer History}. - -The argument @var{initial} is mostly deprecated; we recommend using a -non-@code{nil} value only in conjunction with specifying a cons cell -for @var{history}. @xref{Initial Input}. For default input, use -@var{default} instead. - -If the argument @var{inherit-input-method} is non-@code{nil}, then the -minibuffer inherits the current input method (@pxref{Input -Methods}) and the setting of @code{enable-multibyte-characters} -(@pxref{Text Representations}) from whichever buffer was current before -entering the minibuffer. - -If the variable @code{completion-ignore-case} is -non-@code{nil}, completion ignores case when comparing the input -against the possible matches. @xref{Basic Completion}. In this mode -of operation, @var{predicate} must also ignore case, or you will get -surprising results. - -Here's an example of using @code{completing-read}: - -@smallexample -@group -(completing-read - "Complete a foo: " - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - nil t "fo") -@end group - -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} - ----------- Buffer: Minibuffer ---------- -Complete a foo: fo@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}}, -@code{completing-read} returns @code{barfoo}. - -The @code{completing-read} function binds variables to pass -information to the commands that actually do completion. -They are described in the following section. -@end defun - -@defvar completing-read-function -The value of this variable must be a function, which is called by -@code{completing-read} to actually do its work. It should accept the -same arguments as @code{completing-read}. This can be bound to a -different function to completely override the normal behavior of -@code{completing-read}. -@end defvar - -@node Completion Commands -@subsection Minibuffer Commands that Do Completion - - This section describes the keymaps, commands and user options used -in the minibuffer to do completion. - -@defvar minibuffer-completion-table -The value of this variable is the completion table used for completion -in the minibuffer. This is the global variable that contains what -@code{completing-read} passes to @code{try-completion}. It is used by -minibuffer completion commands such as -@code{minibuffer-complete-word}. -@end defvar - -@defvar minibuffer-completion-predicate -This variable's value is the predicate that @code{completing-read} -passes to @code{try-completion}. The variable is also used by the other -minibuffer completion functions. -@end defvar - -@defvar minibuffer-completion-confirm -This variable determines whether Emacs asks for confirmation before -exiting the minibuffer; @code{completing-read} binds this variable, -and the function @code{minibuffer-complete-and-exit} checks the value -before exiting. If the value is @code{nil}, confirmation is not -required. If the value is @code{confirm}, the user may exit with an -input that is not a valid completion alternative, but Emacs asks for -confirmation. If the value is @code{confirm-after-completion}, the -user may exit with an input that is not a valid completion -alternative, but Emacs asks for confirmation if the user submitted the -input right after any of the completion commands in -@code{minibuffer-confirm-exit-commands}. -@end defvar - -@defvar minibuffer-confirm-exit-commands -This variable holds a list of commands that cause Emacs to ask for -confirmation before exiting the minibuffer, if the @var{require-match} -argument to @code{completing-read} is @code{confirm-after-completion}. -The confirmation is requested if the user attempts to exit the -minibuffer immediately after calling any command in this list. -@end defvar - -@deffn Command minibuffer-complete-word -This function completes the minibuffer contents by at most a single -word. Even if the minibuffer contents have only one completion, -@code{minibuffer-complete-word} does not add any characters beyond the -first character that is not a word constituent. @xref{Syntax Tables}. -@end deffn - -@deffn Command minibuffer-complete -This function completes the minibuffer contents as far as possible. -@end deffn - -@deffn Command minibuffer-complete-and-exit -This function completes the minibuffer contents, and exits if -confirmation is not required, i.e., if -@code{minibuffer-completion-confirm} is @code{nil}. If confirmation -@emph{is} required, it is given by repeating this command -immediately---the command is programmed to work without confirmation -when run twice in succession. -@end deffn - -@deffn Command minibuffer-completion-help -This function creates a list of the possible completions of the -current minibuffer contents. It works by calling @code{all-completions} -using the value of the variable @code{minibuffer-completion-table} as -the @var{collection} argument, and the value of -@code{minibuffer-completion-predicate} as the @var{predicate} argument. -The list of completions is displayed as text in a buffer named -@file{*Completions*}. -@end deffn - -@defun display-completion-list completions &optional common-substring -This function displays @var{completions} to the stream in -@code{standard-output}, usually a buffer. (@xref{Read and Print}, for more -information about streams.) The argument @var{completions} is normally -a list of completions just returned by @code{all-completions}, but it -does not have to be. Each element may be a symbol or a string, either -of which is simply printed. It can also be a list of two strings, -which is printed as if the strings were concatenated. The first of -the two strings is the actual completion, the second string serves as -annotation. - -The argument @var{common-substring} is the prefix that is common to -all the completions. With normal Emacs completion, it is usually the -same as the string that was completed. @code{display-completion-list} -uses this to highlight text in the completion list for better visual -feedback. This is not needed in the minibuffer; for minibuffer -completion, you can pass @code{nil}. - -This function is called by @code{minibuffer-completion-help}. A -common way to use it is together with -@code{with-output-to-temp-buffer}, like this: - -@example -(with-output-to-temp-buffer "*Completions*" - (display-completion-list - (all-completions (buffer-string) my-alist) - (buffer-string))) -@end example -@end defun - -@defopt completion-auto-help -If this variable is non-@code{nil}, the completion commands -automatically display a list of possible completions whenever nothing -can be completed because the next character is not uniquely determined. -@end defopt - -@defvar minibuffer-local-completion-map -@code{completing-read} uses this value as the local keymap when an -exact match of one of the completions is not required. By default, this -keymap makes the following bindings: - -@table @asis -@item @kbd{?} -@code{minibuffer-completion-help} - -@item @key{SPC} -@code{minibuffer-complete-word} - -@item @key{TAB} -@code{minibuffer-complete} -@end table - -@noindent -and uses @code{minibuffer-local-map} as its parent keymap -(@pxref{Definition of minibuffer-local-map}). -@end defvar - -@defvar minibuffer-local-must-match-map -@code{completing-read} uses this value as the local keymap when an -exact match of one of the completions is required. Therefore, no keys -are bound to @code{exit-minibuffer}, the command that exits the -minibuffer unconditionally. By default, this keymap makes the following -bindings: - -@table @asis -@item @kbd{C-j} -@code{minibuffer-complete-and-exit} - -@item @key{RET} -@code{minibuffer-complete-and-exit} -@end table - -@noindent -and uses @code{minibuffer-local-completion-map} as its parent keymap. -@end defvar - -@defvar minibuffer-local-filename-completion-map -This is a sparse keymap that simply unbinds @key{SPC}; because -filenames can contain spaces. The function @code{read-file-name} -combines this keymap with either @code{minibuffer-local-completion-map} -or @code{minibuffer-local-must-match-map}. -@end defvar - - -@node High-Level Completion -@subsection High-Level Completion Functions - - This section describes the higher-level convenience functions for -reading certain sorts of names with completion. - - In most cases, you should not call these functions in the middle of a -Lisp function. When possible, do all minibuffer input as part of -reading the arguments for a command, in the @code{interactive} -specification. @xref{Defining Commands}. - -@defun read-buffer prompt &optional default require-match -This function reads the name of a buffer and returns it as a string. -The argument @var{default} is the default name to use, the value to -return if the user exits with an empty minibuffer. If non-@code{nil}, -it should be a string, a list of strings, or a buffer. If it is -a list, the default value is the first element of this list. It is -mentioned in the prompt, but is not inserted in the minibuffer as -initial input. - -The argument @var{prompt} should be a string ending with a colon and a -space. If @var{default} is non-@code{nil}, the function inserts it in -@var{prompt} before the colon to follow the convention for reading from -the minibuffer with a default value (@pxref{Programming Tips}). - -The optional argument @var{require-match} has the same meaning as in -@code{completing-read}. @xref{Minibuffer Completion}. - -In the following example, the user enters @samp{minibuffer.t}, and -then types @key{RET}. The argument @var{require-match} is @code{t}, -and the only buffer name starting with the given input is -@samp{minibuffer.texi}, so that name is the value. - -@example -(read-buffer "Buffer name: " "foo" t) -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Buffer name (default foo): @point{} ----------- Buffer: Minibuffer ---------- -@end group - -@group -;; @r{The user types @kbd{minibuffer.t @key{RET}}.} - @result{} "minibuffer.texi" -@end group -@end example -@end defun - -@defopt read-buffer-function -This variable specifies how to read buffer names. The function is -called with the arguments passed to @code{read-buffer}. For example, -if you set this variable to @code{iswitchb-read-buffer}, all Emacs -commands that call @code{read-buffer} to read a buffer name will -actually use the @code{iswitchb} package to read it. -@end defopt - -@defopt read-buffer-completion-ignore-case -If this variable is non-@code{nil}, @code{read-buffer} ignores case -when performing completion. -@end defopt - -@defun read-command prompt &optional default -This function reads the name of a command and returns it as a Lisp -symbol. The argument @var{prompt} is used as in -@code{read-from-minibuffer}. Recall that a command is anything for -which @code{commandp} returns @code{t}, and a command name is a symbol -for which @code{commandp} returns @code{t}. @xref{Interactive Call}. - -The argument @var{default} specifies what to return if the user enters -null input. It can be a symbol, a string or a list of strings. If it -is a string, @code{read-command} interns it before returning it. -If it is a list, @code{read-command} interns the first element of this list. -If @var{default} is @code{nil}, that means no default has been -specified; then if the user enters null input, the return value is -@code{(intern "")}, that is, a symbol whose name is an empty string. - -@example -(read-command "Command name? ") - -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Command name? ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -If the user types @kbd{forward-c @key{RET}}, then this function returns -@code{forward-char}. - -The @code{read-command} function is a simplified interface to -@code{completing-read}. It uses the variable @code{obarray} so as to -complete in the set of extant Lisp symbols, and it uses the -@code{commandp} predicate so as to accept only command names: - -@cindex @code{commandp} example -@example -@group -(read-command @var{prompt}) -@equiv{} -(intern (completing-read @var{prompt} obarray - 'commandp t nil)) -@end group -@end example -@end defun - -@defun read-variable prompt &optional default -@anchor{Definition of read-variable} -This function reads the name of a user variable and returns it as a -symbol. Its arguments have the same form as those of @code{read-command}. -In general, this function is similar to @code{read-command}, but uses -the predicate @code{user-variable-p} instead of @code{commandp}. -@end defun - -@deffn Command read-color &optional prompt convert allow-empty display -This function reads a string that is a color specification, either the -color's name or an RGB hex value such as @code{#RRRGGGBBB}. It -prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"}) -and provides completion for color names, but not for hex RGB values. -In addition to names of standard colors, completion candidates include -the foreground and background colors at point. - -Valid RGB values are described in @ref{Color Names}. - -The function's return value is the string typed by the user in the -minibuffer. However, when called interactively or if the optional -argument @var{convert} is non-@code{nil}, it converts any input color -name into the corresponding RGB value string and instead returns that. -This function requires a valid color specification to be input. -Empty color names are allowed when @var{allow-empty} is -non-@code{nil} and the user enters null input. - -Interactively, or when @var{display} is non-@code{nil}, the return -value is also displayed in the echo area. -@end deffn - - See also the functions @code{read-coding-system} and -@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}, -and @code{read-input-method-name}, in @ref{Input Methods}. - -@node Reading File Names -@subsection Reading File Names -@cindex read file names -@cindex prompt for file name - - The high-level completion functions @code{read-file-name}, -@code{read-directory-name}, and @code{read-shell-command} are designed -to read file names, directory names, and shell commands, respectively. -They provide special features, including automatic insertion of the -default directory. - -@defun read-file-name prompt &optional directory default require-match initial predicate -This function reads a file name, prompting with @var{prompt} and -providing completion. - -As an exception, this function reads a file name using a graphical -file dialog instead of the minibuffer, if all of the following are -true: - -@enumerate -@item -It is invoked via a mouse command. - -@item -The selected frame is on a graphical display supporting such dialogs. - -@item -The variable @code{use-dialog-box} is non-@code{nil}. -@xref{Dialog Boxes,, Dialog Boxes, emacs, The GNU Emacs Manual}. - -@item -The @var{directory} argument, described below, does not specify a -remote file. @xref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}. -@end enumerate - -@noindent -The exact behavior when using a graphical file dialog is -platform-dependent. Here, we simply document the behavior when using -the minibuffer. - -@code{read-file-name} does not automatically expand the returned file -name. You must call @code{expand-file-name} yourself if an absolute -file name is required. - -The optional argument @var{require-match} has the same meaning as in -@code{completing-read}. @xref{Minibuffer Completion}. - -The argument @var{directory} specifies the directory to use for -completing relative file names. It should be an absolute directory -name. If the variable @code{insert-default-directory} is non-@code{nil}, -@var{directory} is also inserted in the minibuffer as initial input. -It defaults to the current buffer's value of @code{default-directory}. - -If you specify @var{initial}, that is an initial file name to insert -in the buffer (after @var{directory}, if that is inserted). In this -case, point goes at the beginning of @var{initial}. The default for -@var{initial} is @code{nil}---don't insert any file name. To see what -@var{initial} does, try the command @kbd{C-x C-v} in a buffer visiting -a file. @strong{Please note:} we recommend using @var{default} rather -than @var{initial} in most cases. - -If @var{default} is non-@code{nil}, then the function returns -@var{default} if the user exits the minibuffer with the same non-empty -contents that @code{read-file-name} inserted initially. The initial -minibuffer contents are always non-empty if -@code{insert-default-directory} is non-@code{nil}, as it is by -default. @var{default} is not checked for validity, regardless of the -value of @var{require-match}. However, if @var{require-match} is -non-@code{nil}, the initial minibuffer contents should be a valid file -(or directory) name. Otherwise @code{read-file-name} attempts -completion if the user exits without any editing, and does not return -@var{default}. @var{default} is also available through the history -commands. - -If @var{default} is @code{nil}, @code{read-file-name} tries to find a -substitute default to use in its place, which it treats in exactly the -same way as if it had been specified explicitly. If @var{default} is -@code{nil}, but @var{initial} is non-@code{nil}, then the default is -the absolute file name obtained from @var{directory} and -@var{initial}. If both @var{default} and @var{initial} are @code{nil} -and the buffer is visiting a file, @code{read-file-name} uses the -absolute file name of that file as default. If the buffer is not -visiting a file, then there is no default. In that case, if the user -types @key{RET} without any editing, @code{read-file-name} simply -returns the pre-inserted contents of the minibuffer. - -If the user types @key{RET} in an empty minibuffer, this function -returns an empty string, regardless of the value of -@var{require-match}. This is, for instance, how the user can make the -current buffer visit no file using @kbd{M-x set-visited-file-name}. - -If @var{predicate} is non-@code{nil}, it specifies a function of one -argument that decides which file names are acceptable completion -alternatives. A file name is an acceptable value if @var{predicate} -returns non-@code{nil} for it. - -Here is an example of using @code{read-file-name}: - -@example -@group -(read-file-name "The file is ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is /gp/gnu/elisp/@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -Typing @kbd{manual @key{TAB}} results in the following: - -@example -@group ----------- Buffer: Minibuffer ---------- -The file is /gp/gnu/elisp/manual.texi@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@c Wordy to avoid overfull hbox in smallbook mode. -@noindent -If the user types @key{RET}, @code{read-file-name} returns the file name -as the string @code{"/gp/gnu/elisp/manual.texi"}. -@end defun - -@defvar read-file-name-function -If non-@code{nil}, this should be a function that accepts the same -arguments as @code{read-file-name}. When @code{read-file-name} is -called, it calls this function with the supplied arguments instead of -doing its usual work. -@end defvar - -@defopt read-file-name-completion-ignore-case -If this variable is non-@code{nil}, @code{read-file-name} ignores case -when performing completion. -@end defopt - -@defun read-directory-name prompt &optional directory default require-match initial -This function is like @code{read-file-name} but allows only directory -names as completion alternatives. - -If @var{default} is @code{nil} and @var{initial} is non-@code{nil}, -@code{read-directory-name} constructs a substitute default by -combining @var{directory} (or the current buffer's default directory -if @var{directory} is @code{nil}) and @var{initial}. If both -@var{default} and @var{initial} are @code{nil}, this function uses -@var{directory} as substitute default, or the current buffer's default -directory if @var{directory} is @code{nil}. -@end defun - -@defopt insert-default-directory -This variable is used by @code{read-file-name}, and thus, indirectly, -by most commands reading file names. (This includes all commands that -use the code letters @samp{f} or @samp{F} in their interactive form. -@xref{Interactive Codes,, Code Characters for interactive}.) Its -value controls whether @code{read-file-name} starts by placing the -name of the default directory in the minibuffer, plus the initial file -name, if any. If the value of this variable is @code{nil}, then -@code{read-file-name} does not place any initial input in the -minibuffer (unless you specify initial input with the @var{initial} -argument). In that case, the default directory is still used for -completion of relative file names, but is not displayed. - -If this variable is @code{nil} and the initial minibuffer contents are -empty, the user may have to explicitly fetch the next history element -to access a default value. If the variable is non-@code{nil}, the -initial minibuffer contents are always non-empty and the user can -always request a default value by immediately typing @key{RET} in an -unedited minibuffer. (See above.) - -For example: - -@example -@group -;; @r{Here the minibuffer starts out with the default directory.} -(let ((insert-default-directory t)) - (read-file-name "The file is ")) -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is ~lewis/manual/@point{} ----------- Buffer: Minibuffer ---------- -@end group - -@group -;; @r{Here the minibuffer is empty and only the prompt} -;; @r{appears on its line.} -(let ((insert-default-directory nil)) - (read-file-name "The file is ")) -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is @point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example -@end defopt - -@defun read-shell-command prompt &optional initial history &rest args -This function reads a shell command from the minibuffer, prompting -with @var{prompt} and providing intelligent completion. It completes -the first word of the command using candidates that are appropriate -for command names, and the rest of the command words as file names. - -This function uses @code{minibuffer-local-shell-command-map} as the -keymap for minibuffer input. The @var{history} argument specifies the -history list to use; if is omitted or @code{nil}, it defaults to -@code{shell-command-history} (@pxref{Minibuffer History, -shell-command-history}). The optional argument @var{initial} -specifies the initial content of the minibuffer (@pxref{Initial -Input}). The rest of @var{args}, if present, are used as the -@var{default} and @var{inherit-input-method} arguments in -@code{read-from-minibuffer} (@pxref{Text from Minibuffer}). -@end defun - -@defvar minibuffer-local-shell-command-map -This keymap is used by @code{read-shell-command} for completing -command and file names that are part of a shell command. It uses -@code{minibuffer-local-map} as its parent keymap, and binds @key{TAB} -to @code{completion-at-point}. -@end defvar - -@node Completion Variables -@subsection Completion Variables - - Here are some variables that can be used to alter the default -completion behavior. - -@cindex completion styles -@defopt completion-styles -The value of this variable is a list of completion style (symbols) to -use for performing completion. A @dfn{completion style} is a set of -rules for generating completions. Each symbol occurring this list -must have a corresponding entry in @code{completion-styles-alist}. -@end defopt - -@defvar completion-styles-alist -This variable stores a list of available completion styles. Each -element in the list has the form - -@example -(@var{style} @var{try-completion} @var{all-completions} @var{doc}) -@end example - -@noindent -Here, @var{style} is the name of the completion style (a symbol), -which may be used in the @code{completion-styles} variable to refer to -this style; @var{try-completion} is the function that does the -completion; @var{all-completions} is the function that lists the -completions; and @var{doc} is a string describing the completion -style. - -The @var{try-completion} and @var{all-completions} functions should -each accept four arguments: @var{string}, @var{collection}, -@var{predicate}, and @var{point}. The @var{string}, @var{collection}, -and @var{predicate} arguments have the same meanings as in -@code{try-completion} (@pxref{Basic Completion}), and the @var{point} -argument is the position of point within @var{string}. Each function -should return a non-@code{nil} value if it performed its job, and -@code{nil} if it did not (e.g.@: if there is no way to complete -@var{string} according to the completion style). - -When the user calls a completion command like -@code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks -for the first style listed in @code{completion-styles} and calls its -@var{try-completion} function. If this function returns @code{nil}, -Emacs moves to the next listed completion style and calls its -@var{try-completion} function, and so on until one of the -@var{try-completion} functions successfully performs completion and -returns a non-@code{nil} value. A similar procedure is used for -listing completions, via the @var{all-completions} functions. - -@xref{Completion Styles,,, emacs, The GNU Emacs Manual}, for a -description of the available completion styles. -@end defvar - -@defopt completion-category-overrides -This variable specifies special completion styles and other completion -behaviors to use when completing certain types of text. Its value -should be an alist with elements of the form @code{(@var{category} -. @var{alist})}. @var{category} is a symbol describing what is being -completed; currently, the @code{buffer}, @code{file}, and -@code{unicode-name} categories are defined, but others can be defined -via specialized completion functions (@pxref{Programmed Completion}). -@var{alist} is an association list describing how completion should -behave for the corresponding category. The following alist keys are -supported: - -@table @code -@item styles -The value should be a list of completion styles (symbols). - -@item cycle -The value should be a value for @code{completion-cycle-threshold} -(@pxref{Completion Options,,, emacs, The GNU Emacs Manual}) for this -category. -@end table - -@noindent -Additional alist entries may be defined in the future. -@end defopt - -@defvar completion-extra-properties -This variable is used to specify extra properties of the current -completion command. It is intended to be let-bound by specialized -completion commands. Its value should be a list of property and value -pairs. The following properties are supported: - -@table @code -@item :annotation-function -The value should be a function to add annotations in the completions -buffer. This function must accept one argument, a completion, and -should either return @code{nil} or a string to be displayed next to -the completion. - -@item :exit-function -The value should be a function to run after performing completion. -The function should accept two arguments, @var{string} and -@var{status}, where @var{string} is the text to which the field was -completed, and @var{status} indicates what kind of operation happened: -@code{finished} if text is now complete, @code{sole} if the text -cannot be further completed but completion is not finished, or -@code{exact} if the text is a valid completion but may be further -completed. -@end table -@end defvar - -@node Programmed Completion -@subsection Programmed Completion -@cindex programmed completion - - Sometimes it is not possible or convenient to create an alist or -an obarray containing all the intended possible completions ahead -of time. In such a case, you can supply your own function to compute -the completion of a given string. This is called @dfn{programmed -completion}. Emacs uses programmed completion when completing file -names (@pxref{File Name Completion}), among many other cases. - - To use this feature, pass a function as the @var{collection} -argument to @code{completing-read}. The function -@code{completing-read} arranges to pass your completion function along -to @code{try-completion}, @code{all-completions}, and other basic -completion functions, which will then let your function do all -the work. - - The completion function should accept three arguments: - -@itemize @bullet -@item -The string to be completed. - -@item -A predicate function with which to filter possible matches, or -@code{nil} if none. The function should call the predicate for each -possible match, and ignore the match if the predicate returns -@code{nil}. - -@item -A flag specifying the type of completion operation to perform. This -is one of the following four values: - -@table @code -@item nil -This specifies a @code{try-completion} operation. The function should -return @code{t} if the specified string is a unique and exact match; -if there is more than one match, it should return the common substring -of all matches (if the string is an exact match for one completion -alternative but also matches other longer alternatives, the return -value is the string); if there are no matches, it should return -@code{nil}. - -@item t -This specifies an @code{all-completions} operation. The function -should return a list of all possible completions of the specified -string. - -@item lambda -This specifies a @code{test-completion} operation. The function -should return @code{t} if the specified string is an exact match for -some completion alternative; @code{nil} otherwise. - -@item (boundaries . @var{suffix}) -This specifies a @code{completion-boundaries} operation. The function -should return @code{(boundaries @var{start} . @var{end})}, where -@var{start} is the position of the beginning boundary in the specified -string, and @var{end} is the position of the end boundary in -@var{suffix}. - -@item metadata -This specifies a request for information about the state of the -current completion. The function should return an alist, as described -below. The alist may contain any number of elements. -@end table - -@noindent -If the flag has any other value, the completion function should return -@code{nil}. -@end itemize - -The following is a list of metadata entries that a completion function -may return in response to a @code{metadata} flag argument: - -@table @code -@item category -The value should be a symbol describing what kind of text the -completion function is trying to complete. If the symbol matches one -of the keys in @code{completion-category-overrides}, the usual -completion behavior is overridden. @xref{Completion Variables}. - -@item annotation-function -The value should be a function for @dfn{annotating} completions. The -function should take one argument, @var{string}, which is a possible -completion. It should return a string, which is displayed after the -completion @var{string} in the @file{*Completions*} buffer. - -@item display-sort-function -The value should be a function for sorting completions. The function -should take one argument, a list of completion strings, and return a -sorted list of completion strings. It is allowed to alter the input -list destructively. - -@item cycle-sort-function -The value should be a function for sorting completions, when -@code{completion-cycle-threshold} is non-@code{nil} and the user is -cycling through completion alternatives. @xref{Completion Options,,, -emacs, The GNU Emacs Manual}. Its argument list and return value are -the same as for @code{display-sort-function}. -@end table - -@defun completion-table-dynamic function -This function is a convenient way to write a function that can act as -a programmed completion function. The argument @var{function} should be -a function that takes one argument, a string, and returns an alist of -possible completions of it. You can think of -@code{completion-table-dynamic} as a transducer between that interface -and the interface for programmed completion functions. -@end defun - -@node Completion in Buffers -@subsection Completion in Ordinary Buffers -@cindex inline completion - -@findex completion-at-point - Although completion is usually done in the minibuffer, the -completion facility can also be used on the text in ordinary Emacs -buffers. In many major modes, in-buffer completion is performed by -the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to -@code{completion-at-point}. @xref{Symbol Completion,,, emacs, The GNU -Emacs Manual}. This command uses the abnormal hook variable -@code{completion-at-point-functions}: - -@defvar completion-at-point-functions -The value of this abnormal hook should be a list of functions, which -are used to compute a completion table for completing the text at -point. It can be used by major modes to provide mode-specific -completion tables (@pxref{Major Mode Conventions}). - -When the command @code{completion-at-point} runs, it calls the -functions in the list one by one, without any argument. Each function -should return @code{nil} if it is unable to produce a completion table -for the text at point. Otherwise it should return a list of the form - -@example -(@var{start} @var{end} @var{collection} . @var{props}) -@end example - -@noindent -@var{start} and @var{end} delimit the text to complete (which should -enclose point). @var{collection} is a completion table for completing -that text, in a form suitable for passing as the second argument to -@code{try-completion} (@pxref{Basic Completion}); completion -alternatives will be generated from this completion table in the usual -way, via the completion styles defined in @code{completion-styles} -(@pxref{Completion Variables}). @var{props} is a property list for -additional information; any of the properties in -@code{completion-extra-properties} are recognized (@pxref{Completion -Variables}), as well as the following additional ones: - -@table @code -@item :predicate -The value should be a predicate that completion candidates need to -satisfy. - -@item :exclusive -If the value is @code{no}, then if the completion table fails to match -the text at point, @code{completion-at-point} moves on to the -next function in @code{completion-at-point-functions} instead of -reporting a completion failure. -@end table - -A function in @code{completion-at-point-functions} may also return a -function. In that case, that returned function is called, with no -argument, and it is entirely responsible for performing the -completion. We discourage this usage; it is intended to help convert -old code to using @code{completion-at-point}. - -The first function in @code{completion-at-point-functions} to return a -non-@code{nil} value is used by @code{completion-at-point}. The -remaining functions are not called. The exception to this is when -there is an @code{:exclusive} specification, as described above. -@end defvar - - The following function provides a convenient way to perform -completion on an arbitrary stretch of text in an Emacs buffer: - -@defun completion-in-region start end collection &optional predicate -This function completes the text in the current buffer between the -positions @var{start} and @var{end}, using @var{collection}. The -argument @var{collection} has the same meaning as in -@code{try-completion} (@pxref{Basic Completion}). - -This function inserts the completion text directly into the current -buffer. Unlike @code{completing-read} (@pxref{Minibuffer -Completion}), it does not activate the minibuffer. - -For this function to work, point must be somewhere between @var{start} -and @var{end}. -@end defun - - -@node Yes-or-No Queries -@section Yes-or-No Queries -@cindex asking the user questions -@cindex querying the user -@cindex yes-or-no questions - - This section describes functions used to ask the user a yes-or-no -question. The function @code{y-or-n-p} can be answered with a single -character; it is useful for questions where an inadvertent wrong answer -will not have serious consequences. @code{yes-or-no-p} is suitable for -more momentous questions, since it requires three or four characters to -answer. - - If either of these functions is called in a command that was invoked -using the mouse---more precisely, if @code{last-nonmenu-event} -(@pxref{Command Loop Info}) is either @code{nil} or a list---then it -uses a dialog box or pop-up menu to ask the question. Otherwise, it -uses keyboard input. You can force use either of the mouse or of keyboard -input by binding @code{last-nonmenu-event} to a suitable value around -the call. - - Strictly speaking, @code{yes-or-no-p} uses the minibuffer and -@code{y-or-n-p} does not; but it seems best to describe them together. - -@defun y-or-n-p prompt -This function asks the user a question, expecting input in the echo -area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the -user types @kbd{n}. This function also accepts @key{SPC} to mean yes -and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like -@kbd{C-g}, because the question might look like a minibuffer and for -that reason the user might try to use @kbd{C-]} to get out. The answer -is a single character, with no @key{RET} needed to terminate it. Upper -and lower case are equivalent. - -``Asking the question'' means printing @var{prompt} in the echo area, -followed by the string @w{@samp{(y or n) }}. If the input is not one of -the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}}, -@kbd{@key{DEL}}, or something that quits), the function responds -@samp{Please answer y or n.}, and repeats the request. - -This function does not actually use the minibuffer, since it does not -allow editing of the answer. It actually uses the echo area (@pxref{The -Echo Area}), which uses the same screen space as the minibuffer. The -cursor moves to the echo area while the question is being asked. - -The answers and their meanings, even @samp{y} and @samp{n}, are not -hardwired. The keymap @code{query-replace-map} specifies them. -@xref{Search and Replace}. - -In the following example, the user first types @kbd{q}, which is -invalid. At the next prompt the user types @kbd{y}. - -@c Need an interactive example, because otherwise the return value -@c obscures the display of the valid answer. -@smallexample -@group -(defun ask () - (interactive) - (y-or-n-p "Do you need a lift? ")) - -;; @r{After evaluation of the preceding definition, @kbd{M-x ask}} -;; @r{causes the following prompt to appear in the echo area:} -@end group - -@group ----------- Echo area ---------- -Do you need a lift? (y or n) ----------- Echo area ---------- -@end group - -;; @r{If the user then types @kbd{q}, the following appears:} - -@group ----------- Echo area ---------- -Please answer y or n. Do you need a lift? (y or n) ----------- Echo area ---------- -@end group - -;; @r{When the user types a valid answer,} -;; @r{it is displayed after the question:} - -@group ----------- Echo area ---------- -Do you need a lift? (y or n) y ----------- Echo area ---------- -@end group -@end smallexample - -@noindent -We show successive lines of echo area messages, but only one actually -appears on the screen at a time. -@end defun - -@defun y-or-n-p-with-timeout prompt seconds default -Like @code{y-or-n-p}, except that if the user fails to answer within -@var{seconds} seconds, this function stops waiting and returns -@var{default}. It works by setting up a timer; see @ref{Timers}. -The argument @var{seconds} may be an integer or a floating point number. -@end defun - -@defun yes-or-no-p prompt -This function asks the user a question, expecting input in the -minibuffer. It returns @code{t} if the user enters @samp{yes}, -@code{nil} if the user types @samp{no}. The user must type @key{RET} to -finalize the response. Upper and lower case are equivalent. - -@code{yes-or-no-p} starts by displaying @var{prompt} in the echo area, -followed by @w{@samp{(yes or no) }}. The user must type one of the -expected responses; otherwise, the function responds @samp{Please answer -yes or no.}, waits about two seconds and repeats the request. - -@code{yes-or-no-p} requires more work from the user than -@code{y-or-n-p} and is appropriate for more crucial decisions. - -Here is an example: - -@smallexample -@group -(yes-or-no-p "Do you really want to remove everything? ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: minibuffer ---------- -Do you really want to remove everything? (yes or no) ----------- Buffer: minibuffer ---------- -@end group -@end smallexample - -@noindent -If the user first types @kbd{y @key{RET}}, which is invalid because this -function demands the entire word @samp{yes}, it responds by displaying -these prompts, with a brief pause between them: - -@smallexample -@group ----------- Buffer: minibuffer ---------- -Please answer yes or no. -Do you really want to remove everything? (yes or no) ----------- Buffer: minibuffer ---------- -@end group -@end smallexample -@end defun - -@node Multiple Queries -@section Asking Multiple Y-or-N Questions - - When you have a series of similar questions to ask, such as ``Do you -want to save this buffer'' for each buffer in turn, you should use -@code{map-y-or-n-p} to ask the collection of questions, rather than -asking each question individually. This gives the user certain -convenient facilities such as the ability to answer the whole series at -once. - -@defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area -This function asks the user a series of questions, reading a -single-character answer in the echo area for each one. - -The value of @var{list} specifies the objects to ask questions about. -It should be either a list of objects or a generator function. If it is -a function, it should expect no arguments, and should return either the -next object to ask about, or @code{nil}, meaning to stop asking questions. - -The argument @var{prompter} specifies how to ask each question. If -@var{prompter} is a string, the question text is computed like this: - -@example -(format @var{prompter} @var{object}) -@end example - -@noindent -where @var{object} is the next object to ask about (as obtained from -@var{list}). - -If not a string, @var{prompter} should be a function of one argument -(the next object to ask about) and should return the question text. If -the value is a string, that is the question to ask the user. The -function can also return @code{t}, meaning do act on this object (and -don't ask the user), or @code{nil}, meaning ignore this object (and don't -ask the user). - -The argument @var{actor} says how to act on the answers that the user -gives. It should be a function of one argument, and it is called with -each object that the user says yes for. Its argument is always an -object obtained from @var{list}. - -If the argument @var{help} is given, it should be a list of this form: - -@example -(@var{singular} @var{plural} @var{action}) -@end example - -@noindent -where @var{singular} is a string containing a singular noun that -describes the objects conceptually being acted on, @var{plural} is the -corresponding plural noun, and @var{action} is a transitive verb -describing what @var{actor} does. - -If you don't specify @var{help}, the default is @code{("object" -"objects" "act on")}. - -Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or -@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip -that object; @kbd{!} to act on all following objects; @key{ESC} or -@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on -the current object and then exit; or @kbd{C-h} to get help. These are -the same answers that @code{query-replace} accepts. The keymap -@code{query-replace-map} defines their meaning for @code{map-y-or-n-p} -as well as for @code{query-replace}; see @ref{Search and Replace}. - -You can use @var{action-alist} to specify additional possible answers -and what they mean. It is an alist of elements of the form -@code{(@var{char} @var{function} @var{help})}, each of which defines one -additional answer. In this element, @var{char} is a character (the -answer); @var{function} is a function of one argument (an object from -@var{list}); @var{help} is a string. - -When the user responds with @var{char}, @code{map-y-or-n-p} calls -@var{function}. If it returns non-@code{nil}, the object is considered -``acted upon'', and @code{map-y-or-n-p} advances to the next object in -@var{list}. If it returns @code{nil}, the prompt is repeated for the -same object. - -Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while -prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it -does not do that. - -If @code{map-y-or-n-p} is called in a command that was invoked using the -mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command -Loop Info}) is either @code{nil} or a list---then it uses a dialog box -or pop-up menu to ask the question. In this case, it does not use -keyboard input or the echo area. You can force use either of the mouse or -of keyboard input by binding @code{last-nonmenu-event} to a suitable -value around the call. - -The return value of @code{map-y-or-n-p} is the number of objects acted on. -@end defun -@c FIXME An example of this would be more useful than all the -@c preceding examples of simple things. - -@node Reading a Password -@section Reading a Password -@cindex passwords, reading - - To read a password to pass to another program, you can use the -function @code{read-passwd}. - -@defun read-passwd prompt &optional confirm default -This function reads a password, prompting with @var{prompt}. It does -not echo the password as the user types it; instead, it echoes @samp{.} -for each character in the password. - -The optional argument @var{confirm}, if non-@code{nil}, says to read the -password twice and insist it must be the same both times. If it isn't -the same, the user has to type it over and over until the last two -times match. - -The optional argument @var{default} specifies the default password to -return if the user enters empty input. If @var{default} is @code{nil}, -then @code{read-passwd} returns the null string in that case. -@end defun - -@node Minibuffer Commands -@section Minibuffer Commands - - This section describes some commands meant for use in the -minibuffer. - -@deffn Command exit-minibuffer -This command exits the active minibuffer. It is normally bound to -keys in minibuffer local keymaps. -@end deffn - -@deffn Command self-insert-and-exit -This command exits the active minibuffer after inserting the last -character typed on the keyboard (found in @code{last-command-event}; -@pxref{Command Loop Info}). -@end deffn - -@deffn Command previous-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th previous (older) history element. -@end deffn - -@deffn Command next-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th more recent history element. -@end deffn - -@deffn Command previous-matching-history-element pattern n -This command replaces the minibuffer contents with the value of the -@var{n}th previous (older) history element that matches @var{pattern} (a -regular expression). -@end deffn - -@deffn Command next-matching-history-element pattern n -This command replaces the minibuffer contents with the value of the -@var{n}th next (newer) history element that matches @var{pattern} (a -regular expression). -@end deffn - -@deffn Command previous-complete-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th previous (older) history element that completes the current -contents of the minibuffer before the point. -@end deffn - -@deffn Command next-complete-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th next (newer) history element that completes the current -contents of the minibuffer before the point. -@end deffn - - -@node Minibuffer Windows -@section Minibuffer Windows -@cindex minibuffer windows - - These functions access and select minibuffer windows -and test whether they are active. - -@defun active-minibuffer-window -This function returns the currently active minibuffer window, or -@code{nil} if there is none. -@end defun - -@defun minibuffer-window &optional frame -@anchor{Definition of minibuffer-window} -This function returns the minibuffer window used for frame @var{frame}. -If @var{frame} is @code{nil}, that stands for the current frame. Note -that the minibuffer window used by a frame need not be part of that -frame---a frame that has no minibuffer of its own necessarily uses some -other frame's minibuffer window. -@end defun - -@defun set-minibuffer-window window -This function specifies @var{window} as the minibuffer window to use. -This affects where the minibuffer is displayed if you put text in it -without invoking the usual minibuffer commands. It has no effect on -the usual minibuffer input functions because they all start by -choosing the minibuffer window according to the current frame. -@end defun - -@c Emacs 19 feature -@defun window-minibuffer-p &optional window -This function returns non-@code{nil} if @var{window} is a minibuffer -window. -@var{window} defaults to the selected window. -@end defun - -It is not correct to determine whether a given window is a minibuffer by -comparing it with the result of @code{(minibuffer-window)}, because -there can be more than one minibuffer window if there is more than one -frame. - -@defun minibuffer-window-active-p window -This function returns non-@code{nil} if @var{window} is the currently -active minibuffer window. -@end defun - -@node Minibuffer Contents -@section Minibuffer Contents - - These functions access the minibuffer prompt and contents. - -@defun minibuffer-prompt -This function returns the prompt string of the currently active -minibuffer. If no minibuffer is active, it returns @code{nil}. -@end defun - -@defun minibuffer-prompt-end -This function returns the current -position of the end of the minibuffer prompt, if a minibuffer is -current. Otherwise, it returns the minimum valid buffer position. -@end defun - -@defun minibuffer-prompt-width -This function returns the current display-width of the minibuffer -prompt, if a minibuffer is current. Otherwise, it returns zero. -@end defun - -@defun minibuffer-contents -This function returns the editable -contents of the minibuffer (that is, everything except the prompt) as -a string, if a minibuffer is current. Otherwise, it returns the -entire contents of the current buffer. -@end defun - -@defun minibuffer-contents-no-properties -This is like @code{minibuffer-contents}, except that it does not copy text -properties, just the characters themselves. @xref{Text Properties}. -@end defun - -@defun minibuffer-completion-contents -This is like @code{minibuffer-contents}, except that it returns only -the contents before point. That is the part that completion commands -operate on. @xref{Minibuffer Completion}. -@end defun - -@defun delete-minibuffer-contents -This function erases the editable contents of the minibuffer (that is, -everything except the prompt), if a minibuffer is current. Otherwise, -it erases the entire current buffer. -@end defun - -@node Recursive Mini -@section Recursive Minibuffers -@cindex recursive minibuffers - - These functions and variables deal with recursive minibuffers -(@pxref{Recursive Editing}): - -@defun minibuffer-depth -This function returns the current depth of activations of the -minibuffer, a nonnegative integer. If no minibuffers are active, it -returns zero. -@end defun - -@defopt enable-recursive-minibuffers -If this variable is non-@code{nil}, you can invoke commands (such as -@code{find-file}) that use minibuffers even while the minibuffer window -is active. Such invocation produces a recursive editing level for a new -minibuffer. The outer-level minibuffer is invisible while you are -editing the inner one. - -If this variable is @code{nil}, you cannot invoke minibuffer -commands when the minibuffer window is active, not even if you switch to -another window to do it. -@end defopt - -@c Emacs 19 feature -If a command name has a property @code{enable-recursive-minibuffers} -that is non-@code{nil}, then the command can use the minibuffer to read -arguments even if it is invoked from the minibuffer. A command can -also achieve this by binding @code{enable-recursive-minibuffers} -to @code{t} in the interactive declaration (@pxref{Using Interactive}). -The minibuffer command @code{next-matching-history-element} (normally -@kbd{M-s} in the minibuffer) does the latter. - -@node Minibuffer Misc -@section Minibuffer Miscellany - -@defun minibufferp &optional buffer-or-name -This function returns non-@code{nil} if @var{buffer-or-name} is a -minibuffer. If @var{buffer-or-name} is omitted, it tests the current -buffer. -@end defun - -@defvar minibuffer-setup-hook -This is a normal hook that is run whenever the minibuffer is entered. -@xref{Hooks}. -@end defvar - -@defvar minibuffer-exit-hook -This is a normal hook that is run whenever the minibuffer is exited. -@xref{Hooks}. -@end defvar - -@defvar minibuffer-help-form -@anchor{Definition of minibuffer-help-form} -The current value of this variable is used to rebind @code{help-form} -locally inside the minibuffer (@pxref{Help Functions}). -@end defvar - -@defvar minibuffer-scroll-window -@anchor{Definition of minibuffer-scroll-window} -If the value of this variable is non-@code{nil}, it should be a window -object. When the function @code{scroll-other-window} is called in the -minibuffer, it scrolls this window. -@end defvar - -@defun minibuffer-selected-window -This function returns the window that was selected when the -minibuffer was entered. If selected window is not a minibuffer -window, it returns @code{nil}. -@end defun - -@defopt max-mini-window-height -This variable specifies the maximum height for resizing minibuffer -windows. If a float, it specifies a fraction of the height of the -frame. If an integer, it specifies a number of lines. -@end defopt - -@vindex minibuffer-message-timeout -@defun minibuffer-message string &rest args -This function displays @var{string} temporarily at the end of the -minibuffer text, for a few seconds, or until the next input event -arrives, whichever comes first. The variable -@code{minibuffer-message-timeout} specifies the number of seconds to -wait in the absence of input. It defaults to 2. If @var{args} is -non-@code{nil}, the actual message is obtained by passing @var{string} -and @var{args} through @code{format}. @xref{Formatting Strings}. -@end defun - -@deffn Command minibuffer-inactive-mode -This is the major mode used in inactive minibuffers. It uses -keymap @code{minibuffer-inactive-mode-map}. This can be useful -if the minibuffer is in a separate frame. @xref{Minibuffers and Frames}. -@end deffn diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi deleted file mode 100644 index 83a38b60bca..00000000000 --- a/doc/lispref/modes.texi +++ /dev/null @@ -1,4038 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/modes -@node Modes, Documentation, Keymaps, Top -@chapter Major and Minor Modes -@cindex mode - - A @dfn{mode} is a set of definitions that customize Emacs and can be -turned on and off while you edit. There are two varieties of modes: -@dfn{major modes}, which are mutually exclusive and used for editing -particular kinds of text, and @dfn{minor modes}, which provide features -that users can enable individually. - - This chapter describes how to write both major and minor modes, how to -indicate them in the mode line, and how they run hooks supplied by the -user. For related topics such as keymaps and syntax tables, see -@ref{Keymaps}, and @ref{Syntax Tables}. - -@menu -* Hooks:: How to use hooks; how to write code that provides hooks. -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Imenu:: Providing a menu of definitions made in a buffer. -* Font Lock Mode:: How modes can highlight text according to syntax. -* Auto-Indentation:: How to teach Emacs to indent for a major mode. -* Desktop Save Mode:: How modes can have buffer state saved between - Emacs sessions. -@end menu - -@node Hooks -@section Hooks -@cindex hooks - - A @dfn{hook} is a variable where you can store a function or functions -to be called on a particular occasion by an existing program. Emacs -provides hooks for the sake of customization. Most often, hooks are set -up in the init file (@pxref{Init File}), but Lisp programs can set them also. -@xref{Standard Hooks}, for a list of some standard hook variables. - -@cindex normal hook - Most of the hooks in Emacs are @dfn{normal hooks}. These variables -contain lists of functions to be called with no arguments. By -convention, whenever the hook name ends in @samp{-hook}, that tells -you it is normal. We try to make all hooks normal, as much as -possible, so that you can use them in a uniform way. - - Every major mode command is supposed to run a normal hook called the -@dfn{mode hook} as one of the last steps of initialization. This makes -it easy for a user to customize the behavior of the mode, by overriding -the buffer-local variable assignments already made by the mode. Most -minor mode functions also run a mode hook at the end. But hooks are -used in other contexts too. For example, the hook @code{suspend-hook} -runs just before Emacs suspends itself (@pxref{Suspending Emacs}). - - The recommended way to add a hook function to a hook is by calling -@code{add-hook} (@pxref{Setting Hooks}). The hook functions may be any -of the valid kinds of functions that @code{funcall} accepts (@pxref{What -Is a Function}). Most normal hook variables are initially void; -@code{add-hook} knows how to deal with this. You can add hooks either -globally or buffer-locally with @code{add-hook}. - -@cindex abnormal hook - If the hook variable's name does not end with @samp{-hook}, that -indicates it is probably an @dfn{abnormal hook}. That means the hook -functions are called with arguments, or their return values are used -in some way. The hook's documentation says how the functions are -called. You can use @code{add-hook} to add a function to an abnormal -hook, but you must write the function to follow the hook's calling -convention. - - By convention, abnormal hook names end in @samp{-functions} or -@samp{-hooks}. If the variable's name ends in @samp{-function}, then -its value is just a single function, not a list of functions. - -@menu -* Running Hooks:: How to run a hook. -* Setting Hooks:: How to put functions on a hook, or remove them. -@end menu - -@node Running Hooks -@subsection Running Hooks - - In this section, we document the @code{run-hooks} function, which is -used to run a normal hook. We also document the functions for running -various kinds of abnormal hooks. - -@defun run-hooks &rest hookvars -This function takes one or more normal hook variable names as -arguments, and runs each hook in turn. Each argument should be a -symbol that is a normal hook variable. These arguments are processed -in the order specified. - -If a hook variable has a non-@code{nil} value, that value should be a -list of functions. @code{run-hooks} calls all the functions, one by -one, with no arguments. - -The hook variable's value can also be a single function---either a -lambda expression or a symbol with a function definition---which -@code{run-hooks} calls. But this usage is obsolete. - -If the hook variable is buffer-local, the buffer-local variable will -be used instead of the global variable. However, if the buffer-local -variable contains the element @code{t}, the global hook variable will -be run as well. -@end defun - -@defun run-hook-with-args hook &rest args -This function runs an abnormal hook by calling all the hook functions in -@var{hook}, passing each one the arguments @var{args}. -@end defun - -@defun run-hook-with-args-until-failure hook &rest args -This function runs an abnormal hook by calling each hook function in -turn, stopping if one of them ``fails'' by returning @code{nil}. Each -hook function is passed the arguments @var{args}. If this function -stops because one of the hook functions fails, it returns @code{nil}; -otherwise it returns a non-@code{nil} value. -@end defun - -@defun run-hook-with-args-until-success hook &rest args -This function runs an abnormal hook by calling each hook function, -stopping if one of them ``succeeds'' by returning a non-@code{nil} -value. Each hook function is passed the arguments @var{args}. If this -function stops because one of the hook functions returns a -non-@code{nil} value, it returns that value; otherwise it returns -@code{nil}. -@end defun - -@defmac with-wrapper-hook hook args &rest body -This macro runs the abnormal hook @code{hook} as a series of nested -``wrapper functions'' around the @var{body} forms. The effect is -similar to nested @code{around} advices (@pxref{Around-Advice}). - -Each hook function should accept an argument list consisting of a function -@var{fun}, followed by the additional arguments listed in @var{args}. -The first hook function is passed a function @var{fun} that, if it is -called with arguments @var{args}, performs @var{body} (i.e., the default -operation). The @var{fun} passed to each successive hook function is -constructed from all the preceding hook functions (and @var{body}); if -this @var{fun} is called with arguments @var{args}, it does what the -@code{with-wrapper-hook} call would if the preceding hook functions were -the only ones in @var{hook}. - -Each hook function may call its @var{fun} argument as many times as it -wishes, including never. In that case, such a hook function acts to -replace the default definition altogether, and any preceding hook -functions. Of course, a subsequent hook function may do the same thing. - -Each hook function definition is used to construct the @var{fun} passed -to the next hook function in @var{hook}, if any. The last or -``outermost'' @var{fun} is called once to produce the overall effect. - -When might you want to use a wrapper hook? The function -@code{filter-buffer-substring} illustrates a common case. There is a -basic functionality, performed by @var{body}---in this case, to extract -a buffer-substring. Then any number of hook functions can act in -sequence to modify that string, before returning the final result. -A wrapper-hook also allows for a hook function to completely replace the -default definition (by not calling @var{fun}). -@end defmac - -@defun run-hook-wrapped hook wrap-function &rest args -This function is similar to @code{run-hook-with-args-until-success}. -Like that function, it runs the functions on the abnormal hook -@code{hook}, stopping at the first one that returns non-@code{nil}. -Instead of calling the hook functions directly, though, it actually -calls @code{wrap-function} with arguments @code{fun} and @code{args}. -@end defun - -@node Setting Hooks -@subsection Setting Hooks - - Here's an example that uses a mode hook to turn on Auto Fill mode when -in Lisp Interaction mode: - -@example -(add-hook 'lisp-interaction-mode-hook 'auto-fill-mode) -@end example - -@defun add-hook hook function &optional append local -This function is the handy way to add function @var{function} to hook -variable @var{hook}. You can use it for abnormal hooks as well as for -normal hooks. @var{function} can be any Lisp function that can accept -the proper number of arguments for @var{hook}. For example, - -@example -(add-hook 'text-mode-hook 'my-text-hook-function) -@end example - -@noindent -adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. - -If @var{function} is already present in @var{hook} (comparing using -@code{equal}), then @code{add-hook} does not add it a second time. - -If @var{function} has a non-@code{nil} property -@code{permanent-local-hook}, then @code{kill-all-local-variables} (or -changing major modes) won't delete it from the hook variable's local -value. - -For a normal hook, hook functions should be designed so that the order -in which they are executed does not matter. Any dependence on the order -is asking for trouble. However, the order is predictable: normally, -@var{function} goes at the front of the hook list, so it is executed -first (barring another @code{add-hook} call). If the optional argument -@var{append} is non-@code{nil}, the new hook function goes at the end of -the hook list and is executed last. - -@code{add-hook} can handle the cases where @var{hook} is void or its -value is a single function; it sets or changes the value to a list of -functions. - -If @var{local} is non-@code{nil}, that says to add @var{function} to the -buffer-local hook list instead of to the global hook list. This makes -the hook buffer-local and adds @code{t} to the buffer-local value. The -latter acts as a flag to run the hook functions in the default value as -well as in the local value. -@end defun - -@defun remove-hook hook function &optional local -This function removes @var{function} from the hook variable -@var{hook}. It compares @var{function} with elements of @var{hook} -using @code{equal}, so it works for both symbols and lambda -expressions. - -If @var{local} is non-@code{nil}, that says to remove @var{function} -from the buffer-local hook list instead of from the global hook list. -@end defun - -@node Major Modes -@section Major Modes -@cindex major mode - -@cindex major mode command - Major modes specialize Emacs for editing particular kinds of text. -Each buffer has one major mode at a time. Every major mode is -associated with a @dfn{major mode command}, whose name should end in -@samp{-mode}. This command takes care of switching to that mode in the -current buffer, by setting various buffer-local variables such as a -local keymap. @xref{Major Mode Conventions}. - - The least specialized major mode is called @dfn{Fundamental mode}, -which has no mode-specific definitions or variable settings. - -@deffn Command fundamental-mode -This is the major mode command for Fundamental mode. Unlike other mode -commands, it does @emph{not} run any mode hooks (@pxref{Major Mode -Conventions}), since you are not supposed to customize this mode. -@end deffn - - The easiest way to write a major mode is to use the macro -@code{define-derived-mode}, which sets up the new mode as a variant of -an existing major mode. @xref{Derived Modes}. We recommend using -@code{define-derived-mode} even if the new mode is not an obvious -derivative of another mode, as it automatically enforces many coding -conventions for you. @xref{Basic Major Modes}, for common modes to -derive from. - - The standard GNU Emacs Lisp directory tree contains the code for -several major modes, in files such as @file{text-mode.el}, -@file{texinfo.el}, @file{lisp-mode.el}, and @file{rmail.el}. You can -study these libraries to see how modes are written. - -@defopt major-mode -The buffer-local value of this variable holds the symbol for the current -major mode. Its default value holds the default major mode for new -buffers. The standard default value is @code{fundamental-mode}. - -If the default value is @code{nil}, then whenever Emacs creates a new -buffer via a command such as @kbd{C-x b} (@code{switch-to-buffer}), the -new buffer is put in the major mode of the previously current buffer. -As an exception, if the major mode of the previous buffer has a -@code{mode-class} symbol property with value @code{special}, the new -buffer is put in Fundamental mode (@pxref{Major Mode Conventions}). -@end defopt - -@menu -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. -* Derived Modes:: Defining a new major mode based on another major - mode. -* Basic Major Modes:: Modes that other modes are often derived from. -* Mode Hooks:: Hooks run at the end of major mode functions. -* Tabulated List Mode:: Parent mode for buffers containing tabulated data. -* Generic Modes:: Defining a simple major mode that supports - comment syntax and Font Lock mode. -* Example Major Modes:: Text mode and Lisp modes. -@end menu - -@node Major Mode Conventions -@subsection Major Mode Conventions -@cindex major mode conventions -@cindex conventions for writing major modes - - The code for every major mode should follow various coding -conventions, including conventions for local keymap and syntax table -initialization, function and variable names, and hooks. - - If you use the @code{define-derived-mode} macro, it will take care of -many of these conventions automatically. @xref{Derived Modes}. Note -also that Fundamental mode is an exception to many of these conventions, -because it represents the default state of Emacs. - - The following list of conventions is only partial. Each major mode -should aim for consistency in general with other Emacs major modes, as -this makes Emacs as a whole more coherent. It is impossible to list -here all the possible points where this issue might come up; if the -Emacs developers point out an area where your major mode deviates from -the usual conventions, please make it compatible. - -@itemize @bullet -@item -Define a major mode command whose name ends in @samp{-mode}. When -called with no arguments, this command should switch to the new mode in -the current buffer by setting up the keymap, syntax table, and -buffer-local variables in an existing buffer. It should not change the -buffer's contents. - -@item -Write a documentation string for this command that describes the special -commands available in this mode. @xref{Mode Help}. - -The documentation string may include the special documentation -substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and -@samp{\<@var{keymap}>}, which allow the help display to adapt -automatically to the user's own key bindings. @xref{Keys in -Documentation}. - -@item -The major mode command should start by calling -@code{kill-all-local-variables}. This runs the normal hook -@code{change-major-mode-hook}, then gets rid of the buffer-local -variables of the major mode previously in effect. @xref{Creating -Buffer-Local}. - -@item -The major mode command should set the variable @code{major-mode} to the -major mode command symbol. This is how @code{describe-mode} discovers -which documentation to print. - -@item -The major mode command should set the variable @code{mode-name} to the -``pretty'' name of the mode, usually a string (but see @ref{Mode Line -Data}, for other possible forms). The name of the mode appears -in the mode line. - -@item -@cindex functions in modes -Since all global names are in the same name space, all the global -variables, constants, and functions that are part of the mode should -have names that start with the major mode name (or with an abbreviation -of it if the name is long). @xref{Coding Conventions}. - -@item -In a major mode for editing some kind of structured text, such as a -programming language, indentation of text according to structure is -probably useful. So the mode should set @code{indent-line-function} -to a suitable function, and probably customize other variables -for indentation. @xref{Auto-Indentation}. - -@item -@cindex keymaps in modes -The major mode should usually have its own keymap, which is used as the -local keymap in all buffers in that mode. The major mode command should -call @code{use-local-map} to install this local map. @xref{Active -Keymaps}, for more information. - -This keymap should be stored permanently in a global variable named -@code{@var{modename}-mode-map}. Normally the library that defines the -mode sets this variable. - -@xref{Tips for Defining}, for advice about how to write the code to set -up the mode's keymap variable. - -@item -The key sequences bound in a major mode keymap should usually start with -@kbd{C-c}, followed by a control character, a digit, or @kbd{@{}, -@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation -characters are reserved for minor modes, and ordinary letters are -reserved for users. - -A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and -@kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally -be some kind of ``moving forward and backward'', but this does not -necessarily mean cursor motion. - -It is legitimate for a major mode to rebind a standard key sequence if -it provides a command that does ``the same job'' in a way better -suited to the text this mode is used for. For example, a major mode -for editing a programming language might redefine @kbd{C-M-a} to -``move to the beginning of a function'' in a way that works better for -that language. - -It is also legitimate for a major mode to rebind a standard key -sequence whose standard meaning is rarely useful in that mode. For -instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is -rarely of any use in the minibuffer. Major modes such as Dired or -Rmail that do not allow self-insertion of text can reasonably redefine -letters and other printing characters as special commands. - -@item -Major modes for editing text should not define @key{RET} to do -anything other than insert a newline. However, it is ok for -specialized modes for text that users don't directly edit, such as -Dired and Info modes, to redefine @key{RET} to do something entirely -different. - -@item -Major modes should not alter options that are primarily a matter of user -preference, such as whether Auto-Fill mode is enabled. Leave this to -each user to decide. However, a major mode should customize other -variables so that Auto-Fill mode will work usefully @emph{if} the user -decides to use it. - -@item -@cindex syntax tables in modes -The mode may have its own syntax table or may share one with other -related modes. If it has its own syntax table, it should store this in -a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax -Tables}. - -@item -If the mode handles a language that has a syntax for comments, it should -set the variables that define the comment syntax. @xref{Options for -Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}. - -@item -@cindex abbrev tables in modes -The mode may have its own abbrev table or may share one with other -related modes. If it has its own abbrev table, it should store this -in a variable named @code{@var{modename}-mode-abbrev-table}. If the -major mode command defines any abbrevs itself, it should pass @code{t} -for the @var{system-flag} argument to @code{define-abbrev}. -@xref{Defining Abbrevs}. - -@item -The mode should specify how to do highlighting for Font Lock mode, by -setting up a buffer-local value for the variable -@code{font-lock-defaults} (@pxref{Font Lock Mode}). - -@item -Each face that the mode defines should, if possible, inherit from an -existing Emacs face. @xref{Basic Faces}, and @ref{Faces for Font Lock}. - -@item -The mode should specify how Imenu should find the definitions or -sections of a buffer, by setting up a buffer-local value for the -variable @code{imenu-generic-expression}, for the two variables -@code{imenu-prev-index-position-function} and -@code{imenu-extract-index-name-function}, or for the variable -@code{imenu-create-index-function} (@pxref{Imenu}). - -@item -The mode can specify a local value for -@code{eldoc-documentation-function} to tell ElDoc mode how to handle -this mode. - -@item -The mode can specify how to complete various keywords by adding one or -more buffer-local entries to the special hook -@code{completion-at-point-functions}. @xref{Completion in Buffers}. - -@item -@cindex buffer-local variables in modes -To make a buffer-local binding for an Emacs customization variable, use -@code{make-local-variable} in the major mode command, not -@code{make-variable-buffer-local}. The latter function would make the -variable local to every buffer in which it is subsequently set, which -would affect buffers that do not use this mode. It is undesirable for a -mode to have such global effects. @xref{Buffer-Local Variables}. - -With rare exceptions, the only reasonable way to use -@code{make-variable-buffer-local} in a Lisp package is for a variable -which is used only within that package. Using it on a variable used by -other packages would interfere with them. - -@item -@cindex mode hook -@cindex major mode hook -Each major mode should have a normal @dfn{mode hook} named -@code{@var{modename}-mode-hook}. The very last thing the major mode command -should do is to call @code{run-mode-hooks}. This runs the normal -hook @code{change-major-mode-after-body-hook}, the mode hook, -and then the normal hook @code{after-change-major-mode-hook}. -@xref{Mode Hooks}. - -@item -The major mode command may start by calling some other major mode -command (called the @dfn{parent mode}) and then alter some of its -settings. A mode that does this is called a @dfn{derived mode}. The -recommended way to define one is to use the @code{define-derived-mode} -macro, but this is not required. Such a mode should call the parent -mode command inside a @code{delay-mode-hooks} form. (Using -@code{define-derived-mode} does this automatically.) @xref{Derived -Modes}, and @ref{Mode Hooks}. - -@item -If something special should be done if the user switches a buffer from -this mode to any other major mode, this mode can set up a buffer-local -value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}). - -@item -If this mode is appropriate only for specially-prepared text produced by -the mode itself (rather than by the user typing at the keyboard or by an -external file), then the major mode command symbol should have a -property named @code{mode-class} with value @code{special}, put on as -follows: - -@kindex mode-class @r{(property)} -@cindex @code{special} modes -@example -(put 'funny-mode 'mode-class 'special) -@end example - -@noindent -This tells Emacs that new buffers created while the current buffer is in -Funny mode should not be put in Funny mode, even though the default -value of @code{major-mode} is @code{nil}. By default, the value of -@code{nil} for @code{major-mode} means to use the current buffer's major -mode when creating new buffers (@pxref{Auto Major Mode}), but with such -@code{special} modes, Fundamental mode is used instead. Modes such as -Dired, Rmail, and Buffer List use this feature. - -The function @code{view-buffer} does not enable View mode in buffers -whose mode-class is special, because such modes usually provide their -own View-like bindings. - -The @code{define-derived-mode} macro automatically marks the derived -mode as special if the parent mode is special. Special mode is a -convenient parent for such modes to inherit from; @xref{Basic Major -Modes}. - -@item -If you want to make the new mode the default for files with certain -recognizable names, add an element to @code{auto-mode-alist} to select -the mode for those file names (@pxref{Auto Major Mode}). If you -define the mode command to autoload, you should add this element in -the same file that calls @code{autoload}. If you use an autoload -cookie for the mode command, you can also use an autoload cookie for -the form that adds the element (@pxref{autoload cookie}). If you do -not autoload the mode command, it is sufficient to add the element in -the file that contains the mode definition. - -@item -@cindex mode loading -The top-level forms in the file defining the mode should be written so -that they may be evaluated more than once without adverse consequences. -For instance, use @code{defvar} or @code{defcustom} to set mode-related -variables, so that they are not reinitialized if they already have a -value (@pxref{Defining Variables}). - -@end itemize - -@node Auto Major Mode -@subsection How Emacs Chooses a Major Mode -@cindex major mode, automatic selection - - When Emacs visits a file, it automatically selects a major mode for -the buffer based on information in the file name or in the file itself. -It also processes local variables specified in the file text. - -@deffn Command normal-mode &optional find-file -This function establishes the proper major mode and buffer-local variable -bindings for the current buffer. First it calls @code{set-auto-mode} -(see below), then it runs @code{hack-local-variables} to parse, and -bind or evaluate as appropriate, the file's local variables -(@pxref{File Local Variables}). - -If the @var{find-file} argument to @code{normal-mode} is non-@code{nil}, -@code{normal-mode} assumes that the @code{find-file} function is calling -it. In this case, it may process local variables in the @samp{-*-} -line or at the end of the file. The variable -@code{enable-local-variables} controls whether to do so. @xref{File -Variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, -for the syntax of the local variables section of a file. - -If you run @code{normal-mode} interactively, the argument -@var{find-file} is normally @code{nil}. In this case, -@code{normal-mode} unconditionally processes any file local variables. - -The function calls @code{set-auto-mode} to choose a major mode. If this -does not specify a mode, the buffer stays in the major mode determined -by the default value of @code{major-mode} (see below). - -@cindex file mode specification error -@code{normal-mode} uses @code{condition-case} around the call to the -major mode command, so errors are caught and reported as a @samp{File -mode specification error}, followed by the original error message. -@end deffn - -@defun set-auto-mode &optional keep-mode-if-same -@cindex visited file mode - This function selects the major mode that is appropriate for the -current buffer. It bases its decision (in order of precedence) on the -@w{@samp{-*-}} line, on any @samp{mode:} local variable near the end of -a file, on the @w{@samp{#!}} line (using @code{interpreter-mode-alist}), -on the text at the beginning of the buffer (using -@code{magic-mode-alist}), and finally on the visited file name (using -@code{auto-mode-alist}). @xref{Choosing Modes, , How Major Modes are -Chosen, emacs, The GNU Emacs Manual}. If @code{enable-local-variables} -is @code{nil}, @code{set-auto-mode} does not check the @w{@samp{-*-}} -line, or near the end of the file, for any mode tag. - -@vindex inhibit-local-variables-regexps -There are some file types where it is not appropriate to scan the file -contents for a mode specifier. For example, a tar archive may happen to -contain, near the end of the file, a member file that has a local -variables section specifying a mode for that particular file. This -should not be applied to the containing tar file. Similarly, a tiff -image file might just happen to contain a first line that seems to -match the @w{@samp{-*-}} pattern. For these reasons, both these file -extensions are members of the list @var{inhibit-local-variables-regexps}. -Add patterns to this list to prevent Emacs searching them for local -variables of any kind (not just mode specifiers). - -If @var{keep-mode-if-same} is non-@code{nil}, this function does not -call the mode command if the buffer is already in the proper major -mode. For instance, @code{set-visited-file-name} sets this to -@code{t} to avoid killing buffer local variables that the user may -have set. -@end defun - -@defun set-buffer-major-mode buffer -This function sets the major mode of @var{buffer} to the default value of -@code{major-mode}; if that is @code{nil}, it uses the -current buffer's major mode (if that is suitable). As an exception, -if @var{buffer}'s name is @file{*scratch*}, it sets the mode to -@code{initial-major-mode}. - -The low-level primitives for creating buffers do not use this function, -but medium-level commands such as @code{switch-to-buffer} and -@code{find-file-noselect} use it whenever they create buffers. -@end defun - -@defopt initial-major-mode -@cindex @file{*scratch*} -The value of this variable determines the major mode of the initial -@file{*scratch*} buffer. The value should be a symbol that is a major -mode command. The default value is @code{lisp-interaction-mode}. -@end defopt - -@defvar interpreter-mode-alist -This variable specifies major modes to use for scripts that specify a -command interpreter in a @samp{#!} line. Its value is an alist with -elements of the form @code{(@var{interpreter} . @var{mode})}; for -example, @code{("perl" . perl-mode)} is one element present by -default. The element says to use mode @var{mode} if the file -specifies an interpreter which matches @var{interpreter}. -@end defvar - -@defvar magic-mode-alist -This variable's value is an alist with elements of the form -@code{(@var{regexp} . @var{function})}, where @var{regexp} is a -regular expression and @var{function} is a function or @code{nil}. -After visiting a file, @code{set-auto-mode} calls @var{function} if -the text at the beginning of the buffer matches @var{regexp} and -@var{function} is non-@code{nil}; if @var{function} is @code{nil}, -@code{auto-mode-alist} gets to decide the mode. -@end defvar - -@defvar magic-fallback-mode-alist -This works like @code{magic-mode-alist}, except that it is handled -only if @code{auto-mode-alist} does not specify a mode for this file. -@end defvar - -@defvar auto-mode-alist -This variable contains an association list of file name patterns -(regular expressions) and corresponding major mode commands. Usually, -the file name patterns test for suffixes, such as @samp{.el} and -@samp{.c}, but this need not be the case. An ordinary element of the -alist looks like @code{(@var{regexp} . @var{mode-function})}. - -For example, - -@smallexample -@group -(("\\`/tmp/fol/" . text-mode) - ("\\.texinfo\\'" . texinfo-mode) - ("\\.texi\\'" . texinfo-mode) -@end group -@group - ("\\.el\\'" . emacs-lisp-mode) - ("\\.c\\'" . c-mode) - ("\\.h\\'" . c-mode) - @dots{}) -@end group -@end smallexample - -When you visit a file whose expanded file name (@pxref{File Name -Expansion}), with version numbers and backup suffixes removed using -@code{file-name-sans-versions} (@pxref{File Name Components}), matches -a @var{regexp}, @code{set-auto-mode} calls the corresponding -@var{mode-function}. This feature enables Emacs to select the proper -major mode for most files. - -If an element of @code{auto-mode-alist} has the form @code{(@var{regexp} -@var{function} t)}, then after calling @var{function}, Emacs searches -@code{auto-mode-alist} again for a match against the portion of the file -name that did not match before. This feature is useful for -uncompression packages: an entry of the form @code{("\\.gz\\'" -@var{function} t)} can uncompress the file and then put the uncompressed -file in the proper mode according to the name sans @samp{.gz}. - -Here is an example of how to prepend several pattern pairs to -@code{auto-mode-alist}. (You might use this sort of expression in your -init file.) - -@smallexample -@group -(setq auto-mode-alist - (append - ;; @r{File name (within directory) starts with a dot.} - '(("/\\.[^/]*\\'" . fundamental-mode) - ;; @r{File name has no dot.} - ("/[^\\./]*\\'" . fundamental-mode) - ;; @r{File name ends in @samp{.C}.} - ("\\.C\\'" . c++-mode)) - auto-mode-alist)) -@end group -@end smallexample -@end defvar - -@node Mode Help -@subsection Getting Help about a Major Mode -@cindex mode help -@cindex help for major mode -@cindex documentation for major mode - - The @code{describe-mode} function provides information about major -modes. It is normally bound to @kbd{C-h m}. It uses the value of the -variable @code{major-mode} (@pxref{Major Modes}), which is why every -major mode command needs to set that variable. - -@deffn Command describe-mode &optional buffer -This command displays the documentation of the current buffer's major -mode and minor modes. It uses the @code{documentation} function to -retrieve the documentation strings of the major and minor mode -commands (@pxref{Accessing Documentation}). - -If called from Lisp with a non-nil @var{buffer} argument, this -function displays the documentation for that buffer's major and minor -modes, rather than those of the current buffer. -@end deffn - -@node Derived Modes -@subsection Defining Derived Modes -@cindex derived mode - - The recommended way to define a new major mode is to derive it from an -existing one using @code{define-derived-mode}. If there is no closely -related mode, you should inherit from either @code{text-mode}, -@code{special-mode}, or @code{prog-mode}. @xref{Basic Major Modes}. If -none of these are suitable, you can inherit from @code{fundamental-mode} -(@pxref{Major Modes}). - -@defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{} -This macro defines @var{variant} as a major mode command, using -@var{name} as the string form of the mode name. @var{variant} and -@var{parent} should be unquoted symbols. - -The new command @var{variant} is defined to call the function -@var{parent}, then override certain aspects of that parent mode: - -@itemize @bullet -@item -The new mode has its own sparse keymap, named -@code{@var{variant}-map}. @code{define-derived-mode} -makes the parent mode's keymap the parent of the new map, unless -@code{@var{variant}-map} is already set and already has a parent. - -@item -The new mode has its own syntax table, kept in the variable -@code{@var{variant}-syntax-table}, unless you override this using the -@code{:syntax-table} keyword (see below). @code{define-derived-mode} -makes the parent mode's syntax-table the parent of -@code{@var{variant}-syntax-table}, unless the latter is already set -and already has a parent different from the standard syntax table. - -@item -The new mode has its own abbrev table, kept in the variable -@code{@var{variant}-abbrev-table}, unless you override this using the -@code{:abbrev-table} keyword (see below). - -@item -The new mode has its own mode hook, @code{@var{variant}-hook}. It -runs this hook, after running the hooks of its ancestor modes, with -@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}. -@end itemize - -In addition, you can specify how to override other aspects of -@var{parent} with @var{body}. The command @var{variant} -evaluates the forms in @var{body} after setting up all its usual -overrides, just before running the mode hooks. - -If @var{parent} has a non-@code{nil} @code{mode-class} symbol -property, then @code{define-derived-mode} sets the @code{mode-class} -property of @var{variant} to the same value. This ensures, for -example, that if @var{parent} is a special mode, then @var{variant} is -also a special mode (@pxref{Major Mode Conventions}). - -You can also specify @code{nil} for @var{parent}. This gives the new -mode no parent. Then @code{define-derived-mode} behaves as described -above, but, of course, omits all actions connected with @var{parent}. - -The argument @var{docstring} specifies the documentation string for the -new mode. @code{define-derived-mode} adds some general information -about the mode's hook, followed by the mode's keymap, at the end of this -documentation string. If you omit @var{docstring}, -@code{define-derived-mode} generates a documentation string. - -The @var{keyword-args} are pairs of keywords and values. The values -are evaluated. The following keywords are currently supported: - -@table @code -@item :syntax-table -You can use this to explicitly specify a syntax table for the new -mode. If you specify a @code{nil} value, the new mode uses the same -syntax table as @var{parent}, or the standard syntax table if -@var{parent} is @code{nil}. (Note that this does @emph{not} follow -the convention used for non-keyword arguments that a @code{nil} value -is equivalent with not specifying the argument.) - -@item :abbrev-table -You can use this to explicitly specify an abbrev table for the new -mode. If you specify a @code{nil} value, the new mode uses the same -abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table} -if @var{parent} is @code{nil}. (Again, a @code{nil} value is -@emph{not} equivalent to not specifying this keyword.) - -@item :group -If this is specified, the value should be the customization group for -this mode. (Not all major modes have one.) Only the (still -experimental and unadvertised) command @code{customize-mode} currently -uses this. @code{define-derived-mode} does @emph{not} automatically -define the specified customization group. -@end table - -Here is a hypothetical example: - -@example -(define-derived-mode hypertext-mode - text-mode "Hypertext" - "Major mode for hypertext. -\\@{hypertext-mode-map@}" - (setq case-fold-search nil)) - -(define-key hypertext-mode-map - [down-mouse-3] 'do-hyper-link) -@end example - -Do not write an @code{interactive} spec in the definition; -@code{define-derived-mode} does that automatically. -@end defmac - -@defun derived-mode-p &rest modes -This function returns non-@code{nil} if the current major mode is -derived from any of the major modes given by the symbols @var{modes}. -@end defun - -@node Basic Major Modes -@subsection Basic Major Modes - - Apart from Fundamental mode, there are three major modes that other -major modes commonly derive from: Text mode, Prog mode, and Special -mode. While Text mode is useful in its own right (e.g. for editing -files ending in @file{.txt}), Prog mode and Special mode exist mainly to -let other modes derive from them. - -@vindex prog-mode-hook - As far as possible, new major modes should be derived, either directly -or indirectly, from one of these three modes. One reason is that this -allows users to customize a single mode hook -(e.g. @code{prog-mode-hook}) for an entire family of relevant modes -(e.g. all programming language modes). - -@deffn Command text-mode -Text mode is a major mode for editing human languages. It defines the -@samp{"} and @samp{\} characters as having punctuation syntax -(@pxref{Syntax Class Table}), and binds @kbd{M-@key{TAB}} to -@code{ispell-complete-word} (@pxref{Spelling,,, emacs, The GNU Emacs -Manual}). - -An example of a major mode derived from Text mode is HTML mode. -@xref{HTML Mode,,SGML and HTML Modes, emacs, The GNU Emacs Manual}. -@end deffn - -@deffn Command prog-mode -Prog mode is a basic major mode for buffers containing programming -language source code. Most of the programming language major modes -built into Emacs are derived from it. - -Prog mode binds @code{parse-sexp-ignore-comments} to @code{t} -(@pxref{Motion via Parsing}) and @code{bidi-paragraph-direction} to -@code{left-to-right} (@pxref{Bidirectional Display}). -@end deffn - -@deffn Command special-mode -Special mode is a basic major mode for buffers containing text that is -produced specially by Emacs, rather than directly from a file. Major -modes derived from Special mode are given a @code{mode-class} property -of @code{special} (@pxref{Major Mode Conventions}). - -Special mode sets the buffer to read-only. Its keymap defines several -common bindings, including @kbd{q} for @code{quit-window}, @kbd{z} for -@code{kill-this-buffer}, and @kbd{g} for @code{revert-buffer} -(@pxref{Reverting}). - -An example of a major mode derived from Special mode is Buffer Menu -mode, which is used by the @file{*Buffer List*} buffer. @xref{List -Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}. -@end deffn - - In addition, modes for buffers of tabulated data can inherit from -Tabulated List mode, which is in turn derived from Special mode. -@xref{Tabulated List Mode}. - -@node Mode Hooks -@subsection Mode Hooks - - Every major mode command should finish by running the mode-independent -normal hook @code{change-major-mode-after-body-hook}, its mode hook, -and the normal hook @code{after-change-major-mode-hook}. -It does this by calling @code{run-mode-hooks}. If the major mode is a -derived mode, that is if it calls another major mode (the parent mode) -in its body, it should do this inside @code{delay-mode-hooks} so that -the parent won't run these hooks itself. Instead, the derived mode's -call to @code{run-mode-hooks} runs the parent's mode hook too. -@xref{Major Mode Conventions}. - - Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}. -Versions before 24 did not have @code{change-major-mode-after-body-hook}. -When user-implemented major modes do not use @code{run-mode-hooks} and -have not been updated to use these newer features, they won't entirely -follow these conventions: they may run the parent's mode hook too early, -or fail to run @code{after-change-major-mode-hook}. If you encounter -such a major mode, please correct it to follow these conventions. - - When you defined a major mode using @code{define-derived-mode}, it -automatically makes sure these conventions are followed. If you -define a major mode ``by hand'', not using @code{define-derived-mode}, -use the following functions to handle these conventions automatically. - -@defun run-mode-hooks &rest hookvars -Major modes should run their mode hook using this function. It is -similar to @code{run-hooks} (@pxref{Hooks}), but it also runs -@code{change-major-mode-after-body-hook} and -@code{after-change-major-mode-hook}. - -When this function is called during the execution of a -@code{delay-mode-hooks} form, it does not run the hooks immediately. -Instead, it arranges for the next call to @code{run-mode-hooks} to run -them. -@end defun - -@defmac delay-mode-hooks body@dots{} -When one major mode command calls another, it should do so inside of -@code{delay-mode-hooks}. - -This macro executes @var{body}, but tells all @code{run-mode-hooks} -calls during the execution of @var{body} to delay running their hooks. -The hooks will actually run during the next call to -@code{run-mode-hooks} after the end of the @code{delay-mode-hooks} -construct. -@end defmac - -@defvar change-major-mode-after-body-hook -This is a normal hook run by @code{run-mode-hooks}. It is run before -the mode hooks. -@end defvar - -@defvar after-change-major-mode-hook -This is a normal hook run by @code{run-mode-hooks}. It is run at the -very end of every properly-written major mode command. -@end defvar - -@node Tabulated List Mode -@subsection Tabulated List mode -@cindex Tabulated List mode - - Tabulated List mode is a major mode for displaying tabulated data, -i.e.@: data consisting of @dfn{entries}, each entry occupying one row of -text with its contents divided into columns. Tabulated List mode -provides facilities for pretty-printing rows and columns, and sorting -the rows according to the values in each column. It is derived from -Special mode (@pxref{Basic Major Modes}). - - Tabulated List mode is intended to be used as a parent mode by a more -specialized major mode. Examples include Process Menu mode -(@pxref{Process Information}) and Package Menu mode (@pxref{Package -Menu,,, emacs, The GNU Emacs Manual}). - -@findex tabulated-list-mode - Such a derived mode should use @code{define-derived-mode} in the usual -way, specifying @code{tabulated-list-mode} as the second argument -(@pxref{Derived Modes}). The body of the @code{define-derived-mode} -form should specify the format of the tabulated data, by assigning -values to the variables documented below; then, it should call the -function @code{tabulated-list-init-header} to initialize the header -line. - - The derived mode should also define a @dfn{listing command}. This, -not the mode command, is what the user calls (e.g.@: @kbd{M-x -list-processes}). The listing command should create or switch to a -buffer, turn on the derived mode, specify the tabulated data, and -finally call @code{tabulated-list-print} to populate the buffer. - -@defvar tabulated-list-format -This buffer-local variable specifies the format of the Tabulated List -data. Its value should be a vector. Each element of the vector -represents a data column, and should be a list @code{(@var{name} -@var{width} @var{sort})}, where - -@itemize -@item -@var{name} is the column's name (a string). - -@item -@var{width} is the width to reserve for the column (an integer). This -is meaningless for the last column, which runs to the end of each line. - -@item -@var{sort} specifies how to sort entries by the column. If @code{nil}, -the column cannot be used for sorting. If @code{t}, the column is -sorted by comparing string values. Otherwise, this should be a -predicate function for @code{sort} (@pxref{Rearrangement}), which -accepts two arguments with the same form as the elements of -@code{tabulated-list-entries} (see below). -@end itemize -@end defvar - -@defvar tabulated-list-entries -This buffer-local variable specifies the entries displayed in the -Tabulated List buffer. Its value should be either a list, or a -function. - -If the value is a list, each list element corresponds to one entry, and -should have the form @w{@code{(@var{id} @var{contents})}}, where - -@itemize -@item -@var{id} is either @code{nil}, or a Lisp object that identifies the -entry. If the latter, the cursor stays on the ``same'' entry when -re-sorting entries. Comparison is done with @code{equal}. - -@item -@var{contents} is a vector with the same number of elements as -@code{tabulated-list-format}. Each vector element is either a string, -which is inserted into the buffer as-is, or a list @code{(@var{label} -. @var{properties})}, which means to insert a text button by calling -@code{insert-text-button} with @var{label} and @var{properties} as -arguments (@pxref{Making Buttons}). - -There should be no newlines in any of these strings. -@end itemize - -Otherwise, the value should be a function which returns a list of the -above form when called with no arguments. -@end defvar - -@defvar tabulated-list-revert-hook -This normal hook is run prior to reverting a Tabulated List buffer. A -derived mode can add a function to this hook to recompute -@code{tabulated-list-entries}. -@end defvar - -@defvar tabulated-list-printer -The value of this variable is the function called to insert an entry at -point, including its terminating newline. The function should accept -two arguments, @var{id} and @var{contents}, having the same meanings as -in @code{tabulated-list-entries}. The default value is a function which -inserts an entry in a straightforward way; a mode which uses Tabulated -List mode in a more complex way can specify another function. -@end defvar - -@defvar tabulated-list-sort-key -The value of this variable specifies the current sort key for the -Tabulated List buffer. If it is @code{nil}, no sorting is done. -Otherwise, it should have the form @code{(@var{name} . @var{flip})}, -where @var{name} is a string matching one of the column names in -@code{tabulated-list-format}, and @var{flip}, if non-@code{nil}, means -to invert the sort order. -@end defvar - -@defun tabulated-list-init-header -This function computes and sets @code{header-line-format} for the -Tabulated List buffer (@pxref{Header Lines}), and assigns a keymap to -the header line to allow sort entries by clicking on column headers. - -Modes derived from Tabulated List mode should call this after setting -the above variables (in particular, only after setting -@code{tabulated-list-format}). -@end defun - -@defun tabulated-list-print &optional remember-pos -This function populates the current buffer with entries. It should be -called by the listing command. It erases the buffer, sorts the entries -specified by @code{tabulated-list-entries} according to -@code{tabulated-list-sort-key}, then calls the function specified by -@code{tabulated-list-printer} to insert each entry. - -If the optional argument @var{remember-pos} is non-@code{nil}, this -function looks for the @var{id} element on the current line, if any, and -tries to move to that entry after all the entries are (re)inserted. -@end defun - -@node Generic Modes -@subsection Generic Modes -@cindex generic mode - - @dfn{Generic modes} are simple major modes with basic support for -comment syntax and Font Lock mode. To define a generic mode, use the -macro @code{define-generic-mode}. See the file @file{generic-x.el} -for some examples of the use of @code{define-generic-mode}. - -@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring -This macro defines a generic mode command named @var{mode} (a symbol, -not quoted). The optional argument @var{docstring} is the -documentation for the mode command. If you do not supply it, -@code{define-generic-mode} generates one by default. - -The argument @var{comment-list} is a list in which each element is -either a character, a string of one or two characters, or a cons cell. -A character or a string is set up in the mode's syntax table as a -``comment starter''. If the entry is a cons cell, the @sc{car} is set -up as a ``comment starter'' and the @sc{cdr} as a ``comment ender''. -(Use @code{nil} for the latter if you want comments to end at the end -of the line.) Note that the syntax table mechanism has limitations -about what comment starters and enders are actually possible. -@xref{Syntax Tables}. - -The argument @var{keyword-list} is a list of keywords to highlight -with @code{font-lock-keyword-face}. Each keyword should be a string. -Meanwhile, @var{font-lock-list} is a list of additional expressions to -highlight. Each element of this list should have the same form as an -element of @code{font-lock-keywords}. @xref{Search-based -Fontification}. - -The argument @var{auto-mode-list} is a list of regular expressions to -add to the variable @code{auto-mode-alist}. They are added by the execution -of the @code{define-generic-mode} form, not by expanding the macro call. - -Finally, @var{function-list} is a list of functions for the mode -command to call for additional setup. It calls these functions just -before it runs the mode hook variable @code{@var{mode}-hook}. -@end defmac - -@node Example Major Modes -@subsection Major Mode Examples - - Text mode is perhaps the simplest mode besides Fundamental mode. -Here are excerpts from @file{text-mode.el} that illustrate many of -the conventions listed above: - -@smallexample -@group -;; @r{Create the syntax table for this mode.} -(defvar text-mode-syntax-table - (let ((st (make-syntax-table))) - (modify-syntax-entry ?\" ". " st) - (modify-syntax-entry ?\\ ". " st) - ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'. - (modify-syntax-entry ?' "w p" st) - st) - "Syntax table used while in `text-mode'.") -@end group - -;; @r{Create the keymap for this mode.} -@group -(defvar text-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\e\t" 'ispell-complete-word) - map) - "Keymap for `text-mode'. -Many other modes, such as `mail-mode', `outline-mode' and -`indented-text-mode', inherit all the commands defined in this map.") -@end group -@end smallexample - - Here is how the actual mode command is defined now: - -@smallexample -@group -(define-derived-mode text-mode nil "Text" - "Major mode for editing text written for humans to read. -In this mode, paragraphs are delimited only by blank or white lines. -You can thus get the full benefit of adaptive filling - (see the variable `adaptive-fill-mode'). -\\@{text-mode-map@} -Turning on Text mode runs the normal hook `text-mode-hook'." -@end group -@group - (set (make-local-variable 'text-mode-variant) t) - (set (make-local-variable 'require-final-newline) - mode-require-final-newline) - (set (make-local-variable 'indent-line-function) 'indent-relative)) -@end group -@end smallexample - -@noindent -(The last line is redundant nowadays, since @code{indent-relative} is -the default value, and we'll delete it in a future version.) - -@cindex @file{lisp-mode.el} - The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp Interaction -mode) have more features than Text mode and the code is correspondingly -more complicated. Here are excerpts from @file{lisp-mode.el} that -illustrate how these modes are written. - - Here is how the Lisp mode syntax and abbrev tables are defined: - -@cindex syntax table example -@smallexample -@group -;; @r{Create mode-specific table variables.} -(defvar lisp-mode-abbrev-table nil) -(define-abbrev-table 'lisp-mode-abbrev-table ()) - -(defvar lisp-mode-syntax-table - (let ((table (copy-syntax-table emacs-lisp-mode-syntax-table))) - (modify-syntax-entry ?\[ "_ " table) - (modify-syntax-entry ?\] "_ " table) - (modify-syntax-entry ?# "' 14" table) - (modify-syntax-entry ?| "\" 23bn" table) - table) - "Syntax table used in `lisp-mode'.") -@end group -@end smallexample - - The three modes for Lisp share much of their code. For instance, -each calls the following function to set various variables: - -@smallexample -@group -(defun lisp-mode-variables (&optional lisp-syntax keywords-case-insensitive) - (when lisp-syntax - (set-syntax-table lisp-mode-syntax-table)) - (setq local-abbrev-table lisp-mode-abbrev-table) - @dots{} -@end group -@end smallexample - -@noindent -Amongst other things, this function sets up the @code{comment-start} -variable to handle Lisp comments: - -@smallexample -@group - (make-local-variable 'comment-start) - (setq comment-start ";") - @dots{} -@end group -@end smallexample - - Each of the different Lisp modes has a slightly different keymap. For -example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other -Lisp modes do not. However, all Lisp modes have some commands in -common. The following code sets up the common commands: - -@smallexample -@group -(defvar lisp-mode-shared-map - (let ((map (make-sparse-keymap))) - (define-key map "\e\C-q" 'indent-sexp) - (define-key map "\177" 'backward-delete-char-untabify) - map) - "Keymap for commands shared by all sorts of Lisp modes.") -@end group -@end smallexample - -@noindent -And here is the code to set up the keymap for Lisp mode: - -@smallexample -@group -(defvar lisp-mode-map - (let ((map (make-sparse-keymap)) - (menu-map (make-sparse-keymap "Lisp"))) - (set-keymap-parent map lisp-mode-shared-map) - (define-key map "\e\C-x" 'lisp-eval-defun) - (define-key map "\C-c\C-z" 'run-lisp) - @dots{} - map) - "Keymap for ordinary Lisp mode. -All commands in `lisp-mode-shared-map' are inherited by this map.") -@end group -@end smallexample - -@noindent -Finally, here is the major mode command for Lisp mode: - -@smallexample -@group -(define-derived-mode lisp-mode prog-mode "Lisp" - "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp. -Commands: -Delete converts tabs to spaces as it moves back. -Blank lines separate paragraphs. Semicolons start comments. - -\\@{lisp-mode-map@} -Note that `run-lisp' may be used either to start an inferior Lisp job -or to switch back to an existing one. -@end group - -@group -Entry to this mode calls the value of `lisp-mode-hook' -if that value is non-nil." - (lisp-mode-variables nil t) - (set (make-local-variable 'find-tag-default-function) 'lisp-find-tag-default) - (make-local-variable 'comment-start-skip) - (setq comment-start-skip - "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") - (setq imenu-case-fold-search t)) -@end group -@end smallexample - -@node Minor Modes -@section Minor Modes -@cindex minor mode - - A @dfn{minor mode} provides optional features that users may enable or -disable independently of the choice of major mode. Minor modes can be -enabled individually or in combination. - - Most minor modes implement features that are independent of the major -mode, and can thus be used with most major modes. For example, Auto -Fill mode works with any major mode that permits text insertion. A few -minor modes, however, are specific to a particular major mode. For -example, Diff Auto Refine mode is a minor mode that is intended to be -used only with Diff mode. - - Ideally, a minor mode should have its desired effect regardless of the -other minor modes in effect. It should be possible to activate and -deactivate minor modes in any order. - -@defvar minor-mode-list -The value of this variable is a list of all minor mode commands. -@end defvar - -@menu -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -* Defining Minor Modes:: A convenient facility for defining minor modes. -@end menu - -@node Minor Mode Conventions -@subsection Conventions for Writing Minor Modes -@cindex minor mode conventions -@cindex conventions for writing minor modes - - There are conventions for writing minor modes just as there are for -major modes. These conventions are described below. The easiest way to -follow them is to use the macro @code{define-minor-mode}. -@xref{Defining Minor Modes}. - -@itemize @bullet -@item -@cindex mode variable -Define a variable whose name ends in @samp{-mode}. We call this the -@dfn{mode variable}. The minor mode command should set this variable. -The value will be @code{nil} is the mode is disabled, and non-@code{nil} -if the mode is enabled. The variable should be buffer-local if the -minor mode is buffer-local. - -This variable is used in conjunction with the @code{minor-mode-alist} to -display the minor mode name in the mode line. It also determines -whether the minor mode keymap is active, via @code{minor-mode-map-alist} -(@pxref{Controlling Active Maps}). Individual commands or hooks can -also check its value. - -@item -Define a command, called the @dfn{mode command}, whose name is the same -as the mode variable. Its job is to set the value of the mode variable, -plus anything else that needs to be done to actually enable or disable -the mode's features. - -The mode command should accept one optional argument. If called -interactively with no prefix argument, it should toggle the mode -(i.e.@: enable if it is disabled, and disable if it is enabled). If -called interactively with a prefix argument, it should enable the mode -if the argument is positive and disable it otherwise. - -If the mode command is called from Lisp (i.e.@: non-interactively), it -should enable the mode if the argument is omitted or @code{nil}; it -should toggle the mode if the argument is the symbol @code{toggle}; -otherwise it should treat the argument in the same way as for an -interactive call with a numeric prefix argument, as described above. - -The following example shows how to implement this behavior (it is -similar to the code generated by the @code{define-minor-mode} macro): - -@example -(interactive (list (or current-prefix-arg 'toggle))) -(let ((enable (if (eq arg 'toggle) - (not foo-mode) ; @r{this mode's mode variable} - (> (prefix-numeric-value arg) 0)))) - (if enable - @var{do-enable} - @var{do-disable})) -@end example - -The reason for this somewhat complex behavior is that it lets users -easily toggle the minor mode interactively, and also lets the minor mode -be easily enabled in a mode hook, like this: - -@example -(add-hook 'text-mode-hook 'foo-mode) -@end example - -@noindent -This behaves correctly whether or not @code{foo-mode} was already -enabled, since the @code{foo-mode} mode command unconditionally enables -the minor mode when it is called from Lisp with no argument. Disabling -a minor mode in a mode hook is a little uglier: - -@example -(add-hook 'text-mode-hook (lambda () (foo-mode -1))) -@end example - -@noindent -However, this is not very commonly done. - -@item -Add an element to @code{minor-mode-alist} for each minor mode -(@pxref{Definition of minor-mode-alist}), if you want to indicate the -minor mode in the mode line. This element should be a list of the -following form: - -@smallexample -(@var{mode-variable} @var{string}) -@end smallexample - -Here @var{mode-variable} is the variable that controls enabling of the -minor mode, and @var{string} is a short string, starting with a space, -to represent the mode in the mode line. These strings must be short so -that there is room for several of them at once. - -When you add an element to @code{minor-mode-alist}, use @code{assq} to -check for an existing element, to avoid duplication. For example: - -@smallexample -@group -(unless (assq 'leif-mode minor-mode-alist) - (push '(leif-mode " Leif") minor-mode-alist)) -@end group -@end smallexample - -@noindent -or like this, using @code{add-to-list} (@pxref{List Variables}): - -@smallexample -@group -(add-to-list 'minor-mode-alist '(leif-mode " Leif")) -@end group -@end smallexample -@end itemize - - In addition, several major mode conventions apply to minor modes as -well: those regarding the names of global symbols, the use of a hook at -the end of the initialization function, and the use of keymaps and other -tables. - - The minor mode should, if possible, support enabling and disabling via -Custom (@pxref{Customization}). To do this, the mode variable should be -defined with @code{defcustom}, usually with @code{:type 'boolean}. If -just setting the variable is not sufficient to enable the mode, you -should also specify a @code{:set} method which enables the mode by -invoking the mode command. Note in the variable's documentation string -that setting the variable other than via Custom may not take effect. -Also, mark the definition with an autoload cookie (@pxref{autoload -cookie}), and specify a @code{:require} so that customizing the variable -will load the library that defines the mode. For example: - -@smallexample -@group -;;;###autoload -(defcustom msb-mode nil - "Toggle msb-mode. -Setting this variable directly does not take effect; -use either \\[customize] or the function `msb-mode'." - :set 'custom-set-minor-mode - :initialize 'custom-initialize-default - :version "20.4" - :type 'boolean - :group 'msb - :require 'msb) -@end group -@end smallexample - -@node Keymaps and Minor Modes -@subsection Keymaps and Minor Modes - - Each minor mode can have its own keymap, which is active when the mode -is enabled. To set up a keymap for a minor mode, add an element to the -alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}. - -@cindex @code{self-insert-command}, minor modes - One use of minor mode keymaps is to modify the behavior of certain -self-inserting characters so that they do something else as well as -self-insert. (Another way to customize @code{self-insert-command} is -through @code{post-self-insert-hook}. Apart from this, the facilities -for customizing @code{self-insert-command} are limited to special cases, -designed for abbrevs and Auto Fill mode. Do not try substituting your -own definition of @code{self-insert-command} for the standard one. The -editor command loop handles this function specially.) - -The key sequences bound in a minor mode should consist of @kbd{C-c} -followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other -punctuation characters are reserved for major modes.) - -@node Defining Minor Modes -@subsection Defining Minor Modes - - The macro @code{define-minor-mode} offers a convenient way of -implementing a mode in one self-contained definition. - -@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{} -This macro defines a new minor mode whose name is @var{mode} (a -symbol). It defines a command named @var{mode} to toggle the minor -mode, with @var{doc} as its documentation string. - -The toggle command takes one optional (prefix) argument. -If called interactively with no argument it toggles the mode on or off. -A positive prefix argument enables the mode, any other prefix argument -disables it. From Lisp, an argument of @code{toggle} toggles the mode, -whereas an omitted or @code{nil} argument enables the mode. -This makes it easy to enable the minor mode in a major mode hook, for example. -If @var{doc} is nil, the macro supplies a default documentation string -explaining the above. - -By default, it also defines a variable named @var{mode}, which is set to -@code{t} or @code{nil} by enabling or disabling the mode. The variable -is initialized to @var{init-value}. Except in unusual circumstances -(see below), this value must be @code{nil}. - -The string @var{lighter} says what to display in the mode line -when the mode is enabled; if it is @code{nil}, the mode is not displayed -in the mode line. - -The optional argument @var{keymap} specifies the keymap for the minor -mode. If non-@code{nil}, it should be a variable name (whose value is -a keymap), a keymap, or an alist of the form - -@example -(@var{key-sequence} . @var{definition}) -@end example - -@noindent -where each @var{key-sequence} and @var{definition} are arguments -suitable for passing to @code{define-key} (@pxref{Changing Key -Bindings}). If @var{keymap} is a keymap or an alist, this also -defines the variable @code{@var{mode}-map}. - -The above three arguments @var{init-value}, @var{lighter}, and -@var{keymap} can be (partially) omitted when @var{keyword-args} are -used. The @var{keyword-args} consist of keywords followed by -corresponding values. A few keywords have special meanings: - -@table @code -@item :group @var{group} -Custom group name to use in all generated @code{defcustom} forms. -Defaults to @var{mode} without the possible trailing @samp{-mode}. -@strong{Warning:} don't use this default group name unless you have -written a @code{defgroup} to define that group properly. @xref{Group -Definitions}. - -@item :global @var{global} -If non-@code{nil}, this specifies that the minor mode should be global -rather than buffer-local. It defaults to @code{nil}. - -One of the effects of making a minor mode global is that the -@var{mode} variable becomes a customization variable. Toggling it -through the Customize interface turns the mode on and off, and its -value can be saved for future Emacs sessions (@pxref{Saving -Customizations,,, emacs, The GNU Emacs Manual}. For the saved -variable to work, you should ensure that the @code{define-minor-mode} -form is evaluated each time Emacs starts; for packages that are not -part of Emacs, the easiest way to do this is to specify a -@code{:require} keyword. - -@item :init-value @var{init-value} -This is equivalent to specifying @var{init-value} positionally. - -@item :lighter @var{lighter} -This is equivalent to specifying @var{lighter} positionally. - -@item :keymap @var{keymap} -This is equivalent to specifying @var{keymap} positionally. - -@item :variable @var{place} -This replaces the default variable @var{mode}, used to store the state -of the mode. If you specify this, the @var{mode} variable is not -defined, and any @var{init-value} argument is unused. @var{place} -can be a different named variable (which you must define yourself), or -anything that can be used with the @code{setf} function -(@pxref{Generalized Variables,,, cl, Common Lisp Extensions}). -@var{place} can also be a cons @code{(@var{get} . @var{set})}, -where @var{get} is an expression that returns the current state, -and @var{set} is a function of one argument (a state) that sets it. - -@item :after-hook @var{after-hook} -This defines a single Lisp form which is evaluated after the mode hooks -have run. It should not be quoted. -@end table - -Any other keyword arguments are passed directly to the -@code{defcustom} generated for the variable @var{mode}. - -The command named @var{mode} first performs the standard actions such as -setting the variable named @var{mode} and then executes the @var{body} -forms, if any. It then runs the mode hook variable -@code{@var{mode}-hook} and finishes by evaluating any form in -@code{:after-hook}. -@end defmac - - The initial value must be @code{nil} except in cases where (1) the -mode is preloaded in Emacs, or (2) it is painless for loading to -enable the mode even though the user did not request it. For -instance, if the mode has no effect unless something else is enabled, -and will always be loaded by that time, enabling it by default is -harmless. But these are unusual circumstances. Normally, the -initial value must be @code{nil}. - -@findex easy-mmode-define-minor-mode - The name @code{easy-mmode-define-minor-mode} is an alias -for this macro. - - Here is an example of using @code{define-minor-mode}: - -@smallexample -(define-minor-mode hungry-mode - "Toggle Hungry mode. -Interactively with no argument, this command toggles the mode. -A positive prefix argument enables the mode, any other prefix -argument disables it. From Lisp, argument omitted or nil enables -the mode, `toggle' toggles the state. - -When Hungry mode is enabled, the control delete key -gobbles all preceding whitespace except the last. -See the command \\[hungry-electric-delete]." - ;; The initial value. - nil - ;; The indicator for the mode line. - " Hungry" - ;; The minor mode bindings. - '(([C-backspace] . hungry-electric-delete)) - :group 'hunger) -@end smallexample - -@noindent -This defines a minor mode named ``Hungry mode'', a command named -@code{hungry-mode} to toggle it, a variable named @code{hungry-mode} -which indicates whether the mode is enabled, and a variable named -@code{hungry-mode-map} which holds the keymap that is active when the -mode is enabled. It initializes the keymap with a key binding for -@kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into -custom group @code{hunger}. There are no @var{body} forms---many -minor modes don't need any. - - Here's an equivalent way to write it: - -@smallexample -(define-minor-mode hungry-mode - "Toggle Hungry mode. -...rest of documentation as before..." - ;; The initial value. - :init-value nil - ;; The indicator for the mode line. - :lighter " Hungry" - ;; The minor mode bindings. - :keymap - '(([C-backspace] . hungry-electric-delete) - ([C-M-backspace] - . (lambda () - (interactive) - (hungry-electric-delete t)))) - :group 'hunger) -@end smallexample - -@defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{} -This defines a global toggle named @var{global-mode} whose meaning is -to enable or disable the buffer-local minor mode @var{mode} in all -buffers. To turn on the minor mode in a buffer, it uses the function -@var{turn-on}; to turn off the minor mode, it calls @code{mode} with -@minus{}1 as argument. - -Globally enabling the mode also affects buffers subsequently created -by visiting files, and buffers that use a major mode other than -Fundamental mode; but it does not detect the creation of a new buffer -in Fundamental mode. - -This defines the customization option @var{global-mode} (@pxref{Customization}), -which can be toggled in the Customize interface to turn the minor mode on -and off. As with @code{define-minor-mode}, you should ensure that the -@code{define-globalized-minor-mode} form is evaluated each time Emacs -starts, for example by providing a @code{:require} keyword. - -Use @code{:group @var{group}} in @var{keyword-args} to specify the -custom group for the mode variable of the global minor mode. - -Generally speaking, when you define a globalized minor mode, you should -also define a non-globalized version, so that people can use (or -disable) it in individual buffers. This also allows them to disable a -globally enabled minor mode in a specific major mode, by using that -mode's hook. -@end defmac - - -@node Mode Line Format -@section Mode Line Format -@cindex mode line - - Each Emacs window (aside from minibuffer windows) typically has a mode -line at the bottom, which displays status information about the buffer -displayed in the window. The mode line contains information about the -buffer, such as its name, associated file, depth of recursive editing, -and major and minor modes. A window can also have a @dfn{header -line}, which is much like the mode line but appears at the top of the -window. - - This section describes how to control the contents of the mode line -and header line. We include it in this chapter because much of the -information displayed in the mode line relates to the enabled major and -minor modes. - -@menu -* Base: Mode Line Basics. Basic ideas of mode line control. -* Data: Mode Line Data. The data structure that controls the mode line. -* Top: Mode Line Top. The top level variable, mode-line-format. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. -* Properties in Mode:: Using text properties in the mode line. -* Header Lines:: Like a mode line, but at the top. -* Emulating Mode Line:: Formatting text as the mode line would. -@end menu - -@node Mode Line Basics -@subsection Mode Line Basics - - The contents of each mode line are specified by the buffer-local -variable @code{mode-line-format} (@pxref{Mode Line Top}). This variable -holds a @dfn{mode line construct}: a template that controls what is -displayed on the buffer's mode line. The value of -@code{header-line-format} specifies the buffer's header line in the same -way. All windows for the same buffer use the same -@code{mode-line-format} and @code{header-line-format}. - - For efficiency, Emacs does not continuously recompute each window's -mode line and header line. It does so when circumstances appear to call -for it---for instance, if you change the window configuration, switch -buffers, narrow or widen the buffer, scroll, or modify the buffer. If -you alter any of the variables referenced by @code{mode-line-format} or -@code{header-line-format} (@pxref{Mode Line Variables}), or any other -data structures that affect how text is displayed (@pxref{Display}), you -should use the function @code{force-mode-line-update} to update the -display. - -@defun force-mode-line-update &optional all -This function forces Emacs to update the current buffer's mode line and -header line, based on the latest values of all relevant variables, -during its next redisplay cycle. If the optional argument @var{all} is -non-@code{nil}, it forces an update for all mode lines and header lines. - -This function also forces an update of the menu bar and frame title. -@end defun - - The selected window's mode line is usually displayed in a different -color using the face @code{mode-line}. Other windows' mode lines appear -in the face @code{mode-line-inactive} instead. @xref{Faces}. - -@node Mode Line Data -@subsection The Data Structure of the Mode Line -@cindex mode line construct - - The mode line contents are controlled by a data structure called a -@dfn{mode line construct}, made up of lists, strings, symbols, and -numbers kept in buffer-local variables. Each data type has a specific -meaning for the mode line appearance, as described below. The same data -structure is used for constructing frame titles (@pxref{Frame Titles}) -and header lines (@pxref{Header Lines}). - - A mode line construct may be as simple as a fixed string of text, -but it usually specifies how to combine fixed strings with variables' -values to construct the text. Many of these variables are themselves -defined to have mode line constructs as their values. - - Here are the meanings of various data types as mode line constructs: - -@table @code -@cindex percent symbol in mode line -@item @var{string} -A string as a mode line construct appears verbatim except for -@dfn{@code{%}-constructs} in it. These stand for substitution of -other data; see @ref{%-Constructs}. - -If parts of the string have @code{face} properties, they control -display of the text just as they would text in the buffer. Any -characters which have no @code{face} properties are displayed, by -default, in the face @code{mode-line} or @code{mode-line-inactive} -(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The -@code{help-echo} and @code{local-map} properties in @var{string} have -special meanings. @xref{Properties in Mode}. - -@item @var{symbol} -A symbol as a mode line construct stands for its value. The value of -@var{symbol} is used as a mode line construct, in place of @var{symbol}. -However, the symbols @code{t} and @code{nil} are ignored, as is any -symbol whose value is void. - -There is one exception: if the value of @var{symbol} is a string, it is -displayed verbatim: the @code{%}-constructs are not recognized. - -Unless @var{symbol} is marked as ``risky'' (i.e., it has a -non-@code{nil} @code{risky-local-variable} property), all text -properties specified in @var{symbol}'s value are ignored. This includes -the text properties of strings in @var{symbol}'s value, as well as all -@code{:eval} and @code{:propertize} forms in it. (The reason for this -is security: non-risky variables could be set automatically from file -variables without prompting the user.) - -@item (@var{string} @var{rest}@dots{}) -@itemx (@var{list} @var{rest}@dots{}) -A list whose first element is a string or list means to process all the -elements recursively and concatenate the results. This is the most -common form of mode line construct. - -@item (:eval @var{form}) -A list whose first element is the symbol @code{:eval} says to evaluate -@var{form}, and use the result as a string to display. Make sure this -evaluation cannot load any files, as doing so could cause infinite -recursion. - -@item (:propertize @var{elt} @var{props}@dots{}) -A list whose first element is the symbol @code{:propertize} says to -process the mode line construct @var{elt} recursively, then add the text -properties specified by @var{props} to the result. The argument -@var{props} should consist of zero or more pairs @var{text-property} -@var{value}. - -@item (@var{symbol} @var{then} @var{else}) -A list whose first element is a symbol that is not a keyword specifies -a conditional. Its meaning depends on the value of @var{symbol}. If -@var{symbol} has a non-@code{nil} value, the second element, -@var{then}, is processed recursively as a mode line element. -Otherwise, the third element, @var{else}, is processed recursively. -You may omit @var{else}; then the mode line element displays nothing -if the value of @var{symbol} is @code{nil} or void. - -@item (@var{width} @var{rest}@dots{}) -A list whose first element is an integer specifies truncation or -padding of the results of @var{rest}. The remaining elements -@var{rest} are processed recursively as mode line constructs and -concatenated together. When @var{width} is positive, the result is -space filled on the right if its width is less than @var{width}. When -@var{width} is negative, the result is truncated on the right to -@minus{}@var{width} columns if its width exceeds @minus{}@var{width}. - -For example, the usual way to show what percentage of a buffer is above -the top of the window is to use a list like this: @code{(-3 "%p")}. -@end table - -@node Mode Line Top -@subsection The Top Level of Mode Line Control - - The variable in overall control of the mode line is -@code{mode-line-format}. - -@defopt mode-line-format -The value of this variable is a mode line construct that controls the -contents of the mode-line. It is always buffer-local in all buffers. - -If you set this variable to @code{nil} in a buffer, that buffer does not -have a mode line. (A window that is just one line tall also does not -display a mode line.) -@end defopt - - The default value of @code{mode-line-format} is designed to use the -values of other variables such as @code{mode-line-position} and -@code{mode-line-modes} (which in turn incorporates the values of the -variables @code{mode-name} and @code{minor-mode-alist}). Very few -modes need to alter @code{mode-line-format} itself. For most -purposes, it is sufficient to alter some of the variables that -@code{mode-line-format} either directly or indirectly refers to. - - If you do alter @code{mode-line-format} itself, the new value should -use the same variables that appear in the default value (@pxref{Mode -Line Variables}), rather than duplicating their contents or displaying -the information in another fashion. This way, customizations made by -the user or by Lisp programs (such as @code{display-time} and major -modes) via changes to those variables remain effective. - - Here is a hypothetical example of a @code{mode-line-format} that might -be useful for Shell mode (in reality, Shell mode does not set -@code{mode-line-format}): - -@example -@group -(setq mode-line-format - (list "-" - 'mode-line-mule-info - 'mode-line-modified - 'mode-line-frame-identification - "%b--" -@end group -@group - ;; @r{Note that this is evaluated while making the list.} - ;; @r{It makes a mode line construct which is just a string.} - (getenv "HOST") -@end group - ":" - 'default-directory - " " - 'global-mode-string - " %[(" - '(:eval (mode-line-mode-name)) - 'mode-line-process - 'minor-mode-alist - "%n" - ")%]--" -@group - '(which-func-mode ("" which-func-format "--")) - '(line-number-mode "L%l--") - '(column-number-mode "C%c--") - '(-3 "%p"))) -@end group -@end example - -@noindent -(The variables @code{line-number-mode}, @code{column-number-mode} -and @code{which-func-mode} enable particular minor modes; as usual, -these variable names are also the minor mode command names.) - -@node Mode Line Variables -@subsection Variables Used in the Mode Line - - This section describes variables incorporated by the standard value of -@code{mode-line-format} into the text of the mode line. There is -nothing inherently special about these variables; any other variables -could have the same effects on the mode line if the value of -@code{mode-line-format} is changed to use them. However, various parts -of Emacs set these variables on the understanding that they will control -parts of the mode line; therefore, practically speaking, it is essential -for the mode line to use them. - -@defvar mode-line-mule-info -This variable holds the value of the mode line construct that displays -information about the language environment, buffer coding system, and -current input method. @xref{Non-ASCII Characters}. -@end defvar - -@defvar mode-line-modified -This variable holds the value of the mode line construct that displays -whether the current buffer is modified. Its default value displays -@samp{**} if the buffer is modified, @samp{--} if the buffer is not -modified, @samp{%%} if the buffer is read only, and @samp{%*} if the -buffer is read only and modified. - -Changing this variable does not force an update of the mode line. -@end defvar - -@defvar mode-line-frame-identification -This variable identifies the current frame. Its default value -displays @code{" "} if you are using a window system which can show -multiple frames, or @code{"-%F "} on an ordinary terminal which shows -only one frame at a time. -@end defvar - -@defvar mode-line-buffer-identification -This variable identifies the buffer being displayed in the window. -Its default value displays the buffer name, padded with spaces to at -least 12 columns. -@end defvar - -@defopt mode-line-position -This variable indicates the position in the buffer. Its default value -displays the buffer percentage and, optionally, the buffer size, the -line number and the column number. -@end defopt - -@defvar vc-mode -The variable @code{vc-mode}, buffer-local in each buffer, records -whether the buffer's visited file is maintained with version control, -and, if so, which kind. Its value is a string that appears in the mode -line, or @code{nil} for no version control. -@end defvar - -@defopt mode-line-modes -This variable displays the buffer's major and minor modes. Its -default value also displays the recursive editing level, information -on the process status, and whether narrowing is in effect. -@end defopt - -@defvar mode-line-remote -This variable is used to show whether @code{default-directory} for the -current buffer is remote. -@end defvar - -@defvar mode-line-client -This variable is used to identify @code{emacsclient} frames. -@end defvar - - The following three variables are used in @code{mode-line-modes}: - -@defvar mode-name -This buffer-local variable holds the ``pretty'' name of the current -buffer's major mode. Each major mode should set this variable so that -the mode name will appear in the mode line. The value does not have -to be a string, but can use any of the data types valid in a mode-line -construct (@pxref{Mode Line Data}). To compute the string that will -identify the mode name in the mode line, use @code{format-mode-line} -(@pxref{Emulating Mode Line}). -@end defvar - -@defvar mode-line-process -This buffer-local variable contains the mode line information on process -status in modes used for communicating with subprocesses. It is -displayed immediately following the major mode name, with no intervening -space. For example, its value in the @file{*shell*} buffer is -@code{(":%s")}, which allows the shell to display its status along -with the major mode as: @samp{(Shell:run)}. Normally this variable -is @code{nil}. -@end defvar - -@defvar minor-mode-alist -@anchor{Definition of minor-mode-alist} -This variable holds an association list whose elements specify how the -mode line should indicate that a minor mode is active. Each element of -the @code{minor-mode-alist} should be a two-element list: - -@example -(@var{minor-mode-variable} @var{mode-line-string}) -@end example - -More generally, @var{mode-line-string} can be any mode line construct. -It appears in the mode line when the value of @var{minor-mode-variable} -is non-@code{nil}, and not otherwise. These strings should begin with -spaces so that they don't run together. Conventionally, the -@var{minor-mode-variable} for a specific mode is set to a non-@code{nil} -value when that minor mode is activated. - -@code{minor-mode-alist} itself is not buffer-local. Each variable -mentioned in the alist should be buffer-local if its minor mode can be -enabled separately in each buffer. -@end defvar - -@defvar global-mode-string -This variable holds a mode line construct that, by default, appears in -the mode line just after the @code{which-func-mode} minor mode if set, -else after @code{mode-line-modes}. The command @code{display-time} sets -@code{global-mode-string} to refer to the variable -@code{display-time-string}, which holds a string containing the time and -load information. - -The @samp{%M} construct substitutes the value of -@code{global-mode-string}, but that is obsolete, since the variable is -included in the mode line from @code{mode-line-format}. -@end defvar - -Here is a simplified version of the default value of -@code{mode-line-format}. The real default value also -specifies addition of text properties. - -@example -@group -("-" - mode-line-mule-info - mode-line-modified - mode-line-frame-identification - mode-line-buffer-identification -@end group - " " - mode-line-position - (vc-mode vc-mode) - " " -@group - mode-line-modes - (which-func-mode ("" which-func-format "--")) - (global-mode-string ("--" global-mode-string)) - "-%-") -@end group -@end example - -@node %-Constructs -@subsection @code{%}-Constructs in the Mode Line - - Strings used as mode line constructs can use certain -@code{%}-constructs to substitute various kinds of data. Here is a -list of the defined @code{%}-constructs, and what they mean. In any -construct except @samp{%%}, you can add a decimal integer after the -@samp{%} to specify a minimum field width. If the width is less, the -field is padded with spaces to the right. - -@table @code -@item %b -The current buffer name, obtained with the @code{buffer-name} function. -@xref{Buffer Names}. - -@item %c -The current column number of point. - -@item %e -When Emacs is nearly out of memory for Lisp objects, a brief message -saying so. Otherwise, this is empty. - -@item %f -The visited file name, obtained with the @code{buffer-file-name} -function. @xref{Buffer File Name}. - -@item %F -The title (only on a window system) or the name of the selected frame. -@xref{Basic Parameters}. - -@item %i -The size of the accessible part of the current buffer; basically -@code{(- (point-max) (point-min))}. - -@item %I -Like @samp{%i}, but the size is printed in a more readable way by using -@samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to -abbreviate. - -@item %l -The current line number of point, counting within the accessible portion -of the buffer. - -@item %n -@samp{Narrow} when narrowing is in effect; nothing otherwise (see -@code{narrow-to-region} in @ref{Narrowing}). - -@item %p -The percentage of the buffer text above the @strong{top} of window, or -@samp{Top}, @samp{Bottom} or @samp{All}. Note that the default mode -line construct truncates this to three characters. - -@item %P -The percentage of the buffer text that is above the @strong{bottom} of -the window (which includes the text visible in the window, as well as -the text above the top), plus @samp{Top} if the top of the buffer is -visible on screen; or @samp{Bottom} or @samp{All}. - -@item %s -The status of the subprocess belonging to the current buffer, obtained with -@code{process-status}. @xref{Process Information}. - -@item %t -Whether the visited file is a text file or a binary file. This is a -meaningful distinction only on certain operating systems (@pxref{MS-DOS -File Types}). - -@item %z -The mnemonics of keyboard, terminal, and buffer coding systems. - -@item %Z -Like @samp{%z}, but including the end-of-line format. - -@item %* -@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* -@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* -@samp{-} otherwise. @xref{Buffer Modification}. - -@item %+ -@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* -@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* -@samp{-} otherwise. This differs from @samp{%*} only for a modified -read-only buffer. @xref{Buffer Modification}. - -@item %& -@samp{*} if the buffer is modified, and @samp{-} otherwise. - -@item %[ -An indication of the depth of recursive editing levels (not counting -minibuffer levels): one @samp{[} for each editing level. -@xref{Recursive Editing}. - -@item %] -One @samp{]} for each recursive editing level (not counting minibuffer -levels). - -@item %- -Dashes sufficient to fill the remainder of the mode line. - -@item %% -The character @samp{%}---this is how to include a literal @samp{%} in a -string in which @code{%}-constructs are allowed. -@end table - -The following two @code{%}-constructs are still supported, but they are -obsolete, since you can get the same results with the variables -@code{mode-name} and @code{global-mode-string}. - -@table @code -@item %m -The value of @code{mode-name}. - -@item %M -The value of @code{global-mode-string}. -@end table - -@node Properties in Mode -@subsection Properties in the Mode Line -@cindex text properties in the mode line - - Certain text properties are meaningful in the -mode line. The @code{face} property affects the appearance of text; the -@code{help-echo} property associates help strings with the text, and -@code{local-map} can make the text mouse-sensitive. - - There are four ways to specify text properties for text in the mode -line: - -@enumerate -@item -Put a string with a text property directly into the mode line data -structure. - -@item -Put a text property on a mode line %-construct such as @samp{%12b}; then -the expansion of the %-construct will have that same text property. - -@item -Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to -give @var{elt} a text property specified by @var{props}. - -@item -Use a list containing @code{:eval @var{form}} in the mode line data -structure, and make @var{form} evaluate to a string that has a text -property. -@end enumerate - - You can use the @code{local-map} property to specify a keymap. This -keymap only takes real effect for mouse clicks; binding character keys -and function keys to it has no effect, since it is impossible to move -point into the mode line. - - When the mode line refers to a variable which does not have a -non-@code{nil} @code{risky-local-variable} property, any text -properties given or specified within that variable's values are -ignored. This is because such properties could otherwise specify -functions to be called, and those functions could come from file -local variables. - -@node Header Lines -@subsection Window Header Lines -@cindex header line (of a window) -@cindex window header line - - A window can have a @dfn{header line} at the top, just as it can have -a mode line at the bottom. The header line feature works just like the -mode line feature, except that it's controlled by -@code{header-line-format}: - -@defvar header-line-format -This variable, local in every buffer, specifies how to display the -header line, for windows displaying the buffer. The format of the value -is the same as for @code{mode-line-format} (@pxref{Mode Line Data}). -It is normally @code{nil}, so that ordinary buffers have no header line. -@end defvar - - A window that is just one line tall never displays a header line. A -window that is two lines tall cannot display both a mode line and a -header line at once; if it has a mode line, then it does not display a -header line. - -@node Emulating Mode Line -@subsection Emulating Mode Line Formatting - - You can use the function @code{format-mode-line} to compute the text -that would appear in a mode line or header line based on a certain -mode line construct. - -@defun format-mode-line format &optional face window buffer -This function formats a line of text according to @var{format} as if it -were generating the mode line for @var{window}, but it also returns the -text as a string. The argument @var{window} defaults to the selected -window. If @var{buffer} is non-@code{nil}, all the information used is -taken from @var{buffer}; by default, it comes from @var{window}'s -buffer. - -The value string normally has text properties that correspond to the -faces, keymaps, etc., that the mode line would have. Any character for -which no @code{face} property is specified by @var{format} gets a -default value determined by @var{face}. If @var{face} is @code{t}, that -stands for either @code{mode-line} if @var{window} is selected, -otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or -omitted, that stands for the default face. If @var{face} is an integer, -the value returned by this function will have no text properties. - -You can also specify other valid faces as the value of @var{face}. -If specified, that face provides the @code{face} property for characters -whose face is not specified by @var{format}. - -Note that using @code{mode-line}, @code{mode-line-inactive}, or -@code{header-line} as @var{face} will actually redisplay the mode line -or the header line, respectively, using the current definitions of the -corresponding face, in addition to returning the formatted string. -(Other faces do not cause redisplay.) - -For example, @code{(format-mode-line header-line-format)} returns the -text that would appear in the selected window's header line (@code{""} -if it has no header line). @code{(format-mode-line header-line-format -'header-line)} returns the same text, with each character -carrying the face that it will have in the header line itself, and also -redraws the header line. -@end defun - -@node Imenu -@section Imenu - -@cindex Imenu - @dfn{Imenu} is a feature that lets users select a definition or -section in the buffer, from a menu which lists all of them, to go -directly to that location in the buffer. Imenu works by constructing -a buffer index which lists the names and buffer positions of the -definitions, or other named portions of the buffer; then the user can -choose one of them and move point to it. Major modes can add a menu -bar item to use Imenu using @code{imenu-add-to-menubar}. - -@deffn Command imenu-add-to-menubar name -This function defines a local menu bar item named @var{name} -to run Imenu. -@end deffn - - The user-level commands for using Imenu are described in the Emacs -Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section -explains how to customize Imenu's method of finding definitions or -buffer portions for a particular major mode. - - The usual and simplest way is to set the variable -@code{imenu-generic-expression}: - -@defvar imenu-generic-expression -This variable, if non-@code{nil}, is a list that specifies regular -expressions for finding definitions for Imenu. Simple elements of -@code{imenu-generic-expression} look like this: - -@example -(@var{menu-title} @var{regexp} @var{index}) -@end example - -Here, if @var{menu-title} is non-@code{nil}, it says that the matches -for this element should go in a submenu of the buffer index; -@var{menu-title} itself specifies the name for the submenu. If -@var{menu-title} is @code{nil}, the matches for this element go directly -in the top level of the buffer index. - -The second item in the list, @var{regexp}, is a regular expression -(@pxref{Regular Expressions}); anything in the buffer that it matches -is considered a definition, something to mention in the buffer index. -The third item, @var{index}, is a non-negative integer that indicates -which subexpression in @var{regexp} matches the definition's name. - -An element can also look like this: - -@example -(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{}) -@end example - -Each match for this element creates an index item, and when the index -item is selected by the user, it calls @var{function} with arguments -consisting of the item name, the buffer position, and @var{arguments}. - -For Emacs Lisp mode, @code{imenu-generic-expression} could look like -this: - -@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+] -@example -@group -((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\ -\\s-+\\([-A-Za-z0-9+]+\\)" 2) -@end group -@group - ("*Vars*" "^\\s-*(def\\(var\\|const\\)\ -\\s-+\\([-A-Za-z0-9+]+\\)" 2) -@end group -@group - ("*Types*" - "^\\s-*\ -(def\\(type\\|struct\\|class\\|ine-condition\\)\ -\\s-+\\([-A-Za-z0-9+]+\\)" 2)) -@end group -@end example - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@defvar imenu-case-fold-search -This variable controls whether matching against the regular -expressions in the value of @code{imenu-generic-expression} is -case-sensitive: @code{t}, the default, means matching should ignore -case. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@defvar imenu-syntax-alist -This variable is an alist of syntax table modifiers to use while -processing @code{imenu-generic-expression}, to override the syntax table -of the current buffer. Each element should have this form: - -@example -(@var{characters} . @var{syntax-description}) -@end example - -The @sc{car}, @var{characters}, can be either a character or a string. -The element says to give that character or characters the syntax -specified by @var{syntax-description}, which is passed to -@code{modify-syntax-entry} (@pxref{Syntax Table Functions}). - -This feature is typically used to give word syntax to characters which -normally have symbol syntax, and thus to simplify -@code{imenu-generic-expression} and speed up matching. -For example, Fortran mode uses it this way: - -@example -(setq imenu-syntax-alist '(("_$" . "w"))) -@end example - -The @code{imenu-generic-expression} regular expressions can then use -@samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this -technique may be inconvenient when the mode needs to limit the initial -character of a name to a smaller set of characters than are allowed in -the rest of a name. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - - Another way to customize Imenu for a major mode is to set the -variables @code{imenu-prev-index-position-function} and -@code{imenu-extract-index-name-function}: - -@defvar imenu-prev-index-position-function -If this variable is non-@code{nil}, its value should be a function that -finds the next ``definition'' to put in the buffer index, scanning -backward in the buffer from point. It should return @code{nil} if it -doesn't find another ``definition'' before point. Otherwise it should -leave point at the place it finds a ``definition'' and return any -non-@code{nil} value. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@defvar imenu-extract-index-name-function -If this variable is non-@code{nil}, its value should be a function to -return the name for a definition, assuming point is in that definition -as the @code{imenu-prev-index-position-function} function would leave -it. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - - The last way to customize Imenu for a major mode is to set the -variable @code{imenu-create-index-function}: - -@defvar imenu-create-index-function -This variable specifies the function to use for creating a buffer -index. The function should take no arguments, and return an index -alist for the current buffer. It is called within -@code{save-excursion}, so where it leaves point makes no difference. - -The index alist can have three types of elements. Simple elements -look like this: - -@example -(@var{index-name} . @var{index-position}) -@end example - -Selecting a simple element has the effect of moving to position -@var{index-position} in the buffer. Special elements look like this: - -@example -(@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{}) -@end example - -Selecting a special element performs: - -@example -(funcall @var{function} - @var{index-name} @var{index-position} @var{arguments}@dots{}) -@end example - -A nested sub-alist element looks like this: - -@example -(@var{menu-title} @var{sub-alist}) -@end example - -It creates the submenu @var{menu-title} specified by @var{sub-alist}. - -The default value of @code{imenu-create-index-function} is -@code{imenu-default-create-index-function}. This function calls the -value of @code{imenu-prev-index-position-function} and the value of -@code{imenu-extract-index-name-function} to produce the index alist. -However, if either of these two variables is @code{nil}, the default -function uses @code{imenu-generic-expression} instead. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@node Font Lock Mode -@section Font Lock Mode -@cindex Font Lock mode - - @dfn{Font Lock mode} is a buffer-local minor mode that automatically -attaches @code{face} properties to certain parts of the buffer based on -their syntactic role. How it parses the buffer depends on the major -mode; most major modes define syntactic criteria for which faces to use -in which contexts. This section explains how to customize Font Lock for -a particular major mode. - - Font Lock mode finds text to highlight in two ways: through -syntactic parsing based on the syntax table, and through searching -(usually for regular expressions). Syntactic fontification happens -first; it finds comments and string constants and highlights them. -Search-based fontification happens second. - -@menu -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. -@end menu - -@node Font Lock Basics -@subsection Font Lock Basics - - There are several variables that control how Font Lock mode highlights -text. But major modes should not set any of these variables directly. -Instead, they should set @code{font-lock-defaults} as a buffer-local -variable. The value assigned to this variable is used, if and when Font -Lock mode is enabled, to set all the other variables. - -@defvar font-lock-defaults -This variable is set by major modes to specify how to fontify text in -that mode. It automatically becomes buffer-local when set. If its -value is @code{nil}, Font Lock mode does no highlighting, and you can -use the @samp{Faces} menu (under @samp{Edit} and then @samp{Text -Properties} in the menu bar) to assign faces explicitly to text in the -buffer. - -If non-@code{nil}, the value should look like this: - -@example -(@var{keywords} [@var{keywords-only} [@var{case-fold} - [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]]) -@end example - -The first element, @var{keywords}, indirectly specifies the value of -@code{font-lock-keywords} which directs search-based fontification. -It can be a symbol, a variable or a function whose value is the list -to use for @code{font-lock-keywords}. It can also be a list of -several such symbols, one for each possible level of fontification. -The first symbol specifies the @samp{mode default} level of -fontification, the next symbol level 1 fontification, the next level 2, -and so on. The @samp{mode default} level is normally the same as level -1. It is used when @code{font-lock-maximum-decoration} has a @code{nil} -value. @xref{Levels of Font Lock}. - -The second element, @var{keywords-only}, specifies the value of the -variable @code{font-lock-keywords-only}. If this is omitted or -@code{nil}, syntactic fontification (of strings and comments) is also -performed. If this is non-@code{nil}, syntactic fontification is not -performed. @xref{Syntactic Font Lock}. - -The third element, @var{case-fold}, specifies the value of -@code{font-lock-keywords-case-fold-search}. If it is non-@code{nil}, -Font Lock mode ignores case during search-based fontification. - -If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should -be a list of cons cells of the form @code{(@var{char-or-string} -. @var{string})}. These are used to set up a syntax table for syntactic -fontification; the resulting syntax table is stored in -@code{font-lock-syntax-table}. If @var{syntax-alist} is omitted or -@code{nil}, syntactic fontification uses the syntax table returned by -the @code{syntax-table} function. @xref{Syntax Table Functions}. - -The fifth element, @var{syntax-begin}, specifies the value of -@code{font-lock-beginning-of-syntax-function}. We recommend setting -this variable to @code{nil} and using @code{syntax-begin-function} -instead. - -All the remaining elements (if any) are collectively called -@var{other-vars}. Each of these elements should have the form -@code{(@var{variable} . @var{value})}---which means, make -@var{variable} buffer-local and then set it to @var{value}. You can -use these @var{other-vars} to set other variables that affect -fontification, aside from those you can control with the first five -elements. @xref{Other Font Lock Variables}. -@end defvar - - If your mode fontifies text explicitly by adding -@code{font-lock-face} properties, it can specify @code{(nil t)} for -@code{font-lock-defaults} to turn off all automatic fontification. -However, this is not required; it is possible to fontify some things -using @code{font-lock-face} properties and set up automatic -fontification for other parts of the text. - -@node Search-based Fontification -@subsection Search-based Fontification - - The variable which directly controls search-based fontification is -@code{font-lock-keywords}, which is typically specified via the -@var{keywords} element in @code{font-lock-defaults}. - -@defvar font-lock-keywords -The value of this variable is a list of the keywords to highlight. Lisp -programs should not set this variable directly. Normally, the value is -automatically set by Font Lock mode, using the @var{keywords} element in -@code{font-lock-defaults}. The value can also be altered using the -functions @code{font-lock-add-keywords} and -@code{font-lock-remove-keywords} (@pxref{Customizing Keywords}). -@end defvar - - Each element of @code{font-lock-keywords} specifies how to find -certain cases of text, and how to highlight those cases. Font Lock mode -processes the elements of @code{font-lock-keywords} one by one, and for -each element, it finds and handles all matches. Ordinarily, once -part of the text has been fontified already, this cannot be overridden -by a subsequent match in the same text; but you can specify different -behavior using the @var{override} element of a @var{subexp-highlighter}. - - Each element of @code{font-lock-keywords} should have one of these -forms: - -@table @code -@item @var{regexp} -Highlight all matches for @var{regexp} using -@code{font-lock-keyword-face}. For example, - -@example -;; @r{Highlight occurrences of the word @samp{foo}} -;; @r{using @code{font-lock-keyword-face}.} -"\\" -@end example - -Be careful when composing these regular expressions; a poorly written -pattern can dramatically slow things down! The function -@code{regexp-opt} (@pxref{Regexp Functions}) is useful for calculating -optimal regular expressions to match several keywords. - -@item @var{function} -Find text by calling @var{function}, and highlight the matches -it finds using @code{font-lock-keyword-face}. - -When @var{function} is called, it receives one argument, the limit of -the search; it should begin searching at point, and not search beyond the -limit. It should return non-@code{nil} if it succeeds, and set the -match data to describe the match that was found. Returning @code{nil} -indicates failure of the search. - -Fontification will call @var{function} repeatedly with the same limit, -and with point where the previous invocation left it, until -@var{function} fails. On failure, @var{function} need not reset point -in any particular way. - -@item (@var{matcher} . @var{subexp}) -In this kind of element, @var{matcher} is either a regular -expression or a function, as described above. The @sc{cdr}, -@var{subexp}, specifies which subexpression of @var{matcher} should be -highlighted (instead of the entire text that @var{matcher} matched). - -@example -;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},} -;; @r{using @code{font-lock-keyword-face}.} -("fu\\(bar\\)" . 1) -@end example - -If you use @code{regexp-opt} to produce the regular expression -@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp -Functions}) to calculate the value for @var{subexp}. - -@item (@var{matcher} . @var{facespec}) -In this kind of element, @var{facespec} is an expression whose value -specifies the face to use for highlighting. In the simplest case, -@var{facespec} is a Lisp variable (a symbol) whose value is a face -name. - -@example -;; @r{Highlight occurrences of @samp{fubar},} -;; @r{using the face which is the value of @code{fubar-face}.} -("fubar" . fubar-face) -@end example - -However, @var{facespec} can also evaluate to a list of this form: - -@example -(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{}) -@end example - -@noindent -to specify the face @var{face} and various additional text properties -to put on the text that matches. If you do this, be sure to add the -other text property names that you set in this way to the value of -@code{font-lock-extra-managed-props} so that the properties will also -be cleared out when they are no longer appropriate. Alternatively, -you can set the variable @code{font-lock-unfontify-region-function} to -a function that clears these properties. @xref{Other Font Lock -Variables}. - -@item (@var{matcher} . @var{subexp-highlighter}) -In this kind of element, @var{subexp-highlighter} is a list -which specifies how to highlight matches found by @var{matcher}. -It has the form: - -@example -(@var{subexp} @var{facespec} [@var{override} [@var{laxmatch}]]) -@end example - -The @sc{car}, @var{subexp}, is an integer specifying which subexpression -of the match to fontify (0 means the entire matching text). The second -subelement, @var{facespec}, is an expression whose value specifies the -face, as described above. - -The last two values in @var{subexp-highlighter}, @var{override} and -@var{laxmatch}, are optional flags. If @var{override} is @code{t}, -this element can override existing fontification made by previous -elements of @code{font-lock-keywords}. If it is @code{keep}, then -each character is fontified if it has not been fontified already by -some other element. If it is @code{prepend}, the face specified by -@var{facespec} is added to the beginning of the @code{font-lock-face} -property. If it is @code{append}, the face is added to the end of the -@code{font-lock-face} property. - -If @var{laxmatch} is non-@code{nil}, it means there should be no error -if there is no subexpression numbered @var{subexp} in @var{matcher}. -Obviously, fontification of the subexpression numbered @var{subexp} will -not occur. However, fontification of other subexpressions (and other -regexps) will continue. If @var{laxmatch} is @code{nil}, and the -specified subexpression is missing, then an error is signaled which -terminates search-based fontification. - -Here are some examples of elements of this kind, and what they do: - -@smallexample -;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using} -;; @r{@code{foo-bar-face}, even if they have already been highlighted.} -;; @r{@code{foo-bar-face} should be a variable whose value is a face.} -("foo\\|bar" 0 foo-bar-face t) - -;; @r{Highlight the first subexpression within each occurrence} -;; @r{that the function @code{fubar-match} finds,} -;; @r{using the face which is the value of @code{fubar-face}.} -(fubar-match 1 fubar-face) -@end smallexample - -@item (@var{matcher} . @var{anchored-highlighter}) -In this kind of element, @var{anchored-highlighter} specifies how to -highlight text that follows a match found by @var{matcher}. So a -match found by @var{matcher} acts as the anchor for further searches -specified by @var{anchored-highlighter}. @var{anchored-highlighter} -is a list of the following form: - -@example -(@var{anchored-matcher} @var{pre-form} @var{post-form} - @var{subexp-highlighters}@dots{}) -@end example - -Here, @var{anchored-matcher}, like @var{matcher}, is either a regular -expression or a function. After a match of @var{matcher} is found, -point is at the end of the match. Now, Font Lock evaluates the form -@var{pre-form}. Then it searches for matches of -@var{anchored-matcher} and uses @var{subexp-highlighters} to highlight -these. A @var{subexp-highlighter} is as described above. Finally, -Font Lock evaluates @var{post-form}. - -The forms @var{pre-form} and @var{post-form} can be used to initialize -before, and cleanup after, @var{anchored-matcher} is used. Typically, -@var{pre-form} is used to move point to some position relative to the -match of @var{matcher}, before starting with @var{anchored-matcher}. -@var{post-form} might be used to move back, before resuming with -@var{matcher}. - -After Font Lock evaluates @var{pre-form}, it does not search for -@var{anchored-matcher} beyond the end of the line. However, if -@var{pre-form} returns a buffer position that is greater than the -position of point after @var{pre-form} is evaluated, then the position -returned by @var{pre-form} is used as the limit of the search instead. -It is generally a bad idea to return a position greater than the end -of the line; in other words, the @var{anchored-matcher} search should -not span lines. - -For example, - -@smallexample -;; @r{Highlight occurrences of the word @samp{item} following} -;; @r{an occurrence of the word @samp{anchor} (on the same line)} -;; @r{in the value of @code{item-face}.} -("\\" "\\" nil nil (0 item-face)) -@end smallexample - -Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore -searching for @samp{item} starts at the end of the match of -@samp{anchor}, and searching for subsequent instances of @samp{anchor} -resumes from where searching for @samp{item} concluded. - -@item (@var{matcher} @var{highlighters}@dots{}) -This sort of element specifies several @var{highlighter} lists for a -single @var{matcher}. A @var{highlighter} list can be of the type -@var{subexp-highlighter} or @var{anchored-highlighter} as described -above. - -For example, - -@smallexample -;; @r{Highlight occurrences of the word @samp{anchor} in the value} -;; @r{of @code{anchor-face}, and subsequent occurrences of the word} -;; @r{@samp{item} (on the same line) in the value of @code{item-face}.} -("\\" (0 anchor-face) - ("\\" nil nil (0 item-face))) -@end smallexample - -@item (eval . @var{form}) -Here @var{form} is an expression to be evaluated the first time -this value of @code{font-lock-keywords} is used in a buffer. -Its value should have one of the forms described in this table. -@end table - -@strong{Warning:} Do not design an element of @code{font-lock-keywords} -to match text which spans lines; this does not work reliably. -For details, see @xref{Multiline Font Lock}. - -You can use @var{case-fold} in @code{font-lock-defaults} to specify -the value of @code{font-lock-keywords-case-fold-search} which says -whether search-based fontification should be case-insensitive. - -@defvar font-lock-keywords-case-fold-search -Non-@code{nil} means that regular expression matching for the sake of -@code{font-lock-keywords} should be case-insensitive. -@end defvar - -@node Customizing Keywords -@subsection Customizing Search-Based Fontification - - You can use @code{font-lock-add-keywords} to add additional -search-based fontification rules to a major mode, and -@code{font-lock-remove-keywords} to remove rules. - -@defun font-lock-add-keywords mode keywords &optional how -This function adds highlighting @var{keywords}, for the current buffer -or for major mode @var{mode}. The argument @var{keywords} should be a -list with the same format as the variable @code{font-lock-keywords}. - -If @var{mode} is a symbol which is a major mode command name, such as -@code{c-mode}, the effect is that enabling Font Lock mode in -@var{mode} will add @var{keywords} to @code{font-lock-keywords}. -Calling with a non-@code{nil} value of @var{mode} is correct only in -your @file{~/.emacs} file. - -If @var{mode} is @code{nil}, this function adds @var{keywords} to -@code{font-lock-keywords} in the current buffer. This way of calling -@code{font-lock-add-keywords} is usually used in mode hook functions. - -By default, @var{keywords} are added at the beginning of -@code{font-lock-keywords}. If the optional argument @var{how} is -@code{set}, they are used to replace the value of -@code{font-lock-keywords}. If @var{how} is any other non-@code{nil} -value, they are added at the end of @code{font-lock-keywords}. - -Some modes provide specialized support you can use in additional -highlighting patterns. See the variables -@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types}, -and @code{java-font-lock-extra-types}, for example. - -@strong{Warning:} Major mode commands must not call -@code{font-lock-add-keywords} under any circumstances, either directly -or indirectly, except through their mode hooks. (Doing so would lead to -incorrect behavior for some minor modes.) They should set up their -rules for search-based fontification by setting -@code{font-lock-keywords}. -@end defun - -@defun font-lock-remove-keywords mode keywords -This function removes @var{keywords} from @code{font-lock-keywords} -for the current buffer or for major mode @var{mode}. As in -@code{font-lock-add-keywords}, @var{mode} should be a major mode -command name or @code{nil}. All the caveats and requirements for -@code{font-lock-add-keywords} apply here too. -@end defun - - For example, the following code adds two fontification patterns for C -mode: one to fontify the word @samp{FIXME}, even in comments, and -another to fontify the words @samp{and}, @samp{or} and @samp{not} as -keywords. - -@smallexample -(font-lock-add-keywords 'c-mode - '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) - ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face))) -@end smallexample - -@noindent -This example affects only C mode proper. To add the same patterns to C -mode @emph{and} all modes derived from it, do this instead: - -@smallexample -(add-hook 'c-mode-hook - (lambda () - (font-lock-add-keywords nil - '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) - ("\\<\\(and\\|or\\|not\\)\\>" . - font-lock-keyword-face))))) -@end smallexample - -@node Other Font Lock Variables -@subsection Other Font Lock Variables - - This section describes additional variables that a major mode can -set by means of @var{other-vars} in @code{font-lock-defaults} -(@pxref{Font Lock Basics}). - -@defvar font-lock-mark-block-function -If this variable is non-@code{nil}, it should be a function that is -called with no arguments, to choose an enclosing range of text for -refontification for the command @kbd{M-o M-o} -(@code{font-lock-fontify-block}). - -The function should report its choice by placing the region around it. -A good choice is a range of text large enough to give proper results, -but not too large so that refontification becomes slow. Typical values -are @code{mark-defun} for programming modes or @code{mark-paragraph} for -textual modes. -@end defvar - -@defvar font-lock-extra-managed-props -This variable specifies additional properties (other than -@code{font-lock-face}) that are being managed by Font Lock mode. It -is used by @code{font-lock-default-unfontify-region}, which normally -only manages the @code{font-lock-face} property. If you want Font -Lock to manage other properties as well, you must specify them in a -@var{facespec} in @code{font-lock-keywords} as well as add them to -this list. @xref{Search-based Fontification}. -@end defvar - -@defvar font-lock-fontify-buffer-function -Function to use for fontifying the buffer. The default value is -@code{font-lock-default-fontify-buffer}. -@end defvar - -@defvar font-lock-unfontify-buffer-function -Function to use for unfontifying the buffer. This is used when -turning off Font Lock mode. The default value is -@code{font-lock-default-unfontify-buffer}. -@end defvar - -@defvar font-lock-fontify-region-function -Function to use for fontifying a region. It should take two -arguments, the beginning and end of the region, and an optional third -argument @var{verbose}. If @var{verbose} is non-@code{nil}, the -function should print status messages. The default value is -@code{font-lock-default-fontify-region}. -@end defvar - -@defvar font-lock-unfontify-region-function -Function to use for unfontifying a region. It should take two -arguments, the beginning and end of the region. The default value is -@code{font-lock-default-unfontify-region}. -@end defvar - -@defun jit-lock-register function &optional contextual -This function tells Font Lock mode to run the Lisp function -@var{function} any time it has to fontify or refontify part of the -current buffer. It calls @var{function} before calling the default -fontification functions, and gives it two arguments, @var{start} and -@var{end}, which specify the region to be fontified or refontified. - -The optional argument @var{contextual}, if non-@code{nil}, forces Font -Lock mode to always refontify a syntactically relevant part of the -buffer, and not just the modified lines. This argument can usually be -omitted. -@end defun - -@defun jit-lock-unregister function -If @var{function} was previously registered as a fontification -function using @code{jit-lock-register}, this function unregisters it. -@end defun - -@node Levels of Font Lock -@subsection Levels of Font Lock - - Some major modes offer three different levels of fontification. You -can define multiple levels by using a list of symbols for @var{keywords} -in @code{font-lock-defaults}. Each symbol specifies one level of -fontification; it is up to the user to choose one of these levels, -normally by setting @code{font-lock-maximum-decoration} (@pxref{Font -Lock,,, emacs, the GNU Emacs Manual}). The chosen level's symbol value -is used to initialize @code{font-lock-keywords}. - - Here are the conventions for how to define the levels of -fontification: - -@itemize @bullet -@item -Level 1: highlight function declarations, file directives (such as include or -import directives), strings and comments. The idea is speed, so only -the most important and top-level components are fontified. - -@item -Level 2: in addition to level 1, highlight all language keywords, -including type names that act like keywords, as well as named constant -values. The idea is that all keywords (either syntactic or semantic) -should be fontified appropriately. - -@item -Level 3: in addition to level 2, highlight the symbols being defined in -function and variable declarations, and all builtin function names, -wherever they appear. -@end itemize - -@node Precalculated Fontification -@subsection Precalculated Fontification - - Some major modes such as @code{list-buffers} and @code{occur} -construct the buffer text programmatically. The easiest way for them -to support Font Lock mode is to specify the faces of text when they -insert the text in the buffer. - - The way to do this is to specify the faces in the text with the -special text property @code{font-lock-face} (@pxref{Special -Properties}). When Font Lock mode is enabled, this property controls -the display, just like the @code{face} property. When Font Lock mode -is disabled, @code{font-lock-face} has no effect on the display. - - It is ok for a mode to use @code{font-lock-face} for some text and -also use the normal Font Lock machinery. But if the mode does not use -the normal Font Lock machinery, it should not set the variable -@code{font-lock-defaults}. - -@node Faces for Font Lock -@subsection Faces for Font Lock -@cindex faces for font lock -@cindex font lock faces - - Font Lock mode can highlight using any face, but Emacs defines several -faces specifically for Font Lock to use to highlight text. These -@dfn{Font Lock faces} are listed below. They can also be used by major -modes for syntactic highlighting outside of Font Lock mode (@pxref{Major -Mode Conventions}). - - Each of these symbols is both a face name, and a variable whose -default value is the symbol itself. Thus, the default value of -@code{font-lock-comment-face} is @code{font-lock-comment-face}. - - The faces are listed with descriptions of their typical usage, and in -order of greater to lesser ``prominence''. If a mode's syntactic -categories do not fit well with the usage descriptions, the faces can be -assigned using the ordering as a guide. - -@table @code -@item font-lock-warning-face -@vindex font-lock-warning-face -for a construct that is peculiar, or that greatly changes the meaning of -other text, like @samp{;;;###autoload} in Emacs Lisp and @samp{#error} -in C. - -@item font-lock-function-name-face -@vindex font-lock-function-name-face -for the name of a function being defined or declared. - -@item font-lock-variable-name-face -@vindex font-lock-variable-name-face -for the name of a variable being defined or declared. - -@item font-lock-keyword-face -@vindex font-lock-keyword-face -for a keyword with special syntactic significance, like @samp{for} and -@samp{if} in C. - -@item font-lock-comment-face -@vindex font-lock-comment-face -for comments. - -@item font-lock-comment-delimiter-face -@vindex font-lock-comment-delimiter-face -for comments delimiters, like @samp{/*} and @samp{*/} in C. On most -terminals, this inherits from @code{font-lock-comment-face}. - -@item font-lock-type-face -@vindex font-lock-type-face -for the names of user-defined data types. - -@item font-lock-constant-face -@vindex font-lock-constant-face -for the names of constants, like @samp{NULL} in C. - -@item font-lock-builtin-face -@vindex font-lock-builtin-face -for the names of built-in functions. - -@item font-lock-preprocessor-face -@vindex font-lock-preprocessor-face -for preprocessor commands. This inherits, by default, from -@code{font-lock-builtin-face}. - -@item font-lock-string-face -@vindex font-lock-string-face -for string constants. - -@item font-lock-doc-face -@vindex font-lock-doc-face -for documentation strings in the code. This inherits, by default, from -@code{font-lock-string-face}. - -@item font-lock-negation-char-face -@vindex font-lock-negation-char-face -for easily-overlooked negation characters. -@end table - -@node Syntactic Font Lock -@subsection Syntactic Font Lock -@cindex syntactic font lock - -Syntactic fontification uses a syntax table (@pxref{Syntax Tables}) to -find and highlight syntactically relevant text. If enabled, it runs -prior to search-based fontification. The variable -@code{font-lock-syntactic-face-function}, documented below, determines -which syntactic constructs to highlight. There are several variables -that affect syntactic fontification; you should set them by means of -@code{font-lock-defaults} (@pxref{Font Lock Basics}). - - Whenever Font Lock mode performs syntactic fontification on a stretch -of text, it first calls the function specified by -@code{syntax-propertize-function}. Major modes can use this to apply -@code{syntax-table} text properties to override the buffer's syntax -table in special cases. @xref{Syntax Properties}. - -@defvar font-lock-keywords-only -If the value of this variable is non-@code{nil}, Font Lock does not do -syntactic fontification, only search-based fontification based on -@code{font-lock-keywords}. It is normally set by Font Lock mode based -on the @var{keywords-only} element in @code{font-lock-defaults}. -@end defvar - -@defvar font-lock-syntax-table -This variable holds the syntax table to use for fontification of -comments and strings. It is normally set by Font Lock mode based on the -@var{syntax-alist} element in @code{font-lock-defaults}. If this value -is @code{nil}, syntactic fontification uses the buffer's syntax table -(the value returned by the function @code{syntax-table}; @pxref{Syntax -Table Functions}). -@end defvar - -@defvar font-lock-beginning-of-syntax-function -If this variable is non-@code{nil}, it should be a function to move -point back to a position that is syntactically at ``top level'' and -outside of strings or comments. The value is normally set through an -@var{other-vars} element in @code{font-lock-defaults}. If it is -@code{nil}, Font Lock uses @code{syntax-begin-function} to move back -outside of any comment, string, or sexp (@pxref{Position Parse}). - -This variable is semi-obsolete; we usually recommend setting -@code{syntax-begin-function} instead. One of its uses is to tune the -behavior of syntactic fontification, e.g.@: to ensure that different -kinds of strings or comments are highlighted differently. - -The specified function is called with no arguments. It should leave -point at the beginning of any enclosing syntactic block. Typical values -are @code{beginning-of-line} (used when the start of the line is known -to be outside a syntactic block), or @code{beginning-of-defun} for -programming modes, or @code{backward-paragraph} for textual modes. -@end defvar - -@defvar font-lock-syntactic-face-function -If this variable is non-@code{nil}, it should be a function to determine -which face to use for a given syntactic element (a string or a comment). -The value is normally set through an @var{other-vars} element in -@code{font-lock-defaults}. - -The function is called with one argument, the parse state at point -returned by @code{parse-partial-sexp}, and should return a face. The -default value returns @code{font-lock-comment-face} for comments and -@code{font-lock-string-face} for strings (@pxref{Faces for Font Lock}). -@end defvar - -@node Multiline Font Lock -@subsection Multiline Font Lock Constructs -@cindex multiline font lock - - Normally, elements of @code{font-lock-keywords} should not match -across multiple lines; that doesn't work reliably, because Font Lock -usually scans just part of the buffer, and it can miss a multi-line -construct that crosses the line boundary where the scan starts. (The -scan normally starts at the beginning of a line.) - - Making elements that match multiline constructs work properly has -two aspects: correct @emph{identification} and correct -@emph{rehighlighting}. The first means that Font Lock finds all -multiline constructs. The second means that Font Lock will correctly -rehighlight all the relevant text when a multiline construct is -changed---for example, if some of the text that was previously part of -a multiline construct ceases to be part of it. The two aspects are -closely related, and often getting one of them to work will appear to -make the other also work. However, for reliable results you must -attend explicitly to both aspects. - - There are three ways to ensure correct identification of multiline -constructs: - -@itemize -@item -Add a function to @code{font-lock-extend-region-functions} that does -the @emph{identification} and extends the scan so that the scanned -text never starts or ends in the middle of a multiline construct. -@item -Use the @code{font-lock-fontify-region-function} hook similarly to -extend the scan so that the scanned text never starts or ends in the -middle of a multiline construct. -@item -Somehow identify the multiline construct right when it gets inserted -into the buffer (or at any point after that but before font-lock -tries to highlight it), and mark it with a @code{font-lock-multiline} -which will instruct font-lock not to start or end the scan in the -middle of the construct. -@end itemize - - There are three ways to do rehighlighting of multiline constructs: - -@itemize -@item -Place a @code{font-lock-multiline} property on the construct. This -will rehighlight the whole construct if any part of it is changed. In -some cases you can do this automatically by setting the -@code{font-lock-multiline} variable, which see. -@item -Make sure @code{jit-lock-contextually} is set and rely on it doing its -job. This will only rehighlight the part of the construct that -follows the actual change, and will do it after a short delay. -This only works if the highlighting of the various parts of your -multiline construct never depends on text in subsequent lines. -Since @code{jit-lock-contextually} is activated by default, this can -be an attractive solution. -@item -Place a @code{jit-lock-defer-multiline} property on the construct. -This works only if @code{jit-lock-contextually} is used, and with the -same delay before rehighlighting, but like @code{font-lock-multiline}, -it also handles the case where highlighting depends on -subsequent lines. -@end itemize - -@menu -* Font Lock Multiline:: Marking multiline chunks with a text property. -* Region to Refontify:: Controlling which region gets refontified - after a buffer change. -@end menu - -@node Font Lock Multiline -@subsubsection Font Lock Multiline - - One way to ensure reliable rehighlighting of multiline Font Lock -constructs is to put on them the text property @code{font-lock-multiline}. -It should be present and non-@code{nil} for text that is part of a -multiline construct. - - When Font Lock is about to highlight a range of text, it first -extends the boundaries of the range as necessary so that they do not -fall within text marked with the @code{font-lock-multiline} property. -Then it removes any @code{font-lock-multiline} properties from the -range, and highlights it. The highlighting specification (mostly -@code{font-lock-keywords}) must reinstall this property each time, -whenever it is appropriate. - - @strong{Warning:} don't use the @code{font-lock-multiline} property -on large ranges of text, because that will make rehighlighting slow. - -@defvar font-lock-multiline -If the @code{font-lock-multiline} variable is set to @code{t}, Font -Lock will try to add the @code{font-lock-multiline} property -automatically on multiline constructs. This is not a universal -solution, however, since it slows down Font Lock somewhat. It can -miss some multiline constructs, or make the property larger or smaller -than necessary. - -For elements whose @var{matcher} is a function, the function should -ensure that submatch 0 covers the whole relevant multiline construct, -even if only a small subpart will be highlighted. It is often just as -easy to add the @code{font-lock-multiline} property by hand. -@end defvar - - The @code{font-lock-multiline} property is meant to ensure proper -refontification; it does not automatically identify new multiline -constructs. Identifying the requires that Font Lock mode operate on -large enough chunks at a time. This will happen by accident on many -cases, which may give the impression that multiline constructs magically -work. If you set the @code{font-lock-multiline} variable -non-@code{nil}, this impression will be even stronger, since the -highlighting of those constructs which are found will be properly -updated from then on. But that does not work reliably. - - To find multiline constructs reliably, you must either manually place -the @code{font-lock-multiline} property on the text before Font Lock -mode looks at it, or use @code{font-lock-fontify-region-function}. - -@node Region to Refontify -@subsubsection Region to Fontify after a Buffer Change - - When a buffer is changed, the region that Font Lock refontifies is -by default the smallest sequence of whole lines that spans the change. -While this works well most of the time, sometimes it doesn't---for -example, when a change alters the syntactic meaning of text on an -earlier line. - - You can enlarge (or even reduce) the region to refontify by setting -the following variable: - -@defvar font-lock-extend-after-change-region-function -This buffer-local variable is either @code{nil} or a function for Font -Lock mode to call to determine the region to scan and fontify. - -The function is given three parameters, the standard @var{beg}, -@var{end}, and @var{old-len} from @code{after-change-functions} -(@pxref{Change Hooks}). It should return either a cons of the -beginning and end buffer positions (in that order) of the region to -fontify, or @code{nil} (which means choose the region in the standard -way). This function needs to preserve point, the match-data, and the -current restriction. The region it returns may start or end in the -middle of a line. - -Since this function is called after every buffer change, it should be -reasonably fast. -@end defvar - -@node Auto-Indentation -@section Automatic Indentation of code - -For programming languages, an important feature of a major mode is to -provide automatic indentation. This is controlled in Emacs by -@code{indent-line-function} (@pxref{Mode-Specific Indent}). -Writing a good indentation function can be difficult and to a large -extent it is still a black art. - -Many major mode authors will start by writing a simple indentation -function that works for simple cases, for example by comparing with the -indentation of the previous text line. For most programming languages -that are not really line-based, this tends to scale very poorly: -improving such a function to let it handle more diverse situations tends -to become more and more difficult, resulting in the end with a large, -complex, unmaintainable indentation function which nobody dares to touch. - -A good indentation function will usually need to actually parse the -text, according to the syntax of the language. Luckily, it is not -necessary to parse the text in as much detail as would be needed -for a compiler, but on the other hand, the parser embedded in the -indentation code will want to be somewhat friendly to syntactically -incorrect code. - -Good maintainable indentation functions usually fall into two categories: -either parsing forward from some ``safe'' starting point until the -position of interest, or parsing backward from the position of interest. -Neither of the two is a clearly better choice than the other: parsing -backward is often more difficult than parsing forward because -programming languages are designed to be parsed forward, but for the -purpose of indentation it has the advantage of not needing to -guess a ``safe'' starting point, and it generally enjoys the property -that only a minimum of text will be analyzed to decide the indentation -of a line, so indentation will tend to be unaffected by syntax errors in -some earlier unrelated piece of code. Parsing forward on the other hand -is usually easier and has the advantage of making it possible to -reindent efficiently a whole region at a time, with a single parse. - -Rather than write your own indentation function from scratch, it is -often preferable to try and reuse some existing ones or to rely -on a generic indentation engine. There are sadly few such -engines. The CC-mode indentation code (used with C, C++, Java, Awk -and a few other such modes) has been made more generic over the years, -so if your language seems somewhat similar to one of those languages, -you might try to use that engine. @c FIXME: documentation? -Another one is SMIE which takes an approach in the spirit -of Lisp sexps and adapts it to non-Lisp languages. - -@menu -* SMIE:: A simple minded indentation engine. -@end menu - -@node SMIE -@subsection Simple Minded Indentation Engine - -SMIE is a package that provides a generic navigation and indentation -engine. Based on a very simple parser using an ``operator precedence -grammar'', it lets major modes extend the sexp-based navigation of Lisp -to non-Lisp languages as well as provide a simple to use but reliable -auto-indentation. - -Operator precedence grammar is a very primitive technology for parsing -compared to some of the more common techniques used in compilers. -It has the following characteristics: its parsing power is very limited, -and it is largely unable to detect syntax errors, but it has the -advantage of being algorithmically efficient and able to parse forward -just as well as backward. In practice that means that SMIE can use it -for indentation based on backward parsing, that it can provide both -@code{forward-sexp} and @code{backward-sexp} functionality, and that it -will naturally work on syntactically incorrect code without any extra -effort. The downside is that it also means that most programming -languages cannot be parsed correctly using SMIE, at least not without -resorting to some special tricks (@pxref{SMIE Tricks}). - -@menu -* SMIE setup:: SMIE setup and features. -* Operator Precedence Grammars:: A very simple parsing technique. -* SMIE Grammar:: Defining the grammar of a language. -* SMIE Lexer:: Defining tokens. -* SMIE Tricks:: Working around the parser's limitations. -* SMIE Indentation:: Specifying indentation rules. -* SMIE Indentation Helpers:: Helper functions for indentation rules. -* SMIE Indentation Example:: Sample indentation rules. -@end menu - -@node SMIE setup -@subsubsection SMIE Setup and Features - -SMIE is meant to be a one-stop shop for structural navigation and -various other features which rely on the syntactic structure of code, in -particular automatic indentation. The main entry point is -@code{smie-setup} which is a function typically called while setting -up a major mode. - -@defun smie-setup grammar rules-function &rest keywords -Setup SMIE navigation and indentation. -@var{grammar} is a grammar table generated by @code{smie-prec2->grammar}. -@var{rules-function} is a set of indentation rules for use on -@code{smie-rules-function}. -@var{keywords} are additional arguments, which can include the following -keywords: -@itemize -@item -@code{:forward-token} @var{fun}: Specify the forward lexer to use. -@item -@code{:backward-token} @var{fun}: Specify the backward lexer to use. -@end itemize -@end defun - -Calling this function is sufficient to make commands such as -@code{forward-sexp}, @code{backward-sexp}, and @code{transpose-sexps} be -able to properly handle structural elements other than just the paired -parentheses already handled by syntax tables. For example, if the -provided grammar is precise enough, @code{transpose-sexps} can correctly -transpose the two arguments of a @code{+} operator, taking into account -the precedence rules of the language. - -Calling `smie-setup' is also sufficient to make TAB indentation work in -the expected way, extends @code{blink-matching-paren} to apply to -elements like @code{begin...end}, and provides some commands that you -can bind in the major mode keymap. - -@deffn Command smie-close-block -This command closes the most recently opened (and not yet closed) block. -@end deffn - -@deffn Command smie-down-list &optional arg -This command is like @code{down-list} but it also pays attention to -nesting of tokens other than parentheses, such as @code{begin...end}. -@end deffn - -@node Operator Precedence Grammars -@subsubsection Operator Precedence Grammars - -SMIE's precedence grammars simply give to each token a pair of -precedences: the left-precedence and the right-precedence. We say -@code{T1 < T2} if the right-precedence of token @code{T1} is less than -the left-precedence of token @code{T2}. A good way to read this -@code{<} is as a kind of parenthesis: if we find @code{... T1 something -T2 ...} then that should be parsed as @code{... T1 (something T2 ...} -rather than as @code{... T1 something) T2 ...}. The latter -interpretation would be the case if we had @code{T1 > T2}. If we have -@code{T1 = T2}, it means that token T2 follows token T1 in the same -syntactic construction, so typically we have @code{"begin" = "end"}. -Such pairs of precedences are sufficient to express left-associativity -or right-associativity of infix operators, nesting of tokens like -parentheses and many other cases. - -@c Let's leave this undocumented to leave it more open for change! -@c @defvar smie-grammar -@c The value of this variable is an alist specifying the left and right -@c precedence of each token. It is meant to be initialized by using one of -@c the functions below. -@c @end defvar - -@defun smie-prec2->grammar table -This function takes a @emph{prec2} grammar @var{table} and returns an -alist suitable for use in @code{smie-setup}. The @emph{prec2} -@var{table} is itself meant to be built by one of the functions below. -@end defun - -@defun smie-merge-prec2s &rest tables -This function takes several @emph{prec2} @var{tables} and merges them -into a new @emph{prec2} table. -@end defun - -@defun smie-precs->prec2 precs -This function builds a @emph{prec2} table from a table of precedences -@var{precs}. @var{precs} should be a list, sorted by precedence (for -example @code{"+"} will come before @code{"*"}), of elements of the form -@code{(@var{assoc} @var{op} ...)}, where each @var{op} is a token that -acts as an operator; @var{assoc} is their associativity, which can be -either @code{left}, @code{right}, @code{assoc}, or @code{nonassoc}. -All operators in a given element share the same precedence level -and associativity. -@end defun - -@defun smie-bnf->prec2 bnf &rest resolvers -This function lets you specify the grammar using a BNF notation. -It accepts a @var{bnf} description of the grammar along with a set of -conflict resolution rules @var{resolvers}, and -returns a @emph{prec2} table. - -@var{bnf} is a list of nonterminal definitions of the form -@code{(@var{nonterm} @var{rhs1} @var{rhs2} ...)} where each @var{rhs} -is a (non-empty) list of terminals (aka tokens) or non-terminals. - -Not all grammars are accepted: -@itemize -@item -An @var{rhs} cannot be an empty list (an empty list is never needed, -since SMIE allows all non-terminals to match the empty string anyway). -@item -An @var{rhs} cannot have 2 consecutive non-terminals: each pair of -non-terminals needs to be separated by a terminal (aka token). -This is a fundamental limitation of operator precedence grammars. -@end itemize - -Additionally, conflicts can occur: -@itemize -@item -The returned @emph{prec2} table holds constraints between pairs of tokens, and -for any given pair only one constraint can be present: T1 < T2, -T1 = T2, or T1 > T2. -@item -A token can be an @code{opener} (something similar to an open-paren), -a @code{closer} (like a close-paren), or @code{neither} of the two -(e.g. an infix operator, or an inner token like @code{"else"}). -@end itemize - -Precedence conflicts can be resolved via @var{resolvers}, which -is a list of @emph{precs} tables (see @code{smie-precs->prec2}): for -each precedence conflict, if those @code{precs} tables -specify a particular constraint, then the conflict is resolved by using -this constraint instead, else a conflict is reported and one of the -conflicting constraints is picked arbitrarily and the others are -simply ignored. -@end defun - -@node SMIE Grammar -@subsubsection Defining the Grammar of a Language - -The usual way to define the SMIE grammar of a language is by -defining a new global variable that holds the precedence table by -giving a set of BNF rules. -For example, the grammar definition for a small Pascal-like language -could look like: -@example -@group -(require 'smie) -(defvar sample-smie-grammar - (smie-prec2->grammar - (smie-bnf->prec2 -@end group -@group - '((id) - (inst ("begin" insts "end") - ("if" exp "then" inst "else" inst) - (id ":=" exp) - (exp)) - (insts (insts ";" insts) (inst)) - (exp (exp "+" exp) - (exp "*" exp) - ("(" exps ")")) - (exps (exps "," exps) (exp))) -@end group -@group - '((assoc ";")) - '((assoc ",")) - '((assoc "+") (assoc "*"))))) -@end group -@end example - -@noindent -A few things to note: - -@itemize -@item -The above grammar does not explicitly mention the syntax of function -calls: SMIE will automatically allow any sequence of sexps, such as -identifiers, balanced parentheses, or @code{begin ... end} blocks -to appear anywhere anyway. -@item -The grammar category @code{id} has no right hand side: this does not -mean that it can match only the empty string, since as mentioned any -sequence of sexps can appear anywhere anyway. -@item -Because non terminals cannot appear consecutively in the BNF grammar, it -is difficult to correctly handle tokens that act as terminators, so the -above grammar treats @code{";"} as a statement @emph{separator} instead, -which SMIE can handle very well. -@item -Separators used in sequences (such as @code{","} and @code{";"} above) -are best defined with BNF rules such as @code{(foo (foo "separator" foo) ...)} -which generate precedence conflicts which are then resolved by giving -them an explicit @code{(assoc "separator")}. -@item -The @code{("(" exps ")")} rule was not needed to pair up parens, since -SMIE will pair up any characters that are marked as having paren syntax -in the syntax table. What this rule does instead (together with the -definition of @code{exps}) is to make it clear that @code{","} should -not appear outside of parentheses. -@item -Rather than have a single @emph{precs} table to resolve conflicts, it is -preferable to have several tables, so as to let the BNF part of the -grammar specify relative precedences where possible. -@item -Unless there is a very good reason to prefer @code{left} or -@code{right}, it is usually preferable to mark operators as associative, -using @code{assoc}. For that reason @code{"+"} and @code{"*"} are -defined above as @code{assoc}, although the language defines them -formally as left associative. -@end itemize - -@node SMIE Lexer -@subsubsection Defining Tokens - -SMIE comes with a predefined lexical analyzer which uses syntax tables -in the following way: any sequence of characters that have word or -symbol syntax is considered a token, and so is any sequence of -characters that have punctuation syntax. This default lexer is -often a good starting point but is rarely actually correct for any given -language. For example, it will consider @code{"2,+3"} to be composed -of 3 tokens: @code{"2"}, @code{",+"}, and @code{"3"}. - -To describe the lexing rules of your language to SMIE, you need -2 functions, one to fetch the next token, and another to fetch the -previous token. Those functions will usually first skip whitespace and -comments and then look at the next chunk of text to see if it -is a special token. If so it should skip the token and -return a description of this token. Usually this is simply the string -extracted from the buffer, but it can be anything you want. -For example: -@example -@group -(defvar sample-keywords-regexp - (regexp-opt '("+" "*" "," ";" ">" ">=" "<" "<=" ":=" "="))) -@end group -@group -(defun sample-smie-forward-token () - (forward-comment (point-max)) - (cond - ((looking-at sample-keywords-regexp) - (goto-char (match-end 0)) - (match-string-no-properties 0)) - (t (buffer-substring-no-properties - (point) - (progn (skip-syntax-forward "w_") - (point)))))) -@end group -@group -(defun sample-smie-backward-token () - (forward-comment (- (point))) - (cond - ((looking-back sample-keywords-regexp (- (point) 2) t) - (goto-char (match-beginning 0)) - (match-string-no-properties 0)) - (t (buffer-substring-no-properties - (point) - (progn (skip-syntax-backward "w_") - (point)))))) -@end group -@end example - -Notice how those lexers return the empty string when in front of -parentheses. This is because SMIE automatically takes care of the -parentheses defined in the syntax table. More specifically if the lexer -returns nil or an empty string, SMIE tries to handle the corresponding -text as a sexp according to syntax tables. - -@node SMIE Tricks -@subsubsection Living With a Weak Parser - -The parsing technique used by SMIE does not allow tokens to behave -differently in different contexts. For most programming languages, this -manifests itself by precedence conflicts when converting the -BNF grammar. - -Sometimes, those conflicts can be worked around by expressing the -grammar slightly differently. For example, for Modula-2 it might seem -natural to have a BNF grammar that looks like this: - -@example - ... - (inst ("IF" exp "THEN" insts "ELSE" insts "END") - ("CASE" exp "OF" cases "END") - ...) - (cases (cases "|" cases) - (caselabel ":" insts) - ("ELSE" insts)) - ... -@end example - -But this will create conflicts for @code{"ELSE"}: on the one hand, the -IF rule implies (among many other things) that @code{"ELSE" = "END"}; -but on the other hand, since @code{"ELSE"} appears within @code{cases}, -which appears left of @code{"END"}, we also have @code{"ELSE" > "END"}. -We can solve the conflict either by using: -@example - ... - (inst ("IF" exp "THEN" insts "ELSE" insts "END") - ("CASE" exp "OF" cases "END") - ("CASE" exp "OF" cases "ELSE" insts "END") - ...) - (cases (cases "|" cases) (caselabel ":" insts)) - ... -@end example -or -@example - ... - (inst ("IF" exp "THEN" else "END") - ("CASE" exp "OF" cases "END") - ...) - (else (insts "ELSE" insts)) - (cases (cases "|" cases) (caselabel ":" insts) (else)) - ... -@end example - -Reworking the grammar to try and solve conflicts has its downsides, tho, -because SMIE assumes that the grammar reflects the logical structure of -the code, so it is preferable to keep the BNF closer to the intended -abstract syntax tree. - -Other times, after careful consideration you may conclude that those -conflicts are not serious and simply resolve them via the -@var{resolvers} argument of @code{smie-bnf->prec2}. Usually this is -because the grammar is simply ambiguous: the conflict does not affect -the set of programs described by the grammar, but only the way those -programs are parsed. This is typically the case for separators and -associative infix operators, where you want to add a resolver like -@code{'((assoc "|"))}. Another case where this can happen is for the -classic @emph{dangling else} problem, where you will use @code{'((assoc -"else" "then"))}. It can also happen for cases where the conflict is -real and cannot really be resolved, but it is unlikely to pose a problem -in practice. - -Finally, in many cases some conflicts will remain despite all efforts to -restructure the grammar. Do not despair: while the parser cannot be -made more clever, you can make the lexer as smart as you want. So, the -solution is then to look at the tokens involved in the conflict and to -split one of those tokens into 2 (or more) different tokens. E.g. if -the grammar needs to distinguish between two incompatible uses of the -token @code{"begin"}, make the lexer return different tokens (say -@code{"begin-fun"} and @code{"begin-plain"}) depending on which kind of -@code{"begin"} it finds. This pushes the work of distinguishing the -different cases to the lexer, which will thus have to look at the -surrounding text to find ad-hoc clues. - -@node SMIE Indentation -@subsubsection Specifying Indentation Rules - -Based on the provided grammar, SMIE will be able to provide automatic -indentation without any extra effort. But in practice, this default -indentation style will probably not be good enough. You will want to -tweak it in many different cases. - -SMIE indentation is based on the idea that indentation rules should be -as local as possible. To this end, it relies on the idea of -@emph{virtual} indentation, which is the indentation that a particular -program point would have if it were at the beginning of a line. -Of course, if that program point is indeed at the beginning of a line, -its virtual indentation is its current indentation. But if not, then -SMIE uses the indentation algorithm to compute the virtual indentation -of that point. Now in practice, the virtual indentation of a program -point does not have to be identical to the indentation it would have if -we inserted a newline before it. To see how this works, the SMIE rule -for indentation after a @code{@{} in C does not care whether the -@code{@{} is standing on a line of its own or is at the end of the -preceding line. Instead, these different cases are handled in the -indentation rule that decides how to indent before a @code{@{}. - -Another important concept is the notion of @emph{parent}: The -@emph{parent} of a token, is the head token of the nearest enclosing -syntactic construct. For example, the parent of an @code{else} is the -@code{if} to which it belongs, and the parent of an @code{if}, in turn, -is the lead token of the surrounding construct. The command -@code{backward-sexp} jumps from a token to its parent, but there are -some caveats: for @emph{openers} (tokens which start a construct, like -@code{if}), you need to start with point before the token, while for -others you need to start with point after the token. -@code{backward-sexp} stops with point before the parent token if that is -the @emph{opener} of the token of interest, and otherwise it stops with -point after the parent token. - -SMIE indentation rules are specified using a function that takes two -arguments @var{method} and @var{arg} where the meaning of @var{arg} and the -expected return value depend on @var{method}. - -@var{method} can be: -@itemize -@item -@code{:after}, in which case @var{arg} is a token and the function -should return the @var{offset} to use for indentation after @var{arg}. -@item -@code{:before}, in which case @var{arg} is a token and the function -should return the @var{offset} to use to indent @var{arg} itself. -@item -@code{:elem}, in which case the function should return either the offset -to use to indent function arguments (if @var{arg} is the symbol -@code{arg}) or the basic indentation step (if @var{arg} is the symbol -@code{basic}). -@item -@code{:list-intro}, in which case @var{arg} is a token and the function -should return non-@code{nil} if the token is followed by a list of -expressions (not separated by any token) rather than an expression. -@end itemize - -When @var{arg} is a token, the function is called with point just before -that token. A return value of nil always means to fallback on the -default behavior, so the function should return nil for arguments it -does not expect. - -@var{offset} can be: -@itemize -@item -@code{nil}: use the default indentation rule. -@item -@code{(column . @var{column})}: indent to column @var{column}. -@item -@var{number}: offset by @var{number}, relative to a base token which is -the current token for @code{:after} and its parent for @code{:before}. -@end itemize - -@node SMIE Indentation Helpers -@subsubsection Helper Functions for Indentation Rules - -SMIE provides various functions designed specifically for use in the -indentation rules function (several of those functions break if used in -another context). These functions all start with the prefix -@code{smie-rule-}. - -@defun smie-rule-bolp -Return non-@code{nil} if the current token is the first on the line. -@end defun - -@defun smie-rule-hanging-p -Return non-@code{nil} if the current token is @emph{hanging}. -A token is @emph{hanging} if it is the last token on the line -and if it is preceded by other tokens: a lone token on a line is not -hanging. -@end defun - -@defun smie-rule-next-p &rest tokens -Return non-@code{nil} if the next token is among @var{tokens}. -@end defun - -@defun smie-rule-prev-p &rest tokens -Return non-@code{nil} if the previous token is among @var{tokens}. -@end defun - -@defun smie-rule-parent-p &rest parents -Return non-@code{nil} if the current token's parent is among @var{parents}. -@end defun - -@defun smie-rule-sibling-p -Return non-@code{nil} if the current token's parent is actually a -sibling. This is the case for example when the parent of a @code{","} -is just the previous @code{","}. -@end defun - -@defun smie-rule-parent &optional offset -Return the proper offset to align the current token with the parent. -If non-@code{nil}, @var{offset} should be an integer giving an -additional offset to apply. -@end defun - -@defun smie-rule-separator method -Indent current token as a @emph{separator}. - -By @emph{separator}, we mean here a token whose sole purpose is to -separate various elements within some enclosing syntactic construct, and -which does not have any semantic significance in itself (i.e. it would -typically not exist as a node in an abstract syntax tree). - -Such a token is expected to have an associative syntax and be closely -tied to its syntactic parent. Typical examples are @code{","} in lists -of arguments (enclosed inside parentheses), or @code{";"} in sequences -of instructions (enclosed in a @code{@{...@}} or @code{begin...end} -block). - -@var{method} should be the method name that was passed to -`smie-rules-function'. -@end defun - -@node SMIE Indentation Example -@subsubsection Sample Indentation Rules - -Here is an example of an indentation function: - -@example -(defun sample-smie-rules (kind token) - (pcase (cons kind token) - (`(:elem . basic) sample-indent-basic) - (`(,_ . ",") (smie-rule-separator kind)) - (`(:after . ":=") sample-indent-basic) - (`(:before . ,(or `"begin" `"(" `"@{"))) - (if (smie-rule-hanging-p) (smie-rule-parent))) - (`(:before . "if") - (and (not (smie-rule-bolp)) (smie-rule-prev-p "else") - (smie-rule-parent))))) -@end example - -@noindent -A few things to note: - -@itemize -@item -The first case indicates the basic indentation increment to use. -If @code{sample-indent-basic} is nil, then SMIE uses the global -setting @code{smie-indent-basic}. The major mode could have set -@code{smie-indent-basic} buffer-locally instead, but that -is discouraged. - -@item -The rule for the token @code{","} make SMIE try to be more clever when -the comma separator is placed at the beginning of lines. It tries to -outdent the separator so as to align the code after the comma; for -example: - -@example -x = longfunctionname ( - arg1 - , arg2 - ); -@end example - -@item -The rule for indentation after @code{":="} exists because otherwise -SMIE would treat @code{":="} as an infix operator and would align the -right argument with the left one. - -@item -The rule for indentation before @code{"begin"} is an example of the use -of virtual indentation: This rule is used only when @code{"begin"} is -hanging, which can happen only when @code{"begin"} is not at the -beginning of a line. So this is not used when indenting -@code{"begin"} itself but only when indenting something relative to this -@code{"begin"}. Concretely, this rule changes the indentation from: - -@example - if x > 0 then begin - dosomething(x); - end -@end example -to -@example - if x > 0 then begin - dosomething(x); - end -@end example - -@item -The rule for indentation before @code{"if"} is similar to the one for -@code{"begin"}, but where the purpose is to treat @code{"else if"} -as a single unit, so as to align a sequence of tests rather than indent -each test further to the right. This function does this only in the -case where the @code{"if"} is not placed on a separate line, hence the -@code{smie-rule-bolp} test. - -If we know that the @code{"else"} is always aligned with its @code{"if"} -and is always at the beginning of a line, we can use a more efficient -rule: -@example -((equal token "if") - (and (not (smie-rule-bolp)) - (smie-rule-prev-p "else") - (save-excursion - (sample-smie-backward-token) - (cons 'column (current-column))))) -@end example - -The advantage of this formulation is that it reuses the indentation of -the previous @code{"else"}, rather than going all the way back to the -first @code{"if"} of the sequence. -@end itemize - -@node Desktop Save Mode -@section Desktop Save Mode -@cindex desktop save mode - -@dfn{Desktop Save Mode} is a feature to save the state of Emacs from -one session to another. The user-level commands for using Desktop -Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs -Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit -a file, don't have to do anything to use this feature. - -For buffers not visiting a file to have their state saved, the major -mode must bind the buffer local variable @code{desktop-save-buffer} to -a non-@code{nil} value. - -@defvar desktop-save-buffer -If this buffer-local variable is non-@code{nil}, the buffer will have -its state saved in the desktop file at desktop save. If the value is -a function, it is called at desktop save with argument -@var{desktop-dirname}, and its value is saved in the desktop file along -with the state of the buffer for which it was called. When file names -are returned as part of the auxiliary information, they should be -formatted using the call - -@example -(desktop-file-name @var{file-name} @var{desktop-dirname}) -@end example - -@end defvar - -For buffers not visiting a file to be restored, the major mode must -define a function to do the job, and that function must be listed in -the alist @code{desktop-buffer-mode-handlers}. - -@defvar desktop-buffer-mode-handlers -Alist with elements - -@example -(@var{major-mode} . @var{restore-buffer-function}) -@end example - -The function @var{restore-buffer-function} will be called with -argument list - -@example -(@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc}) -@end example - -and it should return the restored buffer. -Here @var{desktop-buffer-misc} is the value returned by the function -optionally bound to @code{desktop-save-buffer}. -@end defvar - diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi deleted file mode 100644 index c97cd099328..00000000000 --- a/doc/lispref/nonascii.texi +++ /dev/null @@ -1,1962 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/characters -@node Non-ASCII Characters, Searching and Matching, Text, Top -@chapter Non-@acronym{ASCII} Characters -@cindex multibyte characters -@cindex characters, multi-byte -@cindex non-@acronym{ASCII} characters - - This chapter covers the special issues relating to characters and -how they are stored in strings and buffers. - -@menu -* Text Representations:: How Emacs represents text. -* Converting Representations:: Converting unibyte to multibyte and vice versa. -* Selecting a Representation:: Treating a byte sequence as unibyte or multi. -* Character Codes:: How unibyte and multibyte relate to - codes of individual characters. -* Character Properties:: Character attributes that define their - behavior and handling. -* Character Sets:: The space of possible character codes - is divided into various character sets. -* Scanning Charsets:: Which character sets are used in a buffer? -* Translation of Characters:: Translation tables are used for conversion. -* Coding Systems:: Coding systems are conversions for saving files. -* Input Methods:: Input methods allow users to enter various - non-ASCII characters without special keyboards. -* Locales:: Interacting with the POSIX locale. -@end menu - -@node Text Representations -@section Text Representations -@cindex text representation - - Emacs buffers and strings support a large repertoire of characters -from many different scripts, allowing users to type and display text -in almost any known written language. - -@cindex character codepoint -@cindex codespace -@cindex Unicode - To support this multitude of characters and scripts, Emacs closely -follows the @dfn{Unicode Standard}. The Unicode Standard assigns a -unique number, called a @dfn{codepoint}, to each and every character. -The range of codepoints defined by Unicode, or the Unicode -@dfn{codespace}, is @code{0..#x10FFFF} (in hexadecimal notation), -inclusive. Emacs extends this range with codepoints in the range -@code{#x110000..#x3FFFFF}, which it uses for representing characters -that are not unified with Unicode and @dfn{raw 8-bit bytes} that -cannot be interpreted as characters. Thus, a character codepoint in -Emacs is a 22-bit integer number. - -@cindex internal representation of characters -@cindex characters, representation in buffers and strings -@cindex multibyte text - To conserve memory, Emacs does not hold fixed-length 22-bit numbers -that are codepoints of text characters within buffers and strings. -Rather, Emacs uses a variable-length internal representation of -characters, that stores each character as a sequence of 1 to 5 8-bit -bytes, depending on the magnitude of its codepoint@footnote{ -This internal representation is based on one of the encodings defined -by the Unicode Standard, called @dfn{UTF-8}, for representing any -Unicode codepoint, but Emacs extends UTF-8 to represent the additional -codepoints it uses for raw 8-bit bytes and characters not unified with -Unicode.}. For example, any @acronym{ASCII} character takes up only 1 -byte, a Latin-1 character takes up 2 bytes, etc. We call this -representation of text @dfn{multibyte}. - - Outside Emacs, characters can be represented in many different -encodings, such as ISO-8859-1, GB-2312, Big-5, etc. Emacs converts -between these external encodings and its internal representation, as -appropriate, when it reads text into a buffer or a string, or when it -writes text to a disk file or passes it to some other process. - - Occasionally, Emacs needs to hold and manipulate encoded text or -binary non-text data in its buffers or strings. For example, when -Emacs visits a file, it first reads the file's text verbatim into a -buffer, and only then converts it to the internal representation. -Before the conversion, the buffer holds encoded text. - -@cindex unibyte text - Encoded text is not really text, as far as Emacs is concerned, but -rather a sequence of raw 8-bit bytes. We call buffers and strings -that hold encoded text @dfn{unibyte} buffers and strings, because -Emacs treats them as a sequence of individual bytes. Usually, Emacs -displays unibyte buffers and strings as octal codes such as -@code{\237}. We recommend that you never use unibyte buffers and -strings except for manipulating encoded text or binary non-text data. - - In a buffer, the buffer-local value of the variable -@code{enable-multibyte-characters} specifies the representation used. -The representation for a string is determined and recorded in the string -when the string is constructed. - -@defvar enable-multibyte-characters -This variable specifies the current buffer's text representation. -If it is non-@code{nil}, the buffer contains multibyte text; otherwise, -it contains unibyte encoded text or binary non-text data. - -You cannot set this variable directly; instead, use the function -@code{set-buffer-multibyte} to change a buffer's representation. -@end defvar - -@defun position-bytes position -Buffer positions are measured in character units. This function -returns the byte-position corresponding to buffer position -@var{position} in the current buffer. This is 1 at the start of the -buffer, and counts upward in bytes. If @var{position} is out of -range, the value is @code{nil}. -@end defun - -@defun byte-to-position byte-position -Return the buffer position, in character units, corresponding to given -@var{byte-position} in the current buffer. If @var{byte-position} is -out of range, the value is @code{nil}. In a multibyte buffer, an -arbitrary value of @var{byte-position} can be not at character -boundary, but inside a multibyte sequence representing a single -character; in this case, this function returns the buffer position of -the character whose multibyte sequence includes @var{byte-position}. -In other words, the value does not change for all byte positions that -belong to the same character. -@end defun - -@defun multibyte-string-p string -Return @code{t} if @var{string} is a multibyte string, @code{nil} -otherwise. -@end defun - -@defun string-bytes string -@cindex string, number of bytes -This function returns the number of bytes in @var{string}. -If @var{string} is a multibyte string, this can be greater than -@code{(length @var{string})}. -@end defun - -@defun unibyte-string &rest bytes -This function concatenates all its argument @var{bytes} and makes the -result a unibyte string. -@end defun - -@node Converting Representations -@section Converting Text Representations - - Emacs can convert unibyte text to multibyte; it can also convert -multibyte text to unibyte, provided that the multibyte text contains -only @acronym{ASCII} and 8-bit raw bytes. In general, these -conversions happen when inserting text into a buffer, or when putting -text from several strings together in one string. You can also -explicitly convert a string's contents to either representation. - - Emacs chooses the representation for a string based on the text from -which it is constructed. The general rule is to convert unibyte text -to multibyte text when combining it with other multibyte text, because -the multibyte representation is more general and can hold whatever -characters the unibyte text has. - - When inserting text into a buffer, Emacs converts the text to the -buffer's representation, as specified by -@code{enable-multibyte-characters} in that buffer. In particular, when -you insert multibyte text into a unibyte buffer, Emacs converts the text -to unibyte, even though this conversion cannot in general preserve all -the characters that might be in the multibyte text. The other natural -alternative, to convert the buffer contents to multibyte, is not -acceptable because the buffer's representation is a choice made by the -user that cannot be overridden automatically. - - Converting unibyte text to multibyte text leaves @acronym{ASCII} -characters unchanged, and converts bytes with codes 128 through 255 to -the multibyte representation of raw eight-bit bytes. - - Converting multibyte text to unibyte converts all @acronym{ASCII} -and eight-bit characters to their single-byte form, but loses -information for non-@acronym{ASCII} characters by discarding all but -the low 8 bits of each character's codepoint. Converting unibyte text -to multibyte and back to unibyte reproduces the original unibyte text. - -The next two functions either return the argument @var{string}, or a -newly created string with no text properties. - -@defun string-to-multibyte string -This function returns a multibyte string containing the same sequence -of characters as @var{string}. If @var{string} is a multibyte string, -it is returned unchanged. The function assumes that @var{string} -includes only @acronym{ASCII} characters and raw 8-bit bytes; the -latter are converted to their multibyte representation corresponding -to the codepoints @code{#x3FFF80} through @code{#x3FFFFF}, inclusive -(@pxref{Text Representations, codepoints}). -@end defun - -@defun string-to-unibyte string -This function returns a unibyte string containing the same sequence of -characters as @var{string}. It signals an error if @var{string} -contains a non-@acronym{ASCII} character. If @var{string} is a -unibyte string, it is returned unchanged. Use this function for -@var{string} arguments that contain only @acronym{ASCII} and eight-bit -characters. -@end defun - -@defun byte-to-string byte -@cindex byte to string -This function returns a unibyte string containing a single byte of -character data, @var{character}. It signals an error if -@var{character} is not an integer between 0 and 255. -@end defun - -@defun multibyte-char-to-unibyte char -This converts the multibyte character @var{char} to a unibyte -character, and returns that character. If @var{char} is neither -@acronym{ASCII} nor eight-bit, the function returns -1. -@end defun - -@defun unibyte-char-to-multibyte char -This convert the unibyte character @var{char} to a multibyte -character, assuming @var{char} is either @acronym{ASCII} or raw 8-bit -byte. -@end defun - -@node Selecting a Representation -@section Selecting a Representation - - Sometimes it is useful to examine an existing buffer or string as -multibyte when it was unibyte, or vice versa. - -@defun set-buffer-multibyte multibyte -Set the representation type of the current buffer. If @var{multibyte} -is non-@code{nil}, the buffer becomes multibyte. If @var{multibyte} -is @code{nil}, the buffer becomes unibyte. - -This function leaves the buffer contents unchanged when viewed as a -sequence of bytes. As a consequence, it can change the contents -viewed as characters; for instance, a sequence of three bytes which is -treated as one character in multibyte representation will count as -three characters in unibyte representation. Eight-bit characters -representing raw bytes are an exception. They are represented by one -byte in a unibyte buffer, but when the buffer is set to multibyte, -they are converted to two-byte sequences, and vice versa. - -This function sets @code{enable-multibyte-characters} to record which -representation is in use. It also adjusts various data in the buffer -(including overlays, text properties and markers) so that they cover the -same text as they did before. - -You cannot use @code{set-buffer-multibyte} on an indirect buffer, -because indirect buffers always inherit the representation of the -base buffer. -@end defun - -@defun string-as-unibyte string -If @var{string} is already a unibyte string, this function returns -@var{string} itself. Otherwise, it returns a new string with the same -bytes as @var{string}, but treating each byte as a separate character -(so that the value may have more characters than @var{string}); as an -exception, each eight-bit character representing a raw byte is -converted into a single byte. The newly-created string contains no -text properties. -@end defun - -@defun string-as-multibyte string -If @var{string} is a multibyte string, this function returns -@var{string} itself. Otherwise, it returns a new string with the same -bytes as @var{string}, but treating each multibyte sequence as one -character. This means that the value may have fewer characters than -@var{string} has. If a byte sequence in @var{string} is invalid as a -multibyte representation of a single character, each byte in the -sequence is treated as a raw 8-bit byte. The newly-created string -contains no text properties. -@end defun - -@node Character Codes -@section Character Codes -@cindex character codes - - The unibyte and multibyte text representations use different -character codes. The valid character codes for unibyte representation -range from 0 to @code{#xFF} (255)---the values that can fit in one -byte. The valid character codes for multibyte representation range -from 0 to @code{#x3FFFFF}. In this code space, values 0 through -@code{#x7F} (127) are for @acronym{ASCII} characters, and values -@code{#x80} (128) through @code{#x3FFF7F} (4194175) are for -non-@acronym{ASCII} characters. - - Emacs character codes are a superset of the Unicode standard. -Values 0 through @code{#x10FFFF} (1114111) correspond to Unicode -characters of the same codepoint; values @code{#x110000} (1114112) -through @code{#x3FFF7F} (4194175) represent characters that are not -unified with Unicode; and values @code{#x3FFF80} (4194176) through -@code{#x3FFFFF} (4194303) represent eight-bit raw bytes. - -@defun characterp charcode -This returns @code{t} if @var{charcode} is a valid character, and -@code{nil} otherwise. - -@example -@group -(characterp 65) - @result{} t -@end group -@group -(characterp 4194303) - @result{} t -@end group -@group -(characterp 4194304) - @result{} nil -@end group -@end example -@end defun - -@cindex maximum value of character codepoint -@cindex codepoint, largest value -@defun max-char -This function returns the largest value that a valid character -codepoint can have. - -@example -@group -(characterp (max-char)) - @result{} t -@end group -@group -(characterp (1+ (max-char))) - @result{} nil -@end group -@end example -@end defun - -@defun get-byte &optional pos string -This function returns the byte at character position @var{pos} in the -current buffer. If the current buffer is unibyte, this is literally -the byte at that position. If the buffer is multibyte, byte values of -@acronym{ASCII} characters are the same as character codepoints, -whereas eight-bit raw bytes are converted to their 8-bit codes. The -function signals an error if the character at @var{pos} is -non-@acronym{ASCII}. - -The optional argument @var{string} means to get a byte value from that -string instead of the current buffer. -@end defun - -@node Character Properties -@section Character Properties -@cindex character properties -A @dfn{character property} is a named attribute of a character that -specifies how the character behaves and how it should be handled -during text processing and display. Thus, character properties are an -important part of specifying the character's semantics. - - On the whole, Emacs follows the Unicode Standard in its implementation -of character properties. In particular, Emacs supports the -@uref{http://www.unicode.org/reports/tr23/, Unicode Character Property -Model}, and the Emacs character property database is derived from the -Unicode Character Database (@acronym{UCD}). See the -@uref{http://www.unicode.org/versions/Unicode5.0.0/ch04.pdf, Character -Properties chapter of the Unicode Standard}, for a detailed -description of Unicode character properties and their meaning. This -section assumes you are already familiar with that chapter of the -Unicode Standard, and want to apply that knowledge to Emacs Lisp -programs. - - In Emacs, each property has a name, which is a symbol, and a set of -possible values, whose types depend on the property; if a character -does not have a certain property, the value is @code{nil}. As a -general rule, the names of character properties in Emacs are produced -from the corresponding Unicode properties by downcasing them and -replacing each @samp{_} character with a dash @samp{-}. For example, -@code{Canonical_Combining_Class} becomes -@code{canonical-combining-class}. However, sometimes we shorten the -names to make their use easier. - -@cindex unassigned character codepoints - Some codepoints are left @dfn{unassigned} by the -@acronym{UCD}---they don't correspond to any character. The Unicode -Standard defines default values of properties for such codepoints; -they are mentioned below for each property. - - Here is the full list of value types for all the character -properties that Emacs knows about: - -@table @code -@item name -Corresponds to the @code{Name} Unicode property. The value is a -string consisting of upper-case Latin letters A to Z, digits, spaces, -and hyphen @samp{-} characters. For unassigned codepoints, the value -is an empty string. - -@cindex unicode general category -@item general-category -Corresponds to the @code{General_Category} Unicode property. The -value is a symbol whose name is a 2-letter abbreviation of the -character's classification. For unassigned codepoints, the value -is @code{Cn}. - -@item canonical-combining-class -Corresponds to the @code{Canonical_Combining_Class} Unicode property. -The value is an integer number. For unassigned codepoints, the value -is zero. - -@cindex bidirectional class of characters -@item bidi-class -Corresponds to the Unicode @code{Bidi_Class} property. The value is a -symbol whose name is the Unicode @dfn{directional type} of the -character. Emacs uses this property when it reorders bidirectional -text for display (@pxref{Bidirectional Display}). For unassigned -codepoints, the value depends on the code blocks to which the -codepoint belongs: most unassigned codepoints get the value of -@code{L} (strong L), but some get values of @code{AL} (Arabic letter) -or @code{R} (strong R). - -@item decomposition -Corresponds to the Unicode @code{Decomposition_Type} and -@code{Decomposition_Value} properties. The value is a list, whose -first element may be a symbol representing a compatibility formatting -tag, such as @code{small}@footnote{The Unicode specification writes -these tag names inside @samp{<..>} brackets, but the tag names in -Emacs do not include the brackets; e.g.@: Unicode specifies -@samp{} where Emacs uses @samp{small}. }; the other elements -are characters that give the compatibility decomposition sequence of -this character. For unassigned codepoints, the value is the character -itself. - -@item decimal-digit-value -Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Digit}. The value is an -integer number. For unassigned codepoints, the value is @code{nil}, -which means @acronym{NaN}, or ``not-a-number''. - -@item digit-value -Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Decimal}. The value is -an integer number. Examples of such characters include compatibility -subscript and superscript digits, for which the value is the -corresponding number. For unassigned codepoints, the value is -@code{nil}, which means @acronym{NaN}. - -@item numeric-value -Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Numeric}. The value of -this property is an integer or a floating-point number. Examples of -characters that have this property include fractions, subscripts, -superscripts, Roman numerals, currency numerators, and encircled -numbers. For example, the value of this property for the character -@code{U+2155} (@sc{vulgar fraction one fifth}) is @code{0.2}. For -unassigned codepoints, the value is @code{nil}, which means -@acronym{NaN}. - -@cindex mirroring of characters -@item mirrored -Corresponds to the Unicode @code{Bidi_Mirrored} property. The value -of this property is a symbol, either @code{Y} or @code{N}. For -unassigned codepoints, the value is @code{N}. - -@item mirroring -Corresponds to the Unicode @code{Bidi_Mirroring_Glyph} property. The -value of this property is a character whose glyph represents the -mirror image of the character's glyph, or @code{nil} if there's no -defined mirroring glyph. All the characters whose @code{mirrored} -property is @code{N} have @code{nil} as their @code{mirroring} -property; however, some characters whose @code{mirrored} property is -@code{Y} also have @code{nil} for @code{mirroring}, because no -appropriate characters exist with mirrored glyphs. Emacs uses this -property to display mirror images of characters when appropriate -(@pxref{Bidirectional Display}). For unassigned codepoints, the value -is @code{nil}. - -@item old-name -Corresponds to the Unicode @code{Unicode_1_Name} property. The value -is a string. For unassigned codepoints, the value is an empty string. - -@item iso-10646-comment -Corresponds to the Unicode @code{ISO_Comment} property. The value is -a string. For unassigned codepoints, the value is an empty string. - -@item uppercase -Corresponds to the Unicode @code{Simple_Uppercase_Mapping} property. -The value of this property is a single character. For unassigned -codepoints, the value is @code{nil}, which means the character itself. - -@item lowercase -Corresponds to the Unicode @code{Simple_Lowercase_Mapping} property. -The value of this property is a single character. For unassigned -codepoints, the value is @code{nil}, which means the character itself. - -@item titlecase -Corresponds to the Unicode @code{Simple_Titlecase_Mapping} property. -@dfn{Title case} is a special form of a character used when the first -character of a word needs to be capitalized. The value of this -property is a single character. For unassigned codepoints, the value -is @code{nil}, which means the character itself. -@end table - -@defun get-char-code-property char propname -This function returns the value of @var{char}'s @var{propname} property. - -@example -@group -(get-char-code-property ? 'general-category) - @result{} Zs -@end group -@group -(get-char-code-property ?1 'general-category) - @result{} Nd -@end group -@group -;; subscript 4 -(get-char-code-property ?\u2084 'digit-value) - @result{} 4 -@end group -@group -;; one fifth -(get-char-code-property ?\u2155 'numeric-value) - @result{} 0.2 -@end group -@group -;; Roman IV -(get-char-code-property ?\u2163 'numeric-value) - @result{} 4 -@end group -@end example -@end defun - -@defun char-code-property-description prop value -This function returns the description string of property @var{prop}'s -@var{value}, or @code{nil} if @var{value} has no description. - -@example -@group -(char-code-property-description 'general-category 'Zs) - @result{} "Separator, Space" -@end group -@group -(char-code-property-description 'general-category 'Nd) - @result{} "Number, Decimal Digit" -@end group -@group -(char-code-property-description 'numeric-value '1/5) - @result{} nil -@end group -@end example -@end defun - -@defun put-char-code-property char propname value -This function stores @var{value} as the value of the property -@var{propname} for the character @var{char}. -@end defun - -@defvar unicode-category-table -The value of this variable is a char-table (@pxref{Char-Tables}) that -specifies, for each character, its Unicode @code{General_Category} -property as a symbol. -@end defvar - -@defvar char-script-table -The value of this variable is a char-table that specifies, for each -character, a symbol whose name is the script to which the character -belongs, according to the Unicode Standard classification of the -Unicode code space into script-specific blocks. This char-table has a -single extra slot whose value is the list of all script symbols. -@end defvar - -@defvar char-width-table -The value of this variable is a char-table that specifies the width of -each character in columns that it will occupy on the screen. -@end defvar - -@defvar printable-chars -The value of this variable is a char-table that specifies, for each -character, whether it is printable or not. That is, if evaluating -@code{(aref printable-chars char)} results in @code{t}, the character -is printable, and if it results in @code{nil}, it is not. -@end defvar - -@node Character Sets -@section Character Sets -@cindex character sets - -@cindex charset -@cindex coded character set -An Emacs @dfn{character set}, or @dfn{charset}, is a set of characters -in which each character is assigned a numeric code point. (The -Unicode Standard calls this a @dfn{coded character set}.) Each Emacs -charset has a name which is a symbol. A single character can belong -to any number of different character sets, but it will generally have -a different code point in each charset. Examples of character sets -include @code{ascii}, @code{iso-8859-1}, @code{greek-iso8859-7}, and -@code{windows-1255}. The code point assigned to a character in a -charset is usually different from its code point used in Emacs buffers -and strings. - -@cindex @code{emacs}, a charset -@cindex @code{unicode}, a charset -@cindex @code{eight-bit}, a charset - Emacs defines several special character sets. The character set -@code{unicode} includes all the characters whose Emacs code points are -in the range @code{0..#x10FFFF}. The character set @code{emacs} -includes all @acronym{ASCII} and non-@acronym{ASCII} characters. -Finally, the @code{eight-bit} charset includes the 8-bit raw bytes; -Emacs uses it to represent raw bytes encountered in text. - -@defun charsetp object -Returns @code{t} if @var{object} is a symbol that names a character set, -@code{nil} otherwise. -@end defun - -@defvar charset-list -The value is a list of all defined character set names. -@end defvar - -@defun charset-priority-list &optional highestp -This functions returns a list of all defined character sets ordered by -their priority. If @var{highestp} is non-@code{nil}, the function -returns a single character set of the highest priority. -@end defun - -@defun set-charset-priority &rest charsets -This function makes @var{charsets} the highest priority character sets. -@end defun - -@defun char-charset character &optional restriction -This function returns the name of the character set of highest -priority that @var{character} belongs to. @acronym{ASCII} characters -are an exception: for them, this function always returns @code{ascii}. - -If @var{restriction} is non-@code{nil}, it should be a list of -charsets to search. Alternatively, it can be a coding system, in -which case the returned charset must be supported by that coding -system (@pxref{Coding Systems}). -@end defun - -@defun charset-plist charset -This function returns the property list of the character set -@var{charset}. Although @var{charset} is a symbol, this is not the -same as the property list of that symbol. Charset properties include -important information about the charset, such as its documentation -string, short name, etc. -@end defun - -@defun put-charset-property charset propname value -This function sets the @var{propname} property of @var{charset} to the -given @var{value}. -@end defun - -@defun get-charset-property charset propname -This function returns the value of @var{charset}s property -@var{propname}. -@end defun - -@deffn Command list-charset-chars charset -This command displays a list of characters in the character set -@var{charset}. -@end deffn - - Emacs can convert between its internal representation of a character -and the character's codepoint in a specific charset. The following -two functions support these conversions. - -@c FIXME: decode-char and encode-char accept and ignore an additional -@c argument @var{restriction}. When that argument actually makes a -@c difference, it should be documented here. -@defun decode-char charset code-point -This function decodes a character that is assigned a @var{code-point} -in @var{charset}, to the corresponding Emacs character, and returns -it. If @var{charset} doesn't contain a character of that code point, -the value is @code{nil}. If @var{code-point} doesn't fit in a Lisp -integer (@pxref{Integer Basics, most-positive-fixnum}), it can be -specified as a cons cell @code{(@var{high} . @var{low})}, where -@var{low} are the lower 16 bits of the value and @var{high} are the -high 16 bits. -@end defun - -@defun encode-char char charset -This function returns the code point assigned to the character -@var{char} in @var{charset}. If the result does not fit in a Lisp -integer, it is returned as a cons cell @code{(@var{high} . @var{low})} -that fits the second argument of @code{decode-char} above. If -@var{charset} doesn't have a codepoint for @var{char}, the value is -@code{nil}. -@end defun - - The following function comes in handy for applying a certain -function to all or part of the characters in a charset: - -@defun map-charset-chars function charset &optional arg from-code to-code -Call @var{function} for characters in @var{charset}. @var{function} -is called with two arguments. The first one is a cons cell -@code{(@var{from} . @var{to})}, where @var{from} and @var{to} -indicate a range of characters contained in charset. The second -argument passed to @var{function} is @var{arg}. - -By default, the range of codepoints passed to @var{function} includes -all the characters in @var{charset}, but optional arguments -@var{from-code} and @var{to-code} limit that to the range of -characters between these two codepoints of @var{charset}. If either -of them is @code{nil}, it defaults to the first or last codepoint of -@var{charset}, respectively. -@end defun - -@node Scanning Charsets -@section Scanning for Character Sets - - Sometimes it is useful to find out which character set a particular -character belongs to. One use for this is in determining which coding -systems (@pxref{Coding Systems}) are capable of representing all of -the text in question; another is to determine the font(s) for -displaying that text. - -@defun charset-after &optional pos -This function returns the charset of highest priority containing the -character at position @var{pos} in the current buffer. If @var{pos} -is omitted or @code{nil}, it defaults to the current value of point. -If @var{pos} is out of range, the value is @code{nil}. -@end defun - -@defun find-charset-region beg end &optional translation -This function returns a list of the character sets of highest priority -that contain characters in the current buffer between positions -@var{beg} and @var{end}. - -The optional argument @var{translation} specifies a translation table -to use for scanning the text (@pxref{Translation of Characters}). If -it is non-@code{nil}, then each character in the region is translated -through this table, and the value returned describes the translated -characters instead of the characters actually in the buffer. -@end defun - -@defun find-charset-string string &optional translation -This function returns a list of character sets of highest priority -that contain characters in @var{string}. It is just like -@code{find-charset-region}, except that it applies to the contents of -@var{string} instead of part of the current buffer. -@end defun - -@node Translation of Characters -@section Translation of Characters -@cindex character translation tables -@cindex translation tables - - A @dfn{translation table} is a char-table (@pxref{Char-Tables}) that -specifies a mapping of characters into characters. These tables are -used in encoding and decoding, and for other purposes. Some coding -systems specify their own particular translation tables; there are -also default translation tables which apply to all other coding -systems. - - A translation table has two extra slots. The first is either -@code{nil} or a translation table that performs the reverse -translation; the second is the maximum number of characters to look up -for translating sequences of characters (see the description of -@code{make-translation-table-from-alist} below). - -@defun make-translation-table &rest translations -This function returns a translation table based on the argument -@var{translations}. Each element of @var{translations} should be a -list of elements of the form @code{(@var{from} . @var{to})}; this says -to translate the character @var{from} into @var{to}. - -The arguments and the forms in each argument are processed in order, -and if a previous form already translates @var{to} to some other -character, say @var{to-alt}, @var{from} is also translated to -@var{to-alt}. -@end defun - - During decoding, the translation table's translations are applied to -the characters that result from ordinary decoding. If a coding system -has the property @code{:decode-translation-table}, that specifies the -translation table to use, or a list of translation tables to apply in -sequence. (This is a property of the coding system, as returned by -@code{coding-system-get}, not a property of the symbol that is the -coding system's name. @xref{Coding System Basics,, Basic Concepts of -Coding Systems}.) Finally, if -@code{standard-translation-table-for-decode} is non-@code{nil}, the -resulting characters are translated by that table. - - During encoding, the translation table's translations are applied to -the characters in the buffer, and the result of translation is -actually encoded. If a coding system has property -@code{:encode-translation-table}, that specifies the translation table -to use, or a list of translation tables to apply in sequence. In -addition, if the variable @code{standard-translation-table-for-encode} -is non-@code{nil}, it specifies the translation table to use for -translating the result. - -@defvar standard-translation-table-for-decode -This is the default translation table for decoding. If a coding -systems specifies its own translation tables, the table that is the -value of this variable, if non-@code{nil}, is applied after them. -@end defvar - -@defvar standard-translation-table-for-encode -This is the default translation table for encoding. If a coding -systems specifies its own translation tables, the table that is the -value of this variable, if non-@code{nil}, is applied after them. -@end defvar - -@defvar translation-table-for-input -Self-inserting characters are translated through this translation -table before they are inserted. Search commands also translate their -input through this table, so they can compare more reliably with -what's in the buffer. - -This variable automatically becomes buffer-local when set. -@end defvar - -@defun make-translation-table-from-vector vec -This function returns a translation table made from @var{vec} that is -an array of 256 elements to map bytes (values 0 through #xFF) to -characters. Elements may be @code{nil} for untranslated bytes. The -returned table has a translation table for reverse mapping in the -first extra slot, and the value @code{1} in the second extra slot. - -This function provides an easy way to make a private coding system -that maps each byte to a specific character. You can specify the -returned table and the reverse translation table using the properties -@code{:decode-translation-table} and @code{:encode-translation-table} -respectively in the @var{props} argument to -@code{define-coding-system}. -@end defun - -@defun make-translation-table-from-alist alist -This function is similar to @code{make-translation-table} but returns -a complex translation table rather than a simple one-to-one mapping. -Each element of @var{alist} is of the form @code{(@var{from} -. @var{to})}, where @var{from} and @var{to} are either characters or -vectors specifying a sequence of characters. If @var{from} is a -character, that character is translated to @var{to} (i.e.@: to a -character or a character sequence). If @var{from} is a vector of -characters, that sequence is translated to @var{to}. The returned -table has a translation table for reverse mapping in the first extra -slot, and the maximum length of all the @var{from} character sequences -in the second extra slot. -@end defun - -@node Coding Systems -@section Coding Systems - -@cindex coding system - When Emacs reads or writes a file, and when Emacs sends text to a -subprocess or receives text from a subprocess, it normally performs -character code conversion and end-of-line conversion as specified -by a particular @dfn{coding system}. - - How to define a coding system is an arcane matter, and is not -documented here. - -@menu -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -* MS-DOS File Types:: How DOS "text" and "binary" files - relate to coding systems. -@end menu - -@node Coding System Basics -@subsection Basic Concepts of Coding Systems - -@cindex character code conversion - @dfn{Character code conversion} involves conversion between the -internal representation of characters used inside Emacs and some other -encoding. Emacs supports many different encodings, in that it can -convert to and from them. For example, it can convert text to or from -encodings such as Latin 1, Latin 2, Latin 3, Latin 4, Latin 5, and -several variants of ISO 2022. In some cases, Emacs supports several -alternative encodings for the same characters; for example, there are -three coding systems for the Cyrillic (Russian) alphabet: ISO, -Alternativnyj, and KOI8. - - Every coding system specifies a particular set of character code -conversions, but the coding system @code{undecided} is special: it -leaves the choice unspecified, to be chosen heuristically for each -file, based on the file's data. - - In general, a coding system doesn't guarantee roundtrip identity: -decoding a byte sequence using coding system, then encoding the -resulting text in the same coding system, can produce a different byte -sequence. But some coding systems do guarantee that the byte sequence -will be the same as what you originally decoded. Here are a few -examples: - -@quotation -iso-8859-1, utf-8, big5, shift_jis, euc-jp -@end quotation - - Encoding buffer text and then decoding the result can also fail to -reproduce the original text. For instance, if you encode a character -with a coding system which does not support that character, the result -is unpredictable, and thus decoding it using the same coding system -may produce a different text. Currently, Emacs can't report errors -that result from encoding unsupported characters. - -@cindex EOL conversion -@cindex end-of-line conversion -@cindex line end conversion - @dfn{End of line conversion} handles three different conventions -used on various systems for representing end of line in files. The -Unix convention, used on GNU and Unix systems, is to use the linefeed -character (also called newline). The DOS convention, used on -MS-Windows and MS-DOS systems, is to use a carriage-return and a -linefeed at the end of a line. The Mac convention is to use just -carriage-return. - -@cindex base coding system -@cindex variant coding system - @dfn{Base coding systems} such as @code{latin-1} leave the end-of-line -conversion unspecified, to be chosen based on the data. @dfn{Variant -coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and -@code{latin-1-mac} specify the end-of-line conversion explicitly as -well. Most base coding systems have three corresponding variants whose -names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}. - -@vindex raw-text@r{ coding system} - The coding system @code{raw-text} is special in that it prevents -character code conversion, and causes the buffer visited with this -coding system to be a unibyte buffer. For historical reasons, you can -save both unibyte and multibyte text with this coding system. When -you use @code{raw-text} to encode multibyte text, it does perform one -character code conversion: it converts eight-bit characters to their -single-byte external representation. @code{raw-text} does not specify -the end-of-line conversion, allowing that to be determined as usual by -the data, and has the usual three variants which specify the -end-of-line conversion. - -@vindex no-conversion@r{ coding system} -@vindex binary@r{ coding system} - @code{no-conversion} (and its alias @code{binary}) is equivalent to -@code{raw-text-unix}: it specifies no conversion of either character -codes or end-of-line. - -@vindex emacs-internal@r{ coding system} -@vindex utf-8-emacs@r{ coding system} - The coding system @code{utf-8-emacs} specifies that the data is -represented in the internal Emacs encoding (@pxref{Text -Representations}). This is like @code{raw-text} in that no code -conversion happens, but different in that the result is multibyte -data. The name @code{emacs-internal} is an alias for -@code{utf-8-emacs}. - -@defun coding-system-get coding-system property -This function returns the specified property of the coding system -@var{coding-system}. Most coding system properties exist for internal -purposes, but one that you might find useful is @code{:mime-charset}. -That property's value is the name used in MIME for the character coding -which this coding system can read and write. Examples: - -@example -(coding-system-get 'iso-latin-1 :mime-charset) - @result{} iso-8859-1 -(coding-system-get 'iso-2022-cn :mime-charset) - @result{} iso-2022-cn -(coding-system-get 'cyrillic-koi8 :mime-charset) - @result{} koi8-r -@end example - -The value of the @code{:mime-charset} property is also defined -as an alias for the coding system. -@end defun - -@defun coding-system-aliases coding-system -This function returns the list of aliases of @var{coding-system}. -@end defun - -@node Encoding and I/O -@subsection Encoding and I/O - - The principal purpose of coding systems is for use in reading and -writing files. The function @code{insert-file-contents} uses a coding -system to decode the file data, and @code{write-region} uses one to -encode the buffer contents. - - You can specify the coding system to use either explicitly -(@pxref{Specifying Coding Systems}), or implicitly using a default -mechanism (@pxref{Default Coding Systems}). But these methods may not -completely specify what to do. For example, they may choose a coding -system such as @code{undefined} which leaves the character code -conversion to be determined from the data. In these cases, the I/O -operation finishes the job of choosing a coding system. Very often -you will want to find out afterwards which coding system was chosen. - -@defvar buffer-file-coding-system -This buffer-local variable records the coding system used for saving the -buffer and for writing part of the buffer with @code{write-region}. If -the text to be written cannot be safely encoded using the coding system -specified by this variable, these operations select an alternative -encoding by calling the function @code{select-safe-coding-system} -(@pxref{User-Chosen Coding Systems}). If selecting a different encoding -requires to ask the user to specify a coding system, -@code{buffer-file-coding-system} is updated to the newly selected coding -system. - -@code{buffer-file-coding-system} does @emph{not} affect sending text -to a subprocess. -@end defvar - -@defvar save-buffer-coding-system -This variable specifies the coding system for saving the buffer (by -overriding @code{buffer-file-coding-system}). Note that it is not used -for @code{write-region}. - -When a command to save the buffer starts out to use -@code{buffer-file-coding-system} (or @code{save-buffer-coding-system}), -and that coding system cannot handle -the actual text in the buffer, the command asks the user to choose -another coding system (by calling @code{select-safe-coding-system}). -After that happens, the command also updates -@code{buffer-file-coding-system} to represent the coding system that -the user specified. -@end defvar - -@defvar last-coding-system-used -I/O operations for files and subprocesses set this variable to the -coding system name that was used. The explicit encoding and decoding -functions (@pxref{Explicit Encoding}) set it too. - -@strong{Warning:} Since receiving subprocess output sets this variable, -it can change whenever Emacs waits; therefore, you should copy the -value shortly after the function call that stores the value you are -interested in. -@end defvar - - The variable @code{selection-coding-system} specifies how to encode -selections for the window system. @xref{Window System Selections}. - -@defvar file-name-coding-system -The variable @code{file-name-coding-system} specifies the coding -system to use for encoding file names. Emacs encodes file names using -that coding system for all file operations. If -@code{file-name-coding-system} is @code{nil}, Emacs uses a default -coding system determined by the selected language environment. In the -default language environment, any non-@acronym{ASCII} characters in -file names are not encoded specially; they appear in the file system -using the internal Emacs representation. -@end defvar - - @strong{Warning:} if you change @code{file-name-coding-system} (or -the language environment) in the middle of an Emacs session, problems -can result if you have already visited files whose names were encoded -using the earlier coding system and are handled differently under the -new coding system. If you try to save one of these buffers under the -visited file name, saving may use the wrong file name, or it may get -an error. If such a problem happens, use @kbd{C-x C-w} to specify a -new file name for that buffer. - -@node Lisp and Coding Systems -@subsection Coding Systems in Lisp - - Here are the Lisp facilities for working with coding systems: - -@cindex list all coding systems -@defun coding-system-list &optional base-only -This function returns a list of all coding system names (symbols). If -@var{base-only} is non-@code{nil}, the value includes only the -base coding systems. Otherwise, it includes alias and variant coding -systems as well. -@end defun - -@defun coding-system-p object -This function returns @code{t} if @var{object} is a coding system -name or @code{nil}. -@end defun - -@cindex validity of coding system -@cindex coding system, validity check -@defun check-coding-system coding-system -This function checks the validity of @var{coding-system}. If that is -valid, it returns @var{coding-system}. If @var{coding-system} is -@code{nil}, the function return @code{nil}. For any other values, it -signals an error whose @code{error-symbol} is @code{coding-system-error} -(@pxref{Signaling Errors, signal}). -@end defun - -@cindex eol type of coding system -@defun coding-system-eol-type coding-system -This function returns the type of end-of-line (a.k.a.@: @dfn{eol}) -conversion used by @var{coding-system}. If @var{coding-system} -specifies a certain eol conversion, the return value is an integer 0, -1, or 2, standing for @code{unix}, @code{dos}, and @code{mac}, -respectively. If @var{coding-system} doesn't specify eol conversion -explicitly, the return value is a vector of coding systems, each one -with one of the possible eol conversion types, like this: - -@lisp -(coding-system-eol-type 'latin-1) - @result{} [latin-1-unix latin-1-dos latin-1-mac] -@end lisp - -@noindent -If this function returns a vector, Emacs will decide, as part of the -text encoding or decoding process, what eol conversion to use. For -decoding, the end-of-line format of the text is auto-detected, and the -eol conversion is set to match it (e.g., DOS-style CRLF format will -imply @code{dos} eol conversion). For encoding, the eol conversion is -taken from the appropriate default coding system (e.g., -default value of @code{buffer-file-coding-system} for -@code{buffer-file-coding-system}), or from the default eol conversion -appropriate for the underlying platform. -@end defun - -@cindex eol conversion of coding system -@defun coding-system-change-eol-conversion coding-system eol-type -This function returns a coding system which is like @var{coding-system} -except for its eol conversion, which is specified by @code{eol-type}. -@var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or -@code{nil}. If it is @code{nil}, the returned coding system determines -the end-of-line conversion from the data. - -@var{eol-type} may also be 0, 1 or 2, standing for @code{unix}, -@code{dos} and @code{mac}, respectively. -@end defun - -@cindex text conversion of coding system -@defun coding-system-change-text-conversion eol-coding text-coding -This function returns a coding system which uses the end-of-line -conversion of @var{eol-coding}, and the text conversion of -@var{text-coding}. If @var{text-coding} is @code{nil}, it returns -@code{undecided}, or one of its variants according to @var{eol-coding}. -@end defun - -@cindex safely encode region -@cindex coding systems for encoding region -@defun find-coding-systems-region from to -This function returns a list of coding systems that could be used to -encode a text between @var{from} and @var{to}. All coding systems in -the list can safely encode any multibyte characters in that portion of -the text. - -If the text contains no multibyte characters, the function returns the -list @code{(undecided)}. -@end defun - -@cindex safely encode a string -@cindex coding systems for encoding a string -@defun find-coding-systems-string string -This function returns a list of coding systems that could be used to -encode the text of @var{string}. All coding systems in the list can -safely encode any multibyte characters in @var{string}. If the text -contains no multibyte characters, this returns the list -@code{(undecided)}. -@end defun - -@cindex charset, coding systems to encode -@cindex safely encode characters in a charset -@defun find-coding-systems-for-charsets charsets -This function returns a list of coding systems that could be used to -encode all the character sets in the list @var{charsets}. -@end defun - -@defun check-coding-systems-region start end coding-system-list -This function checks whether coding systems in the list -@code{coding-system-list} can encode all the characters in the region -between @var{start} and @var{end}. If all of the coding systems in -the list can encode the specified text, the function returns -@code{nil}. If some coding systems cannot encode some of the -characters, the value is an alist, each element of which has the form -@code{(@var{coding-system1} @var{pos1} @var{pos2} @dots{})}, meaning -that @var{coding-system1} cannot encode characters at buffer positions -@var{pos1}, @var{pos2}, @enddots{}. - -@var{start} may be a string, in which case @var{end} is ignored and -the returned value references string indices instead of buffer -positions. -@end defun - -@defun detect-coding-region start end &optional highest -This function chooses a plausible coding system for decoding the text -from @var{start} to @var{end}. This text should be a byte sequence, -i.e.@: unibyte text or multibyte text with only @acronym{ASCII} and -eight-bit characters (@pxref{Explicit Encoding}). - -Normally this function returns a list of coding systems that could -handle decoding the text that was scanned. They are listed in order of -decreasing priority. But if @var{highest} is non-@code{nil}, then the -return value is just one coding system, the one that is highest in -priority. - -If the region contains only @acronym{ASCII} characters except for such -ISO-2022 control characters ISO-2022 as @code{ESC}, the value is -@code{undecided} or @code{(undecided)}, or a variant specifying -end-of-line conversion, if that can be deduced from the text. - -If the region contains null bytes, the value is @code{no-conversion}, -even if the region contains text encoded in some coding system. -@end defun - -@defun detect-coding-string string &optional highest -This function is like @code{detect-coding-region} except that it -operates on the contents of @var{string} instead of bytes in the buffer. -@end defun - -@cindex null bytes, and decoding text -@defvar inhibit-null-byte-detection -If this variable has a non-@code{nil} value, null bytes are ignored -when detecting the encoding of a region or a string. This allows to -correctly detect the encoding of text that contains null bytes, such -as Info files with Index nodes. -@end defvar - -@defvar inhibit-iso-escape-detection -If this variable has a non-@code{nil} value, ISO-2022 escape sequences -are ignored when detecting the encoding of a region or a string. The -result is that no text is ever detected as encoded in some ISO-2022 -encoding, and all escape sequences become visible in a buffer. -@strong{Warning:} @emph{Use this variable with extreme caution, -because many files in the Emacs distribution use ISO-2022 encoding.} -@end defvar - -@cindex charsets supported by a coding system -@defun coding-system-charset-list coding-system -This function returns the list of character sets (@pxref{Character -Sets}) supported by @var{coding-system}. Some coding systems that -support too many character sets to list them all yield special values: -@itemize @bullet -@item -If @var{coding-system} supports all the ISO-2022 charsets, the value -is @code{iso-2022}. -@item -If @var{coding-system} supports all Emacs characters, the value is -@code{(emacs)}. -@item -If @var{coding-system} supports all emacs-mule characters, the value -is @code{emacs-mule}. -@item -If @var{coding-system} supports all Unicode characters, the value is -@code{(unicode)}. -@end itemize -@end defun - - @xref{Coding systems for a subprocess,, Process Information}, in -particular the description of the functions -@code{process-coding-system} and @code{set-process-coding-system}, for -how to examine or set the coding systems used for I/O to a subprocess. - -@node User-Chosen Coding Systems -@subsection User-Chosen Coding Systems - -@cindex select safe coding system -@defun select-safe-coding-system from to &optional default-coding-system accept-default-p file -This function selects a coding system for encoding specified text, -asking the user to choose if necessary. Normally the specified text -is the text in the current buffer between @var{from} and @var{to}. If -@var{from} is a string, the string specifies the text to encode, and -@var{to} is ignored. - -If the specified text includes raw bytes (@pxref{Text -Representations}), @code{select-safe-coding-system} suggests -@code{raw-text} for its encoding. - -If @var{default-coding-system} is non-@code{nil}, that is the first -coding system to try; if that can handle the text, -@code{select-safe-coding-system} returns that coding system. It can -also be a list of coding systems; then the function tries each of them -one by one. After trying all of them, it next tries the current -buffer's value of @code{buffer-file-coding-system} (if it is not -@code{undecided}), then the default value of -@code{buffer-file-coding-system} and finally the user's most -preferred coding system, which the user can set using the command -@code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing -Coding Systems, emacs, The GNU Emacs Manual}). - -If one of those coding systems can safely encode all the specified -text, @code{select-safe-coding-system} chooses it and returns it. -Otherwise, it asks the user to choose from a list of coding systems -which can encode all the text, and returns the user's choice. - -@var{default-coding-system} can also be a list whose first element is -t and whose other elements are coding systems. Then, if no coding -system in the list can handle the text, @code{select-safe-coding-system} -queries the user immediately, without trying any of the three -alternatives described above. - -The optional argument @var{accept-default-p}, if non-@code{nil}, -should be a function to determine whether a coding system selected -without user interaction is acceptable. @code{select-safe-coding-system} -calls this function with one argument, the base coding system of the -selected coding system. If @var{accept-default-p} returns @code{nil}, -@code{select-safe-coding-system} rejects the silently selected coding -system, and asks the user to select a coding system from a list of -possible candidates. - -@vindex select-safe-coding-system-accept-default-p -If the variable @code{select-safe-coding-system-accept-default-p} is -non-@code{nil}, it should be a function taking a single argument. -It is used in place of @var{accept-default-p}, overriding any -value supplied for this argument. - -As a final step, before returning the chosen coding system, -@code{select-safe-coding-system} checks whether that coding system is -consistent with what would be selected if the contents of the region -were read from a file. (If not, this could lead to data corruption in -a file subsequently re-visited and edited.) Normally, -@code{select-safe-coding-system} uses @code{buffer-file-name} as the -file for this purpose, but if @var{file} is non-@code{nil}, it uses -that file instead (this can be relevant for @code{write-region} and -similar functions). If it detects an apparent inconsistency, -@code{select-safe-coding-system} queries the user before selecting the -coding system. -@end defun - - Here are two functions you can use to let the user specify a coding -system, with completion. @xref{Completion}. - -@defun read-coding-system prompt &optional default -This function reads a coding system using the minibuffer, prompting with -string @var{prompt}, and returns the coding system name as a symbol. If -the user enters null input, @var{default} specifies which coding system -to return. It should be a symbol or a string. -@end defun - -@defun read-non-nil-coding-system prompt -This function reads a coding system using the minibuffer, prompting with -string @var{prompt}, and returns the coding system name as a symbol. If -the user tries to enter null input, it asks the user to try again. -@xref{Coding Systems}. -@end defun - -@node Default Coding Systems -@subsection Default Coding Systems -@cindex default coding system -@cindex coding system, automatically determined - - This section describes variables that specify the default coding -system for certain files or when running certain subprograms, and the -function that I/O operations use to access them. - - The idea of these variables is that you set them once and for all to the -defaults you want, and then do not change them again. To specify a -particular coding system for a particular operation in a Lisp program, -don't change these variables; instead, override them using -@code{coding-system-for-read} and @code{coding-system-for-write} -(@pxref{Specifying Coding Systems}). - -@cindex file contents, and default coding system -@defopt auto-coding-regexp-alist -This variable is an alist of text patterns and corresponding coding -systems. Each element has the form @code{(@var{regexp} -. @var{coding-system})}; a file whose first few kilobytes match -@var{regexp} is decoded with @var{coding-system} when its contents are -read into a buffer. The settings in this alist take priority over -@code{coding:} tags in the files and the contents of -@code{file-coding-system-alist} (see below). The default value is set -so that Emacs automatically recognizes mail files in Babyl format and -reads them with no code conversions. -@end defopt - -@cindex file name, and default coding system -@defopt file-coding-system-alist -This variable is an alist that specifies the coding systems to use for -reading and writing particular files. Each element has the form -@code{(@var{pattern} . @var{coding})}, where @var{pattern} is a regular -expression that matches certain file names. The element applies to file -names that match @var{pattern}. - -The @sc{cdr} of the element, @var{coding}, should be either a coding -system, a cons cell containing two coding systems, or a function name (a -symbol with a function definition). If @var{coding} is a coding system, -that coding system is used for both reading the file and writing it. If -@var{coding} is a cons cell containing two coding systems, its @sc{car} -specifies the coding system for decoding, and its @sc{cdr} specifies the -coding system for encoding. - -If @var{coding} is a function name, the function should take one -argument, a list of all arguments passed to -@code{find-operation-coding-system}. It must return a coding system -or a cons cell containing two coding systems. This value has the same -meaning as described above. - -If @var{coding} (or what returned by the above function) is -@code{undecided}, the normal code-detection is performed. -@end defopt - -@defopt auto-coding-alist -This variable is an alist that specifies the coding systems to use for -reading and writing particular files. Its form is like that of -@code{file-coding-system-alist}, but, unlike the latter, this variable -takes priority over any @code{coding:} tags in the file. -@end defopt - -@cindex program name, and default coding system -@defvar process-coding-system-alist -This variable is an alist specifying which coding systems to use for a -subprocess, depending on which program is running in the subprocess. It -works like @code{file-coding-system-alist}, except that @var{pattern} is -matched against the program name used to start the subprocess. The coding -system or systems specified in this alist are used to initialize the -coding systems used for I/O to the subprocess, but you can specify -other coding systems later using @code{set-process-coding-system}. -@end defvar - - @strong{Warning:} Coding systems such as @code{undecided}, which -determine the coding system from the data, do not work entirely reliably -with asynchronous subprocess output. This is because Emacs handles -asynchronous subprocess output in batches, as it arrives. If the coding -system leaves the character code conversion unspecified, or leaves the -end-of-line conversion unspecified, Emacs must try to detect the proper -conversion from one batch at a time, and this does not always work. - - Therefore, with an asynchronous subprocess, if at all possible, use a -coding system which determines both the character code conversion and -the end of line conversion---that is, one like @code{latin-1-unix}, -rather than @code{undecided} or @code{latin-1}. - -@cindex port number, and default coding system -@cindex network service name, and default coding system -@defvar network-coding-system-alist -This variable is an alist that specifies the coding system to use for -network streams. It works much like @code{file-coding-system-alist}, -with the difference that the @var{pattern} in an element may be either a -port number or a regular expression. If it is a regular expression, it -is matched against the network service name used to open the network -stream. -@end defvar - -@defvar default-process-coding-system -This variable specifies the coding systems to use for subprocess (and -network stream) input and output, when nothing else specifies what to -do. - -The value should be a cons cell of the form @code{(@var{input-coding} -. @var{output-coding})}. Here @var{input-coding} applies to input from -the subprocess, and @var{output-coding} applies to output to it. -@end defvar - -@cindex default coding system, functions to determine -@defopt auto-coding-functions -This variable holds a list of functions that try to determine a -coding system for a file based on its undecoded contents. - -Each function in this list should be written to look at text in the -current buffer, but should not modify it in any way. The buffer will -contain undecoded text of parts of the file. Each function should -take one argument, @var{size}, which tells it how many characters to -look at, starting from point. If the function succeeds in determining -a coding system for the file, it should return that coding system. -Otherwise, it should return @code{nil}. - -If a file has a @samp{coding:} tag, that takes precedence, so these -functions won't be called. -@end defopt - -@defun find-auto-coding filename size -This function tries to determine a suitable coding system for -@var{filename}. It examines the buffer visiting the named file, using -the variables documented above in sequence, until it finds a match for -one of the rules specified by these variables. It then returns a cons -cell of the form @code{(@var{coding} . @var{source})}, where -@var{coding} is the coding system to use and @var{source} is a symbol, -one of @code{auto-coding-alist}, @code{auto-coding-regexp-alist}, -@code{:coding}, or @code{auto-coding-functions}, indicating which one -supplied the matching rule. The value @code{:coding} means the coding -system was specified by the @code{coding:} tag in the file -(@pxref{Specify Coding,, coding tag, emacs, The GNU Emacs Manual}). -The order of looking for a matching rule is @code{auto-coding-alist} -first, then @code{auto-coding-regexp-alist}, then the @code{coding:} -tag, and lastly @code{auto-coding-functions}. If no matching rule was -found, the function returns @code{nil}. - -The second argument @var{size} is the size of text, in characters, -following point. The function examines text only within @var{size} -characters after point. Normally, the buffer should be positioned at -the beginning when this function is called, because one of the places -for the @code{coding:} tag is the first one or two lines of the file; -in that case, @var{size} should be the size of the buffer. -@end defun - -@defun set-auto-coding filename size -This function returns a suitable coding system for file -@var{filename}. It uses @code{find-auto-coding} to find the coding -system. If no coding system could be determined, the function returns -@code{nil}. The meaning of the argument @var{size} is like in -@code{find-auto-coding}. -@end defun - -@defun find-operation-coding-system operation &rest arguments -This function returns the coding system to use (by default) for -performing @var{operation} with @var{arguments}. The value has this -form: - -@example -(@var{decoding-system} . @var{encoding-system}) -@end example - -The first element, @var{decoding-system}, is the coding system to use -for decoding (in case @var{operation} does decoding), and -@var{encoding-system} is the coding system for encoding (in case -@var{operation} does encoding). - -The argument @var{operation} is a symbol; it should be one of -@code{write-region}, @code{start-process}, @code{call-process}, -@code{call-process-region}, @code{insert-file-contents}, or -@code{open-network-stream}. These are the names of the Emacs I/O -primitives that can do character code and eol conversion. - -The remaining arguments should be the same arguments that might be given -to the corresponding I/O primitive. Depending on the primitive, one -of those arguments is selected as the @dfn{target}. For example, if -@var{operation} does file I/O, whichever argument specifies the file -name is the target. For subprocess primitives, the process name is the -target. For @code{open-network-stream}, the target is the service name -or port number. - -Depending on @var{operation}, this function looks up the target in -@code{file-coding-system-alist}, @code{process-coding-system-alist}, -or @code{network-coding-system-alist}. If the target is found in the -alist, @code{find-operation-coding-system} returns its association in -the alist; otherwise it returns @code{nil}. - -If @var{operation} is @code{insert-file-contents}, the argument -corresponding to the target may be a cons cell of the form -@code{(@var{filename} . @var{buffer})}). In that case, @var{filename} -is a file name to look up in @code{file-coding-system-alist}, and -@var{buffer} is a buffer that contains the file's contents (not yet -decoded). If @code{file-coding-system-alist} specifies a function to -call for this file, and that function needs to examine the file's -contents (as it usually does), it should examine the contents of -@var{buffer} instead of reading the file. -@end defun - -@node Specifying Coding Systems -@subsection Specifying a Coding System for One Operation - - You can specify the coding system for a specific operation by binding -the variables @code{coding-system-for-read} and/or -@code{coding-system-for-write}. - -@defvar coding-system-for-read -If this variable is non-@code{nil}, it specifies the coding system to -use for reading a file, or for input from a synchronous subprocess. - -It also applies to any asynchronous subprocess or network stream, but in -a different way: the value of @code{coding-system-for-read} when you -start the subprocess or open the network stream specifies the input -decoding method for that subprocess or network stream. It remains in -use for that subprocess or network stream unless and until overridden. - -The right way to use this variable is to bind it with @code{let} for a -specific I/O operation. Its global value is normally @code{nil}, and -you should not globally set it to any other value. Here is an example -of the right way to use the variable: - -@example -;; @r{Read the file with no character code conversion.} -;; @r{Assume @acronym{crlf} represents end-of-line.} -(let ((coding-system-for-read 'emacs-mule-dos)) - (insert-file-contents filename)) -@end example - -When its value is non-@code{nil}, this variable takes precedence over -all other methods of specifying a coding system to use for input, -including @code{file-coding-system-alist}, -@code{process-coding-system-alist} and -@code{network-coding-system-alist}. -@end defvar - -@defvar coding-system-for-write -This works much like @code{coding-system-for-read}, except that it -applies to output rather than input. It affects writing to files, -as well as sending output to subprocesses and net connections. - -When a single operation does both input and output, as do -@code{call-process-region} and @code{start-process}, both -@code{coding-system-for-read} and @code{coding-system-for-write} -affect it. -@end defvar - -@defopt inhibit-eol-conversion -When this variable is non-@code{nil}, no end-of-line conversion is done, -no matter which coding system is specified. This applies to all the -Emacs I/O and subprocess primitives, and to the explicit encoding and -decoding functions (@pxref{Explicit Encoding}). -@end defopt - -@cindex priority order of coding systems -@cindex coding systems, priority - Sometimes, you need to prefer several coding systems for some -operation, rather than fix a single one. Emacs lets you specify a -priority order for using coding systems. This ordering affects the -sorting of lists of coding systems returned by functions such as -@code{find-coding-systems-region} (@pxref{Lisp and Coding Systems}). - -@defun coding-system-priority-list &optional highestp -This function returns the list of coding systems in the order of their -current priorities. Optional argument @var{highestp}, if -non-@code{nil}, means return only the highest priority coding system. -@end defun - -@defun set-coding-system-priority &rest coding-systems -This function puts @var{coding-systems} at the beginning of the -priority list for coding systems, thus making their priority higher -than all the rest. -@end defun - -@defmac with-coding-priority coding-systems &rest body@dots{} -This macro execute @var{body}, like @code{progn} does -(@pxref{Sequencing, progn}), with @var{coding-systems} at the front of -the priority list for coding systems. @var{coding-systems} should be -a list of coding systems to prefer during execution of @var{body}. -@end defmac - -@node Explicit Encoding -@subsection Explicit Encoding and Decoding -@cindex encoding in coding systems -@cindex decoding in coding systems - - All the operations that transfer text in and out of Emacs have the -ability to use a coding system to encode or decode the text. -You can also explicitly encode and decode text using the functions -in this section. - - The result of encoding, and the input to decoding, are not ordinary -text. They logically consist of a series of byte values; that is, a -series of @acronym{ASCII} and eight-bit characters. In unibyte -buffers and strings, these characters have codes in the range 0 -through #xFF (255). In a multibyte buffer or string, eight-bit -characters have character codes higher than #xFF (@pxref{Text -Representations}), but Emacs transparently converts them to their -single-byte values when you encode or decode such text. - - The usual way to read a file into a buffer as a sequence of bytes, so -you can decode the contents explicitly, is with -@code{insert-file-contents-literally} (@pxref{Reading from Files}); -alternatively, specify a non-@code{nil} @var{rawfile} argument when -visiting a file with @code{find-file-noselect}. These methods result in -a unibyte buffer. - - The usual way to use the byte sequence that results from explicitly -encoding text is to copy it to a file or process---for example, to write -it with @code{write-region} (@pxref{Writing to Files}), and suppress -encoding by binding @code{coding-system-for-write} to -@code{no-conversion}. - - Here are the functions to perform explicit encoding or decoding. The -encoding functions produce sequences of bytes; the decoding functions -are meant to operate on sequences of bytes. All of these functions -discard text properties. They also set @code{last-coding-system-used} -to the precise coding system they used. - -@deffn Command encode-coding-region start end coding-system &optional destination -This command encodes the text from @var{start} to @var{end} according -to coding system @var{coding-system}. Normally, the encoded text -replaces the original text in the buffer, but the optional argument -@var{destination} can change that. If @var{destination} is a buffer, -the encoded text is inserted in that buffer after point (point does -not move); if it is @code{t}, the command returns the encoded text as -a unibyte string without inserting it. - -If encoded text is inserted in some buffer, this command returns the -length of the encoded text. - -The result of encoding is logically a sequence of bytes, but the -buffer remains multibyte if it was multibyte before, and any 8-bit -bytes are converted to their multibyte representation (@pxref{Text -Representations}). - -@cindex @code{undecided} coding-system, when encoding -Do @emph{not} use @code{undecided} for @var{coding-system} when -encoding text, since that may lead to unexpected results. Instead, -use @code{select-safe-coding-system} (@pxref{User-Chosen Coding -Systems, select-safe-coding-system}) to suggest a suitable encoding, -if there's no obvious pertinent value for @var{coding-system}. -@end deffn - -@defun encode-coding-string string coding-system &optional nocopy buffer -This function encodes the text in @var{string} according to coding -system @var{coding-system}. It returns a new string containing the -encoded text, except when @var{nocopy} is non-@code{nil}, in which -case the function may return @var{string} itself if the encoding -operation is trivial. The result of encoding is a unibyte string. -@end defun - -@deffn Command decode-coding-region start end coding-system &optional destination -This command decodes the text from @var{start} to @var{end} according -to coding system @var{coding-system}. To make explicit decoding -useful, the text before decoding ought to be a sequence of byte -values, but both multibyte and unibyte buffers are acceptable (in the -multibyte case, the raw byte values should be represented as eight-bit -characters). Normally, the decoded text replaces the original text in -the buffer, but the optional argument @var{destination} can change -that. If @var{destination} is a buffer, the decoded text is inserted -in that buffer after point (point does not move); if it is @code{t}, -the command returns the decoded text as a multibyte string without -inserting it. - -If decoded text is inserted in some buffer, this command returns the -length of the decoded text. - -This command puts a @code{charset} text property on the decoded text. -The value of the property states the character set used to decode the -original text. -@end deffn - -@defun decode-coding-string string coding-system &optional nocopy buffer -This function decodes the text in @var{string} according to -@var{coding-system}. It returns a new string containing the decoded -text, except when @var{nocopy} is non-@code{nil}, in which case the -function may return @var{string} itself if the decoding operation is -trivial. To make explicit decoding useful, the contents of -@var{string} ought to be a unibyte string with a sequence of byte -values, but a multibyte string is also acceptable (assuming it -contains 8-bit bytes in their multibyte form). - -If optional argument @var{buffer} specifies a buffer, the decoded text -is inserted in that buffer after point (point does not move). In this -case, the return value is the length of the decoded text. - -@cindex @code{charset}, text property -This function puts a @code{charset} text property on the decoded text. -The value of the property states the character set used to decode the -original text: - -@example -@group -(decode-coding-string "Gr\374ss Gott" 'latin-1) - @result{} #("Gr@"uss Gott" 0 9 (charset iso-8859-1)) -@end group -@end example -@end defun - -@defun decode-coding-inserted-region from to filename &optional visit beg end replace -This function decodes the text from @var{from} to @var{to} as if -it were being read from file @var{filename} using @code{insert-file-contents} -using the rest of the arguments provided. - -The normal way to use this function is after reading text from a file -without decoding, if you decide you would rather have decoded it. -Instead of deleting the text and reading it again, this time with -decoding, you can call this function. -@end defun - -@node Terminal I/O Encoding -@subsection Terminal I/O Encoding - - Emacs can decode keyboard input using a coding system, and encode -terminal output. This is useful for terminals that transmit or -display text using a particular encoding such as Latin-1. Emacs does -not set @code{last-coding-system-used} for encoding or decoding of -terminal I/O. - -@defun keyboard-coding-system &optional terminal -This function returns the coding system that is in use for decoding -keyboard input from @var{terminal}---or @code{nil} if no coding system -is to be used for that terminal. If @var{terminal} is omitted or -@code{nil}, it means the selected frame's terminal. @xref{Multiple -Terminals}. -@end defun - -@deffn Command set-keyboard-coding-system coding-system &optional terminal -This command specifies @var{coding-system} as the coding system to use -for decoding keyboard input from @var{terminal}. If -@var{coding-system} is @code{nil}, that means do not decode keyboard -input. If @var{terminal} is a frame, it means that frame's terminal; -if it is @code{nil}, that means the currently selected frame's -terminal. @xref{Multiple Terminals}. -@end deffn - -@defun terminal-coding-system &optional terminal -This function returns the coding system that is in use for encoding -terminal output from @var{terminal}---or @code{nil} if the output is -not encoded. If @var{terminal} is a frame, it means that frame's -terminal; if it is @code{nil}, that means the currently selected -frame's terminal. -@end defun - -@deffn Command set-terminal-coding-system coding-system &optional terminal -This command specifies @var{coding-system} as the coding system to use -for encoding terminal output from @var{terminal}. If -@var{coding-system} is @code{nil}, terminal output is not encoded. If -@var{terminal} is a frame, it means that frame's terminal; if it is -@code{nil}, that means the currently selected frame's terminal. -@end deffn - -@node MS-DOS File Types -@subsection MS-DOS File Types -@cindex DOS file types -@cindex MS-DOS file types -@cindex Windows file types -@cindex file types on MS-DOS and Windows -@cindex text files and binary files -@cindex binary files and text files - - On MS-DOS and Microsoft Windows, Emacs guesses the appropriate -end-of-line conversion for a file by looking at the file's name. This -feature classifies files as @dfn{text files} and @dfn{binary files}. By -``binary file'' we mean a file of literal byte values that are not -necessarily meant to be characters; Emacs does no end-of-line conversion -and no character code conversion for them. On the other hand, the bytes -in a text file are intended to represent characters; when you create a -new file whose name implies that it is a text file, Emacs uses DOS -end-of-line conversion. - -@defvar buffer-file-type -This variable, automatically buffer-local in each buffer, records the -file type of the buffer's visited file. When a buffer does not specify -a coding system with @code{buffer-file-coding-system}, this variable is -used to determine which coding system to use when writing the contents -of the buffer. It should be @code{nil} for text, @code{t} for binary. -If it is @code{t}, the coding system is @code{no-conversion}. -Otherwise, @code{undecided-dos} is used. - -Normally this variable is set by visiting a file; it is set to -@code{nil} if the file was visited without any actual conversion. - -Its default value is used to decide how to handle files for which -@code{file-name-buffer-file-type-alist} says nothing about the type: -If the default value is non-@code{nil}, then these files are treated as -binary: the coding system @code{no-conversion} is used. Otherwise, -nothing special is done for them---the coding system is deduced solely -from the file contents, in the usual Emacs fashion. -@end defvar - -@defopt file-name-buffer-file-type-alist -This variable holds an alist for recognizing text and binary files. -Each element has the form (@var{regexp} . @var{type}), where -@var{regexp} is matched against the file name, and @var{type} may be -@code{nil} for text, @code{t} for binary, or a function to call to -compute which. If it is a function, then it is called with a single -argument (the file name) and should return @code{t} or @code{nil}. - -When running on MS-DOS or MS-Windows, Emacs checks this alist to decide -which coding system to use when reading a file. For a text file, -@code{undecided-dos} is used. For a binary file, @code{no-conversion} -is used. - -If no element in this alist matches a given file name, then -the default value of @code{buffer-file-type} says how to treat the file. -@end defopt - -@node Input Methods -@section Input Methods -@cindex input methods - - @dfn{Input methods} provide convenient ways of entering non-@acronym{ASCII} -characters from the keyboard. Unlike coding systems, which translate -non-@acronym{ASCII} characters to and from encodings meant to be read by -programs, input methods provide human-friendly commands. (@xref{Input -Methods,,, emacs, The GNU Emacs Manual}, for information on how users -use input methods to enter text.) How to define input methods is not -yet documented in this manual, but here we describe how to use them. - - Each input method has a name, which is currently a string; -in the future, symbols may also be usable as input method names. - -@defvar current-input-method -This variable holds the name of the input method now active in the -current buffer. (It automatically becomes local in each buffer when set -in any fashion.) It is @code{nil} if no input method is active in the -buffer now. -@end defvar - -@defopt default-input-method -This variable holds the default input method for commands that choose an -input method. Unlike @code{current-input-method}, this variable is -normally global. -@end defopt - -@deffn Command set-input-method input-method -This command activates input method @var{input-method} for the current -buffer. It also sets @code{default-input-method} to @var{input-method}. -If @var{input-method} is @code{nil}, this command deactivates any input -method for the current buffer. -@end deffn - -@defun read-input-method-name prompt &optional default inhibit-null -This function reads an input method name with the minibuffer, prompting -with @var{prompt}. If @var{default} is non-@code{nil}, that is returned -by default, if the user enters empty input. However, if -@var{inhibit-null} is non-@code{nil}, empty input signals an error. - -The returned value is a string. -@end defun - -@defvar input-method-alist -This variable defines all the supported input methods. -Each element defines one input method, and should have the form: - -@example -(@var{input-method} @var{language-env} @var{activate-func} - @var{title} @var{description} @var{args}...) -@end example - -Here @var{input-method} is the input method name, a string; -@var{language-env} is another string, the name of the language -environment this input method is recommended for. (That serves only for -documentation purposes.) - -@var{activate-func} is a function to call to activate this method. The -@var{args}, if any, are passed as arguments to @var{activate-func}. All -told, the arguments to @var{activate-func} are @var{input-method} and -the @var{args}. - -@var{title} is a string to display in the mode line while this method is -active. @var{description} is a string describing this method and what -it is good for. -@end defvar - - The fundamental interface to input methods is through the -variable @code{input-method-function}. @xref{Reading One Event}, -and @ref{Invoking the Input Method}. - -@node Locales -@section Locales -@cindex locale - - POSIX defines a concept of ``locales'' which control which language -to use in language-related features. These Emacs variables control -how Emacs interacts with these features. - -@defvar locale-coding-system -@cindex keyboard input decoding on X -This variable specifies the coding system to use for decoding system -error messages and---on X Window system only---keyboard input, for -encoding the format argument to @code{format-time-string}, and for -decoding the return value of @code{format-time-string}. -@end defvar - -@defvar system-messages-locale -This variable specifies the locale to use for generating system error -messages. Changing the locale can cause messages to come out in a -different language or in a different orthography. If the variable is -@code{nil}, the locale is specified by environment variables in the -usual POSIX fashion. -@end defvar - -@defvar system-time-locale -This variable specifies the locale to use for formatting time values. -Changing the locale can cause messages to appear according to the -conventions of a different language. If the variable is @code{nil}, the -locale is specified by environment variables in the usual POSIX fashion. -@end defvar - -@defun locale-info item -This function returns locale data @var{item} for the current POSIX -locale, if available. @var{item} should be one of these symbols: - -@table @code -@item codeset -Return the character set as a string (locale item @code{CODESET}). - -@item days -Return a 7-element vector of day names (locale items -@code{DAY_1} through @code{DAY_7}); - -@item months -Return a 12-element vector of month names (locale items @code{MON_1} -through @code{MON_12}). - -@item paper -Return a list @code{(@var{width} @var{height})} for the default paper -size measured in millimeters (locale items @code{PAPER_WIDTH} and -@code{PAPER_HEIGHT}). -@end table - -If the system can't provide the requested information, or if -@var{item} is not one of those symbols, the value is @code{nil}. All -strings in the return value are decoded using -@code{locale-coding-system}. @xref{Locales,,, libc, The GNU Libc Manual}, -for more information about locales and locale items. -@end defun diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi deleted file mode 100644 index 7019fdde172..00000000000 --- a/doc/lispref/numbers.texi +++ /dev/null @@ -1,1230 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/numbers -@node Numbers, Strings and Characters, Lisp Data Types, Top -@chapter Numbers -@cindex integers -@cindex numbers - - GNU Emacs supports two numeric data types: @dfn{integers} and -@dfn{floating point numbers}. Integers are whole numbers such as -@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point -numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or -2.71828. They can also be expressed in exponential notation: 1.5e2 -equals 150; in this example, @samp{e2} stands for ten to the second -power, and that is multiplied by 1.5. Floating point values are not -exact; they have a fixed, limited amount of precision. - -@menu -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating point numbers. -* Bitwise Operations:: Logical and, or, not, shifting. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. -@end menu - -@node Integer Basics -@comment node-name, next, previous, up -@section Integer Basics - - The range of values for an integer depends on the machine. The -minimum range is @minus{}536870912 to 536870911 (30 bits; i.e., -@ifnottex --2**29 -@end ifnottex -@tex -@math{-2^{29}} -@end tex -to -@ifnottex -2**29 - 1), -@end ifnottex -@tex -@math{2^{29}-1}), -@end tex -but some machines provide a wider range. Many examples in this -chapter assume that an integer has 30 bits and that floating point -numbers are IEEE double precision. -@cindex overflow - - The Lisp reader reads an integer as a sequence of digits with optional -initial sign and optional final period. An integer that is out of the -Emacs range is treated as a floating-point number. - -@example - 1 ; @r{The integer 1.} - 1. ; @r{The integer 1.} -+1 ; @r{Also the integer 1.} --1 ; @r{The integer @minus{}1.} - 1073741825 ; @r{The floating point number 1073741825.0.} - 0 ; @r{The integer 0.} --0 ; @r{The integer 0.} -@end example - -@cindex integers in specific radix -@cindex radix for reading an integer -@cindex base for reading an integer -@cindex hex numbers -@cindex octal numbers -@cindex reading numbers in hex, octal, and binary - The syntax for integers in bases other than 10 uses @samp{#} -followed by a letter that specifies the radix: @samp{b} for binary, -@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to -specify radix @var{radix}. Case is not significant for the letter -that specifies the radix. Thus, @samp{#b@var{integer}} reads -@var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads -@var{integer} in radix @var{radix}. Allowed values of @var{radix} run -from 2 to 36. For example: - -@example -#b101100 @result{} 44 -#o54 @result{} 44 -#x2c @result{} 44 -#24r1k @result{} 44 -@end example - - To understand how various functions work on integers, especially the -bitwise operators (@pxref{Bitwise Operations}), it is often helpful to -view the numbers in their binary form. - - In 30-bit binary, the decimal integer 5 looks like this: - -@example -0000...000101 (30 bits total) -@end example - -@noindent -(The @samp{...} stands for enough bits to fill out a 30-bit word; in -this case, @samp{...} stands for twenty 0 bits. Later examples also -use the @samp{...} notation to make binary integers easier to read.) - - The integer @minus{}1 looks like this: - -@example -1111...111111 (30 bits total) -@end example - -@noindent -@cindex two's complement -@minus{}1 is represented as 30 ones. (This is called @dfn{two's -complement} notation.) - - The negative integer, @minus{}5, is creating by subtracting 4 from -@minus{}1. In binary, the decimal integer 4 is 100. Consequently, -@minus{}5 looks like this: - -@example -1111...111011 (30 bits total) -@end example - - In this implementation, the largest 30-bit binary integer value is -536,870,911 in decimal. In binary, it looks like this: - -@example -0111...111111 (30 bits total) -@end example - - Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 536,870,911, the value is the -negative integer @minus{}536,870,912: - -@example -(+ 1 536870911) - @result{} -536870912 - @result{} 1000...000000 (30 bits total) -@end example - - Many of the functions described in this chapter accept markers for -arguments in place of numbers. (@xref{Markers}.) Since the actual -arguments to such functions may be either numbers or markers, we often -give these arguments the name @var{number-or-marker}. When the argument -value is a marker, its position value is used and its buffer is ignored. - -@cindex largest Lisp integer number -@cindex maximum Lisp integer number -@defvar most-positive-fixnum -The value of this variable is the largest integer that Emacs Lisp -can handle. -@end defvar - -@cindex smallest Lisp integer number -@cindex minimum Lisp integer number -@defvar most-negative-fixnum -The value of this variable is the smallest integer that Emacs Lisp can -handle. It is negative. -@end defvar - - @xref{Character Codes, max-char}, for the maximum value of a valid -character codepoint. - -@node Float Basics -@section Floating Point Basics - -@cindex @acronym{IEEE} floating point - Floating point numbers are useful for representing numbers that are -not integral. The precise range of floating point numbers is -machine-specific; it is the same as the range of the C data type -@code{double} on the machine you are using. Emacs uses the -@acronym{IEEE} floating point standard where possible (the standard is -supported by most modern computers). - - The read syntax for floating point numbers requires either a decimal -point (with at least one digit following), an exponent, or both. For -example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and -@samp{.15e4} are five ways of writing a floating point number whose -value is 1500. They are all equivalent. You can also use a minus -sign to write negative floating point numbers, as in @samp{-1.0}. - - Emacs Lisp treats @code{-0.0} as equal to ordinary zero (with -respect to @code{equal} and @code{=}), even though the two are -distinguishable in the @acronym{IEEE} floating point standard. - -@cindex positive infinity -@cindex negative infinity -@cindex infinity -@cindex NaN - The @acronym{IEEE} floating point standard supports positive -infinity and negative infinity as floating point values. It also -provides for a class of values called NaN or ``not-a-number''; -numerical functions return such values in cases where there is no -correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN. (NaN -values can also carry a sign, but for practical purposes there's no -significant difference between different NaN values in Emacs Lisp.) -Here are the read syntaxes for these special floating point values: - -@table @asis -@item positive infinity -@samp{1.0e+INF} -@item negative infinity -@samp{-1.0e+INF} -@item Not-a-number -@samp{0.0e+NaN} or @samp{-0.0e+NaN}. -@end table - -@defun isnan number -This predicate tests whether its argument is NaN, and returns @code{t} -if so, @code{nil} otherwise. The argument must be a number. -@end defun - - The following functions are specialized for handling floating point -numbers: - -@defun frexp x -This function returns a cons cell @code{(@var{sig} . @var{exp})}, -where @var{sig} and @var{exp} are respectively the significand and -exponent of the floating point number @var{x}: - -@smallexample -@var{x} = @var{sig} * 2^@var{exp} -@end smallexample - -@var{sig} is a floating point number between 0.5 (inclusive) and 1.0 -(exclusive). If @var{x} is zero, the return value is @code{(0 . 0)}. -@end defun - -@defun ldexp sig &optional exp -This function returns a floating point number corresponding to the -significand @var{sig} and exponent @var{exp}. -@end defun - -@defun copysign x1 x2 -This function copies the sign of @var{x2} to the value of @var{x1}, -and returns the result. @var{x1} and @var{x2} must be floating point -numbers. -@end defun - -@defun logb number -This function returns the binary exponent of @var{number}. More -precisely, the value is the logarithm of @var{number} base 2, rounded -down to an integer. - -@example -(logb 10) - @result{} 3 -(logb 10.0e20) - @result{} 69 -@end example -@end defun - -@node Predicates on Numbers -@section Type Predicates for Numbers -@cindex predicates for numbers - - The functions in this section test for numbers, or for a specific -type of number. The functions @code{integerp} and @code{floatp} can -take any type of Lisp object as argument (they would not be of much -use otherwise), but the @code{zerop} predicate requires a number as -its argument. See also @code{integer-or-marker-p} and -@code{number-or-marker-p}, in @ref{Predicates on Markers}. - -@defun floatp object -This predicate tests whether its argument is a floating point -number and returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun integerp object -This predicate tests whether its argument is an integer, and returns -@code{t} if so, @code{nil} otherwise. -@end defun - -@defun numberp object -This predicate tests whether its argument is a number (either integer or -floating point), and returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun natnump object -@cindex natural numbers -This predicate (whose name comes from the phrase ``natural number'') -tests to see whether its argument is a nonnegative integer, and -returns @code{t} if so, @code{nil} otherwise. 0 is considered -non-negative. - -@findex wholenump number -This is a synonym for @code{natnump}. -@end defun - -@defun zerop number -This predicate tests whether its argument is zero, and returns @code{t} -if so, @code{nil} otherwise. The argument must be a number. - -@code{(zerop x)} is equivalent to @code{(= x 0)}. -@end defun - -@node Comparison of Numbers -@section Comparison of Numbers -@cindex number comparison -@cindex comparing numbers - - To test numbers for numerical equality, you should normally use -@code{=}, not @code{eq}. There can be many distinct floating point -number objects with the same numeric value. If you use @code{eq} to -compare them, then you test whether two values are the same -@emph{object}. By contrast, @code{=} compares only the numeric values -of the objects. - - At present, each integer value has a unique Lisp object in Emacs Lisp. -Therefore, @code{eq} is equivalent to @code{=} where integers are -concerned. It is sometimes convenient to use @code{eq} for comparing an -unknown value with an integer, because @code{eq} does not report an -error if the unknown value is not a number---it accepts arguments of any -type. By contrast, @code{=} signals an error if the arguments are not -numbers or markers. However, it is a good idea to use @code{=} if you -can, even for comparing integers, just in case we change the -representation of integers in a future Emacs version. - - Sometimes it is useful to compare numbers with @code{equal}; it -treats two numbers as equal if they have the same data type (both -integers, or both floating point) and the same value. By contrast, -@code{=} can treat an integer and a floating point number as equal. -@xref{Equality Predicates}. - - There is another wrinkle: because floating point arithmetic is not -exact, it is often a bad idea to check for equality of two floating -point values. Usually it is better to test for approximate equality. -Here's a function to do this: - -@example -(defvar fuzz-factor 1.0e-6) -(defun approx-equal (x y) - (or (and (= x 0) (= y 0)) - (< (/ (abs (- x y)) - (max (abs x) (abs y))) - fuzz-factor))) -@end example - -@cindex CL note---integers vrs @code{eq} -@quotation -@b{Common Lisp note:} Comparing numbers in Common Lisp always requires -@code{=} because Common Lisp implements multi-word integers, and two -distinct integer objects can have the same numeric value. Emacs Lisp -can have just one integer object for any given value because it has a -limited range of integer values. -@end quotation - -@defun = number-or-marker1 number-or-marker2 -This function tests whether its arguments are numerically equal, and -returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun eql value1 value2 -This function acts like @code{eq} except when both arguments are -numbers. It compares numbers by type and numeric value, so that -@code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and -@code{(eql 1 1)} both return @code{t}. -@end defun - -@defun /= number-or-marker1 number-or-marker2 -This function tests whether its arguments are numerically equal, and -returns @code{t} if they are not, and @code{nil} if they are. -@end defun - -@defun < number-or-marker1 number-or-marker2 -This function tests whether its first argument is strictly less than -its second argument. It returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun <= number-or-marker1 number-or-marker2 -This function tests whether its first argument is less than or equal -to its second argument. It returns @code{t} if so, @code{nil} -otherwise. -@end defun - -@defun > number-or-marker1 number-or-marker2 -This function tests whether its first argument is strictly greater -than its second argument. It returns @code{t} if so, @code{nil} -otherwise. -@end defun - -@defun >= number-or-marker1 number-or-marker2 -This function tests whether its first argument is greater than or -equal to its second argument. It returns @code{t} if so, @code{nil} -otherwise. -@end defun - -@defun max number-or-marker &rest numbers-or-markers -This function returns the largest of its arguments. -If any of the arguments is floating-point, the value is returned -as floating point, even if it was given as an integer. - -@example -(max 20) - @result{} 20 -(max 1 2.5) - @result{} 2.5 -(max 1 3 2.5) - @result{} 3.0 -@end example -@end defun - -@defun min number-or-marker &rest numbers-or-markers -This function returns the smallest of its arguments. -If any of the arguments is floating-point, the value is returned -as floating point, even if it was given as an integer. - -@example -(min -4 1) - @result{} -4 -@end example -@end defun - -@defun abs number -This function returns the absolute value of @var{number}. -@end defun - -@node Numeric Conversions -@section Numeric Conversions -@cindex rounding in conversions -@cindex number conversions -@cindex converting numbers - -To convert an integer to floating point, use the function @code{float}. - -@defun float number -This returns @var{number} converted to floating point. -If @var{number} is already a floating point number, @code{float} returns -it unchanged. -@end defun - -There are four functions to convert floating point numbers to integers; -they differ in how they round. All accept an argument @var{number} -and an optional argument @var{divisor}. Both arguments may be -integers or floating point numbers. @var{divisor} may also be -@code{nil}. If @var{divisor} is @code{nil} or omitted, these -functions convert @var{number} to an integer, or return it unchanged -if it already is an integer. If @var{divisor} is non-@code{nil}, they -divide @var{number} by @var{divisor} and convert the result to an -integer. An @code{arith-error} results if @var{divisor} is 0. - -@defun truncate number &optional divisor -This returns @var{number}, converted to an integer by rounding towards -zero. - -@example -(truncate 1.2) - @result{} 1 -(truncate 1.7) - @result{} 1 -(truncate -1.2) - @result{} -1 -(truncate -1.7) - @result{} -1 -@end example -@end defun - -@defun floor number &optional divisor -This returns @var{number}, converted to an integer by rounding downward -(towards negative infinity). - -If @var{divisor} is specified, this uses the kind of division -operation that corresponds to @code{mod}, rounding downward. - -@example -(floor 1.2) - @result{} 1 -(floor 1.7) - @result{} 1 -(floor -1.2) - @result{} -2 -(floor -1.7) - @result{} -2 -(floor 5.99 3) - @result{} 1 -@end example -@end defun - -@defun ceiling number &optional divisor -This returns @var{number}, converted to an integer by rounding upward -(towards positive infinity). - -@example -(ceiling 1.2) - @result{} 2 -(ceiling 1.7) - @result{} 2 -(ceiling -1.2) - @result{} -1 -(ceiling -1.7) - @result{} -1 -@end example -@end defun - -@defun round number &optional divisor -This returns @var{number}, converted to an integer by rounding towards the -nearest integer. Rounding a value equidistant between two integers -may choose the integer closer to zero, or it may prefer an even integer, -depending on your machine. - -@example -(round 1.2) - @result{} 1 -(round 1.7) - @result{} 2 -(round -1.2) - @result{} -1 -(round -1.7) - @result{} -2 -@end example -@end defun - -@node Arithmetic Operations -@section Arithmetic Operations -@cindex arithmetic operations - - Emacs Lisp provides the traditional four arithmetic operations: -addition, subtraction, multiplication, and division. Remainder and modulus -functions supplement the division functions. The functions to -add or subtract 1 are provided because they are traditional in Lisp and -commonly used. - - All of these functions except @code{%} return a floating point value -if any argument is floating. - - It is important to note that in Emacs Lisp, arithmetic functions -do not check for overflow. Thus @code{(1+ 536870911)} may evaluate to -@minus{}536870912, depending on your hardware. - -@defun 1+ number-or-marker -This function returns @var{number-or-marker} plus 1. -For example, - -@example -(setq foo 4) - @result{} 4 -(1+ foo) - @result{} 5 -@end example - -This function is not analogous to the C operator @code{++}---it does not -increment a variable. It just computes a sum. Thus, if we continue, - -@example -foo - @result{} 4 -@end example - -If you want to increment the variable, you must use @code{setq}, -like this: - -@example -(setq foo (1+ foo)) - @result{} 5 -@end example -@end defun - -@defun 1- number-or-marker -This function returns @var{number-or-marker} minus 1. -@end defun - -@defun + &rest numbers-or-markers -This function adds its arguments together. When given no arguments, -@code{+} returns 0. - -@example -(+) - @result{} 0 -(+ 1) - @result{} 1 -(+ 1 2 3 4) - @result{} 10 -@end example -@end defun - -@defun - &optional number-or-marker &rest more-numbers-or-markers -The @code{-} function serves two purposes: negation and subtraction. -When @code{-} has a single argument, the value is the negative of the -argument. When there are multiple arguments, @code{-} subtracts each of -the @var{more-numbers-or-markers} from @var{number-or-marker}, -cumulatively. If there are no arguments, the result is 0. - -@example -(- 10 1 2 3 4) - @result{} 0 -(- 10) - @result{} -10 -(-) - @result{} 0 -@end example -@end defun - -@defun * &rest numbers-or-markers -This function multiplies its arguments together, and returns the -product. When given no arguments, @code{*} returns 1. - -@example -(*) - @result{} 1 -(* 1) - @result{} 1 -(* 1 2 3 4) - @result{} 24 -@end example -@end defun - -@defun / dividend divisor &rest divisors -This function divides @var{dividend} by @var{divisor} and returns the -quotient. If there are additional arguments @var{divisors}, then it -divides @var{dividend} by each divisor in turn. Each argument may be a -number or a marker. - -If all the arguments are integers, then the result is an integer too. -This means the result has to be rounded. On most machines, the result -is rounded towards zero after each division, but some machines may round -differently with negative arguments. This is because the Lisp function -@code{/} is implemented using the C division operator, which also -permits machine-dependent rounding. As a practical matter, all known -machines round in the standard fashion. - -@cindex @code{arith-error} in division -If you divide an integer by 0, an @code{arith-error} error is signaled. -(@xref{Errors}.) Floating point division by zero returns either -infinity or a NaN if your machine supports @acronym{IEEE} floating point; -otherwise, it signals an @code{arith-error} error. - -@example -@group -(/ 6 2) - @result{} 3 -@end group -(/ 5 2) - @result{} 2 -(/ 5.0 2) - @result{} 2.5 -(/ 5 2.0) - @result{} 2.5 -(/ 5.0 2.0) - @result{} 2.5 -(/ 25 3 2) - @result{} 4 -@group -(/ -17 6) - @result{} -2 @r{(could in theory be @minus{}3 on some machines)} -@end group -@end example -@end defun - -@defun % dividend divisor -@cindex remainder -This function returns the integer remainder after division of @var{dividend} -by @var{divisor}. The arguments must be integers or markers. - -For negative arguments, the remainder is in principle machine-dependent -since the quotient is; but in practice, all known machines behave alike. - -An @code{arith-error} results if @var{divisor} is 0. - -@example -(% 9 4) - @result{} 1 -(% -9 4) - @result{} -1 -(% 9 -4) - @result{} 1 -(% -9 -4) - @result{} -1 -@end example - -For any two integers @var{dividend} and @var{divisor}, - -@example -@group -(+ (% @var{dividend} @var{divisor}) - (* (/ @var{dividend} @var{divisor}) @var{divisor})) -@end group -@end example - -@noindent -always equals @var{dividend}. -@end defun - -@defun mod dividend divisor -@cindex modulus -This function returns the value of @var{dividend} modulo @var{divisor}; -in other words, the remainder after division of @var{dividend} -by @var{divisor}, but with the same sign as @var{divisor}. -The arguments must be numbers or markers. - -Unlike @code{%}, @code{mod} returns a well-defined result for negative -arguments. It also permits floating point arguments; it rounds the -quotient downward (towards minus infinity) to an integer, and uses that -quotient to compute the remainder. - -An @code{arith-error} results if @var{divisor} is 0. - -@example -@group -(mod 9 4) - @result{} 1 -@end group -@group -(mod -9 4) - @result{} 3 -@end group -@group -(mod 9 -4) - @result{} -3 -@end group -@group -(mod -9 -4) - @result{} -1 -@end group -@group -(mod 5.5 2.5) - @result{} .5 -@end group -@end example - -For any two numbers @var{dividend} and @var{divisor}, - -@example -@group -(+ (mod @var{dividend} @var{divisor}) - (* (floor @var{dividend} @var{divisor}) @var{divisor})) -@end group -@end example - -@noindent -always equals @var{dividend}, subject to rounding error if either -argument is floating point. For @code{floor}, see @ref{Numeric -Conversions}. -@end defun - -@node Rounding Operations -@section Rounding Operations -@cindex rounding without conversion - -The functions @code{ffloor}, @code{fceiling}, @code{fround}, and -@code{ftruncate} take a floating point argument and return a floating -point result whose value is a nearby integer. @code{ffloor} returns the -nearest integer below; @code{fceiling}, the nearest integer above; -@code{ftruncate}, the nearest integer in the direction towards zero; -@code{fround}, the nearest integer. - -@defun ffloor float -This function rounds @var{float} to the next lower integral value, and -returns that value as a floating point number. -@end defun - -@defun fceiling float -This function rounds @var{float} to the next higher integral value, and -returns that value as a floating point number. -@end defun - -@defun ftruncate float -This function rounds @var{float} towards zero to an integral value, and -returns that value as a floating point number. -@end defun - -@defun fround float -This function rounds @var{float} to the nearest integral value, -and returns that value as a floating point number. -@end defun - -@node Bitwise Operations -@section Bitwise Operations on Integers -@cindex bitwise arithmetic -@cindex logical arithmetic - - In a computer, an integer is represented as a binary number, a -sequence of @dfn{bits} (digits which are either zero or one). A bitwise -operation acts on the individual bits of such a sequence. For example, -@dfn{shifting} moves the whole sequence left or right one or more places, -reproducing the same pattern ``moved over''. - - The bitwise operations in Emacs Lisp apply only to integers. - -@defun lsh integer1 count -@cindex logical shift -@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the -bits in @var{integer1} to the left @var{count} places, or to the right -if @var{count} is negative, bringing zeros into the vacated bits. If -@var{count} is negative, @code{lsh} shifts zeros into the leftmost -(most-significant) bit, producing a positive result even if -@var{integer1} is negative. Contrast this with @code{ash}, below. - -Here are two examples of @code{lsh}, shifting a pattern of bits one -place to the left. We show only the low-order eight bits of the binary -pattern; the rest are all zero. - -@example -@group -(lsh 5 1) - @result{} 10 -;; @r{Decimal 5 becomes decimal 10.} -00000101 @result{} 00001010 - -(lsh 7 1) - @result{} 14 -;; @r{Decimal 7 becomes decimal 14.} -00000111 @result{} 00001110 -@end group -@end example - -@noindent -As the examples illustrate, shifting the pattern of bits one place to -the left produces a number that is twice the value of the previous -number. - -Shifting a pattern of bits two places to the left produces results -like this (with 8-bit binary numbers): - -@example -@group -(lsh 3 2) - @result{} 12 -;; @r{Decimal 3 becomes decimal 12.} -00000011 @result{} 00001100 -@end group -@end example - -On the other hand, shifting one place to the right looks like this: - -@example -@group -(lsh 6 -1) - @result{} 3 -;; @r{Decimal 6 becomes decimal 3.} -00000110 @result{} 00000011 -@end group - -@group -(lsh 5 -1) - @result{} 2 -;; @r{Decimal 5 becomes decimal 2.} -00000101 @result{} 00000010 -@end group -@end example - -@noindent -As the example illustrates, shifting one place to the right divides the -value of a positive integer by two, rounding downward. - -The function @code{lsh}, like all Emacs Lisp arithmetic functions, does -not check for overflow, so shifting left can discard significant bits -and change the sign of the number. For example, left shifting -536,870,911 produces @minus{}2 in the 30-bit implementation: - -@example -(lsh 536870911 1) ; @r{left shift} - @result{} -2 -@end example - -In binary, the argument looks like this: - -@example -@group -;; @r{Decimal 536,870,911} -0111...111111 (30 bits total) -@end group -@end example - -@noindent -which becomes the following when left shifted: - -@example -@group -;; @r{Decimal @minus{}2} -1111...111110 (30 bits total) -@end group -@end example -@end defun - -@defun ash integer1 count -@cindex arithmetic shift -@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} -to the left @var{count} places, or to the right if @var{count} -is negative. - -@code{ash} gives the same results as @code{lsh} except when -@var{integer1} and @var{count} are both negative. In that case, -@code{ash} puts ones in the empty bit positions on the left, while -@code{lsh} puts zeros in those bit positions. - -Thus, with @code{ash}, shifting the pattern of bits one place to the right -looks like this: - -@example -@group -(ash -6 -1) @result{} -3 -;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} -1111...111010 (30 bits total) - @result{} -1111...111101 (30 bits total) -@end group -@end example - -In contrast, shifting the pattern of bits one place to the right with -@code{lsh} looks like this: - -@example -@group -(lsh -6 -1) @result{} 536870909 -;; @r{Decimal @minus{}6 becomes decimal 536,870,909.} -1111...111010 (30 bits total) - @result{} -0111...111101 (30 bits total) -@end group -@end example - -Here are other examples: - -@c !!! Check if lined up in smallbook format! XDVI shows problem -@c with smallbook but not with regular book! --rjc 16mar92 -@smallexample -@group - ; @r{ 30-bit binary values} - -(lsh 5 2) ; 5 = @r{0000...000101} - @result{} 20 ; = @r{0000...010100} -@end group -@group -(ash 5 2) - @result{} 20 -(lsh -5 2) ; -5 = @r{1111...111011} - @result{} -20 ; = @r{1111...101100} -(ash -5 2) - @result{} -20 -@end group -@group -(lsh 5 -2) ; 5 = @r{0000...000101} - @result{} 1 ; = @r{0000...000001} -@end group -@group -(ash 5 -2) - @result{} 1 -@end group -@group -(lsh -5 -2) ; -5 = @r{1111...111011} - @result{} 268435454 - ; = @r{0011...111110} -@end group -@group -(ash -5 -2) ; -5 = @r{1111...111011} - @result{} -2 ; = @r{1111...111110} -@end group -@end smallexample -@end defun - -@defun logand &rest ints-or-markers -This function returns the ``logical and'' of the arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in all the arguments. (``Set'' means that the value of the bit is 1 -rather than 0.) - -For example, using 4-bit binary numbers, the ``logical and'' of 13 and -12 is 12: 1101 combined with 1100 produces 1100. -In both the binary numbers, the leftmost two bits are set (i.e., they -are 1's), so the leftmost two bits of the returned value are set. -However, for the rightmost two bits, each is zero in at least one of -the arguments, so the rightmost two bits of the returned value are 0's. - -@noindent -Therefore, - -@example -@group -(logand 13 12) - @result{} 12 -@end group -@end example - -If @code{logand} is not passed any argument, it returns a value of -@minus{}1. This number is an identity element for @code{logand} -because its binary representation consists entirely of ones. If -@code{logand} is passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 30-bit binary values} - -(logand 14 13) ; 14 = @r{0000...001110} - ; 13 = @r{0000...001101} - @result{} 12 ; 12 = @r{0000...001100} -@end group - -@group -(logand 14 13 4) ; 14 = @r{0000...001110} - ; 13 = @r{0000...001101} - ; 4 = @r{0000...000100} - @result{} 4 ; 4 = @r{0000...000100} -@end group - -@group -(logand) - @result{} -1 ; -1 = @r{1111...111111} -@end group -@end smallexample -@end defun - -@defun logior &rest ints-or-markers -This function returns the ``inclusive or'' of its arguments: the @var{n}th bit -is set in the result if, and only if, the @var{n}th bit is set in at least -one of the arguments. If there are no arguments, the result is zero, -which is an identity element for this operation. If @code{logior} is -passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 30-bit binary values} - -(logior 12 5) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - @result{} 13 ; 13 = @r{0000...001101} -@end group - -@group -(logior 12 5 7) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - ; 7 = @r{0000...000111} - @result{} 15 ; 15 = @r{0000...001111} -@end group -@end smallexample -@end defun - -@defun logxor &rest ints-or-markers -This function returns the ``exclusive or'' of its arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in an odd number of the arguments. If there are no arguments, the -result is 0, which is an identity element for this operation. If -@code{logxor} is passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 30-bit binary values} - -(logxor 12 5) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - @result{} 9 ; 9 = @r{0000...001001} -@end group - -@group -(logxor 12 5 7) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - ; 7 = @r{0000...000111} - @result{} 14 ; 14 = @r{0000...001110} -@end group -@end smallexample -@end defun - -@defun lognot integer -This function returns the logical complement of its argument: the @var{n}th -bit is one in the result if, and only if, the @var{n}th bit is zero in -@var{integer}, and vice-versa. - -@example -(lognot 5) - @result{} -6 -;; 5 = @r{0000...000101} (30 bits total) -;; @r{becomes} -;; -6 = @r{1111...111010} (30 bits total) -@end example -@end defun - -@node Math Functions -@section Standard Mathematical Functions -@cindex transcendental functions -@cindex mathematical functions -@cindex floating-point functions - - These mathematical functions allow integers as well as floating point -numbers as arguments. - -@defun sin arg -@defunx cos arg -@defunx tan arg -These are the ordinary trigonometric functions, with argument measured -in radians. -@end defun - -@defun asin arg -The value of @code{(asin @var{arg})} is a number between -@ifnottex -@minus{}pi/2 -@end ifnottex -@tex -@math{-\pi/2} -@end tex -and -@ifnottex -pi/2 -@end ifnottex -@tex -@math{\pi/2} -@end tex -(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of -range (outside [@minus{}1, 1]), it signals a @code{domain-error} error. -@end defun - -@defun acos arg -The value of @code{(acos @var{arg})} is a number between 0 and -@ifnottex -pi -@end ifnottex -@tex -@math{\pi} -@end tex -(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out -of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error. -@end defun - -@defun atan y &optional x -The value of @code{(atan @var{y})} is a number between -@ifnottex -@minus{}pi/2 -@end ifnottex -@tex -@math{-\pi/2} -@end tex -and -@ifnottex -pi/2 -@end ifnottex -@tex -@math{\pi/2} -@end tex -(exclusive) whose tangent is @var{y}. If the optional second -argument @var{x} is given, the value of @code{(atan y x)} is the -angle in radians between the vector @code{[@var{x}, @var{y}]} and the -@code{X} axis. -@end defun - -@defun exp arg -This is the exponential function; it returns @math{e} to the power -@var{arg}. -@end defun - -@defun log arg &optional base -This function returns the logarithm of @var{arg}, with base -@var{base}. If you don't specify @var{base}, the natural base -@math{e} is used. If @var{arg} is negative, it signals a -@code{domain-error} error. -@end defun - -@ignore -@defun expm1 arg -This function returns @code{(1- (exp @var{arg}))}, but it is more -accurate than that when @var{arg} is negative and @code{(exp @var{arg})} -is close to 1. -@end defun - -@defun log1p arg -This function returns @code{(log (1+ @var{arg}))}, but it is more -accurate than that when @var{arg} is so small that adding 1 to it would -lose accuracy. -@end defun -@end ignore - -@defun log10 arg -This function returns the logarithm of @var{arg}, with base 10. If -@var{arg} is negative, it signals a @code{domain-error} error. -@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least -approximately. -@end defun - -@defun expt x y -This function returns @var{x} raised to power @var{y}. If both -arguments are integers and @var{y} is positive, the result is an -integer; in this case, overflow causes truncation, so watch out. -@end defun - -@defun sqrt arg -This returns the square root of @var{arg}. If @var{arg} is negative, -it signals a @code{domain-error} error. -@end defun - -In addition, Emacs defines the following common mathematical -constants: - -@defvar float-e -The mathematical constant @math{e} (2.71828@dots{}). -@end defvar - -@defvar float-pi -The mathematical constant @math{pi} (3.14159@dots{}). -@end defvar - -@node Random Numbers -@section Random Numbers -@cindex random numbers - -A deterministic computer program cannot generate true random numbers. -For most purposes, @dfn{pseudo-random numbers} suffice. A series of -pseudo-random numbers is generated in a deterministic fashion. The -numbers are not truly random, but they have certain properties that -mimic a random series. For example, all possible values occur equally -often in a pseudo-random series. - -In Emacs, pseudo-random numbers are generated from a ``seed'' number. -Starting from any given seed, the @code{random} function always -generates the same sequence of numbers. Emacs always starts with the -same seed value, so the sequence of values of @code{random} is actually -the same in each Emacs run! For example, in one operating system, the -first call to @code{(random)} after you start Emacs always returns -@minus{}1457731, and the second one always returns @minus{}7692030. This -repeatability is helpful for debugging. - -If you want random numbers that don't always come out the same, execute -@code{(random t)}. This chooses a new seed based on the current time of -day and on Emacs's process @acronym{ID} number. - -@defun random &optional limit -This function returns a pseudo-random integer. Repeated calls return a -series of pseudo-random integers. - -If @var{limit} is a positive integer, the value is chosen to be -nonnegative and less than @var{limit}. - -If @var{limit} is @code{t}, it means to choose a new seed based on the -current time of day and on Emacs's process @acronym{ID} number. - -On some machines, any integer representable in Lisp may be the result -of @code{random}. On other machines, the result can never be larger -than a certain maximum or less than a certain (negative) minimum. -@end defun diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi deleted file mode 100644 index 64cd4a12392..00000000000 --- a/doc/lispref/objects.texi +++ /dev/null @@ -1,2115 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/objects -@node Lisp Data Types, Numbers, Introduction, Top -@chapter Lisp Data Types -@cindex object -@cindex Lisp object -@cindex type -@cindex data type - - A Lisp @dfn{object} is a piece of data used and manipulated by Lisp -programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of -possible objects. - - Every object belongs to at least one type. Objects of the same type -have similar structures and may usually be used in the same contexts. -Types can overlap, and objects can belong to two or more types. -Consequently, we can ask whether an object belongs to a particular type, -but not for ``the'' type of an object. - -@cindex primitive type - A few fundamental object types are built into Emacs. These, from -which all other types are constructed, are called @dfn{primitive types}. -Each object belongs to one and only one primitive type. These types -include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol}, -@dfn{string}, @dfn{vector}, @dfn{hash-table}, @dfn{subr}, and -@dfn{byte-code function}, plus several special types, such as -@dfn{buffer}, that are related to editing. (@xref{Editing Types}.) - - Each primitive type has a corresponding Lisp function that checks -whether an object is a member of that type. - - Lisp is unlike many other languages in that its objects are -@dfn{self-typing}: the primitive type of each object is implicit in -the object itself. For example, if an object is a vector, nothing can -treat it as a number; Lisp knows it is a vector, not a number. - - In most languages, the programmer must declare the data type of each -variable, and the type is known by the compiler but not represented in -the data. Such type declarations do not exist in Emacs Lisp. A Lisp -variable can have any type of value, and it remembers whatever value -you store in it, type and all. (Actually, a small number of Emacs -Lisp variables can only take on values of a certain type. -@xref{Variables with Restricted Values}.) - - This chapter describes the purpose, printed representation, and read -syntax of each of the standard types in GNU Emacs Lisp. Details on how -to use these types can be found in later chapters. - -@menu -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Circular Objects:: Read syntax for circular structure. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. -@end menu - -@node Printed Representation -@comment node-name, next, previous, up -@section Printed Representation and Read Syntax -@cindex printed representation -@cindex read syntax - - The @dfn{printed representation} of an object is the format of the -output generated by the Lisp printer (the function @code{prin1}) for -that object. Every data type has a unique printed representation. -The @dfn{read syntax} of an object is the format of the input accepted -by the Lisp reader (the function @code{read}) for that object. This -is not necessarily unique; many kinds of object have more than one -syntax. @xref{Read and Print}. - -@cindex hash notation - In most cases, an object's printed representation is also a read -syntax for the object. However, some types have no read syntax, since -it does not make sense to enter objects of these types as constants in -a Lisp program. These objects are printed in @dfn{hash notation}, -which consists of the characters @samp{#<}, a descriptive string -(typically the type name followed by the name of the object), and a -closing @samp{>}. For example: - -@example -(current-buffer) - @result{} # -@end example - -@noindent -Hash notation cannot be read at all, so the Lisp reader signals the -error @code{invalid-read-syntax} whenever it encounters @samp{#<}. -@kindex invalid-read-syntax - - In other languages, an expression is text; it has no other form. In -Lisp, an expression is primarily a Lisp object and only secondarily the -text that is the object's read syntax. Often there is no need to -emphasize this distinction, but you must keep it in the back of your -mind, or you will occasionally be very confused. - - When you evaluate an expression interactively, the Lisp interpreter -first reads the textual representation of it, producing a Lisp object, -and then evaluates that object (@pxref{Evaluation}). However, -evaluation and reading are separate activities. Reading returns the -Lisp object represented by the text that is read; the object may or may -not be evaluated later. @xref{Input Functions}, for a description of -@code{read}, the basic function for reading objects. - -@node Comments -@comment node-name, next, previous, up -@section Comments -@cindex comments -@cindex @samp{;} in comment - - A @dfn{comment} is text that is written in a program only for the sake -of humans that read the program, and that has no effect on the meaning -of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it -is not within a string or character constant. The comment continues to -the end of line. The Lisp reader discards comments; they do not become -part of the Lisp objects which represent the program within the Lisp -system. - - The @samp{#@@@var{count}} construct, which skips the next @var{count} -characters, is useful for program-generated comments containing binary -data. The Emacs Lisp byte compiler uses this in its output files -(@pxref{Byte Compilation}). It isn't meant for source files, however. - - @xref{Comment Tips}, for conventions for formatting comments. - -@node Programming Types -@section Programming Types -@cindex programming types - - There are two general categories of types in Emacs Lisp: those having -to do with Lisp programming, and those having to do with editing. The -former exist in many Lisp implementations, in one form or another. The -latter are unique to Emacs Lisp. - -@menu -* Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Symbol Type:: A multi-use object that refers to a function, - variable, or property list, and has a unique identity. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Char-Table Type:: One-dimensional sparse arrays indexed by characters. -* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. -* Hash Table Type:: Super-fast lookup tables. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. -@end menu - -@node Integer Type -@subsection Integer Type - - The range of values for integers in Emacs Lisp is @minus{}536870912 to -536870911 (30 bits; i.e., -@ifnottex --2**29 -@end ifnottex -@tex -@math{-2^{29}} -@end tex -to -@ifnottex -2**29 - 1) -@end ifnottex -@tex -@math{2^{29}-1}) -@end tex -on typical 32-bit machines. (Some machines provide a wider range.) -Emacs Lisp arithmetic functions do not check for overflow. Thus -@code{(1+ 536870911)} is @minus{}536870912 if Emacs integers are 30 bits. - - The read syntax for integers is a sequence of (base ten) digits with an -optional sign at the beginning and an optional period at the end. The -printed representation produced by the Lisp interpreter never has a -leading @samp{+} or a final @samp{.}. - -@example -@group --1 ; @r{The integer -1.} -1 ; @r{The integer 1.} -1. ; @r{Also the integer 1.} -+1 ; @r{Also the integer 1.} -@end group -@end example - -@noindent -As a special exception, if a sequence of digits specifies an integer -too large or too small to be a valid integer object, the Lisp reader -reads it as a floating-point number (@pxref{Floating Point Type}). -For instance, if Emacs integers are 30 bits, @code{536870912} is read -as the floating-point number @code{536870912.0}. - - @xref{Numbers}, for more information. - -@node Floating Point Type -@subsection Floating Point Type - - Floating point numbers are the computer equivalent of scientific -notation; you can think of a floating point number as a fraction -together with a power of ten. The precise number of significant -figures and the range of possible exponents is machine-specific; Emacs -uses the C data type @code{double} to store the value, and internally -this records a power of 2 rather than a power of 10. - - The printed representation for floating point numbers requires either -a decimal point (with at least one digit following), an exponent, or -both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, -@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point -number whose value is 1500. They are all equivalent. - - @xref{Numbers}, for more information. - -@node Character Type -@subsection Character Type -@cindex @acronym{ASCII} character codes - - A @dfn{character} in Emacs Lisp is nothing more than an integer. In -other words, characters are represented by their character codes. For -example, the character @kbd{A} is represented as the @w{integer 65}. - - Individual characters are used occasionally in programs, but it is -more common to work with @emph{strings}, which are sequences composed -of characters. @xref{String Type}. - - Characters in strings and buffers are currently limited to the range -of 0 to 4194303---twenty two bits (@pxref{Character Codes}). Codes 0 -through 127 are @acronym{ASCII} codes; the rest are -non-@acronym{ASCII} (@pxref{Non-ASCII Characters}). Characters that -represent keyboard input have a much wider range, to encode modifier -keys such as Control, Meta and Shift. - - There are special functions for producing a human-readable textual -description of a character for the sake of messages. @xref{Describing -Characters}. - -@menu -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. -@end menu - -@node Basic Char Syntax -@subsubsection Basic Char Syntax -@cindex read syntax for characters -@cindex printed representation for characters -@cindex syntax for characters -@cindex @samp{?} in character constant -@cindex question mark in character constant - - Since characters are really integers, the printed representation of -a character is a decimal number. This is also a possible read syntax -for a character, but writing characters that way in Lisp programs is -not clear programming. You should @emph{always} use the special read -syntax formats that Emacs Lisp provides for characters. These syntax -formats start with a question mark. - - The usual read syntax for alphanumeric characters is a question mark -followed by the character; thus, @samp{?A} for the character -@kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the -character @kbd{a}. - - For example: - -@example -?Q @result{} 81 ?q @result{} 113 -@end example - - You can use the same syntax for punctuation characters, but it is -often a good idea to add a @samp{\} so that the Emacs commands for -editing Lisp code don't get confused. For example, @samp{?\(} is the -way to write the open-paren character. If the character is @samp{\}, -you @emph{must} use a second @samp{\} to quote it: @samp{?\\}. - -@cindex whitespace -@cindex bell character -@cindex @samp{\a} -@cindex backspace -@cindex @samp{\b} -@cindex tab (ASCII character) -@cindex @samp{\t} -@cindex vertical tab -@cindex @samp{\v} -@cindex formfeed -@cindex @samp{\f} -@cindex newline -@cindex @samp{\n} -@cindex return (ASCII character) -@cindex @samp{\r} -@cindex escape (ASCII character) -@cindex @samp{\e} -@cindex space (ASCII character) -@cindex @samp{\s} - You can express the characters control-g, backspace, tab, newline, -vertical tab, formfeed, space, return, del, and escape as @samp{?\a}, -@samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, -@samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively. -(@samp{?\s} followed by a dash has a different meaning---it applies -the ``super'' modifier to the following character.) Thus, - -@example -?\a @result{} 7 ; @r{control-g, @kbd{C-g}} -?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}} -?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}} -?\n @result{} 10 ; @r{newline, @kbd{C-j}} -?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}} -?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}} -?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}} -?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}} -?\s @result{} 32 ; @r{space character, @key{SPC}} -?\\ @result{} 92 ; @r{backslash character, @kbd{\}} -?\d @result{} 127 ; @r{delete character, @key{DEL}} -@end example - -@cindex escape sequence - These sequences which start with backslash are also known as -@dfn{escape sequences}, because backslash plays the role of an -``escape character''; this terminology has nothing to do with the -character @key{ESC}. @samp{\s} is meant for use in character -constants; in string constants, just write the space. - - A backslash is allowed, and harmless, preceding any character without -a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}. -There is no reason to add a backslash before most characters. However, -you should add a backslash before any of the characters -@samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing -Lisp code. You can also add a backslash before whitespace characters such as -space, tab, newline and formfeed. However, it is cleaner to use one of -the easily readable escape sequences, such as @samp{\t} or @samp{\s}, -instead of an actual whitespace character such as a tab or a space. -(If you do write backslash followed by a space, you should write -an extra space after the character constant to separate it from the -following text.) - -@node General Escape Syntax -@subsubsection General Escape Syntax - - In addition to the specific escape sequences for special important -control characters, Emacs provides several types of escape syntax that -you can use to specify non-@acronym{ASCII} text characters. - -@cindex unicode character escape - You can specify characters by their Unicode values. -@code{?\u@var{nnnn}} represents a character that maps to the Unicode -code point @samp{U+@var{nnnn}} (by convention, Unicode code points are -given in hexadecimal). There is a slightly different syntax for -specifying characters with code points higher than -@code{U+@var{ffff}}: @code{\U00@var{nnnnnn}} represents the character -whose code point is @samp{U+@var{nnnnnn}}. The Unicode Standard only -defines code points up to @samp{U+@var{10ffff}}, so if you specify a -code point higher than that, Emacs signals an error. - - This peculiar and inconvenient syntax was adopted for compatibility -with other programming languages. Unlike some other languages, Emacs -Lisp supports this syntax only in character literals and strings. - -@cindex @samp{\} in character constant -@cindex backslash in character constants -@cindex octal character code - The most general read syntax for a character represents the -character code in either octal or hex. To use octal, write a question -mark followed by a backslash and the octal character code (up to three -octal digits); thus, @samp{?\101} for the character @kbd{A}, -@samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the -character @kbd{C-b}. Although this syntax can represent any -@acronym{ASCII} character, it is preferred only when the precise octal -value is more important than the @acronym{ASCII} representation. - -@example -@group -?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10 -?\101 @result{} 65 ?A @result{} 65 -@end group -@end example - - To use hex, write a question mark followed by a backslash, @samp{x}, -and the hexadecimal character code. You can use any number of hex -digits, so you can represent any character code in this way. -Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the -character @kbd{C-a}, and @code{?\xe0} for the Latin-1 character -@iftex -@samp{@`a}. -@end iftex -@ifnottex -@samp{a} with grave accent. -@end ifnottex - -@node Ctl-Char Syntax -@subsubsection Control-Character Syntax - -@cindex control characters - Control characters can be represented using yet another read syntax. -This consists of a question mark followed by a backslash, caret, and the -corresponding non-control character, in either upper or lower case. For -example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the -character @kbd{C-i}, the character whose value is 9. - - Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is -equivalent to @samp{?\^I} and to @samp{?\^i}: - -@example -?\^I @result{} 9 ?\C-I @result{} 9 -@end example - - In strings and buffers, the only control characters allowed are those -that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn -any character into a control character with @samp{C-}. The character -codes for these non-@acronym{ASCII} control characters include the -@tex -@math{2^{26}} -@end tex -@ifnottex -2**26 -@end ifnottex -bit as well as the code for the corresponding non-control character. -Ordinary text terminals have no way of generating non-@acronym{ASCII} -control characters, but you can generate them straightforwardly using -X and other window systems. - - For historical reasons, Emacs treats the @key{DEL} character as -the control equivalent of @kbd{?}: - -@example -?\^? @result{} 127 ?\C-? @result{} 127 -@end example - -@noindent -As a result, it is currently not possible to represent the character -@kbd{Control-?}, which is a meaningful input character under X, using -@samp{\C-}. It is not easy to change this, as various Lisp files refer -to @key{DEL} in this way. - - For representing control characters to be found in files or strings, -we recommend the @samp{^} syntax; for control characters in keyboard -input, we prefer the @samp{C-} syntax. Which one you use does not -affect the meaning of the program, but may guide the understanding of -people who read it. - -@node Meta-Char Syntax -@subsubsection Meta-Character Syntax - -@cindex meta characters - A @dfn{meta character} is a character typed with the @key{META} -modifier key. The integer that represents such a character has the -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -bit set. We use high bits for this and other modifiers to make -possible a wide range of basic character codes. - - In a string, the -@tex -@math{2^{7}} -@end tex -@ifnottex -2**7 -@end ifnottex -bit attached to an @acronym{ASCII} character indicates a meta -character; thus, the meta characters that can fit in a string have -codes in the range from 128 to 255, and are the meta versions of the -ordinary @acronym{ASCII} characters. @xref{Strings of Events}, for -details about @key{META}-handling in strings. - - The read syntax for meta characters uses @samp{\M-}. For example, -@samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with -octal character codes (see below), with @samp{\C-}, or with any other -syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A}, -or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as -@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}. - -@node Other Char Bits -@subsubsection Other Character Modifier Bits - - The case of a graphic character is indicated by its character code; -for example, @acronym{ASCII} distinguishes between the characters @samp{a} -and @samp{A}. But @acronym{ASCII} has no way to represent whether a control -character is upper case or lower case. Emacs uses the -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit to indicate that the shift key was used in typing a control -character. This distinction is possible only when you use X terminals -or other special terminals; ordinary text terminals do not report the -distinction. The Lisp syntax for the shift bit is @samp{\S-}; thus, -@samp{?\C-\S-o} or @samp{?\C-\S-O} represents the shifted-control-o -character. - -@cindex hyper characters -@cindex super characters -@cindex alt characters - The X Window System defines three other -@anchor{modifier bits}modifier bits that can be set -in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes -for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is -significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents -@kbd{Alt-Hyper-Meta-x}. (Note that @samp{\s} with no following @samp{-} -represents the space character.) -@tex -Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}} -for super and @math{2^{24}} for hyper. -@end tex -@ifnottex -Numerically, the -bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper. -@end ifnottex - -@node Symbol Type -@subsection Symbol Type - - A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The -symbol name serves as the printed representation of the symbol. In -ordinary Lisp use, with one single obarray (@pxref{Creating Symbols}), -a symbol's name is unique---no two symbols have the same name. - - A symbol can serve as a variable, as a function name, or to hold a -property list. Or it may serve only to be distinct from all other Lisp -objects, so that its presence in a data structure may be recognized -reliably. In a given context, usually only one of these uses is -intended. But you can use one symbol in all of these ways, -independently. - - A symbol whose name starts with a colon (@samp{:}) is called a -@dfn{keyword symbol}. These symbols automatically act as constants, -and are normally used only by comparing an unknown symbol with a few -specific alternatives. @xref{Constant Variables}. - -@cindex @samp{\} in symbols -@cindex backslash in symbols - A symbol name can contain any characters whatever. Most symbol names -are written with letters, digits, and the punctuation characters -@samp{-+=*/}. Such names require no special punctuation; the characters -of the name suffice as long as the name does not look like a number. -(If it does, write a @samp{\} at the beginning of the name to force -interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}?} are -less often used but also require no special punctuation. Any other -characters may be included in a symbol's name by escaping them with a -backslash. In contrast to its use in strings, however, a backslash in -the name of a symbol simply quotes the single character that follows the -backslash. For example, in a string, @samp{\t} represents a tab -character; in the name of a symbol, however, @samp{\t} merely quotes the -letter @samp{t}. To have a symbol with a tab character in its name, you -must actually use a tab (preceded with a backslash). But it's rare to -do such a thing. - -@cindex CL note---case of letters -@quotation -@b{Common Lisp note:} In Common Lisp, lower case letters are always -``folded'' to upper case, unless they are explicitly escaped. In Emacs -Lisp, upper case and lower case letters are distinct. -@end quotation - - Here are several examples of symbol names. Note that the @samp{+} in -the fifth example is escaped to prevent it from being read as a number. -This is not necessary in the fourth example because the rest of the name -makes it invalid as a number. - -@example -@group -foo ; @r{A symbol named @samp{foo}.} -FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.} -@end group -@group -1+ ; @r{A symbol named @samp{1+}} - ; @r{(not @samp{+1}, which is an integer).} -@end group -@group -\+1 ; @r{A symbol named @samp{+1}} - ; @r{(not a very readable name).} -@end group -@group -\(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).} -@c the @'s in this next line use up three characters, hence the -@c apparent misalignment of the comment. -+-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.} - ; @r{These characters need not be escaped.} -@end group -@end example - -@cindex @samp{##} read syntax -@ifinfo -@c This uses ``colon'' instead of a literal `:' because Info cannot -@c cope with a `:' in a menu -@cindex @samp{#@var{colon}} read syntax -@end ifinfo -@ifnotinfo -@cindex @samp{#:} read syntax -@end ifnotinfo - As an exception to the rule that a symbol's name serves as its -printed representation, @samp{##} is the printed representation for an -interned symbol whose name is an empty string. Furthermore, -@samp{#:@var{foo}} is the printed representation for an uninterned -symbol whose name is @var{foo}. (Normally, the Lisp reader interns -all symbols; @pxref{Creating Symbols}.) - -@node Sequence Type -@subsection Sequence Types - - A @dfn{sequence} is a Lisp object that represents an ordered set of -elements. There are two kinds of sequence in Emacs Lisp: @dfn{lists} -and @dfn{arrays}. - - Lists are the most commonly-used sequences. A list can hold -elements of any type, and its length can be easily changed by adding -or removing elements. See the next subsection for more about lists. - - Arrays are fixed-length sequences. They are further subdivided into -strings, vectors, char-tables and bool-vectors. Vectors can hold -elements of any type, whereas string elements must be characters, and -bool-vector elements must be @code{t} or @code{nil}. Char-tables are -like vectors except that they are indexed by any valid character code. -The characters in a string can have text properties like characters in -a buffer (@pxref{Text Properties}), but vectors do not support text -properties, even when their elements happen to be characters. - - Lists, strings and the other array types also share important -similarities. For example, all have a length @var{l}, and all have -elements which can be indexed from zero to @var{l} minus one. Several -functions, called sequence functions, accept any kind of sequence. -For example, the function @code{length} reports the length of any kind -of sequence. @xref{Sequences Arrays Vectors}. - - It is generally impossible to read the same sequence twice, since -sequences are always created anew upon reading. If you read the read -syntax for a sequence twice, you get two sequences with equal contents. -There is one exception: the empty list @code{()} always stands for the -same object, @code{nil}. - -@node Cons Cell Type -@subsection Cons Cell and List Types -@cindex address field of register -@cindex decrement field of register -@cindex pointers - - A @dfn{cons cell} is an object that consists of two slots, called -the @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} any -Lisp object. We also say that ``the @sc{car} of this cons cell is'' -whatever object its @sc{car} slot currently holds, and likewise for -the @sc{cdr}. - -@cindex list structure - A @dfn{list} is a series of cons cells, linked together so that the -@sc{cdr} slot of each cons cell holds either the next cons cell or the -empty list. The empty list is actually the symbol @code{nil}. -@xref{Lists}, for details. Because most cons cells are used as part -of lists, we refer to any structure made out of cons cells as a -@dfn{list structure}. - -@cindex linked list -@quotation -A note to C programmers: a Lisp list thus works as a @dfn{linked list} -built up of cons cells. Because pointers in Lisp are implicit, we do -not distinguish between a cons cell slot ``holding'' a value versus -``pointing to'' the value. -@end quotation - -@cindex atoms - Because cons cells are so central to Lisp, we also have a word for -``an object which is not a cons cell''. These objects are called -@dfn{atoms}. - -@cindex parenthesis -@cindex @samp{(@dots{})} in lists - The read syntax and printed representation for lists are identical, and -consist of a left parenthesis, an arbitrary number of elements, and a -right parenthesis. Here are examples of lists: - -@example -(A 2 "A") ; @r{A list of three elements.} -() ; @r{A list of no elements (the empty list).} -nil ; @r{A list of no elements (the empty list).} -("A ()") ; @r{A list of one element: the string @code{"A ()"}.} -(A ()) ; @r{A list of two elements: @code{A} and the empty list.} -(A nil) ; @r{Equivalent to the previous.} -((A B C)) ; @r{A list of one element} - ; @r{(which is a list of three elements).} -@end example - - Upon reading, each object inside the parentheses becomes an element -of the list. That is, a cons cell is made for each element. The -@sc{car} slot of the cons cell holds the element, and its @sc{cdr} -slot refers to the next cons cell of the list, which holds the next -element in the list. The @sc{cdr} slot of the last cons cell is set to -hold @code{nil}. - - The names @sc{car} and @sc{cdr} derive from the history of Lisp. The -original Lisp implementation ran on an @w{IBM 704} computer which -divided words into two parts, called the ``address'' part and the -``decrement''; @sc{car} was an instruction to extract the contents of -the address part of a register, and @sc{cdr} an instruction to extract -the contents of the decrement. By contrast, ``cons cells'' are named -for the function @code{cons} that creates them, which in turn was named -for its purpose, the construction of cells. - -@menu -* Box Diagrams:: Drawing pictures of lists. -* Dotted Pair Notation:: A general syntax for cons cells. -* Association List Type:: A specially constructed list. -@end menu - -@node Box Diagrams -@subsubsection Drawing Lists as Box Diagrams -@cindex box diagrams, for lists -@cindex diagrams, boxed, for lists - - A list can be illustrated by a diagram in which the cons cells are -shown as pairs of boxes, like dominoes. (The Lisp reader cannot read -such an illustration; unlike the textual notation, which can be -understood by both humans and computers, the box illustrations can be -understood only by humans.) This picture represents the three-element -list @code{(rose violet buttercup)}: - -@example -@group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end example - - In this diagram, each box represents a slot that can hold or refer to -any Lisp object. Each pair of boxes represents a cons cell. Each arrow -represents a reference to a Lisp object, either an atom or another cons -cell. - - In this example, the first box, which holds the @sc{car} of the first -cons cell, refers to or ``holds'' @code{rose} (a symbol). The second -box, holding the @sc{cdr} of the first cons cell, refers to the next -pair of boxes, the second cons cell. The @sc{car} of the second cons -cell is @code{violet}, and its @sc{cdr} is the third cons cell. The -@sc{cdr} of the third (and last) cons cell is @code{nil}. - - Here is another diagram of the same list, @code{(rose violet -buttercup)}, sketched in a different manner: - -@smallexample -@group - --------------- ---------------- ------------------- -| car | cdr | | car | cdr | | car | cdr | -| rose | o-------->| violet | o-------->| buttercup | nil | -| | | | | | | | | - --------------- ---------------- ------------------- -@end group -@end smallexample - -@cindex @code{nil} as a list -@cindex empty list - A list with no elements in it is the @dfn{empty list}; it is identical -to the symbol @code{nil}. In other words, @code{nil} is both a symbol -and a list. - - Here is the list @code{(A ())}, or equivalently @code{(A nil)}, -depicted with boxes and arrows: - -@example -@group - --- --- --- --- - | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> A --> nil -@end group -@end example - - Here is a more complex illustration, showing the three-element list, -@code{((pine needles) oak maple)}, the first element of which is a -two-element list: - -@example -@group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - | --> oak --> maple - | - | --- --- --- --- - --> | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> pine --> needles -@end group -@end example - - The same list represented in the second box notation looks like this: - -@example -@group - -------------- -------------- -------------- -| car | cdr | | car | cdr | | car | cdr | -| o | o------->| oak | o------->| maple | nil | -| | | | | | | | | | - -- | --------- -------------- -------------- - | - | - | -------------- ---------------- - | | car | cdr | | car | cdr | - ------>| pine | o------->| needles | nil | - | | | | | | - -------------- ---------------- -@end group -@end example - -@node Dotted Pair Notation -@subsubsection Dotted Pair Notation -@cindex dotted pair notation -@cindex @samp{.} in lists - - @dfn{Dotted pair notation} is a general syntax for cons cells that -represents the @sc{car} and @sc{cdr} explicitly. In this syntax, -@code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is -the object @var{a} and whose @sc{cdr} is the object @var{b}. Dotted -pair notation is more general than list syntax because the @sc{cdr} -does not have to be a list. However, it is more cumbersome in cases -where list syntax would work. In dotted pair notation, the list -@samp{(1 2 3)} is written as @samp{(1 . (2 . (3 . nil)))}. For -@code{nil}-terminated lists, you can use either notation, but list -notation is usually clearer and more convenient. When printing a -list, the dotted pair notation is only used if the @sc{cdr} of a cons -cell is not a list. - - Here's an example using boxes to illustrate dotted pair notation. -This example shows the pair @code{(rose . violet)}: - -@example -@group - --- --- - | | |--> violet - --- --- - | - | - --> rose -@end group -@end example - - You can combine dotted pair notation with list notation to represent -conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}. -You write a dot after the last element of the list, followed by the -@sc{cdr} of the final cons cell. For example, @code{(rose violet -. buttercup)} is equivalent to @code{(rose . (violet . buttercup))}. -The object looks like this: - -@example -@group - --- --- --- --- - | | |--> | | |--> buttercup - --- --- --- --- - | | - | | - --> rose --> violet -@end group -@end example - - The syntax @code{(rose .@: violet .@: buttercup)} is invalid because -there is nothing that it could mean. If anything, it would say to put -@code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already -used for @code{violet}. - - The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}, -and looks like this: - -@example -@group - --- --- --- --- - | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> rose --> violet -@end group -@end example - - Similarly, the three-element list @code{(rose violet buttercup)} -is equivalent to @code{(rose . (violet . (buttercup)))}. -@ifnottex -It looks like this: - -@example -@group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end example -@end ifnottex - -@node Association List Type -@comment node-name, next, previous, up -@subsubsection Association List Type - - An @dfn{association list} or @dfn{alist} is a specially-constructed -list whose elements are cons cells. In each element, the @sc{car} is -considered a @dfn{key}, and the @sc{cdr} is considered an -@dfn{associated value}. (In some cases, the associated value is stored -in the @sc{car} of the @sc{cdr}.) Association lists are often used as -stacks, since it is easy to add or remove associations at the front of -the list. - - For example, - -@example -(setq alist-of-colors - '((rose . red) (lily . white) (buttercup . yellow))) -@end example - -@noindent -sets the variable @code{alist-of-colors} to an alist of three elements. In the -first element, @code{rose} is the key and @code{red} is the value. - - @xref{Association Lists}, for a further explanation of alists and for -functions that work on alists. @xref{Hash Tables}, for another kind of -lookup table, which is much faster for handling a large number of keys. - -@node Array Type -@subsection Array Type - - An @dfn{array} is composed of an arbitrary number of slots for -holding or referring to other Lisp objects, arranged in a contiguous block of -memory. Accessing any element of an array takes approximately the same -amount of time. In contrast, accessing an element of a list requires -time proportional to the position of the element in the list. (Elements -at the end of a list take longer to access than elements at the -beginning of a list.) - - Emacs defines four types of array: strings, vectors, bool-vectors, and -char-tables. - - A string is an array of characters and a vector is an array of -arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}. -These kinds of array may have any length up to the largest integer. -Char-tables are sparse arrays indexed by any valid character code; they -can hold arbitrary objects. - - The first element of an array has index zero, the second element has -index 1, and so on. This is called @dfn{zero-origin} indexing. For -example, an array of four elements has indices 0, 1, 2, @w{and 3}. The -largest possible index value is one less than the length of the array. -Once an array is created, its length is fixed. - - All Emacs Lisp arrays are one-dimensional. (Most other programming -languages support multidimensional arrays, but they are not essential; -you can get the same effect with nested one-dimensional arrays.) Each -type of array has its own read syntax; see the following sections for -details. - - The array type is a subset of the sequence type, and contains the -string type, the vector type, the bool-vector type, and the char-table -type. - -@node String Type -@subsection String Type - - A @dfn{string} is an array of characters. Strings are used for many -purposes in Emacs, as can be expected in a text editor; for example, as -the names of Lisp symbols, as messages for the user, and to represent -text extracted from buffers. Strings in Lisp are constants: evaluation -of a string returns the same string. - - @xref{Strings and Characters}, for functions that operate on strings. - -@menu -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. -@end menu - -@node Syntax for Strings -@subsubsection Syntax for Strings - -@cindex @samp{"} in strings -@cindex double-quote in strings -@cindex @samp{\} in strings -@cindex backslash in strings - The read syntax for a string is a double-quote, an arbitrary number -of characters, and another double-quote, @code{"like this"}. To -include a double-quote in a string, precede it with a backslash; thus, -@code{"\""} is a string containing just a single double-quote -character. Likewise, you can include a backslash by preceding it with -another backslash, like this: @code{"this \\ is a single embedded -backslash"}. - -@cindex newline in strings - The newline character is not special in the read syntax for strings; -if you write a new line between the double-quotes, it becomes a -character in the string. But an escaped newline---one that is preceded -by @samp{\}---does not become part of the string; i.e., the Lisp reader -ignores an escaped newline while reading a string. An escaped space -@w{@samp{\ }} is likewise ignored. - -@example -"It is useful to include newlines -in documentation strings, -but the newline is \ -ignored if escaped." - @result{} "It is useful to include newlines -in documentation strings, -but the newline is ignored if escaped." -@end example - -@node Non-ASCII in Strings -@subsubsection Non-@acronym{ASCII} Characters in Strings - - You can include a non-@acronym{ASCII} international character in a -string constant by writing it literally. There are two text -representations for non-@acronym{ASCII} characters in Emacs strings -(and in buffers): unibyte and multibyte (@pxref{Text -Representations}). If the string constant is read from a multibyte -source, such as a multibyte buffer or string, or a file that would be -visited as multibyte, then Emacs reads the non-@acronym{ASCII} -character as a multibyte character and automatically makes the string -a multibyte string. If the string constant is read from a unibyte -source, then Emacs reads the non-@acronym{ASCII} character as unibyte, -and makes the string unibyte. - - Instead of writing a non-@acronym{ASCII} character literally into a -multibyte string, you can write it as its character code using a hex -escape, @samp{\x@var{nnnnnnn}}, with as many digits as necessary. -(Multibyte non-@acronym{ASCII} character codes are all greater than -256.) You can also specify a character in a multibyte string using -the @samp{\u} or @samp{\U} Unicode escape syntax (@pxref{General -Escape Syntax}). In either case, any character which is not a valid -hex digit terminates the construct. If the next character in the -string could be interpreted as a hex digit, write @w{@samp{\ }} -(backslash and space) to terminate the hex escape---for example, -@w{@samp{\xe0\ }} represents one character, @samp{a} with grave -accent. @w{@samp{\ }} in a string constant is just like -backslash-newline; it does not contribute any character to the string, -but it does terminate the preceding hex escape. Using any hex escape -in a string (even for an @acronym{ASCII} character) automatically -forces the string to be multibyte. - - You can represent a unibyte non-@acronym{ASCII} character with its -character code, which must be in the range from 128 (0200 octal) to -255 (0377 octal). If you write all such character codes in octal and -the string contains no other characters forcing it to be multibyte, -this produces a unibyte string. - -@node Nonprinting Characters -@subsubsection Nonprinting Characters in Strings - - You can use the same backslash escape-sequences in a string constant -as in character literals (but do not use the question mark that begins a -character constant). For example, you can write a string containing the -nonprinting characters tab and @kbd{C-a}, with commas and spaces between -them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a -description of the read syntax for characters. - - However, not all of the characters you can write with backslash -escape-sequences are valid in strings. The only control characters that -a string can hold are the @acronym{ASCII} control characters. Strings do not -distinguish case in @acronym{ASCII} control characters. - - Properly speaking, strings cannot hold meta characters; but when a -string is to be used as a key sequence, there is a special convention -that provides a way to represent meta versions of @acronym{ASCII} -characters in a string. If you use the @samp{\M-} syntax to indicate -a meta character in a string constant, this sets the -@tex -@math{2^{7}} -@end tex -@ifnottex -2**7 -@end ifnottex -bit of the character in the string. If the string is used in -@code{define-key} or @code{lookup-key}, this numeric code is translated -into the equivalent meta character. @xref{Character Type}. - - Strings cannot hold characters that have the hyper, super, or alt -modifiers. - -@node Text Props and Strings -@subsubsection Text Properties in Strings - -@cindex @samp{#(} read syntax -@cindex text properties, read syntax - A string can hold properties for the characters it contains, in -addition to the characters themselves. This enables programs that copy -text between strings and buffers to copy the text's properties with no -special effort. @xref{Text Properties}, for an explanation of what text -properties mean. Strings with text properties use a special read and -print syntax: - -@example -#("@var{characters}" @var{property-data}...) -@end example - -@noindent -where @var{property-data} consists of zero or more elements, in groups -of three as follows: - -@example -@var{beg} @var{end} @var{plist} -@end example - -@noindent -The elements @var{beg} and @var{end} are integers, and together specify -a range of indices in the string; @var{plist} is the property list for -that range. For example, - -@example -#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic)) -@end example - -@noindent -represents a string whose textual contents are @samp{foo bar}, in which -the first three characters have a @code{face} property with value -@code{bold}, and the last three have a @code{face} property with value -@code{italic}. (The fourth character has no text properties, so its -property list is @code{nil}. It is not actually necessary to mention -ranges with @code{nil} as the property list, since any characters not -mentioned in any range will default to having no properties.) - -@node Vector Type -@subsection Vector Type - - A @dfn{vector} is a one-dimensional array of elements of any type. It -takes a constant amount of time to access any element of a vector. (In -a list, the access time of an element is proportional to the distance of -the element from the beginning of the list.) - - The printed representation of a vector consists of a left square -bracket, the elements, and a right square bracket. This is also the -read syntax. Like numbers and strings, vectors are considered constants -for evaluation. - -@example -[1 "two" (three)] ; @r{A vector of three elements.} - @result{} [1 "two" (three)] -@end example - - @xref{Vectors}, for functions that work with vectors. - -@node Char-Table Type -@subsection Char-Table Type - - A @dfn{char-table} is a one-dimensional array of elements of any type, -indexed by character codes. Char-tables have certain extra features to -make them more useful for many jobs that involve assigning information -to character codes---for example, a char-table can have a parent to -inherit from, a default value, and a small number of extra slots to use for -special purposes. A char-table can also specify a single value for -a whole character set. - - The printed representation of a char-table is like a vector -except that there is an extra @samp{#^} at the beginning. - - @xref{Char-Tables}, for special functions to operate on char-tables. -Uses of char-tables include: - -@itemize @bullet -@item -Case tables (@pxref{Case Tables}). - -@item -Character category tables (@pxref{Categories}). - -@item -Display tables (@pxref{Display Tables}). - -@item -Syntax tables (@pxref{Syntax Tables}). -@end itemize - -@node Bool-Vector Type -@subsection Bool-Vector Type - - A @dfn{bool-vector} is a one-dimensional array whose elements must -be @code{t} or @code{nil}. - - The printed representation of a bool-vector is like a string, except -that it begins with @samp{#&} followed by the length. The string -constant that follows actually specifies the contents of the bool-vector -as a bitmap---each ``character'' in the string contains 8 bits, which -specify the next 8 elements of the bool-vector (1 stands for @code{t}, -and 0 for @code{nil}). The least significant bits of the character -correspond to the lowest indices in the bool-vector. - -@example -(make-bool-vector 3 t) - @result{} #&3"^G" -(make-bool-vector 3 nil) - @result{} #&3"^@@" -@end example - -@noindent -These results make sense, because the binary code for @samp{C-g} is -111 and @samp{C-@@} is the character with code 0. - - If the length is not a multiple of 8, the printed representation -shows extra elements, but these extras really make no difference. For -instance, in the next example, the two bool-vectors are equal, because -only the first 3 bits are used: - -@example -(equal #&3"\377" #&3"\007") - @result{} t -@end example - -@node Hash Table Type -@subsection Hash Table Type - - A hash table is a very fast kind of lookup table, somewhat like an -alist in that it maps keys to corresponding values, but much faster. -The printed representation of a hash table specifies its properties -and contents, like this: - -@example -(make-hash-table) - @result{} #s(hash-table size 65 test eql rehash-size 1.5 - rehash-threshold 0.8 data ()) -@end example - -@noindent -@xref{Hash Tables}, for more information about hash tables. - -@node Function Type -@subsection Function Type - - Lisp functions are executable code, just like functions in other -programming languages. In Lisp, unlike most languages, functions are -also Lisp objects. A non-compiled function in Lisp is a lambda -expression: that is, a list whose first element is the symbol -@code{lambda} (@pxref{Lambda Expressions}). - - In most programming languages, it is impossible to have a function -without a name. In Lisp, a function has no intrinsic name. A lambda -expression can be called as a function even though it has no name; to -emphasize this, we also call it an @dfn{anonymous function} -(@pxref{Anonymous Functions}). A named function in Lisp is just a -symbol with a valid function in its function cell (@pxref{Defining -Functions}). - - Most of the time, functions are called when their names are written in -Lisp expressions in Lisp programs. However, you can construct or obtain -a function object at run time and then call it with the primitive -functions @code{funcall} and @code{apply}. @xref{Calling Functions}. - -@node Macro Type -@subsection Macro Type - - A @dfn{Lisp macro} is a user-defined construct that extends the Lisp -language. It is represented as an object much like a function, but with -different argument-passing semantics. A Lisp macro has the form of a -list whose first element is the symbol @code{macro} and whose @sc{cdr} -is a Lisp function object, including the @code{lambda} symbol. - - Lisp macro objects are usually defined with the built-in -@code{defmacro} function, but any list that begins with @code{macro} is -a macro as far as Emacs is concerned. @xref{Macros}, for an explanation -of how to write a macro. - - @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard -Macros}) are entirely different things. When we use the word ``macro'' -without qualification, we mean a Lisp macro, not a keyboard macro. - -@node Primitive Function Type -@subsection Primitive Function Type -@cindex primitive function - - A @dfn{primitive function} is a function callable from Lisp but -written in the C programming language. Primitive functions are also -called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is -derived from ``subroutine''.) Most primitive functions evaluate all -their arguments when they are called. A primitive function that does -not evaluate all its arguments is called a @dfn{special form} -(@pxref{Special Forms}).@refill - - It does not matter to the caller of a function whether the function is -primitive. However, this does matter if you try to redefine a primitive -with a function written in Lisp. The reason is that the primitive -function may be called directly from C code. Calls to the redefined -function from Lisp will use the new definition, but calls from C code -may still use the built-in definition. Therefore, @strong{we discourage -redefinition of primitive functions}. - - The term @dfn{function} refers to all Emacs functions, whether written -in Lisp or C. @xref{Function Type}, for information about the -functions written in Lisp. - - Primitive functions have no read syntax and print in hash notation -with the name of the subroutine. - -@example -@group -(symbol-function 'car) ; @r{Access the function cell} - ; @r{of the symbol.} - @result{} # -(subrp (symbol-function 'car)) ; @r{Is this a primitive function?} - @result{} t ; @r{Yes.} -@end group -@end example - -@node Byte-Code Type -@subsection Byte-Code Function Type - -@dfn{Byte-code function objects} are produced by byte-compiling Lisp -code (@pxref{Byte Compilation}). Internally, a byte-code function -object is much like a vector; however, the evaluator handles this data -type specially when it appears in a function call. @xref{Byte-Code -Objects}. - -The printed representation and read syntax for a byte-code function -object is like that for a vector, with an additional @samp{#} before the -opening @samp{[}. - -@node Autoload Type -@subsection Autoload Type - - An @dfn{autoload object} is a list whose first element is the symbol -@code{autoload}. It is stored as the function definition of a symbol, -where it serves as a placeholder for the real definition. The autoload -object says that the real definition is found in a file of Lisp code -that should be loaded when necessary. It contains the name of the file, -plus some other information about the real definition. - - After the file has been loaded, the symbol should have a new function -definition that is not an autoload object. The new definition is then -called as if it had been there to begin with. From the user's point of -view, the function call works as expected, using the function definition -in the loaded file. - - An autoload object is usually created with the function -@code{autoload}, which stores the object in the function cell of a -symbol. @xref{Autoload}, for more details. - -@node Editing Types -@section Editing Types -@cindex editing types - - The types in the previous section are used for general programming -purposes, and most of them are common to most Lisp dialects. Emacs Lisp -provides several additional data types for purposes connected with -editing. - -@menu -* Buffer Type:: The basic object of editing. -* Marker Type:: A position in a buffer. -* Window Type:: Buffers are displayed in windows. -* Frame Type:: Windows subdivide frames. -* Terminal Type:: A terminal device displays frames. -* Window Configuration Type:: Recording the way a frame is subdivided. -* Frame Configuration Type:: Recording the status of all frames. -* Process Type:: A subprocess of Emacs running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Overlay Type:: How an overlay is represented. -* Font Type:: Fonts for displaying text. -@end menu - -@node Buffer Type -@subsection Buffer Type - - A @dfn{buffer} is an object that holds text that can be edited -(@pxref{Buffers}). Most buffers hold the contents of a disk file -(@pxref{Files}) so they can be edited, but some are used for other -purposes. Most buffers are also meant to be seen by the user, and -therefore displayed, at some time, in a window (@pxref{Windows}). But -a buffer need not be displayed in any window. Each buffer has a -designated position called @dfn{point} (@pxref{Positions}); most -editing commands act on the contents of the current buffer in the -neighborhood of point. At any time, one buffer is the @dfn{current -buffer}. - - The contents of a buffer are much like a string, but buffers are not -used like strings in Emacs Lisp, and the available operations are -different. For example, you can insert text efficiently into an -existing buffer, altering the buffer's contents, whereas ``inserting'' -text into a string requires concatenating substrings, and the result -is an entirely new string object. - - Many of the standard Emacs functions manipulate or test the -characters in the current buffer; a whole chapter in this manual is -devoted to describing these functions (@pxref{Text}). - - Several other data structures are associated with each buffer: - -@itemize @bullet -@item -a local syntax table (@pxref{Syntax Tables}); - -@item -a local keymap (@pxref{Keymaps}); and, - -@item -a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}). - -@item -overlays (@pxref{Overlays}). - -@item -text properties for the text in the buffer (@pxref{Text Properties}). -@end itemize - -@noindent -The local keymap and variable list contain entries that individually -override global bindings or values. These are used to customize the -behavior of programs in different buffers, without actually changing the -programs. - - A buffer may be @dfn{indirect}, which means it shares the text -of another buffer, but presents it differently. @xref{Indirect Buffers}. - - Buffers have no read syntax. They print in hash notation, showing the -buffer name. - -@example -@group -(current-buffer) - @result{} # -@end group -@end example - -@node Marker Type -@subsection Marker Type - - A @dfn{marker} denotes a position in a specific buffer. Markers -therefore have two components: one for the buffer, and one for the -position. Changes in the buffer's text automatically relocate the -position value as necessary to ensure that the marker always points -between the same two characters in the buffer. - - Markers have no read syntax. They print in hash notation, giving the -current character position and the name of the buffer. - -@example -@group -(point-marker) - @result{} # -@end group -@end example - -@xref{Markers}, for information on how to test, create, copy, and move -markers. - -@node Window Type -@subsection Window Type - - A @dfn{window} describes the portion of the terminal screen that Emacs -uses to display a buffer. Every window has one associated buffer, whose -contents appear in the window. By contrast, a given buffer may appear -in one window, no window, or several windows. - - Though many windows may exist simultaneously, at any time one window -is designated the @dfn{selected window}. This is the window where the -cursor is (usually) displayed when Emacs is ready for a command. The -selected window usually displays the current buffer, but this is not -necessarily the case. - - Windows are grouped on the screen into frames; each window belongs to -one and only one frame. @xref{Frame Type}. - - Windows have no read syntax. They print in hash notation, giving the -window number and the name of the buffer being displayed. The window -numbers exist to identify windows uniquely, since the buffer displayed -in any given window can change frequently. - -@example -@group -(selected-window) - @result{} # -@end group -@end example - - @xref{Windows}, for a description of the functions that work on windows. - -@node Frame Type -@subsection Frame Type - - A @dfn{frame} is a screen area that contains one or more Emacs -windows; we also use the term ``frame'' to refer to the Lisp object -that Emacs uses to refer to the screen area. - - Frames have no read syntax. They print in hash notation, giving the -frame's title, plus its address in core (useful to identify the frame -uniquely). - -@example -@group -(selected-frame) - @result{} # -@end group -@end example - - @xref{Frames}, for a description of the functions that work on frames. - -@node Terminal Type -@subsection Terminal Type -@cindex terminal type - - A @dfn{terminal} is a device capable of displaying one or more -Emacs frames (@pxref{Frame Type}). - - Terminals have no read syntax. They print in hash notation giving -the terminal's ordinal number and its TTY device file name. - -@example -@group -(get-device-terminal nil) - @result{} # -@end group -@end example - -@c FIXME: add an xref to where terminal-related primitives are described. - -@node Window Configuration Type -@subsection Window Configuration Type -@cindex window layout in a frame - - A @dfn{window configuration} stores information about the positions, -sizes, and contents of the windows in a frame, so you can recreate the -same arrangement of windows later. - - Window configurations do not have a read syntax; their print syntax -looks like @samp{#}. @xref{Window -Configurations}, for a description of several functions related to -window configurations. - -@node Frame Configuration Type -@subsection Frame Configuration Type -@cindex screen layout -@cindex window layout, all frames - - A @dfn{frame configuration} stores information about the positions, -sizes, and contents of the windows in all frames. It is not a -primitive type---it is actually a list whose @sc{car} is -@code{frame-configuration} and whose @sc{cdr} is an alist. Each alist -element describes one frame, which appears as the @sc{car} of that -element. - - @xref{Frame Configurations}, for a description of several functions -related to frame configurations. - -@node Process Type -@subsection Process Type - - The word @dfn{process} usually means a running program. Emacs itself -runs in a process of this sort. However, in Emacs Lisp, a process is a -Lisp object that designates a subprocess created by the Emacs process. -Programs such as shells, GDB, ftp, and compilers, running in -subprocesses of Emacs, extend the capabilities of Emacs. - An Emacs subprocess takes textual input from Emacs and returns textual -output to Emacs for further manipulation. Emacs can also send signals -to the subprocess. - - Process objects have no read syntax. They print in hash notation, -giving the name of the process: - -@example -@group -(process-list) - @result{} (#) -@end group -@end example - -@xref{Processes}, for information about functions that create, delete, -return information about, send input or signals to, and receive output -from processes. - -@node Stream Type -@subsection Stream Type - - A @dfn{stream} is an object that can be used as a source or sink for -characters---either to supply characters for input or to accept them as -output. Many different types can be used this way: markers, buffers, -strings, and functions. Most often, input streams (character sources) -obtain characters from the keyboard, a buffer, or a file, and output -streams (character sinks) send characters to a buffer, such as a -@file{*Help*} buffer, or to the echo area. - - The object @code{nil}, in addition to its other meanings, may be used -as a stream. It stands for the value of the variable -@code{standard-input} or @code{standard-output}. Also, the object -@code{t} as a stream specifies input using the minibuffer -(@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo -Area}). - - Streams have no special printed representation or read syntax, and -print as whatever primitive type they are. - - @xref{Read and Print}, for a description of functions -related to streams, including parsing and printing functions. - -@node Keymap Type -@subsection Keymap Type - - A @dfn{keymap} maps keys typed by the user to commands. This mapping -controls how the user's command input is executed. A keymap is actually -a list whose @sc{car} is the symbol @code{keymap}. - - @xref{Keymaps}, for information about creating keymaps, handling prefix -keys, local as well as global keymaps, and changing key bindings. - -@node Overlay Type -@subsection Overlay Type - - An @dfn{overlay} specifies properties that apply to a part of a -buffer. Each overlay applies to a specified range of the buffer, and -contains a property list (a list whose elements are alternating property -names and values). Overlay properties are used to present parts of the -buffer temporarily in a different display style. Overlays have no read -syntax, and print in hash notation, giving the buffer name and range of -positions. - - @xref{Overlays}, for information on how you can create and use overlays. - -@node Font Type -@subsection Font Type - - A @dfn{font} specifies how to display text on a graphical terminal. -There are actually three separate font types---@dfn{font objects}, -@dfn{font specs}, and @dfn{font entities}---each of which has slightly -different properties. None of them have a read syntax; their print -syntax looks like @samp{#}, @samp{#}, and -@samp{#} respectively. @xref{Low-Level Font}, for a -description of these Lisp objects. - -@node Circular Objects -@section Read Syntax for Circular Objects -@cindex circular structure, read syntax -@cindex shared structure, read syntax -@cindex @samp{#@var{n}=} read syntax -@cindex @samp{#@var{n}#} read syntax - - To represent shared or circular structures within a complex of Lisp -objects, you can use the reader constructs @samp{#@var{n}=} and -@samp{#@var{n}#}. - - Use @code{#@var{n}=} before an object to label it for later reference; -subsequently, you can use @code{#@var{n}#} to refer the same object in -another place. Here, @var{n} is some integer. For example, here is how -to make a list in which the first element recurs as the third element: - -@example -(#1=(a) b #1#) -@end example - -@noindent -This differs from ordinary syntax such as this - -@example -((a) b (a)) -@end example - -@noindent -which would result in a list whose first and third elements -look alike but are not the same Lisp object. This shows the difference: - -@example -(prog1 nil - (setq x '(#1=(a) b #1#))) -(eq (nth 0 x) (nth 2 x)) - @result{} t -(setq x '((a) b (a))) -(eq (nth 0 x) (nth 2 x)) - @result{} nil -@end example - - You can also use the same syntax to make a circular structure, which -appears as an ``element'' within itself. Here is an example: - -@example -#1=(a #1#) -@end example - -@noindent -This makes a list whose second element is the list itself. -Here's how you can see that it really works: - -@example -(prog1 nil - (setq x '#1=(a #1#))) -(eq x (cadr x)) - @result{} t -@end example - - The Lisp printer can produce this syntax to record circular and shared -structure in a Lisp object, if you bind the variable @code{print-circle} -to a non-@code{nil} value. @xref{Output Variables}. - -@node Type Predicates -@section Type Predicates -@cindex type checking -@kindex wrong-type-argument - - The Emacs Lisp interpreter itself does not perform type checking on -the actual arguments passed to functions when they are called. It could -not do so, since function arguments in Lisp do not have declared data -types, as they do in other programming languages. It is therefore up to -the individual function to test whether each actual argument belongs to -a type that the function can use. - - All built-in functions do check the types of their actual arguments -when appropriate, and signal a @code{wrong-type-argument} error if an -argument is of the wrong type. For example, here is what happens if you -pass an argument to @code{+} that it cannot handle: - -@example -@group -(+ 2 'a) - @error{} Wrong type argument: number-or-marker-p, a -@end group -@end example - -@cindex type predicates -@cindex testing types - If you want your program to handle different types differently, you -must do explicit type checking. The most common way to check the type -of an object is to call a @dfn{type predicate} function. Emacs has a -type predicate for each type, as well as some predicates for -combinations of types. - - A type predicate function takes one argument; it returns @code{t} if -the argument belongs to the appropriate type, and @code{nil} otherwise. -Following a general Lisp convention for predicate functions, most type -predicates' names end with @samp{p}. - - Here is an example which uses the predicates @code{listp} to check for -a list and @code{symbolp} to check for a symbol. - -@example -(defun add-on (x) - (cond ((symbolp x) - ;; If X is a symbol, put it on LIST. - (setq list (cons x list))) - ((listp x) - ;; If X is a list, add its elements to LIST. - (setq list (append x list))) - (t - ;; We handle only symbols and lists. - (error "Invalid argument %s in add-on" x)))) -@end example - - Here is a table of predefined type predicates, in alphabetical order, -with references to further information. - -@table @code -@item atom -@xref{List-related Predicates, atom}. - -@item arrayp -@xref{Array Functions, arrayp}. - -@item bool-vector-p -@xref{Bool-Vectors, bool-vector-p}. - -@item bufferp -@xref{Buffer Basics, bufferp}. - -@item byte-code-function-p -@xref{Byte-Code Type, byte-code-function-p}. - -@item case-table-p -@xref{Case Tables, case-table-p}. - -@item char-or-string-p -@xref{Predicates for Strings, char-or-string-p}. - -@item char-table-p -@xref{Char-Tables, char-table-p}. - -@item commandp -@xref{Interactive Call, commandp}. - -@item consp -@xref{List-related Predicates, consp}. - -@item custom-variable-p -@xref{Variable Definitions, custom-variable-p}. - -@item display-table-p -@xref{Display Tables, display-table-p}. - -@item floatp -@xref{Predicates on Numbers, floatp}. - -@item fontp -@xref{Low-Level Font}. - -@item frame-configuration-p -@xref{Frame Configurations, frame-configuration-p}. - -@item frame-live-p -@xref{Deleting Frames, frame-live-p}. - -@item framep -@xref{Frames, framep}. - -@item functionp -@xref{Functions, functionp}. - -@item hash-table-p -@xref{Other Hash, hash-table-p}. - -@item integer-or-marker-p -@xref{Predicates on Markers, integer-or-marker-p}. - -@item integerp -@xref{Predicates on Numbers, integerp}. - -@item keymapp -@xref{Creating Keymaps, keymapp}. - -@item keywordp -@xref{Constant Variables}. - -@item listp -@xref{List-related Predicates, listp}. - -@item markerp -@xref{Predicates on Markers, markerp}. - -@item wholenump -@xref{Predicates on Numbers, wholenump}. - -@item nlistp -@xref{List-related Predicates, nlistp}. - -@item numberp -@xref{Predicates on Numbers, numberp}. - -@item number-or-marker-p -@xref{Predicates on Markers, number-or-marker-p}. - -@item overlayp -@xref{Overlays, overlayp}. - -@item processp -@xref{Processes, processp}. - -@item sequencep -@xref{Sequence Functions, sequencep}. - -@item stringp -@xref{Predicates for Strings, stringp}. - -@item subrp -@xref{Function Cells, subrp}. - -@item symbolp -@xref{Symbols, symbolp}. - -@item syntax-table-p -@xref{Syntax Tables, syntax-table-p}. - -@item vectorp -@xref{Vectors, vectorp}. - -@item window-configuration-p -@xref{Window Configurations, window-configuration-p}. - -@item window-live-p -@xref{Deleting Windows, window-live-p}. - -@item windowp -@xref{Basic Windows, windowp}. - -@item booleanp -@xref{nil and t, booleanp}. - -@item string-or-null-p -@xref{Predicates for Strings, string-or-null-p}. -@end table - - The most general way to check the type of an object is to call the -function @code{type-of}. Recall that each object belongs to one and -only one primitive type; @code{type-of} tells you which one (@pxref{Lisp -Data Types}). But @code{type-of} knows nothing about non-primitive -types. In most cases, it is more convenient to use type predicates than -@code{type-of}. - -@defun type-of object -This function returns a symbol naming the primitive type of -@var{object}. The value is one of the symbols @code{bool-vector}, -@code{buffer}, @code{char-table}, @code{compiled-function}, -@code{cons}, @code{float}, @code{font-entity}, @code{font-object}, -@code{font-spec}, @code{frame}, @code{hash-table}, @code{integer}, -@code{marker}, @code{overlay}, @code{process}, @code{string}, -@code{subr}, @code{symbol}, @code{vector}, @code{window}, or -@code{window-configuration}. - -@example -(type-of 1) - @result{} integer -@group -(type-of 'nil) - @result{} symbol -(type-of '()) ; @r{@code{()} is @code{nil}.} - @result{} symbol -(type-of '(x)) - @result{} cons -@end group -@end example -@end defun - -@node Equality Predicates -@section Equality Predicates -@cindex equality - - Here we describe functions that test for equality between two -objects. Other functions test equality of contents between objects of -specific types, e.g.@: strings. For these predicates, see the -appropriate chapter describing the data type. - -@defun eq object1 object2 -This function returns @code{t} if @var{object1} and @var{object2} are -the same object, and @code{nil} otherwise. - -If @var{object1} and @var{object2} are integers with the same value, -they are considered to be the same object (i.e.@: @code{eq} returns -@code{t}). If @var{object1} and @var{object2} are symbols with the -same name, they are normally the same object---but see @ref{Creating -Symbols} for exceptions. For other types (e.g.@: lists, vectors, -strings), two arguments with the same contents or elements are not -necessarily @code{eq} to each other: they are @code{eq} only if they -are the same object, meaning that a change in the contents of one will -be reflected by the same change in the contents of the other. - -@example -@group -(eq 'foo 'foo) - @result{} t -@end group - -@group -(eq 456 456) - @result{} t -@end group - -@group -(eq "asdf" "asdf") - @result{} nil -@end group - -@group -(eq "" "") - @result{} t -;; @r{This exception occurs because Emacs Lisp} -;; @r{makes just one multibyte empty string, to save space.} -@end group - -@group -(eq '(1 (2 (3))) '(1 (2 (3)))) - @result{} nil -@end group - -@group -(setq foo '(1 (2 (3)))) - @result{} (1 (2 (3))) -(eq foo foo) - @result{} t -(eq foo '(1 (2 (3)))) - @result{} nil -@end group - -@group -(eq [(1 2) 3] [(1 2) 3]) - @result{} nil -@end group - -@group -(eq (point-marker) (point-marker)) - @result{} nil -@end group -@end example - -@noindent -The @code{make-symbol} function returns an uninterned symbol, distinct -from the symbol that is used if you write the name in a Lisp expression. -Distinct symbols with the same name are not @code{eq}. @xref{Creating -Symbols}. - -@example -@group -(eq (make-symbol "foo") 'foo) - @result{} nil -@end group -@end example -@end defun - -@defun equal object1 object2 -This function returns @code{t} if @var{object1} and @var{object2} have -equal components, and @code{nil} otherwise. Whereas @code{eq} tests -if its arguments are the same object, @code{equal} looks inside -nonidentical arguments to see if their elements or contents are the -same. So, if two objects are @code{eq}, they are @code{equal}, but -the converse is not always true. - -@example -@group -(equal 'foo 'foo) - @result{} t -@end group - -@group -(equal 456 456) - @result{} t -@end group - -@group -(equal "asdf" "asdf") - @result{} t -@end group -@group -(eq "asdf" "asdf") - @result{} nil -@end group - -@group -(equal '(1 (2 (3))) '(1 (2 (3)))) - @result{} t -@end group -@group -(eq '(1 (2 (3))) '(1 (2 (3)))) - @result{} nil -@end group - -@group -(equal [(1 2) 3] [(1 2) 3]) - @result{} t -@end group -@group -(eq [(1 2) 3] [(1 2) 3]) - @result{} nil -@end group - -@group -(equal (point-marker) (point-marker)) - @result{} t -@end group - -@group -(eq (point-marker) (point-marker)) - @result{} nil -@end group -@end example - -Comparison of strings is case-sensitive, but does not take account of -text properties---it compares only the characters in the strings. -@xref{Text Properties}. Use @code{equal-including-properties} to also -compare text properties. For technical reasons, a unibyte string and -a multibyte string are @code{equal} if and only if they contain the -same sequence of character codes and all these codes are either in the -range 0 through 127 (@acronym{ASCII}) or 160 through 255 -(@code{eight-bit-graphic}). (@pxref{Text Representations}). - -@example -@group -(equal "asdf" "ASDF") - @result{} nil -@end group -@end example - -However, two distinct buffers are never considered @code{equal}, even if -their textual contents are the same. -@end defun - - The test for equality is implemented recursively; for example, given -two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})} -returns @code{t} if and only if both the expressions below return -@code{t}: - -@example -(equal (car @var{x}) (car @var{y})) -(equal (cdr @var{x}) (cdr @var{y})) -@end example - -Because of this recursive method, circular lists may therefore cause -infinite recursion (leading to an error). - -@defun equal-including-properties object1 object2 -This function behaves like @code{equal} in all cases but also requires -that for two strings to be equal, they have the same text properties. - -@example -@group -(equal "asdf" (propertize "asdf" '(asdf t))) - @result{} t -@end group -@group -(equal-including-properties "asdf" - (propertize "asdf" '(asdf t))) - @result{} nil -@end group -@end example -@end defun diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi deleted file mode 100644 index 384531c8e37..00000000000 --- a/doc/lispref/os.texi +++ /dev/null @@ -1,2448 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/os -@node System Interface, Packaging, Display, Top -@chapter Operating System Interface - - This chapter is about starting and getting out of Emacs, access to -values in the operating system environment, and terminal input, output. - - @xref{Building Emacs}, for related information. @xref{Display}, for -additional operating system status information pertaining to the -terminal and the screen. - -@menu -* Starting Up:: Customizing Emacs startup processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* User Identification:: Finding the name and user id of the user. -* Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to - calendrical data and vice versa. -* Time Parsing:: Converting a time from numeric form to text - and vice versa. -* Processor Run Time:: Getting the run time used by Emacs. -* Time Calculations:: Adding, subtracting, comparing times, etc. -* Timers:: Setting a timer to call a function at a certain time. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording terminal input. -* Terminal Output:: Controlling and recording terminal output. -* Sound Output:: Playing sounds on the computer's speaker. -* X11 Keysyms:: Operating on key symbols for X Windows. -* Batch Mode:: Running Emacs without terminal interaction. -* Session Management:: Saving and restoring state with X Session Management. -* Notifications:: Desktop notifications. -* Dynamic Libraries:: On-demand loading of support libraries. -@end menu - -@node Starting Up -@section Starting Up Emacs - - This section describes what Emacs does when it is started, and how you -can customize these actions. - -@menu -* Startup Summary:: Sequence of actions Emacs performs at startup. -* Init File:: Details on reading the init file. -* Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command-Line Arguments:: How command-line arguments are processed, - and how you can customize them. -@end menu - -@node Startup Summary -@subsection Summary: Sequence of Actions at Startup -@cindex initialization of Emacs -@cindex startup of Emacs -@cindex @file{startup.el} - - When Emacs is started up, it performs the following operations -(see @code{normal-top-level} in @file{startup.el}): - -@enumerate -@item -It adds subdirectories to @code{load-path}, by running the file named -@file{subdirs.el} in each directory in the list. Normally, this file -adds the directory's subdirectories to the list, and those are scanned -in their turn. The files @file{subdirs.el} are normally generated -automatically when Emacs is installed. - -@item -It registers input methods by loading any @file{leim-list.el} file -found in the @code{load-path}. - -@c It removes PWD from the environment if it is not accurate. -@c It abbreviates default-directory. - -@c Now normal-top-level calls command-line. - -@vindex before-init-time -@item -It sets the variable @code{before-init-time} to the value of -@code{current-time} (@pxref{Time of Day}). It also sets -@code{after-init-time} to @code{nil}, which signals to Lisp programs -that Emacs is being initialized. - -@c set-locale-environment -@item -It sets the language environment and the terminal coding system, -if requested by environment variables such as @env{LANG}. - -@item -It does some basic parsing of the command-line arguments. - -@vindex initial-window-system@r{, and startup} -@vindex window-system-initialization-alist -@item -If not running in batch mode, it initializes the window system that -the variable @code{initial-window-system} specifies (@pxref{Window -Systems, initial-window-system}). The initialization function for -each supported window system is specified by -@code{window-system-initialization-alist}. If the value -of @code{initial-window-system} is @var{windowsystem}, then the -appropriate initialization function is defined in the file -@file{term/@var{windowsystem}-win.el}. This file should have been -compiled into the Emacs executable when it was built. - -@item -It runs the normal hook @code{before-init-hook}. - -@item -If appropriate, it creates a graphical frame. This is not done if the -options @samp{--batch} or @samp{--daemon} were specified. - -@item -It initializes the initial frame's faces, and sets up the menu bar -and tool bar if needed. If graphical frames are supported, it sets up -the tool bar even if the current frame is not a graphical one, since a -graphical frame may be created later on. - -@item -It use @code{custom-reevaluate-setting} to re-initialize the members -of the list @code{custom-delayed-init-variables}. These are any -pre-loaded user options whose default value depends on the run-time, -rather than build-time, context. -@xref{Building Emacs, custom-initialize-delay}. - -@c @item -@c It registers the colors available for tty frames. - -@item -It loads the library @file{site-start}, if it exists. This is not -done if the options @samp{-Q} or @samp{--no-site-file} were specified. -@cindex @file{site-start.el} - -@item -It loads your init file (@pxref{Init File}). This is not done if the -options @samp{-q}, @samp{-Q}, or @samp{--batch} were specified. If -the @samp{-u} option was specified, Emacs looks for the init file in -that user's home directory instead. - -@item -It loads the library @file{default}, if it exists. This is not done -if @code{inhibit-default-init} is non-@code{nil}, nor if the options -@samp{-q}, @samp{-Q}, or @samp{--batch} were specified. -@cindex @file{default.el} - -@item -It loads your abbrevs from the file specified by -@code{abbrev-file-name}, if that file exists and can be read -(@pxref{Abbrev Files, abbrev-file-name}). This is not done if the -option @samp{--batch} was specified. - -@item -If @code{package-enable-at-startup} is non-@code{nil}, it calls the -function @code{package-initialize} to activate any optional Emacs Lisp -package that has been installed. @xref{Packaging Basics}. - -@vindex after-init-time -@item -It sets the variable @code{after-init-time} to the value of -@code{current-time}. This variable was set to @code{nil} earlier; -setting it to the current time signals that the initialization phase -is over, and, together with @code{before-init-time}, provides the -measurement of how long it took. - -@item -It runs the normal hook @code{after-init-hook}. - -@item -If the buffer @file{*scratch*} exists and is still in Fundamental mode -(as it should be by default), it sets its major mode according to -@code{initial-major-mode}. - -@item -If started on a text terminal, it loads the terminal-specific -Lisp library, which is specified by the variable -@code{term-file-prefix} (@pxref{Terminal-Specific}). This is not done -in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}. - -@c Now command-line calls command-line-1. - -@item -It displays the initial echo area message, unless you have suppressed -that with @code{inhibit-startup-echo-area-message}. - -@item -It processes any command-line options that were not handled earlier. - -@c This next one is back in command-line, but the remaining bits of -@c command-line-1 are not done if noninteractive. -@item -It now exits if the option @code{--batch} was specified. - -@item -If @code{initial-buffer-choice} is a string, it visits the file with -that name. If the @file{*scratch*} buffer exists and is -empty, it inserts @code{initial-scratch-message} into that buffer. - -@c To make things nice and confusing, the next three items can be -@c called from two places. If displaying a startup screen, they are -@c called in command-line-1 before the startup screen is shown. -@c inhibit-startup-hooks is then set and window-setup-hook set to nil. -@c If not displaying a startup screen, they are are called in -@c normal-top-level. -@c FIXME? So it seems they can be called before or after the -@c daemon/session restore step? - -@item -It runs @code{emacs-startup-hook} and then @code{term-setup-hook}. - -@item -It calls @code{frame-notice-user-settings}, which modifies the -parameters of the selected frame according to whatever the init files -specify. - -@item -It runs @code{window-setup-hook}. @xref{Window Systems}. - -@item -It displays the @dfn{startup screen}, which is a special buffer that -contains information about copyleft and basic Emacs usage. This is -not done if @code{inhibit-startup-screen} or @code{initial-buffer-choice} -are non-@code{nil}, or if the @samp{--no-splash} or @samp{-Q} command-line -options were specified. - -@c End of command-line-1. - -@c Back to command-line from command-line-1. - -@c This is the point at which we actually exit in batch mode, but the -@c last few bits of command-line-1 are not done in batch mode. - -@item -If the option @code{--daemon} was specified, it calls -@code{server-start} and detaches from the controlling terminal. -@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. - -@item -If started by the X session manager, it calls -@code{emacs-session-restore} passing it as argument the ID of the -previous session. @xref{Session Management}. - -@c End of command-line. - -@c Back to normal-top-level from command-line. - -@end enumerate - -@noindent -The following options affect some aspects of the startup sequence. - -@defopt inhibit-startup-screen -This variable, if non-@code{nil}, inhibits the startup screen. In -that case, Emacs typically displays the @file{*scratch*} buffer; but -see @code{initial-buffer-choice}, below. - -Do not set this variable in the init file of a new user, or in a way -that affects more than one user, as that would prevent new users from -receiving information about copyleft and basic Emacs usage. - -@vindex inhibit-startup-message -@vindex inhibit-splash-screen -@code{inhibit-startup-message} and @code{inhibit-splash-screen} are -aliases for this variable. -@end defopt - -@defopt initial-buffer-choice -If non-@code{nil}, this variable is a string that specifies a file or -directory for Emacs to display after starting up, instead of the -startup screen. -@ignore -@c I do not think this should be mentioned. AFAICS it is just a dodge -@c around inhibit-startup-screen not being settable on a site-wide basis. -If its value is @code{t}, Emacs displays the @file{*scratch*} buffer. -@end ignore -@end defopt - -@defopt inhibit-startup-echo-area-message -This variable controls the display of the startup echo area message. -You can suppress the startup echo area message by adding text with this -form to your init file: - -@example -(setq inhibit-startup-echo-area-message - "@var{your-login-name}") -@end example - -Emacs explicitly checks for an expression as shown above in your init -file; your login name must appear in the expression as a Lisp string -constant. You can also use the Customize interface. Other methods of -setting @code{inhibit-startup-echo-area-message} to the same value do -not inhibit the startup message. This way, you can easily inhibit the -message for yourself if you wish, but thoughtless copying of your init -file will not inhibit the message for someone else. -@end defopt - -@defopt initial-scratch-message -This variable, if non-@code{nil}, should be a string, which is -inserted into the @file{*scratch*} buffer when Emacs starts up. If it -is @code{nil}, the @file{*scratch*} buffer is empty. -@end defopt - -@noindent -The following command-line options affect some aspects of the startup -sequence. @xref{Initial Options,,, emacs, The GNU Emacs Manual}. - -@table @code -@item --no-splash -Do not display a splash screen. - -@item --batch -Run without an interactive terminal. @xref{Batch Mode}. - -@item --daemon -Do not initialize any display; just start a server in the background. - -@item --no-init-file -@itemx -Q -Do not load either the init file, or the @file{default} library. - -@item --no-site-file -Do not load the @file{site-start} library. - -@item --quick -@itemx -Q -Equivalent to @samp{-q --no-site-file --no-splash}. -@c and --no-site-lisp, but let's not mention that here. -@end table - - -@node Init File -@subsection The Init File -@cindex init file -@cindex @file{.emacs} -@cindex @file{init.el} - - When you start Emacs, it normally attempts to load your @dfn{init -file}. This is either a file named @file{.emacs} or @file{.emacs.el} -in your home directory, or a file named @file{init.el} in a -subdirectory named @file{.emacs.d} in your home directory. -@ignore -Whichever place you use, you can also compile the file (@pxref{Byte -Compilation}); then the actual file loaded will be @file{.emacs.elc} -or @file{init.elc}. -@end ignore - - The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u} -control whether and where to find the init file; @samp{-q} (and the -stronger @samp{-Q}) says not to load an init file, while @samp{-u -@var{user}} says to load @var{user}'s init file instead of yours. -@xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither -option is specified, Emacs uses the @env{LOGNAME} environment -variable, or the @env{USER} (most systems) or @env{USERNAME} (MS -systems) variable, to find your home directory and thus your init -file; this way, even if you have su'd, Emacs still loads your own init -file. If those environment variables are absent, though, Emacs uses -your user-id to find your home directory. - -@cindex default init file - An Emacs installation may have a @dfn{default init file}, which is a -Lisp library named @file{default.el}. Emacs finds this file through -the standard search path for libraries (@pxref{How Programs Do -Loading}). The Emacs distribution does not come with this file; it is -intended for local customizations. If the default init file exists, -it is loaded whenever you start Emacs. But your own personal init -file, if any, is loaded first; if it sets @code{inhibit-default-init} -to a non-@code{nil} value, then Emacs does not subsequently load the -@file{default.el} file. In batch mode, or if you specify @samp{-q} -(or @samp{-Q}), Emacs loads neither your personal init file nor -the default init file. - - Another file for site-customization is @file{site-start.el}. Emacs -loads this @emph{before} the user's init file. You can inhibit the -loading of this file with the option @samp{--no-site-file}. - -@defopt site-run-file -This variable specifies the site-customization file to load before the -user's init file. Its normal value is @code{"site-start"}. The only -way you can change it with real effect is to do so before dumping -Emacs. -@c So why even mention it here. I imagine it is almost never changed. -@end defopt - - @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for -examples of how to make various commonly desired customizations in your -@file{.emacs} file. - -@defopt inhibit-default-init -If this variable is non-@code{nil}, it prevents Emacs from loading the -default initialization library file. The default value is @code{nil}. -@end defopt - -@defvar before-init-hook -This normal hook is run, once, just before loading all the init files -(@file{site-start.el}, your init file, and @file{default.el}). -(The only way to change it with real effect is before dumping Emacs.) -@end defvar - -@defvar after-init-hook -This normal hook is run, once, just after loading all the init files -(@file{site-start.el}, your init file, and @file{default.el}), -before loading the terminal-specific library (if started on a text -terminal) and processing the command-line action arguments. -@end defvar - -@defvar emacs-startup-hook -This normal hook is run, once, just after handling the command line -arguments, just before @code{term-setup-hook}. In batch mode, Emacs -does not run either of these hooks. -@end defvar - -@defvar user-init-file -This variable holds the absolute file name of the user's init file. If the -actual init file loaded is a compiled file, such as @file{.emacs.elc}, -the value refers to the corresponding source file. -@end defvar - -@defvar user-emacs-directory -This variable holds the name of the @file{.emacs.d} directory. It is -@file{~/.emacs.d} on all platforms but MS-DOS. -@end defvar - -@node Terminal-Specific -@subsection Terminal-Specific Initialization -@cindex terminal-specific initialization - - Each terminal type can have its own Lisp library that Emacs loads when -run on that type of terminal. The library's name is constructed by -concatenating the value of the variable @code{term-file-prefix} and the -terminal type (specified by the environment variable @env{TERM}). -Normally, @code{term-file-prefix} has the value -@code{"term/"}; changing this is not recommended. Emacs finds the file -in the normal manner, by searching the @code{load-path} directories, and -trying the @samp{.elc} and @samp{.el} suffixes. - -@cindex Termcap - The usual role of a terminal-specific library is to enable special -keys to send sequences that Emacs can recognize. It may also need to -set or add to @code{input-decode-map} if the Termcap or Terminfo entry -does not specify all the terminal's function keys. @xref{Terminal -Input}. - - When the name of the terminal type contains a hyphen or underscore, and no library -is found whose name is identical to the terminal's name, Emacs strips -from the terminal's name the last hyphen or underscore and everything that follows -it, and tries again. This process is repeated until Emacs finds a -matching library, or until there are no more hyphens or underscores in the name -(i.e.@: there is no terminal-specific library). For example, if the -terminal name is @samp{xterm-256color} and there is no -@file{term/xterm-256color.el} library, Emacs tries to load -@file{term/xterm.el}. If necessary, the terminal library can evaluate -@code{(getenv "TERM")} to find the full name of the terminal type. - - Your init file can prevent the loading of the -terminal-specific library by setting the variable -@code{term-file-prefix} to @code{nil}. This feature is useful when -experimenting with your own peculiar customizations. - - You can also arrange to override some of the actions of the -terminal-specific library by setting the variable -@code{term-setup-hook}. This is a normal hook that Emacs runs -at the end of its initialization, after loading both -your init file and any terminal-specific libraries. You could -use this hook to define initializations for terminals that do not -have their own libraries. @xref{Hooks}. - -@defvar term-file-prefix -@cindex @env{TERM} environment variable -If the value of this variable is non-@code{nil}, Emacs loads a -terminal-specific initialization file as follows: - -@example -(load (concat term-file-prefix (getenv "TERM"))) -@end example - -@noindent -You may set the @code{term-file-prefix} variable to @code{nil} in your -init file if you do not wish to load the -terminal-initialization file. - -On MS-DOS, Emacs sets the @env{TERM} environment variable to @samp{internal}. -@end defvar - -@defvar term-setup-hook -This variable is a normal hook that Emacs runs after loading your -init file, the default initialization file (if any) and the -terminal-specific Lisp file. - -You can use @code{term-setup-hook} to override the definitions made by a -terminal-specific file. - -For a related feature, @pxref{Window Systems, window-setup-hook}. -@end defvar - -@node Command-Line Arguments -@subsection Command-Line Arguments -@cindex command-line arguments - - You can use command-line arguments to request various actions when -you start Emacs. Note that the recommended way of using Emacs is to -start it just once, after logging in, and then do all editing in the same -Emacs session (@pxref{Entering Emacs,,, emacs, The GNU Emacs Manual}). -For this reason, you might not use command-line arguments very often; -nonetheless, they can be useful when invoking Emacs from session -scripts or debugging Emacs. This section describes how Emacs -processes command-line arguments. - -@defun command-line -This function parses the command line that Emacs was called with, -processes it, and (amongst other things) loads the user's init file and -displays the startup messages. -@end defun - -@defvar command-line-processed -The value of this variable is @code{t} once the command line has been -processed. - -If you redump Emacs by calling @code{dump-emacs}, you may wish to set -this variable to @code{nil} first in order to cause the new dumped Emacs -to process its new command-line arguments. -@end defvar - -@defvar command-switch-alist -@cindex switches on command line -@cindex options on command line -@cindex command-line options -This variable is an alist of user-defined command-line options and -associated handler functions. By default it is empty, but you can -add elements if you wish. - -A @dfn{command-line option} is an argument on the command line, which -has the form: - -@example --@var{option} -@end example - -The elements of the @code{command-switch-alist} look like this: - -@example -(@var{option} . @var{handler-function}) -@end example - -The @sc{car}, @var{option}, is a string, the name of a command-line -option (not including the initial hyphen). The @var{handler-function} -is called to handle @var{option}, and receives the option name as its -sole argument. - -In some cases, the option is followed in the command line by an -argument. In these cases, the @var{handler-function} can find all the -remaining command-line arguments in the variable -@code{command-line-args-left}. (The entire list of command-line -arguments is in @code{command-line-args}.) - -The command-line arguments are parsed by the @code{command-line-1} -function in the @file{startup.el} file. See also @ref{Emacs -Invocation, , Command Line Arguments for Emacs Invocation, emacs, The -GNU Emacs Manual}. -@end defvar - -@defvar command-line-args -The value of this variable is the list of command-line arguments passed -to Emacs. -@end defvar - -@defvar command-line-args-left -@vindex argv -The value of this variable is the list of command-line arguments that -have not yet been processed. -@c Don't mention this, since it is a "bad name for a dynamically bound variable" -@c @code{argv} is an alias for this. -@end defvar - -@defvar command-line-functions -This variable's value is a list of functions for handling an -unrecognized command-line argument. Each time the next argument to be -processed has no special meaning, the functions in this list are called, -in order of appearance, until one of them returns a non-@code{nil} -value. - -These functions are called with no arguments. They can access the -command-line argument under consideration through the variable -@code{argi}, which is bound temporarily at this point. The remaining -arguments (not including the current one) are in the variable -@code{command-line-args-left}. - -When a function recognizes and processes the argument in @code{argi}, it -should return a non-@code{nil} value to say it has dealt with that -argument. If it has also dealt with some of the following arguments, it -can indicate that by deleting them from @code{command-line-args-left}. - -If all of these functions return @code{nil}, then the argument is treated -as a file name to visit. -@end defvar - -@node Getting Out -@section Getting Out of Emacs -@cindex exiting Emacs - - There are two ways to get out of Emacs: you can kill the Emacs job, -which exits permanently, or you can suspend it, which permits you to -reenter the Emacs process later. (In a graphical environment, you can -of course simply switch to another application without doing anything -special to Emacs, then switch back to Emacs when you want.) - -@menu -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. -@end menu - -@node Killing Emacs -@comment node-name, next, previous, up -@subsection Killing Emacs -@cindex killing Emacs - - Killing Emacs means ending the execution of the Emacs process. -If you started Emacs from a terminal, the parent process normally -resumes control. The low-level primitive for killing Emacs is -@code{kill-emacs}. - -@deffn Command kill-emacs &optional exit-data -This command calls the hook @code{kill-emacs-hook}, then exits the -Emacs process and kills it. - -If @var{exit-data} is an integer, that is used as the exit status of -the Emacs process. (This is useful primarily in batch operation; see -@ref{Batch Mode}.) - -If @var{exit-data} is a string, its contents are stuffed into the -terminal input buffer so that the shell (or whatever program next reads -input) can read them. -@end deffn - -@cindex SIGTERM -@cindex SIGHUP -@cindex SIGINT -@cindex operating system signal - The @code{kill-emacs} function is normally called via the -higher-level command @kbd{C-x C-c} -(@code{save-buffers-kill-terminal}). @xref{Exiting,,, emacs, The GNU -Emacs Manual}. It is also called automatically if Emacs receives a -@code{SIGTERM} or @code{SIGHUP} operating system signal (e.g. when the -controlling terminal is disconnected), or if it receives a -@code{SIGINT} signal while running in batch mode (@pxref{Batch Mode}). - -@defvar kill-emacs-hook -This normal hook is run by @code{kill-emacs}, before it kills Emacs. - -Because @code{kill-emacs} can be called in situations where user -interaction is impossible (e.g. when the terminal is disconnected), -functions on this hook should not attempt to interact with the user. -If you want to interact with the user when Emacs is shutting down, use -@code{kill-emacs-query-functions}, described below. -@end defvar - - When Emacs is killed, all the information in the Emacs process, -aside from files that have been saved, is lost. Because killing Emacs -inadvertently can lose a lot of work, the -@code{save-buffers-kill-terminal} command queries for confirmation if -you have buffers that need saving or subprocesses that are running. -It also runs the abnormal hook @code{kill-emacs-query-functions}: - -@defvar kill-emacs-query-functions -When @code{save-buffers-kill-terminal} is killing Emacs, it calls the -functions in this hook, after asking the standard questions and before -calling @code{kill-emacs}. The functions are called in order of -appearance, with no arguments. Each function can ask for additional -confirmation from the user. If any of them returns @code{nil}, -@code{save-buffers-kill-emacs} does not kill Emacs, and does not run -the remaining functions in this hook. Calling @code{kill-emacs} -directly does not run this hook. -@end defvar - -@node Suspending Emacs -@subsection Suspending Emacs -@cindex suspending Emacs - - On text terminals, it is possible to @dfn{suspend Emacs}, which -means stopping Emacs temporarily and returning control to its superior -process, which is usually the shell. This allows you to resume -editing later in the same Emacs process, with the same buffers, the -same kill ring, the same undo history, and so on. To resume Emacs, -use the appropriate command in the parent shell---most likely -@code{fg}. - -@cindex controlling terminal - Suspending works only on a terminal device from which the Emacs -session was started. We call that device the @dfn{controlling -terminal} of the session. Suspending is not allowed if the -controlling terminal is a graphical terminal. Suspending is usually -not relevant in graphical environments, since you can simply switch to -another application without doing anything special to Emacs. - -@c FIXME? Are there any systems Emacs still supports that do not -@c have SIGTSTP? -@cindex SIGTSTP - Some operating systems (those without @code{SIGTSTP}, or MS-DOS) do -not support suspension of jobs; on these systems, ``suspension'' -actually creates a new shell temporarily as a subprocess of Emacs. -Then you would exit the shell to return to Emacs. - -@deffn Command suspend-emacs &optional string -This function stops Emacs and returns control to the superior process. -If and when the superior process resumes Emacs, @code{suspend-emacs} -returns @code{nil} to its caller in Lisp. - -This function works only on the controlling terminal of the Emacs -session; to relinquish control of other tty devices, use -@code{suspend-tty} (see below). If the Emacs session uses more than -one terminal, you must delete the frames on all the other terminals -before suspending Emacs, or this function signals an error. -@xref{Multiple Terminals}. - -If @var{string} is non-@code{nil}, its characters are sent to Emacs's -superior shell, to be read as terminal input. -@c FIXME? It seems to me that shell does echo STRING. -The characters in @var{string} are not echoed by the superior shell; -only the results appear. - -Before suspending, @code{suspend-emacs} runs the normal hook -@code{suspend-hook}. After the user resumes Emacs, -@code{suspend-emacs} runs the normal hook @code{suspend-resume-hook}. -@xref{Hooks}. - -The next redisplay after resumption will redraw the entire screen, -unless the variable @code{no-redraw-on-reenter} is non-@code{nil}. -@xref{Refresh Screen}. - -Here is an example of how you could use these hooks: - -@smallexample -@group -(add-hook 'suspend-hook - (lambda () (or (y-or-n-p "Really suspend? ") - (error "Suspend canceled")))) -@end group -(add-hook 'suspend-resume-hook (lambda () (message "Resumed!") - (sit-for 2))) -@end smallexample -@c The sit-for prevents the ``nil'' that suspend-emacs returns -@c hiding the message. - -Here is what you would see upon evaluating @code{(suspend-emacs "pwd")}: - -@smallexample -@group ----------- Buffer: Minibuffer ---------- -Really suspend? @kbd{y} ----------- Buffer: Minibuffer ---------- -@end group - -@group ----------- Parent Shell ---------- -bash$ /home/username -bash$ fg -@end group - -@group ----------- Echo Area ---------- -Resumed! -@end group -@end smallexample - -@c FIXME? AFAICS, it is echoed. -Note that @samp{pwd} is not echoed after Emacs is suspended. But it -is read and executed by the shell. -@end deffn - -@defvar suspend-hook -This variable is a normal hook that Emacs runs before suspending. -@end defvar - -@defvar suspend-resume-hook -This variable is a normal hook that Emacs runs on resuming -after a suspension. -@end defvar - -@defun suspend-tty &optional tty -If @var{tty} specifies a terminal device used by Emacs, this function -relinquishes the device and restores it to its prior state. Frames -that used the device continue to exist, but are not updated and Emacs -doesn't read input from them. @var{tty} can be a terminal object, a -frame (meaning the terminal for that frame), or @code{nil} (meaning -the terminal for the selected frame). @xref{Multiple Terminals}. - -If @var{tty} is already suspended, this function does nothing. - -@vindex suspend-tty-functions -This function runs the hook @code{suspend-tty-functions}, passing the -terminal object as an argument to each function. -@end defun - -@defun resume-tty &optional tty -This function resumes the previously suspended terminal device -@var{tty}; where @var{tty} has the same possible values as it does -for @code{suspend-tty}. - -@vindex resume-tty-functions -This function reopens the terminal device, re-initializes it, and -redraws it with that terminal's selected frame. It then runs the -hook @code{resume-tty-functions}, passing the terminal object as an -argument to each function. - -If the same device is already used by another Emacs terminal, this -function signals an error. If @var{tty} is not suspended, this -function does nothing. -@end defun - -@defun controlling-tty-p &optional tty -This function returns non-@code{nil} if @var{tty} is the -controlling terminal of the Emacs session; @var{tty} can be a -terminal object, a frame (meaning the terminal for that frame), or -@code{nil} (meaning the terminal for the selected frame). -@end defun - -@deffn Command suspend-frame -This command @dfn{suspends} a frame. For GUI frames, it calls -@code{iconify-frame} (@pxref{Visibility of Frames}); for frames on -text terminals, it calls either @code{suspend-emacs} or -@code{suspend-tty}, depending on whether the frame is displayed on the -controlling terminal device or not. -@end deffn - -@node System Environment -@section Operating System Environment -@cindex operating system environment - - Emacs provides access to variables in the operating system environment -through various functions. These variables include the name of the -system, the user's @acronym{UID}, and so on. - -@defvar system-configuration -This variable holds the standard GNU configuration name for the -hardware/software configuration of your system, as a string. For -example, a typical value for a 64-bit GNU/Linux system is -@samp{"x86_64-unknown-linux-gnu"}. -@end defvar - -@cindex system type and name -@defvar system-type -The value of this variable is a symbol indicating the type of operating -system Emacs is running on. The possible values are: - -@table @code -@item aix -IBM's AIX. - -@item berkeley-unix -Berkeley BSD and its variants. - -@item cygwin -Cygwin, a Posix layer on top of MS-Windows. - -@item darwin -Darwin (Mac OS X). - -@item gnu -The GNU system (using the GNU kernel, which consists of the HURD and Mach). - -@item gnu/linux -A GNU/Linux system---that is, a variant GNU system, using the Linux -kernel. (These systems are the ones people often call ``Linux'', but -actually Linux is just the kernel, not the whole system.) - -@item gnu/kfreebsd -A GNU (glibc-based) system with a FreeBSD kernel. - -@item hpux -Hewlett-Packard HPUX operating system. - -@item irix -Silicon Graphics Irix system. - -@item ms-dos -Microsoft's DOS. Emacs compiled with DJGPP for MS-DOS binds -@code{system-type} to @code{ms-dos} even when you run it on MS-Windows. - -@item usg-unix-v -AT&T Unix System V. - -@item windows-nt -Microsoft Windows NT, 9X and later. The value of @code{system-type} -is always @code{windows-nt}, e.g. even on Windows 7. - -@end table - -We do not wish to add new symbols to make finer distinctions unless it -is absolutely necessary! In fact, we hope to eliminate some of these -alternatives in the future. If you need to make a finer distinction -than @code{system-type} allows for, you can test -@code{system-configuration}, e.g. against a regexp. -@end defvar - -@defun system-name -This function returns the name of the machine you are running on, as a -string. -@end defun - - The symbol @code{system-name} is a variable as well as a function. In -fact, the function returns whatever value the variable -@code{system-name} currently holds. Thus, you can set the variable -@code{system-name} in case Emacs is confused about the name of your -system. The variable is also useful for constructing frame titles -(@pxref{Frame Titles}). - -@c FIXME seems like this section is not the best place for this option? -@defopt mail-host-address -If this variable is non-@code{nil}, it is used instead of -@code{system-name} for purposes of generating email addresses. For -example, it is used when constructing the default value of -@code{user-mail-address}. @xref{User Identification}. (Since this is -done when Emacs starts up, the value actually used is the one saved when -Emacs was dumped. @xref{Building Emacs}.) -@c FIXME sounds like should probably give this a :set-after and some -@c custom-initialize-delay voodoo. -@end defopt - -@deffn Command getenv var &optional frame -@cindex environment variable access -This function returns the value of the environment variable @var{var}, -as a string. @var{var} should be a string. If @var{var} is undefined -in the environment, @code{getenv} returns @code{nil}. It returns -@samp{""} if @var{var} is set but null. Within Emacs, a list of environment -variables and their values is kept in the variable @code{process-environment}. - -@example -@group -(getenv "USER") - @result{} "lewis" -@end group -@end example - -The shell command @code{printenv} prints all or part of the environment: - -@example -@group -bash$ printenv -PATH=/usr/local/bin:/usr/bin:/bin -USER=lewis -@end group -@group -TERM=xterm -SHELL=/bin/bash -HOME=/home/lewis -@end group -@dots{} -@end example -@end deffn - -@deffn Command setenv variable &optional value substitute -This command sets the value of the environment variable named -@var{variable} to @var{value}. @var{variable} should be a string. -Internally, Emacs Lisp can handle any string. However, normally -@var{variable} should be a valid shell identifier, that is, a sequence -of letters, digits and underscores, starting with a letter or -underscore. Otherwise, errors may occur if subprocesses of Emacs try -to access the value of @var{variable}. If @var{value} is omitted or -@code{nil} (or, interactively, with a prefix argument), @code{setenv} -removes @var{variable} from the environment. Otherwise, @var{value} -should be a string. - -If the optional argument @var{substitute} is non-@code{nil}, Emacs -calls the function @code{substitute-env-vars} to expand any -environment variables in @var{value}. - -@code{setenv} works by modifying @code{process-environment}; binding -that variable with @code{let} is also reasonable practice. - -@code{setenv} returns the new value of @var{variable}, or @code{nil} -if it removed @var{variable} from the environment. -@end deffn - -@defvar process-environment -This variable is a list of strings, each describing one environment -variable. The functions @code{getenv} and @code{setenv} work by means -of this variable. - -@smallexample -@group -process-environment -@result{} ("PATH=/usr/local/bin:/usr/bin:/bin" - "USER=lewis" -@end group -@group - "TERM=xterm" - "SHELL=/bin/bash" - "HOME=/home/lewis" - @dots{}) -@end group -@end smallexample - -If @code{process-environment} contains ``duplicate'' elements that -specify the same environment variable, the first of these elements -specifies the variable, and the other ``duplicates'' are ignored. -@end defvar - -@defvar initial-environment -This variable holds the list of environment variables Emacs inherited -from its parent process when Emacs started. -@end defvar - -@defvar path-separator -This variable holds a string that says which character separates -directories in a search path (as found in an environment variable). Its -value is @code{":"} for Unix and GNU systems, and @code{";"} for MS systems. -@end defvar - -@defun parse-colon-path path -This function takes a search path string such as the value of -the @env{PATH} environment variable, and splits it at the separators, -returning a list of directory names. @code{nil} in this list means -the current directory. Although the function's name says -``colon'', it actually uses the value of @code{path-separator}. - -@example -(parse-colon-path ":/foo:/bar") - @result{} (nil "/foo/" "/bar/") -@end example -@end defun - -@defvar invocation-name -This variable holds the program name under which Emacs was invoked. The -value is a string, and does not include a directory name. -@end defvar - -@defvar invocation-directory -This variable holds the directory from which the Emacs executable was -invoked, or @code{nil} if that directory cannot be determined. -@end defvar - -@defvar installation-directory -If non-@code{nil}, this is a directory within which to look for the -@file{lib-src} and @file{etc} subdirectories. In an installed Emacs, -it is normally @code{nil}. It is non-@code{nil} -when Emacs can't find those directories in their standard installed -locations, but can find them in a directory related somehow to the one -containing the Emacs executable (i.e., @code{invocation-directory}). -@end defvar - -@defun load-average &optional use-float -This function returns the current 1-minute, 5-minute, and 15-minute -system load averages, in a list. The load average indicates the -number of processes trying to run on the system. - -By default, the values are integers that are 100 times the system load -averages, but if @var{use-float} is non-@code{nil}, then they are -returned as floating point numbers without multiplying by 100. - -If it is impossible to obtain the load average, this function signals -an error. On some platforms, access to load averages requires -installing Emacs as setuid or setgid so that it can read kernel -information, and that usually isn't advisable. -@c FIXME which platforms are these? Are they still relevant? - -If the 1-minute load average is available, but the 5- or 15-minute -averages are not, this function returns a shortened list containing -the available averages. - -@example -@group -(load-average) - @result{} (169 48 36) -@end group -@group -(load-average t) - @result{} (1.69 0.48 0.36) -@end group -@end example - -The shell command @code{uptime} returns similar information. -@end defun - -@defun emacs-pid -This function returns the process @acronym{ID} of the Emacs process, -as an integer. -@end defun - -@defvar tty-erase-char -This variable holds the erase character that was selected -in the system's terminal driver, before Emacs was started. -@c FIXME? Seems untrue since 23.1. For me, it is 0. -@c The value is @code{nil} if Emacs is running under a window system. -@end defvar - -@node User Identification -@section User Identification -@cindex user identification - -@defvar init-file-user -This variable says which user's init files should be used by -Emacs---or @code{nil} if none. @code{""} stands for the user who -originally logged in. The value reflects command-line options such as -@samp{-q} or @samp{-u @var{user}}. - -Lisp packages that load files of customizations, or any other sort of -user profile, should obey this variable in deciding where to find it. -They should load the profile of the user name found in this variable. -If @code{init-file-user} is @code{nil}, meaning that the @samp{-q} -option was used, then Lisp packages should not load any customization -files or user profile. -@end defvar - -@defopt user-mail-address -This holds the nominal email address of the user who is using Emacs. -Emacs normally sets this variable to a default value after reading your -init files, but not if you have already set it. So you can set the -variable to some other value in your init file if you do not -want to use the default value. -@end defopt - -@defun user-login-name &optional uid -This function returns the name under which the user is logged in. -It uses the environment variables @env{LOGNAME} or @env{USER} if -either is set. Otherwise, the value is based on the effective -@acronym{UID}, not the real @acronym{UID}. - -If you specify @var{uid} (a number), the result is the user name that -corresponds to @var{uid}, or @code{nil} if there is no such user. -@end defun - -@defun user-real-login-name -This function returns the user name corresponding to Emacs's real -@acronym{UID}. This ignores the effective @acronym{UID}, and the -environment variables @env{LOGNAME} and @env{USER}. -@end defun - -@defun user-full-name &optional uid -This function returns the full name of the logged-in user---or the value -of the environment variable @env{NAME}, if that is set. - -If the Emacs process's user-id does not correspond to any known user (and -provided @code{NAME} is not set), the result is @code{"unknown"}. - -If @var{uid} is non-@code{nil}, then it should be a number (a user-id) -or a string (a login name). Then @code{user-full-name} returns the full -name corresponding to that user-id or login name. If you specify a -user-id or login name that isn't defined, it returns @code{nil}. -@end defun - -@vindex user-full-name -@vindex user-real-login-name -@vindex user-login-name - The symbols @code{user-login-name}, @code{user-real-login-name} and -@code{user-full-name} are variables as well as functions. The functions -return the same values that the variables hold. These variables allow -you to ``fake out'' Emacs by telling the functions what to return. The -variables are also useful for constructing frame titles (@pxref{Frame -Titles}). - -@defun user-real-uid -This function returns the real @acronym{UID} of the user. -The value may be a floating point number, in the (unlikely) event that -the UID is too large to fit in a Lisp integer. -@end defun - -@defun user-uid -This function returns the effective @acronym{UID} of the user. -The value may be a floating point number. -@end defun - -@node Time of Day -@section Time of Day - - This section explains how to determine the current time and time -zone. - -@cindex epoch - Most of these functions represent time as a list of either three -integers, @code{(@var{sec-high} @var{sec-low} @var{microsec})}, or of -two integers, @code{(@var{sec-high} @var{sec-low})}. The integers -@var{sec-high} and @var{sec-low} give the high and low bits of an -integer number of seconds. This integer number, -@ifnottex -@var{high} * 2**16 + @var{low}, -@end ifnottex -@tex -$high*2^{16}+low$, -@end tex -is the number of seconds from the @dfn{epoch} (0:00 January 1, 1970 -UTC) to the specified time. The third list element @var{microsec}, if -present, gives the number of microseconds from the start of that -second to the specified time. - - The return value of @code{current-time} represents time using three -integers, while the timestamps in the return value of -@code{file-attributes} use two integers (@pxref{Definition of -file-attributes}). In function arguments, e.g.@: the @var{time-value} -argument to @code{current-time-string}, both two- and three-integer -lists are accepted. You can convert times from the list -representation into standard human-readable strings using -@code{current-time}, or to other forms using the @code{decode-time} -and @code{format-time-string} functions documented in the following -sections. - -@defun current-time-string &optional time-value -This function returns the current time and date as a human-readable -string. The format of the string is unvarying; the number of -characters used for each part is always the same, so you can reliably -use @code{substring} to extract pieces of it. You should count -characters from the beginning of the string rather than from the end, -as additional information may some day be added at the end. - -The argument @var{time-value}, if given, specifies a time to format -(represented as a list of integers), instead of the current time. - -@example -@group -(current-time-string) - @result{} "Wed Oct 14 22:21:05 1987" -@end group -@end example -@end defun - -@defun current-time -This function returns the current time, represented as a list of three -integers @code{(@var{sec-high} @var{sec-low} @var{microsec})}. On -systems with only one-second time resolutions, @var{microsec} is 0. -@end defun - -@defun float-time &optional time-value -This function returns the current time as a floating-point number of -seconds since the epoch. The optional argument @var{time-value}, if -given, specifies a time (represented as a list of integers) to convert -instead of the current time. - -@emph{Warning}: Since the result is floating point, it may not be -exact. Do not use this function if precise time stamps are required. -@end defun - -@defun current-time-zone &optional time-value -This function returns a list describing the time zone that the user is -in. - -The value has the form @code{(@var{offset} @var{name})}. Here -@var{offset} is an integer giving the number of seconds ahead of UTC -(east of Greenwich). A negative value means west of Greenwich. The -second element, @var{name}, is a string giving the name of the time -zone. Both elements change when daylight saving time begins or ends; -if the user has specified a time zone that does not use a seasonal time -adjustment, then the value is constant through time. - -If the operating system doesn't supply all the information necessary to -compute the value, the unknown elements of the list are @code{nil}. - -The argument @var{time-value}, if given, specifies a time (represented -as a list of integers) to analyze instead of the current time. -@end defun - -The current time zone is determined by the @env{TZ} environment -variable. @xref{System Environment}. For example, you can tell Emacs -to use universal time with @code{(setenv "TZ" "UTC0")}. If @env{TZ} -is not in the environment, Emacs uses a platform-dependent default -time zone. - -@node Time Conversion -@section Time Conversion - - These functions convert time values (lists of two or three integers, -as explained in the previous section) into calendrical information and -vice versa. - - Many 32-bit operating systems are limited to time values containing -32 bits of information; these systems typically handle only the times -from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. -However, 64-bit and some 32-bit operating systems have larger time -values, and can represent times far in the past or future. - - Time conversion functions always use the Gregorian calendar, even -for dates before the Gregorian calendar was introduced. Year numbers -count the number of years since the year 1 B.C., and do not skip zero -as traditional Gregorian years do; for example, the year number -@minus{}37 represents the Gregorian year 38 B.C@. - -@defun decode-time &optional time -This function converts a time value into calendrical information. If -you don't specify @var{time}, it decodes the current time. The return -value is a list of nine elements, as follows: - -@example -(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) -@end example - -Here is what the elements mean: - -@table @var -@item seconds -The number of seconds past the minute, as an integer between 0 and 59. -On some operating systems, this is 60 for leap seconds. -@item minutes -The number of minutes past the hour, as an integer between 0 and 59. -@item hour -The hour of the day, as an integer between 0 and 23. -@item day -The day of the month, as an integer between 1 and 31. -@item month -The month of the year, as an integer between 1 and 12. -@item year -The year, an integer typically greater than 1900. -@item dow -The day of week, as an integer between 0 and 6, where 0 stands for -Sunday. -@item dst -@code{t} if daylight saving time is effect, otherwise @code{nil}. -@item zone -An integer indicating the time zone, as the number of seconds east of -Greenwich. -@end table - -@strong{Common Lisp Note:} Common Lisp has different meanings for -@var{dow} and @var{zone}. -@end defun - -@defun encode-time seconds minutes hour day month year &optional zone -This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a time value. For the meanings of the -arguments, see the table above under @code{decode-time}. - -Year numbers less than 100 are not treated specially. If you want them -to stand for years above 1900, or years above 2000, you must alter them -yourself before you call @code{encode-time}. - -The optional argument @var{zone} defaults to the current time zone and -its daylight saving time rules. If specified, it can be either a list -(as you would get from @code{current-time-zone}), a string as in the -@env{TZ} environment variable, @code{t} for Universal Time, or an -integer (as you would get from @code{decode-time}). The specified -zone is used without any further alteration for daylight saving time. - -If you pass more than seven arguments to @code{encode-time}, the first -six are used as @var{seconds} through @var{year}, the last argument is -used as @var{zone}, and the arguments in between are ignored. This -feature makes it possible to use the elements of a list returned by -@code{decode-time} as the arguments to @code{encode-time}, like this: - -@example -(apply 'encode-time (decode-time @dots{})) -@end example - -You can perform simple date arithmetic by using out-of-range values for -the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month} -arguments; for example, day 0 means the day preceding the given month. - -The operating system puts limits on the range of possible time values; -if you try to encode a time that is out of range, an error results. -For instance, years before 1970 do not work on some systems; -on others, years as early as 1901 do work. -@end defun - -@node Time Parsing -@section Parsing and Formatting Times - - These functions convert time values (lists of two or three integers) -to text in a string, and vice versa. - -@defun date-to-time string -This function parses the time-string @var{string} and returns the -corresponding time value. -@end defun - -@defun format-time-string format-string &optional time universal -This function converts @var{time} (or the current time, if @var{time} is -omitted) to a string according to @var{format-string}. The argument -@var{format-string} may contain @samp{%}-sequences which say to -substitute parts of the time. Here is a table of what the -@samp{%}-sequences mean: - -@table @samp -@item %a -This stands for the abbreviated name of the day of week. -@item %A -This stands for the full name of the day of week. -@item %b -This stands for the abbreviated name of the month. -@item %B -This stands for the full name of the month. -@item %c -This is a synonym for @samp{%x %X}. -@item %C -This has a locale-specific meaning. In the default locale (named C), it -is equivalent to @samp{%A, %B %e, %Y}. -@item %d -This stands for the day of month, zero-padded. -@item %D -This is a synonym for @samp{%m/%d/%y}. -@item %e -This stands for the day of month, blank-padded. -@item %h -This is a synonym for @samp{%b}. -@item %H -This stands for the hour (00-23). -@item %I -This stands for the hour (01-12). -@item %j -This stands for the day of the year (001-366). -@item %k -This stands for the hour (0-23), blank padded. -@item %l -This stands for the hour (1-12), blank padded. -@item %m -This stands for the month (01-12). -@item %M -This stands for the minute (00-59). -@item %n -This stands for a newline. -@item %N -This stands for the nanoseconds (000000000-999999999). To ask for -fewer digits, use @samp{%3N} for milliseconds, @samp{%6N} for -microseconds, etc. Any excess digits are discarded, without rounding. -Currently Emacs time stamps are at best microsecond resolution so the -last three digits generated by plain @samp{%N} are always zero. -@item %p -This stands for @samp{AM} or @samp{PM}, as appropriate. -@item %r -This is a synonym for @samp{%I:%M:%S %p}. -@item %R -This is a synonym for @samp{%H:%M}. -@item %S -This stands for the seconds (00-59). -@item %t -This stands for a tab character. -@item %T -This is a synonym for @samp{%H:%M:%S}. -@item %U -This stands for the week of the year (01-52), assuming that weeks -start on Sunday. -@item %w -This stands for the numeric day of week (0-6). Sunday is day 0. -@item %W -This stands for the week of the year (01-52), assuming that weeks -start on Monday. -@item %x -This has a locale-specific meaning. In the default locale (named -@samp{C}), it is equivalent to @samp{%D}. -@item %X -This has a locale-specific meaning. In the default locale (named -@samp{C}), it is equivalent to @samp{%T}. -@item %y -This stands for the year without century (00-99). -@item %Y -This stands for the year with century. -@item %Z -This stands for the time zone abbreviation (e.g., @samp{EST}). -@item %z -This stands for the time zone numerical offset (e.g., @samp{-0500}). -@end table - -You can also specify the field width and type of padding for any of -these @samp{%}-sequences. This works as in @code{printf}: you write -the field width as digits in the middle of a @samp{%}-sequences. If you -start the field width with @samp{0}, it means to pad with zeros. If you -start the field width with @samp{_}, it means to pad with spaces. - -For example, @samp{%S} specifies the number of seconds since the minute; -@samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to -pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros, -because that is how @samp{%S} normally pads to two positions. - -The characters @samp{E} and @samp{O} act as modifiers when used between -@samp{%} and one of the letters in the table above. @samp{E} specifies -using the current locale's ``alternative'' version of the date and time. -In a Japanese locale, for example, @code{%Ex} might yield a date format -based on the Japanese Emperors' reigns. @samp{E} is allowed in -@samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and -@samp{%EY}. - -@samp{O} means to use the current locale's ``alternative'' -representation of numbers, instead of the ordinary decimal digits. This -is allowed with most letters, all the ones that output numbers. - -If @var{universal} is non-@code{nil}, that means to describe the time as -Universal Time; @code{nil} means describe it using what Emacs believes -is the local time zone (see @code{current-time-zone}). - -This function uses the C library function @code{strftime} -(@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference -Manual}) to do most of the work. In order to communicate with that -function, it first encodes its argument using the coding system -specified by @code{locale-coding-system} (@pxref{Locales}); after -@code{strftime} returns the resulting string, -@code{format-time-string} decodes the string using that same coding -system. -@end defun - -@defun seconds-to-time seconds -This function converts @var{seconds}, a floating point number of -seconds since the epoch, to a time value and returns that. To perform -the inverse conversion, use @code{float-time}. -@end defun - -@defun format-seconds format-string seconds -This function converts its argument @var{seconds} into a string of -years, days, hours, etc., according to @var{format-string}. The -argument @var{format-string} may contain @samp{%}-sequences which -control the conversion. Here is a table of what the -@samp{%}-sequences mean: - -@table @samp -@item %y -@itemx %Y -The integer number of 365-day years. -@item %d -@itemx %D -The integer number of days. -@item %h -@itemx %H -The integer number of hours. -@item %m -@itemx %M -The integer number of minutes. -@item %s -@itemx %S -The integer number of seconds. -@item %z -Non-printing control flag. When it is used, other specifiers must be -given in the order of decreasing size, i.e.@: years before days, hours -before minutes, etc. Nothing will be produced in the result string to -the left of @samp{%z} until the first non-zero conversion is -encountered. For example, the default format used by -@code{emacs-uptime} (@pxref{Processor Run Time, emacs-uptime}) -@w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds -will always be produced, but years, days, hours, and minutes will only -be shown if they are non-zero. -@item %% -Produces a literal @samp{%}. -@end table - -Upper-case format sequences produce the units in addition to the -numbers, lower-case formats produce only the numbers. - -You can also specify the field width by following the @samp{%} with a -number; shorter numbers will be padded with blanks. An optional -period before the width requests zero-padding instead. For example, -@code{"%.3Y"} might produce @code{"004 years"}. - -@emph{Warning:} This function works only with values of @var{seconds} -that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics, -most-positive-fixnum}). -@end defun - -@node Processor Run Time -@section Processor Run time -@cindex processor run time -@cindex Emacs process run time - - Emacs provides several functions and primitives that return time, -both elapsed and processor time, used by the Emacs process. - -@deffn Command emacs-uptime &optional format -This function returns a string representing the Emacs -@dfn{uptime}---the elapsed wall-clock time this instance of Emacs is -running. The string is formatted by @code{format-seconds} according -to the optional argument @var{format}. For the available format -descriptors, see @ref{Time Parsing, format-seconds}. If @var{format} -is @code{nil} or omitted, it defaults to @code{"%Y, %D, %H, %M, -%z%S"}. - -When called interactively, it prints the uptime in the echo area. -@end deffn - -@defun get-internal-run-time -This function returns the processor run time used by Emacs as a list -of three integers: @code{(@var{high} @var{low} @var{microsec})}. The -integers @var{high} and @var{low} combine to give the number of -seconds, which is -@ifnottex -@var{high} * 2**16 + @var{low}. -@end ifnottex -@tex -$high*2^{16}+low$. -@end tex - -The third element, @var{microsec}, gives the microseconds (or 0 for -systems that return time with the resolution of only one second). - -Note that the time returned by this function excludes the time Emacs -was not using the processor, and if the Emacs process has several -threads, the returned value is the sum of the processor times used up -by all Emacs threads. - -If the system doesn't provide a way to determine the processor run -time, @code{get-internal-run-time} returns the same time as -@code{current-time}. -@end defun - -@deffn Command emacs-init-time -This function returns the duration of the Emacs initialization -(@pxref{Startup Summary}) in seconds, as a string. When called -interactively, it prints the duration in the echo area. -@end deffn - -@node Time Calculations -@section Time Calculations - - These functions perform calendrical computations using time values -(the kind of list that @code{current-time} returns). - -@defun time-less-p t1 t2 -This returns @code{t} if time value @var{t1} is less than time value -@var{t2}. -@end defun - -@defun time-subtract t1 t2 -This returns the time difference @var{t1} @minus{} @var{t2} between -two time values, in the same format as a time value. -@end defun - -@defun time-add t1 t2 -This returns the sum of two time values, one of which ought to -represent a time difference rather than a point in time. -Here is how to add a number of seconds to a time value: - -@example -(time-add @var{time} (seconds-to-time @var{seconds})) -@end example -@end defun - -@defun time-to-days time -This function returns the number of days between the beginning of year -1 and @var{time}. -@end defun - -@defun time-to-day-in-year time -This returns the day number within the year corresponding to @var{time}. -@end defun - -@defun date-leap-year-p year -This function returns @code{t} if @var{year} is a leap year. -@end defun - -@node Timers -@section Timers for Delayed Execution -@cindex timer - - You can set up a @dfn{timer} to call a function at a specified -future time or after a certain length of idleness. - - Emacs cannot run timers at any arbitrary point in a Lisp program; it -can run them only when Emacs could accept output from a subprocess: -namely, while waiting or inside certain primitive functions such as -@code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a -timer's execution may be delayed if Emacs is busy. However, the time of -execution is very precise if Emacs is idle. - - Emacs binds @code{inhibit-quit} to @code{t} before calling the timer -function, because quitting out of many timer functions can leave -things in an inconsistent state. This is normally unproblematical -because most timer functions don't do a lot of work. Indeed, for a -timer to call a function that takes substantial time to run is likely -to be annoying. If a timer function needs to allow quitting, it -should use @code{with-local-quit} (@pxref{Quitting}). For example, if -a timer function calls @code{accept-process-output} to receive output -from an external process, that call should be wrapped inside -@code{with-local-quit}, to ensure that @kbd{C-g} works if the external -process hangs. - - It is usually a bad idea for timer functions to alter buffer -contents. When they do, they usually should call @code{undo-boundary} -both before and after changing the buffer, to separate the timer's -changes from user commands' changes and prevent a single undo entry -from growing to be quite large. - - Timer functions should also avoid calling functions that cause Emacs -to wait, such as @code{sit-for} (@pxref{Waiting}). This can lead to -unpredictable effects, since other timers (or even the same timer) can -run while waiting. If a timer function needs to perform an action -after a certain time has elapsed, it can do this by scheduling a new -timer. - - If a timer function calls functions that can change the match data, -it should save and restore the match data. @xref{Saving Match Data}. - -@deffn Command run-at-time time repeat function &rest args -This sets up a timer that calls the function @var{function} with -arguments @var{args} at time @var{time}. If @var{repeat} is a number -(integer or floating point), the timer is scheduled to run again every -@var{repeat} seconds after @var{time}. If @var{repeat} is @code{nil}, -the timer runs only once. - -@var{time} may specify an absolute or a relative time. - -Absolute times may be specified using a string with a limited variety -of formats, and are taken to be times @emph{today}, even if already in -the past. The recognized forms are @samp{@var{xxxx}}, -@samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time), -and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm}, -@samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am}, -@samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or -@samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon -to separate the hour and minute parts. - -To specify a relative time as a string, use numbers followed by units. -For example: - -@table @samp -@item 1 min -denotes 1 minute from now. -@item 1 min 5 sec -denotes 65 seconds from now. -@item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year -denotes exactly 103 months, 123 days, and 10862 seconds from now. -@end table - -For relative time values, Emacs considers a month to be exactly thirty -days, and a year to be exactly 365.25 days. - -Not all convenient formats are strings. If @var{time} is a number -(integer or floating point), that specifies a relative time measured in -seconds. The result of @code{encode-time} can also be used to specify -an absolute value for @var{time}. - -In most cases, @var{repeat} has no effect on when @emph{first} call -takes place---@var{time} alone specifies that. There is one exception: -if @var{time} is @code{t}, then the timer runs whenever the time is a -multiple of @var{repeat} seconds after the epoch. This is useful for -functions like @code{display-time}. - -The function @code{run-at-time} returns a timer value that identifies -the particular scheduled future action. You can use this value to call -@code{cancel-timer} (see below). -@end deffn - - A repeating timer nominally ought to run every @var{repeat} seconds, -but remember that any invocation of a timer can be late. Lateness of -one repetition has no effect on the scheduled time of the next -repetition. For instance, if Emacs is busy computing for long enough -to cover three scheduled repetitions of the timer, and then starts to -wait, it will immediately call the timer function three times in -immediate succession (presuming no other timers trigger before or -between them). If you want a timer to run again no less than @var{n} -seconds after the last invocation, don't use the @var{repeat} argument. -Instead, the timer function should explicitly reschedule the timer. - -@defvar timer-max-repeats -This variable's value specifies the maximum number of times to repeat -calling a timer function in a row, when many previously scheduled -calls were unavoidably delayed. -@end defvar - -@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{} -Execute @var{body}, but give up after @var{seconds} seconds. If -@var{body} finishes before the time is up, @code{with-timeout} returns -the value of the last form in @var{body}. If, however, the execution of -@var{body} is cut short by the timeout, then @code{with-timeout} -executes all the @var{timeout-forms} and returns the value of the last -of them. - -This macro works by setting a timer to run after @var{seconds} seconds. If -@var{body} finishes before that time, it cancels the timer. If the -timer actually runs, it terminates execution of @var{body}, then -executes @var{timeout-forms}. - -Since timers can run within a Lisp program only when the program calls a -primitive that can wait, @code{with-timeout} cannot stop executing -@var{body} while it is in the midst of a computation---only when it -calls one of those primitives. So use @code{with-timeout} only with a -@var{body} that waits for input, not one that does a long computation. -@end defmac - - The function @code{y-or-n-p-with-timeout} provides a simple way to use -a timer to avoid waiting too long for an answer. @xref{Yes-or-No -Queries}. - -@defun cancel-timer timer -This cancels the requested action for @var{timer}, which should be a -timer---usually, one previously returned by @code{run-at-time} or -@code{run-with-idle-timer}. This cancels the effect of that call to -one of these functions; the arrival of the specified time will not -cause anything special to happen. -@end defun - -@node Idle Timers -@section Idle Timers - - Here is how to set up a timer that runs when Emacs is idle for a -certain length of time. Aside from how to set them up, idle timers -work just like ordinary timers. - -@deffn Command run-with-idle-timer secs repeat function &rest args -Set up a timer which runs the next time Emacs is idle for @var{secs} -seconds. The value of @var{secs} may be an integer or a floating -point number; a value of the type returned by @code{current-idle-time} -is also allowed. - -If @var{repeat} is @code{nil}, the timer runs just once, the first time -Emacs remains idle for a long enough time. More often @var{repeat} is -non-@code{nil}, which means to run the timer @emph{each time} Emacs -remains idle for @var{secs} seconds. - -The function @code{run-with-idle-timer} returns a timer value which you -can use in calling @code{cancel-timer} (@pxref{Timers}). -@end deffn - -@cindex idleness - Emacs becomes @dfn{idle} when it starts waiting for user input, and -it remains idle until the user provides some input. If a timer is set -for five seconds of idleness, it runs approximately five seconds after -Emacs first becomes idle. Even if @var{repeat} is non-@code{nil}, -this timer will not run again as long as Emacs remains idle, because -the duration of idleness will continue to increase and will not go -down to five seconds again. - - Emacs can do various things while idle: garbage collect, autosave or -handle data from a subprocess. But these interludes during idleness do -not interfere with idle timers, because they do not reset the clock of -idleness to zero. An idle timer set for 600 seconds will run when ten -minutes have elapsed since the last user command was finished, even if -subprocess output has been accepted thousands of times within those ten -minutes, and even if there have been garbage collections and autosaves. - - When the user supplies input, Emacs becomes non-idle while executing the -input. Then it becomes idle again, and all the idle timers that are -set up to repeat will subsequently run another time, one by one. - -@defun current-idle-time -If Emacs is idle, this function returns the length of time Emacs has -been idle, as a list of three integers: @code{(@var{sec-high} -@var{sec-low} @var{microsec})}, where @var{high} and @var{low} are the -high and low bits for the number of seconds and @var{microsec} is the -additional number of microseconds (@pxref{Time of Day}). - -When Emacs is not idle, @code{current-idle-time} returns @code{nil}. -This is a convenient way to test whether Emacs is idle. - -The main use of this function is when an idle timer function wants to -``take a break'' for a while. It can set up another idle timer to -call the same function again, after a few seconds more idleness. -Here's an example: - -@smallexample -(defvar resume-timer nil - "Timer that `timer-function' used to reschedule itself, or nil.") - -(defun timer-function () - ;; @r{If the user types a command while @code{resume-timer}} - ;; @r{is active, the next time this function is called from} - ;; @r{its main idle timer, deactivate @code{resume-timer}.} - (when resume-timer - (cancel-timer resume-timer)) - ...@var{do the work for a while}... - (when @var{taking-a-break} - (setq resume-timer - (run-with-idle-timer - ;; Compute an idle time @var{break-length} - ;; more than the current value. - (time-add (current-idle-time) - (seconds-to-time @var{break-length})) - nil - 'timer-function)))) -@end smallexample -@end defun - - Do not write an idle timer function containing a loop which does a -certain amount of processing each time around, and exits when -@code{(input-pending-p)} is non-@code{nil}. This approach seems very -natural but has two problems: - -@itemize -@item -It blocks out all process output (since Emacs accepts process output -only while waiting). - -@item -It blocks out any idle timers that ought to run during that time. -@end itemize - -@noindent -The correct approach is for the idle timer to reschedule itself after -a brief pause, using the method in the @code{timer-function} example -above. - -@node Terminal Input -@section Terminal Input -@cindex terminal input - - This section describes functions and variables for recording or -manipulating terminal input. See @ref{Display}, for related -functions. - -@menu -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. -@end menu - -@node Input Modes -@subsection Input Modes -@cindex input modes -@cindex terminal input modes - -@defun set-input-mode interrupt flow meta &optional quit-char -This function sets the mode for reading keyboard input. If -@var{interrupt} is non-null, then Emacs uses input interrupts. If it is -@code{nil}, then it uses @sc{cbreak} mode. The default setting is -system-dependent. Some systems always use @sc{cbreak} mode regardless -of what is specified. - -When Emacs communicates directly with X, it ignores this argument and -uses interrupts if that is the way it knows how to communicate. - -If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} -(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This -has no effect except in @sc{cbreak} mode. - -@c Emacs 19 feature -The argument @var{meta} controls support for input character codes -above 127. If @var{meta} is @code{t}, Emacs converts characters with -the 8th bit set into Meta characters. If @var{meta} is @code{nil}, -Emacs disregards the 8th bit; this is necessary when the terminal uses -it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil}, -Emacs uses all 8 bits of input unchanged. This is good for terminals -that use 8-bit character sets. - -@c Emacs 19 feature -If @var{quit-char} is non-@code{nil}, it specifies the character to -use for quitting. Normally this character is @kbd{C-g}. -@xref{Quitting}. -@end defun - -The @code{current-input-mode} function returns the input mode settings -Emacs is currently using. - -@c Emacs 19 feature -@defun current-input-mode -This function returns the current mode for reading keyboard input. It -returns a list, corresponding to the arguments of @code{set-input-mode}, -of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in -which: -@table @var -@item interrupt -is non-@code{nil} when Emacs is using interrupt-driven input. If -@code{nil}, Emacs is using @sc{cbreak} mode. -@item flow -is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s}) -flow control for output to the terminal. This value is meaningful only -when @var{interrupt} is @code{nil}. -@item meta -is @code{t} if Emacs treats the eighth bit of input characters as -the meta bit; @code{nil} means Emacs clears the eighth bit of every -input character; any other value means Emacs uses all eight bits as the -basic character code. -@item quit -is the character Emacs currently uses for quitting, usually @kbd{C-g}. -@end table -@end defun - -@node Recording Input -@subsection Recording Input -@cindex recording input - -@defun recent-keys -This function returns a vector containing the last 300 input events from -the keyboard or mouse. All input events are included, whether or not -they were used as parts of key sequences. Thus, you always get the last -100 input events, not counting events generated by keyboard macros. -(These are excluded because they are less interesting for debugging; it -should be enough to see the events that invoked the macros.) - -A call to @code{clear-this-command-keys} (@pxref{Command Loop Info}) -causes this function to return an empty vector immediately afterward. -@end defun - -@deffn Command open-dribble-file filename -@cindex dribble file -This function opens a @dfn{dribble file} named @var{filename}. When a -dribble file is open, each input event from the keyboard or mouse (but -not those from keyboard macros) is written in that file. A -non-character event is expressed using its printed representation -surrounded by @samp{<@dots{}>}. - -You close the dribble file by calling this function with an argument -of @code{nil}. - -This function is normally used to record the input necessary to -trigger an Emacs bug, for the sake of a bug report. - -@example -@group -(open-dribble-file "~/dribble") - @result{} nil -@end group -@end example -@end deffn - - See also the @code{open-termscript} function (@pxref{Terminal Output}). - -@node Terminal Output -@section Terminal Output -@cindex terminal output - - The terminal output functions send output to a text terminal, or keep -track of output sent to the terminal. The variable @code{baud-rate} -tells you what Emacs thinks is the output speed of the terminal. - -@defopt baud-rate -This variable's value is the output speed of the terminal, as far as -Emacs knows. Setting this variable does not change the speed of actual -data transmission, but the value is used for calculations such as -padding. - - It also affects decisions about whether to scroll part of the -screen or repaint on text terminals. @xref{Forcing Redisplay}, -for the corresponding functionality on graphical terminals. - -The value is measured in baud. -@end defopt - - If you are running across a network, and different parts of the -network work at different baud rates, the value returned by Emacs may be -different from the value used by your local terminal. Some network -protocols communicate the local terminal speed to the remote machine, so -that Emacs and other programs can get the proper value, but others do -not. If Emacs has the wrong value, it makes decisions that are less -than optimal. To fix the problem, set @code{baud-rate}. - -@defun send-string-to-terminal string &optional terminal -This function sends @var{string} to @var{terminal} without alteration. -Control characters in @var{string} have terminal-dependent effects. -This function operates only on text terminals. @var{terminal} may be -a terminal object, a frame, or @code{nil} for the selected frame's -terminal. In batch mode, @var{string} is sent to @code{stdout} when -@var{terminal} is @code{nil}. - -One use of this function is to define function keys on terminals that -have downloadable function key definitions. For example, this is how (on -certain terminals) to define function key 4 to move forward four -characters (by transmitting the characters @kbd{C-u C-f} to the -computer): - -@example -@group -(send-string-to-terminal "\eF4\^U\^F") - @result{} nil -@end group -@end example -@end defun - -@deffn Command open-termscript filename -@cindex termscript file -This function is used to open a @dfn{termscript file} that will record -all the characters sent by Emacs to the terminal. It returns -@code{nil}. Termscript files are useful for investigating problems -where Emacs garbles the screen, problems that are due to incorrect -Termcap entries or to undesirable settings of terminal options more -often than to actual Emacs bugs. Once you are certain which characters -were actually output, you can determine reliably whether they correspond -to the Termcap specifications in use. - -You close the termscript file by calling this function with an -argument of @code{nil}. - -See also @code{open-dribble-file} in @ref{Recording Input}. - -@example -@group -(open-termscript "../junk/termscript") - @result{} nil -@end group -@end example -@end deffn - -@node Sound Output -@section Sound Output -@cindex sound - - To play sound using Emacs, use the function @code{play-sound}. Only -certain systems are supported; if you call @code{play-sound} on a -system which cannot really do the job, it gives an error. - - The sound must be stored as a file in RIFF-WAVE format (@samp{.wav}) -or Sun Audio format (@samp{.au}). - -@defun play-sound sound -This function plays a specified sound. The argument, @var{sound}, has -the form @code{(sound @var{properties}...)}, where the @var{properties} -consist of alternating keywords (particular symbols recognized -specially) and values corresponding to them. - -Here is a table of the keywords that are currently meaningful in -@var{sound}, and their meanings: - -@table @code -@item :file @var{file} -This specifies the file containing the sound to play. -If the file name is not absolute, it is expanded against -the directory @code{data-directory}. - -@item :data @var{data} -This specifies the sound to play without need to refer to a file. The -value, @var{data}, should be a string containing the same bytes as a -sound file. We recommend using a unibyte string. - -@item :volume @var{volume} -This specifies how loud to play the sound. It should be a number in the -range of 0 to 1. The default is to use whatever volume has been -specified before. - -@item :device @var{device} -This specifies the system device on which to play the sound, as a -string. The default device is system-dependent. -@end table - -Before actually playing the sound, @code{play-sound} -calls the functions in the list @code{play-sound-functions}. -Each function is called with one argument, @var{sound}. -@end defun - -@deffn Command play-sound-file file &optional volume device -This function is an alternative interface to playing a sound @var{file} -specifying an optional @var{volume} and @var{device}. -@end deffn - -@defvar play-sound-functions -A list of functions to be called before playing a sound. Each function -is called with one argument, a property list that describes the sound. -@end defvar - -@node X11 Keysyms -@section Operating on X11 Keysyms -@cindex X11 keysyms - -To define system-specific X11 keysyms, set the variable -@code{system-key-alist}. - -@defvar system-key-alist -This variable's value should be an alist with one element for each -system-specific keysym. Each element has the form @code{(@var{code} -. @var{symbol})}, where @var{code} is the numeric keysym code (not -including the ``vendor specific'' bit, -@ifnottex --2**28), -@end ifnottex -@tex -$-2^{28}$), -@end tex -and @var{symbol} is the name for the function key. - -For example @code{(168 . mute-acute)} defines a system-specific key (used -by HP X servers) whose numeric code is -@ifnottex --2**28 -@end ifnottex -@tex -$-2^{28}$ -@end tex -+ 168. - -It is not crucial to exclude from the alist the keysyms of other X -servers; those do no harm, as long as they don't conflict with the ones -used by the X server actually in use. - -The variable is always local to the current terminal, and cannot be -buffer-local. @xref{Multiple Terminals}. -@end defvar - -You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables: - -@defvar x-alt-keysym -@defvarx x-meta-keysym -@defvarx x-hyper-keysym -@defvarx x-super-keysym -The name of the keysym that should stand for the Alt modifier -(respectively, for Meta, Hyper, and Super). For example, here is -how to swap the Meta and Alt modifiers within Emacs: -@lisp -(setq x-alt-keysym 'meta) -(setq x-meta-keysym 'alt) -@end lisp -@end defvar - -@node Batch Mode -@section Batch Mode -@cindex batch mode - - The command-line option @samp{-batch} causes Emacs to run -noninteractively. In this mode, Emacs does not read commands from the -terminal, it does not alter the terminal modes, and it does not expect -to be outputting to an erasable screen. The idea is that you specify -Lisp programs to run; when they are finished, Emacs should exit. The -way to specify the programs to run is with @samp{-l @var{file}}, which -loads the library named @var{file}, or @samp{-f @var{function}}, which -calls @var{function} with no arguments, or @samp{--eval @var{form}}. - - Any Lisp program output that would normally go to the echo area, -either using @code{message}, or using @code{prin1}, etc., with @code{t} -as the stream, goes instead to Emacs's standard error descriptor when -in batch mode. Similarly, input that would normally come from the -minibuffer is read from the standard input descriptor. -Thus, Emacs behaves much like a noninteractive -application program. (The echo area output that Emacs itself normally -generates, such as command echoing, is suppressed entirely.) - -@defvar noninteractive -This variable is non-@code{nil} when Emacs is running in batch mode. -@end defvar - -@node Session Management -@section Session Management -@cindex session manager - -Emacs supports the X Session Management Protocol, which is used to -suspend and restart applications. In the X Window System, a program -called the @dfn{session manager} is responsible for keeping track of -the applications that are running. When the X server shuts down, the -session manager asks applications to save their state, and delays the -actual shutdown until they respond. An application can also cancel -the shutdown. - -When the session manager restarts a suspended session, it directs -these applications to individually reload their saved state. It does -this by specifying a special command-line argument that says what -saved session to restore. For Emacs, this argument is @samp{--smid -@var{session}}. - -@defvar emacs-save-session-functions -Emacs supports saving state via a hook called -@code{emacs-save-session-functions}. Emacs runs this hook when the -session manager tells it that the window system is shutting down. The -functions are called with no arguments, and with the current buffer -set to a temporary buffer. Each function can use @code{insert} to add -Lisp code to this buffer. At the end, Emacs saves the buffer in a -file, called the @dfn{session file}. - -@findex emacs-session-restore -Subsequently, when the session manager restarts Emacs, it loads the -session file automatically (@pxref{Loading}). This is performed by a -function named @code{emacs-session-restore}, which is called during -startup. @xref{Startup Summary}. - -If a function in @code{emacs-save-session-functions} returns -non-@code{nil}, Emacs tells the session manager to cancel the -shutdown. -@end defvar - -Here is an example that just inserts some text into @file{*scratch*} when -Emacs is restarted by the session manager. - -@example -@group -(add-hook 'emacs-save-session-functions 'save-yourself-test) -@end group - -@group -(defun save-yourself-test () - (insert "(save-current-buffer - (switch-to-buffer \"*scratch*\") - (insert \"I am restored\"))") - nil) -@end group -@end example - -@node Notifications -@section Desktop Notifications -@cindex desktop notifications - -Emacs is able to send @dfn{notifications} on systems that support the -freedesktop.org Desktop Notifications Specification. In order to use -this functionality, Emacs must have been compiled with D-Bus support, -and the @code{notifications} library must be loaded. - -@defun notifications-notify &rest params -This function sends a notification to the desktop via D-Bus, -consisting of the parameters specified by the @var{params} arguments. -These arguments should consist of alternating keyword and value pairs. -The supported keywords and values are as follows: - -@table @code -@item :title @var{title} -The notification title. - -@item :body @var{text} -The notification body text. Depending on the implementation of the -notification server, the text could contain HTML markups, like -@samp{"bold text"}, or hyperlinks. - -@item :app-name @var{name} -The name of the application sending the notification. The default is -@code{notifications-application-name}. - -@item :replaces-id @var{id} -The notification @var{id} that this notification replaces. @var{id} -must be the result of a previous @code{notifications-notify} call. - -@item :app-icon @var{icon-file} -The file name of the notification icon. If set to @code{nil}, no icon -is displayed. The default is @code{notifications-application-icon}. - -@item :actions (@var{key} @var{title} @var{key} @var{title} ...) -A list of actions to be applied. @var{key} and @var{title} are both -strings. The default action (usually invoked by clicking the -notification) should have a key named @samp{"default"}. The title can -be anything, though implementations are free not to display it. - -@item :timeout @var{timeout} -The timeout time in milliseconds since the display of the notification -at which the notification should automatically close. If -1, the -notification's expiration time is dependent on the notification -server's settings, and may vary for the type of notification. If 0, -the notification never expires. Default value is -1. - -@item :urgency @var{urgency} -The urgency level. It can be @code{low}, @code{normal}, or @code{critical}. - -@item :category @var{category} -The type of notification this is, a string. - -@item :desktop-entry @var{filename} -This specifies the name of the desktop filename representing the -calling program, like @samp{"emacs"}. - -@item :image-data (@var{width} @var{height} @var{rowstride} @var{has-alpha} @var{bits} @var{channels} @var{data}) -This is a raw data image format that describes the width, height, -rowstride, whether there is an alpha channel, bits per sample, -channels and image data, respectively. - -@item :image-path @var{path} -This is represented either as a URI (@samp{file://} is the only URI -schema supported right now) or a name in a freedesktop.org-compliant -icon theme from @samp{$XDG_DATA_DIRS/icons}, like @samp{"mail-message-new"}. - -@item :sound-file @var{filename} -The path to a sound file to play when the notification pops up. - -@item :sound-name @var{name} -A themable named sound from the freedesktop.org sound naming -specification from @samp{$XDG_DATA_DIRS/sounds}, to play when the -notification pops up. Similar to the icon name, only for sounds. An -example would be @samp{"message-new-instant"}. - -@item :suppress-sound -Causes the server to suppress playing any sounds, if it has that -ability. - -@item :x @var{position} -@itemx :y @var{position} -Specifies the X, Y location on the screen that the -notification should point to. Both arguments must be used together. - -@item :on-action @var{function} -Function to call when an action is invoked. The notification @var{id} -and the @var{key} of the action are passed as arguments to the -function. - -@item :on-close @var{function} -Function to call when the notification has been closed by timeout or -by the user. The function receive the notification @var{id} and the closing -@var{reason} as arguments: - -@itemize -@item @code{expired} if the notification has expired -@item @code{dismissed} if the notification was dismissed by the user -@item @code{close-notification} if the notification was closed by a call to -@code{notifications-close-notification} -@item @code{undefined} if the notification server hasn't provided a reason -@end itemize -@end table - -This function returns a notification id, an integer, which can be used -to manipulate the notification item with -@code{notifications-close-notification} or the @code{:replaces-id} -argument of another @code{notifications-notify} call. For example: - -@example -@group -(defun my-on-action-function (id key) - (message "Message %d, key \"%s\" pressed" id key)) - @result{} my-on-action-function -@end group - -@group -(defun my-on-close-function (id reason) - (message "Message %d, closed due to \"%s\"" id reason)) - @result{} my-on-close-function -@end group - -@group -(notifications-notify - :title "Title" - :body "This is important." - :actions '("Confirm" "I agree" "Refuse" "I disagree") - :on-action 'my-on-action-function - :on-close 'my-on-close-function) - @result{} 22 -@end group - -@group -A message window opens on the desktop. Press "I agree" - @result{} Message 22, key "Confirm" pressed - Message 22, closed due to "dismissed" -@end group -@end example -@end defun - -@defun notifications-close-notification id -This function closes a notification with identifier @var{id}. -@end defun - -@node Dynamic Libraries -@section Dynamically Loaded Libraries -@cindex dynamic libraries - - A @dfn{dynamically loaded library} is a library that is loaded on -demand, when its facilities are first needed. Emacs supports such -on-demand loading of support libraries for some of its features. - -@defvar dynamic-library-alist -This is an alist of dynamic libraries and external library files -implementing them. - -Each element is a list of the form -@w{@code{(@var{library} @var{files}@dots{})}}, where the @code{car} is -a symbol representing a supported external library, and the rest are -strings giving alternate filenames for that library. - -Emacs tries to load the library from the files in the order they -appear in the list; if none is found, the running session of Emacs -won't have access to that library, and the features that depend on the -library will be unavailable. - -Image support on some platforms uses this facility. Here's an example -of setting this variable for supporting images on MS-Windows: - -@lisp -(setq dynamic-library-alist - '((xpm "libxpm.dll" "xpm4.dll" "libXpm-nox4.dll") - (png "libpng12d.dll" "libpng12.dll" "libpng.dll" - "libpng13d.dll" "libpng13.dll") - (jpeg "jpeg62.dll" "libjpeg.dll" "jpeg-62.dll" "jpeg.dll") - (tiff "libtiff3.dll" "libtiff.dll") - (gif "giflib4.dll" "libungif4.dll" "libungif.dll") - (svg "librsvg-2-2.dll") - (gdk-pixbuf "libgdk_pixbuf-2.0-0.dll") - (glib "libglib-2.0-0.dll") - (gobject "libgobject-2.0-0.dll"))) -@end lisp - -Note that image types @code{pbm} and @code{xbm} do not need entries in -this variable because they do not depend on external libraries and are -always available in Emacs. - -Also note that this variable is not meant to be a generic facility for -accessing external libraries; only those already known by Emacs can -be loaded through it. - -This variable is ignored if the given @var{library} is statically -linked into Emacs. -@end defvar diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi deleted file mode 100644 index 387fba52c63..00000000000 --- a/doc/lispref/package.texi +++ /dev/null @@ -1,339 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2010-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/package -@node Packaging, Antinews, System Interface, Top -@chapter Preparing Lisp code for distribution -@cindex package -@cindex Lisp package - - Emacs provides a standard way to distribute Emacs Lisp code to -users. A @dfn{package} is a collection of one or more files, -formatted and bundled in such a way that users can easily download, -install, uninstall, and upgrade it. - - The following sections describe how to create a package, and how to -put it in a @dfn{package archive} for others to download. -@xref{Packages,,, emacs, The GNU Emacs Manual}, for a description of -user-level features of the packaging system. - -@menu -* Packaging Basics:: The basic concepts of Emacs Lisp packages. -* Simple Packages:: How to package a single .el file. -* Multi-file Packages:: How to package multiple files. -* Package Archives:: Maintaining package archives. -@end menu - -@node Packaging Basics -@section Packaging Basics -@cindex package attributes -@cindex package name -@cindex package version -@cindex dependencies -@cindex package dependencies - - A package is either a @dfn{simple package} or a @dfn{multi-file -package}. A simple package is stored in a package archive as a single -Emacs Lisp file, while a multi-file package is stored as a tar file -(containing multiple Lisp files, and possibly non-Lisp files such as a -manual). - - In ordinary usage, the difference between simple packages and -multi-file packages is relatively unimportant; the Package Menu -interface makes no distinction between them. However, the procedure -for creating them differs, as explained in the following sections. - - Each package (whether simple or multi-file) has certain -@dfn{attributes}: - -@table @asis -@item Name -A short word (e.g. @samp{auctex}). This is usually also the symbol -prefix used in the program (@pxref{Coding Conventions}). - -@item Version -A version number, in a form that the function @code{version-to-list} -understands (e.g. @samp{11.86}). Each release of a package should be -accompanied by an increase in the version number. - -@item Brief description -This is shown when the package is listed in the Package Menu. It -should occupy a single line, ideally in 36 characters or less. - -@item Long description -This is shown in the buffer created by @kbd{C-h P} -(@code{describe-package}), following the package's brief description -and installation status. It normally spans multiple lines, and should -fully describe the package's capabilities and how to begin using it -once it is installed. - -@item Dependencies -A list of other packages (possibly including minimal acceptable -version numbers) on which this package depends. The list may be -empty, meaning this package has no dependencies. Otherwise, -installing this package also automatically installs its dependencies; -if any dependency cannot be found, the package cannot be installed. -@end table - -@cindex content directory, package - Installing a package, either via the command @code{package-install-file}, -or via the Package Menu, creates a subdirectory of -@code{package-user-dir} named @file{@var{name}-@var{version}}, where -@var{name} is the package's name and @var{version} its version -(e.g. @file{~/.emacs.d/elpa/auctex-11.86/}). We call this the -package's @dfn{content directory}. It is where Emacs puts the -package's contents (the single Lisp file for a simple package, or the -files extracted from a multi-file package). - -@cindex package autoloads - Emacs then searches every Lisp file in the content directory for -autoload magic comments (@pxref{Autoload}). These autoload -definitions are saved to a file named @file{@var{name}-autoloads.el} -in the content directory. They are typically used to autoload the -principal user commands defined in the package, but they can also -perform other tasks, such as adding an element to -@code{auto-mode-alist} (@pxref{Auto Major Mode}). Note that a package -typically does @emph{not} autoload every function and variable defined -within it---only the handful of commands typically called to begin -using the package. Emacs then byte-compiles every Lisp file in the -package. - - After installation, the installed package is @dfn{loaded}: Emacs -adds the package's content directory to @code{load-path}, and -evaluates the autoload definitions in @file{@var{name}-autoloads.el}. - - Whenever Emacs starts up, it automatically calls the function -@code{package-initialize} to load installed packages. This is done -after loading the init file and abbrev file (if any) and before -running @code{after-init-hook} (@pxref{Startup Summary}). Automatic -package loading is disabled if the user option -@code{package-enable-at-startup} is @code{nil}. - -@deffn Command package-initialize &optional no-activate -This function initializes Emacs' internal record of which packages are -installed, and loads them. The user option @code{package-load-list} -specifies which packages to load; by default, all installed packages -are loaded. @xref{Package Installation,,, emacs, The GNU Emacs -Manual}. - -The optional argument @var{no-activate}, if non-@code{nil}, causes -Emacs to update its record of installed packages without actually -loading them; it is for internal use only. -@end deffn - -@node Simple Packages -@section Simple Packages -@cindex single file package -@cindex simple package - - A simple package consists of a single Emacs Lisp source file. The -file must conform to the Emacs Lisp library header conventions -(@pxref{Library Headers}). The package's attributes are taken from -the various headers, as illustrated by the following example: - -@example -@group -;;; superfrobnicator.el --- Frobnicate and bifurcate flanges - -;; Copyright (C) 2011 Free Software Foundation, Inc. -@end group - -;; Author: J. R. Hacker -;; Version: 1.3 -;; Package-Requires: ((flange "1.0")) -;; Keywords: frobnicate - -@dots{} - -;;; Commentary: - -;; This package provides a minor mode to frobnicate and/or -;; bifurcate any flanges you desire. To activate it, just type -@dots{} - -;;;###autoload -(define-minor-mode superfrobnicator-mode -@dots{} -@end example - - The name of the package is the same as the base name of the file, as -written on the first line. Here, it is @samp{superfrobnicator}. - - The brief description is also taken from the first line. Here, it -is @samp{Frobnicate and bifurcate flanges}. - - The version number comes from the @samp{Package-Version} header, if -it exists, or from the @samp{Version} header otherwise. One or the -other @emph{must} be present. Here, the version number is 1.3. - - If the file has a @samp{;;; Commentary:} section, this section is -used as the long description. (When displaying the description, Emacs -omits the @samp{;;; Commentary:} line, as well as the leading comment -characters in the commentary itself.) - - If the file has a @samp{Package-Requires} header, that is used as -the package dependencies. In the above example, the package depends -on the @samp{flange} package, version 1.0 or higher. @xref{Library -Headers}, for a description of the @samp{Package-Requires} header. If -the header is omitted, the package has no dependencies. - - The file ought to also contain one or more autoload magic comments, -as explained in @ref{Packaging Basics}. In the above example, a magic -comment autoloads @code{superfrobnicator-mode}. - - @xref{Package Archives}, for a explanation of how to add a -single-file package to a package archive. - -@node Multi-file Packages -@section Multi-file Packages -@cindex multi-file package - - A multi-file package is less convenient to create than a single-file -package, but it offers more features: it can include multiple Emacs -Lisp files, an Info manual, and other file types (such as images). - - Prior to installation, a multi-file package is stored in a package -archive as a tar file. The tar file must be named -@file{@var{name}-@var{version}.tar}, where @var{name} is the package -name and @var{version} is the version number. Its contents, once -extracted, must all appear in a directory named -@file{@var{name}-@var{version}}, the @dfn{content directory} -(@pxref{Packaging Basics}). Files may also extract into -subdirectories of the content directory. - - One of the files in the content directory must be named -@file{@var{name}-pkg.el}. It must contain a single Lisp form, -consisting of a call to the function @code{define-package}, described -below. This defines the package's version, brief description, and -requirements. - - For example, if we distribute version 1.3 of the superfrobnicator as -a multi-file package, the tar file would be -@file{superfrobnicator-1.3.tar}. Its contents would extract into the -directory @file{superfrobnicator-1.3}, and one of these would be the -file @file{superfrobnicator-pkg.el}. - -@defun define-package name version &optional docstring requirements -This function defines a package. @var{name} is the package name, a -string. @var{version} is the version, as a string of a form that can -be understood by the function @code{version-to-list}. @var{docstring} -is the brief description. - -@var{requirements} is a list of required packages and their versions. -Each element in this list should have the form @code{(@var{dep-name} -@var{dep-version})}, where @var{dep-name} is a symbol whose name is -the dependency's package name, and @var{dep-version} is the -dependency's version (a string). -@end defun - - If the content directory contains a file named @file{README}, this -file is used as the long description. - - If the content directory contains a file named @file{dir}, this is -assumed to be an Info directory file made with @command{install-info}. -@xref{Invoking install-info, Invoking install-info, Invoking -install-info, texinfo, Texinfo}. The relevant Info files should also -be present in the content directory. In this case, Emacs will -automatically add the content directory to @code{Info-directory-list} -when the package is activated. - - Do not include any @file{.elc} files in the package. Those are -created when the package is installed. Note that there is no way to -control the order in which files are byte-compiled. - - Do not include any file named @file{@var{name}-autoloads.el}. This -file is reserved for the package's autoload definitions -(@pxref{Packaging Basics}). It is created automatically when the -package is installed, by searching all the Lisp files in the package -for autoload magic comments. - - If the multi-file package contains auxiliary data files (such as -images), the package's Lisp code can refer to these files via the -variable @code{load-file-name} (@pxref{Loading}). Here is an example: - -@smallexample -(defconst superfrobnicator-base (file-name-directory load-file-name)) - -(defun superfrobnicator-fetch-image (file) - (expand-file-name file superfrobnicator-base)) -@end smallexample - -@node Package Archives -@section Creating and Maintaining Package Archives -@cindex package archive - - Via the Package Menu, users may download packages from @dfn{package -archives}. Such archives are specified by the variable -@code{package-archives}, whose default value contains a single entry: -the archive hosted by the GNU project at @url{elpa.gnu.org}. This -section describes how to set up and maintain a package archive. - -@cindex base location, package archive -@defopt package-archives -The value of this variable is an alist of package archives recognized -by the Emacs package manager. - -Each alist element corresponds to one archive, and should have the -form @code{(@var{id} . @var{location})}, where @var{id} is the name of -the archive (a string) and @var{location} is its @dfn{base location} -(a string). - -If the base location starts with @samp{http:}, it is treated as a HTTP -URL, and packages are downloaded from this archive via HTTP (as is the -case for the default GNU archive). - -Otherwise, the base location should be a directory name. In this -case, Emacs retrieves packages from this archive via ordinary file -access. Such ``local'' archives are mainly useful for testing. -@end defopt - - A package archive is simply a directory in which the package files, -and associated files, are stored. If you want the archive to be -reachable via HTTP, this directory must be accessible to a web server. -How to accomplish this is beyond the scope of this manual. - - A convenient way to set up and update a package archive is via the -@code{package-x} library. This is included with Emacs, but not loaded -by default; type @kbd{M-x load-library @key{RET} package-x @key{RET}} to -load it, or add @code{(require 'package-x)} to your init file. -@xref{Lisp Libraries,, Lisp Libraries, emacs, The GNU Emacs Manual}. -Once loaded, you can make use of the following: - -@defopt package-archive-upload-base -The value of this variable is the base location of a package archive, -as a directory name. The commands in the @code{package-x} library -will use this base location. - -The directory name should be absolute. You may specify a remote name, -such as @file{/ssh:foo@@example.com:/var/www/packages/}, if the -package archive is on a different machine. @xref{Remote Files,, -Remote Files, emacs, The GNU Emacs Manual}. -@end defopt - -@deffn Command package-upload-file filename -This command prompts for @var{filename}, a file name, and uploads that -file to @code{package-archive-upload-base}. The file must be either a -simple package (a @file{.el} file) or a multi-file package (a -@file{.tar} file); otherwise, an error is raised. The package -attributes are automatically extracted, and the archive's contents -list is updated with this information. - -If @code{package-archive-upload-base} does not specify a valid -directory, the function prompts interactively for one. If the -directory does not exist, it is created. The directory need not have -any initial contents (i.e., you can use this command to populate an -initially empty archive). -@end deffn - -@deffn Command package-upload-buffer -This command is similar to @code{package-upload-file}, but instead of -prompting for a package file, it uploads the contents of the current -buffer. The current buffer must be visiting a simple package (a -@file{.el} file) or a multi-file package (a @file{.tar} file); -otherwise, an error is raised. -@end deffn - -@noindent -After you create an archive, remember that it is not accessible in the -Package Menu interface unless it is in @code{package-archives}. diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi deleted file mode 100644 index 99722c93902..00000000000 --- a/doc/lispref/positions.texi +++ /dev/null @@ -1,988 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/positions -@node Positions, Markers, Frames, Top -@chapter Positions -@cindex position (in buffer) - - A @dfn{position} is the index of a character in the text of a buffer. -More precisely, a position identifies the place between two characters -(or before the first character, or after the last character), so we can -speak of the character before or after a given position. However, we -often speak of the character ``at'' a position, meaning the character -after that position. - - Positions are usually represented as integers starting from 1, but -can also be represented as @dfn{markers}---special objects that -relocate automatically when text is inserted or deleted so they stay -with the surrounding characters. Functions that expect an argument to -be a position (an integer), but accept a marker as a substitute, -normally ignore which buffer the marker points into; they convert the -marker to an integer, and use that integer, exactly as if you had -passed the integer as the argument, even if the marker points to the -``wrong'' buffer. A marker that points nowhere cannot convert to an -integer; using it instead of an integer causes an error. -@xref{Markers}. - - See also the ``field'' feature (@pxref{Fields}), which provides -functions that are used by many cursor-motion commands. - -@menu -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. -@end menu - -@node Point -@section Point -@cindex point - - @dfn{Point} is a special buffer position used by many editing -commands, including the self-inserting typed characters and text -insertion functions. Other commands move point through the text -to allow editing and insertion at different places. - - Like other positions, point designates a place between two characters -(or before the first character, or after the last character), rather -than a particular character. Usually terminals display the cursor over -the character that immediately follows point; point is actually before -the character on which the cursor sits. - -@cindex point with narrowing - The value of point is a number no less than 1, and no greater than the -buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then -point is constrained to fall within the accessible portion of the buffer -(possibly at one end of it). - - Each buffer has its own value of point, which is independent of the -value of point in other buffers. Each window also has a value of point, -which is independent of the value of point in other windows on the same -buffer. This is why point can have different values in various windows -that display the same buffer. When a buffer appears in only one window, -the buffer's point and the window's point normally have the same value, -so the distinction is rarely important. @xref{Window Point}, for more -details. - -@defun point -@cindex current buffer position -This function returns the value of point in the current buffer, -as an integer. - -@need 700 -@example -@group -(point) - @result{} 175 -@end group -@end example -@end defun - -@defun point-min -This function returns the minimum accessible value of point in the -current buffer. This is normally 1, but if narrowing is in effect, it -is the position of the start of the region that you narrowed to. -(@xref{Narrowing}.) -@end defun - -@defun point-max -This function returns the maximum accessible value of point in the -current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is -in effect, in which case it is the position of the end of the region -that you narrowed to. (@xref{Narrowing}.) -@end defun - -@defun buffer-end flag -This function returns @code{(point-max)} if @var{flag} is greater than -0, @code{(point-min)} otherwise. The argument @var{flag} must be a -number. -@end defun - -@defun buffer-size &optional buffer -This function returns the total number of characters in the current -buffer. In the absence of any narrowing (@pxref{Narrowing}), -@code{point-max} returns a value one larger than this. - -If you specify a buffer, @var{buffer}, then the value is the -size of @var{buffer}. - -@example -@group -(buffer-size) - @result{} 35 -@end group -@group -(point-max) - @result{} 36 -@end group -@end example -@end defun - -@node Motion -@section Motion -@cindex motion by chars, words, lines, lists - - Motion functions change the value of point, either relative to the -current value of point, relative to the beginning or end of the buffer, -or relative to the edges of the selected window. @xref{Point}. - -@menu -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. -@end menu - -@node Character Motion -@subsection Motion by Characters - - These functions move point based on a count of characters. -@code{goto-char} is the fundamental primitive; the other functions use -that. - -@deffn Command goto-char position -This function sets point in the current buffer to the value -@var{position}. If @var{position} is less than 1, it moves point to the -beginning of the buffer. If @var{position} is greater than the length -of the buffer, it moves point to the end. - -If narrowing is in effect, @var{position} still counts from the -beginning of the buffer, but point cannot go outside the accessible -portion. If @var{position} is out of range, @code{goto-char} moves -point to the beginning or the end of the accessible portion. - -When this function is called interactively, @var{position} is the -numeric prefix argument, if provided; otherwise it is read from the -minibuffer. - -@code{goto-char} returns @var{position}. -@end deffn - -@deffn Command forward-char &optional count -@c @kindex beginning-of-buffer -@c @kindex end-of-buffer -This function moves point @var{count} characters forward, towards the -end of the buffer (or backward, towards the beginning of the buffer, if -@var{count} is negative). If @var{count} is @code{nil}, the default -is 1. - -If this attempts to move past the beginning or end of the buffer (or -the limits of the accessible portion, when narrowing is in effect), it -signals an error with error symbol @code{beginning-of-buffer} or -@code{end-of-buffer}. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@deffn Command backward-char &optional count -This is just like @code{forward-char} except that it moves -in the opposite direction. -@end deffn - -@node Word Motion -@subsection Motion by Words - - These functions for parsing words use the syntax table to decide -whether a given character is part of a word. @xref{Syntax Tables}. - -@deffn Command forward-word &optional count -This function moves point forward @var{count} words (or backward if -@var{count} is negative). If @var{count} is @code{nil}, it moves -forward one word. - -``Moving one word'' means moving until point crosses a -word-constituent character and then encounters a word-separator -character. However, this function cannot move point past the boundary -of the accessible portion of the buffer, or across a field boundary -(@pxref{Fields}). The most common case of a field boundary is the end -of the prompt in the minibuffer. - -If it is possible to move @var{count} words, without being stopped -prematurely by the buffer boundary or a field boundary, the value is -@code{t}. Otherwise, the return value is @code{nil} and point stops at -the buffer boundary or field boundary. - -If @code{inhibit-field-text-motion} is non-@code{nil}, -this function ignores field boundaries. - -In an interactive call, @var{count} is specified by the numeric prefix -argument. If @var{count} is omitted or @code{nil}, it defaults to 1. -@end deffn - -@deffn Command backward-word &optional count -This function is just like @code{forward-word}, except that it moves -backward until encountering the front of a word, rather than forward. -@end deffn - -@defopt words-include-escapes -@c Emacs 19 feature -This variable affects the behavior of @code{forward-word} and everything -that uses it. If it is non-@code{nil}, then characters in the -``escape'' and ``character quote'' syntax classes count as part of -words. Otherwise, they do not. -@end defopt - -@defvar inhibit-field-text-motion -If this variable is non-@code{nil}, certain motion functions including -@code{forward-word}, @code{forward-sentence}, and -@code{forward-paragraph} ignore field boundaries. -@end defvar - -@node Buffer End Motion -@subsection Motion to an End of the Buffer -@cindex move to beginning or end of buffer - - To move point to the beginning of the buffer, write: - -@example -@group -(goto-char (point-min)) -@end group -@end example - -@noindent -Likewise, to move to the end of the buffer, use: - -@example -@group -(goto-char (point-max)) -@end group -@end example - - Here are two commands that users use to do these things. They are -documented here to warn you not to use them in Lisp programs, because -they set the mark and display messages in the echo area. - -@deffn Command beginning-of-buffer &optional n -This function moves point to the beginning of the buffer (or the limits -of the accessible portion, when narrowing is in effect), setting the -mark at the previous position (except in Transient Mark mode, if -the mark is already active, it does not set the mark.) - -If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the -way from the beginning of the accessible portion of the buffer. In an -interactive call, @var{n} is the numeric prefix argument, if provided; -otherwise @var{n} defaults to @code{nil}. - -@strong{Warning:} Don't use this function in Lisp programs! -@end deffn - -@deffn Command end-of-buffer &optional n -This function moves point to the end of the buffer (or the limits of -the accessible portion, when narrowing is in effect), setting the mark -at the previous position (except in Transient Mark mode when the mark -is already active). If @var{n} is non-@code{nil}, then it puts point -@var{n} tenths of the way from the end of the accessible portion of -the buffer. - -In an interactive call, @var{n} is the numeric prefix argument, -if provided; otherwise @var{n} defaults to @code{nil}. - -@strong{Warning:} Don't use this function in Lisp programs! -@end deffn - -@node Text Lines -@subsection Motion by Text Lines -@cindex lines - - Text lines are portions of the buffer delimited by newline characters, -which are regarded as part of the previous line. The first text line -begins at the beginning of the buffer, and the last text line ends at -the end of the buffer whether or not the last character is a newline. -The division of the buffer into text lines is not affected by the width -of the window, by line continuation in display, or by how tabs and -control characters are displayed. - -@deffn Command beginning-of-line &optional count -This function moves point to the beginning of the current line. With an -argument @var{count} not @code{nil} or 1, it moves forward -@var{count}@minus{}1 lines and then to the beginning of the line. - -This function does not move point across a field boundary -(@pxref{Fields}) unless doing so would move beyond there to a -different line; therefore, if @var{count} is @code{nil} or 1, and -point starts at a field boundary, point does not move. To ignore -field boundaries, either bind @code{inhibit-field-text-motion} to -@code{t}, or use the @code{forward-line} function instead. For -instance, @code{(forward-line 0)} does the same thing as -@code{(beginning-of-line)}, except that it ignores field boundaries. - -If this function reaches the end of the buffer (or of the accessible -portion, if narrowing is in effect), it positions point there. No error -is signaled. -@end deffn - -@defun line-beginning-position &optional count -Return the position that @code{(beginning-of-line @var{count})} -would move to. -@end defun - -@deffn Command end-of-line &optional count -This function moves point to the end of the current line. With an -argument @var{count} not @code{nil} or 1, it moves forward -@var{count}@minus{}1 lines and then to the end of the line. - -This function does not move point across a field boundary -(@pxref{Fields}) unless doing so would move beyond there to a -different line; therefore, if @var{count} is @code{nil} or 1, and -point starts at a field boundary, point does not move. To ignore -field boundaries, bind @code{inhibit-field-text-motion} to @code{t}. - -If this function reaches the end of the buffer (or of the accessible -portion, if narrowing is in effect), it positions point there. No error -is signaled. -@end deffn - -@defun line-end-position &optional count -Return the position that @code{(end-of-line @var{count})} -would move to. -@end defun - -@deffn Command forward-line &optional count -@cindex beginning of line -This function moves point forward @var{count} lines, to the beginning of -the line. If @var{count} is negative, it moves point -@minus{}@var{count} lines backward, to the beginning of a line. If -@var{count} is zero, it moves point to the beginning of the current -line. If @var{count} is @code{nil}, that means 1. - -If @code{forward-line} encounters the beginning or end of the buffer (or -of the accessible portion) before finding that many lines, it sets point -there. No error is signaled. - -@code{forward-line} returns the difference between @var{count} and the -number of lines actually moved. If you attempt to move down five lines -from the beginning of a buffer that has only three lines, point stops at -the end of the last line, and the value will be 2. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@defun count-lines start end -@cindex lines in region -@anchor{Definition of count-lines} -This function returns the number of lines between the positions -@var{start} and @var{end} in the current buffer. If @var{start} and -@var{end} are equal, then it returns 0. Otherwise it returns at least -1, even if @var{start} and @var{end} are on the same line. This is -because the text between them, considered in isolation, must contain at -least one line unless it is empty. -@end defun - -@deffn Command count-words start end -@cindex words in region -This function returns the number of words between the positions -@var{start} and @var{end} in the current buffer. - -This function can also be called interactively. In that case, it -prints a message reporting the number of lines, words, and characters -in the buffer, or in the region if the region is active. -@end deffn - -@defun line-number-at-pos &optional pos -@cindex line number -This function returns the line number in the current buffer -corresponding to the buffer position @var{pos}. If @var{pos} is @code{nil} -or omitted, the current buffer position is used. -@end defun - -@ignore -@c ================ -The @code{previous-line} and @code{next-line} commands are functions -that should not be used in programs. They are for users and are -mentioned here only for completeness. - -@deffn Command previous-line count -@cindex goal column -This function moves point up @var{count} lines (down if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' -(normally the same column that it was at the beginning of the move). - -If there is no character in the target line exactly under the current -column, point is positioned after the character in that line which -spans this column, or at the end of the line if it is not long enough. - -If it attempts to move beyond the top or bottom of the buffer (or clipped -region), then point is positioned in the goal column in the top or -bottom line. No error is signaled. - -In an interactive call, @var{count} will be the numeric -prefix argument. - -The command @code{set-goal-column} can be used to create a semipermanent -goal column to which this command always moves. Then it does not try to -move vertically. - -If you are thinking of using this in a Lisp program, consider using -@code{forward-line} with a negative argument instead. It is usually easier -to use and more reliable (no dependence on goal column, etc.). -@end deffn - -@deffn Command next-line count -This function moves point down @var{count} lines (up if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' -(normally the same column that it was at the beginning of the move). - -If there is no character in the target line exactly under the current -column, point is positioned after the character in that line which -spans this column, or at the end of the line if it is not long enough. - -If it attempts to move beyond the top or bottom of the buffer (or clipped -region), then point is positioned in the goal column in the top or -bottom line. No error is signaled. - -In the case where the @var{count} is 1, and point is on the last -line of the buffer (or clipped region), a new empty line is inserted at the -end of the buffer (or clipped region) and point moved there. - -In an interactive call, @var{count} will be the numeric -prefix argument. - -The command @code{set-goal-column} can be used to create a semipermanent -goal column to which this command always moves. Then it does not try to -move vertically. - -If you are thinking of using this in a Lisp program, consider using -@code{forward-line} instead. It is usually easier -to use and more reliable (no dependence on goal column, etc.). -@end deffn - -@c ================ -@end ignore - - Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}. -These functions do not move point, but test whether it is already at the -beginning or end of a line. - -@node Screen Lines -@subsection Motion by Screen Lines - - The line functions in the previous section count text lines, delimited -only by newline characters. By contrast, these functions count screen -lines, which are defined by the way the text appears on the screen. A -text line is a single screen line if it is short enough to fit the width -of the selected window, but otherwise it may occupy several screen -lines. - - In some cases, text lines are truncated on the screen rather than -continued onto additional screen lines. In these cases, -@code{vertical-motion} moves point much like @code{forward-line}. -@xref{Truncation}. - - Because the width of a given string depends on the flags that control -the appearance of certain characters, @code{vertical-motion} behaves -differently, for a given piece of text, depending on the buffer it is -in, and even on the selected window (because the width, the truncation -flag, and display table may vary between windows). @xref{Usual -Display}. - - These functions scan text to determine where screen lines break, and -thus take time proportional to the distance scanned. If you intend to -use them heavily, Emacs provides caches which may improve the -performance of your code. @xref{Truncation, cache-long-line-scans}. - -@defun vertical-motion count &optional window -This function moves point to the start of the screen line @var{count} -screen lines down from the screen line containing point. If @var{count} -is negative, it moves up instead. - -The @var{count} argument can be a cons cell, @code{(@var{cols} -. @var{lines})}, instead of an integer. Then the function moves by -@var{lines} screen lines, and puts point @var{cols} columns from the -start of that screen line. - -The return value is the number of screen lines over which point was -moved. The value may be less in absolute value than @var{count} if -the beginning or end of the buffer was reached. - -The window @var{window} is used for obtaining parameters such as the -width, the horizontal scrolling, and the display table. But -@code{vertical-motion} always operates on the current buffer, even if -@var{window} currently displays some other buffer. -@end defun - -@defun count-screen-lines &optional beg end count-final-newline window -This function returns the number of screen lines in the text from -@var{beg} to @var{end}. The number of screen lines may be different -from the number of actual lines, due to line continuation, the display -table, etc. If @var{beg} and @var{end} are @code{nil} or omitted, -they default to the beginning and end of the accessible portion of the -buffer. - -If the region ends with a newline, that is ignored unless the optional -third argument @var{count-final-newline} is non-@code{nil}. - -The optional fourth argument @var{window} specifies the window for -obtaining parameters such as width, horizontal scrolling, and so on. -The default is to use the selected window's parameters. - -Like @code{vertical-motion}, @code{count-screen-lines} always uses the -current buffer, regardless of which buffer is displayed in -@var{window}. This makes possible to use @code{count-screen-lines} in -any buffer, whether or not it is currently displayed in some window. -@end defun - -@deffn Command move-to-window-line count -This function moves point with respect to the text currently displayed -in the selected window. It moves point to the beginning of the screen -line @var{count} screen lines from the top of the window. If -@var{count} is negative, that specifies a position -@w{@minus{}@var{count}} lines from the bottom (or the last line of the -buffer, if the buffer ends above the specified screen position). - -If @var{count} is @code{nil}, then point moves to the beginning of the -line in the middle of the window. If the absolute value of @var{count} -is greater than the size of the window, then point moves to the place -that would appear on that screen line if the window were tall enough. -This will probably cause the next redisplay to scroll to bring that -location onto the screen. - -In an interactive call, @var{count} is the numeric prefix argument. - -The value returned is the window line number point has moved to, with -the top line in the window numbered 0. -@end deffn - -@defun compute-motion from frompos to topos width offsets window -This function scans the current buffer, calculating screen positions. -It scans the buffer forward from position @var{from}, assuming that is -at screen coordinates @var{frompos}, to position @var{to} or coordinates -@var{topos}, whichever comes first. It returns the ending buffer -position and screen coordinates. - -The coordinate arguments @var{frompos} and @var{topos} are cons cells of -the form @code{(@var{hpos} . @var{vpos})}. - -The argument @var{width} is the number of columns available to display -text; this affects handling of continuation lines. @code{nil} means -the actual number of usable text columns in the window, which is -equivalent to the value returned by @code{(window-width window)}. - -The argument @var{offsets} is either @code{nil} or a cons cell of the -form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is -the number of columns not being displayed at the left margin; most -callers get this by calling @code{window-hscroll}. Meanwhile, -@var{tab-offset} is the offset between column numbers on the screen and -column numbers in the buffer. This can be nonzero in a continuation -line, when the previous screen lines' widths do not add up to a multiple -of @code{tab-width}. It is always zero in a non-continuation line. - -The window @var{window} serves only to specify which display table to -use. @code{compute-motion} always operates on the current buffer, -regardless of what buffer is displayed in @var{window}. - -The return value is a list of five elements: - -@example -(@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin}) -@end example - -@noindent -Here @var{pos} is the buffer position where the scan stopped, @var{vpos} -is the vertical screen position, and @var{hpos} is the horizontal screen -position. - -The result @var{prevhpos} is the horizontal position one character back -from @var{pos}. The result @var{contin} is @code{t} if the last line -was continued after (or within) the previous character. - -For example, to find the buffer position of column @var{col} of screen line -@var{line} of a certain window, pass the window's display start location -as @var{from} and the window's upper-left coordinates as @var{frompos}. -Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to -the end of the accessible portion of the buffer, and pass @var{line} and -@var{col} as @var{topos}. Here's a function that does this: - -@example -(defun coordinates-of-position (col line) - (car (compute-motion (window-start) - '(0 . 0) - (point-max) - (cons col line) - (window-width) - (cons (window-hscroll) 0) - (selected-window)))) -@end example - -When you use @code{compute-motion} for the minibuffer, you need to use -@code{minibuffer-prompt-width} to get the horizontal position of the -beginning of the first screen line. @xref{Minibuffer Contents}. -@end defun - -@node List Motion -@comment node-name, next, previous, up -@subsection Moving over Balanced Expressions -@cindex sexp motion -@cindex Lisp expression motion -@cindex list motion -@cindex balanced parenthesis motion - - Here are several functions concerned with balanced-parenthesis -expressions (also called @dfn{sexps} in connection with moving across -them in Emacs). The syntax table controls how these functions interpret -various characters; see @ref{Syntax Tables}. @xref{Parsing -Expressions}, for lower-level primitives for scanning sexps or parts of -sexps. For user-level commands, see @ref{Parentheses,, Commands for -Editing with Parentheses, emacs, The GNU Emacs Manual}. - -@deffn Command forward-list &optional arg -This function moves forward across @var{arg} (default 1) balanced groups of -parentheses. (Other syntactic entities such as words or paired string -quotes are ignored.) -@end deffn - -@deffn Command backward-list &optional arg -This function moves backward across @var{arg} (default 1) balanced groups of -parentheses. (Other syntactic entities such as words or paired string -quotes are ignored.) -@end deffn - -@deffn Command up-list &optional arg -This function moves forward out of @var{arg} (default 1) levels of parentheses. -A negative argument means move backward but still to a less deep spot. -@end deffn - -@deffn Command down-list &optional arg -This function moves forward into @var{arg} (default 1) levels of -parentheses. A negative argument means move backward but still go -deeper in parentheses (@minus{}@var{arg} levels). -@end deffn - -@deffn Command forward-sexp &optional arg -This function moves forward across @var{arg} (default 1) balanced expressions. -Balanced expressions include both those delimited by parentheses and -other kinds, such as words and string constants. -@xref{Parsing Expressions}. For example, - -@example -@group ----------- Buffer: foo ---------- -(concat@point{} "foo " (car x) y z) ----------- Buffer: foo ---------- -@end group - -@group -(forward-sexp 3) - @result{} nil - ----------- Buffer: foo ---------- -(concat "foo " (car x) y@point{} z) ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command backward-sexp &optional arg -This function moves backward across @var{arg} (default 1) balanced expressions. -@end deffn - -@deffn Command beginning-of-defun &optional arg -This function moves back to the @var{arg}th beginning of a defun. If -@var{arg} is negative, this actually moves forward, but it still moves -to the beginning of a defun, not to the end of one. @var{arg} defaults -to 1. -@end deffn - -@deffn Command end-of-defun &optional arg -This function moves forward to the @var{arg}th end of a defun. If -@var{arg} is negative, this actually moves backward, but it still moves -to the end of a defun, not to the beginning of one. @var{arg} defaults -to 1. -@end deffn - -@defopt defun-prompt-regexp -If non-@code{nil}, this buffer-local variable holds a regular -expression that specifies what text can appear before the -open-parenthesis that starts a defun. That is to say, a defun begins -on a line that starts with a match for this regular expression, -followed by a character with open-parenthesis syntax. -@end defopt - -@defopt open-paren-in-column-0-is-defun-start -If this variable's value is non-@code{nil}, an open parenthesis in -column 0 is considered to be the start of a defun. If it is -@code{nil}, an open parenthesis in column 0 has no special meaning. -The default is @code{t}. -@end defopt - -@defvar beginning-of-defun-function -If non-@code{nil}, this variable holds a function for finding the -beginning of a defun. The function @code{beginning-of-defun} -calls this function instead of using its normal method, passing it its -optional argument. If the argument is non-@code{nil}, the function -should move back by that many functions, like -@code{beginning-of-defun} does. -@end defvar - -@defvar end-of-defun-function -If non-@code{nil}, this variable holds a function for finding the end of -a defun. The function @code{end-of-defun} calls this function instead -of using its normal method. -@end defvar - -@node Skipping Characters -@comment node-name, next, previous, up -@subsection Skipping Characters -@cindex skipping characters - - The following two functions move point over a specified set of -characters. For example, they are often used to skip whitespace. For -related functions, see @ref{Motion and Syntax}. - -These functions convert the set string to multibyte if the buffer is -multibyte, and they convert it to unibyte if the buffer is unibyte, as -the search functions do (@pxref{Searching and Matching}). - -@defun skip-chars-forward character-set &optional limit -This function moves point in the current buffer forward, skipping over a -given set of characters. It examines the character following point, -then advances point if the character matches @var{character-set}. This -continues until it reaches a character that does not match. The -function returns the number of characters moved over. - -The argument @var{character-set} is a string, like the inside of a -@samp{[@dots{}]} in a regular expression except that @samp{]} does not -terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. -Thus, @code{"a-zA-Z"} skips over all letters, stopping before the -first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before -the first letter. See @xref{Regular Expressions}. Character classes -can also be used, e.g. @code{"[:alnum:]"}. See @pxref{Char Classes}. - -If @var{limit} is supplied (it must be a number or a marker), it -specifies the maximum position in the buffer that point can be skipped -to. Point will stop at or before @var{limit}. - -In the following example, point is initially located directly before the -@samp{T}. After the form is evaluated, point is located at the end of -that line (between the @samp{t} of @samp{hat} and the newline). The -function skips all letters and spaces, but not newlines. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- -@end group - -@group -(skip-chars-forward "a-zA-Z ") - @result{} 18 - ----------- Buffer: foo ---------- -I read "The cat in the hat@point{} -comes back" twice. ----------- Buffer: foo ---------- -@end group -@end example -@end defun - -@defun skip-chars-backward character-set &optional limit -This function moves point backward, skipping characters that match -@var{character-set}, until @var{limit}. It is just like -@code{skip-chars-forward} except for the direction of motion. - -The return value indicates the distance traveled. It is an integer that -is zero or less. -@end defun - -@node Excursions -@section Excursions -@cindex excursion - - It is often useful to move point ``temporarily'' within a localized -portion of the program. This is called an @dfn{excursion}, and it is -done with the @code{save-excursion} special form. This construct -remembers the initial identity of the current buffer, and its values -of point and the mark, and restores them after the excursion -completes. It is the standard way to move point within one part of a -program and avoid affecting the rest of the program, and is used -thousands of times in the Lisp sources of Emacs. - - If you only need to save and restore the identity of the current -buffer, use @code{save-current-buffer} or @code{with-current-buffer} -instead (@pxref{Current Buffer}). If you need to save or restore -window configurations, see the forms described in @ref{Window -Configurations} and in @ref{Frame Configurations}. - -@defspec save-excursion body@dots{} -@cindex mark excursion -@cindex point excursion -This special form saves the identity of the current buffer and the -values of point and the mark in it, evaluates @var{body}, and finally -restores the buffer and its saved values of point and the mark. All -three saved values are restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). - -The value returned by @code{save-excursion} is the result of the last -form in @var{body}, or @code{nil} if no body forms were given. -@end defspec - - Because @code{save-excursion} only saves point and mark for the -buffer that was current at the start of the excursion, any changes -made to point and/or mark in other buffers, during the excursion, will -remain in effect afterward. This frequently leads to unintended -consequences, so the byte compiler warns if you call @code{set-buffer} -during an excursion: - -@example -Warning: Use `with-current-buffer' rather than save-excursion+set-buffer -@end example - -@noindent -To avoid such problems, you should call @code{save-excursion} only -after setting the desired current buffer, as in the following example: - -@example -@group -(defun append-string-to-buffer (string buffer) - "Append STRING to the end of BUFFER." - (with-current-buffer buffer - (save-excursion - (goto-char (point-max)) - (insert string)))) -@end group -@end example - -@cindex window excursions - Likewise, @code{save-excursion} does not restore window-buffer -correspondences altered by functions such as @code{switch-to-buffer}. -One way to restore these correspondences, and the selected window, is to -use @code{save-window-excursion} inside @code{save-excursion} -(@pxref{Window Configurations}). - - @strong{Warning:} Ordinary insertion of text adjacent to the saved -point value relocates the saved value, just as it relocates all -markers. More precisely, the saved value is a marker with insertion -type @code{nil}. @xref{Marker Insertion Types}. Therefore, when the -saved point value is restored, it normally comes before the inserted -text. - - Although @code{save-excursion} saves the location of the mark, it does -not prevent functions which modify the buffer from setting -@code{deactivate-mark}, and thus causing the deactivation of the mark -after the command finishes. @xref{The Mark}. - -@node Narrowing -@section Narrowing -@cindex narrowing -@cindex restriction (in a buffer) -@cindex accessible portion (of a buffer) - - @dfn{Narrowing} means limiting the text addressable by Emacs editing -commands to a limited range of characters in a buffer. The text that -remains addressable is called the @dfn{accessible portion} of the -buffer. - - Narrowing is specified with two buffer positions which become the -beginning and end of the accessible portion. For most editing commands -and most Emacs primitives, these positions replace the values of the -beginning and end of the buffer. While narrowing is in effect, no text -outside the accessible portion is displayed, and point cannot move -outside the accessible portion. - - Values such as positions or line numbers, which usually count from the -beginning of the buffer, do so despite narrowing, but the functions -which use them refuse to operate on text that is inaccessible. - - The commands for saving buffers are unaffected by narrowing; they save -the entire buffer regardless of any narrowing. - - If you need to display in a single buffer several very different -types of text, consider using an alternative facility described in -@ref{Swapping Text}. - -@deffn Command narrow-to-region start end -This function sets the accessible portion of the current buffer to start -at @var{start} and end at @var{end}. Both arguments should be character -positions. - -In an interactive call, @var{start} and @var{end} are set to the bounds -of the current region (point and the mark, with the smallest first). -@end deffn - -@deffn Command narrow-to-page &optional move-count -This function sets the accessible portion of the current buffer to -include just the current page. An optional first argument -@var{move-count} non-@code{nil} means to move forward or backward by -@var{move-count} pages and then narrow to one page. The variable -@code{page-delimiter} specifies where pages start and end -(@pxref{Standard Regexps}). - -In an interactive call, @var{move-count} is set to the numeric prefix -argument. -@end deffn - -@deffn Command widen -@cindex widening -This function cancels any narrowing in the current buffer, so that the -entire contents are accessible. This is called @dfn{widening}. -It is equivalent to the following expression: - -@example -(narrow-to-region 1 (1+ (buffer-size))) -@end example -@end deffn - -@defspec save-restriction body@dots{} -This special form saves the current bounds of the accessible portion, -evaluates the @var{body} forms, and finally restores the saved bounds, -thus restoring the same state of narrowing (or absence thereof) formerly -in effect. The state of narrowing is restored even in the event of an -abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). -Therefore, this construct is a clean way to narrow a buffer temporarily. - -The value returned by @code{save-restriction} is that returned by the -last form in @var{body}, or @code{nil} if no body forms were given. - -@c Wordy to avoid overfull hbox. --rjc 16mar92 -@strong{Caution:} it is easy to make a mistake when using the -@code{save-restriction} construct. Read the entire description here -before you try it. - -If @var{body} changes the current buffer, @code{save-restriction} still -restores the restrictions on the original buffer (the buffer whose -restrictions it saved from), but it does not restore the identity of the -current buffer. - -@code{save-restriction} does @emph{not} restore point and the mark; use -@code{save-excursion} for that. If you use both @code{save-restriction} -and @code{save-excursion} together, @code{save-excursion} should come -first (on the outside). Otherwise, the old point value would be -restored with temporary narrowing still in effect. If the old point -value were outside the limits of the temporary narrowing, this would -fail to restore it accurately. - -Here is a simple example of correct use of @code{save-restriction}: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of foo -This is the contents of foo -This is the contents of foo@point{} ----------- Buffer: foo ---------- -@end group - -@group -(save-excursion - (save-restriction - (goto-char 1) - (forward-line 2) - (narrow-to-region 1 (point)) - (goto-char (point-min)) - (replace-string "foo" "bar"))) - ----------- Buffer: foo ---------- -This is the contents of bar -This is the contents of bar -This is the contents of foo@point{} ----------- Buffer: foo ---------- -@end group -@end example -@end defspec diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi deleted file mode 100644 index 7426437e6f0..00000000000 --- a/doc/lispref/processes.texi +++ /dev/null @@ -1,3117 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/processes -@node Processes, Display, Abbrevs, Top -@chapter Processes -@cindex child process -@cindex parent process -@cindex subprocess -@cindex process - - In the terminology of operating systems, a @dfn{process} is a space in -which a program can execute. Emacs runs in a process. Emacs Lisp -programs can invoke other programs in processes of their own. These are -called @dfn{subprocesses} or @dfn{child processes} of the Emacs process, -which is their @dfn{parent process}. - - A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous}, -depending on how it is created. When you create a synchronous -subprocess, the Lisp program waits for the subprocess to terminate -before continuing execution. When you create an asynchronous -subprocess, it can run in parallel with the Lisp program. This kind of -subprocess is represented within Emacs by a Lisp object which is also -called a ``process''. Lisp programs can use this object to communicate -with the subprocess or to control it. For example, you can send -signals, obtain status information, receive output from the process, or -send input to it. - -@defun processp object -This function returns @code{t} if @var{object} represents an Emacs -subprocess, @code{nil} otherwise. -@end defun - - In addition to subprocesses of the current Emacs session, you can -also access other processes running on your machine. @xref{System -Processes}. - -@menu -* Subprocess Creation:: Functions that start subprocesses. -* Shell Arguments:: Quoting an argument to pass it to a shell. -* Synchronous Processes:: Details of using synchronous subprocesses. -* Asynchronous Processes:: Starting up an asynchronous subprocess. -* Deleting Processes:: Eliminating an asynchronous subprocess. -* Process Information:: Accessing run-status and other attributes. -* Input to Processes:: Sending input to an asynchronous subprocess. -* Signals to Processes:: Stopping, continuing or interrupting - an asynchronous subprocess. -* Output from Processes:: Collecting output from an asynchronous subprocess. -* Sentinels:: Sentinels run when process run-status changes. -* Query Before Exit:: Whether to query if exiting will kill a process. -* System Processes:: Accessing other processes running on your system. -* Transaction Queues:: Transaction-based communication with subprocesses. -* Network:: Opening network connections. -* Network Servers:: Network servers let Emacs accept net connections. -* Datagrams:: UDP network connections. -* Low-Level Network:: Lower-level but more general function - to create connections and servers. -* Misc Network:: Additional relevant functions for net connections. -* Serial Ports:: Communicating with serial ports. -* Byte Packing:: Using bindat to pack and unpack binary data. -@end menu - -@node Subprocess Creation -@section Functions that Create Subprocesses - - There are three primitives that create a new subprocess in which to run -a program. One of them, @code{start-process}, creates an asynchronous -process and returns a process object (@pxref{Asynchronous Processes}). -The other two, @code{call-process} and @code{call-process-region}, -create a synchronous process and do not return a process object -(@pxref{Synchronous Processes}). There are various higher-level -functions that make use of these primitives to run particular types of -process. - - Synchronous and asynchronous processes are explained in the following -sections. Since the three functions are all called in a similar -fashion, their common arguments are described here. - -@cindex execute program -@cindex @env{PATH} environment variable -@cindex @env{HOME} environment variable - In all cases, the function's @var{program} argument specifies the -program to be run. An error is signaled if the file is not found or -cannot be executed. If the file name is relative, the variable -@code{exec-path} contains a list of directories to search. Emacs -initializes @code{exec-path} when it starts up, based on the value of -the environment variable @env{PATH}. The standard file name -constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as -usual in @code{exec-path}, but environment variable substitutions -(@samp{$HOME}, etc.) are not recognized; use -@code{substitute-in-file-name} to perform them (@pxref{File Name -Expansion}). @code{nil} in this list refers to -@code{default-directory}. - - Executing a program can also try adding suffixes to the specified -name: - -@defvar exec-suffixes -This variable is a list of suffixes (strings) to try adding to the -specified program file name. The list should include @code{""} if you -want the name to be tried exactly as specified. The default value is -system-dependent. -@end defvar - - @strong{Please note:} The argument @var{program} contains only the -name of the program; it may not contain any command-line arguments. You -must use a separate argument, @var{args}, to provide those, as -described below. - - Each of the subprocess-creating functions has a @var{buffer-or-name} -argument that specifies where the standard output from the program will -go. It should be a buffer or a buffer name; if it is a buffer name, -that will create the buffer if it does not already exist. It can also -be @code{nil}, which says to discard the output unless a filter function -handles it. (@xref{Filter Functions}, and @ref{Read and Print}.) -Normally, you should avoid having multiple processes send output to the -same buffer because their output would be intermixed randomly. -For synchronous processes, you can send the output to a file instead -of a buffer. - -@cindex program arguments - All three of the subprocess-creating functions have a @code{&rest} -argument, @var{args}. The @var{args} must all be strings, and they are -supplied to @var{program} as separate command line arguments. Wildcard -characters and other shell constructs have no special meanings in these -strings, since the strings are passed directly to the specified program. - -@cindex environment variables, subprocesses - The subprocess inherits its environment from Emacs, but you can -specify overrides for it with @code{process-environment}. @xref{System -Environment}. The subprocess gets its current directory from the -value of @code{default-directory}. - -@defvar exec-directory -@pindex movemail -The value of this variable is a string, the name of a directory that -contains programs that come with GNU Emacs and are intended for Emacs -to invoke. The program @code{movemail} is an example of such a program; -Rmail uses it to fetch new mail from an inbox. -@end defvar - -@defopt exec-path -The value of this variable is a list of directories to search for -programs to run in subprocesses. Each element is either the name of a -directory (i.e., a string), or @code{nil}, which stands for the default -directory (which is the value of @code{default-directory}). -@cindex program directories - -The value of @code{exec-path} is used by @code{call-process} and -@code{start-process} when the @var{program} argument is not an absolute -file name. - -Generally, you should not modify @code{exec-path} directly. Instead, -ensure that your @env{PATH} environment variable is set appropriately -before starting Emacs. Trying to modify @code{exec-path} -independently of @env{PATH} can lead to confusing results. -@end defopt - -@node Shell Arguments -@section Shell Arguments -@cindex arguments for shell commands -@cindex shell command arguments - - Lisp programs sometimes need to run a shell and give it a command -that contains file names that were specified by the user. These -programs ought to be able to support any valid file name. But the shell -gives special treatment to certain characters, and if these characters -occur in the file name, they will confuse the shell. To handle these -characters, use the function @code{shell-quote-argument}: - -@defun shell-quote-argument argument -This function returns a string that represents, in shell syntax, -an argument whose actual contents are @var{argument}. It should -work reliably to concatenate the return value into a shell command -and then pass it to a shell for execution. - -Precisely what this function does depends on your operating system. The -function is designed to work with the syntax of your system's standard -shell; if you use an unusual shell, you will need to redefine this -function. - -@example -;; @r{This example shows the behavior on GNU and Unix systems.} -(shell-quote-argument "foo > bar") - @result{} "foo\\ \\>\\ bar" - -;; @r{This example shows the behavior on MS-DOS and MS-Windows.} -(shell-quote-argument "foo > bar") - @result{} "\"foo > bar\"" -@end example - -Here's an example of using @code{shell-quote-argument} to construct -a shell command: - -@example -(concat "diff -c " - (shell-quote-argument oldfile) - " " - (shell-quote-argument newfile)) -@end example -@end defun - -@cindex quoting and unquoting command-line arguments -@cindex minibuffer input, and command-line arguments -@cindex @code{call-process}, command-line arguments from minibuffer -@cindex @code{start-process}, command-line arguments from minibuffer - The following two functions are useful for combining a list of -individual command-line argument strings into a single string, and -taking a string apart into a list of individual command-line -arguments. These functions are mainly intended for -converting user input in the minibuffer, a Lisp string, into a list of -string arguments to be passed to @code{call-process} or -@code{start-process}, or for converting such lists of arguments into -a single Lisp string to be presented in the minibuffer or echo area. - -@defun split-string-and-unquote string &optional separators -This function splits @var{string} into substrings at matches for the -regular expression @var{separators}, like @code{split-string} does -(@pxref{Creating Strings}); in addition, it removes quoting from the -substrings. It then makes a list of the substrings and returns it. - -If @var{separators} is omitted or @code{nil}, it defaults to -@code{"\\s-+"}, which is a regular expression that matches one or more -characters with whitespace syntax (@pxref{Syntax Class Table}). - -This function supports two types of quoting: enclosing a whole string -in double quotes @code{"@dots{}"}, and quoting individual characters -with a backslash escape @samp{\}. The latter is also used in Lisp -strings, so this function can handle those as well. -@end defun - -@defun combine-and-quote-strings list-of-strings &optional separator -This function concatenates @var{list-of-strings} into a single string, -quoting each string as necessary. It also sticks the @var{separator} -string between each pair of strings; if @var{separator} is omitted or -@code{nil}, it defaults to @code{" "}. The return value is the -resulting string. - -The strings in @var{list-of-strings} that need quoting are those that -include @var{separator} as their substring. Quoting a string encloses -it in double quotes @code{"@dots{}"}. In the simplest case, if you -are consing a command from the individual command-line arguments, -every argument that includes embedded blanks will be quoted. -@end defun - -@node Synchronous Processes -@section Creating a Synchronous Process -@cindex synchronous subprocess - - After a @dfn{synchronous process} is created, Emacs waits for the -process to terminate before continuing. Starting Dired on GNU or -Unix@footnote{On other systems, Emacs uses a Lisp emulation of -@code{ls}; see @ref{Contents of Directories}.} is an example of this: it -runs @code{ls} in a synchronous process, then modifies the output -slightly. Because the process is synchronous, the entire directory -listing arrives in the buffer before Emacs tries to do anything with it. - - While Emacs waits for the synchronous subprocess to terminate, the -user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill -the subprocess with a @code{SIGINT} signal; but it waits until the -subprocess actually terminates before quitting. If during that time the -user types another @kbd{C-g}, that kills the subprocess instantly with -@code{SIGKILL} and quits immediately (except on MS-DOS, where killing -other processes doesn't work). @xref{Quitting}. - - The synchronous subprocess functions return an indication of how the -process terminated. - - The output from a synchronous subprocess is generally decoded using a -coding system, much like text read from a file. The input sent to a -subprocess by @code{call-process-region} is encoded using a coding -system, much like text written into a file. @xref{Coding Systems}. - -@defun call-process program &optional infile destination display &rest args -This function calls @var{program} and waits for it to finish. - -The standard input for the new process comes from file @var{infile} if -@var{infile} is not @code{nil}, and from the null device otherwise. -The argument @var{destination} says where to put the process output. -Here are the possibilities: - -@table @asis -@item a buffer -Insert the output in that buffer, before point. This includes both the -standard output stream and the standard error stream of the process. - -@item a string -Insert the output in a buffer with that name, before point. - -@item @code{t} -Insert the output in the current buffer, before point. - -@item @code{nil} -Discard the output. - -@item 0 -Discard the output, and return @code{nil} immediately without waiting -for the subprocess to finish. - -In this case, the process is not truly synchronous, since it can run in -parallel with Emacs; but you can think of it as synchronous in that -Emacs is essentially finished with the subprocess as soon as this -function returns. - -MS-DOS doesn't support asynchronous subprocesses, so this option doesn't -work there. - -@item @code{(:file @var{file-name})} -Send the output to the file name specified, overwriting it if it -already exists. - -@item @code{(@var{real-destination} @var{error-destination})} -Keep the standard output stream separate from the standard error stream; -deal with the ordinary output as specified by @var{real-destination}, -and dispose of the error output according to @var{error-destination}. -If @var{error-destination} is @code{nil}, that means to discard the -error output, @code{t} means mix it with the ordinary output, and a -string specifies a file name to redirect error output into. - -You can't directly specify a buffer to put the error output in; that is -too difficult to implement. But you can achieve this result by sending -the error output to a temporary file and then inserting the file into a -buffer. -@end table - -If @var{display} is non-@code{nil}, then @code{call-process} redisplays -the buffer as output is inserted. (However, if the coding system chosen -for decoding output is @code{undecided}, meaning deduce the encoding -from the actual data, then redisplay sometimes cannot continue once -non-@acronym{ASCII} characters are encountered. There are fundamental -reasons why it is hard to fix this; see @ref{Output from Processes}.) - -Otherwise the function @code{call-process} does no redisplay, and the -results become visible on the screen only when Emacs redisplays that -buffer in the normal course of events. - -The remaining arguments, @var{args}, are strings that specify command -line arguments for the program. - -The value returned by @code{call-process} (unless you told it not to -wait) indicates the reason for process termination. A number gives the -exit status of the subprocess; 0 means success, and any other value -means failure. If the process terminated with a signal, -@code{call-process} returns a string describing the signal. - -In the examples below, the buffer @samp{foo} is current. - -@smallexample -@group -(call-process "pwd" nil t) - @result{} 0 - ----------- Buffer: foo ---------- -/home/lewis/manual ----------- Buffer: foo ---------- -@end group - -@group -(call-process "grep" nil "bar" nil "lewis" "/etc/passwd") - @result{} 0 - ----------- Buffer: bar ---------- -lewis:x:1001:1001:Bil Lewis,,,,:/home/lewis:/bin/bash - ----------- Buffer: bar ---------- -@end group -@end smallexample - -Here is an example of the use of @code{call-process}, as used to -be found in the definition of the @code{insert-directory} function: - -@smallexample -@group -(call-process insert-directory-program nil t nil switches - (if full-directory-p - (concat (file-name-as-directory file) ".") - file)) -@end group -@end smallexample -@end defun - -@defun process-file program &optional infile buffer display &rest args -This function processes files synchronously in a separate process. It -is similar to @code{call-process}, but may invoke a file handler based -on the value of the variable @code{default-directory}, which specifies -the current working directory of the subprocess. - -The arguments are handled in almost the same way as for -@code{call-process}, with the following differences: - -Some file handlers may not support all combinations and forms of the -arguments @var{infile}, @var{buffer}, and @var{display}. For example, -some file handlers might behave as if @var{display} were @code{nil}, -regardless of the value actually passed. As another example, some -file handlers might not support separating standard output and error -output by way of the @var{buffer} argument. - -If a file handler is invoked, it determines the program to run based -on the first argument @var{program}. For instance, suppose that a -handler for remote files is invoked. Then the path that is used for -searching for the program might be different from @code{exec-path}. - -The second argument @var{infile} may invoke a file handler. The file -handler could be different from the handler chosen for the -@code{process-file} function itself. (For example, -@code{default-directory} could be on one remote host, and -@var{infile} on a different remote host. Or @code{default-directory} -could be non-special, whereas @var{infile} is on a remote host.) - -If @var{buffer} is a list of the form @code{(@var{real-destination} -@var{error-destination})}, and @var{error-destination} names a file, -then the same remarks as for @var{infile} apply. - -The remaining arguments (@var{args}) will be passed to the process -verbatim. Emacs is not involved in processing file names that are -present in @var{args}. To avoid confusion, it may be best to avoid -absolute file names in @var{args}, but rather to specify all file -names as relative to @code{default-directory}. The function -@code{file-relative-name} is useful for constructing such relative -file names. -@end defun - -@defvar process-file-side-effects -This variable indicates whether a call of @code{process-file} changes -remote files. - -By default, this variable is always set to @code{t}, meaning that a -call of @code{process-file} could potentially change any file on a -remote host. When set to @code{nil}, a file handler could optimize -its behavior with respect to remote file attribute caching. - -You should only ever change this variable with a let-binding; never -with @code{setq}. -@end defvar - -@defun call-process-region start end program &optional delete destination display &rest args -This function sends the text from @var{start} to @var{end} as -standard input to a process running @var{program}. It deletes the text -sent if @var{delete} is non-@code{nil}; this is useful when -@var{destination} is @code{t}, to insert the output in the current -buffer in place of the input. - -The arguments @var{destination} and @var{display} control what to do -with the output from the subprocess, and whether to update the display -as it comes in. For details, see the description of -@code{call-process}, above. If @var{destination} is the integer 0, -@code{call-process-region} discards the output and returns @code{nil} -immediately, without waiting for the subprocess to finish (this only -works if asynchronous subprocesses are supported; i.e. not on MS-DOS). - -The remaining arguments, @var{args}, are strings that specify command -line arguments for the program. - -The return value of @code{call-process-region} is just like that of -@code{call-process}: @code{nil} if you told it to return without -waiting; otherwise, a number or string which indicates how the -subprocess terminated. - -In the following example, we use @code{call-process-region} to run the -@code{cat} utility, with standard input being the first five characters -in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its -standard input into its standard output. Since the argument -@var{destination} is @code{t}, this output is inserted in the current -buffer. - -@smallexample -@group ----------- Buffer: foo ---------- -input@point{} ----------- Buffer: foo ---------- -@end group - -@group -(call-process-region 1 6 "cat" nil t) - @result{} 0 - ----------- Buffer: foo ---------- -inputinput@point{} ----------- Buffer: foo ---------- -@end group -@end smallexample - - For example, the @code{shell-command-on-region} command uses -@code{call-process-region} in a manner similar to this: - -@smallexample -@group -(call-process-region - start end - shell-file-name ; @r{name of program} - nil ; @r{do not delete region} - buffer ; @r{send output to @code{buffer}} - nil ; @r{no redisplay during output} - "-c" command) ; @r{arguments for the shell} -@end group -@end smallexample -@c It actually uses shell-command-switch, but no need to mention that here. -@end defun - -@defun call-process-shell-command command &optional infile destination display &rest args -This function executes the shell command @var{command} synchronously. -The final arguments @var{args} are additional arguments to add at the -end of @var{command}. The other arguments are handled as in -@code{call-process}. -@end defun - -@defun process-file-shell-command command &optional infile destination display &rest args -This function is like @code{call-process-shell-command}, but uses -@code{process-file} internally. Depending on @code{default-directory}, -@var{command} can be executed also on remote hosts. -@end defun - -@defun shell-command-to-string command -This function executes @var{command} (a string) as a shell command, -then returns the command's output as a string. -@end defun - -@c There is also shell-command-on-region, but that is more of a user -@c command, not something to use in programs. - -@defun process-lines program &rest args -This function runs @var{program}, waits for it to finish, and returns -its output as a list of strings. Each string in the list holds a -single line of text output by the program; the end-of-line characters -are stripped from each line. The arguments beyond @var{program}, -@var{args}, are strings that specify command-line arguments with which -to run the program. - -If @var{program} exits with a non-zero exit status, this function -signals an error. - -This function works by calling @code{call-process}, so program output -is decoded in the same way as for @code{call-process}. -@end defun - -@node Asynchronous Processes -@section Creating an Asynchronous Process -@cindex asynchronous subprocess - - After an @dfn{asynchronous process} is created, Emacs and the subprocess -both continue running immediately. The process thereafter runs -in parallel with Emacs, and the two can communicate with each other -using the functions described in the following sections. However, -communication is only partially asynchronous: Emacs sends data to the -process only when certain functions are called, and Emacs accepts data -from the process only when Emacs is waiting for input or for a time -delay. - - Here we describe how to create an asynchronous process. - -@defun start-process name buffer-or-name program &rest args -This function creates a new asynchronous subprocess and starts the -program @var{program} running in it. It returns a process object that -stands for the new subprocess in Lisp. The argument @var{name} -specifies the name for the process object; if a process with this name -already exists, then @var{name} is modified (by appending @samp{<1>}, -etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to -associate with the process. - -If @var{program} is @code{nil}, Emacs opens a new pseudoterminal (pty) -and associates its input and output with @var{buffer-or-name}, without -creating a subprocess. In that case, the remaining arguments -@var{args} are ignored. - -The remaining arguments, @var{args}, are strings that specify command -line arguments for the subprocess. - -In the example below, the first process is started and runs (rather, -sleeps) for 100 seconds (the output buffer @samp{foo} is created -immediately). Meanwhile, the second process is started, and -given the name @samp{my-process<1>} for the sake of uniqueness. It -inserts the directory listing at the end of the buffer @samp{foo}, -before the first process finishes. Then it finishes, and a message to -that effect is inserted in the buffer. Much later, the first process -finishes, and another message is inserted in the buffer for it. - -@smallexample -@group -(start-process "my-process" "foo" "sleep" "100") - @result{} # -@end group - -@group -(start-process "my-process" "foo" "ls" "-l" "/bin") - @result{} #> - ----------- Buffer: foo ---------- -total 8336 --rwxr-xr-x 1 root root 971384 Mar 30 10:14 bash --rwxr-xr-x 1 root root 146920 Jul 5 2011 bsd-csh -@dots{} --rwxr-xr-x 1 root root 696880 Feb 28 15:55 zsh4 - -Process my-process<1> finished - -Process my-process finished ----------- Buffer: foo ---------- -@end group -@end smallexample -@end defun - -@defun start-file-process name buffer-or-name program &rest args -Like @code{start-process}, this function starts a new asynchronous -subprocess running @var{program} in it, and returns its process -object. - -The difference from @code{start-process} is that this function may -invoked a file handler based on the value of @code{default-directory}. -This handler ought to run @var{program}, perhaps on the local host, -perhaps on a remote host that corresponds to @code{default-directory}. -In the latter case, the local part of @code{default-directory} becomes -the working directory of the process. - -This function does not try to invoke file name handlers for -@var{program} or for the @var{program-args}. - -Depending on the implementation of the file handler, it might not be -possible to apply @code{process-filter} or @code{process-sentinel} to -the resulting process object. @xref{Filter Functions}, and @ref{Sentinels}. - -@c FIXME Can we find a better example (i.e. a more modern function -@c that is actually documented). -Some file handlers may not support @code{start-file-process} (for -example the function @code{ange-ftp-hook-function}). In such cases, -this function does nothing and returns @code{nil}. -@end defun - -@defun start-process-shell-command name buffer-or-name command -This function is like @code{start-process}, except that it uses a shell -to execute the specified command. The argument @var{command} is a shell -command name. The variable @code{shell-file-name} specifies which shell to -use. - -The point of running a program through the shell, rather than directly -with @code{start-process}, is so that you can employ shell features such -as wildcards in the arguments. It follows that if you include any -arbitrary user-specified arguments in the command, you should quote them -with @code{shell-quote-argument} first, so that any special shell -characters do @emph{not} have their special shell meanings. @xref{Shell -Arguments}. Of course, when executing commands based on user input -you should also consider the security implications. -@end defun - -@defun start-file-process-shell-command name buffer-or-name command -This function is like @code{start-process-shell-command}, but uses -@code{start-file-process} internally. Because of this, @var{command} -can also be executed on remote hosts, depending on @code{default-directory}. -@end defun - -@defvar process-connection-type -@cindex pipes -@cindex @acronym{PTY}s -This variable controls the type of device used to communicate with -asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are -used, when available. Otherwise, pipes are used. - -@acronym{PTY}s are usually preferable for processes visible to the user, as -in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z}, -etc.) to work between the process and its children, whereas pipes do -not. For subprocesses used for internal purposes by programs, it is -often better to use a pipe, because they are more efficient. In -addition, the total number of @acronym{PTY}s is limited on many systems and -it is good not to waste them. - -The value of @code{process-connection-type} takes effect when -@code{start-process} is called. So you can specify how to communicate -with one subprocess by binding the variable around the call to -@code{start-process}. - -@smallexample -@group -(let ((process-connection-type nil)) ; @r{use a pipe} - (start-process @dots{})) -@end group -@end smallexample - -To determine whether a given subprocess actually got a pipe or a -@acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process -Information}). -@end defvar - -@node Deleting Processes -@section Deleting Processes -@cindex deleting processes - - @dfn{Deleting a process} disconnects Emacs immediately from the -subprocess. Processes are deleted automatically after they terminate, -but not necessarily right away. You can delete a process explicitly -at any time. If you explicitly delete a terminated process before it -is deleted automatically, no harm results. Deleting a running -process sends a signal to terminate it (and its child processes, if -any), and calls the process sentinel if it has one. @xref{Sentinels}. - - When a process is deleted, the process object itself continues to -exist as long as other Lisp objects point to it. All the Lisp -primitives that work on process objects accept deleted processes, but -those that do I/O or send signals will report an error. The process -mark continues to point to the same place as before, usually into a -buffer where output from the process was being inserted. - -@defopt delete-exited-processes -This variable controls automatic deletion of processes that have -terminated (due to calling @code{exit} or to a signal). If it is -@code{nil}, then they continue to exist until the user runs -@code{list-processes}. Otherwise, they are deleted immediately after -they exit. -@end defopt - -@defun delete-process process -This function deletes a process, killing it with a @code{SIGKILL} -signal. The argument may be a process, the name of a process, a -buffer, or the name of a buffer. (A buffer or buffer-name stands for -the process that @code{get-buffer-process} returns.) Calling -@code{delete-process} on a running process terminates it, updates the -process status, and runs the sentinel (if any) immediately. If the -process has already terminated, calling @code{delete-process} has no -effect on its status, or on the running of its sentinel (which will -happen sooner or later). - -@smallexample -@group -(delete-process "*shell*") - @result{} nil -@end group -@end smallexample -@end defun - -@node Process Information -@section Process Information - - Several functions return information about processes. - -@deffn Command list-processes &optional query-only buffer -This command displays a listing of all living processes. In addition, -it finally deletes any process whose status was @samp{Exited} or -@samp{Signaled}. It returns @code{nil}. - -The processes are shown in a buffer named @file{*Process List*} -(unless you specify otherwise using the optional argument @var{buffer}), -whose major mode is Process Menu mode. - -If @var{query-only} is non-@code{nil}, it only lists processes -whose query flag is non-@code{nil}. @xref{Query Before Exit}. -@end deffn - -@defun process-list -This function returns a list of all processes that have not been deleted. - -@smallexample -@group -(process-list) - @result{} (# #) -@end group -@end smallexample -@end defun - -@defun get-process name -This function returns the process named @var{name} (a string), or -@code{nil} if there is none. - -@smallexample -@group -(get-process "shell") - @result{} # -@end group -@end smallexample -@end defun - -@defun process-command process -This function returns the command that was executed to start -@var{process}. This is a list of strings, the first string being the -program executed and the rest of the strings being the arguments that -were given to the program. - -@smallexample -@group -(process-command (get-process "shell")) - @result{} ("bash" "-i") -@end group -@end smallexample -@end defun - -@defun process-contact process &optional key - -This function returns information about how a network or serial -process was set up. When @var{key} is @code{nil}, it returns -@code{(@var{hostname} @var{service})} for a network process, and -@code{(@var{port} @var{speed})} for a serial process. -For an ordinary child process, this function always returns @code{t}. - -If @var{key} is @code{t}, the value is the complete status information -for the connection, server, or serial port; that is, the list of -keywords and values specified in @code{make-network-process} or -@code{make-serial-process}, except that some of the values represent -the current status instead of what you specified. - -For a network process, the values include (see -@code{make-network-process} for a complete list): - -@table @code -@item :buffer -The associated value is the process buffer. -@item :filter -The associated value is the process filter function. -@item :sentinel -The associated value is the process sentinel function. -@item :remote -In a connection, the address in internal format of the remote peer. -@item :local -The local address, in internal format. -@item :service -In a server, if you specified @code{t} for @var{service}, -this value is the actual port number. -@end table - -@code{:local} and @code{:remote} are included even if they were not -specified explicitly in @code{make-network-process}. - -For a serial process, see @code{make-serial-process} and -@code{serial-process-configure} for a list of keys. - -If @var{key} is a keyword, the function returns the value corresponding -to that keyword. -@end defun - -@defun process-id process -This function returns the @acronym{PID} of @var{process}. This is an -integer that distinguishes the process @var{process} from all other -processes running on the same computer at the current time. The -@acronym{PID} of a process is chosen by the operating system kernel when the -process is started and remains constant as long as the process exists. -@end defun - -@defun process-name process -This function returns the name of @var{process}, as a string. -@end defun - -@defun process-status process-name -This function returns the status of @var{process-name} as a symbol. -The argument @var{process-name} must be a process, a buffer, or a -process name (a string). - -The possible values for an actual subprocess are: - -@table @code -@item run -for a process that is running. -@item stop -for a process that is stopped but continuable. -@item exit -for a process that has exited. -@item signal -for a process that has received a fatal signal. -@item open -for a network connection that is open. -@item closed -for a network connection that is closed. Once a connection -is closed, you cannot reopen it, though you might be able to open -a new connection to the same place. -@item connect -for a non-blocking connection that is waiting to complete. -@item failed -for a non-blocking connection that has failed to complete. -@item listen -for a network server that is listening. -@item nil -if @var{process-name} is not the name of an existing process. -@end table - -@smallexample -@group -(process-status (get-buffer "*shell*")) - @result{} run -@end group -@end smallexample - -For a network connection, @code{process-status} returns one of the symbols -@code{open} or @code{closed}. The latter means that the other side -closed the connection, or Emacs did @code{delete-process}. -@end defun - -@defun process-live-p process -This function returns non-@code{nil} if @var{process} is alive. A -process is considered alive if its status is @code{run}, @code{open}, -@code{listen}, @code{connect} or @code{stop}. -@end defun - -@defun process-type process -This function returns the symbol @code{network} for a network -connection or server, @code{serial} for a serial port connection, or -@code{real} for a real subprocess. -@end defun - -@defun process-exit-status process -This function returns the exit status of @var{process} or the signal -number that killed it. (Use the result of @code{process-status} to -determine which of those it is.) If @var{process} has not yet -terminated, the value is 0. -@end defun - -@defun process-tty-name process -This function returns the terminal name that @var{process} is using for -its communication with Emacs---or @code{nil} if it is using pipes -instead of a terminal (see @code{process-connection-type} in -@ref{Asynchronous Processes}). If @var{process} represents a program -running on a remote host, the terminal name used by that program on -the remote host is provided as process property @code{remote-tty}. -@end defun - -@defun process-coding-system process -@anchor{Coding systems for a subprocess} -This function returns a cons cell @code{(@var{decode} . @var{encode})}, -describing the coding systems in use for decoding output from, and -encoding input to, @var{process} (@pxref{Coding Systems}). -@end defun - -@defun set-process-coding-system process &optional decoding-system encoding-system -This function specifies the coding systems to use for subsequent output -from and input to @var{process}. It will use @var{decoding-system} to -decode subprocess output, and @var{encoding-system} to encode subprocess -input. -@end defun - - Every process also has a property list that you can use to store -miscellaneous values associated with the process. - -@defun process-get process propname -This function returns the value of the @var{propname} property -of @var{process}. -@end defun - -@defun process-put process propname value -This function sets the value of the @var{propname} property -of @var{process} to @var{value}. -@end defun - -@defun process-plist process -This function returns the process plist of @var{process}. -@end defun - -@defun set-process-plist process plist -This function sets the process plist of @var{process} to @var{plist}. -@end defun - -@node Input to Processes -@section Sending Input to Processes -@cindex process input - - Asynchronous subprocesses receive input when it is sent to them by -Emacs, which is done with the functions in this section. You must -specify the process to send input to, and the input data to send. The -data appears on the ``standard input'' of the subprocess. - -@c FIXME which? - Some operating systems have limited space for buffered input in a -@acronym{PTY}. On these systems, Emacs sends an @acronym{EOF} -periodically amidst the other characters, to force them through. For -most programs, these @acronym{EOF}s do no harm. - - Subprocess input is normally encoded using a coding system before the -subprocess receives it, much like text written into a file. You can use -@code{set-process-coding-system} to specify which coding system to use -(@pxref{Process Information}). Otherwise, the coding system comes from -@code{coding-system-for-write}, if that is non-@code{nil}; or else from -the defaulting mechanism (@pxref{Default Coding Systems}). - - Sometimes the system is unable to accept input for that process, -because the input buffer is full. When this happens, the send functions -wait a short while, accepting output from subprocesses, and then try -again. This gives the subprocess a chance to read more of its pending -input and make space in the buffer. It also allows filters, sentinels -and timers to run---so take account of that in writing your code. - - In these functions, the @var{process} argument can be a process or -the name of a process, or a buffer or buffer name (which stands -for a process via @code{get-buffer-process}). @code{nil} means -the current buffer's process. - -@defun process-send-string process string -This function sends @var{process} the contents of @var{string} as -standard input. It returns @code{nil}. For example, to make a -Shell buffer list files: - -@smallexample -@group -(process-send-string "shell<1>" "ls\n") - @result{} nil -@end group -@end smallexample -@end defun - -@defun process-send-region process start end -This function sends the text in the region defined by @var{start} and -@var{end} as standard input to @var{process}. - -An error is signaled unless both @var{start} and @var{end} are -integers or markers that indicate positions in the current buffer. (It -is unimportant which number is larger.) -@end defun - -@defun process-send-eof &optional process -This function makes @var{process} see an end-of-file in its -input. The @acronym{EOF} comes after any text already sent to it. -The function returns @var{process}. - -@smallexample -@group -(process-send-eof "shell") - @result{} "shell" -@end group -@end smallexample -@end defun - -@defun process-running-child-p &optional process -This function will tell you whether a @var{process} has given control of -its terminal to its own child process. The value is @code{t} if this is -true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain -that this is not so. -@end defun - -@node Signals to Processes -@section Sending Signals to Processes -@cindex process signals -@cindex sending signals -@cindex signals - - @dfn{Sending a signal} to a subprocess is a way of interrupting its -activities. There are several different signals, each with its own -meaning. The set of signals and their names is defined by the operating -system. For example, the signal @code{SIGINT} means that the user has -typed @kbd{C-c}, or that some analogous thing has happened. - - Each signal has a standard effect on the subprocess. Most signals -kill the subprocess, but some stop (or resume) execution instead. Most -signals can optionally be handled by programs; if the program handles -the signal, then we can say nothing in general about its effects. - - You can send signals explicitly by calling the functions in this -section. Emacs also sends signals automatically at certain times: -killing a buffer sends a @code{SIGHUP} signal to all its associated -processes; killing Emacs sends a @code{SIGHUP} signal to all remaining -processes. (@code{SIGHUP} is a signal that usually indicates that the -user ``hung up the phone'', i.e., disconnected.) - - Each of the signal-sending functions takes two optional arguments: -@var{process} and @var{current-group}. - - The argument @var{process} must be either a process, a process -name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name -stands for a process through @code{get-buffer-process}. @code{nil} -stands for the process associated with the current buffer. An error -is signaled if @var{process} does not identify a process. - - The argument @var{current-group} is a flag that makes a difference -when you are running a job-control shell as an Emacs subprocess. If it -is non-@code{nil}, then the signal is sent to the current process-group -of the terminal that Emacs uses to communicate with the subprocess. If -the process is a job-control shell, this means the shell's current -subjob. If it is @code{nil}, the signal is sent to the process group of -the immediate subprocess of Emacs. If the subprocess is a job-control -shell, this is the shell itself. - - The flag @var{current-group} has no effect when a pipe is used to -communicate with the subprocess, because the operating system does not -support the distinction in the case of pipes. For the same reason, -job-control shells won't work when a pipe is used. See -@code{process-connection-type} in @ref{Asynchronous Processes}. - -@defun interrupt-process &optional process current-group -This function interrupts the process @var{process} by sending the -signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt -character'' (normally @kbd{C-c} on some systems, and @key{DEL} on -others) sends this signal. When the argument @var{current-group} is -non-@code{nil}, you can think of this function as ``typing @kbd{C-c}'' -on the terminal by which Emacs talks to the subprocess. -@end defun - -@defun kill-process &optional process current-group -This function kills the process @var{process} by sending the -signal @code{SIGKILL}. This signal kills the subprocess immediately, -and cannot be handled by the subprocess. -@end defun - -@defun quit-process &optional process current-group -This function sends the signal @code{SIGQUIT} to the process -@var{process}. This signal is the one sent by the ``quit -@c FIXME? Never heard of C-b being used for this. In readline, eg -@c bash, that is backward-word. -character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside -Emacs. -@end defun - -@defun stop-process &optional process current-group -This function stops the process @var{process} by sending the -signal @code{SIGTSTP}. Use @code{continue-process} to resume its -execution. - -Outside of Emacs, on systems with job control, the ``stop character'' -(usually @kbd{C-z}) normally sends this signal. When -@var{current-group} is non-@code{nil}, you can think of this function as -``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the -subprocess. -@end defun - -@defun continue-process &optional process current-group -This function resumes execution of the process @var{process} by sending -it the signal @code{SIGCONT}. This presumes that @var{process} was -stopped previously. -@end defun - -@deffn Command signal-process process signal -This function sends a signal to process @var{process}. The argument -@var{signal} specifies which signal to send; it should be an integer, -or a symbol whose name is a signal. - -The @var{process} argument can be a system process @acronym{ID} (an -integer); that allows you to send signals to processes that are not -children of Emacs. @xref{System Processes}. -@end deffn - -@node Output from Processes -@section Receiving Output from Processes -@cindex process output -@cindex output from processes - - There are two ways to receive the output that a subprocess writes to -its standard output stream. The output can be inserted in a buffer, -which is called the associated buffer of the process (@pxref{Process -Buffers}), or a function called the @dfn{filter function} can be -called to act on the output. If the process has no buffer and no -filter function, its output is discarded. - - When a subprocess terminates, Emacs reads any pending output, -then stops reading output from that subprocess. Therefore, if the -subprocess has children that are still live and still producing -output, Emacs won't receive that output. - - Output from a subprocess can arrive only while Emacs is waiting: when -reading terminal input (see the function @code{waiting-for-user-input-p}), -in @code{sit-for} and @code{sleep-for} (@pxref{Waiting}), and in -@code{accept-process-output} (@pxref{Accepting Output}). This -minimizes the problem of timing errors that usually plague parallel -programming. For example, you can safely create a process and only -then specify its buffer or filter function; no output can arrive -before you finish, if the code in between does not call any primitive -that waits. - -@defvar process-adaptive-read-buffering -On some systems, when Emacs reads the output from a subprocess, the -output data is read in very small blocks, potentially resulting in -very poor performance. This behavior can be remedied to some extent -by setting the variable @code{process-adaptive-read-buffering} to a -non-@code{nil} value (the default), as it will automatically delay reading -from such processes, thus allowing them to produce more output before -Emacs tries to read it. -@end defvar - - It is impossible to separate the standard output and standard error -streams of the subprocess, because Emacs normally spawns the subprocess -inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If -you want to keep the output to those streams separate, you should -redirect one of them to a file---for example, by using an appropriate -shell command. - -@menu -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Decoding Output:: Filters can get unibyte or multibyte strings. -* Accepting Output:: How to wait until process output arrives. -@end menu - -@node Process Buffers -@subsection Process Buffers - - A process can (and usually does) have an @dfn{associated buffer}, -which is an ordinary Emacs buffer that is used for two purposes: storing -the output from the process, and deciding when to kill the process. You -can also use the buffer to identify a process to operate on, since in -normal practice only one process is associated with any given buffer. -Many applications of processes also use the buffer for editing input to -be sent to the process, but this is not built into Emacs Lisp. - - Unless the process has a filter function (@pxref{Filter Functions}), -its output is inserted in the associated buffer. The position to insert -the output is determined by the @code{process-mark}, which is then -updated to point to the end of the text just inserted. Usually, but not -always, the @code{process-mark} is at the end of the buffer. - -@findex process-kill-buffer-query-function - Killing the associated buffer of a process also kills the process. -Emacs asks for confirmation first, if the process's -@code{process-query-on-exit-flag} is non-@code{nil} (@pxref{Query -Before Exit}). This confirmation is done by the function -@code{process-kill-buffer-query-function}, which is run from -@code{kill-buffer-query-functions} (@pxref{Killing Buffers}). - -@defun process-buffer process -This function returns the associated buffer of the process -@var{process}. - -@smallexample -@group -(process-buffer (get-process "shell")) - @result{} # -@end group -@end smallexample -@end defun - -@defun process-mark process -This function returns the process marker for @var{process}, which is the -marker that says where to insert output from the process. - -If @var{process} does not have a buffer, @code{process-mark} returns a -marker that points nowhere. - -Insertion of process output in a buffer uses this marker to decide where -to insert, and updates it to point after the inserted text. That is why -successive batches of output are inserted consecutively. - -Filter functions normally should use this marker in the same fashion -as is done by direct insertion of output in the buffer. For an -example of a filter function that uses @code{process-mark}, -@pxref{Process Filter Example}. - -When the user is expected to enter input in the process buffer for -transmission to the process, the process marker separates the new input -from previous output. -@end defun - -@defun set-process-buffer process buffer -This function sets the buffer associated with @var{process} to -@var{buffer}. If @var{buffer} is @code{nil}, the process becomes -associated with no buffer. -@end defun - -@defun get-buffer-process buffer-or-name -This function returns a nondeleted process associated with the buffer -specified by @var{buffer-or-name}. If there are several processes -associated with it, this function chooses one (currently, the one most -recently created, but don't count on that). Deletion of a process -(see @code{delete-process}) makes it ineligible for this function to -return. - -It is usually a bad idea to have more than one process associated with -the same buffer. - -@smallexample -@group -(get-buffer-process "*shell*") - @result{} # -@end group -@end smallexample - -Killing the process's buffer deletes the process, which kills the -subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}). -@end defun - -@node Filter Functions -@subsection Process Filter Functions -@cindex filter function -@cindex process filter - - A process @dfn{filter function} is a function that receives the -standard output from the associated process. If a process has a filter, -then @emph{all} output from that process is passed to the filter. The -process buffer is used directly for output from the process only when -there is no filter. - - The filter function can only be called when Emacs is waiting for -something, because process output arrives only at such times. Emacs -waits when reading terminal input (see the function -@code{waiting-for-user-input-p}), in @code{sit-for} and -@code{sleep-for} (@pxref{Waiting}), and in -@code{accept-process-output} (@pxref{Accepting Output}). - - A filter function must accept two arguments: the associated process -and a string, which is output just received from it. The function is -then free to do whatever it chooses with the output. - -@c Note this text is duplicated in the sentinels section. - Quitting is normally inhibited within a filter function---otherwise, -the effect of typing @kbd{C-g} at command level or to quit a user -command would be unpredictable. If you want to permit quitting inside -a filter function, bind @code{inhibit-quit} to @code{nil}. In most -cases, the right way to do this is with the macro -@code{with-local-quit}. @xref{Quitting}. - - If an error happens during execution of a filter function, it is -caught automatically, so that it doesn't stop the execution of whatever -program was running when the filter function was started. However, if -@code{debug-on-error} is non-@code{nil}, errors are not caught. -This makes it possible to use the Lisp debugger to debug the -filter function. @xref{Debugger}. - - Many filter functions sometimes (or always) insert the output in the -process's buffer, mimicking the actions of Emacs when there is no -filter. Such filter functions need to make sure that they save the -current buffer, select the correct buffer (if different) before -inserting output, and then restore the original buffer. -They should also check whether the buffer is still alive, update the -process marker, and in some cases update the value of point. Here is -how to do these things: - -@anchor{Process Filter Example} -@smallexample -@group -(defun ordinary-insertion-filter (proc string) - (when (buffer-live-p (process-buffer proc)) - (with-current-buffer (process-buffer proc) - (let ((moving (= (point) (process-mark proc)))) -@end group -@group - (save-excursion - ;; @r{Insert the text, advancing the process marker.} - (goto-char (process-mark proc)) - (insert string) - (set-marker (process-mark proc) (point))) - (if moving (goto-char (process-mark proc))))))) -@end group -@end smallexample - - To make the filter force the process buffer to be visible whenever new -text arrives, you could insert a line like the following just before the -@code{with-current-buffer} construct: - -@smallexample -(display-buffer (process-buffer proc)) -@end smallexample - - To force point to the end of the new output, no matter where it was -previously, eliminate the variable @code{moving} and call -@code{goto-char} unconditionally. - -@ignore - In earlier Emacs versions, every filter function that did regular -expression searching or matching had to explicitly save and restore the -match data. Now Emacs does this automatically for filter functions; -they never need to do it explicitly. -@end ignore - Note that Emacs automatically saves and restores the match data -while executing filter functions. @xref{Match Data}. - - The output to the filter may come in chunks of any size. A program -that produces the same output twice in a row may send it as one batch of -200 characters one time, and five batches of 40 characters the next. If -the filter looks for certain text strings in the subprocess output, make -sure to handle the case where one of these strings is split across two -or more batches of output; one way to do this is to insert the -received text into a temporary buffer, which can then be searched. - -@defun set-process-filter process filter -This function gives @var{process} the filter function @var{filter}. If -@var{filter} is @code{nil}, it gives the process no filter. -@end defun - -@defun process-filter process -This function returns the filter function of @var{process}, or @code{nil} -if it has none. -@end defun - - Here is an example of the use of a filter function: - -@smallexample -@group -(defun keep-output (process output) - (setq kept (cons output kept))) - @result{} keep-output -@end group -@group -(setq kept nil) - @result{} nil -@end group -@group -(set-process-filter (get-process "shell") 'keep-output) - @result{} keep-output -@end group -@group -(process-send-string "shell" "ls ~/other\n") - @result{} nil -kept - @result{} ("lewis@@slug:$ " -@end group -@group -"FINAL-W87-SHORT.MSS backup.otl kolstad.mss~ -address.txt backup.psf kolstad.psf -backup.bib~ david.mss resume-Dec-86.mss~ -backup.err david.psf resume-Dec.psf -backup.mss dland syllabus.mss -" -"#backups.mss# backup.mss~ kolstad.mss -") -@end group -@end smallexample - -@ignore @c The code in this example doesn't show the right way to do things. -Here is another, more realistic example, which demonstrates how to use -the process mark to do insertion in the same fashion as is done when -there is no filter function: - -@smallexample -@group -;; @r{Insert input in the buffer specified by @code{my-shell-buffer}} -;; @r{and make sure that buffer is shown in some window.} -(defun my-process-filter (proc str) - (let ((cur (selected-window)) - (pop-up-windows t)) - (pop-to-buffer my-shell-buffer) -@end group -@group - (goto-char (point-max)) - (insert str) - (set-marker (process-mark proc) (point-max)) - (select-window cur))) -@end group -@end smallexample -@end ignore - -@node Decoding Output -@subsection Decoding Process Output -@cindex decode process output - - When Emacs writes process output directly into a multibyte buffer, -it decodes the output according to the process output coding system. -If the coding system is @code{raw-text} or @code{no-conversion}, Emacs -converts the unibyte output to multibyte using -@code{string-to-multibyte}, and inserts the resulting multibyte text. - - You can use @code{set-process-coding-system} to specify which coding -system to use (@pxref{Process Information}). Otherwise, the coding -system comes from @code{coding-system-for-read}, if that is -non-@code{nil}; or else from the defaulting mechanism (@pxref{Default -Coding Systems}). If the text output by a process contains null -bytes, Emacs by default uses @code{no-conversion} for it; see -@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to -control this behavior. - - @strong{Warning:} Coding systems such as @code{undecided}, which -determine the coding system from the data, do not work entirely -reliably with asynchronous subprocess output. This is because Emacs -has to process asynchronous subprocess output in batches, as it -arrives. Emacs must try to detect the proper coding system from one -batch at a time, and this does not always work. Therefore, if at all -possible, specify a coding system that determines both the character -code conversion and the end of line conversion---that is, one like -@code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}. - -@c Let's keep the index entries that were there for -@c set-process-filter-multibyte and process-filter-multibyte-p, -@cindex filter multibyte flag, of process -@cindex process filter multibyte flag - When Emacs calls a process filter function, it provides the process -output as a multibyte string or as a unibyte string according to the -process's filter coding system. Emacs -decodes the output according to the process output coding system, -which usually produces a multibyte string, except for coding systems -such as @code{binary} and @code{raw-text}. - -@node Accepting Output -@subsection Accepting Output from Processes -@cindex accept input from processes - - Output from asynchronous subprocesses normally arrives only while -Emacs is waiting for some sort of external event, such as elapsed time -or terminal input. Occasionally it is useful in a Lisp program to -explicitly permit output to arrive at a specific point, or even to wait -until output arrives from a process. - -@defun accept-process-output &optional process seconds millisec just-this-one -This function allows Emacs to read pending output from processes. The -output is inserted in the associated buffers or given to their filter -functions. If @var{process} is non-@code{nil} then this function does -not return until some output has been received from @var{process}. - -The arguments @var{seconds} and @var{millisec} let you specify timeout -periods. The former specifies a period measured in seconds and the -latter specifies one measured in milliseconds. The two time periods -thus specified are added together, and @code{accept-process-output} -returns after that much time, whether or not there has been any -subprocess output. - -The argument @var{millisec} is obsolete (and should not be used), -because @var{seconds} can be a floating point number to specify -waiting a fractional number of seconds. If @var{seconds} is 0, the -function accepts whatever output is pending but does not wait. - -@c Emacs 22.1 feature -If @var{process} is a process, and the argument @var{just-this-one} is -non-@code{nil}, only output from that process is handled, suspending output -from other processes until some output has been received from that -process or the timeout expires. If @var{just-this-one} is an integer, -also inhibit running timers. This feature is generally not -recommended, but may be necessary for specific applications, such as -speech synthesis. - -The function @code{accept-process-output} returns non-@code{nil} if it -did get some output, or @code{nil} if the timeout expired before output -arrived. -@end defun - -@node Sentinels -@section Sentinels: Detecting Process Status Changes -@cindex process sentinel -@cindex sentinel (of process) - - A @dfn{process sentinel} is a function that is called whenever the -associated process changes status for any reason, including signals -(whether sent by Emacs or caused by the process's own actions) that -terminate, stop, or continue the process. The process sentinel is -also called if the process exits. The sentinel receives two -arguments: the process for which the event occurred, and a string -describing the type of event. - - The string describing the event looks like one of the following: - -@c FIXME? Also "killed\n" - see example below? -@itemize @bullet -@item -@code{"finished\n"}. - -@item -@code{"exited abnormally with code @var{exitcode}\n"}. - -@item -@code{"@var{name-of-signal}\n"}. - -@item -@code{"@var{name-of-signal} (core dumped)\n"}. -@end itemize - - A sentinel runs only while Emacs is waiting (e.g., for terminal -input, or for time to elapse, or for process output). This avoids the -timing errors that could result from running sentinels at random places in -the middle of other Lisp programs. A program can wait, so that -sentinels will run, by calling @code{sit-for} or @code{sleep-for} -(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting -Output}). Emacs also allows sentinels to run when the command loop is -reading input. @code{delete-process} calls the sentinel when it -terminates a running process. - - Emacs does not keep a queue of multiple reasons to call the sentinel -of one process; it records just the current status and the fact that -there has been a change. Therefore two changes in status, coming in -quick succession, can call the sentinel just once. However, process -termination will always run the sentinel exactly once. This is -because the process status can't change again after termination. - - Emacs explicitly checks for output from the process before running -the process sentinel. Once the sentinel runs due to process -termination, no further output can arrive from the process. - - A sentinel that writes the output into the buffer of the process -should check whether the buffer is still alive. If it tries to insert -into a dead buffer, it will get an error. If the buffer is dead, -@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. - -@c Note this text is duplicated in the filter functions section. - Quitting is normally inhibited within a sentinel---otherwise, the -effect of typing @kbd{C-g} at command level or to quit a user command -would be unpredictable. If you want to permit quitting inside a -sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the -right way to do this is with the macro @code{with-local-quit}. -@xref{Quitting}. - - If an error happens during execution of a sentinel, it is caught -automatically, so that it doesn't stop the execution of whatever -programs was running when the sentinel was started. However, if -@code{debug-on-error} is non-@code{nil}, errors are not caught. -This makes it possible to use the Lisp debugger to debug the -sentinel. @xref{Debugger}. - - While a sentinel is running, the process sentinel is temporarily -set to @code{nil} so that the sentinel won't run recursively. -For this reason it is not possible for a sentinel to specify -a new sentinel. - -@ignore - In earlier Emacs versions, every sentinel that did regular expression -searching or matching had to explicitly save and restore the match data. -Now Emacs does this automatically for sentinels; they never need to do -it explicitly. -@end ignore - Note that Emacs automatically saves and restores the match data -while executing sentinels. @xref{Match Data}. - -@defun set-process-sentinel process sentinel -This function associates @var{sentinel} with @var{process}. If -@var{sentinel} is @code{nil}, then the process will have no sentinel. -The default behavior when there is no sentinel is to insert a message in -the process's buffer when the process status changes. - -Changes in process sentinels take effect immediately---if the sentinel -is slated to be run but has not been called yet, and you specify a new -sentinel, the eventual call to the sentinel will use the new one. - -@smallexample -@group -(defun msg-me (process event) - (princ - (format "Process: %s had the event `%s'" process event))) -(set-process-sentinel (get-process "shell") 'msg-me) - @result{} msg-me -@end group -@group -(kill-process (get-process "shell")) - @print{} Process: # had the event `killed' - @result{} # -@end group -@end smallexample -@end defun - -@defun process-sentinel process -This function returns the sentinel of @var{process}, or @code{nil} if it -has none. -@end defun - -@defun waiting-for-user-input-p -While a sentinel or filter function is running, this function returns -non-@code{nil} if Emacs was waiting for keyboard input from the user at -the time the sentinel or filter function was called, or @code{nil} if it -was not. -@end defun - -@node Query Before Exit -@section Querying Before Exit - - When Emacs exits, it terminates all its subprocesses by sending them -the @code{SIGHUP} signal. Because subprocesses may be doing -valuable work, Emacs normally asks the user to confirm that it is ok -to terminate them. Each process has a query flag, which, if -non-@code{nil}, says that Emacs should ask for confirmation before -exiting and thus killing that process. The default for the query flag -is @code{t}, meaning @emph{do} query. - -@defun process-query-on-exit-flag process -This returns the query flag of @var{process}. -@end defun - -@defun set-process-query-on-exit-flag process flag -This function sets the query flag of @var{process} to @var{flag}. It -returns @var{flag}. - -Here is an example of using @code{set-process-query-on-exit-flag} on a -shell process to avoid querying: - -@smallexample -@group -(set-process-query-on-exit-flag (get-process "shell") nil) - @result{} nil -@end group -@end smallexample -@end defun - -@node System Processes -@section Accessing Other Processes -@cindex system processes - - In addition to accessing and manipulating processes that are -subprocesses of the current Emacs session, Emacs Lisp programs can -also access other processes running on the same machine. We call -these @dfn{system processes}, to distinguish them from Emacs -subprocesses. - - Emacs provides several primitives for accessing system processes. -Not all platforms support these primitives; on those which don't, -these primitives return @code{nil}. - -@defun list-system-processes -This function returns a list of all the processes running on the -system. Each process is identified by its @acronym{PID}, a numerical -process ID that is assigned by the OS and distinguishes the process -from all the other processes running on the same machine at the same -time. -@end defun - -@defun process-attributes pid -This function returns an alist of attributes for the process specified -by its process ID @var{pid}. Each association in the alist is of the -form @code{(@var{key} . @var{value})}, where @var{key} designates the -attribute and @var{value} is the value of that attribute. The various -attribute @var{key}s that this function can return are listed below. -Not all platforms support all of these attributes; if an attribute is -not supported, its association will not appear in the returned alist. -Values that are numbers can be either integer or floating-point, -depending on the magnitude of the value. - -@table @code -@item euid -The effective user ID of the user who invoked the process. The -corresponding @var{value} is a number. If the process was invoked by -the same user who runs the current Emacs session, the value is -identical to what @code{user-uid} returns (@pxref{User -Identification}). - -@item user -User name corresponding to the process's effective user ID, a string. - -@item egid -The group ID of the effective user ID, a number. - -@item group -Group name corresponding to the effective user's group ID, a string. - -@item comm -The name of the command that runs in the process. This is a string -that usually specifies the name of the executable file of the process, -without the leading directories. However, some special system -processes can report strings that do not correspond to an executable -file of a program. - -@item state -The state code of the process. This is a short string that encodes -the scheduling state of the process. Here's a list of the most -frequently seen codes: - -@table @code -@item "D" -uninterruptible sleep (usually I/O) -@item "R" -running -@item "S" -interruptible sleep (waiting for some event) -@item "T" -stopped, e.g., by a job control signal -@item "Z" -``zombie'': a process that terminated, but was not reaped by its parent -@end table - -@noindent -For the full list of the possible states, see the manual page of the -@command{ps} command. - -@item ppid -The process ID of the parent process, a number. - -@item pgrp -The process group ID of the process, a number. - -@item sess -The session ID of the process. This is a number that is the process -ID of the process's @dfn{session leader}. - -@item ttname -A string that is the name of the process's controlling terminal. On -Unix and GNU systems, this is normally the file name of the -corresponding terminal device, such as @file{/dev/pts65}. - -@item tpgid -The numerical process group ID of the foreground process group that -uses the process's terminal. - -@item minflt -The number of minor page faults caused by the process since its -beginning. (Minor page faults are those that don't involve reading -from disk.) - -@item majflt -The number of major page faults caused by the process since its -beginning. (Major page faults require a disk to be read, and are thus -more expensive than minor page faults.) - -@item cminflt -@itemx cmajflt -Like @code{minflt} and @code{majflt}, but include the number of page -faults for all the child processes of the given process. - -@item utime -Time spent by the process in the user context, for running the -application's code. The corresponding @var{value} is in the -@w{@code{(@var{high} @var{low} @var{microsec})}} format, the same -format used by functions @code{current-time} (@pxref{Time of Day, -current-time}) and @code{file-attributes} (@pxref{File Attributes}). - -@item stime -Time spent by the process in the system (kernel) context, for -processing system calls. The corresponding @var{value} is in the same -format as for @code{utime}. - -@item time -The sum of @code{utime} and @code{stime}. The corresponding -@var{value} is in the same format as for @code{utime}. - -@item cutime -@itemx cstime -@itemx ctime -Like @code{utime}, @code{stime}, and @code{time}, but include the -times of all the child processes of the given process. - -@item pri -The numerical priority of the process. - -@item nice -The @dfn{nice value} of the process, a number. (Processes with smaller -nice values get scheduled more favorably.) - -@item thcount -The number of threads in the process. - -@item start -The time when the process was started, in the same -@w{@code{(@var{high} @var{low} @var{microsec})}} format used by -@code{current-time} and @code{file-attributes}. - -@item etime -The time elapsed since the process started, in the @w{@code{(@var{high} -@var{low} @var{microsec})}} format. - -@item vsize -The virtual memory size of the process, measured in kilobytes. - -@item rss -The size of the process's @dfn{resident set}, the number of kilobytes -occupied by the process in the machine's physical memory. - -@item pcpu -The percentage of the CPU time used by the process since it started. -The corresponding @var{value} is a floating-point number between 0 and -100. - -@item pmem -The percentage of the total physical memory installed on the machine -used by the process's resident set. The value is a floating-point -number between 0 and 100. - -@item args -The command-line with which the process was invoked. This is a string -in which individual command-line arguments are separated by blanks; -whitespace characters that are embedded in the arguments are quoted as -appropriate for the system's shell: escaped by backslash characters on -GNU and Unix, and enclosed in double quote characters on Windows. -Thus, this command-line string can be directly used in primitives such -as @code{shell-command}. -@end table - -@end defun - - -@node Transaction Queues -@section Transaction Queues -@cindex transaction queue - -@c That's not very informative. What is a transaction, and when might -@c I want to use one? -You can use a @dfn{transaction queue} to communicate with a subprocess -using transactions. First use @code{tq-create} to create a transaction -queue communicating with a specified process. Then you can call -@code{tq-enqueue} to send a transaction. - -@defun tq-create process -This function creates and returns a transaction queue communicating with -@var{process}. The argument @var{process} should be a subprocess -capable of sending and receiving streams of bytes. It may be a child -process, or it may be a TCP connection to a server, possibly on another -machine. -@end defun - -@defun tq-enqueue queue question regexp closure fn &optional delay-question -This function sends a transaction to queue @var{queue}. Specifying the -queue has the effect of specifying the subprocess to talk to. - -The argument @var{question} is the outgoing message that starts the -transaction. The argument @var{fn} is the function to call when the -corresponding answer comes back; it is called with two arguments: -@var{closure}, and the answer received. - -The argument @var{regexp} is a regular expression that should match -text at the end of the entire answer, but nothing before; that's how -@code{tq-enqueue} determines where the answer ends. - -If the argument @var{delay-question} is non-@code{nil}, delay sending -this question until the process has finished replying to any previous -questions. This produces more reliable results with some processes. -@ignore - -@c Let's not mention it then. -The return value of @code{tq-enqueue} itself is not meaningful. -@end ignore -@end defun - -@defun tq-close queue -Shut down transaction queue @var{queue}, waiting for all pending transactions -to complete, and then terminate the connection or child process. -@end defun - -Transaction queues are implemented by means of a filter function. -@xref{Filter Functions}. - -@node Network -@section Network Connections -@cindex network connection -@cindex TCP -@cindex UDP - - Emacs Lisp programs can open stream (TCP) and datagram (UDP) network -connections (@pxref{Datagrams}) to other processes on the same machine -or other machines. -A network connection is handled by Lisp much like a subprocess, and is -represented by a process object. However, the process you are -communicating with is not a child of the Emacs process, has no -process @acronym{ID}, and you can't kill it or send it signals. All you -can do is send and receive data. @code{delete-process} closes the -connection, but does not kill the program at the other end; that -program must decide what to do about closure of the connection. - - Lisp programs can listen for connections by creating network -servers. A network server is also represented by a kind of process -object, but unlike a network connection, the network server never -transfers data itself. When it receives a connection request, it -creates a new network connection to represent the connection just -made. (The network connection inherits certain information, including -the process plist, from the server.) The network server then goes -back to listening for more connection requests. - - Network connections and servers are created by calling -@code{make-network-process} with an argument list consisting of -keyword/argument pairs, for example @code{:server t} to create a -server process, or @code{:type 'datagram} to create a datagram -connection. @xref{Low-Level Network}, for details. You can also use -the @code{open-network-stream} function described below. - - To distinguish the different types of processes, the -@code{process-type} function returns the symbol @code{network} for a -network connection or server, @code{serial} for a serial port -connection, or @code{real} for a real subprocess. - - The @code{process-status} function returns @code{open}, -@code{closed}, @code{connect}, or @code{failed} for network -connections. For a network server, the status is always -@code{listen}. None of those values is possible for a real -subprocess. @xref{Process Information}. - - You can stop and resume operation of a network process by calling -@code{stop-process} and @code{continue-process}. For a server -process, being stopped means not accepting new connections. (Up to 5 -connection requests will be queued for when you resume the server; you -can increase this limit, unless it is imposed by the operating -system---see the @code{:server} keyword of @code{make-network-process}, -@ref{Network Processes}.) For a network stream connection, being -stopped means not processing input (any arriving input waits until you -resume the connection). For a datagram connection, some number of -packets may be queued but input may be lost. You can use the function -@code{process-command} to determine whether a network connection or -server is stopped; a non-@code{nil} value means yes. - -@cindex network connection, encrypted -@cindex encrypted network connections -@cindex @acronym{TLS} network connections -@cindex @acronym{STARTTLS} network connections -Emacs can create encrypted network connections, using either built-in -or external support. The built-in support uses the GnuTLS -(``Transport Layer Security'') library; see -@uref{http://www.gnu.org/software/gnutls/, the GnuTLS project page}. -If your Emacs was compiled with GnuTLS support, the function -@code{gnutls-available-p} is defined and returns non-@code{nil}. For -more details, @pxref{Top,, Overview, emacs-gnutls, The Emacs-GnuTLS manual}. -The external support uses the @file{starttls.el} library, which -requires a helper utility such as @command{gnutls-cli} to be installed -on the system. The @code{open-network-stream} function can -transparently handle the details of creating encrypted connections for -you, using whatever support is available. - -@defun open-network-stream name buffer host service &rest parameters -This function opens a TCP connection, with optional encryption, and -returns a process object that represents the connection. - -The @var{name} argument specifies the name for the process object. It -is modified as necessary to make it unique. - -The @var{buffer} argument is the buffer to associate with the -connection. Output from the connection is inserted in the buffer, -unless you specify a filter function to handle the output. If -@var{buffer} is @code{nil}, it means that the connection is not -associated with any buffer. - -The arguments @var{host} and @var{service} specify where to connect to; -@var{host} is the host name (a string), and @var{service} is the name of -a defined network service (a string) or a port number (an integer). - -The remaining arguments @var{parameters} are keyword/argument pairs -that are mainly relevant to encrypted connections: - -@table @code - -@item :nowait @var{boolean} -If non-@code{nil}, try to make an asynchronous connection. - -@item :type @var{type} -The type of connection. Options are: - -@table @code -@item plain -An ordinary, unencrypted connection. -@item tls -@itemx ssl -A @acronym{TLS} (``Transport Layer Security'') connection. -@item nil -@itemx network -Start with a plain connection, and if parameters @samp{:success} -and @samp{:capability-command} are supplied, try to upgrade to an encrypted -connection via @acronym{STARTTLS}. If that fails, retain the -unencrypted connection. -@item starttls -As for @code{nil}, but if @acronym{STARTTLS} fails drop the connection. -@item shell -A shell connection. -@end table - -@item :always-query-capabilities @var{boolean} -If non-@code{nil}, always ask for the server's capabilities, even when -doing a @samp{plain} connection. - -@item :capability-command @var{capability-command} -Command string to query the host capabilities. - -@item :end-of-command @var{regexp} -@itemx :end-of-capability @var{regexp} -Regular expression matching the end of a command, or the end of the -command @var{capability-command}. The latter defaults to the former. - -@item :starttls-function @var{function} -Function of one argument (the response to @var{capability-command}), -which returns either @code{nil}, or the command to activate @acronym{STARTTLS} -if supported. - -@item :success @var{regexp} -Regular expression matching a successful @acronym{STARTTLS} negotiation. - -@item :use-starttls-if-possible @var{boolean} -If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs -doesn't have built-in @acronym{TLS} support. - -@item :client-certificate @var{list-or-t} -Either a list of the form @code{(@var{key-file} @var{cert-file})}, -naming the certificate key file and certificate file itself, or -@code{t}, meaning to query @code{auth-source} for this information -(@pxref{Top,,Overview, auth, The Auth-Source Manual}). -Only used for @acronym{TLS} or @acronym{STARTTLS}. - -@item :return-list @var{cons-or-nil} -The return value of this function. If omitted or @code{nil}, return a -process object. Otherwise, a cons of the form @code{(@var{process-object} -. @var{plist})}, where @var{plist} has keywords: - -@table @code -@item :greeting @var{string-or-nil} -If non-@code{nil}, the greeting string returned by the host. -@item :capabilities @var{string-or-nil} -If non-@code{nil}, the host's capability string. -@item :type @var{symbol} -The connection type: @samp{plain} or @samp{tls}. -@end table - -@end table - -@end defun - -@node Network Servers -@section Network Servers -@cindex network servers - - You create a server by calling @code{make-network-process} -(@pxref{Network Processes}) with @code{:server t}. The server will -listen for connection requests from clients. When it accepts a client -connection request, that creates a new network connection, itself a -process object, with the following parameters: - -@itemize @bullet -@item -The connection's process name is constructed by concatenating the -server process's @var{name} with a client identification string. The -@c FIXME? What about IPv6? Say briefly what the difference is? -client identification string for an IPv4 connection looks like -@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}, which represents an -address and port number. Otherwise, it is a -unique number in brackets, as in @samp{<@var{nnn}>}. The number -is unique for each connection in the Emacs session. - -@item -If the server's filter is non-@code{nil}, the connection process does -not get a separate process buffer; otherwise, Emacs creates a new -buffer for the purpose. The buffer name is the server's buffer name -or process name, concatenated with the client identification string. - -The server's process buffer value is never used directly, but the log -function can retrieve it and use it to log connections by inserting -text there. - -@item -The communication type and the process filter and sentinel are -inherited from those of the server. The server never directly -uses its filter and sentinel; their sole purpose is to initialize -connections made to the server. - -@item -The connection's process contact information is set according to the client's -addressing information (typically an IP address and a port number). -This information is associated with the @code{process-contact} -keywords @code{:host}, @code{:service}, @code{:remote}. - -@item -The connection's local address is set up according to the port -number used for the connection. - -@item -The client process's plist is initialized from the server's plist. -@end itemize - -@node Datagrams -@section Datagrams -@cindex datagrams - - A @dfn{datagram} connection communicates with individual packets rather -than streams of data. Each call to @code{process-send} sends one -datagram packet (@pxref{Input to Processes}), and each datagram -received results in one call to the filter function. - - The datagram connection doesn't have to talk with the same remote -peer all the time. It has a @dfn{remote peer address} which specifies -where to send datagrams to. Each time an incoming datagram is passed -to the filter function, the peer address is set to the address that -datagram came from; that way, if the filter function sends a datagram, -it will go back to that place. You can specify the remote peer -address when you create the datagram connection using the -@code{:remote} keyword. You can change it later on by calling -@code{set-process-datagram-address}. - -@defun process-datagram-address process -If @var{process} is a datagram connection or server, this function -returns its remote peer address. -@end defun - -@defun set-process-datagram-address process address -If @var{process} is a datagram connection or server, this function -sets its remote peer address to @var{address}. -@end defun - -@node Low-Level Network -@section Low-Level Network Access - - You can also create network connections by operating at a lower -level than that of @code{open-network-stream}, using -@code{make-network-process}. - -@menu -* Proc: Network Processes. Using @code{make-network-process}. -* Options: Network Options. Further control over network connections. -* Features: Network Feature Testing. - Determining which network features work on - the machine you are using. -@end menu - -@node Network Processes -@subsection @code{make-network-process} - - The basic function for creating network connections and network -servers is @code{make-network-process}. It can do either of those -jobs, depending on the arguments you give it. - -@defun make-network-process &rest args -This function creates a network connection or server and returns the -process object that represents it. The arguments @var{args} are a -list of keyword/argument pairs. Omitting a keyword is always -equivalent to specifying it with value @code{nil}, except for -@code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here -are the meaningful keywords (those corresponding to network options -are listed in the following section): - -@table @asis -@item :name @var{name} -Use the string @var{name} as the process name. It is modified if -necessary to make it unique. - -@item :type @var{type} -Specify the communication type. A value of @code{nil} specifies a -stream connection (the default); @code{datagram} specifies a datagram -connection; @code{seqpacket} specifies a ``sequenced packet stream'' -connection. Both connections and servers can be of these types. - -@item :server @var{server-flag} -If @var{server-flag} is non-@code{nil}, create a server. Otherwise, -create a connection. For a stream type server, @var{server-flag} may -be an integer, which then specifies the length of the queue of pending -connections to the server. The default queue length is 5. - -@item :host @var{host} -Specify the host to connect to. @var{host} should be a host name or -Internet address, as a string, or the symbol @code{local} to specify -the local host. If you specify @var{host} for a server, it must -specify a valid address for the local host, and only clients -connecting to that address will be accepted. - -@item :service @var{service} -@var{service} specifies a port number to connect to; or, for a server, -the port number to listen on. It should be a service name that -translates to a port number, or an integer specifying the port number -directly. For a server, it can also be @code{t}, which means to let -the system select an unused port number. - -@item :family @var{family} -@var{family} specifies the address (and protocol) family for -communication. @code{nil} means determine the proper address family -automatically for the given @var{host} and @var{service}. -@code{local} specifies a Unix socket, in which case @var{host} is -ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6, -respectively. - -@item :local @var{local-address} -For a server process, @var{local-address} is the address to listen on. -It overrides @var{family}, @var{host} and @var{service}, so you -might as well not specify them. - -@item :remote @var{remote-address} -For a connection, @var{remote-address} is the address to connect to. -It overrides @var{family}, @var{host} and @var{service}, so you -might as well not specify them. - -For a datagram server, @var{remote-address} specifies the initial -setting of the remote datagram address. - -The format of @var{local-address} or @var{remote-address} depends on -the address family: - -@itemize - -@item -An IPv4 address is represented as a five-element vector of four 8-bit -integers and one 16-bit integer -@code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to -numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number -@var{p}. - -@item -An IPv6 address is represented as a nine-element vector of 16-bit -integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f} -@var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address -@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and -port number @var{p}. - -@item -A local address is represented as a string, which specifies the address -in the local address space. - -@item -An ``unsupported family'' address is represented by a cons -@code{(@var{f} . @var{av})}, where @var{f} is the family number and -@var{av} is a vector specifying the socket address using one element -per address data byte. Do not rely on this format in portable code, -as it may depend on implementation defined constants, data sizes, and -data structure alignment. -@end itemize - -@item :nowait @var{bool} -If @var{bool} is non-@code{nil} for a stream connection, return -without waiting for the connection to complete. When the connection -succeeds or fails, Emacs will call the sentinel function, with a -second argument matching @code{"open"} (if successful) or -@code{"failed"}. The default is to block, so that -@code{make-network-process} does not return until the connection -has succeeded or failed. - -@item :stop @var{stopped} -If @var{stopped} is non-@code{nil}, start the network connection or -server in the ``stopped'' state. - -@item :buffer @var{buffer} -Use @var{buffer} as the process buffer. - -@item :coding @var{coding} -Use @var{coding} as the coding system for this process. To specify -different coding systems for decoding data from the connection and for -encoding data sent to it, specify @code{(@var{decoding} . -@var{encoding})} for @var{coding}. - -If you don't specify this keyword at all, the default -is to determine the coding systems from the data. - -@item :noquery @var{query-flag} -Initialize the process query flag to @var{query-flag}. -@xref{Query Before Exit}. - -@item :filter @var{filter} -Initialize the process filter to @var{filter}. - -@item :filter-multibyte @var{multibyte} -If @var{multibyte} is non-@code{nil}, strings given to the process -filter are multibyte, otherwise they are unibyte. The default is the -default value of @code{enable-multibyte-characters}. - -@item :sentinel @var{sentinel} -Initialize the process sentinel to @var{sentinel}. - -@item :log @var{log} -Initialize the log function of a server process to @var{log}. The log -function is called each time the server accepts a network connection -from a client. The arguments passed to the log function are -@var{server}, @var{connection}, and @var{message}; where @var{server} -is the server process, @var{connection} is the new process for the -connection, and @var{message} is a string describing what has -happened. - -@item :plist @var{plist} -Initialize the process plist to @var{plist}. -@end table - -The original argument list, modified with the actual connection -information, is available via the @code{process-contact} function. -@end defun - -@node Network Options -@subsection Network Options - - The following network options can be specified when you create a -network process. Except for @code{:reuseaddr}, you can also set or -modify these options later, using @code{set-network-process-option}. - - For a server process, the options specified with -@code{make-network-process} are not inherited by the client -connections, so you will need to set the necessary options for each -child connection as it is created. - -@table @asis -@item :bindtodevice @var{device-name} -If @var{device-name} is a non-empty string identifying a network -interface name (see @code{network-interface-list}), only handle -packets received on that interface. If @var{device-name} is @code{nil} -(the default), handle packets received on any interface. - -Using this option may require special privileges on some systems. - -@item :broadcast @var{broadcast-flag} -If @var{broadcast-flag} is non-@code{nil} for a datagram process, the -process will receive datagram packet sent to a broadcast address, and -be able to send packets to a broadcast address. This is ignored for a stream -connection. - -@item :dontroute @var{dontroute-flag} -If @var{dontroute-flag} is non-@code{nil}, the process can only send -to hosts on the same network as the local host. - -@item :keepalive @var{keepalive-flag} -If @var{keepalive-flag} is non-@code{nil} for a stream connection, -enable exchange of low-level keep-alive messages. - -@item :linger @var{linger-arg} -If @var{linger-arg} is non-@code{nil}, wait for successful -transmission of all queued packets on the connection before it is -deleted (see @code{delete-process}). If @var{linger-arg} is an -integer, it specifies the maximum time in seconds to wait for queued -packets to be sent before closing the connection. The default is -@code{nil}, which means to discard unsent queued packets when the -process is deleted. - -@c FIXME Where out-of-band data is ...? -@item :oobinline @var{oobinline-flag} -If @var{oobinline-flag} is non-@code{nil} for a stream connection, -receive out-of-band data in the normal data stream. Otherwise, ignore -out-of-band data. - -@item :priority @var{priority} -Set the priority for packets sent on this connection to the integer -@var{priority}. The interpretation of this number is protocol -specific; such as setting the TOS (type of service) field on IP -packets sent on this connection. It may also have system dependent -effects, such as selecting a specific output queue on the network -interface. - -@item :reuseaddr @var{reuseaddr-flag} -If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream -server process, allow this server to reuse a specific port number (see -@code{:service}), unless another process on this host is already -listening on that port. If @var{reuseaddr-flag} is @code{nil}, there -may be a period of time after the last use of that port (by any -process on the host) where it is not possible to make a new server on -that port. -@end table - -@defun set-network-process-option process option value &optional no-error -This function sets or modifies a network option for network process -@var{process}. The accepted options and values are as for -@code{make-network-process}. If @var{no-error} is non-@code{nil}, -this function returns @code{nil} instead of signaling an error if -@var{option} is not a supported option. If the function successfully -completes, it returns @code{t}. - -The current setting of an option is available via the -@code{process-contact} function. -@end defun - -@node Network Feature Testing -@subsection Testing Availability of Network Features - - To test for the availability of a given network feature, use -@code{featurep} like this: - -@example -(featurep 'make-network-process '(@var{keyword} @var{value})) -@end example - -@noindent -The result of this form is @code{t} if it works to specify -@var{keyword} with value @var{value} in @code{make-network-process}. -Here are some of the @var{keyword}---@var{value} pairs you can test in -this way. - -@table @code -@item (:nowait t) -Non-@code{nil} if non-blocking connect is supported. -@item (:type datagram) -Non-@code{nil} if datagrams are supported. -@item (:family local) -Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported. -@item (:family ipv6) -Non-@code{nil} if IPv6 is supported. -@item (:service t) -Non-@code{nil} if the system can select the port for a server. -@end table - - To test for the availability of a given network option, use -@code{featurep} like this: - -@example -(featurep 'make-network-process '@var{keyword}) -@end example - -@noindent -The accepted @var{keyword} values are @code{:bindtodevice}, etc. -For the complete list, @pxref{Network Options}. This form returns -non-@code{nil} if that particular network option is supported by -@code{make-network-process} (or @code{set-network-process-option}). - -@node Misc Network -@section Misc Network Facilities - - These additional functions are useful for creating and operating -on network connections. Note that they are supported only on some -systems. - -@defun network-interface-list -This function returns a list describing the network interfaces -of the machine you are using. The value is an alist whose -elements have the form @code{(@var{name} . @var{address})}. -@var{address} has the same form as the @var{local-address} -and @var{remote-address} arguments to @code{make-network-process}. -@end defun - -@defun network-interface-info ifname -This function returns information about the network interface named -@var{ifname}. The value is a list of the form -@code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}. - -@table @var -@item addr -The Internet protocol address. -@item bcast -The broadcast address. -@item netmask -The network mask. -@item hwaddr -The layer 2 address (Ethernet MAC address, for instance). -@item flags -The current flags of the interface. -@end table -@end defun - -@defun format-network-address address &optional omit-port -This function converts the Lisp representation of a network address to -a string. - -A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} -represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port -number @var{p}. @code{format-network-address} converts that to the -string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}. - -A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e} -@var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address along -with a port number. @code{format-network-address} converts that to -the string -@code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}. - -If the vector does not include the port number, @var{p}, or if -@var{omit-port} is non-@code{nil}, the result does not include the -@code{:@var{p}} suffix. -@end defun - -@node Serial Ports -@section Communicating with Serial Ports -@cindex @file{/dev/tty} -@cindex @file{COM1} -@cindex serial connections - - Emacs can communicate with serial ports. For interactive use, -@kbd{M-x serial-term} opens a terminal window. In a Lisp program, -@code{make-serial-process} creates a process object. - - The serial port can be configured at run-time, without having to -close and re-open it. The function @code{serial-process-configure} -lets you change the speed, bytesize, and other parameters. In a -terminal window created by @code{serial-term}, you can click on the -mode line for configuration. - - A serial connection is represented by a process object, which can be -used in a similar way to a subprocess or network process. You can send and -receive data, and configure the serial port. A serial process object -has no process ID, however, and you can't send signals to it, and the -status codes are different from other types of processes. -@code{delete-process} on the process object or @code{kill-buffer} on -the process buffer close the connection, but this does not affect the -device connected to the serial port. - - The function @code{process-type} returns the symbol @code{serial} -for a process object representing a serial port connection. - - Serial ports are available on GNU/Linux, Unix, and MS Windows systems. - -@deffn Command serial-term port speed -Start a terminal-emulator for a serial port in a new buffer. -@var{port} is the name of the serial port to connect to. For -example, this could be @file{/dev/ttyS0} on Unix. On MS Windows, this -could be @file{COM1}, or @file{\\.\COM10} (double the backslashes in -Lisp strings). - -@c FIXME is 9600 still the most common value, or is it 115200 now? -@c (Same value, 9600, appears below as well.) -@var{speed} is the speed of the serial port in bits per second. 9600 -is a common value. The buffer is in Term mode; see @ref{Term Mode,,, -emacs, The GNU Emacs Manual}, for the commands to use in that buffer. -You can change the speed and the configuration in the mode line menu. -@end deffn - -@defun make-serial-process &rest args -This function creates a process and a buffer. Arguments are specified -as keyword/argument pairs. Here's the list of the meaningful -keywords, with the first two (@var{port} and @var{speed}) being mandatory: - -@table @code -@item :port @var{port} -This is the name of the serial port. On Unix and GNU systems, this is -a file name such as @file{/dev/ttyS0}. On Windows, this could be -@file{COM1}, or @file{\\.\COM10} for ports higher than @file{COM9} -(double the backslashes in Lisp strings). - -@item :speed @var{speed} -The speed of the serial port in bits per second. This function calls -@code{serial-process-configure} to handle the speed; see the -following documentation of that function for more details. - -@item :name @var{name} -The name of the process. If @var{name} is not given, @var{port} will -serve as the process name as well. - -@item :buffer @var{buffer} -The buffer to associate with the process. The value can be either a -buffer or a string that names a buffer. Process output goes at the -end of that buffer, unless you specify an output stream or filter -function to handle the output. If @var{buffer} is not given, the -process buffer's name is taken from the value of the @code{:name} -keyword. - -@item :coding @var{coding} -If @var{coding} is a symbol, it specifies the coding system used for -both reading and writing for this process. If @var{coding} is a cons -@code{(@var{decoding} . @var{encoding})}, @var{decoding} is used for -reading, and @var{encoding} is used for writing. If not specified, -the default is to determine the coding systems from the data itself. - -@item :noquery @var{query-flag} -Initialize the process query flag to @var{query-flag}. @xref{Query -Before Exit}. The flags defaults to @code{nil} if unspecified. - -@item :stop @var{bool} -Start process in the ``stopped'' state if @var{bool} is -non-@code{nil}. In the stopped state, a serial process does not -accept incoming data, but you can send outgoing data. The stopped -state is cleared by @code{continue-process} and set by -@code{stop-process}. - -@item :filter @var{filter} -Install @var{filter} as the process filter. - -@item :sentinel @var{sentinel} -Install @var{sentinel} as the process sentinel. - -@item :plist @var{plist} -Install @var{plist} as the initial plist of the process. - -@item :bytesize -@itemx :parity -@itemx :stopbits -@itemx :flowcontrol -These are handled by @code{serial-process-configure}, which is called -by @code{make-serial-process}. -@end table - -The original argument list, possibly modified by later configuration, -is available via the function @code{process-contact}. - -Here is an example: - -@example -(make-serial-process :port "/dev/ttyS0" :speed 9600) -@end example -@end defun - -@defun serial-process-configure &rest args -@cindex baud, in serial connections -@cindex bytesize, in serial connections -@cindex parity, in serial connections -@cindex stopbits, in serial connections -@cindex flowcontrol, in serial connections - -This functions configures a serial port connection. Arguments are -specified as keyword/argument pairs. Attributes that are not given -are re-initialized from the process's current configuration (available -via the function @code{process-contact}), or set to reasonable default -values. The following arguments are defined: - -@table @code -@item :process @var{process} -@itemx :name @var{name} -@itemx :buffer @var{buffer} -@itemx :port @var{port} -Any of these arguments can be given to identify the process that is to -be configured. If none of these arguments is given, the current -buffer's process is used. - -@item :speed @var{speed} -The speed of the serial port in bits per second, a.k.a.@: @dfn{baud -rate}. The value can be any number, but most serial ports work only -at a few defined values between 1200 and 115200, with 9600 being the -most common value. If @var{speed} is @code{nil}, the function ignores -all other arguments and does not configure the port. This may be -useful for special serial ports such as Bluetooth-to-serial converters, -which can only be configured through @samp{AT} commands sent through the -connection. The value of @code{nil} for @var{speed} is valid only for -connections that were already opened by a previous call to -@code{make-serial-process} or @code{serial-term}. - -@item :bytesize @var{bytesize} -The number of bits per byte, which can be 7 or 8. If @var{bytesize} -is not given or @code{nil}, it defaults to 8. - -@item :parity @var{parity} -The value can be @code{nil} (don't use parity), the symbol -@code{odd} (use odd parity), or the symbol @code{even} (use even -parity). If @var{parity} is not given, it defaults to no parity. - -@item :stopbits @var{stopbits} -The number of stopbits used to terminate a transmission -of each byte. @var{stopbits} can be 1 or 2. If @var{stopbits} is not -given or @code{nil}, it defaults to 1. - -@item :flowcontrol @var{flowcontrol} -The type of flow control to use for this connection, which is either -@code{nil} (don't use flow control), the symbol @code{hw} (use RTS/CTS -hardware flow control), or the symbol @code{sw} (use XON/XOFF software -flow control). If @var{flowcontrol} is not given, it defaults to no -flow control. -@end table - -Internally, @code{make-serial-process} calls -@code{serial-process-configure} for the initial configuration of the -serial port. -@end defun - -@node Byte Packing -@section Packing and Unpacking Byte Arrays -@cindex byte packing and unpacking - - This section describes how to pack and unpack arrays of bytes, -usually for binary network protocols. These functions convert byte arrays -to alists, and vice versa. The byte array can be represented as a -@c FIXME? No multibyte? -unibyte string or as a vector of integers, while the alist associates -symbols either with fixed-size objects or with recursive sub-alists. -To use the functions referred to in this section, load the -@code{bindat} library. -@c It doesn't have any autoloads. - -@cindex serializing -@cindex deserializing -@cindex packing -@cindex unpacking - Conversion from byte arrays to nested alists is also known as -@dfn{deserializing} or @dfn{unpacking}, while going in the opposite -direction is also known as @dfn{serializing} or @dfn{packing}. - -@menu -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! -@end menu - -@node Bindat Spec -@subsection Describing Data Layout - - To control unpacking and packing, you write a @dfn{data layout -specification}, a special nested list describing named and typed -@dfn{fields}. This specification controls the length of each field to be -processed, and how to pack or unpack it. We normally keep bindat specs -in variables whose names end in @samp{-bindat-spec}; that kind of name -is automatically recognized as ``risky''. - -@cindex endianness -@cindex big endian -@cindex little endian -@cindex network byte ordering - A field's @dfn{type} describes the size (in bytes) of the object -that the field represents and, in the case of multibyte fields, how -the bytes are ordered within the field. The two possible orderings -are ``big endian'' (also known as ``network byte ordering'') and -``little endian''. For instance, the number @code{#x23cd} (decimal -9165) in big endian would be the two bytes @code{#x23} @code{#xcd}; -and in little endian, @code{#xcd} @code{#x23}. Here are the possible -type values: - -@table @code -@item u8 -@itemx byte -Unsigned byte, with length 1. - -@item u16 -@itemx word -@itemx short -Unsigned integer in network byte order, with length 2. - -@item u24 -Unsigned integer in network byte order, with length 3. - -@item u32 -@itemx dword -@itemx long -Unsigned integer in network byte order, with length 4. -Note: These values may be limited by Emacs's integer implementation limits. - -@item u16r -@itemx u24r -@itemx u32r -Unsigned integer in little endian order, with length 2, 3 and 4, respectively. - -@item str @var{len} -String of length @var{len}. - -@item strz @var{len} -Zero-terminated string, in a fixed-size field with length @var{len}. - -@item vec @var{len} [@var{type}] -Vector of @var{len} elements of type @var{type}, defaulting to bytes. -The @var{type} is any of the simple types above, or another vector -specified as a list of the form @code{(vec @var{len} [@var{type}])}. - -@item ip -@c FIXME? IPv6? -Four-byte vector representing an Internet address. For example: -@code{[127 0 0 1]} for localhost. - -@item bits @var{len} -List of set bits in @var{len} bytes. The bytes are taken in big -endian order and the bits are numbered starting with @code{8 * -@var{len} @minus{} 1} and ending with zero. For example: @code{bits -2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and -@code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}. - -@item (eval @var{form}) -@var{form} is a Lisp expression evaluated at the moment the field is -unpacked or packed. The result of the evaluation should be one of the -above-listed type specifications. -@end table - -For a fixed-size field, the length @var{len} is given as an integer -specifying the number of bytes in the field. - -When the length of a field is not fixed, it typically depends on the -value of a preceding field. In this case, the length @var{len} can be -given either as a list @code{(@var{name} ...)} identifying a -@dfn{field name} in the format specified for @code{bindat-get-field} -below, or by an expression @code{(eval @var{form})} where @var{form} -should evaluate to an integer, specifying the field length. - -A field specification generally has the form @code{([@var{name}] -@var{handler})}, where @var{name} is optional. Don't use names that -are symbols meaningful as type specifications (above) or handler -specifications (below), since that would be ambiguous. @var{name} can -be a symbol or an expression @code{(eval @var{form})}, in which case -@var{form} should evaluate to a symbol. - -@var{handler} describes how to unpack or pack the field and can be one -of the following: - -@table @code -@item @var{type} -Unpack/pack this field according to the type specification @var{type}. - -@item eval @var{form} -Evaluate @var{form}, a Lisp expression, for side-effect only. If the -field name is specified, the value is bound to that field name. - -@item fill @var{len} -Skip @var{len} bytes. In packing, this leaves them unchanged, -which normally means they remain zero. In unpacking, this means -they are ignored. - -@item align @var{len} -Skip to the next multiple of @var{len} bytes. - -@item struct @var{spec-name} -Process @var{spec-name} as a sub-specification. This describes a -structure nested within another structure. - -@item union @var{form} (@var{tag} @var{spec})@dots{} -@c ??? I don't see how one would actually use this. -@c ??? what kind of expression would be useful for @var{form}? -Evaluate @var{form}, a Lisp expression, find the first @var{tag} -that matches it, and process its associated data layout specification -@var{spec}. Matching can occur in one of three ways: - -@itemize -@item -If a @var{tag} has the form @code{(eval @var{expr})}, evaluate -@var{expr} with the variable @code{tag} dynamically bound to the value -of @var{form}. A non-@code{nil} result indicates a match. - -@item -@var{tag} matches if it is @code{equal} to the value of @var{form}. - -@item -@var{tag} matches unconditionally if it is @code{t}. -@end itemize - -@item repeat @var{count} @var{field-specs}@dots{} -Process the @var{field-specs} recursively, in order, then repeat -starting from the first one, processing all the specifications @var{count} -times overall. The @var{count} is given using the same formats as a -field length---if an @code{eval} form is used, it is evaluated just once. -For correct operation, each specification in @var{field-specs} must -include a name. -@end table - -For the @code{(eval @var{form})} forms used in a bindat specification, -the @var{form} can access and update these dynamically bound variables -during evaluation: - -@table @code -@item last -Value of the last field processed. - -@item bindat-raw -The data as a byte array. - -@item bindat-idx -Current index (within @code{bindat-raw}) for unpacking or packing. - -@item struct -The alist containing the structured data that have been unpacked so -far, or the entire structure being packed. You can use -@code{bindat-get-field} to access specific fields of this structure. - -@item count -@itemx index -Inside a @code{repeat} block, these contain the maximum number of -repetitions (as specified by the @var{count} parameter), and the -current repetition number (counting from 0). Setting @code{count} to -zero will terminate the inner-most repeat block after the current -repetition has completed. -@end table - -@node Bindat Functions -@subsection Functions to Unpack and Pack Bytes - - In the following documentation, @var{spec} refers to a data layout -specification, @code{bindat-raw} to a byte array, and @var{struct} to an -alist representing unpacked field data. - -@defun bindat-unpack spec bindat-raw &optional bindat-idx -@c FIXME? Again, no multibyte? -This function unpacks data from the unibyte string or byte -array @code{bindat-raw} -according to @var{spec}. Normally, this starts unpacking at the -beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it -specifies a zero-based starting position to use instead. - -The value is an alist or nested alist in which each element describes -one unpacked field. -@end defun - -@defun bindat-get-field struct &rest name -This function selects a field's data from the nested alist -@var{struct}. Usually @var{struct} was returned by -@code{bindat-unpack}. If @var{name} corresponds to just one argument, -that means to extract a top-level field value. Multiple @var{name} -arguments specify repeated lookup of sub-structures. An integer name -acts as an array index. - -For example, if @var{name} is @code{(a b 2 c)}, that means to find -field @code{c} in the third element of subfield @code{b} of field -@code{a}. (This corresponds to @code{struct.a.b[2].c} in C.) -@end defun - - Although packing and unpacking operations change the organization of -data (in memory), they preserve the data's @dfn{total length}, which is -the sum of all the fields' lengths, in bytes. This value is not -generally inherent in either the specification or alist alone; instead, -both pieces of information contribute to its calculation. Likewise, the -length of a string or array being unpacked may be longer than the data's -total length as described by the specification. - -@defun bindat-length spec struct -This function returns the total length of the data in @var{struct}, -according to @var{spec}. -@end defun - -@defun bindat-pack spec struct &optional bindat-raw bindat-idx -This function returns a byte array packed according to @var{spec} from -the data in the alist @var{struct}. It normally creates and fills a -new byte array starting at the beginning. However, if @var{bindat-raw} -is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to -pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting -offset for packing into @code{bindat-raw}. - -When pre-allocating, you should make sure @code{(length @var{bindat-raw})} -meets or exceeds the total length to avoid an out-of-range error. -@end defun - -@defun bindat-ip-to-string ip -Convert the Internet address vector @var{ip} to a string in the usual -dotted notation. -@c FIXME? Does it do IPv6? - -@example -(bindat-ip-to-string [127 0 0 1]) - @result{} "127.0.0.1" -@end example -@end defun - -@node Bindat Examples -@subsection Examples of Byte Unpacking and Packing -@c FIXME? This seems a very long example for something that is not used -@c very often. As of 24.1, gdb-mi.el is the only user of bindat.el in Emacs. -@c Maybe one or both of these examples should just be moved to the -@c commentary of bindat.el. - - Here is a complete example of byte unpacking and packing: - -@lisp -(require 'bindat) - -(defvar fcookie-index-spec - '((:version u32) - (:count u32) - (:longest u32) - (:shortest u32) - (:flags u32) - (:delim u8) - (:ignored fill 3) - (:offset repeat (:count) (:foo u32))) - "Description of a fortune cookie index file's contents.") - -(defun fcookie (cookies &optional index) - "Display a random fortune cookie from file COOKIES. -Optional second arg INDEX specifies the associated index -filename, by default \"COOKIES.dat\". Display cookie text -in buffer \"*Fortune Cookie: BASENAME*\", where BASENAME -is COOKIES without the directory part." - (interactive "fCookies file: ") - (let* ((info (with-temp-buffer - (insert-file-contents-literally - (or index (concat cookies ".dat"))) - (bindat-unpack fcookie-index-spec - (buffer-string)))) - (sel (random (bindat-get-field info :count))) - (beg (cdar (bindat-get-field info :offset sel))) - (end (or (cdar (bindat-get-field info - :offset (1+ sel))) - (nth 7 (file-attributes cookies))))) - (switch-to-buffer - (get-buffer-create - (format "*Fortune Cookie: %s*" - (file-name-nondirectory cookies)))) - (erase-buffer) - (insert-file-contents-literally - cookies nil beg (- end 3)))) - -(defun fcookie-create-index (cookies &optional index delim) - "Scan file COOKIES, and write out its index file. -Optional arg INDEX specifies the index filename, which by -default is \"COOKIES.dat\". Optional arg DELIM specifies the -unibyte character that, when found on a line of its own in -COOKIES, indicates the border between entries." - (interactive "fCookies file: ") - (setq delim (or delim ?%)) - (let ((delim-line (format "\n%c\n" delim)) - (count 0) - (max 0) - min p q len offsets) - (unless (= 3 (string-bytes delim-line)) - (error "Delimiter cannot be represented in one byte")) - (with-temp-buffer - (insert-file-contents-literally cookies) - (while (and (setq p (point)) - (search-forward delim-line (point-max) t) - (setq len (- (point) 3 p))) - (setq count (1+ count) - max (max max len) - min (min (or min max) len) - offsets (cons (1- p) offsets)))) - (with-temp-buffer - (set-buffer-multibyte nil) - (insert - (bindat-pack - fcookie-index-spec - `((:version . 2) - (:count . ,count) - (:longest . ,max) - (:shortest . ,min) - (:flags . 0) - (:delim . ,delim) - (:offset . ,(mapcar (lambda (o) - (list (cons :foo o))) - (nreverse offsets)))))) - (let ((coding-system-for-write 'raw-text-unix)) - (write-file (or index (concat cookies ".dat"))))))) -@end lisp - -The following is an example of defining and unpacking a complex -structure. Consider the following C structures: - -@example -struct header @{ - unsigned long dest_ip; - unsigned long src_ip; - unsigned short dest_port; - unsigned short src_port; -@}; - -struct data @{ - unsigned char type; - unsigned char opcode; - unsigned short length; /* in network byte order */ - unsigned char id[8]; /* null-terminated string */ - unsigned char data[/* (length + 3) & ~3 */]; -@}; - -struct packet @{ - struct header header; - unsigned long counters[2]; /* in little endian order */ - unsigned char items; - unsigned char filler[3]; - struct data item[/* items */]; - -@}; -@end example - -The corresponding data layout specification is: - -@lisp -(setq header-spec - '((dest-ip ip) - (src-ip ip) - (dest-port u16) - (src-port u16))) - -(setq data-spec - '((type u8) - (opcode u8) - (length u16) ; network byte order - (id strz 8) - (data vec (length)) - (align 4))) - -(setq packet-spec - '((header struct header-spec) - (counters vec 2 u32r) ; little endian order - (items u8) - (fill 3) - (item repeat (items) - (struct data-spec)))) -@end lisp - -A binary data representation is: - -@lisp -(setq binary-data - [ 192 168 1 100 192 168 1 101 01 28 21 32 - 160 134 1 0 5 1 0 0 2 0 0 0 - 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0 - 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ]) -@end lisp - -The corresponding decoded structure is: - -@lisp -(setq decoded (bindat-unpack packet-spec binary-data)) - @result{} -((header - (dest-ip . [192 168 1 100]) - (src-ip . [192 168 1 101]) - (dest-port . 284) - (src-port . 5408)) - (counters . [100000 261]) - (items . 2) - (item ((data . [1 2 3 4 5]) - (id . "ABCDEF") - (length . 5) - (opcode . 3) - (type . 2)) - ((data . [6 7 8 9 10 11 12]) - (id . "BCDEFG") - (length . 7) - (opcode . 4) - (type . 1)))) -@end lisp - -An example of fetching data from this structure: - -@lisp -(bindat-get-field decoded 'item 1 'id) - @result{} "BCDEFG" -@end lisp diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi deleted file mode 100644 index e79d361bfeb..00000000000 --- a/doc/lispref/searching.texi +++ /dev/null @@ -1,1901 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/searching -@node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top -@chapter Searching and Matching -@cindex searching - - GNU Emacs provides two ways to search through a buffer for specified -text: exact string searches and regular expression searches. After a -regular expression search, you can examine the @dfn{match data} to -determine which text matched the whole regular expression or various -portions of it. - -@menu -* String Search:: Search for an exact match. -* Searching and Case:: Case-independent or case-significant searching. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Match Data:: Finding out which part of the text matched, - after a string or regexp search. -* Search and Replace:: Commands that loop, searching and replacing. -* Standard Regexps:: Useful regexps for finding sentences, pages,... -@end menu - - The @samp{skip-chars@dots{}} functions also perform a kind of searching. -@xref{Skipping Characters}. To search for changes in character -properties, see @ref{Property Search}. - -@node String Search -@section Searching for Strings -@cindex string search - - These are the primitive functions for searching through the text in a -buffer. They are meant for use in programs, but you may call them -interactively. If you do so, they prompt for the search string; the -arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat} -is 1. For more details on interactive searching, @pxref{Search,, -Searching and Replacement, emacs, The GNU Emacs Manual}. - - These search functions convert the search string to multibyte if the -buffer is multibyte; they convert the search string to unibyte if the -buffer is unibyte. @xref{Text Representations}. - -@deffn Command search-forward string &optional limit noerror repeat -This function searches forward from point for an exact match for -@var{string}. If successful, it sets point to the end of the occurrence -found, and returns the new value of point. If no match is found, the -value and side effects depend on @var{noerror} (see below). - -In the following example, point is initially at the beginning of the -line. Then @code{(search-forward "fox")} moves point after the last -letter of @samp{fox}: - -@example -@group ----------- Buffer: foo ---------- -@point{}The quick brown fox jumped over the lazy dog. ----------- Buffer: foo ---------- -@end group - -@group -(search-forward "fox") - @result{} 20 - ----------- Buffer: foo ---------- -The quick brown fox@point{} jumped over the lazy dog. ----------- Buffer: foo ---------- -@end group -@end example - -The argument @var{limit} specifies the bound to the search, and should -be a position in the current buffer. No match extending after -that position is accepted. If @var{limit} is omitted or @code{nil}, it -defaults to the end of the accessible portion of the buffer. - -@kindex search-failed -What happens when the search fails depends on the value of -@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed} -error is signaled. If @var{noerror} is @code{t}, @code{search-forward} -returns @code{nil} and does nothing. If @var{noerror} is neither -@code{nil} nor @code{t}, then @code{search-forward} moves point to the -upper bound and returns @code{nil}. -@c I see no prospect of this ever changing, and frankly the current -@c behavior seems better, so there seems no need to mention this. -@ignore -(It would be more consistent now to return the new position of point -in that case, but some existing programs may depend on a value of -@code{nil}.) -@end ignore - -The argument @var{noerror} only affects valid searches which fail to -find a match. Invalid arguments cause errors regardless of -@var{noerror}. - -If @var{repeat} is a positive number @var{n}, it serves as a repeat -count: the search is repeated @var{n} times, each time starting at the -end of the previous time's match. If these successive searches -succeed, the function succeeds, moving point and returning its new -value. Otherwise the search fails, with results depending on the -value of @var{noerror}, as described above. If @var{repeat} is a -negative number -@var{n}, it serves as a repeat count of @var{n} for a -search in the opposite (backward) direction. -@end deffn - -@deffn Command search-backward string &optional limit noerror repeat -This function searches backward from point for @var{string}. It is -like @code{search-forward}, except that it searches backwards rather -than forwards. Backward searches leave point at the beginning of the -match. -@end deffn - -@deffn Command word-search-forward string &optional limit noerror repeat -This function searches forward from point for a ``word'' match for -@var{string}. If it finds a match, it sets point to the end of the -match found, and returns the new value of point. - -Word matching regards @var{string} as a sequence of words, disregarding -punctuation that separates them. It searches the buffer for the same -sequence of words. Each word must be distinct in the buffer (searching -for the word @samp{ball} does not match the word @samp{balls}), but the -details of punctuation and spacing are ignored (searching for @samp{ball -boy} does match @samp{ball. Boy!}). - -In this example, point is initially at the beginning of the buffer; the -search leaves it between the @samp{y} and the @samp{!}. - -@example -@group ----------- Buffer: foo ---------- -@point{}He said "Please! Find -the ball boy!" ----------- Buffer: foo ---------- -@end group - -@group -(word-search-forward "Please find the ball, boy.") - @result{} 36 - ----------- Buffer: foo ---------- -He said "Please! Find -the ball boy@point{}!" ----------- Buffer: foo ---------- -@end group -@end example - -If @var{limit} is non-@code{nil}, it must be a position in the current -buffer; it specifies the upper bound to the search. The match found -must not extend after that position. - -If @var{noerror} is @code{nil}, then @code{word-search-forward} signals -an error if the search fails. If @var{noerror} is @code{t}, then it -returns @code{nil} instead of signaling an error. If @var{noerror} is -neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the -end of the accessible portion of the buffer) and returns @code{nil}. - -If @var{repeat} is non-@code{nil}, then the search is repeated that many -times. Point is positioned at the end of the last match. - -@findex word-search-regexp -Internal, @code{word-search-forward} and related functions use the -function @code{word-search-regexp} to convert @var{string} to a -regular expression that ignores punctuation. -@end deffn - -@deffn Command word-search-forward-lax string &optional limit noerror repeat -This command is identical to @code{word-search-forward}, except that -the end of @var{string} need not match a word boundary, unless @var{string} ends -in whitespace. For instance, searching for @samp{ball boy} matches -@samp{ball boyee}, but does not match @samp{aball boy}. -@end deffn - -@deffn Command word-search-backward string &optional limit noerror repeat -This function searches backward from point for a word match to -@var{string}. This function is just like @code{word-search-forward} -except that it searches backward and normally leaves point at the -beginning of the match. -@end deffn - -@deffn Command word-search-backward-lax string &optional limit noerror repeat -This command is identical to @code{word-search-backward}, except that -the end of @var{string} need not match a word boundary, unless @var{string} ends -in whitespace. -@end deffn - -@node Searching and Case -@section Searching and Case -@cindex searching and case - - By default, searches in Emacs ignore the case of the text they are -searching through; if you specify searching for @samp{FOO}, then -@samp{Foo} or @samp{foo} is also considered a match. This applies to -regular expressions, too; thus, @samp{[aB]} would match @samp{a} or -@samp{A} or @samp{b} or @samp{B}. - - If you do not want this feature, set the variable -@code{case-fold-search} to @code{nil}. Then all letters must match -exactly, including case. This is a buffer-local variable; altering the -variable affects only the current buffer. (@xref{Intro to -Buffer-Local}.) Alternatively, you may change the default value. -In Lisp code, you will more typically use @code{let} to bind -@code{case-fold-search} to the desired value. - - Note that the user-level incremental search feature handles case -distinctions differently. When the search string contains only lower -case letters, the search ignores case, but when the search string -contains one or more upper case letters, the search becomes -case-sensitive. But this has nothing to do with the searching -functions used in Lisp code. @xref{Incremental Search,,, emacs, -The GNU Emacs Manual}. - -@defopt case-fold-search -This buffer-local variable determines whether searches should ignore -case. If the variable is @code{nil} they do not ignore case; otherwise -(and by default) they do ignore case. -@end defopt - -@defopt case-replace -This variable determines whether the higher-level replacement -functions should preserve case. If the variable is @code{nil}, that -means to use the replacement text verbatim. A non-@code{nil} value -means to convert the case of the replacement text according to the -text being replaced. - -This variable is used by passing it as an argument to the function -@code{replace-match}. @xref{Replacing Match}. -@end defopt - -@node Regular Expressions -@section Regular Expressions -@cindex regular expression -@cindex regexp - - A @dfn{regular expression}, or @dfn{regexp} for short, is a pattern that -denotes a (possibly infinite) set of strings. Searching for matches for -a regexp is a very powerful operation. This section explains how to write -regexps; the following section says how to search for them. - -@findex re-builder -@cindex regular expressions, developing - For interactive development of regular expressions, you -can use the @kbd{M-x re-builder} command. It provides a convenient -interface for creating regular expressions, by giving immediate visual -feedback in a separate buffer. As you edit the regexp, all its -matches in the target buffer are highlighted. Each parenthesized -sub-expression of the regexp is shown in a distinct face, which makes -it easier to verify even very complex regexps. - -@menu -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. -* Regexp Functions:: Functions for operating on regular expressions. -@end menu - -@node Syntax of Regexps -@subsection Syntax of Regular Expressions - - Regular expressions have a syntax in which a few characters are -special constructs and the rest are @dfn{ordinary}. An ordinary -character is a simple regular expression that matches that character -and nothing else. The special characters are @samp{.}, @samp{*}, -@samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new -special characters will be defined in the future. The character -@samp{]} is special if it ends a character alternative (see later). -The character @samp{-} is special inside a character alternative. A -@samp{[:} and balancing @samp{:]} enclose a character class inside a -character alternative. Any other character appearing in a regular -expression is ordinary, unless a @samp{\} precedes it. - - For example, @samp{f} is not a special character, so it is ordinary, and -therefore @samp{f} is a regular expression that matches the string -@samp{f} and no other string. (It does @emph{not} match the string -@samp{fg}, but it does match a @emph{part} of that string.) Likewise, -@samp{o} is a regular expression that matches only @samp{o}.@refill - - Any two regular expressions @var{a} and @var{b} can be concatenated. The -result is a regular expression that matches a string if @var{a} matches -some amount of the beginning of that string and @var{b} matches the rest of -the string.@refill - - As a simple example, we can concatenate the regular expressions @samp{f} -and @samp{o} to get the regular expression @samp{fo}, which matches only -the string @samp{fo}. Still trivial. To do something more powerful, you -need to use one of the special regular expression constructs. - -@menu -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. -@end menu - -@node Regexp Special -@subsubsection Special Characters in Regular Expressions - - Here is a list of the characters that are special in a regular -expression. - -@need 800 -@table @asis -@item @samp{.}@: @r{(Period)} -@cindex @samp{.} in regexp -is a special character that matches any single character except a newline. -Using concatenation, we can make regular expressions like @samp{a.b}, which -matches any three-character string that begins with @samp{a} and ends with -@samp{b}.@refill - -@item @samp{*} -@cindex @samp{*} in regexp -is not a construct by itself; it is a postfix operator that means to -match the preceding regular expression repetitively as many times as -possible. Thus, @samp{o*} matches any number of @samp{o}s (including no -@samp{o}s). - -@samp{*} always applies to the @emph{smallest} possible preceding -expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating -@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. - -@cindex backtracking and regular expressions -The matcher processes a @samp{*} construct by matching, immediately, as -many repetitions as can be found. Then it continues with the rest of -the pattern. If that fails, backtracking occurs, discarding some of the -matches of the @samp{*}-modified construct in the hope that that will -make it possible to match the rest of the pattern. For example, in -matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} -first tries to match all three @samp{a}s; but the rest of the pattern is -@samp{ar} and there is only @samp{r} left to match, so this try fails. -The next alternative is for @samp{a*} to match only two @samp{a}s. With -this choice, the rest of the regexp matches successfully. - -@strong{Warning:} Nested repetition operators can run for an -indefinitely long time, if they lead to ambiguous matching. For -example, trying to match the regular expression @samp{\(x+y*\)*a} -against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could -take hours before it ultimately fails. Emacs must try each way of -grouping the @samp{x}s before concluding that none of them can work. -Even worse, @samp{\(x*\)*} can match the null string in infinitely -many ways, so it causes an infinite loop. To avoid these problems, -check nested repetitions carefully, to make sure that they do not -cause combinatorial explosions in backtracking. - -@item @samp{+} -@cindex @samp{+} in regexp -is a postfix operator, similar to @samp{*} except that it must match -the preceding expression at least once. So, for example, @samp{ca+r} -matches the strings @samp{car} and @samp{caaaar} but not the string -@samp{cr}, whereas @samp{ca*r} matches all three strings. - -@item @samp{?} -@cindex @samp{?} in regexp -is a postfix operator, similar to @samp{*} except that it must match the -preceding expression either once or not at all. For example, -@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else. - -@item @samp{*?}, @samp{+?}, @samp{??} -@cindex non-greedy repetition characters in regexp -These are ``non-greedy'' variants of the operators @samp{*}, @samp{+} -and @samp{?}. Where those operators match the largest possible -substring (consistent with matching the entire containing expression), -the non-greedy variants match the smallest possible substring -(consistent with matching the entire containing expression). - -For example, the regular expression @samp{c[ad]*a} when applied to the -string @samp{cdaaada} matches the whole string; but the regular -expression @samp{c[ad]*?a}, applied to that same string, matches just -@samp{cda}. (The smallest possible match here for @samp{[ad]*?} that -permits the whole expression to match is @samp{d}.) - -@item @samp{[ @dots{} ]} -@cindex character alternative (in regexp) -@cindex @samp{[} in regexp -@cindex @samp{]} in regexp -is a @dfn{character alternative}, which begins with @samp{[} and is -terminated by @samp{]}. In the simplest case, the characters between -the two brackets are what this character alternative can match. - -Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and -@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s -(including the empty string). It follows that @samp{c[ad]*r} -matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc. - -You can also include character ranges in a character alternative, by -writing the starting and ending characters with a @samp{-} between them. -Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter. -Ranges may be intermixed freely with individual characters, as in -@samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter -or @samp{$}, @samp{%} or period. - -If @code{case-fold-search} is non-@code{nil}, @samp{[a-z]} also -matches upper-case letters. Note that a range like @samp{[a-z]} is -not affected by the locale's collation sequence, it always represents -a sequence in @acronym{ASCII} order. -@c This wasn't obvious to me, since eg the grep manual "Character -@c Classes and Bracket Expressions" specifically notes the opposite -@c behavior. But by experiment Emacs seems unaffected by LC_COLLATE -@c in this regard. - -Note also that the usual regexp special characters are not special inside a -character alternative. A completely different set of characters is -special inside character alternatives: @samp{]}, @samp{-} and @samp{^}. - -To include a @samp{]} in a character alternative, you must make it the -first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. -To include a @samp{-}, write @samp{-} as the first or last character of -the character alternative, or put it after a range. Thus, @samp{[]-]} -matches both @samp{]} and @samp{-}. (As explained below, you cannot -use @samp{\]} to include a @samp{]} inside a character alternative, -since @samp{\} is not special there.) - -To include @samp{^} in a character alternative, put it anywhere but at -the beginning. - -@c What if it starts with a multibyte and ends with a unibyte? -@c That doesn't seem to match anything...? -If a range starts with a unibyte character @var{c} and ends with a -multibyte character @var{c2}, the range is divided into two parts: one -spans the unibyte characters @samp{@var{c}..?\377}, the other the -multibyte characters @samp{@var{c1}..@var{c2}}, where @var{c1} is the -first character of the charset to which @var{c2} belongs. - -A character alternative can also specify named character classes -(@pxref{Char Classes}). This is a POSIX feature. For example, -@samp{[[:ascii:]]} matches any @acronym{ASCII} character. -Using a character class is equivalent to mentioning each of the -characters in that class; but the latter is not feasible in practice, -since some classes include thousands of different characters. - -@item @samp{[^ @dots{} ]} -@cindex @samp{^} in regexp -@samp{[^} begins a @dfn{complemented character alternative}. This -matches any character except the ones specified. Thus, -@samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and -digits. - -@samp{^} is not special in a character alternative unless it is the first -character. The character following the @samp{^} is treated as if it -were first (in other words, @samp{-} and @samp{]} are not special there). - -A complemented character alternative can match a newline, unless newline is -mentioned as one of the characters not to match. This is in contrast to -the handling of regexps in programs such as @code{grep}. - -You can specify named character classes, just like in character -alternatives. For instance, @samp{[^[:ascii:]]} matches any -non-@acronym{ASCII} character. @xref{Char Classes}. - -@item @samp{^} -@cindex beginning of line in regexp -When matching a buffer, @samp{^} matches the empty string, but only at the -beginning of a line in the text being matched (or the beginning of the -accessible portion of the buffer). Otherwise it fails to match -anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the -beginning of a line. - -When matching a string instead of a buffer, @samp{^} matches at the -beginning of the string or after a newline character. - -For historical compatibility reasons, @samp{^} can be used only at the -beginning of the regular expression, or after @samp{\(}, @samp{\(?:} -or @samp{\|}. - -@item @samp{$} -@cindex @samp{$} in regexp -@cindex end of line in regexp -is similar to @samp{^} but matches only at the end of a line (or the -end of the accessible portion of the buffer). Thus, @samp{x+$} -matches a string of one @samp{x} or more at the end of a line. - -When matching a string instead of a buffer, @samp{$} matches at the end -of the string or before a newline character. - -For historical compatibility reasons, @samp{$} can be used only at the -end of the regular expression, or before @samp{\)} or @samp{\|}. - -@item @samp{\} -@cindex @samp{\} in regexp -has two functions: it quotes the special characters (including -@samp{\}), and it introduces additional special constructs. - -Because @samp{\} quotes special characters, @samp{\$} is a regular -expression that matches only @samp{$}, and @samp{\[} is a regular -expression that matches only @samp{[}, and so on. - -Note that @samp{\} also has special meaning in the read syntax of Lisp -strings (@pxref{String Type}), and must be quoted with @samp{\}. For -example, the regular expression that matches the @samp{\} character is -@samp{\\}. To write a Lisp string that contains the characters -@samp{\\}, Lisp syntax requires you to quote each @samp{\} with another -@samp{\}. Therefore, the read syntax for a regular expression matching -@samp{\} is @code{"\\\\"}.@refill -@end table - -@strong{Please note:} For historical compatibility, special characters -are treated as ordinary ones if they are in contexts where their special -meanings make no sense. For example, @samp{*foo} treats @samp{*} as -ordinary since there is no preceding expression on which the @samp{*} -can act. It is poor practice to depend on this behavior; quote the -special character anyway, regardless of where it appears.@refill - -As a @samp{\} is not special inside a character alternative, it can -never remove the special meaning of @samp{-} or @samp{]}. So you -should not quote these characters when they have no special meaning -either. This would not clarify anything, since backslashes can -legitimately precede these characters where they @emph{have} special -meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), -which matches any single character except a backslash. - -In practice, most @samp{]} that occur in regular expressions close a -character alternative and hence are special. However, occasionally a -regular expression may try to match a complex pattern of literal -@samp{[} and @samp{]}. In such situations, it sometimes may be -necessary to carefully parse the regexp from the start to determine -which square brackets enclose a character alternative. For example, -@samp{[^][]]} consists of the complemented character alternative -@samp{[^][]} (which matches any single character that is not a square -bracket), followed by a literal @samp{]}. - -The exact rules are that at the beginning of a regexp, @samp{[} is -special and @samp{]} not. This lasts until the first unquoted -@samp{[}, after which we are in a character alternative; @samp{[} is -no longer special (except when it starts a character class) but @samp{]} -is special, unless it immediately follows the special @samp{[} or that -@samp{[} followed by a @samp{^}. This lasts until the next special -@samp{]} that does not end a character class. This ends the character -alternative and restores the ordinary syntax of regular expressions; -an unquoted @samp{[} is special again and a @samp{]} not. - -@node Char Classes -@subsubsection Character Classes -@cindex character classes in regexp - - Here is a table of the classes you can use in a character alternative, -and what they mean: - -@table @samp -@item [:ascii:] -This matches any @acronym{ASCII} character (codes 0--127). -@item [:alnum:] -This matches any letter or digit. (At present, for multibyte -characters, it matches anything that has word syntax.) -@item [:alpha:] -This matches any letter. (At present, for multibyte characters, it -matches anything that has word syntax.) -@item [:blank:] -This matches space and tab only. -@item [:cntrl:] -This matches any @acronym{ASCII} control character. -@item [:digit:] -This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]} -matches any digit, as well as @samp{+} and @samp{-}. -@item [:graph:] -This matches graphic characters---everything except @acronym{ASCII} control -characters, space, and the delete character. -@item [:lower:] -This matches any lower-case letter, as determined by the current case -table (@pxref{Case Tables}). If @code{case-fold-search} is -non-@code{nil}, this also matches any upper-case letter. -@item [:multibyte:] -This matches any multibyte character (@pxref{Text Representations}). -@item [:nonascii:] -This matches any non-@acronym{ASCII} character. -@item [:print:] -This matches printing characters---everything except @acronym{ASCII} control -characters and the delete character. -@item [:punct:] -This matches any punctuation character. (At present, for multibyte -characters, it matches anything that has non-word syntax.) -@item [:space:] -This matches any character that has whitespace syntax -(@pxref{Syntax Class Table}). -@item [:unibyte:] -This matches any unibyte character (@pxref{Text Representations}). -@item [:upper:] -This matches any upper-case letter, as determined by the current case -table (@pxref{Case Tables}). If @code{case-fold-search} is -non-@code{nil}, this also matches any lower-case letter. -@item [:word:] -This matches any character that has word syntax (@pxref{Syntax Class -Table}). -@item [:xdigit:] -This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a} -through @samp{f} and @samp{A} through @samp{F}. -@end table - -@node Regexp Backslash -@subsubsection Backslash Constructs in Regular Expressions -@cindex backslash in regular expressions - - For the most part, @samp{\} followed by any character matches only -that character. However, there are several exceptions: certain -two-character sequences starting with @samp{\} that have special -meanings. (The character after the @samp{\} in such a sequence is -always ordinary when used on its own.) Here is a table of the special -@samp{\} constructs. - -@table @samp -@item \| -@cindex @samp{|} in regexp -@cindex regexp alternative -specifies an alternative. -Two regular expressions @var{a} and @var{b} with @samp{\|} in -between form an expression that matches anything that either @var{a} or -@var{b} matches.@refill - -Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string.@refill - -@samp{\|} applies to the largest possible surrounding expressions. Only a -surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}.@refill - -If you need full backtracking capability to handle multiple uses of -@samp{\|}, use the POSIX regular expression functions (@pxref{POSIX -Regexps}). - -@item \@{@var{m}\@} -is a postfix operator that repeats the previous pattern exactly @var{m} -times. Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx} -and nothing else. @samp{c[ad]\@{3\@}r} matches string such as -@samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on. - -@item \@{@var{m},@var{n}\@} -is a more general postfix operator that specifies repetition with a -minimum of @var{m} repeats and a maximum of @var{n} repeats. If @var{m} -is omitted, the minimum is 0; if @var{n} is omitted, there is no -maximum. - -For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car}, -@samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and -nothing else.@* -@samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}.@* -@samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}.@* -@samp{\@{1,\@}} is equivalent to @samp{+}. - -@item \( @dots{} \) -@cindex @samp{(} in regexp -@cindex @samp{)} in regexp -@cindex regexp grouping -is a grouping construct that serves three purposes: - -@enumerate -@item -To enclose a set of @samp{\|} alternatives for other operations. Thus, -the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox} -or @samp{barx}. - -@item -To enclose a complicated expression for the postfix operators @samp{*}, -@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches -@samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any -number (zero or more) of @samp{na} strings. - -@item -To record a matched substring for future reference with -@samp{\@var{digit}} (see below). -@end enumerate - -This last application is not a consequence of the idea of a -parenthetical grouping; it is a separate feature that was assigned as a -second meaning to the same @samp{\( @dots{} \)} construct because, in -practice, there was usually no conflict between the two meanings. But -occasionally there is a conflict, and that led to the introduction of -shy groups. - -@item \(?: @dots{} \) -@cindex shy groups -@cindex non-capturing group -@cindex unnumbered group -@cindex @samp{(?:} in regexp -is the @dfn{shy group} construct. A shy group serves the first two -purposes of an ordinary group (controlling the nesting of other -operators), but it does not get a number, so you cannot refer back to -its value with @samp{\@var{digit}}. Shy groups are particularly -useful for mechanically-constructed regular expressions, because they -can be added automatically without altering the numbering of ordinary, -non-shy groups. - -Shy groups are also called @dfn{non-capturing} or @dfn{unnumbered -groups}. - -@item \(?@var{num}: @dots{} \) -is the @dfn{explicitly numbered group} construct. Normal groups get -their number implicitly, based on their position, which can be -inconvenient. This construct allows you to force a particular group -number. There is no particular restriction on the numbering, -e.g.@: you can have several groups with the same number in which case -the last one to match (i.e.@: the rightmost match) will win. -Implicitly numbered groups always get the smallest integer larger than -the one of any previous group. - -@item \@var{digit} -matches the same text that matched the @var{digit}th occurrence of a -grouping (@samp{\( @dots{} \)}) construct. - -In other words, after the end of a group, the matcher remembers the -beginning and end of the text matched by that group. Later on in the -regular expression you can use @samp{\} followed by @var{digit} to -match that same text, whatever it may have been. - -The strings matching the first nine grouping constructs appearing in -the entire regular expression passed to a search or matching function -are assigned numbers 1 through 9 in the order that the open -parentheses appear in the regular expression. So you can use -@samp{\1} through @samp{\9} to refer to the text matched by the -corresponding grouping constructs. - -For example, @samp{\(.*\)\1} matches any newline-free string that is -composed of two identical halves. The @samp{\(.*\)} matches the first -half, which may be anything, but the @samp{\1} that follows must match -the same exact text. - -If a @samp{\( @dots{} \)} construct matches more than once (which can -happen, for instance, if it is followed by @samp{*}), only the last -match is recorded. - -If a particular grouping construct in the regular expression was never -matched---for instance, if it appears inside of an alternative that -wasn't used, or inside of a repetition that repeated zero times---then -the corresponding @samp{\@var{digit}} construct never matches -anything. To use an artificial example, @samp{\(foo\(b*\)\|lose\)\2} -cannot match @samp{lose}: the second alternative inside the larger -group matches it, but then @samp{\2} is undefined and can't match -anything. But it can match @samp{foobb}, because the first -alternative matches @samp{foob} and @samp{\2} matches @samp{b}. - -@item \w -@cindex @samp{\w} in regexp -matches any word-constituent character. The editor syntax table -determines which characters these are. @xref{Syntax Tables}. - -@item \W -@cindex @samp{\W} in regexp -matches any character that is not a word constituent. - -@item \s@var{code} -@cindex @samp{\s} in regexp -matches any character whose syntax is @var{code}. Here @var{code} is a -character that represents a syntax code: thus, @samp{w} for word -constituent, @samp{-} for whitespace, @samp{(} for open parenthesis, -etc. To represent whitespace syntax, use either @samp{-} or a space -character. @xref{Syntax Class Table}, for a list of syntax codes and -the characters that stand for them. - -@item \S@var{code} -@cindex @samp{\S} in regexp -matches any character whose syntax is not @var{code}. - -@cindex category, regexp search for -@item \c@var{c} -matches any character whose category is @var{c}. Here @var{c} is a -character that represents a category: thus, @samp{c} for Chinese -characters or @samp{g} for Greek characters in the standard category -table. You can see the list of all the currently defined categories -with @kbd{M-x describe-categories @key{RET}}. You can also define -your own categories in addition to the standard ones using the -@code{define-category} function (@pxref{Categories}). - -@item \C@var{c} -matches any character whose category is not @var{c}. -@end table - - The following regular expression constructs match the empty string---that is, -they don't use up any characters---but whether they match depends on the -context. For all, the beginning and end of the accessible portion of -the buffer are treated as if they were the actual beginning and end of -the buffer. - -@table @samp -@item \` -@cindex @samp{\`} in regexp -matches the empty string, but only at the beginning -of the buffer or string being matched against. - -@item \' -@cindex @samp{\'} in regexp -matches the empty string, but only at the end of -the buffer or string being matched against. - -@item \= -@cindex @samp{\=} in regexp -matches the empty string, but only at point. -(This construct is not defined when matching against a string.) - -@item \b -@cindex @samp{\b} in regexp -matches the empty string, but only at the beginning or -end of a word. Thus, @samp{\bfoo\b} matches any occurrence of -@samp{foo} as a separate word. @samp{\bballs?\b} matches -@samp{ball} or @samp{balls} as a separate word.@refill - -@samp{\b} matches at the beginning or end of the buffer (or string) -regardless of what text appears next to it. - -@item \B -@cindex @samp{\B} in regexp -matches the empty string, but @emph{not} at the beginning or -end of a word, nor at the beginning or end of the buffer (or string). - -@item \< -@cindex @samp{\<} in regexp -matches the empty string, but only at the beginning of a word. -@samp{\<} matches at the beginning of the buffer (or string) only if a -word-constituent character follows. - -@item \> -@cindex @samp{\>} in regexp -matches the empty string, but only at the end of a word. @samp{\>} -matches at the end of the buffer (or string) only if the contents end -with a word-constituent character. - -@item \_< -@cindex @samp{\_<} in regexp -matches the empty string, but only at the beginning of a symbol. A -symbol is a sequence of one or more word or symbol constituent -characters. @samp{\_<} matches at the beginning of the buffer (or -string) only if a symbol-constituent character follows. - -@item \_> -@cindex @samp{\_>} in regexp -matches the empty string, but only at the end of a symbol. @samp{\_>} -matches at the end of the buffer (or string) only if the contents end -with a symbol-constituent character. -@end table - -@kindex invalid-regexp - Not every string is a valid regular expression. For example, a string -that ends inside a character alternative without a terminating @samp{]} -is invalid, and so is a string that ends with a single @samp{\}. If -an invalid regular expression is passed to any of the search functions, -an @code{invalid-regexp} error is signaled. - -@node Regexp Example -@comment node-name, next, previous, up -@subsection Complex Regexp Example - - Here is a complicated regexp which was formerly used by Emacs to -recognize the end of a sentence together with any whitespace that -follows. (Nowadays Emacs uses a similar but more complex default -regexp constructed by the function @code{sentence-end}. -@xref{Standard Regexps}.) - - Below, we show first the regexp as a string in Lisp syntax (to -distinguish spaces from tab characters), and then the result of -evaluating it. The string constant begins and ends with a -double-quote. @samp{\"} stands for a double-quote as part of the -string, @samp{\\} for a backslash as part of the string, @samp{\t} for a -tab and @samp{\n} for a newline. - -@example -@group -"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*" - @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[ -]*" -@end group -@end example - -@noindent -In the output, tab and newline appear as themselves. - - This regular expression contains four parts in succession and can be -deciphered as follows: - -@table @code -@item [.?!] -The first part of the pattern is a character alternative that matches -any one of three characters: period, question mark, and exclamation -mark. The match must begin with one of these three characters. (This -is one point where the new default regexp used by Emacs differs from -the old. The new value also allows some non-@acronym{ASCII} -characters that end a sentence without any following whitespace.) - -@item []\"')@}]* -The second part of the pattern matches any closing braces and quotation -marks, zero or more of them, that may follow the period, question mark -or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in -a string. The @samp{*} at the end indicates that the immediately -preceding regular expression (a character alternative, in this case) may be -repeated zero or more times. - -@item \\($\\|@ $\\|\t\\|@ @ \\) -The third part of the pattern matches the whitespace that follows the -end of a sentence: the end of a line (optionally with a space), or a -tab, or two spaces. The double backslashes mark the parentheses and -vertical bars as regular expression syntax; the parentheses delimit a -group and the vertical bars separate alternatives. The dollar sign is -used to match the end of a line. - -@item [ \t\n]* -Finally, the last part of the pattern matches any additional whitespace -beyond the minimum needed to end a sentence. -@end table - -@node Regexp Functions -@subsection Regular Expression Functions - - These functions operate on regular expressions. - -@defun regexp-quote string -This function returns a regular expression whose only exact match is -@var{string}. Using this regular expression in @code{looking-at} will -succeed only if the next characters in the buffer are @var{string}; -using it in a search function will succeed if the text being searched -contains @var{string}. @xref{Regexp Search}. - -This allows you to request an exact string match or search when calling -a function that wants a regular expression. - -@example -@group -(regexp-quote "^The cat$") - @result{} "\\^The cat\\$" -@end group -@end example - -One use of @code{regexp-quote} is to combine an exact string match with -context described as a regular expression. For example, this searches -for the string that is the value of @var{string}, surrounded by -whitespace: - -@example -@group -(re-search-forward - (concat "\\s-" (regexp-quote string) "\\s-")) -@end group -@end example -@end defun - -@defun regexp-opt strings &optional paren -This function returns an efficient regular expression that will match -any of the strings in the list @var{strings}. This is useful when you -need to make matching or searching as fast as possible---for example, -for Font Lock mode@footnote{Note that @code{regexp-opt} does not -guarantee that its result is absolutely the most efficient form -possible. A hand-tuned regular expression can sometimes be slightly -more efficient, but is almost never worth the effort.}. -@c See eg http://debbugs.gnu.org/2816 - -If the optional argument @var{paren} is non-@code{nil}, then the -returned regular expression is always enclosed by at least one -parentheses-grouping construct. If @var{paren} is @code{words}, then -that construct is additionally surrounded by @samp{\<} and @samp{\>}; -alternatively, if @var{paren} is @code{symbols}, then that construct -is additionally surrounded by @samp{\_<} and @samp{\_>} -(@code{symbols} is often appropriate when matching -programming-language keywords and the like). - -This simplified definition of @code{regexp-opt} produces a -regular expression which is equivalent to the actual value -(but not as efficient): - -@example -(defun regexp-opt (strings &optional paren) - (let ((open-paren (if paren "\\(" "")) - (close-paren (if paren "\\)" ""))) - (concat open-paren - (mapconcat 'regexp-quote strings "\\|") - close-paren))) -@end example -@end defun - -@defun regexp-opt-depth regexp -This function returns the total number of grouping constructs -(parenthesized expressions) in @var{regexp}. This does not include -shy groups (@pxref{Regexp Backslash}). -@end defun - -@c Supposedly an internal regexp-opt function, but table.el uses it at least. -@defun regexp-opt-charset chars -This function returns a regular expression matching a character in the -list of characters @var{chars}. - -@example -(regexp-opt-charset '(?a ?b ?c ?d ?e)) - @result{} "[a-e]" -@end example -@end defun - -@c Internal functions: regexp-opt-group - -@node Regexp Search -@section Regular Expression Searching -@cindex regular expression searching -@cindex regexp searching -@cindex searching for regexp - - In GNU Emacs, you can search for the next match for a regular -expression either incrementally or not. For incremental search -commands, see @ref{Regexp Search, , Regular Expression Search, emacs, -The GNU Emacs Manual}. Here we describe only the search functions -useful in programs. The principal one is @code{re-search-forward}. - - These search functions convert the regular expression to multibyte if -the buffer is multibyte; they convert the regular expression to unibyte -if the buffer is unibyte. @xref{Text Representations}. - -@deffn Command re-search-forward regexp &optional limit noerror repeat -This function searches forward in the current buffer for a string of -text that is matched by the regular expression @var{regexp}. The -function skips over any amount of text that is not matched by -@var{regexp}, and leaves point at the end of the first match found. -It returns the new value of point. - -If @var{limit} is non-@code{nil}, it must be a position in the current -buffer. It specifies the upper bound to the search. No match -extending after that position is accepted. - -If @var{repeat} is supplied, it must be a positive number; the search -is repeated that many times; each repetition starts at the end of the -previous match. If all these successive searches succeed, the search -succeeds, moving point and returning its new value. Otherwise the -search fails. What @code{re-search-forward} does when the search -fails depends on the value of @var{noerror}: - -@table @asis -@item @code{nil} -Signal a @code{search-failed} error. -@item @code{t} -Do nothing and return @code{nil}. -@item anything else -Move point to @var{limit} (or the end of the accessible portion of the -buffer) and return @code{nil}. -@end table - -In the following example, point is initially before the @samp{T}. -Evaluating the search call moves point to the end of that line (between -the @samp{t} of @samp{hat} and the newline). - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- -@end group - -@group -(re-search-forward "[a-z]+" nil t 5) - @result{} 27 - ----------- Buffer: foo ---------- -I read "The cat in the hat@point{} -comes back" twice. ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command re-search-backward regexp &optional limit noerror repeat -This function searches backward in the current buffer for a string of -text that is matched by the regular expression @var{regexp}, leaving -point at the beginning of the first text found. - -This function is analogous to @code{re-search-forward}, but they are not -simple mirror images. @code{re-search-forward} finds the match whose -beginning is as close as possible to the starting point. If -@code{re-search-backward} were a perfect mirror image, it would find the -match whose end is as close as possible. However, in fact it finds the -match whose beginning is as close as possible (and yet ends before the -starting point). The reason for this is that matching a regular -expression at a given spot always works from beginning to end, and -starts at a specified beginning position. - -A true mirror-image of @code{re-search-forward} would require a special -feature for matching regular expressions from end to beginning. It's -not worth the trouble of implementing that. -@end deffn - -@defun string-match regexp string &optional start -This function returns the index of the start of the first match for -the regular expression @var{regexp} in @var{string}, or @code{nil} if -there is no match. If @var{start} is non-@code{nil}, the search starts -at that index in @var{string}. - -For example, - -@example -@group -(string-match - "quick" "The quick brown fox jumped quickly.") - @result{} 4 -@end group -@group -(string-match - "quick" "The quick brown fox jumped quickly." 8) - @result{} 27 -@end group -@end example - -@noindent -The index of the first character of the -string is 0, the index of the second character is 1, and so on. - -After this function returns, the index of the first character beyond -the match is available as @code{(match-end 0)}. @xref{Match Data}. - -@example -@group -(string-match - "quick" "The quick brown fox jumped quickly." 8) - @result{} 27 -@end group - -@group -(match-end 0) - @result{} 32 -@end group -@end example -@end defun - -@defun string-match-p regexp string &optional start -This predicate function does what @code{string-match} does, but it -avoids modifying the match data. -@end defun - -@defun looking-at regexp -This function determines whether the text in the current buffer directly -following point matches the regular expression @var{regexp}. ``Directly -following'' means precisely that: the search is ``anchored'' and it can -succeed only starting with the first character following point. The -result is @code{t} if so, @code{nil} otherwise. - -This function does not move point, but it does update the match data. -@xref{Match Data}. If you need to test for a match without modifying -the match data, use @code{looking-at-p}, described below. - -In this example, point is located directly before the @samp{T}. If it -were anywhere else, the result would be @code{nil}. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- - -(looking-at "The cat in the hat$") - @result{} t -@end group -@end example -@end defun - -@defun looking-back regexp &optional limit greedy -This function returns @code{t} if @var{regexp} matches the text -immediately before point (i.e., ending at point), and @code{nil} otherwise. - -Because regular expression matching works only going forward, this is -implemented by searching backwards from point for a match that ends at -point. That can be quite slow if it has to search a long distance. -You can bound the time required by specifying @var{limit}, which says -not to search before @var{limit}. In this case, the match that is -found must begin at or after @var{limit}. - -If @var{greedy} is non-@code{nil}, this function extends the match -backwards as far as possible, stopping when a single additional -previous character cannot be part of a match for regexp. When the -match is extended, its starting position is allowed to occur before -@var{limit}. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- - -(looking-back "read \"" 3) - @result{} t -(looking-back "read \"" 4) - @result{} nil -@end group -@end example - -@c http://debbugs.gnu.org/5689 -As a general recommendation, try to avoid using @code{looking-back} -wherever possible, since it is slow. For this reason, there are no -plans to add a @code{looking-back-p} function. -@end defun - -@defun looking-at-p regexp -This predicate function works like @code{looking-at}, but without -updating the match data. -@end defun - -@defvar search-spaces-regexp -If this variable is non-@code{nil}, it should be a regular expression -that says how to search for whitespace. In that case, any group of -spaces in a regular expression being searched for stands for use of -this regular expression. However, spaces inside of constructs such as -@samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by -@code{search-spaces-regexp}. - -Since this variable affects all regular expression search and match -constructs, you should bind it temporarily for as small as possible -a part of the code. -@end defvar - -@node POSIX Regexps -@section POSIX Regular Expression Searching - -@cindex backtracking and POSIX regular expressions - The usual regular expression functions do backtracking when necessary -to handle the @samp{\|} and repetition constructs, but they continue -this only until they find @emph{some} match. Then they succeed and -report the first match found. - - This section describes alternative search functions which perform the -full backtracking specified by the POSIX standard for regular expression -matching. They continue backtracking until they have tried all -possibilities and found all matches, so they can report the longest -match, as required by POSIX. This is much slower, so use these -functions only when you really need the longest match. - - The POSIX search and match functions do not properly support the -non-greedy repetition operators (@pxref{Regexp Special, non-greedy}). -This is because POSIX backtracking conflicts with the semantics of -non-greedy repetition. - -@deffn Command posix-search-forward regexp &optional limit noerror repeat -This is like @code{re-search-forward} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end deffn - -@deffn Command posix-search-backward regexp &optional limit noerror repeat -This is like @code{re-search-backward} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end deffn - -@defun posix-looking-at regexp -This is like @code{looking-at} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@defun posix-string-match regexp string &optional start -This is like @code{string-match} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@node Match Data -@section The Match Data -@cindex match data - - Emacs keeps track of the start and end positions of the segments of -text found during a search; this is called the @dfn{match data}. -Thanks to the match data, you can search for a complex pattern, such -as a date in a mail message, and then extract parts of the match under -control of the pattern. - - Because the match data normally describe the most recent search only, -you must be careful not to do another search inadvertently between the -search you wish to refer back to and the use of the match data. If you -can't avoid another intervening search, you must save and restore the -match data around it, to prevent it from being overwritten. - - Notice that all functions are allowed to overwrite the match data -unless they're explicitly documented not to do so. A consequence is -that functions that are run implicitly in the background -(@pxref{Timers}, and @ref{Idle Timers}) should likely save and restore -the match data explicitly. - -@menu -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. -@end menu - -@node Replacing Match -@subsection Replacing the Text that Matched -@cindex replace matched text - - This function replaces all or part of the text matched by the last -search. It works by means of the match data. - -@cindex case in replacements -@defun replace-match replacement &optional fixedcase literal string subexp -This function replaces the text in the buffer (or in @var{string}) that -was matched by the last search. It replaces that text with -@var{replacement}. - -If you did the last search in a buffer, you should specify @code{nil} -for @var{string} and make sure that the current buffer when you call -@code{replace-match} is the one in which you did the searching or -matching. Then @code{replace-match} does the replacement by editing -the buffer; it leaves point at the end of the replacement text, and -returns @code{t}. - -If you did the search in a string, pass the same string as @var{string}. -Then @code{replace-match} does the replacement by constructing and -returning a new string. - -If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses -the replacement text without case conversion; otherwise, it converts -the replacement text depending upon the capitalization of the text to -be replaced. If the original text is all upper case, this converts -the replacement text to upper case. If all words of the original text -are capitalized, this capitalizes all the words of the replacement -text. If all the words are one-letter and they are all upper case, -they are treated as capitalized words rather than all-upper-case -words. - -If @var{literal} is non-@code{nil}, then @var{replacement} is inserted -exactly as it is, the only alterations being case changes as needed. -If it is @code{nil} (the default), then the character @samp{\} is treated -specially. If a @samp{\} appears in @var{replacement}, then it must be -part of one of the following sequences: - -@table @asis -@item @samp{\&} -@cindex @samp{&} in replacement -@samp{\&} stands for the entire text being replaced. - -@item @samp{\@var{n}} -@cindex @samp{\@var{n}} in replacement -@samp{\@var{n}}, where @var{n} is a digit, stands for the text that -matched the @var{n}th subexpression in the original regexp. -Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}. -If the @var{n}th subexpression never matched, an empty string is substituted. - -@item @samp{\\} -@cindex @samp{\} in replacement -@samp{\\} stands for a single @samp{\} in the replacement text. -@end table - -These substitutions occur after case conversion, if any, -so the strings they substitute are never case-converted. - -If @var{subexp} is non-@code{nil}, that says to replace just -subexpression number @var{subexp} of the regexp that was matched, not -the entire match. For example, after matching @samp{foo \(ba*r\)}, -calling @code{replace-match} with 1 as @var{subexp} means to replace -just the text that matched @samp{\(ba*r\)}. -@end defun - -@defun match-substitute-replacement replacement &optional fixedcase literal string subexp -This function returns the text that would be inserted into the buffer -by @code{replace-match}, but without modifying the buffer. It is -useful if you want to present the user with actual replacement result, -with constructs like @samp{\@var{n}} or @samp{\&} substituted with -matched groups. Arguments @var{replacement} and optional -@var{fixedcase}, @var{literal}, @var{string} and @var{subexp} have the -same meaning as for @code{replace-match}. -@end defun - -@node Simple Match Data -@subsection Simple Match Data Access - - This section explains how to use the match data to find out what was -matched by the last search or match operation, if it succeeded. - - You can ask about the entire matching text, or about a particular -parenthetical subexpression of a regular expression. The @var{count} -argument in the functions below specifies which. If @var{count} is -zero, you are asking about the entire match. If @var{count} is -positive, it specifies which subexpression you want. - - Recall that the subexpressions of a regular expression are those -expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The -@var{count}th subexpression is found by counting occurrences of -@samp{\(} from the beginning of the whole regular expression. The first -subexpression is numbered 1, the second 2, and so on. Only regular -expressions can have subexpressions---after a simple string search, the -only information available is about the entire match. - - Every successful search sets the match data. Therefore, you should -query the match data immediately after searching, before calling any -other function that might perform another search. Alternatively, you -may save and restore the match data (@pxref{Saving Match Data}) around -the call to functions that could perform another search. Or use the -functions that explicitly do not modify the match data; -e.g. @code{string-match-p}. - -@c This is an old comment and presumably there is no prospect of this -@c changing now. But still the advice stands. - A search which fails may or may not alter the match data. In the -current implementation, it does not, but we may change it in the -future. Don't try to rely on the value of the match data after a -failing search. - -@defun match-string count &optional in-string -This function returns, as a string, the text matched in the last search -or match operation. It returns the entire text if @var{count} is zero, -or just the portion corresponding to the @var{count}th parenthetical -subexpression, if @var{count} is positive. - -If the last such operation was done against a string with -@code{string-match}, then you should pass the same string as the -argument @var{in-string}. After a buffer search or match, -you should omit @var{in-string} or pass @code{nil} for it; but you -should make sure that the current buffer when you call -@code{match-string} is the one in which you did the searching or -matching. Failure to follow this advice will lead to incorrect results. - -The value is @code{nil} if @var{count} is out of range, or for a -subexpression inside a @samp{\|} alternative that wasn't used or a -repetition that repeated zero times. -@end defun - -@defun match-string-no-properties count &optional in-string -This function is like @code{match-string} except that the result -has no text properties. -@end defun - -@defun match-beginning count -This function returns the position of the start of the text matched by the -last regular expression searched for, or a subexpression of it. - -If @var{count} is zero, then the value is the position of the start of -the entire match. Otherwise, @var{count} specifies a subexpression in -the regular expression, and the value of the function is the starting -position of the match for that subexpression. - -The value is @code{nil} for a subexpression inside a @samp{\|} -alternative that wasn't used or a repetition that repeated zero times. -@end defun - -@defun match-end count -This function is like @code{match-beginning} except that it returns the -position of the end of the match, rather than the position of the -beginning. -@end defun - - Here is an example of using the match data, with a comment showing the -positions within the text: - -@example -@group -(string-match "\\(qu\\)\\(ick\\)" - "The quick fox jumped quickly.") - ;0123456789 - @result{} 4 -@end group - -@group -(match-string 0 "The quick fox jumped quickly.") - @result{} "quick" -(match-string 1 "The quick fox jumped quickly.") - @result{} "qu" -(match-string 2 "The quick fox jumped quickly.") - @result{} "ick" -@end group - -@group -(match-beginning 1) ; @r{The beginning of the match} - @result{} 4 ; @r{with @samp{qu} is at index 4.} -@end group - -@group -(match-beginning 2) ; @r{The beginning of the match} - @result{} 6 ; @r{with @samp{ick} is at index 6.} -@end group - -@group -(match-end 1) ; @r{The end of the match} - @result{} 6 ; @r{with @samp{qu} is at index 6.} - -(match-end 2) ; @r{The end of the match} - @result{} 9 ; @r{with @samp{ick} is at index 9.} -@end group -@end example - - Here is another example. Point is initially located at the beginning -of the line. Searching moves point to between the space and the word -@samp{in}. The beginning of the entire match is at the 9th character of -the buffer (@samp{T}), and the beginning of the match for the first -subexpression is at the 13th character (@samp{c}). - -@example -@group -(list - (re-search-forward "The \\(cat \\)") - (match-beginning 0) - (match-beginning 1)) - @result{} (17 9 13) -@end group - -@group ----------- Buffer: foo ---------- -I read "The cat @point{}in the hat comes back" twice. - ^ ^ - 9 13 ----------- Buffer: foo ---------- -@end group -@end example - -@noindent -(In this case, the index returned is a buffer position; the first -character of the buffer counts as 1.) - -@node Entire Match Data -@subsection Accessing the Entire Match Data - - The functions @code{match-data} and @code{set-match-data} read or -write the entire match data, all at once. - -@defun match-data &optional integers reuse reseat -This function returns a list of positions (markers or integers) that -record all the information on the text that the last search matched. -Element zero is the position of the beginning of the match for the -whole expression; element one is the position of the end of the match -for the expression. The next two elements are the positions of the -beginning and end of the match for the first subexpression, and so on. -In general, element -@ifnottex -number 2@var{n} -@end ifnottex -@tex -number {\mathsurround=0pt $2n$} -@end tex -corresponds to @code{(match-beginning @var{n})}; and -element -@ifnottex -number 2@var{n} + 1 -@end ifnottex -@tex -number {\mathsurround=0pt $2n+1$} -@end tex -corresponds to @code{(match-end @var{n})}. - -Normally all the elements are markers or @code{nil}, but if -@var{integers} is non-@code{nil}, that means to use integers instead -of markers. (In that case, the buffer itself is appended as an -additional element at the end of the list, to facilitate complete -restoration of the match data.) If the last match was done on a -string with @code{string-match}, then integers are always used, -since markers can't point into a string. - -If @var{reuse} is non-@code{nil}, it should be a list. In that case, -@code{match-data} stores the match data in @var{reuse}. That is, -@var{reuse} is destructively modified. @var{reuse} does not need to -have the right length. If it is not long enough to contain the match -data, it is extended. If it is too long, the length of @var{reuse} -stays the same, but the elements that were not used are set to -@code{nil}. The purpose of this feature is to reduce the need for -garbage collection. - -If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list -are reseated to point to nowhere. - -As always, there must be no possibility of intervening searches between -the call to a search function and the call to @code{match-data} that is -intended to access the match data for that search. - -@example -@group -(match-data) - @result{} (# - # - # - #) -@end group -@end example -@end defun - -@defun set-match-data match-list &optional reseat -This function sets the match data from the elements of @var{match-list}, -which should be a list that was the value of a previous call to -@code{match-data}. (More precisely, anything that has the same format -will work.) - -If @var{match-list} refers to a buffer that doesn't exist, you don't get -an error; that sets the match data in a meaningless but harmless way. - -If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list -are reseated to point to nowhere. - -@c TODO Make it properly obsolete. -@findex store-match-data -@code{store-match-data} is a semi-obsolete alias for @code{set-match-data}. -@end defun - -@node Saving Match Data -@subsection Saving and Restoring the Match Data - - When you call a function that may search, you may need to save -and restore the match data around that call, if you want to preserve the -match data from an earlier search for later use. Here is an example -that shows the problem that arises if you fail to save the match data: - -@example -@group -(re-search-forward "The \\(cat \\)") - @result{} 48 -(foo) ; @r{@code{foo} does more searching.} -(match-end 0) - @result{} 61 ; @r{Unexpected result---not 48!} -@end group -@end example - - You can save and restore the match data with @code{save-match-data}: - -@defmac save-match-data body@dots{} -This macro executes @var{body}, saving and restoring the match -data around it. The return value is the value of the last form in -@var{body}. -@end defmac - - You could use @code{set-match-data} together with @code{match-data} to -imitate the effect of the special form @code{save-match-data}. Here is -how: - -@example -@group -(let ((data (match-data))) - (unwind-protect - @dots{} ; @r{Ok to change the original match data.} - (set-match-data data))) -@end group -@end example - - Emacs automatically saves and restores the match data when it runs -process filter functions (@pxref{Filter Functions}) and process -sentinels (@pxref{Sentinels}). - -@ignore - Here is a function which restores the match data provided the buffer -associated with it still exists. - -@smallexample -@group -(defun restore-match-data (data) -@c It is incorrect to split the first line of a doc string. -@c If there's a problem here, it should be solved in some other way. - "Restore the match data DATA unless the buffer is missing." - (catch 'foo - (let ((d data)) -@end group - (while d - (and (car d) - (null (marker-buffer (car d))) -@group - ;; @file{match-data} @r{buffer is deleted.} - (throw 'foo nil)) - (setq d (cdr d))) - (set-match-data data)))) -@end group -@end smallexample -@end ignore - -@node Search and Replace -@section Search and Replace -@cindex replacement after search -@cindex searching and replacing - - If you want to find all matches for a regexp in part of the buffer, -and replace them, the best way is to write an explicit loop using -@code{re-search-forward} and @code{replace-match}, like this: - -@example -(while (re-search-forward "foo[ \t]+bar" nil t) - (replace-match "foobar")) -@end example - -@noindent -@xref{Replacing Match,, Replacing the Text that Matched}, for a -description of @code{replace-match}. - - However, replacing matches in a string is more complex, especially -if you want to do it efficiently. So Emacs provides a function to do -this. - -@defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start -This function copies @var{string} and searches it for matches for -@var{regexp}, and replaces them with @var{rep}. It returns the -modified copy. If @var{start} is non-@code{nil}, the search for -matches starts at that index in @var{string}, so matches starting -before that index are not changed. - -This function uses @code{replace-match} to do the replacement, and it -passes the optional arguments @var{fixedcase}, @var{literal} and -@var{subexp} along to @code{replace-match}. - -Instead of a string, @var{rep} can be a function. In that case, -@code{replace-regexp-in-string} calls @var{rep} for each match, -passing the text of the match as its sole argument. It collects the -value @var{rep} returns and passes that to @code{replace-match} as the -replacement string. The match data at this point are the result -of matching @var{regexp} against a substring of @var{string}. -@end defun - - If you want to write a command along the lines of @code{query-replace}, -you can use @code{perform-replace} to do the work. - -@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end -This function is the guts of @code{query-replace} and related -commands. It searches for occurrences of @var{from-string} in the -text between positions @var{start} and @var{end} and replaces some or -all of them. If @var{start} is @code{nil} (or omitted), point is used -instead, and the end of the buffer's accessible portion is used for -@var{end}. - -If @var{query-flag} is @code{nil}, it replaces all -occurrences; otherwise, it asks the user what to do about each one. - -If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is -considered a regular expression; otherwise, it must match literally. If -@var{delimited-flag} is non-@code{nil}, then only replacements -surrounded by word boundaries are considered. - -The argument @var{replacements} specifies what to replace occurrences -with. If it is a string, that string is used. It can also be a list of -strings, to be used in cyclic order. - -If @var{replacements} is a cons cell, @w{@code{(@var{function} -. @var{data})}}, this means to call @var{function} after each match to -get the replacement text. This function is called with two arguments: -@var{data}, and the number of replacements already made. - -If @var{repeat-count} is non-@code{nil}, it should be an integer. Then -it specifies how many times to use each of the strings in the -@var{replacements} list before advancing cyclically to the next one. - -If @var{from-string} contains upper-case letters, then -@code{perform-replace} binds @code{case-fold-search} to @code{nil}, and -it uses the @var{replacements} without altering their case. - -Normally, the keymap @code{query-replace-map} defines the possible -user responses for queries. The argument @var{map}, if -non-@code{nil}, specifies a keymap to use instead of -@code{query-replace-map}. - -This function uses one of two functions to search for the next -occurrence of @var{from-string}. These functions are specified by the -values of two variables: @code{replace-re-search-function} and -@code{replace-search-function}. The former is called when the -argument @var{regexp-flag} is non-@code{nil}, the latter when it is -@code{nil}. -@end defun - -@defvar query-replace-map -This variable holds a special keymap that defines the valid user -responses for @code{perform-replace} and the commands that use it, as -well as @code{y-or-n-p} and @code{map-y-or-n-p}. This map is unusual -in two ways: - -@itemize @bullet -@item -The ``key bindings'' are not commands, just symbols that are meaningful -to the functions that use this map. - -@item -Prefix keys are not supported; each key binding must be for a -single-event key sequence. This is because the functions don't use -@code{read-key-sequence} to get the input; instead, they read a single -event and look it up ``by hand''. -@end itemize -@end defvar - -Here are the meaningful ``bindings'' for @code{query-replace-map}. -Several of them are meaningful only for @code{query-replace} and -friends. - -@table @code -@item act -Do take the action being considered---in other words, ``yes''. - -@item skip -Do not take action for this question---in other words, ``no''. - -@item exit -Answer this question ``no'', and give up on the entire series of -questions, assuming that the answers will be ``no''. - -@item exit-prefix -Like @code{exit}, but add the key that was pressed to -@code{unread-comment-events}. - -@item act-and-exit -Answer this question ``yes'', and give up on the entire series of -questions, assuming that subsequent answers will be ``no''. - -@item act-and-show -Answer this question ``yes'', but show the results---don't advance yet -to the next question. - -@item automatic -Answer this question and all subsequent questions in the series with -``yes'', without further user interaction. - -@item backup -Move back to the previous place that a question was asked about. - -@item edit -Enter a recursive edit to deal with this question---instead of any -other action that would normally be taken. - -@item edit-replacement -Edit the replacement for this question in the minibuffer. - -@item delete-and-edit -Delete the text being considered, then enter a recursive edit to replace -it. - -@item recenter -Redisplay and center the window, then ask the same question again. - -@item quit -Perform a quit right away. Only @code{y-or-n-p} and related functions -use this answer. - -@item help -Display some help, then ask again. -@end table - -@defvar multi-query-replace-map -This variable holds a keymap that extends @code{query-replace-map} by -providing additional keybindings that are useful in multi-buffer -replacements. The additional ``bindings'' are: - -@table @code -@item automatic-all -Answer this question and all subsequent questions in the series with -``yes'', without further user interaction, for all remaining buffers. - -@item exit-current -Answer this question ``no'', and give up on the entire series of -questions for the current buffer. Continue to the next buffer in the -sequence. -@end table -@end defvar - -@defvar replace-search-function -This variable specifies a function that @code{perform-replace} calls -to search for the next string to replace. Its default value is -@code{search-forward}. Any other value should name a function of 3 -arguments: the first 3 arguments of @code{search-forward} -(@pxref{String Search}). -@end defvar - -@defvar replace-re-search-function -This variable specifies a function that @code{perform-replace} calls -to search for the next regexp to replace. Its default value is -@code{re-search-forward}. Any other value should name a function of 3 -arguments: the first 3 arguments of @code{re-search-forward} -(@pxref{Regexp Search}). -@end defvar - -@node Standard Regexps -@section Standard Regular Expressions Used in Editing -@cindex regexps used standardly in editing -@cindex standard regexps used in editing - - This section describes some variables that hold regular expressions -used for certain purposes in editing: - -@defopt page-delimiter -This is the regular expression describing line-beginnings that separate -pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or -@code{"^\C-l"}); this matches a line that starts with a formfeed -character. -@end defopt - - The following two regular expressions should @emph{not} assume the -match always starts at the beginning of a line; they should not use -@samp{^} to anchor the match. Most often, the paragraph commands do -check for a match only at the beginning of a line, which means that -@samp{^} would be superfluous. When there is a nonzero left margin, -they accept matches that start after the left margin. In that case, a -@samp{^} would be incorrect. However, a @samp{^} is harmless in modes -where a left margin is never used. - -@defopt paragraph-separate -This is the regular expression for recognizing the beginning of a line -that separates paragraphs. (If you change this, you may have to -change @code{paragraph-start} also.) The default value is -@w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of -spaces, tabs, and form feeds (after its left margin). -@end defopt - -@defopt paragraph-start -This is the regular expression for recognizing the beginning of a line -that starts @emph{or} separates paragraphs. The default value is -@w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only -whitespace or starting with a form feed (after its left margin). -@end defopt - -@defopt sentence-end -If non-@code{nil}, the value should be a regular expression describing -the end of a sentence, including the whitespace following the -sentence. (All paragraph boundaries also end sentences, regardless.) - -If the value is @code{nil}, as it is by default, then the function -@code{sentence-end} constructs the regexp. That is why you -should always call the function @code{sentence-end} to obtain the -regexp to be used to recognize the end of a sentence. -@end defopt - -@defun sentence-end -This function returns the value of the variable @code{sentence-end}, -if non-@code{nil}. Otherwise it returns a default value based on the -values of the variables @code{sentence-end-double-space} -(@pxref{Definition of sentence-end-double-space}), -@code{sentence-end-without-period}, and -@code{sentence-end-without-space}. -@end defun diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi deleted file mode 100644 index 1a1160a34d7..00000000000 --- a/doc/lispref/sequences.texi +++ /dev/null @@ -1,827 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/sequences -@node Sequences Arrays Vectors, Hash Tables, Lists, Top -@chapter Sequences, Arrays, and Vectors -@cindex sequence - - The @dfn{sequence} type is the union of two other Lisp types: lists -and arrays. In other words, any list is a sequence, and any array is -a sequence. The common property that all sequences have is that each -is an ordered collection of elements. - - An @dfn{array} is a fixed-length object with a slot for each of its -elements. All the elements are accessible in constant time. The four -types of arrays are strings, vectors, char-tables and bool-vectors. - - A list is a sequence of elements, but it is not a single primitive -object; it is made of cons cells, one cell per element. Finding the -@var{n}th element requires looking through @var{n} cons cells, so -elements farther from the beginning of the list take longer to access. -But it is possible to add elements to the list, or remove elements. - - The following diagram shows the relationship between these types: - -@example -@group - _____________________________________________ - | | - | Sequence | - | ______ ________________________________ | - | | | | | | - | | List | | Array | | - | | | | ________ ________ | | - | |______| | | | | | | | - | | | Vector | | String | | | - | | |________| |________| | | - | | ____________ _____________ | | - | | | | | | | | - | | | Char-table | | Bool-vector | | | - | | |____________| |_____________| | | - | |________________________________| | - |_____________________________________________| -@end group -@end example - -@menu -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Special characteristics of Emacs Lisp vectors. -* Vector Functions:: Functions specifically for vectors. -* Char-Tables:: How to work with char-tables. -* Bool-Vectors:: How to work with bool-vectors. -* Rings:: Managing a fixed-size ring of objects. -@end menu - -@node Sequence Functions -@section Sequences - - This section describes functions that accept any kind of sequence. - -@defun sequencep object -This function returns @code{t} if @var{object} is a list, vector, -string, bool-vector, or char-table, @code{nil} otherwise. -@end defun - -@defun length sequence -@cindex string length -@cindex list length -@cindex vector length -@cindex sequence length -@cindex char-table length -This function returns the number of elements in @var{sequence}. If -@var{sequence} is a dotted list, a @code{wrong-type-argument} error is -signaled. Circular lists may cause an infinite loop. For a -char-table, the value returned is always one more than the maximum -Emacs character code. - -@xref{Definition of safe-length}, for the related function @code{safe-length}. - -@example -@group -(length '(1 2 3)) - @result{} 3 -@end group -@group -(length ()) - @result{} 0 -@end group -@group -(length "foobar") - @result{} 6 -@end group -@group -(length [1 2 3]) - @result{} 3 -@end group -@group -(length (make-bool-vector 5 nil)) - @result{} 5 -@end group -@end example -@end defun - -@noindent -See also @code{string-bytes}, in @ref{Text Representations}. - -If you need to compute the width of a string on display, you should -use @code{string-width} (@pxref{Width}), not @code{length}, since -@code{length} only counts the number of characters, but does not -account for the display width of each character. - -@defun elt sequence index -@cindex elements of sequences -This function returns the element of @var{sequence} indexed by -@var{index}. Legitimate values of @var{index} are integers ranging -from 0 up to one less than the length of @var{sequence}. If -@var{sequence} is a list, out-of-range values behave as for -@code{nth}. @xref{Definition of nth}. Otherwise, out-of-range values -trigger an @code{args-out-of-range} error. - -@example -@group -(elt [1 2 3 4] 2) - @result{} 3 -@end group -@group -(elt '(1 2 3 4) 2) - @result{} 3 -@end group -@group -;; @r{We use @code{string} to show clearly which character @code{elt} returns.} -(string (elt "1234" 2)) - @result{} "3" -@end group -@group -(elt [1 2 3 4] 4) - @error{} Args out of range: [1 2 3 4], 4 -@end group -@group -(elt [1 2 3 4] -1) - @error{} Args out of range: [1 2 3 4], -1 -@end group -@end example - -This function generalizes @code{aref} (@pxref{Array Functions}) and -@code{nth} (@pxref{Definition of nth}). -@end defun - -@defun copy-sequence sequence -@cindex copying sequences -This function returns a copy of @var{sequence}. The copy is the same -type of object as the original sequence, and it has the same elements -in the same order. - -Storing a new element into the copy does not affect the original -@var{sequence}, and vice versa. However, the elements of the new -sequence are not copies; they are identical (@code{eq}) to the elements -of the original. Therefore, changes made within these elements, as -found via the copied sequence, are also visible in the original -sequence. - -If the sequence is a string with text properties, the property list in -the copy is itself a copy, not shared with the original's property -list. However, the actual values of the properties are shared. -@xref{Text Properties}. - -This function does not work for dotted lists. Trying to copy a -circular list may cause an infinite loop. - -See also @code{append} in @ref{Building Lists}, @code{concat} in -@ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions}, -for other ways to copy sequences. - -@example -@group -(setq bar '(1 2)) - @result{} (1 2) -@end group -@group -(setq x (vector 'foo bar)) - @result{} [foo (1 2)] -@end group -@group -(setq y (copy-sequence x)) - @result{} [foo (1 2)] -@end group - -@group -(eq x y) - @result{} nil -@end group -@group -(equal x y) - @result{} t -@end group -@group -(eq (elt x 1) (elt y 1)) - @result{} t -@end group - -@group -;; @r{Replacing an element of one sequence.} -(aset x 0 'quux) -x @result{} [quux (1 2)] -y @result{} [foo (1 2)] -@end group - -@group -;; @r{Modifying the inside of a shared element.} -(setcar (aref x 1) 69) -x @result{} [quux (69 2)] -y @result{} [foo (69 2)] -@end group -@end example -@end defun - -@node Arrays -@section Arrays -@cindex array - - An @dfn{array} object has slots that hold a number of other Lisp -objects, called the elements of the array. Any element of an array -may be accessed in constant time. In contrast, the time to access an -element of a list is proportional to the position of that element in -the list. - - Emacs defines four types of array, all one-dimensional: -@dfn{strings} (@pxref{String Type}), @dfn{vectors} (@pxref{Vector -Type}), @dfn{bool-vectors} (@pxref{Bool-Vector Type}), and -@dfn{char-tables} (@pxref{Char-Table Type}). Vectors and char-tables -can hold elements of any type, but strings can only hold characters, -and bool-vectors can only hold @code{t} and @code{nil}. - - All four kinds of array share these characteristics: - -@itemize @bullet -@item -The first element of an array has index zero, the second element has -index 1, and so on. This is called @dfn{zero-origin} indexing. For -example, an array of four elements has indices 0, 1, 2, @w{and 3}. - -@item -The length of the array is fixed once you create it; you cannot -change the length of an existing array. - -@item -For purposes of evaluation, the array is a constant---i.e., -it evaluates to itself. - -@item -The elements of an array may be referenced or changed with the functions -@code{aref} and @code{aset}, respectively (@pxref{Array Functions}). -@end itemize - - When you create an array, other than a char-table, you must specify -its length. You cannot specify the length of a char-table, because that -is determined by the range of character codes. - - In principle, if you want an array of text characters, you could use -either a string or a vector. In practice, we always choose strings for -such applications, for four reasons: - -@itemize @bullet -@item -They occupy one-fourth the space of a vector of the same elements. - -@item -Strings are printed in a way that shows the contents more clearly -as text. - -@item -Strings can hold text properties. @xref{Text Properties}. - -@item -Many of the specialized editing and I/O facilities of Emacs accept only -strings. For example, you cannot insert a vector of characters into a -buffer the way you can insert a string. @xref{Strings and Characters}. -@end itemize - - By contrast, for an array of keyboard input characters (such as a key -sequence), a vector may be necessary, because many keyboard input -characters are outside the range that will fit in a string. @xref{Key -Sequence Input}. - -@node Array Functions -@section Functions that Operate on Arrays - - In this section, we describe the functions that accept all types of -arrays. - -@defun arrayp object -This function returns @code{t} if @var{object} is an array (i.e., a -vector, a string, a bool-vector or a char-table). - -@example -@group -(arrayp [a]) - @result{} t -(arrayp "asdf") - @result{} t -(arrayp (syntax-table)) ;; @r{A char-table.} - @result{} t -@end group -@end example -@end defun - -@defun aref array index -@cindex array elements -This function returns the @var{index}th element of @var{array}. The -first element is at index zero. - -@example -@group -(setq primes [2 3 5 7 11 13]) - @result{} [2 3 5 7 11 13] -(aref primes 4) - @result{} 11 -@end group -@group -(aref "abcdefg" 1) - @result{} 98 ; @r{@samp{b} is @acronym{ASCII} code 98.} -@end group -@end example - -See also the function @code{elt}, in @ref{Sequence Functions}. -@end defun - -@defun aset array index object -This function sets the @var{index}th element of @var{array} to be -@var{object}. It returns @var{object}. - -@example -@group -(setq w [foo bar baz]) - @result{} [foo bar baz] -(aset w 0 'fu) - @result{} fu -w - @result{} [fu bar baz] -@end group - -@group -(setq x "asdfasfd") - @result{} "asdfasfd" -(aset x 3 ?Z) - @result{} 90 -x - @result{} "asdZasfd" -@end group -@end example - -If @var{array} is a string and @var{object} is not a character, a -@code{wrong-type-argument} error results. The function converts a -unibyte string to multibyte if necessary to insert a character. -@end defun - -@defun fillarray array object -This function fills the array @var{array} with @var{object}, so that -each element of @var{array} is @var{object}. It returns @var{array}. - -@example -@group -(setq a [a b c d e f g]) - @result{} [a b c d e f g] -(fillarray a 0) - @result{} [0 0 0 0 0 0 0] -a - @result{} [0 0 0 0 0 0 0] -@end group -@group -(setq s "When in the course") - @result{} "When in the course" -(fillarray s ?-) - @result{} "------------------" -@end group -@end example - -If @var{array} is a string and @var{object} is not a character, a -@code{wrong-type-argument} error results. -@end defun - -The general sequence functions @code{copy-sequence} and @code{length} -are often useful for objects known to be arrays. @xref{Sequence Functions}. - -@node Vectors -@section Vectors -@cindex vector (type) - - A @dfn{vector} is a general-purpose array whose elements can be any -Lisp objects. (By contrast, the elements of a string can only be -characters. @xref{Strings and Characters}.) Vectors are used in -Emacs for many purposes: as key sequences (@pxref{Key Sequences}), as -symbol-lookup tables (@pxref{Creating Symbols}), as part of the -representation of a byte-compiled function (@pxref{Byte Compilation}), -and more. - - Like other arrays, vectors use zero-origin indexing: the first -element has index 0. - - Vectors are printed with square brackets surrounding the elements. -Thus, a vector whose elements are the symbols @code{a}, @code{b} and -@code{a} is printed as @code{[a b a]}. You can write vectors in the -same way in Lisp input. - - A vector, like a string or a number, is considered a constant for -evaluation: the result of evaluating it is the same vector. This does -not evaluate or even examine the elements of the vector. -@xref{Self-Evaluating Forms}. - - Here are examples illustrating these principles: - -@example -@group -(setq avector [1 two '(three) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] -(eval avector) - @result{} [1 two (quote (three)) "four" [five]] -(eq avector (eval avector)) - @result{} t -@end group -@end example - -@node Vector Functions -@section Functions for Vectors - - Here are some functions that relate to vectors: - -@defun vectorp object -This function returns @code{t} if @var{object} is a vector. - -@example -@group -(vectorp [a]) - @result{} t -(vectorp "asdf") - @result{} nil -@end group -@end example -@end defun - -@defun vector &rest objects -This function creates and returns a vector whose elements are the -arguments, @var{objects}. - -@example -@group -(vector 'foo 23 [bar baz] "rats") - @result{} [foo 23 [bar baz] "rats"] -(vector) - @result{} [] -@end group -@end example -@end defun - -@defun make-vector length object -This function returns a new vector consisting of @var{length} elements, -each initialized to @var{object}. - -@example -@group -(setq sleepy (make-vector 9 'Z)) - @result{} [Z Z Z Z Z Z Z Z Z] -@end group -@end example -@end defun - -@defun vconcat &rest sequences -@cindex copying vectors -This function returns a new vector containing all the elements of -@var{sequences}. The arguments @var{sequences} may be true lists, -vectors, strings or bool-vectors. If no @var{sequences} are given, an -empty vector is returned. - -The value is a newly constructed vector that is not @code{eq} to any -existing vector. - -@example -@group -(setq a (vconcat '(A B C) '(D E F))) - @result{} [A B C D E F] -(eq a (vconcat a)) - @result{} nil -@end group -@group -(vconcat) - @result{} [] -(vconcat [A B C] "aa" '(foo (6 7))) - @result{} [A B C 97 97 foo (6 7)] -@end group -@end example - -The @code{vconcat} function also allows byte-code function objects as -arguments. This is a special feature to make it easy to access the entire -contents of a byte-code function object. @xref{Byte-Code Objects}. - -For other concatenation functions, see @code{mapconcat} in @ref{Mapping -Functions}, @code{concat} in @ref{Creating Strings}, and @code{append} -in @ref{Building Lists}. -@end defun - - The @code{append} function also provides a way to convert a vector into a -list with the same elements: - -@example -@group -(setq avector [1 two (quote (three)) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] -(append avector nil) - @result{} (1 two (quote (three)) "four" [five]) -@end group -@end example - -@node Char-Tables -@section Char-Tables -@cindex char-tables -@cindex extra slots of char-table - - A char-table is much like a vector, except that it is indexed by -character codes. Any valid character code, without modifiers, can be -used as an index in a char-table. You can access a char-table's -elements with @code{aref} and @code{aset}, as with any array. In -addition, a char-table can have @dfn{extra slots} to hold additional -data not associated with particular character codes. Like vectors, -char-tables are constants when evaluated, and can hold elements of any -type. - -@cindex subtype of char-table - Each char-table has a @dfn{subtype}, a symbol, which serves two -purposes: - -@itemize @bullet -@item -The subtype provides an easy way to tell what the char-table is for. -For instance, display tables are char-tables with @code{display-table} -as the subtype, and syntax tables are char-tables with -@code{syntax-table} as the subtype. The subtype can be queried using -the function @code{char-table-subtype}, described below. - -@item -The subtype controls the number of @dfn{extra slots} in the -char-table. This number is specified by the subtype's -@code{char-table-extra-slots} symbol property, which should be an -integer between 0 and 10. If the subtype has no such symbol property, -the char-table has no extra slots. @xref{Property Lists}, for -information about symbol properties. -@end itemize - -@cindex parent of char-table - A char-table can have a @dfn{parent}, which is another char-table. If -it does, then whenever the char-table specifies @code{nil} for a -particular character @var{c}, it inherits the value specified in the -parent. In other words, @code{(aref @var{char-table} @var{c})} returns -the value from the parent of @var{char-table} if @var{char-table} itself -specifies @code{nil}. - -@cindex default value of char-table - A char-table can also have a @dfn{default value}. If so, then -@code{(aref @var{char-table} @var{c})} returns the default value -whenever the char-table does not specify any other non-@code{nil} value. - -@defun make-char-table subtype &optional init -Return a newly-created char-table, with subtype @var{subtype} (a -symbol). Each element is initialized to @var{init}, which defaults to -@code{nil}. You cannot alter the subtype of a char-table after the -char-table is created. - -There is no argument to specify the length of the char-table, because -all char-tables have room for any valid character code as an index. - -If @var{subtype} has the @code{char-table-extra-slots} symbol -property, that specifies the number of extra slots in the char-table. -This should be an integer between 0 and 10; otherwise, -@code{make-char-table} raises an error. If @var{subtype} has no -@code{char-table-extra-slots} symbol property (@pxref{Property -Lists}), the char-table has no extra slots. -@end defun - -@defun char-table-p object -This function returns @code{t} if @var{object} is a char-table, and -@code{nil} otherwise. -@end defun - -@defun char-table-subtype char-table -This function returns the subtype symbol of @var{char-table}. -@end defun - -There is no special function to access default values in a char-table. -To do that, use @code{char-table-range} (see below). - -@defun char-table-parent char-table -This function returns the parent of @var{char-table}. The parent is -always either @code{nil} or another char-table. -@end defun - -@defun set-char-table-parent char-table new-parent -This function sets the parent of @var{char-table} to @var{new-parent}. -@end defun - -@defun char-table-extra-slot char-table n -This function returns the contents of extra slot @var{n} of -@var{char-table}. The number of extra slots in a char-table is -determined by its subtype. -@end defun - -@defun set-char-table-extra-slot char-table n value -This function stores @var{value} in extra slot @var{n} of -@var{char-table}. -@end defun - - A char-table can specify an element value for a single character code; -it can also specify a value for an entire character set. - -@defun char-table-range char-table range -This returns the value specified in @var{char-table} for a range of -characters @var{range}. Here are the possibilities for @var{range}: - -@table @asis -@item @code{nil} -Refers to the default value. - -@item @var{char} -Refers to the element for character @var{char} -(supposing @var{char} is a valid character code). - -@item @code{(@var{from} . @var{to})} -A cons cell refers to all the characters in the inclusive range -@samp{[@var{from}..@var{to}]}. -@end table -@end defun - -@defun set-char-table-range char-table range value -This function sets the value in @var{char-table} for a range of -characters @var{range}. Here are the possibilities for @var{range}: - -@table @asis -@item @code{nil} -Refers to the default value. - -@item @code{t} -Refers to the whole range of character codes. - -@item @var{char} -Refers to the element for character @var{char} -(supposing @var{char} is a valid character code). - -@item @code{(@var{from} . @var{to})} -A cons cell refers to all the characters in the inclusive range -@samp{[@var{from}..@var{to}]}. -@end table -@end defun - -@defun map-char-table function char-table -This function calls its argument @var{function} for each element of -@var{char-table} that has a non-@code{nil} value. The call to -@var{function} is with two arguments, a key and a value. The key -is a possible @var{range} argument for @code{char-table-range}---either -a valid character or a cons cell @code{(@var{from} . @var{to})}, -specifying a range of characters that share the same value. The value is -what @code{(char-table-range @var{char-table} @var{key})} returns. - -Overall, the key-value pairs passed to @var{function} describe all the -values stored in @var{char-table}. - -The return value is always @code{nil}; to make calls to -@code{map-char-table} useful, @var{function} should have side effects. -For example, here is how to examine the elements of the syntax table: - -@example -(let (accumulator) - (map-char-table - #'(lambda (key value) - (setq accumulator - (cons (list - (if (consp key) - (list (car key) (cdr key)) - key) - value) - accumulator))) - (syntax-table)) - accumulator) -@result{} -(((2597602 4194303) (2)) ((2597523 2597601) (3)) - ... (65379 (5 . 65378)) (65378 (4 . 65379)) (65377 (1)) - ... (12 (0)) (11 (3)) (10 (12)) (9 (0)) ((0 8) (3))) -@end example -@end defun - -@node Bool-Vectors -@section Bool-vectors -@cindex Bool-vectors - - A bool-vector is much like a vector, except that it stores only the -values @code{t} and @code{nil}. If you try to store any non-@code{nil} -value into an element of the bool-vector, the effect is to store -@code{t} there. As with all arrays, bool-vector indices start from 0, -and the length cannot be changed once the bool-vector is created. -Bool-vectors are constants when evaluated. - - There are two special functions for working with bool-vectors; aside -from that, you manipulate them with same functions used for other kinds -of arrays. - -@defun make-bool-vector length initial -Return a new bool-vector of @var{length} elements, -each one initialized to @var{initial}. -@end defun - -@defun bool-vector-p object -This returns @code{t} if @var{object} is a bool-vector, -and @code{nil} otherwise. -@end defun - - Here is an example of creating, examining, and updating a -bool-vector. Note that the printed form represents up to 8 boolean -values as a single character. - -@example -(setq bv (make-bool-vector 5 t)) - @result{} #&5"^_" -(aref bv 1) - @result{} t -(aset bv 3 nil) - @result{} nil -bv - @result{} #&5"^W" -@end example - -@noindent -These results make sense because the binary codes for control-_ and -control-W are 11111 and 10111, respectively. - -@node Rings -@section Managing a Fixed-Size Ring of Objects - -@cindex ring data structure - A @dfn{ring} is a fixed-size data structure that supports insertion, -deletion, rotation, and modulo-indexed reference and traversal. An -efficient ring data structure is implemented by the @code{ring} -package. It provides the functions listed in this section. - - Note that several ``rings'' in Emacs, like the kill ring and the -mark ring, are actually implemented as simple lists, @emph{not} using -the @code{ring} package; thus the following functions won't work on -them. - -@defun make-ring size -This returns a new ring capable of holding @var{size} objects. -@var{size} should be an integer. -@end defun - -@defun ring-p object -This returns @code{t} if @var{object} is a ring, @code{nil} otherwise. -@end defun - -@defun ring-size ring -This returns the maximum capacity of the @var{ring}. -@end defun - -@defun ring-length ring -This returns the number of objects that @var{ring} currently contains. -The value will never exceed that returned by @code{ring-size}. -@end defun - -@defun ring-elements ring -This returns a list of the objects in @var{ring}, in order, newest first. -@end defun - -@defun ring-copy ring -This returns a new ring which is a copy of @var{ring}. -The new ring contains the same (@code{eq}) objects as @var{ring}. -@end defun - -@defun ring-empty-p ring -This returns @code{t} if @var{ring} is empty, @code{nil} otherwise. -@end defun - - The newest element in the ring always has index 0. Higher indices -correspond to older elements. Indices are computed modulo the ring -length. Index @minus{}1 corresponds to the oldest element, @minus{}2 -to the next-oldest, and so forth. - -@defun ring-ref ring index -This returns the object in @var{ring} found at index @var{index}. -@var{index} may be negative or greater than the ring length. If -@var{ring} is empty, @code{ring-ref} signals an error. -@end defun - -@defun ring-insert ring object -This inserts @var{object} into @var{ring}, making it the newest -element, and returns @var{object}. - -If the ring is full, insertion removes the oldest element to -make room for the new element. -@end defun - -@defun ring-remove ring &optional index -Remove an object from @var{ring}, and return that object. The -argument @var{index} specifies which item to remove; if it is -@code{nil}, that means to remove the oldest item. If @var{ring} is -empty, @code{ring-remove} signals an error. -@end defun - -@defun ring-insert-at-beginning ring object -This inserts @var{object} into @var{ring}, treating it as the oldest -element. The return value is not significant. - -If the ring is full, this function removes the newest element to make -room for the inserted element. -@end defun - -@cindex fifo data structure - If you are careful not to exceed the ring size, you can -use the ring as a first-in-first-out queue. For example: - -@lisp -(let ((fifo (make-ring 5))) - (mapc (lambda (obj) (ring-insert fifo obj)) - '(0 one "two")) - (list (ring-remove fifo) t - (ring-remove fifo) t - (ring-remove fifo))) - @result{} (0 t one t "two") -@end lisp diff --git a/doc/lispref/spellfile b/doc/lispref/spellfile deleted file mode 100644 index 18fb633acfd..00000000000 --- a/doc/lispref/spellfile +++ /dev/null @@ -1,731 +0,0 @@ -ARPA -Abbrev -Acknowledgements -Alan -Arnold -Autoloading -BAppend -Backquote -Beeping -Beverly -Boyes -Brian -CL -CSWKg -Carl -Carroll -Chris -Cleanups -DEC -DStandard -Dan -Dired's -Disassembly -Duff -EMAC -EMACSLOADPATH -Eckelkamp -Edward -Eirik -Emacses -Eric -Erlebacher -Fcar -Fcdr -Fcons -Fcoordinates -Feval -Frazzle -Frederick -Fri -Gardiner -Gentlemen -HAL -HATTED -HS -HU -Hanchrow -Hartzell -Hess -Hewlett -IBM -ISBN -Impl -Interning -Ithought -J's -Jacobson -Jak -Joe -Jones -Jr -Jul -Keymaps -Kimmo -Kirman -Knighten -Korz -Krawitz -LTsHm -LaLiberte -LaTeX -Lammens -Local' -MAC -MONIES -MSS -Maclisp -Magill -Marick -Matthew -Minibuf -Misc -Miscellany -Mocklisp -Montanaro -Myers -NFS -Nathan -Nope -OS -OSITIONS -Oct -Ovwrt -PURESIZE -Packard -Qlistp -Qnil -RMAIL -Raul -Resizing -Robbins -Rockwell -SCO -SIGCONT -SIGHUP -SIGINT -SIGKILL -SIGQUIT -SIGTSTP -SLOAD -Scoordinates -Set' -Setcar -Setcdr -Shinichirou -Snarf -Sor -SourceFile -Stops' -Subprocess -Sugou -Sunview -Suominen -T's -TCP -ThXs -Tharp -Thu -Trost -UCB -UNEVALLED -UNGCPRO -UniPlus -UniSoft's -VMS -Vip -Void' -Warren -Welty -Wethought -Wilding -Worley -Wright -XDVI -XFASTINT -XINT -XWINDOW -Xs -Yo -Zuhn -aB -aa -aaa -abbrevname -abbrevs -abc -abcdefg -abcxyz -abd -above' -abracadabra -address' -after' -alist -alists -anchored' -and' -ar -aref -arg'th -argdecl -arith -arrayp -arrow' -asa -asdZasfd -asdf -asdfasfd -aset -assoc -assq -at' -aug -autoload -automatic' -automatically' -avector -bBuffer -bFrobnicate -ba -back' -bananana -barfoo -barx -bballs -before' -beforep -bfoo -bil -binding's -bish -bobp -bolp -bottommost -boundp -brief' -buf -buffer' -bufferp -buttercup -ca -caaaar -caaar -caddaar -cadr -callable -cbreak -ce -cell' -cells' -cf -chaprm -character' -childp -chistory -ck -column' -commandp -concat -cond -conses -consing -consp -constant' -contains' -continuable -convert' -copyleft -correct' -counterintuitive -cr -creatable -customize -deactivate -deactivated -deassigns -decrement' -deffnx -definition' -defmacro -defsubr -deletable -deletion' -delq -depiction -deselecting -destructive' -destructively' -diffs -ding -directory' -dired -dirname -disassembler -dland -docfile -docstring -doesnt -dont -down' -downcasing -downloadable -dribble -dup -ef -efg -electric' -elided -elt -enablement -endkeyfun -endrecfun -environment' -eobp -eof -eol -eolp -eq -eqlsign -erminal -erste -etags -eval -evalled -evals -evaluate' -excess' -exec -exitcode -expression' -extra' -fails' -fascist -fboundp -featurep -ff -fg -fi -file' -filespec -filesystems -fillarray -firstchar -firstonly -fixedcase -fixit -fixup -floatp -fmakunbound -fns -fo -fol -folded' -following' -fooba -foobaz -foox -for' -formfeed -forms' -forw -found' -frob -from' -front' -fset -fstab -ftp -fu -garbles -gc -gcpro -gd -getenv -getprv -gid -gnuemacs -gp -grep -gtr -halves' -hand' -hashes' -hd -hexadecimal -hf -hfil -hookvar -horsechestnut -hostname -hpux -hscroll -ibmapa -ick -id -idiom -ii -indrm -inode -input' -inputinput -inserting' -integerp -intermixed -ints -irreversibly -jum -keymapp -kill' -killed' -killp -kludge -kolstad -language' -lastchar -lcl -ledit -leif -lessp -level' -lewis -library' -link' -lisplib -listexp -loadable -loadst -loadup -logand -logior -lognot -logxor -long' -loop's -lru -lrwxrwxrwx -ls -lsh -m's -macroexpand -makunbound -malloc -mapatoms -mapconcat -mapvar -mark' -marker's -markerp -mathsurround -medit -memq -mh -mim -mini -minibuffer's -minibuffers -misalignment -misnamed -mode's -modename -modes' -mods -modtime -mqueue -msg -multicharacter -myfile -nCount -nXExpression -na -name's -natnump -nb -nbBuffer -nconc -newdef -newelt -newname -nextrecfun -nfsusr -ninett -nlines -nlinks -nlistp -noconfirm -nodigits -noerror -noforce -nomessage -nominees -nomsg -nonblank -nonconstant -nondestructive -nondirectory -nonidentical -noninteractive -noninteractively -nonletter -nonletters -nonlocally -nonoverlapping -nonprinting -nonselected -nonsequentially -nonvoid -nonwarranty -nonwritable -noop -noprint -norecord -normal' -noselect -nosuffix -nots -noundo -nr -nreverse -ns -nsRename -nth -nthcdr -num -number' -numberp -nums -obarray -obarrays -object' -oldbuf -olddef -oldname -oo -oops -op -or' -otl -out' -over' -overful -overfullrule -overstrike -overstriking -overstruck -p' -paren -part' -passwd -pe -ped -perverse -pid -plist -pnt -pointer' -pointm -pos -preallocate -preload -prepend -prepended -prepends -pretty' -prin -princ -print' -printenv -printer' -proc -process' -processp -programmer' -prolog -protect' -ps -psf -psychotherapy -pty -purecopy -qu -quux -rassq -reader' -readin -rebind -rec -rechecking -recursively' -recycler' -redo -redrawing -redraws -redump -reenabled -reexposed -reg -region' -reindent -reindents -reinitialization -reinitialize -reinitialized -reinstall -reinstalled -resize -resized -resizes -reversibly -reworded -rhetorical -right' -ring' -risky -rmailedit -rms -rplaca -rplacd -rtu -runnable -rw -rwxrwxrwx -sDescribe -sans -se -searching' -section' -seed' -sequence' -sequencep -setp -setplist -setprv -settable -setuid -sexp -sexps -shape' -shell's -sideline -special' -specpdl -st -stanford -startkeyfun -str -stringp -stty -subcategories -subcommands -subexp -subform -subforms -subjob -submap -subprocesses -subr -subr' -subroutine' -subrp -subrs -subwindows -sugar' -suid -supersession -suspension' -symbolp -symlink -syms -syntactic -tabname -temacs -temporarily' -tempvar -tenths -termcap -termcaps -terminfo -termscript -termtype -terpri -text' -textrm -textsl -texttt -than' -the' -tildes -time's -to' -towards -transportable -txt -types' -uid -unbind -unbinding -unbinds -unchanged' -unclutters -undefine -undefines -underfull -undo's -unevaluated' -unexec -unexpand -unhesitatingly -uninterned -unisoft -unpaired -unread -unreadable -unreading -unsaved -untyped -ununderline -up' -uptime -usecount -used' -user' -userlock -usg -val -varbind -varname -varref -vars -varset -vb -vconcat -vectorp -vfil -vi -vn -voidness -vrs -vt -window' -windowing -windowp -wrapped' -xSpecify -xcoord -xcssun -xemacs -xenix -xf -xfirst -xoff -xon -xx -xxxxx -xxxxxxxxx -xy -xyz -ycoord -yes' -zA -zap -zerop diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi deleted file mode 100644 index e485d8c4d14..00000000000 --- a/doc/lispref/streams.texi +++ /dev/null @@ -1,836 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/streams -@node Read and Print, Minibuffers, Debugging, Top -@comment node-name, next, previous, up -@chapter Reading and Printing Lisp Objects - - @dfn{Printing} and @dfn{reading} are the operations of converting Lisp -objects to textual form and vice versa. They use the printed -representations and read syntax described in @ref{Lisp Data Types}. - - This chapter describes the Lisp functions for reading and printing. -It also describes @dfn{streams}, which specify where to get the text (if -reading) or where to put it (if printing). - -@menu -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as output streams. -* Output Functions:: Functions to print Lisp objects as text. -* Output Variables:: Variables that control what the printing functions do. -@end menu - -@node Streams Intro -@section Introduction to Reading and Printing -@cindex Lisp reader -@cindex printing -@cindex reading - - @dfn{Reading} a Lisp object means parsing a Lisp expression in textual -form and producing a corresponding Lisp object. This is how Lisp -programs get into Lisp from files of Lisp code. We call the text the -@dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)} -is the read syntax for a cons cell whose @sc{car} is @code{a} and whose -@sc{cdr} is the number 5. - - @dfn{Printing} a Lisp object means producing text that represents that -object---converting the object to its @dfn{printed representation} -(@pxref{Printed Representation}). Printing the cons cell described -above produces the text @samp{(a .@: 5)}. - - Reading and printing are more or less inverse operations: printing the -object that results from reading a given piece of text often produces -the same text, and reading the text that results from printing an object -usually produces a similar-looking object. For example, printing the -symbol @code{foo} produces the text @samp{foo}, and reading that text -returns the symbol @code{foo}. Printing a list whose elements are -@code{a} and @code{b} produces the text @samp{(a b)}, and reading that -text produces a list (but not the same list) with elements @code{a} -and @code{b}. - - However, these two operations are not precisely inverse to each other. -There are three kinds of exceptions: - -@itemize @bullet -@item -Printing can produce text that cannot be read. For example, buffers, -windows, frames, subprocesses and markers print as text that starts -with @samp{#}; if you try to read this text, you get an error. There is -no way to read those data types. - -@item -One object can have multiple textual representations. For example, -@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and -@samp{(a .@: (b))} represent the same list. Reading will accept any of -the alternatives, but printing must choose one of them. - -@item -Comments can appear at certain points in the middle of an object's -read sequence without affecting the result of reading it. -@end itemize - -@node Input Streams -@section Input Streams -@cindex stream (for reading) -@cindex input stream - - Most of the Lisp functions for reading text take an @dfn{input stream} -as an argument. The input stream specifies where or how to get the -characters of the text to be read. Here are the possible types of input -stream: - -@table @asis -@item @var{buffer} -@cindex buffer input stream -The input characters are read from @var{buffer}, starting with the -character directly after point. Point advances as characters are read. - -@item @var{marker} -@cindex marker input stream -The input characters are read from the buffer that @var{marker} is in, -starting with the character directly after the marker. The marker -position advances as characters are read. The value of point in the -buffer has no effect when the stream is a marker. - -@item @var{string} -@cindex string input stream -The input characters are taken from @var{string}, starting at the first -character in the string and using as many characters as required. - -@item @var{function} -@cindex function input stream -The input characters are generated by @var{function}, which must support -two kinds of calls: - -@itemize @bullet -@item -When it is called with no arguments, it should return the next character. - -@item -When it is called with one argument (always a character), @var{function} -should save the argument and arrange to return it on the next call. -This is called @dfn{unreading} the character; it happens when the Lisp -reader reads one character too many and wants to ``put it back where it -came from''. In this case, it makes no difference what value -@var{function} returns. -@end itemize - -@item @code{t} -@cindex @code{t} input stream -@code{t} used as a stream means that the input is read from the -minibuffer. In fact, the minibuffer is invoked once and the text -given by the user is made into a string that is then used as the -input stream. If Emacs is running in batch mode, standard input is used -instead of the minibuffer. For example, -@example -(message "%s" (read t)) -@end example -will read a Lisp expression from standard input and print the result -to standard output. - -@item @code{nil} -@cindex @code{nil} input stream -@code{nil} supplied as an input stream means to use the value of -@code{standard-input} instead; that value is the @dfn{default input -stream}, and must be a non-@code{nil} input stream. - -@item @var{symbol} -A symbol as input stream is equivalent to the symbol's function -definition (if any). -@end table - - Here is an example of reading from a stream that is a buffer, showing -where point is located before and after: - -@example -@group ----------- Buffer: foo ---------- -This@point{} is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(read (get-buffer "foo")) - @result{} is -@end group -@group -(read (get-buffer "foo")) - @result{} the -@end group - -@group ----------- Buffer: foo ---------- -This is the@point{} contents of foo. ----------- Buffer: foo ---------- -@end group -@end example - -@noindent -Note that the first read skips a space. Reading skips any amount of -whitespace preceding the significant text. - - Here is an example of reading from a stream that is a marker, -initially positioned at the beginning of the buffer shown. The value -read is the symbol @code{This}. - -@example -@group - ----------- Buffer: foo ---------- -This is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(setq m (set-marker (make-marker) 1 (get-buffer "foo"))) - @result{} # -@end group -@group -(read m) - @result{} This -@end group -@group -m - @result{} # ;; @r{Before the first space.} -@end group -@end example - - Here we read from the contents of a string: - -@example -@group -(read "(When in) the course") - @result{} (When in) -@end group -@end example - - The following example reads from the minibuffer. The -prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt -used when you read from the stream @code{t}.) The user's input is shown -following the prompt. - -@example -@group -(read t) - @result{} 23 ----------- Buffer: Minibuffer ---------- -Lisp expression: @kbd{23 @key{RET}} ----------- Buffer: Minibuffer ---------- -@end group -@end example - - Finally, here is an example of a stream that is a function, named -@code{useless-stream}. Before we use the stream, we initialize the -variable @code{useless-list} to a list of characters. Then each call to -the function @code{useless-stream} obtains the next character in the list -or unreads a character by adding it to the front of the list. - -@example -@group -(setq useless-list (append "XY()" nil)) - @result{} (88 89 40 41) -@end group - -@group -(defun useless-stream (&optional unread) - (if unread - (setq useless-list (cons unread useless-list)) - (prog1 (car useless-list) - (setq useless-list (cdr useless-list))))) - @result{} useless-stream -@end group -@end example - -@noindent -Now we read using the stream thus constructed: - -@example -@group -(read 'useless-stream) - @result{} XY -@end group - -@group -useless-list - @result{} (40 41) -@end group -@end example - -@noindent -Note that the open and close parentheses remain in the list. The Lisp -reader encountered the open parenthesis, decided that it ended the -input, and unread it. Another attempt to read from the stream at this -point would read @samp{()} and return @code{nil}. - -@node Input Functions -@section Input Functions - - This section describes the Lisp functions and variables that pertain -to reading. - - In the functions below, @var{stream} stands for an input stream (see -the previous section). If @var{stream} is @code{nil} or omitted, it -defaults to the value of @code{standard-input}. - -@kindex end-of-file - An @code{end-of-file} error is signaled if reading encounters an -unterminated list, vector, or string. - -@defun read &optional stream -This function reads one textual Lisp expression from @var{stream}, -returning it as a Lisp object. This is the basic Lisp input function. -@end defun - -@defun read-from-string string &optional start end -@cindex string to object -This function reads the first textual Lisp expression from the text in -@var{string}. It returns a cons cell whose @sc{car} is that expression, -and whose @sc{cdr} is an integer giving the position of the next -remaining character in the string (i.e., the first one not read). - -If @var{start} is supplied, then reading begins at index @var{start} in -the string (where the first character is at index 0). If you specify -@var{end}, then reading is forced to stop just before that index, as if -the rest of the string were not there. - -For example: - -@example -@group -(read-from-string "(setq x 55) (setq y 5)") - @result{} ((setq x 55) . 11) -@end group -@group -(read-from-string "\"A short string\"") - @result{} ("A short string" . 16) -@end group - -@group -;; @r{Read starting at the first character.} -(read-from-string "(list 112)" 0) - @result{} ((list 112) . 10) -@end group -@group -;; @r{Read starting at the second character.} -(read-from-string "(list 112)" 1) - @result{} (list . 5) -@end group -@group -;; @r{Read starting at the seventh character,} -;; @r{and stopping at the ninth.} -(read-from-string "(list 112)" 6 8) - @result{} (11 . 8) -@end group -@end example -@end defun - -@defvar standard-input -This variable holds the default input stream---the stream that -@code{read} uses when the @var{stream} argument is @code{nil}. -The default is @code{t}, meaning use the minibuffer. -@end defvar - -@defvar read-circle -If non-@code{nil}, this variable enables the reading of circular and -shared structures. @xref{Circular Objects}. Its default value is -@code{t}. -@end defvar - -@node Output Streams -@section Output Streams -@cindex stream (for printing) -@cindex output stream - - An output stream specifies what to do with the characters produced -by printing. Most print functions accept an output stream as an -optional argument. Here are the possible types of output stream: - -@table @asis -@item @var{buffer} -@cindex buffer output stream -The output characters are inserted into @var{buffer} at point. -Point advances as characters are inserted. - -@item @var{marker} -@cindex marker output stream -The output characters are inserted into the buffer that @var{marker} -points into, at the marker position. The marker position advances as -characters are inserted. The value of point in the buffer has no effect -on printing when the stream is a marker, and this kind of printing -does not move point (except that if the marker points at or before the -position of point, point advances with the surrounding text, as -usual). - -@item @var{function} -@cindex function output stream -The output characters are passed to @var{function}, which is responsible -for storing them away. It is called with a single character as -argument, as many times as there are characters to be output, and -is responsible for storing the characters wherever you want to put them. - -@item @code{t} -@cindex @code{t} output stream -The output characters are displayed in the echo area. - -@item @code{nil} -@cindex @code{nil} output stream -@code{nil} specified as an output stream means to use the value of -@code{standard-output} instead; that value is the @dfn{default output -stream}, and must not be @code{nil}. - -@item @var{symbol} -A symbol as output stream is equivalent to the symbol's function -definition (if any). -@end table - - Many of the valid output streams are also valid as input streams. The -difference between input and output streams is therefore more a matter -of how you use a Lisp object, than of different types of object. - - Here is an example of a buffer used as an output stream. Point is -initially located as shown immediately before the @samp{h} in -@samp{the}. At the end, point is located directly before that same -@samp{h}. - -@cindex print example -@example -@group ----------- Buffer: foo ---------- -This is t@point{}he contents of foo. ----------- Buffer: foo ---------- -@end group - -(print "This is the output" (get-buffer "foo")) - @result{} "This is the output" - -@group ----------- Buffer: foo ---------- -This is t -"This is the output" -@point{}he contents of foo. ----------- Buffer: foo ---------- -@end group -@end example - - Now we show a use of a marker as an output stream. Initially, the -marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in -the word @samp{the}. At the end, the marker has advanced over the -inserted text so that it remains positioned before the same @samp{h}. -Note that the location of point, shown in the usual fashion, has no -effect. - -@example -@group ----------- Buffer: foo ---------- -This is the @point{}output ----------- Buffer: foo ---------- -@end group - -@group -(setq m (copy-marker 10)) - @result{} # -@end group - -@group -(print "More output for foo." m) - @result{} "More output for foo." -@end group - -@group ----------- Buffer: foo ---------- -This is t -"More output for foo." -he @point{}output ----------- Buffer: foo ---------- -@end group - -@group -m - @result{} # -@end group -@end example - - The following example shows output to the echo area: - -@example -@group -(print "Echo Area output" t) - @result{} "Echo Area output" ----------- Echo Area ---------- -"Echo Area output" ----------- Echo Area ---------- -@end group -@end example - - Finally, we show the use of a function as an output stream. The -function @code{eat-output} takes each character that it is given and -conses it onto the front of the list @code{last-output} (@pxref{Building -Lists}). At the end, the list contains all the characters output, but -in reverse order. - -@example -@group -(setq last-output nil) - @result{} nil -@end group - -@group -(defun eat-output (c) - (setq last-output (cons c last-output))) - @result{} eat-output -@end group - -@group -(print "This is the output" 'eat-output) - @result{} "This is the output" -@end group - -@group -last-output - @result{} (10 34 116 117 112 116 117 111 32 101 104 - 116 32 115 105 32 115 105 104 84 34 10) -@end group -@end example - -@noindent -Now we can put the output in the proper order by reversing the list: - -@example -@group -(concat (nreverse last-output)) - @result{} " -\"This is the output\" -" -@end group -@end example - -@noindent -Calling @code{concat} converts the list to a string so you can see its -contents more clearly. - -@node Output Functions -@section Output Functions - - This section describes the Lisp functions for printing Lisp -objects---converting objects into their printed representation. - -@cindex @samp{"} in printing -@cindex @samp{\} in printing -@cindex quoting characters in printing -@cindex escape characters in printing - Some of the Emacs printing functions add quoting characters to the -output when necessary so that it can be read properly. The quoting -characters used are @samp{"} and @samp{\}; they distinguish strings from -symbols, and prevent punctuation characters in strings and symbols from -being taken as delimiters when reading. @xref{Printed Representation}, -for full details. You specify quoting or no quoting by the choice of -printing function. - - If the text is to be read back into Lisp, then you should print with -quoting characters to avoid ambiguity. Likewise, if the purpose is to -describe a Lisp object clearly for a Lisp programmer. However, if the -purpose of the output is to look nice for humans, then it is usually -better to print without quoting. - - Lisp objects can refer to themselves. Printing a self-referential -object in the normal way would require an infinite amount of text, and -the attempt could cause infinite recursion. Emacs detects such -recursion and prints @samp{#@var{level}} instead of recursively printing -an object already being printed. For example, here @samp{#0} indicates -a recursive reference to the object at level 0 of the current print -operation: - -@example -(setq foo (list nil)) - @result{} (nil) -(setcar foo foo) - @result{} (#0) -@end example - - In the functions below, @var{stream} stands for an output stream. -(See the previous section for a description of output streams.) If -@var{stream} is @code{nil} or omitted, it defaults to the value of -@code{standard-output}. - -@defun print object &optional stream -@cindex Lisp printer -The @code{print} function is a convenient way of printing. It outputs -the printed representation of @var{object} to @var{stream}, printing in -addition one newline before @var{object} and another after it. Quoting -characters are used. @code{print} returns @var{object}. For example: - -@example -@group -(progn (print 'The\ cat\ in) - (print "the hat") - (print " came back")) - @print{} - @print{} The\ cat\ in - @print{} - @print{} "the hat" - @print{} - @print{} " came back" - @result{} " came back" -@end group -@end example -@end defun - -@defun prin1 object &optional stream -This function outputs the printed representation of @var{object} to -@var{stream}. It does not print newlines to separate output as -@code{print} does, but it does use quoting characters just like -@code{print}. It returns @var{object}. - -@example -@group -(progn (prin1 'The\ cat\ in) - (prin1 "the hat") - (prin1 " came back")) - @print{} The\ cat\ in"the hat"" came back" - @result{} " came back" -@end group -@end example -@end defun - -@defun princ object &optional stream -This function outputs the printed representation of @var{object} to -@var{stream}. It returns @var{object}. - -This function is intended to produce output that is readable by people, -not by @code{read}, so it doesn't insert quoting characters and doesn't -put double-quotes around the contents of strings. It does not add any -spacing between calls. - -@example -@group -(progn - (princ 'The\ cat) - (princ " in the \"hat\"")) - @print{} The cat in the "hat" - @result{} " in the \"hat\"" -@end group -@end example -@end defun - -@defun terpri &optional stream -@cindex newline in print -This function outputs a newline to @var{stream}. The name stands -for ``terminate print''. -@end defun - -@defun write-char character &optional stream -This function outputs @var{character} to @var{stream}. It returns -@var{character}. -@end defun - -@defun prin1-to-string object &optional noescape -@cindex object to string -This function returns a string containing the text that @code{prin1} -would have printed for the same argument. - -@example -@group -(prin1-to-string 'foo) - @result{} "foo" -@end group -@group -(prin1-to-string (mark-marker)) - @result{} "#" -@end group -@end example - -If @var{noescape} is non-@code{nil}, that inhibits use of quoting -characters in the output. (This argument is supported in Emacs versions -19 and later.) - -@example -@group -(prin1-to-string "foo") - @result{} "\"foo\"" -@end group -@group -(prin1-to-string "foo" t) - @result{} "foo" -@end group -@end example - -See @code{format}, in @ref{Formatting Strings}, for other ways to obtain -the printed representation of a Lisp object as a string. -@end defun - -@defmac with-output-to-string body@dots{} -This macro executes the @var{body} forms with @code{standard-output} set -up to feed output into a string. Then it returns that string. - -For example, if the current buffer name is @samp{foo}, - -@example -(with-output-to-string - (princ "The buffer is ") - (princ (buffer-name))) -@end example - -@noindent -returns @code{"The buffer is foo"}. -@end defmac - -@defun pp object &optional stream -This function outputs @var{object} to @var{stream}, just like -@code{prin1}, but does it in a more ``pretty'' way. That is, it'll -indent and fill the object to make it more readable for humans. -@end defun - -@node Output Variables -@section Variables Affecting Output -@cindex output-controlling variables - -@defvar standard-output -The value of this variable is the default output stream---the stream -that print functions use when the @var{stream} argument is @code{nil}. -The default is @code{t}, meaning display in the echo area. -@end defvar - -@defvar print-quoted -If this is non-@code{nil}, that means to print quoted forms using -abbreviated reader syntax, e.g.@: @code{(quote foo)} prints as -@code{'foo}, and @code{(function foo)} as @code{#'foo}. -@end defvar - -@defvar print-escape-newlines -@cindex @samp{\n} in print -@cindex escape characters -If this variable is non-@code{nil}, then newline characters in strings -are printed as @samp{\n} and formfeeds are printed as @samp{\f}. -Normally these characters are printed as actual newlines and formfeeds. - -This variable affects the print functions @code{prin1} and @code{print} -that print with quoting. It does not affect @code{princ}. Here is an -example using @code{prin1}: - -@example -@group -(prin1 "a\nb") - @print{} "a - @print{} b" - @result{} "a -b" -@end group - -@group -(let ((print-escape-newlines t)) - (prin1 "a\nb")) - @print{} "a\nb" - @result{} "a -b" -@end group -@end example - -@noindent -In the second expression, the local binding of -@code{print-escape-newlines} is in effect during the call to -@code{prin1}, but not during the printing of the result. -@end defvar - -@defvar print-escape-nonascii -If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII} -characters in strings are unconditionally printed as backslash sequences -by the print functions @code{prin1} and @code{print} that print with -quoting. - -Those functions also use backslash sequences for unibyte non-@acronym{ASCII} -characters, regardless of the value of this variable, when the output -stream is a multibyte buffer or a marker pointing into one. -@end defvar - -@defvar print-escape-multibyte -If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII} -characters in strings are unconditionally printed as backslash sequences -by the print functions @code{prin1} and @code{print} that print with -quoting. - -Those functions also use backslash sequences for multibyte -non-@acronym{ASCII} characters, regardless of the value of this variable, -when the output stream is a unibyte buffer or a marker pointing into -one. -@end defvar - -@defvar print-length -@cindex printing limits -The value of this variable is the maximum number of elements to print in -any list, vector or bool-vector. If an object being printed has more -than this many elements, it is abbreviated with an ellipsis. - -If the value is @code{nil} (the default), then there is no limit. - -@example -@group -(setq print-length 2) - @result{} 2 -@end group -@group -(print '(1 2 3 4 5)) - @print{} (1 2 ...) - @result{} (1 2 ...) -@end group -@end example -@end defvar - -@defvar print-level -The value of this variable is the maximum depth of nesting of -parentheses and brackets when printed. Any list or vector at a depth -exceeding this limit is abbreviated with an ellipsis. A value of -@code{nil} (which is the default) means no limit. -@end defvar - -@defopt eval-expression-print-length -@defoptx eval-expression-print-level -These are the values for @code{print-length} and @code{print-level} -used by @code{eval-expression}, and thus, indirectly, by many -interactive evaluation commands (@pxref{Lisp Eval,, Evaluating -Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}). -@end defopt - - These variables are used for detecting and reporting circular -and shared structure: - -@defvar print-circle -If non-@code{nil}, this variable enables detection of circular and -shared structure in printing. @xref{Circular Objects}. -@end defvar - -@defvar print-gensym -If non-@code{nil}, this variable enables detection of uninterned symbols -(@pxref{Creating Symbols}) in printing. When this is enabled, -uninterned symbols print with the prefix @samp{#:}, which tells the Lisp -reader to produce an uninterned symbol. -@end defvar - -@defvar print-continuous-numbering -If non-@code{nil}, that means number continuously across print calls. -This affects the numbers printed for @samp{#@var{n}=} labels and -@samp{#@var{m}#} references. -Don't set this variable with @code{setq}; you should only bind it -temporarily to @code{t} with @code{let}. When you do that, you should -also bind @code{print-number-table} to @code{nil}. -@end defvar - -@defvar print-number-table -This variable holds a vector used internally by printing to implement -the @code{print-circle} feature. You should not use it except -to bind it to @code{nil} when you bind @code{print-continuous-numbering}. -@end defvar - -@defvar float-output-format -This variable specifies how to print floating point numbers. The -default is @code{nil}, meaning use the shortest output -that represents the number without losing information. - -To control output format more precisely, you can put a string in this -variable. The string should hold a @samp{%}-specification to be used -in the C function @code{sprintf}. For further restrictions on what -you can use, see the variable's documentation string. -@end defvar diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi deleted file mode 100644 index 3b8c62af313..00000000000 --- a/doc/lispref/strings.texi +++ /dev/null @@ -1,1155 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/strings -@node Strings and Characters, Lists, Numbers, Top -@comment node-name, next, previous, up -@chapter Strings and Characters -@cindex strings -@cindex character arrays -@cindex characters -@cindex bytes - - A string in Emacs Lisp is an array that contains an ordered sequence -of characters. Strings are used as names of symbols, buffers, and -files; to send messages to users; to hold text being copied between -buffers; and for many other purposes. Because strings are so important, -Emacs Lisp has many functions expressly for manipulating them. Emacs -Lisp programs use strings more often than individual characters. - - @xref{Strings of Events}, for special considerations for strings of -keyboard character events. - -@menu -* Basics: String Basics. Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Modifying Strings:: Altering the contents of an existing string. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting to and from characters and strings. -* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. -* Case Conversion:: Case conversion functions. -* Case Tables:: Customizing case conversion. -@end menu - -@node String Basics -@section String and Character Basics - - Characters are represented in Emacs Lisp as integers; -whether an integer is a character or not is determined only by how it is -used. Thus, strings really contain integers. @xref{Character Codes}, -for details about character representation in Emacs. - - The length of a string (like any array) is fixed, and cannot be -altered once the string exists. Strings in Lisp are @emph{not} -terminated by a distinguished character code. (By contrast, strings in -C are terminated by a character with @acronym{ASCII} code 0.) - - Since strings are arrays, and therefore sequences as well, you can -operate on them with the general array and sequence functions. -(@xref{Sequences Arrays Vectors}.) For example, you can access or -change individual characters in a string using the functions @code{aref} -and @code{aset} (@pxref{Array Functions}). However, note that -@code{length} should @emph{not} be used for computing the width of a -string on display; use @code{string-width} (@pxref{Width}) instead. - - There are two text representations for non-@acronym{ASCII} characters in -Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text -Representations}). For most Lisp programming, you don't need to be -concerned with these two representations. - - Sometimes key sequences are represented as unibyte strings. When a -unibyte string is a key sequence, string elements in the range 128 to -255 represent meta characters (which are large integers) rather than -character codes in the range 128 to 255. Strings cannot hold -characters that have the hyper, super or alt modifiers; they can hold -@acronym{ASCII} control characters, but no other control characters. -They do not distinguish case in @acronym{ASCII} control characters. -If you want to store such characters in a sequence, such as a key -sequence, you must use a vector instead of a string. @xref{Character -Type}, for more information about keyboard input characters. - - Strings are useful for holding regular expressions. You can also -match regular expressions against strings with @code{string-match} -(@pxref{Regexp Search}). The functions @code{match-string} -(@pxref{Simple Match Data}) and @code{replace-match} (@pxref{Replacing -Match}) are useful for decomposing and modifying strings after -matching regular expressions against them. - - Like a buffer, a string can contain text properties for the characters -in it, as well as the characters themselves. @xref{Text Properties}. -All the Lisp primitives that copy text from strings to buffers or other -strings also copy the properties of the characters being copied. - - @xref{Text}, for information about functions that display strings or -copy them into buffers. @xref{Character Type}, and @ref{String Type}, -for information about the syntax of characters and strings. -@xref{Non-ASCII Characters}, for functions to convert between text -representations and to encode and decode character codes. - -@node Predicates for Strings -@section The Predicates for Strings - -For more information about general sequence and array predicates, -see @ref{Sequences Arrays Vectors}, and @ref{Arrays}. - -@defun stringp object -This function returns @code{t} if @var{object} is a string, @code{nil} -otherwise. -@end defun - -@defun string-or-null-p object -This function returns @code{t} if @var{object} is a string or -@code{nil}. It returns @code{nil} otherwise. -@end defun - -@defun char-or-string-p object -This function returns @code{t} if @var{object} is a string or a -character (i.e., an integer), @code{nil} otherwise. -@end defun - -@node Creating Strings -@section Creating Strings - - The following functions create strings, either from scratch, or by -putting strings together, or by taking them apart. - -@defun make-string count character -This function returns a string made up of @var{count} repetitions of -@var{character}. If @var{count} is negative, an error is signaled. - -@example -(make-string 5 ?x) - @result{} "xxxxx" -(make-string 0 ?x) - @result{} "" -@end example - - Other functions to compare with this one include @code{make-vector} -(@pxref{Vectors}) and @code{make-list} (@pxref{Building Lists}). -@end defun - -@defun string &rest characters -This returns a string containing the characters @var{characters}. - -@example -(string ?a ?b ?c) - @result{} "abc" -@end example -@end defun - -@defun substring string start &optional end -This function returns a new string which consists of those characters -from @var{string} in the range from (and including) the character at the -index @var{start} up to (but excluding) the character at the index -@var{end}. The first character is at index zero. - -@example -@group -(substring "abcdefg" 0 3) - @result{} "abc" -@end group -@end example - -@noindent -In the above example, the index for @samp{a} is 0, the index for -@samp{b} is 1, and the index for @samp{c} is 2. The index 3---which -is the fourth character in the string---marks the character position -up to which the substring is copied. Thus, @samp{abc} is copied from -the string @code{"abcdefg"}. - -A negative number counts from the end of the string, so that @minus{}1 -signifies the index of the last character of the string. For example: - -@example -@group -(substring "abcdefg" -3 -1) - @result{} "ef" -@end group -@end example - -@noindent -In this example, the index for @samp{e} is @minus{}3, the index for -@samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1. -Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded. - -When @code{nil} is used for @var{end}, it stands for the length of the -string. Thus, - -@example -@group -(substring "abcdefg" -3 nil) - @result{} "efg" -@end group -@end example - -Omitting the argument @var{end} is equivalent to specifying @code{nil}. -It follows that @code{(substring @var{string} 0)} returns a copy of all -of @var{string}. - -@example -@group -(substring "abcdefg" 0) - @result{} "abcdefg" -@end group -@end example - -@noindent -But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence -Functions}). - -If the characters copied from @var{string} have text properties, the -properties are copied into the new string also. @xref{Text Properties}. - -@code{substring} also accepts a vector for the first argument. -For example: - -@example -(substring [a b (c) "d"] 1 3) - @result{} [b (c)] -@end example - -A @code{wrong-type-argument} error is signaled if @var{start} is not -an integer or if @var{end} is neither an integer nor @code{nil}. An -@code{args-out-of-range} error is signaled if @var{start} indicates a -character following @var{end}, or if either integer is out of range -for @var{string}. - -Contrast this function with @code{buffer-substring} (@pxref{Buffer -Contents}), which returns a string containing a portion of the text in -the current buffer. The beginning of a string is at index 0, but the -beginning of a buffer is at index 1. -@end defun - -@defun substring-no-properties string &optional start end -This works like @code{substring} but discards all text properties from -the value. Also, @var{start} may be omitted or @code{nil}, which is -equivalent to 0. Thus, @w{@code{(substring-no-properties -@var{string})}} returns a copy of @var{string}, with all text -properties removed. -@end defun - -@defun concat &rest sequences -@cindex copying strings -@cindex concatenating strings -This function returns a new string consisting of the characters in the -arguments passed to it (along with their text properties, if any). The -arguments may be strings, lists of numbers, or vectors of numbers; they -are not themselves changed. If @code{concat} receives no arguments, it -returns an empty string. - -@example -(concat "abc" "-def") - @result{} "abc-def" -(concat "abc" (list 120 121) [122]) - @result{} "abcxyz" -;; @r{@code{nil} is an empty sequence.} -(concat "abc" nil "-def") - @result{} "abc-def" -(concat "The " "quick brown " "fox.") - @result{} "The quick brown fox." -(concat) - @result{} "" -@end example - -@noindent -This function always constructs a new string that is not @code{eq} to -any existing string, except when the result is the empty string (to -save space, Emacs makes only one empty multibyte string). - -For information about other concatenation functions, see the -description of @code{mapconcat} in @ref{Mapping Functions}, -@code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building -Lists}. For concatenating individual command-line arguments into a -string to be used as a shell command, see @ref{Shell Arguments, -combine-and-quote-strings}. -@end defun - -@defun split-string string &optional separators omit-nulls -This function splits @var{string} into substrings based on the regular -expression @var{separators} (@pxref{Regular Expressions}). Each match -for @var{separators} defines a splitting point; the substrings between -splitting points are made into a list, which is returned. - -If @var{omit-nulls} is @code{nil} (or omitted), the result contains -null strings whenever there are two consecutive matches for -@var{separators}, or a match is adjacent to the beginning or end of -@var{string}. If @var{omit-nulls} is @code{t}, these null strings are -omitted from the result. - -If @var{separators} is @code{nil} (or omitted), the default is the -value of @code{split-string-default-separators}. - -As a special case, when @var{separators} is @code{nil} (or omitted), -null strings are always omitted from the result. Thus: - -@example -(split-string " two words ") - @result{} ("two" "words") -@end example - -The result is not @code{("" "two" "words" "")}, which would rarely be -useful. If you need such a result, use an explicit value for -@var{separators}: - -@example -(split-string " two words " - split-string-default-separators) - @result{} ("" "two" "words" "") -@end example - -More examples: - -@example -(split-string "Soup is good food" "o") - @result{} ("S" "up is g" "" "d f" "" "d") -(split-string "Soup is good food" "o" t) - @result{} ("S" "up is g" "d f" "d") -(split-string "Soup is good food" "o+") - @result{} ("S" "up is g" "d f" "d") -@end example - -Empty matches do count, except that @code{split-string} will not look -for a final empty match when it already reached the end of the string -using a non-empty match or when @var{string} is empty: - -@example -(split-string "aooob" "o*") - @result{} ("" "a" "" "b" "") -(split-string "ooaboo" "o*") - @result{} ("" "" "a" "b" "") -(split-string "" "") - @result{} ("") -@end example - -However, when @var{separators} can match the empty string, -@var{omit-nulls} is usually @code{t}, so that the subtleties in the -three previous examples are rarely relevant: - -@example -(split-string "Soup is good food" "o*" t) - @result{} ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d") -(split-string "Nice doggy!" "" t) - @result{} ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!") -(split-string "" "" t) - @result{} nil -@end example - -Somewhat odd, but predictable, behavior can occur for certain -``non-greedy'' values of @var{separators} that can prefer empty -matches over non-empty matches. Again, such values rarely occur in -practice: - -@example -(split-string "ooo" "o*" t) - @result{} nil -(split-string "ooo" "\\|o+" t) - @result{} ("o" "o" "o") -@end example - -If you need to split a string into a list of individual command-line -arguments suitable for @code{call-process} or @code{start-process}, -see @ref{Shell Arguments, split-string-and-unquote}. -@end defun - -@defvar split-string-default-separators -The default value of @var{separators} for @code{split-string}. Its -usual value is @w{@code{"[ \f\t\n\r\v]+"}}. -@end defvar - -@node Modifying Strings -@section Modifying Strings - - The most basic way to alter the contents of an existing string is with -@code{aset} (@pxref{Array Functions}). @code{(aset @var{string} -@var{idx} @var{char})} stores @var{char} into @var{string} at index -@var{idx}. Each character occupies one or more bytes, and if @var{char} -needs a different number of bytes from the character already present at -that index, @code{aset} signals an error. - - A more powerful function is @code{store-substring}: - -@defun store-substring string idx obj -This function alters part of the contents of the string @var{string}, by -storing @var{obj} starting at index @var{idx}. The argument @var{obj} -may be either a character or a (smaller) string. - -Since it is impossible to change the length of an existing string, it is -an error if @var{obj} doesn't fit within @var{string}'s actual length, -or if any new character requires a different number of bytes from the -character currently present at that point in @var{string}. -@end defun - - To clear out a string that contained a password, use -@code{clear-string}: - -@defun clear-string string -This makes @var{string} a unibyte string and clears its contents to -zeros. It may also change @var{string}'s length. -@end defun - -@need 2000 -@node Text Comparison -@section Comparison of Characters and Strings -@cindex string equality - -@defun char-equal character1 character2 -This function returns @code{t} if the arguments represent the same -character, @code{nil} otherwise. This function ignores differences -in case if @code{case-fold-search} is non-@code{nil}. - -@example -(char-equal ?x ?x) - @result{} t -(let ((case-fold-search nil)) - (char-equal ?x ?X)) - @result{} nil -@end example -@end defun - -@defun string= string1 string2 -This function returns @code{t} if the characters of the two strings -match exactly. Symbols are also allowed as arguments, in which case -the symbol names are used. Case is always significant, regardless of -@code{case-fold-search}. - -This function is equivalent to @code{equal} for comparing two strings -(@pxref{Equality Predicates}). In particular, the text properties of -the two strings are ignored. But if either argument is not a string -or symbol, an error is signaled. - -@example -(string= "abc" "abc") - @result{} t -(string= "abc" "ABC") - @result{} nil -(string= "ab" "ABC") - @result{} nil -@end example - -For technical reasons, a unibyte and a multibyte string are -@code{equal} if and only if they contain the same sequence of -character codes and all these codes are either in the range 0 through -127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}). -However, when a unibyte string is converted to a multibyte string, all -characters with codes in the range 160 through 255 are converted to -characters with higher codes, whereas @acronym{ASCII} characters -remain unchanged. Thus, a unibyte string and its conversion to -multibyte are only @code{equal} if the string is all @acronym{ASCII}. -Character codes 160 through 255 are not entirely proper in multibyte -text, even though they can occur. As a consequence, the situation -where a unibyte and a multibyte string are @code{equal} without both -being all @acronym{ASCII} is a technical oddity that very few Emacs -Lisp programmers ever get confronted with. @xref{Text -Representations}. -@end defun - -@defun string-equal string1 string2 -@code{string-equal} is another name for @code{string=}. -@end defun - -@cindex lexical comparison -@defun string< string1 string2 -@c (findex string< causes problems for permuted index!!) -This function compares two strings a character at a time. It -scans both the strings at the same time to find the first pair of corresponding -characters that do not match. If the lesser character of these two is -the character from @var{string1}, then @var{string1} is less, and this -function returns @code{t}. If the lesser character is the one from -@var{string2}, then @var{string1} is greater, and this function returns -@code{nil}. If the two strings match entirely, the value is @code{nil}. - -Pairs of characters are compared according to their character codes. -Keep in mind that lower case letters have higher numeric values in the -@acronym{ASCII} character set than their upper case counterparts; digits and -many punctuation characters have a lower numeric value than upper case -letters. An @acronym{ASCII} character is less than any non-@acronym{ASCII} -character; a unibyte non-@acronym{ASCII} character is always less than any -multibyte non-@acronym{ASCII} character (@pxref{Text Representations}). - -@example -@group -(string< "abc" "abd") - @result{} t -(string< "abd" "abc") - @result{} nil -(string< "123" "abc") - @result{} t -@end group -@end example - -When the strings have different lengths, and they match up to the -length of @var{string1}, then the result is @code{t}. If they match up -to the length of @var{string2}, the result is @code{nil}. A string of -no characters is less than any other string. - -@example -@group -(string< "" "abc") - @result{} t -(string< "ab" "abc") - @result{} t -(string< "abc" "") - @result{} nil -(string< "abc" "ab") - @result{} nil -(string< "" "") - @result{} nil -@end group -@end example - -Symbols are also allowed as arguments, in which case their print names -are used. -@end defun - -@defun string-lessp string1 string2 -@code{string-lessp} is another name for @code{string<}. -@end defun - -@defun string-prefix-p string1 string2 &optional ignore-case -This function returns non-@code{nil} if @var{string1} is a prefix of -@var{string2}; i.e., if @var{string2} starts with @var{string1}. If -the optional argument @var{ignore-case} is non-@code{nil}, the -comparison ignores case differences. -@end defun - -@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case -This function compares the specified part of @var{string1} with the -specified part of @var{string2}. The specified part of @var{string1} -runs from index @var{start1} up to index @var{end1} (@code{nil} means -the end of the string). The specified part of @var{string2} runs from -index @var{start2} up to index @var{end2} (@code{nil} means the end of -the string). - -The strings are both converted to multibyte for the comparison -(@pxref{Text Representations}) so that a unibyte string and its -conversion to multibyte are always regarded as equal. If -@var{ignore-case} is non-@code{nil}, then case is ignored, so that -upper case letters can be equal to lower case letters. - -If the specified portions of the two strings match, the value is -@code{t}. Otherwise, the value is an integer which indicates how many -leading characters agree, and which string is less. Its absolute value -is one plus the number of characters that agree at the beginning of the -two strings. The sign is negative if @var{string1} (or its specified -portion) is less. -@end defun - -@defun assoc-string key alist &optional case-fold -This function works like @code{assoc}, except that @var{key} must be a -string or symbol, and comparison is done using @code{compare-strings}. -Symbols are converted to strings before testing. -If @var{case-fold} is non-@code{nil}, it ignores case differences. -Unlike @code{assoc}, this function can also match elements of the alist -that are strings or symbols rather than conses. In particular, @var{alist} can -be a list of strings or symbols rather than an actual alist. -@xref{Association Lists}. -@end defun - - See also the function @code{compare-buffer-substrings} in -@ref{Comparing Text}, for a way to compare text in buffers. The -function @code{string-match}, which matches a regular expression -against a string, can be used for a kind of string comparison; see -@ref{Regexp Search}. - -@node String Conversion -@comment node-name, next, previous, up -@section Conversion of Characters and Strings -@cindex conversion of strings - - This section describes functions for converting between characters, -strings and integers. @code{format} (@pxref{Formatting Strings}) and -@code{prin1-to-string} (@pxref{Output Functions}) can also convert -Lisp objects into strings. @code{read-from-string} (@pxref{Input -Functions}) can ``convert'' a string representation of a Lisp object -into an object. The functions @code{string-to-multibyte} and -@code{string-to-unibyte} convert the text representation of a string -(@pxref{Converting Representations}). - - @xref{Documentation}, for functions that produce textual descriptions -of text characters and general input events -(@code{single-key-description} and @code{text-char-description}). These -are used primarily for making help messages. - -@defun number-to-string number -@cindex integer to string -@cindex integer to decimal -This function returns a string consisting of the printed base-ten -representation of @var{number}, which may be an integer or a floating -point number. The returned value starts with a minus sign if the argument is -negative. - -@example -(number-to-string 256) - @result{} "256" -@group -(number-to-string -23) - @result{} "-23" -@end group -(number-to-string -23.5) - @result{} "-23.5" -@end example - -@cindex int-to-string -@code{int-to-string} is a semi-obsolete alias for this function. - -See also the function @code{format} in @ref{Formatting Strings}. -@end defun - -@defun string-to-number string &optional base -@cindex string to number -This function returns the numeric value of the characters in -@var{string}. If @var{base} is non-@code{nil}, it must be an integer -between 2 and 16 (inclusive), and integers are converted in that base. -If @var{base} is @code{nil}, then base ten is used. Floating point -conversion only works in base ten; we have not implemented other -radices for floating point numbers, because that would be much more -work and does not seem useful. If @var{string} looks like an integer -but its value is too large to fit into a Lisp integer, -@code{string-to-number} returns a floating point result. - -The parsing skips spaces and tabs at the beginning of @var{string}, -then reads as much of @var{string} as it can interpret as a number in -the given base. (On some systems it ignores other whitespace at the -beginning, not just spaces and tabs.) If the first character after -the ignored whitespace is neither a digit in the given base, nor a -plus or minus sign, nor the leading dot of a floating point number, -this function returns 0. - -@example -(string-to-number "256") - @result{} 256 -(string-to-number "25 is a perfect square.") - @result{} 25 -(string-to-number "X256") - @result{} 0 -(string-to-number "-4.5") - @result{} -4.5 -(string-to-number "1e5") - @result{} 100000.0 -@end example - -@findex string-to-int -@code{string-to-int} is an obsolete alias for this function. -@end defun - -@defun char-to-string character -@cindex character to string -This function returns a new string containing one character, -@var{character}. This function is semi-obsolete because the function -@code{string} is more general. @xref{Creating Strings}. -@end defun - -@defun string-to-char string - This function returns the first character in @var{string}. This -mostly identical to @code{(aref string 0)}, except that it returns 0 -if the string is empty. (The value is also 0 when the first character -of @var{string} is the null character, @acronym{ASCII} code 0.) This -function may be eliminated in the future if it does not seem useful -enough to retain. -@end defun - - Here are some other functions that can convert to or from a string: - -@table @code -@item concat -This function converts a vector or a list into a string. -@xref{Creating Strings}. - -@item vconcat -This function converts a string into a vector. @xref{Vector -Functions}. - -@item append -This function converts a string into a list. @xref{Building Lists}. - -@item byte-to-string -This function converts a byte of character data into a unibyte string. -@xref{Converting Representations}. -@end table - -@node Formatting Strings -@comment node-name, next, previous, up -@section Formatting Strings -@cindex formatting strings -@cindex strings, formatting them - - @dfn{Formatting} means constructing a string by substituting -computed values at various places in a constant string. This constant -string controls how the other values are printed, as well as where -they appear; it is called a @dfn{format string}. - - Formatting is often useful for computing messages to be displayed. In -fact, the functions @code{message} and @code{error} provide the same -formatting feature described here; they differ from @code{format} only -in how they use the result of formatting. - -@defun format string &rest objects -This function returns a new string that is made by copying -@var{string} and then replacing any format specification -in the copy with encodings of the corresponding @var{objects}. The -arguments @var{objects} are the computed values to be formatted. - -The characters in @var{string}, other than the format specifications, -are copied directly into the output, including their text properties, -if any. -@end defun - -@cindex @samp{%} in format -@cindex format specification - A format specification is a sequence of characters beginning with a -@samp{%}. Thus, if there is a @samp{%d} in @var{string}, the -@code{format} function replaces it with the printed representation of -one of the values to be formatted (one of the arguments @var{objects}). -For example: - -@example -@group -(format "The value of fill-column is %d." fill-column) - @result{} "The value of fill-column is 72." -@end group -@end example - - Since @code{format} interprets @samp{%} characters as format -specifications, you should @emph{never} pass an arbitrary string as -the first argument. This is particularly true when the string is -generated by some Lisp code. Unless the string is @emph{known} to -never include any @samp{%} characters, pass @code{"%s"}, described -below, as the first argument, and the string as the second, like this: - -@example - (format "%s" @var{arbitrary-string}) -@end example - - If @var{string} contains more than one format specification, the -format specifications correspond to successive values from -@var{objects}. Thus, the first format specification in @var{string} -uses the first such value, the second format specification uses the -second such value, and so on. Any extra format specifications (those -for which there are no corresponding values) cause an error. Any -extra values to be formatted are ignored. - - Certain format specifications require values of particular types. If -you supply a value that doesn't fit the requirements, an error is -signaled. - - Here is a table of valid format specifications: - -@table @samp -@item %s -Replace the specification with the printed representation of the object, -made without quoting (that is, using @code{princ}, not -@code{prin1}---@pxref{Output Functions}). Thus, strings are represented -by their contents alone, with no @samp{"} characters, and symbols appear -without @samp{\} characters. - -If the object is a string, its text properties are -copied into the output. The text properties of the @samp{%s} itself -are also copied, but those of the object take priority. - -@item %S -Replace the specification with the printed representation of the object, -made with quoting (that is, using @code{prin1}---@pxref{Output -Functions}). Thus, strings are enclosed in @samp{"} characters, and -@samp{\} characters appear where necessary before special characters. - -@item %o -@cindex integer to octal -Replace the specification with the base-eight representation of an -integer. - -@item %d -Replace the specification with the base-ten representation of an -integer. - -@item %x -@itemx %X -@cindex integer to hexadecimal -Replace the specification with the base-sixteen representation of an -integer. @samp{%x} uses lower case and @samp{%X} uses upper case. - -@item %c -Replace the specification with the character which is the value given. - -@item %e -Replace the specification with the exponential notation for a floating -point number. - -@item %f -Replace the specification with the decimal-point notation for a floating -point number. - -@item %g -Replace the specification with notation for a floating point number, -using either exponential notation or decimal-point notation, whichever -is shorter. - -@item %% -Replace the specification with a single @samp{%}. This format -specification is unusual in that it does not use a value. For example, -@code{(format "%% %d" 30)} returns @code{"% 30"}. -@end table - - Any other format character results in an @samp{Invalid format -operation} error. - - Here are several examples: - -@example -@group -(format "The name of this buffer is %s." (buffer-name)) - @result{} "The name of this buffer is strings.texi." - -(format "The buffer object prints as %s." (current-buffer)) - @result{} "The buffer object prints as strings.texi." - -(format "The octal value of %d is %o, - and the hex value is %x." 18 18 18) - @result{} "The octal value of 18 is 22, - and the hex value is 12." -@end group -@end example - -@cindex field width -@cindex padding - A specification can have a @dfn{width}, which is a decimal number -between the @samp{%} and the specification character. If the printed -representation of the object contains fewer characters than this -width, @code{format} extends it with padding. The width specifier is -ignored for the @samp{%%} specification. Any padding introduced by -the width specifier normally consists of spaces inserted on the left: - -@example -(format "%5d is padded on the left with spaces" 123) - @result{} " 123 is padded on the left with spaces" -@end example - -@noindent -If the width is too small, @code{format} does not truncate the -object's printed representation. Thus, you can use a width to specify -a minimum spacing between columns with no risk of losing information. -In the following three examples, @samp{%7s} specifies a minimum width -of 7. In the first case, the string inserted in place of @samp{%7s} -has only 3 letters, and needs 4 blank spaces as padding. In the -second case, the string @code{"specification"} is 13 letters wide but -is not truncated. - -@example -@group -(format "The word `%7s' has %d letters in it." - "foo" (length "foo")) - @result{} "The word ` foo' has 3 letters in it." -(format "The word `%7s' has %d letters in it." - "specification" (length "specification")) - @result{} "The word `specification' has 13 letters in it." -@end group -@end example - -@cindex flags in format specifications - Immediately after the @samp{%} and before the optional width -specifier, you can also put certain @dfn{flag characters}. - - The flag @samp{+} inserts a plus sign before a positive number, so -that it always has a sign. A space character as flag inserts a space -before a positive number. (Otherwise, positive numbers start with the -first digit.) These flags are useful for ensuring that positive -numbers and negative numbers use the same number of columns. They are -ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if -both flags are used, @samp{+} takes precedence. - - The flag @samp{#} specifies an ``alternate form'' which depends on -the format in use. For @samp{%o}, it ensures that the result begins -with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result -with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g}, -the @samp{#} flag means include a decimal point even if the precision -is zero. - - The flag @samp{0} ensures that the padding consists of @samp{0} -characters instead of spaces. This flag is ignored for non-numerical -specification characters like @samp{%s}, @samp{%S} and @samp{%c}. -These specification characters accept the @samp{0} flag, but still pad -with @emph{spaces}. - - The flag @samp{-} causes the padding inserted by the width -specifier, if any, to be inserted on the right rather than the left. -If both @samp{-} and @samp{0} are present, the @samp{0} flag is -ignored. - -@example -@group -(format "%06d is padded on the left with zeros" 123) - @result{} "000123 is padded on the left with zeros" - -(format "%-6d is padded on the right" 123) - @result{} "123 is padded on the right" - -(format "The word `%-7s' actually has %d letters in it." - "foo" (length "foo")) - @result{} "The word `foo ' actually has 3 letters in it." -@end group -@end example - -@cindex precision in format specifications - All the specification characters allow an optional @dfn{precision} -before the character (after the width, if present). The precision is -a decimal-point @samp{.} followed by a digit-string. For the -floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the -precision specifies how many decimal places to show; if zero, the -decimal-point itself is also omitted. For @samp{%s} and @samp{%S}, -the precision truncates the string to the given width, so @samp{%.3s} -shows only the first three characters of the representation for -@var{object}. Precision has no effect for other specification -characters. - -@node Case Conversion -@comment node-name, next, previous, up -@section Case Conversion in Lisp -@cindex upper case -@cindex lower case -@cindex character case -@cindex case conversion in Lisp - - The character case functions change the case of single characters or -of the contents of strings. The functions normally convert only -alphabetic characters (the letters @samp{A} through @samp{Z} and -@samp{a} through @samp{z}, as well as non-@acronym{ASCII} letters); other -characters are not altered. You can specify a different case -conversion mapping by specifying a case table (@pxref{Case Tables}). - - These functions do not modify the strings that are passed to them as -arguments. - - The examples below use the characters @samp{X} and @samp{x} which have -@acronym{ASCII} codes 88 and 120 respectively. - -@defun downcase string-or-char -This function converts @var{string-or-char}, which should be either a -character or a string, to lower case. - -When @var{string-or-char} is a string, this function returns a new -string in which each letter in the argument that is upper case is -converted to lower case. When @var{string-or-char} is a character, -this function returns the corresponding lower case character (an -integer); if the original character is lower case, or is not a letter, -the return value is equal to the original character. - -@example -(downcase "The cat in the hat") - @result{} "the cat in the hat" - -(downcase ?X) - @result{} 120 -@end example -@end defun - -@defun upcase string-or-char -This function converts @var{string-or-char}, which should be either a -character or a string, to upper case. - -When @var{string-or-char} is a string, this function returns a new -string in which each letter in the argument that is lower case is -converted to upper case. When @var{string-or-char} is a character, -this function returns the corresponding upper case character (an -integer); if the original character is upper case, or is not a letter, -the return value is equal to the original character. - -@example -(upcase "The cat in the hat") - @result{} "THE CAT IN THE HAT" - -(upcase ?x) - @result{} 88 -@end example -@end defun - -@defun capitalize string-or-char -@cindex capitalization -This function capitalizes strings or characters. If -@var{string-or-char} is a string, the function returns a new string -whose contents are a copy of @var{string-or-char} in which each word -has been capitalized. This means that the first character of each -word is converted to upper case, and the rest are converted to lower -case. - -The definition of a word is any sequence of consecutive characters that -are assigned to the word constituent syntax class in the current syntax -table (@pxref{Syntax Class Table}). - -When @var{string-or-char} is a character, this function does the same -thing as @code{upcase}. - -@example -@group -(capitalize "The cat in the hat") - @result{} "The Cat In The Hat" -@end group - -@group -(capitalize "THE 77TH-HATTED CAT") - @result{} "The 77th-Hatted Cat" -@end group - -@group -(capitalize ?x) - @result{} 88 -@end group -@end example -@end defun - -@defun upcase-initials string-or-char -If @var{string-or-char} is a string, this function capitalizes the -initials of the words in @var{string-or-char}, without altering any -letters other than the initials. It returns a new string whose -contents are a copy of @var{string-or-char}, in which each word has -had its initial letter converted to upper case. - -The definition of a word is any sequence of consecutive characters that -are assigned to the word constituent syntax class in the current syntax -table (@pxref{Syntax Class Table}). - -When the argument to @code{upcase-initials} is a character, -@code{upcase-initials} has the same result as @code{upcase}. - -@example -@group -(upcase-initials "The CAT in the hAt") - @result{} "The CAT In The HAt" -@end group -@end example -@end defun - - @xref{Text Comparison}, for functions that compare strings; some of -them ignore case differences, or can optionally ignore case differences. - -@node Case Tables -@section The Case Table - - You can customize case conversion by installing a special @dfn{case -table}. A case table specifies the mapping between upper case and lower -case letters. It affects both the case conversion functions for Lisp -objects (see the previous section) and those that apply to text in the -buffer (@pxref{Case Changes}). Each buffer has a case table; there is -also a standard case table which is used to initialize the case table -of new buffers. - - A case table is a char-table (@pxref{Char-Tables}) whose subtype is -@code{case-table}. This char-table maps each character into the -corresponding lower case character. It has three extra slots, which -hold related tables: - -@table @var -@item upcase -The upcase table maps each character into the corresponding upper -case character. -@item canonicalize -The canonicalize table maps all of a set of case-related characters -into a particular member of that set. -@item equivalences -The equivalences table maps each one of a set of case-related characters -into the next character in that set. -@end table - - In simple cases, all you need to specify is the mapping to lower-case; -the three related tables will be calculated automatically from that one. - - For some languages, upper and lower case letters are not in one-to-one -correspondence. There may be two different lower case letters with the -same upper case equivalent. In these cases, you need to specify the -maps for both lower case and upper case. - - The extra table @var{canonicalize} maps each character to a canonical -equivalent; any two characters that are related by case-conversion have -the same canonical equivalent character. For example, since @samp{a} -and @samp{A} are related by case-conversion, they should have the same -canonical equivalent character (which should be either @samp{a} for both -of them, or @samp{A} for both of them). - - The extra table @var{equivalences} is a map that cyclically permutes -each equivalence class (of characters with the same canonical -equivalent). (For ordinary @acronym{ASCII}, this would map @samp{a} into -@samp{A} and @samp{A} into @samp{a}, and likewise for each set of -equivalent characters.) - - When constructing a case table, you can provide @code{nil} for -@var{canonicalize}; then Emacs fills in this slot from the lower case -and upper case mappings. You can also provide @code{nil} for -@var{equivalences}; then Emacs fills in this slot from -@var{canonicalize}. In a case table that is actually in use, those -components are non-@code{nil}. Do not try to specify -@var{equivalences} without also specifying @var{canonicalize}. - - Here are the functions for working with case tables: - -@defun case-table-p object -This predicate returns non-@code{nil} if @var{object} is a valid case -table. -@end defun - -@defun set-standard-case-table table -This function makes @var{table} the standard case table, so that it will -be used in any buffers created subsequently. -@end defun - -@defun standard-case-table -This returns the standard case table. -@end defun - -@defun current-case-table -This function returns the current buffer's case table. -@end defun - -@defun set-case-table table -This sets the current buffer's case table to @var{table}. -@end defun - -@defmac with-case-table table body@dots{} -The @code{with-case-table} macro saves the current case table, makes -@var{table} the current case table, evaluates the @var{body} forms, -and finally restores the case table. The return value is the value of -the last form in @var{body}. The case table is restored even in case -of an abnormal exit via @code{throw} or error (@pxref{Nonlocal -Exits}). -@end defmac - - Some language environments modify the case conversions of -@acronym{ASCII} characters; for example, in the Turkish language -environment, the @acronym{ASCII} character @samp{I} is downcased into -a Turkish ``dotless i''. This can interfere with code that requires -ordinary @acronym{ASCII} case conversion, such as implementations of -@acronym{ASCII}-based network protocols. In that case, use the -@code{with-case-table} macro with the variable @var{ascii-case-table}, -which stores the unmodified case table for the @acronym{ASCII} -character set. - -@defvar ascii-case-table -The case table for the @acronym{ASCII} character set. This should not be -modified by any language environment settings. -@end defvar - - The following three functions are convenient subroutines for packages -that define non-@acronym{ASCII} character sets. They modify the specified -case table @var{case-table}; they also modify the standard syntax table. -@xref{Syntax Tables}. Normally you would use these functions to change -the standard case table. - -@defun set-case-syntax-pair uc lc case-table -This function specifies a pair of corresponding letters, one upper case -and one lower case. -@end defun - -@defun set-case-syntax-delims l r case-table -This function makes characters @var{l} and @var{r} a matching pair of -case-invariant delimiters. -@end defun - -@defun set-case-syntax char syntax case-table -This function makes @var{char} case-invariant, with syntax -@var{syntax}. -@end defun - -@deffn Command describe-buffer-case-table -This command displays a description of the contents of the current -buffer's case table. -@end deffn diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi deleted file mode 100644 index 6148d76ca32..00000000000 --- a/doc/lispref/symbols.texi +++ /dev/null @@ -1,573 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/symbols -@node Symbols, Evaluation, Hash Tables, Top -@chapter Symbols -@cindex symbol - - A @dfn{symbol} is an object with a unique name. This chapter -describes symbols, their components, their property lists, and how they -are created and interned. Separate chapters describe the use of symbols -as variables and as function names; see @ref{Variables}, and -@ref{Functions}. For the precise read syntax for symbols, see -@ref{Symbol Type}. - - You can test whether an arbitrary Lisp object is a symbol -with @code{symbolp}: - -@defun symbolp object -This function returns @code{t} if @var{object} is a symbol, @code{nil} -otherwise. -@end defun - -@menu -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list - for recording miscellaneous information. -@end menu - -@node Symbol Components, Definitions, Symbols, Symbols -@section Symbol Components -@cindex symbol components - - Each symbol has four components (or ``cells''), each of which -references another object: - -@table @asis -@item Print name -@cindex print name cell -The symbol's name. - -@item Value -@cindex value cell -The symbol's current value as a variable. - -@item Function -@cindex function cell -The symbol's function definition. It can also hold a symbol, a -keymap, or a keyboard macro. - -@item Property list -@cindex property list cell -The symbol's property list. -@end table - -@noindent -The print name cell always holds a string, and cannot be changed. -Each of the other three cells can be set to any Lisp object. - - The print name cell holds the string that is the name of a symbol. -Since symbols are represented textually by their names, it is -important not to have two symbols with the same name. The Lisp reader -ensures this: every time it reads a symbol, it looks for an existing -symbol with the specified name before it creates a new one. To get a -symbol's name, use the function @code{symbol-name} (@pxref{Creating -Symbols}). - - The value cell holds a symbol's value as a variable, which is what -you get if the symbol itself is evaluated as a Lisp expression. -@xref{Variables}, for details about how values are set and retrieved, -including complications such as @dfn{local bindings} and @dfn{scoping -rules}. Most symbols can have any Lisp object as a value, but certain -special symbols have values that cannot be changed; these include -@code{nil} and @code{t}, and any symbol whose name starts with -@samp{:} (those are called @dfn{keywords}). @xref{Constant -Variables}. - - The function cell holds a symbol's function definition. Often, we -refer to ``the function @code{foo}'' when we really mean the function -stored in the function cell of @code{foo}; we make the distinction -explicit only when necessary. Typically, the function cell is used to -hold a function (@pxref{Functions}) or a macro (@pxref{Macros}). -However, it can also be used to hold a symbol (@pxref{Function -Indirection}), keyboard macro (@pxref{Keyboard Macros}), keymap -(@pxref{Keymaps}), or autoload object (@pxref{Autoloading}). To get -the contents of a symbol's function cell, use the function -@code{symbol-function} (@pxref{Function Cells}). - - The property list cell normally should hold a correctly formatted -property list. To get a symbol's property list, use the function -@code{symbol-plist}. @xref{Property Lists}. - - The function cell or the value cell may be @dfn{void}, which means -that the cell does not reference any object. (This is not the same -thing as holding the symbol @code{void}, nor the same as holding the -symbol @code{nil}.) Examining a function or value cell that is void -results in an error, such as @samp{Symbol's value as variable is void}. - - Because each symbol has separate value and function cells, variables -names and function names do not conflict. For example, the symbol -@code{buffer-file-name} has a value (the name of the file being -visited in the current buffer) as well as a function definition (a -primitive function that returns the name of the file): - -@example -buffer-file-name - @result{} "/gnu/elisp/symbols.texi" -(symbol-function 'buffer-file-name) - @result{} # -@end example - -@node Definitions, Creating Symbols, Symbol Components, Symbols -@section Defining Symbols -@cindex definitions of symbols - - A @dfn{definition} is a special kind of Lisp expression that -announces your intention to use a symbol in a particular way. It -typically specifies a value or meaning for the symbol for one kind of -use, plus documentation for its meaning when used in this way. Thus, -when you define a symbol as a variable, you can supply an initial -value for the variable, plus documentation for the variable. - - @code{defvar} and @code{defconst} are special forms that define a -symbol as a @dfn{global variable}---a variable that can be accessed at -any point in a Lisp program. @xref{Variables}, for details about -variables. To define a customizable variable, use the -@code{defcustom} macro, which also calls @code{defvar} as a subroutine -(@pxref{Customization}). - - In principle, you can assign a variable value to any symbol with -@code{setq}, whether not it has first been defined as a variable. -However, you ought to write a variable definition for each global -variable that you want to use; otherwise, your Lisp program may not -act correctly if it is evaluated with lexical scoping enabled -(@pxref{Variable Scoping}). - - @code{defun} defines a symbol as a function, creating a lambda -expression and storing it in the function cell of the symbol. This -lambda expression thus becomes the function definition of the symbol. -(The term ``function definition'', meaning the contents of the function -cell, is derived from the idea that @code{defun} gives the symbol its -definition as a function.) @code{defsubst} and @code{defalias} are two -other ways of defining a function. @xref{Functions}. - - @code{defmacro} defines a symbol as a macro. It creates a macro -object and stores it in the function cell of the symbol. Note that a -given symbol can be a macro or a function, but not both at once, because -both macro and function definitions are kept in the function cell, and -that cell can hold only one Lisp object at any given time. -@xref{Macros}. - - As previously noted, Emacs Lisp allows the same symbol to be defined -both as a variable (e.g.@: with @code{defvar}) and as a function or -macro (e.g.@: with @code{defun}). Such definitions do not conflict. - - These definition also act as guides for programming tools. For -example, the @kbd{C-h f} and @kbd{C-h v} commands create help buffers -containing links to the relevant variable, function, or macro -definitions. @xref{Name Help,,, emacs, The GNU Emacs Manual}. - -@node Creating Symbols, Property Lists, Definitions, Symbols -@section Creating and Interning Symbols -@cindex reading symbols - - To understand how symbols are created in GNU Emacs Lisp, you must know -how Lisp reads them. Lisp must ensure that it finds the same symbol -every time it reads the same set of characters. Failure to do so would -cause complete confusion. - -@cindex symbol name hashing -@cindex hashing -@cindex obarray -@cindex bucket (in obarray) - When the Lisp reader encounters a symbol, it reads all the characters -of the name. Then it ``hashes'' those characters to find an index in a -table called an @dfn{obarray}. Hashing is an efficient method of -looking something up. For example, instead of searching a telephone -book cover to cover when looking up Jan Jones, you start with the J's -and go from there. That is a simple version of hashing. Each element -of the obarray is a @dfn{bucket} which holds all the symbols with a -given hash code; to look for a given name, it is sufficient to look -through all the symbols in the bucket for that name's hash code. (The -same idea is used for general Emacs hash tables, but they are a -different data type; see @ref{Hash Tables}.) - -@cindex interning - If a symbol with the desired name is found, the reader uses that -symbol. If the obarray does not contain a symbol with that name, the -reader makes a new symbol and adds it to the obarray. Finding or adding -a symbol with a certain name is called @dfn{interning} it, and the -symbol is then called an @dfn{interned symbol}. - - Interning ensures that each obarray has just one symbol with any -particular name. Other like-named symbols may exist, but not in the -same obarray. Thus, the reader gets the same symbols for the same -names, as long as you keep reading with the same obarray. - - Interning usually happens automatically in the reader, but sometimes -other programs need to do it. For example, after the @kbd{M-x} command -obtains the command name as a string using the minibuffer, it then -interns the string, to get the interned symbol with that name. - -@cindex symbol equality -@cindex uninterned symbol - No obarray contains all symbols; in fact, some symbols are not in any -obarray. They are called @dfn{uninterned symbols}. An uninterned -symbol has the same four cells as other symbols; however, the only way -to gain access to it is by finding it in some other object or as the -value of a variable. - - Creating an uninterned symbol is useful in generating Lisp code, -because an uninterned symbol used as a variable in the code you generate -cannot clash with any variables used in other Lisp programs. - - In Emacs Lisp, an obarray is actually a vector. Each element of the -vector is a bucket; its value is either an interned symbol whose name -hashes to that bucket, or 0 if the bucket is empty. Each interned -symbol has an internal link (invisible to the user) to the next symbol -in the bucket. Because these links are invisible, there is no way to -find all the symbols in an obarray except using @code{mapatoms} (below). -The order of symbols in a bucket is not significant. - - In an empty obarray, every element is 0, so you can create an obarray -with @code{(make-vector @var{length} 0)}. @strong{This is the only -valid way to create an obarray.} Prime numbers as lengths tend -to result in good hashing; lengths one less than a power of two are also -good. - - @strong{Do not try to put symbols in an obarray yourself.} This does -not work---only @code{intern} can enter a symbol in an obarray properly. - -@cindex CL note---symbol in obarrays -@quotation -@b{Common Lisp note:} Unlike Common Lisp, Emacs Lisp does not provide -for interning a single symbol in several obarrays. -@end quotation - - Most of the functions below take a name and sometimes an obarray as -arguments. A @code{wrong-type-argument} error is signaled if the name -is not a string, or if the obarray is not a vector. - -@defun symbol-name symbol -This function returns the string that is @var{symbol}'s name. For example: - -@example -@group -(symbol-name 'foo) - @result{} "foo" -@end group -@end example - -@strong{Warning:} Changing the string by substituting characters does -change the name of the symbol, but fails to update the obarray, so don't -do it! -@end defun - -@defun make-symbol name -This function returns a newly-allocated, uninterned symbol whose name is -@var{name} (which must be a string). Its value and function definition -are void, and its property list is @code{nil}. In the example below, -the value of @code{sym} is not @code{eq} to @code{foo} because it is a -distinct uninterned symbol whose name is also @samp{foo}. - -@example -(setq sym (make-symbol "foo")) - @result{} foo -(eq sym 'foo) - @result{} nil -@end example -@end defun - -@defun intern name &optional obarray -This function returns the interned symbol whose name is @var{name}. If -there is no such symbol in the obarray @var{obarray}, @code{intern} -creates a new one, adds it to the obarray, and returns it. If -@var{obarray} is omitted, the value of the global variable -@code{obarray} is used. - -@example -(setq sym (intern "foo")) - @result{} foo -(eq sym 'foo) - @result{} t - -(setq sym1 (intern "foo" other-obarray)) - @result{} foo -(eq sym1 'foo) - @result{} nil -@end example -@end defun - -@cindex CL note---interning existing symbol -@quotation -@b{Common Lisp note:} In Common Lisp, you can intern an existing symbol -in an obarray. In Emacs Lisp, you cannot do this, because the argument -to @code{intern} must be a string, not a symbol. -@end quotation - -@defun intern-soft name &optional obarray -This function returns the symbol in @var{obarray} whose name is -@var{name}, or @code{nil} if @var{obarray} has no symbol with that name. -Therefore, you can use @code{intern-soft} to test whether a symbol with -a given name is already interned. If @var{obarray} is omitted, the -value of the global variable @code{obarray} is used. - -The argument @var{name} may also be a symbol; in that case, -the function returns @var{name} if @var{name} is interned -in the specified obarray, and otherwise @code{nil}. - -@example -(intern-soft "frazzle") ; @r{No such symbol exists.} - @result{} nil -(make-symbol "frazzle") ; @r{Create an uninterned one.} - @result{} frazzle -@group -(intern-soft "frazzle") ; @r{That one cannot be found.} - @result{} nil -@end group -@group -(setq sym (intern "frazzle")) ; @r{Create an interned one.} - @result{} frazzle -@end group -@group -(intern-soft "frazzle") ; @r{That one can be found!} - @result{} frazzle -@end group -@group -(eq sym 'frazzle) ; @r{And it is the same one.} - @result{} t -@end group -@end example -@end defun - -@defvar obarray -This variable is the standard obarray for use by @code{intern} and -@code{read}. -@end defvar - -@defun mapatoms function &optional obarray -@anchor{Definition of mapatoms} -This function calls @var{function} once with each symbol in the obarray -@var{obarray}. Then it returns @code{nil}. If @var{obarray} is -omitted, it defaults to the value of @code{obarray}, the standard -obarray for ordinary symbols. - -@example -(setq count 0) - @result{} 0 -(defun count-syms (s) - (setq count (1+ count))) - @result{} count-syms -(mapatoms 'count-syms) - @result{} nil -count - @result{} 1871 -@end example - -See @code{documentation} in @ref{Accessing Documentation}, for another -example using @code{mapatoms}. -@end defun - -@defun unintern symbol obarray -This function deletes @var{symbol} from the obarray @var{obarray}. If -@code{symbol} is not actually in the obarray, @code{unintern} does -nothing. If @var{obarray} is @code{nil}, the current obarray is used. - -If you provide a string instead of a symbol as @var{symbol}, it stands -for a symbol name. Then @code{unintern} deletes the symbol (if any) in -the obarray which has that name. If there is no such symbol, -@code{unintern} does nothing. - -If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise -it returns @code{nil}. -@end defun - -@node Property Lists,, Creating Symbols, Symbols -@section Property Lists -@cindex property list -@cindex plist - - A @dfn{property list} (@dfn{plist} for short) is a list of paired -elements. Each of the pairs associates a property name (usually a -symbol) with a property or value. - - Every symbol has a cell that stores a property list (@pxref{Symbol -Components}). This property list is used to record information about -the symbol, such as its variable documentation and the name of the -file where it was defined. - - Property lists can also be used in other contexts. For instance, -you can assign property lists to character positions in a string or -buffer. @xref{Text Properties}. - - The property names and values in a property list can be any Lisp -objects, but the names are usually symbols. Property list functions -compare the property names using @code{eq}. Here is an example of a -property list, found on the symbol @code{progn} when the compiler is -loaded: - -@example -(lisp-indent-function 0 byte-compile byte-compile-progn) -@end example - -@noindent -Here @code{lisp-indent-function} and @code{byte-compile} are property -names, and the other two elements are the corresponding values. - -@menu -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. -@end menu - -@node Plists and Alists -@subsection Property Lists and Association Lists -@cindex plist vs. alist -@cindex alist vs. plist - -@cindex property lists vs association lists - Association lists (@pxref{Association Lists}) are very similar to -property lists. In contrast to association lists, the order of the -pairs in the property list is not significant since the property names -must be distinct. - - Property lists are better than association lists for attaching -information to various Lisp function names or variables. If your -program keeps all such information in one association list, it will -typically need to search that entire list each time it checks for an -association for a particular Lisp function name or variable, which -could be slow. By contrast, if you keep the same information in the -property lists of the function names or variables themselves, each -search will scan only the length of one property list, which is -usually short. This is why the documentation for a variable is -recorded in a property named @code{variable-documentation}. The byte -compiler likewise uses properties to record those functions needing -special treatment. - - However, association lists have their own advantages. Depending on -your application, it may be faster to add an association to the front of -an association list than to update a property. All properties for a -symbol are stored in the same property list, so there is a possibility -of a conflict between different uses of a property name. (For this -reason, it is a good idea to choose property names that are probably -unique, such as by beginning the property name with the program's usual -name-prefix for variables and functions.) An association list may be -used like a stack where associations are pushed on the front of the list -and later discarded; this is not possible with a property list. - -@node Symbol Plists -@subsection Property List Functions for Symbols - -@defun symbol-plist symbol -This function returns the property list of @var{symbol}. -@end defun - -@defun setplist symbol plist -This function sets @var{symbol}'s property list to @var{plist}. -Normally, @var{plist} should be a well-formed property list, but this is -not enforced. The return value is @var{plist}. - -@example -(setplist 'foo '(a 1 b (2 3) c nil)) - @result{} (a 1 b (2 3) c nil) -(symbol-plist 'foo) - @result{} (a 1 b (2 3) c nil) -@end example - -For symbols in special obarrays, which are not used for ordinary -purposes, it may make sense to use the property list cell in a -nonstandard fashion; in fact, the abbrev mechanism does so -(@pxref{Abbrevs}). -@end defun - -@defun get symbol property -This function finds the value of the property named @var{property} in -@var{symbol}'s property list. If there is no such property, @code{nil} -is returned. Thus, there is no distinction between a value of -@code{nil} and the absence of the property. - -The name @var{property} is compared with the existing property names -using @code{eq}, so any object is a legitimate property. - -See @code{put} for an example. -@end defun - -@defun put symbol property value -This function puts @var{value} onto @var{symbol}'s property list under -the property name @var{property}, replacing any previous property value. -The @code{put} function returns @var{value}. - -@example -(put 'fly 'verb 'transitive) - @result{}'transitive -(put 'fly 'noun '(a buzzing little bug)) - @result{} (a buzzing little bug) -(get 'fly 'verb) - @result{} transitive -(symbol-plist 'fly) - @result{} (verb transitive noun (a buzzing little bug)) -@end example -@end defun - -@node Other Plists -@subsection Property Lists Outside Symbols - - These functions are useful for manipulating property lists -not stored in symbols: - -@defun plist-get plist property -This returns the value of the @var{property} property stored in the -property list @var{plist}. It accepts a malformed @var{plist} -argument. If @var{property} is not found in the @var{plist}, it -returns @code{nil}. For example, - -@example -(plist-get '(foo 4) 'foo) - @result{} 4 -(plist-get '(foo 4 bad) 'foo) - @result{} 4 -(plist-get '(foo 4 bad) 'bad) - @result{} nil -(plist-get '(foo 4 bad) 'bar) - @result{} nil -@end example -@end defun - -@defun plist-put plist property value -This stores @var{value} as the value of the @var{property} property in -the property list @var{plist}. It may modify @var{plist} destructively, -or it may construct a new list structure without altering the old. The -function returns the modified property list, so you can store that back -in the place where you got @var{plist}. For example, - -@example -(setq my-plist '(bar t foo 4)) - @result{} (bar t foo 4) -(setq my-plist (plist-put my-plist 'foo 69)) - @result{} (bar t foo 69) -(setq my-plist (plist-put my-plist 'quux '(a))) - @result{} (bar t foo 69 quux (a)) -@end example -@end defun - - You could define @code{put} in terms of @code{plist-put} as follows: - -@example -(defun put (symbol prop value) - (setplist symbol - (plist-put (symbol-plist symbol) prop value))) -@end example - -@defun lax-plist-get plist property -Like @code{plist-get} except that it compares properties -using @code{equal} instead of @code{eq}. -@end defun - -@defun lax-plist-put plist property value -Like @code{plist-put} except that it compares properties -using @code{equal} instead of @code{eq}. -@end defun - -@defun plist-member plist property -This returns non-@code{nil} if @var{plist} contains the given -@var{property}. Unlike @code{plist-get}, this allows you to distinguish -between a missing property and a property with the value @code{nil}. -The value is actually the tail of @var{plist} whose @code{car} is -@var{property}. -@end defun diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi deleted file mode 100644 index af6243fd457..00000000000 --- a/doc/lispref/syntax.texi +++ /dev/null @@ -1,1224 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/syntax -@node Syntax Tables, Abbrevs, Searching and Matching, Top -@chapter Syntax Tables -@cindex parsing buffer text -@cindex syntax table -@cindex text parsing - - A @dfn{syntax table} specifies the syntactic role of each character -in a buffer. It can be used to determine where words, symbols, and -other syntactic constructs begin and end. This information is used by -many Emacs facilities, including Font Lock mode (@pxref{Font Lock -Mode}) and the various complex movement commands (@pxref{Motion}). - -@menu -* Basics: Syntax Basics. Basic concepts of syntax tables. -* Syntax Descriptors:: How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Syntax Properties:: Overriding syntax with text properties. -* Motion and Syntax:: Moving over characters with certain syntaxes. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. -* Categories:: Another way of classifying character syntax. -@end menu - -@node Syntax Basics -@section Syntax Table Concepts - - A syntax table is a char-table (@pxref{Char-Tables}). The element at -index @var{c} describes the character with code @var{c}. The element's -value should be a list that encodes the syntax of the character in -question. - - Syntax tables are used only for moving across text, not for the Emacs -Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp -expressions, and these rules cannot be changed. (Some Lisp systems -provide ways to redefine the read syntax, but we decided to leave this -feature out of Emacs Lisp for simplicity.) - - Each buffer has its own major mode, and each major mode has its own -idea of the syntactic class of various characters. For example, in -Lisp mode, the character @samp{;} begins a comment, but in C mode, it -terminates a statement. To support these variations, Emacs makes the -syntax table local to each buffer. Typically, each major mode has its -own syntax table and installs that table in each buffer that uses that -mode. Changing this table alters the syntax in all those buffers as -well as in any buffers subsequently put in that mode. Occasionally -several similar modes share one syntax table. @xref{Example Major -Modes}, for an example of how to set up a syntax table. - -A syntax table can inherit the data for some characters from the -standard syntax table, while specifying other characters itself. The -``inherit'' syntax class means ``inherit this character's syntax from -the standard syntax table''. Just changing the standard syntax for a -character affects all syntax tables that inherit from it. - -@defun syntax-table-p object -This function returns @code{t} if @var{object} is a syntax table. -@end defun - -@node Syntax Descriptors -@section Syntax Descriptors -@cindex syntax class - - The syntactic role of a character is called its @dfn{syntax class}. -Each syntax table specifies the syntax class of each character. There -is no necessary relationship between the class of a character in one -syntax table and its class in any other table. - - Each syntax class is designated by a mnemonic character, which -serves as the name of the class when you need to specify a class. -Usually, this designator character is one that is often assigned that -class; however, its meaning as a designator is unvarying and -independent of what syntax that character currently has. Thus, -@samp{\} as a designator character always means ``escape character'' -syntax, regardless of whether the @samp{\} character actually has that -syntax in the current syntax table. -@ifnottex -@xref{Syntax Class Table}, for a list of syntax classes. -@end ifnottex - -@cindex syntax descriptor - A @dfn{syntax descriptor} is a Lisp string that describes the syntax -classes and other syntactic properties of a character. When you want -to modify the syntax of a character, that is done by calling the -function @code{modify-syntax-entry} and passing a syntax descriptor as -one of its arguments (@pxref{Syntax Table Functions}). - - The first character in a syntax descriptor designates the syntax -class. The second character specifies a matching character (e.g.@: in -Lisp, the matching character for @samp{(} is @samp{)}); if there is no -matching character, put a space there. Then come the characters for -any desired flags. - - If no matching character or flags are needed, only one character -(specifying the syntax class) is sufficient. - - For example, the syntax descriptor for the character @samp{*} in C -mode is @code{". 23"} (i.e., punctuation, matching character slot -unused, second character of a comment-starter, first character of a -comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e., -punctuation, matching character slot unused, first character of a -comment-starter, second character of a comment-ender). - -@menu -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. -@end menu - -@node Syntax Class Table -@subsection Table of Syntax Classes - - Here is a table of syntax classes, the characters that designate -them, their meanings, and examples of their use. - -@table @asis -@item Whitespace characters: @samp{@ } or @samp{-} -Characters that separate symbols and words from each other. -Typically, whitespace characters have no other syntactic significance, -and multiple whitespace characters are syntactically equivalent to a -single one. Space, tab, and formfeed are classified as whitespace in -almost all major modes. - -This syntax class can be designated by either @w{@samp{@ }} or -@samp{-}. Both designators are equivalent. - -@item Word constituents: @samp{w} -Parts of words in human languages. These are typically used in -variable and command names in programs. All upper- and lower-case -letters, and the digits, are typically word constituents. - -@item Symbol constituents: @samp{_} -Extra characters used in variable and command names along with word -constituents. Examples include the characters @samp{$&*+-_<>} in Lisp -mode, which may be part of a symbol name even though they are not part -of English words. In standard C, the only non-word-constituent -character that is valid in symbols is underscore (@samp{_}). - -@item Punctuation characters: @samp{.} -Characters used as punctuation in a human language, or used in a -programming language to separate symbols from one another. Some -programming language modes, such as Emacs Lisp mode, have no -characters in this class since the few characters that are not symbol -or word constituents all have other uses. Other programming language -modes, such as C mode, use punctuation syntax for operators. - -@item Open parenthesis characters: @samp{(} -@itemx Close parenthesis characters: @samp{)} -Characters used in dissimilar pairs to surround sentences or -expressions. Such a grouping is begun with an open parenthesis -character and terminated with a close. Each open parenthesis -character matches a particular close parenthesis character, and vice -versa. Normally, Emacs indicates momentarily the matching open -parenthesis when you insert a close parenthesis. @xref{Blinking}. - -In human languages, and in C code, the parenthesis pairs are -@samp{()}, @samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters -for lists and vectors (@samp{()} and @samp{[]}) are classified as -parenthesis characters. - -@item String quotes: @samp{"} -Characters used to delimit string constants. The same string quote -character appears at the beginning and the end of a string. Such -quoted strings do not nest. - -The parsing facilities of Emacs consider a string as a single token. -The usual syntactic meanings of the characters in the string are -suppressed. - -The Lisp modes have two string quote characters: double-quote (@samp{"}) -and vertical bar (@samp{|}). @samp{|} is not used in Emacs Lisp, but it -is used in Common Lisp. C also has two string quote characters: -double-quote for strings, and single-quote (@samp{'}) for character -constants. - -Human text has no string quote characters. We do not want quotation -marks to turn off the usual syntactic properties of other characters -in the quotation. - -@item Escape-syntax characters: @samp{\} -Characters that start an escape sequence, such as is used in string -and character constants. The character @samp{\} belongs to this class -in both C and Lisp. (In C, it is used thus only inside strings, but -it turns out to cause no trouble to treat it this way throughout C -code.) - -Characters in this class count as part of words if -@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}. - -@item Character quotes: @samp{/} -Characters used to quote the following character so that it loses its -normal syntactic meaning. This differs from an escape character in -that only the character immediately following is ever affected. - -Characters in this class count as part of words if -@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}. - -This class is used for backslash in @TeX{} mode. - -@item Paired delimiters: @samp{$} -Similar to string quote characters, except that the syntactic -properties of the characters between the delimiters are not -suppressed. Only @TeX{} mode uses a paired delimiter presently---the -@samp{$} that both enters and leaves math mode. - -@item Expression prefixes: @samp{'} -Characters used for syntactic operators that are considered as part of -an expression if they appear next to one. In Lisp modes, these -characters include the apostrophe, @samp{'} (used for quoting), the -comma, @samp{,} (used in macros), and @samp{#} (used in the read -syntax for certain data types). - -@item Comment starters: @samp{<} -@itemx Comment enders: @samp{>} -@cindex comment syntax -Characters used in various languages to delimit comments. Human text -has no comment characters. In Lisp, the semicolon (@samp{;}) starts a -comment and a newline or formfeed ends one. - -@item Inherit standard syntax: @samp{@@} -This syntax class does not specify a particular syntax. It says to -look in the standard syntax table to find the syntax of this -character. - -@item Generic comment delimiters: @samp{!} -Characters that start or end a special kind of comment. @emph{Any} -generic comment delimiter matches @emph{any} generic comment -delimiter, but they cannot match a comment starter or comment ender; -generic comment delimiters can only match each other. - -This syntax class is primarily meant for use with the -@code{syntax-table} text property (@pxref{Syntax Properties}). You -can mark any range of characters as forming a comment, by giving the -first and last characters of the range @code{syntax-table} properties -identifying them as generic comment delimiters. - -@item Generic string delimiters: @samp{|} -Characters that start or end a string. This class differs from the -string quote class in that @emph{any} generic string delimiter can -match any other generic string delimiter; but they do not match -ordinary string quote characters. - -This syntax class is primarily meant for use with the -@code{syntax-table} text property (@pxref{Syntax Properties}). You -can mark any range of characters as forming a string constant, by -giving the first and last characters of the range @code{syntax-table} -properties identifying them as generic string delimiters. -@end table - -@node Syntax Flags -@subsection Syntax Flags -@cindex syntax flags - - In addition to the classes, entries for characters in a syntax table -can specify flags. There are eight possible flags, represented by the -characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b}, @samp{c}, -@samp{n}, and @samp{p}. - - All the flags except @samp{p} are used to describe comment -delimiters. The digit flags are used for comment delimiters made up -of 2 characters. They indicate that a character can @emph{also} be -part of a comment sequence, in addition to the syntactic properties -associated with its character class. The flags are independent of the -class and each other for the sake of characters such as @samp{*} in -C mode, which is a punctuation character, @emph{and} the second -character of a start-of-comment sequence (@samp{/*}), @emph{and} the -first character of an end-of-comment sequence (@samp{*/}). The flags -@samp{b}, @samp{c}, and @samp{n} are used to qualify the corresponding -comment delimiter. - - Here is a table of the possible flags for a character @var{c}, -and what they mean: - -@itemize @bullet -@item -@samp{1} means @var{c} is the start of a two-character comment-start -sequence. - -@item -@samp{2} means @var{c} is the second character of such a sequence. - -@item -@samp{3} means @var{c} is the start of a two-character comment-end -sequence. - -@item -@samp{4} means @var{c} is the second character of such a sequence. - -@item -@samp{b} means that @var{c} as a comment delimiter belongs to the -alternative ``b'' comment style. For a two-character comment starter, -this flag is only significant on the second char, and for a 2-character -comment ender it is only significant on the first char. - -@item -@samp{c} means that @var{c} as a comment delimiter belongs to the -alternative ``c'' comment style. For a two-character comment -delimiter, @samp{c} on either character makes it of style ``c''. - -@item -@samp{n} on a comment delimiter character specifies -that this kind of comment can be nested. For a two-character -comment delimiter, @samp{n} on either character makes it -nestable. - -Emacs supports several comment styles simultaneously in any one syntax -table. A comment style is a set of flags @samp{b}, @samp{c}, and -@samp{n}, so there can be up to 8 different comment styles. -Each comment delimiter has a style and only matches comment delimiters -of the same style. Thus if a comment starts with the comment-start -sequence of style ``bn'', it will extend until the next matching -comment-end sequence of style ``bn''. - -The appropriate comment syntax settings for C++ can be as follows: - -@table @asis -@item @samp{/} -@samp{124} -@item @samp{*} -@samp{23b} -@item newline -@samp{>} -@end table - -This defines four comment-delimiting sequences: - -@table @asis -@item @samp{/*} -This is a comment-start sequence for ``b'' style because the -second character, @samp{*}, has the @samp{b} flag. - -@item @samp{//} -This is a comment-start sequence for ``a'' style because the second -character, @samp{/}, does not have the @samp{b} flag. - -@item @samp{*/} -This is a comment-end sequence for ``b'' style because the first -character, @samp{*}, has the @samp{b} flag. - -@item newline -This is a comment-end sequence for ``a'' style, because the newline -character does not have the @samp{b} flag. -@end table - -@item -@c Emacs 19 feature -@samp{p} identifies an additional ``prefix character'' for Lisp syntax. -These characters are treated as whitespace when they appear between -expressions. When they appear within an expression, they are handled -according to their usual syntax classes. - -The function @code{backward-prefix-chars} moves back over these -characters, as well as over characters whose primary syntax class is -prefix (@samp{'}). @xref{Motion and Syntax}. -@end itemize - -@node Syntax Table Functions -@section Syntax Table Functions - - In this section we describe functions for creating, accessing and -altering syntax tables. - -@defun make-syntax-table &optional table -This function creates a new syntax table, with all values initialized -to @code{nil}. If @var{table} is non-@code{nil}, it becomes the -parent of the new syntax table, otherwise the standard syntax table is -the parent. Like all char-tables, a syntax table inherits from its -parent. Thus the original syntax of all characters in the returned -syntax table is determined by the parent. @xref{Char-Tables}. - -Most major mode syntax tables are created in this way. -@end defun - -@defun copy-syntax-table &optional table -This function constructs a copy of @var{table} and returns it. If -@var{table} is not supplied (or is @code{nil}), it returns a copy of the -standard syntax table. Otherwise, an error is signaled if @var{table} is -not a syntax table. -@end defun - -@deffn Command modify-syntax-entry char syntax-descriptor &optional table -This function sets the syntax entry for @var{char} according to -@var{syntax-descriptor}. @var{char} must be a character, or a cons -cell of the form @code{(@var{min} . @var{max})}; in the latter case, -the function sets the syntax entries for all characters in the range -between @var{min} and @var{max}, inclusive. - -The syntax is changed only for @var{table}, which defaults to the -current buffer's syntax table, and not in any other syntax table. - -The argument @var{syntax-descriptor} is a syntax descriptor for the -desired syntax (i.e.@: a string beginning with a class designator -character, and optionally containing a matching character and syntax -flags). An error is signaled if the first character is not one of the -seventeen syntax class designators. @xref{Syntax Descriptors}. - -This function always returns @code{nil}. The old syntax information in -the table for this character is discarded. - -@example -@group -@exdent @r{Examples:} - -;; @r{Put the space character in class whitespace.} -(modify-syntax-entry ?\s " ") - @result{} nil -@end group - -@group -;; @r{Make @samp{$} an open parenthesis character,} -;; @r{with @samp{^} as its matching close.} -(modify-syntax-entry ?$ "(^") - @result{} nil -@end group - -@group -;; @r{Make @samp{^} a close parenthesis character,} -;; @r{with @samp{$} as its matching open.} -(modify-syntax-entry ?^ ")$") - @result{} nil -@end group - -@group -;; @r{Make @samp{/} a punctuation character,} -;; @r{the first character of a start-comment sequence,} -;; @r{and the second character of an end-comment sequence.} -;; @r{This is used in C mode.} -(modify-syntax-entry ?/ ". 14") - @result{} nil -@end group -@end example -@end deffn - -@defun char-syntax character -This function returns the syntax class of @var{character}, represented -by its mnemonic designator character. This returns @emph{only} the -class, not any matching parenthesis or flags. - -An error is signaled if @var{char} is not a character. - -The following examples apply to C mode. The first example shows that -the syntax class of space is whitespace (represented by a space). The -second example shows that the syntax of @samp{/} is punctuation. This -does not show the fact that it is also part of comment-start and -end -sequences. The third example shows that open parenthesis is in the class -of open parentheses. This does not show the fact that it has a matching -character, @samp{)}. - -@example -@group -(string (char-syntax ?\s)) - @result{} " " -@end group - -@group -(string (char-syntax ?/)) - @result{} "." -@end group - -@group -(string (char-syntax ?\()) - @result{} "(" -@end group -@end example - -We use @code{string} to make it easier to see the character returned by -@code{char-syntax}. -@end defun - -@defun set-syntax-table table -This function makes @var{table} the syntax table for the current buffer. -It returns @var{table}. -@end defun - -@defun syntax-table -This function returns the current syntax table, which is the table for -the current buffer. -@end defun - -@defmac with-syntax-table @var{table} @var{body}@dots{} -This macro executes @var{body} using @var{table} as the current syntax -table. It returns the value of the last form in @var{body}, after -restoring the old current syntax table. - -Since each buffer has its own current syntax table, we should make that -more precise: @code{with-syntax-table} temporarily alters the current -syntax table of whichever buffer is current at the time the macro -execution starts. Other buffers are not affected. -@end defmac - -@node Syntax Properties -@section Syntax Properties -@kindex syntax-table @r{(text property)} - -When the syntax table is not flexible enough to specify the syntax of -a language, you can override the syntax table for specific character -occurrences in the buffer, by applying a @code{syntax-table} text -property. @xref{Text Properties}, for how to apply text properties. - - The valid values of @code{syntax-table} text property are: - -@table @asis -@item @var{syntax-table} -If the property value is a syntax table, that table is used instead of -the current buffer's syntax table to determine the syntax for the -underlying text character. - -@item @code{(@var{syntax-code} . @var{matching-char})} -A cons cell of this format specifies the syntax for the underlying -text character. (@pxref{Syntax Table Internals}) - -@item @code{nil} -If the property is @code{nil}, the character's syntax is determined from -the current syntax table in the usual way. -@end table - -@defvar parse-sexp-lookup-properties -If this is non-@code{nil}, the syntax scanning functions, like -@code{forward-sexp}, pay attention to syntax text properties. -Otherwise they use only the current syntax table. -@end defvar - -@defvar syntax-propertize-function -This variable, if non-@code{nil}, should store a function for applying -@code{syntax-table} properties to a specified stretch of text. It is -intended to be used by major modes to install a function which applies -@code{syntax-table} properties in some mode-appropriate way. - -The function is called by @code{syntax-ppss} (@pxref{Position Parse}), -and by Font Lock mode during syntactic fontification (@pxref{Syntactic -Font Lock}). It is called with two arguments, @var{start} and -@var{end}, which are the starting and ending positions of the text on -which it should act. It is allowed to call @code{syntax-ppss} on any -position before @var{end}. However, it should not call -@code{syntax-ppss-flush-cache}; so, it is not allowed to call -@code{syntax-ppss} on some position and later modify the buffer at an -earlier position. -@end defvar - -@defvar syntax-propertize-extend-region-functions -This abnormal hook is run by the syntax parsing code prior to calling -@code{syntax-propertize-function}. Its role is to help locate safe -starting and ending buffer positions for passing to -@code{syntax-propertize-function}. For example, a major mode can add -a function to this hook to identify multi-line syntactic constructs, -and ensure that the boundaries do not fall in the middle of one. - -Each function in this hook should accept two arguments, @var{start} -and @var{end}. It should return either a cons cell of two adjusted -buffer positions, @code{(@var{new-start} . @var{new-end})}, or -@code{nil} if no adjustment is necessary. The hook functions are run -in turn, repeatedly, until they all return @code{nil}. -@end defvar - -@node Motion and Syntax -@section Motion and Syntax - - This section describes functions for moving across characters that -have certain syntax classes. - -@defun skip-syntax-forward syntaxes &optional limit -This function moves point forward across characters having syntax -classes mentioned in @var{syntaxes} (a string of syntax class -characters). It stops when it encounters the end of the buffer, or -position @var{limit} (if specified), or a character it is not supposed -to skip. - -If @var{syntaxes} starts with @samp{^}, then the function skips -characters whose syntax is @emph{not} in @var{syntaxes}. - -The return value is the distance traveled, which is a nonnegative -integer. -@end defun - -@defun skip-syntax-backward syntaxes &optional limit -This function moves point backward across characters whose syntax -classes are mentioned in @var{syntaxes}. It stops when it encounters -the beginning of the buffer, or position @var{limit} (if specified), or -a character it is not supposed to skip. - -If @var{syntaxes} starts with @samp{^}, then the function skips -characters whose syntax is @emph{not} in @var{syntaxes}. - -The return value indicates the distance traveled. It is an integer that -is zero or less. -@end defun - -@defun backward-prefix-chars -This function moves point backward over any number of characters with -expression prefix syntax. This includes both characters in the -expression prefix syntax class, and characters with the @samp{p} flag. -@end defun - -@node Parsing Expressions -@section Parsing Expressions - - This section describes functions for parsing and scanning balanced -expressions. We will refer to such expressions as @dfn{sexps}, -following the terminology of Lisp, even though these functions can act -on languages other than Lisp. Basically, a sexp is either a balanced -parenthetical grouping, a string, or a ``symbol'' (i.e.@: a sequence -of characters whose syntax is either word constituent or symbol -constituent). However, characters in the expression prefix syntax -class (@pxref{Syntax Class Table}) are treated as part of the sexp if -they appear next to it. - - The syntax table controls the interpretation of characters, so these -functions can be used for Lisp expressions when in Lisp mode and for C -expressions when in C mode. @xref{List Motion}, for convenient -higher-level functions for moving over balanced expressions. - - A character's syntax controls how it changes the state of the -parser, rather than describing the state itself. For example, a -string delimiter character toggles the parser state between -``in-string'' and ``in-code'', but the syntax of characters does not -directly say whether they are inside a string. For example (note that -15 is the syntax code for generic string delimiters), - -@example -(put-text-property 1 9 'syntax-table '(15 . nil)) -@end example - -@noindent -does not tell Emacs that the first eight chars of the current buffer -are a string, but rather that they are all string delimiters. As a -result, Emacs treats them as four consecutive empty string constants. - -@menu -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. -@end menu - -@node Motion via Parsing -@subsection Motion Commands Based on Parsing - - This section describes simple point-motion functions that operate -based on parsing expressions. - -@defun scan-lists from count depth -This function scans forward @var{count} balanced parenthetical -groupings from position @var{from}. It returns the position where the -scan stops. If @var{count} is negative, the scan moves backwards. - -If @var{depth} is nonzero, treat the starting position as being -@var{depth} parentheses deep. The scanner moves forward or backward -through the buffer until the depth changes to zero @var{count} times. -Hence, a positive value for @var{depth} has the effect of moving out -@var{depth} levels of parenthesis from the starting position, while a -negative @var{depth} has the effect of moving deeper by @var{-depth} -levels of parenthesis. - -Scanning ignores comments if @code{parse-sexp-ignore-comments} is -non-@code{nil}. - -If the scan reaches the beginning or end of the accessible part of the -buffer before it has scanned over @var{count} parenthetical groupings, -the return value is @code{nil} if the depth at that point is zero; if -the depth is non-zero, a @code{scan-error} error is signaled. -@end defun - -@defun scan-sexps from count -This function scans forward @var{count} sexps from position @var{from}. -It returns the position where the scan stops. If @var{count} is -negative, the scan moves backwards. - -Scanning ignores comments if @code{parse-sexp-ignore-comments} is -non-@code{nil}. - -If the scan reaches the beginning or end of (the accessible part of) the -buffer while in the middle of a parenthetical grouping, an error is -signaled. If it reaches the beginning or end between groupings but -before count is used up, @code{nil} is returned. -@end defun - -@defun forward-comment count -This function moves point forward across @var{count} complete comments - (that is, including the starting delimiter and the terminating -delimiter if any), plus any whitespace encountered on the way. It -moves backward if @var{count} is negative. If it encounters anything -other than a comment or whitespace, it stops, leaving point at the -place where it stopped. This includes (for instance) finding the end -of a comment when moving forward and expecting the beginning of one. -The function also stops immediately after moving over the specified -number of complete comments. If @var{count} comments are found as -expected, with nothing except whitespace between them, it returns -@code{t}; otherwise it returns @code{nil}. - -This function cannot tell whether the ``comments'' it traverses are -embedded within a string. If they look like comments, it treats them -as comments. - -To move forward over all comments and whitespace following point, use -@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a -good argument to use, because the number of comments in the buffer -cannot exceed that many. -@end defun - -@node Position Parse -@subsection Finding the Parse State for a Position - - For syntactic analysis, such as in indentation, often the useful -thing is to compute the syntactic state corresponding to a given buffer -position. This function does that conveniently. - -@defun syntax-ppss &optional pos -This function returns the parser state that the parser would reach at -position @var{pos} starting from the beginning of the buffer. -@iftex -See the next section for -@end iftex -@ifnottex -@xref{Parser State}, -@end ifnottex -for a description of the parser state. - -The return value is the same as if you call the low-level parsing -function @code{parse-partial-sexp} to parse from the beginning of the -buffer to @var{pos} (@pxref{Low-Level Parsing}). However, -@code{syntax-ppss} uses a cache to speed up the computation. Due to -this optimization, the second value (previous complete subexpression) -and sixth value (minimum parenthesis depth) in the returned parser -state are not meaningful. - -This function has a side effect: it adds a buffer-local entry to -@code{before-change-functions} (@pxref{Change Hooks}) for -@code{syntax-ppss-flush-cache} (see below). This entry keeps the -cache consistent as the buffer is modified. However, the cache might -not be updated if @code{syntax-ppss} is called while -@code{before-change-functions} is temporarily let-bound, or if the -buffer is modified without running the hook, such as when using -@code{inhibit-modification-hooks}. In those cases, it is necessary to -call @code{syntax-ppss-flush-cache} explicitly. -@end defun - -@defun syntax-ppss-flush-cache beg &rest ignored-args -This function flushes the cache used by @code{syntax-ppss}, starting -at position @var{beg}. The remaining arguments, @var{ignored-args}, -are ignored; this function accepts them so that it can be directly -used on hooks such as @code{before-change-functions} (@pxref{Change -Hooks}). -@end defun - - Major modes can make @code{syntax-ppss} run faster by specifying -where it needs to start parsing. - -@defvar syntax-begin-function -If this is non-@code{nil}, it should be a function that moves to an -earlier buffer position where the parser state is equivalent to -@code{nil}---in other words, a position outside of any comment, -string, or parenthesis. @code{syntax-ppss} uses it to further -optimize its computations, when the cache gives no help. -@end defvar - -@node Parser State -@subsection Parser State -@cindex parser state - - A @dfn{parser state} is a list of ten elements describing the state -of the syntactic parser, after it parses the text between a specified -starting point and a specified end point in the buffer. Parsing -functions such as @code{syntax-ppss} -@ifnottex -(@pxref{Position Parse}) -@end ifnottex -return a parser state as the value. Some parsing functions accept a -parser state as an argument, for resuming parsing. - - Here are the meanings of the elements of the parser state: - -@enumerate 0 -@item -The depth in parentheses, counting from 0. @strong{Warning:} this can -be negative if there are more close parens than open parens between -the parser's starting point and end point. - -@item -@cindex innermost containing parentheses -The character position of the start of the innermost parenthetical -grouping containing the stopping point; @code{nil} if none. - -@item -@cindex previous complete subexpression -The character position of the start of the last complete subexpression -terminated; @code{nil} if none. - -@item -@cindex inside string -Non-@code{nil} if inside a string. More precisely, this is the -character that will terminate the string, or @code{t} if a generic -string delimiter character should terminate it. - -@item -@cindex inside comment -@code{t} if inside a non-nestable comment (of any comment style; -@pxref{Syntax Flags}); or the comment nesting level if inside a -comment that can be nested. - -@item -@cindex quote character -@code{t} if the end point is just after a quote character. - -@item -The minimum parenthesis depth encountered during this scan. - -@item -What kind of comment is active: @code{nil} if not in a comment or in a -comment of style @samp{a}; 1 for a comment of style @samp{b}; 2 for a -comment of style @samp{c}; and @code{syntax-table} for a comment that -should be ended by a generic comment delimiter character. - -@item -The string or comment start position. While inside a comment, this is -the position where the comment began; while inside a string, this is the -position where the string began. When outside of strings and comments, -this element is @code{nil}. - -@item -Internal data for continuing the parsing. The meaning of this -data is subject to change; it is used if you pass this list -as the @var{state} argument to another call. -@end enumerate - - Elements 1, 2, and 6 are ignored in a state which you pass as an -argument to continue parsing, and elements 8 and 9 are used only in -trivial cases. Those elements are mainly used internally by the -parser code. - - One additional piece of useful information is available from a -parser state using this function: - -@defun syntax-ppss-toplevel-pos state -This function extracts, from parser state @var{state}, the last -position scanned in the parse which was at top level in grammatical -structure. ``At top level'' means outside of any parentheses, -comments, or strings. - -The value is @code{nil} if @var{state} represents a parse which has -arrived at a top level position. -@end defun - -@node Low-Level Parsing -@subsection Low-Level Parsing - - The most basic way to use the expression parser is to tell it -to start at a given position with a certain state, and parse up to -a specified end position. - -@defun parse-partial-sexp start limit &optional target-depth stop-before state stop-comment -This function parses a sexp in the current buffer starting at -@var{start}, not scanning past @var{limit}. It stops at position -@var{limit} or when certain criteria described below are met, and sets -point to the location where parsing stops. It returns a parser state -describing the status of the parse at the point where it stops. - -@cindex parenthesis depth -If the third argument @var{target-depth} is non-@code{nil}, parsing -stops if the depth in parentheses becomes equal to @var{target-depth}. -The depth starts at 0, or at whatever is given in @var{state}. - -If the fourth argument @var{stop-before} is non-@code{nil}, parsing -stops when it comes to any character that starts a sexp. If -@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the -start of a comment. If @var{stop-comment} is the symbol -@code{syntax-table}, parsing stops after the start of a comment or a -string, or the end of a comment or a string, whichever comes first. - -If @var{state} is @code{nil}, @var{start} is assumed to be at the top -level of parenthesis structure, such as the beginning of a function -definition. Alternatively, you might wish to resume parsing in the -middle of the structure. To do this, you must provide a @var{state} -argument that describes the initial status of parsing. The value -returned by a previous call to @code{parse-partial-sexp} will do -nicely. -@end defun - -@node Control Parsing -@subsection Parameters to Control Parsing - -@defvar multibyte-syntax-as-symbol -If this variable is non-@code{nil}, @code{scan-sexps} treats all -non-@acronym{ASCII} characters as symbol constituents regardless -of what the syntax table says about them. (However, text properties -can still override the syntax.) -@end defvar - -@defopt parse-sexp-ignore-comments -@cindex skipping comments -If the value is non-@code{nil}, then comments are treated as -whitespace by the functions in this section and by @code{forward-sexp}, -@code{scan-lists} and @code{scan-sexps}. -@end defopt - -@vindex parse-sexp-lookup-properties -The behavior of @code{parse-partial-sexp} is also affected by -@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}). - -You can use @code{forward-comment} to move forward or backward over -one comment or several comments. - -@node Standard Syntax Tables -@section Some Standard Syntax Tables - - Most of the major modes in Emacs have their own syntax tables. Here -are several of them: - -@defun standard-syntax-table -This function returns the standard syntax table, which is the syntax -table used in Fundamental mode. -@end defun - -@defvar text-mode-syntax-table -The value of this variable is the syntax table used in Text mode. -@end defvar - -@defvar c-mode-syntax-table -The value of this variable is the syntax table for C-mode buffers. -@end defvar - -@defvar emacs-lisp-mode-syntax-table -The value of this variable is the syntax table used in Emacs Lisp mode -by editing commands. (It has no effect on the Lisp @code{read} -function.) -@end defvar - -@node Syntax Table Internals -@section Syntax Table Internals -@cindex syntax table internals - - Lisp programs don't usually work with the elements directly; the -Lisp-level syntax table functions usually work with syntax descriptors -(@pxref{Syntax Descriptors}). Nonetheless, here we document the -internal format. This format is used mostly when manipulating -syntax properties. - - Each element of a syntax table is a cons cell of the form -@code{(@var{syntax-code} . @var{matching-char})}. The @sc{car}, -@var{syntax-code}, is an integer that encodes the syntax class, and any -flags. The @sc{cdr}, @var{matching-char}, is non-@code{nil} if -a character to match was specified. - - This table gives the value of @var{syntax-code} which corresponds -to each syntactic type. - -@multitable @columnfractions .05 .3 .3 .31 -@item -@tab -@i{Integer} @i{Class} -@tab -@i{Integer} @i{Class} -@tab -@i{Integer} @i{Class} -@item -@tab -0 @ @ whitespace -@tab -5 @ @ close parenthesis -@tab -10 @ @ character quote -@item -@tab -1 @ @ punctuation -@tab -6 @ @ expression prefix -@tab -11 @ @ comment-start -@item -@tab -2 @ @ word -@tab -7 @ @ string quote -@tab -12 @ @ comment-end -@item -@tab -3 @ @ symbol -@tab -8 @ @ paired delimiter -@tab -13 @ @ inherit -@item -@tab -4 @ @ open parenthesis -@tab -9 @ @ escape -@tab -14 @ @ generic comment -@item -@tab -15 @ generic string -@end multitable - - For example, the usual syntax value for @samp{(} is @code{(4 . 41)}. -(41 is the character code for @samp{)}.) - - The flags are encoded in higher order bits, starting 16 bits from the -least significant bit. This table gives the power of two which -corresponds to each syntax flag. - -@multitable @columnfractions .05 .3 .3 .3 -@item -@tab -@i{Prefix} @i{Flag} -@tab -@i{Prefix} @i{Flag} -@tab -@i{Prefix} @i{Flag} -@item -@tab -@samp{1} @ @ @code{(lsh 1 16)} -@tab -@samp{4} @ @ @code{(lsh 1 19)} -@tab -@samp{b} @ @ @code{(lsh 1 21)} -@item -@tab -@samp{2} @ @ @code{(lsh 1 17)} -@tab -@samp{p} @ @ @code{(lsh 1 20)} -@tab -@samp{n} @ @ @code{(lsh 1 22)} -@item -@tab -@samp{3} @ @ @code{(lsh 1 18)} -@end multitable - -@defun string-to-syntax @var{desc} -This function returns the internal form corresponding to the syntax -descriptor @var{desc}, a cons cell @code{(@var{syntax-code} -. @var{matching-char})}. -@end defun - -@defun syntax-after pos -This function returns the syntax code of the character in the buffer -after position @var{pos}, taking account of syntax properties as well -as the syntax table. If @var{pos} is outside the buffer's accessible -portion (@pxref{Narrowing, accessible portion}), this function returns -@code{nil}. -@end defun - -@defun syntax-class syntax -This function returns the syntax class of the syntax code -@var{syntax}. (It masks off the high 16 bits that hold the flags -encoded in the syntax descriptor.) If @var{syntax} is @code{nil}, it -returns @code{nil}; this is so evaluating the expression - -@example -(syntax-class (syntax-after pos)) -@end example - -@noindent -where @code{pos} is outside the buffer's accessible portion, will -yield @code{nil} without throwing errors or producing wrong syntax -class codes. -@end defun - -@node Categories -@section Categories -@cindex categories of characters -@cindex character categories - - @dfn{Categories} provide an alternate way of classifying characters -syntactically. You can define several categories as needed, then -independently assign each character to one or more categories. Unlike -syntax classes, categories are not mutually exclusive; it is normal for -one character to belong to several categories. - -@cindex category table - Each buffer has a @dfn{category table} which records which categories -are defined and also which characters belong to each category. Each -category table defines its own categories, but normally these are -initialized by copying from the standard categories table, so that the -standard categories are available in all modes. - - Each category has a name, which is an @acronym{ASCII} printing character in -the range @w{@samp{ }} to @samp{~}. You specify the name of a category -when you define it with @code{define-category}. - - The category table is actually a char-table (@pxref{Char-Tables}). -The element of the category table at index @var{c} is a @dfn{category -set}---a bool-vector---that indicates which categories character @var{c} -belongs to. In this category set, if the element at index @var{cat} is -@code{t}, that means category @var{cat} is a member of the set, and that -character @var{c} belongs to category @var{cat}. - -For the next three functions, the optional argument @var{table} -defaults to the current buffer's category table. - -@defun define-category char docstring &optional table -This function defines a new category, with name @var{char} and -documentation @var{docstring}, for the category table @var{table}. - -Here's an example of defining a new category for characters that have -strong right-to-left directionality (@pxref{Bidirectional Display}) -and using it in a special category table: - -@example -(defvar special-category-table-for-bidi - (let ((category-table (make-category-table)) - (uniprop-table (unicode-property-table-internal 'bidi-class))) - (define-category ?R "Characters of bidi-class R, AL, or RLO" - category-table) - (map-char-table - #'(lambda (key val) - (if (memq val '(R AL RLO)) - (modify-category-entry key ?R category-table))) - uniprop-table) - category-table)) -@end example -@end defun - -@defun category-docstring category &optional table -This function returns the documentation string of category @var{category} -in category table @var{table}. - -@example -(category-docstring ?a) - @result{} "ASCII" -(category-docstring ?l) - @result{} "Latin" -@end example -@end defun - -@defun get-unused-category &optional table -This function returns a category name (a character) which is not -currently defined in @var{table}. If all possible categories are in use -in @var{table}, it returns @code{nil}. -@end defun - -@defun category-table -This function returns the current buffer's category table. -@end defun - -@defun category-table-p object -This function returns @code{t} if @var{object} is a category table, -otherwise @code{nil}. -@end defun - -@defun standard-category-table -This function returns the standard category table. -@end defun - -@defun copy-category-table &optional table -This function constructs a copy of @var{table} and returns it. If -@var{table} is not supplied (or is @code{nil}), it returns a copy of the -standard category table. Otherwise, an error is signaled if @var{table} -is not a category table. -@end defun - -@defun set-category-table table -This function makes @var{table} the category table for the current -buffer. It returns @var{table}. -@end defun - -@defun make-category-table -This creates and returns an empty category table. In an empty category -table, no categories have been allocated, and no characters belong to -any categories. -@end defun - -@defun make-category-set categories -This function returns a new category set---a bool-vector---whose initial -contents are the categories listed in the string @var{categories}. The -elements of @var{categories} should be category names; the new category -set has @code{t} for each of those categories, and @code{nil} for all -other categories. - -@example -(make-category-set "al") - @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0" -@end example -@end defun - -@defun char-category-set char -This function returns the category set for character @var{char} in the -current buffer's category table. This is the bool-vector which -records which categories the character @var{char} belongs to. The -function @code{char-category-set} does not allocate storage, because -it returns the same bool-vector that exists in the category table. - -@example -(char-category-set ?a) - @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0" -@end example -@end defun - -@defun category-set-mnemonics category-set -This function converts the category set @var{category-set} into a string -containing the characters that designate the categories that are members -of the set. - -@example -(category-set-mnemonics (char-category-set ?a)) - @result{} "al" -@end example -@end defun - -@defun modify-category-entry char category &optional table reset -This function modifies the category set of @var{char} in category -table @var{table} (which defaults to the current buffer's category -table). @var{char} can be a character, or a cons cell of the form -@code{(@var{min} . @var{max})}; in the latter case, the function -modifies the category sets of all characters in the range between -@var{min} and @var{max}, inclusive. - -Normally, it modifies a category set by adding @var{category} to it. -But if @var{reset} is non-@code{nil}, then it deletes @var{category} -instead. -@end defun - -@deffn Command describe-categories &optional buffer-or-name -This function describes the category specifications in the current -category table. It inserts the descriptions in a buffer, and then -displays that buffer. If @var{buffer-or-name} is non-@code{nil}, it -describes the category table of that buffer instead. -@end deffn diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi deleted file mode 100644 index 1963d2519a3..00000000000 --- a/doc/lispref/text.texi +++ /dev/null @@ -1,4385 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/text -@node Text, Non-ASCII Characters, Markers, Top -@chapter Text -@cindex text - - This chapter describes the functions that deal with the text in a -buffer. Most examine, insert, or delete text in the current buffer, -often operating at point or on text adjacent to point. Many are -interactive. All the functions that change the text provide for undoing -the changes (@pxref{Undo}). - - Many text-related functions operate on a region of text defined by two -buffer positions passed in arguments named @var{start} and @var{end}. -These arguments should be either markers (@pxref{Markers}) or numeric -character positions (@pxref{Positions}). The order of these arguments -does not matter; it is all right for @var{start} to be the end of the -region and @var{end} the beginning. For example, @code{(delete-region 1 -10)} and @code{(delete-region 10 1)} are equivalent. An -@code{args-out-of-range} error is signaled if either @var{start} or -@var{end} is outside the accessible portion of the buffer. In an -interactive call, point and the mark are used for these arguments. - -@cindex buffer contents - Throughout this chapter, ``text'' refers to the characters in the -buffer, together with their properties (when relevant). Keep in mind -that point is always between two characters, and the cursor appears on -the character after point. - -@menu -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* Comparing Text:: Comparing substrings of buffers. -* Insertion:: Adding new text to a buffer. -* Commands for Insertion:: User-level commands to insert text. -* Deletion:: Removing text from a buffer. -* User-Level Deletion:: User-level commands to delete text. -* The Kill Ring:: Where removed text sometimes is saved for later use. -* Undo:: Undoing changes to the text of a buffer. -* Maintaining Undo:: How to enable and disable undo information. - How to control how much information is kept. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Sorting:: Functions for sorting parts of the buffer. -* Columns:: Computing horizontal positions, and using them. -* Indentation:: Functions to insert or adjust indentation. -* Case Changes:: Case conversion of parts of the buffer. -* Text Properties:: Assigning Lisp property lists to text characters. -* Substitution:: Replacing a given character wherever it appears. -* Transposition:: Swapping two portions of a buffer. -* Registers:: How registers are implemented. Accessing the text or - position stored in a register. -* Base 64:: Conversion to or from base 64 encoding. -* Checksum/Hash:: Computing cryptographic hashes. -* Parsing HTML/XML:: Parsing HTML and XML. -* Atomic Changes:: Installing several buffer changes "atomically". -* Change Hooks:: Supplying functions to be run when text is changed. -@end menu - -@node Near Point -@section Examining Text Near Point -@cindex text near point - - Many functions are provided to look at the characters around point. -Several simple functions are described here. See also @code{looking-at} -in @ref{Regexp Search}. - -In the following four functions, ``beginning'' or ``end'' of buffer -refers to the beginning or end of the accessible portion. - -@defun char-after &optional position -This function returns the character in the current buffer at (i.e., -immediately after) position @var{position}. If @var{position} is out of -range for this purpose, either before the beginning of the buffer, or at -or beyond the end, then the value is @code{nil}. The default for -@var{position} is point. - -In the following example, assume that the first character in the -buffer is @samp{@@}: - -@example -@group -(string (char-after 1)) - @result{} "@@" -@end group -@end example -@end defun - -@defun char-before &optional position -This function returns the character in the current buffer immediately -before position @var{position}. If @var{position} is out of range for -this purpose, either at or before the beginning of the buffer, or beyond -the end, then the value is @code{nil}. The default for -@var{position} is point. -@end defun - -@defun following-char -This function returns the character following point in the current -buffer. This is similar to @code{(char-after (point))}. However, if -point is at the end of the buffer, then @code{following-char} returns 0. - -Remember that point is always between characters, and the cursor -normally appears over the character following point. Therefore, the -character returned by @code{following-char} is the character the -cursor is over. - -In this example, point is between the @samp{a} and the @samp{c}. - -@example -@group ----------- Buffer: foo ---------- -Gentlemen may cry ``Pea@point{}ce! Peace!,'' -but there is no peace. ----------- Buffer: foo ---------- -@end group - -@group -(string (preceding-char)) - @result{} "a" -(string (following-char)) - @result{} "c" -@end group -@end example -@end defun - -@defun preceding-char -This function returns the character preceding point in the current -buffer. See above, under @code{following-char}, for an example. If -point is at the beginning of the buffer, @code{preceding-char} returns -0. -@end defun - -@defun bobp -This function returns @code{t} if point is at the beginning of the -buffer. If narrowing is in effect, this means the beginning of the -accessible portion of the text. See also @code{point-min} in -@ref{Point}. -@end defun - -@defun eobp -This function returns @code{t} if point is at the end of the buffer. -If narrowing is in effect, this means the end of accessible portion of -the text. See also @code{point-max} in @xref{Point}. -@end defun - -@defun bolp -This function returns @code{t} if point is at the beginning of a line. -@xref{Text Lines}. The beginning of the buffer (or of its accessible -portion) always counts as the beginning of a line. -@end defun - -@defun eolp -This function returns @code{t} if point is at the end of a line. The -end of the buffer (or of its accessible portion) is always considered -the end of a line. -@end defun - -@node Buffer Contents -@section Examining Buffer Contents - - This section describes functions that allow a Lisp program to -convert any portion of the text in the buffer into a string. - -@defun buffer-substring start end -This function returns a string containing a copy of the text of the -region defined by positions @var{start} and @var{end} in the current -buffer. If the arguments are not positions in the accessible portion -of the buffer, @code{buffer-substring} signals an -@code{args-out-of-range} error. - -Here's an example which assumes Font-Lock mode is not enabled: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of buffer foo - ----------- Buffer: foo ---------- -@end group - -@group -(buffer-substring 1 10) - @result{} "This is t" -@end group -@group -(buffer-substring (point-max) 10) - @result{} "he contents of buffer foo\n" -@end group -@end example - -If the text being copied has any text properties, these are copied into -the string along with the characters they belong to. @xref{Text -Properties}. However, overlays (@pxref{Overlays}) in the buffer and -their properties are ignored, not copied. - -For example, if Font-Lock mode is enabled, you might get results like -these: - -@example -@group -(buffer-substring 1 10) - @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t)) -@end group -@end example -@end defun - -@defun buffer-substring-no-properties start end -This is like @code{buffer-substring}, except that it does not copy text -properties, just the characters themselves. @xref{Text Properties}. -@end defun - -@defun buffer-string -This function returns the contents of the entire accessible portion of -the current buffer as a string. It is equivalent to -@w{@code{(buffer-substring (point-min) (point-max))}}. -@end defun - -@defun filter-buffer-substring start end &optional delete -This function passes the buffer text between @var{start} and @var{end} -through the filter functions specified by the wrapper hook -@code{filter-buffer-substring-functions}, and returns the result. The -obsolete variable @code{buffer-substring-filters} is also consulted. -If both of these variables are @code{nil}, the value is the unaltered -text from the buffer, i.e.@: what @code{buffer-substring} would -return. - -If @var{delete} is non-@code{nil}, this function deletes the text -between @var{start} and @var{end} after copying it, like -@code{delete-and-extract-region}. - -Lisp code should use this function instead of @code{buffer-substring}, -@code{buffer-substring-no-properties}, -or @code{delete-and-extract-region} when copying into user-accessible -data structures such as the kill-ring, X clipboard, and registers. -Major and minor modes can add functions to -@code{filter-buffer-substring-functions} to alter such text as it is -copied out of the buffer. -@end defun - -@defvar filter-buffer-substring-functions -This variable is a wrapper hook (@pxref{Running Hooks}), whose members -should be functions that accept four arguments: @var{fun}, -@var{start}, @var{end}, and @var{delete}. @var{fun} is a function -that takes three arguments (@var{start}, @var{end}, and @var{delete}), -and returns a string. In both cases, the @var{start}, @var{end}, and -@var{delete} arguments are the same as those of -@code{filter-buffer-substring}. - -The first hook function is passed a @var{fun} that is equivalent to -the default operation of @code{filter-buffer-substring}, i.e. it -returns the buffer-substring between @var{start} and @var{end} -(processed by any @code{buffer-substring-filters}) and optionally -deletes the original text from the buffer. In most cases, the hook -function will call @var{fun} once, and then do its own processing of -the result. The next hook function receives a @var{fun} equivalent to -this, and so on. The actual return value is the result of all the -hook functions acting in sequence. -@end defvar - -@defvar buffer-substring-filters -This variable is obsoleted by -@code{filter-buffer-substring-functions}, but is still supported for -backward compatibility. Its value should should be a list of -functions which accept a single string argument and return another -string. @code{filter-buffer-substring} passes the buffer substring to -the first function in this list, and the return value of each function -is passed to the next function. The return value of the last function -is passed to @code{filter-buffer-substring-functions}. -@end defvar - -@defun current-word &optional strict really-word -This function returns the symbol (or word) at or near point, as a -string. The return value includes no text properties. - -If the optional argument @var{really-word} is non-@code{nil}, it finds a -word; otherwise, it finds a symbol (which includes both word -characters and symbol constituent characters). - -If the optional argument @var{strict} is non-@code{nil}, then point -must be in or next to the symbol or word---if no symbol or word is -there, the function returns @code{nil}. Otherwise, a nearby symbol or -word on the same line is acceptable. -@end defun - -@defun thing-at-point thing -Return the @var{thing} around or next to point, as a string. - -The argument @var{thing} is a symbol which specifies a kind of syntactic -entity. Possibilities include @code{symbol}, @code{list}, @code{sexp}, -@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence}, -@code{whitespace}, @code{line}, @code{page}, and others. - -@example ----------- Buffer: foo ---------- -Gentlemen may cry ``Pea@point{}ce! Peace!,'' -but there is no peace. ----------- Buffer: foo ---------- - -(thing-at-point 'word) - @result{} "Peace" -(thing-at-point 'line) - @result{} "Gentlemen may cry ``Peace! Peace!,''\n" -(thing-at-point 'whitespace) - @result{} nil -@end example -@end defun - -@node Comparing Text -@section Comparing Text -@cindex comparing buffer text - - This function lets you compare portions of the text in a buffer, without -copying them into strings first. - -@defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2 -This function lets you compare two substrings of the same buffer or two -different buffers. The first three arguments specify one substring, -giving a buffer (or a buffer name) and two positions within the -buffer. The last three arguments specify the other substring in the -same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or -both to stand for the current buffer. - -The value is negative if the first substring is less, positive if the -first is greater, and zero if they are equal. The absolute value of -the result is one plus the index of the first differing characters -within the substrings. - -This function ignores case when comparing characters -if @code{case-fold-search} is non-@code{nil}. It always ignores -text properties. - -Suppose the current buffer contains the text @samp{foobarbar -haha!rara!}; then in this example the two substrings are @samp{rbar } -and @samp{rara!}. The value is 2 because the first substring is greater -at the second character. - -@example -(compare-buffer-substrings nil 6 11 nil 16 21) - @result{} 2 -@end example -@end defun - -@node Insertion -@section Inserting Text -@cindex insertion of text -@cindex text insertion - -@cindex insertion before point -@cindex before point, insertion - @dfn{Insertion} means adding new text to a buffer. The inserted text -goes at point---between the character before point and the character -after point. Some insertion functions leave point before the inserted -text, while other functions leave it after. We call the former -insertion @dfn{after point} and the latter insertion @dfn{before point}. - - Insertion moves markers located at positions after the insertion -point, so that they stay with the surrounding text (@pxref{Markers}). -When a marker points at the place of insertion, insertion may or may -not relocate the marker, depending on the marker's insertion type -(@pxref{Marker Insertion Types}). Certain special functions such as -@code{insert-before-markers} relocate all such markers to point after -the inserted text, regardless of the markers' insertion type. - - Insertion functions signal an error if the current buffer is -read-only or if they insert within read-only text. - - These functions copy text characters from strings and buffers along -with their properties. The inserted characters have exactly the same -properties as the characters they were copied from. By contrast, -characters specified as separate arguments, not part of a string or -buffer, inherit their text properties from the neighboring text. - - The insertion functions convert text from unibyte to multibyte in -order to insert in a multibyte buffer, and vice versa---if the text -comes from a string or from a buffer. However, they do not convert -unibyte character codes 128 through 255 to multibyte characters, not -even if the current buffer is a multibyte buffer. @xref{Converting -Representations}. - -@defun insert &rest args -This function inserts the strings and/or characters @var{args} into the -current buffer, at point, moving point forward. In other words, it -inserts the text before point. An error is signaled unless all -@var{args} are either strings or characters. The value is @code{nil}. -@end defun - -@defun insert-before-markers &rest args -This function inserts the strings and/or characters @var{args} into the -current buffer, at point, moving point forward. An error is signaled -unless all @var{args} are either strings or characters. The value is -@code{nil}. - -This function is unlike the other insertion functions in that it -relocates markers initially pointing at the insertion point, to point -after the inserted text. If an overlay begins at the insertion point, -the inserted text falls outside the overlay; if a nonempty overlay -ends at the insertion point, the inserted text falls inside that -overlay. -@end defun - -@defun insert-char character count &optional inherit -This function inserts @var{count} instances of @var{character} into the -current buffer before point. The argument @var{count} should be an -integer, and @var{character} must be a character. The value is @code{nil}. - -This function does not convert unibyte character codes 128 through 255 -to multibyte characters, not even if the current buffer is a multibyte -buffer. @xref{Converting Representations}. - -If @var{inherit} is non-@code{nil}, then the inserted characters inherit -sticky text properties from the two characters before and after the -insertion point. @xref{Sticky Properties}. -@end defun - -@defun insert-buffer-substring from-buffer-or-name &optional start end -This function inserts a portion of buffer @var{from-buffer-or-name} -(which must already exist) into the current buffer before point. The -text inserted is the region between @var{start} and @var{end}. (These -arguments default to the beginning and end of the accessible portion of -that buffer.) This function returns @code{nil}. - -In this example, the form is executed with buffer @samp{bar} as the -current buffer. We assume that buffer @samp{bar} is initially empty. - -@example -@group ----------- Buffer: foo ---------- -We hold these truths to be self-evident, that all ----------- Buffer: foo ---------- -@end group - -@group -(insert-buffer-substring "foo" 1 20) - @result{} nil - ----------- Buffer: bar ---------- -We hold these truth@point{} ----------- Buffer: bar ---------- -@end group -@end example -@end defun - -@defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end -This is like @code{insert-buffer-substring} except that it does not -copy any text properties. -@end defun - - @xref{Sticky Properties}, for other insertion functions that inherit -text properties from the nearby text in addition to inserting it. -Whitespace inserted by indentation functions also inherits text -properties. - -@node Commands for Insertion -@section User-Level Insertion Commands - - This section describes higher-level commands for inserting text, -commands intended primarily for the user but useful also in Lisp -programs. - -@deffn Command insert-buffer from-buffer-or-name -This command inserts the entire accessible contents of -@var{from-buffer-or-name} (which must exist) into the current buffer -after point. It leaves the mark after the inserted text. The value -is @code{nil}. -@end deffn - -@deffn Command self-insert-command count -@cindex character insertion -@cindex self-insertion -This command inserts the last character typed; it does so @var{count} -times, before point, and returns @code{nil}. Most printing characters -are bound to this command. In routine use, @code{self-insert-command} -is the most frequently called function in Emacs, but programs rarely use -it except to install it on a keymap. - -In an interactive call, @var{count} is the numeric prefix argument. - -Self-insertion translates the input character through -@code{translation-table-for-input}. @xref{Translation of Characters}. - -This command calls @code{auto-fill-function} whenever that is -non-@code{nil} and the character inserted is in the table -@code{auto-fill-chars} (@pxref{Auto Filling}). - -@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92 -This command performs abbrev expansion if Abbrev mode is enabled and -the inserted character does not have word-constituent -syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also -responsible for calling @code{blink-paren-function} when the inserted -character has close parenthesis syntax (@pxref{Blinking}). - -@vindex post-self-insert-hook -The final thing this command does is to run the hook -@code{post-self-insert-hook}. You could use this to automatically -reindent text as it is typed, for example. - -Do not try substituting your own definition of -@code{self-insert-command} for the standard one. The editor command -loop handles this function specially. -@end deffn - -@deffn Command newline &optional number-of-newlines -This command inserts newlines into the current buffer before point. -If @var{number-of-newlines} is supplied, that many newline characters -are inserted. - -@cindex newline and Auto Fill mode -This function calls @code{auto-fill-function} if the current column -number is greater than the value of @code{fill-column} and -@var{number-of-newlines} is @code{nil}. Typically what -@code{auto-fill-function} does is insert a newline; thus, the overall -result in this case is to insert two newlines at different places: one -at point, and another earlier in the line. @code{newline} does not -auto-fill if @var{number-of-newlines} is non-@code{nil}. - -This command indents to the left margin if that is not zero. -@xref{Margins}. - -The value returned is @code{nil}. In an interactive call, @var{count} -is the numeric prefix argument. -@end deffn - -@defvar overwrite-mode -This variable controls whether overwrite mode is in effect. The value -should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, -or @code{nil}. @code{overwrite-mode-textual} specifies textual -overwrite mode (treats newlines and tabs specially), and -@code{overwrite-mode-binary} specifies binary overwrite mode (treats -newlines and tabs like any other characters). -@end defvar - -@node Deletion -@section Deleting Text -@cindex text deletion - -@cindex deleting text vs killing - Deletion means removing part of the text in a buffer, without saving -it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be -yanked, but can be reinserted using the undo mechanism (@pxref{Undo}). -Some deletion functions do save text in the kill ring in some special -cases. - - All of the deletion functions operate on the current buffer. - -@deffn Command erase-buffer -This function deletes the entire text of the current buffer -(@emph{not} just the accessible portion), leaving it -empty. If the buffer is read-only, it signals a @code{buffer-read-only} -error; if some of the text in it is read-only, it signals a -@code{text-read-only} error. Otherwise, it deletes the text without -asking for any confirmation. It returns @code{nil}. - -Normally, deleting a large amount of text from a buffer inhibits further -auto-saving of that buffer ``because it has shrunk''. However, -@code{erase-buffer} does not do this, the idea being that the future -text is not really related to the former text, and its size should not -be compared with that of the former text. -@end deffn - -@deffn Command delete-region start end -This command deletes the text between positions @var{start} and -@var{end} in the current buffer, and returns @code{nil}. If point was -inside the deleted region, its value afterward is @var{start}. -Otherwise, point relocates with the surrounding text, as markers do. -@end deffn - -@defun delete-and-extract-region start end -This function deletes the text between positions @var{start} and -@var{end} in the current buffer, and returns a string containing the -text just deleted. - -If point was inside the deleted region, its value afterward is -@var{start}. Otherwise, point relocates with the surrounding text, as -markers do. -@end defun - -@deffn Command delete-char count &optional killp -This command deletes @var{count} characters directly after point, or -before point if @var{count} is negative. If @var{killp} is -non-@code{nil}, then it saves the deleted characters in the kill ring. - -In an interactive call, @var{count} is the numeric prefix argument, and -@var{killp} is the unprocessed prefix argument. Therefore, if a prefix -argument is supplied, the text is saved in the kill ring. If no prefix -argument is supplied, then one character is deleted, but not saved in -the kill ring. - -The value returned is always @code{nil}. -@end deffn - -@deffn Command delete-backward-char count &optional killp -@cindex deleting previous char -This command deletes @var{count} characters directly before point, or -after point if @var{count} is negative. If @var{killp} is -non-@code{nil}, then it saves the deleted characters in the kill ring. - -In an interactive call, @var{count} is the numeric prefix argument, and -@var{killp} is the unprocessed prefix argument. Therefore, if a prefix -argument is supplied, the text is saved in the kill ring. If no prefix -argument is supplied, then one character is deleted, but not saved in -the kill ring. - -The value returned is always @code{nil}. -@end deffn - -@deffn Command backward-delete-char-untabify count &optional killp -@cindex tab deletion -This command deletes @var{count} characters backward, changing tabs -into spaces. When the next character to be deleted is a tab, it is -first replaced with the proper number of spaces to preserve alignment -and then one of those spaces is deleted instead of the tab. If -@var{killp} is non-@code{nil}, then the command saves the deleted -characters in the kill ring. - -Conversion of tabs to spaces happens only if @var{count} is positive. -If it is negative, exactly @minus{}@var{count} characters after point -are deleted. - -In an interactive call, @var{count} is the numeric prefix argument, and -@var{killp} is the unprocessed prefix argument. Therefore, if a prefix -argument is supplied, the text is saved in the kill ring. If no prefix -argument is supplied, then one character is deleted, but not saved in -the kill ring. - -The value returned is always @code{nil}. -@end deffn - -@defopt backward-delete-char-untabify-method -This option specifies how @code{backward-delete-char-untabify} should -deal with whitespace. Possible values include @code{untabify}, the -default, meaning convert a tab to many spaces and delete one; -@code{hungry}, meaning delete all tabs and spaces before point with -one command; @code{all} meaning delete all tabs, spaces and newlines -before point, and @code{nil}, meaning do nothing special for -whitespace characters. -@end defopt - -@node User-Level Deletion -@section User-Level Deletion Commands - - This section describes higher-level commands for deleting text, -commands intended primarily for the user but useful also in Lisp -programs. - -@deffn Command delete-horizontal-space &optional backward-only -@cindex deleting whitespace -This function deletes all spaces and tabs around point. It returns -@code{nil}. - -If @var{backward-only} is non-@code{nil}, the function deletes -spaces and tabs before point, but not after point. - -In the following examples, we call @code{delete-horizontal-space} four -times, once on each line, with point between the second and third -characters on the line each time. - -@example -@group ----------- Buffer: foo ---------- -I @point{}thought -I @point{} thought -We@point{} thought -Yo@point{}u thought ----------- Buffer: foo ---------- -@end group - -@group -(delete-horizontal-space) ; @r{Four times.} - @result{} nil - ----------- Buffer: foo ---------- -Ithought -Ithought -Wethought -You thought ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command delete-indentation &optional join-following-p -This function joins the line point is on to the previous line, deleting -any whitespace at the join and in some cases replacing it with one -space. If @var{join-following-p} is non-@code{nil}, -@code{delete-indentation} joins this line to the following line -instead. The function returns @code{nil}. - -If there is a fill prefix, and the second of the lines being joined -starts with the prefix, then @code{delete-indentation} deletes the -fill prefix before joining the lines. @xref{Margins}. - -In the example below, point is located on the line starting -@samp{events}, and it makes no difference if there are trailing spaces -in the preceding line. - -@smallexample -@group ----------- Buffer: foo ---------- -When in the course of human -@point{} events, it becomes necessary ----------- Buffer: foo ---------- -@end group - -(delete-indentation) - @result{} nil - -@group ----------- Buffer: foo ---------- -When in the course of human@point{} events, it becomes necessary ----------- Buffer: foo ---------- -@end group -@end smallexample - -After the lines are joined, the function @code{fixup-whitespace} is -responsible for deciding whether to leave a space at the junction. -@end deffn - -@deffn Command fixup-whitespace -This function replaces all the horizontal whitespace surrounding point -with either one space or no space, according to the context. It -returns @code{nil}. - -At the beginning or end of a line, the appropriate amount of space is -none. Before a character with close parenthesis syntax, or after a -character with open parenthesis or expression-prefix syntax, no space is -also appropriate. Otherwise, one space is appropriate. @xref{Syntax -Class Table}. - -In the example below, @code{fixup-whitespace} is called the first time -with point before the word @samp{spaces} in the first line. For the -second invocation, point is directly after the @samp{(}. - -@smallexample -@group ----------- Buffer: foo ---------- -This has too many @point{}spaces -This has too many spaces at the start of (@point{} this list) ----------- Buffer: foo ---------- -@end group - -@group -(fixup-whitespace) - @result{} nil -(fixup-whitespace) - @result{} nil -@end group - -@group ----------- Buffer: foo ---------- -This has too many spaces -This has too many spaces at the start of (this list) ----------- Buffer: foo ---------- -@end group -@end smallexample -@end deffn - -@deffn Command just-one-space &optional n -@comment !!SourceFile simple.el -This command replaces any spaces and tabs around point with a single -space, or @var{n} spaces if @var{n} is specified. It returns -@code{nil}. -@end deffn - -@deffn Command delete-blank-lines -This function deletes blank lines surrounding point. If point is on a -blank line with one or more blank lines before or after it, then all but -one of them are deleted. If point is on an isolated blank line, then it -is deleted. If point is on a nonblank line, the command deletes all -blank lines immediately following it. - -A blank line is defined as a line containing only tabs and spaces. - -@code{delete-blank-lines} returns @code{nil}. -@end deffn - -@node The Kill Ring -@section The Kill Ring -@cindex kill ring - - @dfn{Kill functions} delete text like the deletion functions, but save -it so that the user can reinsert it by @dfn{yanking}. Most of these -functions have @samp{kill-} in their name. By contrast, the functions -whose names start with @samp{delete-} normally do not save text for -yanking (though they can still be undone); these are ``deletion'' -functions. - - Most of the kill commands are primarily for interactive use, and are -not described here. What we do describe are the functions provided for -use in writing such commands. You can use these functions to write -commands for killing text. When you need to delete text for internal -purposes within a Lisp function, you should normally use deletion -functions, so as not to disturb the kill ring contents. -@xref{Deletion}. - - Killed text is saved for later yanking in the @dfn{kill ring}. This -is a list that holds a number of recent kills, not just the last text -kill. We call this a ``ring'' because yanking treats it as having -elements in a cyclic order. The list is kept in the variable -@code{kill-ring}, and can be operated on with the usual functions for -lists; there are also specialized functions, described in this section, -that treat it as a ring. - - Some people think this use of the word ``kill'' is unfortunate, since -it refers to operations that specifically @emph{do not} destroy the -entities ``killed''. This is in sharp contrast to ordinary life, in -which death is permanent and ``killed'' entities do not come back to -life. Therefore, other metaphors have been proposed. For example, the -term ``cut ring'' makes sense to people who, in pre-computer days, used -scissors and paste to cut up and rearrange manuscripts. However, it -would be difficult to change the terminology now. - -@menu -* Kill Ring Concepts:: What text looks like in the kill ring. -* Kill Functions:: Functions that kill text. -* Yanking:: How yanking is done. -* Yank Commands:: Commands that access the kill ring. -* Low-Level Kill Ring:: Functions and variables for kill ring access. -* Internals of Kill Ring:: Variables that hold kill ring data. -@end menu - -@node Kill Ring Concepts -@comment node-name, next, previous, up -@subsection Kill Ring Concepts - - The kill ring records killed text as strings in a list, most recent -first. A short kill ring, for example, might look like this: - -@example -("some text" "a different piece of text" "even older text") -@end example - -@noindent -When the list reaches @code{kill-ring-max} entries in length, adding a -new entry automatically deletes the last entry. - - When kill commands are interwoven with other commands, each kill -command makes a new entry in the kill ring. Multiple kill commands in -succession build up a single kill ring entry, which would be yanked as a -unit; the second and subsequent consecutive kill commands add text to -the entry made by the first one. - - For yanking, one entry in the kill ring is designated the ``front'' of -the ring. Some yank commands ``rotate'' the ring by designating a -different element as the ``front''. But this virtual rotation doesn't -change the list itself---the most recent entry always comes first in the -list. - -@node Kill Functions -@comment node-name, next, previous, up -@subsection Functions for Killing - - @code{kill-region} is the usual subroutine for killing text. Any -command that calls this function is a ``kill command'' (and should -probably have @samp{kill} in its name). @code{kill-region} puts the -newly killed text in a new element at the beginning of the kill ring or -adds it to the most recent element. It determines automatically (using -@code{last-command}) whether the previous command was a kill command, -and if so appends the killed text to the most recent entry. - -@deffn Command kill-region start end -This function kills the text in the region defined by @var{start} and -@var{end}. The text is deleted but saved in the kill ring, along with -its text properties. The value is always @code{nil}. - -In an interactive call, @var{start} and @var{end} are point and -the mark. - -If the buffer or text is read-only, @code{kill-region} modifies the kill -ring just the same, then signals an error without modifying the buffer. -This is convenient because it lets the user use a series of kill -commands to copy text from a read-only buffer into the kill ring. -@end deffn - -@defopt kill-read-only-ok -If this option is non-@code{nil}, @code{kill-region} does not signal an -error if the buffer or text is read-only. Instead, it simply returns, -updating the kill ring but not changing the buffer. -@end defopt - -@deffn Command copy-region-as-kill start end -This command saves the region defined by @var{start} and @var{end} on -the kill ring (including text properties), but does not delete the text -from the buffer. It returns @code{nil}. - -The command does not set @code{this-command} to @code{kill-region}, so a -subsequent kill command does not append to the same kill ring entry. - -@c FIXME Why is it better? Why isn't copy-region-as-kill obsolete then? -@c Why is it used in many places in Emacs? -In Lisp programs, it is better to use @code{kill-new} or -@code{kill-append} instead of this command. @xref{Low-Level Kill Ring}. -@end deffn - -@node Yanking -@subsection Yanking - - Yanking means inserting text from the kill ring, but it does -not insert the text blindly. Yank commands and some other commands -use @code{insert-for-yank} to perform special processing on the -text that they copy into the buffer. - -@defun insert-for-yank string -This function normally works like @code{insert} except that it doesn't -insert the text properties (@pxref{Text Properties}) in the list -variable @code{yank-excluded-properties}. However, if any part of -@var{string} has a non-@code{nil} @code{yank-handler} text property, -that property can do various special processing on that part of the -text being inserted. -@end defun - -@defun insert-buffer-substring-as-yank buf &optional start end -This function resembles @code{insert-buffer-substring} except that it -doesn't insert the text properties in the -@code{yank-excluded-properties} list. -@end defun - - You can put a @code{yank-handler} text property on all or part of -the text to control how it will be inserted if it is yanked. The -@code{insert-for-yank} function looks for that property. The property -value must be a list of one to four elements, with the following -format (where elements after the first may be omitted): - -@example -(@var{function} @var{param} @var{noexclude} @var{undo}) -@end example - - Here is what the elements do: - -@table @var -@item function -When @var{function} is present and non-@code{nil}, it is called instead of -@code{insert} to insert the string. @var{function} takes one -argument---the string to insert. - -@item param -If @var{param} is present and non-@code{nil}, it replaces @var{string} -(or the part of @var{string} being processed) as the object passed to -@var{function} (or @code{insert}); for example, if @var{function} is -@code{yank-rectangle}, @var{param} should be a list of strings to -insert as a rectangle. - -@item noexclude -If @var{noexclude} is present and non-@code{nil}, the normal removal of the -yank-excluded-properties is not performed; instead @var{function} is -responsible for removing those properties. This may be necessary -if @var{function} adjusts point before or after inserting the object. - -@item undo -If @var{undo} is present and non-@code{nil}, it is a function that will be -called by @code{yank-pop} to undo the insertion of the current object. -It is called with two arguments, the start and end of the current -region. @var{function} can set @code{yank-undo-function} to override -the @var{undo} value. -@end table - -@cindex yanking and text properties -@defopt yank-excluded-properties -Yanking discards certain text properties from the yanked text, as -described above. The value of this variable is the list of properties -to discard. Its default value contains properties that might lead to -annoying results, such as causing the text to respond to the mouse or -specifying key bindings. -@end defopt - -@node Yank Commands -@comment node-name, next, previous, up -@subsection Functions for Yanking - - This section describes higher-level commands for yanking, which are -intended primarily for the user but useful also in Lisp programs. -Both @code{yank} and @code{yank-pop} honor the -@code{yank-excluded-properties} variable and @code{yank-handler} text -property (@pxref{Yanking}). - -@deffn Command yank &optional arg -@cindex inserting killed text -This command inserts before point the text at the front of the kill -ring. It sets the mark at the beginning of that text, using -@code{push-mark} (@pxref{The Mark}), and puts point at the end. - -If @var{arg} is a non-@code{nil} list (which occurs interactively when -the user types @kbd{C-u} with no digits), then @code{yank} inserts the -text as described above, but puts point before the yanked text and -sets the mark after it. - -If @var{arg} is a number, then @code{yank} inserts the @var{arg}th -most recently killed text---the @var{arg}th element of the kill ring -list, counted cyclically from the front, which is considered the -first element for this purpose. - -@code{yank} does not alter the contents of the kill ring, unless it -used text provided by another program, in which case it pushes that text -onto the kill ring. However if @var{arg} is an integer different from -one, it rotates the kill ring to place the yanked string at the front. - -@code{yank} returns @code{nil}. -@end deffn - -@deffn Command yank-pop &optional arg -This command replaces the just-yanked entry from the kill ring with a -different entry from the kill ring. - -This is allowed only immediately after a @code{yank} or another -@code{yank-pop}. At such a time, the region contains text that was just -inserted by yanking. @code{yank-pop} deletes that text and inserts in -its place a different piece of killed text. It does not add the deleted -text to the kill ring, since it is already in the kill ring somewhere. -It does however rotate the kill ring to place the newly yanked string at -the front. - -If @var{arg} is @code{nil}, then the replacement text is the previous -element of the kill ring. If @var{arg} is numeric, the replacement is -the @var{arg}th previous kill. If @var{arg} is negative, a more recent -kill is the replacement. - -The sequence of kills in the kill ring wraps around, so that after the -oldest one comes the newest one, and before the newest one goes the -oldest. - -The return value is always @code{nil}. -@end deffn - -@defvar yank-undo-function -If this variable is non-@code{nil}, the function @code{yank-pop} uses -its value instead of @code{delete-region} to delete the text -inserted by the previous @code{yank} or -@code{yank-pop} command. The value must be a function of two -arguments, the start and end of the current region. - -The function @code{insert-for-yank} automatically sets this variable -according to the @var{undo} element of the @code{yank-handler} -text property, if there is one. -@end defvar - -@node Low-Level Kill Ring -@subsection Low-Level Kill Ring - - These functions and variables provide access to the kill ring at a -lower level, but are still convenient for use in Lisp programs, -because they take care of interaction with window system selections -(@pxref{Window System Selections}). - -@defun current-kill n &optional do-not-move -The function @code{current-kill} rotates the yanking pointer, which -designates the ``front'' of the kill ring, by @var{n} places (from newer -kills to older ones), and returns the text at that place in the ring. - -If the optional second argument @var{do-not-move} is non-@code{nil}, -then @code{current-kill} doesn't alter the yanking pointer; it just -returns the @var{n}th kill, counting from the current yanking pointer. - -If @var{n} is zero, indicating a request for the latest kill, -@code{current-kill} calls the value of -@code{interprogram-paste-function} (documented below) before -consulting the kill ring. If that value is a function and calling it -returns a string or a list of several string, @code{current-kill} -pushes the strings onto the kill ring and returns the first string. -It also sets the yanking pointer to point to the kill-ring entry of -the first string returned by @code{interprogram-paste-function}, -regardless of the value of @var{do-not-move}. Otherwise, -@code{current-kill} does not treat a zero value for @var{n} specially: -it returns the entry pointed at by the yanking pointer and does not -move the yanking pointer. -@end defun - -@defun kill-new string &optional replace -This function pushes the text @var{string} onto the kill ring and -makes the yanking pointer point to it. It discards the oldest entry -if appropriate. It also invokes the value of -@code{interprogram-cut-function} (see below). - -If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the -first element of the kill ring with @var{string}, rather than pushing -@var{string} onto the kill ring. -@end defun - -@defun kill-append string before-p -This function appends the text @var{string} to the first entry in the -kill ring and makes the yanking pointer point to the combined entry. -Normally @var{string} goes at the end of the entry, but if -@var{before-p} is non-@code{nil}, it goes at the beginning. This -function also invokes the value of @code{interprogram-cut-function} -(see below). -@end defun - -@defvar interprogram-paste-function -This variable provides a way of transferring killed text from other -programs, when you are using a window system. Its value should be -@code{nil} or a function of no arguments. - -If the value is a function, @code{current-kill} calls it to get the -``most recent kill''. If the function returns a non-@code{nil} value, -then that value is used as the ``most recent kill''. If it returns -@code{nil}, then the front of the kill ring is used. - -To facilitate support for window systems that support multiple -selections, this function may also return a list of strings. In that -case, the first string is used as the ``most recent kill'', and all -the other strings are pushed onto the kill ring, for easy access by -@code{yank-pop}. - -The normal use of this function is to get the window system's -clipboard as the most recent kill, even if the selection belongs to -another application. @xref{Window System Selections}. However, if -the clipboard contents come from the current Emacs session, this -function should return @code{nil}. -@end defvar - -@defvar interprogram-cut-function -This variable provides a way of communicating killed text to other -programs, when you are using a window system. Its value should be -@code{nil} or a function of one required argument. - -If the value is a function, @code{kill-new} and @code{kill-append} call -it with the new first element of the kill ring as the argument. - -The normal use of this function is to put newly killed text in the -window system's clipboard. @xref{Window System Selections}. -@end defvar - -@node Internals of Kill Ring -@comment node-name, next, previous, up -@subsection Internals of the Kill Ring - - The variable @code{kill-ring} holds the kill ring contents, in the -form of a list of strings. The most recent kill is always at the front -of the list. - - The @code{kill-ring-yank-pointer} variable points to a link in the -kill ring list, whose @sc{car} is the text to yank next. We say it -identifies the ``front'' of the ring. Moving -@code{kill-ring-yank-pointer} to a different link is called -@dfn{rotating the kill ring}. We call the kill ring a ``ring'' because -the functions that move the yank pointer wrap around from the end of the -list to the beginning, or vice-versa. Rotation of the kill ring is -virtual; it does not change the value of @code{kill-ring}. - - Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp -variables whose values are normally lists. The word ``pointer'' in the -name of the @code{kill-ring-yank-pointer} indicates that the variable's -purpose is to identify one element of the list for use by the next yank -command. - - The value of @code{kill-ring-yank-pointer} is always @code{eq} to one -of the links in the kill ring list. The element it identifies is the -@sc{car} of that link. Kill commands, which change the kill ring, also -set this variable to the value of @code{kill-ring}. The effect is to -rotate the ring so that the newly killed text is at the front. - - Here is a diagram that shows the variable @code{kill-ring-yank-pointer} -pointing to the second entry in the kill ring @code{("some text" "a -different piece of text" "yet older text")}. - -@example -@group -kill-ring ---- kill-ring-yank-pointer - | | - | v - | --- --- --- --- --- --- - --> | | |------> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - | | -->"yet older text" - | | - | --> "a different piece of text" - | - --> "some text" -@end group -@end example - -@noindent -This state of affairs might occur after @kbd{C-y} (@code{yank}) -immediately followed by @kbd{M-y} (@code{yank-pop}). - -@defvar kill-ring -This variable holds the list of killed text sequences, most recently -killed first. -@end defvar - -@defvar kill-ring-yank-pointer -This variable's value indicates which element of the kill ring is at the -``front'' of the ring for yanking. More precisely, the value is a tail -of the value of @code{kill-ring}, and its @sc{car} is the kill string -that @kbd{C-y} should yank. -@end defvar - -@defopt kill-ring-max -The value of this variable is the maximum length to which the kill -ring can grow, before elements are thrown away at the end. The default -value for @code{kill-ring-max} is 60. -@end defopt - -@node Undo -@comment node-name, next, previous, up -@section Undo -@cindex redo - - Most buffers have an @dfn{undo list}, which records all changes made -to the buffer's text so that they can be undone. (The buffers that -don't have one are usually special-purpose buffers for which Emacs -assumes that undoing is not useful. In particular, any buffer whose -name begins with a space has its undo recording off by default; -see @ref{Buffer Names}.) All the primitives that modify the -text in the buffer automatically add elements to the front of the undo -list, which is in the variable @code{buffer-undo-list}. - -@defvar buffer-undo-list -This buffer-local variable's value is the undo list of the current -buffer. A value of @code{t} disables the recording of undo information. -@end defvar - -Here are the kinds of elements an undo list can have: - -@table @code -@item @var{position} -This kind of element records a previous value of point; undoing this -element moves point to @var{position}. Ordinary cursor motion does not -make any sort of undo record, but deletion operations use these entries -to record where point was before the command. - -@item (@var{beg} . @var{end}) -This kind of element indicates how to delete text that was inserted. -Upon insertion, the text occupied the range @var{beg}--@var{end} in the -buffer. - -@item (@var{text} . @var{position}) -This kind of element indicates how to reinsert text that was deleted. -The deleted text itself is the string @var{text}. The place to -reinsert it is @code{(abs @var{position})}. If @var{position} is -positive, point was at the beginning of the deleted text, otherwise it -was at the end. - -@item (t @var{high} . @var{low}) -This kind of element indicates that an unmodified buffer became -modified. The elements @var{high} and @var{low} are two integers, each -recording 16 bits of the visited file's modification time as of when it -was previously visited or saved. @code{primitive-undo} uses those -values to determine whether to mark the buffer as unmodified once again; -it does so only if the file's modification time matches those numbers. - -@item (nil @var{property} @var{value} @var{beg} . @var{end}) -This kind of element records a change in a text property. -Here's how you might undo the change: - -@example -(put-text-property @var{beg} @var{end} @var{property} @var{value}) -@end example - -@item (@var{marker} . @var{adjustment}) -This kind of element records the fact that the marker @var{marker} was -relocated due to deletion of surrounding text, and that it moved -@var{adjustment} character positions. Undoing this element moves -@var{marker} @minus{} @var{adjustment} characters. - -@item (apply @var{funname} . @var{args}) -This is an extensible undo item, which is undone by calling -@var{funname} with arguments @var{args}. - -@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args}) -This is an extensible undo item, which records a change limited to the -range @var{beg} to @var{end}, which increased the size of the buffer -by @var{delta}. It is undone by calling @var{funname} with arguments -@var{args}. - -This kind of element enables undo limited to a region to determine -whether the element pertains to that region. - -@item nil -This element is a boundary. The elements between two boundaries are -called a @dfn{change group}; normally, each change group corresponds to -one keyboard command, and undo commands normally undo an entire group as -a unit. -@end table - -@defun undo-boundary -This function places a boundary element in the undo list. The undo -command stops at such a boundary, and successive undo commands undo -to earlier and earlier boundaries. This function returns @code{nil}. - -The editor command loop automatically calls @code{undo-boundary} just -before executing each key sequence, so that each undo normally undoes -the effects of one command. As an exception, the command -@code{self-insert-command}, which produces self-inserting input -characters (@pxref{Commands for Insertion}), may remove the boundary -inserted by the command loop: a boundary is accepted for the first -such character, the next 19 consecutive self-inserting input -characters do not have boundaries, and then the 20th does; and so on -as long as the self-inserting characters continue. Hence, sequences -of consecutive character insertions can be undone as a group. - -All buffer modifications add a boundary whenever the previous undoable -change was made in some other buffer. This is to ensure that -each command makes a boundary in each buffer where it makes changes. - -Calling this function explicitly is useful for splitting the effects of -a command into more than one unit. For example, @code{query-replace} -calls @code{undo-boundary} after each replacement, so that the user can -undo individual replacements one by one. -@end defun - -@defvar undo-in-progress -This variable is normally @code{nil}, but the undo commands bind it to -@code{t}. This is so that various kinds of change hooks can tell when -they're being called for the sake of undoing. -@end defvar - -@defun primitive-undo count list -This is the basic function for undoing elements of an undo list. -It undoes the first @var{count} elements of @var{list}, returning -the rest of @var{list}. - -@code{primitive-undo} adds elements to the buffer's undo list when it -changes the buffer. Undo commands avoid confusion by saving the undo -list value at the beginning of a sequence of undo operations. Then the -undo operations use and update the saved value. The new elements added -by undoing are not part of this saved value, so they don't interfere with -continuing to undo. - -This function does not bind @code{undo-in-progress}. -@end defun - -@node Maintaining Undo -@section Maintaining Undo Lists - - This section describes how to enable and disable undo information for -a given buffer. It also explains how the undo list is truncated -automatically so it doesn't get too big. - - Recording of undo information in a newly created buffer is normally -enabled to start with; but if the buffer name starts with a space, the -undo recording is initially disabled. You can explicitly enable or -disable undo recording with the following two functions, or by setting -@code{buffer-undo-list} yourself. - -@deffn Command buffer-enable-undo &optional buffer-or-name -This command enables recording undo information for buffer -@var{buffer-or-name}, so that subsequent changes can be undone. If no -argument is supplied, then the current buffer is used. This function -does nothing if undo recording is already enabled in the buffer. It -returns @code{nil}. - -In an interactive call, @var{buffer-or-name} is the current buffer. -You cannot specify any other buffer. -@end deffn - -@deffn Command buffer-disable-undo &optional buffer-or-name -@cindex disabling undo -This function discards the undo list of @var{buffer-or-name}, and disables -further recording of undo information. As a result, it is no longer -possible to undo either previous changes or any subsequent changes. If -the undo list of @var{buffer-or-name} is already disabled, this function -has no effect. - -This function returns @code{nil}. -@end deffn - - As editing continues, undo lists get longer and longer. To prevent -them from using up all available memory space, garbage collection trims -them back to size limits you can set. (For this purpose, the ``size'' -of an undo list measures the cons cells that make up the list, plus the -strings of deleted text.) Three variables control the range of acceptable -sizes: @code{undo-limit}, @code{undo-strong-limit} and -@code{undo-outer-limit}. In these variables, size is counted as the -number of bytes occupied, which includes both saved text and other -data. - -@defopt undo-limit -This is the soft limit for the acceptable size of an undo list. The -change group at which this size is exceeded is the last one kept. -@end defopt - -@defopt undo-strong-limit -This is the upper limit for the acceptable size of an undo list. The -change group at which this size is exceeded is discarded itself (along -with all older change groups). There is one exception: the very latest -change group is only discarded if it exceeds @code{undo-outer-limit}. -@end defopt - -@defopt undo-outer-limit -If at garbage collection time the undo info for the current command -exceeds this limit, Emacs discards the info and displays a warning. -This is a last ditch limit to prevent memory overflow. -@end defopt - -@defopt undo-ask-before-discard -If this variable is non-@code{nil}, when the undo info exceeds -@code{undo-outer-limit}, Emacs asks in the echo area whether to -discard the info. The default value is @code{nil}, which means to -discard it automatically. - -This option is mainly intended for debugging. Garbage collection is -inhibited while the question is asked, which means that Emacs might -leak memory if the user waits too long before answering the question. -@end defopt - -@node Filling -@comment node-name, next, previous, up -@section Filling -@cindex filling text - - @dfn{Filling} means adjusting the lengths of lines (by moving the line -breaks) so that they are nearly (but no greater than) a specified -maximum width. Additionally, lines can be @dfn{justified}, which means -inserting spaces to make the left and/or right margins line up -precisely. The width is controlled by the variable @code{fill-column}. -For ease of reading, lines should be no longer than 70 or so columns. - - You can use Auto Fill mode (@pxref{Auto Filling}) to fill text -automatically as you insert it, but changes to existing text may leave -it improperly filled. Then you must fill the text explicitly. - - Most of the commands in this section return values that are not -meaningful. All the functions that do filling take note of the current -left margin, current right margin, and current justification style -(@pxref{Margins}). If the current justification style is -@code{none}, the filling functions don't actually do anything. - - Several of the filling functions have an argument @var{justify}. -If it is non-@code{nil}, that requests some kind of justification. It -can be @code{left}, @code{right}, @code{full}, or @code{center}, to -request a specific style of justification. If it is @code{t}, that -means to use the current justification style for this part of the text -(see @code{current-justification}, below). Any other value is treated -as @code{full}. - - When you call the filling functions interactively, using a prefix -argument implies the value @code{full} for @var{justify}. - -@deffn Command fill-paragraph &optional justify region -This command fills the paragraph at or after point. If -@var{justify} is non-@code{nil}, each line is justified as well. -It uses the ordinary paragraph motion commands to find paragraph -boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}. - -When @var{region} is non-@code{nil}, then if Transient Mark mode is -enabled and the mark is active, this command calls @code{fill-region} -to fill all the paragraphs in the region, instead of filling only the -current paragraph. When this command is called interactively, -@var{region} is @code{t}. -@end deffn - -@deffn Command fill-region start end &optional justify nosqueeze to-eop -This command fills each of the paragraphs in the region from @var{start} -to @var{end}. It justifies as well if @var{justify} is -non-@code{nil}. - -If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace -other than line breaks untouched. If @var{to-eop} is non-@code{nil}, -that means to keep filling to the end of the paragraph---or the next hard -newline, if @code{use-hard-newlines} is enabled (see below). - -The variable @code{paragraph-separate} controls how to distinguish -paragraphs. @xref{Standard Regexps}. -@end deffn - -@deffn Command fill-individual-paragraphs start end &optional justify citation-regexp -This command fills each paragraph in the region according to its -individual fill prefix. Thus, if the lines of a paragraph were indented -with spaces, the filled paragraph will remain indented in the same -fashion. - -The first two arguments, @var{start} and @var{end}, are the beginning -and end of the region to be filled. The third and fourth arguments, -@var{justify} and @var{citation-regexp}, are optional. If -@var{justify} is non-@code{nil}, the paragraphs are justified as -well as filled. If @var{citation-regexp} is non-@code{nil}, it means the -function is operating on a mail message and therefore should not fill -the header lines. If @var{citation-regexp} is a string, it is used as -a regular expression; if it matches the beginning of a line, that line -is treated as a citation marker. - -Ordinarily, @code{fill-individual-paragraphs} regards each change in -indentation as starting a new paragraph. If -@code{fill-individual-varying-indent} is non-@code{nil}, then only -separator lines separate paragraphs. That mode can handle indented -paragraphs with additional indentation on the first line. -@end deffn - -@defopt fill-individual-varying-indent -This variable alters the action of @code{fill-individual-paragraphs} as -described above. -@end defopt - -@deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after -This command considers a region of text as a single paragraph and fills -it. If the region was made up of many paragraphs, the blank lines -between paragraphs are removed. This function justifies as well as -filling when @var{justify} is non-@code{nil}. - -If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace -other than line breaks untouched. If @var{squeeze-after} is -non-@code{nil}, it specifies a position in the region, and means don't -canonicalize spaces before that position. - -In Adaptive Fill mode, this command calls @code{fill-context-prefix} to -choose a fill prefix by default. @xref{Adaptive Fill}. -@end deffn - -@deffn Command justify-current-line &optional how eop nosqueeze -This command inserts spaces between the words of the current line so -that the line ends exactly at @code{fill-column}. It returns -@code{nil}. - -The argument @var{how}, if non-@code{nil} specifies explicitly the style -of justification. It can be @code{left}, @code{right}, @code{full}, -@code{center}, or @code{none}. If it is @code{t}, that means to do -follow specified justification style (see @code{current-justification}, -below). @code{nil} means to do full justification. - -If @var{eop} is non-@code{nil}, that means do only left-justification -if @code{current-justification} specifies full justification. This is -used for the last line of a paragraph; even if the paragraph as a -whole is fully justified, the last line should not be. - -If @var{nosqueeze} is non-@code{nil}, that means do not change interior -whitespace. -@end deffn - -@defopt default-justification -This variable's value specifies the style of justification to use for -text that doesn't specify a style with a text property. The possible -values are @code{left}, @code{right}, @code{full}, @code{center}, or -@code{none}. The default value is @code{left}. -@end defopt - -@defun current-justification -This function returns the proper justification style to use for filling -the text around point. - -This returns the value of the @code{justification} text property at -point, or the variable @var{default-justification} if there is no such -text property. However, it returns @code{nil} rather than @code{none} -to mean ``don't justify''. -@end defun - -@defopt sentence-end-double-space -@anchor{Definition of sentence-end-double-space} -If this variable is non-@code{nil}, a period followed by just one space -does not count as the end of a sentence, and the filling functions -avoid breaking the line at such a place. -@end defopt - -@defopt sentence-end-without-period -If this variable is non-@code{nil}, a sentence can end without a -period. This is used for languages like Thai, where sentences end -with a double space but without a period. -@end defopt - -@defopt sentence-end-without-space -If this variable is non-@code{nil}, it should be a string of -characters that can end a sentence without following spaces. -@end defopt - -@defvar fill-paragraph-function -This variable provides a way to override the filling of paragraphs. -If its value is non-@code{nil}, @code{fill-paragraph} calls this -function to do the work. If the function returns a non-@code{nil} -value, @code{fill-paragraph} assumes the job is done, and immediately -returns that value. - -The usual use of this feature is to fill comments in programming -language modes. If the function needs to fill a paragraph in the usual -way, it can do so as follows: - -@example -(let ((fill-paragraph-function nil)) - (fill-paragraph arg)) -@end example -@end defvar - -@defvar fill-forward-paragraph-function -This variable provides a way to override how the filling functions, -such as @code{fill-region} and @code{fill-paragraph}, move forward to -the next paragraph. Its value should be a function, which is called -with a single argument @var{n}, the number of paragraphs to move, and -should return the difference between @var{n} and the number of -paragraphs actually moved. The default value of this variable is -@code{forward-paragraph}. @xref{Paragraphs,,, emacs, The GNU Emacs -Manual}. -@end defvar - -@defvar use-hard-newlines -If this variable is non-@code{nil}, the filling functions do not delete -newlines that have the @code{hard} text property. These ``hard -newlines'' act as paragraph separators. -@end defvar - -@node Margins -@section Margins for Filling - -@defopt fill-prefix -This buffer-local variable, if non-@code{nil}, specifies a string of -text that appears at the beginning of normal text lines and should be -disregarded when filling them. Any line that fails to start with the -fill prefix is considered the start of a paragraph; so is any line -that starts with the fill prefix followed by additional whitespace. -Lines that start with the fill prefix but no additional whitespace are -ordinary text lines that can be filled together. The resulting filled -lines also start with the fill prefix. - -The fill prefix follows the left margin whitespace, if any. -@end defopt - -@defopt fill-column -This buffer-local variable specifies the maximum width of filled lines. -Its value should be an integer, which is a number of columns. All the -filling, justification, and centering commands are affected by this -variable, including Auto Fill mode (@pxref{Auto Filling}). - -As a practical matter, if you are writing text for other people to -read, you should set @code{fill-column} to no more than 70. Otherwise -the line will be too long for people to read comfortably, and this can -make the text seem clumsy. - -The default value for @code{fill-column} is 70. -@end defopt - -@deffn Command set-left-margin from to margin -This sets the @code{left-margin} property on the text from @var{from} to -@var{to} to the value @var{margin}. If Auto Fill mode is enabled, this -command also refills the region to fit the new margin. -@end deffn - -@deffn Command set-right-margin from to margin -This sets the @code{right-margin} property on the text from @var{from} -to @var{to} to the value @var{margin}. If Auto Fill mode is enabled, -this command also refills the region to fit the new margin. -@end deffn - -@defun current-left-margin -This function returns the proper left margin value to use for filling -the text around point. The value is the sum of the @code{left-margin} -property of the character at the start of the current line (or zero if -none), and the value of the variable @code{left-margin}. -@end defun - -@defun current-fill-column -This function returns the proper fill column value to use for filling -the text around point. The value is the value of the @code{fill-column} -variable, minus the value of the @code{right-margin} property of the -character after point. -@end defun - -@deffn Command move-to-left-margin &optional n force -This function moves point to the left margin of the current line. The -column moved to is determined by calling the function -@code{current-left-margin}. If the argument @var{n} is non-@code{nil}, -@code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first. - -If @var{force} is non-@code{nil}, that says to fix the line's -indentation if that doesn't match the left margin value. -@end deffn - -@defun delete-to-left-margin &optional from to -This function removes left margin indentation from the text between -@var{from} and @var{to}. The amount of indentation to delete is -determined by calling @code{current-left-margin}. In no case does this -function delete non-whitespace. If @var{from} and @var{to} are omitted, -they default to the whole buffer. -@end defun - -@defun indent-to-left-margin -This function adjusts the indentation at the beginning of the current -line to the value specified by the variable @code{left-margin}. (That -may involve either inserting or deleting whitespace.) This function -is value of @code{indent-line-function} in Paragraph-Indent Text mode. -@end defun - -@defopt left-margin -This variable specifies the base left margin column. In Fundamental -mode, @kbd{C-j} indents to this column. This variable automatically -becomes buffer-local when set in any fashion. -@end defopt - -@defopt fill-nobreak-predicate -This variable gives major modes a way to specify not to break a line -at certain places. Its value should be a list of functions. Whenever -filling considers breaking the line at a certain place in the buffer, -it calls each of these functions with no arguments and with point -located at that place. If any of the functions returns -non-@code{nil}, then the line won't be broken there. -@end defopt - -@node Adaptive Fill -@section Adaptive Fill Mode -@c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent. - - When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill -prefix automatically from the text in each paragraph being filled -rather than using a predetermined value. During filling, this fill -prefix gets inserted at the start of the second and subsequent lines -of the paragraph as described in @ref{Filling}, and in @ref{Auto -Filling}. - -@defopt adaptive-fill-mode -Adaptive Fill mode is enabled when this variable is non-@code{nil}. -It is @code{t} by default. -@end defopt - -@defun fill-context-prefix from to -This function implements the heart of Adaptive Fill mode; it chooses a -fill prefix based on the text between @var{from} and @var{to}, -typically the start and end of a paragraph. It does this by looking -at the first two lines of the paragraph, based on the variables -described below. -@c The optional argument first-line-regexp is not documented -@c because it exists for internal purposes and might be eliminated -@c in the future. - -Usually, this function returns the fill prefix, a string. However, -before doing this, the function makes a final check (not specially -mentioned in the following) that a line starting with this prefix -wouldn't look like the start of a paragraph. Should this happen, the -function signals the anomaly by returning @code{nil} instead. - -In detail, @code{fill-context-prefix} does this: - -@enumerate -@item -It takes a candidate for the fill prefix from the first line---it -tries first the function in @code{adaptive-fill-function} (if any), -then the regular expression @code{adaptive-fill-regexp} (see below). -The first non-@code{nil} result of these, or the empty string if -they're both @code{nil}, becomes the first line's candidate. -@item -If the paragraph has as yet only one line, the function tests the -validity of the prefix candidate just found. The function then -returns the candidate if it's valid, or a string of spaces otherwise. -(see the description of @code{adaptive-fill-first-line-regexp} below). -@item -When the paragraph already has two lines, the function next looks for -a prefix candidate on the second line, in just the same way it did for -the first line. If it doesn't find one, it returns @code{nil}. -@item -The function now compares the two candidate prefixes heuristically: if -the non-whitespace characters in the line 2 candidate occur in the -same order in the line 1 candidate, the function returns the line 2 -candidate. Otherwise, it returns the largest initial substring which -is common to both candidates (which might be the empty string). -@end enumerate -@end defun - -@defopt adaptive-fill-regexp -Adaptive Fill mode matches this regular expression against the text -starting after the left margin whitespace (if any) on a line; the -characters it matches are that line's candidate for the fill prefix. - -The default value matches whitespace with certain punctuation -characters intermingled. -@end defopt - -@defopt adaptive-fill-first-line-regexp -Used only in one-line paragraphs, this regular expression acts as an -additional check of the validity of the one available candidate fill -prefix: the candidate must match this regular expression, or match -@code{comment-start-skip}. If it doesn't, @code{fill-context-prefix} -replaces the candidate with a string of spaces ``of the same width'' -as it. - -The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which -matches only a string of whitespace. The effect of this default is to -force the fill prefixes found in one-line paragraphs always to be pure -whitespace. -@end defopt - -@defopt adaptive-fill-function -You can specify more complex ways of choosing a fill prefix -automatically by setting this variable to a function. The function is -called with point after the left margin (if any) of a line, and it -must preserve point. It should return either ``that line's'' fill -prefix or @code{nil}, meaning it has failed to determine a prefix. -@end defopt - -@node Auto Filling -@comment node-name, next, previous, up -@section Auto Filling -@cindex filling, automatic -@cindex Auto Fill mode - - Auto Fill mode is a minor mode that fills lines automatically as text -is inserted. This section describes the hook used by Auto Fill mode. -For a description of functions that you can call explicitly to fill and -justify existing text, see @ref{Filling}. - - Auto Fill mode also enables the functions that change the margins and -justification style to refill portions of the text. @xref{Margins}. - -@defvar auto-fill-function -The value of this buffer-local variable should be a function (of no -arguments) to be called after self-inserting a character from the table -@code{auto-fill-chars}. It may be @code{nil}, in which case nothing -special is done in that case. - -The value of @code{auto-fill-function} is @code{do-auto-fill} when -Auto-Fill mode is enabled. That is a function whose sole purpose is to -implement the usual strategy for breaking a line. -@end defvar - -@defvar normal-auto-fill-function -This variable specifies the function to use for -@code{auto-fill-function}, if and when Auto Fill is turned on. Major -modes can set buffer-local values for this variable to alter how Auto -Fill works. -@end defvar - -@defvar auto-fill-chars -A char table of characters which invoke @code{auto-fill-function} when -self-inserted---space and newline in most language environments. They -have an entry @code{t} in the table. -@end defvar - -@node Sorting -@section Sorting Text -@cindex sorting text - - The sorting functions described in this section all rearrange text in -a buffer. This is in contrast to the function @code{sort}, which -rearranges the order of the elements of a list (@pxref{Rearrangement}). -The values returned by these functions are not meaningful. - -@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate -This function is the general text-sorting routine that subdivides a -buffer into records and then sorts them. Most of the commands in this -section use this function. - -To understand how @code{sort-subr} works, consider the whole accessible -portion of the buffer as being divided into disjoint pieces called -@dfn{sort records}. The records may or may not be contiguous, but they -must not overlap. A portion of each sort record (perhaps all of it) is -designated as the sort key. Sorting rearranges the records in order by -their sort keys. - -Usually, the records are rearranged in order of ascending sort key. -If the first argument to the @code{sort-subr} function, @var{reverse}, -is non-@code{nil}, the sort records are rearranged in order of -descending sort key. - -The next four arguments to @code{sort-subr} are functions that are -called to move point across a sort record. They are called many times -from within @code{sort-subr}. - -@enumerate -@item -@var{nextrecfun} is called with point at the end of a record. This -function moves point to the start of the next record. The first record -is assumed to start at the position of point when @code{sort-subr} is -called. Therefore, you should usually move point to the beginning of -the buffer before calling @code{sort-subr}. - -This function can indicate there are no more sort records by leaving -point at the end of the buffer. - -@item -@var{endrecfun} is called with point within a record. It moves point to -the end of the record. - -@item -@var{startkeyfun} is called to move point from the start of a record to -the start of the sort key. This argument is optional; if it is omitted, -the whole record is the sort key. If supplied, the function should -either return a non-@code{nil} value to be used as the sort key, or -return @code{nil} to indicate that the sort key is in the buffer -starting at point. In the latter case, @var{endkeyfun} is called to -find the end of the sort key. - -@item -@var{endkeyfun} is called to move point from the start of the sort key -to the end of the sort key. This argument is optional. If -@var{startkeyfun} returns @code{nil} and this argument is omitted (or -@code{nil}), then the sort key extends to the end of the record. There -is no need for @var{endkeyfun} if @var{startkeyfun} returns a -non-@code{nil} value. -@end enumerate - -The argument @var{predicate} is the function to use to compare keys. -If keys are numbers, it defaults to @code{<}; otherwise it defaults to -@code{string<}. - -As an example of @code{sort-subr}, here is the complete function -definition for @code{sort-lines}: - -@example -@group -;; @r{Note that the first two lines of doc string} -;; @r{are effectively one line when viewed by a user.} -(defun sort-lines (reverse beg end) - "Sort lines in region alphabetically;\ - argument means descending order. -Called from a program, there are three arguments: -@end group -@group -REVERSE (non-nil means reverse order),\ - BEG and END (region to sort). -The variable `sort-fold-case' determines\ - whether alphabetic case affects -the sort order." -@end group -@group - (interactive "P\nr") - (save-excursion - (save-restriction - (narrow-to-region beg end) - (goto-char (point-min)) - (let ((inhibit-field-text-motion t)) - (sort-subr reverse 'forward-line 'end-of-line))))) -@end group -@end example - -Here @code{forward-line} moves point to the start of the next record, -and @code{end-of-line} moves point to the end of record. We do not pass -the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire -record is used as the sort key. - -The @code{sort-paragraphs} function is very much the same, except that -its @code{sort-subr} call looks like this: - -@example -@group -(sort-subr reverse - (function - (lambda () - (while (and (not (eobp)) - (looking-at paragraph-separate)) - (forward-line 1)))) - 'forward-paragraph) -@end group -@end example - -Markers pointing into any sort records are left with no useful -position after @code{sort-subr} returns. -@end defun - -@defopt sort-fold-case -If this variable is non-@code{nil}, @code{sort-subr} and the other -buffer sorting functions ignore case when comparing strings. -@end defopt - -@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end -This command sorts the region between @var{start} and @var{end} -alphabetically as specified by @var{record-regexp} and @var{key-regexp}. -If @var{reverse} is a negative integer, then sorting is in reverse -order. - -Alphabetical sorting means that two sort keys are compared by -comparing the first characters of each, the second characters of each, -and so on. If a mismatch is found, it means that the sort keys are -unequal; the sort key whose character is less at the point of first -mismatch is the lesser sort key. The individual characters are compared -according to their numerical character codes in the Emacs character set. - -The value of the @var{record-regexp} argument specifies how to divide -the buffer into sort records. At the end of each record, a search is -done for this regular expression, and the text that matches it is taken -as the next record. For example, the regular expression @samp{^.+$}, -which matches lines with at least one character besides a newline, would -make each such line into a sort record. @xref{Regular Expressions}, for -a description of the syntax and meaning of regular expressions. - -The value of the @var{key-regexp} argument specifies what part of each -record is the sort key. The @var{key-regexp} could match the whole -record, or only a part. In the latter case, the rest of the record has -no effect on the sorted order of records, but it is carried along when -the record moves to its new position. - -The @var{key-regexp} argument can refer to the text matched by a -subexpression of @var{record-regexp}, or it can be a regular expression -on its own. - -If @var{key-regexp} is: - -@table @asis -@item @samp{\@var{digit}} -then the text matched by the @var{digit}th @samp{\(...\)} parenthesis -grouping in @var{record-regexp} is the sort key. - -@item @samp{\&} -then the whole record is the sort key. - -@item a regular expression -then @code{sort-regexp-fields} searches for a match for the regular -expression within the record. If such a match is found, it is the sort -key. If there is no match for @var{key-regexp} within a record then -that record is ignored, which means its position in the buffer is not -changed. (The other records may move around it.) -@end table - -For example, if you plan to sort all the lines in the region by the -first word on each line starting with the letter @samp{f}, you should -set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to -@samp{\}. The resulting expression looks like this: - -@example -@group -(sort-regexp-fields nil "^.*$" "\\" - (region-beginning) - (region-end)) -@end group -@end example - -If you call @code{sort-regexp-fields} interactively, it prompts for -@var{record-regexp} and @var{key-regexp} in the minibuffer. -@end deffn - -@deffn Command sort-lines reverse start end -This command alphabetically sorts lines in the region between -@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort -is in reverse order. -@end deffn - -@deffn Command sort-paragraphs reverse start end -This command alphabetically sorts paragraphs in the region between -@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort -is in reverse order. -@end deffn - -@deffn Command sort-pages reverse start end -This command alphabetically sorts pages in the region between -@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort -is in reverse order. -@end deffn - -@deffn Command sort-fields field start end -This command sorts lines in the region between @var{start} and -@var{end}, comparing them alphabetically by the @var{field}th field -of each line. Fields are separated by whitespace and numbered starting -from 1. If @var{field} is negative, sorting is by the -@w{@minus{}@var{field}th} field from the end of the line. This command -is useful for sorting tables. -@end deffn - -@deffn Command sort-numeric-fields field start end -This command sorts lines in the region between @var{start} and -@var{end}, comparing them numerically by the @var{field}th field of -each line. Fields are separated by whitespace and numbered starting -from 1. The specified field must contain a number in each line of the -region. Numbers starting with 0 are treated as octal, and numbers -starting with @samp{0x} are treated as hexadecimal. - -If @var{field} is negative, sorting is by the -@w{@minus{}@var{field}th} field from the end of the line. This -command is useful for sorting tables. -@end deffn - -@defopt sort-numeric-base -This variable specifies the default radix for -@code{sort-numeric-fields} to parse numbers. -@end defopt - -@deffn Command sort-columns reverse &optional beg end -This command sorts the lines in the region between @var{beg} and -@var{end}, comparing them alphabetically by a certain range of -columns. The column positions of @var{beg} and @var{end} bound the -range of columns to sort on. - -If @var{reverse} is non-@code{nil}, the sort is in reverse order. - -One unusual thing about this command is that the entire line -containing position @var{beg}, and the entire line containing position -@var{end}, are included in the region sorted. - -Note that @code{sort-columns} rejects text that contains tabs, because -tabs could be split across the specified columns. Use @kbd{M-x -untabify} to convert tabs to spaces before sorting. - -When possible, this command actually works by calling the @code{sort} -utility program. -@end deffn - -@node Columns -@comment node-name, next, previous, up -@section Counting Columns -@cindex columns -@cindex counting columns -@cindex horizontal position - - The column functions convert between a character position (counting -characters from the beginning of the buffer) and a column position -(counting screen characters from the beginning of a line). - - These functions count each character according to the number of -columns it occupies on the screen. This means control characters count -as occupying 2 or 4 columns, depending upon the value of -@code{ctl-arrow}, and tabs count as occupying a number of columns that -depends on the value of @code{tab-width} and on the column where the tab -begins. @xref{Usual Display}. - - Column number computations ignore the width of the window and the -amount of horizontal scrolling. Consequently, a column value can be -arbitrarily high. The first (or leftmost) column is numbered 0. They -also ignore overlays and text properties, aside from invisibility. - -@defun current-column -This function returns the horizontal position of point, measured in -columns, counting from 0 at the left margin. The column position is the -sum of the widths of all the displayed representations of the characters -between the start of the current line and point. - -For an example of using @code{current-column}, see the description of -@code{count-lines} in @ref{Text Lines}. -@end defun - -@deffn Command move-to-column column &optional force -This function moves point to @var{column} in the current line. The -calculation of @var{column} takes into account the widths of the -displayed representations of the characters between the start of the -line and point. - -When called interactively, @var{column} is the value of prefix numeric -argument. If @var{column} is not an integer, an error is signaled. - -If column @var{column} is beyond the end of the line, point moves to -the end of the line. If @var{column} is negative, point moves to the -beginning of the line. - -If it is impossible to move to column @var{column} because that is in -the middle of a multicolumn character such as a tab, point moves to the -end of that character. However, if @var{force} is non-@code{nil}, and -@var{column} is in the middle of a tab, then @code{move-to-column} -converts the tab into spaces so that it can move precisely to column -@var{column}. Other multicolumn characters can cause anomalies despite -@var{force}, since there is no way to split them. - -The argument @var{force} also has an effect if the line isn't long -enough to reach column @var{column}; if it is @code{t}, that means to -add whitespace at the end of the line to reach that column. - -The return value is the column number actually moved to. -@end deffn - -@node Indentation -@section Indentation -@cindex indentation - - The indentation functions are used to examine, move to, and change -whitespace that is at the beginning of a line. Some of the functions -can also change whitespace elsewhere on a line. Columns and indentation -count from zero at the left margin. - -@menu -* Primitive Indent:: Functions used to count and insert indentation. -* Mode-Specific Indent:: Customize indentation for different modes. -* Region Indent:: Indent all the lines in a region. -* Relative Indent:: Indent the current line based on previous lines. -* Indent Tabs:: Adjustable, typewriter-like tab stops. -* Motion by Indent:: Move to first non-blank character. -@end menu - -@node Primitive Indent -@subsection Indentation Primitives - - This section describes the primitive functions used to count and -insert indentation. The functions in the following sections use these -primitives. @xref{Width}, for related functions. - -@defun current-indentation -@comment !!Type Primitive Function -@comment !!SourceFile indent.c -This function returns the indentation of the current line, which is -the horizontal position of the first nonblank character. If the -contents are entirely blank, then this is the horizontal position of the -end of the line. -@end defun - -@deffn Command indent-to column &optional minimum -@comment !!Type Primitive Function -@comment !!SourceFile indent.c -This function indents from point with tabs and spaces until @var{column} -is reached. If @var{minimum} is specified and non-@code{nil}, then at -least that many spaces are inserted even if this requires going beyond -@var{column}. Otherwise the function does nothing if point is already -beyond @var{column}. The value is the column at which the inserted -indentation ends. - -The inserted whitespace characters inherit text properties from the -surrounding text (usually, from the preceding text only). @xref{Sticky -Properties}. -@end deffn - -@defopt indent-tabs-mode -@comment !!SourceFile indent.c -If this variable is non-@code{nil}, indentation functions can insert -tabs as well as spaces. Otherwise, they insert only spaces. Setting -this variable automatically makes it buffer-local in the current buffer. -@end defopt - -@node Mode-Specific Indent -@subsection Indentation Controlled by Major Mode - - An important function of each major mode is to customize the @key{TAB} -key to indent properly for the language being edited. This section -describes the mechanism of the @key{TAB} key and how to control it. -The functions in this section return unpredictable values. - -@deffn Command indent-for-tab-command &optional rigid -This is the command bound to @key{TAB} in most editing modes. Its -usual action is to indent the current line, but it can alternatively -insert a tab character or indent a region. - -Here is what it does: - -@itemize -@item -First, it checks whether Transient Mark mode is enabled and the region -is active. If so, it called @code{indent-region} to indent all the -text in the region (@pxref{Region Indent}). - -@item -Otherwise, if the indentation function in @code{indent-line-function} -is @code{indent-to-left-margin} (a trivial command that inserts a tab -character), or if the variable @code{tab-always-indent} specifies that -a tab character ought to be inserted (see below), then it inserts a -tab character. - -@item -Otherwise, it indents the current line; this is done by calling the -function in @code{indent-line-function}. If the line is already -indented, and the value of @code{tab-always-indent} is @code{complete} -(see below), it tries completing the text at point. -@end itemize - -If @var{rigid} is non-@code{nil} (interactively, with a prefix -argument), then after this command indents a line or inserts a tab, it -also rigidly indents the entire balanced expression which starts at -the beginning of the current line, in order to reflect the new -indentation. This argument is ignored if the command indents the -region. -@end deffn - -@defvar indent-line-function -This variable's value is the function to be used by -@code{indent-for-tab-command}, and various other indentation commands, -to indent the current line. It is usually assigned by the major mode; -for instance, Lisp mode sets it to @code{lisp-indent-line}, C mode -sets it to @code{c-indent-line}, and so on. The default value is -@code{indent-relative}. @xref{Auto-Indentation}. -@end defvar - -@deffn Command indent-according-to-mode -This command calls the function in @code{indent-line-function} to -indent the current line in a way appropriate for the current major mode. -@end deffn - -@deffn Command newline-and-indent -This function inserts a newline, then indents the new line (the one -following the newline just inserted) according to the major mode. It -does indentation by calling @code{indent-according-to-mode}. -@end deffn - -@deffn Command reindent-then-newline-and-indent -This command reindents the current line, inserts a newline at point, -and then indents the new line (the one following the newline just -inserted). It does indentation on both lines by calling -@code{indent-according-to-mode}. -@end deffn - -@defopt tab-always-indent -This variable can be used to customize the behavior of the @key{TAB} -(@code{indent-for-tab-command}) command. If the value is @code{t} -(the default), the command normally just indents the current line. If -the value is @code{nil}, the command indents the current line only if -point is at the left margin or in the line's indentation; otherwise, -it inserts a tab character. If the value is @code{complete}, the -command first tries to indent the current line, and if the line was -already indented, it calls @code{completion-at-point} to complete the -text at point (@pxref{Completion in Buffers}). -@end defopt - -@node Region Indent -@subsection Indenting an Entire Region - - This section describes commands that indent all the lines in the -region. They return unpredictable values. - -@deffn Command indent-region start end &optional to-column -This command indents each nonblank line starting between @var{start} -(inclusive) and @var{end} (exclusive). If @var{to-column} is -@code{nil}, @code{indent-region} indents each nonblank line by calling -the current mode's indentation function, the value of -@code{indent-line-function}. - -If @var{to-column} is non-@code{nil}, it should be an integer -specifying the number of columns of indentation; then this function -gives each line exactly that much indentation, by either adding or -deleting whitespace. - -If there is a fill prefix, @code{indent-region} indents each line -by making it start with the fill prefix. -@end deffn - -@defvar indent-region-function -The value of this variable is a function that can be used by -@code{indent-region} as a short cut. It should take two arguments, the -start and end of the region. You should design the function so -that it will produce the same results as indenting the lines of the -region one by one, but presumably faster. - -If the value is @code{nil}, there is no short cut, and -@code{indent-region} actually works line by line. - -A short-cut function is useful in modes such as C mode and Lisp mode, -where the @code{indent-line-function} must scan from the beginning of -the function definition: applying it to each line would be quadratic in -time. The short cut can update the scan information as it moves through -the lines indenting them; this takes linear time. In a mode where -indenting a line individually is fast, there is no need for a short cut. - -@code{indent-region} with a non-@code{nil} argument @var{to-column} has -a different meaning and does not use this variable. -@end defvar - -@deffn Command indent-rigidly start end count -This command indents all lines starting between @var{start} -(inclusive) and @var{end} (exclusive) sideways by @var{count} columns. -This ``preserves the shape'' of the affected region, moving it as a -rigid unit. Consequently, this command is useful not only for indenting -regions of unindented text, but also for indenting regions of formatted -code. - -For example, if @var{count} is 3, this command adds 3 columns of -indentation to each of the lines beginning in the region specified. - -In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses -@code{indent-rigidly} to indent the text copied from the message being -replied to. -@end deffn - -@deffn Command indent-code-rigidly start end columns &optional nochange-regexp -This is like @code{indent-rigidly}, except that it doesn't alter lines -that start within strings or comments. - -In addition, it doesn't alter a line if @var{nochange-regexp} matches at -the beginning of the line (if @var{nochange-regexp} is non-@code{nil}). -@end deffn - -@node Relative Indent -@subsection Indentation Relative to Previous Lines - - This section describes two commands that indent the current line -based on the contents of previous lines. - -@deffn Command indent-relative &optional unindented-ok -This command inserts whitespace at point, extending to the same -column as the next @dfn{indent point} of the previous nonblank line. An -indent point is a non-whitespace character following whitespace. The -next indent point is the first one at a column greater than the current -column of point. For example, if point is underneath and to the left of -the first non-blank character of a line of text, it moves to that column -by inserting whitespace. - -If the previous nonblank line has no next indent point (i.e., none at a -great enough column position), @code{indent-relative} either does -nothing (if @var{unindented-ok} is non-@code{nil}) or calls -@code{tab-to-tab-stop}. Thus, if point is underneath and to the right -of the last column of a short line of text, this command ordinarily -moves point to the next tab stop by inserting whitespace. - -The return value of @code{indent-relative} is unpredictable. - -In the following example, point is at the beginning of the second -line: - -@example -@group - This line is indented twelve spaces. -@point{}The quick brown fox jumped. -@end group -@end example - -@noindent -Evaluation of the expression @code{(indent-relative nil)} produces the -following: - -@example -@group - This line is indented twelve spaces. - @point{}The quick brown fox jumped. -@end group -@end example - - In this next example, point is between the @samp{m} and @samp{p} of -@samp{jumped}: - -@example -@group - This line is indented twelve spaces. -The quick brown fox jum@point{}ped. -@end group -@end example - -@noindent -Evaluation of the expression @code{(indent-relative nil)} produces the -following: - -@example -@group - This line is indented twelve spaces. -The quick brown fox jum @point{}ped. -@end group -@end example -@end deffn - -@deffn Command indent-relative-maybe -@comment !!SourceFile indent.el -This command indents the current line like the previous nonblank line, -by calling @code{indent-relative} with @code{t} as the -@var{unindented-ok} argument. The return value is unpredictable. - -If the previous nonblank line has no indent points beyond the current -column, this command does nothing. -@end deffn - -@node Indent Tabs -@comment node-name, next, previous, up -@subsection Adjustable ``Tab Stops'' -@cindex tabs stops for indentation - - This section explains the mechanism for user-specified ``tab stops'' -and the mechanisms that use and set them. The name ``tab stops'' is -used because the feature is similar to that of the tab stops on a -typewriter. The feature works by inserting an appropriate number of -spaces and tab characters to reach the next tab stop column; it does not -affect the display of tab characters in the buffer (@pxref{Usual -Display}). Note that the @key{TAB} character as input uses this tab -stop feature only in a few major modes, such as Text mode. -@xref{Tab Stops,,, emacs, The GNU Emacs Manual}. - -@deffn Command tab-to-tab-stop -This command inserts spaces or tabs before point, up to the next tab -stop column defined by @code{tab-stop-list}. It searches the list for -an element greater than the current column number, and uses that element -as the column to indent to. It does nothing if no such element is -found. -@end deffn - -@defopt tab-stop-list -This variable is the list of tab stop columns used by -@code{tab-to-tab-stops}. The elements should be integers in increasing -order. The tab stop columns need not be evenly spaced. - -Use @kbd{M-x edit-tab-stops} to edit the location of tab stops -interactively. -@end defopt - -@node Motion by Indent -@subsection Indentation-Based Motion Commands - - These commands, primarily for interactive use, act based on the -indentation in the text. - -@deffn Command back-to-indentation -@comment !!SourceFile simple.el -This command moves point to the first non-whitespace character in the -current line (which is the line in which point is located). It returns -@code{nil}. -@end deffn - -@deffn Command backward-to-indentation &optional arg -@comment !!SourceFile simple.el -This command moves point backward @var{arg} lines and then to the -first nonblank character on that line. It returns @code{nil}. -If @var{arg} is omitted or @code{nil}, it defaults to 1. -@end deffn - -@deffn Command forward-to-indentation &optional arg -@comment !!SourceFile simple.el -This command moves point forward @var{arg} lines and then to the first -nonblank character on that line. It returns @code{nil}. -If @var{arg} is omitted or @code{nil}, it defaults to 1. -@end deffn - -@node Case Changes -@comment node-name, next, previous, up -@section Case Changes -@cindex case conversion in buffers - - The case change commands described here work on text in the current -buffer. @xref{Case Conversion}, for case conversion functions that work -on strings and characters. @xref{Case Tables}, for how to customize -which characters are upper or lower case and how to convert them. - -@deffn Command capitalize-region start end -This function capitalizes all words in the region defined by -@var{start} and @var{end}. To capitalize means to convert each word's -first character to upper case and convert the rest of each word to lower -case. The function returns @code{nil}. - -If one end of the region is in the middle of a word, the part of the -word within the region is treated as an entire word. - -When @code{capitalize-region} is called interactively, @var{start} and -@var{end} are point and the mark, with the smallest first. - -@example -@group ----------- Buffer: foo ---------- -This is the contents of the 5th foo. ----------- Buffer: foo ---------- -@end group - -@group -(capitalize-region 1 44) -@result{} nil - ----------- Buffer: foo ---------- -This Is The Contents Of The 5th Foo. ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command downcase-region start end -This function converts all of the letters in the region defined by -@var{start} and @var{end} to lower case. The function returns -@code{nil}. - -When @code{downcase-region} is called interactively, @var{start} and -@var{end} are point and the mark, with the smallest first. -@end deffn - -@deffn Command upcase-region start end -This function converts all of the letters in the region defined by -@var{start} and @var{end} to upper case. The function returns -@code{nil}. - -When @code{upcase-region} is called interactively, @var{start} and -@var{end} are point and the mark, with the smallest first. -@end deffn - -@deffn Command capitalize-word count -This function capitalizes @var{count} words after point, moving point -over as it does. To capitalize means to convert each word's first -character to upper case and convert the rest of each word to lower case. -If @var{count} is negative, the function capitalizes the -@minus{}@var{count} previous words but does not move point. The value -is @code{nil}. - -If point is in the middle of a word, the part of the word before point -is ignored when moving forward. The rest is treated as an entire word. - -When @code{capitalize-word} is called interactively, @var{count} is -set to the numeric prefix argument. -@end deffn - -@deffn Command downcase-word count -This function converts the @var{count} words after point to all lower -case, moving point over as it does. If @var{count} is negative, it -converts the @minus{}@var{count} previous words but does not move point. -The value is @code{nil}. - -When @code{downcase-word} is called interactively, @var{count} is set -to the numeric prefix argument. -@end deffn - -@deffn Command upcase-word count -This function converts the @var{count} words after point to all upper -case, moving point over as it does. If @var{count} is negative, it -converts the @minus{}@var{count} previous words but does not move point. -The value is @code{nil}. - -When @code{upcase-word} is called interactively, @var{count} is set to -the numeric prefix argument. -@end deffn - -@node Text Properties -@section Text Properties -@cindex text properties -@cindex attributes of text -@cindex properties of text - - Each character position in a buffer or a string can have a @dfn{text -property list}, much like the property list of a symbol (@pxref{Property -Lists}). The properties belong to a particular character at a -particular place, such as, the letter @samp{T} at the beginning of this -sentence or the first @samp{o} in @samp{foo}---if the same character -occurs in two different places, the two occurrences in general have -different properties. - - Each property has a name and a value. Both of these can be any Lisp -object, but the name is normally a symbol. Typically each property -name symbol is used for a particular purpose; for instance, the text -property @code{face} specifies the faces for displaying the character -(@pxref{Special Properties}). The usual way to access the property -list is to specify a name and ask what value corresponds to it. - - If a character has a @code{category} property, we call it the -@dfn{property category} of the character. It should be a symbol. The -properties of the symbol serve as defaults for the properties of the -character. - - Copying text between strings and buffers preserves the properties -along with the characters; this includes such diverse functions as -@code{substring}, @code{insert}, and @code{buffer-substring}. - -@menu -* Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. -* Format Properties:: Properties for representing formatting of text. -* Sticky Properties:: How inserted text gets properties from - neighboring text. -* Lazy Properties:: Computing text properties in a lazy fashion - only when text is examined. -* Clickable Text:: Using text properties to make regions of text - do something when you click on them. -* Fields:: The @code{field} property defines - fields within the buffer. -* Not Intervals:: Why text properties do not use - Lisp-visible text intervals. -@end menu - -@node Examining Properties -@subsection Examining Text Properties - - The simplest way to examine text properties is to ask for the value of -a particular property of a particular character. For that, use -@code{get-text-property}. Use @code{text-properties-at} to get the -entire property list of a character. @xref{Property Search}, for -functions to examine the properties of a number of characters at once. - - These functions handle both strings and buffers. Keep in mind that -positions in a string start from 0, whereas positions in a buffer start -from 1. - -@defun get-text-property pos prop &optional object -This function returns the value of the @var{prop} property of the -character after position @var{pos} in @var{object} (a buffer or -string). The argument @var{object} is optional and defaults to the -current buffer. - -If there is no @var{prop} property strictly speaking, but the character -has a property category that is a symbol, then @code{get-text-property} returns -the @var{prop} property of that symbol. -@end defun - -@defun get-char-property position prop &optional object -This function is like @code{get-text-property}, except that it checks -overlays first and then text properties. @xref{Overlays}. - -The argument @var{object} may be a string, a buffer, or a window. If -it is a window, then the buffer displayed in that window is used for -text properties and overlays, but only the overlays active for that -window are considered. If @var{object} is a buffer, then overlays in -that buffer are considered first, in order of decreasing priority, -followed by the text properties. If @var{object} is a string, only -text properties are considered, since strings never have overlays. -@end defun - -@defun get-char-property-and-overlay position prop &optional object -This is like @code{get-char-property}, but gives extra information -about the overlay that the property value comes from. - -Its value is a cons cell whose @sc{car} is the property value, the -same value @code{get-char-property} would return with the same -arguments. Its @sc{cdr} is the overlay in which the property was -found, or @code{nil}, if it was found as a text property or not found -at all. - -If @var{position} is at the end of @var{object}, both the @sc{car} and -the @sc{cdr} of the value are @code{nil}. -@end defun - -@defvar char-property-alias-alist -This variable holds an alist which maps property names to a list of -alternative property names. If a character does not specify a direct -value for a property, the alternative property names are consulted in -order; the first non-@code{nil} value is used. This variable takes -precedence over @code{default-text-properties}, and @code{category} -properties take precedence over this variable. -@end defvar - -@defun text-properties-at position &optional object -This function returns the entire property list of the character at -@var{position} in the string or buffer @var{object}. If @var{object} is -@code{nil}, it defaults to the current buffer. -@end defun - -@defvar default-text-properties -This variable holds a property list giving default values for text -properties. Whenever a character does not specify a value for a -property, neither directly, through a category symbol, or through -@code{char-property-alias-alist}, the value stored in this list is -used instead. Here is an example: - -@example -(setq default-text-properties '(foo 69) - char-property-alias-alist nil) -;; @r{Make sure character 1 has no properties of its own.} -(set-text-properties 1 2 nil) -;; @r{What we get, when we ask, is the default value.} -(get-text-property 1 'foo) - @result{} 69 -@end example -@end defvar - -@node Changing Properties -@subsection Changing Text Properties - - The primitives for changing properties apply to a specified range of -text in a buffer or string. The function @code{set-text-properties} -(see end of section) sets the entire property list of the text in that -range; more often, it is useful to add, change, or delete just certain -properties specified by name. - - Since text properties are considered part of the contents of the -buffer (or string), and can affect how a buffer looks on the screen, -any change in buffer text properties marks the buffer as modified. -Buffer text property changes are undoable also (@pxref{Undo}). -Positions in a string start from 0, whereas positions in a buffer -start from 1. - -@defun put-text-property start end prop value &optional object -This function sets the @var{prop} property to @var{value} for the text -between @var{start} and @var{end} in the string or buffer @var{object}. -If @var{object} is @code{nil}, it defaults to the current buffer. -@end defun - -@defun add-text-properties start end props &optional object -This function adds or overrides text properties for the text between -@var{start} and @var{end} in the string or buffer @var{object}. If -@var{object} is @code{nil}, it defaults to the current buffer. - -The argument @var{props} specifies which properties to add. It should -have the form of a property list (@pxref{Property Lists}): a list whose -elements include the property names followed alternately by the -corresponding values. - -The return value is @code{t} if the function actually changed some -property's value; @code{nil} otherwise (if @var{props} is @code{nil} or -its values agree with those in the text). - -For example, here is how to set the @code{comment} and @code{face} -properties of a range of text: - -@example -(add-text-properties @var{start} @var{end} - '(comment t face highlight)) -@end example -@end defun - -@defun remove-text-properties start end props &optional object -This function deletes specified text properties from the text between -@var{start} and @var{end} in the string or buffer @var{object}. If -@var{object} is @code{nil}, it defaults to the current buffer. - -The argument @var{props} specifies which properties to delete. It -should have the form of a property list (@pxref{Property Lists}): a list -whose elements are property names alternating with corresponding values. -But only the names matter---the values that accompany them are ignored. -For example, here's how to remove the @code{face} property. - -@example -(remove-text-properties @var{start} @var{end} '(face nil)) -@end example - -The return value is @code{t} if the function actually changed some -property's value; @code{nil} otherwise (if @var{props} is @code{nil} or -if no character in the specified text had any of those properties). - -To remove all text properties from certain text, use -@code{set-text-properties} and specify @code{nil} for the new property -list. -@end defun - -@defun remove-list-of-text-properties start end list-of-properties &optional object -Like @code{remove-text-properties} except that -@var{list-of-properties} is a list of property names only, not an -alternating list of property names and values. -@end defun - -@defun set-text-properties start end props &optional object -This function completely replaces the text property list for the text -between @var{start} and @var{end} in the string or buffer @var{object}. -If @var{object} is @code{nil}, it defaults to the current buffer. - -The argument @var{props} is the new property list. It should be a list -whose elements are property names alternating with corresponding values. - -After @code{set-text-properties} returns, all the characters in the -specified range have identical properties. - -If @var{props} is @code{nil}, the effect is to get rid of all properties -from the specified range of text. Here's an example: - -@example -(set-text-properties @var{start} @var{end} nil) -@end example - -Do not rely on the return value of this function. -@end defun - - The easiest way to make a string with text properties -is with @code{propertize}: - -@defun propertize string &rest properties -This function returns a copy of @var{string} which has the text -properties @var{properties}. These properties apply to all the -characters in the string that is returned. Here is an example that -constructs a string with a @code{face} property and a @code{mouse-face} -property: - -@smallexample -(propertize "foo" 'face 'italic - 'mouse-face 'bold-italic) - @result{} #("foo" 0 3 (mouse-face bold-italic face italic)) -@end smallexample - -To put different properties on various parts of a string, you can -construct each part with @code{propertize} and then combine them with -@code{concat}: - -@smallexample -(concat - (propertize "foo" 'face 'italic - 'mouse-face 'bold-italic) - " and " - (propertize "bar" 'face 'italic - 'mouse-face 'bold-italic)) - @result{} #("foo and bar" - 0 3 (face italic mouse-face bold-italic) - 3 8 nil - 8 11 (face italic mouse-face bold-italic)) -@end smallexample -@end defun - - @xref{Buffer Contents}, for the function -@code{buffer-substring-no-properties}, which copies text from the -buffer but does not copy its properties. - -@node Property Search -@subsection Text Property Search Functions - - In typical use of text properties, most of the time several or many -consecutive characters have the same value for a property. Rather than -writing your programs to examine characters one by one, it is much -faster to process chunks of text that have the same property value. - - Here are functions you can use to do this. They use @code{eq} for -comparing property values. In all cases, @var{object} defaults to the -current buffer. - - For good performance, it's very important to use the @var{limit} -argument to these functions, especially the ones that search for a -single property---otherwise, they may spend a long time scanning to the -end of the buffer, if the property you are interested in does not change. - - These functions do not move point; instead, they return a position (or -@code{nil}). Remember that a position is always between two characters; -the position returned by these functions is between two characters with -different properties. - -@defun next-property-change pos &optional object limit -The function scans the text forward from position @var{pos} in the -string or buffer @var{object} until it finds a change in some text -property, then returns the position of the change. In other words, it -returns the position of the first character beyond @var{pos} whose -properties are not identical to those of the character just after -@var{pos}. - -If @var{limit} is non-@code{nil}, then the scan ends at position -@var{limit}. If there is no property change before that point, this -function returns @var{limit}. - -The value is @code{nil} if the properties remain unchanged all the way -to the end of @var{object} and @var{limit} is @code{nil}. If the value -is non-@code{nil}, it is a position greater than or equal to @var{pos}. -The value equals @var{pos} only when @var{limit} equals @var{pos}. - -Here is an example of how to scan the buffer by chunks of text within -which all properties are constant: - -@smallexample -(while (not (eobp)) - (let ((plist (text-properties-at (point))) - (next-change - (or (next-property-change (point) (current-buffer)) - (point-max)))) - @r{Process text from point to @var{next-change}@dots{}} - (goto-char next-change))) -@end smallexample -@end defun - -@defun previous-property-change pos &optional object limit -This is like @code{next-property-change}, but scans back from @var{pos} -instead of forward. If the value is non-@code{nil}, it is a position -less than or equal to @var{pos}; it equals @var{pos} only if @var{limit} -equals @var{pos}. -@end defun - -@defun next-single-property-change pos prop &optional object limit -The function scans text for a change in the @var{prop} property, then -returns the position of the change. The scan goes forward from -position @var{pos} in the string or buffer @var{object}. In other -words, this function returns the position of the first character -beyond @var{pos} whose @var{prop} property differs from that of the -character just after @var{pos}. - -If @var{limit} is non-@code{nil}, then the scan ends at position -@var{limit}. If there is no property change before that point, -@code{next-single-property-change} returns @var{limit}. - -The value is @code{nil} if the property remains unchanged all the way to -the end of @var{object} and @var{limit} is @code{nil}. If the value is -non-@code{nil}, it is a position greater than or equal to @var{pos}; it -equals @var{pos} only if @var{limit} equals @var{pos}. -@end defun - -@defun previous-single-property-change pos prop &optional object limit -This is like @code{next-single-property-change}, but scans back from -@var{pos} instead of forward. If the value is non-@code{nil}, it is a -position less than or equal to @var{pos}; it equals @var{pos} only if -@var{limit} equals @var{pos}. -@end defun - -@defun next-char-property-change pos &optional limit -This is like @code{next-property-change} except that it considers -overlay properties as well as text properties, and if no change is -found before the end of the buffer, it returns the maximum buffer -position rather than @code{nil} (in this sense, it resembles the -corresponding overlay function @code{next-overlay-change}, rather than -@code{next-property-change}). There is no @var{object} operand -because this function operates only on the current buffer. It returns -the next address at which either kind of property changes. -@end defun - -@defun previous-char-property-change pos &optional limit -This is like @code{next-char-property-change}, but scans back from -@var{pos} instead of forward, and returns the minimum buffer -position if no change is found. -@end defun - -@defun next-single-char-property-change pos prop &optional object limit -This is like @code{next-single-property-change} except that it -considers overlay properties as well as text properties, and if no -change is found before the end of the @var{object}, it returns the -maximum valid position in @var{object} rather than @code{nil}. Unlike -@code{next-char-property-change}, this function @emph{does} have an -@var{object} operand; if @var{object} is not a buffer, only -text-properties are considered. -@end defun - -@defun previous-single-char-property-change pos prop &optional object limit -This is like @code{next-single-char-property-change}, but scans back -from @var{pos} instead of forward, and returns the minimum valid -position in @var{object} if no change is found. -@end defun - -@defun text-property-any start end prop value &optional object -This function returns non-@code{nil} if at least one character between -@var{start} and @var{end} has a property @var{prop} whose value is -@var{value}. More precisely, it returns the position of the first such -character. Otherwise, it returns @code{nil}. - -The optional fifth argument, @var{object}, specifies the string or -buffer to scan. Positions are relative to @var{object}. The default -for @var{object} is the current buffer. -@end defun - -@defun text-property-not-all start end prop value &optional object -This function returns non-@code{nil} if at least one character between -@var{start} and @var{end} does not have a property @var{prop} with value -@var{value}. More precisely, it returns the position of the first such -character. Otherwise, it returns @code{nil}. - -The optional fifth argument, @var{object}, specifies the string or -buffer to scan. Positions are relative to @var{object}. The default -for @var{object} is the current buffer. -@end defun - -@node Special Properties -@subsection Properties with Special Meanings - - Here is a table of text property names that have special built-in -meanings. The following sections list a few additional special property -names that control filling and property inheritance. All other names -have no standard meaning, and you can use them as you like. - - Note: the properties @code{composition}, @code{display}, -@code{invisible} and @code{intangible} can also cause point to move to -an acceptable place, after each Emacs command. @xref{Adjusting -Point}. - -@table @code -@cindex property category of text character -@kindex category @r{(text property)} -@item category -If a character has a @code{category} property, we call it the -@dfn{property category} of the character. It should be a symbol. The -properties of this symbol serve as defaults for the properties of the -character. - -@item face -@cindex face codes of text -@kindex face @r{(text property)} -The @code{face} property controls the appearance of the character, -such as its font and color. @xref{Faces}. The value of the property -can be the following: - -@itemize @bullet -@item -A face name (a symbol or string). - -@item -A property list of face attributes. This has the -form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a -face attribute name and @var{value} is a meaningful value for that -attribute. With this feature, you do not need to create a face each -time you want to specify a particular attribute for certain text. -@xref{Face Attributes}. - -@item -A list, where each element uses one of the two forms listed above. -@end itemize - -Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by -dynamically updating the @code{face} property of characters based on -the context. - -@item font-lock-face -@kindex font-lock-face @r{(text property)} -This property specifies a value for the @code{face} property that Font -Lock mode should apply to the underlying text. It is one of the -fontification methods used by Font Lock mode, and is useful for -special modes that implement their own highlighting. -@xref{Precalculated Fontification}. When Font Lock mode is disabled, -@code{font-lock-face} has no effect. - -@item mouse-face -@kindex mouse-face @r{(text property)} -This property is used instead of @code{face} when the mouse is on or -near the character. For this purpose, ``near'' means that all text -between the character and where the mouse is have the same -@code{mouse-face} property value. - -Emacs ignores all face attributes from the @code{mouse-face} property -that alter the text size (e.g. @code{:height}, @code{:weight}, and -@code{:slant}). Those attributes are always the same as for the -unhighlighted text. - -@item fontified -@kindex fontified @r{(text property)} -This property says whether the text is ready for display. If -@code{nil}, Emacs's redisplay routine calls the functions in -@code{fontification-functions} (@pxref{Auto Faces}) to prepare this -part of the buffer before it is displayed. It is used internally by -the ``just in time'' font locking code. - -@item display -This property activates various features that change the -way text is displayed. For example, it can make text appear taller -or shorter, higher or lower, wider or narrow, or replaced with an image. -@xref{Display Property}. - -@item help-echo -@kindex help-echo @r{(text property)} -@cindex tooltip -@anchor{Text help-echo} -If text has a string as its @code{help-echo} property, then when you -move the mouse onto that text, Emacs displays that string in the echo -area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs -Manual}). - -If the value of the @code{help-echo} property is a function, that -function is called with three arguments, @var{window}, @var{object} and -@var{pos} and should return a help string or @code{nil} for -none. The first argument, @var{window} is the window in which -the help was found. The second, @var{object}, is the buffer, overlay or -string which had the @code{help-echo} property. The @var{pos} -argument is as follows: - -@itemize @bullet{} -@item -If @var{object} is a buffer, @var{pos} is the position in the buffer. -@item -If @var{object} is an overlay, that overlay has a @code{help-echo} -property, and @var{pos} is the position in the overlay's buffer. -@item -If @var{object} is a string (an overlay string or a string displayed -with the @code{display} property), @var{pos} is the position in that -string. -@end itemize - -If the value of the @code{help-echo} property is neither a function nor -a string, it is evaluated to obtain a help string. - -You can alter the way help text is displayed by setting the variable -@code{show-help-function} (@pxref{Help display}). - -This feature is used in the mode line and for other active text. - -@item keymap -@cindex keymap of character -@kindex keymap @r{(text property)} -The @code{keymap} property specifies an additional keymap for -commands. When this keymap applies, it is used for key lookup before -the minor mode keymaps and before the buffer's local map. -@xref{Active Keymaps}. If the property value is a symbol, the -symbol's function definition is used as the keymap. - -The property's value for the character before point applies if it is -non-@code{nil} and rear-sticky, and the property's value for the -character after point applies if it is non-@code{nil} and -front-sticky. (For mouse clicks, the position of the click is used -instead of the position of point.) - -@item local-map -@kindex local-map @r{(text property)} -This property works like @code{keymap} except that it specifies a -keymap to use @emph{instead of} the buffer's local map. For most -purposes (perhaps all purposes), it is better to use the @code{keymap} -property. - -@item syntax-table -The @code{syntax-table} property overrides what the syntax table says -about this particular character. @xref{Syntax Properties}. - -@item read-only -@cindex read-only character -@kindex read-only @r{(text property)} -If a character has the property @code{read-only}, then modifying that -character is not allowed. Any command that would do so gets an error, -@code{text-read-only}. If the property value is a string, that string -is used as the error message. - -Insertion next to a read-only character is an error if inserting -ordinary text there would inherit the @code{read-only} property due to -stickiness. Thus, you can control permission to insert next to -read-only text by controlling the stickiness. @xref{Sticky Properties}. - -Since changing properties counts as modifying the buffer, it is not -possible to remove a @code{read-only} property unless you know the -special trick: bind @code{inhibit-read-only} to a non-@code{nil} value -and then remove the property. @xref{Read Only Buffers}. - -@item invisible -@kindex invisible @r{(text property)} -A non-@code{nil} @code{invisible} property can make a character invisible -on the screen. @xref{Invisible Text}, for details. - -@item intangible -@kindex intangible @r{(text property)} -If a group of consecutive characters have equal and non-@code{nil} -@code{intangible} properties, then you cannot place point between them. -If you try to move point forward into the group, point actually moves to -the end of the group. If you try to move point backward into the group, -point actually moves to the start of the group. - -If consecutive characters have unequal non-@code{nil} -@code{intangible} properties, they belong to separate groups; each -group is separately treated as described above. - -When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}, -the @code{intangible} property is ignored. - -Beware: this property operates at a very low level, and affects a lot of code -in unexpected ways. So use it with extreme caution. A common misuse is to put -an intangible property on invisible text, which is actually unnecessary since -the command loop will move point outside of the invisible text at the end of -each command anyway. @xref{Adjusting Point}. - -@item field -@kindex field @r{(text property)} -Consecutive characters with the same @code{field} property constitute a -@dfn{field}. Some motion functions including @code{forward-word} and -@code{beginning-of-line} stop moving at a field boundary. -@xref{Fields}. - -@item cursor -@kindex cursor @r{(text property)} -Normally, the cursor is displayed at the beginning or the end of any -overlay and text property strings present at the current buffer -position. You can place the cursor on any desired character of these -strings by giving that character a non-@code{nil} @code{cursor} text -property. In addition, if the value of the @code{cursor} property is -an integer number, it specifies the number of buffer's character -positions, starting with the position where the overlay or the -@code{display} property begins, for which the cursor should be -displayed on that character. Specifically, if the value of the -@code{cursor} property of a character is the number @var{n}, the -cursor will be displayed on this character for any buffer position in -the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos} -is the overlay's starting position given by @code{overlay-start} -(@pxref{Managing Overlays}), or the position where the @code{display} -text property begins in the buffer. - -In other words, the string character with the @code{cursor} property -of any non-@code{nil} value is the character where to display the -cursor. The value of the property says for which buffer positions to -display the cursor there. If the value is an integer number @var{n}, -the cursor is displayed there when point is anywhere between the -beginning of the overlay or @code{display} property and @var{n} -positions after that. If the value is anything else and -non-@code{nil}, the cursor is displayed there only when point is at -the beginning of the @code{display} property or at -@code{overlay-start}. - -@cindex cursor position for @code{display} properties and overlays -When the buffer has many overlay strings (e.g., @pxref{Overlay -Properties, before-string}) or @code{display} properties that are -strings, it is a good idea to use the @code{cursor} property on these -strings to cue the Emacs display about the places where to put the -cursor while traversing these strings. This directly communicates to -the display engine where the Lisp program wants to put the cursor, or -where the user would expect the cursor. - -@item pointer -@kindex pointer @r{(text property)} -This specifies a specific pointer shape when the mouse pointer is over -this text or image. @xref{Pointer Shape}, for possible pointer -shapes. - -@item line-spacing -@kindex line-spacing @r{(text property)} -A newline can have a @code{line-spacing} text or overlay property that -controls the height of the display line ending with that newline. The -property value overrides the default frame line spacing and the buffer -local @code{line-spacing} variable. @xref{Line Height}. - -@item line-height -@kindex line-height @r{(text property)} -A newline can have a @code{line-height} text or overlay property that -controls the total height of the display line ending in that newline. -@xref{Line Height}. - -@item wrap-prefix -If text has a @code{wrap-prefix} property, the prefix it defines will -be added at display time to the beginning of every continuation line -due to text wrapping (so if lines are truncated, the wrap-prefix is -never used). It may be a string or an image (@pxref{Other Display -Specs}), or a stretch of whitespace such as specified by the -@code{:width} or @code{:align-to} display properties (@pxref{Specified -Space}). - -A wrap-prefix may also be specified for an entire buffer using the -@code{wrap-prefix} buffer-local variable (however, a -@code{wrap-prefix} text-property takes precedence over the value of -the @code{wrap-prefix} variable). @xref{Truncation}. - -@item line-prefix -If text has a @code{line-prefix} property, the prefix it defines will -be added at display time to the beginning of every non-continuation -line. It may be a string or an image (@pxref{Other Display -Specs}), or a stretch of whitespace such as specified by the -@code{:width} or @code{:align-to} display properties (@pxref{Specified -Space}). - -A line-prefix may also be specified for an entire buffer using the -@code{line-prefix} buffer-local variable (however, a -@code{line-prefix} text-property takes precedence over the value of -the @code{line-prefix} variable). @xref{Truncation}. - -@item modification-hooks -@cindex change hooks for a character -@cindex hooks for changing a character -@kindex modification-hooks @r{(text property)} -If a character has the property @code{modification-hooks}, then its -value should be a list of functions; modifying that character calls -all of those functions before the actual modification. Each function -receives two arguments: the beginning and end of the part of the -buffer being modified. Note that if a particular modification hook -function appears on several characters being modified by a single -primitive, you can't predict how many times the function will -be called. -Furthermore, insertion will not modify any existing character, so this -hook will only be run when removing some characters, replacing them -with others, or changing their text-properties. - -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. - -Overlays also support the @code{modification-hooks} property, but the -details are somewhat different (@pxref{Overlay Properties}). - -@item insert-in-front-hooks -@itemx insert-behind-hooks -@kindex insert-in-front-hooks @r{(text property)} -@kindex insert-behind-hooks @r{(text property)} -The operation of inserting text in a buffer also calls the functions -listed in the @code{insert-in-front-hooks} property of the following -character and in the @code{insert-behind-hooks} property of the -preceding character. These functions receive two arguments, the -beginning and end of the inserted text. The functions are called -@emph{after} the actual insertion takes place. - -See also @ref{Change Hooks}, for other hooks that are called -when you change text in a buffer. - -@item point-entered -@itemx point-left -@cindex hooks for motion of point -@kindex point-entered @r{(text property)} -@kindex point-left @r{(text property)} -The special properties @code{point-entered} and @code{point-left} -record hook functions that report motion of point. Each time point -moves, Emacs compares these two property values: - -@itemize @bullet -@item -the @code{point-left} property of the character after the old location, -and -@item -the @code{point-entered} property of the character after the new -location. -@end itemize - -@noindent -If these two values differ, each of them is called (if not @code{nil}) -with two arguments: the old value of point, and the new one. - -The same comparison is made for the characters before the old and new -locations. The result may be to execute two @code{point-left} functions -(which may be the same function) and/or two @code{point-entered} -functions (which may be the same function). In any case, all the -@code{point-left} functions are called first, followed by all the -@code{point-entered} functions. - -It is possible to use @code{char-after} to examine characters at various -buffer positions without moving point to those positions. Only an -actual change in the value of point runs these hook functions. - -The variable @code{inhibit-point-motion-hooks} can inhibit running the -@code{point-left} and @code{point-entered} hooks, see @ref{Inhibit -point motion hooks}. - -@item composition -@kindex composition @r{(text property)} -This text property is used to display a sequence of characters as a -single glyph composed from components. But the value of the property -itself is completely internal to Emacs and should not be manipulated -directly by, for instance, @code{put-text-property}. - -@end table - -@defvar inhibit-point-motion-hooks -@anchor{Inhibit point motion hooks} When this variable is -non-@code{nil}, @code{point-left} and @code{point-entered} hooks are -not run, and the @code{intangible} property has no effect. Do not set -this variable globally; bind it with @code{let}. -@end defvar - -@defvar show-help-function -@anchor{Help display} If this variable is non-@code{nil}, it specifies a -function called to display help strings. These may be @code{help-echo} -properties, menu help strings (@pxref{Simple Menu Items}, -@pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool -Bar}). The specified function is called with one argument, the help -string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs -Manual}) provides an example. -@end defvar - -@node Format Properties -@subsection Formatted Text Properties - - These text properties affect the behavior of the fill commands. They -are used for representing formatted text. @xref{Filling}, and -@ref{Margins}. - -@table @code -@item hard -If a newline character has this property, it is a ``hard'' newline. -The fill commands do not alter hard newlines and do not move words -across them. However, this property takes effect only if the -@code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft -Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}. - -@item right-margin -This property specifies an extra right margin for filling this part of the -text. - -@item left-margin -This property specifies an extra left margin for filling this part of the -text. - -@item justification -This property specifies the style of justification for filling this part -of the text. -@end table - -@node Sticky Properties -@subsection Stickiness of Text Properties -@cindex sticky text properties -@cindex inheritance of text properties - - Self-inserting characters normally take on the same properties as the -preceding character. This is called @dfn{inheritance} of properties. - - A Lisp program can do insertion with inheritance or without, -depending on the choice of insertion primitive. The ordinary text -insertion functions, such as @code{insert}, do not inherit any -properties. They insert text with precisely the properties of the -string being inserted, and no others. This is correct for programs -that copy text from one context to another---for example, into or out -of the kill ring. To insert with inheritance, use the special -primitives described in this section. Self-inserting characters -inherit properties because they work using these primitives. - - When you do insertion with inheritance, @emph{which} properties are -inherited, and from where, depends on which properties are @dfn{sticky}. -Insertion after a character inherits those of its properties that are -@dfn{rear-sticky}. Insertion before a character inherits those of its -properties that are @dfn{front-sticky}. When both sides offer different -sticky values for the same property, the previous character's value -takes precedence. - - By default, a text property is rear-sticky but not front-sticky; thus, -the default is to inherit all the properties of the preceding character, -and nothing from the following character. - - You can control the stickiness of various text properties with two -specific text properties, @code{front-sticky} and @code{rear-nonsticky}, -and with the variable @code{text-property-default-nonsticky}. You can -use the variable to specify a different default for a given property. -You can use those two text properties to make any specific properties -sticky or nonsticky in any particular part of the text. - - If a character's @code{front-sticky} property is @code{t}, then all -its properties are front-sticky. If the @code{front-sticky} property is -a list, then the sticky properties of the character are those whose -names are in the list. For example, if a character has a -@code{front-sticky} property whose value is @code{(face read-only)}, -then insertion before the character can inherit its @code{face} property -and its @code{read-only} property, but no others. - - The @code{rear-nonsticky} property works the opposite way. Most -properties are rear-sticky by default, so the @code{rear-nonsticky} -property says which properties are @emph{not} rear-sticky. If a -character's @code{rear-nonsticky} property is @code{t}, then none of its -properties are rear-sticky. If the @code{rear-nonsticky} property is a -list, properties are rear-sticky @emph{unless} their names are in the -list. - -@defvar text-property-default-nonsticky -This variable holds an alist which defines the default rear-stickiness -of various text properties. Each element has the form -@code{(@var{property} . @var{nonstickiness})}, and it defines the -stickiness of a particular text property, @var{property}. - -If @var{nonstickiness} is non-@code{nil}, this means that the property -@var{property} is rear-nonsticky by default. Since all properties are -front-nonsticky by default, this makes @var{property} nonsticky in both -directions by default. - -The text properties @code{front-sticky} and @code{rear-nonsticky}, when -used, take precedence over the default @var{nonstickiness} specified in -@code{text-property-default-nonsticky}. -@end defvar - - Here are the functions that insert text with inheritance of properties: - -@defun insert-and-inherit &rest strings -Insert the strings @var{strings}, just like the function @code{insert}, -but inherit any sticky properties from the adjoining text. -@end defun - -@defun insert-before-markers-and-inherit &rest strings -Insert the strings @var{strings}, just like the function -@code{insert-before-markers}, but inherit any sticky properties from the -adjoining text. -@end defun - - @xref{Insertion}, for the ordinary insertion functions which do not -inherit. - -@node Lazy Properties -@subsection Lazy Computation of Text Properties - - Instead of computing text properties for all the text in the buffer, -you can arrange to compute the text properties for parts of the text -when and if something depends on them. - - The primitive that extracts text from the buffer along with its -properties is @code{buffer-substring}. Before examining the properties, -this function runs the abnormal hook @code{buffer-access-fontify-functions}. - -@defvar buffer-access-fontify-functions -This variable holds a list of functions for computing text properties. -Before @code{buffer-substring} copies the text and text properties for a -portion of the buffer, it calls all the functions in this list. Each of -the functions receives two arguments that specify the range of the -buffer being accessed. (The buffer itself is always the current -buffer.) -@end defvar - - The function @code{buffer-substring-no-properties} does not call these -functions, since it ignores text properties anyway. - - In order to prevent the hook functions from being called more than -once for the same part of the buffer, you can use the variable -@code{buffer-access-fontified-property}. - -@defvar buffer-access-fontified-property -If this variable's value is non-@code{nil}, it is a symbol which is used -as a text property name. A non-@code{nil} value for that text property -means, ``the other text properties for this character have already been -computed''. - -If all the characters in the range specified for @code{buffer-substring} -have a non-@code{nil} value for this property, @code{buffer-substring} -does not call the @code{buffer-access-fontify-functions} functions. It -assumes these characters already have the right text properties, and -just copies the properties they already have. - -The normal way to use this feature is that the -@code{buffer-access-fontify-functions} functions add this property, as -well as others, to the characters they operate on. That way, they avoid -being called over and over for the same text. -@end defvar - -@node Clickable Text -@subsection Defining Clickable Text -@cindex clickable text -@cindex follow links -@cindex mouse-1 - - @dfn{Clickable text} is text that can be clicked, with either the -mouse or via a keyboard command, to produce some result. Many major -modes use clickable text to implement textual hyper-links, or -@dfn{links} for short. - - The easiest way to insert and manipulate links is to use the -@code{button} package. @xref{Buttons}. In this section, we will -explain how to manually set up clickable text in a buffer, using text -properties. For simplicity, we will refer to the clickable text as a -@dfn{link}. - - Implementing a link involves three separate steps: (1) indicating -clickability when the mouse moves over the link; (2) making @key{RET} -or @kbd{Mouse-2} on that link do something; and (3) setting up a -@code{follow-link} condition so that the link obeys -@code{mouse-1-click-follows-link}. - - To indicate clickability, add the @code{mouse-face} text property to -the text of the link; then Emacs will highlight the link when the -mouse moves over it. In addition, you should define a tooltip or echo -area message, using the @code{help-echo} text property. @xref{Special -Properties}. For instance, here is how Dired indicates that file -names are clickable: - -@smallexample - (if (dired-move-to-filename) - (add-text-properties - (point) - (save-excursion - (dired-move-to-end-of-filename) - (point)) - '(mouse-face highlight - help-echo "mouse-2: visit this file in other window"))) -@end smallexample - - To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to -commands that perform the desired action. Each command should check -to see whether it was called on a link, and act accordingly. For -instance, Dired's major mode keymap binds @kbd{Mouse-2} to the -following command: - -@smallexample -(defun dired-mouse-find-file-other-window (event) - "In Dired, visit the file or directory name you click on." - (interactive "e") - (let ((window (posn-window (event-end event))) - (pos (posn-point (event-end event))) - file) - (if (not (windowp window)) - (error "No file chosen")) - (with-current-buffer (window-buffer window) - (goto-char pos) - (setq file (dired-get-file-for-visit))) - (if (file-directory-p file) - (or (and (cdr dired-subdir-alist) - (dired-goto-subdir file)) - (progn - (select-window window) - (dired-other-window file))) - (select-window window) - (find-file-other-window (file-name-sans-versions file t))))) -@end smallexample - -@noindent -This command uses the functions @code{posn-window} and -@code{posn-point} to determine where the click occurred, and -@code{dired-get-file-for-visit} to determine which file to visit. - - Instead of binding the mouse command in a major mode keymap, you can -bind it within the link text, using the @code{keymap} text property -(@pxref{Special Properties}). For instance: - -@example -(let ((map (make-sparse-keymap))) - (define-key map [mouse-2] 'operate-this-button) - (put-text-property link-start link-end 'keymap map)) -@end example - -@noindent -With this method, you can easily define different commands for -different links. Furthermore, the global definition of @key{RET} and -@kbd{Mouse-2} remain available for the rest of the text in the buffer. - -@vindex mouse-1-click-follows-link - The basic Emacs command for clicking on links is @kbd{Mouse-2}. -However, for compatibility with other graphical applications, Emacs -also recognizes @kbd{Mouse-1} clicks on links, provided the user -clicks on the link quickly without moving the mouse. This behavior is -controlled by the user option @code{mouse-1-click-follows-link}. -@xref{Mouse References,,, emacs, The GNU Emacs Manual}. - - To set up the link so that it obeys -@code{mouse-1-click-follows-link}, you must either (1) apply a -@code{follow-link} text or overlay property to the link text, or (2) -bind the @code{follow-link} event to a keymap (which can be a major -mode keymap or a local keymap specified via the @code{keymap} text -property). The value of the @code{follow-link} property, or the -binding for the @code{follow-link} event, acts as a ``condition'' for -the link action. This condition tells Emacs two things: the -circumstances under which a @kbd{Mouse-1} click should be regarded as -occurring ``inside'' the link, and how to compute an ``action code'' -that says what to translate the @kbd{Mouse-1} click into. The link -action condition can be one of the following: - -@table @asis -@item @code{mouse-face} -If the condition is the symbol @code{mouse-face}, a position is inside -a link if there is a non-@code{nil} @code{mouse-face} property at that -position. The action code is always @code{t}. - -For example, here is how Info mode handles @key{Mouse-1}: - -@smallexample -(define-key Info-mode-map [follow-link] 'mouse-face) -@end smallexample - -@item a function -If the condition is a function, @var{func}, then a position @var{pos} -is inside a link if @code{(@var{func} @var{pos})} evaluates to -non-@code{nil}. The value returned by @var{func} serves as the action -code. - -For example, here is how pcvs enables @kbd{Mouse-1} to follow links on -file names only: - -@smallexample -(define-key map [follow-link] - (lambda (pos) - (eq (get-char-property pos 'face) 'cvs-filename-face))) -@end smallexample - -@item anything else -If the condition value is anything else, then the position is inside a -link and the condition itself is the action code. Clearly, you should -specify this kind of condition only when applying the condition via a -text or property overlay on the link text (so that it does not apply -to the entire buffer). -@end table - -@noindent -The action code tells @kbd{Mouse-1} how to follow the link: - -@table @asis -@item a string or vector -If the action code is a string or vector, the @kbd{Mouse-1} event is -translated into the first element of the string or vector; i.e., the -action of the @kbd{Mouse-1} click is the local or global binding of -that character or symbol. Thus, if the action code is @code{"foo"}, -@kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]}, -@kbd{Mouse-1} translates into @key{foo}. - -@item anything else -For any other non-@code{nil} action code, the @kbd{Mouse-1} event is -translated into a @kbd{Mouse-2} event at the same position. -@end table - - To define @kbd{Mouse-1} to activate a button defined with -@code{define-button-type}, give the button a @code{follow-link} -property. The property value should be a link action condition, as -described above. @xref{Buttons}. For example, here is how Help mode -handles @kbd{Mouse-1}: - -@smallexample -(define-button-type 'help-xref - 'follow-link t - 'action #'help-button-action) -@end smallexample - - To define @kbd{Mouse-1} on a widget defined with -@code{define-widget}, give the widget a @code{:follow-link} property. -The property value should be a link action condition, as described -above. For example, here is how the @code{link} widget specifies that -a @key{Mouse-1} click shall be translated to @key{RET}: - -@smallexample -(define-widget 'link 'item - "An embedded link." - :button-prefix 'widget-link-prefix - :button-suffix 'widget-link-suffix - :follow-link "\C-m" - :help-echo "Follow the link." - :format "%[%t%]") -@end smallexample - -@defun mouse-on-link-p pos -This function returns non-@code{nil} if position @var{pos} in the -current buffer is on a link. @var{pos} can also be a mouse event -location, as returned by @code{event-start} (@pxref{Accessing Mouse}). -@end defun - -@node Fields -@subsection Defining and Using Fields -@cindex fields - - A field is a range of consecutive characters in the buffer that are -identified by having the same value (comparing with @code{eq}) of the -@code{field} property (either a text-property or an overlay property). -This section describes special functions that are available for -operating on fields. - - You specify a field with a buffer position, @var{pos}. We think of -each field as containing a range of buffer positions, so the position -you specify stands for the field containing that position. - - When the characters before and after @var{pos} are part of the same -field, there is no doubt which field contains @var{pos}: the one those -characters both belong to. When @var{pos} is at a boundary between -fields, which field it belongs to depends on the stickiness of the -@code{field} properties of the two surrounding characters (@pxref{Sticky -Properties}). The field whose property would be inherited by text -inserted at @var{pos} is the field that contains @var{pos}. - - There is an anomalous case where newly inserted text at @var{pos} -would not inherit the @code{field} property from either side. This -happens if the previous character's @code{field} property is not -rear-sticky, and the following character's @code{field} property is not -front-sticky. In this case, @var{pos} belongs to neither the preceding -field nor the following field; the field functions treat it as belonging -to an empty field whose beginning and end are both at @var{pos}. - - In all of these functions, if @var{pos} is omitted or @code{nil}, the -value of point is used by default. If narrowing is in effect, then -@var{pos} should fall within the accessible portion. @xref{Narrowing}. - -@defun field-beginning &optional pos escape-from-edge limit -This function returns the beginning of the field specified by @var{pos}. - -If @var{pos} is at the beginning of its field, and -@var{escape-from-edge} is non-@code{nil}, then the return value is -always the beginning of the preceding field that @emph{ends} at @var{pos}, -regardless of the stickiness of the @code{field} properties around -@var{pos}. - -If @var{limit} is non-@code{nil}, it is a buffer position; if the -beginning of the field is before @var{limit}, then @var{limit} will be -returned instead. -@end defun - -@defun field-end &optional pos escape-from-edge limit -This function returns the end of the field specified by @var{pos}. - -If @var{pos} is at the end of its field, and @var{escape-from-edge} is -non-@code{nil}, then the return value is always the end of the following -field that @emph{begins} at @var{pos}, regardless of the stickiness of -the @code{field} properties around @var{pos}. - -If @var{limit} is non-@code{nil}, it is a buffer position; if the end -of the field is after @var{limit}, then @var{limit} will be returned -instead. -@end defun - -@defun field-string &optional pos -This function returns the contents of the field specified by @var{pos}, -as a string. -@end defun - -@defun field-string-no-properties &optional pos -This function returns the contents of the field specified by @var{pos}, -as a string, discarding text properties. -@end defun - -@defun delete-field &optional pos -This function deletes the text of the field specified by @var{pos}. -@end defun - -@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property -This function ``constrains'' @var{new-pos} to the field that -@var{old-pos} belongs to---in other words, it returns the position -closest to @var{new-pos} that is in the same field as @var{old-pos}. - -If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses -the value of point instead, and moves point to the resulting position -in addition to returning that position. - -If @var{old-pos} is at the boundary of two fields, then the acceptable -final positions depend on the argument @var{escape-from-edge}. If -@var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in -the field whose @code{field} property equals what new characters -inserted at @var{old-pos} would inherit. (This depends on the -stickiness of the @code{field} property for the characters before and -after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil}, -@var{new-pos} can be anywhere in the two adjacent fields. -Additionally, if two fields are separated by another field with the -special value @code{boundary}, then any point within this special -field is also considered to be ``on the boundary''. - -Commands like @kbd{C-a} with no argument, that normally move backward -to a specific kind of location and stay there once there, probably -should specify @code{nil} for @var{escape-from-edge}. Other motion -commands that check fields should probably pass @code{t}. - -If the optional argument @var{only-in-line} is non-@code{nil}, and -constraining @var{new-pos} in the usual way would move it to a different -line, @var{new-pos} is returned unconstrained. This used in commands -that move by line, such as @code{next-line} and -@code{beginning-of-line}, so that they respect field boundaries only in -the case where they can still move to the right line. - -If the optional argument @var{inhibit-capture-property} is -non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that -name, then any field boundaries are ignored. - -You can cause @code{constrain-to-field} to ignore all field boundaries -(and so never constrain anything) by binding the variable -@code{inhibit-field-text-motion} to a non-@code{nil} value. -@end defun - -@node Not Intervals -@subsection Why Text Properties are not Intervals -@cindex intervals - - Some editors that support adding attributes to text in the buffer do -so by letting the user specify ``intervals'' within the text, and adding -the properties to the intervals. Those editors permit the user or the -programmer to determine where individual intervals start and end. We -deliberately provided a different sort of interface in Emacs Lisp to -avoid certain paradoxical behavior associated with text modification. - - If the actual subdivision into intervals is meaningful, that means you -can distinguish between a buffer that is just one interval with a -certain property, and a buffer containing the same text subdivided into -two intervals, both of which have that property. - - Suppose you take the buffer with just one interval and kill part of -the text. The text remaining in the buffer is one interval, and the -copy in the kill ring (and the undo list) becomes a separate interval. -Then if you yank back the killed text, you get two intervals with the -same properties. Thus, editing does not preserve the distinction -between one interval and two. - - Suppose we ``fix'' this problem by coalescing the two intervals when -the text is inserted. That works fine if the buffer originally was a -single interval. But suppose instead that we have two adjacent -intervals with the same properties, and we kill the text of one interval -and yank it back. The same interval-coalescence feature that rescues -the other case causes trouble in this one: after yanking, we have just -one interval. One again, editing does not preserve the distinction -between one interval and two. - - Insertion of text at the border between intervals also raises -questions that have no satisfactory answer. - - However, it is easy to arrange for editing to behave consistently for -questions of the form, ``What are the properties of this character?'' -So we have decided these are the only questions that make sense; we have -not implemented asking questions about where intervals start or end. - - In practice, you can usually use the text property search functions in -place of explicit interval boundaries. You can think of them as finding -the boundaries of intervals, assuming that intervals are always -coalesced whenever possible. @xref{Property Search}. - - Emacs also provides explicit intervals as a presentation feature; see -@ref{Overlays}. - -@node Substitution -@section Substituting for a Character Code - - The following functions replace characters within a specified region -based on their character codes. - -@defun subst-char-in-region start end old-char new-char &optional noundo -@cindex replace characters -This function replaces all occurrences of the character @var{old-char} -with the character @var{new-char} in the region of the current buffer -defined by @var{start} and @var{end}. - -@cindex undo avoidance -If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does -not record the change for undo and does not mark the buffer as modified. -This was useful for controlling the old selective display feature -(@pxref{Selective Display}). - -@code{subst-char-in-region} does not move point and returns -@code{nil}. - -@example -@group ----------- Buffer: foo ---------- -This is the contents of the buffer before. ----------- Buffer: foo ---------- -@end group - -@group -(subst-char-in-region 1 20 ?i ?X) - @result{} nil - ----------- Buffer: foo ---------- -ThXs Xs the contents of the buffer before. ----------- Buffer: foo ---------- -@end group -@end example -@end defun - -@deffn Command translate-region start end table -This function applies a translation table to the characters in the -buffer between positions @var{start} and @var{end}. - -The translation table @var{table} is a string or a char-table; -@code{(aref @var{table} @var{ochar})} gives the translated character -corresponding to @var{ochar}. If @var{table} is a string, any -characters with codes larger than the length of @var{table} are not -altered by the translation. - -The return value of @code{translate-region} is the number of -characters that were actually changed by the translation. This does -not count characters that were mapped into themselves in the -translation table. -@end deffn - -@node Registers -@section Registers -@cindex registers - - A register is a sort of variable used in Emacs editing that can hold a -variety of different kinds of values. Each register is named by a -single character. All @acronym{ASCII} characters and their meta variants -(but with the exception of @kbd{C-g}) can be used to name registers. -Thus, there are 255 possible registers. A register is designated in -Emacs Lisp by the character that is its name. - -@defvar register-alist -This variable is an alist of elements of the form @code{(@var{name} . -@var{contents})}. Normally, there is one element for each Emacs -register that has been used. - -The object @var{name} is a character (an integer) identifying the -register. -@end defvar - - The @var{contents} of a register can have several possible types: - -@table @asis -@item a number -A number stands for itself. If @code{insert-register} finds a number -in the register, it converts the number to decimal. - -@item a marker -A marker represents a buffer position to jump to. - -@item a string -A string is text saved in the register. - -@item a rectangle -A rectangle is represented by a list of strings. - -@item @code{(@var{window-configuration} @var{position})} -This represents a window configuration to restore in one frame, and a -position to jump to in the current buffer. - -@item @code{(@var{frame-configuration} @var{position})} -This represents a frame configuration to restore, and a position -to jump to in the current buffer. - -@item (file @var{filename}) -This represents a file to visit; jumping to this value visits file -@var{filename}. - -@item (file-query @var{filename} @var{position}) -This represents a file to visit and a position in it; jumping to this -value visits file @var{filename} and goes to buffer position -@var{position}. Restoring this type of position asks the user for -confirmation first. -@end table - - The functions in this section return unpredictable values unless -otherwise stated. - -@defun get-register reg -This function returns the contents of the register -@var{reg}, or @code{nil} if it has no contents. -@end defun - -@defun set-register reg value -This function sets the contents of register @var{reg} to @var{value}. -A register can be set to any value, but the other register functions -expect only certain data types. The return value is @var{value}. -@end defun - -@deffn Command view-register reg -This command displays what is contained in register @var{reg}. -@end deffn - -@deffn Command insert-register reg &optional beforep -This command inserts contents of register @var{reg} into the current -buffer. - -Normally, this command puts point before the inserted text, and the -mark after it. However, if the optional second argument @var{beforep} -is non-@code{nil}, it puts the mark before and point after. -You can pass a non-@code{nil} second argument @var{beforep} to this -function interactively by supplying any prefix argument. - -If the register contains a rectangle, then the rectangle is inserted -with its upper left corner at point. This means that text is inserted -in the current line and underneath it on successive lines. - -If the register contains something other than saved text (a string) or -a rectangle (a list), currently useless things happen. This may be -changed in the future. -@end deffn - -@node Transposition -@section Transposition of Text - - This function can be used to transpose stretches of text: - -@defun transpose-regions start1 end1 start2 end2 &optional leave-markers -This function exchanges two nonoverlapping portions of the buffer. -Arguments @var{start1} and @var{end1} specify the bounds of one portion -and arguments @var{start2} and @var{end2} specify the bounds of the -other portion. - -Normally, @code{transpose-regions} relocates markers with the transposed -text; a marker previously positioned within one of the two transposed -portions moves along with that portion, thus remaining between the same -two characters in their new position. However, if @var{leave-markers} -is non-@code{nil}, @code{transpose-regions} does not do this---it leaves -all markers unrelocated. -@end defun - -@node Base 64 -@section Base 64 Encoding -@cindex base 64 encoding - - Base 64 code is used in email to encode a sequence of 8-bit bytes as -a longer sequence of @acronym{ASCII} graphic characters. It is defined in -Internet RFC@footnote{ -An RFC, an acronym for @dfn{Request for Comments}, is a numbered -Internet informational document describing a standard. RFCs are -usually written by technical experts acting on their own initiative, -and are traditionally written in a pragmatic, experience-driven -manner. -}2045. This section describes the functions for -converting to and from this code. - -@deffn Command base64-encode-region beg end &optional no-line-break -This function converts the region from @var{beg} to @var{end} into base -64 code. It returns the length of the encoded text. An error is -signaled if a character in the region is multibyte, i.e.@: in a -multibyte buffer the region must contain only characters from the -charsets @code{ascii}, @code{eight-bit-control} and -@code{eight-bit-graphic}. - -Normally, this function inserts newline characters into the encoded -text, to avoid overlong lines. However, if the optional argument -@var{no-line-break} is non-@code{nil}, these newlines are not added, so -the output is just one long line. -@end deffn - -@defun base64-encode-string string &optional no-line-break -This function converts the string @var{string} into base 64 code. It -returns a string containing the encoded text. As for -@code{base64-encode-region}, an error is signaled if a character in the -string is multibyte. - -Normally, this function inserts newline characters into the encoded -text, to avoid overlong lines. However, if the optional argument -@var{no-line-break} is non-@code{nil}, these newlines are not added, so -the result string is just one long line. -@end defun - -@deffn Command base64-decode-region beg end -This function converts the region from @var{beg} to @var{end} from base -64 code into the corresponding decoded text. It returns the length of -the decoded text. - -The decoding functions ignore newline characters in the encoded text. -@end deffn - -@defun base64-decode-string string -This function converts the string @var{string} from base 64 code into -the corresponding decoded text. It returns a unibyte string containing the -decoded text. - -The decoding functions ignore newline characters in the encoded text. -@end defun - -@node Checksum/Hash -@section Checksum/Hash -@cindex MD5 checksum -@cindex SHA hash -@cindex hash, cryptographic -@cindex cryptographic hash - - Emacs has built-in support for computing @dfn{cryptographic hashes}. -A cryptographic hash, or @dfn{checksum}, is a digital ``fingerprint'' -of a piece of data (e.g.@: a block of text) which can be used to check -that you have an unaltered copy of that data. - -@cindex message digest - Emacs supports several common cryptographic hash algorithms: MD5, -SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. MD5 is the -oldest of these algorithms, and is commonly used in @dfn{message -digests} to check the integrity of messages transmitted over a -network. MD5 is not ``collision resistant'' (i.e.@: it is possible to -deliberately design different pieces of data which have the same MD5 -hash), so you should not used it for anything security-related. A -similar theoretical weakness also exists in SHA-1. Therefore, for -security-related applications you should use the other hash types, -such as SHA-2. - -@defun secure-hash algorithm object &optional start end binary -This function returns a hash for @var{object}. The argument -@var{algorithm} is a symbol stating which hash to compute: one of -@code{md5}, @code{sha1}, @code{sha224}, @code{sha256}, @code{sha384} -or @code{sha512}. The argument @var{object} should be a buffer or a -string. - -The optional arguments @var{start} and @var{end} are character -positions specifying the portion of @var{object} to compute the -message digest for. If they are @code{nil} or omitted, the hash is -computed for the whole of @var{object}. - -If the argument @var{binary} is omitted or @code{nil}, the function -returns the @dfn{text form} of the hash, as an ordinary Lisp string. -If @var{binary} is non-@code{nil}, it returns the hash in @dfn{binary -form}, as a sequence of bytes stored in a unibyte string. - -This function does not compute the hash directly from the internal -representation of @var{object}'s text (@pxref{Text Representations}). -Instead, it encodes the text using a coding system (@pxref{Coding -Systems}), and computes the hash from that encoded text. If -@var{object} is a buffer, the coding system used is the one which -would be chosen by default for writing the text into a file. If -@var{object} is a string, the user's preferred coding system is used -(@pxref{Recognize Coding,,, emacs, GNU Emacs Manual}). -@end defun - -@defun md5 object &optional start end coding-system noerror -This function returns an MD5 hash. It is semi-obsolete, since for -most purposes it is equivalent to calling @code{secure-hash} with -@code{md5} as the @var{algorithm} argument. The @var{object}, -@var{start} and @var{end} arguments have the same meanings as in -@code{secure-hash}. - -If @var{coding-system} is non-@code{nil}, it specifies a coding system -to use to encode the text; if omitted or @code{nil}, the default -coding system is used, like in @code{secure-hash}. - -Normally, @code{md5} signals an error if the text can't be encoded -using the specified or chosen coding system. However, if -@var{noerror} is non-@code{nil}, it silently uses @code{raw-text} -coding instead. -@end defun - -@node Parsing HTML/XML -@section Parsing HTML and XML -@cindex parsing html - -When Emacs is compiled with libxml2 support, the following functions -are available to parse HTML or XML text into Lisp object trees. - -@defun libxml-parse-html-region start end &optional base-url -This function parses the text between @var{start} and @var{end} as -HTML, and returns a list representing the HTML @dfn{parse tree}. It -attempts to handle ``real world'' HTML by robustly coping with syntax -mistakes. - -The optional argument @var{base-url}, if non-@code{nil}, should be a -string specifying the base URL for relative URLs occurring in links. - -In the parse tree, each HTML node is represented by a list in which -the first element is a symbol representing the node name, the second -element is an alist of node attributes, and the remaining elements are -the subnodes. - -The following example demonstrates this. Given this (malformed) HTML -document: - -@example -

Foo
Yes -@end example - -@noindent -A call to @code{libxml-parse-html-region} returns this: - -@example -(html () - (head ()) - (body ((width . "101")) - (div ((class . "thing")) - "Foo" - (div () - "Yes")))) -@end example -@end defun - -@cindex parsing xml -@defun libxml-parse-xml-region start end &optional base-url -This function is the same as @code{libxml-parse-html-region}, except -that it parses the text as XML rather than HTML (so it is stricter -about syntax). -@end defun - -@node Atomic Changes -@section Atomic Change Groups -@cindex atomic changes - - In database terminology, an @dfn{atomic} change is an indivisible -change---it can succeed entirely or it can fail entirely, but it -cannot partly succeed. A Lisp program can make a series of changes to -one or several buffers as an @dfn{atomic change group}, meaning that -either the entire series of changes will be installed in their buffers -or, in case of an error, none of them will be. - - To do this for one buffer, the one already current, simply write a -call to @code{atomic-change-group} around the code that makes the -changes, like this: - -@example -(atomic-change-group - (insert foo) - (delete-region x y)) -@end example - -@noindent -If an error (or other nonlocal exit) occurs inside the body of -@code{atomic-change-group}, it unmakes all the changes in that buffer -that were during the execution of the body. This kind of change group -has no effect on any other buffers---any such changes remain. - - If you need something more sophisticated, such as to make changes in -various buffers constitute one atomic group, you must directly call -lower-level functions that @code{atomic-change-group} uses. - -@defun prepare-change-group &optional buffer -This function sets up a change group for buffer @var{buffer}, which -defaults to the current buffer. It returns a ``handle'' that -represents the change group. You must use this handle to activate the -change group and subsequently to finish it. -@end defun - - To use the change group, you must @dfn{activate} it. You must do -this before making any changes in the text of @var{buffer}. - -@defun activate-change-group handle -This function activates the change group that @var{handle} designates. -@end defun - - After you activate the change group, any changes you make in that -buffer become part of it. Once you have made all the desired changes -in the buffer, you must @dfn{finish} the change group. There are two -ways to do this: you can either accept (and finalize) all the changes, -or cancel them all. - -@defun accept-change-group handle -This function accepts all the changes in the change group specified by -@var{handle}, making them final. -@end defun - -@defun cancel-change-group handle -This function cancels and undoes all the changes in the change group -specified by @var{handle}. -@end defun - - Your code should use @code{unwind-protect} to make sure the group is -always finished. The call to @code{activate-change-group} should be -inside the @code{unwind-protect}, in case the user types @kbd{C-g} -just after it runs. (This is one reason why -@code{prepare-change-group} and @code{activate-change-group} are -separate functions, because normally you would call -@code{prepare-change-group} before the start of that -@code{unwind-protect}.) Once you finish the group, don't use the -handle again---in particular, don't try to finish the same group -twice. - - To make a multibuffer change group, call @code{prepare-change-group} -once for each buffer you want to cover, then use @code{nconc} to -combine the returned values, like this: - -@example -(nconc (prepare-change-group buffer-1) - (prepare-change-group buffer-2)) -@end example - -You can then activate the multibuffer change group with a single call -to @code{activate-change-group}, and finish it with a single call to -@code{accept-change-group} or @code{cancel-change-group}. - - Nested use of several change groups for the same buffer works as you -would expect. Non-nested use of change groups for the same buffer -will get Emacs confused, so don't let it happen; the first change -group you start for any given buffer should be the last one finished. - -@node Change Hooks -@section Change Hooks -@cindex change hooks -@cindex hooks for text changes - - These hook variables let you arrange to take notice of all changes in -all buffers (or in a particular buffer, if you make them buffer-local). -See also @ref{Special Properties}, for how to detect changes to specific -parts of the text. - - The functions you use in these hooks should save and restore the match -data if they do anything that uses regular expressions; otherwise, they -will interfere in bizarre ways with the editing operations that call -them. - -@defvar before-change-functions -This variable holds a list of functions to call before any buffer -modification. Each function gets two arguments, the beginning and end -of the region that is about to change, represented as integers. The -buffer that is about to change is always the current buffer. -@end defvar - -@defvar after-change-functions -This variable holds a list of functions to call after any buffer -modification. Each function receives three arguments: the beginning -and end of the region just changed, and the length of the text that -existed before the change. All three arguments are integers. The -buffer has been changed is always the current buffer. - -The length of the old text is the difference between the buffer -positions before and after that text as it was before the change. As -for the changed text, its length is simply the difference between the -first two arguments. -@end defvar - - Output of messages into the @file{*Messages*} buffer does not -call these functions. - -@defmac combine-after-change-calls body@dots{} -The macro executes @var{body} normally, but arranges to call the -after-change functions just once for a series of several changes---if -that seems safe. - -If a program makes several text changes in the same area of the buffer, -using the macro @code{combine-after-change-calls} around that part of -the program can make it run considerably faster when after-change hooks -are in use. When the after-change hooks are ultimately called, the -arguments specify a portion of the buffer including all of the changes -made within the @code{combine-after-change-calls} body. - -@strong{Warning:} You must not alter the values of -@code{after-change-functions} within -the body of a @code{combine-after-change-calls} form. - -@strong{Warning:} if the changes you combine occur in widely scattered -parts of the buffer, this will still work, but it is not advisable, -because it may lead to inefficient behavior for some change hook -functions. -@end defmac - -@defvar first-change-hook -This variable is a normal hook that is run whenever a buffer is changed -that was previously in the unmodified state. -@end defvar - -@defvar inhibit-modification-hooks -If this variable is non-@code{nil}, all of the change hooks are -disabled; none of them run. This affects all the hook variables -described above in this section, as well as the hooks attached to -certain special text properties (@pxref{Special Properties}) and overlay -properties (@pxref{Overlay Properties}). - -Also, this variable is bound to non-@code{nil} while running those -same hook variables, so that by default modifying the buffer from -a modification hook does not cause other modification hooks to be run. -If you do want modification hooks to be run in a particular piece of -code that is itself run from a modification hook, then rebind locally -@code{inhibit-modification-hooks} to @code{nil}. -@end defvar diff --git a/doc/lispref/tindex.pl b/doc/lispref/tindex.pl deleted file mode 100755 index a8765716e71..00000000000 --- a/doc/lispref/tindex.pl +++ /dev/null @@ -1,124 +0,0 @@ -#! /usr/bin/perl - -# Copyright (C) 2000-2012 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -require 5; -use Getopt::Long; - -my $USAGE = < \$help, 'version' => \$version, - 'old=s' => \$old); -if ($version) { - print "0.1\n"; - exit 0; -} elsif (!$rc || !$old || @ARGV) { - print $USAGE; - exit 1; -} elsif ($help) { - print $USAGE; - exit 0; -} - -# Fill the hash %tindex with associations VAR -> COUNT where -# the keys VAR are identifiers mentioned in @tindex lines in the older -# files to process and COUNT is the number of times they are seen in -# the files. - -my %tindex; -my %removed; -my @old_files = glob "$old/*.texi"; -my @new_files = glob "*.texi"; -fatal ("No Texinfo files found in `$old'") unless @old_files; -fatal ("No Texinfo files found in current directory") unless @new_files; - -print "Scanning old files for \@tindex lines\n"; -foreach $file (@old_files) { - open (IN, "<$file") or fatal "Cannot open $file: $!"; - while () { - ++$tindex{$1} if /^\s*\@tindex\s+(\S+)/; - } - close IN; -} - -# Process current files and remove those @tindex lines which we -# know were already present in the files scanned above. - -print "Removing old \@tindex lines\n"; -foreach $file (@new_files) { - my $modified = 0; - my $contents = ""; - - open (IN, "< $file") or fatal "Cannot open $file.orig for reading: $!"; - while () { - if (/^\s*\@tindex\s+(\S+)/ && $tindex{$1}) { - ++$removed{$1}; - $modified = 1; - } else { - $contents = $contents . $_; - } - } - - close IN; - - if ($modified) { - print " $file\n"; - system ("cp $file $file.orig") == 0 or fatal "Cannot backup $file: $!"; - open (OUT, ">$file") or fatal "Cannot open $file for writing: $!"; - print OUT $contents; - close OUT; - } -} - -# Print a list of identifiers removed. - -print "Removed \@tindex commands for:\n"; -my $key; -foreach $key (keys %removed) { - print " $key\n"; -} - diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi deleted file mode 100644 index 56c361cf86e..00000000000 --- a/doc/lispref/tips.texi +++ /dev/null @@ -1,1096 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/tips -@node Tips, GNU Emacs Internals, GPL, Top -@appendix Tips and Conventions -@cindex tips for writing Lisp -@cindex standards of coding style -@cindex coding standards - - This chapter describes no additional features of Emacs Lisp. Instead -it gives advice on making effective use of the features described in the -previous chapters, and describes conventions Emacs Lisp programmers -should follow. - - You can automatically check some of the conventions described below by -running the command @kbd{M-x checkdoc RET} when visiting a Lisp file. -It cannot check all of the conventions, and not all the warnings it -gives necessarily correspond to problems, but it is worth examining them -all. - -@menu -* Coding Conventions:: Conventions for clean and robust programs. -* Key Binding Conventions:: Which keys should be bound by which programs. -* Programming Tips:: Making Emacs code fit smoothly in Emacs. -* Compilation Tips:: Making compiled code run fast. -* Warning Tips:: Turning off compiler warnings. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. -@end menu - -@node Coding Conventions -@section Emacs Lisp Coding Conventions - -@cindex coding conventions in Emacs Lisp - Here are conventions that you should follow when writing Emacs Lisp -code intended for widespread use: - -@itemize @bullet -@item -Simply loading a package should not change Emacs's editing behavior. -Include a command or commands to enable and disable the feature, -or to invoke it. - -This convention is mandatory for any file that includes custom -definitions. If fixing such a file to follow this convention requires -an incompatible change, go ahead and make the incompatible change; -don't postpone it. - -@item -You should choose a short word to distinguish your program from other -Lisp programs. The names of all global variables, constants, and -functions in your program should begin with that chosen prefix. -Separate the prefix from the rest of the name with a hyphen, @samp{-}. -This practice helps avoid name conflicts, since all global variables -in Emacs Lisp share the same name space, and all functions share -another name space@footnote{The benefits of a Common Lisp-style -package system are considered not to outweigh the costs.}. - -Occasionally, for a command name intended for users to use, it is more -convenient if some words come before the package's name prefix. And -constructs that define functions, variables, etc., work better if they -start with @samp{defun} or @samp{defvar}, so put the name prefix later -on in the name. - -This recommendation applies even to names for traditional Lisp -primitives that are not primitives in Emacs Lisp---such as -@code{copy-list}. Believe it or not, there is more than one plausible -way to define @code{copy-list}. Play it safe; append your name prefix -to produce a name like @code{foo-copy-list} or @code{mylib-copy-list} -instead. - -If you write a function that you think ought to be added to Emacs under -a certain name, such as @code{twiddle-files}, don't call it by that name -in your program. Call it @code{mylib-twiddle-files} in your program, -and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add -it to Emacs. If and when we do, we can change the name easily enough. - -If one prefix is insufficient, your package can use two or three -alternative common prefixes, so long as they make sense. - -@item -Put a call to @code{provide} at the end of each separate Lisp file. -@xref{Named Features}. - -@item -If a file requires certain other Lisp programs to be loaded -beforehand, then the comments at the beginning of the file should say -so. Also, use @code{require} to make sure they are loaded. -@xref{Named Features}. - -@item -If a file @var{foo} uses a macro defined in another file @var{bar}, -but does not use any functions or variables defined in @var{bar}, then -@var{foo} should contain the following expression: - -@example -(eval-when-compile (require '@var{bar})) -@end example - -@noindent -This tells Emacs to load @var{bar} just before byte-compiling -@var{foo}, so that the macro definition is available during -compilation. Using @code{eval-when-compile} avoids loading @var{bar} -when the compiled version of @var{foo} is @emph{used}. It should be -called before the first use of the macro in the file. @xref{Compiling -Macros}. - -@item -Avoid loading additional libraries at run time unless they are really -needed. If your file simply cannot work without some other library, -then just @code{require} that library at the top-level and be done -with it. But if your file contains several independent features, and -only one or two require the extra library, then consider putting -@code{require} statements inside the relevant functions rather than at -the top-level. Or use @code{autoload} statements to load the extra -library when needed. This way people who don't use those aspects of -your file do not need to load the extra library. - -@item -Please don't require the @code{cl} package of Common Lisp extensions at -run time. Use of this package is optional, and it is not part of the -standard Emacs namespace. If your package loads @code{cl} at run time, -that could cause name clashes for users who don't use that package. - -However, there is no problem with using the @code{cl} package at -compile time, with @code{(eval-when-compile (require 'cl))}. That's -sufficient for using the macros in the @code{cl} package, because the -compiler expands them before generating the byte-code. - -@item -When defining a major mode, please follow the major mode -conventions. @xref{Major Mode Conventions}. - -@item -When defining a minor mode, please follow the minor mode -conventions. @xref{Minor Mode Conventions}. - -@item -If the purpose of a function is to tell you whether a certain -condition is true or false, give the function a name that ends in -@samp{p} (which stands for ``predicate''). If the name is one word, -add just @samp{p}; if the name is multiple words, add @samp{-p}. -Examples are @code{framep} and @code{frame-live-p}. - -@item -If the purpose of a variable is to store a single function, give it a -name that ends in @samp{-function}. If the purpose of a variable is -to store a list of functions (i.e., the variable is a hook), please -follow the naming conventions for hooks. @xref{Hooks}. - -@item -@cindex unloading packages, preparing for -If loading the file adds functions to hooks, define a function -@code{@var{feature}-unload-hook}, where @var{feature} is the name of -the feature the package provides, and make it undo any such changes. -Using @code{unload-feature} to unload the file will run this function. -@xref{Unloading}. - -@item -It is a bad idea to define aliases for the Emacs primitives. Normally -you should use the standard names instead. The case where an alias -may be useful is where it facilitates backwards compatibility or -portability. - -@item -If a package needs to define an alias or a new function for -compatibility with some other version of Emacs, name it with the package -prefix, not with the raw name with which it occurs in the other version. -Here is an example from Gnus, which provides many examples of such -compatibility issues. - -@example -(defalias 'gnus-point-at-bol - (if (fboundp 'point-at-bol) - 'point-at-bol - 'line-beginning-position)) -@end example - -@item -Redefining or advising an Emacs primitive is a bad idea. It may do -the right thing for a particular program, but there is no telling what -other programs might break as a result. - -@item -It is likewise a bad idea for one Lisp package to advise a function in -another Lisp package (@pxref{Advising Functions}). - -@item -Avoid using @code{eval-after-load} in libraries and packages -(@pxref{Hooks for Loading}). This feature is meant for personal -customizations; using it in a Lisp program is unclean, because it -modifies the behavior of another Lisp file in a way that's not visible -in that file. This is an obstacle for debugging, much like advising a -function in the other package. - -@item -If a file does replace any of the standard functions or library -programs of Emacs, prominent comments at the beginning of the file -should say which functions are replaced, and how the behavior of the -replacements differs from that of the originals. - -@item -Constructs that define a function or variable should be macros, -not functions, and their names should start with @samp{define-}. -The macro should receive the name to be -defined as the first argument. That will help various tools find the -definition automatically. Avoid constructing the names in the macro -itself, since that would confuse these tools. - -@item -In some other systems there is a convention of choosing variable names -that begin and end with @samp{*}. We don't use that convention in Emacs -Lisp, so please don't use it in your programs. (Emacs uses such names -only for special-purpose buffers.) People will find Emacs more -coherent if all libraries use the same conventions. - -@item -If your program contains non-ASCII characters in string or character -constants, you should make sure Emacs always decodes these characters -the same way, regardless of the user's settings. The easiest way to -do this is to use the coding system @code{utf-8-emacs} (@pxref{Coding -System Basics}), and specify that coding in the @samp{-*-} line or the -local variables list. @xref{File Variables, , Local Variables in -Files, emacs, The GNU Emacs Manual}. - -@example -;; XXX.el -*- coding: utf-8-emacs; -*- -@end example - -@item -Indent the file using the default indentation parameters. - -@item -Don't make a habit of putting close-parentheses on lines by -themselves; Lisp programmers find this disconcerting. - -@item -Please put a copyright notice and copying permission notice on the -file if you distribute copies. @xref{Library Headers}. - -@end itemize - -@node Key Binding Conventions -@section Key Binding Conventions -@cindex key binding, conventions for - -@itemize @bullet -@item -@cindex mouse-2 -@cindex references, following -Many special major modes, like Dired, Info, Compilation, and Occur, -are designed to handle read-only text that contains @dfn{hyper-links}. -Such a major mode should redefine @kbd{mouse-2} and @key{RET} to -follow the links. It should also set up a @code{follow-link} -condition, so that the link obeys @code{mouse-1-click-follows-link}. -@xref{Clickable Text}. @xref{Buttons}, for an easy method of -implementing such clickable links. - -@item -@cindex reserved keys -@cindex keys, reserved -Don't define @kbd{C-c @var{letter}} as a key in Lisp programs. -Sequences consisting of @kbd{C-c} and a letter (either upper or lower -case) are reserved for users; they are the @strong{only} sequences -reserved for users, so do not block them. - -Changing all the Emacs major modes to respect this convention was a -lot of work; abandoning this convention would make that work go to -waste, and inconvenience users. Please comply with it. - -@item -Function keys @key{F5} through @key{F9} without modifier keys are -also reserved for users to define. - -@item -Sequences consisting of @kbd{C-c} followed by a control character or a -digit are reserved for major modes. - -@item -Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}}, -@kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes. - -@item -Sequences consisting of @kbd{C-c} followed by any other punctuation -character are allocated for minor modes. Using them in a major mode is -not absolutely prohibited, but if you do that, the major mode binding -may be shadowed from time to time by minor modes. - -@item -Don't bind @kbd{C-h} following any prefix character (including -@kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically -available as a help character for listing the subcommands of the -prefix character. - -@item -Don't bind a key sequence ending in @key{ESC} except following another -@key{ESC}. (That is, it is OK to bind a sequence ending in -@kbd{@key{ESC} @key{ESC}}.) - -The reason for this rule is that a non-prefix binding for @key{ESC} in -any context prevents recognition of escape sequences as function keys in -that context. - -@item -Similarly, don't bind a key sequence ending in @key{C-g}, since that -is commonly used to cancel a key sequence. - -@item -Anything that acts like a temporary mode or state that the user can -enter and leave should define @kbd{@key{ESC} @key{ESC}} or -@kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape. - -For a state that accepts ordinary Emacs commands, or more generally any -kind of state in which @key{ESC} followed by a function key or arrow key -is potentially meaningful, then you must not define @kbd{@key{ESC} -@key{ESC}}, since that would preclude recognizing an escape sequence -after @key{ESC}. In these states, you should define @kbd{@key{ESC} -@key{ESC} @key{ESC}} as the way to escape. Otherwise, define -@kbd{@key{ESC} @key{ESC}} instead. -@end itemize - -@node Programming Tips -@section Emacs Programming Tips -@cindex programming conventions - - Following these conventions will make your program fit better -into Emacs when it runs. - -@itemize @bullet -@item -Don't use @code{next-line} or @code{previous-line} in programs; nearly -always, @code{forward-line} is more convenient as well as more -predictable and robust. @xref{Text Lines}. - -@item -Don't call functions that set the mark, unless setting the mark is one -of the intended features of your program. The mark is a user-level -feature, so it is incorrect to change the mark except to supply a value -for the user's benefit. @xref{The Mark}. - -In particular, don't use any of these functions: - -@itemize @bullet -@item -@code{beginning-of-buffer}, @code{end-of-buffer} -@item -@code{replace-string}, @code{replace-regexp} -@item -@code{insert-file}, @code{insert-buffer} -@end itemize - -If you just want to move point, or replace a certain string, or insert -a file or buffer's contents, without any of the other features -intended for interactive users, you can replace these functions with -one or two lines of simple Lisp code. - -@item -Use lists rather than vectors, except when there is a particular reason -to use a vector. Lisp has more facilities for manipulating lists than -for vectors, and working with lists is usually more convenient. - -Vectors are advantageous for tables that are substantial in size and are -accessed in random order (not searched front to back), provided there is -no need to insert or delete elements (only lists allow that). - -@item -The recommended way to show a message in the echo area is with -the @code{message} function, not @code{princ}. @xref{The Echo Area}. - -@item -When you encounter an error condition, call the function @code{error} -(or @code{signal}). The function @code{error} does not return. -@xref{Signaling Errors}. - -Don't use @code{message}, @code{throw}, @code{sleep-for}, or -@code{beep} to report errors. - -@item -An error message should start with a capital letter but should not end -with a period. - -@item -A question asked in the minibuffer with @code{yes-or-no-p} or -@code{y-or-n-p} should start with a capital letter and end with -@samp{? }. - -@item -When you mention a default value in a minibuffer prompt, -put it and the word @samp{default} inside parentheses. -It should look like this: - -@example -Enter the answer (default 42): -@end example - -@item -In @code{interactive}, if you use a Lisp expression to produce a list -of arguments, don't try to provide the ``correct'' default values for -region or position arguments. Instead, provide @code{nil} for those -arguments if they were not specified, and have the function body -compute the default value when the argument is @code{nil}. For -instance, write this: - -@example -(defun foo (pos) - (interactive - (list (if @var{specified} @var{specified-pos}))) - (unless pos (setq pos @var{default-pos})) - ...) -@end example - -@noindent -rather than this: - -@example -(defun foo (pos) - (interactive - (list (if @var{specified} @var{specified-pos} - @var{default-pos}))) - ...) -@end example - -@noindent -This is so that repetition of the command will recompute -these defaults based on the current circumstances. - -You do not need to take such precautions when you use interactive -specs @samp{d}, @samp{m} and @samp{r}, because they make special -arrangements to recompute the argument values on repetition of the -command. - -@item -Many commands that take a long time to execute display a message that -says something like @samp{Operating...} when they start, and change it -to @samp{Operating...done} when they finish. Please keep the style of -these messages uniform: @emph{no} space around the ellipsis, and -@emph{no} period after @samp{done}. @xref{Progress}, for an easy way -to generate such messages. - -@item -Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e} -command does: use a new local keymap that contains a command defined -to switch back to the old local keymap. Or simply switch to another -buffer and let the user switch back at will. @xref{Recursive Editing}. -@end itemize - -@node Compilation Tips -@section Tips for Making Compiled Code Fast -@cindex execution speed -@cindex speedups - - Here are ways of improving the execution speed of byte-compiled -Lisp programs. - -@itemize @bullet -@item -@cindex profiling -@cindex timing programs -@cindex @file{elp.el} -Profile your program with the @file{elp} library. See the file -@file{elp.el} for instructions. - -@item -@cindex @file{benchmark.el} -@cindex benchmarking -Check the speed of individual Emacs Lisp forms using the -@file{benchmark} library. See the functions @code{benchmark-run} and -@code{benchmark-run-compiled} in @file{benchmark.el}. - -@item -Use iteration rather than recursion whenever possible. -Function calls are slow in Emacs Lisp even when a compiled function -is calling another compiled function. - -@item -Using the primitive list-searching functions @code{memq}, @code{member}, -@code{assq}, or @code{assoc} is even faster than explicit iteration. It -can be worth rearranging a data structure so that one of these primitive -search functions can be used. - -@item -Certain built-in functions are handled specially in byte-compiled code, -avoiding the need for an ordinary function call. It is a good idea to -use these functions rather than alternatives. To see whether a function -is handled specially by the compiler, examine its @code{byte-compile} -property. If the property is non-@code{nil}, then the function is -handled specially. - -For example, the following input will show you that @code{aref} is -compiled specially (@pxref{Array Functions}): - -@example -@group -(get 'aref 'byte-compile) - @result{} byte-compile-two-args -@end group -@end example - -@noindent -Note that in this case (and many others), you must first load the -@file{bytecomp} library, which defines the @code{byte-compile} property. - -@item -If calling a small function accounts for a substantial part of your -program's running time, make the function inline. This eliminates -the function call overhead. Since making a function inline reduces -the flexibility of changing the program, don't do it unless it gives -a noticeable speedup in something slow enough that users care about -the speed. @xref{Inline Functions}. -@end itemize - -@node Warning Tips -@section Tips for Avoiding Compiler Warnings -@cindex byte compiler warnings, how to avoid - -@itemize @bullet -@item -Try to avoid compiler warnings about undefined free variables, by adding -dummy @code{defvar} definitions for these variables, like this: - -@example -(defvar foo) -@end example - -Such a definition has no effect except to tell the compiler -not to warn about uses of the variable @code{foo} in this file. - -@item -Similarly, to avoid a compiler warning about an undefined function -that you know @emph{will} be defined, use a @code{declare-function} -statement (@pxref{Declaring Functions}). - -@item -If you use many functions and variables from a certain file, you can -add a @code{require} for that package to avoid compilation warnings -for them. For instance, - -@example -(eval-when-compile - (require 'foo)) -@end example - -@item -If you bind a variable in one function, and use it or set it in -another function, the compiler warns about the latter function unless -the variable has a definition. But adding a definition would be -unclean if the variable has a short name, since Lisp packages should -not define short variable names. The right thing to do is to rename -this variable to start with the name prefix used for the other -functions and variables in your package. - -@item -The last resort for avoiding a warning, when you want to do something -that is usually a mistake but you know is not a mistake in your usage, -is to put it inside @code{with-no-warnings}. @xref{Compiler Errors}. -@end itemize - -@node Documentation Tips -@section Tips for Documentation Strings -@cindex documentation strings, conventions and tips - -@findex checkdoc-minor-mode - Here are some tips and conventions for the writing of documentation -strings. You can check many of these conventions by running the command -@kbd{M-x checkdoc-minor-mode}. - -@itemize @bullet -@item -Every command, function, or variable intended for users to know about -should have a documentation string. - -@item -An internal variable or subroutine of a Lisp program might as well -have a documentation string. Documentation strings take up very -little space in a running Emacs. - -@item -Format the documentation string so that it fits in an Emacs window on an -80-column screen. It is a good idea for most lines to be no wider than -60 characters. The first line should not be wider than 67 characters -or it will look bad in the output of @code{apropos}. - -You can fill the text if that looks good. However, rather than blindly -filling the entire documentation string, you can often make it much more -readable by choosing certain line breaks with care. Use blank lines -between sections if the documentation string is long. - -@item -The first line of the documentation string should consist of one or two -complete sentences that stand on their own as a summary. @kbd{M-x -apropos} displays just the first line, and if that line's contents don't -stand on their own, the result looks bad. In particular, start the -first line with a capital letter and end it with a period. - -For a function, the first line should briefly answer the question, -``What does this function do?'' For a variable, the first line should -briefly answer the question, ``What does this value mean?'' - -Don't limit the documentation string to one line; use as many lines as -you need to explain the details of how to use the function or -variable. Please use complete sentences for the rest of the text too. - -@item -When the user tries to use a disabled command, Emacs displays just the -first paragraph of its documentation string---everything through the -first blank line. If you wish, you can choose which information to -include before the first blank line so as to make this display useful. - -@item -The first line should mention all the important arguments of the -function, and should mention them in the order that they are written -in a function call. If the function has many arguments, then it is -not feasible to mention them all in the first line; in that case, the -first line should mention the first few arguments, including the most -important arguments. - -@item -When a function's documentation string mentions the value of an argument -of the function, use the argument name in capital letters as if it were -a name for that value. Thus, the documentation string of the function -@code{eval} refers to its first argument as @samp{FORM}, because the -actual argument name is @code{form}: - -@example -Evaluate FORM and return its value. -@end example - -Also write metasyntactic variables in capital letters, such as when you -show the decomposition of a list or vector into subunits, some of which -may vary. @samp{KEY} and @samp{VALUE} in the following example -illustrate this practice: - -@example -The argument TABLE should be an alist whose elements -have the form (KEY . VALUE). Here, KEY is ... -@end example - -@item -Never change the case of a Lisp symbol when you mention it in a doc -string. If the symbol's name is @code{foo}, write ``foo'', not -``Foo'' (which is a different symbol). - -This might appear to contradict the policy of writing function -argument values, but there is no real contradiction; the argument -@emph{value} is not the same thing as the @emph{symbol} that the -function uses to hold the value. - -If this puts a lower-case letter at the beginning of a sentence -and that annoys you, rewrite the sentence so that the symbol -is not at the start of it. - -@item -Do not start or end a documentation string with whitespace. - -@item -@strong{Do not} indent subsequent lines of a documentation string so -that the text is lined up in the source code with the text of the first -line. This looks nice in the source code, but looks bizarre when users -view the documentation. Remember that the indentation before the -starting double-quote is not part of the string! - -@anchor{Docstring hyperlinks} -@item -@iftex -When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), with single-quotes -around it. For example: @samp{`lambda'}. There are two exceptions: -write @code{t} and @code{nil} without single-quotes. -@end iftex -@ifnottex -When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), with single-quotes -around it. For example: @samp{lambda}. There are two exceptions: write -t and nil without single-quotes. (In this manual, we use a different -convention, with single-quotes for all symbols.) -@end ifnottex - -@cindex hyperlinks in documentation strings -Help mode automatically creates a hyperlink when a documentation string -uses a symbol name inside single quotes, if the symbol has either a -function or a variable definition. You do not need to do anything -special to make use of this feature. However, when a symbol has both a -function definition and a variable definition, and you want to refer to -just one of them, you can specify which one by writing one of the words -@samp{variable}, @samp{option}, @samp{function}, or @samp{command}, -immediately before the symbol name. (Case makes no difference in -recognizing these indicator words.) For example, if you write - -@example -This function sets the variable `buffer-file-name'. -@end example - -@noindent -then the hyperlink will refer only to the variable documentation of -@code{buffer-file-name}, and not to its function documentation. - -If a symbol has a function definition and/or a variable definition, but -those are irrelevant to the use of the symbol that you are documenting, -you can write the words @samp{symbol} or @samp{program} before the -symbol name to prevent making any hyperlink. For example, - -@example -If the argument KIND-OF-RESULT is the symbol `list', -this function returns a list of all the objects -that satisfy the criterion. -@end example - -@noindent -does not make a hyperlink to the documentation, irrelevant here, of the -function @code{list}. - -Normally, no hyperlink is made for a variable without variable -documentation. You can force a hyperlink for such variables by -preceding them with one of the words @samp{variable} or -@samp{option}. - -Hyperlinks for faces are only made if the face name is preceded or -followed by the word @samp{face}. In that case, only the face -documentation will be shown, even if the symbol is also defined as a -variable or as a function. - -To make a hyperlink to Info documentation, write the name of the Info -node (or anchor) in single quotes, preceded by @samp{info node}, -@samp{Info node}, @samp{info anchor} or @samp{Info anchor}. The Info -file name defaults to @samp{emacs}. For example, - -@smallexample -See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'. -@end smallexample - -Finally, to create a hyperlink to URLs, write the URL in single -quotes, preceded by @samp{URL}. For example, - -@smallexample -The home page for the GNU project has more information (see URL -`http://www.gnu.org/'). -@end smallexample - -@item -Don't write key sequences directly in documentation strings. Instead, -use the @samp{\\[@dots{}]} construct to stand for them. For example, -instead of writing @samp{C-f}, write the construct -@samp{\\[forward-char]}. When Emacs displays the documentation string, -it substitutes whatever key is currently bound to @code{forward-char}. -(This is normally @samp{C-f}, but it may be some other character if the -user has moved key bindings.) @xref{Keys in Documentation}. - -@item -In documentation strings for a major mode, you will want to refer to the -key bindings of that mode's local map, rather than global ones. -Therefore, use the construct @samp{\\<@dots{}>} once in the -documentation string to specify which key map to use. Do this before -the first use of @samp{\\[@dots{}]}. The text inside the -@samp{\\<@dots{}>} should be the name of the variable containing the -local keymap for the major mode. - -It is not practical to use @samp{\\[@dots{}]} very many times, because -display of the documentation string will become slow. So use this to -describe the most important commands in your major mode, and then use -@samp{\\@{@dots{}@}} to display the rest of the mode's keymap. - -@item -For consistency, phrase the verb in the first sentence of a function's -documentation string as an imperative---for instance, use ``Return the -cons of A and B.'' in preference to ``Returns the cons of A and B@.'' -Usually it looks good to do likewise for the rest of the first -paragraph. Subsequent paragraphs usually look better if each sentence -is indicative and has a proper subject. - -@item -The documentation string for a function that is a yes-or-no predicate -should start with words such as ``Return t if'', to indicate -explicitly what constitutes ``truth''. The word ``return'' avoids -starting the sentence with lower-case ``t'', which could be somewhat -distracting. - -@item -If a line in a documentation string begins with an open-parenthesis, -write a backslash before the open-parenthesis, like this: - -@example -The argument FOO can be either a number -\(a buffer position) or a string (a file name). -@end example - -This prevents the open-parenthesis from being treated as the start of a -defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). - -@item -Write documentation strings in the active voice, not the passive, and in -the present tense, not the future. For instance, use ``Return a list -containing A and B.'' instead of ``A list containing A and B will be -returned.'' - -@item -Avoid using the word ``cause'' (or its equivalents) unnecessarily. -Instead of, ``Cause Emacs to display text in boldface'', write just -``Display text in boldface''. - -@item -Avoid using ``iff'' (a mathematics term meaning ``if and only if''), -since many people are unfamiliar with it and mistake it for a typo. In -most cases, the meaning is clear with just ``if''. Otherwise, try to -find an alternate phrasing that conveys the meaning. - -@item -When a command is meaningful only in a certain mode or situation, -do mention that in the documentation string. For example, -the documentation of @code{dired-find-file} is: - -@example -In Dired, visit the file or directory named on this line. -@end example - -@item -When you define a variable that represents an option users might want -to set, use @code{defcustom}. @xref{Defining Variables}. - -@item -The documentation string for a variable that is a yes-or-no flag should -start with words such as ``Non-nil means'', to make it clear that -all non-@code{nil} values are equivalent and indicate explicitly what -@code{nil} and non-@code{nil} mean. -@end itemize - -@node Comment Tips -@section Tips on Writing Comments -@cindex comments, Lisp convention for - - We recommend these conventions for comments: - -@table @samp -@item ; -Comments that start with a single semicolon, @samp{;}, should all be -aligned to the same column on the right of the source code. Such -comments usually explain how the code on that line does its job. -For example: - -@smallexample -@group -(setq base-version-list ; there was a base - (assoc (substring fn 0 start-vn) ; version to which - file-version-assoc-list)) ; this looks like - ; a subversion -@end group -@end smallexample - -@item ;; -Comments that start with two semicolons, @samp{;;}, should be aligned to -the same level of indentation as the code. Such comments usually -describe the purpose of the following lines or the state of the program -at that point. For example: - -@smallexample -@group -(prog1 (setq auto-fill-function - @dots{} - @dots{} - ;; Update mode line. - (force-mode-line-update))) -@end group -@end smallexample - -We also normally use two semicolons for comments outside functions. - -@smallexample -@group -;; This Lisp code is run in Emacs when it is to operate as -;; a server for other processes. -@end group -@end smallexample - -If a function has no documentation string, it should instead have a -two-semicolon comment right before the function, explaining what the -function does and how to call it properly. Explain precisely what -each argument means and how the function interprets its possible -values. It is much better to convert such comments to documentation -strings, though. - -@item ;;; -Comments that start with three semicolons, @samp{;;;}, should start at -the left margin. These are used, occasionally, for comments within -functions that should start at the margin. We also use them sometimes -for comments that are between functions---whether to use two or three -semicolons depends on whether the comment should be considered a -``heading'' by Outline minor mode. By default, comments starting with -at least three semicolons (followed by a single space and a -non-whitespace character) are considered headings, comments starting -with two or fewer are not. - -Another use for triple-semicolon comments is for commenting out lines -within a function. We use three semicolons for this precisely so that -they remain at the left margin. By default, Outline minor mode does -not consider a comment to be a heading (even if it starts with at -least three semicolons) if the semicolons are followed by at least two -spaces. Thus, if you add an introductory comment to the commented out -code, make sure to indent it by at least two spaces after the three -semicolons. - -@smallexample -(defun foo (a) -;;; This is no longer necessary. -;;; (force-mode-line-update) - (message "Finished with %s" a)) -@end smallexample - -When commenting out entire functions, use two semicolons. - -@item ;;;; -Comments that start with four semicolons, @samp{;;;;}, should be aligned -to the left margin and are used for headings of major sections of a -program. For example: - -@smallexample -;;;; The kill ring -@end smallexample -@end table - -@noindent -Generally speaking, the @kbd{M-;} (@code{comment-dwim}) command -automatically starts a comment of the appropriate type; or indents an -existing comment to the right place, depending on the number of -semicolons. -@xref{Comments,, Manipulating Comments, emacs, The GNU Emacs Manual}. - -@node Library Headers -@section Conventional Headers for Emacs Libraries -@cindex header comments -@cindex library header comments - - Emacs has conventions for using special comments in Lisp libraries -to divide them into sections and give information such as who wrote -them. Using a standard format for these items makes it easier for -tools (and people) to extract the relevant information. This section -explains these conventions, starting with an example: - -@smallexample -@group -;;; foo.el --- Support for the Foo programming language - -;; Copyright (C) 2010-2012 Your Name -@end group - -;; Author: Your Name -;; Maintainer: Someone Else -;; Created: 14 Jul 2010 -@group -;; Keywords: languages - -;; This file is not part of GNU Emacs. - -;; This file is free software@dots{} -@dots{} -;; along with this file. If not, see . -@end group -@end smallexample - - The very first line should have this format: - -@example -;;; @var{filename} --- @var{description} -@end example - -@noindent -The description should be contained in one line. If the file -needs a @samp{-*-} specification, put it after @var{description}. -If this would make the first line too long, use a Local Variables -section at the end of the file. - - The copyright notice usually lists your name (if you wrote the -file). If you have an employer who claims copyright on your work, you -might need to list them instead. Do not say that the copyright holder -is the Free Software Foundation (or that the file is part of GNU -Emacs) unless your file has been accepted into the Emacs distribution. -For more information on the form of copyright and license notices, see -@uref{http://www.gnu.org/licenses/gpl-howto.html, the guide on the GNU -website}. - - After the copyright notice come several @dfn{header comment} lines, -each beginning with @samp{;; @var{header-name}:}. Here is a table of -the conventional possibilities for @var{header-name}: - -@table @samp -@item Author -This line states the name and email address of at least the principal -author of the library. If there are multiple authors, list them on -continuation lines led by @code{;;} and whitespace (this is easier -for tools to parse than having more than one author on one line). -We recommend including a contact email address, of the form -@samp{<@dots{}>}. For example: - -@smallexample -@group -;; Author: Your Name -;; Someone Else -;; Another Person -@end group -@end smallexample - -@item Maintainer -This header has the same format as the Author header. It lists the -person(s) who currently maintain(s) the file (respond to bug reports, -etc.). - -If there is no maintainer line, the person(s) in the Author field -is/are presumed to be the maintainers. Some files in Emacs use -@samp{FSF} for the maintainer. This means that the original author is -no longer responsible for the file, and that it is maintained as part -of Emacs. - -@item Created -This optional line gives the original creation date of the file, and -is for historical interest only. - -@item Version -If you wish to record version numbers for the individual Lisp program, -put them in this line. Lisp files distributed with Emacs generally do -not have a @samp{Version} header, since the version number of Emacs -itself serves the same purpose. If you are distributing a collection -of multiple files, we recommend not writing the version in every file, -but only the main one. - -@item Keywords -This line lists keywords for the @code{finder-by-keyword} help command. -Please use that command to see a list of the meaningful keywords. - -This field is how people will find your package when they're looking -for things by topic. To separate the keywords, you can use spaces, -commas, or both. - -The name of this field is unfortunate, since people often assume it is -the place to write arbitrary keywords that describe their package, -rather than just the relevant Finder keywords. - -@item Package-Version -If @samp{Version} is not suitable for use by the package manager, then -a package can define @samp{Package-Version}; it will be used instead. -This is handy if @samp{Version} is an RCS id or something else that -cannot be parsed by @code{version-to-list}. @xref{Packaging Basics}. - -@item Package-Requires -If this exists, it names packages on which the current package depends -for proper operation. @xref{Packaging Basics}. This is used by the -package manager both at download time (to ensure that a complete set -of packages is downloaded) and at activation time (to ensure that a -package is only activated if all its dependencies have been). - -Its format is a list of lists. The @code{car} of each sub-list is the -name of a package, as a symbol. The @code{cadr} of each sub-list is -the minimum acceptable version number, as a string. For instance: - -@smallexample -;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2")) -@end smallexample - -The package code automatically defines a package named @samp{emacs} -with the version number of the currently running Emacs. This can be -used to require a minimal version of Emacs for a package. -@end table - - Just about every Lisp library ought to have the @samp{Author} and -@samp{Keywords} header comment lines. Use the others if they are -appropriate. You can also put in header lines with other header -names---they have no standard meanings, so they can't do any harm. - - We use additional stylized comments to subdivide the contents of the -library file. These should be separated from anything else by blank -lines. Here is a table of them: - -@table @samp -@item ;;; Commentary: -This begins introductory comments that explain how the library works. -It should come right after the copying permissions, terminated by a -@samp{Change Log}, @samp{History} or @samp{Code} comment line. This -text is used by the Finder package, so it should make sense in that -context. - -@item ;;; Change Log: -This begins an optional log of changes to the file over time. Don't -put too much information in this section---it is better to keep the -detailed logs in a separate @file{ChangeLog} file (as Emacs does), -and/or to use a version control system. @samp{History} is an -alternative to @samp{Change Log}. - -@item ;;; Code: -This begins the actual code of the program. - -@item ;;; @var{filename} ends here -This is the @dfn{footer line}; it appears at the very end of the file. -Its purpose is to enable people to detect truncated versions of the file -from the lack of a footer line. -@end table diff --git a/doc/lispref/two-volume-cross-refs.txt b/doc/lispref/two-volume-cross-refs.txt deleted file mode 100644 index 67b5dbf89a3..00000000000 --- a/doc/lispref/two-volume-cross-refs.txt +++ /dev/null @@ -1,319 +0,0 @@ -Copyright (C) 2001-2012 Free Software Foundation, Inc. -See end for copying conditions. - -Two Volume Cross References -=========================== - -12 June 2007 (karl) - -For lispref 2.9 (for Emacs 22, June 2007), I created a very ugly -Makefile, in the file two-volume.make, to encapsulate all the steps -below, without manual intervention. In theory, simply running "make -f -two-volume.make" should create a vol1.pdf and vol2.pdf with all the -niceties worked out. - -One issue not explicitly discussed below is getting page numbers right. -It's not enough to go through the whole process. You have to go through -the whole process twice -- otherwise, some index entries and/or toc -entries will be off by one. See two-volume.make for a few more comments. - -For future editions, it should suffice to update the usual things in -vol[12].texi (as well as elisp.texi). That was my hope, anyway. - - -18 March 1992 (bob) - -This enables you to create manuals in *two* volumes, with tables of -contents, cross references, and indices in each volume referring to -*both* volumes. - -The procedure is tedious. However, the resulting two volumes are -conveniently organized. Each has an index of the whole two volumes. -Each volume starts with page 1. (I don't like multi-volume works -where each volume starts with a higher page number since I find it -harder to go to the right place in the volume.) - -References to the same volume are just the page number; references to -the other volume are a volume number (in Roman numerals) preceding -the page number. - -For example, in Volume I: - - list length ......... 90 - list motion ......II:117 - -and in Volume II: - - list length ....... I:90 - list motion .........117 - -All other references and the table of contents work the same way. I -find this *very* helpful. - - -In brief: you run tex on a .texi file with - - a. redefined @contents and @summarycontents inputting elisp-toc-2vol.toc file - b. redone .aux file - c. redone .fns file - - -Here are the steps in detail: - -% tex vol1.texi -% texindex vol1.?? -% tex vol1.texi - -% tex vol2.texi -% texindex vol2.?? -% tex vol2.texi - -### Create .aux files with volume numbers for other volume. - -% cp vol1.aux elisp1-aux -% cp vol2.aux elisp2-aux - -% cp vol1.aux elisp1-aux-vol-added -% cp vol2.aux elisp2-aux-vol-added - -on elisp1-aux-vol-number-added -(volume-aux-markup 1) see defun for volume-aux-markup below. -to create elisp1-aux-vol-added - -on elisp2-aux-vol-number-added -(volume-aux-markup 2) -to create elisp2-aux-vol-added - -insert elisp2-aux-vol-added into vol1.aux (append) -insert elisp1-aux-vol-added into vol2.aux (prepend) - -(so you don't have to do it again) -% cp vol1.aux elisp1-aux-ready -% cp vol2.aux elisp2-aux-ready - - -### Create .fn files with volume numbers for other volume. - -% cp vol1.fn elisp1-fn -% cp vol2.fn elisp2-fn - -% cp vol1.fn elisp1-fn-vol-number-added -% cp vol2.fn elisp2-fn-vol-number-added - -on elisp1-fn-vol-number-added -(volume-index-markup "I") -to create elisp1-fn-vol-number-added - -on elisp2-fn-vol-number-added -(volume-index-markup "II") -to create elisp2-fn-vol-number-added - -insert elisp2-fn-vol-number-added into vol1.fn: do following `cat' -insert elisp1-fn-vol-number-added into vol2.fn: do following `cat' - -% cat elisp2-fn-vol-number-added >> vol1.fn -% cat elisp1-fn-vol-number-added >> vol2.fn - -Be sure to handle special case entries by hand. -Be sure that .fn file has no blank lines. - -% texindex vol1.fn -% texindex vol2.fn - -(so you don't have to do it again) -% cp vol1.fns elisp1-fns-2vol-ready -% cp vol2.fns elisp2-fns-2vol-ready - -### Create merged .toc file with volume number headings. - -append vol2.toc to vol1.toc with following `cat' - -% cat vol1.toc vol2.toc > elisp-toc-2vol.toc - -and edit in Volume titles - -\unnumbchapentry {Volume 1}{} -\unnumbchapentry {}{} - -\unnumbchapentry {Index}{295} -\unnumbchapentry {}{} -\unnumbchapentry {Volume 2}{} -\unnumbchapentry {}{} - -If you want to put in volume numbers for TOC, then do this: -Create volume specific .toc files with volume numbers in them. - -% cp elisp-toc-2vol.toc elisp1-toc.toc -% cp elisp-toc-2vol.toc elisp2-toc.toc - -Use keyboard macro to put I: in first half of elisp1-toc.toc and -II: in first half of elisp2-toc.toc - -Copy the tocs to something you can remember more easily - -% cp elisp2-toc.toc elisp1-toc-ready.toc -% cp elisp1-toc.toc elisp2-toc-ready.toc - -Then, edit vol1.texi to input elisp1-toc-ready.toc -and vol2.texi to input elisp2-toc-ready.toc - - -### Now format the two volumes: - -% cp elisp1-aux-2vol-ready vol1.aux -% cp elisp2-aux-2vol-ready vol2.aux - -% tex vol1.texi -% tex vol2.texi - - - -For every additional run: - -### recopy aux files so the correct ones are read: -% cp elisp1-aux-2vol-ready vol1.aux -% cp elisp2-aux-2vol-ready vol2.aux - -Do not run texindex. Then proper sorted index will stay. - else do: % cp elisp2-fns-2vol-ready vol2.fns - -Do not change the .texi files; they will call the elisp-toc-2vol.toc file. - -% tex vol1.texi -% tex vol2.texi - -================================================================ - - -(defun volume-aux-markup (arg) - "Append `vol. NUMBER' to page number. -Apply to aux file that you save. -Then insert marked file into other volume's .aux file." - (interactive "sType volume number, 1 or 2: " ) - (goto-char (point-min)) - (while (search-forward "-pg" nil t) - (end-of-line 1) - (delete-backward-char 1 nil) - (insert ", vol.'tie" arg "}"))) - -(defun volume-index-markup (arg) - "Prepend `NUMBER:' to page number. Use Roman Numeral. -Apply only to unsorted index file, -Then insert marked file into other volume's unsorted index file. -Then run texindex on that file and save." - (interactive - "sType volume number, roman number I or II: " ) - (goto-char (point-min)) - (while (search-forward "\\entry" nil t) - (search-forward "}{" (save-excursion (end-of-line) (point)) nil) - (insert arg ":"))) - - -================================================================ - - -The steps: - -1. Run TeX, texindex and TeX on file1. -2. Run TeX, texindex and TeX on file2. - -3. Copy both .aux files into specially named files - -4. In the case of the elisp ref manual, - - copy the *unsorted* function index files into specially named files - (no other index used in elisp ref manual) - - -5. For aux files: - - Run a function on the specially named .aux files to label each - entry according to volume. Save these files. - - i.e., convert - 'xrdef {Special-pg}{7} to 'xrdef {Special-pg}{7, vol.'tie1} - -5a.Insert each specially named .aux file into the regular .aux file of - the other volume. - -6. For index files: - - Run a function on the specially named unsorted index files to label - each entry according to volume. Save these files. - -6b.Insert each specially named marked unsorted index file into the - regular unsorted file of the other volume. Run texindex on this - -7. Insert the other volumes .toc file into the .toc, edit, and rename to - elisp-toc-2vol.toc - -7a. insert special @contents and @summarycontents defs into .texi files. - -8. Run TeX on each .texi file. - -================ - - - -Here is the discursive commentary: - -I've been running some small test files, called test1.texi and -test2.texi. As far as I can see, if we run tex on the two test files, -tex creates a .aux for each that includes the names of all the nodes -in that file. The node names are used for cross references. - -If you insert the .aux file for the second test file, test2.aux, into -the .aux file for the first test file, test1.aux, then when you next -run TeX on the first test file, test1.texi, the second volume cross -references are inserted. - -You can edit the text of the cross reference in test2.aux to include -the volume number. - -For example, you can take the following two lines from test1.texi and -insert them into test2.texi: - - 'xrdef {Special-pg}{7} - 'xrdef {Special-snt}{Section'tie1.6} - -You can re-edit this to show that the page is in volume 1: - - 'xrdef {Special-pg}{7, vol.'tie1} - 'xrdef {Special-snt}{Section'tie1.6} - -(The 'tie is a TeX special command to keep the number tied on one -line to the previous word. I don't know if it works after a period in -the "vol." but figure it is worth trying. {The ' is the @ of .aux files.} -Apparently 'tie is like the tilde in plain tex; in texinfo.tex, the -definition for 'tie is the following: - - \def\tie{\penalty 10000\ } % Save plain tex definition of ~. - -) - -After running tex on the test2.texi file with the augmented test2.aux -file, you can see the following in the resulting DVI file: - - See Section 1.6 [Special], page 7, vol. 1 - -Note that TeX rewrites the .aux file each time TeX is run, so after -running Tex using an .aux file augmented with the .aux file from the -other volume, the new .aux file will *lack* the other volumes cross -references. Save your augmented .aux file in some other name for -another run! - - -COPYING CONDITIONS - -This file is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -This file is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this file. If not, see . diff --git a/doc/lispref/two-volume.make b/doc/lispref/two-volume.make deleted file mode 100644 index 07fcaf09b98..00000000000 --- a/doc/lispref/two-volume.make +++ /dev/null @@ -1,224 +0,0 @@ -# Copyright (C) 2007-2012 Free Software Foundation, Inc. -# See end for copying conditions. - -# although it would be nice to use tex rather than pdftex to avoid -# colors, spurious warnings about names being referenced but not -# existing, etc., dvips | ps2pdf doesn't preserve the page size. -# Instead of creating a special dvips config file, put up with the warnings. -texinfodir=../misc -emacsdir=../emacs - -tex = TEXINPUTS=".:$(texinfodir):${emacsdir}:${TEXINPUTS}" pdftex -interaction=nonstopmode - -all: vol1.pdf vol2.pdf - -# vol1.texi and vol2.texi specially define \tocreadfilename so we can -# use our premade .toc's. -# -vol1.pdf: elisp1med-fns-ready elisp1med-aux-ready elisp1med-toc-ready - @echo -e "\f Final TeX run for volume 1..." - cp elisp1med-toc-ready elisp1-toc-ready.toc - cp elisp1med-fns-ready vol1.fns - cp elisp1med-aux-ready vol1.aux - $(tex) vol1.texi -# -vol2.pdf: elisp2med-fns-ready elisp2med-aux-ready elisp2med-toc-ready - @echo "Final TeX run for volume 2..." - cp elisp2med-toc-ready elisp2-toc-ready.toc - cp elisp2med-fns-ready vol2.fns - cp elisp2med-aux-ready vol2.aux - $(tex) vol2.texi - -# intermediate toc files. -# -# vol1 toc: volume 1, page break, volume 2 (with II: prepended). -elisp1med-toc-ready: elisp1med-init elisp2med-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - cat elisp1med-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2med-toc >>$@ -# -# vol2 toc: volume 1 (with I: prepended), page break, volume 2. -elisp2med-toc-ready: elisp1med-init elisp2med-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1med-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - cat elisp2med-toc >>$@ - - -# intermediate aux files. -# -# append vol2's fixed aux to normal vol1. -elisp1med-aux-ready: elisp2med-aux-vol-added - cat elisp1med-aux $< >$@ -# -# prepend vol1's fixed aux to vol2. -elisp2med-aux-ready: elisp1med-aux-vol-added - cat $< elisp2med-aux >$@ - -# on -pg entries, append volume number after page number. -elisp1med-aux-vol-added: elisp1med-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1med-aux >$@ -# -elisp2med-aux-vol-added: elisp2med-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2med-aux >$@ - -# intermediate index (fns) file. -# -elisp1med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added - cat elisp2med-fn-vol-added >>vol1.fn - texindex vol1.fn - cp vol1.fns $@ -# -elisp2med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added - cat elisp1med-fn-vol-added >>vol2.fn - texindex vol2.fn - cp vol2.fns $@ - -# Insert volume number (I: or II:) into index file. -elisp1med-fn-vol-added: elisp1med-init - cp vol1.fn elisp1med-fn - sed 's/}{/}{I:/' elisp1med-fn >$@ -# -elisp2med-fn-vol-added: elisp2med-init - cp vol2.fn elisp2med-fn - sed 's/}{/}{II:/' elisp2med-fn >$@ - -# ----------------------------------------------------------------------------- -# everything above is essentially a duplicate of everything below. sorry. -# ----------------------------------------------------------------------------- - -# intermediate TeX runs. -# -# this generates what would be the final versions -- except the page -# numbers aren't right. The process of adding the I: and II: changes -# the page breaks, so a few index entries, at least are wrong. (In -# 2007, x-meta-keysym in vol.II ended up on page 374 when the index had -# it on page 375 from the initial run.) -# -# So, we start all over again, from these fns/aux/toc files. -# -elisp1med-init: elisp1-fns-ready elisp1-aux-ready elisp1init-toc-ready $(texinfodir)/texinfo.tex - @echo -e "\f Intermediate TeX run for volume 1..." - cp elisp1init-toc-ready elisp1-toc-ready.toc - cp elisp1-fns-ready vol1.fns - cp elisp1-aux-ready vol1.aux - $(tex) vol1.texi - texindex vol1.?? - mv vol1.aux elisp1med-aux - mv vol1.toc elisp1med-toc -# -elisp2med-init: elisp2-fns-ready elisp2-aux-ready elisp2init-toc-ready $(texinfodir)/texinfo.tex - @echo "Final TeX run for volume 2..." - cp elisp2init-toc-ready elisp2-toc-ready.toc - cp elisp2-fns-ready vol2.fns - cp elisp2-aux-ready vol2.aux - $(tex) vol2.texi - texindex vol2.?? - mv vol2.aux elisp2med-aux - mv vol2.toc elisp2med-toc - - -# initial toc files. -# -# vol1 toc: volume 1, page break, volume 2 (with II: prepended). -elisp1init-toc-ready: elisp1-init elisp2-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - cat elisp1-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2-toc >>$@ -# -# vol2 toc: volume 1 (with I: prepended), page break, volume 2. -elisp2init-toc-ready: elisp1-init elisp2-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - cat elisp2-toc >>$@ - - -# initial aux files. -# -# append vol2's fixed aux to normal vol1. The initial runs saved -# elisp1-aux and elisp2-aux. -elisp1-aux-ready: elisp2-aux-vol-added - cat elisp1-aux $< >$@ -# -# prepend vol1's fixed aux to vol2. -elisp2-aux-ready: elisp1-aux-vol-added - cat $< elisp2-aux >$@ - -# on -pg entries, append volume number after page number. -elisp1-aux-vol-added: elisp1-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1-aux >$@ -# -elisp2-aux-vol-added: elisp2-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2-aux >$@ - -# initial index (fns) file. -# -# Append other volume's index entries to this one's. -# Index entries in this volume will then take precedence. -elisp1-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added - cat elisp2-fn-vol-added >>vol1.fn - texindex vol1.fn - cp vol1.fns $@ -# -elisp2-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added - cat elisp1-fn-vol-added >>vol2.fn - texindex vol2.fn - cp vol2.fns $@ - -# Insert volume number (I: or II:) into index file. -elisp1-fn-vol-added: elisp1-init - cp vol1.fn elisp1-fn - sed 's/}{/}{I:/' elisp1-fn >$@ -# -elisp2-fn-vol-added: elisp2-init - cp vol2.fn elisp2-fn - sed 's/}{/}{II:/' elisp2-fn >$@ - - -# initial TeX runs. -# -# We use the .fn, .aux, and .toc files created here in subsequent -# processing. The page numbers generated here will not be correct yet, -# but we run texindex and TeX a second time just to get them closer. -# Otherwise it might take even longer for them to converge. -# -elisp1-init: vol1.texi - @echo -e "\f Initial TeX run for volume 1..." - rm -f vol1.aux vol1.toc - $(tex) $< - texindex vol1.?? - mv vol1.aux elisp1-aux - mv vol1.toc elisp1-toc - touch $@ -# -elisp2-init: vol2.texi - @echo "Initial TeX run for volume 2..." - rm -f vol2.aux vol2.toc - $(tex) $< - texindex vol2.?? - mv vol2.aux elisp2-aux - mv vol2.toc elisp2-toc - touch $@ - -# COPYING CONDITIONS -# -# This file is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This file is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this file. If not, see . - diff --git a/doc/lispref/two.el b/doc/lispref/two.el deleted file mode 100644 index 39dee62d45d..00000000000 --- a/doc/lispref/two.el +++ /dev/null @@ -1,78 +0,0 @@ -;; Auxiliary functions for preparing a two volume manual. - -;; Copyright (C) 2001-2012 Free Software Foundation, Inc. - -;; --rjc 30mar92 - -;; This file is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; This file is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with this file. If not, see . - - -(defun volume-aux-markup (arg) - "Append `vol. NUMBER' to page number. -Apply to aux file that you save. -Then insert marked file into other volume's .aux file." - (interactive "sType volume number, 1 or 2: " ) - (goto-char (point-min)) - (while (search-forward "-pg" nil t) - (end-of-line 1) - (delete-backward-char 1 nil) - (insert ", vol.'tie" arg "}"))) - -(defun volume-index-markup (arg) - "Prepend `NUMBER:' to page number. Use Roman Numeral. -Apply only to unsorted index file, -Then insert marked file into other volume's unsorted index file. -Then run texindex on that file and save." - (interactive - "sType volume number, roman number I or II: " ) - (goto-char (point-min)) - (while (search-forward "\\entry" nil t) - (search-forward "}{" (save-excursion (end-of-line) (point)) nil) - (insert arg ":"))) - -(defun volume-numbers-toc-markup (arg) - (interactive - "sType volume number, roman number I or II: " ) - (goto-char (point-min)) - (while (search-forward "chapentry" nil t) - (end-of-line) - (search-backward "{" nil t) - (forward-char 1) - (insert arg ":"))) - -(defun volume-header-toc-markup () - "Insert Volume I and Volume II text into .toc file. -NOTE: this auxiliary function is file specific. -This is for the *Elisp Ref Manual*." - (interactive) - (goto-char (point-min)) - (insert "\\unnumbchapentry {Volume 1}{}\n\\unnumbchapentry {}{}\n") - (search-forward "\\unnumbchapentry {Index}") - (forward-line 1) - (insert - "\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {Volume 2}{}\n\\unnumbchapentry {}{}\n")) - - -;;; In batch mode, you cannot call functions with args; hence this kludge: - -(defun volume-aux-markup-1 () (volume-aux-markup "1")) -(defun volume-aux-markup-2 () (volume-aux-markup "2")) - -(defun volume-index-markup-I () (volume-index-markup "I")) -(defun volume-index-markup-II () (volume-index-markup "II")) - -(defun volume-numbers-toc-markup-I () (volume-numbers-toc-markup "I")) -(defun volume-numbers-toc-markup-II () (volume-numbers-toc-markup "II")) - -;;; two.el ends here diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi deleted file mode 100644 index 93fb4d5f873..00000000000 --- a/doc/lispref/variables.texi +++ /dev/null @@ -1,1947 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/variables -@node Variables, Functions, Control Structures, Top -@chapter Variables -@cindex variable - - A @dfn{variable} is a name used in a program to stand for a value. -In Lisp, each variable is represented by a Lisp symbol -(@pxref{Symbols}). The variable name is simply the symbol's name, and -the variable's value is stored in the symbol's value cell@footnote{To -be precise, under the default @dfn{dynamic binding} rules the value -cell always holds the variable's current value, but this is not the -case under @dfn{lexical binding} rules. @xref{Variable Scoping}, for -details.}. @xref{Symbol Components}. In Emacs Lisp, the use of a -symbol as a variable is independent of its use as a function name. - - As previously noted in this manual, a Lisp program is represented -primarily by Lisp objects, and only secondarily as text. The textual -form of a Lisp program is given by the read syntax of the Lisp objects -that constitute the program. Hence, the textual form of a variable in -a Lisp program is written using the read syntax for the symbol -representing the variable. - -@menu -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Tips for Defining:: Things you should think about when you - define a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. -* File Local Variables:: Handling local variable lists in files. -* Directory Local Variables:: Local variables common to all files in a directory. -* Variable Aliases:: Variables that are aliases for other variables. -* Variables with Restricted Values:: Non-constant variables whose value can - @emph{not} be an arbitrary Lisp object. -@end menu - -@node Global Variables -@section Global Variables -@cindex global variable - - The simplest way to use a variable is @dfn{globally}. This means that -the variable has just one value at a time, and this value is in effect -(at least for the moment) throughout the Lisp system. The value remains -in effect until you specify a new one. When a new value replaces the -old one, no trace of the old value remains in the variable. - - You specify a value for a symbol with @code{setq}. For example, - -@example -(setq x '(a b)) -@end example - -@noindent -gives the variable @code{x} the value @code{(a b)}. Note that -@code{setq} is a special form (@pxref{Special Forms}); it does not -evaluate its first argument, the name of the variable, but it does -evaluate the second argument, the new value. - - Once the variable has a value, you can refer to it by using the -symbol itself as an expression. Thus, - -@example -@group -x @result{} (a b) -@end group -@end example - -@noindent -assuming the @code{setq} form shown above has already been executed. - - If you do set the same variable again, the new value replaces the old -one: - -@example -@group -x - @result{} (a b) -@end group -@group -(setq x 4) - @result{} 4 -@end group -@group -x - @result{} 4 -@end group -@end example - -@node Constant Variables -@section Variables that Never Change -@cindex @code{setting-constant} error -@cindex keyword symbol -@cindex variable with constant value -@cindex constant variables -@cindex symbol that evaluates to itself -@cindex symbol with constant value - - In Emacs Lisp, certain symbols normally evaluate to themselves. These -include @code{nil} and @code{t}, as well as any symbol whose name starts -with @samp{:} (these are called @dfn{keywords}). These symbols cannot -be rebound, nor can their values be changed. Any attempt to set or bind -@code{nil} or @code{t} signals a @code{setting-constant} error. The -same is true for a keyword (a symbol whose name starts with @samp{:}), -if it is interned in the standard obarray, except that setting such a -symbol to itself is not an error. - -@example -@group -nil @equiv{} 'nil - @result{} nil -@end group -@group -(setq nil 500) -@error{} Attempt to set constant symbol: nil -@end group -@end example - -@defun keywordp object -function returns @code{t} if @var{object} is a symbol whose name -starts with @samp{:}, interned in the standard obarray, and returns -@code{nil} otherwise. -@end defun - -These constants are fundamentally different from the ``constants'' -defined using the @code{defconst} special form (@pxref{Defining -Variables}). A @code{defconst} form serves to inform human readers -that you do not intend to change the value of a variable, but Emacs -does not raise an error if you actually change it. - -@node Local Variables -@section Local Variables -@cindex binding local variables -@cindex local variables -@cindex local binding -@cindex global binding - - Global variables have values that last until explicitly superseded -with new values. Sometimes it is useful to give a variable a -@dfn{local value}---a value that takes effect only within a certain -part of a Lisp program. When a variable has a local value, we say -that it is @dfn{locally bound} to that value, and that it is a -@dfn{local variable}. - - For example, when a function is called, its argument variables -receive local values, which are the actual arguments supplied to the -function call; these local bindings take effect within the body of the -function. To take another example, the @code{let} special form -explicitly establishes local bindings for specific variables, which -take effect within the body of the @code{let} form. - - We also speak of the @dfn{global binding}, which is where -(conceptually) the global value is kept. - -@cindex shadowing of variables - Establishing a local binding saves away the variable's previous -value (or lack of one). We say that the previous value is -@dfn{shadowed}. Both global and local values may be shadowed. If a -local binding is in effect, using @code{setq} on the local variable -stores the specified value in the local binding. When that local -binding is no longer in effect, the previously shadowed value (or lack -of one) comes back. - -@cindex current binding - A variable can have more than one local binding at a time (e.g.@: if -there are nested @code{let} forms that bind the variable). The -@dfn{current binding} is the local binding that is actually in effect. -It determines the value returned by evaluating the variable symbol, -and it is the binding acted on by @code{setq}. - - For most purposes, you can think of the current binding as the -``innermost'' local binding, or the global binding if there is no -local binding. To be more precise, a rule called the @dfn{scoping -rule} determines where in a program a local binding takes effect. The -default scoping rule in Emacs Lisp is called @dfn{dynamic scoping}, -which simply states that the current binding at any given point in the -execution of a program is the most recently-created binding for that -variable that still exists. For details about dynamic scoping, and an -alternative scoping rule called @dfn{lexical scoping}, @xref{Variable -Scoping}. - - The special forms @code{let} and @code{let*} exist to create local -bindings: - -@defspec let (bindings@dots{}) forms@dots{} -This special form sets up local bindings for a certain set of -variables, as specified by @var{bindings}, and then evaluates all of -the @var{forms} in textual order. Its return value is the value of -the last form in @var{forms}. - -Each of the @var{bindings} is either @w{(i) a} symbol, in which case -that symbol is locally bound to @code{nil}; or @w{(ii) a} list of the -form @code{(@var{symbol} @var{value-form})}, in which case -@var{symbol} is locally bound to the result of evaluating -@var{value-form}. If @var{value-form} is omitted, @code{nil} is used. - -All of the @var{value-form}s in @var{bindings} are evaluated in the -order they appear and @emph{before} binding any of the symbols to them. -Here is an example of this: @code{z} is bound to the old value of -@code{y}, which is 2, not the new value of @code{y}, which is 1. - -@example -@group -(setq y 2) - @result{} 2 -@end group - -@group -(let ((y 1) - (z y)) - (list y z)) - @result{} (1 2) -@end group -@end example -@end defspec - -@defspec let* (bindings@dots{}) forms@dots{} -This special form is like @code{let}, but it binds each variable right -after computing its local value, before computing the local value for -the next variable. Therefore, an expression in @var{bindings} can -refer to the preceding symbols bound in this @code{let*} form. -Compare the following example with the example above for @code{let}. - -@example -@group -(setq y 2) - @result{} 2 -@end group - -@group -(let* ((y 1) - (z y)) ; @r{Use the just-established value of @code{y}.} - (list y z)) - @result{} (1 1) -@end group -@end example -@end defspec - - Here is a complete list of the other facilities that create local -bindings: - -@itemize @bullet -@item -Function calls (@pxref{Functions}). - -@item -Macro calls (@pxref{Macros}). - -@item -@code{condition-case} (@pxref{Errors}). -@end itemize - - Variables can also have buffer-local bindings (@pxref{Buffer-Local -Variables}); a few variables have terminal-local bindings -(@pxref{Multiple Terminals}). These kinds of bindings work somewhat -like ordinary local bindings, but they are localized depending on -``where'' you are in Emacs. - -@defopt max-specpdl-size -@anchor{Definition of max-specpdl-size} -@cindex variable limit error -@cindex evaluation error -@cindex infinite recursion -This variable defines the limit on the total number of local variable -bindings and @code{unwind-protect} cleanups (see @ref{Cleanups,, -Cleaning Up from Nonlocal Exits}) that are allowed before Emacs -signals an error (with data @code{"Variable binding depth exceeds -max-specpdl-size"}). - -This limit, with the associated error when it is exceeded, is one way -that Lisp avoids infinite recursion on an ill-defined function. -@code{max-lisp-eval-depth} provides another limit on depth of nesting. -@xref{Definition of max-lisp-eval-depth,, Eval}. - -The default value is 1300. Entry to the Lisp debugger increases the -value, if there is little room left, to make sure the debugger itself -has room to execute. -@end defopt - -@node Void Variables -@section When a Variable is ``Void'' -@cindex @code{void-variable} error -@cindex void variable - - We say that a variable is void if its symbol has an unassigned value -cell (@pxref{Symbol Components}). Under Emacs Lisp's default dynamic -binding rules (@pxref{Variable Scoping}), the value cell stores the -variable's current (local or global) value. Note that an unassigned -value cell is @emph{not} the same as having @code{nil} in the value -cell. The symbol @code{nil} is a Lisp object and can be the value of -a variable, just as any other object can be; but it is still a value. -If a variable is void, trying to evaluate the variable signals a -@code{void-variable} error rather than a value. - - Under lexical binding rules, the value cell only holds the -variable's global value, i.e.@: the value outside of any lexical -binding construct. When a variable is lexically bound, the local value -is determined by the lexical environment; the variable may have a -local value if its symbol's value cell is unassigned. - -@defun makunbound symbol -This function empties out the value cell of @var{symbol}, making the -variable void. It returns @var{symbol}. - -If @var{symbol} has a dynamic local binding, @code{makunbound} voids -the current binding, and this voidness lasts only as long as the local -binding is in effect. Afterwards, the previously shadowed local or -global binding is reexposed; then the variable will no longer be void, -unless the reexposed binding is void too. - -Here are some examples (assuming dynamic binding is in effect): - -@smallexample -@group -(setq x 1) ; @r{Put a value in the global binding.} - @result{} 1 -(let ((x 2)) ; @r{Locally bind it.} - (makunbound 'x) ; @r{Void the local binding.} - x) -@error{} Symbol's value as variable is void: x -@end group -@group -x ; @r{The global binding is unchanged.} - @result{} 1 - -(let ((x 2)) ; @r{Locally bind it.} - (let ((x 3)) ; @r{And again.} - (makunbound 'x) ; @r{Void the innermost-local binding.} - x)) ; @r{And refer: it's void.} -@error{} Symbol's value as variable is void: x -@end group - -@group -(let ((x 2)) - (let ((x 3)) - (makunbound 'x)) ; @r{Void inner binding, then remove it.} - x) ; @r{Now outer @code{let} binding is visible.} - @result{} 2 -@end group -@end smallexample -@end defun - -@defun boundp variable -This function returns @code{t} if @var{variable} (a symbol) is not -void, and @code{nil} if it is void. - -Here are some examples (assuming dynamic binding is in effect): - -@smallexample -@group -(boundp 'abracadabra) ; @r{Starts out void.} - @result{} nil -@end group -@group -(let ((abracadabra 5)) ; @r{Locally bind it.} - (boundp 'abracadabra)) - @result{} t -@end group -@group -(boundp 'abracadabra) ; @r{Still globally void.} - @result{} nil -@end group -@group -(setq abracadabra 5) ; @r{Make it globally nonvoid.} - @result{} 5 -@end group -@group -(boundp 'abracadabra) - @result{} t -@end group -@end smallexample -@end defun - -@node Defining Variables -@section Defining Global Variables -@cindex variable definition - - A @dfn{variable definition} is a construct that announces your -intention to use a symbol as a global variable. It uses the special -forms @code{defvar} or @code{defconst}, which are documented below. - - A variable definition serves three purposes. First, it informs -people who read the code that the symbol is @emph{intended} to be used -a certain way (as a variable). Second, it informs the Lisp system of -this, optionally supplying an initial value and a documentation -string. Third, it provides information to programming tools such as -@command{etags}, allowing them to find where the variable was defined. - - The difference between @code{defconst} and @code{defvar} is mainly a -matter of intent, serving to inform human readers of whether the value -should ever change. Emacs Lisp does not actually prevent you from -changing the value of a variable defined with @code{defconst}. One -notable difference between the two forms is that @code{defconst} -unconditionally initializes the variable, whereas @code{defvar} -initializes it only if it is originally void. - - To define a customizable variable, you should use @code{defcustom} -(which calls @code{defvar} as a subroutine). @xref{Customization}. - -@defspec defvar symbol [value [doc-string]] -This special form defines @var{symbol} as a variable. Note that -@var{symbol} is not evaluated; the symbol to be defined should appear -explicitly in the @code{defvar} form. The variable is marked as -@dfn{special}, meaning that it should always be dynamically bound -(@pxref{Variable Scoping}). - -If @var{symbol} is void and @var{value} is specified, @code{defvar} -evaluates @var{value} and sets @var{symbol} to the result. But if -@var{symbol} already has a value (i.e.@: it is not void), @var{value} -is not even evaluated, and @var{symbol}'s value remains unchanged. If -@var{value} is omitted, the value of @var{symbol} is not changed in -any case. - -If @var{symbol} has a buffer-local binding in the current buffer, -@code{defvar} operates on the default value, which is buffer-independent, -not the current (buffer-local) binding. It sets the default value if -the default value is void. @xref{Buffer-Local Variables}. - -When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in -Emacs Lisp mode (@code{eval-defun}), a special feature of -@code{eval-defun} arranges to set the variable unconditionally, without -testing whether its value is void. - -If the @var{doc-string} argument is supplied, it specifies the -documentation string for the variable (stored in the symbol's -@code{variable-documentation} property). @xref{Documentation}. - -Here are some examples. This form defines @code{foo} but does not -initialize it: - -@example -@group -(defvar foo) - @result{} foo -@end group -@end example - -This example initializes the value of @code{bar} to @code{23}, and gives -it a documentation string: - -@example -@group -(defvar bar 23 - "The normal weight of a bar.") - @result{} bar -@end group -@end example - -The @code{defvar} form returns @var{symbol}, but it is normally used -at top level in a file where its value does not matter. -@end defspec - -@cindex constant variables -@defspec defconst symbol value [doc-string] -This special form defines @var{symbol} as a value and initializes it. -It informs a person reading your code that @var{symbol} has a standard -global value, established here, that should not be changed by the user -or by other programs. Note that @var{symbol} is not evaluated; the -symbol to be defined must appear explicitly in the @code{defconst}. - -The @code{defconst} form, like @code{defvar}, marks the variable as -@dfn{special}, meaning that it should always be dynamically bound -(@pxref{Variable Scoping}). In addition, it marks the variable as -risky (@pxref{File Local Variables}). - -@code{defconst} always evaluates @var{value}, and sets the value of -@var{symbol} to the result. If @var{symbol} does have a buffer-local -binding in the current buffer, @code{defconst} sets the default value, -not the buffer-local value. (But you should not be making -buffer-local bindings for a symbol that is defined with -@code{defconst}.) - -An example of the use of @code{defconst} is Emacs's definition of -@code{float-pi}---the mathematical constant @math{pi}, which ought not -to be changed by anyone (attempts by the Indiana State Legislature -notwithstanding). As the second form illustrates, however, -@code{defconst} is only advisory. - -@example -@group -(defconst float-pi 3.141592653589793 "The value of Pi.") - @result{} float-pi -@end group -@group -(setq float-pi 3) - @result{} float-pi -@end group -@group -float-pi - @result{} 3 -@end group -@end example -@end defspec - - @strong{Warning:} If you use a @code{defconst} or @code{defvar} -special form while the variable has a local binding (made with -@code{let}, or a function argument), it sets the local binding rather -than the global binding. This is not what you usually want. To -prevent this, use these special forms at top level in a file, where -normally no local binding is in effect, and make sure to load the file -before making a local binding for the variable. - -@node Tips for Defining -@section Tips for Defining Variables Robustly - - When you define a variable whose value is a function, or a list of -functions, use a name that ends in @samp{-function} or -@samp{-functions}, respectively. - - There are several other variable name conventions; -here is a complete list: - -@table @samp -@item @dots{}-hook -The variable is a normal hook (@pxref{Hooks}). - -@item @dots{}-function -The value is a function. - -@item @dots{}-functions -The value is a list of functions. - -@item @dots{}-form -The value is a form (an expression). - -@item @dots{}-forms -The value is a list of forms (expressions). - -@item @dots{}-predicate -The value is a predicate---a function of one argument that returns -non-@code{nil} for ``good'' arguments and @code{nil} for ``bad'' -arguments. - -@item @dots{}-flag -The value is significant only as to whether it is @code{nil} or not. -Since such variables often end up acquiring more values over time, -this convention is not strongly recommended. - -@item @dots{}-program -The value is a program name. - -@item @dots{}-command -The value is a whole shell command. - -@item @dots{}-switches -The value specifies options for a command. -@end table - - When you define a variable, always consider whether you should mark -it as ``safe'' or ``risky''; see @ref{File Local Variables}. - - When defining and initializing a variable that holds a complicated -value (such as a keymap with bindings in it), it's best to put the -entire computation of the value into the @code{defvar}, like this: - -@example -(defvar my-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) - @dots{} - map) - @var{docstring}) -@end example - -@noindent -This method has several benefits. First, if the user quits while -loading the file, the variable is either still uninitialized or -initialized properly, never in-between. If it is still uninitialized, -reloading the file will initialize it properly. Second, reloading the -file once the variable is initialized will not alter it; that is -important if the user has run hooks to alter part of the contents -(such as, to rebind keys). Third, evaluating the @code{defvar} form -with @kbd{C-M-x} will reinitialize the map completely. - - Putting so much code in the @code{defvar} form has one disadvantage: -it puts the documentation string far away from the line which names the -variable. Here's a safe way to avoid that: - -@example -(defvar my-mode-map nil - @var{docstring}) -(unless my-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) - @dots{} - (setq my-mode-map map))) -@end example - -@noindent -This has all the same advantages as putting the initialization inside -the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on -each form, if you do want to reinitialize the variable. - -@node Accessing Variables -@section Accessing Variable Values - - The usual way to reference a variable is to write the symbol which -names it. @xref{Symbol Forms}. - - Occasionally, you may want to reference a variable which is only -determined at run time. In that case, you cannot specify the variable -name in the text of the program. You can use the @code{symbol-value} -function to extract the value. - -@defun symbol-value symbol -This function returns the value stored in @var{symbol}'s value cell. -This is where the variable's current (dynamic) value is stored. If -the variable has no local binding, this is simply its global value. -If the variable is void, a @code{void-variable} error is signaled. - -If the variable is lexically bound, the value reported by -@code{symbol-value} is not necessarily the same as the variable's -lexical value, which is determined by the lexical environment rather -than the symbol's value cell. @xref{Variable Scoping}. - -@example -@group -(setq abracadabra 5) - @result{} 5 -@end group -@group -(setq foo 9) - @result{} 9 -@end group - -@group -;; @r{Here the symbol @code{abracadabra}} -;; @r{is the symbol whose value is examined.} -(let ((abracadabra 'foo)) - (symbol-value 'abracadabra)) - @result{} foo -@end group - -@group -;; @r{Here, the value of @code{abracadabra},} -;; @r{which is @code{foo},} -;; @r{is the symbol whose value is examined.} -(let ((abracadabra 'foo)) - (symbol-value abracadabra)) - @result{} 9 -@end group - -@group -(symbol-value 'abracadabra) - @result{} 5 -@end group -@end example -@end defun - -@node Setting Variables -@section Setting Variable Values - - The usual way to change the value of a variable is with the special -form @code{setq}. When you need to compute the choice of variable at -run time, use the function @code{set}. - -@defspec setq [symbol form]@dots{} -This special form is the most common method of changing a variable's -value. Each @var{symbol} is given a new value, which is the result of -evaluating the corresponding @var{form}. The current binding of the -symbol is changed. - -@code{setq} does not evaluate @var{symbol}; it sets the symbol that you -write. We say that this argument is @dfn{automatically quoted}. The -@samp{q} in @code{setq} stands for ``quoted''. - -The value of the @code{setq} form is the value of the last @var{form}. - -@example -@group -(setq x (1+ 2)) - @result{} 3 -@end group -x ; @r{@code{x} now has a global value.} - @result{} 3 -@group -(let ((x 5)) - (setq x 6) ; @r{The local binding of @code{x} is set.} - x) - @result{} 6 -@end group -x ; @r{The global value is unchanged.} - @result{} 3 -@end example - -Note that the first @var{form} is evaluated, then the first -@var{symbol} is set, then the second @var{form} is evaluated, then the -second @var{symbol} is set, and so on: - -@example -@group -(setq x 10 ; @r{Notice that @code{x} is set before} - y (1+ x)) ; @r{the value of @code{y} is computed.} - @result{} 11 -@end group -@end example -@end defspec - -@defun set symbol value -This function puts @var{value} in the value cell of @var{symbol}. -Since it is a function rather than a special form, the expression -written for @var{symbol} is evaluated to obtain the symbol to set. -The return value is @var{value}. - -When dynamic variable binding is in effect (the default), @code{set} -has the same effect as @code{setq}, apart from the fact that -@code{set} evaluates its @var{symbol} argument whereas @code{setq} -does not. But when a variable is lexically bound, @code{set} affects -its @emph{dynamic} value, whereas @code{setq} affects its current -(lexical) value. @xref{Variable Scoping}. - -@example -@group -(set one 1) -@error{} Symbol's value as variable is void: one -@end group -@group -(set 'one 1) - @result{} 1 -@end group -@group -(set 'two 'one) - @result{} one -@end group -@group -(set two 2) ; @r{@code{two} evaluates to symbol @code{one}.} - @result{} 2 -@end group -@group -one ; @r{So it is @code{one} that was set.} - @result{} 2 -(let ((one 1)) ; @r{This binding of @code{one} is set,} - (set 'one 3) ; @r{not the global value.} - one) - @result{} 3 -@end group -@group -one - @result{} 2 -@end group -@end example - -If @var{symbol} is not actually a symbol, a @code{wrong-type-argument} -error is signaled. - -@example -(set '(x y) 'z) -@error{} Wrong type argument: symbolp, (x y) -@end example -@end defun - -@node Variable Scoping -@section Scoping Rules for Variable Bindings - - When you create a local binding for a variable, that binding takes -effect only within a limited portion of the program (@pxref{Local -Variables}). This section describes exactly what this means. - -@cindex scope -@cindex extent - Each local binding has a certain @dfn{scope} and @dfn{extent}. -@dfn{Scope} refers to @emph{where} in the textual source code the -binding can be accessed. @dfn{Extent} refers to @emph{when}, as the -program is executing, the binding exists. - -@cindex dynamic binding -@cindex indefinite scope -@cindex dynamic extent - By default, the local bindings that Emacs creates are @dfn{dynamic -bindings}. Such a binding has @dfn{indefinite scope}, meaning that -any part of the program can potentially access the variable binding. -It also has @dfn{dynamic extent}, meaning that the binding lasts only -while the binding construct (such as the body of a @code{let} form) is -being executed. - -@cindex lexical binding -@cindex lexical scope -@cindex indefinite extent - Emacs can optionally create @dfn{lexical bindings}. A lexical -binding has @dfn{lexical scope}, meaning that any reference to the -variable must be located textually within the binding construct. It -also has @dfn{indefinite extent}, meaning that under some -circumstances the binding can live on even after the binding construct -has finished executing, by means of special objects called -@dfn{closures}. - - The following subsections describe dynamic binding and lexical -binding in greater detail, and how to enable lexical binding in Emacs -Lisp programs. - -@menu -* Dynamic Binding:: The default for binding local variables in Emacs. -* Dynamic Binding Tips:: Avoiding problems with dynamic binding. -* Lexical Binding:: A different type of local variable binding. -* Using Lexical Binding:: How to enable lexical binding. -@end menu - -@node Dynamic Binding -@subsection Dynamic Binding - - By default, the local variable bindings made by Emacs are dynamic -bindings. When a variable is dynamically bound, its current binding -at any point in the execution of the Lisp program is simply the most -recently-created dynamic local binding for that symbol, or the global -binding if there is no such local binding. - - Dynamic bindings have indefinite scope and dynamic extent, as shown -by the following example: - -@example -@group -(defvar x -99) ; @r{@code{x} receives an initial value of -99.} - -(defun getx () - x) ; @r{@code{x} is used ``free'' in this function.} - -(let ((x 1)) ; @r{@code{x} is dynamically bound.} - (getx)) - @result{} 1 - -;; @r{After the @code{let} form finishes, @code{x} reverts to its} -;; @r{previous value, which is -99.} - -(getx) - @result{} -99 -@end group -@end example - -@noindent -The function @code{getx} refers to @code{x}. This is a ``free'' -reference, in the sense that there is no binding for @code{x} within -that @code{defun} construct itself. When we call @code{getx} from -within a @code{let} form in which @code{x} is (dynamically) bound, it -retrieves the local value of @code{x} (i.e.@: 1). But when we call -@code{getx} outside the @code{let} form, it retrieves the global value -of @code{x} (i.e.@: -99). - - Here is another example, which illustrates setting a dynamically -bound variable using @code{setq}: - -@example -@group -(defvar x -99) ; @r{@code{x} receives an initial value of -99.} - -(defun addx () - (setq x (1+ x))) ; @r{Add 1 to @code{x} and return its new value.} - -(let ((x 1)) - (addx) - (addx)) - @result{} 3 ; @r{The two @code{addx} calls add to @code{x} twice.} - -;; @r{After the @code{let} form finishes, @code{x} reverts to its} -;; @r{previous value, which is -99.} - -(addx) - @result{} -98 -@end group -@end example - - Dynamic binding is implemented in Emacs Lisp in a simple way. Each -symbol has a value cell, which specifies its current dynamic value (or -absence of value). @xref{Symbol Components}. When a symbol is given -a dynamic local binding, Emacs records the contents of the value cell -(or absence thereof) in a stack, and stores the new local value in the -value cell. When the binding construct finishes executing, Emacs pops -the old value off the stack, and puts it in the value cell. - -@node Dynamic Binding Tips -@subsection Proper Use of Dynamic Binding - - Dynamic binding is a powerful feature, as it allows programs to -refer to variables that are not defined within their local textual -scope. However, if used without restraint, this can also make -programs hard to understand. There are two clean ways to use this -technique: - -@itemize @bullet -@item -If a variable has no global definition, use it as a local variable -only within a binding construct, e.g.@: the body of the @code{let} -form where the variable was bound, or the body of the function for an -argument variable. If this convention is followed consistently -throughout a program, the value of the variable will not affect, nor -be affected by, any uses of the same variable symbol elsewhere in the -program. - -@item -Otherwise, define the variable with @code{defvar}, @code{defconst}, or -@code{defcustom}. @xref{Defining Variables}. Usually, the definition -should be at top-level in an Emacs Lisp file. As far as possible, it -should include a documentation string which explains the meaning and -purpose of the variable. You should also choose the variable's name -to avoid name conflicts (@pxref{Coding Conventions}). - -Then you can bind the variable anywhere in a program, knowing reliably -what the effect will be. Wherever you encounter the variable, it will -be easy to refer back to the definition, e.g.@: via the @kbd{C-h v} -command (provided the variable definition has been loaded into Emacs). -@xref{Name Help,,, emacs, The GNU Emacs Manual}. - -For example, it is common to use local bindings for customizable -variables like @code{case-fold-search}: - -@example -@group -(defun search-for-abc () - "Search for the string \"abc\", ignoring case differences." - (let ((case-fold-search nil)) - (re-search-forward "abc"))) -@end group -@end example -@end itemize - -@node Lexical Binding -@subsection Lexical Binding - -Optionally, you can create lexical bindings in Emacs Lisp. A -lexically bound variable has @dfn{lexical scope}, meaning that any -reference to the variable must be located textually within the binding -construct. - - Here is an example -@iftex -(see the next subsection, for how to actually enable lexical binding): -@end iftex -@ifnottex -(@pxref{Using Lexical Binding}, for how to actually enable lexical binding): -@end ifnottex - -@example -@group -(let ((x 1)) ; @r{@code{x} is lexically bound.} - (+ x 3)) - @result{} 4 - -(defun getx () - x) ; @r{@code{x} is used ``free'' in this function.} - -(let ((x 1)) ; @r{@code{x} is lexically bound.} - (getx)) -@error{} Symbol's value as variable is void: x -@end group -@end example - -@noindent -Here, the variable @code{x} has no global value. When it is lexically -bound within a @code{let} form, it can be used in the textual confines -of that @code{let} form. But it can @emph{not} be used from within a -@code{getx} function called from the @code{let} form, since the -function definition of @code{getx} occurs outside the @code{let} form -itself. - -@cindex lexical environment - Here is how lexical binding works. Each binding construct defines a -@dfn{lexical environment}, specifying the symbols that are bound -within the construct and their local values. When the Lisp evaluator -wants the current value of a variable, it looks first in the lexical -environment; if the variable is not specified in there, it looks in -the symbol's value cell, where the dynamic value is stored. - -@cindex closures - Lexical bindings have indefinite extent. Even after a binding -construct has finished executing, its lexical environment can be -``kept around'' in Lisp objects called @dfn{closures}. A closure is -created when you create a named or anonymous function with lexical -binding enabled. @xref{Closures}, for details. - - When a closure is called as a function, any lexical variable -references within its definition use the retained lexical environment. -Here is an example: - -@example -(defvar my-ticker nil) ; @r{We will use this dynamically bound} - ; @r{variable to store a closure.} - -(let ((x 0)) ; @r{@code{x} is lexically bound.} - (setq my-ticker (lambda () - (setq x (1+ x))))) - @result{} (closure ((x . 0) t) () - (1+ x)) - -(funcall my-ticker) - @result{} 1 - -(funcall my-ticker) - @result{} 2 - -(funcall my-ticker) - @result{} 3 - -x ; @r{Note that @code{x} has no global value.} -@error{} Symbol's value as variable is void: x -@end example - -@noindent -The @code{let} binding defines a lexical environment in which the -variable @code{x} is locally bound to 0. Within this binding -construct, we define a lambda expression which increments @code{x} by -one and returns the incremented value. This lambda expression is -automatically turned into a closure, in which the lexical environment -lives on even after the @code{let} binding construct has exited. Each -time we evaluate the closure, it increments @code{x}, using the -binding of @code{x} in that lexical environment. - - Note that functions like @code{symbol-value}, @code{boundp}, and -@code{set} only retrieve or modify a variable's dynamic binding -(i.e.@: the contents of its symbol's value cell). Also, the code in -the body of a @code{defun} or @code{defmacro} cannot refer to -surrounding lexical variables. - - Currently, lexical binding is not much used within the Emacs -sources. However, we expect its importance to increase in the future. -Lexical binding opens up a lot more opportunities for optimization, so -Emacs Lisp code that makes use of lexical binding is likely to run -faster in future Emacs versions. Such code is also much more friendly -to concurrency, which we want to add to Emacs in the near future. - -@node Using Lexical Binding -@subsection Using Lexical Binding - - When loading an Emacs Lisp file or evaluating a Lisp buffer, lexical -binding is enabled if the buffer-local variable @code{lexical-binding} -is non-@code{nil}: - -@defvar lexical-binding -If this buffer-local variable is non-@code{nil}, Emacs Lisp files and -buffers are evaluated using lexical binding instead of dynamic -binding. (However, special variables are still dynamically bound; see -below.) If @code{nil}, dynamic binding is used for all local -variables. This variable is typically set for a whole Emacs Lisp -file, as a file local variable (@pxref{File Local Variables}). -Note that unlike other such variables, this one must be set in the -first line of a file. -@end defvar - -@noindent -When evaluating Emacs Lisp code directly using an @code{eval} call, -lexical binding is enabled if the @var{lexical} argument to -@code{eval} is non-@code{nil}. @xref{Eval}. - -@cindex special variables - Even when lexical binding is enabled, certain variables will -continue to be dynamically bound. These are called @dfn{special -variables}. Every variable that has been defined with @code{defvar}, -@code{defcustom} or @code{defconst} is a special variable -(@pxref{Defining Variables}). All other variables are subject to -lexical binding. - -@defun special-variable-p SYMBOL -This function returns non-@code{nil} if @var{symbol} is a special -variable (i.e.@: it has a @code{defvar}, @code{defcustom}, or -@code{defconst} variable definition). Otherwise, the return value is -@code{nil}. -@end defun - - The use of a special variable as a formal argument in a function is -discouraged. Doing so gives rise to unspecified behavior when lexical -binding mode is enabled (it may use lexical binding sometimes, and -dynamic binding other times). - - Converting an Emacs Lisp program to lexical binding is pretty easy. -First, add a file-local variable setting of @code{lexical-binding} to -@code{t} in the Emacs Lisp source file. Second, check that every -variable in the program which needs to be dynamically bound has a -variable definition, so that it is not inadvertently bound lexically. - - A simple way to find out which variables need a variable definition -is to byte-compile the source file. @xref{Byte Compilation}. If a -non-special variable is used outside of a @code{let} form, the -byte-compiler will warn about reference or assignment to a ``free -variable''. If a non-special variable is bound but not used within a -@code{let} form, the byte-compiler will warn about an ``unused lexical -variable''. The byte-compiler will also issue a warning if you use a -special variable as a function argument. - - (To silence byte-compiler warnings about unused variables, just use -a variable name that start with an underscore. The byte-compiler -interprets this as an indication that this is a variable known not to -be used.) - -@node Buffer-Local Variables -@section Buffer-Local Variables -@cindex variable, buffer-local -@cindex buffer-local variables - - Global and local variable bindings are found in most programming -languages in one form or another. Emacs, however, also supports -additional, unusual kinds of variable binding, such as -@dfn{buffer-local} bindings, which apply only in one buffer. Having -different values for a variable in different buffers is an important -customization method. (Variables can also have bindings that are -local to each terminal. @xref{Multiple Terminals}.) - -@menu -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own buffer-local values. -@end menu - -@node Intro to Buffer-Local -@subsection Introduction to Buffer-Local Variables - - A buffer-local variable has a buffer-local binding associated with a -particular buffer. The binding is in effect when that buffer is -current; otherwise, it is not in effect. If you set the variable while -a buffer-local binding is in effect, the new value goes in that binding, -so its other bindings are unchanged. This means that the change is -visible only in the buffer where you made it. - - The variable's ordinary binding, which is not associated with any -specific buffer, is called the @dfn{default binding}. In most cases, -this is the global binding. - - A variable can have buffer-local bindings in some buffers but not in -other buffers. The default binding is shared by all the buffers that -don't have their own bindings for the variable. (This includes all -newly-created buffers.) If you set the variable in a buffer that does -not have a buffer-local binding for it, this sets the default binding, -so the new value is visible in all the buffers that see the default -binding. - - The most common use of buffer-local bindings is for major modes to change -variables that control the behavior of commands. For example, C mode and -Lisp mode both set the variable @code{paragraph-start} to specify that only -blank lines separate paragraphs. They do this by making the variable -buffer-local in the buffer that is being put into C mode or Lisp mode, and -then setting it to the new value for that mode. @xref{Major Modes}. - - The usual way to make a buffer-local binding is with -@code{make-local-variable}, which is what major mode commands typically -use. This affects just the current buffer; all other buffers (including -those yet to be created) will continue to share the default value unless -they are explicitly given their own buffer-local bindings. - -@cindex automatically buffer-local - A more powerful operation is to mark the variable as -@dfn{automatically buffer-local} by calling -@code{make-variable-buffer-local}. You can think of this as making the -variable local in all buffers, even those yet to be created. More -precisely, the effect is that setting the variable automatically makes -the variable local to the current buffer if it is not already so. All -buffers start out by sharing the default value of the variable as usual, -but setting the variable creates a buffer-local binding for the current -buffer. The new value is stored in the buffer-local binding, leaving -the default binding untouched. This means that the default value cannot -be changed with @code{setq} in any buffer; the only way to change it is -with @code{setq-default}. - - @strong{Warning:} When a variable has buffer-local -bindings in one or more buffers, @code{let} rebinds the binding that's -currently in effect. For instance, if the current buffer has a -buffer-local value, @code{let} temporarily rebinds that. If no -buffer-local bindings are in effect, @code{let} rebinds -the default value. If inside the @code{let} you then change to a -different current buffer in which a different binding is in effect, -you won't see the @code{let} binding any more. And if you exit the -@code{let} while still in the other buffer, you won't see the -unbinding occur (though it will occur properly). Here is an example -to illustrate: - -@example -@group -(setq foo 'g) -(set-buffer "a") -(make-local-variable 'foo) -@end group -(setq foo 'a) -(let ((foo 'temp)) - ;; foo @result{} 'temp ; @r{let binding in buffer @samp{a}} - (set-buffer "b") - ;; foo @result{} 'g ; @r{the global value since foo is not local in @samp{b}} - @var{body}@dots{}) -@group -foo @result{} 'g ; @r{exiting restored the local value in buffer @samp{a},} - ; @r{but we don't see that in buffer @samp{b}} -@end group -@group -(set-buffer "a") ; @r{verify the local value was restored} -foo @result{} 'a -@end group -@end example - -@noindent -Note that references to @code{foo} in @var{body} access the -buffer-local binding of buffer @samp{b}. - - When a file specifies local variable values, these become buffer-local -values when you visit the file. @xref{File Variables,,, emacs, The -GNU Emacs Manual}. - - A buffer-local variable cannot be made terminal-local -(@pxref{Multiple Terminals}). - -@node Creating Buffer-Local -@subsection Creating and Deleting Buffer-Local Bindings - -@deffn Command make-local-variable variable -This function creates a buffer-local binding in the current buffer for -@var{variable} (a symbol). Other buffers are not affected. The value -returned is @var{variable}. - -The buffer-local value of @var{variable} starts out as the same value -@var{variable} previously had. If @var{variable} was void, it remains -void. - -@example -@group -;; @r{In buffer @samp{b1}:} -(setq foo 5) ; @r{Affects all buffers.} - @result{} 5 -@end group -@group -(make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.} - @result{} foo -@end group -@group -foo ; @r{That did not change} - @result{} 5 ; @r{the value.} -@end group -@group -(setq foo 6) ; @r{Change the value} - @result{} 6 ; @r{in @samp{b1}.} -@end group -@group -foo - @result{} 6 -@end group - -@group -;; @r{In buffer @samp{b2}, the value hasn't changed.} -(with-current-buffer "b2" - foo) - @result{} 5 -@end group -@end example - -Making a variable buffer-local within a @code{let}-binding for that -variable does not work reliably, unless the buffer in which you do this -is not current either on entry to or exit from the @code{let}. This is -because @code{let} does not distinguish between different kinds of -bindings; it knows only which variable the binding was made for. - -If the variable is terminal-local (@pxref{Multiple Terminals}), this -function signals an error. Such variables cannot have buffer-local -bindings as well. - -@strong{Warning:} do not use @code{make-local-variable} for a hook -variable. The hook variables are automatically made buffer-local as -needed if you use the @var{local} argument to @code{add-hook} or -@code{remove-hook}. -@end deffn - -@deffn Command make-variable-buffer-local variable -This function marks @var{variable} (a symbol) automatically -buffer-local, so that any subsequent attempt to set it will make it -local to the current buffer at the time. Unlike -@code{make-local-variable}, with which it is often confused, this -cannot be undone, and affects the behavior of the variable in all -buffers. - -A peculiar wrinkle of this feature is that binding the variable (with -@code{let} or other binding constructs) does not create a buffer-local -binding for it. Only setting the variable (with @code{set} or -@code{setq}), while the variable does not have a @code{let}-style -binding that was made in the current buffer, does so. - -If @var{variable} does not have a default value, then calling this -command will give it a default value of @code{nil}. If @var{variable} -already has a default value, that value remains unchanged. -Subsequently calling @code{makunbound} on @var{variable} will result -in a void buffer-local value and leave the default value unaffected. - -The value returned is @var{variable}. - -@strong{Warning:} Don't assume that you should use -@code{make-variable-buffer-local} for user-option variables, simply -because users @emph{might} want to customize them differently in -different buffers. Users can make any variable local, when they wish -to. It is better to leave the choice to them. - -The time to use @code{make-variable-buffer-local} is when it is crucial -that no two buffers ever share the same binding. For example, when a -variable is used for internal purposes in a Lisp program which depends -on having separate values in separate buffers, then using -@code{make-variable-buffer-local} can be the best solution. -@end deffn - -@defun local-variable-p variable &optional buffer -This returns @code{t} if @var{variable} is buffer-local in buffer -@var{buffer} (which defaults to the current buffer); otherwise, -@code{nil}. -@end defun - -@defun local-variable-if-set-p variable &optional buffer -This returns @code{t} if @var{variable} will become buffer-local in -buffer @var{buffer} (which defaults to the current buffer) if it is -set there. -@end defun - -@defun buffer-local-value variable buffer -This function returns the buffer-local binding of @var{variable} (a -symbol) in buffer @var{buffer}. If @var{variable} does not have a -buffer-local binding in buffer @var{buffer}, it returns the default -value (@pxref{Default Value}) of @var{variable} instead. -@end defun - -@defun buffer-local-variables &optional buffer -This function returns a list describing the buffer-local variables in -buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer -is used.) Normally, each list element has the form -@w{@code{(@var{sym} . @var{val})}}, where @var{sym} is a buffer-local -variable (a symbol) and @var{val} is its buffer-local value. But when -a variable's buffer-local binding in @var{buffer} is void, its list -element is just @var{sym}. - -@example -@group -(make-local-variable 'foobar) -(makunbound 'foobar) -(make-local-variable 'bind-me) -(setq bind-me 69) -@end group -(setq lcl (buffer-local-variables)) - ;; @r{First, built-in variables local in all buffers:} -@result{} ((mark-active . nil) - (buffer-undo-list . nil) - (mode-name . "Fundamental") - @dots{} -@group - ;; @r{Next, non-built-in buffer-local variables.} - ;; @r{This one is buffer-local and void:} - foobar - ;; @r{This one is buffer-local and nonvoid:} - (bind-me . 69)) -@end group -@end example - -Note that storing new values into the @sc{cdr}s of cons cells in this -list does @emph{not} change the buffer-local values of the variables. -@end defun - -@deffn Command kill-local-variable variable -This function deletes the buffer-local binding (if any) for -@var{variable} (a symbol) in the current buffer. As a result, the -default binding of @var{variable} becomes visible in this buffer. This -typically results in a change in the value of @var{variable}, since the -default value is usually different from the buffer-local value just -eliminated. - -If you kill the buffer-local binding of a variable that automatically -becomes buffer-local when set, this makes the default value visible in -the current buffer. However, if you set the variable again, that will -once again create a buffer-local binding for it. - -@code{kill-local-variable} returns @var{variable}. - -This function is a command because it is sometimes useful to kill one -buffer-local variable interactively, just as it is useful to create -buffer-local variables interactively. -@end deffn - -@defun kill-all-local-variables -This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as ``permanent'' and local -hook functions that have a non-@code{nil} @code{permanent-local-hook} -property (@pxref{Setting Hooks}). As a result, the buffer will see -the default values of most variables. - -This function also resets certain other information pertaining to the -buffer: it sets the local keymap to @code{nil}, the syntax table to the -value of @code{(standard-syntax-table)}, the case table to -@code{(standard-case-table)}, and the abbrev table to the value of -@code{fundamental-mode-abbrev-table}. - -The very first thing this function does is run the normal hook -@code{change-major-mode-hook} (see below). - -Every major mode command begins by calling this function, which has the -effect of switching to Fundamental mode and erasing most of the effects -of the previous major mode. To ensure that this does its job, the -variables that major modes set should not be marked permanent. - -@code{kill-all-local-variables} returns @code{nil}. -@end defun - -@defvar change-major-mode-hook -The function @code{kill-all-local-variables} runs this normal hook -before it does anything else. This gives major modes a way to arrange -for something special to be done if the user switches to a different -major mode. It is also useful for buffer-specific minor modes -that should be forgotten if the user changes the major mode. - -For best results, make this variable buffer-local, so that it will -disappear after doing its job and will not interfere with the -subsequent major mode. @xref{Hooks}. -@end defvar - -@c Emacs 19 feature -@cindex permanent local variable -A buffer-local variable is @dfn{permanent} if the variable name (a -symbol) has a @code{permanent-local} property that is non-@code{nil}. -Such variables are unaffected by @code{kill-all-local-variables}, and -their local bindings are therefore not cleared by changing major modes. -Permanent locals are appropriate for data pertaining to where the file -came from or how to save it, rather than with how to edit the contents. - -@node Default Value -@subsection The Default Value of a Buffer-Local Variable -@cindex default value - - The global value of a variable with buffer-local bindings is also -called the @dfn{default} value, because it is the value that is in -effect whenever neither the current buffer nor the selected frame has -its own binding for the variable. - - The functions @code{default-value} and @code{setq-default} access and -change a variable's default value regardless of whether the current -buffer has a buffer-local binding. For example, you could use -@code{setq-default} to change the default setting of -@code{paragraph-start} for most buffers; and this would work even when -you are in a C or Lisp mode buffer that has a buffer-local value for -this variable. - -@c Emacs 19 feature - The special forms @code{defvar} and @code{defconst} also set the -default value (if they set the variable at all), rather than any -buffer-local value. - -@defun default-value symbol -This function returns @var{symbol}'s default value. This is the value -that is seen in buffers and frames that do not have their own values for -this variable. If @var{symbol} is not buffer-local, this is equivalent -to @code{symbol-value} (@pxref{Accessing Variables}). -@end defun - -@c Emacs 19 feature -@defun default-boundp symbol -The function @code{default-boundp} tells you whether @var{symbol}'s -default value is nonvoid. If @code{(default-boundp 'foo)} returns -@code{nil}, then @code{(default-value 'foo)} would get an error. - -@code{default-boundp} is to @code{default-value} as @code{boundp} is to -@code{symbol-value}. -@end defun - -@defspec setq-default [symbol form]@dots{} -This special form gives each @var{symbol} a new default value, which is -the result of evaluating the corresponding @var{form}. It does not -evaluate @var{symbol}, but does evaluate @var{form}. The value of the -@code{setq-default} form is the value of the last @var{form}. - -If a @var{symbol} is not buffer-local for the current buffer, and is not -marked automatically buffer-local, @code{setq-default} has the same -effect as @code{setq}. If @var{symbol} is buffer-local for the current -buffer, then this changes the value that other buffers will see (as long -as they don't have a buffer-local value), but not the value that the -current buffer sees. - -@example -@group -;; @r{In buffer @samp{foo}:} -(make-local-variable 'buffer-local) - @result{} buffer-local -@end group -@group -(setq buffer-local 'value-in-foo) - @result{} value-in-foo -@end group -@group -(setq-default buffer-local 'new-default) - @result{} new-default -@end group -@group -buffer-local - @result{} value-in-foo -@end group -@group -(default-value 'buffer-local) - @result{} new-default -@end group - -@group -;; @r{In (the new) buffer @samp{bar}:} -buffer-local - @result{} new-default -@end group -@group -(default-value 'buffer-local) - @result{} new-default -@end group -@group -(setq buffer-local 'another-default) - @result{} another-default -@end group -@group -(default-value 'buffer-local) - @result{} another-default -@end group - -@group -;; @r{Back in buffer @samp{foo}:} -buffer-local - @result{} value-in-foo -(default-value 'buffer-local) - @result{} another-default -@end group -@end example -@end defspec - -@defun set-default symbol value -This function is like @code{setq-default}, except that @var{symbol} is -an ordinary evaluated argument. - -@example -@group -(set-default (car '(a b c)) 23) - @result{} 23 -@end group -@group -(default-value 'a) - @result{} 23 -@end group -@end example -@end defun - -@node File Local Variables -@section File Local Variables -@cindex file local variables - - A file can specify local variable values; Emacs uses these to create -buffer-local bindings for those variables in the buffer visiting that -file. @xref{File variables, , Local Variables in Files, emacs, The -GNU Emacs Manual}, for basic information about file-local variables. -This section describes the functions and variables that affect how -file-local variables are processed. - - If a file-local variable could specify an arbitrary function or Lisp -expression that would be called later, visiting a file could take over -your Emacs. Emacs protects against this by automatically setting only -those file-local variables whose specified values are known to be -safe. Other file-local variables are set only if the user agrees. - - For additional safety, @code{read-circle} is temporarily bound to -@code{nil} when Emacs reads file-local variables (@pxref{Input -Functions}). This prevents the Lisp reader from recognizing circular -and shared Lisp structures (@pxref{Circular Objects}). - -@defopt enable-local-variables -This variable controls whether to process file-local variables. -The possible values are: - -@table @asis -@item @code{t} (the default) -Set the safe variables, and query (once) about any unsafe variables. -@item @code{:safe} -Set only the safe variables and do not query. -@item @code{:all} -Set all the variables and do not query. -@item @code{nil} -Don't set any variables. -@item anything else -Query (once) about all the variables. -@end table -@end defopt - -@defvar inhibit-local-variables-regexps -This is a list of regular expressions. If a file has a name -matching an element of this list, then it is not scanned for -any form of file-local variable. For examples of why you might want -to use this, @pxref{Auto Major Mode}. -@end defvar - -@defun hack-local-variables &optional mode-only -This function parses, and binds or evaluates as appropriate, any local -variables specified by the contents of the current buffer. The variable -@code{enable-local-variables} has its effect here. However, this -function does not look for the @samp{mode:} local variable in the -@w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking -@code{enable-local-variables} into account (@pxref{Auto Major Mode}). - -This function works by walking the alist stored in -@code{file-local-variables-alist} and applying each local variable in -turn. It calls @code{before-hack-local-variables-hook} and -@code{hack-local-variables-hook} before and after applying the -variables, respectively. It only calls the before-hook if the alist -is non-@code{nil}; it always calls the other hook. This -function ignores a @samp{mode} element if it specifies the same major -mode as the buffer already has. - -If the optional argument @var{mode-only} is non-@code{nil}, then all -this function does is return a symbol specifying the major mode, -if the @w{@samp{-*-}} line or the local variables list specifies one, -and @code{nil} otherwise. It does not set the mode nor any other -file-local variable. -@end defun - -@defvar file-local-variables-alist -This buffer-local variable holds the alist of file-local variable -settings. Each element of the alist is of the form -@w{@code{(@var{var} . @var{value})}}, where @var{var} is a symbol of -the local variable and @var{value} is its value. When Emacs visits a -file, it first collects all the file-local variables into this alist, -and then the @code{hack-local-variables} function applies them one by -one. -@end defvar - -@defvar before-hack-local-variables-hook -Emacs calls this hook immediately before applying file-local variables -stored in @code{file-local-variables-alist}. -@end defvar - -@defvar hack-local-variables-hook -Emacs calls this hook immediately after it finishes applying -file-local variables stored in @code{file-local-variables-alist}. -@end defvar - -@cindex safe local variable - You can specify safe values for a variable with a -@code{safe-local-variable} property. The property has to be a -function of one argument; any value is safe if the function returns -non-@code{nil} given that value. Many commonly-encountered file -variables have @code{safe-local-variable} properties; these include -@code{fill-column}, @code{fill-prefix}, and @code{indent-tabs-mode}. -For boolean-valued variables that are safe, use @code{booleanp} as the -property value. Lambda expressions should be quoted so that -@code{describe-variable} can display the predicate. - - When defining a user option using @code{defcustom}, you can set its -@code{safe-local-variable} property by adding the arguments -@code{:safe @var{function}} to @code{defcustom} (@pxref{Variable -Definitions}). - -@defopt safe-local-variable-values -This variable provides another way to mark some variable values as -safe. It is a list of cons cells @code{(@var{var} . @var{val})}, -where @var{var} is a variable name and @var{val} is a value which is -safe for that variable. - -When Emacs asks the user whether or not to obey a set of file-local -variable specifications, the user can choose to mark them as safe. -Doing so adds those variable/value pairs to -@code{safe-local-variable-values}, and saves it to the user's custom -file. -@end defopt - -@defun safe-local-variable-p sym val -This function returns non-@code{nil} if it is safe to give @var{sym} -the value @var{val}, based on the above criteria. -@end defun - -@c @cindex risky local variable Duplicates risky-local-variable - Some variables are considered @dfn{risky}. If a variable is risky, -it is never entered automatically into -@code{safe-local-variable-values}; Emacs always queries before setting -a risky variable, unless the user explicitly allows a value by -customizing @code{safe-local-variable-values} directly. - - Any variable whose name has a non-@code{nil} -@code{risky-local-variable} property is considered risky. When you -define a user option using @code{defcustom}, you can set its -@code{risky-local-variable} property by adding the arguments -@code{:risky @var{value}} to @code{defcustom} (@pxref{Variable -Definitions}). In addition, any variable whose name ends in any of -@samp{-command}, @samp{-frame-alist}, @samp{-function}, -@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form}, -@samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist}, -@samp{-program}, or @samp{-predicate} is automatically considered -risky. The variables @samp{font-lock-keywords}, -@samp{font-lock-keywords} followed by a digit, and -@samp{font-lock-syntactic-keywords} are also considered risky. - -@defun risky-local-variable-p sym -This function returns non-@code{nil} if @var{sym} is a risky variable, -based on the above criteria. -@end defun - -@defvar ignored-local-variables -This variable holds a list of variables that should not be given local -values by files. Any value specified for one of these variables is -completely ignored. -@end defvar - - The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs -normally asks for confirmation before handling it. - -@defopt enable-local-eval -This variable controls processing of @samp{Eval:} in @samp{-*-} lines -or local variables -lists in files being visited. A value of @code{t} means process them -unconditionally; @code{nil} means ignore them; anything else means ask -the user what to do for each file. The default value is @code{maybe}. -@end defopt - -@defopt safe-local-eval-forms -This variable holds a list of expressions that are safe to -evaluate when found in the @samp{Eval:} ``variable'' in a file -local variables list. -@end defopt - - If the expression is a function call and the function has a -@code{safe-local-eval-function} property, the property value -determines whether the expression is safe to evaluate. The property -value can be a predicate to call to test the expression, a list of -such predicates (it's safe if any predicate succeeds), or @code{t} -(always safe provided the arguments are constant). - - Text properties are also potential loopholes, since their values -could include functions to call. So Emacs discards all text -properties from string values specified for file-local variables. - -@node Directory Local Variables -@section Directory Local Variables -@cindex directory local variables - - A directory can specify local variable values common to all files in -that directory; Emacs uses these to create buffer-local bindings for -those variables in buffers visiting any file in that directory. This -is useful when the files in the directory belong to some @dfn{project} -and therefore share the same local variables. - - There are two different methods for specifying directory local -variables: by putting them in a special file, or by defining a -@dfn{project class} for that directory. - -@defvr Constant dir-locals-file -This constant is the name of the file where Emacs expects to find the -directory-local variables. The name of the file is -@file{.dir-locals.el}@footnote{ -The MS-DOS version of Emacs uses @file{_dir-locals.el} instead, due to -limitations of the DOS filesystems. -}. A file by that name in a directory causes Emacs to apply its -settings to any file in that directory or any of its subdirectories -(optionally, you can exclude subdirectories; see below). -If some of the subdirectories have their own @file{.dir-locals.el} -files, Emacs uses the settings from the deepest file it finds starting -from the file's directory and moving up the directory tree. The file -specifies local variables as a specially formatted list; see -@ref{Directory Variables, , Per-directory Local Variables, emacs, The -GNU Emacs Manual}, for more details. -@end defvr - -@defun hack-dir-local-variables -This function reads the @code{.dir-locals.el} file and stores the -directory-local variables in @code{file-local-variables-alist} that is -local to the buffer visiting any file in the directory, without -applying them. It also stores the directory-local settings in -@code{dir-locals-class-alist}, where it defines a special class for -the directory in which @file{.dir-locals.el} file was found. This -function works by calling @code{dir-locals-set-class-variables} and -@code{dir-locals-set-directory-class}, described below. -@end defun - -@defun hack-dir-local-variables-non-file-buffer -This function looks for directory-local variables, and immediately -applies them in the current buffer. It is intended to be called in -the mode commands for non-file buffers, such as Dired buffers, to let -them obey directory-local variable settings. For non-file buffers, -Emacs looks for directory-local variables in @code{default-directory} -and its parent directories. -@end defun - -@defun dir-locals-set-class-variables class variables -This function defines a set of variable settings for the named -@var{class}, which is a symbol. You can later assign the class to one -or more directories, and Emacs will apply those variable settings to -all files in those directories. The list in @var{variables} can be of -one of the two forms: @code{(@var{major-mode} . @var{alist})} or -@code{(@var{directory} . @var{list})}. With the first form, if the -file's buffer turns on a mode that is derived from @var{major-mode}, -then the all the variables in the associated @var{alist} are applied; -@var{alist} should be of the form @code{(@var{name} . @var{value})}. -A special value @code{nil} for @var{major-mode} means the settings are -applicable to any mode. In @var{alist}, you can use a special -@var{name}: @code{subdirs}. If the associated value is -@code{nil}, the alist is only applied to files in the relevant -directory, not to those in any subdirectories. - -With the second form of @var{variables}, if @var{directory} is the -initial substring of the file's directory, then @var{list} is applied -recursively by following the above rules; @var{list} should be of one -of the two forms accepted by this function in @var{variables}. -@end defun - -@defun dir-locals-set-directory-class directory class &optional mtime -This function assigns @var{class} to all the files in @code{directory} -and its subdirectories. Thereafter, all the variable settings -specified for @var{class} will be applied to any visited file in -@var{directory} and its children. @var{class} must have been already -defined by @code{dir-locals-set-class-variables}. - -Emacs uses this function internally when it loads directory variables -from a @code{.dir-locals.el} file. In that case, the optional -argument @var{mtime} holds the file modification time (as returned by -@code{file-attributes}). Emacs uses this time to check stored -local variables are still valid. If you are assigning a class -directly, not via a file, this argument should be @code{nil}. -@end defun - -@defvar dir-locals-class-alist -This alist holds the class symbols and the associated variable -settings. It is updated by @code{dir-locals-set-class-variables}. -@end defvar - -@defvar dir-locals-directory-cache -This alist holds directory names, their assigned class names, and -modification times of the associated directory local variables file -(if there is one). The function @code{dir-locals-set-directory-class} -updates this list. -@end defvar - -@node Variable Aliases -@section Variable Aliases -@cindex variable aliases - - It is sometimes useful to make two variables synonyms, so that both -variables always have the same value, and changing either one also -changes the other. Whenever you change the name of a -variable---either because you realize its old name was not well -chosen, or because its meaning has partly changed---it can be useful -to keep the old name as an @emph{alias} of the new one for -compatibility. You can do this with @code{defvaralias}. - -@defun defvaralias new-alias base-variable &optional docstring -This function defines the symbol @var{new-alias} as a variable alias -for symbol @var{base-variable}. This means that retrieving the value -of @var{new-alias} returns the value of @var{base-variable}, and -changing the value of @var{new-alias} changes the value of -@var{base-variable}. The two aliased variable names always share the -same value and the same bindings. - -If the @var{docstring} argument is non-@code{nil}, it specifies the -documentation for @var{new-alias}; otherwise, the alias gets the same -documentation as @var{base-variable} has, if any, unless -@var{base-variable} is itself an alias, in which case @var{new-alias} gets -the documentation of the variable at the end of the chain of aliases. - -This function returns @var{base-variable}. -@end defun - - Variable aliases are convenient for replacing an old name for a -variable with a new name. @code{make-obsolete-variable} declares that -the old name is obsolete and therefore that it may be removed at some -stage in the future. - -@defun make-obsolete-variable obsolete-name current-name when &optional access-type -This function makes the byte compiler warn that the variable -@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, -it is the variable's new name; then the warning message says to use -@var{current-name} instead of @var{obsolete-name}. If -@var{current-name} is a string, this is the message and there is no -replacement variable. @var{when} should be a string indicating when -the variable was first made obsolete (usually a version number -string). - -The optional argument @var{access-type}, if non-@code{nil}, should -should specify the kind of access that will trigger obsolescence -warnings; it can be either @code{get} or @code{set}. -@end defun - - You can make two variables synonyms and declare one obsolete at the -same time using the macro @code{define-obsolete-variable-alias}. - -@defmac define-obsolete-variable-alias obsolete-name current-name &optional when docstring -This macro marks the variable @var{obsolete-name} as obsolete and also -makes it an alias for the variable @var{current-name}. It is -equivalent to the following: - -@example -(defvaralias @var{obsolete-name} @var{current-name} @var{docstring}) -(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when}) -@end example -@end defmac - -@defun indirect-variable variable -This function returns the variable at the end of the chain of aliases -of @var{variable}. If @var{variable} is not a symbol, or if @var{variable} is -not defined as an alias, the function returns @var{variable}. - -This function signals a @code{cyclic-variable-indirection} error if -there is a loop in the chain of symbols. -@end defun - -@example -(defvaralias 'foo 'bar) -(indirect-variable 'foo) - @result{} bar -(indirect-variable 'bar) - @result{} bar -(setq bar 2) -bar - @result{} 2 -@group -foo - @result{} 2 -@end group -(setq foo 0) -bar - @result{} 0 -foo - @result{} 0 -@end example - -@node Variables with Restricted Values -@section Variables with Restricted Values - - Ordinary Lisp variables can be assigned any value that is a valid -Lisp object. However, certain Lisp variables are not defined in Lisp, -but in C. Most of these variables are defined in the C code using -@code{DEFVAR_LISP}. Like variables defined in Lisp, these can take on -any value. However, some variables are defined using -@code{DEFVAR_INT} or @code{DEFVAR_BOOL}. @xref{Defining Lisp -variables in C,, Writing Emacs Primitives}, in particular the -description of functions of the type @code{syms_of_@var{filename}}, -for a brief discussion of the C implementation. - - Variables of type @code{DEFVAR_BOOL} can only take on the values -@code{nil} or @code{t}. Attempting to assign them any other value -will set them to @code{t}: - -@example -(let ((display-hourglass 5)) - display-hourglass) - @result{} t -@end example - -@defvar byte-boolean-vars -This variable holds a list of all variables of type @code{DEFVAR_BOOL}. -@end defvar - - Variables of type @code{DEFVAR_INT} can only take on integer values. -Attempting to assign them any other value will result in an error: - -@example -(setq undo-limit 1000.0) -@error{} Wrong type argument: integerp, 1000.0 -@end example diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi deleted file mode 100644 index 2687cd57d5a..00000000000 --- a/doc/lispref/vol1.texi +++ /dev/null @@ -1,1568 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This file is used for printing the GNU Emacs Lisp Reference Manual -@c in two volumes. It is a modified version of elisp.texi. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c %**start of header -@setfilename elisp -@settitle GNU Emacs Lisp Reference Manual: Volume 1 -@c %**end of header - -@c See two-volume-cross-refs.txt. -@tex -\message{Formatting for two volume edition...Volume 1...} -% -% Read special toc file, set up in two-volume.make. -\gdef\tocreadfilename{elisp1-toc-ready.toc} -% -% Don't make outlines, they're not needed and \readdatafile can't pay -% attention to the special definition above. -\global\let\pdfmakeoutlines=\relax -% -% Start volume 1 chapter numbering at 1; this must be listed as chapno0. -\global\chapno=0 -@end tex - -@c Version of the manual and of Emacs. -@set VERSION 3.1 -@include emacsver.texi -@set DATE May 2012 - -@dircategory Emacs -@direntry -* Elisp: (elisp). The Emacs Lisp Reference Manual. -@end direntry - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. the manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@set smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@c Combine indices. -@synindex cp fn -@syncodeindex vr fn -@syncodeindex ky fn -@syncodeindex pg fn -@c We use the "type index" to index new functions and variables. -@c @syncodeindex tp fn - -@copying -This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@* -corresponding to Emacs version @value{EMACSVER}. - -Copyright @copyright{} 1990-1996, 1998-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License,'' with the -Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the -section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@titlepage -@title GNU Emacs Lisp Reference Manual -@subtitle Volume 1 -@subtitle For Emacs Version @value{EMACSVER} -@subtitle Revision @value{VERSION}, @value{DATE} - -@author by Bil Lewis, Dan LaLiberte, Richard Stallman, -@author the GNU Manual Group, et al. -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 - -Published by the Free Software Foundation @* -51 Franklin St, Fifth Floor @* -Boston, MA 02110-1301 @* -USA @* -ISBN 1-882114-74-4 - -@sp 2 -Cover art by Etienne Suvasa. -@end titlepage - - -@c Print the tables of contents -@summarycontents -@contents - - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top Emacs Lisp - -This Info file contains edition @value{VERSION} of the GNU Emacs Lisp -Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}. -@end ifnottex - -@menu -* Introduction:: Introduction and conventions used. - -* Lisp Data Types:: Data types of objects in Emacs Lisp. -* Numbers:: Numbers and arithmetic functions. -* Strings and Characters:: Strings, and functions that work on them. -* Lists:: Lists, cons cells, and related functions. -* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. - Certain functions act on any kind of sequence. - The description of vectors is here as well. -* Hash Tables:: Very fast lookup-tables. -* Symbols:: Symbols represent names, uniquely. - -* Evaluation:: How Lisp expressions are evaluated. -* Control Structures:: Conditionals, loops, nonlocal exits. -* Variables:: Using symbols in programs to stand for values. -* Functions:: A function is a Lisp program - that can be invoked from other functions. -* Macros:: Macros are a way to extend the Lisp language. -* Customization:: Making variables and faces customizable. - -* Loading:: Reading files of Lisp code into Lisp. -* Byte Compilation:: Compilation makes programs run faster. -* Advising Functions:: Adding to the definition of a function. -* Debugging:: Tools and tips for debugging Lisp programs. - -* Read and Print:: Converting Lisp objects to text and back. -* Minibuffers:: Using the minibuffer to read input. -* Command Loop:: How the editor command loop works, - and how you can call its subroutines. -* Keymaps:: Defining the bindings from keys to commands. -* Modes:: Defining major and minor modes. -* Documentation:: Writing and using documentation strings. - -* Files:: Accessing files. -* Backups and Auto-Saving:: Controlling how backups and auto-save - files are made. -* Buffers:: Creating and using buffer objects. -* Windows:: Manipulating windows and displaying buffers. -* Frames:: Making multiple system-level windows. -* Positions:: Buffer positions and motion functions. -* Markers:: Markers represent positions and update - automatically when the text is changed. - -* Text:: Examining and changing text in buffers. -* Non-ASCII Characters:: Non-ASCII text in buffers and strings. -* Searching and Matching:: Searching buffers for strings or regexps. -* Syntax Tables:: The syntax table controls word and list parsing. -* Abbrevs:: How Abbrev mode works, and its data structures. - -* Processes:: Running and communicating with subprocesses. -* Display:: Features for controlling the screen display. -* System Interface:: Getting the user id, system type, environment - variables, and other such things. - -* Packaging:: Preparing Lisp code for distribution. - -Appendices - -* Antinews:: Info for users downgrading to Emacs 23. -* GNU Free Documentation License:: The license for this documentation. -* GPL:: Conditions for copying and changing GNU Emacs. -* Tips:: Advice and coding conventions for Emacs Lisp. -* GNU Emacs Internals:: Building and dumping Emacs; - internal data structures. -* Standard Errors:: List of some standard error symbols. -* Standard Keymaps:: List of some standard keymaps. -* Standard Hooks:: List of some standard hook variables. - -* Index:: Index including concepts, functions, variables, - and other terms. - -@ignore -* New Symbols:: New functions and variables in Emacs @value{EMACSVER}. -@end ignore - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. - -@detailmenu - --- The Detailed Node Listing --- - --------------------------------- - -Here are other nodes that are subnodes of those already listed, -mentioned here so you can get to them in one step: - -Introduction - -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Version Info:: Which Emacs version is running? -* Acknowledgements:: The authors, editors, and sponsors of this manual. - -Conventions - -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use when examples print text. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. - -Format of Descriptions - -* A Sample Function Description:: A description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, @code{electric-future-map}. - -Lisp Data Types - -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Circular Objects:: Read syntax for circular structure. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. - -Programming Types - -* Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Symbol Type:: A multi-use object that refers to a function, - variable, or property list, and has a unique identity. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Char-Table Type:: One-dimensional sparse arrays indexed by characters. -* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. -* Hash Table Type:: Super-fast lookup tables. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. - -Character Type - -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. - -Cons Cell and List Types - -* Box Diagrams:: Drawing pictures of lists. -* Dotted Pair Notation:: A general syntax for cons cells. -* Association List Type:: A specially constructed list. - -String Type - -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. - -Editing Types - -* Buffer Type:: The basic object of editing. -* Marker Type:: A position in a buffer. -* Window Type:: Buffers are displayed in windows. -* Frame Type:: Windows subdivide frames. -* Terminal Type:: A terminal device displays frames. -* Window Configuration Type:: Recording the way a frame is subdivided. -* Frame Configuration Type:: Recording the status of all frames. -* Process Type:: A subprocess of Emacs running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Overlay Type:: How an overlay is represented. -* Font Type:: Fonts for displaying text. - -Numbers - -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating point numbers. -* Bitwise Operations:: Logical and, or, not, shifting. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. - -Strings and Characters - -* String Basics:: Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Modifying Strings:: Altering the contents of an existing string. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting to and from characters and strings. -* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. -* Case Conversion:: Case conversion functions. -* Case Tables:: Customizing case conversion. - -Lists - -* Cons Cells:: How lists are made out of cons cells. -* List-related Predicates:: Is this object a list? Comparing two lists. -* List Elements:: Extracting the pieces of a list. -* Building Lists:: Creating list structure. -* List Variables:: Modifying lists stored in variables. -* Modifying Lists:: Storing new pieces into an existing list. -* Sets And Lists:: A list can represent a finite mathematical set. -* Association Lists:: A list can represent a finite relation or mapping. -* Rings:: Managing a fixed-size ring of objects. - -Modifying Existing List Structure - -* Setcar:: Replacing an element in a list. -* Setcdr:: Replacing part of the list backbone. - This can be used to remove or add elements. -* Rearrangement:: Reordering the elements in a list; combining lists. - -Sequences, Arrays, and Vectors - -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Special characteristics of Emacs Lisp vectors. -* Vector Functions:: Functions specifically for vectors. -* Char-Tables:: How to work with char-tables. -* Bool-Vectors:: How to work with bool-vectors. - -Hash Tables - -* Creating Hash:: Functions to create hash tables. -* Hash Access:: Reading and writing the hash table contents. -* Defining Hash:: Defining new comparison methods. -* Other Hash:: Miscellaneous. - -Symbols - -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list - for recording miscellaneous information. - -Property Lists - -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. - -Evaluation - -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in - the program). -* Backquote:: Easier construction of list structure. -* Eval:: How to invoke the Lisp interpreter explicitly. - -Kinds of Forms - -* Self-Evaluating Forms:: Forms that evaluate to themselves. -* Symbol Forms:: Symbols evaluate as variables. -* Classifying Lists:: How to distinguish various sorts of list forms. -* Function Indirection:: When a symbol appears as the car of a list, - we find the real function via the symbol. -* Function Forms:: Forms that call functions. -* Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, - most of them extremely important. -* Autoloading:: Functions set up to load files - containing their real definitions. - -Control Structures - -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. - -Nonlocal Exits - -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an - error happens. - -Errors - -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. - -Variables - -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Tips for Defining:: Things you should think about when you - define a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. -* File Local Variables:: Handling local variable lists in files. -* Directory Local Variables:: Local variables common to all files in a - directory. -* Frame-Local Variables:: Frame-local bindings for variables. -* Variable Aliases:: Variables that are aliases for other variables. -* Variables with Restricted Values:: Non-constant variables whose value can - @emph{not} be an arbitrary Lisp object. - -Scoping Rules for Variable Bindings - -* Scope:: Scope means where in the program a value - is visible. Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and - avoid problems. - -Buffer-Local Variables - -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own buffer-local values. - -Functions - -* What Is a Function:: Lisp functions vs. primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Closures:: Functions that enclose a lexical environment. -* Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Defining functions that the compiler - will expand inline. -* Declaring Functions:: Telling the compiler that a function is defined. -* Function Safety:: Determining whether a function is safe to call. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how - functions work. - -Lambda Expressions - -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. - -Macros - -* Simple Macro:: A basic example. -* Expansion:: How, when and why macros are expanded. -* Compiling Macros:: How macros are expanded by the compiler. -* Defining Macros:: How to write a macro definition. -* Problems with Macros:: Don't evaluate the macro arguments too many times. - Don't hide the user's variables. -* Indenting Macros:: Specifying how to indent macro calls. - -Common Problems Using Macros - -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. - -Customization Settings - -* Common Keywords:: Common keyword arguments for all kinds of - customization declarations. -* Group Definitions:: Writing customization group definitions. -* Variable Definitions:: Declaring user options. -* Customization Types:: Specifying the type of a user option. -* Applying Customizations:: Functions to apply customization settings. -* Custom Themes:: Writing Custom themes. - -Customization Types - -* Simple Types:: Simple customization types: sexp, integer, number, - string, file, directory, alist. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. - -Loading - -* How Programs Do Loading:: The @code{load} function and others. -* Load Suffixes:: Details about the suffixes that @code{load} tries. -* Library Search:: Finding a library to load. -* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. -* Autoload:: Setting up a function to autoload. -* Repeated Loading:: Precautions about loading a file twice. -* Named Features:: Loading a library if it isn't already loaded. -* Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. -* Hooks for Loading:: Providing code to be run when - particular libraries are loaded. - -Byte Compilation - -* Speed of Byte-Code:: An example of speedup from byte compilation. -* Compilation Functions:: Byte compilation functions. -* Docs and Compilation:: Dynamic loading of documentation strings. -* Dynamic Loading:: Dynamic loading of individual functions. -* Eval During Compile:: Code to be evaluated when you compile. -* Compiler Errors:: Handling compiler error messages. -* Byte-Code Objects:: The data type used for byte-compiled functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. - -Advising Emacs Lisp Functions - -* Simple Advice:: A simple example to explain the basics of advice. -* Defining Advice:: Detailed description of @code{defadvice}. -* Around-Advice:: Wrapping advice around a function's definition. -* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. -* Activation of Advice:: Advice doesn't do anything until you activate it. -* Enabling Advice:: You can enable or disable each piece of advice. -* Preactivation:: Preactivation is a way of speeding up the - loading of compiled advice. -* Argument Access in Advice:: How advice can access the function's arguments. -* Combined Definition:: How advice is implemented. - -Debugging Lisp Programs - -* Debugger:: A debugger for the Emacs Lisp evaluator. -* Edebug:: A source-level Emacs Lisp debugger. -* Syntax Errors:: How to find syntax errors. -* Test Coverage:: Ensuring you have tested all branches in your code. - -The Lisp Debugger - -* Error Debugging:: Entering the debugger when an error happens. -* Infinite Loops:: Stopping and debugging a program that doesn't exit. -* Function Debugging:: Entering it when a certain function is called. -* Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. -* Debugger Commands:: Commands used while in the debugger. -* Invoking the Debugger:: How to call the function @code{debug}. -* Internals of Debugger:: Subroutines of the debugger, and global variables. - -Edebug - -* Using Edebug:: Introduction to use of Edebug. -* Instrumenting:: You must instrument your code - in order to debug it with Edebug. -* Edebug Execution Modes:: Execution modes, stopping more or less often. -* Jumping:: Commands to jump to a specified place. -* Edebug Misc:: Miscellaneous commands. -* Breaks:: Setting breakpoints to make the program stop. -* Trapping Errors:: Trapping errors with Edebug. -* Edebug Views:: Views inside and outside of Edebug. -* Edebug Eval:: Evaluating expressions within Edebug. -* Eval List:: Expressions whose values are displayed - each time you enter Edebug. -* Printing in Edebug:: Customization of printing. -* Trace Buffer:: How to produce trace output in a buffer. -* Coverage Testing:: How to test evaluation coverage. -* The Outside Context:: Data that Edebug saves and restores. -* Edebug and Macros:: Specifying how to handle macro calls. -* Edebug Options:: Option variables for customizing Edebug. - -Breaks - -* Breakpoints:: Breakpoints at stop points. -* Global Break Condition:: Breaking on an event. -* Source Breakpoints:: Embedding breakpoints in source code. - -The Outside Context - -* Checking Whether to Stop::When Edebug decides what to do. -* Edebug Display Update:: When Edebug updates the display. -* Edebug Recursive Edit:: When Edebug stops execution. - -Edebug and Macros - -* Instrumenting Macro Calls::The basic problem. -* Specification List:: How to specify complex patterns of evaluation. -* Backtracking:: What Edebug does when matching fails. -* Specification Examples:: To help understand specifications. - -Debugging Invalid Lisp Syntax - -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. - -Reading and Printing Lisp Objects - -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as - input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as - output streams. -* Output Functions:: Functions to print Lisp objects as text. -* Output Variables:: Variables that control what the printing - functions do. - -Minibuffers - -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. -* Initial Input:: Specifying initial contents for the minibuffer. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Reading a Password:: Reading a password from the terminal. -* Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Windows:: Operating on the special minibuffer windows. -* Minibuffer Contents:: How such commands access the minibuffer text. -* Recursive Mini:: Whether recursive entry to minibuffer is allowed. -* Minibuffer Misc:: Various customization hooks and variables. - -Completion - -* Basic Completion:: Low-level functions for completing strings. - (These are too low level to use the minibuffer.) -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer names, variable names, etc.). -* Reading File Names:: Using completion to read file names and - shell commands. -* Completion Variables:: Variables controlling completion behavior. -* Programmed Completion:: Writing your own completion function. -* Completion in Buffers:: Completing text in ordinary buffers. - -Command Loop - -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Distinguish Interactive:: Making a command distinguish interactive calls. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Adjusting Point:: Adjustment of point after a command. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Special Events:: Events processed immediately and individually. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. - -Defining Commands - -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. - -Input Events - -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. - Event types. -* Accessing Mouse:: Functions to extract info from mouse events. -* Accessing Scroll:: Functions to get info from scroll bar events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. - -Reading Input - -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. - -Keymaps - -* Key Sequences:: Key sequences as Lisp objects. -* Keymap Basics:: Basic concepts of keymaps. -* Format of Keymaps:: What a keymap looks like as a Lisp object. -* Creating Keymaps:: Functions to create and copy keymaps. -* Inheritance and Keymaps:: How one keymap can inherit the bindings - of another keymap. -* Prefix Keys:: Defining a key with a keymap as its definition. -* Active Keymaps:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A minor mode can also override them. -* Key Lookup:: Finding a key's binding in one keymap. -* Functions for Key Lookup:: How to request key lookup. -* Changing Key Bindings:: Redefining a key in a keymap. -* Remapping Commands:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* Key Binding Commands:: Interactive interfaces for redefining keys. -* Scanning Keymaps:: Looking through all keymaps, for printing help. -* Menu Keymaps:: Defining a menu as a keymap. - -Menu Keymaps - -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. - -Defining Menus - -* Simple Menu Items:: A simple kind of menu key binding, - limited in capabilities. -* Extended Menu Items:: More powerful menu item definitions - let you specify keywords to enable - various features. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. -* Toolkit Differences:: Not all toolkits provide the same features. - -Major and Minor Modes - -* Hooks:: How to use hooks; how to write code that provides hooks. -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Imenu:: Providing a menu of definitions made in a buffer. -* Font Lock Mode:: How modes can highlight text according to syntax. -* Auto-Indentation:: How to teach Emacs to indent for a major mode. -* Desktop Save Mode:: How modes can have buffer state saved between - Emacs sessions. - -Hooks - -* Running Hooks:: How to run a hook. -* Setting Hooks:: How to put functions on a hook, or remove them. - -Major Modes - -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. -* Derived Modes:: Defining a new major mode based on another major - mode. -* Basic Major Modes:: Modes that other modes are often derived from. -* Mode Hooks:: Hooks run at the end of major mode functions. -* Tabulated List Mode:: Parent mode for buffers containing tabulated data. -* Generic Modes:: Defining a simple major mode that supports - comment syntax and Font Lock mode. -* Example Major Modes:: Text mode and Lisp modes. - -Minor Modes - -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -* Defining Minor Modes:: A convenient facility for defining minor modes. - -Mode Line Format - -* Mode Line Basics:: Basic ideas of mode line control. -* Mode Line Data:: The data structure that controls the mode line. -* Mode Line Top:: The top level variable, mode-line-format. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. -* Properties in Mode:: Using text properties in the mode line. -* Header Lines:: Like a mode line, but at the top. -* Emulating Mode Line:: Formatting text as the mode line would. - -Font Lock Mode - -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. - -Multiline Font Lock Constructs - -* Font Lock Multiline:: Marking multiline chunks with a text property. -* Region to Refontify:: Controlling which region gets refontified - after a buffer change. - -Automatic Indentation of code - -* SMIE:: A simple minded indentation engine. - -Simple Minded Indentation Engine - -* SMIE setup:: SMIE setup and features. -* Operator Precedence Grammars:: A very simple parsing technique. -* SMIE Grammar:: Defining the grammar of a language. -* SMIE Lexer:: Defining tokens. -* SMIE Tricks:: Working around the parser's limitations. -* SMIE Indentation:: Specifying indentation rules. -* SMIE Indentation Helpers:: Helper functions for indentation rules. -* SMIE Indentation Example:: Sample indentation rules. - -Documentation - -* Documentation Basics:: Where doc strings are defined and stored. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. - -Files - -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing Files:: Renaming files, changing permissions, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Special handling for certain file names. -* Format Conversion:: Conversion to and from various file formats. - -Visiting Files - -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. - -Information about Files - -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A symbolic link? -* Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: How large is it? Any other names? Etc. -* Locating Files:: How to find a file in standard places. - -File Names - -* File Name Components:: The directory part of a file name, and the rest. -* Relative File Names:: Some file names are relative to a current directory. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. -* Standard File Names:: If your package uses a fixed file name, - how to handle various operating systems simply. - -File Format Conversion - -* Format Conversion Overview:: @code{insert-file-contents} and @code{write-region}. -* Format Conversion Round-Trip:: Using @code{format-alist}. -* Format Conversion Piecemeal:: Specifying non-paired conversion. - -Backups and Auto-Saving - -* Backup Files:: How backup files are made; how their names - are chosen. -* Auto-Saving:: How auto-save files are made; how their - names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize - what it does. - -Backup Files - -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file - or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. - -Buffers - -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so that primitives will access its contents. -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file - is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - "behind Emacs's back". -* Read Only Buffers:: Modifying text is not allowed in a - read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Indirect Buffers:: An indirect buffer shares text with some - other buffer. -* Swapping Text:: Swapping text between two buffers. -* Buffer Gap:: The gap in the buffer. - -Windows - -* Basic Windows:: Basic information on using windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Switching Buffers:: Higher-level functions for switching to a buffer. -* Choosing Window:: How to choose a window for displaying a buffer. -* Display Action Functions:: Subroutines for @code{display-buffer}. -* Choosing Window Options:: Extra options affecting how buffers are displayed. -* Window History:: Each window remembers the buffers displayed in it. -* Dedicated Windows:: How to avoid displaying another buffer in - a specific window. -* Window Point:: Each window has its own location of point. -* Window Start and End:: Buffer positions indicating which text is - on-screen in a window. -* Textual Scrolling:: Moving text up and down through the window. -* Vertical Scrolling:: Moving the contents up and down on the window. -* Horizontal Scrolling:: Moving the contents sideways on the window. -* Size of Window:: Accessing the size of a window. -* Resizing Windows:: Changing the size of a window. -* Coordinates and Windows:: Converting coordinates to windows. -* Window Tree:: The layout and sizes of all windows in a frame. -* Window Configurations:: Saving and restoring the state of the screen. -* Window Parameters:: Associating additional information with windows. -* Window Hooks:: Hooks for scrolling, window size changes, - redisplay going past a certain point, - or window configuration changes. - -Frames - -* Creating Frames:: Creating additional frames. -* Multiple Terminals:: Displaying on several different devices. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Terminal Parameters:: Parameters common for all frames on terminal. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other windows; - lowering it makes the others hide it. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shape:: Specifying the shape of the mouse pointer. -* Window System Selections::Transferring text to and from other X clients. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* Color Names:: Getting the definitions of color names. -* Text Terminal Colors:: Defining colors for text terminals. -* Resources:: Getting resource values from the server. -* Display Feature Testing:: Determining the features of a terminal. - -Frame Parameters - -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. - -Window Frame Parameters - -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Font and Color Parameters:: Fonts and colors for the frame text. - -Positions - -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. - -Motion - -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. - -Markers - -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers::Finding the marker's buffer or character position. -* Marker Insertion Types:: Two ways a marker can relocate when you - insert where it points. -* Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How "the mark" is implemented with a marker. -* The Region:: How to access "the region". - -Text - -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* Comparing Text:: Comparing substrings of buffers. -* Insertion:: Adding new text to a buffer. -* Commands for Insertion:: User-level commands to insert text. -* Deletion:: Removing text from a buffer. -* User-Level Deletion:: User-level commands to delete text. -* The Kill Ring:: Where removed text sometimes is saved for - later use. -* Undo:: Undoing changes to the text of a buffer. -* Maintaining Undo:: How to enable and disable undo information. - How to control how much information is kept. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix - from context. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Sorting:: Functions for sorting parts of the buffer. -* Columns:: Computing horizontal positions, and using them. -* Indentation:: Functions to insert or adjust indentation. -* Case Changes:: Case conversion of parts of the buffer. -* Text Properties:: Assigning Lisp property lists to text characters. -* Substitution:: Replacing a given character wherever it appears. -* Transposition:: Swapping two portions of a buffer. -* Registers:: How registers are implemented. Accessing - the text or position stored in a register. -* Base 64:: Conversion to or from base 64 encoding. -* Checksum/Hash:: Computing cryptographic hashes. -* Parsing HTML/XML:: Parsing HTML and XML. -* Atomic Changes:: Installing several buffer changes "atomically". -* Change Hooks:: Supplying functions to be run when text is changed. - -The Kill Ring - -* Kill Ring Concepts:: What text looks like in the kill ring. -* Kill Functions:: Functions that kill text. -* Yanking:: How yanking is done. -* Yank Commands:: Commands that access the kill ring. -* Low-Level Kill Ring:: Functions and variables for kill ring access. -* Internals of Kill Ring:: Variables that hold kill ring data. - -Indentation - -* Primitive Indent:: Functions used to count and insert indentation. -* Mode-Specific Indent:: Customize indentation for different modes. -* Region Indent:: Indent all the lines in a region. -* Relative Indent:: Indent the current line based on previous lines. -* Indent Tabs:: Adjustable, typewriter-like tab stops. -* Motion by Indent:: Move to first non-blank character. - -Text Properties - -* Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. -* Format Properties:: Properties for representing formatting of text. -* Sticky Properties:: How inserted text gets properties from - neighboring text. -* Lazy Properties:: Computing text properties in a lazy fashion - only when text is examined. -* Clickable Text:: Using text properties to make regions of text - do something when you click on them. -* Fields:: The @code{field} property defines - fields within the buffer. -* Not Intervals:: Why text properties do not use - Lisp-visible text intervals. - -Non-@acronym{ASCII} Characters - -* Text Representations:: How Emacs represents text. -* Converting Representations:: Converting unibyte to multibyte and vice versa. -* Selecting a Representation:: Treating a byte sequence as unibyte or multi. -* Character Codes:: How unibyte and multibyte relate to - codes of individual characters. -* Character Properties:: Character attributes that define their - behavior and handling. -* Character Sets:: The space of possible character codes - is divided into various character sets. -* Scanning Charsets:: Which character sets are used in a buffer? -* Translation of Characters:: Translation tables are used for conversion. -* Coding Systems:: Coding systems are conversions for saving files. -* Input Methods:: Input methods allow users to enter various - non-ASCII characters without special keyboards. -* Locales:: Interacting with the POSIX locale. - -Coding Systems - -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -* MS-DOS File Types:: How DOS "text" and "binary" files - relate to coding systems. - -Searching and Matching - -* String Search:: Search for an exact match. -* Searching and Case:: Case-independent or case-significant searching. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Match Data:: Finding out which part of the text matched, - after a string or regexp search. -* Search and Replace:: Commands that loop, searching and replacing. -* Standard Regexps:: Useful regexps for finding sentences, pages,... - -Regular Expressions - -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. -* Regexp Functions:: Functions for operating on regular expressions. - -Syntax of Regular Expressions - -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. - -The Match Data - -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. - -Syntax Tables - -* Syntax Basics:: Basic concepts of syntax tables. -* Syntax Descriptors:: How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Syntax Properties:: Overriding syntax with text properties. -* Motion and Syntax:: Moving over characters with certain syntaxes. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. -* Categories:: Another way of classifying character syntax. - -Syntax Descriptors - -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. - -Parsing Expressions - -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. - -Abbrevs and Abbrev Expansion - -* Abbrev Tables:: Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Abbrev Files:: Saving abbrevs in files. -* Abbrev Expansion:: Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. -* Abbrev Properties:: How to read and set abbrev properties. - Which properties have which effect. -* Abbrev Table Properties:: How to read and set abbrev table properties. - Which properties have which effect. - -Processes - -* Subprocess Creation:: Functions that start subprocesses. -* Shell Arguments:: Quoting an argument to pass it to a shell. -* Synchronous Processes:: Details of using synchronous subprocesses. -* Asynchronous Processes:: Starting up an asynchronous subprocess. -* Deleting Processes:: Eliminating an asynchronous subprocess. -* Process Information:: Accessing run-status and other attributes. -* Input to Processes:: Sending input to an asynchronous subprocess. -* Signals to Processes:: Stopping, continuing or interrupting - an asynchronous subprocess. -* Output from Processes:: Collecting output from an asynchronous subprocess. -* Sentinels:: Sentinels run when process run-status changes. -* Query Before Exit:: Whether to query if exiting will kill a process. -* System Processes:: Accessing other processes running on your system. -* Transaction Queues:: Transaction-based communication with subprocesses. -* Network:: Opening network connections. -* Network Servers:: Network servers let Emacs accept net connections. -* Datagrams:: UDP network connections. -* Low-Level Network:: Lower-level but more general function - to create connections and servers. -* Misc Network:: Additional relevant functions for net connections. -* Serial Ports:: Communicating with serial ports. -* Byte Packing:: Using bindat to pack and unpack binary data. - -Receiving Output from Processes - -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Decoding Output:: Filters can get unibyte or multibyte strings. -* Accepting Output:: How to wait until process output arrives. - -Low-Level Network Access - -* Network Processes:: Using @code{make-network-process}. -* Network Options:: Further control over network connections. -* Network Feature Testing:: Determining which network features work on - the machine you are using. - -Packing and Unpacking Byte Arrays - -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! - -Emacs Display - -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Forcing Redisplay:: Forcing redisplay. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Displaying messages at the bottom of the screen. -* Warnings:: Displaying warning messages for the user. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* Temporary Displays:: Displays that go away automatically. -* Overlays:: Use overlays to highlight parts of the buffer. -* Width:: How wide a character or string is on the screen. -* Line Height:: Controlling the height of lines. -* Faces:: A face defines a graphics style - for text characters: font, colors, etc. -* Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. -* Display Property:: Enabling special display features. -* Images:: Displaying images in Emacs buffers. -* Buttons:: Adding clickable buttons to Emacs buffers. -* Abstract Display:: Emacs's Widget for Object Collections. -* Blinking:: How Emacs shows the matching open parenthesis. -* Character Display:: How Emacs displays individual characters. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. -* Bidirectional Display:: Display of bidirectional scripts, such as - Arabic and Farsi. - -The Echo Area - -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. - -Reporting Warnings - -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize - their warnings. -* Warning Options:: Variables users set to control display of warnings. -* Delayed Warnings:: Deferring warning display until the end of a command. - -Overlays - -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. - -Faces - -* Defining Faces:: How to define a face. -* Face Attributes:: What is in a face? -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for - a character. -* Face Remapping:: Remapping faces to alternative definitions. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Basic Faces:: Faces that are defined by default. -* Font Selection:: Finding the best available font for a face. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. -* Low-Level Font:: Lisp representation for character display fonts. - -Fringes - -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. - -The @code{display} Property - -* Replacing Specs:: Display specs that replace the text. -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; adjusting the height, - spacing, and other properties of text. -* Display Margins:: Displaying text or images to the side of - the main text. - -Images - -* Image Formats:: Supported image formats. -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* GIF Images:: Special features for GIF format. -* TIFF Images:: Special features for TIFF format. -* PostScript Images:: Special features for PostScript format. -* ImageMagick Images:: Special features available through ImageMagick. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once - it is defined. -* Animated Images:: Some image formats can be animated. -* Image Cache:: Internal mechanisms of image display. - -Buttons - -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. - -Abstract Display - -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. - -Character Display - -* Usual Display:: The usual conventions for displaying characters. -* Display Tables:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. -* Glyphless Chars:: How glyphless characters are drawn. - -Operating System Interface - -* Starting Up:: Customizing Emacs startup processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* User Identification:: Finding the name and user id of the user. -* Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to - calendrical data and vice versa. -* Time Parsing:: Converting a time from numeric form to text - and vice versa. -* Processor Run Time:: Getting the run time used by Emacs. -* Time Calculations:: Adding, subtracting, comparing times, etc. -* Timers:: Setting a timer to call a function at a - certain time. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording terminal input. -* Terminal Output:: Controlling and recording terminal output. -* Sound Output:: Playing sounds on the computer's speaker. -* X11 Keysyms:: Operating on key symbols for X Windows. -* Batch Mode:: Running Emacs without terminal interaction. -* Session Management:: Saving and restoring state with - X Session Management. -* Notifications:: Desktop notifications. -* Dynamic Libraries:: On-demand loading of support libraries. - -Starting Up Emacs - -* Startup Summary:: Sequence of actions Emacs performs at startup. -* Init File:: Details on reading the init file. -* Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command-Line Arguments:: How command-line arguments are processed, - and how you can customize them. - -Getting Out of Emacs - -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. - -Terminal Input - -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. - -Preparing Lisp code for distribution - -* Packaging Basics:: The basic concepts of Emacs Lisp packages. -* Simple Packages:: How to package a single .el file. -* Multi-file Packages:: How to package multiple files. -* Package Archives:: Maintaining package archives. - -Tips and Conventions - -* Coding Conventions:: Conventions for clean and robust programs. -* Key Binding Conventions:: Which keys should be bound by which programs. -* Programming Tips:: Making Emacs code fit smoothly in Emacs. -* Compilation Tips:: Making compiled code run fast. -* Warning Tips:: Turning off compiler warnings. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. - -GNU Emacs Internals - -* Building Emacs:: How the dumped Emacs is made. -* Pure Storage:: Kludge to make preloaded Lisp functions shareable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Memory Usage:: Info about total size of Lisp objects made so far. -* Writing Emacs Primitives:: Writing C code for Emacs. -* Object Internals:: Data formats of buffers, windows, processes. - -Object Internals - -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end detailmenu -@end menu - -@include intro.texi -@include objects.texi -@include numbers.texi -@include strings.texi - -@include lists.texi -@include sequences.texi -@include hash.texi -@include symbols.texi -@include eval.texi - -@include control.texi -@include variables.texi -@include functions.texi -@include macros.texi - -@include customize.texi -@include loading.texi -@include compile.texi -@include advice.texi - -@c This includes edebug.texi. -@include debugging.texi -@include streams.texi -@include minibuf.texi -@include commands.texi - -@include keymaps.texi -@include modes.texi -@include help.texi -@include files.texi - -@include backups.texi - -@c ================ Beginning of Volume 2 ================ -@c include buffers.texi -@c include windows.texi -@c include frames.texi - -@c include positions.texi -@c include markers.texi -@c include text.texi -@c include nonascii.texi - -@c include searching.texi -@c include syntax.texi -@c include abbrevs.texi -@c include processes.texi - -@c include display.texi -@c include os.texi - -@c MOVE to Emacs Manual: include misc-modes.texi - -@c appendices - -@c REMOVE this: include non-hacker.texi - -@c include anti.texi -@c include doclicense.texi -@c include gpl.texi -@c include tips.texi -@c include internals.texi -@c include errors.texi -@c include maps.texi -@c include hooks.texi - -@include index.texi - -@ignore -@node New Symbols, , Index, Top -@unnumbered New Symbols Since the Previous Edition - -@printindex tp -@end ignore - -@bye - - -These words prevent "local variables" above from confusing Emacs. diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi deleted file mode 100644 index c74e7c438b4..00000000000 --- a/doc/lispref/vol2.texi +++ /dev/null @@ -1,1567 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This file is used for printing the GNU Emacs Lisp Reference Manual -@c in two volumes. It is a modified version of elisp.texi. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c %**start of header -@setfilename elisp -@settitle GNU Emacs Lisp Reference Manual: Volume 2 -@c %**end of header - -@c See two-volume-cross-refs.txt. -@tex -\message{Formatting for two volume edition...Volume 2...} -% -% Read special toc file, set up in two-volume.make. -\gdef\tocreadfilename{elisp2-toc-ready.toc} -% -% Don't make outlines, they're not needed and \readdatafile can't pay -% attention to the special definition above. -\global\let\pdfmakeoutlines=\relax -% -% Start volume 2 chapter numbering at 27; this must be listed as chapno26 -\global\chapno=26 -@end tex - -@c Version of the manual and of Emacs. -@set VERSION 3.1 -@include emacsver.texi -@set DATE May 2012 - -@dircategory Emacs -@direntry -* Elisp: (elisp). The Emacs Lisp Reference Manual. -@end direntry - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. the manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@set smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@c Combine indices. -@synindex cp fn -@syncodeindex vr fn -@syncodeindex ky fn -@syncodeindex pg fn -@c We use the "type index" to index new functions and variables. -@c @syncodeindex tp fn - -@copying -This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@* -corresponding to Emacs version @value{EMACSVER}. - -Copyright @copyright{} 1990-1996, 1998-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License,'' with the -Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the -section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@titlepage -@title GNU Emacs Lisp Reference Manual -@subtitle Volume 2 -@subtitle For Emacs Version @value{EMACSVER} -@subtitle Revision @value{VERSION}, @value{DATE} - -@author by Bil Lewis, Dan LaLiberte, Richard Stallman, -@author the GNU Manual Group, et al. -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 -Published by the Free Software Foundation @* -51 Franklin St, Fifth Floor @* -Boston, MA 02110-1301 @* -USA @* -ISBN 1-882114-74-4 - -@sp 2 -Cover art by Etienne Suvasa. -@end titlepage - - -@c Print the tables of contents -@summarycontents -@contents - - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top Emacs Lisp - -This Info file contains edition @value{VERSION} of the GNU Emacs Lisp -Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}. -@end ifnottex - -@menu -* Introduction:: Introduction and conventions used. - -* Lisp Data Types:: Data types of objects in Emacs Lisp. -* Numbers:: Numbers and arithmetic functions. -* Strings and Characters:: Strings, and functions that work on them. -* Lists:: Lists, cons cells, and related functions. -* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. - Certain functions act on any kind of sequence. - The description of vectors is here as well. -* Hash Tables:: Very fast lookup-tables. -* Symbols:: Symbols represent names, uniquely. - -* Evaluation:: How Lisp expressions are evaluated. -* Control Structures:: Conditionals, loops, nonlocal exits. -* Variables:: Using symbols in programs to stand for values. -* Functions:: A function is a Lisp program - that can be invoked from other functions. -* Macros:: Macros are a way to extend the Lisp language. -* Customization:: Making variables and faces customizable. - -* Loading:: Reading files of Lisp code into Lisp. -* Byte Compilation:: Compilation makes programs run faster. -* Advising Functions:: Adding to the definition of a function. -* Debugging:: Tools and tips for debugging Lisp programs. - -* Read and Print:: Converting Lisp objects to text and back. -* Minibuffers:: Using the minibuffer to read input. -* Command Loop:: How the editor command loop works, - and how you can call its subroutines. -* Keymaps:: Defining the bindings from keys to commands. -* Modes:: Defining major and minor modes. -* Documentation:: Writing and using documentation strings. - -* Files:: Accessing files. -* Backups and Auto-Saving:: Controlling how backups and auto-save - files are made. -* Buffers:: Creating and using buffer objects. -* Windows:: Manipulating windows and displaying buffers. -* Frames:: Making multiple system-level windows. -* Positions:: Buffer positions and motion functions. -* Markers:: Markers represent positions and update - automatically when the text is changed. - -* Text:: Examining and changing text in buffers. -* Non-ASCII Characters:: Non-ASCII text in buffers and strings. -* Searching and Matching:: Searching buffers for strings or regexps. -* Syntax Tables:: The syntax table controls word and list parsing. -* Abbrevs:: How Abbrev mode works, and its data structures. - -* Processes:: Running and communicating with subprocesses. -* Display:: Features for controlling the screen display. -* System Interface:: Getting the user id, system type, environment - variables, and other such things. - -* Packaging:: Preparing Lisp code for distribution. - -Appendices - -* Antinews:: Info for users downgrading to Emacs 23. -* GNU Free Documentation License:: The license for this documentation. -* GPL:: Conditions for copying and changing GNU Emacs. -* Tips:: Advice and coding conventions for Emacs Lisp. -* GNU Emacs Internals:: Building and dumping Emacs; - internal data structures. -* Standard Errors:: List of some standard error symbols. -* Standard Keymaps:: List of some standard keymaps. -* Standard Hooks:: List of some standard hook variables. - -* Index:: Index including concepts, functions, variables, - and other terms. - -@ignore -* New Symbols:: New functions and variables in Emacs @value{EMACSVER}. -@end ignore - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. - -@detailmenu - --- The Detailed Node Listing --- - --------------------------------- - -Here are other nodes that are subnodes of those already listed, -mentioned here so you can get to them in one step: - -Introduction - -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Version Info:: Which Emacs version is running? -* Acknowledgements:: The authors, editors, and sponsors of this manual. - -Conventions - -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use when examples print text. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. - -Format of Descriptions - -* A Sample Function Description:: A description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, @code{electric-future-map}. - -Lisp Data Types - -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Circular Objects:: Read syntax for circular structure. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. - -Programming Types - -* Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Symbol Type:: A multi-use object that refers to a function, - variable, or property list, and has a unique identity. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Char-Table Type:: One-dimensional sparse arrays indexed by characters. -* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. -* Hash Table Type:: Super-fast lookup tables. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. - -Character Type - -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. - -Cons Cell and List Types - -* Box Diagrams:: Drawing pictures of lists. -* Dotted Pair Notation:: A general syntax for cons cells. -* Association List Type:: A specially constructed list. - -String Type - -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. - -Editing Types - -* Buffer Type:: The basic object of editing. -* Marker Type:: A position in a buffer. -* Window Type:: Buffers are displayed in windows. -* Frame Type:: Windows subdivide frames. -* Terminal Type:: A terminal device displays frames. -* Window Configuration Type:: Recording the way a frame is subdivided. -* Frame Configuration Type:: Recording the status of all frames. -* Process Type:: A subprocess of Emacs running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Overlay Type:: How an overlay is represented. -* Font Type:: Fonts for displaying text. - -Numbers - -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating point numbers. -* Bitwise Operations:: Logical and, or, not, shifting. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. - -Strings and Characters - -* String Basics:: Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Modifying Strings:: Altering the contents of an existing string. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting to and from characters and strings. -* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. -* Case Conversion:: Case conversion functions. -* Case Tables:: Customizing case conversion. - -Lists - -* Cons Cells:: How lists are made out of cons cells. -* List-related Predicates:: Is this object a list? Comparing two lists. -* List Elements:: Extracting the pieces of a list. -* Building Lists:: Creating list structure. -* List Variables:: Modifying lists stored in variables. -* Modifying Lists:: Storing new pieces into an existing list. -* Sets And Lists:: A list can represent a finite mathematical set. -* Association Lists:: A list can represent a finite relation or mapping. -* Rings:: Managing a fixed-size ring of objects. - -Modifying Existing List Structure - -* Setcar:: Replacing an element in a list. -* Setcdr:: Replacing part of the list backbone. - This can be used to remove or add elements. -* Rearrangement:: Reordering the elements in a list; combining lists. - -Sequences, Arrays, and Vectors - -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Special characteristics of Emacs Lisp vectors. -* Vector Functions:: Functions specifically for vectors. -* Char-Tables:: How to work with char-tables. -* Bool-Vectors:: How to work with bool-vectors. - -Hash Tables - -* Creating Hash:: Functions to create hash tables. -* Hash Access:: Reading and writing the hash table contents. -* Defining Hash:: Defining new comparison methods. -* Other Hash:: Miscellaneous. - -Symbols - -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list - for recording miscellaneous information. - -Property Lists - -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. - -Evaluation - -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in - the program). -* Backquote:: Easier construction of list structure. -* Eval:: How to invoke the Lisp interpreter explicitly. - -Kinds of Forms - -* Self-Evaluating Forms:: Forms that evaluate to themselves. -* Symbol Forms:: Symbols evaluate as variables. -* Classifying Lists:: How to distinguish various sorts of list forms. -* Function Indirection:: When a symbol appears as the car of a list, - we find the real function via the symbol. -* Function Forms:: Forms that call functions. -* Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, - most of them extremely important. -* Autoloading:: Functions set up to load files - containing their real definitions. - -Control Structures - -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. - -Nonlocal Exits - -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an - error happens. - -Errors - -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. - -Variables - -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Tips for Defining:: Things you should think about when you - define a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. -* File Local Variables:: Handling local variable lists in files. -* Directory Local Variables:: Local variables common to all files in a - directory. -* Frame-Local Variables:: Frame-local bindings for variables. -* Variable Aliases:: Variables that are aliases for other variables. -* Variables with Restricted Values:: Non-constant variables whose value can - @emph{not} be an arbitrary Lisp object. - -Scoping Rules for Variable Bindings - -* Scope:: Scope means where in the program a value - is visible. Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and - avoid problems. - -Buffer-Local Variables - -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own buffer-local values. - -Functions - -* What Is a Function:: Lisp functions vs. primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Closures:: Functions that enclose a lexical environment. -* Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Defining functions that the compiler - will expand inline. -* Declaring Functions:: Telling the compiler that a function is defined. -* Function Safety:: Determining whether a function is safe to call. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how - functions work. - -Lambda Expressions - -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. - -Macros - -* Simple Macro:: A basic example. -* Expansion:: How, when and why macros are expanded. -* Compiling Macros:: How macros are expanded by the compiler. -* Defining Macros:: How to write a macro definition. -* Problems with Macros:: Don't evaluate the macro arguments too many times. - Don't hide the user's variables. -* Indenting Macros:: Specifying how to indent macro calls. - -Common Problems Using Macros - -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. - -Customization Settings - -* Common Keywords:: Common keyword arguments for all kinds of - customization declarations. -* Group Definitions:: Writing customization group definitions. -* Variable Definitions:: Declaring user options. -* Customization Types:: Specifying the type of a user option. -* Applying Customizations:: Functions to apply customization settings. -* Custom Themes:: Writing Custom themes. - -Customization Types - -* Simple Types:: Simple customization types: sexp, integer, number, - string, file, directory, alist. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. - -Loading - -* How Programs Do Loading:: The @code{load} function and others. -* Load Suffixes:: Details about the suffixes that @code{load} tries. -* Library Search:: Finding a library to load. -* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. -* Autoload:: Setting up a function to autoload. -* Repeated Loading:: Precautions about loading a file twice. -* Named Features:: Loading a library if it isn't already loaded. -* Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. -* Hooks for Loading:: Providing code to be run when - particular libraries are loaded. - -Byte Compilation - -* Speed of Byte-Code:: An example of speedup from byte compilation. -* Compilation Functions:: Byte compilation functions. -* Docs and Compilation:: Dynamic loading of documentation strings. -* Dynamic Loading:: Dynamic loading of individual functions. -* Eval During Compile:: Code to be evaluated when you compile. -* Compiler Errors:: Handling compiler error messages. -* Byte-Code Objects:: The data type used for byte-compiled functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. - -Advising Emacs Lisp Functions - -* Simple Advice:: A simple example to explain the basics of advice. -* Defining Advice:: Detailed description of @code{defadvice}. -* Around-Advice:: Wrapping advice around a function's definition. -* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. -* Activation of Advice:: Advice doesn't do anything until you activate it. -* Enabling Advice:: You can enable or disable each piece of advice. -* Preactivation:: Preactivation is a way of speeding up the - loading of compiled advice. -* Argument Access in Advice:: How advice can access the function's arguments. -* Combined Definition:: How advice is implemented. - -Debugging Lisp Programs - -* Debugger:: A debugger for the Emacs Lisp evaluator. -* Edebug:: A source-level Emacs Lisp debugger. -* Syntax Errors:: How to find syntax errors. -* Test Coverage:: Ensuring you have tested all branches in your code. - -The Lisp Debugger - -* Error Debugging:: Entering the debugger when an error happens. -* Infinite Loops:: Stopping and debugging a program that doesn't exit. -* Function Debugging:: Entering it when a certain function is called. -* Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. -* Debugger Commands:: Commands used while in the debugger. -* Invoking the Debugger:: How to call the function @code{debug}. -* Internals of Debugger:: Subroutines of the debugger, and global variables. - -Edebug - -* Using Edebug:: Introduction to use of Edebug. -* Instrumenting:: You must instrument your code - in order to debug it with Edebug. -* Edebug Execution Modes:: Execution modes, stopping more or less often. -* Jumping:: Commands to jump to a specified place. -* Edebug Misc:: Miscellaneous commands. -* Breaks:: Setting breakpoints to make the program stop. -* Trapping Errors:: Trapping errors with Edebug. -* Edebug Views:: Views inside and outside of Edebug. -* Edebug Eval:: Evaluating expressions within Edebug. -* Eval List:: Expressions whose values are displayed - each time you enter Edebug. -* Printing in Edebug:: Customization of printing. -* Trace Buffer:: How to produce trace output in a buffer. -* Coverage Testing:: How to test evaluation coverage. -* The Outside Context:: Data that Edebug saves and restores. -* Edebug and Macros:: Specifying how to handle macro calls. -* Edebug Options:: Option variables for customizing Edebug. - -Breaks - -* Breakpoints:: Breakpoints at stop points. -* Global Break Condition:: Breaking on an event. -* Source Breakpoints:: Embedding breakpoints in source code. - -The Outside Context - -* Checking Whether to Stop::When Edebug decides what to do. -* Edebug Display Update:: When Edebug updates the display. -* Edebug Recursive Edit:: When Edebug stops execution. - -Edebug and Macros - -* Instrumenting Macro Calls::The basic problem. -* Specification List:: How to specify complex patterns of evaluation. -* Backtracking:: What Edebug does when matching fails. -* Specification Examples:: To help understand specifications. - -Debugging Invalid Lisp Syntax - -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. - -Reading and Printing Lisp Objects - -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as - input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as - output streams. -* Output Functions:: Functions to print Lisp objects as text. -* Output Variables:: Variables that control what the printing - functions do. - -Minibuffers - -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. -* Initial Input:: Specifying initial contents for the minibuffer. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Reading a Password:: Reading a password from the terminal. -* Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Windows:: Operating on the special minibuffer windows. -* Minibuffer Contents:: How such commands access the minibuffer text. -* Recursive Mini:: Whether recursive entry to minibuffer is allowed. -* Minibuffer Misc:: Various customization hooks and variables. - -Completion - -* Basic Completion:: Low-level functions for completing strings. - (These are too low level to use the minibuffer.) -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer names, variable names, etc.). -* Reading File Names:: Using completion to read file names and - shell commands. -* Completion Variables:: Variables controlling completion behavior. -* Programmed Completion:: Writing your own completion function. -* Completion in Buffers:: Completing text in ordinary buffers. - -Command Loop - -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Distinguish Interactive:: Making a command distinguish interactive calls. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Adjusting Point:: Adjustment of point after a command. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Special Events:: Events processed immediately and individually. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. - -Defining Commands - -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. - -Input Events - -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. - Event types. -* Accessing Mouse:: Functions to extract info from mouse events. -* Accessing Scroll:: Functions to get info from scroll bar events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. - -Reading Input - -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. - -Keymaps - -* Key Sequences:: Key sequences as Lisp objects. -* Keymap Basics:: Basic concepts of keymaps. -* Format of Keymaps:: What a keymap looks like as a Lisp object. -* Creating Keymaps:: Functions to create and copy keymaps. -* Inheritance and Keymaps:: How one keymap can inherit the bindings - of another keymap. -* Prefix Keys:: Defining a key with a keymap as its definition. -* Active Keymaps:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A minor mode can also override them. -* Key Lookup:: Finding a key's binding in one keymap. -* Functions for Key Lookup:: How to request key lookup. -* Changing Key Bindings:: Redefining a key in a keymap. -* Remapping Commands:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* Key Binding Commands:: Interactive interfaces for redefining keys. -* Scanning Keymaps:: Looking through all keymaps, for printing help. -* Menu Keymaps:: Defining a menu as a keymap. - -Menu Keymaps - -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. - -Defining Menus - -* Simple Menu Items:: A simple kind of menu key binding, - limited in capabilities. -* Extended Menu Items:: More powerful menu item definitions - let you specify keywords to enable - various features. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. -* Toolkit Differences:: Not all toolkits provide the same features. - -Major and Minor Modes - -* Hooks:: How to use hooks; how to write code that provides hooks. -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Imenu:: Providing a menu of definitions made in a buffer. -* Font Lock Mode:: How modes can highlight text according to syntax. -* Auto-Indentation:: How to teach Emacs to indent for a major mode. -* Desktop Save Mode:: How modes can have buffer state saved between - Emacs sessions. - -Hooks - -* Running Hooks:: How to run a hook. -* Setting Hooks:: How to put functions on a hook, or remove them. - -Major Modes - -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. -* Derived Modes:: Defining a new major mode based on another major - mode. -* Basic Major Modes:: Modes that other modes are often derived from. -* Mode Hooks:: Hooks run at the end of major mode functions. -* Tabulated List Mode:: Parent mode for buffers containing tabulated data. -* Generic Modes:: Defining a simple major mode that supports - comment syntax and Font Lock mode. -* Example Major Modes:: Text mode and Lisp modes. - -Minor Modes - -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -* Defining Minor Modes:: A convenient facility for defining minor modes. - -Mode Line Format - -* Mode Line Basics:: Basic ideas of mode line control. -* Mode Line Data:: The data structure that controls the mode line. -* Mode Line Top:: The top level variable, mode-line-format. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. -* Properties in Mode:: Using text properties in the mode line. -* Header Lines:: Like a mode line, but at the top. -* Emulating Mode Line:: Formatting text as the mode line would. - -Font Lock Mode - -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. - -Multiline Font Lock Constructs - -* Font Lock Multiline:: Marking multiline chunks with a text property. -* Region to Refontify:: Controlling which region gets refontified - after a buffer change. - -Automatic Indentation of code - -* SMIE:: A simple minded indentation engine. - -Simple Minded Indentation Engine - -* SMIE setup:: SMIE setup and features. -* Operator Precedence Grammars:: A very simple parsing technique. -* SMIE Grammar:: Defining the grammar of a language. -* SMIE Lexer:: Defining tokens. -* SMIE Tricks:: Working around the parser's limitations. -* SMIE Indentation:: Specifying indentation rules. -* SMIE Indentation Helpers:: Helper functions for indentation rules. -* SMIE Indentation Example:: Sample indentation rules. - -Documentation - -* Documentation Basics:: Where doc strings are defined and stored. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. - -Files - -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing Files:: Renaming files, changing permissions, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Special handling for certain file names. -* Format Conversion:: Conversion to and from various file formats. - -Visiting Files - -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. - -Information about Files - -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A symbolic link? -* Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: How large is it? Any other names? Etc. -* Locating Files:: How to find a file in standard places. - -File Names - -* File Name Components:: The directory part of a file name, and the rest. -* Relative File Names:: Some file names are relative to a current directory. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. -* Standard File Names:: If your package uses a fixed file name, - how to handle various operating systems simply. - -File Format Conversion - -* Format Conversion Overview:: @code{insert-file-contents} and @code{write-region}. -* Format Conversion Round-Trip:: Using @code{format-alist}. -* Format Conversion Piecemeal:: Specifying non-paired conversion. - -Backups and Auto-Saving - -* Backup Files:: How backup files are made; how their names - are chosen. -* Auto-Saving:: How auto-save files are made; how their - names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize - what it does. - -Backup Files - -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file - or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. - -Buffers - -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so that primitives will access its contents. -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file - is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - "behind Emacs's back". -* Read Only Buffers:: Modifying text is not allowed in a - read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Indirect Buffers:: An indirect buffer shares text with some - other buffer. -* Swapping Text:: Swapping text between two buffers. -* Buffer Gap:: The gap in the buffer. - -Windows - -* Basic Windows:: Basic information on using windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Switching Buffers:: Higher-level functions for switching to a buffer. -* Choosing Window:: How to choose a window for displaying a buffer. -* Display Action Functions:: Subroutines for @code{display-buffer}. -* Choosing Window Options:: Extra options affecting how buffers are displayed. -* Window History:: Each window remembers the buffers displayed in it. -* Dedicated Windows:: How to avoid displaying another buffer in - a specific window. -* Window Point:: Each window has its own location of point. -* Window Start and End:: Buffer positions indicating which text is - on-screen in a window. -* Textual Scrolling:: Moving text up and down through the window. -* Vertical Scrolling:: Moving the contents up and down on the window. -* Horizontal Scrolling:: Moving the contents sideways on the window. -* Size of Window:: Accessing the size of a window. -* Resizing Windows:: Changing the size of a window. -* Coordinates and Windows:: Converting coordinates to windows. -* Window Tree:: The layout and sizes of all windows in a frame. -* Window Configurations:: Saving and restoring the state of the screen. -* Window Parameters:: Associating additional information with windows. -* Window Hooks:: Hooks for scrolling, window size changes, - redisplay going past a certain point, - or window configuration changes. - -Frames - -* Creating Frames:: Creating additional frames. -* Multiple Terminals:: Displaying on several different devices. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Terminal Parameters:: Parameters common for all frames on terminal. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other windows; - lowering it makes the others hide it. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shape:: Specifying the shape of the mouse pointer. -* Window System Selections::Transferring text to and from other X clients. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* Color Names:: Getting the definitions of color names. -* Text Terminal Colors:: Defining colors for text terminals. -* Resources:: Getting resource values from the server. -* Display Feature Testing:: Determining the features of a terminal. - -Frame Parameters - -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. - -Window Frame Parameters - -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Font and Color Parameters:: Fonts and colors for the frame text. - -Positions - -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. - -Motion - -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. - -Markers - -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers::Finding the marker's buffer or character position. -* Marker Insertion Types:: Two ways a marker can relocate when you - insert where it points. -* Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How "the mark" is implemented with a marker. -* The Region:: How to access "the region". - -Text - -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* Comparing Text:: Comparing substrings of buffers. -* Insertion:: Adding new text to a buffer. -* Commands for Insertion:: User-level commands to insert text. -* Deletion:: Removing text from a buffer. -* User-Level Deletion:: User-level commands to delete text. -* The Kill Ring:: Where removed text sometimes is saved for - later use. -* Undo:: Undoing changes to the text of a buffer. -* Maintaining Undo:: How to enable and disable undo information. - How to control how much information is kept. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix - from context. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Sorting:: Functions for sorting parts of the buffer. -* Columns:: Computing horizontal positions, and using them. -* Indentation:: Functions to insert or adjust indentation. -* Case Changes:: Case conversion of parts of the buffer. -* Text Properties:: Assigning Lisp property lists to text characters. -* Substitution:: Replacing a given character wherever it appears. -* Transposition:: Swapping two portions of a buffer. -* Registers:: How registers are implemented. Accessing - the text or position stored in a register. -* Base 64:: Conversion to or from base 64 encoding. -* Checksum/Hash:: Computing cryptographic hashes. -* Parsing HTML/XML:: Parsing HTML and XML. -* Atomic Changes:: Installing several buffer changes "atomically". -* Change Hooks:: Supplying functions to be run when text is changed. - -The Kill Ring - -* Kill Ring Concepts:: What text looks like in the kill ring. -* Kill Functions:: Functions that kill text. -* Yanking:: How yanking is done. -* Yank Commands:: Commands that access the kill ring. -* Low-Level Kill Ring:: Functions and variables for kill ring access. -* Internals of Kill Ring:: Variables that hold kill ring data. - -Indentation - -* Primitive Indent:: Functions used to count and insert indentation. -* Mode-Specific Indent:: Customize indentation for different modes. -* Region Indent:: Indent all the lines in a region. -* Relative Indent:: Indent the current line based on previous lines. -* Indent Tabs:: Adjustable, typewriter-like tab stops. -* Motion by Indent:: Move to first non-blank character. - -Text Properties - -* Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. -* Format Properties:: Properties for representing formatting of text. -* Sticky Properties:: How inserted text gets properties from - neighboring text. -* Lazy Properties:: Computing text properties in a lazy fashion - only when text is examined. -* Clickable Text:: Using text properties to make regions of text - do something when you click on them. -* Fields:: The @code{field} property defines - fields within the buffer. -* Not Intervals:: Why text properties do not use - Lisp-visible text intervals. - -Non-@acronym{ASCII} Characters - -* Text Representations:: How Emacs represents text. -* Converting Representations:: Converting unibyte to multibyte and vice versa. -* Selecting a Representation:: Treating a byte sequence as unibyte or multi. -* Character Codes:: How unibyte and multibyte relate to - codes of individual characters. -* Character Properties:: Character attributes that define their - behavior and handling. -* Character Sets:: The space of possible character codes - is divided into various character sets. -* Scanning Charsets:: Which character sets are used in a buffer? -* Translation of Characters:: Translation tables are used for conversion. -* Coding Systems:: Coding systems are conversions for saving files. -* Input Methods:: Input methods allow users to enter various - non-ASCII characters without special keyboards. -* Locales:: Interacting with the POSIX locale. - -Coding Systems - -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -* MS-DOS File Types:: How DOS "text" and "binary" files - relate to coding systems. - -Searching and Matching - -* String Search:: Search for an exact match. -* Searching and Case:: Case-independent or case-significant searching. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Match Data:: Finding out which part of the text matched, - after a string or regexp search. -* Search and Replace:: Commands that loop, searching and replacing. -* Standard Regexps:: Useful regexps for finding sentences, pages,... - -Regular Expressions - -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. -* Regexp Functions:: Functions for operating on regular expressions. - -Syntax of Regular Expressions - -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. - -The Match Data - -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. - -Syntax Tables - -* Syntax Basics:: Basic concepts of syntax tables. -* Syntax Descriptors:: How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Syntax Properties:: Overriding syntax with text properties. -* Motion and Syntax:: Moving over characters with certain syntaxes. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. -* Categories:: Another way of classifying character syntax. - -Syntax Descriptors - -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. - -Parsing Expressions - -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. - -Abbrevs and Abbrev Expansion - -* Abbrev Tables:: Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Abbrev Files:: Saving abbrevs in files. -* Abbrev Expansion:: Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. -* Abbrev Properties:: How to read and set abbrev properties. - Which properties have which effect. -* Abbrev Table Properties:: How to read and set abbrev table properties. - Which properties have which effect. - -Processes - -* Subprocess Creation:: Functions that start subprocesses. -* Shell Arguments:: Quoting an argument to pass it to a shell. -* Synchronous Processes:: Details of using synchronous subprocesses. -* Asynchronous Processes:: Starting up an asynchronous subprocess. -* Deleting Processes:: Eliminating an asynchronous subprocess. -* Process Information:: Accessing run-status and other attributes. -* Input to Processes:: Sending input to an asynchronous subprocess. -* Signals to Processes:: Stopping, continuing or interrupting - an asynchronous subprocess. -* Output from Processes:: Collecting output from an asynchronous subprocess. -* Sentinels:: Sentinels run when process run-status changes. -* Query Before Exit:: Whether to query if exiting will kill a process. -* System Processes:: Accessing other processes running on your system. -* Transaction Queues:: Transaction-based communication with subprocesses. -* Network:: Opening network connections. -* Network Servers:: Network servers let Emacs accept net connections. -* Datagrams:: UDP network connections. -* Low-Level Network:: Lower-level but more general function - to create connections and servers. -* Misc Network:: Additional relevant functions for - network connections. -* Serial Ports:: Communicating with serial ports. -* Byte Packing:: Using bindat to pack and unpack binary data. - -Receiving Output from Processes - -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Decoding Output:: Filters can get unibyte or multibyte strings. -* Accepting Output:: How to wait until process output arrives. - -Low-Level Network Access - -* Network Processes:: Using @code{make-network-process}. -* Network Options:: Further control over network connections. -* Network Feature Testing:: Determining which network features work on - the machine you are using. - -Packing and Unpacking Byte Arrays - -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! - -Emacs Display - -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Forcing Redisplay:: Forcing redisplay. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Displaying messages at the bottom of the screen. -* Warnings:: Displaying warning messages for the user. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* Temporary Displays:: Displays that go away automatically. -* Overlays:: Use overlays to highlight parts of the buffer. -* Width:: How wide a character or string is on the screen. -* Line Height:: Controlling the height of lines. -* Faces:: A face defines a graphics style - for text characters: font, colors, etc. -* Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. -* Display Property:: Enabling special display features. -* Images:: Displaying images in Emacs buffers. -* Buttons:: Adding clickable buttons to Emacs buffers. -* Abstract Display:: Emacs's Widget for Object Collections. -* Blinking:: How Emacs shows the matching open parenthesis. -* Character Display:: How Emacs displays individual characters. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. -* Bidirectional Display:: Display of bidirectional scripts, such as - Arabic and Farsi. - -The Echo Area - -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. - -Reporting Warnings - -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize - their warnings. -* Warning Options:: Variables users set to control display of warnings. -* Delayed Warnings:: Deferring a warning until the end of a command. - -Overlays - -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. - -Faces - -* Defining Faces:: How to define a face. -* Face Attributes:: What is in a face? -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for - a character. -* Face Remapping:: Remapping faces to alternative definitions. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Basic Faces:: Faces that are defined by default. -* Font Selection:: Finding the best available font for a face. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. -* Low-Level Font:: Lisp representation for character display fonts. - -Fringes - -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. - -The @code{display} Property - -* Replacing Specs:: Display specs that replace the text. -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; adjusting the height, - spacing, and other properties of text. -* Display Margins:: Displaying text or images to the side of - the main text. - -Images - -* Image Formats:: Supported image formats. -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* GIF Images:: Special features for GIF format. -* TIFF Images:: Special features for TIFF format. -* PostScript Images:: Special features for PostScript format. -* ImageMagick Images:: Special features available through ImageMagick. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once - it is defined. -* Animated Images:: Some image formats can be animated. -* Image Cache:: Internal mechanisms of image display. - -Buttons - -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. - -Abstract Display - -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. - -Character Display - -* Usual Display:: The usual conventions for displaying characters. -* Display Tables:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. -* Glyphless Chars:: How glyphless characters are drawn. - -Operating System Interface - -* Starting Up:: Customizing Emacs startup processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* User Identification:: Finding the name and user id of the user. -* Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to - calendrical data and vice versa. -* Time Parsing:: Converting a time from numeric form to text - and vice versa. -* Processor Run Time:: Getting the run time used by Emacs. -* Time Calculations:: Adding, subtracting, comparing times, etc. -* Timers:: Setting a timer to call a function at a - certain time. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording terminal input. -* Terminal Output:: Controlling and recording terminal output. -* Sound Output:: Playing sounds on the computer's speaker. -* X11 Keysyms:: Operating on key symbols for X Windows. -* Batch Mode:: Running Emacs without terminal interaction. -* Session Management:: Saving and restoring state with - X Session Management. -* Notifications:: Desktop notifications. -* Dynamic Libraries:: On-demand loading of support libraries. - -Starting Up Emacs - -* Startup Summary:: Sequence of actions Emacs performs at startup. -* Init File:: Details on reading the init file. -* Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command-Line Arguments:: How command-line arguments are processed, - and how you can customize them. - -Getting Out of Emacs - -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. - -Terminal Input - -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. - -Preparing Lisp code for distribution - -* Packaging Basics:: The basic concepts of Emacs Lisp packages. -* Simple Packages:: How to package a single .el file. -* Multi-file Packages:: How to package multiple files. - -Tips and Conventions - -* Coding Conventions:: Conventions for clean and robust programs. -* Key Binding Conventions:: Which keys should be bound by which programs. -* Programming Tips:: Making Emacs code fit smoothly in Emacs. -* Compilation Tips:: Making compiled code run fast. -* Warning Tips:: Turning off compiler warnings. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. - -GNU Emacs Internals - -* Building Emacs:: How the dumped Emacs is made. -* Pure Storage:: Kludge to make preloaded Lisp functions shareable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Memory Usage:: Info about total size of Lisp objects made so far. -* Writing Emacs Primitives:: Writing C code for Emacs. -* Object Internals:: Data formats of buffers, windows, processes. - -Object Internals - -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end detailmenu -@end menu - -@c include intro.texi -@c include objects.texi -@c include numbers.texi -@c include strings.texi - -@c include lists.texi -@c include sequences.texi -@c include hash.texi -@c include symbols.texi -@c include eval.texi - -@c include control.texi -@c include variables.texi -@c include functions.texi -@c include macros.texi - -@c include customize.texi -@c include loading.texi -@c include compile.texi -@c include advice.texi - -@c This includes edebug.texi. -@c include debugging.texi -@c include streams.texi -@c include minibuf.texi -@c include commands.texi - -@c include keymaps.texi -@c include modes.texi -@c include help.texi -@c include files.texi - -@c include backups.texi - -@c ================ Beginning of Volume 2 ================ -@include buffers.texi -@include windows.texi -@include frames.texi - -@include positions.texi -@include markers.texi -@include text.texi -@include nonascii.texi - -@include searching.texi -@include syntax.texi -@include abbrevs.texi -@include processes.texi - -@include display.texi -@include os.texi - -@c MOVE to Emacs Manual: include misc-modes.texi - -@c appendices - -@c REMOVE this: include non-hacker.texi - -@include anti.texi -@include doclicense.texi -@include gpl.texi -@include tips.texi -@include internals.texi -@include errors.texi -@include maps.texi -@include hooks.texi - -@include index.texi - -@ignore -@node New Symbols, , Index, Top -@unnumbered New Symbols Since the Previous Edition - -@printindex tp -@end ignore - -@bye - - -These words prevent "local variables" above from confusing Emacs. diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi deleted file mode 100644 index 75d4a9beb8c..00000000000 --- a/doc/lispref/windows.texi +++ /dev/null @@ -1,3452 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/windows -@node Windows, Frames, Buffers, Top -@chapter Windows - -This chapter describes the functions and variables related to Emacs -windows. @xref{Frames}, for how windows are assigned an area of screen -available for Emacs to use. @xref{Display}, for information on how text -is displayed in windows. - -@menu -* Basic Windows:: Basic information on using windows. -* Windows and Frames:: Relating windows to the frame they appear on. -* Window Sizes:: Accessing a window's size. -* Resizing Windows:: Changing the sizes of windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Switching Buffers:: Higher-level functions for switching to a buffer. -* Choosing Window:: How to choose a window for displaying a buffer. -* Display Action Functions:: Subroutines for @code{display-buffer}. -* Choosing Window Options:: Extra options affecting how buffers are displayed. -* Window History:: Each window remembers the buffers displayed in it. -* Dedicated Windows:: How to avoid displaying another buffer in - a specific window. -* Quitting Windows:: How to restore the state prior to displaying a - buffer. -* Window Point:: Each window has its own location of point. -* Window Start and End:: Buffer positions indicating which text is - on-screen in a window. -* Textual Scrolling:: Moving text up and down through the window. -* Vertical Scrolling:: Moving the contents up and down on the window. -* Horizontal Scrolling:: Moving the contents sideways on the window. -* Coordinates and Windows:: Converting coordinates to windows. -* Window Configurations:: Saving and restoring the state of the screen. -* Window Parameters:: Associating additional information with windows. -* Window Hooks:: Hooks for scrolling, window size changes, - redisplay going past a certain point, - or window configuration changes. -@end menu - - -@node Basic Windows -@section Basic Concepts of Emacs Windows -@cindex window - -A @dfn{window} is a area of the screen that is used to display a -buffer (@pxref{Buffers}). In Emacs Lisp, windows are represented by a -special Lisp object type. - -@cindex multiple windows - Windows are grouped into frames (@pxref{Frames}). Each frame -contains at least one window; the user can subdivide it into multiple, -non-overlapping windows to view several buffers at once. Lisp -programs can use multiple windows for a variety of purposes. In -Rmail, for example, you can view a summary of message titles in one -window, and the contents of the selected message in another window. - -@cindex terminal screen -@cindex screen of terminal - Emacs uses the word ``window'' with a different meaning than in -graphical desktop environments and window systems, such as the X -Window System. When Emacs is run on X, each of its graphical X -windows is an Emacs frame (containing one or more Emacs windows). -When Emacs is run on a text terminal, the frame fills the entire -terminal screen. - -@cindex tiled windows - Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap -within the area of the frame. When a window is created, resized, or -deleted, the change in window space is taken from or given to the -adjacent windows, so that the total area of the frame is unchanged. - -@cindex live windows -@cindex internal windows - A @dfn{live window} is one that is actually displaying a buffer in a -frame. Such a window can be @dfn{deleted}, i.e. removed from the -frame (@pxref{Deleting Windows}); then it is no longer live, but the -Lisp object representing it might be still referenced from other Lisp -objects. A deleted window may be brought back to life by restoring a -saved window configuration (@pxref{Window Configurations}). - -@defun windowp object -This function returns @code{t} if @var{object} is a window (whether or -not it is live). Otherwise, it returns @code{nil}. -@end defun - -@defun window-live-p object -This function returns @code{t} if @var{object} is a live window and -@code{nil} otherwise. A live window is one that displays a buffer. -@end defun - - The windows in each frame are organized into a @dfn{window tree}. -@xref{Windows and Frames}. The leaf nodes of each window tree are -live windows---the ones actually displaying buffers. The internal -nodes of the window tree are internal windows, which are not live. -You can distinguish internal windows from deleted windows with -@code{window-valid-p}. - -@defun window-valid-p object -This function returns @code{t} if @var{object} is a live window, or an -internal window in a window tree. Otherwise, it returns @code{nil}, -including for the case where @var{object} is a deleted window. -@end defun - -@cindex selected window -@cindex window selected within a frame - In each frame, at any time, exactly one Emacs window is designated -as @dfn{selected within the frame}. For the selected frame, that -window is called the @dfn{selected window}---the one in which most -editing takes place, and in which the cursor for selected windows -appears (@pxref{Cursor Parameters}). The selected window's buffer is -usually also the current buffer, except when @code{set-buffer} has -been used (@pxref{Current Buffer}). As for non-selected frames, the -window selected within the frame becomes the selected window if the -frame is ever selected. @xref{Selecting Windows}. - -@defun selected-window -This function returns the selected window (which is always a live -window). -@end defun - -@node Windows and Frames -@section Windows and Frames - -Each window belongs to exactly one frame (@pxref{Frames}). - -@defun window-frame window -This function returns the frame that the window @var{window} belongs -to. If @var{window} is @code{nil}, it defaults to the selected -window. -@end defun - -@defun window-list &optional frame minibuffer window -This function returns a list of live windows belonging to the frame -@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to -the selected frame. - -The optional argument @var{minibuffer} specifies whether to include -the minibuffer window in the returned list. If @var{minibuffer} is -@code{t}, the minibuffer window is included. If @var{minibuffer} is -@code{nil} or omitted, the minibuffer window is included only if it is -active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the -minibuffer window is never included. - -The optional argument @var{window}, if non-@code{nil}, should be a live -window on the specified frame; then @var{window} will be the first -element in the returned list. If @var{window} is omitted or @code{nil}, -the window selected within the frame is the first element. -@end defun - -@cindex window tree -@cindex root window - Windows in the same frame are organized into a @dfn{window tree}, -whose leaf nodes are the live windows. The internal nodes of a window -tree are not live; they exist for the purpose of organizing the -relationships between live windows. The root node of a window tree is -called the @dfn{root window}. It can be either a live window (if the -frame has just one window), or an internal window. - - A minibuffer window (@pxref{Minibuffer Windows}) is not part of its -frame's window tree unless the frame is a minibuffer-only frame. -Nonetheless, most of the functions in this section accept the -minibuffer window as an argument. Also, the function -@code{window-tree} described at the end of this section lists the -minibuffer window alongside the actual window tree. - -@defun frame-root-window &optional frame-or-window -This function returns the root window for @var{frame-or-window}. The -argument @var{frame-or-window} should be either a window or a frame; -if omitted or @code{nil}, it defaults to the selected frame. If -@var{frame-or-window} is a window, the return value is the root window -of that window's frame. -@end defun - -@cindex parent window -@cindex child window -@cindex sibling window - When a window is split, there are two live windows where previously -there was one. One of these is represented by the same Lisp window -object as the original window, and the other is represented by a -newly-created Lisp window object. Both of these live windows become -leaf nodes of the window tree, as @dfn{child windows} of a single -internal window. If necessary, Emacs automatically creates this -internal window, which is also called the @dfn{parent window}, and -assigns it to the appropriate position in the window tree. A set of -windows that share the same parent are called @dfn{siblings}. - -@cindex parent window -@defun window-parent &optional window -This function returns the parent window of @var{window}. If -@var{window} is omitted or @code{nil}, it defaults to the selected -window. The return value is @code{nil} if @var{window} has no parent -(i.e. it is a minibuffer window or the root window of its frame). -@end defun - - Each internal window always has at least two child windows. If this -number falls to one as a result of window deletion, Emacs -automatically deletes the internal window, and its sole remaining -child window takes its place in the window tree. - - Each child window can be either a live window, or an internal window -(which in turn would have its own child windows). Therefore, each -internal window can be thought of as occupying a certain rectangular -@dfn{screen area}---the union of the areas occupied by the live -windows that are ultimately descended from it. - -@cindex window combination -@cindex vertical combination -@cindex horizontal combination - For each internal window, the screen areas of the immediate children -are arranged either vertically or horizontally (never both). If the -child windows are arranged one above the other, they are said to form -a @dfn{vertical combination}; if they are arranged side by side, they -are said to form a @dfn{horizontal combination}. Consider the -following example: - -@smallexample -@group - ______________________________________ - | ______ ____________________________ | - || || __________________________ || - || ||| ||| - || ||| ||| - || ||| ||| - || |||____________W4____________||| - || || __________________________ || - || ||| ||| - || ||| ||| - || |||____________W5____________||| - ||__W2__||_____________W3_____________ | - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -The root window of this frame is an internal window, @code{W1}. Its -child windows form a horizontal combination, consisting of the live -window @code{W2} and the internal window @code{W3}. The child windows -of @code{W3} form a vertical combination, consisting of the live -windows @code{W4} and @code{W5}. Hence, the live windows in this -window tree are @code{W2} @code{W4}, and @code{W5}. - - The following functions can be used to retrieve a child window of an -internal window, and the siblings of a child window. - -@defun window-top-child window -This function returns the topmost child window of @var{window}, if -@var{window} is an internal window whose children form a vertical -combination. For any other type of window, the return value is -@code{nil}. -@end defun - -@defun window-left-child window -This function returns the leftmost child window of @var{window}, if -@var{window} is an internal window whose children form a horizontal -combination. For any other type of window, the return value is -@code{nil}. -@end defun - -@defun window-child window -This function returns the first child window of the internal window -@var{window}---the topmost child window for a vertical combination, or -the leftmost child window for a horizontal combination. If -@var{window} is a live window, the return value is @code{nil}. -@end defun - -@defun window-combined-p &optional window horizontal -This function returns a non-@code{nil} value if and only if -@var{window} is part of a vertical combination. If @var{window} is -omitted or @code{nil}, it defaults to the selected one. - -If the optional argument @var{horizontal} is non-@code{nil}, this -means to return non-@code{nil} if and only if @var{window} is part of -a horizontal combination. -@end defun - -@defun window-next-sibling &optional window -This function returns the next sibling of the window @var{window}. If -omitted or @code{nil}, @var{window} defaults to the selected window. -The return value is @code{nil} if @var{window} is the last child of -its parent. -@end defun - -@defun window-prev-sibling &optional window -This function returns the previous sibling of the window @var{window}. -If omitted or @code{nil}, @var{window} defaults to the selected -window. The return value is @code{nil} if @var{window} is the first -child of its parent. -@end defun - -The functions @code{window-next-sibling} and -@code{window-prev-sibling} should not be confused with the functions -@code{next-window} and @code{previous-window}, which return the next -and previous window, respectively, in the cyclic ordering of windows -(@pxref{Cyclic Window Ordering}). - - You can use the following functions to find the first live window on -a frame, and to retrieve the entire window tree of a frame: - -@defun frame-first-window &optional frame-or-window -This function returns the live window at the upper left corner of the -frame specified by @var{frame-or-window}. The argument -@var{frame-or-window} must denote a window or a live frame and defaults -to the selected frame. If @var{frame-or-window} specifies a window, -this function returns the first window on that window's frame. Under -the assumption that the frame from our canonical example is selected -@code{(frame-first-window)} returns @code{W2}. -@end defun - -@defun window-tree &optional frame -This function returns a list representing the window tree for frame -@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to -the selected frame. - -The return value is a list of the form @code{(@var{root} @var{mini})}, -where @var{root} represents the window tree of the frame's root -window, and @var{mini} is the frame's minibuffer window. - -If the root window is live, @var{root} is that window itself. -Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1} -@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal -combination and @code{t} for a vertical combination, @var{edges} gives -the size and position of the combination, and the remaining elements -are the child windows. Each child window may again be a window object -(for a live window) or a list with the same format as above (for an -internal window). The @var{edges} element is a list @code{(@var{left} -@var{top} @var{right} @var{bottom})}, similar to the value returned by -@code{window-edges} (@pxref{Coordinates and Windows}). -@end defun - -@node Window Sizes -@section Window Sizes -@cindex window size -@cindex size of window - - The following schematic shows the structure of a live window: - -@smallexample -@group - _________________________________________ - ^ |______________ Header Line_______________| - | |LS|LF|LM| |RM|RF|RS| ^ - | | | | | | | | | | - Window | | | | Text Area | | | | Window - Total | | | | (Window Body) | | | | Body - Height | | | | | | | | Height - | | | | |<- Window Body Width ->| | | | | - | |__|__|__|_______________________|__|__|__| v - v |_______________ Mode Line _______________| - - <----------- Window Total Width --------> - -@end group -@end smallexample - -@cindex window body -@cindex text area of a window -@cindex body of a window - At the center of the window is the @dfn{text area}, or @dfn{body}, -where the buffer text is displayed. On each side of the text area is -a series of vertical areas; from innermost to outermost, these are the -left and right margins, denoted by LM and RM in the schematic -(@pxref{Display Margins}); the left and right fringes, denoted by LF -and RF (@pxref{Fringes}); and the left or right scroll bar, only one of -which is present at any time, denoted by LS and RS (@pxref{Scroll -Bars}). At the top of the window is an optional header line -(@pxref{Header Lines}), and at the bottom of the window is the mode -line (@pxref{Mode Line Format}). - - Emacs provides several functions for finding the height and width of -a window. Except where noted, Emacs reports window heights and widths -as integer numbers of lines and columns, respectively. On a graphical -display, each ``line'' and ``column'' actually corresponds to the -height and width of a ``default'' character specified by the frame's -default font. Thus, if a window is displaying text with a different -font or size, the reported height and width for that window may differ -from the actual number of text lines or columns displayed within it. - -@cindex window height -@cindex height of a window -@cindex total height of a window -@cindex window width -@cindex width of a window -@cindex total width of a window - The @dfn{total height} of a window is the distance between the top -and bottom of the window, including the header line (if one exists) -and the mode line. The @dfn{total width} of a window is the distance -between the left and right edges of the mode line. Note that the -height of a frame is not the same as the height of its windows, since -a frame may also contain an echo area, menu bar, and tool bar -(@pxref{Size and Position}). - -@defun window-total-height &optional window -This function returns the total height, in lines, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. If @var{window} is an internal window, the -return value is the total height occupied by its descendant windows. -@end defun - -@defun window-total-width &optional window -This function returns the total width, in columns, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. If @var{window} is internal, the return value -is the total width occupied by its descendant windows. -@end defun - -@defun window-total-size &optional window horizontal -This function returns either the total height or width of the window -@var{window}. If @var{horizontal} is omitted or @code{nil}, this is -equivalent to calling @code{window-total-height} for @var{window}; -otherwise it is equivalent to calling @code{window-total-width} for -@var{window}. -@end defun - -@cindex full-width window -@cindex full-height window - The following functions can be used to determine whether a given -window has any adjacent windows. - -@defun window-full-height-p &optional window -This function returns non-@code{nil} if @var{window} has no other -window above or below it in its frame, i.e. its total height equals -the total height of the root window on that frame. If @var{window} is -omitted or @code{nil}, it defaults to the selected window. -@end defun - -@defun window-full-width-p &optional window -This function returns non-@code{nil} if @var{window} has no other -window to the left or right in its frame, i.e. its total width equals -that of the root window on that frame. If @var{window} is omitted or -@code{nil}, it defaults to the selected window. -@end defun - -@cindex window body height -@cindex body height of a window -@cindex window body width -@cindex body width of a window -@cindex body size of a window -@cindex window body size - The @dfn{body height} of a window is the height of its text area, -which does not include the mode or header line. Similarly, the -@dfn{body width} is the width of the text area, which does not include -the scroll bar, fringes, or margins. - -@defun window-body-height &optional window -This function returns the body height, in lines, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window; otherwise it must be a live window. - -If there is a partially-visible line at the bottom of the text area, -that counts as a whole line; to exclude such a partially-visible line, -use @code{window-text-height}, below. -@end defun - -@defun window-body-width &optional window -This function returns the body width, in columns, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window; otherwise it must be a live window. -@end defun - -@defun window-body-size &optional window horizontal -This function returns the body height or body width of @var{window}. -If @var{horizontal} is omitted or @code{nil}, it is equivalent to -calling @code{window-body-height} for @var{window}; otherwise it is -equivalent to calling @code{window-body-width}. -@end defun - -@defun window-text-height &optional window -This function is like @code{window-body-height}, except that any -partially-visible line at the bottom of the text area is not counted. -@end defun - - For compatibility with previous versions of Emacs, -@code{window-height} is an alias for @code{window-total-height}, and -@code{window-width} is an alias for @code{window-body-width}. These -aliases are considered obsolete and will be removed in the future. - -@cindex fixed-size window - Commands that change the size of windows (@pxref{Resizing Windows}), -or split them (@pxref{Splitting Windows}), obey the variables -@code{window-min-height} and @code{window-min-width}, which specify -the smallest allowable window height and width. @xref{Change -Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs -Manual}. They also obey the variable @code{window-size-fixed}, with -which a window can be @dfn{fixed} in size: - -@defvar window-size-fixed -If this buffer-local variable is non-@code{nil}, the size of any -window displaying the buffer cannot normally be changed. Deleting a -window or changing the frame's size may still change its size, if -there is no choice. - -If the value is @code{height}, then only the window's height is fixed; -if the value is @code{width}, then only the window's width is fixed. -Any other non-@code{nil} value fixes both the width and the height. -@end defvar - -@defun window-size-fixed-p &optional window horizontal -This function returns a non-@code{nil} value if @var{window}'s height -is fixed. If @var{window} is omitted or @code{nil}, it defaults to -the selected window. If the optional argument @var{horizontal} is -non-@code{nil}, the return value is non-@code{nil} if @var{window}'s -width is fixed. - -A @code{nil} return value does not necessarily mean that @var{window} -can be resized in the desired direction. To determine that, use the -function @code{window-resizable}. @xref{Resizing Windows}. -@end defun - - @xref{Coordinates and Windows}, for more functions that report the -positions of various parts of a window relative to the frame, from -which you can calculate its size. In particular, you can use the -functions @code{window-pixel-edges} and -@code{window-inside-pixel-edges} to find the size in pixels, for -graphical displays. - -@node Resizing Windows -@section Resizing Windows -@cindex window resizing -@cindex resize window -@cindex changing window size -@cindex window size, changing - - This section describes functions for resizing a window without -changing the size of its frame. Because live windows do not overlap, -these functions are meaningful only on frames that contain two or more -windows: resizing a window also changes the size of a neighboring -window. If there is just one window on a frame, its size cannot be -changed except by resizing the frame (@pxref{Size and Position}). - - Except where noted, these functions also accept internal windows as -arguments. Resizing an internal window causes its child windows to be -resized to fit the same space. - -@defun window-resizable window delta &optional horizontal ignore -This function returns @var{delta} if the size of @var{window} can be -changed vertically by @var{delta} lines. If the optional argument -@var{horizontal} is non-@code{nil}, it instead returns @var{delta} if -@var{window} can be resized horizontally by @var{delta} columns. It -does not actually change the window size. - -If @var{window} is @code{nil}, it defaults to the selected window. - -A positive value of @var{delta} means to check whether the window can be -enlarged by that number of lines or columns; a negative value of -@var{delta} means to check whether the window can be shrunk by that many -lines or columns. If @var{delta} is non-zero, a return value of 0 means -that the window cannot be resized. - -Normally, the variables @code{window-min-height} and -@code{window-min-width} specify the smallest allowable window size. -@xref{Change Window,, Deleting and Rearranging Windows, emacs, The GNU -Emacs Manual}. However, if the optional argument @var{ignore} is -non-@code{nil}, this function ignores @code{window-min-height} and -@code{window-min-width}, as well as @code{window-size-fixed}. -Instead, it considers the minimum-height window to be one consisting -of a header (if any), a mode line, plus a text area one line tall; and -a minimum-width window as one consisting of fringes, margins, and -scroll bar (if any), plus a text area two columns wide. -@end defun - -@defun window-resize window delta &optional horizontal ignore -This function resizes @var{window} by @var{delta} increments. If -@var{horizontal} is @code{nil}, it changes the height by @var{delta} -lines; otherwise, it changes the width by @var{delta} columns. A -positive @var{delta} means to enlarge the window, and a negative -@var{delta} means to shrink it. - -If @var{window} is @code{nil}, it defaults to the selected window. If -the window cannot be resized as demanded, an error is signaled. - -The optional argument @var{ignore} has the same meaning as for the -function @code{window-resizable} above. - -The choice of which window edges this function alters depends on the -values of the option @code{window-combination-resize} and the -combination limits of the involved windows; in some cases, it may alter -both edges. @xref{Splitting Windows}. To resize by moving only the -bottom or right edge of a window, use the function -@code{adjust-window-trailing-edge}, below. -@end defun - -@c The commands enlarge-window, enlarge-window-horizontally, -@c shrink-window, and shrink-window-horizontally are documented in the -@c Emacs manual. They are not preferred for calling from Lisp. - -@defun adjust-window-trailing-edge window delta &optional horizontal -This function moves @var{window}'s bottom edge by @var{delta} lines. -If optional argument @var{horizontal} is non-@code{nil}, it instead -moves the right edge by @var{delta} columns. If @var{window} is -@code{nil}, it defaults to the selected window. - -A positive @var{delta} moves the edge downwards or to the right; a -negative @var{delta} moves it upwards or to the left. If the edge -cannot be moved as far as specified by @var{delta}, this function -moves it as far as possible but does not signal a error. - -This function tries to resize windows adjacent to the edge that is -moved. If this is not possible for some reason (e.g. if that adjacent -window is fixed-size), it may resize other windows. -@end defun - - The following commands resize windows in more specific ways. When -called interactively, they act on the selected window. - -@deffn Command fit-window-to-buffer &optional window max-height min-height override -This command adjusts the height of @var{window} to fit the text in it. -It returns non-@code{nil} if it was able to resize @var{window}, and -@code{nil} otherwise. If @var{window} is omitted or @code{nil}, it -defaults to the selected window. Otherwise, it should be a live -window. - -The optional argument @var{max-height}, if non-@code{nil}, specifies -the maximum total height that this function can give @var{window}. -The optional argument @var{min-height}, if non-@code{nil}, specifies -the minimum total height that it can give, which overrides the -variable @code{window-min-height}. - -If the optional argument @var{override} is non-@code{nil}, this -function ignores any size restrictions imposed by -@code{window-min-height} and @code{window-min-width}. -@end deffn - -@deffn Command shrink-window-if-larger-than-buffer &optional window -This command attempts to reduce @var{window}'s height as much as -possible while still showing its full buffer, but no less than -@code{window-min-height} lines. The return value is non-@code{nil} if -the window was resized, and @code{nil} otherwise. If @var{window} is -omitted or @code{nil}, it defaults to the selected window. Otherwise, -it should be a live window. - -This command does nothing if the window is already too short to -display all of its buffer, or if any of the buffer is scrolled -off-screen, or if the window is the only live window in its frame. -@end deffn - -@cindex balancing window sizes -@deffn Command balance-windows &optional window-or-frame -This function balances windows in a way that gives more space to -full-width and/or full-height windows. If @var{window-or-frame} -specifies a frame, it balances all windows on that frame. If -@var{window-or-frame} specifies a window, it balances only that window -and its siblings (@pxref{Windows and Frames}). -@end deffn - -@deffn Command balance-windows-area -This function attempts to give all windows on the selected frame -approximately the same share of the screen area. Full-width or -full-height windows are not given more space than other windows. -@end deffn - -@cindex maximizing windows -@deffn Command maximize-window &optional window -This function attempts to make @var{window} as large as possible, in -both dimensions, without resizing its frame or deleting other windows. -If @var{window} is omitted or @code{nil}, it defaults to the selected -window. -@end deffn - -@cindex minimizing windows -@deffn Command minimize-window &optional window -This function attempts to make @var{window} as small as possible, in -both dimensions, without deleting it or resizing its frame. If -@var{window} is omitted or @code{nil}, it defaults to the selected -window. -@end deffn - - -@node Splitting Windows -@section Splitting Windows -@cindex splitting windows -@cindex window splitting - -This section describes functions for creating a new window by -@dfn{splitting} an existing one. - -@deffn Command split-window &optional window size side -This function creates a new live window next to the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. That window is ``split'', and reduced in -size. The space is taken up by the new window, which is returned. - -The optional second argument @var{size} determines the sizes of -@var{window} and/or the new window. If it is omitted or @code{nil}, -both windows are given equal sizes; if there is an odd line, it is -allocated to the new window. If @var{size} is a positive number, -@var{window} is given @var{size} lines (or columns, depending on the -value of @var{side}). If @var{size} is a negative number, the new -window is given @minus{}@var{size} lines (or columns). - -If @var{size} is @code{nil}, this function obeys the variables -@code{window-min-height} and @code{window-min-width}. @xref{Change -Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs -Manual}. Thus, it signals an error if splitting would result in -making a window smaller than those variables specify. However, a -non-@code{nil} value for @var{size} causes those variables to be -ignored; in that case, the smallest allowable window is considered to -be one that has space for a text area one line tall and/or two columns -wide. - -The optional third argument @var{side} determines the position of the -new window relative to @var{window}. If it is @code{nil} or -@code{below}, the new window is placed below @var{window}. If it is -@code{above}, the new window is placed above @var{window}. In both -these cases, @var{size} specifies a total window height, in lines. - -If @var{side} is @code{t} or @code{right}, the new window is placed on -the right of @var{window}. If @var{side} is @code{left}, the new -window is placed on the left of @var{window}. In both these cases, -@var{size} specifies a total window width, in columns. - -If @var{window} is a live window, the new window inherits various -properties from it, including margins and scroll bars. If -@var{window} is an internal window, the new window inherits the -properties of the window selected within @var{window}'s frame. - -The behavior of this function may be altered by the window parameters -of @var{window}, so long as the variable -@code{ignore-window-parameters} is @code{nil}. If the value of -the @code{split-window} window parameter is @code{t}, this function -ignores all other window parameters. Otherwise, if the value of the -@code{split-window} window parameter is a function, that function is -called with the arguments @var{window}, @var{size}, and @var{side}, in -lieu of the usual action of @code{split-window}. Otherwise, this -function obeys the @code{window-atom} or @code{window-side} window -parameter, if any. @xref{Window Parameters}. -@end deffn - - As an example, here is a sequence of @code{split-window} calls that -yields the window configuration discussed in @ref{Windows and Frames}. -This example demonstrates splitting a live window as well as splitting -an internal window. We begin with a frame containing a single window -(a live root window), which we denote by @var{W4}. Calling -@code{(split-window W4)} yields this window configuration: - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - || || - ||_________________W4_________________|| - | ____________________________________ | - || || - || || - || || - ||_________________W5_________________|| - |__________________W3__________________| - -@end group -@end smallexample - -@noindent -The @code{split-window} call has created a new live window, denoted by -@var{W5}. It has also created a new internal window, denoted by -@var{W3}, which becomes the root window and the parent of both -@var{W4} and @var{W5}. - - Next, we call @code{(split-window W3 nil 'left)}, passing the -internal window @var{W3} as the argument. The result: - -@smallexample -@group - ______________________________________ - | ______ ____________________________ | - || || __________________________ || - || ||| ||| - || ||| ||| - || ||| ||| - || |||____________W4____________||| - || || __________________________ || - || ||| ||| - || ||| ||| - || |||____________W5____________||| - ||__W2__||_____________W3_____________ | - |__________________W1__________________| -@end group -@end smallexample - -@noindent -A new live window @var{W2} is created, to the left of the internal -window @var{W3}. A new internal window @var{W1} is created, becoming -the new root window. - -@defopt window-combination-resize -If this variable is @code{nil}, @code{split-window} can only split a -window (denoted by @var{window}) if @var{window}'s screen area is large -enough to accommodate both itself and the new window. - -If this variable is @code{t}, @code{split-window} tries to resize all -windows that are part of the same combination as @var{window}, in order -to accommodate the new window. In particular, this may allow -@code{split-window} to succeed even if @var{window} is a fixed-size -window or too small to ordinarily split. Furthermore, subsequently -resizing or deleting @var{window} may resize all other windows in its -combination. - -The default is @code{nil}. Other values are reserved for future use. -The value of this variable is ignored when -@code{window-combination-limit} is non-@code{nil} (see below). -@end defopt - - To illustrate the effect of @code{window-combination-resize}, -consider the following window configuration: - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - || || - || || - || || - ||_________________W3_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -If @code{window-combination-resize} is @code{nil}, splitting window -@code{W3} leaves the size of @code{W2} unchanged: - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - ||_________________W3_________________|| - | ____________________________________ | - || || - ||_________________W4_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -If @code{window-combination-resize} is @code{t}, splitting @code{W3} -instead leaves all three live windows with approximately the same -height: - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - || || - ||_________________W3_________________|| - | ____________________________________ | - || || - || || - ||_________________W4_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@defopt window-combination-limit -If the value of this variable is @code{t}, the @code{split-window} -function always creates a new internal window. If the value is -@code{nil}, the new live window is allowed to share the existing -parent window, if one exists, provided the split occurs in the same -direction as the existing window combination (otherwise, a new -internal window is created anyway). The default is @code{nil}. Other -values are reserved for future use. - -Thus, if the value of this variable is at all times @code{t}, then at -all times every window tree is a binary tree (a tree where each window -except the root window has exactly one sibling). - -Furthermore, @code{split-window} calls -@code{set-window-combination-limit} on the newly-created internal -window, recording the current value of this variable. This affects -how the window tree is rearranged when the child windows are deleted -(see below). -@end defopt - -@cindex window combination limit -@defun set-window-combination-limit window limit -This functions sets the @dfn{combination limit} of the window -@var{window} to @var{limit}. This value can be retrieved via the -function @code{window-combination-limit}. See below for its effects; -note that it is only meaningful for internal windows. The -@code{split-window} function automatically calls this function, passing -the value of the variable @code{window-combination-limit} as -@var{limit}. -@end defun - -@defun window-combination-limit window -This function returns the combination limit for @var{window}. - -The combination limit is meaningful only for an internal window. If -it is @code{nil}, then Emacs is allowed to automatically delete -@var{window}, in response to a window deletion, in order to group the -child windows of @var{window} with its sibling windows to form a new -window combination. If the combination limit is @code{t}, the child -windows of @var{window} are never automatically re-combined with its -siblings. -@end defun - - To illustrate the effect of @code{window-combination-limit}, -consider the following configuration (throughout this example, we will -assume that @code{window-combination-resize} is @code{nil}): - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - || || - || || - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - || || - ||_________________W3_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -If @code{window-combination-limit} is @code{nil}, splitting @code{W2} -into two windows, one above the other, yields - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - || || - ||_________________W4_________________|| - | ____________________________________ | - || || - || || - ||_________________W3_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -The newly-created window, @code{W4}, shares the same internal window -@code{W1}. If @code{W4} is resized, it is allowed to resize the other -live window, @code{W3}. - - If @code{window-combination-limit} is @code{t}, splitting @code{W2} -in the initial configuration would instead have produced this: - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || __________________________________ || - ||| ||| - |||________________W2________________||| - || __________________________________ || - ||| ||| - |||________________W4________________||| - ||_________________W5_________________|| - | ____________________________________ | - || || - || || - ||_________________W3_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -A new internal window @code{W5} has been created; its children are -@code{W2} and the new live window @code{W4}. Now, @code{W2} is the -only sibling of @code{W4}, so resizing @code{W4} will resize -@code{W2}, leaving @code{W3} unaffected. - - For interactive use, Emacs provides two commands which always split -the selected window. These call @code{split-window} internally. - -@deffn Command split-window-right &optional size -This function splits the selected window into two side-by-side -windows, putting the selected window on the left. If @var{size} is -positive, the left window gets @var{size} columns; if @var{size} is -negative, the right window gets @minus{}@var{size} columns. -@end deffn - -@deffn Command split-window-below &optional size -This function splits the selected window into two windows, one above -the other, leaving the upper window selected. If @var{size} is -positive, the upper window gets @var{size} lines; if @var{size} is -negative, the lower window gets @minus{}@var{size} lines. -@end deffn - -@defopt split-window-keep-point -If the value of this variable is non-@code{nil} (the default), -@code{split-window-below} behaves as described above. - -If it is @code{nil}, @code{split-window-below} adjusts point in each -of the two windows to minimize redisplay. (This is useful on slow -terminals.) It selects whichever window contains the screen line that -point was previously on. Note that this only affects -@code{split-window-below}, not the lower-level @code{split-window} -function. -@end defopt - -@node Deleting Windows -@section Deleting Windows -@cindex deleting windows - - @dfn{Deleting} a window removes it from the frame's window tree. If -the window is a live window, it disappears from the screen. If the -window is an internal window, its child windows are deleted too. - - Even after a window is deleted, it continues to exist as a Lisp -object, until there are no more references to it. Window deletion can -be reversed, by restoring a saved window configuration (@pxref{Window -Configurations}). - -@deffn Command delete-window &optional window -This function removes @var{window} from display and returns -@code{nil}. If @var{window} is omitted or @code{nil}, it defaults to -the selected window. If deleting the window would leave no more -windows in the window tree (e.g. if it is the only live window in the -frame), an error is signaled. - -By default, the space taken up by @var{window} is given to one of its -adjacent sibling windows, if any. However, if the variable -@code{window-combination-resize} is non-@code{nil}, the space is -proportionally distributed among any remaining windows in the window -combination. @xref{Splitting Windows}. - -The behavior of this function may be altered by the window parameters -of @var{window}, so long as the variable -@code{ignore-window-parameters} is @code{nil}. If the value of -the @code{delete-window} window parameter is @code{t}, this function -ignores all other window parameters. Otherwise, if the value of the -@code{delete-window} window parameter is a function, that function is -called with the argument @var{window}, in lieu of the usual action of -@code{delete-window}. Otherwise, this function obeys the -@code{window-atom} or @code{window-side} window parameter, if any. -@xref{Window Parameters}. -@end deffn - -@deffn Command delete-other-windows &optional window -This function makes @var{window} fill its frame, by deleting other -windows as necessary. If @var{window} is omitted or @code{nil}, it -defaults to the selected window. The return value is @code{nil}. - -The behavior of this function may be altered by the window parameters -of @var{window}, so long as the variable -@code{ignore-window-parameters} is @code{nil}. If the value of -the @code{delete-other-windows} window parameter is @code{t}, this -function ignores all other window parameters. Otherwise, if the value -of the @code{delete-other-windows} window parameter is a function, -that function is called with the argument @var{window}, in lieu of the -usual action of @code{delete-other-windows}. Otherwise, this function -obeys the @code{window-atom} or @code{window-side} window parameter, -if any. @xref{Window Parameters}. -@end deffn - -@deffn Command delete-windows-on &optional buffer-or-name frame -This function deletes all windows showing @var{buffer-or-name}, by -calling @code{delete-window} on those windows. @var{buffer-or-name} -should be a buffer, or the name of a buffer; if omitted or @code{nil}, -it defaults to the current buffer. If there are no windows showing -the specified buffer, this function does nothing. If the specified -buffer is a minibuffer, an error is signaled. - -If there is a dedicated window showing the buffer, and that window is -the only one on its frame, this function also deletes that frame if it -is not the only frame on the terminal. - -The optional argument @var{frame} specifies which frames to operate -on: - -@itemize @bullet -@item @code{nil} -means operate on all frames. -@item @code{t} -means operate on the selected frame. -@item @code{visible} -means operate on all visible frames. -@item @code{0} -means operate on all visible or iconified frames. -@item A frame -means operate on that frame. -@end itemize - -Note that this argument does not have the same meaning as in other -functions which scan all live windows (@pxref{Cyclic Window -Ordering}). Specifically, the meanings of @code{t} and @code{nil} here -are the opposite of what they are in those other functions. -@end deffn - -@node Selecting Windows -@section Selecting Windows -@cindex selecting a window - -@defun select-window window &optional norecord -This function makes @var{window} the selected window, as well as the -window selected within its frame (@pxref{Basic Windows}). -@var{window} must be a live window. Unless @var{window} already is the -selected window, its buffer becomes the current buffer (@pxref{Buffers -and Windows}). The return value is @var{window}. - -By default, this function also moves @var{window}'s selected buffer to -the front of the buffer list (@pxref{The Buffer List}), and makes -@var{window} the most recently selected window. However, if the -optional argument @var{norecord} is non-@code{nil}, these additional -actions are omitted. -@end defun - -@cindex most recently selected windows - The sequence of calls to @code{select-window} with a non-@code{nil} -@var{norecord} argument determines an ordering of windows by their -selection time. The function @code{get-lru-window} can be used to -retrieve the least recently selected live window (@pxref{Cyclic Window -Ordering}). - -@defmac save-selected-window forms@dots{} -This macro records the selected frame, as well as the selected window -of each frame, executes @var{forms} in sequence, then restores the -earlier selected frame and windows. It also saves and restores the -current buffer. It returns the value of the last form in @var{forms}. - -This macro does not save or restore anything about the sizes, -arrangement or contents of windows; therefore, if @var{forms} change -them, the change persists. If the previously selected window of some -frame is no longer live at the time of exit from @var{forms}, that -frame's selected window is left alone. If the previously selected -window is no longer live, then whatever window is selected at the end of -@var{forms} remains selected. The current buffer is restored if and -only if it is still live when exiting @var{forms}. - -This macro changes neither the ordering of recently selected windows nor -the buffer list. -@end defmac - -@defmac with-selected-window window forms@dots{} -This macro selects @var{window}, executes @var{forms} in sequence, then -restores the previously selected window and current buffer. The ordering -of recently selected windows and the buffer list remain unchanged unless -you deliberately change them within @var{forms}; for example, by calling -@code{select-window} with argument @var{norecord} @code{nil}. - -This macro does not change the order of recently selected windows or -the buffer list. -@end defmac - -@defun frame-selected-window &optional frame -This function returns the window on @var{frame} that is selected -within that frame. @var{frame} should be a live frame; if omitted or -@code{nil}, it defaults to the selected frame. -@end defun - -@defun set-frame-selected-window frame window &optional norecord -This function makes @var{window} the window selected within the frame -@var{frame}. @var{frame} should be a live frame; if omitted or -@code{nil}, it defaults to the selected frame. @var{window} should be -a live window; if omitted or @code{nil}, it defaults to the selected -window. - -If @var{frame} is the selected frame, this makes @var{window} the -selected window. - -If the optional argument @var{norecord} is non-@code{nil}, this -function does not alter the list of most recently selected windows, -nor the buffer list. -@end defun - -@node Cyclic Window Ordering -@section Cyclic Ordering of Windows -@cindex cyclic ordering of windows -@cindex ordering of windows, cyclic -@cindex window ordering, cyclic - - When you use the command @kbd{C-x o} (@code{other-window}) to select -some other window, it moves through live windows in a specific order. -For any given configuration of windows, this order never varies. It -is called the @dfn{cyclic ordering of windows}. - - The ordering is determined by a depth-first traversal of the frame's -window tree, retrieving the live windows which are the leaf nodes of -the tree (@pxref{Windows and Frames}). If the minibuffer is active, -the minibuffer window is included too. The ordering is cyclic, so the -last window in the sequence is followed by the first one. - -@defun next-window &optional window minibuf all-frames -@cindex minibuffer window, and @code{next-window} -This function returns a live window, the one following @var{window} in -the cyclic ordering of windows. @var{window} should be a live window; -if omitted or @code{nil}, it defaults to the selected window. - -The optional argument @var{minibuf} specifies whether minibuffer windows -should be included in the cyclic ordering. Normally, when @var{minibuf} -is @code{nil}, a minibuffer window is included only if it is currently -``active''; this matches the behavior of @kbd{C-x o}. (Note that a -minibuffer window is active as long as its minibuffer is in use; see -@ref{Minibuffers}). - -If @var{minibuf} is @code{t}, the cyclic ordering includes all -minibuffer windows. If @var{minibuf} is neither @code{t} nor -@code{nil}, minibuffer windows are not included even if they are active. - -The optional argument @var{all-frames} specifies which frames to -consider: - -@itemize @bullet -@item @code{nil} -means to consider windows on @var{window}'s frame. If the minibuffer -window is considered (as specified by the @var{minibuf} argument), -then frames that share the minibuffer window are considered too. - -@item @code{t} -means to consider windows on all existing frames. - -@item @code{visible} -means to consider windows on all visible frames. - -@item 0 -means to consider windows on all visible or iconified frames. - -@item A frame -means to consider windows on that specific frame. - -@item Anything else -means to consider windows on @var{window}'s frame, and no others. -@end itemize - -If more than one frame is considered, the cyclic ordering is obtained -by appending the orderings for those frames, in the same order as the -list of all live frames (@pxref{Finding All Frames}). -@end defun - -@defun previous-window &optional window minibuf all-frames -This function returns a live window, the one preceding @var{window} in -the cyclic ordering of windows. The other arguments are handled like -in @code{next-window}. -@end defun - -@deffn Command other-window count &optional all-frames -This function selects a live window, one @var{count} places from the -selected window in the cyclic ordering of windows. If @var{count} is -a positive number, it skips @var{count} windows forwards; if -@var{count} is negative, it skips @minus{}@var{count} windows -backwards; if @var{count} is zero, that simply re-selects the selected -window. When called interactively, @var{count} is the numeric prefix -argument. - -The optional argument @var{all-frames} has the same meaning as in -@code{next-window}, like a @code{nil} @var{minibuf} argument to -@code{next-window}. - -This function does not select a window that has a non-@code{nil} -@code{no-other-window} window parameter (@pxref{Window Parameters}). -@end deffn - -@defun walk-windows fun &optional minibuf all-frames -This function calls the function @var{fun} once for each live window, -with the window as the argument. - -It follows the cyclic ordering of windows. The optional arguments -@var{minibuf} and @var{all-frames} specify the set of windows -included; these have the same arguments as in @code{next-window}. If -@var{all-frames} specifies a frame, the first window walked is the -first window on that frame (the one returned by -@code{frame-first-window}), not necessarily the selected window. - -If @var{fun} changes the window configuration by splitting or deleting -windows, that does not alter the set of windows walked, which is -determined prior to calling @var{fun} for the first time. -@end defun - -@defun one-window-p &optional no-mini all-frames -This function returns @code{t} if the selected window is the only live -window, and @code{nil} otherwise. - -If the minibuffer window is active, it is normally considered (so that -this function returns @code{nil}). However, if the optional argument -@var{no-mini} is non-@code{nil}, the minibuffer window is ignored even -if active. The optional argument @var{all-frames} has the same -meaning as for @code{next-window}. -@end defun - -@cindex finding windows - The following functions return a window which satisfies some -criterion, without selecting it: - -@cindex least recently used window -@defun get-lru-window &optional all-frames dedicated -This function returns a live window which is heuristically the ``least -recently used'' window. The optional argument @var{all-frames} has -the same meaning as in @code{next-window}. - -If any full-width windows are present, only those windows are -considered. The selected window is never returned, unless it is the -only candidate. A minibuffer window is never a candidate. A -dedicated window (@pxref{Dedicated Windows}) is never a candidate -unless the optional argument @var{dedicated} is non-@code{nil}. -@end defun - -@cindex largest window -@defun get-largest-window &optional all-frames dedicated -This function returns the window with the largest area (height times -width). A minibuffer window is never a candidate. A dedicated window -(@pxref{Dedicated Windows}) is never a candidate unless the optional -argument @var{dedicated} is non-@code{nil}. - -If there are two candidate windows of the same size, this function -prefers the one that comes first in the cyclic ordering of windows, -starting from the selected window. - -The optional argument @var{all-frames} specifies the windows to -search, and has the same meaning as in @code{next-window}. -@end defun - -@cindex window that satisfies a predicate -@cindex conditional selection of windows -@defun get-window-with-predicate predicate &optional minibuf all-frames default -This function calls the function @var{predicate} for each of the -windows in the cyclic order of windows in turn, passing it the window -as an argument. If the predicate returns non-@code{nil} for any -window, this function stops and returns that window. If no such -window is found, the return value is @var{default} (which defaults to -@code{nil}). - -The optional arguments @var{minibuf} and @var{all-frames} specify the -windows to search, and have the same meanings as in -@code{next-window}. -@end defun - -@node Buffers and Windows -@section Buffers and Windows -@cindex examining windows -@cindex windows, controlling precisely -@cindex buffers, controlled in windows - - This section describes low-level functions for examining and setting -the contents of windows. @xref{Switching Buffers}, for higher-level -functions for displaying a specific buffer in a window. - -@defun window-buffer &optional window -This function returns the buffer that @var{window} is displaying. If -@var{window} is omitted or @code{nil} it defaults to the selected -window. If @var{window} is an internal window, this function returns -@code{nil}. -@end defun - -@defun set-window-buffer window buffer-or-name &optional keep-margins -This function makes @var{window} display @var{buffer-or-name}. -@var{window} should be a live window; if @code{nil}, it defaults to -the selected window. @var{buffer-or-name} should be a buffer, or the -name of an existing buffer. This function does not change which -window is selected, nor does it directly change which buffer is -current (@pxref{Current Buffer}). Its return value is @code{nil}. - -If @var{window} is @dfn{strongly dedicated} to a buffer and -@var{buffer-or-name} does not specify that buffer, this function -signals an error. @xref{Dedicated Windows}. - -By default, this function resets @var{window}'s position, display -margins, fringe widths, and scroll bar settings, based on the local -variables in the specified buffer. However, if the optional argument -@var{keep-margins} is non-@code{nil}, it leaves the display margins -and fringe widths unchanged. - -When writing an application, you should normally use the higher-level -functions described in @ref{Switching Buffers}, instead of calling -@code{set-window-buffer} directly. - -This function runs @code{window-scroll-functions}, followed by -@code{window-configuration-change-hook}. @xref{Window Hooks}. -@end defun - -@defvar buffer-display-count -This buffer-local variable records the number of times a buffer has been -displayed in a window. It is incremented each time -@code{set-window-buffer} is called for the buffer. -@end defvar - -@defvar buffer-display-time -This buffer-local variable records the time at which a buffer was last -displayed in a window. The value is @code{nil} if the buffer has -never been displayed. It is updated each time -@code{set-window-buffer} is called for the buffer, with the value -returned by @code{current-time} (@pxref{Time of Day}). -@end defvar - -@defun get-buffer-window &optional buffer-or-name all-frames -This function returns the first window displaying @var{buffer-or-name} -in the cyclic ordering of windows, starting from the selected window -(@pxref{Cyclic Window Ordering}). If no such window exists, the -return value is @code{nil}. - -@var{buffer-or-name} should be a buffer or the name of a buffer; if -omitted or @code{nil}, it defaults to the current buffer. The -optional argument @var{all-frames} specifies which windows to -consider: - -@itemize @bullet -@item -@code{t} means consider windows on all existing frames. -@item -@code{visible} means consider windows on all visible frames. -@item -0 means consider windows on all visible or iconified frames. -@item -A frame means consider windows on that frame only. -@item -Any other value means consider windows on the selected frame. -@end itemize - -Note that these meanings differ slightly from those of the -@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window -Ordering}). This function may be changed in a future version of Emacs -to eliminate this discrepancy. -@end defun - -@defun get-buffer-window-list &optional buffer-or-name minibuf all-frames -This function returns a list of all windows currently displaying -@var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the -name of an existing buffer. If omitted or @code{nil}, it defaults to -the current buffer. - -The arguments @var{minibuf} and @var{all-frames} have the same -meanings as in the function @code{next-window} (@pxref{Cyclic Window -Ordering}). Note that the @var{all-frames} argument does @emph{not} -behave exactly like in @code{get-buffer-window}. -@end defun - -@deffn Command replace-buffer-in-windows &optional buffer-or-name -This command replaces @var{buffer-or-name} with some other buffer, in -all windows displaying it. @var{buffer-or-name} should be a buffer, -or the name of an existing buffer; if omitted or @code{nil}, it -defaults to the current buffer. - -The replacement buffer in each window is chosen via -@code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated -window displaying @var{buffer-or-name} is deleted (@pxref{Dedicated -Windows}), unless it is the only window on its frame---if it is the -only window, and that frame is not the only frame on its terminal, the -frame is ``dismissed'' by calling the function specified by -@code{frame-auto-hide-function} (@pxref{Quitting Windows}). If the -dedicated window is the only window on the only frame on its terminal, -the buffer is replaced anyway. -@end deffn - -@node Switching Buffers -@section Switching to a Buffer in a Window -@cindex switching to a buffer -@cindex displaying a buffer - - This section describes high-level functions for switching to a -specified buffer in some window. - - Do @emph{not} use these functions to make a buffer temporarily -current just so a Lisp program can access or modify it. They have -side-effects, such as changing window histories (@pxref{Window -History}), which will surprise the user if used that way. If you want -to make a buffer current to modify it in Lisp, use -@code{with-current-buffer}, @code{save-current-buffer}, or -@code{set-buffer}. @xref{Current Buffer}. - -@deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window -This function displays @var{buffer-or-name} in the selected window, -and makes it the current buffer. (In contrast, @code{set-buffer} -makes the buffer current but does not display it; @pxref{Current -Buffer}). It is often used interactively (as the binding of @kbd{C-x -b}), as well as in Lisp programs. The return value is the buffer -switched to. - -If @var{buffer-or-name} is @code{nil}, it defaults to the buffer -returned by @code{other-buffer} (@pxref{The Buffer List}). If -@var{buffer-or-name} is a string that is not the name of any existing -buffer, this function creates a new buffer with that name; the new -buffer's major mode is determined by the variable @code{major-mode} -(@pxref{Major Modes}). - -Normally the specified buffer is put at the front of the buffer -list---both the global buffer list and the selected frame's buffer -list (@pxref{The Buffer List}). However, this is not done if the -optional argument @var{norecord} is non-@code{nil}. - -If this function is unable to display the buffer in the selected -window---usually because the selected window is a minibuffer window or -is strongly dedicated to its buffer (@pxref{Dedicated Windows})---then -it normally tries to display the buffer in some other window, in the -manner of @code{pop-to-buffer} (see below). However, if the optional -argument @var{force-same-window} is non-@code{nil}, it signals an error -instead. -@end deffn - -The next two functions are similar to @code{switch-to-buffer}, except -for the described features. - -@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord -This function makes the buffer specified by @var{buffer-or-name} -current and displays it in some window other than the selected window. -It uses the function @code{pop-to-buffer} internally (see below). - -If the selected window already displays the specified buffer, it -continues to do so, but another window is nonetheless found to display -it as well. - -The @var{buffer-or-name} and @var{norecord} arguments have the same -meanings as in @code{switch-to-buffer}. -@end deffn - -@deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord -This function makes the buffer specified by @var{buffer-or-name} -current and displays it, usually in a new frame. It uses the function -@code{pop-to-buffer} (see below). - -If the specified buffer is already displayed in another window, in any -frame on the current terminal, this switches to that window instead of -creating a new frame. However, the selected window is never used for -this. - -The @var{buffer-or-name} and @var{norecord} arguments have the same -meanings as in @code{switch-to-buffer}. -@end deffn - -The above commands use the function @code{pop-to-buffer}, which -flexibly displays a buffer in some window and selects that window for -editing. In turn, @code{pop-to-buffer} uses @code{display-buffer} for -displaying the buffer. Hence, all the variables affecting -@code{display-buffer} will affect it as well. @xref{Choosing Window}, -for the documentation of @code{display-buffer}. - -@deffn Command pop-to-buffer buffer-or-name &optional action norecord -This function makes @var{buffer-or-name} the current buffer and -displays it in some window, preferably not the window previously -selected. It then selects the displaying window. If that window is -on a different graphical frame, that frame is given input focus if -possible (@pxref{Input Focus}). The return value is the buffer that -was switched to. - -If @var{buffer-or-name} is @code{nil}, it defaults to the buffer -returned by @code{other-buffer} (@pxref{The Buffer List}). If -@var{buffer-or-name} is a string that is not the name of any existing -buffer, this function creates a new buffer with that name; the new -buffer's major mode is determined by the variable @code{major-mode} -(@pxref{Major Modes}). - -If @var{action} is non-@code{nil}, it should be a display action to -pass to @code{display-buffer} (@pxref{Choosing Window}). -Alternatively, a non-@code{nil}, non-list value means to pop to a -window other than the selected one---even if the buffer is already -displayed in the selected window. - -Like @code{switch-to-buffer}, this function updates the buffer list -unless @var{norecord} is non-@code{nil}. -@end deffn - -@node Choosing Window -@section Choosing a Window for Display - - The command @code{display-buffer} flexibly chooses a window for -display, and displays a specified buffer in that window. It can be -called interactively, via the key binding @kbd{C-x 4 C-o}. It is also -used as a subroutine by many functions and commands, including -@code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching -Buffers}). - -@cindex display action -@cindex action function, for @code{display-buffer} -@cindex action alist, for @code{display-buffer} - This command performs several complex steps to find a window to -display in. These steps are described by means of @dfn{display -actions}, which have the form @code{(@var{function} . @var{alist})}. -Here, @var{function} is either a function or a list of functions, -which we refer to as @dfn{action functions}; @var{alist} is an -association list, which we refer to as @dfn{action alists}. - - An action function accepts two arguments: the buffer to display and -an action alist. It attempts to display the buffer in some window, -picking or creating a window according to its own criteria. If -successful, it returns the window; otherwise, it returns @code{nil}. -@xref{Display Action Functions}, for a list of predefined action -functions. - - @code{display-buffer} works by combining display actions from -several sources, and calling the action functions in turn, until one -of them manages to display the buffer and returns a non-@code{nil} -value. - -@deffn Command display-buffer buffer-or-name &optional action frame -This command makes @var{buffer-or-name} appear in some window, without -selecting the window or making the buffer current. The argument -@var{buffer-or-name} must be a buffer or the name of an existing -buffer. The return value is the window chosen to display the buffer. - -The optional argument @var{action}, if non-@code{nil}, should normally -be a display action (described above). @code{display-buffer} builds a -list of action functions and an action alist, by consolidating display -actions from the following sources (in order): - -@itemize -@item -The variable @code{display-buffer-overriding-action}. - -@item -The user option @code{display-buffer-alist}. - -@item -A special action for handling @code{special-display-buffer-names} and -@code{special-display-regexps}, if either of those variables is -non-@code{nil}. @xref{Choosing Window Options}. - -@item -The @var{action} argument. - -@item -The user option @code{display-buffer-base-action}. - -@item -The constant @code{display-buffer-fallback-action}. -@end itemize - -@noindent -Each action function is called in turn, passing the buffer as the -first argument and the combined action alist as the second argument, -until one of the functions returns non-@code{nil}. - -The argument @var{action} can also have a non-@code{nil}, non-list -value. This has the special meaning that the buffer should be -displayed in a window other than the selected one, even if the -selected window is already displaying it. If called interactively -with a prefix argument, @var{action} is @code{t}. - -The optional argument @var{frame}, if non-@code{nil}, specifies which -frames to check when deciding whether the buffer is already displayed. -It is equivalent to adding an element @code{(reusable-frames -. @var{frame})} to the action alist of @var{action}. @xref{Display -Action Functions}. -@end deffn - -@defvar display-buffer-overriding-action -The value of this variable should be a display action, which is -treated with the highest priority by @code{display-buffer}. The -default value is empty, i.e. @code{(nil . nil)}. -@end defvar - -@defopt display-buffer-alist -The value of this option is an alist mapping regular expressions to -display actions. If the name of the buffer passed to -@code{display-buffer} matches a regular expression in this alist, then -@code{display-buffer} uses the corresponding display action. -@end defopt - -@defopt display-buffer-base-action -The value of this option should be a display action. This option can -be used to define a ``standard'' display action for calls to -@code{display-buffer}. -@end defopt - -@defvr Constant display-buffer-fallback-action -This display action specifies the fallback behavior for -@code{display-buffer} if no other display actions are given. -@end defvr - -@node Display Action Functions -@section Action Functions for @code{display-buffer} - -The following basic action functions are defined in Emacs. Each of -these functions takes two arguments: @var{buffer}, the buffer to -display, and @var{alist}, an action alist. Each action function -returns the window if it succeeds, and @code{nil} if it fails. - -@defun display-buffer-same-window buffer alist -This function tries to display @var{buffer} in the selected window. -It fails if the selected window is a minibuffer window or is dedicated -to another buffer (@pxref{Dedicated Windows}). It also fails if -@var{alist} has a non-@code{nil} @code{inhibit-same-window} entry. -@end defun - -@defun display-buffer-reuse-window buffer alist -This function tries to ``display'' @var{buffer} by finding a window -that is already displaying it. - -If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, -the selected window is not eligible for reuse. If @var{alist} -contains a @code{reusable-frames} entry, its value determines which -frames to search for a reusable window: - -@itemize @bullet -@item -@code{nil} means consider windows on the selected frame. -(Actually, the last non-minibuffer frame.) -@item -@code{t} means consider windows on all frames. -@item -@code{visible} means consider windows on all visible frames. -@item -0 means consider windows on all visible or iconified frames. -@item -A frame means consider windows on that frame only. -@end itemize - -If @var{alist} contains no @code{reusable-frames} entry, this function -normally searches just the selected frame; however, if either the -variable @code{display-buffer-reuse-frames} or the variable -@code{pop-up-frames} is non-@code{nil}, it searches all frames on the -current terminal. @xref{Choosing Window Options}. - -If this function chooses a window on another frame, it makes that -frame visible and raises it if necessary. -@end defun - -@defun display-buffer-pop-up-frame buffer alist -This function creates a new frame, and displays the buffer in that -frame's window. It actually performs the frame creation by calling -the function specified in @code{pop-up-frame-function} -(@pxref{Choosing Window Options}). -@end defun - -@defun display-buffer-pop-up-window buffer alist -This function tries to display @var{buffer} by splitting the largest -or least recently-used window (typically one on the selected frame). -It actually performs the split by calling the function specified in -@code{split-window-preferred-function} (@pxref{Choosing Window -Options}). - -It can fail if no window splitting can be performed for some reason -(e.g. if there is just one frame and it has an @code{unsplittable} -frame parameter; @pxref{Buffer Parameters}). -@end defun - -@defun display-buffer-use-some-window buffer alist -This function tries to display @var{buffer} by choosing an existing -window and displaying the buffer in that window. It can fail if all -windows are dedicated to another buffer (@pxref{Dedicated Windows}). -@end defun - -@node Choosing Window Options -@section Additional Options for Displaying Buffers - -The behavior of the standard display actions of @code{display-buffer} -(@pxref{Choosing Window}) can be modified by a variety of user -options. - -@defopt display-buffer-reuse-frames -If the value of this variable is non-@code{nil}, @code{display-buffer} -may search all frames on the current terminal when looking for a -window already displaying the specified buffer. The default is -@code{nil}. This variable is consulted by the action function -@code{display-buffer-reuse-window} (@pxref{Display Action Functions}). -@end defopt - -@defopt pop-up-windows -If the value of this variable is non-@code{nil}, @code{display-buffer} -is allowed to split an existing window to make a new window for -displaying in. This is the default. - -This variable is provided mainly for backward compatibility. It is -obeyed by @code{display-buffer} via a special mechanism in -@code{display-buffer-fallback-action}, which only calls the action -function @code{display-buffer-pop-up-window} (@pxref{Display Action -Functions}) when the value is @code{nil}. It is not consulted by -@code{display-buffer-pop-up-window} itself, which the user may specify -directly in @code{display-buffer-alist} etc. -@end defopt - -@defopt split-window-preferred-function -This variable specifies a function for splitting a window, in order to -make a new window for displaying a buffer. It is used by the -@code{display-buffer-pop-up-window} action function to actually split -the window (@pxref{Display Action Functions}). - -The default value is @code{split-window-sensibly}, which is documented -below. The value must be a function that takes one argument, a -window, and return either a new window (which is used to display the -desired buffer) or @code{nil} (which means the splitting failed). -@end defopt - -@defun split-window-sensibly window -This function tries to split @var{window}, and return the newly -created window. If @var{window} cannot be split, it returns -@code{nil}. - -This function obeys the usual rules that determine when a window may -be split (@pxref{Splitting Windows}). It first tries to split by -placing the new window below, subject to the restriction imposed by -@code{split-height-threshold} (see below), in addition to any other -restrictions. If that fails, it tries to split by placing the new -window to the right, subject to @code{split-width-threshold} (see -below). If that fails, and the window is the only window on its -frame, this function again tries to split and place the new window -below, disregarding @code{split-height-threshold}. If this fails as -well, this function gives up and returns @code{nil}. -@end defun - -@defopt split-height-threshold -This variable, used by @code{split-window-sensibly}, specifies whether -to split the window placing the new window below. If it is an -integer, that means to split only if the original window has at least -that many lines. If it is @code{nil}, that means not to split this -way. -@end defopt - -@defopt split-width-threshold -This variable, used by @code{split-window-sensibly}, specifies whether -to split the window placing the new window to the right. If the value -is an integer, that means to split only if the original window has at -least that many columns. If the value is @code{nil}, that means not -to split this way. -@end defopt - -@defopt pop-up-frames -If the value of this variable is non-@code{nil}, that means -@code{display-buffer} may display buffers by making new frames. The -default is @code{nil}. - -A non-@code{nil} value also means that when @code{display-buffer} is -looking for a window already displaying @var{buffer-or-name}, it can -search any visible or iconified frame, not just the selected frame. - -This variable is provided mainly for backward compatibility. It is -obeyed by @code{display-buffer} via a special mechanism in -@code{display-buffer-fallback-action}, which calls the action function -@code{display-buffer-pop-up-frame} (@pxref{Display Action Functions}) -if the value is non-@code{nil}. (This is done before attempting to -split a window.) This variable is not consulted by -@code{display-buffer-pop-up-frame} itself, which the user may specify -directly in @code{display-buffer-alist} etc. -@end defopt - -@defopt pop-up-frame-function -This variable specifies a function for creating a new frame, in order -to make a new window for displaying a buffer. It is used by the -@code{display-buffer-pop-up-frame} action function (@pxref{Display -Action Functions}). - -The value should be a function that takes no arguments and returns a -frame, or @code{nil} if no frame could be created. The default value -is a function that creates a frame using the parameters specified by -@code{pop-up-frame-alist} (see below). -@end defopt - -@defopt pop-up-frame-alist -This variable holds an alist of frame parameters (@pxref{Frame -Parameters}), which is used by the default function in -@code{pop-up-frame-function} to make a new frame. The default is -@code{nil}. -@end defopt - -@defopt special-display-buffer-names -A list of buffer names identifying buffers that should be displayed -specially. If the name of @var{buffer-or-name} is in this list, -@code{display-buffer} handles the buffer specially. By default, special -display means to give the buffer a dedicated frame. - -If an element is a list, instead of a string, then the @sc{car} of that -list is the buffer name, and the rest of that list says how to create -the frame. There are two possibilities for the rest of that list (its -@sc{cdr}): It can be an alist, specifying frame parameters, or it can -contain a function and arguments to give to it. (The function's first -argument is always the buffer to be displayed; the arguments from the -list come after that.) - -For example: - -@example -(("myfile" (minibuffer) (menu-bar-lines . 0))) -@end example - -@noindent -specifies to display a buffer named @samp{myfile} in a dedicated frame -with specified @code{minibuffer} and @code{menu-bar-lines} parameters. - -The list of frame parameters can also use the phony frame parameters -@code{same-frame} and @code{same-window}. If the specified frame -parameters include @code{(same-window . @var{value})} and @var{value} -is non-@code{nil}, that means to display the buffer in the current -selected window. Otherwise, if they include @code{(same-frame . -@var{value})} and @var{value} is non-@code{nil}, that means to display -the buffer in a new window in the currently selected frame. -@end defopt - -@defopt special-display-regexps -A list of regular expressions specifying buffers that should be -displayed specially. If the buffer's name matches any of the regular -expressions in this list, @code{display-buffer} handles the buffer -specially. By default, special display means to give the buffer a -dedicated frame. - -If an element is a list, instead of a string, then the @sc{car} of the -list is the regular expression, and the rest of the list says how to -create the frame. See @code{special-display-buffer-names} above. -@end defopt - -@defun special-display-p buffer-name -This function returns non-@code{nil} if displaying a buffer -named @var{buffer-name} with @code{display-buffer} would -create a special frame. The value is @code{t} if it would -use the default frame parameters, or else the specified list -of frame parameters. -@end defun - -@defopt special-display-function -This variable holds the function to call to display a buffer specially. -It receives the buffer as an argument, and should return the window in -which it is displayed. The default value of this variable is -@code{special-display-popup-frame}, see below. -@end defopt - -@defun special-display-popup-frame buffer &optional args -This function tries to make @var{buffer} visible in a frame of its own. -If @var{buffer} is already displayed in some window, it makes that -window's frame visible and raises it. Otherwise, it creates a frame -that is dedicated to @var{buffer}. The return value is the window used -to display @var{buffer}. - -If @var{args} is an alist, it specifies frame parameters for the new -frame. If @var{args} is a list whose @sc{car} is a symbol, then -@code{(car @var{args})} is a function to actually create and -set up the frame; it is called with @var{buffer} as first argument, and -@code{(cdr @var{args})} as additional arguments. - -This function always uses an existing window displaying @var{buffer}, -whether or not it is in a frame of its own; but if you set up the above -variables in your init file, before @var{buffer} was created, then -presumably the window was previously made by this function. -@end defun - -@defopt special-display-frame-alist -@anchor{Definition of special-display-frame-alist} -This variable holds frame parameters for -@code{special-display-popup-frame} to use when it creates a frame. -@end defopt - -@defopt same-window-buffer-names -A list of buffer names for buffers that should be displayed in the -selected window. If a buffer's name is in this list, -@code{display-buffer} handles the buffer by switching to it in the -selected window. -@end defopt - -@defopt same-window-regexps -A list of regular expressions that specify buffers that should be -displayed in the selected window. If the buffer's name matches any of -the regular expressions in this list, @code{display-buffer} handles the -buffer by switching to it in the selected window. -@end defopt - -@defun same-window-p buffer-name -This function returns @code{t} if displaying a buffer -named @var{buffer-name} with @code{display-buffer} would -put it in the selected window. -@end defun - -@c Emacs 19 feature -@defopt display-buffer-function -This variable is the most flexible way to customize the behavior of -@code{display-buffer}. If it is non-@code{nil}, it should be a function -that @code{display-buffer} calls to do the work. The function should -accept two arguments, the first two arguments that @code{display-buffer} -received. It should choose or create a window, display the specified -buffer in it, and then return the window. - -This variable takes precedence over all the other options described -above. -@end defopt - -@node Window History -@section Window History -@cindex window history - -Each window remembers the buffers it has previously displayed, and the order -in which these buffers were removed from it. This history is used, -for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and -Windows}). This list is automatically maintained by Emacs, but you can -use the following functions to explicitly inspect or alter it: - -@defun window-prev-buffers &optional window -This function returns a list specifying the previous contents of -@var{window}, which should be a live window and defaults to the -selected window. - -Each list element has the form @code{(@var{buffer} @var{window-start} -@var{window-pos})}, where @var{buffer} is a buffer previously shown in -the window, @var{window-start} is the window start position when that -buffer was last shown, and @var{window-pos} is the point position when -that buffer was last shown. - -The list is ordered so that earlier elements correspond to more -recently-shown buffers, and the first element usually corresponds to the -buffer most recently removed from the window. -@end defun - -@defun set-window-prev-buffers window prev-buffers -This function sets @var{window}'s previous buffers to the value of -@var{prev-buffers}. The argument @var{window} must be a live window -and defaults to the selected one. The argument @var{prev-buffers} -should be a list of the same form as that returned by -@code{window-prev-buffers}. -@end defun - -In addition, each buffer maintains a list of @dfn{next buffers}, which -is a list of buffers re-shown by @code{switch-to-prev-buffer} (see -below). This list is mainly used by @code{switch-to-prev-buffer} and -@code{switch-to-next-buffer} for choosing buffers to switch to. - -@defun window-next-buffers &optional window -This function returns the list of buffers recently re-shown in -@var{window} via @code{switch-to-prev-buffer}. The @var{window} -argument must denote a live window or @code{nil} (meaning the selected -window). -@end defun - -@defun set-window-next-buffers window next-buffers -This function sets the next buffer list of @var{window} to -@var{next-buffers}. The @var{window} argument should be a live window -or @code{nil} (meaning the selected window). The argument -@var{next-buffers} should be a list of buffers. -@end defun - -The following commands can be used to cycle through the global buffer -list, much like @code{bury-buffer} and @code{unbury-buffer}. However, -they cycle according to the specified window's history list, rather -than the global buffer list. In addition, they restore -window-specific window start and point positions, and may show a -buffer even if it is already shown in another window. The -@code{switch-to-prev-buffer} command, in particular, is used by -@code{replace-buffer-in-windows}, @code{bury-buffer} and -@code{quit-window} to find a replacement buffer for a window. - -@deffn Command switch-to-prev-buffer &optional window bury-or-kill -This command displays the previous buffer in @var{window}. The -argument @var{window} should be a live window or @code{nil} (meaning -the selected window). If the optional argument @var{bury-or-kill} is -non-@code{nil}, this means that the buffer currently shown in -@var{window} is about to be buried or killed and consequently should -not be switched to in future invocations of this command. - -The previous buffer is usually the buffer shown before the buffer -currently shown in @var{window}. However, a buffer that has been buried -or killed, or has been already shown by a recent invocation of -@code{switch-to-prev-buffer}, does not qualify as previous buffer. - -If repeated invocations of this command have already shown all buffers -previously shown in @var{window}, further invocations will show buffers -from the buffer list of the frame @var{window} appears on (@pxref{The -Buffer List}), trying to skip buffers that are already shown in another -window on that frame. -@end deffn - -@deffn Command switch-to-next-buffer &optional window -This command switches to the next buffer in @var{window}, thus undoing -the effect of the last @code{switch-to-prev-buffer} command in -@var{window}. The argument @var{window} must be a live window and -defaults to the selected one. - -If there is no recent invocation of @code{switch-to-prev-buffer} that -can be undone, this function tries to show a buffer from the buffer list -of the frame @var{window} appears on (@pxref{The Buffer List}). -@end deffn - -By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer} -can switch to a buffer that is already shown in another window on the -same frame. The following option can be used to override this behavior. - -@defopt switch-to-visible-buffer -If this variable is non-@code{nil}, @code{switch-to-prev-buffer} and -@code{switch-to-next-buffer} may switch to a buffer that is already -visible on the same frame, provided the buffer was shown in the relevant -window before. If it is @code{nil}, @code{switch-to-prev-buffer} and -@code{switch-to-next-buffer} always try to avoid switching to a buffer -that is already visible in another window on the same frame. -@end defopt - - -@node Dedicated Windows -@section Dedicated Windows -@cindex dedicated window - -Functions for displaying a buffer can be told to not use specific -windows by marking these windows as @dfn{dedicated} to their buffers. -@code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated -window for displaying another buffer in it. @code{get-lru-window} and -@code{get-largest-window} (@pxref{Selecting Windows}) do not consider -dedicated windows as candidates when their @var{dedicated} argument is -non-@code{nil}. The behavior of @code{set-window-buffer} -(@pxref{Buffers and Windows}) with respect to dedicated windows is -slightly different, see below. - -When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to -delete a dedicated window and that window is the only window on its -frame, it deletes the window's frame too, provided there are other -frames left. @code{replace-buffer-in-windows} (@pxref{Switching -Buffers}) tries to delete all dedicated windows showing its buffer -argument. When such a window is the only window on its frame, that -frame is deleted, provided there are other frames left. If there are -no more frames left, some other buffer is displayed in the window, and -the window is marked as non-dedicated. - -When you kill a buffer (@pxref{Killing Buffers}) displayed in a -dedicated window, any such window usually gets deleted too, since -@code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning -up windows. Burying a buffer (@pxref{The Buffer List}) deletes the -selected window if it is dedicated to that buffer. If, however, that -window is the only window on its frame, @code{bury-buffer} displays -another buffer in it and iconifies the frame. - -@defun window-dedicated-p &optional window -This function returns non-@code{nil} if @var{window} is dedicated to its -buffer and @code{nil} otherwise. More precisely, the return value is -the value assigned by the last call of @code{set-window-dedicated-p} for -@var{window}, or @code{nil} if that function was never called with -@var{window} as its argument. The default for @var{window} is the -selected window. -@end defun - -@defun set-window-dedicated-p window flag -This function marks @var{window} as dedicated to its buffer if -@var{flag} is non-@code{nil}, and non-dedicated otherwise. - -As a special case, if @var{flag} is @code{t}, @var{window} becomes -@dfn{strongly} dedicated to its buffer. @code{set-window-buffer} -signals an error when the window it acts upon is strongly dedicated to -its buffer and does not already display the buffer it is asked to -display. Other functions do not treat @code{t} differently from any -non-@code{nil} value. -@end defun - - -@node Quitting Windows -@section Quitting Windows - -When you want to get rid of a window used for displaying a buffer, you -can call @code{delete-window} or @code{delete-windows-on} -(@pxref{Deleting Windows}) to remove that window from its frame. If the -buffer is shown on a separate frame, you might want to call -@code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other -hand, a window has been reused for displaying the buffer, you might -prefer showing the buffer previously shown in that window, by calling the -function @code{switch-to-prev-buffer} (@pxref{Window History}). -Finally, you might want to either bury (@pxref{The Buffer List}) or kill -(@pxref{Killing Buffers}) the window's buffer. - - The following function uses information on how the window for -displaying the buffer was obtained in the first place, thus attempting to -automate the above decisions for you. - -@deffn Command quit-window &optional kill window -This command quits @var{window} and buries its buffer. The argument -@var{window} must be a live window and defaults to the selected one. -With prefix argument @var{kill} non-@code{nil}, it kills the buffer -instead of burying it. - -Quitting @var{window} means to proceed as follows: If @var{window} was -created specially for displaying its current buffer, delete @var{window} -provided its frame contains at least one other live window. If -@var{window} is the only window on its frame and there are other frames -on the frame's terminal, the value of @var{kill} determines how to -proceed with the window. If @var{kill} is @code{nil}, the fate of the -frame is determined by calling @code{frame-auto-hide-function} (see -below) with that frame as sole argument. If @var{kill} is -non-@code{nil}, the frame is deleted unconditionally. - -If @var{window} was reused for displaying its buffer, this command tries -to display the buffer previously shown in it. It also tries to restore -the window start (@pxref{Window Start and End}) and point (@pxref{Window -Point}) positions of the previously shown buffer. If, in addition, the -current buffer was temporarily resized, this command will also try to -restore the original height of @var{window}. - -The three cases described so far require that the buffer shown in -@var{window} is still the buffer displayed by the last buffer display -function for this window. If another buffer has been shown in the -meantime, or the buffer previously shown no longer exists, this command -calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show some -other buffer instead. -@end deffn - -The function @code{quit-window} bases its decisions on information -stored in @var{window}'s @code{quit-restore} window parameter -(@pxref{Window Parameters}), and resets that parameter to @code{nil} -after it's done. - -The following option specifies how to deal with a frame containing just -one window that should be either quit, or whose buffer should be buried. - -@defopt frame-auto-hide-function -The function specified by this option is called to automatically hide -frames. This function is called with one argument---a frame. - -The function specified here is called by @code{bury-buffer} (@pxref{The -Buffer List}) when the selected window is dedicated and shows the buffer -that should be buried. It is also called by @code{quit-window} (see -above) when the frame of the window that should be quit has been -specially created for displaying that window's buffer and the buffer -should be buried. - -The default is to call @code{iconify-frame} (@pxref{Visibility of -Frames}). Alternatively, you may specify either @code{delete-frame} -(@pxref{Deleting Frames}) to remove the frame from its display, -@code{ignore} to leave the frame unchanged, or any other function that -can take a frame as its sole argument. - -Note that the function specified by this option is called if and only if -there is at least one other frame on the terminal of the frame it's -supposed to handle, and that frame contains only one live window. -@end defopt - - -@node Window Point -@section Windows and Point -@cindex window position -@cindex window point -@cindex position in window -@cindex point in window - - Each window has its own value of point (@pxref{Point}), independent of -the value of point in other windows displaying the same buffer. This -makes it useful to have multiple windows showing one buffer. - -@itemize @bullet -@item -The window point is established when a window is first created; it is -initialized from the buffer's point, or from the window point of another -window opened on the buffer if such a window exists. - -@item -Selecting a window sets the value of point in its buffer from the -window's value of point. Conversely, deselecting a window sets the -window's value of point from that of the buffer. Thus, when you switch -between windows that display a given buffer, the point value for the -selected window is in effect in the buffer, while the point values for -the other windows are stored in those windows. - -@item -As long as the selected window displays the current buffer, the window's -point and the buffer's point always move together; they remain equal. -@end itemize - -@cindex cursor - As far as the user is concerned, point is where the cursor is, and -when the user switches to another buffer, the cursor jumps to the -position of point in that buffer. - -@defun window-point &optional window -This function returns the current position of point in @var{window}. -For a nonselected window, this is the value point would have (in that -window's buffer) if that window were selected. The default for -@var{window} is the selected window. - -When @var{window} is the selected window and its buffer is also the -current buffer, the value returned is the same as point in that buffer. -Strictly speaking, it would be more correct to return the ``top-level'' -value of point, outside of any @code{save-excursion} forms. But that -value is hard to find. -@end defun - -@defun set-window-point window position -This function positions point in @var{window} at position -@var{position} in @var{window}'s buffer. It returns @var{position}. - -If @var{window} is selected, and its buffer is current, -this simply does @code{goto-char}. -@end defun - -@defvar window-point-insertion-type -This variable specifies the marker insertion type (@pxref{Marker -Insertion Types}) of @code{window-point}. The default is @code{nil}, -so @code{window-point} will stay behind text inserted there. -@end defvar - -@node Window Start and End -@section The Window Start and End Positions -@cindex window start position - - Each window maintains a marker used to keep track of a buffer position -that specifies where in the buffer display should start. This position -is called the @dfn{display-start} position of the window (or just the -@dfn{start}). The character after this position is the one that appears -at the upper left corner of the window. It is usually, but not -inevitably, at the beginning of a text line. - - After switching windows or buffers, and in some other cases, if the -window start is in the middle of a line, Emacs adjusts the window -start to the start of a line. This prevents certain operations from -leaving the window start at a meaningless point within a line. This -feature may interfere with testing some Lisp code by executing it -using the commands of Lisp mode, because they trigger this -readjustment. To test such code, put it into a command and bind the -command to a key. - -@defun window-start &optional window -@cindex window top line -This function returns the display-start position of window -@var{window}. If @var{window} is @code{nil}, the selected window is -used. - -When you create a window, or display a different buffer in it, the -display-start position is set to a display-start position recently used -for the same buffer, or to @code{point-min} if the buffer doesn't have -any. - -Redisplay updates the window-start position (if you have not specified -it explicitly since the previous redisplay)---to make sure point appears -on the screen. Nothing except redisplay automatically changes the -window-start position; if you move point, do not expect the window-start -position to change in response until after the next redisplay. -@end defun - -@cindex window end position -@defun window-end &optional window update -This function returns the position where display of its buffer ends in -@var{window}. The default for @var{window} is the selected window. - -Simply changing the buffer text or moving point does not update the -value that @code{window-end} returns. The value is updated only when -Emacs redisplays and redisplay completes without being preempted. - -If the last redisplay of @var{window} was preempted, and did not finish, -Emacs does not know the position of the end of display in that window. -In that case, this function returns @code{nil}. - -If @var{update} is non-@code{nil}, @code{window-end} always returns an -up-to-date value for where display ends, based on the current -@code{window-start} value. If a previously saved value of that position -is still valid, @code{window-end} returns that value; otherwise it -computes the correct value by scanning the buffer text. - -Even if @var{update} is non-@code{nil}, @code{window-end} does not -attempt to scroll the display if point has moved off the screen, the -way real redisplay would do. It does not alter the -@code{window-start} value. In effect, it reports where the displayed -text will end if scrolling is not required. -@end defun - -@defun set-window-start window position &optional noforce -This function sets the display-start position of @var{window} to -@var{position} in @var{window}'s buffer. It returns @var{position}. - -The display routines insist that the position of point be visible when a -buffer is displayed. Normally, they change the display-start position -(that is, scroll the window) whenever necessary to make point visible. -However, if you specify the start position with this function using -@code{nil} for @var{noforce}, it means you want display to start at -@var{position} even if that would put the location of point off the -screen. If this does place point off screen, the display routines move -point to the left margin on the middle line in the window. - -For example, if point @w{is 1} and you set the start of the window -@w{to 37}, the start of the next line, point will be ``above'' the top -of the window. The display routines will automatically move point if -it is still 1 when redisplay occurs. Here is an example: - -@example -@group -;; @r{Here is what @samp{foo} looks like before executing} -;; @r{the @code{set-window-start} expression.} -@end group - -@group ----------- Buffer: foo ---------- -@point{}This is the contents of buffer foo. -2 -3 -4 -5 -6 ----------- Buffer: foo ---------- -@end group - -@group -(set-window-start - (selected-window) - (save-excursion - (goto-char 1) - (forward-line 1) - (point))) -@result{} 37 -@end group - -@group -;; @r{Here is what @samp{foo} looks like after executing} -;; @r{the @code{set-window-start} expression.} ----------- Buffer: foo ---------- -2 -3 -@point{}4 -5 -6 ----------- Buffer: foo ---------- -@end group -@end example - -If @var{noforce} is non-@code{nil}, and @var{position} would place point -off screen at the next redisplay, then redisplay computes a new window-start -position that works well with point, and thus @var{position} is not used. -@end defun - -@defun pos-visible-in-window-p &optional position window partially -This function returns non-@code{nil} if @var{position} is within the -range of text currently visible on the screen in @var{window}. It -returns @code{nil} if @var{position} is scrolled vertically out of view. -Locations that are partially obscured are not considered visible unless -@var{partially} is non-@code{nil}. The argument @var{position} defaults -to the current position of point in @var{window}; @var{window}, to the -selected window. If @var{position} is @code{t}, that means to check the -last visible position in @var{window}. - -This function considers only vertical scrolling. If @var{position} is -out of view only because @var{window} has been scrolled horizontally, -@code{pos-visible-in-window-p} returns non-@code{nil} anyway. -@xref{Horizontal Scrolling}. - -If @var{position} is visible, @code{pos-visible-in-window-p} returns -@code{t} if @var{partially} is @code{nil}; if @var{partially} is -non-@code{nil}, and the character following @var{position} is fully -visible, it returns a list of the form @code{(@var{x} @var{y})}, where -@var{x} and @var{y} are the pixel coordinates relative to the top left -corner of the window; otherwise it returns an extended list of the form -@code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})}, -where @var{rtop} and @var{rbot} specify the number of off-window pixels -at the top and bottom of the row at @var{position}, @var{rowh} specifies -the visible height of that row, and @var{vpos} specifies the vertical -position (zero-based row number) of that row. - -Here is an example: - -@example -@group -;; @r{If point is off the screen now, recenter it now.} -(or (pos-visible-in-window-p - (point) (selected-window)) - (recenter 0)) -@end group -@end example -@end defun - -@defun window-line-height &optional line window -This function returns the height of text line @var{line} in -@var{window}. If @var{line} is one of @code{header-line} or -@code{mode-line}, @code{window-line-height} returns information about -the corresponding line of the window. Otherwise, @var{line} is a text -line number starting from 0. A negative number counts from the end of -the window. The default for @var{line} is the current line in -@var{window}; the default for @var{window} is the selected window. - -If the display is not up to date, @code{window-line-height} returns -@code{nil}. In that case, @code{pos-visible-in-window-p} may be used -to obtain related information. - -If there is no line corresponding to the specified @var{line}, -@code{window-line-height} returns @code{nil}. Otherwise, it returns -a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})}, -where @var{height} is the height in pixels of the visible part of the -line, @var{vpos} and @var{ypos} are the vertical position in lines and -pixels of the line relative to the top of the first text line, and -@var{offbot} is the number of off-window pixels at the bottom of the -text line. If there are off-window pixels at the top of the (first) -text line, @var{ypos} is negative. -@end defun - -@node Textual Scrolling -@section Textual Scrolling -@cindex textual scrolling -@cindex scrolling textually - - @dfn{Textual scrolling} means moving the text up or down through a -window. It works by changing the window's display-start location. It -may also change the value of @code{window-point} to keep point on the -screen (@pxref{Window Point}). - - The basic textual scrolling functions are @code{scroll-up} (which -scrolls forward) and @code{scroll-down} (which scrolls backward). In -these function names, ``up'' and ``down'' refer to the direction of -motion of the buffer text relative to the window. Imagine that the -text is written on a long roll of paper and that the scrolling -commands move the paper up and down. Thus, if you are looking at the -middle of a buffer and repeatedly call @code{scroll-down}, you will -eventually see the beginning of the buffer. - - Unfortunately, this sometimes causes confusion, because some people -tend to think in terms of the opposite convention: they -imagine the window moving over text that remains in place, so that -``down'' commands take you to the end of the buffer. This convention -is consistent with fact that such a command is bound to a key named -@key{PageDown} on modern keyboards. -@ignore -We have not switched to this convention as that is likely to break -existing Emacs Lisp code. -@end ignore - - Textual scrolling functions (aside from @code{scroll-other-window}) -have unpredictable results if the current buffer is not the one -displayed in the selected window. @xref{Current Buffer}. - - If the window contains a row taller than the height of the window -(for example in the presence of a large image), the scroll functions -will adjust the window's vertical scroll position to scroll the -partially visible row. Lisp callers can disable this feature by -binding the variable @code{auto-window-vscroll} to @code{nil} -(@pxref{Vertical Scrolling}). - -@deffn Command scroll-up &optional count -This function scrolls forward by @var{count} lines in the selected -window. - -If @var{count} is negative, it scrolls backward instead. If -@var{count} is @code{nil} (or omitted), the distance scrolled is -@code{next-screen-context-lines} lines less than the height of the -window's text area. - -If the selected window cannot be scrolled any further, this function -signals an error. Otherwise, it returns @code{nil}. -@end deffn - -@deffn Command scroll-down &optional count -This function scrolls backward by @var{count} lines in the selected -window. - -If @var{count} is negative, it scrolls forward instead. In other -respects, it behaves the same way as @code{scroll-up} does. -@end deffn - -@deffn Command scroll-up-command &optional count -This behaves like @code{scroll-up}, except that if the selected window -cannot be scrolled any further and the value of the variable -@code{scroll-error-top-bottom} is @code{t}, it tries to move to the -end of the buffer instead. If point is already there, it signals an -error. -@end deffn - -@deffn Command scroll-down-command &optional count -This behaves like @code{scroll-down}, except that if the selected -window cannot be scrolled any further and the value of the variable -@code{scroll-error-top-bottom} is @code{t}, it tries to move to the -beginning of the buffer instead. If point is already there, it -signals an error. -@end deffn - -@deffn Command scroll-other-window &optional count -This function scrolls the text in another window upward @var{count} -lines. Negative values of @var{count}, or @code{nil}, are handled -as in @code{scroll-up}. - -You can specify which buffer to scroll by setting the variable -@code{other-window-scroll-buffer} to a buffer. If that buffer isn't -already displayed, @code{scroll-other-window} displays it in some -window. - -When the selected window is the minibuffer, the next window is normally -the leftmost one immediately above it. You can specify a different -window to scroll, when the minibuffer is selected, by setting the variable -@code{minibuffer-scroll-window}. This variable has no effect when any -other window is selected. When it is non-@code{nil} and the -minibuffer is selected, it takes precedence over -@code{other-window-scroll-buffer}. @xref{Definition of -minibuffer-scroll-window}. - -When the minibuffer is active, it is the next window if the selected -window is the one at the bottom right corner. In this case, -@code{scroll-other-window} attempts to scroll the minibuffer. If the -minibuffer contains just one line, it has nowhere to scroll to, so the -line reappears after the echo area momentarily displays the message -@samp{End of buffer}. -@end deffn - -@defvar other-window-scroll-buffer -If this variable is non-@code{nil}, it tells @code{scroll-other-window} -which buffer's window to scroll. -@end defvar - -@defopt scroll-margin -This option specifies the size of the scroll margin---a minimum number -of lines between point and the top or bottom of a window. Whenever -point gets within this many lines of the top or bottom of the window, -redisplay scrolls the text automatically (if possible) to move point -out of the margin, closer to the center of the window. -@end defopt - -@defopt scroll-conservatively -This variable controls how scrolling is done automatically when point -moves off the screen (or into the scroll margin). If the value is a -positive integer @var{n}, then redisplay scrolls the text up to -@var{n} lines in either direction, if that will bring point back into -proper view. This behavior is called @dfn{conservative scrolling}. -Otherwise, scrolling happens in the usual way, under the control of -other variables such as @code{scroll-up-aggressively} and -@code{scroll-down-aggressively}. - -The default value is zero, which means that conservative scrolling -never happens. -@end defopt - -@defopt scroll-down-aggressively -The value of this variable should be either @code{nil} or a fraction -@var{f} between 0 and 1. If it is a fraction, that specifies where on -the screen to put point when scrolling down. More precisely, when a -window scrolls down because point is above the window start, the new -start position is chosen to put point @var{f} part of the window -height from the top. The larger @var{f}, the more aggressive the -scrolling. - -A value of @code{nil} is equivalent to .5, since its effect is to center -point. This variable automatically becomes buffer-local when set in any -fashion. -@end defopt - -@defopt scroll-up-aggressively -Likewise, for scrolling up. The value, @var{f}, specifies how far -point should be placed from the bottom of the window; thus, as with -@code{scroll-up-aggressively}, a larger value scrolls more aggressively. -@end defopt - -@defopt scroll-step -This variable is an older variant of @code{scroll-conservatively}. -The difference is that if its value is @var{n}, that permits scrolling -only by precisely @var{n} lines, not a smaller number. This feature -does not work with @code{scroll-margin}. The default value is zero. -@end defopt - -@cindex @code{scroll-command} property -@defopt scroll-preserve-screen-position -If this option is @code{t}, whenever a scrolling command moves point -off-window, Emacs tries to adjust point to keep the cursor at its old -vertical position in the window, rather than the window edge. - -If the value is non-@code{nil} and not @code{t}, Emacs adjusts point -to keep the cursor at the same vertical position, even if the -scrolling command didn't move point off-window. - -This option affects all scroll commands that have a non-@code{nil} -@code{scroll-command} symbol property. -@end defopt - -@defopt next-screen-context-lines -The value of this variable is the number of lines of continuity to -retain when scrolling by full screens. For example, @code{scroll-up} -with an argument of @code{nil} scrolls so that this many lines at the -bottom of the window appear instead at the top. The default value is -@code{2}. -@end defopt - -@defopt scroll-error-top-bottom -If this option is @code{nil} (the default), @code{scroll-up-command} -and @code{scroll-down-command} simply signal an error when no more -scrolling is possible. - -If the value is @code{t}, these commands instead move point to the -beginning or end of the buffer (depending on scrolling direction); -only if point is already on that position do they signal an error. -@end defopt - -@deffn Command recenter &optional count -@cindex centering point -This function scrolls the text in the selected window so that point is -displayed at a specified vertical position within the window. It does -not ``move point'' with respect to the text. - -If @var{count} is a non-negative number, that puts the line containing -point @var{count} lines down from the top of the window. If -@var{count} is a negative number, then it counts upward from the -bottom of the window, so that @minus{}1 stands for the last usable -line in the window. - -If @var{count} is @code{nil} (or a non-@code{nil} list), -@code{recenter} puts the line containing point in the middle of the -window. If @var{count} is @code{nil}, this function may redraw the -frame, according to the value of @code{recenter-redisplay}. - -When @code{recenter} is called interactively, @var{count} is the raw -prefix argument. Thus, typing @kbd{C-u} as the prefix sets the -@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets -@var{count} to 4, which positions the current line four lines from the -top. - -With an argument of zero, @code{recenter} positions the current line at -the top of the window. The command @code{recenter-top-bottom} offers -a more convenient way to achieve this. -@end deffn - -@defopt recenter-redisplay -If this variable is non-@code{nil}, calling @code{recenter} with a -@code{nil} argument redraws the frame. The default value is -@code{tty}, which means only redraw the frame if it is a tty frame. -@end defopt - -@deffn Command recenter-top-bottom &optional count -This command, which is the default binding for @kbd{C-l}, acts like -@code{recenter}, except if called with no argument. In that case, -successive calls place point according to the cycling order defined -by the variable @code{recenter-positions}. -@end deffn - -@defopt recenter-positions -This variable controls how @code{recenter-top-bottom} behaves when -called with no argument. The default value is @code{(middle top -bottom)}, which means that successive calls of -@code{recenter-top-bottom} with no argument cycle between placing -point at the middle, top, and bottom of the window. -@end defopt - - -@node Vertical Scrolling -@section Vertical Fractional Scrolling -@cindex vertical fractional scrolling -@cindex vertical scroll position - - @dfn{Vertical fractional scrolling} means shifting text in a window -up or down by a specified multiple or fraction of a line. Each window -has a @dfn{vertical scroll position}, which is a number, never less than -zero. It specifies how far to raise the contents of the window. -Raising the window contents generally makes all or part of some lines -disappear off the top, and all or part of some other lines appear at the -bottom. The usual value is zero. - - The vertical scroll position is measured in units of the normal line -height, which is the height of the default font. Thus, if the value is -.5, that means the window contents are scrolled up half the normal line -height. If it is 3.3, that means the window contents are scrolled up -somewhat over three times the normal line height. - - What fraction of a line the vertical scrolling covers, or how many -lines, depends on what the lines contain. A value of .5 could scroll a -line whose height is very short off the screen, while a value of 3.3 -could scroll just part of the way through a tall line or an image. - -@defun window-vscroll &optional window pixels-p -This function returns the current vertical scroll position of -@var{window}. The default for @var{window} is the selected window. -If @var{pixels-p} is non-@code{nil}, the return value is measured in -pixels, rather than in units of the normal line height. - -@example -@group -(window-vscroll) - @result{} 0 -@end group -@end example -@end defun - -@defun set-window-vscroll window lines &optional pixels-p -This function sets @var{window}'s vertical scroll position to -@var{lines}. If @var{window} is @code{nil}, the selected window is -used. The argument @var{lines} should be zero or positive; if not, it -is taken as zero. - - -The actual vertical scroll position must always correspond -to an integral number of pixels, so the value you specify -is rounded accordingly. - -The return value is the result of this rounding. - -@example -@group -(set-window-vscroll (selected-window) 1.2) - @result{} 1.13 -@end group -@end example - -If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of -pixels. In this case, the return value is @var{lines}. -@end defun - -@defvar auto-window-vscroll -If this variable is non-@code{nil}, the line-move, scroll-up, and -scroll-down functions will automatically modify the vertical scroll -position to scroll through display rows that are taller than the height -of the window, for example in the presence of large images. -@end defvar - -@node Horizontal Scrolling -@section Horizontal Scrolling -@cindex horizontal scrolling - - @dfn{Horizontal scrolling} means shifting the image in the window left -or right by a specified multiple of the normal character width. Each -window has a @dfn{horizontal scroll position}, which is a number, never -less than zero. It specifies how far to shift the contents left. -Shifting the window contents left generally makes all or part of some -characters disappear off the left, and all or part of some other -characters appear at the right. The usual value is zero. - - The horizontal scroll position is measured in units of the normal -character width, which is the width of space in the default font. Thus, -if the value is 5, that means the window contents are scrolled left by 5 -times the normal character width. How many characters actually -disappear off to the left depends on their width, and could vary from -line to line. - - Because we read from side to side in the ``inner loop'', and from top -to bottom in the ``outer loop'', the effect of horizontal scrolling is -not like that of textual or vertical scrolling. Textual scrolling -involves selection of a portion of text to display, and vertical -scrolling moves the window contents contiguously; but horizontal -scrolling causes part of @emph{each line} to go off screen. - - Usually, no horizontal scrolling is in effect; then the leftmost -column is at the left edge of the window. In this state, scrolling to -the right is meaningless, since there is no data to the left of the edge -to be revealed by it; so this is not allowed. Scrolling to the left is -allowed; it scrolls the first columns of text off the edge of the window -and can reveal additional columns on the right that were truncated -before. Once a window has a nonzero amount of leftward horizontal -scrolling, you can scroll it back to the right, but only so far as to -reduce the net horizontal scroll to zero. There is no limit to how far -left you can scroll, but eventually all the text will disappear off the -left edge. - -@vindex auto-hscroll-mode - If @code{auto-hscroll-mode} is set, redisplay automatically alters -the horizontal scrolling of a window as necessary to ensure that point -is always visible. However, you can still set the horizontal -scrolling value explicitly. The value you specify serves as a lower -bound for automatic scrolling, i.e. automatic scrolling will not -scroll a window to a column less than the specified one. - -@deffn Command scroll-left &optional count set-minimum -This function scrolls the selected window @var{count} columns to the -left (or to the right if @var{count} is negative). The default -for @var{count} is the window width, minus 2. - -The return value is the total amount of leftward horizontal scrolling in -effect after the change---just like the value returned by -@code{window-hscroll} (below). - -Once you scroll a window as far right as it can go, back to its normal -position where the total leftward scrolling is zero, attempts to scroll -any farther right have no effect. - -If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes -the lower bound for automatic scrolling; that is, automatic scrolling -will not scroll a window to a column less than the value returned by -this function. Interactive calls pass non-@code{nil} for -@var{set-minimum}. -@end deffn - -@deffn Command scroll-right &optional count set-minimum -This function scrolls the selected window @var{count} columns to the -right (or to the left if @var{count} is negative). The default -for @var{count} is the window width, minus 2. Aside from the direction -of scrolling, this works just like @code{scroll-left}. -@end deffn - -@defun window-hscroll &optional window -This function returns the total leftward horizontal scrolling of -@var{window}---the number of columns by which the text in @var{window} -is scrolled left past the left margin. The default for -@var{window} is the selected window. - -The return value is never negative. It is zero when no horizontal -scrolling has been done in @var{window} (which is usually the case). - - -@example -@group -(window-hscroll) - @result{} 0 -@end group -@group -(scroll-left 5) - @result{} 5 -@end group -@group -(window-hscroll) - @result{} 5 -@end group -@end example -@end defun - -@defun set-window-hscroll window columns -This function sets horizontal scrolling of @var{window}. The value of -@var{columns} specifies the amount of scrolling, in terms of columns -from the left margin. The argument @var{columns} should be zero or -positive; if not, it is taken as zero. Fractional values of -@var{columns} are not supported at present. - -Note that @code{set-window-hscroll} may appear not to work if you test -it by evaluating a call with @kbd{M-:} in a simple way. What happens -is that the function sets the horizontal scroll value and returns, but -then redisplay adjusts the horizontal scrolling to make point visible, -and this overrides what the function did. You can observe the -function's effect if you call it while point is sufficiently far from -the left margin that it will remain visible. - -The value returned is @var{columns}. - -@example -@group -(set-window-hscroll (selected-window) 10) - @result{} 10 -@end group -@end example -@end defun - - Here is how you can determine whether a given position @var{position} -is off the screen due to horizontal scrolling: - -@example -@group -(defun hscroll-on-screen (window position) - (save-excursion - (goto-char position) - (and - (>= (- (current-column) (window-hscroll window)) 0) - (< (- (current-column) (window-hscroll window)) - (window-width window))))) -@end group -@end example - -@node Coordinates and Windows -@section Coordinates and Windows -@cindex frame-relative coordinate -@cindex coordinate, relative to frame -@cindex window position - - This section describes functions that report the position of a -window. Most of these functions report positions relative to the -window's frame. In this case, the coordinate origin @samp{(0,0)} lies -near the upper left corner of the frame. For technical reasons, on -graphical displays the origin is not located at the exact corner of -the graphical window as it appears on the screen. If Emacs is built -with the GTK+ toolkit, the origin is at the upper left corner of the -frame area used for displaying Emacs windows, below the title-bar, -GTK+ menu bar, and tool bar (since these are drawn by the window -manager and/or GTK+, not by Emacs). But if Emacs is not built with -GTK+, the origin is at the upper left corner of the tool bar (since in -this case Emacs itself draws the tool bar). In both cases, the X and -Y coordinates increase rightward and downward respectively. - - Except where noted, X and Y coordinates are reported in integer -character units, i.e. numbers of lines and columns respectively. On a -graphical display, each ``line'' and ``column'' corresponds to the -height and width of a default character specified by the frame's -default font. - -@defun window-edges &optional window -This function returns a list of the edge coordinates of @var{window}. -If @var{window} is omitted or @code{nil}, it defaults to the selected -window. - -The return value has the form @code{(@var{left} @var{top} @var{right} -@var{bottom})}. These list elements are, respectively, the X -coordinate of the leftmost column occupied by the window, the Y -coordinate of the topmost row, the X coordinate one column to the -right of the rightmost column, and the Y coordinate one row down from -the bottommost row. - -Note that these are the actual outer edges of the window, including -any header line, mode line, scroll bar, fringes, and display margins. -On a text terminal, if the window has a neighbor on its right, its -right edge includes the separator line between the window and its -neighbor. -@end defun - -@defun window-inside-edges &optional window -This function is similar to @code{window-edges}, but the returned edge -values are for the text area of the window. They exclude any header -line, mode line, scroll bar, fringes, display margins, and vertical -separator. -@end defun - -@defun window-top-line &optional window -This function returns the Y coordinate of the topmost row of -@var{window}, equivalent to the @var{top} entry in the list returned -by @code{window-edges}. -@end defun - -@defun window-left-column &optional window -This function returns the X coordinate of the leftmost column of -@var{window}, equivalent to the @var{left} entry in the list returned -by @code{window-edges}. -@end defun - - The following functions can be used to relate a set of -frame-relative coordinates to a window: - -@defun window-at x y &optional frame -This function returns the live window at the frame-relative -coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no -window at that position, the return value is @code{nil}. If -@var{frame} is omitted or @code{nil}, it defaults to the selected -frame. -@end defun - -@defun coordinates-in-window-p coordinates window -This function checks whether a window @var{window} occupies the -frame-relative coordinates @var{coordinates}, and if so, which part of -the window that is. @var{window} should be a live window. -@var{coordinates} should be a cons cell of the form @code{(@var{x} -. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates. - -If there is no window at the specified position, the return value is -@code{nil} . Otherwise, the return value is one of the following: - -@table @code -@item (@var{relx} . @var{rely}) -The coordinates are inside @var{window}. The numbers @var{relx} and -@var{rely} are the equivalent window-relative coordinates for the -specified position, counting from 0 at the top left corner of the -window. - -@item mode-line -The coordinates are in the mode line of @var{window}. - -@item header-line -The coordinates are in the header line of @var{window}. - -@item vertical-line -The coordinates are in the vertical line between @var{window} and its -neighbor to the right. This value occurs only if the window doesn't -have a scroll bar; positions in a scroll bar are considered outside the -window for these purposes. - -@item left-fringe -@itemx right-fringe -The coordinates are in the left or right fringe of the window. - -@item left-margin -@itemx right-margin -The coordinates are in the left or right margin of the window. - -@item nil -The coordinates are not in any part of @var{window}. -@end table - -The function @code{coordinates-in-window-p} does not require a frame as -argument because it always uses the frame that @var{window} is on. -@end defun - - The following functions return window positions in pixels, rather -than character units. Though mostly useful on graphical displays, -they can also be called on text terminals, where the screen area of -each text character is taken to be ``one pixel''. - -@defun window-pixel-edges &optional window -This function returns a list of pixel coordinates for the edges of -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. - -The return value has the form @code{(@var{left} @var{top} @var{right} -@var{bottom})}. The list elements are, respectively, the X pixel -coordinate of the left window edge, the Y pixel coordinate of the top -edge, one more than the X pixel coordinate of the right edge, and one -more than the Y pixel coordinate of the bottom edge. -@end defun - -@defun window-inside-pixel-edges &optional window -This function is like @code{window-pixel-edges}, except that it -returns the pixel coordinates for the edges of the window's text area, -rather than the pixel coordinates for the edges of the window itself. -@var{window} must specify a live window. -@end defun - - The following functions return window positions in pixels, relative -to the display screen rather than the frame: - -@defun window-absolute-pixel-edges &optional window -This function is like @code{window-pixel-edges}, except that it -returns the edge pixel coordinates relative to the top left corner of -the display screen. -@end defun - -@defun window-inside-absolute-pixel-edges &optional window -This function is like @code{window-inside-pixel-edges}, except that it -returns the edge pixel coordinates relative to the top left corner of -the display screen. @var{window} must specify a live window. -@end defun - -@node Window Configurations -@section Window Configurations -@cindex window configurations -@cindex saving window information - -A @dfn{window configuration} records the entire layout of one -frame---all windows, their sizes, which buffers they contain, how those -buffers are scrolled, and their values of point and the mark; also their -fringes, margins, and scroll bar settings. It also includes the value -of @code{minibuffer-scroll-window}. As a special exception, the window -configuration does not record the value of point in the selected window -for the current buffer. - - You can bring back an entire frame layout by restoring a previously -saved window configuration. If you want to record the layout of all -frames instead of just one, use a frame configuration instead of a -window configuration. @xref{Frame Configurations}. - -@defun current-window-configuration &optional frame -This function returns a new object representing @var{frame}'s current -window configuration. The default for @var{frame} is the selected -frame. The variable @code{window-persistent-parameters} specifies -which window parameters (if any) are saved by this function. -@xref{Window Parameters}. -@end defun - -@defun set-window-configuration configuration -This function restores the configuration of windows and buffers as -specified by @var{configuration}, for the frame that @var{configuration} -was created for. - -The argument @var{configuration} must be a value that was previously -returned by @code{current-window-configuration}. The configuration is -restored in the frame from which @var{configuration} was made, whether -that frame is selected or not. This always counts as a window size -change and triggers execution of the @code{window-size-change-functions} -(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't -know how to tell whether the new configuration actually differs from the -old one. - -If the frame from which @var{configuration} was saved is dead, all this -function does is restore the three variables @code{window-min-height}, -@code{window-min-width} and @code{minibuffer-scroll-window}. In this -case, the function returns @code{nil}. Otherwise, it returns @code{t}. - -Here is a way of using this function to get the same effect -as @code{save-window-excursion}: - -@example -@group -(let ((config (current-window-configuration))) - (unwind-protect - (progn (split-window-below nil) - @dots{}) - (set-window-configuration config))) -@end group -@end example -@end defun - -@defmac save-window-excursion forms@dots{} -This special form records the window configuration, executes @var{forms} -in sequence, then restores the earlier window configuration. The window -configuration includes, for each window, the value of point and the -portion of the buffer that is visible. It also includes the choice of -selected window. However, it does not include the value of point in -the current buffer; use @code{save-excursion} also, if you wish to -preserve that. - -Don't use this construct when @code{save-selected-window} is sufficient. - -Exit from @code{save-window-excursion} always triggers execution of -@code{window-size-change-functions}. (It doesn't know how to tell -whether the restored configuration actually differs from the one in -effect at the end of the @var{forms}.) - -The return value is the value of the final form in @var{forms}. -For example: - -@example -@group -(split-window) - @result{} # -@end group -@group -(setq w (selected-window)) - @result{} # -@end group -@group -(save-window-excursion - (delete-other-windows w) - (switch-to-buffer "foo") - 'do-something) - @result{} do-something - ;; @r{The screen is now split again.} -@end group -@end example -@end defmac - -@defun window-configuration-p object -This function returns @code{t} if @var{object} is a window configuration. -@end defun - -@defun compare-window-configurations config1 config2 -This function compares two window configurations as regards the -structure of windows, but ignores the values of point and mark and the -saved scrolling positions---it can return @code{t} even if those -aspects differ. - -The function @code{equal} can also compare two window configurations; it -regards configurations as unequal if they differ in any respect, even a -saved point or mark. -@end defun - -@defun window-configuration-frame config -This function returns the frame for which the window configuration -@var{config} was made. -@end defun - - Other primitives to look inside of window configurations would make -sense, but are not implemented because we did not need them. See the -file @file{winner.el} for some more operations on windows -configurations. - - The objects returned by @code{current-window-configuration} die -together with the Emacs process. In order to store a window -configuration on disk and read it back in another Emacs session, you -can use the functions described next. These functions are also useful -to clone the state of a frame into an arbitrary live window -(@code{set-window-configuration} effectively clones the windows of a -frame into the root window of that very frame only). - -@defun window-state-get &optional window writable -This function returns the state of @var{window} as a Lisp object. The -argument @var{window} can be any window and defaults to the root window -of the selected frame. - -If the optional argument @var{writable} is non-@code{nil}, this means to -not use markers for sampling positions like @code{window-point} or -@code{window-start}. This argument should be non-@code{nil} when the -state will be written to disk and read back in another session. - -Together, the argument @var{writable} and the variable -@code{window-persistent-parameters} specify which window parameters are -saved by this function. @xref{Window Parameters}. -@end defun - -The value returned by @code{window-state-get} can be used in the same -session to make a clone of a window in another window. It can be also -written to disk and read back in another session. In either case, use -the following function to restore the state of the window. - -@defun window-state-put state &optional window ignore -This function puts the window state @var{state} into @var{window}. The -argument @var{state} should be the state of a window returned by an -earlier invocation of @code{window-state-get}, see above. The optional -argument @var{window} must specify a live window and defaults to the -selected one. - -If the optional argument @var{ignore} is non-@code{nil}, it means to ignore -minimum window sizes and fixed-size restrictions. If @var{ignore} -is @code{safe}, this means windows can get as small as one line -and/or two columns. -@end defun - - -@node Window Parameters -@section Window Parameters -@cindex window parameters - -This section describes how window parameters can be used to associate -additional information with windows. - -@defun window-parameter window parameter -This function returns @var{window}'s value for @var{parameter}. The -default for @var{window} is the selected window. If @var{window} has no -setting for @var{parameter}, this function returns @code{nil}. -@end defun - -@defun window-parameters &optional window -This function returns all parameters of @var{window} and their values. -The default for @var{window} is the selected window. The return value -is either @code{nil}, or an association list whose elements have the form -@code{(@var{parameter} . @var{value})}. -@end defun - -@defun set-window-parameter window parameter value -This function sets @var{window}'s value of @var{parameter} to -@var{value} and returns @var{value}. The default for @var{window} -is the selected window. -@end defun - -By default, the functions that save and restore window configurations or the -states of windows (@pxref{Window Configurations}) do not care about -window parameters. This means that when you change the value of a -parameter within the body of a @code{save-window-excursion}, the -previous value is not restored when that macro exits. It also means -that when you restore via @code{window-state-put} a window state saved -earlier by @code{window-state-get}, all cloned windows have their -parameters reset to @code{nil}. The following variable allows you to -override the standard behavior: - -@defvar window-persistent-parameters -This variable is an alist specifying which parameters get saved by -@code{current-window-configuration} and @code{window-state-get}, and -subsequently restored by @code{set-window-configuration} and -@code{window-state-put}. @xref{Window Configurations}. - -The @sc{car} of each entry of this alist is a symbol specifying the -parameter. The @sc{cdr} should be one of the following: - -@table @asis -@item @code{nil} -This value means the parameter is saved neither by -@code{window-state-get} nor by @code{current-window-configuration}. - -@item @code{t} -This value specifies that the parameter is saved by -@code{current-window-configuration} and (provided its @var{writable} -argument is @code{nil}) by @code{window-state-get}. - -@item @code{writable} -This means that the parameter is saved unconditionally by both -@code{current-window-configuration} and @code{window-state-get}. This -value should not be used for parameters whose values do not have a read -syntax. Otherwise, invoking @code{window-state-put} in another session -may fail with an @code{invalid-read-syntax} error. -@end table -@end defvar - -Some functions (notably @code{delete-window}, -@code{delete-other-windows} and @code{split-window}), may behave specially -when their @var{window} argument has a parameter set. You can override -such special behavior by binding the following variable to a -non-@code{nil} value: - -@defvar ignore-window-parameters -If this variable is non-@code{nil}, some standard functions do not -process window parameters. The functions currently affected by this are -@code{split-window}, @code{delete-window}, @code{delete-other-windows}, -and @code{other-window}. - -An application can bind this variable to a non-@code{nil} value around -calls to these functions. If it does so, the application is fully -responsible for correctly assigning the parameters of all involved -windows when exiting that function. -@end defvar - -The following parameters are currently used by the window management -code: - -@table @asis -@item @code{delete-window} -This parameter affects the execution of @code{delete-window} -(@pxref{Deleting Windows}). - -@item @code{delete-other-windows} -This parameter affects the execution of @code{delete-other-windows} -(@pxref{Deleting Windows}). - -@item @code{split-window} -This parameter affects the execution of @code{split-window} -(@pxref{Splitting Windows}). - -@item @code{other-window} -This parameter affects the execution of @code{other-window} -(@pxref{Cyclic Window Ordering}). - -@item @code{no-other-window} -This parameter marks the window as not selectable by @code{other-window} -(@pxref{Cyclic Window Ordering}). - -@item @code{clone-of} -This parameter specifies the window that this one has been cloned -from. It is installed by @code{window-state-get} (@pxref{Window -Configurations}). - -@item @code{quit-restore} -This parameter specifies what to do with a window when the buffer it -shows is not needed any more. It is installed by the buffer display -functions (@pxref{Choosing Window}), and consulted by the function -@code{quit-window} (@pxref{Quitting Windows}). -@end table - -There are additional parameters @code{window-atom} and @code{window-side}; -these are reserved and should not be used by applications. - - -@node Window Hooks -@section Hooks for Window Scrolling and Changes -@cindex hooks for window operations - -This section describes how a Lisp program can take action whenever a -window displays a different part of its buffer or a different buffer. -There are three actions that can change this: scrolling the window, -switching buffers in the window, and changing the size of the window. -The first two actions run @code{window-scroll-functions}; the last runs -@code{window-size-change-functions}. - -@defvar window-scroll-functions -This variable holds a list of functions that Emacs should call before -redisplaying a window with scrolling. Displaying a different buffer in -the window also runs these functions. - -This variable is not a normal hook, because each function is called with -two arguments: the window, and its new display-start position. - -These functions must take care when using @code{window-end} -(@pxref{Window Start and End}); if you need an up-to-date value, you -must use the @var{update} argument to ensure you get it. - -@strong{Warning:} don't use this feature to alter the way the window -is scrolled. It's not designed for that, and such use probably won't -work. -@end defvar - -@defvar window-size-change-functions -This variable holds a list of functions to be called if the size of any -window changes for any reason. The functions are called just once per -redisplay, and just once for each frame on which size changes have -occurred. - -Each function receives the frame as its sole argument. There is no -direct way to find out which windows on that frame have changed size, or -precisely how. However, if a size-change function records, at each -call, the existing windows and their sizes, it can also compare the -present sizes and the previous sizes. - -Creating or deleting windows counts as a size change, and therefore -causes these functions to be called. Changing the frame size also -counts, because it changes the sizes of the existing windows. - -It is not a good idea to use @code{save-window-excursion} (@pxref{Window -Configurations}) in these functions, because that always counts as a -size change, and it would cause these functions to be called over and -over. In most cases, @code{save-selected-window} (@pxref{Selecting -Windows}) is what you need here. -@end defvar - -@defvar window-configuration-change-hook -A normal hook that is run every time you change the window configuration -of an existing frame. This includes splitting or deleting windows, -changing the sizes of windows, or displaying a different buffer in a -window. - -The buffer-local part of this hook is run once for each window on the -affected frame, with the relevant window selected and its buffer -current. The global part is run once for the modified frame, with that -frame selected. -@end defvar - - In addition, you can use @code{jit-lock-register} to register a Font -Lock fontification function, which will be called whenever parts of a -buffer are (re)fontified because a window was scrolled or its size -changed. @xref{Other Font Lock Variables}. diff --git a/doc/misc/ada-mode.texi b/doc/misc/ada-mode.texi deleted file mode 100644 index 8d06ae0de22..00000000000 --- a/doc/misc/ada-mode.texi +++ /dev/null @@ -1,1526 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/ada-mode -@settitle Ada Mode - -@copying -Copyright @copyright{} 1999-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs editing modes -@direntry -* Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code. -@end direntry - -@titlepage -@sp 10 -@title{Ada Mode} -@sp 2 -@subtitle An Emacs major mode for programming in Ada -@subtitle Ada Mode Version 4.00 -@sp 2 -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top, Overview, (dir), (dir) -@top Ada Mode - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: -* Installation:: Installing Ada mode on your system -* Customization:: Setting up Ada mode to your taste -* Compiling Executing:: Working with your application within Emacs -* Project files:: Describing the organization of your project -* Compiling Examples:: A small tutorial -* Moving Through Ada Code:: Moving easily through Ada sources -* Identifier completion:: Finishing words automatically -* Automatic Smart Indentation:: Indenting your code automatically as you type -* Formatting Parameter Lists:: Formatting subprograms' parameter lists - automatically -* Automatic Casing:: Adjusting the case of words automatically -* Statement Templates:: Inserting code templates -* Comment Handling:: Reformatting comments easily -* GNU Free Documentation License:: The license for this documentation. -* Index:: -@end menu - - -@node Overview, Installation, Top, Top -@chapter Overview - -The Emacs mode for programming in Ada helps the user in understanding -existing code and facilitates writing new code. - -When the Gnu Ada compiler GNAT is used, the cross-reference -information output by the compiler is used to provide powerful code -navigation (jump to definition, find all uses, etc). - -When you open a file with a file extension of @file{.ads} or -@file{.adb}, Emacs will automatically load and activate Ada mode. - -Ada mode works without any customization, if you are using the GNAT -compiler (@url{https://libre2.adacore.com/}) and the GNAT default -naming convention. - -You must customize a few things if you are using a different compiler -or file naming convention; @xref{Other compiler}, @xref{Non-standard -file names}. - -In addition, you may want to customize the indentation, -capitalization, and other things; @xref{Other customization}. - -Finally, for large Ada projects, you will want to set up an Emacs -Ada mode project file for each project; @xref{Project files}. Note -that these are different from the GNAT project files used by gnatmake -and other GNAT commands. - -See the Emacs info manual, section 'Running Debuggers Under Emacs', -for general information on debugging. - -@node Installation, Customization, Overview, Top -@chapter Installation - -Ada mode is part of the standard Emacs distribution; if you use that, -no files need to be installed. - -Ada mode is also available as a separate distribution, from the Emacs -Ada mode website -@uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. The -separate distribution may be more recent. - -For installing the separate distribution, see the @file{README} file -in the distribution. - -To see what version of Ada mode you have installed, do @kbd{M-x -ada-mode-version}. - -The following files are provided with the Ada mode distribution: - -@itemize @bullet - -@item -@file{ada-mode.el}: The main file for Ada mode, providing indentation, -formatting of parameter lists, moving through code, comment handling -and automatic casing. - -@item -@file{ada-prj.el}: GUI editing of Ada mode project files, using Emacs -widgets. - -@item -@file{ada-stmt.el}: Ada statement templates. - -@item -@file{ada-xref.el}: GNAT cross-references, completion of identifiers, -and compilation. Also provides project files (which are not -GNAT-specific). - -@end itemize - -@node Customization, Compiling Executing, Installation, Top -@chapter Customizing Ada mode - -Here we assume you are familiar with setting variables in Emacs, -either thru 'customize' or in elisp (in your @file{.emacs} file). For -a basic introduction to customize, elisp, and Emacs in general, see -the tutorial in -@iftex -@cite{The GNU Emacs Manual}. -@end iftex -@ifhtml -@cite{The GNU Emacs Manual}. -@end ifhtml -@ifinfo -@ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}. -@end ifinfo - -These global Emacs settings are strongly recommended (put them in your -.emacs): - -@example -(global-font-lock-mode t) -(transient-mark-mode t) -@end example - -@samp{(global-font-lock-mode t)} turns on syntax -highlighting for all buffers (it is off by default because it may be -too slow for some machines). - -@samp{(transient-mark-mode t)} highlights selected text. - -See the Emacs help for each of these variables for more information. - -@menu -* Non-standard file names:: -* Other compiler:: -* Other customization:: -@end menu - -@node Non-standard file names, Other compiler, Customization, Customization -@section Non-standard file names - -By default, Ada mode is configured to use the GNAT file naming -convention, where file names are a simple modification of the Ada -names, and the extension for specs and bodies are -@samp{.ads} and @samp{.adb}, respectively. - -Ada mode uses the file extensions to allow moving from a package body -to the corresponding spec and back. - -Ada mode supports a list of alternative file extensions for specs and bodies. - -For instance, if your spec and bodies files are called -@file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you -can add the following to your @file{.emacs} file: - -@example -(ada-add-extensions "_s.ada" "_b.ada") -@end example - -You can define additional extensions: - -@example -(ada-add-extensions ".ads" "_b.ada") -(ada-add-extensions ".ads" ".body") -@end example - -This means that whenever Ada mode looks for the body for a file -whose extension is @file{.ads}, it will take the first available file -that ends with either @file{.adb}, @file{_b.ada} or -@file{.body}. - -Similarly, if Ada mode is looking for a spec, it will look for -@file{.ads} or @file{_s.ada}. - -If the filename is not derived from the Ada name following the GNAT -convention, things are a little more complicated. You then need to -rewrite the function @code{ada-make-filename-from-adaname}. Doing that -is beyond the scope of this manual; see the current definitions in -@file{ada-mode.el} and @file{ada-xref.el} for examples. - -@node Other compiler, Other customization, Non-standard file names, Customization -@section Other compiler - -By default, Ada mode is configured to use the Gnu Ada compiler GNAT. - -To use a different Ada compiler, you must specify the command lines -used to run that compiler, either in lisp variables or in Emacs -Ada mode project files. See @ref{Project file variables} for the list -of project variables, and the corresponding lisp variables. - -@node Other customization, , Other compiler, Customization -@section Other customization - -All user-settable Ada mode variables can be set via the menu -@samp{Ada | Customize}. Click on the @samp{Help} button there for help -on using customize. - -To modify a specific variable, you can directly call the function -@code{customize-variable}; just type @kbd{M-x customize-variable -@key{RET} @var{variable-name} @key{RET}}). - -Alternately, you can specify variable settings in the Emacs -configuration file, @file{.emacs}. This file is coded in Emacs lisp, -and the syntax to set a variable is the following: -@example -(setq variable-name value) -@end example - -@node Compiling Executing, Project files, Customization, Top -@chapter Compiling Executing - -Ada projects can be compiled, linked, and executed using commands on -the Ada menu. All of these commands can be customized via a project -file (@pxref{Project files}), but the defaults are sufficient for using -the GNAT compiler for simple projects (single files, or several files -in a single directory). - -Even when no project file is used, the GUI project editor (menu -@samp{Ada | Project | Edit}) shows the settings of the various project -file variables referenced here. - -@menu -* Compile commands:: -* Compiler errors:: -@end menu - -@node Compile commands, Compiler errors, Compiling Executing, Compiling Executing -@section Compile commands - -Here are the commands for building and using an Ada project, as -listed in the Ada menu. - -In multi-file projects, there must be one file that is the main -program. That is given by the @code{main} project file variable; -it defaults to the current file if not yet set, but is also set by the -``set main and build'' command. - -@table @code - -@item Check file -Compiles the current file in syntax check mode, by running -@code{check_cmd} defined in the current project file. This typically -runs faster than full compile mode, speeding up finding and fixing -compilation errors. - -This sets @code{main} only if it has not been set yet. - -@item Compile file -Compiles the current file, by running @code{comp_cmd} from the current -project file. - -This does not set @code{main}. - -@item Set main and Build -Sets @code{main} to the current file, then executes the Build -command. - -@item Show main -Display @code{main} in the message buffer. - -@item Build -Compiles all obsolete units of the current @code{main}, and links -@code{main}, by running @code{make_cmd} from the current project. - -This sets @code{main} only if it has not been set yet. - -@item Run -Executes the main program in a shell, displayed in a separate Emacs -buffer. This runs @code{run_cmd} from the current project. The -execution buffer allows for interactive input/output. - -To modify the run command, in particular to provide or change the -command line arguments, type @kbd{C-u} before invoking the command. - -This command is not available for a cross-compilation toolchain. - -@end table -It is important when using these commands to understand how -@code{main} is used and changed. - -Build runs 'gnatmake' on the main unit. During a typical edit/compile -session, this is the only command you need to invoke, which is why it -is bound to @kbd{C-c C-c}. It will compile all files needed by the -main unit, and display compilation errors in any of them. - -Note that Build can be invoked from any Ada buffer; typically you will -be fixing errors in files other than the main, but you don't have to -switch back to the main to invoke the compiler again. - -Novices and students typically work on single-file Ada projects. In -this case, @kbd{C-c C-m} will normally be the only command needed; it -will build the current file, rather than the last-built main. - -There are three ways to change @code{main}: - -@enumerate -@item -Invoke @samp{Ada | Set main and Build}, which sets @code{main} to -the current file. - -@item -Invoke @samp{Ada | Project | Edit}, edit @code{main} and -@code{main}, and click @samp{[save]} - -@item -Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main} - -@end enumerate - -@node Compiler errors, , Compile commands, Compiling Executing -@section Compiler errors - -The @code{Check file}, @code{Compile file}, and @code{Build} commands -all place compilation errors in a separate buffer named -@code{*compilation*}. - -Each line in this buffer will become active: you can simply click on -it with the middle button of the mouse, or move point to it and press -@key{RET}. Emacs will then display the relevant source file and put -point on the line and column where the error was found. - -You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs -will jump to the first error. If you press that key again, it will -move you to the second error, and so on. - -Some error messages might also include references to other files. These -references are also clickable in the same way, or put point after the -line number and press @key{RET}. - -@node Project files, Compiling Examples, Compiling Executing, Top -@chapter Project files - -An Emacs Ada mode project file specifies what directories hold sources -for your project, and allows you to customize the compilation commands -and other things on a per-project basis. - -Note that Ada mode project files @samp{*.adp} are different than GNAT -compiler project files @samp{*.gpr}. However, Emacs Ada mode can use a -GNAT project file to specify the project directories. If no -other customization is needed, a GNAT project file can be used without -an Emacs Ada mode project file. - -@menu -* Project File Overview:: -* GUI Editor:: -* Project file variables:: -@end menu - -@node Project File Overview, GUI Editor, Project files, Project files -@section Project File Overview - -Project files have a simple syntax; they may be edited directly. Each -line specifies a project variable name and its value, separated by ``='': -@example -src_dir=/Projects/my_project/src_1 -src_dir=/Projects/my_project/src_2 -@end example - -Some variables (like @code{src_dir}) are lists; multiple occurrences -are concatenated. - -There must be no space between the variable name and ``='', and no -trailing spaces. - -Alternately, a GUI editor for project files is available (@pxref{GUI -Editor}). It uses Emacs widgets, similar to Emacs customize. - -The GUI editor also provides a convenient way to view current project -settings, if they have been modified using menu commands rather than -by editing the project file. - -After the first Ada mode build command is invoked, there is always a -current project file, given by the lisp variable -@code{ada-prj-default-project-file}. Currently, the only way to show -the current project file is to invoke the GUI editor. - -To find the project file the first time, Ada mode uses the following -search algorithm: - -@itemize @bullet -@item -If @code{ada-prj-default-project-file} is set, use that. - -@item -Otherwise, search for a file in the current directory with -the same base name as the Ada file, but extension given by -@code{ada-prj-file-extension} (default @code{".adp"}). - -@item -If not found, search for @file{*.adp} in the current directory; if -several are found, prompt the user to select one. - -@item -If none are found, use @file{default.adp} in the current directory (even -if it does not exist). - -@end itemize - -This algorithm always sets @code{ada-prj-default-project-file}, even -when the file does not actually exist. - -To change the project file before or after the first one is found, -invoke @samp{Ada | Project | Load ...}. - -Or, in lisp, evaluate @code{(ada-set-default-project-file "/path/file.adp")}. -This sets @code{ada-prj-default-project-file}, and reads the project file. - -You can also specify a GNAT project file to @samp{Ada | Project | Load -...} or @code{ada-set-default-project-file}. Emacs Ada mode checks the -file extension; if it is @code{.gpr}, the file is treated as a GNAT -project file. Any other extension is treated as an Emacs Ada mode -project file. - -@node GUI Editor, Project file variables, Project File Overview, Project files -@section GUI Editor - -The project file editor is invoked with the menu @samp{Ada | Projects -| Edit}. - -Once in the buffer for editing the project file, you can save your -modification using the @samp{[save]} button at the bottom of the -buffer, or the @kbd{C-x C-s} binding. To cancel your modifications, -kill the buffer or click on the @samp{[cancel]} button. - -@node Project file variables, , GUI Editor, Project files -@section Project file variables - -The following variables can be defined in a project file; some can -also be defined in lisp variables. - -To set a project variable that is a list, specify each element of the -list on a separate line in the project file. - -Any project variable can be referenced in other project variables, -using a shell-like notation. For instance, if the variable -@code{comp_cmd} contains @code{$@{comp_opt@}}, the value of the -@code{comp_opt} variable will be substituted when @code{comp_cmd} is -used. - -In addition, process environment variables can be referenced using the -same syntax, or the normal @code{$var} syntax. - -Most project variables have defaults that can be changed by setting -lisp variables; the table below identifies the lisp variable for each -project variable. Lisp variables corresponding to project variables -that are lists are lisp lists. - -In general, project variables are evaluated when referenced in -Emacs Ada mode commands. Relative file paths are expanded to -absolute relative to @code{$@{build_dir@}}. - -Here is the list of variables. In the default values, the current -directory @code{"."} is the project file directory. - -@table @asis -@c defined in ada-default-prj-properties; alphabetical order - -@item @code{ada_project_path_sep} [default: @code{":" or ";"}] -Path separator for @code{ADA_PROJECT_PATH}. It defaults to the correct -value for a native implementation of GNAT for the current operating -system. The user must override this when using Windows native GNAT -with Cygwin Emacs, and perhaps in other cases. - -Lisp variable: @code{ada-prj-ada-project-path-sep}. - -@item @code{ada_project_path} [default: @code{""}] -A list of directories to search for GNAT project files. - -If set, the @code{ADA_PROJECT_PATH} process environment variable is -set to this value in the Emacs process when the Emacs Ada mode project -is selected via menu @samp{Ada | Project | Load}. - -For @code{ada_project_path}, relative file paths are expanded to -absolute when the Emacs Ada project file is read, rather than when the -project file is selected. - -For example if the project file is in the directory -@file{/home/myproject}, the environment variable @code{GDS_ROOT} is -set to @code{/home/shared}, and the project file contains: -@example -ada_project_path_sep=: -ada_project_path=$GDS_ROOT/makerules -ada_project_path=../opentoken -@end example -the environment variable @code{ADA_PROJECT_PATH} will be set to -@code{"/home/shared/makerules:/home/opentoken/"}. - -The default value is not the current value of this environment -variable, because that will typically have been set by another -project, and will therefore be incorrect for this project. - -If you have the environment variable set correctly for all of your -projects, you do not need to set this project variable. - -@item @code{bind_opt} [default: @code{""}] -Holds user binder options; used in the default build commands. - -Lisp variable: @code{ada-prj-default-bind-opt}. - -@item @code{build_dir} [default: @code{"."}] -The compile commands will be issued in this directory. - -@item @code{casing} [default: @code{("~/.emacs_case_exceptions")} -List of files containing casing exceptions. See the help on -@code{ada-case-exception-file} for more info. -@c FIXME: section on case exceptions - -Lisp variable: @code{ada-case-exception-file}. - -@item @code{check_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c -gnatc $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] -Command used to syntax check a single file. -The name of the file is substituted for @code{full_current}. - -Lisp variable: @code{ada-prj-default-check-cmd} - -@item @code{comp_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] -Command used to compile a single file. -The name of the file is substituted for @code{full_current}. - -Lisp variable: @code{ada-prj-default-comp-cmd}. - -@item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}] -Holds user compiler options; used in the default compile commands. The -default value tells gnatmake to generate library files for -cross-referencing even when there are errors. - -If source code for the project is in multiple directories, the -appropriate compiler options must be added here. @ref{Set source -search path} for examples of this. Alternately, GNAT project files may -be used; @ref{Use GNAT project file}. - -Lisp variable: @code{ada-prj-default-comp-opt}. - -@item @code{cross_prefix} [default: @code{""}] -Name of target machine in a cross-compilation environment. Used in -default compile and build commands. - -@item @code{debug_cmd} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}] -Command used to debug the application - -Lisp variable: @code{ada-prj-default-debugger}. - -@item @code{debug_post_cmd} [default: @code{""}] -Command executed after @code{debug_cmd}. - -@item @code{debug_pre_cmd} [default: @code{"cd $@{build_dir@}"}] -Command executed before @code{debug_cmd}. - -@item @code{gnatfind_opt} [default: @code{"-rf"}] -Holds user gnatfind options; used in the default find commands. - -Lisp variable: @code{ada-prj-gnatfind-switches}. - -@item @code{gnatmake_opt} [default: @code{"-g"}] -Holds user gnatmake options; used in the default build commands. - -Lisp variable: @code{ada-prj-default-gnatmake-opt}. - -@item @code{gpr_file} [default: @code{""}] -Specify GNAT project file. - -If set, the source and object directories specified in the GNAT -project file are appended to @code{src_dir} and @code{obj_dir}. This -allows specifying Ada source directories with a GNAT project file, and -other source directories with the Emacs project file. - -In addition, @code{-P@{gpr_file@}} is added to the project variable -@code{gnatmake_opt} whenever it is referenced. With the default -project variables, this passes the project file to all gnatmake -commands. - -Lisp variable: @code{ada-prj-default-gpr-file}. - -@c FIXME: add gnatstub-opts - -@item @code{link_opt} [default: @code{""}] -Holds user linker options; used in the default build commands. - -Lisp variable: @code{ada-prj-default-link-opt}. - -@item @code{main} [default: current file] -Specifies the name of the executable file for the project; used in the -default build commands. - -@item @code{make_cmd} [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main@} $@{gnatmake_opt@} -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}] -Command used to build the application. - -Lisp variable: @code{ada-prj-default-make-cmd}. - -@item @code{obj_dir} [default: @code{"."}] -A list of directories to search for library files. Ada mode searches -this list for the @samp{.ali} files generated by GNAT that contain -cross-reference information. - -The compiler commands must place the @samp{.ali} files in one of these -directories; the default commands do that. - -@item @code{remote_machine} [default: @code{""}] -Name of the machine to log into before issuing the compile and build -commands. If this variable is empty, the command will be run on the -local machine. - -@item @code{run_cmd} [default: @code{"./$@{main@}"}] -Command used to run the application. - -@item @code{src_dir} [default: @code{"."}] -A list of directories to search for source files, both for compile -commands and source navigation. - -@end table - -@node Compiling Examples, Moving Through Ada Code, Project files, Top -@chapter Compiling Examples - -We present several small projects, and walk thru the process of -compiling, linking, and running them. - -The first example illustrates more Ada mode features than the others; -you should work thru that example before doing the others. - -All of these examples assume you are using GNAT. - -The source for these examples is available on the Emacs Ada mode -website mentioned in @xref{Installation}. - -@menu -* No project files:: Just menus -* Set compiler options:: A basic Ada mode project file -* Set source search path:: Source in multiple directories -* Use GNAT project file:: -* Use multiple GNAT project files:: -@end menu - -@node No project files, Set compiler options, Compiling Examples, Compiling Examples -@section No project files -This example uses no project files. - -First, create a directory @file{Example_1}, containing: - -@file{hello.adb}: - -@example -with Ada.Text_IO; -procedure Hello -is begin - Put_Line("Hello from hello.adb"); -end Hello; -@end example - -Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate -compiler error handling. - -@file{hello_2.adb}: - -@example -with Hello_Pkg; -procedure Hello_2 -is begin - Hello_Pkg.Say_Hello; -end Hello_2; -@end example - -This file has no errors. - -@file{hello_pkg.ads}: - -@example -package Hello_Pkg is - procedure Say_Hello; -end Hello_Pkg; -@end example - -This file has no errors. - -@file{hello_pkg.adb}: - -@example -with Ada.Text_IO; -package Hello_Pkg is - procedure Say_Hello - is begin - Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); - end Say_Hello; -end Hello_Pkg; -@end example - -Yes, this is missing the keyword @code{body}; another compiler error -example. - -In buffer @file{hello.adb}, invoke @samp{Ada | Check file}. You should -get a @code{*compilation*} buffer containing something like (the -directory paths will be different): - -@example -cd c:/Examples/Example_1/ -gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ -gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb -hello.adb:4:04: "Put_Line" is not visible -hello.adb:4:04: non-visible declaration at a-textio.ads:264 -hello.adb:4:04: non-visible declaration at a-textio.ads:260 -gnatmake: "c:/Examples/Example_1/hello.adb" compilation error -@end example - -If you have enabled font-lock, the lines with actual errors (starting -with @file{hello.adb}) are highlighted, with the file name in red. - -Now type @kbd{C-x `} (on a PC keyboard, @key{`} is next to @key{1}). -Or you can click the middle mouse button on the first error line. The -compilation buffer scrolls to put the first error on the top line, and -point is put at the place of the error in the @file{hello.adb} buffer. - -To fix the error, change the line to be - -@example - Ada.Text_IO.Put_Line ("hello from hello.adb"); -@end example - -Now invoke @samp{Ada | Show main}; this displays @samp{Ada mode main: hello}. - -Now (in buffer @file{hello.adb}), invoke @samp{Ada | Build}. You are -prompted to save the file (if you haven't already). Then the -compilation buffer is displayed again, containing: - -@example -cd c:/Examples/Example_1/ -gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs -gcc -c -g -gnatq -gnatQ hello.adb -gnatbind -x hello.ali -gnatlink hello.ali -o hello.exe -g -@end example - -The compilation has succeeded without errors; @file{hello.exe} now -exists in the same directory as @file{hello.adb}. - -Now invoke @samp{Ada | Run}. A @file{*run*} buffer is displayed, -containing - -@example -Hello from hello.adb - -Process run finished -@end example - -That completes the first part of this example. - -Now we will compile a multi-file project. Open the file -@file{hello_2.adb}, and invoke @samp{Ada | Set main and Build}. This -finds an error in @file{hello_pkg.adb}: - -@example -cd c:/Examples/Example_1/ -gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs -gcc -c -g -gnatq -gnatQ hello_pkg.adb -hello_pkg.adb:2:08: keyword "body" expected here [see file name] -gnatmake: "hello_pkg.adb" compilation error -@end example - -This demonstrates that gnatmake finds the files needed by the main -program. However, it cannot find files in a different directory, -unless you use an Emacs Ada mode project file to specify the other directories; -@xref{Set source search path}, or a GNAT project file; @ref{Use GNAT -project file}. - -Invoke @samp{Ada | Show main}; this displays @file{Ada mode main: hello_2}. - -Move to the error with @kbd{C-x `}, and fix the error by adding @code{body}: - -@example -package body Hello_Pkg is -@end example - -Now, while still in @file{hello_pkg.adb}, invoke @samp{Ada | Build}. -gnatmake successfully builds @file{hello_2}. This demonstrates that -Emacs has remembered the main file, in the project variable -@code{main}, and used it for the Build command. - -Finally, again while in @file{hello_pkg.adb}, invoke @samp{Ada | Run}. -The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}. - -One final point. If you switch back to buffer @file{hello.adb}, and -invoke @samp{Ada | Run}, @file{hello_2.exe} will be run. That is -because @code{main} is still set to @code{hello_2}, as you can -see when you invoke @samp{Ada | Project | Edit}. - -There are three ways to change @code{main}: - -@enumerate -@item -Invoke @samp{Ada | Set main and Build}, which sets @code{main} to -the current file. - -@item -Invoke @samp{Ada | Project | Edit}, edit @code{main}, and click @samp{[save]} - -@item -Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main} - -@end enumerate - -@node Set compiler options, Set source search path, No project files, Compiling Examples -@section Set compiler options - -This example illustrates using an Emacs Ada mode project file to set a -compiler option. - -If you have files from @file{Example_1} open in Emacs, you should -close them so you don't get confused. Use menu @samp{File | Close -(current buffer)}. - -In directory @file{Example_2}, create these files: - -@file{hello.adb}: - -@example -with Ada.Text_IO; -procedure Hello -is begin - Put_Line("Hello from hello.adb"); -end Hello; -@end example - -This is the same as @file{hello.adb} from @file{Example_1}. It has two -errors; missing ``use Ada.Text_IO;'', and no space between -@code{Put_Line} and its argument list. - -@file{hello.adp}: - -@example -comp_opt=-gnatyt -@end example - -This tells the GNAT compiler to check for token spacing; in -particular, there must be a space preceding a parenthesis. - -In buffer @file{hello.adb}, invoke @samp{Ada | Project | Load...}, and -select @file{Example_2/hello.adp}. - -Then, again in buffer @file{hello.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @code{*compilation*} buffer containing -something like (the directory paths will be different): - -@example -cd c:/Examples/Example_2/ -gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs -gcc -c -g -gnatyt hello.adb -hello.adb:4:04: "Put_Line" is not visible -hello.adb:4:04: non-visible declaration at a-textio.ads:264 -hello.adb:4:04: non-visible declaration at a-textio.ads:260 -hello.adb:4:12: (style) space required -gnatmake: "hello.adb" compilation error -@end example - -Compare this to the compiler output in @ref{No project files}; the -gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by -@code{-cargs -gnaty}, and an additional error is reported in -@file{hello.adb} on line 4. This shows that @file{hello.adp} is being -used to set the compiler options. - -Fixing the error, linking and running the code proceed as in @ref{No -project files}. - -@node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples -@section Set source search path - -In this example, we show how to deal with files in more than one -directory. We start with the same code as in @ref{No project files}; -create those files (with the errors present) - -Create the directory @file{Example_3}, containing: - -@file{hello_pkg.ads}: - -@example -package Hello_Pkg is - procedure Say_Hello; -end Hello_Pkg; -@end example - -@file{hello_pkg.adb}: - -@example -with Ada.Text_IO; -package Hello_Pkg is - procedure Say_Hello - is begin - Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); - end Say_Hello; -end Hello_Pkg; -@end example - -These are the same files from example 1; @file{hello_pkg.adb} has an -error on line 2. - -In addition, create a directory @file{Example_3/Other}, containing these files: - -@file{Other/hello_3.adb}: - -@example -with Hello_Pkg; -with Ada.Text_IO; use Ada.Text_IO; -procedure Hello_3 -is begin - Hello_Pkg.Say_Hello; - Put_Line ("From hello_3"); -end Hello_3; -@end example - -There are no errors in this file. - -@file{Other/other.adp}: - -@example -src_dir=.. -comp_opt=-I.. -@end example - -Note that there must be no trailing spaces. - -In buffer @file{hello_3.adb}, invoke @samp{Ada | Project | Load...}, and -select @file{Example_3/Other/other.adp}. - -Then, again in @file{hello_3.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @code{*compilation*} buffer containing -something like (the directory paths will be different): - -@example -cd c:/Examples/Example_3/Other/ -gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs -gcc -c -g -I.. hello_3.adb -gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb -hello_pkg.adb:2:08: keyword "body" expected here [see file name] -gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error -@end example - -Compare the @code{-cargs} option to the compiler output in @ref{Set -compiler options}; this shows that @file{other.adp} is being used to -set the compiler options. - -Move to the error with @kbd{C-x `}. Ada mode searches the list of -directories given by @code{src_dir} for the file mentioned in the -compiler error message. - -Fixing the error, linking and running the code proceed as in @ref{No -project files}. - -@node Use GNAT project file, Use multiple GNAT project files, Set source search path, Compiling Examples -@section Use GNAT project file - -In this example, we show how to use a GNAT project file, with no Ada -mode project file. - -Create the directory @file{Example_4}, containing: - -@file{hello_pkg.ads}: - -@example -package Hello_Pkg is - procedure Say_Hello; -end Hello_Pkg; -@end example - -@file{hello_pkg.adb}: - -@example -with Ada.Text_IO; -package Hello_Pkg is - procedure Say_Hello - is begin - Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); - end Say_Hello; -end Hello_Pkg; -@end example - -These are the same files from example 1; @file{hello_pkg.adb} has an -error on line 2. - -In addition, create a directory @file{Example_4/Gnat_Project}, -containing these files: - -@file{Gnat_Project/hello_4.adb}: - -@example -with Hello_Pkg; -with Ada.Text_IO; use Ada.Text_IO; -procedure Hello_4 -is begin - Hello_Pkg.Say_Hello; - Put_Line ("From hello_4"); -end Hello_4; -@end example - -There are no errors in this file. - -@file{Gnat_Project/hello_4.gpr}: - -@example -Project Hello_4 is - for Source_Dirs use (".", ".."); -end Hello_4; -@end example - -In buffer @file{hello_4.adb}, invoke @samp{Ada | Project | Load...}, and -select @file{Example_4/Gnat_Project/hello_4.gpr}. - -Then, again in @file{hello_4.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @code{*compilation*} buffer containing -something like (the directory paths will be different): - -@example -cd c:/Examples/Example_4/Gnat_Project/ -gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs -gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb -gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb -hello_pkg.adb:2:08: keyword "body" expected here [see file name] -gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error -@end example - -Compare the @code{gcc} options to the compiler output in @ref{Set -compiler options}; this shows that @file{hello_4.gpr} is being used to -set the compiler options. - -Fixing the error, linking and running the code proceed as in @ref{No -project files}. - -@node Use multiple GNAT project files, , Use GNAT project file, Compiling Examples -@section Use multiple GNAT project files - -In this example, we show how to use multiple GNAT project files, -specifying the GNAT project search path in an Ada mode project file. - -Create the directory @file{Example_4} as specified in @ref{Use GNAT -project file}. - -Create the directory @file{Example_5}, containing: - -@file{hello_5.adb}: - -@example -with Hello_Pkg; -with Ada.Text_IO; use Ada.Text_IO; -procedure Hello_5 -is begin - Hello_Pkg.Say_Hello; - Put_Line ("From hello_5"); -end Hello_5; -@end example - -There are no errors in this file. - -@file{hello_5.adp}: - -@example -ada_project_path=../Example_4/Gnat_Project -gpr_file=hello_5.gpr -@end example - -@file{hello_5.gpr}: - -@example -with "hello_4"; -Project Hello_5 is - for Source_Dirs use ("."); - package Compiler is - for Default_Switches ("Ada") use ("-g", "-gnatyt"); - end Compiler; -end Hello_5; -@end example - -In buffer @file{hello_5.adb}, invoke @samp{Ada | Project | Load...}, and -select @file{Example_5/hello_5.adp}. - -Then, again in @file{hello_5.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @code{*compilation*} buffer containing -something like (the directory paths will be different): - -@example -cd c:/Examples/Example_5/ -gnatmake -o hello_5 hello_5 -Phello_5.gpr -g -cargs -gnatq -gnatQ -bargs -largs -gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_5\hello_5.adb -gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb -hello_pkg.adb:2:08: keyword "body" expected here [see file name] -gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error -@end example - -Now type @kbd{C-x `}. @file{Example_4/hello_pkg.adb} is shown, -demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being -used to set the compilation search path. - -@node Moving Through Ada Code, Identifier completion, Compiling Examples, Top -@chapter Moving Through Ada Code - -There are several easy to use commands to navigate through Ada code. All -these functions are available through the Ada menu, and you can also -use the following key bindings or the command names. Some of these -menu entries are available only if the GNAT compiler is used, since -the implementation relies on the GNAT cross-referencing information. - -@table @kbd -@item M-C-e -@findex ada-next-procedure -Move to the next function/procedure/task, which ever comes next -(@code{ada-next-procedure}). -@item M-C-a -@findex ada-previous-procedure -Move to previous function/procedure/task -(@code{ada-previous-procedure}). -@item M-x ada-next-package -@findex ada-next-package -Move to next package. -@item M-x ada-previous-package -@findex ada-previous-package -Move to previous package. -@item C-c C-a -@findex ada-move-to-start -Move to matching start of @code{end} (@code{ada-move-to-start}). If -point is at the end of a subprogram, this command jumps to the -corresponding @code{begin} if the user option -@code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to -the subprogram declaration. -@item C-c C-e -@findex ada-move-to-end -Move point to end of current block (@code{ada-move-to-end}). -@item C-c o -Switch between corresponding spec and body file -(@code{ff-find-other-file}). If point is in a subprogram, position -point on the corresponding declaration or body in the other file. -@item C-c c-d -@findex ada-goto-declaration -Move from any reference to its declaration, for from a declaration to -its body (for procedures, tasks, private and incomplete types). -@item C-c C-r -@findex ada-find-references -Runs the @file{gnatfind} command to search for all references to the -identifier surrounding point (@code{ada-find-references}). Use -@kbd{C-x `} (@code{next-error}) to visit each reference (as for -compilation errors). -@end table - -If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs -will try to run GNAT for you whenever cross-reference information is -needed, and is older than the current source file. - -@node Identifier completion, Automatic Smart Indentation, Moving Through Ada Code, Top -@chapter Identifier completion - -Emacs and Ada mode provide two general ways for the completion of -identifiers. This is an easy way to type faster: you just have to type -the first few letters of an identifiers, and then loop through all the -possible completions. - -The first method is general for Emacs. It works by parsing all open -files for possible completions. - -For instance, if the words @samp{my_identifier}, @samp{my_subprogram} -are the only words starting with @samp{my} in any of the opened files, -then you will have this scenario: - -@example -You type: my@kbd{M-/} -Emacs inserts: @samp{my_identifier} -If you press @kbd{M-/} once again, Emacs replaces @samp{my_identifier} with -@samp{my_subprogram}. -Pressing @kbd{M-/} once more will bring you back to @samp{my_identifier}. -@end example - -This is a very fast way to do completion, and the casing of words will -also be respected. - -The second method (@kbd{C-@key{TAB}}) is specific to Ada mode and the GNAT -compiler. Emacs will search the cross-information for possible -completions. - -The main advantage is that this completion is more accurate: only -existing identifier will be suggested. - -On the other hand, this completion is a little bit slower and requires -that you have compiled your file at least once since you created that -identifier. - -@table @kbd -@item C-@key{TAB} -@findex ada-complete-identifier -Complete current identifier using cross-reference information. -@item M-/ -Complete identifier using buffer information (not Ada-specific). -@end table - -@node Automatic Smart Indentation, Formatting Parameter Lists, Identifier completion, Top -@chapter Automatic Smart Indentation - -Ada mode comes with a full set of rules for automatic indentation. You -can also configure the indentation, via the following variables: - -@table @asis -@item @code{ada-broken-indent} (default value: 2) -Number of columns to indent the continuation of a broken line. - -@item @code{ada-indent} (default value: 3) -Number of columns for default indentation. - -@item @code{ada-indent-record-rel-type} (default value: 3) -Indentation for @code{record} relative to @code{type} or @code{use}. - -@item @code{ada-indent-return} (default value: 0) -Indentation for @code{return} relative to @code{function} (if -@code{ada-indent-return} is greater than 0), or the open parenthesis -(if @code{ada-indent-return} is negative or 0). Note that in the second -case, when there is no open parenthesis, the indentation is done -relative to @code{function} with the value of @code{ada-broken-indent}. - -@item @code{ada-label-indent} (default value: -4) -Number of columns to indent a label. - -@item @code{ada-stmt-end-indent} (default value: 0) -Number of columns to indent a statement @code{end} keyword on a separate line. - -@item @code{ada-when-indent} (default value: 3) -Indentation for @code{when} relative to @code{exception} or @code{case}. - -@item @code{ada-indent-is-separate} (default value: t) -Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line. - -@item @code{ada-indent-to-open-paren} (default value: t) -Non-@code{nil} means indent according to the innermost open parenthesis. - -@item @code{ada-indent-after-return} (default value: t) -Non-@code{nil} means that the current line will also be re-indented -before inserting a newline, when you press @key{RET}. -@end table - -Most of the time, the indentation will be automatic, i.e when you -press @key{RET}, the cursor will move to the correct column on the -next line. - -You can also indent single lines, or the current region, with @key{TAB}. - -Another mode of indentation exists that helps you to set up your -indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do -the following: - -@itemize @bullet -@item -Reindent the current line, as @key{TAB} would do. -@item -Temporarily move the cursor to a reference line, i.e., the line that -was used to calculate the current indentation. -@item -Display in the message window the name of the variable that provided -the offset for the indentation. -@end itemize - -The exact indentation of the current line is the same as the one for the -reference line, plus an offset given by the variable. - -@table @kbd -@item @key{TAB} -Indent the current line or the current region. -@item C-M-\ -Indent lines in the current region. -@item C-c @key{TAB} -Indent the current line and display the name of the variable used for -indentation. -@end table - -@node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top -@chapter Formatting Parameter Lists - -@table @kbd -@item C-c C-f -@findex ada-format-paramlist -Format the parameter list (@code{ada-format-paramlist}). -@end table - -This aligns the declarations on the colon (@samp{:}) separating -argument names and argument types, and aligns the @code{in}, -@code{out} and @code{in out} keywords. - -@node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top -@chapter Automatic Casing - -Casing of identifiers, attributes and keywords is automatically -performed while typing when the variable @code{ada-auto-case} is set. -Every time you press a word separator, the previous word is -automatically cased. - -You can customize the automatic casing differently for keywords, -attributes and identifiers. The relevant variables are the following: -@code{ada-case-keyword}, @code{ada-case-attribute} and -@code{ada-case-identifier}. - -All these variables can have one of the following values: - -@table @code -@item downcase-word -The word will be lowercase. For instance @code{My_vARIable} is -converted to @code{my_variable}. - -@item upcase-word -The word will be uppercase. For instance @code{My_vARIable} is -converted to @code{MY_VARIABLE}. - -@item ada-capitalize-word -The first letter and each letter following an underscore (@samp{_}) -are uppercase, others are lowercase. For instance @code{My_vARIable} -is converted to @code{My_Variable}. - -@item ada-loose-case-word -Characters after an underscore @samp{_} character are uppercase, -others are not modified. For instance @code{My_vARIable} is converted -to @code{My_VARIable}. -@end table - -Ada mode allows you to define exceptions to these rules, in a file -specified by the variable @code{ada-case-exception-file} -(default @file{~/.emacs_case_exceptions}). Each line in this file -specifies the casing of one word or word fragment. Comments may be -included, separated from the word by a space. - -If the word starts with an asterisk (@key{*}), it defines the casing -as a word fragment (or ``substring''); part of a word between two -underscores or word boundary. - -For example: - -@example -DOD Department of Defense -*IO -GNAT The GNAT compiler from Ada Core Technologies -@end example - -The word fragment @code{*IO} applies to any word containing ``_io''; -@code{Text_IO}, @code{Hardware_IO}, etc. - -@findex ada-create-case-exception -There are two ways to add new items to this file: you can simply edit -it as you would edit any text file. Or you can position point on the -word you want to add, and select menu @samp{Ada | Edit | Create Case -Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}). -The word will automatically be added to the current list of exceptions -and to the file. - -To define a word fragment case exception, select the word fragment, -then select menu @samp{Ada | Edit | Create Case Exception Substring}. - -It is sometimes useful to have multiple exception files around (for -instance, one could be the standard Ada acronyms, the second some -company specific exceptions, and the last one some project specific -exceptions). If you set up the variable @code{ada-case-exception-file} -as a list of files, each of them will be parsed and used in your emacs -session. However, when you save a new exception through the menu, as -described above, the new exception will be added to the first file in -the list. - -@table @kbd -@item C-c C-b -@findex ada-adjust-case-buffer -Adjust case in the whole buffer (@code{ada-adjust-case-buffer}). -@item C-c C-y -Create a new entry in the exception dictionary, with the word under -the cursor (@code{ada-create-case-exception}) -@item C-c C-t -@findex ada-case-read-exceptions -Rereads the exception dictionary from the file -@code{ada-case-exception-file} (@code{ada-case-read-exceptions}). -@end table - -@node Statement Templates, Comment Handling, Automatic Casing, Top -@chapter Statement Templates - -Templates are defined for most Ada statements, using the Emacs -``skeleton'' package. They can be inserted in the buffer using the -following commands: - -@table @kbd -@item C-c t b -@findex ada-exception-block -exception Block (@code{ada-exception-block}). -@item C-c t c -@findex ada-case -case (@code{ada-case}). -@item C-c t d -@findex ada-declare-block -declare Block (@code{ada-declare-block}). -@item C-c t e -@findex ada-else -else (@code{ada-else}). -@item C-c t f -@findex ada-for-loop -for Loop (@code{ada-for-loop}). -@item C-c t h -@findex ada-header -Header (@code{ada-header}). -@item C-c t i -@findex ada-if -if (@code{ada-if}). -@item C-c t k -@findex ada-package-body -package Body (@code{ada-package-body}). -@item C-c t l -@findex ada-loop -loop (@code{ada-loop}). -@item C-c p -@findex ada-subprogram-body -subprogram body (@code{ada-subprogram-body}). -@item C-c t t -@findex ada-task-body -task Body (@code{ada-task-body}). -@item C-c t w -@findex ada-while -while Loop (@code{ada-while}). -@item C-c t u -@findex ada-use -use (@code{ada-use}). -@item C-c t x -@findex ada-exit -exit (@code{ada-exit}). -@item C-c t C-a -@findex ada-array -array (@code{ada-array}). -@item C-c t C-e -@findex ada-elsif -elsif (@code{ada-elsif}). -@item C-c t C-f -@findex ada-function-spec -function Spec (@code{ada-function-spec}). -@item C-c t C-k -@findex ada-package-spec -package Spec (@code{ada-package-spec}). -@item C-c t C-p -@findex ada-procedure-spec -procedure Spec (@code{ada-package-spec}. -@item C-c t C-r -@findex ada-record -record (@code{ada-record}). -@item C-c t C-s -@findex ada-subtype -subtype (@code{ada-subtype}). -@item C-c t C-t -@findex ada-task-spec -task Spec (@code{ada-task-spec}). -@item C-c t C-u -@findex ada-with -with (@code{ada-with}). -@item C-c t C-v -@findex ada-private -private (@code{ada-private}). -@item C-c t C-w -@findex ada-when -when (@code{ada-when}). -@item C-c t C-x -@findex ada-exception -exception (@code{ada-exception}). -@item C-c t C-y -@findex ada-type -type (@code{ada-type}). -@end table - -@node Comment Handling, GNU Free Documentation License, Statement Templates, Top -@chapter Comment Handling - -By default, comment lines get indented like Ada code. There are a few -additional functions to handle comments: - -@table @kbd -@item M-; -Start a comment in default column. -@item M-j -Continue comment on next line. -@item C-c ; -Comment the selected region (add -- at the beginning of lines). -@item C-c : -Uncomment the selected region -@item M-q -autofill the current comment. -@end table - -@node GNU Free Documentation License, Index, Comment Handling, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index, , GNU Free Documentation License, Top -@unnumbered Index - -@printindex fn - -@bye diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi deleted file mode 100644 index 4ce4e337a0f..00000000000 --- a/doc/misc/auth.texi +++ /dev/null @@ -1,536 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@include gnus-overrides.texi - -@setfilename ../../info/auth -@settitle Emacs auth-source Library @value{VERSION} - -@set VERSION 0.3 - -@copying -This file describes the Emacs auth-source library. - -Copyright @copyright{} 2008-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License'' -in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs lisp libraries -@direntry -* Auth-source: (auth). The Emacs auth-source library. -@end direntry - -@titlepage -@ifset WEBHACKDEVEL -@title Emacs auth-source Library (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title Emacs auth-source Library -@end ifclear -@author by Ted Zlatanov -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Emacs auth-source -This manual describes the Emacs auth-source library. - -It is a way for multiple applications to share a single configuration -(in Emacs and in files) for user convenience. - -@insertcopying - -@menu -* Overview:: Overview of the auth-source library. -* Help for users:: -* Secret Service API:: -* Help for developers:: -* GnuPG and EasyPG Assistant Configuration:: -* Index:: -* Function Index:: -* Variable Index:: -@end menu -@end ifnottex - -@node Overview -@chapter Overview - -The auth-source library is simply a way for Emacs and Gnus, among -others, to answer the old burning question ``What are my user name and -password?'' - -(This is different from the old question about burning ``Where is the -fire extinguisher, please?''.) - -The auth-source library supports more than just the user name or the -password (known as the secret). - -Similarly, the auth-source library supports multiple storage backend, -currently either the classic ``netrc'' backend, examples of which you -can see later in this document, or the Secret Service API. This is -done with EIEIO-based backends and you can write your own if you want. - -@node Help for users -@chapter Help for users - -``Netrc'' files are a de facto standard. They look like this: -@example -machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport} -@end example - -The @code{machine} is the server (either a DNS name or an IP address). -It's known as @var{:host} in @code{auth-source-search} queries. You -can also use @code{host}. - -The @code{port} is the connection port or protocol. It's known as -@var{:port} in @code{auth-source-search} queries. - -The @code{user} is the user name. It's known as @var{:user} in -@code{auth-source-search} queries. You can also use @code{login} and -@code{account}. - -Spaces are always OK as far as auth-source is concerned (but other -programs may not like them). Just put the data in quotes, escaping -quotes as you'd expect with @samp{\}. - -All these are optional. You could just say (but we don't recommend -it, we're just showing that it's possible) - -@example -password @var{mypassword} -@end example - -to use the same password everywhere. Again, @emph{DO NOT DO THIS} or -you will be pwned as the kids say. - -``Netrc'' files are usually called @file{.authinfo} or @file{.netrc}; -nowadays @file{.authinfo} seems to be more popular and the auth-source -library encourages this confusion by accepting both, as you'll see -later. - -If you have problems with the search, set @code{auth-source-debug} to -@code{'trivia} and see what host, port, and user the library is -checking in the @samp{*Messages*} buffer. Ditto for any other -problems, your first step is always to see what's being checked. The -second step, of course, is to write a blog entry about it and wait for -the answer in the comments. - -You can customize the variable @code{auth-sources}. The following may -be needed if you are using an older version of Emacs or if the -auth-source library is not loaded for some other reason. - -@lisp -(require 'auth-source) ;; probably not necessary -(customize-variable 'auth-sources) ;; optional, do it once -@end lisp - -@defvar auth-sources - -The @code{auth-sources} variable tells the auth-source library where -your netrc files or Secret Service API collection items live for a -particular host and protocol. While you can get fancy, the default -and simplest configuration is: - -@lisp -;;; old default: required :host and :port, not needed anymore -(setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t))) -;;; mostly equivalent (see below about fallbacks) but shorter: -(setq auth-sources '((:source "~/.authinfo.gpg"))) -;;; even shorter and the @emph{default}: -(setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc")) -;;; use the Secrets API @var{Login} collection (@pxref{Secret Service API}) -(setq auth-sources '("secrets:Login")) -@end lisp - -By adding multiple entries to @code{auth-sources} with a particular -host or protocol, you can have specific netrc files for that host or -protocol. Usually this is unnecessary but may make sense if you have -shared netrc files or some other unusual setup (90% of Emacs users -have unusual setups and the remaining 10% are @emph{really} unusual). - -Here's a mixed example using two sources: - -@lisp -(setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe") - "~/.authinfo.gpg")) -@end lisp - -@end defvar - -If you don't customize @code{auth-sources}, you'll have to live with -the defaults: any host and any port are looked up in the netrc -file @file{~/.authinfo.gpg}, which is a GnuPG encrypted file -(@pxref{GnuPG and EasyPG Assistant Configuration}). - -If that fails, the unencrypted netrc files @file{~/.authinfo} and -@file{~/.netrc} will be used. - -The typical netrc line example is without a port. - -@example -machine YOURMACHINE login YOU password YOURPASSWORD -@end example - -This will match any authentication port. Simple, right? But what if -there's a SMTP server on port 433 of that machine that needs a -different password from the IMAP server? - -@example -machine YOURMACHINE login YOU password SMTPPASSWORD port 433 -machine YOURMACHINE login YOU password GENERALPASSWORD -@end example - -For url-auth authentication (HTTP/HTTPS), you need to put this in your -netrc file: - -@example -machine yourmachine.com:80 port http login testuser password testpass -@end example - -This will match any realm and authentication method (basic or digest) -over HTTP. HTTPS is set up similarly. If you want finer controls, -explore the url-auth source code and variables. - -For Tramp authentication, use: - -@example -machine yourmachine.com port scp login testuser password testpass -@end example - -Note that the port denotes the Tramp connection method. When you -don't use a port entry, you match any Tramp method, as explained -earlier. Since Tramp has about 88 connection methods, this may be -necessary if you have an unusual (see earlier comment on those) setup. - -@node Secret Service API -@chapter Secret Service API - -The @dfn{Secret Service API} is a standard from -@uref{http://www.freedesktop.org/wiki/Specifications/secret-storage-spec,,freedesktop.org} -to securely store passwords and other confidential information. This -API is implemented by system daemons such as the GNOME Keyring and the -KDE Wallet (these are GNOME and KDE packages respectively and should -be available on most modern GNU/Linux systems). - -The auth-source library uses the @file{secrets.el} library to connect -through the Secret Service API. You can also use that library in -other packages, it's not exclusive to auth-source. - -@defvar secrets-enabled -After loading @file{secrets.el}, a non-@code{nil} value of this -variable indicates the existence of a daemon providing the Secret -Service API. -@end defvar - -@deffn Command secrets-show-secrets -This command shows all collections, items, and their attributes. -@end deffn - -The atomic objects managed by the Secret Service API are @dfn{secret -items}, which contain things an application wishes to store securely, -like a password. Secret items have a label (a name), the @dfn{secret} -(which is the string we want, like a password), and a set of lookup -attributes. The attributes can be used to search and retrieve a -secret item at a later date. - -Secret items are grouped in @dfn{collections}. A collection is -sometimes called a @samp{keyring} or @samp{wallet} in GNOME Keyring -and KDE Wallet but it's the same thing, a group of secrets. -Collections are personal and protected so only the owner can open them. - -The most common collection is called @code{"login"}. - -A collection can have an alias. The alias @code{"default"} is -commonly used so the clients don't have to know the specific name of -the collection they open. Other aliases are not supported yet. -Since aliases are globally accessible, set the @code{"default"} alias -only when you're sure it's appropriate. - -@defun secrets-list-collections -This function returns all the collection names as a list. -@end defun - -@defun secrets-set-alias collection alias -Set @var{alias} as alias of collection labeled @var{collection}. -Currently only the alias @code{"default"} is supported. -@end defun - -@defun secrets-get-alias alias -Return the collection name @var{alias} is referencing to. -Currently only the alias @code{"default"} is supported. -@end defun - -Collections can be created and deleted by the functions -@code{secrets-create-collection} and @code{secrets-delete-collection}. -Usually, this is not done from within Emacs. Do not delete standard -collections such as @code{"login"}. - -The special collection @code{"session"} exists for the lifetime of the -corresponding client session (in our case, Emacs's lifetime). It is -created automatically when Emacs uses the Secret Service interface and -it is deleted when Emacs is killed. Therefore, it can be used to -store and retrieve secret items temporarily. The @code{"session"} -collection is better than a persistent collection when the secret -items should not live longer than Emacs. The session collection can -be specified either by the string @code{"session"}, or by @code{nil}, -whenever a collection parameter is needed in the following functions. - -@defun secrets-list-items collection -Returns all the item labels of @var{collection} as a list. -@end defun - -@defun secrets-create-item collection item password &rest attributes -This function creates a new item in @var{collection} with label -@var{item} and password @var{password}. @var{attributes} are -key-value pairs set for the created item. The keys are keyword -symbols, starting with a colon. Example: - -@example -;;; The session "session", the label is "my item" -;;; and the secret (password) is "geheim" -(secrets-create-item "session" "my item" "geheim" - :method "sudo" :user "joe" :host "remote-host") -@end example -@end defun - -@defun secrets-get-secret collection item -Return the secret of item labeled @var{item} in @var{collection}. -If there is no such item, return @code{nil}. -@end defun - -@defun secrets-delete-item collection item -This function deletes item @var{item} in @var{collection}. -@end defun - -The lookup attributes, which are specified during creation of a -secret item, must be a key-value pair. Keys are keyword symbols, -starting with a colon; values are strings. They can be retrieved -from a given secret item and they can be used for searching of items. - -@defun secrets-get-attribute collection item attribute -Returns the value of key @var{attribute} of item labeled @var{item} in -@var{collection}. If there is no such item, or the item doesn't own -this key, the function returns @code{nil}. -@end defun - -@defun secrets-get-attributes collection item -Return the lookup attributes of item labeled @var{item} in -@var{collection}. If there is no such item, or the item has no -attributes, it returns @code{nil}. Example: - -@example -(secrets-get-attributes "session" "my item") - @result{} ((:user . "joe") (:host ."remote-host")) -@end example -@end defun - -@defun secrets-search-items collection &rest attributes -Search for the items in @var{collection} with matching -@var{attributes}. The @var{attributes} are key-value pairs, as used -in @code{secrets-create-item}. Example: - -@example -(secrets-search-items "session" :user "joe") - @result{} ("my item" "another item") -@end example -@end defun - -The auth-source library uses the @file{secrets.el} library and thus -the Secret Service API when you specify a source matching -@code{"secrets:COLLECTION"}. For instance, you could use -@code{"secrets:session"} to use the @code{"session"} collection, open only -for the lifetime of Emacs. Or you could use @code{"secrets:Login"} to -open the @code{"Login"} collection. As a special case, you can use the -symbol @code{default} in @code{auth-sources} (not a string, but a -symbol) to specify the @code{"default"} alias. Here is a contrived -example that sets @code{auth-sources} to search three collections and -then fall back to @file{~/.authinfo.gpg}. - -@example -(setq auth-sources '(default - "secrets:session" - "secrets:Login" - "~/.authinfo.gpg")) -@end example - -@node Help for developers -@chapter Help for developers - -The auth-source library lets you control logging output easily. - -@defvar auth-source-debug -Set this variable to @code{'trivia} to see lots of output in -@samp{*Messages*}, or set it to a function that behaves like -@code{message} to do your own logging. -@end defvar - -The auth-source library only has a few functions for external use. - -@defun auth-source-search &rest spec &key type max host user port secret require create delete &allow-other-keys -This function searches (or modifies) authentication backends according -to @var{spec}. See the function's doc-string for details. -@c TODO more details. -@end defun - -Let's take a look at an example of using @code{auth-source-search} -from Gnus's @code{nnimap.el}. - -@example -(defun nnimap-credentials (address ports) - (let* ((auth-source-creation-prompts - '((user . "IMAP user at %h: ") - (secret . "IMAP password for %u@@%h: "))) - (found (nth 0 (auth-source-search :max 1 - :host address - :port ports - :require '(:user :secret) - :create t)))) - (if found - (list (plist-get found :user) - (let ((secret (plist-get found :secret))) - (if (functionp secret) - (funcall secret) - secret)) - (plist-get found :save-function)) - nil))) -@end example - -This call requires the user and password (secret) to be in the -results. It also requests that an entry be created if it doesn't -exist already. While the created entry is being assembled, the shown -prompts will be used to interact with the user. The caller can also -pass data in @code{auth-source-creation-defaults} to supply defaults -for any of the prompts. - -Note that the password needs to be evaluated if it's a function. It's -wrapped in a function to provide some security. - -Later, after a successful login, @code{nnimap.el} calls the -@code{:save-function} like so: - -@example -(when (functionp (nth 2 credentials)) - (funcall (nth 2 credentials))) -@end example - -This will work whether the @code{:save-function} was provided or not. -@code{:save-function} will be provided only when a new entry was -created, so this effectively says ``after a successful login, save the -authentication information we just used, if it was newly created.'' - -After the first time it's called, the @code{:save-function} will not -run again (but it will log something if you have set -@code{auth-source-debug} to @code{'trivia}). This is so it won't ask -the same question again, which is annoying. This is so it won't ask -the same question again, which is annoying. This is so it won't ask -the same question again, which is annoying. - -So the responsibility of the API user that specified @code{:create t} -is to call the @code{:save-function} if it's provided. - -@defun auth-source-delete &rest spec &key delete &allow-other-keys -This function deletes entries matching @var{spec} from the -authentication backends. It returns the entries that were deleted. -The backend may not actually delete the entries. -@end defun - -@defun auth-source-forget spec -This function forgets any cached data that exactly matches @var{spec}. -It returns @code{t} if it forget some data, and @code{nil} if no -matching data was found. -@end defun - -@defun auth-source-forget+ &rest spec &allow-other-keys -This function forgets any cached data matching @var{spec}. -It returns the number of items forgotten. -@end defun - -@node GnuPG and EasyPG Assistant Configuration -@appendix GnuPG and EasyPG Assistant Configuration - -If you don't customize @code{auth-sources}, the auth-source library -reads @file{~/.authinfo.gpg}, which is a GnuPG encrypted file. Then -it will check @file{~/.authinfo} but it's not recommended to use such -an unencrypted file. - -In Emacs 23 or later there is an option @code{auto-encryption-mode} to -automatically decrypt @file{*.gpg} files. It is enabled by default. -If you are using earlier versions of Emacs, you will need: - -@lisp -(require 'epa-file) -(epa-file-enable) -@end lisp - -If you want your GnuPG passwords to be cached, set up @code{gpg-agent} -or EasyPG Assistant -(@pxref{Caching Passphrases, , Caching Passphrases, epa}). - -To quick start, here are some questions: - -@enumerate -@item -Do you use GnuPG version 2 instead of GnuPG version 1? -@item -Do you use symmetric encryption rather than public key encryption? -@item -Do you want to use gpg-agent? -@end enumerate - -Here are configurations depending on your answers: - -@multitable {111} {222} {333} {configuration configuration configuration} -@item @b{1} @tab @b{2} @tab @b{3} @tab Configuration -@item Yes @tab Yes @tab Yes @tab Set up gpg-agent. -@item Yes @tab Yes @tab No @tab You can't, without gpg-agent. -@item Yes @tab No @tab Yes @tab Set up gpg-agent. -@item Yes @tab No @tab No @tab You can't, without gpg-agent. -@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache. -@item No @tab Yes @tab No @tab Set up elisp passphrase cache. -@item No @tab No @tab Yes @tab Set up gpg-agent. -@item No @tab No @tab No @tab You can't, without gpg-agent. -@end multitable - -To set up gpg-agent, follow the instruction in GnuPG manual -(@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}). - -To set up elisp passphrase cache, set -@code{epa-file-cache-passphrase-for-symmetric-encryption}. - -@node Index -@chapter Index -@printindex cp - -@node Function Index -@chapter Function Index -@printindex fn - -@node Variable Index -@chapter Variable Index -@printindex vr - -@bye - -@c End: diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi deleted file mode 100644 index 9d7a51233ff..00000000000 --- a/doc/misc/autotype.texi +++ /dev/null @@ -1,665 +0,0 @@ -\input texinfo -@c This is an annex of the Emacs manual. -@c Author: Daniel.Pfeiffer@Informatik.START.dbp.de, fax (+49 69) 7588-2389 -@setfilename ../../info/autotype -@c @node Autotypist, Picture, Abbrevs, Top -@c @chapter Features for Automatic Typing -@settitle Features for Automatic Typing -@c @cindex text -@c @cindex selfinserting text -@c @cindex autotypist - -@copying -Copyright @copyright{} 1994-1995, 1999, 2001-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Autotype: (autotype). Convenient features for text that you - enter frequently in Emacs. -@end direntry - -@titlepage -@sp 10 - -@center @titlefont{Autotyping} -@sp 2 -@center @subtitlefont{Convenient features for text that you enter -frequently in Emacs} -@sp 2 -@center Daniel Pfeiffer -@center additions by Dave Love - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top Autotyping - - Under certain circumstances you will find yourself typing similar things -over and over again. This is especially true of form letters and programming -language constructs. Project-specific header comments, flow-control -constructs or magic numbers are essentially the same every time. Emacs has -various features for doing tedious and repetitive typing chores for you -in addition to the Abbrev features (@pxref{(emacs)Abbrevs}). - - One solution is using skeletons, flexible rules that say what to -insert, and how to do it. Various programming language modes offer some -ready-to-use skeletons, and you can adapt them to suit your needs or -taste, or define new ones. - - Another feature is automatic insertion of what you want into empty files, -depending on the file-name or the mode as appropriate. You can have a file or -a skeleton inserted, or you can call a function. Then there is the -possibility to have Un*x interpreter scripts automatically take on a magic -number and be executable as soon as they are saved. Or you can have a -copyright notice's year updated, if necessary, every time you save a -file. Similarly for time stamps in the file. - - URLs can be inserted based on a word at point. Flexible templates can -be defined for inserting and navigating between text more generally. A -sort of meta-expansion facility can be used to try a set of alternative -completions and expansions of text at point. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Using Skeletons:: How to insert a skeleton into your text. -* Wrapping Skeletons:: Putting existing text within a skeleton. -* Skeletons as Abbrevs:: An alternative for issuing skeleton commands. -* Skeleton Language:: Making skeleton commands insert what you want. -* Inserting Pairs:: Typing one character and getting another - after point. -* Autoinserting:: Filling up empty files as soon as you visit them. -* Copyrights:: Inserting and updating copyrights. -* Executables:: Turning interpreter scripts into executables. -* Timestamps:: Updating dates and times in modified files. -* QuickURL:: Inserting URLs based on text at point. -* Tempo:: Flexible template insertion. -* Hippie Expand:: Expansion of text trying various methods. - -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: -* Command Index:: -* Variable Index:: -@end menu - - -@node Using Skeletons -@chapter Using Skeletons -@cindex skeletons -@cindex using skeletons - - When you want Emacs to insert a form letter or a typical construct of the -programming language you are using, skeletons are a means of accomplishing -this. Normally skeletons each have a command of their own, that, when called, -will insert the skeleton. These commands can be issued in the usual ways -(@pxref{(emacs)Commands}). Modes that offer various skeletons will often -bind these to key-sequences on the @kbd{C-c} prefix, as well as having -an @cite{Insert} menu and maybe even predefined abbrevs for them -(@pxref{Skeletons as Abbrevs}). - - The simplest kind of skeleton will simply insert some text indented -according to the major mode and leave the cursor at a likely place in the -middle. Interactive skeletons may prompt you for a string that will be part -of the inserted text. - - Skeletons may ask for input several times. They even have a looping -mechanism in which you will be asked for input as long as you are willing to -furnish it. An example would be multiple ``else if'' conditions. You can -recognize this situation by a prompt ending in @key{RET}, @kbd{C-g} -or @kbd{C-h}. This -means that entering an empty string will simply assume that you are finished. -Typing quit on the other hand terminates the loop but also the rest of the -skeleton, e.g. an ``else'' clause is skipped. Only a syntactically necessary -termination still gets inserted. - - - -@node Wrapping Skeletons -@chapter Wrapping Skeletons Around Existing Text -@cindex wrapping skeletons - - Often you will find yourself with some code that for whatever reason -suddenly becomes conditional. Or you have written a bit of text and want to -put it in the middle of a form letter. Skeletons provide a means for -accomplishing this, and can even, in the case of programming languages, -reindent the wrapped code for you. - - Skeleton commands take an optional numeric prefix argument -(@pxref{(emacs)Arguments}). This is interpreted in two different ways depending -on whether the prefix is positive, i.e. forwards oriented or negative, -i.e. backwards oriented. - - A positive prefix means to wrap the skeleton around that many -following words. This is accomplished by putting the words there where -the point is normally left after that skeleton is inserted (@pxref{Using -Skeletons}). The point (@pxref{(emacs)Point}) is left at the next -interesting spot in the skeleton instead. - - A negative prefix means to do something similar with that many previously -marked interregions (@pxref{(emacs)Mark}). In the simplest case, if you type -@kbd{M--} just before issuing the skeleton command, that will wrap the -skeleton around the current region, just like a positive argument would have -wrapped it around a number of words. - - Smaller negative arguments will wrap that many interregions into successive -interesting spots within the skeleton, again leaving the point at the next one. -We speak about interregions rather than regions here, because we treat them in -the order they appear in the buffer, which coincides with successive regions -only if they were marked in order. - - That is, if you marked in alphabetical order the points A B C [] (where [] -represents the point) and call a skeleton command with @kbd{M-- 3}, you will -wrap the text from A to B into the first interesting spot of the skeleton, the -text from B to C into the next one, the text from C to the point into the -third one, and leave the point in the fourth one. If there are less marks in -the buffer, or if the skeleton defines less interesting points, the surplus is -ignored. - - If, on the other hand, you marked in alphabetical order the points [] A C B, -and call a skeleton command with @kbd{M-- 3}, you will wrap the text from -point to A, then the text from A to C and finally the text from C to B. This -is done because the regions overlap and Emacs would be helplessly lost if it -tried to follow the order in which you marked these points. - - - -@node Skeletons as Abbrevs -@chapter Skeletons as Abbrev Expansions -@cindex skeletons as abbrevs - - Rather than use a key binding for every skeleton command, you can also -define an abbreviation (@pxref{(emacs)Defining Abbrevs}) that will expand -(@pxref{(emacs)Expanding Abbrevs}) into the skeleton. - - Say you want @samp{ifst} to be an abbreviation for the C language if -statement. You will tell Emacs that @samp{ifst} expands to the empty string -and then calls the skeleton command. In Emacs Lisp you can say something like -@code{(define-abbrev c-mode-abbrev-table "ifst" "" 'c-if)}. Or you can edit -the output from @kbd{M-x list-abbrevs} to make it look like this: - -@example -(c-mode-abbrev-table) -"if" 0 "" c-if -@end example - -@noindent -(Some blank lines of no semantic significance, and other abbrev tables, -have been omitted.) - - - -@node Skeleton Language -@chapter Skeleton Language -@cindex skeleton language - -@findex skeleton-insert - Skeletons are an shorthand extension to the Lisp language, where various -atoms directly perform either actions on the current buffer or rudimentary -flow control mechanisms. Skeletons are interpreted by the function -@code{skeleton-insert}. - - A skeleton is a list starting with an interactor, which is usually a -prompt-string, or @code{nil} when not needed, but can also be a Lisp -expression for complex read functions or for returning some calculated value. -The rest of the list are any number of elements as described in the following -table: - -@table @asis -@item @code{"@var{string}"}, @code{?@var{c}}, @code{?\@var{c}} -@vindex skeleton-transformation -Insert string or character. Literal strings and characters are passed through -@code{skeleton-transformation} when that is non-@code{nil}. -@item @code{?\n} -@c ??? something seems very wrong here. -Insert a newline and align under current line. Use newline character -@code{?\n} to prevent alignment. -@item @code{_} -Interesting point. When wrapping skeletons around successive regions, they are -put at these places. Point is left at first @code{_} where nothing is wrapped. -@item @code{>} -Indent line according to major mode. When following element is @code{_}, and -there is a interregion that will be wrapped here, indent that interregion. -@item @code{&} -Logical and. Iff preceding element moved point, i.e. usually inserted -something, do following element. -@item @code{|} -Logical xor. Iff preceding element didn't move point, i.e. usually inserted -nothing, do following element. -@item @code{-@var{number}} -Delete preceding number characters. Depends on value of -@code{skeleton-untabify}. -@item @code{()} or @code{nil} -Ignored. -@item @var{lisp-expression} -Evaluated, and the return value is again interpreted as a skeleton element. -@item @code{str} -A special variable that, when evaluated the first time, usually prompts -for input according to the skeleton's interactor. It is then set to the -return value resulting from the interactor. Each subskeleton has its local -copy of this variable. -@item @code{v1}, @code{v2} -Skeleton-local user variables. -@item @code{'@var{expression}} -Evaluate following Lisp expression for its side-effect, but prevent it from -being interpreted as a skeleton element. -@item @var{skeleton} -Subskeletons are inserted recursively, not once, but as often as the user -enters something at the subskeletons interactor. Thus there must be a -@code{str} in the subskeleton. They can also be used non-interactively, when -prompt is a lisp-expression that returns successive list-elements. -@item @code{resume:} -Ignored. Execution resumes here if the user quits during skeleton -interpretation. -@item @code{quit} -A constant which is non-@code{nil} when the @code{resume:} section was entered -because the user quit. -@end table - -@findex skeleton-further-elements - Some modes also use other skeleton elements they themselves defined. For -example in shell script mode's skeletons you will find @code{<} which does a -rigid indentation backwards, or in CC mode's skeletons you find the -self-inserting elements @code{@{} and @code{@}}. These are defined by the -buffer-local variable @code{skeleton-further-elements} which is a list of -variables bound while interpreting a skeleton. - -@findex define-skeleton - The macro @code{define-skeleton} defines a command for interpreting a -skeleton. The first argument is the command name, the second is a -documentation string, and the rest is an interactor and any number of skeleton -elements together forming a skeleton. This skeleton is assigned to a variable -of the same name as the command and can thus be overridden from your -@file{~/.emacs} file (@pxref{(emacs)Init File}). - - - -@node Inserting Pairs -@chapter Inserting Matching Pairs of Characters -@cindex inserting pairs -@cindex pairs - - Various characters usually appear in pairs. When, for example, you insert -an open parenthesis, no matter whether you are programming or writing prose, -you will surely enter a closing one later. By entering both at the same time -and leaving the cursor inbetween, Emacs can guarantee you that such -parentheses are always balanced. And if you have a non-qwerty keyboard, where -typing some of the stranger programming language symbols makes you bend your -fingers backwards, this can be quite relieving too. - -@findex skeleton-pair-insert-maybe -@vindex skeleton-pair - This is done by binding the first key (@pxref{(emacs)Rebinding}) of -the pair to @code{skeleton-pair-insert-maybe} instead of -@code{self-insert-command}. The ``maybe'' comes from the fact that -this at-first surprising behavior is initially turned off. To enable -it, you must set @code{skeleton-pair} to some non-@code{nil} value. -And even then, a positive argument (@pxref{(emacs)Arguments}) will -make this key behave like a self-inserting key -(@pxref{(emacs)Inserting Text}). - -@vindex skeleton-pair-on-word - While this breaks with the stated intention of always balancing pairs, it -turns out that one often doesn't want pairing to occur, when the following -character is part of a word. If you want pairing to occur even then, set -@code{skeleton-pair-on-word} to some non-@code{nil} value. - -@vindex skeleton-pair-alist - Pairing is possible for all visible characters. By default the -parenthesis @samp{(}, the square bracket @samp{[}, the brace -@samp{@{}, the pointed bracket @samp{<} and the backquote @samp{`} all -pair with the symmetrical character. All other characters pair -themselves. This behavior can be modified by the variable -@code{skeleton-pair-alist}. This is in fact an alist of skeletons -(@pxref{Skeleton Language}), with the first part of each sublist -matching the typed character. This is the position of the interactor, -but since pairs don't need the @code{str} element, this is ignored. - - Some modes have bound the command @code{skeleton-pair-insert-maybe} -to relevant keys. These modes also configure the pairs as -appropriate. For example, when typing english prose, you'd expect the -backquote (@samp{`}) to pair with the quote (@samp{'}), while in Shell -script mode it must pair to itself. They can also inhibit pairing in -certain contexts. For example an escaped character stands for itself. - - - -@node Autoinserting -@chapter Autoinserting Text in Empty Files -@cindex autoinserting - -@findex auto-insert - @kbd{M-x auto-insert} will put some predefined text at the beginning of -the buffer. The main application for this function, as its name suggests, -is to have it be called automatically every time an empty, and only an -empty file is visited. This is accomplished by putting @code{(add-hook -'find-file-hook 'auto-insert)} into your @file{~/.emacs} file -(@pxref{(emacs)Init File}). - -@vindex auto-insert-alist - What gets inserted, if anything, is determined by the variable -@code{auto-insert-alist}. The @sc{car}s of this list are each either -a mode name, making an element applicable when a buffer is in that -mode. Or they can be a string, which is a regexp matched against the -buffer's file name. In that way different kinds of files that have -the same mode in Emacs can be distinguished. The @sc{car}s may also -be cons cells consisting of mode name or regexp as above and an -additional descriptive string. - - When a matching element is found, the @sc{cdr} says what to do. It may -be a string, which is a file name, whose contents are to be inserted, if -that file is found in the directory @code{auto-insert-directory} or under a -absolute file name. Or it can be a skeleton (@pxref{Skeleton Language}) to -be inserted. - - It can also be a function, which allows doing various things. The function -can simply insert some text, indeed, it can be skeleton command (@pxref{Using -Skeletons}). It can be a lambda function which will for example conditionally -call another function. Or it can even reset the mode for the buffer. If you -want to perform several such actions in order, you use a vector, i.e. several -of the above elements between square brackets (@samp{[@r{@dots{}}]}). - - By default C and C++ headers insert a definition of a symbol derived from -the filename to prevent multiple inclusions. C and C++ sources insert an -include of the header. Makefiles insert the file makefile.inc if it exists. - - TeX and bibTeX mode files insert the file tex-insert.tex if it exists, while -LaTeX mode files insert a typical @code{\documentclass} frame. Html -files insert a skeleton with the usual frame. - - Ada mode files call the Ada header skeleton command. Emacs lisp -source files insert the usual header, with a copyright of your -environment variable @env{$ORGANIZATION} or else the FSF, and prompt -for valid keywords describing the contents. Files in a @file{bin} -directory for which Emacs could determine no specialized mode -(@pxref{(emacs)Choosing Modes}) are set to Shell script mode. - -@findex define-auto-insert - In Lisp (@pxref{(emacs)Init File}) you can use the function -@code{define-auto-insert} to add to or modify -@code{auto-insert-alist}. See its documentation with @kbd{C-h f -define-auto-insert}. - -@vindex auto-insert - The variable @code{auto-insert} says what to do when @code{auto-insert} is -called non-interactively, e.g. when a newly found file is empty (see above): -@table @asis -@item @code{nil} -Do nothing. -@item @code{t} -Insert something if possible, i.e. there is a matching entry in -@code{auto-insert-alist}. -@item other -Insert something if possible, but mark as unmodified. -@end table - -@vindex auto-insert-query - The variable @code{auto-insert-query} controls whether to ask about -inserting something. When this is @code{nil}, inserting is only done with -@kbd{M-x auto-insert}. When this is @code{function}, you are queried -whenever @code{auto-insert} is called as a function, such as when Emacs -visits an empty file and you have set the above-mentioned hook. Otherwise -you are always queried. - -@vindex auto-insert-prompt - When querying, the variable @code{auto-insert-prompt}'s value is used as a -prompt for a y-or-n-type question. If this includes a @samp{%s} construct, -that is replaced by what caused the insertion rule to be chosen. This is -either a descriptive text, the mode-name of the buffer or the regular -expression that matched the filename. - - - -@node Copyrights -@chapter Inserting and Updating Copyrights -@cindex copyrights - -@findex copyright - @kbd{M-x copyright} is a skeleton inserting command, that adds a copyright -notice at the point. The ``by'' part is taken from your environment variable -@env{$ORGANIZATION} or if that isn't set you are prompted for it. If the -buffer has a comment syntax (@pxref{(emacs)Comments}), this is inserted as a comment. - -@findex copyright-update -@vindex copyright-limit -@vindex copyright-current-year - @kbd{M-x copyright-update} looks for a copyright notice in the first -@code{copyright-limit} characters of the buffer and updates it when necessary. -The current year (variable @code{copyright-current-year}) is added to the -existing ones, in the same format as the preceding year, i.e. 1994, '94 or 94. -If a dash-separated year list up to last year is found, that is extended to -current year, else the year is added separated by a comma. Or it replaces -them when this is called with a prefix argument. If a header referring to a -wrong version of the GNU General Public License (@pxref{(emacs)Copying}) is found, -that is updated too. - - An interesting application for this function is to have it be called -automatically every time a file is saved. This is accomplished by -putting @code{(add-hook 'before-save-hook 'copyright-update)} into -your @file{~/.emacs} file (@pxref{(emacs)Init File}). Alternative, -you can do @kbd{M-x customize-variable @key{RET} before-save-hook -@key{RET}}. @code{copyright-update} is conveniently listed as an -option in the customization buffer. - -@vindex copyright-query - The variable @code{copyright-query} controls whether to update the -copyright or whether to ask about it. When this is @code{nil} updating is -only done with @kbd{M-x copyright-update}. When this is @code{function} -you are queried whenever @code{copyright-update} is called as a function, -such as in the @code{before-save-hook} feature mentioned above. Otherwise -you are always queried. - - - -@node Executables -@chapter Making Interpreter Scripts Executable -@cindex executables - -@vindex executable-prefix -@vindex executable-chmod - Various interpreter modes such as Shell script mode or AWK mode will -automatically insert or update the buffer's magic number, a special -comment on the first line that makes the @code{exec} systemcall know -how to execute the script. To this end the script is automatically -made executable upon saving, with @code{executable-chmod} as argument -to the system @code{chmod} command. The magic number is prefixed by -the value of @code{executable-prefix}. - -@vindex executable-magicless-file-regexp - Any file whose name matches @code{executable-magicless-file-regexp} is not -furnished with a magic number, nor is it made executable. This is mainly -intended for resource files, which are only meant to be read in. - -@vindex executable-insert - The variable @code{executable-insert} says what to do when -@code{executable-set-magic} is called non-interactively, e.g. when file has no -or the wrong magic number: -@table @asis -@item @code{nil} -Do nothing. -@item @code{t} -Insert or update magic number. -@item other -Insert or update magic number, but mark as unmodified. -@end table - -@findex executable-set-magic -@vindex executable-query - The variable @code{executable-query} controls whether to ask about -inserting or updating the magic number. When this is @code{nil} updating -is only done with @kbd{M-x executable-set-magic}. When this is -@code{function} you are queried whenever @code{executable-set-magic} is -called as a function, such as when Emacs puts a buffer in Shell script -mode. Otherwise you are always queried. - -@findex executable-self-display - @kbd{M-x executable-self-display} adds a magic number to the buffer, which -will turn it into a self displaying text file, when called as a Un*x command. -The ``interpreter'' used is @code{executable-self-display} with argument -@samp{+2}. - -@node Timestamps -@chapter Maintaining Timestamps in Modified Files -@cindex timestamps - -@findex time-stamp -@vindex before-save-hook -The @code{time-stamp} command can be used to update automatically a -template in a file with a new time stamp every time you save the file. -Customize the hook @code{before-save-hook} to add the function -@code{time-stamp} to arrange this. It you use Custom to do this, -then @code{time-stamp} is conveniently listed as an option in the -customization buffer. - -@vindex time-stamp-active -@vindex time-stamp-format -@vindex time-stamp-start -The time stamp is updated only if the customizable variable -@code{time-stamp-active} is on, which it is by default; the command -@code{time-stamp-toggle-active} can be used to toggle it. The format of -the time stamp is set by the customizable variable -@code{time-stamp-format}. - -@vindex time-stamp-line-limit -@vindex time-stamp-end -@vindex time-stamp-count -@vindex time-stamp-inserts-lines -The variables @code{time-stamp-line-limit}, @code{time-stamp-start}, -@code{time-stamp-end}, @code{time-stamp-count}, and -@code{time-stamp-inserts-lines} control finding the template. Do not -change these in your init file or you will be incompatible with other -people's files. If you must change them, do so only in the local -variables section of the file itself. - -Normally the template must appear in the first 8 lines of a file and -look like one of the following: - -@example -Time-stamp: <> -Time-stamp: " " -@end example - -The time stamp is written between the brackets or quotes: - -@example -Time-stamp: <1998-02-18 10:20:51 gildea> -@end example - -@node QuickURL -@chapter QuickURL: Inserting URLs Based on Text at Point - -@vindex quickurl-url-file -@findex quickurl -@cindex URLs -@kbd{M-x quickurl} can be used to insert a URL into a buffer based on -the text at point. The URLs are stored in an external file defined by -the variable @code{quickurl-url-file} as a list of either cons cells of -the form @code{(@var{key} . @var{URL})} or -lists of the form @code{(@var{key} @var{URL} @var{comment})}. These -specify that @kbd{M-x quickurl} should insert @var{URL} if the word -@var{key} is at point, for example: - -@example -(("FSF" "http://www.fsf.org/" "The Free Software Foundation") - ("emacs" . "http://www.emacs.org/") - ("hagbard" "http://www.hagbard.demon.co.uk" "Hagbard's World")) -@end example - -@findex quickurl-add-url -@findex quickurl-list -@kbd{M-x quickurl-add-url} can be used to add a new @var{key}/@var{URL} -pair. @kbd{M-x quickurl-list} provides interactive editing of the URL -list. - -@node Tempo -@chapter Tempo: Flexible Template Insertion - -@cindex templates -The Tempo package provides a simple way to define powerful templates, or -macros, if you wish. It is mainly intended for, but not limited to, -programmers to be used for creating shortcuts for editing -certain kinds of documents. - -@findex tempo-backward-mark -@findex tempo-forward-mark -A template is defined as a list of items to be inserted in the current -buffer at point. Some can be simple strings, while others can control -formatting or define special points of interest in the inserted text. -@kbd{M-x tempo-backward-mark} and @kbd{M-x tempo-forward-mark} can be -used to jump between such points. - -More flexible templates can be created by including Lisp symbols, which -will be evaluated as variables, or lists, which will be evaluated -as Lisp expressions. Automatic completion of specified tags to expanded -templates can be provided. - -@findex tempo-define-template -See the documentation for @code{tempo-define-template} for the different -items that can be used to define a tempo template with a command for -inserting it. - -See the commentary in @file{tempo.el} for more information on using the -Tempo package. - -@node Hippie Expand -@chapter `Hippie' Expansion - -@findex hippie-expand -@kindex M-/ -@vindex hippie-expand-try-functions-list -@kbd{M-x hippie-expand} is a single command providing a variety of -completions and expansions. Called repeatedly, it tries all possible -completions in succession. - -Which ones to try, and in which order, is determined by the contents of -the customizable option @code{hippie-expand-try-functions-list}. Much -customization of the expansion behavior can be made by changing the -order of, removing, or inserting new functions in this list. Given a -positive numeric argument, @kbd{M-x hippie-expand} jumps directly that -number of functions forward in this list. Given some other argument (a -negative argument or just @kbd{C-u}) it undoes the tried completion. - -See the commentary in @file{hippie-exp.el} for more information on the -possibilities. - -Typically you would bind @code{hippie-expand} to @kbd{M-/} with -@code{dabbrev-expand}, the standard binding of @kbd{M-/}, providing one -of the expansion possibilities. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@node Command Index -@unnumbered Command Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@bye diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi deleted file mode 100644 index 48252ceb327..00000000000 --- a/doc/misc/calc.texi +++ /dev/null @@ -1,36957 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header (This is for running Texinfo on a region.) -@c smallbook -@setfilename ../../info/calc -@c [title] -@settitle GNU Emacs Calc Manual -@setchapternewpage odd -@comment %**end of header (This is for running Texinfo on a region.) - -@include emacsver.texi - -@c The following macros are used for conditional output for single lines. -@c @texline foo -@c `foo' will appear only in TeX output -@c @infoline foo -@c `foo' will appear only in non-TeX output - -@c @expr{expr} will typeset an expression; -@c $x$ in TeX, @samp{x} otherwise. - -@iftex -@macro texline -@end macro -@alias infoline=comment -@alias expr=math -@alias tfn=code -@alias mathit=expr -@alias summarykey=key -@macro cpi{} -@math{@pi{}} -@end macro -@macro cpiover{den} -@math{@pi/\den\} -@end macro -@end iftex - -@ifnottex -@alias texline=comment -@macro infoline{stuff} -\stuff\ -@end macro -@alias expr=samp -@alias tfn=t -@alias mathit=i -@macro summarykey{ky} -\ky\ -@end macro -@macro cpi{} -@expr{pi} -@end macro -@macro cpiover{den} -@expr{pi/\den\} -@end macro -@end ifnottex - - -@tex -% Suggested by Karl Berry -\gdef\!{\mskip-\thinmuskip} -@end tex - -@c Fix some other things specifically for this manual. -@iftex -@finalout -@mathcode`@:=`@: @c Make Calc fractions come out right in math mode -@tex -\gdef\coloneq{\mathrel{\mathord:\mathord=}} - -\gdef\beforedisplay{\vskip-10pt} -\gdef\afterdisplay{\vskip-5pt} -\gdef\beforedisplayh{\vskip-25pt} -\gdef\afterdisplayh{\vskip-10pt} -@end tex -@newdimen@kyvpos @kyvpos=0pt -@newdimen@kyhpos @kyhpos=0pt -@newcount@calcclubpenalty @calcclubpenalty=1000 -@ignore -@newcount@calcpageno -@newtoks@calcoldeverypar @calcoldeverypar=@everypar -@everypar={@calceverypar@the@calcoldeverypar} -@ifx@ninett@undefinedzzz@font@ninett=cmtt9@fi -@catcode`@\=0 \catcode`\@=11 -\r@ggedbottomtrue -\catcode`\@=0 @catcode`@\=@active -@end ignore -@end iftex - -@copying -@ifinfo -This file documents Calc, the GNU Emacs calculator. -@end ifinfo -@ifnotinfo -This file documents Calc, the GNU Emacs calculator, included with -GNU Emacs @value{EMACSVER}. -@end ifnotinfo - -Copyright @copyright{} 1990-1991, 2001-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being just ``GNU GENERAL PUBLIC LICENSE'', with the -Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the section -entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Calc: (calc). Advanced desk calculator and mathematical tool. -@end direntry - -@titlepage -@sp 6 -@center @titlefont{Calc Manual} -@sp 4 -@center GNU Emacs Calc -@c [volume] -@sp 5 -@center Dave Gillespie -@center daveg@@synaptics.com -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - - -@summarycontents - -@c [end] - -@contents - -@c [begin] -@ifnottex -@node Top, Getting Started, (dir), (dir) -@chapter The GNU Emacs Calculator - -@noindent -@dfn{Calc} is an advanced desk calculator and mathematical tool -written by Dave Gillespie that runs as part of the GNU Emacs environment. - -This manual, also written (mostly) by Dave Gillespie, is divided into -three major parts: ``Getting Started,'' the ``Calc Tutorial,'' and the -``Calc Reference.'' The Tutorial introduces all the major aspects of -Calculator use in an easy, hands-on way. The remainder of the manual is -a complete reference to the features of the Calculator. -@end ifnottex - -@ifinfo -For help in the Emacs Info system (which you are using to read this -file), type @kbd{?}. (You can also type @kbd{h} to run through a -longer Info tutorial.) -@end ifinfo - -@insertcopying - -@menu -* Getting Started:: General description and overview. -@ifinfo -* Interactive Tutorial:: -@end ifinfo -* Tutorial:: A step-by-step introduction for beginners. - -* Introduction:: Introduction to the Calc reference manual. -* Data Types:: Types of objects manipulated by Calc. -* Stack and Trail:: Manipulating the stack and trail buffers. -* Mode Settings:: Adjusting display format and other modes. -* Arithmetic:: Basic arithmetic functions. -* Scientific Functions:: Transcendentals and other scientific functions. -* Matrix Functions:: Operations on vectors and matrices. -* Algebra:: Manipulating expressions algebraically. -* Units:: Operations on numbers with units. -* Store and Recall:: Storing and recalling variables. -* Graphics:: Commands for making graphs of data. -* Kill and Yank:: Moving data into and out of Calc. -* Keypad Mode:: Operating Calc from a keypad. -* Embedded Mode:: Working with formulas embedded in a file. -* Programming:: Calc as a programmable calculator. - -* Copying:: How you can copy and share Calc. -* GNU Free Documentation License:: The license for this documentation. -* Customizing Calc:: Customizing Calc. -* Reporting Bugs:: How to report bugs and make suggestions. - -* Summary:: Summary of Calc commands and functions. - -* Key Index:: The standard Calc key sequences. -* Command Index:: The interactive Calc commands. -* Function Index:: Functions (in algebraic formulas). -* Concept Index:: General concepts. -* Variable Index:: Variables used by Calc (both user and internal). -* Lisp Function Index:: Internal Lisp math functions. -@end menu - -@ifinfo -@node Getting Started, Interactive Tutorial, Top, Top -@end ifinfo -@ifnotinfo -@node Getting Started, Tutorial, Top, Top -@end ifnotinfo -@chapter Getting Started -@noindent -This chapter provides a general overview of Calc, the GNU Emacs -Calculator: What it is, how to start it and how to exit from it, -and what are the various ways that it can be used. - -@menu -* What is Calc:: -* About This Manual:: -* Notations Used in This Manual:: -* Demonstration of Calc:: -* Using Calc:: -* History and Acknowledgements:: -@end menu - -@node What is Calc, About This Manual, Getting Started, Getting Started -@section What is Calc? - -@noindent -@dfn{Calc} is an advanced calculator and mathematical tool that runs as -part of the GNU Emacs environment. Very roughly based on the HP-28/48 -series of calculators, its many features include: - -@itemize @bullet -@item -Choice of algebraic or RPN (stack-based) entry of calculations. - -@item -Arbitrary precision integers and floating-point numbers. - -@item -Arithmetic on rational numbers, complex numbers (rectangular and polar), -error forms with standard deviations, open and closed intervals, vectors -and matrices, dates and times, infinities, sets, quantities with units, -and algebraic formulas. - -@item -Mathematical operations such as logarithms and trigonometric functions. - -@item -Programmer's features (bitwise operations, non-decimal numbers). - -@item -Financial functions such as future value and internal rate of return. - -@item -Number theoretical features such as prime factorization and arithmetic -modulo @var{m} for any @var{m}. - -@item -Algebraic manipulation features, including symbolic calculus. - -@item -Moving data to and from regular editing buffers. - -@item -Embedded mode for manipulating Calc formulas and data directly -inside any editing buffer. - -@item -Graphics using GNUPLOT, a versatile (and free) plotting program. - -@item -Easy programming using keyboard macros, algebraic formulas, -algebraic rewrite rules, or extended Emacs Lisp. -@end itemize - -Calc tries to include a little something for everyone; as a result it is -large and might be intimidating to the first-time user. If you plan to -use Calc only as a traditional desk calculator, all you really need to -read is the ``Getting Started'' chapter of this manual and possibly the -first few sections of the tutorial. As you become more comfortable with -the program you can learn its additional features. Calc does not -have the scope and depth of a fully-functional symbolic math package, -but Calc has the advantages of convenience, portability, and freedom. - -@node About This Manual, Notations Used in This Manual, What is Calc, Getting Started -@section About This Manual - -@noindent -This document serves as a complete description of the GNU Emacs -Calculator. It works both as an introduction for novices and as -a reference for experienced users. While it helps to have some -experience with GNU Emacs in order to get the most out of Calc, -this manual ought to be readable even if you don't know or use Emacs -regularly. - -This manual is divided into three major parts:@: the ``Getting -Started'' chapter you are reading now, the Calc tutorial, and the Calc -reference manual. -@c [when-split] -@c This manual has been printed in two volumes, the @dfn{Tutorial} and the -@c @dfn{Reference}. Both volumes include a copy of the ``Getting Started'' -@c chapter. - -If you are in a hurry to use Calc, there is a brief ``demonstration'' -below which illustrates the major features of Calc in just a couple of -pages. If you don't have time to go through the full tutorial, this -will show you everything you need to know to begin. -@xref{Demonstration of Calc}. - -The tutorial chapter walks you through the various parts of Calc -with lots of hands-on examples and explanations. If you are new -to Calc and you have some time, try going through at least the -beginning of the tutorial. The tutorial includes about 70 exercises -with answers. These exercises give you some guided practice with -Calc, as well as pointing out some interesting and unusual ways -to use its features. - -The reference section discusses Calc in complete depth. You can read -the reference from start to finish if you want to learn every aspect -of Calc. Or, you can look in the table of contents or the Concept -Index to find the parts of the manual that discuss the things you -need to know. - -@c @cindex Marginal notes -Every Calc keyboard command is listed in the Calc Summary, and also -in the Key Index. Algebraic functions, @kbd{M-x} commands, and -variables also have their own indices. -@c @texline Each -@c @infoline In the printed manual, each -@c paragraph that is referenced in the Key or Function Index is marked -@c in the margin with its index entry. - -@c [fix-ref Help Commands] -You can access this manual on-line at any time within Calc by pressing -the @kbd{h i} key sequence. Outside of the Calc window, you can press -@kbd{C-x * i} to read the manual on-line. From within Calc the command -@kbd{h t} will jump directly to the Tutorial; from outside of Calc the -command @kbd{C-x * t} will jump to the Tutorial and start Calc if -necessary. Pressing @kbd{h s} or @kbd{C-x * s} will take you directly -to the Calc Summary. Within Calc, you can also go to the part of the -manual describing any Calc key, function, or variable using -@w{@kbd{h k}}, @kbd{h f}, or @kbd{h v}, respectively. @xref{Help Commands}. - -@ifnottex -The Calc manual can be printed, but because the manual is so large, you -should only make a printed copy if you really need it. To print the -manual, you will need the @TeX{} typesetting program (this is a free -program by Donald Knuth at Stanford University) as well as the -@file{texindex} program and @file{texinfo.tex} file, both of which can -be obtained from the FSF as part of the @code{texinfo} package. -To print the Calc manual in one huge tome, you will need the -source code to this manual, @file{calc.texi}, available as part of the -Emacs source. Once you have this file, type @kbd{texi2dvi calc.texi}. -Alternatively, change to the @file{man} subdirectory of the Emacs -source distribution, and type @kbd{make calc.dvi}. (Don't worry if you -get some ``overfull box'' warnings while @TeX{} runs.) -The result will be a device-independent output file called -@file{calc.dvi}, which you must print in whatever way is right -for your system. On many systems, the command is - -@example -lpr -d calc.dvi -@end example - -@noindent -or - -@example -dvips calc.dvi -@end example -@end ifnottex -@c Printed copies of this manual are also available from the Free Software -@c Foundation. - -@node Notations Used in This Manual, Demonstration of Calc, About This Manual, Getting Started -@section Notations Used in This Manual - -@noindent -This section describes the various notations that are used -throughout the Calc manual. - -In keystroke sequences, uppercase letters mean you must hold down -the shift key while typing the letter. Keys pressed with Control -held down are shown as @kbd{C-x}. Keys pressed with Meta held down -are shown as @kbd{M-x}. Other notations are @key{RET} for the -Return key, @key{SPC} for the space bar, @key{TAB} for the Tab key, -@key{DEL} for the Delete key, and @key{LFD} for the Line-Feed key. -The @key{DEL} key is called Backspace on some keyboards, it is -whatever key you would use to correct a simple typing error when -regularly using Emacs. - -(If you don't have the @key{LFD} or @key{TAB} keys on your keyboard, -the @kbd{C-j} and @kbd{C-i} keys are equivalent to them, respectively. -If you don't have a Meta key, look for Alt or Extend Char. You can -also press @key{ESC} or @kbd{C-[} first to get the same effect, so -that @kbd{M-x}, @kbd{@key{ESC} x}, and @kbd{C-[ x} are all equivalent.) - -Sometimes the @key{RET} key is not shown when it is ``obvious'' -that you must press @key{RET} to proceed. For example, the @key{RET} -is usually omitted in key sequences like @kbd{M-x calc-keypad @key{RET}}. - -Commands are generally shown like this: @kbd{p} (@code{calc-precision}) -or @kbd{C-x * k} (@code{calc-keypad}). This means that the command is -normally used by pressing the @kbd{p} key or @kbd{C-x * k} key sequence, -but it also has the full-name equivalent shown, e.g., @kbd{M-x calc-precision}. - -Commands that correspond to functions in algebraic notation -are written: @kbd{C} (@code{calc-cos}) [@code{cos}]. This means -the @kbd{C} key is equivalent to @kbd{M-x calc-cos}, and that -the corresponding function in an algebraic-style formula would -be @samp{cos(@var{x})}. - -A few commands don't have key equivalents: @code{calc-sincos} -[@code{sincos}]. - -@node Demonstration of Calc, Using Calc, Notations Used in This Manual, Getting Started -@section A Demonstration of Calc - -@noindent -@cindex Demonstration of Calc -This section will show some typical small problems being solved with -Calc. The focus is more on demonstration than explanation, but -everything you see here will be covered more thoroughly in the -Tutorial. - -To begin, start Emacs if necessary (usually the command @code{emacs} -does this), and type @kbd{C-x * c} to start the -Calculator. (You can also use @kbd{M-x calc} if this doesn't work. -@xref{Starting Calc}, for various ways of starting the Calculator.) - -Be sure to type all the sample input exactly, especially noting the -difference between lower-case and upper-case letters. Remember, -@key{RET}, @key{TAB}, @key{DEL}, and @key{SPC} are the Return, Tab, -Delete, and Space keys. - -@strong{RPN calculation.} In RPN, you type the input number(s) first, -then the command to operate on the numbers. - -@noindent -Type @kbd{2 @key{RET} 3 + Q} to compute -@texline @math{\sqrt{2+3} = 2.2360679775}. -@infoline the square root of 2+3, which is 2.2360679775. - -@noindent -Type @kbd{P 2 ^} to compute -@texline @math{\pi^2 = 9.86960440109}. -@infoline the value of `pi' squared, 9.86960440109. - -@noindent -Type @key{TAB} to exchange the order of these two results. - -@noindent -Type @kbd{- I H S} to subtract these results and compute the Inverse -Hyperbolic sine of the difference, 2.72996136574. - -@noindent -Type @key{DEL} to erase this result. - -@strong{Algebraic calculation.} You can also enter calculations using -conventional ``algebraic'' notation. To enter an algebraic formula, -use the apostrophe key. - -@noindent -Type @kbd{' sqrt(2+3) @key{RET}} to compute -@texline @math{\sqrt{2+3}}. -@infoline the square root of 2+3. - -@noindent -Type @kbd{' pi^2 @key{RET}} to enter -@texline @math{\pi^2}. -@infoline `pi' squared. -To evaluate this symbolic formula as a number, type @kbd{=}. - -@noindent -Type @kbd{' arcsinh($ - $$) @key{RET}} to subtract the second-most-recent -result from the most-recent and compute the Inverse Hyperbolic sine. - -@strong{Keypad mode.} If you are using the X window system, press -@w{@kbd{C-x * k}} to get Keypad mode. (If you don't use X, skip to -the next section.) - -@noindent -Click on the @key{2}, @key{ENTER}, @key{3}, @key{+}, and @key{SQRT} -``buttons'' using your left mouse button. - -@noindent -Click on @key{PI}, @key{2}, and @tfn{y^x}. - -@noindent -Click on @key{INV}, then @key{ENTER} to swap the two results. - -@noindent -Click on @key{-}, @key{INV}, @key{HYP}, and @key{SIN}. - -@noindent -Click on @key{<-} to erase the result, then click @key{OFF} to turn -the Keypad Calculator off. - -@strong{Grabbing data.} Type @kbd{C-x * x} if necessary to exit Calc. -Now select the following numbers as an Emacs region: ``Mark'' the -front of the list by typing @kbd{C-@key{SPC}} or @kbd{C-@@} there, -then move to the other end of the list. (Either get this list from -the on-line copy of this manual, accessed by @w{@kbd{C-x * i}}, or just -type these numbers into a scratch file.) Now type @kbd{C-x * g} to -``grab'' these numbers into Calc. - -@example -@group -1.23 1.97 -1.6 2 -1.19 1.08 -@end group -@end example - -@noindent -The result @samp{[1.23, 1.97, 1.6, 2, 1.19, 1.08]} is a Calc ``vector.'' -Type @w{@kbd{V R +}} to compute the sum of these numbers. - -@noindent -Type @kbd{U} to Undo this command, then type @kbd{V R *} to compute -the product of the numbers. - -@noindent -You can also grab data as a rectangular matrix. Place the cursor on -the upper-leftmost @samp{1} and set the mark, then move to just after -the lower-right @samp{8} and press @kbd{C-x * r}. - -@noindent -Type @kbd{v t} to transpose this -@texline @math{3\times2} -@infoline 3x2 -matrix into a -@texline @math{2\times3} -@infoline 2x3 -matrix. Type @w{@kbd{v u}} to unpack the rows into two separate -vectors. Now type @w{@kbd{V R + @key{TAB} V R +}} to compute the sums -of the two original columns. (There is also a special -grab-and-sum-columns command, @kbd{C-x * :}.) - -@strong{Units conversion.} Units are entered algebraically. -Type @w{@kbd{' 43 mi/hr @key{RET}}} to enter the quantity 43 miles-per-hour. -Type @w{@kbd{u c km/hr @key{RET}}}. Type @w{@kbd{u c m/s @key{RET}}}. - -@strong{Date arithmetic.} Type @kbd{t N} to get the current date and -time. Type @kbd{90 +} to find the date 90 days from now. Type -@kbd{' <25 dec 87> @key{RET}} to enter a date, then @kbd{- 7 /} to see how -many weeks have passed since then. - -@strong{Algebra.} Algebraic entries can also include formulas -or equations involving variables. Type @kbd{@w{' [x + y} = a, x y = 1] @key{RET}} -to enter a pair of equations involving three variables. -(Note the leading apostrophe in this example; also, note that the space -in @samp{x y} is required.) Type @w{@kbd{a S x,y @key{RET}}} to solve -these equations for the variables @expr{x} and @expr{y}. - -@noindent -Type @kbd{d B} to view the solutions in more readable notation. -Type @w{@kbd{d C}} to view them in C language notation, @kbd{d T} -to view them in the notation for the @TeX{} typesetting system, -and @kbd{d L} to view them in the notation for the La@TeX{} typesetting -system. Type @kbd{d N} to return to normal notation. - -@noindent -Type @kbd{7.5}, then @kbd{s l a @key{RET}} to let @expr{a = 7.5} in these formulas. -(That's the letter @kbd{l}, not the numeral @kbd{1}.) - -@ifnotinfo -@strong{Help functions.} You can read about any command in the on-line -manual. Type @kbd{C-x * c} to return to Calc after each of these -commands: @kbd{h k t N} to read about the @kbd{t N} command, -@kbd{h f sqrt @key{RET}} to read about the @code{sqrt} function, and -@kbd{h s} to read the Calc summary. -@end ifnotinfo -@ifinfo -@strong{Help functions.} You can read about any command in the on-line -manual. Remember to type the letter @kbd{l}, then @kbd{C-x * c}, to -return here after each of these commands: @w{@kbd{h k t N}} to read -about the @w{@kbd{t N}} command, @kbd{h f sqrt @key{RET}} to read about the -@code{sqrt} function, and @kbd{h s} to read the Calc summary. -@end ifinfo - -Press @key{DEL} repeatedly to remove any leftover results from the stack. -To exit from Calc, press @kbd{q} or @kbd{C-x * c} again. - -@node Using Calc, History and Acknowledgements, Demonstration of Calc, Getting Started -@section Using Calc - -@noindent -Calc has several user interfaces that are specialized for -different kinds of tasks. As well as Calc's standard interface, -there are Quick mode, Keypad mode, and Embedded mode. - -@menu -* Starting Calc:: -* The Standard Interface:: -* Quick Mode Overview:: -* Keypad Mode Overview:: -* Standalone Operation:: -* Embedded Mode Overview:: -* Other C-x * Commands:: -@end menu - -@node Starting Calc, The Standard Interface, Using Calc, Using Calc -@subsection Starting Calc - -@noindent -On most systems, you can type @kbd{C-x *} to start the Calculator. -The key sequence @kbd{C-x *} is bound to the command @code{calc-dispatch}, -which can be rebound if convenient (@pxref{Customizing Calc}). - -When you press @kbd{C-x *}, Emacs waits for you to press a second key to -complete the command. In this case, you will follow @kbd{C-x *} with a -letter (upper- or lower-case, it doesn't matter for @kbd{C-x *}) that says -which Calc interface you want to use. - -To get Calc's standard interface, type @kbd{C-x * c}. To get -Keypad mode, type @kbd{C-x * k}. Type @kbd{C-x * ?} to get a brief -list of the available options, and type a second @kbd{?} to get -a complete list. - -To ease typing, @kbd{C-x * *} also works to start Calc. It starts the -same interface (either @kbd{C-x * c} or @w{@kbd{C-x * k}}) that you last -used, selecting the @kbd{C-x * c} interface by default. - -If @kbd{C-x *} doesn't work for you, you can always type explicit -commands like @kbd{M-x calc} (for the standard user interface) or -@w{@kbd{M-x calc-keypad}} (for Keypad mode). First type @kbd{M-x} -(that's Meta with the letter @kbd{x}), then, at the prompt, -type the full command (like @kbd{calc-keypad}) and press Return. - -The same commands (like @kbd{C-x * c} or @kbd{C-x * *}) that start -the Calculator also turn it off if it is already on. - -@node The Standard Interface, Quick Mode Overview, Starting Calc, Using Calc -@subsection The Standard Calc Interface - -@noindent -@cindex Standard user interface -Calc's standard interface acts like a traditional RPN calculator, -operated by the normal Emacs keyboard. When you type @kbd{C-x * c} -to start the Calculator, the Emacs screen splits into two windows -with the file you were editing on top and Calc on the bottom. - -@smallexample -@group - -... ---**-Emacs: myfile (Fundamental)----All---------------------- ---- Emacs Calculator Mode --- |Emacs Calculator Trail -2: 17.3 | 17.3 -1: -5 | 3 - . | 2 - | 4 - | * 8 - | ->-5 - | ---%*-Calc: 12 Deg (Calculator)----All----- --%*- *Calc Trail* -@end group -@end smallexample - -In this figure, the mode-line for @file{myfile} has moved up and the -``Calculator'' window has appeared below it. As you can see, Calc -actually makes two windows side-by-side. The lefthand one is -called the @dfn{stack window} and the righthand one is called the -@dfn{trail window.} The stack holds the numbers involved in the -calculation you are currently performing. The trail holds a complete -record of all calculations you have done. In a desk calculator with -a printer, the trail corresponds to the paper tape that records what -you do. - -In this case, the trail shows that four numbers (17.3, 3, 2, and 4) -were first entered into the Calculator, then the 2 and 4 were -multiplied to get 8, then the 3 and 8 were subtracted to get @mathit{-5}. -(The @samp{>} symbol shows that this was the most recent calculation.) -The net result is the two numbers 17.3 and @mathit{-5} sitting on the stack. - -Most Calculator commands deal explicitly with the stack only, but -there is a set of commands that allow you to search back through -the trail and retrieve any previous result. - -Calc commands use the digits, letters, and punctuation keys. -Shifted (i.e., upper-case) letters are different from lowercase -letters. Some letters are @dfn{prefix} keys that begin two-letter -commands. For example, @kbd{e} means ``enter exponent'' and shifted -@kbd{E} means @expr{e^x}. With the @kbd{d} (``display modes'') prefix -the letter ``e'' takes on very different meanings: @kbd{d e} means -``engineering notation'' and @kbd{d E} means ``@dfn{eqn} language mode.'' - -There is nothing stopping you from switching out of the Calc -window and back into your editing window, say by using the Emacs -@w{@kbd{C-x o}} (@code{other-window}) command. When the cursor is -inside a regular window, Emacs acts just like normal. When the -cursor is in the Calc stack or trail windows, keys are interpreted -as Calc commands. - -When you quit by pressing @kbd{C-x * c} a second time, the Calculator -windows go away but the actual Stack and Trail are not gone, just -hidden. When you press @kbd{C-x * c} once again you will get the -same stack and trail contents you had when you last used the -Calculator. - -The Calculator does not remember its state between Emacs sessions. -Thus if you quit Emacs and start it again, @kbd{C-x * c} will give you -a fresh stack and trail. There is a command (@kbd{m m}) that lets -you save your favorite mode settings between sessions, though. -One of the things it saves is which user interface (standard or -Keypad) you last used; otherwise, a freshly started Emacs will -always treat @kbd{C-x * *} the same as @kbd{C-x * c}. - -The @kbd{q} key is another equivalent way to turn the Calculator off. - -If you type @kbd{C-x * b} first and then @kbd{C-x * c}, you get a -full-screen version of Calc (@code{full-calc}) in which the stack and -trail windows are still side-by-side but are now as tall as the whole -Emacs screen. When you press @kbd{q} or @kbd{C-x * c} again to quit, -the file you were editing before reappears. The @kbd{C-x * b} key -switches back and forth between ``big'' full-screen mode and the -normal partial-screen mode. - -Finally, @kbd{C-x * o} (@code{calc-other-window}) is like @kbd{C-x * c} -except that the Calc window is not selected. The buffer you were -editing before remains selected instead. If you are in a Calc window, -then @kbd{C-x * o} will switch you out of it, being careful not to -switch you to the Calc Trail window. So @kbd{C-x * o} is a handy -way to switch out of Calc momentarily to edit your file; you can then -type @kbd{C-x * c} to switch back into Calc when you are done. - -@node Quick Mode Overview, Keypad Mode Overview, The Standard Interface, Using Calc -@subsection Quick Mode (Overview) - -@noindent -@dfn{Quick mode} is a quick way to use Calc when you don't need the -full complexity of the stack and trail. To use it, type @kbd{C-x * q} -(@code{quick-calc}) in any regular editing buffer. - -Quick mode is very simple: It prompts you to type any formula in -standard algebraic notation (like @samp{4 - 2/3}) and then displays -the result at the bottom of the Emacs screen (@mathit{3.33333333333} -in this case). You are then back in the same editing buffer you -were in before, ready to continue editing or to type @kbd{C-x * q} -again to do another quick calculation. The result of the calculation -will also be in the Emacs ``kill ring'' so that a @kbd{C-y} command -at this point will yank the result into your editing buffer. - -Calc mode settings affect Quick mode, too, though you will have to -go into regular Calc (with @kbd{C-x * c}) to change the mode settings. - -@c [fix-ref Quick Calculator mode] -@xref{Quick Calculator}, for further information. - -@node Keypad Mode Overview, Standalone Operation, Quick Mode Overview, Using Calc -@subsection Keypad Mode (Overview) - -@noindent -@dfn{Keypad mode} is a mouse-based interface to the Calculator. -It is designed for use with terminals that support a mouse. If you -don't have a mouse, you will have to operate Keypad mode with your -arrow keys (which is probably more trouble than it's worth). - -Type @kbd{C-x * k} to turn Keypad mode on or off. Once again you -get two new windows, this time on the righthand side of the screen -instead of at the bottom. The upper window is the familiar Calc -Stack; the lower window is a picture of a typical calculator keypad. - -@tex -\dimen0=\pagetotal% -\advance \dimen0 by 24\baselineskip% -\ifdim \dimen0>\pagegoal \vfill\eject \fi% -\medskip -@end tex -@smallexample -@group -|--- Emacs Calculator Mode --- -|2: 17.3 -|1: -5 -| . -|--%*-Calc: 12 Deg (Calcul -|----+----+--Calc---+----+----1 -|FLR |CEIL|RND |TRNC|CLN2|FLT | -|----+----+----+----+----+----| -| LN |EXP | |ABS |IDIV|MOD | -|----+----+----+----+----+----| -|SIN |COS |TAN |SQRT|y^x |1/x | -|----+----+----+----+----+----| -| ENTER |+/- |EEX |UNDO| <- | -|-----+---+-+--+--+-+---++----| -| INV | 7 | 8 | 9 | / | -|-----+-----+-----+-----+-----| -| HYP | 4 | 5 | 6 | * | -|-----+-----+-----+-----+-----| -|EXEC | 1 | 2 | 3 | - | -|-----+-----+-----+-----+-----| -| OFF | 0 | . | PI | + | -|-----+-----+-----+-----+-----+ -@end group -@end smallexample - -Keypad mode is much easier for beginners to learn, because there -is no need to memorize lots of obscure key sequences. But not all -commands in regular Calc are available on the Keypad. You can -always switch the cursor into the Calc stack window to use -standard Calc commands if you need. Serious Calc users, though, -often find they prefer the standard interface over Keypad mode. - -To operate the Calculator, just click on the ``buttons'' of the -keypad using your left mouse button. To enter the two numbers -shown here you would click @w{@kbd{1 7 .@: 3 ENTER 5 +/- ENTER}}; to -add them together you would then click @kbd{+} (to get 12.3 on -the stack). - -If you click the right mouse button, the top three rows of the -keypad change to show other sets of commands, such as advanced -math functions, vector operations, and operations on binary -numbers. - -Because Keypad mode doesn't use the regular keyboard, Calc leaves -the cursor in your original editing buffer. You can type in -this buffer in the usual way while also clicking on the Calculator -keypad. One advantage of Keypad mode is that you don't need an -explicit command to switch between editing and calculating. - -If you press @kbd{C-x * b} first, you get a full-screen Keypad mode -(@code{full-calc-keypad}) with three windows: The keypad in the lower -left, the stack in the lower right, and the trail on top. - -@c [fix-ref Keypad Mode] -@xref{Keypad Mode}, for further information. - -@node Standalone Operation, Embedded Mode Overview, Keypad Mode Overview, Using Calc -@subsection Standalone Operation - -@noindent -@cindex Standalone Operation -If you are not in Emacs at the moment but you wish to use Calc, -you must start Emacs first. If all you want is to run Calc, you -can give the commands: - -@example -emacs -f full-calc -@end example - -@noindent -or - -@example -emacs -f full-calc-keypad -@end example - -@noindent -which run a full-screen Calculator (as if by @kbd{C-x * b C-x * c}) or -a full-screen X-based Calculator (as if by @kbd{C-x * b C-x * k}). -In standalone operation, quitting the Calculator (by pressing -@kbd{q} or clicking on the keypad @key{EXIT} button) quits Emacs -itself. - -@node Embedded Mode Overview, Other C-x * Commands, Standalone Operation, Using Calc -@subsection Embedded Mode (Overview) - -@noindent -@dfn{Embedded mode} is a way to use Calc directly from inside an -editing buffer. Suppose you have a formula written as part of a -document like this: - -@smallexample -@group -The derivative of - - ln(ln(x)) - -is -@end group -@end smallexample - -@noindent -and you wish to have Calc compute and format the derivative for -you and store this derivative in the buffer automatically. To -do this with Embedded mode, first copy the formula down to where -you want the result to be, leaving a blank line before and after the -formula: - -@smallexample -@group -The derivative of - - ln(ln(x)) - -is - - ln(ln(x)) -@end group -@end smallexample - -Now, move the cursor onto this new formula and press @kbd{C-x * e}. -Calc will read the formula (using the surrounding blank lines to tell -how much text to read), then push this formula (invisibly) onto the Calc -stack. The cursor will stay on the formula in the editing buffer, but -the line with the formula will now appear as it would on the Calc stack -(in this case, it will be left-aligned) and the buffer's mode line will -change to look like the Calc mode line (with mode indicators like -@samp{12 Deg} and so on). Even though you are still in your editing -buffer, the keyboard now acts like the Calc keyboard, and any new result -you get is copied from the stack back into the buffer. To take the -derivative, you would type @kbd{a d x @key{RET}}. - -@smallexample -@group -The derivative of - - ln(ln(x)) - -is - -1 / ln(x) x -@end group -@end smallexample - -(Note that by default, Calc gives division lower precedence than multiplication, -so that @samp{1 / ln(x) x} is equivalent to @samp{1 / (ln(x) x)}.) - -To make this look nicer, you might want to press @kbd{d =} to center -the formula, and even @kbd{d B} to use Big display mode. - -@smallexample -@group -The derivative of - - ln(ln(x)) - -is -% [calc-mode: justify: center] -% [calc-mode: language: big] - - 1 - ------- - ln(x) x -@end group -@end smallexample - -Calc has added annotations to the file to help it remember the modes -that were used for this formula. They are formatted like comments -in the @TeX{} typesetting language, just in case you are using @TeX{} or -La@TeX{}. (In this example @TeX{} is not being used, so you might want -to move these comments up to the top of the file or otherwise put them -out of the way.) - -As an extra flourish, we can add an equation number using a -righthand label: Type @kbd{d @} (1) @key{RET}}. - -@smallexample -@group -% [calc-mode: justify: center] -% [calc-mode: language: big] -% [calc-mode: right-label: " (1)"] - - 1 - ------- (1) - ln(x) x -@end group -@end smallexample - -To leave Embedded mode, type @kbd{C-x * e} again. The mode line -and keyboard will revert to the way they were before. - -The related command @kbd{C-x * w} operates on a single word, which -generally means a single number, inside text. It searches for an -expression which ``looks'' like a number containing the point. -Here's an example of its use: - -@smallexample -A slope of one-third corresponds to an angle of 1 degrees. -@end smallexample - -Place the cursor on the @samp{1}, then type @kbd{C-x * w} to enable -Embedded mode on that number. Now type @kbd{3 /} (to get one-third), -and @kbd{I T} (the Inverse Tangent converts a slope into an angle), -then @w{@kbd{C-x * w}} again to exit Embedded mode. - -@smallexample -A slope of one-third corresponds to an angle of 18.4349488229 degrees. -@end smallexample - -@c [fix-ref Embedded Mode] -@xref{Embedded Mode}, for full details. - -@node Other C-x * Commands, , Embedded Mode Overview, Using Calc -@subsection Other @kbd{C-x *} Commands - -@noindent -Two more Calc-related commands are @kbd{C-x * g} and @kbd{C-x * r}, -which ``grab'' data from a selected region of a buffer into the -Calculator. The region is defined in the usual Emacs way, by -a ``mark'' placed at one end of the region, and the Emacs -cursor or ``point'' placed at the other. - -The @kbd{C-x * g} command reads the region in the usual left-to-right, -top-to-bottom order. The result is packaged into a Calc vector -of numbers and placed on the stack. Calc (in its standard -user interface) is then started. Type @kbd{v u} if you want -to unpack this vector into separate numbers on the stack. Also, -@kbd{C-u C-x * g} interprets the region as a single number or -formula. - -The @kbd{C-x * r} command reads a rectangle, with the point and -mark defining opposite corners of the rectangle. The result -is a matrix of numbers on the Calculator stack. - -Complementary to these is @kbd{C-x * y}, which ``yanks'' the -value at the top of the Calc stack back into an editing buffer. -If you type @w{@kbd{C-x * y}} while in such a buffer, the value is -yanked at the current position. If you type @kbd{C-x * y} while -in the Calc buffer, Calc makes an educated guess as to which -editing buffer you want to use. The Calc window does not have -to be visible in order to use this command, as long as there -is something on the Calc stack. - -Here, for reference, is the complete list of @kbd{C-x *} commands. -The shift, control, and meta keys are ignored for the keystroke -following @kbd{C-x *}. - -@noindent -Commands for turning Calc on and off: - -@table @kbd -@item * -Turn Calc on or off, employing the same user interface as last time. - -@item =, +, -, /, \, &, # -Alternatives for @kbd{*}. - -@item C -Turn Calc on or off using its standard bottom-of-the-screen -interface. If Calc is already turned on but the cursor is not -in the Calc window, move the cursor into the window. - -@item O -Same as @kbd{C}, but don't select the new Calc window. If -Calc is already turned on and the cursor is in the Calc window, -move it out of that window. - -@item B -Control whether @kbd{C-x * c} and @kbd{C-x * k} use the full screen. - -@item Q -Use Quick mode for a single short calculation. - -@item K -Turn Calc Keypad mode on or off. - -@item E -Turn Calc Embedded mode on or off at the current formula. - -@item J -Turn Calc Embedded mode on or off, select the interesting part. - -@item W -Turn Calc Embedded mode on or off at the current word (number). - -@item Z -Turn Calc on in a user-defined way, as defined by a @kbd{Z I} command. - -@item X -Quit Calc; turn off standard, Keypad, or Embedded mode if on. -(This is like @kbd{q} or @key{OFF} inside of Calc.) -@end table -@iftex -@sp 2 -@end iftex - -@noindent -Commands for moving data into and out of the Calculator: - -@table @kbd -@item G -Grab the region into the Calculator as a vector. - -@item R -Grab the rectangular region into the Calculator as a matrix. - -@item : -Grab the rectangular region and compute the sums of its columns. - -@item _ -Grab the rectangular region and compute the sums of its rows. - -@item Y -Yank a value from the Calculator into the current editing buffer. -@end table -@iftex -@sp 2 -@end iftex - -@noindent -Commands for use with Embedded mode: - -@table @kbd -@item A -``Activate'' the current buffer. Locate all formulas that -contain @samp{:=} or @samp{=>} symbols and record their locations -so that they can be updated automatically as variables are changed. - -@item D -Duplicate the current formula immediately below and select -the duplicate. - -@item F -Insert a new formula at the current point. - -@item N -Move the cursor to the next active formula in the buffer. - -@item P -Move the cursor to the previous active formula in the buffer. - -@item U -Update (i.e., as if by the @kbd{=} key) the formula at the current point. - -@item ` -Edit (as if by @code{calc-edit}) the formula at the current point. -@end table -@iftex -@sp 2 -@end iftex - -@noindent -Miscellaneous commands: - -@table @kbd -@item I -Run the Emacs Info system to read the Calc manual. -(This is the same as @kbd{h i} inside of Calc.) - -@item T -Run the Emacs Info system to read the Calc Tutorial. - -@item S -Run the Emacs Info system to read the Calc Summary. - -@item L -Load Calc entirely into memory. (Normally the various parts -are loaded only as they are needed.) - -@item M -Read a region of written keystroke names (like @kbd{C-n a b c @key{RET}}) -and record them as the current keyboard macro. - -@item 0 -(This is the ``zero'' digit key.) Reset the Calculator to -its initial state: Empty stack, and initial mode settings. -@end table - -@node History and Acknowledgements, , Using Calc, Getting Started -@section History and Acknowledgements - -@noindent -Calc was originally started as a two-week project to occupy a lull -in the author's schedule. Basically, a friend asked if I remembered -the value of -@texline @math{2^{32}}. -@infoline @expr{2^32}. -I didn't offhand, but I said, ``that's easy, just call up an -@code{xcalc}.'' @code{Xcalc} duly reported that the answer to our -question was @samp{4.294967e+09}---with no way to see the full ten -digits even though we knew they were there in the program's memory! I -was so annoyed, I vowed to write a calculator of my own, once and for -all. - -I chose Emacs Lisp, a) because I had always been curious about it -and b) because, being only a text editor extension language after -all, Emacs Lisp would surely reach its limits long before the project -got too far out of hand. - -To make a long story short, Emacs Lisp turned out to be a distressingly -solid implementation of Lisp, and the humble task of calculating -turned out to be more open-ended than one might have expected. - -Emacs Lisp didn't have built-in floating point math (now it does), so -this had to be simulated in software. In fact, Emacs integers would -only comfortably fit six decimal digits or so---not enough for a decent -calculator. So I had to write my own high-precision integer code as -well, and once I had this I figured that arbitrary-size integers were -just as easy as large integers. Arbitrary floating-point precision was -the logical next step. Also, since the large integer arithmetic was -there anyway it seemed only fair to give the user direct access to it, -which in turn made it practical to support fractions as well as floats. -All these features inspired me to look around for other data types that -might be worth having. - -Around this time, my friend Rick Koshi showed me his nifty new HP-28 -calculator. It allowed the user to manipulate formulas as well as -numerical quantities, and it could also operate on matrices. I -decided that these would be good for Calc to have, too. And once -things had gone this far, I figured I might as well take a look at -serious algebra systems for further ideas. Since these systems did -far more than I could ever hope to implement, I decided to focus on -rewrite rules and other programming features so that users could -implement what they needed for themselves. - -Rick complained that matrices were hard to read, so I put in code to -format them in a 2D style. Once these routines were in place, Big mode -was obligatory. Gee, what other language modes would be useful? - -Scott Hemphill and Allen Knutson, two friends with a strong mathematical -bent, contributed ideas and algorithms for a number of Calc features -including modulo forms, primality testing, and float-to-fraction conversion. - -Units were added at the eager insistence of Mass Sivilotti. Later, -Ulrich Mueller at CERN and Przemek Klosowski at NIST provided invaluable -expert assistance with the units table. As far as I can remember, the -idea of using algebraic formulas and variables to represent units dates -back to an ancient article in Byte magazine about muMath, an early -algebra system for microcomputers. - -Many people have contributed to Calc by reporting bugs and suggesting -features, large and small. A few deserve special mention: Tim Peters, -who helped develop the ideas that led to the selection commands, rewrite -rules, and many other algebra features; -@texline Fran\c{c}ois -@infoline Francois -Pinard, who contributed an early prototype of the Calc Summary appendix -as well as providing valuable suggestions in many other areas of Calc; -Carl Witty, whose eagle eyes discovered many typographical and factual -errors in the Calc manual; Tim Kay, who drove the development of -Embedded mode; Ove Ewerlid, who made many suggestions relating to the -algebra commands and contributed some code for polynomial operations; -Randal Schwartz, who suggested the @code{calc-eval} function; Juha -Sarlin, who first worked out how to split Calc into quickly-loading -parts; Bob Weiner, who helped immensely with the Lucid Emacs port; and -Robert J. Chassell, who suggested the Calc Tutorial and exercises as -well as many other things. - -@cindex Bibliography -@cindex Knuth, Art of Computer Programming -@cindex Numerical Recipes -@c Should these be expanded into more complete references? -Among the books used in the development of Calc were Knuth's @emph{Art -of Computer Programming} (especially volume II, @emph{Seminumerical -Algorithms}); @emph{Numerical Recipes} by Press, Flannery, Teukolsky, -and Vetterling; Bevington's @emph{Data Reduction and Error Analysis -for the Physical Sciences}; @emph{Concrete Mathematics} by Graham, -Knuth, and Patashnik; Steele's @emph{Common Lisp, the Language}; the -@emph{CRC Standard Math Tables} (William H. Beyer, ed.); and -Abramowitz and Stegun's venerable @emph{Handbook of Mathematical -Functions}. Also, of course, Calc could not have been written without -the excellent @emph{GNU Emacs Lisp Reference Manual}, by Bil Lewis and -Dan LaLiberte. - -Final thanks go to Richard Stallman, without whose fine implementations -of the Emacs editor, language, and environment, Calc would have been -finished in two weeks. - -@c [tutorial] - -@ifinfo -@c This node is accessed by the `C-x * t' command. -@node Interactive Tutorial, Tutorial, Getting Started, Top -@chapter Tutorial - -@noindent -Some brief instructions on using the Emacs Info system for this tutorial: - -Press the space bar and Delete keys to go forward and backward in a -section by screenfuls (or use the regular Emacs scrolling commands -for this). - -Press @kbd{n} or @kbd{p} to go to the Next or Previous section. -If the section has a @dfn{menu}, press a digit key like @kbd{1} -or @kbd{2} to go to a sub-section from the menu. Press @kbd{u} to -go back up from a sub-section to the menu it is part of. - -Exercises in the tutorial all have cross-references to the -appropriate page of the ``answers'' section. Press @kbd{f}, then -the exercise number, to see the answer to an exercise. After -you have followed a cross-reference, you can press the letter -@kbd{l} to return to where you were before. - -You can press @kbd{?} at any time for a brief summary of Info commands. - -Press the number @kbd{1} now to enter the first section of the Tutorial. - -@menu -* Tutorial:: -@end menu - -@node Tutorial, Introduction, Interactive Tutorial, Top -@end ifinfo -@ifnotinfo -@node Tutorial, Introduction, Getting Started, Top -@end ifnotinfo -@chapter Tutorial - -@noindent -This chapter explains how to use Calc and its many features, in -a step-by-step, tutorial way. You are encouraged to run Calc and -work along with the examples as you read (@pxref{Starting Calc}). -If you are already familiar with advanced calculators, you may wish -@c [not-split] -to skip on to the rest of this manual. -@c [when-split] -@c to skip on to volume II of this manual, the @dfn{Calc Reference}. - -@c [fix-ref Embedded Mode] -This tutorial describes the standard user interface of Calc only. -The Quick mode and Keypad mode interfaces are fairly -self-explanatory. @xref{Embedded Mode}, for a description of -the Embedded mode interface. - -The easiest way to read this tutorial on-line is to have two windows on -your Emacs screen, one with Calc and one with the Info system. Press -@kbd{C-x * t} to set this up; the on-line tutorial will be opened in the -current window and Calc will be started in another window. From the -Info window, the command @kbd{C-x * c} can be used to switch to the Calc -window and @kbd{C-x * o} can be used to switch back to the Info window. -(If you have a printed copy of the manual you can use that instead; in -that case you only need to press @kbd{C-x * c} to start Calc.) - -This tutorial is designed to be done in sequence. But the rest of this -manual does not assume you have gone through the tutorial. The tutorial -does not cover everything in the Calculator, but it touches on most -general areas. - -@ifnottex -You may wish to print out a copy of the Calc Summary and keep notes on -it as you learn Calc. @xref{About This Manual}, to see how to make a -printed summary. @xref{Summary}. -@end ifnottex -@iftex -The Calc Summary at the end of the reference manual includes some blank -space for your own use. You may wish to keep notes there as you learn -Calc. -@end iftex - -@menu -* Basic Tutorial:: -* Arithmetic Tutorial:: -* Vector/Matrix Tutorial:: -* Types Tutorial:: -* Algebra Tutorial:: -* Programming Tutorial:: - -* Answers to Exercises:: -@end menu - -@node Basic Tutorial, Arithmetic Tutorial, Tutorial, Tutorial -@section Basic Tutorial - -@noindent -In this section, we learn how RPN and algebraic-style calculations -work, how to undo and redo an operation done by mistake, and how -to control various modes of the Calculator. - -@menu -* RPN Tutorial:: Basic operations with the stack. -* Algebraic Tutorial:: Algebraic entry; variables. -* Undo Tutorial:: If you make a mistake: Undo and the trail. -* Modes Tutorial:: Common mode-setting commands. -@end menu - -@node RPN Tutorial, Algebraic Tutorial, Basic Tutorial, Basic Tutorial -@subsection RPN Calculations and the Stack - -@cindex RPN notation -@ifnottex -@noindent -Calc normally uses RPN notation. You may be familiar with the RPN -system from Hewlett-Packard calculators, FORTH, or PostScript. -(Reverse Polish Notation, RPN, is named after the Polish mathematician -Jan Lukasiewicz.) -@end ifnottex -@tex -\noindent -Calc normally uses RPN notation. You may be familiar with the RPN -system from Hewlett-Packard calculators, FORTH, or PostScript. -(Reverse Polish Notation, RPN, is named after the Polish mathematician -Jan \L ukasiewicz.) -@end tex - -The central component of an RPN calculator is the @dfn{stack}. A -calculator stack is like a stack of dishes. New dishes (numbers) are -added at the top of the stack, and numbers are normally only removed -from the top of the stack. - -@cindex Operators -@cindex Operands -In an operation like @expr{2+3}, the 2 and 3 are called the @dfn{operands} -and the @expr{+} is the @dfn{operator}. In an RPN calculator you always -enter the operands first, then the operator. Each time you type a -number, Calc adds or @dfn{pushes} it onto the top of the Stack. -When you press an operator key like @kbd{+}, Calc @dfn{pops} the appropriate -number of operands from the stack and pushes back the result. - -Thus we could add the numbers 2 and 3 in an RPN calculator by typing: -@kbd{2 @key{RET} 3 @key{RET} +}. (The @key{RET} key, Return, corresponds to -the @key{ENTER} key on traditional RPN calculators.) Try this now if -you wish; type @kbd{C-x * c} to switch into the Calc window (you can type -@kbd{C-x * c} again or @kbd{C-x * o} to switch back to the Tutorial window). -The first four keystrokes ``push'' the numbers 2 and 3 onto the stack. -The @kbd{+} key ``pops'' the top two numbers from the stack, adds them, -and pushes the result (5) back onto the stack. Here's how the stack -will look at various points throughout the calculation: - -@smallexample -@group - . 1: 2 2: 2 1: 5 . - . 1: 3 . - . - - C-x * c 2 @key{RET} 3 @key{RET} + @key{DEL} -@end group -@end smallexample - -The @samp{.} symbol is a marker that represents the top of the stack. -Note that the ``top'' of the stack is really shown at the bottom of -the Stack window. This may seem backwards, but it turns out to be -less distracting in regular use. - -@cindex Stack levels -@cindex Levels of stack -The numbers @samp{1:} and @samp{2:} on the left are @dfn{stack level -numbers}. Old RPN calculators always had four stack levels called -@expr{x}, @expr{y}, @expr{z}, and @expr{t}. Calc's stack can grow -as large as you like, so it uses numbers instead of letters. Some -stack-manipulation commands accept a numeric argument that says -which stack level to work on. Normal commands like @kbd{+} always -work on the top few levels of the stack. - -@c [fix-ref Truncating the Stack] -The Stack buffer is just an Emacs buffer, and you can move around in -it using the regular Emacs motion commands. But no matter where the -cursor is, even if you have scrolled the @samp{.} marker out of -view, most Calc commands always move the cursor back down to level 1 -before doing anything. It is possible to move the @samp{.} marker -upwards through the stack, temporarily ``hiding'' some numbers from -commands like @kbd{+}. This is called @dfn{stack truncation} and -we will not cover it in this tutorial; @pxref{Truncating the Stack}, -if you are interested. - -You don't really need the second @key{RET} in @kbd{2 @key{RET} 3 -@key{RET} +}. That's because if you type any operator name or -other non-numeric key when you are entering a number, the Calculator -automatically enters that number and then does the requested command. -Thus @kbd{2 @key{RET} 3 +} will work just as well. - -Examples in this tutorial will often omit @key{RET} even when the -stack displays shown would only happen if you did press @key{RET}: - -@smallexample -@group -1: 2 2: 2 1: 5 - . 1: 3 . - . - - 2 @key{RET} 3 + -@end group -@end smallexample - -@noindent -Here, after pressing @kbd{3} the stack would really show @samp{1: 2} -with @samp{Calc:@: 3} in the minibuffer. In these situations, you can -press the optional @key{RET} to see the stack as the figure shows. - -(@bullet{}) @strong{Exercise 1.} (This tutorial will include exercises -at various points. Try them if you wish. Answers to all the exercises -are located at the end of the Tutorial chapter. Each exercise will -include a cross-reference to its particular answer. If you are -reading with the Emacs Info system, press @kbd{f} and the -exercise number to go to the answer, then the letter @kbd{l} to -return to where you were.) - -@noindent -Here's the first exercise: What will the keystrokes @kbd{1 @key{RET} 2 -@key{RET} 3 @key{RET} 4 + * -} compute? (@samp{*} is the symbol for -multiplication.) Figure it out by hand, then try it with Calc to see -if you're right. @xref{RPN Answer 1, 1}. (@bullet{}) - -(@bullet{}) @strong{Exercise 2.} Compute -@texline @math{(2\times4) + (7\times9.4) + {5\over4}} -@infoline @expr{2*4 + 7*9.5 + 5/4} -using the stack. @xref{RPN Answer 2, 2}. (@bullet{}) - -The @key{DEL} key is called Backspace on some keyboards. It is -whatever key you would use to correct a simple typing error when -regularly using Emacs. The @key{DEL} key pops and throws away the -top value on the stack. (You can still get that value back from -the Trail if you should need it later on.) There are many places -in this tutorial where we assume you have used @key{DEL} to erase the -results of the previous example at the beginning of a new example. -In the few places where it is really important to use @key{DEL} to -clear away old results, the text will remind you to do so. - -(It won't hurt to let things accumulate on the stack, except that -whenever you give a display-mode-changing command Calc will have to -spend a long time reformatting such a large stack.) - -Since the @kbd{-} key is also an operator (it subtracts the top two -stack elements), how does one enter a negative number? Calc uses -the @kbd{_} (underscore) key to act like the minus sign in a number. -So, typing @kbd{-5 @key{RET}} won't work because the @kbd{-} key -will try to do a subtraction, but @kbd{_5 @key{RET}} works just fine. - -You can also press @kbd{n}, which means ``change sign.'' It changes -the number at the top of the stack (or the number being entered) -from positive to negative or vice-versa: @kbd{5 n @key{RET}}. - -@cindex Duplicating a stack entry -If you press @key{RET} when you're not entering a number, the effect -is to duplicate the top number on the stack. Consider this calculation: - -@smallexample -@group -1: 3 2: 3 1: 9 2: 9 1: 81 - . 1: 3 . 1: 9 . - . . - - 3 @key{RET} @key{RET} * @key{RET} * -@end group -@end smallexample - -@noindent -(Of course, an easier way to do this would be @kbd{3 @key{RET} 4 ^}, -to raise 3 to the fourth power.) - -The space-bar key (denoted @key{SPC} here) performs the same function -as @key{RET}; you could replace all three occurrences of @key{RET} in -the above example with @key{SPC} and the effect would be the same. - -@cindex Exchanging stack entries -Another stack manipulation key is @key{TAB}. This exchanges the top -two stack entries. Suppose you have computed @kbd{2 @key{RET} 3 +} -to get 5, and then you realize what you really wanted to compute -was @expr{20 / (2+3)}. - -@smallexample -@group -1: 5 2: 5 2: 20 1: 4 - . 1: 20 1: 5 . - . . - - 2 @key{RET} 3 + 20 @key{TAB} / -@end group -@end smallexample - -@noindent -Planning ahead, the calculation would have gone like this: - -@smallexample -@group -1: 20 2: 20 3: 20 2: 20 1: 4 - . 1: 2 2: 2 1: 5 . - . 1: 3 . - . - - 20 @key{RET} 2 @key{RET} 3 + / -@end group -@end smallexample - -A related stack command is @kbd{M-@key{TAB}} (hold @key{META} and type -@key{TAB}). It rotates the top three elements of the stack upward, -bringing the object in level 3 to the top. - -@smallexample -@group -1: 10 2: 10 3: 10 3: 20 3: 30 - . 1: 20 2: 20 2: 30 2: 10 - . 1: 30 1: 10 1: 20 - . . . - - 10 @key{RET} 20 @key{RET} 30 @key{RET} M-@key{TAB} M-@key{TAB} -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 3.} Suppose the numbers 10, 20, and 30 are -on the stack. Figure out how to add one to the number in level 2 -without affecting the rest of the stack. Also figure out how to add -one to the number in level 3. @xref{RPN Answer 3, 3}. (@bullet{}) - -Operations like @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, and @kbd{^} pop two -arguments from the stack and push a result. Operations like @kbd{n} and -@kbd{Q} (square root) pop a single number and push the result. You can -think of them as simply operating on the top element of the stack. - -@smallexample -@group -1: 3 1: 9 2: 9 1: 25 1: 5 - . . 1: 16 . . - . - - 3 @key{RET} @key{RET} * 4 @key{RET} @key{RET} * + Q -@end group -@end smallexample - -@noindent -(Note that capital @kbd{Q} means to hold down the Shift key while -typing @kbd{q}. Remember, plain unshifted @kbd{q} is the Quit command.) - -@cindex Pythagorean Theorem -Here we've used the Pythagorean Theorem to determine the hypotenuse of a -right triangle. Calc actually has a built-in command for that called -@kbd{f h}, but let's suppose we can't remember the necessary keystrokes. -We can still enter it by its full name using @kbd{M-x} notation: - -@smallexample -@group -1: 3 2: 3 1: 5 - . 1: 4 . - . - - 3 @key{RET} 4 @key{RET} M-x calc-hypot -@end group -@end smallexample - -All Calculator commands begin with the word @samp{calc-}. Since it -gets tiring to type this, Calc provides an @kbd{x} key which is just -like the regular Emacs @kbd{M-x} key except that it types the @samp{calc-} -prefix for you: - -@smallexample -@group -1: 3 2: 3 1: 5 - . 1: 4 . - . - - 3 @key{RET} 4 @key{RET} x hypot -@end group -@end smallexample - -What happens if you take the square root of a negative number? - -@smallexample -@group -1: 4 1: -4 1: (0, 2) - . . . - - 4 @key{RET} n Q -@end group -@end smallexample - -@noindent -The notation @expr{(a, b)} represents a complex number. -Complex numbers are more traditionally written @expr{a + b i}; -Calc can display in this format, too, but for now we'll stick to the -@expr{(a, b)} notation. - -If you don't know how complex numbers work, you can safely ignore this -feature. Complex numbers only arise from operations that would be -errors in a calculator that didn't have complex numbers. (For example, -taking the square root or logarithm of a negative number produces a -complex result.) - -Complex numbers are entered in the notation shown. The @kbd{(} and -@kbd{,} and @kbd{)} keys manipulate ``incomplete complex numbers.'' - -@smallexample -@group -1: ( ... 2: ( ... 1: (2, ... 1: (2, ... 1: (2, 3) - . 1: 2 . 3 . - . . - - ( 2 , 3 ) -@end group -@end smallexample - -You can perform calculations while entering parts of incomplete objects. -However, an incomplete object cannot actually participate in a calculation: - -@smallexample -@group -1: ( ... 2: ( ... 3: ( ... 1: ( ... 1: ( ... - . 1: 2 2: 2 5 5 - . 1: 3 . . - . - (error) - ( 2 @key{RET} 3 + + -@end group -@end smallexample - -@noindent -Adding 5 to an incomplete object makes no sense, so the last command -produces an error message and leaves the stack the same. - -Incomplete objects can't participate in arithmetic, but they can be -moved around by the regular stack commands. - -@smallexample -@group -2: 2 3: 2 3: 3 1: ( ... 1: (2, 3) -1: 3 2: 3 2: ( ... 2 . - . 1: ( ... 1: 2 3 - . . . - -2 @key{RET} 3 @key{RET} ( M-@key{TAB} M-@key{TAB} ) -@end group -@end smallexample - -@noindent -Note that the @kbd{,} (comma) key did not have to be used here. -When you press @kbd{)} all the stack entries between the incomplete -entry and the top are collected, so there's never really a reason -to use the comma. It's up to you. - -(@bullet{}) @strong{Exercise 4.} To enter the complex number @expr{(2, 3)}, -your friend Joe typed @kbd{( 2 , @key{SPC} 3 )}. What happened? -(Joe thought of a clever way to correct his mistake in only two -keystrokes, but it didn't quite work. Try it to find out why.) -@xref{RPN Answer 4, 4}. (@bullet{}) - -Vectors are entered the same way as complex numbers, but with square -brackets in place of parentheses. We'll meet vectors again later in -the tutorial. - -Any Emacs command can be given a @dfn{numeric prefix argument} by -typing a series of @key{META}-digits beforehand. If @key{META} is -awkward for you, you can instead type @kbd{C-u} followed by the -necessary digits. Numeric prefix arguments can be negative, as in -@kbd{M-- M-3 M-5} or @w{@kbd{C-u - 3 5}}. Calc commands use numeric -prefix arguments in a variety of ways. For example, a numeric prefix -on the @kbd{+} operator adds any number of stack entries at once: - -@smallexample -@group -1: 10 2: 10 3: 10 3: 10 1: 60 - . 1: 20 2: 20 2: 20 . - . 1: 30 1: 30 - . . - - 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u 3 + -@end group -@end smallexample - -For stack manipulation commands like @key{RET}, a positive numeric -prefix argument operates on the top @var{n} stack entries at once. A -negative argument operates on the entry in level @var{n} only. An -argument of zero operates on the entire stack. In this example, we copy -the second-to-top element of the stack: - -@smallexample -@group -1: 10 2: 10 3: 10 3: 10 4: 10 - . 1: 20 2: 20 2: 20 3: 20 - . 1: 30 1: 30 2: 30 - . . 1: 20 - . - - 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u -2 @key{RET} -@end group -@end smallexample - -@cindex Clearing the stack -@cindex Emptying the stack -Another common idiom is @kbd{M-0 @key{DEL}}, which clears the stack. -(The @kbd{M-0} numeric prefix tells @key{DEL} to operate on the -entire stack.) - -@node Algebraic Tutorial, Undo Tutorial, RPN Tutorial, Basic Tutorial -@subsection Algebraic-Style Calculations - -@noindent -If you are not used to RPN notation, you may prefer to operate the -Calculator in Algebraic mode, which is closer to the way -non-RPN calculators work. In Algebraic mode, you enter formulas -in traditional @expr{2+3} notation. - -@strong{Notice:} Calc gives @samp{/} lower precedence than @samp{*}, so -that @samp{a/b*c} is interpreted as @samp{a/(b*c)}; this is not -standard across all computer languages. See below for details. - -You don't really need any special ``mode'' to enter algebraic formulas. -You can enter a formula at any time by pressing the apostrophe (@kbd{'}) -key. Answer the prompt with the desired formula, then press @key{RET}. -The formula is evaluated and the result is pushed onto the RPN stack. -If you don't want to think in RPN at all, you can enter your whole -computation as a formula, read the result from the stack, then press -@key{DEL} to delete it from the stack. - -Try pressing the apostrophe key, then @kbd{2+3+4}, then @key{RET}. -The result should be the number 9. - -Algebraic formulas use the operators @samp{+}, @samp{-}, @samp{*}, -@samp{/}, and @samp{^}. You can use parentheses to make the order -of evaluation clear. In the absence of parentheses, @samp{^} is -evaluated first, then @samp{*}, then @samp{/}, then finally -@samp{+} and @samp{-}. For example, the expression - -@example -2 + 3*4*5 / 6*7^8 - 9 -@end example - -@noindent -is equivalent to - -@example -2 + ((3*4*5) / (6*(7^8)) - 9 -@end example - -@noindent -or, in large mathematical notation, - -@ifnottex -@example -@group - 3 * 4 * 5 -2 + --------- - 9 - 8 - 6 * 7 -@end group -@end example -@end ifnottex -@tex -\beforedisplay -$$ 2 + { 3 \times 4 \times 5 \over 6 \times 7^8 } - 9 $$ -\afterdisplay -@end tex - -@noindent -The result of this expression will be the number @mathit{-6.99999826533}. - -Calc's order of evaluation is the same as for most computer languages, -except that @samp{*} binds more strongly than @samp{/}, as the above -example shows. As in normal mathematical notation, the @samp{*} symbol -can often be omitted: @samp{2 a} is the same as @samp{2*a}. - -Operators at the same level are evaluated from left to right, except -that @samp{^} is evaluated from right to left. Thus, @samp{2-3-4} is -equivalent to @samp{(2-3)-4} or @mathit{-5}, whereas @samp{2^3^4} is equivalent -to @samp{2^(3^4)} (a very large integer; try it!). - -If you tire of typing the apostrophe all the time, there is -Algebraic mode, where Calc automatically senses -when you are about to type an algebraic expression. To enter this -mode, press the two letters @w{@kbd{m a}}. (An @samp{Alg} indicator -should appear in the Calc window's mode line.) - -Press @kbd{m a}, then @kbd{2+3+4} with no apostrophe, then @key{RET}. - -In Algebraic mode, when you press any key that would normally begin -entering a number (such as a digit, a decimal point, or the @kbd{_} -key), or if you press @kbd{(} or @kbd{[}, Calc automatically begins -an algebraic entry. - -Functions which do not have operator symbols like @samp{+} and @samp{*} -must be entered in formulas using function-call notation. For example, -the function name corresponding to the square-root key @kbd{Q} is -@code{sqrt}. To compute a square root in a formula, you would use -the notation @samp{sqrt(@var{x})}. - -Press the apostrophe, then type @kbd{sqrt(5*2) - 3}. The result should -be @expr{0.16227766017}. - -Note that if the formula begins with a function name, you need to use -the apostrophe even if you are in Algebraic mode. If you type @kbd{arcsin} -out of the blue, the @kbd{a r} will be taken as an Algebraic Rewrite -command, and the @kbd{csin} will be taken as the name of the rewrite -rule to use! - -Some people prefer to enter complex numbers and vectors in algebraic -form because they find RPN entry with incomplete objects to be too -distracting, even though they otherwise use Calc as an RPN calculator. - -Still in Algebraic mode, type: - -@smallexample -@group -1: (2, 3) 2: (2, 3) 1: (8, -1) 2: (8, -1) 1: (9, -1) - . 1: (1, -2) . 1: 1 . - . . - - (2,3) @key{RET} (1,-2) @key{RET} * 1 @key{RET} + -@end group -@end smallexample - -Algebraic mode allows us to enter complex numbers without pressing -an apostrophe first, but it also means we need to press @key{RET} -after every entry, even for a simple number like @expr{1}. - -(You can type @kbd{C-u m a} to enable a special Incomplete Algebraic -mode in which the @kbd{(} and @kbd{[} keys use algebraic entry even -though regular numeric keys still use RPN numeric entry. There is also -Total Algebraic mode, started by typing @kbd{m t}, in which all -normal keys begin algebraic entry. You must then use the @key{META} key -to type Calc commands: @kbd{M-m t} to get back out of Total Algebraic -mode, @kbd{M-q} to quit, etc.) - -If you're still in Algebraic mode, press @kbd{m a} again to turn it off. - -Actual non-RPN calculators use a mixture of algebraic and RPN styles. -In general, operators of two numbers (like @kbd{+} and @kbd{*}) -use algebraic form, but operators of one number (like @kbd{n} and @kbd{Q}) -use RPN form. Also, a non-RPN calculator allows you to see the -intermediate results of a calculation as you go along. You can -accomplish this in Calc by performing your calculation as a series -of algebraic entries, using the @kbd{$} sign to tie them together. -In an algebraic formula, @kbd{$} represents the number on the top -of the stack. Here, we perform the calculation -@texline @math{\sqrt{2\times4+1}}, -@infoline @expr{sqrt(2*4+1)}, -which on a traditional calculator would be done by pressing -@kbd{2 * 4 + 1 =} and then the square-root key. - -@smallexample -@group -1: 8 1: 9 1: 3 - . . . - - ' 2*4 @key{RET} $+1 @key{RET} Q -@end group -@end smallexample - -@noindent -Notice that we didn't need to press an apostrophe for the @kbd{$+1}, -because the dollar sign always begins an algebraic entry. - -(@bullet{}) @strong{Exercise 1.} How could you get the same effect as -pressing @kbd{Q} but using an algebraic entry instead? How about -if the @kbd{Q} key on your keyboard were broken? -@xref{Algebraic Answer 1, 1}. (@bullet{}) - -The notations @kbd{$$}, @kbd{$$$}, and so on stand for higher stack -entries. For example, @kbd{' $$+$ @key{RET}} is just like typing @kbd{+}. - -Algebraic formulas can include @dfn{variables}. To store in a -variable, press @kbd{s s}, then type the variable name, then press -@key{RET}. (There are actually two flavors of store command: -@kbd{s s} stores a number in a variable but also leaves the number -on the stack, while @w{@kbd{s t}} removes a number from the stack and -stores it in the variable.) A variable name should consist of one -or more letters or digits, beginning with a letter. - -@smallexample -@group -1: 17 . 1: a + a^2 1: 306 - . . . - - 17 s t a @key{RET} ' a+a^2 @key{RET} = -@end group -@end smallexample - -@noindent -The @kbd{=} key @dfn{evaluates} a formula by replacing all its -variables by the values that were stored in them. - -For RPN calculations, you can recall a variable's value on the -stack either by entering its name as a formula and pressing @kbd{=}, -or by using the @kbd{s r} command. - -@smallexample -@group -1: 17 2: 17 3: 17 2: 17 1: 306 - . 1: 17 2: 17 1: 289 . - . 1: 2 . - . - - s r a @key{RET} ' a @key{RET} = 2 ^ + -@end group -@end smallexample - -If you press a single digit for a variable name (as in @kbd{s t 3}, you -get one of ten @dfn{quick variables} @code{q0} through @code{q9}. -They are ``quick'' simply because you don't have to type the letter -@code{q} or the @key{RET} after their names. In fact, you can type -simply @kbd{s 3} as a shorthand for @kbd{s s 3}, and likewise for -@kbd{t 3} and @w{@kbd{r 3}}. - -Any variables in an algebraic formula for which you have not stored -values are left alone, even when you evaluate the formula. - -@smallexample -@group -1: 2 a + 2 b 1: 34 + 2 b - . . - - ' 2a+2b @key{RET} = -@end group -@end smallexample - -Calls to function names which are undefined in Calc are also left -alone, as are calls for which the value is undefined. - -@smallexample -@group -1: 2 + log10(0) + log10(x) + log10(5, 6) + foo(3) - . - - ' log10(100) + log10(0) + log10(x) + log10(5,6) + foo(3) @key{RET} -@end group -@end smallexample - -@noindent -In this example, the first call to @code{log10} works, but the other -calls are not evaluated. In the second call, the logarithm is -undefined for that value of the argument; in the third, the argument -is symbolic, and in the fourth, there are too many arguments. In the -fifth case, there is no function called @code{foo}. You will see a -``Wrong number of arguments'' message referring to @samp{log10(5,6)}. -Press the @kbd{w} (``why'') key to see any other messages that may -have arisen from the last calculation. In this case you will get -``logarithm of zero,'' then ``number expected: @code{x}''. Calc -automatically displays the first message only if the message is -sufficiently important; for example, Calc considers ``wrong number -of arguments'' and ``logarithm of zero'' to be important enough to -report automatically, while a message like ``number expected: @code{x}'' -will only show up if you explicitly press the @kbd{w} key. - -(@bullet{}) @strong{Exercise 2.} Joe entered the formula @samp{2 x y}, -stored 5 in @code{x}, pressed @kbd{=}, and got the expected result, -@samp{10 y}. He then tried the same for the formula @samp{2 x (1+y)}, -expecting @samp{10 (1+y)}, but it didn't work. Why not? -@xref{Algebraic Answer 2, 2}. (@bullet{}) - -(@bullet{}) @strong{Exercise 3.} What result would you expect -@kbd{1 @key{RET} 0 /} to give? What if you then type @kbd{0 *}? -@xref{Algebraic Answer 3, 3}. (@bullet{}) - -One interesting way to work with variables is to use the -@dfn{evaluates-to} (@samp{=>}) operator. It works like this: -Enter a formula algebraically in the usual way, but follow -the formula with an @samp{=>} symbol. (There is also an @kbd{s =} -command which builds an @samp{=>} formula using the stack.) On -the stack, you will see two copies of the formula with an @samp{=>} -between them. The lefthand formula is exactly like you typed it; -the righthand formula has been evaluated as if by typing @kbd{=}. - -@smallexample -@group -2: 2 + 3 => 5 2: 2 + 3 => 5 -1: 2 a + 2 b => 34 + 2 b 1: 2 a + 2 b => 20 + 2 b - . . - -' 2+3 => @key{RET} ' 2a+2b @key{RET} s = 10 s t a @key{RET} -@end group -@end smallexample - -@noindent -Notice that the instant we stored a new value in @code{a}, all -@samp{=>} operators already on the stack that referred to @expr{a} -were updated to use the new value. With @samp{=>}, you can push a -set of formulas on the stack, then change the variables experimentally -to see the effects on the formulas' values. - -You can also ``unstore'' a variable when you are through with it: - -@smallexample -@group -2: 2 + 5 => 5 -1: 2 a + 2 b => 2 a + 2 b - . - - s u a @key{RET} -@end group -@end smallexample - -We will encounter formulas involving variables and functions again -when we discuss the algebra and calculus features of the Calculator. - -@node Undo Tutorial, Modes Tutorial, Algebraic Tutorial, Basic Tutorial -@subsection Undo and Redo - -@noindent -If you make a mistake, you can usually correct it by pressing shift-@kbd{U}, -the ``undo'' command. First, clear the stack (@kbd{M-0 @key{DEL}}) and exit -and restart Calc (@kbd{C-x * * C-x * *}) to make sure things start off -with a clean slate. Now: - -@smallexample -@group -1: 2 2: 2 1: 8 2: 2 1: 6 - . 1: 3 . 1: 3 . - . . - - 2 @key{RET} 3 ^ U * -@end group -@end smallexample - -You can undo any number of times. Calc keeps a complete record of -all you have done since you last opened the Calc window. After the -above example, you could type: - -@smallexample -@group -1: 6 2: 2 1: 2 . . - . 1: 3 . - . - (error) - U U U U -@end group -@end smallexample - -You can also type @kbd{D} to ``redo'' a command that you have undone -mistakenly. - -@smallexample -@group - . 1: 2 2: 2 1: 6 1: 6 - . 1: 3 . . - . - (error) - D D D D -@end group -@end smallexample - -@noindent -It was not possible to redo past the @expr{6}, since that was placed there -by something other than an undo command. - -@cindex Time travel -You can think of undo and redo as a sort of ``time machine.'' Press -@kbd{U} to go backward in time, @kbd{D} to go forward. If you go -backward and do something (like @kbd{*}) then, as any science fiction -reader knows, you have changed your future and you cannot go forward -again. Thus, the inability to redo past the @expr{6} even though there -was an earlier undo command. - -You can always recall an earlier result using the Trail. We've ignored -the trail so far, but it has been faithfully recording everything we -did since we loaded the Calculator. If the Trail is not displayed, -press @kbd{t d} now to turn it on. - -Let's try grabbing an earlier result. The @expr{8} we computed was -undone by a @kbd{U} command, and was lost even to Redo when we pressed -@kbd{*}, but it's still there in the trail. There should be a little -@samp{>} arrow (the @dfn{trail pointer}) resting on the last trail -entry. If there isn't, press @kbd{t ]} to reset the trail pointer. -Now, press @w{@kbd{t p}} to move the arrow onto the line containing -@expr{8}, and press @w{@kbd{t y}} to ``yank'' that number back onto the -stack. - -If you press @kbd{t ]} again, you will see that even our Yank command -went into the trail. - -Let's go further back in time. Earlier in the tutorial we computed -a huge integer using the formula @samp{2^3^4}. We don't remember -what it was, but the first digits were ``241''. Press @kbd{t r} -(which stands for trail-search-reverse), then type @kbd{241}. -The trail cursor will jump back to the next previous occurrence of -the string ``241'' in the trail. This is just a regular Emacs -incremental search; you can now press @kbd{C-s} or @kbd{C-r} to -continue the search forwards or backwards as you like. - -To finish the search, press @key{RET}. This halts the incremental -search and leaves the trail pointer at the thing we found. Now we -can type @kbd{t y} to yank that number onto the stack. If we hadn't -remembered the ``241'', we could simply have searched for @kbd{2^3^4}, -then pressed @kbd{@key{RET} t n} to halt and then move to the next item. - -You may have noticed that all the trail-related commands begin with -the letter @kbd{t}. (The store-and-recall commands, on the other hand, -all began with @kbd{s}.) Calc has so many commands that there aren't -enough keys for all of them, so various commands are grouped into -two-letter sequences where the first letter is called the @dfn{prefix} -key. If you type a prefix key by accident, you can press @kbd{C-g} -to cancel it. (In fact, you can press @kbd{C-g} to cancel almost -anything in Emacs.) To get help on a prefix key, press that key -followed by @kbd{?}. Some prefixes have several lines of help, -so you need to press @kbd{?} repeatedly to see them all. -You can also type @kbd{h h} to see all the help at once. - -Try pressing @kbd{t ?} now. You will see a line of the form, - -@smallexample -trail/time: Display; Fwd, Back; Next, Prev, Here, [, ]; Yank: [MORE] t- -@end smallexample - -@noindent -The word ``trail'' indicates that the @kbd{t} prefix key contains -trail-related commands. Each entry on the line shows one command, -with a single capital letter showing which letter you press to get -that command. We have used @kbd{t n}, @kbd{t p}, @kbd{t ]}, and -@kbd{t y} so far. The @samp{[MORE]} means you can press @kbd{?} -again to see more @kbd{t}-prefix commands. Notice that the commands -are roughly divided (by semicolons) into related groups. - -When you are in the help display for a prefix key, the prefix is -still active. If you press another key, like @kbd{y} for example, -it will be interpreted as a @kbd{t y} command. If all you wanted -was to look at the help messages, press @kbd{C-g} afterwards to cancel -the prefix. - -One more way to correct an error is by editing the stack entries. -The actual Stack buffer is marked read-only and must not be edited -directly, but you can press @kbd{`} (the backquote or accent grave) -to edit a stack entry. - -Try entering @samp{3.141439} now. If this is supposed to represent -@cpi{}, it's got several errors. Press @kbd{`} to edit this number. -Now use the normal Emacs cursor motion and editing keys to change -the second 4 to a 5, and to transpose the 3 and the 9. When you -press @key{RET}, the number on the stack will be replaced by your -new number. This works for formulas, vectors, and all other types -of values you can put on the stack. The @kbd{`} key also works -during entry of a number or algebraic formula. - -@node Modes Tutorial, , Undo Tutorial, Basic Tutorial -@subsection Mode-Setting Commands - -@noindent -Calc has many types of @dfn{modes} that affect the way it interprets -your commands or the way it displays data. We have already seen one -mode, namely Algebraic mode. There are many others, too; we'll -try some of the most common ones here. - -Perhaps the most fundamental mode in Calc is the current @dfn{precision}. -Notice the @samp{12} on the Calc window's mode line: - -@smallexample ---%*-Calc: 12 Deg (Calculator)----All------ -@end smallexample - -@noindent -Most of the symbols there are Emacs things you don't need to worry -about, but the @samp{12} and the @samp{Deg} are mode indicators. -The @samp{12} means that calculations should always be carried to -12 significant figures. That is why, when we type @kbd{1 @key{RET} 7 /}, -we get @expr{0.142857142857} with exactly 12 digits, not counting -leading and trailing zeros. - -You can set the precision to anything you like by pressing @kbd{p}, -then entering a suitable number. Try pressing @kbd{p 30 @key{RET}}, -then doing @kbd{1 @key{RET} 7 /} again: - -@smallexample -@group -1: 0.142857142857 -2: 0.142857142857142857142857142857 - . -@end group -@end smallexample - -Although the precision can be set arbitrarily high, Calc always -has to have @emph{some} value for the current precision. After -all, the true value @expr{1/7} is an infinitely repeating decimal; -Calc has to stop somewhere. - -Of course, calculations are slower the more digits you request. -Press @w{@kbd{p 12}} now to set the precision back down to the default. - -Calculations always use the current precision. For example, even -though we have a 30-digit value for @expr{1/7} on the stack, if -we use it in a calculation in 12-digit mode it will be rounded -down to 12 digits before it is used. Try it; press @key{RET} to -duplicate the number, then @w{@kbd{1 +}}. Notice that the @key{RET} -key didn't round the number, because it doesn't do any calculation. -But the instant we pressed @kbd{+}, the number was rounded down. - -@smallexample -@group -1: 0.142857142857 -2: 0.142857142857142857142857142857 -3: 1.14285714286 - . -@end group -@end smallexample - -@noindent -In fact, since we added a digit on the left, we had to lose one -digit on the right from even the 12-digit value of @expr{1/7}. - -How did we get more than 12 digits when we computed @samp{2^3^4}? The -answer is that Calc makes a distinction between @dfn{integers} and -@dfn{floating-point} numbers, or @dfn{floats}. An integer is a number -that does not contain a decimal point. There is no such thing as an -``infinitely repeating fraction integer,'' so Calc doesn't have to limit -itself. If you asked for @samp{2^10000} (don't try this!), you would -have to wait a long time but you would eventually get an exact answer. -If you ask for @samp{2.^10000}, you will quickly get an answer which is -correct only to 12 places. The decimal point tells Calc that it should -use floating-point arithmetic to get the answer, not exact integer -arithmetic. - -You can use the @kbd{F} (@code{calc-floor}) command to convert a -floating-point value to an integer, and @kbd{c f} (@code{calc-float}) -to convert an integer to floating-point form. - -Let's try entering that last calculation: - -@smallexample -@group -1: 2. 2: 2. 1: 1.99506311689e3010 - . 1: 10000 . - . - - 2.0 @key{RET} 10000 @key{RET} ^ -@end group -@end smallexample - -@noindent -@cindex Scientific notation, entry of -Notice the letter @samp{e} in there. It represents ``times ten to the -power of,'' and is used by Calc automatically whenever writing the -number out fully would introduce more extra zeros than you probably -want to see. You can enter numbers in this notation, too. - -@smallexample -@group -1: 2. 2: 2. 1: 1.99506311678e3010 - . 1: 10000. . - . - - 2.0 @key{RET} 1e4 @key{RET} ^ -@end group -@end smallexample - -@cindex Round-off errors -@noindent -Hey, the answer is different! Look closely at the middle columns -of the two examples. In the first, the stack contained the -exact integer @expr{10000}, but in the second it contained -a floating-point value with a decimal point. When you raise a -number to an integer power, Calc uses repeated squaring and -multiplication to get the answer. When you use a floating-point -power, Calc uses logarithms and exponentials. As you can see, -a slight error crept in during one of these methods. Which -one should we trust? Let's raise the precision a bit and find -out: - -@smallexample -@group - . 1: 2. 2: 2. 1: 1.995063116880828e3010 - . 1: 10000. . - . - - p 16 @key{RET} 2. @key{RET} 1e4 ^ p 12 @key{RET} -@end group -@end smallexample - -@noindent -@cindex Guard digits -Presumably, it doesn't matter whether we do this higher-precision -calculation using an integer or floating-point power, since we -have added enough ``guard digits'' to trust the first 12 digits -no matter what. And the verdict is@dots{} Integer powers were more -accurate; in fact, the result was only off by one unit in the -last place. - -@cindex Guard digits -Calc does many of its internal calculations to a slightly higher -precision, but it doesn't always bump the precision up enough. -In each case, Calc added about two digits of precision during -its calculation and then rounded back down to 12 digits -afterward. In one case, it was enough; in the other, it -wasn't. If you really need @var{x} digits of precision, it -never hurts to do the calculation with a few extra guard digits. - -What if we want guard digits but don't want to look at them? -We can set the @dfn{float format}. Calc supports four major -formats for floating-point numbers, called @dfn{normal}, -@dfn{fixed-point}, @dfn{scientific notation}, and @dfn{engineering -notation}. You get them by pressing @w{@kbd{d n}}, @kbd{d f}, -@kbd{d s}, and @kbd{d e}, respectively. In each case, you can -supply a numeric prefix argument which says how many digits -should be displayed. As an example, let's put a few numbers -onto the stack and try some different display modes. First, -use @kbd{M-0 @key{DEL}} to clear the stack, then enter the four -numbers shown here: - -@smallexample -@group -4: 12345 4: 12345 4: 12345 4: 12345 4: 12345 -3: 12345. 3: 12300. 3: 1.2345e4 3: 1.23e4 3: 12345.000 -2: 123.45 2: 123. 2: 1.2345e2 2: 1.23e2 2: 123.450 -1: 12.345 1: 12.3 1: 1.2345e1 1: 1.23e1 1: 12.345 - . . . . . - - d n M-3 d n d s M-3 d s M-3 d f -@end group -@end smallexample - -@noindent -Notice that when we typed @kbd{M-3 d n}, the numbers were rounded down -to three significant digits, but then when we typed @kbd{d s} all -five significant figures reappeared. The float format does not -affect how numbers are stored, it only affects how they are -displayed. Only the current precision governs the actual rounding -of numbers in the Calculator's memory. - -Engineering notation, not shown here, is like scientific notation -except the exponent (the power-of-ten part) is always adjusted to be -a multiple of three (as in ``kilo,'' ``micro,'' etc.). As a result -there will be one, two, or three digits before the decimal point. - -Whenever you change a display-related mode, Calc redraws everything -in the stack. This may be slow if there are many things on the stack, -so Calc allows you to type shift-@kbd{H} before any mode command to -prevent it from updating the stack. Anything Calc displays after the -mode-changing command will appear in the new format. - -@smallexample -@group -4: 12345 4: 12345 4: 12345 4: 12345 4: 12345 -3: 12345.000 3: 12345.000 3: 12345.000 3: 1.2345e4 3: 12345. -2: 123.450 2: 123.450 2: 1.2345e1 2: 1.2345e1 2: 123.45 -1: 12.345 1: 1.2345e1 1: 1.2345e2 1: 1.2345e2 1: 12.345 - . . . . . - - H d s @key{DEL} U @key{TAB} d @key{SPC} d n -@end group -@end smallexample - -@noindent -Here the @kbd{H d s} command changes to scientific notation but without -updating the screen. Deleting the top stack entry and undoing it back -causes it to show up in the new format; swapping the top two stack -entries reformats both entries. The @kbd{d @key{SPC}} command refreshes the -whole stack. The @kbd{d n} command changes back to the normal float -format; since it doesn't have an @kbd{H} prefix, it also updates all -the stack entries to be in @kbd{d n} format. - -Notice that the integer @expr{12345} was not affected by any -of the float formats. Integers are integers, and are always -displayed exactly. - -@cindex Large numbers, readability -Large integers have their own problems. Let's look back at -the result of @kbd{2^3^4}. - -@example -2417851639229258349412352 -@end example - -@noindent -Quick---how many digits does this have? Try typing @kbd{d g}: - -@example -2,417,851,639,229,258,349,412,352 -@end example - -@noindent -Now how many digits does this have? It's much easier to tell! -We can actually group digits into clumps of any size. Some -people prefer @kbd{M-5 d g}: - -@example -24178,51639,22925,83494,12352 -@end example - -Let's see what happens to floating-point numbers when they are grouped. -First, type @kbd{p 25 @key{RET}} to make sure we have enough precision -to get ourselves into trouble. Now, type @kbd{1e13 /}: - -@example -24,17851,63922.9258349412352 -@end example - -@noindent -The integer part is grouped but the fractional part isn't. Now try -@kbd{M-- M-5 d g} (that's meta-minus-sign, meta-five): - -@example -24,17851,63922.92583,49412,352 -@end example - -If you find it hard to tell the decimal point from the commas, try -changing the grouping character to a space with @kbd{d , @key{SPC}}: - -@example -24 17851 63922.92583 49412 352 -@end example - -Type @kbd{d , ,} to restore the normal grouping character, then -@kbd{d g} again to turn grouping off. Also, press @kbd{p 12} to -restore the default precision. - -Press @kbd{U} enough times to get the original big integer back. -(Notice that @kbd{U} does not undo each mode-setting command; if -you want to undo a mode-setting command, you have to do it yourself.) -Now, type @kbd{d r 16 @key{RET}}: - -@example -16#200000000000000000000 -@end example - -@noindent -The number is now displayed in @dfn{hexadecimal}, or ``base-16'' form. -Suddenly it looks pretty simple; this should be no surprise, since we -got this number by computing a power of two, and 16 is a power of 2. -In fact, we can use @w{@kbd{d r 2 @key{RET}}} to see it in actual binary -form: - -@example -2#1000000000000000000000000000000000000000000000000000000 @dots{} -@end example - -@noindent -We don't have enough space here to show all the zeros! They won't -fit on a typical screen, either, so you will have to use horizontal -scrolling to see them all. Press @kbd{<} and @kbd{>} to scroll the -stack window left and right by half its width. Another way to view -something large is to press @kbd{`} (back-quote) to edit the top of -stack in a separate window. (Press @kbd{C-c C-c} when you are done.) - -You can enter non-decimal numbers using the @kbd{#} symbol, too. -Let's see what the hexadecimal number @samp{5FE} looks like in -binary. Type @kbd{16#5FE} (the letters can be typed in upper or -lower case; they will always appear in upper case). It will also -help to turn grouping on with @kbd{d g}: - -@example -2#101,1111,1110 -@end example - -Notice that @kbd{d g} groups by fours by default if the display radix -is binary or hexadecimal, but by threes if it is decimal, octal, or any -other radix. - -Now let's see that number in decimal; type @kbd{d r 10}: - -@example -1,534 -@end example - -Numbers are not @emph{stored} with any particular radix attached. They're -just numbers; they can be entered in any radix, and are always displayed -in whatever radix you've chosen with @kbd{d r}. The current radix applies -to integers, fractions, and floats. - -@cindex Roundoff errors, in non-decimal numbers -(@bullet{}) @strong{Exercise 1.} Your friend Joe tried to enter one-third -as @samp{3#0.1} in @kbd{d r 3} mode with a precision of 12. He got -@samp{3#0.0222222...} (with 25 2's) in the display. When he multiplied -that by three, he got @samp{3#0.222222...} instead of the expected -@samp{3#1}. Next, Joe entered @samp{3#0.2} and, to his great relief, -saw @samp{3#0.2} on the screen. But when he typed @kbd{2 /}, he got -@samp{3#0.10000001} (some zeros omitted). What's going on here? -@xref{Modes Answer 1, 1}. (@bullet{}) - -@cindex Scientific notation, in non-decimal numbers -(@bullet{}) @strong{Exercise 2.} Scientific notation works in non-decimal -modes in the natural way (the exponent is a power of the radix instead of -a power of ten, although the exponent itself is always written in decimal). -Thus @samp{8#1.23e3 = 8#1230.0}. Suppose we have the hexadecimal number -@samp{f.e8f} times 16 to the 15th power: We write @samp{16#f.e8fe15}. -What is wrong with this picture? What could we write instead that would -work better? @xref{Modes Answer 2, 2}. (@bullet{}) - -The @kbd{m} prefix key has another set of modes, relating to the way -Calc interprets your inputs and does computations. Whereas @kbd{d}-prefix -modes generally affect the way things look, @kbd{m}-prefix modes affect -the way they are actually computed. - -The most popular @kbd{m}-prefix mode is the @dfn{angular mode}. Notice -the @samp{Deg} indicator in the mode line. This means that if you use -a command that interprets a number as an angle, it will assume the -angle is measured in degrees. For example, - -@smallexample -@group -1: 45 1: 0.707106781187 1: 0.500000000001 1: 0.5 - . . . . - - 45 S 2 ^ c 1 -@end group -@end smallexample - -@noindent -The shift-@kbd{S} command computes the sine of an angle. The sine -of 45 degrees is -@texline @math{\sqrt{2}/2}; -@infoline @expr{sqrt(2)/2}; -squaring this yields @expr{2/4 = 0.5}. However, there has been a slight -roundoff error because the representation of -@texline @math{\sqrt{2}/2} -@infoline @expr{sqrt(2)/2} -wasn't exact. The @kbd{c 1} command is a handy way to clean up numbers -in this case; it temporarily reduces the precision by one digit while it -re-rounds the number on the top of the stack. - -@cindex Roundoff errors, examples -(@bullet{}) @strong{Exercise 3.} Your friend Joe computed the sine -of 45 degrees as shown above, then, hoping to avoid an inexact -result, he increased the precision to 16 digits before squaring. -What happened? @xref{Modes Answer 3, 3}. (@bullet{}) - -To do this calculation in radians, we would type @kbd{m r} first. -(The indicator changes to @samp{Rad}.) 45 degrees corresponds to -@cpiover{4} radians. To get @cpi{}, press the @kbd{P} key. (Once -again, this is a shifted capital @kbd{P}. Remember, unshifted -@kbd{p} sets the precision.) - -@smallexample -@group -1: 3.14159265359 1: 0.785398163398 1: 0.707106781187 - . . . - - P 4 / m r S -@end group -@end smallexample - -Likewise, inverse trigonometric functions generate results in -either radians or degrees, depending on the current angular mode. - -@smallexample -@group -1: 0.707106781187 1: 0.785398163398 1: 45. - . . . - - .5 Q m r I S m d U I S -@end group -@end smallexample - -@noindent -Here we compute the Inverse Sine of -@texline @math{\sqrt{0.5}}, -@infoline @expr{sqrt(0.5)}, -first in radians, then in degrees. - -Use @kbd{c d} and @kbd{c r} to convert a number from radians to degrees -and vice-versa. - -@smallexample -@group -1: 45 1: 0.785398163397 1: 45. - . . . - - 45 c r c d -@end group -@end smallexample - -Another interesting mode is @dfn{Fraction mode}. Normally, -dividing two integers produces a floating-point result if the -quotient can't be expressed as an exact integer. Fraction mode -causes integer division to produce a fraction, i.e., a rational -number, instead. - -@smallexample -@group -2: 12 1: 1.33333333333 1: 4:3 -1: 9 . . - . - - 12 @key{RET} 9 / m f U / m f -@end group -@end smallexample - -@noindent -In the first case, we get an approximate floating-point result. -In the second case, we get an exact fractional result (four-thirds). - -You can enter a fraction at any time using @kbd{:} notation. -(Calc uses @kbd{:} instead of @kbd{/} as the fraction separator -because @kbd{/} is already used to divide the top two stack -elements.) Calculations involving fractions will always -produce exact fractional results; Fraction mode only says -what to do when dividing two integers. - -@cindex Fractions vs. floats -@cindex Floats vs. fractions -(@bullet{}) @strong{Exercise 4.} If fractional arithmetic is exact, -why would you ever use floating-point numbers instead? -@xref{Modes Answer 4, 4}. (@bullet{}) - -Typing @kbd{m f} doesn't change any existing values in the stack. -In the above example, we had to Undo the division and do it over -again when we changed to Fraction mode. But if you use the -evaluates-to operator you can get commands like @kbd{m f} to -recompute for you. - -@smallexample -@group -1: 12 / 9 => 1.33333333333 1: 12 / 9 => 1.333 1: 12 / 9 => 4:3 - . . . - - ' 12/9 => @key{RET} p 4 @key{RET} m f -@end group -@end smallexample - -@noindent -In this example, the righthand side of the @samp{=>} operator -on the stack is recomputed when we change the precision, then -again when we change to Fraction mode. All @samp{=>} expressions -on the stack are recomputed every time you change any mode that -might affect their values. - -@node Arithmetic Tutorial, Vector/Matrix Tutorial, Basic Tutorial, Tutorial -@section Arithmetic Tutorial - -@noindent -In this section, we explore the arithmetic and scientific functions -available in the Calculator. - -The standard arithmetic commands are @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, -and @kbd{^}. Each normally takes two numbers from the top of the stack -and pushes back a result. The @kbd{n} and @kbd{&} keys perform -change-sign and reciprocal operations, respectively. - -@smallexample -@group -1: 5 1: 0.2 1: 5. 1: -5. 1: 5. - . . . . . - - 5 & & n n -@end group -@end smallexample - -@cindex Binary operators -You can apply a ``binary operator'' like @kbd{+} across any number of -stack entries by giving it a numeric prefix. You can also apply it -pairwise to several stack elements along with the top one if you use -a negative prefix. - -@smallexample -@group -3: 2 1: 9 3: 2 4: 2 3: 12 -2: 3 . 2: 3 3: 3 2: 13 -1: 4 1: 4 2: 4 1: 14 - . . 1: 10 . - . - -2 @key{RET} 3 @key{RET} 4 M-3 + U 10 M-- M-3 + -@end group -@end smallexample - -@cindex Unary operators -You can apply a ``unary operator'' like @kbd{&} to the top @var{n} -stack entries with a numeric prefix, too. - -@smallexample -@group -3: 2 3: 0.5 3: 0.5 -2: 3 2: 0.333333333333 2: 3. -1: 4 1: 0.25 1: 4. - . . . - -2 @key{RET} 3 @key{RET} 4 M-3 & M-2 & -@end group -@end smallexample - -Notice that the results here are left in floating-point form. -We can convert them back to integers by pressing @kbd{F}, the -``floor'' function. This function rounds down to the next lower -integer. There is also @kbd{R}, which rounds to the nearest -integer. - -@smallexample -@group -7: 2. 7: 2 7: 2 -6: 2.4 6: 2 6: 2 -5: 2.5 5: 2 5: 3 -4: 2.6 4: 2 4: 3 -3: -2. 3: -2 3: -2 -2: -2.4 2: -3 2: -2 -1: -2.6 1: -3 1: -3 - . . . - - M-7 F U M-7 R -@end group -@end smallexample - -Since dividing-and-flooring (i.e., ``integer quotient'') is such a -common operation, Calc provides a special command for that purpose, the -backslash @kbd{\}. Another common arithmetic operator is @kbd{%}, which -computes the remainder that would arise from a @kbd{\} operation, i.e., -the ``modulo'' of two numbers. For example, - -@smallexample -@group -2: 1234 1: 12 2: 1234 1: 34 -1: 100 . 1: 100 . - . . - -1234 @key{RET} 100 \ U % -@end group -@end smallexample - -These commands actually work for any real numbers, not just integers. - -@smallexample -@group -2: 3.1415 1: 3 2: 3.1415 1: 0.1415 -1: 1 . 1: 1 . - . . - -3.1415 @key{RET} 1 \ U % -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 1.} The @kbd{\} command would appear to be a -frill, since you could always do the same thing with @kbd{/ F}. Think -of a situation where this is not true---@kbd{/ F} would be inadequate. -Now think of a way you could get around the problem if Calc didn't -provide a @kbd{\} command. @xref{Arithmetic Answer 1, 1}. (@bullet{}) - -We've already seen the @kbd{Q} (square root) and @kbd{S} (sine) -commands. Other commands along those lines are @kbd{C} (cosine), -@kbd{T} (tangent), @kbd{E} (@expr{e^x}) and @kbd{L} (natural -logarithm). These can be modified by the @kbd{I} (inverse) and -@kbd{H} (hyperbolic) prefix keys. - -Let's compute the sine and cosine of an angle, and verify the -identity -@texline @math{\sin^2x + \cos^2x = 1}. -@infoline @expr{sin(x)^2 + cos(x)^2 = 1}. -We'll arbitrarily pick @mathit{-64} degrees as a good value for @expr{x}. -With the angular mode set to degrees (type @w{@kbd{m d}}), do: - -@smallexample -@group -2: -64 2: -64 2: -0.89879 2: -0.89879 1: 1. -1: -64 1: -0.89879 1: -64 1: 0.43837 . - . . . . - - 64 n @key{RET} @key{RET} S @key{TAB} C f h -@end group -@end smallexample - -@noindent -(For brevity, we're showing only five digits of the results here. -You can of course do these calculations to any precision you like.) - -Remember, @kbd{f h} is the @code{calc-hypot}, or square-root of sum -of squares, command. - -Another identity is -@texline @math{\displaystyle\tan x = {\sin x \over \cos x}}. -@infoline @expr{tan(x) = sin(x) / cos(x)}. -@smallexample -@group - -2: -0.89879 1: -2.0503 1: -64. -1: 0.43837 . . - . - - U / I T -@end group -@end smallexample - -A physical interpretation of this calculation is that if you move -@expr{0.89879} units downward and @expr{0.43837} units to the right, -your direction of motion is @mathit{-64} degrees from horizontal. Suppose -we move in the opposite direction, up and to the left: - -@smallexample -@group -2: -0.89879 2: 0.89879 1: -2.0503 1: -64. -1: 0.43837 1: -0.43837 . . - . . - - U U M-2 n / I T -@end group -@end smallexample - -@noindent -How can the angle be the same? The answer is that the @kbd{/} operation -loses information about the signs of its inputs. Because the quotient -is negative, we know exactly one of the inputs was negative, but we -can't tell which one. There is an @kbd{f T} [@code{arctan2}] function which -computes the inverse tangent of the quotient of a pair of numbers. -Since you feed it the two original numbers, it has enough information -to give you a full 360-degree answer. - -@smallexample -@group -2: 0.89879 1: 116. 3: 116. 2: 116. 1: 180. -1: -0.43837 . 2: -0.89879 1: -64. . - . 1: 0.43837 . - . - - U U f T M-@key{RET} M-2 n f T - -@end group -@end smallexample - -@noindent -The resulting angles differ by 180 degrees; in other words, they -point in opposite directions, just as we would expect. - -The @key{META}-@key{RET} we used in the third step is the -``last-arguments'' command. It is sort of like Undo, except that it -restores the arguments of the last command to the stack without removing -the command's result. It is useful in situations like this one, -where we need to do several operations on the same inputs. We could -have accomplished the same thing by using @kbd{M-2 @key{RET}} to duplicate -the top two stack elements right after the @kbd{U U}, then a pair of -@kbd{M-@key{TAB}} commands to cycle the 116 up around the duplicates. - -A similar identity is supposed to hold for hyperbolic sines and cosines, -except that it is the @emph{difference} -@texline @math{\cosh^2x - \sinh^2x} -@infoline @expr{cosh(x)^2 - sinh(x)^2} -that always equals one. Let's try to verify this identity. - -@smallexample -@group -2: -64 2: -64 2: -64 2: 9.7192e54 2: 9.7192e54 -1: -64 1: -3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54 - . . . . . - - 64 n @key{RET} @key{RET} H C 2 ^ @key{TAB} H S 2 ^ -@end group -@end smallexample - -@noindent -@cindex Roundoff errors, examples -Something's obviously wrong, because when we subtract these numbers -the answer will clearly be zero! But if you think about it, if these -numbers @emph{did} differ by one, it would be in the 55th decimal -place. The difference we seek has been lost entirely to roundoff -error. - -We could verify this hypothesis by doing the actual calculation with, -say, 60 decimal places of precision. This will be slow, but not -enormously so. Try it if you wish; sure enough, the answer is -0.99999, reasonably close to 1. - -Of course, a more reasonable way to verify the identity is to use -a more reasonable value for @expr{x}! - -@cindex Common logarithm -Some Calculator commands use the Hyperbolic prefix for other purposes. -The logarithm and exponential functions, for example, work to the base -@expr{e} normally but use base-10 instead if you use the Hyperbolic -prefix. - -@smallexample -@group -1: 1000 1: 6.9077 1: 1000 1: 3 - . . . . - - 1000 L U H L -@end group -@end smallexample - -@noindent -First, we mistakenly compute a natural logarithm. Then we undo -and compute a common logarithm instead. - -The @kbd{B} key computes a general base-@var{b} logarithm for any -value of @var{b}. - -@smallexample -@group -2: 1000 1: 3 1: 1000. 2: 1000. 1: 6.9077 -1: 10 . . 1: 2.71828 . - . . - - 1000 @key{RET} 10 B H E H P B -@end group -@end smallexample - -@noindent -Here we first use @kbd{B} to compute the base-10 logarithm, then use -the ``hyperbolic'' exponential as a cheap hack to recover the number -1000, then use @kbd{B} again to compute the natural logarithm. Note -that @kbd{P} with the hyperbolic prefix pushes the constant @expr{e} -onto the stack. - -You may have noticed that both times we took the base-10 logarithm -of 1000, we got an exact integer result. Calc always tries to give -an exact rational result for calculations involving rational numbers -where possible. But when we used @kbd{H E}, the result was a -floating-point number for no apparent reason. In fact, if we had -computed @kbd{10 @key{RET} 3 ^} we @emph{would} have gotten an -exact integer 1000. But the @kbd{H E} command is rigged to generate -a floating-point result all of the time so that @kbd{1000 H E} will -not waste time computing a thousand-digit integer when all you -probably wanted was @samp{1e1000}. - -(@bullet{}) @strong{Exercise 2.} Find a pair of integer inputs to -the @kbd{B} command for which Calc could find an exact rational -result but doesn't. @xref{Arithmetic Answer 2, 2}. (@bullet{}) - -The Calculator also has a set of functions relating to combinatorics -and statistics. You may be familiar with the @dfn{factorial} function, -which computes the product of all the integers up to a given number. - -@smallexample -@group -1: 100 1: 93326215443... 1: 100. 1: 9.3326e157 - . . . . - - 100 ! U c f ! -@end group -@end smallexample - -@noindent -Recall, the @kbd{c f} command converts the integer or fraction at the -top of the stack to floating-point format. If you take the factorial -of a floating-point number, you get a floating-point result -accurate to the current precision. But if you give @kbd{!} an -exact integer, you get an exact integer result (158 digits long -in this case). - -If you take the factorial of a non-integer, Calc uses a generalized -factorial function defined in terms of Euler's Gamma function -@texline @math{\Gamma(n)} -@infoline @expr{gamma(n)} -(which is itself available as the @kbd{f g} command). - -@smallexample -@group -3: 4. 3: 24. 1: 5.5 1: 52.342777847 -2: 4.5 2: 52.3427777847 . . -1: 5. 1: 120. - . . - - M-3 ! M-0 @key{DEL} 5.5 f g -@end group -@end smallexample - -@noindent -Here we verify the identity -@texline @math{n! = \Gamma(n+1)}. -@infoline @expr{@var{n}!@: = gamma(@var{n}+1)}. - -The binomial coefficient @var{n}-choose-@var{m} -@texline or @math{\displaystyle {n \choose m}} -is defined by -@texline @math{\displaystyle {n! \over m! \, (n-m)!}} -@infoline @expr{n!@: / m!@: (n-m)!} -for all reals @expr{n} and @expr{m}. The intermediate results in this -formula can become quite large even if the final result is small; the -@kbd{k c} command computes a binomial coefficient in a way that avoids -large intermediate values. - -The @kbd{k} prefix key defines several common functions out of -combinatorics and number theory. Here we compute the binomial -coefficient 30-choose-20, then determine its prime factorization. - -@smallexample -@group -2: 30 1: 30045015 1: [3, 3, 5, 7, 11, 13, 23, 29] -1: 20 . . - . - - 30 @key{RET} 20 k c k f -@end group -@end smallexample - -@noindent -You can verify these prime factors by using @kbd{V R *} to multiply -together the elements of this vector. The result is the original -number, 30045015. - -@cindex Hash tables -Suppose a program you are writing needs a hash table with at least -10000 entries. It's best to use a prime number as the actual size -of a hash table. Calc can compute the next prime number after 10000: - -@smallexample -@group -1: 10000 1: 10007 1: 9973 - . . . - - 10000 k n I k n -@end group -@end smallexample - -@noindent -Just for kicks we've also computed the next prime @emph{less} than -10000. - -@c [fix-ref Financial Functions] -@xref{Financial Functions}, for a description of the Calculator -commands that deal with business and financial calculations (functions -like @code{pv}, @code{rate}, and @code{sln}). - -@c [fix-ref Binary Number Functions] -@xref{Binary Functions}, to read about the commands for operating -on binary numbers (like @code{and}, @code{xor}, and @code{lsh}). - -@node Vector/Matrix Tutorial, Types Tutorial, Arithmetic Tutorial, Tutorial -@section Vector/Matrix Tutorial - -@noindent -A @dfn{vector} is a list of numbers or other Calc data objects. -Calc provides a large set of commands that operate on vectors. Some -are familiar operations from vector analysis. Others simply treat -a vector as a list of objects. - -@menu -* Vector Analysis Tutorial:: -* Matrix Tutorial:: -* List Tutorial:: -@end menu - -@node Vector Analysis Tutorial, Matrix Tutorial, Vector/Matrix Tutorial, Vector/Matrix Tutorial -@subsection Vector Analysis - -@noindent -If you add two vectors, the result is a vector of the sums of the -elements, taken pairwise. - -@smallexample -@group -1: [1, 2, 3] 2: [1, 2, 3] 1: [8, 8, 3] - . 1: [7, 6, 0] . - . - - [1,2,3] s 1 [7 6 0] s 2 + -@end group -@end smallexample - -@noindent -Note that we can separate the vector elements with either commas or -spaces. This is true whether we are using incomplete vectors or -algebraic entry. The @kbd{s 1} and @kbd{s 2} commands save these -vectors so we can easily reuse them later. - -If you multiply two vectors, the result is the sum of the products -of the elements taken pairwise. This is called the @dfn{dot product} -of the vectors. - -@smallexample -@group -2: [1, 2, 3] 1: 19 -1: [7, 6, 0] . - . - - r 1 r 2 * -@end group -@end smallexample - -@cindex Dot product -The dot product of two vectors is equal to the product of their -lengths times the cosine of the angle between them. (Here the vector -is interpreted as a line from the origin @expr{(0,0,0)} to the -specified point in three-dimensional space.) The @kbd{A} -(absolute value) command can be used to compute the length of a -vector. - -@smallexample -@group -3: 19 3: 19 1: 0.550782 1: 56.579 -2: [1, 2, 3] 2: 3.741657 . . -1: [7, 6, 0] 1: 9.219544 - . . - - M-@key{RET} M-2 A * / I C -@end group -@end smallexample - -@noindent -First we recall the arguments to the dot product command, then -we compute the absolute values of the top two stack entries to -obtain the lengths of the vectors, then we divide the dot product -by the product of the lengths to get the cosine of the angle. -The inverse cosine finds that the angle between the vectors -is about 56 degrees. - -@cindex Cross product -@cindex Perpendicular vectors -The @dfn{cross product} of two vectors is a vector whose length -is the product of the lengths of the inputs times the sine of the -angle between them, and whose direction is perpendicular to both -input vectors. Unlike the dot product, the cross product is -defined only for three-dimensional vectors. Let's double-check -our computation of the angle using the cross product. - -@smallexample -@group -2: [1, 2, 3] 3: [-18, 21, -8] 1: [-0.52, 0.61, -0.23] 1: 56.579 -1: [7, 6, 0] 2: [1, 2, 3] . . - . 1: [7, 6, 0] - . - - r 1 r 2 V C s 3 M-@key{RET} M-2 A * / A I S -@end group -@end smallexample - -@noindent -First we recall the original vectors and compute their cross product, -which we also store for later reference. Now we divide the vector -by the product of the lengths of the original vectors. The length of -this vector should be the sine of the angle; sure enough, it is! - -@c [fix-ref General Mode Commands] -Vector-related commands generally begin with the @kbd{v} prefix key. -Some are uppercase letters and some are lowercase. To make it easier -to type these commands, the shift-@kbd{V} prefix key acts the same as -the @kbd{v} key. (@xref{General Mode Commands}, for a way to make all -prefix keys have this property.) - -If we take the dot product of two perpendicular vectors we expect -to get zero, since the cosine of 90 degrees is zero. Let's check -that the cross product is indeed perpendicular to both inputs: - -@smallexample -@group -2: [1, 2, 3] 1: 0 2: [7, 6, 0] 1: 0 -1: [-18, 21, -8] . 1: [-18, 21, -8] . - . . - - r 1 r 3 * @key{DEL} r 2 r 3 * -@end group -@end smallexample - -@cindex Normalizing a vector -@cindex Unit vectors -(@bullet{}) @strong{Exercise 1.} Given a vector on the top of the -stack, what keystrokes would you use to @dfn{normalize} the -vector, i.e., to reduce its length to one without changing its -direction? @xref{Vector Answer 1, 1}. (@bullet{}) - -(@bullet{}) @strong{Exercise 2.} Suppose a certain particle can be -at any of several positions along a ruler. You have a list of -those positions in the form of a vector, and another list of the -probabilities for the particle to be at the corresponding positions. -Find the average position of the particle. -@xref{Vector Answer 2, 2}. (@bullet{}) - -@node Matrix Tutorial, List Tutorial, Vector Analysis Tutorial, Vector/Matrix Tutorial -@subsection Matrices - -@noindent -A @dfn{matrix} is just a vector of vectors, all the same length. -This means you can enter a matrix using nested brackets. You can -also use the semicolon character to enter a matrix. We'll show -both methods here: - -@smallexample -@group -1: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ] - [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] - . . - - [[1 2 3] [4 5 6]] ' [1 2 3; 4 5 6] @key{RET} -@end group -@end smallexample - -@noindent -We'll be using this matrix again, so type @kbd{s 4} to save it now. - -Note that semicolons work with incomplete vectors, but they work -better in algebraic entry. That's why we use the apostrophe in -the second example. - -When two matrices are multiplied, the lefthand matrix must have -the same number of columns as the righthand matrix has rows. -Row @expr{i}, column @expr{j} of the result is effectively the -dot product of row @expr{i} of the left matrix by column @expr{j} -of the right matrix. - -If we try to duplicate this matrix and multiply it by itself, -the dimensions are wrong and the multiplication cannot take place: - -@smallexample -@group -1: [ [ 1, 2, 3 ] * [ [ 1, 2, 3 ] - [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] - . - - @key{RET} * -@end group -@end smallexample - -@noindent -Though rather hard to read, this is a formula which shows the product -of two matrices. The @samp{*} function, having invalid arguments, has -been left in symbolic form. - -We can multiply the matrices if we @dfn{transpose} one of them first. - -@smallexample -@group -2: [ [ 1, 2, 3 ] 1: [ [ 14, 32 ] 1: [ [ 17, 22, 27 ] - [ 4, 5, 6 ] ] [ 32, 77 ] ] [ 22, 29, 36 ] -1: [ [ 1, 4 ] . [ 27, 36, 45 ] ] - [ 2, 5 ] . - [ 3, 6 ] ] - . - - U v t * U @key{TAB} * -@end group -@end smallexample - -Matrix multiplication is not commutative; indeed, switching the -order of the operands can even change the dimensions of the result -matrix, as happened here! - -If you multiply a plain vector by a matrix, it is treated as a -single row or column depending on which side of the matrix it is -on. The result is a plain vector which should also be interpreted -as a row or column as appropriate. - -@smallexample -@group -2: [ [ 1, 2, 3 ] 1: [14, 32] - [ 4, 5, 6 ] ] . -1: [1, 2, 3] - . - - r 4 r 1 * -@end group -@end smallexample - -Multiplying in the other order wouldn't work because the number of -rows in the matrix is different from the number of elements in the -vector. - -(@bullet{}) @strong{Exercise 1.} Use @samp{*} to sum along the rows -of the above -@texline @math{2\times3} -@infoline 2x3 -matrix to get @expr{[6, 15]}. Now use @samp{*} to sum along the columns -to get @expr{[5, 7, 9]}. -@xref{Matrix Answer 1, 1}. (@bullet{}) - -@cindex Identity matrix -An @dfn{identity matrix} is a square matrix with ones along the -diagonal and zeros elsewhere. It has the property that multiplication -by an identity matrix, on the left or on the right, always produces -the original matrix. - -@smallexample -@group -1: [ [ 1, 2, 3 ] 2: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ] - [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] - . 1: [ [ 1, 0, 0 ] . - [ 0, 1, 0 ] - [ 0, 0, 1 ] ] - . - - r 4 v i 3 @key{RET} * -@end group -@end smallexample - -If a matrix is square, it is often possible to find its @dfn{inverse}, -that is, a matrix which, when multiplied by the original matrix, yields -an identity matrix. The @kbd{&} (reciprocal) key also computes the -inverse of a matrix. - -@smallexample -@group -1: [ [ 1, 2, 3 ] 1: [ [ -2.4, 1.2, -0.2 ] - [ 4, 5, 6 ] [ 2.8, -1.4, 0.4 ] - [ 7, 6, 0 ] ] [ -0.73333, 0.53333, -0.2 ] ] - . . - - r 4 r 2 | s 5 & -@end group -@end smallexample - -@noindent -The vertical bar @kbd{|} @dfn{concatenates} numbers, vectors, and -matrices together. Here we have used it to add a new row onto -our matrix to make it square. - -We can multiply these two matrices in either order to get an identity. - -@smallexample -@group -1: [ [ 1., 0., 0. ] 1: [ [ 1., 0., 0. ] - [ 0., 1., 0. ] [ 0., 1., 0. ] - [ 0., 0., 1. ] ] [ 0., 0., 1. ] ] - . . - - M-@key{RET} * U @key{TAB} * -@end group -@end smallexample - -@cindex Systems of linear equations -@cindex Linear equations, systems of -Matrix inverses are related to systems of linear equations in algebra. -Suppose we had the following set of equations: - -@ifnottex -@group -@example - a + 2b + 3c = 6 - 4a + 5b + 6c = 2 - 7a + 6b = 3 -@end example -@end group -@end ifnottex -@tex -\beforedisplayh -$$ \openup1\jot \tabskip=0pt plus1fil -\halign to\displaywidth{\tabskip=0pt - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr - a&+&2b&+&3c&=6 \cr - 4a&+&5b&+&6c&=2 \cr - 7a&+&6b& & &=3 \cr} -$$ -\afterdisplayh -@end tex - -@noindent -This can be cast into the matrix equation, - -@ifnottex -@group -@example - [ [ 1, 2, 3 ] [ [ a ] [ [ 6 ] - [ 4, 5, 6 ] * [ b ] = [ 2 ] - [ 7, 6, 0 ] ] [ c ] ] [ 3 ] ] -@end example -@end group -@end ifnottex -@tex -\beforedisplay -$$ \pmatrix{ 1 & 2 & 3 \cr 4 & 5 & 6 \cr 7 & 6 & 0 } - \times - \pmatrix{ a \cr b \cr c } = \pmatrix{ 6 \cr 2 \cr 3 } -$$ -\afterdisplay -@end tex - -We can solve this system of equations by multiplying both sides by the -inverse of the matrix. Calc can do this all in one step: - -@smallexample -@group -2: [6, 2, 3] 1: [-12.6, 15.2, -3.93333] -1: [ [ 1, 2, 3 ] . - [ 4, 5, 6 ] - [ 7, 6, 0 ] ] - . - - [6,2,3] r 5 / -@end group -@end smallexample - -@noindent -The result is the @expr{[a, b, c]} vector that solves the equations. -(Dividing by a square matrix is equivalent to multiplying by its -inverse.) - -Let's verify this solution: - -@smallexample -@group -2: [ [ 1, 2, 3 ] 1: [6., 2., 3.] - [ 4, 5, 6 ] . - [ 7, 6, 0 ] ] -1: [-12.6, 15.2, -3.93333] - . - - r 5 @key{TAB} * -@end group -@end smallexample - -@noindent -Note that we had to be careful about the order in which we multiplied -the matrix and vector. If we multiplied in the other order, Calc would -assume the vector was a row vector in order to make the dimensions -come out right, and the answer would be incorrect. If you -don't feel safe letting Calc take either interpretation of your -vectors, use explicit -@texline @math{N\times1} -@infoline Nx1 -or -@texline @math{1\times N} -@infoline 1xN -matrices instead. In this case, you would enter the original column -vector as @samp{[[6], [2], [3]]} or @samp{[6; 2; 3]}. - -(@bullet{}) @strong{Exercise 2.} Algebraic entry allows you to make -vectors and matrices that include variables. Solve the following -system of equations to get expressions for @expr{x} and @expr{y} -in terms of @expr{a} and @expr{b}. - -@ifnottex -@group -@example - x + a y = 6 - x + b y = 10 -@end example -@end group -@end ifnottex -@tex -\beforedisplay -$$ \eqalign{ x &+ a y = 6 \cr - x &+ b y = 10} -$$ -\afterdisplay -@end tex - -@noindent -@xref{Matrix Answer 2, 2}. (@bullet{}) - -@cindex Least-squares for over-determined systems -@cindex Over-determined systems of equations -(@bullet{}) @strong{Exercise 3.} A system of equations is ``over-determined'' -if it has more equations than variables. It is often the case that -there are no values for the variables that will satisfy all the -equations at once, but it is still useful to find a set of values -which ``nearly'' satisfy all the equations. In terms of matrix equations, -you can't solve @expr{A X = B} directly because the matrix @expr{A} -is not square for an over-determined system. Matrix inversion works -only for square matrices. One common trick is to multiply both sides -on the left by the transpose of @expr{A}: -@ifnottex -@samp{trn(A)*A*X = trn(A)*B}. -@end ifnottex -@tex -$A^T A \, X = A^T B$, where $A^T$ is the transpose \samp{trn(A)}. -@end tex -Now -@texline @math{A^T A} -@infoline @expr{trn(A)*A} -is a square matrix so a solution is possible. It turns out that the -@expr{X} vector you compute in this way will be a ``least-squares'' -solution, which can be regarded as the ``closest'' solution to the set -of equations. Use Calc to solve the following over-determined -system: - -@ifnottex -@group -@example - a + 2b + 3c = 6 - 4a + 5b + 6c = 2 - 7a + 6b = 3 - 2a + 4b + 6c = 11 -@end example -@end group -@end ifnottex -@tex -\beforedisplayh -$$ \openup1\jot \tabskip=0pt plus1fil -\halign to\displaywidth{\tabskip=0pt - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr - a&+&2b&+&3c&=6 \cr - 4a&+&5b&+&6c&=2 \cr - 7a&+&6b& & &=3 \cr - 2a&+&4b&+&6c&=11 \cr} -$$ -\afterdisplayh -@end tex - -@noindent -@xref{Matrix Answer 3, 3}. (@bullet{}) - -@node List Tutorial, , Matrix Tutorial, Vector/Matrix Tutorial -@subsection Vectors as Lists - -@noindent -@cindex Lists -Although Calc has a number of features for manipulating vectors and -matrices as mathematical objects, you can also treat vectors as -simple lists of values. For example, we saw that the @kbd{k f} -command returns a vector which is a list of the prime factors of a -number. - -You can pack and unpack stack entries into vectors: - -@smallexample -@group -3: 10 1: [10, 20, 30] 3: 10 -2: 20 . 2: 20 -1: 30 1: 30 - . . - - M-3 v p v u -@end group -@end smallexample - -You can also build vectors out of consecutive integers, or out -of many copies of a given value: - -@smallexample -@group -1: [1, 2, 3, 4] 2: [1, 2, 3, 4] 2: [1, 2, 3, 4] - . 1: 17 1: [17, 17, 17, 17] - . . - - v x 4 @key{RET} 17 v b 4 @key{RET} -@end group -@end smallexample - -You can apply an operator to every element of a vector using the -@dfn{map} command. - -@smallexample -@group -1: [17, 34, 51, 68] 1: [289, 1156, 2601, 4624] 1: [17, 34, 51, 68] - . . . - - V M * 2 V M ^ V M Q -@end group -@end smallexample - -@noindent -In the first step, we multiply the vector of integers by the vector -of 17's elementwise. In the second step, we raise each element to -the power two. (The general rule is that both operands must be -vectors of the same length, or else one must be a vector and the -other a plain number.) In the final step, we take the square root -of each element. - -(@bullet{}) @strong{Exercise 1.} Compute a vector of powers of two -from -@texline @math{2^{-4}} -@infoline @expr{2^-4} -to @expr{2^4}. @xref{List Answer 1, 1}. (@bullet{}) - -You can also @dfn{reduce} a binary operator across a vector. -For example, reducing @samp{*} computes the product of all the -elements in the vector: - -@smallexample -@group -1: 123123 1: [3, 7, 11, 13, 41] 1: 123123 - . . . - - 123123 k f V R * -@end group -@end smallexample - -@noindent -In this example, we decompose 123123 into its prime factors, then -multiply those factors together again to yield the original number. - -We could compute a dot product ``by hand'' using mapping and -reduction: - -@smallexample -@group -2: [1, 2, 3] 1: [7, 12, 0] 1: 19 -1: [7, 6, 0] . . - . - - r 1 r 2 V M * V R + -@end group -@end smallexample - -@noindent -Recalling two vectors from the previous section, we compute the -sum of pairwise products of the elements to get the same answer -for the dot product as before. - -A slight variant of vector reduction is the @dfn{accumulate} operation, -@kbd{V U}. This produces a vector of the intermediate results from -a corresponding reduction. Here we compute a table of factorials: - -@smallexample -@group -1: [1, 2, 3, 4, 5, 6] 1: [1, 2, 6, 24, 120, 720] - . . - - v x 6 @key{RET} V U * -@end group -@end smallexample - -Calc allows vectors to grow as large as you like, although it gets -rather slow if vectors have more than about a hundred elements. -Actually, most of the time is spent formatting these large vectors -for display, not calculating on them. Try the following experiment -(if your computer is very fast you may need to substitute a larger -vector size). - -@smallexample -@group -1: [1, 2, 3, 4, ... 1: [2, 3, 4, 5, ... - . . - - v x 500 @key{RET} 1 V M + -@end group -@end smallexample - -Now press @kbd{v .} (the letter @kbd{v}, then a period) and try the -experiment again. In @kbd{v .} mode, long vectors are displayed -``abbreviated'' like this: - -@smallexample -@group -1: [1, 2, 3, ..., 500] 1: [2, 3, 4, ..., 501] - . . - - v x 500 @key{RET} 1 V M + -@end group -@end smallexample - -@noindent -(where now the @samp{...} is actually part of the Calc display). -You will find both operations are now much faster. But notice that -even in @w{@kbd{v .}} mode, the full vectors are still shown in the Trail. -Type @w{@kbd{t .}} to cause the trail to abbreviate as well, and try the -experiment one more time. Operations on long vectors are now quite -fast! (But of course if you use @kbd{t .} you will lose the ability -to get old vectors back using the @kbd{t y} command.) - -An easy way to view a full vector when @kbd{v .} mode is active is -to press @kbd{`} (back-quote) to edit the vector; editing always works -with the full, unabbreviated value. - -@cindex Least-squares for fitting a straight line -@cindex Fitting data to a line -@cindex Line, fitting data to -@cindex Data, extracting from buffers -@cindex Columns of data, extracting -As a larger example, let's try to fit a straight line to some data, -using the method of least squares. (Calc has a built-in command for -least-squares curve fitting, but we'll do it by hand here just to -practice working with vectors.) Suppose we have the following list -of values in a file we have loaded into Emacs: - -@smallexample - x y - --- --- - 1.34 0.234 - 1.41 0.298 - 1.49 0.402 - 1.56 0.412 - 1.64 0.466 - 1.73 0.473 - 1.82 0.601 - 1.91 0.519 - 2.01 0.603 - 2.11 0.637 - 2.22 0.645 - 2.33 0.705 - 2.45 0.917 - 2.58 1.009 - 2.71 0.971 - 2.85 1.062 - 3.00 1.148 - 3.15 1.157 - 3.32 1.354 -@end smallexample - -@noindent -If you are reading this tutorial in printed form, you will find it -easiest to press @kbd{C-x * i} to enter the on-line Info version of -the manual and find this table there. (Press @kbd{g}, then type -@kbd{List Tutorial}, to jump straight to this section.) - -Position the cursor at the upper-left corner of this table, just -to the left of the @expr{1.34}. Press @kbd{C-@@} to set the mark. -(On your system this may be @kbd{C-2}, @kbd{C-@key{SPC}}, or @kbd{NUL}.) -Now position the cursor to the lower-right, just after the @expr{1.354}. -You have now defined this region as an Emacs ``rectangle.'' Still -in the Info buffer, type @kbd{C-x * r}. This command -(@code{calc-grab-rectangle}) will pop you back into the Calculator, with -the contents of the rectangle you specified in the form of a matrix. - -@smallexample -@group -1: [ [ 1.34, 0.234 ] - [ 1.41, 0.298 ] - @dots{} -@end group -@end smallexample - -@noindent -(You may wish to use @kbd{v .} mode to abbreviate the display of this -large matrix.) - -We want to treat this as a pair of lists. The first step is to -transpose this matrix into a pair of rows. Remember, a matrix is -just a vector of vectors. So we can unpack the matrix into a pair -of row vectors on the stack. - -@smallexample -@group -1: [ [ 1.34, 1.41, 1.49, ... ] 2: [1.34, 1.41, 1.49, ... ] - [ 0.234, 0.298, 0.402, ... ] ] 1: [0.234, 0.298, 0.402, ... ] - . . - - v t v u -@end group -@end smallexample - -@noindent -Let's store these in quick variables 1 and 2, respectively. - -@smallexample -@group -1: [1.34, 1.41, 1.49, ... ] . - . - - t 2 t 1 -@end group -@end smallexample - -@noindent -(Recall that @kbd{t 2} is a variant of @kbd{s 2} that removes the -stored value from the stack.) - -In a least squares fit, the slope @expr{m} is given by the formula - -@ifnottex -@example -m = (N sum(x y) - sum(x) sum(y)) / (N sum(x^2) - sum(x)^2) -@end example -@end ifnottex -@tex -\beforedisplay -$$ m = {N \sum x y - \sum x \sum y \over - N \sum x^2 - \left( \sum x \right)^2} $$ -\afterdisplay -@end tex - -@noindent -where -@texline @math{\sum x} -@infoline @expr{sum(x)} -represents the sum of all the values of @expr{x}. While there is an -actual @code{sum} function in Calc, it's easier to sum a vector using a -simple reduction. First, let's compute the four different sums that -this formula uses. - -@smallexample -@group -1: 41.63 1: 98.0003 - . . - - r 1 V R + t 3 r 1 2 V M ^ V R + t 4 - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 13.613 1: 33.36554 - . . - - r 2 V R + t 5 r 1 r 2 V M * V R + t 6 -@end group -@end smallexample - -@ifnottex -@noindent -These are @samp{sum(x)}, @samp{sum(x^2)}, @samp{sum(y)}, and @samp{sum(x y)}, -respectively. (We could have used @kbd{*} to compute @samp{sum(x^2)} and -@samp{sum(x y)}.) -@end ifnottex -@tex -These are $\sum x$, $\sum x^2$, $\sum y$, and $\sum x y$, -respectively. (We could have used \kbd{*} to compute $\sum x^2$ and -$\sum x y$.) -@end tex - -Finally, we also need @expr{N}, the number of data points. This is just -the length of either of our lists. - -@smallexample -@group -1: 19 - . - - r 1 v l t 7 -@end group -@end smallexample - -@noindent -(That's @kbd{v} followed by a lower-case @kbd{l}.) - -Now we grind through the formula: - -@smallexample -@group -1: 633.94526 2: 633.94526 1: 67.23607 - . 1: 566.70919 . - . - - r 7 r 6 * r 3 r 5 * - - -@end group -@end smallexample -@noindent -@smallexample -@group -2: 67.23607 3: 67.23607 2: 67.23607 1: 0.52141679 -1: 1862.0057 2: 1862.0057 1: 128.9488 . - . 1: 1733.0569 . - . - - r 7 r 4 * r 3 2 ^ - / t 8 -@end group -@end smallexample - -That gives us the slope @expr{m}. The y-intercept @expr{b} can now -be found with the simple formula, - -@ifnottex -@example -b = (sum(y) - m sum(x)) / N -@end example -@end ifnottex -@tex -\beforedisplay -$$ b = {\sum y - m \sum x \over N} $$ -\afterdisplay -\vskip10pt -@end tex - -@smallexample -@group -1: 13.613 2: 13.613 1: -8.09358 1: -0.425978 - . 1: 21.70658 . . - . - - r 5 r 8 r 3 * - r 7 / t 9 -@end group -@end smallexample - -Let's ``plot'' this straight line approximation, -@texline @math{y \approx m x + b}, -@infoline @expr{m x + b}, -and compare it with the original data. - -@smallexample -@group -1: [0.699, 0.735, ... ] 1: [0.273, 0.309, ... ] - . . - - r 1 r 8 * r 9 + s 0 -@end group -@end smallexample - -@noindent -Notice that multiplying a vector by a constant, and adding a constant -to a vector, can be done without mapping commands since these are -common operations from vector algebra. As far as Calc is concerned, -we've just been doing geometry in 19-dimensional space! - -We can subtract this vector from our original @expr{y} vector to get -a feel for the error of our fit. Let's find the maximum error: - -@smallexample -@group -1: [0.0387, 0.0112, ... ] 1: [0.0387, 0.0112, ... ] 1: 0.0897 - . . . - - r 2 - V M A V R X -@end group -@end smallexample - -@noindent -First we compute a vector of differences, then we take the absolute -values of these differences, then we reduce the @code{max} function -across the vector. (The @code{max} function is on the two-key sequence -@kbd{f x}; because it is so common to use @code{max} in a vector -operation, the letters @kbd{X} and @kbd{N} are also accepted for -@code{max} and @code{min} in this context. In general, you answer -the @kbd{V M} or @kbd{V R} prompt with the actual key sequence that -invokes the function you want. You could have typed @kbd{V R f x} or -even @kbd{V R x max @key{RET}} if you had preferred.) - -If your system has the GNUPLOT program, you can see graphs of your -data and your straight line to see how well they match. (If you have -GNUPLOT 3.0 or higher, the following instructions will work regardless -of the kind of display you have. Some GNUPLOT 2.0, non-X-windows systems -may require additional steps to view the graphs.) - -Let's start by plotting the original data. Recall the ``@var{x}'' and ``@var{y}'' -vectors onto the stack and press @kbd{g f}. This ``fast'' graphing -command does everything you need to do for simple, straightforward -plotting of data. - -@smallexample -@group -2: [1.34, 1.41, 1.49, ... ] -1: [0.234, 0.298, 0.402, ... ] - . - - r 1 r 2 g f -@end group -@end smallexample - -If all goes well, you will shortly get a new window containing a graph -of the data. (If not, contact your GNUPLOT or Calc installer to find -out what went wrong.) In the X window system, this will be a separate -graphics window. For other kinds of displays, the default is to -display the graph in Emacs itself using rough character graphics. -Press @kbd{q} when you are done viewing the character graphics. - -Next, let's add the line we got from our least-squares fit. -@ifinfo -(If you are reading this tutorial on-line while running Calc, typing -@kbd{g a} may cause the tutorial to disappear from its window and be -replaced by a buffer named @samp{*Gnuplot Commands*}. The tutorial -will reappear when you terminate GNUPLOT by typing @kbd{g q}.) -@end ifinfo - -@smallexample -@group -2: [1.34, 1.41, 1.49, ... ] -1: [0.273, 0.309, 0.351, ... ] - . - - @key{DEL} r 0 g a g p -@end group -@end smallexample - -It's not very useful to get symbols to mark the data points on this -second curve; you can type @kbd{g S g p} to remove them. Type @kbd{g q} -when you are done to remove the X graphics window and terminate GNUPLOT. - -(@bullet{}) @strong{Exercise 2.} An earlier exercise showed how to do -least squares fitting to a general system of equations. Our 19 data -points are really 19 equations of the form @expr{y_i = m x_i + b} for -different pairs of @expr{(x_i,y_i)}. Use the matrix-transpose method -to solve for @expr{m} and @expr{b}, duplicating the above result. -@xref{List Answer 2, 2}. (@bullet{}) - -@cindex Geometric mean -(@bullet{}) @strong{Exercise 3.} If the input data do not form a -rectangle, you can use @w{@kbd{C-x * g}} (@code{calc-grab-region}) -to grab the data the way Emacs normally works with regions---it reads -left-to-right, top-to-bottom, treating line breaks the same as spaces. -Use this command to find the geometric mean of the following numbers. -(The geometric mean is the @var{n}th root of the product of @var{n} numbers.) - -@example -2.3 6 22 15.1 7 - 15 14 7.5 - 2.5 -@end example - -@noindent -The @kbd{C-x * g} command accepts numbers separated by spaces or commas, -with or without surrounding vector brackets. -@xref{List Answer 3, 3}. (@bullet{}) - -@ifnottex -As another example, a theorem about binomial coefficients tells -us that the alternating sum of binomial coefficients -@var{n}-choose-0 minus @var{n}-choose-1 plus @var{n}-choose-2, and so -on up to @var{n}-choose-@var{n}, -always comes out to zero. Let's verify this -for @expr{n=6}. -@end ifnottex -@tex -As another example, a theorem about binomial coefficients tells -us that the alternating sum of binomial coefficients -${n \choose 0} - {n \choose 1} + {n \choose 2} - \cdots \pm {n \choose n}$ -always comes out to zero. Let's verify this -for \cite{n=6}. -@end tex - -@smallexample -@group -1: [1, 2, 3, 4, 5, 6, 7] 1: [0, 1, 2, 3, 4, 5, 6] - . . - - v x 7 @key{RET} 1 - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [1, -6, 15, -20, 15, -6, 1] 1: 0 - . . - - V M ' (-1)^$ choose(6,$) @key{RET} V R + -@end group -@end smallexample - -The @kbd{V M '} command prompts you to enter any algebraic expression -to define the function to map over the vector. The symbol @samp{$} -inside this expression represents the argument to the function. -The Calculator applies this formula to each element of the vector, -substituting each element's value for the @samp{$} sign(s) in turn. - -To define a two-argument function, use @samp{$$} for the first -argument and @samp{$} for the second: @kbd{V M ' $$-$ @key{RET}} is -equivalent to @kbd{V M -}. This is analogous to regular algebraic -entry, where @samp{$$} would refer to the next-to-top stack entry -and @samp{$} would refer to the top stack entry, and @kbd{' $$-$ @key{RET}} -would act exactly like @kbd{-}. - -Notice that the @kbd{V M '} command has recorded two things in the -trail: The result, as usual, and also a funny-looking thing marked -@samp{oper} that represents the operator function you typed in. -The function is enclosed in @samp{< >} brackets, and the argument is -denoted by a @samp{#} sign. If there were several arguments, they -would be shown as @samp{#1}, @samp{#2}, and so on. (For example, -@kbd{V M ' $$-$} will put the function @samp{<#1 - #2>} on the -trail.) This object is a ``nameless function''; you can use nameless -@w{@samp{< >}} notation to answer the @kbd{V M '} prompt if you like. -Nameless function notation has the interesting, occasionally useful -property that a nameless function is not actually evaluated until -it is used. For example, @kbd{V M ' $+random(2.0)} evaluates -@samp{random(2.0)} once and adds that random number to all elements -of the vector, but @kbd{V M ' <#+random(2.0)>} evaluates the -@samp{random(2.0)} separately for each vector element. - -Another group of operators that are often useful with @kbd{V M} are -the relational operators: @kbd{a =}, for example, compares two numbers -and gives the result 1 if they are equal, or 0 if not. Similarly, -@w{@kbd{a <}} checks for one number being less than another. - -Other useful vector operations include @kbd{v v}, to reverse a -vector end-for-end; @kbd{V S}, to sort the elements of a vector -into increasing order; and @kbd{v r} and @w{@kbd{v c}}, to extract -one row or column of a matrix, or (in both cases) to extract one -element of a plain vector. With a negative argument, @kbd{v r} -and @kbd{v c} instead delete one row, column, or vector element. - -@cindex Divisor functions -(@bullet{}) @strong{Exercise 4.} The @expr{k}th @dfn{divisor function} -@tex -$\sigma_k(n)$ -@end tex -is the sum of the @expr{k}th powers of all the divisors of an -integer @expr{n}. Figure out a method for computing the divisor -function for reasonably small values of @expr{n}. As a test, -the 0th and 1st divisor functions of 30 are 8 and 72, respectively. -@xref{List Answer 4, 4}. (@bullet{}) - -@cindex Square-free numbers -@cindex Duplicate values in a list -(@bullet{}) @strong{Exercise 5.} The @kbd{k f} command produces a -list of prime factors for a number. Sometimes it is important to -know that a number is @dfn{square-free}, i.e., that no prime occurs -more than once in its list of prime factors. Find a sequence of -keystrokes to tell if a number is square-free; your method should -leave 1 on the stack if it is, or 0 if it isn't. -@xref{List Answer 5, 5}. (@bullet{}) - -@cindex Triangular lists -(@bullet{}) @strong{Exercise 6.} Build a list of lists that looks -like the following diagram. (You may wish to use the @kbd{v /} -command to enable multi-line display of vectors.) - -@smallexample -@group -1: [ [1], - [1, 2], - [1, 2, 3], - [1, 2, 3, 4], - [1, 2, 3, 4, 5], - [1, 2, 3, 4, 5, 6] ] -@end group -@end smallexample - -@noindent -@xref{List Answer 6, 6}. (@bullet{}) - -(@bullet{}) @strong{Exercise 7.} Build the following list of lists. - -@smallexample -@group -1: [ [0], - [1, 2], - [3, 4, 5], - [6, 7, 8, 9], - [10, 11, 12, 13, 14], - [15, 16, 17, 18, 19, 20] ] -@end group -@end smallexample - -@noindent -@xref{List Answer 7, 7}. (@bullet{}) - -@cindex Maximizing a function over a list of values -@c [fix-ref Numerical Solutions] -(@bullet{}) @strong{Exercise 8.} Compute a list of values of Bessel's -@texline @math{J_1(x)} -@infoline @expr{J1} -function @samp{besJ(1,x)} for @expr{x} from 0 to 5 in steps of 0.25. -Find the value of @expr{x} (from among the above set of values) for -which @samp{besJ(1,x)} is a maximum. Use an ``automatic'' method, -i.e., just reading along the list by hand to find the largest value -is not allowed! (There is an @kbd{a X} command which does this kind -of thing automatically; @pxref{Numerical Solutions}.) -@xref{List Answer 8, 8}. (@bullet{}) - -@cindex Digits, vectors of -(@bullet{}) @strong{Exercise 9.} You are given an integer in the range -@texline @math{0 \le N < 10^m} -@infoline @expr{0 <= N < 10^m} -for @expr{m=12} (i.e., an integer of less than -twelve digits). Convert this integer into a vector of @expr{m} -digits, each in the range from 0 to 9. In vector-of-digits notation, -add one to this integer to produce a vector of @expr{m+1} digits -(since there could be a carry out of the most significant digit). -Convert this vector back into a regular integer. A good integer -to try is 25129925999. @xref{List Answer 9, 9}. (@bullet{}) - -(@bullet{}) @strong{Exercise 10.} Your friend Joe tried to use -@kbd{V R a =} to test if all numbers in a list were equal. What -happened? How would you do this test? @xref{List Answer 10, 10}. (@bullet{}) - -(@bullet{}) @strong{Exercise 11.} The area of a circle of radius one -is @cpi{}. The area of the -@texline @math{2\times2} -@infoline 2x2 -square that encloses that circle is 4. So if we throw @var{n} darts at -random points in the square, about @cpiover{4} of them will land inside -the circle. This gives us an entertaining way to estimate the value of -@cpi{}. The @w{@kbd{k r}} -command picks a random number between zero and the value on the stack. -We could get a random floating-point number between @mathit{-1} and 1 by typing -@w{@kbd{2.0 k r 1 -}}. Build a vector of 100 random @expr{(x,y)} points in -this square, then use vector mapping and reduction to count how many -points lie inside the unit circle. Hint: Use the @kbd{v b} command. -@xref{List Answer 11, 11}. (@bullet{}) - -@cindex Matchstick problem -(@bullet{}) @strong{Exercise 12.} The @dfn{matchstick problem} provides -another way to calculate @cpi{}. Say you have an infinite field -of vertical lines with a spacing of one inch. Toss a one-inch matchstick -onto the field. The probability that the matchstick will land crossing -a line turns out to be -@texline @math{2/\pi}. -@infoline @expr{2/pi}. -Toss 100 matchsticks to estimate @cpi{}. (If you want still more fun, -the probability that the GCD (@w{@kbd{k g}}) of two large integers is -one turns out to be -@texline @math{6/\pi^2}. -@infoline @expr{6/pi^2}. -That provides yet another way to estimate @cpi{}.) -@xref{List Answer 12, 12}. (@bullet{}) - -(@bullet{}) @strong{Exercise 13.} An algebraic entry of a string in -double-quote marks, @samp{"hello"}, creates a vector of the numerical -(ASCII) codes of the characters (here, @expr{[104, 101, 108, 108, 111]}). -Sometimes it is convenient to compute a @dfn{hash code} of a string, -which is just an integer that represents the value of that string. -Two equal strings have the same hash code; two different strings -@dfn{probably} have different hash codes. (For example, Calc has -over 400 function names, but Emacs can quickly find the definition for -any given name because it has sorted the functions into ``buckets'' by -their hash codes. Sometimes a few names will hash into the same bucket, -but it is easier to search among a few names than among all the names.) -One popular hash function is computed as follows: First set @expr{h = 0}. -Then, for each character from the string in turn, set @expr{h = 3h + c_i} -where @expr{c_i} is the character's ASCII code. If we have 511 buckets, -we then take the hash code modulo 511 to get the bucket number. Develop a -simple command or commands for converting string vectors into hash codes. -The hash code for @samp{"Testing, 1, 2, 3"} is 1960915098, which modulo -511 is 121. @xref{List Answer 13, 13}. (@bullet{}) - -(@bullet{}) @strong{Exercise 14.} The @kbd{H V R} and @kbd{H V U} -commands do nested function evaluations. @kbd{H V U} takes a starting -value and a number of steps @var{n} from the stack; it then applies the -function you give to the starting value 0, 1, 2, up to @var{n} times -and returns a vector of the results. Use this command to create a -``random walk'' of 50 steps. Start with the two-dimensional point -@expr{(0,0)}; then take one step a random distance between @mathit{-1} and 1 -in both @expr{x} and @expr{y}; then take another step, and so on. Use the -@kbd{g f} command to display this random walk. Now modify your random -walk to walk a unit distance, but in a random direction, at each step. -(Hint: The @code{sincos} function returns a vector of the cosine and -sine of an angle.) @xref{List Answer 14, 14}. (@bullet{}) - -@node Types Tutorial, Algebra Tutorial, Vector/Matrix Tutorial, Tutorial -@section Types Tutorial - -@noindent -Calc understands a variety of data types as well as simple numbers. -In this section, we'll experiment with each of these types in turn. - -The numbers we've been using so far have mainly been either @dfn{integers} -or @dfn{floats}. We saw that floats are usually a good approximation to -the mathematical concept of real numbers, but they are only approximations -and are susceptible to roundoff error. Calc also supports @dfn{fractions}, -which can exactly represent any rational number. - -@smallexample -@group -1: 3628800 2: 3628800 1: 518400:7 1: 518414:7 1: 7:518414 - . 1: 49 . . . - . - - 10 ! 49 @key{RET} : 2 + & -@end group -@end smallexample - -@noindent -The @kbd{:} command divides two integers to get a fraction; @kbd{/} -would normally divide integers to get a floating-point result. -Notice we had to type @key{RET} between the @kbd{49} and the @kbd{:} -since the @kbd{:} would otherwise be interpreted as part of a -fraction beginning with 49. - -You can convert between floating-point and fractional format using -@kbd{c f} and @kbd{c F}: - -@smallexample -@group -1: 1.35027217629e-5 1: 7:518414 - . . - - c f c F -@end group -@end smallexample - -The @kbd{c F} command replaces a floating-point number with the -``simplest'' fraction whose floating-point representation is the -same, to within the current precision. - -@smallexample -@group -1: 3.14159265359 1: 1146408:364913 1: 3.1416 1: 355:113 - . . . . - - P c F @key{DEL} p 5 @key{RET} P c F -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 1.} A calculation has produced the -result 1.26508260337. You suspect it is the square root of the -product of @cpi{} and some rational number. Is it? (Be sure -to allow for roundoff error!) @xref{Types Answer 1, 1}. (@bullet{}) - -@dfn{Complex numbers} can be stored in both rectangular and polar form. - -@smallexample -@group -1: -9 1: (0, 3) 1: (3; 90.) 1: (6; 90.) 1: (2.4495; 45.) - . . . . . - - 9 n Q c p 2 * Q -@end group -@end smallexample - -@noindent -The square root of @mathit{-9} is by default rendered in rectangular form -(@w{@expr{0 + 3i}}), but we can convert it to polar form (3 with a -phase angle of 90 degrees). All the usual arithmetic and scientific -operations are defined on both types of complex numbers. - -Another generalized kind of number is @dfn{infinity}. Infinity -isn't really a number, but it can sometimes be treated like one. -Calc uses the symbol @code{inf} to represent positive infinity, -i.e., a value greater than any real number. Naturally, you can -also write @samp{-inf} for minus infinity, a value less than any -real number. The word @code{inf} can only be input using -algebraic entry. - -@smallexample -@group -2: inf 2: -inf 2: -inf 2: -inf 1: nan -1: -17 1: -inf 1: -inf 1: inf . - . . . . - -' inf @key{RET} 17 n * @key{RET} 72 + A + -@end group -@end smallexample - -@noindent -Since infinity is infinitely large, multiplying it by any finite -number (like @mathit{-17}) has no effect, except that since @mathit{-17} -is negative, it changes a plus infinity to a minus infinity. -(``A huge positive number, multiplied by @mathit{-17}, yields a huge -negative number.'') Adding any finite number to infinity also -leaves it unchanged. Taking an absolute value gives us plus -infinity again. Finally, we add this plus infinity to the minus -infinity we had earlier. If you work it out, you might expect -the answer to be @mathit{-72} for this. But the 72 has been completely -lost next to the infinities; by the time we compute @w{@samp{inf - inf}} -the finite difference between them, if any, is undetectable. -So we say the result is @dfn{indeterminate}, which Calc writes -with the symbol @code{nan} (for Not A Number). - -Dividing by zero is normally treated as an error, but you can get -Calc to write an answer in terms of infinity by pressing @kbd{m i} -to turn on Infinite mode. - -@smallexample -@group -3: nan 2: nan 2: nan 2: nan 1: nan -2: 1 1: 1 / 0 1: uinf 1: uinf . -1: 0 . . . - . - - 1 @key{RET} 0 / m i U / 17 n * + -@end group -@end smallexample - -@noindent -Dividing by zero normally is left unevaluated, but after @kbd{m i} -it instead gives an infinite result. The answer is actually -@code{uinf}, ``undirected infinity.'' If you look at a graph of -@expr{1 / x} around @w{@expr{x = 0}}, you'll see that it goes toward -plus infinity as you approach zero from above, but toward minus -infinity as you approach from below. Since we said only @expr{1 / 0}, -Calc knows that the answer is infinite but not in which direction. -That's what @code{uinf} means. Notice that multiplying @code{uinf} -by a negative number still leaves plain @code{uinf}; there's no -point in saying @samp{-uinf} because the sign of @code{uinf} is -unknown anyway. Finally, we add @code{uinf} to our @code{nan}, -yielding @code{nan} again. It's easy to see that, because -@code{nan} means ``totally unknown'' while @code{uinf} means -``unknown sign but known to be infinite,'' the more mysterious -@code{nan} wins out when it is combined with @code{uinf}, or, for -that matter, with anything else. - -(@bullet{}) @strong{Exercise 2.} Predict what Calc will answer -for each of these formulas: @samp{inf / inf}, @samp{exp(inf)}, -@samp{exp(-inf)}, @samp{sqrt(-inf)}, @samp{sqrt(uinf)}, -@samp{abs(uinf)}, @samp{ln(0)}. -@xref{Types Answer 2, 2}. (@bullet{}) - -(@bullet{}) @strong{Exercise 3.} We saw that @samp{inf - inf = nan}, -which stands for an unknown value. Can @code{nan} stand for -a complex number? Can it stand for infinity? -@xref{Types Answer 3, 3}. (@bullet{}) - -@dfn{HMS forms} represent a value in terms of hours, minutes, and -seconds. - -@smallexample -@group -1: 2@@ 30' 0" 1: 3@@ 30' 0" 2: 3@@ 30' 0" 1: 2. - . . 1: 1@@ 45' 0." . - . - - 2@@ 30' @key{RET} 1 + @key{RET} 2 / / -@end group -@end smallexample - -HMS forms can also be used to hold angles in degrees, minutes, and -seconds. - -@smallexample -@group -1: 0.5 1: 26.56505 1: 26@@ 33' 54.18" 1: 0.44721 - . . . . - - 0.5 I T c h S -@end group -@end smallexample - -@noindent -First we convert the inverse tangent of 0.5 to degrees-minutes-seconds -form, then we take the sine of that angle. Note that the trigonometric -functions will accept HMS forms directly as input. - -@cindex Beatles -(@bullet{}) @strong{Exercise 4.} The Beatles' @emph{Abbey Road} is -47 minutes and 26 seconds long, and contains 17 songs. What is the -average length of a song on @emph{Abbey Road}? If the Extended Disco -Version of @emph{Abbey Road} added 20 seconds to the length of each -song, how long would the album be? @xref{Types Answer 4, 4}. (@bullet{}) - -A @dfn{date form} represents a date, or a date and time. Dates must -be entered using algebraic entry. Date forms are surrounded by -@samp{< >} symbols; most standard formats for dates are recognized. - -@smallexample -@group -2: 1: 2.25 -1: <6:00pm Thu Jan 10, 1991> . - . - -' <13 Jan 1991>, <1/10/91, 6pm> @key{RET} - -@end group -@end smallexample - -@noindent -In this example, we enter two dates, then subtract to find the -number of days between them. It is also possible to add an -HMS form or a number (of days) to a date form to get another -date form. - -@smallexample -@group -1: <4:45:59pm Mon Jan 14, 1991> 1: <2:50:59am Thu Jan 17, 1991> - . . - - t N 2 + 10@@ 5' + -@end group -@end smallexample - -@c [fix-ref Date Arithmetic] -@noindent -The @kbd{t N} (``now'') command pushes the current date and time on the -stack; then we add two days, ten hours and five minutes to the date and -time. Other date-and-time related commands include @kbd{t J}, which -does Julian day conversions, @kbd{t W}, which finds the beginning of -the week in which a date form lies, and @kbd{t I}, which increments a -date by one or several months. @xref{Date Arithmetic}, for more. - -(@bullet{}) @strong{Exercise 5.} How many days until the next -Friday the 13th? @xref{Types Answer 5, 5}. (@bullet{}) - -(@bullet{}) @strong{Exercise 6.} How many leap years will there be -between now and the year 10001 A.D.? @xref{Types Answer 6, 6}. (@bullet{}) - -@cindex Slope and angle of a line -@cindex Angle and slope of a line -An @dfn{error form} represents a mean value with an attached standard -deviation, or error estimate. Suppose our measurements indicate that -a certain telephone pole is about 30 meters away, with an estimated -error of 1 meter, and 8 meters tall, with an estimated error of 0.2 -meters. What is the slope of a line from here to the top of the -pole, and what is the equivalent angle in degrees? - -@smallexample -@group -1: 8 +/- 0.2 2: 8 +/- 0.2 1: 0.266 +/- 0.011 1: 14.93 +/- 0.594 - . 1: 30 +/- 1 . . - . - - 8 p .2 @key{RET} 30 p 1 / I T -@end group -@end smallexample - -@noindent -This means that the angle is about 15 degrees, and, assuming our -original error estimates were valid standard deviations, there is about -a 60% chance that the result is correct within 0.59 degrees. - -@cindex Torus, volume of -(@bullet{}) @strong{Exercise 7.} The volume of a torus (a donut shape) is -@texline @math{2 \pi^2 R r^2} -@infoline @w{@expr{2 pi^2 R r^2}} -where @expr{R} is the radius of the circle that -defines the center of the tube and @expr{r} is the radius of the tube -itself. Suppose @expr{R} is 20 cm and @expr{r} is 4 cm, each known to -within 5 percent. What is the volume and the relative uncertainty of -the volume? @xref{Types Answer 7, 7}. (@bullet{}) - -An @dfn{interval form} represents a range of values. While an -error form is best for making statistical estimates, intervals give -you exact bounds on an answer. Suppose we additionally know that -our telephone pole is definitely between 28 and 31 meters away, -and that it is between 7.7 and 8.1 meters tall. - -@smallexample -@group -1: [7.7 .. 8.1] 2: [7.7 .. 8.1] 1: [0.24 .. 0.28] 1: [13.9 .. 16.1] - . 1: [28 .. 31] . . - . - - [ 7.7 .. 8.1 ] [ 28 .. 31 ] / I T -@end group -@end smallexample - -@noindent -If our bounds were correct, then the angle to the top of the pole -is sure to lie in the range shown. - -The square brackets around these intervals indicate that the endpoints -themselves are allowable values. In other words, the distance to the -telephone pole is between 28 and 31, @emph{inclusive}. You can also -make an interval that is exclusive of its endpoints by writing -parentheses instead of square brackets. You can even make an interval -which is inclusive (``closed'') on one end and exclusive (``open'') on -the other. - -@smallexample -@group -1: [1 .. 10) 1: (0.1 .. 1] 2: (0.1 .. 1] 1: (0.2 .. 3) - . . 1: [2 .. 3) . - . - - [ 1 .. 10 ) & [ 2 .. 3 ) * -@end group -@end smallexample - -@noindent -The Calculator automatically keeps track of which end values should -be open and which should be closed. You can also make infinite or -semi-infinite intervals by using @samp{-inf} or @samp{inf} for one -or both endpoints. - -(@bullet{}) @strong{Exercise 8.} What answer would you expect from -@samp{@w{1 /} @w{(0 .. 10)}}? What about @samp{@w{1 /} @w{(-10 .. 0)}}? What -about @samp{@w{1 /} @w{[0 .. 10]}} (where the interval actually includes -zero)? What about @samp{@w{1 /} @w{(-10 .. 10)}}? -@xref{Types Answer 8, 8}. (@bullet{}) - -(@bullet{}) @strong{Exercise 9.} Two easy ways of squaring a number -are @kbd{@key{RET} *} and @w{@kbd{2 ^}}. Normally these produce the same -answer. Would you expect this still to hold true for interval forms? -If not, which of these will result in a larger interval? -@xref{Types Answer 9, 9}. (@bullet{}) - -A @dfn{modulo form} is used for performing arithmetic modulo @var{m}. -For example, arithmetic involving time is generally done modulo 12 -or 24 hours. - -@smallexample -@group -1: 17 mod 24 1: 3 mod 24 1: 21 mod 24 1: 9 mod 24 - . . . . - - 17 M 24 @key{RET} 10 + n 5 / -@end group -@end smallexample - -@noindent -In this last step, Calc has divided by 5 modulo 24; i.e., it has found a -new number which, when multiplied by 5 modulo 24, produces the original -number, 21. If @var{m} is prime and the divisor is not a multiple of -@var{m}, it is always possible to find such a number. For non-prime -@var{m} like 24, it is only sometimes possible. - -@smallexample -@group -1: 10 mod 24 1: 16 mod 24 1: 1000000... 1: 16 - . . . . - - 10 M 24 @key{RET} 100 ^ 10 @key{RET} 100 ^ 24 % -@end group -@end smallexample - -@noindent -These two calculations get the same answer, but the first one is -much more efficient because it avoids the huge intermediate value -that arises in the second one. - -@cindex Fermat, primality test of -(@bullet{}) @strong{Exercise 10.} A theorem of Pierre de Fermat -says that -@texline @w{@math{x^{n-1} \bmod n = 1}} -@infoline @expr{x^(n-1) mod n = 1} -if @expr{n} is a prime number and @expr{x} is an integer less than -@expr{n}. If @expr{n} is @emph{not} a prime number, this will -@emph{not} be true for most values of @expr{x}. Thus we can test -informally if a number is prime by trying this formula for several -values of @expr{x}. Use this test to tell whether the following numbers -are prime: 811749613, 15485863. @xref{Types Answer 10, 10}. (@bullet{}) - -It is possible to use HMS forms as parts of error forms, intervals, -modulo forms, or as the phase part of a polar complex number. -For example, the @code{calc-time} command pushes the current time -of day on the stack as an HMS/modulo form. - -@smallexample -@group -1: 17@@ 34' 45" mod 24@@ 0' 0" 1: 6@@ 22' 15" mod 24@@ 0' 0" - . . - - x time @key{RET} n -@end group -@end smallexample - -@noindent -This calculation tells me it is six hours and 22 minutes until midnight. - -(@bullet{}) @strong{Exercise 11.} A rule of thumb is that one year -is about -@texline @math{\pi \times 10^7} -@infoline @w{@expr{pi * 10^7}} -seconds. What time will it be that many seconds from right now? -@xref{Types Answer 11, 11}. (@bullet{}) - -(@bullet{}) @strong{Exercise 12.} You are preparing to order packaging -for the CD release of the Extended Disco Version of @emph{Abbey Road}. -You are told that the songs will actually be anywhere from 20 to 60 -seconds longer than the originals. One CD can hold about 75 minutes -of music. Should you order single or double packages? -@xref{Types Answer 12, 12}. (@bullet{}) - -Another kind of data the Calculator can manipulate is numbers with -@dfn{units}. This isn't strictly a new data type; it's simply an -application of algebraic expressions, where we use variables with -suggestive names like @samp{cm} and @samp{in} to represent units -like centimeters and inches. - -@smallexample -@group -1: 2 in 1: 5.08 cm 1: 0.027778 fath 1: 0.0508 m - . . . . - - ' 2in @key{RET} u c cm @key{RET} u c fath @key{RET} u b -@end group -@end smallexample - -@noindent -We enter the quantity ``2 inches'' (actually an algebraic expression -which means two times the variable @samp{in}), then we convert it -first to centimeters, then to fathoms, then finally to ``base'' units, -which in this case means meters. - -@smallexample -@group -1: 9 acre 1: 3 sqrt(acre) 1: 190.84 m 1: 190.84 m + 30 cm - . . . . - - ' 9 acre @key{RET} Q u s ' $+30 cm @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 191.14 m 1: 36536.3046 m^2 1: 365363046 cm^2 - . . . - - u s 2 ^ u c cgs -@end group -@end smallexample - -@noindent -Since units expressions are really just formulas, taking the square -root of @samp{acre} is undefined. After all, @code{acre} might be an -algebraic variable that you will someday assign a value. We use the -``units-simplify'' command to simplify the expression with variables -being interpreted as unit names. - -In the final step, we have converted not to a particular unit, but to a -units system. The ``cgs'' system uses centimeters instead of meters -as its standard unit of length. - -There is a wide variety of units defined in the Calculator. - -@smallexample -@group -1: 55 mph 1: 88.5139 kph 1: 88.5139 km / hr 1: 8.201407e-8 c - . . . . - - ' 55 mph @key{RET} u c kph @key{RET} u c km/hr @key{RET} u c c @key{RET} -@end group -@end smallexample - -@noindent -We express a speed first in miles per hour, then in kilometers per -hour, then again using a slightly more explicit notation, then -finally in terms of fractions of the speed of light. - -Temperature conversions are a bit more tricky. There are two ways to -interpret ``20 degrees Fahrenheit''---it could mean an actual -temperature, or it could mean a change in temperature. For normal -units there is no difference, but temperature units have an offset -as well as a scale factor and so there must be two explicit commands -for them. - -@smallexample -@group -1: 20 degF 1: 11.1111 degC 1: -20:3 degC 1: -6.666 degC - . . . . - - ' 20 degF @key{RET} u c degC @key{RET} U u t degC @key{RET} c f -@end group -@end smallexample - -@noindent -First we convert a change of 20 degrees Fahrenheit into an equivalent -change in degrees Celsius (or Centigrade). Then, we convert the -absolute temperature 20 degrees Fahrenheit into Celsius. Since -this comes out as an exact fraction, we then convert to floating-point -for easier comparison with the other result. - -For simple unit conversions, you can put a plain number on the stack. -Then @kbd{u c} and @kbd{u t} will prompt for both old and new units. -When you use this method, you're responsible for remembering which -numbers are in which units: - -@smallexample -@group -1: 55 1: 88.5139 1: 8.201407e-8 - . . . - - 55 u c mph @key{RET} kph @key{RET} u c km/hr @key{RET} c @key{RET} -@end group -@end smallexample - -To see a complete list of built-in units, type @kbd{u v}. Press -@w{@kbd{C-x * c}} again to re-enter the Calculator when you're done looking -at the units table. - -(@bullet{}) @strong{Exercise 13.} How many seconds are there really -in a year? @xref{Types Answer 13, 13}. (@bullet{}) - -@cindex Speed of light -(@bullet{}) @strong{Exercise 14.} Supercomputer designs are limited by -the speed of light (and of electricity, which is nearly as fast). -Suppose a computer has a 4.1 ns (nanosecond) clock cycle, and its -cabinet is one meter across. Is speed of light going to be a -significant factor in its design? @xref{Types Answer 14, 14}. (@bullet{}) - -(@bullet{}) @strong{Exercise 15.} Sam the Slug normally travels about -five yards in an hour. He has obtained a supply of Power Pills; each -Power Pill he eats doubles his speed. How many Power Pills can he -swallow and still travel legally on most US highways? -@xref{Types Answer 15, 15}. (@bullet{}) - -@node Algebra Tutorial, Programming Tutorial, Types Tutorial, Tutorial -@section Algebra and Calculus Tutorial - -@noindent -This section shows how to use Calc's algebra facilities to solve -equations, do simple calculus problems, and manipulate algebraic -formulas. - -@menu -* Basic Algebra Tutorial:: -* Rewrites Tutorial:: -@end menu - -@node Basic Algebra Tutorial, Rewrites Tutorial, Algebra Tutorial, Algebra Tutorial -@subsection Basic Algebra - -@noindent -If you enter a formula in Algebraic mode that refers to variables, -the formula itself is pushed onto the stack. You can manipulate -formulas as regular data objects. - -@smallexample -@group -1: 2 x^2 - 6 1: 6 - 2 x^2 1: (6 - 2 x^2) (3 x^2 + y) - . . . - - ' 2x^2-6 @key{RET} n ' 3x^2+y @key{RET} * -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 1.} Do @kbd{' x @key{RET} Q 2 ^} and -@kbd{' x @key{RET} 2 ^ Q} both wind up with the same result (@samp{x})? -Why or why not? @xref{Algebra Answer 1, 1}. (@bullet{}) - -There are also commands for doing common algebraic operations on -formulas. Continuing with the formula from the last example, - -@smallexample -@group -1: 18 x^2 + 6 y - 6 x^4 - 2 x^2 y 1: (18 - 2 y) x^2 - 6 x^4 + 6 y - . . - - a x a c x @key{RET} -@end group -@end smallexample - -@noindent -First we ``expand'' using the distributive law, then we ``collect'' -terms involving like powers of @expr{x}. - -Let's find the value of this expression when @expr{x} is 2 and @expr{y} -is one-half. - -@smallexample -@group -1: 17 x^2 - 6 x^4 + 3 1: -25 - . . - - 1:2 s l y @key{RET} 2 s l x @key{RET} -@end group -@end smallexample - -@noindent -The @kbd{s l} command means ``let''; it takes a number from the top of -the stack and temporarily assigns it as the value of the variable -you specify. It then evaluates (as if by the @kbd{=} key) the -next expression on the stack. After this command, the variable goes -back to its original value, if any. - -(An earlier exercise in this tutorial involved storing a value in the -variable @code{x}; if this value is still there, you will have to -unstore it with @kbd{s u x @key{RET}} before the above example will work -properly.) - -@cindex Maximum of a function using Calculus -Let's find the maximum value of our original expression when @expr{y} -is one-half and @expr{x} ranges over all possible values. We can -do this by taking the derivative with respect to @expr{x} and examining -values of @expr{x} for which the derivative is zero. If the second -derivative of the function at that value of @expr{x} is negative, -the function has a local maximum there. - -@smallexample -@group -1: 17 x^2 - 6 x^4 + 3 1: 34 x - 24 x^3 - . . - - U @key{DEL} s 1 a d x @key{RET} s 2 -@end group -@end smallexample - -@noindent -Well, the derivative is clearly zero when @expr{x} is zero. To find -the other root(s), let's divide through by @expr{x} and then solve: - -@smallexample -@group -1: (34 x - 24 x^3) / x 1: 34 x / x - 24 x^3 / x 1: 34 - 24 x^2 - . . . - - ' x @key{RET} / a x a s - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 34 - 24 x^2 = 0 1: x = 1.19023 - . . - - 0 a = s 3 a S x @key{RET} -@end group -@end smallexample - -@noindent -Notice the use of @kbd{a s} to ``simplify'' the formula. When the -default algebraic simplifications don't do enough, you can use -@kbd{a s} to tell Calc to spend more time on the job. - -Now we compute the second derivative and plug in our values of @expr{x}: - -@smallexample -@group -1: 1.19023 2: 1.19023 2: 1.19023 - . 1: 34 x - 24 x^3 1: 34 - 72 x^2 - . . - - a . r 2 a d x @key{RET} s 4 -@end group -@end smallexample - -@noindent -(The @kbd{a .} command extracts just the righthand side of an equation. -Another method would have been to use @kbd{v u} to unpack the equation -@w{@samp{x = 1.19}} to @samp{x} and @samp{1.19}, then use @kbd{M-- M-2 @key{DEL}} -to delete the @samp{x}.) - -@smallexample -@group -2: 34 - 72 x^2 1: -68. 2: 34 - 72 x^2 1: 34 -1: 1.19023 . 1: 0 . - . . - - @key{TAB} s l x @key{RET} U @key{DEL} 0 s l x @key{RET} -@end group -@end smallexample - -@noindent -The first of these second derivatives is negative, so we know the function -has a maximum value at @expr{x = 1.19023}. (The function also has a -local @emph{minimum} at @expr{x = 0}.) - -When we solved for @expr{x}, we got only one value even though -@expr{34 - 24 x^2 = 0} is a quadratic equation that ought to have -two solutions. The reason is that @w{@kbd{a S}} normally returns a -single ``principal'' solution. If it needs to come up with an -arbitrary sign (as occurs in the quadratic formula) it picks @expr{+}. -If it needs an arbitrary integer, it picks zero. We can get a full -solution by pressing @kbd{H} (the Hyperbolic flag) before @kbd{a S}. - -@smallexample -@group -1: 34 - 24 x^2 = 0 1: x = 1.19023 s1 1: x = -1.19023 - . . . - - r 3 H a S x @key{RET} s 5 1 n s l s1 @key{RET} -@end group -@end smallexample - -@noindent -Calc has invented the variable @samp{s1} to represent an unknown sign; -it is supposed to be either @mathit{+1} or @mathit{-1}. Here we have used -the ``let'' command to evaluate the expression when the sign is negative. -If we plugged this into our second derivative we would get the same, -negative, answer, so @expr{x = -1.19023} is also a maximum. - -To find the actual maximum value, we must plug our two values of @expr{x} -into the original formula. - -@smallexample -@group -2: 17 x^2 - 6 x^4 + 3 1: 24.08333 s1^2 - 12.04166 s1^4 + 3 -1: x = 1.19023 s1 . - . - - r 1 r 5 s l @key{RET} -@end group -@end smallexample - -@noindent -(Here we see another way to use @kbd{s l}; if its input is an equation -with a variable on the lefthand side, then @kbd{s l} treats the equation -like an assignment to that variable if you don't give a variable name.) - -It's clear that this will have the same value for either sign of -@code{s1}, but let's work it out anyway, just for the exercise: - -@smallexample -@group -2: [-1, 1] 1: [15.04166, 15.04166] -1: 24.08333 s1^2 ... . - . - - [ 1 n , 1 ] @key{TAB} V M $ @key{RET} -@end group -@end smallexample - -@noindent -Here we have used a vector mapping operation to evaluate the function -at several values of @samp{s1} at once. @kbd{V M $} is like @kbd{V M '} -except that it takes the formula from the top of the stack. The -formula is interpreted as a function to apply across the vector at the -next-to-top stack level. Since a formula on the stack can't contain -@samp{$} signs, Calc assumes the variables in the formula stand for -different arguments. It prompts you for an @dfn{argument list}, giving -the list of all variables in the formula in alphabetical order as the -default list. In this case the default is @samp{(s1)}, which is just -what we want so we simply press @key{RET} at the prompt. - -If there had been several different values, we could have used -@w{@kbd{V R X}} to find the global maximum. - -Calc has a built-in @kbd{a P} command that solves an equation using -@w{@kbd{H a S}} and returns a vector of all the solutions. It simply -automates the job we just did by hand. Applied to our original -cubic polynomial, it would produce the vector of solutions -@expr{[1.19023, -1.19023, 0]}. (There is also an @kbd{a X} command -which finds a local maximum of a function. It uses a numerical search -method rather than examining the derivatives, and thus requires you -to provide some kind of initial guess to show it where to look.) - -(@bullet{}) @strong{Exercise 2.} Given a vector of the roots of a -polynomial (such as the output of an @kbd{a P} command), what -sequence of commands would you use to reconstruct the original -polynomial? (The answer will be unique to within a constant -multiple; choose the solution where the leading coefficient is one.) -@xref{Algebra Answer 2, 2}. (@bullet{}) - -The @kbd{m s} command enables Symbolic mode, in which formulas -like @samp{sqrt(5)} that can't be evaluated exactly are left in -symbolic form rather than giving a floating-point approximate answer. -Fraction mode (@kbd{m f}) is also useful when doing algebra. - -@smallexample -@group -2: 34 x - 24 x^3 2: 34 x - 24 x^3 -1: 34 x - 24 x^3 1: [sqrt(51) / 6, sqrt(51) / -6, 0] - . . - - r 2 @key{RET} m s m f a P x @key{RET} -@end group -@end smallexample - -One more mode that makes reading formulas easier is Big mode. - -@smallexample -@group - 3 -2: 34 x - 24 x - - ____ ____ - V 51 V 51 -1: [-----, -----, 0] - 6 -6 - - . - - d B -@end group -@end smallexample - -Here things like powers, square roots, and quotients and fractions -are displayed in a two-dimensional pictorial form. Calc has other -language modes as well, such as C mode, FORTRAN mode, @TeX{} mode -and La@TeX{} mode. - -@smallexample -@group -2: 34*x - 24*pow(x, 3) 2: 34*x - 24*x**3 -1: @{sqrt(51) / 6, sqrt(51) / -6, 0@} 1: /sqrt(51) / 6, sqrt(51) / -6, 0/ - . . - - d C d F - -@end group -@end smallexample -@noindent -@smallexample -@group -3: 34 x - 24 x^3 -2: [@{\sqrt@{51@} \over 6@}, @{\sqrt@{51@} \over -6@}, 0] -1: @{2 \over 3@} \sqrt@{5@} - . - - d T ' 2 \sqrt@{5@} \over 3 @key{RET} -@end group -@end smallexample - -@noindent -As you can see, language modes affect both entry and display of -formulas. They affect such things as the names used for built-in -functions, the set of arithmetic operators and their precedences, -and notations for vectors and matrices. - -Notice that @samp{sqrt(51)} may cause problems with older -implementations of C and FORTRAN, which would require something more -like @samp{sqrt(51.0)}. It is always wise to check over the formulas -produced by the various language modes to make sure they are fully -correct. - -Type @kbd{m s}, @kbd{m f}, and @kbd{d N} to reset these modes. (You -may prefer to remain in Big mode, but all the examples in the tutorial -are shown in normal mode.) - -@cindex Area under a curve -What is the area under the portion of this curve from @expr{x = 1} to @expr{2}? -This is simply the integral of the function: - -@smallexample -@group -1: 17 x^2 - 6 x^4 + 3 1: 5.6666 x^3 - 1.2 x^5 + 3 x - . . - - r 1 a i x -@end group -@end smallexample - -@noindent -We want to evaluate this at our two values for @expr{x} and subtract. -One way to do it is again with vector mapping and reduction: - -@smallexample -@group -2: [2, 1] 1: [12.93333, 7.46666] 1: 5.46666 -1: 5.6666 x^3 ... . . - - [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R - -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 3.} Find the integral from 1 to @expr{y} -of -@texline @math{x \sin \pi x} -@infoline @w{@expr{x sin(pi x)}} -(where the sine is calculated in radians). Find the values of the -integral for integers @expr{y} from 1 to 5. @xref{Algebra Answer 3, -3}. (@bullet{}) - -Calc's integrator can do many simple integrals symbolically, but many -others are beyond its capabilities. Suppose we wish to find the area -under the curve -@texline @math{\sin x \ln x} -@infoline @expr{sin(x) ln(x)} -over the same range of @expr{x}. If you entered this formula and typed -@kbd{a i x @key{RET}} (don't bother to try this), Calc would work for a -long time but would be unable to find a solution. In fact, there is no -closed-form solution to this integral. Now what do we do? - -@cindex Integration, numerical -@cindex Numerical integration -One approach would be to do the integral numerically. It is not hard -to do this by hand using vector mapping and reduction. It is rather -slow, though, since the sine and logarithm functions take a long time. -We can save some time by reducing the working precision. - -@smallexample -@group -3: 10 1: [1, 1.1, 1.2, ... , 1.8, 1.9] -2: 1 . -1: 0.1 - . - - 10 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x -@end group -@end smallexample - -@noindent -(Note that we have used the extended version of @kbd{v x}; we could -also have used plain @kbd{v x} as follows: @kbd{v x 10 @key{RET} 9 + .1 *}.) - -@smallexample -@group -2: [1, 1.1, ... ] 1: [0., 0.084941, 0.16993, ... ] -1: sin(x) ln(x) . - . - - ' sin(x) ln(x) @key{RET} s 1 m r p 5 @key{RET} V M $ @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 3.4195 0.34195 - . . - - V R + 0.1 * -@end group -@end smallexample - -@noindent -(If you got wildly different results, did you remember to switch -to Radians mode?) - -Here we have divided the curve into ten segments of equal width; -approximating these segments as rectangular boxes (i.e., assuming -the curve is nearly flat at that resolution), we compute the areas -of the boxes (height times width), then sum the areas. (It is -faster to sum first, then multiply by the width, since the width -is the same for every box.) - -The true value of this integral turns out to be about 0.374, so -we're not doing too well. Let's try another approach. - -@smallexample -@group -1: sin(x) ln(x) 1: 0.84147 x - 0.84147 + 0.11957 (x - 1)^2 - ... - . . - - r 1 a t x=1 @key{RET} 4 @key{RET} -@end group -@end smallexample - -@noindent -Here we have computed the Taylor series expansion of the function -about the point @expr{x=1}. We can now integrate this polynomial -approximation, since polynomials are easy to integrate. - -@smallexample -@group -1: 0.42074 x^2 + ... 1: [-0.0446, -0.42073] 1: 0.3761 - . . . - - a i x @key{RET} [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R - -@end group -@end smallexample - -@noindent -Better! By increasing the precision and/or asking for more terms -in the Taylor series, we can get a result as accurate as we like. -(Taylor series converge better away from singularities in the -function such as the one at @code{ln(0)}, so it would also help to -expand the series about the points @expr{x=2} or @expr{x=1.5} instead -of @expr{x=1}.) - -@cindex Simpson's rule -@cindex Integration by Simpson's rule -(@bullet{}) @strong{Exercise 4.} Our first method approximated the -curve by stairsteps of width 0.1; the total area was then the sum -of the areas of the rectangles under these stairsteps. Our second -method approximated the function by a polynomial, which turned out -to be a better approximation than stairsteps. A third method is -@dfn{Simpson's rule}, which is like the stairstep method except -that the steps are not required to be flat. Simpson's rule boils -down to the formula, - -@ifnottex -@example -(h/3) * (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + ... - + 2 f(a+(n-2)*h) + 4 f(a+(n-1)*h) + f(a+n*h)) -@end example -@end ifnottex -@tex -\beforedisplay -$$ \displaylines{ - \qquad {h \over 3} (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + \cdots - \hfill \cr \hfill {} + 2 f(a+(n-2)h) + 4 f(a+(n-1)h) + f(a+n h)) \qquad -} $$ -\afterdisplay -@end tex - -@noindent -where @expr{n} (which must be even) is the number of slices and @expr{h} -is the width of each slice. These are 10 and 0.1 in our example. -For reference, here is the corresponding formula for the stairstep -method: - -@ifnottex -@example -h * (f(a) + f(a+h) + f(a+2h) + f(a+3h) + ... - + f(a+(n-2)*h) + f(a+(n-1)*h)) -@end example -@end ifnottex -@tex -\beforedisplay -$$ h (f(a) + f(a+h) + f(a+2h) + f(a+3h) + \cdots - + f(a+(n-2)h) + f(a+(n-1)h)) $$ -\afterdisplay -@end tex - -Compute the integral from 1 to 2 of -@texline @math{\sin x \ln x} -@infoline @expr{sin(x) ln(x)} -using Simpson's rule with 10 slices. -@xref{Algebra Answer 4, 4}. (@bullet{}) - -Calc has a built-in @kbd{a I} command for doing numerical integration. -It uses @dfn{Romberg's method}, which is a more sophisticated cousin -of Simpson's rule. In particular, it knows how to keep refining the -result until the current precision is satisfied. - -@c [fix-ref Selecting Sub-Formulas] -Aside from the commands we've seen so far, Calc also provides a -large set of commands for operating on parts of formulas. You -indicate the desired sub-formula by placing the cursor on any part -of the formula before giving a @dfn{selection} command. Selections won't -be covered in the tutorial; @pxref{Selecting Subformulas}, for -details and examples. - -@c hard exercise: simplify (2^(n r) - 2^(r*(n - 1))) / (2^r - 1) 2^(n - 1) -@c to 2^((n-1)*(r-1)). - -@node Rewrites Tutorial, , Basic Algebra Tutorial, Algebra Tutorial -@subsection Rewrite Rules - -@noindent -No matter how many built-in commands Calc provided for doing algebra, -there would always be something you wanted to do that Calc didn't have -in its repertoire. So Calc also provides a @dfn{rewrite rule} system -that you can use to define your own algebraic manipulations. - -Suppose we want to simplify this trigonometric formula: - -@smallexample -@group -1: 2 / cos(x)^2 - 2 tan(x)^2 - . - - ' 2/cos(x)^2 - 2tan(x)^2 @key{RET} s 1 -@end group -@end smallexample - -@noindent -If we were simplifying this by hand, we'd probably replace the -@samp{tan} with a @samp{sin/cos} first, then combine over a common -denominator. The @kbd{I a s} command will do the former and the @kbd{a n} -algebra command will do the latter, but we'll do both with rewrite -rules just for practice. - -Rewrite rules are written with the @samp{:=} symbol. - -@smallexample -@group -1: 2 / cos(x)^2 - 2 sin(x)^2 / cos(x)^2 - . - - a r tan(a) := sin(a)/cos(a) @key{RET} -@end group -@end smallexample - -@noindent -(The ``assignment operator'' @samp{:=} has several uses in Calc. All -by itself the formula @samp{tan(a) := sin(a)/cos(a)} doesn't do anything, -but when it is given to the @kbd{a r} command, that command interprets -it as a rewrite rule.) - -The lefthand side, @samp{tan(a)}, is called the @dfn{pattern} of the -rewrite rule. Calc searches the formula on the stack for parts that -match the pattern. Variables in a rewrite pattern are called -@dfn{meta-variables}, and when matching the pattern each meta-variable -can match any sub-formula. Here, the meta-variable @samp{a} matched -the actual variable @samp{x}. - -When the pattern part of a rewrite rule matches a part of the formula, -that part is replaced by the righthand side with all the meta-variables -substituted with the things they matched. So the result is -@samp{sin(x) / cos(x)}. Calc's normal algebraic simplifications then -mix this in with the rest of the original formula. - -To merge over a common denominator, we can use another simple rule: - -@smallexample -@group -1: (2 - 2 sin(x)^2) / cos(x)^2 - . - - a r a/x + b/x := (a+b)/x @key{RET} -@end group -@end smallexample - -This rule points out several interesting features of rewrite patterns. -First, if a meta-variable appears several times in a pattern, it must -match the same thing everywhere. This rule detects common denominators -because the same meta-variable @samp{x} is used in both of the -denominators. - -Second, meta-variable names are independent from variables in the -target formula. Notice that the meta-variable @samp{x} here matches -the subformula @samp{cos(x)^2}; Calc never confuses the two meanings of -@samp{x}. - -And third, rewrite patterns know a little bit about the algebraic -properties of formulas. The pattern called for a sum of two quotients; -Calc was able to match a difference of two quotients by matching -@samp{a = 2}, @samp{b = -2 sin(x)^2}, and @samp{x = cos(x)^2}. - -@c [fix-ref Algebraic Properties of Rewrite Rules] -We could just as easily have written @samp{a/x - b/x := (a-b)/x} for -the rule. It would have worked just the same in all cases. (If we -really wanted the rule to apply only to @samp{+} or only to @samp{-}, -we could have used the @code{plain} symbol. @xref{Algebraic Properties -of Rewrite Rules}, for some examples of this.) - -One more rewrite will complete the job. We want to use the identity -@samp{sin(x)^2 + cos(x)^2 = 1}, but of course we must first rearrange -the identity in a way that matches our formula. The obvious rule -would be @samp{@w{2 - 2 sin(x)^2} := 2 cos(x)^2}, but a little thought shows -that the rule @samp{sin(x)^2 := 1 - cos(x)^2} will also work. The -latter rule has a more general pattern so it will work in many other -situations, too. - -@smallexample -@group -1: (2 + 2 cos(x)^2 - 2) / cos(x)^2 1: 2 - . . - - a r sin(x)^2 := 1 - cos(x)^2 @key{RET} a s -@end group -@end smallexample - -You may ask, what's the point of using the most general rule if you -have to type it in every time anyway? The answer is that Calc allows -you to store a rewrite rule in a variable, then give the variable -name in the @kbd{a r} command. In fact, this is the preferred way to -use rewrites. For one, if you need a rule once you'll most likely -need it again later. Also, if the rule doesn't work quite right you -can simply Undo, edit the variable, and run the rule again without -having to retype it. - -@smallexample -@group -' tan(x) := sin(x)/cos(x) @key{RET} s t tsc @key{RET} -' a/x + b/x := (a+b)/x @key{RET} s t merge @key{RET} -' sin(x)^2 := 1 - cos(x)^2 @key{RET} s t sinsqr @key{RET} - -1: 2 / cos(x)^2 - 2 tan(x)^2 1: 2 - . . - - r 1 a r tsc @key{RET} a r merge @key{RET} a r sinsqr @key{RET} a s -@end group -@end smallexample - -To edit a variable, type @kbd{s e} and the variable name, use regular -Emacs editing commands as necessary, then type @kbd{C-c C-c} to store -the edited value back into the variable. -You can also use @w{@kbd{s e}} to create a new variable if you wish. - -Notice that the first time you use each rule, Calc puts up a ``compiling'' -message briefly. The pattern matcher converts rules into a special -optimized pattern-matching language rather than using them directly. -This allows @kbd{a r} to apply even rather complicated rules very -efficiently. If the rule is stored in a variable, Calc compiles it -only once and stores the compiled form along with the variable. That's -another good reason to store your rules in variables rather than -entering them on the fly. - -(@bullet{}) @strong{Exercise 1.} Type @kbd{m s} to get Symbolic -mode, then enter the formula @samp{@w{(2 + sqrt(2))} / @w{(1 + sqrt(2))}}. -Using a rewrite rule, simplify this formula by multiplying the top and -bottom by the conjugate @w{@samp{1 - sqrt(2)}}. The result will have -to be expanded by the distributive law; do this with another -rewrite. @xref{Rewrites Answer 1, 1}. (@bullet{}) - -The @kbd{a r} command can also accept a vector of rewrite rules, or -a variable containing a vector of rules. - -@smallexample -@group -1: [tsc, merge, sinsqr] 1: [tan(x) := sin(x) / cos(x), ... ] - . . - - ' [tsc,merge,sinsqr] @key{RET} = - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 1 / cos(x) - sin(x) tan(x) 1: cos(x) - . . - - s t trig @key{RET} r 1 a r trig @key{RET} a s -@end group -@end smallexample - -@c [fix-ref Nested Formulas with Rewrite Rules] -Calc tries all the rules you give against all parts of the formula, -repeating until no further change is possible. (The exact order in -which things are tried is rather complex, but for simple rules like -the ones we've used here the order doesn't really matter. -@xref{Nested Formulas with Rewrite Rules}.) - -Calc actually repeats only up to 100 times, just in case your rule set -has gotten into an infinite loop. You can give a numeric prefix argument -to @kbd{a r} to specify any limit. In particular, @kbd{M-1 a r} does -only one rewrite at a time. - -@smallexample -@group -1: 1 / cos(x) - sin(x)^2 / cos(x) 1: (1 - sin(x)^2) / cos(x) - . . - - r 1 M-1 a r trig @key{RET} M-1 a r trig @key{RET} -@end group -@end smallexample - -You can type @kbd{M-0 a r} if you want no limit at all on the number -of rewrites that occur. - -Rewrite rules can also be @dfn{conditional}. Simply follow the rule -with a @samp{::} symbol and the desired condition. For example, - -@smallexample -@group -1: exp(2 pi i) + exp(3 pi i) + exp(4 pi i) - . - - ' exp(2 pi i) + exp(3 pi i) + exp(4 pi i) @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 1 + exp(3 pi i) + 1 - . - - a r exp(k pi i) := 1 :: k % 2 = 0 @key{RET} -@end group -@end smallexample - -@noindent -(Recall, @samp{k % 2} is the remainder from dividing @samp{k} by 2, -which will be zero only when @samp{k} is an even integer.) - -An interesting point is that the variables @samp{pi} and @samp{i} -were matched literally rather than acting as meta-variables. -This is because they are special-constant variables. The special -constants @samp{e}, @samp{phi}, and so on also match literally. -A common error with rewrite -rules is to write, say, @samp{f(a,b,c,d,e) := g(a+b+c+d+e)}, expecting -to match any @samp{f} with five arguments but in fact matching -only when the fifth argument is literally @samp{e}! - -@cindex Fibonacci numbers -@ignore -@starindex -@end ignore -@tindex fib -Rewrite rules provide an interesting way to define your own functions. -Suppose we want to define @samp{fib(n)} to produce the @var{n}th -Fibonacci number. The first two Fibonacci numbers are each 1; -later numbers are formed by summing the two preceding numbers in -the sequence. This is easy to express in a set of three rules: - -@smallexample -@group -' [fib(1) := 1, fib(2) := 1, fib(n) := fib(n-1) + fib(n-2)] @key{RET} s t fib - -1: fib(7) 1: 13 - . . - - ' fib(7) @key{RET} a r fib @key{RET} -@end group -@end smallexample - -One thing that is guaranteed about the order that rewrites are tried -is that, for any given subformula, earlier rules in the rule set will -be tried for that subformula before later ones. So even though the -first and third rules both match @samp{fib(1)}, we know the first will -be used preferentially. - -This rule set has one dangerous bug: Suppose we apply it to the -formula @samp{fib(x)}? (Don't actually try this.) The third rule -will match @samp{fib(x)} and replace it with @w{@samp{fib(x-1) + fib(x-2)}}. -Each of these will then be replaced to get @samp{fib(x-2) + 2 fib(x-3) + -fib(x-4)}, and so on, expanding forever. What we really want is to apply -the third rule only when @samp{n} is an integer greater than two. Type -@w{@kbd{s e fib @key{RET}}}, then edit the third rule to: - -@smallexample -fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 -@end smallexample - -@noindent -Now: - -@smallexample -@group -1: fib(6) + fib(x) + fib(0) 1: 8 + fib(x) + fib(0) - . . - - ' fib(6)+fib(x)+fib(0) @key{RET} a r fib @key{RET} -@end group -@end smallexample - -@noindent -We've created a new function, @code{fib}, and a new command, -@w{@kbd{a r fib @key{RET}}}, which means ``evaluate all @code{fib} calls in -this formula.'' To make things easier still, we can tell Calc to -apply these rules automatically by storing them in the special -variable @code{EvalRules}. - -@smallexample -@group -1: [fib(1) := ...] . 1: [8, 13] - . . - - s r fib @key{RET} s t EvalRules @key{RET} ' [fib(6), fib(7)] @key{RET} -@end group -@end smallexample - -It turns out that this rule set has the problem that it does far -more work than it needs to when @samp{n} is large. Consider the -first few steps of the computation of @samp{fib(6)}: - -@smallexample -@group -fib(6) = -fib(5) + fib(4) = -fib(4) + fib(3) + fib(3) + fib(2) = -fib(3) + fib(2) + fib(2) + fib(1) + fib(2) + fib(1) + 1 = ... -@end group -@end smallexample - -@noindent -Note that @samp{fib(3)} appears three times here. Unless Calc's -algebraic simplifier notices the multiple @samp{fib(3)}s and combines -them (and, as it happens, it doesn't), this rule set does lots of -needless recomputation. To cure the problem, type @code{s e EvalRules} -to edit the rules (or just @kbd{s E}, a shorthand command for editing -@code{EvalRules}) and add another condition: - -@smallexample -fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 :: remember -@end smallexample - -@noindent -If a @samp{:: remember} condition appears anywhere in a rule, then if -that rule succeeds Calc will add another rule that describes that match -to the front of the rule set. (Remembering works in any rule set, but -for technical reasons it is most effective in @code{EvalRules}.) For -example, if the rule rewrites @samp{fib(7)} to something that evaluates -to 13, then the rule @samp{fib(7) := 13} will be added to the rule set. - -Type @kbd{' fib(8) @key{RET}} to compute the eighth Fibonacci number, then -type @kbd{s E} again to see what has happened to the rule set. - -With the @code{remember} feature, our rule set can now compute -@samp{fib(@var{n})} in just @var{n} steps. In the process it builds -up a table of all Fibonacci numbers up to @var{n}. After we have -computed the result for a particular @var{n}, we can get it back -(and the results for all smaller @var{n}) later in just one step. - -All Calc operations will run somewhat slower whenever @code{EvalRules} -contains any rules. You should type @kbd{s u EvalRules @key{RET}} now to -un-store the variable. - -(@bullet{}) @strong{Exercise 2.} Sometimes it is possible to reformulate -a problem to reduce the amount of recursion necessary to solve it. -Create a rule that, in about @var{n} simple steps and without recourse -to the @code{remember} option, replaces @samp{fib(@var{n}, 1, 1)} with -@samp{fib(1, @var{x}, @var{y})} where @var{x} and @var{y} are the -@var{n}th and @var{n+1}st Fibonacci numbers, respectively. This rule is -rather clunky to use, so add a couple more rules to make the ``user -interface'' the same as for our first version: enter @samp{fib(@var{n})}, -get back a plain number. @xref{Rewrites Answer 2, 2}. (@bullet{}) - -There are many more things that rewrites can do. For example, there -are @samp{&&&} and @samp{|||} pattern operators that create ``and'' -and ``or'' combinations of rules. As one really simple example, we -could combine our first two Fibonacci rules thusly: - -@example -[fib(1 ||| 2) := 1, fib(n) := ... ] -@end example - -@noindent -That means ``@code{fib} of something matching either 1 or 2 rewrites -to 1.'' - -You can also make meta-variables optional by enclosing them in @code{opt}. -For example, the pattern @samp{a + b x} matches @samp{2 + 3 x} but not -@samp{2 + x} or @samp{3 x} or @samp{x}. The pattern @samp{opt(a) + opt(b) x} -matches all of these forms, filling in a default of zero for @samp{a} -and one for @samp{b}. - -(@bullet{}) @strong{Exercise 3.} Your friend Joe had @samp{2 + 3 x} -on the stack and tried to use the rule -@samp{opt(a) + opt(b) x := f(a, b, x)}. What happened? -@xref{Rewrites Answer 3, 3}. (@bullet{}) - -(@bullet{}) @strong{Exercise 4.} Starting with a positive integer @expr{a}, -divide @expr{a} by two if it is even, otherwise compute @expr{3 a + 1}. -Now repeat this step over and over. A famous unproved conjecture -is that for any starting @expr{a}, the sequence always eventually -reaches 1. Given the formula @samp{seq(@var{a}, 0)}, write a set of -rules that convert this into @samp{seq(1, @var{n})} where @var{n} -is the number of steps it took the sequence to reach the value 1. -Now enhance the rules to accept @samp{seq(@var{a})} as a starting -configuration, and to stop with just the number @var{n} by itself. -Now make the result be a vector of values in the sequence, from @var{a} -to 1. (The formula @samp{@var{x}|@var{y}} appends the vectors @var{x} -and @var{y}.) For example, rewriting @samp{seq(6)} should yield the -vector @expr{[6, 3, 10, 5, 16, 8, 4, 2, 1]}. -@xref{Rewrites Answer 4, 4}. (@bullet{}) - -(@bullet{}) @strong{Exercise 5.} Define, using rewrite rules, a function -@samp{nterms(@var{x})} that returns the number of terms in the sum -@var{x}, or 1 if @var{x} is not a sum. (A @dfn{sum} for our purposes -is one or more non-sum terms separated by @samp{+} or @samp{-} signs, -so that @expr{2 - 3 (x + y) + x y} is a sum of three terms.) -@xref{Rewrites Answer 5, 5}. (@bullet{}) - -(@bullet{}) @strong{Exercise 6.} A Taylor series for a function is an -infinite series that exactly equals the value of that function at -values of @expr{x} near zero. - -@ifnottex -@example -cos(x) = 1 - x^2 / 2! + x^4 / 4! - x^6 / 6! + ... -@end example -@end ifnottex -@tex -\beforedisplay -$$ \cos x = 1 - {x^2 \over 2!} + {x^4 \over 4!} - {x^6 \over 6!} + \cdots $$ -\afterdisplay -@end tex - -The @kbd{a t} command produces a @dfn{truncated Taylor series} which -is obtained by dropping all the terms higher than, say, @expr{x^2}. -Calc represents the truncated Taylor series as a polynomial in @expr{x}. -Mathematicians often write a truncated series using a ``big-O'' notation -that records what was the lowest term that was truncated. - -@ifnottex -@example -cos(x) = 1 - x^2 / 2! + O(x^3) -@end example -@end ifnottex -@tex -\beforedisplay -$$ \cos x = 1 - {x^2 \over 2!} + O(x^3) $$ -\afterdisplay -@end tex - -@noindent -The meaning of @expr{O(x^3)} is ``a quantity which is negligibly small -if @expr{x^3} is considered negligibly small as @expr{x} goes to zero.'' - -The exercise is to create rewrite rules that simplify sums and products of -power series represented as @samp{@var{polynomial} + O(@var{var}^@var{n})}. -For example, given @samp{1 - x^2 / 2 + O(x^3)} and @samp{x - x^3 / 6 + O(x^4)} -on the stack, we want to be able to type @kbd{*} and get the result -@samp{x - 2:3 x^3 + O(x^4)}. Don't worry if the terms of the sum are -rearranged or if @kbd{a s} needs to be typed after rewriting. (This one -is rather tricky; the solution at the end of this chapter uses 6 rewrite -rules. Hint: The @samp{constant(x)} condition tests whether @samp{x} is -a number.) @xref{Rewrites Answer 6, 6}. (@bullet{}) - -Just for kicks, try adding the rule @code{2+3 := 6} to @code{EvalRules}. -What happens? (Be sure to remove this rule afterward, or you might get -a nasty surprise when you use Calc to balance your checkbook!) - -@xref{Rewrite Rules}, for the whole story on rewrite rules. - -@node Programming Tutorial, Answers to Exercises, Algebra Tutorial, Tutorial -@section Programming Tutorial - -@noindent -The Calculator is written entirely in Emacs Lisp, a highly extensible -language. If you know Lisp, you can program the Calculator to do -anything you like. Rewrite rules also work as a powerful programming -system. But Lisp and rewrite rules take a while to master, and often -all you want to do is define a new function or repeat a command a few -times. Calc has features that allow you to do these things easily. - -One very limited form of programming is defining your own functions. -Calc's @kbd{Z F} command allows you to define a function name and -key sequence to correspond to any formula. Programming commands use -the shift-@kbd{Z} prefix; the user commands they create use the lower -case @kbd{z} prefix. - -@smallexample -@group -1: 1 + x + x^2 / 2 + x^3 / 6 1: 1 + x + x^2 / 2 + x^3 / 6 - . . - - ' 1 + x + x^2/2! + x^3/3! @key{RET} Z F e myexp @key{RET} @key{RET} @key{RET} y -@end group -@end smallexample - -This polynomial is a Taylor series approximation to @samp{exp(x)}. -The @kbd{Z F} command asks a number of questions. The above answers -say that the key sequence for our function should be @kbd{z e}; the -@kbd{M-x} equivalent should be @code{calc-myexp}; the name of the -function in algebraic formulas should also be @code{myexp}; the -default argument list @samp{(x)} is acceptable; and finally @kbd{y} -answers the question ``leave it in symbolic form for non-constant -arguments?'' - -@smallexample -@group -1: 1.3495 2: 1.3495 3: 1.3495 - . 1: 1.34986 2: 1.34986 - . 1: myexp(a + 1) - . - - .3 z e .3 E ' a+1 @key{RET} z e -@end group -@end smallexample - -@noindent -First we call our new @code{exp} approximation with 0.3 as an -argument, and compare it with the true @code{exp} function. Then -we note that, as requested, if we try to give @kbd{z e} an -argument that isn't a plain number, it leaves the @code{myexp} -function call in symbolic form. If we had answered @kbd{n} to the -final question, @samp{myexp(a + 1)} would have evaluated by plugging -in @samp{a + 1} for @samp{x} in the defining formula. - -@cindex Sine integral Si(x) -@ignore -@starindex -@end ignore -@tindex Si -(@bullet{}) @strong{Exercise 1.} The ``sine integral'' function -@texline @math{{\rm Si}(x)} -@infoline @expr{Si(x)} -is defined as the integral of @samp{sin(t)/t} for -@expr{t = 0} to @expr{x} in radians. (It was invented because this -integral has no solution in terms of basic functions; if you give it -to Calc's @kbd{a i} command, it will ponder it for a long time and then -give up.) We can use the numerical integration command, however, -which in algebraic notation is written like @samp{ninteg(f(t), t, 0, x)} -with any integrand @samp{f(t)}. Define a @kbd{z s} command and -@code{Si} function that implement this. You will need to edit the -default argument list a bit. As a test, @samp{Si(1)} should return -0.946083. (If you don't get this answer, you might want to check that -Calc is in Radians mode. Also, @code{ninteg} will run a lot faster if -you reduce the precision to, say, six digits beforehand.) -@xref{Programming Answer 1, 1}. (@bullet{}) - -The simplest way to do real ``programming'' of Emacs is to define a -@dfn{keyboard macro}. A keyboard macro is simply a sequence of -keystrokes which Emacs has stored away and can play back on demand. -For example, if you find yourself typing @kbd{H a S x @key{RET}} often, -you may wish to program a keyboard macro to type this for you. - -@smallexample -@group -1: y = sqrt(x) 1: x = y^2 - . . - - ' y=sqrt(x) @key{RET} C-x ( H a S x @key{RET} C-x ) - -1: y = cos(x) 1: x = s1 arccos(y) + 2 pi n1 - . . - - ' y=cos(x) @key{RET} X -@end group -@end smallexample - -@noindent -When you type @kbd{C-x (}, Emacs begins recording. But it is also -still ready to execute your keystrokes, so you're really ``training'' -Emacs by walking it through the procedure once. When you type -@w{@kbd{C-x )}}, the macro is recorded. You can now type @kbd{X} to -re-execute the same keystrokes. - -You can give a name to your macro by typing @kbd{Z K}. - -@smallexample -@group -1: . 1: y = x^4 1: x = s2 sqrt(s1 sqrt(y)) - . . - - Z K x @key{RET} ' y=x^4 @key{RET} z x -@end group -@end smallexample - -@noindent -Notice that we use shift-@kbd{Z} to define the command, and lower-case -@kbd{z} to call it up. - -Keyboard macros can call other macros. - -@smallexample -@group -1: abs(x) 1: x = s1 y 1: 2 / x 1: x = 2 / y - . . . . - - ' abs(x) @key{RET} C-x ( ' y @key{RET} a = z x C-x ) ' 2/x @key{RET} X -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 2.} Define a keyboard macro to negate -the item in level 3 of the stack, without disturbing the rest of -the stack. @xref{Programming Answer 2, 2}. (@bullet{}) - -(@bullet{}) @strong{Exercise 3.} Define keyboard macros to compute -the following functions: - -@enumerate -@item -Compute -@texline @math{\displaystyle{\sin x \over x}}, -@infoline @expr{sin(x) / x}, -where @expr{x} is the number on the top of the stack. - -@item -Compute the base-@expr{b} logarithm, just like the @kbd{B} key except -the arguments are taken in the opposite order. - -@item -Produce a vector of integers from 1 to the integer on the top of -the stack. -@end enumerate -@noindent -@xref{Programming Answer 3, 3}. (@bullet{}) - -(@bullet{}) @strong{Exercise 4.} Define a keyboard macro to compute -the average (mean) value of a list of numbers. -@xref{Programming Answer 4, 4}. (@bullet{}) - -In many programs, some of the steps must execute several times. -Calc has @dfn{looping} commands that allow this. Loops are useful -inside keyboard macros, but actually work at any time. - -@smallexample -@group -1: x^6 2: x^6 1: 360 x^2 - . 1: 4 . - . - - ' x^6 @key{RET} 4 Z < a d x @key{RET} Z > -@end group -@end smallexample - -@noindent -Here we have computed the fourth derivative of @expr{x^6} by -enclosing a derivative command in a ``repeat loop'' structure. -This structure pops a repeat count from the stack, then -executes the body of the loop that many times. - -If you make a mistake while entering the body of the loop, -type @w{@kbd{Z C-g}} to cancel the loop command. - -@cindex Fibonacci numbers -Here's another example: - -@smallexample -@group -3: 1 2: 10946 -2: 1 1: 17711 -1: 20 . - . - -1 @key{RET} @key{RET} 20 Z < @key{TAB} C-j + Z > -@end group -@end smallexample - -@noindent -The numbers in levels 2 and 1 should be the 21st and 22nd Fibonacci -numbers, respectively. (To see what's going on, try a few repetitions -of the loop body by hand; @kbd{C-j}, also on the Line-Feed or @key{LFD} -key if you have one, makes a copy of the number in level 2.) - -@cindex Golden ratio -@cindex Phi, golden ratio -A fascinating property of the Fibonacci numbers is that the @expr{n}th -Fibonacci number can be found directly by computing -@texline @math{\phi^n / \sqrt{5}} -@infoline @expr{phi^n / sqrt(5)} -and then rounding to the nearest integer, where -@texline @math{\phi} (``phi''), -@infoline @expr{phi}, -the ``golden ratio,'' is -@texline @math{(1 + \sqrt{5}) / 2}. -@infoline @expr{(1 + sqrt(5)) / 2}. -(For convenience, this constant is available from the @code{phi} -variable, or the @kbd{I H P} command.) - -@smallexample -@group -1: 1.61803 1: 24476.0000409 1: 10945.9999817 1: 10946 - . . . . - - I H P 21 ^ 5 Q / R -@end group -@end smallexample - -@cindex Continued fractions -(@bullet{}) @strong{Exercise 5.} The @dfn{continued fraction} -representation of -@texline @math{\phi} -@infoline @expr{phi} -is -@texline @math{1 + 1/(1 + 1/(1 + 1/( \ldots )))}. -@infoline @expr{1 + 1/(1 + 1/(1 + 1/( ...@: )))}. -We can compute an approximate value by carrying this however far -and then replacing the innermost -@texline @math{1/( \ldots )} -@infoline @expr{1/( ...@: )} -by 1. Approximate -@texline @math{\phi} -@infoline @expr{phi} -using a twenty-term continued fraction. -@xref{Programming Answer 5, 5}. (@bullet{}) - -(@bullet{}) @strong{Exercise 6.} Linear recurrences like the one for -Fibonacci numbers can be expressed in terms of matrices. Given a -vector @w{@expr{[a, b]}} determine a matrix which, when multiplied by this -vector, produces the vector @expr{[b, c]}, where @expr{a}, @expr{b} and -@expr{c} are three successive Fibonacci numbers. Now write a program -that, given an integer @expr{n}, computes the @expr{n}th Fibonacci number -using matrix arithmetic. @xref{Programming Answer 6, 6}. (@bullet{}) - -@cindex Harmonic numbers -A more sophisticated kind of loop is the @dfn{for} loop. Suppose -we wish to compute the 20th ``harmonic'' number, which is equal to -the sum of the reciprocals of the integers from 1 to 20. - -@smallexample -@group -3: 0 1: 3.597739 -2: 1 . -1: 20 - . - -0 @key{RET} 1 @key{RET} 20 Z ( & + 1 Z ) -@end group -@end smallexample - -@noindent -The ``for'' loop pops two numbers, the lower and upper limits, then -repeats the body of the loop as an internal counter increases from -the lower limit to the upper one. Just before executing the loop -body, it pushes the current loop counter. When the loop body -finishes, it pops the ``step,'' i.e., the amount by which to -increment the loop counter. As you can see, our loop always -uses a step of one. - -This harmonic number function uses the stack to hold the running -total as well as for the various loop housekeeping functions. If -you find this disorienting, you can sum in a variable instead: - -@smallexample -@group -1: 0 2: 1 . 1: 3.597739 - . 1: 20 . - . - - 0 t 7 1 @key{RET} 20 Z ( & s + 7 1 Z ) r 7 -@end group -@end smallexample - -@noindent -The @kbd{s +} command adds the top-of-stack into the value in a -variable (and removes that value from the stack). - -It's worth noting that many jobs that call for a ``for'' loop can -also be done more easily by Calc's high-level operations. Two -other ways to compute harmonic numbers are to use vector mapping -and reduction (@kbd{v x 20}, then @w{@kbd{V M &}}, then @kbd{V R +}), -or to use the summation command @kbd{a +}. Both of these are -probably easier than using loops. However, there are some -situations where loops really are the way to go: - -(@bullet{}) @strong{Exercise 7.} Use a ``for'' loop to find the first -harmonic number which is greater than 4.0. -@xref{Programming Answer 7, 7}. (@bullet{}) - -Of course, if we're going to be using variables in our programs, -we have to worry about the programs clobbering values that the -caller was keeping in those same variables. This is easy to -fix, though: - -@smallexample -@group - . 1: 0.6667 1: 0.6667 3: 0.6667 - . . 2: 3.597739 - 1: 0.6667 - . - - Z ` p 4 @key{RET} 2 @key{RET} 3 / s 7 s s a @key{RET} Z ' r 7 s r a @key{RET} -@end group -@end smallexample - -@noindent -When we type @kbd{Z `} (that's a back-quote character), Calc saves -its mode settings and the contents of the ten ``quick variables'' -for later reference. When we type @kbd{Z '} (that's an apostrophe -now), Calc restores those saved values. Thus the @kbd{p 4} and -@kbd{s 7} commands have no effect outside this sequence. Wrapping -this around the body of a keyboard macro ensures that it doesn't -interfere with what the user of the macro was doing. Notice that -the contents of the stack, and the values of named variables, -survive past the @kbd{Z '} command. - -@cindex Bernoulli numbers, approximate -The @dfn{Bernoulli numbers} are a sequence with the interesting -property that all of the odd Bernoulli numbers are zero, and the -even ones, while difficult to compute, can be roughly approximated -by the formula -@texline @math{\displaystyle{2 n! \over (2 \pi)^n}}. -@infoline @expr{2 n!@: / (2 pi)^n}. -Let's write a keyboard macro to compute (approximate) Bernoulli numbers. -(Calc has a command, @kbd{k b}, to compute exact Bernoulli numbers, but -this command is very slow for large @expr{n} since the higher Bernoulli -numbers are very large fractions.) - -@smallexample -@group -1: 10 1: 0.0756823 - . . - - 10 C-x ( @key{RET} 2 % Z [ @key{DEL} 0 Z : ' 2 $! / (2 pi)^$ @key{RET} = Z ] C-x ) -@end group -@end smallexample - -@noindent -You can read @kbd{Z [} as ``then,'' @kbd{Z :} as ``else,'' and -@kbd{Z ]} as ``end-if.'' There is no need for an explicit ``if'' -command. For the purposes of @w{@kbd{Z [}}, the condition is ``true'' -if the value it pops from the stack is a nonzero number, or ``false'' -if it pops zero or something that is not a number (like a formula). -Here we take our integer argument modulo 2; this will be nonzero -if we're asking for an odd Bernoulli number. - -The actual tenth Bernoulli number is @expr{5/66}. - -@smallexample -@group -3: 0.0756823 1: 0 1: 0.25305 1: 0 1: 1.16659 -2: 5:66 . . . . -1: 0.0757575 - . - -10 k b @key{RET} c f M-0 @key{DEL} 11 X @key{DEL} 12 X @key{DEL} 13 X @key{DEL} 14 X -@end group -@end smallexample - -Just to exercise loops a bit more, let's compute a table of even -Bernoulli numbers. - -@smallexample -@group -3: [] 1: [0.10132, 0.03079, 0.02340, 0.033197, ...] -2: 2 . -1: 30 - . - - [ ] 2 @key{RET} 30 Z ( X | 2 Z ) -@end group -@end smallexample - -@noindent -The vertical-bar @kbd{|} is the vector-concatenation command. When -we execute it, the list we are building will be in stack level 2 -(initially this is an empty list), and the next Bernoulli number -will be in level 1. The effect is to append the Bernoulli number -onto the end of the list. (To create a table of exact fractional -Bernoulli numbers, just replace @kbd{X} with @kbd{k b} in the above -sequence of keystrokes.) - -With loops and conditionals, you can program essentially anything -in Calc. One other command that makes looping easier is @kbd{Z /}, -which takes a condition from the stack and breaks out of the enclosing -loop if the condition is true (non-zero). You can use this to make -``while'' and ``until'' style loops. - -If you make a mistake when entering a keyboard macro, you can edit -it using @kbd{Z E}. First, you must attach it to a key with @kbd{Z K}. -One technique is to enter a throwaway dummy definition for the macro, -then enter the real one in the edit command. - -@smallexample -@group -1: 3 1: 3 Calc Macro Edit Mode. - . . Original keys: 1 2 + - - 1 ;; calc digits - RET ;; calc-enter - 2 ;; calc digits - + ;; calc-plus - -C-x ( 1 @key{RET} 2 + C-x ) Z K h @key{RET} Z E h -@end group -@end smallexample - -@noindent -A keyboard macro is stored as a pure keystroke sequence. The -@file{edmacro} package (invoked by @kbd{Z E}) scans along the -macro and tries to decode it back into human-readable steps. -Descriptions of the keystrokes are given as comments, which begin with -@samp{;;}, and which are ignored when the edited macro is saved. -Spaces and line breaks are also ignored when the edited macro is saved. -To enter a space into the macro, type @code{SPC}. All the special -characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, @code{DEL}, -and @code{NUL} must be written in all uppercase, as must the prefixes -@code{C-} and @code{M-}. - -Let's edit in a new definition, for computing harmonic numbers. -First, erase the four lines of the old definition. Then, type -in the new definition (or use Emacs @kbd{M-w} and @kbd{C-y} commands -to copy it from this page of the Info file; you can of course skip -typing the comments, which begin with @samp{;;}). - -@smallexample -Z` ;; calc-kbd-push (Save local values) -0 ;; calc digits (Push a zero onto the stack) -st ;; calc-store-into (Store it in the following variable) -1 ;; calc quick variable (Quick variable q1) -1 ;; calc digits (Initial value for the loop) -TAB ;; calc-roll-down (Swap initial and final) -Z( ;; calc-kbd-for (Begin the "for" loop) -& ;; calc-inv (Take the reciprocal) -s+ ;; calc-store-plus (Add to the following variable) -1 ;; calc quick variable (Quick variable q1) -1 ;; calc digits (The loop step is 1) -Z) ;; calc-kbd-end-for (End the "for" loop) -sr ;; calc-recall (Recall the final accumulated value) -1 ;; calc quick variable (Quick variable q1) -Z' ;; calc-kbd-pop (Restore values) -@end smallexample - -@noindent -Press @kbd{C-c C-c} to finish editing and return to the Calculator. - -@smallexample -@group -1: 20 1: 3.597739 - . . - - 20 z h -@end group -@end smallexample - -The @file{edmacro} package defines a handy @code{read-kbd-macro} command -which reads the current region of the current buffer as a sequence of -keystroke names, and defines that sequence on the @kbd{X} -(and @kbd{C-x e}) key. Because this is so useful, Calc puts this -command on the @kbd{C-x * m} key. Try reading in this macro in the -following form: Press @kbd{C-@@} (or @kbd{C-@key{SPC}}) at -one end of the text below, then type @kbd{C-x * m} at the other. - -@example -@group -Z ` 0 t 1 - 1 TAB - Z ( & s + 1 1 Z ) - r 1 -Z ' -@end group -@end example - -(@bullet{}) @strong{Exercise 8.} A general algorithm for solving -equations numerically is @dfn{Newton's Method}. Given the equation -@expr{f(x) = 0} for any function @expr{f}, and an initial guess -@expr{x_0} which is reasonably close to the desired solution, apply -this formula over and over: - -@ifnottex -@example -new_x = x - f(x)/f'(x) -@end example -@end ifnottex -@tex -\beforedisplay -$$ x_{\rm new} = x - {f(x) \over f^{\prime}(x)} $$ -\afterdisplay -@end tex - -@noindent -where @expr{f'(x)} is the derivative of @expr{f}. The @expr{x} -values will quickly converge to a solution, i.e., eventually -@texline @math{x_{\rm new}} -@infoline @expr{new_x} -and @expr{x} will be equal to within the limits -of the current precision. Write a program which takes a formula -involving the variable @expr{x}, and an initial guess @expr{x_0}, -on the stack, and produces a value of @expr{x} for which the formula -is zero. Use it to find a solution of -@texline @math{\sin(\cos x) = 0.5} -@infoline @expr{sin(cos(x)) = 0.5} -near @expr{x = 4.5}. (Use angles measured in radians.) Note that -the built-in @w{@kbd{a R}} (@code{calc-find-root}) command uses Newton's -method when it is able. @xref{Programming Answer 8, 8}. (@bullet{}) - -@cindex Digamma function -@cindex Gamma constant, Euler's -@cindex Euler's gamma constant -(@bullet{}) @strong{Exercise 9.} The @dfn{digamma} function -@texline @math{\psi(z) (``psi'')} -@infoline @expr{psi(z)} -is defined as the derivative of -@texline @math{\ln \Gamma(z)}. -@infoline @expr{ln(gamma(z))}. -For large values of @expr{z}, it can be approximated by the infinite sum - -@ifnottex -@example -psi(z) ~= ln(z) - 1/2z - sum(bern(2 n) / 2 n z^(2 n), n, 1, inf) -@end example -@end ifnottex -@tex -\beforedisplay -$$ \psi(z) \approx \ln z - {1\over2z} - - \sum_{n=1}^\infty {\code{bern}(2 n) \over 2 n z^{2n}} -$$ -\afterdisplay -@end tex - -@noindent -where -@texline @math{\sum} -@infoline @expr{sum} -represents the sum over @expr{n} from 1 to infinity -(or to some limit high enough to give the desired accuracy), and -the @code{bern} function produces (exact) Bernoulli numbers. -While this sum is not guaranteed to converge, in practice it is safe. -An interesting mathematical constant is Euler's gamma, which is equal -to about 0.5772. One way to compute it is by the formula, -@texline @math{\gamma = -\psi(1)}. -@infoline @expr{gamma = -psi(1)}. -Unfortunately, 1 isn't a large enough argument -for the above formula to work (5 is a much safer value for @expr{z}). -Fortunately, we can compute -@texline @math{\psi(1)} -@infoline @expr{psi(1)} -from -@texline @math{\psi(5)} -@infoline @expr{psi(5)} -using the recurrence -@texline @math{\psi(z+1) = \psi(z) + {1 \over z}}. -@infoline @expr{psi(z+1) = psi(z) + 1/z}. -Your task: Develop a program to compute -@texline @math{\psi(z)}; -@infoline @expr{psi(z)}; -it should ``pump up'' @expr{z} -if necessary to be greater than 5, then use the above summation -formula. Use looping commands to compute the sum. Use your function -to compute -@texline @math{\gamma} -@infoline @expr{gamma} -to twelve decimal places. (Calc has a built-in command -for Euler's constant, @kbd{I P}, which you can use to check your answer.) -@xref{Programming Answer 9, 9}. (@bullet{}) - -@cindex Polynomial, list of coefficients -(@bullet{}) @strong{Exercise 10.} Given a polynomial in @expr{x} and -a number @expr{m} on the stack, where the polynomial is of degree -@expr{m} or less (i.e., does not have any terms higher than @expr{x^m}), -write a program to convert the polynomial into a list-of-coefficients -notation. For example, @expr{5 x^4 + (x + 1)^2} with @expr{m = 6} -should produce the list @expr{[1, 2, 1, 0, 5, 0, 0]}. Also develop -a way to convert from this form back to the standard algebraic form. -@xref{Programming Answer 10, 10}. (@bullet{}) - -@cindex Recursion -(@bullet{}) @strong{Exercise 11.} The @dfn{Stirling numbers of the -first kind} are defined by the recurrences, - -@ifnottex -@example -s(n,n) = 1 for n >= 0, -s(n,0) = 0 for n > 0, -s(n+1,m) = s(n,m-1) - n s(n,m) for n >= m >= 1. -@end example -@end ifnottex -@tex -\beforedisplay -$$ \eqalign{ s(n,n) &= 1 \qquad \hbox{for } n \ge 0, \cr - s(n,0) &= 0 \qquad \hbox{for } n > 0, \cr - s(n+1,m) &= s(n,m-1) - n \, s(n,m) \qquad - \hbox{for } n \ge m \ge 1.} -$$ -\afterdisplay -\vskip5pt -(These numbers are also sometimes written $\displaystyle{n \brack m}$.) -@end tex - -This can be implemented using a @dfn{recursive} program in Calc; the -program must invoke itself in order to calculate the two righthand -terms in the general formula. Since it always invokes itself with -``simpler'' arguments, it's easy to see that it must eventually finish -the computation. Recursion is a little difficult with Emacs keyboard -macros since the macro is executed before its definition is complete. -So here's the recommended strategy: Create a ``dummy macro'' and assign -it to a key with, e.g., @kbd{Z K s}. Now enter the true definition, -using the @kbd{z s} command to call itself recursively, then assign it -to the same key with @kbd{Z K s}. Now the @kbd{z s} command will run -the complete recursive program. (Another way is to use @w{@kbd{Z E}} -or @kbd{C-x * m} (@code{read-kbd-macro}) to read the whole macro at once, -thus avoiding the ``training'' phase.) The task: Write a program -that computes Stirling numbers of the first kind, given @expr{n} and -@expr{m} on the stack. Test it with @emph{small} inputs like -@expr{s(4,2)}. (There is a built-in command for Stirling numbers, -@kbd{k s}, which you can use to check your answers.) -@xref{Programming Answer 11, 11}. (@bullet{}) - -The programming commands we've seen in this part of the tutorial -are low-level, general-purpose operations. Often you will find -that a higher-level function, such as vector mapping or rewrite -rules, will do the job much more easily than a detailed, step-by-step -program can: - -(@bullet{}) @strong{Exercise 12.} Write another program for -computing Stirling numbers of the first kind, this time using -rewrite rules. Once again, @expr{n} and @expr{m} should be taken -from the stack. @xref{Programming Answer 12, 12}. (@bullet{}) - -@example - -@end example -This ends the tutorial section of the Calc manual. Now you know enough -about Calc to use it effectively for many kinds of calculations. But -Calc has many features that were not even touched upon in this tutorial. -@c [not-split] -The rest of this manual tells the whole story. -@c [when-split] -@c Volume II of this manual, the @dfn{Calc Reference}, tells the whole story. - -@page -@node Answers to Exercises, , Programming Tutorial, Tutorial -@section Answers to Exercises - -@noindent -This section includes answers to all the exercises in the Calc tutorial. - -@menu -* RPN Answer 1:: 1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * - -* RPN Answer 2:: 2*4 + 7*9.5 + 5/4 -* RPN Answer 3:: Operating on levels 2 and 3 -* RPN Answer 4:: Joe's complex problems -* Algebraic Answer 1:: Simulating Q command -* Algebraic Answer 2:: Joe's algebraic woes -* Algebraic Answer 3:: 1 / 0 -* Modes Answer 1:: 3#0.1 = 3#0.0222222? -* Modes Answer 2:: 16#f.e8fe15 -* Modes Answer 3:: Joe's rounding bug -* Modes Answer 4:: Why floating point? -* Arithmetic Answer 1:: Why the \ command? -* Arithmetic Answer 2:: Tripping up the B command -* Vector Answer 1:: Normalizing a vector -* Vector Answer 2:: Average position -* Matrix Answer 1:: Row and column sums -* Matrix Answer 2:: Symbolic system of equations -* Matrix Answer 3:: Over-determined system -* List Answer 1:: Powers of two -* List Answer 2:: Least-squares fit with matrices -* List Answer 3:: Geometric mean -* List Answer 4:: Divisor function -* List Answer 5:: Duplicate factors -* List Answer 6:: Triangular list -* List Answer 7:: Another triangular list -* List Answer 8:: Maximum of Bessel function -* List Answer 9:: Integers the hard way -* List Answer 10:: All elements equal -* List Answer 11:: Estimating pi with darts -* List Answer 12:: Estimating pi with matchsticks -* List Answer 13:: Hash codes -* List Answer 14:: Random walk -* Types Answer 1:: Square root of pi times rational -* Types Answer 2:: Infinities -* Types Answer 3:: What can "nan" be? -* Types Answer 4:: Abbey Road -* Types Answer 5:: Friday the 13th -* Types Answer 6:: Leap years -* Types Answer 7:: Erroneous donut -* Types Answer 8:: Dividing intervals -* Types Answer 9:: Squaring intervals -* Types Answer 10:: Fermat's primality test -* Types Answer 11:: pi * 10^7 seconds -* Types Answer 12:: Abbey Road on CD -* Types Answer 13:: Not quite pi * 10^7 seconds -* Types Answer 14:: Supercomputers and c -* Types Answer 15:: Sam the Slug -* Algebra Answer 1:: Squares and square roots -* Algebra Answer 2:: Building polynomial from roots -* Algebra Answer 3:: Integral of x sin(pi x) -* Algebra Answer 4:: Simpson's rule -* Rewrites Answer 1:: Multiplying by conjugate -* Rewrites Answer 2:: Alternative fib rule -* Rewrites Answer 3:: Rewriting opt(a) + opt(b) x -* Rewrites Answer 4:: Sequence of integers -* Rewrites Answer 5:: Number of terms in sum -* Rewrites Answer 6:: Truncated Taylor series -* Programming Answer 1:: Fresnel's C(x) -* Programming Answer 2:: Negate third stack element -* Programming Answer 3:: Compute sin(x) / x, etc. -* Programming Answer 4:: Average value of a list -* Programming Answer 5:: Continued fraction phi -* Programming Answer 6:: Matrix Fibonacci numbers -* Programming Answer 7:: Harmonic number greater than 4 -* Programming Answer 8:: Newton's method -* Programming Answer 9:: Digamma function -* Programming Answer 10:: Unpacking a polynomial -* Programming Answer 11:: Recursive Stirling numbers -* Programming Answer 12:: Stirling numbers with rewrites -@end menu - -@c The following kludgery prevents the individual answers from -@c being entered on the table of contents. -@tex -\global\let\oldwrite=\write -\gdef\skipwrite#1#2{\let\write=\oldwrite} -\global\let\oldchapternofonts=\chapternofonts -\gdef\chapternofonts{\let\write=\skipwrite\oldchapternofonts} -@end tex - -@node RPN Answer 1, RPN Answer 2, Answers to Exercises, Answers to Exercises -@subsection RPN Tutorial Exercise 1 - -@noindent -@kbd{1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -} - -The result is -@texline @math{1 - (2 \times (3 + 4)) = -13}. -@infoline @expr{1 - (2 * (3 + 4)) = -13}. - -@node RPN Answer 2, RPN Answer 3, RPN Answer 1, Answers to Exercises -@subsection RPN Tutorial Exercise 2 - -@noindent -@texline @math{2\times4 + 7\times9.5 + {5\over4} = 75.75} -@infoline @expr{2*4 + 7*9.5 + 5/4 = 75.75} - -After computing the intermediate term -@texline @math{2\times4 = 8}, -@infoline @expr{2*4 = 8}, -you can leave that result on the stack while you compute the second -term. With both of these results waiting on the stack you can then -compute the final term, then press @kbd{+ +} to add everything up. - -@smallexample -@group -2: 2 1: 8 3: 8 2: 8 -1: 4 . 2: 7 1: 66.5 - . 1: 9.5 . - . - - 2 @key{RET} 4 * 7 @key{RET} 9.5 * - -@end group -@end smallexample -@noindent -@smallexample -@group -4: 8 3: 8 2: 8 1: 75.75 -3: 66.5 2: 66.5 1: 67.75 . -2: 5 1: 1.25 . -1: 4 . - . - - 5 @key{RET} 4 / + + -@end group -@end smallexample - -Alternatively, you could add the first two terms before going on -with the third term. - -@smallexample -@group -2: 8 1: 74.5 3: 74.5 2: 74.5 1: 75.75 -1: 66.5 . 2: 5 1: 1.25 . - . 1: 4 . - . - - ... + 5 @key{RET} 4 / + -@end group -@end smallexample - -On an old-style RPN calculator this second method would have the -advantage of using only three stack levels. But since Calc's stack -can grow arbitrarily large this isn't really an issue. Which method -you choose is purely a matter of taste. - -@node RPN Answer 3, RPN Answer 4, RPN Answer 2, Answers to Exercises -@subsection RPN Tutorial Exercise 3 - -@noindent -The @key{TAB} key provides a way to operate on the number in level 2. - -@smallexample -@group -3: 10 3: 10 4: 10 3: 10 3: 10 -2: 20 2: 30 3: 30 2: 30 2: 21 -1: 30 1: 20 2: 20 1: 21 1: 30 - . . 1: 1 . . - . - - @key{TAB} 1 + @key{TAB} -@end group -@end smallexample - -Similarly, @kbd{M-@key{TAB}} gives you access to the number in level 3. - -@smallexample -@group -3: 10 3: 21 3: 21 3: 30 3: 11 -2: 21 2: 30 2: 30 2: 11 2: 21 -1: 30 1: 10 1: 11 1: 21 1: 30 - . . . . . - - M-@key{TAB} 1 + M-@key{TAB} M-@key{TAB} -@end group -@end smallexample - -@node RPN Answer 4, Algebraic Answer 1, RPN Answer 3, Answers to Exercises -@subsection RPN Tutorial Exercise 4 - -@noindent -Either @kbd{( 2 , 3 )} or @kbd{( 2 @key{SPC} 3 )} would have worked, -but using both the comma and the space at once yields: - -@smallexample -@group -1: ( ... 2: ( ... 1: (2, ... 2: (2, ... 2: (2, ... - . 1: 2 . 1: (2, ... 1: (2, 3) - . . . - - ( 2 , @key{SPC} 3 ) -@end group -@end smallexample - -Joe probably tried to type @kbd{@key{TAB} @key{DEL}} to swap the -extra incomplete object to the top of the stack and delete it. -But a feature of Calc is that @key{DEL} on an incomplete object -deletes just one component out of that object, so he had to press -@key{DEL} twice to finish the job. - -@smallexample -@group -2: (2, ... 2: (2, 3) 2: (2, 3) 1: (2, 3) -1: (2, 3) 1: (2, ... 1: ( ... . - . . . - - @key{TAB} @key{DEL} @key{DEL} -@end group -@end smallexample - -(As it turns out, deleting the second-to-top stack entry happens often -enough that Calc provides a special key, @kbd{M-@key{DEL}}, to do just that. -@kbd{M-@key{DEL}} is just like @kbd{@key{TAB} @key{DEL}}, except that it doesn't exhibit -the ``feature'' that tripped poor Joe.) - -@node Algebraic Answer 1, Algebraic Answer 2, RPN Answer 4, Answers to Exercises -@subsection Algebraic Entry Tutorial Exercise 1 - -@noindent -Type @kbd{' sqrt($) @key{RET}}. - -If the @kbd{Q} key is broken, you could use @kbd{' $^0.5 @key{RET}}. -Or, RPN style, @kbd{0.5 ^}. - -(Actually, @samp{$^1:2}, using the fraction one-half as the power, is -a closer equivalent, since @samp{9^0.5} yields @expr{3.0} whereas -@samp{sqrt(9)} and @samp{9^1:2} yield the exact integer @expr{3}.) - -@node Algebraic Answer 2, Algebraic Answer 3, Algebraic Answer 1, Answers to Exercises -@subsection Algebraic Entry Tutorial Exercise 2 - -@noindent -In the formula @samp{2 x (1+y)}, @samp{x} was interpreted as a function -name with @samp{1+y} as its argument. Assigning a value to a variable -has no relation to a function by the same name. Joe needed to use an -explicit @samp{*} symbol here: @samp{2 x*(1+y)}. - -@node Algebraic Answer 3, Modes Answer 1, Algebraic Answer 2, Answers to Exercises -@subsection Algebraic Entry Tutorial Exercise 3 - -@noindent -The result from @kbd{1 @key{RET} 0 /} will be the formula @expr{1 / 0}. -The ``function'' @samp{/} cannot be evaluated when its second argument -is zero, so it is left in symbolic form. When you now type @kbd{0 *}, -the result will be zero because Calc uses the general rule that ``zero -times anything is zero.'' - -@c [fix-ref Infinities] -The @kbd{m i} command enables an @dfn{Infinite mode} in which @expr{1 / 0} -results in a special symbol that represents ``infinity.'' If you -multiply infinity by zero, Calc uses another special new symbol to -show that the answer is ``indeterminate.'' @xref{Infinities}, for -further discussion of infinite and indeterminate values. - -@node Modes Answer 1, Modes Answer 2, Algebraic Answer 3, Answers to Exercises -@subsection Modes Tutorial Exercise 1 - -@noindent -Calc always stores its numbers in decimal, so even though one-third has -an exact base-3 representation (@samp{3#0.1}), it is still stored as -0.3333333 (chopped off after 12 or however many decimal digits) inside -the calculator's memory. When this inexact number is converted back -to base 3 for display, it may still be slightly inexact. When we -multiply this number by 3, we get 0.999999, also an inexact value. - -When Calc displays a number in base 3, it has to decide how many digits -to show. If the current precision is 12 (decimal) digits, that corresponds -to @samp{12 / log10(3) = 25.15} base-3 digits. Because 25.15 is not an -exact integer, Calc shows only 25 digits, with the result that stored -numbers carry a little bit of extra information that may not show up on -the screen. When Joe entered @samp{3#0.2}, the stored number 0.666666 -happened to round to a pleasing value when it lost that last 0.15 of a -digit, but it was still inexact in Calc's memory. When he divided by 2, -he still got the dreaded inexact value 0.333333. (Actually, he divided -0.666667 by 2 to get 0.333334, which is why he got something a little -higher than @code{3#0.1} instead of a little lower.) - -If Joe didn't want to be bothered with all this, he could have typed -@kbd{M-24 d n} to display with one less digit than the default. (If -you give @kbd{d n} a negative argument, it uses default-minus-that, -so @kbd{M-- d n} would be an easier way to get the same effect.) Those -inexact results would still be lurking there, but they would now be -rounded to nice, natural-looking values for display purposes. (Remember, -@samp{0.022222} in base 3 is like @samp{0.099999} in base 10; rounding -off one digit will round the number up to @samp{0.1}.) Depending on the -nature of your work, this hiding of the inexactness may be a benefit or -a danger. With the @kbd{d n} command, Calc gives you the choice. - -Incidentally, another consequence of all this is that if you type -@kbd{M-30 d n} to display more digits than are ``really there,'' -you'll see garbage digits at the end of the number. (In decimal -display mode, with decimally-stored numbers, these garbage digits are -always zero so they vanish and you don't notice them.) Because Calc -rounds off that 0.15 digit, there is the danger that two numbers could -be slightly different internally but still look the same. If you feel -uneasy about this, set the @kbd{d n} precision to be a little higher -than normal; you'll get ugly garbage digits, but you'll always be able -to tell two distinct numbers apart. - -An interesting side note is that most computers store their -floating-point numbers in binary, and convert to decimal for display. -Thus everyday programs have the same problem: Decimal 0.1 cannot be -represented exactly in binary (try it: @kbd{0.1 d 2}), so @samp{0.1 * 10} -comes out as an inexact approximation to 1 on some machines (though -they generally arrange to hide it from you by rounding off one digit as -we did above). Because Calc works in decimal instead of binary, you can -be sure that numbers that look exact @emph{are} exact as long as you stay -in decimal display mode. - -It's not hard to show that any number that can be represented exactly -in binary, octal, or hexadecimal is also exact in decimal, so the kinds -of problems we saw in this exercise are likely to be severe only when -you use a relatively unusual radix like 3. - -@node Modes Answer 2, Modes Answer 3, Modes Answer 1, Answers to Exercises -@subsection Modes Tutorial Exercise 2 - -If the radix is 15 or higher, we can't use the letter @samp{e} to mark -the exponent because @samp{e} is interpreted as a digit. When Calc -needs to display scientific notation in a high radix, it writes -@samp{16#F.E8F*16.^15}. You can enter a number like this as an -algebraic entry. Also, pressing @kbd{e} without any digits before it -normally types @kbd{1e}, but in a high radix it types @kbd{16.^} and -puts you in algebraic entry: @kbd{16#f.e8f @key{RET} e 15 @key{RET} *} is another -way to enter this number. - -The reason Calc puts a decimal point in the @samp{16.^} is to prevent -huge integers from being generated if the exponent is large (consider -@samp{16#1.23*16^1000}, where we compute @samp{16^1000} as a giant -exact integer and then throw away most of the digits when we multiply -it by the floating-point @samp{16#1.23}). While this wouldn't normally -matter for display purposes, it could give you a nasty surprise if you -copied that number into a file and later moved it back into Calc. - -@node Modes Answer 3, Modes Answer 4, Modes Answer 2, Answers to Exercises -@subsection Modes Tutorial Exercise 3 - -@noindent -The answer he got was @expr{0.5000000000006399}. - -The problem is not that the square operation is inexact, but that the -sine of 45 that was already on the stack was accurate to only 12 places. -Arbitrary-precision calculations still only give answers as good as -their inputs. - -The real problem is that there is no 12-digit number which, when -squared, comes out to 0.5 exactly. The @kbd{f [} and @kbd{f ]} -commands decrease or increase a number by one unit in the last -place (according to the current precision). They are useful for -determining facts like this. - -@smallexample -@group -1: 0.707106781187 1: 0.500000000001 - . . - - 45 S 2 ^ - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 0.707106781187 1: 0.707106781186 1: 0.499999999999 - . . . - - U @key{DEL} f [ 2 ^ -@end group -@end smallexample - -A high-precision calculation must be carried out in high precision -all the way. The only number in the original problem which was known -exactly was the quantity 45 degrees, so the precision must be raised -before anything is done after the number 45 has been entered in order -for the higher precision to be meaningful. - -@node Modes Answer 4, Arithmetic Answer 1, Modes Answer 3, Answers to Exercises -@subsection Modes Tutorial Exercise 4 - -@noindent -Many calculations involve real-world quantities, like the width and -height of a piece of wood or the volume of a jar. Such quantities -can't be measured exactly anyway, and if the data that is input to -a calculation is inexact, doing exact arithmetic on it is a waste -of time. - -Fractions become unwieldy after too many calculations have been -done with them. For example, the sum of the reciprocals of the -integers from 1 to 10 is 7381:2520. The sum from 1 to 30 is -9304682830147:2329089562800. After a point it will take a long -time to add even one more term to this sum, but a floating-point -calculation of the sum will not have this problem. - -Also, rational numbers cannot express the results of all calculations. -There is no fractional form for the square root of two, so if you type -@w{@kbd{2 Q}}, Calc has no choice but to give you a floating-point answer. - -@node Arithmetic Answer 1, Arithmetic Answer 2, Modes Answer 4, Answers to Exercises -@subsection Arithmetic Tutorial Exercise 1 - -@noindent -Dividing two integers that are larger than the current precision may -give a floating-point result that is inaccurate even when rounded -down to an integer. Consider @expr{123456789 / 2} when the current -precision is 6 digits. The true answer is @expr{61728394.5}, but -with a precision of 6 this will be rounded to -@texline @math{12345700.0/2.0 = 61728500.0}. -@infoline @expr{12345700.@: / 2.@: = 61728500.}. -The result, when converted to an integer, will be off by 106. - -Here are two solutions: Raise the precision enough that the -floating-point round-off error is strictly to the right of the -decimal point. Or, convert to Fraction mode so that @expr{123456789 / 2} -produces the exact fraction @expr{123456789:2}, which can be rounded -down by the @kbd{F} command without ever switching to floating-point -format. - -@node Arithmetic Answer 2, Vector Answer 1, Arithmetic Answer 1, Answers to Exercises -@subsection Arithmetic Tutorial Exercise 2 - -@noindent -@kbd{27 @key{RET} 9 B} could give the exact result @expr{3:2}, but it -does a floating-point calculation instead and produces @expr{1.5}. - -Calc will find an exact result for a logarithm if the result is an integer -or (when in Fraction mode) the reciprocal of an integer. But there is -no efficient way to search the space of all possible rational numbers -for an exact answer, so Calc doesn't try. - -@node Vector Answer 1, Vector Answer 2, Arithmetic Answer 2, Answers to Exercises -@subsection Vector Tutorial Exercise 1 - -@noindent -Duplicate the vector, compute its length, then divide the vector -by its length: @kbd{@key{RET} A /}. - -@smallexample -@group -1: [1, 2, 3] 2: [1, 2, 3] 1: [0.27, 0.53, 0.80] 1: 1. - . 1: 3.74165738677 . . - . - - r 1 @key{RET} A / A -@end group -@end smallexample - -The final @kbd{A} command shows that the normalized vector does -indeed have unit length. - -@node Vector Answer 2, Matrix Answer 1, Vector Answer 1, Answers to Exercises -@subsection Vector Tutorial Exercise 2 - -@noindent -The average position is equal to the sum of the products of the -positions times their corresponding probabilities. This is the -definition of the dot product operation. So all you need to do -is to put the two vectors on the stack and press @kbd{*}. - -@node Matrix Answer 1, Matrix Answer 2, Vector Answer 2, Answers to Exercises -@subsection Matrix Tutorial Exercise 1 - -@noindent -The trick is to multiply by a vector of ones. Use @kbd{r 4 [1 1 1] *} to -get the row sum. Similarly, use @kbd{[1 1] r 4 *} to get the column sum. - -@node Matrix Answer 2, Matrix Answer 3, Matrix Answer 1, Answers to Exercises -@subsection Matrix Tutorial Exercise 2 - -@ifnottex -@example -@group - x + a y = 6 - x + b y = 10 -@end group -@end example -@end ifnottex -@tex -\beforedisplay -$$ \eqalign{ x &+ a y = 6 \cr - x &+ b y = 10} -$$ -\afterdisplay -@end tex - -Just enter the righthand side vector, then divide by the lefthand side -matrix as usual. - -@smallexample -@group -1: [6, 10] 2: [6, 10] 1: [6 - 4 a / (b - a), 4 / (b - a) ] - . 1: [ [ 1, a ] . - [ 1, b ] ] - . - -' [6 10] @key{RET} ' [1 a; 1 b] @key{RET} / -@end group -@end smallexample - -This can be made more readable using @kbd{d B} to enable Big display -mode: - -@smallexample -@group - 4 a 4 -1: [6 - -----, -----] - b - a b - a -@end group -@end smallexample - -Type @kbd{d N} to return to Normal display mode afterwards. - -@node Matrix Answer 3, List Answer 1, Matrix Answer 2, Answers to Exercises -@subsection Matrix Tutorial Exercise 3 - -@noindent -To solve -@texline @math{A^T A \, X = A^T B}, -@infoline @expr{trn(A) * A * X = trn(A) * B}, -first we compute -@texline @math{A' = A^T A} -@infoline @expr{A2 = trn(A) * A} -and -@texline @math{B' = A^T B}; -@infoline @expr{B2 = trn(A) * B}; -now, we have a system -@texline @math{A' X = B'} -@infoline @expr{A2 * X = B2} -which we can solve using Calc's @samp{/} command. - -@ifnottex -@example -@group - a + 2b + 3c = 6 - 4a + 5b + 6c = 2 - 7a + 6b = 3 - 2a + 4b + 6c = 11 -@end group -@end example -@end ifnottex -@tex -\beforedisplayh -$$ \openup1\jot \tabskip=0pt plus1fil -\halign to\displaywidth{\tabskip=0pt - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr - a&+&2b&+&3c&=6 \cr - 4a&+&5b&+&6c&=2 \cr - 7a&+&6b& & &=3 \cr - 2a&+&4b&+&6c&=11 \cr} -$$ -\afterdisplayh -@end tex - -The first step is to enter the coefficient matrix. We'll store it in -quick variable number 7 for later reference. Next, we compute the -@texline @math{B'} -@infoline @expr{B2} -vector. - -@smallexample -@group -1: [ [ 1, 2, 3 ] 2: [ [ 1, 4, 7, 2 ] 1: [57, 84, 96] - [ 4, 5, 6 ] [ 2, 5, 6, 4 ] . - [ 7, 6, 0 ] [ 3, 6, 0, 6 ] ] - [ 2, 4, 6 ] ] 1: [6, 2, 3, 11] - . . - -' [1 2 3; 4 5 6; 7 6 0; 2 4 6] @key{RET} s 7 v t [6 2 3 11] * -@end group -@end smallexample - -@noindent -Now we compute the matrix -@texline @math{A'} -@infoline @expr{A2} -and divide. - -@smallexample -@group -2: [57, 84, 96] 1: [-11.64, 14.08, -3.64] -1: [ [ 70, 72, 39 ] . - [ 72, 81, 60 ] - [ 39, 60, 81 ] ] - . - - r 7 v t r 7 * / -@end group -@end smallexample - -@noindent -(The actual computed answer will be slightly inexact due to -round-off error.) - -Notice that the answers are similar to those for the -@texline @math{3\times3} -@infoline 3x3 -system solved in the text. That's because the fourth equation that was -added to the system is almost identical to the first one multiplied -by two. (If it were identical, we would have gotten the exact same -answer since the -@texline @math{4\times3} -@infoline 4x3 -system would be equivalent to the original -@texline @math{3\times3} -@infoline 3x3 -system.) - -Since the first and fourth equations aren't quite equivalent, they -can't both be satisfied at once. Let's plug our answers back into -the original system of equations to see how well they match. - -@smallexample -@group -2: [-11.64, 14.08, -3.64] 1: [5.6, 2., 3., 11.2] -1: [ [ 1, 2, 3 ] . - [ 4, 5, 6 ] - [ 7, 6, 0 ] - [ 2, 4, 6 ] ] - . - - r 7 @key{TAB} * -@end group -@end smallexample - -@noindent -This is reasonably close to our original @expr{B} vector, -@expr{[6, 2, 3, 11]}. - -@node List Answer 1, List Answer 2, Matrix Answer 3, Answers to Exercises -@subsection List Tutorial Exercise 1 - -@noindent -We can use @kbd{v x} to build a vector of integers. This needs to be -adjusted to get the range of integers we desire. Mapping @samp{-} -across the vector will accomplish this, although it turns out the -plain @samp{-} key will work just as well. - -@smallexample -@group -2: 2 2: 2 -1: [1, 2, 3, 4, 5, 6, 7, 8, 9] 1: [-4, -3, -2, -1, 0, 1, 2, 3, 4] - . . - - 2 v x 9 @key{RET} 5 V M - or 5 - -@end group -@end smallexample - -@noindent -Now we use @kbd{V M ^} to map the exponentiation operator across the -vector. - -@smallexample -@group -1: [0.0625, 0.125, 0.25, 0.5, 1, 2, 4, 8, 16] - . - - V M ^ -@end group -@end smallexample - -@node List Answer 2, List Answer 3, List Answer 1, Answers to Exercises -@subsection List Tutorial Exercise 2 - -@noindent -Given @expr{x} and @expr{y} vectors in quick variables 1 and 2 as before, -the first job is to form the matrix that describes the problem. - -@ifnottex -@example - m*x + b*1 = y -@end example -@end ifnottex -@tex -\beforedisplay -$$ m \times x + b \times 1 = y $$ -\afterdisplay -@end tex - -Thus we want a -@texline @math{19\times2} -@infoline 19x2 -matrix with our @expr{x} vector as one column and -ones as the other column. So, first we build the column of ones, then -we combine the two columns to form our @expr{A} matrix. - -@smallexample -@group -2: [1.34, 1.41, 1.49, ... ] 1: [ [ 1.34, 1 ] -1: [1, 1, 1, ...] [ 1.41, 1 ] - . [ 1.49, 1 ] - @dots{} - - r 1 1 v b 19 @key{RET} M-2 v p v t s 3 -@end group -@end smallexample - -@noindent -Now we compute -@texline @math{A^T y} -@infoline @expr{trn(A) * y} -and -@texline @math{A^T A} -@infoline @expr{trn(A) * A} -and divide. - -@smallexample -@group -1: [33.36554, 13.613] 2: [33.36554, 13.613] - . 1: [ [ 98.0003, 41.63 ] - [ 41.63, 19 ] ] - . - - v t r 2 * r 3 v t r 3 * -@end group -@end smallexample - -@noindent -(Hey, those numbers look familiar!) - -@smallexample -@group -1: [0.52141679, -0.425978] - . - - / -@end group -@end smallexample - -Since we were solving equations of the form -@texline @math{m \times x + b \times 1 = y}, -@infoline @expr{m*x + b*1 = y}, -these numbers should be @expr{m} and @expr{b}, respectively. Sure -enough, they agree exactly with the result computed using @kbd{V M} and -@kbd{V R}! - -The moral of this story: @kbd{V M} and @kbd{V R} will probably solve -your problem, but there is often an easier way using the higher-level -arithmetic functions! - -@c [fix-ref Curve Fitting] -In fact, there is a built-in @kbd{a F} command that does least-squares -fits. @xref{Curve Fitting}. - -@node List Answer 3, List Answer 4, List Answer 2, Answers to Exercises -@subsection List Tutorial Exercise 3 - -@noindent -Move to one end of the list and press @kbd{C-@@} (or @kbd{C-@key{SPC}} or -whatever) to set the mark, then move to the other end of the list -and type @w{@kbd{C-x * g}}. - -@smallexample -@group -1: [2.3, 6, 22, 15.1, 7, 15, 14, 7.5, 2.5] - . -@end group -@end smallexample - -To make things interesting, let's assume we don't know at a glance -how many numbers are in this list. Then we could type: - -@smallexample -@group -2: [2.3, 6, 22, ... ] 2: [2.3, 6, 22, ... ] -1: [2.3, 6, 22, ... ] 1: 126356422.5 - . . - - @key{RET} V R * - -@end group -@end smallexample -@noindent -@smallexample -@group -2: 126356422.5 2: 126356422.5 1: 7.94652913734 -1: [2.3, 6, 22, ... ] 1: 9 . - . . - - @key{TAB} v l I ^ -@end group -@end smallexample - -@noindent -(The @kbd{I ^} command computes the @var{n}th root of a number. -You could also type @kbd{& ^} to take the reciprocal of 9 and -then raise the number to that power.) - -@node List Answer 4, List Answer 5, List Answer 3, Answers to Exercises -@subsection List Tutorial Exercise 4 - -@noindent -A number @expr{j} is a divisor of @expr{n} if -@texline @math{n \mathbin{\hbox{\code{\%}}} j = 0}. -@infoline @samp{n % j = 0}. -The first step is to get a vector that identifies the divisors. - -@smallexample -@group -2: 30 2: [0, 0, 0, 2, ...] 1: [1, 1, 1, 0, ...] -1: [1, 2, 3, 4, ...] 1: 0 . - . . - - 30 @key{RET} v x 30 @key{RET} s 1 V M % 0 V M a = s 2 -@end group -@end smallexample - -@noindent -This vector has 1's marking divisors of 30 and 0's marking non-divisors. - -The zeroth divisor function is just the total number of divisors. -The first divisor function is the sum of the divisors. - -@smallexample -@group -1: 8 3: 8 2: 8 2: 8 - 2: [1, 2, 3, 4, ...] 1: [1, 2, 3, 0, ...] 1: 72 - 1: [1, 1, 1, 0, ...] . . - . - - V R + r 1 r 2 V M * V R + -@end group -@end smallexample - -@noindent -Once again, the last two steps just compute a dot product for which -a simple @kbd{*} would have worked equally well. - -@node List Answer 5, List Answer 6, List Answer 4, Answers to Exercises -@subsection List Tutorial Exercise 5 - -@noindent -The obvious first step is to obtain the list of factors with @kbd{k f}. -This list will always be in sorted order, so if there are duplicates -they will be right next to each other. A suitable method is to compare -the list with a copy of itself shifted over by one. - -@smallexample -@group -1: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19, 0] - . 1: [3, 7, 7, 7, 19, 0] 1: [0, 3, 7, 7, 7, 19] - . . - - 19551 k f @key{RET} 0 | @key{TAB} 0 @key{TAB} | - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0, 0, 1, 1, 0, 0] 1: 2 1: 0 - . . . - - V M a = V R + 0 a = -@end group -@end smallexample - -@noindent -Note that we have to arrange for both vectors to have the same length -so that the mapping operation works; no prime factor will ever be -zero, so adding zeros on the left and right is safe. From then on -the job is pretty straightforward. - -Incidentally, Calc provides the -@texline @dfn{M@"obius} @math{\mu} -@infoline @dfn{Moebius mu} -function which is zero if and only if its argument is square-free. It -would be a much more convenient way to do the above test in practice. - -@node List Answer 6, List Answer 7, List Answer 5, Answers to Exercises -@subsection List Tutorial Exercise 6 - -@noindent -First use @kbd{v x 6 @key{RET}} to get a list of integers, then @kbd{V M v x} -to get a list of lists of integers! - -@node List Answer 7, List Answer 8, List Answer 6, Answers to Exercises -@subsection List Tutorial Exercise 7 - -@noindent -Here's one solution. First, compute the triangular list from the previous -exercise and type @kbd{1 -} to subtract one from all the elements. - -@smallexample -@group -1: [ [0], - [0, 1], - [0, 1, 2], - @dots{} - - 1 - -@end group -@end smallexample - -The numbers down the lefthand edge of the list we desire are called -the ``triangular numbers'' (now you know why!). The @expr{n}th -triangular number is the sum of the integers from 1 to @expr{n}, and -can be computed directly by the formula -@texline @math{n (n+1) \over 2}. -@infoline @expr{n * (n+1) / 2}. - -@smallexample -@group -2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ] -1: [0, 1, 2, 3, 4, 5] 1: [0, 1, 3, 6, 10, 15] - . . - - v x 6 @key{RET} 1 - V M ' $ ($+1)/2 @key{RET} -@end group -@end smallexample - -@noindent -Adding this list to the above list of lists produces the desired -result: - -@smallexample -@group -1: [ [0], - [1, 2], - [3, 4, 5], - [6, 7, 8, 9], - [10, 11, 12, 13, 14], - [15, 16, 17, 18, 19, 20] ] - . - - V M + -@end group -@end smallexample - -If we did not know the formula for triangular numbers, we could have -computed them using a @kbd{V U +} command. We could also have -gotten them the hard way by mapping a reduction across the original -triangular list. - -@smallexample -@group -2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ] -1: [ [0], [0, 1], ... ] 1: [0, 1, 3, 6, 10, 15] - . . - - @key{RET} V M V R + -@end group -@end smallexample - -@noindent -(This means ``map a @kbd{V R +} command across the vector,'' and -since each element of the main vector is itself a small vector, -@kbd{V R +} computes the sum of its elements.) - -@node List Answer 8, List Answer 9, List Answer 7, Answers to Exercises -@subsection List Tutorial Exercise 8 - -@noindent -The first step is to build a list of values of @expr{x}. - -@smallexample -@group -1: [1, 2, 3, ..., 21] 1: [0, 1, 2, ..., 20] 1: [0, 0.25, 0.5, ..., 5] - . . . - - v x 21 @key{RET} 1 - 4 / s 1 -@end group -@end smallexample - -Next, we compute the Bessel function values. - -@smallexample -@group -1: [0., 0.124, 0.242, ..., -0.328] - . - - V M ' besJ(1,$) @key{RET} -@end group -@end smallexample - -@noindent -(Another way to do this would be @kbd{1 @key{TAB} V M f j}.) - -A way to isolate the maximum value is to compute the maximum using -@kbd{V R X}, then compare all the Bessel values with that maximum. - -@smallexample -@group -2: [0., 0.124, 0.242, ... ] 1: [0, 0, 0, ... ] 2: [0, 0, 0, ... ] -1: 0.5801562 . 1: 1 - . . - - @key{RET} V R X V M a = @key{RET} V R + @key{DEL} -@end group -@end smallexample - -@noindent -It's a good idea to verify, as in the last step above, that only -one value is equal to the maximum. (After all, a plot of -@texline @math{\sin x} -@infoline @expr{sin(x)} -might have many points all equal to the maximum value, 1.) - -The vector we have now has a single 1 in the position that indicates -the maximum value of @expr{x}. Now it is a simple matter to convert -this back into the corresponding value itself. - -@smallexample -@group -2: [0, 0, 0, ... ] 1: [0, 0., 0., ... ] 1: 1.75 -1: [0, 0.25, 0.5, ... ] . . - . - - r 1 V M * V R + -@end group -@end smallexample - -If @kbd{a =} had produced more than one @expr{1} value, this method -would have given the sum of all maximum @expr{x} values; not very -useful! In this case we could have used @kbd{v m} (@code{calc-mask-vector}) -instead. This command deletes all elements of a ``data'' vector that -correspond to zeros in a ``mask'' vector, leaving us with, in this -example, a vector of maximum @expr{x} values. - -The built-in @kbd{a X} command maximizes a function using more -efficient methods. Just for illustration, let's use @kbd{a X} -to maximize @samp{besJ(1,x)} over this same interval. - -@smallexample -@group -2: besJ(1, x) 1: [1.84115, 0.581865] -1: [0 .. 5] . - . - -' besJ(1,x), [0..5] @key{RET} a X x @key{RET} -@end group -@end smallexample - -@noindent -The output from @kbd{a X} is a vector containing the value of @expr{x} -that maximizes the function, and the function's value at that maximum. -As you can see, our simple search got quite close to the right answer. - -@node List Answer 9, List Answer 10, List Answer 8, Answers to Exercises -@subsection List Tutorial Exercise 9 - -@noindent -Step one is to convert our integer into vector notation. - -@smallexample -@group -1: 25129925999 3: 25129925999 - . 2: 10 - 1: [11, 10, 9, ..., 1, 0] - . - - 25129925999 @key{RET} 10 @key{RET} 12 @key{RET} v x 12 @key{RET} - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 25129925999 1: [0, 2, 25, 251, 2512, ... ] -2: [100000000000, ... ] . - . - - V M ^ s 1 V M \ -@end group -@end smallexample - -@noindent -(Recall, the @kbd{\} command computes an integer quotient.) - -@smallexample -@group -1: [0, 2, 5, 1, 2, 9, 9, 2, 5, 9, 9, 9] - . - - 10 V M % s 2 -@end group -@end smallexample - -Next we must increment this number. This involves adding one to -the last digit, plus handling carries. There is a carry to the -left out of a digit if that digit is a nine and all the digits to -the right of it are nines. - -@smallexample -@group -1: [0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1] 1: [1, 1, 1, 0, 0, 1, ... ] - . . - - 9 V M a = v v - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [1, 1, 1, 0, 0, 0, ... ] 1: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1] - . . - - V U * v v 1 | -@end group -@end smallexample - -@noindent -Accumulating @kbd{*} across a vector of ones and zeros will preserve -only the initial run of ones. These are the carries into all digits -except the rightmost digit. Concatenating a one on the right takes -care of aligning the carries properly, and also adding one to the -rightmost digit. - -@smallexample -@group -2: [0, 0, 0, 0, ... ] 1: [0, 0, 2, 5, 1, 2, 9, 9, 2, 6, 0, 0, 0] -1: [0, 0, 2, 5, ... ] . - . - - 0 r 2 | V M + 10 V M % -@end group -@end smallexample - -@noindent -Here we have concatenated 0 to the @emph{left} of the original number; -this takes care of shifting the carries by one with respect to the -digits that generated them. - -Finally, we must convert this list back into an integer. - -@smallexample -@group -3: [0, 0, 2, 5, ... ] 2: [0, 0, 2, 5, ... ] -2: 1000000000000 1: [1000000000000, 100000000000, ... ] -1: [100000000000, ... ] . - . - - 10 @key{RET} 12 ^ r 1 | - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0, 0, 20000000000, 5000000000, ... ] 1: 25129926000 - . . - - V M * V R + -@end group -@end smallexample - -@noindent -Another way to do this final step would be to reduce the formula -@w{@samp{10 $$ + $}} across the vector of digits. - -@smallexample -@group -1: [0, 0, 2, 5, ... ] 1: 25129926000 - . . - - V R ' 10 $$ + $ @key{RET} -@end group -@end smallexample - -@node List Answer 10, List Answer 11, List Answer 9, Answers to Exercises -@subsection List Tutorial Exercise 10 - -@noindent -For the list @expr{[a, b, c, d]}, the result is @expr{((a = b) = c) = d}, -which will compare @expr{a} and @expr{b} to produce a 1 or 0, which is -then compared with @expr{c} to produce another 1 or 0, which is then -compared with @expr{d}. This is not at all what Joe wanted. - -Here's a more correct method: - -@smallexample -@group -1: [7, 7, 7, 8, 7] 2: [7, 7, 7, 8, 7] - . 1: 7 - . - - ' [7,7,7,8,7] @key{RET} @key{RET} v r 1 @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [1, 1, 1, 0, 1] 1: 0 - . . - - V M a = V R * -@end group -@end smallexample - -@node List Answer 11, List Answer 12, List Answer 10, Answers to Exercises -@subsection List Tutorial Exercise 11 - -@noindent -The circle of unit radius consists of those points @expr{(x,y)} for which -@expr{x^2 + y^2 < 1}. We start by generating a vector of @expr{x^2} -and a vector of @expr{y^2}. - -We can make this go a bit faster by using the @kbd{v .} and @kbd{t .} -commands. - -@smallexample -@group -2: [2., 2., ..., 2.] 2: [2., 2., ..., 2.] -1: [2., 2., ..., 2.] 1: [1.16, 1.98, ..., 0.81] - . . - - v . t . 2. v b 100 @key{RET} @key{RET} V M k r - -@end group -@end smallexample -@noindent -@smallexample -@group -2: [2., 2., ..., 2.] 1: [0.026, 0.96, ..., 0.036] -1: [0.026, 0.96, ..., 0.036] 2: [0.53, 0.81, ..., 0.094] - . . - - 1 - 2 V M ^ @key{TAB} V M k r 1 - 2 V M ^ -@end group -@end smallexample - -Now we sum the @expr{x^2} and @expr{y^2} values, compare with 1 to -get a vector of 1/0 truth values, then sum the truth values. - -@smallexample -@group -1: [0.56, 1.78, ..., 0.13] 1: [1, 0, ..., 1] 1: 84 - . . . - - + 1 V M a < V R + -@end group -@end smallexample - -@noindent -The ratio @expr{84/100} should approximate the ratio @cpiover{4}. - -@smallexample -@group -1: 0.84 1: 3.36 2: 3.36 1: 1.0695 - . . 1: 3.14159 . - - 100 / 4 * P / -@end group -@end smallexample - -@noindent -Our estimate, 3.36, is off by about 7%. We could get a better estimate -by taking more points (say, 1000), but it's clear that this method is -not very efficient! - -(Naturally, since this example uses random numbers your own answer -will be slightly different from the one shown here!) - -If you typed @kbd{v .} and @kbd{t .} before, type them again to -return to full-sized display of vectors. - -@node List Answer 12, List Answer 13, List Answer 11, Answers to Exercises -@subsection List Tutorial Exercise 12 - -@noindent -This problem can be made a lot easier by taking advantage of some -symmetries. First of all, after some thought it's clear that the -@expr{y} axis can be ignored altogether. Just pick a random @expr{x} -component for one end of the match, pick a random direction -@texline @math{\theta}, -@infoline @expr{theta}, -and see if @expr{x} and -@texline @math{x + \cos \theta} -@infoline @expr{x + cos(theta)} -(which is the @expr{x} coordinate of the other endpoint) cross a line. -The lines are at integer coordinates, so this happens when the two -numbers surround an integer. - -Since the two endpoints are equivalent, we may as well choose the leftmost -of the two endpoints as @expr{x}. Then @expr{theta} is an angle pointing -to the right, in the range -90 to 90 degrees. (We could use radians, but -it would feel like cheating to refer to @cpiover{2} radians while trying -to estimate @cpi{}!) - -In fact, since the field of lines is infinite we can choose the -coordinates 0 and 1 for the lines on either side of the leftmost -endpoint. The rightmost endpoint will be between 0 and 1 if the -match does not cross a line, or between 1 and 2 if it does. So: -Pick random @expr{x} and -@texline @math{\theta}, -@infoline @expr{theta}, -compute -@texline @math{x + \cos \theta}, -@infoline @expr{x + cos(theta)}, -and count how many of the results are greater than one. Simple! - -We can make this go a bit faster by using the @kbd{v .} and @kbd{t .} -commands. - -@smallexample -@group -1: [0.52, 0.71, ..., 0.72] 2: [0.52, 0.71, ..., 0.72] - . 1: [78.4, 64.5, ..., -42.9] - . - -v . t . 1. v b 100 @key{RET} V M k r 180. v b 100 @key{RET} V M k r 90 - -@end group -@end smallexample - -@noindent -(The next step may be slow, depending on the speed of your computer.) - -@smallexample -@group -2: [0.52, 0.71, ..., 0.72] 1: [0.72, 1.14, ..., 1.45] -1: [0.20, 0.43, ..., 0.73] . - . - - m d V M C + - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0, 1, ..., 1] 1: 0.64 1: 3.125 - . . . - - 1 V M a > V R + 100 / 2 @key{TAB} / -@end group -@end smallexample - -Let's try the third method, too. We'll use random integers up to -one million. The @kbd{k r} command with an integer argument picks -a random integer. - -@smallexample -@group -2: [1000000, 1000000, ..., 1000000] 2: [78489, 527587, ..., 814975] -1: [1000000, 1000000, ..., 1000000] 1: [324014, 358783, ..., 955450] - . . - - 1000000 v b 100 @key{RET} @key{RET} V M k r @key{TAB} V M k r - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [1, 1, ..., 25] 1: [1, 1, ..., 0] 1: 0.56 - . . . - - V M k g 1 V M a = V R + 100 / - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 10.714 1: 3.273 - . . - - 6 @key{TAB} / Q -@end group -@end smallexample - -For a proof of this property of the GCD function, see section 4.5.2, -exercise 10, of Knuth's @emph{Art of Computer Programming}, volume II. - -If you typed @kbd{v .} and @kbd{t .} before, type them again to -return to full-sized display of vectors. - -@node List Answer 13, List Answer 14, List Answer 12, Answers to Exercises -@subsection List Tutorial Exercise 13 - -@noindent -First, we put the string on the stack as a vector of ASCII codes. - -@smallexample -@group -1: [84, 101, 115, ..., 51] - . - - "Testing, 1, 2, 3 @key{RET} -@end group -@end smallexample - -@noindent -Note that the @kbd{"} key, like @kbd{$}, initiates algebraic entry so -there was no need to type an apostrophe. Also, Calc didn't mind that -we omitted the closing @kbd{"}. (The same goes for all closing delimiters -like @kbd{)} and @kbd{]} at the end of a formula. - -We'll show two different approaches here. In the first, we note that -if the input vector is @expr{[a, b, c, d]}, then the hash code is -@expr{3 (3 (3a + b) + c) + d = 27a + 9b + 3c + d}. In other words, -it's a sum of descending powers of three times the ASCII codes. - -@smallexample -@group -2: [84, 101, 115, ..., 51] 2: [84, 101, 115, ..., 51] -1: 16 1: [15, 14, 13, ..., 0] - . . - - @key{RET} v l v x 16 @key{RET} - - -@end group -@end smallexample -@noindent -@smallexample -@group -2: [84, 101, 115, ..., 51] 1: 1960915098 1: 121 -1: [14348907, ..., 1] . . - . - - 3 @key{TAB} V M ^ * 511 % -@end group -@end smallexample - -@noindent -Once again, @kbd{*} elegantly summarizes most of the computation. -But there's an even more elegant approach: Reduce the formula -@kbd{3 $$ + $} across the vector. Recall that this represents a -function of two arguments that computes its first argument times three -plus its second argument. - -@smallexample -@group -1: [84, 101, 115, ..., 51] 1: 1960915098 - . . - - "Testing, 1, 2, 3 @key{RET} V R ' 3$$+$ @key{RET} -@end group -@end smallexample - -@noindent -If you did the decimal arithmetic exercise, this will be familiar. -Basically, we're turning a base-3 vector of digits into an integer, -except that our ``digits'' are much larger than real digits. - -Instead of typing @kbd{511 %} again to reduce the result, we can be -cleverer still and notice that rather than computing a huge integer -and taking the modulo at the end, we can take the modulo at each step -without affecting the result. While this means there are more -arithmetic operations, the numbers we operate on remain small so -the operations are faster. - -@smallexample -@group -1: [84, 101, 115, ..., 51] 1: 121 - . . - - "Testing, 1, 2, 3 @key{RET} V R ' (3$$+$)%511 @key{RET} -@end group -@end smallexample - -Why does this work? Think about a two-step computation: -@w{@expr{3 (3a + b) + c}}. Taking a result modulo 511 basically means -subtracting off enough 511's to put the result in the desired range. -So the result when we take the modulo after every step is, - -@ifnottex -@example -3 (3 a + b - 511 m) + c - 511 n -@end example -@end ifnottex -@tex -\beforedisplay -$$ 3 (3 a + b - 511 m) + c - 511 n $$ -\afterdisplay -@end tex - -@noindent -for some suitable integers @expr{m} and @expr{n}. Expanding out by -the distributive law yields - -@ifnottex -@example -9 a + 3 b + c - 511*3 m - 511 n -@end example -@end ifnottex -@tex -\beforedisplay -$$ 9 a + 3 b + c - 511\times3 m - 511 n $$ -\afterdisplay -@end tex - -@noindent -The @expr{m} term in the latter formula is redundant because any -contribution it makes could just as easily be made by the @expr{n} -term. So we can take it out to get an equivalent formula with -@expr{n' = 3m + n}, - -@ifnottex -@example -9 a + 3 b + c - 511 n' -@end example -@end ifnottex -@tex -\beforedisplay -$$ 9 a + 3 b + c - 511 n^{\prime} $$ -\afterdisplay -@end tex - -@noindent -which is just the formula for taking the modulo only at the end of -the calculation. Therefore the two methods are essentially the same. - -Later in the tutorial we will encounter @dfn{modulo forms}, which -basically automate the idea of reducing every intermediate result -modulo some value @var{m}. - -@node List Answer 14, Types Answer 1, List Answer 13, Answers to Exercises -@subsection List Tutorial Exercise 14 - -We want to use @kbd{H V U} to nest a function which adds a random -step to an @expr{(x,y)} coordinate. The function is a bit long, but -otherwise the problem is quite straightforward. - -@smallexample -@group -2: [0, 0] 1: [ [ 0, 0 ] -1: 50 [ 0.4288, -0.1695 ] - . [ -0.4787, -0.9027 ] - ... - - [0,0] 50 H V U ' <# + [random(2.0)-1, random(2.0)-1]> @key{RET} -@end group -@end smallexample - -Just as the text recommended, we used @samp{< >} nameless function -notation to keep the two @code{random} calls from being evaluated -before nesting even begins. - -We now have a vector of @expr{[x, y]} sub-vectors, which by Calc's -rules acts like a matrix. We can transpose this matrix and unpack -to get a pair of vectors, @expr{x} and @expr{y}, suitable for graphing. - -@smallexample -@group -2: [ 0, 0.4288, -0.4787, ... ] -1: [ 0, -0.1696, -0.9027, ... ] - . - - v t v u g f -@end group -@end smallexample - -Incidentally, because the @expr{x} and @expr{y} are completely -independent in this case, we could have done two separate commands -to create our @expr{x} and @expr{y} vectors of numbers directly. - -To make a random walk of unit steps, we note that @code{sincos} of -a random direction exactly gives us an @expr{[x, y]} step of unit -length; in fact, the new nesting function is even briefer, though -we might want to lower the precision a bit for it. - -@smallexample -@group -2: [0, 0] 1: [ [ 0, 0 ] -1: 50 [ 0.1318, 0.9912 ] - . [ -0.5965, 0.3061 ] - ... - - [0,0] 50 m d p 6 @key{RET} H V U ' <# + sincos(random(360.0))> @key{RET} -@end group -@end smallexample - -Another @kbd{v t v u g f} sequence will graph this new random walk. - -An interesting twist on these random walk functions would be to use -complex numbers instead of 2-vectors to represent points on the plane. -In the first example, we'd use something like @samp{random + random*(0,1)}, -and in the second we could use polar complex numbers with random phase -angles. (This exercise was first suggested in this form by Randal -Schwartz.) - -@node Types Answer 1, Types Answer 2, List Answer 14, Answers to Exercises -@subsection Types Tutorial Exercise 1 - -@noindent -If the number is the square root of @cpi{} times a rational number, -then its square, divided by @cpi{}, should be a rational number. - -@smallexample -@group -1: 1.26508260337 1: 0.509433962268 1: 2486645810:4881193627 - . . . - - 2 ^ P / c F -@end group -@end smallexample - -@noindent -Technically speaking this is a rational number, but not one that is -likely to have arisen in the original problem. More likely, it just -happens to be the fraction which most closely represents some -irrational number to within 12 digits. - -But perhaps our result was not quite exact. Let's reduce the -precision slightly and try again: - -@smallexample -@group -1: 0.509433962268 1: 27:53 - . . - - U p 10 @key{RET} c F -@end group -@end smallexample - -@noindent -Aha! It's unlikely that an irrational number would equal a fraction -this simple to within ten digits, so our original number was probably -@texline @math{\sqrt{27 \pi / 53}}. -@infoline @expr{sqrt(27 pi / 53)}. - -Notice that we didn't need to re-round the number when we reduced the -precision. Remember, arithmetic operations always round their inputs -to the current precision before they begin. - -@node Types Answer 2, Types Answer 3, Types Answer 1, Answers to Exercises -@subsection Types Tutorial Exercise 2 - -@noindent -@samp{inf / inf = nan}. Perhaps @samp{1} is the ``obvious'' answer. -But if @w{@samp{17 inf = inf}}, then @samp{17 inf / inf = inf / inf = 17}, too. - -@samp{exp(inf) = inf}. It's tempting to say that the exponential -of infinity must be ``bigger'' than ``regular'' infinity, but as -far as Calc is concerned all infinities are the same size. -In other words, as @expr{x} goes to infinity, @expr{e^x} also goes -to infinity, but the fact the @expr{e^x} grows much faster than -@expr{x} is not relevant here. - -@samp{exp(-inf) = 0}. Here we have a finite answer even though -the input is infinite. - -@samp{sqrt(-inf) = (0, 1) inf}. Remember that @expr{(0, 1)} -represents the imaginary number @expr{i}. Here's a derivation: -@samp{sqrt(-inf) = @w{sqrt((-1) * inf)} = sqrt(-1) * sqrt(inf)}. -The first part is, by definition, @expr{i}; the second is @code{inf} -because, once again, all infinities are the same size. - -@samp{sqrt(uinf) = uinf}. In fact, we do know something about the -direction because @code{sqrt} is defined to return a value in the -right half of the complex plane. But Calc has no notation for this, -so it settles for the conservative answer @code{uinf}. - -@samp{abs(uinf) = inf}. No matter which direction @expr{x} points, -@samp{abs(x)} always points along the positive real axis. - -@samp{ln(0) = -inf}. Here we have an infinite answer to a finite -input. As in the @expr{1 / 0} case, Calc will only use infinities -here if you have turned on Infinite mode. Otherwise, it will -treat @samp{ln(0)} as an error. - -@node Types Answer 3, Types Answer 4, Types Answer 2, Answers to Exercises -@subsection Types Tutorial Exercise 3 - -@noindent -We can make @samp{inf - inf} be any real number we like, say, -@expr{a}, just by claiming that we added @expr{a} to the first -infinity but not to the second. This is just as true for complex -values of @expr{a}, so @code{nan} can stand for a complex number. -(And, similarly, @code{uinf} can stand for an infinity that points -in any direction in the complex plane, such as @samp{(0, 1) inf}). - -In fact, we can multiply the first @code{inf} by two. Surely -@w{@samp{2 inf - inf = inf}}, but also @samp{2 inf - inf = inf - inf = nan}. -So @code{nan} can even stand for infinity. Obviously it's just -as easy to make it stand for minus infinity as for plus infinity. - -The moral of this story is that ``infinity'' is a slippery fish -indeed, and Calc tries to handle it by having a very simple model -for infinities (only the direction counts, not the ``size''); but -Calc is careful to write @code{nan} any time this simple model is -unable to tell what the true answer is. - -@node Types Answer 4, Types Answer 5, Types Answer 3, Answers to Exercises -@subsection Types Tutorial Exercise 4 - -@smallexample -@group -2: 0@@ 47' 26" 1: 0@@ 2' 47.411765" -1: 17 . - . - - 0@@ 47' 26" @key{RET} 17 / -@end group -@end smallexample - -@noindent -The average song length is two minutes and 47.4 seconds. - -@smallexample -@group -2: 0@@ 2' 47.411765" 1: 0@@ 3' 7.411765" 1: 0@@ 53' 6.000005" -1: 0@@ 0' 20" . . - . - - 20" + 17 * -@end group -@end smallexample - -@noindent -The album would be 53 minutes and 6 seconds long. - -@node Types Answer 5, Types Answer 6, Types Answer 4, Answers to Exercises -@subsection Types Tutorial Exercise 5 - -@noindent -Let's suppose it's January 14, 1991. The easiest thing to do is -to keep trying 13ths of months until Calc reports a Friday. -We can do this by manually entering dates, or by using @kbd{t I}: - -@smallexample -@group -1: 1: 1: - . . . - - ' <2/13> @key{RET} @key{DEL} ' <3/13> @key{RET} t I -@end group -@end smallexample - -@noindent -(Calc assumes the current year if you don't say otherwise.) - -This is getting tedious---we can keep advancing the date by typing -@kbd{t I} over and over again, but let's automate the job by using -vector mapping. The @kbd{t I} command actually takes a second -``how-many-months'' argument, which defaults to one. This -argument is exactly what we want to map over: - -@smallexample -@group -2: 1: [, , -1: [1, 2, 3, 4, 5, 6] , , - . , ] - . - - v x 6 @key{RET} V M t I -@end group -@end smallexample - -@noindent -Et voil@`a, September 13, 1991 is a Friday. - -@smallexample -@group -1: 242 - . - -' - @key{RET} -@end group -@end smallexample - -@noindent -And the answer to our original question: 242 days to go. - -@node Types Answer 6, Types Answer 7, Types Answer 5, Answers to Exercises -@subsection Types Tutorial Exercise 6 - -@noindent -The full rule for leap years is that they occur in every year divisible -by four, except that they don't occur in years divisible by 100, except -that they @emph{do} in years divisible by 400. We could work out the -answer by carefully counting the years divisible by four and the -exceptions, but there is a much simpler way that works even if we -don't know the leap year rule. - -Let's assume the present year is 1991. Years have 365 days, except -that leap years (whenever they occur) have 366 days. So let's count -the number of days between now and then, and compare that to the -number of years times 365. The number of extra days we find must be -equal to the number of leap years there were. - -@smallexample -@group -1: 2: 1: 2925593 - . 1: . - . - - ' @key{RET} ' @key{RET} - - -@end group -@end smallexample -@noindent -@smallexample -@group -3: 2925593 2: 2925593 2: 2925593 1: 1943 -2: 10001 1: 8010 1: 2923650 . -1: 1991 . . - . - - 10001 @key{RET} 1991 - 365 * - -@end group -@end smallexample - -@c [fix-ref Date Forms] -@noindent -There will be 1943 leap years before the year 10001. (Assuming, -of course, that the algorithm for computing leap years remains -unchanged for that long. @xref{Date Forms}, for some interesting -background information in that regard.) - -@node Types Answer 7, Types Answer 8, Types Answer 6, Answers to Exercises -@subsection Types Tutorial Exercise 7 - -@noindent -The relative errors must be converted to absolute errors so that -@samp{+/-} notation may be used. - -@smallexample -@group -1: 1. 2: 1. - . 1: 0.2 - . - - 20 @key{RET} .05 * 4 @key{RET} .05 * -@end group -@end smallexample - -Now we simply chug through the formula. - -@smallexample -@group -1: 19.7392088022 1: 394.78 +/- 19.739 1: 6316.5 +/- 706.21 - . . . - - 2 P 2 ^ * 20 p 1 * 4 p .2 @key{RET} 2 ^ * -@end group -@end smallexample - -It turns out the @kbd{v u} command will unpack an error form as -well as a vector. This saves us some retyping of numbers. - -@smallexample -@group -3: 6316.5 +/- 706.21 2: 6316.5 +/- 706.21 -2: 6316.5 1: 0.1118 -1: 706.21 . - . - - @key{RET} v u @key{TAB} / -@end group -@end smallexample - -@noindent -Thus the volume is 6316 cubic centimeters, within about 11 percent. - -@node Types Answer 8, Types Answer 9, Types Answer 7, Answers to Exercises -@subsection Types Tutorial Exercise 8 - -@noindent -The first answer is pretty simple: @samp{1 / (0 .. 10) = (0.1 .. inf)}. -Since a number in the interval @samp{(0 .. 10)} can get arbitrarily -close to zero, its reciprocal can get arbitrarily large, so the answer -is an interval that effectively means, ``any number greater than 0.1'' -but with no upper bound. - -The second answer, similarly, is @samp{1 / (-10 .. 0) = (-inf .. -0.1)}. - -Calc normally treats division by zero as an error, so that the formula -@w{@samp{1 / 0}} is left unsimplified. Our third problem, -@w{@samp{1 / [0 .. 10]}}, also (potentially) divides by zero because zero -is now a member of the interval. So Calc leaves this one unevaluated, too. - -If you turn on Infinite mode by pressing @kbd{m i}, you will -instead get the answer @samp{[0.1 .. inf]}, which includes infinity -as a possible value. - -The fourth calculation, @samp{1 / (-10 .. 10)}, has the same problem. -Zero is buried inside the interval, but it's still a possible value. -It's not hard to see that the actual result of @samp{1 / (-10 .. 10)} -will be either greater than @mathit{0.1}, or less than @mathit{-0.1}. Thus -the interval goes from minus infinity to plus infinity, with a ``hole'' -in it from @mathit{-0.1} to @mathit{0.1}. Calc doesn't have any way to -represent this, so it just reports @samp{[-inf .. inf]} as the answer. -It may be disappointing to hear ``the answer lies somewhere between -minus infinity and plus infinity, inclusive,'' but that's the best -that interval arithmetic can do in this case. - -@node Types Answer 9, Types Answer 10, Types Answer 8, Answers to Exercises -@subsection Types Tutorial Exercise 9 - -@smallexample -@group -1: [-3 .. 3] 2: [-3 .. 3] 2: [0 .. 9] - . 1: [0 .. 9] 1: [-9 .. 9] - . . - - [ 3 n .. 3 ] @key{RET} 2 ^ @key{TAB} @key{RET} * -@end group -@end smallexample - -@noindent -In the first case the result says, ``if a number is between @mathit{-3} and -3, its square is between 0 and 9.'' The second case says, ``the product -of two numbers each between @mathit{-3} and 3 is between @mathit{-9} and 9.'' - -An interval form is not a number; it is a symbol that can stand for -many different numbers. Two identical-looking interval forms can stand -for different numbers. - -The same issue arises when you try to square an error form. - -@node Types Answer 10, Types Answer 11, Types Answer 9, Answers to Exercises -@subsection Types Tutorial Exercise 10 - -@noindent -Testing the first number, we might arbitrarily choose 17 for @expr{x}. - -@smallexample -@group -1: 17 mod 811749613 2: 17 mod 811749613 1: 533694123 mod 811749613 - . 811749612 . - . - - 17 M 811749613 @key{RET} 811749612 ^ -@end group -@end smallexample - -@noindent -Since 533694123 is (considerably) different from 1, the number 811749613 -must not be prime. - -It's awkward to type the number in twice as we did above. There are -various ways to avoid this, and algebraic entry is one. In fact, using -a vector mapping operation we can perform several tests at once. Let's -use this method to test the second number. - -@smallexample -@group -2: [17, 42, 100000] 1: [1 mod 15485863, 1 mod ... ] -1: 15485863 . - . - - [17 42 100000] 15485863 @key{RET} V M ' ($$ mod $)^($-1) @key{RET} -@end group -@end smallexample - -@noindent -The result is three ones (modulo @expr{n}), so it's very probable that -15485863 is prime. (In fact, this number is the millionth prime.) - -Note that the functions @samp{($$^($-1)) mod $} or @samp{$$^($-1) % $} -would have been hopelessly inefficient, since they would have calculated -the power using full integer arithmetic. - -Calc has a @kbd{k p} command that does primality testing. For small -numbers it does an exact test; for large numbers it uses a variant -of the Fermat test we used here. You can use @kbd{k p} repeatedly -to prove that a large integer is prime with any desired probability. - -@node Types Answer 11, Types Answer 12, Types Answer 10, Answers to Exercises -@subsection Types Tutorial Exercise 11 - -@noindent -There are several ways to insert a calculated number into an HMS form. -One way to convert a number of seconds to an HMS form is simply to -multiply the number by an HMS form representing one second: - -@smallexample -@group -1: 31415926.5359 2: 31415926.5359 1: 8726@@ 38' 46.5359" - . 1: 0@@ 0' 1" . - . - - P 1e7 * 0@@ 0' 1" * - -@end group -@end smallexample -@noindent -@smallexample -@group -2: 8726@@ 38' 46.5359" 1: 6@@ 6' 2.5359" mod 24@@ 0' 0" -1: 15@@ 27' 16" mod 24@@ 0' 0" . - . - - x time @key{RET} + -@end group -@end smallexample - -@noindent -It will be just after six in the morning. - -The algebraic @code{hms} function can also be used to build an -HMS form: - -@smallexample -@group -1: hms(0, 0, 10000000. pi) 1: 8726@@ 38' 46.5359" - . . - - ' hms(0, 0, 1e7 pi) @key{RET} = -@end group -@end smallexample - -@noindent -The @kbd{=} key is necessary to evaluate the symbol @samp{pi} to -the actual number 3.14159... - -@node Types Answer 12, Types Answer 13, Types Answer 11, Answers to Exercises -@subsection Types Tutorial Exercise 12 - -@noindent -As we recall, there are 17 songs of about 2 minutes and 47 seconds -each. - -@smallexample -@group -2: 0@@ 2' 47" 1: [0@@ 3' 7" .. 0@@ 3' 47"] -1: [0@@ 0' 20" .. 0@@ 1' 0"] . - . - - [ 0@@ 20" .. 0@@ 1' ] + - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0@@ 52' 59." .. 1@@ 4' 19."] - . - - 17 * -@end group -@end smallexample - -@noindent -No matter how long it is, the album will fit nicely on one CD. - -@node Types Answer 13, Types Answer 14, Types Answer 12, Answers to Exercises -@subsection Types Tutorial Exercise 13 - -@noindent -Type @kbd{' 1 yr @key{RET} u c s @key{RET}}. The answer is 31557600 seconds. - -@node Types Answer 14, Types Answer 15, Types Answer 13, Answers to Exercises -@subsection Types Tutorial Exercise 14 - -@noindent -How long will it take for a signal to get from one end of the computer -to the other? - -@smallexample -@group -1: m / c 1: 3.3356 ns - . . - - ' 1 m / c @key{RET} u c ns @key{RET} -@end group -@end smallexample - -@noindent -(Recall, @samp{c} is a ``unit'' corresponding to the speed of light.) - -@smallexample -@group -1: 3.3356 ns 1: 0.81356 ns / ns 1: 0.81356 -2: 4.1 ns . . - . - - ' 4.1 ns @key{RET} / u s -@end group -@end smallexample - -@noindent -Thus a signal could take up to 81 percent of a clock cycle just to -go from one place to another inside the computer, assuming the signal -could actually attain the full speed of light. Pretty tight! - -@node Types Answer 15, Algebra Answer 1, Types Answer 14, Answers to Exercises -@subsection Types Tutorial Exercise 15 - -@noindent -The speed limit is 55 miles per hour on most highways. We want to -find the ratio of Sam's speed to the US speed limit. - -@smallexample -@group -1: 55 mph 2: 55 mph 3: 11 hr mph / yd - . 1: 5 yd / hr . - . - - ' 55 mph @key{RET} ' 5 yd/hr @key{RET} / -@end group -@end smallexample - -The @kbd{u s} command cancels out these units to get a plain -number. Now we take the logarithm base two to find the final -answer, assuming that each successive pill doubles his speed. - -@smallexample -@group -1: 19360. 2: 19360. 1: 14.24 - . 1: 2 . - . - - u s 2 B -@end group -@end smallexample - -@noindent -Thus Sam can take up to 14 pills without a worry. - -@node Algebra Answer 1, Algebra Answer 2, Types Answer 15, Answers to Exercises -@subsection Algebra Tutorial Exercise 1 - -@noindent -@c [fix-ref Declarations] -The result @samp{sqrt(x)^2} is simplified back to @expr{x} by the -Calculator, but @samp{sqrt(x^2)} is not. (Consider what happens -if @w{@expr{x = -4}}.) If @expr{x} is real, this formula could be -simplified to @samp{abs(x)}, but for general complex arguments even -that is not safe. (@xref{Declarations}, for a way to tell Calc -that @expr{x} is known to be real.) - -@node Algebra Answer 2, Algebra Answer 3, Algebra Answer 1, Answers to Exercises -@subsection Algebra Tutorial Exercise 2 - -@noindent -Suppose our roots are @expr{[a, b, c]}. We want a polynomial which -is zero when @expr{x} is any of these values. The trivial polynomial -@expr{x-a} is zero when @expr{x=a}, so the product @expr{(x-a)(x-b)(x-c)} -will do the job. We can use @kbd{a c x} to write this in a more -familiar form. - -@smallexample -@group -1: 34 x - 24 x^3 1: [1.19023, -1.19023, 0] - . . - - r 2 a P x @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [x - 1.19023, x + 1.19023, x] 1: (x - 1.19023) (x + 1.19023) x - . . - - V M ' x-$ @key{RET} V R * - -@end group -@end smallexample -@noindent -@smallexample -@group -1: x^3 - 1.41666 x 1: 34 x - 24 x^3 - . . - - a c x @key{RET} 24 n * a x -@end group -@end smallexample - -@noindent -Sure enough, our answer (multiplied by a suitable constant) is the -same as the original polynomial. - -@node Algebra Answer 3, Algebra Answer 4, Algebra Answer 2, Answers to Exercises -@subsection Algebra Tutorial Exercise 3 - -@smallexample -@group -1: x sin(pi x) 1: (sin(pi x) - pi x cos(pi x)) / pi^2 - . . - - ' x sin(pi x) @key{RET} m r a i x @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [y, 1] -2: (sin(pi x) - pi x cos(pi x)) / pi^2 - . - - ' [y,1] @key{RET} @key{TAB} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [(sin(pi y) - pi y cos(pi y)) / pi^2, (sin(pi) - pi cos(pi)) / pi^2] - . - - V M $ @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: (sin(pi y) - pi y cos(pi y)) / pi^2 + (pi cos(pi) - sin(pi)) / pi^2 - . - - V R - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: (sin(3.14159 y) - 3.14159 y cos(3.14159 y)) / 9.8696 - 0.3183 - . - - = - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0., -0.95493, 0.63662, -1.5915, 1.2732] - . - - v x 5 @key{RET} @key{TAB} V M $ @key{RET} -@end group -@end smallexample - -@node Algebra Answer 4, Rewrites Answer 1, Algebra Answer 3, Answers to Exercises -@subsection Algebra Tutorial Exercise 4 - -@noindent -The hard part is that @kbd{V R +} is no longer sufficient to add up all -the contributions from the slices, since the slices have varying -coefficients. So first we must come up with a vector of these -coefficients. Here's one way: - -@smallexample -@group -2: -1 2: 3 1: [4, 2, ..., 4] -1: [1, 2, ..., 9] 1: [-1, 1, ..., -1] . - . . - - 1 n v x 9 @key{RET} V M ^ 3 @key{TAB} - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [4, 2, ..., 4, 1] 1: [1, 4, 2, ..., 4, 1] - . . - - 1 | 1 @key{TAB} | -@end group -@end smallexample - -@noindent -Now we compute the function values. Note that for this method we need -eleven values, including both endpoints of the desired interval. - -@smallexample -@group -2: [1, 4, 2, ..., 4, 1] -1: [1, 1.1, 1.2, ... , 1.8, 1.9, 2.] - . - - 11 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x - -@end group -@end smallexample -@noindent -@smallexample -@group -2: [1, 4, 2, ..., 4, 1] -1: [0., 0.084941, 0.16993, ... ] - . - - ' sin(x) ln(x) @key{RET} m r p 5 @key{RET} V M $ @key{RET} -@end group -@end smallexample - -@noindent -Once again this calls for @kbd{V M * V R +}; a simple @kbd{*} does the -same thing. - -@smallexample -@group -1: 11.22 1: 1.122 1: 0.374 - . . . - - * .1 * 3 / -@end group -@end smallexample - -@noindent -Wow! That's even better than the result from the Taylor series method. - -@node Rewrites Answer 1, Rewrites Answer 2, Algebra Answer 4, Answers to Exercises -@subsection Rewrites Tutorial Exercise 1 - -@noindent -We'll use Big mode to make the formulas more readable. - -@smallexample -@group - ___ - 2 + V 2 -1: (2 + sqrt(2)) / (1 + sqrt(2)) 1: -------- - . ___ - 1 + V 2 - - . - - ' (2+sqrt(2)) / (1+sqrt(2)) @key{RET} d B -@end group -@end smallexample - -@noindent -Multiplying by the conjugate helps because @expr{(a+b) (a-b) = a^2 - b^2}. - -@smallexample -@group - ___ ___ -1: (2 + V 2 ) (V 2 - 1) - . - - a r a/(b+c) := a*(b-c) / (b^2-c^2) @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group - ___ ___ -1: 2 + V 2 - 2 1: V 2 - . . - - a r a*(b+c) := a*b + a*c a s -@end group -@end smallexample - -@noindent -(We could have used @kbd{a x} instead of a rewrite rule for the -second step.) - -The multiply-by-conjugate rule turns out to be useful in many -different circumstances, such as when the denominator involves -sines and cosines or the imaginary constant @code{i}. - -@node Rewrites Answer 2, Rewrites Answer 3, Rewrites Answer 1, Answers to Exercises -@subsection Rewrites Tutorial Exercise 2 - -@noindent -Here is the rule set: - -@smallexample -@group -[ fib(n) := fib(n, 1, 1) :: integer(n) :: n >= 1, - fib(1, x, y) := x, - fib(n, x, y) := fib(n-1, y, x+y) ] -@end group -@end smallexample - -@noindent -The first rule turns a one-argument @code{fib} that people like to write -into a three-argument @code{fib} that makes computation easier. The -second rule converts back from three-argument form once the computation -is done. The third rule does the computation itself. It basically -says that if @expr{x} and @expr{y} are two consecutive Fibonacci numbers, -then @expr{y} and @expr{x+y} are the next (overlapping) pair of Fibonacci -numbers. - -Notice that because the number @expr{n} was ``validated'' by the -conditions on the first rule, there is no need to put conditions on -the other rules because the rule set would never get that far unless -the input were valid. That further speeds computation, since no -extra conditions need to be checked at every step. - -Actually, a user with a nasty sense of humor could enter a bad -three-argument @code{fib} call directly, say, @samp{fib(0, 1, 1)}, -which would get the rules into an infinite loop. One thing that would -help keep this from happening by accident would be to use something like -@samp{ZzFib} instead of @code{fib} as the name of the three-argument -function. - -@node Rewrites Answer 3, Rewrites Answer 4, Rewrites Answer 2, Answers to Exercises -@subsection Rewrites Tutorial Exercise 3 - -@noindent -He got an infinite loop. First, Calc did as expected and rewrote -@w{@samp{2 + 3 x}} to @samp{f(2, 3, x)}. Then it looked for ways to -apply the rule again, and found that @samp{f(2, 3, x)} looks like -@samp{a + b x} with @w{@samp{a = 0}} and @samp{b = 1}, so it rewrote to -@samp{f(0, 1, f(2, 3, x))}. It then wrapped another @samp{f(0, 1, ...)} -around that, and so on, ad infinitum. Joe should have used @kbd{M-1 a r} -to make sure the rule applied only once. - -(Actually, even the first step didn't work as he expected. What Calc -really gives for @kbd{M-1 a r} in this situation is @samp{f(3 x, 1, 2)}, -treating 2 as the ``variable,'' and @samp{3 x} as a constant being added -to it. While this may seem odd, it's just as valid a solution as the -``obvious'' one. One way to fix this would be to add the condition -@samp{:: variable(x)} to the rule, to make sure the thing that matches -@samp{x} is indeed a variable, or to change @samp{x} to @samp{quote(x)} -on the lefthand side, so that the rule matches the actual variable -@samp{x} rather than letting @samp{x} stand for something else.) - -@node Rewrites Answer 4, Rewrites Answer 5, Rewrites Answer 3, Answers to Exercises -@subsection Rewrites Tutorial Exercise 4 - -@noindent -@ignore -@starindex -@end ignore -@tindex seq -Here is a suitable set of rules to solve the first part of the problem: - -@smallexample -@group -[ seq(n, c) := seq(n/2, c+1) :: n%2 = 0, - seq(n, c) := seq(3n+1, c+1) :: n%2 = 1 :: n > 1 ] -@end group -@end smallexample - -Given the initial formula @samp{seq(6, 0)}, application of these -rules produces the following sequence of formulas: - -@example -seq( 3, 1) -seq(10, 2) -seq( 5, 3) -seq(16, 4) -seq( 8, 5) -seq( 4, 6) -seq( 2, 7) -seq( 1, 8) -@end example - -@noindent -whereupon neither of the rules match, and rewriting stops. - -We can pretty this up a bit with a couple more rules: - -@smallexample -@group -[ seq(n) := seq(n, 0), - seq(1, c) := c, - ... ] -@end group -@end smallexample - -@noindent -Now, given @samp{seq(6)} as the starting configuration, we get 8 -as the result. - -The change to return a vector is quite simple: - -@smallexample -@group -[ seq(n) := seq(n, []) :: integer(n) :: n > 0, - seq(1, v) := v | 1, - seq(n, v) := seq(n/2, v | n) :: n%2 = 0, - seq(n, v) := seq(3n+1, v | n) :: n%2 = 1 ] -@end group -@end smallexample - -@noindent -Given @samp{seq(6)}, the result is @samp{[6, 3, 10, 5, 16, 8, 4, 2, 1]}. - -Notice that the @expr{n > 1} guard is no longer necessary on the last -rule since the @expr{n = 1} case is now detected by another rule. -But a guard has been added to the initial rule to make sure the -initial value is suitable before the computation begins. - -While still a good idea, this guard is not as vitally important as it -was for the @code{fib} function, since calling, say, @samp{seq(x, [])} -will not get into an infinite loop. Calc will not be able to prove -the symbol @samp{x} is either even or odd, so none of the rules will -apply and the rewrites will stop right away. - -@node Rewrites Answer 5, Rewrites Answer 6, Rewrites Answer 4, Answers to Exercises -@subsection Rewrites Tutorial Exercise 5 - -@noindent -@ignore -@starindex -@end ignore -@tindex nterms -If @expr{x} is the sum @expr{a + b}, then `@tfn{nterms(}@var{x}@tfn{)}' must -be `@tfn{nterms(}@var{a}@tfn{)}' plus `@tfn{nterms(}@var{b}@tfn{)}'. If @expr{x} -is not a sum, then `@tfn{nterms(}@var{x}@tfn{)}' = 1. - -@smallexample -@group -[ nterms(a + b) := nterms(a) + nterms(b), - nterms(x) := 1 ] -@end group -@end smallexample - -@noindent -Here we have taken advantage of the fact that earlier rules always -match before later rules; @samp{nterms(x)} will only be tried if we -already know that @samp{x} is not a sum. - -@node Rewrites Answer 6, Programming Answer 1, Rewrites Answer 5, Answers to Exercises -@subsection Rewrites Tutorial Exercise 6 - -@noindent -Here is a rule set that will do the job: - -@smallexample -@group -[ a*(b + c) := a*b + a*c, - opt(a) O(x^n) + opt(b) O(x^m) := O(x^n) :: n <= m - :: constant(a) :: constant(b), - opt(a) O(x^n) + opt(b) x^m := O(x^n) :: n <= m - :: constant(a) :: constant(b), - a O(x^n) := O(x^n) :: constant(a), - x^opt(m) O(x^n) := O(x^(n+m)), - O(x^n) O(x^m) := O(x^(n+m)) ] -@end group -@end smallexample - -If we really want the @kbd{+} and @kbd{*} keys to operate naturally -on power series, we should put these rules in @code{EvalRules}. For -testing purposes, it is better to put them in a different variable, -say, @code{O}, first. - -The first rule just expands products of sums so that the rest of the -rules can assume they have an expanded-out polynomial to work with. -Note that this rule does not mention @samp{O} at all, so it will -apply to any product-of-sum it encounters---this rule may surprise -you if you put it into @code{EvalRules}! - -In the second rule, the sum of two O's is changed to the smaller O. -The optional constant coefficients are there mostly so that -@samp{O(x^2) - O(x^3)} and @samp{O(x^3) - O(x^2)} are handled -as well as @samp{O(x^2) + O(x^3)}. - -The third rule absorbs higher powers of @samp{x} into O's. - -The fourth rule says that a constant times a negligible quantity -is still negligible. (This rule will also match @samp{O(x^3) / 4}, -with @samp{a = 1/4}.) - -The fifth rule rewrites, for example, @samp{x^2 O(x^3)} to @samp{O(x^5)}. -(It is easy to see that if one of these forms is negligible, the other -is, too.) Notice the @samp{x^opt(m)} to pick up terms like -@w{@samp{x O(x^3)}}. Optional powers will match @samp{x} as @samp{x^1} -but not 1 as @samp{x^0}. This turns out to be exactly what we want here. - -The sixth rule is the corresponding rule for products of two O's. - -Another way to solve this problem would be to create a new ``data type'' -that represents truncated power series. We might represent these as -function calls @samp{series(@var{coefs}, @var{x})} where @var{coefs} is -a vector of coefficients for @expr{x^0}, @expr{x^1}, @expr{x^2}, and so -on. Rules would exist for sums and products of such @code{series} -objects, and as an optional convenience could also know how to combine a -@code{series} object with a normal polynomial. (With this, and with a -rule that rewrites @samp{O(x^n)} to the equivalent @code{series} form, -you could still enter power series in exactly the same notation as -before.) Operations on such objects would probably be more efficient, -although the objects would be a bit harder to read. - -@c [fix-ref Compositions] -Some other symbolic math programs provide a power series data type -similar to this. Mathematica, for example, has an object that looks -like @samp{PowerSeries[@var{x}, @var{x0}, @var{coefs}, @var{nmin}, -@var{nmax}, @var{den}]}, where @var{x0} is the point about which the -power series is taken (we've been assuming this was always zero), -and @var{nmin}, @var{nmax}, and @var{den} allow pseudo-power-series -with fractional or negative powers. Also, the @code{PowerSeries} -objects have a special display format that makes them look like -@samp{2 x^2 + O(x^4)} when they are printed out. (@xref{Compositions}, -for a way to do this in Calc, although for something as involved as -this it would probably be better to write the formatting routine -in Lisp.) - -@node Programming Answer 1, Programming Answer 2, Rewrites Answer 6, Answers to Exercises -@subsection Programming Tutorial Exercise 1 - -@noindent -Just enter the formula @samp{ninteg(sin(t)/t, t, 0, x)}, type -@kbd{Z F}, and answer the questions. Since this formula contains two -variables, the default argument list will be @samp{(t x)}. We want to -change this to @samp{(x)} since @expr{t} is really a dummy variable -to be used within @code{ninteg}. - -The exact keystrokes are @kbd{Z F s Si @key{RET} @key{RET} C-b C-b @key{DEL} @key{DEL} @key{RET} y}. -(The @kbd{C-b C-b @key{DEL} @key{DEL}} are what fix the argument list.) - -@node Programming Answer 2, Programming Answer 3, Programming Answer 1, Answers to Exercises -@subsection Programming Tutorial Exercise 2 - -@noindent -One way is to move the number to the top of the stack, operate on -it, then move it back: @kbd{C-x ( M-@key{TAB} n M-@key{TAB} M-@key{TAB} C-x )}. - -Another way is to negate the top three stack entries, then negate -again the top two stack entries: @kbd{C-x ( M-3 n M-2 n C-x )}. - -Finally, it turns out that a negative prefix argument causes a -command like @kbd{n} to operate on the specified stack entry only, -which is just what we want: @kbd{C-x ( M-- 3 n C-x )}. - -Just for kicks, let's also do it algebraically: -@w{@kbd{C-x ( ' -$$$, $$, $ @key{RET} C-x )}}. - -@node Programming Answer 3, Programming Answer 4, Programming Answer 2, Answers to Exercises -@subsection Programming Tutorial Exercise 3 - -@noindent -Each of these functions can be computed using the stack, or using -algebraic entry, whichever way you prefer: - -@noindent -Computing -@texline @math{\displaystyle{\sin x \over x}}: -@infoline @expr{sin(x) / x}: - -Using the stack: @kbd{C-x ( @key{RET} S @key{TAB} / C-x )}. - -Using algebraic entry: @kbd{C-x ( ' sin($)/$ @key{RET} C-x )}. - -@noindent -Computing the logarithm: - -Using the stack: @kbd{C-x ( @key{TAB} B C-x )} - -Using algebraic entry: @kbd{C-x ( ' log($,$$) @key{RET} C-x )}. - -@noindent -Computing the vector of integers: - -Using the stack: @kbd{C-x ( 1 @key{RET} 1 C-u v x C-x )}. (Recall that -@kbd{C-u v x} takes the vector size, starting value, and increment -from the stack.) - -Alternatively: @kbd{C-x ( ~ v x C-x )}. (The @kbd{~} key pops a -number from the stack and uses it as the prefix argument for the -next command.) - -Using algebraic entry: @kbd{C-x ( ' index($) @key{RET} C-x )}. - -@node Programming Answer 4, Programming Answer 5, Programming Answer 3, Answers to Exercises -@subsection Programming Tutorial Exercise 4 - -@noindent -Here's one way: @kbd{C-x ( @key{RET} V R + @key{TAB} v l / C-x )}. - -@node Programming Answer 5, Programming Answer 6, Programming Answer 4, Answers to Exercises -@subsection Programming Tutorial Exercise 5 - -@smallexample -@group -2: 1 1: 1.61803398502 2: 1.61803398502 -1: 20 . 1: 1.61803398875 - . . - - 1 @key{RET} 20 Z < & 1 + Z > I H P -@end group -@end smallexample - -@noindent -This answer is quite accurate. - -@node Programming Answer 6, Programming Answer 7, Programming Answer 5, Answers to Exercises -@subsection Programming Tutorial Exercise 6 - -@noindent -Here is the matrix: - -@example -[ [ 0, 1 ] * [a, b] = [b, a + b] - [ 1, 1 ] ] -@end example - -@noindent -Thus @samp{[0, 1; 1, 1]^n * [1, 1]} computes Fibonacci numbers @expr{n+1} -and @expr{n+2}. Here's one program that does the job: - -@example -C-x ( ' [0, 1; 1, 1] ^ ($-1) * [1, 1] @key{RET} v u @key{DEL} C-x ) -@end example - -@noindent -This program is quite efficient because Calc knows how to raise a -matrix (or other value) to the power @expr{n} in only -@texline @math{\log_2 n} -@infoline @expr{log(n,2)} -steps. For example, this program can compute the 1000th Fibonacci -number (a 209-digit integer!) in about 10 steps; even though the -@kbd{Z < ... Z >} solution had much simpler steps, it would have -required so many steps that it would not have been practical. - -@node Programming Answer 7, Programming Answer 8, Programming Answer 6, Answers to Exercises -@subsection Programming Tutorial Exercise 7 - -@noindent -The trick here is to compute the harmonic numbers differently, so that -the loop counter itself accumulates the sum of reciprocals. We use -a separate variable to hold the integer counter. - -@smallexample -@group -1: 1 2: 1 1: . - . 1: 4 - . - - 1 t 1 1 @key{RET} 4 Z ( t 2 r 1 1 + s 1 & Z ) -@end group -@end smallexample - -@noindent -The body of the loop goes as follows: First save the harmonic sum -so far in variable 2. Then delete it from the stack; the for loop -itself will take care of remembering it for us. Next, recall the -count from variable 1, add one to it, and feed its reciprocal to -the for loop to use as the step value. The for loop will increase -the ``loop counter'' by that amount and keep going until the -loop counter exceeds 4. - -@smallexample -@group -2: 31 3: 31 -1: 3.99498713092 2: 3.99498713092 - . 1: 4.02724519544 - . - - r 1 r 2 @key{RET} 31 & + -@end group -@end smallexample - -Thus we find that the 30th harmonic number is 3.99, and the 31st -harmonic number is 4.02. - -@node Programming Answer 8, Programming Answer 9, Programming Answer 7, Answers to Exercises -@subsection Programming Tutorial Exercise 8 - -@noindent -The first step is to compute the derivative @expr{f'(x)} and thus -the formula -@texline @math{\displaystyle{x - {f(x) \over f'(x)}}}. -@infoline @expr{x - f(x)/f'(x)}. - -(Because this definition is long, it will be repeated in concise form -below. You can use @w{@kbd{C-x * m}} to load it from there. While you are -entering a @kbd{Z ` Z '} body in a macro, Calc simply collects -keystrokes without executing them. In the following diagrams we'll -pretend Calc actually executed the keystrokes as you typed them, -just for purposes of illustration.) - -@smallexample -@group -2: sin(cos(x)) - 0.5 3: 4.5 -1: 4.5 2: sin(cos(x)) - 0.5 - . 1: -(sin(x) cos(cos(x))) - . - -' sin(cos(x))-0.5 @key{RET} 4.5 m r C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -2: 4.5 -1: x + (sin(cos(x)) - 0.5) / sin(x) cos(cos(x)) - . - - / ' x @key{RET} @key{TAB} - t 1 -@end group -@end smallexample - -Now, we enter the loop. We'll use a repeat loop with a 20-repetition -limit just in case the method fails to converge for some reason. -(Normally, the @w{@kbd{Z /}} command will stop the loop before all 20 -repetitions are done.) - -@smallexample -@group -1: 4.5 3: 4.5 2: 4.5 - . 2: x + (sin(cos(x)) ... 1: 5.24196456928 - 1: 4.5 . - . - - 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET} -@end group -@end smallexample - -This is the new guess for @expr{x}. Now we compare it with the -old one to see if we've converged. - -@smallexample -@group -3: 5.24196 2: 5.24196 1: 5.24196 1: 5.26345856348 -2: 5.24196 1: 0 . . -1: 4.5 . - . - - @key{RET} M-@key{TAB} a = Z / Z > Z ' C-x ) -@end group -@end smallexample - -The loop converges in just a few steps to this value. To check -the result, we can simply substitute it back into the equation. - -@smallexample -@group -2: 5.26345856348 -1: 0.499999999997 - . - - @key{RET} ' sin(cos($)) @key{RET} -@end group -@end smallexample - -Let's test the new definition again: - -@smallexample -@group -2: x^2 - 9 1: 3. -1: 1 . - . - - ' x^2-9 @key{RET} 1 X -@end group -@end smallexample - -Once again, here's the full Newton's Method definition: - -@example -@group -C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} / ' x @key{RET} @key{TAB} - t 1 - 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET} - @key{RET} M-@key{TAB} a = Z / - Z > - Z ' -C-x ) -@end group -@end example - -@c [fix-ref Nesting and Fixed Points] -It turns out that Calc has a built-in command for applying a formula -repeatedly until it converges to a number. @xref{Nesting and Fixed Points}, -to see how to use it. - -@c [fix-ref Root Finding] -Also, of course, @kbd{a R} is a built-in command that uses Newton's -method (among others) to look for numerical solutions to any equation. -@xref{Root Finding}. - -@node Programming Answer 9, Programming Answer 10, Programming Answer 8, Answers to Exercises -@subsection Programming Tutorial Exercise 9 - -@noindent -The first step is to adjust @expr{z} to be greater than 5. A simple -``for'' loop will do the job here. If @expr{z} is less than 5, we -reduce the problem using -@texline @math{\psi(z) = \psi(z+1) - 1/z}. -@infoline @expr{psi(z) = psi(z+1) - 1/z}. We go -on to compute -@texline @math{\psi(z+1)}, -@infoline @expr{psi(z+1)}, -and remember to add back a factor of @expr{-1/z} when we're done. This -step is repeated until @expr{z > 5}. - -(Because this definition is long, it will be repeated in concise form -below. You can use @w{@kbd{C-x * m}} to load it from there. While you are -entering a @kbd{Z ` Z '} body in a macro, Calc simply collects -keystrokes without executing them. In the following diagrams we'll -pretend Calc actually executed the keystrokes as you typed them, -just for purposes of illustration.) - -@smallexample -@group -1: 1. 1: 1. - . . - - 1.0 @key{RET} C-x ( Z ` s 1 0 t 2 -@end group -@end smallexample - -Here, variable 1 holds @expr{z} and variable 2 holds the adjustment -factor. If @expr{z < 5}, we use a loop to increase it. - -(By the way, we started with @samp{1.0} instead of the integer 1 because -otherwise the calculation below will try to do exact fractional arithmetic, -and will never converge because fractions compare equal only if they -are exactly equal, not just equal to within the current precision.) - -@smallexample -@group -3: 1. 2: 1. 1: 6. -2: 1. 1: 1 . -1: 5 . - . - - @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ] -@end group -@end smallexample - -Now we compute the initial part of the sum: -@texline @math{\ln z - {1 \over 2z}} -@infoline @expr{ln(z) - 1/2z} -minus the adjustment factor. - -@smallexample -@group -2: 1.79175946923 2: 1.7084261359 1: -0.57490719743 -1: 0.0833333333333 1: 2.28333333333 . - . . - - L r 1 2 * & - r 2 - -@end group -@end smallexample - -Now we evaluate the series. We'll use another ``for'' loop counting -up the value of @expr{2 n}. (Calc does have a summation command, -@kbd{a +}, but we'll use loops just to get more practice with them.) - -@smallexample -@group -3: -0.5749 3: -0.5749 4: -0.5749 2: -0.5749 -2: 2 2: 1:6 3: 1:6 1: 2.3148e-3 -1: 40 1: 2 2: 2 . - . . 1: 36. - . - - 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * / - -@end group -@end smallexample -@noindent -@smallexample -@group -3: -0.5749 3: -0.5772 2: -0.5772 1: -0.577215664892 -2: -0.5749 2: -0.5772 1: 0 . -1: 2.3148e-3 1: -0.5749 . - . . - - @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / 2 Z ) Z ' C-x ) -@end group -@end smallexample - -This is the value of -@texline @math{-\gamma}, -@infoline @expr{- gamma}, -with a slight bit of roundoff error. To get a full 12 digits, let's use -a higher precision: - -@smallexample -@group -2: -0.577215664892 2: -0.577215664892 -1: 1. 1: -0.577215664901532 - - 1. @key{RET} p 16 @key{RET} X -@end group -@end smallexample - -Here's the complete sequence of keystrokes: - -@example -@group -C-x ( Z ` s 1 0 t 2 - @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ] - L r 1 2 * & - r 2 - - 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * / - @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / - 2 Z ) - Z ' -C-x ) -@end group -@end example - -@node Programming Answer 10, Programming Answer 11, Programming Answer 9, Answers to Exercises -@subsection Programming Tutorial Exercise 10 - -@noindent -Taking the derivative of a term of the form @expr{x^n} will produce -a term like -@texline @math{n x^{n-1}}. -@infoline @expr{n x^(n-1)}. -Taking the derivative of a constant -produces zero. From this it is easy to see that the @expr{n}th -derivative of a polynomial, evaluated at @expr{x = 0}, will equal the -coefficient on the @expr{x^n} term times @expr{n!}. - -(Because this definition is long, it will be repeated in concise form -below. You can use @w{@kbd{C-x * m}} to load it from there. While you are -entering a @kbd{Z ` Z '} body in a macro, Calc simply collects -keystrokes without executing them. In the following diagrams we'll -pretend Calc actually executed the keystrokes as you typed them, -just for purposes of illustration.) - -@smallexample -@group -2: 5 x^4 + (x + 1)^2 3: 5 x^4 + (x + 1)^2 -1: 6 2: 0 - . 1: 6 - . - - ' 5 x^4 + (x+1)^2 @key{RET} 6 C-x ( Z ` [ ] t 1 0 @key{TAB} -@end group -@end smallexample - -@noindent -Variable 1 will accumulate the vector of coefficients. - -@smallexample -@group -2: 0 3: 0 2: 5 x^4 + ... -1: 5 x^4 + ... 2: 5 x^4 + ... 1: 1 - . 1: 1 . - . - - Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1 -@end group -@end smallexample - -@noindent -Note that @kbd{s | 1} appends the top-of-stack value to the vector -in a variable; it is completely analogous to @kbd{s + 1}. We could -have written instead, @kbd{r 1 @key{TAB} | t 1}. - -@smallexample -@group -1: 20 x^3 + 2 x + 2 1: 0 1: [1, 2, 1, 0, 5, 0, 0] - . . . - - a d x @key{RET} 1 Z ) @key{DEL} r 1 Z ' C-x ) -@end group -@end smallexample - -To convert back, a simple method is just to map the coefficients -against a table of powers of @expr{x}. - -@smallexample -@group -2: [1, 2, 1, 0, 5, 0, 0] 2: [1, 2, 1, 0, 5, 0, 0] -1: 6 1: [0, 1, 2, 3, 4, 5, 6] - . . - - 6 @key{RET} 1 + 0 @key{RET} 1 C-u v x - -@end group -@end smallexample -@noindent -@smallexample -@group -2: [1, 2, 1, 0, 5, 0, 0] 2: 1 + 2 x + x^2 + 5 x^4 -1: [1, x, x^2, x^3, ... ] . - . - - ' x @key{RET} @key{TAB} V M ^ * -@end group -@end smallexample - -Once again, here are the whole polynomial to/from vector programs: - -@example -@group -C-x ( Z ` [ ] t 1 0 @key{TAB} - Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1 - a d x @key{RET} - 1 Z ) r 1 - Z ' -C-x ) - -C-x ( 1 + 0 @key{RET} 1 C-u v x ' x @key{RET} @key{TAB} V M ^ * C-x ) -@end group -@end example - -@node Programming Answer 11, Programming Answer 12, Programming Answer 10, Answers to Exercises -@subsection Programming Tutorial Exercise 11 - -@noindent -First we define a dummy program to go on the @kbd{z s} key. The true -@w{@kbd{z s}} key is supposed to take two numbers from the stack and -return one number, so @key{DEL} as a dummy definition will make -sure the stack comes out right. - -@smallexample -@group -2: 4 1: 4 2: 4 -1: 2 . 1: 2 - . . - - 4 @key{RET} 2 C-x ( @key{DEL} C-x ) Z K s @key{RET} 2 -@end group -@end smallexample - -The last step replaces the 2 that was eaten during the creation -of the dummy @kbd{z s} command. Now we move on to the real -definition. The recurrence needs to be rewritten slightly, -to the form @expr{s(n,m) = s(n-1,m-1) - (n-1) s(n-1,m)}. - -(Because this definition is long, it will be repeated in concise form -below. You can use @kbd{C-x * m} to load it from there.) - -@smallexample -@group -2: 4 4: 4 3: 4 2: 4 -1: 2 3: 2 2: 2 1: 2 - . 2: 4 1: 0 . - 1: 2 . - . - - C-x ( M-2 @key{RET} a = Z [ @key{DEL} @key{DEL} 1 Z : - -@end group -@end smallexample -@noindent -@smallexample -@group -4: 4 2: 4 2: 3 4: 3 4: 3 3: 3 -3: 2 1: 2 1: 2 3: 2 3: 2 2: 2 -2: 2 . . 2: 3 2: 3 1: 3 -1: 0 1: 2 1: 1 . - . . . - - @key{RET} 0 a = Z [ @key{DEL} @key{DEL} 0 Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s -@end group -@end smallexample - -@noindent -(Note that the value 3 that our dummy @kbd{z s} produces is not correct; -it is merely a placeholder that will do just as well for now.) - -@smallexample -@group -3: 3 4: 3 3: 3 2: 3 1: -6 -2: 3 3: 3 2: 3 1: 9 . -1: 2 2: 3 1: 3 . - . 1: 2 . - . - - M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: -6 2: 4 1: 11 2: 11 - . 1: 2 . 1: 11 - . . - - Z ] Z ] C-x ) Z K s @key{RET} @key{DEL} 4 @key{RET} 2 z s M-@key{RET} k s -@end group -@end smallexample - -Even though the result that we got during the definition was highly -bogus, once the definition is complete the @kbd{z s} command gets -the right answers. - -Here's the full program once again: - -@example -@group -C-x ( M-2 @key{RET} a = - Z [ @key{DEL} @key{DEL} 1 - Z : @key{RET} 0 a = - Z [ @key{DEL} @key{DEL} 0 - Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s - M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * - - Z ] - Z ] -C-x ) -@end group -@end example - -You can read this definition using @kbd{C-x * m} (@code{read-kbd-macro}) -followed by @kbd{Z K s}, without having to make a dummy definition -first, because @code{read-kbd-macro} doesn't need to execute the -definition as it reads it in. For this reason, @code{C-x * m} is often -the easiest way to create recursive programs in Calc. - -@node Programming Answer 12, , Programming Answer 11, Answers to Exercises -@subsection Programming Tutorial Exercise 12 - -@noindent -This turns out to be a much easier way to solve the problem. Let's -denote Stirling numbers as calls of the function @samp{s}. - -First, we store the rewrite rules corresponding to the definition of -Stirling numbers in a convenient variable: - -@smallexample -s e StirlingRules @key{RET} -[ s(n,n) := 1 :: n >= 0, - s(n,0) := 0 :: n > 0, - s(n,m) := s(n-1,m-1) - (n-1) s(n-1,m) :: n >= m :: m >= 1 ] -C-c C-c -@end smallexample - -Now, it's just a matter of applying the rules: - -@smallexample -@group -2: 4 1: s(4, 2) 1: 11 -1: 2 . . - . - - 4 @key{RET} 2 C-x ( ' s($$,$) @key{RET} a r StirlingRules @key{RET} C-x ) -@end group -@end smallexample - -As in the case of the @code{fib} rules, it would be useful to put these -rules in @code{EvalRules} and to add a @samp{:: remember} condition to -the last rule. - -@c This ends the table-of-contents kludge from above: -@tex -\global\let\chapternofonts=\oldchapternofonts -@end tex - -@c [reference] - -@node Introduction, Data Types, Tutorial, Top -@chapter Introduction - -@noindent -This chapter is the beginning of the Calc reference manual. -It covers basic concepts such as the stack, algebraic and -numeric entry, undo, numeric prefix arguments, etc. - -@c [when-split] -@c (Chapter 2, the Tutorial, has been printed in a separate volume.) - -@menu -* Basic Commands:: -* Help Commands:: -* Stack Basics:: -* Numeric Entry:: -* Algebraic Entry:: -* Quick Calculator:: -* Prefix Arguments:: -* Undo:: -* Error Messages:: -* Multiple Calculators:: -* Troubleshooting Commands:: -@end menu - -@node Basic Commands, Help Commands, Introduction, Introduction -@section Basic Commands - -@noindent -@pindex calc -@pindex calc-mode -@cindex Starting the Calculator -@cindex Running the Calculator -To start the Calculator in its standard interface, type @kbd{M-x calc}. -By default this creates a pair of small windows, @samp{*Calculator*} -and @samp{*Calc Trail*}. The former displays the contents of the -Calculator stack and is manipulated exclusively through Calc commands. -It is possible (though not usually necessary) to create several Calc -mode buffers each of which has an independent stack, undo list, and -mode settings. There is exactly one Calc Trail buffer; it records a -list of the results of all calculations that have been done. The -Calc Trail buffer uses a variant of Calc mode, so Calculator commands -still work when the trail buffer's window is selected. It is possible -to turn the trail window off, but the @samp{*Calc Trail*} buffer itself -still exists and is updated silently. @xref{Trail Commands}. - -@kindex C-x * c -@kindex C-x * * -@ignore -@mindex @null -@end ignore -In most installations, the @kbd{C-x * c} key sequence is a more -convenient way to start the Calculator. Also, @kbd{C-x * *} -is a synonym for @kbd{C-x * c} unless you last used Calc -in its Keypad mode. - -@kindex x -@kindex M-x -@pindex calc-execute-extended-command -Most Calc commands use one or two keystrokes. Lower- and upper-case -letters are distinct. Commands may also be entered in full @kbd{M-x} form; -for some commands this is the only form. As a convenience, the @kbd{x} -key (@code{calc-execute-extended-command}) -is like @kbd{M-x} except that it enters the initial string @samp{calc-} -for you. For example, the following key sequences are equivalent: -@kbd{S}, @kbd{M-x calc-sin @key{RET}}, @kbd{x sin @key{RET}}. - -Although Calc is designed to be used from the keyboard, some of -Calc's more common commands are available from a menu. In the menu, the -arguments to the functions are given by referring to their stack level -numbers. - -@cindex Extensions module -@cindex @file{calc-ext} module -The Calculator exists in many parts. When you type @kbd{C-x * c}, the -Emacs ``auto-load'' mechanism will bring in only the first part, which -contains the basic arithmetic functions. The other parts will be -auto-loaded the first time you use the more advanced commands like trig -functions or matrix operations. This is done to improve the response time -of the Calculator in the common case when all you need to do is a -little arithmetic. If for some reason the Calculator fails to load an -extension module automatically, you can force it to load all the -extensions by using the @kbd{C-x * L} (@code{calc-load-everything}) -command. @xref{Mode Settings}. - -If you type @kbd{M-x calc} or @kbd{C-x * c} with any numeric prefix argument, -the Calculator is loaded if necessary, but it is not actually started. -If the argument is positive, the @file{calc-ext} extensions are also -loaded if necessary. User-written Lisp code that wishes to make use -of Calc's arithmetic routines can use @samp{(calc 0)} or @samp{(calc 1)} -to auto-load the Calculator. - -@kindex C-x * b -@pindex full-calc -If you type @kbd{C-x * b}, then next time you use @kbd{C-x * c} you -will get a Calculator that uses the full height of the Emacs screen. -When full-screen mode is on, @kbd{C-x * c} runs the @code{full-calc} -command instead of @code{calc}. From the Unix shell you can type -@samp{emacs -f full-calc} to start a new Emacs specifically for use -as a calculator. When Calc is started from the Emacs command line -like this, Calc's normal ``quit'' commands actually quit Emacs itself. - -@kindex C-x * o -@pindex calc-other-window -The @kbd{C-x * o} command is like @kbd{C-x * c} except that the Calc -window is not actually selected. If you are already in the Calc -window, @kbd{C-x * o} switches you out of it. (The regular Emacs -@kbd{C-x o} command would also work for this, but it has a -tendency to drop you into the Calc Trail window instead, which -@kbd{C-x * o} takes care not to do.) - -@ignore -@mindex C-x * q -@end ignore -For one quick calculation, you can type @kbd{C-x * q} (@code{quick-calc}) -which prompts you for a formula (like @samp{2+3/4}). The result is -displayed at the bottom of the Emacs screen without ever creating -any special Calculator windows. @xref{Quick Calculator}. - -@ignore -@mindex C-x * k -@end ignore -Finally, if you are using the X window system you may want to try -@kbd{C-x * k} (@code{calc-keypad}) which runs Calc with a -``calculator keypad'' picture as well as a stack display. Click on -the keys with the mouse to operate the calculator. @xref{Keypad Mode}. - -@kindex q -@pindex calc-quit -@cindex Quitting the Calculator -@cindex Exiting the Calculator -The @kbd{q} key (@code{calc-quit}) exits Calc mode and closes the -Calculator's window(s). It does not delete the Calculator buffers. -If you type @kbd{M-x calc} again, the Calculator will reappear with the -contents of the stack intact. Typing @kbd{C-x * c} or @kbd{C-x * *} -again from inside the Calculator buffer is equivalent to executing -@code{calc-quit}; you can think of @kbd{C-x * *} as toggling the -Calculator on and off. - -@kindex C-x * x -The @kbd{C-x * x} command also turns the Calculator off, no matter which -user interface (standard, Keypad, or Embedded) is currently active. -It also cancels @code{calc-edit} mode if used from there. - -@kindex d @key{SPC} -@pindex calc-refresh -@cindex Refreshing a garbled display -@cindex Garbled displays, refreshing -The @kbd{d @key{SPC}} key sequence (@code{calc-refresh}) redraws the contents -of the Calculator buffer from memory. Use this if the contents of the -buffer have been damaged somehow. - -@ignore -@mindex o -@end ignore -The @kbd{o} key (@code{calc-realign}) moves the cursor back to its -``home'' position at the bottom of the Calculator buffer. - -@kindex < -@kindex > -@pindex calc-scroll-left -@pindex calc-scroll-right -@cindex Horizontal scrolling -@cindex Scrolling -@cindex Wide text, scrolling -The @kbd{<} and @kbd{>} keys are bound to @code{calc-scroll-left} and -@code{calc-scroll-right}. These are just like the normal horizontal -scrolling commands except that they scroll one half-screen at a time by -default. (Calc formats its output to fit within the bounds of the -window whenever it can.) - -@kindex @{ -@kindex @} -@pindex calc-scroll-down -@pindex calc-scroll-up -@cindex Vertical scrolling -The @kbd{@{} and @kbd{@}} keys are bound to @code{calc-scroll-down} -and @code{calc-scroll-up}. They scroll up or down by one-half the -height of the Calc window. - -@kindex C-x * 0 -@pindex calc-reset -The @kbd{C-x * 0} command (@code{calc-reset}; that's @kbd{C-x *} followed -by a zero) resets the Calculator to its initial state. This clears -the stack, resets all the modes to their initial values (the values -that were saved with @kbd{m m} (@code{calc-save-modes})), clears the -caches (@pxref{Caches}), and so on. (It does @emph{not} erase the -values of any variables.) With an argument of 0, Calc will be reset to -its default state; namely, the modes will be given their default values. -With a positive prefix argument, @kbd{C-x * 0} preserves the contents of -the stack but resets everything else to its initial state; with a -negative prefix argument, @kbd{C-x * 0} preserves the contents of the -stack but resets everything else to its default state. - -@node Help Commands, Stack Basics, Basic Commands, Introduction -@section Help Commands - -@noindent -@cindex Help commands -@kindex ? -@kindex a ? -@kindex b ? -@kindex c ? -@kindex d ? -@kindex f ? -@kindex g ? -@kindex j ? -@kindex k ? -@kindex m ? -@kindex r ? -@kindex s ? -@kindex t ? -@kindex u ? -@kindex v ? -@kindex V ? -@kindex z ? -@kindex Z ? -@pindex calc-help -The @kbd{?} key (@code{calc-help}) displays a series of brief help messages. -Some keys (such as @kbd{b} and @kbd{d}) are prefix keys, like Emacs's -@key{ESC} and @kbd{C-x} prefixes. You can type -@kbd{?} after a prefix to see a list of commands beginning with that -prefix. (If the message includes @samp{[MORE]}, press @kbd{?} again -to see additional commands for that prefix.) - -@kindex h h -@pindex calc-full-help -The @kbd{h h} (@code{calc-full-help}) command displays all the @kbd{?} -responses at once. When printed, this makes a nice, compact (three pages) -summary of Calc keystrokes. - -In general, the @kbd{h} key prefix introduces various commands that -provide help within Calc. Many of the @kbd{h} key functions are -Calc-specific analogues to the @kbd{C-h} functions for Emacs help. - -@kindex h i -@kindex C-x * i -@kindex i -@pindex calc-info -The @kbd{h i} (@code{calc-info}) command runs the Emacs Info system -to read this manual on-line. This is basically the same as typing -@kbd{C-h i} (the regular way to run the Info system), then, if Info -is not already in the Calc manual, selecting the beginning of the -manual. The @kbd{C-x * i} command is another way to read the Calc -manual; it is different from @kbd{h i} in that it works any time, -not just inside Calc. The plain @kbd{i} key is also equivalent to -@kbd{h i}, though this key is obsolete and may be replaced with a -different command in a future version of Calc. - -@kindex h t -@kindex C-x * t -@pindex calc-tutorial -The @kbd{h t} (@code{calc-tutorial}) command runs the Info system on -the Tutorial section of the Calc manual. It is like @kbd{h i}, -except that it selects the starting node of the tutorial rather -than the beginning of the whole manual. (It actually selects the -node ``Interactive Tutorial'' which tells a few things about -using the Info system before going on to the actual tutorial.) -The @kbd{C-x * t} key is equivalent to @kbd{h t} (but it works at -all times). - -@kindex h s -@kindex C-x * s -@pindex calc-info-summary -The @kbd{h s} (@code{calc-info-summary}) command runs the Info system -on the Summary node of the Calc manual. @xref{Summary}. The @kbd{C-x * s} -key is equivalent to @kbd{h s}. - -@kindex h k -@pindex calc-describe-key -The @kbd{h k} (@code{calc-describe-key}) command looks up a key -sequence in the Calc manual. For example, @kbd{h k H a S} looks -up the documentation on the @kbd{H a S} (@code{calc-solve-for}) -command. This works by looking up the textual description of -the key(s) in the Key Index of the manual, then jumping to the -node indicated by the index. - -Most Calc commands do not have traditional Emacs documentation -strings, since the @kbd{h k} command is both more convenient and -more instructive. This means the regular Emacs @kbd{C-h k} -(@code{describe-key}) command will not be useful for Calc keystrokes. - -@kindex h c -@pindex calc-describe-key-briefly -The @kbd{h c} (@code{calc-describe-key-briefly}) command reads a -key sequence and displays a brief one-line description of it at -the bottom of the screen. It looks for the key sequence in the -Summary node of the Calc manual; if it doesn't find the sequence -there, it acts just like its regular Emacs counterpart @kbd{C-h c} -(@code{describe-key-briefly}). For example, @kbd{h c H a S} -gives the description: - -@smallexample -H a S runs calc-solve-for: a `H a S' v => fsolve(a,v) (?=notes) -@end smallexample - -@noindent -which means the command @kbd{H a S} or @kbd{H M-x calc-solve-for} -takes a value @expr{a} from the stack, prompts for a value @expr{v}, -then applies the algebraic function @code{fsolve} to these values. -The @samp{?=notes} message means you can now type @kbd{?} to see -additional notes from the summary that apply to this command. - -@kindex h f -@pindex calc-describe-function -The @kbd{h f} (@code{calc-describe-function}) command looks up an -algebraic function or a command name in the Calc manual. Enter an -algebraic function name to look up that function in the Function -Index or enter a command name beginning with @samp{calc-} to look it -up in the Command Index. This command will also look up operator -symbols that can appear in algebraic formulas, like @samp{%} and -@samp{=>}. - -@kindex h v -@pindex calc-describe-variable -The @kbd{h v} (@code{calc-describe-variable}) command looks up a -variable in the Calc manual. Enter a variable name like @code{pi} or -@code{PlotRejects}. - -@kindex h b -@pindex describe-bindings -The @kbd{h b} (@code{calc-describe-bindings}) command is just like -@kbd{C-h b}, except that only local (Calc-related) key bindings are -listed. - -@kindex h n -The @kbd{h n} or @kbd{h C-n} (@code{calc-view-news}) command displays -the ``news'' or change history of Calc. This is kept in the file -@file{README}, which Calc looks for in the same directory as the Calc -source files. - -@kindex h C-c -@kindex h C-d -@kindex h C-w -The @kbd{h C-c}, @kbd{h C-d}, and @kbd{h C-w} keys display copying, -distribution, and warranty information about Calc. These work by -pulling up the appropriate parts of the ``Copying'' or ``Reporting -Bugs'' sections of the manual. - -@node Stack Basics, Numeric Entry, Help Commands, Introduction -@section Stack Basics - -@noindent -@cindex Stack basics -@c [fix-tut RPN Calculations and the Stack] -Calc uses RPN notation. If you are not familiar with RPN, @pxref{RPN -Tutorial}. - -To add the numbers 1 and 2 in Calc you would type the keys: -@kbd{1 @key{RET} 2 +}. -(@key{RET} corresponds to the @key{ENTER} key on most calculators.) -The first three keystrokes ``push'' the numbers 1 and 2 onto the stack. The -@kbd{+} key always ``pops'' the top two numbers from the stack, adds them, -and pushes the result (3) back onto the stack. This number is ready for -further calculations: @kbd{5 -} pushes 5 onto the stack, then pops the -3 and 5, subtracts them, and pushes the result (@mathit{-2}). - -Note that the ``top'' of the stack actually appears at the @emph{bottom} -of the buffer. A line containing a single @samp{.} character signifies -the end of the buffer; Calculator commands operate on the number(s) -directly above this line. The @kbd{d t} (@code{calc-truncate-stack}) -command allows you to move the @samp{.} marker up and down in the stack; -@pxref{Truncating the Stack}. - -@kindex d l -@pindex calc-line-numbering -Stack elements are numbered consecutively, with number 1 being the top of -the stack. These line numbers are ordinarily displayed on the lefthand side -of the window. The @kbd{d l} (@code{calc-line-numbering}) command controls -whether these numbers appear. (Line numbers may be turned off since they -slow the Calculator down a bit and also clutter the display.) - -@kindex o -@pindex calc-realign -The unshifted letter @kbd{o} (@code{calc-realign}) command repositions -the cursor to its top-of-stack ``home'' position. It also undoes any -horizontal scrolling in the window. If you give it a numeric prefix -argument, it instead moves the cursor to the specified stack element. - -The @key{RET} (or equivalent @key{SPC}) key is only required to separate -two consecutive numbers. -(After all, if you typed @kbd{1 2} by themselves the Calculator -would enter the number 12.) If you press @key{RET} or @key{SPC} @emph{not} -right after typing a number, the key duplicates the number on the top of -the stack. @kbd{@key{RET} *} is thus a handy way to square a number. - -The @key{DEL} key pops and throws away the top number on the stack. -The @key{TAB} key swaps the top two objects on the stack. -@xref{Stack and Trail}, for descriptions of these and other stack-related -commands. - -@node Numeric Entry, Algebraic Entry, Stack Basics, Introduction -@section Numeric Entry - -@noindent -@kindex 0-9 -@kindex . -@kindex e -@cindex Numeric entry -@cindex Entering numbers -Pressing a digit or other numeric key begins numeric entry using the -minibuffer. The number is pushed on the stack when you press the @key{RET} -or @key{SPC} keys. If you press any other non-numeric key, the number is -pushed onto the stack and the appropriate operation is performed. If -you press a numeric key which is not valid, the key is ignored. - -@cindex Minus signs -@cindex Negative numbers, entering -@kindex _ -There are three different concepts corresponding to the word ``minus,'' -typified by @expr{a-b} (subtraction), @expr{-x} -(change-sign), and @expr{-5} (negative number). Calc uses three -different keys for these operations, respectively: -@kbd{-}, @kbd{n}, and @kbd{_} (the underscore). The @kbd{-} key subtracts -the two numbers on the top of the stack. The @kbd{n} key changes the sign -of the number on the top of the stack or the number currently being entered. -The @kbd{_} key begins entry of a negative number or changes the sign of -the number currently being entered. The following sequences all enter the -number @mathit{-5} onto the stack: @kbd{0 @key{RET} 5 -}, @kbd{5 n @key{RET}}, -@kbd{5 @key{RET} n}, @kbd{_ 5 @key{RET}}, @kbd{5 _ @key{RET}}. - -Some other keys are active during numeric entry, such as @kbd{#} for -non-decimal numbers, @kbd{:} for fractions, and @kbd{@@} for HMS forms. -These notations are described later in this manual with the corresponding -data types. @xref{Data Types}. - -During numeric entry, the only editing key available is @key{DEL}. - -@node Algebraic Entry, Quick Calculator, Numeric Entry, Introduction -@section Algebraic Entry - -@noindent -@kindex ' -@pindex calc-algebraic-entry -@cindex Algebraic notation -@cindex Formulas, entering -The @kbd{'} (@code{calc-algebraic-entry}) command can be used to enter -calculations in algebraic form. This is accomplished by typing the -apostrophe key, ', followed by the expression in standard format: - -@example -' 2+3*4 @key{RET}. -@end example - -@noindent -This will compute -@texline @math{2+(3\times4) = 14} -@infoline @expr{2+(3*4) = 14} -and push it on the stack. If you wish you can -ignore the RPN aspect of Calc altogether and simply enter algebraic -expressions in this way. You may want to use @key{DEL} every so often to -clear previous results off the stack. - -You can press the apostrophe key during normal numeric entry to switch -the half-entered number into Algebraic entry mode. One reason to do -this would be to fix a typo, as the full Emacs cursor motion and editing -keys are available during algebraic entry but not during numeric entry. - -In the same vein, during either numeric or algebraic entry you can -press @kbd{`} (backquote) to switch to @code{calc-edit} mode, where -you complete your half-finished entry in a separate buffer. -@xref{Editing Stack Entries}. - -@kindex m a -@pindex calc-algebraic-mode -@cindex Algebraic Mode -If you prefer algebraic entry, you can use the command @kbd{m a} -(@code{calc-algebraic-mode}) to set Algebraic mode. In this mode, -digits and other keys that would normally start numeric entry instead -start full algebraic entry; as long as your formula begins with a digit -you can omit the apostrophe. Open parentheses and square brackets also -begin algebraic entry. You can still do RPN calculations in this mode, -but you will have to press @key{RET} to terminate every number: -@kbd{2 @key{RET} 3 @key{RET} * 4 @key{RET} +} would accomplish the same -thing as @kbd{2*3+4 @key{RET}}. - -@cindex Incomplete Algebraic Mode -If you give a numeric prefix argument like @kbd{C-u} to the @kbd{m a} -command, it enables Incomplete Algebraic mode; this is like regular -Algebraic mode except that it applies to the @kbd{(} and @kbd{[} keys -only. Numeric keys still begin a numeric entry in this mode. - -@kindex m t -@pindex calc-total-algebraic-mode -@cindex Total Algebraic Mode -The @kbd{m t} (@code{calc-total-algebraic-mode}) gives you an even -stronger algebraic-entry mode, in which @emph{all} regular letter and -punctuation keys begin algebraic entry. Use this if you prefer typing -@w{@kbd{sqrt( )}} instead of @kbd{Q}, @w{@kbd{factor( )}} instead of -@kbd{a f}, and so on. To type regular Calc commands when you are in -Total Algebraic mode, hold down the @key{META} key. Thus @kbd{M-q} -is the command to quit Calc, @kbd{M-p} sets the precision, and -@kbd{M-m t} (or @kbd{M-m M-t}, if you prefer) turns Total Algebraic -mode back off again. Meta keys also terminate algebraic entry, so -that @kbd{2+3 M-S} is equivalent to @kbd{2+3 @key{RET} M-S}. The symbol -@samp{Alg*} will appear in the mode line whenever you are in this mode. - -Pressing @kbd{'} (the apostrophe) a second time re-enters the previous -algebraic formula. You can then use the normal Emacs editing keys to -modify this formula to your liking before pressing @key{RET}. - -@kindex $ -@cindex Formulas, referring to stack -Within a formula entered from the keyboard, the symbol @kbd{$} -represents the number on the top of the stack. If an entered formula -contains any @kbd{$} characters, the Calculator replaces the top of -stack with that formula rather than simply pushing the formula onto the -stack. Thus, @kbd{' 1+2 @key{RET}} pushes 3 on the stack, and @kbd{$*2 -@key{RET}} replaces it with 6. Note that the @kbd{$} key always -initiates algebraic entry; the @kbd{'} is unnecessary if @kbd{$} is the -first character in the new formula. - -Higher stack elements can be accessed from an entered formula with the -symbols @kbd{$$}, @kbd{$$$}, and so on. The number of stack elements -removed (to be replaced by the entered values) equals the number of dollar -signs in the longest such symbol in the formula. For example, @samp{$$+$$$} -adds the second and third stack elements, replacing the top three elements -with the answer. (All information about the top stack element is thus lost -since no single @samp{$} appears in this formula.) - -A slightly different way to refer to stack elements is with a dollar -sign followed by a number: @samp{$1}, @samp{$2}, and so on are much -like @samp{$}, @samp{$$}, etc., except that stack entries referred -to numerically are not replaced by the algebraic entry. That is, while -@samp{$+1} replaces 5 on the stack with 6, @samp{$1+1} leaves the 5 -on the stack and pushes an additional 6. - -If a sequence of formulas are entered separated by commas, each formula -is pushed onto the stack in turn. For example, @samp{1,2,3} pushes -those three numbers onto the stack (leaving the 3 at the top), and -@samp{$+1,$-1} replaces a 5 on the stack with 4 followed by 6. Also, -@samp{$,$$} exchanges the top two elements of the stack, just like the -@key{TAB} key. - -You can finish an algebraic entry with @kbd{M-=} or @kbd{M-@key{RET}} instead -of @key{RET}. This uses @kbd{=} to evaluate the variables in each -formula that goes onto the stack. (Thus @kbd{' pi @key{RET}} pushes -the variable @samp{pi}, but @kbd{' pi M-@key{RET}} pushes 3.1415.) - -If you finish your algebraic entry by pressing @key{LFD} (or @kbd{C-j}) -instead of @key{RET}, Calc disables the default simplifications -(as if by @kbd{m O}; @pxref{Simplification Modes}) while the entry -is being pushed on the stack. Thus @kbd{' 1+2 @key{RET}} pushes 3 -on the stack, but @kbd{' 1+2 @key{LFD}} pushes the formula @expr{1+2}; -you might then press @kbd{=} when it is time to evaluate this formula. - -@node Quick Calculator, Prefix Arguments, Algebraic Entry, Introduction -@section ``Quick Calculator'' Mode - -@noindent -@kindex C-x * q -@pindex quick-calc -@cindex Quick Calculator -There is another way to invoke the Calculator if all you need to do -is make one or two quick calculations. Type @kbd{C-x * q} (or -@kbd{M-x quick-calc}), then type any formula as an algebraic entry. -The Calculator will compute the result and display it in the echo -area, without ever actually putting up a Calc window. - -You can use the @kbd{$} character in a Quick Calculator formula to -refer to the previous Quick Calculator result. Older results are -not retained; the Quick Calculator has no effect on the full -Calculator's stack or trail. If you compute a result and then -forget what it was, just run @code{C-x * q} again and enter -@samp{$} as the formula. - -If this is the first time you have used the Calculator in this Emacs -session, the @kbd{C-x * q} command will create the @code{*Calculator*} -buffer and perform all the usual initializations; it simply will -refrain from putting that buffer up in a new window. The Quick -Calculator refers to the @code{*Calculator*} buffer for all mode -settings. Thus, for example, to set the precision that the Quick -Calculator uses, simply run the full Calculator momentarily and use -the regular @kbd{p} command. - -If you use @code{C-x * q} from inside the Calculator buffer, the -effect is the same as pressing the apostrophe key (algebraic entry). - -The result of a Quick calculation is placed in the Emacs ``kill ring'' -as well as being displayed. A subsequent @kbd{C-y} command will -yank the result into the editing buffer. You can also use this -to yank the result into the next @kbd{C-x * q} input line as a more -explicit alternative to @kbd{$} notation, or to yank the result -into the Calculator stack after typing @kbd{C-x * c}. - -If you finish your formula by typing @key{LFD} (or @kbd{C-j}) instead -of @key{RET}, the result is inserted immediately into the current -buffer rather than going into the kill ring. - -Quick Calculator results are actually evaluated as if by the @kbd{=} -key (which replaces variable names by their stored values, if any). -If the formula you enter is an assignment to a variable using the -@samp{:=} operator, say, @samp{foo := 2 + 3} or @samp{foo := foo + 1}, -then the result of the evaluation is stored in that Calc variable. -@xref{Store and Recall}. - -If the result is an integer and the current display radix is decimal, -the number will also be displayed in hex, octal and binary formats. If -the integer is in the range from 1 to 126, it will also be displayed as -an ASCII character. - -For example, the quoted character @samp{"x"} produces the vector -result @samp{[120]} (because 120 is the ASCII code of the lower-case -`x'; @pxref{Strings}). Since this is a vector, not an integer, it -is displayed only according to the current mode settings. But -running Quick Calc again and entering @samp{120} will produce the -result @samp{120 (16#78, 8#170, x)} which shows the number in its -decimal, hexadecimal, octal, and ASCII forms. - -Please note that the Quick Calculator is not any faster at loading -or computing the answer than the full Calculator; the name ``quick'' -merely refers to the fact that it's much less hassle to use for -small calculations. - -@node Prefix Arguments, Undo, Quick Calculator, Introduction -@section Numeric Prefix Arguments - -@noindent -Many Calculator commands use numeric prefix arguments. Some, such as -@kbd{d s} (@code{calc-sci-notation}), set a parameter to the value of -the prefix argument or use a default if you don't use a prefix. -Others (like @kbd{d f} (@code{calc-fix-notation})) require an argument -and prompt for a number if you don't give one as a prefix. - -As a rule, stack-manipulation commands accept a numeric prefix argument -which is interpreted as an index into the stack. A positive argument -operates on the top @var{n} stack entries; a negative argument operates -on the @var{n}th stack entry in isolation; and a zero argument operates -on the entire stack. - -Most commands that perform computations (such as the arithmetic and -scientific functions) accept a numeric prefix argument that allows the -operation to be applied across many stack elements. For unary operations -(that is, functions of one argument like absolute value or complex -conjugate), a positive prefix argument applies that function to the top -@var{n} stack entries simultaneously, and a negative argument applies it -to the @var{n}th stack entry only. For binary operations (functions of -two arguments like addition, GCD, and vector concatenation), a positive -prefix argument ``reduces'' the function across the top @var{n} -stack elements (for example, @kbd{C-u 5 +} sums the top 5 stack entries; -@pxref{Reducing and Mapping}), and a negative argument maps the next-to-top -@var{n} stack elements with the top stack element as a second argument -(for example, @kbd{7 c-u -5 +} adds 7 to the top 5 stack elements). -This feature is not available for operations which use the numeric prefix -argument for some other purpose. - -Numeric prefixes are specified the same way as always in Emacs: Press -a sequence of @key{META}-digits, or press @key{ESC} followed by digits, -or press @kbd{C-u} followed by digits. Some commands treat plain -@kbd{C-u} (without any actual digits) specially. - -@kindex ~ -@pindex calc-num-prefix -You can type @kbd{~} (@code{calc-num-prefix}) to pop an integer from the -top of the stack and enter it as the numeric prefix for the next command. -For example, @kbd{C-u 16 p} sets the precision to 16 digits; an alternate -(silly) way to do this would be @kbd{2 @key{RET} 4 ^ ~ p}, i.e., compute 2 -to the fourth power and set the precision to that value. - -Conversely, if you have typed a numeric prefix argument the @kbd{~} key -pushes it onto the stack in the form of an integer. - -@node Undo, Error Messages, Prefix Arguments, Introduction -@section Undoing Mistakes - -@noindent -@kindex U -@kindex C-_ -@pindex calc-undo -@cindex Mistakes, undoing -@cindex Undoing mistakes -@cindex Errors, undoing -The shift-@kbd{U} key (@code{calc-undo}) undoes the most recent operation. -If that operation added or dropped objects from the stack, those objects -are removed or restored. If it was a ``store'' operation, you are -queried whether or not to restore the variable to its original value. -The @kbd{U} key may be pressed any number of times to undo successively -farther back in time; with a numeric prefix argument it undoes a -specified number of operations. When the Calculator is quit, as with -the @kbd{q} (@code{calc-quit}) command, the undo history will be -truncated to the length of the customizable variable -@code{calc-undo-length} (@pxref{Customizing Calc}), which by default -is @expr{100}. (Recall that @kbd{C-x * c} is synonymous with -@code{calc-quit} while inside the Calculator; this also truncates the -undo history.) - -Currently the mode-setting commands (like @code{calc-precision}) are not -undoable. You can undo past a point where you changed a mode, but you -will need to reset the mode yourself. - -@kindex D -@pindex calc-redo -@cindex Redoing after an Undo -The shift-@kbd{D} key (@code{calc-redo}) redoes an operation that was -mistakenly undone. Pressing @kbd{U} with a negative prefix argument is -equivalent to executing @code{calc-redo}. You can redo any number of -times, up to the number of recent consecutive undo commands. Redo -information is cleared whenever you give any command that adds new undo -information, i.e., if you undo, then enter a number on the stack or make -any other change, then it will be too late to redo. - -@kindex M-@key{RET} -@pindex calc-last-args -@cindex Last-arguments feature -@cindex Arguments, restoring -The @kbd{M-@key{RET}} key (@code{calc-last-args}) is like undo in that -it restores the arguments of the most recent command onto the stack; -however, it does not remove the result of that command. Given a numeric -prefix argument, this command applies to the @expr{n}th most recent -command which removed items from the stack; it pushes those items back -onto the stack. - -The @kbd{K} (@code{calc-keep-args}) command provides a related function -to @kbd{M-@key{RET}}. @xref{Stack and Trail}. - -It is also possible to recall previous results or inputs using the trail. -@xref{Trail Commands}. - -The standard Emacs @kbd{C-_} undo key is recognized as a synonym for @kbd{U}. - -@node Error Messages, Multiple Calculators, Undo, Introduction -@section Error Messages - -@noindent -@kindex w -@pindex calc-why -@cindex Errors, messages -@cindex Why did an error occur? -Many situations that would produce an error message in other calculators -simply create unsimplified formulas in the Emacs Calculator. For example, -@kbd{1 @key{RET} 0 /} pushes the formula @expr{1 / 0}; @w{@kbd{0 L}} pushes -the formula @samp{ln(0)}. Floating-point overflow and underflow are also -reasons for this to happen. - -When a function call must be left in symbolic form, Calc usually -produces a message explaining why. Messages that are probably -surprising or indicative of user errors are displayed automatically. -Other messages are simply kept in Calc's memory and are displayed only -if you type @kbd{w} (@code{calc-why}). You can also press @kbd{w} if -the same computation results in several messages. (The first message -will end with @samp{[w=more]} in this case.) - -@kindex d w -@pindex calc-auto-why -The @kbd{d w} (@code{calc-auto-why}) command controls when error messages -are displayed automatically. (Calc effectively presses @kbd{w} for you -after your computation finishes.) By default, this occurs only for -``important'' messages. The other possible modes are to report -@emph{all} messages automatically, or to report none automatically (so -that you must always press @kbd{w} yourself to see the messages). - -@node Multiple Calculators, Troubleshooting Commands, Error Messages, Introduction -@section Multiple Calculators - -@noindent -@pindex another-calc -It is possible to have any number of Calc mode buffers at once. -Usually this is done by executing @kbd{M-x another-calc}, which -is similar to @kbd{C-x * c} except that if a @samp{*Calculator*} -buffer already exists, a new, independent one with a name of the -form @samp{*Calculator*<@var{n}>} is created. You can also use the -command @code{calc-mode} to put any buffer into Calculator mode, but -this would ordinarily never be done. - -The @kbd{q} (@code{calc-quit}) command does not destroy a Calculator buffer; -it only closes its window. Use @kbd{M-x kill-buffer} to destroy a -Calculator buffer. - -Each Calculator buffer keeps its own stack, undo list, and mode settings -such as precision, angular mode, and display formats. In Emacs terms, -variables such as @code{calc-stack} are buffer-local variables. The -global default values of these variables are used only when a new -Calculator buffer is created. The @code{calc-quit} command saves -the stack and mode settings of the buffer being quit as the new defaults. - -There is only one trail buffer, @samp{*Calc Trail*}, used by all -Calculator buffers. - -@node Troubleshooting Commands, , Multiple Calculators, Introduction -@section Troubleshooting Commands - -@noindent -This section describes commands you can use in case a computation -incorrectly fails or gives the wrong answer. - -@xref{Reporting Bugs}, if you find a problem that appears to be due -to a bug or deficiency in Calc. - -@menu -* Autoloading Problems:: -* Recursion Depth:: -* Caches:: -* Debugging Calc:: -@end menu - -@node Autoloading Problems, Recursion Depth, Troubleshooting Commands, Troubleshooting Commands -@subsection Autoloading Problems - -@noindent -The Calc program is split into many component files; components are -loaded automatically as you use various commands that require them. -Occasionally Calc may lose track of when a certain component is -necessary; typically this means you will type a command and it won't -work because some function you've never heard of was undefined. - -@kindex C-x * L -@pindex calc-load-everything -If this happens, the easiest workaround is to type @kbd{C-x * L} -(@code{calc-load-everything}) to force all the parts of Calc to be -loaded right away. This will cause Emacs to take up a lot more -memory than it would otherwise, but it's guaranteed to fix the problem. - -@node Recursion Depth, Caches, Autoloading Problems, Troubleshooting Commands -@subsection Recursion Depth - -@noindent -@kindex M -@kindex I M -@pindex calc-more-recursion-depth -@pindex calc-less-recursion-depth -@cindex Recursion depth -@cindex ``Computation got stuck'' message -@cindex @code{max-lisp-eval-depth} -@cindex @code{max-specpdl-size} -Calc uses recursion in many of its calculations. Emacs Lisp keeps a -variable @code{max-lisp-eval-depth} which limits the amount of recursion -possible in an attempt to recover from program bugs. If a calculation -ever halts incorrectly with the message ``Computation got stuck or -ran too long,'' use the @kbd{M} command (@code{calc-more-recursion-depth}) -to increase this limit. (Of course, this will not help if the -calculation really did get stuck due to some problem inside Calc.) - -The limit is always increased (multiplied) by a factor of two. There -is also an @kbd{I M} (@code{calc-less-recursion-depth}) command which -decreases this limit by a factor of two, down to a minimum value of 200. -The default value is 1000. - -These commands also double or halve @code{max-specpdl-size}, another -internal Lisp recursion limit. The minimum value for this limit is 600. - -@node Caches, Debugging Calc, Recursion Depth, Troubleshooting Commands -@subsection Caches - -@noindent -@cindex Caches -@cindex Flushing caches -Calc saves certain values after they have been computed once. For -example, the @kbd{P} (@code{calc-pi}) command initially ``knows'' the -constant @cpi{} to about 20 decimal places; if the current precision -is greater than this, it will recompute @cpi{} using a series -approximation. This value will not need to be recomputed ever again -unless you raise the precision still further. Many operations such as -logarithms and sines make use of similarly cached values such as -@cpiover{4} and -@texline @math{\ln 2}. -@infoline @expr{ln(2)}. -The visible effect of caching is that -high-precision computations may seem to do extra work the first time. -Other things cached include powers of two (for the binary arithmetic -functions), matrix inverses and determinants, symbolic integrals, and -data points computed by the graphing commands. - -@pindex calc-flush-caches -If you suspect a Calculator cache has become corrupt, you can use the -@code{calc-flush-caches} command to reset all caches to the empty state. -(This should only be necessary in the event of bugs in the Calculator.) -The @kbd{C-x * 0} (with the zero key) command also resets caches along -with all other aspects of the Calculator's state. - -@node Debugging Calc, , Caches, Troubleshooting Commands -@subsection Debugging Calc - -@noindent -A few commands exist to help in the debugging of Calc commands. -@xref{Programming}, to see the various ways that you can write -your own Calc commands. - -@kindex Z T -@pindex calc-timing -The @kbd{Z T} (@code{calc-timing}) command turns on and off a mode -in which the timing of slow commands is reported in the Trail. -Any Calc command that takes two seconds or longer writes a line -to the Trail showing how many seconds it took. This value is -accurate only to within one second. - -All steps of executing a command are included; in particular, time -taken to format the result for display in the stack and trail is -counted. Some prompts also count time taken waiting for them to -be answered, while others do not; this depends on the exact -implementation of the command. For best results, if you are timing -a sequence that includes prompts or multiple commands, define a -keyboard macro to run the whole sequence at once. Calc's @kbd{X} -command (@pxref{Keyboard Macros}) will then report the time taken -to execute the whole macro. - -Another advantage of the @kbd{X} command is that while it is -executing, the stack and trail are not updated from step to step. -So if you expect the output of your test sequence to leave a result -that may take a long time to format and you don't wish to count -this formatting time, end your sequence with a @key{DEL} keystroke -to clear the result from the stack. When you run the sequence with -@kbd{X}, Calc will never bother to format the large result. - -Another thing @kbd{Z T} does is to increase the Emacs variable -@code{gc-cons-threshold} to a much higher value (two million; the -usual default in Calc is 250,000) for the duration of each command. -This generally prevents garbage collection during the timing of -the command, though it may cause your Emacs process to grow -abnormally large. (Garbage collection time is a major unpredictable -factor in the timing of Emacs operations.) - -Another command that is useful when debugging your own Lisp -extensions to Calc is @kbd{M-x calc-pass-errors}, which disables -the error handler that changes the ``@code{max-lisp-eval-depth} -exceeded'' message to the much more friendly ``Computation got -stuck or ran too long.'' This handler interferes with the Emacs -Lisp debugger's @code{debug-on-error} mode. Errors are reported -in the handler itself rather than at the true location of the -error. After you have executed @code{calc-pass-errors}, Lisp -errors will be reported correctly but the user-friendly message -will be lost. - -@node Data Types, Stack and Trail, Introduction, Top -@chapter Data Types - -@noindent -This chapter discusses the various types of objects that can be placed -on the Calculator stack, how they are displayed, and how they are -entered. (@xref{Data Type Formats}, for information on how these data -types are represented as underlying Lisp objects.) - -Integers, fractions, and floats are various ways of describing real -numbers. HMS forms also for many purposes act as real numbers. These -types can be combined to form complex numbers, modulo forms, error forms, -or interval forms. (But these last four types cannot be combined -arbitrarily:@: error forms may not contain modulo forms, for example.) -Finally, all these types of numbers may be combined into vectors, -matrices, or algebraic formulas. - -@menu -* Integers:: The most basic data type. -* Fractions:: This and above are called @dfn{rationals}. -* Floats:: This and above are called @dfn{reals}. -* Complex Numbers:: This and above are called @dfn{numbers}. -* Infinities:: -* Vectors and Matrices:: -* Strings:: -* HMS Forms:: -* Date Forms:: -* Modulo Forms:: -* Error Forms:: -* Interval Forms:: -* Incomplete Objects:: -* Variables:: -* Formulas:: -@end menu - -@node Integers, Fractions, Data Types, Data Types -@section Integers - -@noindent -@cindex Integers -The Calculator stores integers to arbitrary precision. Addition, -subtraction, and multiplication of integers always yields an exact -integer result. (If the result of a division or exponentiation of -integers is not an integer, it is expressed in fractional or -floating-point form according to the current Fraction mode. -@xref{Fraction Mode}.) - -A decimal integer is represented as an optional sign followed by a -sequence of digits. Grouping (@pxref{Grouping Digits}) can be used to -insert a comma at every third digit for display purposes, but you -must not type commas during the entry of numbers. - -@kindex # -A non-decimal integer is represented as an optional sign, a radix -between 2 and 36, a @samp{#} symbol, and one or more digits. For radix 11 -and above, the letters A through Z (upper- or lower-case) count as -digits and do not terminate numeric entry mode. @xref{Radix Modes}, for how -to set the default radix for display of integers. Numbers of any radix -may be entered at any time. If you press @kbd{#} at the beginning of a -number, the current display radix is used. - -@node Fractions, Floats, Integers, Data Types -@section Fractions - -@noindent -@cindex Fractions -A @dfn{fraction} is a ratio of two integers. Fractions are traditionally -written ``2/3'' but Calc uses the notation @samp{2:3}. (The @kbd{/} key -performs RPN division; the following two sequences push the number -@samp{2:3} on the stack: @kbd{2 :@: 3 @key{RET}}, or @kbd{2 @key{RET} 3 /} -assuming Fraction mode has been enabled.) -When the Calculator produces a fractional result it always reduces it to -simplest form, which may in fact be an integer. - -Fractions may also be entered in a three-part form, where @samp{2:3:4} -represents two-and-three-quarters. @xref{Fraction Formats}, for fraction -display formats. - -Non-decimal fractions are entered and displayed as -@samp{@var{radix}#@var{num}:@var{denom}} (or in the analogous three-part -form). The numerator and denominator always use the same radix. - -@node Floats, Complex Numbers, Fractions, Data Types -@section Floats - -@noindent -@cindex Floating-point numbers -A floating-point number or @dfn{float} is a number stored in scientific -notation. The number of significant digits in the fractional part is -governed by the current floating precision (@pxref{Precision}). The -range of acceptable values is from -@texline @math{10^{-3999999}} -@infoline @expr{10^-3999999} -(inclusive) to -@texline @math{10^{4000000}} -@infoline @expr{10^4000000} -(exclusive), plus the corresponding negative values and zero. - -Calculations that would exceed the allowable range of values (such -as @samp{exp(exp(20))}) are left in symbolic form by Calc. The -messages ``floating-point overflow'' or ``floating-point underflow'' -indicate that during the calculation a number would have been produced -that was too large or too close to zero, respectively, to be represented -by Calc. This does not necessarily mean the final result would have -overflowed, just that an overflow occurred while computing the result. -(In fact, it could report an underflow even though the final result -would have overflowed!) - -If a rational number and a float are mixed in a calculation, the result -will in general be expressed as a float. Commands that require an integer -value (such as @kbd{k g} [@code{gcd}]) will also accept integer-valued -floats, i.e., floating-point numbers with nothing after the decimal point. - -Floats are identified by the presence of a decimal point and/or an -exponent. In general a float consists of an optional sign, digits -including an optional decimal point, and an optional exponent consisting -of an @samp{e}, an optional sign, and up to seven exponent digits. -For example, @samp{23.5e-2} is 23.5 times ten to the minus-second power, -or 0.235. - -Floating-point numbers are normally displayed in decimal notation with -all significant figures shown. Exceedingly large or small numbers are -displayed in scientific notation. Various other display options are -available. @xref{Float Formats}. - -@cindex Accuracy of calculations -Floating-point numbers are stored in decimal, not binary. The result -of each operation is rounded to the nearest value representable in the -number of significant digits specified by the current precision, -rounding away from zero in the case of a tie. Thus (in the default -display mode) what you see is exactly what you get. Some operations such -as square roots and transcendental functions are performed with several -digits of extra precision and then rounded down, in an effort to make the -final result accurate to the full requested precision. However, -accuracy is not rigorously guaranteed. If you suspect the validity of a -result, try doing the same calculation in a higher precision. The -Calculator's arithmetic is not intended to be IEEE-conformant in any -way. - -While floats are always @emph{stored} in decimal, they can be entered -and displayed in any radix just like integers and fractions. Since a -float that is entered in a radix other that 10 will be converted to -decimal, the number that Calc stores may not be exactly the number that -was entered, it will be the closest decimal approximation given the -current precision. The notation @samp{@var{radix}#@var{ddd}.@var{ddd}} -is a floating-point number whose digits are in the specified radix. -Note that the @samp{.} is more aptly referred to as a ``radix point'' -than as a decimal point in this case. The number @samp{8#123.4567} is -defined as @samp{8#1234567 * 8^-4}. If the radix is 14 or less, you can -use @samp{e} notation to write a non-decimal number in scientific -notation. The exponent is written in decimal, and is considered to be a -power of the radix: @samp{8#1234567e-4}. If the radix is 15 or above, -the letter @samp{e} is a digit, so scientific notation must be written -out, e.g., @samp{16#123.4567*16^2}. The first two exercises of the -Modes Tutorial explore some of the properties of non-decimal floats. - -@node Complex Numbers, Infinities, Floats, Data Types -@section Complex Numbers - -@noindent -@cindex Complex numbers -There are two supported formats for complex numbers: rectangular and -polar. The default format is rectangular, displayed in the form -@samp{(@var{real},@var{imag})} where @var{real} is the real part and -@var{imag} is the imaginary part, each of which may be any real number. -Rectangular complex numbers can also be displayed in @samp{@var{a}+@var{b}i} -notation; @pxref{Complex Formats}. - -Polar complex numbers are displayed in the form -@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}' -@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}' -where @var{r} is the nonnegative magnitude and -@texline @math{\theta} -@infoline @var{theta} -is the argument or phase angle. The range of -@texline @math{\theta} -@infoline @var{theta} -depends on the current angular mode (@pxref{Angular Modes}); it is -generally between @mathit{-180} and @mathit{+180} degrees or the equivalent range -in radians. - -Complex numbers are entered in stages using incomplete objects. -@xref{Incomplete Objects}. - -Operations on rectangular complex numbers yield rectangular complex -results, and similarly for polar complex numbers. Where the two types -are mixed, or where new complex numbers arise (as for the square root of -a negative real), the current @dfn{Polar mode} is used to determine the -type. @xref{Polar Mode}. - -A complex result in which the imaginary part is zero (or the phase angle -is 0 or 180 degrees or @cpi{} radians) is automatically converted to a real -number. - -@node Infinities, Vectors and Matrices, Complex Numbers, Data Types -@section Infinities - -@noindent -@cindex Infinity -@cindex @code{inf} variable -@cindex @code{uinf} variable -@cindex @code{nan} variable -@vindex inf -@vindex uinf -@vindex nan -The word @code{inf} represents the mathematical concept of @dfn{infinity}. -Calc actually has three slightly different infinity-like values: -@code{inf}, @code{uinf}, and @code{nan}. These are just regular -variable names (@pxref{Variables}); you should avoid using these -names for your own variables because Calc gives them special -treatment. Infinities, like all variable names, are normally -entered using algebraic entry. - -Mathematically speaking, it is not rigorously correct to treat -``infinity'' as if it were a number, but mathematicians often do -so informally. When they say that @samp{1 / inf = 0}, what they -really mean is that @expr{1 / x}, as @expr{x} becomes larger and -larger, becomes arbitrarily close to zero. So you can imagine -that if @expr{x} got ``all the way to infinity,'' then @expr{1 / x} -would go all the way to zero. Similarly, when they say that -@samp{exp(inf) = inf}, they mean that -@texline @math{e^x} -@infoline @expr{exp(x)} -grows without bound as @expr{x} grows. The symbol @samp{-inf} likewise -stands for an infinitely negative real value; for example, we say that -@samp{exp(-inf) = 0}. You can have an infinity pointing in any -direction on the complex plane: @samp{sqrt(-inf) = i inf}. - -The same concept of limits can be used to define @expr{1 / 0}. We -really want the value that @expr{1 / x} approaches as @expr{x} -approaches zero. But if all we have is @expr{1 / 0}, we can't -tell which direction @expr{x} was coming from. If @expr{x} was -positive and decreasing toward zero, then we should say that -@samp{1 / 0 = inf}. But if @expr{x} was negative and increasing -toward zero, the answer is @samp{1 / 0 = -inf}. In fact, @expr{x} -could be an imaginary number, giving the answer @samp{i inf} or -@samp{-i inf}. Calc uses the special symbol @samp{uinf} to mean -@dfn{undirected infinity}, i.e., a value which is infinitely -large but with an unknown sign (or direction on the complex plane). - -Calc actually has three modes that say how infinities are handled. -Normally, infinities never arise from calculations that didn't -already have them. Thus, @expr{1 / 0} is treated simply as an -error and left unevaluated. The @kbd{m i} (@code{calc-infinite-mode}) -command (@pxref{Infinite Mode}) enables a mode in which -@expr{1 / 0} evaluates to @code{uinf} instead. There is also -an alternative type of infinite mode which says to treat zeros -as if they were positive, so that @samp{1 / 0 = inf}. While this -is less mathematically correct, it may be the answer you want in -some cases. - -Since all infinities are ``as large'' as all others, Calc simplifies, -e.g., @samp{5 inf} to @samp{inf}. Another example is -@samp{5 - inf = -inf}, where the @samp{-inf} is so large that -adding a finite number like five to it does not affect it. -Note that @samp{a - inf} also results in @samp{-inf}; Calc assumes -that variables like @code{a} always stand for finite quantities. -Just to show that infinities really are all the same size, -note that @samp{sqrt(inf) = inf^2 = exp(inf) = inf} in Calc's -notation. - -It's not so easy to define certain formulas like @samp{0 * inf} and -@samp{inf / inf}. Depending on where these zeros and infinities -came from, the answer could be literally anything. The latter -formula could be the limit of @expr{x / x} (giving a result of one), -or @expr{2 x / x} (giving two), or @expr{x^2 / x} (giving @code{inf}), -or @expr{x / x^2} (giving zero). Calc uses the symbol @code{nan} -to represent such an @dfn{indeterminate} value. (The name ``nan'' -comes from analogy with the ``NAN'' concept of IEEE standard -arithmetic; it stands for ``Not A Number.'' This is somewhat of a -misnomer, since @code{nan} @emph{does} stand for some number or -infinity, it's just that @emph{which} number it stands for -cannot be determined.) In Calc's notation, @samp{0 * inf = nan} -and @samp{inf / inf = nan}. A few other common indeterminate -expressions are @samp{inf - inf} and @samp{inf ^ 0}. Also, -@samp{0 / 0 = nan} if you have turned on Infinite mode -(as described above). - -Infinities are especially useful as parts of @dfn{intervals}. -@xref{Interval Forms}. - -@node Vectors and Matrices, Strings, Infinities, Data Types -@section Vectors and Matrices - -@noindent -@cindex Vectors -@cindex Plain vectors -@cindex Matrices -The @dfn{vector} data type is flexible and general. A vector is simply a -list of zero or more data objects. When these objects are numbers, the -whole is a vector in the mathematical sense. When these objects are -themselves vectors of equal (nonzero) length, the whole is a @dfn{matrix}. -A vector which is not a matrix is referred to here as a @dfn{plain vector}. - -A vector is displayed as a list of values separated by commas and enclosed -in square brackets: @samp{[1, 2, 3]}. Thus the following is a 2 row by -3 column matrix: @samp{[[1, 2, 3], [4, 5, 6]]}. Vectors, like complex -numbers, are entered as incomplete objects. @xref{Incomplete Objects}. -During algebraic entry, vectors are entered all at once in the usual -brackets-and-commas form. Matrices may be entered algebraically as nested -vectors, or using the shortcut notation @w{@samp{[1, 2, 3; 4, 5, 6]}}, -with rows separated by semicolons. The commas may usually be omitted -when entering vectors: @samp{[1 2 3]}. Curly braces may be used in -place of brackets: @samp{@{1, 2, 3@}}, but the commas are required in -this case. - -Traditional vector and matrix arithmetic is also supported; -@pxref{Basic Arithmetic} and @pxref{Matrix Functions}. -Many other operations are applied to vectors element-wise. For example, -the complex conjugate of a vector is a vector of the complex conjugates -of its elements. - -@ignore -@starindex -@end ignore -@tindex vec -Algebraic functions for building vectors include @samp{vec(a, b, c)} -to build @samp{[a, b, c]}, @samp{cvec(a, n, m)} to build an -@texline @math{n\times m} -@infoline @var{n}x@var{m} -matrix of @samp{a}s, and @samp{index(n)} to build a vector of integers -from 1 to @samp{n}. - -@node Strings, HMS Forms, Vectors and Matrices, Data Types -@section Strings - -@noindent -@kindex " -@cindex Strings -@cindex Character strings -Character strings are not a special data type in the Calculator. -Rather, a string is represented simply as a vector all of whose -elements are integers in the range 0 to 255 (ASCII codes). You can -enter a string at any time by pressing the @kbd{"} key. Quotation -marks and backslashes are written @samp{\"} and @samp{\\}, respectively, -inside strings. Other notations introduced by backslashes are: - -@example -@group -\a 7 \^@@ 0 -\b 8 \^a-z 1-26 -\e 27 \^[ 27 -\f 12 \^\\ 28 -\n 10 \^] 29 -\r 13 \^^ 30 -\t 9 \^_ 31 - \^? 127 -@end group -@end example - -@noindent -Finally, a backslash followed by three octal digits produces any -character from its ASCII code. - -@kindex d " -@pindex calc-display-strings -Strings are normally displayed in vector-of-integers form. The -@w{@kbd{d "}} (@code{calc-display-strings}) command toggles a mode in -which any vectors of small integers are displayed as quoted strings -instead. - -The backslash notations shown above are also used for displaying -strings. Characters 128 and above are not translated by Calc; unless -you have an Emacs modified for 8-bit fonts, these will show up in -backslash-octal-digits notation. For characters below 32, and -for character 127, Calc uses the backslash-letter combination if -there is one, or otherwise uses a @samp{\^} sequence. - -The only Calc feature that uses strings is @dfn{compositions}; -@pxref{Compositions}. Strings also provide a convenient -way to do conversions between ASCII characters and integers. - -@ignore -@starindex -@end ignore -@tindex string -There is a @code{string} function which provides a different display -format for strings. Basically, @samp{string(@var{s})}, where @var{s} -is a vector of integers in the proper range, is displayed as the -corresponding string of characters with no surrounding quotation -marks or other modifications. Thus @samp{string("ABC")} (or -@samp{string([65 66 67])}) will look like @samp{ABC} on the stack. -This happens regardless of whether @w{@kbd{d "}} has been used. The -only way to turn it off is to use @kbd{d U} (unformatted language -mode) which will display @samp{string("ABC")} instead. - -Control characters are displayed somewhat differently by @code{string}. -Characters below 32, and character 127, are shown using @samp{^} notation -(same as shown above, but without the backslash). The quote and -backslash characters are left alone, as are characters 128 and above. - -@ignore -@starindex -@end ignore -@tindex bstring -The @code{bstring} function is just like @code{string} except that -the resulting string is breakable across multiple lines if it doesn't -fit all on one line. Potential break points occur at every space -character in the string. - -@node HMS Forms, Date Forms, Strings, Data Types -@section HMS Forms - -@noindent -@cindex Hours-minutes-seconds forms -@cindex Degrees-minutes-seconds forms -@dfn{HMS} stands for Hours-Minutes-Seconds; when used as an angular -argument, the interpretation is Degrees-Minutes-Seconds. All functions -that operate on angles accept HMS forms. These are interpreted as -degrees regardless of the current angular mode. It is also possible to -use HMS as the angular mode so that calculated angles are expressed in -degrees, minutes, and seconds. - -@kindex @@ -@ignore -@mindex @null -@end ignore -@kindex ' (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex " (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex h (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex o (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex m (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex s (HMS forms) -The default format for HMS values is -@samp{@var{hours}@@ @var{mins}' @var{secs}"}. During entry, the letters -@samp{h} (for ``hours'') or -@samp{o} (approximating the ``degrees'' symbol) are accepted as well as -@samp{@@}, @samp{m} is accepted in place of @samp{'}, and @samp{s} is -accepted in place of @samp{"}. -The @var{hours} value is an integer (or integer-valued float). -The @var{mins} value is an integer or integer-valued float between 0 and 59. -The @var{secs} value is a real number between 0 (inclusive) and 60 -(exclusive). A positive HMS form is interpreted as @var{hours} + -@var{mins}/60 + @var{secs}/3600. A negative HMS form is interpreted -as @mathit{- @var{hours}} @mathit{-} @var{mins}/60 @mathit{-} @var{secs}/3600. -Display format for HMS forms is quite flexible. @xref{HMS Formats}. - -HMS forms can be added and subtracted. When they are added to numbers, -the numbers are interpreted according to the current angular mode. HMS -forms can also be multiplied and divided by real numbers. Dividing -two HMS forms produces a real-valued ratio of the two angles. - -@pindex calc-time -@cindex Time of day -Just for kicks, @kbd{M-x calc-time} pushes the current time of day on -the stack as an HMS form. - -@node Date Forms, Modulo Forms, HMS Forms, Data Types -@section Date Forms - -@noindent -@cindex Date forms -A @dfn{date form} represents a date and possibly an associated time. -Simple date arithmetic is supported: Adding a number to a date -produces a new date shifted by that many days; adding an HMS form to -a date shifts it by that many hours. Subtracting two date forms -computes the number of days between them (represented as a simple -number). Many other operations, such as multiplying two date forms, -are nonsensical and are not allowed by Calc. - -Date forms are entered and displayed enclosed in @samp{< >} brackets. -The default format is, e.g., @samp{} for dates, -or @samp{<3:32:20pm Wed Jan 9, 1991>} for dates with times. -Input is flexible; date forms can be entered in any of the usual -notations for dates and times. @xref{Date Formats}. - -Date forms are stored internally as numbers, specifically the number -of days since midnight on the morning of January 1 of the year 1 AD. -If the internal number is an integer, the form represents a date only; -if the internal number is a fraction or float, the form represents -a date and time. For example, @samp{<6:00am Wed Jan 9, 1991>} -is represented by the number 726842.25. The standard precision of -12 decimal digits is enough to ensure that a (reasonable) date and -time can be stored without roundoff error. - -If the current precision is greater than 12, date forms will keep -additional digits in the seconds position. For example, if the -precision is 15, the seconds will keep three digits after the -decimal point. Decreasing the precision below 12 may cause the -time part of a date form to become inaccurate. This can also happen -if astronomically high years are used, though this will not be an -issue in everyday (or even everymillennium) use. Note that date -forms without times are stored as exact integers, so roundoff is -never an issue for them. - -You can use the @kbd{v p} (@code{calc-pack}) and @kbd{v u} -(@code{calc-unpack}) commands to get at the numerical representation -of a date form. @xref{Packing and Unpacking}. - -Date forms can go arbitrarily far into the future or past. Negative -year numbers represent years BC. Calc uses a combination of the -Gregorian and Julian calendars, following the history of Great -Britain and the British colonies. This is the same calendar that -is used by the @code{cal} program in most Unix implementations. - -@cindex Julian calendar -@cindex Gregorian calendar -Some historical background: The Julian calendar was created by -Julius Caesar in the year 46 BC as an attempt to fix the gradual -drift caused by the lack of leap years in the calendar used -until that time. The Julian calendar introduced an extra day in -all years divisible by four. After some initial confusion, the -calendar was adopted around the year we call 8 AD. Some centuries -later it became apparent that the Julian year of 365.25 days was -itself not quite right. In 1582 Pope Gregory XIII introduced the -Gregorian calendar, which added the new rule that years divisible -by 100, but not by 400, were not to be considered leap years -despite being divisible by four. Many countries delayed adoption -of the Gregorian calendar because of religious differences; -in Britain it was put off until the year 1752, by which time -the Julian calendar had fallen eleven days behind the true -seasons. So the switch to the Gregorian calendar in early -September 1752 introduced a discontinuity: The day after -Sep 2, 1752 is Sep 14, 1752. Calc follows this convention. -To take another example, Russia waited until 1918 before -adopting the new calendar, and thus needed to remove thirteen -days (between Feb 1, 1918 and Feb 14, 1918). This means that -Calc's reckoning will be inconsistent with Russian history between -1752 and 1918, and similarly for various other countries. - -Today's timekeepers introduce an occasional ``leap second'' as -well, but Calc does not take these minor effects into account. -(If it did, it would have to report a non-integer number of days -between, say, @samp{<12:00am Mon Jan 1, 1900>} and -@samp{<12:00am Sat Jan 1, 2000>}.) - -Calc uses the Julian calendar for all dates before the year 1752, -including dates BC when the Julian calendar technically had not -yet been invented. Thus the claim that day number @mathit{-10000} is -called ``August 16, 28 BC'' should be taken with a grain of salt. - -Please note that there is no ``year 0''; the day before -@samp{} is @samp{}. These are -days 0 and @mathit{-1} respectively in Calc's internal numbering scheme. - -@cindex Julian day counting -Another day counting system in common use is, confusingly, also called -``Julian.'' The Julian day number is the numbers of days since -12:00 noon (GMT) on Jan 1, 4713 BC, which in Calc's scheme (in GMT) -is @mathit{-1721423.5} (recall that Calc starts at midnight instead -of noon). Thus to convert a Calc date code obtained by unpacking a -date form into a Julian day number, simply add 1721423.5 after -compensating for the time zone difference. The built-in @kbd{t J} -command performs this conversion for you. - -The Julian day number is based on the Julian cycle, which was invented -in 1583 by Joseph Justus Scaliger. Scaliger named it the Julian cycle -since it involves the Julian calendar, but some have suggested that -Scaliger named it in honor of his father, Julius Caesar Scaliger. The -Julian cycle is based on three other cycles: the indiction cycle, the -Metonic cycle, and the solar cycle. The indiction cycle is a 15 year -cycle originally used by the Romans for tax purposes but later used to -date medieval documents. The Metonic cycle is a 19 year cycle; 19 -years is close to being a common multiple of a solar year and a lunar -month, and so every 19 years the phases of the moon will occur on the -same days of the year. The solar cycle is a 28 year cycle; the Julian -calendar repeats itself every 28 years. The smallest time period -which contains multiples of all three cycles is the least common -multiple of 15 years, 19 years and 28 years, which (since they're -pairwise relatively prime) is -@texline @math{15\times 19\times 28 = 7980} years. -@infoline 15*19*28 = 7980 years. -This is the length of a Julian cycle. Working backwards, the previous -year in which all three cycles began was 4713 BC, and so Scaliger -chose that year as the beginning of a Julian cycle. Since at the time -there were no historical records from before 4713 BC, using this year -as a starting point had the advantage of avoiding negative year -numbers. In 1849, the astronomer John Herschel (son of William -Herschel) suggested using the number of days since the beginning of -the Julian cycle as an astronomical dating system; this idea was taken -up by other astronomers. (At the time, noon was the start of the -astronomical day. Herschel originally suggested counting the days -since Jan 1, 4713 BC at noon Alexandria time; this was later amended to -noon GMT.) Julian day numbering is largely used in astronomy. - -@cindex Unix time format -The Unix operating system measures time as an integer number of -seconds since midnight, Jan 1, 1970. To convert a Calc date -value into a Unix time stamp, first subtract 719164 (the code -for @samp{}), then multiply by 86400 (the number of -seconds in a day) and press @kbd{R} to round to the nearest -integer. If you have a date form, you can simply subtract the -day @samp{} instead of unpacking and subtracting -719164. Likewise, divide by 86400 and add @samp{} -to convert from Unix time to a Calc date form. (Note that -Unix normally maintains the time in the GMT time zone; you may -need to subtract five hours to get New York time, or eight hours -for California time. The same is usually true of Julian day -counts.) The built-in @kbd{t U} command performs these -conversions. - -@node Modulo Forms, Error Forms, Date Forms, Data Types -@section Modulo Forms - -@noindent -@cindex Modulo forms -A @dfn{modulo form} is a real number which is taken modulo (i.e., within -an integer multiple of) some value @var{M}. Arithmetic modulo @var{M} -often arises in number theory. Modulo forms are written -`@var{a} @tfn{mod} @var{M}', -where @var{a} and @var{M} are real numbers or HMS forms, and -@texline @math{0 \le a < M}. -@infoline @expr{0 <= a < @var{M}}. -In many applications @expr{a} and @expr{M} will be -integers but this is not required. - -@ignore -@mindex M -@end ignore -@kindex M (modulo forms) -@ignore -@mindex mod -@end ignore -@tindex mod (operator) -To create a modulo form during numeric entry, press the shift-@kbd{M} -key to enter the word @samp{mod}. As a special convenience, pressing -shift-@kbd{M} a second time automatically enters the value of @expr{M} -that was most recently used before. During algebraic entry, either -type @samp{mod} by hand or press @kbd{M-m} (that's @kbd{@key{META}-m}). -Once again, pressing this a second time enters the current modulo. - -Modulo forms are not to be confused with the modulo operator @samp{%}. -The expression @samp{27 % 10} means to compute 27 modulo 10 to produce -the result 7. Further computations treat this 7 as just a regular integer. -The expression @samp{27 mod 10} produces the result @samp{7 mod 10}; -further computations with this value are again reduced modulo 10 so that -the result always lies in the desired range. - -When two modulo forms with identical @expr{M}'s are added or multiplied, -the Calculator simply adds or multiplies the values, then reduces modulo -@expr{M}. If one argument is a modulo form and the other a plain number, -the plain number is treated like a compatible modulo form. It is also -possible to raise modulo forms to powers; the result is the value raised -to the power, then reduced modulo @expr{M}. (When all values involved -are integers, this calculation is done much more efficiently than -actually computing the power and then reducing.) - -@cindex Modulo division -Two modulo forms `@var{a} @tfn{mod} @var{M}' and `@var{b} @tfn{mod} @var{M}' -can be divided if @expr{a}, @expr{b}, and @expr{M} are all -integers. The result is the modulo form which, when multiplied by -`@var{b} @tfn{mod} @var{M}', produces `@var{a} @tfn{mod} @var{M}'. If -there is no solution to this equation (which can happen only when -@expr{M} is non-prime), or if any of the arguments are non-integers, the -division is left in symbolic form. Other operations, such as square -roots, are not yet supported for modulo forms. (Note that, although -@w{`@tfn{(}@var{a} @tfn{mod} @var{M}@tfn{)^.5}'} will compute a ``modulo square root'' -in the sense of reducing -@texline @math{\sqrt a} -@infoline @expr{sqrt(a)} -modulo @expr{M}, this is not a useful definition from the -number-theoretical point of view.) - -It is possible to mix HMS forms and modulo forms. For example, an -HMS form modulo 24 could be used to manipulate clock times; an HMS -form modulo 360 would be suitable for angles. Making the modulo @expr{M} -also be an HMS form eliminates troubles that would arise if the angular -mode were inadvertently set to Radians, in which case -@w{@samp{2@@ 0' 0" mod 24}} would be interpreted as two degrees modulo -24 radians! - -Modulo forms cannot have variables or formulas for components. If you -enter the formula @samp{(x + 2) mod 5}, Calc propagates the modulus -to each of the coefficients: @samp{(1 mod 5) x + (2 mod 5)}. - -You can use @kbd{v p} and @kbd{%} to modify modulo forms. -@xref{Packing and Unpacking}. @xref{Basic Arithmetic}. - -@ignore -@starindex -@end ignore -@tindex makemod -The algebraic function @samp{makemod(a, m)} builds the modulo form -@w{@samp{a mod m}}. - -@node Error Forms, Interval Forms, Modulo Forms, Data Types -@section Error Forms - -@noindent -@cindex Error forms -@cindex Standard deviations -An @dfn{error form} is a number with an associated standard -deviation, as in @samp{2.3 +/- 0.12}. The notation -@texline `@var{x} @tfn{+/-} @math{\sigma}' -@infoline `@var{x} @tfn{+/-} sigma' -stands for an uncertain value which follows -a normal or Gaussian distribution of mean @expr{x} and standard -deviation or ``error'' -@texline @math{\sigma}. -@infoline @expr{sigma}. -Both the mean and the error can be either numbers or -formulas. Generally these are real numbers but the mean may also be -complex. If the error is negative or complex, it is changed to its -absolute value. An error form with zero error is converted to a -regular number by the Calculator. - -All arithmetic and transcendental functions accept error forms as input. -Operations on the mean-value part work just like operations on regular -numbers. The error part for any function @expr{f(x)} (such as -@texline @math{\sin x} -@infoline @expr{sin(x)}) -is defined by the error of @expr{x} times the derivative of @expr{f} -evaluated at the mean value of @expr{x}. For a two-argument function -@expr{f(x,y)} (such as addition) the error is the square root of the sum -of the squares of the errors due to @expr{x} and @expr{y}. -@tex -$$ \eqalign{ - f(x \hbox{\code{ +/- }} \sigma) - &= f(x) \hbox{\code{ +/- }} \sigma \left| {df(x) \over dx} \right| \cr - f(x \hbox{\code{ +/- }} \sigma_x, y \hbox{\code{ +/- }} \sigma_y) - &= f(x,y) \hbox{\code{ +/- }} - \sqrt{\left(\sigma_x \left| {\partial f(x,y) \over \partial x} - \right| \right)^2 - +\left(\sigma_y \left| {\partial f(x,y) \over \partial y} - \right| \right)^2 } \cr -} $$ -@end tex -Note that this -definition assumes the errors in @expr{x} and @expr{y} are uncorrelated. -A side effect of this definition is that @samp{(2 +/- 1) * (2 +/- 1)} -is not the same as @samp{(2 +/- 1)^2}; the former represents the product -of two independent values which happen to have the same probability -distributions, and the latter is the product of one random value with itself. -The former will produce an answer with less error, since on the average -the two independent errors can be expected to cancel out. - -Consult a good text on error analysis for a discussion of the proper use -of standard deviations. Actual errors often are neither Gaussian-distributed -nor uncorrelated, and the above formulas are valid only when errors -are small. As an example, the error arising from -@texline `@tfn{sin(}@var{x} @tfn{+/-} @math{\sigma}@tfn{)}' -@infoline `@tfn{sin(}@var{x} @tfn{+/-} @var{sigma}@tfn{)}' -is -@texline `@math{\sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. -@infoline `@var{sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. -When @expr{x} is close to zero, -@texline @math{\cos x} -@infoline @expr{cos(x)} -is close to one so the error in the sine is close to -@texline @math{\sigma}; -@infoline @expr{sigma}; -this makes sense, since -@texline @math{\sin x} -@infoline @expr{sin(x)} -is approximately @expr{x} near zero, so a given error in @expr{x} will -produce about the same error in the sine. Likewise, near 90 degrees -@texline @math{\cos x} -@infoline @expr{cos(x)} -is nearly zero and so the computed error is -small: The sine curve is nearly flat in that region, so an error in @expr{x} -has relatively little effect on the value of -@texline @math{\sin x}. -@infoline @expr{sin(x)}. -However, consider @samp{sin(90 +/- 1000)}. The cosine of 90 is zero, so -Calc will report zero error! We get an obviously wrong result because -we have violated the small-error approximation underlying the error -analysis. If the error in @expr{x} had been small, the error in -@texline @math{\sin x} -@infoline @expr{sin(x)} -would indeed have been negligible. - -@ignore -@mindex p -@end ignore -@kindex p (error forms) -@tindex +/- -To enter an error form during regular numeric entry, use the @kbd{p} -(``plus-or-minus'') key to type the @samp{+/-} symbol. (If you try actually -typing @samp{+/-} the @kbd{+} key will be interpreted as the Calculator's -@kbd{+} command!) Within an algebraic formula, you can press @kbd{M-+} to -type the @samp{+/-} symbol, or type it out by hand. - -Error forms and complex numbers can be mixed; the formulas shown above -are used for complex numbers, too; note that if the error part evaluates -to a complex number its absolute value (or the square root of the sum of -the squares of the absolute values of the two error contributions) is -used. Mathematically, this corresponds to a radially symmetric Gaussian -distribution of numbers on the complex plane. However, note that Calc -considers an error form with real components to represent a real number, -not a complex distribution around a real mean. - -Error forms may also be composed of HMS forms. For best results, both -the mean and the error should be HMS forms if either one is. - -@ignore -@starindex -@end ignore -@tindex sdev -The algebraic function @samp{sdev(a, b)} builds the error form @samp{a +/- b}. - -@node Interval Forms, Incomplete Objects, Error Forms, Data Types -@section Interval Forms - -@noindent -@cindex Interval forms -An @dfn{interval} is a subset of consecutive real numbers. For example, -the interval @samp{[2 ..@: 4]} represents all the numbers from 2 to 4, -inclusive. If you multiply it by the interval @samp{[0.5 ..@: 2]} you -obtain @samp{[1 ..@: 8]}. This calculation represents the fact that if -you multiply some number in the range @samp{[2 ..@: 4]} by some other -number in the range @samp{[0.5 ..@: 2]}, your result will lie in the range -from 1 to 8. Interval arithmetic is used to get a worst-case estimate -of the possible range of values a computation will produce, given the -set of possible values of the input. - -@ifnottex -Calc supports several varieties of intervals, including @dfn{closed} -intervals of the type shown above, @dfn{open} intervals such as -@samp{(2 ..@: 4)}, which represents the range of numbers from 2 to 4 -@emph{exclusive}, and @dfn{semi-open} intervals in which one end -uses a round parenthesis and the other a square bracket. In mathematical -terms, -@samp{[2 ..@: 4]} means @expr{2 <= x <= 4}, whereas -@samp{[2 ..@: 4)} represents @expr{2 <= x < 4}, -@samp{(2 ..@: 4]} represents @expr{2 < x <= 4}, and -@samp{(2 ..@: 4)} represents @expr{2 < x < 4}. -@end ifnottex -@tex -Calc supports several varieties of intervals, including \dfn{closed} -intervals of the type shown above, \dfn{open} intervals such as -\samp{(2 ..\: 4)}, which represents the range of numbers from 2 to 4 -\emph{exclusive}, and \dfn{semi-open} intervals in which one end -uses a round parenthesis and the other a square bracket. In mathematical -terms, -$$ \eqalign{ - [2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 \le x \le 4 \cr - [2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 \le x < 4 \cr - (2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 < x \le 4 \cr - (2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 < x < 4 \cr -} $$ -@end tex - -The lower and upper limits of an interval must be either real numbers -(or HMS or date forms), or symbolic expressions which are assumed to be -real-valued, or @samp{-inf} and @samp{inf}. In general the lower limit -must be less than the upper limit. A closed interval containing only -one value, @samp{[3 ..@: 3]}, is converted to a plain number (3) -automatically. An interval containing no values at all (such as -@samp{[3 ..@: 2]} or @samp{[2 ..@: 2)}) can be represented but is not -guaranteed to behave well when used in arithmetic. Note that the -interval @samp{[3 .. inf)} represents all real numbers greater than -or equal to 3, and @samp{(-inf .. inf)} represents all real numbers. -In fact, @samp{[-inf .. inf]} represents all real numbers including -the real infinities. - -Intervals are entered in the notation shown here, either as algebraic -formulas, or using incomplete forms. (@xref{Incomplete Objects}.) -In algebraic formulas, multiple periods in a row are collected from -left to right, so that @samp{1...1e2} is interpreted as @samp{1.0 ..@: 1e2} -rather than @samp{1 ..@: 0.1e2}. Add spaces or zeros if you want to -get the other interpretation. If you omit the lower or upper limit, -a default of @samp{-inf} or @samp{inf} (respectively) is furnished. - -Infinite mode also affects operations on intervals -(@pxref{Infinities}). Calc will always introduce an open infinity, -as in @samp{1 / (0 .. 2] = [0.5 .. inf)}. But closed infinities, -@w{@samp{1 / [0 .. 2] = [0.5 .. inf]}}, arise only in Infinite mode; -otherwise they are left unevaluated. Note that the ``direction'' of -a zero is not an issue in this case since the zero is always assumed -to be continuous with the rest of the interval. For intervals that -contain zero inside them Calc is forced to give the result, -@samp{1 / (-2 .. 2) = [-inf .. inf]}. - -While it may seem that intervals and error forms are similar, they are -based on entirely different concepts of inexact quantities. An error -form -@texline `@var{x} @tfn{+/-} @math{\sigma}' -@infoline `@var{x} @tfn{+/-} @var{sigma}' -means a variable is random, and its value could -be anything but is ``probably'' within one -@texline @math{\sigma} -@infoline @var{sigma} -of the mean value @expr{x}. An interval -`@tfn{[}@var{a} @tfn{..@:} @var{b}@tfn{]}' means a -variable's value is unknown, but guaranteed to lie in the specified -range. Error forms are statistical or ``average case'' approximations; -interval arithmetic tends to produce ``worst case'' bounds on an -answer. - -Intervals may not contain complex numbers, but they may contain -HMS forms or date forms. - -@xref{Set Operations}, for commands that interpret interval forms -as subsets of the set of real numbers. - -@ignore -@starindex -@end ignore -@tindex intv -The algebraic function @samp{intv(n, a, b)} builds an interval form -from @samp{a} to @samp{b}; @samp{n} is an integer code which must -be 0 for @samp{(..)}, 1 for @samp{(..]}, 2 for @samp{[..)}, or -3 for @samp{[..]}. - -Please note that in fully rigorous interval arithmetic, care would be -taken to make sure that the computation of the lower bound rounds toward -minus infinity, while upper bound computations round toward plus -infinity. Calc's arithmetic always uses a round-to-nearest mode, -which means that roundoff errors could creep into an interval -calculation to produce intervals slightly smaller than they ought to -be. For example, entering @samp{[1..2]} and pressing @kbd{Q 2 ^} -should yield the interval @samp{[1..2]} again, but in fact it yields the -(slightly too small) interval @samp{[1..1.9999999]} due to roundoff -error. - -@node Incomplete Objects, Variables, Interval Forms, Data Types -@section Incomplete Objects - -@noindent -@ignore -@mindex [ ] -@end ignore -@kindex [ -@ignore -@mindex ( ) -@end ignore -@kindex ( -@kindex , -@ignore -@mindex @null -@end ignore -@kindex ] -@ignore -@mindex @null -@end ignore -@kindex ) -@cindex Incomplete vectors -@cindex Incomplete complex numbers -@cindex Incomplete interval forms -When @kbd{(} or @kbd{[} is typed to begin entering a complex number or -vector, respectively, the effect is to push an @dfn{incomplete} complex -number or vector onto the stack. The @kbd{,} key adds the value(s) at -the top of the stack onto the current incomplete object. The @kbd{)} -and @kbd{]} keys ``close'' the incomplete object after adding any values -on the top of the stack in front of the incomplete object. - -As a result, the sequence of keystrokes @kbd{[ 2 , 3 @key{RET} 2 * , 9 ]} -pushes the vector @samp{[2, 6, 9]} onto the stack. Likewise, @kbd{( 1 , 2 Q )} -pushes the complex number @samp{(1, 1.414)} (approximately). - -If several values lie on the stack in front of the incomplete object, -all are collected and appended to the object. Thus the @kbd{,} key -is redundant: @kbd{[ 2 @key{RET} 3 @key{RET} 2 * 9 ]}. Some people -prefer the equivalent @key{SPC} key to @key{RET}. - -As a special case, typing @kbd{,} immediately after @kbd{(}, @kbd{[}, or -@kbd{,} adds a zero or duplicates the preceding value in the list being -formed. Typing @key{DEL} during incomplete entry removes the last item -from the list. - -@kindex ; -The @kbd{;} key is used in the same way as @kbd{,} to create polar complex -numbers: @kbd{( 1 ; 2 )}. When entering a vector, @kbd{;} is useful for -creating a matrix. In particular, @kbd{[ [ 1 , 2 ; 3 , 4 ; 5 , 6 ] ]} is -equivalent to @kbd{[ [ 1 , 2 ] , [ 3 , 4 ] , [ 5 , 6 ] ]}. - -@kindex .. -@pindex calc-dots -Incomplete entry is also used to enter intervals. For example, -@kbd{[ 2 ..@: 4 )} enters a semi-open interval. Note that when you type -the first period, it will be interpreted as a decimal point, but when -you type a second period immediately afterward, it is re-interpreted as -part of the interval symbol. Typing @kbd{..} corresponds to executing -the @code{calc-dots} command. - -If you find incomplete entry distracting, you may wish to enter vectors -and complex numbers as algebraic formulas by pressing the apostrophe key. - -@node Variables, Formulas, Incomplete Objects, Data Types -@section Variables - -@noindent -@cindex Variables, in formulas -A @dfn{variable} is somewhere between a storage register on a conventional -calculator, and a variable in a programming language. (In fact, a Calc -variable is really just an Emacs Lisp variable that contains a Calc number -or formula.) A variable's name is normally composed of letters and digits. -Calc also allows apostrophes and @code{#} signs in variable names. -(The Calc variable @code{foo} corresponds to the Emacs Lisp variable -@code{var-foo}, but unless you access the variable from within Emacs -Lisp, you don't need to worry about it. Variable names in algebraic -formulas implicitly have @samp{var-} prefixed to their names. The -@samp{#} character in variable names used in algebraic formulas -corresponds to a dash @samp{-} in the Lisp variable name. If the name -contains any dashes, the prefix @samp{var-} is @emph{not} automatically -added. Thus the two formulas @samp{foo + 1} and @samp{var#foo + 1} both -refer to the same variable.) - -In a command that takes a variable name, you can either type the full -name of a variable, or type a single digit to use one of the special -convenience variables @code{q0} through @code{q9}. For example, -@kbd{3 s s 2} stores the number 3 in variable @code{q2}, and -@w{@kbd{3 s s foo @key{RET}}} stores that number in variable -@code{foo}. - -To push a variable itself (as opposed to the variable's value) on the -stack, enter its name as an algebraic expression using the apostrophe -(@key{'}) key. - -@kindex = -@pindex calc-evaluate -@cindex Evaluation of variables in a formula -@cindex Variables, evaluation -@cindex Formulas, evaluation -The @kbd{=} (@code{calc-evaluate}) key ``evaluates'' a formula by -replacing all variables in the formula which have been given values by a -@code{calc-store} or @code{calc-let} command by their stored values. -Other variables are left alone. Thus a variable that has not been -stored acts like an abstract variable in algebra; a variable that has -been stored acts more like a register in a traditional calculator. -With a positive numeric prefix argument, @kbd{=} evaluates the top -@var{n} stack entries; with a negative argument, @kbd{=} evaluates -the @var{n}th stack entry. - -@cindex @code{e} variable -@cindex @code{pi} variable -@cindex @code{i} variable -@cindex @code{phi} variable -@cindex @code{gamma} variable -@vindex e -@vindex pi -@vindex i -@vindex phi -@vindex gamma -A few variables are called @dfn{special constants}. Their names are -@samp{e}, @samp{pi}, @samp{i}, @samp{phi}, and @samp{gamma}. -(@xref{Scientific Functions}.) When they are evaluated with @kbd{=}, -their values are calculated if necessary according to the current precision -or complex polar mode. If you wish to use these symbols for other purposes, -simply undefine or redefine them using @code{calc-store}. - -The variables @samp{inf}, @samp{uinf}, and @samp{nan} stand for -infinite or indeterminate values. It's best not to use them as -regular variables, since Calc uses special algebraic rules when -it manipulates them. Calc displays a warning message if you store -a value into any of these special variables. - -@xref{Store and Recall}, for a discussion of commands dealing with variables. - -@node Formulas, , Variables, Data Types -@section Formulas - -@noindent -@cindex Formulas -@cindex Expressions -@cindex Operators in formulas -@cindex Precedence of operators -When you press the apostrophe key you may enter any expression or formula -in algebraic form. (Calc uses the terms ``expression'' and ``formula'' -interchangeably.) An expression is built up of numbers, variable names, -and function calls, combined with various arithmetic operators. -Parentheses may -be used to indicate grouping. Spaces are ignored within formulas, except -that spaces are not permitted within variable names or numbers. -Arithmetic operators, in order from highest to lowest precedence, and -with their equivalent function names, are: - -@samp{_} [@code{subscr}] (subscripts); - -postfix @samp{%} [@code{percent}] (as in @samp{25% = 0.25}); - -prefix @samp{!} [@code{lnot}] (logical ``not,'' as in @samp{!x}); - -@samp{+/-} [@code{sdev}] (the standard deviation symbol) and -@samp{mod} [@code{makemod}] (the symbol for modulo forms); - -postfix @samp{!} [@code{fact}] (factorial, as in @samp{n!}) -and postfix @samp{!!} [@code{dfact}] (double factorial); - -@samp{^} [@code{pow}] (raised-to-the-power-of); - -prefix @samp{+} and @samp{-} [@code{neg}] (as in @samp{-x}); - -@samp{*} [@code{mul}]; - -@samp{/} [@code{div}], @samp{%} [@code{mod}] (modulo), and -@samp{\} [@code{idiv}] (integer division); - -infix @samp{+} [@code{add}] and @samp{-} [@code{sub}] (as in @samp{x-y}); - -@samp{|} [@code{vconcat}] (vector concatenation); - -relations @samp{=} [@code{eq}], @samp{!=} [@code{neq}], @samp{<} [@code{lt}], -@samp{>} [@code{gt}], @samp{<=} [@code{leq}], and @samp{>=} [@code{geq}]; - -@samp{&&} [@code{land}] (logical ``and''); - -@samp{||} [@code{lor}] (logical ``or''); - -the C-style ``if'' operator @samp{a?b:c} [@code{if}]; - -@samp{!!!} [@code{pnot}] (rewrite pattern ``not''); - -@samp{&&&} [@code{pand}] (rewrite pattern ``and''); - -@samp{|||} [@code{por}] (rewrite pattern ``or''); - -@samp{:=} [@code{assign}] (for assignments and rewrite rules); - -@samp{::} [@code{condition}] (rewrite pattern condition); - -@samp{=>} [@code{evalto}]. - -Note that, unlike in usual computer notation, multiplication binds more -strongly than division: @samp{a*b/c*d} is equivalent to -@texline @math{a b \over c d}. -@infoline @expr{(a*b)/(c*d)}. - -@cindex Multiplication, implicit -@cindex Implicit multiplication -The multiplication sign @samp{*} may be omitted in many cases. In particular, -if the righthand side is a number, variable name, or parenthesized -expression, the @samp{*} may be omitted. Implicit multiplication has the -same precedence as the explicit @samp{*} operator. The one exception to -the rule is that a variable name followed by a parenthesized expression, -as in @samp{f(x)}, -is interpreted as a function call, not an implicit @samp{*}. In many -cases you must use a space if you omit the @samp{*}: @samp{2a} is the -same as @samp{2*a}, and @samp{a b} is the same as @samp{a*b}, but @samp{ab} -is a variable called @code{ab}, @emph{not} the product of @samp{a} and -@samp{b}! Also note that @samp{f (x)} is still a function call. - -@cindex Implicit comma in vectors -The rules are slightly different for vectors written with square brackets. -In vectors, the space character is interpreted (like the comma) as a -separator of elements of the vector. Thus @w{@samp{[ 2a b+c d ]}} is -equivalent to @samp{[2*a, b+c, d]}, whereas @samp{2a b+c d} is equivalent -to @samp{2*a*b + c*d}. -Note that spaces around the brackets, and around explicit commas, are -ignored. To force spaces to be interpreted as multiplication you can -enclose a formula in parentheses as in @samp{[(a b) 2(c d)]}, which is -interpreted as @samp{[a*b, 2*c*d]}. An implicit comma is also inserted -between @samp{][}, as in the matrix @samp{[[1 2][3 4]]}. - -Vectors that contain commas (not embedded within nested parentheses or -brackets) do not treat spaces specially: @samp{[a b, 2 c d]} is a vector -of two elements. Also, if it would be an error to treat spaces as -separators, but not otherwise, then Calc will ignore spaces: -@w{@samp{[a - b]}} is a vector of one element, but @w{@samp{[a -b]}} is -a vector of two elements. Finally, vectors entered with curly braces -instead of square brackets do not give spaces any special treatment. -When Calc displays a vector that does not contain any commas, it will -insert parentheses if necessary to make the meaning clear: -@w{@samp{[(a b)]}}. - -The expression @samp{5%-2} is ambiguous; is this five-percent minus two, -or five modulo minus-two? Calc always interprets the leftmost symbol as -an infix operator preferentially (modulo, in this case), so you would -need to write @samp{(5%)-2} to get the former interpretation. - -@cindex Function call notation -A function call is, e.g., @samp{sin(1+x)}. (The Calc algebraic function -@code{foo} corresponds to the Emacs Lisp function @code{calcFunc-foo}, -but unless you access the function from within Emacs Lisp, you don't -need to worry about it.) Most mathematical Calculator commands like -@code{calc-sin} have function equivalents like @code{sin}. -If no Lisp function is defined for a function called by a formula, the -call is left as it is during algebraic manipulation: @samp{f(x+y)} is -left alone. Beware that many innocent-looking short names like @code{in} -and @code{re} have predefined meanings which could surprise you; however, -single letters or single letters followed by digits are always safe to -use for your own function names. @xref{Function Index}. - -In the documentation for particular commands, the notation @kbd{H S} -(@code{calc-sinh}) [@code{sinh}] means that the key sequence @kbd{H S}, the -command @kbd{M-x calc-sinh}, and the algebraic function @code{sinh(x)} all -represent the same operation. - -Commands that interpret (``parse'') text as algebraic formulas include -algebraic entry (@kbd{'}), editing commands like @kbd{`} which parse -the contents of the editing buffer when you finish, the @kbd{C-x * g} -and @w{@kbd{C-x * r}} commands, the @kbd{C-y} command, the X window system -``paste'' mouse operation, and Embedded mode. All of these operations -use the same rules for parsing formulas; in particular, language modes -(@pxref{Language Modes}) affect them all in the same way. - -When you read a large amount of text into the Calculator (say a vector -which represents a big set of rewrite rules; @pxref{Rewrite Rules}), -you may wish to include comments in the text. Calc's formula parser -ignores the symbol @samp{%%} and anything following it on a line: - -@example -[ a + b, %% the sum of "a" and "b" - c + d, - %% last line is coming up: - e + f ] -@end example - -@noindent -This is parsed exactly the same as @samp{[ a + b, c + d, e + f ]}. - -@xref{Syntax Tables}, for a way to create your own operators and other -input notations. @xref{Compositions}, for a way to create new display -formats. - -@xref{Algebra}, for commands for manipulating formulas symbolically. - -@node Stack and Trail, Mode Settings, Data Types, Top -@chapter Stack and Trail Commands - -@noindent -This chapter describes the Calc commands for manipulating objects on the -stack and in the trail buffer. (These commands operate on objects of any -type, such as numbers, vectors, formulas, and incomplete objects.) - -@menu -* Stack Manipulation:: -* Editing Stack Entries:: -* Trail Commands:: -* Keep Arguments:: -@end menu - -@node Stack Manipulation, Editing Stack Entries, Stack and Trail, Stack and Trail -@section Stack Manipulation Commands - -@noindent -@kindex @key{RET} -@kindex @key{SPC} -@pindex calc-enter -@cindex Duplicating stack entries -To duplicate the top object on the stack, press @key{RET} or @key{SPC} -(two equivalent keys for the @code{calc-enter} command). -Given a positive numeric prefix argument, these commands duplicate -several elements at the top of the stack. -Given a negative argument, -these commands duplicate the specified element of the stack. -Given an argument of zero, they duplicate the entire stack. -For example, with @samp{10 20 30} on the stack, -@key{RET} creates @samp{10 20 30 30}, -@kbd{C-u 2 @key{RET}} creates @samp{10 20 30 20 30}, -@kbd{C-u - 2 @key{RET}} creates @samp{10 20 30 20}, and -@kbd{C-u 0 @key{RET}} creates @samp{10 20 30 10 20 30}. - -@kindex @key{LFD} -@pindex calc-over -The @key{LFD} (@code{calc-over}) command (on a key marked Line-Feed if you -have it, else on @kbd{C-j}) is like @code{calc-enter} -except that the sign of the numeric prefix argument is interpreted -oppositely. Also, with no prefix argument the default argument is 2. -Thus with @samp{10 20 30} on the stack, @key{LFD} and @kbd{C-u 2 @key{LFD}} -are both equivalent to @kbd{C-u - 2 @key{RET}}, producing -@samp{10 20 30 20}. - -@kindex @key{DEL} -@kindex C-d -@pindex calc-pop -@cindex Removing stack entries -@cindex Deleting stack entries -To remove the top element from the stack, press @key{DEL} (@code{calc-pop}). -The @kbd{C-d} key is a synonym for @key{DEL}. -(If the top element is an incomplete object with at least one element, the -last element is removed from it.) Given a positive numeric prefix argument, -several elements are removed. Given a negative argument, the specified -element of the stack is deleted. Given an argument of zero, the entire -stack is emptied. -For example, with @samp{10 20 30} on the stack, -@key{DEL} leaves @samp{10 20}, -@kbd{C-u 2 @key{DEL}} leaves @samp{10}, -@kbd{C-u - 2 @key{DEL}} leaves @samp{10 30}, and -@kbd{C-u 0 @key{DEL}} leaves an empty stack. - -@kindex M-@key{DEL} -@pindex calc-pop-above -The @kbd{M-@key{DEL}} (@code{calc-pop-above}) command is to @key{DEL} what -@key{LFD} is to @key{RET}: It interprets the sign of the numeric -prefix argument in the opposite way, and the default argument is 2. -Thus @kbd{M-@key{DEL}} by itself removes the second-from-top stack element, -leaving the first, third, fourth, and so on; @kbd{M-3 M-@key{DEL}} deletes -the third stack element. - -@kindex @key{TAB} -@pindex calc-roll-down -To exchange the top two elements of the stack, press @key{TAB} -(@code{calc-roll-down}). Given a positive numeric prefix argument, the -specified number of elements at the top of the stack are rotated downward. -Given a negative argument, the entire stack is rotated downward the specified -number of times. Given an argument of zero, the entire stack is reversed -top-for-bottom. -For example, with @samp{10 20 30 40 50} on the stack, -@key{TAB} creates @samp{10 20 30 50 40}, -@kbd{C-u 3 @key{TAB}} creates @samp{10 20 50 30 40}, -@kbd{C-u - 2 @key{TAB}} creates @samp{40 50 10 20 30}, and -@kbd{C-u 0 @key{TAB}} creates @samp{50 40 30 20 10}. - -@kindex M-@key{TAB} -@pindex calc-roll-up -The command @kbd{M-@key{TAB}} (@code{calc-roll-up}) is analogous to @key{TAB} -except that it rotates upward instead of downward. Also, the default -with no prefix argument is to rotate the top 3 elements. -For example, with @samp{10 20 30 40 50} on the stack, -@kbd{M-@key{TAB}} creates @samp{10 20 40 50 30}, -@kbd{C-u 4 M-@key{TAB}} creates @samp{10 30 40 50 20}, -@kbd{C-u - 2 M-@key{TAB}} creates @samp{30 40 50 10 20}, and -@kbd{C-u 0 M-@key{TAB}} creates @samp{50 40 30 20 10}. - -A good way to view the operation of @key{TAB} and @kbd{M-@key{TAB}} is in -terms of moving a particular element to a new position in the stack. -With a positive argument @var{n}, @key{TAB} moves the top stack -element down to level @var{n}, making room for it by pulling all the -intervening stack elements toward the top. @kbd{M-@key{TAB}} moves the -element at level @var{n} up to the top. (Compare with @key{LFD}, -which copies instead of moving the element in level @var{n}.) - -With a negative argument @mathit{-@var{n}}, @key{TAB} rotates the stack -to move the object in level @var{n} to the deepest place in the -stack, and the object in level @mathit{@var{n}+1} to the top. @kbd{M-@key{TAB}} -rotates the deepest stack element to be in level @var{n}, also -putting the top stack element in level @mathit{@var{n}+1}. - -@xref{Selecting Subformulas}, for a way to apply these commands to -any portion of a vector or formula on the stack. - -@kindex C-xC-t -@pindex calc-transpose-lines -@cindex Moving stack entries -The command @kbd{C-x C-t} (@code{calc-transpose-lines}) will transpose -the stack object determined by the point with the stack object at the -next higher level. For example, with @samp{10 20 30 40 50} on the -stack and the point on the line containing @samp{30}, @kbd{C-x C-t} -creates @samp{10 20 40 30 50}. More generally, @kbd{C-x C-t} acts on -the stack objects determined by the current point (and mark) similar -to how the text-mode command @code{transpose-lines} acts on -lines. With argument @var{n}, @kbd{C-x C-t} will move the stack object -at the level above the current point and move it past N other objects; -for example, with @samp{10 20 30 40 50} on the stack and the point on -the line containing @samp{30}, @kbd{C-u 2 C-x C-t} creates -@samp{10 40 20 30 50}. With an argument of 0, @kbd{C-x C-t} will switch -the stack objects at the levels determined by the point and the mark. - -@node Editing Stack Entries, Trail Commands, Stack Manipulation, Stack and Trail -@section Editing Stack Entries - -@noindent -@kindex ` -@pindex calc-edit -@pindex calc-edit-finish -@cindex Editing the stack with Emacs -The @kbd{`} (@code{calc-edit}) command creates a temporary buffer -(@samp{*Calc Edit*}) for editing the top-of-stack value using regular -Emacs commands. Note that @kbd{`} is a backquote, not a quote. With a -numeric prefix argument, it edits the specified number of stack entries -at once. (An argument of zero edits the entire stack; a negative -argument edits one specific stack entry.) - -When you are done editing, press @kbd{C-c C-c} to finish and return -to Calc. The @key{RET} and @key{LFD} keys also work to finish most -sorts of editing, though in some cases Calc leaves @key{RET} with its -usual meaning (``insert a newline'') if it's a situation where you -might want to insert new lines into the editing buffer. - -When you finish editing, the Calculator parses the lines of text in -the @samp{*Calc Edit*} buffer as numbers or formulas, replaces the -original stack elements in the original buffer with these new values, -then kills the @samp{*Calc Edit*} buffer. The original Calculator buffer -continues to exist during editing, but for best results you should be -careful not to change it until you have finished the edit. You can -also cancel the edit by killing the buffer with @kbd{C-x k}. - -The formula is normally reevaluated as it is put onto the stack. -For example, editing @samp{a + 2} to @samp{3 + 2} and pressing -@kbd{C-c C-c} will push 5 on the stack. If you use @key{LFD} to -finish, Calc will put the result on the stack without evaluating it. - -If you give a prefix argument to @kbd{C-c C-c}, -Calc will not kill the @samp{*Calc Edit*} buffer. You can switch -back to that buffer and continue editing if you wish. However, you -should understand that if you initiated the edit with @kbd{`}, the -@kbd{C-c C-c} operation will be programmed to replace the top of the -stack with the new edited value, and it will do this even if you have -rearranged the stack in the meanwhile. This is not so much of a problem -with other editing commands, though, such as @kbd{s e} -(@code{calc-edit-variable}; @pxref{Operations on Variables}). - -If the @code{calc-edit} command involves more than one stack entry, -each line of the @samp{*Calc Edit*} buffer is interpreted as a -separate formula. Otherwise, the entire buffer is interpreted as -one formula, with line breaks ignored. (You can use @kbd{C-o} or -@kbd{C-q C-j} to insert a newline in the buffer without pressing @key{RET}.) - -The @kbd{`} key also works during numeric or algebraic entry. The -text entered so far is moved to the @code{*Calc Edit*} buffer for -more extensive editing than is convenient in the minibuffer. - -@node Trail Commands, Keep Arguments, Editing Stack Entries, Stack and Trail -@section Trail Commands - -@noindent -@cindex Trail buffer -The commands for manipulating the Calc Trail buffer are two-key sequences -beginning with the @kbd{t} prefix. - -@kindex t d -@pindex calc-trail-display -The @kbd{t d} (@code{calc-trail-display}) command turns display of the -trail on and off. Normally the trail display is toggled on if it was off, -off if it was on. With a numeric prefix of zero, this command always -turns the trail off; with a prefix of one, it always turns the trail on. -The other trail-manipulation commands described here automatically turn -the trail on. Note that when the trail is off values are still recorded -there; they are simply not displayed. To set Emacs to turn the trail -off by default, type @kbd{t d} and then save the mode settings with -@kbd{m m} (@code{calc-save-modes}). - -@kindex t i -@pindex calc-trail-in -@kindex t o -@pindex calc-trail-out -The @kbd{t i} (@code{calc-trail-in}) and @kbd{t o} -(@code{calc-trail-out}) commands switch the cursor into and out of the -Calc Trail window. In practice they are rarely used, since the commands -shown below are a more convenient way to move around in the -trail, and they work ``by remote control'' when the cursor is still -in the Calculator window. - -@cindex Trail pointer -There is a @dfn{trail pointer} which selects some entry of the trail at -any given time. The trail pointer looks like a @samp{>} symbol right -before the selected number. The following commands operate on the -trail pointer in various ways. - -@kindex t y -@pindex calc-trail-yank -@cindex Retrieving previous results -The @kbd{t y} (@code{calc-trail-yank}) command reads the selected value in -the trail and pushes it onto the Calculator stack. It allows you to -re-use any previously computed value without retyping. With a numeric -prefix argument @var{n}, it yanks the value @var{n} lines above the current -trail pointer. - -@kindex t < -@pindex calc-trail-scroll-left -@kindex t > -@pindex calc-trail-scroll-right -The @kbd{t <} (@code{calc-trail-scroll-left}) and @kbd{t >} -(@code{calc-trail-scroll-right}) commands horizontally scroll the trail -window left or right by one half of its width. - -@kindex t n -@pindex calc-trail-next -@kindex t p -@pindex calc-trail-previous -@kindex t f -@pindex calc-trail-forward -@kindex t b -@pindex calc-trail-backward -The @kbd{t n} (@code{calc-trail-next}) and @kbd{t p} -(@code{calc-trail-previous)} commands move the trail pointer down or up -one line. The @kbd{t f} (@code{calc-trail-forward}) and @kbd{t b} -(@code{calc-trail-backward}) commands move the trail pointer down or up -one screenful at a time. All of these commands accept numeric prefix -arguments to move several lines or screenfuls at a time. - -@kindex t [ -@pindex calc-trail-first -@kindex t ] -@pindex calc-trail-last -@kindex t h -@pindex calc-trail-here -The @kbd{t [} (@code{calc-trail-first}) and @kbd{t ]} -(@code{calc-trail-last}) commands move the trail pointer to the first or -last line of the trail. The @kbd{t h} (@code{calc-trail-here}) command -moves the trail pointer to the cursor position; unlike the other trail -commands, @kbd{t h} works only when Calc Trail is the selected window. - -@kindex t s -@pindex calc-trail-isearch-forward -@kindex t r -@pindex calc-trail-isearch-backward -@ifnottex -The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r} -(@code{calc-trail-isearch-backward}) commands perform an incremental -search forward or backward through the trail. You can press @key{RET} -to terminate the search; the trail pointer moves to the current line. -If you cancel the search with @kbd{C-g}, the trail pointer stays where -it was when the search began. -@end ifnottex -@tex -The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r} -(@code{calc-trail-isearch-backward}) com\-mands perform an incremental -search forward or backward through the trail. You can press @key{RET} -to terminate the search; the trail pointer moves to the current line. -If you cancel the search with @kbd{C-g}, the trail pointer stays where -it was when the search began. -@end tex - -@kindex t m -@pindex calc-trail-marker -The @kbd{t m} (@code{calc-trail-marker}) command allows you to enter a -line of text of your own choosing into the trail. The text is inserted -after the line containing the trail pointer; this usually means it is -added to the end of the trail. Trail markers are useful mainly as the -targets for later incremental searches in the trail. - -@kindex t k -@pindex calc-trail-kill -The @kbd{t k} (@code{calc-trail-kill}) command removes the selected line -from the trail. The line is saved in the Emacs kill ring suitable for -yanking into another buffer, but it is not easy to yank the text back -into the trail buffer. With a numeric prefix argument, this command -kills the @var{n} lines below or above the selected one. - -The @kbd{t .} (@code{calc-full-trail-vectors}) command is described -elsewhere; @pxref{Vector and Matrix Formats}. - -@node Keep Arguments, , Trail Commands, Stack and Trail -@section Keep Arguments - -@noindent -@kindex K -@pindex calc-keep-args -The @kbd{K} (@code{calc-keep-args}) command acts like a prefix for -the following command. It prevents that command from removing its -arguments from the stack. For example, after @kbd{2 @key{RET} 3 +}, -the stack contains the sole number 5, but after @kbd{2 @key{RET} 3 K +}, -the stack contains the arguments and the result: @samp{2 3 5}. - -With the exception of keyboard macros, this works for all commands that -take arguments off the stack. (To avoid potentially unpleasant behavior, -a @kbd{K} prefix before a keyboard macro will be ignored. A @kbd{K} -prefix called @emph{within} the keyboard macro will still take effect.) -As another example, @kbd{K a s} simplifies a formula, pushing the -simplified version of the formula onto the stack after the original -formula (rather than replacing the original formula). Note that you -could get the same effect by typing @kbd{@key{RET} a s}, copying the -formula and then simplifying the copy. One difference is that for a very -large formula the time taken to format the intermediate copy in -@kbd{@key{RET} a s} could be noticeable; @kbd{K a s} would avoid this -extra work. - -Even stack manipulation commands are affected. @key{TAB} works by -popping two values and pushing them back in the opposite order, -so @kbd{2 @key{RET} 3 K @key{TAB}} produces @samp{2 3 3 2}. - -A few Calc commands provide other ways of doing the same thing. -For example, @kbd{' sin($)} replaces the number on the stack with -its sine using algebraic entry; to push the sine and keep the -original argument you could use either @kbd{' sin($1)} or -@kbd{K ' sin($)}. @xref{Algebraic Entry}. Also, the @kbd{s s} -command is effectively the same as @kbd{K s t}. @xref{Storing Variables}. - -If you execute a command and then decide you really wanted to keep -the argument, you can press @kbd{M-@key{RET}} (@code{calc-last-args}). -This command pushes the last arguments that were popped by any command -onto the stack. Note that the order of things on the stack will be -different than with @kbd{K}: @kbd{2 @key{RET} 3 + M-@key{RET}} leaves -@samp{5 2 3} on the stack instead of @samp{2 3 5}. @xref{Undo}. - -@node Mode Settings, Arithmetic, Stack and Trail, Top -@chapter Mode Settings - -@noindent -This chapter describes commands that set modes in the Calculator. -They do not affect the contents of the stack, although they may change -the @emph{appearance} or @emph{interpretation} of the stack's contents. - -@menu -* General Mode Commands:: -* Precision:: -* Inverse and Hyperbolic:: -* Calculation Modes:: -* Simplification Modes:: -* Declarations:: -* Display Modes:: -* Language Modes:: -* Modes Variable:: -* Calc Mode Line:: -@end menu - -@node General Mode Commands, Precision, Mode Settings, Mode Settings -@section General Mode Commands - -@noindent -@kindex m m -@pindex calc-save-modes -@cindex Continuous memory -@cindex Saving mode settings -@cindex Permanent mode settings -@cindex Calc init file, mode settings -You can save all of the current mode settings in your Calc init file -(the file given by the variable @code{calc-settings-file}, typically -@file{~/.emacs.d/calc.el}) with the @kbd{m m} (@code{calc-save-modes}) -command. This will cause Emacs to reestablish these modes each time -it starts up. The modes saved in the file include everything -controlled by the @kbd{m} and @kbd{d} prefix keys, the current -precision and binary word size, whether or not the trail is displayed, -the current height of the Calc window, and more. The current -interface (used when you type @kbd{C-x * *}) is also saved. If there -were already saved mode settings in the file, they are replaced. -Otherwise, the new mode information is appended to the end of the -file. - -@kindex m R -@pindex calc-mode-record-mode -The @kbd{m R} (@code{calc-mode-record-mode}) command tells Calc to -record all the mode settings (as if by pressing @kbd{m m}) every -time a mode setting changes. If the modes are saved this way, then this -``automatic mode recording'' mode is also saved. -Type @kbd{m R} again to disable this method of recording the mode -settings. To turn it off permanently, the @kbd{m m} command will also be -necessary. (If Embedded mode is enabled, other options for recording -the modes are available; @pxref{Mode Settings in Embedded Mode}.) - -@kindex m F -@pindex calc-settings-file-name -The @kbd{m F} (@code{calc-settings-file-name}) command allows you to -choose a different file than the current value of @code{calc-settings-file} -for @kbd{m m}, @kbd{Z P}, and similar commands to save permanent information. -You are prompted for a file name. All Calc modes are then reset to -their default values, then settings from the file you named are loaded -if this file exists, and this file becomes the one that Calc will -use in the future for commands like @kbd{m m}. The default settings -file name is @file{~/.emacs.d/calc.el}. You can see the current file name by -giving a blank response to the @kbd{m F} prompt. See also the -discussion of the @code{calc-settings-file} variable; @pxref{Customizing Calc}. - -If the file name you give is your user init file (typically -@file{~/.emacs}), @kbd{m F} will not automatically load the new file. This -is because your user init file may contain other things you don't want -to reread. You can give -a numeric prefix argument of 1 to @kbd{m F} to force it to read the -file no matter what. Conversely, an argument of @mathit{-1} tells -@kbd{m F} @emph{not} to read the new file. An argument of 2 or @mathit{-2} -tells @kbd{m F} not to reset the modes to their defaults beforehand, -which is useful if you intend your new file to have a variant of the -modes present in the file you were using before. - -@kindex m x -@pindex calc-always-load-extensions -The @kbd{m x} (@code{calc-always-load-extensions}) command enables a mode -in which the first use of Calc loads the entire program, including all -extensions modules. Otherwise, the extensions modules will not be loaded -until the various advanced Calc features are used. Since this mode only -has effect when Calc is first loaded, @kbd{m x} is usually followed by -@kbd{m m} to make the mode-setting permanent. To load all of Calc just -once, rather than always in the future, you can press @kbd{C-x * L}. - -@kindex m S -@pindex calc-shift-prefix -The @kbd{m S} (@code{calc-shift-prefix}) command enables a mode in which -all of Calc's letter prefix keys may be typed shifted as well as unshifted. -If you are typing, say, @kbd{a S} (@code{calc-solve-for}) quite often -you might find it easier to turn this mode on so that you can type -@kbd{A S} instead. When this mode is enabled, the commands that used to -be on those single shifted letters (e.g., @kbd{A} (@code{calc-abs})) can -now be invoked by pressing the shifted letter twice: @kbd{A A}. Note -that the @kbd{v} prefix key always works both shifted and unshifted, and -the @kbd{z} and @kbd{Z} prefix keys are always distinct. Also, the @kbd{h} -prefix is not affected by this mode. Press @kbd{m S} again to disable -shifted-prefix mode. - -@node Precision, Inverse and Hyperbolic, General Mode Commands, Mode Settings -@section Precision - -@noindent -@kindex p -@pindex calc-precision -@cindex Precision of calculations -The @kbd{p} (@code{calc-precision}) command controls the precision to -which floating-point calculations are carried. The precision must be -at least 3 digits and may be arbitrarily high, within the limits of -memory and time. This affects only floats: Integer and rational -calculations are always carried out with as many digits as necessary. - -The @kbd{p} key prompts for the current precision. If you wish you -can instead give the precision as a numeric prefix argument. - -Many internal calculations are carried to one or two digits higher -precision than normal. Results are rounded down afterward to the -current precision. Unless a special display mode has been selected, -floats are always displayed with their full stored precision, i.e., -what you see is what you get. Reducing the current precision does not -round values already on the stack, but those values will be rounded -down before being used in any calculation. The @kbd{c 0} through -@kbd{c 9} commands (@pxref{Conversions}) can be used to round an -existing value to a new precision. - -@cindex Accuracy of calculations -It is important to distinguish the concepts of @dfn{precision} and -@dfn{accuracy}. In the normal usage of these words, the number -123.4567 has a precision of 7 digits but an accuracy of 4 digits. -The precision is the total number of digits not counting leading -or trailing zeros (regardless of the position of the decimal point). -The accuracy is simply the number of digits after the decimal point -(again not counting trailing zeros). In Calc you control the precision, -not the accuracy of computations. If you were to set the accuracy -instead, then calculations like @samp{exp(100)} would generate many -more digits than you would typically need, while @samp{exp(-100)} would -probably round to zero! In Calc, both these computations give you -exactly 12 (or the requested number of) significant digits. - -The only Calc features that deal with accuracy instead of precision -are fixed-point display mode for floats (@kbd{d f}; @pxref{Float Formats}), -and the rounding functions like @code{floor} and @code{round} -(@pxref{Integer Truncation}). Also, @kbd{c 0} through @kbd{c 9} -deal with both precision and accuracy depending on the magnitudes -of the numbers involved. - -If you need to work with a particular fixed accuracy (say, dollars and -cents with two digits after the decimal point), one solution is to work -with integers and an ``implied'' decimal point. For example, $8.99 -divided by 6 would be entered @kbd{899 @key{RET} 6 /}, yielding 149.833 -(actually $1.49833 with our implied decimal point); pressing @kbd{R} -would round this to 150 cents, i.e., $1.50. - -@xref{Floats}, for still more on floating-point precision and related -issues. - -@node Inverse and Hyperbolic, Calculation Modes, Precision, Mode Settings -@section Inverse and Hyperbolic Flags - -@noindent -@kindex I -@pindex calc-inverse -There is no single-key equivalent to the @code{calc-arcsin} function. -Instead, you must first press @kbd{I} (@code{calc-inverse}) to set -the @dfn{Inverse Flag}, then press @kbd{S} (@code{calc-sin}). -The @kbd{I} key actually toggles the Inverse Flag. When this flag -is set, the word @samp{Inv} appears in the mode line. - -@kindex H -@pindex calc-hyperbolic -Likewise, the @kbd{H} key (@code{calc-hyperbolic}) sets or clears the -Hyperbolic Flag, which transforms @code{calc-sin} into @code{calc-sinh}. -If both of these flags are set at once, the effect will be -@code{calc-arcsinh}. (The Hyperbolic flag is also used by some -non-trigonometric commands; for example @kbd{H L} computes a base-10, -instead of base-@mathit{e}, logarithm.) - -Command names like @code{calc-arcsin} are provided for completeness, and -may be executed with @kbd{x} or @kbd{M-x}. Their effect is simply to -toggle the Inverse and/or Hyperbolic flags and then execute the -corresponding base command (@code{calc-sin} in this case). - -@kindex O -@pindex calc-option -The @kbd{O} key (@code{calc-option}) sets another flag, the -@dfn{Option Flag}, which also can alter the subsequent Calc command in -various ways. - -The Inverse, Hyperbolic and Option flags apply only to the next -Calculator command, after which they are automatically cleared. (They -are also cleared if the next keystroke is not a Calc command.) Digits -you type after @kbd{I}, @kbd{H} or @kbd{O} (or @kbd{K}) are treated as -prefix arguments for the next command, not as numeric entries. The -same is true of @kbd{C-u}, but not of the minus sign (@kbd{K -} means -to subtract and keep arguments). - -Another Calc prefix flag, @kbd{K} (keep-arguments), is discussed -elsewhere. @xref{Keep Arguments}. - -@node Calculation Modes, Simplification Modes, Inverse and Hyperbolic, Mode Settings -@section Calculation Modes - -@noindent -The commands in this section are two-key sequences beginning with -the @kbd{m} prefix. (That's the letter @kbd{m}, not the @key{META} key.) -The @samp{m a} (@code{calc-algebraic-mode}) command is described elsewhere -(@pxref{Algebraic Entry}). - -@menu -* Angular Modes:: -* Polar Mode:: -* Fraction Mode:: -* Infinite Mode:: -* Symbolic Mode:: -* Matrix Mode:: -* Automatic Recomputation:: -* Working Message:: -@end menu - -@node Angular Modes, Polar Mode, Calculation Modes, Calculation Modes -@subsection Angular Modes - -@noindent -@cindex Angular mode -The Calculator supports three notations for angles: radians, degrees, -and degrees-minutes-seconds. When a number is presented to a function -like @code{sin} that requires an angle, the current angular mode is -used to interpret the number as either radians or degrees. If an HMS -form is presented to @code{sin}, it is always interpreted as -degrees-minutes-seconds. - -Functions that compute angles produce a number in radians, a number in -degrees, or an HMS form depending on the current angular mode. If the -result is a complex number and the current mode is HMS, the number is -instead expressed in degrees. (Complex-number calculations would -normally be done in Radians mode, though. Complex numbers are converted -to degrees by calculating the complex result in radians and then -multiplying by 180 over @cpi{}.) - -@kindex m r -@pindex calc-radians-mode -@kindex m d -@pindex calc-degrees-mode -@kindex m h -@pindex calc-hms-mode -The @kbd{m r} (@code{calc-radians-mode}), @kbd{m d} (@code{calc-degrees-mode}), -and @kbd{m h} (@code{calc-hms-mode}) commands control the angular mode. -The current angular mode is displayed on the Emacs mode line. -The default angular mode is Degrees. - -@node Polar Mode, Fraction Mode, Angular Modes, Calculation Modes -@subsection Polar Mode - -@noindent -@cindex Polar mode -The Calculator normally ``prefers'' rectangular complex numbers in the -sense that rectangular form is used when the proper form can not be -decided from the input. This might happen by multiplying a rectangular -number by a polar one, by taking the square root of a negative real -number, or by entering @kbd{( 2 @key{SPC} 3 )}. - -@kindex m p -@pindex calc-polar-mode -The @kbd{m p} (@code{calc-polar-mode}) command toggles complex-number -preference between rectangular and polar forms. In Polar mode, all -of the above example situations would produce polar complex numbers. - -@node Fraction Mode, Infinite Mode, Polar Mode, Calculation Modes -@subsection Fraction Mode - -@noindent -@cindex Fraction mode -@cindex Division of integers -Division of two integers normally yields a floating-point number if the -result cannot be expressed as an integer. In some cases you would -rather get an exact fractional answer. One way to accomplish this is -to use the @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command, which -divides the two integers on the top of the stack to produce a fraction: -@kbd{6 @key{RET} 4 :} produces @expr{3:2} even though -@kbd{6 @key{RET} 4 /} produces @expr{1.5}. - -@kindex m f -@pindex calc-frac-mode -To set the Calculator to produce fractional results for normal integer -divisions, use the @kbd{m f} (@code{calc-frac-mode}) command. -For example, @expr{8/4} produces @expr{2} in either mode, -but @expr{6/4} produces @expr{3:2} in Fraction mode, @expr{1.5} in -Float mode. - -At any time you can use @kbd{c f} (@code{calc-float}) to convert a -fraction to a float, or @kbd{c F} (@code{calc-fraction}) to convert a -float to a fraction. @xref{Conversions}. - -@node Infinite Mode, Symbolic Mode, Fraction Mode, Calculation Modes -@subsection Infinite Mode - -@noindent -@cindex Infinite mode -The Calculator normally treats results like @expr{1 / 0} as errors; -formulas like this are left in unsimplified form. But Calc can be -put into a mode where such calculations instead produce ``infinite'' -results. - -@kindex m i -@pindex calc-infinite-mode -The @kbd{m i} (@code{calc-infinite-mode}) command turns this mode -on and off. When the mode is off, infinities do not arise except -in calculations that already had infinities as inputs. (One exception -is that infinite open intervals like @samp{[0 .. inf)} can be -generated; however, intervals closed at infinity (@samp{[0 .. inf]}) -will not be generated when Infinite mode is off.) - -With Infinite mode turned on, @samp{1 / 0} will generate @code{uinf}, -an undirected infinity. @xref{Infinities}, for a discussion of the -difference between @code{inf} and @code{uinf}. Also, @expr{0 / 0} -evaluates to @code{nan}, the ``indeterminate'' symbol. Various other -functions can also return infinities in this mode; for example, -@samp{ln(0) = -inf}, and @samp{gamma(-7) = uinf}. Once again, -note that @samp{exp(inf) = inf} regardless of Infinite mode because -this calculation has infinity as an input. - -@cindex Positive Infinite mode -The @kbd{m i} command with a numeric prefix argument of zero, -i.e., @kbd{C-u 0 m i}, turns on a Positive Infinite mode in -which zero is treated as positive instead of being directionless. -Thus, @samp{1 / 0 = inf} and @samp{-1 / 0 = -inf} in this mode. -Note that zero never actually has a sign in Calc; there are no -separate representations for @mathit{+0} and @mathit{-0}. Positive -Infinite mode merely changes the interpretation given to the -single symbol, @samp{0}. One consequence of this is that, while -you might expect @samp{1 / -0 = -inf}, actually @samp{1 / -0} -is equivalent to @samp{1 / 0}, which is equal to positive @code{inf}. - -@node Symbolic Mode, Matrix Mode, Infinite Mode, Calculation Modes -@subsection Symbolic Mode - -@noindent -@cindex Symbolic mode -@cindex Inexact results -Calculations are normally performed numerically wherever possible. -For example, the @code{calc-sqrt} command, or @code{sqrt} function in an -algebraic expression, produces a numeric answer if the argument is a -number or a symbolic expression if the argument is an expression: -@kbd{2 Q} pushes 1.4142 but @kbd{@key{'} x+1 @key{RET} Q} pushes @samp{sqrt(x+1)}. - -@kindex m s -@pindex calc-symbolic-mode -In @dfn{Symbolic mode}, controlled by the @kbd{m s} (@code{calc-symbolic-mode}) -command, functions which would produce inexact, irrational results are -left in symbolic form. Thus @kbd{16 Q} pushes 4, but @kbd{2 Q} pushes -@samp{sqrt(2)}. - -@kindex N -@pindex calc-eval-num -The shift-@kbd{N} (@code{calc-eval-num}) command evaluates numerically -the expression at the top of the stack, by temporarily disabling -@code{calc-symbolic-mode} and executing @kbd{=} (@code{calc-evaluate}). -Given a numeric prefix argument, it also -sets the floating-point precision to the specified value for the duration -of the command. - -To evaluate a formula numerically without expanding the variables it -contains, you can use the key sequence @kbd{m s a v m s} (this uses -@code{calc-alg-evaluate}, which resimplifies but doesn't evaluate -variables.) - -@node Matrix Mode, Automatic Recomputation, Symbolic Mode, Calculation Modes -@subsection Matrix and Scalar Modes - -@noindent -@cindex Matrix mode -@cindex Scalar mode -Calc sometimes makes assumptions during algebraic manipulation that -are awkward or incorrect when vectors and matrices are involved. -Calc has two modes, @dfn{Matrix mode} and @dfn{Scalar mode}, which -modify its behavior around vectors in useful ways. - -@kindex m v -@pindex calc-matrix-mode -Press @kbd{m v} (@code{calc-matrix-mode}) once to enter Matrix mode. -In this mode, all objects are assumed to be matrices unless provably -otherwise. One major effect is that Calc will no longer consider -multiplication to be commutative. (Recall that in matrix arithmetic, -@samp{A*B} is not the same as @samp{B*A}.) This assumption affects -rewrite rules and algebraic simplification. Another effect of this -mode is that calculations that would normally produce constants like -0 and 1 (e.g., @expr{a - a} and @expr{a / a}, respectively) will now -produce function calls that represent ``generic'' zero or identity -matrices: @samp{idn(0)}, @samp{idn(1)}. The @code{idn} function -@samp{idn(@var{a},@var{n})} returns @var{a} times an @var{n}x@var{n} -identity matrix; if @var{n} is omitted, it doesn't know what -dimension to use and so the @code{idn} call remains in symbolic -form. However, if this generic identity matrix is later combined -with a matrix whose size is known, it will be converted into -a true identity matrix of the appropriate size. On the other hand, -if it is combined with a scalar (as in @samp{idn(1) + 2}), Calc -will assume it really was a scalar after all and produce, e.g., 3. - -Press @kbd{m v} a second time to get Scalar mode. Here, objects are -assumed @emph{not} to be vectors or matrices unless provably so. -For example, normally adding a variable to a vector, as in -@samp{[x, y, z] + a}, will leave the sum in symbolic form because -as far as Calc knows, @samp{a} could represent either a number or -another 3-vector. In Scalar mode, @samp{a} is assumed to be a -non-vector, and the addition is evaluated to @samp{[x+a, y+a, z+a]}. - -Press @kbd{m v} a third time to return to the normal mode of operation. - -If you press @kbd{m v} with a numeric prefix argument @var{n}, you -get a special ``dimensioned'' Matrix mode in which matrices of -unknown size are assumed to be @var{n}x@var{n} square matrices. -Then, the function call @samp{idn(1)} will expand into an actual -matrix rather than representing a ``generic'' matrix. Simply typing -@kbd{C-u m v} will get you a square Matrix mode, in which matrices of -unknown size are assumed to be square matrices of unspecified size. - -@cindex Declaring scalar variables -Of course these modes are approximations to the true state of -affairs, which is probably that some quantities will be matrices -and others will be scalars. One solution is to ``declare'' -certain variables or functions to be scalar-valued. -@xref{Declarations}, to see how to make declarations in Calc. - -There is nothing stopping you from declaring a variable to be -scalar and then storing a matrix in it; however, if you do, the -results you get from Calc may not be valid. Suppose you let Calc -get the result @samp{[x+a, y+a, z+a]} shown above, and then stored -@samp{[1, 2, 3]} in @samp{a}. The result would not be the same as -for @samp{[x, y, z] + [1, 2, 3]}, but that's because you have broken -your earlier promise to Calc that @samp{a} would be scalar. - -Another way to mix scalars and matrices is to use selections -(@pxref{Selecting Subformulas}). Use Matrix mode when operating on -your formula normally; then, to apply Scalar mode to a certain part -of the formula without affecting the rest just select that part, -change into Scalar mode and press @kbd{=} to resimplify the part -under this mode, then change back to Matrix mode before deselecting. - -@node Automatic Recomputation, Working Message, Matrix Mode, Calculation Modes -@subsection Automatic Recomputation - -@noindent -The @dfn{evaluates-to} operator, @samp{=>}, has the special -property that any @samp{=>} formulas on the stack are recomputed -whenever variable values or mode settings that might affect them -are changed. @xref{Evaluates-To Operator}. - -@kindex m C -@pindex calc-auto-recompute -The @kbd{m C} (@code{calc-auto-recompute}) command turns this -automatic recomputation on and off. If you turn it off, Calc will -not update @samp{=>} operators on the stack (nor those in the -attached Embedded mode buffer, if there is one). They will not -be updated unless you explicitly do so by pressing @kbd{=} or until -you press @kbd{m C} to turn recomputation back on. (While automatic -recomputation is off, you can think of @kbd{m C m C} as a command -to update all @samp{=>} operators while leaving recomputation off.) - -To update @samp{=>} operators in an Embedded buffer while -automatic recomputation is off, use @w{@kbd{C-x * u}}. -@xref{Embedded Mode}. - -@node Working Message, , Automatic Recomputation, Calculation Modes -@subsection Working Messages - -@noindent -@cindex Performance -@cindex Working messages -Since the Calculator is written entirely in Emacs Lisp, which is not -designed for heavy numerical work, many operations are quite slow. -The Calculator normally displays the message @samp{Working...} in the -echo area during any command that may be slow. In addition, iterative -operations such as square roots and trigonometric functions display the -intermediate result at each step. Both of these types of messages can -be disabled if you find them distracting. - -@kindex m w -@pindex calc-working -Type @kbd{m w} (@code{calc-working}) with a numeric prefix of 0 to -disable all ``working'' messages. Use a numeric prefix of 1 to enable -only the plain @samp{Working...} message. Use a numeric prefix of 2 to -see intermediate results as well. With no numeric prefix this displays -the current mode. - -While it may seem that the ``working'' messages will slow Calc down -considerably, experiments have shown that their impact is actually -quite small. But if your terminal is slow you may find that it helps -to turn the messages off. - -@node Simplification Modes, Declarations, Calculation Modes, Mode Settings -@section Simplification Modes - -@noindent -The current @dfn{simplification mode} controls how numbers and formulas -are ``normalized'' when being taken from or pushed onto the stack. -Some normalizations are unavoidable, such as rounding floating-point -results to the current precision, and reducing fractions to simplest -form. Others, such as simplifying a formula like @expr{a+a} (or @expr{2+3}), -are done by default but can be turned off when necessary. - -When you press a key like @kbd{+} when @expr{2} and @expr{3} are on the -stack, Calc pops these numbers, normalizes them, creates the formula -@expr{2+3}, normalizes it, and pushes the result. Of course the standard -rules for normalizing @expr{2+3} will produce the result @expr{5}. - -Simplification mode commands consist of the lower-case @kbd{m} prefix key -followed by a shifted letter. - -@kindex m O -@pindex calc-no-simplify-mode -The @kbd{m O} (@code{calc-no-simplify-mode}) command turns off all optional -simplifications. These would leave a formula like @expr{2+3} alone. In -fact, nothing except simple numbers are ever affected by normalization -in this mode. - -@kindex m N -@pindex calc-num-simplify-mode -The @kbd{m N} (@code{calc-num-simplify-mode}) command turns off simplification -of any formulas except those for which all arguments are constants. For -example, @expr{1+2} is simplified to @expr{3}, and @expr{a+(2-2)} is -simplified to @expr{a+0} but no further, since one argument of the sum -is not a constant. Unfortunately, @expr{(a+2)-2} is @emph{not} simplified -because the top-level @samp{-} operator's arguments are not both -constant numbers (one of them is the formula @expr{a+2}). -A constant is a number or other numeric object (such as a constant -error form or modulo form), or a vector all of whose -elements are constant. - -@kindex m D -@pindex calc-default-simplify-mode -The @kbd{m D} (@code{calc-default-simplify-mode}) command restores the -default simplifications for all formulas. This includes many easy and -fast algebraic simplifications such as @expr{a+0} to @expr{a}, and -@expr{a + 2 a} to @expr{3 a}, as well as evaluating functions like -@expr{@tfn{deriv}(x^2, x)} to @expr{2 x}. - -@kindex m B -@pindex calc-bin-simplify-mode -The @kbd{m B} (@code{calc-bin-simplify-mode}) mode applies the default -simplifications to a result and then, if the result is an integer, -uses the @kbd{b c} (@code{calc-clip}) command to clip the integer according -to the current binary word size. @xref{Binary Functions}. Real numbers -are rounded to the nearest integer and then clipped; other kinds of -results (after the default simplifications) are left alone. - -@kindex m A -@pindex calc-alg-simplify-mode -The @kbd{m A} (@code{calc-alg-simplify-mode}) mode does algebraic -simplification; it applies all the default simplifications, and also -the more powerful (and slower) simplifications made by @kbd{a s} -(@code{calc-simplify}). @xref{Algebraic Simplifications}. - -@kindex m E -@pindex calc-ext-simplify-mode -The @kbd{m E} (@code{calc-ext-simplify-mode}) mode does ``extended'' -algebraic simplification, as by the @kbd{a e} (@code{calc-simplify-extended}) -command. @xref{Unsafe Simplifications}. - -@kindex m U -@pindex calc-units-simplify-mode -The @kbd{m U} (@code{calc-units-simplify-mode}) mode does units -simplification; it applies the command @kbd{u s} -(@code{calc-simplify-units}), which in turn -is a superset of @kbd{a s}. In this mode, variable names which -are identifiable as unit names (like @samp{mm} for ``millimeters'') -are simplified with their unit definitions in mind. - -A common technique is to set the simplification mode down to the lowest -amount of simplification you will allow to be applied automatically, then -use manual commands like @kbd{a s} and @kbd{c c} (@code{calc-clean}) to -perform higher types of simplifications on demand. @xref{Algebraic -Definitions}, for another sample use of No-Simplification mode. - -@node Declarations, Display Modes, Simplification Modes, Mode Settings -@section Declarations - -@noindent -A @dfn{declaration} is a statement you make that promises you will -use a certain variable or function in a restricted way. This may -give Calc the freedom to do things that it couldn't do if it had to -take the fully general situation into account. - -@menu -* Declaration Basics:: -* Kinds of Declarations:: -* Functions for Declarations:: -@end menu - -@node Declaration Basics, Kinds of Declarations, Declarations, Declarations -@subsection Declaration Basics - -@noindent -@kindex s d -@pindex calc-declare-variable -The @kbd{s d} (@code{calc-declare-variable}) command is the easiest -way to make a declaration for a variable. This command prompts for -the variable name, then prompts for the declaration. The default -at the declaration prompt is the previous declaration, if any. -You can edit this declaration, or press @kbd{C-k} to erase it and -type a new declaration. (Or, erase it and press @key{RET} to clear -the declaration, effectively ``undeclaring'' the variable.) - -A declaration is in general a vector of @dfn{type symbols} and -@dfn{range} values. If there is only one type symbol or range value, -you can write it directly rather than enclosing it in a vector. -For example, @kbd{s d foo @key{RET} real @key{RET}} declares @code{foo} to -be a real number, and @kbd{s d bar @key{RET} [int, const, [1..6]] @key{RET}} -declares @code{bar} to be a constant integer between 1 and 6. -(Actually, you can omit the outermost brackets and Calc will -provide them for you: @kbd{s d bar @key{RET} int, const, [1..6] @key{RET}}.) - -@cindex @code{Decls} variable -@vindex Decls -Declarations in Calc are kept in a special variable called @code{Decls}. -This variable encodes the set of all outstanding declarations in -the form of a matrix. Each row has two elements: A variable or -vector of variables declared by that row, and the declaration -specifier as described above. You can use the @kbd{s D} command to -edit this variable if you wish to see all the declarations at once. -@xref{Operations on Variables}, for a description of this command -and the @kbd{s p} command that allows you to save your declarations -permanently if you wish. - -Items being declared can also be function calls. The arguments in -the call are ignored; the effect is to say that this function returns -values of the declared type for any valid arguments. The @kbd{s d} -command declares only variables, so if you wish to make a function -declaration you will have to edit the @code{Decls} matrix yourself. - -For example, the declaration matrix - -@smallexample -@group -[ [ foo, real ] - [ [j, k, n], int ] - [ f(1,2,3), [0 .. inf) ] ] -@end group -@end smallexample - -@noindent -declares that @code{foo} represents a real number, @code{j}, @code{k} -and @code{n} represent integers, and the function @code{f} always -returns a real number in the interval shown. - -@vindex All -If there is a declaration for the variable @code{All}, then that -declaration applies to all variables that are not otherwise declared. -It does not apply to function names. For example, using the row -@samp{[All, real]} says that all your variables are real unless they -are explicitly declared without @code{real} in some other row. -The @kbd{s d} command declares @code{All} if you give a blank -response to the variable-name prompt. - -@node Kinds of Declarations, Functions for Declarations, Declaration Basics, Declarations -@subsection Kinds of Declarations - -@noindent -The type-specifier part of a declaration (that is, the second prompt -in the @kbd{s d} command) can be a type symbol, an interval, or a -vector consisting of zero or more type symbols followed by zero or -more intervals or numbers that represent the set of possible values -for the variable. - -@smallexample -@group -[ [ a, [1, 2, 3, 4, 5] ] - [ b, [1 .. 5] ] - [ c, [int, 1 .. 5] ] ] -@end group -@end smallexample - -Here @code{a} is declared to contain one of the five integers shown; -@code{b} is any number in the interval from 1 to 5 (any real number -since we haven't specified), and @code{c} is any integer in that -interval. Thus the declarations for @code{a} and @code{c} are -nearly equivalent (see below). - -The type-specifier can be the empty vector @samp{[]} to say that -nothing is known about a given variable's value. This is the same -as not declaring the variable at all except that it overrides any -@code{All} declaration which would otherwise apply. - -The initial value of @code{Decls} is the empty vector @samp{[]}. -If @code{Decls} has no stored value or if the value stored in it -is not valid, it is ignored and there are no declarations as far -as Calc is concerned. (The @kbd{s d} command will replace such a -malformed value with a fresh empty matrix, @samp{[]}, before recording -the new declaration.) Unrecognized type symbols are ignored. - -The following type symbols describe what sorts of numbers will be -stored in a variable: - -@table @code -@item int -Integers. -@item numint -Numerical integers. (Integers or integer-valued floats.) -@item frac -Fractions. (Rational numbers which are not integers.) -@item rat -Rational numbers. (Either integers or fractions.) -@item float -Floating-point numbers. -@item real -Real numbers. (Integers, fractions, or floats. Actually, -intervals and error forms with real components also count as -reals here.) -@item pos -Positive real numbers. (Strictly greater than zero.) -@item nonneg -Nonnegative real numbers. (Greater than or equal to zero.) -@item number -Numbers. (Real or complex.) -@end table - -Calc uses this information to determine when certain simplifications -of formulas are safe. For example, @samp{(x^y)^z} cannot be -simplified to @samp{x^(y z)} in general; for example, -@samp{((-3)^2)^1:2} is 3, but @samp{(-3)^(2*1:2) = (-3)^1} is @mathit{-3}. -However, this simplification @emph{is} safe if @code{z} is known -to be an integer, or if @code{x} is known to be a nonnegative -real number. If you have given declarations that allow Calc to -deduce either of these facts, Calc will perform this simplification -of the formula. - -Calc can apply a certain amount of logic when using declarations. -For example, @samp{(x^y)^(2n+1)} will be simplified if @code{n} -has been declared @code{int}; Calc knows that an integer times an -integer, plus an integer, must always be an integer. (In fact, -Calc would simplify @samp{(-x)^(2n+1)} to @samp{-(x^(2n+1))} since -it is able to determine that @samp{2n+1} must be an odd integer.) - -Similarly, @samp{(abs(x)^y)^z} will be simplified to @samp{abs(x)^(y z)} -because Calc knows that the @code{abs} function always returns a -nonnegative real. If you had a @code{myabs} function that also had -this property, you could get Calc to recognize it by adding the row -@samp{[myabs(), nonneg]} to the @code{Decls} matrix. - -One instance of this simplification is @samp{sqrt(x^2)} (since the -@code{sqrt} function is effectively a one-half power). Normally -Calc leaves this formula alone. After the command -@kbd{s d x @key{RET} real @key{RET}}, however, it can simplify the formula to -@samp{abs(x)}. And after @kbd{s d x @key{RET} nonneg @key{RET}}, Calc can -simplify this formula all the way to @samp{x}. - -If there are any intervals or real numbers in the type specifier, -they comprise the set of possible values that the variable or -function being declared can have. In particular, the type symbol -@code{real} is effectively the same as the range @samp{[-inf .. inf]} -(note that infinity is included in the range of possible values); -@code{pos} is the same as @samp{(0 .. inf]}, and @code{nonneg} is -the same as @samp{[0 .. inf]}. Saying @samp{[real, [-5 .. 5]]} is -redundant because the fact that the variable is real can be -deduced just from the interval, but @samp{[int, [-5 .. 5]]} and -@samp{[rat, [-5 .. 5]]} are useful combinations. - -Note that the vector of intervals or numbers is in the same format -used by Calc's set-manipulation commands. @xref{Set Operations}. - -The type specifier @samp{[1, 2, 3]} is equivalent to -@samp{[numint, 1, 2, 3]}, @emph{not} to @samp{[int, 1, 2, 3]}. -In other words, the range of possible values means only that -the variable's value must be numerically equal to a number in -that range, but not that it must be equal in type as well. -Calc's set operations act the same way; @samp{in(2, [1., 2., 3.])} -and @samp{in(1.5, [1:2, 3:2, 5:2])} both report ``true.'' - -If you use a conflicting combination of type specifiers, the -results are unpredictable. An example is @samp{[pos, [0 .. 5]]}, -where the interval does not lie in the range described by the -type symbol. - -``Real'' declarations mostly affect simplifications involving powers -like the one described above. Another case where they are used -is in the @kbd{a P} command which returns a list of all roots of a -polynomial; if the variable has been declared real, only the real -roots (if any) will be included in the list. - -``Integer'' declarations are used for simplifications which are valid -only when certain values are integers (such as @samp{(x^y)^z} -shown above). - -Another command that makes use of declarations is @kbd{a s}, when -simplifying equations and inequalities. It will cancel @code{x} -from both sides of @samp{a x = b x} only if it is sure @code{x} -is non-zero, say, because it has a @code{pos} declaration. -To declare specifically that @code{x} is real and non-zero, -use @samp{[[-inf .. 0), (0 .. inf]]}. (There is no way in the -current notation to say that @code{x} is nonzero but not necessarily -real.) The @kbd{a e} command does ``unsafe'' simplifications, -including canceling @samp{x} from the equation when @samp{x} is -not known to be nonzero. - -Another set of type symbols distinguish between scalars and vectors. - -@table @code -@item scalar -The value is not a vector. -@item vector -The value is a vector. -@item matrix -The value is a matrix (a rectangular vector of vectors). -@item sqmatrix -The value is a square matrix. -@end table - -These type symbols can be combined with the other type symbols -described above; @samp{[int, matrix]} describes an object which -is a matrix of integers. - -Scalar/vector declarations are used to determine whether certain -algebraic operations are safe. For example, @samp{[a, b, c] + x} -is normally not simplified to @samp{[a + x, b + x, c + x]}, but -it will be if @code{x} has been declared @code{scalar}. On the -other hand, multiplication is usually assumed to be commutative, -but the terms in @samp{x y} will never be exchanged if both @code{x} -and @code{y} are known to be vectors or matrices. (Calc currently -never distinguishes between @code{vector} and @code{matrix} -declarations.) - -@xref{Matrix Mode}, for a discussion of Matrix mode and -Scalar mode, which are similar to declaring @samp{[All, matrix]} -or @samp{[All, scalar]} but much more convenient. - -One more type symbol that is recognized is used with the @kbd{H a d} -command for taking total derivatives of a formula. @xref{Calculus}. - -@table @code -@item const -The value is a constant with respect to other variables. -@end table - -Calc does not check the declarations for a variable when you store -a value in it. However, storing @mathit{-3.5} in a variable that has -been declared @code{pos}, @code{int}, or @code{matrix} may have -unexpected effects; Calc may evaluate @samp{sqrt(x^2)} to @expr{3.5} -if it substitutes the value first, or to @expr{-3.5} if @code{x} -was declared @code{pos} and the formula @samp{sqrt(x^2)} is -simplified to @samp{x} before the value is substituted. Before -using a variable for a new purpose, it is best to use @kbd{s d} -or @kbd{s D} to check to make sure you don't still have an old -declaration for the variable that will conflict with its new meaning. - -@node Functions for Declarations, , Kinds of Declarations, Declarations -@subsection Functions for Declarations - -@noindent -Calc has a set of functions for accessing the current declarations -in a convenient manner. These functions return 1 if the argument -can be shown to have the specified property, or 0 if the argument -can be shown @emph{not} to have that property; otherwise they are -left unevaluated. These functions are suitable for use with rewrite -rules (@pxref{Conditional Rewrite Rules}) or programming constructs -(@pxref{Conditionals in Macros}). They can be entered only using -algebraic notation. @xref{Logical Operations}, for functions -that perform other tests not related to declarations. - -For example, @samp{dint(17)} returns 1 because 17 is an integer, as -do @samp{dint(n)} and @samp{dint(2 n - 3)} if @code{n} has been declared -@code{int}, but @samp{dint(2.5)} and @samp{dint(n + 0.5)} return 0. -Calc consults knowledge of its own built-in functions as well as your -own declarations: @samp{dint(floor(x))} returns 1. - -@ignore -@starindex -@end ignore -@tindex dint -@ignore -@starindex -@end ignore -@tindex dnumint -@ignore -@starindex -@end ignore -@tindex dnatnum -The @code{dint} function checks if its argument is an integer. -The @code{dnatnum} function checks if its argument is a natural -number, i.e., a nonnegative integer. The @code{dnumint} function -checks if its argument is numerically an integer, i.e., either an -integer or an integer-valued float. Note that these and the other -data type functions also accept vectors or matrices composed of -suitable elements, and that real infinities @samp{inf} and @samp{-inf} -are considered to be integers for the purposes of these functions. - -@ignore -@starindex -@end ignore -@tindex drat -The @code{drat} function checks if its argument is rational, i.e., -an integer or fraction. Infinities count as rational, but intervals -and error forms do not. - -@ignore -@starindex -@end ignore -@tindex dreal -The @code{dreal} function checks if its argument is real. This -includes integers, fractions, floats, real error forms, and intervals. - -@ignore -@starindex -@end ignore -@tindex dimag -The @code{dimag} function checks if its argument is imaginary, -i.e., is mathematically equal to a real number times @expr{i}. - -@ignore -@starindex -@end ignore -@tindex dpos -@ignore -@starindex -@end ignore -@tindex dneg -@ignore -@starindex -@end ignore -@tindex dnonneg -The @code{dpos} function checks for positive (but nonzero) reals. -The @code{dneg} function checks for negative reals. The @code{dnonneg} -function checks for nonnegative reals, i.e., reals greater than or -equal to zero. Note that the @kbd{a s} command can simplify an -expression like @expr{x > 0} to 1 or 0 using @code{dpos}, and that -@kbd{a s} is effectively applied to all conditions in rewrite rules, -so the actual functions @code{dpos}, @code{dneg}, and @code{dnonneg} -are rarely necessary. - -@ignore -@starindex -@end ignore -@tindex dnonzero -The @code{dnonzero} function checks that its argument is nonzero. -This includes all nonzero real or complex numbers, all intervals that -do not include zero, all nonzero modulo forms, vectors all of whose -elements are nonzero, and variables or formulas whose values can be -deduced to be nonzero. It does not include error forms, since they -represent values which could be anything including zero. (This is -also the set of objects considered ``true'' in conditional contexts.) - -@ignore -@starindex -@end ignore -@tindex deven -@ignore -@starindex -@end ignore -@tindex dodd -The @code{deven} function returns 1 if its argument is known to be -an even integer (or integer-valued float); it returns 0 if its argument -is known not to be even (because it is known to be odd or a non-integer). -The @kbd{a s} command uses this to simplify a test of the form -@samp{x % 2 = 0}. There is also an analogous @code{dodd} function. - -@ignore -@starindex -@end ignore -@tindex drange -The @code{drange} function returns a set (an interval or a vector -of intervals and/or numbers; @pxref{Set Operations}) that describes -the set of possible values of its argument. If the argument is -a variable or a function with a declaration, the range is copied -from the declaration. Otherwise, the possible signs of the -expression are determined using a method similar to @code{dpos}, -etc., and a suitable set like @samp{[0 .. inf]} is returned. If -the expression is not provably real, the @code{drange} function -remains unevaluated. - -@ignore -@starindex -@end ignore -@tindex dscalar -The @code{dscalar} function returns 1 if its argument is provably -scalar, or 0 if its argument is provably non-scalar. It is left -unevaluated if this cannot be determined. (If Matrix mode or Scalar -mode is in effect, this function returns 1 or 0, respectively, -if it has no other information.) When Calc interprets a condition -(say, in a rewrite rule) it considers an unevaluated formula to be -``false.'' Thus, @samp{dscalar(a)} is ``true'' only if @code{a} is -provably scalar, and @samp{!dscalar(a)} is ``true'' only if @code{a} -is provably non-scalar; both are ``false'' if there is insufficient -information to tell. - -@node Display Modes, Language Modes, Declarations, Mode Settings -@section Display Modes - -@noindent -The commands in this section are two-key sequences beginning with the -@kbd{d} prefix. The @kbd{d l} (@code{calc-line-numbering}) and @kbd{d b} -(@code{calc-line-breaking}) commands are described elsewhere; -@pxref{Stack Basics} and @pxref{Normal Language Modes}, respectively. -Display formats for vectors and matrices are also covered elsewhere; -@pxref{Vector and Matrix Formats}. - -One thing all display modes have in common is their treatment of the -@kbd{H} prefix. This prefix causes any mode command that would normally -refresh the stack to leave the stack display alone. The word ``Dirty'' -will appear in the mode line when Calc thinks the stack display may not -reflect the latest mode settings. - -@kindex d @key{RET} -@pindex calc-refresh-top -The @kbd{d @key{RET}} (@code{calc-refresh-top}) command reformats the -top stack entry according to all the current modes. Positive prefix -arguments reformat the top @var{n} entries; negative prefix arguments -reformat the specified entry, and a prefix of zero is equivalent to -@kbd{d @key{SPC}} (@code{calc-refresh}), which reformats the entire stack. -For example, @kbd{H d s M-2 d @key{RET}} changes to scientific notation -but reformats only the top two stack entries in the new mode. - -The @kbd{I} prefix has another effect on the display modes. The mode -is set only temporarily; the top stack entry is reformatted according -to that mode, then the original mode setting is restored. In other -words, @kbd{I d s} is equivalent to @kbd{H d s d @key{RET} H d (@var{old mode})}. - -@menu -* Radix Modes:: -* Grouping Digits:: -* Float Formats:: -* Complex Formats:: -* Fraction Formats:: -* HMS Formats:: -* Date Formats:: -* Truncating the Stack:: -* Justification:: -* Labels:: -@end menu - -@node Radix Modes, Grouping Digits, Display Modes, Display Modes -@subsection Radix Modes - -@noindent -@cindex Radix display -@cindex Non-decimal numbers -@cindex Decimal and non-decimal numbers -Calc normally displays numbers in decimal (@dfn{base-10} or @dfn{radix-10}) -notation. Calc can actually display in any radix from two (binary) to 36. -When the radix is above 10, the letters @code{A} to @code{Z} are used as -digits. When entering such a number, letter keys are interpreted as -potential digits rather than terminating numeric entry mode. - -@kindex d 2 -@kindex d 8 -@kindex d 6 -@kindex d 0 -@cindex Hexadecimal integers -@cindex Octal integers -The key sequences @kbd{d 2}, @kbd{d 8}, @kbd{d 6}, and @kbd{d 0} select -binary, octal, hexadecimal, and decimal as the current display radix, -respectively. Numbers can always be entered in any radix, though the -current radix is used as a default if you press @kbd{#} without any initial -digits. A number entered without a @kbd{#} is @emph{always} interpreted -as decimal. - -@kindex d r -@pindex calc-radix -To set the radix generally, use @kbd{d r} (@code{calc-radix}) and enter -an integer from 2 to 36. You can specify the radix as a numeric prefix -argument; otherwise you will be prompted for it. - -@kindex d z -@pindex calc-leading-zeros -@cindex Leading zeros -Integers normally are displayed with however many digits are necessary to -represent the integer and no more. The @kbd{d z} (@code{calc-leading-zeros}) -command causes integers to be padded out with leading zeros according to the -current binary word size. (@xref{Binary Functions}, for a discussion of -word size.) If the absolute value of the word size is @expr{w}, all integers -are displayed with at least enough digits to represent -@texline @math{2^w-1} -@infoline @expr{(2^w)-1} -in the current radix. (Larger integers will still be displayed in their -entirety.) - -@cindex Two's complements -Calc can display @expr{w}-bit integers using two's complement -notation, although this is most useful with the binary, octal and -hexadecimal display modes. This option is selected by using the -@kbd{O} option prefix before setting the display radix, and a negative word -size might be appropriate (@pxref{Binary Functions}). In two's -complement notation, the integers in the (nearly) symmetric interval -from -@texline @math{-2^{w-1}} -@infoline @expr{-2^(w-1)} -to -@texline @math{2^{w-1}-1} -@infoline @expr{2^(w-1)-1} -are represented by the integers from @expr{0} to @expr{2^w-1}: -the integers from @expr{0} to -@texline @math{2^{w-1}-1} -@infoline @expr{2^(w-1)-1} -are represented by themselves and the integers from -@texline @math{-2^{w-1}} -@infoline @expr{-2^(w-1)} -to @expr{-1} are represented by the integers from -@texline @math{2^{w-1}} -@infoline @expr{2^(w-1)} -to @expr{2^w-1} (the integer @expr{k} is represented by @expr{k+2^w}). -Calc will display a two's complement integer by the radix (either -@expr{2}, @expr{8} or @expr{16}), two @kbd{#} symbols, and then its -representation (including any leading zeros necessary to include all -@expr{w} bits). In a two's complement display mode, numbers that -are not displayed in two's complement notation (i.e., that aren't -integers from -@texline @math{-2^{w-1}} -@infoline @expr{-2^(w-1)} -to -@c ( -@texline @math{2^{w-1}-1}) -@infoline @expr{2^(w-1)-1}) -will be represented using Calc's usual notation (in the appropriate -radix). - -@node Grouping Digits, Float Formats, Radix Modes, Display Modes -@subsection Grouping Digits - -@noindent -@kindex d g -@pindex calc-group-digits -@cindex Grouping digits -@cindex Digit grouping -Long numbers can be hard to read if they have too many digits. For -example, the factorial of 30 is 33 digits long! Press @kbd{d g} -(@code{calc-group-digits}) to enable @dfn{Grouping} mode, in which digits -are displayed in clumps of 3 or 4 (depending on the current radix) -separated by commas. - -The @kbd{d g} command toggles grouping on and off. -With a numeric prefix of 0, this command displays the current state of -the grouping flag; with an argument of minus one it disables grouping; -with a positive argument @expr{N} it enables grouping on every @expr{N} -digits. For floating-point numbers, grouping normally occurs only -before the decimal point. A negative prefix argument @expr{-N} enables -grouping every @expr{N} digits both before and after the decimal point. - -@kindex d , -@pindex calc-group-char -The @kbd{d ,} (@code{calc-group-char}) command allows you to choose any -character as the grouping separator. The default is the comma character. -If you find it difficult to read vectors of large integers grouped with -commas, you may wish to use spaces or some other character instead. -This command takes the next character you type, whatever it is, and -uses it as the digit separator. As a special case, @kbd{d , \} selects -@samp{\,} (@TeX{}'s thin-space symbol) as the digit separator. - -Please note that grouped numbers will not generally be parsed correctly -if re-read in textual form, say by the use of @kbd{C-x * y} and @kbd{C-x * g}. -(@xref{Kill and Yank}, for details on these commands.) One exception is -the @samp{\,} separator, which doesn't interfere with parsing because it -is ignored by @TeX{} language mode. - -@node Float Formats, Complex Formats, Grouping Digits, Display Modes -@subsection Float Formats - -@noindent -Floating-point quantities are normally displayed in standard decimal -form, with scientific notation used if the exponent is especially high -or low. All significant digits are normally displayed. The commands -in this section allow you to choose among several alternative display -formats for floats. - -@kindex d n -@pindex calc-normal-notation -The @kbd{d n} (@code{calc-normal-notation}) command selects the normal -display format. All significant figures in a number are displayed. -With a positive numeric prefix, numbers are rounded if necessary to -that number of significant digits. With a negative numerix prefix, -the specified number of significant digits less than the current -precision is used. (Thus @kbd{C-u -2 d n} displays 10 digits if the -current precision is 12.) - -@kindex d f -@pindex calc-fix-notation -The @kbd{d f} (@code{calc-fix-notation}) command selects fixed-point -notation. The numeric argument is the number of digits after the -decimal point, zero or more. This format will relax into scientific -notation if a nonzero number would otherwise have been rounded all the -way to zero. Specifying a negative number of digits is the same as -for a positive number, except that small nonzero numbers will be rounded -to zero rather than switching to scientific notation. - -@kindex d s -@pindex calc-sci-notation -@cindex Scientific notation, display of -The @kbd{d s} (@code{calc-sci-notation}) command selects scientific -notation. A positive argument sets the number of significant figures -displayed, of which one will be before and the rest after the decimal -point. A negative argument works the same as for @kbd{d n} format. -The default is to display all significant digits. - -@kindex d e -@pindex calc-eng-notation -@cindex Engineering notation, display of -The @kbd{d e} (@code{calc-eng-notation}) command selects engineering -notation. This is similar to scientific notation except that the -exponent is rounded down to a multiple of three, with from one to three -digits before the decimal point. An optional numeric prefix sets the -number of significant digits to display, as for @kbd{d s}. - -It is important to distinguish between the current @emph{precision} and -the current @emph{display format}. After the commands @kbd{C-u 10 p} -and @kbd{C-u 6 d n} the Calculator computes all results to ten -significant figures but displays only six. (In fact, intermediate -calculations are often carried to one or two more significant figures, -but values placed on the stack will be rounded down to ten figures.) -Numbers are never actually rounded to the display precision for storage, -except by commands like @kbd{C-k} and @kbd{C-x * y} which operate on the -actual displayed text in the Calculator buffer. - -@kindex d . -@pindex calc-point-char -The @kbd{d .} (@code{calc-point-char}) command selects the character used -as a decimal point. Normally this is a period; users in some countries -may wish to change this to a comma. Note that this is only a display -style; on entry, periods must always be used to denote floating-point -numbers, and commas to separate elements in a list. - -@node Complex Formats, Fraction Formats, Float Formats, Display Modes -@subsection Complex Formats - -@noindent -@kindex d c -@pindex calc-complex-notation -There are three supported notations for complex numbers in rectangular -form. The default is as a pair of real numbers enclosed in parentheses -and separated by a comma: @samp{(a,b)}. The @kbd{d c} -(@code{calc-complex-notation}) command selects this style. - -@kindex d i -@pindex calc-i-notation -@kindex d j -@pindex calc-j-notation -The other notations are @kbd{d i} (@code{calc-i-notation}), in which -numbers are displayed in @samp{a+bi} form, and @kbd{d j} -(@code{calc-j-notation}) which displays the form @samp{a+bj} preferred -in some disciplines. - -@cindex @code{i} variable -@vindex i -Complex numbers are normally entered in @samp{(a,b)} format. -If you enter @samp{2+3i} as an algebraic formula, it will be stored as -the formula @samp{2 + 3 * i}. However, if you use @kbd{=} to evaluate -this formula and you have not changed the variable @samp{i}, the @samp{i} -will be interpreted as @samp{(0,1)} and the formula will be simplified -to @samp{(2,3)}. Other commands (like @code{calc-sin}) will @emph{not} -interpret the formula @samp{2 + 3 * i} as a complex number. -@xref{Variables}, under ``special constants.'' - -@node Fraction Formats, HMS Formats, Complex Formats, Display Modes -@subsection Fraction Formats - -@noindent -@kindex d o -@pindex calc-over-notation -Display of fractional numbers is controlled by the @kbd{d o} -(@code{calc-over-notation}) command. By default, a number like -eight thirds is displayed in the form @samp{8:3}. The @kbd{d o} command -prompts for a one- or two-character format. If you give one character, -that character is used as the fraction separator. Common separators are -@samp{:} and @samp{/}. (During input of numbers, the @kbd{:} key must be -used regardless of the display format; in particular, the @kbd{/} is used -for RPN-style division, @emph{not} for entering fractions.) - -If you give two characters, fractions use ``integer-plus-fractional-part'' -notation. For example, the format @samp{+/} would display eight thirds -as @samp{2+2/3}. If two colons are present in a number being entered, -the number is interpreted in this form (so that the entries @kbd{2:2:3} -and @kbd{8:3} are equivalent). - -It is also possible to follow the one- or two-character format with -a number. For example: @samp{:10} or @samp{+/3}. In this case, -Calc adjusts all fractions that are displayed to have the specified -denominator, if possible. Otherwise it adjusts the denominator to -be a multiple of the specified value. For example, in @samp{:6} mode -the fraction @expr{1:6} will be unaffected, but @expr{2:3} will be -displayed as @expr{4:6}, @expr{1:2} will be displayed as @expr{3:6}, -and @expr{1:8} will be displayed as @expr{3:24}. Integers are also -affected by this mode: 3 is displayed as @expr{18:6}. Note that the -format @samp{:1} writes fractions the same as @samp{:}, but it writes -integers as @expr{n:1}. - -The fraction format does not affect the way fractions or integers are -stored, only the way they appear on the screen. The fraction format -never affects floats. - -@node HMS Formats, Date Formats, Fraction Formats, Display Modes -@subsection HMS Formats - -@noindent -@kindex d h -@pindex calc-hms-notation -The @kbd{d h} (@code{calc-hms-notation}) command controls the display of -HMS (hours-minutes-seconds) forms. It prompts for a string which -consists basically of an ``hours'' marker, optional punctuation, a -``minutes'' marker, more optional punctuation, and a ``seconds'' marker. -Punctuation is zero or more spaces, commas, or semicolons. The hours -marker is one or more non-punctuation characters. The minutes and -seconds markers must be single non-punctuation characters. - -The default HMS format is @samp{@@ ' "}, producing HMS values of the form -@samp{23@@ 30' 15.75"}. The format @samp{deg, ms} would display this same -value as @samp{23deg, 30m15.75s}. During numeric entry, the @kbd{h} or @kbd{o} -keys are recognized as synonyms for @kbd{@@} regardless of display format. -The @kbd{m} and @kbd{s} keys are recognized as synonyms for @kbd{'} and -@kbd{"}, respectively, but only if an @kbd{@@} (or @kbd{h} or @kbd{o}) has -already been typed; otherwise, they have their usual meanings -(@kbd{m-} prefix and @kbd{s-} prefix). Thus, @kbd{5 "}, @kbd{0 @@ 5 "}, and -@kbd{0 h 5 s} are some of the ways to enter the quantity ``five seconds.'' -The @kbd{'} key is recognized as ``minutes'' only if @kbd{@@} (or @kbd{h} or -@kbd{o}) has already been pressed; otherwise it means to switch to algebraic -entry. - -@node Date Formats, Truncating the Stack, HMS Formats, Display Modes -@subsection Date Formats - -@noindent -@kindex d d -@pindex calc-date-notation -The @kbd{d d} (@code{calc-date-notation}) command controls the display -of date forms (@pxref{Date Forms}). It prompts for a string which -contains letters that represent the various parts of a date and time. -To show which parts should be omitted when the form represents a pure -date with no time, parts of the string can be enclosed in @samp{< >} -marks. If you don't include @samp{< >} markers in the format, Calc -guesses at which parts, if any, should be omitted when formatting -pure dates. - -The default format is: @samp{Www Mmm D, YYYY}. -An example string in this format is @samp{3:32pm Wed Jan 9, 1991}. -If you enter a blank format string, this default format is -reestablished. - -Calc uses @samp{< >} notation for nameless functions as well as for -dates. @xref{Specifying Operators}. To avoid confusion with nameless -functions, your date formats should avoid using the @samp{#} character. - -@menu -* Date Formatting Codes:: -* Free-Form Dates:: -* Standard Date Formats:: -@end menu - -@node Date Formatting Codes, Free-Form Dates, Date Formats, Date Formats -@subsubsection Date Formatting Codes - -@noindent -When displaying a date, the current date format is used. All -characters except for letters and @samp{<} and @samp{>} are -copied literally when dates are formatted. The portion between -@samp{< >} markers is omitted for pure dates, or included for -date/time forms. Letters are interpreted according to the table -below. - -When dates are read in during algebraic entry, Calc first tries to -match the input string to the current format either with or without -the time part. The punctuation characters (including spaces) must -match exactly; letter fields must correspond to suitable text in -the input. If this doesn't work, Calc checks if the input is a -simple number; if so, the number is interpreted as a number of days -since Jan 1, 1 AD. Otherwise, Calc tries a much more relaxed and -flexible algorithm which is described in the next section. - -Weekday names are ignored during reading. - -Two-digit year numbers are interpreted as lying in the range -from 1941 to 2039. Years outside that range are always -entered and displayed in full. Year numbers with a leading -@samp{+} sign are always interpreted exactly, allowing the -entry and display of the years 1 through 99 AD. - -Here is a complete list of the formatting codes for dates: - -@table @asis -@item Y -Year: ``91'' for 1991, ``7'' for 2007, ``+23'' for 23 AD. -@item YY -Year: ``91'' for 1991, ``07'' for 2007, ``+23'' for 23 AD. -@item BY -Year: ``91'' for 1991, `` 7'' for 2007, ``+23'' for 23 AD. -@item YYY -Year: ``1991'' for 1991, ``23'' for 23 AD. -@item YYYY -Year: ``1991'' for 1991, ``+23'' for 23 AD. -@item aa -Year: ``ad'' or blank. -@item AA -Year: ``AD'' or blank. -@item aaa -Year: ``ad '' or blank. (Note trailing space.) -@item AAA -Year: ``AD '' or blank. -@item aaaa -Year: ``a.d.'' or blank. -@item AAAA -Year: ``A.D.'' or blank. -@item bb -Year: ``bc'' or blank. -@item BB -Year: ``BC'' or blank. -@item bbb -Year: `` bc'' or blank. (Note leading space.) -@item BBB -Year: `` BC'' or blank. -@item bbbb -Year: ``b.c.'' or blank. -@item BBBB -Year: ``B.C.'' or blank. -@item M -Month: ``8'' for August. -@item MM -Month: ``08'' for August. -@item BM -Month: `` 8'' for August. -@item MMM -Month: ``AUG'' for August. -@item Mmm -Month: ``Aug'' for August. -@item mmm -Month: ``aug'' for August. -@item MMMM -Month: ``AUGUST'' for August. -@item Mmmm -Month: ``August'' for August. -@item D -Day: ``7'' for 7th day of month. -@item DD -Day: ``07'' for 7th day of month. -@item BD -Day: `` 7'' for 7th day of month. -@item W -Weekday: ``0'' for Sunday, ``6'' for Saturday. -@item WWW -Weekday: ``SUN'' for Sunday. -@item Www -Weekday: ``Sun'' for Sunday. -@item www -Weekday: ``sun'' for Sunday. -@item WWWW -Weekday: ``SUNDAY'' for Sunday. -@item Wwww -Weekday: ``Sunday'' for Sunday. -@item d -Day of year: ``34'' for Feb. 3. -@item ddd -Day of year: ``034'' for Feb. 3. -@item bdd -Day of year: `` 34'' for Feb. 3. -@item h -Hour: ``5'' for 5 AM; ``17'' for 5 PM. -@item hh -Hour: ``05'' for 5 AM; ``17'' for 5 PM. -@item bh -Hour: `` 5'' for 5 AM; ``17'' for 5 PM. -@item H -Hour: ``5'' for 5 AM and 5 PM. -@item HH -Hour: ``05'' for 5 AM and 5 PM. -@item BH -Hour: `` 5'' for 5 AM and 5 PM. -@item p -AM/PM: ``a'' or ``p''. -@item P -AM/PM: ``A'' or ``P''. -@item pp -AM/PM: ``am'' or ``pm''. -@item PP -AM/PM: ``AM'' or ``PM''. -@item pppp -AM/PM: ``a.m.'' or ``p.m.''. -@item PPPP -AM/PM: ``A.M.'' or ``P.M.''. -@item m -Minutes: ``7'' for 7. -@item mm -Minutes: ``07'' for 7. -@item bm -Minutes: `` 7'' for 7. -@item s -Seconds: ``7'' for 7; ``7.23'' for 7.23. -@item ss -Seconds: ``07'' for 7; ``07.23'' for 7.23. -@item bs -Seconds: `` 7'' for 7; `` 7.23'' for 7.23. -@item SS -Optional seconds: ``07'' for 7; blank for 0. -@item BS -Optional seconds: `` 7'' for 7; blank for 0. -@item N -Numeric date/time: ``726842.25'' for 6:00am Wed Jan 9, 1991. -@item n -Numeric date: ``726842'' for any time on Wed Jan 9, 1991. -@item J -Julian date/time: ``2448265.75'' for 6:00am Wed Jan 9, 1991. -@item j -Julian date: ``2448266'' for any time on Wed Jan 9, 1991. -@item U -Unix time: ``663400800'' for 6:00am Wed Jan 9, 1991. -@item X -Brackets suppression. An ``X'' at the front of the format -causes the surrounding @w{@samp{< >}} delimiters to be omitted -when formatting dates. Note that the brackets are still -required for algebraic entry. -@end table - -If ``SS'' or ``BS'' (optional seconds) is preceded by a colon, the -colon is also omitted if the seconds part is zero. - -If ``bb,'' ``bbb'' or ``bbbb'' or their upper-case equivalents -appear in the format, then negative year numbers are displayed -without a minus sign. Note that ``aa'' and ``bb'' are mutually -exclusive. Some typical usages would be @samp{YYYY AABB}; -@samp{AAAYYYYBBB}; @samp{YYYYBBB}. - -The formats ``YY,'' ``YYYY,'' ``MM,'' ``DD,'' ``ddd,'' ``hh,'' ``HH,'' -``mm,'' ``ss,'' and ``SS'' actually match any number of digits during -reading unless several of these codes are strung together with no -punctuation in between, in which case the input must have exactly as -many digits as there are letters in the format. - -The ``j,'' ``J,'' and ``U'' formats do not make any time zone -adjustment. They effectively use @samp{julian(x,0)} and -@samp{unixtime(x,0)} to make the conversion; @pxref{Date Arithmetic}. - -@node Free-Form Dates, Standard Date Formats, Date Formatting Codes, Date Formats -@subsubsection Free-Form Dates - -@noindent -When reading a date form during algebraic entry, Calc falls back -on the algorithm described here if the input does not exactly -match the current date format. This algorithm generally -``does the right thing'' and you don't have to worry about it, -but it is described here in full detail for the curious. - -Calc does not distinguish between upper- and lower-case letters -while interpreting dates. - -First, the time portion, if present, is located somewhere in the -text and then removed. The remaining text is then interpreted as -the date. - -A time is of the form @samp{hh:mm:ss}, possibly with the seconds -part omitted and possibly with an AM/PM indicator added to indicate -12-hour time. If the AM/PM is present, the minutes may also be -omitted. The AM/PM part may be any of the words @samp{am}, -@samp{pm}, @samp{noon}, or @samp{midnight}; each of these may be -abbreviated to one letter, and the alternate forms @samp{a.m.}, -@samp{p.m.}, and @samp{mid} are also understood. Obviously -@samp{noon} and @samp{midnight} are allowed only on 12:00:00. -The words @samp{noon}, @samp{mid}, and @samp{midnight} are also -recognized with no number attached. - -If there is no AM/PM indicator, the time is interpreted in 24-hour -format. - -To read the date portion, all words and numbers are isolated -from the string; other characters are ignored. All words must -be either month names or day-of-week names (the latter of which -are ignored). Names can be written in full or as three-letter -abbreviations. - -Large numbers, or numbers with @samp{+} or @samp{-} signs, -are interpreted as years. If one of the other numbers is -greater than 12, then that must be the day and the remaining -number in the input is therefore the month. Otherwise, Calc -assumes the month, day and year are in the same order that they -appear in the current date format. If the year is omitted, the -current year is taken from the system clock. - -If there are too many or too few numbers, or any unrecognizable -words, then the input is rejected. - -If there are any large numbers (of five digits or more) other than -the year, they are ignored on the assumption that they are something -like Julian dates that were included along with the traditional -date components when the date was formatted. - -One of the words @samp{ad}, @samp{a.d.}, @samp{bc}, or @samp{b.c.} -may optionally be used; the latter two are equivalent to a -minus sign on the year value. - -If you always enter a four-digit year, and use a name instead -of a number for the month, there is no danger of ambiguity. - -@node Standard Date Formats, , Free-Form Dates, Date Formats -@subsubsection Standard Date Formats - -@noindent -There are actually ten standard date formats, numbered 0 through 9. -Entering a blank line at the @kbd{d d} command's prompt gives -you format number 1, Calc's usual format. You can enter any digit -to select the other formats. - -To create your own standard date formats, give a numeric prefix -argument from 0 to 9 to the @w{@kbd{d d}} command. The format you -enter will be recorded as the new standard format of that -number, as well as becoming the new current date format. -You can save your formats permanently with the @w{@kbd{m m}} -command (@pxref{Mode Settings}). - -@table @asis -@item 0 -@samp{N} (Numerical format) -@item 1 -@samp{Www Mmm D, YYYY} (American format) -@item 2 -@samp{D Mmm YYYY<, h:mm:SS>} (European format) -@item 3 -@samp{Www Mmm BD< hh:mm:ss> YYYY} (Unix written date format) -@item 4 -@samp{M/D/Y< H:mm:SSpp>} (American slashed format) -@item 5 -@samp{D.M.Y< h:mm:SS>} (European dotted format) -@item 6 -@samp{M-D-Y< H:mm:SSpp>} (American dashed format) -@item 7 -@samp{D-M-Y< h:mm:SS>} (European dashed format) -@item 8 -@samp{j<, h:mm:ss>} (Julian day plus time) -@item 9 -@samp{YYddd< hh:mm:ss>} (Year-day format) -@end table - -@node Truncating the Stack, Justification, Date Formats, Display Modes -@subsection Truncating the Stack - -@noindent -@kindex d t -@pindex calc-truncate-stack -@cindex Truncating the stack -@cindex Narrowing the stack -The @kbd{d t} (@code{calc-truncate-stack}) command moves the @samp{.}@: -line that marks the top-of-stack up or down in the Calculator buffer. -The number right above that line is considered to the be at the top of -the stack. Any numbers below that line are ``hidden'' from all stack -operations (although still visible to the user). This is similar to the -Emacs ``narrowing'' feature, except that the values below the @samp{.} -are @emph{visible}, just temporarily frozen. This feature allows you to -keep several independent calculations running at once in different parts -of the stack, or to apply a certain command to an element buried deep in -the stack. - -Pressing @kbd{d t} by itself moves the @samp{.} to the line the cursor -is on. Thus, this line and all those below it become hidden. To un-hide -these lines, move down to the end of the buffer and press @w{@kbd{d t}}. -With a positive numeric prefix argument @expr{n}, @kbd{d t} hides the -bottom @expr{n} values in the buffer. With a negative argument, it hides -all but the top @expr{n} values. With an argument of zero, it hides zero -values, i.e., moves the @samp{.} all the way down to the bottom. - -@kindex d [ -@pindex calc-truncate-up -@kindex d ] -@pindex calc-truncate-down -The @kbd{d [} (@code{calc-truncate-up}) and @kbd{d ]} -(@code{calc-truncate-down}) commands move the @samp{.} up or down one -line at a time (or several lines with a prefix argument). - -@node Justification, Labels, Truncating the Stack, Display Modes -@subsection Justification - -@noindent -@kindex d < -@pindex calc-left-justify -@kindex d = -@pindex calc-center-justify -@kindex d > -@pindex calc-right-justify -Values on the stack are normally left-justified in the window. You can -control this arrangement by typing @kbd{d <} (@code{calc-left-justify}), -@kbd{d >} (@code{calc-right-justify}), or @kbd{d =} -(@code{calc-center-justify}). For example, in Right-Justification mode, -stack entries are displayed flush-right against the right edge of the -window. - -If you change the width of the Calculator window you may have to type -@kbd{d @key{SPC}} (@code{calc-refresh}) to re-align right-justified or centered -text. - -Right-justification is especially useful together with fixed-point -notation (see @code{d f}; @code{calc-fix-notation}). With these modes -together, the decimal points on numbers will always line up. - -With a numeric prefix argument, the justification commands give you -a little extra control over the display. The argument specifies the -horizontal ``origin'' of a display line. It is also possible to -specify a maximum line width using the @kbd{d b} command (@pxref{Normal -Language Modes}). For reference, the precise rules for formatting and -breaking lines are given below. Notice that the interaction between -origin and line width is slightly different in each justification -mode. - -In Left-Justified mode, the line is indented by a number of spaces -given by the origin (default zero). If the result is longer than the -maximum line width, if given, or too wide to fit in the Calc window -otherwise, then it is broken into lines which will fit; each broken -line is indented to the origin. - -In Right-Justified mode, lines are shifted right so that the rightmost -character is just before the origin, or just before the current -window width if no origin was specified. If the line is too long -for this, then it is broken; the current line width is used, if -specified, or else the origin is used as a width if that is -specified, or else the line is broken to fit in the window. - -In Centering mode, the origin is the column number of the center of -each stack entry. If a line width is specified, lines will not be -allowed to go past that width; Calc will either indent less or -break the lines if necessary. If no origin is specified, half the -line width or Calc window width is used. - -Note that, in each case, if line numbering is enabled the display -is indented an additional four spaces to make room for the line -number. The width of the line number is taken into account when -positioning according to the current Calc window width, but not -when positioning by explicit origins and widths. In the latter -case, the display is formatted as specified, and then uniformly -shifted over four spaces to fit the line numbers. - -@node Labels, , Justification, Display Modes -@subsection Labels - -@noindent -@kindex d @{ -@pindex calc-left-label -The @kbd{d @{} (@code{calc-left-label}) command prompts for a string, -then displays that string to the left of every stack entry. If the -entries are left-justified (@pxref{Justification}), then they will -appear immediately after the label (unless you specified an origin -greater than the length of the label). If the entries are centered -or right-justified, the label appears on the far left and does not -affect the horizontal position of the stack entry. - -Give a blank string (with @kbd{d @{ @key{RET}}) to turn the label off. - -@kindex d @} -@pindex calc-right-label -The @kbd{d @}} (@code{calc-right-label}) command similarly adds a -label on the righthand side. It does not affect positioning of -the stack entries unless they are right-justified. Also, if both -a line width and an origin are given in Right-Justified mode, the -stack entry is justified to the origin and the righthand label is -justified to the line width. - -One application of labels would be to add equation numbers to -formulas you are manipulating in Calc and then copying into a -document (possibly using Embedded mode). The equations would -typically be centered, and the equation numbers would be on the -left or right as you prefer. - -@node Language Modes, Modes Variable, Display Modes, Mode Settings -@section Language Modes - -@noindent -The commands in this section change Calc to use a different notation for -entry and display of formulas, corresponding to the conventions of some -other common language such as Pascal or La@TeX{}. Objects displayed on the -stack or yanked from the Calculator to an editing buffer will be formatted -in the current language; objects entered in algebraic entry or yanked from -another buffer will be interpreted according to the current language. - -The current language has no effect on things written to or read from the -trail buffer, nor does it affect numeric entry. Only algebraic entry is -affected. You can make even algebraic entry ignore the current language -and use the standard notation by giving a numeric prefix, e.g., @kbd{C-u '}. - -For example, suppose the formula @samp{2*a[1] + atan(a[2])} occurs in a C -program; elsewhere in the program you need the derivatives of this formula -with respect to @samp{a[1]} and @samp{a[2]}. First, type @kbd{d C} -to switch to C notation. Now use @code{C-u C-x * g} to grab the formula -into the Calculator, @kbd{a d a[1] @key{RET}} to differentiate with respect -to the first variable, and @kbd{C-x * y} to yank the formula for the derivative -back into your C program. Press @kbd{U} to undo the differentiation and -repeat with @kbd{a d a[2] @key{RET}} for the other derivative. - -Without being switched into C mode first, Calc would have misinterpreted -the brackets in @samp{a[1]} and @samp{a[2]}, would not have known that -@code{atan} was equivalent to Calc's built-in @code{arctan} function, -and would have written the formula back with notations (like implicit -multiplication) which would not have been valid for a C program. - -As another example, suppose you are maintaining a C program and a La@TeX{} -document, each of which needs a copy of the same formula. You can grab the -formula from the program in C mode, switch to La@TeX{} mode, and yank the -formula into the document in La@TeX{} math-mode format. - -Language modes are selected by typing the letter @kbd{d} followed by a -shifted letter key. - -@menu -* Normal Language Modes:: -* C FORTRAN Pascal:: -* TeX and LaTeX Language Modes:: -* Eqn Language Mode:: -* Yacas Language Mode:: -* Maxima Language Mode:: -* Giac Language Mode:: -* Mathematica Language Mode:: -* Maple Language Mode:: -* Compositions:: -* Syntax Tables:: -@end menu - -@node Normal Language Modes, C FORTRAN Pascal, Language Modes, Language Modes -@subsection Normal Language Modes - -@noindent -@kindex d N -@pindex calc-normal-language -The @kbd{d N} (@code{calc-normal-language}) command selects the usual -notation for Calc formulas, as described in the rest of this manual. -Matrices are displayed in a multi-line tabular format, but all other -objects are written in linear form, as they would be typed from the -keyboard. - -@kindex d O -@pindex calc-flat-language -@cindex Matrix display -The @kbd{d O} (@code{calc-flat-language}) command selects a language -identical with the normal one, except that matrices are written in -one-line form along with everything else. In some applications this -form may be more suitable for yanking data into other buffers. - -@kindex d b -@pindex calc-line-breaking -@cindex Line breaking -@cindex Breaking up long lines -Even in one-line mode, long formulas or vectors will still be split -across multiple lines if they exceed the width of the Calculator window. -The @kbd{d b} (@code{calc-line-breaking}) command turns this line-breaking -feature on and off. (It works independently of the current language.) -If you give a numeric prefix argument of five or greater to the @kbd{d b} -command, that argument will specify the line width used when breaking -long lines. - -@kindex d B -@pindex calc-big-language -The @kbd{d B} (@code{calc-big-language}) command selects a language -which uses textual approximations to various mathematical notations, -such as powers, quotients, and square roots: - -@example - ____________ - | a + 1 2 - | ----- + c -\| b -@end example - -@noindent -in place of @samp{sqrt((a+1)/b + c^2)}. - -Subscripts like @samp{a_i} are displayed as actual subscripts in Big -mode. Double subscripts, @samp{a_i_j} (@samp{subscr(subscr(a, i), j)}) -are displayed as @samp{a} with subscripts separated by commas: -@samp{i, j}. They must still be entered in the usual underscore -notation. - -One slight ambiguity of Big notation is that - -@example - 3 -- - - 4 -@end example - -@noindent -can represent either the negative rational number @expr{-3:4}, or the -actual expression @samp{-(3/4)}; but the latter formula would normally -never be displayed because it would immediately be evaluated to -@expr{-3:4} or @expr{-0.75}, so this ambiguity is not a problem in -typical use. - -Non-decimal numbers are displayed with subscripts. Thus there is no -way to tell the difference between @samp{16#C2} and @samp{C2_16}, -though generally you will know which interpretation is correct. -Logarithms @samp{log(x,b)} and @samp{log10(x)} also use subscripts -in Big mode. - -In Big mode, stack entries often take up several lines. To aid -readability, stack entries are separated by a blank line in this mode. -You may find it useful to expand the Calc window's height using -@kbd{C-x ^} (@code{enlarge-window}) or to make the Calc window the only -one on the screen with @kbd{C-x 1} (@code{delete-other-windows}). - -Long lines are currently not rearranged to fit the window width in -Big mode, so you may need to use the @kbd{<} and @kbd{>} keys -to scroll across a wide formula. For really big formulas, you may -even need to use @kbd{@{} and @kbd{@}} to scroll up and down. - -@kindex d U -@pindex calc-unformatted-language -The @kbd{d U} (@code{calc-unformatted-language}) command altogether disables -the use of operator notation in formulas. In this mode, the formula -shown above would be displayed: - -@example -sqrt(add(div(add(a, 1), b), pow(c, 2))) -@end example - -These four modes differ only in display format, not in the format -expected for algebraic entry. The standard Calc operators work in -all four modes, and unformatted notation works in any language mode -(except that Mathematica mode expects square brackets instead of -parentheses). - -@node C FORTRAN Pascal, TeX and LaTeX Language Modes, Normal Language Modes, Language Modes -@subsection C, FORTRAN, and Pascal Modes - -@noindent -@kindex d C -@pindex calc-c-language -@cindex C language -The @kbd{d C} (@code{calc-c-language}) command selects the conventions -of the C language for display and entry of formulas. This differs from -the normal language mode in a variety of (mostly minor) ways. In -particular, C language operators and operator precedences are used in -place of Calc's usual ones. For example, @samp{a^b} means @samp{xor(a,b)} -in C mode; a value raised to a power is written as a function call, -@samp{pow(a,b)}. - -In C mode, vectors and matrices use curly braces instead of brackets. -Octal and hexadecimal values are written with leading @samp{0} or @samp{0x} -rather than using the @samp{#} symbol. Array subscripting is -translated into @code{subscr} calls, so that @samp{a[i]} in C -mode is the same as @samp{a_i} in Normal mode. Assignments -turn into the @code{assign} function, which Calc normally displays -using the @samp{:=} symbol. - -The variables @code{pi} and @code{e} would be displayed @samp{pi} -and @samp{e} in Normal mode, but in C mode they are displayed as -@samp{M_PI} and @samp{M_E}, corresponding to the names of constants -typically provided in the @file{} header. Functions whose -names are different in C are translated automatically for entry and -display purposes. For example, entering @samp{asin(x)} will push the -formula @samp{arcsin(x)} onto the stack; this formula will be displayed -as @samp{asin(x)} as long as C mode is in effect. - -@kindex d P -@pindex calc-pascal-language -@cindex Pascal language -The @kbd{d P} (@code{calc-pascal-language}) command selects Pascal -conventions. Like C mode, Pascal mode interprets array brackets and uses -a different table of operators. Hexadecimal numbers are entered and -displayed with a preceding dollar sign. (Thus the regular meaning of -@kbd{$2} during algebraic entry does not work in Pascal mode, though -@kbd{$} (and @kbd{$$}, etc.) not followed by digits works the same as -always.) No special provisions are made for other non-decimal numbers, -vectors, and so on, since there is no universally accepted standard way -of handling these in Pascal. - -@kindex d F -@pindex calc-fortran-language -@cindex FORTRAN language -The @kbd{d F} (@code{calc-fortran-language}) command selects FORTRAN -conventions. Various function names are transformed into FORTRAN -equivalents. Vectors are written as @samp{/1, 2, 3/}, and may be -entered this way or using square brackets. Since FORTRAN uses round -parentheses for both function calls and array subscripts, Calc displays -both in the same way; @samp{a(i)} is interpreted as a function call -upon reading, and subscripts must be entered as @samp{subscr(a, i)}. -If the variable @code{a} has been declared to have type -@code{vector} or @code{matrix}, however, then @samp{a(i)} will be -parsed as a subscript. (@xref{Declarations}.) Usually it doesn't -matter, though; if you enter the subscript expression @samp{a(i)} and -Calc interprets it as a function call, you'll never know the difference -unless you switch to another language mode or replace @code{a} with an -actual vector (or unless @code{a} happens to be the name of a built-in -function!). - -Underscores are allowed in variable and function names in all of these -language modes. The underscore here is equivalent to the @samp{#} in -Normal mode, or to hyphens in the underlying Emacs Lisp variable names. - -FORTRAN and Pascal modes normally do not adjust the case of letters in -formulas. Most built-in Calc names use lower-case letters. If you use a -positive numeric prefix argument with @kbd{d P} or @kbd{d F}, these -modes will use upper-case letters exclusively for display, and will -convert to lower-case on input. With a negative prefix, these modes -convert to lower-case for display and input. - -@node TeX and LaTeX Language Modes, Eqn Language Mode, C FORTRAN Pascal, Language Modes -@subsection @TeX{} and La@TeX{} Language Modes - -@noindent -@kindex d T -@pindex calc-tex-language -@cindex TeX language -@kindex d L -@pindex calc-latex-language -@cindex LaTeX language -The @kbd{d T} (@code{calc-tex-language}) command selects the conventions -of ``math mode'' in Donald Knuth's @TeX{} typesetting language, -and the @kbd{d L} (@code{calc-latex-language}) command selects the -conventions of ``math mode'' in La@TeX{}, a typesetting language that -uses @TeX{} as its formatting engine. Calc's La@TeX{} language mode can -read any formula that the @TeX{} language mode can, although La@TeX{} -mode may display it differently. - -Formulas are entered and displayed in the appropriate notation; -@texline @math{\sin(a/b)} -@infoline @expr{sin(a/b)} -will appear as @samp{\sin\left( @{a \over b@} \right)} in @TeX{} mode and -@samp{\sin\left(\frac@{a@}@{b@}\right)} in La@TeX{} mode. -Math formulas are often enclosed by @samp{$ $} signs in @TeX{} and -La@TeX{}; these should be omitted when interfacing with Calc. To Calc, -the @samp{$} sign has the same meaning it always does in algebraic -formulas (a reference to an existing entry on the stack). - -Complex numbers are displayed as in @samp{3 + 4i}. Fractions and -quotients are written using @code{\over} in @TeX{} mode (as in -@code{@{a \over b@}}) and @code{\frac} in La@TeX{} mode (as in -@code{\frac@{a@}@{b@}}); binomial coefficients are written with -@code{\choose} in @TeX{} mode (as in @code{@{a \choose b@}}) and -@code{\binom} in La@TeX{} mode (as in @code{\binom@{a@}@{b@}}). -Interval forms are written with @code{\ldots}, and error forms are -written with @code{\pm}. Absolute values are written as in -@samp{|x + 1|}, and the floor and ceiling functions are written with -@code{\lfloor}, @code{\rfloor}, etc. The words @code{\left} and -@code{\right} are ignored when reading formulas in @TeX{} and La@TeX{} -modes. Both @code{inf} and @code{uinf} are written as @code{\infty}; -when read, @code{\infty} always translates to @code{inf}. - -Function calls are written the usual way, with the function name followed -by the arguments in parentheses. However, functions for which @TeX{} -and La@TeX{} have special names (like @code{\sin}) will use curly braces -instead of parentheses for very simple arguments. During input, curly -braces and parentheses work equally well for grouping, but when the -document is formatted the curly braces will be invisible. Thus the -printed result is -@texline @math{\sin{2 x}} -@infoline @expr{sin 2x} -but -@texline @math{\sin(2 + x)}. -@infoline @expr{sin(2 + x)}. - -The @TeX{} specific unit names (@pxref{Predefined Units}) will not use -the @samp{tex} prefix; the unit name for a @TeX{} point will be -@samp{pt} instead of @samp{texpt}, for example. - -Function and variable names not treated specially by @TeX{} and La@TeX{} -are simply written out as-is, which will cause them to come out in -italic letters in the printed document. If you invoke @kbd{d T} or -@kbd{d L} with a positive numeric prefix argument, names of more than -one character will instead be enclosed in a protective commands that -will prevent them from being typeset in the math italics; they will be -written @samp{\hbox@{@var{name}@}} in @TeX{} mode and -@samp{\text@{@var{name}@}} in La@TeX{} mode. The -@samp{\hbox@{ @}} and @samp{\text@{ @}} notations are ignored during -reading. If you use a negative prefix argument, such function names are -written @samp{\@var{name}}, and function names that begin with @code{\} during -reading have the @code{\} removed. (Note that in this mode, long -variable names are still written with @code{\hbox} or @code{\text}. -However, you can always make an actual variable name like @code{\bar} in -any @TeX{} mode.) - -During reading, text of the form @samp{\matrix@{ ...@: @}} is replaced -by @samp{[ ...@: ]}. The same also applies to @code{\pmatrix} and -@code{\bmatrix}. In La@TeX{} mode this also applies to -@samp{\begin@{matrix@} ... \end@{matrix@}}, -@samp{\begin@{bmatrix@} ... \end@{bmatrix@}}, -@samp{\begin@{pmatrix@} ... \end@{pmatrix@}}, as well as -@samp{\begin@{smallmatrix@} ... \end@{smallmatrix@}}. -The symbol @samp{&} is interpreted as a comma, -and the symbols @samp{\cr} and @samp{\\} are interpreted as semicolons. -During output, matrices are displayed in @samp{\matrix@{ a & b \\ c & d@}} -format in @TeX{} mode and in -@samp{\begin@{pmatrix@} a & b \\ c & d \end@{pmatrix@}} format in -La@TeX{} mode; you may need to edit this afterwards to change to your -preferred matrix form. If you invoke @kbd{d T} or @kbd{d L} with an -argument of 2 or -2, then matrices will be displayed in two-dimensional -form, such as - -@example -\begin@{pmatrix@} -a & b \\ -c & d -\end@{pmatrix@} -@end example - -@noindent -This may be convenient for isolated matrices, but could lead to -expressions being displayed like - -@example -\begin@{pmatrix@} \times x -a & b \\ -c & d -\end@{pmatrix@} -@end example - -@noindent -While this wouldn't bother Calc, it is incorrect La@TeX{}. -(Similarly for @TeX{}.) - -Accents like @code{\tilde} and @code{\bar} translate into function -calls internally (@samp{tilde(x)}, @samp{bar(x)}). The @code{\underline} -sequence is treated as an accent. The @code{\vec} accent corresponds -to the function name @code{Vec}, because @code{vec} is the name of -a built-in Calc function. The following table shows the accents -in Calc, @TeX{}, La@TeX{} and @dfn{eqn} (described in the next section): - -@ignore -@iftex -@begingroup -@let@calcindexershow=@calcindexernoshow @c Suppress marginal notes -@let@calcindexersh=@calcindexernoshow -@end iftex -@starindex -@end ignore -@tindex acute -@ignore -@starindex -@end ignore -@tindex Acute -@ignore -@starindex -@end ignore -@tindex bar -@ignore -@starindex -@end ignore -@tindex Bar -@ignore -@starindex -@end ignore -@tindex breve -@ignore -@starindex -@end ignore -@tindex Breve -@ignore -@starindex -@end ignore -@tindex check -@ignore -@starindex -@end ignore -@tindex Check -@ignore -@starindex -@end ignore -@tindex dddot -@ignore -@starindex -@end ignore -@tindex ddddot -@ignore -@starindex -@end ignore -@tindex dot -@ignore -@starindex -@end ignore -@tindex Dot -@ignore -@starindex -@end ignore -@tindex dotdot -@ignore -@starindex -@end ignore -@tindex DotDot -@ignore -@starindex -@end ignore -@tindex dyad -@ignore -@starindex -@end ignore -@tindex grave -@ignore -@starindex -@end ignore -@tindex Grave -@ignore -@starindex -@end ignore -@tindex hat -@ignore -@starindex -@end ignore -@tindex Hat -@ignore -@starindex -@end ignore -@tindex Prime -@ignore -@starindex -@end ignore -@tindex tilde -@ignore -@starindex -@end ignore -@tindex Tilde -@ignore -@starindex -@end ignore -@tindex under -@ignore -@starindex -@end ignore -@tindex Vec -@ignore -@starindex -@end ignore -@tindex VEC -@ignore -@iftex -@endgroup -@end iftex -@end ignore -@example -Calc TeX LaTeX eqn ----- --- ----- --- -acute \acute \acute -Acute \Acute -bar \bar \bar bar -Bar \Bar -breve \breve \breve -Breve \Breve -check \check \check -Check \Check -dddot \dddot -ddddot \ddddot -dot \dot \dot dot -Dot \Dot -dotdot \ddot \ddot dotdot -DotDot \Ddot -dyad dyad -grave \grave \grave -Grave \Grave -hat \hat \hat hat -Hat \Hat -Prime prime -tilde \tilde \tilde tilde -Tilde \Tilde -under \underline \underline under -Vec \vec \vec vec -VEC \Vec -@end example - -The @samp{=>} (evaluates-to) operator appears as a @code{\to} symbol: -@samp{@{@var{a} \to @var{b}@}}. @TeX{} defines @code{\to} as an -alias for @code{\rightarrow}. However, if the @samp{=>} is the -top-level expression being formatted, a slightly different notation -is used: @samp{\evalto @var{a} \to @var{b}}. The @code{\evalto} -word is ignored by Calc's input routines, and is undefined in @TeX{}. -You will typically want to include one of the following definitions -at the top of a @TeX{} file that uses @code{\evalto}: - -@example -\def\evalto@{@} -\def\evalto#1\to@{@} -@end example - -The first definition formats evaluates-to operators in the usual -way. The second causes only the @var{b} part to appear in the -printed document; the @var{a} part and the arrow are hidden. -Another definition you may wish to use is @samp{\let\to=\Rightarrow} -which causes @code{\to} to appear more like Calc's @samp{=>} symbol. -@xref{Evaluates-To Operator}, for a discussion of @code{evalto}. - -The complete set of @TeX{} control sequences that are ignored during -reading is: - -@example -\hbox \mbox \text \left \right -\, \> \: \; \! \quad \qquad \hfil \hfill -\displaystyle \textstyle \dsize \tsize -\scriptstyle \scriptscriptstyle \ssize \ssize -\rm \bf \it \sl \roman \bold \italic \slanted -\cal \mit \Cal \Bbb \frak \goth -\evalto -@end example - -Note that, because these symbols are ignored, reading a @TeX{} or -La@TeX{} formula into Calc and writing it back out may lose spacing and -font information. - -Also, the ``discretionary multiplication sign'' @samp{\*} is read -the same as @samp{*}. - -@ifnottex -The @TeX{} version of this manual includes some printed examples at the -end of this section. -@end ifnottex -@iftex -Here are some examples of how various Calc formulas are formatted in @TeX{}: - -@example -@group -sin(a^2 / b_i) -\sin\left( {a^2 \over b_i} \right) -@end group -@end example -@tex -$$ \sin\left( a^2 \over b_i \right) $$ -@end tex -@sp 1 - -@example -@group -[(3, 4), 3:4, 3 +/- 4, [3 .. inf)] -[3 + 4i, @{3 \over 4@}, 3 \pm 4, [3 \ldots \infty)] -@end group -@end example -@tex -$$ [3 + 4i, {3 \over 4}, 3 \pm 4, [ 3 \ldots \infty)] $$ -@end tex -@sp 1 - -@example -@group -[abs(a), abs(a / b), floor(a), ceil(a / b)] -[|a|, \left| a \over b \right|, - \lfloor a \rfloor, \left\lceil a \over b \right\rceil] -@end group -@end example -@tex -$$ [|a|, \left| a \over b \right|, - \lfloor a \rfloor, \left\lceil a \over b \right\rceil] $$ -@end tex -@sp 1 - -@example -@group -[sin(a), sin(2 a), sin(2 + a), sin(a / b)] -[\sin@{a@}, \sin@{2 a@}, \sin(2 + a), - \sin\left( @{a \over b@} \right)] -@end group -@end example -@tex -$$ [\sin{a}, \sin{2 a}, \sin(2 + a), \sin\left( {a \over b} \right)] $$ -@end tex -@sp 2 - -First with plain @kbd{d T}, then with @kbd{C-u d T}, then finally with -@kbd{C-u - d T} (using the example definition -@samp{\def\foo#1@{\tilde F(#1)@}}: - -@example -@group -[f(a), foo(bar), sin(pi)] -[f(a), foo(bar), \sin{\pi}] -[f(a), \hbox@{foo@}(\hbox@{bar@}), \sin@{\pi@}] -[f(a), \foo@{\hbox@{bar@}@}, \sin@{\pi@}] -@end group -@end example -@tex -$$ [f(a), foo(bar), \sin{\pi}] $$ -$$ [f(a), \hbox{foo}(\hbox{bar}), \sin{\pi}] $$ -$$ [f(a), \tilde F(\hbox{bar}), \sin{\pi}] $$ -@end tex -@sp 2 - -First with @samp{\def\evalto@{@}}, then with @samp{\def\evalto#1\to@{@}}: - -@example -@group -2 + 3 => 5 -\evalto 2 + 3 \to 5 -@end group -@end example -@tex -$$ 2 + 3 \to 5 $$ -$$ 5 $$ -@end tex -@sp 2 - -First with standard @code{\to}, then with @samp{\let\to\Rightarrow}: - -@example -@group -[2 + 3 => 5, a / 2 => (b + c) / 2] -[@{2 + 3 \to 5@}, @{@{a \over 2@} \to @{b + c \over 2@}@}] -@end group -@end example -@tex -$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$ -{\let\to\Rightarrow -$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$} -@end tex -@sp 2 - -Matrices normally, then changing @code{\matrix} to @code{\pmatrix}: - -@example -@group -[ [ a / b, 0 ], [ 0, 2^(x + 1) ] ] -\matrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @} -\pmatrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @} -@end group -@end example -@tex -$$ \matrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$ -$$ \pmatrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$ -@end tex -@sp 2 -@end iftex - -@node Eqn Language Mode, Yacas Language Mode, TeX and LaTeX Language Modes, Language Modes -@subsection Eqn Language Mode - -@noindent -@kindex d E -@pindex calc-eqn-language -@dfn{Eqn} is another popular formatter for math formulas. It is -designed for use with the TROFF text formatter, and comes standard -with many versions of Unix. The @kbd{d E} (@code{calc-eqn-language}) -command selects @dfn{eqn} notation. - -The @dfn{eqn} language's main idiosyncrasy is that whitespace plays -a significant part in the parsing of the language. For example, -@samp{sqrt x+1 + y} treats @samp{x+1} as the argument of the -@code{sqrt} operator. @dfn{Eqn} also understands more conventional -grouping using curly braces: @samp{sqrt@{x+1@} + y}. Braces are -required only when the argument contains spaces. - -In Calc's @dfn{eqn} mode, however, curly braces are required to -delimit arguments of operators like @code{sqrt}. The first of the -above examples would treat only the @samp{x} as the argument of -@code{sqrt}, and in fact @samp{sin x+1} would be interpreted as -@samp{sin * x + 1}, because @code{sin} is not a special operator -in the @dfn{eqn} language. If you always surround the argument -with curly braces, Calc will never misunderstand. - -Calc also understands parentheses as grouping characters. Another -peculiarity of @dfn{eqn}'s syntax makes it advisable to separate -words with spaces from any surrounding characters that aren't curly -braces, so Calc writes @samp{sin ( x + y )} in @dfn{eqn} mode. -(The spaces around @code{sin} are important to make @dfn{eqn} -recognize that @code{sin} should be typeset in a roman font, and -the spaces around @code{x} and @code{y} are a good idea just in -case the @dfn{eqn} document has defined special meanings for these -names, too.) - -Powers and subscripts are written with the @code{sub} and @code{sup} -operators, respectively. Note that the caret symbol @samp{^} is -treated the same as a space in @dfn{eqn} mode, as is the @samp{~} -symbol (these are used to introduce spaces of various widths into -the typeset output of @dfn{eqn}). - -As in La@TeX{} mode, Calc's formatter omits parentheses around the -arguments of functions like @code{ln} and @code{sin} if they are -``simple-looking''; in this case Calc surrounds the argument with -braces, separated by a @samp{~} from the function name: @samp{sin~@{x@}}. - -Font change codes (like @samp{roman @var{x}}) and positioning codes -(like @samp{~} and @samp{down @var{n} @var{x}}) are ignored by the -@dfn{eqn} reader. Also ignored are the words @code{left}, @code{right}, -@code{mark}, and @code{lineup}. Quotation marks in @dfn{eqn} mode input -are treated the same as curly braces: @samp{sqrt "1+x"} is equivalent to -@samp{sqrt @{1+x@}}; this is only an approximation to the true meaning -of quotes in @dfn{eqn}, but it is good enough for most uses. - -Accent codes (@samp{@var{x} dot}) are handled by treating them as -function calls (@samp{dot(@var{x})}) internally. -@xref{TeX and LaTeX Language Modes}, for a table of these accent -functions. The @code{prime} accent is treated specially if it occurs on -a variable or function name: @samp{f prime prime @w{( x prime )}} is -stored internally as @samp{f'@w{'}(x')}. For example, taking the -derivative of @samp{f(2 x)} with @kbd{a d x} will produce @samp{2 f'(2 -x)}, which @dfn{eqn} mode will display as @samp{2 f prime ( 2 x )}. - -Assignments are written with the @samp{<-} (left-arrow) symbol, -and @code{evalto} operators are written with @samp{->} or -@samp{evalto ... ->} (@pxref{TeX and LaTeX Language Modes}, for a discussion -of this). The regular Calc symbols @samp{:=} and @samp{=>} are also -recognized for these operators during reading. - -Vectors in @dfn{eqn} mode use regular Calc square brackets, but -matrices are formatted as @samp{matrix @{ ccol @{ a above b @} ... @}}. -The words @code{lcol} and @code{rcol} are recognized as synonyms -for @code{ccol} during input, and are generated instead of @code{ccol} -if the matrix justification mode so specifies. - -@node Yacas Language Mode, Maxima Language Mode, Eqn Language Mode, Language Modes -@subsection Yacas Language Mode - -@noindent -@kindex d Y -@pindex calc-yacas-language -@cindex Yacas language -The @kbd{d Y} (@code{calc-yacas-language}) command selects the -conventions of Yacas, a free computer algebra system. While the -operators and functions in Yacas are similar to those of Calc, the names -of built-in functions in Yacas are capitalized. The Calc formula -@samp{sin(2 x)}, for example, is entered and displayed @samp{Sin(2 x)} -in Yacas mode, and `@samp{arcsin(x^2)} is @samp{ArcSin(x^2)} in Yacas -mode. Complex numbers are written are written @samp{3 + 4 I}. -The standard special constants are written @code{Pi}, @code{E}, -@code{I}, @code{GoldenRatio} and @code{Gamma}. @code{Infinity} -represents both @code{inf} and @code{uinf}, and @code{Undefined} -represents @code{nan}. - -Certain operators on functions, such as @code{D} for differentiation -and @code{Integrate} for integration, take a prefix form in Yacas. For -example, the derivative of @w{@samp{e^x sin(x)}} can be computed with -@w{@samp{D(x) Exp(x)*Sin(x)}}. - -Other notable differences between Yacas and standard Calc expressions -are that vectors and matrices use curly braces in Yacas, and subscripts -use square brackets. If, for example, @samp{A} represents the list -@samp{@{a,2,c,4@}}, then @samp{A[3]} would equal @samp{c}. - - -@node Maxima Language Mode, Giac Language Mode, Yacas Language Mode, Language Modes -@subsection Maxima Language Mode - -@noindent -@kindex d X -@pindex calc-maxima-language -@cindex Maxima language -The @kbd{d X} (@code{calc-maxima-language}) command selects the -conventions of Maxima, another free computer algebra system. The -function names in Maxima are similar, but not always identical, to Calc. -For example, instead of @samp{arcsin(x)}, Maxima will use -@samp{asin(x)}. Complex numbers are written @samp{3 + 4 %i}. The -standard special constants are written @code{%pi}, @code{%e}, -@code{%i}, @code{%phi} and @code{%gamma}. In Maxima, @code{inf} means -the same as in Calc, but @code{infinity} represents Calc's @code{uinf}. - -Underscores as well as percent signs are allowed in function and -variable names in Maxima mode. The underscore again is equivalent to -the @samp{#} in Normal mode, and the percent sign is equivalent to -@samp{o'o}. - -Maxima uses square brackets for lists and vectors, and matrices are -written as calls to the function @code{matrix}, given the row vectors of -the matrix as arguments. Square brackets are also used as subscripts. - -@node Giac Language Mode, Mathematica Language Mode, Maxima Language Mode, Language Modes -@subsection Giac Language Mode - -@noindent -@kindex d A -@pindex calc-giac-language -@cindex Giac language -The @kbd{d A} (@code{calc-giac-language}) command selects the -conventions of Giac, another free computer algebra system. The function -names in Giac are similar to Maxima. Complex numbers are written -@samp{3 + 4 i}. The standard special constants in Giac are the same as -in Calc, except that @code{infinity} represents both Calc's @code{inf} -and @code{uinf}. - -Underscores are allowed in function and variable names in Giac mode. -Brackets are used for subscripts. In Giac, indexing of lists begins at -0, instead of 1 as in Calc. So if @samp{A} represents the list -@samp{[a,2,c,4]}, then @samp{A[2]} would equal @samp{c}. In general, -@samp{A[n]} in Giac mode corresponds to @samp{A_(n+1)} in Normal mode. - -The Giac interval notation @samp{2 .. 3} has no surrounding brackets; -Calc reads @samp{2 .. 3} as the closed interval @samp{[2 .. 3]} and -writes any kind of interval as @samp{2 .. 3}. This means you cannot see -the difference between an open and a closed interval while in Giac mode. - -@node Mathematica Language Mode, Maple Language Mode, Giac Language Mode, Language Modes -@subsection Mathematica Language Mode - -@noindent -@kindex d M -@pindex calc-mathematica-language -@cindex Mathematica language -The @kbd{d M} (@code{calc-mathematica-language}) command selects the -conventions of Mathematica. Notable differences in Mathematica mode -are that the names of built-in functions are capitalized, and function -calls use square brackets instead of parentheses. Thus the Calc -formula @samp{sin(2 x)} is entered and displayed @w{@samp{Sin[2 x]}} in -Mathematica mode. - -Vectors and matrices use curly braces in Mathematica. Complex numbers -are written @samp{3 + 4 I}. The standard special constants in Calc are -written @code{Pi}, @code{E}, @code{I}, @code{GoldenRatio}, @code{EulerGamma}, -@code{Infinity}, @code{ComplexInfinity}, and @code{Indeterminate} in -Mathematica mode. -Non-decimal numbers are written, e.g., @samp{16^^7fff}. Floating-point -numbers in scientific notation are written @samp{1.23*10.^3}. -Subscripts use double square brackets: @samp{a[[i]]}. - -@node Maple Language Mode, Compositions, Mathematica Language Mode, Language Modes -@subsection Maple Language Mode - -@noindent -@kindex d W -@pindex calc-maple-language -@cindex Maple language -The @kbd{d W} (@code{calc-maple-language}) command selects the -conventions of Maple. - -Maple's language is much like C. Underscores are allowed in symbol -names; square brackets are used for subscripts; explicit @samp{*}s for -multiplications are required. Use either @samp{^} or @samp{**} to -denote powers. - -Maple uses square brackets for lists and curly braces for sets. Calc -interprets both notations as vectors, and displays vectors with square -brackets. This means Maple sets will be converted to lists when they -pass through Calc. As a special case, matrices are written as calls -to the function @code{matrix}, given a list of lists as the argument, -and can be read in this form or with all-capitals @code{MATRIX}. - -The Maple interval notation @samp{2 .. 3} is like Giac's interval -notation, and is handled the same by Calc. - -Maple writes complex numbers as @samp{3 + 4*I}. Its special constants -are @code{Pi}, @code{E}, @code{I}, and @code{infinity} (all three of -@code{inf}, @code{uinf}, and @code{nan} display as @code{infinity}). -Floating-point numbers are written @samp{1.23*10.^3}. - -Among things not currently handled by Calc's Maple mode are the -various quote symbols, procedures and functional operators, and -inert (@samp{&}) operators. - -@node Compositions, Syntax Tables, Maple Language Mode, Language Modes -@subsection Compositions - -@noindent -@cindex Compositions -There are several @dfn{composition functions} which allow you to get -displays in a variety of formats similar to those in Big language -mode. Most of these functions do not evaluate to anything; they are -placeholders which are left in symbolic form by Calc's evaluator but -are recognized by Calc's display formatting routines. - -Two of these, @code{string} and @code{bstring}, are described elsewhere. -@xref{Strings}. For example, @samp{string("ABC")} is displayed as -@samp{ABC}. When viewed on the stack it will be indistinguishable from -the variable @code{ABC}, but internally it will be stored as -@samp{string([65, 66, 67])} and can still be manipulated this way; for -example, the selection and vector commands @kbd{j 1 v v j u} would -select the vector portion of this object and reverse the elements, then -deselect to reveal a string whose characters had been reversed. - -The composition functions do the same thing in all language modes -(although their components will of course be formatted in the current -language mode). The one exception is Unformatted mode (@kbd{d U}), -which does not give the composition functions any special treatment. -The functions are discussed here because of their relationship to -the language modes. - -@menu -* Composition Basics:: -* Horizontal Compositions:: -* Vertical Compositions:: -* Other Compositions:: -* Information about Compositions:: -* User-Defined Compositions:: -@end menu - -@node Composition Basics, Horizontal Compositions, Compositions, Compositions -@subsubsection Composition Basics - -@noindent -Compositions are generally formed by stacking formulas together -horizontally or vertically in various ways. Those formulas are -themselves compositions. @TeX{} users will find this analogous -to @TeX{}'s ``boxes.'' Each multi-line composition has a -@dfn{baseline}; horizontal compositions use the baselines to -decide how formulas should be positioned relative to one another. -For example, in the Big mode formula - -@example -@group - 2 - a + b -17 + ------ - c -@end group -@end example - -@noindent -the second term of the sum is four lines tall and has line three as -its baseline. Thus when the term is combined with 17, line three -is placed on the same level as the baseline of 17. - -@tex -\bigskip -@end tex - -Another important composition concept is @dfn{precedence}. This is -an integer that represents the binding strength of various operators. -For example, @samp{*} has higher precedence (195) than @samp{+} (180), -which means that @samp{(a * b) + c} will be formatted without the -parentheses, but @samp{a * (b + c)} will keep the parentheses. - -The operator table used by normal and Big language modes has the -following precedences: - -@example -_ 1200 @r{(subscripts)} -% 1100 @r{(as in n}%@r{)} -! 1000 @r{(as in }!@r{n)} -mod 400 -+/- 300 -!! 210 @r{(as in n}!!@r{)} -! 210 @r{(as in n}!@r{)} -^ 200 -- 197 @r{(as in }-@r{n)} -* 195 @r{(or implicit multiplication)} -/ % \ 190 -+ - 180 @r{(as in a}+@r{b)} -| 170 -< = 160 @r{(and other relations)} -&& 110 -|| 100 -? : 90 -!!! 85 -&&& 80 -||| 75 -:= 50 -:: 45 -=> 40 -@end example - -The general rule is that if an operator with precedence @expr{n} -occurs as an argument to an operator with precedence @expr{m}, then -the argument is enclosed in parentheses if @expr{n < m}. Top-level -expressions and expressions which are function arguments, vector -components, etc., are formatted with precedence zero (so that they -normally never get additional parentheses). - -For binary left-associative operators like @samp{+}, the righthand -argument is actually formatted with one-higher precedence than shown -in the table. This makes sure @samp{(a + b) + c} omits the parentheses, -but the unnatural form @samp{a + (b + c)} keeps its parentheses. -Right-associative operators like @samp{^} format the lefthand argument -with one-higher precedence. - -@ignore -@starindex -@end ignore -@tindex cprec -The @code{cprec} function formats an expression with an arbitrary -precedence. For example, @samp{cprec(abc, 185)} will combine into -sums and products as follows: @samp{7 + abc}, @samp{7 (abc)} (because -this @code{cprec} form has higher precedence than addition, but lower -precedence than multiplication). - -@tex -\bigskip -@end tex - -A final composition issue is @dfn{line breaking}. Calc uses two -different strategies for ``flat'' and ``non-flat'' compositions. -A non-flat composition is anything that appears on multiple lines -(not counting line breaking). Examples would be matrices and Big -mode powers and quotients. Non-flat compositions are displayed -exactly as specified. If they come out wider than the current -window, you must use horizontal scrolling (@kbd{<} and @kbd{>}) to -view them. - -Flat compositions, on the other hand, will be broken across several -lines if they are too wide to fit the window. Certain points in a -composition are noted internally as @dfn{break points}. Calc's -general strategy is to fill each line as much as possible, then to -move down to the next line starting at the first break point that -didn't fit. However, the line breaker understands the hierarchical -structure of formulas. It will not break an ``inner'' formula if -it can use an earlier break point from an ``outer'' formula instead. -For example, a vector of sums might be formatted as: - -@example -@group -[ a + b + c, d + e + f, - g + h + i, j + k + l, m ] -@end group -@end example - -@noindent -If the @samp{m} can fit, then so, it seems, could the @samp{g}. -But Calc prefers to break at the comma since the comma is part -of a ``more outer'' formula. Calc would break at a plus sign -only if it had to, say, if the very first sum in the vector had -itself been too large to fit. - -Of the composition functions described below, only @code{choriz} -generates break points. The @code{bstring} function (@pxref{Strings}) -also generates breakable items: A break point is added after every -space (or group of spaces) except for spaces at the very beginning or -end of the string. - -Composition functions themselves count as levels in the formula -hierarchy, so a @code{choriz} that is a component of a larger -@code{choriz} will be less likely to be broken. As a special case, -if a @code{bstring} occurs as a component of a @code{choriz} or -@code{choriz}-like object (such as a vector or a list of arguments -in a function call), then the break points in that @code{bstring} -will be on the same level as the break points of the surrounding -object. - -@node Horizontal Compositions, Vertical Compositions, Composition Basics, Compositions -@subsubsection Horizontal Compositions - -@noindent -@ignore -@starindex -@end ignore -@tindex choriz -The @code{choriz} function takes a vector of objects and composes -them horizontally. For example, @samp{choriz([17, a b/c, d])} formats -as @w{@samp{17a b / cd}} in Normal language mode, or as - -@example -@group - a b -17---d - c -@end group -@end example - -@noindent -in Big language mode. This is actually one case of the general -function @samp{choriz(@var{vec}, @var{sep}, @var{prec})}, where -either or both of @var{sep} and @var{prec} may be omitted. -@var{Prec} gives the @dfn{precedence} to use when formatting -each of the components of @var{vec}. The default precedence is -the precedence from the surrounding environment. - -@var{Sep} is a string (i.e., a vector of character codes as might -be entered with @code{" "} notation) which should separate components -of the composition. Also, if @var{sep} is given, the line breaker -will allow lines to be broken after each occurrence of @var{sep}. -If @var{sep} is omitted, the composition will not be breakable -(unless any of its component compositions are breakable). - -For example, @samp{2 choriz([a, b c, d = e], " + ", 180)} is -formatted as @samp{2 a + b c + (d = e)}. To get the @code{choriz} -to have precedence 180 ``outwards'' as well as ``inwards,'' -enclose it in a @code{cprec} form: @samp{2 cprec(choriz(...), 180)} -formats as @samp{2 (a + b c + (d = e))}. - -The baseline of a horizontal composition is the same as the -baselines of the component compositions, which are all aligned. - -@node Vertical Compositions, Other Compositions, Horizontal Compositions, Compositions -@subsubsection Vertical Compositions - -@noindent -@ignore -@starindex -@end ignore -@tindex cvert -The @code{cvert} function makes a vertical composition. Each -component of the vector is centered in a column. The baseline of -the result is by default the top line of the resulting composition. -For example, @samp{f(cvert([a, bb, ccc]), cvert([a^2 + 1, b^2]))} -formats in Big mode as - -@example -@group -f( a , 2 ) - bb a + 1 - ccc 2 - b -@end group -@end example - -@ignore -@starindex -@end ignore -@tindex cbase -There are several special composition functions that work only as -components of a vertical composition. The @code{cbase} function -controls the baseline of the vertical composition; the baseline -will be the same as the baseline of whatever component is enclosed -in @code{cbase}. Thus @samp{f(cvert([a, cbase(bb), ccc]), -cvert([a^2 + 1, cbase(b^2)]))} displays as - -@example -@group - 2 - a + 1 - a 2 -f(bb , b ) - ccc -@end group -@end example - -@ignore -@starindex -@end ignore -@tindex ctbase -@ignore -@starindex -@end ignore -@tindex cbbase -There are also @code{ctbase} and @code{cbbase} functions which -make the baseline of the vertical composition equal to the top -or bottom line (rather than the baseline) of that component. -Thus @samp{cvert([cbase(a / b)]) + cvert([ctbase(a / b)]) + -cvert([cbbase(a / b)])} gives - -@example -@group - a -a - -- + a + b -b - - b -@end group -@end example - -There should be only one @code{cbase}, @code{ctbase}, or @code{cbbase} -function in a given vertical composition. These functions can also -be written with no arguments: @samp{ctbase()} is a zero-height object -which means the baseline is the top line of the following item, and -@samp{cbbase()} means the baseline is the bottom line of the preceding -item. - -@ignore -@starindex -@end ignore -@tindex crule -The @code{crule} function builds a ``rule,'' or horizontal line, -across a vertical composition. By itself @samp{crule()} uses @samp{-} -characters to build the rule. You can specify any other character, -e.g., @samp{crule("=")}. The argument must be a character code or -vector of exactly one character code. It is repeated to match the -width of the widest item in the stack. For example, a quotient -with a thick line is @samp{cvert([a + 1, cbase(crule("=")), b^2])}: - -@example -@group -a + 1 -===== - 2 - b -@end group -@end example - -@ignore -@starindex -@end ignore -@tindex clvert -@ignore -@starindex -@end ignore -@tindex crvert -Finally, the functions @code{clvert} and @code{crvert} act exactly -like @code{cvert} except that the items are left- or right-justified -in the stack. Thus @samp{clvert([a, bb, ccc]) + crvert([a, bb, ccc])} -gives: - -@example -@group -a + a -bb bb -ccc ccc -@end group -@end example - -Like @code{choriz}, the vertical compositions accept a second argument -which gives the precedence to use when formatting the components. -Vertical compositions do not support separator strings. - -@node Other Compositions, Information about Compositions, Vertical Compositions, Compositions -@subsubsection Other Compositions - -@noindent -@ignore -@starindex -@end ignore -@tindex csup -The @code{csup} function builds a superscripted expression. For -example, @samp{csup(a, b)} looks the same as @samp{a^b} does in Big -language mode. This is essentially a horizontal composition of -@samp{a} and @samp{b}, where @samp{b} is shifted up so that its -bottom line is one above the baseline. - -@ignore -@starindex -@end ignore -@tindex csub -Likewise, the @code{csub} function builds a subscripted expression. -This shifts @samp{b} down so that its top line is one below the -bottom line of @samp{a} (note that this is not quite analogous to -@code{csup}). Other arrangements can be obtained by using -@code{choriz} and @code{cvert} directly. - -@ignore -@starindex -@end ignore -@tindex cflat -The @code{cflat} function formats its argument in ``flat'' mode, -as obtained by @samp{d O}, if the current language mode is normal -or Big. It has no effect in other language modes. For example, -@samp{a^(b/c)} is formatted by Big mode like @samp{csup(a, cflat(b/c))} -to improve its readability. - -@ignore -@starindex -@end ignore -@tindex cspace -The @code{cspace} function creates horizontal space. For example, -@samp{cspace(4)} is effectively the same as @samp{string(" ")}. -A second string (i.e., vector of characters) argument is repeated -instead of the space character. For example, @samp{cspace(4, "ab")} -looks like @samp{abababab}. If the second argument is not a string, -it is formatted in the normal way and then several copies of that -are composed together: @samp{cspace(4, a^2)} yields - -@example -@group - 2 2 2 2 -a a a a -@end group -@end example - -@noindent -If the number argument is zero, this is a zero-width object. - -@ignore -@starindex -@end ignore -@tindex cvspace -The @code{cvspace} function creates vertical space, or a vertical -stack of copies of a certain string or formatted object. The -baseline is the center line of the resulting stack. A numerical -argument of zero will produce an object which contributes zero -height if used in a vertical composition. - -@ignore -@starindex -@end ignore -@tindex ctspace -@ignore -@starindex -@end ignore -@tindex cbspace -There are also @code{ctspace} and @code{cbspace} functions which -create vertical space with the baseline the same as the baseline -of the top or bottom copy, respectively, of the second argument. -Thus @samp{cvspace(2, a/b) + ctspace(2, a/b) + cbspace(2, a/b)} -displays as: - -@example -@group - a - - -a b -- a a -b + - + - -a b b -- a -b - - b -@end group -@end example - -@node Information about Compositions, User-Defined Compositions, Other Compositions, Compositions -@subsubsection Information about Compositions - -@noindent -The functions in this section are actual functions; they compose their -arguments according to the current language and other display modes, -then return a certain measurement of the composition as an integer. - -@ignore -@starindex -@end ignore -@tindex cwidth -The @code{cwidth} function measures the width, in characters, of a -composition. For example, @samp{cwidth(a + b)} is 5, and -@samp{cwidth(a / b)} is 5 in Normal mode, 1 in Big mode, and 11 in -@TeX{} mode (for @samp{@{a \over b@}}). The argument may involve -the composition functions described in this section. - -@ignore -@starindex -@end ignore -@tindex cheight -The @code{cheight} function measures the height of a composition. -This is the total number of lines in the argument's printed form. - -@ignore -@starindex -@end ignore -@tindex cascent -@ignore -@starindex -@end ignore -@tindex cdescent -The functions @code{cascent} and @code{cdescent} measure the amount -of the height that is above (and including) the baseline, or below -the baseline, respectively. Thus @samp{cascent(@var{x}) + cdescent(@var{x})} -always equals @samp{cheight(@var{x})}. For a one-line formula like -@samp{a + b}, @code{cascent} returns 1 and @code{cdescent} returns 0. -For @samp{a / b} in Big mode, @code{cascent} returns 2 and @code{cdescent} -returns 1. The only formula for which @code{cascent} will return zero -is @samp{cvspace(0)} or equivalents. - -@node User-Defined Compositions, , Information about Compositions, Compositions -@subsubsection User-Defined Compositions - -@noindent -@kindex Z C -@pindex calc-user-define-composition -The @kbd{Z C} (@code{calc-user-define-composition}) command lets you -define the display format for any algebraic function. You provide a -formula containing a certain number of argument variables on the stack. -Any time Calc formats a call to the specified function in the current -language mode and with that number of arguments, Calc effectively -replaces the function call with that formula with the arguments -replaced. - -Calc builds the default argument list by sorting all the variable names -that appear in the formula into alphabetical order. You can edit this -argument list before pressing @key{RET} if you wish. Any variables in -the formula that do not appear in the argument list will be displayed -literally; any arguments that do not appear in the formula will not -affect the display at all. - -You can define formats for built-in functions, for functions you have -defined with @kbd{Z F} (@pxref{Algebraic Definitions}), or for functions -which have no definitions but are being used as purely syntactic objects. -You can define different formats for each language mode, and for each -number of arguments, using a succession of @kbd{Z C} commands. When -Calc formats a function call, it first searches for a format defined -for the current language mode (and number of arguments); if there is -none, it uses the format defined for the Normal language mode. If -neither format exists, Calc uses its built-in standard format for that -function (usually just @samp{@var{func}(@var{args})}). - -If you execute @kbd{Z C} with the number 0 on the stack instead of a -formula, any defined formats for the function in the current language -mode will be removed. The function will revert to its standard format. - -For example, the default format for the binomial coefficient function -@samp{choose(n, m)} in the Big language mode is - -@example -@group - n -( ) - m -@end group -@end example - -@noindent -You might prefer the notation, - -@example -@group - C -n m -@end group -@end example - -@noindent -To define this notation, first make sure you are in Big mode, -then put the formula - -@smallexample -choriz([cvert([cvspace(1), n]), C, cvert([cvspace(1), m])]) -@end smallexample - -@noindent -on the stack and type @kbd{Z C}. Answer the first prompt with -@code{choose}. The second prompt will be the default argument list -of @samp{(C m n)}. Edit this list to be @samp{(n m)} and press -@key{RET}. Now, try it out: For example, turn simplification -off with @kbd{m O} and enter @samp{choose(a,b) + choose(7,3)} -as an algebraic entry. - -@example -@group - C + C -a b 7 3 -@end group -@end example - -As another example, let's define the usual notation for Stirling -numbers of the first kind, @samp{stir1(n, m)}. This is just like -the regular format for binomial coefficients but with square brackets -instead of parentheses. - -@smallexample -choriz([string("["), cvert([n, cbase(cvspace(1)), m]), string("]")]) -@end smallexample - -Now type @kbd{Z C stir1 @key{RET}}, edit the argument list to -@samp{(n m)}, and type @key{RET}. - -The formula provided to @kbd{Z C} usually will involve composition -functions, but it doesn't have to. Putting the formula @samp{a + b + c} -onto the stack and typing @kbd{Z C foo @key{RET} @key{RET}} would define -the function @samp{foo(x,y,z)} to display like @samp{x + y + z}. -This ``sum'' will act exactly like a real sum for all formatting -purposes (it will be parenthesized the same, and so on). However -it will be computationally unrelated to a sum. For example, the -formula @samp{2 * foo(1, 2, 3)} will display as @samp{2 (1 + 2 + 3)}. -Operator precedences have caused the ``sum'' to be written in -parentheses, but the arguments have not actually been summed. -(Generally a display format like this would be undesirable, since -it can easily be confused with a real sum.) - -The special function @code{eval} can be used inside a @kbd{Z C} -composition formula to cause all or part of the formula to be -evaluated at display time. For example, if the formula is -@samp{a + eval(b + c)}, then @samp{foo(1, 2, 3)} will be displayed -as @samp{1 + 5}. Evaluation will use the default simplifications, -regardless of the current simplification mode. There are also -@code{evalsimp} and @code{evalextsimp} which simplify as if by -@kbd{a s} and @kbd{a e} (respectively). Note that these ``functions'' -operate only in the context of composition formulas (and also in -rewrite rules, where they serve a similar purpose; @pxref{Rewrite -Rules}). On the stack, a call to @code{eval} will be left in -symbolic form. - -It is not a good idea to use @code{eval} except as a last resort. -It can cause the display of formulas to be extremely slow. For -example, while @samp{eval(a + b)} might seem quite fast and simple, -there are several situations where it could be slow. For example, -@samp{a} and/or @samp{b} could be polar complex numbers, in which -case doing the sum requires trigonometry. Or, @samp{a} could be -the factorial @samp{fact(100)} which is unevaluated because you -have typed @kbd{m O}; @code{eval} will evaluate it anyway to -produce a large, unwieldy integer. - -You can save your display formats permanently using the @kbd{Z P} -command (@pxref{Creating User Keys}). - -@node Syntax Tables, , Compositions, Language Modes -@subsection Syntax Tables - -@noindent -@cindex Syntax tables -@cindex Parsing formulas, customized -Syntax tables do for input what compositions do for output: They -allow you to teach custom notations to Calc's formula parser. -Calc keeps a separate syntax table for each language mode. - -(Note that the Calc ``syntax tables'' discussed here are completely -unrelated to the syntax tables described in the Emacs manual.) - -@kindex Z S -@pindex calc-edit-user-syntax -The @kbd{Z S} (@code{calc-edit-user-syntax}) command edits the -syntax table for the current language mode. If you want your -syntax to work in any language, define it in the Normal language -mode. Type @kbd{C-c C-c} to finish editing the syntax table, or -@kbd{C-x k} to cancel the edit. The @kbd{m m} command saves all -the syntax tables along with the other mode settings; -@pxref{General Mode Commands}. - -@menu -* Syntax Table Basics:: -* Precedence in Syntax Tables:: -* Advanced Syntax Patterns:: -* Conditional Syntax Rules:: -@end menu - -@node Syntax Table Basics, Precedence in Syntax Tables, Syntax Tables, Syntax Tables -@subsubsection Syntax Table Basics - -@noindent -@dfn{Parsing} is the process of converting a raw string of characters, -such as you would type in during algebraic entry, into a Calc formula. -Calc's parser works in two stages. First, the input is broken down -into @dfn{tokens}, such as words, numbers, and punctuation symbols -like @samp{+}, @samp{:=}, and @samp{+/-}. Space between tokens is -ignored (except when it serves to separate adjacent words). Next, -the parser matches this string of tokens against various built-in -syntactic patterns, such as ``an expression followed by @samp{+} -followed by another expression'' or ``a name followed by @samp{(}, -zero or more expressions separated by commas, and @samp{)}.'' - -A @dfn{syntax table} is a list of user-defined @dfn{syntax rules}, -which allow you to specify new patterns to define your own -favorite input notations. Calc's parser always checks the syntax -table for the current language mode, then the table for the Normal -language mode, before it uses its built-in rules to parse an -algebraic formula you have entered. Each syntax rule should go on -its own line; it consists of a @dfn{pattern}, a @samp{:=} symbol, -and a Calc formula with an optional @dfn{condition}. (Syntax rules -resemble algebraic rewrite rules, but the notation for patterns is -completely different.) - -A syntax pattern is a list of tokens, separated by spaces. -Except for a few special symbols, tokens in syntax patterns are -matched literally, from left to right. For example, the rule, - -@example -foo ( ) := 2+3 -@end example - -@noindent -would cause Calc to parse the formula @samp{4+foo()*5} as if it -were @samp{4+(2+3)*5}. Notice that the parentheses were written -as two separate tokens in the rule. As a result, the rule works -for both @samp{foo()} and @w{@samp{foo ( )}}. If we had written -the rule as @samp{foo () := 2+3}, then Calc would treat @samp{()} -as a single, indivisible token, so that @w{@samp{foo( )}} would -not be recognized by the rule. (It would be parsed as a regular -zero-argument function call instead.) In fact, this rule would -also make trouble for the rest of Calc's parser: An unrelated -formula like @samp{bar()} would now be tokenized into @samp{bar ()} -instead of @samp{bar ( )}, so that the standard parser for function -calls would no longer recognize it! - -While it is possible to make a token with a mixture of letters -and punctuation symbols, this is not recommended. It is better to -break it into several tokens, as we did with @samp{foo()} above. - -The symbol @samp{#} in a syntax pattern matches any Calc expression. -On the righthand side, the things that matched the @samp{#}s can -be referred to as @samp{#1}, @samp{#2}, and so on (where @samp{#1} -matches the leftmost @samp{#} in the pattern). For example, these -rules match a user-defined function, prefix operator, infix operator, -and postfix operator, respectively: - -@example -foo ( # ) := myfunc(#1) -foo # := myprefix(#1) -# foo # := myinfix(#1,#2) -# foo := mypostfix(#1) -@end example - -Thus @samp{foo(3)} will parse as @samp{myfunc(3)}, and @samp{2+3 foo} -will parse as @samp{mypostfix(2+3)}. - -It is important to write the first two rules in the order shown, -because Calc tries rules in order from first to last. If the -pattern @samp{foo #} came first, it would match anything that could -match the @samp{foo ( # )} rule, since an expression in parentheses -is itself a valid expression. Thus the @w{@samp{foo ( # )}} rule would -never get to match anything. Likewise, the last two rules must be -written in the order shown or else @samp{3 foo 4} will be parsed as -@samp{mypostfix(3) * 4}. (Of course, the best way to avoid these -ambiguities is not to use the same symbol in more than one way at -the same time! In case you're not convinced, try the following -exercise: How will the above rules parse the input @samp{foo(3,4)}, -if at all? Work it out for yourself, then try it in Calc and see.) - -Calc is quite flexible about what sorts of patterns are allowed. -The only rule is that every pattern must begin with a literal -token (like @samp{foo} in the first two patterns above), or with -a @samp{#} followed by a literal token (as in the last two -patterns). After that, any mixture is allowed, although putting -two @samp{#}s in a row will not be very useful since two -expressions with nothing between them will be parsed as one -expression that uses implicit multiplication. - -As a more practical example, Maple uses the notation -@samp{sum(a(i), i=1..10)} for sums, which Calc's Maple mode doesn't -recognize at present. To handle this syntax, we simply add the -rule, - -@example -sum ( # , # = # .. # ) := sum(#1,#2,#3,#4) -@end example - -@noindent -to the Maple mode syntax table. As another example, C mode can't -read assignment operators like @samp{++} and @samp{*=}. We can -define these operators quite easily: - -@example -# *= # := muleq(#1,#2) -# ++ := postinc(#1) -++ # := preinc(#1) -@end example - -@noindent -To complete the job, we would use corresponding composition functions -and @kbd{Z C} to cause these functions to display in their respective -Maple and C notations. (Note that the C example ignores issues of -operator precedence, which are discussed in the next section.) - -You can enclose any token in quotes to prevent its usual -interpretation in syntax patterns: - -@example -# ":=" # := becomes(#1,#2) -@end example - -Quotes also allow you to include spaces in a token, although once -again it is generally better to use two tokens than one token with -an embedded space. To include an actual quotation mark in a quoted -token, precede it with a backslash. (This also works to include -backslashes in tokens.) - -@example -# "bad token" # "/\"\\" # := silly(#1,#2,#3) -@end example - -@noindent -This will parse @samp{3 bad token 4 /"\ 5} to @samp{silly(3,4,5)}. - -The token @kbd{#} has a predefined meaning in Calc's formula parser; -it is not valid to use @samp{"#"} in a syntax rule. However, longer -tokens that include the @samp{#} character are allowed. Also, while -@samp{"$"} and @samp{"\""} are allowed as tokens, their presence in -the syntax table will prevent those characters from working in their -usual ways (referring to stack entries and quoting strings, -respectively). - -Finally, the notation @samp{%%} anywhere in a syntax table causes -the rest of the line to be ignored as a comment. - -@node Precedence in Syntax Tables, Advanced Syntax Patterns, Syntax Table Basics, Syntax Tables -@subsubsection Precedence - -@noindent -Different operators are generally assigned different @dfn{precedences}. -By default, an operator defined by a rule like - -@example -# foo # := foo(#1,#2) -@end example - -@noindent -will have an extremely low precedence, so that @samp{2*3+4 foo 5 == 6} -will be parsed as @samp{(2*3+4) foo (5 == 6)}. To change the -precedence of an operator, use the notation @samp{#/@var{p}} in -place of @samp{#}, where @var{p} is an integer precedence level. -For example, 185 lies between the precedences for @samp{+} and -@samp{*}, so if we change this rule to - -@example -#/185 foo #/186 := foo(#1,#2) -@end example - -@noindent -then @samp{2+3 foo 4*5} will be parsed as @samp{2+(3 foo (4*5))}. -Also, because we've given the righthand expression slightly higher -precedence, our new operator will be left-associative: -@samp{1 foo 2 foo 3} will be parsed as @samp{(1 foo 2) foo 3}. -By raising the precedence of the lefthand expression instead, we -can create a right-associative operator. - -@xref{Composition Basics}, for a table of precedences of the -standard Calc operators. For the precedences of operators in other -language modes, look in the Calc source file @file{calc-lang.el}. - -@node Advanced Syntax Patterns, Conditional Syntax Rules, Precedence in Syntax Tables, Syntax Tables -@subsubsection Advanced Syntax Patterns - -@noindent -To match a function with a variable number of arguments, you could -write - -@example -foo ( # ) := myfunc(#1) -foo ( # , # ) := myfunc(#1,#2) -foo ( # , # , # ) := myfunc(#1,#2,#3) -@end example - -@noindent -but this isn't very elegant. To match variable numbers of items, -Calc uses some notations inspired regular expressions and the -``extended BNF'' style used by some language designers. - -@example -foo ( @{ # @}*, ) := apply(myfunc,#1) -@end example - -The token @samp{@{} introduces a repeated or optional portion. -One of the three tokens @samp{@}*}, @samp{@}+}, or @samp{@}?} -ends the portion. These will match zero or more, one or more, -or zero or one copies of the enclosed pattern, respectively. -In addition, @samp{@}*} and @samp{@}+} can be followed by a -separator token (with no space in between, as shown above). -Thus @samp{@{ # @}*,} matches nothing, or one expression, or -several expressions separated by commas. - -A complete @samp{@{ ... @}} item matches as a vector of the -items that matched inside it. For example, the above rule will -match @samp{foo(1,2,3)} to get @samp{apply(myfunc,[1,2,3])}. -The Calc @code{apply} function takes a function name and a vector -of arguments and builds a call to the function with those -arguments, so the net result is the formula @samp{myfunc(1,2,3)}. - -If the body of a @samp{@{ ... @}} contains several @samp{#}s -(or nested @samp{@{ ... @}} constructs), then the items will be -strung together into the resulting vector. If the body -does not contain anything but literal tokens, the result will -always be an empty vector. - -@example -foo ( @{ # , # @}+, ) := bar(#1) -foo ( @{ @{ # @}*, @}*; ) := matrix(#1) -@end example - -@noindent -will parse @samp{foo(1, 2, 3, 4)} as @samp{bar([1, 2, 3, 4])}, and -@samp{foo(1, 2; 3, 4)} as @samp{matrix([[1, 2], [3, 4]])}. Also, after -some thought it's easy to see how this pair of rules will parse -@samp{foo(1, 2, 3)} as @samp{matrix([[1, 2, 3]])}, since the first -rule will only match an even number of arguments. The rule - -@example -foo ( # @{ , # , # @}? ) := bar(#1,#2) -@end example - -@noindent -will parse @samp{foo(2,3,4)} as @samp{bar(2,[3,4])}, and -@samp{foo(2)} as @samp{bar(2,[])}. - -The notation @samp{@{ ... @}?.} (note the trailing period) works -just the same as regular @samp{@{ ... @}?}, except that it does not -count as an argument; the following two rules are equivalent: - -@example -foo ( # , @{ also @}? # ) := bar(#1,#3) -foo ( # , @{ also @}?. # ) := bar(#1,#2) -@end example - -@noindent -Note that in the first case the optional text counts as @samp{#2}, -which will always be an empty vector, but in the second case no -empty vector is produced. - -Another variant is @samp{@{ ... @}?$}, which means the body is -optional only at the end of the input formula. All built-in syntax -rules in Calc use this for closing delimiters, so that during -algebraic entry you can type @kbd{[sqrt(2), sqrt(3 @key{RET}}, omitting -the closing parenthesis and bracket. Calc does this automatically -for trailing @samp{)}, @samp{]}, and @samp{>} tokens in syntax -rules, but you can use @samp{@{ ... @}?$} explicitly to get -this effect with any token (such as @samp{"@}"} or @samp{end}). -Like @samp{@{ ... @}?.}, this notation does not count as an -argument. Conversely, you can use quotes, as in @samp{")"}, to -prevent a closing-delimiter token from being automatically treated -as optional. - -Calc's parser does not have full backtracking, which means some -patterns will not work as you might expect: - -@example -foo ( @{ # , @}? # , # ) := bar(#1,#2,#3) -@end example - -@noindent -Here we are trying to make the first argument optional, so that -@samp{foo(2,3)} parses as @samp{bar([],2,3)}. Unfortunately, Calc -first tries to match @samp{2,} against the optional part of the -pattern, finds a match, and so goes ahead to match the rest of the -pattern. Later on it will fail to match the second comma, but it -doesn't know how to go back and try the other alternative at that -point. One way to get around this would be to use two rules: - -@example -foo ( # , # , # ) := bar([#1],#2,#3) -foo ( # , # ) := bar([],#1,#2) -@end example - -More precisely, when Calc wants to match an optional or repeated -part of a pattern, it scans forward attempting to match that part. -If it reaches the end of the optional part without failing, it -``finalizes'' its choice and proceeds. If it fails, though, it -backs up and tries the other alternative. Thus Calc has ``partial'' -backtracking. A fully backtracking parser would go on to make sure -the rest of the pattern matched before finalizing the choice. - -@node Conditional Syntax Rules, , Advanced Syntax Patterns, Syntax Tables -@subsubsection Conditional Syntax Rules - -@noindent -It is possible to attach a @dfn{condition} to a syntax rule. For -example, the rules - -@example -foo ( # ) := ifoo(#1) :: integer(#1) -foo ( # ) := gfoo(#1) -@end example - -@noindent -will parse @samp{foo(3)} as @samp{ifoo(3)}, but will parse -@samp{foo(3.5)} and @samp{foo(x)} as calls to @code{gfoo}. Any -number of conditions may be attached; all must be true for the -rule to succeed. A condition is ``true'' if it evaluates to a -nonzero number. @xref{Logical Operations}, for a list of Calc -functions like @code{integer} that perform logical tests. - -The exact sequence of events is as follows: When Calc tries a -rule, it first matches the pattern as usual. It then substitutes -@samp{#1}, @samp{#2}, etc., in the conditions, if any. Next, the -conditions are simplified and evaluated in order from left to right, -as if by the @w{@kbd{a s}} algebra command (@pxref{Simplifying Formulas}). -Each result is true if it is a nonzero number, or an expression -that can be proven to be nonzero (@pxref{Declarations}). If the -results of all conditions are true, the expression (such as -@samp{ifoo(#1)}) has its @samp{#}s substituted, and that is the -result of the parse. If the result of any condition is false, Calc -goes on to try the next rule in the syntax table. - -Syntax rules also support @code{let} conditions, which operate in -exactly the same way as they do in algebraic rewrite rules. -@xref{Other Features of Rewrite Rules}, for details. A @code{let} -condition is always true, but as a side effect it defines a -variable which can be used in later conditions, and also in the -expression after the @samp{:=} sign: - -@example -foo ( # ) := hifoo(x) :: let(x := #1 + 0.5) :: dnumint(x) -@end example - -@noindent -The @code{dnumint} function tests if a value is numerically an -integer, i.e., either a true integer or an integer-valued float. -This rule will parse @code{foo} with a half-integer argument, -like @samp{foo(3.5)}, to a call like @samp{hifoo(4.)}. - -The lefthand side of a syntax rule @code{let} must be a simple -variable, not the arbitrary pattern that is allowed in rewrite -rules. - -The @code{matches} function is also treated specially in syntax -rule conditions (again, in the same way as in rewrite rules). -@xref{Matching Commands}. If the matching pattern contains -meta-variables, then those meta-variables may be used in later -conditions and in the result expression. The arguments to -@code{matches} are not evaluated in this situation. - -@example -sum ( # , # ) := sum(#1,a,b,c) :: matches(#2, a=[b..c]) -@end example - -@noindent -This is another way to implement the Maple mode @code{sum} notation. -In this approach, we allow @samp{#2} to equal the whole expression -@samp{i=1..10}. Then, we use @code{matches} to break it apart into -its components. If the expression turns out not to match the pattern, -the syntax rule will fail. Note that @kbd{Z S} always uses Calc's -Normal language mode for editing expressions in syntax rules, so we -must use regular Calc notation for the interval @samp{[b..c]} that -will correspond to the Maple mode interval @samp{1..10}. - -@node Modes Variable, Calc Mode Line, Language Modes, Mode Settings -@section The @code{Modes} Variable - -@noindent -@kindex m g -@pindex calc-get-modes -The @kbd{m g} (@code{calc-get-modes}) command pushes onto the stack -a vector of numbers that describes the various mode settings that -are in effect. With a numeric prefix argument, it pushes only the -@var{n}th mode, i.e., the @var{n}th element of this vector. Keyboard -macros can use the @kbd{m g} command to modify their behavior based -on the current mode settings. - -@cindex @code{Modes} variable -@vindex Modes -The modes vector is also available in the special variable -@code{Modes}. In other words, @kbd{m g} is like @kbd{s r Modes @key{RET}}. -It will not work to store into this variable; in fact, if you do, -@code{Modes} will cease to track the current modes. (The @kbd{m g} -command will continue to work, however.) - -In general, each number in this vector is suitable as a numeric -prefix argument to the associated mode-setting command. (Recall -that the @kbd{~} key takes a number from the stack and gives it as -a numeric prefix to the next command.) - -The elements of the modes vector are as follows: - -@enumerate -@item -Current precision. Default is 12; associated command is @kbd{p}. - -@item -Binary word size. Default is 32; associated command is @kbd{b w}. - -@item -Stack size (not counting the value about to be pushed by @kbd{m g}). -This is zero if @kbd{m g} is executed with an empty stack. - -@item -Number radix. Default is 10; command is @kbd{d r}. - -@item -Floating-point format. This is the number of digits, plus the -constant 0 for normal notation, 10000 for scientific notation, -20000 for engineering notation, or 30000 for fixed-point notation. -These codes are acceptable as prefix arguments to the @kbd{d n} -command, but note that this may lose information: For example, -@kbd{d s} and @kbd{C-u 12 d s} have similar (but not quite -identical) effects if the current precision is 12, but they both -produce a code of 10012, which will be treated by @kbd{d n} as -@kbd{C-u 12 d s}. If the precision then changes, the float format -will still be frozen at 12 significant figures. - -@item -Angular mode. Default is 1 (degrees). Other values are 2 (radians) -and 3 (HMS). The @kbd{m d} command accepts these prefixes. - -@item -Symbolic mode. Value is 0 or 1; default is 0. Command is @kbd{m s}. - -@item -Fraction mode. Value is 0 or 1; default is 0. Command is @kbd{m f}. - -@item -Polar mode. Value is 0 (rectangular) or 1 (polar); default is 0. -Command is @kbd{m p}. - -@item -Matrix/Scalar mode. Default value is @mathit{-1}. Value is 0 for Scalar -mode, @mathit{-2} for Matrix mode, @mathit{-3} for square Matrix mode, -or @var{N} for -@texline @math{N\times N} -@infoline @var{N}x@var{N} -Matrix mode. Command is @kbd{m v}. - -@item -Simplification mode. Default is 1. Value is @mathit{-1} for off (@kbd{m O}), -0 for @kbd{m N}, 2 for @kbd{m B}, 3 for @kbd{m A}, 4 for @kbd{m E}, -or 5 for @w{@kbd{m U}}. The @kbd{m D} command accepts these prefixes. - -@item -Infinite mode. Default is @mathit{-1} (off). Value is 1 if the mode is on, -or 0 if the mode is on with positive zeros. Command is @kbd{m i}. -@end enumerate - -For example, the sequence @kbd{M-1 m g @key{RET} 2 + ~ p} increases the -precision by two, leaving a copy of the old precision on the stack. -Later, @kbd{~ p} will restore the original precision using that -stack value. (This sequence might be especially useful inside a -keyboard macro.) - -As another example, @kbd{M-3 m g 1 - ~ @key{DEL}} deletes all but the -oldest (bottommost) stack entry. - -Yet another example: The HP-48 ``round'' command rounds a number -to the current displayed precision. You could roughly emulate this -in Calc with the sequence @kbd{M-5 m g 10000 % ~ c c}. (This -would not work for fixed-point mode, but it wouldn't be hard to -do a full emulation with the help of the @kbd{Z [} and @kbd{Z ]} -programming commands. @xref{Conditionals in Macros}.) - -@node Calc Mode Line, , Modes Variable, Mode Settings -@section The Calc Mode Line - -@noindent -@cindex Mode line indicators -This section is a summary of all symbols that can appear on the -Calc mode line, the highlighted bar that appears under the Calc -stack window (or under an editing window in Embedded mode). - -The basic mode line format is: - -@example ---%*-Calc: 12 Deg @var{other modes} (Calculator) -@end example - -The @samp{%*} indicates that the buffer is ``read-only''; it shows that -regular Emacs commands are not allowed to edit the stack buffer -as if it were text. - -The word @samp{Calc:} changes to @samp{CalcEmbed:} if Embedded mode -is enabled. The words after this describe the various Calc modes -that are in effect. - -The first mode is always the current precision, an integer. -The second mode is always the angular mode, either @code{Deg}, -@code{Rad}, or @code{Hms}. - -Here is a complete list of the remaining symbols that can appear -on the mode line: - -@table @code -@item Alg -Algebraic mode (@kbd{m a}; @pxref{Algebraic Entry}). - -@item Alg[( -Incomplete algebraic mode (@kbd{C-u m a}). - -@item Alg* -Total algebraic mode (@kbd{m t}). - -@item Symb -Symbolic mode (@kbd{m s}; @pxref{Symbolic Mode}). - -@item Matrix -Matrix mode (@kbd{m v}; @pxref{Matrix Mode}). - -@item Matrix@var{n} -Dimensioned Matrix mode (@kbd{C-u @var{n} m v}; @pxref{Matrix Mode}). - -@item SqMatrix -Square Matrix mode (@kbd{C-u m v}; @pxref{Matrix Mode}). - -@item Scalar -Scalar mode (@kbd{m v}; @pxref{Matrix Mode}). - -@item Polar -Polar complex mode (@kbd{m p}; @pxref{Polar Mode}). - -@item Frac -Fraction mode (@kbd{m f}; @pxref{Fraction Mode}). - -@item Inf -Infinite mode (@kbd{m i}; @pxref{Infinite Mode}). - -@item +Inf -Positive Infinite mode (@kbd{C-u 0 m i}). - -@item NoSimp -Default simplifications off (@kbd{m O}; @pxref{Simplification Modes}). - -@item NumSimp -Default simplifications for numeric arguments only (@kbd{m N}). - -@item BinSimp@var{w} -Binary-integer simplification mode; word size @var{w} (@kbd{m B}, @kbd{b w}). - -@item AlgSimp -Algebraic simplification mode (@kbd{m A}). - -@item ExtSimp -Extended algebraic simplification mode (@kbd{m E}). - -@item UnitSimp -Units simplification mode (@kbd{m U}). - -@item Bin -Current radix is 2 (@kbd{d 2}; @pxref{Radix Modes}). - -@item Oct -Current radix is 8 (@kbd{d 8}). - -@item Hex -Current radix is 16 (@kbd{d 6}). - -@item Radix@var{n} -Current radix is @var{n} (@kbd{d r}). - -@item Zero -Leading zeros (@kbd{d z}; @pxref{Radix Modes}). - -@item Big -Big language mode (@kbd{d B}; @pxref{Normal Language Modes}). - -@item Flat -One-line normal language mode (@kbd{d O}). - -@item Unform -Unformatted language mode (@kbd{d U}). - -@item C -C language mode (@kbd{d C}; @pxref{C FORTRAN Pascal}). - -@item Pascal -Pascal language mode (@kbd{d P}). - -@item Fortran -FORTRAN language mode (@kbd{d F}). - -@item TeX -@TeX{} language mode (@kbd{d T}; @pxref{TeX and LaTeX Language Modes}). - -@item LaTeX -La@TeX{} language mode (@kbd{d L}; @pxref{TeX and LaTeX Language Modes}). - -@item Eqn -@dfn{Eqn} language mode (@kbd{d E}; @pxref{Eqn Language Mode}). - -@item Math -Mathematica language mode (@kbd{d M}; @pxref{Mathematica Language Mode}). - -@item Maple -Maple language mode (@kbd{d W}; @pxref{Maple Language Mode}). - -@item Norm@var{n} -Normal float mode with @var{n} digits (@kbd{d n}; @pxref{Float Formats}). - -@item Fix@var{n} -Fixed point mode with @var{n} digits after the point (@kbd{d f}). - -@item Sci -Scientific notation mode (@kbd{d s}). - -@item Sci@var{n} -Scientific notation with @var{n} digits (@kbd{d s}). - -@item Eng -Engineering notation mode (@kbd{d e}). - -@item Eng@var{n} -Engineering notation with @var{n} digits (@kbd{d e}). - -@item Left@var{n} -Left-justified display indented by @var{n} (@kbd{d <}; @pxref{Justification}). - -@item Right -Right-justified display (@kbd{d >}). - -@item Right@var{n} -Right-justified display with width @var{n} (@kbd{d >}). - -@item Center -Centered display (@kbd{d =}). - -@item Center@var{n} -Centered display with center column @var{n} (@kbd{d =}). - -@item Wid@var{n} -Line breaking with width @var{n} (@kbd{d b}; @pxref{Normal Language Modes}). - -@item Wide -No line breaking (@kbd{d b}). - -@item Break -Selections show deep structure (@kbd{j b}; @pxref{Making Selections}). - -@item Save -Record modes in @file{~/.emacs.d/calc.el} (@kbd{m R}; @pxref{General Mode Commands}). - -@item Local -Record modes in Embedded buffer (@kbd{m R}). - -@item LocEdit -Record modes as editing-only in Embedded buffer (@kbd{m R}). - -@item LocPerm -Record modes as permanent-only in Embedded buffer (@kbd{m R}). - -@item Global -Record modes as global in Embedded buffer (@kbd{m R}). - -@item Manual -Automatic recomputation turned off (@kbd{m C}; @pxref{Automatic -Recomputation}). - -@item Graph -GNUPLOT process is alive in background (@pxref{Graphics}). - -@item Sel -Top-of-stack has a selection (Embedded only; @pxref{Making Selections}). - -@item Dirty -The stack display may not be up-to-date (@pxref{Display Modes}). - -@item Inv -``Inverse'' prefix was pressed (@kbd{I}; @pxref{Inverse and Hyperbolic}). - -@item Hyp -``Hyperbolic'' prefix was pressed (@kbd{H}). - -@item Keep -``Keep-arguments'' prefix was pressed (@kbd{K}). - -@item Narrow -Stack is truncated (@kbd{d t}; @pxref{Truncating the Stack}). -@end table - -In addition, the symbols @code{Active} and @code{~Active} can appear -as minor modes on an Embedded buffer's mode line. @xref{Embedded Mode}. - -@node Arithmetic, Scientific Functions, Mode Settings, Top -@chapter Arithmetic Functions - -@noindent -This chapter describes the Calc commands for doing simple calculations -on numbers, such as addition, absolute value, and square roots. These -commands work by removing the top one or two values from the stack, -performing the desired operation, and pushing the result back onto the -stack. If the operation cannot be performed, the result pushed is a -formula instead of a number, such as @samp{2/0} (because division by zero -is invalid) or @samp{sqrt(x)} (because the argument @samp{x} is a formula). - -Most of the commands described here can be invoked by a single keystroke. -Some of the more obscure ones are two-letter sequences beginning with -the @kbd{f} (``functions'') prefix key. - -@xref{Prefix Arguments}, for a discussion of the effect of numeric -prefix arguments on commands in this chapter which do not otherwise -interpret a prefix argument. - -@menu -* Basic Arithmetic:: -* Integer Truncation:: -* Complex Number Functions:: -* Conversions:: -* Date Arithmetic:: -* Financial Functions:: -* Binary Functions:: -@end menu - -@node Basic Arithmetic, Integer Truncation, Arithmetic, Arithmetic -@section Basic Arithmetic - -@noindent -@kindex + -@pindex calc-plus -@ignore -@mindex @null -@end ignore -@tindex + -The @kbd{+} (@code{calc-plus}) command adds two numbers. The numbers may -be any of the standard Calc data types. The resulting sum is pushed back -onto the stack. - -If both arguments of @kbd{+} are vectors or matrices (of matching dimensions), -the result is a vector or matrix sum. If one argument is a vector and the -other a scalar (i.e., a non-vector), the scalar is added to each of the -elements of the vector to form a new vector. If the scalar is not a -number, the operation is left in symbolic form: Suppose you added @samp{x} -to the vector @samp{[1,2]}. You may want the result @samp{[1+x,2+x]}, or -you may plan to substitute a 2-vector for @samp{x} in the future. Since -the Calculator can't tell which interpretation you want, it makes the -safest assumption. @xref{Reducing and Mapping}, for a way to add @samp{x} -to every element of a vector. - -If either argument of @kbd{+} is a complex number, the result will in general -be complex. If one argument is in rectangular form and the other polar, -the current Polar mode determines the form of the result. If Symbolic -mode is enabled, the sum may be left as a formula if the necessary -conversions for polar addition are non-trivial. - -If both arguments of @kbd{+} are HMS forms, the forms are added according to -the usual conventions of hours-minutes-seconds notation. If one argument -is an HMS form and the other is a number, that number is converted from -degrees or radians (depending on the current Angular mode) to HMS format -and then the two HMS forms are added. - -If one argument of @kbd{+} is a date form, the other can be either a -real number, which advances the date by a certain number of days, or -an HMS form, which advances the date by a certain amount of time. -Subtracting two date forms yields the number of days between them. -Adding two date forms is meaningless, but Calc interprets it as the -subtraction of one date form and the negative of the other. (The -negative of a date form can be understood by remembering that dates -are stored as the number of days before or after Jan 1, 1 AD.) - -If both arguments of @kbd{+} are error forms, the result is an error form -with an appropriately computed standard deviation. If one argument is an -error form and the other is a number, the number is taken to have zero error. -Error forms may have symbolic formulas as their mean and/or error parts; -adding these will produce a symbolic error form result. However, adding an -error form to a plain symbolic formula (as in @samp{(a +/- b) + c}) will not -work, for the same reasons just mentioned for vectors. Instead you must -write @samp{(a +/- b) + (c +/- 0)}. - -If both arguments of @kbd{+} are modulo forms with equal values of @expr{M}, -or if one argument is a modulo form and the other a plain number, the -result is a modulo form which represents the sum, modulo @expr{M}, of -the two values. - -If both arguments of @kbd{+} are intervals, the result is an interval -which describes all possible sums of the possible input values. If -one argument is a plain number, it is treated as the interval -@w{@samp{[x ..@: x]}}. - -If one argument of @kbd{+} is an infinity and the other is not, the -result is that same infinity. If both arguments are infinite and in -the same direction, the result is the same infinity, but if they are -infinite in different directions the result is @code{nan}. - -@kindex - -@pindex calc-minus -@ignore -@mindex @null -@end ignore -@tindex - -The @kbd{-} (@code{calc-minus}) command subtracts two values. The top -number on the stack is subtracted from the one behind it, so that the -computation @kbd{5 @key{RET} 2 -} produces 3, not @mathit{-3}. All options -available for @kbd{+} are available for @kbd{-} as well. - -@kindex * -@pindex calc-times -@ignore -@mindex @null -@end ignore -@tindex * -The @kbd{*} (@code{calc-times}) command multiplies two numbers. If one -argument is a vector and the other a scalar, the scalar is multiplied by -the elements of the vector to produce a new vector. If both arguments -are vectors, the interpretation depends on the dimensions of the -vectors: If both arguments are matrices, a matrix multiplication is -done. If one argument is a matrix and the other a plain vector, the -vector is interpreted as a row vector or column vector, whichever is -dimensionally correct. If both arguments are plain vectors, the result -is a single scalar number which is the dot product of the two vectors. - -If one argument of @kbd{*} is an HMS form and the other a number, the -HMS form is multiplied by that amount. It is an error to multiply two -HMS forms together, or to attempt any multiplication involving date -forms. Error forms, modulo forms, and intervals can be multiplied; -see the comments for addition of those forms. When two error forms -or intervals are multiplied they are considered to be statistically -independent; thus, @samp{[-2 ..@: 3] * [-2 ..@: 3]} is @samp{[-6 ..@: 9]}, -whereas @w{@samp{[-2 ..@: 3] ^ 2}} is @samp{[0 ..@: 9]}. - -@kindex / -@pindex calc-divide -@ignore -@mindex @null -@end ignore -@tindex / -The @kbd{/} (@code{calc-divide}) command divides two numbers. - -When combining multiplication and division in an algebraic formula, it -is good style to use parentheses to distinguish between possible -interpretations; the expression @samp{a/b*c} should be written -@samp{(a/b)*c} or @samp{a/(b*c)}, as appropriate. Without the -parentheses, Calc will interpret @samp{a/b*c} as @samp{a/(b*c)}, since -in algebraic entry Calc gives division a lower precedence than -multiplication. (This is not standard across all computer languages, and -Calc may change the precedence depending on the language mode being used. -@xref{Language Modes}.) This default ordering can be changed by setting -the customizable variable @code{calc-multiplication-has-precedence} to -@code{nil} (@pxref{Customizing Calc}); this will give multiplication and -division equal precedences. Note that Calc's default choice of -precedence allows @samp{a b / c d} to be used as a shortcut for -@smallexample -@group -a b ----. -c d -@end group -@end smallexample - -When dividing a scalar @expr{B} by a square matrix @expr{A}, the -computation performed is @expr{B} times the inverse of @expr{A}. This -also occurs if @expr{B} is itself a vector or matrix, in which case the -effect is to solve the set of linear equations represented by @expr{B}. -If @expr{B} is a matrix with the same number of rows as @expr{A}, or a -plain vector (which is interpreted here as a column vector), then the -equation @expr{A X = B} is solved for the vector or matrix @expr{X}. -Otherwise, if @expr{B} is a non-square matrix with the same number of -@emph{columns} as @expr{A}, the equation @expr{X A = B} is solved. If -you wish a vector @expr{B} to be interpreted as a row vector to be -solved as @expr{X A = B}, make it into a one-row matrix with @kbd{C-u 1 -v p} first. To force a left-handed solution with a square matrix -@expr{B}, transpose @expr{A} and @expr{B} before dividing, then -transpose the result. - -HMS forms can be divided by real numbers or by other HMS forms. Error -forms can be divided in any combination of ways. Modulo forms where both -values and the modulo are integers can be divided to get an integer modulo -form result. Intervals can be divided; dividing by an interval that -encompasses zero or has zero as a limit will result in an infinite -interval. - -@kindex ^ -@pindex calc-power -@ignore -@mindex @null -@end ignore -@tindex ^ -The @kbd{^} (@code{calc-power}) command raises a number to a power. If -the power is an integer, an exact result is computed using repeated -multiplications. For non-integer powers, Calc uses Newton's method or -logarithms and exponentials. Square matrices can be raised to integer -powers. If either argument is an error (or interval or modulo) form, -the result is also an error (or interval or modulo) form. - -@kindex I ^ -@tindex nroot -If you press the @kbd{I} (inverse) key first, the @kbd{I ^} command -computes an Nth root: @kbd{125 @key{RET} 3 I ^} computes the number 5. -(This is entirely equivalent to @kbd{125 @key{RET} 1:3 ^}.) - -@kindex \ -@pindex calc-idiv -@tindex idiv -@ignore -@mindex @null -@end ignore -@tindex \ -The @kbd{\} (@code{calc-idiv}) command divides two numbers on the stack -to produce an integer result. It is equivalent to dividing with -@key{/}, then rounding down with @kbd{F} (@code{calc-floor}), only a bit -more convenient and efficient. Also, since it is an all-integer -operation when the arguments are integers, it avoids problems that -@kbd{/ F} would have with floating-point roundoff. - -@kindex % -@pindex calc-mod -@ignore -@mindex @null -@end ignore -@tindex % -The @kbd{%} (@code{calc-mod}) command performs a ``modulo'' (or ``remainder'') -operation. Mathematically, @samp{a%b = a - (a\b)*b}, and is defined -for all real numbers @expr{a} and @expr{b} (except @expr{b=0}). For -positive @expr{b}, the result will always be between 0 (inclusive) and -@expr{b} (exclusive). Modulo does not work for HMS forms and error forms. -If @expr{a} is a modulo form, its modulo is changed to @expr{b}, which -must be positive real number. - -@kindex : -@pindex calc-fdiv -@tindex fdiv -The @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command -divides the two integers on the top of the stack to produce a fractional -result. This is a convenient shorthand for enabling Fraction mode (with -@kbd{m f}) temporarily and using @samp{/}. Note that during numeric entry -the @kbd{:} key is interpreted as a fraction separator, so to divide 8 by 6 -you would have to type @kbd{8 @key{RET} 6 @key{RET} :}. (Of course, in -this case, it would be much easier simply to enter the fraction directly -as @kbd{8:6 @key{RET}}!) - -@kindex n -@pindex calc-change-sign -The @kbd{n} (@code{calc-change-sign}) command negates the number on the top -of the stack. It works on numbers, vectors and matrices, HMS forms, date -forms, error forms, intervals, and modulo forms. - -@kindex A -@pindex calc-abs -@tindex abs -The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the absolute -value of a number. The result of @code{abs} is always a nonnegative -real number: With a complex argument, it computes the complex magnitude. -With a vector or matrix argument, it computes the Frobenius norm, i.e., -the square root of the sum of the squares of the absolute values of the -elements. The absolute value of an error form is defined by replacing -the mean part with its absolute value and leaving the error part the same. -The absolute value of a modulo form is undefined. The absolute value of -an interval is defined in the obvious way. - -@kindex f A -@pindex calc-abssqr -@tindex abssqr -The @kbd{f A} (@code{calc-abssqr}) [@code{abssqr}] command computes the -absolute value squared of a number, vector or matrix, or error form. - -@kindex f s -@pindex calc-sign -@tindex sign -The @kbd{f s} (@code{calc-sign}) [@code{sign}] command returns 1 if its -argument is positive, @mathit{-1} if its argument is negative, or 0 if its -argument is zero. In algebraic form, you can also write @samp{sign(a,x)} -which evaluates to @samp{x * sign(a)}, i.e., either @samp{x}, @samp{-x}, or -zero depending on the sign of @samp{a}. - -@kindex & -@pindex calc-inv -@tindex inv -@cindex Reciprocal -The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the -reciprocal of a number, i.e., @expr{1 / x}. Operating on a square -matrix, it computes the inverse of that matrix. - -@kindex Q -@pindex calc-sqrt -@tindex sqrt -The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] command computes the square -root of a number. For a negative real argument, the result will be a -complex number whose form is determined by the current Polar mode. - -@kindex f h -@pindex calc-hypot -@tindex hypot -The @kbd{f h} (@code{calc-hypot}) [@code{hypot}] command computes the square -root of the sum of the squares of two numbers. That is, @samp{hypot(a,b)} -is the length of the hypotenuse of a right triangle with sides @expr{a} -and @expr{b}. If the arguments are complex numbers, their squared -magnitudes are used. - -@kindex f Q -@pindex calc-isqrt -@tindex isqrt -The @kbd{f Q} (@code{calc-isqrt}) [@code{isqrt}] command computes the -integer square root of an integer. This is the true square root of the -number, rounded down to an integer. For example, @samp{isqrt(10)} -produces 3. Note that, like @kbd{\} [@code{idiv}], this uses exact -integer arithmetic throughout to avoid roundoff problems. If the input -is a floating-point number or other non-integer value, this is exactly -the same as @samp{floor(sqrt(x))}. - -@kindex f n -@kindex f x -@pindex calc-min -@tindex min -@pindex calc-max -@tindex max -The @kbd{f n} (@code{calc-min}) [@code{min}] and @kbd{f x} (@code{calc-max}) -[@code{max}] commands take the minimum or maximum of two real numbers, -respectively. These commands also work on HMS forms, date forms, -intervals, and infinities. (In algebraic expressions, these functions -take any number of arguments and return the maximum or minimum among -all the arguments.) - -@kindex f M -@kindex f X -@pindex calc-mant-part -@tindex mant -@pindex calc-xpon-part -@tindex xpon -The @kbd{f M} (@code{calc-mant-part}) [@code{mant}] function extracts -the ``mantissa'' part @expr{m} of its floating-point argument; @kbd{f X} -(@code{calc-xpon-part}) [@code{xpon}] extracts the ``exponent'' part -@expr{e}. The original number is equal to -@texline @math{m \times 10^e}, -@infoline @expr{m * 10^e}, -where @expr{m} is in the interval @samp{[1.0 ..@: 10.0)} except that -@expr{m=e=0} if the original number is zero. For integers -and fractions, @code{mant} returns the number unchanged and @code{xpon} -returns zero. The @kbd{v u} (@code{calc-unpack}) command can also be -used to ``unpack'' a floating-point number; this produces an integer -mantissa and exponent, with the constraint that the mantissa is not -a multiple of ten (again except for the @expr{m=e=0} case). - -@kindex f S -@pindex calc-scale-float -@tindex scf -The @kbd{f S} (@code{calc-scale-float}) [@code{scf}] function scales a number -by a given power of ten. Thus, @samp{scf(mant(x), xpon(x)) = x} for any -real @samp{x}. The second argument must be an integer, but the first -may actually be any numeric value. For example, @samp{scf(5,-2) = 0.05} -or @samp{1:20} depending on the current Fraction mode. - -@kindex f [ -@kindex f ] -@pindex calc-decrement -@pindex calc-increment -@tindex decr -@tindex incr -The @kbd{f [} (@code{calc-decrement}) [@code{decr}] and @kbd{f ]} -(@code{calc-increment}) [@code{incr}] functions decrease or increase -a number by one unit. For integers, the effect is obvious. For -floating-point numbers, the change is by one unit in the last place. -For example, incrementing @samp{12.3456} when the current precision -is 6 digits yields @samp{12.3457}. If the current precision had been -8 digits, the result would have been @samp{12.345601}. Incrementing -@samp{0.0} produces -@texline @math{10^{-p}}, -@infoline @expr{10^-p}, -where @expr{p} is the current -precision. These operations are defined only on integers and floats. -With numeric prefix arguments, they change the number by @expr{n} units. - -Note that incrementing followed by decrementing, or vice-versa, will -almost but not quite always cancel out. Suppose the precision is -6 digits and the number @samp{9.99999} is on the stack. Incrementing -will produce @samp{10.0000}; decrementing will produce @samp{9.9999}. -One digit has been dropped. This is an unavoidable consequence of the -way floating-point numbers work. - -Incrementing a date/time form adjusts it by a certain number of seconds. -Incrementing a pure date form adjusts it by a certain number of days. - -@node Integer Truncation, Complex Number Functions, Basic Arithmetic, Arithmetic -@section Integer Truncation - -@noindent -There are four commands for truncating a real number to an integer, -differing mainly in their treatment of negative numbers. All of these -commands have the property that if the argument is an integer, the result -is the same integer. An integer-valued floating-point argument is converted -to integer form. - -If you press @kbd{H} (@code{calc-hyperbolic}) first, the result will be -expressed as an integer-valued floating-point number. - -@cindex Integer part of a number -@kindex F -@pindex calc-floor -@tindex floor -@tindex ffloor -@ignore -@mindex @null -@end ignore -@kindex H F -The @kbd{F} (@code{calc-floor}) [@code{floor} or @code{ffloor}] command -truncates a real number to the next lower integer, i.e., toward minus -infinity. Thus @kbd{3.6 F} produces 3, but @kbd{_3.6 F} produces -@mathit{-4}. - -@kindex I F -@pindex calc-ceiling -@tindex ceil -@tindex fceil -@ignore -@mindex @null -@end ignore -@kindex H I F -The @kbd{I F} (@code{calc-ceiling}) [@code{ceil} or @code{fceil}] -command truncates toward positive infinity. Thus @kbd{3.6 I F} produces -4, and @kbd{_3.6 I F} produces @mathit{-3}. - -@kindex R -@pindex calc-round -@tindex round -@tindex fround -@ignore -@mindex @null -@end ignore -@kindex H R -The @kbd{R} (@code{calc-round}) [@code{round} or @code{fround}] command -rounds to the nearest integer. When the fractional part is .5 exactly, -this command rounds away from zero. (All other rounding in the -Calculator uses this convention as well.) Thus @kbd{3.5 R} produces 4 -but @kbd{3.4 R} produces 3; @kbd{_3.5 R} produces @mathit{-4}. - -@kindex I R -@pindex calc-trunc -@tindex trunc -@tindex ftrunc -@ignore -@mindex @null -@end ignore -@kindex H I R -The @kbd{I R} (@code{calc-trunc}) [@code{trunc} or @code{ftrunc}] -command truncates toward zero. In other words, it ``chops off'' -everything after the decimal point. Thus @kbd{3.6 I R} produces 3 and -@kbd{_3.6 I R} produces @mathit{-3}. - -These functions may not be applied meaningfully to error forms, but they -do work for intervals. As a convenience, applying @code{floor} to a -modulo form floors the value part of the form. Applied to a vector, -these functions operate on all elements of the vector one by one. -Applied to a date form, they operate on the internal numerical -representation of dates, converting a date/time form into a pure date. - -@ignore -@starindex -@end ignore -@tindex rounde -@ignore -@starindex -@end ignore -@tindex roundu -@ignore -@starindex -@end ignore -@tindex frounde -@ignore -@starindex -@end ignore -@tindex froundu -There are two more rounding functions which can only be entered in -algebraic notation. The @code{roundu} function is like @code{round} -except that it rounds up, toward plus infinity, when the fractional -part is .5. This distinction matters only for negative arguments. -Also, @code{rounde} rounds to an even number in the case of a tie, -rounding up or down as necessary. For example, @samp{rounde(3.5)} and -@samp{rounde(4.5)} both return 4, but @samp{rounde(5.5)} returns 6. -The advantage of round-to-even is that the net error due to rounding -after a long calculation tends to cancel out to zero. An important -subtle point here is that the number being fed to @code{rounde} will -already have been rounded to the current precision before @code{rounde} -begins. For example, @samp{rounde(2.500001)} with a current precision -of 6 will incorrectly, or at least surprisingly, yield 2 because the -argument will first have been rounded down to @expr{2.5} (which -@code{rounde} sees as an exact tie between 2 and 3). - -Each of these functions, when written in algebraic formulas, allows -a second argument which specifies the number of digits after the -decimal point to keep. For example, @samp{round(123.4567, 2)} will -produce the answer 123.46, and @samp{round(123.4567, -1)} will -produce 120 (i.e., the cutoff is one digit to the @emph{left} of -the decimal point). A second argument of zero is equivalent to -no second argument at all. - -@cindex Fractional part of a number -To compute the fractional part of a number (i.e., the amount which, when -added to `@tfn{floor(}@var{n}@tfn{)}', will produce @var{n}) just take @var{n} -modulo 1 using the @code{%} command. - -Note also the @kbd{\} (integer quotient), @kbd{f I} (integer logarithm), -and @kbd{f Q} (integer square root) commands, which are analogous to -@kbd{/}, @kbd{B}, and @kbd{Q}, respectively, except that they take integer -arguments and return the result rounded down to an integer. - -@node Complex Number Functions, Conversions, Integer Truncation, Arithmetic -@section Complex Number Functions - -@noindent -@kindex J -@pindex calc-conj -@tindex conj -The @kbd{J} (@code{calc-conj}) [@code{conj}] command computes the -complex conjugate of a number. For complex number @expr{a+bi}, the -complex conjugate is @expr{a-bi}. If the argument is a real number, -this command leaves it the same. If the argument is a vector or matrix, -this command replaces each element by its complex conjugate. - -@kindex G -@pindex calc-argument -@tindex arg -The @kbd{G} (@code{calc-argument}) [@code{arg}] command computes the -``argument'' or polar angle of a complex number. For a number in polar -notation, this is simply the second component of the pair -@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}'. -@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}'. -The result is expressed according to the current angular mode and will -be in the range @mathit{-180} degrees (exclusive) to @mathit{+180} degrees -(inclusive), or the equivalent range in radians. - -@pindex calc-imaginary -The @code{calc-imaginary} command multiplies the number on the -top of the stack by the imaginary number @expr{i = (0,1)}. This -command is not normally bound to a key in Calc, but it is available -on the @key{IMAG} button in Keypad mode. - -@kindex f r -@pindex calc-re -@tindex re -The @kbd{f r} (@code{calc-re}) [@code{re}] command replaces a complex number -by its real part. This command has no effect on real numbers. (As an -added convenience, @code{re} applied to a modulo form extracts -the value part.) - -@kindex f i -@pindex calc-im -@tindex im -The @kbd{f i} (@code{calc-im}) [@code{im}] command replaces a complex number -by its imaginary part; real numbers are converted to zero. With a vector -or matrix argument, these functions operate element-wise. - -@ignore -@mindex v p -@end ignore -@kindex v p (complex) -@kindex V p (complex) -@pindex calc-pack -The @kbd{v p} (@code{calc-pack}) command can pack the top two numbers on -the stack into a composite object such as a complex number. With -a prefix argument of @mathit{-1}, it produces a rectangular complex number; -with an argument of @mathit{-2}, it produces a polar complex number. -(Also, @pxref{Building Vectors}.) - -@ignore -@mindex v u -@end ignore -@kindex v u (complex) -@kindex V u (complex) -@pindex calc-unpack -The @kbd{v u} (@code{calc-unpack}) command takes the complex number -(or other composite object) on the top of the stack and unpacks it -into its separate components. - -@node Conversions, Date Arithmetic, Complex Number Functions, Arithmetic -@section Conversions - -@noindent -The commands described in this section convert numbers from one form -to another; they are two-key sequences beginning with the letter @kbd{c}. - -@kindex c f -@pindex calc-float -@tindex pfloat -The @kbd{c f} (@code{calc-float}) [@code{pfloat}] command converts the -number on the top of the stack to floating-point form. For example, -@expr{23} is converted to @expr{23.0}, @expr{3:2} is converted to -@expr{1.5}, and @expr{2.3} is left the same. If the value is a composite -object such as a complex number or vector, each of the components is -converted to floating-point. If the value is a formula, all numbers -in the formula are converted to floating-point. Note that depending -on the current floating-point precision, conversion to floating-point -format may lose information. - -As a special exception, integers which appear as powers or subscripts -are not floated by @kbd{c f}. If you really want to float a power, -you can use a @kbd{j s} command to select the power followed by @kbd{c f}. -Because @kbd{c f} cannot examine the formula outside of the selection, -it does not notice that the thing being floated is a power. -@xref{Selecting Subformulas}. - -The normal @kbd{c f} command is ``pervasive'' in the sense that it -applies to all numbers throughout the formula. The @code{pfloat} -algebraic function never stays around in a formula; @samp{pfloat(a + 1)} -changes to @samp{a + 1.0} as soon as it is evaluated. - -@kindex H c f -@tindex float -With the Hyperbolic flag, @kbd{H c f} [@code{float}] operates -only on the number or vector of numbers at the top level of its -argument. Thus, @samp{float(1)} is 1.0, but @samp{float(a + 1)} -is left unevaluated because its argument is not a number. - -You should use @kbd{H c f} if you wish to guarantee that the final -value, once all the variables have been assigned, is a float; you -would use @kbd{c f} if you wish to do the conversion on the numbers -that appear right now. - -@kindex c F -@pindex calc-fraction -@tindex pfrac -The @kbd{c F} (@code{calc-fraction}) [@code{pfrac}] command converts a -floating-point number into a fractional approximation. By default, it -produces a fraction whose decimal representation is the same as the -input number, to within the current precision. You can also give a -numeric prefix argument to specify a tolerance, either directly, or, -if the prefix argument is zero, by using the number on top of the stack -as the tolerance. If the tolerance is a positive integer, the fraction -is correct to within that many significant figures. If the tolerance is -a non-positive integer, it specifies how many digits fewer than the current -precision to use. If the tolerance is a floating-point number, the -fraction is correct to within that absolute amount. - -@kindex H c F -@tindex frac -The @code{pfrac} function is pervasive, like @code{pfloat}. -There is also a non-pervasive version, @kbd{H c F} [@code{frac}], -which is analogous to @kbd{H c f} discussed above. - -@kindex c d -@pindex calc-to-degrees -@tindex deg -The @kbd{c d} (@code{calc-to-degrees}) [@code{deg}] command converts a -number into degrees form. The value on the top of the stack may be an -HMS form (interpreted as degrees-minutes-seconds), or a real number which -will be interpreted in radians regardless of the current angular mode. - -@kindex c r -@pindex calc-to-radians -@tindex rad -The @kbd{c r} (@code{calc-to-radians}) [@code{rad}] command converts an -HMS form or angle in degrees into an angle in radians. - -@kindex c h -@pindex calc-to-hms -@tindex hms -The @kbd{c h} (@code{calc-to-hms}) [@code{hms}] command converts a real -number, interpreted according to the current angular mode, to an HMS -form describing the same angle. In algebraic notation, the @code{hms} -function also accepts three arguments: @samp{hms(@var{h}, @var{m}, @var{s})}. -(The three-argument version is independent of the current angular mode.) - -@pindex calc-from-hms -The @code{calc-from-hms} command converts the HMS form on the top of the -stack into a real number according to the current angular mode. - -@kindex c p -@kindex I c p -@pindex calc-polar -@tindex polar -@tindex rect -The @kbd{c p} (@code{calc-polar}) command converts the complex number on -the top of the stack from polar to rectangular form, or from rectangular -to polar form, whichever is appropriate. Real numbers are left the same. -This command is equivalent to the @code{rect} or @code{polar} -functions in algebraic formulas, depending on the direction of -conversion. (It uses @code{polar}, except that if the argument is -already a polar complex number, it uses @code{rect} instead. The -@kbd{I c p} command always uses @code{rect}.) - -@kindex c c -@pindex calc-clean -@tindex pclean -The @kbd{c c} (@code{calc-clean}) [@code{pclean}] command ``cleans'' the -number on the top of the stack. Floating point numbers are re-rounded -according to the current precision. Polar numbers whose angular -components have strayed from the @mathit{-180} to @mathit{+180} degree range -are normalized. (Note that results will be undesirable if the current -angular mode is different from the one under which the number was -produced!) Integers and fractions are generally unaffected by this -operation. Vectors and formulas are cleaned by cleaning each component -number (i.e., pervasively). - -If the simplification mode is set below the default level, it is raised -to the default level for the purposes of this command. Thus, @kbd{c c} -applies the default simplifications even if their automatic application -is disabled. @xref{Simplification Modes}. - -@cindex Roundoff errors, correcting -A numeric prefix argument to @kbd{c c} sets the floating-point precision -to that value for the duration of the command. A positive prefix (of at -least 3) sets the precision to the specified value; a negative or zero -prefix decreases the precision by the specified amount. - -@kindex c 0-9 -@pindex calc-clean-num -The keystroke sequences @kbd{c 0} through @kbd{c 9} are equivalent -to @kbd{c c} with the corresponding negative prefix argument. If roundoff -errors have changed 2.0 into 1.999999, typing @kbd{c 1} to clip off one -decimal place often conveniently does the trick. - -The @kbd{c c} command with a numeric prefix argument, and the @kbd{c 0} -through @kbd{c 9} commands, also ``clip'' very small floating-point -numbers to zero. If the exponent is less than or equal to the negative -of the specified precision, the number is changed to 0.0. For example, -if the current precision is 12, then @kbd{c 2} changes the vector -@samp{[1e-8, 1e-9, 1e-10, 1e-11]} to @samp{[1e-8, 1e-9, 0, 0]}. -Numbers this small generally arise from roundoff noise. - -If the numbers you are using really are legitimately this small, -you should avoid using the @kbd{c 0} through @kbd{c 9} commands. -(The plain @kbd{c c} command rounds to the current precision but -does not clip small numbers.) - -One more property of @kbd{c 0} through @kbd{c 9}, and of @kbd{c c} with -a prefix argument, is that integer-valued floats are converted to -plain integers, so that @kbd{c 1} on @samp{[1., 1.5, 2., 2.5, 3.]} -produces @samp{[1, 1.5, 2, 2.5, 3]}. This is not done for huge -numbers (@samp{1e100} is technically an integer-valued float, but -you wouldn't want it automatically converted to a 100-digit integer). - -@kindex H c 0-9 -@kindex H c c -@tindex clean -With the Hyperbolic flag, @kbd{H c c} and @kbd{H c 0} through @kbd{H c 9} -operate non-pervasively [@code{clean}]. - -@node Date Arithmetic, Financial Functions, Conversions, Arithmetic -@section Date Arithmetic - -@noindent -@cindex Date arithmetic, additional functions -The commands described in this section perform various conversions -and calculations involving date forms (@pxref{Date Forms}). They -use the @kbd{t} (for time/date) prefix key followed by shifted -letters. - -The simplest date arithmetic is done using the regular @kbd{+} and @kbd{-} -commands. In particular, adding a number to a date form advances the -date form by a certain number of days; adding an HMS form to a date -form advances the date by a certain amount of time; and subtracting two -date forms produces a difference measured in days. The commands -described here provide additional, more specialized operations on dates. - -Many of these commands accept a numeric prefix argument; if you give -plain @kbd{C-u} as the prefix, these commands will instead take the -additional argument from the top of the stack. - -@menu -* Date Conversions:: -* Date Functions:: -* Time Zones:: -* Business Days:: -@end menu - -@node Date Conversions, Date Functions, Date Arithmetic, Date Arithmetic -@subsection Date Conversions - -@noindent -@kindex t D -@pindex calc-date -@tindex date -The @kbd{t D} (@code{calc-date}) [@code{date}] command converts a -date form into a number, measured in days since Jan 1, 1 AD. The -result will be an integer if @var{date} is a pure date form, or a -fraction or float if @var{date} is a date/time form. Or, if its -argument is a number, it converts this number into a date form. - -With a numeric prefix argument, @kbd{t D} takes that many objects -(up to six) from the top of the stack and interprets them in one -of the following ways: - -The @samp{date(@var{year}, @var{month}, @var{day})} function -builds a pure date form out of the specified year, month, and -day, which must all be integers. @var{Year} is a year number, -such as 1991 (@emph{not} the same as 91!). @var{Month} must be -an integer in the range 1 to 12; @var{day} must be in the range -1 to 31. If the specified month has fewer than 31 days and -@var{day} is too large, the equivalent day in the following -month will be used. - -The @samp{date(@var{month}, @var{day})} function builds a -pure date form using the current year, as determined by the -real-time clock. - -The @samp{date(@var{year}, @var{month}, @var{day}, @var{hms})} -function builds a date/time form using an @var{hms} form. - -The @samp{date(@var{year}, @var{month}, @var{day}, @var{hour}, -@var{minute}, @var{second})} function builds a date/time form. -@var{hour} should be an integer in the range 0 to 23; -@var{minute} should be an integer in the range 0 to 59; -@var{second} should be any real number in the range @samp{[0 .. 60)}. -The last two arguments default to zero if omitted. - -@kindex t J -@pindex calc-julian -@tindex julian -@cindex Julian day counts, conversions -The @kbd{t J} (@code{calc-julian}) [@code{julian}] command converts -a date form into a Julian day count, which is the number of days -since noon (GMT) on Jan 1, 4713 BC. A pure date is converted to an -integer Julian count representing noon of that day. A date/time form -is converted to an exact floating-point Julian count, adjusted to -interpret the date form in the current time zone but the Julian -day count in Greenwich Mean Time. A numeric prefix argument allows -you to specify the time zone; @pxref{Time Zones}. Use a prefix of -zero to suppress the time zone adjustment. Note that pure date forms -are never time-zone adjusted. - -This command can also do the opposite conversion, from a Julian day -count (either an integer day, or a floating-point day and time in -the GMT zone), into a pure date form or a date/time form in the -current or specified time zone. - -@kindex t U -@pindex calc-unix-time -@tindex unixtime -@cindex Unix time format, conversions -The @kbd{t U} (@code{calc-unix-time}) [@code{unixtime}] command -converts a date form into a Unix time value, which is the number of -seconds since midnight on Jan 1, 1970, or vice-versa. The numeric result -will be an integer if the current precision is 12 or less; for higher -precision, the result may be a float with (@var{precision}@minus{}12) -digits after the decimal. Just as for @kbd{t J}, the numeric time -is interpreted in the GMT time zone and the date form is interpreted -in the current or specified zone. Some systems use Unix-like -numbering but with the local time zone; give a prefix of zero to -suppress the adjustment if so. - -@kindex t C -@pindex calc-convert-time-zones -@tindex tzconv -@cindex Time Zones, converting between -The @kbd{t C} (@code{calc-convert-time-zones}) [@code{tzconv}] -command converts a date form from one time zone to another. You -are prompted for each time zone name in turn; you can answer with -any suitable Calc time zone expression (@pxref{Time Zones}). -If you answer either prompt with a blank line, the local time -zone is used for that prompt. You can also answer the first -prompt with @kbd{$} to take the two time zone names from the -stack (and the date to be converted from the third stack level). - -@node Date Functions, Business Days, Date Conversions, Date Arithmetic -@subsection Date Functions - -@noindent -@kindex t N -@pindex calc-now -@tindex now -The @kbd{t N} (@code{calc-now}) [@code{now}] command pushes the -current date and time on the stack as a date form. The time is -reported in terms of the specified time zone; with no numeric prefix -argument, @kbd{t N} reports for the current time zone. - -@kindex t P -@pindex calc-date-part -The @kbd{t P} (@code{calc-date-part}) command extracts one part -of a date form. The prefix argument specifies the part; with no -argument, this command prompts for a part code from 1 to 9. -The various part codes are described in the following paragraphs. - -@tindex year -The @kbd{M-1 t P} [@code{year}] function extracts the year number -from a date form as an integer, e.g., 1991. This and the -following functions will also accept a real number for an -argument, which is interpreted as a standard Calc day number. -Note that this function will never return zero, since the year -1 BC immediately precedes the year 1 AD. - -@tindex month -The @kbd{M-2 t P} [@code{month}] function extracts the month number -from a date form as an integer in the range 1 to 12. - -@tindex day -The @kbd{M-3 t P} [@code{day}] function extracts the day number -from a date form as an integer in the range 1 to 31. - -@tindex hour -The @kbd{M-4 t P} [@code{hour}] function extracts the hour from -a date form as an integer in the range 0 (midnight) to 23. Note -that 24-hour time is always used. This returns zero for a pure -date form. This function (and the following two) also accept -HMS forms as input. - -@tindex minute -The @kbd{M-5 t P} [@code{minute}] function extracts the minute -from a date form as an integer in the range 0 to 59. - -@tindex second -The @kbd{M-6 t P} [@code{second}] function extracts the second -from a date form. If the current precision is 12 or less, -the result is an integer in the range 0 to 59. For higher -precision, the result may instead be a floating-point number. - -@tindex weekday -The @kbd{M-7 t P} [@code{weekday}] function extracts the weekday -number from a date form as an integer in the range 0 (Sunday) -to 6 (Saturday). - -@tindex yearday -The @kbd{M-8 t P} [@code{yearday}] function extracts the day-of-year -number from a date form as an integer in the range 1 (January 1) -to 366 (December 31 of a leap year). - -@tindex time -The @kbd{M-9 t P} [@code{time}] function extracts the time portion -of a date form as an HMS form. This returns @samp{0@@ 0' 0"} -for a pure date form. - -@kindex t M -@pindex calc-new-month -@tindex newmonth -The @kbd{t M} (@code{calc-new-month}) [@code{newmonth}] command -computes a new date form that represents the first day of the month -specified by the input date. The result is always a pure date -form; only the year and month numbers of the input are retained. -With a numeric prefix argument @var{n} in the range from 1 to 31, -@kbd{t M} computes the @var{n}th day of the month. (If @var{n} -is greater than the actual number of days in the month, or if -@var{n} is zero, the last day of the month is used.) - -@kindex t Y -@pindex calc-new-year -@tindex newyear -The @kbd{t Y} (@code{calc-new-year}) [@code{newyear}] command -computes a new pure date form that represents the first day of -the year specified by the input. The month, day, and time -of the input date form are lost. With a numeric prefix argument -@var{n} in the range from 1 to 366, @kbd{t Y} computes the -@var{n}th day of the year (366 is treated as 365 in non-leap -years). A prefix argument of 0 computes the last day of the -year (December 31). A negative prefix argument from @mathit{-1} to -@mathit{-12} computes the first day of the @var{n}th month of the year. - -@kindex t W -@pindex calc-new-week -@tindex newweek -The @kbd{t W} (@code{calc-new-week}) [@code{newweek}] command -computes a new pure date form that represents the Sunday on or before -the input date. With a numeric prefix argument, it can be made to -use any day of the week as the starting day; the argument must be in -the range from 0 (Sunday) to 6 (Saturday). This function always -subtracts between 0 and 6 days from the input date. - -Here's an example use of @code{newweek}: Find the date of the next -Wednesday after a given date. Using @kbd{M-3 t W} or @samp{newweek(d, 3)} -will give you the @emph{preceding} Wednesday, so @samp{newweek(d+7, 3)} -will give you the following Wednesday. A further look at the definition -of @code{newweek} shows that if the input date is itself a Wednesday, -this formula will return the Wednesday one week in the future. An -exercise for the reader is to modify this formula to yield the same day -if the input is already a Wednesday. Another interesting exercise is -to preserve the time-of-day portion of the input (@code{newweek} resets -the time to midnight; hint:@: how can @code{newweek} be defined in terms -of the @code{weekday} function?). - -@ignore -@starindex -@end ignore -@tindex pwday -The @samp{pwday(@var{date})} function (not on any key) computes the -day-of-month number of the Sunday on or before @var{date}. With -two arguments, @samp{pwday(@var{date}, @var{day})} computes the day -number of the Sunday on or before day number @var{day} of the month -specified by @var{date}. The @var{day} must be in the range from -7 to 31; if the day number is greater than the actual number of days -in the month, the true number of days is used instead. Thus -@samp{pwday(@var{date}, 7)} finds the first Sunday of the month, and -@samp{pwday(@var{date}, 31)} finds the last Sunday of the month. -With a third @var{weekday} argument, @code{pwday} can be made to look -for any day of the week instead of Sunday. - -@kindex t I -@pindex calc-inc-month -@tindex incmonth -The @kbd{t I} (@code{calc-inc-month}) [@code{incmonth}] command -increases a date form by one month, or by an arbitrary number of -months specified by a numeric prefix argument. The time portion, -if any, of the date form stays the same. The day also stays the -same, except that if the new month has fewer days the day -number may be reduced to lie in the valid range. For example, -@samp{incmonth()} produces @samp{}. -Because of this, @kbd{t I t I} and @kbd{M-2 t I} do not always give -the same results (@samp{} versus @samp{} -in this case). - -@ignore -@starindex -@end ignore -@tindex incyear -The @samp{incyear(@var{date}, @var{step})} function increases -a date form by the specified number of years, which may be -any positive or negative integer. Note that @samp{incyear(d, n)} -is equivalent to @w{@samp{incmonth(d, 12*n)}}, but these do not have -simple equivalents in terms of day arithmetic because -months and years have varying lengths. If the @var{step} -argument is omitted, 1 year is assumed. There is no keyboard -command for this function; use @kbd{C-u 12 t I} instead. - -There is no @code{newday} function at all because @kbd{F} [@code{floor}] -serves this purpose. Similarly, instead of @code{incday} and -@code{incweek} simply use @expr{d + n} or @expr{d + 7 n}. - -@xref{Basic Arithmetic}, for the @kbd{f ]} [@code{incr}] command -which can adjust a date/time form by a certain number of seconds. - -@node Business Days, Time Zones, Date Functions, Date Arithmetic -@subsection Business Days - -@noindent -Often time is measured in ``business days'' or ``working days,'' -where weekends and holidays are skipped. Calc's normal date -arithmetic functions use calendar days, so that subtracting two -consecutive Mondays will yield a difference of 7 days. By contrast, -subtracting two consecutive Mondays would yield 5 business days -(assuming two-day weekends and the absence of holidays). - -@kindex t + -@kindex t - -@tindex badd -@tindex bsub -@pindex calc-business-days-plus -@pindex calc-business-days-minus -The @kbd{t +} (@code{calc-business-days-plus}) [@code{badd}] -and @kbd{t -} (@code{calc-business-days-minus}) [@code{bsub}] -commands perform arithmetic using business days. For @kbd{t +}, -one argument must be a date form and the other must be a real -number (positive or negative). If the number is not an integer, -then a certain amount of time is added as well as a number of -days; for example, adding 0.5 business days to a time in Friday -evening will produce a time in Monday morning. It is also -possible to add an HMS form; adding @samp{12@@ 0' 0"} also adds -half a business day. For @kbd{t -}, the arguments are either a -date form and a number or HMS form, or two date forms, in which -case the result is the number of business days between the two -dates. - -@cindex @code{Holidays} variable -@vindex Holidays -By default, Calc considers any day that is not a Saturday or -Sunday to be a business day. You can define any number of -additional holidays by editing the variable @code{Holidays}. -(There is an @w{@kbd{s H}} convenience command for editing this -variable.) Initially, @code{Holidays} contains the vector -@samp{[sat, sun]}. Entries in the @code{Holidays} vector may -be any of the following kinds of objects: - -@itemize @bullet -@item -Date forms (pure dates, not date/time forms). These specify -particular days which are to be treated as holidays. - -@item -Intervals of date forms. These specify a range of days, all of -which are holidays (e.g., Christmas week). @xref{Interval Forms}. - -@item -Nested vectors of date forms. Each date form in the vector is -considered to be a holiday. - -@item -Any Calc formula which evaluates to one of the above three things. -If the formula involves the variable @expr{y}, it stands for a -yearly repeating holiday; @expr{y} will take on various year -numbers like 1992. For example, @samp{date(y, 12, 25)} specifies -Christmas day, and @samp{newweek(date(y, 11, 7), 4) + 21} specifies -Thanksgiving (which is held on the fourth Thursday of November). -If the formula involves the variable @expr{m}, that variable -takes on month numbers from 1 to 12: @samp{date(y, m, 15)} is -a holiday that takes place on the 15th of every month. - -@item -A weekday name, such as @code{sat} or @code{sun}. This is really -a variable whose name is a three-letter, lower-case day name. - -@item -An interval of year numbers (integers). This specifies the span of -years over which this holiday list is to be considered valid. Any -business-day arithmetic that goes outside this range will result -in an error message. Use this if you are including an explicit -list of holidays, rather than a formula to generate them, and you -want to make sure you don't accidentally go beyond the last point -where the holidays you entered are complete. If there is no -limiting interval in the @code{Holidays} vector, the default -@samp{[1 .. 2737]} is used. (This is the absolute range of years -for which Calc's business-day algorithms will operate.) - -@item -An interval of HMS forms. This specifies the span of hours that -are to be considered one business day. For example, if this -range is @samp{[9@@ 0' 0" .. 17@@ 0' 0"]} (i.e., 9am to 5pm), then -the business day is only eight hours long, so that @kbd{1.5 t +} -on @samp{<4:00pm Fri Dec 13, 1991>} will add one business day and -four business hours to produce @samp{<12:00pm Tue Dec 17, 1991>}. -Likewise, @kbd{t -} will now express differences in time as -fractions of an eight-hour day. Times before 9am will be treated -as 9am by business date arithmetic, and times at or after 5pm will -be treated as 4:59:59pm. If there is no HMS interval in @code{Holidays}, -the full 24-hour day @samp{[0@ 0' 0" .. 24@ 0' 0"]} is assumed. -(Regardless of the type of bounds you specify, the interval is -treated as inclusive on the low end and exclusive on the high end, -so that the work day goes from 9am up to, but not including, 5pm.) -@end itemize - -If the @code{Holidays} vector is empty, then @kbd{t +} and -@kbd{t -} will act just like @kbd{+} and @kbd{-} because there will -then be no difference between business days and calendar days. - -Calc expands the intervals and formulas you give into a complete -list of holidays for internal use. This is done mainly to make -sure it can detect multiple holidays. (For example, -@samp{} is both New Year's Day and a Sunday, but -Calc's algorithms take care to count it only once when figuring -the number of holidays between two dates.) - -Since the complete list of holidays for all the years from 1 to -2737 would be huge, Calc actually computes only the part of the -list between the smallest and largest years that have been involved -in business-day calculations so far. Normally, you won't have to -worry about this. Keep in mind, however, that if you do one -calculation for 1992, and another for 1792, even if both involve -only a small range of years, Calc will still work out all the -holidays that fall in that 200-year span. - -If you add a (positive) number of days to a date form that falls on a -weekend or holiday, the date form is treated as if it were the most -recent business day. (Thus adding one business day to a Friday, -Saturday, or Sunday will all yield the following Monday.) If you -subtract a number of days from a weekend or holiday, the date is -effectively on the following business day. (So subtracting one business -day from Saturday, Sunday, or Monday yields the preceding Friday.) The -difference between two dates one or both of which fall on holidays -equals the number of actual business days between them. These -conventions are consistent in the sense that, if you add @var{n} -business days to any date, the difference between the result and the -original date will come out to @var{n} business days. (It can't be -completely consistent though; a subtraction followed by an addition -might come out a bit differently, since @kbd{t +} is incapable of -producing a date that falls on a weekend or holiday.) - -@ignore -@starindex -@end ignore -@tindex holiday -There is a @code{holiday} function, not on any keys, that takes -any date form and returns 1 if that date falls on a weekend or -holiday, as defined in @code{Holidays}, or 0 if the date is a -business day. - -@node Time Zones, , Business Days, Date Arithmetic -@subsection Time Zones - -@noindent -@cindex Time zones -@cindex Daylight saving time -Time zones and daylight saving time are a complicated business. -The conversions to and from Julian and Unix-style dates automatically -compute the correct time zone and daylight saving adjustment to use, -provided they can figure out this information. This section describes -Calc's time zone adjustment algorithm in detail, in case you want to -do conversions in different time zones or in case Calc's algorithms -can't determine the right correction to use. - -Adjustments for time zones and daylight saving time are done by -@kbd{t U}, @kbd{t J}, @kbd{t N}, and @kbd{t C}, but not by any other -commands. In particular, @samp{ - } evaluates -to exactly 30 days even though there is a daylight-saving -transition in between. This is also true for Julian pure dates: -@samp{julian() - julian()}. But Julian -and Unix date/times will adjust for daylight saving time: using Calc's -default daylight saving time rule (see the explanation below), -@samp{julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)} -evaluates to @samp{29.95833} (that's 29 days and 23 hours) -because one hour was lost when daylight saving commenced on -April 7, 1991. - -In brief, the idiom @samp{julian(@var{date1}) - julian(@var{date2})} -computes the actual number of 24-hour periods between two dates, whereas -@samp{@var{date1} - @var{date2}} computes the number of calendar -days between two dates without taking daylight saving into account. - -@pindex calc-time-zone -@ignore -@starindex -@end ignore -@tindex tzone -The @code{calc-time-zone} [@code{tzone}] command converts the time -zone specified by its numeric prefix argument into a number of -seconds difference from Greenwich mean time (GMT). If the argument -is a number, the result is simply that value multiplied by 3600. -Typical arguments for North America are 5 (Eastern) or 8 (Pacific). If -Daylight Saving time is in effect, one hour should be subtracted from -the normal difference. - -If you give a prefix of plain @kbd{C-u}, @code{calc-time-zone} (like other -date arithmetic commands that include a time zone argument) takes the -zone argument from the top of the stack. (In the case of @kbd{t J} -and @kbd{t U}, the normal argument is then taken from the second-to-top -stack position.) This allows you to give a non-integer time zone -adjustment. The time-zone argument can also be an HMS form, or -it can be a variable which is a time zone name in upper- or lower-case. -For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)} -(for Pacific standard and daylight saving times, respectively). - -North American and European time zone names are defined as follows; -note that for each time zone there is one name for standard time, -another for daylight saving time, and a third for ``generalized'' time -in which the daylight saving adjustment is computed from context. - -@smallexample -@group -YST PST MST CST EST AST NST GMT WET MET MEZ - 9 8 7 6 5 4 3.5 0 -1 -2 -2 - -YDT PDT MDT CDT EDT ADT NDT BST WETDST METDST MESZ - 8 7 6 5 4 3 2.5 -1 -2 -3 -3 - -YGT PGT MGT CGT EGT AGT NGT BGT WEGT MEGT MEGZ -9/8 8/7 7/6 6/5 5/4 4/3 3.5/2.5 0/-1 -1/-2 -2/-3 -2/-3 -@end group -@end smallexample - -@vindex math-tzone-names -To define time zone names that do not appear in the above table, -you must modify the Lisp variable @code{math-tzone-names}. This -is a list of lists describing the different time zone names; its -structure is best explained by an example. The three entries for -Pacific Time look like this: - -@smallexample -@group -( ( "PST" 8 0 ) ; Name as an upper-case string, then standard - ( "PDT" 8 -1 ) ; adjustment, then daylight saving adjustment. - ( "PGT" 8 "PST" "PDT" ) ) ; Generalized time zone. -@end group -@end smallexample - -@cindex @code{TimeZone} variable -@vindex TimeZone -With no arguments, @code{calc-time-zone} or @samp{tzone()} will by -default get the time zone and daylight saving information from the -calendar (@pxref{Daylight Saving,Calendar/Diary,The Calendar and the Diary, -emacs,The GNU Emacs Manual}). To use a different time zone, or if the -calendar does not give the desired result, you can set the Calc variable -@code{TimeZone} (which is by default @code{nil}) to an appropriate -time zone name. (The easiest way to do this is to edit the -@code{TimeZone} variable using Calc's @kbd{s T} command, then use the -@kbd{s p} (@code{calc-permanent-variable}) command to save the value of -@code{TimeZone} permanently.) -If the time zone given by @code{TimeZone} is a generalized time zone, -e.g., @code{EGT}, Calc examines the date being converted to tell whether -to use standard or daylight saving time. But if the current time zone -is explicit, e.g., @code{EST} or @code{EDT}, then that adjustment is -used exactly and Calc's daylight saving algorithm is not consulted. -The special time zone name @code{local} -is equivalent to no argument; i.e., it uses the information obtained -from the calendar. - -The @kbd{t J} and @code{t U} commands with no numeric prefix -arguments do the same thing as @samp{tzone()}; namely, use the -information from the calendar if @code{TimeZone} is @code{nil}, -otherwise use the time zone given by @code{TimeZone}. - -@vindex math-daylight-savings-hook -@findex math-std-daylight-savings -When Calc computes the daylight saving information itself (i.e., when -the @code{TimeZone} variable is set), it will by default consider -daylight saving time to begin at 2 a.m.@: on the second Sunday of March -(for years from 2007 on) or on the last Sunday in April (for years -before 2007), and to end at 2 a.m.@: on the first Sunday of -November. (for years from 2007 on) or the last Sunday in October (for -years before 2007). These are the rules that have been in effect in -much of North America since 1966 and take into account the rule change -that began in 2007. If you are in a country that uses different rules -for computing daylight saving time, you have two choices: Write your own -daylight saving hook, or control time zones explicitly by setting the -@code{TimeZone} variable and/or always giving a time-zone argument for -the conversion functions. - -The Lisp variable @code{math-daylight-savings-hook} holds the -name of a function that is used to compute the daylight saving -adjustment for a given date. The default is -@code{math-std-daylight-savings}, which computes an adjustment -(either 0 or @mathit{-1}) using the North American rules given above. - -The daylight saving hook function is called with four arguments: -The date, as a floating-point number in standard Calc format; -a six-element list of the date decomposed into year, month, day, -hour, minute, and second, respectively; a string which contains -the generalized time zone name in upper-case, e.g., @code{"WEGT"}; -and a special adjustment to be applied to the hour value when -converting into a generalized time zone (see below). - -@findex math-prev-weekday-in-month -The Lisp function @code{math-prev-weekday-in-month} is useful for -daylight saving computations. This is an internal version of -the user-level @code{pwday} function described in the previous -section. It takes four arguments: The floating-point date value, -the corresponding six-element date list, the day-of-month number, -and the weekday number (0-6). - -The default daylight saving hook ignores the time zone name, but a -more sophisticated hook could use different algorithms for different -time zones. It would also be possible to use different algorithms -depending on the year number, but the default hook always uses the -algorithm for 1987 and later. Here is a listing of the default -daylight saving hook: - -@smallexample -(defun math-std-daylight-savings (date dt zone bump) - (cond ((< (nth 1 dt) 4) 0) - ((= (nth 1 dt) 4) - (let ((sunday (math-prev-weekday-in-month date dt 7 0))) - (cond ((< (nth 2 dt) sunday) 0) - ((= (nth 2 dt) sunday) - (if (>= (nth 3 dt) (+ 3 bump)) -1 0)) - (t -1)))) - ((< (nth 1 dt) 10) -1) - ((= (nth 1 dt) 10) - (let ((sunday (math-prev-weekday-in-month date dt 31 0))) - (cond ((< (nth 2 dt) sunday) -1) - ((= (nth 2 dt) sunday) - (if (>= (nth 3 dt) (+ 2 bump)) 0 -1)) - (t 0)))) - (t 0)) -) -@end smallexample - -@noindent -The @code{bump} parameter is equal to zero when Calc is converting -from a date form in a generalized time zone into a GMT date value. -It is @mathit{-1} when Calc is converting in the other direction. The -adjustments shown above ensure that the conversion behaves correctly -and reasonably around the 2 a.m.@: transition in each direction. - -There is a ``missing'' hour between 2 a.m.@: and 3 a.m.@: at the -beginning of daylight saving time; converting a date/time form that -falls in this hour results in a time value for the following hour, -from 3 a.m.@: to 4 a.m. At the end of daylight saving time, the -hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time -form that falls in this hour results in a time value for the first -manifestation of that time (@emph{not} the one that occurs one hour -later). - -If @code{math-daylight-savings-hook} is @code{nil}, then the -daylight saving adjustment is always taken to be zero. - -In algebraic formulas, @samp{tzone(@var{zone}, @var{date})} -computes the time zone adjustment for a given zone name at a -given date. The @var{date} is ignored unless @var{zone} is a -generalized time zone. If @var{date} is a date form, the -daylight saving computation is applied to it as it appears. -If @var{date} is a numeric date value, it is adjusted for the -daylight-saving version of @var{zone} before being given to -the daylight saving hook. This odd-sounding rule ensures -that the daylight-saving computation is always done in -local time, not in the GMT time that a numeric @var{date} -is typically represented in. - -@ignore -@starindex -@end ignore -@tindex dsadj -The @samp{dsadj(@var{date}, @var{zone})} function computes the -daylight saving adjustment that is appropriate for @var{date} in -time zone @var{zone}. If @var{zone} is explicitly in or not in -daylight saving time (e.g., @code{PDT} or @code{PST}) the -@var{date} is ignored. If @var{zone} is a generalized time zone, -the algorithms described above are used. If @var{zone} is omitted, -the computation is done for the current time zone. - -@node Financial Functions, Binary Functions, Date Arithmetic, Arithmetic -@section Financial Functions - -@noindent -Calc's financial or business functions use the @kbd{b} prefix -key followed by a shifted letter. (The @kbd{b} prefix followed by -a lower-case letter is used for operations on binary numbers.) - -Note that the rate and the number of intervals given to these -functions must be on the same time scale, e.g., both months or -both years. Mixing an annual interest rate with a time expressed -in months will give you very wrong answers! - -It is wise to compute these functions to a higher precision than -you really need, just to make sure your answer is correct to the -last penny; also, you may wish to check the definitions at the end -of this section to make sure the functions have the meaning you expect. - -@menu -* Percentages:: -* Future Value:: -* Present Value:: -* Related Financial Functions:: -* Depreciation Functions:: -* Definitions of Financial Functions:: -@end menu - -@node Percentages, Future Value, Financial Functions, Financial Functions -@subsection Percentages - -@kindex M-% -@pindex calc-percent -@tindex % -@tindex percent -The @kbd{M-%} (@code{calc-percent}) command takes a percentage value, -say 5.4, and converts it to an equivalent actual number. For example, -@kbd{5.4 M-%} enters 0.054 on the stack. (That's the @key{META} or -@key{ESC} key combined with @kbd{%}.) - -Actually, @kbd{M-%} creates a formula of the form @samp{5.4%}. -You can enter @samp{5.4%} yourself during algebraic entry. The -@samp{%} operator simply means, ``the preceding value divided by -100.'' The @samp{%} operator has very high precedence, so that -@samp{1+8%} is interpreted as @samp{1+(8%)}, not as @samp{(1+8)%}. -(The @samp{%} operator is just a postfix notation for the -@code{percent} function, just like @samp{20!} is the notation for -@samp{fact(20)}, or twenty-factorial.) - -The formula @samp{5.4%} would normally evaluate immediately to -0.054, but the @kbd{M-%} command suppresses evaluation as it puts -the formula onto the stack. However, the next Calc command that -uses the formula @samp{5.4%} will evaluate it as its first step. -The net effect is that you get to look at @samp{5.4%} on the stack, -but Calc commands see it as @samp{0.054}, which is what they expect. - -In particular, @samp{5.4%} and @samp{0.054} are suitable values -for the @var{rate} arguments of the various financial functions, -but the number @samp{5.4} is probably @emph{not} suitable---it -represents a rate of 540 percent! - -The key sequence @kbd{M-% *} effectively means ``percent-of.'' -For example, @kbd{68 @key{RET} 25 M-% *} computes 17, which is 25% of -68 (and also 68% of 25, which comes out to the same thing). - -@kindex c % -@pindex calc-convert-percent -The @kbd{c %} (@code{calc-convert-percent}) command converts the -value on the top of the stack from numeric to percentage form. -For example, if 0.08 is on the stack, @kbd{c %} converts it to -@samp{8%}. The quantity is the same, it's just represented -differently. (Contrast this with @kbd{M-%}, which would convert -this number to @samp{0.08%}.) The @kbd{=} key is a convenient way -to convert a formula like @samp{8%} back to numeric form, 0.08. - -To compute what percentage one quantity is of another quantity, -use @kbd{/ c %}. For example, @w{@kbd{17 @key{RET} 68 / c %}} displays -@samp{25%}. - -@kindex b % -@pindex calc-percent-change -@tindex relch -The @kbd{b %} (@code{calc-percent-change}) [@code{relch}] command -calculates the percentage change from one number to another. -For example, @kbd{40 @key{RET} 50 b %} produces the answer @samp{25%}, -since 50 is 25% larger than 40. A negative result represents a -decrease: @kbd{50 @key{RET} 40 b %} produces @samp{-20%}, since 40 is -20% smaller than 50. (The answers are different in magnitude -because, in the first case, we're increasing by 25% of 40, but -in the second case, we're decreasing by 20% of 50.) The effect -of @kbd{40 @key{RET} 50 b %} is to compute @expr{(50-40)/40}, converting -the answer to percentage form as if by @kbd{c %}. - -@node Future Value, Present Value, Percentages, Financial Functions -@subsection Future Value - -@noindent -@kindex b F -@pindex calc-fin-fv -@tindex fv -The @kbd{b F} (@code{calc-fin-fv}) [@code{fv}] command computes -the future value of an investment. It takes three arguments -from the stack: @samp{fv(@var{rate}, @var{n}, @var{payment})}. -If you give payments of @var{payment} every year for @var{n} -years, and the money you have paid earns interest at @var{rate} per -year, then this function tells you what your investment would be -worth at the end of the period. (The actual interval doesn't -have to be years, as long as @var{n} and @var{rate} are expressed -in terms of the same intervals.) This function assumes payments -occur at the @emph{end} of each interval. - -@kindex I b F -@tindex fvb -The @kbd{I b F} [@code{fvb}] command does the same computation, -but assuming your payments are at the beginning of each interval. -Suppose you plan to deposit $1000 per year in a savings account -earning 5.4% interest, starting right now. How much will be -in the account after five years? @code{fvb(5.4%, 5, 1000) = 5870.73}. -Thus you will have earned $870 worth of interest over the years. -Using the stack, this calculation would have been -@kbd{5.4 M-% 5 @key{RET} 1000 I b F}. Note that the rate is expressed -as a number between 0 and 1, @emph{not} as a percentage. - -@kindex H b F -@tindex fvl -The @kbd{H b F} [@code{fvl}] command computes the future value -of an initial lump sum investment. Suppose you could deposit -those five thousand dollars in the bank right now; how much would -they be worth in five years? @code{fvl(5.4%, 5, 5000) = 6503.89}. - -The algebraic functions @code{fv} and @code{fvb} accept an optional -fourth argument, which is used as an initial lump sum in the sense -of @code{fvl}. In other words, @code{fv(@var{rate}, @var{n}, -@var{payment}, @var{initial}) = fv(@var{rate}, @var{n}, @var{payment}) -+ fvl(@var{rate}, @var{n}, @var{initial})}. - -To illustrate the relationships between these functions, we could -do the @code{fvb} calculation ``by hand'' using @code{fvl}. The -final balance will be the sum of the contributions of our five -deposits at various times. The first deposit earns interest for -five years: @code{fvl(5.4%, 5, 1000) = 1300.78}. The second -deposit only earns interest for four years: @code{fvl(5.4%, 4, 1000) = -1234.13}. And so on down to the last deposit, which earns one -year's interest: @code{fvl(5.4%, 1, 1000) = 1054.00}. The sum of -these five values is, sure enough, $5870.73, just as was computed -by @code{fvb} directly. - -What does @code{fv(5.4%, 5, 1000) = 5569.96} mean? The payments -are now at the ends of the periods. The end of one year is the same -as the beginning of the next, so what this really means is that we've -lost the payment at year zero (which contributed $1300.78), but we're -now counting the payment at year five (which, since it didn't have -a chance to earn interest, counts as $1000). Indeed, @expr{5569.96 = -5870.73 - 1300.78 + 1000} (give or take a bit of roundoff error). - -@node Present Value, Related Financial Functions, Future Value, Financial Functions -@subsection Present Value - -@noindent -@kindex b P -@pindex calc-fin-pv -@tindex pv -The @kbd{b P} (@code{calc-fin-pv}) [@code{pv}] command computes -the present value of an investment. Like @code{fv}, it takes -three arguments: @code{pv(@var{rate}, @var{n}, @var{payment})}. -It computes the present value of a series of regular payments. -Suppose you have the chance to make an investment that will -pay $2000 per year over the next four years; as you receive -these payments you can put them in the bank at 9% interest. -You want to know whether it is better to make the investment, or -to keep the money in the bank where it earns 9% interest right -from the start. The calculation @code{pv(9%, 4, 2000)} gives the -result 6479.44. If your initial investment must be less than this, -say, $6000, then the investment is worthwhile. But if you had to -put up $7000, then it would be better just to leave it in the bank. - -Here is the interpretation of the result of @code{pv}: You are -trying to compare the return from the investment you are -considering, which is @code{fv(9%, 4, 2000) = 9146.26}, with -the return from leaving the money in the bank, which is -@code{fvl(9%, 4, @var{x})} where @var{x} is the amount of money -you would have to put up in advance. The @code{pv} function -finds the break-even point, @expr{x = 6479.44}, at which -@code{fvl(9%, 4, 6479.44)} is also equal to 9146.26. This is -the largest amount you should be willing to invest. - -@kindex I b P -@tindex pvb -The @kbd{I b P} [@code{pvb}] command solves the same problem, -but with payments occurring at the beginning of each interval. -It has the same relationship to @code{fvb} as @code{pv} has -to @code{fv}. For example @code{pvb(9%, 4, 2000) = 7062.59}, -a larger number than @code{pv} produced because we get to start -earning interest on the return from our investment sooner. - -@kindex H b P -@tindex pvl -The @kbd{H b P} [@code{pvl}] command computes the present value of -an investment that will pay off in one lump sum at the end of the -period. For example, if we get our $8000 all at the end of the -four years, @code{pvl(9%, 4, 8000) = 5667.40}. This is much -less than @code{pv} reported, because we don't earn any interest -on the return from this investment. Note that @code{pvl} and -@code{fvl} are simple inverses: @code{fvl(9%, 4, 5667.40) = 8000}. - -You can give an optional fourth lump-sum argument to @code{pv} -and @code{pvb}; this is handled in exactly the same way as the -fourth argument for @code{fv} and @code{fvb}. - -@kindex b N -@pindex calc-fin-npv -@tindex npv -The @kbd{b N} (@code{calc-fin-npv}) [@code{npv}] command computes -the net present value of a series of irregular investments. -The first argument is the interest rate. The second argument is -a vector which represents the expected return from the investment -at the end of each interval. For example, if the rate represents -a yearly interest rate, then the vector elements are the return -from the first year, second year, and so on. - -Thus, @code{npv(9%, [2000,2000,2000,2000]) = pv(9%, 4, 2000) = 6479.44}. -Obviously this function is more interesting when the payments are -not all the same! - -The @code{npv} function can actually have two or more arguments. -Multiple arguments are interpreted in the same way as for the -vector statistical functions like @code{vsum}. -@xref{Single-Variable Statistics}. Basically, if there are several -payment arguments, each either a vector or a plain number, all these -values are collected left-to-right into the complete list of payments. -A numeric prefix argument on the @kbd{b N} command says how many -payment values or vectors to take from the stack. - -@kindex I b N -@tindex npvb -The @kbd{I b N} [@code{npvb}] command computes the net present -value where payments occur at the beginning of each interval -rather than at the end. - -@node Related Financial Functions, Depreciation Functions, Present Value, Financial Functions -@subsection Related Financial Functions - -@noindent -The functions in this section are basically inverses of the -present value functions with respect to the various arguments. - -@kindex b M -@pindex calc-fin-pmt -@tindex pmt -The @kbd{b M} (@code{calc-fin-pmt}) [@code{pmt}] command computes -the amount of periodic payment necessary to amortize a loan. -Thus @code{pmt(@var{rate}, @var{n}, @var{amount})} equals the -value of @var{payment} such that @code{pv(@var{rate}, @var{n}, -@var{payment}) = @var{amount}}. - -@kindex I b M -@tindex pmtb -The @kbd{I b M} [@code{pmtb}] command does the same computation -but using @code{pvb} instead of @code{pv}. Like @code{pv} and -@code{pvb}, these functions can also take a fourth argument which -represents an initial lump-sum investment. - -@kindex H b M -The @kbd{H b M} key just invokes the @code{fvl} function, which is -the inverse of @code{pvl}. There is no explicit @code{pmtl} function. - -@kindex b # -@pindex calc-fin-nper -@tindex nper -The @kbd{b #} (@code{calc-fin-nper}) [@code{nper}] command computes -the number of regular payments necessary to amortize a loan. -Thus @code{nper(@var{rate}, @var{payment}, @var{amount})} equals -the value of @var{n} such that @code{pv(@var{rate}, @var{n}, -@var{payment}) = @var{amount}}. If @var{payment} is too small -ever to amortize a loan for @var{amount} at interest rate @var{rate}, -the @code{nper} function is left in symbolic form. - -@kindex I b # -@tindex nperb -The @kbd{I b #} [@code{nperb}] command does the same computation -but using @code{pvb} instead of @code{pv}. You can give a fourth -lump-sum argument to these functions, but the computation will be -rather slow in the four-argument case. - -@kindex H b # -@tindex nperl -The @kbd{H b #} [@code{nperl}] command does the same computation -using @code{pvl}. By exchanging @var{payment} and @var{amount} you -can also get the solution for @code{fvl}. For example, -@code{nperl(8%, 2000, 1000) = 9.006}, so if you place $1000 in a -bank account earning 8%, it will take nine years to grow to $2000. - -@kindex b T -@pindex calc-fin-rate -@tindex rate -The @kbd{b T} (@code{calc-fin-rate}) [@code{rate}] command computes -the rate of return on an investment. This is also an inverse of @code{pv}: -@code{rate(@var{n}, @var{payment}, @var{amount})} computes the value of -@var{rate} such that @code{pv(@var{rate}, @var{n}, @var{payment}) = -@var{amount}}. The result is expressed as a formula like @samp{6.3%}. - -@kindex I b T -@kindex H b T -@tindex rateb -@tindex ratel -The @kbd{I b T} [@code{rateb}] and @kbd{H b T} [@code{ratel}] -commands solve the analogous equations with @code{pvb} or @code{pvl} -in place of @code{pv}. Also, @code{rate} and @code{rateb} can -accept an optional fourth argument just like @code{pv} and @code{pvb}. -To redo the above example from a different perspective, -@code{ratel(9, 2000, 1000) = 8.00597%}, which says you will need an -interest rate of 8% in order to double your account in nine years. - -@kindex b I -@pindex calc-fin-irr -@tindex irr -The @kbd{b I} (@code{calc-fin-irr}) [@code{irr}] command is the -analogous function to @code{rate} but for net present value. -Its argument is a vector of payments. Thus @code{irr(@var{payments})} -computes the @var{rate} such that @code{npv(@var{rate}, @var{payments}) = 0}; -this rate is known as the @dfn{internal rate of return}. - -@kindex I b I -@tindex irrb -The @kbd{I b I} [@code{irrb}] command computes the internal rate of -return assuming payments occur at the beginning of each period. - -@node Depreciation Functions, Definitions of Financial Functions, Related Financial Functions, Financial Functions -@subsection Depreciation Functions - -@noindent -The functions in this section calculate @dfn{depreciation}, which is -the amount of value that a possession loses over time. These functions -are characterized by three parameters: @var{cost}, the original cost -of the asset; @var{salvage}, the value the asset will have at the end -of its expected ``useful life''; and @var{life}, the number of years -(or other periods) of the expected useful life. - -There are several methods for calculating depreciation that differ in -the way they spread the depreciation over the lifetime of the asset. - -@kindex b S -@pindex calc-fin-sln -@tindex sln -The @kbd{b S} (@code{calc-fin-sln}) [@code{sln}] command computes the -``straight-line'' depreciation. In this method, the asset depreciates -by the same amount every year (or period). For example, -@samp{sln(12000, 2000, 5)} returns 2000. The asset costs $12000 -initially and will be worth $2000 after five years; it loses $2000 -per year. - -@kindex b Y -@pindex calc-fin-syd -@tindex syd -The @kbd{b Y} (@code{calc-fin-syd}) [@code{syd}] command computes the -accelerated ``sum-of-years'-digits'' depreciation. Here the depreciation -is higher during the early years of the asset's life. Since the -depreciation is different each year, @kbd{b Y} takes a fourth @var{period} -parameter which specifies which year is requested, from 1 to @var{life}. -If @var{period} is outside this range, the @code{syd} function will -return zero. - -@kindex b D -@pindex calc-fin-ddb -@tindex ddb -The @kbd{b D} (@code{calc-fin-ddb}) [@code{ddb}] command computes an -accelerated depreciation using the double-declining balance method. -It also takes a fourth @var{period} parameter. - -For symmetry, the @code{sln} function will accept a @var{period} -parameter as well, although it will ignore its value except that the -return value will as usual be zero if @var{period} is out of range. - -For example, pushing the vector @expr{[1,2,3,4,5]} (perhaps with @kbd{v x 5}) -and then mapping @kbd{V M ' [sln(12000,2000,5,$), syd(12000,2000,5,$), -ddb(12000,2000,5,$)] @key{RET}} produces a matrix that allows us to compare -the three depreciation methods: - -@example -@group -[ [ 2000, 3333, 4800 ] - [ 2000, 2667, 2880 ] - [ 2000, 2000, 1728 ] - [ 2000, 1333, 592 ] - [ 2000, 667, 0 ] ] -@end group -@end example - -@noindent -(Values have been rounded to nearest integers in this figure.) -We see that @code{sln} depreciates by the same amount each year, -@kbd{syd} depreciates more at the beginning and less at the end, -and @kbd{ddb} weights the depreciation even more toward the beginning. - -Summing columns with @kbd{V R : +} yields @expr{[10000, 10000, 10000]}; -the total depreciation in any method is (by definition) the -difference between the cost and the salvage value. - -@node Definitions of Financial Functions, , Depreciation Functions, Financial Functions -@subsection Definitions - -@noindent -For your reference, here are the actual formulas used to compute -Calc's financial functions. - -Calc will not evaluate a financial function unless the @var{rate} or -@var{n} argument is known. However, @var{payment} or @var{amount} can -be a variable. Calc expands these functions according to the -formulas below for symbolic arguments only when you use the @kbd{a "} -(@code{calc-expand-formula}) command, or when taking derivatives or -integrals or solving equations involving the functions. - -@ifnottex -These formulas are shown using the conventions of Big display -mode (@kbd{d B}); for example, the formula for @code{fv} written -linearly is @samp{pmt * ((1 + rate)^n) - 1) / rate}. - -@example - n - (1 + rate) - 1 -fv(rate, n, pmt) = pmt * --------------- - rate - - n - ((1 + rate) - 1) (1 + rate) -fvb(rate, n, pmt) = pmt * ---------------------------- - rate - - n -fvl(rate, n, pmt) = pmt * (1 + rate) - - -n - 1 - (1 + rate) -pv(rate, n, pmt) = pmt * ---------------- - rate - - -n - (1 - (1 + rate) ) (1 + rate) -pvb(rate, n, pmt) = pmt * ----------------------------- - rate - - -n -pvl(rate, n, pmt) = pmt * (1 + rate) - - -1 -2 -3 -npv(rate, [a, b, c]) = a*(1 + rate) + b*(1 + rate) + c*(1 + rate) - - -1 -2 -npvb(rate, [a, b, c]) = a + b*(1 + rate) + c*(1 + rate) - - -n - (amt - x * (1 + rate) ) * rate -pmt(rate, n, amt, x) = ------------------------------- - -n - 1 - (1 + rate) - - -n - (amt - x * (1 + rate) ) * rate -pmtb(rate, n, amt, x) = ------------------------------- - -n - (1 - (1 + rate) ) (1 + rate) - - amt * rate -nper(rate, pmt, amt) = - log(1 - ------------, 1 + rate) - pmt - - amt * rate -nperb(rate, pmt, amt) = - log(1 - ---------------, 1 + rate) - pmt * (1 + rate) - - amt -nperl(rate, pmt, amt) = - log(---, 1 + rate) - pmt - - 1/n - pmt -ratel(n, pmt, amt) = ------ - 1 - 1/n - amt - - cost - salv -sln(cost, salv, life) = ----------- - life - - (cost - salv) * (life - per + 1) -syd(cost, salv, life, per) = -------------------------------- - life * (life + 1) / 2 - - book * 2 -ddb(cost, salv, life, per) = --------, book = cost - depreciation so far - life -@end example -@end ifnottex -@tex -$$ \code{fv}(r, n, p) = p { (1 + r)^n - 1 \over r } $$ -$$ \code{fvb}(r, n, p) = p { ((1 + r)^n - 1) (1 + r) \over r } $$ -$$ \code{fvl}(r, n, p) = p (1 + r)^n $$ -$$ \code{pv}(r, n, p) = p { 1 - (1 + r)^{-n} \over r } $$ -$$ \code{pvb}(r, n, p) = p { (1 - (1 + r)^{-n}) (1 + r) \over r } $$ -$$ \code{pvl}(r, n, p) = p (1 + r)^{-n} $$ -$$ \code{npv}(r, [a,b,c]) = a (1 + r)^{-1} + b (1 + r)^{-2} + c (1 + r)^{-3} $$ -$$ \code{npvb}(r, [a,b,c]) = a + b (1 + r)^{-1} + c (1 + r)^{-2} $$ -$$ \code{pmt}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over 1 - (1 + r)^{-n} }$$ -$$ \code{pmtb}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over - (1 - (1 + r)^{-n}) (1 + r) } $$ -$$ \code{nper}(r, p, a) = -\code{log}(1 - { a r \over p }, 1 + r) $$ -$$ \code{nperb}(r, p, a) = -\code{log}(1 - { a r \over p (1 + r) }, 1 + r) $$ -$$ \code{nperl}(r, p, a) = -\code{log}({a \over p}, 1 + r) $$ -$$ \code{ratel}(n, p, a) = { p^{1/n} \over a^{1/n} } - 1 $$ -$$ \code{sln}(c, s, l) = { c - s \over l } $$ -$$ \code{syd}(c, s, l, p) = { (c - s) (l - p + 1) \over l (l+1) / 2 } $$ -$$ \code{ddb}(c, s, l, p) = { 2 (c - \hbox{depreciation so far}) \over l } $$ -@end tex - -@noindent -In @code{pmt} and @code{pmtb}, @expr{x=0} if omitted. - -These functions accept any numeric objects, including error forms, -intervals, and even (though not very usefully) complex numbers. The -above formulas specify exactly the behavior of these functions with -all sorts of inputs. - -Note that if the first argument to the @code{log} in @code{nper} is -negative, @code{nper} leaves itself in symbolic form rather than -returning a (financially meaningless) complex number. - -@samp{rate(num, pmt, amt)} solves the equation -@samp{pv(rate, num, pmt) = amt} for @samp{rate} using @kbd{H a R} -(@code{calc-find-root}), with the interval @samp{[.01% .. 100%]} -for an initial guess. The @code{rateb} function is the same except -that it uses @code{pvb}. Note that @code{ratel} can be solved -directly; its formula is shown in the above list. - -Similarly, @samp{irr(pmts)} solves the equation @samp{npv(rate, pmts) = 0} -for @samp{rate}. - -If you give a fourth argument to @code{nper} or @code{nperb}, Calc -will also use @kbd{H a R} to solve the equation using an initial -guess interval of @samp{[0 .. 100]}. - -A fourth argument to @code{fv} simply sums the two components -calculated from the above formulas for @code{fv} and @code{fvl}. -The same is true of @code{fvb}, @code{pv}, and @code{pvb}. - -The @kbd{ddb} function is computed iteratively; the ``book'' value -starts out equal to @var{cost}, and decreases according to the above -formula for the specified number of periods. If the book value -would decrease below @var{salvage}, it only decreases to @var{salvage} -and the depreciation is zero for all subsequent periods. The @code{ddb} -function returns the amount the book value decreased in the specified -period. - -@node Binary Functions, , Financial Functions, Arithmetic -@section Binary Number Functions - -@noindent -The commands in this chapter all use two-letter sequences beginning with -the @kbd{b} prefix. - -@cindex Binary numbers -The ``binary'' operations actually work regardless of the currently -displayed radix, although their results make the most sense in a radix -like 2, 8, or 16 (as obtained by the @kbd{d 2}, @kbd{d 8}, or @w{@kbd{d 6}} -commands, respectively). You may also wish to enable display of leading -zeros with @kbd{d z}. @xref{Radix Modes}. - -@cindex Word size for binary operations -The Calculator maintains a current @dfn{word size} @expr{w}, an -arbitrary positive or negative integer. For a positive word size, all -of the binary operations described here operate modulo @expr{2^w}. In -particular, negative arguments are converted to positive integers modulo -@expr{2^w} by all binary functions. - -If the word size is negative, binary operations produce twos-complement -integers from -@texline @math{-2^{-w-1}} -@infoline @expr{-(2^(-w-1))} -to -@texline @math{2^{-w-1}-1} -@infoline @expr{2^(-w-1)-1} -inclusive. Either mode accepts inputs in any range; the sign of -@expr{w} affects only the results produced. - -@kindex b c -@pindex calc-clip -@tindex clip -The @kbd{b c} (@code{calc-clip}) -[@code{clip}] command can be used to clip a number by reducing it modulo -@expr{2^w}. The commands described in this chapter automatically clip -their results to the current word size. Note that other operations like -addition do not use the current word size, since integer addition -generally is not ``binary.'' (However, @pxref{Simplification Modes}, -@code{calc-bin-simplify-mode}.) For example, with a word size of 8 -bits @kbd{b c} converts a number to the range 0 to 255; with a word -size of @mathit{-8} @kbd{b c} converts to the range @mathit{-128} to 127. - -@kindex b w -@pindex calc-word-size -The default word size is 32 bits. All operations except the shifts and -rotates allow you to specify a different word size for that one -operation by giving a numeric prefix argument: @kbd{C-u 8 b c} clips the -top of stack to the range 0 to 255 regardless of the current word size. -To set the word size permanently, use @kbd{b w} (@code{calc-word-size}). -This command displays a prompt with the current word size; press @key{RET} -immediately to keep this word size, or type a new word size at the prompt. - -When the binary operations are written in symbolic form, they take an -optional second (or third) word-size parameter. When a formula like -@samp{and(a,b)} is finally evaluated, the word size current at that time -will be used, but when @samp{and(a,b,-8)} is evaluated, a word size of -@mathit{-8} will always be used. A symbolic binary function will be left -in symbolic form unless the all of its argument(s) are integers or -integer-valued floats. - -If either or both arguments are modulo forms for which @expr{M} is a -power of two, that power of two is taken as the word size unless a -numeric prefix argument overrides it. The current word size is never -consulted when modulo-power-of-two forms are involved. - -@kindex b a -@pindex calc-and -@tindex and -The @kbd{b a} (@code{calc-and}) [@code{and}] command computes the bitwise -AND of the two numbers on the top of the stack. In other words, for each -of the @expr{w} binary digits of the two numbers (pairwise), the corresponding -bit of the result is 1 if and only if both input bits are 1: -@samp{and(2#1100, 2#1010) = 2#1000}. - -@kindex b o -@pindex calc-or -@tindex or -The @kbd{b o} (@code{calc-or}) [@code{or}] command computes the bitwise -inclusive OR of two numbers. A bit is 1 if either of the input bits, or -both, are 1: @samp{or(2#1100, 2#1010) = 2#1110}. - -@kindex b x -@pindex calc-xor -@tindex xor -The @kbd{b x} (@code{calc-xor}) [@code{xor}] command computes the bitwise -exclusive OR of two numbers. A bit is 1 if exactly one of the input bits -is 1: @samp{xor(2#1100, 2#1010) = 2#0110}. - -@kindex b d -@pindex calc-diff -@tindex diff -The @kbd{b d} (@code{calc-diff}) [@code{diff}] command computes the bitwise -difference of two numbers; this is defined by @samp{diff(a,b) = and(a,not(b))}, -so that @samp{diff(2#1100, 2#1010) = 2#0100}. - -@kindex b n -@pindex calc-not -@tindex not -The @kbd{b n} (@code{calc-not}) [@code{not}] command computes the bitwise -NOT of a number. A bit is 1 if the input bit is 0 and vice-versa. - -@kindex b l -@pindex calc-lshift-binary -@tindex lsh -The @kbd{b l} (@code{calc-lshift-binary}) [@code{lsh}] command shifts a -number left by one bit, or by the number of bits specified in the numeric -prefix argument. A negative prefix argument performs a logical right shift, -in which zeros are shifted in on the left. In symbolic form, @samp{lsh(a)} -is short for @samp{lsh(a,1)}, which in turn is short for @samp{lsh(a,n,w)}. -Bits shifted ``off the end,'' according to the current word size, are lost. - -@kindex H b l -@kindex H b r -@ignore -@mindex @idots -@end ignore -@kindex H b L -@ignore -@mindex @null -@end ignore -@kindex H b R -@ignore -@mindex @null -@end ignore -@kindex H b t -The @kbd{H b l} command also does a left shift, but it takes two arguments -from the stack (the value to shift, and, at top-of-stack, the number of -bits to shift). This version interprets the prefix argument just like -the regular binary operations, i.e., as a word size. The Hyperbolic flag -has a similar effect on the rest of the binary shift and rotate commands. - -@kindex b r -@pindex calc-rshift-binary -@tindex rsh -The @kbd{b r} (@code{calc-rshift-binary}) [@code{rsh}] command shifts a -number right by one bit, or by the number of bits specified in the numeric -prefix argument: @samp{rsh(a,n) = lsh(a,-n)}. - -@kindex b L -@pindex calc-lshift-arith -@tindex ash -The @kbd{b L} (@code{calc-lshift-arith}) [@code{ash}] command shifts a -number left. It is analogous to @code{lsh}, except that if the shift -is rightward (the prefix argument is negative), an arithmetic shift -is performed as described below. - -@kindex b R -@pindex calc-rshift-arith -@tindex rash -The @kbd{b R} (@code{calc-rshift-arith}) [@code{rash}] command performs -an ``arithmetic'' shift to the right, in which the leftmost bit (according -to the current word size) is duplicated rather than shifting in zeros. -This corresponds to dividing by a power of two where the input is interpreted -as a signed, twos-complement number. (The distinction between the @samp{rsh} -and @samp{rash} operations is totally independent from whether the word -size is positive or negative.) With a negative prefix argument, this -performs a standard left shift. - -@kindex b t -@pindex calc-rotate-binary -@tindex rot -The @kbd{b t} (@code{calc-rotate-binary}) [@code{rot}] command rotates a -number one bit to the left. The leftmost bit (according to the current -word size) is dropped off the left and shifted in on the right. With a -numeric prefix argument, the number is rotated that many bits to the left -or right. - -@xref{Set Operations}, for the @kbd{b p} and @kbd{b u} commands that -pack and unpack binary integers into sets. (For example, @kbd{b u} -unpacks the number @samp{2#11001} to the set of bit-numbers -@samp{[0, 3, 4]}.) Type @kbd{b u V #} to count the number of ``1'' -bits in a binary integer. - -Another interesting use of the set representation of binary integers -is to reverse the bits in, say, a 32-bit integer. Type @kbd{b u} to -unpack; type @kbd{31 @key{TAB} -} to replace each bit-number in the set -with 31 minus that bit-number; type @kbd{b p} to pack the set back -into a binary integer. - -@node Scientific Functions, Matrix Functions, Arithmetic, Top -@chapter Scientific Functions - -@noindent -The functions described here perform trigonometric and other transcendental -calculations. They generally produce floating-point answers correct to the -full current precision. The @kbd{H} (Hyperbolic) and @kbd{I} (Inverse) -flag keys must be used to get some of these functions from the keyboard. - -@kindex P -@pindex calc-pi -@cindex @code{pi} variable -@vindex pi -@kindex H P -@cindex @code{e} variable -@vindex e -@kindex I P -@cindex @code{gamma} variable -@vindex gamma -@cindex Gamma constant, Euler's -@cindex Euler's gamma constant -@kindex H I P -@cindex @code{phi} variable -@cindex Phi, golden ratio -@cindex Golden ratio -One miscellaneous command is shift-@kbd{P} (@code{calc-pi}), which pushes -the value of @cpi{} (at the current precision) onto the stack. With the -Hyperbolic flag, it pushes the value @expr{e}, the base of natural logarithms. -With the Inverse flag, it pushes Euler's constant -@texline @math{\gamma} -@infoline @expr{gamma} -(about 0.5772). With both Inverse and Hyperbolic, it -pushes the ``golden ratio'' -@texline @math{\phi} -@infoline @expr{phi} -(about 1.618). (At present, Euler's constant is not available -to unlimited precision; Calc knows only the first 100 digits.) -In Symbolic mode, these commands push the -actual variables @samp{pi}, @samp{e}, @samp{gamma}, and @samp{phi}, -respectively, instead of their values; @pxref{Symbolic Mode}. - -@ignore -@mindex Q -@end ignore -@ignore -@mindex I Q -@end ignore -@kindex I Q -@tindex sqr -The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] function is described elsewhere; -@pxref{Basic Arithmetic}. With the Inverse flag [@code{sqr}], this command -computes the square of the argument. - -@xref{Prefix Arguments}, for a discussion of the effect of numeric -prefix arguments on commands in this chapter which do not otherwise -interpret a prefix argument. - -@menu -* Logarithmic Functions:: -* Trigonometric and Hyperbolic Functions:: -* Advanced Math Functions:: -* Branch Cuts:: -* Random Numbers:: -* Combinatorial Functions:: -* Probability Distribution Functions:: -@end menu - -@node Logarithmic Functions, Trigonometric and Hyperbolic Functions, Scientific Functions, Scientific Functions -@section Logarithmic Functions - -@noindent -@kindex L -@pindex calc-ln -@tindex ln -@ignore -@mindex @null -@end ignore -@kindex I E -The shift-@kbd{L} (@code{calc-ln}) [@code{ln}] command computes the natural -logarithm of the real or complex number on the top of the stack. With -the Inverse flag it computes the exponential function instead, although -this is redundant with the @kbd{E} command. - -@kindex E -@pindex calc-exp -@tindex exp -@ignore -@mindex @null -@end ignore -@kindex I L -The shift-@kbd{E} (@code{calc-exp}) [@code{exp}] command computes the -exponential, i.e., @expr{e} raised to the power of the number on the stack. -The meanings of the Inverse and Hyperbolic flags follow from those for -the @code{calc-ln} command. - -@kindex H L -@kindex H E -@pindex calc-log10 -@tindex log10 -@tindex exp10 -@ignore -@mindex @null -@end ignore -@kindex H I L -@ignore -@mindex @null -@end ignore -@kindex H I E -The @kbd{H L} (@code{calc-log10}) [@code{log10}] command computes the common -(base-10) logarithm of a number. (With the Inverse flag [@code{exp10}], -it raises ten to a given power.) Note that the common logarithm of a -complex number is computed by taking the natural logarithm and dividing -by -@texline @math{\ln10}. -@infoline @expr{ln(10)}. - -@kindex B -@kindex I B -@pindex calc-log -@tindex log -@tindex alog -The @kbd{B} (@code{calc-log}) [@code{log}] command computes a logarithm -to any base. For example, @kbd{1024 @key{RET} 2 B} produces 10, since -@texline @math{2^{10} = 1024}. -@infoline @expr{2^10 = 1024}. -In certain cases like @samp{log(3,9)}, the result -will be either @expr{1:2} or @expr{0.5} depending on the current Fraction -mode setting. With the Inverse flag [@code{alog}], this command is -similar to @kbd{^} except that the order of the arguments is reversed. - -@kindex f I -@pindex calc-ilog -@tindex ilog -The @kbd{f I} (@code{calc-ilog}) [@code{ilog}] command computes the -integer logarithm of a number to any base. The number and the base must -themselves be positive integers. This is the true logarithm, rounded -down to an integer. Thus @kbd{ilog(x,10)} is 3 for all @expr{x} in the -range from 1000 to 9999. If both arguments are positive integers, exact -integer arithmetic is used; otherwise, this is equivalent to -@samp{floor(log(x,b))}. - -@kindex f E -@pindex calc-expm1 -@tindex expm1 -The @kbd{f E} (@code{calc-expm1}) [@code{expm1}] command computes -@texline @math{e^x - 1}, -@infoline @expr{exp(x)-1}, -but using an algorithm that produces a more accurate -answer when the result is close to zero, i.e., when -@texline @math{e^x} -@infoline @expr{exp(x)} -is close to one. - -@kindex f L -@pindex calc-lnp1 -@tindex lnp1 -The @kbd{f L} (@code{calc-lnp1}) [@code{lnp1}] command computes -@texline @math{\ln(x+1)}, -@infoline @expr{ln(x+1)}, -producing a more accurate answer when @expr{x} is close to zero. - -@node Trigonometric and Hyperbolic Functions, Advanced Math Functions, Logarithmic Functions, Scientific Functions -@section Trigonometric/Hyperbolic Functions - -@noindent -@kindex S -@pindex calc-sin -@tindex sin -The shift-@kbd{S} (@code{calc-sin}) [@code{sin}] command computes the sine -of an angle or complex number. If the input is an HMS form, it is interpreted -as degrees-minutes-seconds; otherwise, the input is interpreted according -to the current angular mode. It is best to use Radians mode when operating -on complex numbers. - -Calc's ``units'' mechanism includes angular units like @code{deg}, -@code{rad}, and @code{grad}. While @samp{sin(45 deg)} is not evaluated -all the time, the @kbd{u s} (@code{calc-simplify-units}) command will -simplify @samp{sin(45 deg)} by taking the sine of 45 degrees, regardless -of the current angular mode. @xref{Basic Operations on Units}. - -Also, the symbolic variable @code{pi} is not ordinarily recognized in -arguments to trigonometric functions, as in @samp{sin(3 pi / 4)}, but -the @kbd{a s} (@code{calc-simplify}) command recognizes many such -formulas when the current angular mode is Radians @emph{and} Symbolic -mode is enabled; this example would be replaced by @samp{sqrt(2) / 2}. -@xref{Symbolic Mode}. Beware, this simplification occurs even if you -have stored a different value in the variable @samp{pi}; this is one -reason why changing built-in variables is a bad idea. Arguments of -the form @expr{x} plus a multiple of @cpiover{2} are also simplified. -Calc includes similar formulas for @code{cos} and @code{tan}. - -The @kbd{a s} command knows all angles which are integer multiples of -@cpiover{12}, @cpiover{10}, or @cpiover{8} radians. In Degrees mode, -analogous simplifications occur for integer multiples of 15 or 18 -degrees, and for arguments plus multiples of 90 degrees. - -@kindex I S -@pindex calc-arcsin -@tindex arcsin -With the Inverse flag, @code{calc-sin} computes an arcsine. This is also -available as the @code{calc-arcsin} command or @code{arcsin} algebraic -function. The returned argument is converted to degrees, radians, or HMS -notation depending on the current angular mode. - -@kindex H S -@pindex calc-sinh -@tindex sinh -@kindex H I S -@pindex calc-arcsinh -@tindex arcsinh -With the Hyperbolic flag, @code{calc-sin} computes the hyperbolic -sine, also available as @code{calc-sinh} [@code{sinh}]. With the -Hyperbolic and Inverse flags, it computes the hyperbolic arcsine -(@code{calc-arcsinh}) [@code{arcsinh}]. - -@kindex C -@pindex calc-cos -@tindex cos -@ignore -@mindex @idots -@end ignore -@kindex I C -@pindex calc-arccos -@ignore -@mindex @null -@end ignore -@tindex arccos -@ignore -@mindex @null -@end ignore -@kindex H C -@pindex calc-cosh -@ignore -@mindex @null -@end ignore -@tindex cosh -@ignore -@mindex @null -@end ignore -@kindex H I C -@pindex calc-arccosh -@ignore -@mindex @null -@end ignore -@tindex arccosh -@ignore -@mindex @null -@end ignore -@kindex T -@pindex calc-tan -@ignore -@mindex @null -@end ignore -@tindex tan -@ignore -@mindex @null -@end ignore -@kindex I T -@pindex calc-arctan -@ignore -@mindex @null -@end ignore -@tindex arctan -@ignore -@mindex @null -@end ignore -@kindex H T -@pindex calc-tanh -@ignore -@mindex @null -@end ignore -@tindex tanh -@ignore -@mindex @null -@end ignore -@kindex H I T -@pindex calc-arctanh -@ignore -@mindex @null -@end ignore -@tindex arctanh -The shift-@kbd{C} (@code{calc-cos}) [@code{cos}] command computes the cosine -of an angle or complex number, and shift-@kbd{T} (@code{calc-tan}) [@code{tan}] -computes the tangent, along with all the various inverse and hyperbolic -variants of these functions. - -@kindex f T -@pindex calc-arctan2 -@tindex arctan2 -The @kbd{f T} (@code{calc-arctan2}) [@code{arctan2}] command takes two -numbers from the stack and computes the arc tangent of their ratio. The -result is in the full range from @mathit{-180} (exclusive) to @mathit{+180} -(inclusive) degrees, or the analogous range in radians. A similar -result would be obtained with @kbd{/} followed by @kbd{I T}, but the -value would only be in the range from @mathit{-90} to @mathit{+90} degrees -since the division loses information about the signs of the two -components, and an error might result from an explicit division by zero -which @code{arctan2} would avoid. By (arbitrary) definition, -@samp{arctan2(0,0)=0}. - -@pindex calc-sincos -@ignore -@starindex -@end ignore -@tindex sincos -@ignore -@starindex -@end ignore -@ignore -@mindex arc@idots -@end ignore -@tindex arcsincos -The @code{calc-sincos} [@code{sincos}] command computes the sine and -cosine of a number, returning them as a vector of the form -@samp{[@var{cos}, @var{sin}]}. -With the Inverse flag [@code{arcsincos}], this command takes a two-element -vector as an argument and computes @code{arctan2} of the elements. -(This command does not accept the Hyperbolic flag.) - -@pindex calc-sec -@tindex sec -@pindex calc-csc -@tindex csc -@pindex calc-cot -@tindex cot -@pindex calc-sech -@tindex sech -@pindex calc-csch -@tindex csch -@pindex calc-coth -@tindex coth -The remaining trigonometric functions, @code{calc-sec} [@code{sec}], -@code{calc-csc} [@code{csc}] and @code{calc-cot} [@code{cot}], are also -available. With the Hyperbolic flag, these compute their hyperbolic -counterparts, which are also available separately as @code{calc-sech} -[@code{sech}], @code{calc-csch} [@code{csch}] and @code{calc-coth} -[@code{coth}]. (These commands do not accept the Inverse flag.) - -@node Advanced Math Functions, Branch Cuts, Trigonometric and Hyperbolic Functions, Scientific Functions -@section Advanced Mathematical Functions - -@noindent -Calc can compute a variety of less common functions that arise in -various branches of mathematics. All of the functions described in -this section allow arbitrary complex arguments and, except as noted, -will work to arbitrarily large precision. They can not at present -handle error forms or intervals as arguments. - -NOTE: These functions are still experimental. In particular, their -accuracy is not guaranteed in all domains. It is advisable to set the -current precision comfortably higher than you actually need when -using these functions. Also, these functions may be impractically -slow for some values of the arguments. - -@kindex f g -@pindex calc-gamma -@tindex gamma -The @kbd{f g} (@code{calc-gamma}) [@code{gamma}] command computes the Euler -gamma function. For positive integer arguments, this is related to the -factorial function: @samp{gamma(n+1) = fact(n)}. For general complex -arguments the gamma function can be defined by the following definite -integral: -@texline @math{\Gamma(a) = \int_0^\infty t^{a-1} e^t dt}. -@infoline @expr{gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)}. -(The actual implementation uses far more efficient computational methods.) - -@kindex f G -@tindex gammaP -@ignore -@mindex @idots -@end ignore -@kindex I f G -@ignore -@mindex @null -@end ignore -@kindex H f G -@ignore -@mindex @null -@end ignore -@kindex H I f G -@pindex calc-inc-gamma -@ignore -@mindex @null -@end ignore -@tindex gammaQ -@ignore -@mindex @null -@end ignore -@tindex gammag -@ignore -@mindex @null -@end ignore -@tindex gammaG -The @kbd{f G} (@code{calc-inc-gamma}) [@code{gammaP}] command computes -the incomplete gamma function, denoted @samp{P(a,x)}. This is defined by -the integral, -@texline @math{P(a,x) = \left( \int_0^x t^{a-1} e^t dt \right) / \Gamma(a)}. -@infoline @expr{gammaP(a,x) = integ(t^(a-1) exp(t), t, 0, x) / gamma(a)}. -This implies that @samp{gammaP(a,inf) = 1} for any @expr{a} (see the -definition of the normal gamma function). - -Several other varieties of incomplete gamma function are defined. -The complement of @expr{P(a,x)}, called @expr{Q(a,x) = 1-P(a,x)} by -some authors, is computed by the @kbd{I f G} [@code{gammaQ}] command. -You can think of this as taking the other half of the integral, from -@expr{x} to infinity. - -@ifnottex -The functions corresponding to the integrals that define @expr{P(a,x)} -and @expr{Q(a,x)} but without the normalizing @expr{1/gamma(a)} -factor are called @expr{g(a,x)} and @expr{G(a,x)}, respectively -(where @expr{g} and @expr{G} represent the lower- and upper-case Greek -letter gamma). You can obtain these using the @kbd{H f G} [@code{gammag}] -and @kbd{H I f G} [@code{gammaG}] commands. -@end ifnottex -@tex -The functions corresponding to the integrals that define $P(a,x)$ -and $Q(a,x)$ but without the normalizing $1/\Gamma(a)$ -factor are called $\gamma(a,x)$ and $\Gamma(a,x)$, respectively. -You can obtain these using the \kbd{H f G} [\code{gammag}] and -\kbd{I H f G} [\code{gammaG}] commands. -@end tex - -@kindex f b -@pindex calc-beta -@tindex beta -The @kbd{f b} (@code{calc-beta}) [@code{beta}] command computes the -Euler beta function, which is defined in terms of the gamma function as -@texline @math{B(a,b) = \Gamma(a) \Gamma(b) / \Gamma(a+b)}, -@infoline @expr{beta(a,b) = gamma(a) gamma(b) / gamma(a+b)}, -or by -@texline @math{B(a,b) = \int_0^1 t^{a-1} (1-t)^{b-1} dt}. -@infoline @expr{beta(a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, 1)}. - -@kindex f B -@kindex H f B -@pindex calc-inc-beta -@tindex betaI -@tindex betaB -The @kbd{f B} (@code{calc-inc-beta}) [@code{betaI}] command computes -the incomplete beta function @expr{I(x,a,b)}. It is defined by -@texline @math{I(x,a,b) = \left( \int_0^x t^{a-1} (1-t)^{b-1} dt \right) / B(a,b)}. -@infoline @expr{betaI(x,a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, x) / beta(a,b)}. -Once again, the @kbd{H} (hyperbolic) prefix gives the corresponding -un-normalized version [@code{betaB}]. - -@kindex f e -@kindex I f e -@pindex calc-erf -@tindex erf -@tindex erfc -The @kbd{f e} (@code{calc-erf}) [@code{erf}] command computes the -error function -@texline @math{\hbox{erf}(x) = {2 \over \sqrt{\pi}} \int_0^x e^{-t^2} dt}. -@infoline @expr{erf(x) = 2 integ(exp(-(t^2)), t, 0, x) / sqrt(pi)}. -The complementary error function @kbd{I f e} (@code{calc-erfc}) [@code{erfc}] -is the corresponding integral from @samp{x} to infinity; the sum -@texline @math{\hbox{erf}(x) + \hbox{erfc}(x) = 1}. -@infoline @expr{erf(x) + erfc(x) = 1}. - -@kindex f j -@kindex f y -@pindex calc-bessel-J -@pindex calc-bessel-Y -@tindex besJ -@tindex besY -The @kbd{f j} (@code{calc-bessel-J}) [@code{besJ}] and @kbd{f y} -(@code{calc-bessel-Y}) [@code{besY}] commands compute the Bessel -functions of the first and second kinds, respectively. -In @samp{besJ(n,x)} and @samp{besY(n,x)} the ``order'' parameter -@expr{n} is often an integer, but is not required to be one. -Calc's implementation of the Bessel functions currently limits the -precision to 8 digits, and may not be exact even to that precision. -Use with care! - -@node Branch Cuts, Random Numbers, Advanced Math Functions, Scientific Functions -@section Branch Cuts and Principal Values - -@noindent -@cindex Branch cuts -@cindex Principal values -All of the logarithmic, trigonometric, and other scientific functions are -defined for complex numbers as well as for reals. -This section describes the values -returned in cases where the general result is a family of possible values. -Calc follows section 12.5.3 of Steele's @dfn{Common Lisp, the Language}, -second edition, in these matters. This section will describe each -function briefly; for a more detailed discussion (including some nifty -diagrams), consult Steele's book. - -Note that the branch cuts for @code{arctan} and @code{arctanh} were -changed between the first and second editions of Steele. Recent -versions of Calc follow the second edition. - -The new branch cuts exactly match those of the HP-28/48 calculators. -They also match those of Mathematica 1.2, except that Mathematica's -@code{arctan} cut is always in the right half of the complex plane, -and its @code{arctanh} cut is always in the top half of the plane. -Calc's cuts are continuous with quadrants I and III for @code{arctan}, -or II and IV for @code{arctanh}. - -Note: The current implementations of these functions with complex arguments -are designed with proper behavior around the branch cuts in mind, @emph{not} -efficiency or accuracy. You may need to increase the floating precision -and wait a while to get suitable answers from them. - -For @samp{sqrt(a+bi)}: When @expr{a<0} and @expr{b} is small but positive -or zero, the result is close to the @expr{+i} axis. For @expr{b} small and -negative, the result is close to the @expr{-i} axis. The result always lies -in the right half of the complex plane. - -For @samp{ln(a+bi)}: The real part is defined as @samp{ln(abs(a+bi))}. -The imaginary part is defined as @samp{arg(a+bi) = arctan2(b,a)}. -Thus the branch cuts for @code{sqrt} and @code{ln} both lie on the -negative real axis. - -The following table describes these branch cuts in another way. -If the real and imaginary parts of @expr{z} are as shown, then -the real and imaginary parts of @expr{f(z)} will be as shown. -Here @code{eps} stands for a small positive value; each -occurrence of @code{eps} may stand for a different small value. - -@smallexample - z sqrt(z) ln(z) ----------------------------------------- - +, 0 +, 0 any, 0 - -, 0 0, + any, pi - -, +eps +eps, + +eps, + - -, -eps +eps, - +eps, - -@end smallexample - -For @samp{z1^z2}: This is defined by @samp{exp(ln(z1)*z2)}. -One interesting consequence of this is that @samp{(-8)^1:3} does -not evaluate to @mathit{-2} as you might expect, but to the complex -number @expr{(1., 1.732)}. Both of these are valid cube roots -of @mathit{-8} (as is @expr{(1., -1.732)}); Calc chooses a perhaps -less-obvious root for the sake of mathematical consistency. - -For @samp{arcsin(z)}: This is defined by @samp{-i*ln(i*z + sqrt(1-z^2))}. -The branch cuts are on the real axis, less than @mathit{-1} and greater than 1. - -For @samp{arccos(z)}: This is defined by @samp{-i*ln(z + i*sqrt(1-z^2))}, -or equivalently by @samp{pi/2 - arcsin(z)}. The branch cuts are on -the real axis, less than @mathit{-1} and greater than 1. - -For @samp{arctan(z)}: This is defined by -@samp{(ln(1+i*z) - ln(1-i*z)) / (2*i)}. The branch cuts are on the -imaginary axis, below @expr{-i} and above @expr{i}. - -For @samp{arcsinh(z)}: This is defined by @samp{ln(z + sqrt(1+z^2))}. -The branch cuts are on the imaginary axis, below @expr{-i} and -above @expr{i}. - -For @samp{arccosh(z)}: This is defined by -@samp{ln(z + (z+1)*sqrt((z-1)/(z+1)))}. The branch cut is on the -real axis less than 1. - -For @samp{arctanh(z)}: This is defined by @samp{(ln(1+z) - ln(1-z)) / 2}. -The branch cuts are on the real axis, less than @mathit{-1} and greater than 1. - -The following tables for @code{arcsin}, @code{arccos}, and -@code{arctan} assume the current angular mode is Radians. The -hyperbolic functions operate independently of the angular mode. - -@smallexample - z arcsin(z) arccos(z) -------------------------------------------------------- - (-1..1), 0 (-pi/2..pi/2), 0 (0..pi), 0 - (-1..1), +eps (-pi/2..pi/2), +eps (0..pi), -eps - (-1..1), -eps (-pi/2..pi/2), -eps (0..pi), +eps - <-1, 0 -pi/2, + pi, - - <-1, +eps -pi/2 + eps, + pi - eps, - - <-1, -eps -pi/2 + eps, - pi - eps, + - >1, 0 pi/2, - 0, + - >1, +eps pi/2 - eps, + +eps, - - >1, -eps pi/2 - eps, - +eps, + -@end smallexample - -@smallexample - z arccosh(z) arctanh(z) ------------------------------------------------------ - (-1..1), 0 0, (0..pi) any, 0 - (-1..1), +eps +eps, (0..pi) any, +eps - (-1..1), -eps +eps, (-pi..0) any, -eps - <-1, 0 +, pi -, pi/2 - <-1, +eps +, pi - eps -, pi/2 - eps - <-1, -eps +, -pi + eps -, -pi/2 + eps - >1, 0 +, 0 +, -pi/2 - >1, +eps +, +eps +, pi/2 - eps - >1, -eps +, -eps +, -pi/2 + eps -@end smallexample - -@smallexample - z arcsinh(z) arctan(z) ------------------------------------------------------ - 0, (-1..1) 0, (-pi/2..pi/2) 0, any - 0, <-1 -, -pi/2 -pi/2, - - +eps, <-1 +, -pi/2 + eps pi/2 - eps, - - -eps, <-1 -, -pi/2 + eps -pi/2 + eps, - - 0, >1 +, pi/2 pi/2, + - +eps, >1 +, pi/2 - eps pi/2 - eps, + - -eps, >1 -, pi/2 - eps -pi/2 + eps, + -@end smallexample - -Finally, the following identities help to illustrate the relationship -between the complex trigonometric and hyperbolic functions. They -are valid everywhere, including on the branch cuts. - -@smallexample -sin(i*z) = i*sinh(z) arcsin(i*z) = i*arcsinh(z) -cos(i*z) = cosh(z) arcsinh(i*z) = i*arcsin(z) -tan(i*z) = i*tanh(z) arctan(i*z) = i*arctanh(z) -sinh(i*z) = i*sin(z) cosh(i*z) = cos(z) -@end smallexample - -The ``advanced math'' functions (gamma, Bessel, etc.@:) are also defined -for general complex arguments, but their branch cuts and principal values -are not rigorously specified at present. - -@node Random Numbers, Combinatorial Functions, Branch Cuts, Scientific Functions -@section Random Numbers - -@noindent -@kindex k r -@pindex calc-random -@tindex random -The @kbd{k r} (@code{calc-random}) [@code{random}] command produces -random numbers of various sorts. - -Given a positive numeric prefix argument @expr{M}, it produces a random -integer @expr{N} in the range -@texline @math{0 \le N < M}. -@infoline @expr{0 <= N < M}. -Each possible value @expr{N} appears with equal probability. - -With no numeric prefix argument, the @kbd{k r} command takes its argument -from the stack instead. Once again, if this is a positive integer @expr{M} -the result is a random integer less than @expr{M}. However, note that -while numeric prefix arguments are limited to six digits or so, an @expr{M} -taken from the stack can be arbitrarily large. If @expr{M} is negative, -the result is a random integer in the range -@texline @math{M < N \le 0}. -@infoline @expr{M < N <= 0}. - -If the value on the stack is a floating-point number @expr{M}, the result -is a random floating-point number @expr{N} in the range -@texline @math{0 \le N < M} -@infoline @expr{0 <= N < M} -or -@texline @math{M < N \le 0}, -@infoline @expr{M < N <= 0}, -according to the sign of @expr{M}. - -If @expr{M} is zero, the result is a Gaussian-distributed random real -number; the distribution has a mean of zero and a standard deviation -of one. The algorithm used generates random numbers in pairs; thus, -every other call to this function will be especially fast. - -If @expr{M} is an error form -@texline @math{m} @code{+/-} @math{\sigma} -@infoline @samp{m +/- s} -where @var{m} and -@texline @math{\sigma} -@infoline @var{s} -are both real numbers, the result uses a Gaussian distribution with mean -@var{m} and standard deviation -@texline @math{\sigma}. -@infoline @var{s}. - -If @expr{M} is an interval form, the lower and upper bounds specify the -acceptable limits of the random numbers. If both bounds are integers, -the result is a random integer in the specified range. If either bound -is floating-point, the result is a random real number in the specified -range. If the interval is open at either end, the result will be sure -not to equal that end value. (This makes a big difference for integer -intervals, but for floating-point intervals it's relatively minor: -with a precision of 6, @samp{random([1.0..2.0))} will return any of one -million numbers from 1.00000 to 1.99999; @samp{random([1.0..2.0])} may -additionally return 2.00000, but the probability of this happening is -extremely small.) - -If @expr{M} is a vector, the result is one element taken at random from -the vector. All elements of the vector are given equal probabilities. - -@vindex RandSeed -The sequence of numbers produced by @kbd{k r} is completely random by -default, i.e., the sequence is seeded each time you start Calc using -the current time and other information. You can get a reproducible -sequence by storing a particular ``seed value'' in the Calc variable -@code{RandSeed}. Any integer will do for a seed; integers of from 1 -to 12 digits are good. If you later store a different integer into -@code{RandSeed}, Calc will switch to a different pseudo-random -sequence. If you ``unstore'' @code{RandSeed}, Calc will re-seed itself -from the current time. If you store the same integer that you used -before back into @code{RandSeed}, you will get the exact same sequence -of random numbers as before. - -@pindex calc-rrandom -The @code{calc-rrandom} command (not on any key) produces a random real -number between zero and one. It is equivalent to @samp{random(1.0)}. - -@kindex k a -@pindex calc-random-again -The @kbd{k a} (@code{calc-random-again}) command produces another random -number, re-using the most recent value of @expr{M}. With a numeric -prefix argument @var{n}, it produces @var{n} more random numbers using -that value of @expr{M}. - -@kindex k h -@pindex calc-shuffle -@tindex shuffle -The @kbd{k h} (@code{calc-shuffle}) command produces a vector of several -random values with no duplicates. The value on the top of the stack -specifies the set from which the random values are drawn, and may be any -of the @expr{M} formats described above. The numeric prefix argument -gives the length of the desired list. (If you do not provide a numeric -prefix argument, the length of the list is taken from the top of the -stack, and @expr{M} from second-to-top.) - -If @expr{M} is a floating-point number, zero, or an error form (so -that the random values are being drawn from the set of real numbers) -there is little practical difference between using @kbd{k h} and using -@kbd{k r} several times. But if the set of possible values consists -of just a few integers, or the elements of a vector, then there is -a very real chance that multiple @kbd{k r}'s will produce the same -number more than once. The @kbd{k h} command produces a vector whose -elements are always distinct. (Actually, there is a slight exception: -If @expr{M} is a vector, no given vector element will be drawn more -than once, but if several elements of @expr{M} are equal, they may -each make it into the result vector.) - -One use of @kbd{k h} is to rearrange a list at random. This happens -if the prefix argument is equal to the number of values in the list: -@kbd{[1, 1.5, 2, 2.5, 3] 5 k h} might produce the permuted list -@samp{[2.5, 1, 1.5, 3, 2]}. As a convenient feature, if the argument -@var{n} is negative it is replaced by the size of the set represented -by @expr{M}. Naturally, this is allowed only when @expr{M} specifies -a small discrete set of possibilities. - -To do the equivalent of @kbd{k h} but with duplications allowed, -given @expr{M} on the stack and with @var{n} just entered as a numeric -prefix, use @kbd{v b} to build a vector of copies of @expr{M}, then use -@kbd{V M k r} to ``map'' the normal @kbd{k r} function over the -elements of this vector. @xref{Matrix Functions}. - -@menu -* Random Number Generator:: (Complete description of Calc's algorithm) -@end menu - -@node Random Number Generator, , Random Numbers, Random Numbers -@subsection Random Number Generator - -Calc's random number generator uses several methods to ensure that -the numbers it produces are highly random. Knuth's @emph{Art of -Computer Programming}, Volume II, contains a thorough description -of the theory of random number generators and their measurement and -characterization. - -If @code{RandSeed} has no stored value, Calc calls Emacs's built-in -@code{random} function to get a stream of random numbers, which it -then treats in various ways to avoid problems inherent in the simple -random number generators that many systems use to implement @code{random}. - -When Calc's random number generator is first invoked, it ``seeds'' -the low-level random sequence using the time of day, so that the -random number sequence will be different every time you use Calc. - -Since Emacs Lisp doesn't specify the range of values that will be -returned by its @code{random} function, Calc exercises the function -several times to estimate the range. When Calc subsequently uses -the @code{random} function, it takes only 10 bits of the result -near the most-significant end. (It avoids at least the bottom -four bits, preferably more, and also tries to avoid the top two -bits.) This strategy works well with the linear congruential -generators that are typically used to implement @code{random}. - -If @code{RandSeed} contains an integer, Calc uses this integer to -seed an ``additive congruential'' method (Knuth's algorithm 3.2.2A, -computing -@texline @math{X_{n-55} - X_{n-24}}. -@infoline @expr{X_n-55 - X_n-24}). -This method expands the seed -value into a large table which is maintained internally; the variable -@code{RandSeed} is changed from, e.g., 42 to the vector @expr{[42]} -to indicate that the seed has been absorbed into this table. When -@code{RandSeed} contains a vector, @kbd{k r} and related commands -continue to use the same internal table as last time. There is no -way to extract the complete state of the random number generator -so that you can restart it from any point; you can only restart it -from the same initial seed value. A simple way to restart from the -same seed is to type @kbd{s r RandSeed} to get the seed vector, -@kbd{v u} to unpack it back into a number, then @kbd{s t RandSeed} -to reseed the generator with that number. - -Calc uses a ``shuffling'' method as described in algorithm 3.2.2B -of Knuth. It fills a table with 13 random 10-bit numbers. Then, -to generate a new random number, it uses the previous number to -index into the table, picks the value it finds there as the new -random number, then replaces that table entry with a new value -obtained from a call to the base random number generator (either -the additive congruential generator or the @code{random} function -supplied by the system). If there are any flaws in the base -generator, shuffling will tend to even them out. But if the system -provides an excellent @code{random} function, shuffling will not -damage its randomness. - -To create a random integer of a certain number of digits, Calc -builds the integer three decimal digits at a time. For each group -of three digits, Calc calls its 10-bit shuffling random number generator -(which returns a value from 0 to 1023); if the random value is 1000 -or more, Calc throws it out and tries again until it gets a suitable -value. - -To create a random floating-point number with precision @var{p}, Calc -simply creates a random @var{p}-digit integer and multiplies by -@texline @math{10^{-p}}. -@infoline @expr{10^-p}. -The resulting random numbers should be very clean, but note -that relatively small numbers will have few significant random digits. -In other words, with a precision of 12, you will occasionally get -numbers on the order of -@texline @math{10^{-9}} -@infoline @expr{10^-9} -or -@texline @math{10^{-10}}, -@infoline @expr{10^-10}, -but those numbers will only have two or three random digits since they -correspond to small integers times -@texline @math{10^{-12}}. -@infoline @expr{10^-12}. - -To create a random integer in the interval @samp{[0 .. @var{m})}, Calc -counts the digits in @var{m}, creates a random integer with three -additional digits, then reduces modulo @var{m}. Unless @var{m} is a -power of ten the resulting values will be very slightly biased toward -the lower numbers, but this bias will be less than 0.1%. (For example, -if @var{m} is 42, Calc will reduce a random integer less than 100000 -modulo 42 to get a result less than 42. It is easy to show that the -numbers 40 and 41 will be only 2380/2381 as likely to result from this -modulo operation as numbers 39 and below.) If @var{m} is a power of -ten, however, the numbers should be completely unbiased. - -The Gaussian random numbers generated by @samp{random(0.0)} use the -``polar'' method described in Knuth section 3.4.1C. This method -generates a pair of Gaussian random numbers at a time, so only every -other call to @samp{random(0.0)} will require significant calculations. - -@node Combinatorial Functions, Probability Distribution Functions, Random Numbers, Scientific Functions -@section Combinatorial Functions - -@noindent -Commands relating to combinatorics and number theory begin with the -@kbd{k} key prefix. - -@kindex k g -@pindex calc-gcd -@tindex gcd -The @kbd{k g} (@code{calc-gcd}) [@code{gcd}] command computes the -Greatest Common Divisor of two integers. It also accepts fractions; -the GCD of two fractions is defined by taking the GCD of the -numerators, and the LCM of the denominators. This definition is -consistent with the idea that @samp{a / gcd(a,x)} should yield an -integer for any @samp{a} and @samp{x}. For other types of arguments, -the operation is left in symbolic form. - -@kindex k l -@pindex calc-lcm -@tindex lcm -The @kbd{k l} (@code{calc-lcm}) [@code{lcm}] command computes the -Least Common Multiple of two integers or fractions. The product of -the LCM and GCD of two numbers is equal to the product of the -numbers. - -@kindex k E -@pindex calc-extended-gcd -@tindex egcd -The @kbd{k E} (@code{calc-extended-gcd}) [@code{egcd}] command computes -the GCD of two integers @expr{x} and @expr{y} and returns a vector -@expr{[g, a, b]} where -@texline @math{g = \gcd(x,y) = a x + b y}. -@infoline @expr{g = gcd(x,y) = a x + b y}. - -@kindex ! -@pindex calc-factorial -@tindex fact -@ignore -@mindex @null -@end ignore -@tindex ! -The @kbd{!} (@code{calc-factorial}) [@code{fact}] command computes the -factorial of the number at the top of the stack. If the number is an -integer, the result is an exact integer. If the number is an -integer-valued float, the result is a floating-point approximation. If -the number is a non-integral real number, the generalized factorial is used, -as defined by the Euler Gamma function. Please note that computation of -large factorials can be slow; using floating-point format will help -since fewer digits must be maintained. The same is true of many of -the commands in this section. - -@kindex k d -@pindex calc-double-factorial -@tindex dfact -@ignore -@mindex @null -@end ignore -@tindex !! -The @kbd{k d} (@code{calc-double-factorial}) [@code{dfact}] command -computes the ``double factorial'' of an integer. For an even integer, -this is the product of even integers from 2 to @expr{N}. For an odd -integer, this is the product of odd integers from 3 to @expr{N}. If -the argument is an integer-valued float, the result is a floating-point -approximation. This function is undefined for negative even integers. -The notation @expr{N!!} is also recognized for double factorials. - -@kindex k c -@pindex calc-choose -@tindex choose -The @kbd{k c} (@code{calc-choose}) [@code{choose}] command computes the -binomial coefficient @expr{N}-choose-@expr{M}, where @expr{M} is the number -on the top of the stack and @expr{N} is second-to-top. If both arguments -are integers, the result is an exact integer. Otherwise, the result is a -floating-point approximation. The binomial coefficient is defined for all -real numbers by -@texline @math{N! \over M! (N-M)!\,}. -@infoline @expr{N! / M! (N-M)!}. - -@kindex H k c -@pindex calc-perm -@tindex perm -@ifnottex -The @kbd{H k c} (@code{calc-perm}) [@code{perm}] command computes the -number-of-permutations function @expr{N! / (N-M)!}. -@end ifnottex -@tex -The \kbd{H k c} (\code{calc-perm}) [\code{perm}] command computes the -number-of-perm\-utations function $N! \over (N-M)!\,$. -@end tex - -@kindex k b -@kindex H k b -@pindex calc-bernoulli-number -@tindex bern -The @kbd{k b} (@code{calc-bernoulli-number}) [@code{bern}] command -computes a given Bernoulli number. The value at the top of the stack -is a nonnegative integer @expr{n} that specifies which Bernoulli number -is desired. The @kbd{H k b} command computes a Bernoulli polynomial, -taking @expr{n} from the second-to-top position and @expr{x} from the -top of the stack. If @expr{x} is a variable or formula the result is -a polynomial in @expr{x}; if @expr{x} is a number the result is a number. - -@kindex k e -@kindex H k e -@pindex calc-euler-number -@tindex euler -The @kbd{k e} (@code{calc-euler-number}) [@code{euler}] command similarly -computes an Euler number, and @w{@kbd{H k e}} computes an Euler polynomial. -Bernoulli and Euler numbers occur in the Taylor expansions of several -functions. - -@kindex k s -@kindex H k s -@pindex calc-stirling-number -@tindex stir1 -@tindex stir2 -The @kbd{k s} (@code{calc-stirling-number}) [@code{stir1}] command -computes a Stirling number of the first -@texline kind@tie{}@math{n \brack m}, -@infoline kind, -given two integers @expr{n} and @expr{m} on the stack. The @kbd{H k s} -[@code{stir2}] command computes a Stirling number of the second -@texline kind@tie{}@math{n \brace m}. -@infoline kind. -These are the number of @expr{m}-cycle permutations of @expr{n} objects, -and the number of ways to partition @expr{n} objects into @expr{m} -non-empty sets, respectively. - -@kindex k p -@pindex calc-prime-test -@cindex Primes -The @kbd{k p} (@code{calc-prime-test}) command checks if the integer on -the top of the stack is prime. For integers less than eight million, the -answer is always exact and reasonably fast. For larger integers, a -probabilistic method is used (see Knuth vol. II, section 4.5.4, algorithm P). -The number is first checked against small prime factors (up to 13). Then, -any number of iterations of the algorithm are performed. Each step either -discovers that the number is non-prime, or substantially increases the -certainty that the number is prime. After a few steps, the chance that -a number was mistakenly described as prime will be less than one percent. -(Indeed, this is a worst-case estimate of the probability; in practice -even a single iteration is quite reliable.) After the @kbd{k p} command, -the number will be reported as definitely prime or non-prime if possible, -or otherwise ``probably'' prime with a certain probability of error. - -@ignore -@starindex -@end ignore -@tindex prime -The normal @kbd{k p} command performs one iteration of the primality -test. Pressing @kbd{k p} repeatedly for the same integer will perform -additional iterations. Also, @kbd{k p} with a numeric prefix performs -the specified number of iterations. There is also an algebraic function -@samp{prime(n)} or @samp{prime(n,iters)} which returns 1 if @expr{n} -is (probably) prime and 0 if not. - -@kindex k f -@pindex calc-prime-factors -@tindex prfac -The @kbd{k f} (@code{calc-prime-factors}) [@code{prfac}] command -attempts to decompose an integer into its prime factors. For numbers up -to 25 million, the answer is exact although it may take some time. The -result is a vector of the prime factors in increasing order. For larger -inputs, prime factors above 5000 may not be found, in which case the -last number in the vector will be an unfactored integer greater than 25 -million (with a warning message). For negative integers, the first -element of the list will be @mathit{-1}. For inputs @mathit{-1}, @mathit{0}, and -@mathit{1}, the result is a list of the same number. - -@kindex k n -@pindex calc-next-prime -@ignore -@mindex nextpr@idots -@end ignore -@tindex nextprime -The @kbd{k n} (@code{calc-next-prime}) [@code{nextprime}] command finds -the next prime above a given number. Essentially, it searches by calling -@code{calc-prime-test} on successive integers until it finds one that -passes the test. This is quite fast for integers less than eight million, -but once the probabilistic test comes into play the search may be rather -slow. Ordinarily this command stops for any prime that passes one iteration -of the primality test. With a numeric prefix argument, a number must pass -the specified number of iterations before the search stops. (This only -matters when searching above eight million.) You can always use additional -@kbd{k p} commands to increase your certainty that the number is indeed -prime. - -@kindex I k n -@pindex calc-prev-prime -@ignore -@mindex prevpr@idots -@end ignore -@tindex prevprime -The @kbd{I k n} (@code{calc-prev-prime}) [@code{prevprime}] command -analogously finds the next prime less than a given number. - -@kindex k t -@pindex calc-totient -@tindex totient -The @kbd{k t} (@code{calc-totient}) [@code{totient}] command computes the -Euler ``totient'' -@texline function@tie{}@math{\phi(n)}, -@infoline function, -the number of integers less than @expr{n} which -are relatively prime to @expr{n}. - -@kindex k m -@pindex calc-moebius -@tindex moebius -The @kbd{k m} (@code{calc-moebius}) [@code{moebius}] command computes the -@texline M@"obius @math{\mu} -@infoline Moebius ``mu'' -function. If the input number is a product of @expr{k} -distinct factors, this is @expr{(-1)^k}. If the input number has any -duplicate factors (i.e., can be divided by the same prime more than once), -the result is zero. - -@node Probability Distribution Functions, , Combinatorial Functions, Scientific Functions -@section Probability Distribution Functions - -@noindent -The functions in this section compute various probability distributions. -For continuous distributions, this is the integral of the probability -density function from @expr{x} to infinity. (These are the ``upper -tail'' distribution functions; there are also corresponding ``lower -tail'' functions which integrate from minus infinity to @expr{x}.) -For discrete distributions, the upper tail function gives the sum -from @expr{x} to infinity; the lower tail function gives the sum -from minus infinity up to, but not including,@w{ }@expr{x}. - -To integrate from @expr{x} to @expr{y}, just use the distribution -function twice and subtract. For example, the probability that a -Gaussian random variable with mean 2 and standard deviation 1 will -lie in the range from 2.5 to 2.8 is @samp{utpn(2.5,2,1) - utpn(2.8,2,1)} -(``the probability that it is greater than 2.5, but not greater than 2.8''), -or equivalently @samp{ltpn(2.8,2,1) - ltpn(2.5,2,1)}. - -@kindex k B -@kindex I k B -@pindex calc-utpb -@tindex utpb -@tindex ltpb -The @kbd{k B} (@code{calc-utpb}) [@code{utpb}] function uses the -binomial distribution. Push the parameters @var{n}, @var{p}, and -then @var{x} onto the stack; the result (@samp{utpb(x,n,p)}) is the -probability that an event will occur @var{x} or more times out -of @var{n} trials, if its probability of occurring in any given -trial is @var{p}. The @kbd{I k B} [@code{ltpb}] function is -the probability that the event will occur fewer than @var{x} times. - -The other probability distribution functions similarly take the -form @kbd{k @var{X}} (@code{calc-utp@var{x}}) [@code{utp@var{x}}] -and @kbd{I k @var{X}} [@code{ltp@var{x}}], for various letters -@var{x}. The arguments to the algebraic functions are the value of -the random variable first, then whatever other parameters define the -distribution. Note these are among the few Calc functions where the -order of the arguments in algebraic form differs from the order of -arguments as found on the stack. (The random variable comes last on -the stack, so that you can type, e.g., @kbd{2 @key{RET} 1 @key{RET} 2.5 -k N M-@key{RET} @key{DEL} 2.8 k N -}, using @kbd{M-@key{RET} @key{DEL}} to -recover the original arguments but substitute a new value for @expr{x}.) - -@kindex k C -@pindex calc-utpc -@tindex utpc -@ignore -@mindex @idots -@end ignore -@kindex I k C -@ignore -@mindex @null -@end ignore -@tindex ltpc -The @samp{utpc(x,v)} function uses the chi-square distribution with -@texline @math{\nu} -@infoline @expr{v} -degrees of freedom. It is the probability that a model is -correct if its chi-square statistic is @expr{x}. - -@kindex k F -@pindex calc-utpf -@tindex utpf -@ignore -@mindex @idots -@end ignore -@kindex I k F -@ignore -@mindex @null -@end ignore -@tindex ltpf -The @samp{utpf(F,v1,v2)} function uses the F distribution, used in -various statistical tests. The parameters -@texline @math{\nu_1} -@infoline @expr{v1} -and -@texline @math{\nu_2} -@infoline @expr{v2} -are the degrees of freedom in the numerator and denominator, -respectively, used in computing the statistic @expr{F}. - -@kindex k N -@pindex calc-utpn -@tindex utpn -@ignore -@mindex @idots -@end ignore -@kindex I k N -@ignore -@mindex @null -@end ignore -@tindex ltpn -The @samp{utpn(x,m,s)} function uses a normal (Gaussian) distribution -with mean @expr{m} and standard deviation -@texline @math{\sigma}. -@infoline @expr{s}. -It is the probability that such a normal-distributed random variable -would exceed @expr{x}. - -@kindex k P -@pindex calc-utpp -@tindex utpp -@ignore -@mindex @idots -@end ignore -@kindex I k P -@ignore -@mindex @null -@end ignore -@tindex ltpp -The @samp{utpp(n,x)} function uses a Poisson distribution with -mean @expr{x}. It is the probability that @expr{n} or more such -Poisson random events will occur. - -@kindex k T -@pindex calc-ltpt -@tindex utpt -@ignore -@mindex @idots -@end ignore -@kindex I k T -@ignore -@mindex @null -@end ignore -@tindex ltpt -The @samp{utpt(t,v)} function uses the Student's ``t'' distribution -with -@texline @math{\nu} -@infoline @expr{v} -degrees of freedom. It is the probability that a -t-distributed random variable will be greater than @expr{t}. -(Note: This computes the distribution function -@texline @math{A(t|\nu)} -@infoline @expr{A(t|v)} -where -@texline @math{A(0|\nu) = 1} -@infoline @expr{A(0|v) = 1} -and -@texline @math{A(\infty|\nu) \to 0}. -@infoline @expr{A(inf|v) -> 0}. -The @code{UTPT} operation on the HP-48 uses a different definition which -returns half of Calc's value: @samp{UTPT(t,v) = .5*utpt(t,v)}.) - -While Calc does not provide inverses of the probability distribution -functions, the @kbd{a R} command can be used to solve for the inverse. -Since the distribution functions are monotonic, @kbd{a R} is guaranteed -to be able to find a solution given any initial guess. -@xref{Numerical Solutions}. - -@node Matrix Functions, Algebra, Scientific Functions, Top -@chapter Vector/Matrix Functions - -@noindent -Many of the commands described here begin with the @kbd{v} prefix. -(For convenience, the shift-@kbd{V} prefix is equivalent to @kbd{v}.) -The commands usually apply to both plain vectors and matrices; some -apply only to matrices or only to square matrices. If the argument -has the wrong dimensions the operation is left in symbolic form. - -Vectors are entered and displayed using @samp{[a,b,c]} notation. -Matrices are vectors of which all elements are vectors of equal length. -(Though none of the standard Calc commands use this concept, a -three-dimensional matrix or rank-3 tensor could be defined as a -vector of matrices, and so on.) - -@menu -* Packing and Unpacking:: -* Building Vectors:: -* Extracting Elements:: -* Manipulating Vectors:: -* Vector and Matrix Arithmetic:: -* Set Operations:: -* Statistical Operations:: -* Reducing and Mapping:: -* Vector and Matrix Formats:: -@end menu - -@node Packing and Unpacking, Building Vectors, Matrix Functions, Matrix Functions -@section Packing and Unpacking - -@noindent -Calc's ``pack'' and ``unpack'' commands collect stack entries to build -composite objects such as vectors and complex numbers. They are -described in this chapter because they are most often used to build -vectors. - -@kindex v p -@kindex V p -@pindex calc-pack -The @kbd{v p} (@code{calc-pack}) [@code{pack}] command collects several -elements from the stack into a matrix, complex number, HMS form, error -form, etc. It uses a numeric prefix argument to specify the kind of -object to be built; this argument is referred to as the ``packing mode.'' -If the packing mode is a nonnegative integer, a vector of that -length is created. For example, @kbd{C-u 5 v p} will pop the top -five stack elements and push back a single vector of those five -elements. (@kbd{C-u 0 v p} simply creates an empty vector.) - -The same effect can be had by pressing @kbd{[} to push an incomplete -vector on the stack, using @key{TAB} (@code{calc-roll-down}) to sneak -the incomplete object up past a certain number of elements, and -then pressing @kbd{]} to complete the vector. - -Negative packing modes create other kinds of composite objects: - -@table @cite -@item -1 -Two values are collected to build a complex number. For example, -@kbd{5 @key{RET} 7 C-u -1 v p} creates the complex number -@expr{(5, 7)}. The result is always a rectangular complex -number. The two input values must both be real numbers, -i.e., integers, fractions, or floats. If they are not, Calc -will instead build a formula like @samp{a + (0, 1) b}. (The -other packing modes also create a symbolic answer if the -components are not suitable.) - -@item -2 -Two values are collected to build a polar complex number. -The first is the magnitude; the second is the phase expressed -in either degrees or radians according to the current angular -mode. - -@item -3 -Three values are collected into an HMS form. The first -two values (hours and minutes) must be integers or -integer-valued floats. The third value may be any real -number. - -@item -4 -Two values are collected into an error form. The inputs -may be real numbers or formulas. - -@item -5 -Two values are collected into a modulo form. The inputs -must be real numbers. - -@item -6 -Two values are collected into the interval @samp{[a .. b]}. -The inputs may be real numbers, HMS or date forms, or formulas. - -@item -7 -Two values are collected into the interval @samp{[a .. b)}. - -@item -8 -Two values are collected into the interval @samp{(a .. b]}. - -@item -9 -Two values are collected into the interval @samp{(a .. b)}. - -@item -10 -Two integer values are collected into a fraction. - -@item -11 -Two values are collected into a floating-point number. -The first is the mantissa; the second, which must be an -integer, is the exponent. The result is the mantissa -times ten to the power of the exponent. - -@item -12 -This is treated the same as @mathit{-11} by the @kbd{v p} command. -When unpacking, @mathit{-12} specifies that a floating-point mantissa -is desired. - -@item -13 -A real number is converted into a date form. - -@item -14 -Three numbers (year, month, day) are packed into a pure date form. - -@item -15 -Six numbers are packed into a date/time form. -@end table - -With any of the two-input negative packing modes, either or both -of the inputs may be vectors. If both are vectors of the same -length, the result is another vector made by packing corresponding -elements of the input vectors. If one input is a vector and the -other is a plain number, the number is packed along with each vector -element to produce a new vector. For example, @kbd{C-u -4 v p} -could be used to convert a vector of numbers and a vector of errors -into a single vector of error forms; @kbd{C-u -5 v p} could convert -a vector of numbers and a single number @var{M} into a vector of -numbers modulo @var{M}. - -If you don't give a prefix argument to @kbd{v p}, it takes -the packing mode from the top of the stack. The elements to -be packed then begin at stack level 2. Thus -@kbd{1 @key{RET} 2 @key{RET} 4 n v p} is another way to -enter the error form @samp{1 +/- 2}. - -If the packing mode taken from the stack is a vector, the result is a -matrix with the dimensions specified by the elements of the vector, -which must each be integers. For example, if the packing mode is -@samp{[2, 3]}, then six numbers will be taken from the stack and -returned in the form @samp{[@w{[a, b, c]}, [d, e, f]]}. - -If any elements of the vector are negative, other kinds of -packing are done at that level as described above. For -example, @samp{[2, 3, -4]} takes 12 objects and creates a -@texline @math{2\times3} -@infoline 2x3 -matrix of error forms: @samp{[[a +/- b, c +/- d ... ]]}. -Also, @samp{[-4, -10]} will convert four integers into an -error form consisting of two fractions: @samp{a:b +/- c:d}. - -@ignore -@starindex -@end ignore -@tindex pack -There is an equivalent algebraic function, -@samp{pack(@var{mode}, @var{items})} where @var{mode} is a -packing mode (an integer or a vector of integers) and @var{items} -is a vector of objects to be packed (re-packed, really) according -to that mode. For example, @samp{pack([3, -4], [a,b,c,d,e,f])} -yields @samp{[a +/- b, @w{c +/- d}, e +/- f]}. The function is -left in symbolic form if the packing mode is invalid, or if the -number of data items does not match the number of items required -by the mode. - -@kindex v u -@kindex V u -@pindex calc-unpack -The @kbd{v u} (@code{calc-unpack}) command takes the vector, complex -number, HMS form, or other composite object on the top of the stack and -``unpacks'' it, pushing each of its elements onto the stack as separate -objects. Thus, it is the ``inverse'' of @kbd{v p}. If the value -at the top of the stack is a formula, @kbd{v u} unpacks it by pushing -each of the arguments of the top-level operator onto the stack. - -You can optionally give a numeric prefix argument to @kbd{v u} -to specify an explicit (un)packing mode. If the packing mode is -negative and the input is actually a vector or matrix, the result -will be two or more similar vectors or matrices of the elements. -For example, given the vector @samp{[@w{a +/- b}, c^2, d +/- 7]}, -the result of @kbd{C-u -4 v u} will be the two vectors -@samp{[a, c^2, d]} and @w{@samp{[b, 0, 7]}}. - -Note that the prefix argument can have an effect even when the input is -not a vector. For example, if the input is the number @mathit{-5}, then -@kbd{c-u -1 v u} yields @mathit{-5} and 0 (the components of @mathit{-5} -when viewed as a rectangular complex number); @kbd{C-u -2 v u} yields 5 -and 180 (assuming Degrees mode); and @kbd{C-u -10 v u} yields @mathit{-5} -and 1 (the numerator and denominator of @mathit{-5}, viewed as a rational -number). Plain @kbd{v u} with this input would complain that the input -is not a composite object. - -Unpacking mode @mathit{-11} converts a float into an integer mantissa and -an integer exponent, where the mantissa is not divisible by 10 -(except that 0.0 is represented by a mantissa and exponent of 0). -Unpacking mode @mathit{-12} converts a float into a floating-point mantissa -and integer exponent, where the mantissa (for non-zero numbers) -is guaranteed to lie in the range [1 .. 10). In both cases, -the mantissa is shifted left or right (and the exponent adjusted -to compensate) in order to satisfy these constraints. - -Positive unpacking modes are treated differently than for @kbd{v p}. -A mode of 1 is much like plain @kbd{v u} with no prefix argument, -except that in addition to the components of the input object, -a suitable packing mode to re-pack the object is also pushed. -Thus, @kbd{C-u 1 v u} followed by @kbd{v p} will re-build the -original object. - -A mode of 2 unpacks two levels of the object; the resulting -re-packing mode will be a vector of length 2. This might be used -to unpack a matrix, say, or a vector of error forms. Higher -unpacking modes unpack the input even more deeply. - -@ignore -@starindex -@end ignore -@tindex unpack -There are two algebraic functions analogous to @kbd{v u}. -The @samp{unpack(@var{mode}, @var{item})} function unpacks the -@var{item} using the given @var{mode}, returning the result as -a vector of components. Here the @var{mode} must be an -integer, not a vector. For example, @samp{unpack(-4, a +/- b)} -returns @samp{[a, b]}, as does @samp{unpack(1, a +/- b)}. - -@ignore -@starindex -@end ignore -@tindex unpackt -The @code{unpackt} function is like @code{unpack} but instead -of returning a simple vector of items, it returns a vector of -two things: The mode, and the vector of items. For example, -@samp{unpackt(1, 2:3 +/- 1:4)} returns @samp{[-4, [2:3, 1:4]]}, -and @samp{unpackt(2, 2:3 +/- 1:4)} returns @samp{[[-4, -10], [2, 3, 1, 4]]}. -The identity for re-building the original object is -@samp{apply(pack, unpackt(@var{n}, @var{x})) = @var{x}}. (The -@code{apply} function builds a function call given the function -name and a vector of arguments.) - -@cindex Numerator of a fraction, extracting -Subscript notation is a useful way to extract a particular part -of an object. For example, to get the numerator of a rational -number, you can use @samp{unpack(-10, @var{x})_1}. - -@node Building Vectors, Extracting Elements, Packing and Unpacking, Matrix Functions -@section Building Vectors - -@noindent -Vectors and matrices can be added, -subtracted, multiplied, and divided; @pxref{Basic Arithmetic}. - -@kindex | -@pindex calc-concat -@ignore -@mindex @null -@end ignore -@tindex | -The @kbd{|} (@code{calc-concat}) [@code{vconcat}] command ``concatenates'' two vectors -into one. For example, after @kbd{@w{[ 1 , 2 ]} [ 3 , 4 ] |}, the stack -will contain the single vector @samp{[1, 2, 3, 4]}. If the arguments -are matrices, the rows of the first matrix are concatenated with the -rows of the second. (In other words, two matrices are just two vectors -of row-vectors as far as @kbd{|} is concerned.) - -If either argument to @kbd{|} is a scalar (a non-vector), it is treated -like a one-element vector for purposes of concatenation: @kbd{1 [ 2 , 3 ] |} -produces the vector @samp{[1, 2, 3]}. Likewise, if one argument is a -matrix and the other is a plain vector, the vector is treated as a -one-row matrix. - -@kindex H | -@tindex append -The @kbd{H |} (@code{calc-append}) [@code{append}] command concatenates -two vectors without any special cases. Both inputs must be vectors. -Whether or not they are matrices is not taken into account. If either -argument is a scalar, the @code{append} function is left in symbolic form. -See also @code{cons} and @code{rcons} below. - -@kindex I | -@kindex H I | -The @kbd{I |} and @kbd{H I |} commands are similar, but they use their -two stack arguments in the opposite order. Thus @kbd{I |} is equivalent -to @kbd{@key{TAB} |}, but possibly more convenient and also a bit faster. - -@kindex v d -@kindex V d -@pindex calc-diag -@tindex diag -The @kbd{v d} (@code{calc-diag}) [@code{diag}] function builds a diagonal -square matrix. The optional numeric prefix gives the number of rows -and columns in the matrix. If the value at the top of the stack is a -vector, the elements of the vector are used as the diagonal elements; the -prefix, if specified, must match the size of the vector. If the value on -the stack is a scalar, it is used for each element on the diagonal, and -the prefix argument is required. - -To build a constant square matrix, e.g., a -@texline @math{3\times3} -@infoline 3x3 -matrix filled with ones, use @kbd{0 M-3 v d 1 +}, i.e., build a zero -matrix first and then add a constant value to that matrix. (Another -alternative would be to use @kbd{v b} and @kbd{v a}; see below.) - -@kindex v i -@kindex V i -@pindex calc-ident -@tindex idn -The @kbd{v i} (@code{calc-ident}) [@code{idn}] function builds an identity -matrix of the specified size. It is a convenient form of @kbd{v d} -where the diagonal element is always one. If no prefix argument is given, -this command prompts for one. - -In algebraic notation, @samp{idn(a,n)} acts much like @samp{diag(a,n)}, -except that @expr{a} is required to be a scalar (non-vector) quantity. -If @expr{n} is omitted, @samp{idn(a)} represents @expr{a} times an -identity matrix of unknown size. Calc can operate algebraically on -such generic identity matrices, and if one is combined with a matrix -whose size is known, it is converted automatically to an identity -matrix of a suitable matching size. The @kbd{v i} command with an -argument of zero creates a generic identity matrix, @samp{idn(1)}. -Note that in dimensioned Matrix mode (@pxref{Matrix Mode}), generic -identity matrices are immediately expanded to the current default -dimensions. - -@kindex v x -@kindex V x -@pindex calc-index -@tindex index -The @kbd{v x} (@code{calc-index}) [@code{index}] function builds a vector -of consecutive integers from 1 to @var{n}, where @var{n} is the numeric -prefix argument. If you do not provide a prefix argument, you will be -prompted to enter a suitable number. If @var{n} is negative, the result -is a vector of negative integers from @var{n} to @mathit{-1}. - -With a prefix argument of just @kbd{C-u}, the @kbd{v x} command takes -three values from the stack: @var{n}, @var{start}, and @var{incr} (with -@var{incr} at top-of-stack). Counting starts at @var{start} and increases -by @var{incr} for successive vector elements. If @var{start} or @var{n} -is in floating-point format, the resulting vector elements will also be -floats. Note that @var{start} and @var{incr} may in fact be any kind -of numbers or formulas. - -When @var{start} and @var{incr} are specified, a negative @var{n} has a -different interpretation: It causes a geometric instead of arithmetic -sequence to be generated. For example, @samp{index(-3, a, b)} produces -@samp{[a, a b, a b^2]}. If you omit @var{incr} in the algebraic form, -@samp{index(@var{n}, @var{start})}, the default value for @var{incr} -is one for positive @var{n} or two for negative @var{n}. - -@kindex v b -@kindex V b -@pindex calc-build-vector -@tindex cvec -The @kbd{v b} (@code{calc-build-vector}) [@code{cvec}] function builds a -vector of @var{n} copies of the value on the top of the stack, where @var{n} -is the numeric prefix argument. In algebraic formulas, @samp{cvec(x,n,m)} -can also be used to build an @var{n}-by-@var{m} matrix of copies of @var{x}. -(Interactively, just use @kbd{v b} twice: once to build a row, then again -to build a matrix of copies of that row.) - -@kindex v h -@kindex V h -@kindex I v h -@kindex I V h -@pindex calc-head -@pindex calc-tail -@tindex head -@tindex tail -The @kbd{v h} (@code{calc-head}) [@code{head}] function returns the first -element of a vector. The @kbd{I v h} (@code{calc-tail}) [@code{tail}] -function returns the vector with its first element removed. In both -cases, the argument must be a non-empty vector. - -@kindex v k -@kindex V k -@pindex calc-cons -@tindex cons -The @kbd{v k} (@code{calc-cons}) [@code{cons}] function takes a value @var{h} -and a vector @var{t} from the stack, and produces the vector whose head is -@var{h} and whose tail is @var{t}. This is similar to @kbd{|}, except -if @var{h} is itself a vector, @kbd{|} will concatenate the two vectors -whereas @code{cons} will insert @var{h} at the front of the vector @var{t}. - -@kindex H v h -@kindex H V h -@tindex rhead -@ignore -@mindex @idots -@end ignore -@kindex H I v h -@kindex H I V h -@ignore -@mindex @null -@end ignore -@kindex H v k -@kindex H V k -@ignore -@mindex @null -@end ignore -@tindex rtail -@ignore -@mindex @null -@end ignore -@tindex rcons -Each of these three functions also accepts the Hyperbolic flag [@code{rhead}, -@code{rtail}, @code{rcons}] in which case @var{t} instead represents -the @emph{last} single element of the vector, with @var{h} -representing the remainder of the vector. Thus the vector -@samp{[a, b, c, d] = cons(a, [b, c, d]) = rcons([a, b, c], d)}. -Also, @samp{head([a, b, c, d]) = a}, @samp{tail([a, b, c, d]) = [b, c, d]}, -@samp{rhead([a, b, c, d]) = [a, b, c]}, and @samp{rtail([a, b, c, d]) = d}. - -@node Extracting Elements, Manipulating Vectors, Building Vectors, Matrix Functions -@section Extracting Vector Elements - -@noindent -@kindex v r -@kindex V r -@pindex calc-mrow -@tindex mrow -The @kbd{v r} (@code{calc-mrow}) [@code{mrow}] command extracts one row of -the matrix on the top of the stack, or one element of the plain vector on -the top of the stack. The row or element is specified by the numeric -prefix argument; the default is to prompt for the row or element number. -The matrix or vector is replaced by the specified row or element in the -form of a vector or scalar, respectively. - -@cindex Permutations, applying -With a prefix argument of @kbd{C-u} only, @kbd{v r} takes the index of -the element or row from the top of the stack, and the vector or matrix -from the second-to-top position. If the index is itself a vector of -integers, the result is a vector of the corresponding elements of the -input vector, or a matrix of the corresponding rows of the input matrix. -This command can be used to obtain any permutation of a vector. - -With @kbd{C-u}, if the index is an interval form with integer components, -it is interpreted as a range of indices and the corresponding subvector or -submatrix is returned. - -@cindex Subscript notation -@kindex a _ -@pindex calc-subscript -@tindex subscr -@tindex _ -Subscript notation in algebraic formulas (@samp{a_b}) stands for the -Calc function @code{subscr}, which is synonymous with @code{mrow}. -Thus, @samp{[x, y, z]_k} produces @expr{x}, @expr{y}, or @expr{z} if -@expr{k} is one, two, or three, respectively. A double subscript -(@samp{M_i_j}, equivalent to @samp{subscr(subscr(M, i), j)}) will -access the element at row @expr{i}, column @expr{j} of a matrix. -The @kbd{a _} (@code{calc-subscript}) command creates a subscript -formula @samp{a_b} out of two stack entries. (It is on the @kbd{a} -``algebra'' prefix because subscripted variables are often used -purely as an algebraic notation.) - -@tindex mrrow -Given a negative prefix argument, @kbd{v r} instead deletes one row or -element from the matrix or vector on the top of the stack. Thus -@kbd{C-u 2 v r} replaces a matrix with its second row, but @kbd{C-u -2 v r} -replaces the matrix with the same matrix with its second row removed. -In algebraic form this function is called @code{mrrow}. - -@tindex getdiag -Given a prefix argument of zero, @kbd{v r} extracts the diagonal elements -of a square matrix in the form of a vector. In algebraic form this -function is called @code{getdiag}. - -@kindex v c -@kindex V c -@pindex calc-mcol -@tindex mcol -@tindex mrcol -The @kbd{v c} (@code{calc-mcol}) [@code{mcol} or @code{mrcol}] command is -the analogous operation on columns of a matrix. Given a plain vector -it extracts (or removes) one element, just like @kbd{v r}. If the -index in @kbd{C-u v c} is an interval or vector and the argument is a -matrix, the result is a submatrix with only the specified columns -retained (and possibly permuted in the case of a vector index). - -To extract a matrix element at a given row and column, use @kbd{v r} to -extract the row as a vector, then @kbd{v c} to extract the column element -from that vector. In algebraic formulas, it is often more convenient to -use subscript notation: @samp{m_i_j} gives row @expr{i}, column @expr{j} -of matrix @expr{m}. - -@kindex v s -@kindex V s -@pindex calc-subvector -@tindex subvec -The @kbd{v s} (@code{calc-subvector}) [@code{subvec}] command extracts -a subvector of a vector. The arguments are the vector, the starting -index, and the ending index, with the ending index in the top-of-stack -position. The starting index indicates the first element of the vector -to take. The ending index indicates the first element @emph{past} the -range to be taken. Thus, @samp{subvec([a, b, c, d, e], 2, 4)} produces -the subvector @samp{[b, c]}. You could get the same result using -@samp{mrow([a, b, c, d, e], @w{[2 .. 4)})}. - -If either the start or the end index is zero or negative, it is -interpreted as relative to the end of the vector. Thus -@samp{subvec([a, b, c, d, e], 2, -2)} also produces @samp{[b, c]}. In -the algebraic form, the end index can be omitted in which case it -is taken as zero, i.e., elements from the starting element to the -end of the vector are used. The infinity symbol, @code{inf}, also -has this effect when used as the ending index. - -@kindex I v s -@kindex I V s -@tindex rsubvec -With the Inverse flag, @kbd{I v s} [@code{rsubvec}] removes a subvector -from a vector. The arguments are interpreted the same as for the -normal @kbd{v s} command. Thus, @samp{rsubvec([a, b, c, d, e], 2, 4)} -produces @samp{[a, d, e]}. It is always true that @code{subvec} and -@code{rsubvec} return complementary parts of the input vector. - -@xref{Selecting Subformulas}, for an alternative way to operate on -vectors one element at a time. - -@node Manipulating Vectors, Vector and Matrix Arithmetic, Extracting Elements, Matrix Functions -@section Manipulating Vectors - -@noindent -@kindex v l -@kindex V l -@pindex calc-vlength -@tindex vlen -The @kbd{v l} (@code{calc-vlength}) [@code{vlen}] command computes the -length of a vector. The length of a non-vector is considered to be zero. -Note that matrices are just vectors of vectors for the purposes of this -command. - -@kindex H v l -@kindex H V l -@tindex mdims -With the Hyperbolic flag, @kbd{H v l} [@code{mdims}] computes a vector -of the dimensions of a vector, matrix, or higher-order object. For -example, @samp{mdims([[a,b,c],[d,e,f]])} returns @samp{[2, 3]} since -its argument is a -@texline @math{2\times3} -@infoline 2x3 -matrix. - -@kindex v f -@kindex V f -@pindex calc-vector-find -@tindex find -The @kbd{v f} (@code{calc-vector-find}) [@code{find}] command searches -along a vector for the first element equal to a given target. The target -is on the top of the stack; the vector is in the second-to-top position. -If a match is found, the result is the index of the matching element. -Otherwise, the result is zero. The numeric prefix argument, if given, -allows you to select any starting index for the search. - -@kindex v a -@kindex V a -@pindex calc-arrange-vector -@tindex arrange -@cindex Arranging a matrix -@cindex Reshaping a matrix -@cindex Flattening a matrix -The @kbd{v a} (@code{calc-arrange-vector}) [@code{arrange}] command -rearranges a vector to have a certain number of columns and rows. The -numeric prefix argument specifies the number of columns; if you do not -provide an argument, you will be prompted for the number of columns. -The vector or matrix on the top of the stack is @dfn{flattened} into a -plain vector. If the number of columns is nonzero, this vector is -then formed into a matrix by taking successive groups of @var{n} elements. -If the number of columns does not evenly divide the number of elements -in the vector, the last row will be short and the result will not be -suitable for use as a matrix. For example, with the matrix -@samp{[[1, 2], @w{[3, 4]}]} on the stack, @kbd{v a 4} produces -@samp{[[1, 2, 3, 4]]} (a -@texline @math{1\times4} -@infoline 1x4 -matrix), @kbd{v a 1} produces @samp{[[1], [2], [3], [4]]} (a -@texline @math{4\times1} -@infoline 4x1 -matrix), @kbd{v a 2} produces @samp{[[1, 2], [3, 4]]} (the original -@texline @math{2\times2} -@infoline 2x2 -matrix), @w{@kbd{v a 3}} produces @samp{[[1, 2, 3], [4]]} (not a -matrix), and @kbd{v a 0} produces the flattened list -@samp{[1, 2, @w{3, 4}]}. - -@cindex Sorting data -@kindex v S -@kindex V S -@kindex I v S -@kindex I V S -@pindex calc-sort -@tindex sort -@tindex rsort -The @kbd{V S} (@code{calc-sort}) [@code{sort}] command sorts the elements of -a vector into increasing order. Real numbers, real infinities, and -constant interval forms come first in this ordering; next come other -kinds of numbers, then variables (in alphabetical order), then finally -come formulas and other kinds of objects; these are sorted according -to a kind of lexicographic ordering with the useful property that -one vector is less or greater than another if the first corresponding -unequal elements are less or greater, respectively. Since quoted strings -are stored by Calc internally as vectors of ASCII character codes -(@pxref{Strings}), this means vectors of strings are also sorted into -alphabetical order by this command. - -The @kbd{I V S} [@code{rsort}] command sorts a vector into decreasing order. - -@cindex Permutation, inverse of -@cindex Inverse of permutation -@cindex Index tables -@cindex Rank tables -@kindex v G -@kindex V G -@kindex I v G -@kindex I V G -@pindex calc-grade -@tindex grade -@tindex rgrade -The @kbd{V G} (@code{calc-grade}) [@code{grade}, @code{rgrade}] command -produces an index table or permutation vector which, if applied to the -input vector (as the index of @kbd{C-u v r}, say), would sort the vector. -A permutation vector is just a vector of integers from 1 to @var{n}, where -each integer occurs exactly once. One application of this is to sort a -matrix of data rows using one column as the sort key; extract that column, -grade it with @kbd{V G}, then use the result to reorder the original matrix -with @kbd{C-u v r}. Another interesting property of the @code{V G} command -is that, if the input is itself a permutation vector, the result will -be the inverse of the permutation. The inverse of an index table is -a rank table, whose @var{k}th element says where the @var{k}th original -vector element will rest when the vector is sorted. To get a rank -table, just use @kbd{V G V G}. - -With the Inverse flag, @kbd{I V G} produces an index table that would -sort the input into decreasing order. Note that @kbd{V S} and @kbd{V G} -use a ``stable'' sorting algorithm, i.e., any two elements which are equal -will not be moved out of their original order. Generally there is no way -to tell with @kbd{V S}, since two elements which are equal look the same, -but with @kbd{V G} this can be an important issue. In the matrix-of-rows -example, suppose you have names and telephone numbers as two columns and -you wish to sort by phone number primarily, and by name when the numbers -are equal. You can sort the data matrix by names first, and then again -by phone numbers. Because the sort is stable, any two rows with equal -phone numbers will remain sorted by name even after the second sort. - -@cindex Histograms -@kindex v H -@kindex V H -@pindex calc-histogram -@ignore -@mindex histo@idots -@end ignore -@tindex histogram -The @kbd{V H} (@code{calc-histogram}) [@code{histogram}] command builds a -histogram of a vector of numbers. Vector elements are assumed to be -integers or real numbers in the range [0..@var{n}) for some ``number of -bins'' @var{n}, which is the numeric prefix argument given to the -command. The result is a vector of @var{n} counts of how many times -each value appeared in the original vector. Non-integers in the input -are rounded down to integers. Any vector elements outside the specified -range are ignored. (You can tell if elements have been ignored by noting -that the counts in the result vector don't add up to the length of the -input vector.) - -If no prefix is given, then you will be prompted for a vector which -will be used to determine the bins. (If a positive integer is given at -this prompt, it will be still treated as if it were given as a -prefix.) Each bin will consist of the interval of numbers closest to -the corresponding number of this new vector; if the vector -@expr{[a, b, c, ...]} is entered at the prompt, the bins will be -@expr{(-inf, (a+b)/2]}, @expr{((a+b)/2, (b+c)/2]}, etc. The result of -this command will be a vector counting how many elements of the -original vector are in each bin. - -The result will then be a vector with the same length as this new vector; -each element of the new vector will be replaced by the number of -elements of the original vector which are closest to it. - -@kindex H v H -@kindex H V H -With the Hyperbolic flag, @kbd{H V H} pulls two vectors from the stack. -The second-to-top vector is the list of numbers as before. The top -vector is an equal-sized list of ``weights'' to attach to the elements -of the data vector. For example, if the first data element is 4.2 and -the first weight is 10, then 10 will be added to bin 4 of the result -vector. Without the hyperbolic flag, every element has a weight of one. - -@kindex v t -@kindex V t -@pindex calc-transpose -@tindex trn -The @kbd{v t} (@code{calc-transpose}) [@code{trn}] command computes -the transpose of the matrix at the top of the stack. If the argument -is a plain vector, it is treated as a row vector and transposed into -a one-column matrix. - -@kindex v v -@kindex V v -@pindex calc-reverse-vector -@tindex rev -The @kbd{v v} (@code{calc-reverse-vector}) [@code{rev}] command reverses -a vector end-for-end. Given a matrix, it reverses the order of the rows. -(To reverse the columns instead, just use @kbd{v t v v v t}. The same -principle can be used to apply other vector commands to the columns of -a matrix.) - -@kindex v m -@kindex V m -@pindex calc-mask-vector -@tindex vmask -The @kbd{v m} (@code{calc-mask-vector}) [@code{vmask}] command uses -one vector as a mask to extract elements of another vector. The mask -is in the second-to-top position; the target vector is on the top of -the stack. These vectors must have the same length. The result is -the same as the target vector, but with all elements which correspond -to zeros in the mask vector deleted. Thus, for example, -@samp{vmask([1, 0, 1, 0, 1], [a, b, c, d, e])} produces @samp{[a, c, e]}. -@xref{Logical Operations}. - -@kindex v e -@kindex V e -@pindex calc-expand-vector -@tindex vexp -The @kbd{v e} (@code{calc-expand-vector}) [@code{vexp}] command -expands a vector according to another mask vector. The result is a -vector the same length as the mask, but with nonzero elements replaced -by successive elements from the target vector. The length of the target -vector is normally the number of nonzero elements in the mask. If the -target vector is longer, its last few elements are lost. If the target -vector is shorter, the last few nonzero mask elements are left -unreplaced in the result. Thus @samp{vexp([2, 0, 3, 0, 7], [a, b])} -produces @samp{[a, 0, b, 0, 7]}. - -@kindex H v e -@kindex H V e -With the Hyperbolic flag, @kbd{H v e} takes a filler value from the -top of the stack; the mask and target vectors come from the third and -second elements of the stack. This filler is used where the mask is -zero: @samp{vexp([2, 0, 3, 0, 7], [a, b], z)} produces -@samp{[a, z, c, z, 7]}. If the filler value is itself a vector, -then successive values are taken from it, so that the effect is to -interleave two vectors according to the mask: -@samp{vexp([2, 0, 3, 7, 0, 0], [a, b], [x, y])} produces -@samp{[a, x, b, 7, y, 0]}. - -Another variation on the masking idea is to combine @samp{[a, b, c, d, e]} -with the mask @samp{[1, 0, 1, 0, 1]} to produce @samp{[a, 0, c, 0, e]}. -You can accomplish this with @kbd{V M a &}, mapping the logical ``and'' -operation across the two vectors. @xref{Logical Operations}. Note that -the @code{? :} operation also discussed there allows other types of -masking using vectors. - -@node Vector and Matrix Arithmetic, Set Operations, Manipulating Vectors, Matrix Functions -@section Vector and Matrix Arithmetic - -@noindent -Basic arithmetic operations like addition and multiplication are defined -for vectors and matrices as well as for numbers. Division of matrices, in -the sense of multiplying by the inverse, is supported. (Division by a -matrix actually uses LU-decomposition for greater accuracy and speed.) -@xref{Basic Arithmetic}. - -The following functions are applied element-wise if their arguments are -vectors or matrices: @code{change-sign}, @code{conj}, @code{arg}, -@code{re}, @code{im}, @code{polar}, @code{rect}, @code{clean}, -@code{float}, @code{frac}. @xref{Function Index}. - -@kindex v J -@kindex V J -@pindex calc-conj-transpose -@tindex ctrn -The @kbd{V J} (@code{calc-conj-transpose}) [@code{ctrn}] command computes -the conjugate transpose of its argument, i.e., @samp{conj(trn(x))}. - -@ignore -@mindex A -@end ignore -@kindex A (vectors) -@pindex calc-abs (vectors) -@ignore -@mindex abs -@end ignore -@tindex abs (vectors) -The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the -Frobenius norm of a vector or matrix argument. This is the square -root of the sum of the squares of the absolute values of the -elements of the vector or matrix. If the vector is interpreted as -a point in two- or three-dimensional space, this is the distance -from that point to the origin. - -@kindex v n -@kindex V n -@pindex calc-rnorm -@tindex rnorm -The @kbd{v n} (@code{calc-rnorm}) [@code{rnorm}] command computes the -infinity-norm of a vector, or the row norm of a matrix. For a plain -vector, this is the maximum of the absolute values of the elements. For -a matrix, this is the maximum of the row-absolute-value-sums, i.e., of -the sums of the absolute values of the elements along the various rows. - -@kindex v N -@kindex V N -@pindex calc-cnorm -@tindex cnorm -The @kbd{V N} (@code{calc-cnorm}) [@code{cnorm}] command computes -the one-norm of a vector, or column norm of a matrix. For a plain -vector, this is the sum of the absolute values of the elements. -For a matrix, this is the maximum of the column-absolute-value-sums. -General @expr{k}-norms for @expr{k} other than one or infinity are -not provided. However, the 2-norm (or Frobenius norm) is provided for -vectors by the @kbd{A} (@code{calc-abs}) command. - -@kindex v C -@kindex V C -@pindex calc-cross -@tindex cross -The @kbd{V C} (@code{calc-cross}) [@code{cross}] command computes the -right-handed cross product of two vectors, each of which must have -exactly three elements. - -@ignore -@mindex & -@end ignore -@kindex & (matrices) -@pindex calc-inv (matrices) -@ignore -@mindex inv -@end ignore -@tindex inv (matrices) -The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the -inverse of a square matrix. If the matrix is singular, the inverse -operation is left in symbolic form. Matrix inverses are recorded so -that once an inverse (or determinant) of a particular matrix has been -computed, the inverse and determinant of the matrix can be recomputed -quickly in the future. - -If the argument to @kbd{&} is a plain number @expr{x}, this -command simply computes @expr{1/x}. This is okay, because the -@samp{/} operator also does a matrix inversion when dividing one -by a matrix. - -@kindex v D -@kindex V D -@pindex calc-mdet -@tindex det -The @kbd{V D} (@code{calc-mdet}) [@code{det}] command computes the -determinant of a square matrix. - -@kindex v L -@kindex V L -@pindex calc-mlud -@tindex lud -The @kbd{V L} (@code{calc-mlud}) [@code{lud}] command computes the -LU decomposition of a matrix. The result is a list of three matrices -which, when multiplied together left-to-right, form the original matrix. -The first is a permutation matrix that arises from pivoting in the -algorithm, the second is lower-triangular with ones on the diagonal, -and the third is upper-triangular. - -@kindex v T -@kindex V T -@pindex calc-mtrace -@tindex tr -The @kbd{V T} (@code{calc-mtrace}) [@code{tr}] command computes the -trace of a square matrix. This is defined as the sum of the diagonal -elements of the matrix. - -@kindex v K -@kindex V K -@pindex calc-kron -@tindex kron -The @kbd{V K} (@code{calc-kron}) [@code{kron}] command computes -the Kronecker product of two matrices. - -@node Set Operations, Statistical Operations, Vector and Matrix Arithmetic, Matrix Functions -@section Set Operations using Vectors - -@noindent -@cindex Sets, as vectors -Calc includes several commands which interpret vectors as @dfn{sets} of -objects. A set is a collection of objects; any given object can appear -only once in the set. Calc stores sets as vectors of objects in -sorted order. Objects in a Calc set can be any of the usual things, -such as numbers, variables, or formulas. Two set elements are considered -equal if they are identical, except that numerically equal numbers like -the integer 4 and the float 4.0 are considered equal even though they -are not ``identical.'' Variables are treated like plain symbols without -attached values by the set operations; subtracting the set @samp{[b]} -from @samp{[a, b]} always yields the set @samp{[a]} even though if -the variables @samp{a} and @samp{b} both equaled 17, you might -expect the answer @samp{[]}. - -If a set contains interval forms, then it is assumed to be a set of -real numbers. In this case, all set operations require the elements -of the set to be only things that are allowed in intervals: Real -numbers, plus and minus infinity, HMS forms, and date forms. If -there are variables or other non-real objects present in a real set, -all set operations on it will be left in unevaluated form. - -If the input to a set operation is a plain number or interval form -@var{a}, it is treated like the one-element vector @samp{[@var{a}]}. -The result is always a vector, except that if the set consists of a -single interval, the interval itself is returned instead. - -@xref{Logical Operations}, for the @code{in} function which tests if -a certain value is a member of a given set. To test if the set @expr{A} -is a subset of the set @expr{B}, use @samp{vdiff(A, B) = []}. - -@kindex v + -@kindex V + -@pindex calc-remove-duplicates -@tindex rdup -The @kbd{V +} (@code{calc-remove-duplicates}) [@code{rdup}] command -converts an arbitrary vector into set notation. It works by sorting -the vector as if by @kbd{V S}, then removing duplicates. (For example, -@kbd{[a, 5, 4, a, 4.0]} is sorted to @samp{[4, 4.0, 5, a, a]} and then -reduced to @samp{[4, 5, a]}). Overlapping intervals are merged as -necessary. You rarely need to use @kbd{V +} explicitly, since all the -other set-based commands apply @kbd{V +} to their inputs before using -them. - -@kindex v V -@kindex V V -@pindex calc-set-union -@tindex vunion -The @kbd{V V} (@code{calc-set-union}) [@code{vunion}] command computes -the union of two sets. An object is in the union of two sets if and -only if it is in either (or both) of the input sets. (You could -accomplish the same thing by concatenating the sets with @kbd{|}, -then using @kbd{V +}.) - -@kindex v ^ -@kindex V ^ -@pindex calc-set-intersect -@tindex vint -The @kbd{V ^} (@code{calc-set-intersect}) [@code{vint}] command computes -the intersection of two sets. An object is in the intersection if -and only if it is in both of the input sets. Thus if the input -sets are disjoint, i.e., if they share no common elements, the result -will be the empty vector @samp{[]}. Note that the characters @kbd{V} -and @kbd{^} were chosen to be close to the conventional mathematical -notation for set -@texline union@tie{}(@math{A \cup B}) -@infoline union -and -@texline intersection@tie{}(@math{A \cap B}). -@infoline intersection. - -@kindex v - -@kindex V - -@pindex calc-set-difference -@tindex vdiff -The @kbd{V -} (@code{calc-set-difference}) [@code{vdiff}] command computes -the difference between two sets. An object is in the difference -@expr{A - B} if and only if it is in @expr{A} but not in @expr{B}. -Thus subtracting @samp{[y,z]} from a set will remove the elements -@samp{y} and @samp{z} if they are present. You can also think of this -as a general @dfn{set complement} operator; if @expr{A} is the set of -all possible values, then @expr{A - B} is the ``complement'' of @expr{B}. -Obviously this is only practical if the set of all possible values in -your problem is small enough to list in a Calc vector (or simple -enough to express in a few intervals). - -@kindex v X -@kindex V X -@pindex calc-set-xor -@tindex vxor -The @kbd{V X} (@code{calc-set-xor}) [@code{vxor}] command computes -the ``exclusive-or,'' or ``symmetric difference'' of two sets. -An object is in the symmetric difference of two sets if and only -if it is in one, but @emph{not} both, of the sets. Objects that -occur in both sets ``cancel out.'' - -@kindex v ~ -@kindex V ~ -@pindex calc-set-complement -@tindex vcompl -The @kbd{V ~} (@code{calc-set-complement}) [@code{vcompl}] command -computes the complement of a set with respect to the real numbers. -Thus @samp{vcompl(x)} is equivalent to @samp{vdiff([-inf .. inf], x)}. -For example, @samp{vcompl([2, (3 .. 4]])} evaluates to -@samp{[[-inf .. 2), (2 .. 3], (4 .. inf]]}. - -@kindex v F -@kindex V F -@pindex calc-set-floor -@tindex vfloor -The @kbd{V F} (@code{calc-set-floor}) [@code{vfloor}] command -reinterprets a set as a set of integers. Any non-integer values, -and intervals that do not enclose any integers, are removed. Open -intervals are converted to equivalent closed intervals. Successive -integers are converted into intervals of integers. For example, the -complement of the set @samp{[2, 6, 7, 8]} is messy, but if you wanted -the complement with respect to the set of integers you could type -@kbd{V ~ V F} to get @samp{[[-inf .. 1], [3 .. 5], [9 .. inf]]}. - -@kindex v E -@kindex V E -@pindex calc-set-enumerate -@tindex venum -The @kbd{V E} (@code{calc-set-enumerate}) [@code{venum}] command -converts a set of integers into an explicit vector. Intervals in -the set are expanded out to lists of all integers encompassed by -the intervals. This only works for finite sets (i.e., sets which -do not involve @samp{-inf} or @samp{inf}). - -@kindex v : -@kindex V : -@pindex calc-set-span -@tindex vspan -The @kbd{V :} (@code{calc-set-span}) [@code{vspan}] command converts any -set of reals into an interval form that encompasses all its elements. -The lower limit will be the smallest element in the set; the upper -limit will be the largest element. For an empty set, @samp{vspan([])} -returns the empty interval @w{@samp{[0 .. 0)}}. - -@kindex v # -@kindex V # -@pindex calc-set-cardinality -@tindex vcard -The @kbd{V #} (@code{calc-set-cardinality}) [@code{vcard}] command counts -the number of integers in a set. The result is the length of the vector -that would be produced by @kbd{V E}, although the computation is much -more efficient than actually producing that vector. - -@cindex Sets, as binary numbers -Another representation for sets that may be more appropriate in some -cases is binary numbers. If you are dealing with sets of integers -in the range 0 to 49, you can use a 50-bit binary number where a -particular bit is 1 if the corresponding element is in the set. -@xref{Binary Functions}, for a list of commands that operate on -binary numbers. Note that many of the above set operations have -direct equivalents in binary arithmetic: @kbd{b o} (@code{calc-or}), -@kbd{b a} (@code{calc-and}), @kbd{b d} (@code{calc-diff}), -@kbd{b x} (@code{calc-xor}), and @kbd{b n} (@code{calc-not}), -respectively. You can use whatever representation for sets is most -convenient to you. - -@kindex b p -@kindex b u -@pindex calc-pack-bits -@pindex calc-unpack-bits -@tindex vpack -@tindex vunpack -The @kbd{b u} (@code{calc-unpack-bits}) [@code{vunpack}] command -converts an integer that represents a set in binary into a set -in vector/interval notation. For example, @samp{vunpack(67)} -returns @samp{[[0 .. 1], 6]}. If the input is negative, the set -it represents is semi-infinite: @samp{vunpack(-4) = [2 .. inf)}. -Use @kbd{V E} afterwards to expand intervals to individual -values if you wish. Note that this command uses the @kbd{b} -(binary) prefix key. - -The @kbd{b p} (@code{calc-pack-bits}) [@code{vpack}] command -converts the other way, from a vector or interval representing -a set of nonnegative integers into a binary integer describing -the same set. The set may include positive infinity, but must -not include any negative numbers. The input is interpreted as a -set of integers in the sense of @kbd{V F} (@code{vfloor}). Beware -that a simple input like @samp{[100]} can result in a huge integer -representation -@texline (@math{2^{100}}, a 31-digit integer, in this case). -@infoline (@expr{2^100}, a 31-digit integer, in this case). - -@node Statistical Operations, Reducing and Mapping, Set Operations, Matrix Functions -@section Statistical Operations on Vectors - -@noindent -@cindex Statistical functions -The commands in this section take vectors as arguments and compute -various statistical measures on the data stored in the vectors. The -references used in the definitions of these functions are Bevington's -@emph{Data Reduction and Error Analysis for the Physical Sciences}, -and @emph{Numerical Recipes} by Press, Flannery, Teukolsky and -Vetterling. - -The statistical commands use the @kbd{u} prefix key followed by -a shifted letter or other character. - -@xref{Manipulating Vectors}, for a description of @kbd{V H} -(@code{calc-histogram}). - -@xref{Curve Fitting}, for the @kbd{a F} command for doing -least-squares fits to statistical data. - -@xref{Probability Distribution Functions}, for several common -probability distribution functions. - -@menu -* Single-Variable Statistics:: -* Paired-Sample Statistics:: -@end menu - -@node Single-Variable Statistics, Paired-Sample Statistics, Statistical Operations, Statistical Operations -@subsection Single-Variable Statistics - -@noindent -These functions do various statistical computations on single -vectors. Given a numeric prefix argument, they actually pop -@var{n} objects from the stack and combine them into a data -vector. Each object may be either a number or a vector; if a -vector, any sub-vectors inside it are ``flattened'' as if by -@kbd{v a 0}; @pxref{Manipulating Vectors}. By default one object -is popped, which (in order to be useful) is usually a vector. - -If an argument is a variable name, and the value stored in that -variable is a vector, then the stored vector is used. This method -has the advantage that if your data vector is large, you can avoid -the slow process of manipulating it directly on the stack. - -These functions are left in symbolic form if any of their arguments -are not numbers or vectors, e.g., if an argument is a formula, or -a non-vector variable. However, formulas embedded within vector -arguments are accepted; the result is a symbolic representation -of the computation, based on the assumption that the formula does -not itself represent a vector. All varieties of numbers such as -error forms and interval forms are acceptable. - -Some of the functions in this section also accept a single error form -or interval as an argument. They then describe a property of the -normal or uniform (respectively) statistical distribution described -by the argument. The arguments are interpreted in the same way as -the @var{M} argument of the random number function @kbd{k r}. In -particular, an interval with integer limits is considered an integer -distribution, so that @samp{[2 .. 6)} is the same as @samp{[2 .. 5]}. -An interval with at least one floating-point limit is a continuous -distribution: @samp{[2.0 .. 6.0)} is @emph{not} the same as -@samp{[2.0 .. 5.0]}! - -@kindex u # -@pindex calc-vector-count -@tindex vcount -The @kbd{u #} (@code{calc-vector-count}) [@code{vcount}] command -computes the number of data values represented by the inputs. -For example, @samp{vcount(1, [2, 3], [[4, 5], [], x, y])} returns 7. -If the argument is a single vector with no sub-vectors, this -simply computes the length of the vector. - -@kindex u + -@kindex u * -@pindex calc-vector-sum -@pindex calc-vector-prod -@tindex vsum -@tindex vprod -@cindex Summations (statistical) -The @kbd{u +} (@code{calc-vector-sum}) [@code{vsum}] command -computes the sum of the data values. The @kbd{u *} -(@code{calc-vector-prod}) [@code{vprod}] command computes the -product of the data values. If the input is a single flat vector, -these are the same as @kbd{V R +} and @kbd{V R *} -(@pxref{Reducing and Mapping}). - -@kindex u X -@kindex u N -@pindex calc-vector-max -@pindex calc-vector-min -@tindex vmax -@tindex vmin -The @kbd{u X} (@code{calc-vector-max}) [@code{vmax}] command -computes the maximum of the data values, and the @kbd{u N} -(@code{calc-vector-min}) [@code{vmin}] command computes the minimum. -If the argument is an interval, this finds the minimum or maximum -value in the interval. (Note that @samp{vmax([2..6)) = 5} as -described above.) If the argument is an error form, this returns -plus or minus infinity. - -@kindex u M -@pindex calc-vector-mean -@tindex vmean -@cindex Mean of data values -The @kbd{u M} (@code{calc-vector-mean}) [@code{vmean}] command -computes the average (arithmetic mean) of the data values. -If the inputs are error forms -@texline @math{x \pm \sigma}, -@infoline @samp{x +/- s}, -this is the weighted mean of the @expr{x} values with weights -@texline @math{1 /\sigma^2}. -@infoline @expr{1 / s^2}. -@tex -$$ \mu = { \displaystyle \sum { x_i \over \sigma_i^2 } \over - \displaystyle \sum { 1 \over \sigma_i^2 } } $$ -@end tex -If the inputs are not error forms, this is simply the sum of the -values divided by the count of the values. - -Note that a plain number can be considered an error form with -error -@texline @math{\sigma = 0}. -@infoline @expr{s = 0}. -If the input to @kbd{u M} is a mixture of -plain numbers and error forms, the result is the mean of the -plain numbers, ignoring all values with non-zero errors. (By the -above definitions it's clear that a plain number effectively -has an infinite weight, next to which an error form with a finite -weight is completely negligible.) - -This function also works for distributions (error forms or -intervals). The mean of an error form `@var{a} @tfn{+/-} @var{b}' is simply -@expr{a}. The mean of an interval is the mean of the minimum -and maximum values of the interval. - -@kindex I u M -@pindex calc-vector-mean-error -@tindex vmeane -The @kbd{I u M} (@code{calc-vector-mean-error}) [@code{vmeane}] -command computes the mean of the data points expressed as an -error form. This includes the estimated error associated with -the mean. If the inputs are error forms, the error is the square -root of the reciprocal of the sum of the reciprocals of the squares -of the input errors. (I.e., the variance is the reciprocal of the -sum of the reciprocals of the variances.) -@tex -$$ \sigma_\mu^2 = {1 \over \displaystyle \sum {1 \over \sigma_i^2}} $$ -@end tex -If the inputs are plain -numbers, the error is equal to the standard deviation of the values -divided by the square root of the number of values. (This works -out to be equivalent to calculating the standard deviation and -then assuming each value's error is equal to this standard -deviation.) -@tex -$$ \sigma_\mu^2 = {\sigma^2 \over N} $$ -@end tex - -@kindex H u M -@pindex calc-vector-median -@tindex vmedian -@cindex Median of data values -The @kbd{H u M} (@code{calc-vector-median}) [@code{vmedian}] -command computes the median of the data values. The values are -first sorted into numerical order; the median is the middle -value after sorting. (If the number of data values is even, -the median is taken to be the average of the two middle values.) -The median function is different from the other functions in -this section in that the arguments must all be real numbers; -variables are not accepted even when nested inside vectors. -(Otherwise it is not possible to sort the data values.) If -any of the input values are error forms, their error parts are -ignored. - -The median function also accepts distributions. For both normal -(error form) and uniform (interval) distributions, the median is -the same as the mean. - -@kindex H I u M -@pindex calc-vector-harmonic-mean -@tindex vhmean -@cindex Harmonic mean -The @kbd{H I u M} (@code{calc-vector-harmonic-mean}) [@code{vhmean}] -command computes the harmonic mean of the data values. This is -defined as the reciprocal of the arithmetic mean of the reciprocals -of the values. -@tex -$$ { N \over \displaystyle \sum {1 \over x_i} } $$ -@end tex - -@kindex u G -@pindex calc-vector-geometric-mean -@tindex vgmean -@cindex Geometric mean -The @kbd{u G} (@code{calc-vector-geometric-mean}) [@code{vgmean}] -command computes the geometric mean of the data values. This -is the @var{n}th root of the product of the values. This is also -equal to the @code{exp} of the arithmetic mean of the logarithms -of the data values. -@tex -$$ \exp \left ( \sum { \ln x_i } \right ) = - \left ( \prod { x_i } \right)^{1 / N} $$ -@end tex - -@kindex H u G -@tindex agmean -The @kbd{H u G} [@code{agmean}] command computes the ``arithmetic-geometric -mean'' of two numbers taken from the stack. This is computed by -replacing the two numbers with their arithmetic mean and geometric -mean, then repeating until the two values converge. -@tex -$$ a_{i+1} = { a_i + b_i \over 2 } , \qquad b_{i+1} = \sqrt{a_i b_i} $$ -@end tex - -@cindex Root-mean-square -Another commonly used mean, the RMS (root-mean-square), can be computed -for a vector of numbers simply by using the @kbd{A} command. - -@kindex u S -@pindex calc-vector-sdev -@tindex vsdev -@cindex Standard deviation -@cindex Sample statistics -The @kbd{u S} (@code{calc-vector-sdev}) [@code{vsdev}] command -computes the standard -@texline deviation@tie{}@math{\sigma} -@infoline deviation -of the data values. If the values are error forms, the errors are used -as weights just as for @kbd{u M}. This is the @emph{sample} standard -deviation, whose value is the square root of the sum of the squares of -the differences between the values and the mean of the @expr{N} values, -divided by @expr{N-1}. -@tex -$$ \sigma^2 = {1 \over N - 1} \sum (x_i - \mu)^2 $$ -@end tex - -This function also applies to distributions. The standard deviation -of a single error form is simply the error part. The standard deviation -of a continuous interval happens to equal the difference between the -limits, divided by -@texline @math{\sqrt{12}}. -@infoline @expr{sqrt(12)}. -The standard deviation of an integer interval is the same as the -standard deviation of a vector of those integers. - -@kindex I u S -@pindex calc-vector-pop-sdev -@tindex vpsdev -@cindex Population statistics -The @kbd{I u S} (@code{calc-vector-pop-sdev}) [@code{vpsdev}] -command computes the @emph{population} standard deviation. -It is defined by the same formula as above but dividing -by @expr{N} instead of by @expr{N-1}. The population standard -deviation is used when the input represents the entire set of -data values in the distribution; the sample standard deviation -is used when the input represents a sample of the set of all -data values, so that the mean computed from the input is itself -only an estimate of the true mean. -@tex -$$ \sigma^2 = {1 \over N} \sum (x_i - \mu)^2 $$ -@end tex - -For error forms and continuous intervals, @code{vpsdev} works -exactly like @code{vsdev}. For integer intervals, it computes the -population standard deviation of the equivalent vector of integers. - -@kindex H u S -@kindex H I u S -@pindex calc-vector-variance -@pindex calc-vector-pop-variance -@tindex vvar -@tindex vpvar -@cindex Variance of data values -The @kbd{H u S} (@code{calc-vector-variance}) [@code{vvar}] and -@kbd{H I u S} (@code{calc-vector-pop-variance}) [@code{vpvar}] -commands compute the variance of the data values. The variance -is the -@texline square@tie{}@math{\sigma^2} -@infoline square -of the standard deviation, i.e., the sum of the -squares of the deviations of the data values from the mean. -(This definition also applies when the argument is a distribution.) - -@ignore -@starindex -@end ignore -@tindex vflat -The @code{vflat} algebraic function returns a vector of its -arguments, interpreted in the same way as the other functions -in this section. For example, @samp{vflat(1, [2, [3, 4]], 5)} -returns @samp{[1, 2, 3, 4, 5]}. - -@node Paired-Sample Statistics, , Single-Variable Statistics, Statistical Operations -@subsection Paired-Sample Statistics - -@noindent -The functions in this section take two arguments, which must be -vectors of equal size. The vectors are each flattened in the same -way as by the single-variable statistical functions. Given a numeric -prefix argument of 1, these functions instead take one object from -the stack, which must be an -@texline @math{N\times2} -@infoline Nx2 -matrix of data values. Once again, variable names can be used in place -of actual vectors and matrices. - -@kindex u C -@pindex calc-vector-covariance -@tindex vcov -@cindex Covariance -The @kbd{u C} (@code{calc-vector-covariance}) [@code{vcov}] command -computes the sample covariance of two vectors. The covariance -of vectors @var{x} and @var{y} is the sum of the products of the -differences between the elements of @var{x} and the mean of @var{x} -times the differences between the corresponding elements of @var{y} -and the mean of @var{y}, all divided by @expr{N-1}. Note that -the variance of a vector is just the covariance of the vector -with itself. Once again, if the inputs are error forms the -errors are used as weight factors. If both @var{x} and @var{y} -are composed of error forms, the error for a given data point -is taken as the square root of the sum of the squares of the two -input errors. -@tex -$$ \sigma_{x\!y}^2 = {1 \over N-1} \sum (x_i - \mu_x) (y_i - \mu_y) $$ -$$ \sigma_{x\!y}^2 = - {\displaystyle {1 \over N-1} - \sum {(x_i - \mu_x) (y_i - \mu_y) \over \sigma_i^2} - \over \displaystyle {1 \over N} \sum {1 \over \sigma_i^2}} -$$ -@end tex - -@kindex I u C -@pindex calc-vector-pop-covariance -@tindex vpcov -The @kbd{I u C} (@code{calc-vector-pop-covariance}) [@code{vpcov}] -command computes the population covariance, which is the same as the -sample covariance computed by @kbd{u C} except dividing by @expr{N} -instead of @expr{N-1}. - -@kindex H u C -@pindex calc-vector-correlation -@tindex vcorr -@cindex Correlation coefficient -@cindex Linear correlation -The @kbd{H u C} (@code{calc-vector-correlation}) [@code{vcorr}] -command computes the linear correlation coefficient of two vectors. -This is defined by the covariance of the vectors divided by the -product of their standard deviations. (There is no difference -between sample or population statistics here.) -@tex -$$ r_{x\!y} = { \sigma_{x\!y}^2 \over \sigma_x^2 \sigma_y^2 } $$ -@end tex - -@node Reducing and Mapping, Vector and Matrix Formats, Statistical Operations, Matrix Functions -@section Reducing and Mapping Vectors - -@noindent -The commands in this section allow for more general operations on the -elements of vectors. - -@kindex v A -@kindex V A -@pindex calc-apply -@tindex apply -The simplest of these operations is @kbd{V A} (@code{calc-apply}) -[@code{apply}], which applies a given operator to the elements of a vector. -For example, applying the hypothetical function @code{f} to the vector -@w{@samp{[1, 2, 3]}} would produce the function call @samp{f(1, 2, 3)}. -Applying the @code{+} function to the vector @samp{[a, b]} gives -@samp{a + b}. Applying @code{+} to the vector @samp{[a, b, c]} is an -error, since the @code{+} function expects exactly two arguments. - -While @kbd{V A} is useful in some cases, you will usually find that either -@kbd{V R} or @kbd{V M}, described below, is closer to what you want. - -@menu -* Specifying Operators:: -* Mapping:: -* Reducing:: -* Nesting and Fixed Points:: -* Generalized Products:: -@end menu - -@node Specifying Operators, Mapping, Reducing and Mapping, Reducing and Mapping -@subsection Specifying Operators - -@noindent -Commands in this section (like @kbd{V A}) prompt you to press the key -corresponding to the desired operator. Press @kbd{?} for a partial -list of the available operators. Generally, an operator is any key or -sequence of keys that would normally take one or more arguments from -the stack and replace them with a result. For example, @kbd{V A H C} -uses the hyperbolic cosine operator, @code{cosh}. (Since @code{cosh} -expects one argument, @kbd{V A H C} requires a vector with a single -element as its argument.) - -You can press @kbd{x} at the operator prompt to select any algebraic -function by name to use as the operator. This includes functions you -have defined yourself using the @kbd{Z F} command. (@xref{Algebraic -Definitions}.) If you give a name for which no function has been -defined, the result is left in symbolic form, as in @samp{f(1, 2, 3)}. -Calc will prompt for the number of arguments the function takes if it -can't figure it out on its own (say, because you named a function that -is currently undefined). It is also possible to type a digit key before -the function name to specify the number of arguments, e.g., -@kbd{V M 3 x f @key{RET}} calls @code{f} with three arguments even if it -looks like it ought to have only two. This technique may be necessary -if the function allows a variable number of arguments. For example, -the @kbd{v e} [@code{vexp}] function accepts two or three arguments; -if you want to map with the three-argument version, you will have to -type @kbd{V M 3 v e}. - -It is also possible to apply any formula to a vector by treating that -formula as a function. When prompted for the operator to use, press -@kbd{'} (the apostrophe) and type your formula as an algebraic entry. -You will then be prompted for the argument list, which defaults to a -list of all variables that appear in the formula, sorted into alphabetic -order. For example, suppose you enter the formula @w{@samp{x + 2y^x}}. -The default argument list would be @samp{(x y)}, which means that if -this function is applied to the arguments @samp{[3, 10]} the result will -be @samp{3 + 2*10^3}. (If you plan to use a certain formula in this -way often, you might consider defining it as a function with @kbd{Z F}.) - -Another way to specify the arguments to the formula you enter is with -@kbd{$}, @kbd{$$}, and so on. For example, @kbd{V A ' $$ + 2$^$$} -has the same effect as the previous example. The argument list is -automatically taken to be @samp{($$ $)}. (The order of the arguments -may seem backwards, but it is analogous to the way normal algebraic -entry interacts with the stack.) - -If you press @kbd{$} at the operator prompt, the effect is similar to -the apostrophe except that the relevant formula is taken from top-of-stack -instead. The actual vector arguments of the @kbd{V A $} or related command -then start at the second-to-top stack position. You will still be -prompted for an argument list. - -@cindex Nameless functions -@cindex Generic functions -A function can be written without a name using the notation @samp{<#1 - #2>}, -which means ``a function of two arguments that computes the first -argument minus the second argument.'' The symbols @samp{#1} and @samp{#2} -are placeholders for the arguments. You can use any names for these -placeholders if you wish, by including an argument list followed by a -colon: @samp{}. When you type @kbd{V A ' $$ + 2$^$$ @key{RET}}, -Calc builds the nameless function @samp{<#1 + 2 #2^#1>} as the function -to map across the vectors. When you type @kbd{V A ' x + 2y^x @key{RET} @key{RET}}, -Calc builds the nameless function @w{@samp{}}. In both -cases, Calc also writes the nameless function to the Trail so that you -can get it back later if you wish. - -If there is only one argument, you can write @samp{#} in place of @samp{#1}. -(Note that @samp{< >} notation is also used for date forms. Calc tells -that @samp{<@var{stuff}>} is a nameless function by the presence of -@samp{#} signs inside @var{stuff}, or by the fact that @var{stuff} -begins with a list of variables followed by a colon.) - -You can type a nameless function directly to @kbd{V A '}, or put one on -the stack and use it with @w{@kbd{V A $}}. Calc will not prompt for an -argument list in this case, since the nameless function specifies the -argument list as well as the function itself. In @kbd{V A '}, you can -omit the @samp{< >} marks if you use @samp{#} notation for the arguments, -so that @kbd{V A ' #1+#2 @key{RET}} is the same as @kbd{V A ' <#1+#2> @key{RET}}, -which in turn is the same as @kbd{V A ' $$+$ @key{RET}}. - -@cindex Lambda expressions -@ignore -@starindex -@end ignore -@tindex lambda -The internal format for @samp{} is @samp{lambda(x, y, x + y)}. -(The word @code{lambda} derives from Lisp notation and the theory of -functions.) The internal format for @samp{<#1 + #2>} is @samp{lambda(ArgA, -ArgB, ArgA + ArgB)}. Note that there is no actual Calc function called -@code{lambda}; the whole point is that the @code{lambda} expression is -used in its symbolic form, not evaluated for an answer until it is applied -to specific arguments by a command like @kbd{V A} or @kbd{V M}. - -(Actually, @code{lambda} does have one special property: Its arguments -are never evaluated; for example, putting @samp{<(2/3) #>} on the stack -will not simplify the @samp{2/3} until the nameless function is actually -called.) - -@tindex add -@tindex sub -@ignore -@mindex @idots -@end ignore -@tindex mul -@ignore -@mindex @null -@end ignore -@tindex div -@ignore -@mindex @null -@end ignore -@tindex pow -@ignore -@mindex @null -@end ignore -@tindex neg -@ignore -@mindex @null -@end ignore -@tindex mod -@ignore -@mindex @null -@end ignore -@tindex vconcat -As usual, commands like @kbd{V A} have algebraic function name equivalents. -For example, @kbd{V A k g} with an argument of @samp{v} is equivalent to -@samp{apply(gcd, v)}. The first argument specifies the operator name, -and is either a variable whose name is the same as the function name, -or a nameless function like @samp{<#^3+1>}. Operators that are normally -written as algebraic symbols have the names @code{add}, @code{sub}, -@code{mul}, @code{div}, @code{pow}, @code{neg}, @code{mod}, and -@code{vconcat}. - -@ignore -@starindex -@end ignore -@tindex call -The @code{call} function builds a function call out of several arguments: -@samp{call(gcd, x, y)} is the same as @samp{apply(gcd, [x, y])}, which -in turn is the same as @samp{gcd(x, y)}. The first argument of @code{call}, -like the other functions described here, may be either a variable naming a -function, or a nameless function (@samp{call(<#1+2#2>, x, y)} is the same -as @samp{x + 2y}). - -(Experts will notice that it's not quite proper to use a variable to name -a function, since the name @code{gcd} corresponds to the Lisp variable -@code{var-gcd} but to the Lisp function @code{calcFunc-gcd}. Calc -automatically makes this translation, so you don't have to worry -about it.) - -@node Mapping, Reducing, Specifying Operators, Reducing and Mapping -@subsection Mapping - -@noindent -@kindex v M -@kindex V M -@pindex calc-map -@tindex map -The @kbd{V M} (@code{calc-map}) [@code{map}] command applies a given -operator elementwise to one or more vectors. For example, mapping -@code{A} [@code{abs}] produces a vector of the absolute values of the -elements in the input vector. Mapping @code{+} pops two vectors from -the stack, which must be of equal length, and produces a vector of the -pairwise sums of the elements. If either argument is a non-vector, it -is duplicated for each element of the other vector. For example, -@kbd{[1,2,3] 2 V M ^} squares the elements of the specified vector. -With the 2 listed first, it would have computed a vector of powers of -two. Mapping a user-defined function pops as many arguments from the -stack as the function requires. If you give an undefined name, you will -be prompted for the number of arguments to use. - -If any argument to @kbd{V M} is a matrix, the operator is normally mapped -across all elements of the matrix. For example, given the matrix -@expr{[[1, -2, 3], [-4, 5, -6]]}, @kbd{V M A} takes six absolute values to -produce another -@texline @math{3\times2} -@infoline 3x2 -matrix, @expr{[[1, 2, 3], [4, 5, 6]]}. - -@tindex mapr -The command @kbd{V M _} [@code{mapr}] (i.e., type an underscore at the -operator prompt) maps by rows instead. For example, @kbd{V M _ A} views -the above matrix as a vector of two 3-element row vectors. It produces -a new vector which contains the absolute values of those row vectors, -namely @expr{[3.74, 8.77]}. (Recall, the absolute value of a vector is -defined as the square root of the sum of the squares of the elements.) -Some operators accept vectors and return new vectors; for example, -@kbd{v v} reverses a vector, so @kbd{V M _ v v} would reverse each row -of the matrix to get a new matrix, @expr{[[3, -2, 1], [-6, 5, -4]]}. - -Sometimes a vector of vectors (representing, say, strings, sets, or lists) -happens to look like a matrix. If so, remember to use @kbd{V M _} if you -want to map a function across the whole strings or sets rather than across -their individual elements. - -@tindex mapc -The command @kbd{V M :} [@code{mapc}] maps by columns. Basically, it -transposes the input matrix, maps by rows, and then, if the result is a -matrix, transposes again. For example, @kbd{V M : A} takes the absolute -values of the three columns of the matrix, treating each as a 2-vector, -and @kbd{V M : v v} reverses the columns to get the matrix -@expr{[[-4, 5, -6], [1, -2, 3]]}. - -(The symbols @kbd{_} and @kbd{:} were chosen because they had row-like -and column-like appearances, and were not already taken by useful -operators. Also, they appear shifted on most keyboards so they are easy -to type after @kbd{V M}.) - -The @kbd{_} and @kbd{:} modifiers have no effect on arguments that are -not matrices (so if none of the arguments are matrices, they have no -effect at all). If some of the arguments are matrices and others are -plain numbers, the plain numbers are held constant for all rows of the -matrix (so that @kbd{2 V M _ ^} squares every row of a matrix; squaring -a vector takes a dot product of the vector with itself). - -If some of the arguments are vectors with the same lengths as the -rows (for @kbd{V M _}) or columns (for @kbd{V M :}) of the matrix -arguments, those vectors are also held constant for every row or -column. - -Sometimes it is useful to specify another mapping command as the operator -to use with @kbd{V M}. For example, @kbd{V M _ V A +} applies @kbd{V A +} -to each row of the input matrix, which in turn adds the two values on that -row. If you give another vector-operator command as the operator for -@kbd{V M}, it automatically uses map-by-rows mode if you don't specify -otherwise; thus @kbd{V M V A +} is equivalent to @kbd{V M _ V A +}. (If -you really want to map-by-elements another mapping command, you can use -a triple-nested mapping command: @kbd{V M V M V A +} means to map -@kbd{V M V A +} over the rows of the matrix; in turn, @kbd{V A +} is -mapped over the elements of each row.) - -@tindex mapa -@tindex mapd -Previous versions of Calc had ``map across'' and ``map down'' modes -that are now considered obsolete; the old ``map across'' is now simply -@kbd{V M V A}, and ``map down'' is now @kbd{V M : V A}. The algebraic -functions @code{mapa} and @code{mapd} are still supported, though. -Note also that, while the old mapping modes were persistent (once you -set the mode, it would apply to later mapping commands until you reset -it), the new @kbd{:} and @kbd{_} modifiers apply only to the current -mapping command. The default @kbd{V M} always means map-by-elements. - -@xref{Algebraic Manipulation}, for the @kbd{a M} command, which is like -@kbd{V M} but for equations and inequalities instead of vectors. -@xref{Storing Variables}, for the @kbd{s m} command which modifies a -variable's stored value using a @kbd{V M}-like operator. - -@node Reducing, Nesting and Fixed Points, Mapping, Reducing and Mapping -@subsection Reducing - -@noindent -@kindex v R -@kindex V R -@pindex calc-reduce -@tindex reduce -The @kbd{V R} (@code{calc-reduce}) [@code{reduce}] command applies a given -binary operator across all the elements of a vector. A binary operator is -a function such as @code{+} or @code{max} which takes two arguments. For -example, reducing @code{+} over a vector computes the sum of the elements -of the vector. Reducing @code{-} computes the first element minus each of -the remaining elements. Reducing @code{max} computes the maximum element -and so on. In general, reducing @code{f} over the vector @samp{[a, b, c, d]} -produces @samp{f(f(f(a, b), c), d)}. - -@kindex I v R -@kindex I V R -@tindex rreduce -The @kbd{I V R} [@code{rreduce}] command is similar to @kbd{V R} except -that works from right to left through the vector. For example, plain -@kbd{V R -} on the vector @samp{[a, b, c, d]} produces @samp{a - b - c - d} -but @kbd{I V R -} on the same vector produces @samp{a - (b - (c - d))}, -or @samp{a - b + c - d}. This ``alternating sum'' occurs frequently -in power series expansions. - -@kindex v U -@kindex V U -@tindex accum -The @kbd{V U} (@code{calc-accumulate}) [@code{accum}] command does an -accumulation operation. Here Calc does the corresponding reduction -operation, but instead of producing only the final result, it produces -a vector of all the intermediate results. Accumulating @code{+} over -the vector @samp{[a, b, c, d]} produces the vector -@samp{[a, a + b, a + b + c, a + b + c + d]}. - -@kindex I v U -@kindex I V U -@tindex raccum -The @kbd{I V U} [@code{raccum}] command does a right-to-left accumulation. -For example, @kbd{I V U -} on the vector @samp{[a, b, c, d]} produces the -vector @samp{[a - b + c - d, b - c + d, c - d, d]}. - -@tindex reducea -@tindex rreducea -@tindex reduced -@tindex rreduced -As for @kbd{V M}, @kbd{V R} normally reduces a matrix elementwise. For -example, given the matrix @expr{[[a, b, c], [d, e, f]]}, @kbd{V R +} will -compute @expr{a + b + c + d + e + f}. You can type @kbd{V R _} or -@kbd{V R :} to modify this behavior. The @kbd{V R _} [@code{reducea}] -command reduces ``across'' the matrix; it reduces each row of the matrix -as a vector, then collects the results. Thus @kbd{V R _ +} of this -matrix would produce @expr{[a + b + c, d + e + f]}. Similarly, @kbd{V R :} -[@code{reduced}] reduces down; @kbd{V R : +} would produce @expr{[a + d, -b + e, c + f]}. - -@tindex reducer -@tindex rreducer -There is a third ``by rows'' mode for reduction that is occasionally -useful; @kbd{V R =} [@code{reducer}] simply reduces the operator over -the rows of the matrix themselves. Thus @kbd{V R = +} on the above -matrix would get the same result as @kbd{V R : +}, since adding two -row vectors is equivalent to adding their elements. But @kbd{V R = *} -would multiply the two rows (to get a single number, their dot product), -while @kbd{V R : *} would produce a vector of the products of the columns. - -These three matrix reduction modes work with @kbd{V R} and @kbd{I V R}, -but they are not currently supported with @kbd{V U} or @kbd{I V U}. - -@tindex reducec -@tindex rreducec -The obsolete reduce-by-columns function, @code{reducec}, is still -supported but there is no way to get it through the @kbd{V R} command. - -The commands @kbd{C-x * :} and @kbd{C-x * _} are equivalent to typing -@kbd{C-x * r} to grab a rectangle of data into Calc, and then typing -@kbd{V R : +} or @kbd{V R _ +}, respectively, to sum the columns or -rows of the matrix. @xref{Grabbing From Buffers}. - -@node Nesting and Fixed Points, Generalized Products, Reducing, Reducing and Mapping -@subsection Nesting and Fixed Points - -@noindent -@kindex H v R -@kindex H V R -@tindex nest -The @kbd{H V R} [@code{nest}] command applies a function to a given -argument repeatedly. It takes two values, @samp{a} and @samp{n}, from -the stack, where @samp{n} must be an integer. It then applies the -function nested @samp{n} times; if the function is @samp{f} and @samp{n} -is 3, the result is @samp{f(f(f(a)))}. The number @samp{n} may be -negative if Calc knows an inverse for the function @samp{f}; for -example, @samp{nest(sin, a, -2)} returns @samp{arcsin(arcsin(a))}. - -@kindex H v U -@kindex H V U -@tindex anest -The @kbd{H V U} [@code{anest}] command is an accumulating version of -@code{nest}: It returns a vector of @samp{n+1} values, e.g., -@samp{[a, f(a), f(f(a)), f(f(f(a)))]}. If @samp{n} is negative and -@samp{F} is the inverse of @samp{f}, then the result is of the -form @samp{[a, F(a), F(F(a)), F(F(F(a)))]}. - -@kindex H I v R -@kindex H I V R -@tindex fixp -@cindex Fixed points -The @kbd{H I V R} [@code{fixp}] command is like @kbd{H V R}, except -that it takes only an @samp{a} value from the stack; the function is -applied until it reaches a ``fixed point,'' i.e., until the result -no longer changes. - -@kindex H I v U -@kindex H I V U -@tindex afixp -The @kbd{H I V U} [@code{afixp}] command is an accumulating @code{fixp}. -The first element of the return vector will be the initial value @samp{a}; -the last element will be the final result that would have been returned -by @code{fixp}. - -For example, 0.739085 is a fixed point of the cosine function (in radians): -@samp{cos(0.739085) = 0.739085}. You can find this value by putting, say, -1.0 on the stack and typing @kbd{H I V U C}. (We use the accumulating -version so we can see the intermediate results: @samp{[1, 0.540302, 0.857553, -0.65329, ...]}. With a precision of six, this command will take 36 steps -to converge to 0.739085.) - -Newton's method for finding roots is a classic example of iteration -to a fixed point. To find the square root of five starting with an -initial guess, Newton's method would look for a fixed point of the -function @samp{(x + 5/x) / 2}. Putting a guess of 1 on the stack -and typing @kbd{H I V R ' ($ + 5/$)/2 @key{RET}} quickly yields the result -2.23607. This is equivalent to using the @kbd{a R} (@code{calc-find-root}) -command to find a root of the equation @samp{x^2 = 5}. - -These examples used numbers for @samp{a} values. Calc keeps applying -the function until two successive results are equal to within the -current precision. For complex numbers, both the real parts and the -imaginary parts must be equal to within the current precision. If -@samp{a} is a formula (say, a variable name), then the function is -applied until two successive results are exactly the same formula. -It is up to you to ensure that the function will eventually converge; -if it doesn't, you may have to press @kbd{C-g} to stop the Calculator. - -The algebraic @code{fixp} function takes two optional arguments, @samp{n} -and @samp{tol}. The first is the maximum number of steps to be allowed, -and must be either an integer or the symbol @samp{inf} (infinity, the -default). The second is a convergence tolerance. If a tolerance is -specified, all results during the calculation must be numbers, not -formulas, and the iteration stops when the magnitude of the difference -between two successive results is less than or equal to the tolerance. -(This implies that a tolerance of zero iterates until the results are -exactly equal.) - -Putting it all together, @samp{fixp(<(# + A/#)/2>, B, 20, 1e-10)} -computes the square root of @samp{A} given the initial guess @samp{B}, -stopping when the result is correct within the specified tolerance, or -when 20 steps have been taken, whichever is sooner. - -@node Generalized Products, , Nesting and Fixed Points, Reducing and Mapping -@subsection Generalized Products - -@kindex v O -@kindex V O -@pindex calc-outer-product -@tindex outer -The @kbd{V O} (@code{calc-outer-product}) [@code{outer}] command applies -a given binary operator to all possible pairs of elements from two -vectors, to produce a matrix. For example, @kbd{V O *} with @samp{[a, b]} -and @samp{[x, y, z]} on the stack produces a multiplication table: -@samp{[[a x, a y, a z], [b x, b y, b z]]}. Element @var{r},@var{c} of -the result matrix is obtained by applying the operator to element @var{r} -of the lefthand vector and element @var{c} of the righthand vector. - -@kindex v I -@kindex V I -@pindex calc-inner-product -@tindex inner -The @kbd{V I} (@code{calc-inner-product}) [@code{inner}] command computes -the generalized inner product of two vectors or matrices, given a -``multiplicative'' operator and an ``additive'' operator. These can each -actually be any binary operators; if they are @samp{*} and @samp{+}, -respectively, the result is a standard matrix multiplication. Element -@var{r},@var{c} of the result matrix is obtained by mapping the -multiplicative operator across row @var{r} of the lefthand matrix and -column @var{c} of the righthand matrix, and then reducing with the additive -operator. Just as for the standard @kbd{*} command, this can also do a -vector-matrix or matrix-vector inner product, or a vector-vector -generalized dot product. - -Since @kbd{V I} requires two operators, it prompts twice. In each case, -you can use any of the usual methods for entering the operator. If you -use @kbd{$} twice to take both operator formulas from the stack, the -first (multiplicative) operator is taken from the top of the stack -and the second (additive) operator is taken from second-to-top. - -@node Vector and Matrix Formats, , Reducing and Mapping, Matrix Functions -@section Vector and Matrix Display Formats - -@noindent -Commands for controlling vector and matrix display use the @kbd{v} prefix -instead of the usual @kbd{d} prefix. But they are display modes; in -particular, they are influenced by the @kbd{I} and @kbd{H} prefix keys -in the same way (@pxref{Display Modes}). Matrix display is also -influenced by the @kbd{d O} (@code{calc-flat-language}) mode; -@pxref{Normal Language Modes}. - -@kindex v < -@kindex V < -@pindex calc-matrix-left-justify -@kindex v = -@kindex V = -@pindex calc-matrix-center-justify -@kindex v > -@kindex V > -@pindex calc-matrix-right-justify -The commands @kbd{v <} (@code{calc-matrix-left-justify}), @kbd{v >} -(@code{calc-matrix-right-justify}), and @w{@kbd{v =}} -(@code{calc-matrix-center-justify}) control whether matrix elements -are justified to the left, right, or center of their columns. - -@kindex v [ -@kindex V [ -@pindex calc-vector-brackets -@kindex v @{ -@kindex V @{ -@pindex calc-vector-braces -@kindex v ( -@kindex V ( -@pindex calc-vector-parens -The @kbd{v [} (@code{calc-vector-brackets}) command turns the square -brackets that surround vectors and matrices displayed in the stack on -and off. The @kbd{v @{} (@code{calc-vector-braces}) and @kbd{v (} -(@code{calc-vector-parens}) commands use curly braces or parentheses, -respectively, instead of square brackets. For example, @kbd{v @{} might -be used in preparation for yanking a matrix into a buffer running -Mathematica. (In fact, the Mathematica language mode uses this mode; -@pxref{Mathematica Language Mode}.) Note that, regardless of the -display mode, either brackets or braces may be used to enter vectors, -and parentheses may never be used for this purpose. - -@kindex V ] -@kindex v ] -@kindex V ) -@kindex v ) -@kindex V @} -@kindex v @} -@pindex calc-matrix-brackets -The @kbd{v ]} (@code{calc-matrix-brackets}) command controls the -``big'' style display of matrices, for matrices which have more than -one row. It prompts for a string of code letters; currently -implemented letters are @code{R}, which enables brackets on each row -of the matrix; @code{O}, which enables outer brackets in opposite -corners of the matrix; and @code{C}, which enables commas or -semicolons at the ends of all rows but the last. The default format -is @samp{RO}. (Before Calc 2.00, the format was fixed at @samp{ROC}.) -Here are some example matrices: - -@example -@group -[ [ 123, 0, 0 ] [ [ 123, 0, 0 ], - [ 0, 123, 0 ] [ 0, 123, 0 ], - [ 0, 0, 123 ] ] [ 0, 0, 123 ] ] - - RO ROC - -@end group -@end example -@noindent -@example -@group - [ 123, 0, 0 [ 123, 0, 0 ; - 0, 123, 0 0, 123, 0 ; - 0, 0, 123 ] 0, 0, 123 ] - - O OC - -@end group -@end example -@noindent -@example -@group - [ 123, 0, 0 ] 123, 0, 0 - [ 0, 123, 0 ] 0, 123, 0 - [ 0, 0, 123 ] 0, 0, 123 - - R @r{blank} -@end group -@end example - -@noindent -Note that of the formats shown here, @samp{RO}, @samp{ROC}, and -@samp{OC} are all recognized as matrices during reading, while -the others are useful for display only. - -@kindex v , -@kindex V , -@pindex calc-vector-commas -The @kbd{v ,} (@code{calc-vector-commas}) command turns commas on and -off in vector and matrix display. - -In vectors of length one, and in all vectors when commas have been -turned off, Calc adds extra parentheses around formulas that might -otherwise be ambiguous. For example, @samp{[a b]} could be a vector -of the one formula @samp{a b}, or it could be a vector of two -variables with commas turned off. Calc will display the former -case as @samp{[(a b)]}. You can disable these extra parentheses -(to make the output less cluttered at the expense of allowing some -ambiguity) by adding the letter @code{P} to the control string you -give to @kbd{v ]} (as described above). - -@kindex v . -@kindex V . -@pindex calc-full-vectors -The @kbd{v .} (@code{calc-full-vectors}) command turns abbreviated -display of long vectors on and off. In this mode, vectors of six -or more elements, or matrices of six or more rows or columns, will -be displayed in an abbreviated form that displays only the first -three elements and the last element: @samp{[a, b, c, ..., z]}. -When very large vectors are involved this will substantially -improve Calc's display speed. - -@kindex t . -@pindex calc-full-trail-vectors -The @kbd{t .} (@code{calc-full-trail-vectors}) command controls a -similar mode for recording vectors in the Trail. If you turn on -this mode, vectors of six or more elements and matrices of six or -more rows or columns will be abbreviated when they are put in the -Trail. The @kbd{t y} (@code{calc-trail-yank}) command will be -unable to recover those vectors. If you are working with very -large vectors, this mode will improve the speed of all operations -that involve the trail. - -@kindex v / -@kindex V / -@pindex calc-break-vectors -The @kbd{v /} (@code{calc-break-vectors}) command turns multi-line -vector display on and off. Normally, matrices are displayed with one -row per line but all other types of vectors are displayed in a single -line. This mode causes all vectors, whether matrices or not, to be -displayed with a single element per line. Sub-vectors within the -vectors will still use the normal linear form. - -@node Algebra, Units, Matrix Functions, Top -@chapter Algebra - -@noindent -This section covers the Calc features that help you work with -algebraic formulas. First, the general sub-formula selection -mechanism is described; this works in conjunction with any Calc -commands. Then, commands for specific algebraic operations are -described. Finally, the flexible @dfn{rewrite rule} mechanism -is discussed. - -The algebraic commands use the @kbd{a} key prefix; selection -commands use the @kbd{j} (for ``just a letter that wasn't used -for anything else'') prefix. - -@xref{Editing Stack Entries}, to see how to manipulate formulas -using regular Emacs editing commands. - -When doing algebraic work, you may find several of the Calculator's -modes to be helpful, including Algebraic Simplification mode (@kbd{m A}) -or No-Simplification mode (@kbd{m O}), -Algebraic entry mode (@kbd{m a}), Fraction mode (@kbd{m f}), and -Symbolic mode (@kbd{m s}). @xref{Mode Settings}, for discussions -of these modes. You may also wish to select Big display mode (@kbd{d B}). -@xref{Normal Language Modes}. - -@menu -* Selecting Subformulas:: -* Algebraic Manipulation:: -* Simplifying Formulas:: -* Polynomials:: -* Calculus:: -* Solving Equations:: -* Numerical Solutions:: -* Curve Fitting:: -* Summations:: -* Logical Operations:: -* Rewrite Rules:: -@end menu - -@node Selecting Subformulas, Algebraic Manipulation, Algebra, Algebra -@section Selecting Sub-Formulas - -@noindent -@cindex Selections -@cindex Sub-formulas -@cindex Parts of formulas -When working with an algebraic formula it is often necessary to -manipulate a portion of the formula rather than the formula as a -whole. Calc allows you to ``select'' a portion of any formula on -the stack. Commands which would normally operate on that stack -entry will now operate only on the sub-formula, leaving the -surrounding part of the stack entry alone. - -One common non-algebraic use for selection involves vectors. To work -on one element of a vector in-place, simply select that element as a -``sub-formula'' of the vector. - -@menu -* Making Selections:: -* Changing Selections:: -* Displaying Selections:: -* Operating on Selections:: -* Rearranging with Selections:: -@end menu - -@node Making Selections, Changing Selections, Selecting Subformulas, Selecting Subformulas -@subsection Making Selections - -@noindent -@kindex j s -@pindex calc-select-here -To select a sub-formula, move the Emacs cursor to any character in that -sub-formula, and press @w{@kbd{j s}} (@code{calc-select-here}). Calc will -highlight the smallest portion of the formula that contains that -character. By default the sub-formula is highlighted by blanking out -all of the rest of the formula with dots. Selection works in any -display mode but is perhaps easiest in Big mode (@kbd{d B}). -Suppose you enter the following formula: - -@smallexample -@group - 3 ___ - (a + b) + V c -1: --------------- - 2 x + 1 -@end group -@end smallexample - -@noindent -(by typing @kbd{' ((a+b)^3 + sqrt(c)) / (2x+1)}). If you move the -cursor to the letter @samp{b} and press @w{@kbd{j s}}, the display changes -to - -@smallexample -@group - . ... - .. . b. . . . -1* ............... - . . . . -@end group -@end smallexample - -@noindent -Every character not part of the sub-formula @samp{b} has been changed -to a dot. (If the customizable variable -@code{calc-highlight-selections-with-faces} is non-nil, then the characters -not part of the sub-formula are de-emphasized by using a less -noticeable face instead of using dots. @pxref{Displaying Selections}.) -The @samp{*} next to the line number is to remind you that -the formula has a portion of it selected. (In this case, it's very -obvious, but it might not always be. If Embedded mode is enabled, -the word @samp{Sel} also appears in the mode line because the stack -may not be visible. @pxref{Embedded Mode}.) - -If you had instead placed the cursor on the parenthesis immediately to -the right of the @samp{b}, the selection would have been: - -@smallexample -@group - . ... - (a + b) . . . -1* ............... - . . . . -@end group -@end smallexample - -@noindent -The portion selected is always large enough to be considered a complete -formula all by itself, so selecting the parenthesis selects the whole -formula that it encloses. Putting the cursor on the @samp{+} sign -would have had the same effect. - -(Strictly speaking, the Emacs cursor is really the manifestation of -the Emacs ``point,'' which is a position @emph{between} two characters -in the buffer. So purists would say that Calc selects the smallest -sub-formula which contains the character to the right of ``point.'') - -If you supply a numeric prefix argument @var{n}, the selection is -expanded to the @var{n}th enclosing sub-formula. Thus, positioning -the cursor on the @samp{b} and typing @kbd{C-u 1 j s} will select -@samp{a + b}; typing @kbd{C-u 2 j s} will select @samp{(a + b)^3}, -and so on. - -If the cursor is not on any part of the formula, or if you give a -numeric prefix that is too large, the entire formula is selected. - -If the cursor is on the @samp{.} line that marks the top of the stack -(i.e., its normal ``rest position''), this command selects the entire -formula at stack level 1. Most selection commands similarly operate -on the formula at the top of the stack if you haven't positioned the -cursor on any stack entry. - -@kindex j a -@pindex calc-select-additional -The @kbd{j a} (@code{calc-select-additional}) command enlarges the -current selection to encompass the cursor. To select the smallest -sub-formula defined by two different points, move to the first and -press @kbd{j s}, then move to the other and press @kbd{j a}. This -is roughly analogous to using @kbd{C-@@} (@code{set-mark-command}) to -select the two ends of a region of text during normal Emacs editing. - -@kindex j o -@pindex calc-select-once -The @kbd{j o} (@code{calc-select-once}) command selects a formula in -exactly the same way as @kbd{j s}, except that the selection will -last only as long as the next command that uses it. For example, -@kbd{j o 1 +} is a handy way to add one to the sub-formula indicated -by the cursor. - -(A somewhat more precise definition: The @kbd{j o} command sets a flag -such that the next command involving selected stack entries will clear -the selections on those stack entries afterwards. All other selection -commands except @kbd{j a} and @kbd{j O} clear this flag.) - -@kindex j S -@kindex j O -@pindex calc-select-here-maybe -@pindex calc-select-once-maybe -The @kbd{j S} (@code{calc-select-here-maybe}) and @kbd{j O} -(@code{calc-select-once-maybe}) commands are equivalent to @kbd{j s} -and @kbd{j o}, respectively, except that if the formula already -has a selection they have no effect. This is analogous to the -behavior of some commands such as @kbd{j r} (@code{calc-rewrite-selection}; -@pxref{Selections with Rewrite Rules}) and is mainly intended to be -used in keyboard macros that implement your own selection-oriented -commands. - -Selection of sub-formulas normally treats associative terms like -@samp{a + b - c + d} and @samp{x * y * z} as single levels of the formula. -If you place the cursor anywhere inside @samp{a + b - c + d} except -on one of the variable names and use @kbd{j s}, you will select the -entire four-term sum. - -@kindex j b -@pindex calc-break-selections -The @kbd{j b} (@code{calc-break-selections}) command controls a mode -in which the ``deep structure'' of these associative formulas shows -through. Calc actually stores the above formulas as -@samp{((a + b) - c) + d} and @samp{x * (y * z)}. (Note that for certain -obscure reasons, by default Calc treats multiplication as -right-associative.) Once you have enabled @kbd{j b} mode, selecting -with the cursor on the @samp{-} sign would only select the @samp{a + b - -c} portion, which makes sense when the deep structure of the sum is -considered. There is no way to select the @samp{b - c + d} portion; -although this might initially look like just as legitimate a sub-formula -as @samp{a + b - c}, the deep structure shows that it isn't. The @kbd{d -U} command can be used to view the deep structure of any formula -(@pxref{Normal Language Modes}). - -When @kbd{j b} mode has not been enabled, the deep structure is -generally hidden by the selection commands---what you see is what -you get. - -@kindex j u -@pindex calc-unselect -The @kbd{j u} (@code{calc-unselect}) command unselects the formula -that the cursor is on. If there was no selection in the formula, -this command has no effect. With a numeric prefix argument, it -unselects the @var{n}th stack element rather than using the cursor -position. - -@kindex j c -@pindex calc-clear-selections -The @kbd{j c} (@code{calc-clear-selections}) command unselects all -stack elements. - -@node Changing Selections, Displaying Selections, Making Selections, Selecting Subformulas -@subsection Changing Selections - -@noindent -@kindex j m -@pindex calc-select-more -Once you have selected a sub-formula, you can expand it using the -@w{@kbd{j m}} (@code{calc-select-more}) command. If @samp{a + b} is -selected, pressing @w{@kbd{j m}} repeatedly works as follows: - -@smallexample -@group - 3 ... 3 ___ 3 ___ - (a + b) . . . (a + b) + V c (a + b) + V c -1* ............... 1* ............... 1* --------------- - . . . . . . . . 2 x + 1 -@end group -@end smallexample - -@noindent -In the last example, the entire formula is selected. This is roughly -the same as having no selection at all, but because there are subtle -differences the @samp{*} character is still there on the line number. - -With a numeric prefix argument @var{n}, @kbd{j m} expands @var{n} -times (or until the entire formula is selected). Note that @kbd{j s} -with argument @var{n} is equivalent to plain @kbd{j s} followed by -@kbd{j m} with argument @var{n}. If @w{@kbd{j m}} is used when there -is no current selection, it is equivalent to @w{@kbd{j s}}. - -Even though @kbd{j m} does not explicitly use the location of the -cursor within the formula, it nevertheless uses the cursor to determine -which stack element to operate on. As usual, @kbd{j m} when the cursor -is not on any stack element operates on the top stack element. - -@kindex j l -@pindex calc-select-less -The @kbd{j l} (@code{calc-select-less}) command reduces the current -selection around the cursor position. That is, it selects the -immediate sub-formula of the current selection which contains the -cursor, the opposite of @kbd{j m}. If the cursor is not inside the -current selection, the command de-selects the formula. - -@kindex j 1-9 -@pindex calc-select-part -The @kbd{j 1} through @kbd{j 9} (@code{calc-select-part}) commands -select the @var{n}th sub-formula of the current selection. They are -like @kbd{j l} (@code{calc-select-less}) except they use counting -rather than the cursor position to decide which sub-formula to select. -For example, if the current selection is @kbd{a + b + c} or -@kbd{f(a, b, c)} or @kbd{[a, b, c]}, then @kbd{j 1} selects @samp{a}, -@kbd{j 2} selects @samp{b}, and @kbd{j 3} selects @samp{c}; in each of -these cases, @kbd{j 4} through @kbd{j 9} would be errors. - -If there is no current selection, @kbd{j 1} through @kbd{j 9} select -the @var{n}th top-level sub-formula. (In other words, they act as if -the entire stack entry were selected first.) To select the @var{n}th -sub-formula where @var{n} is greater than nine, you must instead invoke -@w{@kbd{j 1}} with @var{n} as a numeric prefix argument. - -@kindex j n -@kindex j p -@pindex calc-select-next -@pindex calc-select-previous -The @kbd{j n} (@code{calc-select-next}) and @kbd{j p} -(@code{calc-select-previous}) commands change the current selection -to the next or previous sub-formula at the same level. For example, -if @samp{b} is selected in @w{@samp{2 + a*b*c + x}}, then @kbd{j n} -selects @samp{c}. Further @kbd{j n} commands would be in error because, -even though there is something to the right of @samp{c} (namely, @samp{x}), -it is not at the same level; in this case, it is not a term of the -same product as @samp{b} and @samp{c}. However, @kbd{j m} (to select -the whole product @samp{a*b*c} as a term of the sum) followed by -@w{@kbd{j n}} would successfully select the @samp{x}. - -Similarly, @kbd{j p} moves the selection from the @samp{b} in this -sample formula to the @samp{a}. Both commands accept numeric prefix -arguments to move several steps at a time. - -It is interesting to compare Calc's selection commands with the -Emacs Info system's commands for navigating through hierarchically -organized documentation. Calc's @kbd{j n} command is completely -analogous to Info's @kbd{n} command. Likewise, @kbd{j p} maps to -@kbd{p}, @kbd{j 2} maps to @kbd{2}, and Info's @kbd{u} is like @kbd{j m}. -(Note that @kbd{j u} stands for @code{calc-unselect}, not ``up''.) -The Info @kbd{m} command is somewhat similar to Calc's @kbd{j s} and -@kbd{j l}; in each case, you can jump directly to a sub-component -of the hierarchy simply by pointing to it with the cursor. - -@node Displaying Selections, Operating on Selections, Changing Selections, Selecting Subformulas -@subsection Displaying Selections - -@noindent -@kindex j d -@pindex calc-show-selections -@vindex calc-highlight-selections-with-faces -@vindex calc-selected-face -@vindex calc-nonselected-face -The @kbd{j d} (@code{calc-show-selections}) command controls how -selected sub-formulas are displayed. One of the alternatives is -illustrated in the above examples; if we press @kbd{j d} we switch -to the other style in which the selected portion itself is obscured -by @samp{#} signs: - -@smallexample -@group - 3 ... # ___ - (a + b) . . . ## # ## + V c -1* ............... 1* --------------- - . . . . 2 x + 1 -@end group -@end smallexample -If the customizable variable -@code{calc-highlight-selections-with-faces} is non-nil, then the -non-selected portion of the formula will be de-emphasized by using a -less noticeable face (@code{calc-nonselected-face}) instead of dots -and the selected sub-formula will be highlighted by using a more -noticeable face (@code{calc-selected-face}) instead of @samp{#} -signs. (@pxref{Customizing Calc}.) - -@node Operating on Selections, Rearranging with Selections, Displaying Selections, Selecting Subformulas -@subsection Operating on Selections - -@noindent -Once a selection is made, all Calc commands that manipulate items -on the stack will operate on the selected portions of the items -instead. (Note that several stack elements may have selections -at once, though there can be only one selection at a time in any -given stack element.) - -@kindex j e -@pindex calc-enable-selections -The @kbd{j e} (@code{calc-enable-selections}) command disables the -effect that selections have on Calc commands. The current selections -still exist, but Calc commands operate on whole stack elements anyway. -This mode can be identified by the fact that the @samp{*} markers on -the line numbers are gone, even though selections are visible. To -reactivate the selections, press @kbd{j e} again. - -To extract a sub-formula as a new formula, simply select the -sub-formula and press @key{RET}. This normally duplicates the top -stack element; here it duplicates only the selected portion of that -element. - -To replace a sub-formula with something different, you can enter the -new value onto the stack and press @key{TAB}. This normally exchanges -the top two stack elements; here it swaps the value you entered into -the selected portion of the formula, returning the old selected -portion to the top of the stack. - -@smallexample -@group - 3 ... ... ___ - (a + b) . . . 17 x y . . . 17 x y + V c -2* ............... 2* ............. 2: ------------- - . . . . . . . . 2 x + 1 - - 3 3 -1: 17 x y 1: (a + b) 1: (a + b) -@end group -@end smallexample - -In this example we select a sub-formula of our original example, -enter a new formula, @key{TAB} it into place, then deselect to see -the complete, edited formula. - -If you want to swap whole formulas around even though they contain -selections, just use @kbd{j e} before and after. - -@kindex j ' -@pindex calc-enter-selection -The @kbd{j '} (@code{calc-enter-selection}) command is another way -to replace a selected sub-formula. This command does an algebraic -entry just like the regular @kbd{'} key. When you press @key{RET}, -the formula you type replaces the original selection. You can use -the @samp{$} symbol in the formula to refer to the original -selection. If there is no selection in the formula under the cursor, -the cursor is used to make a temporary selection for the purposes of -the command. Thus, to change a term of a formula, all you have to -do is move the Emacs cursor to that term and press @kbd{j '}. - -@kindex j ` -@pindex calc-edit-selection -The @kbd{j `} (@code{calc-edit-selection}) command is a similar -analogue of the @kbd{`} (@code{calc-edit}) command. It edits the -selected sub-formula in a separate buffer. If there is no -selection, it edits the sub-formula indicated by the cursor. - -To delete a sub-formula, press @key{DEL}. This generally replaces -the sub-formula with the constant zero, but in a few suitable contexts -it uses the constant one instead. The @key{DEL} key automatically -deselects and re-simplifies the entire formula afterwards. Thus: - -@smallexample -@group - ### - 17 x y + # # 17 x y 17 # y 17 y -1* ------------- 1: ------- 1* ------- 1: ------- - 2 x + 1 2 x + 1 2 x + 1 2 x + 1 -@end group -@end smallexample - -In this example, we first delete the @samp{sqrt(c)} term; Calc -accomplishes this by replacing @samp{sqrt(c)} with zero and -resimplifying. We then delete the @kbd{x} in the numerator; -since this is part of a product, Calc replaces it with @samp{1} -and resimplifies. - -If you select an element of a vector and press @key{DEL}, that -element is deleted from the vector. If you delete one side of -an equation or inequality, only the opposite side remains. - -@kindex j @key{DEL} -@pindex calc-del-selection -The @kbd{j @key{DEL}} (@code{calc-del-selection}) command is like -@key{DEL} but with the auto-selecting behavior of @kbd{j '} and -@kbd{j `}. It deletes the selected portion of the formula -indicated by the cursor, or, in the absence of a selection, it -deletes the sub-formula indicated by the cursor position. - -@kindex j @key{RET} -@pindex calc-grab-selection -(There is also an auto-selecting @kbd{j @key{RET}} (@code{calc-copy-selection}) -command.) - -Normal arithmetic operations also apply to sub-formulas. Here we -select the denominator, press @kbd{5 -} to subtract five from the -denominator, press @kbd{n} to negate the denominator, then -press @kbd{Q} to take the square root. - -@smallexample -@group - .. . .. . .. . .. . -1* ....... 1* ....... 1* ....... 1* .......... - 2 x + 1 2 x - 4 4 - 2 x _________ - V 4 - 2 x -@end group -@end smallexample - -Certain types of operations on selections are not allowed. For -example, for an arithmetic function like @kbd{-} no more than one of -the arguments may be a selected sub-formula. (As the above example -shows, the result of the subtraction is spliced back into the argument -which had the selection; if there were more than one selection involved, -this would not be well-defined.) If you try to subtract two selections, -the command will abort with an error message. - -Operations on sub-formulas sometimes leave the formula as a whole -in an ``un-natural'' state. Consider negating the @samp{2 x} term -of our sample formula by selecting it and pressing @kbd{n} -(@code{calc-change-sign}). - -@smallexample -@group - .. . .. . -1* .......... 1* ........... - ......... .......... - . . . 2 x . . . -2 x -@end group -@end smallexample - -Unselecting the sub-formula reveals that the minus sign, which would -normally have canceled out with the subtraction automatically, has -not been able to do so because the subtraction was not part of the -selected portion. Pressing @kbd{=} (@code{calc-evaluate}) or doing -any other mathematical operation on the whole formula will cause it -to be simplified. - -@smallexample -@group - 17 y 17 y -1: ----------- 1: ---------- - __________ _________ - V 4 - -2 x V 4 + 2 x -@end group -@end smallexample - -@node Rearranging with Selections, , Operating on Selections, Selecting Subformulas -@subsection Rearranging Formulas using Selections - -@noindent -@kindex j R -@pindex calc-commute-right -The @kbd{j R} (@code{calc-commute-right}) command moves the selected -sub-formula to the right in its surrounding formula. Generally the -selection is one term of a sum or product; the sum or product is -rearranged according to the commutative laws of algebra. - -As with @kbd{j '} and @kbd{j @key{DEL}}, the term under the cursor is used -if there is no selection in the current formula. All commands described -in this section share this property. In this example, we place the -cursor on the @samp{a} and type @kbd{j R}, then repeat. - -@smallexample -1: a + b - c 1: b + a - c 1: b - c + a -@end smallexample - -@noindent -Note that in the final step above, the @samp{a} is switched with -the @samp{c} but the signs are adjusted accordingly. When moving -terms of sums and products, @kbd{j R} will never change the -mathematical meaning of the formula. - -The selected term may also be an element of a vector or an argument -of a function. The term is exchanged with the one to its right. -In this case, the ``meaning'' of the vector or function may of -course be drastically changed. - -@smallexample -1: [a, b, c] 1: [b, a, c] 1: [b, c, a] - -1: f(a, b, c) 1: f(b, a, c) 1: f(b, c, a) -@end smallexample - -@kindex j L -@pindex calc-commute-left -The @kbd{j L} (@code{calc-commute-left}) command is like @kbd{j R} -except that it swaps the selected term with the one to its left. - -With numeric prefix arguments, these commands move the selected -term several steps at a time. It is an error to try to move a -term left or right past the end of its enclosing formula. -With numeric prefix arguments of zero, these commands move the -selected term as far as possible in the given direction. - -@kindex j D -@pindex calc-sel-distribute -The @kbd{j D} (@code{calc-sel-distribute}) command mixes the selected -sum or product into the surrounding formula using the distributive -law. For example, in @samp{a * (b - c)} with the @samp{b - c} -selected, the result is @samp{a b - a c}. This also distributes -products or quotients into surrounding powers, and can also do -transformations like @samp{exp(a + b)} to @samp{exp(a) exp(b)}, -where @samp{a + b} is the selected term, and @samp{ln(a ^ b)} -to @samp{ln(a) b}, where @samp{a ^ b} is the selected term. - -For multiple-term sums or products, @kbd{j D} takes off one term -at a time: @samp{a * (b + c - d)} goes to @samp{a * (c - d) + a b} -with the @samp{c - d} selected so that you can type @kbd{j D} -repeatedly to expand completely. The @kbd{j D} command allows a -numeric prefix argument which specifies the maximum number of -times to expand at once; the default is one time only. - -@vindex DistribRules -The @kbd{j D} command is implemented using rewrite rules. -@xref{Selections with Rewrite Rules}. The rules are stored in -the Calc variable @code{DistribRules}. A convenient way to view -these rules is to use @kbd{s e} (@code{calc-edit-variable}) which -displays and edits the stored value of a variable. Press @kbd{C-c C-c} -to return from editing mode; be careful not to make any actual changes -or else you will affect the behavior of future @kbd{j D} commands! - -To extend @kbd{j D} to handle new cases, just edit @code{DistribRules} -as described above. You can then use the @kbd{s p} command to save -this variable's value permanently for future Calc sessions. -@xref{Operations on Variables}. - -@kindex j M -@pindex calc-sel-merge -@vindex MergeRules -The @kbd{j M} (@code{calc-sel-merge}) command is the complement -of @kbd{j D}; given @samp{a b - a c} with either @samp{a b} or -@samp{a c} selected, the result is @samp{a * (b - c)}. Once -again, @kbd{j M} can also merge calls to functions like @code{exp} -and @code{ln}; examine the variable @code{MergeRules} to see all -the relevant rules. - -@kindex j C -@pindex calc-sel-commute -@vindex CommuteRules -The @kbd{j C} (@code{calc-sel-commute}) command swaps the arguments -of the selected sum, product, or equation. It always behaves as -if @kbd{j b} mode were in effect, i.e., the sum @samp{a + b + c} is -treated as the nested sums @samp{(a + b) + c} by this command. -If you put the cursor on the first @samp{+}, the result is -@samp{(b + a) + c}; if you put the cursor on the second @samp{+}, the -result is @samp{c + (a + b)} (which the default simplifications -will rearrange to @samp{(c + a) + b}). The relevant rules are stored -in the variable @code{CommuteRules}. - -You may need to turn default simplifications off (with the @kbd{m O} -command) in order to get the full benefit of @kbd{j C}. For example, -commuting @samp{a - b} produces @samp{-b + a}, but the default -simplifications will ``simplify'' this right back to @samp{a - b} if -you don't turn them off. The same is true of some of the other -manipulations described in this section. - -@kindex j N -@pindex calc-sel-negate -@vindex NegateRules -The @kbd{j N} (@code{calc-sel-negate}) command replaces the selected -term with the negative of that term, then adjusts the surrounding -formula in order to preserve the meaning. For example, given -@samp{exp(a - b)} where @samp{a - b} is selected, the result is -@samp{1 / exp(b - a)}. By contrast, selecting a term and using the -regular @kbd{n} (@code{calc-change-sign}) command negates the -term without adjusting the surroundings, thus changing the meaning -of the formula as a whole. The rules variable is @code{NegateRules}. - -@kindex j & -@pindex calc-sel-invert -@vindex InvertRules -The @kbd{j &} (@code{calc-sel-invert}) command is similar to @kbd{j N} -except it takes the reciprocal of the selected term. For example, -given @samp{a - ln(b)} with @samp{b} selected, the result is -@samp{a + ln(1/b)}. The rules variable is @code{InvertRules}. - -@kindex j E -@pindex calc-sel-jump-equals -@vindex JumpRules -The @kbd{j E} (@code{calc-sel-jump-equals}) command moves the -selected term from one side of an equation to the other. Given -@samp{a + b = c + d} with @samp{c} selected, the result is -@samp{a + b - c = d}. This command also works if the selected -term is part of a @samp{*}, @samp{/}, or @samp{^} formula. The -relevant rules variable is @code{JumpRules}. - -@kindex j I -@kindex H j I -@pindex calc-sel-isolate -The @kbd{j I} (@code{calc-sel-isolate}) command isolates the -selected term on its side of an equation. It uses the @kbd{a S} -(@code{calc-solve-for}) command to solve the equation, and the -Hyperbolic flag affects it in the same way. @xref{Solving Equations}. -When it applies, @kbd{j I} is often easier to use than @kbd{j E}. -It understands more rules of algebra, and works for inequalities -as well as equations. - -@kindex j * -@kindex j / -@pindex calc-sel-mult-both-sides -@pindex calc-sel-div-both-sides -The @kbd{j *} (@code{calc-sel-mult-both-sides}) command prompts for a -formula using algebraic entry, then multiplies both sides of the -selected quotient or equation by that formula. It simplifies each -side with @kbd{a s} (@code{calc-simplify}) before re-forming the -quotient or equation. You can suppress this simplification by -providing a prefix argument: @kbd{C-u j *}. There is also a @kbd{j /} -(@code{calc-sel-div-both-sides}) which is similar to @kbd{j *} but -dividing instead of multiplying by the factor you enter. - -If the selection is a quotient with numerator 1, then Calc's default -simplifications would normally cancel the new factors. To prevent -this, when the @kbd{j *} command is used on a selection whose numerator is -1 or -1, the denominator is expanded at the top level using the -distributive law (as if using the @kbd{C-u 1 a x} command). Suppose the -formula on the stack is @samp{1 / (a + 1)} and you wish to multiplying the -top and bottom by @samp{a - 1}. Calc's default simplifications would -normally change the result @samp{(a - 1) /(a + 1) (a - 1)} back -to the original form by cancellation; when @kbd{j *} is used, Calc -expands the denominator to @samp{a (a - 1) + a - 1} to prevent this. - -If you wish the @kbd{j *} command to completely expand the denominator -of a quotient you can call it with a zero prefix: @kbd{C-u 0 j *}. For -example, if the formula on the stack is @samp{1 / (sqrt(a) + 1)}, you may -wish to eliminate the square root in the denominator by multiplying -the top and bottom by @samp{sqrt(a) - 1}. If you did this simply by using -a simple @kbd{j *} command, you would get -@samp{(sqrt(a)-1)/ (sqrt(a) (sqrt(a) - 1) + sqrt(a) - 1)}. Instead, -you would probably want to use @kbd{C-u 0 j *}, which would expand the -bottom and give you the desired result @samp{(sqrt(a)-1)/(a-1)}. More -generally, if @kbd{j *} is called with an argument of a positive -integer @var{n}, then the denominator of the expression will be -expanded @var{n} times (as if with the @kbd{C-u @var{n} a x} command). - -If the selection is an inequality, @kbd{j *} and @kbd{j /} will -accept any factor, but will warn unless they can prove the factor -is either positive or negative. (In the latter case the direction -of the inequality will be switched appropriately.) @xref{Declarations}, -for ways to inform Calc that a given variable is positive or -negative. If Calc can't tell for sure what the sign of the factor -will be, it will assume it is positive and display a warning -message. - -For selections that are not quotients, equations, or inequalities, -these commands pull out a multiplicative factor: They divide (or -multiply) by the entered formula, simplify, then multiply (or divide) -back by the formula. - -@kindex j + -@kindex j - -@pindex calc-sel-add-both-sides -@pindex calc-sel-sub-both-sides -The @kbd{j +} (@code{calc-sel-add-both-sides}) and @kbd{j -} -(@code{calc-sel-sub-both-sides}) commands analogously add to or -subtract from both sides of an equation or inequality. For other -types of selections, they extract an additive factor. A numeric -prefix argument suppresses simplification of the intermediate -results. - -@kindex j U -@pindex calc-sel-unpack -The @kbd{j U} (@code{calc-sel-unpack}) command replaces the -selected function call with its argument. For example, given -@samp{a + sin(x^2)} with @samp{sin(x^2)} selected, the result -is @samp{a + x^2}. (The @samp{x^2} will remain selected; if you -wanted to change the @code{sin} to @code{cos}, just press @kbd{C} -now to take the cosine of the selected part.) - -@kindex j v -@pindex calc-sel-evaluate -The @kbd{j v} (@code{calc-sel-evaluate}) command performs the -normal default simplifications on the selected sub-formula. -These are the simplifications that are normally done automatically -on all results, but which may have been partially inhibited by -previous selection-related operations, or turned off altogether -by the @kbd{m O} command. This command is just an auto-selecting -version of the @w{@kbd{a v}} command (@pxref{Algebraic Manipulation}). - -With a numeric prefix argument of 2, @kbd{C-u 2 j v} applies -the @kbd{a s} (@code{calc-simplify}) command to the selected -sub-formula. With a prefix argument of 3 or more, e.g., @kbd{C-u j v} -applies the @kbd{a e} (@code{calc-simplify-extended}) command. -@xref{Simplifying Formulas}. With a negative prefix argument -it simplifies at the top level only, just as with @kbd{a v}. -Here the ``top'' level refers to the top level of the selected -sub-formula. - -@kindex j " -@pindex calc-sel-expand-formula -The @kbd{j "} (@code{calc-sel-expand-formula}) command is to @kbd{a "} -(@pxref{Algebraic Manipulation}) what @kbd{j v} is to @kbd{a v}. - -You can use the @kbd{j r} (@code{calc-rewrite-selection}) command -to define other algebraic operations on sub-formulas. @xref{Rewrite Rules}. - -@node Algebraic Manipulation, Simplifying Formulas, Selecting Subformulas, Algebra -@section Algebraic Manipulation - -@noindent -The commands in this section perform general-purpose algebraic -manipulations. They work on the whole formula at the top of the -stack (unless, of course, you have made a selection in that -formula). - -Many algebra commands prompt for a variable name or formula. If you -answer the prompt with a blank line, the variable or formula is taken -from top-of-stack, and the normal argument for the command is taken -from the second-to-top stack level. - -@kindex a v -@pindex calc-alg-evaluate -The @kbd{a v} (@code{calc-alg-evaluate}) command performs the normal -default simplifications on a formula; for example, @samp{a - -b} is -changed to @samp{a + b}. These simplifications are normally done -automatically on all Calc results, so this command is useful only if -you have turned default simplifications off with an @kbd{m O} -command. @xref{Simplification Modes}. - -It is often more convenient to type @kbd{=}, which is like @kbd{a v} -but which also substitutes stored values for variables in the formula. -Use @kbd{a v} if you want the variables to ignore their stored values. - -If you give a numeric prefix argument of 2 to @kbd{a v}, it simplifies -as if in Algebraic Simplification mode. This is equivalent to typing -@kbd{a s}; @pxref{Simplifying Formulas}. If you give a numeric prefix -of 3 or more, it uses Extended Simplification mode (@kbd{a e}). - -If you give a negative prefix argument @mathit{-1}, @mathit{-2}, or @mathit{-3}, -it simplifies in the corresponding mode but only works on the top-level -function call of the formula. For example, @samp{(2 + 3) * (2 + 3)} will -simplify to @samp{(2 + 3)^2}, without simplifying the sub-formulas -@samp{2 + 3}. As another example, typing @kbd{V R +} to sum the vector -@samp{[1, 2, 3, 4]} produces the formula @samp{reduce(add, [1, 2, 3, 4])} -in No-Simplify mode. Using @kbd{a v} will evaluate this all the way to -10; using @kbd{C-u - a v} will evaluate it only to @samp{1 + 2 + 3 + 4}. -(@xref{Reducing and Mapping}.) - -@tindex evalv -@tindex evalvn -The @kbd{=} command corresponds to the @code{evalv} function, and -the related @kbd{N} command, which is like @kbd{=} but temporarily -disables Symbolic mode (@kbd{m s}) during the evaluation, corresponds -to the @code{evalvn} function. (These commands interpret their prefix -arguments differently than @kbd{a v}; @kbd{=} treats the prefix as -the number of stack elements to evaluate at once, and @kbd{N} treats -it as a temporary different working precision.) - -The @code{evalvn} function can take an alternate working precision -as an optional second argument. This argument can be either an -integer, to set the precision absolutely, or a vector containing -a single integer, to adjust the precision relative to the current -precision. Note that @code{evalvn} with a larger than current -precision will do the calculation at this higher precision, but the -result will as usual be rounded back down to the current precision -afterward. For example, @samp{evalvn(pi - 3.1415)} at a precision -of 12 will return @samp{9.265359e-5}; @samp{evalvn(pi - 3.1415, 30)} -will return @samp{9.26535897932e-5} (computing a 25-digit result which -is then rounded down to 12); and @samp{evalvn(pi - 3.1415, [-2])} -will return @samp{9.2654e-5}. - -@kindex a " -@pindex calc-expand-formula -The @kbd{a "} (@code{calc-expand-formula}) command expands functions -into their defining formulas wherever possible. For example, -@samp{deg(x^2)} is changed to @samp{180 x^2 / pi}. Most functions, -like @code{sin} and @code{gcd}, are not defined by simple formulas -and so are unaffected by this command. One important class of -functions which @emph{can} be expanded is the user-defined functions -created by the @kbd{Z F} command. @xref{Algebraic Definitions}. -Other functions which @kbd{a "} can expand include the probability -distribution functions, most of the financial functions, and the -hyperbolic and inverse hyperbolic functions. A numeric prefix argument -affects @kbd{a "} in the same way as it does @kbd{a v}: A positive -argument expands all functions in the formula and then simplifies in -various ways; a negative argument expands and simplifies only the -top-level function call. - -@kindex a M -@pindex calc-map-equation -@tindex mapeq -The @kbd{a M} (@code{calc-map-equation}) [@code{mapeq}] command applies -a given function or operator to one or more equations. It is analogous -to @kbd{V M}, which operates on vectors instead of equations. -@pxref{Reducing and Mapping}. For example, @kbd{a M S} changes -@samp{x = y+1} to @samp{sin(x) = sin(y+1)}, and @kbd{a M +} with -@samp{x = y+1} and @expr{6} on the stack produces @samp{x+6 = y+7}. -With two equations on the stack, @kbd{a M +} would add the lefthand -sides together and the righthand sides together to get the two -respective sides of a new equation. - -Mapping also works on inequalities. Mapping two similar inequalities -produces another inequality of the same type. Mapping an inequality -with an equation produces an inequality of the same type. Mapping a -@samp{<=} with a @samp{<} or @samp{!=} (not-equal) produces a @samp{<}. -If inequalities with opposite direction (e.g., @samp{<} and @samp{>}) -are mapped, the direction of the second inequality is reversed to -match the first: Using @kbd{a M +} on @samp{a < b} and @samp{a > 2} -reverses the latter to get @samp{2 < a}, which then allows the -combination @samp{a + 2 < b + a}, which the @kbd{a s} command can -then simplify to get @samp{2 < b}. - -Using @kbd{a M *}, @kbd{a M /}, @kbd{a M n}, or @kbd{a M &} to negate -or invert an inequality will reverse the direction of the inequality. -Other adjustments to inequalities are @emph{not} done automatically; -@kbd{a M S} will change @w{@samp{x < y}} to @samp{sin(x) < sin(y)} even -though this is not true for all values of the variables. - -@kindex H a M -@tindex mapeqp -With the Hyperbolic flag, @kbd{H a M} [@code{mapeqp}] does a plain -mapping operation without reversing the direction of any inequalities. -Thus, @kbd{H a M &} would change @kbd{x > 2} to @kbd{1/x > 0.5}. -(This change is mathematically incorrect, but perhaps you were -fixing an inequality which was already incorrect.) - -@kindex I a M -@tindex mapeqr -With the Inverse flag, @kbd{I a M} [@code{mapeqr}] always reverses -the direction of the inequality. You might use @kbd{I a M C} to -change @samp{x < y} to @samp{cos(x) > cos(y)} if you know you are -working with small positive angles. - -@kindex a b -@pindex calc-substitute -@tindex subst -The @kbd{a b} (@code{calc-substitute}) [@code{subst}] command substitutes -all occurrences -of some variable or sub-expression of an expression with a new -sub-expression. For example, substituting @samp{sin(x)} with @samp{cos(y)} -in @samp{2 sin(x)^2 + x sin(x) + sin(2 x)} produces -@samp{2 cos(y)^2 + x cos(y) + @w{sin(2 x)}}. -Note that this is a purely structural substitution; the lone @samp{x} and -the @samp{sin(2 x)} stayed the same because they did not look like -@samp{sin(x)}. @xref{Rewrite Rules}, for a more general method for -doing substitutions. - -The @kbd{a b} command normally prompts for two formulas, the old -one and the new one. If you enter a blank line for the first -prompt, all three arguments are taken from the stack (new, then old, -then target expression). If you type an old formula but then enter a -blank line for the new one, the new formula is taken from top-of-stack -and the target from second-to-top. If you answer both prompts, the -target is taken from top-of-stack as usual. - -Note that @kbd{a b} has no understanding of commutativity or -associativity. The pattern @samp{x+y} will not match the formula -@samp{y+x}. Also, @samp{y+z} will not match inside the formula @samp{x+y+z} -because the @samp{+} operator is left-associative, so the ``deep -structure'' of that formula is @samp{(x+y) + z}. Use @kbd{d U} -(@code{calc-unformatted-language}) mode to see the true structure of -a formula. The rewrite rule mechanism, discussed later, does not have -these limitations. - -As an algebraic function, @code{subst} takes three arguments: -Target expression, old, new. Note that @code{subst} is always -evaluated immediately, even if its arguments are variables, so if -you wish to put a call to @code{subst} onto the stack you must -turn the default simplifications off first (with @kbd{m O}). - -@node Simplifying Formulas, Polynomials, Algebraic Manipulation, Algebra -@section Simplifying Formulas - -@noindent -@kindex a s -@kindex I a s -@kindex H a s -@pindex calc-simplify -@tindex simplify -The @kbd{a s} (@code{calc-simplify}) [@code{simplify}] command applies -various algebraic rules to simplify a formula. This includes rules which -are not part of the default simplifications because they may be too slow -to apply all the time, or may not be desirable all of the time. For -example, non-adjacent terms of sums are combined, as in @samp{a + b + 2 a} -to @samp{b + 3 a}, and some formulas like @samp{sin(arcsin(x))} are -simplified to @samp{x}. - -The sections below describe all the various kinds of algebraic -simplifications Calc provides in full detail. None of Calc's -simplification commands are designed to pull rabbits out of hats; -they simply apply certain specific rules to put formulas into -less redundant or more pleasing forms. Serious algebra in Calc -must be done manually, usually with a combination of selections -and rewrite rules. @xref{Rearranging with Selections}. -@xref{Rewrite Rules}. - -@xref{Simplification Modes}, for commands to control what level of -simplification occurs automatically. Normally only the ``default -simplifications'' occur. - -There are some simplifications that, while sometimes useful, are never -done automatically. For example, the @kbd{I} prefix can be given to -@kbd{a s}; the @kbd{I a s} command will change any trigonometric -function to the appropriate combination of @samp{sin}s and @samp{cos}s -before simplifying. This can be useful in simplifying even mildly -complicated trigonometric expressions. For example, while @kbd{a s} -can reduce @samp{sin(x) csc(x)} to @samp{1}, it will not simplify -@samp{sin(x)^2 csc(x)}. The command @kbd{I a s} can be used to -simplify this latter expression; it will transform @samp{sin(x)^2 -csc(x)} into @samp{sin(x)}. However, @kbd{I a s} will also perform -some ``simplifications'' which may not be desired; for example, it -will transform @samp{tan(x)^2} into @samp{sin(x)^2 / cos(x)^2}. The -Hyperbolic prefix @kbd{H} can be used similarly; the @kbd{H a s} will -replace any hyperbolic functions in the formula with the appropriate -combinations of @samp{sinh}s and @samp{cosh}s before simplifying. - - -@menu -* Default Simplifications:: -* Algebraic Simplifications:: -* Unsafe Simplifications:: -* Simplification of Units:: -@end menu - -@node Default Simplifications, Algebraic Simplifications, Simplifying Formulas, Simplifying Formulas -@subsection Default Simplifications - -@noindent -@cindex Default simplifications -This section describes the ``default simplifications,'' those which are -normally applied to all results. For example, if you enter the variable -@expr{x} on the stack twice and push @kbd{+}, Calc's default -simplifications automatically change @expr{x + x} to @expr{2 x}. - -The @kbd{m O} command turns off the default simplifications, so that -@expr{x + x} will remain in this form unless you give an explicit -``simplify'' command like @kbd{=} or @kbd{a v}. @xref{Algebraic -Manipulation}. The @kbd{m D} command turns the default simplifications -back on. - -The most basic default simplification is the evaluation of functions. -For example, @expr{2 + 3} is evaluated to @expr{5}, and @expr{@tfn{sqrt}(9)} -is evaluated to @expr{3}. Evaluation does not occur if the arguments -to a function are somehow of the wrong type @expr{@tfn{tan}([2,3,4])}), -range (@expr{@tfn{tan}(90)}), or number (@expr{@tfn{tan}(3,5)}), -or if the function name is not recognized (@expr{@tfn{f}(5)}), or if -Symbolic mode (@pxref{Symbolic Mode}) prevents evaluation -(@expr{@tfn{sqrt}(2)}). - -Calc simplifies (evaluates) the arguments to a function before it -simplifies the function itself. Thus @expr{@tfn{sqrt}(5+4)} is -simplified to @expr{@tfn{sqrt}(9)} before the @code{sqrt} function -itself is applied. There are very few exceptions to this rule: -@code{quote}, @code{lambda}, and @code{condition} (the @code{::} -operator) do not evaluate their arguments, @code{if} (the @code{? :} -operator) does not evaluate all of its arguments, and @code{evalto} -does not evaluate its lefthand argument. - -Most commands apply the default simplifications to all arguments they -take from the stack, perform a particular operation, then simplify -the result before pushing it back on the stack. In the common special -case of regular arithmetic commands like @kbd{+} and @kbd{Q} [@code{sqrt}], -the arguments are simply popped from the stack and collected into a -suitable function call, which is then simplified (the arguments being -simplified first as part of the process, as described above). - -The default simplifications are too numerous to describe completely -here, but this section will describe the ones that apply to the -major arithmetic operators. This list will be rather technical in -nature, and will probably be interesting to you only if you are -a serious user of Calc's algebra facilities. - -@tex -\bigskip -@end tex - -As well as the simplifications described here, if you have stored -any rewrite rules in the variable @code{EvalRules} then these rules -will also be applied before any built-in default simplifications. -@xref{Automatic Rewrites}, for details. - -@tex -\bigskip -@end tex - -And now, on with the default simplifications: - -Arithmetic operators like @kbd{+} and @kbd{*} always take two -arguments in Calc's internal form. Sums and products of three or -more terms are arranged by the associative law of algebra into -a left-associative form for sums, @expr{((a + b) + c) + d}, and -(by default) a right-associative form for products, -@expr{a * (b * (c * d))}. Formulas like @expr{(a + b) + (c + d)} are -rearranged to left-associative form, though this rarely matters since -Calc's algebra commands are designed to hide the inner structure of sums -and products as much as possible. Sums and products in their proper -associative form will be written without parentheses in the examples -below. - -Sums and products are @emph{not} rearranged according to the -commutative law (@expr{a + b} to @expr{b + a}) except in a few -special cases described below. Some algebra programs always -rearrange terms into a canonical order, which enables them to -see that @expr{a b + b a} can be simplified to @expr{2 a b}. -Calc assumes you have put the terms into the order you want -and generally leaves that order alone, with the consequence -that formulas like the above will only be simplified if you -explicitly give the @kbd{a s} command. @xref{Algebraic -Simplifications}. - -Differences @expr{a - b} are treated like sums @expr{a + (-b)} -for purposes of simplification; one of the default simplifications -is to rewrite @expr{a + (-b)} or @expr{(-b) + a}, where @expr{-b} -represents a ``negative-looking'' term, into @expr{a - b} form. -``Negative-looking'' means negative numbers, negated formulas like -@expr{-x}, and products or quotients in which either term is -negative-looking. - -Other simplifications involving negation are @expr{-(-x)} to @expr{x}; -@expr{-(a b)} or @expr{-(a/b)} where either @expr{a} or @expr{b} is -negative-looking, simplified by negating that term, or else where -@expr{a} or @expr{b} is any number, by negating that number; -@expr{-(a + b)} to @expr{-a - b}, and @expr{-(b - a)} to @expr{a - b}. -(This, and rewriting @expr{(-b) + a} to @expr{a - b}, are the only -cases where the order of terms in a sum is changed by the default -simplifications.) - -The distributive law is used to simplify sums in some cases: -@expr{a x + b x} to @expr{(a + b) x}, where @expr{a} represents -a number or an implicit 1 or @mathit{-1} (as in @expr{x} or @expr{-x}) -and similarly for @expr{b}. Use the @kbd{a c}, @w{@kbd{a f}}, or -@kbd{j M} commands to merge sums with non-numeric coefficients -using the distributive law. - -The distributive law is only used for sums of two terms, or -for adjacent terms in a larger sum. Thus @expr{a + b + b + c} -is simplified to @expr{a + 2 b + c}, but @expr{a + b + c + b} -is not simplified. The reason is that comparing all terms of a -sum with one another would require time proportional to the -square of the number of terms; Calc relegates potentially slow -operations like this to commands that have to be invoked -explicitly, like @kbd{a s}. - -Finally, @expr{a + 0} and @expr{0 + a} are simplified to @expr{a}. -A consequence of the above rules is that @expr{0 - a} is simplified -to @expr{-a}. - -@tex -\bigskip -@end tex - -The products @expr{1 a} and @expr{a 1} are simplified to @expr{a}; -@expr{(-1) a} and @expr{a (-1)} are simplified to @expr{-a}; -@expr{0 a} and @expr{a 0} are simplified to @expr{0}, except that -in Matrix mode where @expr{a} is not provably scalar the result -is the generic zero matrix @samp{idn(0)}, and that if @expr{a} is -infinite the result is @samp{nan}. - -Also, @expr{(-a) b} and @expr{a (-b)} are simplified to @expr{-(a b)}, -where this occurs for negated formulas but not for regular negative -numbers. - -Products are commuted only to move numbers to the front: -@expr{a b 2} is commuted to @expr{2 a b}. - -The product @expr{a (b + c)} is distributed over the sum only if -@expr{a} and at least one of @expr{b} and @expr{c} are numbers: -@expr{2 (x + 3)} goes to @expr{2 x + 6}. The formula -@expr{(-a) (b - c)}, where @expr{-a} is a negative number, is -rewritten to @expr{a (c - b)}. - -The distributive law of products and powers is used for adjacent -terms of the product: @expr{x^a x^b} goes to -@texline @math{x^{a+b}} -@infoline @expr{x^(a+b)} -where @expr{a} is a number, or an implicit 1 (as in @expr{x}), -or the implicit one-half of @expr{@tfn{sqrt}(x)}, and similarly for -@expr{b}. The result is written using @samp{sqrt} or @samp{1/sqrt} -if the sum of the powers is @expr{1/2} or @expr{-1/2}, respectively. -If the sum of the powers is zero, the product is simplified to -@expr{1} or to @samp{idn(1)} if Matrix mode is enabled. - -The product of a negative power times anything but another negative -power is changed to use division: -@texline @math{x^{-2} y} -@infoline @expr{x^(-2) y} -goes to @expr{y / x^2} unless Matrix mode is -in effect and neither @expr{x} nor @expr{y} are scalar (in which -case it is considered unsafe to rearrange the order of the terms). - -Finally, @expr{a (b/c)} is rewritten to @expr{(a b)/c}, and also -@expr{(a/b) c} is changed to @expr{(a c)/b} unless in Matrix mode. - -@tex -\bigskip -@end tex - -Simplifications for quotients are analogous to those for products. -The quotient @expr{0 / x} is simplified to @expr{0}, with the same -exceptions that were noted for @expr{0 x}. Likewise, @expr{x / 1} -and @expr{x / (-1)} are simplified to @expr{x} and @expr{-x}, -respectively. - -The quotient @expr{x / 0} is left unsimplified or changed to an -infinite quantity, as directed by the current infinite mode. -@xref{Infinite Mode}. - -The expression -@texline @math{a / b^{-c}} -@infoline @expr{a / b^(-c)} -is changed to @expr{a b^c}, where @expr{-c} is any negative-looking -power. Also, @expr{1 / b^c} is changed to -@texline @math{b^{-c}} -@infoline @expr{b^(-c)} -for any power @expr{c}. - -Also, @expr{(-a) / b} and @expr{a / (-b)} go to @expr{-(a/b)}; -@expr{(a/b) / c} goes to @expr{a / (b c)}; and @expr{a / (b/c)} -goes to @expr{(a c) / b} unless Matrix mode prevents this -rearrangement. Similarly, @expr{a / (b:c)} is simplified to -@expr{(c:b) a} for any fraction @expr{b:c}. - -The distributive law is applied to @expr{(a + b) / c} only if -@expr{c} and at least one of @expr{a} and @expr{b} are numbers. -Quotients of powers and square roots are distributed just as -described for multiplication. - -Quotients of products cancel only in the leading terms of the -numerator and denominator. In other words, @expr{a x b / a y b} -is canceled to @expr{x b / y b} but not to @expr{x / y}. Once -again this is because full cancellation can be slow; use @kbd{a s} -to cancel all terms of the quotient. - -Quotients of negative-looking values are simplified according -to @expr{(-a) / (-b)} to @expr{a / b}, @expr{(-a) / (b - c)} -to @expr{a / (c - b)}, and @expr{(a - b) / (-c)} to @expr{(b - a) / c}. - -@tex -\bigskip -@end tex - -The formula @expr{x^0} is simplified to @expr{1}, or to @samp{idn(1)} -in Matrix mode. The formula @expr{0^x} is simplified to @expr{0} -unless @expr{x} is a negative number, complex number or zero. -If @expr{x} is negative, complex or @expr{0.0}, @expr{0^x} is an -infinity or an unsimplified formula according to the current infinite -mode. The expression @expr{0^0} is simplified to @expr{1}. - -Powers of products or quotients @expr{(a b)^c}, @expr{(a/b)^c} -are distributed to @expr{a^c b^c}, @expr{a^c / b^c} only if @expr{c} -is an integer, or if either @expr{a} or @expr{b} are nonnegative -real numbers. Powers of powers @expr{(a^b)^c} are simplified to -@texline @math{a^{b c}} -@infoline @expr{a^(b c)} -only when @expr{c} is an integer and @expr{b c} also -evaluates to an integer. Without these restrictions these simplifications -would not be safe because of problems with principal values. -(In other words, -@texline @math{((-3)^{1/2})^2} -@infoline @expr{((-3)^1:2)^2} -is safe to simplify, but -@texline @math{((-3)^2)^{1/2}} -@infoline @expr{((-3)^2)^1:2} -is not.) @xref{Declarations}, for ways to inform Calc that your -variables satisfy these requirements. - -As a special case of this rule, @expr{@tfn{sqrt}(x)^n} is simplified to -@texline @math{x^{n/2}} -@infoline @expr{x^(n/2)} -only for even integers @expr{n}. - -If @expr{a} is known to be real, @expr{b} is an even integer, and -@expr{c} is a half- or quarter-integer, then @expr{(a^b)^c} is -simplified to @expr{@tfn{abs}(a^(b c))}. - -Also, @expr{(-a)^b} is simplified to @expr{a^b} if @expr{b} is an -even integer, or to @expr{-(a^b)} if @expr{b} is an odd integer, -for any negative-looking expression @expr{-a}. - -Square roots @expr{@tfn{sqrt}(x)} generally act like one-half powers -@texline @math{x^{1:2}} -@infoline @expr{x^1:2} -for the purposes of the above-listed simplifications. - -Also, note that -@texline @math{1 / x^{1:2}} -@infoline @expr{1 / x^1:2} -is changed to -@texline @math{x^{-1:2}}, -@infoline @expr{x^(-1:2)}, -but @expr{1 / @tfn{sqrt}(x)} is left alone. - -@tex -\bigskip -@end tex - -Generic identity matrices (@pxref{Matrix Mode}) are simplified by the -following rules: @expr{@tfn{idn}(a) + b} to @expr{a + b} if @expr{b} -is provably scalar, or expanded out if @expr{b} is a matrix; -@expr{@tfn{idn}(a) + @tfn{idn}(b)} to @expr{@tfn{idn}(a + b)}; -@expr{-@tfn{idn}(a)} to @expr{@tfn{idn}(-a)}; @expr{a @tfn{idn}(b)} to -@expr{@tfn{idn}(a b)} if @expr{a} is provably scalar, or to @expr{a b} -if @expr{a} is provably non-scalar; @expr{@tfn{idn}(a) @tfn{idn}(b)} to -@expr{@tfn{idn}(a b)}; analogous simplifications for quotients involving -@code{idn}; and @expr{@tfn{idn}(a)^n} to @expr{@tfn{idn}(a^n)} where -@expr{n} is an integer. - -@tex -\bigskip -@end tex - -The @code{floor} function and other integer truncation functions -vanish if the argument is provably integer-valued, so that -@expr{@tfn{floor}(@tfn{round}(x))} simplifies to @expr{@tfn{round}(x)}. -Also, combinations of @code{float}, @code{floor} and its friends, -and @code{ffloor} and its friends, are simplified in appropriate -ways. @xref{Integer Truncation}. - -The expression @expr{@tfn{abs}(-x)} changes to @expr{@tfn{abs}(x)}. -The expression @expr{@tfn{abs}(@tfn{abs}(x))} changes to -@expr{@tfn{abs}(x)}; in fact, @expr{@tfn{abs}(x)} changes to @expr{x} or -@expr{-x} if @expr{x} is provably nonnegative or nonpositive -(@pxref{Declarations}). - -While most functions do not recognize the variable @code{i} as an -imaginary number, the @code{arg} function does handle the two cases -@expr{@tfn{arg}(@tfn{i})} and @expr{@tfn{arg}(-@tfn{i})} just for convenience. - -The expression @expr{@tfn{conj}(@tfn{conj}(x))} simplifies to @expr{x}. -Various other expressions involving @code{conj}, @code{re}, and -@code{im} are simplified, especially if some of the arguments are -provably real or involve the constant @code{i}. For example, -@expr{@tfn{conj}(a + b i)} is changed to -@expr{@tfn{conj}(a) - @tfn{conj}(b) i}, or to @expr{a - b i} if @expr{a} -and @expr{b} are known to be real. - -Functions like @code{sin} and @code{arctan} generally don't have -any default simplifications beyond simply evaluating the functions -for suitable numeric arguments and infinity. The @kbd{a s} command -described in the next section does provide some simplifications for -these functions, though. - -One important simplification that does occur is that -@expr{@tfn{ln}(@tfn{e})} is simplified to 1, and @expr{@tfn{ln}(@tfn{e}^x)} is -simplified to @expr{x} for any @expr{x}. This occurs even if you have -stored a different value in the Calc variable @samp{e}; but this would -be a bad idea in any case if you were also using natural logarithms! - -Among the logical functions, @tfn{!(@var{a} <= @var{b})} changes to -@tfn{@var{a} > @var{b}} and so on. Equations and inequalities where both sides -are either negative-looking or zero are simplified by negating both sides -and reversing the inequality. While it might seem reasonable to simplify -@expr{!!x} to @expr{x}, this would not be valid in general because -@expr{!!2} is 1, not 2. - -Most other Calc functions have few if any default simplifications -defined, aside of course from evaluation when the arguments are -suitable numbers. - -@node Algebraic Simplifications, Unsafe Simplifications, Default Simplifications, Simplifying Formulas -@subsection Algebraic Simplifications - -@noindent -@cindex Algebraic simplifications -The @kbd{a s} command makes simplifications that may be too slow to -do all the time, or that may not be desirable all of the time. -If you find these simplifications are worthwhile, you can type -@kbd{m A} to have Calc apply them automatically. - -This section describes all simplifications that are performed by -the @kbd{a s} command. Note that these occur in addition to the -default simplifications; even if the default simplifications have -been turned off by an @kbd{m O} command, @kbd{a s} will turn them -back on temporarily while it simplifies the formula. - -There is a variable, @code{AlgSimpRules}, in which you can put rewrites -to be applied by @kbd{a s}. Its use is analogous to @code{EvalRules}, -but without the special restrictions. Basically, the simplifier does -@samp{@w{a r} AlgSimpRules} with an infinite repeat count on the whole -expression being simplified, then it traverses the expression applying -the built-in rules described below. If the result is different from -the original expression, the process repeats with the default -simplifications (including @code{EvalRules}), then @code{AlgSimpRules}, -then the built-in simplifications, and so on. - -@tex -\bigskip -@end tex - -Sums are simplified in two ways. Constant terms are commuted to the -end of the sum, so that @expr{a + 2 + b} changes to @expr{a + b + 2}. -The only exception is that a constant will not be commuted away -from the first position of a difference, i.e., @expr{2 - x} is not -commuted to @expr{-x + 2}. - -Also, terms of sums are combined by the distributive law, as in -@expr{x + y + 2 x} to @expr{y + 3 x}. This always occurs for -adjacent terms, but @kbd{a s} compares all pairs of terms including -non-adjacent ones. - -@tex -\bigskip -@end tex - -Products are sorted into a canonical order using the commutative -law. For example, @expr{b c a} is commuted to @expr{a b c}. -This allows easier comparison of products; for example, the default -simplifications will not change @expr{x y + y x} to @expr{2 x y}, -but @kbd{a s} will; it first rewrites the sum to @expr{x y + x y}, -and then the default simplifications are able to recognize a sum -of identical terms. - -The canonical ordering used to sort terms of products has the -property that real-valued numbers, interval forms and infinities -come first, and are sorted into increasing order. The @kbd{V S} -command uses the same ordering when sorting a vector. - -Sorting of terms of products is inhibited when Matrix mode is -turned on; in this case, Calc will never exchange the order of -two terms unless it knows at least one of the terms is a scalar. - -Products of powers are distributed by comparing all pairs of -terms, using the same method that the default simplifications -use for adjacent terms of products. - -Even though sums are not sorted, the commutative law is still -taken into account when terms of a product are being compared. -Thus @expr{(x + y) (y + x)} will be simplified to @expr{(x + y)^2}. -A subtle point is that @expr{(x - y) (y - x)} will @emph{not} -be simplified to @expr{-(x - y)^2}; Calc does not notice that -one term can be written as a constant times the other, even if -that constant is @mathit{-1}. - -A fraction times any expression, @expr{(a:b) x}, is changed to -a quotient involving integers: @expr{a x / b}. This is not -done for floating-point numbers like @expr{0.5}, however. This -is one reason why you may find it convenient to turn Fraction mode -on while doing algebra; @pxref{Fraction Mode}. - -@tex -\bigskip -@end tex - -Quotients are simplified by comparing all terms in the numerator -with all terms in the denominator for possible cancellation using -the distributive law. For example, @expr{a x^2 b / c x^3 d} will -cancel @expr{x^2} from the top and bottom to get @expr{a b / c x d}. -(The terms in the denominator will then be rearranged to @expr{c d x} -as described above.) If there is any common integer or fractional -factor in the numerator and denominator, it is canceled out; -for example, @expr{(4 x + 6) / 8 x} simplifies to @expr{(2 x + 3) / 4 x}. - -Non-constant common factors are not found even by @kbd{a s}. To -cancel the factor @expr{a} in @expr{(a x + a) / a^2} you could first -use @kbd{j M} on the product @expr{a x} to Merge the numerator to -@expr{a (1+x)}, which can then be simplified successfully. - -@tex -\bigskip -@end tex - -Integer powers of the variable @code{i} are simplified according -to the identity @expr{i^2 = -1}. If you store a new value other -than the complex number @expr{(0,1)} in @code{i}, this simplification -will no longer occur. This is done by @kbd{a s} instead of by default -in case someone (unwisely) uses the name @code{i} for a variable -unrelated to complex numbers; it would be unfortunate if Calc -quietly and automatically changed this formula for reasons the -user might not have been thinking of. - -Square roots of integer or rational arguments are simplified in -several ways. (Note that these will be left unevaluated only in -Symbolic mode.) First, square integer or rational factors are -pulled out so that @expr{@tfn{sqrt}(8)} is rewritten as -@texline @math{2\,@tfn{sqrt}(2)}. -@infoline @expr{2 sqrt(2)}. -Conceptually speaking this implies factoring the argument into primes -and moving pairs of primes out of the square root, but for reasons of -efficiency Calc only looks for primes up to 29. - -Square roots in the denominator of a quotient are moved to the -numerator: @expr{1 / @tfn{sqrt}(3)} changes to @expr{@tfn{sqrt}(3) / 3}. -The same effect occurs for the square root of a fraction: -@expr{@tfn{sqrt}(2:3)} changes to @expr{@tfn{sqrt}(6) / 3}. - -@tex -\bigskip -@end tex - -The @code{%} (modulo) operator is simplified in several ways -when the modulus @expr{M} is a positive real number. First, if -the argument is of the form @expr{x + n} for some real number -@expr{n}, then @expr{n} is itself reduced modulo @expr{M}. For -example, @samp{(x - 23) % 10} is simplified to @samp{(x + 7) % 10}. - -If the argument is multiplied by a constant, and this constant -has a common integer divisor with the modulus, then this factor is -canceled out. For example, @samp{12 x % 15} is changed to -@samp{3 (4 x % 5)} by factoring out 3. Also, @samp{(12 x + 1) % 15} -is changed to @samp{3 ((4 x + 1:3) % 5)}. While these forms may -not seem ``simpler,'' they allow Calc to discover useful information -about modulo forms in the presence of declarations. - -If the modulus is 1, then Calc can use @code{int} declarations to -evaluate the expression. For example, the idiom @samp{x % 2} is -often used to check whether a number is odd or even. As described -above, @w{@samp{2 n % 2}} and @samp{(2 n + 1) % 2} are simplified to -@samp{2 (n % 1)} and @samp{2 ((n + 1:2) % 1)}, respectively; Calc -can simplify these to 0 and 1 (respectively) if @code{n} has been -declared to be an integer. - -@tex -\bigskip -@end tex - -Trigonometric functions are simplified in several ways. Whenever a -products of two trigonometric functions can be replaced by a single -function, the replacement is made; for example, -@expr{@tfn{tan}(x) @tfn{cos}(x)} is simplified to @expr{@tfn{sin}(x)}. -Reciprocals of trigonometric functions are replaced by their reciprocal -function; for example, @expr{1/@tfn{sec}(x)} is simplified to -@expr{@tfn{cos}(x)}. The corresponding simplifications for the -hyperbolic functions are also handled. - -Trigonometric functions of their inverse functions are -simplified. The expression @expr{@tfn{sin}(@tfn{arcsin}(x))} is -simplified to @expr{x}, and similarly for @code{cos} and @code{tan}. -Trigonometric functions of inverses of different trigonometric -functions can also be simplified, as in @expr{@tfn{sin}(@tfn{arccos}(x))} -to @expr{@tfn{sqrt}(1 - x^2)}. - -If the argument to @code{sin} is negative-looking, it is simplified to -@expr{-@tfn{sin}(x)}, and similarly for @code{cos} and @code{tan}. -Finally, certain special values of the argument are recognized; -@pxref{Trigonometric and Hyperbolic Functions}. - -Hyperbolic functions of their inverses and of negative-looking -arguments are also handled, as are exponentials of inverse -hyperbolic functions. - -No simplifications for inverse trigonometric and hyperbolic -functions are known, except for negative arguments of @code{arcsin}, -@code{arctan}, @code{arcsinh}, and @code{arctanh}. Note that -@expr{@tfn{arcsin}(@tfn{sin}(x))} can @emph{not} safely change to -@expr{x}, since this only correct within an integer multiple of -@texline @math{2 \pi} -@infoline @expr{2 pi} -radians or 360 degrees. However, @expr{@tfn{arcsinh}(@tfn{sinh}(x))} is -simplified to @expr{x} if @expr{x} is known to be real. - -Several simplifications that apply to logarithms and exponentials -are that @expr{@tfn{exp}(@tfn{ln}(x))}, -@texline @tfn{e}@math{^{\ln(x)}}, -@infoline @expr{e^@tfn{ln}(x)}, -and -@texline @math{10^{{\rm log10}(x)}} -@infoline @expr{10^@tfn{log10}(x)} -all reduce to @expr{x}. Also, @expr{@tfn{ln}(@tfn{exp}(x))}, etc., can -reduce to @expr{x} if @expr{x} is provably real. The form -@expr{@tfn{exp}(x)^y} is simplified to @expr{@tfn{exp}(x y)}. If @expr{x} -is a suitable multiple of -@texline @math{\pi i} -@infoline @expr{pi i} -(as described above for the trigonometric functions), then -@expr{@tfn{exp}(x)} or @expr{e^x} will be expanded. Finally, -@expr{@tfn{ln}(x)} is simplified to a form involving @code{pi} and -@code{i} where @expr{x} is provably negative, positive imaginary, or -negative imaginary. - -The error functions @code{erf} and @code{erfc} are simplified when -their arguments are negative-looking or are calls to the @code{conj} -function. - -@tex -\bigskip -@end tex - -Equations and inequalities are simplified by canceling factors -of products, quotients, or sums on both sides. Inequalities -change sign if a negative multiplicative factor is canceled. -Non-constant multiplicative factors as in @expr{a b = a c} are -canceled from equations only if they are provably nonzero (generally -because they were declared so; @pxref{Declarations}). Factors -are canceled from inequalities only if they are nonzero and their -sign is known. - -Simplification also replaces an equation or inequality with -1 or 0 (``true'' or ``false'') if it can through the use of -declarations. If @expr{x} is declared to be an integer greater -than 5, then @expr{x < 3}, @expr{x = 3}, and @expr{x = 7.5} are -all simplified to 0, but @expr{x > 3} is simplified to 1. -By a similar analysis, @expr{abs(x) >= 0} is simplified to 1, -as is @expr{x^2 >= 0} if @expr{x} is known to be real. - -@node Unsafe Simplifications, Simplification of Units, Algebraic Simplifications, Simplifying Formulas -@subsection ``Unsafe'' Simplifications - -@noindent -@cindex Unsafe simplifications -@cindex Extended simplification -@kindex a e -@pindex calc-simplify-extended -@ignore -@mindex esimpl@idots -@end ignore -@tindex esimplify -The @kbd{a e} (@code{calc-simplify-extended}) [@code{esimplify}] command -is like @kbd{a s} -except that it applies some additional simplifications which are not -``safe'' in all cases. Use this only if you know the values in your -formula lie in the restricted ranges for which these simplifications -are valid. The symbolic integrator uses @kbd{a e}; -one effect of this is that the integrator's results must be used with -caution. Where an integral table will often attach conditions like -``for positive @expr{a} only,'' Calc (like most other symbolic -integration programs) will simply produce an unqualified result. - -Because @kbd{a e}'s simplifications are unsafe, it is sometimes better -to type @kbd{C-u -3 a v}, which does extended simplification only -on the top level of the formula without affecting the sub-formulas. -In fact, @kbd{C-u -3 j v} allows you to target extended simplification -to any specific part of a formula. - -The variable @code{ExtSimpRules} contains rewrites to be applied by -the @kbd{a e} command. These are applied in addition to -@code{EvalRules} and @code{AlgSimpRules}. (The @kbd{a r AlgSimpRules} -step described above is simply followed by an @kbd{a r ExtSimpRules} step.) - -Following is a complete list of ``unsafe'' simplifications performed -by @kbd{a e}. - -@tex -\bigskip -@end tex - -Inverse trigonometric or hyperbolic functions, called with their -corresponding non-inverse functions as arguments, are simplified -by @kbd{a e}. For example, @expr{@tfn{arcsin}(@tfn{sin}(x))} changes -to @expr{x}. Also, @expr{@tfn{arcsin}(@tfn{cos}(x))} and -@expr{@tfn{arccos}(@tfn{sin}(x))} both change to @expr{@tfn{pi}/2 - x}. -These simplifications are unsafe because they are valid only for -values of @expr{x} in a certain range; outside that range, values -are folded down to the 360-degree range that the inverse trigonometric -functions always produce. - -Powers of powers @expr{(x^a)^b} are simplified to -@texline @math{x^{a b}} -@infoline @expr{x^(a b)} -for all @expr{a} and @expr{b}. These results will be valid only -in a restricted range of @expr{x}; for example, in -@texline @math{(x^2)^{1:2}} -@infoline @expr{(x^2)^1:2} -the powers cancel to get @expr{x}, which is valid for positive values -of @expr{x} but not for negative or complex values. - -Similarly, @expr{@tfn{sqrt}(x^a)} and @expr{@tfn{sqrt}(x)^a} are both -simplified (possibly unsafely) to -@texline @math{x^{a/2}}. -@infoline @expr{x^(a/2)}. - -Forms like @expr{@tfn{sqrt}(1 - sin(x)^2)} are simplified to, e.g., -@expr{@tfn{cos}(x)}. Calc has identities of this sort for @code{sin}, -@code{cos}, @code{tan}, @code{sinh}, and @code{cosh}. - -Arguments of square roots are partially factored to look for -squared terms that can be extracted. For example, -@expr{@tfn{sqrt}(a^2 b^3 + a^3 b^2)} simplifies to -@expr{a b @tfn{sqrt}(a+b)}. - -The simplifications of @expr{@tfn{ln}(@tfn{exp}(x))}, -@expr{@tfn{ln}(@tfn{e}^x)}, and @expr{@tfn{log10}(10^x)} to @expr{x} are also -unsafe because of problems with principal values (although these -simplifications are safe if @expr{x} is known to be real). - -Common factors are canceled from products on both sides of an -equation, even if those factors may be zero: @expr{a x / b x} -to @expr{a / b}. Such factors are never canceled from -inequalities: Even @kbd{a e} is not bold enough to reduce -@expr{a x < b x} to @expr{a < b} (or @expr{a > b}, depending -on whether you believe @expr{x} is positive or negative). -The @kbd{a M /} command can be used to divide a factor out of -both sides of an inequality. - -@node Simplification of Units, , Unsafe Simplifications, Simplifying Formulas -@subsection Simplification of Units - -@noindent -The simplifications described in this section are applied by the -@kbd{u s} (@code{calc-simplify-units}) command. These are in addition -to the regular @kbd{a s} (but not @kbd{a e}) simplifications described -earlier. @xref{Basic Operations on Units}. - -The variable @code{UnitSimpRules} contains rewrites to be applied by -the @kbd{u s} command. These are applied in addition to @code{EvalRules} -and @code{AlgSimpRules}. - -Scalar mode is automatically put into effect when simplifying units. -@xref{Matrix Mode}. - -Sums @expr{a + b} involving units are simplified by extracting the -units of @expr{a} as if by the @kbd{u x} command (call the result -@expr{u_a}), then simplifying the expression @expr{b / u_a} -using @kbd{u b} and @kbd{u s}. If the result has units then the sum -is inconsistent and is left alone. Otherwise, it is rewritten -in terms of the units @expr{u_a}. - -If units auto-ranging mode is enabled, products or quotients in -which the first argument is a number which is out of range for the -leading unit are modified accordingly. - -When canceling and combining units in products and quotients, -Calc accounts for unit names that differ only in the prefix letter. -For example, @samp{2 km m} is simplified to @samp{2000 m^2}. -However, compatible but different units like @code{ft} and @code{in} -are not combined in this way. - -Quotients @expr{a / b} are simplified in three additional ways. First, -if @expr{b} is a number or a product beginning with a number, Calc -computes the reciprocal of this number and moves it to the numerator. - -Second, for each pair of unit names from the numerator and denominator -of a quotient, if the units are compatible (e.g., they are both -units of area) then they are replaced by the ratio between those -units. For example, in @samp{3 s in N / kg cm} the units -@samp{in / cm} will be replaced by @expr{2.54}. - -Third, if the units in the quotient exactly cancel out, so that -a @kbd{u b} command on the quotient would produce a dimensionless -number for an answer, then the quotient simplifies to that number. - -For powers and square roots, the ``unsafe'' simplifications -@expr{(a b)^c} to @expr{a^c b^c}, @expr{(a/b)^c} to @expr{a^c / b^c}, -and @expr{(a^b)^c} to -@texline @math{a^{b c}} -@infoline @expr{a^(b c)} -are done if the powers are real numbers. (These are safe in the context -of units because all numbers involved can reasonably be assumed to be -real.) - -Also, if a unit name is raised to a fractional power, and the -base units in that unit name all occur to powers which are a -multiple of the denominator of the power, then the unit name -is expanded out into its base units, which can then be simplified -according to the previous paragraph. For example, @samp{acre^1.5} -is simplified by noting that @expr{1.5 = 3:2}, that @samp{acre} -is defined in terms of @samp{m^2}, and that the 2 in the power of -@code{m} is a multiple of 2 in @expr{3:2}. Thus, @code{acre^1.5} is -replaced by approximately -@texline @math{(4046 m^2)^{1.5}} -@infoline @expr{(4046 m^2)^1.5}, -which is then changed to -@texline @math{4046^{1.5} \, (m^2)^{1.5}}, -@infoline @expr{4046^1.5 (m^2)^1.5}, -then to @expr{257440 m^3}. - -The functions @code{float}, @code{frac}, @code{clean}, @code{abs}, -as well as @code{floor} and the other integer truncation functions, -applied to unit names or products or quotients involving units, are -simplified. For example, @samp{round(1.6 in)} is changed to -@samp{round(1.6) round(in)}; the lefthand term evaluates to 2, -and the righthand term simplifies to @code{in}. - -The functions @code{sin}, @code{cos}, and @code{tan} with arguments -that have angular units like @code{rad} or @code{arcmin} are -simplified by converting to base units (radians), then evaluating -with the angular mode temporarily set to radians. - -@node Polynomials, Calculus, Simplifying Formulas, Algebra -@section Polynomials - -A @dfn{polynomial} is a sum of terms which are coefficients times -various powers of a ``base'' variable. For example, @expr{2 x^2 + 3 x - 4} -is a polynomial in @expr{x}. Some formulas can be considered -polynomials in several different variables: @expr{1 + 2 x + 3 y + 4 x y^2} -is a polynomial in both @expr{x} and @expr{y}. Polynomial coefficients -are often numbers, but they may in general be any formulas not -involving the base variable. - -@kindex a f -@pindex calc-factor -@tindex factor -The @kbd{a f} (@code{calc-factor}) [@code{factor}] command factors a -polynomial into a product of terms. For example, the polynomial -@expr{x^3 + 2 x^2 + x} is factored into @samp{x*(x+1)^2}. As another -example, @expr{a c + b d + b c + a d} is factored into the product -@expr{(a + b) (c + d)}. - -Calc currently has three algorithms for factoring. Formulas which are -linear in several variables, such as the second example above, are -merged according to the distributive law. Formulas which are -polynomials in a single variable, with constant integer or fractional -coefficients, are factored into irreducible linear and/or quadratic -terms. The first example above factors into three linear terms -(@expr{x}, @expr{x+1}, and @expr{x+1} again). Finally, formulas -which do not fit the above criteria are handled by the algebraic -rewrite mechanism. - -Calc's polynomial factorization algorithm works by using the general -root-finding command (@w{@kbd{a P}}) to solve for the roots of the -polynomial. It then looks for roots which are rational numbers -or complex-conjugate pairs, and converts these into linear and -quadratic terms, respectively. Because it uses floating-point -arithmetic, it may be unable to find terms that involve large -integers (whose number of digits approaches the current precision). -Also, irreducible factors of degree higher than quadratic are not -found, and polynomials in more than one variable are not treated. -(A more robust factorization algorithm may be included in a future -version of Calc.) - -@vindex FactorRules -@ignore -@starindex -@end ignore -@tindex thecoefs -@ignore -@starindex -@end ignore -@ignore -@mindex @idots -@end ignore -@tindex thefactors -The rewrite-based factorization method uses rules stored in the variable -@code{FactorRules}. @xref{Rewrite Rules}, for a discussion of the -operation of rewrite rules. The default @code{FactorRules} are able -to factor quadratic forms symbolically into two linear terms, -@expr{(a x + b) (c x + d)}. You can edit these rules to include other -cases if you wish. To use the rules, Calc builds the formula -@samp{thecoefs(x, [a, b, c, ...])} where @code{x} is the polynomial -base variable and @code{a}, @code{b}, etc., are polynomial coefficients -(which may be numbers or formulas). The constant term is written first, -i.e., in the @code{a} position. When the rules complete, they should have -changed the formula into the form @samp{thefactors(x, [f1, f2, f3, ...])} -where each @code{fi} should be a factored term, e.g., @samp{x - ai}. -Calc then multiplies these terms together to get the complete -factored form of the polynomial. If the rules do not change the -@code{thecoefs} call to a @code{thefactors} call, @kbd{a f} leaves the -polynomial alone on the assumption that it is unfactorable. (Note that -the function names @code{thecoefs} and @code{thefactors} are used only -as placeholders; there are no actual Calc functions by those names.) - -@kindex H a f -@tindex factors -The @kbd{H a f} [@code{factors}] command also factors a polynomial, -but it returns a list of factors instead of an expression which is the -product of the factors. Each factor is represented by a sub-vector -of the factor, and the power with which it appears. For example, -@expr{x^5 + x^4 - 33 x^3 + 63 x^2} factors to @expr{(x + 7) x^2 (x - 3)^2} -in @kbd{a f}, or to @expr{[ [x, 2], [x+7, 1], [x-3, 2] ]} in @kbd{H a f}. -If there is an overall numeric factor, it always comes first in the list. -The functions @code{factor} and @code{factors} allow a second argument -when written in algebraic form; @samp{factor(x,v)} factors @expr{x} with -respect to the specific variable @expr{v}. The default is to factor with -respect to all the variables that appear in @expr{x}. - -@kindex a c -@pindex calc-collect -@tindex collect -The @kbd{a c} (@code{calc-collect}) [@code{collect}] command rearranges a -formula as a -polynomial in a given variable, ordered in decreasing powers of that -variable. For example, given @expr{1 + 2 x + 3 y + 4 x y^2} on -the stack, @kbd{a c x} would produce @expr{(2 + 4 y^2) x + (1 + 3 y)}, -and @kbd{a c y} would produce @expr{(4 x) y^2 + 3 y + (1 + 2 x)}. -The polynomial will be expanded out using the distributive law as -necessary: Collecting @expr{x} in @expr{(x - 1)^3} produces -@expr{x^3 - 3 x^2 + 3 x - 1}. Terms not involving @expr{x} will -not be expanded. - -The ``variable'' you specify at the prompt can actually be any -expression: @kbd{a c ln(x+1)} will collect together all terms multiplied -by @samp{ln(x+1)} or integer powers thereof. If @samp{x} also appears -in the formula in a context other than @samp{ln(x+1)}, @kbd{a c} will -treat those occurrences as unrelated to @samp{ln(x+1)}, i.e., as constants. - -@kindex a x -@pindex calc-expand -@tindex expand -The @kbd{a x} (@code{calc-expand}) [@code{expand}] command expands an -expression by applying the distributive law everywhere. It applies to -products, quotients, and powers involving sums. By default, it fully -distributes all parts of the expression. With a numeric prefix argument, -the distributive law is applied only the specified number of times, then -the partially expanded expression is left on the stack. - -The @kbd{a x} and @kbd{j D} commands are somewhat redundant. Use -@kbd{a x} if you want to expand all products of sums in your formula. -Use @kbd{j D} if you want to expand a particular specified term of -the formula. There is an exactly analogous correspondence between -@kbd{a f} and @kbd{j M}. (The @kbd{j D} and @kbd{j M} commands -also know many other kinds of expansions, such as -@samp{exp(a + b) = exp(a) exp(b)}, which @kbd{a x} and @kbd{a f} -do not do.) - -Calc's automatic simplifications will sometimes reverse a partial -expansion. For example, the first step in expanding @expr{(x+1)^3} is -to write @expr{(x+1) (x+1)^2}. If @kbd{a x} stops there and tries -to put this formula onto the stack, though, Calc will automatically -simplify it back to @expr{(x+1)^3} form. The solution is to turn -simplification off first (@pxref{Simplification Modes}), or to run -@kbd{a x} without a numeric prefix argument so that it expands all -the way in one step. - -@kindex a a -@pindex calc-apart -@tindex apart -The @kbd{a a} (@code{calc-apart}) [@code{apart}] command expands a -rational function by partial fractions. A rational function is the -quotient of two polynomials; @code{apart} pulls this apart into a -sum of rational functions with simple denominators. In algebraic -notation, the @code{apart} function allows a second argument that -specifies which variable to use as the ``base''; by default, Calc -chooses the base variable automatically. - -@kindex a n -@pindex calc-normalize-rat -@tindex nrat -The @kbd{a n} (@code{calc-normalize-rat}) [@code{nrat}] command -attempts to arrange a formula into a quotient of two polynomials. -For example, given @expr{1 + (a + b/c) / d}, the result would be -@expr{(b + a c + c d) / c d}. The quotient is reduced, so that -@kbd{a n} will simplify @expr{(x^2 + 2x + 1) / (x^2 - 1)} by dividing -out the common factor @expr{x + 1}, yielding @expr{(x + 1) / (x - 1)}. - -@kindex a \ -@pindex calc-poly-div -@tindex pdiv -The @kbd{a \} (@code{calc-poly-div}) [@code{pdiv}] command divides -two polynomials @expr{u} and @expr{v}, yielding a new polynomial -@expr{q}. If several variables occur in the inputs, the inputs are -considered multivariate polynomials. (Calc divides by the variable -with the largest power in @expr{u} first, or, in the case of equal -powers, chooses the variables in alphabetical order.) For example, -dividing @expr{x^2 + 3 x + 2} by @expr{x + 2} yields @expr{x + 1}. -The remainder from the division, if any, is reported at the bottom -of the screen and is also placed in the Trail along with the quotient. - -Using @code{pdiv} in algebraic notation, you can specify the particular -variable to be used as the base: @code{pdiv(@var{a},@var{b},@var{x})}. -If @code{pdiv} is given only two arguments (as is always the case with -the @kbd{a \} command), then it does a multivariate division as outlined -above. - -@kindex a % -@pindex calc-poly-rem -@tindex prem -The @kbd{a %} (@code{calc-poly-rem}) [@code{prem}] command divides -two polynomials and keeps the remainder @expr{r}. The quotient -@expr{q} is discarded. For any formulas @expr{a} and @expr{b}, the -results of @kbd{a \} and @kbd{a %} satisfy @expr{a = q b + r}. -(This is analogous to plain @kbd{\} and @kbd{%}, which compute the -integer quotient and remainder from dividing two numbers.) - -@kindex a / -@kindex H a / -@pindex calc-poly-div-rem -@tindex pdivrem -@tindex pdivide -The @kbd{a /} (@code{calc-poly-div-rem}) [@code{pdivrem}] command -divides two polynomials and reports both the quotient and the -remainder as a vector @expr{[q, r]}. The @kbd{H a /} [@code{pdivide}] -command divides two polynomials and constructs the formula -@expr{q + r/b} on the stack. (Naturally if the remainder is zero, -this will immediately simplify to @expr{q}.) - -@kindex a g -@pindex calc-poly-gcd -@tindex pgcd -The @kbd{a g} (@code{calc-poly-gcd}) [@code{pgcd}] command computes -the greatest common divisor of two polynomials. (The GCD actually -is unique only to within a constant multiplier; Calc attempts to -choose a GCD which will be unsurprising.) For example, the @kbd{a n} -command uses @kbd{a g} to take the GCD of the numerator and denominator -of a quotient, then divides each by the result using @kbd{a \}. (The -definition of GCD ensures that this division can take place without -leaving a remainder.) - -While the polynomials used in operations like @kbd{a /} and @kbd{a g} -often have integer coefficients, this is not required. Calc can also -deal with polynomials over the rationals or floating-point reals. -Polynomials with modulo-form coefficients are also useful in many -applications; if you enter @samp{(x^2 + 3 x - 1) mod 5}, Calc -automatically transforms this into a polynomial over the field of -integers mod 5: @samp{(1 mod 5) x^2 + (3 mod 5) x + (4 mod 5)}. - -Congratulations and thanks go to Ove Ewerlid -(@code{ewerlid@@mizar.DoCS.UU.SE}), who contributed many of the -polynomial routines used in the above commands. - -@xref{Decomposing Polynomials}, for several useful functions for -extracting the individual coefficients of a polynomial. - -@node Calculus, Solving Equations, Polynomials, Algebra -@section Calculus - -@noindent -The following calculus commands do not automatically simplify their -inputs or outputs using @code{calc-simplify}. You may find it helps -to do this by hand by typing @kbd{a s} or @kbd{a e}. It may also help -to use @kbd{a x} and/or @kbd{a c} to arrange a result in the most -readable way. - -@menu -* Differentiation:: -* Integration:: -* Customizing the Integrator:: -* Numerical Integration:: -* Taylor Series:: -@end menu - -@node Differentiation, Integration, Calculus, Calculus -@subsection Differentiation - -@noindent -@kindex a d -@kindex H a d -@pindex calc-derivative -@tindex deriv -@tindex tderiv -The @kbd{a d} (@code{calc-derivative}) [@code{deriv}] command computes -the derivative of the expression on the top of the stack with respect to -some variable, which it will prompt you to enter. Normally, variables -in the formula other than the specified differentiation variable are -considered constant, i.e., @samp{deriv(y,x)} is reduced to zero. With -the Hyperbolic flag, the @code{tderiv} (total derivative) operation is used -instead, in which derivatives of variables are not reduced to zero -unless those variables are known to be ``constant,'' i.e., independent -of any other variables. (The built-in special variables like @code{pi} -are considered constant, as are variables that have been declared -@code{const}; @pxref{Declarations}.) - -With a numeric prefix argument @var{n}, this command computes the -@var{n}th derivative. - -When working with trigonometric functions, it is best to switch to -Radians mode first (with @w{@kbd{m r}}). The derivative of @samp{sin(x)} -in degrees is @samp{(pi/180) cos(x)}, probably not the expected -answer! - -If you use the @code{deriv} function directly in an algebraic formula, -you can write @samp{deriv(f,x,x0)} which represents the derivative -of @expr{f} with respect to @expr{x}, evaluated at the point -@texline @math{x=x_0}. -@infoline @expr{x=x0}. - -If the formula being differentiated contains functions which Calc does -not know, the derivatives of those functions are produced by adding -primes (apostrophe characters). For example, @samp{deriv(f(2x), x)} -produces @samp{2 f'(2 x)}, where the function @code{f'} represents the -derivative of @code{f}. - -For functions you have defined with the @kbd{Z F} command, Calc expands -the functions according to their defining formulas unless you have -also defined @code{f'} suitably. For example, suppose we define -@samp{sinc(x) = sin(x)/x} using @kbd{Z F}. If we then differentiate -the formula @samp{sinc(2 x)}, the formula will be expanded to -@samp{sin(2 x) / (2 x)} and differentiated. However, if we also -define @samp{sinc'(x) = dsinc(x)}, say, then Calc will write the -result as @samp{2 dsinc(2 x)}. @xref{Algebraic Definitions}. - -For multi-argument functions @samp{f(x,y,z)}, the derivative with respect -to the first argument is written @samp{f'(x,y,z)}; derivatives with -respect to the other arguments are @samp{f'2(x,y,z)} and @samp{f'3(x,y,z)}. -Various higher-order derivatives can be formed in the obvious way, e.g., -@samp{f'@var{}'(x)} (the second derivative of @code{f}) or -@samp{f'@var{}'2'3(x,y,z)} (@code{f} differentiated with respect to each -argument once). - -@node Integration, Customizing the Integrator, Differentiation, Calculus -@subsection Integration - -@noindent -@kindex a i -@pindex calc-integral -@tindex integ -The @kbd{a i} (@code{calc-integral}) [@code{integ}] command computes the -indefinite integral of the expression on the top of the stack with -respect to a prompted-for variable. The integrator is not guaranteed to -work for all integrable functions, but it is able to integrate several -large classes of formulas. In particular, any polynomial or rational -function (a polynomial divided by a polynomial) is acceptable. -(Rational functions don't have to be in explicit quotient form, however; -@texline @math{x/(1+x^{-2})} -@infoline @expr{x/(1+x^-2)} -is not strictly a quotient of polynomials, but it is equivalent to -@expr{x^3/(x^2+1)}, which is.) Also, square roots of terms involving -@expr{x} and @expr{x^2} may appear in rational functions being -integrated. Finally, rational functions involving trigonometric or -hyperbolic functions can be integrated. - -With an argument (@kbd{C-u a i}), this command will compute the definite -integral of the expression on top of the stack. In this case, the -command will again prompt for an integration variable, then prompt for a -lower limit and an upper limit. - -@ifnottex -If you use the @code{integ} function directly in an algebraic formula, -you can also write @samp{integ(f,x,v)} which expresses the resulting -indefinite integral in terms of variable @code{v} instead of @code{x}. -With four arguments, @samp{integ(f(x),x,a,b)} represents a definite -integral from @code{a} to @code{b}. -@end ifnottex -@tex -If you use the @code{integ} function directly in an algebraic formula, -you can also write @samp{integ(f,x,v)} which expresses the resulting -indefinite integral in terms of variable @code{v} instead of @code{x}. -With four arguments, @samp{integ(f(x),x,a,b)} represents a definite -integral $\int_a^b f(x) \, dx$. -@end tex - -Please note that the current implementation of Calc's integrator sometimes -produces results that are significantly more complex than they need to -be. For example, the integral Calc finds for -@texline @math{1/(x+\sqrt{x^2+1})} -@infoline @expr{1/(x+sqrt(x^2+1))} -is several times more complicated than the answer Mathematica -returns for the same input, although the two forms are numerically -equivalent. Also, any indefinite integral should be considered to have -an arbitrary constant of integration added to it, although Calc does not -write an explicit constant of integration in its result. For example, -Calc's solution for -@texline @math{1/(1+\tan x)} -@infoline @expr{1/(1+tan(x))} -differs from the solution given in the @emph{CRC Math Tables} by a -constant factor of -@texline @math{\pi i / 2} -@infoline @expr{pi i / 2}, -due to a different choice of constant of integration. - -The Calculator remembers all the integrals it has done. If conditions -change in a way that would invalidate the old integrals, say, a switch -from Degrees to Radians mode, then they will be thrown out. If you -suspect this is not happening when it should, use the -@code{calc-flush-caches} command; @pxref{Caches}. - -@vindex IntegLimit -Calc normally will pursue integration by substitution or integration by -parts up to 3 nested times before abandoning an approach as fruitless. -If the integrator is taking too long, you can lower this limit by storing -a number (like 2) in the variable @code{IntegLimit}. (The @kbd{s I} -command is a convenient way to edit @code{IntegLimit}.) If this variable -has no stored value or does not contain a nonnegative integer, a limit -of 3 is used. The lower this limit is, the greater the chance that Calc -will be unable to integrate a function it could otherwise handle. Raising -this limit allows the Calculator to solve more integrals, though the time -it takes may grow exponentially. You can monitor the integrator's actions -by creating an Emacs buffer called @code{*Trace*}. If such a buffer -exists, the @kbd{a i} command will write a log of its actions there. - -If you want to manipulate integrals in a purely symbolic way, you can -set the integration nesting limit to 0 to prevent all but fast -table-lookup solutions of integrals. You might then wish to define -rewrite rules for integration by parts, various kinds of substitutions, -and so on. @xref{Rewrite Rules}. - -@node Customizing the Integrator, Numerical Integration, Integration, Calculus -@subsection Customizing the Integrator - -@noindent -@vindex IntegRules -Calc has two built-in rewrite rules called @code{IntegRules} and -@code{IntegAfterRules} which you can edit to define new integration -methods. @xref{Rewrite Rules}. At each step of the integration process, -Calc wraps the current integrand in a call to the fictitious function -@samp{integtry(@var{expr},@var{var})}, where @var{expr} is the -integrand and @var{var} is the integration variable. If your rules -rewrite this to be a plain formula (not a call to @code{integtry}), then -Calc will use this formula as the integral of @var{expr}. For example, -the rule @samp{integtry(mysin(x),x) := -mycos(x)} would define a rule to -integrate a function @code{mysin} that acts like the sine function. -Then, putting @samp{4 mysin(2y+1)} on the stack and typing @kbd{a i y} -will produce the integral @samp{-2 mycos(2y+1)}. Note that Calc has -automatically made various transformations on the integral to allow it -to use your rule; integral tables generally give rules for -@samp{mysin(a x + b)}, but you don't need to use this much generality -in your @code{IntegRules}. - -@cindex Exponential integral Ei(x) -@ignore -@starindex -@end ignore -@tindex Ei -As a more serious example, the expression @samp{exp(x)/x} cannot be -integrated in terms of the standard functions, so the ``exponential -integral'' function -@texline @math{{\rm Ei}(x)} -@infoline @expr{Ei(x)} -was invented to describe it. -We can get Calc to do this integral in terms of a made-up @code{Ei} -function by adding the rule @samp{[integtry(exp(x)/x, x) := Ei(x)]} -to @code{IntegRules}. Now entering @samp{exp(2x)/x} on the stack -and typing @kbd{a i x} yields @samp{Ei(2 x)}. This new rule will -work with Calc's various built-in integration methods (such as -integration by substitution) to solve a variety of other problems -involving @code{Ei}: For example, now Calc will also be able to -integrate @samp{exp(exp(x))} and @samp{ln(ln(x))} (to get @samp{Ei(exp(x))} -and @samp{x ln(ln(x)) - Ei(ln(x))}, respectively). - -Your rule may do further integration by calling @code{integ}. For -example, @samp{integtry(twice(u),x) := twice(integ(u))} allows Calc -to integrate @samp{twice(sin(x))} to get @samp{twice(-cos(x))}. -Note that @code{integ} was called with only one argument. This notation -is allowed only within @code{IntegRules}; it means ``integrate this -with respect to the same integration variable.'' If Calc is unable -to integrate @code{u}, the integration that invoked @code{IntegRules} -also fails. Thus integrating @samp{twice(f(x))} fails, returning the -unevaluated integral @samp{integ(twice(f(x)), x)}. It is still valid -to call @code{integ} with two or more arguments, however; in this case, -if @code{u} is not integrable, @code{twice} itself will still be -integrated: If the above rule is changed to @samp{... := twice(integ(u,x))}, -then integrating @samp{twice(f(x))} will yield @samp{twice(integ(f(x),x))}. - -If a rule instead produces the formula @samp{integsubst(@var{sexpr}, -@var{svar})}, either replacing the top-level @code{integtry} call or -nested anywhere inside the expression, then Calc will apply the -substitution @samp{@var{u} = @var{sexpr}(@var{svar})} to try to -integrate the original @var{expr}. For example, the rule -@samp{sqrt(a) := integsubst(sqrt(x),x)} says that if Calc ever finds -a square root in the integrand, it should attempt the substitution -@samp{u = sqrt(x)}. (This particular rule is unnecessary because -Calc always tries ``obvious'' substitutions where @var{sexpr} actually -appears in the integrand.) The variable @var{svar} may be the same -as the @var{var} that appeared in the call to @code{integtry}, but -it need not be. - -When integrating according to an @code{integsubst}, Calc uses the -equation solver to find the inverse of @var{sexpr} (if the integrand -refers to @var{var} anywhere except in subexpressions that exactly -match @var{sexpr}). It uses the differentiator to find the derivative -of @var{sexpr} and/or its inverse (it has two methods that use one -derivative or the other). You can also specify these items by adding -extra arguments to the @code{integsubst} your rules construct; the -general form is @samp{integsubst(@var{sexpr}, @var{svar}, @var{sinv}, -@var{sprime})}, where @var{sinv} is the inverse of @var{sexpr} (still -written as a function of @var{svar}), and @var{sprime} is the -derivative of @var{sexpr} with respect to @var{svar}. If you don't -specify these things, and Calc is not able to work them out on its -own with the information it knows, then your substitution rule will -work only in very specific, simple cases. - -Calc applies @code{IntegRules} as if by @kbd{C-u 1 a r IntegRules}; -in other words, Calc stops rewriting as soon as any rule in your rule -set succeeds. (If it weren't for this, the @samp{integsubst(sqrt(x),x)} -example above would keep on adding layers of @code{integsubst} calls -forever!) - -@vindex IntegSimpRules -Another set of rules, stored in @code{IntegSimpRules}, are applied -every time the integrator uses @kbd{a s} to simplify an intermediate -result. For example, putting the rule @samp{twice(x) := 2 x} into -@code{IntegSimpRules} would tell Calc to convert the @code{twice} -function into a form it knows whenever integration is attempted. - -One more way to influence the integrator is to define a function with -the @kbd{Z F} command (@pxref{Algebraic Definitions}). Calc's -integrator automatically expands such functions according to their -defining formulas, even if you originally asked for the function to -be left unevaluated for symbolic arguments. (Certain other Calc -systems, such as the differentiator and the equation solver, also -do this.) - -@vindex IntegAfterRules -Sometimes Calc is able to find a solution to your integral, but it -expresses the result in a way that is unnecessarily complicated. If -this happens, you can either use @code{integsubst} as described -above to try to hint at a more direct path to the desired result, or -you can use @code{IntegAfterRules}. This is an extra rule set that -runs after the main integrator returns its result; basically, Calc does -an @kbd{a r IntegAfterRules} on the result before showing it to you. -(It also does an @kbd{a s}, without @code{IntegSimpRules}, after that -to further simplify the result.) For example, Calc's integrator -sometimes produces expressions of the form @samp{ln(1+x) - ln(1-x)}; -the default @code{IntegAfterRules} rewrite this into the more readable -form @samp{2 arctanh(x)}. Note that, unlike @code{IntegRules}, -@code{IntegSimpRules} and @code{IntegAfterRules} are applied any number -of times until no further changes are possible. Rewriting by -@code{IntegAfterRules} occurs only after the main integrator has -finished, not at every step as for @code{IntegRules} and -@code{IntegSimpRules}. - -@node Numerical Integration, Taylor Series, Customizing the Integrator, Calculus -@subsection Numerical Integration - -@noindent -@kindex a I -@pindex calc-num-integral -@tindex ninteg -If you want a purely numerical answer to an integration problem, you can -use the @kbd{a I} (@code{calc-num-integral}) [@code{ninteg}] command. This -command prompts for an integration variable, a lower limit, and an -upper limit. Except for the integration variable, all other variables -that appear in the integrand formula must have stored values. (A stored -value, if any, for the integration variable itself is ignored.) - -Numerical integration works by evaluating your formula at many points in -the specified interval. Calc uses an ``open Romberg'' method; this means -that it does not evaluate the formula actually at the endpoints (so that -it is safe to integrate @samp{sin(x)/x} from zero, for example). Also, -the Romberg method works especially well when the function being -integrated is fairly smooth. If the function is not smooth, Calc will -have to evaluate it at quite a few points before it can accurately -determine the value of the integral. - -Integration is much faster when the current precision is small. It is -best to set the precision to the smallest acceptable number of digits -before you use @kbd{a I}. If Calc appears to be taking too long, press -@kbd{C-g} to halt it and try a lower precision. If Calc still appears -to need hundreds of evaluations, check to make sure your function is -well-behaved in the specified interval. - -It is possible for the lower integration limit to be @samp{-inf} (minus -infinity). Likewise, the upper limit may be plus infinity. Calc -internally transforms the integral into an equivalent one with finite -limits. However, integration to or across singularities is not supported: -The integral of @samp{1/sqrt(x)} from 0 to 1 exists (it can be found -by Calc's symbolic integrator, for example), but @kbd{a I} will fail -because the integrand goes to infinity at one of the endpoints. - -@node Taylor Series, , Numerical Integration, Calculus -@subsection Taylor Series - -@noindent -@kindex a t -@pindex calc-taylor -@tindex taylor -The @kbd{a t} (@code{calc-taylor}) [@code{taylor}] command computes a -power series expansion or Taylor series of a function. You specify the -variable and the desired number of terms. You may give an expression of -the form @samp{@var{var} = @var{a}} or @samp{@var{var} - @var{a}} instead -of just a variable to produce a Taylor expansion about the point @var{a}. -You may specify the number of terms with a numeric prefix argument; -otherwise the command will prompt you for the number of terms. Note that -many series expansions have coefficients of zero for some terms, so you -may appear to get fewer terms than you asked for. - -If the @kbd{a i} command is unable to find a symbolic integral for a -function, you can get an approximation by integrating the function's -Taylor series. - -@node Solving Equations, Numerical Solutions, Calculus, Algebra -@section Solving Equations - -@noindent -@kindex a S -@pindex calc-solve-for -@tindex solve -@cindex Equations, solving -@cindex Solving equations -The @kbd{a S} (@code{calc-solve-for}) [@code{solve}] command rearranges -an equation to solve for a specific variable. An equation is an -expression of the form @expr{L = R}. For example, the command @kbd{a S x} -will rearrange @expr{y = 3x + 6} to the form, @expr{x = y/3 - 2}. If the -input is not an equation, it is treated like an equation of the -form @expr{X = 0}. - -This command also works for inequalities, as in @expr{y < 3x + 6}. -Some inequalities cannot be solved where the analogous equation could -be; for example, solving -@texline @math{a < b \, c} -@infoline @expr{a < b c} -for @expr{b} is impossible -without knowing the sign of @expr{c}. In this case, @kbd{a S} will -produce the result -@texline @math{b \mathbin{\hbox{\code{!=}}} a/c} -@infoline @expr{b != a/c} -(using the not-equal-to operator) to signify that the direction of the -inequality is now unknown. The inequality -@texline @math{a \le b \, c} -@infoline @expr{a <= b c} -is not even partially solved. @xref{Declarations}, for a way to tell -Calc that the signs of the variables in a formula are in fact known. - -Two useful commands for working with the result of @kbd{a S} are -@kbd{a .} (@pxref{Logical Operations}), which converts @expr{x = y/3 - 2} -to @expr{y/3 - 2}, and @kbd{s l} (@pxref{Let Command}) which evaluates -another formula with @expr{x} set equal to @expr{y/3 - 2}. - -@menu -* Multiple Solutions:: -* Solving Systems of Equations:: -* Decomposing Polynomials:: -@end menu - -@node Multiple Solutions, Solving Systems of Equations, Solving Equations, Solving Equations -@subsection Multiple Solutions - -@noindent -@kindex H a S -@tindex fsolve -Some equations have more than one solution. The Hyperbolic flag -(@code{H a S}) [@code{fsolve}] tells the solver to report the fully -general family of solutions. It will invent variables @code{n1}, -@code{n2}, @dots{}, which represent independent arbitrary integers, and -@code{s1}, @code{s2}, @dots{}, which represent independent arbitrary -signs (either @mathit{+1} or @mathit{-1}). If you don't use the Hyperbolic -flag, Calc will use zero in place of all arbitrary integers, and plus -one in place of all arbitrary signs. Note that variables like @code{n1} -and @code{s1} are not given any special interpretation in Calc except by -the equation solver itself. As usual, you can use the @w{@kbd{s l}} -(@code{calc-let}) command to obtain solutions for various actual values -of these variables. - -For example, @kbd{' x^2 = y @key{RET} H a S x @key{RET}} solves to -get @samp{x = s1 sqrt(y)}, indicating that the two solutions to the -equation are @samp{sqrt(y)} and @samp{-sqrt(y)}. Another way to -think about it is that the square-root operation is really a -two-valued function; since every Calc function must return a -single result, @code{sqrt} chooses to return the positive result. -Then @kbd{H a S} doctors this result using @code{s1} to indicate -the full set of possible values of the mathematical square-root. - -There is a similar phenomenon going the other direction: Suppose -we solve @samp{sqrt(y) = x} for @code{y}. Calc squares both sides -to get @samp{y = x^2}. This is correct, except that it introduces -some dubious solutions. Consider solving @samp{sqrt(y) = -3}: -Calc will report @expr{y = 9} as a valid solution, which is true -in the mathematical sense of square-root, but false (there is no -solution) for the actual Calc positive-valued @code{sqrt}. This -happens for both @kbd{a S} and @kbd{H a S}. - -@cindex @code{GenCount} variable -@vindex GenCount -@ignore -@starindex -@end ignore -@tindex an -@ignore -@starindex -@end ignore -@tindex as -If you store a positive integer in the Calc variable @code{GenCount}, -then Calc will generate formulas of the form @samp{as(@var{n})} for -arbitrary signs, and @samp{an(@var{n})} for arbitrary integers, -where @var{n} represents successive values taken by incrementing -@code{GenCount} by one. While the normal arbitrary sign and -integer symbols start over at @code{s1} and @code{n1} with each -new Calc command, the @code{GenCount} approach will give each -arbitrary value a name that is unique throughout the entire Calc -session. Also, the arbitrary values are function calls instead -of variables, which is advantageous in some cases. For example, -you can make a rewrite rule that recognizes all arbitrary signs -using a pattern like @samp{as(n)}. The @kbd{s l} command only works -on variables, but you can use the @kbd{a b} (@code{calc-substitute}) -command to substitute actual values for function calls like @samp{as(3)}. - -The @kbd{s G} (@code{calc-edit-GenCount}) command is a convenient -way to create or edit this variable. Press @kbd{C-c C-c} to finish. - -If you have not stored a value in @code{GenCount}, or if the value -in that variable is not a positive integer, the regular -@code{s1}/@code{n1} notation is used. - -@kindex I a S -@kindex H I a S -@tindex finv -@tindex ffinv -With the Inverse flag, @kbd{I a S} [@code{finv}] treats the expression -on top of the stack as a function of the specified variable and solves -to find the inverse function, written in terms of the same variable. -For example, @kbd{I a S x} inverts @expr{2x + 6} to @expr{x/2 - 3}. -You can use both Inverse and Hyperbolic [@code{ffinv}] to obtain a -fully general inverse, as described above. - -@kindex a P -@pindex calc-poly-roots -@tindex roots -Some equations, specifically polynomials, have a known, finite number -of solutions. The @kbd{a P} (@code{calc-poly-roots}) [@code{roots}] -command uses @kbd{H a S} to solve an equation in general form, then, for -all arbitrary-sign variables like @code{s1}, and all arbitrary-integer -variables like @code{n1} for which @code{n1} only usefully varies over -a finite range, it expands these variables out to all their possible -values. The results are collected into a vector, which is returned. -For example, @samp{roots(x^4 = 1, x)} returns the four solutions -@samp{[1, -1, (0, 1), (0, -1)]}. Generally an @var{n}th degree -polynomial will always have @var{n} roots on the complex plane. -(If you have given a @code{real} declaration for the solution -variable, then only the real-valued solutions, if any, will be -reported; @pxref{Declarations}.) - -Note that because @kbd{a P} uses @kbd{H a S}, it is able to deliver -symbolic solutions if the polynomial has symbolic coefficients. Also -note that Calc's solver is not able to get exact symbolic solutions -to all polynomials. Polynomials containing powers up to @expr{x^4} -can always be solved exactly; polynomials of higher degree sometimes -can be: @expr{x^6 + x^3 + 1} is converted to @expr{(x^3)^2 + (x^3) + 1}, -which can be solved for @expr{x^3} using the quadratic equation, and then -for @expr{x} by taking cube roots. But in many cases, like -@expr{x^6 + x + 1}, Calc does not know how to rewrite the polynomial -into a form it can solve. The @kbd{a P} command can still deliver a -list of numerical roots, however, provided that Symbolic mode (@kbd{m s}) -is not turned on. (If you work with Symbolic mode on, recall that the -@kbd{N} (@code{calc-eval-num}) key is a handy way to reevaluate the -formula on the stack with Symbolic mode temporarily off.) Naturally, -@kbd{a P} can only provide numerical roots if the polynomial coefficients -are all numbers (real or complex). - -@node Solving Systems of Equations, Decomposing Polynomials, Multiple Solutions, Solving Equations -@subsection Solving Systems of Equations - -@noindent -@cindex Systems of equations, symbolic -You can also use the commands described above to solve systems of -simultaneous equations. Just create a vector of equations, then -specify a vector of variables for which to solve. (You can omit -the surrounding brackets when entering the vector of variables -at the prompt.) - -For example, putting @samp{[x + y = a, x - y = b]} on the stack -and typing @kbd{a S x,y @key{RET}} produces the vector of solutions -@samp{[x = a - (a-b)/2, y = (a-b)/2]}. The result vector will -have the same length as the variables vector, and the variables -will be listed in the same order there. Note that the solutions -are not always simplified as far as possible; the solution for -@expr{x} here could be improved by an application of the @kbd{a n} -command. - -Calc's algorithm works by trying to eliminate one variable at a -time by solving one of the equations for that variable and then -substituting into the other equations. Calc will try all the -possibilities, but you can speed things up by noting that Calc -first tries to eliminate the first variable with the first -equation, then the second variable with the second equation, -and so on. It also helps to put the simpler (e.g., more linear) -equations toward the front of the list. Calc's algorithm will -solve any system of linear equations, and also many kinds of -nonlinear systems. - -@ignore -@starindex -@end ignore -@tindex elim -Normally there will be as many variables as equations. If you -give fewer variables than equations (an ``over-determined'' system -of equations), Calc will find a partial solution. For example, -typing @kbd{a S y @key{RET}} with the above system of equations -would produce @samp{[y = a - x]}. There are now several ways to -express this solution in terms of the original variables; Calc uses -the first one that it finds. You can control the choice by adding -variable specifiers of the form @samp{elim(@var{v})} to the -variables list. This says that @var{v} should be eliminated from -the equations; the variable will not appear at all in the solution. -For example, typing @kbd{a S y,elim(x)} would yield -@samp{[y = a - (b+a)/2]}. - -If the variables list contains only @code{elim} specifiers, -Calc simply eliminates those variables from the equations -and then returns the resulting set of equations. For example, -@kbd{a S elim(x)} produces @samp{[a - 2 y = b]}. Every variable -eliminated will reduce the number of equations in the system -by one. - -Again, @kbd{a S} gives you one solution to the system of -equations. If there are several solutions, you can use @kbd{H a S} -to get a general family of solutions, or, if there is a finite -number of solutions, you can use @kbd{a P} to get a list. (In -the latter case, the result will take the form of a matrix where -the rows are different solutions and the columns correspond to the -variables you requested.) - -Another way to deal with certain kinds of overdetermined systems of -equations is the @kbd{a F} command, which does least-squares fitting -to satisfy the equations. @xref{Curve Fitting}. - -@node Decomposing Polynomials, , Solving Systems of Equations, Solving Equations -@subsection Decomposing Polynomials - -@noindent -@ignore -@starindex -@end ignore -@tindex poly -The @code{poly} function takes a polynomial and a variable as -arguments, and returns a vector of polynomial coefficients (constant -coefficient first). For example, @samp{poly(x^3 + 2 x, x)} returns -@expr{[0, 2, 0, 1]}. If the input is not a polynomial in @expr{x}, -the call to @code{poly} is left in symbolic form. If the input does -not involve the variable @expr{x}, the input is returned in a list -of length one, representing a polynomial with only a constant -coefficient. The call @samp{poly(x, x)} returns the vector @expr{[0, 1]}. -The last element of the returned vector is guaranteed to be nonzero; -note that @samp{poly(0, x)} returns the empty vector @expr{[]}. -Note also that @expr{x} may actually be any formula; for example, -@samp{poly(sin(x)^2 - sin(x) + 3, sin(x))} returns @expr{[3, -1, 1]}. - -@cindex Coefficients of polynomial -@cindex Degree of polynomial -To get the @expr{x^k} coefficient of polynomial @expr{p}, use -@samp{poly(p, x)_(k+1)}. To get the degree of polynomial @expr{p}, -use @samp{vlen(poly(p, x)) - 1}. For example, @samp{poly((x+1)^4, x)} -returns @samp{[1, 4, 6, 4, 1]}, so @samp{poly((x+1)^4, x)_(2+1)} -gives the @expr{x^2} coefficient of this polynomial, 6. - -@ignore -@starindex -@end ignore -@tindex gpoly -One important feature of the solver is its ability to recognize -formulas which are ``essentially'' polynomials. This ability is -made available to the user through the @code{gpoly} function, which -is used just like @code{poly}: @samp{gpoly(@var{expr}, @var{var})}. -If @var{expr} is a polynomial in some term which includes @var{var}, then -this function will return a vector @samp{[@var{x}, @var{c}, @var{a}]} -where @var{x} is the term that depends on @var{var}, @var{c} is a -vector of polynomial coefficients (like the one returned by @code{poly}), -and @var{a} is a multiplier which is usually 1. Basically, -@samp{@var{expr} = @var{a}*(@var{c}_1 + @var{c}_2 @var{x} + -@var{c}_3 @var{x}^2 + ...)}. The last element of @var{c} is -guaranteed to be non-zero, and @var{c} will not equal @samp{[1]} -(i.e., the trivial decomposition @var{expr} = @var{x} is not -considered a polynomial). One side effect is that @samp{gpoly(x, x)} -and @samp{gpoly(6, x)}, both of which might be expected to recognize -their arguments as polynomials, will not because the decomposition -is considered trivial. - -For example, @samp{gpoly((x-2)^2, x)} returns @samp{[x, [4, -4, 1], 1]}, -since the expanded form of this polynomial is @expr{4 - 4 x + x^2}. - -The term @var{x} may itself be a polynomial in @var{var}. This is -done to reduce the size of the @var{c} vector. For example, -@samp{gpoly(x^4 + x^2 - 1, x)} returns @samp{[x^2, [-1, 1, 1], 1]}, -since a quadratic polynomial in @expr{x^2} is easier to solve than -a quartic polynomial in @expr{x}. - -A few more examples of the kinds of polynomials @code{gpoly} can -discover: - -@smallexample -sin(x) - 1 [sin(x), [-1, 1], 1] -x + 1/x - 1 [x, [1, -1, 1], 1/x] -x + 1/x [x^2, [1, 1], 1/x] -x^3 + 2 x [x^2, [2, 1], x] -x + x^2:3 + sqrt(x) [x^1:6, [1, 1, 0, 1], x^1:2] -x^(2a) + 2 x^a + 5 [x^a, [5, 2, 1], 1] -(exp(-x) + exp(x)) / 2 [e^(2 x), [0.5, 0.5], e^-x] -@end smallexample - -The @code{poly} and @code{gpoly} functions accept a third integer argument -which specifies the largest degree of polynomial that is acceptable. -If this is @expr{n}, then only @var{c} vectors of length @expr{n+1} -or less will be returned. Otherwise, the @code{poly} or @code{gpoly} -call will remain in symbolic form. For example, the equation solver -can handle quartics and smaller polynomials, so it calls -@samp{gpoly(@var{expr}, @var{var}, 4)} to discover whether @var{expr} -can be treated by its linear, quadratic, cubic, or quartic formulas. - -@ignore -@starindex -@end ignore -@tindex pdeg -The @code{pdeg} function computes the degree of a polynomial; -@samp{pdeg(p,x)} is the highest power of @code{x} that appears in -@code{p}. This is the same as @samp{vlen(poly(p,x))-1}, but is -much more efficient. If @code{p} is constant with respect to @code{x}, -then @samp{pdeg(p,x) = 0}. If @code{p} is not a polynomial in @code{x} -(e.g., @samp{pdeg(2 cos(x), x)}, the function remains unevaluated. -It is possible to omit the second argument @code{x}, in which case -@samp{pdeg(p)} returns the highest total degree of any term of the -polynomial, counting all variables that appear in @code{p}. Note -that @code{pdeg(c) = pdeg(c,x) = 0} for any nonzero constant @code{c}; -the degree of the constant zero is considered to be @code{-inf} -(minus infinity). - -@ignore -@starindex -@end ignore -@tindex plead -The @code{plead} function finds the leading term of a polynomial. -Thus @samp{plead(p,x)} is equivalent to @samp{poly(p,x)_vlen(poly(p,x))}, -though again more efficient. In particular, @samp{plead((2x+1)^10, x)} -returns 1024 without expanding out the list of coefficients. The -value of @code{plead(p,x)} will be zero only if @expr{p = 0}. - -@ignore -@starindex -@end ignore -@tindex pcont -The @code{pcont} function finds the @dfn{content} of a polynomial. This -is the greatest common divisor of all the coefficients of the polynomial. -With two arguments, @code{pcont(p,x)} effectively uses @samp{poly(p,x)} -to get a list of coefficients, then uses @code{pgcd} (the polynomial -GCD function) to combine these into an answer. For example, -@samp{pcont(4 x y^2 + 6 x^2 y, x)} is @samp{2 y}. The content is -basically the ``biggest'' polynomial that can be divided into @code{p} -exactly. The sign of the content is the same as the sign of the leading -coefficient. - -With only one argument, @samp{pcont(p)} computes the numerical -content of the polynomial, i.e., the @code{gcd} of the numerical -coefficients of all the terms in the formula. Note that @code{gcd} -is defined on rational numbers as well as integers; it computes -the @code{gcd} of the numerators and the @code{lcm} of the -denominators. Thus @samp{pcont(4:3 x y^2 + 6 x^2 y)} returns 2:3. -Dividing the polynomial by this number will clear all the -denominators, as well as dividing by any common content in the -numerators. The numerical content of a polynomial is negative only -if all the coefficients in the polynomial are negative. - -@ignore -@starindex -@end ignore -@tindex pprim -The @code{pprim} function finds the @dfn{primitive part} of a -polynomial, which is simply the polynomial divided (using @code{pdiv} -if necessary) by its content. If the input polynomial has rational -coefficients, the result will have integer coefficients in simplest -terms. - -@node Numerical Solutions, Curve Fitting, Solving Equations, Algebra -@section Numerical Solutions - -@noindent -Not all equations can be solved symbolically. The commands in this -section use numerical algorithms that can find a solution to a specific -instance of an equation to any desired accuracy. Note that the -numerical commands are slower than their algebraic cousins; it is a -good idea to try @kbd{a S} before resorting to these commands. - -(@xref{Curve Fitting}, for some other, more specialized, operations -on numerical data.) - -@menu -* Root Finding:: -* Minimization:: -* Numerical Systems of Equations:: -@end menu - -@node Root Finding, Minimization, Numerical Solutions, Numerical Solutions -@subsection Root Finding - -@noindent -@kindex a R -@pindex calc-find-root -@tindex root -@cindex Newton's method -@cindex Roots of equations -@cindex Numerical root-finding -The @kbd{a R} (@code{calc-find-root}) [@code{root}] command finds a -numerical solution (or @dfn{root}) of an equation. (This command treats -inequalities the same as equations. If the input is any other kind -of formula, it is interpreted as an equation of the form @expr{X = 0}.) - -The @kbd{a R} command requires an initial guess on the top of the -stack, and a formula in the second-to-top position. It prompts for a -solution variable, which must appear in the formula. All other variables -that appear in the formula must have assigned values, i.e., when -a value is assigned to the solution variable and the formula is -evaluated with @kbd{=}, it should evaluate to a number. Any assigned -value for the solution variable itself is ignored and unaffected by -this command. - -When the command completes, the initial guess is replaced on the stack -by a vector of two numbers: The value of the solution variable that -solves the equation, and the difference between the lefthand and -righthand sides of the equation at that value. Ordinarily, the second -number will be zero or very nearly zero. (Note that Calc uses a -slightly higher precision while finding the root, and thus the second -number may be slightly different from the value you would compute from -the equation yourself.) - -The @kbd{v h} (@code{calc-head}) command is a handy way to extract -the first element of the result vector, discarding the error term. - -The initial guess can be a real number, in which case Calc searches -for a real solution near that number, or a complex number, in which -case Calc searches the whole complex plane near that number for a -solution, or it can be an interval form which restricts the search -to real numbers inside that interval. - -Calc tries to use @kbd{a d} to take the derivative of the equation. -If this succeeds, it uses Newton's method. If the equation is not -differentiable Calc uses a bisection method. (If Newton's method -appears to be going astray, Calc switches over to bisection if it -can, or otherwise gives up. In this case it may help to try again -with a slightly different initial guess.) If the initial guess is a -complex number, the function must be differentiable. - -If the formula (or the difference between the sides of an equation) -is negative at one end of the interval you specify and positive at -the other end, the root finder is guaranteed to find a root. -Otherwise, Calc subdivides the interval into small parts looking for -positive and negative values to bracket the root. When your guess is -an interval, Calc will not look outside that interval for a root. - -@kindex H a R -@tindex wroot -The @kbd{H a R} [@code{wroot}] command is similar to @kbd{a R}, except -that if the initial guess is an interval for which the function has -the same sign at both ends, then rather than subdividing the interval -Calc attempts to widen it to enclose a root. Use this mode if -you are not sure if the function has a root in your interval. - -If the function is not differentiable, and you give a simple number -instead of an interval as your initial guess, Calc uses this widening -process even if you did not type the Hyperbolic flag. (If the function -@emph{is} differentiable, Calc uses Newton's method which does not -require a bounding interval in order to work.) - -If Calc leaves the @code{root} or @code{wroot} function in symbolic -form on the stack, it will normally display an explanation for why -no root was found. If you miss this explanation, press @kbd{w} -(@code{calc-why}) to get it back. - -@node Minimization, Numerical Systems of Equations, Root Finding, Numerical Solutions -@subsection Minimization - -@noindent -@kindex a N -@kindex H a N -@kindex a X -@kindex H a X -@pindex calc-find-minimum -@pindex calc-find-maximum -@tindex minimize -@tindex maximize -@cindex Minimization, numerical -The @kbd{a N} (@code{calc-find-minimum}) [@code{minimize}] command -finds a minimum value for a formula. It is very similar in operation -to @kbd{a R} (@code{calc-find-root}): You give the formula and an initial -guess on the stack, and are prompted for the name of a variable. The guess -may be either a number near the desired minimum, or an interval enclosing -the desired minimum. The function returns a vector containing the -value of the variable which minimizes the formula's value, along -with the minimum value itself. - -Note that this command looks for a @emph{local} minimum. Many functions -have more than one minimum; some, like -@texline @math{x \sin x}, -@infoline @expr{x sin(x)}, -have infinitely many. In fact, there is no easy way to define the -``global'' minimum of -@texline @math{x \sin x} -@infoline @expr{x sin(x)} -but Calc can still locate any particular local minimum -for you. Calc basically goes downhill from the initial guess until it -finds a point at which the function's value is greater both to the left -and to the right. Calc does not use derivatives when minimizing a function. - -If your initial guess is an interval and it looks like the minimum -occurs at one or the other endpoint of the interval, Calc will return -that endpoint only if that endpoint is closed; thus, minimizing @expr{17 x} -over @expr{[2..3]} will return @expr{[2, 38]}, but minimizing over -@expr{(2..3]} would report no minimum found. In general, you should -use closed intervals to find literally the minimum value in that -range of @expr{x}, or open intervals to find the local minimum, if -any, that happens to lie in that range. - -Most functions are smooth and flat near their minimum values. Because -of this flatness, if the current precision is, say, 12 digits, the -variable can only be determined meaningfully to about six digits. Thus -you should set the precision to twice as many digits as you need in your -answer. - -@ignore -@mindex wmin@idots -@end ignore -@tindex wminimize -@ignore -@mindex wmax@idots -@end ignore -@tindex wmaximize -The @kbd{H a N} [@code{wminimize}] command, analogously to @kbd{H a R}, -expands the guess interval to enclose a minimum rather than requiring -that the minimum lie inside the interval you supply. - -The @kbd{a X} (@code{calc-find-maximum}) [@code{maximize}] and -@kbd{H a X} [@code{wmaximize}] commands effectively minimize the -negative of the formula you supply. - -The formula must evaluate to a real number at all points inside the -interval (or near the initial guess if the guess is a number). If -the initial guess is a complex number the variable will be minimized -over the complex numbers; if it is real or an interval it will -be minimized over the reals. - -@node Numerical Systems of Equations, , Minimization, Numerical Solutions -@subsection Systems of Equations - -@noindent -@cindex Systems of equations, numerical -The @kbd{a R} command can also solve systems of equations. In this -case, the equation should instead be a vector of equations, the -guess should instead be a vector of numbers (intervals are not -supported), and the variable should be a vector of variables. You -can omit the brackets while entering the list of variables. Each -equation must be differentiable by each variable for this mode to -work. The result will be a vector of two vectors: The variable -values that solved the system of equations, and the differences -between the sides of the equations with those variable values. -There must be the same number of equations as variables. Since -only plain numbers are allowed as guesses, the Hyperbolic flag has -no effect when solving a system of equations. - -It is also possible to minimize over many variables with @kbd{a N} -(or maximize with @kbd{a X}). Once again the variable name should -be replaced by a vector of variables, and the initial guess should -be an equal-sized vector of initial guesses. But, unlike the case of -multidimensional @kbd{a R}, the formula being minimized should -still be a single formula, @emph{not} a vector. Beware that -multidimensional minimization is currently @emph{very} slow. - -@node Curve Fitting, Summations, Numerical Solutions, Algebra -@section Curve Fitting - -@noindent -The @kbd{a F} command fits a set of data to a @dfn{model formula}, -such as @expr{y = m x + b} where @expr{m} and @expr{b} are parameters -to be determined. For a typical set of measured data there will be -no single @expr{m} and @expr{b} that exactly fit the data; in this -case, Calc chooses values of the parameters that provide the closest -possible fit. The model formula can be entered in various ways after -the key sequence @kbd{a F} is pressed. - -If the letter @kbd{P} is pressed after @kbd{a F} but before the model -description is entered, the data as well as the model formula will be -plotted after the formula is determined. This will be indicated by a -``P'' in the minibuffer after the help message. - -@menu -* Linear Fits:: -* Polynomial and Multilinear Fits:: -* Error Estimates for Fits:: -* Standard Nonlinear Models:: -* Curve Fitting Details:: -* Interpolation:: -@end menu - -@node Linear Fits, Polynomial and Multilinear Fits, Curve Fitting, Curve Fitting -@subsection Linear Fits - -@noindent -@kindex a F -@pindex calc-curve-fit -@tindex fit -@cindex Linear regression -@cindex Least-squares fits -The @kbd{a F} (@code{calc-curve-fit}) [@code{fit}] command attempts -to fit a set of data (@expr{x} and @expr{y} vectors of numbers) to a -straight line, polynomial, or other function of @expr{x}. For the -moment we will consider only the case of fitting to a line, and we -will ignore the issue of whether or not the model was in fact a good -fit for the data. - -In a standard linear least-squares fit, we have a set of @expr{(x,y)} -data points that we wish to fit to the model @expr{y = m x + b} -by adjusting the parameters @expr{m} and @expr{b} to make the @expr{y} -values calculated from the formula be as close as possible to the actual -@expr{y} values in the data set. (In a polynomial fit, the model is -instead, say, @expr{y = a x^3 + b x^2 + c x + d}. In a multilinear fit, -we have data points of the form @expr{(x_1,x_2,x_3,y)} and our model is -@expr{y = a x_1 + b x_2 + c x_3 + d}. These will be discussed later.) - -In the model formula, variables like @expr{x} and @expr{x_2} are called -the @dfn{independent variables}, and @expr{y} is the @dfn{dependent -variable}. Variables like @expr{m}, @expr{a}, and @expr{b} are called -the @dfn{parameters} of the model. - -The @kbd{a F} command takes the data set to be fitted from the stack. -By default, it expects the data in the form of a matrix. For example, -for a linear or polynomial fit, this would be a -@texline @math{2\times N} -@infoline 2xN -matrix where the first row is a list of @expr{x} values and the second -row has the corresponding @expr{y} values. For the multilinear fit -shown above, the matrix would have four rows (@expr{x_1}, @expr{x_2}, -@expr{x_3}, and @expr{y}, respectively). - -If you happen to have an -@texline @math{N\times2} -@infoline Nx2 -matrix instead of a -@texline @math{2\times N} -@infoline 2xN -matrix, just press @kbd{v t} first to transpose the matrix. - -After you type @kbd{a F}, Calc prompts you to select a model. For a -linear fit, press the digit @kbd{1}. - -Calc then prompts for you to name the variables. By default it chooses -high letters like @expr{x} and @expr{y} for independent variables and -low letters like @expr{a} and @expr{b} for parameters. (The dependent -variable doesn't need a name.) The two kinds of variables are separated -by a semicolon. Since you generally care more about the names of the -independent variables than of the parameters, Calc also allows you to -name only those and let the parameters use default names. - -For example, suppose the data matrix - -@ifnottex -@example -@group -[ [ 1, 2, 3, 4, 5 ] - [ 5, 7, 9, 11, 13 ] ] -@end group -@end example -@end ifnottex -@tex -\beforedisplay -$$ \pmatrix{ 1 & 2 & 3 & 4 & 5 \cr - 5 & 7 & 9 & 11 & 13 } -$$ -\afterdisplay -@end tex - -@noindent -is on the stack and we wish to do a simple linear fit. Type -@kbd{a F}, then @kbd{1} for the model, then @key{RET} to use -the default names. The result will be the formula @expr{3. + 2. x} -on the stack. Calc has created the model expression @kbd{a + b x}, -then found the optimal values of @expr{a} and @expr{b} to fit the -data. (In this case, it was able to find an exact fit.) Calc then -substituted those values for @expr{a} and @expr{b} in the model -formula. - -The @kbd{a F} command puts two entries in the trail. One is, as -always, a copy of the result that went to the stack; the other is -a vector of the actual parameter values, written as equations: -@expr{[a = 3, b = 2]}, in case you'd rather read them in a list -than pick them out of the formula. (You can type @kbd{t y} -to move this vector to the stack; see @ref{Trail Commands}. - -Specifying a different independent variable name will affect the -resulting formula: @kbd{a F 1 k @key{RET}} produces @kbd{3 + 2 k}. -Changing the parameter names (say, @kbd{a F 1 k;b,m @key{RET}}) will affect -the equations that go into the trail. - -@tex -\bigskip -@end tex - -To see what happens when the fit is not exact, we could change -the number 13 in the data matrix to 14 and try the fit again. -The result is: - -@example -2.6 + 2.2 x -@end example - -Evaluating this formula, say with @kbd{v x 5 @key{RET} @key{TAB} V M $ @key{RET}}, shows -a reasonably close match to the y-values in the data. - -@example -[4.8, 7., 9.2, 11.4, 13.6] -@end example - -Since there is no line which passes through all the @var{n} data points, -Calc has chosen a line that best approximates the data points using -the method of least squares. The idea is to define the @dfn{chi-square} -error measure - -@ifnottex -@example -chi^2 = sum((y_i - (a + b x_i))^2, i, 1, N) -@end example -@end ifnottex -@tex -\beforedisplay -$$ \chi^2 = \sum_{i=1}^N (y_i - (a + b x_i))^2 $$ -\afterdisplay -@end tex - -@noindent -which is clearly zero if @expr{a + b x} exactly fits all data points, -and increases as various @expr{a + b x_i} values fail to match the -corresponding @expr{y_i} values. There are several reasons why the -summand is squared, one of them being to ensure that -@texline @math{\chi^2 \ge 0}. -@infoline @expr{chi^2 >= 0}. -Least-squares fitting simply chooses the values of @expr{a} and @expr{b} -for which the error -@texline @math{\chi^2} -@infoline @expr{chi^2} -is as small as possible. - -Other kinds of models do the same thing but with a different model -formula in place of @expr{a + b x_i}. - -@tex -\bigskip -@end tex - -A numeric prefix argument causes the @kbd{a F} command to take the -data in some other form than one big matrix. A positive argument @var{n} -will take @var{N} items from the stack, corresponding to the @var{n} rows -of a data matrix. In the linear case, @var{n} must be 2 since there -is always one independent variable and one dependent variable. - -A prefix of zero or plain @kbd{C-u} is a compromise; Calc takes two -items from the stack, an @var{n}-row matrix of @expr{x} values, and a -vector of @expr{y} values. If there is only one independent variable, -the @expr{x} values can be either a one-row matrix or a plain vector, -in which case the @kbd{C-u} prefix is the same as a @w{@kbd{C-u 2}} prefix. - -@node Polynomial and Multilinear Fits, Error Estimates for Fits, Linear Fits, Curve Fitting -@subsection Polynomial and Multilinear Fits - -@noindent -To fit the data to higher-order polynomials, just type one of the -digits @kbd{2} through @kbd{9} when prompted for a model. For example, -we could fit the original data matrix from the previous section -(with 13, not 14) to a parabola instead of a line by typing -@kbd{a F 2 @key{RET}}. - -@example -2.00000000001 x - 1.5e-12 x^2 + 2.99999999999 -@end example - -Note that since the constant and linear terms are enough to fit the -data exactly, it's no surprise that Calc chose a tiny contribution -for @expr{x^2}. (The fact that it's not exactly zero is due only -to roundoff error. Since our data are exact integers, we could get -an exact answer by typing @kbd{m f} first to get Fraction mode. -Then the @expr{x^2} term would vanish altogether. Usually, though, -the data being fitted will be approximate floats so Fraction mode -won't help.) - -Doing the @kbd{a F 2} fit on the data set with 14 instead of 13 -gives a much larger @expr{x^2} contribution, as Calc bends the -line slightly to improve the fit. - -@example -0.142857142855 x^2 + 1.34285714287 x + 3.59999999998 -@end example - -An important result from the theory of polynomial fitting is that it -is always possible to fit @var{n} data points exactly using a polynomial -of degree @mathit{@var{n}-1}, sometimes called an @dfn{interpolating polynomial}. -Using the modified (14) data matrix, a model number of 4 gives -a polynomial that exactly matches all five data points: - -@example -0.04167 x^4 - 0.4167 x^3 + 1.458 x^2 - 0.08333 x + 4. -@end example - -The actual coefficients we get with a precision of 12, like -@expr{0.0416666663588}, clearly suffer from loss of precision. -It is a good idea to increase the working precision to several -digits beyond what you need when you do a fitting operation. -Or, if your data are exact, use Fraction mode to get exact -results. - -You can type @kbd{i} instead of a digit at the model prompt to fit -the data exactly to a polynomial. This just counts the number of -columns of the data matrix to choose the degree of the polynomial -automatically. - -Fitting data ``exactly'' to high-degree polynomials is not always -a good idea, though. High-degree polynomials have a tendency to -wiggle uncontrollably in between the fitting data points. Also, -if the exact-fit polynomial is going to be used to interpolate or -extrapolate the data, it is numerically better to use the @kbd{a p} -command described below. @xref{Interpolation}. - -@tex -\bigskip -@end tex - -Another generalization of the linear model is to assume the -@expr{y} values are a sum of linear contributions from several -@expr{x} values. This is a @dfn{multilinear} fit, and it is also -selected by the @kbd{1} digit key. (Calc decides whether the fit -is linear or multilinear by counting the rows in the data matrix.) - -Given the data matrix, - -@example -@group -[ [ 1, 2, 3, 4, 5 ] - [ 7, 2, 3, 5, 2 ] - [ 14.5, 15, 18.5, 22.5, 24 ] ] -@end group -@end example - -@noindent -the command @kbd{a F 1 @key{RET}} will call the first row @expr{x} and the -second row @expr{y}, and will fit the values in the third row to the -model @expr{a + b x + c y}. - -@example -8. + 3. x + 0.5 y -@end example - -Calc can do multilinear fits with any number of independent variables -(i.e., with any number of data rows). - -@tex -\bigskip -@end tex - -Yet another variation is @dfn{homogeneous} linear models, in which -the constant term is known to be zero. In the linear case, this -means the model formula is simply @expr{a x}; in the multilinear -case, the model might be @expr{a x + b y + c z}; and in the polynomial -case, the model could be @expr{a x + b x^2 + c x^3}. You can get -a homogeneous linear or multilinear model by pressing the letter -@kbd{h} followed by a regular model key, like @kbd{1} or @kbd{2}. -This will be indicated by an ``h'' in the minibuffer after the help -message. - -It is certainly possible to have other constrained linear models, -like @expr{2.3 + a x} or @expr{a - 4 x}. While there is no single -key to select models like these, a later section shows how to enter -any desired model by hand. In the first case, for example, you -would enter @kbd{a F ' 2.3 + a x}. - -Another class of models that will work but must be entered by hand -are multinomial fits, e.g., @expr{a + b x + c y + d x^2 + e y^2 + f x y}. - -@node Error Estimates for Fits, Standard Nonlinear Models, Polynomial and Multilinear Fits, Curve Fitting -@subsection Error Estimates for Fits - -@noindent -@kindex H a F -@tindex efit -With the Hyperbolic flag, @kbd{H a F} [@code{efit}] performs the same -fitting operation as @kbd{a F}, but reports the coefficients as error -forms instead of plain numbers. Fitting our two data matrices (first -with 13, then with 14) to a line with @kbd{H a F} gives the results, - -@example -3. + 2. x -2.6 +/- 0.382970843103 + 2.2 +/- 0.115470053838 x -@end example - -In the first case the estimated errors are zero because the linear -fit is perfect. In the second case, the errors are nonzero but -moderately small, because the data are still very close to linear. - -It is also possible for the @emph{input} to a fitting operation to -contain error forms. The data values must either all include errors -or all be plain numbers. Error forms can go anywhere but generally -go on the numbers in the last row of the data matrix. If the last -row contains error forms -@texline `@var{y_i}@w{ @tfn{+/-} }@math{\sigma_i}', -@infoline `@var{y_i}@w{ @tfn{+/-} }@var{sigma_i}', -then the -@texline @math{\chi^2} -@infoline @expr{chi^2} -statistic is now, - -@ifnottex -@example -chi^2 = sum(((y_i - (a + b x_i)) / sigma_i)^2, i, 1, N) -@end example -@end ifnottex -@tex -\beforedisplay -$$ \chi^2 = \sum_{i=1}^N \left(y_i - (a + b x_i) \over \sigma_i\right)^2 $$ -\afterdisplay -@end tex - -@noindent -so that data points with larger error estimates contribute less to -the fitting operation. - -If there are error forms on other rows of the data matrix, all the -errors for a given data point are combined; the square root of the -sum of the squares of the errors forms the -@texline @math{\sigma_i} -@infoline @expr{sigma_i} -used for the data point. - -Both @kbd{a F} and @kbd{H a F} can accept error forms in the input -matrix, although if you are concerned about error analysis you will -probably use @kbd{H a F} so that the output also contains error -estimates. - -If the input contains error forms but all the -@texline @math{\sigma_i} -@infoline @expr{sigma_i} -values are the same, it is easy to see that the resulting fitted model -will be the same as if the input did not have error forms at all -@texline (@math{\chi^2} -@infoline (@expr{chi^2} -is simply scaled uniformly by -@texline @math{1 / \sigma^2}, -@infoline @expr{1 / sigma^2}, -which doesn't affect where it has a minimum). But there @emph{will} be -a difference in the estimated errors of the coefficients reported by -@kbd{H a F}. - -Consult any text on statistical modeling of data for a discussion -of where these error estimates come from and how they should be -interpreted. - -@tex -\bigskip -@end tex - -@kindex I a F -@tindex xfit -With the Inverse flag, @kbd{I a F} [@code{xfit}] produces even more -information. The result is a vector of six items: - -@enumerate -@item -The model formula with error forms for its coefficients or -parameters. This is the result that @kbd{H a F} would have -produced. - -@item -A vector of ``raw'' parameter values for the model. These are the -polynomial coefficients or other parameters as plain numbers, in the -same order as the parameters appeared in the final prompt of the -@kbd{I a F} command. For polynomials of degree @expr{d}, this vector -will have length @expr{M = d+1} with the constant term first. - -@item -The covariance matrix @expr{C} computed from the fit. This is -an @var{m}x@var{m} symmetric matrix; the diagonal elements -@texline @math{C_{jj}} -@infoline @expr{C_j_j} -are the variances -@texline @math{\sigma_j^2} -@infoline @expr{sigma_j^2} -of the parameters. The other elements are covariances -@texline @math{\sigma_{ij}^2} -@infoline @expr{sigma_i_j^2} -that describe the correlation between pairs of parameters. (A related -set of numbers, the @dfn{linear correlation coefficients} -@texline @math{r_{ij}}, -@infoline @expr{r_i_j}, -are defined as -@texline @math{\sigma_{ij}^2 / \sigma_i \, \sigma_j}.) -@infoline @expr{sigma_i_j^2 / sigma_i sigma_j}.) - -@item -A vector of @expr{M} ``parameter filter'' functions whose -meanings are described below. If no filters are necessary this -will instead be an empty vector; this is always the case for the -polynomial and multilinear fits described so far. - -@item -The value of -@texline @math{\chi^2} -@infoline @expr{chi^2} -for the fit, calculated by the formulas shown above. This gives a -measure of the quality of the fit; statisticians consider -@texline @math{\chi^2 \approx N - M} -@infoline @expr{chi^2 = N - M} -to indicate a moderately good fit (where again @expr{N} is the number of -data points and @expr{M} is the number of parameters). - -@item -A measure of goodness of fit expressed as a probability @expr{Q}. -This is computed from the @code{utpc} probability distribution -function using -@texline @math{\chi^2} -@infoline @expr{chi^2} -with @expr{N - M} degrees of freedom. A -value of 0.5 implies a good fit; some texts recommend that often -@expr{Q = 0.1} or even 0.001 can signify an acceptable fit. In -particular, -@texline @math{\chi^2} -@infoline @expr{chi^2} -statistics assume the errors in your inputs -follow a normal (Gaussian) distribution; if they don't, you may -have to accept smaller values of @expr{Q}. - -The @expr{Q} value is computed only if the input included error -estimates. Otherwise, Calc will report the symbol @code{nan} -for @expr{Q}. The reason is that in this case the -@texline @math{\chi^2} -@infoline @expr{chi^2} -value has effectively been used to estimate the original errors -in the input, and thus there is no redundant information left -over to use for a confidence test. -@end enumerate - -@node Standard Nonlinear Models, Curve Fitting Details, Error Estimates for Fits, Curve Fitting -@subsection Standard Nonlinear Models - -@noindent -The @kbd{a F} command also accepts other kinds of models besides -lines and polynomials. Some common models have quick single-key -abbreviations; others must be entered by hand as algebraic formulas. - -Here is a complete list of the standard models recognized by @kbd{a F}: - -@table @kbd -@item 1 -Linear or multilinear. @mathit{a + b x + c y + d z}. -@item 2-9 -Polynomials. @mathit{a + b x + c x^2 + d x^3}. -@item e -Exponential. @mathit{a} @tfn{exp}@mathit{(b x)} @tfn{exp}@mathit{(c y)}. -@item E -Base-10 exponential. @mathit{a} @tfn{10^}@mathit{(b x)} @tfn{10^}@mathit{(c y)}. -@item x -Exponential (alternate notation). @tfn{exp}@mathit{(a + b x + c y)}. -@item X -Base-10 exponential (alternate). @tfn{10^}@mathit{(a + b x + c y)}. -@item l -Logarithmic. @mathit{a + b} @tfn{ln}@mathit{(x) + c} @tfn{ln}@mathit{(y)}. -@item L -Base-10 logarithmic. @mathit{a + b} @tfn{log10}@mathit{(x) + c} @tfn{log10}@mathit{(y)}. -@item ^ -General exponential. @mathit{a b^x c^y}. -@item p -Power law. @mathit{a x^b y^c}. -@item q -Quadratic. @mathit{a + b (x-c)^2 + d (x-e)^2}. -@item g -Gaussian. -@texline @math{{a \over b \sqrt{2 \pi}} \exp\left( -{1 \over 2} \left( x - c \over b \right)^2 \right)}. -@infoline @mathit{(a / b sqrt(2 pi)) exp(-0.5*((x-c)/b)^2)}. -@item s -Logistic @emph{s} curve. -@texline @math{a/(1+e^{b(x-c)})}. -@infoline @mathit{a/(1 + exp(b (x - c)))}. -@item b -Logistic bell curve. -@texline @math{ae^{b(x-c)}/(1+e^{b(x-c)})^2}. -@infoline @mathit{a exp(b (x - c))/(1 + exp(b (x - c)))^2}. -@item o -Hubbert linearization. -@texline @math{{y \over x} = a(1-x/b)}. -@infoline @mathit{(y/x) = a (1 - x/b)}. -@end table - -All of these models are used in the usual way; just press the appropriate -letter at the model prompt, and choose variable names if you wish. The -result will be a formula as shown in the above table, with the best-fit -values of the parameters substituted. (You may find it easier to read -the parameter values from the vector that is placed in the trail.) - -All models except Gaussian, logistics, Hubbert and polynomials can -generalize as shown to any number of independent variables. Also, all -the built-in models except for the logistic and Hubbert curves have an -additive or multiplicative parameter shown as @expr{a} in the above table -which can be replaced by zero or one, as appropriate, by typing @kbd{h} -before the model key. - -Note that many of these models are essentially equivalent, but express -the parameters slightly differently. For example, @expr{a b^x} and -the other two exponential models are all algebraic rearrangements of -each other. Also, the ``quadratic'' model is just a degree-2 polynomial -with the parameters expressed differently. Use whichever form best -matches the problem. - -The HP-28/48 calculators support four different models for curve -fitting, called @code{LIN}, @code{LOG}, @code{EXP}, and @code{PWR}. -These correspond to Calc models @samp{a + b x}, @samp{a + b ln(x)}, -@samp{a exp(b x)}, and @samp{a x^b}, respectively. In each case, -@expr{a} is what the HP-48 identifies as the ``intercept,'' and -@expr{b} is what it calls the ``slope.'' - -@tex -\bigskip -@end tex - -If the model you want doesn't appear on this list, press @kbd{'} -(the apostrophe key) at the model prompt to enter any algebraic -formula, such as @kbd{m x - b}, as the model. (Not all models -will work, though---see the next section for details.) - -The model can also be an equation like @expr{y = m x + b}. -In this case, Calc thinks of all the rows of the data matrix on -equal terms; this model effectively has two parameters -(@expr{m} and @expr{b}) and two independent variables (@expr{x} -and @expr{y}), with no ``dependent'' variables. Model equations -do not need to take this @expr{y =} form. For example, the -implicit line equation @expr{a x + b y = 1} works fine as a -model. - -When you enter a model, Calc makes an alphabetical list of all -the variables that appear in the model. These are used for the -default parameters, independent variables, and dependent variable -(in that order). If you enter a plain formula (not an equation), -Calc assumes the dependent variable does not appear in the formula -and thus does not need a name. - -For example, if the model formula has the variables @expr{a,mu,sigma,t,x}, -and the data matrix has three rows (meaning two independent variables), -Calc will use @expr{a,mu,sigma} as the default parameters, and the -data rows will be named @expr{t} and @expr{x}, respectively. If you -enter an equation instead of a plain formula, Calc will use @expr{a,mu} -as the parameters, and @expr{sigma,t,x} as the three independent -variables. - -You can, of course, override these choices by entering something -different at the prompt. If you leave some variables out of the list, -those variables must have stored values and those stored values will -be used as constants in the model. (Stored values for the parameters -and independent variables are ignored by the @kbd{a F} command.) -If you list only independent variables, all the remaining variables -in the model formula will become parameters. - -If there are @kbd{$} signs in the model you type, they will stand -for parameters and all other variables (in alphabetical order) -will be independent. Use @kbd{$} for one parameter, @kbd{$$} for -another, and so on. Thus @kbd{$ x + $$} is another way to describe -a linear model. - -If you type a @kbd{$} instead of @kbd{'} at the model prompt itself, -Calc will take the model formula from the stack. (The data must then -appear at the second stack level.) The same conventions are used to -choose which variables in the formula are independent by default and -which are parameters. - -Models taken from the stack can also be expressed as vectors of -two or three elements, @expr{[@var{model}, @var{vars}]} or -@expr{[@var{model}, @var{vars}, @var{params}]}. Each of @var{vars} -and @var{params} may be either a variable or a vector of variables. -(If @var{params} is omitted, all variables in @var{model} except -those listed as @var{vars} are parameters.) - -When you enter a model manually with @kbd{'}, Calc puts a 3-vector -describing the model in the trail so you can get it back if you wish. - -@tex -\bigskip -@end tex - -@vindex Model1 -@vindex Model2 -Finally, you can store a model in one of the Calc variables -@code{Model1} or @code{Model2}, then use this model by typing -@kbd{a F u} or @kbd{a F U} (respectively). The value stored in -the variable can be any of the formats that @kbd{a F $} would -accept for a model on the stack. - -@tex -\bigskip -@end tex - -Calc uses the principal values of inverse functions like @code{ln} -and @code{arcsin} when doing fits. For example, when you enter -the model @samp{y = sin(a t + b)} Calc actually uses the easier -form @samp{arcsin(y) = a t + b}. The @code{arcsin} function always -returns results in the range from @mathit{-90} to 90 degrees (or the -equivalent range in radians). Suppose you had data that you -believed to represent roughly three oscillations of a sine wave, -so that the argument of the sine might go from zero to -@texline @math{3\times360} -@infoline @mathit{3*360} -degrees. -The above model would appear to be a good way to determine the -true frequency and phase of the sine wave, but in practice it -would fail utterly. The righthand side of the actual model -@samp{arcsin(y) = a t + b} will grow smoothly with @expr{t}, but -the lefthand side will bounce back and forth between @mathit{-90} and 90. -No values of @expr{a} and @expr{b} can make the two sides match, -even approximately. - -There is no good solution to this problem at present. You could -restrict your data to small enough ranges so that the above problem -doesn't occur (i.e., not straddling any peaks in the sine wave). -Or, in this case, you could use a totally different method such as -Fourier analysis, which is beyond the scope of the @kbd{a F} command. -(Unfortunately, Calc does not currently have any facilities for -taking Fourier and related transforms.) - -@node Curve Fitting Details, Interpolation, Standard Nonlinear Models, Curve Fitting -@subsection Curve Fitting Details - -@noindent -Calc's internal least-squares fitter can only handle multilinear -models. More precisely, it can handle any model of the form -@expr{a f(x,y,z) + b g(x,y,z) + c h(x,y,z)}, where @expr{a,b,c} -are the parameters and @expr{x,y,z} are the independent variables -(of course there can be any number of each, not just three). - -In a simple multilinear or polynomial fit, it is easy to see how -to convert the model into this form. For example, if the model -is @expr{a + b x + c x^2}, then @expr{f(x) = 1}, @expr{g(x) = x}, -and @expr{h(x) = x^2} are suitable functions. - -For most other models, Calc uses a variety of algebraic manipulations -to try to put the problem into the form - -@smallexample -Y(x,y,z) = A(a,b,c) F(x,y,z) + B(a,b,c) G(x,y,z) + C(a,b,c) H(x,y,z) -@end smallexample - -@noindent -where @expr{Y,A,B,C,F,G,H} are arbitrary functions. It computes -@expr{Y}, @expr{F}, @expr{G}, and @expr{H} for all the data points, -does a standard linear fit to find the values of @expr{A}, @expr{B}, -and @expr{C}, then uses the equation solver to solve for @expr{a,b,c} -in terms of @expr{A,B,C}. - -A remarkable number of models can be cast into this general form. -We'll look at two examples here to see how it works. The power-law -model @expr{y = a x^b} with two independent variables and two parameters -can be rewritten as follows: - -@example -y = a x^b -y = a exp(b ln(x)) -y = exp(ln(a) + b ln(x)) -ln(y) = ln(a) + b ln(x) -@end example - -@noindent -which matches the desired form with -@texline @math{Y = \ln(y)}, -@infoline @expr{Y = ln(y)}, -@texline @math{A = \ln(a)}, -@infoline @expr{A = ln(a)}, -@expr{F = 1}, @expr{B = b}, and -@texline @math{G = \ln(x)}. -@infoline @expr{G = ln(x)}. -Calc thus computes the logarithms of your @expr{y} and @expr{x} values, -does a linear fit for @expr{A} and @expr{B}, then solves to get -@texline @math{a = \exp(A)} -@infoline @expr{a = exp(A)} -and @expr{b = B}. - -Another interesting example is the ``quadratic'' model, which can -be handled by expanding according to the distributive law. - -@example -y = a + b*(x - c)^2 -y = a + b c^2 - 2 b c x + b x^2 -@end example - -@noindent -which matches with @expr{Y = y}, @expr{A = a + b c^2}, @expr{F = 1}, -@expr{B = -2 b c}, @expr{G = x} (the @mathit{-2} factor could just as easily -have been put into @expr{G} instead of @expr{B}), @expr{C = b}, and -@expr{H = x^2}. - -The Gaussian model looks quite complicated, but a closer examination -shows that it's actually similar to the quadratic model but with an -exponential that can be brought to the top and moved into @expr{Y}. - -The logistic models cannot be put into general linear form. For these -models, and the Hubbert linearization, Calc computes a rough -approximation for the parameters, then uses the Levenberg-Marquardt -iterative method to refine the approximations. - -Another model that cannot be put into general linear -form is a Gaussian with a constant background added on, i.e., -@expr{d} + the regular Gaussian formula. If you have a model like -this, your best bet is to replace enough of your parameters with -constants to make the model linearizable, then adjust the constants -manually by doing a series of fits. You can compare the fits by -graphing them, by examining the goodness-of-fit measures returned by -@kbd{I a F}, or by some other method suitable to your application. -Note that some models can be linearized in several ways. The -Gaussian-plus-@var{d} model can be linearized by setting @expr{d} -(the background) to a constant, or by setting @expr{b} (the standard -deviation) and @expr{c} (the mean) to constants. - -To fit a model with constants substituted for some parameters, just -store suitable values in those parameter variables, then omit them -from the list of parameters when you answer the variables prompt. - -@tex -\bigskip -@end tex - -A last desperate step would be to use the general-purpose -@code{minimize} function rather than @code{fit}. After all, both -functions solve the problem of minimizing an expression (the -@texline @math{\chi^2} -@infoline @expr{chi^2} -sum) by adjusting certain parameters in the expression. The @kbd{a F} -command is able to use a vastly more efficient algorithm due to its -special knowledge about linear chi-square sums, but the @kbd{a N} -command can do the same thing by brute force. - -A compromise would be to pick out a few parameters without which the -fit is linearizable, and use @code{minimize} on a call to @code{fit} -which efficiently takes care of the rest of the parameters. The thing -to be minimized would be the value of -@texline @math{\chi^2} -@infoline @expr{chi^2} -returned as the fifth result of the @code{xfit} function: - -@smallexample -minimize(xfit(gaus(a,b,c,d,x), x, [a,b,c], data)_5, d, guess) -@end smallexample - -@noindent -where @code{gaus} represents the Gaussian model with background, -@code{data} represents the data matrix, and @code{guess} represents -the initial guess for @expr{d} that @code{minimize} requires. -This operation will only be, shall we say, extraordinarily slow -rather than astronomically slow (as would be the case if @code{minimize} -were used by itself to solve the problem). - -@tex -\bigskip -@end tex - -The @kbd{I a F} [@code{xfit}] command is somewhat trickier when -nonlinear models are used. The second item in the result is the -vector of ``raw'' parameters @expr{A}, @expr{B}, @expr{C}. The -covariance matrix is written in terms of those raw parameters. -The fifth item is a vector of @dfn{filter} expressions. This -is the empty vector @samp{[]} if the raw parameters were the same -as the requested parameters, i.e., if @expr{A = a}, @expr{B = b}, -and so on (which is always true if the model is already linear -in the parameters as written, e.g., for polynomial fits). If the -parameters had to be rearranged, the fifth item is instead a vector -of one formula per parameter in the original model. The raw -parameters are expressed in these ``filter'' formulas as -@samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} for @expr{B}, -and so on. - -When Calc needs to modify the model to return the result, it replaces -@samp{fitdummy(1)} in all the filters with the first item in the raw -parameters list, and so on for the other raw parameters, then -evaluates the resulting filter formulas to get the actual parameter -values to be substituted into the original model. In the case of -@kbd{H a F} and @kbd{I a F} where the parameters must be error forms, -Calc uses the square roots of the diagonal entries of the covariance -matrix as error values for the raw parameters, then lets Calc's -standard error-form arithmetic take it from there. - -If you use @kbd{I a F} with a nonlinear model, be sure to remember -that the covariance matrix is in terms of the raw parameters, -@emph{not} the actual requested parameters. It's up to you to -figure out how to interpret the covariances in the presence of -nontrivial filter functions. - -Things are also complicated when the input contains error forms. -Suppose there are three independent and dependent variables, @expr{x}, -@expr{y}, and @expr{z}, one or more of which are error forms in the -data. Calc combines all the error values by taking the square root -of the sum of the squares of the errors. It then changes @expr{x} -and @expr{y} to be plain numbers, and makes @expr{z} into an error -form with this combined error. The @expr{Y(x,y,z)} part of the -linearized model is evaluated, and the result should be an error -form. The error part of that result is used for -@texline @math{\sigma_i} -@infoline @expr{sigma_i} -for the data point. If for some reason @expr{Y(x,y,z)} does not return -an error form, the combined error from @expr{z} is used directly for -@texline @math{\sigma_i}. -@infoline @expr{sigma_i}. -Finally, @expr{z} is also stripped of its error -for use in computing @expr{F(x,y,z)}, @expr{G(x,y,z)} and so on; -the righthand side of the linearized model is computed in regular -arithmetic with no error forms. - -(While these rules may seem complicated, they are designed to do -the most reasonable thing in the typical case that @expr{Y(x,y,z)} -depends only on the dependent variable @expr{z}, and in fact is -often simply equal to @expr{z}. For common cases like polynomials -and multilinear models, the combined error is simply used as the -@texline @math{\sigma} -@infoline @expr{sigma} -for the data point with no further ado.) - -@tex -\bigskip -@end tex - -@vindex FitRules -It may be the case that the model you wish to use is linearizable, -but Calc's built-in rules are unable to figure it out. Calc uses -its algebraic rewrite mechanism to linearize a model. The rewrite -rules are kept in the variable @code{FitRules}. You can edit this -variable using the @kbd{s e FitRules} command; in fact, there is -a special @kbd{s F} command just for editing @code{FitRules}. -@xref{Operations on Variables}. - -@xref{Rewrite Rules}, for a discussion of rewrite rules. - -@ignore -@starindex -@end ignore -@tindex fitvar -@ignore -@starindex -@end ignore -@ignore -@mindex @idots -@end ignore -@tindex fitparam -@ignore -@starindex -@end ignore -@ignore -@mindex @null -@end ignore -@tindex fitmodel -@ignore -@starindex -@end ignore -@ignore -@mindex @null -@end ignore -@tindex fitsystem -@ignore -@starindex -@end ignore -@ignore -@mindex @null -@end ignore -@tindex fitdummy -Calc uses @code{FitRules} as follows. First, it converts the model -to an equation if necessary and encloses the model equation in a -call to the function @code{fitmodel} (which is not actually a defined -function in Calc; it is only used as a placeholder by the rewrite rules). -Parameter variables are renamed to function calls @samp{fitparam(1)}, -@samp{fitparam(2)}, and so on, and independent variables are renamed -to @samp{fitvar(1)}, @samp{fitvar(2)}, etc. The dependent variable -is the highest-numbered @code{fitvar}. For example, the power law -model @expr{a x^b} is converted to @expr{y = a x^b}, then to - -@smallexample -@group -fitmodel(fitvar(2) = fitparam(1) fitvar(1)^fitparam(2)) -@end group -@end smallexample - -Calc then applies the rewrites as if by @samp{C-u 0 a r FitRules}. -(The zero prefix means that rewriting should continue until no further -changes are possible.) - -When rewriting is complete, the @code{fitmodel} call should have -been replaced by a @code{fitsystem} call that looks like this: - -@example -fitsystem(@var{Y}, @var{FGH}, @var{abc}) -@end example - -@noindent -where @var{Y} is a formula that describes the function @expr{Y(x,y,z)}, -@var{FGH} is the vector of formulas @expr{[F(x,y,z), G(x,y,z), H(x,y,z)]}, -and @var{abc} is the vector of parameter filters which refer to the -raw parameters as @samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} -for @expr{B}, etc. While the number of raw parameters (the length of -the @var{FGH} vector) is usually the same as the number of original -parameters (the length of the @var{abc} vector), this is not required. - -The power law model eventually boils down to - -@smallexample -@group -fitsystem(ln(fitvar(2)), - [1, ln(fitvar(1))], - [exp(fitdummy(1)), fitdummy(2)]) -@end group -@end smallexample - -The actual implementation of @code{FitRules} is complicated; it -proceeds in four phases. First, common rearrangements are done -to try to bring linear terms together and to isolate functions like -@code{exp} and @code{ln} either all the way ``out'' (so that they -can be put into @var{Y}) or all the way ``in'' (so that they can -be put into @var{abc} or @var{FGH}). In particular, all -non-constant powers are converted to logs-and-exponentials form, -and the distributive law is used to expand products of sums. -Quotients are rewritten to use the @samp{fitinv} function, where -@samp{fitinv(x)} represents @expr{1/x} while the @code{FitRules} -are operating. (The use of @code{fitinv} makes recognition of -linear-looking forms easier.) If you modify @code{FitRules}, you -will probably only need to modify the rules for this phase. - -Phase two, whose rules can actually also apply during phases one -and three, first rewrites @code{fitmodel} to a two-argument -form @samp{fitmodel(@var{Y}, @var{model})}, where @var{Y} is -initially zero and @var{model} has been changed from @expr{a=b} -to @expr{a-b} form. It then tries to peel off invertible functions -from the outside of @var{model} and put them into @var{Y} instead, -calling the equation solver to invert the functions. Finally, when -this is no longer possible, the @code{fitmodel} is changed to a -four-argument @code{fitsystem}, where the fourth argument is -@var{model} and the @var{FGH} and @var{abc} vectors are initially -empty. (The last vector is really @var{ABC}, corresponding to -raw parameters, for now.) - -Phase three converts a sum of items in the @var{model} to a sum -of @samp{fitpart(@var{a}, @var{b}, @var{c})} terms which represent -terms @samp{@var{a}*@var{b}*@var{c}} of the sum, where @var{a} -is all factors that do not involve any variables, @var{b} is all -factors that involve only parameters, and @var{c} is the factors -that involve only independent variables. (If this decomposition -is not possible, the rule set will not complete and Calc will -complain that the model is too complex.) Then @code{fitpart}s -with equal @var{b} or @var{c} components are merged back together -using the distributive law in order to minimize the number of -raw parameters needed. - -Phase four moves the @code{fitpart} terms into the @var{FGH} and -@var{ABC} vectors. Also, some of the algebraic expansions that -were done in phase 1 are undone now to make the formulas more -computationally efficient. Finally, it calls the solver one more -time to convert the @var{ABC} vector to an @var{abc} vector, and -removes the fourth @var{model} argument (which by now will be zero) -to obtain the three-argument @code{fitsystem} that the linear -least-squares solver wants to see. - -@ignore -@starindex -@end ignore -@ignore -@mindex hasfit@idots -@end ignore -@tindex hasfitparams -@ignore -@starindex -@end ignore -@ignore -@mindex @null -@end ignore -@tindex hasfitvars -Two functions which are useful in connection with @code{FitRules} -are @samp{hasfitparams(x)} and @samp{hasfitvars(x)}, which check -whether @expr{x} refers to any parameters or independent variables, -respectively. Specifically, these functions return ``true'' if the -argument contains any @code{fitparam} (or @code{fitvar}) function -calls, and ``false'' otherwise. (Recall that ``true'' means a -nonzero number, and ``false'' means zero. The actual nonzero number -returned is the largest @var{n} from all the @samp{fitparam(@var{n})}s -or @samp{fitvar(@var{n})}s, respectively, that appear in the formula.) - -@tex -\bigskip -@end tex - -The @code{fit} function in algebraic notation normally takes four -arguments, @samp{fit(@var{model}, @var{vars}, @var{params}, @var{data})}, -where @var{model} is the model formula as it would be typed after -@kbd{a F '}, @var{vars} is the independent variable or a vector of -independent variables, @var{params} likewise gives the parameter(s), -and @var{data} is the data matrix. Note that the length of @var{vars} -must be equal to the number of rows in @var{data} if @var{model} is -an equation, or one less than the number of rows if @var{model} is -a plain formula. (Actually, a name for the dependent variable is -allowed but will be ignored in the plain-formula case.) - -If @var{params} is omitted, the parameters are all variables in -@var{model} except those that appear in @var{vars}. If @var{vars} -is also omitted, Calc sorts all the variables that appear in -@var{model} alphabetically and uses the higher ones for @var{vars} -and the lower ones for @var{params}. - -Alternatively, @samp{fit(@var{modelvec}, @var{data})} is allowed -where @var{modelvec} is a 2- or 3-vector describing the model -and variables, as discussed previously. - -If Calc is unable to do the fit, the @code{fit} function is left -in symbolic form, ordinarily with an explanatory message. The -message will be ``Model expression is too complex'' if the -linearizer was unable to put the model into the required form. - -The @code{efit} (corresponding to @kbd{H a F}) and @code{xfit} -(for @kbd{I a F}) functions are completely analogous. - -@node Interpolation, , Curve Fitting Details, Curve Fitting -@subsection Polynomial Interpolation - -@kindex a p -@pindex calc-poly-interp -@tindex polint -The @kbd{a p} (@code{calc-poly-interp}) [@code{polint}] command does -a polynomial interpolation at a particular @expr{x} value. It takes -two arguments from the stack: A data matrix of the sort used by -@kbd{a F}, and a single number which represents the desired @expr{x} -value. Calc effectively does an exact polynomial fit as if by @kbd{a F i}, -then substitutes the @expr{x} value into the result in order to get an -approximate @expr{y} value based on the fit. (Calc does not actually -use @kbd{a F i}, however; it uses a direct method which is both more -efficient and more numerically stable.) - -The result of @kbd{a p} is actually a vector of two values: The @expr{y} -value approximation, and an error measure @expr{dy} that reflects Calc's -estimation of the probable error of the approximation at that value of -@expr{x}. If the input @expr{x} is equal to any of the @expr{x} values -in the data matrix, the output @expr{y} will be the corresponding @expr{y} -value from the matrix, and the output @expr{dy} will be exactly zero. - -A prefix argument of 2 causes @kbd{a p} to take separate x- and -y-vectors from the stack instead of one data matrix. - -If @expr{x} is a vector of numbers, @kbd{a p} will return a matrix of -interpolated results for each of those @expr{x} values. (The matrix will -have two columns, the @expr{y} values and the @expr{dy} values.) -If @expr{x} is a formula instead of a number, the @code{polint} function -remains in symbolic form; use the @kbd{a "} command to expand it out to -a formula that describes the fit in symbolic terms. - -In all cases, the @kbd{a p} command leaves the data vectors or matrix -on the stack. Only the @expr{x} value is replaced by the result. - -@kindex H a p -@tindex ratint -The @kbd{H a p} [@code{ratint}] command does a rational function -interpolation. It is used exactly like @kbd{a p}, except that it -uses as its model the quotient of two polynomials. If there are -@expr{N} data points, the numerator and denominator polynomials will -each have degree @expr{N/2} (if @expr{N} is odd, the denominator will -have degree one higher than the numerator). - -Rational approximations have the advantage that they can accurately -describe functions that have poles (points at which the function's value -goes to infinity, so that the denominator polynomial of the approximation -goes to zero). If @expr{x} corresponds to a pole of the fitted rational -function, then the result will be a division by zero. If Infinite mode -is enabled, the result will be @samp{[uinf, uinf]}. - -There is no way to get the actual coefficients of the rational function -used by @kbd{H a p}. (The algorithm never generates these coefficients -explicitly, and quotients of polynomials are beyond @w{@kbd{a F}}'s -capabilities to fit.) - -@node Summations, Logical Operations, Curve Fitting, Algebra -@section Summations - -@noindent -@cindex Summation of a series -@kindex a + -@pindex calc-summation -@tindex sum -The @kbd{a +} (@code{calc-summation}) [@code{sum}] command computes -the sum of a formula over a certain range of index values. The formula -is taken from the top of the stack; the command prompts for the -name of the summation index variable, the lower limit of the -sum (any formula), and the upper limit of the sum. If you -enter a blank line at any of these prompts, that prompt and -any later ones are answered by reading additional elements from -the stack. Thus, @kbd{' k^2 @key{RET} ' k @key{RET} 1 @key{RET} 5 @key{RET} a + @key{RET}} -produces the result 55. -@tex -$$ \sum_{k=1}^5 k^2 = 55 $$ -@end tex - -The choice of index variable is arbitrary, but it's best not to -use a variable with a stored value. In particular, while -@code{i} is often a favorite index variable, it should be avoided -in Calc because @code{i} has the imaginary constant @expr{(0, 1)} -as a value. If you pressed @kbd{=} on a sum over @code{i}, it would -be changed to a nonsensical sum over the ``variable'' @expr{(0, 1)}! -If you really want to use @code{i} as an index variable, use -@w{@kbd{s u i @key{RET}}} first to ``unstore'' this variable. -(@xref{Storing Variables}.) - -A numeric prefix argument steps the index by that amount rather -than by one. Thus @kbd{' a_k @key{RET} C-u -2 a + k @key{RET} 10 @key{RET} 0 @key{RET}} -yields @samp{a_10 + a_8 + a_6 + a_4 + a_2 + a_0}. A prefix -argument of plain @kbd{C-u} causes @kbd{a +} to prompt for the -step value, in which case you can enter any formula or enter -a blank line to take the step value from the stack. With the -@kbd{C-u} prefix, @kbd{a +} can take up to five arguments from -the stack: The formula, the variable, the lower limit, the -upper limit, and (at the top of the stack), the step value. - -Calc knows how to do certain sums in closed form. For example, -@samp{sum(6 k^2, k, 1, n) = @w{2 n^3} + 3 n^2 + n}. In particular, -this is possible if the formula being summed is polynomial or -exponential in the index variable. Sums of logarithms are -transformed into logarithms of products. Sums of trigonometric -and hyperbolic functions are transformed to sums of exponentials -and then done in closed form. Also, of course, sums in which the -lower and upper limits are both numbers can always be evaluated -just by grinding them out, although Calc will use closed forms -whenever it can for the sake of efficiency. - -The notation for sums in algebraic formulas is -@samp{sum(@var{expr}, @var{var}, @var{low}, @var{high}, @var{step})}. -If @var{step} is omitted, it defaults to one. If @var{high} is -omitted, @var{low} is actually the upper limit and the lower limit -is one. If @var{low} is also omitted, the limits are @samp{-inf} -and @samp{inf}, respectively. - -Infinite sums can sometimes be evaluated: @samp{sum(.5^k, k, 1, inf)} -returns @expr{1}. This is done by evaluating the sum in closed -form (to @samp{1. - 0.5^n} in this case), then evaluating this -formula with @code{n} set to @code{inf}. Calc's usual rules -for ``infinite'' arithmetic can find the answer from there. If -infinite arithmetic yields a @samp{nan}, or if the sum cannot be -solved in closed form, Calc leaves the @code{sum} function in -symbolic form. @xref{Infinities}. - -As a special feature, if the limits are infinite (or omitted, as -described above) but the formula includes vectors subscripted by -expressions that involve the iteration variable, Calc narrows -the limits to include only the range of integers which result in -valid subscripts for the vector. For example, the sum -@samp{sum(k [a,b,c,d,e,f,g]_(2k),k)} evaluates to @samp{b + 2 d + 3 f}. - -The limits of a sum do not need to be integers. For example, -@samp{sum(a_k, k, 0, 2 n, n)} produces @samp{a_0 + a_n + a_(2 n)}. -Calc computes the number of iterations using the formula -@samp{1 + (@var{high} - @var{low}) / @var{step}}, which must, -after simplification as if by @kbd{a s}, evaluate to an integer. - -If the number of iterations according to the above formula does -not come out to an integer, the sum is invalid and will be left -in symbolic form. However, closed forms are still supplied, and -you are on your honor not to misuse the resulting formulas by -substituting mismatched bounds into them. For example, -@samp{sum(k, k, 1, 10, 2)} is invalid, but Calc will go ahead and -evaluate the closed form solution for the limits 1 and 10 to get -the rather dubious answer, 29.25. - -If the lower limit is greater than the upper limit (assuming a -positive step size), the result is generally zero. However, -Calc only guarantees a zero result when the upper limit is -exactly one step less than the lower limit, i.e., if the number -of iterations is @mathit{-1}. Thus @samp{sum(f(k), k, n, n-1)} is zero -but the sum from @samp{n} to @samp{n-2} may report a nonzero value -if Calc used a closed form solution. - -Calc's logical predicates like @expr{a < b} return 1 for ``true'' -and 0 for ``false.'' @xref{Logical Operations}. This can be -used to advantage for building conditional sums. For example, -@samp{sum(prime(k)*k^2, k, 1, 20)} is the sum of the squares of all -prime numbers from 1 to 20; the @code{prime} predicate returns 1 if -its argument is prime and 0 otherwise. You can read this expression -as ``the sum of @expr{k^2}, where @expr{k} is prime.'' Indeed, -@samp{sum(prime(k)*k^2, k)} would represent the sum of @emph{all} primes -squared, since the limits default to plus and minus infinity, but -there are no such sums that Calc's built-in rules can do in -closed form. - -As another example, @samp{sum((k != k_0) * f(k), k, 1, n)} is the -sum of @expr{f(k)} for all @expr{k} from 1 to @expr{n}, excluding -one value @expr{k_0}. Slightly more tricky is the summand -@samp{(k != k_0) / (k - k_0)}, which is an attempt to describe -the sum of all @expr{1/(k-k_0)} except at @expr{k = k_0}, where -this would be a division by zero. But at @expr{k = k_0}, this -formula works out to the indeterminate form @expr{0 / 0}, which -Calc will not assume is zero. Better would be to use -@samp{(k != k_0) ? 1/(k-k_0) : 0}; the @samp{? :} operator does -an ``if-then-else'' test: This expression says, ``if -@texline @math{k \ne k_0}, -@infoline @expr{k != k_0}, -then @expr{1/(k-k_0)}, else zero.'' Now the formula @expr{1/(k-k_0)} -will not even be evaluated by Calc when @expr{k = k_0}. - -@cindex Alternating sums -@kindex a - -@pindex calc-alt-summation -@tindex asum -The @kbd{a -} (@code{calc-alt-summation}) [@code{asum}] command -computes an alternating sum. Successive terms of the sequence -are given alternating signs, with the first term (corresponding -to the lower index value) being positive. Alternating sums -are converted to normal sums with an extra term of the form -@samp{(-1)^(k-@var{low})}. This formula is adjusted appropriately -if the step value is other than one. For example, the Taylor -series for the sine function is @samp{asum(x^k / k!, k, 1, inf, 2)}. -(Calc cannot evaluate this infinite series, but it can approximate -it if you replace @code{inf} with any particular odd number.) -Calc converts this series to a regular sum with a step of one, -namely @samp{sum((-1)^k x^(2k+1) / (2k+1)!, k, 0, inf)}. - -@cindex Product of a sequence -@kindex a * -@pindex calc-product -@tindex prod -The @kbd{a *} (@code{calc-product}) [@code{prod}] command is -the analogous way to take a product of many terms. Calc also knows -some closed forms for products, such as @samp{prod(k, k, 1, n) = n!}. -Conditional products can be written @samp{prod(k^prime(k), k, 1, n)} -or @samp{prod(prime(k) ? k : 1, k, 1, n)}. - -@kindex a T -@pindex calc-tabulate -@tindex table -The @kbd{a T} (@code{calc-tabulate}) [@code{table}] command -evaluates a formula at a series of iterated index values, just -like @code{sum} and @code{prod}, but its result is simply a -vector of the results. For example, @samp{table(a_i, i, 1, 7, 2)} -produces @samp{[a_1, a_3, a_5, a_7]}. - -@node Logical Operations, Rewrite Rules, Summations, Algebra -@section Logical Operations - -@noindent -The following commands and algebraic functions return true/false values, -where 1 represents ``true'' and 0 represents ``false.'' In cases where -a truth value is required (such as for the condition part of a rewrite -rule, or as the condition for a @w{@kbd{Z [ Z ]}} control structure), any -nonzero value is accepted to mean ``true.'' (Specifically, anything -for which @code{dnonzero} returns 1 is ``true,'' and anything for -which @code{dnonzero} returns 0 or cannot decide is assumed ``false.'' -Note that this means that @w{@kbd{Z [ Z ]}} will execute the ``then'' -portion if its condition is provably true, but it will execute the -``else'' portion for any condition like @expr{a = b} that is not -provably true, even if it might be true. Algebraic functions that -have conditions as arguments, like @code{? :} and @code{&&}, remain -unevaluated if the condition is neither provably true nor provably -false. @xref{Declarations}.) - -@kindex a = -@pindex calc-equal-to -@tindex eq -@tindex = -@tindex == -The @kbd{a =} (@code{calc-equal-to}) command, or @samp{eq(a,b)} function -(which can also be written @samp{a = b} or @samp{a == b} in an algebraic -formula) is true if @expr{a} and @expr{b} are equal, either because they -are identical expressions, or because they are numbers which are -numerically equal. (Thus the integer 1 is considered equal to the float -1.0.) If the equality of @expr{a} and @expr{b} cannot be determined, -the comparison is left in symbolic form. Note that as a command, this -operation pops two values from the stack and pushes back either a 1 or -a 0, or a formula @samp{a = b} if the values' equality cannot be determined. - -Many Calc commands use @samp{=} formulas to represent @dfn{equations}. -For example, the @kbd{a S} (@code{calc-solve-for}) command rearranges -an equation to solve for a given variable. The @kbd{a M} -(@code{calc-map-equation}) command can be used to apply any -function to both sides of an equation; for example, @kbd{2 a M *} -multiplies both sides of the equation by two. Note that just -@kbd{2 *} would not do the same thing; it would produce the formula -@samp{2 (a = b)} which represents 2 if the equality is true or -zero if not. - -The @code{eq} function with more than two arguments (e.g., @kbd{C-u 3 a =} -or @samp{a = b = c}) tests if all of its arguments are equal. In -algebraic notation, the @samp{=} operator is unusual in that it is -neither left- nor right-associative: @samp{a = b = c} is not the -same as @samp{(a = b) = c} or @samp{a = (b = c)} (which each compare -one variable with the 1 or 0 that results from comparing two other -variables). - -@kindex a # -@pindex calc-not-equal-to -@tindex neq -@tindex != -The @kbd{a #} (@code{calc-not-equal-to}) command, or @samp{neq(a,b)} or -@samp{a != b} function, is true if @expr{a} and @expr{b} are not equal. -This also works with more than two arguments; @samp{a != b != c != d} -tests that all four of @expr{a}, @expr{b}, @expr{c}, and @expr{d} are -distinct numbers. - -@kindex a < -@tindex lt -@ignore -@mindex @idots -@end ignore -@kindex a > -@ignore -@mindex @null -@end ignore -@kindex a [ -@ignore -@mindex @null -@end ignore -@kindex a ] -@pindex calc-less-than -@pindex calc-greater-than -@pindex calc-less-equal -@pindex calc-greater-equal -@ignore -@mindex @null -@end ignore -@tindex gt -@ignore -@mindex @null -@end ignore -@tindex leq -@ignore -@mindex @null -@end ignore -@tindex geq -@ignore -@mindex @null -@end ignore -@tindex < -@ignore -@mindex @null -@end ignore -@tindex > -@ignore -@mindex @null -@end ignore -@tindex <= -@ignore -@mindex @null -@end ignore -@tindex >= -The @kbd{a <} (@code{calc-less-than}) [@samp{lt(a,b)} or @samp{a < b}] -operation is true if @expr{a} is less than @expr{b}. Similar functions -are @kbd{a >} (@code{calc-greater-than}) [@samp{gt(a,b)} or @samp{a > b}], -@kbd{a [} (@code{calc-less-equal}) [@samp{leq(a,b)} or @samp{a <= b}], and -@kbd{a ]} (@code{calc-greater-equal}) [@samp{geq(a,b)} or @samp{a >= b}]. - -While the inequality functions like @code{lt} do not accept more -than two arguments, the syntax @w{@samp{a <= b < c}} is translated to an -equivalent expression involving intervals: @samp{b in [a .. c)}. -(See the description of @code{in} below.) All four combinations -of @samp{<} and @samp{<=} are allowed, or any of the four combinations -of @samp{>} and @samp{>=}. Four-argument constructions like -@samp{a < b < c < d}, and mixtures like @w{@samp{a < b = c}} that -involve both equations and inequalities, are not allowed. - -@kindex a . -@pindex calc-remove-equal -@tindex rmeq -The @kbd{a .} (@code{calc-remove-equal}) [@code{rmeq}] command extracts -the righthand side of the equation or inequality on the top of the -stack. It also works elementwise on vectors. For example, if -@samp{[x = 2.34, y = z / 2]} is on the stack, then @kbd{a .} produces -@samp{[2.34, z / 2]}. As a special case, if the righthand side is a -variable and the lefthand side is a number (as in @samp{2.34 = x}), then -Calc keeps the lefthand side instead. Finally, this command works with -assignments @samp{x := 2.34} as well as equations, always taking the -righthand side, and for @samp{=>} (evaluates-to) operators, always -taking the lefthand side. - -@kindex a & -@pindex calc-logical-and -@tindex land -@tindex && -The @kbd{a &} (@code{calc-logical-and}) [@samp{land(a,b)} or @samp{a && b}] -function is true if both of its arguments are true, i.e., are -non-zero numbers. In this case, the result will be either @expr{a} or -@expr{b}, chosen arbitrarily. If either argument is zero, the result is -zero. Otherwise, the formula is left in symbolic form. - -@kindex a | -@pindex calc-logical-or -@tindex lor -@tindex || -The @kbd{a |} (@code{calc-logical-or}) [@samp{lor(a,b)} or @samp{a || b}] -function is true if either or both of its arguments are true (nonzero). -The result is whichever argument was nonzero, choosing arbitrarily if both -are nonzero. If both @expr{a} and @expr{b} are zero, the result is -zero. - -@kindex a ! -@pindex calc-logical-not -@tindex lnot -@tindex ! -The @kbd{a !} (@code{calc-logical-not}) [@samp{lnot(a)} or @samp{!@: a}] -function is true if @expr{a} is false (zero), or false if @expr{a} is -true (nonzero). It is left in symbolic form if @expr{a} is not a -number. - -@kindex a : -@pindex calc-logical-if -@tindex if -@ignore -@mindex ? : -@end ignore -@tindex ? -@ignore -@mindex @null -@end ignore -@tindex : -@cindex Arguments, not evaluated -The @kbd{a :} (@code{calc-logical-if}) [@samp{if(a,b,c)} or @samp{a ? b :@: c}] -function is equal to either @expr{b} or @expr{c} if @expr{a} is a nonzero -number or zero, respectively. If @expr{a} is not a number, the test is -left in symbolic form and neither @expr{b} nor @expr{c} is evaluated in -any way. In algebraic formulas, this is one of the few Calc functions -whose arguments are not automatically evaluated when the function itself -is evaluated. The others are @code{lambda}, @code{quote}, and -@code{condition}. - -One minor surprise to watch out for is that the formula @samp{a?3:4} -will not work because the @samp{3:4} is parsed as a fraction instead of -as three separate symbols. Type something like @samp{a ? 3 : 4} or -@samp{a?(3):4} instead. - -As a special case, if @expr{a} evaluates to a vector, then both @expr{b} -and @expr{c} are evaluated; the result is a vector of the same length -as @expr{a} whose elements are chosen from corresponding elements of -@expr{b} and @expr{c} according to whether each element of @expr{a} -is zero or nonzero. Each of @expr{b} and @expr{c} must be either a -vector of the same length as @expr{a}, or a non-vector which is matched -with all elements of @expr{a}. - -@kindex a @{ -@pindex calc-in-set -@tindex in -The @kbd{a @{} (@code{calc-in-set}) [@samp{in(a,b)}] function is true if -the number @expr{a} is in the set of numbers represented by @expr{b}. -If @expr{b} is an interval form, @expr{a} must be one of the values -encompassed by the interval. If @expr{b} is a vector, @expr{a} must be -equal to one of the elements of the vector. (If any vector elements are -intervals, @expr{a} must be in any of the intervals.) If @expr{b} is a -plain number, @expr{a} must be numerically equal to @expr{b}. -@xref{Set Operations}, for a group of commands that manipulate sets -of this sort. - -@ignore -@starindex -@end ignore -@tindex typeof -The @samp{typeof(a)} function produces an integer or variable which -characterizes @expr{a}. If @expr{a} is a number, vector, or variable, -the result will be one of the following numbers: - -@example - 1 Integer - 2 Fraction - 3 Floating-point number - 4 HMS form - 5 Rectangular complex number - 6 Polar complex number - 7 Error form - 8 Interval form - 9 Modulo form -10 Date-only form -11 Date/time form -12 Infinity (inf, uinf, or nan) -100 Variable -101 Vector (but not a matrix) -102 Matrix -@end example - -Otherwise, @expr{a} is a formula, and the result is a variable which -represents the name of the top-level function call. - -@ignore -@starindex -@end ignore -@tindex integer -@ignore -@starindex -@end ignore -@tindex real -@ignore -@starindex -@end ignore -@tindex constant -The @samp{integer(a)} function returns true if @expr{a} is an integer. -The @samp{real(a)} function -is true if @expr{a} is a real number, either integer, fraction, or -float. The @samp{constant(a)} function returns true if @expr{a} is -any of the objects for which @code{typeof} would produce an integer -code result except for variables, and provided that the components of -an object like a vector or error form are themselves constant. -Note that infinities do not satisfy any of these tests, nor do -special constants like @code{pi} and @code{e}. - -@xref{Declarations}, for a set of similar functions that recognize -formulas as well as actual numbers. For example, @samp{dint(floor(x))} -is true because @samp{floor(x)} is provably integer-valued, but -@samp{integer(floor(x))} does not because @samp{floor(x)} is not -literally an integer constant. - -@ignore -@starindex -@end ignore -@tindex refers -The @samp{refers(a,b)} function is true if the variable (or sub-expression) -@expr{b} appears in @expr{a}, or false otherwise. Unlike the other -tests described here, this function returns a definite ``no'' answer -even if its arguments are still in symbolic form. The only case where -@code{refers} will be left unevaluated is if @expr{a} is a plain -variable (different from @expr{b}). - -@ignore -@starindex -@end ignore -@tindex negative -The @samp{negative(a)} function returns true if @expr{a} ``looks'' negative, -because it is a negative number, because it is of the form @expr{-x}, -or because it is a product or quotient with a term that looks negative. -This is most useful in rewrite rules. Beware that @samp{negative(a)} -evaluates to 1 or 0 for @emph{any} argument @expr{a}, so it can only -be stored in a formula if the default simplifications are turned off -first with @kbd{m O} (or if it appears in an unevaluated context such -as a rewrite rule condition). - -@ignore -@starindex -@end ignore -@tindex variable -The @samp{variable(a)} function is true if @expr{a} is a variable, -or false if not. If @expr{a} is a function call, this test is left -in symbolic form. Built-in variables like @code{pi} and @code{inf} -are considered variables like any others by this test. - -@ignore -@starindex -@end ignore -@tindex nonvar -The @samp{nonvar(a)} function is true if @expr{a} is a non-variable. -If its argument is a variable it is left unsimplified; it never -actually returns zero. However, since Calc's condition-testing -commands consider ``false'' anything not provably true, this is -often good enough. - -@ignore -@starindex -@end ignore -@tindex lin -@ignore -@starindex -@end ignore -@tindex linnt -@ignore -@starindex -@end ignore -@tindex islin -@ignore -@starindex -@end ignore -@tindex islinnt -@cindex Linearity testing -The functions @code{lin}, @code{linnt}, @code{islin}, and @code{islinnt} -check if an expression is ``linear,'' i.e., can be written in the form -@expr{a + b x} for some constants @expr{a} and @expr{b}, and some -variable or subformula @expr{x}. The function @samp{islin(f,x)} checks -if formula @expr{f} is linear in @expr{x}, returning 1 if so. For -example, @samp{islin(x,x)}, @samp{islin(-x,x)}, @samp{islin(3,x)}, and -@samp{islin(x y / 3 - 2, x)} all return 1. The @samp{lin(f,x)} function -is similar, except that instead of returning 1 it returns the vector -@expr{[a, b, x]}. For the above examples, this vector would be -@expr{[0, 1, x]}, @expr{[0, -1, x]}, @expr{[3, 0, x]}, and -@expr{[-2, y/3, x]}, respectively. Both @code{lin} and @code{islin} -generally remain unevaluated for expressions which are not linear, -e.g., @samp{lin(2 x^2, x)} and @samp{lin(sin(x), x)}. The second -argument can also be a formula; @samp{islin(2 + 3 sin(x), sin(x))} -returns true. - -The @code{linnt} and @code{islinnt} functions perform a similar check, -but require a ``non-trivial'' linear form, which means that the -@expr{b} coefficient must be non-zero. For example, @samp{lin(2,x)} -returns @expr{[2, 0, x]} and @samp{lin(y,x)} returns @expr{[y, 0, x]}, -but @samp{linnt(2,x)} and @samp{linnt(y,x)} are left unevaluated -(in other words, these formulas are considered to be only ``trivially'' -linear in @expr{x}). - -All four linearity-testing functions allow you to omit the second -argument, in which case the input may be linear in any non-constant -formula. Here, the @expr{a=0}, @expr{b=1} case is also considered -trivial, and only constant values for @expr{a} and @expr{b} are -recognized. Thus, @samp{lin(2 x y)} returns @expr{[0, 2, x y]}, -@samp{lin(2 - x y)} returns @expr{[2, -1, x y]}, and @samp{lin(x y)} -returns @expr{[0, 1, x y]}. The @code{linnt} function would allow the -first two cases but not the third. Also, neither @code{lin} nor -@code{linnt} accept plain constants as linear in the one-argument -case: @samp{islin(2,x)} is true, but @samp{islin(2)} is false. - -@ignore -@starindex -@end ignore -@tindex istrue -The @samp{istrue(a)} function returns 1 if @expr{a} is a nonzero -number or provably nonzero formula, or 0 if @expr{a} is anything else. -Calls to @code{istrue} can only be manipulated if @kbd{m O} mode is -used to make sure they are not evaluated prematurely. (Note that -declarations are used when deciding whether a formula is true; -@code{istrue} returns 1 when @code{dnonzero} would return 1, and -it returns 0 when @code{dnonzero} would return 0 or leave itself -in symbolic form.) - -@node Rewrite Rules, , Logical Operations, Algebra -@section Rewrite Rules - -@noindent -@cindex Rewrite rules -@cindex Transformations -@cindex Pattern matching -@kindex a r -@pindex calc-rewrite -@tindex rewrite -The @kbd{a r} (@code{calc-rewrite}) [@code{rewrite}] command makes -substitutions in a formula according to a specified pattern or patterns -known as @dfn{rewrite rules}. Whereas @kbd{a b} (@code{calc-substitute}) -matches literally, so that substituting @samp{sin(x)} with @samp{cos(x)} -matches only the @code{sin} function applied to the variable @code{x}, -rewrite rules match general kinds of formulas; rewriting using the rule -@samp{sin(x) := cos(x)} matches @code{sin} of any argument and replaces -it with @code{cos} of that same argument. The only significance of the -name @code{x} is that the same name is used on both sides of the rule. - -Rewrite rules rearrange formulas already in Calc's memory. -@xref{Syntax Tables}, to read about @dfn{syntax rules}, which are -similar to algebraic rewrite rules but operate when new algebraic -entries are being parsed, converting strings of characters into -Calc formulas. - -@menu -* Entering Rewrite Rules:: -* Basic Rewrite Rules:: -* Conditional Rewrite Rules:: -* Algebraic Properties of Rewrite Rules:: -* Other Features of Rewrite Rules:: -* Composing Patterns in Rewrite Rules:: -* Nested Formulas with Rewrite Rules:: -* Multi-Phase Rewrite Rules:: -* Selections with Rewrite Rules:: -* Matching Commands:: -* Automatic Rewrites:: -* Debugging Rewrites:: -* Examples of Rewrite Rules:: -@end menu - -@node Entering Rewrite Rules, Basic Rewrite Rules, Rewrite Rules, Rewrite Rules -@subsection Entering Rewrite Rules - -@noindent -Rewrite rules normally use the ``assignment'' operator -@samp{@var{old} := @var{new}}. -This operator is equivalent to the function call @samp{assign(old, new)}. -The @code{assign} function is undefined by itself in Calc, so an -assignment formula such as a rewrite rule will be left alone by ordinary -Calc commands. But certain commands, like the rewrite system, interpret -assignments in special ways. - -For example, the rule @samp{sin(x)^2 := 1-cos(x)^2} says to replace -every occurrence of the sine of something, squared, with one minus the -square of the cosine of that same thing. All by itself as a formula -on the stack it does nothing, but when given to the @kbd{a r} command -it turns that command into a sine-squared-to-cosine-squared converter. - -To specify a set of rules to be applied all at once, make a vector of -rules. - -When @kbd{a r} prompts you to enter the rewrite rules, you can answer -in several ways: - -@enumerate -@item -With a rule: @kbd{f(x) := g(x) @key{RET}}. -@item -With a vector of rules: @kbd{[f1(x) := g1(x), f2(x) := g2(x)] @key{RET}}. -(You can omit the enclosing square brackets if you wish.) -@item -With the name of a variable that contains the rule or rules vector: -@kbd{myrules @key{RET}}. -@item -With any formula except a rule, a vector, or a variable name; this -will be interpreted as the @var{old} half of a rewrite rule, -and you will be prompted a second time for the @var{new} half: -@kbd{f(x) @key{RET} g(x) @key{RET}}. -@item -With a blank line, in which case the rule, rules vector, or variable -will be taken from the top of the stack (and the formula to be -rewritten will come from the second-to-top position). -@end enumerate - -If you enter the rules directly (as opposed to using rules stored -in a variable), those rules will be put into the Trail so that you -can retrieve them later. @xref{Trail Commands}. - -It is most convenient to store rules you use often in a variable and -invoke them by giving the variable name. The @kbd{s e} -(@code{calc-edit-variable}) command is an easy way to create or edit a -rule set stored in a variable. You may also wish to use @kbd{s p} -(@code{calc-permanent-variable}) to save your rules permanently; -@pxref{Operations on Variables}. - -Rewrite rules are compiled into a special internal form for faster -matching. If you enter a rule set directly it must be recompiled -every time. If you store the rules in a variable and refer to them -through that variable, they will be compiled once and saved away -along with the variable for later reference. This is another good -reason to store your rules in a variable. - -Calc also accepts an obsolete notation for rules, as vectors -@samp{[@var{old}, @var{new}]}. But because it is easily confused with a -vector of two rules, the use of this notation is no longer recommended. - -@node Basic Rewrite Rules, Conditional Rewrite Rules, Entering Rewrite Rules, Rewrite Rules -@subsection Basic Rewrite Rules - -@noindent -To match a particular formula @expr{x} with a particular rewrite rule -@samp{@var{old} := @var{new}}, Calc compares the structure of @expr{x} with -the structure of @var{old}. Variables that appear in @var{old} are -treated as @dfn{meta-variables}; the corresponding positions in @expr{x} -may contain any sub-formulas. For example, the pattern @samp{f(x,y)} -would match the expression @samp{f(12, a+1)} with the meta-variable -@samp{x} corresponding to 12 and with @samp{y} corresponding to -@samp{a+1}. However, this pattern would not match @samp{f(12)} or -@samp{g(12, a+1)}, since there is no assignment of the meta-variables -that will make the pattern match these expressions. Notice that if -the pattern is a single meta-variable, it will match any expression. - -If a given meta-variable appears more than once in @var{old}, the -corresponding sub-formulas of @expr{x} must be identical. Thus -the pattern @samp{f(x,x)} would match @samp{f(12, 12)} and -@samp{f(a+1, a+1)} but not @samp{f(12, a+1)} or @samp{f(a+b, b+a)}. -(@xref{Conditional Rewrite Rules}, for a way to match the latter.) - -Things other than variables must match exactly between the pattern -and the target formula. To match a particular variable exactly, use -the pseudo-function @samp{quote(v)} in the pattern. For example, the -pattern @samp{x+quote(y)} matches @samp{x+y}, @samp{2+y}, or -@samp{sin(a)+y}. - -The special variable names @samp{e}, @samp{pi}, @samp{i}, @samp{phi}, -@samp{gamma}, @samp{inf}, @samp{uinf}, and @samp{nan} always match -literally. Thus the pattern @samp{sin(d + e + f)} acts exactly like -@samp{sin(d + quote(e) + f)}. - -If the @var{old} pattern is found to match a given formula, that -formula is replaced by @var{new}, where any occurrences in @var{new} -of meta-variables from the pattern are replaced with the sub-formulas -that they matched. Thus, applying the rule @samp{f(x,y) := g(y+x,x)} -to @samp{f(12, a+1)} would produce @samp{g(a+13, 12)}. - -The normal @kbd{a r} command applies rewrite rules over and over -throughout the target formula until no further changes are possible -(up to a limit of 100 times). Use @kbd{C-u 1 a r} to make only one -change at a time. - -@node Conditional Rewrite Rules, Algebraic Properties of Rewrite Rules, Basic Rewrite Rules, Rewrite Rules -@subsection Conditional Rewrite Rules - -@noindent -A rewrite rule can also be @dfn{conditional}, written in the form -@samp{@var{old} := @var{new} :: @var{cond}}. (There is also the obsolete -form @samp{[@var{old}, @var{new}, @var{cond}]}.) If a @var{cond} part -is present in the -rule, this is an additional condition that must be satisfied before -the rule is accepted. Once @var{old} has been successfully matched -to the target expression, @var{cond} is evaluated (with all the -meta-variables substituted for the values they matched) and simplified -with @kbd{a s} (@code{calc-simplify}). If the result is a nonzero -number or any other object known to be nonzero (@pxref{Declarations}), -the rule is accepted. If the result is zero or if it is a symbolic -formula that is not known to be nonzero, the rule is rejected. -@xref{Logical Operations}, for a number of functions that return -1 or 0 according to the results of various tests. - -For example, the formula @samp{n > 0} simplifies to 1 or 0 if @expr{n} -is replaced by a positive or nonpositive number, respectively (or if -@expr{n} has been declared to be positive or nonpositive). Thus, -the rule @samp{f(x,y) := g(y+x,x) :: x+y > 0} would apply to -@samp{f(0, 4)} but not to @samp{f(-3, 2)} or @samp{f(12, a+1)} -(assuming no outstanding declarations for @expr{a}). In the case of -@samp{f(-3, 2)}, the condition can be shown not to be satisfied; in -the case of @samp{f(12, a+1)}, the condition merely cannot be shown -to be satisfied, but that is enough to reject the rule. - -While Calc will use declarations to reason about variables in the -formula being rewritten, declarations do not apply to meta-variables. -For example, the rule @samp{f(a) := g(a+1)} will match for any values -of @samp{a}, such as complex numbers, vectors, or formulas, even if -@samp{a} has been declared to be real or scalar. If you want the -meta-variable @samp{a} to match only literal real numbers, use -@samp{f(a) := g(a+1) :: real(a)}. If you want @samp{a} to match only -reals and formulas which are provably real, use @samp{dreal(a)} as -the condition. - -The @samp{::} operator is a shorthand for the @code{condition} -function; @samp{@var{old} := @var{new} :: @var{cond}} is equivalent to -the formula @samp{condition(assign(@var{old}, @var{new}), @var{cond})}. - -If you have several conditions, you can use @samp{... :: c1 :: c2 :: c3} -or @samp{... :: c1 && c2 && c3}. The two are entirely equivalent. - -It is also possible to embed conditions inside the pattern: -@samp{f(x :: x>0, y) := g(y+x, x)}. This is purely a notational -convenience, though; where a condition appears in a rule has no -effect on when it is tested. The rewrite-rule compiler automatically -decides when it is best to test each condition while a rule is being -matched. - -Certain conditions are handled as special cases by the rewrite rule -system and are tested very efficiently: Where @expr{x} is any -meta-variable, these conditions are @samp{integer(x)}, @samp{real(x)}, -@samp{constant(x)}, @samp{negative(x)}, @samp{x >= y} where @expr{y} -is either a constant or another meta-variable and @samp{>=} may be -replaced by any of the six relational operators, and @samp{x % a = b} -where @expr{a} and @expr{b} are constants. Other conditions, like -@samp{x >= y+1} or @samp{dreal(x)}, will be less efficient to check -since Calc must bring the whole evaluator and simplifier into play. - -An interesting property of @samp{::} is that neither of its arguments -will be touched by Calc's default simplifications. This is important -because conditions often are expressions that cannot safely be -evaluated early. For example, the @code{typeof} function never -remains in symbolic form; entering @samp{typeof(a)} will put the -number 100 (the type code for variables like @samp{a}) on the stack. -But putting the condition @samp{... :: typeof(a) = 6} on the stack -is safe since @samp{::} prevents the @code{typeof} from being -evaluated until the condition is actually used by the rewrite system. - -Since @samp{::} protects its lefthand side, too, you can use a dummy -condition to protect a rule that must itself not evaluate early. -For example, it's not safe to put @samp{a(f,x) := apply(f, [x])} on -the stack because it will immediately evaluate to @samp{a(f,x) := f(x)}, -where the meta-variable-ness of @code{f} on the righthand side has been -lost. But @samp{a(f,x) := apply(f, [x]) :: 1} is safe, and of course -the condition @samp{1} is always true (nonzero) so it has no effect on -the functioning of the rule. (The rewrite compiler will ensure that -it doesn't even impact the speed of matching the rule.) - -@node Algebraic Properties of Rewrite Rules, Other Features of Rewrite Rules, Conditional Rewrite Rules, Rewrite Rules -@subsection Algebraic Properties of Rewrite Rules - -@noindent -The rewrite mechanism understands the algebraic properties of functions -like @samp{+} and @samp{*}. In particular, pattern matching takes -the associativity and commutativity of the following functions into -account: - -@smallexample -+ - * = != && || and or xor vint vunion vxor gcd lcm max min beta -@end smallexample - -For example, the rewrite rule: - -@example -a x + b x := (a + b) x -@end example - -@noindent -will match formulas of the form, - -@example -a x + b x, x a + x b, a x + x b, x a + b x -@end example - -Rewrites also understand the relationship between the @samp{+} and @samp{-} -operators. The above rewrite rule will also match the formulas, - -@example -a x - b x, x a - x b, a x - x b, x a - b x -@end example - -@noindent -by matching @samp{b} in the pattern to @samp{-b} from the formula. - -Applied to a sum of many terms like @samp{r + a x + s + b x + t}, this -pattern will check all pairs of terms for possible matches. The rewrite -will take whichever suitable pair it discovers first. - -In general, a pattern using an associative operator like @samp{a + b} -will try @var{2 n} different ways to match a sum of @var{n} terms -like @samp{x + y + z - w}. First, @samp{a} is matched against each -of @samp{x}, @samp{y}, @samp{z}, and @samp{-w} in turn, with @samp{b} -being matched to the remainders @samp{y + z - w}, @samp{x + z - w}, etc. -If none of these succeed, then @samp{b} is matched against each of the -four terms with @samp{a} matching the remainder. Half-and-half matches, -like @samp{(x + y) + (z - w)}, are not tried. - -Note that @samp{*} is not commutative when applied to matrices, but -rewrite rules pretend that it is. If you type @kbd{m v} to enable -Matrix mode (@pxref{Matrix Mode}), rewrite rules will match @samp{*} -literally, ignoring its usual commutativity property. (In the -current implementation, the associativity also vanishes---it is as -if the pattern had been enclosed in a @code{plain} marker; see below.) -If you are applying rewrites to formulas with matrices, it's best to -enable Matrix mode first to prevent algebraically incorrect rewrites -from occurring. - -The pattern @samp{-x} will actually match any expression. For example, -the rule - -@example -f(-x) := -f(x) -@end example - -@noindent -will rewrite @samp{f(a)} to @samp{-f(-a)}. To avoid this, either use -a @code{plain} marker as described below, or add a @samp{negative(x)} -condition. The @code{negative} function is true if its argument -``looks'' negative, for example, because it is a negative number or -because it is a formula like @samp{-x}. The new rule using this -condition is: - -@example -f(x) := -f(-x) :: negative(x) @r{or, equivalently,} -f(-x) := -f(x) :: negative(-x) -@end example - -In the same way, the pattern @samp{x - y} will match the sum @samp{a + b} -by matching @samp{y} to @samp{-b}. - -The pattern @samp{a b} will also match the formula @samp{x/y} if -@samp{y} is a number. Thus the rule @samp{a x + @w{b x} := (a+b) x} -will also convert @samp{a x + x / 2} to @samp{(a + 0.5) x} (or -@samp{(a + 1:2) x}, depending on the current fraction mode). - -Calc will @emph{not} take other liberties with @samp{*}, @samp{/}, and -@samp{^}. For example, the pattern @samp{f(a b)} will not match -@samp{f(x^2)}, and @samp{f(a + b)} will not match @samp{f(2 x)}, even -though conceivably these patterns could match with @samp{a = b = x}. -Nor will @samp{f(a b)} match @samp{f(x / y)} if @samp{y} is not a -constant, even though it could be considered to match with @samp{a = x} -and @samp{b = 1/y}. The reasons are partly for efficiency, and partly -because while few mathematical operations are substantively different -for addition and subtraction, often it is preferable to treat the cases -of multiplication, division, and integer powers separately. - -Even more subtle is the rule set - -@example -[ f(a) + f(b) := f(a + b), -f(a) := f(-a) ] -@end example - -@noindent -attempting to match @samp{f(x) - f(y)}. You might think that Calc -will view this subtraction as @samp{f(x) + (-f(y))} and then apply -the above two rules in turn, but actually this will not work because -Calc only does this when considering rules for @samp{+} (like the -first rule in this set). So it will see first that @samp{f(x) + (-f(y))} -does not match @samp{f(a) + f(b)} for any assignments of the -meta-variables, and then it will see that @samp{f(x) - f(y)} does -not match @samp{-f(a)} for any assignment of @samp{a}. Because Calc -tries only one rule at a time, it will not be able to rewrite -@samp{f(x) - f(y)} with this rule set. An explicit @samp{f(a) - f(b)} -rule will have to be added. - -Another thing patterns will @emph{not} do is break up complex numbers. -The pattern @samp{myconj(a + @w{b i)} := a - b i} will work for formulas -involving the special constant @samp{i} (such as @samp{3 - 4 i}), but -it will not match actual complex numbers like @samp{(3, -4)}. A version -of the above rule for complex numbers would be - -@example -myconj(a) := re(a) - im(a) (0,1) :: im(a) != 0 -@end example - -@noindent -(Because the @code{re} and @code{im} functions understand the properties -of the special constant @samp{i}, this rule will also work for -@samp{3 - 4 i}. In fact, this particular rule would probably be better -without the @samp{im(a) != 0} condition, since if @samp{im(a) = 0} the -righthand side of the rule will still give the correct answer for the -conjugate of a real number.) - -It is also possible to specify optional arguments in patterns. The rule - -@example -opt(a) x + opt(b) (x^opt(c) + opt(d)) := f(a, b, c, d) -@end example - -@noindent -will match the formula - -@example -5 (x^2 - 4) + 3 x -@end example - -@noindent -in a fairly straightforward manner, but it will also match reduced -formulas like - -@example -x + x^2, 2(x + 1) - x, x + x -@end example - -@noindent -producing, respectively, - -@example -f(1, 1, 2, 0), f(-1, 2, 1, 1), f(1, 1, 1, 0) -@end example - -(The latter two formulas can be entered only if default simplifications -have been turned off with @kbd{m O}.) - -The default value for a term of a sum is zero. The default value -for a part of a product, for a power, or for the denominator of a -quotient, is one. Also, @samp{-x} matches the pattern @samp{opt(a) b} -with @samp{a = -1}. - -In particular, the distributive-law rule can be refined to - -@example -opt(a) x + opt(b) x := (a + b) x -@end example - -@noindent -so that it will convert, e.g., @samp{a x - x}, to @samp{(a - 1) x}. - -The pattern @samp{opt(a) + opt(b) x} matches almost any formulas which -are linear in @samp{x}. You can also use the @code{lin} and @code{islin} -functions with rewrite conditions to test for this; @pxref{Logical -Operations}. These functions are not as convenient to use in rewrite -rules, but they recognize more kinds of formulas as linear: -@samp{x/z} is considered linear with @expr{b = 1/z} by @code{lin}, -but it will not match the above pattern because that pattern calls -for a multiplication, not a division. - -As another example, the obvious rule to replace @samp{sin(x)^2 + cos(x)^2} -by 1, - -@example -sin(x)^2 + cos(x)^2 := 1 -@end example - -@noindent -misses many cases because the sine and cosine may both be multiplied by -an equal factor. Here's a more successful rule: - -@example -opt(a) sin(x)^2 + opt(a) cos(x)^2 := a -@end example - -Note that this rule will @emph{not} match @samp{sin(x)^2 + 6 cos(x)^2} -because one @expr{a} would have ``matched'' 1 while the other matched 6. - -Calc automatically converts a rule like - -@example -f(x-1, x) := g(x) -@end example - -@noindent -into the form - -@example -f(temp, x) := g(x) :: temp = x-1 -@end example - -@noindent -(where @code{temp} stands for a new, invented meta-variable that -doesn't actually have a name). This modified rule will successfully -match @samp{f(6, 7)}, binding @samp{temp} and @samp{x} to 6 and 7, -respectively, then verifying that they differ by one even though -@samp{6} does not superficially look like @samp{x-1}. - -However, Calc does not solve equations to interpret a rule. The -following rule, - -@example -f(x-1, x+1) := g(x) -@end example - -@noindent -will not work. That is, it will match @samp{f(a - 1 + b, a + 1 + b)} -but not @samp{f(6, 8)}. Calc always interprets at least one occurrence -of a variable by literal matching. If the variable appears ``isolated'' -then Calc is smart enough to use it for literal matching. But in this -last example, Calc is forced to rewrite the rule to @samp{f(x-1, temp) -:= g(x) :: temp = x+1} where the @samp{x-1} term must correspond to an -actual ``something-minus-one'' in the target formula. - -A successful way to write this would be @samp{f(x, x+2) := g(x+1)}. -You could make this resemble the original form more closely by using -@code{let} notation, which is described in the next section: - -@example -f(xm1, x+1) := g(x) :: let(x := xm1+1) -@end example - -Calc does this rewriting or ``conditionalizing'' for any sub-pattern -which involves only the functions in the following list, operating -only on constants and meta-variables which have already been matched -elsewhere in the pattern. When matching a function call, Calc is -careful to match arguments which are plain variables before arguments -which are calls to any of the functions below, so that a pattern like -@samp{f(x-1, x)} can be conditionalized even though the isolated -@samp{x} comes after the @samp{x-1}. - -@smallexample -+ - * / \ % ^ abs sign round rounde roundu trunc floor ceil -max min re im conj arg -@end smallexample - -You can suppress all of the special treatments described in this -section by surrounding a function call with a @code{plain} marker. -This marker causes the function call which is its argument to be -matched literally, without regard to commutativity, associativity, -negation, or conditionalization. When you use @code{plain}, the -``deep structure'' of the formula being matched can show through. -For example, - -@example -plain(a - a b) := f(a, b) -@end example - -@noindent -will match only literal subtractions. However, the @code{plain} -marker does not affect its arguments' arguments. In this case, -commutativity and associativity is still considered while matching -the @w{@samp{a b}} sub-pattern, so the whole pattern will match -@samp{x - y x} as well as @samp{x - x y}. We could go still -further and use - -@example -plain(a - plain(a b)) := f(a, b) -@end example - -@noindent -which would do a completely strict match for the pattern. - -By contrast, the @code{quote} marker means that not only the -function name but also the arguments must be literally the same. -The above pattern will match @samp{x - x y} but - -@example -quote(a - a b) := f(a, b) -@end example - -@noindent -will match only the single formula @samp{a - a b}. Also, - -@example -quote(a - quote(a b)) := f(a, b) -@end example - -@noindent -will match only @samp{a - quote(a b)}---probably not the desired -effect! - -A certain amount of algebra is also done when substituting the -meta-variables on the righthand side of a rule. For example, -in the rule - -@example -a + f(b) := f(a + b) -@end example - -@noindent -matching @samp{f(x) - y} would produce @samp{f((-y) + x)} if -taken literally, but the rewrite mechanism will simplify the -righthand side to @samp{f(x - y)} automatically. (Of course, -the default simplifications would do this anyway, so this -special simplification is only noticeable if you have turned the -default simplifications off.) This rewriting is done only when -a meta-variable expands to a ``negative-looking'' expression. -If this simplification is not desirable, you can use a @code{plain} -marker on the righthand side: - -@example -a + f(b) := f(plain(a + b)) -@end example - -@noindent -In this example, we are still allowing the pattern-matcher to -use all the algebra it can muster, but the righthand side will -always simplify to a literal addition like @samp{f((-y) + x)}. - -@node Other Features of Rewrite Rules, Composing Patterns in Rewrite Rules, Algebraic Properties of Rewrite Rules, Rewrite Rules -@subsection Other Features of Rewrite Rules - -@noindent -Certain ``function names'' serve as markers in rewrite rules. -Here is a complete list of these markers. First are listed the -markers that work inside a pattern; then come the markers that -work in the righthand side of a rule. - -@ignore -@starindex -@end ignore -@tindex import -One kind of marker, @samp{import(x)}, takes the place of a whole -rule. Here @expr{x} is the name of a variable containing another -rule set; those rules are ``spliced into'' the rule set that -imports them. For example, if @samp{[f(a+b) := f(a) + f(b), -f(a b) := a f(b) :: real(a)]} is stored in variable @samp{linearF}, -then the rule set @samp{[f(0) := 0, import(linearF)]} will apply -all three rules. It is possible to modify the imported rules -slightly: @samp{import(x, v1, x1, v2, x2, @dots{})} imports -the rule set @expr{x} with all occurrences of -@texline @math{v_1}, -@infoline @expr{v1}, -as either a variable name or a function name, replaced with -@texline @math{x_1} -@infoline @expr{x1} -and so on. (If -@texline @math{v_1} -@infoline @expr{v1} -is used as a function name, then -@texline @math{x_1} -@infoline @expr{x1} -must be either a function name itself or a @w{@samp{< >}} nameless -function; @pxref{Specifying Operators}.) For example, @samp{[g(0) := 0, -import(linearF, f, g)]} applies the linearity rules to the function -@samp{g} instead of @samp{f}. Imports can be nested, but the -import-with-renaming feature may fail to rename sub-imports properly. - -The special functions allowed in patterns are: - -@table @samp -@item quote(x) -@ignore -@starindex -@end ignore -@tindex quote -This pattern matches exactly @expr{x}; variable names in @expr{x} are -not interpreted as meta-variables. The only flexibility is that -numbers are compared for numeric equality, so that the pattern -@samp{f(quote(12))} will match both @samp{f(12)} and @samp{f(12.0)}. -(Numbers are always treated this way by the rewrite mechanism: -The rule @samp{f(x,x) := g(x)} will match @samp{f(12, 12.0)}. -The rewrite may produce either @samp{g(12)} or @samp{g(12.0)} -as a result in this case.) - -@item plain(x) -@ignore -@starindex -@end ignore -@tindex plain -Here @expr{x} must be a function call @samp{f(x1,x2,@dots{})}. This -pattern matches a call to function @expr{f} with the specified -argument patterns. No special knowledge of the properties of the -function @expr{f} is used in this case; @samp{+} is not commutative or -associative. Unlike @code{quote}, the arguments @samp{x1,x2,@dots{}} -are treated as patterns. If you wish them to be treated ``plainly'' -as well, you must enclose them with more @code{plain} markers: -@samp{plain(plain(@w{-a}) + plain(b c))}. - -@item opt(x,def) -@ignore -@starindex -@end ignore -@tindex opt -Here @expr{x} must be a variable name. This must appear as an -argument to a function or an element of a vector; it specifies that -the argument or element is optional. -As an argument to @samp{+}, @samp{-}, @samp{*}, @samp{&&}, or @samp{||}, -or as the second argument to @samp{/} or @samp{^}, the value @var{def} -may be omitted. The pattern @samp{x + opt(y)} matches a sum by -binding one summand to @expr{x} and the other to @expr{y}, and it -matches anything else by binding the whole expression to @expr{x} and -zero to @expr{y}. The other operators above work similarly. - -For general miscellaneous functions, the default value @code{def} -must be specified. Optional arguments are dropped starting with -the rightmost one during matching. For example, the pattern -@samp{f(opt(a,0), b, opt(c,b))} will match @samp{f(b)}, @samp{f(a,b)}, -or @samp{f(a,b,c)}. Default values of zero and @expr{b} are -supplied in this example for the omitted arguments. Note that -the literal variable @expr{b} will be the default in the latter -case, @emph{not} the value that matched the meta-variable @expr{b}. -In other words, the default @var{def} is effectively quoted. - -@item condition(x,c) -@ignore -@starindex -@end ignore -@tindex condition -@tindex :: -This matches the pattern @expr{x}, with the attached condition -@expr{c}. It is the same as @samp{x :: c}. - -@item pand(x,y) -@ignore -@starindex -@end ignore -@tindex pand -@tindex &&& -This matches anything that matches both pattern @expr{x} and -pattern @expr{y}. It is the same as @samp{x &&& y}. -@pxref{Composing Patterns in Rewrite Rules}. - -@item por(x,y) -@ignore -@starindex -@end ignore -@tindex por -@tindex ||| -This matches anything that matches either pattern @expr{x} or -pattern @expr{y}. It is the same as @w{@samp{x ||| y}}. - -@item pnot(x) -@ignore -@starindex -@end ignore -@tindex pnot -@tindex !!! -This matches anything that does not match pattern @expr{x}. -It is the same as @samp{!!! x}. - -@item cons(h,t) -@ignore -@mindex cons -@end ignore -@tindex cons (rewrites) -This matches any vector of one or more elements. The first -element is matched to @expr{h}; a vector of the remaining -elements is matched to @expr{t}. Note that vectors of fixed -length can also be matched as actual vectors: The rule -@samp{cons(a,cons(b,[])) := cons(a+b,[])} is equivalent -to the rule @samp{[a,b] := [a+b]}. - -@item rcons(t,h) -@ignore -@mindex rcons -@end ignore -@tindex rcons (rewrites) -This is like @code{cons}, except that the @emph{last} element -is matched to @expr{h}, with the remaining elements matched -to @expr{t}. - -@item apply(f,args) -@ignore -@mindex apply -@end ignore -@tindex apply (rewrites) -This matches any function call. The name of the function, in -the form of a variable, is matched to @expr{f}. The arguments -of the function, as a vector of zero or more objects, are -matched to @samp{args}. Constants, variables, and vectors -do @emph{not} match an @code{apply} pattern. For example, -@samp{apply(f,x)} matches any function call, @samp{apply(quote(f),x)} -matches any call to the function @samp{f}, @samp{apply(f,[a,b])} -matches any function call with exactly two arguments, and -@samp{apply(quote(f), cons(a,cons(b,x)))} matches any call -to the function @samp{f} with two or more arguments. Another -way to implement the latter, if the rest of the rule does not -need to refer to the first two arguments of @samp{f} by name, -would be @samp{apply(quote(f), x :: vlen(x) >= 2)}. -Here's a more interesting sample use of @code{apply}: - -@example -apply(f,[x+n]) := n + apply(f,[x]) - :: in(f, [floor,ceil,round,trunc]) :: integer(n) -@end example - -Note, however, that this will be slower to match than a rule -set with four separate rules. The reason is that Calc sorts -the rules of a rule set according to top-level function name; -if the top-level function is @code{apply}, Calc must try the -rule for every single formula and sub-formula. If the top-level -function in the pattern is, say, @code{floor}, then Calc invokes -the rule only for sub-formulas which are calls to @code{floor}. - -Formulas normally written with operators like @code{+} are still -considered function calls: @code{apply(f,x)} matches @samp{a+b} -with @samp{f = add}, @samp{x = [a,b]}. - -You must use @code{apply} for meta-variables with function names -on both sides of a rewrite rule: @samp{apply(f, [x]) := f(x+1)} -is @emph{not} correct, because it rewrites @samp{spam(6)} into -@samp{f(7)}. The righthand side should be @samp{apply(f, [x+1])}. -Also note that you will have to use No-Simplify mode (@kbd{m O}) -when entering this rule so that the @code{apply} isn't -evaluated immediately to get the new rule @samp{f(x) := f(x+1)}. -Or, use @kbd{s e} to enter the rule without going through the stack, -or enter the rule as @samp{apply(f, [x]) := apply(f, [x+1]) @w{:: 1}}. -@xref{Conditional Rewrite Rules}. - -@item select(x) -@ignore -@starindex -@end ignore -@tindex select -This is used for applying rules to formulas with selections; -@pxref{Selections with Rewrite Rules}. -@end table - -Special functions for the righthand sides of rules are: - -@table @samp -@item quote(x) -The notation @samp{quote(x)} is changed to @samp{x} when the -righthand side is used. As far as the rewrite rule is concerned, -@code{quote} is invisible. However, @code{quote} has the special -property in Calc that its argument is not evaluated. Thus, -while it will not work to put the rule @samp{t(a) := typeof(a)} -on the stack because @samp{typeof(a)} is evaluated immediately -to produce @samp{t(a) := 100}, you can use @code{quote} to -protect the righthand side: @samp{t(a) := quote(typeof(a))}. -(@xref{Conditional Rewrite Rules}, for another trick for -protecting rules from evaluation.) - -@item plain(x) -Special properties of and simplifications for the function call -@expr{x} are not used. One interesting case where @code{plain} -is useful is the rule, @samp{q(x) := quote(x)}, trying to expand a -shorthand notation for the @code{quote} function. This rule will -not work as shown; instead of replacing @samp{q(foo)} with -@samp{quote(foo)}, it will replace it with @samp{foo}! The correct -rule would be @samp{q(x) := plain(quote(x))}. - -@item cons(h,t) -Where @expr{t} is a vector, this is converted into an expanded -vector during rewrite processing. Note that @code{cons} is a regular -Calc function which normally does this anyway; the only way @code{cons} -is treated specially by rewrites is that @code{cons} on the righthand -side of a rule will be evaluated even if default simplifications -have been turned off. - -@item rcons(t,h) -Analogous to @code{cons} except putting @expr{h} at the @emph{end} of -the vector @expr{t}. - -@item apply(f,args) -Where @expr{f} is a variable and @var{args} is a vector, this -is converted to a function call. Once again, note that @code{apply} -is also a regular Calc function. - -@item eval(x) -@ignore -@starindex -@end ignore -@tindex eval -The formula @expr{x} is handled in the usual way, then the -default simplifications are applied to it even if they have -been turned off normally. This allows you to treat any function -similarly to the way @code{cons} and @code{apply} are always -treated. However, there is a slight difference: @samp{cons(2+3, [])} -with default simplifications off will be converted to @samp{[2+3]}, -whereas @samp{eval(cons(2+3, []))} will be converted to @samp{[5]}. - -@item evalsimp(x) -@ignore -@starindex -@end ignore -@tindex evalsimp -The formula @expr{x} has meta-variables substituted in the usual -way, then algebraically simplified as if by the @kbd{a s} command. - -@item evalextsimp(x) -@ignore -@starindex -@end ignore -@tindex evalextsimp -The formula @expr{x} has meta-variables substituted in the normal -way, then ``extendedly'' simplified as if by the @kbd{a e} command. - -@item select(x) -@xref{Selections with Rewrite Rules}. -@end table - -There are also some special functions you can use in conditions. - -@table @samp -@item let(v := x) -@ignore -@starindex -@end ignore -@tindex let -The expression @expr{x} is evaluated with meta-variables substituted. -The @kbd{a s} command's simplifications are @emph{not} applied by -default, but @expr{x} can include calls to @code{evalsimp} or -@code{evalextsimp} as described above to invoke higher levels -of simplification. The -result of @expr{x} is then bound to the meta-variable @expr{v}. As -usual, if this meta-variable has already been matched to something -else the two values must be equal; if the meta-variable is new then -it is bound to the result of the expression. This variable can then -appear in later conditions, and on the righthand side of the rule. -In fact, @expr{v} may be any pattern in which case the result of -evaluating @expr{x} is matched to that pattern, binding any -meta-variables that appear in that pattern. Note that @code{let} -can only appear by itself as a condition, or as one term of an -@samp{&&} which is a whole condition: It cannot be inside -an @samp{||} term or otherwise buried. - -The alternate, equivalent form @samp{let(v, x)} is also recognized. -Note that the use of @samp{:=} by @code{let}, while still being -assignment-like in character, is unrelated to the use of @samp{:=} -in the main part of a rewrite rule. - -As an example, @samp{f(a) := g(ia) :: let(ia := 1/a) :: constant(ia)} -replaces @samp{f(a)} with @samp{g} of the inverse of @samp{a}, if -that inverse exists and is constant. For example, if @samp{a} is a -singular matrix the operation @samp{1/a} is left unsimplified and -@samp{constant(ia)} fails, but if @samp{a} is an invertible matrix -then the rule succeeds. Without @code{let} there would be no way -to express this rule that didn't have to invert the matrix twice. -Note that, because the meta-variable @samp{ia} is otherwise unbound -in this rule, the @code{let} condition itself always ``succeeds'' -because no matter what @samp{1/a} evaluates to, it can successfully -be bound to @code{ia}. - -Here's another example, for integrating cosines of linear -terms: @samp{myint(cos(y),x) := sin(y)/b :: let([a,b,x] := lin(y,x))}. -The @code{lin} function returns a 3-vector if its argument is linear, -or leaves itself unevaluated if not. But an unevaluated @code{lin} -call will not match the 3-vector on the lefthand side of the @code{let}, -so this @code{let} both verifies that @code{y} is linear, and binds -the coefficients @code{a} and @code{b} for use elsewhere in the rule. -(It would have been possible to use @samp{sin(a x + b)/b} for the -righthand side instead, but using @samp{sin(y)/b} avoids gratuitous -rearrangement of the argument of the sine.) - -@ignore -@starindex -@end ignore -@tindex ierf -Similarly, here is a rule that implements an inverse-@code{erf} -function. It uses @code{root} to search for a solution. If -@code{root} succeeds, it will return a vector of two numbers -where the first number is the desired solution. If no solution -is found, @code{root} remains in symbolic form. So we use -@code{let} to check that the result was indeed a vector. - -@example -ierf(x) := y :: let([y,z] := root(erf(a) = x, a, .5)) -@end example - -@item matches(v,p) -The meta-variable @var{v}, which must already have been matched -to something elsewhere in the rule, is compared against pattern -@var{p}. Since @code{matches} is a standard Calc function, it -can appear anywhere in a condition. But if it appears alone or -as a term of a top-level @samp{&&}, then you get the special -extra feature that meta-variables which are bound to things -inside @var{p} can be used elsewhere in the surrounding rewrite -rule. - -The only real difference between @samp{let(p := v)} and -@samp{matches(v, p)} is that the former evaluates @samp{v} using -the default simplifications, while the latter does not. - -@item remember -@vindex remember -This is actually a variable, not a function. If @code{remember} -appears as a condition in a rule, then when that rule succeeds -the original expression and rewritten expression are added to the -front of the rule set that contained the rule. If the rule set -was not stored in a variable, @code{remember} is ignored. The -lefthand side is enclosed in @code{quote} in the added rule if it -contains any variables. - -For example, the rule @samp{f(n) := n f(n-1) :: remember} applied -to @samp{f(7)} will add the rule @samp{f(7) := 7 f(6)} to the front -of the rule set. The rule set @code{EvalRules} works slightly -differently: There, the evaluation of @samp{f(6)} will complete before -the result is added to the rule set, in this case as @samp{f(7) := 5040}. -Thus @code{remember} is most useful inside @code{EvalRules}. - -It is up to you to ensure that the optimization performed by -@code{remember} is safe. For example, the rule @samp{foo(n) := n -:: evalv(eatfoo) > 0 :: remember} is a bad idea (@code{evalv} is -the function equivalent of the @kbd{=} command); if the variable -@code{eatfoo} ever contains 1, rules like @samp{foo(7) := 7} will -be added to the rule set and will continue to operate even if -@code{eatfoo} is later changed to 0. - -@item remember(c) -@ignore -@starindex -@end ignore -@tindex remember -Remember the match as described above, but only if condition @expr{c} -is true. For example, @samp{remember(n % 4 = 0)} in the above factorial -rule remembers only every fourth result. Note that @samp{remember(1)} -is equivalent to @samp{remember}, and @samp{remember(0)} has no effect. -@end table - -@node Composing Patterns in Rewrite Rules, Nested Formulas with Rewrite Rules, Other Features of Rewrite Rules, Rewrite Rules -@subsection Composing Patterns in Rewrite Rules - -@noindent -There are three operators, @samp{&&&}, @samp{|||}, and @samp{!!!}, -that combine rewrite patterns to make larger patterns. The -combinations are ``and,'' ``or,'' and ``not,'' respectively, and -these operators are the pattern equivalents of @samp{&&}, @samp{||} -and @samp{!} (which operate on zero-or-nonzero logical values). - -Note that @samp{&&&}, @samp{|||}, and @samp{!!!} are left in symbolic -form by all regular Calc features; they have special meaning only in -the context of rewrite rule patterns. - -The pattern @samp{@var{p1} &&& @var{p2}} matches anything that -matches both @var{p1} and @var{p2}. One especially useful case is -when one of @var{p1} or @var{p2} is a meta-variable. For example, -here is a rule that operates on error forms: - -@example -f(x &&& a +/- b, x) := g(x) -@end example - -This does the same thing, but is arguably simpler than, the rule - -@example -f(a +/- b, a +/- b) := g(a +/- b) -@end example - -@ignore -@starindex -@end ignore -@tindex ends -Here's another interesting example: - -@example -ends(cons(a, x) &&& rcons(y, b)) := [a, b] -@end example - -@noindent -which effectively clips out the middle of a vector leaving just -the first and last elements. This rule will change a one-element -vector @samp{[a]} to @samp{[a, a]}. The similar rule - -@example -ends(cons(a, rcons(y, b))) := [a, b] -@end example - -@noindent -would do the same thing except that it would fail to match a -one-element vector. - -@tex -\bigskip -@end tex - -The pattern @samp{@var{p1} ||| @var{p2}} matches anything that -matches either @var{p1} or @var{p2}. Calc first tries matching -against @var{p1}; if that fails, it goes on to try @var{p2}. - -@ignore -@starindex -@end ignore -@tindex curve -A simple example of @samp{|||} is - -@example -curve(inf ||| -inf) := 0 -@end example - -@noindent -which converts both @samp{curve(inf)} and @samp{curve(-inf)} to zero. - -Here is a larger example: - -@example -log(a, b) ||| (ln(a) :: let(b := e)) := mylog(a, b) -@end example - -This matches both generalized and natural logarithms in a single rule. -Note that the @samp{::} term must be enclosed in parentheses because -that operator has lower precedence than @samp{|||} or @samp{:=}. - -(In practice this rule would probably include a third alternative, -omitted here for brevity, to take care of @code{log10}.) - -While Calc generally treats interior conditions exactly the same as -conditions on the outside of a rule, it does guarantee that if all the -variables in the condition are special names like @code{e}, or already -bound in the pattern to which the condition is attached (say, if -@samp{a} had appeared in this condition), then Calc will process this -condition right after matching the pattern to the left of the @samp{::}. -Thus, we know that @samp{b} will be bound to @samp{e} only if the -@code{ln} branch of the @samp{|||} was taken. - -Note that this rule was careful to bind the same set of meta-variables -on both sides of the @samp{|||}. Calc does not check this, but if -you bind a certain meta-variable only in one branch and then use that -meta-variable elsewhere in the rule, results are unpredictable: - -@example -f(a,b) ||| g(b) := h(a,b) -@end example - -Here if the pattern matches @samp{g(17)}, Calc makes no promises about -the value that will be substituted for @samp{a} on the righthand side. - -@tex -\bigskip -@end tex - -The pattern @samp{!!! @var{pat}} matches anything that does not -match @var{pat}. Any meta-variables that are bound while matching -@var{pat} remain unbound outside of @var{pat}. - -For example, - -@example -f(x &&& !!! a +/- b, !!![]) := g(x) -@end example - -@noindent -converts @code{f} whose first argument is anything @emph{except} an -error form, and whose second argument is not the empty vector, into -a similar call to @code{g} (but without the second argument). - -If we know that the second argument will be a vector (empty or not), -then an equivalent rule would be: - -@example -f(x, y) := g(x) :: typeof(x) != 7 :: vlen(y) > 0 -@end example - -@noindent -where of course 7 is the @code{typeof} code for error forms. -Another final condition, that works for any kind of @samp{y}, -would be @samp{!istrue(y == [])}. (The @code{istrue} function -returns an explicit 0 if its argument was left in symbolic form; -plain @samp{!(y == [])} or @samp{y != []} would not work to replace -@samp{!!![]} since these would be left unsimplified, and thus cause -the rule to fail, if @samp{y} was something like a variable name.) - -It is possible for a @samp{!!!} to refer to meta-variables bound -elsewhere in the pattern. For example, - -@example -f(a, !!!a) := g(a) -@end example - -@noindent -matches any call to @code{f} with different arguments, changing -this to @code{g} with only the first argument. - -If a function call is to be matched and one of the argument patterns -contains a @samp{!!!} somewhere inside it, that argument will be -matched last. Thus - -@example -f(!!!a, a) := g(a) -@end example - -@noindent -will be careful to bind @samp{a} to the second argument of @code{f} -before testing the first argument. If Calc had tried to match the -first argument of @code{f} first, the results would have been -disastrous: since @code{a} was unbound so far, the pattern @samp{a} -would have matched anything at all, and the pattern @samp{!!!a} -therefore would @emph{not} have matched anything at all! - -@node Nested Formulas with Rewrite Rules, Multi-Phase Rewrite Rules, Composing Patterns in Rewrite Rules, Rewrite Rules -@subsection Nested Formulas with Rewrite Rules - -@noindent -When @kbd{a r} (@code{calc-rewrite}) is used, it takes an expression from -the top of the stack and attempts to match any of the specified rules -to any part of the expression, starting with the whole expression -and then, if that fails, trying deeper and deeper sub-expressions. -For each part of the expression, the rules are tried in the order -they appear in the rules vector. The first rule to match the first -sub-expression wins; it replaces the matched sub-expression according -to the @var{new} part of the rule. - -Often, the rule set will match and change the formula several times. -The top-level formula is first matched and substituted repeatedly until -it no longer matches the pattern; then, sub-formulas are tried, and -so on. Once every part of the formula has gotten its chance, the -rewrite mechanism starts over again with the top-level formula -(in case a substitution of one of its arguments has caused it again -to match). This continues until no further matches can be made -anywhere in the formula. - -It is possible for a rule set to get into an infinite loop. The -most obvious case, replacing a formula with itself, is not a problem -because a rule is not considered to ``succeed'' unless the righthand -side actually comes out to something different than the original -formula or sub-formula that was matched. But if you accidentally -had both @samp{ln(a b) := ln(a) + ln(b)} and the reverse -@samp{ln(a) + ln(b) := ln(a b)} in your rule set, Calc would -run forever switching a formula back and forth between the two -forms. - -To avoid disaster, Calc normally stops after 100 changes have been -made to the formula. This will be enough for most multiple rewrites, -but it will keep an endless loop of rewrites from locking up the -computer forever. (On most systems, you can also type @kbd{C-g} to -halt any Emacs command prematurely.) - -To change this limit, give a positive numeric prefix argument. -In particular, @kbd{M-1 a r} applies only one rewrite at a time, -useful when you are first testing your rule (or just if repeated -rewriting is not what is called for by your application). - -@ignore -@starindex -@end ignore -@ignore -@mindex iter@idots -@end ignore -@tindex iterations -You can also put a ``function call'' @samp{iterations(@var{n})} -in place of a rule anywhere in your rules vector (but usually at -the top). Then, @var{n} will be used instead of 100 as the default -number of iterations for this rule set. You can use -@samp{iterations(inf)} if you want no iteration limit by default. -A prefix argument will override the @code{iterations} limit in the -rule set. - -@example -[ iterations(1), - f(x) := f(x+1) ] -@end example - -More precisely, the limit controls the number of ``iterations,'' -where each iteration is a successful matching of a rule pattern whose -righthand side, after substituting meta-variables and applying the -default simplifications, is different from the original sub-formula -that was matched. - -A prefix argument of zero sets the limit to infinity. Use with caution! - -Given a negative numeric prefix argument, @kbd{a r} will match and -substitute the top-level expression up to that many times, but -will not attempt to match the rules to any sub-expressions. - -In a formula, @code{rewrite(@var{expr}, @var{rules}, @var{n})} -does a rewriting operation. Here @var{expr} is the expression -being rewritten, @var{rules} is the rule, vector of rules, or -variable containing the rules, and @var{n} is the optional -iteration limit, which may be a positive integer, a negative -integer, or @samp{inf} or @samp{-inf}. If @var{n} is omitted -the @code{iterations} value from the rule set is used; if both -are omitted, 100 is used. - -@node Multi-Phase Rewrite Rules, Selections with Rewrite Rules, Nested Formulas with Rewrite Rules, Rewrite Rules -@subsection Multi-Phase Rewrite Rules - -@noindent -It is possible to separate a rewrite rule set into several @dfn{phases}. -During each phase, certain rules will be enabled while certain others -will be disabled. A @dfn{phase schedule} controls the order in which -phases occur during the rewriting process. - -@ignore -@starindex -@end ignore -@tindex phase -@vindex all -If a call to the marker function @code{phase} appears in the rules -vector in place of a rule, all rules following that point will be -members of the phase(s) identified in the arguments to @code{phase}. -Phases are given integer numbers. The markers @samp{phase()} and -@samp{phase(all)} both mean the following rules belong to all phases; -this is the default at the start of the rule set. - -If you do not explicitly schedule the phases, Calc sorts all phase -numbers that appear in the rule set and executes the phases in -ascending order. For example, the rule set - -@example -@group -[ f0(x) := g0(x), - phase(1), - f1(x) := g1(x), - phase(2), - f2(x) := g2(x), - phase(3), - f3(x) := g3(x), - phase(1,2), - f4(x) := g4(x) ] -@end group -@end example - -@noindent -has three phases, 1 through 3. Phase 1 consists of the @code{f0}, -@code{f1}, and @code{f4} rules (in that order). Phase 2 consists of -@code{f0}, @code{f2}, and @code{f4}. Phase 3 consists of @code{f0} -and @code{f3}. - -When Calc rewrites a formula using this rule set, it first rewrites -the formula using only the phase 1 rules until no further changes are -possible. Then it switches to the phase 2 rule set and continues -until no further changes occur, then finally rewrites with phase 3. -When no more phase 3 rules apply, rewriting finishes. (This is -assuming @kbd{a r} with a large enough prefix argument to allow the -rewriting to run to completion; the sequence just described stops -early if the number of iterations specified in the prefix argument, -100 by default, is reached.) - -During each phase, Calc descends through the nested levels of the -formula as described previously. (@xref{Nested Formulas with Rewrite -Rules}.) Rewriting starts at the top of the formula, then works its -way down to the parts, then goes back to the top and works down again. -The phase 2 rules do not begin until no phase 1 rules apply anywhere -in the formula. - -@ignore -@starindex -@end ignore -@tindex schedule -A @code{schedule} marker appearing in the rule set (anywhere, but -conventionally at the top) changes the default schedule of phases. -In the simplest case, @code{schedule} has a sequence of phase numbers -for arguments; each phase number is invoked in turn until the -arguments to @code{schedule} are exhausted. Thus adding -@samp{schedule(3,2,1)} at the top of the above rule set would -reverse the order of the phases; @samp{schedule(1,2,3)} would have -no effect since this is the default schedule; and @samp{schedule(1,2,1,3)} -would give phase 1 a second chance after phase 2 has completed, before -moving on to phase 3. - -Any argument to @code{schedule} can instead be a vector of phase -numbers (or even of sub-vectors). Then the sub-sequence of phases -described by the vector are tried repeatedly until no change occurs -in any phase in the sequence. For example, @samp{schedule([1, 2], 3)} -tries phase 1, then phase 2, then, if either phase made any changes -to the formula, repeats these two phases until they can make no -further progress. Finally, it goes on to phase 3 for finishing -touches. - -Also, items in @code{schedule} can be variable names as well as -numbers. A variable name is interpreted as the name of a function -to call on the whole formula. For example, @samp{schedule(1, simplify)} -says to apply the phase-1 rules (presumably, all of them), then to -call @code{simplify} which is the function name equivalent of @kbd{a s}. -Likewise, @samp{schedule([1, simplify])} says to alternate between -phase 1 and @kbd{a s} until no further changes occur. - -Phases can be used purely to improve efficiency; if it is known that -a certain group of rules will apply only at the beginning of rewriting, -and a certain other group will apply only at the end, then rewriting -will be faster if these groups are identified as separate phases. -Once the phase 1 rules are done, Calc can put them aside and no longer -spend any time on them while it works on phase 2. - -There are also some problems that can only be solved with several -rewrite phases. For a real-world example of a multi-phase rule set, -examine the set @code{FitRules}, which is used by the curve-fitting -command to convert a model expression to linear form. -@xref{Curve Fitting Details}. This set is divided into four phases. -The first phase rewrites certain kinds of expressions to be more -easily linearizable, but less computationally efficient. After the -linear components have been picked out, the final phase includes the -opposite rewrites to put each component back into an efficient form. -If both sets of rules were included in one big phase, Calc could get -into an infinite loop going back and forth between the two forms. - -Elsewhere in @code{FitRules}, the components are first isolated, -then recombined where possible to reduce the complexity of the linear -fit, then finally packaged one component at a time into vectors. -If the packaging rules were allowed to begin before the recombining -rules were finished, some components might be put away into vectors -before they had a chance to recombine. By putting these rules in -two separate phases, this problem is neatly avoided. - -@node Selections with Rewrite Rules, Matching Commands, Multi-Phase Rewrite Rules, Rewrite Rules -@subsection Selections with Rewrite Rules - -@noindent -If a sub-formula of the current formula is selected (as by @kbd{j s}; -@pxref{Selecting Subformulas}), the @kbd{a r} (@code{calc-rewrite}) -command applies only to that sub-formula. Together with a negative -prefix argument, you can use this fact to apply a rewrite to one -specific part of a formula without affecting any other parts. - -@kindex j r -@pindex calc-rewrite-selection -The @kbd{j r} (@code{calc-rewrite-selection}) command allows more -sophisticated operations on selections. This command prompts for -the rules in the same way as @kbd{a r}, but it then applies those -rules to the whole formula in question even though a sub-formula -of it has been selected. However, the selected sub-formula will -first have been surrounded by a @samp{select( )} function call. -(Calc's evaluator does not understand the function name @code{select}; -this is only a tag used by the @kbd{j r} command.) - -For example, suppose the formula on the stack is @samp{2 (a + b)^2} -and the sub-formula @samp{a + b} is selected. This formula will -be rewritten to @samp{2 select(a + b)^2} and then the rewrite -rules will be applied in the usual way. The rewrite rules can -include references to @code{select} to tell where in the pattern -the selected sub-formula should appear. - -If there is still exactly one @samp{select( )} function call in -the formula after rewriting is done, it indicates which part of -the formula should be selected afterwards. Otherwise, the -formula will be unselected. - -You can make @kbd{j r} act much like @kbd{a r} by enclosing both parts -of the rewrite rule with @samp{select()}. However, @kbd{j r} -allows you to use the current selection in more flexible ways. -Suppose you wished to make a rule which removed the exponent from -the selected term; the rule @samp{select(a)^x := select(a)} would -work. In the above example, it would rewrite @samp{2 select(a + b)^2} -to @samp{2 select(a + b)}. This would then be returned to the -stack as @samp{2 (a + b)} with the @samp{a + b} selected. - -The @kbd{j r} command uses one iteration by default, unlike -@kbd{a r} which defaults to 100 iterations. A numeric prefix -argument affects @kbd{j r} in the same way as @kbd{a r}. -@xref{Nested Formulas with Rewrite Rules}. - -As with other selection commands, @kbd{j r} operates on the stack -entry that contains the cursor. (If the cursor is on the top-of-stack -@samp{.} marker, it works as if the cursor were on the formula -at stack level 1.) - -If you don't specify a set of rules, the rules are taken from the -top of the stack, just as with @kbd{a r}. In this case, the -cursor must indicate stack entry 2 or above as the formula to be -rewritten (otherwise the same formula would be used as both the -target and the rewrite rules). - -If the indicated formula has no selection, the cursor position within -the formula temporarily selects a sub-formula for the purposes of this -command. If the cursor is not on any sub-formula (e.g., it is in -the line-number area to the left of the formula), the @samp{select( )} -markers are ignored by the rewrite mechanism and the rules are allowed -to apply anywhere in the formula. - -As a special feature, the normal @kbd{a r} command also ignores -@samp{select( )} calls in rewrite rules. For example, if you used the -above rule @samp{select(a)^x := select(a)} with @kbd{a r}, it would apply -the rule as if it were @samp{a^x := a}. Thus, you can write general -purpose rules with @samp{select( )} hints inside them so that they -will ``do the right thing'' in both @kbd{a r} and @kbd{j r}, -both with and without selections. - -@node Matching Commands, Automatic Rewrites, Selections with Rewrite Rules, Rewrite Rules -@subsection Matching Commands - -@noindent -@kindex a m -@pindex calc-match -@tindex match -The @kbd{a m} (@code{calc-match}) [@code{match}] function takes a -vector of formulas and a rewrite-rule-style pattern, and produces -a vector of all formulas which match the pattern. The command -prompts you to enter the pattern; as for @kbd{a r}, you can enter -a single pattern (i.e., a formula with meta-variables), or a -vector of patterns, or a variable which contains patterns, or -you can give a blank response in which case the patterns are taken -from the top of the stack. The pattern set will be compiled once -and saved if it is stored in a variable. If there are several -patterns in the set, vector elements are kept if they match any -of the patterns. - -For example, @samp{match(a+b, [x, x+y, x-y, 7, x+y+z])} -will return @samp{[x+y, x-y, x+y+z]}. - -The @code{import} mechanism is not available for pattern sets. - -The @kbd{a m} command can also be used to extract all vector elements -which satisfy any condition: The pattern @samp{x :: x>0} will select -all the positive vector elements. - -@kindex I a m -@tindex matchnot -With the Inverse flag [@code{matchnot}], this command extracts all -vector elements which do @emph{not} match the given pattern. - -@ignore -@starindex -@end ignore -@tindex matches -There is also a function @samp{matches(@var{x}, @var{p})} which -evaluates to 1 if expression @var{x} matches pattern @var{p}, or -to 0 otherwise. This is sometimes useful for including into the -conditional clauses of other rewrite rules. - -@ignore -@starindex -@end ignore -@tindex vmatches -The function @code{vmatches} is just like @code{matches}, except -that if the match succeeds it returns a vector of assignments to -the meta-variables instead of the number 1. For example, -@samp{vmatches(f(1,2), f(a,b))} returns @samp{[a := 1, b := 2]}. -If the match fails, the function returns the number 0. - -@node Automatic Rewrites, Debugging Rewrites, Matching Commands, Rewrite Rules -@subsection Automatic Rewrites - -@noindent -@cindex @code{EvalRules} variable -@vindex EvalRules -It is possible to get Calc to apply a set of rewrite rules on all -results, effectively adding to the built-in set of default -simplifications. To do this, simply store your rule set in the -variable @code{EvalRules}. There is a convenient @kbd{s E} command -for editing @code{EvalRules}; @pxref{Operations on Variables}. - -For example, suppose you want @samp{sin(a + b)} to be expanded out -to @samp{sin(b) cos(a) + cos(b) sin(a)} wherever it appears, and -similarly for @samp{cos(a + b)}. The corresponding rewrite rule -set would be, - -@smallexample -@group -[ sin(a + b) := cos(a) sin(b) + sin(a) cos(b), - cos(a + b) := cos(a) cos(b) - sin(a) sin(b) ] -@end group -@end smallexample - -To apply these manually, you could put them in a variable called -@code{trigexp} and then use @kbd{a r trigexp} every time you wanted -to expand trig functions. But if instead you store them in the -variable @code{EvalRules}, they will automatically be applied to all -sines and cosines of sums. Then, with @samp{2 x} and @samp{45} on -the stack, typing @kbd{+ S} will (assuming Degrees mode) result in -@samp{0.7071 sin(2 x) + 0.7071 cos(2 x)} automatically. - -As each level of a formula is evaluated, the rules from -@code{EvalRules} are applied before the default simplifications. -Rewriting continues until no further @code{EvalRules} apply. -Note that this is different from the usual order of application of -rewrite rules: @code{EvalRules} works from the bottom up, simplifying -the arguments to a function before the function itself, while @kbd{a r} -applies rules from the top down. - -Because the @code{EvalRules} are tried first, you can use them to -override the normal behavior of any built-in Calc function. - -It is important not to write a rule that will get into an infinite -loop. For example, the rule set @samp{[f(0) := 1, f(n) := n f(n-1)]} -appears to be a good definition of a factorial function, but it is -unsafe. Imagine what happens if @samp{f(2.5)} is simplified. Calc -will continue to subtract 1 from this argument forever without reaching -zero. A safer second rule would be @samp{f(n) := n f(n-1) :: n>0}. -Another dangerous rule is @samp{g(x, y) := g(y, x)}. Rewriting -@samp{g(2, 4)}, this would bounce back and forth between that and -@samp{g(4, 2)} forever. If an infinite loop in @code{EvalRules} -occurs, Emacs will eventually stop with a ``Computation got stuck -or ran too long'' message. - -Another subtle difference between @code{EvalRules} and regular rewrites -concerns rules that rewrite a formula into an identical formula. For -example, @samp{f(n) := f(floor(n))} ``fails to match'' when @expr{n} is -already an integer. But in @code{EvalRules} this case is detected only -if the righthand side literally becomes the original formula before any -further simplification. This means that @samp{f(n) := f(floor(n))} will -get into an infinite loop if it occurs in @code{EvalRules}. Calc will -replace @samp{f(6)} with @samp{f(floor(6))}, which is different from -@samp{f(6)}, so it will consider the rule to have matched and will -continue simplifying that formula; first the argument is simplified -to get @samp{f(6)}, then the rule matches again to get @samp{f(floor(6))} -again, ad infinitum. A much safer rule would check its argument first, -say, with @samp{f(n) := f(floor(n)) :: !dint(n)}. - -(What really happens is that the rewrite mechanism substitutes the -meta-variables in the righthand side of a rule, compares to see if the -result is the same as the original formula and fails if so, then uses -the default simplifications to simplify the result and compares again -(and again fails if the formula has simplified back to its original -form). The only special wrinkle for the @code{EvalRules} is that the -same rules will come back into play when the default simplifications -are used. What Calc wants to do is build @samp{f(floor(6))}, see that -this is different from the original formula, simplify to @samp{f(6)}, -see that this is the same as the original formula, and thus halt the -rewriting. But while simplifying, @samp{f(6)} will again trigger -the same @code{EvalRules} rule and Calc will get into a loop inside -the rewrite mechanism itself.) - -The @code{phase}, @code{schedule}, and @code{iterations} markers do -not work in @code{EvalRules}. If the rule set is divided into phases, -only the phase 1 rules are applied, and the schedule is ignored. -The rules are always repeated as many times as possible. - -The @code{EvalRules} are applied to all function calls in a formula, -but not to numbers (and other number-like objects like error forms), -nor to vectors or individual variable names. (Though they will apply -to @emph{components} of vectors and error forms when appropriate.) You -might try to make a variable @code{phihat} which automatically expands -to its definition without the need to press @kbd{=} by writing the -rule @samp{quote(phihat) := (1-sqrt(5))/2}, but unfortunately this rule -will not work as part of @code{EvalRules}. - -Finally, another limitation is that Calc sometimes calls its built-in -functions directly rather than going through the default simplifications. -When it does this, @code{EvalRules} will not be able to override those -functions. For example, when you take the absolute value of the complex -number @expr{(2, 3)}, Calc computes @samp{sqrt(2*2 + 3*3)} by calling -the multiplication, addition, and square root functions directly rather -than applying the default simplifications to this formula. So an -@code{EvalRules} rule that (perversely) rewrites @samp{sqrt(13) := 6} -would not apply. (However, if you put Calc into Symbolic mode so that -@samp{sqrt(13)} will be left in symbolic form by the built-in square -root function, your rule will be able to apply. But if the complex -number were @expr{(3,4)}, so that @samp{sqrt(25)} must be calculated, -then Symbolic mode will not help because @samp{sqrt(25)} can be -evaluated exactly to 5.) - -One subtle restriction that normally only manifests itself with -@code{EvalRules} is that while a given rewrite rule is in the process -of being checked, that same rule cannot be recursively applied. Calc -effectively removes the rule from its rule set while checking the rule, -then puts it back once the match succeeds or fails. (The technical -reason for this is that compiled pattern programs are not reentrant.) -For example, consider the rule @samp{foo(x) := x :: foo(x/2) > 0} -attempting to match @samp{foo(8)}. This rule will be inactive while -the condition @samp{foo(4) > 0} is checked, even though it might be -an integral part of evaluating that condition. Note that this is not -a problem for the more usual recursive type of rule, such as -@samp{foo(x) := foo(x/2)}, because there the rule has succeeded and -been reactivated by the time the righthand side is evaluated. - -If @code{EvalRules} has no stored value (its default state), or if -anything but a vector is stored in it, then it is ignored. - -Even though Calc's rewrite mechanism is designed to compare rewrite -rules to formulas as quickly as possible, storing rules in -@code{EvalRules} may make Calc run substantially slower. This is -particularly true of rules where the top-level call is a commonly used -function, or is not fixed. The rule @samp{f(n) := n f(n-1) :: n>0} will -only activate the rewrite mechanism for calls to the function @code{f}, -but @samp{lg(n) + lg(m) := lg(n m)} will check every @samp{+} operator. - -@smallexample -apply(f, [a*b]) := apply(f, [a]) + apply(f, [b]) :: in(f, [ln, log10]) -@end smallexample - -@noindent -may seem more ``efficient'' than two separate rules for @code{ln} and -@code{log10}, but actually it is vastly less efficient because rules -with @code{apply} as the top-level pattern must be tested against -@emph{every} function call that is simplified. - -@cindex @code{AlgSimpRules} variable -@vindex AlgSimpRules -Suppose you want @samp{sin(a + b)} to be expanded out not all the time, -but only when @kbd{a s} is used to simplify the formula. The variable -@code{AlgSimpRules} holds rules for this purpose. The @kbd{a s} command -will apply @code{EvalRules} and @code{AlgSimpRules} to the formula, as -well as all of its built-in simplifications. - -Most of the special limitations for @code{EvalRules} don't apply to -@code{AlgSimpRules}. Calc simply does an @kbd{a r AlgSimpRules} -command with an infinite repeat count as the first step of @kbd{a s}. -It then applies its own built-in simplifications throughout the -formula, and then repeats these two steps (along with applying the -default simplifications) until no further changes are possible. - -@cindex @code{ExtSimpRules} variable -@cindex @code{UnitSimpRules} variable -@vindex ExtSimpRules -@vindex UnitSimpRules -There are also @code{ExtSimpRules} and @code{UnitSimpRules} variables -that are used by @kbd{a e} and @kbd{u s}, respectively; these commands -also apply @code{EvalRules} and @code{AlgSimpRules}. The variable -@code{IntegSimpRules} contains simplification rules that are used -only during integration by @kbd{a i}. - -@node Debugging Rewrites, Examples of Rewrite Rules, Automatic Rewrites, Rewrite Rules -@subsection Debugging Rewrites - -@noindent -If a buffer named @samp{*Trace*} exists, the rewrite mechanism will -record some useful information there as it operates. The original -formula is written there, as is the result of each successful rewrite, -and the final result of the rewriting. All phase changes are also -noted. - -Calc always appends to @samp{*Trace*}. You must empty this buffer -yourself periodically if it is in danger of growing unwieldy. - -Note that the rewriting mechanism is substantially slower when the -@samp{*Trace*} buffer exists, even if the buffer is not visible on -the screen. Once you are done, you will probably want to kill this -buffer (with @kbd{C-x k *Trace* @key{RET}}). If you leave it in -existence and forget about it, all your future rewrite commands will -be needlessly slow. - -@node Examples of Rewrite Rules, , Debugging Rewrites, Rewrite Rules -@subsection Examples of Rewrite Rules - -@noindent -Returning to the example of substituting the pattern -@samp{sin(x)^2 + cos(x)^2} with 1, we saw that the rule -@samp{opt(a) sin(x)^2 + opt(a) cos(x)^2 := a} does a good job of -finding suitable cases. Another solution would be to use the rule -@samp{cos(x)^2 := 1 - sin(x)^2}, followed by algebraic simplification -if necessary. This rule will be the most effective way to do the job, -but at the expense of making some changes that you might not desire. - -Another algebraic rewrite rule is @samp{exp(x+y) := exp(x) exp(y)}. -To make this work with the @w{@kbd{j r}} command so that it can be -easily targeted to a particular exponential in a large formula, -you might wish to write the rule as @samp{select(exp(x+y)) := -select(exp(x) exp(y))}. The @samp{select} markers will be -ignored by the regular @kbd{a r} command -(@pxref{Selections with Rewrite Rules}). - -A surprisingly useful rewrite rule is @samp{a/(b-c) := a*(b+c)/(b^2-c^2)}. -This will simplify the formula whenever @expr{b} and/or @expr{c} can -be made simpler by squaring. For example, applying this rule to -@samp{2 / (sqrt(2) + 3)} yields @samp{6:7 - 2:7 sqrt(2)} (assuming -Symbolic mode has been enabled to keep the square root from being -evaluated to a floating-point approximation). This rule is also -useful when working with symbolic complex numbers, e.g., -@samp{(a + b i) / (c + d i)}. - -As another example, we could define our own ``triangular numbers'' function -with the rules @samp{[tri(0) := 0, tri(n) := n + tri(n-1) :: n>0]}. Enter -this vector and store it in a variable: @kbd{@w{s t} trirules}. Now, given -a suitable formula like @samp{tri(5)} on the stack, type @samp{a r trirules} -to apply these rules repeatedly. After six applications, @kbd{a r} will -stop with 15 on the stack. Once these rules are debugged, it would probably -be most useful to add them to @code{EvalRules} so that Calc will evaluate -the new @code{tri} function automatically. We could then use @kbd{Z K} on -the keyboard macro @kbd{' tri($) @key{RET}} to make a command that applies -@code{tri} to the value on the top of the stack. @xref{Programming}. - -@cindex Quaternions -The following rule set, contributed by -@texline Fran\c cois -@infoline Francois -Pinard, implements @dfn{quaternions}, a generalization of the concept of -complex numbers. Quaternions have four components, and are here -represented by function calls @samp{quat(@var{w}, [@var{x}, @var{y}, -@var{z}])} with ``real part'' @var{w} and the three ``imaginary'' parts -collected into a vector. Various arithmetical operations on quaternions -are supported. To use these rules, either add them to @code{EvalRules}, -or create a command based on @kbd{a r} for simplifying quaternion -formulas. A convenient way to enter quaternions would be a command -defined by a keyboard macro containing: @kbd{' quat($$$$, [$$$, $$, $]) -@key{RET}}. - -@smallexample -[ quat(w, x, y, z) := quat(w, [x, y, z]), - quat(w, [0, 0, 0]) := w, - abs(quat(w, v)) := hypot(w, v), - -quat(w, v) := quat(-w, -v), - r + quat(w, v) := quat(r + w, v) :: real(r), - r - quat(w, v) := quat(r - w, -v) :: real(r), - quat(w1, v1) + quat(w2, v2) := quat(w1 + w2, v1 + v2), - r * quat(w, v) := quat(r * w, r * v) :: real(r), - plain(quat(w1, v1) * quat(w2, v2)) - := quat(w1 * w2 - v1 * v2, w1 * v2 + w2 * v1 + cross(v1, v2)), - quat(w1, v1) / r := quat(w1 / r, v1 / r) :: real(r), - z / quat(w, v) := z * quatinv(quat(w, v)), - quatinv(quat(w, v)) := quat(w, -v) / (w^2 + v^2), - quatsqr(quat(w, v)) := quat(w^2 - v^2, 2 * w * v), - quat(w, v)^k := quatsqr(quat(w, v)^(k / 2)) - :: integer(k) :: k > 0 :: k % 2 = 0, - quat(w, v)^k := quatsqr(quat(w, v)^((k - 1) / 2)) * quat(w, v) - :: integer(k) :: k > 2, - quat(w, v)^-k := quatinv(quat(w, v)^k) :: integer(k) :: k > 0 ] -@end smallexample - -Quaternions, like matrices, have non-commutative multiplication. -In other words, @expr{q1 * q2 = q2 * q1} is not necessarily true if -@expr{q1} and @expr{q2} are @code{quat} forms. The @samp{quat*quat} -rule above uses @code{plain} to prevent Calc from rearranging the -product. It may also be wise to add the line @samp{[quat(), matrix]} -to the @code{Decls} matrix, to ensure that Calc's other algebraic -operations will not rearrange a quaternion product. @xref{Declarations}. - -These rules also accept a four-argument @code{quat} form, converting -it to the preferred form in the first rule. If you would rather see -results in the four-argument form, just append the two items -@samp{phase(2), quat(w, [x, y, z]) := quat(w, x, y, z)} to the end -of the rule set. (But remember that multi-phase rule sets don't work -in @code{EvalRules}.) - -@node Units, Store and Recall, Algebra, Top -@chapter Operating on Units - -@noindent -One special interpretation of algebraic formulas is as numbers with units. -For example, the formula @samp{5 m / s^2} can be read ``five meters -per second squared.'' The commands in this chapter help you -manipulate units expressions in this form. Units-related commands -begin with the @kbd{u} prefix key. - -@menu -* Basic Operations on Units:: -* The Units Table:: -* Predefined Units:: -* User-Defined Units:: -* Logarithmic Units:: -* Musical Notes:: -@end menu - -@node Basic Operations on Units, The Units Table, Units, Units -@section Basic Operations on Units - -@noindent -A @dfn{units expression} is a formula which is basically a number -multiplied and/or divided by one or more @dfn{unit names}, which may -optionally be raised to integer powers. Actually, the value part need not -be a number; any product or quotient involving unit names is a units -expression. Many of the units commands will also accept any formula, -where the command applies to all units expressions which appear in the -formula. - -A unit name is a variable whose name appears in the @dfn{unit table}, -or a variable whose name is a prefix character like @samp{k} (for ``kilo'') -or @samp{u} (for ``micro'') followed by a name in the unit table. -A substantial table of built-in units is provided with Calc; -@pxref{Predefined Units}. You can also define your own unit names; -@pxref{User-Defined Units}. - -Note that if the value part of a units expression is exactly @samp{1}, -it will be removed by the Calculator's automatic algebra routines: The -formula @samp{1 mm} is ``simplified'' to @samp{mm}. This is only a -display anomaly, however; @samp{mm} will work just fine as a -representation of one millimeter. - -You may find that Algebraic mode (@pxref{Algebraic Entry}) makes working -with units expressions easier. Otherwise, you will have to remember -to hit the apostrophe key every time you wish to enter units. - -@kindex u s -@pindex calc-simplify-units -@ignore -@mindex usimpl@idots -@end ignore -@tindex usimplify -The @kbd{u s} (@code{calc-simplify-units}) [@code{usimplify}] command -simplifies a units -expression. It uses @kbd{a s} (@code{calc-simplify}) to simplify the -expression first as a regular algebraic formula; it then looks for -features that can be further simplified by converting one object's units -to be compatible with another's. For example, @samp{5 m + 23 mm} will -simplify to @samp{5.023 m}. When different but compatible units are -added, the righthand term's units are converted to match those of the -lefthand term. @xref{Simplification Modes}, for a way to have this done -automatically at all times. - -Units simplification also handles quotients of two units with the same -dimensionality, as in @w{@samp{2 in s/L cm}} to @samp{5.08 s/L}; fractional -powers of unit expressions, as in @samp{sqrt(9 mm^2)} to @samp{3 mm} and -@samp{sqrt(9 acre)} to a quantity in meters; and @code{floor}, -@code{ceil}, @code{round}, @code{rounde}, @code{roundu}, @code{trunc}, -@code{float}, @code{frac}, @code{abs}, and @code{clean} -applied to units expressions, in which case -the operation in question is applied only to the numeric part of the -expression. Finally, trigonometric functions of quantities with units -of angle are evaluated, regardless of the current angular mode. - -@kindex u c -@pindex calc-convert-units -The @kbd{u c} (@code{calc-convert-units}) command converts a units -expression to new, compatible units. For example, given the units -expression @samp{55 mph}, typing @kbd{u c m/s @key{RET}} produces -@samp{24.5872 m/s}. If you have previously converted a units expression -with the same type of units (in this case, distance over time), you will -be offered the previous choice of new units as a default. Continuing -the above example, entering the units expression @samp{100 km/hr} and -typing @kbd{u c @key{RET}} (without specifying new units) produces -@samp{27.7777777778 m/s}. - -@kindex u t -@pindex calc-convert-temperature -@cindex Temperature conversion -The @kbd{u c} command treats temperature units (like @samp{degC} and -@samp{K}) as relative temperatures. For example, @kbd{u c} converts -@samp{10 degC} to @samp{18 degF}: A change of 10 degrees Celsius -corresponds to a change of 18 degrees Fahrenheit. To convert absolute -temperatures, you can use the @kbd{u t} -(@code{calc-convert-temperature}) command. The value on the stack -must be a simple units expression with units of temperature only. -This command would convert @samp{10 degC} to @samp{50 degF}, the -equivalent temperature on the Fahrenheit scale. - -While many of Calc's conversion factors are exact, some are necessarily -approximate. If Calc is in fraction mode (@pxref{Fraction Mode}), then -unit conversions will try to give exact, rational conversions, but it -isn't always possible. Given @samp{55 mph} in fraction mode, typing -@kbd{u c m/s @key{RET}} produces @samp{15367:625 m/s}, for example, -while typing @kbd{u c au/yr @key{RET}} produces -@samp{5.18665819999e-3 au/yr}. - -If the units you request are inconsistent with the original units, the -number will be converted into your units times whatever ``remainder'' -units are left over. For example, converting @samp{55 mph} into acres -produces @samp{6.08e-3 acre / m s}. (Recall that multiplication binds -more strongly than division in Calc formulas, so the units here are -acres per meter-second.) Remainder units are expressed in terms of -``fundamental'' units like @samp{m} and @samp{s}, regardless of the -input units. - -One special exception is that if you specify a single unit name, and -a compatible unit appears somewhere in the units expression, then -that compatible unit will be converted to the new unit and the -remaining units in the expression will be left alone. For example, -given the input @samp{980 cm/s^2}, the command @kbd{u c ms} will -change the @samp{s} to @samp{ms} to get @samp{9.8e-4 cm/ms^2}. -The ``remainder unit'' @samp{cm} is left alone rather than being -changed to the base unit @samp{m}. - -You can use explicit unit conversion instead of the @kbd{u s} command -to gain more control over the units of the result of an expression. -For example, given @samp{5 m + 23 mm}, you can type @kbd{u c m} or -@kbd{u c mm} to express the result in either meters or millimeters. -(For that matter, you could type @kbd{u c fath} to express the result -in fathoms, if you preferred!) - -In place of a specific set of units, you can also enter one of the -units system names @code{si}, @code{mks} (equivalent), or @code{cgs}. -For example, @kbd{u c si @key{RET}} converts the expression into -International System of Units (SI) base units. Also, @kbd{u c base} -converts to Calc's base units, which are the same as @code{si} units -except that @code{base} uses @samp{g} as the fundamental unit of mass -whereas @code{si} uses @samp{kg}. - -@cindex Composite units -The @kbd{u c} command also accepts @dfn{composite units}, which -are expressed as the sum of several compatible unit names. For -example, converting @samp{30.5 in} to units @samp{mi+ft+in} (miles, -feet, and inches) produces @samp{2 ft + 6.5 in}. Calc first -sorts the unit names into order of decreasing relative size. -It then accounts for as much of the input quantity as it can -using an integer number times the largest unit, then moves on -to the next smaller unit, and so on. Only the smallest unit -may have a non-integer amount attached in the result. A few -standard unit names exist for common combinations, such as -@code{mfi} for @samp{mi+ft+in}, and @code{tpo} for @samp{ton+lb+oz}. -Composite units are expanded as if by @kbd{a x}, so that -@samp{(ft+in)/hr} is first converted to @samp{ft/hr+in/hr}. - -If the value on the stack does not contain any units, @kbd{u c} will -prompt first for the old units which this value should be considered -to have, then for the new units. Assuming the old and new units you -give are consistent with each other, the result also will not contain -any units. For example, @kbd{@w{u c} cm @key{RET} in @key{RET}} -converts the number 2 on the stack to 5.08. - -@kindex u b -@pindex calc-base-units -The @kbd{u b} (@code{calc-base-units}) command is shorthand for -@kbd{u c base}; it converts the units expression on the top of the -stack into @code{base} units. If @kbd{u s} does not simplify a -units expression as far as you would like, try @kbd{u b}. - -Like the @kbd{u c} command, the @kbd{u b} command treats temperature -units as relative temperatures. - -@kindex u r -@pindex calc-remove-units -@kindex u x -@pindex calc-extract-units -The @kbd{u r} (@code{calc-remove-units}) command removes units from the -formula at the top of the stack. The @kbd{u x} -(@code{calc-extract-units}) command extracts only the units portion of a -formula. These commands essentially replace every term of the formula -that does or doesn't (respectively) look like a unit name by the -constant 1, then resimplify the formula. - -@kindex u a -@pindex calc-autorange-units -The @kbd{u a} (@code{calc-autorange-units}) command turns on and off a -mode in which unit prefixes like @code{k} (``kilo'') are automatically -applied to keep the numeric part of a units expression in a reasonable -range. This mode affects @kbd{u s} and all units conversion commands -except @kbd{u b}. For example, with autoranging on, @samp{12345 Hz} -will be simplified to @samp{12.345 kHz}. Autoranging is useful for -some kinds of units (like @code{Hz} and @code{m}), but is probably -undesirable for non-metric units like @code{ft} and @code{tbsp}. -(Composite units are more appropriate for those; see above.) - -Autoranging always applies the prefix to the leftmost unit name. -Calc chooses the largest prefix that causes the number to be greater -than or equal to 1.0. Thus an increasing sequence of adjusted times -would be @samp{1 ms, 10 ms, 100 ms, 1 s, 10 s, 100 s, 1 ks}. -Generally the rule of thumb is that the number will be adjusted -to be in the interval @samp{[1 .. 1000)}, although there are several -exceptions to this rule. First, if the unit has a power then this -is not possible; @samp{0.1 s^2} simplifies to @samp{100000 ms^2}. -Second, the ``centi-'' prefix is allowed to form @code{cm} (centimeters), -but will not apply to other units. The ``deci-,'' ``deka-,'' and -``hecto-'' prefixes are never used. Thus the allowable interval is -@samp{[1 .. 10)} for millimeters and @samp{[1 .. 100)} for centimeters. -Finally, a prefix will not be added to a unit if the resulting name -is also the actual name of another unit; @samp{1e-15 t} would normally -be considered a ``femto-ton,'' but it is written as @samp{1000 at} -(1000 atto-tons) instead because @code{ft} would be confused with feet. - -@node The Units Table, Predefined Units, Basic Operations on Units, Units -@section The Units Table - -@noindent -@kindex u v -@pindex calc-enter-units-table -The @kbd{u v} (@code{calc-enter-units-table}) command displays the units table -in another buffer called @code{*Units Table*}. Each entry in this table -gives the unit name as it would appear in an expression, the definition -of the unit in terms of simpler units, and a full name or description of -the unit. Fundamental units are defined as themselves; these are the -units produced by the @kbd{u b} command. The fundamental units are -meters, seconds, grams, kelvins, amperes, candelas, moles, radians, -and steradians. - -The Units Table buffer also displays the Unit Prefix Table. Note that -two prefixes, ``kilo'' and ``hecto,'' accept either upper- or lower-case -prefix letters. @samp{Meg} is also accepted as a synonym for the @samp{M} -prefix. Whenever a unit name can be interpreted as either a built-in name -or a prefix followed by another built-in name, the former interpretation -wins. For example, @samp{2 pt} means two pints, not two pico-tons. - -The Units Table buffer, once created, is not rebuilt unless you define -new units. To force the buffer to be rebuilt, give any numeric prefix -argument to @kbd{u v}. - -@kindex u V -@pindex calc-view-units-table -The @kbd{u V} (@code{calc-view-units-table}) command is like @kbd{u v} except -that the cursor is not moved into the Units Table buffer. You can -type @kbd{u V} again to remove the Units Table from the display. To -return from the Units Table buffer after a @kbd{u v}, type @kbd{C-x * c} -again or use the regular Emacs @w{@kbd{C-x o}} (@code{other-window}) -command. You can also kill the buffer with @kbd{C-x k} if you wish; -the actual units table is safely stored inside the Calculator. - -@kindex u g -@pindex calc-get-unit-definition -The @kbd{u g} (@code{calc-get-unit-definition}) command retrieves a unit's -defining expression and pushes it onto the Calculator stack. For example, -@kbd{u g in} will produce the expression @samp{2.54 cm}. This is the -same definition for the unit that would appear in the Units Table buffer. -Note that this command works only for actual unit names; @kbd{u g km} -will report that no such unit exists, for example, because @code{km} is -really the unit @code{m} with a @code{k} (``kilo'') prefix. To see a -definition of a unit in terms of base units, it is easier to push the -unit name on the stack and then reduce it to base units with @kbd{u b}. - -@kindex u e -@pindex calc-explain-units -The @kbd{u e} (@code{calc-explain-units}) command displays an English -description of the units of the expression on the stack. For example, -for the expression @samp{62 km^2 g / s^2 mol K}, the description is -``Square-Kilometer Gram per (Second-squared Mole Degree-Kelvin).'' This -command uses the English descriptions that appear in the righthand -column of the Units Table. - -@node Predefined Units, User-Defined Units, The Units Table, Units -@section Predefined Units - -@noindent -The definitions of many units have changed over the years. For example, -the meter was originally defined in 1791 as one ten-millionth of the -distance from the equator to the north pole. In order to be more -precise, the definition was adjusted several times, and now a meter is -defined as the distance that light will travel in a vacuum in -1/299792458 of a second; consequently, the speed of light in a -vacuum is exactly 299792458 m/s. Many other units have been -redefined in terms of fundamental physical processes; a second, for -example, is currently defined as 9192631770 periods of a certain -radiation related to the cesium-133 atom. The only SI unit that is not -based on a fundamental physical process (although there are efforts to -change this) is the kilogram, which was originally defined as the mass -of one liter of water, but is now defined as the mass of the -International Prototype Kilogram (IPK), a cylinder of platinum-iridium -kept at the Bureau International des Poids et Mesures in S@`evres, -France. (There are several copies of the IPK throughout the world.) -The British imperial units, once defined in terms of physical objects, -were redefined in 1963 in terms of SI units. The US customary units, -which were the same as British units until the British imperial system -was created in 1824, were also defined in terms of the SI units in 1893. -Because of these redefinitions, conversions between metric, British -Imperial, and US customary units can often be done precisely. - -Since the exact definitions of many kinds of units have evolved over the -years, and since certain countries sometimes have local differences in -their definitions, it is a good idea to examine Calc's definition of a -unit before depending on its exact value. For example, there are three -different units for gallons, corresponding to the US (@code{gal}), -Canadian (@code{galC}), and British (@code{galUK}) definitions. Also, -note that @code{oz} is a standard ounce of mass, @code{ozt} is a Troy -ounce, and @code{ozfl} is a fluid ounce. - -The temperature units corresponding to degrees Kelvin and Centigrade -(Celsius) are the same in this table, since most units commands treat -temperatures as being relative. The @code{calc-convert-temperature} -command has special rules for handling the different absolute magnitudes -of the various temperature scales. - -The unit of volume ``liters'' can be referred to by either the lower-case -@code{l} or the upper-case @code{L}. - -The unit @code{A} stands for Amperes; the name @code{Ang} is used -@tex -for \AA ngstroms. -@end tex -@ifnottex -for Angstroms. -@end ifnottex - -The unit @code{pt} stands for pints; the name @code{point} stands for -a typographical point, defined by @samp{72 point = 1 in}. This is -slightly different than the point defined by the American Typefounder's -Association in 1886, but the point used by Calc has become standard -largely due to its use by the PostScript page description language. -There is also @code{texpt}, which stands for a printer's point as -defined by the @TeX{} typesetting system: @samp{72.27 texpt = 1 in}. -Other units used by @TeX{} are available; they are @code{texpc} (a pica), -@code{texbp} (a ``big point'', equal to a standard point which is larger -than the point used by @TeX{}), @code{texdd} (a Didot point), -@code{texcc} (a Cicero) and @code{texsp} (a scaled @TeX{} point, -all dimensions representable in @TeX{} are multiples of this value). - -When Calc is using the @TeX{} or La@TeX{} language mode (@pxref{TeX -and LaTeX Language Modes}), the @TeX{} specific unit names will not -use the @samp{tex} prefix; the unit name for a @TeX{} point will be -@samp{pt} instead of @samp{texpt}, for example. To avoid conflicts, -the unit names for pint and parsec will simply be @samp{pint} and -@samp{parsec} instead of @samp{pt} and @samp{pc}. - - -The unit @code{e} stands for the elementary (electron) unit of charge; -because algebra command could mistake this for the special constant -@expr{e}, Calc provides the alternate unit name @code{ech} which is -preferable to @code{e}. - -The name @code{g} stands for one gram of mass; there is also @code{gf}, -one gram of force. (Likewise for @kbd{lb}, pounds, and @kbd{lbf}.) -Meanwhile, one ``@expr{g}'' of acceleration is denoted @code{ga}. - -The unit @code{ton} is a U.S. ton of @samp{2000 lb}, and @code{t} is -a metric ton of @samp{1000 kg}. - -The names @code{s} (or @code{sec}) and @code{min} refer to units of -time; @code{arcsec} and @code{arcmin} are units of angle. - -Some ``units'' are really physical constants; for example, @code{c} -represents the speed of light, and @code{h} represents Planck's -constant. You can use these just like other units: converting -@samp{.5 c} to @samp{m/s} expresses one-half the speed of light in -meters per second. You can also use this merely as a handy reference; -the @kbd{u g} command gets the definition of one of these constants -in its normal terms, and @kbd{u b} expresses the definition in base -units. - -Two units, @code{pi} and @code{alpha} (the fine structure constant, -approximately @mathit{1/137}) are dimensionless. The units simplification -commands simply treat these names as equivalent to their corresponding -values. However you can, for example, use @kbd{u c} to convert a pure -number into multiples of the fine structure constant, or @kbd{u b} to -convert this back into a pure number. (When @kbd{u c} prompts for the -``old units,'' just enter a blank line to signify that the value -really is unitless.) - -@c Describe angular units, luminosity vs. steradians problem. - -@node User-Defined Units, Logarithmic Units, Predefined Units, Units -@section User-Defined Units - -@noindent -Calc provides ways to get quick access to your selected ``favorite'' -units, as well as ways to define your own new units. - -@kindex u 0-9 -@pindex calc-quick-units -@vindex Units -@cindex @code{Units} variable -@cindex Quick units -To select your favorite units, store a vector of unit names or -expressions in the Calc variable @code{Units}. The @kbd{u 1} -through @kbd{u 9} commands (@code{calc-quick-units}) provide access -to these units. If the value on the top of the stack is a plain -number (with no units attached), then @kbd{u 1} gives it the -specified units. (Basically, it multiplies the number by the -first item in the @code{Units} vector.) If the number on the -stack @emph{does} have units, then @kbd{u 1} converts that number -to the new units. For example, suppose the vector @samp{[in, ft]} -is stored in @code{Units}. Then @kbd{30 u 1} will create the -expression @samp{30 in}, and @kbd{u 2} will convert that expression -to @samp{2.5 ft}. - -The @kbd{u 0} command accesses the tenth element of @code{Units}. -Only ten quick units may be defined at a time. If the @code{Units} -variable has no stored value (the default), or if its value is not -a vector, then the quick-units commands will not function. The -@kbd{s U} command is a convenient way to edit the @code{Units} -variable; @pxref{Operations on Variables}. - -@kindex u d -@pindex calc-define-unit -@cindex User-defined units -The @kbd{u d} (@code{calc-define-unit}) command records the units -expression on the top of the stack as the definition for a new, -user-defined unit. For example, putting @samp{16.5 ft} on the stack and -typing @kbd{u d rod} defines the new unit @samp{rod} to be equivalent to -16.5 feet. The unit conversion and simplification commands will now -treat @code{rod} just like any other unit of length. You will also be -prompted for an optional English description of the unit, which will -appear in the Units Table. If you wish the definition of this unit to -be displayed in a special way in the Units Table buffer (such as with an -asterisk to indicate an approximate value), then you can call this -command with an argument, @kbd{C-u u d}; you will then also be prompted -for a string that will be used to display the definition. - -@kindex u u -@pindex calc-undefine-unit -The @kbd{u u} (@code{calc-undefine-unit}) command removes a user-defined -unit. It is not possible to remove one of the predefined units, -however. - -If you define a unit with an existing unit name, your new definition -will replace the original definition of that unit. If the unit was a -predefined unit, the old definition will not be replaced, only -``shadowed.'' The built-in definition will reappear if you later use -@kbd{u u} to remove the shadowing definition. - -To create a new fundamental unit, use either 1 or the unit name itself -as the defining expression. Otherwise the expression can involve any -other units that you like (except for composite units like @samp{mfi}). -You can create a new composite unit with a sum of other units as the -defining expression. The next unit operation like @kbd{u c} or @kbd{u v} -will rebuild the internal unit table incorporating your modifications. -Note that erroneous definitions (such as two units defined in terms of -each other) will not be detected until the unit table is next rebuilt; -@kbd{u v} is a convenient way to force this to happen. - -Temperature units are treated specially inside the Calculator; it is not -possible to create user-defined temperature units. - -@kindex u p -@pindex calc-permanent-units -@cindex Calc init file, user-defined units -The @kbd{u p} (@code{calc-permanent-units}) command stores the user-defined -units in your Calc init file (the file given by the variable -@code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}), so that the -units will still be available in subsequent Emacs sessions. If there -was already a set of user-defined units in your Calc init file, it -is replaced by the new set. (@xref{General Mode Commands}, for a way to -tell Calc to use a different file for the Calc init file.) - -@node Logarithmic Units, Musical Notes, User-Defined Units, Units -@section Logarithmic Units - -The units @code{dB} (decibels) and @code{Np} (nepers) are logarithmic -units which are manipulated differently than standard units. Calc -provides commands to work with these logarithmic units. - -Decibels and nepers are used to measure power quantities as well as -field quantities (quantities whose squares are proportional to power); -these two types of quantities are handled slightly different from each -other. By default the Calc commands work as if power quantities are -being used; with the @kbd{H} prefix the Calc commands work as if field -quantities are being used. - -The decibel level of a power -@infoline @math{P1}, -@texline @math{P_1}, -relative to a reference power -@infoline @math{P0}, -@texline @math{P_0}, -is defined to be -@infoline @math{10 log10(P1/P0) dB}. -@texline @math{10 \log_{10}(P_{1}/P_{0}) {\rm dB}}. -(The factor of 10 is because a decibel, as its name implies, is -one-tenth of a bel. The bel, named after Alexander Graham Bell, was -considered to be too large of a unit and was effectively replaced by -the decibel.) If @math{F} is a field quantity with power -@math{P=k F^2}, then a reference quantity of -@infoline @math{F0} -@texline @math{F_0} -would correspond to a power of -@infoline @math{P0=k F0^2}. -@texline @math{P_{0}=kF_{0}^2}. -If -@infoline @math{P1=k F1^2}, -@texline @math{P_{1}=kF_{1}^2}, -then - -@ifnottex -@example -10 log10(P1/P0) = 10 log10(F1^2/F0^2) = 20 log10(F1/F0). -@end example -@end ifnottex -@tex -$$ 10 \log_{10}(P_1/P_0) = 10 \log_{10}(F_1^2/F_0^2) = 20 -\log_{10}(F_1/F_0)$$ -@end tex - -@noindent -In order to get the same decibel level regardless of whether a field -quantity or the corresponding power quantity is used, the decibel -level of a field quantity -@infoline @math{F1}, -@texline @math{F_1}, -relative to a reference -@infoline @math{F0}, -@texline @math{F_0}, -is defined as -@infoline @math{20 log10(F1/F0) dB}. -@texline @math{20 \log_{10}(F_{1}/F_{0}) {\rm dB}}. -For example, the decibel value of a sound pressure level of -@infoline @math{60 uPa} -@texline @math{60 \mu{\rm Pa}} -relative to -@infoline @math{20 uPa} -@texline @math{20 \mu{\rm Pa}} -(the threshold of human hearing) is -@infoline @math{20 log10(60 uPa/ 20 uPa) dB = 20 log10(3) dB}, -@texline @math{20 \log_{10}(60 \mu{\rm Pa}/20 \mu{\rm Pa}) {\rm dB} = 20 \log_{10}(3) {\rm dB}}, -which is about -@infoline @math{9.54 dB}. -@texline @math{9.54 {\rm dB}}. -Note that in taking the ratio, the original units cancel and so these -logarithmic units are dimensionless. - -Nepers (named after John Napier, who is credited with inventing the -logarithm) are similar to bels except they use natural logarithms instead -of common logarithms. The neper level of a power -@infoline @math{P1}, -@texline @math{P_1}, -relative to a reference power -@infoline @math{P0}, -@texline @math{P_0}, -is -@infoline @math{(1/2) ln(P1/P0) Np}. -@texline @math{(1/2) \ln(P_1/P_0) {\rm Np}}. -The neper level of a field -@infoline @math{F1}, -@texline @math{F_1}, -relative to a reference field -@infoline @math{F0}, -@texline @math{F_0}, -is -@infoline @math{ln(F1/F0) Np}. -@texline @math{\ln(F_1/F_0) {\rm Np}}. - -@vindex calc-lu-power-reference -@vindex calc-lu-field-reference -For power quantities, Calc uses -@infoline @math{1 mW} -@texline @math{1 {\rm mW}} -as the default reference quantity; this default can be changed by changing -the value of the customizable variable -@code{calc-lu-power-reference} (@pxref{Customizing Calc}). -For field quantities, Calc uses -@infoline @math{20 uPa} -@texline @math{20 \mu{\rm Pa}} -as the default reference quantity; this is the value used in acoustics -which is where decibels are commonly encountered. This default can be -changed by changing the value of the customizable variable -@code{calc-lu-field-reference} (@pxref{Customizing Calc}). A -non-default reference quantity will be read from the stack if the -capital @kbd{O} prefix is used. - -@kindex l q -@pindex calc-lu-quant -@tindex lupquant -@tindex lufquant -The @kbd{l q} (@code{calc-lu-quant}) [@code{lupquant}] -command computes the power quantity corresponding to a given number of -logarithmic units. With the capital @kbd{O} prefix, @kbd{O l q}, the -reference level will be read from the top of the stack. (In an -algebraic formula, @code{lupquant} can be given an optional second -argument which will be used for the reference level.) For example, -@code{20 dB @key{RET} l q} will return @code{100 mW}; -@code{20 dB @key{RET} 4 W @key{RET} O l q} will return @code{400 W}. -The @kbd{H l q} [@code{lufquant}] command behaves like @kbd{l q} but -computes field quantities instead of power quantities. - -@kindex l d -@pindex calc-db -@tindex dbpower -@tindex dbfield -@kindex l n -@pindex calc-np -@tindex nppower -@tindex npfield -The @kbd{l d} (@code{calc-db}) [@code{dbpower}] command will compute -the decibel level of a power quantity using the default reference -level; @kbd{H l d} [@code{dbfield}] will compute the decibel level of -a field quantity. The commands @kbd{l n} (@code{calc-np}) -[@code{nppower}] and @kbd{H l n} [@code{npfield}] will similarly -compute neper levels. With the capital @kbd{O} prefix these commands -will read a reference level from the stack; in an algebraic formula -the reference level can be given as an optional second argument. - -@kindex l + -@pindex calc-lu-plus -@tindex lupadd -@tindex lufadd -@kindex l - -@pindex calc-lu-minus -@tindex lupsub -@tindex lufsub -@kindex l * -@pindex calc-lu-times -@tindex lupmul -@tindex lufmul -@kindex l / -@pindex calc-lu-divide -@tindex lupdiv -@tindex lufdiv -The sum of two power or field quantities doesn't correspond to the sum -of the corresponding decibel or neper levels. If the powers -corresponding to decibel levels -@infoline @math{D1} -@texline @math{D_1} -and -@infoline @math{D2} -@texline @math{D_2} -are added, the corresponding decibel level ``sum'' will be - -@ifnottex -@example - 10 log10(10^(D1/10) + 10^(D2/10)) dB. -@end example -@end ifnottex -@tex -$$ 10 \log_{10}(10^{D_1/10} + 10^{D_2/10}) {\rm dB}.$$ -@end tex - -@noindent -When field quantities are combined, it often means the corresponding -powers are added and so the above formula might be used. In -acoustics, for example, the sound pressure level is a field quantity -and so the decibels are often defined using the field formula, but the -sound pressure levels are combined as the sound power levels, and so -the above formula should be used. If two field quantities themselves -are added, the new decibel level will be - -@ifnottex -@example - 20 log10(10^(D1/20) + 10^(D2/20)) dB. -@end example -@end ifnottex -@tex -$$ 20 \log_{10}(10^{D_1/20} + 10^{D_2/20}) {\rm dB}.$$ -@end tex - -@noindent -If the power corresponding to @math{D} dB is multiplied by a number @math{N}, -then the corresponding decibel level will be - -@ifnottex -@example - D + 10 log10(N) dB, -@end example -@end ifnottex -@tex -$$ D + 10 \log_{10}(N) {\rm dB},$$ -@end tex - -@noindent -if a field quantity is multiplied by @math{N} the corresponding decibel level -will be - -@ifnottex -@example - D + 20 log10(N) dB. -@end example -@end ifnottex -@tex -$$ D + 20 \log_{10}(N) {\rm dB}.$$ -@end tex - -@noindent -There are similar formulas for combining nepers. The @kbd{l +} -(@code{calc-lu-plus}) [@code{lupadd}] command will ``add'' two -logarithmic unit power levels this way; with the @kbd{H} prefix, -@kbd{H l +} [@code{lufadd}] will add logarithmic unit field levels. -Similarly, logarithmic units can be ``subtracted'' with @kbd{l -} -(@code{calc-lu-minus}) [@code{lupsub}] or @kbd{H l -} [@code{lufsub}]. -The @kbd{l *} (@code{calc-lu-times}) [@code{lupmul}] and @kbd{H l *} -[@code{lufmul}] commands will ``multiply'' a logarithmic unit by a -number; the @kbd{l /} (@code{calc-lu-divide}) [@code{lupdiv}] and -@kbd{H l /} [@code{lufdiv}] commands will ``divide'' a logarithmic -unit by a number. Note that the reference quantities don't play a role -in this arithmetic. - -@node Musical Notes, , Logarithmic Units, Units -@section Musical Notes - -Calc can convert between musical notes and their associated -frequencies. Notes can be given using either scientific pitch -notation or midi numbers. Since these note systems are basically -logarithmic scales, Calc uses the @kbd{l} prefix for functions -operating on notes. - -Scientific pitch notation refers to a note by giving a letter -A through G, possibly followed by a flat or sharp) with a subscript -indicating an octave number. Each octave starts with C and ends with -B and -@c increasing each note by a semitone will result -@c in the sequence @expr{C}, @expr{C} sharp, @expr{D}, @expr{E} flat, @expr{E}, -@c @expr{F}, @expr{F} sharp, @expr{G}, @expr{A} flat, @expr{A}, @expr{B} -@c flat and @expr{B}. -the octave numbered 0 was chosen to correspond to the lowest -audible frequency. Using this system, middle C (about 261.625 Hz) -corresponds to the note @expr{C} in octave 4 and is denoted -@expr{C_4}. Any frequency can be described by giving a note plus an -offset in cents (where a cent is a ratio of frequencies so that a -semitone consists of 100 cents). - -The midi note number system assigns numbers to notes so that -@expr{C_(-1)} corresponds to the midi note number 0 and @expr{G_9} -corresponds to the midi note number 127. A midi controller can have -up to 128 keys and each midi note number from 0 to 127 corresponds to -a possible key. - -@kindex l s -@pindex calc-spn -@tindex spn -The @kbd{l s} (@code{calc-spn}) [@code{spn}] command converts either -a frequency or a midi number to scientific pitch notation. For -example, @code{500 Hz} gets converted to -@code{B_4 + 21.3094853649 cents} and @code{84} to @code{C_6}. - - -@kindex l m -@pindex calc-midi -@tindex midi -The @kbd{l m} (@code{calc-midi}) [@code{midi}] command converts either -a frequency or a note given in scientific pitch notation to the -corresponding midi number. For example, @code{C_6} gets converted to 84 -and @code{440 Hz} to 69. - -@kindex l f -@pindex calc-freq -@tindex freq -The @kbd{l f} (@code{calc-freq}) [@code{freq}] command converts either -either a midi number or a note given in scientific pitch notation to -the corresponding frequency. For example, @code{Asharp_2 + 30 cents} -gets converted to @code{118.578040134 Hz} and @code{55} to -@code{195.99771799 Hz}. - -Since the frequencies of notes are not usually given exactly (and are -typically irrational), the customizable variable -@code{calc-note-threshold} determines how close (in cents) a frequency -needs to be to a note to be recognized as that note -(@pxref{Customizing Calc}). This variable has a default value of -@code{1}. For example, middle @var{C} is approximately -@expr{261.625565302 Hz}; this frequency is often shortened to -@expr{261.625 Hz}. Without @code{calc-note-threshold} (or a value of -@expr{0}), Calc would convert @code{261.625 Hz} to scientific pitch -notation @code{B_3 + 99.9962592773 cents}; with the default value of -@code{1}, Calc converts @code{261.625 Hz} to @code{C_4}. - - - -@node Store and Recall, Graphics, Units, Top -@chapter Storing and Recalling - -@noindent -Calculator variables are really just Lisp variables that contain numbers -or formulas in a form that Calc can understand. The commands in this -section allow you to manipulate variables conveniently. Commands related -to variables use the @kbd{s} prefix key. - -@menu -* Storing Variables:: -* Recalling Variables:: -* Operations on Variables:: -* Let Command:: -* Evaluates-To Operator:: -@end menu - -@node Storing Variables, Recalling Variables, Store and Recall, Store and Recall -@section Storing Variables - -@noindent -@kindex s s -@pindex calc-store -@cindex Storing variables -@cindex Quick variables -@vindex q0 -@vindex q9 -The @kbd{s s} (@code{calc-store}) command stores the value at the top of -the stack into a specified variable. It prompts you to enter the -name of the variable. If you press a single digit, the value is stored -immediately in one of the ``quick'' variables @code{q0} through -@code{q9}. Or you can enter any variable name. - -@kindex s t -@pindex calc-store-into -The @kbd{s s} command leaves the stored value on the stack. There is -also an @kbd{s t} (@code{calc-store-into}) command, which removes a -value from the stack and stores it in a variable. - -If the top of stack value is an equation @samp{a = 7} or assignment -@samp{a := 7} with a variable on the lefthand side, then Calc will -assign that variable with that value by default, i.e., if you type -@kbd{s s @key{RET}} or @kbd{s t @key{RET}}. In this example, the -value 7 would be stored in the variable @samp{a}. (If you do type -a variable name at the prompt, the top-of-stack value is stored in -its entirety, even if it is an equation: @samp{s s b @key{RET}} -with @samp{a := 7} on the stack stores @samp{a := 7} in @code{b}.) - -In fact, the top of stack value can be a vector of equations or -assignments with different variables on their lefthand sides; the -default will be to store all the variables with their corresponding -righthand sides simultaneously. - -It is also possible to type an equation or assignment directly at -the prompt for the @kbd{s s} or @kbd{s t} command: @kbd{s s foo = 7}. -In this case the expression to the right of the @kbd{=} or @kbd{:=} -symbol is evaluated as if by the @kbd{=} command, and that value is -stored in the variable. No value is taken from the stack; @kbd{s s} -and @kbd{s t} are equivalent when used in this way. - -@kindex s 0-9 -@kindex t 0-9 -The prefix keys @kbd{s} and @kbd{t} may be followed immediately by a -digit; @kbd{s 9} is equivalent to @kbd{s s 9}, and @kbd{t 9} is -equivalent to @kbd{s t 9}. (The @kbd{t} prefix is otherwise used -for trail and time/date commands.) - -@kindex s + -@kindex s - -@ignore -@mindex @idots -@end ignore -@kindex s * -@ignore -@mindex @null -@end ignore -@kindex s / -@ignore -@mindex @null -@end ignore -@kindex s ^ -@ignore -@mindex @null -@end ignore -@kindex s | -@ignore -@mindex @null -@end ignore -@kindex s n -@ignore -@mindex @null -@end ignore -@kindex s & -@ignore -@mindex @null -@end ignore -@kindex s [ -@ignore -@mindex @null -@end ignore -@kindex s ] -@pindex calc-store-plus -@pindex calc-store-minus -@pindex calc-store-times -@pindex calc-store-div -@pindex calc-store-power -@pindex calc-store-concat -@pindex calc-store-neg -@pindex calc-store-inv -@pindex calc-store-decr -@pindex calc-store-incr -There are also several ``arithmetic store'' commands. For example, -@kbd{s +} removes a value from the stack and adds it to the specified -variable. The other arithmetic stores are @kbd{s -}, @kbd{s *}, @kbd{s /}, -@kbd{s ^}, and @w{@kbd{s |}} (vector concatenation), plus @kbd{s n} and -@kbd{s &} which negate or invert the value in a variable, and @w{@kbd{s [}} -and @kbd{s ]} which decrease or increase a variable by one. - -All the arithmetic stores accept the Inverse prefix to reverse the -order of the operands. If @expr{v} represents the contents of the -variable, and @expr{a} is the value drawn from the stack, then regular -@w{@kbd{s -}} assigns -@texline @math{v \coloneq v - a}, -@infoline @expr{v := v - a}, -but @kbd{I s -} assigns -@texline @math{v \coloneq a - v}. -@infoline @expr{v := a - v}. -While @kbd{I s *} might seem pointless, it is -useful if matrix multiplication is involved. Actually, all the -arithmetic stores use formulas designed to behave usefully both -forwards and backwards: - -@example -@group -s + v := v + a v := a + v -s - v := v - a v := a - v -s * v := v * a v := a * v -s / v := v / a v := a / v -s ^ v := v ^ a v := a ^ v -s | v := v | a v := a | v -s n v := v / (-1) v := (-1) / v -s & v := v ^ (-1) v := (-1) ^ v -s [ v := v - 1 v := 1 - v -s ] v := v - (-1) v := (-1) - v -@end group -@end example - -In the last four cases, a numeric prefix argument will be used in -place of the number one. (For example, @kbd{M-2 s ]} increases -a variable by 2, and @kbd{M-2 I s ]} replaces a variable by -minus-two minus the variable. - -The first six arithmetic stores can also be typed @kbd{s t +}, @kbd{s t -}, -etc. The commands @kbd{s s +}, @kbd{s s -}, and so on are analogous -arithmetic stores that don't remove the value @expr{a} from the stack. - -All arithmetic stores report the new value of the variable in the -Trail for your information. They signal an error if the variable -previously had no stored value. If default simplifications have been -turned off, the arithmetic stores temporarily turn them on for numeric -arguments only (i.e., they temporarily do an @kbd{m N} command). -@xref{Simplification Modes}. Large vectors put in the trail by -these commands always use abbreviated (@kbd{t .}) mode. - -@kindex s m -@pindex calc-store-map -The @kbd{s m} command is a general way to adjust a variable's value -using any Calc function. It is a ``mapping'' command analogous to -@kbd{V M}, @kbd{V R}, etc. @xref{Reducing and Mapping}, to see -how to specify a function for a mapping command. Basically, -all you do is type the Calc command key that would invoke that -function normally. For example, @kbd{s m n} applies the @kbd{n} -key to negate the contents of the variable, so @kbd{s m n} is -equivalent to @kbd{s n}. Also, @kbd{s m Q} takes the square root -of the value stored in a variable, @kbd{s m v v} uses @kbd{v v} to -reverse the vector stored in the variable, and @kbd{s m H I S} -takes the hyperbolic arcsine of the variable contents. - -If the mapping function takes two or more arguments, the additional -arguments are taken from the stack; the old value of the variable -is provided as the first argument. Thus @kbd{s m -} with @expr{a} -on the stack computes @expr{v - a}, just like @kbd{s -}. With the -Inverse prefix, the variable's original value becomes the @emph{last} -argument instead of the first. Thus @kbd{I s m -} is also -equivalent to @kbd{I s -}. - -@kindex s x -@pindex calc-store-exchange -The @kbd{s x} (@code{calc-store-exchange}) command exchanges the value -of a variable with the value on the top of the stack. Naturally, the -variable must already have a stored value for this to work. - -You can type an equation or assignment at the @kbd{s x} prompt. The -command @kbd{s x a=6} takes no values from the stack; instead, it -pushes the old value of @samp{a} on the stack and stores @samp{a = 6}. - -@kindex s u -@pindex calc-unstore -@cindex Void variables -@cindex Un-storing variables -Until you store something in them, most variables are ``void,'' that is, -they contain no value at all. If they appear in an algebraic formula -they will be left alone even if you press @kbd{=} (@code{calc-evaluate}). -The @kbd{s u} (@code{calc-unstore}) command returns a variable to the -void state. - -@kindex s c -@pindex calc-copy-variable -The @kbd{s c} (@code{calc-copy-variable}) command copies the stored -value of one variable to another. One way it differs from a simple -@kbd{s r} followed by an @kbd{s t} (aside from saving keystrokes) is -that the value never goes on the stack and thus is never rounded, -evaluated, or simplified in any way; it is not even rounded down to the -current precision. - -The only variables with predefined values are the ``special constants'' -@code{pi}, @code{e}, @code{i}, @code{phi}, and @code{gamma}. You are free -to unstore these variables or to store new values into them if you like, -although some of the algebraic-manipulation functions may assume these -variables represent their standard values. Calc displays a warning if -you change the value of one of these variables, or of one of the other -special variables @code{inf}, @code{uinf}, and @code{nan} (which are -normally void). - -Note that @code{pi} doesn't actually have 3.14159265359 stored in it, -but rather a special magic value that evaluates to @cpi{} at the current -precision. Likewise @code{e}, @code{i}, and @code{phi} evaluate -according to the current precision or polar mode. If you recall a value -from @code{pi} and store it back, this magic property will be lost. The -magic property is preserved, however, when a variable is copied with -@kbd{s c}. - -@kindex s k -@pindex calc-copy-special-constant -If one of the ``special constants'' is redefined (or undefined) so that -it no longer has its magic property, the property can be restored with -@kbd{s k} (@code{calc-copy-special-constant}). This command will prompt -for a special constant and a variable to store it in, and so a special -constant can be stored in any variable. Here, the special constant that -you enter doesn't depend on the value of the corresponding variable; -@code{pi} will represent 3.14159@dots{} regardless of what is currently -stored in the Calc variable @code{pi}. If one of the other special -variables, @code{inf}, @code{uinf} or @code{nan}, is given a value, its -original behavior can be restored by voiding it with @kbd{s u}. - -@node Recalling Variables, Operations on Variables, Storing Variables, Store and Recall -@section Recalling Variables - -@noindent -@kindex s r -@pindex calc-recall -@cindex Recalling variables -The most straightforward way to extract the stored value from a variable -is to use the @kbd{s r} (@code{calc-recall}) command. This command prompts -for a variable name (similarly to @code{calc-store}), looks up the value -of the specified variable, and pushes that value onto the stack. It is -an error to try to recall a void variable. - -It is also possible to recall the value from a variable by evaluating a -formula containing that variable. For example, @kbd{' a @key{RET} =} is -the same as @kbd{s r a @key{RET}} except that if the variable is void, the -former will simply leave the formula @samp{a} on the stack whereas the -latter will produce an error message. - -@kindex r 0-9 -The @kbd{r} prefix may be followed by a digit, so that @kbd{r 9} is -equivalent to @kbd{s r 9}. - -@node Operations on Variables, Let Command, Recalling Variables, Store and Recall -@section Other Operations on Variables - -@noindent -@kindex s e -@pindex calc-edit-variable -The @kbd{s e} (@code{calc-edit-variable}) command edits the stored -value of a variable without ever putting that value on the stack -or simplifying or evaluating the value. It prompts for the name of -the variable to edit. If the variable has no stored value, the -editing buffer will start out empty. If the editing buffer is -empty when you press @kbd{C-c C-c} to finish, the variable will -be made void. @xref{Editing Stack Entries}, for a general -description of editing. - -The @kbd{s e} command is especially useful for creating and editing -rewrite rules which are stored in variables. Sometimes these rules -contain formulas which must not be evaluated until the rules are -actually used. (For example, they may refer to @samp{deriv(x,y)}, -where @code{x} will someday become some expression involving @code{y}; -if you let Calc evaluate the rule while you are defining it, Calc will -replace @samp{deriv(x,y)} with 0 because the formula @code{x} does -not itself refer to @code{y}.) By contrast, recalling the variable, -editing with @kbd{`}, and storing will evaluate the variable's value -as a side effect of putting the value on the stack. - -@kindex s A -@kindex s D -@ignore -@mindex @idots -@end ignore -@kindex s E -@ignore -@mindex @null -@end ignore -@kindex s F -@ignore -@mindex @null -@end ignore -@kindex s G -@ignore -@mindex @null -@end ignore -@kindex s H -@ignore -@mindex @null -@end ignore -@kindex s I -@ignore -@mindex @null -@end ignore -@kindex s L -@ignore -@mindex @null -@end ignore -@kindex s P -@ignore -@mindex @null -@end ignore -@kindex s R -@ignore -@mindex @null -@end ignore -@kindex s T -@ignore -@mindex @null -@end ignore -@kindex s U -@ignore -@mindex @null -@end ignore -@kindex s X -@pindex calc-store-AlgSimpRules -@pindex calc-store-Decls -@pindex calc-store-EvalRules -@pindex calc-store-FitRules -@pindex calc-store-GenCount -@pindex calc-store-Holidays -@pindex calc-store-IntegLimit -@pindex calc-store-LineStyles -@pindex calc-store-PointStyles -@pindex calc-store-PlotRejects -@pindex calc-store-TimeZone -@pindex calc-store-Units -@pindex calc-store-ExtSimpRules -There are several special-purpose variable-editing commands that -use the @kbd{s} prefix followed by a shifted letter: - -@table @kbd -@item s A -Edit @code{AlgSimpRules}. @xref{Algebraic Simplifications}. -@item s D -Edit @code{Decls}. @xref{Declarations}. -@item s E -Edit @code{EvalRules}. @xref{Default Simplifications}. -@item s F -Edit @code{FitRules}. @xref{Curve Fitting}. -@item s G -Edit @code{GenCount}. @xref{Solving Equations}. -@item s H -Edit @code{Holidays}. @xref{Business Days}. -@item s I -Edit @code{IntegLimit}. @xref{Calculus}. -@item s L -Edit @code{LineStyles}. @xref{Graphics}. -@item s P -Edit @code{PointStyles}. @xref{Graphics}. -@item s R -Edit @code{PlotRejects}. @xref{Graphics}. -@item s T -Edit @code{TimeZone}. @xref{Time Zones}. -@item s U -Edit @code{Units}. @xref{User-Defined Units}. -@item s X -Edit @code{ExtSimpRules}. @xref{Unsafe Simplifications}. -@end table - -These commands are just versions of @kbd{s e} that use fixed variable -names rather than prompting for the variable name. - -@kindex s p -@pindex calc-permanent-variable -@cindex Storing variables -@cindex Permanent variables -@cindex Calc init file, variables -The @kbd{s p} (@code{calc-permanent-variable}) command saves a -variable's value permanently in your Calc init file (the file given by -the variable @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}), so -that its value will still be available in future Emacs sessions. You -can re-execute @w{@kbd{s p}} later on to update the saved value, but the -only way to remove a saved variable is to edit your calc init file -by hand. (@xref{General Mode Commands}, for a way to tell Calc to -use a different file for the Calc init file.) - -If you do not specify the name of a variable to save (i.e., -@kbd{s p @key{RET}}), all Calc variables with defined values -are saved except for the special constants @code{pi}, @code{e}, -@code{i}, @code{phi}, and @code{gamma}; the variables @code{TimeZone} -and @code{PlotRejects}; -@code{FitRules}, @code{DistribRules}, and other built-in rewrite -rules; and @code{PlotData@var{n}} variables generated -by the graphics commands. (You can still save these variables by -explicitly naming them in an @kbd{s p} command.) - -@kindex s i -@pindex calc-insert-variables -The @kbd{s i} (@code{calc-insert-variables}) command writes -the values of all Calc variables into a specified buffer. -The variables are written with the prefix @code{var-} in the form of -Lisp @code{setq} commands -which store the values in string form. You can place these commands -in your Calc init file (or @file{.emacs}) if you wish, though in this case it -would be easier to use @kbd{s p @key{RET}}. (Note that @kbd{s i} -omits the same set of variables as @w{@kbd{s p @key{RET}}}; the difference -is that @kbd{s i} will store the variables in any buffer, and it also -stores in a more human-readable format.) - -@node Let Command, Evaluates-To Operator, Operations on Variables, Store and Recall -@section The Let Command - -@noindent -@kindex s l -@pindex calc-let -@cindex Variables, temporary assignment -@cindex Temporary assignment to variables -If you have an expression like @samp{a+b^2} on the stack and you wish to -compute its value where @expr{b=3}, you can simply store 3 in @expr{b} and -then press @kbd{=} to reevaluate the formula. This has the side-effect -of leaving the stored value of 3 in @expr{b} for future operations. - -The @kbd{s l} (@code{calc-let}) command evaluates a formula under a -@emph{temporary} assignment of a variable. It stores the value on the -top of the stack into the specified variable, then evaluates the -second-to-top stack entry, then restores the original value (or lack of one) -in the variable. Thus after @kbd{'@w{ }a+b^2 @key{RET} 3 s l b @key{RET}}, -the stack will contain the formula @samp{a + 9}. The subsequent command -@kbd{@w{5 s l a} @key{RET}} will replace this formula with the number 14. -The variables @samp{a} and @samp{b} are not permanently affected in any way -by these commands. - -The value on the top of the stack may be an equation or assignment, or -a vector of equations or assignments, in which case the default will be -analogous to the case of @kbd{s t @key{RET}}. @xref{Storing Variables}. - -Also, you can answer the variable-name prompt with an equation or -assignment: @kbd{s l b=3 @key{RET}} is the same as storing 3 on the stack -and typing @kbd{s l b @key{RET}}. - -The @kbd{a b} (@code{calc-substitute}) command is another way to substitute -a variable with a value in a formula. It does an actual substitution -rather than temporarily assigning the variable and evaluating. For -example, letting @expr{n=2} in @samp{f(n pi)} with @kbd{a b} will -produce @samp{f(2 pi)}, whereas @kbd{s l} would give @samp{f(6.28)} -since the evaluation step will also evaluate @code{pi}. - -@node Evaluates-To Operator, , Let Command, Store and Recall -@section The Evaluates-To Operator - -@noindent -@tindex evalto -@tindex => -@cindex Evaluates-to operator -@cindex @samp{=>} operator -The special algebraic symbol @samp{=>} is known as the @dfn{evaluates-to -operator}. (It will show up as an @code{evalto} function call in -other language modes like Pascal and La@TeX{}.) This is a binary -operator, that is, it has a lefthand and a righthand argument, -although it can be entered with the righthand argument omitted. - -A formula like @samp{@var{a} => @var{b}} is evaluated by Calc as -follows: First, @var{a} is not simplified or modified in any -way. The previous value of argument @var{b} is thrown away; the -formula @var{a} is then copied and evaluated as if by the @kbd{=} -command according to all current modes and stored variable values, -and the result is installed as the new value of @var{b}. - -For example, suppose you enter the algebraic formula @samp{2 + 3 => 17}. -The number 17 is ignored, and the lefthand argument is left in its -unevaluated form; the result is the formula @samp{2 + 3 => 5}. - -@kindex s = -@pindex calc-evalto -You can enter an @samp{=>} formula either directly using algebraic -entry (in which case the righthand side may be omitted since it is -going to be replaced right away anyhow), or by using the @kbd{s =} -(@code{calc-evalto}) command, which takes @var{a} from the stack -and replaces it with @samp{@var{a} => @var{b}}. - -Calc keeps track of all @samp{=>} operators on the stack, and -recomputes them whenever anything changes that might affect their -values, i.e., a mode setting or variable value. This occurs only -if the @samp{=>} operator is at the top level of the formula, or -if it is part of a top-level vector. In other words, pushing -@samp{2 + (a => 17)} will change the 17 to the actual value of -@samp{a} when you enter the formula, but the result will not be -dynamically updated when @samp{a} is changed later because the -@samp{=>} operator is buried inside a sum. However, a vector -of @samp{=>} operators will be recomputed, since it is convenient -to push a vector like @samp{[a =>, b =>, c =>]} on the stack to -make a concise display of all the variables in your problem. -(Another way to do this would be to use @samp{[a, b, c] =>}, -which provides a slightly different format of display. You -can use whichever you find easiest to read.) - -@kindex m C -@pindex calc-auto-recompute -The @kbd{m C} (@code{calc-auto-recompute}) command allows you to -turn this automatic recomputation on or off. If you turn -recomputation off, you must explicitly recompute an @samp{=>} -operator on the stack in one of the usual ways, such as by -pressing @kbd{=}. Turning recomputation off temporarily can save -a lot of time if you will be changing several modes or variables -before you look at the @samp{=>} entries again. - -Most commands are not especially useful with @samp{=>} operators -as arguments. For example, given @samp{x + 2 => 17}, it won't -work to type @kbd{1 +} to get @samp{x + 3 => 18}. If you want -to operate on the lefthand side of the @samp{=>} operator on -the top of the stack, type @kbd{j 1} (that's the digit ``one'') -to select the lefthand side, execute your commands, then type -@kbd{j u} to unselect. - -All current modes apply when an @samp{=>} operator is computed, -including the current simplification mode. Recall that the -formula @samp{x + y + x} is not handled by Calc's default -simplifications, but the @kbd{a s} command will reduce it to -the simpler form @samp{y + 2 x}. You can also type @kbd{m A} -to enable an Algebraic Simplification mode in which the -equivalent of @kbd{a s} is used on all of Calc's results. -If you enter @samp{x + y + x =>} normally, the result will -be @samp{x + y + x => x + y + x}. If you change to -Algebraic Simplification mode, the result will be -@samp{x + y + x => y + 2 x}. However, just pressing @kbd{a s} -once will have no effect on @samp{x + y + x => x + y + x}, -because the righthand side depends only on the lefthand side -and the current mode settings, and the lefthand side is not -affected by commands like @kbd{a s}. - -The ``let'' command (@kbd{s l}) has an interesting interaction -with the @samp{=>} operator. The @kbd{s l} command evaluates the -second-to-top stack entry with the top stack entry supplying -a temporary value for a given variable. As you might expect, -if that stack entry is an @samp{=>} operator its righthand -side will temporarily show this value for the variable. In -fact, all @samp{=>}s on the stack will be updated if they refer -to that variable. But this change is temporary in the sense -that the next command that causes Calc to look at those stack -entries will make them revert to the old variable value. - -@smallexample -@group -2: a => a 2: a => 17 2: a => a -1: a + 1 => a + 1 1: a + 1 => 18 1: a + 1 => a + 1 - . . . - - 17 s l a @key{RET} p 8 @key{RET} -@end group -@end smallexample - -Here the @kbd{p 8} command changes the current precision, -thus causing the @samp{=>} forms to be recomputed after the -influence of the ``let'' is gone. The @kbd{d @key{SPC}} command -(@code{calc-refresh}) is a handy way to force the @samp{=>} -operators on the stack to be recomputed without any other -side effects. - -@kindex s : -@pindex calc-assign -@tindex assign -@tindex := -Embedded mode also uses @samp{=>} operators. In Embedded mode, -the lefthand side of an @samp{=>} operator can refer to variables -assigned elsewhere in the file by @samp{:=} operators. The -assignment operator @samp{a := 17} does not actually do anything -by itself. But Embedded mode recognizes it and marks it as a sort -of file-local definition of the variable. You can enter @samp{:=} -operators in Algebraic mode, or by using the @kbd{s :} -(@code{calc-assign}) [@code{assign}] command which takes a variable -and value from the stack and replaces them with an assignment. - -@xref{TeX and LaTeX Language Modes}, for the way @samp{=>} appears in -@TeX{} language output. The @dfn{eqn} mode gives similar -treatment to @samp{=>}. - -@node Graphics, Kill and Yank, Store and Recall, Top -@chapter Graphics - -@noindent -The commands for graphing data begin with the @kbd{g} prefix key. Calc -uses GNUPLOT 2.0 or later to do graphics. These commands will only work -if GNUPLOT is available on your system. (While GNUPLOT sounds like -a relative of GNU Emacs, it is actually completely unrelated. -However, it is free software. It can be obtained from -@samp{http://www.gnuplot.info}.) - -@vindex calc-gnuplot-name -If you have GNUPLOT installed on your system but Calc is unable to -find it, you may need to set the @code{calc-gnuplot-name} variable in -your Calc init file or @file{.emacs}. You may also need to set some -Lisp variables to show Calc how to run GNUPLOT on your system; these -are described under @kbd{g D} and @kbd{g O} below. If you are using -the X window system or MS-Windows, Calc will configure GNUPLOT for you -automatically. If you have GNUPLOT 3.0 or later and you are using a -Unix or GNU system without X, Calc will configure GNUPLOT to display -graphs using simple character graphics that will work on any -Posix-compatible terminal. - -@menu -* Basic Graphics:: -* Three Dimensional Graphics:: -* Managing Curves:: -* Graphics Options:: -* Devices:: -@end menu - -@node Basic Graphics, Three Dimensional Graphics, Graphics, Graphics -@section Basic Graphics - -@noindent -@kindex g f -@pindex calc-graph-fast -The easiest graphics command is @kbd{g f} (@code{calc-graph-fast}). -This command takes two vectors of equal length from the stack. -The vector at the top of the stack represents the ``y'' values of -the various data points. The vector in the second-to-top position -represents the corresponding ``x'' values. This command runs -GNUPLOT (if it has not already been started by previous graphing -commands) and displays the set of data points. The points will -be connected by lines, and there will also be some kind of symbol -to indicate the points themselves. - -The ``x'' entry may instead be an interval form, in which case suitable -``x'' values are interpolated between the minimum and maximum values of -the interval (whether the interval is open or closed is ignored). - -The ``x'' entry may also be a number, in which case Calc uses the -sequence of ``x'' values @expr{x}, @expr{x+1}, @expr{x+2}, etc. -(Generally the number 0 or 1 would be used for @expr{x} in this case.) - -The ``y'' entry may be any formula instead of a vector. Calc effectively -uses @kbd{N} (@code{calc-eval-num}) to evaluate variables in the formula; -the result of this must be a formula in a single (unassigned) variable. -The formula is plotted with this variable taking on the various ``x'' -values. Graphs of formulas by default use lines without symbols at the -computed data points. Note that if neither ``x'' nor ``y'' is a vector, -Calc guesses at a reasonable number of data points to use. See the -@kbd{g N} command below. (The ``x'' values must be either a vector -or an interval if ``y'' is a formula.) - -@ignore -@starindex -@end ignore -@tindex xy -If ``y'' is (or evaluates to) a formula of the form -@samp{xy(@var{x}, @var{y})} then the result is a -parametric plot. The two arguments of the fictitious @code{xy} function -are used as the ``x'' and ``y'' coordinates of the curve, respectively. -In this case the ``x'' vector or interval you specified is not directly -visible in the graph. For example, if ``x'' is the interval @samp{[0..360]} -and ``y'' is the formula @samp{xy(sin(t), cos(t))}, the resulting graph -will be a circle. - -Also, ``x'' and ``y'' may each be variable names, in which case Calc -looks for suitable vectors, intervals, or formulas stored in those -variables. - -The ``x'' and ``y'' values for the data points (as pulled from the vectors, -calculated from the formulas, or interpolated from the intervals) should -be real numbers (integers, fractions, or floats). One exception to this -is that the ``y'' entry can consist of a vector of numbers combined with -error forms, in which case the points will be plotted with the -appropriate error bars. Other than this, if either the ``x'' -value or the ``y'' value of a given data point is not a real number, that -data point will be omitted from the graph. The points on either side -of the invalid point will @emph{not} be connected by a line. - -See the documentation for @kbd{g a} below for a description of the way -numeric prefix arguments affect @kbd{g f}. - -@cindex @code{PlotRejects} variable -@vindex PlotRejects -If you store an empty vector in the variable @code{PlotRejects} -(i.e., @kbd{[ ] s t PlotRejects}), Calc will append information to -this vector for every data point which was rejected because its -``x'' or ``y'' values were not real numbers. The result will be -a matrix where each row holds the curve number, data point number, -``x'' value, and ``y'' value for a rejected data point. -@xref{Evaluates-To Operator}, for a handy way to keep tabs on the -current value of @code{PlotRejects}. @xref{Operations on Variables}, -for the @kbd{s R} command which is another easy way to examine -@code{PlotRejects}. - -@kindex g c -@pindex calc-graph-clear -To clear the graphics display, type @kbd{g c} (@code{calc-graph-clear}). -If the GNUPLOT output device is an X window, the window will go away. -Effects on other kinds of output devices will vary. You don't need -to use @kbd{g c} if you don't want to---if you give another @kbd{g f} -or @kbd{g p} command later on, it will reuse the existing graphics -window if there is one. - -@node Three Dimensional Graphics, Managing Curves, Basic Graphics, Graphics -@section Three-Dimensional Graphics - -@kindex g F -@pindex calc-graph-fast-3d -The @kbd{g F} (@code{calc-graph-fast-3d}) command makes a three-dimensional -graph. It works only if you have GNUPLOT 3.0 or later; with GNUPLOT 2.0, -you will see a GNUPLOT error message if you try this command. - -The @kbd{g F} command takes three values from the stack, called ``x'', -``y'', and ``z'', respectively. As was the case for 2D graphs, there -are several options for these values. - -In the first case, ``x'' and ``y'' are each vectors (not necessarily of -the same length); either or both may instead be interval forms. The -``z'' value must be a matrix with the same number of rows as elements -in ``x'', and the same number of columns as elements in ``y''. The -result is a surface plot where -@texline @math{z_{ij}} -@infoline @expr{z_ij} -is the height of the point -at coordinate @expr{(x_i, y_j)} on the surface. The 3D graph will -be displayed from a certain default viewpoint; you can change this -viewpoint by adding a @samp{set view} to the @samp{*Gnuplot Commands*} -buffer as described later. See the GNUPLOT documentation for a -description of the @samp{set view} command. - -Each point in the matrix will be displayed as a dot in the graph, -and these points will be connected by a grid of lines (@dfn{isolines}). - -In the second case, ``x'', ``y'', and ``z'' are all vectors of equal -length. The resulting graph displays a 3D line instead of a surface, -where the coordinates of points along the line are successive triplets -of values from the input vectors. - -In the third case, ``x'' and ``y'' are vectors or interval forms, and -``z'' is any formula involving two variables (not counting variables -with assigned values). These variables are sorted into alphabetical -order; the first takes on values from ``x'' and the second takes on -values from ``y'' to form a matrix of results that are graphed as a -3D surface. - -@ignore -@starindex -@end ignore -@tindex xyz -If the ``z'' formula evaluates to a call to the fictitious function -@samp{xyz(@var{x}, @var{y}, @var{z})}, then the result is a -``parametric surface.'' In this case, the axes of the graph are -taken from the @var{x} and @var{y} values in these calls, and the -``x'' and ``y'' values from the input vectors or intervals are used only -to specify the range of inputs to the formula. For example, plotting -@samp{[0..360], [0..180], xyz(sin(x)*sin(y), cos(x)*sin(y), cos(y))} -will draw a sphere. (Since the default resolution for 3D plots is -5 steps in each of ``x'' and ``y'', this will draw a very crude -sphere. You could use the @kbd{g N} command, described below, to -increase this resolution, or specify the ``x'' and ``y'' values as -vectors with more than 5 elements. - -It is also possible to have a function in a regular @kbd{g f} plot -evaluate to an @code{xyz} call. Since @kbd{g f} plots a line, not -a surface, the result will be a 3D parametric line. For example, -@samp{[[0..720], xyz(sin(x), cos(x), x)]} will plot two turns of a -helix (a three-dimensional spiral). - -As for @kbd{g f}, each of ``x'', ``y'', and ``z'' may instead be -variables containing the relevant data. - -@node Managing Curves, Graphics Options, Three Dimensional Graphics, Graphics -@section Managing Curves - -@noindent -The @kbd{g f} command is really shorthand for the following commands: -@kbd{C-u g d g a g p}. Likewise, @w{@kbd{g F}} is shorthand for -@kbd{C-u g d g A g p}. You can gain more control over your graph -by using these commands directly. - -@kindex g a -@pindex calc-graph-add -The @kbd{g a} (@code{calc-graph-add}) command adds the ``curve'' -represented by the two values on the top of the stack to the current -graph. You can have any number of curves in the same graph. When -you give the @kbd{g p} command, all the curves will be drawn superimposed -on the same axes. - -The @kbd{g a} command (and many others that affect the current graph) -will cause a special buffer, @samp{*Gnuplot Commands*}, to be displayed -in another window. This buffer is a template of the commands that will -be sent to GNUPLOT when it is time to draw the graph. The first -@kbd{g a} command adds a @code{plot} command to this buffer. Succeeding -@kbd{g a} commands add extra curves onto that @code{plot} command. -Other graph-related commands put other GNUPLOT commands into this -buffer. In normal usage you never need to work with this buffer -directly, but you can if you wish. The only constraint is that there -must be only one @code{plot} command, and it must be the last command -in the buffer. If you want to save and later restore a complete graph -configuration, you can use regular Emacs commands to save and restore -the contents of the @samp{*Gnuplot Commands*} buffer. - -@vindex PlotData1 -@vindex PlotData2 -If the values on the stack are not variable names, @kbd{g a} will invent -variable names for them (of the form @samp{PlotData@var{n}}) and store -the values in those variables. The ``x'' and ``y'' variables are what -go into the @code{plot} command in the template. If you add a curve -that uses a certain variable and then later change that variable, you -can replot the graph without having to delete and re-add the curve. -That's because the variable name, not the vector, interval or formula -itself, is what was added by @kbd{g a}. - -A numeric prefix argument on @kbd{g a} or @kbd{g f} changes the way -stack entries are interpreted as curves. With a positive prefix -argument @expr{n}, the top @expr{n} stack entries are ``y'' values -for @expr{n} different curves which share a common ``x'' value in -the @expr{n+1}st stack entry. (Thus @kbd{g a} with no prefix -argument is equivalent to @kbd{C-u 1 g a}.) - -A prefix of zero or plain @kbd{C-u} means to take two stack entries, -``x'' and ``y'' as usual, but to interpret ``y'' as a vector of -``y'' values for several curves that share a common ``x''. - -A negative prefix argument tells Calc to read @expr{n} vectors from -the stack; each vector @expr{[x, y]} describes an independent curve. -This is the only form of @kbd{g a} that creates several curves at once -that don't have common ``x'' values. (Of course, the range of ``x'' -values covered by all the curves ought to be roughly the same if -they are to look nice on the same graph.) - -For example, to plot -@texline @math{\sin n x} -@infoline @expr{sin(n x)} -for integers @expr{n} -from 1 to 5, you could use @kbd{v x} to create a vector of integers -(@expr{n}), then @kbd{V M '} or @kbd{V M $} to map @samp{sin(n x)} -across this vector. The resulting vector of formulas is suitable -for use as the ``y'' argument to a @kbd{C-u g a} or @kbd{C-u g f} -command. - -@kindex g A -@pindex calc-graph-add-3d -The @kbd{g A} (@code{calc-graph-add-3d}) command adds a 3D curve -to the graph. It is not valid to intermix 2D and 3D curves in a -single graph. This command takes three arguments, ``x'', ``y'', -and ``z'', from the stack. With a positive prefix @expr{n}, it -takes @expr{n+2} arguments (common ``x'' and ``y'', plus @expr{n} -separate ``z''s). With a zero prefix, it takes three stack entries -but the ``z'' entry is a vector of curve values. With a negative -prefix @expr{-n}, it takes @expr{n} vectors of the form @expr{[x, y, z]}. -The @kbd{g A} command works by adding a @code{splot} (surface-plot) -command to the @samp{*Gnuplot Commands*} buffer. - -(Although @kbd{g a} adds a 2D @code{plot} command to the -@samp{*Gnuplot Commands*} buffer, Calc changes this to @code{splot} -before sending it to GNUPLOT if it notices that the data points are -evaluating to @code{xyz} calls. It will not work to mix 2D and 3D -@kbd{g a} curves in a single graph, although Calc does not currently -check for this.) - -@kindex g d -@pindex calc-graph-delete -The @kbd{g d} (@code{calc-graph-delete}) command deletes the most -recently added curve from the graph. It has no effect if there are -no curves in the graph. With a numeric prefix argument of any kind, -it deletes all of the curves from the graph. - -@kindex g H -@pindex calc-graph-hide -The @kbd{g H} (@code{calc-graph-hide}) command ``hides'' or ``unhides'' -the most recently added curve. A hidden curve will not appear in -the actual plot, but information about it such as its name and line and -point styles will be retained. - -@kindex g j -@pindex calc-graph-juggle -The @kbd{g j} (@code{calc-graph-juggle}) command moves the curve -at the end of the list (the ``most recently added curve'') to the -front of the list. The next-most-recent curve is thus exposed for -@w{@kbd{g d}} or similar commands to use. With @kbd{g j} you can work -with any curve in the graph even though curve-related commands only -affect the last curve in the list. - -@kindex g p -@pindex calc-graph-plot -The @kbd{g p} (@code{calc-graph-plot}) command uses GNUPLOT to draw -the graph described in the @samp{*Gnuplot Commands*} buffer. Any -GNUPLOT parameters which are not defined by commands in this buffer -are reset to their default values. The variables named in the @code{plot} -command are written to a temporary data file and the variable names -are then replaced by the file name in the template. The resulting -plotting commands are fed to the GNUPLOT program. See the documentation -for the GNUPLOT program for more specific information. All temporary -files are removed when Emacs or GNUPLOT exits. - -If you give a formula for ``y'', Calc will remember all the values that -it calculates for the formula so that later plots can reuse these values. -Calc throws out these saved values when you change any circumstances -that may affect the data, such as switching from Degrees to Radians -mode, or changing the value of a parameter in the formula. You can -force Calc to recompute the data from scratch by giving a negative -numeric prefix argument to @kbd{g p}. - -Calc uses a fairly rough step size when graphing formulas over intervals. -This is to ensure quick response. You can ``refine'' a plot by giving -a positive numeric prefix argument to @kbd{g p}. Calc goes through -the data points it has computed and saved from previous plots of the -function, and computes and inserts a new data point midway between -each of the existing points. You can refine a plot any number of times, -but beware that the amount of calculation involved doubles each time. - -Calc does not remember computed values for 3D graphs. This means the -numerix prefix argument, if any, to @kbd{g p} is effectively ignored if -the current graph is three-dimensional. - -@kindex g P -@pindex calc-graph-print -The @kbd{g P} (@code{calc-graph-print}) command is like @kbd{g p}, -except that it sends the output to a printer instead of to the -screen. More precisely, @kbd{g p} looks for @samp{set terminal} -or @samp{set output} commands in the @samp{*Gnuplot Commands*} buffer; -lacking these it uses the default settings. However, @kbd{g P} -ignores @samp{set terminal} and @samp{set output} commands and -uses a different set of default values. All of these values are -controlled by the @kbd{g D} and @kbd{g O} commands discussed below. -Provided everything is set up properly, @kbd{g p} will plot to -the screen unless you have specified otherwise and @kbd{g P} will -always plot to the printer. - -@node Graphics Options, Devices, Managing Curves, Graphics -@section Graphics Options - -@noindent -@kindex g g -@pindex calc-graph-grid -The @kbd{g g} (@code{calc-graph-grid}) command turns the ``grid'' -on and off. It is off by default; tick marks appear only at the -edges of the graph. With the grid turned on, dotted lines appear -across the graph at each tick mark. Note that this command only -changes the setting in @samp{*Gnuplot Commands*}; to see the effects -of the change you must give another @kbd{g p} command. - -@kindex g b -@pindex calc-graph-border -The @kbd{g b} (@code{calc-graph-border}) command turns the border -(the box that surrounds the graph) on and off. It is on by default. -This command will only work with GNUPLOT 3.0 and later versions. - -@kindex g k -@pindex calc-graph-key -The @kbd{g k} (@code{calc-graph-key}) command turns the ``key'' -on and off. The key is a chart in the corner of the graph that -shows the correspondence between curves and line styles. It is -off by default, and is only really useful if you have several -curves on the same graph. - -@kindex g N -@pindex calc-graph-num-points -The @kbd{g N} (@code{calc-graph-num-points}) command allows you -to select the number of data points in the graph. This only affects -curves where neither ``x'' nor ``y'' is specified as a vector. -Enter a blank line to revert to the default value (initially 15). -With no prefix argument, this command affects only the current graph. -With a positive prefix argument this command changes or, if you enter -a blank line, displays the default number of points used for all -graphs created by @kbd{g a} that don't specify the resolution explicitly. -With a negative prefix argument, this command changes or displays -the default value (initially 5) used for 3D graphs created by @kbd{g A}. -Note that a 3D setting of 5 means that a total of @expr{5^2 = 25} points -will be computed for the surface. - -Data values in the graph of a function are normally computed to a -precision of five digits, regardless of the current precision at the -time. This is usually more than adequate, but there are cases where -it will not be. For example, plotting @expr{1 + x} with @expr{x} in the -interval @samp{[0 ..@: 1e-6]} will round all the data points down -to 1.0! Putting the command @samp{set precision @var{n}} in the -@samp{*Gnuplot Commands*} buffer will cause the data to be computed -at precision @var{n} instead of 5. Since this is such a rare case, -there is no keystroke-based command to set the precision. - -@kindex g h -@pindex calc-graph-header -The @kbd{g h} (@code{calc-graph-header}) command sets the title -for the graph. This will show up centered above the graph. -The default title is blank (no title). - -@kindex g n -@pindex calc-graph-name -The @kbd{g n} (@code{calc-graph-name}) command sets the title of an -individual curve. Like the other curve-manipulating commands, it -affects the most recently added curve, i.e., the last curve on the -list in the @samp{*Gnuplot Commands*} buffer. To set the title of -the other curves you must first juggle them to the end of the list -with @kbd{g j}, or edit the @samp{*Gnuplot Commands*} buffer by hand. -Curve titles appear in the key; if the key is turned off they are -not used. - -@kindex g t -@kindex g T -@pindex calc-graph-title-x -@pindex calc-graph-title-y -The @kbd{g t} (@code{calc-graph-title-x}) and @kbd{g T} -(@code{calc-graph-title-y}) commands set the titles on the ``x'' -and ``y'' axes, respectively. These titles appear next to the -tick marks on the left and bottom edges of the graph, respectively. -Calc does not have commands to control the tick marks themselves, -but you can edit them into the @samp{*Gnuplot Commands*} buffer if -you wish. See the GNUPLOT documentation for details. - -@kindex g r -@kindex g R -@pindex calc-graph-range-x -@pindex calc-graph-range-y -The @kbd{g r} (@code{calc-graph-range-x}) and @kbd{g R} -(@code{calc-graph-range-y}) commands set the range of values on the -``x'' and ``y'' axes, respectively. You are prompted to enter a -suitable range. This should be either a pair of numbers of the -form, @samp{@var{min}:@var{max}}, or a blank line to revert to the -default behavior of setting the range based on the range of values -in the data, or @samp{$} to take the range from the top of the stack. -Ranges on the stack can be represented as either interval forms or -vectors: @samp{[@var{min} ..@: @var{max}]} or @samp{[@var{min}, @var{max}]}. - -@kindex g l -@kindex g L -@pindex calc-graph-log-x -@pindex calc-graph-log-y -The @kbd{g l} (@code{calc-graph-log-x}) and @kbd{g L} (@code{calc-graph-log-y}) -commands allow you to set either or both of the axes of the graph to -be logarithmic instead of linear. - -@kindex g C-l -@kindex g C-r -@kindex g C-t -@pindex calc-graph-log-z -@pindex calc-graph-range-z -@pindex calc-graph-title-z -For 3D plots, @kbd{g C-t}, @kbd{g C-r}, and @kbd{g C-l} (those are -letters with the Control key held down) are the corresponding commands -for the ``z'' axis. - -@kindex g z -@kindex g Z -@pindex calc-graph-zero-x -@pindex calc-graph-zero-y -The @kbd{g z} (@code{calc-graph-zero-x}) and @kbd{g Z} -(@code{calc-graph-zero-y}) commands control whether a dotted line is -drawn to indicate the ``x'' and/or ``y'' zero axes. (These are the same -dotted lines that would be drawn there anyway if you used @kbd{g g} to -turn the ``grid'' feature on.) Zero-axis lines are on by default, and -may be turned off only in GNUPLOT 3.0 and later versions. They are -not available for 3D plots. - -@kindex g s -@pindex calc-graph-line-style -The @kbd{g s} (@code{calc-graph-line-style}) command turns the connecting -lines on or off for the most recently added curve, and optionally selects -the style of lines to be used for that curve. Plain @kbd{g s} simply -toggles the lines on and off. With a numeric prefix argument, @kbd{g s} -turns lines on and sets a particular line style. Line style numbers -start at one and their meanings vary depending on the output device. -GNUPLOT guarantees that there will be at least six different line styles -available for any device. - -@kindex g S -@pindex calc-graph-point-style -The @kbd{g S} (@code{calc-graph-point-style}) command similarly turns -the symbols at the data points on or off, or sets the point style. -If you turn both lines and points off, the data points will show as -tiny dots. If the ``y'' values being plotted contain error forms and -the connecting lines are turned off, then this command will also turn -the error bars on or off. - -@cindex @code{LineStyles} variable -@cindex @code{PointStyles} variable -@vindex LineStyles -@vindex PointStyles -Another way to specify curve styles is with the @code{LineStyles} and -@code{PointStyles} variables. These variables initially have no stored -values, but if you store a vector of integers in one of these variables, -the @kbd{g a} and @kbd{g f} commands will use those style numbers -instead of the defaults for new curves that are added to the graph. -An entry should be a positive integer for a specific style, or 0 to let -the style be chosen automatically, or @mathit{-1} to turn off lines or points -altogether. If there are more curves than elements in the vector, the -last few curves will continue to have the default styles. Of course, -you can later use @kbd{g s} and @kbd{g S} to change any of these styles. - -For example, @kbd{'[2 -1 3] @key{RET} s t LineStyles} causes the first curve -to have lines in style number 2, the second curve to have no connecting -lines, and the third curve to have lines in style 3. Point styles will -still be assigned automatically, but you could store another vector in -@code{PointStyles} to define them, too. - -@node Devices, , Graphics Options, Graphics -@section Graphical Devices - -@noindent -@kindex g D -@pindex calc-graph-device -The @kbd{g D} (@code{calc-graph-device}) command sets the device name -(or ``terminal name'' in GNUPLOT lingo) to be used by @kbd{g p} commands -on this graph. It does not affect the permanent default device name. -If you enter a blank name, the device name reverts to the default. -Enter @samp{?} to see a list of supported devices. - -With a positive numeric prefix argument, @kbd{g D} instead sets -the default device name, used by all plots in the future which do -not override it with a plain @kbd{g D} command. If you enter a -blank line this command shows you the current default. The special -name @code{default} signifies that Calc should choose @code{x11} if -the X window system is in use (as indicated by the presence of a -@code{DISPLAY} environment variable), @code{windows} on MS-Windows, or -otherwise @code{dumb} under GNUPLOT 3.0 and later, or -@code{postscript} under GNUPLOT 2.0. This is the initial default -value. - -The @code{dumb} device is an interface to ``dumb terminals,'' i.e., -terminals with no special graphics facilities. It writes a crude -picture of the graph composed of characters like @code{-} and @code{|} -to a buffer called @samp{*Gnuplot Trail*}, which Calc then displays. -The graph is made the same size as the Emacs screen, which on most -dumb terminals will be -@texline @math{80\times24} -@infoline 80x24 -characters. The graph is displayed in -an Emacs ``recursive edit''; type @kbd{q} or @kbd{C-c C-c} to exit -the recursive edit and return to Calc. Note that the @code{dumb} -device is present only in GNUPLOT 3.0 and later versions. - -The word @code{dumb} may be followed by two numbers separated by -spaces. These are the desired width and height of the graph in -characters. Also, the device name @code{big} is like @code{dumb} -but creates a graph four times the width and height of the Emacs -screen. You will then have to scroll around to view the entire -graph. In the @samp{*Gnuplot Trail*} buffer, @key{SPC}, @key{DEL}, -@kbd{<}, and @kbd{>} are defined to scroll by one screenful in each -of the four directions. - -With a negative numeric prefix argument, @kbd{g D} sets or displays -the device name used by @kbd{g P} (@code{calc-graph-print}). This -is initially @code{postscript}. If you don't have a PostScript -printer, you may decide once again to use @code{dumb} to create a -plot on any text-only printer. - -@kindex g O -@pindex calc-graph-output -The @kbd{g O} (@code{calc-graph-output}) command sets the name of the -output file used by GNUPLOT. For some devices, notably @code{x11} and -@code{windows}, there is no output file and this information is not -used. Many other ``devices'' are really file formats like -@code{postscript}; in these cases the output in the desired format -goes into the file you name with @kbd{g O}. Type @kbd{g O stdout -@key{RET}} to set GNUPLOT to write to its standard output stream, -i.e., to @samp{*Gnuplot Trail*}. This is the default setting. - -Another special output name is @code{tty}, which means that GNUPLOT -is going to write graphics commands directly to its standard output, -which you wish Emacs to pass through to your terminal. Tektronix -graphics terminals, among other devices, operate this way. Calc does -this by telling GNUPLOT to write to a temporary file, then running a -sub-shell executing the command @samp{cat tempfile >/dev/tty}. On -typical Unix systems, this will copy the temporary file directly to -the terminal, bypassing Emacs entirely. You will have to type @kbd{C-l} -to Emacs afterwards to refresh the screen. - -Once again, @kbd{g O} with a positive or negative prefix argument -sets the default or printer output file names, respectively. In each -case you can specify @code{auto}, which causes Calc to invent a temporary -file name for each @kbd{g p} (or @kbd{g P}) command. This temporary file -will be deleted once it has been displayed or printed. If the output file -name is not @code{auto}, the file is not automatically deleted. - -The default and printer devices and output files can be saved -permanently by the @kbd{m m} (@code{calc-save-modes}) command. The -default number of data points (see @kbd{g N}) and the X geometry -(see @kbd{g X}) are also saved. Other graph information is @emph{not} -saved; you can save a graph's configuration simply by saving the contents -of the @samp{*Gnuplot Commands*} buffer. - -@vindex calc-gnuplot-plot-command -@vindex calc-gnuplot-default-device -@vindex calc-gnuplot-default-output -@vindex calc-gnuplot-print-command -@vindex calc-gnuplot-print-device -@vindex calc-gnuplot-print-output -You may wish to configure the default and -printer devices and output files for the whole system. The relevant -Lisp variables are @code{calc-gnuplot-default-device} and @code{-output}, -and @code{calc-gnuplot-print-device} and @code{-output}. The output -file names must be either strings as described above, or Lisp -expressions which are evaluated on the fly to get the output file names. - -Other important Lisp variables are @code{calc-gnuplot-plot-command} and -@code{calc-gnuplot-print-command}, which give the system commands to -display or print the output of GNUPLOT, respectively. These may be -@code{nil} if no command is necessary, or strings which can include -@samp{%s} to signify the name of the file to be displayed or printed. -Or, these variables may contain Lisp expressions which are evaluated -to display or print the output. These variables are customizable -(@pxref{Customizing Calc}). - -@kindex g x -@pindex calc-graph-display -The @kbd{g x} (@code{calc-graph-display}) command lets you specify -on which X window system display your graphs should be drawn. Enter -a blank line to see the current display name. This command has no -effect unless the current device is @code{x11}. - -@kindex g X -@pindex calc-graph-geometry -The @kbd{g X} (@code{calc-graph-geometry}) command is a similar -command for specifying the position and size of the X window. -The normal value is @code{default}, which generally means your -window manager will let you place the window interactively. -Entering @samp{800x500+0+0} would create an 800-by-500 pixel -window in the upper-left corner of the screen. This command has no -effect if the current device is @code{windows}. - -The buffer called @samp{*Gnuplot Trail*} holds a transcript of the -session with GNUPLOT. This shows the commands Calc has ``typed'' to -GNUPLOT and the responses it has received. Calc tries to notice when an -error message has appeared here and display the buffer for you when -this happens. You can check this buffer yourself if you suspect -something has gone wrong@footnote{ -On MS-Windows, due to the peculiarities of how the Windows version of -GNUPLOT (called @command{wgnuplot}) works, the GNUPLOT responses are -not communicated back to Calc. Instead, you need to look them up in -the GNUPLOT command window that is displayed as in normal interactive -usage of GNUPLOT. -}. - -@kindex g C -@pindex calc-graph-command -The @kbd{g C} (@code{calc-graph-command}) command prompts you to -enter any line of text, then simply sends that line to the current -GNUPLOT process. The @samp{*Gnuplot Trail*} buffer looks deceptively -like a Shell buffer but you can't type commands in it yourself. -Instead, you must use @kbd{g C} for this purpose. - -@kindex g v -@kindex g V -@pindex calc-graph-view-commands -@pindex calc-graph-view-trail -The @kbd{g v} (@code{calc-graph-view-commands}) and @kbd{g V} -(@code{calc-graph-view-trail}) commands display the @samp{*Gnuplot Commands*} -and @samp{*Gnuplot Trail*} buffers, respectively, in another window. -This happens automatically when Calc thinks there is something you -will want to see in either of these buffers. If you type @kbd{g v} -or @kbd{g V} when the relevant buffer is already displayed, the -buffer is hidden again. (Note that on MS-Windows, the @samp{*Gnuplot -Trail*} buffer will usually show nothing of interest, because -GNUPLOT's responses are not communicated back to Calc.) - -One reason to use @kbd{g v} is to add your own commands to the -@samp{*Gnuplot Commands*} buffer. Press @kbd{g v}, then use -@kbd{C-x o} to switch into that window. For example, GNUPLOT has -@samp{set label} and @samp{set arrow} commands that allow you to -annotate your plots. Since Calc doesn't understand these commands, -you have to add them to the @samp{*Gnuplot Commands*} buffer -yourself, then use @w{@kbd{g p}} to replot using these new commands. Note -that your commands must appear @emph{before} the @code{plot} command. -To get help on any GNUPLOT feature, type, e.g., @kbd{g C help set label}. -You may have to type @kbd{g C @key{RET}} a few times to clear the -``press return for more'' or ``subtopic of @dots{}'' requests. -Note that Calc always sends commands (like @samp{set nolabel}) to -reset all plotting parameters to the defaults before each plot, so -to delete a label all you need to do is delete the @samp{set label} -line you added (or comment it out with @samp{#}) and then replot -with @kbd{g p}. - -@kindex g q -@pindex calc-graph-quit -You can use @kbd{g q} (@code{calc-graph-quit}) to kill the GNUPLOT -process that is running. The next graphing command you give will -start a fresh GNUPLOT process. The word @samp{Graph} appears in -the Calc window's mode line whenever a GNUPLOT process is currently -running. The GNUPLOT process is automatically killed when you -exit Emacs if you haven't killed it manually by then. - -@kindex g K -@pindex calc-graph-kill -The @kbd{g K} (@code{calc-graph-kill}) command is like @kbd{g q} -except that it also views the @samp{*Gnuplot Trail*} buffer so that -you can see the process being killed. This is better if you are -killing GNUPLOT because you think it has gotten stuck. - -@node Kill and Yank, Keypad Mode, Graphics, Top -@chapter Kill and Yank Functions - -@noindent -The commands in this chapter move information between the Calculator and -other Emacs editing buffers. - -In many cases Embedded mode is an easier and more natural way to -work with Calc from a regular editing buffer. @xref{Embedded Mode}. - -@menu -* Killing From Stack:: -* Yanking Into Stack:: -* Saving Into Registers:: -* Inserting From Registers:: -* Grabbing From Buffers:: -* Yanking Into Buffers:: -* X Cut and Paste:: -@end menu - -@node Killing From Stack, Yanking Into Stack, Kill and Yank, Kill and Yank -@section Killing from the Stack - -@noindent -@kindex C-k -@pindex calc-kill -@kindex M-k -@pindex calc-copy-as-kill -@kindex C-w -@pindex calc-kill-region -@kindex M-w -@pindex calc-copy-region-as-kill -@kindex M-C-w -@cindex Kill ring -@dfn{Kill} commands are Emacs commands that insert text into the ``kill -ring,'' from which it can later be ``yanked'' by a @kbd{C-y} command. -Three common kill commands in normal Emacs are @kbd{C-k}, which kills -one line, @kbd{C-w}, which kills the region between mark and point, and -@kbd{M-w}, which puts the region into the kill ring without actually -deleting it. All of these commands work in the Calculator, too, -although in the Calculator they operate on whole stack entries, so they -``round up'' the specified region to encompass full lines. (To copy -only parts of lines, the @kbd{M-C-w} command in the Calculator will copy -the region to the kill ring without any ``rounding up'', just like the -@kbd{M-w} command in normal Emacs.) Also, @kbd{M-k} has been provided -to complete the set; it puts the current line into the kill ring without -deleting anything. - -The kill commands are unusual in that they pay attention to the location -of the cursor in the Calculator buffer. If the cursor is on or below -the bottom line, the kill commands operate on the top of the stack. -Otherwise, they operate on whatever stack element the cursor is on. The -text is copied into the kill ring exactly as it appears on the screen, -including line numbers if they are enabled. - -A numeric prefix argument to @kbd{C-k} or @kbd{M-k} affects the number -of lines killed. A positive argument kills the current line and @expr{n-1} -lines below it. A negative argument kills the @expr{-n} lines above the -current line. Again this mirrors the behavior of the standard Emacs -@kbd{C-k} command. Although a whole line is always deleted, @kbd{C-k} -with no argument copies only the number itself into the kill ring, whereas -@kbd{C-k} with a prefix argument of 1 copies the number with its trailing -newline. - -@node Yanking Into Stack, Saving Into Registers, Killing From Stack, Kill and Yank -@section Yanking into the Stack - -@noindent -@kindex C-y -@pindex calc-yank -The @kbd{C-y} command yanks the most recently killed text back into the -Calculator. It pushes this value onto the top of the stack regardless of -the cursor position. In general it re-parses the killed text as a number -or formula (or a list of these separated by commas or newlines). However if -the thing being yanked is something that was just killed from the Calculator -itself, its full internal structure is yanked. For example, if you have -set the floating-point display mode to show only four significant digits, -then killing and re-yanking 3.14159 (which displays as 3.142) will yank the -full 3.14159, even though yanking it into any other buffer would yank the -number in its displayed form, 3.142. (Since the default display modes -show all objects to their full precision, this feature normally makes no -difference.) - -@node Saving Into Registers, Inserting From Registers, Yanking Into Stack, Kill and Yank -@section Saving into Registers - -@noindent -@kindex r s -@pindex calc-copy-to-register -@pindex calc-prepend-to-register -@pindex calc-append-to-register -@cindex Registers -An alternative to killing and yanking stack entries is using -registers in Calc. Saving stack entries in registers is like -saving text in normal Emacs registers; although, like Calc's kill -commands, register commands always operate on whole stack -entries. - -Registers in Calc are places to store stack entries for later use; -each register is indexed by a single character. To store the current -region (rounded up, of course, to include full stack entries) into a -register, use the command @kbd{r s} (@code{calc-copy-to-register}). -You will then be prompted for a register to use, the next character -you type will be the index for the register. To store the region in -register @var{r}, the full command will be @kbd{r s @var{r}}. With an -argument, @kbd{C-u r s @var{r}}, the region being copied to the -register will be deleted from the Calc buffer. - -It is possible to add additional stack entries to a register. The -command @kbd{M-x calc-append-to-register} will prompt for a register, -then add the stack entries in the region to the end of the register -contents. The command @kbd{M-x calc-prepend-to-register} will -similarly prompt for a register and add the stack entries in the -region to the beginning of the register contents. Both commands take -@kbd{C-u} arguments, which will cause the region to be deleted after being -added to the register. - -@node Inserting From Registers, Grabbing From Buffers, Saving Into Registers, Kill and Yank -@section Inserting from Registers -@noindent -@kindex r i -@pindex calc-insert-register -The command @kbd{r i} (@code{calc-insert-register}) will prompt for a -register, then insert the contents of that register into the -Calculator. If the contents of the register were placed there from -within Calc, then the full internal structure of the contents will be -inserted into the Calculator, otherwise whatever text is in the -register is reparsed and then inserted into the Calculator. - -@node Grabbing From Buffers, Yanking Into Buffers, Inserting From Registers, Kill and Yank -@section Grabbing from Other Buffers - -@noindent -@kindex C-x * g -@pindex calc-grab-region -The @kbd{C-x * g} (@code{calc-grab-region}) command takes the text between -point and mark in the current buffer and attempts to parse it as a -vector of values. Basically, it wraps the text in vector brackets -@samp{[ ]} unless the text already is enclosed in vector brackets, -then reads the text as if it were an algebraic entry. The contents -of the vector may be numbers, formulas, or any other Calc objects. -If the @kbd{C-x * g} command works successfully, it does an automatic -@kbd{C-x * c} to enter the Calculator buffer. - -A numeric prefix argument grabs the specified number of lines around -point, ignoring the mark. A positive prefix grabs from point to the -@expr{n}th following newline (so that @kbd{M-1 C-x * g} grabs from point -to the end of the current line); a negative prefix grabs from point -back to the @expr{n+1}st preceding newline. In these cases the text -that is grabbed is exactly the same as the text that @kbd{C-k} would -delete given that prefix argument. - -A prefix of zero grabs the current line; point may be anywhere on the -line. - -A plain @kbd{C-u} prefix interprets the region between point and mark -as a single number or formula rather than a vector. For example, -@kbd{C-x * g} on the text @samp{2 a b} produces the vector of three -values @samp{[2, a, b]}, but @kbd{C-u C-x * g} on the same region -reads a formula which is a product of three things: @samp{2 a b}. -(The text @samp{a + b}, on the other hand, will be grabbed as a -vector of one element by plain @kbd{C-x * g} because the interpretation -@samp{[a, +, b]} would be a syntax error.) - -If a different language has been specified (@pxref{Language Modes}), -the grabbed text will be interpreted according to that language. - -@kindex C-x * r -@pindex calc-grab-rectangle -The @kbd{C-x * r} (@code{calc-grab-rectangle}) command takes the text between -point and mark and attempts to parse it as a matrix. If point and mark -are both in the leftmost column, the lines in between are parsed in their -entirety. Otherwise, point and mark define the corners of a rectangle -whose contents are parsed. - -Each line of the grabbed area becomes a row of the matrix. The result -will actually be a vector of vectors, which Calc will treat as a matrix -only if every row contains the same number of values. - -If a line contains a portion surrounded by square brackets (or curly -braces), that portion is interpreted as a vector which becomes a row -of the matrix. Any text surrounding the bracketed portion on the line -is ignored. - -Otherwise, the entire line is interpreted as a row vector as if it -were surrounded by square brackets. Leading line numbers (in the -format used in the Calc stack buffer) are ignored. If you wish to -force this interpretation (even if the line contains bracketed -portions), give a negative numeric prefix argument to the -@kbd{C-x * r} command. - -If you give a numeric prefix argument of zero or plain @kbd{C-u}, each -line is instead interpreted as a single formula which is converted into -a one-element vector. Thus the result of @kbd{C-u C-x * r} will be a -one-column matrix. For example, suppose one line of the data is the -expression @samp{2 a}. A plain @w{@kbd{C-x * r}} will interpret this as -@samp{[2 a]}, which in turn is read as a two-element vector that forms -one row of the matrix. But a @kbd{C-u C-x * r} will interpret this row -as @samp{[2*a]}. - -If you give a positive numeric prefix argument @var{n}, then each line -will be split up into columns of width @var{n}; each column is parsed -separately as a matrix element. If a line contained -@w{@samp{2 +/- 3 4 +/- 5}}, then grabbing with a prefix argument of 8 -would correctly split the line into two error forms. - -@xref{Matrix Functions}, to see how to pull the matrix apart into its -constituent rows and columns. (If it is a -@texline @math{1\times1} -@infoline 1x1 -matrix, just hit @kbd{v u} (@code{calc-unpack}) twice.) - -@kindex C-x * : -@kindex C-x * _ -@pindex calc-grab-sum-across -@pindex calc-grab-sum-down -@cindex Summing rows and columns of data -The @kbd{C-x * :} (@code{calc-grab-sum-down}) command is a handy way to -grab a rectangle of data and sum its columns. It is equivalent to -typing @kbd{C-x * r}, followed by @kbd{V R : +} (the vector reduction -command that sums the columns of a matrix; @pxref{Reducing}). The -result of the command will be a vector of numbers, one for each column -in the input data. The @kbd{C-x * _} (@code{calc-grab-sum-across}) command -similarly grabs a rectangle and sums its rows by executing @w{@kbd{V R _ +}}. - -As well as being more convenient, @kbd{C-x * :} and @kbd{C-x * _} are also -much faster because they don't actually place the grabbed vector on -the stack. In a @kbd{C-x * r V R : +} sequence, formatting the vector -for display on the stack takes a large fraction of the total time -(unless you have planned ahead and used @kbd{v .} and @kbd{t .} modes). - -For example, suppose we have a column of numbers in a file which we -wish to sum. Go to one corner of the column and press @kbd{C-@@} to -set the mark; go to the other corner and type @kbd{C-x * :}. Since there -is only one column, the result will be a vector of one number, the sum. -(You can type @kbd{v u} to unpack this vector into a plain number if -you want to do further arithmetic with it.) - -To compute the product of the column of numbers, we would have to do -it ``by hand'' since there's no special grab-and-multiply command. -Use @kbd{C-x * r} to grab the column of numbers into the calculator in -the form of a column matrix. The statistics command @kbd{u *} is a -handy way to find the product of a vector or matrix of numbers. -@xref{Statistical Operations}. Another approach would be to use -an explicit column reduction command, @kbd{V R : *}. - -@node Yanking Into Buffers, X Cut and Paste, Grabbing From Buffers, Kill and Yank -@section Yanking into Other Buffers - -@noindent -@kindex y -@pindex calc-copy-to-buffer -The plain @kbd{y} (@code{calc-copy-to-buffer}) command inserts the number -at the top of the stack into the most recently used normal editing buffer. -(More specifically, this is the most recently used buffer which is displayed -in a window and whose name does not begin with @samp{*}. If there is no -such buffer, this is the most recently used buffer except for Calculator -and Calc Trail buffers.) The number is inserted exactly as it appears and -without a newline. (If line-numbering is enabled, the line number is -normally not included.) The number is @emph{not} removed from the stack. - -With a prefix argument, @kbd{y} inserts several numbers, one per line. -A positive argument inserts the specified number of values from the top -of the stack. A negative argument inserts the @expr{n}th value from the -top of the stack. An argument of zero inserts the entire stack. Note -that @kbd{y} with an argument of 1 is slightly different from @kbd{y} -with no argument; the former always copies full lines, whereas the -latter strips off the trailing newline. - -With a lone @kbd{C-u} as a prefix argument, @kbd{y} @emph{replaces} the -region in the other buffer with the yanked text, then quits the -Calculator, leaving you in that buffer. A typical use would be to use -@kbd{C-x * g} to read a region of data into the Calculator, operate on the -data to produce a new matrix, then type @kbd{C-u y} to replace the -original data with the new data. One might wish to alter the matrix -display style (@pxref{Vector and Matrix Formats}) or change the current -display language (@pxref{Language Modes}) before doing this. Also, note -that this command replaces a linear region of text (as grabbed by -@kbd{C-x * g}), not a rectangle (as grabbed by @kbd{C-x * r}). - -If the editing buffer is in overwrite (as opposed to insert) mode, -and the @kbd{C-u} prefix was not used, then the yanked number will -overwrite the characters following point rather than being inserted -before those characters. The usual conventions of overwrite mode -are observed; for example, characters will be inserted at the end of -a line rather than overflowing onto the next line. Yanking a multi-line -object such as a matrix in overwrite mode overwrites the next @var{n} -lines in the buffer, lengthening or shortening each line as necessary. -Finally, if the thing being yanked is a simple integer or floating-point -number (like @samp{-1.2345e-3}) and the characters following point also -make up such a number, then Calc will replace that number with the new -number, lengthening or shortening as necessary. The concept of -``overwrite mode'' has thus been generalized from overwriting characters -to overwriting one complete number with another. - -@kindex C-x * y -The @kbd{C-x * y} key sequence is equivalent to @kbd{y} except that -it can be typed anywhere, not just in Calc. This provides an easy -way to guarantee that Calc knows which editing buffer you want to use! - -@node X Cut and Paste, , Yanking Into Buffers, Kill and Yank -@section X Cut and Paste - -@noindent -If you are using Emacs with the X window system, there is an easier -way to move small amounts of data into and out of the calculator: -Use the mouse-oriented cut and paste facilities of X. - -The default bindings for a three-button mouse cause the left button -to move the Emacs cursor to the given place, the right button to -select the text between the cursor and the clicked location, and -the middle button to yank the selection into the buffer at the -clicked location. So, if you have a Calc window and an editing -window on your Emacs screen, you can use left-click/right-click -to select a number, vector, or formula from one window, then -middle-click to paste that value into the other window. When you -paste text into the Calc window, Calc interprets it as an algebraic -entry. It doesn't matter where you click in the Calc window; the -new value is always pushed onto the top of the stack. - -The @code{xterm} program that is typically used for general-purpose -shell windows in X interprets the mouse buttons in the same way. -So you can use the mouse to move data between Calc and any other -Unix program. One nice feature of @code{xterm} is that a double -left-click selects one word, and a triple left-click selects a -whole line. So you can usually transfer a single number into Calc -just by double-clicking on it in the shell, then middle-clicking -in the Calc window. - -@node Keypad Mode, Embedded Mode, Kill and Yank, Top -@chapter Keypad Mode - -@noindent -@kindex C-x * k -@pindex calc-keypad -The @kbd{C-x * k} (@code{calc-keypad}) command starts the Calculator -and displays a picture of a calculator-style keypad. If you are using -the X window system, you can click on any of the ``keys'' in the -keypad using the left mouse button to operate the calculator. -The original window remains the selected window; in Keypad mode -you can type in your file while simultaneously performing -calculations with the mouse. - -@pindex full-calc-keypad -If you have used @kbd{C-x * b} first, @kbd{C-x * k} instead invokes -the @code{full-calc-keypad} command, which takes over the whole -Emacs screen and displays the keypad, the Calc stack, and the Calc -trail all at once. This mode would normally be used when running -Calc standalone (@pxref{Standalone Operation}). - -If you aren't using the X window system, you must switch into -the @samp{*Calc Keypad*} window, place the cursor on the desired -``key,'' and type @key{SPC} or @key{RET}. If you think this -is easier than using Calc normally, go right ahead. - -Calc commands are more or less the same in Keypad mode. Certain -keypad keys differ slightly from the corresponding normal Calc -keystrokes; all such deviations are described below. - -Keypad mode includes many more commands than will fit on the keypad -at once. Click the right mouse button [@code{calc-keypad-menu}] -to switch to the next menu. The bottom five rows of the keypad -stay the same; the top three rows change to a new set of commands. -To return to earlier menus, click the middle mouse button -[@code{calc-keypad-menu-back}] or simply advance through the menus -until you wrap around. Typing @key{TAB} inside the keypad window -is equivalent to clicking the right mouse button there. - -You can always click the @key{EXEC} button and type any normal -Calc key sequence. This is equivalent to switching into the -Calc buffer, typing the keys, then switching back to your -original buffer. - -@menu -* Keypad Main Menu:: -* Keypad Functions Menu:: -* Keypad Binary Menu:: -* Keypad Vectors Menu:: -* Keypad Modes Menu:: -@end menu - -@node Keypad Main Menu, Keypad Functions Menu, Keypad Mode, Keypad Mode -@section Main Menu - -@smallexample -@group -|----+----+--Calc---+----+----1 -|FLR |CEIL|RND |TRNC|CLN2|FLT | -|----+----+----+----+----+----| -| LN |EXP | |ABS |IDIV|MOD | -|----+----+----+----+----+----| -|SIN |COS |TAN |SQRT|y^x |1/x | -|----+----+----+----+----+----| -| ENTER |+/- |EEX |UNDO| <- | -|-----+---+-+--+--+-+---++----| -| INV | 7 | 8 | 9 | / | -|-----+-----+-----+-----+-----| -| HYP | 4 | 5 | 6 | * | -|-----+-----+-----+-----+-----| -|EXEC | 1 | 2 | 3 | - | -|-----+-----+-----+-----+-----| -| OFF | 0 | . | PI | + | -|-----+-----+-----+-----+-----+ -@end group -@end smallexample - -@noindent -This is the menu that appears the first time you start Keypad mode. -It will show up in a vertical window on the right side of your screen. -Above this menu is the traditional Calc stack display. On a 24-line -screen you will be able to see the top three stack entries. - -The ten digit keys, decimal point, and @key{EEX} key are used for -entering numbers in the obvious way. @key{EEX} begins entry of an -exponent in scientific notation. Just as with regular Calc, the -number is pushed onto the stack as soon as you press @key{ENTER} -or any other function key. - -The @key{+/-} key corresponds to normal Calc's @kbd{n} key. During -numeric entry it changes the sign of the number or of the exponent. -At other times it changes the sign of the number on the top of the -stack. - -The @key{INV} and @key{HYP} keys modify other keys. As well as -having the effects described elsewhere in this manual, Keypad mode -defines several other ``inverse'' operations. These are described -below and in the following sections. - -The @key{ENTER} key finishes the current numeric entry, or otherwise -duplicates the top entry on the stack. - -The @key{UNDO} key undoes the most recent Calc operation. -@kbd{INV UNDO} is the ``redo'' command, and @kbd{HYP UNDO} is -``last arguments'' (@kbd{M-@key{RET}}). - -The @key{<-} key acts as a ``backspace'' during numeric entry. -At other times it removes the top stack entry. @kbd{INV <-} -clears the entire stack. @kbd{HYP <-} takes an integer from -the stack, then removes that many additional stack elements. - -The @key{EXEC} key prompts you to enter any keystroke sequence -that would normally work in Calc mode. This can include a -numeric prefix if you wish. It is also possible simply to -switch into the Calc window and type commands in it; there is -nothing ``magic'' about this window when Keypad mode is active. - -The other keys in this display perform their obvious calculator -functions. @key{CLN2} rounds the top-of-stack by temporarily -reducing the precision by 2 digits. @key{FLT} converts an -integer or fraction on the top of the stack to floating-point. - -The @key{INV} and @key{HYP} keys combined with several of these keys -give you access to some common functions even if the appropriate menu -is not displayed. Obviously you don't need to learn these keys -unless you find yourself wasting time switching among the menus. - -@table @kbd -@item INV +/- -is the same as @key{1/x}. -@item INV + -is the same as @key{SQRT}. -@item INV - -is the same as @key{CONJ}. -@item INV * -is the same as @key{y^x}. -@item INV / -is the same as @key{INV y^x} (the @expr{x}th root of @expr{y}). -@item HYP/INV 1 -are the same as @key{SIN} / @kbd{INV SIN}. -@item HYP/INV 2 -are the same as @key{COS} / @kbd{INV COS}. -@item HYP/INV 3 -are the same as @key{TAN} / @kbd{INV TAN}. -@item INV/HYP 4 -are the same as @key{LN} / @kbd{HYP LN}. -@item INV/HYP 5 -are the same as @key{EXP} / @kbd{HYP EXP}. -@item INV 6 -is the same as @key{ABS}. -@item INV 7 -is the same as @key{RND} (@code{calc-round}). -@item INV 8 -is the same as @key{CLN2}. -@item INV 9 -is the same as @key{FLT} (@code{calc-float}). -@item INV 0 -is the same as @key{IMAG}. -@item INV . -is the same as @key{PREC}. -@item INV ENTER -is the same as @key{SWAP}. -@item HYP ENTER -is the same as @key{RLL3}. -@item INV HYP ENTER -is the same as @key{OVER}. -@item HYP +/- -packs the top two stack entries as an error form. -@item HYP EEX -packs the top two stack entries as a modulo form. -@item INV EEX -creates an interval form; this removes an integer which is one -of 0 @samp{[]}, 1 @samp{[)}, 2 @samp{(]} or 3 @samp{()}, followed -by the two limits of the interval. -@end table - -The @kbd{OFF} key turns Calc off; typing @kbd{C-x * k} or @kbd{C-x * *} -again has the same effect. This is analogous to typing @kbd{q} or -hitting @kbd{C-x * c} again in the normal calculator. If Calc is -running standalone (the @code{full-calc-keypad} command appeared in the -command line that started Emacs), then @kbd{OFF} is replaced with -@kbd{EXIT}; clicking on this actually exits Emacs itself. - -@node Keypad Functions Menu, Keypad Binary Menu, Keypad Main Menu, Keypad Mode -@section Functions Menu - -@smallexample -@group -|----+----+----+----+----+----2 -|IGAM|BETA|IBET|ERF |BESJ|BESY| -|----+----+----+----+----+----| -|IMAG|CONJ| RE |ATN2|RAND|RAGN| -|----+----+----+----+----+----| -|GCD |FACT|DFCT|BNOM|PERM|NXTP| -|----+----+----+----+----+----| -@end group -@end smallexample - -@noindent -This menu provides various operations from the @kbd{f} and @kbd{k} -prefix keys. - -@key{IMAG} multiplies the number on the stack by the imaginary -number @expr{i = (0, 1)}. - -@key{RE} extracts the real part a complex number. @kbd{INV RE} -extracts the imaginary part. - -@key{RAND} takes a number from the top of the stack and computes -a random number greater than or equal to zero but less than that -number. (@xref{Random Numbers}.) @key{RAGN} is the ``random -again'' command; it computes another random number using the -same limit as last time. - -@key{INV GCD} computes the LCM (least common multiple) function. - -@key{INV FACT} is the gamma function. -@texline @math{\Gamma(x) = (x-1)!}. -@infoline @expr{gamma(x) = (x-1)!}. - -@key{PERM} is the number-of-permutations function, which is on the -@kbd{H k c} key in normal Calc. - -@key{NXTP} finds the next prime after a number. @kbd{INV NXTP} -finds the previous prime. - -@node Keypad Binary Menu, Keypad Vectors Menu, Keypad Functions Menu, Keypad Mode -@section Binary Menu - -@smallexample -@group -|----+----+----+----+----+----3 -|AND | OR |XOR |NOT |LSH |RSH | -|----+----+----+----+----+----| -|DEC |HEX |OCT |BIN |WSIZ|ARSH| -|----+----+----+----+----+----| -| A | B | C | D | E | F | -|----+----+----+----+----+----| -@end group -@end smallexample - -@noindent -The keys in this menu perform operations on binary integers. -Note that both logical and arithmetic right-shifts are provided. -@key{INV LSH} rotates one bit to the left. - -The ``difference'' function (normally on @kbd{b d}) is on @key{INV AND}. -The ``clip'' function (normally on @w{@kbd{b c}}) is on @key{INV NOT}. - -The @key{DEC}, @key{HEX}, @key{OCT}, and @key{BIN} keys select the -current radix for display and entry of numbers: Decimal, hexadecimal, -octal, or binary. The six letter keys @key{A} through @key{F} are used -for entering hexadecimal numbers. - -The @key{WSIZ} key displays the current word size for binary operations -and allows you to enter a new word size. You can respond to the prompt -using either the keyboard or the digits and @key{ENTER} from the keypad. -The initial word size is 32 bits. - -@node Keypad Vectors Menu, Keypad Modes Menu, Keypad Binary Menu, Keypad Mode -@section Vectors Menu - -@smallexample -@group -|----+----+----+----+----+----4 -|SUM |PROD|MAX |MAP*|MAP^|MAP$| -|----+----+----+----+----+----| -|MINV|MDET|MTRN|IDNT|CRSS|"x" | -|----+----+----+----+----+----| -|PACK|UNPK|INDX|BLD |LEN |... | -|----+----+----+----+----+----| -@end group -@end smallexample - -@noindent -The keys in this menu operate on vectors and matrices. - -@key{PACK} removes an integer @var{n} from the top of the stack; -the next @var{n} stack elements are removed and packed into a vector, -which is replaced onto the stack. Thus the sequence -@kbd{1 ENTER 3 ENTER 5 ENTER 3 PACK} enters the vector -@samp{[1, 3, 5]} onto the stack. To enter a matrix, build each row -on the stack as a vector, then use a final @key{PACK} to collect the -rows into a matrix. - -@key{UNPK} unpacks the vector on the stack, pushing each of its -components separately. - -@key{INDX} removes an integer @var{n}, then builds a vector of -integers from 1 to @var{n}. @kbd{INV INDX} takes three numbers -from the stack: The vector size @var{n}, the starting number, -and the increment. @kbd{BLD} takes an integer @var{n} and any -value @var{x} and builds a vector of @var{n} copies of @var{x}. - -@key{IDNT} removes an integer @var{n}, then builds an @var{n}-by-@var{n} -identity matrix. - -@key{LEN} replaces a vector by its length, an integer. - -@key{...} turns on or off ``abbreviated'' display mode for large vectors. - -@key{MINV}, @key{MDET}, @key{MTRN}, and @key{CROSS} are the matrix -inverse, determinant, and transpose, and vector cross product. - -@key{SUM} replaces a vector by the sum of its elements. It is -equivalent to @kbd{u +} in normal Calc (@pxref{Statistical Operations}). -@key{PROD} computes the product of the elements of a vector, and -@key{MAX} computes the maximum of all the elements of a vector. - -@key{INV SUM} computes the alternating sum of the first element -minus the second, plus the third, minus the fourth, and so on. -@key{INV MAX} computes the minimum of the vector elements. - -@key{HYP SUM} computes the mean of the vector elements. -@key{HYP PROD} computes the sample standard deviation. -@key{HYP MAX} computes the median. - -@key{MAP*} multiplies two vectors elementwise. It is equivalent -to the @kbd{V M *} command. @key{MAP^} computes powers elementwise. -The arguments must be vectors of equal length, or one must be a vector -and the other must be a plain number. For example, @kbd{2 MAP^} squares -all the elements of a vector. - -@key{MAP$} maps the formula on the top of the stack across the -vector in the second-to-top position. If the formula contains -several variables, Calc takes that many vectors starting at the -second-to-top position and matches them to the variables in -alphabetical order. The result is a vector of the same size as -the input vectors, whose elements are the formula evaluated with -the variables set to the various sets of numbers in those vectors. -For example, you could simulate @key{MAP^} using @key{MAP$} with -the formula @samp{x^y}. - -The @kbd{"x"} key pushes the variable name @expr{x} onto the -stack. To build the formula @expr{x^2 + 6}, you would use the -key sequence @kbd{"x" 2 y^x 6 +}. This formula would then be -suitable for use with the @key{MAP$} key described above. -With @key{INV}, @key{HYP}, or @key{INV} and @key{HYP}, the -@kbd{"x"} key pushes the variable names @expr{y}, @expr{z}, and -@expr{t}, respectively. - -@node Keypad Modes Menu, , Keypad Vectors Menu, Keypad Mode -@section Modes Menu - -@smallexample -@group -|----+----+----+----+----+----5 -|FLT |FIX |SCI |ENG |GRP | | -|----+----+----+----+----+----| -|RAD |DEG |FRAC|POLR|SYMB|PREC| -|----+----+----+----+----+----| -|SWAP|RLL3|RLL4|OVER|STO |RCL | -|----+----+----+----+----+----| -@end group -@end smallexample - -@noindent -The keys in this menu manipulate modes, variables, and the stack. - -The @key{FLT}, @key{FIX}, @key{SCI}, and @key{ENG} keys select -floating-point, fixed-point, scientific, or engineering notation. -@key{FIX} displays two digits after the decimal by default; the -others display full precision. With the @key{INV} prefix, these -keys pop a number-of-digits argument from the stack. - -The @key{GRP} key turns grouping of digits with commas on or off. -@kbd{INV GRP} enables grouping to the right of the decimal point as -well as to the left. - -The @key{RAD} and @key{DEG} keys switch between radians and degrees -for trigonometric functions. - -The @key{FRAC} key turns Fraction mode on or off. This affects -whether commands like @kbd{/} with integer arguments produce -fractional or floating-point results. - -The @key{POLR} key turns Polar mode on or off, determining whether -polar or rectangular complex numbers are used by default. - -The @key{SYMB} key turns Symbolic mode on or off, in which -operations that would produce inexact floating-point results -are left unevaluated as algebraic formulas. - -The @key{PREC} key selects the current precision. Answer with -the keyboard or with the keypad digit and @key{ENTER} keys. - -The @key{SWAP} key exchanges the top two stack elements. -The @key{RLL3} key rotates the top three stack elements upwards. -The @key{RLL4} key rotates the top four stack elements upwards. -The @key{OVER} key duplicates the second-to-top stack element. - -The @key{STO} and @key{RCL} keys are analogous to @kbd{s t} and -@kbd{s r} in regular Calc. @xref{Store and Recall}. Click the -@key{STO} or @key{RCL} key, then one of the ten digits. (Named -variables are not available in Keypad mode.) You can also use, -for example, @kbd{STO + 3} to add to register 3. - -@node Embedded Mode, Programming, Keypad Mode, Top -@chapter Embedded Mode - -@noindent -Embedded mode in Calc provides an alternative to copying numbers -and formulas back and forth between editing buffers and the Calc -stack. In Embedded mode, your editing buffer becomes temporarily -linked to the stack and this copying is taken care of automatically. - -@menu -* Basic Embedded Mode:: -* More About Embedded Mode:: -* Assignments in Embedded Mode:: -* Mode Settings in Embedded Mode:: -* Customizing Embedded Mode:: -@end menu - -@node Basic Embedded Mode, More About Embedded Mode, Embedded Mode, Embedded Mode -@section Basic Embedded Mode - -@noindent -@kindex C-x * e -@pindex calc-embedded -To enter Embedded mode, position the Emacs point (cursor) on a -formula in any buffer and press @kbd{C-x * e} (@code{calc-embedded}). -Note that @kbd{C-x * e} is not to be used in the Calc stack buffer -like most Calc commands, but rather in regular editing buffers that -are visiting your own files. - -Calc will try to guess an appropriate language based on the major mode -of the editing buffer. (@xref{Language Modes}.) If the current buffer is -in @code{latex-mode}, for example, Calc will set its language to La@TeX{}. -Similarly, Calc will use @TeX{} language for @code{tex-mode}, -@code{plain-tex-mode} and @code{context-mode}, C language for -@code{c-mode} and @code{c++-mode}, FORTRAN language for -@code{fortran-mode} and @code{f90-mode}, Pascal for @code{pascal-mode}, -and eqn for @code{nroff-mode} (@pxref{Customizing Calc}). -These can be overridden with Calc's mode -changing commands (@pxref{Mode Settings in Embedded Mode}). If no -suitable language is available, Calc will continue with its current language. - -Calc normally scans backward and forward in the buffer for the -nearest opening and closing @dfn{formula delimiters}. The simplest -delimiters are blank lines. Other delimiters that Embedded mode -understands are: - -@enumerate -@item -The @TeX{} and La@TeX{} math delimiters @samp{$ $}, @samp{$$ $$}, -@samp{\[ \]}, and @samp{\( \)}; -@item -Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters); -@item -Lines beginning with @samp{@@} (Texinfo delimiters). -@item -Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters); -@item -Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else. -@end enumerate - -@xref{Customizing Embedded Mode}, to see how to make Calc recognize -your own favorite delimiters. Delimiters like @samp{$ $} can appear -on their own separate lines or in-line with the formula. - -If you give a positive or negative numeric prefix argument, Calc -instead uses the current point as one end of the formula, and includes -that many lines forward or backward (respectively, including the current -line). Explicit delimiters are not necessary in this case. - -With a prefix argument of zero, Calc uses the current region (delimited -by point and mark) instead of formula delimiters. With a prefix -argument of @kbd{C-u} only, Calc uses the current line as the formula. - -@kindex C-x * w -@pindex calc-embedded-word -The @kbd{C-x * w} (@code{calc-embedded-word}) command will start Embedded -mode on the current ``word''; in this case Calc will scan for the first -non-numeric character (i.e., the first character that is not a digit, -sign, decimal point, or upper- or lower-case @samp{e}) forward and -backward to delimit the formula. - -When you enable Embedded mode for a formula, Calc reads the text -between the delimiters and tries to interpret it as a Calc formula. -Calc can generally identify @TeX{} formulas and -Big-style formulas even if the language mode is wrong. If Calc -can't make sense of the formula, it beeps and refuses to enter -Embedded mode. But if the current language is wrong, Calc can -sometimes parse the formula successfully (but incorrectly); -for example, the C expression @samp{atan(a[1])} can be parsed -in Normal language mode, but the @code{atan} won't correspond to -the built-in @code{arctan} function, and the @samp{a[1]} will be -interpreted as @samp{a} times the vector @samp{[1]}! - -If you press @kbd{C-x * e} or @kbd{C-x * w} to activate an embedded -formula which is blank, say with the cursor on the space between -the two delimiters @samp{$ $}, Calc will immediately prompt for -an algebraic entry. - -Only one formula in one buffer can be enabled at a time. If you -move to another area of the current buffer and give Calc commands, -Calc turns Embedded mode off for the old formula and then tries -to restart Embedded mode at the new position. Other buffers are -not affected by Embedded mode. - -When Embedded mode begins, Calc pushes the current formula onto -the stack. No Calc stack window is created; however, Calc copies -the top-of-stack position into the original buffer at all times. -You can create a Calc window by hand with @kbd{C-x * o} if you -find you need to see the entire stack. - -For example, typing @kbd{C-x * e} while somewhere in the formula -@samp{n>2} in the following line enables Embedded mode on that -inequality: - -@example -We define $F_n = F_(n-1)+F_(n-2)$ for all $n>2$. -@end example - -@noindent -The formula @expr{n>2} will be pushed onto the Calc stack, and -the top of stack will be copied back into the editing buffer. -This means that spaces will appear around the @samp{>} symbol -to match Calc's usual display style: - -@example -We define $F_n = F_(n-1)+F_(n-2)$ for all $n > 2$. -@end example - -@noindent -No spaces have appeared around the @samp{+} sign because it's -in a different formula, one which we have not yet touched with -Embedded mode. - -Now that Embedded mode is enabled, keys you type in this buffer -are interpreted as Calc commands. At this point we might use -the ``commute'' command @kbd{j C} to reverse the inequality. -This is a selection-based command for which we first need to -move the cursor onto the operator (@samp{>} in this case) that -needs to be commuted. - -@example -We define $F_n = F_(n-1)+F_(n-2)$ for all $2 < n$. -@end example - -The @kbd{C-x * o} command is a useful way to open a Calc window -without actually selecting that window. Giving this command -verifies that @samp{2 < n} is also on the Calc stack. Typing -@kbd{17 @key{RET}} would produce: - -@example -We define $F_n = F_(n-1)+F_(n-2)$ for all $17$. -@end example - -@noindent -with @samp{2 < n} and @samp{17} on the stack; typing @key{TAB} -at this point will exchange the two stack values and restore -@samp{2 < n} to the embedded formula. Even though you can't -normally see the stack in Embedded mode, it is still there and -it still operates in the same way. But, as with old-fashioned -RPN calculators, you can only see the value at the top of the -stack at any given time (unless you use @kbd{C-x * o}). - -Typing @kbd{C-x * e} again turns Embedded mode off. The Calc -window reveals that the formula @w{@samp{2 < n}} is automatically -removed from the stack, but the @samp{17} is not. Entering -Embedded mode always pushes one thing onto the stack, and -leaving Embedded mode always removes one thing. Anything else -that happens on the stack is entirely your business as far as -Embedded mode is concerned. - -If you press @kbd{C-x * e} in the wrong place by accident, it is -possible that Calc will be able to parse the nearby text as a -formula and will mangle that text in an attempt to redisplay it -``properly'' in the current language mode. If this happens, -press @kbd{C-x * e} again to exit Embedded mode, then give the -regular Emacs ``undo'' command (@kbd{C-_} or @kbd{C-x u}) to put -the text back the way it was before Calc edited it. Note that Calc's -own Undo command (typed before you turn Embedded mode back off) -will not do you any good, because as far as Calc is concerned -you haven't done anything with this formula yet. - -@node More About Embedded Mode, Assignments in Embedded Mode, Basic Embedded Mode, Embedded Mode -@section More About Embedded Mode - -@noindent -When Embedded mode ``activates'' a formula, i.e., when it examines -the formula for the first time since the buffer was created or -loaded, Calc tries to sense the language in which the formula was -written. If the formula contains any La@TeX{}-like @samp{\} sequences, -it is parsed (i.e., read) in La@TeX{} mode. If the formula appears to -be written in multi-line Big mode, it is parsed in Big mode. Otherwise, -it is parsed according to the current language mode. - -Note that Calc does not change the current language mode according -the formula it reads in. Even though it can read a La@TeX{} formula when -not in La@TeX{} mode, it will immediately rewrite this formula using -whatever language mode is in effect. - -@tex -\bigskip -@end tex - -@kindex d p -@pindex calc-show-plain -Calc's parser is unable to read certain kinds of formulas. For -example, with @kbd{v ]} (@code{calc-matrix-brackets}) you can -specify matrix display styles which the parser is unable to -recognize as matrices. The @kbd{d p} (@code{calc-show-plain}) -command turns on a mode in which a ``plain'' version of a -formula is placed in front of the fully-formatted version. -When Calc reads a formula that has such a plain version in -front, it reads the plain version and ignores the formatted -version. - -Plain formulas are preceded and followed by @samp{%%%} signs -by default. This notation has the advantage that the @samp{%} -character begins a comment in @TeX{} and La@TeX{}, so if your formula is -embedded in a @TeX{} or La@TeX{} document its plain version will be -invisible in the final printed copy. Certain major modes have different -delimiters to ensure that the ``plain'' version will be -in a comment for those modes, also. -See @ref{Customizing Embedded Mode} to see how to change the ``plain'' -formula delimiters. - -There are several notations which Calc's parser for ``big'' -formatted formulas can't yet recognize. In particular, it can't -read the large symbols for @code{sum}, @code{prod}, and @code{integ}, -and it can't handle @samp{=>} with the righthand argument omitted. -Also, Calc won't recognize special formats you have defined with -the @kbd{Z C} command (@pxref{User-Defined Compositions}). In -these cases it is important to use ``plain'' mode to make sure -Calc will be able to read your formula later. - -Another example where ``plain'' mode is important is if you have -specified a float mode with few digits of precision. Normally -any digits that are computed but not displayed will simply be -lost when you save and re-load your embedded buffer, but ``plain'' -mode allows you to make sure that the complete number is present -in the file as well as the rounded-down number. - -@tex -\bigskip -@end tex - -Embedded buffers remember active formulas for as long as they -exist in Emacs memory. Suppose you have an embedded formula -which is @cpi{} to the normal 12 decimal places, and then -type @w{@kbd{C-u 5 d n}} to display only five decimal places. -If you then type @kbd{d n}, all 12 places reappear because the -full number is still there on the Calc stack. More surprisingly, -even if you exit Embedded mode and later re-enter it for that -formula, typing @kbd{d n} will restore all 12 places because -each buffer remembers all its active formulas. However, if you -save the buffer in a file and reload it in a new Emacs session, -all non-displayed digits will have been lost unless you used -``plain'' mode. - -@tex -\bigskip -@end tex - -In some applications of Embedded mode, you will want to have a -sequence of copies of a formula that show its evolution as you -work on it. For example, you might want to have a sequence -like this in your file (elaborating here on the example from -the ``Getting Started'' chapter): - -@smallexample -The derivative of - - ln(ln(x)) - -is - - @r{(the derivative of }ln(ln(x))@r{)} - -whose value at x = 2 is - - @r{(the value)} - -and at x = 3 is - - @r{(the value)} -@end smallexample - -@kindex C-x * d -@pindex calc-embedded-duplicate -The @kbd{C-x * d} (@code{calc-embedded-duplicate}) command is a -handy way to make sequences like this. If you type @kbd{C-x * d}, -the formula under the cursor (which may or may not have Embedded -mode enabled for it at the time) is copied immediately below and -Embedded mode is then enabled for that copy. - -For this example, you would start with just - -@smallexample -The derivative of - - ln(ln(x)) -@end smallexample - -@noindent -and press @kbd{C-x * d} with the cursor on this formula. The result -is - -@smallexample -The derivative of - - ln(ln(x)) - - - ln(ln(x)) -@end smallexample - -@noindent -with the second copy of the formula enabled in Embedded mode. -You can now press @kbd{a d x @key{RET}} to take the derivative, and -@kbd{C-x * d C-x * d} to make two more copies of the derivative. -To complete the computations, type @kbd{3 s l x @key{RET}} to evaluate -the last formula, then move up to the second-to-last formula -and type @kbd{2 s l x @key{RET}}. - -Finally, you would want to press @kbd{C-x * e} to exit Embedded -mode, then go up and insert the necessary text in between the -various formulas and numbers. - -@tex -\bigskip -@end tex - -@kindex C-x * f -@kindex C-x * ' -@pindex calc-embedded-new-formula -The @kbd{C-x * f} (@code{calc-embedded-new-formula}) command -creates a new embedded formula at the current point. It inserts -some default delimiters, which are usually just blank lines, -and then does an algebraic entry to get the formula (which is -then enabled for Embedded mode). This is just shorthand for -typing the delimiters yourself, positioning the cursor between -the new delimiters, and pressing @kbd{C-x * e}. The key sequence -@kbd{C-x * '} is equivalent to @kbd{C-x * f}. - -@kindex C-x * n -@kindex C-x * p -@pindex calc-embedded-next -@pindex calc-embedded-previous -The @kbd{C-x * n} (@code{calc-embedded-next}) and @kbd{C-x * p} -(@code{calc-embedded-previous}) commands move the cursor to the -next or previous active embedded formula in the buffer. They -can take positive or negative prefix arguments to move by several -formulas. Note that these commands do not actually examine the -text of the buffer looking for formulas; they only see formulas -which have previously been activated in Embedded mode. In fact, -@kbd{C-x * n} and @kbd{C-x * p} are a useful way to tell which -embedded formulas are currently active. Also, note that these -commands do not enable Embedded mode on the next or previous -formula, they just move the cursor. - -@kindex C-x * ` -@pindex calc-embedded-edit -The @kbd{C-x * `} (@code{calc-embedded-edit}) command edits the -embedded formula at the current point as if by @kbd{`} (@code{calc-edit}). -Embedded mode does not have to be enabled for this to work. Press -@kbd{C-c C-c} to finish the edit, or @kbd{C-x k} to cancel. - -@node Assignments in Embedded Mode, Mode Settings in Embedded Mode, More About Embedded Mode, Embedded Mode -@section Assignments in Embedded Mode - -@noindent -The @samp{:=} (assignment) and @samp{=>} (``evaluates-to'') operators -are especially useful in Embedded mode. They allow you to make -a definition in one formula, then refer to that definition in -other formulas embedded in the same buffer. - -An embedded formula which is an assignment to a variable, as in - -@example -foo := 5 -@end example - -@noindent -records @expr{5} as the stored value of @code{foo} for the -purposes of Embedded mode operations in the current buffer. It -does @emph{not} actually store @expr{5} as the ``global'' value -of @code{foo}, however. Regular Calc operations, and Embedded -formulas in other buffers, will not see this assignment. - -One way to use this assigned value is simply to create an -Embedded formula elsewhere that refers to @code{foo}, and to press -@kbd{=} in that formula. However, this permanently replaces the -@code{foo} in the formula with its current value. More interesting -is to use @samp{=>} elsewhere: - -@example -foo + 7 => 12 -@end example - -@xref{Evaluates-To Operator}, for a general discussion of @samp{=>}. - -If you move back and change the assignment to @code{foo}, any -@samp{=>} formulas which refer to it are automatically updated. - -@example -foo := 17 - -foo + 7 => 24 -@end example - -The obvious question then is, @emph{how} can one easily change the -assignment to @code{foo}? If you simply select the formula in -Embedded mode and type 17, the assignment itself will be replaced -by the 17. The effect on the other formula will be that the -variable @code{foo} becomes unassigned: - -@example -17 - -foo + 7 => foo + 7 -@end example - -The right thing to do is first to use a selection command (@kbd{j 2} -will do the trick) to select the righthand side of the assignment. -Then, @kbd{17 @key{TAB} @key{DEL}} will swap the 17 into place (@pxref{Selecting -Subformulas}, to see how this works). - -@kindex C-x * j -@pindex calc-embedded-select -The @kbd{C-x * j} (@code{calc-embedded-select}) command provides an -easy way to operate on assignments. It is just like @kbd{C-x * e}, -except that if the enabled formula is an assignment, it uses -@kbd{j 2} to select the righthand side. If the enabled formula -is an evaluates-to, it uses @kbd{j 1} to select the lefthand side. -A formula can also be a combination of both: - -@example -bar := foo + 3 => 20 -@end example - -@noindent -in which case @kbd{C-x * j} will select the middle part (@samp{foo + 3}). - -The formula is automatically deselected when you leave Embedded -mode. - -@kindex C-x * u -@pindex calc-embedded-update-formula -Another way to change the assignment to @code{foo} would simply be -to edit the number using regular Emacs editing rather than Embedded -mode. Then, we have to find a way to get Embedded mode to notice -the change. The @kbd{C-x * u} (@code{calc-embedded-update-formula}) -command is a convenient way to do this. - -@example -foo := 6 - -foo + 7 => 13 -@end example - -Pressing @kbd{C-x * u} is much like pressing @kbd{C-x * e = C-x * e}, that -is, temporarily enabling Embedded mode for the formula under the -cursor and then evaluating it with @kbd{=}. But @kbd{C-x * u} does -not actually use @kbd{C-x * e}, and in fact another formula somewhere -else can be enabled in Embedded mode while you use @kbd{C-x * u} and -that formula will not be disturbed. - -With a numeric prefix argument, @kbd{C-x * u} updates all active -@samp{=>} formulas in the buffer. Formulas which have not yet -been activated in Embedded mode, and formulas which do not have -@samp{=>} as their top-level operator, are not affected by this. -(This is useful only if you have used @kbd{m C}; see below.) - -With a plain @kbd{C-u} prefix, @kbd{C-u C-x * u} updates only in the -region between mark and point rather than in the whole buffer. - -@kbd{C-x * u} is also a handy way to activate a formula, such as an -@samp{=>} formula that has freshly been typed in or loaded from a -file. - -@kindex C-x * a -@pindex calc-embedded-activate -The @kbd{C-x * a} (@code{calc-embedded-activate}) command scans -through the current buffer and activates all embedded formulas -that contain @samp{:=} or @samp{=>} symbols. This does not mean -that Embedded mode is actually turned on, but only that the -formulas' positions are registered with Embedded mode so that -the @samp{=>} values can be properly updated as assignments are -changed. - -It is a good idea to type @kbd{C-x * a} right after loading a file -that uses embedded @samp{=>} operators. Emacs includes a nifty -``buffer-local variables'' feature that you can use to do this -automatically. The idea is to place near the end of your file -a few lines that look like this: - -@example ---- Local Variables: --- ---- eval:(calc-embedded-activate) --- ---- End: --- -@end example - -@noindent -where the leading and trailing @samp{---} can be replaced by -any suitable strings (which must be the same on all three lines) -or omitted altogether; in a @TeX{} or La@TeX{} file, @samp{%} would be a good -leading string and no trailing string would be necessary. In a -C program, @samp{/*} and @samp{*/} would be good leading and -trailing strings. - -When Emacs loads a file into memory, it checks for a Local Variables -section like this one at the end of the file. If it finds this -section, it does the specified things (in this case, running -@kbd{C-x * a} automatically) before editing of the file begins. -The Local Variables section must be within 3000 characters of the -end of the file for Emacs to find it, and it must be in the last -page of the file if the file has any page separators. -@xref{File Variables, , Local Variables in Files, emacs, the -Emacs manual}. - -Note that @kbd{C-x * a} does not update the formulas it finds. -To do this, type, say, @kbd{M-1 C-x * u} after @w{@kbd{C-x * a}}. -Generally this should not be a problem, though, because the -formulas will have been up-to-date already when the file was -saved. - -Normally, @kbd{C-x * a} activates all the formulas it finds, but -any previous active formulas remain active as well. With a -positive numeric prefix argument, @kbd{C-x * a} first deactivates -all current active formulas, then actives the ones it finds in -its scan of the buffer. With a negative prefix argument, -@kbd{C-x * a} simply deactivates all formulas. - -Embedded mode has two symbols, @samp{Active} and @samp{~Active}, -which it puts next to the major mode name in a buffer's mode line. -It puts @samp{Active} if it has reason to believe that all -formulas in the buffer are active, because you have typed @kbd{C-x * a} -and Calc has not since had to deactivate any formulas (which can -happen if Calc goes to update an @samp{=>} formula somewhere because -a variable changed, and finds that the formula is no longer there -due to some kind of editing outside of Embedded mode). Calc puts -@samp{~Active} in the mode line if some, but probably not all, -formulas in the buffer are active. This happens if you activate -a few formulas one at a time but never use @kbd{C-x * a}, or if you -used @kbd{C-x * a} but then Calc had to deactivate a formula -because it lost track of it. If neither of these symbols appears -in the mode line, no embedded formulas are active in the buffer -(e.g., before Embedded mode has been used, or after a @kbd{M-- C-x * a}). - -Embedded formulas can refer to assignments both before and after them -in the buffer. If there are several assignments to a variable, the -nearest preceding assignment is used if there is one, otherwise the -following assignment is used. - -@example -x => 1 - -x := 1 - -x => 1 - -x := 2 - -x => 2 -@end example - -As well as simple variables, you can also assign to subscript -expressions of the form @samp{@var{var}_@var{number}} (as in -@code{x_0}), or @samp{@var{var}_@var{var}} (as in @code{x_max}). -Assignments to other kinds of objects can be represented by Calc, -but the automatic linkage between assignments and references works -only for plain variables and these two kinds of subscript expressions. - -If there are no assignments to a given variable, the global -stored value for the variable is used (@pxref{Storing Variables}), -or, if no value is stored, the variable is left in symbolic form. -Note that global stored values will be lost when the file is saved -and loaded in a later Emacs session, unless you have used the -@kbd{s p} (@code{calc-permanent-variable}) command to save them; -@pxref{Operations on Variables}. - -The @kbd{m C} (@code{calc-auto-recompute}) command turns automatic -recomputation of @samp{=>} forms on and off. If you turn automatic -recomputation off, you will have to use @kbd{C-x * u} to update these -formulas manually after an assignment has been changed. If you -plan to change several assignments at once, it may be more efficient -to type @kbd{m C}, change all the assignments, then use @kbd{M-1 C-x * u} -to update the entire buffer afterwards. The @kbd{m C} command also -controls @samp{=>} formulas on the stack; @pxref{Evaluates-To -Operator}. When you turn automatic recomputation back on, the -stack will be updated but the Embedded buffer will not; you must -use @kbd{C-x * u} to update the buffer by hand. - -@node Mode Settings in Embedded Mode, Customizing Embedded Mode, Assignments in Embedded Mode, Embedded Mode -@section Mode Settings in Embedded Mode - -@kindex m e -@pindex calc-embedded-preserve-modes -@noindent -The mode settings can be changed while Calc is in embedded mode, but -by default they will revert to their original values when embedded mode -is ended. However, the modes saved when the mode-recording mode is -@code{Save} (see below) and the modes in effect when the @kbd{m e} -(@code{calc-embedded-preserve-modes}) command is given -will be preserved when embedded mode is ended. - -Embedded mode has a rather complicated mechanism for handling mode -settings in Embedded formulas. It is possible to put annotations -in the file that specify mode settings either global to the entire -file or local to a particular formula or formulas. In the latter -case, different modes can be specified for use when a formula -is the enabled Embedded mode formula. - -When you give any mode-setting command, like @kbd{m f} (for Fraction -mode) or @kbd{d s} (for scientific notation), Embedded mode adds -a line like the following one to the file just before the opening -delimiter of the formula. - -@example -% [calc-mode: fractions: t] -% [calc-mode: float-format: (sci 0)] -@end example - -When Calc interprets an embedded formula, it scans the text before -the formula for mode-setting annotations like these and sets the -Calc buffer to match these modes. Modes not explicitly described -in the file are not changed. Calc scans all the way to the top of -the file, or up to a line of the form - -@example -% [calc-defaults] -@end example - -@noindent -which you can insert at strategic places in the file if this backward -scan is getting too slow, or just to provide a barrier between one -``zone'' of mode settings and another. - -If the file contains several annotations for the same mode, the -closest one before the formula is used. Annotations after the -formula are never used (except for global annotations, described -below). - -The scan does not look for the leading @samp{% }, only for the -square brackets and the text they enclose. In fact, the leading -characters are different for different major modes. You can edit the -mode annotations to a style that works better in context if you wish. -@xref{Customizing Embedded Mode}, to see how to change the style -that Calc uses when it generates the annotations. You can write -mode annotations into the file yourself if you know the syntax; -the easiest way to find the syntax for a given mode is to let -Calc write the annotation for it once and see what it does. - -If you give a mode-changing command for a mode that already has -a suitable annotation just above the current formula, Calc will -modify that annotation rather than generating a new, conflicting -one. - -Mode annotations have three parts, separated by colons. (Spaces -after the colons are optional.) The first identifies the kind -of mode setting, the second is a name for the mode itself, and -the third is the value in the form of a Lisp symbol, number, -or list. Annotations with unrecognizable text in the first or -second parts are ignored. The third part is not checked to make -sure the value is of a valid type or range; if you write an -annotation by hand, be sure to give a proper value or results -will be unpredictable. Mode-setting annotations are case-sensitive. - -While Embedded mode is enabled, the word @code{Local} appears in -the mode line. This is to show that mode setting commands generate -annotations that are ``local'' to the current formula or set of -formulas. The @kbd{m R} (@code{calc-mode-record-mode}) command -causes Calc to generate different kinds of annotations. Pressing -@kbd{m R} repeatedly cycles through the possible modes. - -@code{LocEdit} and @code{LocPerm} modes generate annotations -that look like this, respectively: - -@example -% [calc-edit-mode: float-format: (sci 0)] -% [calc-perm-mode: float-format: (sci 5)] -@end example - -The first kind of annotation will be used only while a formula -is enabled in Embedded mode. The second kind will be used only -when the formula is @emph{not} enabled. (Whether the formula -is ``active'' or not, i.e., whether Calc has seen this formula -yet, is not relevant here.) - -@code{Global} mode generates an annotation like this at the end -of the file: - -@example -% [calc-global-mode: fractions t] -@end example - -Global mode annotations affect all formulas throughout the file, -and may appear anywhere in the file. This allows you to tuck your -mode annotations somewhere out of the way, say, on a new page of -the file, as long as those mode settings are suitable for all -formulas in the file. - -Enabling a formula with @kbd{C-x * e} causes a fresh scan for local -mode annotations; you will have to use this after adding annotations -above a formula by hand to get the formula to notice them. Updating -a formula with @kbd{C-x * u} will also re-scan the local modes, but -global modes are only re-scanned by @kbd{C-x * a}. - -Another way that modes can get out of date is if you add a local -mode annotation to a formula that has another formula after it. -In this example, we have used the @kbd{d s} command while the -first of the two embedded formulas is active. But the second -formula has not changed its style to match, even though by the -rules of reading annotations the @samp{(sci 0)} applies to it, too. - -@example -% [calc-mode: float-format: (sci 0)] -1.23e2 - -456. -@end example - -We would have to go down to the other formula and press @kbd{C-x * u} -on it in order to get it to notice the new annotation. - -Two more mode-recording modes selectable by @kbd{m R} are available -which are also available outside of Embedded mode. -(@pxref{General Mode Commands}.) They are @code{Save}, in which mode -settings are recorded permanently in your Calc init file (the file given -by the variable @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}) -rather than by annotating the current document, and no-recording -mode (where there is no symbol like @code{Save} or @code{Local} in -the mode line), in which mode-changing commands do not leave any -annotations at all. - -When Embedded mode is not enabled, mode-recording modes except -for @code{Save} have no effect. - -@node Customizing Embedded Mode, , Mode Settings in Embedded Mode, Embedded Mode -@section Customizing Embedded Mode - -@noindent -You can modify Embedded mode's behavior by setting various Lisp -variables described here. These variables are customizable -(@pxref{Customizing Calc}), or you can use @kbd{M-x set-variable} -or @kbd{M-x edit-options} to adjust a variable on the fly. -(Another possibility would be to use a file-local variable annotation at -the end of the file; -@pxref{File Variables, , Local Variables in Files, emacs, the Emacs manual}.) -Many of the variables given mentioned here can be set to depend on the -major mode of the editing buffer (@pxref{Customizing Calc}). - -@vindex calc-embedded-open-formula -The @code{calc-embedded-open-formula} variable holds a regular -expression for the opening delimiter of a formula. @xref{Regexp Search, -, Regular Expression Search, emacs, the Emacs manual}, to see -how regular expressions work. Basically, a regular expression is a -pattern that Calc can search for. A regular expression that considers -blank lines, @samp{$}, and @samp{$$} to be opening delimiters is -@code{"\\`\\|^\n\\|\\$\\$?"}. Just in case the meaning of this -regular expression is not completely plain, let's go through it -in detail. - -The surrounding @samp{" "} marks quote the text between them as a -Lisp string. If you left them off, @code{set-variable} or -@code{edit-options} would try to read the regular expression as a -Lisp program. - -The most obvious property of this regular expression is that it -contains indecently many backslashes. There are actually two levels -of backslash usage going on here. First, when Lisp reads a quoted -string, all pairs of characters beginning with a backslash are -interpreted as special characters. Here, @code{\n} changes to a -new-line character, and @code{\\} changes to a single backslash. -So the actual regular expression seen by Calc is -@samp{\`\|^ @r{(newline)} \|\$\$?}. - -Regular expressions also consider pairs beginning with backslash -to have special meanings. Sometimes the backslash is used to quote -a character that otherwise would have a special meaning in a regular -expression, like @samp{$}, which normally means ``end-of-line,'' -or @samp{?}, which means that the preceding item is optional. So -@samp{\$\$?} matches either one or two dollar signs. - -The other codes in this regular expression are @samp{^}, which matches -``beginning-of-line,'' @samp{\|}, which means ``or,'' and @samp{\`}, -which matches ``beginning-of-buffer.'' So the whole pattern means -that a formula begins at the beginning of the buffer, or on a newline -that occurs at the beginning of a line (i.e., a blank line), or at -one or two dollar signs. - -The default value of @code{calc-embedded-open-formula} looks just -like this example, with several more alternatives added on to -recognize various other common kinds of delimiters. - -By the way, the reason to use @samp{^\n} rather than @samp{^$} -or @samp{\n\n}, which also would appear to match blank lines, -is that the former expression actually ``consumes'' only one -newline character as @emph{part of} the delimiter, whereas the -latter expressions consume zero or two newlines, respectively. -The former choice gives the most natural behavior when Calc -must operate on a whole formula including its delimiters. - -See the Emacs manual for complete details on regular expressions. -But just for your convenience, here is a list of all characters -which must be quoted with backslash (like @samp{\$}) to avoid -some special interpretation: @samp{. * + ? [ ] ^ $ \}. (Note -the backslash in this list; for example, to match @samp{\[} you -must use @code{"\\\\\\["}. An exercise for the reader is to -account for each of these six backslashes!) - -@vindex calc-embedded-close-formula -The @code{calc-embedded-close-formula} variable holds a regular -expression for the closing delimiter of a formula. A closing -regular expression to match the above example would be -@code{"\\'\\|\n$\\|\\$\\$?"}. This is almost the same as the -other one, except it now uses @samp{\'} (``end-of-buffer'') and -@samp{\n$} (newline occurring at end of line, yet another way -of describing a blank line that is more appropriate for this -case). - -@vindex calc-embedded-word-regexp -The @code{calc-embedded-word-regexp} variable holds a regular expression -used to define an expression to look for (a ``word'') when you type -@kbd{C-x * w} to enable Embedded mode. - -@vindex calc-embedded-open-plain -The @code{calc-embedded-open-plain} variable is a string which -begins a ``plain'' formula written in front of the formatted -formula when @kbd{d p} mode is turned on. Note that this is an -actual string, not a regular expression, because Calc must be able -to write this string into a buffer as well as to recognize it. -The default string is @code{"%%% "} (note the trailing space), but may -be different for certain major modes. - -@vindex calc-embedded-close-plain -The @code{calc-embedded-close-plain} variable is a string which -ends a ``plain'' formula. The default is @code{" %%%\n"}, but may be -different for different major modes. Without -the trailing newline here, the first line of a Big mode formula -that followed might be shifted over with respect to the other lines. - -@vindex calc-embedded-open-new-formula -The @code{calc-embedded-open-new-formula} variable is a string -which is inserted at the front of a new formula when you type -@kbd{C-x * f}. Its default value is @code{"\n\n"}. If this -string begins with a newline character and the @kbd{C-x * f} is -typed at the beginning of a line, @kbd{C-x * f} will skip this -first newline to avoid introducing unnecessary blank lines in -the file. - -@vindex calc-embedded-close-new-formula -The @code{calc-embedded-close-new-formula} variable is the corresponding -string which is inserted at the end of a new formula. Its default -value is also @code{"\n\n"}. The final newline is omitted by -@w{@kbd{C-x * f}} if typed at the end of a line. (It follows that if -@kbd{C-x * f} is typed on a blank line, both a leading opening -newline and a trailing closing newline are omitted.) - -@vindex calc-embedded-announce-formula -The @code{calc-embedded-announce-formula} variable is a regular -expression which is sure to be followed by an embedded formula. -The @kbd{C-x * a} command searches for this pattern as well as for -@samp{=>} and @samp{:=} operators. Note that @kbd{C-x * a} will -not activate just anything surrounded by formula delimiters; after -all, blank lines are considered formula delimiters by default! -But if your language includes a delimiter which can only occur -actually in front of a formula, you can take advantage of it here. -The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, but may be -different for different major modes. -This pattern will check for @samp{%Embed} followed by any number of -lines beginning with @samp{%} and a space. This last is important to -make Calc consider mode annotations part of the pattern, so that the -formula's opening delimiter really is sure to follow the pattern. - -@vindex calc-embedded-open-mode -The @code{calc-embedded-open-mode} variable is a string (not a -regular expression) which should precede a mode annotation. -Calc never scans for this string; Calc always looks for the -annotation itself. But this is the string that is inserted before -the opening bracket when Calc adds an annotation on its own. -The default is @code{"% "}, but may be different for different major -modes. - -@vindex calc-embedded-close-mode -The @code{calc-embedded-close-mode} variable is a string which -follows a mode annotation written by Calc. Its default value -is simply a newline, @code{"\n"}, but may be different for different -major modes. If you change this, it is a good idea still to end with a -newline so that mode annotations will appear on lines by themselves. - -@node Programming, Copying, Embedded Mode, Top -@chapter Programming - -@noindent -There are several ways to ``program'' the Emacs Calculator, depending -on the nature of the problem you need to solve. - -@enumerate -@item -@dfn{Keyboard macros} allow you to record a sequence of keystrokes -and play them back at a later time. This is just the standard Emacs -keyboard macro mechanism, dressed up with a few more features such -as loops and conditionals. - -@item -@dfn{Algebraic definitions} allow you to use any formula to define a -new function. This function can then be used in algebraic formulas or -as an interactive command. - -@item -@dfn{Rewrite rules} are discussed in the section on algebra commands. -@xref{Rewrite Rules}. If you put your rewrite rules in the variable -@code{EvalRules}, they will be applied automatically to all Calc -results in just the same way as an internal ``rule'' is applied to -evaluate @samp{sqrt(9)} to 3 and so on. @xref{Automatic Rewrites}. - -@item -@dfn{Lisp} is the programming language that Calc (and most of Emacs) -is written in. If the above techniques aren't powerful enough, you -can write Lisp functions to do anything that built-in Calc commands -can do. Lisp code is also somewhat faster than keyboard macros or -rewrite rules. -@end enumerate - -@kindex z -Programming features are available through the @kbd{z} and @kbd{Z} -prefix keys. New commands that you define are two-key sequences -beginning with @kbd{z}. Commands for managing these definitions -use the shift-@kbd{Z} prefix. (The @kbd{Z T} (@code{calc-timing}) -command is described elsewhere; @pxref{Troubleshooting Commands}. -The @kbd{Z C} (@code{calc-user-define-composition}) command is also -described elsewhere; @pxref{User-Defined Compositions}.) - -@menu -* Creating User Keys:: -* Keyboard Macros:: -* Invocation Macros:: -* Algebraic Definitions:: -* Lisp Definitions:: -@end menu - -@node Creating User Keys, Keyboard Macros, Programming, Programming -@section Creating User Keys - -@noindent -@kindex Z D -@pindex calc-user-define -Any Calculator command may be bound to a key using the @kbd{Z D} -(@code{calc-user-define}) command. Actually, it is bound to a two-key -sequence beginning with the lower-case @kbd{z} prefix. - -The @kbd{Z D} command first prompts for the key to define. For example, -press @kbd{Z D a} to define the new key sequence @kbd{z a}. You are then -prompted for the name of the Calculator command that this key should -run. For example, the @code{calc-sincos} command is not normally -available on a key. Typing @kbd{Z D s sincos @key{RET}} programs the -@kbd{z s} key sequence to run @code{calc-sincos}. This definition will remain -in effect for the rest of this Emacs session, or until you redefine -@kbd{z s} to be something else. - -You can actually bind any Emacs command to a @kbd{z} key sequence by -backspacing over the @samp{calc-} when you are prompted for the command name. - -As with any other prefix key, you can type @kbd{z ?} to see a list of -all the two-key sequences you have defined that start with @kbd{z}. -Initially, no @kbd{z} sequences (except @kbd{z ?} itself) are defined. - -User keys are typically letters, but may in fact be any key. -(@key{META}-keys are not permitted, nor are a terminal's special -function keys which generate multi-character sequences when pressed.) -You can define different commands on the shifted and unshifted versions -of a letter if you wish. - -@kindex Z U -@pindex calc-user-undefine -The @kbd{Z U} (@code{calc-user-undefine}) command unbinds a user key. -For example, the key sequence @kbd{Z U s} will undefine the @code{sincos} -key we defined above. - -@kindex Z P -@pindex calc-user-define-permanent -@cindex Storing user definitions -@cindex Permanent user definitions -@cindex Calc init file, user-defined commands -The @kbd{Z P} (@code{calc-user-define-permanent}) command makes a key -binding permanent so that it will remain in effect even in future Emacs -sessions. (It does this by adding a suitable bit of Lisp code into -your Calc init file; that is, the file given by the variable -@code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}.) For example, -@kbd{Z P s} would register our @code{sincos} command permanently. If -you later wish to unregister this command you must edit your Calc init -file by hand. (@xref{General Mode Commands}, for a way to tell Calc to -use a different file for the Calc init file.) - -The @kbd{Z P} command also saves the user definition, if any, for the -command bound to the key. After @kbd{Z F} and @kbd{Z C}, a given user -key could invoke a command, which in turn calls an algebraic function, -which might have one or more special display formats. A single @kbd{Z P} -command will save all of these definitions. -To save an algebraic function, type @kbd{'} (the apostrophe) -when prompted for a key, and type the function name. To save a command -without its key binding, type @kbd{M-x} and enter a function name. (The -@samp{calc-} prefix will automatically be inserted for you.) -(If the command you give implies a function, the function will be saved, -and if the function has any display formats, those will be saved, but -not the other way around: Saving a function will not save any commands -or key bindings associated with the function.) - -@kindex Z E -@pindex calc-user-define-edit -@cindex Editing user definitions -The @kbd{Z E} (@code{calc-user-define-edit}) command edits the definition -of a user key. This works for keys that have been defined by either -keyboard macros or formulas; further details are contained in the relevant -following sections. - -@node Keyboard Macros, Invocation Macros, Creating User Keys, Programming -@section Programming with Keyboard Macros - -@noindent -@kindex X -@cindex Programming with keyboard macros -@cindex Keyboard macros -The easiest way to ``program'' the Emacs Calculator is to use standard -keyboard macros. Press @w{@kbd{C-x (}} to begin recording a macro. From -this point on, keystrokes you type will be saved away as well as -performing their usual functions. Press @kbd{C-x )} to end recording. -Press shift-@kbd{X} (or the standard Emacs key sequence @kbd{C-x e}) to -execute your keyboard macro by replaying the recorded keystrokes. -@xref{Keyboard Macros, , , emacs, the Emacs Manual}, for further -information. - -When you use @kbd{X} to invoke a keyboard macro, the entire macro is -treated as a single command by the undo and trail features. The stack -display buffer is not updated during macro execution, but is instead -fixed up once the macro completes. Thus, commands defined with keyboard -macros are convenient and efficient. The @kbd{C-x e} command, on the -other hand, invokes the keyboard macro with no special treatment: Each -command in the macro will record its own undo information and trail entry, -and update the stack buffer accordingly. If your macro uses features -outside of Calc's control to operate on the contents of the Calc stack -buffer, or if it includes Undo, Redo, or last-arguments commands, you -must use @kbd{C-x e} to make sure the buffer and undo list are up-to-date -at all times. You could also consider using @kbd{K} (@code{calc-keep-args}) -instead of @kbd{M-@key{RET}} (@code{calc-last-args}). - -Calc extends the standard Emacs keyboard macros in several ways. -Keyboard macros can be used to create user-defined commands. Keyboard -macros can include conditional and iteration structures, somewhat -analogous to those provided by a traditional programmable calculator. - -@menu -* Naming Keyboard Macros:: -* Conditionals in Macros:: -* Loops in Macros:: -* Local Values in Macros:: -* Queries in Macros:: -@end menu - -@node Naming Keyboard Macros, Conditionals in Macros, Keyboard Macros, Keyboard Macros -@subsection Naming Keyboard Macros - -@noindent -@kindex Z K -@pindex calc-user-define-kbd-macro -Once you have defined a keyboard macro, you can bind it to a @kbd{z} -key sequence with the @kbd{Z K} (@code{calc-user-define-kbd-macro}) command. -This command prompts first for a key, then for a command name. For -example, if you type @kbd{C-x ( n @key{TAB} n @key{TAB} C-x )} you will -define a keyboard macro which negates the top two numbers on the stack -(@key{TAB} swaps the top two stack elements). Now you can type -@kbd{Z K n @key{RET}} to define this keyboard macro onto the @kbd{z n} key -sequence. The default command name (if you answer the second prompt with -just the @key{RET} key as in this example) will be something like -@samp{calc-User-n}. The keyboard macro will now be available as both -@kbd{z n} and @kbd{M-x calc-User-n}. You can backspace and enter a more -descriptive command name if you wish. - -Macros defined by @kbd{Z K} act like single commands; they are executed -in the same way as by the @kbd{X} key. If you wish to define the macro -as a standard no-frills Emacs macro (to be executed as if by @kbd{C-x e}), -give a negative prefix argument to @kbd{Z K}. - -Once you have bound your keyboard macro to a key, you can use -@kbd{Z P} to register it permanently with Emacs. @xref{Creating User Keys}. - -@cindex Keyboard macros, editing -The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has -been defined by a keyboard macro tries to use the @code{edmacro} package -edit the macro. Type @kbd{C-c C-c} to finish editing and update -the definition stored on the key, or, to cancel the edit, kill the -buffer with @kbd{C-x k}. -The special characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, -@code{DEL}, and @code{NUL} must be entered as these three character -sequences, written in all uppercase, as must the prefixes @code{C-} and -@code{M-}. Spaces and line breaks are ignored. Other characters are -copied verbatim into the keyboard macro. Basically, the notation is the -same as is used in all of this manual's examples, except that the manual -takes some liberties with spaces: When we say @kbd{' [1 2 3] @key{RET}}, -we take it for granted that it is clear we really mean -@kbd{' [1 @key{SPC} 2 @key{SPC} 3] @key{RET}}. - -@kindex C-x * m -@pindex read-kbd-macro -The @kbd{C-x * m} (@code{read-kbd-macro}) command reads an Emacs ``region'' -of spelled-out keystrokes and defines it as the current keyboard macro. -It is a convenient way to define a keyboard macro that has been stored -in a file, or to define a macro without executing it at the same time. - -@node Conditionals in Macros, Loops in Macros, Naming Keyboard Macros, Keyboard Macros -@subsection Conditionals in Keyboard Macros - -@noindent -@kindex Z [ -@kindex Z ] -@pindex calc-kbd-if -@pindex calc-kbd-else -@pindex calc-kbd-else-if -@pindex calc-kbd-end-if -@cindex Conditional structures -The @kbd{Z [} (@code{calc-kbd-if}) and @kbd{Z ]} (@code{calc-kbd-end-if}) -commands allow you to put simple tests in a keyboard macro. When Calc -sees the @kbd{Z [}, it pops an object from the stack and, if the object is -a non-zero value, continues executing keystrokes. But if the object is -zero, or if it is not provably nonzero, Calc skips ahead to the matching -@kbd{Z ]} keystroke. @xref{Logical Operations}, for a set of commands for -performing tests which conveniently produce 1 for true and 0 for false. - -For example, @kbd{@key{RET} 0 a < Z [ n Z ]} implements an absolute-value -function in the form of a keyboard macro. This macro duplicates the -number on the top of the stack, pushes zero and compares using @kbd{a <} -(@code{calc-less-than}), then, if the number was less than zero, -executes @kbd{n} (@code{calc-change-sign}). Otherwise, the change-sign -command is skipped. - -To program this macro, type @kbd{C-x (}, type the above sequence of -keystrokes, then type @kbd{C-x )}. Note that the keystrokes will be -executed while you are making the definition as well as when you later -re-execute the macro by typing @kbd{X}. Thus you should make sure a -suitable number is on the stack before defining the macro so that you -don't get a stack-underflow error during the definition process. - -Conditionals can be nested arbitrarily. However, there should be exactly -one @kbd{Z ]} for each @kbd{Z [} in a keyboard macro. - -@kindex Z : -The @kbd{Z :} (@code{calc-kbd-else}) command allows you to choose between -two keystroke sequences. The general format is @kbd{@var{cond} Z [ -@var{then-part} Z : @var{else-part} Z ]}. If @var{cond} is true -(i.e., if the top of stack contains a non-zero number after @var{cond} -has been executed), the @var{then-part} will be executed and the -@var{else-part} will be skipped. Otherwise, the @var{then-part} will -be skipped and the @var{else-part} will be executed. - -@kindex Z | -The @kbd{Z |} (@code{calc-kbd-else-if}) command allows you to choose -between any number of alternatives. For example, -@kbd{@var{cond1} Z [ @var{part1} Z : @var{cond2} Z | @var{part2} Z : -@var{part3} Z ]} will execute @var{part1} if @var{cond1} is true, -otherwise it will execute @var{part2} if @var{cond2} is true, otherwise -it will execute @var{part3}. - -More precisely, @kbd{Z [} pops a number and conditionally skips to the -next matching @kbd{Z :} or @kbd{Z ]} key. @w{@kbd{Z ]}} has no effect when -actually executed. @kbd{Z :} skips to the next matching @kbd{Z ]}. -@kbd{Z |} pops a number and conditionally skips to the next matching -@kbd{Z :} or @kbd{Z ]}; thus, @kbd{Z [} and @kbd{Z |} are functionally -equivalent except that @kbd{Z [} participates in nesting but @kbd{Z |} -does not. - -Calc's conditional and looping constructs work by scanning the -keyboard macro for occurrences of character sequences like @samp{Z:} -and @samp{Z]}. One side-effect of this is that if you use these -constructs you must be careful that these character pairs do not -occur by accident in other parts of the macros. Since Calc rarely -uses shift-@kbd{Z} for any purpose except as a prefix character, this -is not likely to be a problem. Another side-effect is that it will -not work to define your own custom key bindings for these commands. -Only the standard shift-@kbd{Z} bindings will work correctly. - -@kindex Z C-g -If Calc gets stuck while skipping characters during the definition of a -macro, type @kbd{Z C-g} to cancel the definition. (Typing plain @kbd{C-g} -actually adds a @kbd{C-g} keystroke to the macro.) - -@node Loops in Macros, Local Values in Macros, Conditionals in Macros, Keyboard Macros -@subsection Loops in Keyboard Macros - -@noindent -@kindex Z < -@kindex Z > -@pindex calc-kbd-repeat -@pindex calc-kbd-end-repeat -@cindex Looping structures -@cindex Iterative structures -The @kbd{Z <} (@code{calc-kbd-repeat}) and @kbd{Z >} -(@code{calc-kbd-end-repeat}) commands pop a number from the stack, -which must be an integer, then repeat the keystrokes between the brackets -the specified number of times. If the integer is zero or negative, the -body is skipped altogether. For example, @kbd{1 @key{TAB} Z < 2 * Z >} -computes two to a nonnegative integer power. First, we push 1 on the -stack and then swap the integer argument back to the top. The @kbd{Z <} -pops that argument leaving the 1 back on top of the stack. Then, we -repeat a multiply-by-two step however many times. - -Once again, the keyboard macro is executed as it is being entered. -In this case it is especially important to set up reasonable initial -conditions before making the definition: Suppose the integer 1000 just -happened to be sitting on the stack before we typed the above definition! -Another approach is to enter a harmless dummy definition for the macro, -then go back and edit in the real one with a @kbd{Z E} command. Yet -another approach is to type the macro as written-out keystroke names -in a buffer, then use @kbd{C-x * m} (@code{read-kbd-macro}) to read the -macro. - -@kindex Z / -@pindex calc-break -The @kbd{Z /} (@code{calc-kbd-break}) command allows you to break out -of a keyboard macro loop prematurely. It pops an object from the stack; -if that object is true (a non-zero number), control jumps out of the -innermost enclosing @kbd{Z <} @dots{} @kbd{Z >} loop and continues -after the @kbd{Z >}. If the object is false, the @kbd{Z /} has no -effect. Thus @kbd{@var{cond} Z /} is similar to @samp{if (@var{cond}) break;} -in the C language. - -@kindex Z ( -@kindex Z ) -@pindex calc-kbd-for -@pindex calc-kbd-end-for -The @kbd{Z (} (@code{calc-kbd-for}) and @kbd{Z )} (@code{calc-kbd-end-for}) -commands are similar to @kbd{Z <} and @kbd{Z >}, except that they make the -value of the counter available inside the loop. The general layout is -@kbd{@var{init} @var{final} Z ( @var{body} @var{step} Z )}. The @kbd{Z (} -command pops initial and final values from the stack. It then creates -a temporary internal counter and initializes it with the value @var{init}. -The @kbd{Z (} command then repeatedly pushes the counter value onto the -stack and executes @var{body} and @var{step}, adding @var{step} to the -counter each time until the loop finishes. - -@cindex Summations (by keyboard macros) -By default, the loop finishes when the counter becomes greater than (or -less than) @var{final}, assuming @var{initial} is less than (greater -than) @var{final}. If @var{initial} is equal to @var{final}, the body -executes exactly once. The body of the loop always executes at least -once. For example, @kbd{0 1 10 Z ( 2 ^ + 1 Z )} computes the sum of the -squares of the integers from 1 to 10, in steps of 1. - -If you give a numeric prefix argument of 1 to @kbd{Z (}, the loop is -forced to use upward-counting conventions. In this case, if @var{initial} -is greater than @var{final} the body will not be executed at all. -Note that @var{step} may still be negative in this loop; the prefix -argument merely constrains the loop-finished test. Likewise, a prefix -argument of @mathit{-1} forces downward-counting conventions. - -@kindex Z @{ -@kindex Z @} -@pindex calc-kbd-loop -@pindex calc-kbd-end-loop -The @kbd{Z @{} (@code{calc-kbd-loop}) and @kbd{Z @}} -(@code{calc-kbd-end-loop}) commands are similar to @kbd{Z <} and -@kbd{Z >}, except that they do not pop a count from the stack---they -effectively create an infinite loop. Every @kbd{Z @{} @dots{} @kbd{Z @}} -loop ought to include at least one @kbd{Z /} to make sure the loop -doesn't run forever. (If any error message occurs which causes Emacs -to beep, the keyboard macro will also be halted; this is a standard -feature of Emacs. You can also generally press @kbd{C-g} to halt a -running keyboard macro, although not all versions of Unix support -this feature.) - -The conditional and looping constructs are not actually tied to -keyboard macros, but they are most often used in that context. -For example, the keystrokes @kbd{10 Z < 23 @key{RET} Z >} push -ten copies of 23 onto the stack. This can be typed ``live'' just -as easily as in a macro definition. - -@xref{Conditionals in Macros}, for some additional notes about -conditional and looping commands. - -@node Local Values in Macros, Queries in Macros, Loops in Macros, Keyboard Macros -@subsection Local Values in Macros - -@noindent -@cindex Local variables -@cindex Restoring saved modes -Keyboard macros sometimes want to operate under known conditions -without affecting surrounding conditions. For example, a keyboard -macro may wish to turn on Fraction mode, or set a particular -precision, independent of the user's normal setting for those -modes. - -@kindex Z ` -@kindex Z ' -@pindex calc-kbd-push -@pindex calc-kbd-pop -Macros also sometimes need to use local variables. Assignments to -local variables inside the macro should not affect any variables -outside the macro. The @kbd{Z `} (@code{calc-kbd-push}) and @kbd{Z '} -(@code{calc-kbd-pop}) commands give you both of these capabilities. - -When you type @kbd{Z `} (with a backquote or accent grave character), -the values of various mode settings are saved away. The ten ``quick'' -variables @code{q0} through @code{q9} are also saved. When -you type @w{@kbd{Z '}} (with an apostrophe), these values are restored. -Pairs of @kbd{Z `} and @kbd{Z '} commands may be nested. - -If a keyboard macro halts due to an error in between a @kbd{Z `} and -a @kbd{Z '}, the saved values will be restored correctly even though -the macro never reaches the @kbd{Z '} command. Thus you can use -@kbd{Z `} and @kbd{Z '} without having to worry about what happens -in exceptional conditions. - -If you type @kbd{Z `} ``live'' (not in a keyboard macro), Calc puts -you into a ``recursive edit.'' You can tell you are in a recursive -edit because there will be extra square brackets in the mode line, -as in @samp{[(Calculator)]}. These brackets will go away when you -type the matching @kbd{Z '} command. The modes and quick variables -will be saved and restored in just the same way as if actual keyboard -macros were involved. - -The modes saved by @kbd{Z `} and @kbd{Z '} are the current precision -and binary word size, the angular mode (Deg, Rad, or HMS), the -simplification mode, Algebraic mode, Symbolic mode, Infinite mode, -Matrix or Scalar mode, Fraction mode, and the current complex mode -(Polar or Rectangular). The ten ``quick'' variables' values (or lack -thereof) are also saved. - -Most mode-setting commands act as toggles, but with a numeric prefix -they force the mode either on (positive prefix) or off (negative -or zero prefix). Since you don't know what the environment might -be when you invoke your macro, it's best to use prefix arguments -for all mode-setting commands inside the macro. - -In fact, @kbd{C-u Z `} is like @kbd{Z `} except that it sets the modes -listed above to their default values. As usual, the matching @kbd{Z '} -will restore the modes to their settings from before the @kbd{C-u Z `}. -Also, @w{@kbd{Z `}} with a negative prefix argument resets the algebraic mode -to its default (off) but leaves the other modes the same as they were -outside the construct. - -The contents of the stack and trail, values of non-quick variables, and -other settings such as the language mode and the various display modes, -are @emph{not} affected by @kbd{Z `} and @kbd{Z '}. - -@node Queries in Macros, , Local Values in Macros, Keyboard Macros -@subsection Queries in Keyboard Macros - -@c @noindent -@c @kindex Z = -@c @pindex calc-kbd-report -@c The @kbd{Z =} (@code{calc-kbd-report}) command displays an informative -@c message including the value on the top of the stack. You are prompted -@c to enter a string. That string, along with the top-of-stack value, -@c is displayed unless @kbd{m w} (@code{calc-working}) has been used -@c to turn such messages off. - -@noindent -@kindex Z # -@pindex calc-kbd-query -The @kbd{Z #} (@code{calc-kbd-query}) command prompts for an algebraic -entry which takes its input from the keyboard, even during macro -execution. All the normal conventions of algebraic input, including the -use of @kbd{$} characters, are supported. The prompt message itself is -taken from the top of the stack, and so must be entered (as a string) -before the @kbd{Z #} command. (Recall, as a string it can be entered by -pressing the @kbd{"} key and will appear as a vector when it is put on -the stack. The prompt message is only put on the stack to provide a -prompt for the @kbd{Z #} command; it will not play any role in any -subsequent calculations.) This command allows your keyboard macros to -accept numbers or formulas as interactive input. - -As an example, -@kbd{2 @key{RET} "Power: " @key{RET} Z # 3 @key{RET} ^} will prompt for -input with ``Power: '' in the minibuffer, then return 2 to the provided -power. (The response to the prompt that's given, 3 in this example, -will not be part of the macro.) - -@xref{Keyboard Macro Query, , , emacs, the Emacs Manual}, for a description of -@kbd{C-x q} (@code{kbd-macro-query}), the standard Emacs way to accept -keyboard input during a keyboard macro. In particular, you can use -@kbd{C-x q} to enter a recursive edit, which allows the user to perform -any Calculator operations interactively before pressing @kbd{C-M-c} to -return control to the keyboard macro. - -@node Invocation Macros, Algebraic Definitions, Keyboard Macros, Programming -@section Invocation Macros - -@kindex C-x * z -@kindex Z I -@pindex calc-user-invocation -@pindex calc-user-define-invocation -Calc provides one special keyboard macro, called up by @kbd{C-x * z} -(@code{calc-user-invocation}), that is intended to allow you to define -your own special way of starting Calc. To define this ``invocation -macro,'' create the macro in the usual way with @kbd{C-x (} and -@kbd{C-x )}, then type @kbd{Z I} (@code{calc-user-define-invocation}). -There is only one invocation macro, so you don't need to type any -additional letters after @kbd{Z I}. From now on, you can type -@kbd{C-x * z} at any time to execute your invocation macro. - -For example, suppose you find yourself often grabbing rectangles of -numbers into Calc and multiplying their columns. You can do this -by typing @kbd{C-x * r} to grab, and @kbd{V R : *} to multiply columns. -To make this into an invocation macro, just type @kbd{C-x ( C-x * r -V R : * C-x )}, then @kbd{Z I}. Then, to multiply a rectangle of data, -just mark the data in its buffer in the usual way and type @kbd{C-x * z}. - -Invocation macros are treated like regular Emacs keyboard macros; -all the special features described above for @kbd{Z K}-style macros -do not apply. @kbd{C-x * z} is just like @kbd{C-x e}, except that it -uses the macro that was last stored by @kbd{Z I}. (In fact, the -macro does not even have to have anything to do with Calc!) - -The @kbd{m m} command saves the last invocation macro defined by -@kbd{Z I} along with all the other Calc mode settings. -@xref{General Mode Commands}. - -@node Algebraic Definitions, Lisp Definitions, Invocation Macros, Programming -@section Programming with Formulas - -@noindent -@kindex Z F -@pindex calc-user-define-formula -@cindex Programming with algebraic formulas -Another way to create a new Calculator command uses algebraic formulas. -The @kbd{Z F} (@code{calc-user-define-formula}) command stores the -formula at the top of the stack as the definition for a key. This -command prompts for five things: The key, the command name, the function -name, the argument list, and the behavior of the command when given -non-numeric arguments. - -For example, suppose we type @kbd{' a+2b @key{RET}} to push the formula -@samp{a + 2*b} onto the stack. We now type @kbd{Z F m} to define this -formula on the @kbd{z m} key sequence. The next prompt is for a command -name, beginning with @samp{calc-}, which should be the long (@kbd{M-x}) form -for the new command. If you simply press @key{RET}, a default name like -@code{calc-User-m} will be constructed. In our example, suppose we enter -@kbd{spam @key{RET}} to define the new command as @code{calc-spam}. - -If you want to give the formula a long-style name only, you can press -@key{SPC} or @key{RET} when asked which single key to use. For example -@kbd{Z F @key{RET} spam @key{RET}} defines the new command as -@kbd{M-x calc-spam}, with no keyboard equivalent. - -The third prompt is for an algebraic function name. The default is to -use the same name as the command name but without the @samp{calc-} -prefix. (If this is of the form @samp{User-m}, the hyphen is removed so -it won't be taken for a minus sign in algebraic formulas.) -This is the name you will use if you want to enter your -new function in an algebraic formula. Suppose we enter @kbd{yow @key{RET}}. -Then the new function can be invoked by pushing two numbers on the -stack and typing @kbd{z m} or @kbd{x spam}, or by entering the algebraic -formula @samp{yow(x,y)}. - -The fourth prompt is for the function's argument list. This is used to -associate values on the stack with the variables that appear in the formula. -The default is a list of all variables which appear in the formula, sorted -into alphabetical order. In our case, the default would be @samp{(a b)}. -This means that, when the user types @kbd{z m}, the Calculator will remove -two numbers from the stack, substitute these numbers for @samp{a} and -@samp{b} (respectively) in the formula, then simplify the formula and -push the result on the stack. In other words, @kbd{10 @key{RET} 100 z m} -would replace the 10 and 100 on the stack with the number 210, which is -@expr{a + 2 b} with @expr{a=10} and @expr{b=100}. Likewise, the formula -@samp{yow(10, 100)} will be evaluated by substituting @expr{a=10} and -@expr{b=100} in the definition. - -You can rearrange the order of the names before pressing @key{RET} to -control which stack positions go to which variables in the formula. If -you remove a variable from the argument list, that variable will be left -in symbolic form by the command. Thus using an argument list of @samp{(b)} -for our function would cause @kbd{10 z m} to replace the 10 on the stack -with the formula @samp{a + 20}. If we had used an argument list of -@samp{(b a)}, the result with inputs 10 and 100 would have been 120. - -You can also put a nameless function on the stack instead of just a -formula, as in @samp{}. @xref{Specifying Operators}. -In this example, the command will be defined by the formula @samp{a + 2 b} -using the argument list @samp{(a b)}. - -The final prompt is a y-or-n question concerning what to do if symbolic -arguments are given to your function. If you answer @kbd{y}, then -executing @kbd{z m} (using the original argument list @samp{(a b)}) with -arguments @expr{10} and @expr{x} will leave the function in symbolic -form, i.e., @samp{yow(10,x)}. On the other hand, if you answer @kbd{n}, -then the formula will always be expanded, even for non-constant -arguments: @samp{10 + 2 x}. If you never plan to feed algebraic -formulas to your new function, it doesn't matter how you answer this -question. - -If you answered @kbd{y} to this question you can still cause a function -call to be expanded by typing @kbd{a "} (@code{calc-expand-formula}). -Also, Calc will expand the function if necessary when you take a -derivative or integral or solve an equation involving the function. - -@kindex Z G -@pindex calc-get-user-defn -Once you have defined a formula on a key, you can retrieve this formula -with the @kbd{Z G} (@code{calc-user-define-get-defn}) command. Press a -key, and this command pushes the formula that was used to define that -key onto the stack. Actually, it pushes a nameless function that -specifies both the argument list and the defining formula. You will get -an error message if the key is undefined, or if the key was not defined -by a @kbd{Z F} command. - -The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has -been defined by a formula uses a variant of the @code{calc-edit} command -to edit the defining formula. Press @kbd{C-c C-c} to finish editing and -store the new formula back in the definition, or kill the buffer with -@kbd{C-x k} to -cancel the edit. (The argument list and other properties of the -definition are unchanged; to adjust the argument list, you can use -@kbd{Z G} to grab the function onto the stack, edit with @kbd{`}, and -then re-execute the @kbd{Z F} command.) - -As usual, the @kbd{Z P} command records your definition permanently. -In this case it will permanently record all three of the relevant -definitions: the key, the command, and the function. - -You may find it useful to turn off the default simplifications with -@kbd{m O} (@code{calc-no-simplify-mode}) when entering a formula to be -used as a function definition. For example, the formula @samp{deriv(a^2,v)} -which might be used to define a new function @samp{dsqr(a,v)} will be -``simplified'' to 0 immediately upon entry since @code{deriv} considers -@expr{a} to be constant with respect to @expr{v}. Turning off -default simplifications cures this problem: The definition will be stored -in symbolic form without ever activating the @code{deriv} function. Press -@kbd{m D} to turn the default simplifications back on afterwards. - -@node Lisp Definitions, , Algebraic Definitions, Programming -@section Programming with Lisp - -@noindent -The Calculator can be programmed quite extensively in Lisp. All you -do is write a normal Lisp function definition, but with @code{defmath} -in place of @code{defun}. This has the same form as @code{defun}, but it -automagically replaces calls to standard Lisp functions like @code{+} and -@code{zerop} with calls to the corresponding functions in Calc's own library. -Thus you can write natural-looking Lisp code which operates on all of the -standard Calculator data types. You can then use @kbd{Z D} if you wish to -bind your new command to a @kbd{z}-prefix key sequence. The @kbd{Z E} command -will not edit a Lisp-based definition. - -Emacs Lisp is described in the GNU Emacs Lisp Reference Manual. This section -assumes a familiarity with Lisp programming concepts; if you do not know -Lisp, you may find keyboard macros or rewrite rules to be an easier way -to program the Calculator. - -This section first discusses ways to write commands, functions, or -small programs to be executed inside of Calc. Then it discusses how -your own separate programs are able to call Calc from the outside. -Finally, there is a list of internal Calc functions and data structures -for the true Lisp enthusiast. - -@menu -* Defining Functions:: -* Defining Simple Commands:: -* Defining Stack Commands:: -* Argument Qualifiers:: -* Example Definitions:: - -* Calling Calc from Your Programs:: -* Internals:: -@end menu - -@node Defining Functions, Defining Simple Commands, Lisp Definitions, Lisp Definitions -@subsection Defining New Functions - -@noindent -@findex defmath -The @code{defmath} function (actually a Lisp macro) is like @code{defun} -except that code in the body of the definition can make use of the full -range of Calculator data types. The prefix @samp{calcFunc-} is added -to the specified name to get the actual Lisp function name. As a simple -example, - -@example -(defmath myfact (n) - (if (> n 0) - (* n (myfact (1- n))) - 1)) -@end example - -@noindent -This actually expands to the code, - -@example -(defun calcFunc-myfact (n) - (if (math-posp n) - (math-mul n (calcFunc-myfact (math-add n -1))) - 1)) -@end example - -@noindent -This function can be used in algebraic expressions, e.g., @samp{myfact(5)}. - -The @samp{myfact} function as it is defined above has the bug that an -expression @samp{myfact(a+b)} will be simplified to 1 because the -formula @samp{a+b} is not considered to be @code{posp}. A robust -factorial function would be written along the following lines: - -@smallexample -(defmath myfact (n) - (if (> n 0) - (* n (myfact (1- n))) - (if (= n 0) - 1 - nil))) ; this could be simplified as: (and (= n 0) 1) -@end smallexample - -If a function returns @code{nil}, it is left unsimplified by the Calculator -(except that its arguments will be simplified). Thus, @samp{myfact(a+1+2)} -will be simplified to @samp{myfact(a+3)} but no further. Beware that every -time the Calculator reexamines this formula it will attempt to resimplify -it, so your function ought to detect the returning-@code{nil} case as -efficiently as possible. - -The following standard Lisp functions are treated by @code{defmath}: -@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^} or -@code{expt}, @code{=}, @code{<}, @code{>}, @code{<=}, @code{>=}, -@code{/=}, @code{1+}, @code{1-}, @code{logand}, @code{logior}, @code{logxor}, -@code{logandc2}, @code{lognot}. Also, @code{~=} is an abbreviation for -@code{math-nearly-equal}, which is useful in implementing Taylor series. - -For other functions @var{func}, if a function by the name -@samp{calcFunc-@var{func}} exists it is used, otherwise if a function by the -name @samp{math-@var{func}} exists it is used, otherwise if @var{func} itself -is defined as a function it is used, otherwise @samp{calcFunc-@var{func}} is -used on the assumption that this is a to-be-defined math function. Also, if -the function name is quoted as in @samp{('integerp a)} the function name is -always used exactly as written (but not quoted). - -Variable names have @samp{var-} prepended to them unless they appear in -the function's argument list or in an enclosing @code{let}, @code{let*}, -@code{for}, or @code{foreach} form, -or their names already contain a @samp{-} character. Thus a reference to -@samp{foo} is the same as a reference to @samp{var-foo}. - -A few other Lisp extensions are available in @code{defmath} definitions: - -@itemize @bullet -@item -The @code{elt} function accepts any number of index variables. -Note that Calc vectors are stored as Lisp lists whose first -element is the symbol @code{vec}; thus, @samp{(elt v 2)} yields -the second element of vector @code{v}, and @samp{(elt m i j)} -yields one element of a Calc matrix. - -@item -The @code{setq} function has been extended to act like the Common -Lisp @code{setf} function. (The name @code{setf} is recognized as -a synonym of @code{setq}.) Specifically, the first argument of -@code{setq} can be an @code{nth}, @code{elt}, @code{car}, or @code{cdr} form, -in which case the effect is to store into the specified -element of a list. Thus, @samp{(setq (elt m i j) x)} stores @expr{x} -into one element of a matrix. - -@item -A @code{for} looping construct is available. For example, -@samp{(for ((i 0 10)) body)} executes @code{body} once for each -binding of @expr{i} from zero to 10. This is like a @code{let} -form in that @expr{i} is temporarily bound to the loop count -without disturbing its value outside the @code{for} construct. -Nested loops, as in @samp{(for ((i 0 10) (j 0 (1- i) 2)) body)}, -are also available. For each value of @expr{i} from zero to 10, -@expr{j} counts from 0 to @expr{i-1} in steps of two. Note that -@code{for} has the same general outline as @code{let*}, except -that each element of the header is a list of three or four -things, not just two. - -@item -The @code{foreach} construct loops over elements of a list. -For example, @samp{(foreach ((x (cdr v))) body)} executes -@code{body} with @expr{x} bound to each element of Calc vector -@expr{v} in turn. The purpose of @code{cdr} here is to skip over -the initial @code{vec} symbol in the vector. - -@item -The @code{break} function breaks out of the innermost enclosing -@code{while}, @code{for}, or @code{foreach} loop. If given a -value, as in @samp{(break x)}, this value is returned by the -loop. (Lisp loops otherwise always return @code{nil}.) - -@item -The @code{return} function prematurely returns from the enclosing -function. For example, @samp{(return (+ x y))} returns @expr{x+y} -as the value of a function. You can use @code{return} anywhere -inside the body of the function. -@end itemize - -Non-integer numbers (and extremely large integers) cannot be included -directly into a @code{defmath} definition. This is because the Lisp -reader will fail to parse them long before @code{defmath} ever gets control. -Instead, use the notation, @samp{:"3.1415"}. In fact, any algebraic -formula can go between the quotes. For example, - -@smallexample -(defmath sqexp (x) ; sqexp(x) == sqrt(exp(x)) == exp(x*0.5) - (and (numberp x) - (exp :"x * 0.5"))) -@end smallexample - -expands to - -@smallexample -(defun calcFunc-sqexp (x) - (and (math-numberp x) - (calcFunc-exp (math-mul x '(float 5 -1))))) -@end smallexample - -Note the use of @code{numberp} as a guard to ensure that the argument is -a number first, returning @code{nil} if not. The exponential function -could itself have been included in the expression, if we had preferred: -@samp{:"exp(x * 0.5)"}. As another example, the multiplication-and-recursion -step of @code{myfact} could have been written - -@example -:"n * myfact(n-1)" -@end example - -A good place to put your @code{defmath} commands is your Calc init file -(the file given by @code{calc-settings-file}, typically -@file{~/.emacs.d/calc.el}), which will not be loaded until Calc starts. -If a file named @file{.emacs} exists in your home directory, Emacs reads -and executes the Lisp forms in this file as it starts up. While it may -seem reasonable to put your favorite @code{defmath} commands there, -this has the unfortunate side-effect that parts of the Calculator must be -loaded in to process the @code{defmath} commands whether or not you will -actually use the Calculator! If you want to put the @code{defmath} -commands there (for example, if you redefine @code{calc-settings-file} -to be @file{.emacs}), a better effect can be had by writing - -@example -(put 'calc-define 'thing '(progn - (defmath ... ) - (defmath ... ) -)) -@end example - -@noindent -@vindex calc-define -The @code{put} function adds a @dfn{property} to a symbol. Each Lisp -symbol has a list of properties associated with it. Here we add a -property with a name of @code{thing} and a @samp{(progn ...)} form as -its value. When Calc starts up, and at the start of every Calc command, -the property list for the symbol @code{calc-define} is checked and the -values of any properties found are evaluated as Lisp forms. The -properties are removed as they are evaluated. The property names -(like @code{thing}) are not used; you should choose something like the -name of your project so as not to conflict with other properties. - -The net effect is that you can put the above code in your @file{.emacs} -file and it will not be executed until Calc is loaded. Or, you can put -that same code in another file which you load by hand either before or -after Calc itself is loaded. - -The properties of @code{calc-define} are evaluated in the same order -that they were added. They can assume that the Calc modules @file{calc.el}, -@file{calc-ext.el}, and @file{calc-macs.el} have been fully loaded, and -that the @samp{*Calculator*} buffer will be the current buffer. - -If your @code{calc-define} property only defines algebraic functions, -you can be sure that it will have been evaluated before Calc tries to -call your function, even if the file defining the property is loaded -after Calc is loaded. But if the property defines commands or key -sequences, it may not be evaluated soon enough. (Suppose it defines the -new command @code{tweak-calc}; the user can load your file, then type -@kbd{M-x tweak-calc} before Calc has had chance to do anything.) To -protect against this situation, you can put - -@example -(run-hooks 'calc-check-defines) -@end example - -@findex calc-check-defines -@noindent -at the end of your file. The @code{calc-check-defines} function is what -looks for and evaluates properties on @code{calc-define}; @code{run-hooks} -has the advantage that it is quietly ignored if @code{calc-check-defines} -is not yet defined because Calc has not yet been loaded. - -Examples of things that ought to be enclosed in a @code{calc-define} -property are @code{defmath} calls, @code{define-key} calls that modify -the Calc key map, and any calls that redefine things defined inside Calc. -Ordinary @code{defun}s need not be enclosed with @code{calc-define}. - -@node Defining Simple Commands, Defining Stack Commands, Defining Functions, Lisp Definitions -@subsection Defining New Simple Commands - -@noindent -@findex interactive -If a @code{defmath} form contains an @code{interactive} clause, it defines -a Calculator command. Actually such a @code{defmath} results in @emph{two} -function definitions: One, a @samp{calcFunc-} function as was just described, -with the @code{interactive} clause removed. Two, a @samp{calc-} function -with a suitable @code{interactive} clause and some sort of wrapper to make -the command work in the Calc environment. - -In the simple case, the @code{interactive} clause has the same form as -for normal Emacs Lisp commands: - -@smallexample -(defmath increase-precision (delta) - "Increase precision by DELTA." ; This is the "documentation string" - (interactive "p") ; Register this as a M-x-able command - (setq calc-internal-prec (+ calc-internal-prec delta))) -@end smallexample - -This expands to the pair of definitions, - -@smallexample -(defun calc-increase-precision (delta) - "Increase precision by DELTA." - (interactive "p") - (calc-wrapper - (setq calc-internal-prec (math-add calc-internal-prec delta)))) - -(defun calcFunc-increase-precision (delta) - "Increase precision by DELTA." - (setq calc-internal-prec (math-add calc-internal-prec delta))) -@end smallexample - -@noindent -where in this case the latter function would never really be used! Note -that since the Calculator stores small integers as plain Lisp integers, -the @code{math-add} function will work just as well as the native -@code{+} even when the intent is to operate on native Lisp integers. - -@findex calc-wrapper -The @samp{calc-wrapper} call invokes a macro which surrounds the body of -the function with code that looks roughly like this: - -@smallexample -(let ((calc-command-flags nil)) - (unwind-protect - (save-current-buffer - (calc-select-buffer) - @emph{body of function} - @emph{renumber stack} - @emph{clear} Working @emph{message}) - @emph{realign cursor and window} - @emph{clear Inverse, Hyperbolic, and Keep Args flags} - @emph{update Emacs mode line})) -@end smallexample - -@findex calc-select-buffer -The @code{calc-select-buffer} function selects the @samp{*Calculator*} -buffer if necessary, say, because the command was invoked from inside -the @samp{*Calc Trail*} window. - -@findex calc-set-command-flag -You can call, for example, @code{(calc-set-command-flag 'no-align)} to -set the above-mentioned command flags. Calc routines recognize the -following command flags: - -@table @code -@item renum-stack -Stack line numbers @samp{1:}, @samp{2:}, and so on must be renumbered -after this command completes. This is set by routines like -@code{calc-push}. - -@item clear-message -Calc should call @samp{(message "")} if this command completes normally -(to clear a ``Working@dots{}'' message out of the echo area). - -@item no-align -Do not move the cursor back to the @samp{.} top-of-stack marker. - -@item position-point -Use the variables @code{calc-position-point-line} and -@code{calc-position-point-column} to position the cursor after -this command finishes. - -@item keep-flags -Do not clear @code{calc-inverse-flag}, @code{calc-hyperbolic-flag}, -and @code{calc-keep-args-flag} at the end of this command. - -@item do-edit -Switch to buffer @samp{*Calc Edit*} after this command. - -@item hold-trail -Do not move trail pointer to end of trail when something is recorded -there. -@end table - -@kindex Y -@kindex Y ? -@vindex calc-Y-help-msgs -Calc reserves a special prefix key, shift-@kbd{Y}, for user-written -extensions to Calc. There are no built-in commands that work with -this prefix key; you must call @code{define-key} from Lisp (probably -from inside a @code{calc-define} property) to add to it. Initially only -@kbd{Y ?} is defined; it takes help messages from a list of strings -(initially @code{nil}) in the variable @code{calc-Y-help-msgs}. All -other undefined keys except for @kbd{Y} are reserved for use by -future versions of Calc. - -If you are writing a Calc enhancement which you expect to give to -others, it is best to minimize the number of @kbd{Y}-key sequences -you use. In fact, if you have more than one key sequence you should -consider defining three-key sequences with a @kbd{Y}, then a key that -stands for your package, then a third key for the particular command -within your package. - -Users may wish to install several Calc enhancements, and it is possible -that several enhancements will choose to use the same key. In the -example below, a variable @code{inc-prec-base-key} has been defined -to contain the key that identifies the @code{inc-prec} package. Its -value is initially @code{"P"}, but a user can change this variable -if necessary without having to modify the file. - -Here is a complete file, @file{inc-prec.el}, which makes a @kbd{Y P I} -command that increases the precision, and a @kbd{Y P D} command that -decreases the precision. - -@smallexample -;;; Increase and decrease Calc precision. Dave Gillespie, 5/31/91. -;; (Include copyright or copyleft stuff here.) - -(defvar inc-prec-base-key "P" - "Base key for inc-prec.el commands.") - -(put 'calc-define 'inc-prec '(progn - -(define-key calc-mode-map (format "Y%sI" inc-prec-base-key) - 'increase-precision) -(define-key calc-mode-map (format "Y%sD" inc-prec-base-key) - 'decrease-precision) - -(setq calc-Y-help-msgs - (cons (format "%s + Inc-prec, Dec-prec" inc-prec-base-key) - calc-Y-help-msgs)) - -(defmath increase-precision (delta) - "Increase precision by DELTA." - (interactive "p") - (setq calc-internal-prec (+ calc-internal-prec delta))) - -(defmath decrease-precision (delta) - "Decrease precision by DELTA." - (interactive "p") - (setq calc-internal-prec (- calc-internal-prec delta))) - -)) ; end of calc-define property - -(run-hooks 'calc-check-defines) -@end smallexample - -@node Defining Stack Commands, Argument Qualifiers, Defining Simple Commands, Lisp Definitions -@subsection Defining New Stack-Based Commands - -@noindent -To define a new computational command which takes and/or leaves arguments -on the stack, a special form of @code{interactive} clause is used. - -@example -(interactive @var{num} @var{tag}) -@end example - -@noindent -where @var{num} is an integer, and @var{tag} is a string. The effect is -to pop @var{num} values off the stack, resimplify them by calling -@code{calc-normalize}, and hand them to your function according to the -function's argument list. Your function may include @code{&optional} and -@code{&rest} parameters, so long as calling the function with @var{num} -parameters is valid. - -Your function must return either a number or a formula in a form -acceptable to Calc, or a list of such numbers or formulas. These value(s) -are pushed onto the stack when the function completes. They are also -recorded in the Calc Trail buffer on a line beginning with @var{tag}, -a string of (normally) four characters or less. If you omit @var{tag} -or use @code{nil} as a tag, the result is not recorded in the trail. - -As an example, the definition - -@smallexample -(defmath myfact (n) - "Compute the factorial of the integer at the top of the stack." - (interactive 1 "fact") - (if (> n 0) - (* n (myfact (1- n))) - (and (= n 0) 1))) -@end smallexample - -@noindent -is a version of the factorial function shown previously which can be used -as a command as well as an algebraic function. It expands to - -@smallexample -(defun calc-myfact () - "Compute the factorial of the integer at the top of the stack." - (interactive) - (calc-slow-wrapper - (calc-enter-result 1 "fact" - (cons 'calcFunc-myfact (calc-top-list-n 1))))) - -(defun calcFunc-myfact (n) - "Compute the factorial of the integer at the top of the stack." - (if (math-posp n) - (math-mul n (calcFunc-myfact (math-add n -1))) - (and (math-zerop n) 1))) -@end smallexample - -@findex calc-slow-wrapper -The @code{calc-slow-wrapper} function is a version of @code{calc-wrapper} -that automatically puts up a @samp{Working...} message before the -computation begins. (This message can be turned off by the user -with an @kbd{m w} (@code{calc-working}) command.) - -@findex calc-top-list-n -The @code{calc-top-list-n} function returns a list of the specified number -of values from the top of the stack. It resimplifies each value by -calling @code{calc-normalize}. If its argument is zero it returns an -empty list. It does not actually remove these values from the stack. - -@findex calc-enter-result -The @code{calc-enter-result} function takes an integer @var{num} and string -@var{tag} as described above, plus a third argument which is either a -Calculator data object or a list of such objects. These objects are -resimplified and pushed onto the stack after popping the specified number -of values from the stack. If @var{tag} is non-@code{nil}, the values -being pushed are also recorded in the trail. - -Note that if @code{calcFunc-myfact} returns @code{nil} this represents -``leave the function in symbolic form.'' To return an actual empty list, -in the sense that @code{calc-enter-result} will push zero elements back -onto the stack, you should return the special value @samp{'(nil)}, a list -containing the single symbol @code{nil}. - -The @code{interactive} declaration can actually contain a limited -Emacs-style code string as well which comes just before @var{num} and -@var{tag}. Currently the only Emacs code supported is @samp{"p"}, as in - -@example -(defmath foo (a b &optional c) - (interactive "p" 2 "foo") - @var{body}) -@end example - -In this example, the command @code{calc-foo} will evaluate the expression -@samp{foo(a,b)} if executed with no argument, or @samp{foo(a,b,n)} if -executed with a numeric prefix argument of @expr{n}. - -The other code string allowed is @samp{"m"} (unrelated to the usual @samp{"m"} -code as used with @code{defun}). It uses the numeric prefix argument as the -number of objects to remove from the stack and pass to the function. -In this case, the integer @var{num} serves as a default number of -arguments to be used when no prefix is supplied. - -@node Argument Qualifiers, Example Definitions, Defining Stack Commands, Lisp Definitions -@subsection Argument Qualifiers - -@noindent -Anywhere a parameter name can appear in the parameter list you can also use -an @dfn{argument qualifier}. Thus the general form of a definition is: - -@example -(defmath @var{name} (@var{param} @var{param...} - &optional @var{param} @var{param...} - &rest @var{param}) - @var{body}) -@end example - -@noindent -where each @var{param} is either a symbol or a list of the form - -@example -(@var{qual} @var{param}) -@end example - -The following qualifiers are recognized: - -@table @samp -@item complete -@findex complete -The argument must not be an incomplete vector, interval, or complex number. -(This is rarely needed since the Calculator itself will never call your -function with an incomplete argument. But there is nothing stopping your -own Lisp code from calling your function with an incomplete argument.) - -@item integer -@findex integer -The argument must be an integer. If it is an integer-valued float -it will be accepted but converted to integer form. Non-integers and -formulas are rejected. - -@item natnum -@findex natnum -Like @samp{integer}, but the argument must be non-negative. - -@item fixnum -@findex fixnum -Like @samp{integer}, but the argument must fit into a native Lisp integer, -which on most systems means less than 2^23 in absolute value. The -argument is converted into Lisp-integer form if necessary. - -@item float -@findex float -The argument is converted to floating-point format if it is a number or -vector. If it is a formula it is left alone. (The argument is never -actually rejected by this qualifier.) - -@item @var{pred} -The argument must satisfy predicate @var{pred}, which is one of the -standard Calculator predicates. @xref{Predicates}. - -@item not-@var{pred} -The argument must @emph{not} satisfy predicate @var{pred}. -@end table - -For example, - -@example -(defmath foo (a (constp (not-matrixp b)) &optional (float c) - &rest (integer d)) - @var{body}) -@end example - -@noindent -expands to - -@example -(defun calcFunc-foo (a b &optional c &rest d) - (and (math-matrixp b) - (math-reject-arg b 'not-matrixp)) - (or (math-constp b) - (math-reject-arg b 'constp)) - (and c (setq c (math-check-float c))) - (setq d (mapcar 'math-check-integer d)) - @var{body}) -@end example - -@noindent -which performs the necessary checks and conversions before executing the -body of the function. - -@node Example Definitions, Calling Calc from Your Programs, Argument Qualifiers, Lisp Definitions -@subsection Example Definitions - -@noindent -This section includes some Lisp programming examples on a larger scale. -These programs make use of some of the Calculator's internal functions; -@pxref{Internals}. - -@menu -* Bit Counting Example:: -* Sine Example:: -@end menu - -@node Bit Counting Example, Sine Example, Example Definitions, Example Definitions -@subsubsection Bit-Counting - -@noindent -@ignore -@starindex -@end ignore -@tindex bcount -Calc does not include a built-in function for counting the number of -``one'' bits in a binary integer. It's easy to invent one using @kbd{b u} -to convert the integer to a set, and @kbd{V #} to count the elements of -that set; let's write a function that counts the bits without having to -create an intermediate set. - -@smallexample -(defmath bcount ((natnum n)) - (interactive 1 "bcnt") - (let ((count 0)) - (while (> n 0) - (if (oddp n) - (setq count (1+ count))) - (setq n (lsh n -1))) - count)) -@end smallexample - -@noindent -When this is expanded by @code{defmath}, it will become the following -Emacs Lisp function: - -@smallexample -(defun calcFunc-bcount (n) - (setq n (math-check-natnum n)) - (let ((count 0)) - (while (math-posp n) - (if (math-oddp n) - (setq count (math-add count 1))) - (setq n (calcFunc-lsh n -1))) - count)) -@end smallexample - -If the input numbers are large, this function involves a fair amount -of arithmetic. A binary right shift is essentially a division by two; -recall that Calc stores integers in decimal form so bit shifts must -involve actual division. - -To gain a bit more efficiency, we could divide the integer into -@var{n}-bit chunks, each of which can be handled quickly because -they fit into Lisp integers. It turns out that Calc's arithmetic -routines are especially fast when dividing by an integer less than -1000, so we can set @var{n = 9} bits and use repeated division by 512: - -@smallexample -(defmath bcount ((natnum n)) - (interactive 1 "bcnt") - (let ((count 0)) - (while (not (fixnump n)) - (let ((qr (idivmod n 512))) - (setq count (+ count (bcount-fixnum (cdr qr))) - n (car qr)))) - (+ count (bcount-fixnum n)))) - -(defun bcount-fixnum (n) - (let ((count 0)) - (while (> n 0) - (setq count (+ count (logand n 1)) - n (lsh n -1))) - count)) -@end smallexample - -@noindent -Note that the second function uses @code{defun}, not @code{defmath}. -Because this function deals only with native Lisp integers (``fixnums''), -it can use the actual Emacs @code{+} and related functions rather -than the slower but more general Calc equivalents which @code{defmath} -uses. - -The @code{idivmod} function does an integer division, returning both -the quotient and the remainder at once. Again, note that while it -might seem that @samp{(logand n 511)} and @samp{(lsh n -9)} are -more efficient ways to split off the bottom nine bits of @code{n}, -actually they are less efficient because each operation is really -a division by 512 in disguise; @code{idivmod} allows us to do the -same thing with a single division by 512. - -@node Sine Example, , Bit Counting Example, Example Definitions -@subsubsection The Sine Function - -@noindent -@ignore -@starindex -@end ignore -@tindex mysin -A somewhat limited sine function could be defined as follows, using the -well-known Taylor series expansion for -@texline @math{\sin x}: -@infoline @samp{sin(x)}: - -@smallexample -(defmath mysin ((float (anglep x))) - (interactive 1 "mysn") - (setq x (to-radians x)) ; Convert from current angular mode. - (let ((sum x) ; Initial term of Taylor expansion of sin. - newsum - (nfact 1) ; "nfact" equals "n" factorial at all times. - (xnegsqr :"-(x^2)")) ; "xnegsqr" equals -x^2. - (for ((n 3 100 2)) ; Upper limit of 100 is a good precaution. - (working "mysin" sum) ; Display "Working" message, if enabled. - (setq nfact (* nfact (1- n) n) - x (* x xnegsqr) - newsum (+ sum (/ x nfact))) - (if (~= newsum sum) ; If newsum is "nearly equal to" sum, - (break)) ; then we are done. - (setq sum newsum)) - sum)) -@end smallexample - -The actual @code{sin} function in Calc works by first reducing the problem -to a sine or cosine of a nonnegative number less than @cpiover{4}. This -ensures that the Taylor series will converge quickly. Also, the calculation -is carried out with two extra digits of precision to guard against cumulative -round-off in @samp{sum}. Finally, complex arguments are allowed and handled -by a separate algorithm. - -@smallexample -(defmath mysin ((float (scalarp x))) - (interactive 1 "mysn") - (setq x (to-radians x)) ; Convert from current angular mode. - (with-extra-prec 2 ; Evaluate with extra precision. - (cond ((complexp x) - (mysin-complex x)) - ((< x 0) - (- (mysin-raw (- x))) ; Always call mysin-raw with x >= 0. - (t (mysin-raw x)))))) - -(defmath mysin-raw (x) - (cond ((>= x 7) - (mysin-raw (% x (two-pi)))) ; Now x < 7. - ((> x (pi-over-2)) - (- (mysin-raw (- x (pi))))) ; Now -pi/2 <= x <= pi/2. - ((> x (pi-over-4)) - (mycos-raw (- x (pi-over-2)))) ; Now -pi/2 <= x <= pi/4. - ((< x (- (pi-over-4))) - (- (mycos-raw (+ x (pi-over-2))))) ; Now -pi/4 <= x <= pi/4, - (t (mysin-series x)))) ; so the series will be efficient. -@end smallexample - -@noindent -where @code{mysin-complex} is an appropriate function to handle complex -numbers, @code{mysin-series} is the routine to compute the sine Taylor -series as before, and @code{mycos-raw} is a function analogous to -@code{mysin-raw} for cosines. - -The strategy is to ensure that @expr{x} is nonnegative before calling -@code{mysin-raw}. This function then recursively reduces its argument -to a suitable range, namely, plus-or-minus @cpiover{4}. Note that each -test, and particularly the first comparison against 7, is designed so -that small roundoff errors cannot produce an infinite loop. (Suppose -we compared with @samp{(two-pi)} instead; if due to roundoff problems -the modulo operator ever returned @samp{(two-pi)} exactly, an infinite -recursion could result!) We use modulo only for arguments that will -clearly get reduced, knowing that the next rule will catch any reductions -that this rule misses. - -If a program is being written for general use, it is important to code -it carefully as shown in this second example. For quick-and-dirty programs, -when you know that your own use of the sine function will never encounter -a large argument, a simpler program like the first one shown is fine. - -@node Calling Calc from Your Programs, Internals, Example Definitions, Lisp Definitions -@subsection Calling Calc from Your Lisp Programs - -@noindent -A later section (@pxref{Internals}) gives a full description of -Calc's internal Lisp functions. It's not hard to call Calc from -inside your programs, but the number of these functions can be daunting. -So Calc provides one special ``programmer-friendly'' function called -@code{calc-eval} that can be made to do just about everything you -need. It's not as fast as the low-level Calc functions, but it's -much simpler to use! - -It may seem that @code{calc-eval} itself has a daunting number of -options, but they all stem from one simple operation. - -In its simplest manifestation, @samp{(calc-eval "1+2")} parses the -string @code{"1+2"} as if it were a Calc algebraic entry and returns -the result formatted as a string: @code{"3"}. - -Since @code{calc-eval} is on the list of recommended @code{autoload} -functions, you don't need to make any special preparations to load -Calc before calling @code{calc-eval} the first time. Calc will be -loaded and initialized for you. - -All the Calc modes that are currently in effect will be used when -evaluating the expression and formatting the result. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Additional Arguments to @code{calc-eval} - -@noindent -If the input string parses to a list of expressions, Calc returns -the results separated by @code{", "}. You can specify a different -separator by giving a second string argument to @code{calc-eval}: -@samp{(calc-eval "1+2,3+4" ";")} returns @code{"3;7"}. - -The ``separator'' can also be any of several Lisp symbols which -request other behaviors from @code{calc-eval}. These are discussed -one by one below. - -You can give additional arguments to be substituted for -@samp{$}, @samp{$$}, and so on in the main expression. For -example, @samp{(calc-eval "$/$$" nil "7" "1+1")} evaluates the -expression @code{"7/(1+1)"} to yield the result @code{"3.5"} -(assuming Fraction mode is not in effect). Note the @code{nil} -used as a placeholder for the item-separator argument. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Error Handling - -@noindent -If @code{calc-eval} encounters an error, it returns a list containing -the character position of the error, plus a suitable message as a -string. Note that @samp{1 / 0} is @emph{not} an error by Calc's -standards; it simply returns the string @code{"1 / 0"} which is the -division left in symbolic form. But @samp{(calc-eval "1/")} will -return the list @samp{(2 "Expected a number")}. - -If you bind the variable @code{calc-eval-error} to @code{t} -using a @code{let} form surrounding the call to @code{calc-eval}, -errors instead call the Emacs @code{error} function which aborts -to the Emacs command loop with a beep and an error message. - -If you bind this variable to the symbol @code{string}, error messages -are returned as strings instead of lists. The character position is -ignored. - -As a courtesy to other Lisp code which may be using Calc, be sure -to bind @code{calc-eval-error} using @code{let} rather than changing -it permanently with @code{setq}. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Numbers Only - -@noindent -Sometimes it is preferable to treat @samp{1 / 0} as an error -rather than returning a symbolic result. If you pass the symbol -@code{num} as the second argument to @code{calc-eval}, results -that are not constants are treated as errors. The error message -reported is the first @code{calc-why} message if there is one, -or otherwise ``Number expected.'' - -A result is ``constant'' if it is a number, vector, or other -object that does not include variables or function calls. If it -is a vector, the components must themselves be constants. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Default Modes - -@noindent -If the first argument to @code{calc-eval} is a list whose first -element is a formula string, then @code{calc-eval} sets all the -various Calc modes to their default values while the formula is -evaluated and formatted. For example, the precision is set to 12 -digits, digit grouping is turned off, and the Normal language -mode is used. - -This same principle applies to the other options discussed below. -If the first argument would normally be @var{x}, then it can also -be the list @samp{(@var{x})} to use the default mode settings. - -If there are other elements in the list, they are taken as -variable-name/value pairs which override the default mode -settings. Look at the documentation at the front of the -@file{calc.el} file to find the names of the Lisp variables for -the various modes. The mode settings are restored to their -original values when @code{calc-eval} is done. - -For example, @samp{(calc-eval '("$+$$" calc-internal-prec 8) 'num a b)} -computes the sum of two numbers, requiring a numeric result, and -using default mode settings except that the precision is 8 instead -of the default of 12. - -It's usually best to use this form of @code{calc-eval} unless your -program actually considers the interaction with Calc's mode settings -to be a feature. This will avoid all sorts of potential ``gotchas''; -consider what happens with @samp{(calc-eval "sqrt(2)" 'num)} -when the user has left Calc in Symbolic mode or No-Simplify mode. - -As another example, @samp{(equal (calc-eval '("$<$$") nil a b) "1")} -checks if the number in string @expr{a} is less than the one in -string @expr{b}. Without using a list, the integer 1 might -come out in a variety of formats which would be hard to test for -conveniently: @code{"1"}, @code{"8#1"}, @code{"00001"}. (But -see ``Predicates'' mode, below.) - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Raw Numbers - -@noindent -Normally all input and output for @code{calc-eval} is done with strings. -You can do arithmetic with, say, @samp{(calc-eval "$+$$" nil a b)} -in place of @samp{(+ a b)}, but this is very inefficient since the -numbers must be converted to and from string format as they are passed -from one @code{calc-eval} to the next. - -If the separator is the symbol @code{raw}, the result will be returned -as a raw Calc data structure rather than a string. You can read about -how these objects look in the following sections, but usually you can -treat them as ``black box'' objects with no important internal -structure. - -There is also a @code{rawnum} symbol, which is a combination of -@code{raw} (returning a raw Calc object) and @code{num} (signaling -an error if that object is not a constant). - -You can pass a raw Calc object to @code{calc-eval} in place of a -string, either as the formula itself or as one of the @samp{$} -arguments. Thus @samp{(calc-eval "$+$$" 'raw a b)} is an -addition function that operates on raw Calc objects. Of course -in this case it would be easier to call the low-level @code{math-add} -function in Calc, if you can remember its name. - -In particular, note that a plain Lisp integer is acceptable to Calc -as a raw object. (All Lisp integers are accepted on input, but -integers of more than six decimal digits are converted to ``big-integer'' -form for output. @xref{Data Type Formats}.) - -When it comes time to display the object, just use @samp{(calc-eval a)} -to format it as a string. - -It is an error if the input expression evaluates to a list of -values. The separator symbol @code{list} is like @code{raw} -except that it returns a list of one or more raw Calc objects. - -Note that a Lisp string is not a valid Calc object, nor is a list -containing a string. Thus you can still safely distinguish all the -various kinds of error returns discussed above. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Predicates - -@noindent -If the separator symbol is @code{pred}, the result of the formula is -treated as a true/false value; @code{calc-eval} returns @code{t} or -@code{nil}, respectively. A value is considered ``true'' if it is a -non-zero number, or false if it is zero or if it is not a number. - -For example, @samp{(calc-eval "$<$$" 'pred a b)} tests whether -one value is less than another. - -As usual, it is also possible for @code{calc-eval} to return one of -the error indicators described above. Lisp will interpret such an -indicator as ``true'' if you don't check for it explicitly. If you -wish to have an error register as ``false'', use something like -@samp{(eq (calc-eval ...) t)}. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Variable Values - -@noindent -Variables in the formula passed to @code{calc-eval} are not normally -replaced by their values. If you wish this, you can use the -@code{evalv} function (@pxref{Algebraic Manipulation}). For example, -if 4 is stored in Calc variable @code{a} (i.e., in Lisp variable -@code{var-a}), then @samp{(calc-eval "a+pi")} will return the -formula @code{"a + pi"}, but @samp{(calc-eval "evalv(a+pi)")} -will return @code{"7.14159265359"}. - -To store in a Calc variable, just use @code{setq} to store in the -corresponding Lisp variable. (This is obtained by prepending -@samp{var-} to the Calc variable name.) Calc routines will -understand either string or raw form values stored in variables, -although raw data objects are much more efficient. For example, -to increment the Calc variable @code{a}: - -@example -(setq var-a (calc-eval "evalv(a+1)" 'raw)) -@end example - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Stack Access - -@noindent -If the separator symbol is @code{push}, the formula argument is -evaluated (with possible @samp{$} expansions, as usual). The -result is pushed onto the Calc stack. The return value is @code{nil} -(unless there is an error from evaluating the formula, in which -case the return value depends on @code{calc-eval-error} in the -usual way). - -If the separator symbol is @code{pop}, the first argument to -@code{calc-eval} must be an integer instead of a string. That -many values are popped from the stack and thrown away. A negative -argument deletes the entry at that stack level. The return value -is the number of elements remaining in the stack after popping; -@samp{(calc-eval 0 'pop)} is a good way to measure the size of -the stack. - -If the separator symbol is @code{top}, the first argument to -@code{calc-eval} must again be an integer. The value at that -stack level is formatted as a string and returned. Thus -@samp{(calc-eval 1 'top)} returns the top-of-stack value. If the -integer is out of range, @code{nil} is returned. - -The separator symbol @code{rawtop} is just like @code{top} except -that the stack entry is returned as a raw Calc object instead of -as a string. - -In all of these cases the first argument can be made a list in -order to force the default mode settings, as described above. -Thus @samp{(calc-eval '(2 calc-number-radix 16) 'top)} returns the -second-to-top stack entry, formatted as a string using the default -instead of current display modes, except that the radix is -hexadecimal instead of decimal. - -It is, of course, polite to put the Calc stack back the way you -found it when you are done, unless the user of your program is -actually expecting it to affect the stack. - -Note that you do not actually have to switch into the @samp{*Calculator*} -buffer in order to use @code{calc-eval}; it temporarily switches into -the stack buffer if necessary. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Keyboard Macros - -@noindent -If the separator symbol is @code{macro}, the first argument must be a -string of characters which Calc can execute as a sequence of keystrokes. -This switches into the Calc buffer for the duration of the macro. -For example, @samp{(calc-eval "vx5\rVR+" 'macro)} pushes the -vector @samp{[1,2,3,4,5]} on the stack and then replaces it -with the sum of those numbers. Note that @samp{\r} is the Lisp -notation for the carriage-return, @key{RET}, character. - -If your keyboard macro wishes to pop the stack, @samp{\C-d} is -safer than @samp{\177} (the @key{DEL} character) because some -installations may have switched the meanings of @key{DEL} and -@kbd{C-h}. Calc always interprets @kbd{C-d} as a synonym for -``pop-stack'' regardless of key mapping. - -If you provide a third argument to @code{calc-eval}, evaluation -of the keyboard macro will leave a record in the Trail using -that argument as a tag string. Normally the Trail is unaffected. - -The return value in this case is always @code{nil}. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Lisp Evaluation - -@noindent -Finally, if the separator symbol is @code{eval}, then the Lisp -@code{eval} function is called on the first argument, which must -be a Lisp expression rather than a Calc formula. Remember to -quote the expression so that it is not evaluated until inside -@code{calc-eval}. - -The difference from plain @code{eval} is that @code{calc-eval} -switches to the Calc buffer before evaluating the expression. -For example, @samp{(calc-eval '(setq calc-internal-prec 17) 'eval)} -will correctly affect the buffer-local Calc precision variable. - -An alternative would be @samp{(calc-eval '(calc-precision 17) 'eval)}. -This is evaluating a call to the function that is normally invoked -by the @kbd{p} key, giving it 17 as its ``numeric prefix argument.'' -Note that this function will leave a message in the echo area as -a side effect. Also, all Calc functions switch to the Calc buffer -automatically if not invoked from there, so the above call is -also equivalent to @samp{(calc-precision 17)} by itself. -In all cases, Calc uses @code{save-excursion} to switch back to -your original buffer when it is done. - -As usual the first argument can be a list that begins with a Lisp -expression to use default instead of current mode settings. - -The result of @code{calc-eval} in this usage is just the result -returned by the evaluated Lisp expression. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Example - -@noindent -@findex convert-temp -Here is a sample Emacs command that uses @code{calc-eval}. Suppose -you have a document with lots of references to temperatures on the -Fahrenheit scale, say ``98.6 F'', and you wish to convert these -references to Centigrade. The following command does this conversion. -Place the Emacs cursor right after the letter ``F'' and invoke the -command to change ``98.6 F'' to ``37 C''. Or, if the temperature is -already in Centigrade form, the command changes it back to Fahrenheit. - -@example -(defun convert-temp () - (interactive) - (save-excursion - (re-search-backward "[^-.0-9]\\([-.0-9]+\\) *\\([FC]\\)") - (let* ((top1 (match-beginning 1)) - (bot1 (match-end 1)) - (number (buffer-substring top1 bot1)) - (top2 (match-beginning 2)) - (bot2 (match-end 2)) - (type (buffer-substring top2 bot2))) - (if (equal type "F") - (setq type "C" - number (calc-eval "($ - 32)*5/9" nil number)) - (setq type "F" - number (calc-eval "$*9/5 + 32" nil number))) - (goto-char top2) - (delete-region top2 bot2) - (insert-before-markers type) - (goto-char top1) - (delete-region top1 bot1) - (if (string-match "\\.$" number) ; change "37." to "37" - (setq number (substring number 0 -1))) - (insert number)))) -@end example - -Note the use of @code{insert-before-markers} when changing between -``F'' and ``C'', so that the character winds up before the cursor -instead of after it. - -@node Internals, , Calling Calc from Your Programs, Lisp Definitions -@subsection Calculator Internals - -@noindent -This section describes the Lisp functions defined by the Calculator that -may be of use to user-written Calculator programs (as described in the -rest of this chapter). These functions are shown by their names as they -conventionally appear in @code{defmath}. Their full Lisp names are -generally gotten by prepending @samp{calcFunc-} or @samp{math-} to their -apparent names. (Names that begin with @samp{calc-} are already in -their full Lisp form.) You can use the actual full names instead if you -prefer them, or if you are calling these functions from regular Lisp. - -The functions described here are scattered throughout the various -Calc component files. Note that @file{calc.el} includes @code{autoload}s -for only a few component files; when Calc wants to call an advanced -function it calls @samp{(calc-extensions)} first; this function -autoloads @file{calc-ext.el}, which in turn autoloads all the functions -in the remaining component files. - -Because @code{defmath} itself uses the extensions, user-written code -generally always executes with the extensions already loaded, so -normally you can use any Calc function and be confident that it will -be autoloaded for you when necessary. If you are doing something -special, check carefully to make sure each function you are using is -from @file{calc.el} or its components, and call @samp{(calc-extensions)} -before using any function based in @file{calc-ext.el} if you can't -prove this file will already be loaded. - -@menu -* Data Type Formats:: -* Interactive Lisp Functions:: -* Stack Lisp Functions:: -* Predicates:: -* Computational Lisp Functions:: -* Vector Lisp Functions:: -* Symbolic Lisp Functions:: -* Formatting Lisp Functions:: -* Hooks:: -@end menu - -@node Data Type Formats, Interactive Lisp Functions, Internals, Internals -@subsubsection Data Type Formats - -@noindent -Integers are stored in either of two ways, depending on their magnitude. -Integers less than one million in absolute value are stored as standard -Lisp integers. This is the only storage format for Calc data objects -which is not a Lisp list. - -Large integers are stored as lists of the form @samp{(bigpos @var{d0} -@var{d1} @var{d2} @dots{})} for positive integers 1000000 or more, or -@samp{(bigneg @var{d0} @var{d1} @var{d2} @dots{})} for negative integers -@mathit{-1000000} or less. Each @var{d} is a base-1000 ``digit,'' a Lisp integer -from 0 to 999. The least significant digit is @var{d0}; the last digit, -@var{dn}, which is always nonzero, is the most significant digit. For -example, the integer @mathit{-12345678} is stored as @samp{(bigneg 678 345 12)}. - -The distinction between small and large integers is entirely hidden from -the user. In @code{defmath} definitions, the Lisp predicate @code{integerp} -returns true for either kind of integer, and in general both big and small -integers are accepted anywhere the word ``integer'' is used in this manual. -If the distinction must be made, native Lisp integers are called @dfn{fixnums} -and large integers are called @dfn{bignums}. - -Fractions are stored as a list of the form, @samp{(frac @var{n} @var{d})} -where @var{n} is an integer (big or small) numerator, @var{d} is an -integer denominator greater than one, and @var{n} and @var{d} are relatively -prime. Note that fractions where @var{d} is one are automatically converted -to plain integers by all math routines; fractions where @var{d} is negative -are normalized by negating the numerator and denominator. - -Floating-point numbers are stored in the form, @samp{(float @var{mant} -@var{exp})}, where @var{mant} (the ``mantissa'') is an integer less than -@samp{10^@var{p}} in absolute value (@var{p} represents the current -precision), and @var{exp} (the ``exponent'') is a fixnum. The value of -the float is @samp{@var{mant} * 10^@var{exp}}. For example, the number -@mathit{-3.14} is stored as @samp{(float -314 -2) = -314*10^-2}. Other constraints -are that the number 0.0 is always stored as @samp{(float 0 0)}, and, -except for the 0.0 case, the rightmost base-10 digit of @var{mant} is -always nonzero. (If the rightmost digit is zero, the number is -rearranged by dividing @var{mant} by ten and incrementing @var{exp}.) - -Rectangular complex numbers are stored in the form @samp{(cplx @var{re} -@var{im})}, where @var{re} and @var{im} are each real numbers, either -integers, fractions, or floats. The value is @samp{@var{re} + @var{im}i}. -The @var{im} part is nonzero; complex numbers with zero imaginary -components are converted to real numbers automatically. - -Polar complex numbers are stored in the form @samp{(polar @var{r} -@var{theta})}, where @var{r} is a positive real value and @var{theta} -is a real value or HMS form representing an angle. This angle is -usually normalized to lie in the interval @samp{(-180 ..@: 180)} degrees, -or @samp{(-pi ..@: pi)} radians, according to the current angular mode. -If the angle is 0 the value is converted to a real number automatically. -(If the angle is 180 degrees, the value is usually also converted to a -negative real number.) - -Hours-minutes-seconds forms are stored as @samp{(hms @var{h} @var{m} -@var{s})}, where @var{h} is an integer or an integer-valued float (i.e., -a float with @samp{@var{exp} >= 0}), @var{m} is an integer or integer-valued -float in the range @w{@samp{[0 ..@: 60)}}, and @var{s} is any real number -in the range @samp{[0 ..@: 60)}. - -Date forms are stored as @samp{(date @var{n})}, where @var{n} is -a real number that counts days since midnight on the morning of -January 1, 1 AD. If @var{n} is an integer, this is a pure date -form. If @var{n} is a fraction or float, this is a date/time form. - -Modulo forms are stored as @samp{(mod @var{n} @var{m})}, where @var{m} is a -positive real number or HMS form, and @var{n} is a real number or HMS -form in the range @samp{[0 ..@: @var{m})}. - -Error forms are stored as @samp{(sdev @var{x} @var{sigma})}, where @var{x} -is the mean value and @var{sigma} is the standard deviation. Each -component is either a number, an HMS form, or a symbolic object -(a variable or function call). If @var{sigma} is zero, the value is -converted to a plain real number. If @var{sigma} is negative or -complex, it is automatically normalized to be a positive real. - -Interval forms are stored as @samp{(intv @var{mask} @var{lo} @var{hi})}, -where @var{mask} is one of the integers 0, 1, 2, or 3, and @var{lo} and -@var{hi} are real numbers, HMS forms, or symbolic objects. The @var{mask} -is a binary integer where 1 represents the fact that the interval is -closed on the high end, and 2 represents the fact that it is closed on -the low end. (Thus 3 represents a fully closed interval.) The interval -@w{@samp{(intv 3 @var{x} @var{x})}} is converted to the plain number @var{x}; -intervals @samp{(intv @var{mask} @var{x} @var{x})} for any other @var{mask} -represent empty intervals. If @var{hi} is less than @var{lo}, the interval -is converted to a standard empty interval by replacing @var{hi} with @var{lo}. - -Vectors are stored as @samp{(vec @var{v1} @var{v2} @dots{})}, where @var{v1} -is the first element of the vector, @var{v2} is the second, and so on. -An empty vector is stored as @samp{(vec)}. A matrix is simply a vector -where all @var{v}'s are themselves vectors of equal lengths. Note that -Calc vectors are unrelated to the Emacs Lisp ``vector'' type, which is -generally unused by Calc data structures. - -Variables are stored as @samp{(var @var{name} @var{sym})}, where -@var{name} is a Lisp symbol whose print name is used as the visible name -of the variable, and @var{sym} is a Lisp symbol in which the variable's -value is actually stored. Thus, @samp{(var pi var-pi)} represents the -special constant @samp{pi}. Almost always, the form is @samp{(var -@var{v} var-@var{v})}. If the variable name was entered with @code{#} -signs (which are converted to hyphens internally), the form is -@samp{(var @var{u} @var{v})}, where @var{u} is a symbol whose name -contains @code{#} characters, and @var{v} is a symbol that contains -@code{-} characters instead. The value of a variable is the Calc -object stored in its @var{sym} symbol's value cell. If the symbol's -value cell is void or if it contains @code{nil}, the variable has no -value. Special constants have the form @samp{(special-const -@var{value})} stored in their value cell, where @var{value} is a formula -which is evaluated when the constant's value is requested. Variables -which represent units are not stored in any special way; they are units -only because their names appear in the units table. If the value -cell contains a string, it is parsed to get the variable's value when -the variable is used. - -A Lisp list with any other symbol as the first element is a function call. -The symbols @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^}, -and @code{|} represent special binary operators; these lists are always -of the form @samp{(@var{op} @var{lhs} @var{rhs})} where @var{lhs} is the -sub-formula on the lefthand side and @var{rhs} is the sub-formula on the -right. The symbol @code{neg} represents unary negation; this list is always -of the form @samp{(neg @var{arg})}. Any other symbol @var{func} represents a -function that would be displayed in function-call notation; the symbol -@var{func} is in general always of the form @samp{calcFunc-@var{name}}. -The function cell of the symbol @var{func} should contain a Lisp function -for evaluating a call to @var{func}. This function is passed the remaining -elements of the list (themselves already evaluated) as arguments; such -functions should return @code{nil} or call @code{reject-arg} to signify -that they should be left in symbolic form, or they should return a Calc -object which represents their value, or a list of such objects if they -wish to return multiple values. (The latter case is allowed only for -functions which are the outer-level call in an expression whose value is -about to be pushed on the stack; this feature is considered obsolete -and is not used by any built-in Calc functions.) - -@node Interactive Lisp Functions, Stack Lisp Functions, Data Type Formats, Internals -@subsubsection Interactive Functions - -@noindent -The functions described here are used in implementing interactive Calc -commands. Note that this list is not exhaustive! If there is an -existing command that behaves similarly to the one you want to define, -you may find helpful tricks by checking the source code for that command. - -@defun calc-set-command-flag flag -Set the command flag @var{flag}. This is generally a Lisp symbol, but -may in fact be anything. The effect is to add @var{flag} to the list -stored in the variable @code{calc-command-flags}, unless it is already -there. @xref{Defining Simple Commands}. -@end defun - -@defun calc-clear-command-flag flag -If @var{flag} appears among the list of currently-set command flags, -remove it from that list. -@end defun - -@defun calc-record-undo rec -Add the ``undo record'' @var{rec} to the list of steps to take if the -current operation should need to be undone. Stack push and pop functions -automatically call @code{calc-record-undo}, so the kinds of undo records -you might need to create take the form @samp{(set @var{sym} @var{value})}, -which says that the Lisp variable @var{sym} was changed and had previously -contained @var{value}; @samp{(store @var{var} @var{value})} which says that -the Calc variable @var{var} (a string which is the name of the symbol that -contains the variable's value) was stored and its previous value was -@var{value} (either a Calc data object, or @code{nil} if the variable was -previously void); or @samp{(eval @var{undo} @var{redo} @var{args} @dots{})}, -which means that to undo requires calling the function @samp{(@var{undo} -@var{args} @dots{})} and, if the undo is later redone, calling -@samp{(@var{redo} @var{args} @dots{})}. -@end defun - -@defun calc-record-why msg args -Record the error or warning message @var{msg}, which is normally a string. -This message will be replayed if the user types @kbd{w} (@code{calc-why}); -if the message string begins with a @samp{*}, it is considered important -enough to display even if the user doesn't type @kbd{w}. If one or more -@var{args} are present, the displayed message will be of the form, -@samp{@var{msg}: @var{arg1}, @var{arg2}, @dots{}}, where the arguments are -formatted on the assumption that they are either strings or Calc objects of -some sort. If @var{msg} is a symbol, it is the name of a Calc predicate -(such as @code{integerp} or @code{numvecp}) which the arguments did not -satisfy; it is expanded to a suitable string such as ``Expected an -integer.'' The @code{reject-arg} function calls @code{calc-record-why} -automatically; @pxref{Predicates}. -@end defun - -@defun calc-is-inverse -This predicate returns true if the current command is inverse, -i.e., if the Inverse (@kbd{I} key) flag was set. -@end defun - -@defun calc-is-hyperbolic -This predicate is the analogous function for the @kbd{H} key. -@end defun - -@node Stack Lisp Functions, Predicates, Interactive Lisp Functions, Internals -@subsubsection Stack-Oriented Functions - -@noindent -The functions described here perform various operations on the Calc -stack and trail. They are to be used in interactive Calc commands. - -@defun calc-push-list vals n -Push the Calc objects in list @var{vals} onto the stack at stack level -@var{n}. If @var{n} is omitted it defaults to 1, so that the elements -are pushed at the top of the stack. If @var{n} is greater than 1, the -elements will be inserted into the stack so that the last element will -end up at level @var{n}, the next-to-last at level @var{n}+1, etc. -The elements of @var{vals} are assumed to be valid Calc objects, and -are not evaluated, rounded, or renormalized in any way. If @var{vals} -is an empty list, nothing happens. - -The stack elements are pushed without any sub-formula selections. -You can give an optional third argument to this function, which must -be a list the same size as @var{vals} of selections. Each selection -must be @code{eq} to some sub-formula of the corresponding formula -in @var{vals}, or @code{nil} if that formula should have no selection. -@end defun - -@defun calc-top-list n m -Return a list of the @var{n} objects starting at level @var{m} of the -stack. If @var{m} is omitted it defaults to 1, so that the elements are -taken from the top of the stack. If @var{n} is omitted, it also -defaults to 1, so that the top stack element (in the form of a -one-element list) is returned. If @var{m} is greater than 1, the -@var{m}th stack element will be at the end of the list, the @var{m}+1st -element will be next-to-last, etc. If @var{n} or @var{m} are out of -range, the command is aborted with a suitable error message. If @var{n} -is zero, the function returns an empty list. The stack elements are not -evaluated, rounded, or renormalized. - -If any stack elements contain selections, and selections have not -been disabled by the @kbd{j e} (@code{calc-enable-selections}) command, -this function returns the selected portions rather than the entire -stack elements. It can be given a third ``selection-mode'' argument -which selects other behaviors. If it is the symbol @code{t}, then -a selection in any of the requested stack elements produces an -``invalid operation on selections'' error. If it is the symbol @code{full}, -the whole stack entry is always returned regardless of selections. -If it is the symbol @code{sel}, the selected portion is always returned, -or @code{nil} if there is no selection. (This mode ignores the @kbd{j e} -command.) If the symbol is @code{entry}, the complete stack entry in -list form is returned; the first element of this list will be the whole -formula, and the third element will be the selection (or @code{nil}). -@end defun - -@defun calc-pop-stack n m -Remove the specified elements from the stack. The parameters @var{n} -and @var{m} are defined the same as for @code{calc-top-list}. The return -value of @code{calc-pop-stack} is uninteresting. - -If there are any selected sub-formulas among the popped elements, and -@kbd{j e} has not been used to disable selections, this produces an -error without changing the stack. If you supply an optional third -argument of @code{t}, the stack elements are popped even if they -contain selections. -@end defun - -@defun calc-record-list vals tag -This function records one or more results in the trail. The @var{vals} -are a list of strings or Calc objects. The @var{tag} is the four-character -tag string to identify the values. If @var{tag} is omitted, a blank tag -will be used. -@end defun - -@defun calc-normalize n -This function takes a Calc object and ``normalizes'' it. At the very -least this involves re-rounding floating-point values according to the -current precision and other similar jobs. Also, unless the user has -selected No-Simplify mode (@pxref{Simplification Modes}), this involves -actually evaluating a formula object by executing the function calls -it contains, and possibly also doing algebraic simplification, etc. -@end defun - -@defun calc-top-list-n n m -This function is identical to @code{calc-top-list}, except that it calls -@code{calc-normalize} on the values that it takes from the stack. They -are also passed through @code{check-complete}, so that incomplete -objects will be rejected with an error message. All computational -commands should use this in preference to @code{calc-top-list}; the only -standard Calc commands that operate on the stack without normalizing -are stack management commands like @code{calc-enter} and @code{calc-roll-up}. -This function accepts the same optional selection-mode argument as -@code{calc-top-list}. -@end defun - -@defun calc-top-n m -This function is a convenient form of @code{calc-top-list-n} in which only -a single element of the stack is taken and returned, rather than a list -of elements. This also accepts an optional selection-mode argument. -@end defun - -@defun calc-enter-result n tag vals -This function is a convenient interface to most of the above functions. -The @var{vals} argument should be either a single Calc object, or a list -of Calc objects; the object or objects are normalized, and the top @var{n} -stack entries are replaced by the normalized objects. If @var{tag} is -non-@code{nil}, the normalized objects are also recorded in the trail. -A typical stack-based computational command would take the form, - -@smallexample -(calc-enter-result @var{n} @var{tag} (cons 'calcFunc-@var{func} - (calc-top-list-n @var{n}))) -@end smallexample - -If any of the @var{n} stack elements replaced contain sub-formula -selections, and selections have not been disabled by @kbd{j e}, -this function takes one of two courses of action. If @var{n} is -equal to the number of elements in @var{vals}, then each element of -@var{vals} is spliced into the corresponding selection; this is what -happens when you use the @key{TAB} key, or when you use a unary -arithmetic operation like @code{sqrt}. If @var{vals} has only one -element but @var{n} is greater than one, there must be only one -selection among the top @var{n} stack elements; the element from -@var{vals} is spliced into that selection. This is what happens when -you use a binary arithmetic operation like @kbd{+}. Any other -combination of @var{n} and @var{vals} is an error when selections -are present. -@end defun - -@defun calc-unary-op tag func arg -This function implements a unary operator that allows a numeric prefix -argument to apply the operator over many stack entries. If the prefix -argument @var{arg} is @code{nil}, this uses @code{calc-enter-result} -as outlined above. Otherwise, it maps the function over several stack -elements; @pxref{Prefix Arguments}. For example, - -@smallexample -(defun calc-zeta (arg) - (interactive "P") - (calc-unary-op "zeta" 'calcFunc-zeta arg)) -@end smallexample -@end defun - -@defun calc-binary-op tag func arg ident unary -This function implements a binary operator, analogously to -@code{calc-unary-op}. The optional @var{ident} and @var{unary} -arguments specify the behavior when the prefix argument is zero or -one, respectively. If the prefix is zero, the value @var{ident} -is pushed onto the stack, if specified, otherwise an error message -is displayed. If the prefix is one, the unary function @var{unary} -is applied to the top stack element, or, if @var{unary} is not -specified, nothing happens. When the argument is two or more, -the binary function @var{func} is reduced across the top @var{arg} -stack elements; when the argument is negative, the function is -mapped between the next-to-top @mathit{-@var{arg}} stack elements and the -top element. -@end defun - -@defun calc-stack-size -Return the number of elements on the stack as an integer. This count -does not include elements that have been temporarily hidden by stack -truncation; @pxref{Truncating the Stack}. -@end defun - -@defun calc-cursor-stack-index n -Move the point to the @var{n}th stack entry. If @var{n} is zero, this -will be the @samp{.} line. If @var{n} is from 1 to the current stack size, -this will be the beginning of the first line of that stack entry's display. -If line numbers are enabled, this will move to the first character of the -line number, not the stack entry itself. -@end defun - -@defun calc-substack-height n -Return the number of lines between the beginning of the @var{n}th stack -entry and the bottom of the buffer. If @var{n} is zero, this -will be one (assuming no stack truncation). If all stack entries are -one line long (i.e., no matrices are displayed), the return value will -be equal @var{n}+1 as long as @var{n} is in range. (Note that in Big -mode, the return value includes the blank lines that separate stack -entries.) -@end defun - -@defun calc-refresh -Erase the @code{*Calculator*} buffer and reformat its contents from memory. -This must be called after changing any parameter, such as the current -display radix, which might change the appearance of existing stack -entries. (During a keyboard macro invoked by the @kbd{X} key, refreshing -is suppressed, but a flag is set so that the entire stack will be refreshed -rather than just the top few elements when the macro finishes.) -@end defun - -@node Predicates, Computational Lisp Functions, Stack Lisp Functions, Internals -@subsubsection Predicates - -@noindent -The functions described here are predicates, that is, they return a -true/false value where @code{nil} means false and anything else means -true. These predicates are expanded by @code{defmath}, for example, -from @code{zerop} to @code{math-zerop}. In many cases they correspond -to native Lisp functions by the same name, but are extended to cover -the full range of Calc data types. - -@defun zerop x -Returns true if @var{x} is numerically zero, in any of the Calc data -types. (Note that for some types, such as error forms and intervals, -it never makes sense to return true.) In @code{defmath}, the expression -@samp{(= x 0)} will automatically be converted to @samp{(math-zerop x)}, -and @samp{(/= x 0)} will be converted to @samp{(not (math-zerop x))}. -@end defun - -@defun negp x -Returns true if @var{x} is negative. This accepts negative real numbers -of various types, negative HMS and date forms, and intervals in which -all included values are negative. In @code{defmath}, the expression -@samp{(< x 0)} will automatically be converted to @samp{(math-negp x)}, -and @samp{(>= x 0)} will be converted to @samp{(not (math-negp x))}. -@end defun - -@defun posp x -Returns true if @var{x} is positive (and non-zero). For complex -numbers, none of these three predicates will return true. -@end defun - -@defun looks-negp x -Returns true if @var{x} is ``negative-looking.'' This returns true if -@var{x} is a negative number, or a formula with a leading minus sign -such as @samp{-a/b}. In other words, this is an object which can be -made simpler by calling @code{(- @var{x})}. -@end defun - -@defun integerp x -Returns true if @var{x} is an integer of any size. -@end defun - -@defun fixnump x -Returns true if @var{x} is a native Lisp integer. -@end defun - -@defun natnump x -Returns true if @var{x} is a nonnegative integer of any size. -@end defun - -@defun fixnatnump x -Returns true if @var{x} is a nonnegative Lisp integer. -@end defun - -@defun num-integerp x -Returns true if @var{x} is numerically an integer, i.e., either a -true integer or a float with no significant digits to the right of -the decimal point. -@end defun - -@defun messy-integerp x -Returns true if @var{x} is numerically, but not literally, an integer. -A value is @code{num-integerp} if it is @code{integerp} or -@code{messy-integerp} (but it is never both at once). -@end defun - -@defun num-natnump x -Returns true if @var{x} is numerically a nonnegative integer. -@end defun - -@defun evenp x -Returns true if @var{x} is an even integer. -@end defun - -@defun looks-evenp x -Returns true if @var{x} is an even integer, or a formula with a leading -multiplicative coefficient which is an even integer. -@end defun - -@defun oddp x -Returns true if @var{x} is an odd integer. -@end defun - -@defun ratp x -Returns true if @var{x} is a rational number, i.e., an integer or a -fraction. -@end defun - -@defun realp x -Returns true if @var{x} is a real number, i.e., an integer, fraction, -or floating-point number. -@end defun - -@defun anglep x -Returns true if @var{x} is a real number or HMS form. -@end defun - -@defun floatp x -Returns true if @var{x} is a float, or a complex number, error form, -interval, date form, or modulo form in which at least one component -is a float. -@end defun - -@defun complexp x -Returns true if @var{x} is a rectangular or polar complex number -(but not a real number). -@end defun - -@defun rect-complexp x -Returns true if @var{x} is a rectangular complex number. -@end defun - -@defun polar-complexp x -Returns true if @var{x} is a polar complex number. -@end defun - -@defun numberp x -Returns true if @var{x} is a real number or a complex number. -@end defun - -@defun scalarp x -Returns true if @var{x} is a real or complex number or an HMS form. -@end defun - -@defun vectorp x -Returns true if @var{x} is a vector (this simply checks if its argument -is a list whose first element is the symbol @code{vec}). -@end defun - -@defun numvecp x -Returns true if @var{x} is a number or vector. -@end defun - -@defun matrixp x -Returns true if @var{x} is a matrix, i.e., a vector of one or more vectors, -all of the same size. -@end defun - -@defun square-matrixp x -Returns true if @var{x} is a square matrix. -@end defun - -@defun objectp x -Returns true if @var{x} is any numeric Calc object, including real and -complex numbers, HMS forms, date forms, error forms, intervals, and -modulo forms. (Note that error forms and intervals may include formulas -as their components; see @code{constp} below.) -@end defun - -@defun objvecp x -Returns true if @var{x} is an object or a vector. This also accepts -incomplete objects, but it rejects variables and formulas (except as -mentioned above for @code{objectp}). -@end defun - -@defun primp x -Returns true if @var{x} is a ``primitive'' or ``atomic'' Calc object, -i.e., one whose components cannot be regarded as sub-formulas. This -includes variables, and all @code{objectp} types except error forms -and intervals. -@end defun - -@defun constp x -Returns true if @var{x} is constant, i.e., a real or complex number, -HMS form, date form, or error form, interval, or vector all of whose -components are @code{constp}. -@end defun - -@defun lessp x y -Returns true if @var{x} is numerically less than @var{y}. Returns false -if @var{x} is greater than or equal to @var{y}, or if the order is -undefined or cannot be determined. Generally speaking, this works -by checking whether @samp{@var{x} - @var{y}} is @code{negp}. In -@code{defmath}, the expression @samp{(< x y)} will automatically be -converted to @samp{(lessp x y)}; expressions involving @code{>}, @code{<=}, -and @code{>=} are similarly converted in terms of @code{lessp}. -@end defun - -@defun beforep x y -Returns true if @var{x} comes before @var{y} in a canonical ordering -of Calc objects. If @var{x} and @var{y} are both real numbers, this -will be the same as @code{lessp}. But whereas @code{lessp} considers -other types of objects to be unordered, @code{beforep} puts any two -objects into a definite, consistent order. The @code{beforep} -function is used by the @kbd{V S} vector-sorting command, and also -by @kbd{a s} to put the terms of a product into canonical order: -This allows @samp{x y + y x} to be simplified easily to @samp{2 x y}. -@end defun - -@defun equal x y -This is the standard Lisp @code{equal} predicate; it returns true if -@var{x} and @var{y} are structurally identical. This is the usual way -to compare numbers for equality, but note that @code{equal} will treat -0 and 0.0 as different. -@end defun - -@defun math-equal x y -Returns true if @var{x} and @var{y} are numerically equal, either because -they are @code{equal}, or because their difference is @code{zerop}. In -@code{defmath}, the expression @samp{(= x y)} will automatically be -converted to @samp{(math-equal x y)}. -@end defun - -@defun equal-int x n -Returns true if @var{x} and @var{n} are numerically equal, where @var{n} -is a fixnum which is not a multiple of 10. This will automatically be -used by @code{defmath} in place of the more general @code{math-equal} -whenever possible. -@end defun - -@defun nearly-equal x y -Returns true if @var{x} and @var{y}, as floating-point numbers, are -equal except possibly in the last decimal place. For example, -314.159 and 314.166 are considered nearly equal if the current -precision is 6 (since they differ by 7 units), but not if the current -precision is 7 (since they differ by 70 units). Most functions which -use series expansions use @code{with-extra-prec} to evaluate the -series with 2 extra digits of precision, then use @code{nearly-equal} -to decide when the series has converged; this guards against cumulative -error in the series evaluation without doing extra work which would be -lost when the result is rounded back down to the current precision. -In @code{defmath}, this can be written @samp{(~= @var{x} @var{y})}. -The @var{x} and @var{y} can be numbers of any kind, including complex. -@end defun - -@defun nearly-zerop x y -Returns true if @var{x} is nearly zero, compared to @var{y}. This -checks whether @var{x} plus @var{y} would by be @code{nearly-equal} -to @var{y} itself, to within the current precision, in other words, -if adding @var{x} to @var{y} would have a negligible effect on @var{y} -due to roundoff error. @var{X} may be a real or complex number, but -@var{y} must be real. -@end defun - -@defun is-true x -Return true if the formula @var{x} represents a true value in -Calc, not Lisp, terms. It tests if @var{x} is a non-zero number -or a provably non-zero formula. -@end defun - -@defun reject-arg val pred -Abort the current function evaluation due to unacceptable argument values. -This calls @samp{(calc-record-why @var{pred} @var{val})}, then signals a -Lisp error which @code{normalize} will trap. The net effect is that the -function call which led here will be left in symbolic form. -@end defun - -@defun inexact-value -If Symbolic mode is enabled, this will signal an error that causes -@code{normalize} to leave the formula in symbolic form, with the message -``Inexact result.'' (This function has no effect when not in Symbolic mode.) -Note that if your function calls @samp{(sin 5)} in Symbolic mode, the -@code{sin} function will call @code{inexact-value}, which will cause your -function to be left unsimplified. You may instead wish to call -@samp{(normalize (list 'calcFunc-sin 5))}, which in Symbolic mode will -return the formula @samp{sin(5)} to your function. -@end defun - -@defun overflow -This signals an error that will be reported as a floating-point overflow. -@end defun - -@defun underflow -This signals a floating-point underflow. -@end defun - -@node Computational Lisp Functions, Vector Lisp Functions, Predicates, Internals -@subsubsection Computational Functions - -@noindent -The functions described here do the actual computational work of the -Calculator. In addition to these, note that any function described in -the main body of this manual may be called from Lisp; for example, if -the documentation refers to the @code{calc-sqrt} [@code{sqrt}] command, -this means @code{calc-sqrt} is an interactive stack-based square-root -command and @code{sqrt} (which @code{defmath} expands to @code{calcFunc-sqrt}) -is the actual Lisp function for taking square roots. - -The functions @code{math-add}, @code{math-sub}, @code{math-mul}, -@code{math-div}, @code{math-mod}, and @code{math-neg} are not included -in this list, since @code{defmath} allows you to write native Lisp -@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, and unary @code{-}, -respectively, instead. - -@defun normalize val -(Full form: @code{math-normalize}.) -Reduce the value @var{val} to standard form. For example, if @var{val} -is a fixnum, it will be converted to a bignum if it is too large, and -if @var{val} is a bignum it will be normalized by clipping off trailing -(i.e., most-significant) zero digits and converting to a fixnum if it is -small. All the various data types are similarly converted to their standard -forms. Variables are left alone, but function calls are actually evaluated -in formulas. For example, normalizing @samp{(+ 2 (calcFunc-abs -4))} will -return 6. - -If a function call fails, because the function is void or has the wrong -number of parameters, or because it returns @code{nil} or calls -@code{reject-arg} or @code{inexact-result}, @code{normalize} returns -the formula still in symbolic form. - -If the current simplification mode is ``none'' or ``numeric arguments -only,'' @code{normalize} will act appropriately. However, the more -powerful simplification modes (like Algebraic Simplification) are -not handled by @code{normalize}. They are handled by @code{calc-normalize}, -which calls @code{normalize} and possibly some other routines, such -as @code{simplify} or @code{simplify-units}. Programs generally will -never call @code{calc-normalize} except when popping or pushing values -on the stack. -@end defun - -@defun evaluate-expr expr -Replace all variables in @var{expr} that have values with their values, -then use @code{normalize} to simplify the result. This is what happens -when you press the @kbd{=} key interactively. -@end defun - -@defmac with-extra-prec n body -Evaluate the Lisp forms in @var{body} with precision increased by @var{n} -digits. This is a macro which expands to - -@smallexample -(math-normalize - (let ((calc-internal-prec (+ calc-internal-prec @var{n}))) - @var{body})) -@end smallexample - -The surrounding call to @code{math-normalize} causes a floating-point -result to be rounded down to the original precision afterwards. This -is important because some arithmetic operations assume a number's -mantissa contains no more digits than the current precision allows. -@end defmac - -@defun make-frac n d -Build a fraction @samp{@var{n}:@var{d}}. This is equivalent to calling -@samp{(normalize (list 'frac @var{n} @var{d}))}, but more efficient. -@end defun - -@defun make-float mant exp -Build a floating-point value out of @var{mant} and @var{exp}, both -of which are arbitrary integers. This function will return a -properly normalized float value, or signal an overflow or underflow -if @var{exp} is out of range. -@end defun - -@defun make-sdev x sigma -Build an error form out of @var{x} and the absolute value of @var{sigma}. -If @var{sigma} is zero, the result is the number @var{x} directly. -If @var{sigma} is negative or complex, its absolute value is used. -If @var{x} or @var{sigma} is not a valid type of object for use in -error forms, this calls @code{reject-arg}. -@end defun - -@defun make-intv mask lo hi -Build an interval form out of @var{mask} (which is assumed to be an -integer from 0 to 3), and the limits @var{lo} and @var{hi}. If -@var{lo} is greater than @var{hi}, an empty interval form is returned. -This calls @code{reject-arg} if @var{lo} or @var{hi} is unsuitable. -@end defun - -@defun sort-intv mask lo hi -Build an interval form, similar to @code{make-intv}, except that if -@var{lo} is less than @var{hi} they are simply exchanged, and the -bits of @var{mask} are swapped accordingly. -@end defun - -@defun make-mod n m -Build a modulo form out of @var{n} and the modulus @var{m}. Since modulo -forms do not allow formulas as their components, if @var{n} or @var{m} -is not a real number or HMS form the result will be a formula which -is a call to @code{makemod}, the algebraic version of this function. -@end defun - -@defun float x -Convert @var{x} to floating-point form. Integers and fractions are -converted to numerically equivalent floats; components of complex -numbers, vectors, HMS forms, date forms, error forms, intervals, and -modulo forms are recursively floated. If the argument is a variable -or formula, this calls @code{reject-arg}. -@end defun - -@defun compare x y -Compare the numbers @var{x} and @var{y}, and return @mathit{-1} if -@samp{(lessp @var{x} @var{y})}, 1 if @samp{(lessp @var{y} @var{x})}, -0 if @samp{(math-equal @var{x} @var{y})}, or 2 if the order is -undefined or cannot be determined. -@end defun - -@defun numdigs n -Return the number of digits of integer @var{n}, effectively -@samp{ceil(log10(@var{n}))}, but much more efficient. Zero is -considered to have zero digits. -@end defun - -@defun scale-int x n -Shift integer @var{x} left @var{n} decimal digits, or right @mathit{-@var{n}} -digits with truncation toward zero. -@end defun - -@defun scale-rounding x n -Like @code{scale-int}, except that a right shift rounds to the nearest -integer rather than truncating. -@end defun - -@defun fixnum n -Return the integer @var{n} as a fixnum, i.e., a native Lisp integer. -If @var{n} is outside the permissible range for Lisp integers (usually -24 binary bits) the result is undefined. -@end defun - -@defun sqr x -Compute the square of @var{x}; short for @samp{(* @var{x} @var{x})}. -@end defun - -@defun quotient x y -Divide integer @var{x} by integer @var{y}; return an integer quotient -and discard the remainder. If @var{x} or @var{y} is negative, the -direction of rounding is undefined. -@end defun - -@defun idiv x y -Perform an integer division; if @var{x} and @var{y} are both nonnegative -integers, this uses the @code{quotient} function, otherwise it computes -@samp{floor(@var{x}/@var{y})}. Thus the result is well-defined but -slower than for @code{quotient}. -@end defun - -@defun imod x y -Divide integer @var{x} by integer @var{y}; return the integer remainder -and discard the quotient. Like @code{quotient}, this works only for -integer arguments and is not well-defined for negative arguments. -For a more well-defined result, use @samp{(% @var{x} @var{y})}. -@end defun - -@defun idivmod x y -Divide integer @var{x} by integer @var{y}; return a cons cell whose -@code{car} is @samp{(quotient @var{x} @var{y})} and whose @code{cdr} -is @samp{(imod @var{x} @var{y})}. -@end defun - -@defun pow x y -Compute @var{x} to the power @var{y}. In @code{defmath} code, this can -also be written @samp{(^ @var{x} @var{y})} or -@w{@samp{(expt @var{x} @var{y})}}. -@end defun - -@defun abs-approx x -Compute a fast approximation to the absolute value of @var{x}. For -example, for a rectangular complex number the result is the sum of -the absolute values of the components. -@end defun - -@findex e -@findex gamma-const -@findex ln-2 -@findex ln-10 -@findex phi -@findex pi-over-2 -@findex pi-over-4 -@findex pi-over-180 -@findex sqrt-two-pi -@findex sqrt-e -@findex two-pi -@defun pi -The function @samp{(pi)} computes @samp{pi} to the current precision. -Other related constant-generating functions are @code{two-pi}, -@code{pi-over-2}, @code{pi-over-4}, @code{pi-over-180}, @code{sqrt-two-pi}, -@code{e}, @code{sqrt-e}, @code{ln-2}, @code{ln-10}, @code{phi} and -@code{gamma-const}. Each function returns a floating-point value in the -current precision, and each uses caching so that all calls after the -first are essentially free. -@end defun - -@defmac math-defcache @var{func} @var{initial} @var{form} -This macro, usually used as a top-level call like @code{defun} or -@code{defvar}, defines a new cached constant analogous to @code{pi}, etc. -It defines a function @code{func} which returns the requested value; -if @var{initial} is non-@code{nil} it must be a @samp{(float @dots{})} -form which serves as an initial value for the cache. If @var{func} -is called when the cache is empty or does not have enough digits to -satisfy the current precision, the Lisp expression @var{form} is evaluated -with the current precision increased by four, and the result minus its -two least significant digits is stored in the cache. For example, -calling @samp{(pi)} with a precision of 30 computes @samp{pi} to 34 -digits, rounds it down to 32 digits for future use, then rounds it -again to 30 digits for use in the present request. -@end defmac - -@findex half-circle -@findex quarter-circle -@defun full-circle symb -If the current angular mode is Degrees or HMS, this function returns the -integer 360. In Radians mode, this function returns either the -corresponding value in radians to the current precision, or the formula -@samp{2*pi}, depending on the Symbolic mode. There are also similar -function @code{half-circle} and @code{quarter-circle}. -@end defun - -@defun power-of-2 n -Compute two to the integer power @var{n}, as a (potentially very large) -integer. Powers of two are cached, so only the first call for a -particular @var{n} is expensive. -@end defun - -@defun integer-log2 n -Compute the base-2 logarithm of @var{n}, which must be an integer which -is a power of two. If @var{n} is not a power of two, this function will -return @code{nil}. -@end defun - -@defun div-mod a b m -Divide @var{a} by @var{b}, modulo @var{m}. This returns @code{nil} if -there is no solution, or if any of the arguments are not integers. -@end defun - -@defun pow-mod a b m -Compute @var{a} to the power @var{b}, modulo @var{m}. If @var{a}, -@var{b}, and @var{m} are integers, this uses an especially efficient -algorithm. Otherwise, it simply computes @samp{(% (^ a b) m)}. -@end defun - -@defun isqrt n -Compute the integer square root of @var{n}. This is the square root -of @var{n} rounded down toward zero, i.e., @samp{floor(sqrt(@var{n}))}. -If @var{n} is itself an integer, the computation is especially efficient. -@end defun - -@defun to-hms a ang -Convert the argument @var{a} into an HMS form. If @var{ang} is specified, -it is the angular mode in which to interpret @var{a}, either @code{deg} -or @code{rad}. Otherwise, the current angular mode is used. If @var{a} -is already an HMS form it is returned as-is. -@end defun - -@defun from-hms a ang -Convert the HMS form @var{a} into a real number. If @var{ang} is specified, -it is the angular mode in which to express the result, otherwise the -current angular mode is used. If @var{a} is already a real number, it -is returned as-is. -@end defun - -@defun to-radians a -Convert the number or HMS form @var{a} to radians from the current -angular mode. -@end defun - -@defun from-radians a -Convert the number @var{a} from radians to the current angular mode. -If @var{a} is a formula, this returns the formula @samp{deg(@var{a})}. -@end defun - -@defun to-radians-2 a -Like @code{to-radians}, except that in Symbolic mode a degrees to -radians conversion yields a formula like @samp{@var{a}*pi/180}. -@end defun - -@defun from-radians-2 a -Like @code{from-radians}, except that in Symbolic mode a radians to -degrees conversion yields a formula like @samp{@var{a}*180/pi}. -@end defun - -@defun random-digit -Produce a random base-1000 digit in the range 0 to 999. -@end defun - -@defun random-digits n -Produce a random @var{n}-digit integer; this will be an integer -in the interval @samp{[0, 10^@var{n})}. -@end defun - -@defun random-float -Produce a random float in the interval @samp{[0, 1)}. -@end defun - -@defun prime-test n iters -Determine whether the integer @var{n} is prime. Return a list which has -one of these forms: @samp{(nil @var{f})} means the number is non-prime -because it was found to be divisible by @var{f}; @samp{(nil)} means it -was found to be non-prime by table look-up (so no factors are known); -@samp{(nil unknown)} means it is definitely non-prime but no factors -are known because @var{n} was large enough that Fermat's probabilistic -test had to be used; @samp{(t)} means the number is definitely prime; -and @samp{(maybe @var{i} @var{p})} means that Fermat's test, after @var{i} -iterations, is @var{p} percent sure that the number is prime. The -@var{iters} parameter is the number of Fermat iterations to use, in the -case that this is necessary. If @code{prime-test} returns ``maybe,'' -you can call it again with the same @var{n} to get a greater certainty; -@code{prime-test} remembers where it left off. -@end defun - -@defun to-simple-fraction f -If @var{f} is a floating-point number which can be represented exactly -as a small rational number. return that number, else return @var{f}. -For example, 0.75 would be converted to 3:4. This function is very -fast. -@end defun - -@defun to-fraction f tol -Find a rational approximation to floating-point number @var{f} to within -a specified tolerance @var{tol}; this corresponds to the algebraic -function @code{frac}, and can be rather slow. -@end defun - -@defun quarter-integer n -If @var{n} is an integer or integer-valued float, this function -returns zero. If @var{n} is a half-integer (i.e., an integer plus -@mathit{1:2} or 0.5), it returns 2. If @var{n} is a quarter-integer, -it returns 1 or 3. If @var{n} is anything else, this function -returns @code{nil}. -@end defun - -@node Vector Lisp Functions, Symbolic Lisp Functions, Computational Lisp Functions, Internals -@subsubsection Vector Functions - -@noindent -The functions described here perform various operations on vectors and -matrices. - -@defun math-concat x y -Do a vector concatenation; this operation is written @samp{@var{x} | @var{y}} -in a symbolic formula. @xref{Building Vectors}. -@end defun - -@defun vec-length v -Return the length of vector @var{v}. If @var{v} is not a vector, the -result is zero. If @var{v} is a matrix, this returns the number of -rows in the matrix. -@end defun - -@defun mat-dimens m -Determine the dimensions of vector or matrix @var{m}. If @var{m} is not -a vector, the result is an empty list. If @var{m} is a plain vector -but not a matrix, the result is a one-element list containing the length -of the vector. If @var{m} is a matrix with @var{r} rows and @var{c} columns, -the result is the list @samp{(@var{r} @var{c})}. Higher-order tensors -produce lists of more than two dimensions. Note that the object -@samp{[[1, 2, 3], [4, 5]]} is a vector of vectors not all the same size, -and is treated by this and other Calc routines as a plain vector of two -elements. -@end defun - -@defun dimension-error -Abort the current function with a message of ``Dimension error.'' -The Calculator will leave the function being evaluated in symbolic -form; this is really just a special case of @code{reject-arg}. -@end defun - -@defun build-vector args -Return a Calc vector with @var{args} as elements. -For example, @samp{(build-vector 1 2 3)} returns the Calc vector -@samp{[1, 2, 3]}, stored internally as the list @samp{(vec 1 2 3)}. -@end defun - -@defun make-vec obj dims -Return a Calc vector or matrix all of whose elements are equal to -@var{obj}. For example, @samp{(make-vec 27 3 4)} returns a 3x4 matrix -filled with 27's. -@end defun - -@defun row-matrix v -If @var{v} is a plain vector, convert it into a row matrix, i.e., -a matrix whose single row is @var{v}. If @var{v} is already a matrix, -leave it alone. -@end defun - -@defun col-matrix v -If @var{v} is a plain vector, convert it into a column matrix, i.e., a -matrix with each element of @var{v} as a separate row. If @var{v} is -already a matrix, leave it alone. -@end defun - -@defun map-vec f v -Map the Lisp function @var{f} over the Calc vector @var{v}. For example, -@samp{(map-vec 'math-floor v)} returns a vector of the floored components -of vector @var{v}. -@end defun - -@defun map-vec-2 f a b -Map the Lisp function @var{f} over the two vectors @var{a} and @var{b}. -If @var{a} and @var{b} are vectors of equal length, the result is a -vector of the results of calling @samp{(@var{f} @var{ai} @var{bi})} -for each pair of elements @var{ai} and @var{bi}. If either @var{a} or -@var{b} is a scalar, it is matched with each value of the other vector. -For example, @samp{(map-vec-2 'math-add v 1)} returns the vector @var{v} -with each element increased by one. Note that using @samp{'+} would not -work here, since @code{defmath} does not expand function names everywhere, -just where they are in the function position of a Lisp expression. -@end defun - -@defun reduce-vec f v -Reduce the function @var{f} over the vector @var{v}. For example, if -@var{v} is @samp{[10, 20, 30, 40]}, this calls @samp{(f (f (f 10 20) 30) 40)}. -If @var{v} is a matrix, this reduces over the rows of @var{v}. -@end defun - -@defun reduce-cols f m -Reduce the function @var{f} over the columns of matrix @var{m}. For -example, if @var{m} is @samp{[[1, 2], [3, 4], [5, 6]]}, the result -is a vector of the two elements @samp{(f (f 1 3) 5)} and @samp{(f (f 2 4) 6)}. -@end defun - -@defun mat-row m n -Return the @var{n}th row of matrix @var{m}. This is equivalent to -@samp{(elt m n)}. For a slower but safer version, use @code{mrow}. -(@xref{Extracting Elements}.) -@end defun - -@defun mat-col m n -Return the @var{n}th column of matrix @var{m}, in the form of a vector. -The arguments are not checked for correctness. -@end defun - -@defun mat-less-row m n -Return a copy of matrix @var{m} with its @var{n}th row deleted. The -number @var{n} must be in range from 1 to the number of rows in @var{m}. -@end defun - -@defun mat-less-col m n -Return a copy of matrix @var{m} with its @var{n}th column deleted. -@end defun - -@defun transpose m -Return the transpose of matrix @var{m}. -@end defun - -@defun flatten-vector v -Flatten nested vector @var{v} into a vector of scalars. For example, -if @var{v} is @samp{[[1, 2, 3], [4, 5]]} the result is @samp{[1, 2, 3, 4, 5]}. -@end defun - -@defun copy-matrix m -If @var{m} is a matrix, return a copy of @var{m}. This maps -@code{copy-sequence} over the rows of @var{m}; in Lisp terms, each -element of the result matrix will be @code{eq} to the corresponding -element of @var{m}, but none of the @code{cons} cells that make up -the structure of the matrix will be @code{eq}. If @var{m} is a plain -vector, this is the same as @code{copy-sequence}. -@end defun - -@defun swap-rows m r1 r2 -Exchange rows @var{r1} and @var{r2} of matrix @var{m} in-place. In -other words, unlike most of the other functions described here, this -function changes @var{m} itself rather than building up a new result -matrix. The return value is @var{m}, i.e., @samp{(eq (swap-rows m 1 2) m)} -is true, with the side effect of exchanging the first two rows of -@var{m}. -@end defun - -@node Symbolic Lisp Functions, Formatting Lisp Functions, Vector Lisp Functions, Internals -@subsubsection Symbolic Functions - -@noindent -The functions described here operate on symbolic formulas in the -Calculator. - -@defun calc-prepare-selection num -Prepare a stack entry for selection operations. If @var{num} is -omitted, the stack entry containing the cursor is used; otherwise, -it is the number of the stack entry to use. This function stores -useful information about the current stack entry into a set of -variables. @code{calc-selection-cache-num} contains the number of -the stack entry involved (equal to @var{num} if you specified it); -@code{calc-selection-cache-entry} contains the stack entry as a -list (such as @code{calc-top-list} would return with @code{entry} -as the selection mode); and @code{calc-selection-cache-comp} contains -a special ``tagged'' composition (@pxref{Formatting Lisp Functions}) -which allows Calc to relate cursor positions in the buffer with -their corresponding sub-formulas. - -A slight complication arises in the selection mechanism because -formulas may contain small integers. For example, in the vector -@samp{[1, 2, 1]} the first and last elements are @code{eq} to each -other; selections are recorded as the actual Lisp object that -appears somewhere in the tree of the whole formula, but storing -@code{1} would falsely select both @code{1}'s in the vector. So -@code{calc-prepare-selection} also checks the stack entry and -replaces any plain integers with ``complex number'' lists of the form -@samp{(cplx @var{n} 0)}. This list will be displayed the same as a -plain @var{n} and the change will be completely invisible to the -user, but it will guarantee that no two sub-formulas of the stack -entry will be @code{eq} to each other. Next time the stack entry -is involved in a computation, @code{calc-normalize} will replace -these lists with plain numbers again, again invisibly to the user. -@end defun - -@defun calc-encase-atoms x -This modifies the formula @var{x} to ensure that each part of the -formula is a unique atom, using the @samp{(cplx @var{n} 0)} trick -described above. This function may use @code{setcar} to modify -the formula in-place. -@end defun - -@defun calc-find-selected-part -Find the smallest sub-formula of the current formula that contains -the cursor. This assumes @code{calc-prepare-selection} has been -called already. If the cursor is not actually on any part of the -formula, this returns @code{nil}. -@end defun - -@defun calc-change-current-selection selection -Change the currently prepared stack element's selection to -@var{selection}, which should be @code{eq} to some sub-formula -of the stack element, or @code{nil} to unselect the formula. -The stack element's appearance in the Calc buffer is adjusted -to reflect the new selection. -@end defun - -@defun calc-find-nth-part expr n -Return the @var{n}th sub-formula of @var{expr}. This function is used -by the selection commands, and (unless @kbd{j b} has been used) treats -sums and products as flat many-element formulas. Thus if @var{expr} -is @samp{((a + b) - c) + d}, calling @code{calc-find-nth-part} with -@var{n} equal to four will return @samp{d}. -@end defun - -@defun calc-find-parent-formula expr part -Return the sub-formula of @var{expr} which immediately contains -@var{part}. If @var{expr} is @samp{a*b + (c+1)*d} and @var{part} -is @code{eq} to the @samp{c+1} term of @var{expr}, then this function -will return @samp{(c+1)*d}. If @var{part} turns out not to be a -sub-formula of @var{expr}, the function returns @code{nil}. If -@var{part} is @code{eq} to @var{expr}, the function returns @code{t}. -This function does not take associativity into account. -@end defun - -@defun calc-find-assoc-parent-formula expr part -This is the same as @code{calc-find-parent-formula}, except that -(unless @kbd{j b} has been used) it continues widening the selection -to contain a complete level of the formula. Given @samp{a} from -@samp{((a + b) - c) + d}, @code{calc-find-parent-formula} will -return @samp{a + b} but @code{calc-find-assoc-parent-formula} will -return the whole expression. -@end defun - -@defun calc-grow-assoc-formula expr part -This expands sub-formula @var{part} of @var{expr} to encompass a -complete level of the formula. If @var{part} and its immediate -parent are not compatible associative operators, or if @kbd{j b} -has been used, this simply returns @var{part}. -@end defun - -@defun calc-find-sub-formula expr part -This finds the immediate sub-formula of @var{expr} which contains -@var{part}. It returns an index @var{n} such that -@samp{(calc-find-nth-part @var{expr} @var{n})} would return @var{part}. -If @var{part} is not a sub-formula of @var{expr}, it returns @code{nil}. -If @var{part} is @code{eq} to @var{expr}, it returns @code{t}. This -function does not take associativity into account. -@end defun - -@defun calc-replace-sub-formula expr old new -This function returns a copy of formula @var{expr}, with the -sub-formula that is @code{eq} to @var{old} replaced by @var{new}. -@end defun - -@defun simplify expr -Simplify the expression @var{expr} by applying various algebraic rules. -This is what the @w{@kbd{a s}} (@code{calc-simplify}) command uses. This -always returns a copy of the expression; the structure @var{expr} points -to remains unchanged in memory. - -More precisely, here is what @code{simplify} does: The expression is -first normalized and evaluated by calling @code{normalize}. If any -@code{AlgSimpRules} have been defined, they are then applied. Then -the expression is traversed in a depth-first, bottom-up fashion; at -each level, any simplifications that can be made are made until no -further changes are possible. Once the entire formula has been -traversed in this way, it is compared with the original formula (from -before the call to @code{normalize}) and, if it has changed, -the entire procedure is repeated (starting with @code{normalize}) -until no further changes occur. Usually only two iterations are -needed:@: one to simplify the formula, and another to verify that no -further simplifications were possible. -@end defun - -@defun simplify-extended expr -Simplify the expression @var{expr}, with additional rules enabled that -help do a more thorough job, while not being entirely ``safe'' in all -circumstances. (For example, this mode will simplify @samp{sqrt(x^2)} -to @samp{x}, which is only valid when @var{x} is positive.) This is -implemented by temporarily binding the variable @code{math-living-dangerously} -to @code{t} (using a @code{let} form) and calling @code{simplify}. -Dangerous simplification rules are written to check this variable -before taking any action. -@end defun - -@defun simplify-units expr -Simplify the expression @var{expr}, treating variable names as units -whenever possible. This works by binding the variable -@code{math-simplifying-units} to @code{t} while calling @code{simplify}. -@end defun - -@defmac math-defsimplify funcs body -Register a new simplification rule; this is normally called as a top-level -form, like @code{defun} or @code{defmath}. If @var{funcs} is a symbol -(like @code{+} or @code{calcFunc-sqrt}), this simplification rule is -applied to the formulas which are calls to the specified function. Or, -@var{funcs} can be a list of such symbols; the rule applies to all -functions on the list. The @var{body} is written like the body of a -function with a single argument called @code{expr}. The body will be -executed with @code{expr} bound to a formula which is a call to one of -the functions @var{funcs}. If the function body returns @code{nil}, or -if it returns a result @code{equal} to the original @code{expr}, it is -ignored and Calc goes on to try the next simplification rule that applies. -If the function body returns something different, that new formula is -substituted for @var{expr} in the original formula. - -At each point in the formula, rules are tried in the order of the -original calls to @code{math-defsimplify}; the search stops after the -first rule that makes a change. Thus later rules for that same -function will not have a chance to trigger until the next iteration -of the main @code{simplify} loop. - -Note that, since @code{defmath} is not being used here, @var{body} must -be written in true Lisp code without the conveniences that @code{defmath} -provides. If you prefer, you can have @var{body} simply call another -function (defined with @code{defmath}) which does the real work. - -The arguments of a function call will already have been simplified -before any rules for the call itself are invoked. Since a new argument -list is consed up when this happens, this means that the rule's body is -allowed to rearrange the function's arguments destructively if that is -convenient. Here is a typical example of a simplification rule: - -@smallexample -(math-defsimplify calcFunc-arcsinh - (or (and (math-looks-negp (nth 1 expr)) - (math-neg (list 'calcFunc-arcsinh - (math-neg (nth 1 expr))))) - (and (eq (car-safe (nth 1 expr)) 'calcFunc-sinh) - (or math-living-dangerously - (math-known-realp (nth 1 (nth 1 expr)))) - (nth 1 (nth 1 expr))))) -@end smallexample - -This is really a pair of rules written with one @code{math-defsimplify} -for convenience; the first replaces @samp{arcsinh(-x)} with -@samp{-arcsinh(x)}, and the second, which is safe only for real @samp{x}, -replaces @samp{arcsinh(sinh(x))} with @samp{x}. -@end defmac - -@defun common-constant-factor expr -Check @var{expr} to see if it is a sum of terms all multiplied by the -same rational value. If so, return this value. If not, return @code{nil}. -For example, if called on @samp{6x + 9y + 12z}, it would return 3, since -3 is a common factor of all the terms. -@end defun - -@defun cancel-common-factor expr factor -Assuming @var{expr} is a sum with @var{factor} as a common factor, -divide each term of the sum by @var{factor}. This is done by -destructively modifying parts of @var{expr}, on the assumption that -it is being used by a simplification rule (where such things are -allowed; see above). For example, consider this built-in rule for -square roots: - -@smallexample -(math-defsimplify calcFunc-sqrt - (let ((fac (math-common-constant-factor (nth 1 expr)))) - (and fac (not (eq fac 1)) - (math-mul (math-normalize (list 'calcFunc-sqrt fac)) - (math-normalize - (list 'calcFunc-sqrt - (math-cancel-common-factor - (nth 1 expr) fac))))))) -@end smallexample -@end defun - -@defun frac-gcd a b -Compute a ``rational GCD'' of @var{a} and @var{b}, which must both be -rational numbers. This is the fraction composed of the GCD of the -numerators of @var{a} and @var{b}, over the GCD of the denominators. -It is used by @code{common-constant-factor}. Note that the standard -@code{gcd} function uses the LCM to combine the denominators. -@end defun - -@defun map-tree func expr many -Try applying Lisp function @var{func} to various sub-expressions of -@var{expr}. Initially, call @var{func} with @var{expr} itself as an -argument. If this returns an expression which is not @code{equal} to -@var{expr}, apply @var{func} again until eventually it does return -@var{expr} with no changes. Then, if @var{expr} is a function call, -recursively apply @var{func} to each of the arguments. This keeps going -until no changes occur anywhere in the expression; this final expression -is returned by @code{map-tree}. Note that, unlike simplification rules, -@var{func} functions may @emph{not} make destructive changes to -@var{expr}. If a third argument @var{many} is provided, it is an -integer which says how many times @var{func} may be applied; the -default, as described above, is infinitely many times. -@end defun - -@defun compile-rewrites rules -Compile the rewrite rule set specified by @var{rules}, which should -be a formula that is either a vector or a variable name. If the latter, -the compiled rules are saved so that later @code{compile-rules} calls -for that same variable can return immediately. If there are problems -with the rules, this function calls @code{error} with a suitable -message. -@end defun - -@defun apply-rewrites expr crules heads -Apply the compiled rewrite rule set @var{crules} to the expression -@var{expr}. This will make only one rewrite and only checks at the -top level of the expression. The result @code{nil} if no rules -matched, or if the only rules that matched did not actually change -the expression. The @var{heads} argument is optional; if is given, -it should be a list of all function names that (may) appear in -@var{expr}. The rewrite compiler tags each rule with the -rarest-looking function name in the rule; if you specify @var{heads}, -@code{apply-rewrites} can use this information to narrow its search -down to just a few rules in the rule set. -@end defun - -@defun rewrite-heads expr -Compute a @var{heads} list for @var{expr} suitable for use with -@code{apply-rewrites}, as discussed above. -@end defun - -@defun rewrite expr rules many -This is an all-in-one rewrite function. It compiles the rule set -specified by @var{rules}, then uses @code{map-tree} to apply the -rules throughout @var{expr} up to @var{many} (default infinity) -times. -@end defun - -@defun match-patterns pat vec not-flag -Given a Calc vector @var{vec} and an uncompiled pattern set or -pattern set variable @var{pat}, this function returns a new vector -of all elements of @var{vec} which do (or don't, if @var{not-flag} is -non-@code{nil}) match any of the patterns in @var{pat}. -@end defun - -@defun deriv expr var value symb -Compute the derivative of @var{expr} with respect to variable @var{var} -(which may actually be any sub-expression). If @var{value} is specified, -the derivative is evaluated at the value of @var{var}; otherwise, the -derivative is left in terms of @var{var}. If the expression contains -functions for which no derivative formula is known, new derivative -functions are invented by adding primes to the names; @pxref{Calculus}. -However, if @var{symb} is non-@code{nil}, the presence of nondifferentiable -functions in @var{expr} instead cancels the whole differentiation, and -@code{deriv} returns @code{nil} instead. - -Derivatives of an @var{n}-argument function can be defined by -adding a @code{math-derivative-@var{n}} property to the property list -of the symbol for the function's derivative, which will be the -function name followed by an apostrophe. The value of the property -should be a Lisp function; it is called with the same arguments as the -original function call that is being differentiated. It should return -a formula for the derivative. For example, the derivative of @code{ln} -is defined by - -@smallexample -(put 'calcFunc-ln\' 'math-derivative-1 - (function (lambda (u) (math-div 1 u)))) -@end smallexample - -The two-argument @code{log} function has two derivatives, -@smallexample -(put 'calcFunc-log\' 'math-derivative-2 ; d(log(x,b)) / dx - (function (lambda (x b) ... ))) -(put 'calcFunc-log\'2 'math-derivative-2 ; d(log(x,b)) / db - (function (lambda (x b) ... ))) -@end smallexample -@end defun - -@defun tderiv expr var value symb -Compute the total derivative of @var{expr}. This is the same as -@code{deriv}, except that variables other than @var{var} are not -assumed to be constant with respect to @var{var}. -@end defun - -@defun integ expr var low high -Compute the integral of @var{expr} with respect to @var{var}. -@xref{Calculus}, for further details. -@end defun - -@defmac math-defintegral funcs body -Define a rule for integrating a function or functions of one argument; -this macro is very similar in format to @code{math-defsimplify}. -The main difference is that here @var{body} is the body of a function -with a single argument @code{u} which is bound to the argument to the -function being integrated, not the function call itself. Also, the -variable of integration is available as @code{math-integ-var}. If -evaluation of the integral requires doing further integrals, the body -should call @samp{(math-integral @var{x})} to find the integral of -@var{x} with respect to @code{math-integ-var}; this function returns -@code{nil} if the integral could not be done. Some examples: - -@smallexample -(math-defintegral calcFunc-conj - (let ((int (math-integral u))) - (and int - (list 'calcFunc-conj int)))) - -(math-defintegral calcFunc-cos - (and (equal u math-integ-var) - (math-from-radians-2 (list 'calcFunc-sin u)))) -@end smallexample - -In the @code{cos} example, we define only the integral of @samp{cos(x) dx}, -relying on the general integration-by-substitution facility to handle -cosines of more complicated arguments. An integration rule should return -@code{nil} if it can't do the integral; if several rules are defined for -the same function, they are tried in order until one returns a non-@code{nil} -result. -@end defmac - -@defmac math-defintegral-2 funcs body -Define a rule for integrating a function or functions of two arguments. -This is exactly analogous to @code{math-defintegral}, except that @var{body} -is written as the body of a function with two arguments, @var{u} and -@var{v}. -@end defmac - -@defun solve-for lhs rhs var full -Attempt to solve the equation @samp{@var{lhs} = @var{rhs}} by isolating -the variable @var{var} on the lefthand side; return the resulting righthand -side, or @code{nil} if the equation cannot be solved. The variable -@var{var} must appear at least once in @var{lhs} or @var{rhs}. Note that -the return value is a formula which does not contain @var{var}; this is -different from the user-level @code{solve} and @code{finv} functions, -which return a rearranged equation or a functional inverse, respectively. -If @var{full} is non-@code{nil}, a full solution including dummy signs -and dummy integers will be produced. User-defined inverses are provided -as properties in a manner similar to derivatives: - -@smallexample -(put 'calcFunc-ln 'math-inverse - (function (lambda (x) (list 'calcFunc-exp x)))) -@end smallexample - -This function can call @samp{(math-solve-get-sign @var{x})} to create -a new arbitrary sign variable, returning @var{x} times that sign, and -@samp{(math-solve-get-int @var{x})} to create a new arbitrary integer -variable multiplied by @var{x}. These functions simply return @var{x} -if the caller requested a non-``full'' solution. -@end defun - -@defun solve-eqn expr var full -This version of @code{solve-for} takes an expression which will -typically be an equation or inequality. (If it is not, it will be -interpreted as the equation @samp{@var{expr} = 0}.) It returns an -equation or inequality, or @code{nil} if no solution could be found. -@end defun - -@defun solve-system exprs vars full -This function solves a system of equations. Generally, @var{exprs} -and @var{vars} will be vectors of equal length. -@xref{Solving Systems of Equations}, for other options. -@end defun - -@defun expr-contains expr var -Returns a non-@code{nil} value if @var{var} occurs as a subexpression -of @var{expr}. - -This function might seem at first to be identical to -@code{calc-find-sub-formula}. The key difference is that -@code{expr-contains} uses @code{equal} to test for matches, whereas -@code{calc-find-sub-formula} uses @code{eq}. In the formula -@samp{f(a, a)}, the two @samp{a}s will be @code{equal} but not -@code{eq} to each other. -@end defun - -@defun expr-contains-count expr var -Returns the number of occurrences of @var{var} as a subexpression -of @var{expr}, or @code{nil} if there are no occurrences. -@end defun - -@defun expr-depends expr var -Returns true if @var{expr} refers to any variable the occurs in @var{var}. -In other words, it checks if @var{expr} and @var{var} have any variables -in common. -@end defun - -@defun expr-contains-vars expr -Return true if @var{expr} contains any variables, or @code{nil} if @var{expr} -contains only constants and functions with constant arguments. -@end defun - -@defun expr-subst expr old new -Returns a copy of @var{expr}, with all occurrences of @var{old} replaced -by @var{new}. This treats @code{lambda} forms specially with respect -to the dummy argument variables, so that the effect is always to return -@var{expr} evaluated at @var{old} = @var{new}. -@end defun - -@defun multi-subst expr old new -This is like @code{expr-subst}, except that @var{old} and @var{new} -are lists of expressions to be substituted simultaneously. If one -list is shorter than the other, trailing elements of the longer list -are ignored. -@end defun - -@defun expr-weight expr -Returns the ``weight'' of @var{expr}, basically a count of the total -number of objects and function calls that appear in @var{expr}. For -``primitive'' objects, this will be one. -@end defun - -@defun expr-height expr -Returns the ``height'' of @var{expr}, which is the deepest level to -which function calls are nested. (Note that @samp{@var{a} + @var{b}} -counts as a function call.) For primitive objects, this returns zero. -@end defun - -@defun polynomial-p expr var -Check if @var{expr} is a polynomial in variable (or sub-expression) -@var{var}. If so, return the degree of the polynomial, that is, the -highest power of @var{var} that appears in @var{expr}. For example, -for @samp{(x^2 + 3)^3 + 4} this would return 6. This function returns -@code{nil} unless @var{expr}, when expanded out by @kbd{a x} -(@code{calc-expand}), would consist of a sum of terms in which @var{var} -appears only raised to nonnegative integer powers. Note that if -@var{var} does not occur in @var{expr}, then @var{expr} is considered -a polynomial of degree 0. -@end defun - -@defun is-polynomial expr var degree loose -Check if @var{expr} is a polynomial in variable or sub-expression -@var{var}, and, if so, return a list representation of the polynomial -where the elements of the list are coefficients of successive powers of -@var{var}: @samp{@var{a} + @var{b} x + @var{c} x^3} would produce the -list @samp{(@var{a} @var{b} 0 @var{c})}, and @samp{(x + 1)^2} would -produce the list @samp{(1 2 1)}. The highest element of the list will -be non-zero, with the special exception that if @var{expr} is the -constant zero, the returned value will be @samp{(0)}. Return @code{nil} -if @var{expr} is not a polynomial in @var{var}. If @var{degree} is -specified, this will not consider polynomials of degree higher than that -value. This is a good precaution because otherwise an input of -@samp{(x+1)^1000} will cause a huge coefficient list to be built. If -@var{loose} is non-@code{nil}, then a looser definition of a polynomial -is used in which coefficients are no longer required not to depend on -@var{var}, but are only required not to take the form of polynomials -themselves. For example, @samp{sin(x) x^2 + cos(x)} is a loose -polynomial with coefficients @samp{((calcFunc-cos x) 0 (calcFunc-sin -x))}. The result will never be @code{nil} in loose mode, since any -expression can be interpreted as a ``constant'' loose polynomial. -@end defun - -@defun polynomial-base expr pred -Check if @var{expr} is a polynomial in any variable that occurs in it; -if so, return that variable. (If @var{expr} is a multivariate polynomial, -this chooses one variable arbitrarily.) If @var{pred} is specified, it should -be a Lisp function which is called as @samp{(@var{pred} @var{subexpr})}, -and which should return true if @code{mpb-top-expr} (a global name for -the original @var{expr}) is a suitable polynomial in @var{subexpr}. -The default predicate uses @samp{(polynomial-p mpb-top-expr @var{subexpr})}; -you can use @var{pred} to specify additional conditions. Or, you could -have @var{pred} build up a list of every suitable @var{subexpr} that -is found. -@end defun - -@defun poly-simplify poly -Simplify polynomial coefficient list @var{poly} by (destructively) -clipping off trailing zeros. -@end defun - -@defun poly-mix a ac b bc -Mix two polynomial lists @var{a} and @var{b} (in the form returned by -@code{is-polynomial}) in a linear combination with coefficient expressions -@var{ac} and @var{bc}. The result is a (not necessarily simplified) -polynomial list representing @samp{@var{ac} @var{a} + @var{bc} @var{b}}. -@end defun - -@defun poly-mul a b -Multiply two polynomial coefficient lists @var{a} and @var{b}. The -result will be in simplified form if the inputs were simplified. -@end defun - -@defun build-polynomial-expr poly var -Construct a Calc formula which represents the polynomial coefficient -list @var{poly} applied to variable @var{var}. The @kbd{a c} -(@code{calc-collect}) command uses @code{is-polynomial} to turn an -expression into a coefficient list, then @code{build-polynomial-expr} -to turn the list back into an expression in regular form. -@end defun - -@defun check-unit-name var -Check if @var{var} is a variable which can be interpreted as a unit -name. If so, return the units table entry for that unit. This -will be a list whose first element is the unit name (not counting -prefix characters) as a symbol and whose second element is the -Calc expression which defines the unit. (Refer to the Calc sources -for details on the remaining elements of this list.) If @var{var} -is not a variable or is not a unit name, return @code{nil}. -@end defun - -@defun units-in-expr-p expr sub-exprs -Return true if @var{expr} contains any variables which can be -interpreted as units. If @var{sub-exprs} is @code{t}, the entire -expression is searched. If @var{sub-exprs} is @code{nil}, this -checks whether @var{expr} is directly a units expression. -@end defun - -@defun single-units-in-expr-p expr -Check whether @var{expr} contains exactly one units variable. If so, -return the units table entry for the variable. If @var{expr} does -not contain any units, return @code{nil}. If @var{expr} contains -two or more units, return the symbol @code{wrong}. -@end defun - -@defun to-standard-units expr which -Convert units expression @var{expr} to base units. If @var{which} -is @code{nil}, use Calc's native base units. Otherwise, @var{which} -can specify a units system, which is a list of two-element lists, -where the first element is a Calc base symbol name and the second -is an expression to substitute for it. -@end defun - -@defun remove-units expr -Return a copy of @var{expr} with all units variables replaced by ones. -This expression is generally normalized before use. -@end defun - -@defun extract-units expr -Return a copy of @var{expr} with everything but units variables replaced -by ones. -@end defun - -@node Formatting Lisp Functions, Hooks, Symbolic Lisp Functions, Internals -@subsubsection I/O and Formatting Functions - -@noindent -The functions described here are responsible for parsing and formatting -Calc numbers and formulas. - -@defun calc-eval str sep arg1 arg2 @dots{} -This is the simplest interface to the Calculator from another Lisp program. -@xref{Calling Calc from Your Programs}. -@end defun - -@defun read-number str -If string @var{str} contains a valid Calc number, either integer, -fraction, float, or HMS form, this function parses and returns that -number. Otherwise, it returns @code{nil}. -@end defun - -@defun read-expr str -Read an algebraic expression from string @var{str}. If @var{str} does -not have the form of a valid expression, return a list of the form -@samp{(error @var{pos} @var{msg})} where @var{pos} is an integer index -into @var{str} of the general location of the error, and @var{msg} is -a string describing the problem. -@end defun - -@defun read-exprs str -Read a list of expressions separated by commas, and return it as a -Lisp list. If an error occurs in any expressions, an error list as -shown above is returned instead. -@end defun - -@defun calc-do-alg-entry initial prompt no-norm -Read an algebraic formula or formulas using the minibuffer. All -conventions of regular algebraic entry are observed. The return value -is a list of Calc formulas; there will be more than one if the user -entered a list of values separated by commas. The result is @code{nil} -if the user presses Return with a blank line. If @var{initial} is -given, it is a string which the minibuffer will initially contain. -If @var{prompt} is given, it is the prompt string to use; the default -is ``Algebraic:''. If @var{no-norm} is @code{t}, the formulas will -be returned exactly as parsed; otherwise, they will be passed through -@code{calc-normalize} first. - -To support the use of @kbd{$} characters in the algebraic entry, use -@code{let} to bind @code{calc-dollar-values} to a list of the values -to be substituted for @kbd{$}, @kbd{$$}, and so on, and bind -@code{calc-dollar-used} to 0. Upon return, @code{calc-dollar-used} -will have been changed to the highest number of consecutive @kbd{$}s -that actually appeared in the input. -@end defun - -@defun format-number a -Convert the real or complex number or HMS form @var{a} to string form. -@end defun - -@defun format-flat-expr a prec -Convert the arbitrary Calc number or formula @var{a} to string form, -in the style used by the trail buffer and the @code{calc-edit} command. -This is a simple format designed -mostly to guarantee the string is of a form that can be re-parsed by -@code{read-expr}. Most formatting modes, such as digit grouping, -complex number format, and point character, are ignored to ensure the -result will be re-readable. The @var{prec} parameter is normally 0; if -you pass a large integer like 1000 instead, the expression will be -surrounded by parentheses unless it is a plain number or variable name. -@end defun - -@defun format-nice-expr a width -This is like @code{format-flat-expr} (with @var{prec} equal to 0), -except that newlines will be inserted to keep lines down to the -specified @var{width}, and vectors that look like matrices or rewrite -rules are written in a pseudo-matrix format. The @code{calc-edit} -command uses this when only one stack entry is being edited. -@end defun - -@defun format-value a width -Convert the Calc number or formula @var{a} to string form, using the -format seen in the stack buffer. Beware the string returned may -not be re-readable by @code{read-expr}, for example, because of digit -grouping. Multi-line objects like matrices produce strings that -contain newline characters to separate the lines. The @var{w} -parameter, if given, is the target window size for which to format -the expressions. If @var{w} is omitted, the width of the Calculator -window is used. -@end defun - -@defun compose-expr a prec -Format the Calc number or formula @var{a} according to the current -language mode, returning a ``composition.'' To learn about the -structure of compositions, see the comments in the Calc source code. -You can specify the format of a given type of function call by putting -a @code{math-compose-@var{lang}} property on the function's symbol, -whose value is a Lisp function that takes @var{a} and @var{prec} as -arguments and returns a composition. Here @var{lang} is a language -mode name, one of @code{normal}, @code{big}, @code{c}, @code{pascal}, -@code{fortran}, @code{tex}, @code{eqn}, @code{math}, or @code{maple}. -In Big mode, Calc actually tries @code{math-compose-big} first, then -tries @code{math-compose-normal}. If this property does not exist, -or if the function returns @code{nil}, the function is written in the -normal function-call notation for that language. -@end defun - -@defun composition-to-string c w -Convert a composition structure returned by @code{compose-expr} into -a string. Multi-line compositions convert to strings containing -newline characters. The target window size is given by @var{w}. -The @code{format-value} function basically calls @code{compose-expr} -followed by @code{composition-to-string}. -@end defun - -@defun comp-width c -Compute the width in characters of composition @var{c}. -@end defun - -@defun comp-height c -Compute the height in lines of composition @var{c}. -@end defun - -@defun comp-ascent c -Compute the portion of the height of composition @var{c} which is on or -above the baseline. For a one-line composition, this will be one. -@end defun - -@defun comp-descent c -Compute the portion of the height of composition @var{c} which is below -the baseline. For a one-line composition, this will be zero. -@end defun - -@defun comp-first-char c -If composition @var{c} is a ``flat'' composition, return the first -(leftmost) character of the composition as an integer. Otherwise, -return @code{nil}. -@end defun - -@defun comp-last-char c -If composition @var{c} is a ``flat'' composition, return the last -(rightmost) character, otherwise return @code{nil}. -@end defun - -@comment @node Lisp Variables, Hooks, Formatting Lisp Functions, Internals -@comment @subsubsection Lisp Variables -@comment -@comment @noindent -@comment (This section is currently unfinished.) - -@node Hooks, , Formatting Lisp Functions, Internals -@subsubsection Hooks - -@noindent -Hooks are variables which contain Lisp functions (or lists of functions) -which are called at various times. Calc defines a number of hooks -that help you to customize it in various ways. Calc uses the Lisp -function @code{run-hooks} to invoke the hooks shown below. Several -other customization-related variables are also described here. - -@defvar calc-load-hook -This hook is called at the end of @file{calc.el}, after the file has -been loaded, before any functions in it have been called, but after -@code{calc-mode-map} and similar variables have been set up. -@end defvar - -@defvar calc-ext-load-hook -This hook is called at the end of @file{calc-ext.el}. -@end defvar - -@defvar calc-start-hook -This hook is called as the last step in a @kbd{M-x calc} command. -At this point, the Calc buffer has been created and initialized if -necessary, the Calc window and trail window have been created, -and the ``Welcome to Calc'' message has been displayed. -@end defvar - -@defvar calc-mode-hook -This hook is called when the Calc buffer is being created. Usually -this will only happen once per Emacs session. The hook is called -after Emacs has switched to the new buffer, the mode-settings file -has been read if necessary, and all other buffer-local variables -have been set up. After this hook returns, Calc will perform a -@code{calc-refresh} operation, set up the mode line display, then -evaluate any deferred @code{calc-define} properties that have not -been evaluated yet. -@end defvar - -@defvar calc-trail-mode-hook -This hook is called when the Calc Trail buffer is being created. -It is called as the very last step of setting up the Trail buffer. -Like @code{calc-mode-hook}, this will normally happen only once -per Emacs session. -@end defvar - -@defvar calc-end-hook -This hook is called by @code{calc-quit}, generally because the user -presses @kbd{q} or @kbd{C-x * c} while in Calc. The Calc buffer will -be the current buffer. The hook is called as the very first -step, before the Calc window is destroyed. -@end defvar - -@defvar calc-window-hook -If this hook is non-@code{nil}, it is called to create the Calc window. -Upon return, this new Calc window should be the current window. -(The Calc buffer will already be the current buffer when the -hook is called.) If the hook is not defined, Calc will -generally use @code{split-window}, @code{set-window-buffer}, -and @code{select-window} to create the Calc window. -@end defvar - -@defvar calc-trail-window-hook -If this hook is non-@code{nil}, it is called to create the Calc Trail -window. The variable @code{calc-trail-buffer} will contain the buffer -which the window should use. Unlike @code{calc-window-hook}, this hook -must @emph{not} switch into the new window. -@end defvar - -@defvar calc-embedded-mode-hook -This hook is called the first time that Embedded mode is entered. -@end defvar - -@defvar calc-embedded-new-buffer-hook -This hook is called each time that Embedded mode is entered in a -new buffer. -@end defvar - -@defvar calc-embedded-new-formula-hook -This hook is called each time that Embedded mode is enabled for a -new formula. -@end defvar - -@defvar calc-edit-mode-hook -This hook is called by @code{calc-edit} (and the other ``edit'' -commands) when the temporary editing buffer is being created. -The buffer will have been selected and set up to be in -@code{calc-edit-mode}, but will not yet have been filled with -text. (In fact it may still have leftover text from a previous -@code{calc-edit} command.) -@end defvar - -@defvar calc-mode-save-hook -This hook is called by the @code{calc-save-modes} command, -after Calc's own mode features have been inserted into the -Calc init file and just before the ``End of mode settings'' -message is inserted. -@end defvar - -@defvar calc-reset-hook -This hook is called after @kbd{C-x * 0} (@code{calc-reset}) has -reset all modes. The Calc buffer will be the current buffer. -@end defvar - -@defvar calc-other-modes -This variable contains a list of strings. The strings are -concatenated at the end of the modes portion of the Calc -mode line (after standard modes such as ``Deg'', ``Inv'' and -``Hyp''). Each string should be a short, single word followed -by a space. The variable is @code{nil} by default. -@end defvar - -@defvar calc-mode-map -This is the keymap that is used by Calc mode. The best time -to adjust it is probably in a @code{calc-mode-hook}. If the -Calc extensions package (@file{calc-ext.el}) has not yet been -loaded, many of these keys will be bound to @code{calc-missing-key}, -which is a command that loads the extensions package and -``retypes'' the key. If your @code{calc-mode-hook} rebinds -one of these keys, it will probably be overridden when the -extensions are loaded. -@end defvar - -@defvar calc-digit-map -This is the keymap that is used during numeric entry. Numeric -entry uses the minibuffer, but this map binds every non-numeric -key to @code{calcDigit-nondigit} which generally calls -@code{exit-minibuffer} and ``retypes'' the key. -@end defvar - -@defvar calc-alg-ent-map -This is the keymap that is used during algebraic entry. This is -mostly a copy of @code{minibuffer-local-map}. -@end defvar - -@defvar calc-store-var-map -This is the keymap that is used during entry of variable names for -commands like @code{calc-store} and @code{calc-recall}. This is -mostly a copy of @code{minibuffer-local-completion-map}. -@end defvar - -@defvar calc-edit-mode-map -This is the (sparse) keymap used by @code{calc-edit} and other -temporary editing commands. It binds @key{RET}, @key{LFD}, -and @kbd{C-c C-c} to @code{calc-edit-finish}. -@end defvar - -@defvar calc-mode-var-list -This is a list of variables which are saved by @code{calc-save-modes}. -Each entry is a list of two items, the variable (as a Lisp symbol) -and its default value. When modes are being saved, each variable -is compared with its default value (using @code{equal}) and any -non-default variables are written out. -@end defvar - -@defvar calc-local-var-list -This is a list of variables which should be buffer-local to the -Calc buffer. Each entry is a variable name (as a Lisp symbol). -These variables also have their default values manipulated by -the @code{calc} and @code{calc-quit} commands; @pxref{Multiple Calculators}. -Since @code{calc-mode-hook} is called after this list has been -used the first time, your hook should add a variable to the -list and also call @code{make-local-variable} itself. -@end defvar - -@node Copying, GNU Free Documentation License, Programming, Top -@appendix GNU GENERAL PUBLIC LICENSE -@include gpl.texi - -@node GNU Free Documentation License, Customizing Calc, Copying, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Customizing Calc, Reporting Bugs, GNU Free Documentation License, Top -@appendix Customizing Calc - -The usual prefix for Calc is the key sequence @kbd{C-x *}. If you wish -to use a different prefix, you can put - -@example -(global-set-key "NEWPREFIX" 'calc-dispatch) -@end example - -@noindent -in your .emacs file. -(@xref{Key Bindings,,Customizing Key Bindings,emacs, -The GNU Emacs Manual}, for more information on binding keys.) -A convenient way to start Calc is with @kbd{C-x * *}; to make it equally -convenient for users who use a different prefix, the prefix can be -followed by @kbd{=}, @kbd{&}, @kbd{#}, @kbd{\}, @kbd{/}, @kbd{+} or -@kbd{-} as well as @kbd{*} to start Calc, and so in many cases the last -character of the prefix can simply be typed twice. - -Calc is controlled by many variables, most of which can be reset -from within Calc. Some variables are less involved with actual -calculation and can be set outside of Calc using Emacs'ss -customization facilities. These variables are listed below. -Typing @kbd{M-x customize-variable RET @var{variable-name} RET} -will bring up a buffer in which the variable's value can be redefined. -Typing @kbd{M-x customize-group RET calc RET} will bring up a buffer which -contains all of Calc's customizable variables. (These variables can -also be reset by putting the appropriate lines in your .emacs file; -@xref{Init File, ,Init File, emacs, The GNU Emacs Manual}.) - -Some of the customizable variables are regular expressions. A regular -expression is basically a pattern that Calc can search for. -See @ref{Regexp Search,, Regular Expression Search, emacs, The GNU Emacs Manual} -to see how regular expressions work. - -@defvar calc-settings-file -The variable @code{calc-settings-file} holds the file name in -which commands like @kbd{m m} and @kbd{Z P} store ``permanent'' -definitions. -If @code{calc-settings-file} is not your user init file (typically -@file{~/.emacs}) and if the variable @code{calc-loaded-settings-file} is -@code{nil}, then Calc will automatically load your settings file (if it -exists) the first time Calc is invoked. - -The default value for this variable is @code{"~/.emacs.d/calc.el"} -unless the file @file{~/.calc.el} exists, in which case the default -value will be @code{"~/.calc.el"}. -@end defvar - -@defvar calc-gnuplot-name -See @ref{Graphics}.@* -The variable @code{calc-gnuplot-name} should be the name of the -GNUPLOT program (a string). If you have GNUPLOT installed on your -system but Calc is unable to find it, you may need to set this -variable. You may also need to set some Lisp variables to show Calc how -to run GNUPLOT on your system, see @ref{Devices, ,Graphical Devices} . -The default value of @code{calc-gnuplot-name} is @code{"gnuplot"}. -@end defvar - -@defvar calc-gnuplot-plot-command -@defvarx calc-gnuplot-print-command -See @ref{Devices, ,Graphical Devices}.@* -The variables @code{calc-gnuplot-plot-command} and -@code{calc-gnuplot-print-command} represent system commands to -display and print the output of GNUPLOT, respectively. These may be -@code{nil} if no command is necessary, or strings which can include -@samp{%s} to signify the name of the file to be displayed or printed. -Or, these variables may contain Lisp expressions which are evaluated -to display or print the output. - -The default value of @code{calc-gnuplot-plot-command} is @code{nil}, -and the default value of @code{calc-gnuplot-print-command} is -@code{"lp %s"}. -@end defvar - -@defvar calc-language-alist -See @ref{Basic Embedded Mode}.@* -The variable @code{calc-language-alist} controls the languages that -Calc will associate with major modes. When Calc embedded mode is -enabled, it will try to use the current major mode to -determine what language should be used. (This can be overridden using -Calc's mode changing commands, @xref{Mode Settings in Embedded Mode}.) -The variable @code{calc-language-alist} consists of a list of pairs of -the form @code{(@var{MAJOR-MODE} . @var{LANGUAGE})}; for example, -@code{(latex-mode . latex)} is one such pair. If Calc embedded is -activated in a buffer whose major mode is @var{MAJOR-MODE}, it will set itself -to use the language @var{LANGUAGE}. - -The default value of @code{calc-language-alist} is -@example - ((latex-mode . latex) - (tex-mode . tex) - (plain-tex-mode . tex) - (context-mode . tex) - (nroff-mode . eqn) - (pascal-mode . pascal) - (c-mode . c) - (c++-mode . c) - (fortran-mode . fortran) - (f90-mode . fortran)) -@end example -@end defvar - -@defvar calc-embedded-announce-formula -@defvarx calc-embedded-announce-formula-alist -See @ref{Customizing Embedded Mode}.@* -The variable @code{calc-embedded-announce-formula} helps determine -what formulas @kbd{C-x * a} will activate in a buffer. It is a -regular expression, and when activating embedded formulas with -@kbd{C-x * a}, it will tell Calc that what follows is a formula to be -activated. (Calc also uses other patterns to find formulas, such as -@samp{=>} and @samp{:=}.) - -The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, which checks -for @samp{%Embed} followed by any number of lines beginning with -@samp{%} and a space. - -The variable @code{calc-embedded-announce-formula-alist} is used to -set @code{calc-embedded-announce-formula} to different regular -expressions depending on the major mode of the editing buffer. -It consists of a list of pairs of the form @code{(@var{MAJOR-MODE} . -@var{REGEXP})}, and its default value is -@example - ((c++-mode . "//Embed\n\\(// .*\n\\)*") - (c-mode . "/\\*Embed\\*/\n\\(/\\* .*\\*/\n\\)*") - (f90-mode . "!Embed\n\\(! .*\n\\)*") - (fortran-mode . "C Embed\n\\(C .*\n\\)*") - (html-helper-mode . "\n\\(\n\\)*") - (html-mode . "\n\\(\n\\)*") - (nroff-mode . "\\\\\"Embed\n\\(\\\\\" .*\n\\)*") - (pascal-mode . "@{Embed@}\n\\(@{.*@}\n\\)*") - (sgml-mode . "\n\\(\n\\)*") - (xml-mode . "\n\\(\n\\)*") - (texinfo-mode . "@@c Embed\n\\(@@c .*\n\\)*")) -@end example -Any major modes added to @code{calc-embedded-announce-formula-alist} -should also be added to @code{calc-embedded-open-close-plain-alist} -and @code{calc-embedded-open-close-mode-alist}. -@end defvar - -@defvar calc-embedded-open-formula -@defvarx calc-embedded-close-formula -@defvarx calc-embedded-open-close-formula-alist -See @ref{Customizing Embedded Mode}.@* -The variables @code{calc-embedded-open-formula} and -@code{calc-embedded-close-formula} control the region that Calc will -activate as a formula when Embedded mode is entered with @kbd{C-x * e}. -They are regular expressions; -Calc normally scans backward and forward in the buffer for the -nearest text matching these regular expressions to be the ``formula -delimiters''. - -The simplest delimiters are blank lines. Other delimiters that -Embedded mode understands by default are: -@enumerate -@item -The @TeX{} and La@TeX{} math delimiters @samp{$ $}, @samp{$$ $$}, -@samp{\[ \]}, and @samp{\( \)}; -@item -Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters); -@item -Lines beginning with @samp{@@} (Texinfo delimiters). -@item -Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters); -@item -Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else. -@end enumerate - -The variable @code{calc-embedded-open-close-formula-alist} is used to -set @code{calc-embedded-open-formula} and -@code{calc-embedded-close-formula} to different regular -expressions depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{OPEN-FORMULA-REGEXP} -@var{CLOSE-FORMULA-REGEXP})}, and its default value is -@code{nil}. -@end defvar - -@defvar calc-embedded-word-regexp -@defvarx calc-embedded-word-regexp-alist -See @ref{Customizing Embedded Mode}.@* -The variable @code{calc-embedded-word-regexp} determines the expression -that Calc will activate when Embedded mode is entered with @kbd{C-x * -w}. It is a regular expressions. - -The default value of @code{calc-embedded-word-regexp} is -@code{"[-+]?[0-9]+\\(\\.[0-9]+\\)?\\([eE][-+]?[0-9]+\\)?"}. - -The variable @code{calc-embedded-word-regexp-alist} is used to -set @code{calc-embedded-word-regexp} to a different regular -expression depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{WORD-REGEXP})}, and its default value is -@code{nil}. -@end defvar - -@defvar calc-embedded-open-plain -@defvarx calc-embedded-close-plain -@defvarx calc-embedded-open-close-plain-alist -See @ref{Customizing Embedded Mode}.@* -The variables @code{calc-embedded-open-plain} and -@code{calc-embedded-open-plain} are used to delimit ``plain'' -formulas. Note that these are actual strings, not regular -expressions, because Calc must be able to write these string into a -buffer as well as to recognize them. - -The default string for @code{calc-embedded-open-plain} is -@code{"%%% "}, note the trailing space. The default string for -@code{calc-embedded-close-plain} is @code{" %%%\n"}, without -the trailing newline here, the first line of a Big mode formula -that followed might be shifted over with respect to the other lines. - -The variable @code{calc-embedded-open-close-plain-alist} is used to -set @code{calc-embedded-open-plain} and -@code{calc-embedded-close-plain} to different strings -depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{OPEN-PLAIN-STRING} -@var{CLOSE-PLAIN-STRING})}, and its default value is -@example - ((c++-mode "// %% " " %%\n") - (c-mode "/* %% " " %% */\n") - (f90-mode "! %% " " %%\n") - (fortran-mode "C %% " " %%\n") - (html-helper-mode "\n") - (html-mode "\n") - (nroff-mode "\\\" %% " " %%\n") - (pascal-mode "@{%% " " %%@}\n") - (sgml-mode "\n") - (xml-mode "\n") - (texinfo-mode "@@c %% " " %%\n")) -@end example -Any major modes added to @code{calc-embedded-open-close-plain-alist} -should also be added to @code{calc-embedded-announce-formula-alist} -and @code{calc-embedded-open-close-mode-alist}. -@end defvar - -@defvar calc-embedded-open-new-formula -@defvarx calc-embedded-close-new-formula -@defvarx calc-embedded-open-close-new-formula-alist -See @ref{Customizing Embedded Mode}.@* -The variables @code{calc-embedded-open-new-formula} and -@code{calc-embedded-close-new-formula} are strings which are -inserted before and after a new formula when you type @kbd{C-x * f}. - -The default value of @code{calc-embedded-open-new-formula} is -@code{"\n\n"}. If this string begins with a newline character and the -@kbd{C-x * f} is typed at the beginning of a line, @kbd{C-x * f} will skip -this first newline to avoid introducing unnecessary blank lines in the -file. The default value of @code{calc-embedded-close-new-formula} is -also @code{"\n\n"}. The final newline is omitted by @w{@kbd{C-x * f}} -if typed at the end of a line. (It follows that if @kbd{C-x * f} is -typed on a blank line, both a leading opening newline and a trailing -closing newline are omitted.) - -The variable @code{calc-embedded-open-close-new-formula-alist} is used to -set @code{calc-embedded-open-new-formula} and -@code{calc-embedded-close-new-formula} to different strings -depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{OPEN-NEW-FORMULA-STRING} -@var{CLOSE-NEW-FORMULA-STRING})}, and its default value is -@code{nil}. -@end defvar - -@defvar calc-embedded-open-mode -@defvarx calc-embedded-close-mode -@defvarx calc-embedded-open-close-mode-alist -See @ref{Customizing Embedded Mode}.@* -The variables @code{calc-embedded-open-mode} and -@code{calc-embedded-close-mode} are strings which Calc will place before -and after any mode annotations that it inserts. Calc never scans for -these strings; Calc always looks for the annotation itself, so it is not -necessary to add them to user-written annotations. - -The default value of @code{calc-embedded-open-mode} is @code{"% "} -and the default value of @code{calc-embedded-close-mode} is -@code{"\n"}. -If you change the value of @code{calc-embedded-close-mode}, it is a good -idea still to end with a newline so that mode annotations will appear on -lines by themselves. - -The variable @code{calc-embedded-open-close-mode-alist} is used to -set @code{calc-embedded-open-mode} and -@code{calc-embedded-close-mode} to different strings -expressions depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{OPEN-MODE-STRING} -@var{CLOSE-MODE-STRING})}, and its default value is -@example - ((c++-mode "// " "\n") - (c-mode "/* " " */\n") - (f90-mode "! " "\n") - (fortran-mode "C " "\n") - (html-helper-mode "\n") - (html-mode "\n") - (nroff-mode "\\\" " "\n") - (pascal-mode "@{ " " @}\n") - (sgml-mode "\n") - (xml-mode "\n") - (texinfo-mode "@@c " "\n")) -@end example -Any major modes added to @code{calc-embedded-open-close-mode-alist} -should also be added to @code{calc-embedded-announce-formula-alist} -and @code{calc-embedded-open-close-plain-alist}. -@end defvar - -@defvar calc-lu-power-reference -@defvarx calc-lu-field-reference -See @ref{Logarithmic Units}.@* -The variables @code{calc-lu-power-reference} and -@code{calc-lu-field-reference} are unit expressions (written as -strings) which Calc will use as reference quantities for logarithmic -units. - -The default value of @code{calc-lu-power-reference} is @code{"mW"} -and the default value of @code{calc-lu-field-reference} is -@code{"20 uPa"}. -@end defvar - -@defvar calc-note-threshold -See @ref{Musical Notes}.@* -The variable @code{calc-note-threshold} is a number (written as a -string) which determines how close (in cents) a frequency needs to be -to a note to be recognized as that note. - -The default value of @code{calc-note-threshold} is 1. -@end defvar - -@defvar calc-highlight-selections-with-faces -@defvarx calc-selected-face -@defvarx calc-nonselected-face -See @ref{Displaying Selections}.@* -The variable @code{calc-highlight-selections-with-faces} -determines how selected sub-formulas are distinguished. -If @code{calc-highlight-selections-with-faces} is nil, then -a selected sub-formula is distinguished either by changing every -character not part of the sub-formula with a dot or by changing every -character in the sub-formula with a @samp{#} sign. -If @code{calc-highlight-selections-with-faces} is t, -then a selected sub-formula is distinguished either by displaying the -non-selected portion of the formula with @code{calc-nonselected-face} -or by displaying the selected sub-formula with -@code{calc-nonselected-face}. -@end defvar - -@defvar calc-multiplication-has-precedence -The variable @code{calc-multiplication-has-precedence} determines -whether multiplication has precedence over division in algebraic -formulas in normal language modes. If -@code{calc-multiplication-has-precedence} is non-@code{nil}, then -multiplication has precedence (and, for certain obscure reasons, is -right associative), and so for example @samp{a/b*c} will be interpreted -as @samp{a/(b*c)}. If @code{calc-multiplication-has-precedence} is -@code{nil}, then multiplication has the same precedence as division -(and, like division, is left associative), and so for example -@samp{a/b*c} will be interpreted as @samp{(a/b)*c}. The default value -of @code{calc-multiplication-has-precedence} is @code{t}. -@end defvar - -@defvar calc-undo-length -The variable @code{calc-undo-length} determines the number of undo -steps that Calc will keep track of when @code{calc-quit} is called. -If @code{calc-undo-length} is a non-negative integer, then this is the -number of undo steps that will be preserved; if -@code{calc-undo-length} has any other value, then all undo steps will -be preserved. The default value of @code{calc-undo-length} is @expr{100}. -@end defvar - -@node Reporting Bugs, Summary, Customizing Calc, Top -@appendix Reporting Bugs - -@noindent -If you find a bug in Calc, send e-mail to Jay Belanger, - -@example -jay.p.belanger@@gmail.com -@end example - -@noindent -There is an automatic command @kbd{M-x report-calc-bug} which helps -you to report bugs. This command prompts you for a brief subject -line, then leaves you in a mail editing buffer. Type @kbd{C-c C-c} to -send your mail. Make sure your subject line indicates that you are -reporting a Calc bug; this command sends mail to the maintainer's -regular mailbox. - -If you have suggestions for additional features for Calc, please send -them. Some have dared to suggest that Calc is already top-heavy with -features; this obviously cannot be the case, so if you have ideas, send -them right in. - -At the front of the source file, @file{calc.el}, is a list of ideas for -future work. If any enthusiastic souls wish to take it upon themselves -to work on these, please send a message (using @kbd{M-x report-calc-bug}) -so any efforts can be coordinated. - -The latest version of Calc is available from Savannah, in the Emacs -repository. See @uref{http://savannah.gnu.org/projects/emacs}. - -@c [summary] -@node Summary, Key Index, Reporting Bugs, Top -@appendix Calc Summary - -@noindent -This section includes a complete list of Calc keystroke commands. -Each line lists the stack entries used by the command (top-of-stack -last), the keystrokes themselves, the prompts asked by the command, -and the result of the command (also with top-of-stack last). -The result is expressed using the equivalent algebraic function. -Commands which put no results on the stack show the full @kbd{M-x} -command name in that position. Numbers preceding the result or -command name refer to notes at the end. - -Algebraic functions and @kbd{M-x} commands that don't have corresponding -keystrokes are not listed in this summary. -@xref{Command Index}. @xref{Function Index}. - -@iftex -@begingroup -@tex -\vskip-2\baselineskip \null -\gdef\sumrow#1{\sumrowx#1\relax}% -\gdef\sumrowx#1\:#2\:#3\:#4\:#5\:#6\relax{% -\leavevmode% -{\smallfonts -\hbox to5em{\sl\hss#1}% -\hbox to5em{\tt#2\hss}% -\hbox to4em{\sl#3\hss}% -\hbox to5em{\rm\hss#4}% -\thinspace% -{\tt#5}% -{\sl#6}% -}}% -\gdef\sumlpar{{\rm(}}% -\gdef\sumrpar{{\rm)}}% -\gdef\sumcomma{{\rm,\thinspace}}% -\gdef\sumexcl{{\rm!}}% -\gdef\sumbreak{\vskip-2.5\baselineskip\goodbreak}% -\gdef\minus#1{{\tt-}}% -@end tex -@let@:=@sumsep -@let@r=@sumrow -@catcode`@(=@active @let(=@sumlpar -@catcode`@)=@active @let)=@sumrpar -@catcode`@,=@active @let,=@sumcomma -@catcode`@!=@active @let!=@sumexcl -@end iftex -@format -@iftex -@advance@baselineskip-2.5pt -@let@c@sumbreak -@end iftex -@r{ @: C-x * a @: @: 33 @:calc-embedded-activate@:} -@r{ @: C-x * b @: @: @:calc-big-or-small@:} -@r{ @: C-x * c @: @: @:calc@:} -@r{ @: C-x * d @: @: @:calc-embedded-duplicate@:} -@r{ @: C-x * e @: @: 34 @:calc-embedded@:} -@r{ @: C-x * f @:formula @: @:calc-embedded-new-formula@:} -@r{ @: C-x * g @: @: 35 @:calc-grab-region@:} -@r{ @: C-x * i @: @: @:calc-info@:} -@r{ @: C-x * j @: @: @:calc-embedded-select@:} -@r{ @: C-x * k @: @: @:calc-keypad@:} -@r{ @: C-x * l @: @: @:calc-load-everything@:} -@r{ @: C-x * m @: @: @:read-kbd-macro@:} -@r{ @: C-x * n @: @: 4 @:calc-embedded-next@:} -@r{ @: C-x * o @: @: @:calc-other-window@:} -@r{ @: C-x * p @: @: 4 @:calc-embedded-previous@:} -@r{ @: C-x * q @:formula @: @:quick-calc@:} -@r{ @: C-x * r @: @: 36 @:calc-grab-rectangle@:} -@r{ @: C-x * s @: @: @:calc-info-summary@:} -@r{ @: C-x * t @: @: @:calc-tutorial@:} -@r{ @: C-x * u @: @: @:calc-embedded-update-formula@:} -@r{ @: C-x * w @: @: @:calc-embedded-word@:} -@r{ @: C-x * x @: @: @:calc-quit@:} -@r{ @: C-x * y @: @:1,28,49 @:calc-copy-to-buffer@:} -@r{ @: C-x * z @: @: @:calc-user-invocation@:} -@r{ @: C-x * : @: @: 36 @:calc-grab-sum-down@:} -@r{ @: C-x * _ @: @: 36 @:calc-grab-sum-across@:} -@r{ @: C-x * ` @:editing @: 30 @:calc-embedded-edit@:} -@r{ @: C-x * 0 @:(zero) @: @:calc-reset@:} - -@c -@r{ @: 0-9 @:number @: @:@:number} -@r{ @: . @:number @: @:@:0.number} -@r{ @: _ @:number @: @:-@:number} -@r{ @: e @:number @: @:@:1e number} -@r{ @: # @:number @: @:@:current-radix@tfn{#}number} -@r{ @: P @:(in number) @: @:+/-@:} -@r{ @: M @:(in number) @: @:mod@:} -@r{ @: @@ ' " @: (in number)@: @:@:HMS form} -@r{ @: h m s @: (in number)@: @:@:HMS form} - -@c -@r{ @: ' @:formula @: 37,46 @:@:formula} -@r{ @: $ @:formula @: 37,46 @:$@:formula} -@r{ @: " @:string @: 37,46 @:@:string} - -@c -@r{ a b@: + @: @: 2 @:add@:(a,b) a+b} -@r{ a b@: - @: @: 2 @:sub@:(a,b) a@minus{}b} -@r{ a b@: * @: @: 2 @:mul@:(a,b) a b, a*b} -@r{ a b@: / @: @: 2 @:div@:(a,b) a/b} -@r{ a b@: ^ @: @: 2 @:pow@:(a,b) a^b} -@r{ a b@: I ^ @: @: 2 @:nroot@:(a,b) a^(1/b)} -@r{ a b@: % @: @: 2 @:mod@:(a,b) a%b} -@r{ a b@: \ @: @: 2 @:idiv@:(a,b) a\b} -@r{ a b@: : @: @: 2 @:fdiv@:(a,b)} -@r{ a b@: | @: @: 2 @:vconcat@:(a,b) a|b} -@r{ a b@: I | @: @: @:vconcat@:(b,a) b|a} -@r{ a b@: H | @: @: 2 @:append@:(a,b)} -@r{ a b@: I H | @: @: @:append@:(b,a)} -@r{ a@: & @: @: 1 @:inv@:(a) 1/a} -@r{ a@: ! @: @: 1 @:fact@:(a) a!} -@r{ a@: = @: @: 1 @:evalv@:(a)} -@r{ a@: M-% @: @: @:percent@:(a) a%} - -@c -@r{ ... a@: @summarykey{RET} @: @: 1 @:@:... a a} -@r{ ... a@: @summarykey{SPC} @: @: 1 @:@:... a a} -@r{... a b@: @summarykey{TAB} @: @: 3 @:@:... b a} -@r{. a b c@: M-@summarykey{TAB} @: @: 3 @:@:... b c a} -@r{... a b@: @summarykey{LFD} @: @: 1 @:@:... a b a} -@r{ ... a@: @summarykey{DEL} @: @: 1 @:@:...} -@r{... a b@: M-@summarykey{DEL} @: @: 1 @:@:... b} -@r{ @: M-@summarykey{RET} @: @: 4 @:calc-last-args@:} -@r{ a@: ` @:editing @: 1,30 @:calc-edit@:} - -@c -@r{ ... a@: C-d @: @: 1 @:@:...} -@r{ @: C-k @: @: 27 @:calc-kill@:} -@r{ @: C-w @: @: 27 @:calc-kill-region@:} -@r{ @: C-y @: @: @:calc-yank@:} -@r{ @: C-_ @: @: 4 @:calc-undo@:} -@r{ @: M-k @: @: 27 @:calc-copy-as-kill@:} -@r{ @: M-w @: @: 27 @:calc-copy-region-as-kill@:} - -@c -@r{ @: [ @: @: @:@:[...} -@r{[.. a b@: ] @: @: @:@:[a,b]} -@r{ @: ( @: @: @:@:(...} -@r{(.. a b@: ) @: @: @:@:(a,b)} -@r{ @: , @: @: @:@:vector or rect complex} -@r{ @: ; @: @: @:@:matrix or polar complex} -@r{ @: .. @: @: @:@:interval} - -@c -@r{ @: ~ @: @: @:calc-num-prefix@:} -@r{ @: < @: @: 4 @:calc-scroll-left@:} -@r{ @: > @: @: 4 @:calc-scroll-right@:} -@r{ @: @{ @: @: 4 @:calc-scroll-down@:} -@r{ @: @} @: @: 4 @:calc-scroll-up@:} -@r{ @: ? @: @: @:calc-help@:} - -@c -@r{ a@: n @: @: 1 @:neg@:(a) @minus{}a} -@r{ @: o @: @: 4 @:calc-realign@:} -@r{ @: p @:precision @: 31 @:calc-precision@:} -@r{ @: q @: @: @:calc-quit@:} -@r{ @: w @: @: @:calc-why@:} -@r{ @: x @:command @: @:M-x calc-@:command} -@r{ a@: y @: @:1,28,49 @:calc-copy-to-buffer@:} - -@c -@r{ a@: A @: @: 1 @:abs@:(a)} -@r{ a b@: B @: @: 2 @:log@:(a,b)} -@r{ a b@: I B @: @: 2 @:alog@:(a,b) b^a} -@r{ a@: C @: @: 1 @:cos@:(a)} -@r{ a@: I C @: @: 1 @:arccos@:(a)} -@r{ a@: H C @: @: 1 @:cosh@:(a)} -@r{ a@: I H C @: @: 1 @:arccosh@:(a)} -@r{ @: D @: @: 4 @:calc-redo@:} -@r{ a@: E @: @: 1 @:exp@:(a)} -@r{ a@: H E @: @: 1 @:exp10@:(a) 10.^a} -@r{ a@: F @: @: 1,11 @:floor@:(a,d)} -@r{ a@: I F @: @: 1,11 @:ceil@:(a,d)} -@r{ a@: H F @: @: 1,11 @:ffloor@:(a,d)} -@r{ a@: I H F @: @: 1,11 @:fceil@:(a,d)} -@r{ a@: G @: @: 1 @:arg@:(a)} -@r{ @: H @:command @: 32 @:@:Hyperbolic} -@r{ @: I @:command @: 32 @:@:Inverse} -@r{ a@: J @: @: 1 @:conj@:(a)} -@r{ @: K @:command @: 32 @:@:Keep-args} -@r{ a@: L @: @: 1 @:ln@:(a)} -@r{ a@: H L @: @: 1 @:log10@:(a)} -@r{ @: M @: @: @:calc-more-recursion-depth@:} -@r{ @: I M @: @: @:calc-less-recursion-depth@:} -@r{ a@: N @: @: 5 @:evalvn@:(a)} -@r{ @: O @:command @: 32 @:@:Option} -@r{ @: P @: @: @:@:pi} -@r{ @: I P @: @: @:@:gamma} -@r{ @: H P @: @: @:@:e} -@r{ @: I H P @: @: @:@:phi} -@r{ a@: Q @: @: 1 @:sqrt@:(a)} -@r{ a@: I Q @: @: 1 @:sqr@:(a) a^2} -@r{ a@: R @: @: 1,11 @:round@:(a,d)} -@r{ a@: I R @: @: 1,11 @:trunc@:(a,d)} -@r{ a@: H R @: @: 1,11 @:fround@:(a,d)} -@r{ a@: I H R @: @: 1,11 @:ftrunc@:(a,d)} -@r{ a@: S @: @: 1 @:sin@:(a)} -@r{ a@: I S @: @: 1 @:arcsin@:(a)} -@r{ a@: H S @: @: 1 @:sinh@:(a)} -@r{ a@: I H S @: @: 1 @:arcsinh@:(a)} -@r{ a@: T @: @: 1 @:tan@:(a)} -@r{ a@: I T @: @: 1 @:arctan@:(a)} -@r{ a@: H T @: @: 1 @:tanh@:(a)} -@r{ a@: I H T @: @: 1 @:arctanh@:(a)} -@r{ @: U @: @: 4 @:calc-undo@:} -@r{ @: X @: @: 4 @:calc-call-last-kbd-macro@:} - -@c -@r{ a b@: a = @: @: 2 @:eq@:(a,b) a=b} -@r{ a b@: a # @: @: 2 @:neq@:(a,b) a!=b} -@r{ a b@: a < @: @: 2 @:lt@:(a,b) a @: @: 2 @:gt@:(a,b) a>b} -@r{ a b@: a [ @: @: 2 @:leq@:(a,b) a<=b} -@r{ a b@: a ] @: @: 2 @:geq@:(a,b) a>=b} -@r{ a b@: a @{ @: @: 2 @:in@:(a,b)} -@r{ a b@: a & @: @: 2,45 @:land@:(a,b) a&&b} -@r{ a b@: a | @: @: 2,45 @:lor@:(a,b) a||b} -@r{ a@: a ! @: @: 1,45 @:lnot@:(a) !a} -@r{ a b c@: a : @: @: 45 @:if@:(a,b,c) a?b:c} -@r{ a@: a . @: @: 1 @:rmeq@:(a)} -@r{ a@: a " @: @: 7,8 @:calc-expand-formula@:} - -@c -@r{ a@: a + @:i, l, h @: 6,38 @:sum@:(a,i,l,h)} -@r{ a@: a - @:i, l, h @: 6,38 @:asum@:(a,i,l,h)} -@r{ a@: a * @:i, l, h @: 6,38 @:prod@:(a,i,l,h)} -@r{ a b@: a _ @: @: 2 @:subscr@:(a,b) a_b} - -@c -@r{ a b@: a \ @: @: 2 @:pdiv@:(a,b)} -@r{ a b@: a % @: @: 2 @:prem@:(a,b)} -@r{ a b@: a / @: @: 2 @:pdivrem@:(a,b) [q,r]} -@r{ a b@: H a / @: @: 2 @:pdivide@:(a,b) q+r/b} - -@c -@r{ a@: a a @: @: 1 @:apart@:(a)} -@r{ a@: a b @:old, new @: 38 @:subst@:(a,old,new)} -@r{ a@: a c @:v @: 38 @:collect@:(a,v)} -@r{ a@: a d @:v @: 4,38 @:deriv@:(a,v)} -@r{ a@: H a d @:v @: 4,38 @:tderiv@:(a,v)} -@r{ a@: a e @: @: @:esimplify@:(a)} -@r{ a@: a f @: @: 1 @:factor@:(a)} -@r{ a@: H a f @: @: 1 @:factors@:(a)} -@r{ a b@: a g @: @: 2 @:pgcd@:(a,b)} -@r{ a@: a i @:v @: 38 @:integ@:(a,v)} -@r{ a@: a m @:pats @: 38 @:match@:(a,pats)} -@r{ a@: I a m @:pats @: 38 @:matchnot@:(a,pats)} -@r{ data x@: a p @: @: 28 @:polint@:(data,x)} -@r{ data x@: H a p @: @: 28 @:ratint@:(data,x)} -@r{ a@: a n @: @: 1 @:nrat@:(a)} -@r{ a@: a r @:rules @:4,8,38 @:rewrite@:(a,rules,n)} -@r{ a@: a s @: @: @:simplify@:(a)} -@r{ a@: a t @:v, n @: 31,39 @:taylor@:(a,v,n)} -@r{ a@: a v @: @: 7,8 @:calc-alg-evaluate@:} -@r{ a@: a x @: @: 4,8 @:expand@:(a)} - -@c -@r{ data@: a F @:model, vars @: 48 @:fit@:(m,iv,pv,data)} -@r{ data@: I a F @:model, vars @: 48 @:xfit@:(m,iv,pv,data)} -@r{ data@: H a F @:model, vars @: 48 @:efit@:(m,iv,pv,data)} -@r{ a@: a I @:v, l, h @: 38 @:ninteg@:(a,v,l,h)} -@r{ a b@: a M @:op @: 22 @:mapeq@:(op,a,b)} -@r{ a b@: I a M @:op @: 22 @:mapeqr@:(op,a,b)} -@r{ a b@: H a M @:op @: 22 @:mapeqp@:(op,a,b)} -@r{ a g@: a N @:v @: 38 @:minimize@:(a,v,g)} -@r{ a g@: H a N @:v @: 38 @:wminimize@:(a,v,g)} -@r{ a@: a P @:v @: 38 @:roots@:(a,v)} -@r{ a g@: a R @:v @: 38 @:root@:(a,v,g)} -@r{ a g@: H a R @:v @: 38 @:wroot@:(a,v,g)} -@r{ a@: a S @:v @: 38 @:solve@:(a,v)} -@r{ a@: I a S @:v @: 38 @:finv@:(a,v)} -@r{ a@: H a S @:v @: 38 @:fsolve@:(a,v)} -@r{ a@: I H a S @:v @: 38 @:ffinv@:(a,v)} -@r{ a@: a T @:i, l, h @: 6,38 @:table@:(a,i,l,h)} -@r{ a g@: a X @:v @: 38 @:maximize@:(a,v,g)} -@r{ a g@: H a X @:v @: 38 @:wmaximize@:(a,v,g)} - -@c -@r{ a b@: b a @: @: 9 @:and@:(a,b,w)} -@r{ a@: b c @: @: 9 @:clip@:(a,w)} -@r{ a b@: b d @: @: 9 @:diff@:(a,b,w)} -@r{ a@: b l @: @: 10 @:lsh@:(a,n,w)} -@r{ a n@: H b l @: @: 9 @:lsh@:(a,n,w)} -@r{ a@: b n @: @: 9 @:not@:(a,w)} -@r{ a b@: b o @: @: 9 @:or@:(a,b,w)} -@r{ v@: b p @: @: 1 @:vpack@:(v)} -@r{ a@: b r @: @: 10 @:rsh@:(a,n,w)} -@r{ a n@: H b r @: @: 9 @:rsh@:(a,n,w)} -@r{ a@: b t @: @: 10 @:rot@:(a,n,w)} -@r{ a n@: H b t @: @: 9 @:rot@:(a,n,w)} -@r{ a@: b u @: @: 1 @:vunpack@:(a)} -@r{ @: b w @:w @: 9,50 @:calc-word-size@:} -@r{ a b@: b x @: @: 9 @:xor@:(a,b,w)} - -@c -@r{c s l p@: b D @: @: @:ddb@:(c,s,l,p)} -@r{ r n p@: b F @: @: @:fv@:(r,n,p)} -@r{ r n p@: I b F @: @: @:fvb@:(r,n,p)} -@r{ r n p@: H b F @: @: @:fvl@:(r,n,p)} -@r{ v@: b I @: @: 19 @:irr@:(v)} -@r{ v@: I b I @: @: 19 @:irrb@:(v)} -@r{ a@: b L @: @: 10 @:ash@:(a,n,w)} -@r{ a n@: H b L @: @: 9 @:ash@:(a,n,w)} -@r{ r n a@: b M @: @: @:pmt@:(r,n,a)} -@r{ r n a@: I b M @: @: @:pmtb@:(r,n,a)} -@r{ r n a@: H b M @: @: @:pmtl@:(r,n,a)} -@r{ r v@: b N @: @: 19 @:npv@:(r,v)} -@r{ r v@: I b N @: @: 19 @:npvb@:(r,v)} -@r{ r n p@: b P @: @: @:pv@:(r,n,p)} -@r{ r n p@: I b P @: @: @:pvb@:(r,n,p)} -@r{ r n p@: H b P @: @: @:pvl@:(r,n,p)} -@r{ a@: b R @: @: 10 @:rash@:(a,n,w)} -@r{ a n@: H b R @: @: 9 @:rash@:(a,n,w)} -@r{ c s l@: b S @: @: @:sln@:(c,s,l)} -@r{ n p a@: b T @: @: @:rate@:(n,p,a)} -@r{ n p a@: I b T @: @: @:rateb@:(n,p,a)} -@r{ n p a@: H b T @: @: @:ratel@:(n,p,a)} -@r{c s l p@: b Y @: @: @:syd@:(c,s,l,p)} - -@r{ r p a@: b # @: @: @:nper@:(r,p,a)} -@r{ r p a@: I b # @: @: @:nperb@:(r,p,a)} -@r{ r p a@: H b # @: @: @:nperl@:(r,p,a)} -@r{ a b@: b % @: @: @:relch@:(a,b)} - -@c -@r{ a@: c c @: @: 5 @:pclean@:(a,p)} -@r{ a@: c 0-9 @: @: @:pclean@:(a,p)} -@r{ a@: H c c @: @: 5 @:clean@:(a,p)} -@r{ a@: H c 0-9 @: @: @:clean@:(a,p)} -@r{ a@: c d @: @: 1 @:deg@:(a)} -@r{ a@: c f @: @: 1 @:pfloat@:(a)} -@r{ a@: H c f @: @: 1 @:float@:(a)} -@r{ a@: c h @: @: 1 @:hms@:(a)} -@r{ a@: c p @: @: @:polar@:(a)} -@r{ a@: I c p @: @: @:rect@:(a)} -@r{ a@: c r @: @: 1 @:rad@:(a)} - -@c -@r{ a@: c F @: @: 5 @:pfrac@:(a,p)} -@r{ a@: H c F @: @: 5 @:frac@:(a,p)} - -@c -@r{ a@: c % @: @: @:percent@:(a*100)} - -@c -@r{ @: d . @:char @: 50 @:calc-point-char@:} -@r{ @: d , @:char @: 50 @:calc-group-char@:} -@r{ @: d < @: @: 13,50 @:calc-left-justify@:} -@r{ @: d = @: @: 13,50 @:calc-center-justify@:} -@r{ @: d > @: @: 13,50 @:calc-right-justify@:} -@r{ @: d @{ @:label @: 50 @:calc-left-label@:} -@r{ @: d @} @:label @: 50 @:calc-right-label@:} -@r{ @: d [ @: @: 4 @:calc-truncate-up@:} -@r{ @: d ] @: @: 4 @:calc-truncate-down@:} -@r{ @: d " @: @: 12,50 @:calc-display-strings@:} -@r{ @: d @summarykey{SPC} @: @: @:calc-refresh@:} -@r{ @: d @summarykey{RET} @: @: 1 @:calc-refresh-top@:} - -@c -@r{ @: d 0 @: @: 50 @:calc-decimal-radix@:} -@r{ @: d 2 @: @: 50 @:calc-binary-radix@:} -@r{ @: d 6 @: @: 50 @:calc-hex-radix@:} -@r{ @: d 8 @: @: 50 @:calc-octal-radix@:} - -@c -@r{ @: d b @: @:12,13,50 @:calc-line-breaking@:} -@r{ @: d c @: @: 50 @:calc-complex-notation@:} -@r{ @: d d @:format @: 50 @:calc-date-notation@:} -@r{ @: d e @: @: 5,50 @:calc-eng-notation@:} -@r{ @: d f @:num @: 31,50 @:calc-fix-notation@:} -@r{ @: d g @: @:12,13,50 @:calc-group-digits@:} -@r{ @: d h @:format @: 50 @:calc-hms-notation@:} -@r{ @: d i @: @: 50 @:calc-i-notation@:} -@r{ @: d j @: @: 50 @:calc-j-notation@:} -@r{ @: d l @: @: 12,50 @:calc-line-numbering@:} -@r{ @: d n @: @: 5,50 @:calc-normal-notation@:} -@r{ @: d o @:format @: 50 @:calc-over-notation@:} -@r{ @: d p @: @: 12,50 @:calc-show-plain@:} -@r{ @: d r @:radix @: 31,50 @:calc-radix@:} -@r{ @: d s @: @: 5,50 @:calc-sci-notation@:} -@r{ @: d t @: @: 27 @:calc-truncate-stack@:} -@r{ @: d w @: @: 12,13 @:calc-auto-why@:} -@r{ @: d z @: @: 12,50 @:calc-leading-zeros@:} - -@c -@r{ @: d B @: @: 50 @:calc-big-language@:} -@r{ @: d C @: @: 50 @:calc-c-language@:} -@r{ @: d E @: @: 50 @:calc-eqn-language@:} -@r{ @: d F @: @: 50 @:calc-fortran-language@:} -@r{ @: d M @: @: 50 @:calc-mathematica-language@:} -@r{ @: d N @: @: 50 @:calc-normal-language@:} -@r{ @: d O @: @: 50 @:calc-flat-language@:} -@r{ @: d P @: @: 50 @:calc-pascal-language@:} -@r{ @: d T @: @: 50 @:calc-tex-language@:} -@r{ @: d L @: @: 50 @:calc-latex-language@:} -@r{ @: d U @: @: 50 @:calc-unformatted-language@:} -@r{ @: d W @: @: 50 @:calc-maple-language@:} - -@c -@r{ a@: f [ @: @: 4 @:decr@:(a,n)} -@r{ a@: f ] @: @: 4 @:incr@:(a,n)} - -@c -@r{ a b@: f b @: @: 2 @:beta@:(a,b)} -@r{ a@: f e @: @: 1 @:erf@:(a)} -@r{ a@: I f e @: @: 1 @:erfc@:(a)} -@r{ a@: f g @: @: 1 @:gamma@:(a)} -@r{ a b@: f h @: @: 2 @:hypot@:(a,b)} -@r{ a@: f i @: @: 1 @:im@:(a)} -@r{ n a@: f j @: @: 2 @:besJ@:(n,a)} -@r{ a b@: f n @: @: 2 @:min@:(a,b)} -@r{ a@: f r @: @: 1 @:re@:(a)} -@r{ a@: f s @: @: 1 @:sign@:(a)} -@r{ a b@: f x @: @: 2 @:max@:(a,b)} -@r{ n a@: f y @: @: 2 @:besY@:(n,a)} - -@c -@r{ a@: f A @: @: 1 @:abssqr@:(a)} -@r{ x a b@: f B @: @: @:betaI@:(x,a,b)} -@r{ x a b@: H f B @: @: @:betaB@:(x,a,b)} -@r{ a@: f E @: @: 1 @:expm1@:(a)} -@r{ a x@: f G @: @: 2 @:gammaP@:(a,x)} -@r{ a x@: I f G @: @: 2 @:gammaQ@:(a,x)} -@r{ a x@: H f G @: @: 2 @:gammag@:(a,x)} -@r{ a x@: I H f G @: @: 2 @:gammaG@:(a,x)} -@r{ a b@: f I @: @: 2 @:ilog@:(a,b)} -@r{ a b@: I f I @: @: 2 @:alog@:(a,b) b^a} -@r{ a@: f L @: @: 1 @:lnp1@:(a)} -@r{ a@: f M @: @: 1 @:mant@:(a)} -@r{ a@: f Q @: @: 1 @:isqrt@:(a)} -@r{ a@: I f Q @: @: 1 @:sqr@:(a) a^2} -@r{ a n@: f S @: @: 2 @:scf@:(a,n)} -@r{ y x@: f T @: @: @:arctan2@:(y,x)} -@r{ a@: f X @: @: 1 @:xpon@:(a)} - -@c -@r{ x y@: g a @: @: 28,40 @:calc-graph-add@:} -@r{ @: g b @: @: 12 @:calc-graph-border@:} -@r{ @: g c @: @: @:calc-graph-clear@:} -@r{ @: g d @: @: 41 @:calc-graph-delete@:} -@r{ x y@: g f @: @: 28,40 @:calc-graph-fast@:} -@r{ @: g g @: @: 12 @:calc-graph-grid@:} -@r{ @: g h @:title @: @:calc-graph-header@:} -@r{ @: g j @: @: 4 @:calc-graph-juggle@:} -@r{ @: g k @: @: 12 @:calc-graph-key@:} -@r{ @: g l @: @: 12 @:calc-graph-log-x@:} -@r{ @: g n @:name @: @:calc-graph-name@:} -@r{ @: g p @: @: 42 @:calc-graph-plot@:} -@r{ @: g q @: @: @:calc-graph-quit@:} -@r{ @: g r @:range @: @:calc-graph-range-x@:} -@r{ @: g s @: @: 12,13 @:calc-graph-line-style@:} -@r{ @: g t @:title @: @:calc-graph-title-x@:} -@r{ @: g v @: @: @:calc-graph-view-commands@:} -@r{ @: g x @:display @: @:calc-graph-display@:} -@r{ @: g z @: @: 12 @:calc-graph-zero-x@:} - -@c -@r{ x y z@: g A @: @: 28,40 @:calc-graph-add-3d@:} -@r{ @: g C @:command @: @:calc-graph-command@:} -@r{ @: g D @:device @: 43,44 @:calc-graph-device@:} -@r{ x y z@: g F @: @: 28,40 @:calc-graph-fast-3d@:} -@r{ @: g H @: @: 12 @:calc-graph-hide@:} -@r{ @: g K @: @: @:calc-graph-kill@:} -@r{ @: g L @: @: 12 @:calc-graph-log-y@:} -@r{ @: g N @:number @: 43,51 @:calc-graph-num-points@:} -@r{ @: g O @:filename @: 43,44 @:calc-graph-output@:} -@r{ @: g P @: @: 42 @:calc-graph-print@:} -@r{ @: g R @:range @: @:calc-graph-range-y@:} -@r{ @: g S @: @: 12,13 @:calc-graph-point-style@:} -@r{ @: g T @:title @: @:calc-graph-title-y@:} -@r{ @: g V @: @: @:calc-graph-view-trail@:} -@r{ @: g X @:format @: @:calc-graph-geometry@:} -@r{ @: g Z @: @: 12 @:calc-graph-zero-y@:} - -@c -@r{ @: g C-l @: @: 12 @:calc-graph-log-z@:} -@r{ @: g C-r @:range @: @:calc-graph-range-z@:} -@r{ @: g C-t @:title @: @:calc-graph-title-z@:} - -@c -@r{ @: h b @: @: @:calc-describe-bindings@:} -@r{ @: h c @:key @: @:calc-describe-key-briefly@:} -@r{ @: h f @:function @: @:calc-describe-function@:} -@r{ @: h h @: @: @:calc-full-help@:} -@r{ @: h i @: @: @:calc-info@:} -@r{ @: h k @:key @: @:calc-describe-key@:} -@r{ @: h n @: @: @:calc-view-news@:} -@r{ @: h s @: @: @:calc-info-summary@:} -@r{ @: h t @: @: @:calc-tutorial@:} -@r{ @: h v @:var @: @:calc-describe-variable@:} - -@c -@r{ @: j 1-9 @: @: @:calc-select-part@:} -@r{ @: j @summarykey{RET} @: @: 27 @:calc-copy-selection@:} -@r{ @: j @summarykey{DEL} @: @: 27 @:calc-del-selection@:} -@r{ @: j ' @:formula @: 27 @:calc-enter-selection@:} -@r{ @: j ` @:editing @: 27,30 @:calc-edit-selection@:} -@r{ @: j " @: @: 7,27 @:calc-sel-expand-formula@:} - -@c -@r{ @: j + @:formula @: 27 @:calc-sel-add-both-sides@:} -@r{ @: j - @:formula @: 27 @:calc-sel-sub-both-sides@:} -@r{ @: j * @:formula @: 27 @:calc-sel-mul-both-sides@:} -@r{ @: j / @:formula @: 27 @:calc-sel-div-both-sides@:} -@r{ @: j & @: @: 27 @:calc-sel-invert@:} - -@c -@r{ @: j a @: @: 27 @:calc-select-additional@:} -@r{ @: j b @: @: 12 @:calc-break-selections@:} -@r{ @: j c @: @: @:calc-clear-selections@:} -@r{ @: j d @: @: 12,50 @:calc-show-selections@:} -@r{ @: j e @: @: 12 @:calc-enable-selections@:} -@r{ @: j l @: @: 4,27 @:calc-select-less@:} -@r{ @: j m @: @: 4,27 @:calc-select-more@:} -@r{ @: j n @: @: 4 @:calc-select-next@:} -@r{ @: j o @: @: 4,27 @:calc-select-once@:} -@r{ @: j p @: @: 4 @:calc-select-previous@:} -@r{ @: j r @:rules @:4,8,27 @:calc-rewrite-selection@:} -@r{ @: j s @: @: 4,27 @:calc-select-here@:} -@r{ @: j u @: @: 27 @:calc-unselect@:} -@r{ @: j v @: @: 7,27 @:calc-sel-evaluate@:} - -@c -@r{ @: j C @: @: 27 @:calc-sel-commute@:} -@r{ @: j D @: @: 4,27 @:calc-sel-distribute@:} -@r{ @: j E @: @: 27 @:calc-sel-jump-equals@:} -@r{ @: j I @: @: 27 @:calc-sel-isolate@:} -@r{ @: H j I @: @: 27 @:calc-sel-isolate@: (full)} -@r{ @: j L @: @: 4,27 @:calc-commute-left@:} -@r{ @: j M @: @: 27 @:calc-sel-merge@:} -@r{ @: j N @: @: 27 @:calc-sel-negate@:} -@r{ @: j O @: @: 4,27 @:calc-select-once-maybe@:} -@r{ @: j R @: @: 4,27 @:calc-commute-right@:} -@r{ @: j S @: @: 4,27 @:calc-select-here-maybe@:} -@r{ @: j U @: @: 27 @:calc-sel-unpack@:} - -@c -@r{ @: k a @: @: @:calc-random-again@:} -@r{ n@: k b @: @: 1 @:bern@:(n)} -@r{ n x@: H k b @: @: 2 @:bern@:(n,x)} -@r{ n m@: k c @: @: 2 @:choose@:(n,m)} -@r{ n m@: H k c @: @: 2 @:perm@:(n,m)} -@r{ n@: k d @: @: 1 @:dfact@:(n) n!!} -@r{ n@: k e @: @: 1 @:euler@:(n)} -@r{ n x@: H k e @: @: 2 @:euler@:(n,x)} -@r{ n@: k f @: @: 4 @:prfac@:(n)} -@r{ n m@: k g @: @: 2 @:gcd@:(n,m)} -@r{ m n@: k h @: @: 14 @:shuffle@:(n,m)} -@r{ n m@: k l @: @: 2 @:lcm@:(n,m)} -@r{ n@: k m @: @: 1 @:moebius@:(n)} -@r{ n@: k n @: @: 4 @:nextprime@:(n)} -@r{ n@: I k n @: @: 4 @:prevprime@:(n)} -@r{ n@: k p @: @: 4,28 @:calc-prime-test@:} -@r{ m@: k r @: @: 14 @:random@:(m)} -@r{ n m@: k s @: @: 2 @:stir1@:(n,m)} -@r{ n m@: H k s @: @: 2 @:stir2@:(n,m)} -@r{ n@: k t @: @: 1 @:totient@:(n)} - -@c -@r{ n p x@: k B @: @: @:utpb@:(x,n,p)} -@r{ n p x@: I k B @: @: @:ltpb@:(x,n,p)} -@r{ v x@: k C @: @: @:utpc@:(x,v)} -@r{ v x@: I k C @: @: @:ltpc@:(x,v)} -@r{ n m@: k E @: @: @:egcd@:(n,m)} -@r{v1 v2 x@: k F @: @: @:utpf@:(x,v1,v2)} -@r{v1 v2 x@: I k F @: @: @:ltpf@:(x,v1,v2)} -@r{ m s x@: k N @: @: @:utpn@:(x,m,s)} -@r{ m s x@: I k N @: @: @:ltpn@:(x,m,s)} -@r{ m x@: k P @: @: @:utpp@:(x,m)} -@r{ m x@: I k P @: @: @:ltpp@:(x,m)} -@r{ v x@: k T @: @: @:utpt@:(x,v)} -@r{ v x@: I k T @: @: @:ltpt@:(x,v)} - -@c -@r{ a b@: l + @: @: @:lupadd@:(a,b)} -@r{ a b@: H l + @: @: @:lufadd@:(a,b)} -@r{ a b@: l - @: @: @:lupsub@:(a,b)} -@r{ a b@: H l - @: @: @:lufsub@:(a,b)} -@r{ a b@: l * @: @: @:lupmul@:(a,b)} -@r{ a b@: H l * @: @: @:lufmul@:(a,b)} -@r{ a b@: l / @: @: @:lupdiv@:(a,b)} -@r{ a b@: H l / @: @: @:lufdiv@:(a,b)} -@r{ a@: l d @: @: @:dbpower@:(a)} -@r{ a b@: O l d @: @: @:dbpower@:(a,b)} -@r{ a@: H l d @: @: @:dbfield@:(a)} -@r{ a b@: O H l d @: @: @:dbfield@:(a,b)} -@r{ a@: l n @: @: @:nppower@:(a)} -@r{ a b@: O l n @: @: @:nppower@:(a,b)} -@r{ a@: H l n @: @: @:npfield@:(a)} -@r{ a b@: O H l n @: @: @:npfield@:(a,b)} -@r{ a@: l q @: @: @:lupquant@:(a)} -@r{ a b@: O l q @: @: @:lupquant@:(a,b)} -@r{ a@: H l q @: @: @:lufquant@:(a)} -@r{ a b@: O H l q @: @: @:lufquant@:(a,b)} -@r{ a@: l s @: @: @:spn@:(a)} -@r{ a@: l m @: @: @:midi@:(a)} -@r{ a@: l f @: @: @:freq@:(a)} - -@c -@r{ @: m a @: @: 12,13 @:calc-algebraic-mode@:} -@r{ @: m d @: @: @:calc-degrees-mode@:} -@r{ @: m e @: @: @:calc-embedded-preserve-modes@:} -@r{ @: m f @: @: 12 @:calc-frac-mode@:} -@r{ @: m g @: @: 52 @:calc-get-modes@:} -@r{ @: m h @: @: @:calc-hms-mode@:} -@r{ @: m i @: @: 12,13 @:calc-infinite-mode@:} -@r{ @: m m @: @: @:calc-save-modes@:} -@r{ @: m p @: @: 12 @:calc-polar-mode@:} -@r{ @: m r @: @: @:calc-radians-mode@:} -@r{ @: m s @: @: 12 @:calc-symbolic-mode@:} -@r{ @: m t @: @: 12 @:calc-total-algebraic-mode@:} -@r{ @: m v @: @: 12,13 @:calc-matrix-mode@:} -@r{ @: m w @: @: 13 @:calc-working@:} -@r{ @: m x @: @: @:calc-always-load-extensions@:} - -@c -@r{ @: m A @: @: 12 @:calc-alg-simplify-mode@:} -@r{ @: m B @: @: 12 @:calc-bin-simplify-mode@:} -@r{ @: m C @: @: 12 @:calc-auto-recompute@:} -@r{ @: m D @: @: @:calc-default-simplify-mode@:} -@r{ @: m E @: @: 12 @:calc-ext-simplify-mode@:} -@r{ @: m F @:filename @: 13 @:calc-settings-file-name@:} -@r{ @: m N @: @: 12 @:calc-num-simplify-mode@:} -@r{ @: m O @: @: 12 @:calc-no-simplify-mode@:} -@r{ @: m R @: @: 12,13 @:calc-mode-record-mode@:} -@r{ @: m S @: @: 12 @:calc-shift-prefix@:} -@r{ @: m U @: @: 12 @:calc-units-simplify-mode@:} - -@c -@r{ @: r s @:register @: 27 @:calc-copy-to-register@:} -@r{ @: r i @:register @: @:calc-insert-register@:} - -@c -@r{ @: s c @:var1, var2 @: 29 @:calc-copy-variable@:} -@r{ @: s d @:var, decl @: @:calc-declare-variable@:} -@r{ @: s e @:var, editing @: 29,30 @:calc-edit-variable@:} -@r{ @: s i @:buffer @: @:calc-insert-variables@:} -@r{ @: s k @:const, var @: 29 @:calc-copy-special-constant@:} -@r{ a b@: s l @:var @: 29 @:@:a (letting var=b)} -@r{ a ...@: s m @:op, var @: 22,29 @:calc-store-map@:} -@r{ @: s n @:var @: 29,47 @:calc-store-neg@: (v/-1)} -@r{ @: s p @:var @: 29 @:calc-permanent-variable@:} -@r{ @: s r @:var @: 29 @:@:v (recalled value)} -@r{ @: r 0-9 @: @: @:calc-recall-quick@:} -@r{ a@: s s @:var @: 28,29 @:calc-store@:} -@r{ a@: s 0-9 @: @: @:calc-store-quick@:} -@r{ a@: s t @:var @: 29 @:calc-store-into@:} -@r{ a@: t 0-9 @: @: @:calc-store-into-quick@:} -@r{ @: s u @:var @: 29 @:calc-unstore@:} -@r{ a@: s x @:var @: 29 @:calc-store-exchange@:} - -@c -@r{ @: s A @:editing @: 30 @:calc-edit-AlgSimpRules@:} -@r{ @: s D @:editing @: 30 @:calc-edit-Decls@:} -@r{ @: s E @:editing @: 30 @:calc-edit-EvalRules@:} -@r{ @: s F @:editing @: 30 @:calc-edit-FitRules@:} -@r{ @: s G @:editing @: 30 @:calc-edit-GenCount@:} -@r{ @: s H @:editing @: 30 @:calc-edit-Holidays@:} -@r{ @: s I @:editing @: 30 @:calc-edit-IntegLimit@:} -@r{ @: s L @:editing @: 30 @:calc-edit-LineStyles@:} -@r{ @: s P @:editing @: 30 @:calc-edit-PointStyles@:} -@r{ @: s R @:editing @: 30 @:calc-edit-PlotRejects@:} -@r{ @: s T @:editing @: 30 @:calc-edit-TimeZone@:} -@r{ @: s U @:editing @: 30 @:calc-edit-Units@:} -@r{ @: s X @:editing @: 30 @:calc-edit-ExtSimpRules@:} - -@c -@r{ a@: s + @:var @: 29,47 @:calc-store-plus@: (v+a)} -@r{ a@: s - @:var @: 29,47 @:calc-store-minus@: (v-a)} -@r{ a@: s * @:var @: 29,47 @:calc-store-times@: (v*a)} -@r{ a@: s / @:var @: 29,47 @:calc-store-div@: (v/a)} -@r{ a@: s ^ @:var @: 29,47 @:calc-store-power@: (v^a)} -@r{ a@: s | @:var @: 29,47 @:calc-store-concat@: (v|a)} -@r{ @: s & @:var @: 29,47 @:calc-store-inv@: (v^-1)} -@r{ @: s [ @:var @: 29,47 @:calc-store-decr@: (v-1)} -@r{ @: s ] @:var @: 29,47 @:calc-store-incr@: (v-(-1))} -@r{ a b@: s : @: @: 2 @:assign@:(a,b) a @tfn{:=} b} -@r{ a@: s = @: @: 1 @:evalto@:(a,b) a @tfn{=>}} - -@c -@r{ @: t [ @: @: 4 @:calc-trail-first@:} -@r{ @: t ] @: @: 4 @:calc-trail-last@:} -@r{ @: t < @: @: 4 @:calc-trail-scroll-left@:} -@r{ @: t > @: @: 4 @:calc-trail-scroll-right@:} -@r{ @: t . @: @: 12 @:calc-full-trail-vectors@:} - -@c -@r{ @: t b @: @: 4 @:calc-trail-backward@:} -@r{ @: t d @: @: 12,50 @:calc-trail-display@:} -@r{ @: t f @: @: 4 @:calc-trail-forward@:} -@r{ @: t h @: @: @:calc-trail-here@:} -@r{ @: t i @: @: @:calc-trail-in@:} -@r{ @: t k @: @: 4 @:calc-trail-kill@:} -@r{ @: t m @:string @: @:calc-trail-marker@:} -@r{ @: t n @: @: 4 @:calc-trail-next@:} -@r{ @: t o @: @: @:calc-trail-out@:} -@r{ @: t p @: @: 4 @:calc-trail-previous@:} -@r{ @: t r @:string @: @:calc-trail-isearch-backward@:} -@r{ @: t s @:string @: @:calc-trail-isearch-forward@:} -@r{ @: t y @: @: 4 @:calc-trail-yank@:} - -@c -@r{ d@: t C @:oz, nz @: @:tzconv@:(d,oz,nz)} -@r{d oz nz@: t C @:$ @: @:tzconv@:(d,oz,nz)} -@r{ d@: t D @: @: 15 @:date@:(d)} -@r{ d@: t I @: @: 4 @:incmonth@:(d,n)} -@r{ d@: t J @: @: 16 @:julian@:(d,z)} -@r{ d@: t M @: @: 17 @:newmonth@:(d,n)} -@r{ @: t N @: @: 16 @:now@:(z)} -@r{ d@: t P @:1 @: 31 @:year@:(d)} -@r{ d@: t P @:2 @: 31 @:month@:(d)} -@r{ d@: t P @:3 @: 31 @:day@:(d)} -@r{ d@: t P @:4 @: 31 @:hour@:(d)} -@r{ d@: t P @:5 @: 31 @:minute@:(d)} -@r{ d@: t P @:6 @: 31 @:second@:(d)} -@r{ d@: t P @:7 @: 31 @:weekday@:(d)} -@r{ d@: t P @:8 @: 31 @:yearday@:(d)} -@r{ d@: t P @:9 @: 31 @:time@:(d)} -@r{ d@: t U @: @: 16 @:unixtime@:(d,z)} -@r{ d@: t W @: @: 17 @:newweek@:(d,w)} -@r{ d@: t Y @: @: 17 @:newyear@:(d,n)} - -@c -@r{ a b@: t + @: @: 2 @:badd@:(a,b)} -@r{ a b@: t - @: @: 2 @:bsub@:(a,b)} - -@c -@r{ @: u a @: @: 12 @:calc-autorange-units@:} -@r{ a@: u b @: @: @:calc-base-units@:} -@r{ a@: u c @:units @: 18 @:calc-convert-units@:} -@r{ defn@: u d @:unit, descr @: @:calc-define-unit@:} -@r{ @: u e @: @: @:calc-explain-units@:} -@r{ @: u g @:unit @: @:calc-get-unit-definition@:} -@r{ @: u p @: @: @:calc-permanent-units@:} -@r{ a@: u r @: @: @:calc-remove-units@:} -@r{ a@: u s @: @: @:usimplify@:(a)} -@r{ a@: u t @:units @: 18 @:calc-convert-temperature@:} -@r{ @: u u @:unit @: @:calc-undefine-unit@:} -@r{ @: u v @: @: @:calc-enter-units-table@:} -@r{ a@: u x @: @: @:calc-extract-units@:} -@r{ a@: u 0-9 @: @: @:calc-quick-units@:} - -@c -@r{ v1 v2@: u C @: @: 20 @:vcov@:(v1,v2)} -@r{ v1 v2@: I u C @: @: 20 @:vpcov@:(v1,v2)} -@r{ v1 v2@: H u C @: @: 20 @:vcorr@:(v1,v2)} -@r{ v@: u G @: @: 19 @:vgmean@:(v)} -@r{ a b@: H u G @: @: 2 @:agmean@:(a,b)} -@r{ v@: u M @: @: 19 @:vmean@:(v)} -@r{ v@: I u M @: @: 19 @:vmeane@:(v)} -@r{ v@: H u M @: @: 19 @:vmedian@:(v)} -@r{ v@: I H u M @: @: 19 @:vhmean@:(v)} -@r{ v@: u N @: @: 19 @:vmin@:(v)} -@r{ v@: u S @: @: 19 @:vsdev@:(v)} -@r{ v@: I u S @: @: 19 @:vpsdev@:(v)} -@r{ v@: H u S @: @: 19 @:vvar@:(v)} -@r{ v@: I H u S @: @: 19 @:vpvar@:(v)} -@r{ @: u V @: @: @:calc-view-units-table@:} -@r{ v@: u X @: @: 19 @:vmax@:(v)} - -@c -@r{ v@: u + @: @: 19 @:vsum@:(v)} -@r{ v@: u * @: @: 19 @:vprod@:(v)} -@r{ v@: u # @: @: 19 @:vcount@:(v)} - -@c -@r{ @: V ( @: @: 50 @:calc-vector-parens@:} -@r{ @: V @{ @: @: 50 @:calc-vector-braces@:} -@r{ @: V [ @: @: 50 @:calc-vector-brackets@:} -@r{ @: V ] @:ROCP @: 50 @:calc-matrix-brackets@:} -@r{ @: V , @: @: 50 @:calc-vector-commas@:} -@r{ @: V < @: @: 50 @:calc-matrix-left-justify@:} -@r{ @: V = @: @: 50 @:calc-matrix-center-justify@:} -@r{ @: V > @: @: 50 @:calc-matrix-right-justify@:} -@r{ @: V / @: @: 12,50 @:calc-break-vectors@:} -@r{ @: V . @: @: 12,50 @:calc-full-vectors@:} - -@c -@r{ s t@: V ^ @: @: 2 @:vint@:(s,t)} -@r{ s t@: V - @: @: 2 @:vdiff@:(s,t)} -@r{ s@: V ~ @: @: 1 @:vcompl@:(s)} -@r{ s@: V # @: @: 1 @:vcard@:(s)} -@r{ s@: V : @: @: 1 @:vspan@:(s)} -@r{ s@: V + @: @: 1 @:rdup@:(s)} - -@c -@r{ m@: V & @: @: 1 @:inv@:(m) 1/m} - -@c -@r{ v@: v a @:n @: @:arrange@:(v,n)} -@r{ a@: v b @:n @: @:cvec@:(a,n)} -@r{ v@: v c @:n >0 @: 21,31 @:mcol@:(v,n)} -@r{ v@: v c @:n <0 @: 31 @:mrcol@:(v,-n)} -@r{ m@: v c @:0 @: 31 @:getdiag@:(m)} -@r{ v@: v d @: @: 25 @:diag@:(v,n)} -@r{ v m@: v e @: @: 2 @:vexp@:(v,m)} -@r{ v m f@: H v e @: @: 2 @:vexp@:(v,m,f)} -@r{ v a@: v f @: @: 26 @:find@:(v,a,n)} -@r{ v@: v h @: @: 1 @:head@:(v)} -@r{ v@: I v h @: @: 1 @:tail@:(v)} -@r{ v@: H v h @: @: 1 @:rhead@:(v)} -@r{ v@: I H v h @: @: 1 @:rtail@:(v)} -@r{ @: v i @:n @: 31 @:idn@:(1,n)} -@r{ @: v i @:0 @: 31 @:idn@:(1)} -@r{ h t@: v k @: @: 2 @:cons@:(h,t)} -@r{ h t@: H v k @: @: 2 @:rcons@:(h,t)} -@r{ v@: v l @: @: 1 @:vlen@:(v)} -@r{ v@: H v l @: @: 1 @:mdims@:(v)} -@r{ v m@: v m @: @: 2 @:vmask@:(v,m)} -@r{ v@: v n @: @: 1 @:rnorm@:(v)} -@r{ a b c@: v p @: @: 24 @:calc-pack@:} -@r{ v@: v r @:n >0 @: 21,31 @:mrow@:(v,n)} -@r{ v@: v r @:n <0 @: 31 @:mrrow@:(v,-n)} -@r{ m@: v r @:0 @: 31 @:getdiag@:(m)} -@r{ v i j@: v s @: @: @:subvec@:(v,i,j)} -@r{ v i j@: I v s @: @: @:rsubvec@:(v,i,j)} -@r{ m@: v t @: @: 1 @:trn@:(m)} -@r{ v@: v u @: @: 24 @:calc-unpack@:} -@r{ v@: v v @: @: 1 @:rev@:(v)} -@r{ @: v x @:n @: 31 @:index@:(n)} -@r{ n s i@: C-u v x @: @: @:index@:(n,s,i)} - -@c -@r{ v@: V A @:op @: 22 @:apply@:(op,v)} -@r{ v1 v2@: V C @: @: 2 @:cross@:(v1,v2)} -@r{ m@: V D @: @: 1 @:det@:(m)} -@r{ s@: V E @: @: 1 @:venum@:(s)} -@r{ s@: V F @: @: 1 @:vfloor@:(s)} -@r{ v@: V G @: @: @:grade@:(v)} -@r{ v@: I V G @: @: @:rgrade@:(v)} -@r{ v@: V H @:n @: 31 @:histogram@:(v,n)} -@r{ v w@: H V H @:n @: 31 @:histogram@:(v,w,n)} -@r{ v1 v2@: V I @:mop aop @: 22 @:inner@:(mop,aop,v1,v2)} -@r{ m@: V J @: @: 1 @:ctrn@:(m)} -@r{ m1 m2@: V K @: @: @:kron@:(m1,m2)} -@r{ m@: V L @: @: 1 @:lud@:(m)} -@r{ v@: V M @:op @: 22,23 @:map@:(op,v)} -@r{ v@: V N @: @: 1 @:cnorm@:(v)} -@r{ v1 v2@: V O @:op @: 22 @:outer@:(op,v1,v2)} -@r{ v@: V R @:op @: 22,23 @:reduce@:(op,v)} -@r{ v@: I V R @:op @: 22,23 @:rreduce@:(op,v)} -@r{ a n@: H V R @:op @: 22 @:nest@:(op,a,n)} -@r{ a@: I H V R @:op @: 22 @:fixp@:(op,a)} -@r{ v@: V S @: @: @:sort@:(v)} -@r{ v@: I V S @: @: @:rsort@:(v)} -@r{ m@: V T @: @: 1 @:tr@:(m)} -@r{ v@: V U @:op @: 22 @:accum@:(op,v)} -@r{ v@: I V U @:op @: 22 @:raccum@:(op,v)} -@r{ a n@: H V U @:op @: 22 @:anest@:(op,a,n)} -@r{ a@: I H V U @:op @: 22 @:afixp@:(op,a)} -@r{ s t@: V V @: @: 2 @:vunion@:(s,t)} -@r{ s t@: V X @: @: 2 @:vxor@:(s,t)} - -@c -@r{ @: Y @: @: @:@:user commands} - -@c -@r{ @: z @: @: @:@:user commands} - -@c -@r{ c@: Z [ @: @: 45 @:calc-kbd-if@:} -@r{ c@: Z | @: @: 45 @:calc-kbd-else-if@:} -@r{ @: Z : @: @: @:calc-kbd-else@:} -@r{ @: Z ] @: @: @:calc-kbd-end-if@:} - -@c -@r{ @: Z @{ @: @: 4 @:calc-kbd-loop@:} -@r{ c@: Z / @: @: 45 @:calc-kbd-break@:} -@r{ @: Z @} @: @: @:calc-kbd-end-loop@:} -@r{ n@: Z < @: @: @:calc-kbd-repeat@:} -@r{ @: Z > @: @: @:calc-kbd-end-repeat@:} -@r{ n m@: Z ( @: @: @:calc-kbd-for@:} -@r{ s@: Z ) @: @: @:calc-kbd-end-for@:} - -@c -@r{ @: Z C-g @: @: @:@:cancel if/loop command} - -@c -@r{ @: Z ` @: @: @:calc-kbd-push@:} -@r{ @: Z ' @: @: @:calc-kbd-pop@:} -@r{ @: Z # @: @: @:calc-kbd-query@:} - -@c -@r{ comp@: Z C @:func, args @: 50 @:calc-user-define-composition@:} -@r{ @: Z D @:key, command @: @:calc-user-define@:} -@r{ @: Z E @:key, editing @: 30 @:calc-user-define-edit@:} -@r{ defn@: Z F @:k, c, f, a, n@: 28 @:calc-user-define-formula@:} -@r{ @: Z G @:key @: @:calc-get-user-defn@:} -@r{ @: Z I @: @: @:calc-user-define-invocation@:} -@r{ @: Z K @:key, command @: @:calc-user-define-kbd-macro@:} -@r{ @: Z P @:key @: @:calc-user-define-permanent@:} -@r{ @: Z S @: @: 30 @:calc-edit-user-syntax@:} -@r{ @: Z T @: @: 12 @:calc-timing@:} -@r{ @: Z U @:key @: @:calc-user-undefine@:} - -@end format - -@noindent -NOTES - -@enumerate -@c 1 -@item -Positive prefix arguments apply to @expr{n} stack entries. -Negative prefix arguments apply to the @expr{-n}th stack entry. -A prefix of zero applies to the entire stack. (For @key{LFD} and -@kbd{M-@key{DEL}}, the meaning of the sign is reversed.) - -@c 2 -@item -Positive prefix arguments apply to @expr{n} stack entries. -Negative prefix arguments apply to the top stack entry -and the next @expr{-n} stack entries. - -@c 3 -@item -Positive prefix arguments rotate top @expr{n} stack entries by one. -Negative prefix arguments rotate the entire stack by @expr{-n}. -A prefix of zero reverses the entire stack. - -@c 4 -@item -Prefix argument specifies a repeat count or distance. - -@c 5 -@item -Positive prefix arguments specify a precision @expr{p}. -Negative prefix arguments reduce the current precision by @expr{-p}. - -@c 6 -@item -A prefix argument is interpreted as an additional step-size parameter. -A plain @kbd{C-u} prefix means to prompt for the step size. - -@c 7 -@item -A prefix argument specifies simplification level and depth. -1=Default, 2=like @kbd{a s}, 3=like @kbd{a e}. - -@c 8 -@item -A negative prefix operates only on the top level of the input formula. - -@c 9 -@item -Positive prefix arguments specify a word size of @expr{w} bits, unsigned. -Negative prefix arguments specify a word size of @expr{w} bits, signed. - -@c 10 -@item -Prefix arguments specify the shift amount @expr{n}. The @expr{w} argument -cannot be specified in the keyboard version of this command. - -@c 11 -@item -From the keyboard, @expr{d} is omitted and defaults to zero. - -@c 12 -@item -Mode is toggled; a positive prefix always sets the mode, and a negative -prefix always clears the mode. - -@c 13 -@item -Some prefix argument values provide special variations of the mode. - -@c 14 -@item -A prefix argument, if any, is used for @expr{m} instead of taking -@expr{m} from the stack. @expr{M} may take any of these values: -@iftex -{@advance@tableindent10pt -@end iftex -@table @asis -@item Integer -Random integer in the interval @expr{[0 .. m)}. -@item Float -Random floating-point number in the interval @expr{[0 .. m)}. -@item 0.0 -Gaussian with mean 1 and standard deviation 0. -@item Error form -Gaussian with specified mean and standard deviation. -@item Interval -Random integer or floating-point number in that interval. -@item Vector -Random element from the vector. -@end table -@iftex -} -@end iftex - -@c 15 -@item -A prefix argument from 1 to 6 specifies number of date components -to remove from the stack. @xref{Date Conversions}. - -@c 16 -@item -A prefix argument specifies a time zone; @kbd{C-u} says to take the -time zone number or name from the top of the stack. @xref{Time Zones}. - -@c 17 -@item -A prefix argument specifies a day number (0-6, 0-31, or 0-366). - -@c 18 -@item -If the input has no units, you will be prompted for both the old and -the new units. - -@c 19 -@item -With a prefix argument, collect that many stack entries to form the -input data set. Each entry may be a single value or a vector of values. - -@c 20 -@item -With a prefix argument of 1, take a single -@texline @var{n}@math{\times2} -@infoline @mathit{@var{N}x2} -matrix from the stack instead of two separate data vectors. - -@c 21 -@item -The row or column number @expr{n} may be given as a numeric prefix -argument instead. A plain @kbd{C-u} prefix says to take @expr{n} -from the top of the stack. If @expr{n} is a vector or interval, -a subvector/submatrix of the input is created. - -@c 22 -@item -The @expr{op} prompt can be answered with the key sequence for the -desired function, or with @kbd{x} or @kbd{z} followed by a function name, -or with @kbd{$} to take a formula from the top of the stack, or with -@kbd{'} and a typed formula. In the last two cases, the formula may -be a nameless function like @samp{<#1+#2>} or @samp{}, or it -may include @kbd{$}, @kbd{$$}, etc. (where @kbd{$} will correspond to the -last argument of the created function), or otherwise you will be -prompted for an argument list. The number of vectors popped from the -stack by @kbd{V M} depends on the number of arguments of the function. - -@c 23 -@item -One of the mapping direction keys @kbd{_} (horizontal, i.e., map -by rows or reduce across), @kbd{:} (vertical, i.e., map by columns or -reduce down), or @kbd{=} (map or reduce by rows) may be used before -entering @expr{op}; these modify the function name by adding the letter -@code{r} for ``rows,'' @code{c} for ``columns,'' @code{a} for ``across,'' -or @code{d} for ``down.'' - -@c 24 -@item -The prefix argument specifies a packing mode. A nonnegative mode -is the number of items (for @kbd{v p}) or the number of levels -(for @kbd{v u}). A negative mode is as described below. With no -prefix argument, the mode is taken from the top of the stack and -may be an integer or a vector of integers. -@iftex -{@advance@tableindent-20pt -@end iftex -@table @cite -@item -1 -(@var{2}) Rectangular complex number. -@item -2 -(@var{2}) Polar complex number. -@item -3 -(@var{3}) HMS form. -@item -4 -(@var{2}) Error form. -@item -5 -(@var{2}) Modulo form. -@item -6 -(@var{2}) Closed interval. -@item -7 -(@var{2}) Closed .. open interval. -@item -8 -(@var{2}) Open .. closed interval. -@item -9 -(@var{2}) Open interval. -@item -10 -(@var{2}) Fraction. -@item -11 -(@var{2}) Float with integer mantissa. -@item -12 -(@var{2}) Float with mantissa in @expr{[1 .. 10)}. -@item -13 -(@var{1}) Date form (using date numbers). -@item -14 -(@var{3}) Date form (using year, month, day). -@item -15 -(@var{6}) Date form (using year, month, day, hour, minute, second). -@end table -@iftex -} -@end iftex - -@c 25 -@item -A prefix argument specifies the size @expr{n} of the matrix. With no -prefix argument, @expr{n} is omitted and the size is inferred from -the input vector. - -@c 26 -@item -The prefix argument specifies the starting position @expr{n} (default 1). - -@c 27 -@item -Cursor position within stack buffer affects this command. - -@c 28 -@item -Arguments are not actually removed from the stack by this command. - -@c 29 -@item -Variable name may be a single digit or a full name. - -@c 30 -@item -Editing occurs in a separate buffer. Press @kbd{C-c C-c} (or -@key{LFD}, or in some cases @key{RET}) to finish the edit, or kill the -buffer with @kbd{C-x k} to cancel the edit. The @key{LFD} key prevents evaluation -of the result of the edit. - -@c 31 -@item -The number prompted for can also be provided as a prefix argument. - -@c 32 -@item -Press this key a second time to cancel the prefix. - -@c 33 -@item -With a negative prefix, deactivate all formulas. With a positive -prefix, deactivate and then reactivate from scratch. - -@c 34 -@item -Default is to scan for nearest formula delimiter symbols. With a -prefix of zero, formula is delimited by mark and point. With a -non-zero prefix, formula is delimited by scanning forward or -backward by that many lines. - -@c 35 -@item -Parse the region between point and mark as a vector. A nonzero prefix -parses @var{n} lines before or after point as a vector. A zero prefix -parses the current line as a vector. A @kbd{C-u} prefix parses the -region between point and mark as a single formula. - -@c 36 -@item -Parse the rectangle defined by point and mark as a matrix. A positive -prefix @var{n} divides the rectangle into columns of width @var{n}. -A zero or @kbd{C-u} prefix parses each line as one formula. A negative -prefix suppresses special treatment of bracketed portions of a line. - -@c 37 -@item -A numeric prefix causes the current language mode to be ignored. - -@c 38 -@item -Responding to a prompt with a blank line answers that and all -later prompts by popping additional stack entries. - -@c 39 -@item -Answer for @expr{v} may also be of the form @expr{v = v_0} or -@expr{v - v_0}. - -@c 40 -@item -With a positive prefix argument, stack contains many @expr{y}'s and one -common @expr{x}. With a zero prefix, stack contains a vector of -@expr{y}s and a common @expr{x}. With a negative prefix, stack -contains many @expr{[x,y]} vectors. (For 3D plots, substitute -@expr{z} for @expr{y} and @expr{x,y} for @expr{x}.) - -@c 41 -@item -With any prefix argument, all curves in the graph are deleted. - -@c 42 -@item -With a positive prefix, refines an existing plot with more data points. -With a negative prefix, forces recomputation of the plot data. - -@c 43 -@item -With any prefix argument, set the default value instead of the -value for this graph. - -@c 44 -@item -With a negative prefix argument, set the value for the printer. - -@c 45 -@item -Condition is considered ``true'' if it is a nonzero real or complex -number, or a formula whose value is known to be nonzero; it is ``false'' -otherwise. - -@c 46 -@item -Several formulas separated by commas are pushed as multiple stack -entries. Trailing @kbd{)}, @kbd{]}, @kbd{@}}, @kbd{>}, and @kbd{"} -delimiters may be omitted. The notation @kbd{$$$} refers to the value -in stack level three, and causes the formula to replace the top three -stack levels. The notation @kbd{$3} refers to stack level three without -causing that value to be removed from the stack. Use @key{LFD} in place -of @key{RET} to prevent evaluation; use @kbd{M-=} in place of @key{RET} -to evaluate variables. - -@c 47 -@item -The variable is replaced by the formula shown on the right. The -Inverse flag reverses the order of the operands, e.g., @kbd{I s - x} -assigns -@texline @math{x \coloneq a-x}. -@infoline @expr{x := a-x}. - -@c 48 -@item -Press @kbd{?} repeatedly to see how to choose a model. Answer the -variables prompt with @expr{iv} or @expr{iv;pv} to specify -independent and parameter variables. A positive prefix argument -takes @mathit{@var{n}+1} vectors from the stack; a zero prefix takes a matrix -and a vector from the stack. - -@c 49 -@item -With a plain @kbd{C-u} prefix, replace the current region of the -destination buffer with the yanked text instead of inserting. - -@c 50 -@item -All stack entries are reformatted; the @kbd{H} prefix inhibits this. -The @kbd{I} prefix sets the mode temporarily, redraws the top stack -entry, then restores the original setting of the mode. - -@c 51 -@item -A negative prefix sets the default 3D resolution instead of the -default 2D resolution. - -@c 52 -@item -This grabs a vector of the form [@var{prec}, @var{wsize}, @var{ssize}, -@var{radix}, @var{flfmt}, @var{ang}, @var{frac}, @var{symb}, @var{polar}, -@var{matrix}, @var{simp}, @var{inf}]. A prefix argument from 1 to 12 -grabs the @var{n}th mode value only. -@end enumerate - -@iftex -(Space is provided below for you to keep your own written notes.) -@page -@endgroup -@end iftex - - -@c [end-summary] - -@node Key Index, Command Index, Summary, Top -@unnumbered Index of Key Sequences - -@printindex ky - -@node Command Index, Function Index, Key Index, Top -@unnumbered Index of Calculator Commands - -Since all Calculator commands begin with the prefix @samp{calc-}, the -@kbd{x} key has been provided as a variant of @kbd{M-x} which automatically -types @samp{calc-} for you. Thus, @kbd{x last-args} is short for -@kbd{M-x calc-last-args}. - -@printindex pg - -@node Function Index, Concept Index, Command Index, Top -@unnumbered Index of Algebraic Functions - -This is a list of built-in functions and operators usable in algebraic -expressions. Their full Lisp names are derived by adding the prefix -@samp{calcFunc-}, as in @code{calcFunc-sqrt}. -@iftex -All functions except those noted with ``*'' have corresponding -Calc keystrokes and can also be found in the Calc Summary. -@end iftex - -@printindex tp - -@node Concept Index, Variable Index, Function Index, Top -@unnumbered Concept Index - -@printindex cp - -@node Variable Index, Lisp Function Index, Concept Index, Top -@unnumbered Index of Variables - -The variables in this list that do not contain dashes are accessible -as Calc variables. Add a @samp{var-} prefix to get the name of the -corresponding Lisp variable. - -The remaining variables are Lisp variables suitable for @code{setq}ing -in your Calc init file or @file{.emacs} file. - -@printindex vr - -@node Lisp Function Index, , Variable Index, Top -@unnumbered Index of Lisp Math Functions - -The following functions are meant to be used with @code{defmath}, not -@code{defun} definitions. For names that do not start with @samp{calc-}, -the corresponding full Lisp name is derived by adding a prefix of -@samp{math-}. - -@printindex fn - -@bye diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi deleted file mode 100644 index 8c574be8f2a..00000000000 --- a/doc/misc/cc-mode.texi +++ /dev/null @@ -1,7246 +0,0 @@ -\input texinfo -@c Notes to self regarding line handling: -@c -@c Empty lines are often significant before @end directives; avoid them. -@c -@c Empty lines before and after @example directives are significant in -@c info output but not in TeX. Empty lines inside @example directives -@c are significant. - -@c Conventions for formatting examples: -@c o If the example contains empty lines then put the surrounding empty -@c lines inside the @example directives. Put them outside otherwise. -@c o Use @group inside the example only if it shows indentation where -@c the relation between lines inside is relevant. -@c o Format line number columns like this: -@c 1: foo -@c 2: bar -@c ^ one space -@c ^^ two columns, right alignment -@c o Check line lengths in TeX output; they can typically be no longer -@c than 70 chars, 60 if the paragraph is indented. - -@comment TBD: Document the finer details of statement anchoring? - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment %**start of header (This is for running Texinfo on a region) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment How to make the various output formats: -@comment (Thanks to Robert Chassell for supplying this information.) -@comment Note that Texinfo 4.7 (or later) is needed. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@ignore -In each of the following pairs of commands, the first generates a -version with cross references pointing to the GNU Emacs manuals, -the second with them pointing to the XEmacs manuals. - ## Info output - makeinfo cc-mode.texi - makeinfo -DXEMACS cc-mode.texi - - ## DVI output - ## You may need to set up the environment variable TEXINPUTS so - ## that tex can find the file texinfo.tex - See the tex - ## manpage. - texi2dvi cc-mode.texi - texi2dvi -t "@set XEMACS " cc-mode.texi - - ## HTML output. (The --no-split parameter is optional) - makeinfo --html --no-split cc-mode.texi - makeinfo --html --no-split -DXEMACS cc-mode.texi - - ## Plain text output - makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ - --no-headers --output=cc-mode.txt cc-mode.texi - makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ - --no-headers --output=cc-mode.txt -DXEMACS cc-mode.texi - - ## DocBook output - makeinfo --docbook --no-split --paragraph-indent=0 \ - cc-mode.texi - makeinfo --docbook --no-split --paragraph-indent=0 \ - -DXEMACS cc-mode.texi - - ## XML output - makeinfo --xml --no-split --paragraph-indent=0 \ - cc-mode.texi - makeinfo --xml --no-split --paragraph-indent=0 \ - -DXEMACS cc-mode.texi - - #### (You must be in the same directory as the viewed file.) - - ## View DVI output - xdvi cc-mode.dvi & - - ## View HTML output - mozilla cc-mode.html -@end ignore - -@comment No overfull hbox marks in the dvi file. -@finalout - -@setfilename ../../info/ccmode -@settitle CC Mode Manual -@footnotestyle end - -@c The following four macros generate the filenames and titles of the -@c main (X)Emacs manual and the Elisp/Lispref manual. Leave the -@c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it -@c to generate an XEmacs version, e.g. with -@c "makeinfo -DXEMACS cc-mode.texi". -@ifset XEMACS -@macro emacsman -xemacs -@end macro -@macro emacsmantitle -XEmacs User's Manual -@end macro -@macro lispref -lispref -@end macro -@macro lispreftitle -XEmacs Lisp Reference Manual -@end macro -@end ifset - -@ifclear XEMACS -@macro emacsman -emacs -@end macro -@macro emacsmantitle -GNU Emacs Manual -@end macro -@macro lispref -elisp -@end macro -@macro lispreftitle -GNU Emacs Lisp Reference Manual -@end macro -@end ifclear - - -@macro ccmode -CC Mode -@end macro - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment @setchapternewpage odd !! we don't want blank pages !! -@comment %**end of header (This is for running Texinfo on a region) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment -@comment Texinfo manual for CC Mode -@comment Generated from the original README file by Krishna Padmasola -@comment -@comment -@comment Authors: -@comment Barry A. Warsaw -@comment Martin Stjernholm -@comment Alan Mackenzie -@comment -@comment Maintained by Martin Stjernholm and Alan Mackenzie -@comment -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@comment Define an index for syntactic symbols. -@defindex ss - -@comment Combine key, syntactic symbol and concept indices into one. -@syncodeindex ss cp -@syncodeindex ky cp - -@copying -This manual is for CC Mode in Emacs. - -Copyright @copyright{} 1995-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@comment Info directory entry for use by install-info. The indentation -@comment here is by request from the FSF folks. -@dircategory Emacs editing modes -@direntry -* CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C, - Java, Pike, AWK, and CORBA IDL code. -@end direntry - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment TeX title page -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@titlepage -@sp 10 - -@center @titlefont{CC Mode 5.32} -@sp 2 -@center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} -@sp 2 -@center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie - -@page -@vskip 0pt plus 1filll -@insertcopying - -This manual was generated from cc-mode.texi, which is distributed with Emacs, -or can be downloaded from @url{http://savannah.gnu.org/projects/emacs/}. -@end titlepage - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment The Top node contains the master menu for the Info file. -@comment This appears only in the Info file, not the printed manual. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@summarycontents -@contents - -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up - -@ifnottex -@top @ccmode{} - -@ccmode{} is a GNU Emacs mode for editing files containing C, C++, -Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike -and AWK code. It provides syntax-based indentation, font locking, and -has several handy commands and some minor modes to make the editing -easier. It does not provide tools to look up and navigate between -functions, classes etc - there are other packages for that. - -@insertcopying -@end ifnottex - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@menu -* Introduction:: -* Overview:: -* Getting Started:: -* Commands:: -* Font Locking:: -* Config Basics:: -* Custom Filling and Breaking:: -* Custom Auto-newlines:: -* Clean-ups:: -* Indentation Engine Basics:: -* Customizing Indentation:: -* Custom Macros:: -* Odds and Ends:: -* Sample .emacs File:: -* Performance Issues:: -* Limitations and Known Bugs:: -* FAQ:: -* Updating CC Mode:: -* Mailing Lists and Bug Reports:: -* GNU Free Documentation License:: -* Command and Function Index:: -* Variable Index:: -* Concept and Key Index:: - -@detailmenu - --- The Detailed Node Listing --- - -Commands - -* Indentation Commands:: -* Comment Commands:: -* Movement Commands:: -* Filling and Breaking:: -* Minor Modes:: -* Electric Keys:: -* Auto-newlines:: -* Hungry WS Deletion:: -* Subword Movement:: -* Other Commands:: - -Font Locking - -* Font Locking Preliminaries:: -* Faces:: -* Doc Comments:: -* AWK Mode Font Locking:: - -Configuration Basics - -* CC Hooks:: -* Style Variables:: -* Styles:: - -Styles - -* Built-in Styles:: -* Choosing a Style:: -* Adding Styles:: -* Guessing the Style:: -* File Styles:: - -Customizing Auto-newlines - -* Hanging Braces:: -* Hanging Colons:: -* Hanging Semicolons and Commas:: - -Hanging Braces - -* Custom Braces:: - -Indentation Engine Basics - -* Syntactic Analysis:: -* Syntactic Symbols:: -* Indentation Calculation:: - -Syntactic Symbols - -* Function Symbols:: -* Class Symbols:: -* Conditional Construct Symbols:: -* Switch Statement Symbols:: -* Brace List Symbols:: -* External Scope Symbols:: -* Paren List Symbols:: -* Literal Symbols:: -* Multiline Macro Symbols:: -* Objective-C Method Symbols:: -* Java Symbols:: -* Statement Block Symbols:: -* K&R Symbols:: - -Customizing Indentation - -* c-offsets-alist:: -* Interactive Customization:: -* Line-Up Functions:: -* Custom Line-Up:: -* Other Indentation:: - -Line-Up Functions - -* Brace/Paren Line-Up:: -* List Line-Up:: -* Operator Line-Up:: -* Comment Line-Up:: -* Misc Line-Up:: - -Customizing Macros - -* Macro Backslashes:: -* Macros with ;:: - -@end detailmenu -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Introduction, Overview, Top, Top -@comment node-name, next, previous, up -@chapter Introduction -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex BOCM -@cindex history -@cindex awk-mode.el -@cindex c-mode.el -@cindex c++-mode.el - -Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C, -C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and -CIDL), Pike and AWK code. This incarnation of the mode is descended -from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM -@t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been -maintaining since 1992, and @file{awk-mode.el}, a long neglected mode -in the (X)Emacs base. - -Late in 1997, Martin Stjernholm joined Barry on the @ccmode{} -Maintainers Team, and implemented the Pike support. In 2000 Martin -took over as the sole maintainer. In 2001 Alan Mackenzie joined the -team, implementing AWK support in version 5.30. @ccmode{} did not -originally contain the font lock support for its languages --- that -was added in version 5.30. - -This manual describes @ccmode{} -@comment The following line must appear on its own, so that the -version 5.32. -@comment Release.py script can update the version number automatically - -@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C, -Java, CORBA's Interface Definition Language, Pike@footnote{A C-like -scripting language with its roots in the LPC language used in some MUD -engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this -way, you can easily set up consistent font locking and coding styles for -use in editing all of these languages, although AWK is not yet as -uniformly integrated as the other languages. - -@findex c-mode -@findex c++-mode -@findex objc-mode -@findex java-mode -@findex idl-mode -@findex pike-mode -@findex awk-mode -Note that the name of this package is ``@ccmode{}'', but there is no top -level @code{cc-mode} entry point. All of the variables, commands, and -functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and -@code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, -@code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are -provided. This package is intended to be a replacement for -@file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}. - -A special word of thanks goes to Krishna Padmasola for his work in -converting the original @file{README} file to Texinfo format. I'd -also like to thank all the @ccmode{} victims who help enormously -during the early beta stages of @ccmode{}'s development. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Overview, Getting Started, Introduction, Top -@comment node-name, next, previous, up@cindex organization of the manual -@chapter Overview of the Manual -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@noindent -The manual starts with several introductory chapters (including this -one). - -@noindent -The next chunk of the manual describes the day to day @emph{use} of -@ccmode{} (as contrasted with how to customize it). - -@itemize @bullet -@item -The chapter ``Commands'' describes in detail how to use (nearly) all -of @ccmode{}'s features. There are extensive cross-references from -here to the corresponding sections later in the manual which tell you -how to customize these features. - -@item -``Font Locking'' describes how ``syntax highlighting'' is applied to -your buffers. It is mainly background information and can be skipped -over at a first reading. -@end itemize - -@noindent -The next chunk of the manual describes how to @emph{customize} -@ccmode{}. Typically, an overview of a topic is given at the chapter -level, then the sections and subsections describe the material in -increasing detail. - -@itemize @bullet -@item -The chapter ``Configuration Basics'' tells you @emph{how} to write -customizations - whether in hooks, in styles, in both, or in neither, -depending on your needs. It describes the @ccmode{} style system and -lists the standard styles that @ccmode{} supplies. - -@item -The next few chapters describe in detail how to customize the various -features of @ccmode{}. - -@item -Finally, there is a sample @file{.emacs} fragment, which might help you -in creating your own customization. -@end itemize - -@noindent -The manual ends with ``this and that'', things that don't fit cleanly -into any of the previous chunks. - -@itemize @bullet -@item -Two chapters discuss the performance of @ccmode{} and known -bugs/limitations. - -@item -The FAQ contains a list of common problems and questions. - -@item -The next two chapters tell you how to get in touch with the @ccmode{} -project - whether for updating @ccmode{} or submitting bug reports. -@end itemize - -@noindent -Finally, there are the customary indices. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Getting Started, Commands, Overview, Top -@comment node-name, next, previous, up -@chapter Getting Started -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If you got this version of @ccmode{} with Emacs or XEmacs, it should -work just fine right out of the box. Note however that you might not -have the latest @ccmode{} release and might want to upgrade your copy -(see below). - -You should probably start by skimming through the entire Commands chapter -(@pxref{Commands}) to get an overview of @ccmode{}'s capabilities. - -After trying out some commands, you may dislike some aspects of -@ccmode{}'s default configuration. Here is an outline of how to -change some of the settings that newcomers to @ccmode{} most often -want to change: - -@table @asis -@item c-basic-offset -This Lisp variable holds an integer, the number of columns @ccmode{} -indents nested code. To set this value to 6, customize -@code{c-basic-offset} or put this into your @file{.emacs}: - -@example -(setq c-basic-offset 6) -@end example - -@item The (indentation) style -The basic ``shape'' of indentation created by @ccmode{}---by default, -this is @code{gnu} style (except for Java and AWK buffers). A list of -the available styles and their descriptions can be found in -@ref{Built-in Styles}. A complete specification of the @ccmode{} -style system, including how to create your own style, can be found in -the chapter @ref{Styles}. To set your style to @code{linux}, either -customize @code{c-default-style} or put this into your @file{.emacs}: - -@example -(setq c-default-style '((java-mode . "java") - (awk-mode . "awk") - (other . "linux"))) -@end example - -@item Electric Indentation -Normally, when you type ``punctuation'' characters such as @samp{;} or -@samp{@{}, @ccmode{} instantly reindents the current line. This can -be disconcerting until you get used to it. To disable @dfn{electric -indentation} in the current buffer, type @kbd{C-c C-l}. Type the same -thing to enable it again. To have electric indentation disabled by -default, put the following into your @file{.emacs} file@footnote{There -is no ``easy customization'' facility for making this change.}: - -@example -(setq-default c-electric-flag nil) -@end example - -@noindent -Details of this and other similar ``Minor Modes'' appear in the -section @ref{Minor Modes}. - -@item Making the @key{RET} key indent the new line -The standard Emacs binding for @key{RET} just adds a new line. If you -want it to reindent the new line as well, rebind the key. Note that -the action of rebinding would fail if the pertinent keymap didn't yet -exist---we thus need to delay the action until after @ccmode{} has -been loaded. Put the following code into your @file{.emacs}: - -@example -(defun my-make-CR-do-indent () - (define-key c-mode-base-map "\C-m" 'c-context-line-break)) -(add-hook 'c-initialization-hook 'my-make-CR-do-indent) -@end example - -@noindent -This example demonstrates the use of a very powerful @ccmode{} (and -Emacs) facility, the hook. The use of @ccmode{}'s hooks is described -in @ref{CC Hooks}. -@end table - -All these settings should occur in your @file{.emacs} @emph{before} -any @ccmode{} buffers get loaded---in particular, before any call of -@code{desktop-read}. - -As you get to know the mode better, you may want to make more -ambitious changes to your configuration. For this, you should start -reading the chapter @ref{Config Basics}. - -If you are upgrading an existing @ccmode{} installation, please see -the @file{README} file for installation details. In particular, if -you are going to be editing AWK files, @file{README} describes how to -configure your (X)Emacs so that @ccmode{} will supersede the obsolete -@code{awk-mode.el} which might have been supplied with your (X)Emacs. -@ccmode{} might not work with older versions of Emacs or XEmacs. See -the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net} -for the latest information on Emacs version and package compatibility -(@pxref{Updating CC Mode}). - -@deffn Command c-version -@findex version (c-) -You can find out what version of @ccmode{} you are using by visiting a C -file and entering @kbd{M-x c-version RET}. You should see this message in -the echo area: - -@example -Using CC Mode version 5.XX -@end example - -@noindent -where @samp{XX} is the minor release number. -@end deffn - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Commands, Font Locking, Getting Started, Top -@comment node-name, next, previous, up -@chapter Commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This chapter specifies all of CC Mode's commands, and thus contains -nearly everything you need to know to @emph{use} @ccmode{} (as -contrasted with configuring it). @dfn{Commands} here means both -control key sequences and @dfn{electric keys}, these being characters -such as @samp{;} which, as well as inserting themselves into the -buffer, also do other things. - -You might well want to review -@ifset XEMACS -@ref{Lists,,,@emacsman{}, @emacsmantitle{}}, -@end ifset -@ifclear XEMACS -@ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}}, -@end ifclear -which describes commands for moving around brace and parenthesis -structures. - - -@menu -* Indentation Commands:: -* Comment Commands:: -* Movement Commands:: -* Filling and Breaking:: -* Minor Modes:: -* Electric Keys:: -* Auto-newlines:: -* Hungry WS Deletion:: -* Subword Movement:: -* Other Commands:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Commands, Comment Commands, Commands, Commands -@comment node-name, next, previous,up -@section Indentation Commands -@cindex indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The following commands reindent C constructs. Note that when you -change your coding style, either interactively or through some other -means, your file does @emph{not} automatically get reindented. You -will need to execute one of the following commands to see the effects -of your changes. - -@cindex GNU indent program -Also, variables like @code{c-hanging-*} and @code{c-cleanup-list} -(@pxref{Custom Auto-newlines}) only affect how on-the-fly code is -formatted. Changing the ``hanginess'' of a brace and then -reindenting, will not move the brace to a different line. For this, -you're better off getting an external program like GNU @code{indent}, -which will rearrange brace location, amongst other things. - -Preprocessor directives are handled as syntactic whitespace from other -code, i.e. they can be interspersed anywhere without affecting the -indentation of the surrounding code, just like comments. - -The code inside macro definitions is, by default, still analyzed -syntactically so that you get relative indentation there just as you'd -get if the same code was outside a macro. However, since there is no -hint about the syntactic context, i.e. whether the macro expands to an -expression, to some statements, or perhaps to whole functions, the -syntactic recognition can be wrong. @ccmode{} manages to figure it -out correctly most of the time, though. - -Some macros, when invoked, ''have their own semicolon''. To get the -next line indented correctly, rather than as a continuation line, -@xref{Macros with ;}. - -Reindenting large sections of code can take a long time. When -@ccmode{} reindents a region of code, it is essentially equivalent to -hitting @key{TAB} on every line of the region. - -These commands indent code: - -@table @asis -@item @kbd{@key{TAB}} (@code{c-indent-command}) -@kindex TAB -@findex c-indent-command -@findex indent-command (c-) -This command indents the current line. That is all you need to know -about it for normal use. - -@code{c-indent-command} does different things, depending on the -setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine -Basics}): - -@itemize @bullet -@item -When it's non-@code{nil} (which it normally is), the command indents -the line according to its syntactic context. With a prefix argument -(@kbd{C-u @key{TAB}}), it will re-indent the entire -expression@footnote{this is only useful for a line starting with a -comment opener or an opening brace, parenthesis, or string quote.} -that begins at the line's left margin. - -@item -When it's @code{nil}, the command indents the line by an extra -@code{c-basic-offset} columns. A prefix argument acts as a -multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1, -removing @code{c-basic-offset} columns from the indentation. -@end itemize - -The precise behavior is modified by several variables: With -@code{c-tab-always-indent}, you can make @key{TAB} insert whitespace -in some circumstances---@code{c-insert-tab-function} then defines -precisely what sort of ``whitespace'' this will be. Set the standard -Emacs variable @code{indent-tabs-mode} to @code{t} if you want real -@samp{tab} characters to be used in the indentation, to @code{nil} if -you want only spaces. @xref{Just Spaces,,,@emacsman{}, -@emacsmantitle{}}. - -@defopt c-tab-always-indent -@vindex tab-always-indent (c-) -@cindex literal -This variable modifies how @key{TAB} operates. -@itemize @bullet -@item -When it is @code{t} (the default), @key{TAB} simply indents the -current line. -@item -When it is @code{nil}, @key{TAB} (re)indents the line only if point is -to the left of the first non-whitespace character on the line. -Otherwise it inserts some whitespace (a tab or an equivalent number of -spaces - see below) at point. -@item -With some other value, the line is reindented. Additionally, if point -is within a string or comment, some whitespace is inserted. -@end itemize -@end defopt - -@defopt c-insert-tab-function -@vindex insert-tab-function (c-) -@findex tab-to-tab-stop -When ``some whitespace'' is inserted as described above, what actually -happens is that the function stored in @code{c-insert-tab-function} is -called. Normally, this is @code{insert-tab}, which inserts a real tab -character or the equivalent number of spaces (depending on -@code{indent-tabs-mode}). Some people, however, set -@code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get -hard tab stops when indenting. -@end defopt -@end table - -@noindent -The kind of indentation the next five commands do depends on the -setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine -Basics}): -@itemize @bullet -@item -when it is non-@code{nil} (the default), the commands indent lines -according to their syntactic context; -@item -when it is @code{nil}, they just indent each line the same amount as -the previous non-blank line. The commands that indent a region aren't -very useful in this case. -@end itemize - -@table @asis -@item @kbd{C-j} (@code{newline-and-indent}) -@kindex C-j -@findex newline-and-indent -Inserts a newline and indents the new blank line, ready to start -typing. This is a standard (X)Emacs command. - -@item @kbd{C-M-q} (@code{c-indent-exp}) -@kindex C-M-q -@findex c-indent-exp -@findex indent-exp (c-) -Indents an entire balanced brace or parenthesis expression. Note that -point must be on the opening brace or parenthesis of the expression -you want to indent. - -@item @kbd{C-c C-q} (@code{c-indent-defun}) -@kindex C-c C-q -@findex c-indent-defun -@findex indent-defun (c-) -Indents the entire top-level function, class or macro definition -encompassing point. It leaves point unchanged. This function can't be -used to reindent a nested brace construct, such as a nested class or -function, or a Java method. The top-level construct being reindented -must be complete, i.e. it must have both a beginning brace and an ending -brace. - -@item @kbd{C-M-\} (@code{indent-region}) -@kindex C-M-\ -@findex indent-region -Indents an arbitrary region of code. This is a standard Emacs command, -tailored for C code in a @ccmode{} buffer. Note, of course, that point -and mark must delineate the region you want to indent. - -@item @kbd{C-M-h} (@code{c-mark-function}) -@kindex C-M-h -@findex c-mark-function -@findex mark-function (c-) -While not strictly an indentation command, this is useful for marking -the current top-level function or class definition as the current -region. As with @code{c-indent-defun}, this command operates on -top-level constructs, and can't be used to mark say, a Java method. -@end table - -These variables are also useful when indenting code: - -@defopt indent-tabs-mode -This is a standard Emacs variable that controls how line indentation -is composed. When it's non-@code{nil}, tabs can be used in a line's -indentation, otherwise only spaces are used. -@end defopt - -@defopt c-progress-interval -@vindex progress-interval (c-) -When indenting large regions of code, this variable controls how often a -progress message is displayed. Set this variable to @code{nil} to -inhibit the progress messages, or set it to an integer which is how -often (in seconds) progress messages are to be displayed. -@end defopt - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Comment Commands, Movement Commands, Indentation Commands, Commands -@comment node-name, next, previous, up -@section Comment Commands -@cindex comments (insertion of) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@table @asis -@item @kbd{C-c C-c} (@code{comment-region}) -@kindex C-c C-c -@findex comment-region -This command comments out the lines that start in the region. With a -negative argument, it does the opposite - it deletes the comment -delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU -Emacs Manual}, for fuller details. @code{comment-region} isn't -actually part of @ccmode{} - it is given a @ccmode{} binding for -convenience. - -@item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.}) -@kindex M-; -@findex comment-dwim -@findex indent-for-comment -Insert a comment at the end of the current line, if none is there -already. Then reindent the comment according to @code{comment-column} -@ifclear XEMACS -(@pxref{Options for Comments,,, emacs, GNU Emacs Manual}) -@end ifclear -@ifset XEMACS -(@pxref{Comments,,, xemacs, XEmacs User's Manual}) -@end ifset -and the variables below. Finally, position the point after the -comment starter. @kbd{C-u M-;} kills any comment on the current line, -together with any whitespace before it. This is a standard Emacs -command, but @ccmode{} enhances it a bit with two variables: - -@defopt c-indent-comment-alist -@vindex indent-comment-alist (c-) -@vindex comment-column -This style variable allows you to vary the column that @kbd{M-;} puts -the comment at, depending on what sort of code is on the line, and -possibly the indentation of any similar comment on the preceding line. -It is an association list that maps different types of lines to -actions describing how they should be handled. If a certain line type -isn't present on the list then the line is indented to the column -specified by @code{comment-column}. - -See the documentation string for a full description of this -variable (use @kbd{C-h v c-indent-comment-alist}). -@end defopt - -@defopt c-indent-comments-syntactically-p -@vindex indent-comments-syntactically-p (c-) -Normally, when this style variable is @code{nil}, @kbd{M-;} will -indent comment-only lines according to @code{c-indent-comment-alist}, -just as it does with lines where other code precede the comments. -However, if you want it to act just like @key{TAB} for comment-only -lines you can get that by setting -@code{c-indent-comments-syntactically-p} to non-@code{nil}. - -If @code{c-indent-comments-syntactically-p} is non-@code{nil} then -@code{c-indent-comment-alist} won't be consulted at all for comment-only -lines. -@end defopt -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Movement Commands, Filling and Breaking, Comment Commands, Commands -@comment node-name, next, previous, up -@section Movement Commands -@cindex movement -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} contains some useful commands for moving around in C code. - -@table @asis -@item @kbd{C-M-a} (@code{c-beginning-of-defun}) -@itemx @kbd{C-M-e} (@code{c-end-of-defun}) -@findex c-beginning-of-defun -@findex c-end-of-defun -@vindex c-defun-tactic -@vindex defun-tactic (c-) - -Move to the beginning or end of the current or next function. Other -constructs (such as a structs or classes) which have a brace block -also count as ``functions'' here. To move over several functions, you -can give these commands a repeat count. - -The start of a function is at its header. The end of the function is -after its closing brace, or after the semicolon of a construct (such -as a @code{struct}) which doesn't end at the brace. These two -commands try to leave point at the beginning of a line near the actual -start or end of the function. This occasionally causes point not to -move at all. - -By default, these commands will recognize functions contained within a -@dfn{declaration scope} such as a C++ @code{class} or @code{namespace} -construct, should the point start inside it. If @ccmode fails to find -function beginnings or ends inside the current declaration scope, it -will search the enclosing scopes. If you want @ccmode to recognize -functions only at the top level@footnote{this was @ccmode{}'s -behavior prior to version 5.32.}, set @code{c-defun-tactic} to -@code{t}. - -These functions are analogous to the Emacs built-in commands -@code{beginning-of-defun} and @code{end-of-defun}, except they -eliminate the constraint that the top-level opening brace of the defun -must be in column zero. See @ref{Defuns,,,@emacsman{}, -@emacsmantitle{}}, for more information. - -@item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun}) -@itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun}) -@kindex C-M-a (AWK Mode) -@kindex C-M-e (AWK Mode) -@findex c-awk-beginning-of-defun -@findex awk-beginning-of-defun (c-) -@findex c-awk-end-of-defun -@findex awk-end-of-defun (c-) -Move to the beginning or end of the current or next AWK defun. These -commands can take prefix-arguments, their functionality being entirely -equivalent to @code{beginning-of-defun} and @code{end-of-defun}. - -AWK Mode @dfn{defuns} are either pattern/action pairs (either of which -might be implicit) or user defined functions. Having the @samp{@{} and -@samp{@}} (if there are any) in column zero, as is suggested for some -modes, is neither necessary nor helpful in AWK mode. - -@item @kbd{M-a} (@code{c-beginning-of-statement}) -@itemx @kbd{M-e} (@code{c-end-of-statement}) -@kindex M-a -@kindex M-e -@findex c-beginning-of-statement -@findex c-end-of-statement -@findex beginning-of-statement (c-) -@findex end-of-statement (c-) -Move to the beginning or end of the innermost C statement. If point -is already there, move to the next beginning or end of a statement, -even if that means moving into a block. (Use @kbd{C-M-b} or -@kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n} -means move over @var{n} statements. - -If point is within or next to a comment or a string which spans more -than one line, these commands move by sentences instead of statements. - -When called from a program, these functions take three optional -arguments: the repetition count, a buffer position limit which is the -farthest back to search for the syntactic context, and a flag saying -whether to do sentence motion in or near comments and multiline -strings. - -@item @kbd{C-c C-u} (@code{c-up-conditional}) -@kindex C-c C-u -@findex c-up-conditional -@findex up-conditional (c-) -Move back to the containing preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move forward to the end of the containing preprocessor -conditional. - -@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the -function stops at them when going backward, but not when going -forward. - -This key sequence is not bound in AWK Mode, which doesn't have -preprocessor statements. - -@item @kbd{M-x c-up-conditional-with-else} -@findex c-up-conditional-with-else -@findex up-conditional-with-else (c-) -A variety of @code{c-up-conditional} that also stops at @samp{#else} -lines. Normally those lines are ignored. - -@item @kbd{M-x c-down-conditional} -@findex c-down-conditional -@findex down-conditional (c-) -Move forward into the next nested preprocessor conditional, leaving -the mark behind. A prefix argument acts as a repeat count. With a -negative argument, move backward into the previous nested preprocessor -conditional. - -@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the -function stops at them when going forward, but not when going backward. - -@item @kbd{M-x c-down-conditional-with-else} -@findex c-down-conditional-with-else -@findex down-conditional-with-else (c-) -A variety of @code{c-down-conditional} that also stops at @samp{#else} -lines. Normally those lines are ignored. - -@item @kbd{C-c C-p} (@code{c-backward-conditional}) -@itemx @kbd{C-c C-n} (@code{c-forward-conditional}) -@kindex C-c C-p -@kindex C-c C-n -@findex c-backward-conditional -@findex c-forward-conditional -@findex backward-conditional (c-) -@findex forward-conditional (c-) -Move backward or forward across a preprocessor conditional, leaving -the mark behind. A prefix argument acts as a repeat count. With a -negative argument, move in the opposite direction. - -These key sequences are not bound in AWK Mode, which doesn't have -preprocessor statements. - -@item @kbd{M-x c-backward-into-nomenclature} -@itemx @kbd{M-x c-forward-into-nomenclature} -@findex c-backward-into-nomenclature -@findex c-forward-into-nomenclature -@findex backward-into-nomenclature (c-) -@findex forward-into-nomenclature (c-) -A popular programming style, especially for object-oriented languages -such as C++ is to write symbols in a mixed case format, where the -first letter of each word is capitalized, and not separated by -underscores. E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}. - -These commands move backward or forward to the beginning of the next -capitalized word. With prefix argument @var{n}, move @var{n} times. -If @var{n} is negative, move in the opposite direction. - -Note that these two commands have been superseded by -@code{subword-mode}, which you should use instead. @xref{Subword -Movement}. They might be removed from a future release of @ccmode{}. -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Filling and Breaking, Minor Modes, Movement Commands, Commands -@comment node-name, next, previous, up -@section Filling and Line Breaking Commands -@cindex text filling -@cindex line breaking -@cindex comment handling -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since there's a lot of normal text in comments and string literals, -@ccmode{} provides features to edit these like in text mode. The goal -is to do it seamlessly, i.e. you can use auto fill mode, sentence and -paragraph movement, paragraph filling, adaptive filling etc. wherever -there's a piece of normal text without having to think much about it. -@ccmode{} keeps the indentation, fixes suitable comment line prefixes, -and so on. - -You can configure the exact way comments get filled and broken, and -where Emacs does auto-filling (see @pxref{Custom Filling and -Breaking}). Typically, the style system (@pxref{Styles}) will have -set this up for you, so you probably won't have to bother. - -@findex auto-fill-mode -@cindex Auto Fill mode -@cindex paragraph filling -Line breaks are by default handled (almost) the same regardless of -whether they are made by auto fill mode (@pxref{Auto -Fill,,,@emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with -@kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In -string literals, the new line gets the same indentation as the -previous nonempty line.@footnote{You can change this default by -setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols} -and @pxref{Customizing Indentation})}. - -@table @asis -@item @kbd{M-q} (@code{c-fill-paragraph}) -@kindex M-q -@findex c-fill-paragraph -@findex fill-paragraph (c-) -@cindex Javadoc markup -@cindex Pike autodoc markup -This command fills multiline string literals and both block -and line style comments. In Java buffers, the Javadoc markup words -are recognized as paragraph starters. The line oriented Pike autodoc -markup words are recognized in the same way in Pike mode. - -The formatting of the starters (@code{/*}) and enders (@code{*/}) of -block comments are kept as they were before the filling. I.e., if -either the starter or ender were on a line of its own, then it stays -on its own line; conversely, if the delimiter has comment text on its -line, it keeps at least one word of that text with it on the line. - -This command is the replacement for @code{fill-paragraph} in @ccmode{} -buffers. - -@item @kbd{M-j} (@code{c-indent-new-comment-line}) -@kindex M-j -@findex c-indent-new-comment-line -@findex indent-new-comment-line (c-) -This breaks the current line at point and indents the new line. If -point was in a comment, the new line gets the proper comment line -prefix. If point was inside a macro, a backslash is inserted before -the line break. It is the replacement for -@code{indent-new-comment-line}. - -@item @kbd{M-x c-context-line-break} -@findex c-context-line-break -@findex context-line-break (c-) -Insert a line break suitable to the context: If the point is inside a -comment, the new line gets the suitable indentation and comment line -prefix like @code{c-indent-new-comment-line}. In normal code it's -indented like @code{newline-and-indent} would do. In macros it acts -like @code{newline-and-indent} but additionally inserts and optionally -aligns the line ending backslash so that the macro remains unbroken. -@xref{Custom Macros}, for details about the backslash alignment. In a -string, a backslash is inserted only if the string is within a -macro@footnote{In GCC, unescaped line breaks within strings are -valid.}. - -This function is not bound to a key by default, but it's intended to be -used on the @kbd{RET} key. If you like the behavior of -@code{newline-and-indent} on @kbd{RET}, you should consider switching to -this function. @xref{Sample .emacs File}. - -@item @kbd{M-x c-context-open-line} -@findex c-context-open-line -@findex context-open-line (c-) -This is to @kbd{C-o} (@kbd{M-x open-line}) as -@code{c-context-line-break} is to @kbd{RET}. I.e. it works just like -@code{c-context-line-break} but leaves the point before the inserted -line break. -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Minor Modes, Electric Keys, Filling and Breaking, Commands -@comment node-name, next, previous, up -@section Minor Modes -@cindex Minor Modes -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} contains several minor-mode-like features that you might -find useful while writing new code or editing old code: - -@table @asis -@item electric mode -When this is enabled, certain visible characters cause reformatting as -they are typed. This is normally helpful, but can be a nuisance when -editing chaotically formatted code. It can also be disconcerting, -especially for users who are new to @ccmode{}. -@item auto-newline mode -This automatically inserts newlines where you'd probably want to type -them yourself, e.g. after typing @samp{@}}s. Its action is suppressed -when electric mode is disabled. -@item hungry-delete mode -This lets you delete a contiguous block of whitespace with a single -key - for example, the newline and indentation just inserted by -auto-newline when you want to back up and write a comment after the -last statement. -@item subword mode -This mode makes basic word movement commands like @kbd{M-f} -(@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the -parts of sillycapsed symbols as different words. -E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS}, -@samp{Graphics}, and @samp{Context}. -@item syntactic-indentation mode -When this is enabled (which it normally is), indentation commands such -as @kbd{C-j} indent lines of code according to their syntactic -structure. Otherwise, a line is simply indented to the same level as -the previous one and @kbd{@key{TAB}} adjusts the indentation in steps -of `c-basic-offset'. -@end table - -Full details on how these minor modes work are at @ref{Electric Keys}, -@ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement}, -and @ref{Indentation Engine Basics}. - -You can toggle each of these minor modes on and off, and you can -configure @ccmode{} so that it starts up with your favorite -combination of them (@pxref{Sample .emacs File}). By default, when -you initialize a buffer, electric mode and syntactic-indentation mode -are enabled but the other two modes are disabled. - -@ccmode{} displays the current state of the first four of these minor -modes on the modeline by appending letters to the major mode's name, -one letter for each enabled minor mode - @samp{l} for electric mode, -@samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and -@samp{w} for subword mode. If all these modes were enabled, you'd see -@samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of -the language in question for the other languages @ccmode{} supports.}. - -Here are the commands to toggle these modes: - -@table @asis -@item @kbd{C-c C-l} (@code{c-toggle-electric-state}) -@kindex C-c C-l -@findex c-toggle-electric-state -@findex toggle-electric-state (c-) -Toggle electric minor mode. When the command turns the mode off, it -also suppresses auto-newline mode. - -@item @kbd{C-c C-a} (@code{c-toggle-auto-newline}) -@kindex C-c C-a -@findex c-toggle-auto-newline -@findex toggle-auto-newline (c-) -Toggle auto-newline minor mode. When the command turns the mode on, -it also enables electric minor mode. - -@item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.} -@findex c-toggle-hungry-state -@findex toggle-hungry-state (c-) -Toggle hungry-delete minor mode. - -@item @kbd{M-x c-toggle-auto-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-t}.} -@findex c-toggle-auto-hungry-state -@findex toggle-auto-hungry-state (c-) -Toggle both auto-newline and hungry delete minor modes. - -@item @kbd{C-c C-w} (@code{M-x subword-mode}) -@kindex C-c C-w -@findex subword-mode -Toggle subword mode. - -@item @kbd{M-x c-toggle-syntactic-indentation} -@findex c-toggle-syntactic-indentation -@findex toggle-syntactic-indentation (c-) -Toggle syntactic-indentation mode. -@end table - -Common to all the toggle functions above is that if they are called -programmatically, they take an optional numerical argument. A -positive value will turn on the minor mode (or both of them in the -case of @code{c-toggle-auto-hungry-state}) and a negative value will -turn it (or them) off. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Electric Keys, Auto-newlines, Minor Modes, Commands -@comment node-name, next, previous, up -@section Electric Keys and Keywords -@cindex electric characters -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Most punctuation keys provide @dfn{electric} behavior - as well as -inserting themselves they perform some other action, such as -reindenting the line. This reindentation saves you from having to -reindent a line manually after typing, say, a @samp{@}}. A few -keywords, such as @code{else}, also trigger electric action. - -You can inhibit the electric behavior described here by disabling -electric minor mode (@pxref{Minor Modes}). - -Common to all these keys is that they only behave electrically when -used in normal code (as contrasted with getting typed in a string -literal or comment). Those which cause re-indentation do so only when -@code{c-syntactic-indentation} has a non-@code{nil} value (which it -does by default). - -These keys and keywords are: -@c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more -@c like a bug in the code than a bug in this document. It'll get -@c fixed in the code sometime. - -@table @kbd -@item # -@kindex # -@findex c-electric-pound -@findex electric-pound (c-) -@vindex c-electric-pound-behavior -@vindex electric-pound-behavior (c-) -Pound (bound to @code{c-electric-pound}) is electric when typed as the -first non-whitespace character on a line and not within a macro -definition. In this case, the variable @code{c-electric-pound-behavior} -is consulted for the electric behavior. This variable takes a list -value, although the only element currently defined is @code{alignleft}, -which tells this command to force the @samp{#} character into column -zero. This is useful for entering preprocessor macro definitions. - -Pound is not electric in AWK buffers, where @samp{#} starts a comment, -and is bound to @code{self-insert-command} like any typical printable -character. -@c ACM, 2004/8/24: Change this (and the code) to do AWK comment -@c reindentation. - -@item * -@kindex * -@itemx / -@kindex / -@findex c-electric-star -@findex electric-star (c-) -@findex c-electric-slash -@findex electric-slash (c-) -A star (bound to @code{c-electric-star}) or a slash -(@code{c-electric-slash}) causes reindentation when you type it as the -second component of a C style block comment opener (@samp{/*}) or a -C++ line comment opener (@samp{//}) respectively, but only if the -comment opener is the first thing on the line (i.e. there's only -whitespace before it). - -Additionally, you can configure @ccmode{} so that typing a slash at -the start of a line within a block comment will terminate the -comment. You don't need to have electric minor mode enabled to get -this behavior. @xref{Clean-ups}. - -In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not -electric. - -@item < -@kindex < -@itemx > -@kindex > -@findex c-electric-lt-gt -@findex electric-lt-gt (c-) -A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is -electric in two circumstances: when it is an angle bracket in a C++ -@samp{template} declaration (and similar constructs in other -languages) and when it is the second of two @kbd{<} or @kbd{>} -characters in a C++ style stream operator. In either case, the line -is reindented. Angle brackets in C @samp{#include} directives are not -electric. - -@item ( -@kindex ( -@itemx ) -@kindex ) -@findex c-electric-paren -@findex electric-paren (c-) -The normal parenthesis characters @samp{(} and @samp{)} (bound to -@code{c-electric-paren}) reindent the current line. This is useful -for getting the closing parenthesis of an argument list aligned -automatically. - -You can also configure @ccmode{} to insert a space automatically -between a function name and the @samp{(} you've just typed, and to -remove it automatically after typing @samp{)}, should the argument -list be empty. You don't need to have electric minor mode enabled to -get these actions. @xref{Clean-ups}. - -@item @{ -@kindex @{ -@itemx @} -@kindex @} -@findex c-electric-brace -@findex electric-brace (c-) -Typing a brace (bound to @code{c-electric-brace}) reindents the -current line. Also, one or more newlines might be inserted if -auto-newline minor mode is enabled. @xref{Auto-newlines}. -Additionally, you can configure @ccmode{} to compact excess whitespace -inserted by auto-newline mode in certain circumstances. -@xref{Clean-ups}. - -@item : -@kindex : -@findex c-electric-colon -@findex electric-colon (c-) -Typing a colon (bound to @code{c-electric-colon}) reindents the -current line. Additionally, one or more newlines might be inserted if -auto-newline minor mode is enabled. @xref{Auto-newlines}. If you -type a second colon immediately after such an auto-newline, by default -the whitespace between the two colons is removed, leaving a C++ scope -operator. @xref{Clean-ups}. - -If you prefer, you can insert @samp{::} in a single operation, -avoiding all these spurious reindentations, newlines, and clean-ups. -@xref{Other Commands}. - -@item ; -@kindex ; -@itemx , -@kindex , -@findex c-electric-semi&comma -@findex electric-semi&comma (c-) -Typing a semicolon or comma (bound to @code{c-electric-semi&comma}) -reindents the current line. Also, a newline might be inserted if -auto-newline minor mode is enabled. @xref{Auto-newlines}. -Additionally, you can configure @ccmode{} so that when auto-newline -has inserted whitespace after a @samp{@}}, it will be removed again -when you type a semicolon or comma just after it. @xref{Clean-ups}. - -@end table - -@deffn Command c-electric-continued-statement -@findex electric-continued-statement (c-) - -Certain keywords are electric, causing reindentation when they are -preceded only by whitespace on the line. The keywords are those that -continue an earlier statement instead of starting a new one: -@code{else}, @code{while}, @code{catch} (only in C++ and Java) and -@code{finally} (only in Java). - -An example: - -@example -@group -for (i = 0; i < 17; i++) - if (a[i]) - res += a[i]->offset; -else -@end group -@end example - -Here, the @code{else} should be indented like the preceding @code{if}, -since it continues that statement. @ccmode{} will automatically -reindent it after the @code{else} has been typed in full, since only -then is it possible to decide whether it's a new statement or a -continuation of the preceding @code{if}. - -@vindex abbrev-mode -@findex abbrev-mode -@cindex Abbrev mode -@ccmode{} uses Abbrev mode (@pxref{Abbrevs,,,@emacsman{}, @emacsmantitle{}}) -to accomplish this. It's therefore turned on by default in all language -modes except IDL mode, since CORBA IDL doesn't have any statements. -@end deffn - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands -@comment node-name, next, previous, up -@section Auto-newline Insertion -@cindex auto-newline -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor -Modes}), @ccmode{} inserts newlines for you automatically (in certain -syntactic contexts) when you type a left or right brace, a colon, a -semicolon, or a comma. Sometimes a newline appears before the -character you type, sometimes after it, sometimes both. - -Auto-newline only triggers when the following conditions hold: - -@itemize @bullet -@item -Auto-newline minor mode is enabled, as evidenced by the indicator -@samp{a} after the mode name on the modeline (e.g. @samp{C/a} or -@samp{C/la}). - -@item -The character was typed at the end of a line, or with only whitespace -after it, and possibly a @samp{\} escaping the newline. - -@item -The character is not on its own line already. (This applies only to -insertion of a newline @emph{before} the character.) - -@item -@cindex literal -@cindex syntactic whitespace -The character was not typed inside of a literal @footnote{A -@dfn{literal} is defined as any comment, string, or preprocessor macro -definition. These constructs are also known as @dfn{syntactic -whitespace} since they are usually ignored when scanning C code.}. - -@item -No numeric argument was supplied to the command (i.e. it was typed as -normal, with no @kbd{C-u} prefix). -@end itemize - -You can configure the precise circumstances in which newlines get -inserted (see @pxref{Custom Auto-newlines}). Typically, the style -system (@pxref{Styles}) will have set this up for you, so you probably -won't have to bother. - -Sometimes @ccmode{} inserts an auto-newline where you don't want one, -such as after a @samp{@}} when you're about to type a @samp{;}. -Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can -activate an appropriate @dfn{clean-up}, which will remove the excess -whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a -full description. See also @ref{Electric Keys} for a summary of -clean-ups listed by key. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands -@comment node-name, next, previous, up -@section Hungry Deletion of Whitespace -@cindex hungry-deletion -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If you want to delete an entire block of whitespace at point, you can -use @dfn{hungry deletion}. This deletes all the contiguous whitespace -either before point or after point in a single operation. -``Whitespace'' here includes tabs and newlines, but not comments or -preprocessor commands. Hungry deletion can markedly cut down on the -number of times you have to hit deletion keys when, for example, -you've made a mistake on the preceding line and have already pressed -@kbd{C-j}. - -Hungry deletion is a simple feature that some people find extremely -useful. In fact, you might find yourself wanting it in @strong{all} -your editing modes! - -Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the -backspace key'' and @dfn{@key{DELETE}} means ``the forward delete -key''. This is discussed in more detail below. - -There are two different ways you can use hungry deletion: - -@table @asis -@item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d} -Here you toggle Hungry Delete minor mode with @kbd{M-x -c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command -was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding -for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This -makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry -deletion. - -@table @asis -@item @kbd{@key{DEL}} (@code{c-electric-backspace}) -@kindex DEL -@findex c-electric-backspace -@findex electric-backspace (c-) -This command is run by default when you hit the @kbd{DEL} key. When -hungry delete mode is enabled, it deletes any amount of whitespace in -the backwards direction. Otherwise, or when used with a prefix -argument or in a literal (@pxref{Auto-newlines}), the command just -deletes backwards in the usual way. (More precisely, it calls the -function contained in the variable @code{c-backspace-function}, -passing it the prefix argument, if any.) - -@item @code{c-backspace-function} -@vindex c-backspace-function -@vindex backspace-function (c-) -@findex backward-delete-char-untabify -Hook that gets called by @code{c-electric-backspace} when it doesn't -do an ``electric'' deletion of the preceding whitespace. The default -value is @code{backward-delete-char-untabify} -(@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which -deletes a single character. - -@item @kbd{C-d} (@code{c-electric-delete-forward}) -@kindex C-d -@findex c-electric-delete-forward -@findex electric-delete-forward (c-) -This function, which is bound to @kbd{C-d} by default, works just like -@code{c-electric-backspace} but in the forward direction. When it -doesn't do an ``electric'' deletion of the following whitespace, it -just does @code{delete-char}, more or less. (Strictly speaking, it -calls the function in @code{c-delete-function} with the prefix -argument.) - -@item @code{c-delete-function} -@vindex c-delete-function -@vindex delete-function (c-) -@findex delete-char -Hook that gets called by @code{c-electric-delete-forward} when it -doesn't do an ``electric'' deletion of the following whitespace. The -default value is @code{delete-char}. -@end table - -@item Using Distinct Bindings -The other (newer and recommended) way to use hungry deletion is to -perform @code{c-hungry-delete-backwards} and -@code{c-hungry-delete-forward} directly through their key sequences -rather than using the minor mode toggling. - -@table @asis -@item @kbd{C-c C-@key{DEL}}, or @kbd{C-c @key{DEL}} (@code{c-hungry-delete-backwards})@footnote{This command was formerly known as @code{c-hungry-backspace}.} -@kindex C-c C- -@kindex C-c -@kindex C-c C-DEL -@kindex C-c DEL -@findex c-hungry-delete-backwards -@findex hungry-delete-backwards (c-) -Delete any amount of whitespace in the backwards direction (regardless -whether hungry-delete mode is enabled or not). This command is bound -to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more -natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at -a character terminal. - -@item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward}) -@kindex C-c C-d -@kindex C-c C- -@kindex C-c -@findex c-hungry-delete-forward -@findex hungry-delete-forward (c-) -Delete any amount of whitespace in the forward direction (regardless -whether hungry-delete mode is enabled or not). This command is bound -to both @kbd{C-c C-@key{DELETE}} and @kbd{C-c @key{DELETE}} for the -same reason as for @key{DEL} above. -@end table -@end table - -@kindex -@kindex - -When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we -actually do so without connecting them to the physical keys commonly -known as @key{Backspace} and @key{Delete}. The default bindings to -those two keys depends on the flavor of (X)Emacs you are using. - -@findex c-electric-delete -@findex electric-delete (c-) -@findex c-hungry-delete -@findex hungry-delete (c-) -@vindex delete-key-deletes-forward -In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to -@code{c-electric-backspace} and the @key{Delete} key is bound to -@code{c-electric-delete}. You control the direction it deletes in by -setting the variable @code{delete-key-deletes-forward}, a standard -XEmacs variable. -@c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...). -When this variable is non-@code{nil}, @code{c-electric-delete} will do -forward deletion with @code{c-electric-delete-forward}, otherwise it -does backward deletion with @code{c-electric-backspace}. Similarly, -@kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to -@code{c-hungry-delete} which is controlled in the same way by -@code{delete-key-deletes-forward}. - -@findex normal-erase-is-backspace-mode - -Emacs 21 and later automatically binds @key{Backspace} and -@key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment, -and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}} -etc. If you need to change the bindings through -@code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt -its extended bindings accordingly. - -In earlier (X)Emacs versions, @ccmode{} doesn't bind either -@key{Backspace} or @key{Delete} directly. Only the key codes -@kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings -to map the physical keys to them. You might need to modify this -yourself if the defaults are unsuitable. - -Getting your @key{Backspace} and @key{Delete} keys properly set up can -sometimes be tricky. The information in @ref{DEL Does Not -Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having -trouble with this in GNU Emacs. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Subword Movement, Other Commands, Hungry WS Deletion, Commands -@comment node-name, next, previous, up -@section Subword Movement and Editing -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex nomenclature -@cindex subword -In spite of the GNU Coding Standards, it is popular to name a symbol -by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget}, -@samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call -these mixed case symbols @dfn{nomenclatures}. Also, each capitalized -(or completely uppercase) part of a nomenclature is called a -@dfn{subword}. Here are some examples: - -@multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}} -@c This could be converted to @headitem when we require Texinfo 4.7 -@iftex -@item @b{Nomenclature} - @tab @b{Subwords} -@end iftex -@ifnottex -@item Nomenclature - @tab Subwords -@item --------------------------------------------------------- -@end ifnottex -@item @samp{GtkWindow} - @tab @samp{Gtk} and @samp{Window} -@item @samp{EmacsFrameClass} - @tab @samp{Emacs}, @samp{Frame}, and @samp{Class} -@item @samp{NSGraphicsContext} - @tab @samp{NS}, @samp{Graphics}, and @samp{Context} -@end multitable - -The subword minor mode replaces the basic word oriented movement and -editing commands with variants that recognize subwords in a -nomenclature and treat them as separate words: - -@findex c-forward-subword -@findex forward-subword (c-) -@findex c-backward-subword -@findex backward-subword (c-) -@findex c-mark-subword -@findex mark-subword (c-) -@findex c-kill-subword -@findex kill-subword (c-) -@findex c-backward-kill-subword -@findex backward-kill-subword (c-) -@findex c-transpose-subwords -@findex transpose-subwords (c-) -@findex c-capitalize-subword -@findex capitalize-subword (c-) -@findex c-upcase-subword -@findex upcase-subword (c-) -@findex c-downcase-subword -@findex downcase-subword (c-) -@multitable @columnfractions .20 .40 .40 -@c This could be converted to @headitem when we require Texinfo 4.7 -@iftex -@item @b{Key} @tab @b{Word oriented command} @tab @b{Subword oriented command} -@end iftex -@ifnottex -@item Key @tab Word oriented command @tab Subword oriented command -@item ---------------------------------------------------------------------------- -@end ifnottex -@item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword} -@item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword} -@item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword} -@item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword} -@item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword} -@item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords} -@item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword} -@item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword} -@item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword} -@end multitable - -Note that if you have changed the key bindings for the word oriented -commands in your @file{.emacs} or a similar place, the keys you have -configured are also used for the corresponding subword oriented -commands. - -Type @kbd{C-c C-w} to toggle subword mode on and off. To make the -mode turn on automatically, put the following code in your -@file{.emacs}: - -@example -(add-hook 'c-mode-common-hook - (lambda () (subword-mode 1))) -@end example - -As a bonus, you can also use @code{subword-mode} in non-@ccmode{} -buffers by typing @kbd{M-x subword-mode}. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Other Commands, , Subword Movement, Commands -@comment node-name, next, previous, up -@section Other Commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here are the various other commands that didn't fit anywhere else: - -@table @asis -@item @kbd{C-c .} (@code{c-set-style}) -@kindex C-c . -@findex c-set-style -@findex set-style (c-) -Switch to the specified style in the current buffer. Use like this: - -@example -@kbd{C-c . @var{style-name} @key{RET}} -@end example - -You can use the @key{TAB} in the normal way to do completion on the -style name. Note that all style names are case insensitive, even the -ones you define yourself. - -Setting a style in this way does @emph{not} automatically reindent your -file. For commands that you can use to view the effect of your changes, -see @ref{Indentation Commands} and @ref{Filling and Breaking}. - -For details of the @ccmode{} style system, see @ref{Styles}. -@item @kbd{C-c :} (@code{c-scope-operator}) -@kindex C-c : -@findex c-scope-operator -@findex scope-operator (c-) -In C++, it is also sometimes desirable to insert the double-colon scope -operator without performing the electric behavior of colon insertion. -@kbd{C-c :} does just this. - -@item @kbd{C-c C-\} (@code{c-backslash-region}) -@kindex C-c C-\ -@findex c-backslash-region -@findex backslash-region (c-) -This function inserts and aligns or deletes end-of-line backslashes in -the current region. These are typically used in multi-line macros. - -With no prefix argument, it inserts any missing backslashes and aligns -them according to the @code{c-backslash-column} and -@code{c-backslash-max-column} variables. With a prefix argument, it -deletes any backslashes. - -The function does not modify blank lines at the start of the region. If -the region ends at the start of a line, it always deletes the backslash -(if any) at the end of the previous line. - -To customize the precise workings of this command, @ref{Custom Macros}. -@end table - -@noindent -The recommended line breaking function, @code{c-context-line-break} -(@pxref{Filling and Breaking}), is especially nice if you edit -multiline macros frequently. When used inside a macro, it -automatically inserts and adjusts the mandatory backslash at the end -of the line to keep the macro together, and it leaves the point at the -right indentation column for the code. Thus you can write code inside -macros almost exactly as you can elsewhere, without having to bother -with the trailing backslashes. - -@table @asis -@item @kbd{C-c C-e} (@code{c-macro-expand}) -@kindex C-c C-e -@findex c-macro-expand -@findex macro-expand (c-) -This command expands C, C++, Objective C or Pike macros in the region, -using an appropriate external preprocessor program. Normally it -displays its output in a temporary buffer, but if you give it a prefix -arg (with @kbd{C-u C-c C-e}) it will overwrite the original region -with the expansion. - -The command does not work in any of the other modes, and the key -sequence is not bound in these other modes. - -@code{c-macro-expand} isn't actually part of @ccmode{}, even though it -is bound to a @ccmode{} key sequence. If you need help setting it up -or have other problems with it, you can either read its source code or -ask for help in the standard (X)Emacs forums. -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Font Locking, Config Basics, Commands, Top -@comment node-name, next, previous, up -@chapter Font Locking -@cindex font locking -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex Font Lock mode - -@ccmode{} provides font locking for its supported languages by -supplying patterns for use with Font Lock mode. This means that you -get distinct faces on the various syntactic parts such as comments, -strings, keywords and types, which is very helpful in telling them -apart at a glance and discovering syntactic errors. @xref{Font -Lock,,, emacs, GNU Emacs Manual}, for ways to enable font locking in -@ccmode{} buffers. - -@strong{Please note:} The font locking in AWK mode is currently not -integrated with the rest of @ccmode{}. Only the last section of this -chapter, @ref{AWK Mode Font Locking}, applies to AWK. The other -sections apply to the other languages. - -@menu -* Font Locking Preliminaries:: -* Faces:: -* Doc Comments:: -* AWK Mode Font Locking:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Font Locking Preliminaries, Faces, Font Locking, Font Locking -@comment node-name, next, previous, up -@section Font Locking Preliminaries -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The font locking for most of the @ccmode{} languages were provided -directly by the Font Lock package prior to version 5.30 of @ccmode{}. -In the transition to @ccmode{} the patterns have been reworked -completely and are applied uniformly across all the languages except AWK -mode, just like the indentation rules (although each language still has -some peculiarities of its own, of course). Since the languages -previously had completely separate font locking patterns, this means -that it's a bit different in most languages now. - -The main goal for the font locking in @ccmode{} is accuracy, to provide -a dependable aid in recognizing the various constructs. Some, like -strings and comments, are easy to recognize while others, like -declarations and types, can be very tricky. @ccmode{} can go to great -lengths to recognize declarations and casts correctly, especially when -the types aren't recognized by standard patterns. This is a fairly -demanding analysis which can be slow on older hardware, and it can -therefore be disabled by choosing a lower decoration level with the -variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,, -emacs, GNU Emacs Manual}). - -@vindex font-lock-maximum-decoration - -The decoration levels are used as follows: - -@enumerate -@comment 1 -@item -Minimal font locking: Fontify only comments, strings and preprocessor -directives (in the languages that use cpp). - -@comment 2 -@item -Fast font locking: In addition to level 1, fontify keywords, simple -types and declarations that are easy to recognize. The variables -@code{*-font-lock-extra-types} (where @samp{*} is the name of the -language) are used to recognize types (see below). Documentation -comments like Javadoc are fontified according to -@code{c-doc-comment-style} (@pxref{Doc Comments}). - -Use this if you think the font locking is too slow. It's the closest -corresponding level to level 3 in the old font lock patterns. - -@comment 3 -@item -Accurate font locking: Like level 2 but uses a different approach that -can recognize types and declarations much more accurately. The -@code{*-font-lock-extra-types} variables are still used, but user -defined types are recognized correctly anyway in most cases. Therefore -those variables should be fairly restrictive and not contain patterns -that are uncertain. - -@cindex Lazy Lock mode -@cindex Just-in-time Lock mode - -This level is designed for fairly modern hardware and a font lock -support mode like Lazy Lock or Just-in-time Lock mode that only -fontifies the parts that are actually shown. Fontifying the whole -buffer at once can easily get bothersomely slow even on contemporary -hardware. @xref{Font Lock,,,@emacsman{}, @emacsmantitle{}}. -@end enumerate - -@cindex user defined types -@cindex types, user defined - -Since user defined types are hard to recognize you can provide -additional regexps to match those you use: - -@defopt c-font-lock-extra-types -@defoptx c++-font-lock-extra-types -@defoptx objc-font-lock-extra-types -@defoptx java-font-lock-extra-types -@defoptx idl-font-lock-extra-types -@defoptx pike-font-lock-extra-types -For each language there's a variable @code{*-font-lock-extra-types}, -where @samp{*} stands for the language in question. It contains a list -of regexps that matches identifiers that should be recognized as types, -e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t} -as is customary in C code. Each regexp should not match more than a -single identifier. - -The default values contain regexps for many types in standard runtime -libraries that are otherwise difficult to recognize, and patterns for -standard type naming conventions like the @samp{_t} suffix in C and C++. -Java, Objective-C and Pike have as a convention to start class names -with capitals, so there are patterns for that in those languages. - -Despite the names of these variables, they are not only used for -fontification but in other places as well where @ccmode{} needs to -recognize types. -@end defopt - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Faces, Doc Comments, Font Locking Preliminaries, Font Locking -@comment node-name, next, previous, up -@section Faces -@cindex faces -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} attempts to use the standard faces for programming languages -in accordance with their intended purposes as far as possible. No extra -faces are currently provided, with the exception of a replacement face -@code{c-invalid-face} for emacsen that don't provide -@code{font-lock-warning-face}. - -@itemize @bullet -@item -@vindex font-lock-comment-face -Normal comments are fontified in @code{font-lock-comment-face}. - -@item -@vindex font-lock-doc-face -@vindex font-lock-doc-string-face -@vindex font-lock-comment-face -Comments that are recognized as documentation (@pxref{Doc Comments}) -get @code{font-lock-doc-face} (Emacs) or -@code{font-lock-doc-string-face} (XEmacs) if those faces exist. If -they don't then @code{font-lock-comment-face} is used. - -@item -@vindex font-lock-string-face -String and character literals are fontified in -@code{font-lock-string-face}. - -@item -@vindex font-lock-keyword-face -Keywords are fontified with @code{font-lock-keyword-face}. - -@item -@vindex font-lock-function-name-face -@code{font-lock-function-name-face} is used for function names in -declarations and definitions, and classes in those contexts. It's also -used for preprocessor defines with arguments. - -@item -@vindex font-lock-variable-name-face -Variables in declarations and definitions, and other identifiers in such -variable contexts, get @code{font-lock-variable-name-face}. It's also -used for preprocessor defines without arguments. - -@item -@vindex font-lock-constant-face -@vindex font-lock-reference-face -Builtin constants are fontified in @code{font-lock-constant-face} if it -exists, @code{font-lock-reference-face} otherwise. As opposed to the -preceding two faces, this is used on the names in expressions, and it's -not used in declarations, even if there happen to be a @samp{const} in -them somewhere. - -@item -@vindex font-lock-type-face -@code{font-lock-type-face} is put on types (both predefined and user -defined) and classes in type contexts. - -@item -@vindex font-lock-constant-face -@vindex font-lock-reference-face -Label identifiers get @code{font-lock-constant-face} if it exists, -@code{font-lock-reference-face} otherwise. - -@item -Name qualifiers and identifiers for scope constructs are fontified like -labels. - -@item -Special markup inside documentation comments are also fontified like -labels. - -@item -@vindex font-lock-preprocessor-face -@vindex font-lock-builtin-face -@vindex font-lock-reference-face -Preprocessor directives get @code{font-lock-preprocessor-face} if it -exists (i.e. XEmacs). In Emacs they get @code{font-lock-builtin-face} -or @code{font-lock-reference-face}, for lack of a closer equivalent. - -@item -@vindex font-lock-warning-face -@vindex c-invalid-face -@vindex invalid-face (c-) -Some kinds of syntactic errors are fontified with -@code{font-lock-warning-face} in Emacs. In older XEmacs versions -there's no corresponding standard face, so there a special -@code{c-invalid-face} is used, which is defined to stand out sharply by -default. - -Note that it's not used for @samp{#error} or @samp{#warning} directives, -since those aren't syntactic errors in themselves. -@end itemize - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Doc Comments, AWK Mode Font Locking, Faces, Font Locking -@comment node-name, next, previous, up -@section Documentation Comments -@cindex documentation comments -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -There are various tools to supply documentation in the source as -specially structured comments, e.g. the standard Javadoc tool in Java. -@ccmode{} provides an extensible mechanism to fontify such comments and -the special markup inside them. - -@defopt c-doc-comment-style -@vindex doc-comment-style (c-) -This is a style variable that specifies which documentation comment -style to recognize, e.g. @code{javadoc} for Javadoc comments. - -The value may also be a list of styles, in which case all of them are -recognized simultaneously (presumably with markup cues that don't -conflict). - -The value may also be an association list to specify different comment -styles for different languages. The symbol for the major mode is then -looked up in the alist, and the value of that element is interpreted as -above if found. If it isn't found then the symbol `other' is looked up -and its value is used instead. - -The default value for @code{c-doc-comment-style} is -@w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}. - -Note that @ccmode{} uses this variable to set other variables that -handle fontification etc. That's done at mode initialization or when -you switch to a style which sets this variable. Thus, if you change it -in some other way, e.g. interactively in a CC Mode buffer, you will need -to do @kbd{M-x java-mode} (or whatever mode you're currently using) to -reinitialize. - -@findex c-setup-doc-comment-style -@findex setup-doc-comment-style (c-) -Note also that when @ccmode{} starts up, the other variables are -modified before the mode hooks are run. If you change this variable in -a mode hook, you'll have to call @code{c-setup-doc-comment-style} -afterwards to redo that work. -@end defopt - -@ccmode{} currently provides handing of the following doc comment -styles: - -@table @code -@item javadoc -@cindex Javadoc markup -Javadoc comments, the standard tool in Java. - -@item autodoc -@cindex Pike autodoc markup -For Pike autodoc markup, the standard in Pike. - -@item gtkdoc -@cindex GtkDoc markup -For GtkDoc markup, widely used in the Gnome community. -@end table - -The above is by no means complete. If you'd like to see support for -other doc comment styles, please let us know (@pxref{Mailing Lists and -Bug Reports}). - -You can also write your own doc comment fontification support to use -with @code{c-doc-comment-style}: Supply a variable or function -@code{*-font-lock-keywords} where @samp{*} is the name you want to use -in @code{c-doc-comment-style}. If it's a variable, it's prepended to -@code{font-lock-keywords}. If it's a function, it's called at mode -initialization and the result is prepended. For an example, see -@code{javadoc-font-lock-keywords} in @file{cc-fonts.el}. - -If you add support for another doc comment style, please consider -contributing it - send a note to @email{bug-cc-mode@@gnu.org}. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node AWK Mode Font Locking, , Doc Comments, Font Locking -@comment node-name, next, previous, up -@section AWK Mode Font Locking -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The general appearance of font-locking in AWK mode is much like in any -other programming mode. @xref{Faces For Font Lock,,,elisp, GNU Emacs -Lisp Reference Manual}. - -The following faces are, however, used in a non-standard fashion in -AWK mode: - -@table @asis -@item @code{font-lock-variable-name-face} -This face was intended for variable declarations. Since variables are -not declared in AWK, this face is used instead for AWK system -variables (such as @code{NF}) and ``Special File Names'' (such as -@code{"/dev/stderr"}). - -@item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs) -This face is normally used for preprocessor directives in @ccmode{}. -There are no such things in AWK, so this face is used instead for -standard functions (such as @code{match}). - -@item @code{font-lock-string-face} -As well as being used for strings, including localizable strings, -(delimited by @samp{"} and @samp{_"}), this face is also used for AWK -regular expressions (delimited by @samp{/}). - -@item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs) -This face highlights the following syntactically invalid AWK -constructs: - -@itemize @bullet -@item -An unterminated string or regular expression. Here the opening -delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in -@code{font-lock-warning-face}. This is most noticeable when typing in a -new string/regular expression into a buffer, when the warning-face -serves as a continual reminder to terminate the construct. - -AWK mode fontifies unterminated strings/regular expressions -differently from other modes: Only the text up to the end of the line -is fontified as a string (escaped newlines being handled correctly), -rather than the text up to the next string quote. - -@item -A space between the function name and opening parenthesis when calling -a user function. The last character of the function name and the -opening parenthesis are highlighted. This font-locking rule will -spuriously highlight a valid concatenation expression where an -identifier precedes a parenthesized expression. Unfortunately. - -@item -Whitespace following the @samp{\} in what otherwise looks like an -escaped newline. The @samp{\} is highlighted. -@end itemize -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Config Basics, Custom Filling and Breaking, Font Locking, Top -@comment node-name, next, previous, up -@chapter Configuration Basics -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex Emacs Initialization File -@cindex Configuration -You configure @ccmode{} by setting Lisp variables and calling (and -perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't -difficult.}, which is usually done by adding code to an Emacs -initialization file. This file might be @file{site-start.el} or -@file{.emacs} or @file{init.el} or @file{default.el} or perhaps some -other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For -the sake of conciseness, we just call this file ``your @file{.emacs}'' -throughout the rest of the manual. - -Several of these variables (currently 16), are known collectively as -@dfn{style variables}. @ccmode{} provides a special mechanism, known -as @dfn{styles} to make it easier to set these variables as a group, -to ``inherit'' settings from one style into another, and so on. Style -variables remain ordinary Lisp variables, whose values can be read and -changed independently of the style system. @xref{Style Variables}. - -There are several ways you can write the code, depending on the -precise effect you want---they are described further down on this page. -If you are new to @ccmode{}, we suggest you begin with the simplest -method, ``Top-level commands or the customization interface''. - -If you make conflicting settings in several of these ways, the way -that takes precedence is the one that appears latest in this list: -@itemize @w{} -@item -@table @asis -@item Style -@itemx File Style@footnote{In earlier versions of @ccmode{}, a File Style setting took precedence over any other setting apart from a File Local Variable setting.} -@itemx Top-level command or ``customization interface'' -@itemx Hook -@itemx File Local Variable setting -@end table -@end itemize - -Here is a summary of the different ways of writing your configuration -settings: - -@table @asis -@item Top-level commands or the ``customization interface'' -Most simply, you can write @code{setq} and similar commands at the top -level of your @file{.emacs} file. When you load a @ccmode{} buffer, -it initializes its configuration from these global values (at least, -for those settings you have given values to), so it makes sense to -have these @code{setq} commands run @emph{before} @ccmode{} is first -initialized---in particular, before any call to @code{desktop-read} -(@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For -example, you might set c-basic-offset thus: - -@example -(setq c-basic-offset 4) -@end example - -You can use the more user friendly Customization interface instead, -but this manual does not cover in detail how that works. To do this, -start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}. -@xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}. -@c The following note really belongs in the Emacs manual. -Emacs normally writes the customizations at the end of your -@file{.emacs} file. If you use @code{desktop-read}, you should edit -your @file{.emacs} to place the call to @code{desktop-read} @emph{after} -the customizations. - -The first initialization of @ccmode{} puts a snapshot of the -configuration settings into the special style @code{user}. -@xref{Built-in Styles}. - -For basic use of Emacs, either of these ways of configuring is -adequate. However, the settings are then the same in all @ccmode{} -buffers and it can be clumsy to communicate them between programmers. -For more flexibility, you'll want to use one (or both) of @ccmode{}'s -more sophisticated facilities, hooks and styles. - -@item Hooks -An Emacs @dfn{hook} is a place to put Lisp functions that you want -Emacs to execute later in specific circumstances. -@xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main -hook and a language-specific hook for each language it supports - any -functions you put onto these hooks get executed as the last part of a -buffer's initialization. Typically you put most of your customization -within the main hook, and use the language-specific hooks to vary the -customization settings between language modes. For example, if you -wanted different (non-standard) values of @code{c-basic-offset} in C -Mode and Java Mode buffers, you could do it like this: - -@example -@group -(defun my-c-mode-hook () - (setq c-basic-offset 3)) -(add-hook 'c-mode-hook 'my-c-mode-hook) - -(defun my-java-mode-hook () - (setq c-basic-offset 6)) -(add-hook 'java-mode-hook 'my-java-mode-hook) -@end group -@end example - -See @ref{CC Hooks} for more details on the use of @ccmode{} hooks. - -@item Styles -A @ccmode{} @dfn{style} is a coherent collection of customizations -with a name. At any time, exactly one style is active in each -@ccmode{} buffer, either the one you have selected or a default. -@ccmode{} is delivered with several existing styles. Additionally, -you can create your own styles, possibly based on these existing -styles. If you worked in a programming team called the ``Free -Group'', which had its own coding standards, you might well have this -in your @file{.emacs} file: - -@example -(setq c-default-style '((java-mode . "java") - (awk-mode . "awk") - (other . "free-group-style"))) -@end example - -See @ref{Styles} for fuller details on using @ccmode{} styles and how -to create them. - -@item File Local Variable setting -A @dfn{file local variable setting} is a setting which applies to an -individual source file. You put this in a @dfn{local variables list}, -a special block at the end of the source file (@pxref{Specifying File -Variables,,,@emacsman{}}). - -@item File Styles -A @dfn{file style} is a rarely used variant of the ``style'' mechanism -described above, which applies to an individual source file. -@xref{File Styles}. You use this by setting certain special variables -in a local variables list (@pxref{Specifying File -Variables,,,@emacsman{}}). - -@item Hooks with Styles -For ultimate flexibility, you can use hooks and styles together. For -example, if your team were developing a product which required a -Linux driver, you'd probably want to use the ``linux'' style for the -driver, and your own team's style for the rest of the code. You -could achieve this with code like this in your @file{.emacs}: - -@example -@group -(defun my-c-mode-hook () - (c-set-style - (if (and (buffer-file-name) - (string-match "/usr/src/linux" (buffer-file-name))) - "linux" - "free-group-style"))) -(add-hook 'c-mode-hook 'my-c-mode-hook) -@end group -@end example - -In a programming team, a hook is a also a good place for each member -to put his own personal preferences. For example, you might be the -only person in your team who likes Auto-newline minor mode. You could -have it enabled by default by placing the following in your -@file{.emacs}: - -@example -@group -(defun my-turn-on-auto-newline () - (c-toggle-auto-newline 1)) -(add-hook 'c-mode-common-hook 'my-turn-on-auto-newline) -@end group -@end example -@end table - -@menu -* CC Hooks:: -* Style Variables:: -* Styles:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node CC Hooks, Style Variables, Config Basics, Config Basics -@comment node-name, next, previous, up -@section Hooks -@cindex mode hooks -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@c The node name is "CC Hooks" rather than "Hooks" because of a bug in -@c some older versions of Info, e.g. the info.el in GNU Emacs 21.3. -@c If you go to "Config Basics" and hit on the xref to "CC -@c Hooks" the function Info-follow-reference searches for "*Note: CC -@c Hooks" from the beginning of the page. If this node were instead -@c named "Hooks", that search would spuriously find "*Note: -@c Hooks(elisp)" and go to the wrong node. - -@ccmode{} provides several hooks that you can use to customize the -mode for your coding style. The main hook is -@code{c-mode-common-hook}; typically, you'll put the bulk of your -customizations here. In addition, each language mode has its own -hook, allowing you to fine tune your settings individually for the -different @ccmode{} languages, and there is a package initialization -hook. Finally, there is @code{c-special-indent-hook}, which enables -you to solve anomalous indentation problems. It is described in -@ref{Other Indentation}, not here. All these hooks adhere to the -standard Emacs conventions. - -When you open a buffer, @ccmode{} first initializes it with the -currently active style (@pxref{Styles}). Then it calls -@code{c-mode-common-hook}, and finally it calls the language-specific -hook. Thus, any style settings done in these hooks will override -those set by @code{c-default-style}. - -@defvar c-initialization-hook -@vindex initialization-hook (c-) -Hook run only once per Emacs session, when @ccmode{} is initialized. -This is a good place to change key bindings (or add new ones) in any -of the @ccmode{} key maps. @xref{Sample .emacs File}. -@end defvar - -@defvar c-mode-common-hook -@vindex mode-common-hook (c-) -Common hook across all languages. It's run immediately before the -language specific hook. -@end defvar - -@defvar c-mode-hook -@defvarx c++-mode-hook -@defvarx objc-mode-hook -@defvarx java-mode-hook -@defvarx idl-mode-hook -@defvarx pike-mode-hook -@defvarx awk-mode-hook -The language specific mode hooks. The appropriate one is run as the -last thing when you enter that language mode. -@end defvar - -Although these hooks are variables defined in @ccmode{}, you can give -them values before @ccmode{}'s code is loaded---indeed, this is the -only way to use @code{c-initialization-hook}. Their values aren't -overwritten when @ccmode{} gets loaded. - -Here's a simplified example of what you can add to your @file{.emacs} -file to do things whenever any @ccmode{} language is edited. See the -Emacs manuals for more information on customizing Emacs via hooks. -@xref{Sample .emacs File}, for a more complete sample @file{.emacs} -file. - -@example -(defun my-c-mode-common-hook () - ;; my customizations for all of c-mode and related modes - (no-case-fold-search) - ) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) -@end example - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Style Variables, Styles, CC Hooks, Config Basics -@comment node-name, next, previous, up -@section Style Variables -@cindex styles -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex style variables -The variables that @ccmode{}'s style system control are called -@dfn{style variables}. Note that style variables are ordinary Lisp -variables, which the style system initializes; you can change their -values at any time (e.g. in a hook function). The style system can -also set other variables, to some extent. @xref{Styles}. - -@dfn{Style variables} are handled specially in several ways: - -@itemize @bullet -@item -Style variables are by default buffer-local variables. However, they -can instead be made global by setting -@code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is -initialized. - -@item -@vindex c-old-style-variable-behavior -@vindex old-style-variable-behavior (c-) -The default global binding of any style variable (with two exceptions -- see below) is the special symbol @code{set-from-style}. When the -style system initializes a buffer-local copy of a style variable for a -@ccmode{} buffer, if its global binding is still that symbol then it -will be set from the current style. Otherwise it will retain its -global default@footnote{This is a big change from versions of -@ccmode{} earlier than 5.26, where such settings would get overridden -by the style system unless special precautions were taken. That was -changed since it was counterintuitive and confusing, especially to -novice users. If your configuration depends on the old overriding -behavior, you can set the variable -@code{c-old-style-variable-behavior} to non-@code{nil}.}. This -``otherwise'' happens, for example, when you've set the variable with -@code{setq} at the top level of your @file{.emacs} (@pxref{Config -Basics}). - -@item -The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is -an association list with an element for each syntactic symbol. It's -handled a little differently from the other style variables. It's -default global binding is the empty list @code{nil}, rather than -@code{set-from-style}. Before the style system is initialized, you -can add individual elements to @code{c-offsets-alist} by calling -@code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set -other style variables with @code{setq}. Those elements will then -prevail when the style system later initializes a buffer-local copy of -@code{c-offsets-alist}. - -@item -The style variable @code{c-special-indent-hook} is also handled in a -special way. Styles can only add functions to this hook, not remove -them, so any global settings you put on it are always -preserved@footnote{This did not change in version 5.26.}. The value -you give this variable in a style definition can be either a function -or a list of functions. - -@item -The global bindings of the style variables get captured in the special -@code{user} style when the style system is first initialized. -@xref{Built-in Styles}, for details. -@end itemize - -The style variables are:@* -@code{c-indent-comment-alist}, -@code{c-indent-comments-syntactically-p} (@pxref{Indentation -Commands});@* -@code{c-doc-comment-style} (@pxref{Doc Comments});@* -@code{c-block-comment-prefix}, @code{c-comment-prefix-regexp} -(@pxref{Custom Filling and Breaking});@* -@code{c-hanging-braces-alist} (@pxref{Hanging Braces});@* -@code{c-hanging-colons-alist} (@pxref{Hanging Colons});@* -@code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and -Commas});@* -@code{c-cleanup-list} (@pxref{Clean-ups});@* -@code{c-basic-offset} (@pxref{Customizing Indentation});@* -@code{c-offsets-alist} (@pxref{c-offsets-alist});@* -@code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@* -@code{c-special-indent-hook}, @code{c-label-minimum-indentation} -(@pxref{Other Indentation});@* -@code{c-backslash-column}, @code{c-backslash-max-column} -(@pxref{Custom Macros}). - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Styles, , Style Variables, Config Basics -@comment node-name, next, previous, up -@section Styles -@cindex styles -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -By @dfn{style} we mean the layout of the code---things like how many -columns to indent a block of code, whether an opening brace gets -indented to the level of the code it encloses, or of the construct -that introduces it, or ``hangs'' at the end of a line. - -Most people only need to edit code formatted in just a few well-defined -and consistent styles. For example, their organization might impose a -``blessed'' style that all its programmers must conform to. Similarly, -people who work on GNU software will have to use the GNU coding style. -Some shops are more lenient, allowing a variety of coding styles, and as -programmers come and go, there could be a number of styles in use. For -this reason, @ccmode{} makes it convenient for you to set up logical -groupings of customizations called @dfn{styles}, associate a single name -for any particular style, and pretty easily start editing new or -existing code using these styles. - -As an alternative to writing a style definition yourself, you can have -@ccmode{} @dfn{guess} (at least part of) your style by looking at an -already formatted piece of your code, @ref{Guessing the Style}. - -@menu -* Built-in Styles:: -* Choosing a Style:: -* Adding Styles:: -* Guessing the Style:: -* File Styles:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Built-in Styles, Choosing a Style, Styles, Styles -@comment node-name, next, previous, up -@subsection Built-in Styles -@cindex styles, built-in -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If you're lucky, one of @ccmode{}'s built-in styles might be just -what you're looking for. These are: - -@table @code -@item gnu -@cindex GNU style -Coding style blessed by the Free Software Foundation -for C code in GNU programs. - -@item k&r -@cindex K&R style -The classic Kernighan and Ritchie style for C code. - -@item bsd -@cindex BSD style -Also known as ``Allman style'' after Eric Allman. - -@item whitesmith -@cindex Whitesmith style -Popularized by the examples that came with Whitesmiths C, an early -commercial C compiler. - -@item stroustrup -@cindex Stroustrup style -The classic Stroustrup style for C++ code. - -@item ellemtel -@cindex Ellemtel style -Popular C++ coding standards as defined by ``Programming in C++, Rules -and Recommendations,'' Erik Nyquist and Mats Henricson, -Ellemtel@footnote{This document is available at -@uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other -places.}. -@c N.B. This URL was still valid at 2005/8/28 (ACM). - -@item linux -@cindex Linux style -C coding standard for Linux (the kernel). - -@item python -@cindex Python style -C coding standard for Python extension modules@footnote{Python is a -high level scripting language with a C/C++ foreign function interface. -For more information, see @uref{http://www.python.org/}.}. - -@item java -@cindex Java style -The style for editing Java code. Note that the default -value for @code{c-default-style} installs this style when you enter -@code{java-mode}. - -@item awk -@cindex AWK style -The style for editing AWK code. Note that the default value for -@code{c-default-style} installs this style when you enter -@code{awk-mode}. - -@item user -@cindex User style -This is a special style created by you. It consists of the factory -defaults for all the style variables as modified by the customizations -you do either with the Customization interface or by writing -@code{setq}s and @code{c-set-offset}s at the top level of your -@file{.emacs} file (@pxref{Config Basics}). The style system creates -this style as part of its initialization and doesn't modify it -afterwards. -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Choosing a Style, Adding Styles, Built-in Styles, Styles -@comment node-name, next, previous, up -@subsection Choosing a Style -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -When you create a new buffer, its style will be set from -@code{c-default-style}. The factory default is the style @code{gnu}, -except in Java and AWK modes where it's @code{java} and @code{awk}. - -Remember that if you set a style variable with the Customization -interface or at the top level of your @file{.emacs} file before the -style system is initialized (@pxref{Config Basics}), this setting will -override the one that the style system would have given the variable. - -To set a buffer's style interactively, use the command @kbd{C-c .} -(@pxref{Other Commands}). To set it from a file's local variable -list, @ref{File Styles}. - -@defopt c-default-style -@vindex default-style (c-) -This variable specifies which style to install by default in new -buffers. It takes either a style name string, or an association list -of major mode symbols to style names: - -@enumerate -@item -When @code{c-default-style} is a string, it must be an existing style -name. This style is then used for all modes. - -@item -When @code{c-default-style} is an association list, the mode language -is looked up to find a style name string. - -@item -If @code{c-default-style} is an association list where the mode -language mode isn't found then the special symbol @samp{other} is -looked up. If it's found then the associated style is used. - -@item -If @samp{other} is not found then the @samp{gnu} style is used. -@end enumerate - -In all cases, the style described in @code{c-default-style} is installed -@emph{before} the language hooks are run, so you can always override -this setting by including an explicit call to @code{c-set-style} in your -language mode hook, or in @code{c-mode-common-hook}. - -The standard value of @code{c-default-style} is @w{@code{((java-mode -. "java") (awk-mode . "awk") (other . "gnu"))}}. -@end defopt - -@defvar c-indentation-style -@vindex indentation-style (c-) -This variable always contains the buffer's current style name, as a -string. -@end defvar - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Adding Styles, Guessing the Style, Choosing a Style, Styles -@comment node-name, next, previous, up -@subsection Adding and Amending Styles -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If none of the built-in styles is appropriate, you'll probably want to -create a new @dfn{style definition}, possibly based on an existing -style. To do this, put the new style's settings into a list with the -following format - the list can then be passed as an argument to the -function @code{c-add-style}. You can see an example of a style -definition in @ref{Sample .emacs File}. - -@cindex style definition -@c @defvr {List} style definition -@table @asis -@item Structure of a Style Definition List -([@var{base-style}] [(@var{variable} . @var{value}) @dots{}]) - -Optional @var{base-style}, if present, must be a string which is the -name of the @dfn{base style} from which this style inherits. At most -one @var{base-style} is allowed in a style definition. If -@var{base-style} is not specified, the style inherits from the table -of factory default values@footnote{This table is stored internally in -the variable c-fallback-style.} instead. All styles eventually -inherit from this internal table. Style loops generate errors. The -list of pre-existing styles can be seen in @ref{Built-in Styles}. - -The dotted pairs (@var{variable} . @var{value}) each consist of a -variable and the value it is to be set to when the style is later -activated.@footnote{Note that if the variable has been given a value -by the Customization interface or a @code{setq} at the top level of -your @file{.emacs}, this value will override the one the style system -tries to give it. @xref{Config Basics}.} The variable can be either a -@ccmode{} style variable or an arbitrary Emacs variable. In the -latter case, it is @emph{not} made buffer-local by the @ccmode{} style -system. -@c @end defvr - -Two variables are treated specially in the dotted pair list: - -@table @code -@item c-offsets-alist -The value is in turn a list of dotted pairs of the form - -@example -(@r{@var{syntactic-symbol}} . @r{@var{offset}}) -@end example - -as described in @ref{c-offsets-alist}. These are passed to -@code{c-set-offset} so there is no need to set every syntactic symbol -in your style, only those that are different from the inherited style. - -@item c-special-indent-hook -The value is added to @code{c-special-indent-hook} using -@code{add-hook}, so any functions already on it are kept. If the value -is a list, each element of the list is added with @code{add-hook}. -@end table -@end table - -Styles are kept in the @code{c-style-alist} variable, but you -should never modify this variable directly. Instead, @ccmode{} -provides the function @code{c-add-style} for this purpose. - -@defun c-add-style stylename description &optional set-p -@findex add-style (c-) -Add or update a style called @var{stylename}, a string. -@var{description} is the new style definition in the form described -above. If @var{stylename} already exists in @code{c-style-alist} then -it is replaced by @var{description}. (Note, this replacement is -total. The old style is @emph{not} merged into the new one.) -Otherwise, a new style is added. - -If the optional @var{set-p} is non-@code{nil} then the new style is -applied to the current buffer as well. The use of this facility is -deprecated and it might be removed from @ccmode{} in a future release. -You should use @code{c-set-style} instead. - -The sample @file{.emacs} file provides a concrete example of how a new -style can be added and automatically set. @xref{Sample .emacs File}. -@end defun - -@defvar c-style-alist -@vindex style-alist (c-) -This is the variable that holds the definitions for the styles. It -should not be changed directly; use @code{c-add-style} instead. -@end defvar - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Guessing the Style, File Styles, Adding Styles, Styles -@comment node-name, next, previous, up -@subsection Guessing the Style -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Instead of specifying a style, you can get @ccmode{} to @dfn{guess} -your style by examining an already formatted code buffer. @ccmode{} -then determines the ''most frequent'' offset (@pxref{c-offsets-alist}) -for each of the syntactic symbols (@pxref{Indentation Engine Basics}) -encountered in the buffer, and the ''most frequent'' value of -c-basic-offset (@pxref{Customizing Indentation}), then merges the -current style with these ''guesses'' to form a new style. This -combined style is known as the @dfn{guessed style}. - -To do this, call @code{c-guess} (or one of the other 5 guessing -commands) on your sample buffer. The analysis of your code may take -some time. - -You can then set the guessed style in any @ccmode{} buffer with -@code{c-guess-install}. You can display the style with -@code{c-guess-view}, and preserve it by copying it into your -@file{.emacs} for future use, preferably after editing it. - -@table @asis -@item @kbd{M-x c-guess-no-install} -@itemx @kbd{M-x c-guess-buffer-no-install} -@itemx @kbd{M-x c-guess-region-no-install} -@findex c-guess-no-install -@findex c-guess-buffer-no-install -@findex c-guess-region-no-install -@findex guess-no-install (c-) -@findex guess-buffer-no-install (c-) -@findex guess-region-no-install (c-) -These commands analyze a part of the current buffer and guess the -style from it. - -The part of the buffer examined is either the region -(@code{c-guess-region-no-install}), the entire buffer -(@code{c-guess-buffer-no-install}), or the first -@code{c-guess-region-max} bytes (@code{c-guess-no-install}). - -Each of these commands can be given an optional prefix argument. This -instructs @ccmode{} to combine the new guesses with the current -guesses before forming the guessed style. -@end table - -@table @asis -@item @kbd{M-x c-guess} -@itemx @kbd{M-x c-guess-buffer} -@itemx @kbd{M-x c-guess-region} -@findex c-guess -@findex c-guess-buffer -@findex c-guess-region -@findex guess (c-) -@findex guess-buffer (c-) -@findex guess-region (c-) -These commands analyze a part of the current buffer, guess the style -from it, then install the guessed style on the buffer. The guessed -style is given a name based on the buffer's absolute file name, and -you can then set this style on any @ccmode{} buffer with @kbd{C-c .}. - -The part of the buffer examined is either the region -(@code{c-guess-region}), the entire buffer (@code{c-guess-buffer}), or -the first @code{c-guess-region-max} bytes (@code{c-guess}). - -Each of these commands can be given an optional prefix argument. This -instructs @ccmode{} to combine the new guesses with the current -guesses before forming the guessed style. -@end table - -@defopt c-guess-region-max -@vindex guess-region-max (c-) -This variable, default 50000, is the size in bytes of the buffer -portion examined by c-guess and c-guess-no-install. If set to -@code{nil}, the entire buffer is examined. -@end defopt - -@defopt c-guess-offset-threshold -@vindex guess-offset-threshold (c-) -This variable, default 10, is the maximum offset, either outwards or -inwards, which will be taken into account by the analysis process. -Any offset bigger than this will be ignored. For no limit, set this -variable to a large number. -@end defopt - -@table @asis -@item @kbd{M-x c-guess-install} -@findex c-guess-install -@findex guess-install (c-) - -Set the current buffer's style to the guessed style. This prompts you -to enter an optional new style name to give to the guessed style. By -default, this name is based on the buffer's absolute file name. You -can then use this style like any other. - -@item @kbd{M-x c-guess-view} -@findex c-guess-view -@findex guess-view (c-) -Display the most recently guessed style in a temporary buffer. This -display is in the form of a @code{c-add-style} form (@pxref{Adding -Styles}) which can be easily copied to your @file{.emacs}. You will -probably want to edit it first. - -The display of the guessed style contains these elements: - -@table @asis -@item Placeholder Name -You should replace this with a style name of your own. -@item Parent Style -The style current when the guessing began, from which the guessed -style inherits (@pxref{Config Basics}) the settings which weren't -guessed. -@item Guessed Offsets -These are the core result of the guessing process. Each of them is -marked by a comment. -@item Inherited Offsets -These are syntactic offsets which have been taken over from the parent -style. To avoid possible future conflicts, you should remove either -these offsets or the parent style name. -@end table -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node File Styles, , Guessing the Style, Styles -@comment node-name, next, previous, up -@subsection File Styles -@cindex styles, file local -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex file local variables - -The Emacs manual describes how you can customize certain variables on a -per-file basis by including a @dfn{file local variable} block at the end -of the file (@pxref{File Variables,, Local Variables in Files,@emacsman{}, -@emacsmantitle{}}). - -So far, you've only seen a functional interface for setting styles in -@ccmode{}, and this can't be used here. @ccmode{} fills the gap by -providing two variables for use in a file's local variable list. -Don't use them anywhere else! These allow you to customize the style -on a per-file basis: - -@defvar c-file-style -@vindex file-style (c-) -Set this variable to a style name string in the Local Variables list. -From now on, when you visit the file, @ccmode{} will automatically set -the file's style to this one using @code{c-set-style}. -@end defvar - -@defvar c-file-offsets -@vindex file-offsets (c-) -Set this variable (in the Local Variables list) to an association list -of the same format as @code{c-offsets-alist}. From now on, when you -visit the file, @ccmode{} will automatically institute these offsets -using @code{c-set-offset}. -@end defvar - -Note that file style settings (i.e. @code{c-file-style}) are applied -before file offset settings -(i.e. @code{c-file-offsets})@footnote{Also, if either of these are set -in a file's local variable section, all the style variable values are -made local to that buffer, even if -@code{c-style-variables-are-local-p} is @code{nil}. Since this -variable is virtually always non-@code{nil} anyhow, you're unlikely to -notice this effect.}. - -If you set any variable by the file local variables mechanism, that -setting takes priority over all other settings, even those in your -mode hooks (@pxref{CC Hooks}). Any individual setting of a variable -will override one made through @code{c-file-style} or -@code{c-file-offsets}. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top -@comment node-name, next, previous, up -@chapter Customizing Filling and Line Breaking -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since there's a lot of normal text in comments and string literals, -@ccmode{} provides features to edit these like in text mode. It does -this by hooking in on the different line breaking functions and tuning -relevant variables as necessary. - -@vindex c-comment-prefix-regexp -@vindex comment-prefix-regexp (c-) -@cindex comment line prefix -@vindex comment-start -@vindex comment-end -@vindex comment-start-skip -@vindex paragraph-start -@vindex paragraph-separate -@vindex paragraph-ignore-fill-prefix -@vindex adaptive-fill-mode -@vindex adaptive-fill-regexp -@vindex adaptive-fill-first-line-regexp -To make Emacs recognize comments and treat text in them as normal -paragraphs, @ccmode{} makes several standard -variables@footnote{@code{comment-start}, @code{comment-end}, -@code{comment-start-skip}, @code{paragraph-start}, -@code{paragraph-separate}, @code{paragraph-ignore-fill-prefix}, -@code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and -@code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them -according to the language syntax and the comment line prefix. - -@defopt c-comment-prefix-regexp -@vindex comment-prefix-regexp (c-) -This style variable contains the regexp used to recognize the -@dfn{comment line prefix}, which is the line decoration that starts -every line in a comment. The variable is either the comment line -prefix itself, or (more usually) an association list with different -values for different languages. The symbol for the major mode is -looked up in the alist to get the regexp for the language, and if it -isn't found then the special symbol @samp{other} is looked up instead. - -When a comment line gets divided by @kbd{M-j} or the like, @ccmode{} -inserts the comment line prefix from a neighboring line at the start -of the new line. The default value of c-comment-prefix-regexp is -@samp{//+\\|\\**}, which matches C++ style line comments like - -@example -// blah blah -@end example - -@noindent -with two or more slashes in front of them, and the second and -subsequent lines of C style block comments like - -@example -@group -/* - * blah blah - */ -@end group -@end example - -@noindent -with zero or more stars at the beginning of every line. If you change -this variable, please make sure it still matches the comment starter -(i.e. @code{//}) of line comments @emph{and} the line prefix inside -block comments. - -@findex c-setup-paragraph-variables -@findex setup-paragraph-variables (c-) -Also note that since @ccmode{} uses the value of -@code{c-comment-prefix-regexp} to set up several other variables at -mode initialization, there won't be any effect if you just change it -inside a @ccmode{} buffer. You need to call the command -@code{c-setup-paragraph-variables} too, to update those other -variables. That's also the case if you modify -@code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will -already have set up these variables before calling the hook. -@end defopt - -In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt -the line prefix from the other lines in the comment. - -@vindex adaptive-fill-mode -@cindex Adaptive Fill mode -@ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU -Emacs Manual}) to make Emacs correctly keep the line prefix when -filling paragraphs. That also makes Emacs preserve the text -indentation @emph{inside} the comment line prefix. E.g. in the -following comment, both paragraphs will be filled with the left -margins of the texts kept intact: - -@example -@group -/* Make a balanced b-tree of the nodes in the incoming - * stream. But, to quote the famous words of Donald E. - * Knuth, - * - * Beware of bugs in the above code; I have only - * proved it correct, not tried it. - */ -@end group -@end example - -@findex c-setup-filladapt -@findex setup-filladapt (c-) -@findex filladapt-mode -@vindex filladapt-mode -@cindex Filladapt mode -It's also possible to use other adaptive filling packages, notably Kyle -E. Jones' Filladapt package@footnote{It's available from -@uref{http://www.wonderworks.com/}. As of version 2.12, it does however -lack a feature that makes it work suboptimally when -@code{c-comment-prefix-regexp} matches the empty string (which it does -by default). A patch for that is available from -@uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.}, -@c 2005/11/22: The above is still believed to be the case. -which handles things like bulleted lists nicely. There's a convenience -function @code{c-setup-filladapt} that tunes the relevant variables in -Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with -something like this in your @file{.emacs}: - -@example -(defun my-c-mode-common-hook () - (c-setup-filladapt) - (filladapt-mode 1)) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) -@end example - -@defopt c-block-comment-prefix -@vindex block-comment-prefix (c-) -@vindex c-comment-continuation-stars -@vindex comment-continuation-stars (c-) -Normally the comment line prefix inserted for a new line inside a -comment is deduced from other lines in it. However there's one -situation when there's no hint about what the prefix should look like, -namely when a block comment is broken for the first time. This style -variable@footnote{In versions before 5.26, this variable was called -@code{c-comment-continuation-stars}. As a compatibility measure, -@ccmode{} still uses the value on that variable if it's set.} is used -then as the comment prefix. It defaults to @samp{* -}@footnote{Actually, this default setting of -@code{c-block-comment-prefix} typically gets overridden by the default -style @code{gnu}, which sets it to blank. You can see the line -splitting effect described here by setting a different style, -e.g. @code{k&r} @xref{Choosing a Style}.}, which makes a comment - -@example -/* Got O(n^2) here, which is a Bad Thing. */ -@end example - -@noindent -break into - -@example -@group -/* Got O(n^2) here, which - * is a Bad Thing. */ -@end group -@end example - -Note that it won't work to adjust the indentation by putting leading -spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the -normal indentation engine to indent the line. Thus, the right way to -fix the indentation is by customizing the @code{c} syntactic symbol. It -defaults to @code{c-lineup-C-comments}, which handles the indentation of -most common comment styles, see @ref{Line-Up Functions}. -@end defopt - -@defopt c-ignore-auto-fill -@vindex ignore-auto-fill (c-) -When auto fill mode is enabled, @ccmode{} can selectively ignore it -depending on the context the line break would occur in, e.g. to never -break a line automatically inside a string literal. This variable -takes a list of symbols for the different contexts where auto-filling -never should occur: - -@table @code -@item string -Inside a string or character literal. -@item c -Inside a C style block comment. -@item c++ -Inside a C++ style line comment. -@item cpp -Inside a preprocessor directive. -@item code -Anywhere else, i.e. in normal code. -@end table - -By default, @code{c-ignore-auto-fill} is set to @code{(string cpp -code)}, which means that when auto-fill mode is activated, -auto-filling only occurs in comments. In literals, it's often -desirable to have explicit control over newlines. In preprocessor -directives, the necessary @samp{\} escape character before the newline -is not automatically inserted, so an automatic line break would -produce invalid code. In normal code, line breaks are normally -dictated by some logical structure in the code rather than the last -whitespace character, so automatic line breaks there will produce poor -results in the current implementation. -@end defopt - -@vindex comment-multi-line -If inside a comment and @code{comment-multi-line} (@pxref{Auto -Fill,,,@emacsman{}, @emacsmantitle{}} is non-@code{nil}, the -indentation and -line prefix are preserved. If inside a comment and -@code{comment-multi-line} is @code{nil}, a new comment of the same -type is started on the next line and indented as appropriate for -comments. - -Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at -startup. The reason is that @kbd{M-j} could otherwise produce sequences -of single line block comments for texts that should logically be treated -as one comment, and the rest of the paragraph handling code -(e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to -inconsistent behavior. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top -@comment node-name, next, previous, up -@chapter Customizing Auto-newlines -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} determines whether to insert auto-newlines in two basically -different ways, depending on the character just typed: - -@table @asis -@item Braces and Colons -@ccmode{} first determines the syntactic context of the brace or colon -(@pxref{Syntactic Symbols}), then looks for a corresponding element in -an alist. This element specifies where to put newlines - this is any -combination of before and after the brace or colon. If no alist -element is found, newlines are inserted both before and after a brace, -but none are inserted around a colon. See @ref{Hanging Braces} and -@ref{Hanging Colons}. - -@item Semicolons and Commas -The variable @code{c-hanging-semi&comma-criteria} contains a list of -functions which determine whether to insert a newline after a newly -typed semicolon or comma. @xref{Hanging Semicolons and Commas}. -@end table - -The names of these configuration variables contain @samp{hanging} -because they let you @dfn{hang} the pertinent characters. A character -which introduces a C construct is said to @dfn{hang on the right} when -it appears at the end of a line after other code, being separated by a -line break from the construct it introduces, like the opening brace in: - -@example -@group -while (i < MAX) @{ - total += entry[i]; - entry [i++] = 0; -@} -@end group -@end example - -@noindent -A character @dfn{hangs on the left} when it appears at the start of -the line after the construct it closes off, like the above closing -brace. - -The next chapter, ``Clean-ups'', describes how to configure @ccmode{} -to remove these automatically added newlines in certain specific -circumstances. @xref{Clean-ups}. - -@menu -* Hanging Braces:: -* Hanging Colons:: -* Hanging Semicolons and Commas:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines -@comment node-name, next, previous, up -@section Hanging Braces -@cindex hanging braces -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -To specify which kinds of braces you want auto-newlines put around, -you set the style variable @code{c-hanging-braces-alist}. Its -structure and semantics are described in this section. Details of how -to set it up, and its relationship to CC Mode's style system are given -in @ref{Style Variables}. - -Say you wanted an auto-newline after (but not before) the following -@samp{@{}: - -@example -if (foo < 17) @{ -@end example - -@noindent -First you need to find the @dfn{syntactic context} of the brace---type -a @key{RET} before the brace to get it on a line of its -own@footnote{Also insert a @samp{\} at the end of the previous line if -you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you -something like: - -@example -((substatement-open 1061)) -@end example - -@noindent -So here you need to put the entry @code{(substatement-open . (after))} -into @code{c-hanging-braces-alist}. - -If you don't want any auto-newlines for a particular syntactic symbol, -put this into @code{c-hanging-braces-alist}: - -@example -(brace-entry-open) -@end example - -If some brace syntactic symbol is not in @code{c-hanging-brace-alist}, -its entry is taken by default as @code{(before after)}---insert a -newline both before and after the brace. In place of a -``before/after'' list you can specify a function in this alist---this -is useful when the auto newlines depend on the code around the brace. - -@defopt c-hanging-braces-alist -@vindex hanging-braces-alist (c-) - -This variable is an association list which maps syntactic symbols to -lists of places to insert a newline. @xref{Association -Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the -syntactic symbol, the associated value is either @code{nil}, a list, -or a function. - -@table @asis -@item The Key - the syntactic symbol -The syntactic symbols that are useful as keys in this list are -@code{brace-list-intro}, @code{statement-cont}, -@code{inexpr-class-open}, @code{inexpr-class-close}, and all the -@code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols}, -for a more detailed description of these syntactic symbols, except for -@code{inexpr-class-open} and @code{inexpr-class-close}, which aren't -actual syntactic symbols. Elements with any other value as a key get -ignored. - -The braces of anonymous inner classes in Java are given the special -symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that -they can be distinguished from the braces of normal classes@footnote{The -braces of anonymous classes produce a combination of -@code{inexpr-class}, and @code{class-open} or @code{class-close} in -normal indentation analysis.}. - -Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})}, -@samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace -lists in this regard, even though they do for normal indentation -purposes. It's currently not possible to set automatic newlines on -these constructs. - -@item The associated value - the ``ACTION'' list or function -The value associated with each syntactic symbol in this association -list is called an @var{action}, which can be either a list or a -function which returns a list. @xref{Custom Braces}, for how to use -a function as a brace hanging @var{action}. - -The list @var{action} (or the list returned by @var{action} when it's -a function) contains some combination of the symbols @code{before} and -@code{after}, directing @ccmode{} where to put newlines in -relationship to the brace being inserted. Thus, if the list contains -only the symbol @code{after}, then the brace hangs on the right side -of the line, as in: - -@example -// here, open braces always `hang' -void spam( int i ) @{ - if( i == 7 ) @{ - dosomething(i); - @} -@} -@end example - -When the list contains both @code{after} and @code{before}, the braces -will appear on a line by themselves, as shown by the close braces in -the above example. The list can also be empty, in which case newlines -are added neither before nor after the brace. -@end table - -If a syntactic symbol is missing entirely from -@code{c-hanging-braces-alist}, it's treated in the same way as an -@var{action} with a list containing @code{before} and @code{after}, so -that braces by default end up on their own line. - -For example, the default value of @code{c-hanging-braces-alist} is: - -@example -((brace-list-open) - (brace-entry-open) - (statement-cont) - (substatement-open after) - (block-close . c-snug-do-while) - (extern-lang-open after) - (namespace-open after) - (module-open after) - (composition-open after) - (inexpr-class-open after) - (inexpr-class-close before)) -@end example - -@noindent which says that @code{brace-list-open}, -@code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists -inside statements, such as initializers for static array variables -inside functions in C, are recognized as @code{statement-cont}. All -normal substatement blocks are recognized with other symbols.} braces -should both hang on the right side and allow subsequent text to follow -on the same line as the brace. Also, @code{substatement-open}, -@code{extern-lang-open}, and @code{inexpr-class-open} braces should hang -on the right side, but subsequent text should follow on the next line. -The opposite holds for @code{inexpr-class-close} braces; they won't -hang, but the following text continues on the same line. Here, in the -@code{block-close} entry, you also see an example of using a function as -an @var{action}. In all other cases, braces are put on a line by -themselves. -@end defopt - -@menu -* Custom Braces:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Braces, , Hanging Braces, Hanging Braces -@comment node-name, next, previous, up -@subsection Custom Brace Hanging -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@vindex c-hanging-braces-alist -@vindex hanging-braces-alist (c-) -@cindex action functions -Syntactic symbols aren't the only place where you can customize -@ccmode{} with the lisp equivalent of callback functions. Remember -that @var{action}s are usually a list containing some combination of -the symbols @code{before} and @code{after} (@pxref{Hanging Braces}). -For more flexibility, you can instead specify brace ``hanginess'' by -giving a syntactic symbol an @dfn{action function} in -@code{c-hanging-braces-alist}; this function determines the -``hanginess'' of a brace, usually by looking at the code near it. - -@cindex customization, brace hanging -An action function is called with two arguments: the syntactic symbol -for the brace (e.g. @code{substatement-open}), and the buffer position -where the brace has been inserted. Point is undefined on entry to an -action function, but the function must preserve it (e.g. by using -@code{save-excursion}). The return value should be a list containing -some combination of @code{before} and @code{after}, including neither -of them (i.e. @code{nil}). - -@defvar c-syntactic-context -@vindex syntactic-context (c-) -During the call to the indentation or brace hanging @var{action} -function, this variable is bound to the full syntactic analysis list. -This might be, for example, @samp{((block-close 73))}. Don't ever -give @code{c-syntactic-context} a value yourself---this would disrupt -the proper functioning of @ccmode{}. - -This variable is also bound in three other circumstances: -(i)@w{ }when calling a c-hanging-semi&comma-criteria function -(@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a -line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a -c-special-indent-hook function (@pxref{Other Indentation}). -@end defvar - -As an example, @ccmode{} itself uses this feature to dynamically -determine the hanginess of braces which close ``do-while'' -constructs: - -@example -void do_list( int count, char** atleast_one_string ) -@{ - int i=0; - do @{ - handle_string( atleast_one_string[i] ); - i++; - @} while( i < count ); -@} -@end example - -@ccmode{} assigns the @code{block-close} syntactic symbol to the -brace that closes the @code{do} construct, and normally we'd like the -line that follows a @code{block-close} brace to begin on a separate -line. However, with ``do-while'' constructs, we want the -@code{while} clause to follow the closing brace. To do this, we -associate the @code{block-close} symbol with the @var{action} function -@code{c-snug-do-while}: - -@example -(defun c-snug-do-while (syntax pos) - "Dynamically calculate brace hanginess for do-while statements." - (save-excursion - (let (langelem) - (if (and (eq syntax 'block-close) - (setq langelem (assq 'block-close c-syntactic-context)) - (progn (goto-char (cdr langelem)) - (if (= (following-char) ?@{) - (forward-sexp -1)) - (looking-at "\\[^_]"))) - '(before) - '(before after))))) -@end example - -@findex c-snug-do-while -@findex snug-do-while (c-) -This function simply looks to see if the brace closes a ``do-while'' -clause and if so, returns the list @samp{(before)} indicating -that a newline should be inserted before the brace, but not after it. -In all other cases, it returns the list @samp{(before after)} so -that the brace appears on a line by itself. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines -@comment node-name, next, previous, up -@section Hanging Colons -@cindex hanging colons -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex customization, colon hanging -@vindex c-hanging-colons-alist -@vindex hanging-colons-alist (c-) - -Using a mechanism similar to brace hanging (@pxref{Hanging Braces}), -colons can also be made to hang using the style variable -@code{c-hanging-colons-alist} - When a colon is typed, @ccmode -determines its syntactic context, looks this up in the alist -@code{c-changing-colons-alist} and inserts up to two newlines -accordingly. Here, however, If @ccmode fails to find an entry for a -syntactic symbol in the alist, no newlines are inserted around the -newly typed colon. - -@defopt c-hanging-colons-alist -@vindex hanging-colons-alist (c-) - -@table @asis -@item The Key - the syntactic symbol -The syntactic symbols appropriate as keys in this association list -are: @code{case-label}, @code{label}, @code{access-label}, -@code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic -Symbols}. Elements with any other value as a key get ignored. - -@item The associate value - the ``ACTION'' list -The @var{action} here is simply a list containing a combination of the -symbols @code{before} and @code{after}. Unlike in -@code{c-hanging-braces-alist}, functions as @var{actions} are not -supported - there doesn't seem to be any need for them. -@end table -@end defopt - -In C++, double-colons are used as a scope operator but because these -colons always appear right next to each other, newlines before and after -them are controlled by a different mechanism, called @dfn{clean-ups} in -@ccmode{}. @xref{Clean-ups}, for details. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines -@comment node-name, next, previous, up -@section Hanging Semicolons and Commas -@cindex hanging semicolons -@cindex hanging commas -@cindex customization, semicolon newlines -@cindex customization, comma newlines -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@defopt c-hanging-semi&comma-criteria -@vindex hanging-semi&comma-criteria (c-) -This style variable takes a list of functions; these get called when -you type a semicolon or comma. The functions are called in order -without arguments. When these functions are entered, point is just -after the newly inserted @samp{;} or @samp{,} and they must preserve -point (e.g., by using @code{save-excursion}). During the call, the -variable @code{c-syntactic-context} is bound to the syntactic context -of the current line@footnote{This was first introduced in @ccmode{} -5.31.} @pxref{Custom Braces}. These functions don't insert newlines -themselves, rather they direct @ccmode{} whether or not to do so. -They should return one of the following values: - -@table @code -@item t -A newline is to be inserted after the @samp{;} or @samp{,}, and no -more functions from the list are to be called. -@item stop -No more functions from the list are to be called, and no newline is to -be inserted. -@item nil -No determination has been made, and the next function in the list is -to be called. -@end table - -Note that auto-newlines are never inserted @emph{before} a semicolon -or comma. If every function in the list is called without a -determination being made, then no newline is added. - -In AWK mode, this variable is set by default to @code{nil}. In the -other modes, the default value is a list containing a single function, -@code{c-semi&comma-inside-parenlist}. This inserts newlines after all -semicolons, apart from those separating @code{for}-clause statements. -@end defopt - -@defun c-semi&comma-no-newlines-before-nonblanks -@findex semi&comma-no-newlines-before-nonblanks (c-) -This is an example of a criteria function, provided by @ccmode{}. It -prevents newlines from being inserted after semicolons when there is a -non-blank following line. Otherwise, it makes no determination. To -use, add this function to the front of the -@code{c-hanging-semi&comma-criteria} list. - -@example -(defun c-semi&comma-no-newlines-before-nonblanks () - (save-excursion - (if (and (eq last-command-char ?\;) - (zerop (forward-line 1)) - (not (looking-at "^[ \t]*$"))) - 'stop - nil))) -@end example -@end defun - -@defun c-semi&comma-inside-parenlist -@findex semi&comma-inside-parenlist (c-) -@defunx c-semi&comma-no-newlines-for-oneline-inliners -@findex semi&comma-no-newlines-for-oneline-inliners (c-) -The function @code{c-semi&comma-inside-parenlist} is what prevents -newlines from being inserted inside the parenthesis list of @code{for} -statements. In addition to -@code{c-semi&comma-no-newlines-before-nonblanks} described above, -@ccmode{} also comes with the criteria function -@code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses -newlines after semicolons inside one-line inline method definitions -(e.g. in C++ or Java). -@end defun - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top -@comment node-name, next, previous, up -@chapter Clean-ups -@cindex clean-ups -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@dfn{Clean-ups} are mechanisms which remove (or exceptionally, add) -whitespace in specific circumstances and are complementary to colon -and brace hanging. You enable a clean-up by adding its symbol into -@code{c-cleanup-list}, e.g. like this: - -@example -(add-to-list 'c-cleanup-list 'space-before-funcall) -@end example - -On the surface, it would seem that clean-ups overlap the functionality -provided by the @code{c-hanging-*-alist} variables. Clean-ups, -however, are used to adjust code ``after-the-fact'', i.e. to adjust -the whitespace in constructs later than when they were typed. - -Most of the clean-ups remove automatically inserted newlines, and are -only active when auto-newline minor mode is turned on. Others will -work all the time. Note that clean-ups are only performed when there -is nothing but whitespace appearing between the individual components -of the construct, and (apart from @code{comment-close-slash}) when the -construct does not occur within a literal (@pxref{Auto-newlines}). - -@defopt c-cleanup-list -@vindex cleanup-list (c-) -@cindex literal - -You configure @ccmode{}'s clean-ups by setting the style variable -@code{c-cleanup-list}, which is a list of clean-up symbols. By -default, @ccmode{} cleans up only the @code{scope-operator} construct, -which is necessary for proper C++ support. -@end defopt - -These are the clean-ups that are only active when electric and -auto-newline minor modes are enabled: - -@c TBD: Would like to use some sort of @deffoo here; @table indents a -@c bit too much in dvi output. -@table @code -@item brace-else-brace -Clean up @samp{@} else @{} constructs by placing the entire construct on -a single line. Clean up occurs when the open brace after the -@samp{else} is typed. So for example, this: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} - else - @{ -@end group -@end example - -@noindent -appears like this after the last open brace is typed: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else @{ -@end group -@end example - -@item brace-elseif-brace -Similar to the @code{brace-else-brace} clean-up, but this cleans up -@samp{@} else if (...) @{} constructs. For example: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} - else if( i==3 ) - @{ -@end group -@end example - -@noindent -appears like this after the last open parenthesis is typed: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else if( -@end group -@end example - -@noindent -and like this after the last open brace is typed: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else if( i==3 ) @{ -@end group -@end example - -@item brace-catch-brace -Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch -(...) @{} in C++ and Java mode. - -@item empty-defun-braces -Clean up braces following a top-level function or class definition that -contains no body. Clean up occurs when the closing brace is typed. -Thus the following: - -@example -@group -class Spam -@{ -@} -@end group -@end example - -@noindent -is transformed into this when the close brace is typed: - -@example -@group -class Spam -@{@} -@end group -@end example - -@item defun-close-semi -Clean up the terminating semicolon on top-level function or class -definitions when they follow a close brace. Clean up occurs when the -semicolon is typed. So for example, the following: - -@example -@group -class Spam -@{ -... -@} -; -@end group -@end example - -@noindent -is transformed into this when the semicolon is typed: - -@example -@group -class Spam -@{ -... -@}; -@end group -@end example - -@item list-close-comma -Clean up commas following braces in array and aggregate initializers. -Clean up occurs when the comma is typed. The space before the comma -is zapped just like the space before the semicolon in -@code{defun-close-semi}. - -@item scope-operator -Clean up double colons which might designate a C++ scope operator split -across multiple lines@footnote{Certain C++ constructs introduce -ambiguous situations, so @code{scope-operator} clean-ups might not -always be correct. This usually only occurs when scoped identifiers -appear in switch label tags.}. Clean up occurs when the second colon is -typed. You will always want @code{scope-operator} in the -@code{c-cleanup-list} when you are editing C++ code. - -@item one-liner-defun -Clean up a single line of code enclosed by defun braces by removing -the whitespace before and after the code. The clean-up happens when -the closing brace is typed. If the variable -@code{c-max-one-liner-length} is set, the cleanup is only done if the -resulting line would be no longer than the value of that variable. - -For example, consider this AWK code: - -@example -@group -BEGIN @{ - FS = "\t" # use as a field separator -@} -@end group -@end example - -@noindent -It gets compacted to the following when the closing brace is typed: - -@example -@group -BEGIN @{FS = "\t"@} # use as a field separator -@end group -@end example - -@defopt c-max-one-liner-length -@vindex max-one-liner-length (c-) -The maximum length of the resulting line for which the clean-up -@code{one-liner-defun} will be triggered. This length is that of the entire -line, including any leading whitespace and any trailing comment. Its -default value is 80. If the value is zero or @code{nil}, no limit -applies. -@end defopt -@end table - -The following clean-ups are always active when they occur on -@code{c-cleanup-list}, regardless of whether Electric minor mode or -Auto-newline minor mode are enabled: - -@table @code -@item space-before-funcall -Insert a space between the function name and the opening parenthesis -of a function call. This produces function calls in the style -mandated by the GNU coding standards, e.g. @samp{signal@w{ }(SIGINT, -SIG_IGN)} and @samp{abort@w{ }()}. Clean up occurs when the opening -parenthesis is typed. This clean-up should never be active in AWK -Mode, since such a space is syntactically invalid for user defined -functions. - -@item compact-empty-funcall -Clean up any space between the function name and the opening parenthesis -of a function call that has no arguments. This is typically used -together with @code{space-before-funcall} if you prefer the GNU function -call style for functions with arguments but think it looks ugly when -it's only an empty parenthesis pair. I.e. you will get @samp{signal -(SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the -closing parenthesis is typed. - -@item comment-close-slash -When inside a block comment, terminate the comment when you type a slash -at the beginning of a line (i.e. immediately after the comment prefix). -This clean-up removes whitespace preceding the slash and if needed, -inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this -situation if you just want a literal @samp{/} inserted. -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top -@comment node-name, next, previous, up -@chapter Indentation Engine Basics -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This chapter will briefly cover how @ccmode{} indents lines of code. -It is helpful to understand the indentation model being used so that -you will know how to customize @ccmode{} for your personal coding -style. All the details are in @ref{Customizing Indentation}. - -@ccmode{} has an indentation engine that provides a flexible and -general mechanism for customizing indentation. When @ccmode{} indents -a line of code, it separates its calculations into two steps: - -@enumerate -@item -@cindex syntactic symbol -@cindex anchor position -It analyzes the line to determine its @dfn{syntactic symbol(s)} (the -kind of language construct it's looking at) and its @dfn{anchor -position} (the position earlier in the file that @ccmode{} will indent -the line relative to). The anchor position might be the location of -an opening brace in the previous line, for example. @xref{Syntactic -Analysis}. -@item -@cindex offsets -@cindex indentation offset specifications -It looks up the syntactic symbol(s) in the configuration to get the -corresponding @dfn{offset(s)}. The symbol @code{+}, which means -``indent this line one more level'' is a typical offset. @ccmode{} -then applies these offset(s) to the anchor position, giving the -indentation for the line. The different sorts of offsets are -described in @ref{c-offsets-alist}. -@end enumerate - -In exceptional circumstances, the syntax directed indentation -described here may be a nuisance rather than a help. You can disable -it by setting @code{c-syntactic-indentation} to @code{nil}. (To set -the variable interactively, @ref{Minor Modes}). - -@defopt c-syntactic-indentation -@vindex syntactic-indentation (c-) -When this is non-@code{nil} (which it is by default), the indentation -of code is done according to its syntactic structure. When it's -@code{nil}, every line is just indented to the same level as the -previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the -indentation in steps of @code{c-basic-offset}. The current style -(@pxref{Config Basics}) then has no effect on indentation, nor do any -of the variables associated with indentation, not even -@code{c-special-indent-hook}. -@end defopt - -@menu -* Syntactic Analysis:: -* Syntactic Symbols:: -* Indentation Calculation:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics -@comment node-name, next, previous, up -@section Syntactic Analysis -@cindex syntactic analysis -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex syntactic element -@cindex syntactic context -The first thing @ccmode{} does when indenting a line of code, is to -analyze the line, determining the @dfn{syntactic context} of the -(first) construct on that line. It's a list of @dfn{syntactic -elements}, where each syntactic element in turn is a list@footnote{In -@ccmode 5.28 and earlier, a syntactic element was a dotted pair; the -cons was the syntactic symbol and the cdr was the anchor position. -For compatibility's sake, the parameter passed to a line-up function -still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a -brief and typical example: - -@example -((defun-block-intro 1959)) -@end example - -@cindex syntactic symbol -@noindent -The first thing inside each syntactic element is always a -@dfn{syntactic symbol}. It describes the kind of construct that was -recognized, e.g. @code{statement}, @code{substatement}, -@code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols}, -for a complete list of currently recognized syntactic symbols and -their semantics. The remaining entries are various data associated -with the recognized construct - there might be zero or more. - -@cindex anchor position -Conceptually, a line of code is always indented relative to some -position higher up in the buffer (typically the indentation of the -previous line). That position is the @dfn{anchor position} in the -syntactic element. If there is an entry after the syntactic symbol in -the syntactic element list then it's either nil or that anchor position. - -Here is an example. Suppose we had the following code as the only thing -in a C++ buffer @footnote{The line numbers in this and future examples -don't actually appear in the buffer, of course!}: - -@example - 1: void swap( int& a, int& b ) - 2: @{ - 3: int tmp = a; - 4: a = b; - 5: b = tmp; - 6: @} -@end example - -@noindent -We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to -report what the syntactic analysis is for the current line: - -@table @asis -@item @kbd{C-c C-s} (@code{c-show-syntactic-information}) -@kindex C-c C-s -@findex c-show-syntactic-information -@findex show-syntactic-information (c-) -This command calculates the syntactic analysis of the current line and -displays it in the minibuffer. The command also highlights the anchor -position(s). -@end table - - Running this command on line 4 of this example, we'd see in the echo -area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the -analysis is inserted into the buffer as a comment on the current -line.}: - -@example -((statement 35)) -@end example - -@noindent -and the @samp{i} of @code{int} on line 3 would be highlighted. This -tells us that the line is a statement and it is indented relative to -buffer position 35, the highlighted position. If you were to move -point to line 3 and hit @kbd{C-c C-s}, you would see: - -@example -((defun-block-intro 29)) -@end example - -@noindent -This indicates that the @samp{int} line is the first statement in a top -level function block, and is indented relative to buffer position 29, -which is the brace just after the function header. - -Here's another example: - -@example - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end example - -@noindent -Hitting @kbd{C-c C-s} on line 4 gives us: - -@example -((substatement-open 46)) -@end example - -@cindex substatement -@cindex substatement block -@noindent -which tells us that this is a brace that @emph{opens} a substatement -block. @footnote{A @dfn{substatement} is the line after a -conditional statement, such as @code{if}, @code{else}, @code{while}, -@code{do}, @code{switch}, etc. A @dfn{substatement -block} is a brace block following one of these conditional statements.} - -@cindex comment-only line -Syntactic contexts can contain more than one element, and syntactic -elements need not have anchor positions. The most common example of -this is a @dfn{comment-only line}: - -@example - 1: void draw_list( List& drawables ) - 2: @{ - 3: // call the virtual draw() method on each element in list - 4: for( int i=0; i < drawables.count(), ++i ) - 5: @{ - 6: drawables[i].draw(); - 7: @} - 8: @} -@end example - -@noindent -Hitting @kbd{C-c C-s} on line 3 of this example gives: - -@example -((comment-intro) (defun-block-intro 46)) -@end example - -@noindent -and you can see that the syntactic context contains two syntactic -elements. Notice that the first element, @samp{(comment-intro)}, has no -anchor position. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics -@comment node-name, next, previous, up -@section Syntactic Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex syntactic symbols, brief list -@vindex c-offsets-alist -@vindex offsets-alist (c-) -This section is a complete list of the syntactic symbols which appear -in the @code{c-offsets-alist} style variable, along with brief -descriptions. The previous section (@pxref{Syntactic Analysis}) -states what syntactic symbols are and how the indentation engine uses -them. - -More detailed descriptions of these symbols, together with snippets of -source code to which they apply, appear in the examples in the -subsections below. Note that, in the interests of brevity, the anchor -position associated with most syntactic symbols is @emph{not} -specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent -line---this highlights the anchor position. - -@ssindex -open symbols -@ssindex -close symbols -@ssindex -block-intro symbols -The syntactic symbols which indicate brace constructs follow a general -naming convention. When a line begins with an open or close brace, -its syntactic symbol will contain the suffix @code{-open} or -@code{-close} respectively. The first line within the brace block -construct will contain the suffix @code{-block-intro}. - -@ssindex -intro symbols -@ssindex -cont symbols -In constructs which can span several lines, a distinction is usually -made between the first line that introduces the construct and the -lines that continue it. The syntactic symbols that indicate these -lines will contain the suffixes @code{-intro} or @code{-cont} -respectively. - -The best way to understand how all this works is by looking at some -examples. Remember that you can see the syntax of any source code -line by using @kbd{C-c C-s}. - -@table @code -@item string -Inside a multiline string. @ref{Literal Symbols}. -@item c -Inside a multiline C style block comment. @ref{Literal Symbols}. -@item defun-open -Brace that opens a top-level function definition. @ref{Function -Symbols}. -@item defun-close -Brace that closes a top-level function definition. @ref{Function -Symbols}. -@item defun-block-intro -The first line in a top-level defun. @ref{Function Symbols}. -@item class-open -Brace that opens a class definition. @ref{Class Symbols}. -@item class-close -Brace that closes a class definition. @ref{Class Symbols}. -@item inline-open -Brace that opens an in-class inline method. @ref{Class Symbols}. -@item inline-close -Brace that closes an in-class inline method. @ref{Class Symbols}. -@item func-decl-cont -The region between a function definition's argument list and the -function opening brace (excluding K&R argument declarations). In C, -you cannot put anything but whitespace and comments in this region, -however in C++ and Java, @code{throws} declarations and other things -can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not -@c go somewhere better?} -@item knr-argdecl-intro -First line of a K&R C argument declaration. @ref{K&R Symbols}. -@item knr-argdecl -Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}. -@item topmost-intro -The first line in a ``topmost'' definition. @ref{Function Symbols}. -@item topmost-intro-cont -Topmost definition continuation lines. This is only used in the parts -that aren't covered by other symbols such as @code{func-decl-cont} and -@code{knr-argdecl}. @ref{Function Symbols}. -@item annotation-top-cont -Topmost definition continuation lines where all previous items are -annotations. @ref{Java Symbols}. -@item member-init-intro -First line in a member initialization list. @ref{Class Symbols}. -@item member-init-cont -Subsequent member initialization list lines. @ref{Class Symbols}. -@item inher-intro -First line of a multiple inheritance list. @ref{Class Symbols}. -@item inher-cont -Subsequent multiple inheritance lines. @ref{Class Symbols}. -@item block-open -Statement block open brace. @ref{Literal Symbols}. -@item block-close -Statement block close brace. @ref{Conditional Construct Symbols}. -@item brace-list-open -Open brace of an enum or static array list. @ref{Brace List Symbols}. -@item brace-list-close -Close brace of an enum or static array list. @ref{Brace List Symbols}. -@item brace-list-intro -First line in an enum or static array list. @ref{Brace List Symbols}. -@item brace-list-entry -Subsequent lines in an enum or static array list. @ref{Brace List -Symbols}. -@item brace-entry-open -Subsequent lines in an enum or static array list where the line begins -with an open brace. @ref{Brace List Symbols}. -@item statement -A statement. @ref{Function Symbols}. -@item statement-cont -A continuation of a statement. @ref{Function Symbols}. -@item annotation-var-cont -A continuation of a statement where all previous items are -annotations. @ref{Java Symbols}. -@item statement-block-intro -The first line in a new statement block. @ref{Conditional Construct -Symbols}. -@item statement-case-intro -The first line in a case block. @ref{Switch Statement Symbols}. -@item statement-case-open -The first line in a case block that starts with a brace. @ref{Switch -Statement Symbols}. -@item substatement -The first line after a conditional or loop construct. -@ref{Conditional Construct Symbols}. -@item substatement-open -The brace that opens a substatement block. @ref{Conditional Construct -Symbols}. -@item substatement-label -The first line after a conditional or loop construct if it's a label. -@ref{Conditional Construct Symbols}. -@item case-label -A label in a @code{switch} block. @ref{Switch Statement Symbols}. -@item access-label -C++ access control label. @ref{Class Symbols}. -@item label -Any other label. @ref{Literal Symbols}. -@item do-while-closure -The @code{while} line that ends a @code{do}-@code{while} construct. -@ref{Conditional Construct Symbols}. -@item else-clause -The @code{else} line of an @code{if}-@code{else} construct. -@ref{Conditional Construct Symbols}. -@item catch-clause -The @code{catch} or @code{finally} (in Java) line of a -@code{try}-@code{catch} construct. @ref{Conditional Construct -Symbols}. -@item comment-intro -A line containing only a comment introduction. @ref{Literal Symbols}. -@item arglist-intro -The first line in an argument list. @ref{Paren List Symbols}. -@item arglist-cont -Subsequent argument list lines when no arguments follow on the same -line as the arglist opening paren. @ref{Paren List Symbols}. -@item arglist-cont-nonempty -Subsequent argument list lines when at least one argument follows on -the same line as the arglist opening paren. @ref{Paren List Symbols}. -@item arglist-close -The solo close paren of an argument list. @ref{Paren List Symbols}. -@item stream-op -Lines continuing a stream operator (C++ only). @ref{Literal -Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?} -@item inclass -The line is nested inside a class definition. @ref{Class Symbols}. -@item cpp-macro -The start of a preprocessor macro definition. @ref{Literal Symbols}. -@item cpp-define-intro -The first line inside a multiline preprocessor macro if -@code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro -Symbols}. -@item cpp-macro-cont -All lines inside multiline preprocessor macros if -@code{c-syntactic-indentation-in-macros} is @code{nil}. -@ref{Multiline Macro Symbols}. -@item friend -A C++ friend declaration. @ref{Class Symbols}. -@item objc-method-intro -The first line of an Objective-C method definition. @ref{Objective-C -Method Symbols}. -@item objc-method-args-cont -Lines continuing an Objective-C method definition. @ref{Objective-C -Method Symbols}. -@item objc-method-call-cont -Lines continuing an Objective-C method call. @ref{Objective-C Method -Symbols}. -@item extern-lang-open -Brace that opens an @code{extern} block (e.g. @code{extern "C" -@{...@}}). @ref{External Scope Symbols}. -@item extern-lang-close -Brace that closes an @code{extern} block. @ref{External Scope -Symbols}. -@item inextern-lang -Analogous to @code{inclass} syntactic symbol, but used inside -@code{extern} blocks. @ref{External Scope Symbols}. -@item namespace-open -@itemx namespace-close -@itemx innamespace -These are analogous to the three @code{extern-lang} symbols above, but -are returned for C++ namespace blocks. @ref{External Scope Symbols}. -@item module-open -@itemx module-close -@itemx inmodule -Analogous to the above, but for CORBA IDL @code{module} blocks. -@ref{External Scope Symbols}. -@item composition-open -@itemx composition-close -@itemx incomposition -Analogous to the above, but for CORBA CIDL @code{composition} blocks. -@ref{External Scope Symbols}. -@item template-args-cont -C++ template argument list continuations. @ref{Class Symbols}. -@item inlambda -Analogous to @code{inclass} syntactic symbol, but used inside lambda -(i.e. anonymous) functions. Only used in Pike mode. @ref{Statement -Block Symbols}. -@item lambda-intro-cont -Lines continuing the header of a lambda function, i.e. between the -@code{lambda} keyword and the function body. Only used in Pike mode. -@ref{Statement Block Symbols}. -@item inexpr-statement -A statement block inside an expression. The gcc C and C++ extension -for this is recognized. It's also used for the special functions that -take a statement block as an argument in Pike. @ref{Statement Block -Symbols}. -@item inexpr-class -A class definition inside an expression. This is used for anonymous -classes in Java. It's also used for anonymous array initializers in -Java. @ref{Java Symbols}. -@end table - -@menu -* Function Symbols:: -* Class Symbols:: -* Conditional Construct Symbols:: -* Switch Statement Symbols:: -* Brace List Symbols:: -* External Scope Symbols:: -* Paren List Symbols:: -* Literal Symbols:: -* Multiline Macro Symbols:: -* Objective-C Method Symbols:: -* Java Symbols:: -* Statement Block Symbols:: -* K&R Symbols:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Function Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This example shows a typical function declaration. - -@example - 1: void - 2: swap( int& a, int& b ) - 3: @{ - 4: int tmp = a; - 5: a = b; - 6: b = tmp; - 7: int ignored = - 8: a + b; - 9: @} -@end example - -@ssindex topmost-intro -@ssindex topmost-intro-cont -@ssindex defun-open -@ssindex defun-close -@ssindex defun-block-intro -Line 1 shows a @code{topmost-intro} since it is the first line that -introduces a top-level construct. Line 2 is a continuation of the -top-level construct introduction so it has the syntax -@code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is -the brace that opens a top-level function definition. Line 9 is the -corresponding -@code{defun-close} since it contains the brace that closes the top-level -function definition. Line 4 is a @code{defun-block-intro}, i.e. it is -the first line of a brace-block, enclosed in a -top-level function definition. - -@ssindex statement -@ssindex statement-cont -Lines 5, 6, and 7 are all given @code{statement} syntax since there -isn't much special about them. Note however that line 8 is given -@code{statement-cont} syntax since it continues the statement begun -on the previous line. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Class related Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here's an example which illustrates some C++ class syntactic symbols: - -@example - 1: class Bass - 2: : public Guitar, - 3: public Amplifiable - 4: @{ - 5: public: - 6: Bass() - 7: : eString( new BassString( 0.105 )), - 8: aString( new BassString( 0.085 )), - 9: dString( new BassString( 0.065 )), -10: gString( new BassString( 0.045 )) -11: @{ -12: eString.tune( 'E' ); -13: aString.tune( 'A' ); -14: dString.tune( 'D' ); -15: gString.tune( 'G' ); -16: @} -17: friend class Luthier; -18: @}; -@end example - -@ssindex class-open -@ssindex class-close -As in the previous example, line 1 has the @code{topmost-intro} syntax. -Here however, the brace that opens a C++ class definition on line 4 is -assigned the @code{class-open} syntax. Note that in C++, classes, -structs, and unions are essentially equivalent syntactically (and are -very similar semantically), so replacing the @code{class} keyword in the -example above with @code{struct} or @code{union} would still result in a -syntax of @code{class-open} for line 4 @footnote{This is the case even -for C and Objective-C. For consistency, structs in all supported -languages are syntactically equivalent to classes. Note however that -the keyword @code{class} is meaningless in C and Objective-C.}. -Similarly, line 18 is assigned @code{class-close} syntax. - -@ssindex inher-intro -@ssindex inher-cont -Line 2 introduces the inheritance list for the class so it is assigned -the @code{inher-intro} syntax, and line 3, which continues the -inheritance list is given @code{inher-cont} syntax. - -@ssindex access-label -@ssindex inclass -Hitting @kbd{C-c C-s} on line 5 shows the following analysis: - -@example -((inclass 58) (access-label 58)) -@end example - -@noindent -The primary syntactic symbol for this line is @code{access-label} as -this is a label keyword that specifies access protection in C++. However, -because this line is also a top-level construct inside a class -definition, the analysis actually shows two syntactic symbols. The -other syntactic symbol assigned to this line is @code{inclass}. -Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} -syntax: - -@example -((inclass 58) (topmost-intro 60)) -@end example - -@ssindex member-init-intro -@ssindex member-init-cont -Line 7 introduces a C++ member initialization list and as such is given -@code{member-init-intro} syntax. Note that in this case it is -@emph{not} assigned @code{inclass} since this is not considered a -top-level construct. Lines 8 through 10 are all assigned -@code{member-init-cont} since they continue the member initialization -list started on line 7. - -@cindex in-class inline methods -@ssindex inline-open -@ssindex inline-close -Line 11's analysis is a bit more complicated: - -@example -((inclass 58) (inline-open)) -@end example - -This line is assigned a syntax of both @code{inline-open} and -@code{inclass} because it opens an @dfn{in-class} C++ inline method -definition. This is distinct from, but related to, the C++ notion of an -inline function in that its definition occurs inside an enclosing class -definition, which in C++ implies that the function should be inlined. -However, if the definition of the @code{Bass} constructor appeared -outside the class definition, the construct would be given the -@code{defun-open} syntax, even if the keyword @code{inline} appeared -before the method name, as in: - -@example - 1: class Bass - 2: : public Guitar, - 3: public Amplifiable - 4: @{ - 5: public: - 6: Bass(); - 7: @}; - 8: - 9: inline -10: Bass::Bass() -11: : eString( new BassString( 0.105 )), -12: aString( new BassString( 0.085 )), -13: dString( new BassString( 0.065 )), -14: gString( new BassString( 0.045 )) -15: @{ -16: eString.tune( 'E' ); -17: aString.tune( 'A' ); -18: dString.tune( 'D' ); -19: gString.tune( 'G' ); -20: @} -@end example - -@ssindex friend -Returning to the previous example, line 16 is given @code{inline-close} -syntax, while line 12 is given @code{defun-block-open} syntax, and lines -13 through 15 are all given @code{statement} syntax. Line 17 is -interesting in that its syntactic analysis list contains three -elements: - -@example -((inclass 58) (topmost-intro 380) (friend)) -@end example - -The @code{friend} and @code{inline-open} syntactic symbols are -modifiers that do not have anchor positions. - -@ssindex template-args-cont -Template definitions introduce yet another syntactic symbol: - -@example - 1: ThingManager framework_callbacks; -@end example - -Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3 -are both analyzed as @code{template-args-cont} lines. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Conditional Construct Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here is a (totally contrived) example which illustrates how syntax is -assigned to various conditional constructs: - -@example - 1: void spam( int index ) - 2: @{ - 3: for( int i=0; i 0 ); -15: @} -@end example - -Only the lines that illustrate new syntactic symbols will be discussed. - -@ssindex substatement-open -@ssindex statement-block-intro -@ssindex block-close -Line 4 has a brace which opens a conditional's substatement block. It -is thus assigned @code{substatement-open} syntax, and since line 5 is -the first line in the substatement block, it is assigned -@code{statement-block-intro} syntax. Line 10 contains the brace -that closes the inner substatement block, and is therefore given the -syntax @code{block-close}@footnote{@code{block-open} is used only for -``free-standing'' blocks, and is somewhat rare (@pxref{Literal -Symbols} for an example.)}. Line 13 is treated the same way. - -@ssindex substatement -Lines 6 and 9 are also substatements of conditionals, but since they -don't start blocks they are given @code{substatement} syntax -instead of @code{substatement-open}. - -@ssindex substatement-label -Line 8 contains a label, which is normally given @code{label} syntax. -This one is however a bit special since it's between a conditional and -its substatement. It's analyzed as @code{substatement-label} to let you -handle this rather odd case differently from normal labels. - -@ssindex else-clause -@ssindex catch-clause -Line 7 start with an @code{else} that matches the @code{if} statement on -line 5. It is therefore given the @code{else-clause} syntax and is -anchored on the matching @code{if}. The @code{try}-@code{catch} -constructs in C++ and Java are treated this way too, except that -@code{catch} and (in Java) @code{finally}, are marked with -@code{catch-clause}. - -@ssindex do-while-closure -The @code{while} construct on line 14 that closes a @code{do} -conditional is given the special syntax @code{do-while-closure} if it -appears on a line by itself. Note that if the @code{while} appeared on -the same line as the preceding close brace, that line would still have -@code{block-close} syntax. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Switch Statement Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Switch statements have their own set of syntactic symbols. Here's an -example: - -@example - 1: void spam( enum Ingredient i ) - 2: @{ - 3: switch( i ) @{ - 4: case Ham: - 5: be_a_pig(); - 6: break; - 7: case Salt: - 8: drink_some_water(); - 9: break; -10: default: -11: @{ -12: what_is_it(); -13: break; -14: @} -15: @} -14: @} -@end example - -@ssindex case-label -@ssindex statement-case-intro -@ssindex statement-case-open -Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, -while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 -is treated slightly differently since it contains a brace that opens a -block --- it is given @code{statement-case-open} syntax. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Brace List Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex brace lists -There are a set of syntactic symbols that are used to recognize -constructs inside of brace lists. A brace list is defined as an -@code{enum} or aggregate initializer list, such as might statically -initialize an array of structs. The three special aggregate constructs -in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as -brace lists too. An example: - -@example - 1: static char* ingredients[] = - 2: @{ - 3: "Ham", - 4: "Salt", - 5: NULL - 6: @}; -@end example - -@ssindex brace-list-open -@ssindex brace-list-intro -@ssindex brace-list-close -@ssindex brace-list-entry -Following convention, line 2 in this example is assigned -@code{brace-list-open} syntax, and line 3 is assigned -@code{brace-list-intro} syntax. Likewise, line 6 is assigned -@code{brace-list-close} syntax. Lines 4 and 5 however, are assigned -@code{brace-list-entry} syntax, as would all subsequent lines in this -initializer list. - -@ssindex brace-entry-open -Your static initializer might be initializing nested structures, for -example: - -@example - 1: struct intpairs[] = - 2: @{ - 3: @{ 1, 2 @}, - 4: @{ - 5: 3, - 6: 4 - 7: @} - 8: @{ 1, - 9: 2 @}, -10: @{ 3, 4 @} -11: @}; -@end example - -Here, you've already seen the analysis of lines 1, 2, 3, and 11. On -line 4, things get interesting; this line is assigned -@code{brace-entry-open} syntactic symbol because it's a bracelist entry -line that starts with an open brace. Lines 5 and 6 (and line 9) are -pretty standard, and line 7 is a @code{brace-list-close} as you'd -expect. Once again, line 8 is assigned as @code{brace-entry-open} as is -line 10. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection External Scope Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -External language definition blocks also have their own syntactic -symbols. In this example: - -@example - 1: extern "C" - 2: @{ - 3: int thing_one( int ); - 4: int thing_two( double ); - 5: @} -@end example - -@ssindex extern-lang-open -@ssindex extern-lang-close -@ssindex inextern-lang -@ssindex inclass -@noindent -line 2 is given the @code{extern-lang-open} syntax, while line 5 is given -the @code{extern-lang-close} syntax. The analysis for line 3 yields: - -@example -((inextern-lang) (topmost-intro 14)) -@end example - -@noindent -where @code{inextern-lang} is a modifier similar in purpose to -@code{inclass}. - -There are various other top level blocks like @code{extern}, and they -are all treated in the same way except that the symbols are named after -the keyword that introduces the block. E.g. C++ namespace blocks get -the three symbols @code{namespace-open}, @code{namespace-close} and -@code{innamespace}. The currently recognized top level blocks are: - -@table @asis -@item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang} -@code{extern} blocks in C and C++.@footnote{These should logically be -named @code{extern-open}, @code{extern-close} and @code{inextern}, but -that isn't the case for historical reasons.} - -@item @code{namespace-open}, @code{namespace-close}, @code{innamespace} -@ssindex namespace-open -@ssindex namespace-close -@ssindex innamespace -@code{namespace} blocks in C++. - -@item @code{module-open}, @code{module-close}, @code{inmodule} -@ssindex module-open -@ssindex module-close -@ssindex inmodule -@code{module} blocks in CORBA IDL. - -@item @code{composition-open}, @code{composition-close}, @code{incomposition} -@ssindex composition-open -@ssindex composition-close -@ssindex incomposition -@code{composition} blocks in CORBA CIDL. -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Parenthesis (Argument) List Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -A number of syntactic symbols are associated with parenthesis lists, -a.k.a argument lists, as found in function declarations and function -calls. This example illustrates these: - -@example - 1: void a_function( int line1, - 2: int line2 ); - 3: - 4: void a_longer_function( - 5: int line1, - 6: int line2 - 7: ); - 8: - 9: void call_them( int line1, int line2 ) -10: @{ -11: a_function( -12: line1, -13: line2 -14: ); -15: -16: a_longer_function( line1, -17: line2 ); -18: @} -@end example - -@ssindex arglist-intro -@ssindex arglist-close -Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are -the first line following the open parenthesis, and lines 7 and 14 are -assigned @code{arglist-close} syntax since they contain the parenthesis -that closes the argument list. - -@ssindex arglist-cont-nonempty -@ssindex arglist-cont -Lines that continue argument lists can be assigned one of two syntactic -symbols. For example, Lines 2 and 17 -are assigned @code{arglist-cont-nonempty} syntax. What this means -is that they continue an argument list, but that the line containing the -parenthesis that opens the list is @emph{not empty} following the open -parenthesis. Contrast this against lines 6 and 13 which are assigned -@code{arglist-cont} syntax. This is because the parenthesis that opens -their argument lists is the last character on that line. - -Syntactic elements with @code{arglist-intro}, -@code{arglist-cont-nonempty}, and @code{arglist-close} contain two -buffer positions: the anchor position (the beginning of the -declaration or statement) and the position of the open parenthesis. -The latter position can be used in a line-up function (@pxref{Line-Up -Functions}). - -Note that there is no @code{arglist-open} syntax. This is because any -parenthesis that opens an argument list, appearing on a separate line, -is assigned the @code{statement-cont} syntax instead. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Comment String Label and Macro Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -A few miscellaneous syntactic symbols that haven't been previously -covered are illustrated by this C++ example: - -@example - 1: void Bass::play( int volume ) - 2: const - 3: @{ - 4: /* this line starts a multiline - 5: * comment. This line should get `c' syntax */ - 6: - 7: char* a_multiline_string = "This line starts a multiline \ - 8: string. This line should get `string' syntax."; - 9: -10: note: -11: @{ -12: #ifdef LOCK -13: Lock acquire(); -14: #endif // LOCK -15: slap_pop(); -16: cout << "I played " -17: << "a note\n"; -18: @} -19: @} -@end example - -The lines to note in this example include: - -@itemize @bullet -@item -@ssindex func-decl-cont -Line 2 is assigned the @code{func-decl-cont} syntax. - -@item -@ssindex comment-intro -Line 4 is assigned both @code{defun-block-intro} @emph{and} -@code{comment-intro} syntax. A syntactic element with -@code{comment-intro} has no anchor point --- It is always accompanied -by another syntactic element which does have one. - -@item -@ssindex c -Line 5 is assigned @code{c} syntax. - -@item -@cindex syntactic whitespace -Line 6 which, even though it contains nothing but whitespace, is -assigned @code{defun-block-intro}. Note that the appearance of the -comment on lines 4 and 5 do not cause line 6 to be assigned -@code{statement} syntax because comments are considered to be -@dfn{syntactic whitespace}, which are ignored when analyzing -code. - -@item -@ssindex string -Line 8 is assigned @code{string} syntax. - -@item -@ssindex label -Line 10 is assigned @code{label} syntax. - -@item -@ssindex block-open -Line 11 is assigned @code{block-open} as well as @code{statement} -syntax. A @code{block-open} syntactic element doesn't have an anchor -position, since it always appears with another syntactic element which -does have one. - -@item -@ssindex cpp-macro -Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the -normal syntactic symbols (@code{statement-block-intro} and -@code{statement}, respectively). Normally @code{cpp-macro} is -configured to cancel out the normal syntactic context to make all -preprocessor directives stick to the first column, but that's easily -changed if you want preprocessor directives to be indented like the rest -of the code. Like @code{comment-intro}, a syntactic element with -@code{cpp-macro} doesn't contain an anchor position. - -@item -@ssindex stream-op -Line 17 is assigned @code{stream-op} syntax. -@end itemize - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Multiline Macro Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex multiline macros -@cindex syntactic whitespace -@ssindex cpp-define-intro -@ssindex cpp-macro-cont -Multiline preprocessor macro definitions are normally handled just like -other code, i.e. the lines inside them are indented according to the -syntactic analysis of the preceding lines inside the macro. The first -line inside a macro definition (i.e. the line after the starting line of -the cpp directive itself) gets @code{cpp-define-intro}. In this example: - -@example - 1: #define LIST_LOOP(cons, listp) \ - 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \ - 3: if (!CONSP (cons)) \ - 4: signal_error ("Invalid list format", listp); \ - 5: else -@end example - -@noindent -line 1 is given the syntactic symbol @code{cpp-macro}. The first line -of a cpp directive is always given that symbol. Line 2 is given -@code{cpp-define-intro}, so that you can give the macro body as a whole -some extra indentation. Lines 3 through 5 are then analyzed as normal -code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause} -on line 5. - -The syntactic analysis inside macros can be turned off with -@code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In -that case, lines 2 through 5 would all be given @code{cpp-macro-cont} -with an anchor position pointing to the @code{#} which starts the cpp -directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed -macros.}. - -@xref{Custom Macros}, for more info about the treatment of macros. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Objective-C Method Symbols, Java Symbols, Multiline Macro Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Objective-C Method Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -In Objective-C buffers, there are three additional syntactic symbols -assigned to various message calling constructs. Here's an example -illustrating these: - -@example - 1: - (void)setDelegate:anObject - 2: withStuff:stuff - 3: @{ - 4: [delegate masterWillRebind:self - 5: toDelegate:anObject - 6: withExtraStuff:stuff]; - 7: @} -@end example - -@ssindex objc-method-intro -@ssindex objc-method-args-cont -@ssindex objc-method-call-cont -Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is -assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both -assigned @code{objc-method-call-cont} syntax. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Java Symbols, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Java Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Java has a concept of anonymous classes which can look something like -this: - -@example - 1: @@Test - 2: public void watch(Observable o) @{ - 3: @@NonNull - 4: Observer obs = new Observer() @{ - 5: public void update(Observable o, Object arg) @{ - 6: history.addElement(arg); - 7: @} - 8: @}; - 9: o.addObserver(obs); - 10: @} -@end example - -@ssindex inexpr-class -The brace following the @code{new} operator opens the anonymous class. -Lines 5 and 8 are assigned the @code{inexpr-class} syntax, besides the -@code{inclass} symbol used in normal classes. Thus, the class will be -indented just like a normal class, with the added indentation given to -@code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't -have an anchor position. - -@ssindex annotation-top-cont -@ssindex annotation-var-cont -Line 2 is assigned the @code{annotation-top-cont} syntax, due to it being a -continuation of a topmost introduction with an annotation symbol preceding -the current line. Similarly, line 4 is assigned the @code{annotation-var-cont} -syntax due to it being a continuation of a variable declaration where preceding -the declaration is an annotation. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Statement Block Symbols, K&R Symbols, Java Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Statement Block Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -There are a few occasions where a statement block might be used inside -an expression. One is in C or C++ code using the gcc extension for -this, e.g: - -@example - 1: int res = (@{ - 2: int y = foo (); int z; - 3: if (y > 0) z = y; else z = - y; - 4: z; - 5: @}); -@end example - -@ssindex inexpr-statement -Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the -symbols they'd get in a normal block. Therefore, the indentation put on -@code{inexpr-statement} is added to the normal statement block -indentation. An @code{inexpr-statement} syntactic element doesn't -contain an anchor position. - -In Pike code, there are a few other situations where blocks occur inside -statements, as illustrated here: - -@example - 1: array itgob() - 2: @{ - 3: string s = map (backtrace()[-2][3..], - 4: lambda - 5: (mixed arg) - 6: @{ - 7: return sprintf ("%t", arg); - 8: @}) * ", " + "\n"; - 9: return catch @{ -10: write (s + "\n"); -11: @}; -12: @} -@end example - -@ssindex inlambda -@ssindex lambda-intro-cont -Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes -by the @code{lambda} keyword. If the function argument list is put -on a line of its own, as in line 5, it gets the @code{lambda-intro-cont} -syntax. The function body is handled as an inline method body, with the -addition of the @code{inlambda} syntactic symbol. This means that line -6 gets @code{inlambda} and @code{inline-open}, and line 8 gets -@code{inline-close}@footnote{You might wonder why it doesn't get -@code{inlambda} too. It's because the closing brace is relative to the -opening brace, which stands on its own line in this example. If the -opening brace was hanging on the previous line, then the closing brace -would get the @code{inlambda} syntax too to be indented correctly.}. - -@ssindex inexpr-statement -On line 9, @code{catch} is a special function taking a statement block -as its argument. The block is handled as an in-expression statement -with the @code{inexpr-statement} syntax, just like the gcc extended C -example above. The other similar special function, @code{gauge}, is -handled like this too. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node K&R Symbols, , Statement Block Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection K&R Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ssindex knr-argdecl-intro -@ssindex knr-argdecl -Two other syntactic symbols can appear in old style, non-prototyped C -code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}: - -@example - 1: int add_three_integers(a, b, c) - 2: int a; - 3: int b; - 4: int c; - 5: @{ - 6: return a + b + c; - 7: @} -@end example - -Here, line 2 is the first line in an argument declaration list and so is -given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines -(i.e. lines 3 and 4 in this example), are given @code{knr-argdecl} -syntax. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics -@comment node-name, next, previous, up -@section Indentation Calculation -@cindex indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Indentation for a line is calculated from the syntactic context -(@pxref{Syntactic Analysis}). - -First, a buffer position is found whose column will be the base for the -indentation calculation. It's the anchor position in the first -syntactic element that provides one that is used. If no syntactic -element has an anchor position then column zero is used. - -Second, the syntactic symbols in each syntactic element are looked up -in the @code{c-offsets-alist} style variable -(@pxref{c-offsets-alist}), which is an association list of syntactic -symbols and the offsets to apply for those symbols. These offsets are -added together with the base column to produce the new indentation -column. - -Let's use our two code examples above to see how this works. Here is -our first example again: - -@example - 1: void swap( int& a, int& b ) - 2: @{ - 3: int tmp = a; - 4: a = b; - 5: b = tmp; - 6: @} -@end example - -Let's say point is on line 3 and we hit the @key{TAB} key to reindent -the line. The syntactic context for that line is: - -@example -((defun-block-intro 29)) -@end example - -@noindent -Since buffer position 29 is the first and only anchor position in the -list, @ccmode{} goes there and asks for the current column. This brace -is in column zero, so @ccmode{} uses @samp{0} as the base column. - -Next, @ccmode{} looks up @code{defun-block-intro} in the -@code{c-offsets-alist} style variable. Let's say it finds the value -@samp{4}; it adds this to the base column @samp{0}, yielding a running -total indentation of 4 spaces. - -Since there is only one syntactic element on the list for this line, -indentation calculation is complete, and the total indentation for the -line is 4 spaces. - -Here's another example: - -@example - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end example - -If we were to hit @kbd{TAB} on line 4 in the above example, the same -basic process is performed, despite the differences in the syntactic -context. The context for this line is: - -@example -((substatement-open 46)) -@end example - -Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in -@code{if} on line 3. This character is in the fourth column on that -line so the base column is @samp{4}. Then @ccmode{} looks up the -@code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it -finds the value @samp{4}. It's added with the base column and yields an -indentation for the line of 8 spaces. - -Simple, huh? - -Actually, it's a bit more complicated than that since the entries on -@code{c-offsets-alist} can be much more than plain offsets. -@xref{c-offsets-alist}, for the full story. - -Anyway, the mode usually just does The Right Thing without you having to -think about it in this much detail. But when customizing indentation, -it's helpful to understand the general indentation model being used. - -As you configure @ccmode{}, you might want to set the variable -@code{c-echo-syntactic-information-p} to non-@code{nil} so that the -syntactic context and calculated offset always is echoed in the -minibuffer when you hit @kbd{TAB}. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top -@comment node-name, next, previous, up -@chapter Customizing Indentation -@cindex customization, indentation -@cindex indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The principal variable for customizing indentation is the style -variable @code{c-offsets-alist}, which gives an @dfn{offset} (an -indentation rule) for each syntactic symbol. Its structure and -semantics are completely described in @ref{c-offsets-alist}. The -various ways you can set the variable, including the use of the -@ccmode{} style system, are described in @ref{Config Basics} and its -sections, in particular @ref{Style Variables}. - -The simplest and most used kind of ``offset'' setting in -@code{c-offsets-alist} is in terms of multiples of -@code{c-basic-offset}: - -@defopt c-basic-offset -@vindex basic-offset (c-) -This style variable holds the basic offset between indentation levels. -It's factory default is 4, but all the built-in styles set it -themselves, to some value between 2 (for @code{gnu} style) and 8 (for -@code{bsd}, @code{linux}, and @code{python} styles). -@end defopt - -The most flexible ``offset'' setting you can make in -@code{c-offsets-alist} is a line-up function (or even a list of them), -either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one -you write yourself (@pxref{Custom Line-Up}). - -Finally, in @ref{Other Indentation} you'll find the tool of last -resort: a hook which is called after a line has been indented. You -can install functions here to make ad-hoc adjustments to any line's -indentation. - -@menu -* c-offsets-alist:: -* Interactive Customization:: -* Line-Up Functions:: -* Custom Line-Up:: -* Other Indentation:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation -@comment node-name, next, previous, up -@section c-offsets-alist -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This section explains the structure and semantics of the style -variable @code{c-offsets-alist}, the principal variable for configuring -indentation. Details of how to set it up, and its relationship to -@ccmode{}'s style system are given in @ref{Style Variables}. - -@defopt c-offsets-alist -@vindex offsets-alist (c-) -This is an alist which associates an offset with each syntactic -symbol. This @dfn{offset} is a rule specifying how to indent a line -whose syntactic context matches the symbol. @xref{Syntactic -Analysis}. - -Note that the buffer-local binding of this alist in a @ccmode{} buffer -contains an entry for @emph{every} syntactic symbol. Its global -binding and its settings within style specifications usually contain -only a few entries. @xref{Style Variables}. - -The offset specification associated with any particular syntactic -symbol can be an integer, a variable name, a vector, a function or -lambda expression, a list, or one of the following special symbols: -@code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The -meanings of these values are described in detail below. - -Here is an example fragment of a @code{c-offsets-alist}, showing some -of these kinds of offsets: - -@example -((statement . 0) - (substatement . +) - (cpp-macro . [0]) - (topmost-intro-cont . c-lineup-topmost-intro-cont) - (statement-block-intro . (add c-lineup-whitesmith-in-block - c-indent-multi-line-block)) - @dots{} -@*) -@end example -@end defopt - -@deffn Command c-set-offset (@kbd{C-c C-o}) -@findex set-offset (c-) -@kindex C-c C-o -This command changes the entry for a syntactic symbol in the current -binding of @code{c-offsets-alist}, or it inserts a new entry if there -isn't already one for that syntactic symbol. - -You can use @code{c-set-offsets} interactively within a @ccmode{} -buffer to make experimental changes to your indentation settings. -@kbd{C-c C-o} prompts you for the syntactic symbol to change -(defaulting to that of the current line) and the new offset -(defaulting to the current offset). - -@code{c-set-offsets} takes two arguments when used programmatically: -@var{symbol}, the syntactic element symbol to change and @var{offset}, -the new offset for that syntactic element. You can call the command -in your @file{.emacs} to change the global binding of -@code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a -hook function to make changes from the current style. @ccmode{} -itself uses this function when initializing styles. -@end deffn - -@cindex offset specification -The ``offset specifications'' in @code{c-offsets-alist} can be any of -the following: - -@table @asis -@item An integer -The integer specifies a relative offset. All relative -offsets@footnote{The syntactic context @code{@w{((defun-block-intro -2724) (comment-intro))}} would likely have two relative offsets.} will -be added together and used to calculate the indentation relative to an -anchor position earlier in the buffer. @xref{Indentation -Calculation}, for details. Most of the time, it's probably better to -use one of the special symbols like @code{+} than an integer (apart -from zero). - -@item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/} -These special symbols describe a relative offset in multiples of -@code{c-basic-offset}: - -By defining a style's indentation in terms of @code{c-basic-offset}, -you can change the amount of whitespace given to an indentation level -while maintaining the same basic shape of your code. Here are the -values that the special symbols correspond to: - -@table @code -@item + -@code{c-basic-offset} times 1 -@item - -@code{c-basic-offset} times -1 -@item ++ -@code{c-basic-offset} times 2 -@item -- -@code{c-basic-offset} times -2 -@item * -@code{c-basic-offset} times 0.5 -@item / -@code{c-basic-offset} times -0.5 -@end table - -@item A vector -The first element of the vector, an integer, sets the absolute -indentation column. This will override any previously calculated -indentation, but won't override relative indentation calculated from -syntactic elements later on in the syntactic context of the line being -indented. @xref{Indentation Calculation}. Any elements in the vector -beyond the first will be ignored. - -@item A function or lambda expression -The function will be called and its return value will in turn be -evaluated as an offset specification. Functions are useful when more -context than just the syntactic symbol is needed to get the desired -indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for -details about them. - -@item A symbol with a variable binding -If the symbol also has a function binding, the function takes -precedence over the variable. Otherwise the value of the variable is -used. It must be an integer (which is used as relative offset) or a -vector (an absolute offset). - -@item A list -The offset can also be a list containing several offset -specifications; these are evaluated recursively and combined. A list -is typically only useful when some of the offsets are line-up -functions. A common strategy is calling a sequence of functions in -turn until one of them recognizes that it is appropriate for the -source line and returns a non-@code{nil} value. - -@code{nil} values are always ignored when the offsets are combined. -The first element of the list specifies the method of combining the -non-@code{nil} offsets from the remaining elements: - -@table @code -@item first -Use the first offset that doesn't evaluate to @code{nil}. Subsequent -elements of the list don't get evaluated. -@item min -Use the minimum of all the offsets. All must be either relative or -absolute - they can't be mixed. -@item max -Use the maximum of all the offsets. All must be either relative or -absolute - they can't be mixed. -@item add -Add all the evaluated offsets together. Exactly one of them may be -absolute, in which case the result is absolute. Any relative offsets -that preceded the absolute one in the list will be ignored in that case. -@end table - -As a compatibility measure, if the first element is none of the above -then it too will be taken as an offset specification and the whole list -will be combined according to the method @code{first}. -@end table - -@vindex c-strict-syntax-p -@vindex strict-syntax-p (c-) -If an offset specification evaluates to @code{nil}, then a relative -offset of 0 (zero) is used@footnote{There is however a variable -@code{c-strict-syntax-p} that when set to non-@code{nil} will cause an -error to be signaled in that case. It's now considered obsolete since -it doesn't work well with some of the alignment functions that return -@code{nil} instead of zero. You should therefore leave -@code{c-strict-syntax-p} set to @code{nil}.}. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation -@comment node-name, next, previous, up -@section Interactive Customization -@cindex customization, interactive -@cindex interactive customization -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -As an example of how to customize indentation, let's change the -style of this example@footnote{In this and subsequent examples, the -original code is formatted using the @samp{gnu} style unless otherwise -indicated. @xref{Styles}.}: - -@example -@group - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end group -@end example - -@noindent -to: - -@example -@group - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end group -@end example - -In other words, we want to change the indentation of braces that open a -block following a condition so that the braces line up under the -conditional, instead of being indented. Notice that the construct we -want to change starts on line 4. To change the indentation of a line, -we need to see which syntactic symbols affect the offset calculations -for that line. Hitting @kbd{C-c C-s} on line 4 yields: - -@example -((substatement-open 44)) -@end example - -@noindent -so we know that to change the offset of the open brace, we need to -change the indentation for the @code{substatement-open} syntactic -symbol. - -To do this interactively, just hit @kbd{C-c C-o}. This prompts -you for the syntactic symbol to change, providing a reasonable default. -In this case, the default is @code{substatement-open}, which is just the -syntactic symbol we want to change! - -After you hit return, @ccmode{} will then prompt you for the new -offset value, with the old value as the default. The default in this -case is @samp{+}, but we want no extra indentation so enter -@samp{0} and @kbd{RET}. This will associate the offset 0 with the -syntactic symbol @code{substatement-open}. - -To check your changes quickly, just hit @kbd{C-c C-q} -(@code{c-indent-defun}) to reindent the entire function. The example -should now look like: - -@example -@group - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end group -@end example - -Notice how just changing the open brace offset on line 4 is all we -needed to do. Since the other affected lines are indented relative to -line 4, they are automatically indented the way you'd expect. For more -complicated examples, this might not always work. The general approach -to take is to always start adjusting offsets for lines higher up in the -file, then reindent and see if any following lines need further -adjustments. - -@c Move this bit to "Styles" (2005/10/7) -@deffn Command c-set-offset symbol offset -@findex set-offset (c-) -@kindex C-c C-o -This is the command bound to @kbd{C-c C-o}. It provides a convenient -way to set offsets on @code{c-offsets-alist} both interactively (see -the example above) and from your mode hook. - -It takes two arguments when used programmatically: @var{symbol} is the -syntactic element symbol to change and @var{offset} is the new offset -for that syntactic element. -@end deffn -@c End of MOVE THIS BIT. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation -@comment node-name, next, previous, up -@section Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex line-up function -@cindex indentation function -Often there are cases when a simple offset setting on a syntactic -symbol isn't enough to get the desired indentation---for example, you -might want to line up a closing parenthesis with the matching opening -one rather than indenting relative to its ``anchor point''. @ccmode{} -provides this flexibility with @dfn{line-up functions}. - -The way you associate a line-up function with a syntactic symbol is -described in @ref{c-offsets-alist}. @ccmode{} comes with many -predefined line-up functions for common situations. If none of these -does what you want, you can write your own. @xref{Custom Line-Up}. -Sometimes, it is easier to tweak the standard indentation by adding a -function to @code{c-special-indent-hook} (@pxref{Other Indentation}). - -The line-up functions haven't been adapted for AWK buffers or tested -with them. Some of them might work serendipitously. There shouldn't be -any problems writing custom line-up functions for AWK mode. - -The calling convention for line-up functions is described fully in -@ref{Custom Line-Up}. Roughly speaking, the return value is either an -offset itself (such as @code{+} or @code{[0]}) or it's @code{nil}, -meaning ``this function is inappropriate in this case - try a -different one''. @xref{c-offsets-alist}. - -The subsections below describe all the standard line-up functions, -categorized by the sort of token the lining-up centers around. For -each of these functions there is a ``works with'' list that indicates -which syntactic symbols the function is intended to be used with. - -@macro workswith -@emph{Works with:@ } -@end macro -@ifinfo -@unmacro workswith -@macro workswith -Works with: -@end macro -@end ifinfo - -@macro sssTBasicOffset -<--> @i{c-basic-offset}@c -@end macro - -@macro sssTsssTBasicOffset -<--><--> @i{c-basic-offset}@c -@end macro - -@macro hereFn{func} -<- @i{\func\}@c -@end macro - -@c The TeX backend seems to insert extra spaces around the argument. :P -@iftex -@unmacro hereFn -@macro hereFn{func} -<-@i{\func\}@c -@end macro -@end iftex - -@menu -* Brace/Paren Line-Up:: -* List Line-Up:: -* Operator Line-Up:: -* Comment Line-Up:: -* Misc Line-Up:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions -@comment node-name, next, previous, up -@subsection Brace and Parenthesis Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here calculate the indentation for braces, -parentheses and statements within brace blocks. - -@defun c-lineup-close-paren -@findex lineup-close-paren (c-) -Line up the closing paren under its corresponding open paren if the -open paren is followed by code. If the open paren ends its line, no -indentation is added. E.g: - -@example -@group -main (int, - char ** - ) @hereFn{c-lineup-close-paren} -@end group -@end example - -@noindent -and - -@example -@group -main ( - int, char ** -) @hereFn{c-lineup-close-paren} -@end group -@end example - -As a special case, if a brace block is opened at the same line as the -open parenthesis of the argument list, the indentation is -@code{c-basic-offset} instead of the open paren column. See -@code{c-lineup-arglist} for further discussion of this ``DWIM'' measure. - -@workswith All @code{*-close} symbols. -@end defun - -@comment ------------------------------------------------------------ - -@anchor{c-lineup-arglist-close-under-paren} -@defun c-lineup-arglist-close-under-paren -@findex lineup-arglist-close-under-paren (c-) -Set your @code{arglist-close} syntactic symbol to this line-up function -so that parentheses that close argument lists will line up under the -parenthesis that opened the argument list. It can also be used with -@code{arglist-cont} and @code{arglist-cont-nonempty} to line up all -lines inside a parenthesis under the open paren. - -As a special case, if a brace block is opened at the same line as the -open parenthesis of the argument list, the indentation is -@code{c-basic-offset} only. See @code{c-lineup-arglist} for further -discussion of this ``DWIM'' measure. - -@workswith Almost all symbols, but are typically most useful on -@code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and -@code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-indent-one-line-block -@findex indent-one-line-block (c-) -Indent a one line block @code{c-basic-offset} extra. E.g: - -@example -@group -if (n > 0) - @{m+=n; n=0;@} @hereFn{c-indent-one-line-block} -@sssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -if (n > 0) -@{ @hereFn{c-indent-one-line-block} - m+=n; n=0; -@} -@end group -@end example - -The block may be surrounded by any kind of parenthesis characters. -@code{nil} is returned if the line doesn't start with a one line block, -which makes the function usable in list expressions. - -@workswith Almost all syntactic symbols, but most useful on the -@code{-open} symbols. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-indent-multi-line-block -@findex indent-multi-line-block (c-) -Indent a multiline block @code{c-basic-offset} extra. E.g: - -@example -@group -int *foo[] = @{ - NULL, - @{17@}, @hereFn{c-indent-multi-line-block} -@end group -@end example - -@noindent -and - -@example -@group -int *foo[] = @{ - NULL, - @{ @hereFn{c-indent-multi-line-block} - 17 - @}, - @sssTBasicOffset{} -@end group -@end example - -The block may be surrounded by any kind of parenthesis characters. -@code{nil} is returned if the line doesn't start with a multiline -block, which makes the function usable in list expressions. - -@workswith Almost all syntactic symbols, but most useful on the -@code{-open} symbols. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-runin-statements -@findex lineup-runin-statements (c-) -Line up statements for coding standards which place the first statement -in a block on the same line as the block opening brace@footnote{Run-in -style doesn't really work too well. You might need to write your own -custom line-up functions to better support this style.}. E.g: - -@example -@group -int main() -@{ puts ("Hello!"); - return 0; @hereFn{c-lineup-runin-statements} -@} -@end group -@end example - -If there is no statement after the opening brace to align with, -@code{nil} is returned. This makes the function usable in list -expressions. - -@workswith The @code{statement} syntactic symbol. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-inexpr-block -@findex lineup-inexpr-block (c-) -This can be used with the in-expression block symbols to indent the -whole block to the column where the construct is started. E.g. for Java -anonymous classes, this lines up the class under the @samp{new} keyword, -and in Pike it lines up the lambda function body under the @samp{lambda} -keyword. Returns @code{nil} if the block isn't part of such a -construct. - -@workswith @code{inlambda}, @code{inexpr-statement}, -@code{inexpr-class}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-after-whitesmith-blocks -@findex lineup-after-whitesmith-blocks (c-) -Compensate for Whitesmith style indentation of blocks. Due to the way -@ccmode{} calculates anchor positions for normal lines inside blocks, -this function is necessary for those lines to get correct Whitesmith -style indentation. Consider the following examples: - -@example -@group -int foo() - @{ - a; - x; @hereFn{c-lineup-after-whitesmith-blocks} -@end group -@end example - -@example -@group -int foo() - @{ - @{ - a; - @} - x; @hereFn{c-lineup-after-whitesmith-blocks} -@end group -@end example - -The fact that the line with @code{x} is preceded by a Whitesmith style -indented block in the latter case and not the first should not affect -its indentation. But since CC Mode in cases like this uses the -indentation of the preceding statement as anchor position, the @code{x} -would in the second case be indented too much if the offset for -@code{statement} was set simply to zero. - -This lineup function corrects for this situation by detecting if the -anchor position is at an open paren character. In that case, it instead -indents relative to the surrounding block just like -@code{c-lineup-whitesmith-in-block}. - -@workswith @code{brace-list-entry}, @code{brace-entry-open}, -@code{statement}, @code{arglist-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-whitesmith-in-block -@findex lineup-whitesmith-in-block (c-) -Line up lines inside a block in Whitesmith style. It's done in a way -that works both when the opening brace hangs and when it doesn't. E.g: - -@example -@group -something - @{ - foo; @hereFn{c-lineup-whitesmith-in-block} - @} -@end group -@end example - -@noindent -and - -@example -@group -something @{ - foo; @hereFn{c-lineup-whitesmith-in-block} - @} -@sssTBasicOffset{} -@end group -@end example - -In the first case the indentation is kept unchanged, in the second -@code{c-basic-offset} is added. - -@workswith @code{defun-close}, @code{defun-block-intro}, -@code{inline-close}, @code{block-close}, @code{brace-list-close}, -@code{brace-list-intro}, @code{statement-block-intro}, -@code{arglist-intro}, @code{arglist-cont-nonempty}, -@code{arglist-close}, and all @code{in*} symbols, e.g. @code{inclass} -and @code{inextern-lang}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection List Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here calculate the indentation for lines which -form lists of items, usually separated by commas. - -The function @ref{c-lineup-arglist-close-under-paren}, which is mainly -for indenting a close parenthesis, is also useful for the lines -contained within parentheses. - -@defun c-lineup-arglist -@findex lineup-arglist (c-) -Line up the current argument line under the first argument. - -As a special case, if an argument on the same line as the open -parenthesis starts with a brace block opener, the indentation is -@code{c-basic-offset} only. This is intended as a ``DWIM'' measure in -cases like macros that contain statement blocks, e.g: - -@example -@group -A_VERY_LONG_MACRO_NAME (@{ - some (code, with + long, lines * in[it]); - @}); -@sssTBasicOffset{} -@end group -@end example - -This is motivated partly because it's more in line with how code -blocks are handled, and partly since it approximates the behavior of -earlier CC Mode versions, which due to inaccurate analysis tended to -indent such cases this way. - -@workswith @code{arglist-cont-nonempty}, @code{arglist-close}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-arglist-intro-after-paren -@findex lineup-arglist-intro-after-paren (c-) -Line up a line to just after the open paren of the surrounding paren or -brace block. - -@workswith @code{defun-block-intro}, @code{brace-list-intro}, -@code{statement-block-intro}, @code{statement-case-intro}, -@code{arglist-intro}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-multi-inher -@findex lineup-multi-inher (c-) -Line up the classes in C++ multiple inheritance clauses and member -initializers under each other. E.g: - -@example -@group -Foo::Foo (int a, int b): - Cyphr (a), - Bar (b) @hereFn{c-lineup-multi-inher} -@end group -@end example - -@noindent -and - -@example -@group -class Foo - : public Cyphr, - public Bar @hereFn{c-lineup-multi-inher} -@end group -@end example - -@noindent -and - -@example -@group -Foo::Foo (int a, int b) - : Cyphr (a) - , Bar (b) @hereFn{c-lineup-multi-inher} -@end group -@end example - -@workswith @code{inher-cont}, @code{member-init-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-java-inher -@findex lineup-java-inher (c-) -Line up Java implements and extends declarations. If class names -follow on the same line as the @samp{implements}/@samp{extends} -keyword, they are lined up under each other. Otherwise, they are -indented by adding @code{c-basic-offset} to the column of the keyword. -E.g: - -@example -@group -class Foo - extends - Bar @hereFn{c-lineup-java-inher} - @sssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -class Foo - extends Cyphr, - Bar @hereFn{c-lineup-java-inher} -@end group -@end example - -@workswith @code{inher-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-java-throws -@findex lineup-java-throws (c-) -Line up Java throws declarations. If exception names follow on the -same line as the throws keyword, they are lined up under each other. -Otherwise, they are indented by adding @code{c-basic-offset} to the -column of the @samp{throws} keyword. The @samp{throws} keyword itself -is also indented by @code{c-basic-offset} from the function declaration -start if it doesn't hang. E.g: - -@example -@group -int foo() - throws @hereFn{c-lineup-java-throws} - Bar @hereFn{c-lineup-java-throws} -@sssTsssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -int foo() throws Cyphr, - Bar, @hereFn{c-lineup-java-throws} - Vlod @hereFn{c-lineup-java-throws} -@end group -@end example - -@workswith @code{func-decl-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-template-args -@findex lineup-template-args (c-) -Line up the arguments of a template argument list under each other, but -only in the case where the first argument is on the same line as the -opening @samp{<}. - -To allow this function to be used in a list expression, @code{nil} is -returned if there's no template argument on the first line. - -@workswith @code{template-args-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-ObjC-method-call -@findex lineup-ObjC-method-call (c-) -For Objective-C code, line up selector args as Emacs Lisp mode does -with function args: go to the position right after the message receiver, -and if you are at the end of the line, indent the current line -c-basic-offset columns from the opening bracket; otherwise you are -looking at the first character of the first method call argument, so -lineup the current line with it. - -@workswith @code{objc-method-call-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-ObjC-method-args -@findex lineup-ObjC-method-args (c-) -For Objective-C code, line up the colons that separate args. The colon -on the current line is aligned with the one on the first line. - -@workswith @code{objc-method-args-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-ObjC-method-args-2 -@findex lineup-ObjC-method-args-2 (c-) -Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on -the current line with the colon on the previous line. - -@workswith @code{objc-method-args-cont}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection Operator Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here calculate the indentation for lines which -start with an operator, by lining it up with something on the previous -line. - -@defun c-lineup-argcont -@findex lineup-argcont (c-) -Line up a continued argument. E.g: - -@example -@group -foo (xyz, aaa + bbb + ccc - + ddd + eee + fff); @hereFn{c-lineup-argcont} -@end group -@end example - -Only continuation lines like this are touched, @code{nil} is returned on -lines which are the start of an argument. - -Within a gcc @code{asm} block, @code{:} is recognized as an argument -separator, but of course only between operand specifications, not in the -expressions for the operands. - -@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-arglist-operators -@findex lineup-arglist-operators (c-) -Line up lines starting with an infix operator under the open paren. -Return @code{nil} on lines that don't start with an operator, to leave -those cases to other line-up functions. Example: - -@example -@group -if ( x < 10 - || at_limit (x, @hereFn{c-lineup-arglist-operators} - list) @hereFn{c-lineup-arglist-operators@r{ returns nil}} - ) -@end group -@end example - -Since this function doesn't do anything for lines without an infix -operator you typically want to use it together with some other lineup -settings, e.g. as follows (the @code{arglist-close} setting is just a -suggestion to get a consistent style): - -@example -(c-set-offset 'arglist-cont - '(c-lineup-arglist-operators 0)) -(c-set-offset 'arglist-cont-nonempty - '(c-lineup-arglist-operators c-lineup-arglist)) -(c-set-offset 'arglist-close - '(c-lineup-arglist-close-under-paren)) -@end example - -@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-assignments -@findex lineup-assignments (c-) -Line up the current line after the assignment operator on the first line -in the statement. If there isn't any, return nil to allow stacking with -other line-up functions. If the current line contains an assignment -operator too, try to align it with the first one. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. - -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-math -@findex lineup-math (c-) -Like @code{c-lineup-assignments} but indent with @code{c-basic-offset} -if no assignment operator was found on the first line. I.e. this -function is the same as specifying a list @code{(c-lineup-assignments -+)}. It's provided for compatibility with old configurations. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-cascaded-calls -@findex lineup-cascaded-calls (c-) -Line up ``cascaded calls'' under each other. If the line begins with -@code{->} or @code{.} and the preceding line ends with one or more -function calls preceded by the same token, then the arrow is lined up -with the first of those tokens. E.g: - -@example -@group -r = proc->add(17)->add(18) - ->add(19) + @hereFn{c-lineup-cascaded-calls} - offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}} -@end group -@end example - -In any other situation @code{nil} is returned to allow use in list -expressions. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-streamop -@findex lineup-streamop (c-) -Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}). - -@workswith @code{stream-op}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-string-cont -@findex lineup-string-cont (c-) -Line up a continued string under the one it continues. A continued -string in this sense is where a string literal follows directly after -another one. E.g: - -@example -@group -result = prefix + "A message " - "string."; @hereFn{c-lineup-string-cont} -@end group -@end example - -@code{nil} is returned in other situations, to allow stacking with other -lineup functions. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection Comment Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The lineup functions here calculate the indentation for several types -of comment structure. - -@defun c-lineup-C-comments -@findex lineup-C-comments (c-) -Line up C block comment continuation lines. Various heuristics are used -to handle most of the common comment styles. Some examples: - -@example -@group -/* /** /* - * text * text text - */ */ */ -@end group -@end example - -@example -@group -/* text /* /** - text ** text ** text -*/ */ */ -@end group -@end example - -@example -@group -/************************************************** - * text - *************************************************/ -@end group -@end example - -@vindex comment-start-skip -@example -@group -/************************************************** - Free form text comments: - In comments with a long delimiter line at the - start, the indentation is kept unchanged for lines - that start with an empty comment line prefix. The - delimiter line is whatever matches the - @code{comment-start-skip} regexp. -**************************************************/ -@end group -@end example - -The style variable @code{c-comment-prefix-regexp} is used to recognize -the comment line prefix, e.g. the @samp{*} that usually starts every -line inside a comment. - -@workswith The @code{c} syntactic symbol. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-comment -@findex lineup-comment (c-) -Line up a comment-only line according to the style variable -@code{c-comment-only-line-offset}. If the comment is lined up with a -comment starter on the previous line, that alignment is preserved. - -@defopt c-comment-only-line-offset -@vindex comment-only-line-offset (c-) -This style variable specifies the extra offset for the line. It can -contain an integer or a cons cell of the form - -@example -(@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}}) -@end example - -@noindent -where @var{non-anchored-offset} is the amount of offset given to -non-column-zero anchored lines, and @var{anchored-offset} is the amount -of offset to give column-zero anchored lines. Just an integer as value -is equivalent to @code{(@r{@var{value}} . -1000)}. -@end defopt - -@workswith @code{comment-intro}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-knr-region-comment -@findex lineup-knr-region-comment (c-) -Line up a comment in the ``K&R region'' with the declaration. That is -the region between the function or class header and the beginning of the -block. E.g: - -@example -@group -int main() -/* Called at startup. */ @hereFn{c-lineup-knr-region-comment} -@{ - return 0; -@} -@end group -@end example - -Return @code{nil} if called in any other situation, to be useful in list -expressions. - -@workswith @code{comment-intro}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Misc Line-Up, , Comment Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection Miscellaneous Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here are the odds and ends which didn't fit into -any earlier category. - -@defun c-lineup-dont-change -@findex lineup-dont-change (c-) -This lineup function makes the line stay at whatever indentation it -already has; think of it as an identity function for lineups. - -@workswith Any syntactic symbol. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-cpp-define -@findex lineup-cpp-define (c-) -Line up macro continuation lines according to the indentation of the -construct preceding the macro. E.g: - -@example -@group -const char msg[] = @hereFn{@r{The beginning of the preceding construct.}} - \"Some text.\"; - -#define X(A, B) \ -do @{ \ @hereFn{c-lineup-cpp-define} - printf (A, B); \ -@} while (0) -@end group -@end example - -@noindent -and: - -@example -@group -int dribble() @{ - if (!running) @hereFn{@r{The beginning of the preceding construct.}} - error(\"Not running!\"); - -#define X(A, B) \ - do @{ \ @hereFn{c-lineup-cpp-define} - printf (A, B); \ - @} while (0) -@end group -@end example - -If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the -function returns the relative indentation to the macro start line to -allow accumulation with other offsets. E.g. in the following cases, -@code{cpp-define-intro} is combined with the -@code{statement-block-intro} that comes from the @samp{do @{} that hangs -on the @samp{#define} line: - -@example -@group -const char msg[] = - \"Some text.\"; - -#define X(A, B) do @{ \ - printf (A, B); \ @hereFn{c-lineup-cpp-define} - this->refs++; \ -@} while (0) @hereFn{c-lineup-cpp-define} -@end group -@end example - -@noindent -and: - -@example -@group -int dribble() @{ - if (!running) - error(\"Not running!\"); - -#define X(A, B) do @{ \ - printf (A, B); \ @hereFn{c-lineup-cpp-define} - this->refs++; \ - @} while (0) @hereFn{c-lineup-cpp-define} -@end group -@end example - -The relative indentation returned by @code{c-lineup-cpp-define} is zero -and two, respectively, on the two lines in each of these examples. They -are then added to the two column indentation that -@code{statement-block-intro} gives in both cases here. - -If the relative indentation is zero, then @code{nil} is returned -instead. That is useful in a list expression to specify the default -indentation on the top level. - -If @code{c-syntactic-indentation-in-macros} is @code{nil} then this -function keeps the current indentation, except for empty lines (ignoring -the ending backslash) where it takes the indentation from the closest -preceding nonempty line in the macro. If there's no such line in the -macro then the indentation is taken from the construct preceding it, as -described above. - -@workswith @code{cpp-define-intro}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-gcc-asm-reg -@findex lineup-gcc-asm-reg (c-) -Line up a gcc asm register under one on a previous line. - -@example -@group - asm ("foo %1, %0\n" - "bar %0, %1" - : "=r" (w), - "=r" (x) - : "0" (y), - "1" (z)); -@end group -@end example - -The @samp{x} line is aligned to the text after the @samp{:} on the -@samp{w} line, and similarly @samp{z} under @samp{y}. - -This is done only in an @samp{asm} or @samp{__asm__} block, and only to -those lines mentioned. Anywhere else @code{nil} is returned. The usual -arrangement is to have this routine as an extra feature at the start of -arglist lineups, e.g. - -@example -(c-lineup-gcc-asm-reg c-lineup-arglist) -@end example - -@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-topmost-intro-cont -@findex lineup-topmost-intro-cont (c-) -Line up declaration continuation lines zero or one indentation -step@footnote{This function is mainly provided to mimic the behavior of -CC Mode 5.28 and earlier where this case wasn't handled consistently so -that those lines could be analyzed as either topmost-intro-cont or -statement-cont. It's used for @code{topmost-intro-cont} by default, but -you might consider using @code{+} instead.}. For lines preceding a -definition, zero is used. For other lines, @code{c-basic-offset} is -added to the indentation. E.g: - -@example -@group -int -neg (int i) @hereFn{c-lineup-topmost-intro-cont} -@{ - return -i; -@} -@end group -@end example - -@noindent -and - -@example -@group -struct -larch @hereFn{c-lineup-topmost-intro-cont} -@{ - double height; -@} - the_larch, @hereFn{c-lineup-topmost-intro-cont} - another_larch; @hereFn{c-lineup-topmost-intro-cont} -@sssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -struct larch -the_larch, @hereFn{c-lineup-topmost-intro-cont} - another_larch; @hereFn{c-lineup-topmost-intro-cont} -@end group -@end example - -@workswith @code{topmost-intro-cont}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation -@comment node-name, next, previous, up -@section Custom Line-Up Functions -@cindex customization, indentation functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The most flexible way to customize indentation is by writing custom -line-up functions, and associating them with specific syntactic -symbols (@pxref{c-offsets-alist}). Depending on the effect you want, -it might be better to write a @code{c-special-indent-hook} function -rather than a line-up function (@pxref{Other Indentation}). - -@ccmode{} comes with an extensive set of predefined line-up functions, -not all of which are used by the default styles. So there's a good -chance the function you want already exists. @xref{Line-Up -Functions}, for a list of them. If you write your own line-up -function, it's probably a good idea to start working from one of these -predefined functions, which can be found in the file -@file{cc-align.el}. If you have written a line-up function that you -think is generally useful, you're very welcome to contribute it; -please contact @email{bug-cc-mode@@gnu.org}. - - Line-up functions are passed a single argument, the syntactic -element (see below). The return value is a @code{c-offsets-alist} -offset specification: for example, an integer, a symbol such as -@code{+}, a vector, @code{nil}@footnote{Returning @code{nil} is useful -when the offset specification for a syntactic element is a list -containing the line-up function (@pxref{c-offsets-alist}).}, or even -another line-up function. Full details of these are in -@ref{c-offsets-alist}. - -Line-up functions must not move point or change the content of the -buffer (except temporarily). They are however allowed to do -@dfn{hidden buffer changes}, i.e. setting text properties for caching -purposes etc. Buffer undo recording is disabled while they run. - -The syntactic element passed as the parameter to a line-up function is -a cons cell of the form - -@example -(@r{@var{syntactic-symbol}} . @r{@var{anchor-position}}) -@end example - -@noindent -@c FIXME!!! The following sentence might be better omitted, since the -@c information is in the cross reference "Syntactic Analysis". 2005/10/2. -where @var{syntactic-symbol} is the symbol that the function was -called for, and @var{anchor-position} is the anchor position (if any) -for the construct that triggered the syntactic symbol -(@pxref{Syntactic Analysis}). This cons cell is how the syntactic -element of a line used to be represented in @ccmode{} 5.28 and -earlier. Line-up functions are still passed this cons cell, so as to -preserve compatibility with older configurations. In the future, we -may decide to convert to using the full list format---you can prepare -your setup for this by using the access functions -(@code{c-langelem-sym}, etc.) described below. - -@vindex c-syntactic-element -@vindex syntactic-element (c-) -@vindex c-syntactic-context -@vindex syntactic-context (c-) -Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more -info in the syntactic element - typically other positions that can be -interesting besides the anchor position. That info can't be accessed -through the passed argument, which is a cons cell. Instead, you can -get this information from the variable @code{c-syntactic-element}, -which is dynamically bound to the complete syntactic element. The -variable @code{c-syntactic-context} might also be useful - it gets -dynamically bound to the complete syntactic context. @xref{Custom -Braces}. - -@ccmode{} provides a few functions to access parts of syntactic -elements in a more abstract way. Besides making the code easier to -read, they also hide the difference between the old cons cell form -used in the line-up function argument and the new list form used in -@code{c-syntactic-element} and everywhere else. The functions are: - -@defun c-langelem-sym langelem -@findex langelem-sym (c-) -Return the syntactic symbol in @var{langelem}. -@end defun - -@defun c-langelem-pos langelem -@findex langelem-pos (c-) -Return the anchor position in @var{langelem}, or nil if there is none. -@end defun - -@defun c-langelem-col langelem &optional preserve-point -@findex langelem-col (c-) -Return the column of the anchor position in @var{langelem}. Also move -the point to that position unless @var{preserve-point} is -non-@code{nil}. -@end defun - -@defun c-langelem-2nd-pos langelem -@findex langelem-2nd-pos (c-) -Return the secondary position in @var{langelem}, or @code{nil} if there -is none. - -Note that the return value of this function is always @code{nil} if -@var{langelem} is in the old cons cell form. Thus this function is -only meaningful when used on syntactic elements taken from -@code{c-syntactic-element} or @code{c-syntactic-context}. -@end defun - -Custom line-up functions can be as simple or as complex as you like, and -any syntactic symbol that appears in @code{c-offsets-alist} can have a -custom line-up function associated with it. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Other Indentation, , Custom Line-Up, Customizing Indentation -@comment node-name, next, previous, up -@section Other Special Indentations -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -To configure macros which you invoke without a terminating @samp{;}, -see @xref{Macros with ;}. - -Here are the remaining odds and ends regarding indentation: - -@defopt c-label-minimum-indentation -@vindex label-minimum-indentation (c-) -In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is -imposed on lines inside code blocks. This minimum indentation is -controlled by this style variable. The default value is 1. - -@findex c-gnu-impose-minimum -@findex gnu-impose-minimum (c-) -It's the function @code{c-gnu-impose-minimum} that enforces this minimum -indentation. It must be present on @code{c-special-indent-hook} to -work. -@end defopt - -@defopt c-special-indent-hook -@vindex special-indent-hook (c-) -This style variable is a standard hook variable that is called after -every line is indented by @ccmode{}. It is called only if -@code{c-syntactic-indentation} is non-@code{nil} (which it is by -default (@pxref{Indentation Engine Basics})). You can put a function -on this hook to do any special indentation or ad hoc line adjustments -your style dictates, such as adding extra indentation to constructors -or destructor declarations in a class definition, etc. Sometimes it -is better to write a custom Line-up Function instead (@pxref{Custom -Line-Up}). - -When the indentation engine calls this hook, the variable -@code{c-syntactic-context} is bound to the current syntactic context -(i.e. what you would get by typing @kbd{C-c C-s} on the source line. -@xref{Custom Braces}.). Note that you should not change point or mark -inside a @code{c-special-indent-hook} function, i.e. you'll probably -want to wrap your function in a @code{save-excursion}@footnote{The -numerical value returned by @code{point} will change if you change the -indentation of the line within a @code{save-excursion} form, but point -itself will still be over the same piece of text.}. - -Setting @code{c-special-indent-hook} in style definitions is handled -slightly differently from other variables---A style can only add -functions to this hook, not remove them. @xref{Style Variables}. -@end defopt - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Macros, Odds and Ends, Customizing Indentation, Top -@comment node-name, next, previous, up -@chapter Customizing Macros -@cindex macros -@cindex preprocessor directives -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Preprocessor macros in C, C++, and Objective C (introduced by -@code{#define}) have a syntax different from the main language---for -example, a macro declaration is not terminated by a semicolon, and if -it is more than a line long, line breaks in it must be escaped with -backslashes. @ccmode{} has some commands to manipulate these, see -@ref{Macro Backslashes}. - -Normally, the lines in a multi-line macro are indented relative to -each other as though they were code. You can suppress this behavior -by setting the following user option: - -@defopt c-syntactic-indentation-in-macros -@vindex syntactic-indentation-in-macros (c-) -Enable syntactic analysis inside macros, which is the default. If this -is @code{nil}, all lines inside macro definitions are analyzed as -@code{cpp-macro-cont}. -@end defopt - -Because a macro can expand into anything at all, near where one is -invoked @ccmode{} can only indent and fontify code heuristically. -Sometimes it gets it wrong. Usually you should try to design your -macros so that they ''look like ordinary code'' when you invoke them. -However, one situation is so common that @ccmode{} handles it -specially: that is when certain macros needn't (or mustn't) be -followed by a @samp{;}. You need to configure @ccmode{} to handle -these macros properly, see @ref{Macros with ;}. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@menu -* Macro Backslashes:: -* Macros with ;:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Macro Backslashes, Macros with ;, Custom Macros, Custom Macros -@comment node-name, next, previous, up -@section Customizing Macro Backslashes -@cindex @code{#define} -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} provides some tools to help keep the line continuation -backslashes in macros neat and tidy. Their precise action is -customized with these variables: - -@defopt c-backslash-column -@vindex backslash-column (c-) -@defoptx c-backslash-max-column -@vindex backslash-max-column (c-) -These variables control the alignment columns for line continuation -backslashes in multiline macros. They are used by the functions that -automatically insert or align such backslashes, -e.g. @code{c-backslash-region} and @code{c-context-line-break}. - -@code{c-backslash-column} specifies the minimum column for the -backslashes. If any line in the macro goes past this column, then the -next tab stop (i.e. next multiple of @code{tab-width}) in that line is -used as the alignment column for all the backslashes, so that they -remain in a single column. However, if any lines go past -@code{c-backslash-max-column} then the backslashes in the rest of the -macro will be kept at that column, so that the lines which are too -long ``stick out'' instead. - -Don't ever set these variables to @code{nil}. If you want to disable -the automatic alignment of backslashes, use -@code{c-auto-align-backslashes}. -@end defopt - -@defopt c-auto-align-backslashes -@vindex auto-align-backslashes (c-) -Align automatically inserted line continuation backslashes if -non-@code{nil}. When line continuation backslashes are inserted -automatically for line breaks in multiline macros, e.g. by -@code{c-context-line-break}, they are aligned with the other -backslashes in the same macro if this flag is set. - -If @code{c-auto-align-backslashes} is @code{nil}, automatically -inserted backslashes are preceded by a single space, and backslashes -get aligned only when you explicitly invoke the command -@code{c-backslash-region} (@kbd{C-c C-\}). -@end defopt - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Macros with ;, , Macro Backslashes, Custom Macros -@comment node-name, next, previous, up -@section Macros with semicolons -@cindex macros with semicolons -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -Macros which needn't (or mustn't) be followed by a semicolon when you -invoke them, @dfn{macros with semicolons}, are very common. These can -cause @ccmode{} to parse the next line wrongly as a -@code{statement-cont} (@pxref{Function Symbols}) and thus mis-indent -it. - -You can prevent this by specifying which macros have semicolons. It -doesn't matter whether or not such a macro has a parameter list: - -@defopt c-macro-names-with-semicolon -@vindex macro-names-with-semicolon (c-) -This buffer-local variable specifies which macros have semicolons. -After setting its value, you need to call -@code{c-make-macro-with-semi-re} for it to take effect. It should be -set to one of these values: - -@table @asis -@item nil -There are no macros with semicolons. -@item a list of strings -Each string is the name of a macro with a semicolon. Only valid -@code{#define} names are allowed here. For example, to set the -default value, you could write the following into your @file{.emacs}: - -@example -(setq c-macro-names-with-semicolon - '("Q_OBJECT" "Q_PROPERTY" "Q_DECLARE" "Q_ENUMS")) -@end example - -@item a regular expression -This matches each symbol which is a macro with a semicolon. It must -not match any string which isn't a valid @code{#define} name. For -example: - -@example -(setq c-macro-names-with-semicolon - "\\<\\(CLEAN_UP_AND_RETURN\\|Q_[[:upper:]]+\\)\\>") -@end example -@end table -@end defopt - -@defun c-make-macro-with-semi-re -@findex make-macro-with-semi-re (c-) -Call this (non-interactive) function, which sets internal variables, -each time you change the value of -@code{c-macro-names-with-semicolon}. It takes no arguments, and its -return value has no meaning. This function is called by @ccmode{}'s -initialization code. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Odds and Ends, Sample .emacs File, Custom Macros, Top -@comment node-name, next, previous, up -@chapter Odds and Ends -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The stuff that didn't fit in anywhere else is documented here. - -@defopt c-require-final-newline -@vindex require-final-newline (c-) -Controls whether a final newline is enforced when the file is saved. -The value is an association list that for each language mode specifies -the value to give to @code{require-final-newline} (@pxref{Saving -Buffers,,,@lispref{}, @lispreftitle{}}) at mode initialization. If a -language isn't present on the association list, CC Mode won't touch -@code{require-final-newline} in buffers for that language. - -The default is to set @code{require-final-newline} to @code{t} in the -languages that mandate that source files should end with newlines. -These are C, C++ and Objective-C. -@end defopt - -@defopt c-echo-syntactic-information-p -@vindex echo-syntactic-information-p (c-) -If non-@code{nil}, the syntactic analysis for the current line is shown -in the echo area when it's indented (unless -@code{c-syntactic-indentation} is @code{nil}). That's useful when -finding out which syntactic symbols to modify to get the indentation you -want. -@end defopt - -@defopt c-report-syntactic-errors -@vindex report-syntactic-errors (c-) -If non-@code{nil}, certain syntactic errors are reported with a ding and -a message, for example when an @code{else} is indented for which there -is no corresponding @code{if}. - -Note however that @ccmode{} doesn't make any special effort to check for -syntactic errors; that's the job of the compiler. The reason it can -report cases like the one above is that it can't find the correct -anchoring position to indent the line in that case. -@end defopt - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Sample .emacs File, Performance Issues, Odds and Ends, Top -@comment node-name, next, previous, up -@appendix Sample .emacs File -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here's a sample .emacs file fragment that might help you along the way. -Just copy this region and paste it into your .emacs file. You might want -to change some of the actual values. - -@verbatim -;; Make a non-standard key binding. We can put this in -;; c-mode-base-map because c-mode-map, c++-mode-map, and so on, -;; inherit from it. -(defun my-c-initialization-hook () - (define-key c-mode-base-map "\C-m" 'c-context-line-break)) -(add-hook 'c-initialization-hook 'my-c-initialization-hook) - -;; offset customizations not in my-c-style -;; This will take precedence over any setting of the syntactic symbol -;; made by a style. -(setq c-offsets-alist '((member-init-intro . ++))) - -;; Create my personal style. -(defconst my-c-style - '((c-tab-always-indent . t) - (c-comment-only-line-offset . 4) - (c-hanging-braces-alist . ((substatement-open after) - (brace-list-open))) - (c-hanging-colons-alist . ((member-init-intro before) - (inher-intro) - (case-label after) - (label after) - (access-label after))) - (c-cleanup-list . (scope-operator - empty-defun-braces - defun-close-semi)) - (c-offsets-alist . ((arglist-close . c-lineup-arglist) - (substatement-open . 0) - (case-label . 4) - (block-open . 0) - (knr-argdecl-intro . -))) - (c-echo-syntactic-information-p . t)) - "My C Programming Style") -(c-add-style "PERSONAL" my-c-style) - -;; Customizations for all modes in CC Mode. -(defun my-c-mode-common-hook () - ;; set my personal style for the current buffer - (c-set-style "PERSONAL") - ;; other customizations - (setq tab-width 8 - ;; this will make sure spaces are used instead of tabs - indent-tabs-mode nil) - ;; we like auto-newline, but not hungry-delete - (c-toggle-auto-newline 1)) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) -@end verbatim - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top -@comment node-name, next, previous, up -@chapter Performance Issues -@cindex performance -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here. - -C and its derivative languages are highly complex creatures. Often, -ambiguous code situations arise that require @ccmode{} to scan large -portions of the buffer to determine syntactic context. Such -pathological code can cause @ccmode{} to perform fairly badly. This -section gives some insight in how @ccmode{} operates, how that interacts -with some coding styles, and what you can use to improve performance. - -The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take -more than a fraction of a second) in any interactive operation. -I.e. it's tuned to limit the maximum response time in single operations, -which is sometimes at the expense of batch-like operations like -reindenting whole blocks. If you find that @ccmode{} gradually gets -slower and slower in certain situations, perhaps as the file grows in -size or as the macro or comment you're editing gets bigger, then chances -are that something isn't working right. You should consider reporting -it, unless it's something that's mentioned in this section. - -Because @ccmode{} has to scan the buffer backwards from the current -insertion point, and because C's syntax is fairly difficult to parse in -the backwards direction, @ccmode{} often tries to find the nearest -position higher up in the buffer from which to begin a forward scan -(it's typically an opening or closing parenthesis of some kind). The -farther this position is from the current insertion point, the slower it -gets. - -@findex beginning-of-defun -In earlier versions of @ccmode{}, we used to recommend putting the -opening brace of a top-level construct@footnote{E.g. a function in C, -or outermost class definition in C++ or Java.} into the leftmost -column. Earlier still, this used to be a rigid Emacs constraint, as -embodied in the @code{beginning-of-defun} function. @ccmode now -caches syntactic information much better, so that the delay caused by -searching for such a brace when it's not in column 0 is minimal, -except perhaps when you've just moved a long way inside the file. - -@findex defun-prompt-regexp -@vindex c-Java-defun-prompt-regexp -@vindex Java-defun-prompt-regexp (c-) -A special note about @code{defun-prompt-regexp} in Java mode: The common -style is to hang the opening braces of functions and classes on the -right side of the line, and that doesn't work well with the Emacs -approach. @ccmode{} comes with a constant -@code{c-Java-defun-prompt-regexp} which tries to define a regular -expression usable for this style, but there are problems with it. In -some cases it can cause @code{beginning-of-defun} to hang@footnote{This -has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, -it is not used by default, but if you feel adventurous, you can set -@code{defun-prompt-regexp} to it in your mode hook. In any event, -setting and relying on @code{defun-prompt-regexp} will definitely slow -things down because (X)Emacs will be doing regular expression searches a -lot, so you'll probably be taking a hit either way! - -@ccmode{} maintains a cache of the opening parentheses of the blocks -surrounding the point, and it adapts that cache as the point is moved -around. That means that in bad cases it can take noticeable time to -indent a line in a new surrounding, but after that it gets fast as long -as the point isn't moved far off. The farther the point is moved, the -less useful is the cache. Since editing typically is done in ``chunks'' -rather than on single lines far apart from each other, the cache -typically gives good performance even when the code doesn't fit the -Emacs approach to finding the defun starts. - -@vindex c-enable-xemacs-performance-kludge-p -@vindex enable-xemacs-performance-kludge-p (c-) -XEmacs users can set the variable -@code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This -tells @ccmode{} to use XEmacs-specific built-in functions which, in some -circumstances, can locate the top-most opening brace much more quickly than -@code{beginning-of-defun}. Preliminary testing has shown that for -styles where these braces are hung (e.g. most JDK-derived Java styles), -this hack can improve performance of the core syntax parsing routines -from 3 to 60 times. However, for styles which @emph{do} conform to -Emacs's recommended style of putting top-level braces in column zero, -this hack can degrade performance by about as much. Thus this variable -is set to @code{nil} by default, since the Emacs-friendly styles should -be more common (and encouraged!). Note that this variable has no effect -in Emacs since the necessary built-in functions don't exist (in Emacs -22.1 as of this writing in February 2007). - -Text properties are used to speed up skipping over syntactic whitespace, -i.e. comments and preprocessor directives. Indenting a line after a -huge macro definition can be slow the first time, but after that the -text properties are in place and it should be fast (even after you've -edited other parts of the file and then moved back). - -Font locking can be a CPU hog, especially the font locking done on -decoration level 3 which tries to be very accurate. Note that that -level is designed to be used with a font lock support mode that only -fontifies the text that's actually shown, i.e. Lazy Lock or Just-in-time -Lock mode, so make sure you use one of them. Fontification of a whole -buffer with some thousand lines can often take over a minute. That is -a known weakness; the idea is that it never should happen. - -The most effective way to speed up font locking is to reduce the -decoration level to 2 by setting @code{font-lock-maximum-decoration} -appropriately. That level is designed to be as pretty as possible -without sacrificing performance. @xref{Font Locking Preliminaries}, for -more info. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Limitations and Known Bugs, FAQ, Performance Issues, Top -@comment node-name, next, previous, up -@chapter Limitations and Known Bugs -@cindex limitations -@cindex bugs -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@itemize @bullet -@item -@ccmode{} doesn't support trigraphs. (These are character sequences -such as @samp{??(}, which represents @samp{[}. They date from a time -when some character sets didn't have all the characters that C needs, -and are now utterly obsolete.) - -@item -There is no way to apply auto newline settings (@pxref{Auto-newlines}) -on already typed lines. That's only a feature to ease interactive -editing. - -To generalize this issue a bit: @ccmode{} is not intended to be used as -a reformatter for old code in some more or less batch-like way. With -the exception of some functions like @code{c-indent-region}, it's only -geared to be used interactively to edit new code. There's currently no -intention to change this goal. - -If you want to reformat old code, you're probably better off using some -other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent' -Manual}, which has more powerful reformatting capabilities than -@ccmode{}. - -@item -The support for C++ templates (in angle brackets) is not yet complete. -When a non-nested template is used in a declaration, @ccmode{} indents -it and font-locks it OK. Templates used in expressions, and nested -templates do not fare so well. Sometimes a workaround is to refontify -the expression after typing the closing @samp{>}. - -@item -In a @dfn{k&r region} (the part of an old-fashioned C function -declaration which specifies the types of its parameters, coming -between the parameter list and the opening brace), there should be at -most 20 top-level parenthesis and bracket pairs. This limit has been -imposed for performance reasons. If it is violated, the source file -might be incorrectly indented or fontified. - -@item -On loading @ccmode{}, sometimes this error message appears: - -@example -File mode specification error: (void-variable c-font-lock-keywords-3) -@end example - -This is due to a bug in the function @code{eval-after-load} in some -versions of (X)Emacs. It can manifest itself when there is a symbolic -link in the path of the directory which contains (X)Emacs. As a -workaround, put the following into your @file{.emacs} file, fairly -early on: - -@example -(defun my-load-cc-fonts () - (require "cc-fonts")) -(add-hook 'c-initialization-hook 'my-load-cc-fonts) -@end example -@end itemize - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node FAQ, Updating CC Mode, Limitations and Known Bugs, Top -@comment node-name, next, previous, up -@appendix Frequently Asked Questions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@itemize @bullet -@item -@emph{How can I change the indent level from 4 spaces to 2 spaces?} - -Set the variable @code{c-basic-offset}. @xref{Getting Started}. - -@item -@kindex RET -@kindex C-j -@emph{Why doesn't the @kbd{RET} key indent the new line?} - -Emacs's convention is that @kbd{RET} just adds a newline, and that -@kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this -too by adding this to your @code{c-initialization-hook}: - -@example -(define-key c-mode-base-map "\C-m" 'c-context-line-break) -@end example - -@xref{Getting Started}. This is a very common question. If you want -this to be the default behavior, don't lobby us, lobby RMS! @t{:-)} - -@item -@emph{How do I stop my code jumping all over the place when I type?} - -Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting -Started}. - -@item -@kindex C-x h -@kindex C-M-\ -@emph{How do I reindent the whole file?} - -Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit -@kbd{C-M-\}. @xref{Indentation Commands}. - -@item -@kindex C-M-q -@kindex C-M-u -@emph{How do I reindent the current block?} - -First move to the brace which opens the block with @kbd{C-M-u}, then -reindent that expression with @kbd{C-M-q}. @xref{Indentation -Commands}. - -@item -@emph{I put @code{(c-set-offset 'substatement-open 0)} in my -@file{.emacs} file but I get an error saying that @code{c-set-offset}'s -function definition is void. What's wrong?} - -This means that @ccmode{} hasn't yet been loaded into your Emacs -session by the time the @code{c-set-offset} call is reached, most -likely because @ccmode{} is being autoloaded. Instead of putting the -@code{c-set-offset} line in your top-level @file{.emacs} file, put it -in your @code{c-initialization-hook} (@pxref{CC Hooks}), or simply -modify @code{c-offsets-alist} directly: - -@example -(setq c-offsets-alist '((substatement-open . 0))) -@end example - -@item -@cindex open paren in column zero -@emph{I have an open paren character at column zero inside a comment or -multiline string literal, and it causes the fontification and/or -indentation to go haywire. What gives?} - -It's due to the ad-hoc rule in (X)Emacs that such open parens always -start defuns (which translates to functions, classes, namespaces or any -other top-level block constructs in the @ccmode{} languages). -@ifset XEMACS -@xref{Defuns,,, xemacs, XEmacs User's Manual}, for details. -@end ifset -@ifclear XEMACS -@xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details -(@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual). -@end ifclear - -This heuristic is built into the core syntax analysis routines in -(X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs -21.1 it became possible to turn it off@footnote{Using the variable -@code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so -there since it's got its own system to keep track of blocks. - -@end itemize - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top -@comment node-name, next, previous, up -@appendix Getting the Latest CC Mode Release -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} has been standard with all versions of Emacs since 19.34 and -of XEmacs since 19.16. - -@cindex web site -Due to release schedule skew, it is likely that all of these Emacsen -have old versions of @ccmode{} and so should be upgraded. Access to the -@ccmode{} source code, as well as more detailed information on Emacsen -compatibility, etc. are all available on the web site: - -@quotation -@uref{http://cc-mode.sourceforge.net/} -@end quotation - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Mailing Lists and Bug Reports, GNU Free Documentation License, Updating CC Mode, Top -@comment node-name, next, previous, up -@appendix Mailing Lists and Submitting Bug Reports -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@kindex C-c C-b -@findex c-submit-bug-report -@findex submit-bug-report (c-) -To report bugs, use the @kbd{C-c C-b} (bound to -@code{c-submit-bug-report}) command. This provides vital information -we need to reproduce your problem. Make sure you include a concise, -but complete code example. Please try to boil your example down to -just the essential code needed to reproduce the problem, and include -an exact recipe of steps needed to expose the bug. Be especially sure -to include any code that appears @emph{before} your bug example, if -you think it might affect our ability to reproduce it. - -Please try to produce the problem in an Emacs instance without any -customizations loaded (i.e. start it with the @samp{-q --no-site-file} -arguments). If it works correctly there, the problem might be caused -by faulty customizations in either your own or your site -configuration. In that case, we'd appreciate it if you isolate the -Emacs Lisp code that triggers the bug and include it in your report. - -@cindex bug report mailing list -Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can -also send other questions and suggestions (kudos? @t{;-)} to that -address. It's a mailing list which you can join or browse an archive -of; see the web site at @uref{http://cc-mode.sourceforge.net/} for -further details. - -@cindex announcement mailing list -If you want to get announcements of new @ccmode{} releases, send the -word @emph{subscribe} in the body of a message to -@email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible -to subscribe from the web site too. Announcements will also be posted -to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs}, -@code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++}, -@code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools}, -@code{comp.lang.idl}, and @code{comp.lang.awk}. -@c There is no newsgroup for Pike. :-( - - -@node GNU Free Documentation License, Command and Function Index, Mailing Lists and Bug Reports, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@c Removed the tentative node "Mode Initialization" from here, 2005/8/27. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Command and Function Index, Variable Index, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Command and Function Index -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since most @ccmode{} commands are prepended with the string -@samp{c-}, each appears under its @code{c-@var{thing}} name and its -@code{@var{thing} (c-)} name. -@iftex -@sp 2 -@end iftex -@printindex fn - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Variable Index, Concept and Key Index, Command and Function Index, Top -@comment node-name, next, previous, up -@unnumbered Variable Index -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since most @ccmode{} variables are prepended with the string -@samp{c-}, each appears under its @code{c-@var{thing}} name and its -@code{@var{thing} (c-)} name. -@iftex -@sp 2 -@end iftex -@printindex vr - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Concept and Key Index, , Variable Index, Top -@comment node-name, next, previous, up -@unnumbered Concept and Key Index -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@printindex cp - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment Epilogue. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@bye diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi deleted file mode 100644 index d35c14acd1d..00000000000 --- a/doc/misc/cl.texi +++ /dev/null @@ -1,5344 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/cl -@settitle Common Lisp Extensions - -@copying -This file documents the GNU Emacs Common Lisp emulation package. - -Copyright @copyright{} 1993, 2001-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs lisp libraries -@direntry -* CL: (cl). Partial Common Lisp support for Emacs Lisp. -@end direntry - -@finalout - -@titlepage -@sp 6 -@center @titlefont{Common Lisp Extensions} -@sp 4 -@center For GNU Emacs Lisp -@sp 1 -@center Version 2.02 -@sp 5 -@center Dave Gillespie -@center daveg@@synaptics.com -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top, Overview, (dir), (dir) -@chapter Introduction - -@noindent -This document describes a set of Emacs Lisp facilities borrowed from -Common Lisp. All the facilities are described here in detail. While -this document does not assume any prior knowledge of Common Lisp, it -does assume a basic familiarity with Emacs Lisp. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: Installation, usage, etc. -* Program Structure:: Arglists, @code{eval-when}, @code{defalias} -* Predicates:: @code{typep} and @code{equalp} -* Control Structure:: @code{setf}, @code{do}, @code{loop}, etc. -* Macros:: Destructuring, @code{define-compiler-macro} -* Declarations:: @code{proclaim}, @code{declare}, etc. -* Symbols:: Property lists, @code{gensym} -* Numbers:: Predicates, functions, random numbers -* Sequences:: Mapping, functions, searching, sorting -* Lists:: @code{caddr}, @code{sublis}, @code{member*}, @code{assoc*}, etc. -* Structures:: @code{defstruct} -* Assertions:: @code{check-type}, @code{assert}, @code{ignore-errors}. - -* Efficiency Concerns:: Hints and techniques -* Common Lisp Compatibility:: All known differences with Steele -* Old CL Compatibility:: All known differences with old cl.el -* Porting Common Lisp:: Hints for porting Common Lisp code - -* GNU Free Documentation License:: The license for this documentation. -* Function Index:: -* Variable Index:: -@end menu - -@node Overview, Program Structure, Top, Top -@ifnottex -@chapter Overview -@end ifnottex - -@noindent -Common Lisp is a huge language, and Common Lisp systems tend to be -massive and extremely complex. Emacs Lisp, by contrast, is rather -minimalist in the choice of Lisp features it offers the programmer. -As Emacs Lisp programmers have grown in number, and the applications -they write have grown more ambitious, it has become clear that Emacs -Lisp could benefit from many of the conveniences of Common Lisp. - -The @dfn{CL} package adds a number of Common Lisp functions and -control structures to Emacs Lisp. While not a 100% complete -implementation of Common Lisp, @dfn{CL} adds enough functionality -to make Emacs Lisp programming significantly more convenient. - -@strong{Please note:} the @dfn{CL} functions are not standard parts of -the Emacs Lisp name space, so it is legitimate for users to define -them with other, conflicting meanings. To avoid conflicting with -those user activities, we have a policy that packages installed in -Emacs must not load @dfn{CL} at run time. (It is ok for them to load -@dfn{CL} at compile time only, with @code{eval-when-compile}, and use -the macros it provides.) If you are writing packages that you plan to -distribute and invite widespread use for, you might want to observe -the same rule. - -Some Common Lisp features have been omitted from this package -for various reasons: - -@itemize @bullet -@item -Some features are too complex or bulky relative to their benefit -to Emacs Lisp programmers. CLOS and Common Lisp streams are fine -examples of this group. - -@item -Other features cannot be implemented without modification to the -Emacs Lisp interpreter itself, such as multiple return values, -lexical scoping, case-insensitive symbols, and complex numbers. -The @dfn{CL} package generally makes no attempt to emulate these -features. - -@item -Some features conflict with existing things in Emacs Lisp. For -example, Emacs's @code{assoc} function is incompatible with the -Common Lisp @code{assoc}. In such cases, this package usually -adds the suffix @samp{*} to the function name of the Common -Lisp version of the function (e.g., @code{assoc*}). -@end itemize - -The package described here was written by Dave Gillespie, -@file{daveg@@synaptics.com}. It is a total rewrite of the original -1986 @file{cl.el} package by Cesar Quiroz. Most features of the -Quiroz package have been retained; any incompatibilities are -noted in the descriptions below. Care has been taken in this -version to ensure that each function is defined efficiently, -concisely, and with minimal impact on the rest of the Emacs -environment. - -@menu -* Usage:: How to use the CL package -* Organization:: The package's five component files -* Installation:: Compiling and installing CL -* Naming Conventions:: Notes on CL function names -@end menu - -@node Usage, Organization, Overview, Overview -@section Usage - -@noindent -Lisp code that uses features from the @dfn{CL} package should -include at the beginning: - -@example -(require 'cl) -@end example - -@noindent -It is safe to arrange to load @dfn{CL} at all times, e.g., -in your @file{.emacs} file. But it's a good idea, for portability, -to @code{(require 'cl)} in your code even if you do this. - -@node Organization, Installation, Usage, Overview -@section Organization - -@noindent -The Common Lisp package is organized into four files: - -@table @file -@item cl.el -This is the ``main'' file, which contains basic functions -and information about the package. This file is relatively -compact---about 700 lines. - -@item cl-extra.el -This file contains the larger, more complex or unusual functions. -It is kept separate so that packages which only want to use Common -Lisp fundamentals like the @code{cadr} function won't need to pay -the overhead of loading the more advanced functions. - -@item cl-seq.el -This file contains most of the advanced functions for operating -on sequences or lists, such as @code{delete-if} and @code{assoc*}. - -@item cl-macs.el -This file contains the features of the packages which are macros -instead of functions. Macros expand when the caller is compiled, -not when it is run, so the macros generally only need to be -present when the byte-compiler is running (or when the macros are -used in uncompiled code such as a @file{.emacs} file). Most of -the macros of this package are isolated in @file{cl-macs.el} so -that they won't take up memory unless you are compiling. -@end table - -The file @file{cl.el} includes all necessary @code{autoload} -commands for the functions and macros in the other three files. -All you have to do is @code{(require 'cl)}, and @file{cl.el} -will take care of pulling in the other files when they are -needed. - -There is another file, @file{cl-compat.el}, which defines some -routines from the older @file{cl.el} package that are not otherwise -present in the new package. This includes internal routines -like @code{setelt} and @code{zip-lists}, deprecated features -like @code{defkeyword}, and an emulation of the old-style -multiple-values feature. This file is obsolete and should not be used -in new code. @xref{Old CL Compatibility}. - -@node Installation, Naming Conventions, Organization, Overview -@section Installation - -@noindent -The @dfn{CL} package is distributed with Emacs, so there is no need -to install anything. - -If you do need to install it, just put the byte-compiled files -@file{cl.elc}, @file{cl-extra.elc}, @file{cl-seq.elc}, -@file{cl-macs.elc}, and (if necessary) @file{cl-compat.elc} into a -directory on your @code{load-path}. Also, format the @file{cl.texi} -file and put the resulting Info files into a directory in your -@code{Info-directory-list}. - -@node Naming Conventions, , Installation, Overview -@section Naming Conventions - -@noindent -Except where noted, all functions defined by this package have the -same names and calling conventions as their Common Lisp counterparts. - -Following is a complete list of functions whose names were changed -from Common Lisp, usually to avoid conflicts with Emacs. In each -case, a @samp{*} has been appended to the Common Lisp name to obtain -the Emacs name: - -@example -defun* defsubst* defmacro* function* -member* assoc* rassoc* get* -remove* delete* mapcar* sort* -floor* ceiling* truncate* round* -mod* rem* random* -@end example - -Internal function and variable names in the package are prefixed -by @code{cl-}. Here is a complete list of functions @emph{not} -prefixed by @code{cl-} which were not taken from Common Lisp: - -@example -floatp-safe lexical-let lexical-let* -callf callf2 letf letf* -defsubst* -@end example - -The following simple functions and macros are defined in @file{cl.el}; -they do not cause other components like @file{cl-extra} to be loaded. - -@example -floatp-safe endp -evenp oddp plusp minusp -caaar .. cddddr -list* ldiff rest first .. tenth -copy-list subst mapcar* [2] -adjoin [3] acons pairlis pop [4] -push [4] pushnew [3,4] incf [4] decf [4] -proclaim declaim -@end example - -@noindent -[2] Only for one sequence argument or two list arguments. - -@noindent -[3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified, -and @code{:key} is not used. - -@noindent -[4] Only when @var{place} is a plain variable name. - -@iftex -@chapno=4 -@end iftex - -@node Program Structure, Predicates, Overview, Top -@chapter Program Structure - -@noindent -This section describes features of the @dfn{CL} package which have to -do with programs as a whole: advanced argument lists for functions, -and the @code{eval-when} construct. - -@menu -* Argument Lists:: @code{&key}, @code{&aux}, @code{defun*}, @code{defmacro*}. -* Time of Evaluation:: The @code{eval-when} construct. -@end menu - -@iftex -@secno=1 -@end iftex - -@node Argument Lists, Time of Evaluation, Program Structure, Program Structure -@section Argument Lists - -@noindent -Emacs Lisp's notation for argument lists of functions is a subset of -the Common Lisp notation. As well as the familiar @code{&optional} -and @code{&rest} markers, Common Lisp allows you to specify default -values for optional arguments, and it provides the additional markers -@code{&key} and @code{&aux}. - -Since argument parsing is built-in to Emacs, there is no way for -this package to implement Common Lisp argument lists seamlessly. -Instead, this package defines alternates for several Lisp forms -which you must use if you need Common Lisp argument lists. - -@defspec defun* name arglist body... -This form is identical to the regular @code{defun} form, except -that @var{arglist} is allowed to be a full Common Lisp argument -list. Also, the function body is enclosed in an implicit block -called @var{name}; @pxref{Blocks and Exits}. -@end defspec - -@defspec defsubst* name arglist body... -This is just like @code{defun*}, except that the function that -is defined is automatically proclaimed @code{inline}, i.e., -calls to it may be expanded into in-line code by the byte compiler. -This is analogous to the @code{defsubst} form; -@code{defsubst*} uses a different method (compiler macros) which -works in all versions of Emacs, and also generates somewhat more -efficient inline expansions. In particular, @code{defsubst*} -arranges for the processing of keyword arguments, default values, -etc., to be done at compile-time whenever possible. -@end defspec - -@defspec defmacro* name arglist body... -This is identical to the regular @code{defmacro} form, -except that @var{arglist} is allowed to be a full Common Lisp -argument list. The @code{&environment} keyword is supported as -described in Steele. The @code{&whole} keyword is supported only -within destructured lists (see below); top-level @code{&whole} -cannot be implemented with the current Emacs Lisp interpreter. -The macro expander body is enclosed in an implicit block called -@var{name}. -@end defspec - -@defspec function* symbol-or-lambda -This is identical to the regular @code{function} form, -except that if the argument is a @code{lambda} form then that -form may use a full Common Lisp argument list. -@end defspec - -Also, all forms (such as @code{defsetf} and @code{flet}) defined -in this package that include @var{arglist}s in their syntax allow -full Common Lisp argument lists. - -Note that it is @emph{not} necessary to use @code{defun*} in -order to have access to most @dfn{CL} features in your function. -These features are always present; @code{defun*}'s only -difference from @code{defun} is its more flexible argument -lists and its implicit block. - -The full form of a Common Lisp argument list is - -@example -(@var{var}... - &optional (@var{var} @var{initform} @var{svar})... - &rest @var{var} - &key ((@var{keyword} @var{var}) @var{initform} @var{svar})... - &aux (@var{var} @var{initform})...) -@end example - -Each of the five argument list sections is optional. The @var{svar}, -@var{initform}, and @var{keyword} parts are optional; if they are -omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}. - -The first section consists of zero or more @dfn{required} arguments. -These arguments must always be specified in a call to the function; -there is no difference between Emacs Lisp and Common Lisp as far as -required arguments are concerned. - -The second section consists of @dfn{optional} arguments. These -arguments may be specified in the function call; if they are not, -@var{initform} specifies the default value used for the argument. -(No @var{initform} means to use @code{nil} as the default.) The -@var{initform} is evaluated with the bindings for the preceding -arguments already established; @code{(a &optional (b (1+ a)))} -matches one or two arguments, with the second argument defaulting -to one plus the first argument. If the @var{svar} is specified, -it is an auxiliary variable which is bound to @code{t} if the optional -argument was specified, or to @code{nil} if the argument was omitted. -If you don't use an @var{svar}, then there will be no way for your -function to tell whether it was called with no argument, or with -the default value passed explicitly as an argument. - -The third section consists of a single @dfn{rest} argument. If -more arguments were passed to the function than are accounted for -by the required and optional arguments, those extra arguments are -collected into a list and bound to the ``rest'' argument variable. -Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp. -Common Lisp accepts @code{&body} as a synonym for @code{&rest} in -macro contexts; this package accepts it all the time. - -The fourth section consists of @dfn{keyword} arguments. These -are optional arguments which are specified by name rather than -positionally in the argument list. For example, - -@example -(defun* foo (a &optional b &key c d (e 17))) -@end example - -@noindent -defines a function which may be called with one, two, or more -arguments. The first two arguments are bound to @code{a} and -@code{b} in the usual way. The remaining arguments must be -pairs of the form @code{:c}, @code{:d}, or @code{:e} followed -by the value to be bound to the corresponding argument variable. -(Symbols whose names begin with a colon are called @dfn{keywords}, -and they are self-quoting in the same way as @code{nil} and -@code{t}.) - -For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five -arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword -appears more than once in the function call, the first occurrence -takes precedence over the later ones. Note that it is not possible -to specify keyword arguments without specifying the optional -argument @code{b} as well, since @code{(foo 1 :c 2)} would bind -@code{b} to the keyword @code{:c}, then signal an error because -@code{2} is not a valid keyword. - -You can also explicitly specify the keyword argument; it need not be -simply the variable name prefixed with a colon. For example, - -@example -(defun* bar (&key (a 1) ((baz b) 4))) -@end example - -@noindent - -specifies a keyword @code{:a} that sets the variable @code{a} with -default value 1, as well as a keyword @code{baz} that sets the -variable @code{b} with default value 4. In this case, because -@code{baz} is not self-quoting, you must quote it explicitly in the -function call, like this: - -@example -(bar :a 10 'baz 42) -@end example - -Ordinarily, it is an error to pass an unrecognized keyword to -a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask -Lisp to ignore unrecognized keywords, either by adding the -marker @code{&allow-other-keys} after the keyword section -of the argument list, or by specifying an @code{:allow-other-keys} -argument in the call whose value is non-@code{nil}. If the -function uses both @code{&rest} and @code{&key} at the same time, -the ``rest'' argument is bound to the keyword list as it appears -in the call. For example: - -@smallexample -(defun* find-thing (thing &rest rest &key need &allow-other-keys) - (or (apply 'member* thing thing-list :allow-other-keys t rest) - (if need (error "Thing not found")))) -@end smallexample - -@noindent -This function takes a @code{:need} keyword argument, but also -accepts other keyword arguments which are passed on to the -@code{member*} function. @code{allow-other-keys} is used to -keep both @code{find-thing} and @code{member*} from complaining -about each others' keywords in the arguments. - -The fifth section of the argument list consists of @dfn{auxiliary -variables}. These are not really arguments at all, but simply -variables which are bound to @code{nil} or to the specified -@var{initforms} during execution of the function. There is no -difference between the following two functions, except for a -matter of stylistic taste: - -@example -(defun* foo (a b &aux (c (+ a b)) d) - @var{body}) - -(defun* foo (a b) - (let ((c (+ a b)) d) - @var{body})) -@end example - -Argument lists support @dfn{destructuring}. In Common Lisp, -destructuring is only allowed with @code{defmacro}; this package -allows it with @code{defun*} and other argument lists as well. -In destructuring, any argument variable (@var{var} in the above -diagram) can be replaced by a list of variables, or more generally, -a recursive argument list. The corresponding argument value must -be a list whose elements match this recursive argument list. -For example: - -@example -(defmacro* dolist ((var listform &optional resultform) - &rest body) - ...) -@end example - -This says that the first argument of @code{dolist} must be a list -of two or three items; if there are other arguments as well as this -list, they are stored in @code{body}. All features allowed in -regular argument lists are allowed in these recursive argument lists. -In addition, the clause @samp{&whole @var{var}} is allowed at the -front of a recursive argument list. It binds @var{var} to the -whole list being matched; thus @code{(&whole all a b)} matches -a list of two things, with @code{a} bound to the first thing, -@code{b} bound to the second thing, and @code{all} bound to the -list itself. (Common Lisp allows @code{&whole} in top-level -@code{defmacro} argument lists as well, but Emacs Lisp does not -support this usage.) - -One last feature of destructuring is that the argument list may be -dotted, so that the argument list @code{(a b . c)} is functionally -equivalent to @code{(a b &rest c)}. - -If the optimization quality @code{safety} is set to 0 -(@pxref{Declarations}), error checking for wrong number of -arguments and invalid keyword arguments is disabled. By default, -argument lists are rigorously checked. - -@node Time of Evaluation, , Argument Lists, Program Structure -@section Time of Evaluation - -@noindent -Normally, the byte-compiler does not actually execute the forms in -a file it compiles. For example, if a file contains @code{(setq foo t)}, -the act of compiling it will not actually set @code{foo} to @code{t}. -This is true even if the @code{setq} was a top-level form (i.e., not -enclosed in a @code{defun} or other form). Sometimes, though, you -would like to have certain top-level forms evaluated at compile-time. -For example, the compiler effectively evaluates @code{defmacro} forms -at compile-time so that later parts of the file can refer to the -macros that are defined. - -@defspec eval-when (situations...) forms... -This form controls when the body @var{forms} are evaluated. -The @var{situations} list may contain any set of the symbols -@code{compile}, @code{load}, and @code{eval} (or their long-winded -ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel}, -and @code{:execute}). - -The @code{eval-when} form is handled differently depending on -whether or not it is being compiled as a top-level form. -Specifically, it gets special treatment if it is being compiled -by a command such as @code{byte-compile-file} which compiles files -or buffers of code, and it appears either literally at the -top level of the file or inside a top-level @code{progn}. - -For compiled top-level @code{eval-when}s, the body @var{forms} are -executed at compile-time if @code{compile} is in the @var{situations} -list, and the @var{forms} are written out to the file (to be executed -at load-time) if @code{load} is in the @var{situations} list. - -For non-compiled-top-level forms, only the @code{eval} situation is -relevant. (This includes forms executed by the interpreter, forms -compiled with @code{byte-compile} rather than @code{byte-compile-file}, -and non-top-level forms.) The @code{eval-when} acts like a -@code{progn} if @code{eval} is specified, and like @code{nil} -(ignoring the body @var{forms}) if not. - -The rules become more subtle when @code{eval-when}s are nested; -consult Steele (second edition) for the gruesome details (and -some gruesome examples). - -Some simple examples: - -@example -;; Top-level forms in foo.el: -(eval-when (compile) (setq foo1 'bar)) -(eval-when (load) (setq foo2 'bar)) -(eval-when (compile load) (setq foo3 'bar)) -(eval-when (eval) (setq foo4 'bar)) -(eval-when (eval compile) (setq foo5 'bar)) -(eval-when (eval load) (setq foo6 'bar)) -(eval-when (eval compile load) (setq foo7 'bar)) -@end example - -When @file{foo.el} is compiled, these variables will be set during -the compilation itself: - -@example -foo1 foo3 foo5 foo7 ; `compile' -@end example - -When @file{foo.elc} is loaded, these variables will be set: - -@example -foo2 foo3 foo6 foo7 ; `load' -@end example - -And if @file{foo.el} is loaded uncompiled, these variables will -be set: - -@example -foo4 foo5 foo6 foo7 ; `eval' -@end example - -If these seven @code{eval-when}s had been, say, inside a @code{defun}, -then the first three would have been equivalent to @code{nil} and the -last four would have been equivalent to the corresponding @code{setq}s. - -Note that @code{(eval-when (load eval) @dots{})} is equivalent -to @code{(progn @dots{})} in all contexts. The compiler treats -certain top-level forms, like @code{defmacro} (sort-of) and -@code{require}, as if they were wrapped in @code{(eval-when -(compile load eval) @dots{})}. -@end defspec - -Emacs includes two special forms related to @code{eval-when}. -One of these, @code{eval-when-compile}, is not quite equivalent to -any @code{eval-when} construct and is described below. - -The other form, @code{(eval-and-compile @dots{})}, is exactly -equivalent to @samp{(eval-when (compile load eval) @dots{})} and -so is not itself defined by this package. - -@defspec eval-when-compile forms... -The @var{forms} are evaluated at compile-time; at execution time, -this form acts like a quoted constant of the resulting value. Used -at top-level, @code{eval-when-compile} is just like @samp{eval-when -(compile eval)}. In other contexts, @code{eval-when-compile} -allows code to be evaluated once at compile-time for efficiency -or other reasons. - -This form is similar to the @samp{#.} syntax of true Common Lisp. -@end defspec - -@defspec load-time-value form -The @var{form} is evaluated at load-time; at execution time, -this form acts like a quoted constant of the resulting value. - -Early Common Lisp had a @samp{#,} syntax that was similar to -this, but ANSI Common Lisp replaced it with @code{load-time-value} -and gave it more well-defined semantics. - -In a compiled file, @code{load-time-value} arranges for @var{form} -to be evaluated when the @file{.elc} file is loaded and then used -as if it were a quoted constant. In code compiled by -@code{byte-compile} rather than @code{byte-compile-file}, the -effect is identical to @code{eval-when-compile}. In uncompiled -code, both @code{eval-when-compile} and @code{load-time-value} -act exactly like @code{progn}. - -@example -(defun report () - (insert "This function was executed on: " - (current-time-string) - ", compiled on: " - (eval-when-compile (current-time-string)) - ;; or '#.(current-time-string) in real Common Lisp - ", and loaded on: " - (load-time-value (current-time-string)))) -@end example - -@noindent -Byte-compiled, the above defun will result in the following code -(or its compiled equivalent, of course) in the @file{.elc} file: - -@example -(setq --temp-- (current-time-string)) -(defun report () - (insert "This function was executed on: " - (current-time-string) - ", compiled on: " - '"Wed Jun 23 18:33:43 1993" - ", and loaded on: " - --temp--)) -@end example -@end defspec - -@node Predicates, Control Structure, Program Structure, Top -@chapter Predicates - -@noindent -This section describes functions for testing whether various -facts are true or false. - -@menu -* Type Predicates:: @code{typep}, @code{deftype}, and @code{coerce} -* Equality Predicates:: @code{equalp} -@end menu - -@node Type Predicates, Equality Predicates, Predicates, Predicates -@section Type Predicates - -@noindent -The @dfn{CL} package defines a version of the Common Lisp @code{typep} -predicate. - -@defun typep object type -Check if @var{object} is of type @var{type}, where @var{type} is a -(quoted) type name of the sort used by Common Lisp. For example, -@code{(typep foo 'integer)} is equivalent to @code{(integerp foo)}. -@end defun - -The @var{type} argument to the above function is either a symbol -or a list beginning with a symbol. - -@itemize @bullet -@item -If the type name is a symbol, Emacs appends @samp{-p} to the -symbol name to form the name of a predicate function for testing -the type. (Built-in predicates whose names end in @samp{p} rather -than @samp{-p} are used when appropriate.) - -@item -The type symbol @code{t} stands for the union of all types. -@code{(typep @var{object} t)} is always true. Likewise, the -type symbol @code{nil} stands for nothing at all, and -@code{(typep @var{object} nil)} is always false. - -@item -The type symbol @code{null} represents the symbol @code{nil}. -Thus @code{(typep @var{object} 'null)} is equivalent to -@code{(null @var{object})}. - -@item -The type symbol @code{atom} represents all objects that are not cons -cells. Thus @code{(typep @var{object} 'atom)} is equivalent to -@code{(atom @var{object})}. - -@item -The type symbol @code{real} is a synonym for @code{number}, and -@code{fixnum} is a synonym for @code{integer}. - -@item -The type symbols @code{character} and @code{string-char} match -integers in the range from 0 to 255. - -@item -The type symbol @code{float} uses the @code{floatp-safe} predicate -defined by this package rather than @code{floatp}, so it will work -correctly even in Emacs versions without floating-point support. - -@item -The type list @code{(integer @var{low} @var{high})} represents all -integers between @var{low} and @var{high}, inclusive. Either bound -may be a list of a single integer to specify an exclusive limit, -or a @code{*} to specify no limit. The type @code{(integer * *)} -is thus equivalent to @code{integer}. - -@item -Likewise, lists beginning with @code{float}, @code{real}, or -@code{number} represent numbers of that type falling in a particular -range. - -@item -Lists beginning with @code{and}, @code{or}, and @code{not} form -combinations of types. For example, @code{(or integer (float 0 *))} -represents all objects that are integers or non-negative floats. - -@item -Lists beginning with @code{member} or @code{member*} represent -objects @code{eql} to any of the following values. For example, -@code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)}, -and @code{(member nil)} is equivalent to @code{null}. - -@item -Lists of the form @code{(satisfies @var{predicate})} represent -all objects for which @var{predicate} returns true when called -with that object as an argument. -@end itemize - -The following function and macro (not technically predicates) are -related to @code{typep}. - -@defun coerce object type -This function attempts to convert @var{object} to the specified -@var{type}. If @var{object} is already of that type as determined by -@code{typep}, it is simply returned. Otherwise, certain types of -conversions will be made: If @var{type} is any sequence type -(@code{string}, @code{list}, etc.) then @var{object} will be -converted to that type if possible. If @var{type} is -@code{character}, then strings of length one and symbols with -one-character names can be coerced. If @var{type} is @code{float}, -then integers can be coerced in versions of Emacs that support -floats. In all other circumstances, @code{coerce} signals an -error. -@end defun - -@defspec deftype name arglist forms... -This macro defines a new type called @var{name}. It is similar -to @code{defmacro} in many ways; when @var{name} is encountered -as a type name, the body @var{forms} are evaluated and should -return a type specifier that is equivalent to the type. The -@var{arglist} is a Common Lisp argument list of the sort accepted -by @code{defmacro*}. The type specifier @samp{(@var{name} @var{args}...)} -is expanded by calling the expander with those arguments; the type -symbol @samp{@var{name}} is expanded by calling the expander with -no arguments. The @var{arglist} is processed the same as for -@code{defmacro*} except that optional arguments without explicit -defaults use @code{*} instead of @code{nil} as the ``default'' -default. Some examples: - -@example -(deftype null () '(satisfies null)) ; predefined -(deftype list () '(or null cons)) ; predefined -(deftype unsigned-byte (&optional bits) - (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits))))) -(unsigned-byte 8) @equiv{} (integer 0 255) -(unsigned-byte) @equiv{} (integer 0 *) -unsigned-byte @equiv{} (integer 0 *) -@end example - -@noindent -The last example shows how the Common Lisp @code{unsigned-byte} -type specifier could be implemented if desired; this package does -not implement @code{unsigned-byte} by default. -@end defspec - -The @code{typecase} and @code{check-type} macros also use type -names. @xref{Conditionals}. @xref{Assertions}. The @code{map}, -@code{concatenate}, and @code{merge} functions take type-name -arguments to specify the type of sequence to return. @xref{Sequences}. - -@node Equality Predicates, , Type Predicates, Predicates -@section Equality Predicates - -@noindent -This package defines the Common Lisp predicate @code{equalp}. - -@defun equalp a b -This function is a more flexible version of @code{equal}. In -particular, it compares strings case-insensitively, and it compares -numbers without regard to type (so that @code{(equalp 3 3.0)} is -true). Vectors and conses are compared recursively. All other -objects are compared as if by @code{equal}. - -This function differs from Common Lisp @code{equalp} in several -respects. First, Common Lisp's @code{equalp} also compares -@emph{characters} case-insensitively, which would be impractical -in this package since Emacs does not distinguish between integers -and characters. In keeping with the idea that strings are less -vector-like in Emacs Lisp, this package's @code{equalp} also will -not compare strings against vectors of integers. -@end defun - -Also note that the Common Lisp functions @code{member} and @code{assoc} -use @code{eql} to compare elements, whereas Emacs Lisp follows the -MacLisp tradition and uses @code{equal} for these two functions. -In Emacs, use @code{member*} and @code{assoc*} to get functions -which use @code{eql} for comparisons. - -@node Control Structure, Macros, Predicates, Top -@chapter Control Structure - -@noindent -The features described in the following sections implement -various advanced control structures, including the powerful -@code{setf} facility and a number of looping and conditional -constructs. - -@menu -* Assignment:: The @code{psetq} form -* Generalized Variables:: @code{setf}, @code{incf}, @code{push}, etc. -* Variable Bindings:: @code{progv}, @code{lexical-let}, @code{flet}, @code{macrolet} -* Conditionals:: @code{case}, @code{typecase} -* Blocks and Exits:: @code{block}, @code{return}, @code{return-from} -* Iteration:: @code{do}, @code{dotimes}, @code{dolist}, @code{do-symbols} -* Loop Facility:: The Common Lisp @code{loop} macro -* Multiple Values:: @code{values}, @code{multiple-value-bind}, etc. -@end menu - -@node Assignment, Generalized Variables, Control Structure, Control Structure -@section Assignment - -@noindent -The @code{psetq} form is just like @code{setq}, except that multiple -assignments are done in parallel rather than sequentially. - -@defspec psetq [symbol form]@dots{} -This special form (actually a macro) is used to assign to several -variables simultaneously. Given only one @var{symbol} and @var{form}, -it has the same effect as @code{setq}. Given several @var{symbol} -and @var{form} pairs, it evaluates all the @var{form}s in advance -and then stores the corresponding variables afterwards. - -@example -(setq x 2 y 3) -(setq x (+ x y) y (* x y)) -x - @result{} 5 -y ; @r{@code{y} was computed after @code{x} was set.} - @result{} 15 -(setq x 2 y 3) -(psetq x (+ x y) y (* x y)) -x - @result{} 5 -y ; @r{@code{y} was computed before @code{x} was set.} - @result{} 6 -@end example - -The simplest use of @code{psetq} is @code{(psetq x y y x)}, which -exchanges the values of two variables. (The @code{rotatef} form -provides an even more convenient way to swap two variables; -@pxref{Modify Macros}.) - -@code{psetq} always returns @code{nil}. -@end defspec - -@node Generalized Variables, Variable Bindings, Assignment, Control Structure -@section Generalized Variables - -@noindent -A ``generalized variable'' or ``place form'' is one of the many places -in Lisp memory where values can be stored. The simplest place form is -a regular Lisp variable. But the cars and cdrs of lists, elements -of arrays, properties of symbols, and many other locations are also -places where Lisp values are stored. - -The @code{setf} form is like @code{setq}, except that it accepts -arbitrary place forms on the left side rather than just -symbols. For example, @code{(setf (car a) b)} sets the car of -@code{a} to @code{b}, doing the same operation as @code{(setcar a b)} -but without having to remember two separate functions for setting -and accessing every type of place. - -Generalized variables are analogous to ``lvalues'' in the C -language, where @samp{x = a[i]} gets an element from an array -and @samp{a[i] = x} stores an element using the same notation. -Just as certain forms like @code{a[i]} can be lvalues in C, there -is a set of forms that can be generalized variables in Lisp. - -@menu -* Basic Setf:: @code{setf} and place forms -* Modify Macros:: @code{incf}, @code{push}, @code{rotatef}, @code{letf}, @code{callf}, etc. -* Customizing Setf:: @code{define-modify-macro}, @code{defsetf}, @code{define-setf-method} -@end menu - -@node Basic Setf, Modify Macros, Generalized Variables, Generalized Variables -@subsection Basic Setf - -@noindent -The @code{setf} macro is the most basic way to operate on generalized -variables. - -@defspec setf [place form]@dots{} -This macro evaluates @var{form} and stores it in @var{place}, which -must be a valid generalized variable form. If there are several -@var{place} and @var{form} pairs, the assignments are done sequentially -just as with @code{setq}. @code{setf} returns the value of the last -@var{form}. - -The following Lisp forms will work as generalized variables, and -so may appear in the @var{place} argument of @code{setf}: - -@itemize @bullet -@item -A symbol naming a variable. In other words, @code{(setf x y)} is -exactly equivalent to @code{(setq x y)}, and @code{setq} itself is -strictly speaking redundant now that @code{setf} exists. Many -programmers continue to prefer @code{setq} for setting simple -variables, though, purely for stylistic or historical reasons. -The macro @code{(setf x y)} actually expands to @code{(setq x y)}, -so there is no performance penalty for using it in compiled code. - -@item -A call to any of the following Lisp functions: - -@smallexample -car cdr caar .. cddddr -nth rest first .. tenth -aref elt nthcdr -symbol-function symbol-value symbol-plist -get get* getf -gethash subseq -@end smallexample - -@noindent -Note that for @code{nthcdr} and @code{getf}, the list argument -of the function must itself be a valid @var{place} form. For -example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself -to 7. Note that @code{push} and @code{pop} on an @code{nthcdr} -place can be used to insert or delete at any position in a list. -The use of @code{nthcdr} as a @var{place} form is an extension -to standard Common Lisp. - -@item -The following Emacs-specific functions are also @code{setf}-able. - -@smallexample -buffer-file-name marker-position -buffer-modified-p match-data -buffer-name mouse-position -buffer-string overlay-end -buffer-substring overlay-get -current-buffer overlay-start -current-case-table point -current-column point-marker -current-global-map point-max -current-input-mode point-min -current-local-map process-buffer -current-window-configuration process-filter -default-file-modes process-sentinel -default-value read-mouse-position -documentation-property screen-height -extent-data screen-menubar -extent-end-position screen-width -extent-start-position selected-window -face-background selected-screen -face-background-pixmap selected-frame -face-font standard-case-table -face-foreground syntax-table -face-underline-p window-buffer -file-modes window-dedicated-p -frame-height window-display-table -frame-parameters window-height -frame-visible-p window-hscroll -frame-width window-point -get-register window-start -getenv window-width -global-key-binding x-get-secondary-selection -keymap-parent x-get-selection -local-key-binding -mark -mark-marker -@end smallexample - -Most of these have directly corresponding ``set'' functions, like -@code{use-local-map} for @code{current-local-map}, or @code{goto-char} -for @code{point}. A few, like @code{point-min}, expand to longer -sequences of code when they are @code{setf}'d (@code{(narrow-to-region -x (point-max))} in this case). - -@item -A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])}, -where @var{subplace} is itself a valid generalized variable whose -current value is a string, and where the value stored is also a -string. The new string is spliced into the specified part of the -destination string. For example: - -@example -(setq a (list "hello" "world")) - @result{} ("hello" "world") -(cadr a) - @result{} "world" -(substring (cadr a) 2 4) - @result{} "rl" -(setf (substring (cadr a) 2 4) "o") - @result{} "o" -(cadr a) - @result{} "wood" -a - @result{} ("hello" "wood") -@end example - -The generalized variable @code{buffer-substring}, listed above, -also works in this way by replacing a portion of the current buffer. - -@item -A call of the form @code{(apply '@var{func} @dots{})} or -@code{(apply (function @var{func}) @dots{})}, where @var{func} -is a @code{setf}-able function whose store function is ``suitable'' -in the sense described in Steele's book; since none of the standard -Emacs place functions are suitable in this sense, this feature is -only interesting when used with places you define yourself with -@code{define-setf-method} or the long form of @code{defsetf}. - -@item -A macro call, in which case the macro is expanded and @code{setf} -is applied to the resulting form. - -@item -Any form for which a @code{defsetf} or @code{define-setf-method} -has been made. -@end itemize - -Using any forms other than these in the @var{place} argument to -@code{setf} will signal an error. - -The @code{setf} macro takes care to evaluate all subforms in -the proper left-to-right order; for example, - -@example -(setf (aref vec (incf i)) i) -@end example - -@noindent -looks like it will evaluate @code{(incf i)} exactly once, before the -following access to @code{i}; the @code{setf} expander will insert -temporary variables as necessary to ensure that it does in fact work -this way no matter what setf-method is defined for @code{aref}. -(In this case, @code{aset} would be used and no such steps would -be necessary since @code{aset} takes its arguments in a convenient -order.) - -However, if the @var{place} form is a macro which explicitly -evaluates its arguments in an unusual order, this unusual order -will be preserved. Adapting an example from Steele, given - -@example -(defmacro wrong-order (x y) (list 'aref y x)) -@end example - -@noindent -the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will -evaluate @var{b} first, then @var{a}, just as in an actual call -to @code{wrong-order}. -@end defspec - -@node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables -@subsection Modify Macros - -@noindent -This package defines a number of other macros besides @code{setf} -that operate on generalized variables. Many are interesting and -useful even when the @var{place} is just a variable name. - -@defspec psetf [place form]@dots{} -This macro is to @code{setf} what @code{psetq} is to @code{setq}: -When several @var{place}s and @var{form}s are involved, the -assignments take place in parallel rather than sequentially. -Specifically, all subforms are evaluated from left to right, then -all the assignments are done (in an undefined order). -@end defspec - -@defspec incf place &optional x -This macro increments the number stored in @var{place} by one, or -by @var{x} if specified. The incremented value is returned. For -example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and -@code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}. - -Once again, care is taken to preserve the ``apparent'' order of -evaluation. For example, - -@example -(incf (aref vec (incf i))) -@end example - -@noindent -appears to increment @code{i} once, then increment the element of -@code{vec} addressed by @code{i}; this is indeed exactly what it -does, which means the above form is @emph{not} equivalent to the -``obvious'' expansion, - -@example -(setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong! -@end example - -@noindent -but rather to something more like - -@example -(let ((temp (incf i))) - (setf (aref vec temp) (1+ (aref vec temp)))) -@end example - -@noindent -Again, all of this is taken care of automatically by @code{incf} and -the other generalized-variable macros. - -As a more Emacs-specific example of @code{incf}, the expression -@code{(incf (point) @var{n})} is essentially equivalent to -@code{(forward-char @var{n})}. -@end defspec - -@defspec decf place &optional x -This macro decrements the number stored in @var{place} by one, or -by @var{x} if specified. -@end defspec - -@defspec pop place -This macro removes and returns the first element of the list stored -in @var{place}. It is analogous to @code{(prog1 (car @var{place}) -(setf @var{place} (cdr @var{place})))}, except that it takes care -to evaluate all subforms only once. -@end defspec - -@defspec push x place -This macro inserts @var{x} at the front of the list stored in -@var{place}. It is analogous to @code{(setf @var{place} (cons -@var{x} @var{place}))}, except for evaluation of the subforms. -@end defspec - -@defspec pushnew x place @t{&key :test :test-not :key} -This macro inserts @var{x} at the front of the list stored in -@var{place}, but only if @var{x} was not @code{eql} to any -existing element of the list. The optional keyword arguments -are interpreted in the same way as for @code{adjoin}. -@xref{Lists as Sets}. -@end defspec - -@defspec shiftf place@dots{} newvalue -This macro shifts the @var{place}s left by one, shifting in the -value of @var{newvalue} (which may be any Lisp expression, not just -a generalized variable), and returning the value shifted out of -the first @var{place}. Thus, @code{(shiftf @var{a} @var{b} @var{c} -@var{d})} is equivalent to - -@example -(prog1 - @var{a} - (psetf @var{a} @var{b} - @var{b} @var{c} - @var{c} @var{d})) -@end example - -@noindent -except that the subforms of @var{a}, @var{b}, and @var{c} are actually -evaluated only once each and in the apparent order. -@end defspec - -@defspec rotatef place@dots{} -This macro rotates the @var{place}s left by one in circular fashion. -Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to - -@example -(psetf @var{a} @var{b} - @var{b} @var{c} - @var{c} @var{d} - @var{d} @var{a}) -@end example - -@noindent -except for the evaluation of subforms. @code{rotatef} always -returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})} -conveniently exchanges @var{a} and @var{b}. -@end defspec - -The following macros were invented for this package; they have no -analogues in Common Lisp. - -@defspec letf (bindings@dots{}) forms@dots{} -This macro is analogous to @code{let}, but for generalized variables -rather than just symbols. Each @var{binding} should be of the form -@code{(@var{place} @var{value})}; the original contents of the -@var{place}s are saved, the @var{value}s are stored in them, and -then the body @var{form}s are executed. Afterwards, the @var{places} -are set back to their original saved contents. This cleanup happens -even if the @var{form}s exit irregularly due to a @code{throw} or an -error. - -For example, - -@example -(letf (((point) (point-min)) - (a 17)) - ...) -@end example - -@noindent -moves ``point'' in the current buffer to the beginning of the buffer, -and also binds @code{a} to 17 (as if by a normal @code{let}, since -@code{a} is just a regular variable). After the body exits, @code{a} -is set back to its original value and point is moved back to its -original position. - -Note that @code{letf} on @code{(point)} is not quite like a -@code{save-excursion}, as the latter effectively saves a marker -which tracks insertions and deletions in the buffer. Actually, -a @code{letf} of @code{(point-marker)} is much closer to this -behavior. (@code{point} and @code{point-marker} are equivalent -as @code{setf} places; each will accept either an integer or a -marker as the stored value.) - -Since generalized variables look like lists, @code{let}'s shorthand -of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would -be ambiguous in @code{letf} and is not allowed. - -However, a @var{binding} specifier may be a one-element list -@samp{(@var{place})}, which is similar to @samp{(@var{place} -@var{place})}. In other words, the @var{place} is not disturbed -on entry to the body, and the only effect of the @code{letf} is -to restore the original value of @var{place} afterwards. (The -redundant access-and-store suggested by the @code{(@var{place} -@var{place})} example does not actually occur.) - -In most cases, the @var{place} must have a well-defined value on -entry to the @code{letf} form. The only exceptions are plain -variables and calls to @code{symbol-value} and @code{symbol-function}. -If the symbol is not bound on entry, it is simply made unbound by -@code{makunbound} or @code{fmakunbound} on exit. -@end defspec - -@defspec letf* (bindings@dots{}) forms@dots{} -This macro is to @code{letf} what @code{let*} is to @code{let}: -It does the bindings in sequential rather than parallel order. -@end defspec - -@defspec callf @var{function} @var{place} @var{args}@dots{} -This is the ``generic'' modify macro. It calls @var{function}, -which should be an unquoted function name, macro name, or lambda. -It passes @var{place} and @var{args} as arguments, and assigns the -result back to @var{place}. For example, @code{(incf @var{place} -@var{n})} is the same as @code{(callf + @var{place} @var{n})}. -Some more examples: - -@example -(callf abs my-number) -(callf concat (buffer-name) "<" (int-to-string n) ">") -(callf union happy-people (list joe bob) :test 'same-person) -@end example - -@xref{Customizing Setf}, for @code{define-modify-macro}, a way -to create even more concise notations for modify macros. Note -again that @code{callf} is an extension to standard Common Lisp. -@end defspec - -@defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} -This macro is like @code{callf}, except that @var{place} is -the @emph{second} argument of @var{function} rather than the -first. For example, @code{(push @var{x} @var{place})} is -equivalent to @code{(callf2 cons @var{x} @var{place})}. -@end defspec - -The @code{callf} and @code{callf2} macros serve as building -blocks for other macros like @code{incf}, @code{pushnew}, and -@code{define-modify-macro}. The @code{letf} and @code{letf*} -macros are used in the processing of symbol macros; -@pxref{Macro Bindings}. - -@node Customizing Setf, , Modify Macros, Generalized Variables -@subsection Customizing Setf - -@noindent -Common Lisp defines three macros, @code{define-modify-macro}, -@code{defsetf}, and @code{define-setf-method}, that allow the -user to extend generalized variables in various ways. - -@defspec define-modify-macro name arglist function [doc-string] -This macro defines a ``read-modify-write'' macro similar to -@code{incf} and @code{decf}. The macro @var{name} is defined -to take a @var{place} argument followed by additional arguments -described by @var{arglist}. The call - -@example -(@var{name} @var{place} @var{args}...) -@end example - -@noindent -will be expanded to - -@example -(callf @var{func} @var{place} @var{args}...) -@end example - -@noindent -which in turn is roughly equivalent to - -@example -(setf @var{place} (@var{func} @var{place} @var{args}...)) -@end example - -For example: - -@example -(define-modify-macro incf (&optional (n 1)) +) -(define-modify-macro concatf (&rest args) concat) -@end example - -Note that @code{&key} is not allowed in @var{arglist}, but -@code{&rest} is sufficient to pass keywords on to the function. - -Most of the modify macros defined by Common Lisp do not exactly -follow the pattern of @code{define-modify-macro}. For example, -@code{push} takes its arguments in the wrong order, and @code{pop} -is completely irregular. You can define these macros ``by hand'' -using @code{get-setf-method}, or consult the source file -@file{cl-macs.el} to see how to use the internal @code{setf} -building blocks. -@end defspec - -@defspec defsetf access-fn update-fn -This is the simpler of two @code{defsetf} forms. Where -@var{access-fn} is the name of a function which accesses a place, -this declares @var{update-fn} to be the corresponding store -function. From now on, - -@example -(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value}) -@end example - -@noindent -will be expanded to - -@example -(@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value}) -@end example - -@noindent -The @var{update-fn} is required to be either a true function, or -a macro which evaluates its arguments in a function-like way. Also, -the @var{update-fn} is expected to return @var{value} as its result. -Otherwise, the above expansion would not obey the rules for the way -@code{setf} is supposed to behave. - -As a special (non-Common-Lisp) extension, a third argument of @code{t} -to @code{defsetf} says that the @code{update-fn}'s return value is -not suitable, so that the above @code{setf} should be expanded to -something more like - -@example -(let ((temp @var{value})) - (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp) - temp) -@end example - -Some examples of the use of @code{defsetf}, drawn from the standard -suite of setf methods, are: - -@example -(defsetf car setcar) -(defsetf symbol-value set) -(defsetf buffer-name rename-buffer t) -@end example -@end defspec - -@defspec defsetf access-fn arglist (store-var) forms@dots{} -This is the second, more complex, form of @code{defsetf}. It is -rather like @code{defmacro} except for the additional @var{store-var} -argument. The @var{forms} should return a Lisp form which stores -the value of @var{store-var} into the generalized variable formed -by a call to @var{access-fn} with arguments described by @var{arglist}. -The @var{forms} may begin with a string which documents the @code{setf} -method (analogous to the doc string that appears at the front of a -function). - -For example, the simple form of @code{defsetf} is shorthand for - -@example -(defsetf @var{access-fn} (&rest args) (store) - (append '(@var{update-fn}) args (list store))) -@end example - -The Lisp form that is returned can access the arguments from -@var{arglist} and @var{store-var} in an unrestricted fashion; -macros like @code{setf} and @code{incf} which invoke this -setf-method will insert temporary variables as needed to make -sure the apparent order of evaluation is preserved. - -Another example drawn from the standard package: - -@example -(defsetf nth (n x) (store) - (list 'setcar (list 'nthcdr n x) store)) -@end example -@end defspec - -@defspec define-setf-method access-fn arglist forms@dots{} -This is the most general way to create new place forms. When -a @code{setf} to @var{access-fn} with arguments described by -@var{arglist} is expanded, the @var{forms} are evaluated and -must return a list of five items: - -@enumerate -@item -A list of @dfn{temporary variables}. - -@item -A list of @dfn{value forms} corresponding to the temporary variables -above. The temporary variables will be bound to these value forms -as the first step of any operation on the generalized variable. - -@item -A list of exactly one @dfn{store variable} (generally obtained -from a call to @code{gensym}). - -@item -A Lisp form which stores the contents of the store variable into -the generalized variable, assuming the temporaries have been -bound as described above. - -@item -A Lisp form which accesses the contents of the generalized variable, -assuming the temporaries have been bound. -@end enumerate - -This is exactly like the Common Lisp macro of the same name, -except that the method returns a list of five values rather -than the five values themselves, since Emacs Lisp does not -support Common Lisp's notion of multiple return values. - -Once again, the @var{forms} may begin with a documentation string. - -A setf-method should be maximally conservative with regard to -temporary variables. In the setf-methods generated by -@code{defsetf}, the second return value is simply the list of -arguments in the place form, and the first return value is a -list of a corresponding number of temporary variables generated -by @code{gensym}. Macros like @code{setf} and @code{incf} which -use this setf-method will optimize away most temporaries that -turn out to be unnecessary, so there is little reason for the -setf-method itself to optimize. -@end defspec - -@defun get-setf-method place &optional env -This function returns the setf-method for @var{place}, by -invoking the definition previously recorded by @code{defsetf} -or @code{define-setf-method}. The result is a list of five -values as described above. You can use this function to build -your own @code{incf}-like modify macros. (Actually, it is -better to use the internal functions @code{cl-setf-do-modify} -and @code{cl-setf-do-store}, which are a bit easier to use and -which also do a number of optimizations; consult the source -code for the @code{incf} function for a simple example.) - -The argument @var{env} specifies the ``environment'' to be -passed on to @code{macroexpand} if @code{get-setf-method} should -need to expand a macro in @var{place}. It should come from -an @code{&environment} argument to the macro or setf-method -that called @code{get-setf-method}. - -See also the source code for the setf-methods for @code{apply} -and @code{substring}, each of which works by calling -@code{get-setf-method} on a simpler case, then massaging -the result in various ways. -@end defun - -Modern Common Lisp defines a second, independent way to specify -the @code{setf} behavior of a function, namely ``@code{setf} -functions'' whose names are lists @code{(setf @var{name})} -rather than symbols. For example, @code{(defun (setf foo) @dots{})} -defines the function that is used when @code{setf} is applied to -@code{foo}. This package does not currently support @code{setf} -functions. In particular, it is a compile-time error to use -@code{setf} on a form which has not already been @code{defsetf}'d -or otherwise declared; in newer Common Lisps, this would not be -an error since the function @code{(setf @var{func})} might be -defined later. - -@iftex -@secno=4 -@end iftex - -@node Variable Bindings, Conditionals, Generalized Variables, Control Structure -@section Variable Bindings - -@noindent -These Lisp forms make bindings to variables and function names, -analogous to Lisp's built-in @code{let} form. - -@xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which -are also related to variable bindings. - -@menu -* Dynamic Bindings:: The @code{progv} form -* Lexical Bindings:: @code{lexical-let} and lexical closures -* Function Bindings:: @code{flet} and @code{labels} -* Macro Bindings:: @code{macrolet} and @code{symbol-macrolet} -@end menu - -@node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings -@subsection Dynamic Bindings - -@noindent -The standard @code{let} form binds variables whose names are known -at compile-time. The @code{progv} form provides an easy way to -bind variables whose names are computed at run-time. - -@defspec progv symbols values forms@dots{} -This form establishes @code{let}-style variable bindings on a -set of variables computed at run-time. The expressions -@var{symbols} and @var{values} are evaluated, and must return lists -of symbols and values, respectively. The symbols are bound to the -corresponding values for the duration of the body @var{form}s. -If @var{values} is shorter than @var{symbols}, the last few symbols -are made unbound (as if by @code{makunbound}) inside the body. -If @var{symbols} is shorter than @var{values}, the excess values -are ignored. -@end defspec - -@node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings -@subsection Lexical Bindings - -@noindent -The @dfn{CL} package defines the following macro which -more closely follows the Common Lisp @code{let} form: - -@defspec lexical-let (bindings@dots{}) forms@dots{} -This form is exactly like @code{let} except that the bindings it -establishes are purely lexical. Lexical bindings are similar to -local variables in a language like C: Only the code physically -within the body of the @code{lexical-let} (after macro expansion) -may refer to the bound variables. - -@example -(setq a 5) -(defun foo (b) (+ a b)) -(let ((a 2)) (foo a)) - @result{} 4 -(lexical-let ((a 2)) (foo a)) - @result{} 7 -@end example - -@noindent -In this example, a regular @code{let} binding of @code{a} actually -makes a temporary change to the global variable @code{a}, so @code{foo} -is able to see the binding of @code{a} to 2. But @code{lexical-let} -actually creates a distinct local variable @code{a} for use within its -body, without any effect on the global variable of the same name. - -The most important use of lexical bindings is to create @dfn{closures}. -A closure is a function object that refers to an outside lexical -variable. For example: - -@example -(defun make-adder (n) - (lexical-let ((n n)) - (function (lambda (m) (+ n m))))) -(setq add17 (make-adder 17)) -(funcall add17 4) - @result{} 21 -@end example - -@noindent -The call @code{(make-adder 17)} returns a function object which adds -17 to its argument. If @code{let} had been used instead of -@code{lexical-let}, the function object would have referred to the -global @code{n}, which would have been bound to 17 only during the -call to @code{make-adder} itself. - -@example -(defun make-counter () - (lexical-let ((n 0)) - (function* (lambda (&optional (m 1)) (incf n m))))) -(setq count-1 (make-counter)) -(funcall count-1 3) - @result{} 3 -(funcall count-1 14) - @result{} 17 -(setq count-2 (make-counter)) -(funcall count-2 5) - @result{} 5 -(funcall count-1 2) - @result{} 19 -(funcall count-2) - @result{} 6 -@end example - -@noindent -Here we see that each call to @code{make-counter} creates a distinct -local variable @code{n}, which serves as a private counter for the -function object that is returned. - -Closed-over lexical variables persist until the last reference to -them goes away, just like all other Lisp objects. For example, -@code{count-2} refers to a function object which refers to an -instance of the variable @code{n}; this is the only reference -to that variable, so after @code{(setq count-2 nil)} the garbage -collector would be able to delete this instance of @code{n}. -Of course, if a @code{lexical-let} does not actually create any -closures, then the lexical variables are free as soon as the -@code{lexical-let} returns. - -Many closures are used only during the extent of the bindings they -refer to; these are known as ``downward funargs'' in Lisp parlance. -When a closure is used in this way, regular Emacs Lisp dynamic -bindings suffice and will be more efficient than @code{lexical-let} -closures: - -@example -(defun add-to-list (x list) - (mapcar (lambda (y) (+ x y))) list) -(add-to-list 7 '(1 2 5)) - @result{} (8 9 12) -@end example - -@noindent -Since this lambda is only used while @code{x} is still bound, -it is not necessary to make a true closure out of it. - -You can use @code{defun} or @code{flet} inside a @code{lexical-let} -to create a named closure. If several closures are created in the -body of a single @code{lexical-let}, they all close over the same -instance of the lexical variable. - -The @code{lexical-let} form is an extension to Common Lisp. In -true Common Lisp, all bindings are lexical unless declared otherwise. -@end defspec - -@defspec lexical-let* (bindings@dots{}) forms@dots{} -This form is just like @code{lexical-let}, except that the bindings -are made sequentially in the manner of @code{let*}. -@end defspec - -@node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings -@subsection Function Bindings - -@noindent -These forms make @code{let}-like bindings to functions instead -of variables. - -@defspec flet (bindings@dots{}) forms@dots{} -This form establishes @code{let}-style bindings on the function -cells of symbols rather than on the value cells. Each @var{binding} -must be a list of the form @samp{(@var{name} @var{arglist} -@var{forms}@dots{})}, which defines a function exactly as if -it were a @code{defun*} form. The function @var{name} is defined -accordingly for the duration of the body of the @code{flet}; then -the old function definition, or lack thereof, is restored. - -While @code{flet} in Common Lisp establishes a lexical binding of -@var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The -result is that @code{flet} affects indirect calls to a function as -well as calls directly inside the @code{flet} form itself. - -You can use @code{flet} to disable or modify the behavior of a -function in a temporary fashion. This will even work on Emacs -primitives, although note that some calls to primitive functions -internal to Emacs are made without going through the symbol's -function cell, and so will not be affected by @code{flet}. For -example, - -@example -(flet ((message (&rest args) (push args saved-msgs))) - (do-something)) -@end example - -This code attempts to replace the built-in function @code{message} -with a function that simply saves the messages in a list rather -than displaying them. The original definition of @code{message} -will be restored after @code{do-something} exits. This code will -work fine on messages generated by other Lisp code, but messages -generated directly inside Emacs will not be caught since they make -direct C-language calls to the message routines rather than going -through the Lisp @code{message} function. - -@c Bug#411. -Also note that many primitives (e.g. @code{+}) have special byte-compile -handling. Attempts to redefine such functions using @code{flet} will -fail if byte-compiled. In such cases, use @code{labels} instead. - -Functions defined by @code{flet} may use the full Common Lisp -argument notation supported by @code{defun*}; also, the function -body is enclosed in an implicit block as if by @code{defun*}. -@xref{Program Structure}. -@end defspec - -@defspec labels (bindings@dots{}) forms@dots{} -The @code{labels} form is like @code{flet}, except that it -makes lexical bindings of the function names rather than -dynamic bindings. (In true Common Lisp, both @code{flet} and -@code{labels} make lexical bindings of slightly different sorts; -since Emacs Lisp is dynamically bound by default, it seemed -more appropriate for @code{flet} also to use dynamic binding. -The @code{labels} form, with its lexical binding, is fully -compatible with Common Lisp.) - -Lexical scoping means that all references to the named -functions must appear physically within the body of the -@code{labels} form. References may appear both in the body -@var{forms} of @code{labels} itself, and in the bodies of -the functions themselves. Thus, @code{labels} can define -local recursive functions, or mutually-recursive sets of -functions. - -A ``reference'' to a function name is either a call to that -function, or a use of its name quoted by @code{quote} or -@code{function} to be passed on to, say, @code{mapcar}. -@end defspec - -@node Macro Bindings, , Function Bindings, Variable Bindings -@subsection Macro Bindings - -@noindent -These forms create local macros and ``symbol macros.'' - -@defspec macrolet (bindings@dots{}) forms@dots{} -This form is analogous to @code{flet}, but for macros instead of -functions. Each @var{binding} is a list of the same form as the -arguments to @code{defmacro*} (i.e., a macro name, argument list, -and macro-expander forms). The macro is defined accordingly for -use within the body of the @code{macrolet}. - -Because of the nature of macros, @code{macrolet} is lexically -scoped even in Emacs Lisp: The @code{macrolet} binding will -affect only calls that appear physically within the body -@var{forms}, possibly after expansion of other macros in the -body. -@end defspec - -@defspec symbol-macrolet (bindings@dots{}) forms@dots{} -This form creates @dfn{symbol macros}, which are macros that look -like variable references rather than function calls. Each -@var{binding} is a list @samp{(@var{var} @var{expansion})}; -any reference to @var{var} within the body @var{forms} is -replaced by @var{expansion}. - -@example -(setq bar '(5 . 9)) -(symbol-macrolet ((foo (car bar))) - (incf foo)) -bar - @result{} (6 . 9) -@end example - -A @code{setq} of a symbol macro is treated the same as a @code{setf}. -I.e., @code{(setq foo 4)} in the above would be equivalent to -@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}. - -Likewise, a @code{let} or @code{let*} binding a symbol macro is -treated like a @code{letf} or @code{letf*}. This differs from true -Common Lisp, where the rules of lexical scoping cause a @code{let} -binding to shadow a @code{symbol-macrolet} binding. In this package, -only @code{lexical-let} and @code{lexical-let*} will shadow a symbol -macro. - -There is no analogue of @code{defmacro} for symbol macros; all symbol -macros are local. A typical use of @code{symbol-macrolet} is in the -expansion of another macro: - -@example -(defmacro* my-dolist ((x list) &rest body) - (let ((var (gensym))) - (list 'loop 'for var 'on list 'do - (list* 'symbol-macrolet (list (list x (list 'car var))) - body)))) - -(setq mylist '(1 2 3 4)) -(my-dolist (x mylist) (incf x)) -mylist - @result{} (2 3 4 5) -@end example - -@noindent -In this example, the @code{my-dolist} macro is similar to @code{dolist} -(@pxref{Iteration}) except that the variable @code{x} becomes a true -reference onto the elements of the list. The @code{my-dolist} call -shown here expands to - -@example -(loop for G1234 on mylist do - (symbol-macrolet ((x (car G1234))) - (incf x))) -@end example - -@noindent -which in turn expands to - -@example -(loop for G1234 on mylist do (incf (car G1234))) -@end example - -@xref{Loop Facility}, for a description of the @code{loop} macro. -This package defines a nonstandard @code{in-ref} loop clause that -works much like @code{my-dolist}. -@end defspec - -@node Conditionals, Blocks and Exits, Variable Bindings, Control Structure -@section Conditionals - -@noindent -These conditional forms augment Emacs Lisp's simple @code{if}, -@code{and}, @code{or}, and @code{cond} forms. - -@defspec case keyform clause@dots{} -This macro evaluates @var{keyform}, then compares it with the key -values listed in the various @var{clause}s. Whichever clause matches -the key is executed; comparison is done by @code{eql}. If no clause -matches, the @code{case} form returns @code{nil}. The clauses are -of the form - -@example -(@var{keylist} @var{body-forms}@dots{}) -@end example - -@noindent -where @var{keylist} is a list of key values. If there is exactly -one value, and it is not a cons cell or the symbol @code{nil} or -@code{t}, then it can be used by itself as a @var{keylist} without -being enclosed in a list. All key values in the @code{case} form -must be distinct. The final clauses may use @code{t} in place of -a @var{keylist} to indicate a default clause that should be taken -if none of the other clauses match. (The symbol @code{otherwise} -is also recognized in place of @code{t}. To make a clause that -matches the actual symbol @code{t}, @code{nil}, or @code{otherwise}, -enclose the symbol in a list.) - -For example, this expression reads a keystroke, then does one of -four things depending on whether it is an @samp{a}, a @samp{b}, -a @key{RET} or @kbd{C-j}, or anything else. - -@example -(case (read-char) - (?a (do-a-thing)) - (?b (do-b-thing)) - ((?\r ?\n) (do-ret-thing)) - (t (do-other-thing))) -@end example -@end defspec - -@defspec ecase keyform clause@dots{} -This macro is just like @code{case}, except that if the key does -not match any of the clauses, an error is signaled rather than -simply returning @code{nil}. -@end defspec - -@defspec typecase keyform clause@dots{} -This macro is a version of @code{case} that checks for types -rather than values. Each @var{clause} is of the form -@samp{(@var{type} @var{body}...)}. @xref{Type Predicates}, -for a description of type specifiers. For example, - -@example -(typecase x - (integer (munch-integer x)) - (float (munch-float x)) - (string (munch-integer (string-to-int x))) - (t (munch-anything x))) -@end example - -The type specifier @code{t} matches any type of object; the word -@code{otherwise} is also allowed. To make one clause match any of -several types, use an @code{(or ...)} type specifier. -@end defspec - -@defspec etypecase keyform clause@dots{} -This macro is just like @code{typecase}, except that if the key does -not match any of the clauses, an error is signaled rather than -simply returning @code{nil}. -@end defspec - -@node Blocks and Exits, Iteration, Conditionals, Control Structure -@section Blocks and Exits - -@noindent -Common Lisp @dfn{blocks} provide a non-local exit mechanism very -similar to @code{catch} and @code{throw}, but lexically rather than -dynamically scoped. This package actually implements @code{block} -in terms of @code{catch}; however, the lexical scoping allows the -optimizing byte-compiler to omit the costly @code{catch} step if the -body of the block does not actually @code{return-from} the block. - -@defspec block name forms@dots{} -The @var{forms} are evaluated as if by a @code{progn}. However, -if any of the @var{forms} execute @code{(return-from @var{name})}, -they will jump out and return directly from the @code{block} form. -The @code{block} returns the result of the last @var{form} unless -a @code{return-from} occurs. - -The @code{block}/@code{return-from} mechanism is quite similar to -the @code{catch}/@code{throw} mechanism. The main differences are -that block @var{name}s are unevaluated symbols, rather than forms -(such as quoted symbols) which evaluate to a tag at run-time; and -also that blocks are lexically scoped whereas @code{catch}/@code{throw} -are dynamically scoped. This means that functions called from the -body of a @code{catch} can also @code{throw} to the @code{catch}, -but the @code{return-from} referring to a block name must appear -physically within the @var{forms} that make up the body of the block. -They may not appear within other called functions, although they may -appear within macro expansions or @code{lambda}s in the body. Block -names and @code{catch} names form independent name-spaces. - -In true Common Lisp, @code{defun} and @code{defmacro} surround -the function or expander bodies with implicit blocks with the -same name as the function or macro. This does not occur in Emacs -Lisp, but this package provides @code{defun*} and @code{defmacro*} -forms which do create the implicit block. - -The Common Lisp looping constructs defined by this package, -such as @code{loop} and @code{dolist}, also create implicit blocks -just as in Common Lisp. - -Because they are implemented in terms of Emacs Lisp @code{catch} -and @code{throw}, blocks have the same overhead as actual -@code{catch} constructs (roughly two function calls). However, -the optimizing byte compiler will optimize away the @code{catch} -if the block does -not in fact contain any @code{return} or @code{return-from} calls -that jump to it. This means that @code{do} loops and @code{defun*} -functions which don't use @code{return} don't pay the overhead to -support it. -@end defspec - -@defspec return-from name [result] -This macro returns from the block named @var{name}, which must be -an (unevaluated) symbol. If a @var{result} form is specified, it -is evaluated to produce the result returned from the @code{block}. -Otherwise, @code{nil} is returned. -@end defspec - -@defspec return [result] -This macro is exactly like @code{(return-from nil @var{result})}. -Common Lisp loops like @code{do} and @code{dolist} implicitly enclose -themselves in @code{nil} blocks. -@end defspec - -@node Iteration, Loop Facility, Blocks and Exits, Control Structure -@section Iteration - -@noindent -The macros described here provide more sophisticated, high-level -looping constructs to complement Emacs Lisp's basic @code{while} -loop. - -@defspec loop forms@dots{} -The @dfn{CL} package supports both the simple, old-style meaning of -@code{loop} and the extremely powerful and flexible feature known as -the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced -facility is discussed in the following section; @pxref{Loop Facility}. -The simple form of @code{loop} is described here. - -If @code{loop} is followed by zero or more Lisp expressions, -then @code{(loop @var{exprs}@dots{})} simply creates an infinite -loop executing the expressions over and over. The loop is -enclosed in an implicit @code{nil} block. Thus, - -@example -(loop (foo) (if (no-more) (return 72)) (bar)) -@end example - -@noindent -is exactly equivalent to - -@example -(block nil (while t (foo) (if (no-more) (return 72)) (bar))) -@end example - -If any of the expressions are plain symbols, the loop is instead -interpreted as a Loop Macro specification as described later. -(This is not a restriction in practice, since a plain symbol -in the above notation would simply access and throw away the -value of a variable.) -@end defspec - -@defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{} -This macro creates a general iterative loop. Each @var{spec} is -of the form - -@example -(@var{var} [@var{init} [@var{step}]]) -@end example - -The loop works as follows: First, each @var{var} is bound to the -associated @var{init} value as if by a @code{let} form. Then, in -each iteration of the loop, the @var{end-test} is evaluated; if -true, the loop is finished. Otherwise, the body @var{forms} are -evaluated, then each @var{var} is set to the associated @var{step} -expression (as if by a @code{psetq} form) and the next iteration -begins. Once the @var{end-test} becomes true, the @var{result} -forms are evaluated (with the @var{var}s still bound to their -values) to produce the result returned by @code{do}. - -The entire @code{do} loop is enclosed in an implicit @code{nil} -block, so that you can use @code{(return)} to break out of the -loop at any time. - -If there are no @var{result} forms, the loop returns @code{nil}. -If a given @var{var} has no @var{step} form, it is bound to its -@var{init} value but not otherwise modified during the @code{do} -loop (unless the code explicitly modifies it); this case is just -a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})} -around the loop. If @var{init} is also omitted it defaults to -@code{nil}, and in this case a plain @samp{@var{var}} can be used -in place of @samp{(@var{var})}, again following the analogy with -@code{let}. - -This example (from Steele) illustrates a loop which applies the -function @code{f} to successive pairs of values from the lists -@code{foo} and @code{bar}; it is equivalent to the call -@code{(mapcar* 'f foo bar)}. Note that this loop has no body -@var{forms} at all, performing all its work as side effects of -the rest of the loop. - -@example -(do ((x foo (cdr x)) - (y bar (cdr y)) - (z nil (cons (f (car x) (car y)) z))) - ((or (null x) (null y)) - (nreverse z))) -@end example -@end defspec - -@defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{} -This is to @code{do} what @code{let*} is to @code{let}. In -particular, the initial values are bound as if by @code{let*} -rather than @code{let}, and the steps are assigned as if by -@code{setq} rather than @code{psetq}. - -Here is another way to write the above loop: - -@example -(do* ((xp foo (cdr xp)) - (yp bar (cdr yp)) - (x (car xp) (car xp)) - (y (car yp) (car yp)) - z) - ((or (null xp) (null yp)) - (nreverse z)) - (push (f x y) z)) -@end example -@end defspec - -@defspec dolist (var list [result]) forms@dots{} -This is a more specialized loop which iterates across the elements -of a list. @var{list} should evaluate to a list; the body @var{forms} -are executed with @var{var} bound to each element of the list in -turn. Finally, the @var{result} form (or @code{nil}) is evaluated -with @var{var} bound to @code{nil} to produce the result returned by -the loop. Unlike with Emacs'ss built in @code{dolist}, the loop is -surrounded by an implicit @code{nil} block. -@end defspec - -@defspec dotimes (var count [result]) forms@dots{} -This is a more specialized loop which iterates a specified number -of times. The body is executed with @var{var} bound to the integers -from zero (inclusive) to @var{count} (exclusive), in turn. Then -the @code{result} form is evaluated with @var{var} bound to the total -number of iterations that were done (i.e., @code{(max 0 @var{count})}) -to get the return value for the loop form. Unlike with Emacs'ss built in -@code{dolist}, the loop is surrounded by an implicit @code{nil} block. -@end defspec - -@defspec do-symbols (var [obarray [result]]) forms@dots{} -This loop iterates over all interned symbols. If @var{obarray} -is specified and is not @code{nil}, it loops over all symbols in -that obarray. For each symbol, the body @var{forms} are evaluated -with @var{var} bound to that symbol. The symbols are visited in -an unspecified order. Afterward the @var{result} form, if any, -is evaluated (with @var{var} bound to @code{nil}) to get the return -value. The loop is surrounded by an implicit @code{nil} block. -@end defspec - -@defspec do-all-symbols (var [result]) forms@dots{} -This is identical to @code{do-symbols} except that the @var{obarray} -argument is omitted; it always iterates over the default obarray. -@end defspec - -@xref{Mapping over Sequences}, for some more functions for -iterating over vectors or lists. - -@node Loop Facility, Multiple Values, Iteration, Control Structure -@section Loop Facility - -@noindent -A common complaint with Lisp's traditional looping constructs is -that they are either too simple and limited, such as Common Lisp's -@code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and -obscure, like Common Lisp's @code{do} loop. - -To remedy this, recent versions of Common Lisp have added a new -construct called the ``Loop Facility'' or ``@code{loop} macro,'' -with an easy-to-use but very powerful and expressive syntax. - -@menu -* Loop Basics:: @code{loop} macro, basic clause structure -* Loop Examples:: Working examples of @code{loop} macro -* For Clauses:: Clauses introduced by @code{for} or @code{as} -* Iteration Clauses:: @code{repeat}, @code{while}, @code{thereis}, etc. -* Accumulation Clauses:: @code{collect}, @code{sum}, @code{maximize}, etc. -* Other Clauses:: @code{with}, @code{if}, @code{initially}, @code{finally} -@end menu - -@node Loop Basics, Loop Examples, Loop Facility, Loop Facility -@subsection Loop Basics - -@noindent -The @code{loop} macro essentially creates a mini-language within -Lisp that is specially tailored for describing loops. While this -language is a little strange-looking by the standards of regular Lisp, -it turns out to be very easy to learn and well-suited to its purpose. - -Since @code{loop} is a macro, all parsing of the loop language -takes place at byte-compile time; compiled @code{loop}s are just -as efficient as the equivalent @code{while} loops written longhand. - -@defspec loop clauses@dots{} -A loop construct consists of a series of @var{clause}s, each -introduced by a symbol like @code{for} or @code{do}. Clauses -are simply strung together in the argument list of @code{loop}, -with minimal extra parentheses. The various types of clauses -specify initializations, such as the binding of temporary -variables, actions to be taken in the loop, stepping actions, -and final cleanup. - -Common Lisp specifies a certain general order of clauses in a -loop: - -@example -(loop @var{name-clause} - @var{var-clauses}@dots{} - @var{action-clauses}@dots{}) -@end example - -The @var{name-clause} optionally gives a name to the implicit -block that surrounds the loop. By default, the implicit block -is named @code{nil}. The @var{var-clauses} specify what -variables should be bound during the loop, and how they should -be modified or iterated throughout the course of the loop. The -@var{action-clauses} are things to be done during the loop, such -as computing, collecting, and returning values. - -The Emacs version of the @code{loop} macro is less restrictive about -the order of clauses, but things will behave most predictably if -you put the variable-binding clauses @code{with}, @code{for}, and -@code{repeat} before the action clauses. As in Common Lisp, -@code{initially} and @code{finally} clauses can go anywhere. - -Loops generally return @code{nil} by default, but you can cause -them to return a value by using an accumulation clause like -@code{collect}, an end-test clause like @code{always}, or an -explicit @code{return} clause to jump out of the implicit block. -(Because the loop body is enclosed in an implicit block, you can -also use regular Lisp @code{return} or @code{return-from} to -break out of the loop.) -@end defspec - -The following sections give some examples of the Loop Macro in -action, and describe the particular loop clauses in great detail. -Consult the second edition of Steele's @dfn{Common Lisp, the Language}, -for additional discussion and examples of the @code{loop} macro. - -@node Loop Examples, For Clauses, Loop Basics, Loop Facility -@subsection Loop Examples - -@noindent -Before listing the full set of clauses that are allowed, let's -look at a few example loops just to get a feel for the @code{loop} -language. - -@example -(loop for buf in (buffer-list) - collect (buffer-file-name buf)) -@end example - -@noindent -This loop iterates over all Emacs buffers, using the list -returned by @code{buffer-list}. For each buffer @code{buf}, -it calls @code{buffer-file-name} and collects the results into -a list, which is then returned from the @code{loop} construct. -The result is a list of the file names of all the buffers in -Emacs's memory. The words @code{for}, @code{in}, and @code{collect} -are reserved words in the @code{loop} language. - -@example -(loop repeat 20 do (insert "Yowsa\n")) -@end example - -@noindent -This loop inserts the phrase ``Yowsa'' twenty times in the -current buffer. - -@example -(loop until (eobp) do (munch-line) (forward-line 1)) -@end example - -@noindent -This loop calls @code{munch-line} on every line until the end -of the buffer. If point is already at the end of the buffer, -the loop exits immediately. - -@example -(loop do (munch-line) until (eobp) do (forward-line 1)) -@end example - -@noindent -This loop is similar to the above one, except that @code{munch-line} -is always called at least once. - -@example -(loop for x from 1 to 100 - for y = (* x x) - until (>= y 729) - finally return (list x (= y 729))) -@end example - -@noindent -This more complicated loop searches for a number @code{x} whose -square is 729. For safety's sake it only examines @code{x} -values up to 100; dropping the phrase @samp{to 100} would -cause the loop to count upwards with no limit. The second -@code{for} clause defines @code{y} to be the square of @code{x} -within the loop; the expression after the @code{=} sign is -reevaluated each time through the loop. The @code{until} -clause gives a condition for terminating the loop, and the -@code{finally} clause says what to do when the loop finishes. -(This particular example was written less concisely than it -could have been, just for the sake of illustration.) - -Note that even though this loop contains three clauses (two -@code{for}s and an @code{until}) that would have been enough to -define loops all by themselves, it still creates a single loop -rather than some sort of triple-nested loop. You must explicitly -nest your @code{loop} constructs if you want nested loops. - -@node For Clauses, Iteration Clauses, Loop Examples, Loop Facility -@subsection For Clauses - -@noindent -Most loops are governed by one or more @code{for} clauses. -A @code{for} clause simultaneously describes variables to be -bound, how those variables are to be stepped during the loop, -and usually an end condition based on those variables. - -The word @code{as} is a synonym for the word @code{for}. This -word is followed by a variable name, then a word like @code{from} -or @code{across} that describes the kind of iteration desired. -In Common Lisp, the phrase @code{being the} sometimes precedes -the type of iteration; in this package both @code{being} and -@code{the} are optional. The word @code{each} is a synonym -for @code{the}, and the word that follows it may be singular -or plural: @samp{for x being the elements of y} or -@samp{for x being each element of y}. Which form you use -is purely a matter of style. - -The variable is bound around the loop as if by @code{let}: - -@example -(setq i 'happy) -(loop for i from 1 to 10 do (do-something-with i)) -i - @result{} happy -@end example - -@table @code -@item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3} -This type of @code{for} clause creates a counting loop. Each of -the three sub-terms is optional, though there must be at least one -term so that the clause is marked as a counting clause. - -The three expressions are the starting value, the ending value, and -the step value, respectively, of the variable. The loop counts -upwards by default (@var{expr3} must be positive), from @var{expr1} -to @var{expr2} inclusively. If you omit the @code{from} term, the -loop counts from zero; if you omit the @code{to} term, the loop -counts forever without stopping (unless stopped by some other -loop clause, of course); if you omit the @code{by} term, the loop -counts in steps of one. - -You can replace the word @code{from} with @code{upfrom} or -@code{downfrom} to indicate the direction of the loop. Likewise, -you can replace @code{to} with @code{upto} or @code{downto}. -For example, @samp{for x from 5 downto 1} executes five times -with @code{x} taking on the integers from 5 down to 1 in turn. -Also, you can replace @code{to} with @code{below} or @code{above}, -which are like @code{upto} and @code{downto} respectively except -that they are exclusive rather than inclusive limits: - -@example -(loop for x to 10 collect x) - @result{} (0 1 2 3 4 5 6 7 8 9 10) -(loop for x below 10 collect x) - @result{} (0 1 2 3 4 5 6 7 8 9) -@end example - -The @code{by} value is always positive, even for downward-counting -loops. Some sort of @code{from} value is required for downward -loops; @samp{for x downto 5} is not a valid loop clause all by -itself. - -@item for @var{var} in @var{list} by @var{function} -This clause iterates @var{var} over all the elements of @var{list}, -in turn. If you specify the @code{by} term, then @var{function} -is used to traverse the list instead of @code{cdr}; it must be a -function taking one argument. For example: - -@example -(loop for x in '(1 2 3 4 5 6) collect (* x x)) - @result{} (1 4 9 16 25 36) -(loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x)) - @result{} (1 9 25) -@end example - -@item for @var{var} on @var{list} by @var{function} -This clause iterates @var{var} over all the cons cells of @var{list}. - -@example -(loop for x on '(1 2 3 4) collect x) - @result{} ((1 2 3 4) (2 3 4) (3 4) (4)) -@end example - -With @code{by}, there is no real reason that the @code{on} expression -must be a list. For example: - -@example -(loop for x on first-animal by 'next-animal collect x) -@end example - -@noindent -where @code{(next-animal x)} takes an ``animal'' @var{x} and returns -the next in the (assumed) sequence of animals, or @code{nil} if -@var{x} was the last animal in the sequence. - -@item for @var{var} in-ref @var{list} by @var{function} -This is like a regular @code{in} clause, but @var{var} becomes -a @code{setf}-able ``reference'' onto the elements of the list -rather than just a temporary variable. For example, - -@example -(loop for x in-ref my-list do (incf x)) -@end example - -@noindent -increments every element of @code{my-list} in place. This clause -is an extension to standard Common Lisp. - -@item for @var{var} across @var{array} -This clause iterates @var{var} over all the elements of @var{array}, -which may be a vector or a string. - -@example -(loop for x across "aeiou" - do (use-vowel (char-to-string x))) -@end example - -@item for @var{var} across-ref @var{array} -This clause iterates over an array, with @var{var} a @code{setf}-able -reference onto the elements; see @code{in-ref} above. - -@item for @var{var} being the elements of @var{sequence} -This clause iterates over the elements of @var{sequence}, which may -be a list, vector, or string. Since the type must be determined -at run-time, this is somewhat less efficient than @code{in} or -@code{across}. The clause may be followed by the additional term -@samp{using (index @var{var2})} to cause @var{var2} to be bound to -the successive indices (starting at 0) of the elements. - -This clause type is taken from older versions of the @code{loop} macro, -and is not present in modern Common Lisp. The @samp{using (sequence ...)} -term of the older macros is not supported. - -@item for @var{var} being the elements of-ref @var{sequence} -This clause iterates over a sequence, with @var{var} a @code{setf}-able -reference onto the elements; see @code{in-ref} above. - -@item for @var{var} being the symbols [of @var{obarray}] -This clause iterates over symbols, either over all interned symbols -or over all symbols in @var{obarray}. The loop is executed with -@var{var} bound to each symbol in turn. The symbols are visited in -an unspecified order. - -As an example, - -@example -(loop for sym being the symbols - when (fboundp sym) - when (string-match "^map" (symbol-name sym)) - collect sym) -@end example - -@noindent -returns a list of all the functions whose names begin with @samp{map}. - -The Common Lisp words @code{external-symbols} and @code{present-symbols} -are also recognized but are equivalent to @code{symbols} in Emacs Lisp. - -Due to a minor implementation restriction, it will not work to have -more than one @code{for} clause iterating over symbols, hash tables, -keymaps, overlays, or intervals in a given @code{loop}. Fortunately, -it would rarely if ever be useful to do so. It @emph{is} valid to mix -one of these types of clauses with other clauses like @code{for ... to} -or @code{while}. - -@item for @var{var} being the hash-keys of @var{hash-table} -@itemx for @var{var} being the hash-values of @var{hash-table} -This clause iterates over the entries in @var{hash-table} with -@var{var} bound to each key, or value. A @samp{using} clause can bind -a second variable to the opposite part. - -@example -(loop for k being the hash-keys of h - using (hash-values v) - do - (message "key %S -> value %S" k v)) -@end example - -@item for @var{var} being the key-codes of @var{keymap} -@itemx for @var{var} being the key-bindings of @var{keymap} -This clause iterates over the entries in @var{keymap}. -The iteration does not enter nested keymaps but does enter inherited -(parent) keymaps. -A @code{using} clause can access both the codes and the bindings -together. - -@example -(loop for c being the key-codes of (current-local-map) - using (key-bindings b) - do - (message "key %S -> binding %S" c b)) -@end example - - -@item for @var{var} being the key-seqs of @var{keymap} -This clause iterates over all key sequences defined by @var{keymap} -and its nested keymaps, where @var{var} takes on values which are -vectors. The strings or vectors -are reused for each iteration, so you must copy them if you wish to keep -them permanently. You can add a @samp{using (key-bindings ...)} -clause to get the command bindings as well. - -@item for @var{var} being the overlays [of @var{buffer}] @dots{} -This clause iterates over the ``overlays'' of a buffer -(the clause @code{extents} is synonymous -with @code{overlays}). If the @code{of} term is omitted, the current -buffer is used. -This clause also accepts optional @samp{from @var{pos}} and -@samp{to @var{pos}} terms, limiting the clause to overlays which -overlap the specified region. - -@item for @var{var} being the intervals [of @var{buffer}] @dots{} -This clause iterates over all intervals of a buffer with constant -text properties. The variable @var{var} will be bound to conses -of start and end positions, where one start position is always equal -to the previous end position. The clause allows @code{of}, -@code{from}, @code{to}, and @code{property} terms, where the latter -term restricts the search to just the specified property. The -@code{of} term may specify either a buffer or a string. - -@item for @var{var} being the frames -This clause iterates over all Emacs frames. The clause @code{screens} is -a synonym for @code{frames}. The frames are visited in -@code{next-frame} order starting from @code{selected-frame}. - -@item for @var{var} being the windows [of @var{frame}] -This clause iterates over the windows (in the Emacs sense) of -the current frame, or of the specified @var{frame}. It visits windows -in @code{next-window} order starting from @code{selected-window} -(or @code{frame-selected-window} if you specify @var{frame}). -This clause treats the minibuffer window in the same way as -@code{next-window} does. For greater flexibility, consider using -@code{walk-windows} instead. - -@item for @var{var} being the buffers -This clause iterates over all buffers in Emacs. It is equivalent -to @samp{for @var{var} in (buffer-list)}. - -@item for @var{var} = @var{expr1} then @var{expr2} -This clause does a general iteration. The first time through -the loop, @var{var} will be bound to @var{expr1}. On the second -and successive iterations it will be set by evaluating @var{expr2} -(which may refer to the old value of @var{var}). For example, -these two loops are effectively the same: - -@example -(loop for x on my-list by 'cddr do ...) -(loop for x = my-list then (cddr x) while x do ...) -@end example - -Note that this type of @code{for} clause does not imply any sort -of terminating condition; the above example combines it with a -@code{while} clause to tell when to end the loop. - -If you omit the @code{then} term, @var{expr1} is used both for -the initial setting and for successive settings: - -@example -(loop for x = (random) when (> x 0) return x) -@end example - -@noindent -This loop keeps taking random numbers from the @code{(random)} -function until it gets a positive one, which it then returns. -@end table - -If you include several @code{for} clauses in a row, they are -treated sequentially (as if by @code{let*} and @code{setq}). -You can instead use the word @code{and} to link the clauses, -in which case they are processed in parallel (as if by @code{let} -and @code{psetq}). - -@example -(loop for x below 5 for y = nil then x collect (list x y)) - @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4)) -(loop for x below 5 and y = nil then x collect (list x y)) - @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3)) -@end example - -@noindent -In the first loop, @code{y} is set based on the value of @code{x} -that was just set by the previous clause; in the second loop, -@code{x} and @code{y} are set simultaneously so @code{y} is set -based on the value of @code{x} left over from the previous time -through the loop. - -Another feature of the @code{loop} macro is @dfn{destructuring}, -similar in concept to the destructuring provided by @code{defmacro}. -The @var{var} part of any @code{for} clause can be given as a list -of variables instead of a single variable. The values produced -during loop execution must be lists; the values in the lists are -stored in the corresponding variables. - -@example -(loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y)) - @result{} (5 9 13) -@end example - -In loop destructuring, if there are more values than variables -the trailing values are ignored, and if there are more variables -than values the trailing variables get the value @code{nil}. -If @code{nil} is used as a variable name, the corresponding -values are ignored. Destructuring may be nested, and dotted -lists of variables like @code{(x . y)} are allowed, so for example -to process an alist - -@example -(loop for (key . value) in '((a . 1) (b . 2)) - collect value) - @result{} (1 2) -@end example - -@node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility -@subsection Iteration Clauses - -@noindent -Aside from @code{for} clauses, there are several other loop clauses -that control the way the loop operates. They might be used by -themselves, or in conjunction with one or more @code{for} clauses. - -@table @code -@item repeat @var{integer} -This clause simply counts up to the specified number using an -internal temporary variable. The loops - -@example -(loop repeat (1+ n) do ...) -(loop for temp to n do ...) -@end example - -@noindent -are identical except that the second one forces you to choose -a name for a variable you aren't actually going to use. - -@item while @var{condition} -This clause stops the loop when the specified condition (any Lisp -expression) becomes @code{nil}. For example, the following two -loops are equivalent, except for the implicit @code{nil} block -that surrounds the second one: - -@example -(while @var{cond} @var{forms}@dots{}) -(loop while @var{cond} do @var{forms}@dots{}) -@end example - -@item until @var{condition} -This clause stops the loop when the specified condition is true, -i.e., non-@code{nil}. - -@item always @var{condition} -This clause stops the loop when the specified condition is @code{nil}. -Unlike @code{while}, it stops the loop using @code{return nil} so that -the @code{finally} clauses are not executed. If all the conditions -were non-@code{nil}, the loop returns @code{t}: - -@example -(if (loop for size in size-list always (> size 10)) - (some-big-sizes) - (no-big-sizes)) -@end example - -@item never @var{condition} -This clause is like @code{always}, except that the loop returns -@code{t} if any conditions were false, or @code{nil} otherwise. - -@item thereis @var{condition} -This clause stops the loop when the specified form is non-@code{nil}; -in this case, it returns that non-@code{nil} value. If all the -values were @code{nil}, the loop returns @code{nil}. -@end table - -@node Accumulation Clauses, Other Clauses, Iteration Clauses, Loop Facility -@subsection Accumulation Clauses - -@noindent -These clauses cause the loop to accumulate information about the -specified Lisp @var{form}. The accumulated result is returned -from the loop unless overridden, say, by a @code{return} clause. - -@table @code -@item collect @var{form} -This clause collects the values of @var{form} into a list. Several -examples of @code{collect} appear elsewhere in this manual. - -The word @code{collecting} is a synonym for @code{collect}, and -likewise for the other accumulation clauses. - -@item append @var{form} -This clause collects lists of values into a result list using -@code{append}. - -@item nconc @var{form} -This clause collects lists of values into a result list by -destructively modifying the lists rather than copying them. - -@item concat @var{form} -This clause concatenates the values of the specified @var{form} -into a string. (It and the following clause are extensions to -standard Common Lisp.) - -@item vconcat @var{form} -This clause concatenates the values of the specified @var{form} -into a vector. - -@item count @var{form} -This clause counts the number of times the specified @var{form} -evaluates to a non-@code{nil} value. - -@item sum @var{form} -This clause accumulates the sum of the values of the specified -@var{form}, which must evaluate to a number. - -@item maximize @var{form} -This clause accumulates the maximum value of the specified @var{form}, -which must evaluate to a number. The return value is undefined if -@code{maximize} is executed zero times. - -@item minimize @var{form} -This clause accumulates the minimum value of the specified @var{form}. -@end table - -Accumulation clauses can be followed by @samp{into @var{var}} to -cause the data to be collected into variable @var{var} (which is -automatically @code{let}-bound during the loop) rather than an -unnamed temporary variable. Also, @code{into} accumulations do -not automatically imply a return value. The loop must use some -explicit mechanism, such as @code{finally return}, to return -the accumulated result. - -It is valid for several accumulation clauses of the same type to -accumulate into the same place. From Steele: - -@example -(loop for name in '(fred sue alice joe june) - for kids in '((bob ken) () () (kris sunshine) ()) - collect name - append kids) - @result{} (fred bob ken sue alice joe kris sunshine june) -@end example - -@node Other Clauses, , Accumulation Clauses, Loop Facility -@subsection Other Clauses - -@noindent -This section describes the remaining loop clauses. - -@table @code -@item with @var{var} = @var{value} -This clause binds a variable to a value around the loop, but -otherwise leaves the variable alone during the loop. The following -loops are basically equivalent: - -@example -(loop with x = 17 do ...) -(let ((x 17)) (loop do ...)) -(loop for x = 17 then x do ...) -@end example - -Naturally, the variable @var{var} might be used for some purpose -in the rest of the loop. For example: - -@example -(loop for x in my-list with res = nil do (push x res) - finally return res) -@end example - -This loop inserts the elements of @code{my-list} at the front of -a new list being accumulated in @code{res}, then returns the -list @code{res} at the end of the loop. The effect is similar -to that of a @code{collect} clause, but the list gets reversed -by virtue of the fact that elements are being pushed onto the -front of @code{res} rather than the end. - -If you omit the @code{=} term, the variable is initialized to -@code{nil}. (Thus the @samp{= nil} in the above example is -unnecessary.) - -Bindings made by @code{with} are sequential by default, as if -by @code{let*}. Just like @code{for} clauses, @code{with} clauses -can be linked with @code{and} to cause the bindings to be made by -@code{let} instead. - -@item if @var{condition} @var{clause} -This clause executes the following loop clause only if the specified -condition is true. The following @var{clause} should be an accumulation, -@code{do}, @code{return}, @code{if}, or @code{unless} clause. -Several clauses may be linked by separating them with @code{and}. -These clauses may be followed by @code{else} and a clause or clauses -to execute if the condition was false. The whole construct may -optionally be followed by the word @code{end} (which may be used to -disambiguate an @code{else} or @code{and} in a nested @code{if}). - -The actual non-@code{nil} value of the condition form is available -by the name @code{it} in the ``then'' part. For example: - -@example -(setq funny-numbers '(6 13 -1)) - @result{} (6 13 -1) -(loop for x below 10 - if (oddp x) - collect x into odds - and if (memq x funny-numbers) return (cdr it) end - else - collect x into evens - finally return (vector odds evens)) - @result{} [(1 3 5 7 9) (0 2 4 6 8)] -(setq funny-numbers '(6 7 13 -1)) - @result{} (6 7 13 -1) -(loop <@r{same thing again}>) - @result{} (13 -1) -@end example - -Note the use of @code{and} to put two clauses into the ``then'' -part, one of which is itself an @code{if} clause. Note also that -@code{end}, while normally optional, was necessary here to make -it clear that the @code{else} refers to the outermost @code{if} -clause. In the first case, the loop returns a vector of lists -of the odd and even values of @var{x}. In the second case, the -odd number 7 is one of the @code{funny-numbers} so the loop -returns early; the actual returned value is based on the result -of the @code{memq} call. - -@item when @var{condition} @var{clause} -This clause is just a synonym for @code{if}. - -@item unless @var{condition} @var{clause} -The @code{unless} clause is just like @code{if} except that the -sense of the condition is reversed. - -@item named @var{name} -This clause gives a name other than @code{nil} to the implicit -block surrounding the loop. The @var{name} is the symbol to be -used as the block name. - -@item initially [do] @var{forms}... -This keyword introduces one or more Lisp forms which will be -executed before the loop itself begins (but after any variables -requested by @code{for} or @code{with} have been bound to their -initial values). @code{initially} clauses can appear anywhere; -if there are several, they are executed in the order they appear -in the loop. The keyword @code{do} is optional. - -@item finally [do] @var{forms}... -This introduces Lisp forms which will be executed after the loop -finishes (say, on request of a @code{for} or @code{while}). -@code{initially} and @code{finally} clauses may appear anywhere -in the loop construct, but they are executed (in the specified -order) at the beginning or end, respectively, of the loop. - -@item finally return @var{form} -This says that @var{form} should be executed after the loop -is done to obtain a return value. (Without this, or some other -clause like @code{collect} or @code{return}, the loop will simply -return @code{nil}.) Variables bound by @code{for}, @code{with}, -or @code{into} will still contain their final values when @var{form} -is executed. - -@item do @var{forms}... -The word @code{do} may be followed by any number of Lisp expressions -which are executed as an implicit @code{progn} in the body of the -loop. Many of the examples in this section illustrate the use of -@code{do}. - -@item return @var{form} -This clause causes the loop to return immediately. The following -Lisp form is evaluated to give the return value of the @code{loop} -form. The @code{finally} clauses, if any, are not executed. -Of course, @code{return} is generally used inside an @code{if} or -@code{unless}, as its use in a top-level loop clause would mean -the loop would never get to ``loop'' more than once. - -The clause @samp{return @var{form}} is equivalent to -@samp{do (return @var{form})} (or @code{return-from} if the loop -was named). The @code{return} clause is implemented a bit more -efficiently, though. -@end table - -While there is no high-level way to add user extensions to @code{loop} -(comparable to @code{defsetf} for @code{setf}, say), this package -does offer two properties called @code{cl-loop-handler} and -@code{cl-loop-for-handler} which are functions to be called when -a given symbol is encountered as a top-level loop clause or -@code{for} clause, respectively. Consult the source code in -file @file{cl-macs.el} for details. - -This package's @code{loop} macro is compatible with that of Common -Lisp, except that a few features are not implemented: @code{loop-finish} -and data-type specifiers. Naturally, the @code{for} clauses which -iterate over keymaps, overlays, intervals, frames, windows, and -buffers are Emacs-specific extensions. - -@node Multiple Values, , Loop Facility, Control Structure -@section Multiple Values - -@noindent -Common Lisp functions can return zero or more results. Emacs Lisp -functions, by contrast, always return exactly one result. This -package makes no attempt to emulate Common Lisp multiple return -values; Emacs versions of Common Lisp functions that return more -than one value either return just the first value (as in -@code{compiler-macroexpand}) or return a list of values (as in -@code{get-setf-method}). This package @emph{does} define placeholders -for the Common Lisp functions that work with multiple values, but -in Emacs Lisp these functions simply operate on lists instead. -The @code{values} form, for example, is a synonym for @code{list} -in Emacs. - -@defspec multiple-value-bind (var@dots{}) values-form forms@dots{} -This form evaluates @var{values-form}, which must return a list of -values. It then binds the @var{var}s to these respective values, -as if by @code{let}, and then executes the body @var{forms}. -If there are more @var{var}s than values, the extra @var{var}s -are bound to @code{nil}. If there are fewer @var{var}s than -values, the excess values are ignored. -@end defspec - -@defspec multiple-value-setq (var@dots{}) form -This form evaluates @var{form}, which must return a list of values. -It then sets the @var{var}s to these respective values, as if by -@code{setq}. Extra @var{var}s or values are treated the same as -in @code{multiple-value-bind}. -@end defspec - -The older Quiroz package attempted a more faithful (but still -imperfect) emulation of Common Lisp multiple values. The old -method ``usually'' simulated true multiple values quite well, -but under certain circumstances would leave spurious return -values in memory where a later, unrelated @code{multiple-value-bind} -form would see them. - -Since a perfect emulation is not feasible in Emacs Lisp, this -package opts to keep it as simple and predictable as possible. - -@node Macros, Declarations, Control Structure, Top -@chapter Macros - -@noindent -This package implements the various Common Lisp features of -@code{defmacro}, such as destructuring, @code{&environment}, -and @code{&body}. Top-level @code{&whole} is not implemented -for @code{defmacro} due to technical difficulties. -@xref{Argument Lists}. - -Destructuring is made available to the user by way of the -following macro: - -@defspec destructuring-bind arglist expr forms@dots{} -This macro expands to code which executes @var{forms}, with -the variables in @var{arglist} bound to the list of values -returned by @var{expr}. The @var{arglist} can include all -the features allowed for @code{defmacro} argument lists, -including destructuring. (The @code{&environment} keyword -is not allowed.) The macro expansion will signal an error -if @var{expr} returns a list of the wrong number of arguments -or with incorrect keyword arguments. -@end defspec - -This package also includes the Common Lisp @code{define-compiler-macro} -facility, which allows you to define compile-time expansions and -optimizations for your functions. - -@defspec define-compiler-macro name arglist forms@dots{} -This form is similar to @code{defmacro}, except that it only expands -calls to @var{name} at compile-time; calls processed by the Lisp -interpreter are not expanded, nor are they expanded by the -@code{macroexpand} function. - -The argument list may begin with a @code{&whole} keyword and a -variable. This variable is bound to the macro-call form itself, -i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}. -If the macro expander returns this form unchanged, then the -compiler treats it as a normal function call. This allows -compiler macros to work as optimizers for special cases of a -function, leaving complicated cases alone. - -For example, here is a simplified version of a definition that -appears as a standard part of this package: - -@example -(define-compiler-macro member* (&whole form a list &rest keys) - (if (and (null keys) - (eq (car-safe a) 'quote) - (not (floatp-safe (cadr a)))) - (list 'memq a list) - form)) -@end example - -@noindent -This definition causes @code{(member* @var{a} @var{list})} to change -to a call to the faster @code{memq} in the common case where @var{a} -is a non-floating-point constant; if @var{a} is anything else, or -if there are any keyword arguments in the call, then the original -@code{member*} call is left intact. (The actual compiler macro -for @code{member*} optimizes a number of other cases, including -common @code{:test} predicates.) -@end defspec - -@defun compiler-macroexpand form -This function is analogous to @code{macroexpand}, except that it -expands compiler macros rather than regular macros. It returns -@var{form} unchanged if it is not a call to a function for which -a compiler macro has been defined, or if that compiler macro -decided to punt by returning its @code{&whole} argument. Like -@code{macroexpand}, it expands repeatedly until it reaches a form -for which no further expansion is possible. -@end defun - -@xref{Macro Bindings}, for descriptions of the @code{macrolet} -and @code{symbol-macrolet} forms for making ``local'' macro -definitions. - -@node Declarations, Symbols, Macros, Top -@chapter Declarations - -@noindent -Common Lisp includes a complex and powerful ``declaration'' -mechanism that allows you to give the compiler special hints -about the types of data that will be stored in particular variables, -and about the ways those variables and functions will be used. This -package defines versions of all the Common Lisp declaration forms: -@code{declare}, @code{locally}, @code{proclaim}, @code{declaim}, -and @code{the}. - -Most of the Common Lisp declarations are not currently useful in -Emacs Lisp, as the byte-code system provides little opportunity -to benefit from type information, and @code{special} declarations -are redundant in a fully dynamically-scoped Lisp. A few -declarations are meaningful when the optimizing byte -compiler is being used, however. Under the earlier non-optimizing -compiler, these declarations will effectively be ignored. - -@defun proclaim decl-spec -This function records a ``global'' declaration specified by -@var{decl-spec}. Since @code{proclaim} is a function, @var{decl-spec} -is evaluated and thus should normally be quoted. -@end defun - -@defspec declaim decl-specs@dots{} -This macro is like @code{proclaim}, except that it takes any number -of @var{decl-spec} arguments, and the arguments are unevaluated and -unquoted. The @code{declaim} macro also puts an @code{(eval-when -(compile load eval) ...)} around the declarations so that they will -be registered at compile-time as well as at run-time. (This is vital, -since normally the declarations are meant to influence the way the -compiler treats the rest of the file that contains the @code{declaim} -form.) -@end defspec - -@defspec declare decl-specs@dots{} -This macro is used to make declarations within functions and other -code. Common Lisp allows declarations in various locations, generally -at the beginning of any of the many ``implicit @code{progn}s'' -throughout Lisp syntax, such as function bodies, @code{let} bodies, -etc. Currently the only declaration understood by @code{declare} -is @code{special}. -@end defspec - -@defspec locally declarations@dots{} forms@dots{} -In this package, @code{locally} is no different from @code{progn}. -@end defspec - -@defspec the type form -Type information provided by @code{the} is ignored in this package; -in other words, @code{(the @var{type} @var{form})} is equivalent -to @var{form}. Future versions of the optimizing byte-compiler may -make use of this information. - -For example, @code{mapcar} can map over both lists and arrays. It is -hard for the compiler to expand @code{mapcar} into an in-line loop -unless it knows whether the sequence will be a list or an array ahead -of time. With @code{(mapcar 'car (the vector foo))}, a future -compiler would have enough information to expand the loop in-line. -For now, Emacs Lisp will treat the above code as exactly equivalent -to @code{(mapcar 'car foo)}. -@end defspec - -Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or -@code{declare} should be a list beginning with a symbol that says -what kind of declaration it is. This package currently understands -@code{special}, @code{inline}, @code{notinline}, @code{optimize}, -and @code{warn} declarations. (The @code{warn} declaration is an -extension of standard Common Lisp.) Other Common Lisp declarations, -such as @code{type} and @code{ftype}, are silently ignored. - -@table @code -@item special -Since all variables in Emacs Lisp are ``special'' (in the Common -Lisp sense), @code{special} declarations are only advisory. They -simply tell the optimizing byte compiler that the specified -variables are intentionally being referred to without being -bound in the body of the function. The compiler normally emits -warnings for such references, since they could be typographical -errors for references to local variables. - -The declaration @code{(declare (special @var{var1} @var{var2}))} is -equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the -optimizing compiler, or to nothing at all in older compilers (which -do not warn for non-local references). - -In top-level contexts, it is generally better to write -@code{(defvar @var{var})} than @code{(declaim (special @var{var}))}, -since @code{defvar} makes your intentions clearer. But the older -byte compilers can not handle @code{defvar}s appearing inside of -functions, while @code{(declare (special @var{var}))} takes care -to work correctly with all compilers. - -@item inline -The @code{inline} @var{decl-spec} lists one or more functions -whose bodies should be expanded ``in-line'' into calling functions -whenever the compiler is able to arrange for it. For example, -the Common Lisp function @code{cadr} is declared @code{inline} -by this package so that the form @code{(cadr @var{x})} will -expand directly into @code{(car (cdr @var{x}))} when it is called -in user functions, for a savings of one (relatively expensive) -function call. - -The following declarations are all equivalent. Note that the -@code{defsubst} form is a convenient way to define a function -and declare it inline all at once. - -@example -(declaim (inline foo bar)) -(eval-when (compile load eval) (proclaim '(inline foo bar))) -(defsubst foo (...) ...) ; instead of defun -@end example - -@strong{Please note:} this declaration remains in effect after the -containing source file is done. It is correct to use it to -request that a function you have defined should be inlined, -but it is impolite to use it to request inlining of an external -function. - -In Common Lisp, it is possible to use @code{(declare (inline @dots{}))} -before a particular call to a function to cause just that call to -be inlined; the current byte compilers provide no way to implement -this, so @code{(declare (inline @dots{}))} is currently ignored by -this package. - -@item notinline -The @code{notinline} declaration lists functions which should -not be inlined after all; it cancels a previous @code{inline} -declaration. - -@item optimize -This declaration controls how much optimization is performed by -the compiler. Naturally, it is ignored by the earlier non-optimizing -compilers. - -The word @code{optimize} is followed by any number of lists like -@code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several -optimization ``qualities''; this package ignores all but @code{speed} -and @code{safety}. The value of a quality should be an integer from -0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.'' -The default level for both qualities is 1. - -In this package, with the optimizing compiler, the -@code{speed} quality is tied to the @code{byte-compile-optimize} -flag, which is set to @code{nil} for @code{(speed 0)} and to -@code{t} for higher settings; and the @code{safety} quality is -tied to the @code{byte-compile-delete-errors} flag, which is -set to @code{t} for @code{(safety 3)} and to @code{nil} for all -lower settings. (The latter flag controls whether the compiler -is allowed to optimize out code whose only side-effect could -be to signal an error, e.g., rewriting @code{(progn foo bar)} to -@code{bar} when it is not known whether @code{foo} will be bound -at run-time.) - -Note that even compiling with @code{(safety 0)}, the Emacs -byte-code system provides sufficient checking to prevent real -harm from being done. For example, barring serious bugs in -Emacs itself, Emacs will not crash with a segmentation fault -just because of an error in a fully-optimized Lisp program. - -The @code{optimize} declaration is normally used in a top-level -@code{proclaim} or @code{declaim} in a file; Common Lisp allows -it to be used with @code{declare} to set the level of optimization -locally for a given form, but this will not work correctly with the -current version of the optimizing compiler. (The @code{declare} -will set the new optimization level, but that level will not -automatically be unset after the enclosing form is done.) - -@item warn -This declaration controls what sorts of warnings are generated -by the byte compiler. Again, only the optimizing compiler -generates warnings. The word @code{warn} is followed by any -number of ``warning qualities,'' similar in form to optimization -qualities. The currently supported warning types are -@code{redefine}, @code{callargs}, @code{unresolved}, and -@code{free-vars}; in the current system, a value of 0 will -disable these warnings and any higher value will enable them. -See the documentation for the optimizing byte compiler for details. -@end table - -@node Symbols, Numbers, Declarations, Top -@chapter Symbols - -@noindent -This package defines several symbol-related features that were -missing from Emacs Lisp. - -@menu -* Property Lists:: @code{get*}, @code{remprop}, @code{getf}, @code{remf} -* Creating Symbols:: @code{gensym}, @code{gentemp} -@end menu - -@node Property Lists, Creating Symbols, Symbols, Symbols -@section Property Lists - -@noindent -These functions augment the standard Emacs Lisp functions @code{get} -and @code{put} for operating on properties attached to symbols. -There are also functions for working with property lists as -first-class data structures not attached to particular symbols. - -@defun get* symbol property &optional default -This function is like @code{get}, except that if the property is -not found, the @var{default} argument provides the return value. -(The Emacs Lisp @code{get} function always uses @code{nil} as -the default; this package's @code{get*} is equivalent to Common -Lisp's @code{get}.) - -The @code{get*} function is @code{setf}-able; when used in this -fashion, the @var{default} argument is allowed but ignored. -@end defun - -@defun remprop symbol property -This function removes the entry for @var{property} from the property -list of @var{symbol}. It returns a true value if the property was -indeed found and removed, or @code{nil} if there was no such property. -(This function was probably omitted from Emacs originally because, -since @code{get} did not allow a @var{default}, it was very difficult -to distinguish between a missing property and a property whose value -was @code{nil}; thus, setting a property to @code{nil} was close -enough to @code{remprop} for most purposes.) -@end defun - -@defun getf place property &optional default -This function scans the list @var{place} as if it were a property -list, i.e., a list of alternating property names and values. If -an even-numbered element of @var{place} is found which is @code{eq} -to @var{property}, the following odd-numbered element is returned. -Otherwise, @var{default} is returned (or @code{nil} if no default -is given). - -In particular, - -@example -(get sym prop) @equiv{} (getf (symbol-plist sym) prop) -@end example - -It is valid to use @code{getf} as a @code{setf} place, in which case -its @var{place} argument must itself be a valid @code{setf} place. -The @var{default} argument, if any, is ignored in this context. -The effect is to change (via @code{setcar}) the value cell in the -list that corresponds to @var{property}, or to cons a new property-value -pair onto the list if the property is not yet present. - -@example -(put sym prop val) @equiv{} (setf (getf (symbol-plist sym) prop) val) -@end example - -The @code{get} and @code{get*} functions are also @code{setf}-able. -The fact that @code{default} is ignored can sometimes be useful: - -@example -(incf (get* 'foo 'usage-count 0)) -@end example - -Here, symbol @code{foo}'s @code{usage-count} property is incremented -if it exists, or set to 1 (an incremented 0) otherwise. - -When not used as a @code{setf} form, @code{getf} is just a regular -function and its @var{place} argument can actually be any Lisp -expression. -@end defun - -@defspec remf place property -This macro removes the property-value pair for @var{property} from -the property list stored at @var{place}, which is any @code{setf}-able -place expression. It returns true if the property was found. Note -that if @var{property} happens to be first on the list, this will -effectively do a @code{(setf @var{place} (cddr @var{place}))}, -whereas if it occurs later, this simply uses @code{setcdr} to splice -out the property and value cells. -@end defspec - -@iftex -@secno=2 -@end iftex - -@node Creating Symbols, , Property Lists, Symbols -@section Creating Symbols - -@noindent -These functions create unique symbols, typically for use as -temporary variables. - -@defun gensym &optional x -This function creates a new, uninterned symbol (using @code{make-symbol}) -with a unique name. (The name of an uninterned symbol is relevant -only if the symbol is printed.) By default, the name is generated -from an increasing sequence of numbers, @samp{G1000}, @samp{G1001}, -@samp{G1002}, etc. If the optional argument @var{x} is a string, that -string is used as a prefix instead of @samp{G}. Uninterned symbols -are used in macro expansions for temporary variables, to ensure that -their names will not conflict with ``real'' variables in the user's -code. -@end defun - -@defvar *gensym-counter* -This variable holds the counter used to generate @code{gensym} names. -It is incremented after each use by @code{gensym}. In Common Lisp -this is initialized with 0, but this package initializes it with a -random (time-dependent) value to avoid trouble when two files that -each used @code{gensym} in their compilation are loaded together. -(Uninterned symbols become interned when the compiler writes them -out to a file and the Emacs loader loads them, so their names have to -be treated a bit more carefully than in Common Lisp where uninterned -symbols remain uninterned after loading.) -@end defvar - -@defun gentemp &optional x -This function is like @code{gensym}, except that it produces a new -@emph{interned} symbol. If the symbol that is generated already -exists, the function keeps incrementing the counter and trying -again until a new symbol is generated. -@end defun - -The Quiroz @file{cl.el} package also defined a @code{defkeyword} -form for creating self-quoting keyword symbols. This package -automatically creates all keywords that are called for by -@code{&key} argument specifiers, and discourages the use of -keywords as data unrelated to keyword arguments, so the -@code{defkeyword} form has been discontinued. - -@iftex -@chapno=11 -@end iftex - -@node Numbers, Sequences, Symbols, Top -@chapter Numbers - -@noindent -This section defines a few simple Common Lisp operations on numbers -which were left out of Emacs Lisp. - -@menu -* Predicates on Numbers:: @code{plusp}, @code{oddp}, @code{floatp-safe}, etc. -* Numerical Functions:: @code{abs}, @code{floor*}, etc. -* Random Numbers:: @code{random*}, @code{make-random-state} -* Implementation Parameters:: @code{most-positive-float} -@end menu - -@iftex -@secno=1 -@end iftex - -@node Predicates on Numbers, Numerical Functions, Numbers, Numbers -@section Predicates on Numbers - -@noindent -These functions return @code{t} if the specified condition is -true of the numerical argument, or @code{nil} otherwise. - -@defun plusp number -This predicate tests whether @var{number} is positive. It is an -error if the argument is not a number. -@end defun - -@defun minusp number -This predicate tests whether @var{number} is negative. It is an -error if the argument is not a number. -@end defun - -@defun oddp integer -This predicate tests whether @var{integer} is odd. It is an -error if the argument is not an integer. -@end defun - -@defun evenp integer -This predicate tests whether @var{integer} is even. It is an -error if the argument is not an integer. -@end defun - -@defun floatp-safe object -This predicate tests whether @var{object} is a floating-point -number. On systems that support floating-point, this is equivalent -to @code{floatp}. On other systems, this always returns @code{nil}. -@end defun - -@iftex -@secno=3 -@end iftex - -@node Numerical Functions, Random Numbers, Predicates on Numbers, Numbers -@section Numerical Functions - -@noindent -These functions perform various arithmetic operations on numbers. - -@defun gcd &rest integers -This function returns the Greatest Common Divisor of the arguments. -For one argument, it returns the absolute value of that argument. -For zero arguments, it returns zero. -@end defun - -@defun lcm &rest integers -This function returns the Least Common Multiple of the arguments. -For one argument, it returns the absolute value of that argument. -For zero arguments, it returns one. -@end defun - -@defun isqrt integer -This function computes the ``integer square root'' of its integer -argument, i.e., the greatest integer less than or equal to the true -square root of the argument. -@end defun - -@defun floor* number &optional divisor -This function implements the Common Lisp @code{floor} function. -It is called @code{floor*} to avoid name conflicts with the -simpler @code{floor} function built-in to Emacs. - -With one argument, @code{floor*} returns a list of two numbers: -The argument rounded down (toward minus infinity) to an integer, -and the ``remainder'' which would have to be added back to the -first return value to yield the argument again. If the argument -is an integer @var{x}, the result is always the list @code{(@var{x} 0)}. -If the argument is a floating-point number, the first -result is a Lisp integer and the second is a Lisp float between -0 (inclusive) and 1 (exclusive). - -With two arguments, @code{floor*} divides @var{number} by -@var{divisor}, and returns the floor of the quotient and the -corresponding remainder as a list of two numbers. If -@code{(floor* @var{x} @var{y})} returns @code{(@var{q} @var{r})}, -then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r} -between 0 (inclusive) and @var{r} (exclusive). Also, note -that @code{(floor* @var{x})} is exactly equivalent to -@code{(floor* @var{x} 1)}. - -This function is entirely compatible with Common Lisp's @code{floor} -function, except that it returns the two results in a list since -Emacs Lisp does not support multiple-valued functions. -@end defun - -@defun ceiling* number &optional divisor -This function implements the Common Lisp @code{ceiling} function, -which is analogous to @code{floor} except that it rounds the -argument or quotient of the arguments up toward plus infinity. -The remainder will be between 0 and minus @var{r}. -@end defun - -@defun truncate* number &optional divisor -This function implements the Common Lisp @code{truncate} function, -which is analogous to @code{floor} except that it rounds the -argument or quotient of the arguments toward zero. Thus it is -equivalent to @code{floor*} if the argument or quotient is -positive, or to @code{ceiling*} otherwise. The remainder has -the same sign as @var{number}. -@end defun - -@defun round* number &optional divisor -This function implements the Common Lisp @code{round} function, -which is analogous to @code{floor} except that it rounds the -argument or quotient of the arguments to the nearest integer. -In the case of a tie (the argument or quotient is exactly -halfway between two integers), it rounds to the even integer. -@end defun - -@defun mod* number divisor -This function returns the same value as the second return value -of @code{floor}. -@end defun - -@defun rem* number divisor -This function returns the same value as the second return value -of @code{truncate}. -@end defun - -These definitions are compatible with those in the Quiroz -@file{cl.el} package, except that this package appends @samp{*} -to certain function names to avoid conflicts with existing -Emacs functions, and that the mechanism for returning -multiple values is different. - -@iftex -@secno=8 -@end iftex - -@node Random Numbers, Implementation Parameters, Numerical Functions, Numbers -@section Random Numbers - -@noindent -This package also provides an implementation of the Common Lisp -random number generator. It uses its own additive-congruential -algorithm, which is much more likely to give statistically clean -random numbers than the simple generators supplied by many -operating systems. - -@defun random* number &optional state -This function returns a random nonnegative number less than -@var{number}, and of the same type (either integer or floating-point). -The @var{state} argument should be a @code{random-state} object -which holds the state of the random number generator. The -function modifies this state object as a side effect. If -@var{state} is omitted, it defaults to the variable -@code{*random-state*}, which contains a pre-initialized -@code{random-state} object. -@end defun - -@defvar *random-state* -This variable contains the system ``default'' @code{random-state} -object, used for calls to @code{random*} that do not specify an -alternative state object. Since any number of programs in the -Emacs process may be accessing @code{*random-state*} in interleaved -fashion, the sequence generated from this variable will be -irreproducible for all intents and purposes. -@end defvar - -@defun make-random-state &optional state -This function creates or copies a @code{random-state} object. -If @var{state} is omitted or @code{nil}, it returns a new copy of -@code{*random-state*}. This is a copy in the sense that future -sequences of calls to @code{(random* @var{n})} and -@code{(random* @var{n} @var{s})} (where @var{s} is the new -random-state object) will return identical sequences of random -numbers. - -If @var{state} is a @code{random-state} object, this function -returns a copy of that object. If @var{state} is @code{t}, this -function returns a new @code{random-state} object seeded from the -date and time. As an extension to Common Lisp, @var{state} may also -be an integer in which case the new object is seeded from that -integer; each different integer seed will result in a completely -different sequence of random numbers. - -It is valid to print a @code{random-state} object to a buffer or -file and later read it back with @code{read}. If a program wishes -to use a sequence of pseudo-random numbers which can be reproduced -later for debugging, it can call @code{(make-random-state t)} to -get a new sequence, then print this sequence to a file. When the -program is later rerun, it can read the original run's random-state -from the file. -@end defun - -@defun random-state-p object -This predicate returns @code{t} if @var{object} is a -@code{random-state} object, or @code{nil} otherwise. -@end defun - -@node Implementation Parameters, , Random Numbers, Numbers -@section Implementation Parameters - -@noindent -This package defines several useful constants having to with numbers. - -The following parameters have to do with floating-point numbers. -This package determines their values by exercising the computer's -floating-point arithmetic in various ways. Because this operation -might be slow, the code for initializing them is kept in a separate -function that must be called before the parameters can be used. - -@defun cl-float-limits -This function makes sure that the Common Lisp floating-point parameters -like @code{most-positive-float} have been initialized. Until it is -called, these parameters will be @code{nil}. If this version of Emacs -does not support floats, the parameters will remain @code{nil}. If the -parameters have already been initialized, the function returns -immediately. - -The algorithm makes assumptions that will be valid for most modern -machines, but will fail if the machine's arithmetic is extremely -unusual, e.g., decimal. -@end defun - -Since true Common Lisp supports up to four different floating-point -precisions, it has families of constants like -@code{most-positive-single-float}, @code{most-positive-double-float}, -@code{most-positive-long-float}, and so on. Emacs has only one -floating-point precision, so this package omits the precision word -from the constants' names. - -@defvar most-positive-float -This constant equals the largest value a Lisp float can hold. -For those systems whose arithmetic supports infinities, this is -the largest @emph{finite} value. For IEEE machines, the value -is approximately @code{1.79e+308}. -@end defvar - -@defvar most-negative-float -This constant equals the most-negative value a Lisp float can hold. -(It is assumed to be equal to @code{(- most-positive-float)}.) -@end defvar - -@defvar least-positive-float -This constant equals the smallest Lisp float value greater than zero. -For IEEE machines, it is about @code{4.94e-324} if denormals are -supported or @code{2.22e-308} if not. -@end defvar - -@defvar least-positive-normalized-float -This constant equals the smallest @emph{normalized} Lisp float greater -than zero, i.e., the smallest value for which IEEE denormalization -will not result in a loss of precision. For IEEE machines, this -value is about @code{2.22e-308}. For machines that do not support -the concept of denormalization and gradual underflow, this constant -will always equal @code{least-positive-float}. -@end defvar - -@defvar least-negative-float -This constant is the negative counterpart of @code{least-positive-float}. -@end defvar - -@defvar least-negative-normalized-float -This constant is the negative counterpart of -@code{least-positive-normalized-float}. -@end defvar - -@defvar float-epsilon -This constant is the smallest positive Lisp float that can be added -to 1.0 to produce a distinct value. Adding a smaller number to 1.0 -will yield 1.0 again due to roundoff. For IEEE machines, epsilon -is about @code{2.22e-16}. -@end defvar - -@defvar float-negative-epsilon -This is the smallest positive value that can be subtracted from -1.0 to produce a distinct value. For IEEE machines, it is about -@code{1.11e-16}. -@end defvar - -@iftex -@chapno=13 -@end iftex - -@node Sequences, Lists, Numbers, Top -@chapter Sequences - -@noindent -Common Lisp defines a number of functions that operate on -@dfn{sequences}, which are either lists, strings, or vectors. -Emacs Lisp includes a few of these, notably @code{elt} and -@code{length}; this package defines most of the rest. - -@menu -* Sequence Basics:: Arguments shared by all sequence functions -* Mapping over Sequences:: @code{mapcar*}, @code{mapcan}, @code{map}, @code{every}, etc. -* Sequence Functions:: @code{subseq}, @code{remove*}, @code{substitute}, etc. -* Searching Sequences:: @code{find}, @code{position}, @code{count}, @code{search}, etc. -* Sorting Sequences:: @code{sort*}, @code{stable-sort}, @code{merge} -@end menu - -@node Sequence Basics, Mapping over Sequences, Sequences, Sequences -@section Sequence Basics - -@noindent -Many of the sequence functions take keyword arguments; @pxref{Argument -Lists}. All keyword arguments are optional and, if specified, -may appear in any order. - -The @code{:key} argument should be passed either @code{nil}, or a -function of one argument. This key function is used as a filter -through which the elements of the sequence are seen; for example, -@code{(find x y :key 'car)} is similar to @code{(assoc* x y)}: -It searches for an element of the list whose @code{car} equals -@code{x}, rather than for an element which equals @code{x} itself. -If @code{:key} is omitted or @code{nil}, the filter is effectively -the identity function. - -The @code{:test} and @code{:test-not} arguments should be either -@code{nil}, or functions of two arguments. The test function is -used to compare two sequence elements, or to compare a search value -with sequence elements. (The two values are passed to the test -function in the same order as the original sequence function -arguments from which they are derived, or, if they both come from -the same sequence, in the same order as they appear in that sequence.) -The @code{:test} argument specifies a function which must return -true (non-@code{nil}) to indicate a match; instead, you may use -@code{:test-not} to give a function which returns @emph{false} to -indicate a match. The default test function is @code{eql}. - -Many functions which take @var{item} and @code{:test} or @code{:test-not} -arguments also come in @code{-if} and @code{-if-not} varieties, -where a @var{predicate} function is passed instead of @var{item}, -and sequence elements match if the predicate returns true on them -(or false in the case of @code{-if-not}). For example: - -@example -(remove* 0 seq :test '=) @equiv{} (remove-if 'zerop seq) -@end example - -@noindent -to remove all zeros from sequence @code{seq}. - -Some operations can work on a subsequence of the argument sequence; -these function take @code{:start} and @code{:end} arguments which -default to zero and the length of the sequence, respectively. -Only elements between @var{start} (inclusive) and @var{end} -(exclusive) are affected by the operation. The @var{end} argument -may be passed @code{nil} to signify the length of the sequence; -otherwise, both @var{start} and @var{end} must be integers, with -@code{0 <= @var{start} <= @var{end} <= (length @var{seq})}. -If the function takes two sequence arguments, the limits are -defined by keywords @code{:start1} and @code{:end1} for the first, -and @code{:start2} and @code{:end2} for the second. - -A few functions accept a @code{:from-end} argument, which, if -non-@code{nil}, causes the operation to go from right-to-left -through the sequence instead of left-to-right, and a @code{:count} -argument, which specifies an integer maximum number of elements -to be removed or otherwise processed. - -The sequence functions make no guarantees about the order in -which the @code{:test}, @code{:test-not}, and @code{:key} functions -are called on various elements. Therefore, it is a bad idea to depend -on side effects of these functions. For example, @code{:from-end} -may cause the sequence to be scanned actually in reverse, or it may -be scanned forwards but computing a result ``as if'' it were scanned -backwards. (Some functions, like @code{mapcar*} and @code{every}, -@emph{do} specify exactly the order in which the function is called -so side effects are perfectly acceptable in those cases.) - -Strings may contain ``text properties'' as well -as character data. Except as noted, it is undefined whether or -not text properties are preserved by sequence functions. For -example, @code{(remove* ?A @var{str})} may or may not preserve -the properties of the characters copied from @var{str} into the -result. - -@node Mapping over Sequences, Sequence Functions, Sequence Basics, Sequences -@section Mapping over Sequences - -@noindent -These functions ``map'' the function you specify over the elements -of lists or arrays. They are all variations on the theme of the -built-in function @code{mapcar}. - -@defun mapcar* function seq &rest more-seqs -This function calls @var{function} on successive parallel sets of -elements from its argument sequences. Given a single @var{seq} -argument it is equivalent to @code{mapcar}; given @var{n} sequences, -it calls the function with the first elements of each of the sequences -as the @var{n} arguments to yield the first element of the result -list, then with the second elements, and so on. The mapping stops as -soon as the shortest sequence runs out. The argument sequences may -be any mixture of lists, strings, and vectors; the return sequence -is always a list. - -Common Lisp's @code{mapcar} accepts multiple arguments but works -only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence -argument. This package's @code{mapcar*} works as a compatible -superset of both. -@end defun - -@defun map result-type function seq &rest more-seqs -This function maps @var{function} over the argument sequences, -just like @code{mapcar*}, but it returns a sequence of type -@var{result-type} rather than a list. @var{result-type} must -be one of the following symbols: @code{vector}, @code{string}, -@code{list} (in which case the effect is the same as for -@code{mapcar*}), or @code{nil} (in which case the results are -thrown away and @code{map} returns @code{nil}). -@end defun - -@defun maplist function list &rest more-lists -This function calls @var{function} on each of its argument lists, -then on the @code{cdr}s of those lists, and so on, until the -shortest list runs out. The results are returned in the form -of a list. Thus, @code{maplist} is like @code{mapcar*} except -that it passes in the list pointers themselves rather than the -@code{car}s of the advancing pointers. -@end defun - -@defun cl-mapc function seq &rest more-seqs -This function is like @code{mapcar*}, except that the values returned -by @var{function} are ignored and thrown away rather than being -collected into a list. The return value of @code{cl-mapc} is @var{seq}, -the first sequence. This function is more general than the Emacs -primitive @code{mapc}. -@end defun - -@defun mapl function list &rest more-lists -This function is like @code{maplist}, except that it throws away -the values returned by @var{function}. -@end defun - -@defun mapcan function seq &rest more-seqs -This function is like @code{mapcar*}, except that it concatenates -the return values (which must be lists) using @code{nconc}, -rather than simply collecting them into a list. -@end defun - -@defun mapcon function list &rest more-lists -This function is like @code{maplist}, except that it concatenates -the return values using @code{nconc}. -@end defun - -@defun some predicate seq &rest more-seqs -This function calls @var{predicate} on each element of @var{seq} -in turn; if @var{predicate} returns a non-@code{nil} value, -@code{some} returns that value, otherwise it returns @code{nil}. -Given several sequence arguments, it steps through the sequences -in parallel until the shortest one runs out, just as in -@code{mapcar*}. You can rely on the left-to-right order in which -the elements are visited, and on the fact that mapping stops -immediately as soon as @var{predicate} returns non-@code{nil}. -@end defun - -@defun every predicate seq &rest more-seqs -This function calls @var{predicate} on each element of the sequence(s) -in turn; it returns @code{nil} as soon as @var{predicate} returns -@code{nil} for any element, or @code{t} if the predicate was true -for all elements. -@end defun - -@defun notany predicate seq &rest more-seqs -This function calls @var{predicate} on each element of the sequence(s) -in turn; it returns @code{nil} as soon as @var{predicate} returns -a non-@code{nil} value for any element, or @code{t} if the predicate -was @code{nil} for all elements. -@end defun - -@defun notevery predicate seq &rest more-seqs -This function calls @var{predicate} on each element of the sequence(s) -in turn; it returns a non-@code{nil} value as soon as @var{predicate} -returns @code{nil} for any element, or @code{t} if the predicate was -true for all elements. -@end defun - -@defun reduce function seq @t{&key :from-end :start :end :initial-value :key} -This function combines the elements of @var{seq} using an associative -binary operation. Suppose @var{function} is @code{*} and @var{seq} is -the list @code{(2 3 4 5)}. The first two elements of the list are -combined with @code{(* 2 3) = 6}; this is combined with the next -element, @code{(* 6 4) = 24}, and that is combined with the final -element: @code{(* 24 5) = 120}. Note that the @code{*} function happens -to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as -an explicit call to @code{reduce}. - -If @code{:from-end} is true, the reduction is right-associative instead -of left-associative: - -@example -(reduce '- '(1 2 3 4)) - @equiv{} (- (- (- 1 2) 3) 4) @result{} -8 -(reduce '- '(1 2 3 4) :from-end t) - @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2 -@end example - -If @code{:key} is specified, it is a function of one argument which -is called on each of the sequence elements in turn. - -If @code{:initial-value} is specified, it is effectively added to the -front (or rear in the case of @code{:from-end}) of the sequence. -The @code{:key} function is @emph{not} applied to the initial value. - -If the sequence, including the initial value, has exactly one element -then that element is returned without ever calling @var{function}. -If the sequence is empty (and there is no initial value), then -@var{function} is called with no arguments to obtain the return value. -@end defun - -All of these mapping operations can be expressed conveniently in -terms of the @code{loop} macro. In compiled code, @code{loop} will -be faster since it generates the loop as in-line code with no -function calls. - -@node Sequence Functions, Searching Sequences, Mapping over Sequences, Sequences -@section Sequence Functions - -@noindent -This section describes a number of Common Lisp functions for -operating on sequences. - -@defun subseq sequence start &optional end -This function returns a given subsequence of the argument -@var{sequence}, which may be a list, string, or vector. -The indices @var{start} and @var{end} must be in range, and -@var{start} must be no greater than @var{end}. If @var{end} -is omitted, it defaults to the length of the sequence. The -return value is always a copy; it does not share structure -with @var{sequence}. - -As an extension to Common Lisp, @var{start} and/or @var{end} -may be negative, in which case they represent a distance back -from the end of the sequence. This is for compatibility with -Emacs's @code{substring} function. Note that @code{subseq} is -the @emph{only} sequence function that allows negative -@var{start} and @var{end}. - -You can use @code{setf} on a @code{subseq} form to replace a -specified range of elements with elements from another sequence. -The replacement is done as if by @code{replace}, described below. -@end defun - -@defun concatenate result-type &rest seqs -This function concatenates the argument sequences together to -form a result sequence of type @var{result-type}, one of the -symbols @code{vector}, @code{string}, or @code{list}. The -arguments are always copied, even in cases such as -@code{(concatenate 'list '(1 2 3))} where the result is -identical to an argument. -@end defun - -@defun fill seq item @t{&key :start :end} -This function fills the elements of the sequence (or the specified -part of the sequence) with the value @var{item}. -@end defun - -@defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2} -This function copies part of @var{seq2} into part of @var{seq1}. -The sequence @var{seq1} is not stretched or resized; the amount -of data copied is simply the shorter of the source and destination -(sub)sequences. The function returns @var{seq1}. - -If @var{seq1} and @var{seq2} are @code{eq}, then the replacement -will work correctly even if the regions indicated by the start -and end arguments overlap. However, if @var{seq1} and @var{seq2} -are lists which share storage but are not @code{eq}, and the -start and end arguments specify overlapping regions, the effect -is undefined. -@end defun - -@defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end} -This returns a copy of @var{seq} with all elements matching -@var{item} removed. The result may share storage with or be -@code{eq} to @var{seq} in some circumstances, but the original -@var{seq} will not be modified. The @code{:test}, @code{:test-not}, -and @code{:key} arguments define the matching test that is used; -by default, elements @code{eql} to @var{item} are removed. The -@code{:count} argument specifies the maximum number of matching -elements that can be removed (only the leftmost @var{count} matches -are removed). The @code{:start} and @code{:end} arguments specify -a region in @var{seq} in which elements will be removed; elements -outside that region are not matched or removed. The @code{:from-end} -argument, if true, says that elements should be deleted from the -end of the sequence rather than the beginning (this matters only -if @var{count} was also specified). -@end defun - -@defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end} -This deletes all elements of @var{seq} which match @var{item}. -It is a destructive operation. Since Emacs Lisp does not support -stretchable strings or vectors, this is the same as @code{remove*} -for those sequence types. On lists, @code{remove*} will copy the -list if necessary to preserve the original list, whereas -@code{delete*} will splice out parts of the argument list. -Compare @code{append} and @code{nconc}, which are analogous -non-destructive and destructive list operations in Emacs Lisp. -@end defun - -@findex remove-if -@findex remove-if-not -@findex delete-if -@findex delete-if-not -The predicate-oriented functions @code{remove-if}, @code{remove-if-not}, -@code{delete-if}, and @code{delete-if-not} are defined similarly. - -@defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end} -This function returns a copy of @var{seq} with duplicate elements -removed. Specifically, if two elements from the sequence match -according to the @code{:test}, @code{:test-not}, and @code{:key} -arguments, only the rightmost one is retained. If @code{:from-end} -is true, the leftmost one is retained instead. If @code{:start} or -@code{:end} is specified, only elements within that subsequence are -examined or removed. -@end defun - -@defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end} -This function deletes duplicate elements from @var{seq}. It is -a destructive version of @code{remove-duplicates}. -@end defun - -@defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} -This function returns a copy of @var{seq}, with all elements -matching @var{old} replaced with @var{new}. The @code{:count}, -@code{:start}, @code{:end}, and @code{:from-end} arguments may be -used to limit the number of substitutions made. -@end defun - -@defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} -This is a destructive version of @code{substitute}; it performs -the substitution using @code{setcar} or @code{aset} rather than -by returning a changed copy of the sequence. -@end defun - -@findex substitute-if -@findex substitute-if-not -@findex nsubstitute-if -@findex nsubstitute-if-not -The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if}, -and @code{nsubstitute-if-not} functions are defined similarly. For -these, a @var{predicate} is given in place of the @var{old} argument. - -@node Searching Sequences, Sorting Sequences, Sequence Functions, Sequences -@section Searching Sequences - -@noindent -These functions search for elements or subsequences in a sequence. -(See also @code{member*} and @code{assoc*}; @pxref{Lists}.) - -@defun find item seq @t{&key :test :test-not :key :start :end :from-end} -This function searches @var{seq} for an element matching @var{item}. -If it finds a match, it returns the matching element. Otherwise, -it returns @code{nil}. It returns the leftmost match, unless -@code{:from-end} is true, in which case it returns the rightmost -match. The @code{:start} and @code{:end} arguments may be used to -limit the range of elements that are searched. -@end defun - -@defun position item seq @t{&key :test :test-not :key :start :end :from-end} -This function is like @code{find}, except that it returns the -integer position in the sequence of the matching item rather than -the item itself. The position is relative to the start of the -sequence as a whole, even if @code{:start} is non-zero. The function -returns @code{nil} if no matching element was found. -@end defun - -@defun count item seq @t{&key :test :test-not :key :start :end} -This function returns the number of elements of @var{seq} which -match @var{item}. The result is always a nonnegative integer. -@end defun - -@findex find-if -@findex find-if-not -@findex position-if -@findex position-if-not -@findex count-if -@findex count-if-not -The @code{find-if}, @code{find-if-not}, @code{position-if}, -@code{position-if-not}, @code{count-if}, and @code{count-if-not} -functions are defined similarly. - -@defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end} -This function compares the specified parts of @var{seq1} and -@var{seq2}. If they are the same length and the corresponding -elements match (according to @code{:test}, @code{:test-not}, -and @code{:key}), the function returns @code{nil}. If there is -a mismatch, the function returns the index (relative to @var{seq1}) -of the first mismatching element. This will be the leftmost pair of -elements which do not match, or the position at which the shorter of -the two otherwise-matching sequences runs out. - -If @code{:from-end} is true, then the elements are compared from right -to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}. -If the sequences differ, then one plus the index of the rightmost -difference (relative to @var{seq1}) is returned. - -An interesting example is @code{(mismatch str1 str2 :key 'upcase)}, -which compares two strings case-insensitively. -@end defun - -@defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2} -This function searches @var{seq2} for a subsequence that matches -@var{seq1} (or part of it specified by @code{:start1} and -@code{:end1}.) Only matches which fall entirely within the region -defined by @code{:start2} and @code{:end2} will be considered. -The return value is the index of the leftmost element of the -leftmost match, relative to the start of @var{seq2}, or @code{nil} -if no matches were found. If @code{:from-end} is true, the -function finds the @emph{rightmost} matching subsequence. -@end defun - -@node Sorting Sequences, , Searching Sequences, Sequences -@section Sorting Sequences - -@defun sort* seq predicate @t{&key :key} -This function sorts @var{seq} into increasing order as determined -by using @var{predicate} to compare pairs of elements. @var{predicate} -should return true (non-@code{nil}) if and only if its first argument -is less than (not equal to) its second argument. For example, -@code{<} and @code{string-lessp} are suitable predicate functions -for sorting numbers and strings, respectively; @code{>} would sort -numbers into decreasing rather than increasing order. - -This function differs from Emacs's built-in @code{sort} in that it -can operate on any type of sequence, not just lists. Also, it -accepts a @code{:key} argument which is used to preprocess data -fed to the @var{predicate} function. For example, - -@example -(setq data (sort* data 'string-lessp :key 'downcase)) -@end example - -@noindent -sorts @var{data}, a sequence of strings, into increasing alphabetical -order without regard to case. A @code{:key} function of @code{car} -would be useful for sorting association lists. It should only be a -simple accessor though, it's used heavily in the current -implementation. - -The @code{sort*} function is destructive; it sorts lists by actually -rearranging the @code{cdr} pointers in suitable fashion. -@end defun - -@defun stable-sort seq predicate @t{&key :key} -This function sorts @var{seq} @dfn{stably}, meaning two elements -which are equal in terms of @var{predicate} are guaranteed not to -be rearranged out of their original order by the sort. - -In practice, @code{sort*} and @code{stable-sort} are equivalent -in Emacs Lisp because the underlying @code{sort} function is -stable by default. However, this package reserves the right to -use non-stable methods for @code{sort*} in the future. -@end defun - -@defun merge type seq1 seq2 predicate @t{&key :key} -This function merges two sequences @var{seq1} and @var{seq2} by -interleaving their elements. The result sequence, of type @var{type} -(in the sense of @code{concatenate}), has length equal to the sum -of the lengths of the two input sequences. The sequences may be -modified destructively. Order of elements within @var{seq1} and -@var{seq2} is preserved in the interleaving; elements of the two -sequences are compared by @var{predicate} (in the sense of -@code{sort}) and the lesser element goes first in the result. -When elements are equal, those from @var{seq1} precede those from -@var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are -both sorted according to @var{predicate}, then the result will be -a merged sequence which is (stably) sorted according to -@var{predicate}. -@end defun - -@node Lists, Structures, Sequences, Top -@chapter Lists - -@noindent -The functions described here operate on lists. - -@menu -* List Functions:: @code{caddr}, @code{first}, @code{list*}, etc. -* Substitution of Expressions:: @code{subst}, @code{sublis}, etc. -* Lists as Sets:: @code{member*}, @code{adjoin}, @code{union}, etc. -* Association Lists:: @code{assoc*}, @code{rassoc*}, @code{acons}, @code{pairlis} -@end menu - -@node List Functions, Substitution of Expressions, Lists, Lists -@section List Functions - -@noindent -This section describes a number of simple operations on lists, -i.e., chains of cons cells. - -@defun caddr x -This function is equivalent to @code{(car (cdr (cdr @var{x})))}. -Likewise, this package defines all 28 @code{c@var{xxx}r} functions -where @var{xxx} is up to four @samp{a}s and/or @samp{d}s. -All of these functions are @code{setf}-able, and calls to them -are expanded inline by the byte-compiler for maximum efficiency. -@end defun - -@defun first x -This function is a synonym for @code{(car @var{x})}. Likewise, -the functions @code{second}, @code{third}, @dots{}, through -@code{tenth} return the given element of the list @var{x}. -@end defun - -@defun rest x -This function is a synonym for @code{(cdr @var{x})}. -@end defun - -@defun endp x -Common Lisp defines this function to act like @code{null}, but -signaling an error if @code{x} is neither a @code{nil} nor a -cons cell. This package simply defines @code{endp} as a synonym -for @code{null}. -@end defun - -@defun list-length x -This function returns the length of list @var{x}, exactly like -@code{(length @var{x})}, except that if @var{x} is a circular -list (where the cdr-chain forms a loop rather than terminating -with @code{nil}), this function returns @code{nil}. (The regular -@code{length} function would get stuck if given a circular list.) -@end defun - -@defun list* arg &rest others -This function constructs a list of its arguments. The final -argument becomes the @code{cdr} of the last cell constructed. -Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to -@code{(cons @var{a} (cons @var{b} @var{c}))}, and -@code{(list* @var{a} @var{b} nil)} is equivalent to -@code{(list @var{a} @var{b})}. - -(Note that this function really is called @code{list*} in Common -Lisp; it is not a name invented for this package like @code{member*} -or @code{defun*}.) -@end defun - -@defun ldiff list sublist -If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to -one of the cons cells of @var{list}, then this function returns -a copy of the part of @var{list} up to but not including -@var{sublist}. For example, @code{(ldiff x (cddr x))} returns -the first two elements of the list @code{x}. The result is a -copy; the original @var{list} is not modified. If @var{sublist} -is not a sublist of @var{list}, a copy of the entire @var{list} -is returned. -@end defun - -@defun copy-list list -This function returns a copy of the list @var{list}. It copies -dotted lists like @code{(1 2 . 3)} correctly. -@end defun - -@defun copy-tree x &optional vecp -This function returns a copy of the tree of cons cells @var{x}. -Unlike @code{copy-sequence} (and its alias @code{copy-list}), -which copies only along the @code{cdr} direction, this function -copies (recursively) along both the @code{car} and the @code{cdr} -directions. If @var{x} is not a cons cell, the function simply -returns @var{x} unchanged. If the optional @var{vecp} argument -is true, this function copies vectors (recursively) as well as -cons cells. -@end defun - -@defun tree-equal x y @t{&key :test :test-not :key} -This function compares two trees of cons cells. If @var{x} and -@var{y} are both cons cells, their @code{car}s and @code{cdr}s are -compared recursively. If neither @var{x} nor @var{y} is a cons -cell, they are compared by @code{eql}, or according to the -specified test. The @code{:key} function, if specified, is -applied to the elements of both trees. @xref{Sequences}. -@end defun - -@iftex -@secno=3 -@end iftex - -@node Substitution of Expressions, Lists as Sets, List Functions, Lists -@section Substitution of Expressions - -@noindent -These functions substitute elements throughout a tree of cons -cells. (@xref{Sequence Functions}, for the @code{substitute} -function, which works on just the top-level elements of a list.) - -@defun subst new old tree @t{&key :test :test-not :key} -This function substitutes occurrences of @var{old} with @var{new} -in @var{tree}, a tree of cons cells. It returns a substituted -tree, which will be a copy except that it may share storage with -the argument @var{tree} in parts where no substitutions occurred. -The original @var{tree} is not modified. This function recurses -on, and compares against @var{old}, both @code{car}s and @code{cdr}s -of the component cons cells. If @var{old} is itself a cons cell, -then matching cells in the tree are substituted as usual without -recursively substituting in that cell. Comparisons with @var{old} -are done according to the specified test (@code{eql} by default). -The @code{:key} function is applied to the elements of the tree -but not to @var{old}. -@end defun - -@defun nsubst new old tree @t{&key :test :test-not :key} -This function is like @code{subst}, except that it works by -destructive modification (by @code{setcar} or @code{setcdr}) -rather than copying. -@end defun - -@findex subst-if -@findex subst-if-not -@findex nsubst-if -@findex nsubst-if-not -The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and -@code{nsubst-if-not} functions are defined similarly. - -@defun sublis alist tree @t{&key :test :test-not :key} -This function is like @code{subst}, except that it takes an -association list @var{alist} of @var{old}-@var{new} pairs. -Each element of the tree (after applying the @code{:key} -function, if any), is compared with the @code{car}s of -@var{alist}; if it matches, it is replaced by the corresponding -@code{cdr}. -@end defun - -@defun nsublis alist tree @t{&key :test :test-not :key} -This is a destructive version of @code{sublis}. -@end defun - -@node Lists as Sets, Association Lists, Substitution of Expressions, Lists -@section Lists as Sets - -@noindent -These functions perform operations on lists which represent sets -of elements. - -@defun member* item list @t{&key :test :test-not :key} -This function searches @var{list} for an element matching @var{item}. -If a match is found, it returns the cons cell whose @code{car} was -the matching element. Otherwise, it returns @code{nil}. Elements -are compared by @code{eql} by default; you can use the @code{:test}, -@code{:test-not}, and @code{:key} arguments to modify this behavior. -@xref{Sequences}. - -Note that this function's name is suffixed by @samp{*} to avoid -the incompatible @code{member} function defined in Emacs. -(That function uses @code{equal} for comparisons; it is equivalent -to @code{(member* @var{item} @var{list} :test 'equal)}.) -@end defun - -@findex member-if -@findex member-if-not -The @code{member-if} and @code{member-if-not} functions -analogously search for elements which satisfy a given predicate. - -@defun tailp sublist list -This function returns @code{t} if @var{sublist} is a sublist of -@var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to -any of its @code{cdr}s. -@end defun - -@defun adjoin item list @t{&key :test :test-not :key} -This function conses @var{item} onto the front of @var{list}, -like @code{(cons @var{item} @var{list})}, but only if @var{item} -is not already present on the list (as determined by @code{member*}). -If a @code{:key} argument is specified, it is applied to -@var{item} as well as to the elements of @var{list} during -the search, on the reasoning that @var{item} is ``about'' to -become part of the list. -@end defun - -@defun union list1 list2 @t{&key :test :test-not :key} -This function combines two lists which represent sets of items, -returning a list that represents the union of those two sets. -The result list will contain all items which appear in @var{list1} -or @var{list2}, and no others. If an item appears in both -@var{list1} and @var{list2} it will be copied only once. If -an item is duplicated in @var{list1} or @var{list2}, it is -undefined whether or not that duplication will survive in the -result list. The order of elements in the result list is also -undefined. -@end defun - -@defun nunion list1 list2 @t{&key :test :test-not :key} -This is a destructive version of @code{union}; rather than copying, -it tries to reuse the storage of the argument lists if possible. -@end defun - -@defun intersection list1 list2 @t{&key :test :test-not :key} -This function computes the intersection of the sets represented -by @var{list1} and @var{list2}. It returns the list of items -which appear in both @var{list1} and @var{list2}. -@end defun - -@defun nintersection list1 list2 @t{&key :test :test-not :key} -This is a destructive version of @code{intersection}. It -tries to reuse storage of @var{list1} rather than copying. -It does @emph{not} reuse the storage of @var{list2}. -@end defun - -@defun set-difference list1 list2 @t{&key :test :test-not :key} -This function computes the ``set difference'' of @var{list1} -and @var{list2}, i.e., the set of elements that appear in -@var{list1} but @emph{not} in @var{list2}. -@end defun - -@defun nset-difference list1 list2 @t{&key :test :test-not :key} -This is a destructive @code{set-difference}, which will try -to reuse @var{list1} if possible. -@end defun - -@defun set-exclusive-or list1 list2 @t{&key :test :test-not :key} -This function computes the ``set exclusive or'' of @var{list1} -and @var{list2}, i.e., the set of elements that appear in -exactly one of @var{list1} and @var{list2}. -@end defun - -@defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key} -This is a destructive @code{set-exclusive-or}, which will try -to reuse @var{list1} and @var{list2} if possible. -@end defun - -@defun subsetp list1 list2 @t{&key :test :test-not :key} -This function checks whether @var{list1} represents a subset -of @var{list2}, i.e., whether every element of @var{list1} -also appears in @var{list2}. -@end defun - -@node Association Lists, , Lists as Sets, Lists -@section Association Lists - -@noindent -An @dfn{association list} is a list representing a mapping from -one set of values to another; any list whose elements are cons -cells is an association list. - -@defun assoc* item a-list @t{&key :test :test-not :key} -This function searches the association list @var{a-list} for an -element whose @code{car} matches (in the sense of @code{:test}, -@code{:test-not}, and @code{:key}, or by comparison with @code{eql}) -a given @var{item}. It returns the matching element, if any, -otherwise @code{nil}. It ignores elements of @var{a-list} which -are not cons cells. (This corresponds to the behavior of -@code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's -@code{assoc} ignores @code{nil}s but considers any other non-cons -elements of @var{a-list} to be an error.) -@end defun - -@defun rassoc* item a-list @t{&key :test :test-not :key} -This function searches for an element whose @code{cdr} matches -@var{item}. If @var{a-list} represents a mapping, this applies -the inverse of the mapping to @var{item}. -@end defun - -@findex assoc-if -@findex assoc-if-not -@findex rassoc-if -@findex rassoc-if-not -The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if}, -and @code{rassoc-if-not} functions are defined similarly. - -Two simple functions for constructing association lists are: - -@defun acons key value alist -This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}. -@end defun - -@defun pairlis keys values &optional alist -This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values}) -@var{alist})}. -@end defun - -@iftex -@chapno=18 -@end iftex - -@node Structures, Assertions, Lists, Top -@chapter Structures - -@noindent -The Common Lisp @dfn{structure} mechanism provides a general way -to define data types similar to C's @code{struct} types. A -structure is a Lisp object containing some number of @dfn{slots}, -each of which can hold any Lisp data object. Functions are -provided for accessing and setting the slots, creating or copying -structure objects, and recognizing objects of a particular structure -type. - -In true Common Lisp, each structure type is a new type distinct -from all existing Lisp types. Since the underlying Emacs Lisp -system provides no way to create new distinct types, this package -implements structures as vectors (or lists upon request) with a -special ``tag'' symbol to identify them. - -@defspec defstruct name slots@dots{} -The @code{defstruct} form defines a new structure type called -@var{name}, with the specified @var{slots}. (The @var{slots} -may begin with a string which documents the structure type.) -In the simplest case, @var{name} and each of the @var{slots} -are symbols. For example, - -@example -(defstruct person name age sex) -@end example - -@noindent -defines a struct type called @code{person} which contains three -slots. Given a @code{person} object @var{p}, you can access those -slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})}, -and @code{(person-sex @var{p})}. You can also change these slots by -using @code{setf} on any of these place forms: - -@example -(incf (person-age birthday-boy)) -@end example - -You can create a new @code{person} by calling @code{make-person}, -which takes keyword arguments @code{:name}, @code{:age}, and -@code{:sex} to specify the initial values of these slots in the -new object. (Omitting any of these arguments leaves the corresponding -slot ``undefined,'' according to the Common Lisp standard; in Emacs -Lisp, such uninitialized slots are filled with @code{nil}.) - -Given a @code{person}, @code{(copy-person @var{p})} makes a new -object of the same type whose slots are @code{eq} to those of @var{p}. - -Given any Lisp object @var{x}, @code{(person-p @var{x})} returns -true if @var{x} looks like a @code{person}, false otherwise. (Again, -in Common Lisp this predicate would be exact; in Emacs Lisp the -best it can do is verify that @var{x} is a vector of the correct -length which starts with the correct tag symbol.) - -Accessors like @code{person-name} normally check their arguments -(effectively using @code{person-p}) and signal an error if the -argument is the wrong type. This check is affected by -@code{(optimize (safety @dots{}))} declarations. Safety level 1, -the default, uses a somewhat optimized check that will detect all -incorrect arguments, but may use an uninformative error message -(e.g., ``expected a vector'' instead of ``expected a @code{person}''). -Safety level 0 omits all checks except as provided by the underlying -@code{aref} call; safety levels 2 and 3 do rigorous checking that will -always print a descriptive error message for incorrect inputs. -@xref{Declarations}. - -@example -(setq dave (make-person :name "Dave" :sex 'male)) - @result{} [cl-struct-person "Dave" nil male] -(setq other (copy-person dave)) - @result{} [cl-struct-person "Dave" nil male] -(eq dave other) - @result{} nil -(eq (person-name dave) (person-name other)) - @result{} t -(person-p dave) - @result{} t -(person-p [1 2 3 4]) - @result{} nil -(person-p "Bogus") - @result{} nil -(person-p '[cl-struct-person counterfeit person object]) - @result{} t -@end example - -In general, @var{name} is either a name symbol or a list of a name -symbol followed by any number of @dfn{struct options}; each @var{slot} -is either a slot symbol or a list of the form @samp{(@var{slot-name} -@var{default-value} @var{slot-options}@dots{})}. The @var{default-value} -is a Lisp form which is evaluated any time an instance of the -structure type is created without specifying that slot's value. - -Common Lisp defines several slot options, but the only one -implemented in this package is @code{:read-only}. A non-@code{nil} -value for this option means the slot should not be @code{setf}-able; -the slot's value is determined when the object is created and does -not change afterward. - -@example -(defstruct person - (name nil :read-only t) - age - (sex 'unknown)) -@end example - -Any slot options other than @code{:read-only} are ignored. - -For obscure historical reasons, structure options take a different -form than slot options. A structure option is either a keyword -symbol, or a list beginning with a keyword symbol possibly followed -by arguments. (By contrast, slot options are key-value pairs not -enclosed in lists.) - -@example -(defstruct (person (:constructor create-person) - (:type list) - :named) - name age sex) -@end example - -The following structure options are recognized. - -@table @code -@iftex -@itemmax=0 in -@advance@leftskip-.5@tableindent -@end iftex -@item :conc-name -The argument is a symbol whose print name is used as the prefix for -the names of slot accessor functions. The default is the name of -the struct type followed by a hyphen. The option @code{(:conc-name p-)} -would change this prefix to @code{p-}. Specifying @code{nil} as an -argument means no prefix, so that the slot names themselves are used -to name the accessor functions. - -@item :constructor -In the simple case, this option takes one argument which is an -alternate name to use for the constructor function. The default -is @code{make-@var{name}}, e.g., @code{make-person}. The above -example changes this to @code{create-person}. Specifying @code{nil} -as an argument means that no standard constructor should be -generated at all. - -In the full form of this option, the constructor name is followed -by an arbitrary argument list. @xref{Program Structure}, for a -description of the format of Common Lisp argument lists. All -options, such as @code{&rest} and @code{&key}, are supported. -The argument names should match the slot names; each slot is -initialized from the corresponding argument. Slots whose names -do not appear in the argument list are initialized based on the -@var{default-value} in their slot descriptor. Also, @code{&optional} -and @code{&key} arguments which don't specify defaults take their -defaults from the slot descriptor. It is valid to include arguments -which don't correspond to slot names; these are useful if they are -referred to in the defaults for optional, keyword, or @code{&aux} -arguments which @emph{do} correspond to slots. - -You can specify any number of full-format @code{:constructor} -options on a structure. The default constructor is still generated -as well unless you disable it with a simple-format @code{:constructor} -option. - -@example -(defstruct - (person - (:constructor nil) ; no default constructor - (:constructor new-person (name sex &optional (age 0))) - (:constructor new-hound (&key (name "Rover") - (dog-years 0) - &aux (age (* 7 dog-years)) - (sex 'canine)))) - name age sex) -@end example - -The first constructor here takes its arguments positionally rather -than by keyword. (In official Common Lisp terminology, constructors -that work By Order of Arguments instead of by keyword are called -``BOA constructors.'' No, I'm not making this up.) For example, -@code{(new-person "Jane" 'female)} generates a person whose slots -are @code{"Jane"}, 0, and @code{female}, respectively. - -The second constructor takes two keyword arguments, @code{:name}, -which initializes the @code{name} slot and defaults to @code{"Rover"}, -and @code{:dog-years}, which does not itself correspond to a slot -but which is used to initialize the @code{age} slot. The @code{sex} -slot is forced to the symbol @code{canine} with no syntax for -overriding it. - -@item :copier -The argument is an alternate name for the copier function for -this type. The default is @code{copy-@var{name}}. @code{nil} -means not to generate a copier function. (In this implementation, -all copier functions are simply synonyms for @code{copy-sequence}.) - -@item :predicate -The argument is an alternate name for the predicate which recognizes -objects of this type. The default is @code{@var{name}-p}. @code{nil} -means not to generate a predicate function. (If the @code{:type} -option is used without the @code{:named} option, no predicate is -ever generated.) - -In true Common Lisp, @code{typep} is always able to recognize a -structure object even if @code{:predicate} was used. In this -package, @code{typep} simply looks for a function called -@code{@var{typename}-p}, so it will work for structure types -only if they used the default predicate name. - -@item :include -This option implements a very limited form of C++-style inheritance. -The argument is the name of another structure type previously -created with @code{defstruct}. The effect is to cause the new -structure type to inherit all of the included structure's slots -(plus, of course, any new slots described by this struct's slot -descriptors). The new structure is considered a ``specialization'' -of the included one. In fact, the predicate and slot accessors -for the included type will also accept objects of the new type. - -If there are extra arguments to the @code{:include} option after -the included-structure name, these options are treated as replacement -slot descriptors for slots in the included structure, possibly with -modified default values. Borrowing an example from Steele: - -@example -(defstruct person name (age 0) sex) - @result{} person -(defstruct (astronaut (:include person (age 45))) - helmet-size - (favorite-beverage 'tang)) - @result{} astronaut - -(setq joe (make-person :name "Joe")) - @result{} [cl-struct-person "Joe" 0 nil] -(setq buzz (make-astronaut :name "Buzz")) - @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang] - -(list (person-p joe) (person-p buzz)) - @result{} (t t) -(list (astronaut-p joe) (astronaut-p buzz)) - @result{} (nil t) - -(person-name buzz) - @result{} "Buzz" -(astronaut-name joe) - @result{} error: "astronaut-name accessing a non-astronaut" -@end example - -Thus, if @code{astronaut} is a specialization of @code{person}, -then every @code{astronaut} is also a @code{person} (but not the -other way around). Every @code{astronaut} includes all the slots -of a @code{person}, plus extra slots that are specific to -astronauts. Operations that work on people (like @code{person-name}) -work on astronauts just like other people. - -@item :print-function -In full Common Lisp, this option allows you to specify a function -which is called to print an instance of the structure type. The -Emacs Lisp system offers no hooks into the Lisp printer which would -allow for such a feature, so this package simply ignores -@code{:print-function}. - -@item :type -The argument should be one of the symbols @code{vector} or @code{list}. -This tells which underlying Lisp data type should be used to implement -the new structure type. Vectors are used by default, but -@code{(:type list)} will cause structure objects to be stored as -lists instead. - -The vector representation for structure objects has the advantage -that all structure slots can be accessed quickly, although creating -vectors is a bit slower in Emacs Lisp. Lists are easier to create, -but take a relatively long time accessing the later slots. - -@item :named -This option, which takes no arguments, causes a characteristic ``tag'' -symbol to be stored at the front of the structure object. Using -@code{:type} without also using @code{:named} will result in a -structure type stored as plain vectors or lists with no identifying -features. - -The default, if you don't specify @code{:type} explicitly, is to -use named vectors. Therefore, @code{:named} is only useful in -conjunction with @code{:type}. - -@example -(defstruct (person1) name age sex) -(defstruct (person2 (:type list) :named) name age sex) -(defstruct (person3 (:type list)) name age sex) - -(setq p1 (make-person1)) - @result{} [cl-struct-person1 nil nil nil] -(setq p2 (make-person2)) - @result{} (person2 nil nil nil) -(setq p3 (make-person3)) - @result{} (nil nil nil) - -(person1-p p1) - @result{} t -(person2-p p2) - @result{} t -(person3-p p3) - @result{} error: function person3-p undefined -@end example - -Since unnamed structures don't have tags, @code{defstruct} is not -able to make a useful predicate for recognizing them. Also, -accessors like @code{person3-name} will be generated but they -will not be able to do any type checking. The @code{person3-name} -function, for example, will simply be a synonym for @code{car} in -this case. By contrast, @code{person2-name} is able to verify -that its argument is indeed a @code{person2} object before -proceeding. - -@item :initial-offset -The argument must be a nonnegative integer. It specifies a -number of slots to be left ``empty'' at the front of the -structure. If the structure is named, the tag appears at the -specified position in the list or vector; otherwise, the first -slot appears at that position. Earlier positions are filled -with @code{nil} by the constructors and ignored otherwise. If -the type @code{:include}s another type, then @code{:initial-offset} -specifies a number of slots to be skipped between the last slot -of the included type and the first new slot. -@end table -@end defspec - -Except as noted, the @code{defstruct} facility of this package is -entirely compatible with that of Common Lisp. - -@iftex -@chapno=23 -@end iftex - -@node Assertions, Efficiency Concerns, Structures, Top -@chapter Assertions and Errors - -@noindent -This section describes two macros that test @dfn{assertions}, i.e., -conditions which must be true if the program is operating correctly. -Assertions never add to the behavior of a Lisp program; they simply -make ``sanity checks'' to make sure everything is as it should be. - -If the optimization property @code{speed} has been set to 3, and -@code{safety} is less than 3, then the byte-compiler will optimize -away the following assertions. Because assertions might be optimized -away, it is a bad idea for them to include side-effects. - -@defspec assert test-form [show-args string args@dots{}] -This form verifies that @var{test-form} is true (i.e., evaluates to -a non-@code{nil} value). If so, it returns @code{nil}. If the test -is not satisfied, @code{assert} signals an error. - -A default error message will be supplied which includes @var{test-form}. -You can specify a different error message by including a @var{string} -argument plus optional extra arguments. Those arguments are simply -passed to @code{error} to signal the error. - -If the optional second argument @var{show-args} is @code{t} instead -of @code{nil}, then the error message (with or without @var{string}) -will also include all non-constant arguments of the top-level -@var{form}. For example: - -@example -(assert (> x 10) t "x is too small: %d") -@end example - -This usage of @var{show-args} is an extension to Common Lisp. In -true Common Lisp, the second argument gives a list of @var{places} -which can be @code{setf}'d by the user before continuing from the -error. Since Emacs Lisp does not support continuable errors, it -makes no sense to specify @var{places}. -@end defspec - -@defspec check-type form type [string] -This form verifies that @var{form} evaluates to a value of type -@var{type}. If so, it returns @code{nil}. If not, @code{check-type} -signals a @code{wrong-type-argument} error. The default error message -lists the erroneous value along with @var{type} and @var{form} -themselves. If @var{string} is specified, it is included in the -error message in place of @var{type}. For example: - -@example -(check-type x (integer 1 *) "a positive integer") -@end example - -@xref{Type Predicates}, for a description of the type specifiers -that may be used for @var{type}. - -Note that in Common Lisp, the first argument to @code{check-type} -must be a @var{place} suitable for use by @code{setf}, because -@code{check-type} signals a continuable error that allows the -user to modify @var{place}. -@end defspec - -The following error-related macro is also defined: - -@defspec ignore-errors forms@dots{} -This executes @var{forms} exactly like a @code{progn}, except that -errors are ignored during the @var{forms}. More precisely, if -an error is signaled then @code{ignore-errors} immediately -aborts execution of the @var{forms} and returns @code{nil}. -If the @var{forms} complete successfully, @code{ignore-errors} -returns the result of the last @var{form}. -@end defspec - -@node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top -@appendix Efficiency Concerns - -@appendixsec Macros - -@noindent -Many of the advanced features of this package, such as @code{defun*}, -@code{loop}, and @code{setf}, are implemented as Lisp macros. In -byte-compiled code, these complex notations will be expanded into -equivalent Lisp code which is simple and efficient. For example, -the forms - -@example -(incf i n) -(push x (car p)) -@end example - -@noindent -are expanded at compile-time to the Lisp forms - -@example -(setq i (+ i n)) -(setcar p (cons x (car p))) -@end example - -@noindent -which are the most efficient ways of doing these respective operations -in Lisp. Thus, there is no performance penalty for using the more -readable @code{incf} and @code{push} forms in your compiled code. - -@emph{Interpreted} code, on the other hand, must expand these macros -every time they are executed. For this reason it is strongly -recommended that code making heavy use of macros be compiled. -(The features labeled ``Special Form'' instead of ``Function'' in -this manual are macros.) A loop using @code{incf} a hundred times -will execute considerably faster if compiled, and will also -garbage-collect less because the macro expansion will not have -to be generated, used, and thrown away a hundred times. - -You can find out how a macro expands by using the -@code{cl-prettyexpand} function. - -@defun cl-prettyexpand form &optional full -This function takes a single Lisp form as an argument and inserts -a nicely formatted copy of it in the current buffer (which must be -in Lisp mode so that indentation works properly). It also expands -all Lisp macros which appear in the form. The easiest way to use -this function is to go to the @code{*scratch*} buffer and type, say, - -@example -(cl-prettyexpand '(loop for x below 10 collect x)) -@end example - -@noindent -and type @kbd{C-x C-e} immediately after the closing parenthesis; -the expansion - -@example -(block nil - (let* ((x 0) - (G1004 nil)) - (while (< x 10) - (setq G1004 (cons x G1004)) - (setq x (+ x 1))) - (nreverse G1004))) -@end example - -@noindent -will be inserted into the buffer. (The @code{block} macro is -expanded differently in the interpreter and compiler, so -@code{cl-prettyexpand} just leaves it alone. The temporary -variable @code{G1004} was created by @code{gensym}.) - -If the optional argument @var{full} is true, then @emph{all} -macros are expanded, including @code{block}, @code{eval-when}, -and compiler macros. Expansion is done as if @var{form} were -a top-level form in a file being compiled. For example, - -@example -(cl-prettyexpand '(pushnew 'x list)) - @print{} (setq list (adjoin 'x list)) -(cl-prettyexpand '(pushnew 'x list) t) - @print{} (setq list (if (memq 'x list) list (cons 'x list))) -(cl-prettyexpand '(caddr (member* 'a list)) t) - @print{} (car (cdr (cdr (memq 'a list)))) -@end example - -Note that @code{adjoin}, @code{caddr}, and @code{member*} all -have built-in compiler macros to optimize them in common cases. -@end defun - -@ifinfo -@example - -@end example -@end ifinfo -@appendixsec Error Checking - -@noindent -Common Lisp compliance has in general not been sacrificed for the -sake of efficiency. A few exceptions have been made for cases -where substantial gains were possible at the expense of marginal -incompatibility. - -The Common Lisp standard (as embodied in Steele's book) uses the -phrase ``it is an error if'' to indicate a situation which is not -supposed to arise in complying programs; implementations are strongly -encouraged but not required to signal an error in these situations. -This package sometimes omits such error checking in the interest of -compactness and efficiency. For example, @code{do} variable -specifiers are supposed to be lists of one, two, or three forms; -extra forms are ignored by this package rather than signaling a -syntax error. The @code{endp} function is simply a synonym for -@code{null} in this package. Functions taking keyword arguments -will accept an odd number of arguments, treating the trailing -keyword as if it were followed by the value @code{nil}. - -Argument lists (as processed by @code{defun*} and friends) -@emph{are} checked rigorously except for the minor point just -mentioned; in particular, keyword arguments are checked for -validity, and @code{&allow-other-keys} and @code{:allow-other-keys} -are fully implemented. Keyword validity checking is slightly -time consuming (though not too bad in byte-compiled code); -you can use @code{&allow-other-keys} to omit this check. Functions -defined in this package such as @code{find} and @code{member*} -do check their keyword arguments for validity. - -@ifinfo -@example - -@end example -@end ifinfo -@appendixsec Optimizing Compiler - -@noindent -Use of the optimizing Emacs compiler is highly recommended; many of the Common -Lisp macros emit -code which can be improved by optimization. In particular, -@code{block}s (whether explicit or implicit in constructs like -@code{defun*} and @code{loop}) carry a fair run-time penalty; the -optimizing compiler removes @code{block}s which are not actually -referenced by @code{return} or @code{return-from} inside the block. - -@node Common Lisp Compatibility, Old CL Compatibility, Efficiency Concerns, Top -@appendix Common Lisp Compatibility - -@noindent -Following is a list of all known incompatibilities between this -package and Common Lisp as documented in Steele (2nd edition). - -Certain function names, such as @code{member}, @code{assoc}, and -@code{floor}, were already taken by (incompatible) Emacs Lisp -functions; this package appends @samp{*} to the names of its -Common Lisp versions of these functions. - -The word @code{defun*} is required instead of @code{defun} in order -to use extended Common Lisp argument lists in a function. Likewise, -@code{defmacro*} and @code{function*} are versions of those forms -which understand full-featured argument lists. The @code{&whole} -keyword does not work in @code{defmacro} argument lists (except -inside recursive argument lists). - -The @code{equal} predicate does not distinguish -between IEEE floating-point plus and minus zero. The @code{equalp} -predicate has several differences with Common Lisp; @pxref{Predicates}. - -The @code{setf} mechanism is entirely compatible, except that -setf-methods return a list of five values rather than five -values directly. Also, the new ``@code{setf} function'' concept -(typified by @code{(defun (setf foo) @dots{})}) is not implemented. - -The @code{do-all-symbols} form is the same as @code{do-symbols} -with no @var{obarray} argument. In Common Lisp, this form would -iterate over all symbols in all packages. Since Emacs obarrays -are not a first-class package mechanism, there is no way for -@code{do-all-symbols} to locate any but the default obarray. - -The @code{loop} macro is complete except that @code{loop-finish} -and type specifiers are unimplemented. - -The multiple-value return facility treats lists as multiple -values, since Emacs Lisp cannot support multiple return values -directly. The macros will be compatible with Common Lisp if -@code{values} or @code{values-list} is always used to return to -a @code{multiple-value-bind} or other multiple-value receiver; -if @code{values} is used without @code{multiple-value-@dots{}} -or vice-versa the effect will be different from Common Lisp. - -Many Common Lisp declarations are ignored, and others match -the Common Lisp standard in concept but not in detail. For -example, local @code{special} declarations, which are purely -advisory in Emacs Lisp, do not rigorously obey the scoping rules -set down in Steele's book. - -The variable @code{*gensym-counter*} starts out with a pseudo-random -value rather than with zero. This is to cope with the fact that -generated symbols become interned when they are written to and -loaded back from a file. - -The @code{defstruct} facility is compatible, except that structures -are of type @code{:type vector :named} by default rather than some -special, distinct type. Also, the @code{:type} slot option is ignored. - -The second argument of @code{check-type} is treated differently. - -@node Old CL Compatibility, Porting Common Lisp, Common Lisp Compatibility, Top -@appendix Old CL Compatibility - -@noindent -Following is a list of all known incompatibilities between this package -and the older Quiroz @file{cl.el} package. - -This package's emulation of multiple return values in functions is -incompatible with that of the older package. That package attempted -to come as close as possible to true Common Lisp multiple return -values; unfortunately, it could not be 100% reliable and so was prone -to occasional surprises if used freely. This package uses a simpler -method, namely replacing multiple values with lists of values, which -is more predictable though more noticeably different from Common Lisp. - -The @code{defkeyword} form and @code{keywordp} function are not -implemented in this package. - -The @code{member}, @code{floor}, @code{ceiling}, @code{truncate}, -@code{round}, @code{mod}, and @code{rem} functions are suffixed -by @samp{*} in this package to avoid collision with existing -functions in Emacs. The older package simply -redefined these functions, overwriting the built-in meanings and -causing serious portability problems. (Some more -recent versions of the Quiroz package changed the names to -@code{cl-member}, etc.; this package defines the latter names as -aliases for @code{member*}, etc.) - -Certain functions in the old package which were buggy or inconsistent -with the Common Lisp standard are incompatible with the conforming -versions in this package. For example, @code{eql} and @code{member} -were synonyms for @code{eq} and @code{memq} in that package, @code{setf} -failed to preserve correct order of evaluation of its arguments, etc. - -Finally, unlike the older package, this package is careful to -prefix all of its internal names with @code{cl-}. Except for a -few functions which are explicitly defined as additional features -(such as @code{floatp-safe} and @code{letf}), this package does not -export any non-@samp{cl-} symbols which are not also part of Common -Lisp. - -@ifinfo -@example - -@end example -@end ifinfo -@appendixsec The @code{cl-compat} package - -@noindent -The @dfn{CL} package includes emulations of some features of the -old @file{cl.el}, in the form of a compatibility package -@code{cl-compat}. This file is obsolete and may be removed in future, -so it should not be used in new code. - -The old package defined a number of internal routines without -@code{cl-} prefixes or other annotations. Call to these routines -may have crept into existing Lisp code. @code{cl-compat} -provides emulations of the following internal routines: -@code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists}, -@code{reassemble-arglists}, @code{duplicate-symbols-p}, -@code{safe-idiv}. - -Some @code{setf} forms translated into calls to internal -functions that user code might call directly. The functions -@code{setnth}, @code{setnthcdr}, and @code{setelt} fall in -this category; they are defined by @code{cl-compat}, but the -best fix is to change to use @code{setf} properly. - -The @code{cl-compat} file defines the keyword functions -@code{keywordp}, @code{keyword-of}, and @code{defkeyword}, -which are not defined by the new @dfn{CL} package because the -use of keywords as data is discouraged. - -The @code{build-klist} mechanism for parsing keyword arguments -is emulated by @code{cl-compat}; the @code{with-keyword-args} -macro is not, however, and in any case it's best to change to -use the more natural keyword argument processing offered by -@code{defun*}. - -Multiple return values are treated differently by the two -Common Lisp packages. The old package's method was more -compatible with true Common Lisp, though it used heuristics -that caused it to report spurious multiple return values in -certain cases. The @code{cl-compat} package defines a set -of multiple-value macros that are compatible with the old -CL package; again, they are heuristic in nature, but they -are guaranteed to work in any case where the old package's -macros worked. To avoid name collision with the ``official'' -multiple-value facilities, the ones in @code{cl-compat} have -capitalized names: @code{Values}, @code{Values-list}, -@code{Multiple-value-bind}, etc. - -The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate}, -and @code{cl-round} are defined by @code{cl-compat} to use the -old-style multiple-value mechanism, just as they did in the old -package. The newer @code{floor*} and friends return their two -results in a list rather than as multiple values. Note that -older versions of the old package used the unadorned names -@code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use -these names because they conflict with Emacs built-ins. - -@node Porting Common Lisp, GNU Free Documentation License, Old CL Compatibility, Top -@appendix Porting Common Lisp - -@noindent -This package is meant to be used as an extension to Emacs Lisp, -not as an Emacs implementation of true Common Lisp. Some of the -remaining differences between Emacs Lisp and Common Lisp make it -difficult to port large Common Lisp applications to Emacs. For -one, some of the features in this package are not fully compliant -with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there -are also quite a few features that this package does not provide -at all. Here are some major omissions that you will want to watch out -for when bringing Common Lisp code into Emacs. - -@itemize @bullet -@item -Case-insensitivity. Symbols in Common Lisp are case-insensitive -by default. Some programs refer to a function or variable as -@code{foo} in one place and @code{Foo} or @code{FOO} in another. -Emacs Lisp will treat these as three distinct symbols. - -Some Common Lisp code is written entirely in upper case. While Emacs -is happy to let the program's own functions and variables use -this convention, calls to Lisp builtins like @code{if} and -@code{defun} will have to be changed to lower case. - -@item -Lexical scoping. In Common Lisp, function arguments and @code{let} -bindings apply only to references physically within their bodies -(or within macro expansions in their bodies). Emacs Lisp, by -contrast, uses @dfn{dynamic scoping} wherein a binding to a -variable is visible even inside functions called from the body. - -Variables in Common Lisp can be made dynamically scoped by -declaring them @code{special} or using @code{defvar}. In Emacs -Lisp it is as if all variables were declared @code{special}. - -Often you can use code that was written for lexical scoping -even in a dynamically scoped Lisp, but not always. Here is -an example of a Common Lisp code fragment that would fail in -Emacs Lisp: - -@example -(defun map-odd-elements (func list) - (loop for x in list - for flag = t then (not flag) - collect (if flag x (funcall func x)))) - -(defun add-odd-elements (list x) - (map-odd-elements (lambda (a) (+ a x)) list)) -@end example - -@noindent -In Common Lisp, the two functions' usages of @code{x} are completely -independent. In Emacs Lisp, the binding to @code{x} made by -@code{add-odd-elements} will have been hidden by the binding -in @code{map-odd-elements} by the time the @code{(+ a x)} function -is called. - -(This package avoids such problems in its own mapping functions -by using names like @code{cl-x} instead of @code{x} internally; -as long as you don't use the @code{cl-} prefix for your own -variables no collision can occur.) - -@xref{Lexical Bindings}, for a description of the @code{lexical-let} -form which establishes a Common Lisp-style lexical binding, and some -examples of how it differs from Emacs's regular @code{let}. - -@item -Reader macros. Common Lisp includes a second type of macro that -works at the level of individual characters. For example, Common -Lisp implements the quote notation by a reader macro called @code{'}, -whereas Emacs Lisp's parser just treats quote as a special case. -Some Lisp packages use reader macros to create special syntaxes -for themselves, which the Emacs parser is incapable of reading. - -@item -Other syntactic features. Common Lisp provides a number of -notations beginning with @code{#} that the Emacs Lisp parser -won't understand. For example, @samp{#| ... |#} is an -alternate comment notation, and @samp{#+lucid (foo)} tells -the parser to ignore the @code{(foo)} except in Lucid Common -Lisp. - -@item -Packages. In Common Lisp, symbols are divided into @dfn{packages}. -Symbols that are Lisp built-ins are typically stored in one package; -symbols that are vendor extensions are put in another, and each -application program would have a package for its own symbols. -Certain symbols are ``exported'' by a package and others are -internal; certain packages ``use'' or import the exported symbols -of other packages. To access symbols that would not normally be -visible due to this importing and exporting, Common Lisp provides -a syntax like @code{package:symbol} or @code{package::symbol}. - -Emacs Lisp has a single namespace for all interned symbols, and -then uses a naming convention of putting a prefix like @code{cl-} -in front of the name. Some Emacs packages adopt the Common Lisp-like -convention of using @code{cl:} or @code{cl::} as the prefix. -However, the Emacs parser does not understand colons and just -treats them as part of the symbol name. Thus, while @code{mapcar} -and @code{lisp:mapcar} may refer to the same symbol in Common -Lisp, they are totally distinct in Emacs Lisp. Common Lisp -programs which refer to a symbol by the full name sometimes -and the short name other times will not port cleanly to Emacs. - -Emacs Lisp does have a concept of ``obarrays,'' which are -package-like collections of symbols, but this feature is not -strong enough to be used as a true package mechanism. - -@item -The @code{format} function is quite different between Common -Lisp and Emacs Lisp. It takes an additional ``destination'' -argument before the format string. A destination of @code{nil} -means to format to a string as in Emacs Lisp; a destination -of @code{t} means to write to the terminal (similar to -@code{message} in Emacs). Also, format control strings are -utterly different; @code{~} is used instead of @code{%} to -introduce format codes, and the set of available codes is -much richer. There are no notations like @code{\n} for -string literals; instead, @code{format} is used with the -``newline'' format code, @code{~%}. More advanced formatting -codes provide such features as paragraph filling, case -conversion, and even loops and conditionals. - -While it would have been possible to implement most of Common -Lisp @code{format} in this package (under the name @code{format*}, -of course), it was not deemed worthwhile. It would have required -a huge amount of code to implement even a decent subset of -@code{format*}, yet the functionality it would provide over -Emacs Lisp's @code{format} would rarely be useful. - -@item -Vector constants use square brackets in Emacs Lisp, but -@code{#(a b c)} notation in Common Lisp. To further complicate -matters, Emacs has its own @code{#(} notation for -something entirely different---strings with properties. - -@item -Characters are distinct from integers in Common Lisp. The notation -for character constants is also different: @code{#\A} in Common Lisp -where Emacs Lisp uses @code{?A}. Also, @code{string=} and -@code{string-equal} are synonyms in Emacs Lisp, whereas the latter is -case-insensitive in Common Lisp. - -@item -Data types. Some Common Lisp data types do not exist in Emacs -Lisp. Rational numbers and complex numbers are not present, -nor are large integers (all integers are ``fixnums''). All -arrays are one-dimensional. There are no readtables or pathnames; -streams are a set of existing data types rather than a new data -type of their own. Hash tables, random-states, structures, and -packages (obarrays) are built from Lisp vectors or lists rather -than being distinct types. - -@item -The Common Lisp Object System (CLOS) is not implemented, -nor is the Common Lisp Condition System. However, the EIEIO package -(@pxref{Top, , Introduction, eieio, EIEIO}) does implement some -CLOS functionality. - -@item -Common Lisp features that are completely redundant with Emacs -Lisp features of a different name generally have not been -implemented. For example, Common Lisp writes @code{defconstant} -where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list} -takes its arguments in different ways in the two Lisps but does -exactly the same thing, so this package has not bothered to -implement a Common Lisp-style @code{make-list}. - -@item -A few more notable Common Lisp features not included in this -package: @code{compiler-let}, @code{tagbody}, @code{prog}, -@code{ldb/dpb}, @code{parse-integer}, @code{cerror}. - -@item -Recursion. While recursion works in Emacs Lisp just like it -does in Common Lisp, various details of the Emacs Lisp system -and compiler make recursion much less efficient than it is in -most Lisps. Some schools of thought prefer to use recursion -in Lisp over other techniques; they would sum a list of -numbers using something like - -@example -(defun sum-list (list) - (if list - (+ (car list) (sum-list (cdr list))) - 0)) -@end example - -@noindent -where a more iteratively-minded programmer might write one of -these forms: - -@example -(let ((total 0)) (dolist (x my-list) (incf total x)) total) -(loop for x in my-list sum x) -@end example - -While this would be mainly a stylistic choice in most Common Lisps, -in Emacs Lisp you should be aware that the iterative forms are -much faster than recursion. Also, Lisp programmers will want to -note that the current Emacs Lisp compiler does not optimize tail -recursion. -@end itemize - -@node GNU Free Documentation License, Function Index, Porting Common Lisp, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index, Variable Index, GNU Free Documentation License, Top -@unnumbered Function Index - -@printindex fn - -@node Variable Index, , Function Index, Top -@unnumbered Variable Index - -@printindex vr - -@bye - diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi deleted file mode 100644 index 204afe7056e..00000000000 --- a/doc/misc/dbus.texi +++ /dev/null @@ -1,1852 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/dbus -@c %**start of header -@settitle Using of D-Bus -@c @setchapternewpage odd -@c %**end of header - -@syncodeindex vr cp -@syncodeindex fn cp - -@copying -Copyright @copyright{} 2007-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs lisp libraries -@direntry -* D-Bus: (dbus). Using D-Bus in Emacs. -@end direntry - -@contents - - -@node Top, Overview, (dir), (dir) -@top D-Bus integration in Emacs - -This manual documents an API for usage of D-Bus in Emacs. D-Bus is a -message bus system, a simple way for applications to talk to one -another. An overview of D-Bus can be found at -@uref{http://dbus.freedesktop.org/}. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: An overview of D-Bus. -* Inspection:: Inspection of D-Bus services. -* Type Conversion:: Mapping Lisp types and D-Bus types. -* Synchronous Methods:: Calling methods in a blocking way. -* Asynchronous Methods:: Calling methods non-blocking. -* Receiving Method Calls:: Offering own methods. -* Signals:: Sending and receiving signals. -* Alternative Buses:: Alternative buses. -* Errors and Events:: Errors and events. -* Index:: Index including concepts, functions, variables. - -* GNU Free Documentation License:: The license for this documentation. -@end menu - - -@node Overview -@chapter An overview of D-Bus -@cindex overview - -D-Bus is an inter-process communication mechanism for applications -residing on the same host. The communication is based on -@dfn{messages}. Data in the messages is carried in a structured way, -it is not just a byte stream. - -The communication is connection oriented to two kinds of message -buses: a so called @dfn{system bus}, and a @dfn{session bus}. On a -given machine, there is always one single system bus for miscellaneous -system-wide communication, like changing of hardware configuration. -On the other hand, the session bus is always related to a single -user's session. - -Every client application, which is connected to a bus, registers under -a @dfn{unique name} at the bus. This name is used for identifying the -client application. Such a unique name starts always with a colon, -and looks like @samp{:1.42}. - -Additionally, a client application can register itself to a so called -@dfn{known name}, which is a series of identifiers separated by dots, -as in @samp{org.gnu.Emacs}. If several applications register to the -same known name, these registrations are queued, and only the first -application which has registered for the known name is reachable via -this name. If this application disconnects from the bus, the next -queued unique name becomes the owner of this known name. - -An application can install one or several objects under its name. -Such objects are identified by an @dfn{object path}, which looks -similar to paths in a filesystem. An example of such an object path -could be @samp{/org/gnu/Emacs/}. - -Applications might send a request to an object, that means sending a -message with some data as input parameters, and receiving a message -from that object with the result of this message, the output -parameters. Such a request is called @dfn{method} in D-Bus. - -The other form of communication are @dfn{signals}. The underlying -message is emitted from an object and will be received by all other -applications which have registered for such a signal. - -All methods and signals an object supports are called @dfn{interface} -of the object. Interfaces are specified under a hierarchical name in -D-Bus; an object can support several interfaces. Such an interface -name could be @samp{org.gnu.Emacs.TextEditor} or -@samp{org.gnu.Emacs.FileManager}. - - -@node Inspection -@chapter Inspection of D-Bus services. -@cindex inspection - -@menu -* Bus names:: Discovering D-Bus names. -* Introspection:: Knowing the details of D-Bus services. -* Nodes and Interfaces:: Detecting object paths and interfaces. -* Methods and Signal:: Applying the functionality. -* Properties and Annotations:: What else to know about interfaces. -* Arguments and Signatures:: The final details. -@end menu - - -@node Bus names -@section Bus names. - -There are several basic functions which inspect the buses for -registered names. Internally they use the basic interface -@samp{org.freedesktop.DBus}, which is supported by all objects of a bus. - -@defun dbus-list-activatable-names &optional bus -This function returns the D-Bus service names, which can be activated -for @var{bus}. It must be either the symbol @code{:system} (the -default) or the symbol @code{:session}. An activatable service is -described in a service registration file. Under GNU/Linux, such files -are located at @file{/usr/share/dbus-1/system-services/} (for the -@code{:system} bus) or @file{/usr/share/dbus-1/services/}. An -activatable service is not necessarily registered at @var{bus} at already. - -The result is a list of strings, which is @code{nil} when there are no -activatable service names at all. Example: - -@lisp -;; Check, whether the document viewer can be accessed via D-Bus. -(member "org.gnome.evince.Daemon" - (dbus-list-activatable-names :session)) -@end lisp - -@end defun - -@defun dbus-list-names bus -All service names, which are registered at D-Bus @var{bus}, are -returned. The result is a list of strings, which is @code{nil} when -there are no registered service names at all. Well known names are -strings like @samp{org.freedesktop.DBus}. Names starting with -@samp{:} are unique names for services. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. -@end defun - -@defun dbus-list-known-names bus -Retrieves all registered services which correspond to a known name in @var{bus}. -A service has a known name if it doesn't start with @samp{:}. The -result is a list of strings, which is @code{nil} when there are no -known names at all. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. -@end defun - -@defun dbus-list-queued-owners bus service -For a given service, registered at D-Bus @var{bus} under the name -@var{service}, all queued unique names are returned. The result is a -list of strings, or @code{nil} when there are no queued names for -@var{service} at all. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. @var{service} must be a known service name as -string. -@end defun - -@defun dbus-get-name-owner bus service -For a given service, registered at D-Bus @var{bus} under the name -@var{service}, the unique name of the name owner is returned. The -result is a string, or @code{nil} when there exist no name owner of -@var{service}. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. @var{service} must be a known service name as -string. -@end defun - -@defun dbus-ping bus service &optional timeout -Check whether the service name @var{service} is registered at D-Bus -@var{bus}. @var{service} might not have been started yet, it is -autostarted if possible. The result is either @code{t} or @code{nil}. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. @var{service} must be a string. @var{timeout}, a -nonnegative integer, specifies the maximum number of milliseconds -@code{dbus-ping} must return. The default value is 25,000. Example: - -@lisp -(message - "%s screensaver on board." - (cond - ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome") - ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE") - (t "No"))) -@end lisp - -If it shall be checked whether @var{service} is already running -without autostarting it, one shall apply - -@lisp -(member service (dbus-list-known-names bus)) -@end lisp -@end defun - -@defun dbus-get-unique-name bus -The unique name, under which Emacs is registered at D-Bus @var{bus}, -is returned as string. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. -@end defun - - -@node Introspection -@section Knowing the details of D-Bus services. - -D-Bus services publish their interfaces. This can be retrieved and -analyzed during runtime, in order to understand the used -implementation. - -The resulting introspection data are in XML format. The root -introspection element is always a @code{node} element. It might have -a @code{name} attribute, which denotes the (absolute) object path an -interface is introspected. - -The root @code{node} element may have @code{node} and @code{interface} -children. A child @code{node} element must have a @code{name} -attribute, this case it is the relative object path to the root -@code{node} element. - -An @code{interface} element has just one attribute, @code{name}, which -is the full name of that interface. The default interface -@samp{org.freedesktop.DBus.Introspectable} is always present. Example: - -@example - - - @dots{} - - - @dots{} - - - @dots{} - - - @dots{} - - - - - - -@end example - -Children of an @code{interface} element can be @code{method}, -@code{signal} and @code{property} elements. A @code{method} element -stands for a D-Bus method of the surrounding interface. The element -itself has a @code{name} attribute, showing the method name. Children -elements @code{arg} stand for the arguments of a method. Example: - -@example - - - - - - - - - - - - - -@end example - -@code{arg} elements can have the attributes @code{name}, @code{type} -and @code{direction}. The @code{name} attribute is optional. The -@code{type} attribute stands for the @dfn{signature} of the argument -in D-Bus. For a discussion of D-Bus types and their Lisp -representation see @ref{Type Conversion}.@footnote{D-Bus signatures -are explained in the D-Bus specification -@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.} -The @code{direction} attribute of an @code{arg} element can be only -@samp{in} or @samp{out}; in case it is omitted, it defaults to -@samp{in}. - -A @code{signal} element of an @code{interface} has a similar -structure. The @code{direction} attribute of an @code{arg} child -element can be only @samp{out} here; which is also the default value. -Example: - -@example - - - - -@end example - -A @code{property} element has no @code{arg} child -element. It just has the attributes @code{name}, @code{type} and -@code{access}, which are all mandatory. The @code{access} attribute -allows the values @samp{readwrite}, @samp{read}, and @samp{write}. -Example: - -@example - -@end example - -@code{annotation} elements can be children of @code{interface}, -@code{method}, @code{signal}, and @code{property} elements. Unlike -properties, which can change their values during lifetime of a D-Bus -object, annotations are static. Often they are used for code -generators of D-Bus language bindings. Example: - -@example - -@end example - -Annotations have just @code{name} and @code{value} attributes, both -must be strings. - -@defun dbus-introspect bus service path -This function returns all interfaces and sub-nodes of @var{service}, -registered at object path @var{path} at bus @var{bus}. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. @var{service} must be a known service name, and -@var{path} must be a valid object path. The last two parameters are -strings. The result, the introspection data, is a string in XML -format. Example: - -@lisp -(dbus-introspect - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer") - -@result{} " - - - - - - @dots{} - - - - - - @dots{} - " -@end lisp - -This example informs us, that the service @samp{org.freedesktop.Hal} -at object path @samp{/org/freedesktop/Hal/devices/computer} offers the -interface @samp{org.freedesktop.Hal.Device} (and 2 other interfaces -not documented here). This interface contains the method -@samp{GetAllProperties}, which needs no input parameters, but returns -as output parameter an array of dictionary entries (key-value pairs). -Every dictionary entry has a string as key, and a variant as value. - -The interface offers also a signal, which returns 2 parameters: an -integer, and an array consisting of elements which are a struct of a -string and 2 boolean values.@footnote{ The interfaces of the service -@samp{org.freedesktop.Hal} are described at -@uref{http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces}.} -@end defun - -@defun dbus-introspect-xml bus service path -This function has the same intention as function -@code{dbus-introspect}. The returned value is a parsed XML tree, -which can be used for further analysis. Example: - -@lisp -(dbus-introspect-xml - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main") - -@result{} (node ((name . "/org/freedesktop/xesam/searcher/main")) - (interface ((name . "org.freedesktop.xesam.Search")) - (method ((name . "GetHitData")) - (arg ((name . "search") (type . "s") (direction . "in"))) - (arg ((name . "hit_ids") (type . "au") (direction . "in"))) - (arg ((name . "fields") (type . "as") (direction . "in"))) - (arg ((name . "hit_data") (type . "aav") (direction . "out"))) - ) - @dots{} - (signal ((name . "HitsAdded")) - (arg ((name . "search") (type . "s"))) - (arg ((name . "count") (type . "u"))) - ) - ) - @dots{} - ) -@end lisp -@end defun - -@defun dbus-introspect-get-attribute object attribute -It returns the @var{attribute} value of a D-Bus introspection -@var{object}. @var{object} can be every subtree of a parsed XML tree -as retrieved with @code{dbus-introspect-xml}. @var{attribute} must be -a string according to the attribute names in the D-Bus specification. -Example: - -@lisp -(dbus-introspect-get-attribute - (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends" - "/org/freedesktop/SystemToolsBackends/UsersConfig") - "name") - -@result{} "/org/freedesktop/SystemToolsBackends/UsersConfig" -@end lisp - -If @var{object} has no @var{attribute}, the function returns -@code{nil}. -@end defun - - -@node Nodes and Interfaces -@section Detecting object paths and interfaces. - -The first elements, to be introspected for a D-Bus object, are further -object paths and interfaces. - -@defun dbus-introspect-get-node-names bus service path -All node names of @var{service} in D-Bus @var{bus} at object path -@var{path} are returned as list of strings. Example: - -@lisp -(dbus-introspect-get-node-names - :session "org.gnome.seahorse" "/org/gnome/seahorse") - -@result{} ("crypto" "keys") -@end lisp - -The node names stand for further object paths of the D-Bus -@var{service}, relative to @var{path}. In the example, -@samp{/org/gnome/seahorse/crypto} and @samp{/org/gnome/seahorse/keys} -are also object paths of the D-Bus service @samp{org.gnome.seahorse}. -@end defun - -@defun dbus-introspect-get-all-nodes bus service path -This function returns all node names of @var{service} in D-Bus -@var{bus} at object path @var{path}. It returns a list of strings -with all object paths of @var{service}, starting at @var{path}. -Example: - -@lisp -(dbus-introspect-get-all-nodes :session "org.gnome.seahorse" "/") - -@result{} ("/" "/org" "/org/gnome" "/org/gnome/seahorse" - "/org/gnome/seahorse/crypto" - "/org/gnome/seahorse/keys" - "/org/gnome/seahorse/keys/openpgp" - "/org/gnome/seahorse/keys/openpgp/local" - "/org/gnome/seahorse/keys/openssh" - "/org/gnome/seahorse/keys/openssh/local") -@end lisp -@end defun - -@defun dbus-introspect-get-interface-names bus service path -There will be returned a list strings of all interface names of -@var{service} in D-Bus @var{bus} at object path @var{path}. This list -will contain the default interface @samp{org.freedesktop.DBus.Introspectable}. - -Another default interface is @samp{org.freedesktop.DBus.Properties}. -If present, @code{interface} elements can also have @code{property} -children. Example: - -@lisp -(dbus-introspect-get-interface-names - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer") - -@result{} ("org.freedesktop.DBus.Introspectable" - "org.freedesktop.Hal.Device" - "org.freedesktop.Hal.Device.SystemPowerManagement" - "org.freedesktop.Hal.Device.CPUFreq") -@end lisp -@end defun - -@defun dbus-introspect-get-interface bus service path interface -Return @var{interface} of @var{service} in D-Bus @var{bus} at object -path @var{path}. The return value is an XML element. @var{interface} -must be a string, element of the list returned by -@code{dbus-introspect-get-interface-names}. Example: - -@lisp -(dbus-introspect-get-interface - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search") - -@result{} (interface ((name . "org.freedesktop.xesam.Search")) - (method ((name . "GetHitData")) - (arg ((name . "search") (type . "s") (direction . "in"))) - (arg ((name . "hit_ids") (type . "au") (direction . "in"))) - (arg ((name . "fields") (type . "as") (direction . "in"))) - (arg ((name . "hit_data") (type . "aav") (direction . "out"))) - ) - @dots{} - (signal ((name . "HitsAdded")) - (arg ((name . "search") (type . "s"))) - (arg ((name . "count") (type . "u"))) - ) - ) -@end lisp -@end defun - -@noindent -With these functions, it is possible to retrieve all introspection -data from a running system: - -@lisp -(with-current-buffer (switch-to-buffer "*introspect*") - (erase-buffer) - (dolist (service (dbus-list-known-names :session)) - (dolist (path (dbus-introspect-get-all-nodes :session service "/")) - ;; We want to introspect only elements, which have more than - ;; the default interface "org.freedesktop.DBus.Introspectable". - (when (delete - "org.freedesktop.DBus.Introspectable" - (dbus-introspect-get-interface-names :session service path)) - (insert (message "\nservice: \"%s\" path: \"%s\"\n" service path) - (dbus-introspect :session service path)) - (redisplay t))))) -@end lisp - - -@node Methods and Signal -@section Applying the functionality. - -Methods and signals are the communication means to D-Bus. The -following functions return their specifications. - -@defun dbus-introspect-get-method-names bus service path interface -Return a list of strings of all method names of @var{interface} of -@var{service} in D-Bus @var{bus} at object path @var{path}. Example: - -@lisp -(dbus-introspect-get-method-names - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search") - -@result{} ("GetState" "StartSearch" "GetHitCount" "GetHits" "NewSession" - "CloseSession" "GetHitData" "SetProperty" "NewSearch" - "GetProperty" "CloseSearch") -@end lisp -@end defun - -@defun dbus-introspect-get-method bus service path interface method -This function returns @var{method} of @var{interface} as XML element. -It must be located at @var{service} in D-Bus @var{bus} at object path -@var{path}. @var{method} must be a string, element of the list -returned by @code{dbus-introspect-get-method-names}. Example: - -@lisp -(dbus-introspect-get-method - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "GetHitData") - -@result{} (method ((name . "GetHitData")) - (arg ((name . "search") (type . "s") (direction . "in"))) - (arg ((name . "hit_ids") (type . "au") (direction . "in"))) - (arg ((name . "fields") (type . "as") (direction . "in"))) - (arg ((name . "hit_data") (type . "aav") (direction . "out"))) - ) -@end lisp -@end defun - -@defun dbus-introspect-get-signal-names bus service path interface -Return a list of strings of all signal names of @var{interface} of -@var{service} in D-Bus @var{bus} at object path @var{path}. Example: - -@lisp -(dbus-introspect-get-signal-names - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search") - -@result{} ("StateChanged" "SearchDone" "HitsModified" - "HitsRemoved" "HitsAdded") -@end lisp -@end defun - -@defun dbus-introspect-get-signal bus service path interface signal -This function returns @var{signal} of @var{interface} as XML element. -It must be located at @var{service} in D-Bus @var{bus} at object path -@var{path}. @var{signal} must be a string, element of the list -returned by @code{dbus-introspect-get-signal-names}. Example: - -@lisp -(dbus-introspect-get-signal - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "HitsAdded") - -@result{} (signal ((name . "HitsAdded")) - (arg ((name . "search") (type . "s"))) - (arg ((name . "count") (type . "u"))) - ) -@end lisp -@end defun - - -@node Properties and Annotations -@section What else to know about interfaces. - -Interfaces can have properties. These can be exposed via the -@samp{org.freedesktop.DBus.Properties} interface@footnote{See -@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties}}. -That is, properties can be retrieved and changed during lifetime of an -element. - -Annotations, on the other hand, are static values for an element. -Often, they are used to instruct generators, how to generate code from -the interface for a given language binding. - -@defun dbus-introspect-get-property-names bus service path interface -Return a list of strings with all property names of @var{interface} of -@var{service} in D-Bus @var{bus} at object path @var{path}. Example: - -@lisp -(dbus-introspect-get-property-names - :session "org.kde.kded" "/modules/networkstatus" - "org.kde.Solid.Networking.Client") - -@result{} ("Status") -@end lisp - -If an interface declares properties, the corresponding element supports -also the @samp{org.freedesktop.DBus.Properties} interface. -@end defun - -@defun dbus-introspect-get-property bus service path interface property -This function returns @var{property} of @var{interface} as XML element. -It must be located at @var{service} in D-Bus @var{bus} at object path -@var{path}. @var{property} must be a string, element of the list -returned by @code{dbus-introspect-get-property-names}. - -A @var{property} value can be retrieved by the function -@code{dbus-introspect-get-attribute}. Example: - -@lisp -(dbus-introspect-get-property - :session "org.kde.kded" "/modules/networkstatus" - "org.kde.Solid.Networking.Client" "Status") - -@result{} (property ((access . "read") (type . "u") (name . "Status"))) - -(dbus-introspect-get-attribute - (dbus-introspect-get-property - :session "org.kde.kded" "/modules/networkstatus" - "org.kde.Solid.Networking.Client" "Status") - "access") - -@result{} "read" -@end lisp -@end defun - -@defun dbus-get-property bus service path interface property -This function returns the value of @var{property} of @var{interface}. -It will be checked at @var{bus}, @var{service}, @var{path}. The -result can be any valid D-Bus value, or @code{nil} if there is no -@var{property}. Example: - -@lisp -(dbus-get-property - :session "org.kde.kded" "/modules/networkstatus" - "org.kde.Solid.Networking.Client" "Status") - -@result{} 4 -@end lisp -@end defun - -@defun dbus-set-property bus service path interface property value -Set value of @var{property} of @var{interface} to @var{value}. It -will be checked at @var{bus}, @var{service}, @var{path}. When the -value has been set successful, the result is @var{value}. Otherwise, -@code{nil} is returned. Example: - -@lisp -(dbus-set-property - :session "org.kde.kaccess" "/MainApplication" - "com.trolltech.Qt.QApplication" "doubleClickInterval" 500) - -@result{} 500 -@end lisp -@end defun - -@defun dbus-get-all-properties bus service path interface -This function returns all properties of @var{interface}. It will be -checked at @var{bus}, @var{service}, @var{path}. The result is a list -of cons. Every cons contains the name of the property, and its value. -If there are no properties, @code{nil} is returned. Example: - -@lisp -(dbus-get-all-properties - :session "org.kde.kaccess" "/MainApplication" - "com.trolltech.Qt.QApplication") - -@result{} (("cursorFlashTime" . 1000) ("doubleClickInterval" . 500) - ("keyboardInputInterval" . 400) ("wheelScrollLines" . 3) - ("globalStrut" 0 0) ("startDragTime" . 500) - ("startDragDistance" . 4) ("quitOnLastWindowClosed" . t) - ("styleSheet" . "")) -@end lisp -@end defun - -@defun dbus-introspect-get-annotation-names bus service path interface &optional name -Return a list of all annotation names as list of strings. If -@var{name} is @code{nil}, the annotations are children of -@var{interface}, otherwise @var{name} must be a @code{method}, -@code{signal}, or @code{property} XML element, where the annotations -belong to. Example: - -@lisp -(dbus-introspect-get-annotation-names - :session "de.berlios.Pinot" "/de/berlios/Pinot" - "de.berlios.Pinot" "GetStatistics") - -@result{} ("de.berlios.Pinot.GetStatistics") -@end lisp - -Default annotation names@footnote{See -@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format}} -are - -@table @samp -@item org.freedesktop.DBus.Deprecated -Whether or not the entity is deprecated; defaults to @code{nil} - -@item org.freedesktop.DBus.GLib.CSymbol -The C symbol; may be used for @code{methods} and @code{interfaces} - -@item org.freedesktop.DBus.Method.NoReply -If set, don't expect a reply to the @code{method} call; defaults to @code{nil} -@end table -@end defun - -@defun dbus-introspect-get-annotation bus service path interface name annotation -Return annotation @var{ANNOTATION} as XML object. If @var{name} is -@code{nil}, @var{ANNOTATION} is a child of @var{interface}, otherwise -@var{name} must be the name of a @code{method}, @code{signal}, or -@code{property} XML element, where the @var{ANNOTATION} belongs to. - -An attribute value can be retrieved by -@code{dbus-introspect-get-attribute}. Example: - -@lisp -(dbus-introspect-get-annotation - :session "de.berlios.Pinot" "/de/berlios/Pinot" - "de.berlios.Pinot" "GetStatistics" - "de.berlios.Pinot.GetStatistics") - -@result{} (annotation ((name . "de.berlios.Pinot.GetStatistics") - (value . "pinotDBus"))) - -(dbus-introspect-get-attribute - (dbus-introspect-get-annotation - :session "de.berlios.Pinot" "/de/berlios/Pinot" - "de.berlios.Pinot" "GetStatistics" - "de.berlios.Pinot.GetStatistics") - "value") - -@result{} "pinotDBus" -@end lisp -@end defun - - -@node Arguments and Signatures -@section The final details. - -Methods and signals have arguments. They are described in the -@code{arg} XML elements. - -@defun dbus-introspect-get-argument-names bus service path interface name -Return a list of all argument names as list of strings. @var{name} -must be a @code{method} or @code{signal} XML element. Example: - -@lisp -(dbus-introspect-get-argument-names - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "GetHitData") - -@result{} ("search" "hit_ids" "fields" "hit_data") -@end lisp - -Argument names are optional; the function can return @code{nil} -therefore, even if the method or signal has arguments. -@end defun - -@defun dbus-introspect-get-argument bus service path interface name arg -Return argument @var{ARG} as XML object. @var{name} -must be a @code{method} or @code{signal} XML element. Example: - -@lisp -(dbus-introspect-get-argument - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "GetHitData" "search") - -@result{} (arg ((name . "search") (type . "s") (direction . "in"))) -@end lisp -@end defun - -@defun dbus-introspect-get-signature bus service path interface name &optional direction -Return signature of a @code{method} or @code{signal}, represented by -@var{name}, as string. - -If @var{name} is a @code{method}, @var{direction} can be either -@samp{in} or @samp{out}. If @var{direction} is @code{nil}, @samp{in} -is assumed. - -If @var{name} is a @code{signal}, and @var{direction} is -non-@code{nil}, @var{direction} must be @samp{out}. Example: - -@lisp -(dbus-introspect-get-signature - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "GetHitData" "in") - -@result{} "sauas" - -(dbus-introspect-get-signature - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "HitsAdded") - -@result{} "su" -@end lisp -@end defun - - -@node Type Conversion -@chapter Mapping Lisp types and D-Bus types. -@cindex type conversion - -D-Bus method calls and signals accept usually several arguments as -parameters, either as input parameter, or as output parameter. Every -argument belongs to a D-Bus type. - -Such arguments must be mapped between the value encoded as a D-Bus -type, and the corresponding type of Lisp objects. The mapping is -applied Lisp object @expansion{} D-Bus type for input parameters, and -D-Bus type @expansion{} Lisp object for output parameters. - - -@section Input parameters. - -Input parameters for D-Bus methods and signals occur as arguments of a -Lisp function call. The following mapping to D-Bus types is -applied, when the corresponding D-Bus message is created: - -@example -@multitable {negative integer} {@expansion{}} {DBUS_TYPE_BOOLEAN} -@item Lisp type @tab @tab D-Bus type -@item -@item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN -@item natural number @tab @expansion{} @tab DBUS_TYPE_UINT32 -@item negative integer @tab @expansion{} @tab DBUS_TYPE_INT32 -@item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE -@item string @tab @expansion{} @tab DBUS_TYPE_STRING -@item list @tab @expansion{} @tab DBUS_TYPE_ARRAY -@end multitable -@end example - -Other Lisp objects, like symbols or hash tables, are not accepted as -input parameters. - -If it is necessary to use another D-Bus type, a corresponding type -symbol can be prepended to the corresponding Lisp object. Basic D-Bus -types are represented by the type symbols @code{:byte}, -@code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32}, -@code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double}, -@code{:string}, @code{:object-path}, @code{:signature} and -@code{:unix-fd}. - -@noindent -Example: - -@lisp -(dbus-call-method @dots{} @var{NAT-NUMBER} @var{STRING}) -@end lisp - -is equivalent to - -@lisp -(dbus-call-method @dots{} :uint32 @var{NAT-NUMBER} :string @var{STRING}) -@end lisp - -but different to - -@lisp -(dbus-call-method @dots{} :int32 @var{NAT-NUMBER} :signature @var{STRING}) -@end lisp - -The value for a byte D-Bus type can be any integer in the range 0 -through 255. If a character is used as argument, modifiers -represented outside this range are stripped of. For example, -@code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to -@code{:byte ?\C-x} or @code{:byte ?\M-\C-x}. - -A D-Bus compound type is always represented as a list. The @sc{car} -of this list can be the type symbol @code{:array}, @code{:variant}, -@code{:struct} or @code{:dict-entry}, which would result in a -corresponding D-Bus container. @code{:array} is optional, because -this is the default compound D-Bus type for a list. - -The objects being elements of the list are checked according to the -D-Bus compound type rules. - -@itemize -@item An array must contain only elements of the same D-Bus type. It -can be empty. - -@item A variant must contain only one single element. - -@item A dictionary entry must be element of an array, and it must -contain only a key-value pair of two elements, with a basic D-Bus type -key. - -@item There is no restriction for structs. -@end itemize - -If an empty array needs an element D-Bus type other than string, it -can contain exactly one element of D-Bus type @code{:signature}. The -value of this element (a string) is used as the signature of the -elements of this array. Example: - -@lisp -(dbus-call-method - :session "org.freedesktop.Notifications" - "/org/freedesktop/Notifications" - "org.freedesktop.Notifications" "Notify" - "GNU Emacs" ;; Application name. - 0 ;; No replacement of other notifications. - "" ;; No icon. - "Notification summary" ;; Summary. - (format ;; Body. - "This is a test notification, raised from %s" (emacs-version)) - '(:array) ;; No actions (empty array of strings). - '(:array :signature "@{sv@}") ;; No hints - ;; (empty array of dictionary entries). - :int32 -1) ;; Default timeout. - -@result{} 3 -@end lisp - -@defun dbus-string-to-byte-array string -Sometimes, D-Bus methods require as input parameter an array of bytes, -instead of a string. If it is guaranteed, that @var{string} is an -UTF8 string, this function performs the conversion. Example: - -@lisp -(dbus-string-to-byte-array "/etc/hosts") - -@result{} (:array :byte 47 :byte 101 :byte 116 :byte 99 :byte 47 - :byte 104 :byte 111 :byte 115 :byte 116 :byte 115) -@end lisp -@end defun - -@defun dbus-escape-as-identifier string -Escape an arbitrary @var{string} so it follows the rules for a C -identifier. The escaped string can be used as object path component, -interface element component, bus name component or member name in -D-Bus. - -The escaping consists of replacing all non-alphanumerics, and the -first character if it's a digit, with an underscore and two -lower-case hex digits. As a special case, "" is escaped to -"_". Example: - -@lisp -(dbus-escape-as-identifier "0123abc_xyz\x01\xff") - -@result{} "_30123abc_5fxyz_01_ff" -@end lisp -@end defun - - -@section Output parameters. - -Output parameters of D-Bus methods and signals are mapped to Lisp -objects. - -@example -@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {natural number or float} -@item D-Bus type @tab @tab Lisp type -@item -@item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil} -@item DBUS_TYPE_BYTE @tab @expansion{} @tab natural number -@item DBUS_TYPE_UINT16 @tab @expansion{} @tab natural number -@item DBUS_TYPE_INT16 @tab @expansion{} @tab integer -@item DBUS_TYPE_UINT32 @tab @expansion{} @tab natural number or float -@item DBUS_TYPE_UNIX_FD @tab @expansion{} @tab natural number or float -@item DBUS_TYPE_INT32 @tab @expansion{} @tab integer or float -@item DBUS_TYPE_UINT64 @tab @expansion{} @tab natural number or float -@item DBUS_TYPE_INT64 @tab @expansion{} @tab integer or float -@item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float -@item DBUS_TYPE_STRING @tab @expansion{} @tab string -@item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string -@item DBUS_TYPE_SIGNATURE @tab @expansion{} @tab string -@item DBUS_TYPE_ARRAY @tab @expansion{} @tab list -@item DBUS_TYPE_VARIANT @tab @expansion{} @tab list -@item DBUS_TYPE_STRUCT @tab @expansion{} @tab list -@item DBUS_TYPE_DICT_ENTRY @tab @expansion{} @tab list -@end multitable -@end example - -A float object in case of @code{DBUS_TYPE_UINT32}, -@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64}, -@code{DBUS_TYPE_INT64} and @code{DBUS_TYPE_UNIX_FD} is returned, when -the C value exceeds the Emacs number size range. - -The resulting list of the last 4 D-Bus compound types contains as -elements the elements of the D-Bus container, mapped according to the -same rules. - -The signal @code{PropertyModified}, discussed as example in -@ref{Inspection}, would offer as Lisp data the following object -(@var{BOOL} stands here for either @code{nil} or @code{t}): - -@lisp -(@var{INTEGER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{})) -@end lisp - -@defun dbus-byte-array-to-string byte-array -If a D-Bus method or signal returns an array of bytes, which are known -to represent an UTF8 string, this function converts @var{byte-array} -to the corresponding string. Example: - -@lisp -(dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115)) - -@result{} "/etc/hosts" -@end lisp -@end defun - -@defun dbus-unescape-from-identifier string -Retrieve the original string from the encoded @var{string}. -@var{string} must have been coded with -@code{dbus-escape-as-identifier}. Example: - -@lisp -(dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff") - -@ifinfo -@result{} "0123abc_xyz^Aÿ" -@end ifinfo -@ifnotinfo -@result{} "0123abc_xyz^A@"y" -@end ifnotinfo -@end lisp -@end defun - - -@node Synchronous Methods -@chapter Calling methods in a blocking way. -@cindex method calls, synchronous -@cindex synchronous method calls - -Methods can be called synchronously (@dfn{blocking}) or asynchronously -(@dfn{non-blocking}). - -At D-Bus level, a method call consist of two messages: one message -which carries the input parameters to the object owning the method to -be called, and a reply message returning the resulting output -parameters from the object. - -@defun dbus-call-method bus service path interface method &optional :timeout timeout &rest args -This function calls @var{method} on the D-Bus @var{bus}. @var{bus} is -either the symbol @code{:system} or the symbol @code{:session}. - -@var{service} is the D-Bus service name to be used. @var{path} is the -D-Bus object path, @var{service} is registered at. @var{interface} is -an interface offered by @var{service}. It must provide @var{method}. - -If the parameter @code{:timeout} is given, the following integer -@var{timeout} specifies the maximum number of milliseconds the method -call must return. The default value is 25,000. If the method call -doesn't return in time, a D-Bus error is raised (@pxref{Errors and -Events}). - -All other arguments args are passed to @var{method} as arguments. -They are converted into D-Bus types as described in @ref{Type -Conversion}. - -The function returns the resulting values of @var{method} as a list of -Lisp objects, according to the type conversion rules described in -@ref{Type Conversion}. Example: - -@lisp -(dbus-call-method - :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp" - "org.gnome.seahorse.Keys" "GetKeyField" - "openpgp:657984B8C7A966DD" "simple-name") - -@result{} (t ("Philip R. Zimmermann")) -@end lisp - -If the result of the method call is just one value, the converted Lisp -object is returned instead of a list containing this single Lisp -object. Example: - -@lisp -(dbus-call-method - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer" - "org.freedesktop.Hal.Device" "GetPropertyString" - "system.kernel.machine") - -@result{} "i686" -@end lisp - -With the @code{dbus-introspect} function it is possible to explore the -interfaces of @samp{org.freedesktop.Hal} service. It offers the -interfaces @samp{org.freedesktop.Hal.Manager} for the object at the -path @samp{/org/freedesktop/Hal/Manager} as well as the interface -@samp{org.freedesktop.Hal.Device} for all objects prefixed with the -path @samp{/org/freedesktop/Hal/devices}. With the methods -@samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to -emulate the @code{lshal} command on GNU/Linux systems: - -@lisp -(dolist (device - (dbus-call-method - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/Manager" - "org.freedesktop.Hal.Manager" "GetAllDevices")) - (message "\nudi = %s" device) - (dolist (properties - (dbus-call-method - :system "org.freedesktop.Hal" device - "org.freedesktop.Hal.Device" "GetAllProperties")) - (message " %s = %S" - (car properties) (or (caar (cdr properties)) "")))) - -@print{} "udi = /org/freedesktop/Hal/devices/computer - info.addons = (\"hald-addon-acpi\") - info.bus = \"unknown\" - info.product = \"Computer\" - info.subsystem = \"unknown\" - info.udi = \"/org/freedesktop/Hal/devices/computer\" - linux.sysfs_path_device = \"(none)\" - power_management.acpi.linux.version = \"20051216\" - power_management.can_suspend_to_disk = t - power_management.can_suspend_to_ram = \"\" - power_management.type = \"acpi\" - smbios.bios.release_date = \"11/07/2001\" - system.chassis.manufacturer = \"COMPAL\" - system.chassis.type = \"Notebook\" - system.firmware.release_date = \"03/19/2005\" - @dots{}" -@end lisp -@end defun - -@defun dbus-call-method-non-blocking bus service path interface method &optional :timeout timeout &rest args -Call @var{method} on the D-Bus @var{bus}, but don't block the event queue. -This is necessary for communicating to registered D-Bus methods, -which are running in the same Emacs process. - -The arguments are the same as in @code{dbus-call-method}. Example: - -@lisp -(dbus-call-method-non-blocking - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer" - "org.freedesktop.Hal.Device" "GetPropertyString" - "system.kernel.machine") - -@result{} "i686" -@end lisp -@end defun - - -@node Asynchronous Methods -@chapter Calling methods non-blocking. -@cindex method calls, asynchronous -@cindex asynchronous method calls - -@defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout &rest args -This function calls @var{method} on the D-Bus @var{bus} -asynchronously. @var{bus} is either the symbol @code{:system} or the -symbol @code{:session}. - -@var{service} is the D-Bus service name to be used. @var{path} is the -D-Bus object path, @var{service} is registered at. @var{interface} is -an interface offered by @var{service}. It must provide @var{method}. - -@var{handler} is a Lisp function, which is called when the -corresponding return message has arrived. If @var{handler} is -@code{nil}, no return message will be expected. - -If the parameter @code{:timeout} is given, the following integer -@var{timeout} specifies the maximum number of milliseconds a reply -message must arrive. The default value is 25,000. If there is no -reply message in time, a D-Bus error is raised (@pxref{Errors and -Events}). - -All other arguments args are passed to @var{method} as arguments. -They are converted into D-Bus types as described in @ref{Type -Conversion}. - -Unless @var{handler} is @code{nil}, the function returns a key into -the hash table @code{dbus-registered-objects-table}. The -corresponding entry in the hash table is removed, when the return -message has been arrived, and @var{handler} is called. Example: - -@lisp -(dbus-call-method-asynchronously - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer" - "org.freedesktop.Hal.Device" "GetPropertyString" 'message - "system.kernel.machine") - -@result{} (:system 2) - -@print{} i686 -@end lisp -@end defun - - -@node Receiving Method Calls -@chapter Offering own methods. -@cindex method calls, returning -@cindex returning method calls - -In order to register methods on the D-Bus, Emacs has to request a well -known name on the D-Bus under which it will be available for other -clients. Names on the D-Bus can be registered and unregistered using -the following functions: - -@defun dbus-register-service bus service &rest flags -Register the known name @var{service} on D-Bus @var{bus}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the service name to be registered on the D-Bus. It -must be a known name. - -@var{flags} is a subset of the following keywords: - -@itemize -@item @code{:allow-replacement}: Allow another service to become the primary -owner if requested. - -@item @code{:replace-existing}: Request to replace the current primary owner. - -@item @code{:do-not-queue}: If we can not become the primary owner do not -place us in the queue. -@end itemize - -One of the following keywords is returned: - -@itemize - -@item @code{:primary-owner}: We have become the primary owner of the name -@var{service}. - -@item @code{:in-queue}: We could not become the primary owner and -have been placed in the queue. - -@item @code{:exists}: We already are in the queue. - -@item @code{:already-owner}: We already are the primary -owner. -@end itemize -@end defun - -@defun dbus-unregister-service bus service -Unregister all objects from D-Bus @var{bus}, registered by Emacs for -@var{service}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the D-Bus service name of the D-Bus. It must be a -known name. Emacs releases its association to @var{service} from -D-Bus. - -One of the following keywords is returned: - -@itemize -@item @code{:released}: We successfully released the name @var{service}. -@item @code{:non-existent}: The name @var{service} does not exist on the bus. -@item @code{:not-owner}: We are not an owner of the name @var{service}. -@end itemize -@end defun - -When a name has been chosen, Emacs can offer own methods, which can be -called by other applications. These methods could be an -implementation of an interface of a well known service, like -@samp{org.freedesktop.TextEditor}. - -It could be also an implementation of an own interface. In this case, -the service name must be @samp{org.gnu.Emacs}. The object path shall -begin with @samp{/org/gnu/Emacs/@strong{Application}/}, and the -interface name shall be @code{org.gnu.Emacs.@strong{Application}}. -@samp{@strong{Application}} is the name of the application which -provides the interface. - -@deffn Constant dbus-service-emacs -The well known service name of Emacs. -@end deffn - -@deffn Constant dbus-path-emacs -The object path head "/org/gnu/Emacs" used by Emacs. All object -paths, used by offered methods or signals, shall start with this -string. -@end deffn - -@defun dbus-register-method bus service path interface method handler dont-register-service -With this function, an application registers @var{method} on the D-Bus -@var{bus}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the D-Bus service name of the D-Bus object -@var{method} is registered for. It must be a known name (See -discussion of @var{dont-register-service} below). - -@var{path} is the D-Bus object path @var{service} is registered (See -discussion of @var{dont-register-service} below). - -@var{interface} is the interface offered by @var{service}. It must -provide @var{method}. - -@var{handler} is a Lisp function to be called when a @var{method} call -is received. It must accept as arguments the input arguments of -@var{method}. @var{handler} should return a list, whose elements are -to be used as arguments for the reply message of @var{method}. This -list can be composed like the input parameters in @ref{Type -Conversion}. - -If @var{handler} wants to return just one Lisp object and it is not a -cons cell, @var{handler} can return this object directly, instead of -returning a list containing the object. - -In case @var{handler} shall return a reply message with an empty -argument list, @var{handler} must return the symbol @code{:ignore}. - -When @var{dont-register-service} is non-@code{nil}, the known name -@var{service} is not registered. This means that other D-Bus clients -have no way of noticing the newly registered method. When interfaces -are constructed incrementally by adding single methods or properties -at a time, @var{dont-register-service} can be used to prevent other -clients from discovering the still incomplete interface. - -The default D-Bus timeout when waiting for a message reply is 25 -seconds. This value could be even smaller, depending on the calling -client. Therefore, @var{handler} shall not last longer than -absolutely necessary. - -@code{dbus-register-method} returns a Lisp object, which can be used -as argument in @code{dbus-unregister-object} for removing the -registration for @var{method}. Example: - -@lisp -(defun my-dbus-method-handler (filename) - (let (result) - (if (find-file filename) - (setq result '(:boolean t)) - (setq result '(:boolean nil))) - result)) - -@result{} my-dbus-method-handler - -(dbus-register-method - :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "OpenFile" - 'my-dbus-method-handler) - -@result{} ((:session "org.freedesktop.TextEditor" "OpenFile") - ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - my-dbus-method-handler)) -@end lisp - -If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile} -from another D-Bus application with a filename as parameter, the file -is opened in Emacs, and the method returns either @var{true} or -@var{false}, indicating the success of the method. As test tool one -could use the command line tool @code{dbus-send} in a shell: - -@example -# dbus-send --session --print-reply \ - --dest="org.freedesktop.TextEditor" \ - "/org/freedesktop/TextEditor" \ - "org.freedesktop.TextEditor.OpenFile" string:"/etc/hosts" - -@print{} method return sender=:1.22 -> dest=:1.23 reply_serial=2 - boolean true -@end example - -You can indicate an error by raising the Emacs signal -@code{dbus-error}. The handler above could be changed like this: - -@lisp -(defun my-dbus-method-handler (&rest args) - (unless (and (= (length args) 1) (stringp (car args))) - (signal 'dbus-error (list (format "Wrong argument list: %S" args)))) - (condition-case err - (find-file (car args)) - (error (signal 'dbus-error (cdr err)))) - t) - -@result{} my-dbus-method-handler -@end lisp - -The test runs then - -@example -# dbus-send --session --print-reply \ - --dest="org.freedesktop.TextEditor" \ - "/org/freedesktop/TextEditor" \ - "org.freedesktop.TextEditor.OpenFile" \ - string:"/etc/hosts" string:"/etc/passwd" - -@print{} Error org.freedesktop.DBus.Error.Failed: - Wrong argument list: ("/etc/hosts" "/etc/passwd") -@end example -@end defun - -@defun dbus-register-property bus service path interface property access value &optional emits-signal dont-register-service -With this function, an application declares a @var{property} on the D-Bus -@var{bus}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the D-Bus service name of the D-Bus. It must be a -known name. - -@var{path} is the D-Bus object path @var{service} is registered (See -discussion of @var{dont-register-service} below). - -@var{interface} is the name of the interface used at @var{path}, -@var{property} is the name of the property of @var{interface}. - -@var{access} indicates, whether the property can be changed by other -services via D-Bus. It must be either the symbol @code{:read} or -@code{:readwrite}. @var{value} is the initial value of the property, -it can be of any valid type (see @code{dbus-call-method} for details). - -If @var{property} already exists on @var{path}, it will be -overwritten. For properties with access type @code{:read} this is the -only way to change their values. Properties with access type -@code{:readwrite} can be changed by @code{dbus-set-property}. - -The interface @samp{org.freedesktop.DBus.Properties} is added to -@var{path}, including a default handler for the @samp{Get}, -@samp{GetAll} and @samp{Set} methods of this interface. When -@var{emits-signal} is non-@code{nil}, the signal -@samp{PropertiesChanged} is sent when the property is changed by -@code{dbus-set-property}. - -When @var{dont-register-service} is non-@code{nil}, the known name -@var{service} is not registered. This means that other D-Bus clients -have no way of noticing the newly registered method. When interfaces -are constructed incrementally by adding single methods or properties -at a time, @var{dont-register-service} can be used to prevent other -clients from discovering the still incomplete interface. - -@noindent Example: - -@lisp -(dbus-register-property - :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "name" :read "GNU Emacs") - -@result{} ((:session "org.freedesktop.TextEditor" "name") - ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor")) - -(dbus-register-property - :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "version" :readwrite emacs-version t) - -@result{} ((:session "org.freedesktop.TextEditor" "version") - ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor")) -@end lisp - -Other D-Bus applications can read the property via the default methods -@samp{org.freedesktop.DBus.Properties.Get} and -@samp{org.freedesktop.DBus.Properties.GetAll}. Testing is also -possible via the command line tool @code{dbus-send} in a shell: - -@example -# dbus-send --session --print-reply \ - --dest="org.freedesktop.TextEditor" \ - "/org/freedesktop/TextEditor" \ - "org.freedesktop.DBus.Properties.GetAll" \ - string:"org.freedesktop.TextEditor" - -@print{} method return sender=:1.22 -> dest=:1.23 reply_serial=3 - array [ - dict entry( - string "name" - variant string "GNU Emacs" - ) - dict entry( - string "version" - variant string "23.1.50.5" - ) - ] -@end example - -It is also possible, to apply the @code{dbus-get-property}, -@code{dbus-get-all-properties} and @code{dbus-set-property} functions -(@pxref{Properties and Annotations}). - -@lisp -(dbus-set-property - :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "version" "23.1.50") - -@result{} "23.1.50" - -(dbus-get-property - :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "version") - -@result{} "23.1.50" -@end lisp -@end defun - -@defun dbus-unregister-object object -Unregister @var{object} from the D-Bus. @var{object} must be the -result of a preceding @code{dbus-register-method}, -@code{dbus-register-property} or @code{dbus-register-signal} call -(@pxref{Signals}). It returns @code{t} if @var{object} has been -unregistered, @code{nil} otherwise. - -When @var{object} identifies the last method or property, which is -registered for the respective service, Emacs releases its association -to the service from D-Bus. -@end defun - - -@node Signals -@chapter Sending and receiving signals. -@cindex signals - -Signals are broadcast messages. They carry input parameters, which -are received by all objects which have registered for such a signal. - -@defun dbus-send-signal bus service path interface signal &rest args -This function is similar to @code{dbus-call-method}. The difference -is, that there are no returning output parameters. - -The function emits @var{signal} on the D-Bus @var{bus}. @var{bus} is -either the symbol @code{:system} or the symbol @code{:session}. It -doesn't matter whether another object has registered for @var{signal}. - -@var{service} is the D-Bus service name of the object the signal is -emitted from. @var{path} is the corresponding D-Bus object path, -@var{service} is registered at. @var{interface} is an interface -offered by @var{service}. It must provide @var{signal}. - -All other arguments args are passed to @var{signal} as arguments. -They are converted into D-Bus types as described in @ref{Type -Conversion}. Example: - -@lisp -(dbus-send-signal - :session dbus-service-emacs dbus-path-emacs - (concat dbus-service-emacs ".FileManager") "FileModified" - "/home/albinus/.emacs") -@end lisp -@end defun - -@defun dbus-register-signal bus service path interface signal handler &rest args -With this function, an application registers for @var{signal} on the -D-Bus @var{bus}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the D-Bus service name used by the sending D-Bus -object. It can be either a known name or the unique name of the D-Bus -object sending the signal. A known name will be mapped onto the -unique name of the object, owning @var{service} at registration time. -When the corresponding D-Bus object disappears, signals won't be -received any longer. - -When @var{service} is @code{nil}, related signals from all D-Bus -objects shall be accepted. - -@var{path} is the corresponding D-Bus object path, @var{service} is -registered at. It can also be @code{nil} if the path name of incoming -signals shall not be checked. - -@var{interface} is an interface offered by @var{service}. It must -provide @var{signal}. - -@var{handler} is a Lisp function to be called when the @var{signal} is -received. It must accept as arguments the output parameters -@var{signal} is sending. - -All other arguments @var{args}, if specified, must be strings. They -stand for the respective arguments of @var{signal} in their order, and -are used for filtering as well. A @code{nil} argument might be used -to preserve the order. - -@code{dbus-register-signal} returns a Lisp object, which can be used -as argument in @code{dbus-unregister-object} for removing the -registration for @var{signal}. Example: - -@lisp -(defun my-dbus-signal-handler (device) - (message "Device %s added" device)) - -@result{} my-dbus-signal-handler - -(dbus-register-signal - :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager" - "org.freedesktop.Hal.Manager" "DeviceAdded" - 'my-dbus-signal-handler) - -@result{} ((:system "org.freedesktop.Hal.Manager" "DeviceAdded") - ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager" - my-signal-handler)) -@end lisp - -As we know from the introspection data of interface -@samp{org.freedesktop.Hal.Manager}, the signal @samp{DeviceAdded} -provides one single parameter, which is mapped into a Lisp string. -The callback function @code{my-dbus-signal-handler} must define one -single string argument therefore. Plugging an USB device to your -machine, when registered for signal @samp{DeviceAdded}, will show you -which objects the GNU/Linux @code{hal} daemon adds. -@end defun - - -@node Alternative Buses -@chapter Alternative buses. -@cindex bus names -@cindex UNIX domain socket - -Until now, we have spoken about the system and the session buses, -which are the default buses to be connected to. However, it is -possible to connect to any bus, from which the address is known. This -is a UNIX domain socket. Everywhere, where a @var{bus} is mentioned -as argument of a function (the symbol @code{:system} or the symbol -@code{:session}), this address can be used instead. The connection to -this bus must be initialized first. - -@defun dbus-init-bus bus -Establish the connection to D-Bus @var{bus}. - -@var{bus} can be either the symbol @code{:system} or the symbol -@code{:session}, or it can be a string denoting the address of the -corresponding bus. For the system and session buses, this function -is called when loading @file{dbus.el}, there is no need to call it -again. - -Example: You open another session bus in a terminal window on your host: - -@example -# eval `dbus-launch --auto-syntax` -# echo $DBUS_SESSION_BUS_ADDRESS - -@print{} unix:abstract=/tmp/dbus-JoFtAVG92w,guid=2f320a1ebe50b7ef58e -@end example - -In Emacs, you can access to this bus via its address: - -@lisp -(setq my-bus - "unix:abstract=/tmp/dbus-JoFtAVG92w,guid=2f320a1ebe50b7ef58e") - -@result{} "unix:abstract=/tmp/dbus-JoFtAVG92w,guid=2f320a1ebe50b7ef58e" - -(dbus-init-bus my-bus) - -@result{} nil - -(dbus-get-unique-name my-bus) - -@result{} ":1.0" -@end lisp -@end defun - - -@node Errors and Events -@chapter Errors and events. -@cindex debugging -@cindex errors -@cindex events - -The internal actions can be traced by running in a debug mode. - -@defvar dbus-debug -If this variable is non-@code{nil}, D-Bus specific debug messages are raised. -@end defvar - -Input parameters of @code{dbus-call-method}, -@code{dbus-call-method-non-blocking}, -@code{dbus-call-method-asynchronously}, and -@code{dbus-register-signal} are checked for correct D-Bus types. If -there is a type mismatch, the Lisp error @code{wrong-type-argument} -@code{D-Bus ARG} is raised. - -All errors raised by D-Bus are signaled with the error symbol -@code{dbus-error}. If possible, error messages from D-Bus are -appended to the @code{dbus-error}. - -@defspec dbus-ignore-errors forms@dots{} -This executes @var{forms} exactly like a @code{progn}, except that -@code{dbus-error} errors are ignored during the @var{forms}. These -errors can be made visible when @code{dbus-debug} is set to @code{t}. -@end defspec - -Incoming D-Bus messages are handled as Emacs events, see @pxref{Misc -Events, , , elisp}. They are retrieved only, when Emacs runs in -interactive mode. The generated event has this form: - -@lisp -(dbus-event @var{bus} @var{type} @var{serial} @var{service} @var{path} @var{interface} @var{member} @var{handler} - &rest @var{args}) -@end lisp - -@var{bus} identifies the D-Bus the message is coming from. It is -either the symbol @code{:system} or the symbol @code{:session}. - -@var{type} is the D-Bus message type which has caused the event. It -can be @code{dbus-message-type-invalid}, -@code{dbus-message-type-method-call}, -@code{dbus-message-type-method-return}, -@code{dbus-message-type-error}, or @code{dbus-message-type-signal}. -@var{serial} is the serial number of the received D-Bus message. - -@var{service} and @var{path} are the unique name and the object path -of the D-Bus object emitting the message. @var{interface} and -@var{member} denote the message which has been sent. - -@var{handler} is the callback function which has been registered for -this message (see @pxref{Signals}). When a @code{dbus-event} event -arrives, @var{handler} is called with @var{args} as arguments. - -In order to inspect the @code{dbus-event} data, you could extend the -definition of the callback function in @ref{Signals}: - -@lisp -(defun my-dbus-signal-handler (&rest args) - (message "my-dbus-signal-handler: %S" last-input-event)) -@end lisp - -There exist convenience functions which could be called inside a -callback function in order to retrieve the information from the event. - -@defun dbus-event-bus-name event -Returns the bus name @var{event} is coming from. -The result is either the symbol @code{:system} or the symbol @code{:session}. -@end defun - -@defun dbus-event-message-type event -Returns the message type of the corresponding D-Bus message. The -result is a natural number. -@end defun - -@defun dbus-event-serial-number event -Returns the serial number of the corresponding D-Bus message. -The result is a natural number. -@end defun - -@defun dbus-event-service-name event -Returns the unique name of the D-Bus object @var{event} is coming from. -@end defun - -@defun dbus-event-path-name event -Returns the object path of the D-Bus object @var{event} is coming from. -@end defun - -@defun dbus-event-interface-name event -Returns the interface name of the D-Bus object @var{event} is coming from. -@end defun - -@defun dbus-event-member-name event -Returns the member name of the D-Bus object @var{event} is coming -from. It is either a signal name or a method name. -@end defun - -D-Bus errors are not propagated during event handling, because it is -usually not desired. D-Bus errors in events can be made visible by -setting the variable @code{dbus-debug} to @code{t}. They can also be -handled by a hook function. - -@defvar dbus-event-error-hooks -This hook variable keeps a list of functions, which are called when a -D-Bus error happens in the event handler. Every function must accept -two arguments, the event and the error variable caught in -@code{condition-case} by @code{dbus-error}. - -Such functions can be used the adapt the error signal to be raised. -Example: - -@lisp -(defun my-dbus-event-error-handler (event error) - (when (string-equal (concat dbus-service-emacs ".FileManager") - (dbus-event-interface-name event)) - (message "my-dbus-event-error-handler: %S %S" event error) - (signal 'file-error (cdr error)))) - -(add-hook 'dbus-event-error-hooks 'my-dbus-event-error-handler) -@end lisp -@end defvar - -Hook functions shall take into account, that there might be other -D-Bus applications running. Therefore, they shall check carefully, -whether a given D-Bus error is related to them. - - -@node Index -@unnumbered Index - -@printindex cp - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@bye diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi deleted file mode 100644 index 95c129f411d..00000000000 --- a/doc/misc/dired-x.texi +++ /dev/null @@ -1,1113 +0,0 @@ -\input texinfo @comment -*-texinfo-*- - -@c dired-x.texi --- Sebastian Kremer's Extra DIRED hacked up for GNU Emacs -@c -@c Author: Sebastian Kremer -@c Lawrence R. Dodd -@c [Dodd's address no longer valid.] - -@comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/dired-x -@settitle Dired Extra User's Manual - -@include emacsver.texi - -@iftex -@finalout -@end iftex -@c @setchapternewpage odd % For book style double sided manual. -@comment %**end of header (This is for running Texinfo on a region.) - -@copying -Copyright @copyright{} 1994-1995, 1999, 2001-2012 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Dired-X: (dired-x). Dired Extra Features. -@end direntry - -@c @smallbook -@tex -\overfullrule=0pt -%\global\baselineskip 30pt % For printing in double spaces -@end tex - -@titlepage -@sp 6 -@center @titlefont{Dired Extra} -@sp 2 -@center @titlefont{For The GNU Emacs} -@sp 1 -@center @titlefont{Directory Editor} -@sp 4 -@center Lawrence R@. Dodd -@c @center @t{dodd@@roebling.poly.edu} -@sp 5 -@center (Based on @file{dired.texi} by Sebastian Kremer ) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - - -@ifnottex - -@node Top -@top Dired Extra - -@noindent -This documents the ``extra'' features for GNU Emacs's Dired Mode that are -provided by the file @file{dired-x.el}. - -@itemize @bullet - -@item -Based on @file{dired.texi} by Sebastian Kremer - -@item -For @file{dired-x.el} as distributed with GNU Emacs @value{EMACSVER}. - -@end itemize - -@insertcopying - -@menu -* Introduction:: -* Installation:: -* Omitting Files in Dired:: -* Local Variables:: -* Shell Command Guessing:: -* Virtual Dired:: -* Advanced Mark Commands:: -* Multiple Dired Directories:: -* Find File At Point:: -* Miscellaneous Commands:: -* Bugs:: - -* GNU Free Documentation License:: -* Concept Index:: -* Command Index:: -* Key Index:: -* Variable Index:: - -@end menu - -@end ifnottex - -@node Introduction, Installation, Top, Top -@chapter Introduction - -This documents some @emph{extra} features for GNU Emacs's Dired Mode -that are provided by @file{dired-x.el} (derived from Sebastian Kremer's -original @file{dired-x.el}). - -@ifnottex -@menu -* Features:: -* Technical Details:: -@end menu -@end ifnottex - -@node Features, Technical Details, , Introduction -@section Features -@cindex Features - -Some features provided by Dired Extra: - -@enumerate -@item -Omitting uninteresting files from Dired listing -(@pxref{Omitting Files in Dired}). -@item -Guessing shell commands in Dired buffers -(@pxref{Shell Command Guessing}). -@item -Running Dired command in non-Dired buffers -(@pxref{Virtual Dired}). -@item -Finding a file mentioned in a buffer -(@pxref{Find File At Point}). -@item -Commands using file marking -(@pxref{Advanced Mark Commands}). -@end enumerate - -@noindent -@file{dired-x.el} binds some functions to keys in Dired Mode (@pxref{Key -Index}) and also binds @kbd{C-x C-j} and @kbd{C-x 4 C-j} @emph{globally} to -@code{dired-jump} (@pxref{Miscellaneous Commands}). Optionally, it -also binds @kbd{C-x C-f} and @kbd{C-x 4 C-f} to -@code{dired-x-find-file} and @code{dired-x-find-file-other-window}, -respectively (@pxref{Find File At Point}). - -@node Technical Details, , Features, Introduction -@section Technical Details -@cindex Modified functions -@cindex @file{dired-aux.el} - -When @file{dired-x.el} is loaded, some standard Dired functions from -@file{dired.el} and @file{dired-aux.el} offer additional features. -@code{dired-add-entry} obeys Dired Omit mode (@pxref{Omitting Files in -Dired}), if it is active. @code{dired-find-buffer-nocreate} and -@code{dired-initial-position} respect the value of -@code{dired-find-subdir} (@pxref{Miscellaneous Commands}). -@code{dired-clean-up-after-deletion} respects the value of -@code{dired-clean-up-buffers-too}. @code{dired-read-shell-command} uses -@code{dired-guess-shell-command} (@pxref{Shell Command Guessing}) to -offer a smarter default command. - -@node Installation, Omitting Files in Dired, Introduction, Top -@chapter Installation - -@noindent -This manual describes the Dired features provided by the file -@file{dired-x.el}. To take advantage of these features, you must load the -file and (optionally) set some variables. - -@noindent -In your @file{~/.emacs} file, or in the system-wide initialization file -@file{default.el} in the @file{site-lisp} directory, put - -@example -(add-hook 'dired-load-hook - (lambda () - (load "dired-x") - ;; Set dired-x global variables here. For example: - ;; (setq dired-guess-shell-gnutar "gtar") - ;; (setq dired-x-hands-off-my-keys nil) - )) -(add-hook 'dired-mode-hook - (lambda () - ;; Set dired-x buffer-local variables here. For example: - ;; (dired-omit-mode 1) - )) -@end example - -@noindent -This will load @file{dired-x.el} when Dired is first invoked (for example, -when you first type @kbd{C-x d}). - -@ifnottex -@menu -* Optional Installation Dired Jump:: -* Optional Installation File At Point:: -@end menu -@end ifnottex - -@node Optional Installation Dired Jump, Optional Installation File At Point, , Installation -@section Optional Installation Dired Jump - -@cindex Autoloading @code{dired-jump} and @code{dired-jump-other-window} - -In order to have @code{dired-jump} and @code{dired-jump-other-window} -(@pxref{Miscellaneous Commands}) work @emph{before} @code{dired} and -@code{dired-x} have been properly loaded you should set-up an autoload -for these functions. In your @file{.emacs} file put - -@example -(autoload 'dired-jump "dired-x" - "Jump to Dired buffer corresponding to current buffer." t) - -(autoload 'dired-jump-other-window "dired-x" - "Like \\[dired-jump] (dired-jump) but in other window." t) - -(define-key global-map "\C-x\C-j" 'dired-jump) -(define-key global-map "\C-x4\C-j" 'dired-jump-other-window) -@end example - -@node Optional Installation File At Point, , Optional Installation Dired Jump, Installation -@section Optional Installation File At Point - -@cindex Binding @code{dired-x-find-file} -If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over -@code{find-file} (@pxref{Find File At Point}), then you will need to set -@code{dired-x-hands-off-my-keys}. To do this, either set it -@emph{before} @file{dired-x.el} is loaded, or use @kbd{M-x customize-variable}, -or call @code{dired-x-bind-find-file} after changing the value. - -@example -(add-hook 'dired-load-hook - (lambda () - ;; Bind dired-x-find-file. - (setq dired-x-hands-off-my-keys nil) - (load "dired-x") - )) -@end example - -@node Omitting Files in Dired, Local Variables, Installation, Top -@chapter Omitting Files in Dired - -@cindex Omitting Files in Dired -@cindex Uninteresting files -@dfn{Omitting} a file means removing it from the directory listing. Omitting -is useful for keeping Dired buffers free of ``uninteresting'' files (for -instance, auto-save, auxiliary, backup, and revision control files) so that -the user can concentrate on the interesting files. Like hidden files, omitted -files are never seen by Dired. Omitting differs from hiding in several -respects: - -@itemize @bullet - -@item -Omitting works on individual files, not on directories; an entire directory -cannot be omitted (though each of its files could be). - -@item -Omitting is wholesale; if omitting is turned on for a Dired buffer, then all -uninteresting files listed in that buffer are omitted. The user does not omit -(or unomit) files one at a time. - -@item -Omitting can be automatic; uninteresting file lines in the buffer can be -removed before the user ever sees them. - -@item -Marked files are never omitted. -@end itemize - -@table @kbd -@item M-o -@kindex M-o -@findex dired-omit-mode -(@code{dired-omit-mode}) Toggle between displaying and omitting -``uninteresting'' files. -@item * O -@kindex * O -@findex dired-mark-omitted -(@code{dired-mark-omitted}) Mark ``uninteresting'' files. -@end table - -@noindent -In order to make Dired Omit work you first need to load @file{dired-x.el} -inside @code{dired-load-hook} (@pxref{Installation}) and then evaluate -@code{(dired-omit-mode 1)} in some way (@pxref{Omitting Variables}). - -@ifnottex -@menu -* Omitting Variables:: -* Omitting Examples:: -* Omitting Technical:: -@end menu -@end ifnottex - -@node Omitting Variables, Omitting Examples, , Omitting Files in Dired -@section Omitting Variables - -@cindex Customizing file omitting -The following variables can be used to customize omitting. - -@table @code - -@vindex dired-omit-mode -@item dired-omit-mode - -Default: @code{nil} - -@cindex How to make omitting the default in Dired -If non-@code{nil}, ``uninteresting'' files are not listed. -Uninteresting files are those whose files whose names match regexp -@code{dired-omit-files}, plus those ending with extensions in -@code{dired-omit-extensions}. @kbd{M-o} (@code{dired-omit-mode}) -toggles its value, which is buffer-local. Put - -@example -(dired-omit-mode 1) -@end example - -@noindent -inside your @code{dired-mode-hook} to have omitting initially turned on in -@emph{every} Dired buffer (@pxref{Installation}). You can then use @kbd{M-o} to -unomit in that buffer. - -To enable omitting automatically only in certain directories you can add -a directory local setting -(@pxref{Directory Variables,,,emacs,The Gnu Emacs manual}) for Dired mode - -@example -((dired-mode . ((dired-omit-mode . t)))) -@end example - -@noindent -to a @file{.dir-locals.el} file in that directory. You can use the -command @code{add-dir-local-variable} to do this. - -@vindex dired-omit-files -@item dired-omit-files - -Default: @code{"^#\\|\\.$"} - -Files whose names match this buffer-local regexp will not be displayed. -This only has effect when @code{dired-omit-mode}'s value is @code{t}. - -The default value omits the special directories @file{.} and @file{..} and -autosave files (plus other files ending in @file{.}) (@pxref{Omitting Examples}). - -@vindex dired-omit-extensions -@item dired-omit-extensions - -Default: The elements of @code{completion-ignored-extensions}, -@code{dired-latex-unclean-extensions}, @code{dired-bibtex-unclean-extensions} -and @code{dired-texinfo-unclean-extensions}. - -If non-@code{nil}, a list of extensions (strings) to omit from Dired listings. -Its format is the same as that of @code{completion-ignored-extensions}. - -@vindex dired-omit-localp -@item dired-omit-localp - -Default: @code{no-dir} - -The @var{localp} argument @code{dired-omit-expunge} passes to -@code{dired-get-filename}. If it is @code{no-dir}, omitting is much faster, -but you can only match against the non-directory part of the file name. Set it -to @code{nil} if you need to match the whole file name or @code{t} to match the -file name relative to the buffer's top-level directory. - -@item dired-omit-marker-char -@vindex dired-omit-marker-char -@cindex Omitting additional files -Default: @kbd{C-o} - -Temporary marker used by Dired to implement omitting. Should never be used -as marker by the user or other packages. There is one exception to this rule: -by adding - -@example -(setq dired-mark-keys "\C-o") -;; i.e., the value of dired-omit-marker-char -;; (which is not defined yet) -@end example - -@noindent -to your @file{~/.emacs}, you can bind the @kbd{C-o} key to insert a -@kbd{C-o} marker, thus causing these files to be omitted in addition to the -usually omitted files. Unfortunately the files you omitted manually this way -will show up again after reverting the buffer, unlike the others. - -@end table - -@node Omitting Examples, Omitting Technical, Omitting Variables, Omitting Files in Dired -@section Examples of Omitting Various File Types - -@itemize @bullet - -@item -@cindex RCS files, how to omit them in Dired -@cindex Omitting RCS files in Dired -If you wish to avoid seeing RCS files and the @file{RCS} directory, then put - -@example -(setq dired-omit-files - (concat dired-omit-files "\\|^RCS$\\|,v$")) -@end example - -@noindent -in the @code{dired-load-hook} (@pxref{Installation}). This assumes -@code{dired-omit-localp} has its default value of @code{no-dir} to make the -@code{^}-anchored matches work. As a slower alternative, with -@code{dired-omit-localp} set to @code{nil}, you can use @code{/} instead of -@code{^} in the regexp. - -@item -@cindex Tib files, how to omit them in Dired -@cindex Omitting tib files in Dired -If you use @code{tib}, the bibliography program for use with @TeX{} and -La@TeX{}, and you -want to omit the @file{INDEX} and the @file{*-t.tex} files, then put - -@example -(setq dired-omit-files - (concat dired-omit-files "\\|^INDEX$\\|-t\\.tex$")) -@end example - -@noindent -in the @code{dired-load-hook} (@pxref{Installation}). - -@item -@cindex Dot files, how to omit them in Dired -@cindex Omitting dot files in Dired -If you do not wish to see @samp{dot} files (files starting with a @file{.}), -then put - -@example -(setq dired-omit-files - (concat dired-omit-files "\\|^\\..+$")) -@end example - -@noindent -in the @code{dired-load-hook} (@pxref{Installation}). (Of course, a -better way to achieve this particular goal is simply to omit @samp{-a} from -@code{dired-listing-switches}.) - -@end itemize - -@node Omitting Technical, , Omitting Examples, Omitting Files in Dired -@section Some Technical Details of Omitting - -Loading @file{dired-x.el} will install Dired Omit by putting -@code{dired-omit-expunge} on your @code{dired-after-readin-hook}, and will -call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup} -in your @code{dired-mode-hook}. - -@node Local Variables, Shell Command Guessing, Omitting Files in Dired, Top -@chapter Local Variables for Dired Directories - -@cindex Local Variables for Dired Directories -@vindex dired-local-variables-file -@vindex dired-enable-local-variables -@noindent -This Dired-X feature is obsolete as of Emacs 24.1. The standard Emacs -directory local variables mechanism (@pxref{Directory -Variables,,,emacs,The Gnu Emacs manual}) replaces it. For an example of -the new mechanisms, @pxref{Omitting Variables}. - -When Dired visits a directory, it looks for a file whose name is the -value of variable @code{dired-local-variables-file} (default: @file{.dired}). -If such a file is found, Dired will temporarily insert it into the Dired -buffer and run @code{hack-local-variables}. - -@noindent -For example, if the user puts - -@example -Local Variables: -dired-actual-switches: "-lat" -dired-omit-mode: t -End: -@end example - -@noindent -into a file called @file{.dired} in a directory then when that directory is -viewed it will be - -@enumerate -@item -sorted by date -@item -omitted automatically -@end enumerate - -@noindent -You can set @code{dired-local-variables-file} to @code{nil} to suppress this. -The value of @code{dired-enable-local-variables} controls if and how these -local variables are read. This variable exists so that it may override the -default value of @code{enable-local-variables}. - -@noindent -Please see the GNU Emacs Manual to learn more about local variables. -@xref{File Variables,Local Variables in Files,Local Variables in -Files,emacs,The GNU Emacs Manual}. - -@noindent -The following variables affect Dired Local Variables - -@table @code -@vindex dired-local-variables-file -@item dired-local-variables-file -Default: @code{".dired"} - -If non-@code{nil}, file name for local variables for Dired. If Dired finds a -file with that name in the current directory, it will temporarily insert it -into the Dired buffer and run @code{hack-local-variables}. - -@vindex dired-enable-local-variables -@item dired-enable-local-variables -Default: @code{t} - -Controls the use of local-variables lists in Dired. This variable -temporarily overrides the value of @code{enable-local-variables} when -the Dired Local Variables are hacked. It takes the same values as that -variable. A value of @code{nil} means to ignore any Dired Local Variables. -@end table - -@node Shell Command Guessing, Virtual Dired, Local Variables, Top -@chapter Shell Command Guessing -@cindex Guessing shell commands for files. - -Based upon the name of a file, Dired tries to guess what shell -command you might want to apply to it. For example, if you have point -on a file named @file{foo.tar} and you press @kbd{!}, Dired will guess -you want to @samp{tar xvf} it and suggest that as the default shell -command. - -The default is mentioned in brackets and you can type @kbd{M-n} to get -the default into the minibuffer and then edit it, e.g., to change -@samp{tar xvf} to @samp{tar tvf}. If there are several commands for a given -file, e.g., @samp{xtex} and @samp{dvips} for a @file{.dvi} file, you can type -@kbd{M-n} several times to see each of the matching commands. - -Dired only tries to guess a command for a single file, never for a list -of marked files. - -@table @code -@item dired-guess-shell-alist-default -@vindex dired-guess-shell-alist-default -Predefined rules for shell commands. Set this to @code{nil} to turn guessing off. -The elements of @code{dired-guess-shell-alist-user} (defined by the -user) will override these rules.@refill - -@item dired-guess-shell-alist-user -@vindex dired-guess-shell-alist-user -If non-@code{nil}, a user-defined alist of file regexps and their suggested -commands. These rules take precedence over the predefined rules in the -variable @code{dired-guess-shell-alist-default} (to which they are prepended) -when @code{dired-do-shell-command} is run). -@refill - -Each element of the alist looks like - -@example -(@var{regexp} @var{command}@dots{}) -@end example - -@noindent -where each @var{command} can either be a string or a Lisp expression -that evaluates to a string. If several commands are given, all of -them will temporarily be pushed onto the history. - -If @samp{*} in the shell command, that means to substitute the file -name. - -You can set this variable in your @file{~/.emacs}. For example, -to add rules for @samp{.foo} and @samp{.bar} file extensions, write - -@example -(setq dired-guess-shell-alist-user - (list - (list "\\.foo$" "@var{foo-command}");; fixed rule - ;; possibly more rules... - (list "\\.bar$";; rule with condition test - '(if @var{condition} - "@var{bar-command-1}" - "@var{bar-command-2}")))) -@end example - -@noindent -This will override any predefined rules for the same extensions. - -@item dired-guess-shell-case-fold-search -@vindex dired-guess-shell-case-fold-search -Default: @code{t} - -Non-@code{nil} means @code{dired-guess-shell-alist-default} and -@code{dired-guess-shell-alist-user} are matched case-insensitively. - -@item dired-guess-shell-gnutar -@vindex dired-guess-shell-gnutar -@cindex Passing GNU Tar its @samp{z} switch. -Default: @code{nil} - -If non-@code{nil}, this is the name of the GNU Tar executable (e.g., -@samp{tar} or @samp{gnutar}). GNU Tar's @samp{z} switch is used for -compressed tar files. -If you don't have GNU tar, set this to @code{nil}: a pipe using @samp{zcat} is -then used. - -@item dired-guess-shell-gzip-quiet -@vindex dired-guess-shell-gzip-quiet -@cindex @code{gzip} -Default: @code{t} - -A non-@code{nil} value means that @samp{-q} is passed to @code{gzip} -overriding a verbose option in the @env{GZIP} environment variable. - -@item dired-guess-shell-znew-switches nil -@vindex dired-guess-shell-znew-switches nil -@cindex @code{znew} -Default: @code{nil} - -A string of switches passed to @code{znew}. An example is -@samp{-K} which will make @code{znew} keep a @file{.Z} file when it is -smaller than the @file{.gz} file. - -@item dired-shell-command-history nil -@vindex dired-shell-command-history nil - -History list for commands that read dired-shell commands. -@end table - -@node Virtual Dired, Advanced Mark Commands, Shell Command Guessing, Top -@chapter Virtual Dired - -@cindex Virtual Dired -@cindex Perusing @code{ls} listings -@cindex @code{ls} listings, how to peruse them in Dired -Using @dfn{Virtual Dired} means putting a buffer with Dired-like -contents in Dired mode. The files described by the buffer contents need -not actually exist. This is useful if you want to peruse an @samp{ls -lR} -output file, for example one you got from an FTP server. You can use -all motion commands usually available in Dired. You can also use -it to save a Dired buffer in a file and resume it in a later session. - -@findex dired-virtual -@kindex g -@findex dired-virtual-revert -Type @kbd{M-x dired-virtual} to put the current buffer into virtual -Dired mode. You will be prompted for the top level directory of this -buffer, with a default value guessed from the buffer contents. To -convert the virtual to a real Dired buffer again, type @kbd{g} (which -calls @code{dired-virtual-revert}) in the virtual Dired buffer and -answer @samp{y}. You don't have to do this, though: you can relist -single subdirectories using @kbd{l} (@code{dired-do-redisplay}) on the subdirectory -headerline, leaving the buffer in virtual Dired mode all the time. - -@findex dired-virtual-mode -@vindex auto-mode-alist -The function @samp{dired-virtual-mode} is specially designed to turn on -virtual Dired mode from the @code{auto-mode-alist}. To edit all -@file{*.dired} files automatically in virtual Dired mode, put this into your -@file{~/.emacs}: - -@example -(setq auto-mode-alist (cons '("[^/]\\.dired$" . dired-virtual-mode) - auto-mode-alist)) -@end example - -@noindent -The regexp is a bit more complicated than usual to exclude @file{.dired} -local-variable files. - -@node Advanced Mark Commands, Multiple Dired Directories, Virtual Dired, Top -@chapter Advanced Mark Commands - -@table @kbd -@item F -@kindex F -@cindex Visiting several files at once -@cindex Simultaneous visiting of several files -@findex dired-do-find-marked-files -(@code{dired-do-find-marked-files}) Find all marked files at once displaying -them simultaneously. If optional @var{noselect} is non-@code{nil} then just -find the -files but do not select. If you want to keep the Dired buffer displayed, type -@kbd{C-x 2} first. If you want just the marked files displayed and nothing -else, type @kbd{C-x 1} first. - -The current window is split across all files marked, as evenly as possible. -Remaining lines go to the bottom-most window. The number of files that can be -displayed this way is restricted by the height of the current window and the -variable @code{window-min-height}. -@end table - -@table @code -@item dired-mark-extension -@findex dired-mark-extension -Mark all files with a certain extension for use in later commands. A @samp{.} -is not automatically prepended to the string entered, you must type it -explicitly. - -When called from Lisp, @var{extension} may also be a list of extensions -and an optional argument @var{marker-char} specifies the marker used. - -@item dired-flag-extension -@findex dired-flag-extension -Flag all files with a certain extension for deletion. A @samp{.} is -@emph{not} automatically prepended to the string entered. -@end table - -@ifnottex -@menu -* Advanced Cleaning Functions:: -* Advanced Cleaning Variables:: -* Special Marking Function:: -@end menu -@end ifnottex - -@node Advanced Cleaning Functions, Advanced Cleaning Variables, , Advanced Mark Commands -@section Advanced Cleaning Functions - -@table @code -@item dired-clean-patch -@findex dired-clean-patch -Flag dispensable files created by the @samp{patch} program for deletion. See -variable @code{dired-patch-unclean-extensions}. - -@item dired-clean-tex -@findex dired-clean-tex -Flag dispensable files created by @TeX{}, La@TeX{}, and @samp{texinfo} for -deletion. See the following variables (@pxref{Advanced Cleaning Variables}): - -@itemize @bullet -@item -@code{dired-tex-unclean-extensions} -@item -@code{dired-texinfo-unclean-extensions} -@item -@code{dired-latex-unclean-extensions} -@item -@code{dired-bibtex-unclean-extensions} -@end itemize - -@item dired-very-clean-tex -@findex dired-very-clean-tex -Flag dispensable files created by @TeX{}, La@TeX{}, @samp{texinfo}, -and @file{*.dvi} files for deletion. -@end table - -@node Advanced Cleaning Variables, Special Marking Function, Advanced Cleaning Functions, Advanced Mark Commands -@section Advanced Cleaning Variables - -@noindent Variables used by the above cleaning commands (and in the default value for -variable @code{dired-omit-extensions}, @pxref{Omitting Variables}) - -@table @code -@item dired-patch-unclean-extensions -@vindex dired-patch-unclean-extensions -Default: @code{(".rej" ".orig")} - -List of extensions of dispensable files created by the @samp{patch} program. - -@item dired-tex-unclean-extensions -@vindex dired-tex-unclean-extensions -Default: @code{(".toc" ".log" ".aux")} - -List of extensions of dispensable files created by @TeX{}. - -@item dired-texinfo-unclean-extensions -@vindex dired-texinfo-unclean-extensions -Default: @code{(".cp" ".cps" ".fn" ".fns" ".ky" ".kys"} -@code{".pg" ".pgs" ".tp" ".tps" ".vr" ".vrs")} - -List of extensions of dispensable files created by @samp{texinfo}. - -@item dired-latex-unclean-extensions -@vindex dired-latex-unclean-extensions -Default: @code{(".idx" ".lof" ".lot" ".glo")} - -List of extensions of dispensable files created by La@TeX{}. - -@item dired-bibtex-unclean-extensions -@vindex dired-bibtex-unclean-extensions -Default: @code{(".blg" ".bbl")} - -List of extensions of dispensable files created by Bib@TeX{}. -@end table - -@node Special Marking Function, , Advanced Cleaning Variables, Advanced Mark Commands -@section Special Marking Function - -@table @kbd -@item M-( -@kindex M-( -@findex dired-mark-sexp -@cindex Lisp expression, marking files with in Dired -@cindex Mark file by Lisp expression -(@code{dired-mark-sexp}) Mark files for which @var{predicate} returns -non-@code{nil}. With a prefix argument, unflag those files instead. - -The @var{predicate} is a Lisp expression that can refer to the following -symbols: -@table @code -@item inode -[@i{integer}] the inode of the file (only for @samp{ls -i} output) -@item s -[@i{integer}] the size of the file for @samp{ls -s} output (usually in blocks or, -with @samp{-k}, in KBytes) -@item mode -[@i{string}] file permission bits, e.g., @samp{-rw-r--r--} -@item nlink -[@i{integer}] number of links to file -@item uid -[@i{string}] owner -@item gid -[@i{string}] group (If the gid is not displayed by @samp{ls}, this -will still be set (to the same as uid)) -@item size -[@i{integer}] file size in bytes -@item time -[@i{string}] the time that @samp{ls} displays, e.g., @samp{Feb 12 14:17} -@item name -[@i{string}] the name of the file -@item sym -[@i{string}] if file is a symbolic link, the linked-to name, else @code{""} -@end table - -@noindent -For example, use -@example -(equal 0 size) -@end example -to mark all zero length files. - -To find out all not yet compiled Emacs Lisp files in a directory, Dired -all @file{.el} files in the lisp directory using the wildcard -@samp{*.el}. Then use @kbd{M-(} with -@example -(not (file-exists-p (concat name "c"))) -@end example -to mark all @file{.el} files without a corresponding @file{.elc} file. - -@end table - -@node Multiple Dired Directories, Find File At Point, Advanced Mark Commands, Top -@chapter Multiple Dired Directories and Non-Dired Commands - -@cindex Multiple Dired directories -@cindex Working directory -An Emacs buffer can have but one working directory, stored in the -buffer-local variable @code{default-directory}. A Dired buffer may have -several subdirectories inserted, but it still has only one working -directory: that of the top-level Dired directory in that buffer. For -some commands it is appropriate that they use the current Dired -directory instead of @code{default-directory}, e.g., @code{find-file} and -@code{compile}. - -@findex dired-smart-shell-command -@findex shell-command -@kindex M-! -The command @code{dired-smart-shell-command}, bound to @kbd{M-!} in -Dired buffers, is like @code{shell-command}, but it runs with -@code{default-directory} bound to the current Dired directory. - -@node Find File At Point, Miscellaneous Commands, Multiple Dired Directories, Top -@section Find File At Point -@cindex Visiting a file mentioned in a buffer -@cindex Finding a file at point - -@file{dired-x} provides a method of visiting or editing a file mentioned in -the buffer you are viewing (e.g., a mail buffer, a news article, a -@file{README} file, etc.) or to test if that file exists. You can then modify -this in the minibuffer after snatching the file name. - -When installed @file{dired-x} will substitute @code{dired-x-find-file} for -@code{find-file} (normally bound to @kbd{C-x C-f}) and -@code{dired-x-find-file-other-window} for @code{find-file-other-window} -(normally bound to @kbd{C-x 4 C-f}). - -In order to use this feature, you will need to set -@code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook} -(@pxref{Optional Installation File At Point}). - -@table @code -@item dired-x-find-file -@findex dired-x-find-file -@kindex C-x C-f - -@code{dired-x-find-file} behaves exactly like @code{find-file} (normally bound -to @kbd{C-x C-f}) unless a prefix argument is passed to the function in which -case it will use the file name at point as a guess for the file to visit. - -For example, if the buffer you were reading contained the words - -@example -Available via anonymous ftp in - - /roebling.poly.edu:/pub/lisp/crypt++.el.gz -@end example - -@noindent -then you could move your cursor to the line containing the ftp address and -type @kbd{C-u C-x C-f} (the @kbd{C-u} is a universal argument). The -minibuffer would read - -@example -Find file: /roebling.poly.edu:/pub/lisp/crypt++.el.gz -@end example - -@noindent -with the point after the last @code{/}. If you hit @key{RET}, emacs will visit -the file at that address. This also works with files on your own computer. - -@item dired-x-find-file-other-window -@findex dired-x-find-file-other-window -@kindex C-x 4 C-f - -@code{dired-x-find-file-other-window} behaves exactly like -@code{find-file-other-window} (normally bound to @kbd{C-x 4 C-f}) unless a -prefix argument is used. See @code{dired-x-find-file} for more information. - -@item dired-x-hands-off-my-keys -@vindex dired-x-hands-off-my-keys -If set to @code{t}, then it means that @file{dired-x} should @emph{not} bind -@code{dired-x-find-file} over @code{find-file} on keyboard. Similarly, it -should not bind @code{dired-x-find-file-other-window} over -@code{find-file-other-window}. If you change this variable after -@file{dired-x.el} is loaded then do @kbd{M-x dired-x-bind-find-file}. The -default value of this variable is @code{t}; by default, the binding is not -done. See @xref{Optional Installation File At Point}. - -@item dired-x-bind-find-file -@findex dired-x-bind-find-file -A function, which can be called interactively or in your @file{~/.emacs} file, -that uses the value of @code{dired-x-hands-off-my-keys} to determine if -@code{dired-x-find-file} should be bound over @code{find-file} and -@code{dired-x-find-file-other-window} bound over -@code{find-file-other-window}. See @xref{Optional Installation File At Point}. -@end table - -@node Miscellaneous Commands, Bugs, Find File At Point, Top -@chapter Miscellaneous Commands - -Miscellaneous features not fitting anywhere else: - -@table @code -@item dired-find-subdir -@vindex dired-find-subdir -Default: @code{nil} - -If non-@code{nil}, Dired does not make a new buffer for a directory if it can -be found (perhaps as subdirectory) in some existing Dired buffer. - -If there are several Dired buffers for a directory, the most recently -used is chosen. - -Dired avoids switching to the current buffer, so that if you have a -normal and a wildcard buffer for the same directory, @kbd{C-x d RET} -will toggle between those two. -@end table - -@table @kbd -@findex dired-goto-subdir -@kindex M-G -@item M-G -(@code{dired-goto-subdir}) Go to the header line of an inserted directory. -This command reads its argument, with completion derived from the names of the -inserted subdirectories. -@end table - -@table @code - -@item dired-jump -@findex dired-jump -@kindex C-x C-j -@cindex Jumping to Dired listing containing file. -Bound to @kbd{C-x C-j}. Jump back to Dired: If in a file, edit the current -directory and move to file's line. If in Dired already, pop up a level and -go to old directory's line. In case the proper Dired file line cannot be -found, refresh the Dired buffer and try again. - -@item dired-jump-other-window -@findex dired-jump-other-window -@kindex C-x 4 C-j -Bound to @kbd{C-x 4 C-j}. Like @code{dired-jump}, but to other window. - -These functions can be autoloaded so they work even though @file{dired-x.el} -has not been loaded yet (@pxref{Optional Installation Dired Jump}). - -@vindex dired-bind-jump -If the variable @code{dired-bind-jump} is @code{nil}, @code{dired-jump} will not be -bound to @kbd{C-x C-j} and @code{dired-jump-other-window} will not be bound to -@kbd{C-x 4 C-j}. - -@item dired-vm -@cindex Reading mail. -@kindex V -@findex dired-vm -Bound to @kbd{V} if @code{dired-bind-vm} is @code{t}. Run VM on this -file (assumed to be a UNIX mail folder). - -@vindex dired-vm-read-only-folders -If you give this command a prefix argument, it will visit the folder -read-only. - -If the variable @code{dired-vm-read-only-folders} is @code{t}, -@code{dired-vm} will visit all folders read-only. If it is neither -@code{nil} nor @code{t}, e.g., the symbol @code{if-file-read-only}, only -files not writable by you are visited read-only. - -@vindex dired-bind-vm -If the variable @code{dired-bind-vm} is @code{t}, @code{dired-vm} will be bound -to @kbd{V}. Otherwise, @code{dired-bind-rmail} will be bound. - -@item dired-rmail -@cindex Reading mail. -@findex dired-rmail -Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}. Run Rmail on this -file (assumed to be mail folder in Rmail format). - -@item dired-info -@kindex I -@cindex Running info. -@findex dired-info -Bound to @kbd{I}. Run Info on this file (assumed to be a file in Info -format). - -@vindex dired-bind-info -If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will -not be bound to @kbd{I}. - -@item dired-man -@cindex Running man. -@kindex N -@findex dired-man -Bound to @kbd{N}. Run man on this file (assumed to be a file in @code{nroff} -format). - -@vindex dired-bind-man -If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not -be bound to @kbd{N}. - -@item dired-do-relsymlink -@cindex Relative symbolic links. -@kindex Y -@findex dired-do-relsymlink -Bound to @kbd{Y}. Relative symlink all marked (or next ARG) files into a -directory, or make a relative symbolic link to the current file. This creates -relative symbolic links like - -@example - foo -> ../bar/foo -@end example - -@noindent -not absolute ones like - -@example - foo -> /ugly/path/that/may/change/any/day/bar/foo -@end example - -@item dired-do-relsymlink-regexp -@kindex %Y -@findex dired-do-relsymlink-regexp -Bound to @kbd{%Y}. Relative symlink all marked files containing -@var{regexp} to @var{newname}. See functions -@code{dired-do-rename-regexp} and @code{dired-do-relsymlink} for more -info. -@end table - -@node Bugs, GNU Free Documentation License, Miscellaneous Commands, Top -@chapter Bugs -@cindex Bugs - -@noindent -If you encounter a bug in this package, or wish to suggest an -enhancement, then please use @kbd{M-x report-emacs-bug} to report it. - -@node GNU Free Documentation License, Concept Index, Bugs, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index, Command Index, GNU Free Documentation License, Top -@unnumbered Concept Index -@printindex cp - -@node Command Index, Key Index, Concept Index, Top -@unnumbered Function Index -@printindex fn - -@node Key Index, Variable Index, Command Index, Top -@unnumbered Key Index -@printindex ky - -@node Variable Index, , Key Index, Top -@unnumbered Variable Index -@printindex vr - -@bye diff --git a/doc/misc/doclicense.texi b/doc/misc/doclicense.texi deleted file mode 100644 index a511ffcd5a8..00000000000 --- a/doc/misc/doclicense.texi +++ /dev/null @@ -1,507 +0,0 @@ -@c -*-texinfo-*- -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008, 2009 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input -format, @acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML}, -PostScript or @acronym{PDF} designed for human modification. Examples -of transparent image formats include @acronym{PNG}, @acronym{XCF} and -@acronym{JPG}. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, @acronym{SGML} or -@acronym{XML} for which the @acronym{DTD} and/or processing tools are -not generally available, and the machine-generated @acronym{HTML}, -PostScript or @acronym{PDF} produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.'' line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: diff --git a/doc/misc/ebrowse.texi b/doc/misc/ebrowse.texi deleted file mode 100644 index 6db27a38808..00000000000 --- a/doc/misc/ebrowse.texi +++ /dev/null @@ -1,1453 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@comment %**start of header -@setfilename ../../info/ebrowse -@settitle A Class Browser for C++ -@setchapternewpage odd -@syncodeindex fn cp -@comment %**end of header - -@copying -This file documents Ebrowse, a C++ class browser for GNU Emacs. - -Copyright @copyright{} 2000-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Ebrowse: (ebrowse). A C++ class browser for Emacs. -@end direntry - -@titlepage -@title Ebrowse User's Manual -@sp 4 -@subtitle Ebrowse/Emacs -@sp 5 -@author Gerd Moellmann -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Overview, (dir), (dir) -@top Ebrowse - -You can browse C++ class hierarchies from within Emacs by using -Ebrowse. - -@insertcopying -@end ifnottex - -@menu -* Overview:: What is it and how does it work? -* Generating browser files:: How to process C++ source files -* Loading a Tree:: How to start browsing -* Tree Buffers:: Traversing class hierarchies -* Member Buffers:: Looking at member information -* Tags-like Functions:: Finding members from source files -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: An entry for each concept defined -@end menu - - - - -@node Overview, Generating browser files, Top, Top -@chapter Introduction - -When working in software projects using C++, I frequently missed -software support for two things: - -@itemize @bullet -@item -When you get a new class library, or you have to work on source code you -haven't written yourself (or written sufficiently long ago), you need a -tool to let you navigate class hierarchies and investigate -features of the software. Without such a tool you often end up -@command{grep}ing through dozens or even hundreds of files. - -@item -Once you are productive, it would be nice to have a tool that knows your -sources and can help you while you are editing source code. Imagine to -be able to jump to the definition of an identifier while you are -editing, or something that can complete long identifier names because it -knows what identifiers are defined in your program@dots{}. -@end itemize - -The design of Ebrowse reflects these two needs. - -How does it work? - -@cindex parser for C++ sources -A fast parser written in C is used to process C++ source files. -The parser generates a data base containing information about classes, -members, global functions, defines, types etc.@: found in the sources. - -The second part of Ebrowse is a Lisp program. This program reads -the data base generated by the parser. It displays its contents in -various forms and allows you to perform operations on it, or do -something with the help of the knowledge contained in the data base. - -@cindex major modes, of Ebrowse buffers -@dfn{Navigational} use of Ebrowse is centered around two -types of buffers which define their own major modes: - -@cindex tree buffer -@dfn{Tree buffers} are used to view class hierarchies in tree form. -They allow you to quickly find classes, find or view class declarations, -perform operations like query replace on sets of your source files, and -finally tree buffers are used to produce the second buffer form---member -buffers. @xref{Tree Buffers}. - -@cindex member buffer -Members are displayed in @dfn{member buffers}. Ebrowse -distinguishes between six different types of members; each type is -displayed as a member list of its own: - -@itemize @bullet -@item -Instance member variables; - -@item -Instance member functions; - -@item -Static member variables; - -@item -Static member functions; - -@item -Friends/Defines. The list of defines is contained in the friends -list of the pseudo-class @samp{*Globals*}; - -@item -Types (@code{enum}s, and @code{typedef}s defined with class -scope).@refill -@end itemize - -You can switch member buffers from one list to another, or to another -class. You can include inherited members in the display, you can set -filters that remove categories of members from the display, and most -importantly you can find or view member declarations and definitions -with a keystroke. @xref{Member Buffers}. - -These two buffer types and the commands they provide support the -navigational use of the browser. The second form resembles Emacs's Tags -package for C and other procedural languages. Ebrowse's commands of -this type are not confined to special buffers; they are most often used -while you are editing your source code. - -To list just a subset of what you can use the Tags part of Ebrowse for: - -@itemize @bullet -@item -Jump to the definition or declaration of an identifier in your source -code, with an electric position stack that lets you easily navigate -back and forth. - -@item -Complete identifiers in your source with a completion list containing -identifiers from your source code only. - -@item -Perform search and query replace operations over some or all of your -source files. - -@item -Show all identifiers matching a regular expression---and jump to one of -them, if you like. -@end itemize - - - - -@node Generating browser files, Loading a Tree, Overview, Top -@comment node-name, next, previous, up -@chapter Processing Source Files - -@cindex @command{ebrowse}, the program -@cindex class data base creation -Before you can start browsing a class hierarchy, you must run the parser -@command{ebrowse} on your source files in order to generate a Lisp data -base describing your program. - -@cindex command line for @command{ebrowse} -The operation of @command{ebrowse} can be tailored with command line -options. Under normal circumstances it suffices to let the parser use -its default settings. If you want to do that, call it with a command -line like: - -@example -ebrowse *.h *.cc -@end example - -@noindent -or, if your shell doesn't allow all the file names to be specified on -the command line, - -@example -ebrowse --files=@var{file} -@end example - -@noindent -where @var{file} contains the names of the files to be parsed, one -per line. - -@findex --help -When invoked with option @samp{--help}, @command{ebrowse} prints a list of -available command line options.@refill - -@menu -* Input files:: Specifying which files to parse -* Output file:: Changing the output file name -* Structs and unions:: Omitting @code{struct}s and @code{union}s -* Matching:: Setting regular expression lengths -* Verbosity:: Getting feedback for lengthy operations -@end menu - - - - -@comment name, next, prev, up -@node Input files, Output file, Generating browser files, Generating browser files -@section Specifying Input Files - -@table @samp -@cindex input files, for @command{ebrowse} -@item file -Each file name on the command line tells @command{ebrowse} to parse -that file. - -@cindex response files -@findex --files -@item --files=@var{file} -This command line switch specifies that @var{file} contains a list of -file names to parse. Each line in @var{file} must contain one file -name. More than one option of this kind is allowed. You might, for -instance, want to use one file for header files, and another for source -files. - -@cindex standard input, specifying input files -@item standard input -When @command{ebrowse} finds no file names on the command line, and no -@samp{--file} option is specified, it reads file names from standard -input. This is sometimes convenient when @command{ebrowse} is used as part -of a command pipe. - -@findex --search-path -@item --search-path=@var{paths} -This option lets you specify search paths for your input files. -@var{paths} is a list of directory names, separated from each other by a -either a colon or a semicolon, depending on the operating system. -@end table - -@cindex header files -@cindex friend functions -It is generally a good idea to specify input files so that header files -are parsed before source files. This facilitates the parser's work of -properly identifying friend functions of a class. - - - -@comment name, next, prev, up -@node Output file, Structs and unions, Input files, Generating browser files -@section Changing the Output File Name - -@table @samp -@cindex output file name -@findex --output-file -@cindex @file{BROWSE} file -@item --output-file=@var{file} -This option instructs @command{ebrowse} to generate a Lisp data base with -name @var{file}. By default, the data base is named @file{BROWSE}, and -is written in the directory in which @command{ebrowse} is invoked. - -If you regularly use data base names different from the default, you -might want to add this to your init file: - -@lisp -(add-to-list 'auto-mode-alist '(@var{NAME} . ebrowse-tree-mode)) -@end lisp - -@noindent -where @var{NAME} is the Lisp data base name you are using. - -@findex --append -@cindex appending output to class data base -@item --append -By default, each run of @command{ebrowse} erases the old contents of the -output file when writing to it. You can instruct @command{ebrowse} to -append its output to an existing file produced by @command{ebrowse} -with this command line option. -@end table - - - - -@comment name, next, prev, up -@node Structs and unions, Matching, Output file, Generating browser files -@section Structs and Unions -@cindex structs -@cindex unions - -@table @samp -@findex --no-structs-or-unions -@item --no-structs-or-unions -This switch suppresses all classes in the data base declared as -@code{struct} or @code{union} in the output. - -This is mainly useful when you are converting an existing -C program to C++, and do not want to see the old C structs in a class -tree. -@end table - - - - -@comment name, next, prev, up -@node Matching, Verbosity, Structs and unions, Generating browser files -@section Regular Expressions - -@cindex regular expressions, recording -The parser @command{ebrowse} normally writes regular expressions to its -output file that help the Lisp part of Ebrowse to find functions, -variables etc.@: in their source files. - -You can instruct @command{ebrowse} to omit these regular expressions by -calling it with the command line switch @samp{--no-regexps}. - -When you do this, the Lisp part of Ebrowse tries to guess, from member -or class names, suitable regular expressions to locate that class or -member in source files. This works fine in most cases, but the -automatic generation of regular expressions can be too weak if unusual -coding styles are used. - -@table @samp -@findex --no-regexps -@item --no-regexps -This option turns off regular expression recording. - -@findex --min-regexp-length -@cindex minimum regexp length for recording -@item --min-regexp-length=@var{n} -The number @var{n} following this option specifies the minimum length of -the regular expressions recorded to match class and member declarations -and definitions. The default value is set at compilation time of -@command{ebrowse}. - -The smaller the minimum length, the higher the probability that -Ebrowse will find a wrong match. The larger the value, the -larger the output file and therefore the memory consumption once the -file is read from Emacs. - -@findex --max-regexp-length -@cindex maximum regexp length for recording -@item --max-regexp-length=@var{n} -The number following this option specifies the maximum length of the -regular expressions used to match class and member declarations and -definitions. The default value is set at compilation time of -@command{ebrowse}. - -The larger the maximum length, the higher the probability that the -browser will find a correct match, but the larger the value the larger -the output file and therefore the memory consumption once the data is -read. As a second effect, the larger the regular expression, the higher -the probability that it will no longer match after editing the file. -@end table - - - - -@node Verbosity, , Matching, Generating browser files -@comment node-name, next, previous, up -@section Verbose Mode -@cindex verbose operation - -@table @samp -@findex --verbose -@item --verbose -When this option is specified on the command line, @command{ebrowse} prints -a period for each file parsed, and it displays a @samp{+} for each -class written to the output file. - -@findex --very-verbose -@item --very-verbose -This option makes @command{ebrowse} print out the names of the files and -the names of the classes seen. -@end table - - - - -@node Loading a Tree, Tree Buffers, Generating browser files, Top -@comment node-name, next, previous, up -@chapter Starting to Browse -@cindex loading -@cindex browsing - -You start browsing a class hierarchy parsed by @command{ebrowse} by just -finding the @file{BROWSE} file with @kbd{C-x C-f}. - -An example of a tree buffer display is shown below. - -@example -| Collection -| IndexedCollection -| Array -| FixedArray -| Set -| Dictionary -@end example - -@cindex mouse highlight in tree buffers -When you run Emacs on a display which supports colors and the mouse, you -will notice that certain areas in the tree buffer are highlighted -when you move the mouse over them. This highlight marks mouse-sensitive -regions in the buffer. Please notice the help strings in the echo area -when the mouse moves over a sensitive region. - -@cindex context menu -A click with @kbd{Mouse-3} on a mouse-sensitive region opens a context -menu. In addition to this, each buffer also has a buffer-specific menu -that is opened with a click with @kbd{Mouse-3} somewhere in the buffer -where no highlight is displayed. - - - -@comment **************************************************************** -@comment *** -@comment *** TREE BUFFERS -@comment *** -@comment **************************************************************** - -@node Tree Buffers, Member Buffers, Loading a Tree, Top -@comment node-name, next, previous, up -@chapter Tree Buffers -@cindex tree buffer mode -@cindex class trees - -Class trees are displayed in @dfn{tree buffers} which install their own -major mode. Most Emacs keys work in tree buffers in the usual way, -e.g.@: you can move around in the buffer with the usual @kbd{C-f}, -@kbd{C-v} etc., or you can search with @kbd{C-s}. - -Tree-specific commands are bound to simple keystrokes, similar to -@code{Gnus}. You can take a look at the key bindings by entering -@kbd{?} which calls @code{M-x describe-mode} in both tree and member -buffers. - -@menu -* Source Display:: Viewing and finding a class declaration -* Member Display:: Showing members, switching to member buffers -* Go to Class:: Finding a class -* Quitting:: Discarding and burying the tree buffer -* File Name Display:: Showing file names in the tree -* Expanding and Collapsing:: Expanding and collapsing branches -* Tree Indentation:: Changing the tree indentation -* Killing Classes:: Removing class from the tree -* Saving a Tree:: Saving a modified tree -* Statistics:: Displaying class tree statistics -* Marking Classes:: Marking and unmarking classes -@end menu - - - -@node Source Display, Member Display, Tree Buffers, Tree Buffers -@comment node-name, next, previous, up -@section Viewing and Finding Class Declarations -@cindex viewing, class -@cindex finding a class -@cindex class declaration - -You can view or find a class declaration when the cursor is on a class -name. - -@table @kbd -@item SPC -This command views the class declaration if the database -contains information about it. If you don't parse the entire source -you are working on, some classes will only be known to exist but the -location of their declarations and definitions will not be known.@refill - -@item RET -Works like @kbd{SPC}, except that it finds the class -declaration rather than viewing it, so that it is ready for -editing.@refill -@end table - -The same functionality is available from the menu opened with -@kbd{Mouse-3} on the class name. - - - - -@node Member Display, Go to Class, Source Display, Tree Buffers -@comment node-name, next, previous, up -@section Displaying Members -@cindex @samp{*Members*} buffer -@cindex @samp{*Globals*} -@cindex freezing a member buffer -@cindex member lists, in tree buffers - -Ebrowse distinguishes six different kinds of members, each of -which is displayed as a separate @dfn{member list}: instance variables, -instance functions, static variables, static functions, friend -functions, and types. - -Each of these lists can be displayed in a member buffer with a command -starting with @kbd{L} when the cursor is on a class name. By default, -there is only one member buffer named @dfn{*Members*} that is reused -each time you display a member list---this has proven to be more -practical than to clutter up the buffer list with dozens of member -buffers. - -If you want to display more than one member list at a time you can -@dfn{freeze} its member buffer. Freezing a member buffer prevents it -from being overwritten the next time you display a member list. You can -toggle this buffer status at any time. - -Every member list display command in the tree buffer can be used with a -prefix argument (@kbd{C-u}). Without a prefix argument, the command will -pop to a member buffer displaying the member list. With prefix argument, -the member buffer will additionally be @dfn{frozen}. - -@table @kbd -@cindex instance member variables, list -@item L v -This command displays the list of instance member variables. - -@cindex static variables, list -@item L V -Display the list of static variables. - -@cindex friend functions, list -@item L d -Display the list of friend functions. This list is used for defines if -you are viewing the class @samp{*Globals*} which is a place holder for -global symbols. - -@cindex member functions, list -@item L f -Display the list of member functions. - -@cindex static member functions, list -@item L F -Display the list of static member functions. - -@cindex types, list -@item L t -Display a list of types. -@end table - -These lists are also available from the class' context menu invoked with -@kbd{Mouse-3} on the class name. - - - - -@node Go to Class, Quitting, Member Display, Tree Buffers -@comment node-name, next, previous, up -@section Finding a Class -@cindex locate class -@cindex expanding branches -@cindex class location - -@table @kbd -@cindex search for class -@item / -This command reads a class name from the minibuffer with completion and -positions the cursor on the class in the class tree. - -If the branch of the class tree containing the class searched for is -currently collapsed, the class itself and all its base classes are -recursively made visible. (See also @ref{Expanding and -Collapsing}.)@refill - -This function is also available from the tree buffer's context menu. - -@item n -Repeat the last search done with @kbd{/}. Each tree buffer has its own -local copy of the regular expression last searched in it. -@end table - - - - -@node Quitting, File Name Display, Go to Class, Tree Buffers -@comment node-name, next, previous, up -@section Burying a Tree Buffer -@cindex burying tree buffer - -@table @kbd -@item q -Is a synonym for @kbd{M-x bury-buffer}. -@end table - - - - -@node File Name Display, Expanding and Collapsing, Quitting, Tree Buffers -@comment node-name, next, previous, up -@section Displaying File Names - -@table @kbd -@cindex file names in tree buffers -@item T f -This command toggles the display of file names in a tree buffer. If -file name display is switched on, the names of the files containing the -class declaration are shown to the right of the class names. If the -file is not known, the string @samp{unknown} is displayed. - -This command is also provided in the tree buffer's context menu. - -@item s -Display file names for the current line, or for the number of lines -given by a prefix argument. -@end table - -Here is an example of a tree buffer with file names displayed. - -@example -| Collection (unknown) -| IndexedCollection (indexedcltn.h) -| Array (array.h) -| FixedArray (fixedarray.h) -| Set (set.h) -| Dictionary (dict.h) -@end example - - -@node Expanding and Collapsing, Tree Indentation, File Name Display, Tree Buffers -@comment node-name, next, previous, up -@section Expanding and Collapsing a Tree -@cindex expand tree branch -@cindex collapse tree branch -@cindex branches of class tree -@cindex class tree, collapse or expand - -You can expand and collapse parts of a tree to reduce the complexity of -large class hierarchies. Expanding or collapsing branches of a tree has -no impact on the functionality of other commands, like @kbd{/}. (See -also @ref{Go to Class}.)@refill - -Collapsed branches are indicated with an ellipsis following the class -name like in the example below. - -@example -| Collection -| IndexedCollection... -| Set -| Dictionary -@end example - -@table @kbd -@item - -This command collapses the branch of the tree starting at the class the -cursor is on. - -@item + -This command expands the branch of the tree starting at the class the -cursor is on. Both commands for collapsing and expanding branches are -also available from the class' object menu. - -@item * -This command expands all collapsed branches in the tree. -@end table - - - - -@node Tree Indentation, Killing Classes, Expanding and Collapsing, Tree Buffers -@comment node-name, next, previous, up -@section Changing the Tree Indentation -@cindex tree indentation -@cindex indentation of the tree - -@table @kbd -@item T w -This command reads a new indentation width from the minibuffer and -redisplays the tree buffer with the new indentation It is also -available from the tree buffer's context menu. -@end table - - - - -@node Killing Classes, Saving a Tree, Tree Indentation, Tree Buffers -@comment node-name, next, previous, up -@section Removing Classes from the Tree -@cindex killing classes -@cindex class, remove from tree - -@table @kbd -@item C-k -This command removes the class the cursor is on and all its derived -classes from the tree. The user is asked for confirmation before the -deletion is actually performed. -@end table - - - - -@node Saving a Tree, Statistics, Killing Classes, Tree Buffers -@comment node-name, next, previous, up -@comment node-name, next, previous, up -@section Saving a Tree -@cindex save tree to a file -@cindex tree, save to a file -@cindex class tree, save to a file - -@table @kbd -@item C-x C-s -This command writes a class tree to the file from which it was read. -This is useful after classes have been deleted from a tree. - -@item C-x C-w -Writes the tree to a file whose name is read from the minibuffer. -@end table - - - - -@node Statistics, Marking Classes, Saving a Tree, Tree Buffers -@comment node-name, next, previous, up -@cindex statistics for a tree -@cindex tree statistics -@cindex class statistics - -@table @kbd -@item x -Display statistics for the tree, like number of classes in it, number of -member functions, etc. This command can also be found in the buffer's -context menu. -@end table - - - - -@node Marking Classes, , Statistics, Tree Buffers -@comment node-name, next, previous, up -@cindex marking classes -@cindex operations on marked classes - -Classes can be marked for operations similar to the standard Emacs -commands @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} (see -also @xref{Tags-like Functions}.)@refill - -@table @kbd -@cindex toggle mark -@item M t -Toggle the mark of the line point is in or for as many lines as given by -a prefix command. This command can also be found in the class' context -menu. - -@cindex unmark all -@item M a -Unmark all classes. With prefix argument @kbd{C-u}, mark all classes in -the tree. Since this command operates on the whole buffer, it can also be -found in the buffer's object menu. -@end table - -Marked classes are displayed with an @code{>} in column one of the tree -display, like in the following example - -@example -|> Collection -| IndexedCollection... -|> Set -| Dictionary -@end example - - - - -@c **************************************************************** -@c *** -@c *** MEMBER BUFFERS -@c *** -@c **************************************************************** - -@node Member Buffers, Tags-like Functions, Tree Buffers, Top -@comment node-name, next, previous, up -@chapter Member Buffers -@cindex members -@cindex member buffer mode - -@cindex class members, types -@cindex types of class members -@dfn{Member buffers} are used to operate on lists of members of a class. -Ebrowse distinguishes six kinds of lists: - -@itemize @bullet -@item -Instance variables (normal member variables); -@item -Instance functions (normal member functions); -@item -Static variables; -@item -Static member functions; -@item -Friend functions; -@item -Types (@code{enum}s and @code{typedef}s defined with class scope. -Nested classes will be shown in the class tree like normal classes. -@end itemize - -Like tree buffers, member buffers install their own major mode. Also -like in tree buffers, menus are provided for certain areas in the -buffer: members, classes, and the buffer itself. - -@menu -* Switching Member Lists:: Choosing which members to display -* Finding/Viewing:: Modifying source code -* Inherited Members:: Display of Inherited Members -* Searching Members:: Finding members in member buffer -* Switching to Tree:: Going back to the tree buffer -* Filters:: Selective member display -* Attributes:: Display of @code{virtual} etc. -* Long and Short Display:: Comprehensive and verbose display -* Regexp Display:: Showing matching regular expressions -* Switching Classes:: Displaying another class -* Killing/Burying:: Getting rid of the member buffer -* Column Width:: Display style -* Redisplay:: Redrawing the member list -* Getting Help:: How to get help for key bindings -@end menu - - - - -@node Switching Member Lists, Finding/Viewing, Member Buffers, Member Buffers -@comment node-name, next, previous, up -@section Switching Member Lists -@cindex member lists, in member buffers -@cindex static members -@cindex friends -@cindex types -@cindex defines - -@table @kbd -@cindex next member list -@item L n -This command switches the member buffer display to the next member list. - -@cindex previous member list -@item L p -This command switches the member buffer display to the previous member -list. - -@item L f -Switch to the list of member functions. - -@cindex static -@item L F -Switch to the list of static member functions. - -@item L v -Switch to the list of member variables. - -@item L V -Switch to the list of static member variables. - -@item L d -Switch to the list of friends or defines. - -@item L t -Switch to the list of types. -@end table - -Both commands cycle through the member list. - -Most of the commands are also available from the member buffer's -context menu. - - - - -@node Finding/Viewing, Inherited Members, Switching Member Lists, Member Buffers -@comment node-name, next, previous, up -@section Finding and Viewing Member Source -@cindex finding members, in member buffers -@cindex viewing members, in member buffers -@cindex member definitions, in member buffers -@cindex member declarations, in member buffers -@cindex definition of a member, in member buffers -@cindex declaration of a member, in member buffers - -@table @kbd -@item RET -This command finds the definition of the member the cursor is on. -Finding involves roughly the same as the standard Emacs tags facility -does---loading the file and searching for a regular expression matching -the member. - -@item f -This command finds the declaration of the member the cursor is on. - -@item SPC -This is the same command as @kbd{RET}, but views the member definition -instead of finding the member's source file. - -@item v -This is the same command as @kbd{f}, but views the member's declaration -instead of finding the file the declaration is in. -@end table - -You can install a hook function to perform actions after a member or -class declaration or definition has been found, or when it is not found. - -All the commands described above can also be found in the context menu -displayed when clicking @kbd{Mouse-2} on a member name. - - - - -@node Inherited Members, Searching Members, Finding/Viewing, Member Buffers -@comment node-name, next, previous, up -@section Display of Inherited Members -@cindex superclasses, members -@cindex base classes, members -@cindex inherited members - -@table @kbd -@item D b -This command toggles the display of inherited members in the member -buffer. This is also in the buffer's context menu. -@end table - - - - -@node Searching Members, Switching to Tree, Inherited Members, Member Buffers -@comment node-name, next, previous, up -@section Searching Members -@cindex searching members - -@table @kbd -@item G v -Position the cursor on a member whose name is read from the minibuffer; -only members shown in the current member buffer appear in the completion -list. - -@item G m -Like the above command, but all members for the current class appear in -the completion list. If necessary, the current member list is switched -to the one containing the member. - -With a prefix argument (@kbd{C-u}), all members in the class tree, -i.e.@: all members the browser knows about appear in the completion -list. The member display will be switched to the class and member list -containing the member. - -@item G n -Repeat the last member search. -@end table - -Look into the buffer's context menu for a convenient way to do this with -a mouse. - - - -@node Switching to Tree, Filters, Searching Members, Member Buffers -@comment node-name, next, previous, up -@section Switching to Tree Buffer -@cindex tree buffer, switch to -@cindex buffer switching -@cindex switching buffers - -@table @kbd -@item @key{TAB} -Pop up the tree buffer to which the member buffer belongs. - -@item t -Do the same as @key{TAB} but also position the cursor on the class -displayed in the member buffer. -@end table - - - - -@node Filters, Attributes, Switching to Tree, Member Buffers -@comment node-name, next, previous, up -@section Filters -@cindex filters - -@table @kbd -@cindex @code{public} members -@item F a u -This command toggles the display of @code{public} members. The -@samp{a} stands for `access'. - -@cindex @code{protected} members -@item F a o -This command toggles the display of @code{protected} members. - -@cindex @code{private} members -@item F a i -This command toggles the display of @code{private} members. - -@cindex @code{virtual} members -@item F v -This command toggles the display of @code{virtual} members. - -@cindex @code{inline} members -@item F i -This command toggles the display of @code{inline} members. - -@cindex @code{const} members -@item F c -This command toggles the display of @code{const} members. - -@cindex pure virtual members -@item F p -This command toggles the display of pure virtual members. - -@cindex remove filters -@item F r -This command removes all filters. -@end table - -These commands are also found in the buffer's context menu. - - - - -@node Attributes, Long and Short Display, Filters, Member Buffers -@comment node-name, next, previous, up -@section Displaying Member Attributes -@cindex attributes -@cindex member attribute display - -@table @kbd -@item D a -Toggle the display of member attributes (default is on). - -The nine member attributes Ebrowse knows about are displayed -as a list a single-characters flags enclosed in angle brackets in front -the of the member's name. A @samp{-} at a given position means that -the attribute is false. The list of attributes from left to right is - -@table @samp -@cindex @code{template} attribute -@item T -The member is a template. - -@cindex @code{extern "C"} attribute -@item C -The member is declared @code{extern "C"}. - -@cindex @code{virtual} attribute -@item v -Means the member is declared @code{virtual}. - -@cindex @code{inline} -@item i -The member is declared @code{inline}. - -@cindex @code{const} attribute -@item c -The member is @code{const}. - -@cindex pure virtual function attribute -@item 0 -The member is a pure virtual function. - -@cindex @code{mutable} attribute -@item m -The member is declared @code{mutable}. - -@cindex @code{explicit} attribute -@item e -The member is declared @code{explicit}. - -@item t -The member is a function with a throw list. -@end table -@end table - -This command is also in the buffer's context menu. - - - -@node Long and Short Display, Regexp Display, Attributes, Member Buffers -@comment node-name, next, previous, up -@section Long and Short Member Display -@cindex display form -@cindex long display -@cindex short display - -@table @kbd -@item D l -This command toggles the member buffer between short and long display -form. The short display form displays member names, only: - -@example -| isEmpty contains hasMember create -| storeSize hash isEqual restoreGuts -| saveGuts -@end example - -The long display shows one member per line with member name and regular -expressions matching the member (if known): - -@example -| isEmpty Bool isEmpty () const... -| hash unsigned hash () const... -| isEqual int isEqual (... -@end example - -Regular expressions will only be displayed when the Lisp database has -not been produced with the @command{ebrowse} option @samp{--no-regexps}. -@xref{Matching, --no-regexps, Regular Expressions}. -@end table - - - - -@node Regexp Display, Switching Classes, Long and Short Display, Member Buffers -@comment node-name, next, previous, up -@section Display of Regular Expressions -@cindex regular expression display - -@table @kbd -@item D r -This command toggles the long display form from displaying the regular -expressions matching the member declarations to those expressions -matching member definitions. -@end table - -Regular expressions will only be displayed when the Lisp database has -not been produced with the @command{ebrowse} option @samp{--no-regexps}, -see @ref{Matching, --no-regexps, Regular Expressions}. - - - - -@node Switching Classes, Killing/Burying, Regexp Display, Member Buffers -@comment node-name, next, previous, up -@section Displaying Another Class -@cindex base class, display -@cindex derived class, display -@cindex superclass, display -@cindex subclass, display -@cindex class display - -@table @kbd -@item C c -This command lets you switch the member buffer to another class. It -reads the name of the new class from the minibuffer with completion. - -@item C b -This is the same command as @kbd{C c} but restricts the classes shown in -the completion list to immediate base classes, only. If only one base -class exists, this one is immediately shown in the minibuffer. - -@item C d -Same as @kbd{C b}, but for derived classes. - -@item C p -Switch to the previous class in the class hierarchy on the same level as -the class currently displayed. - -@item C n -Switch to the next sibling of the class in the class tree. -@end table - - - - -@node Killing/Burying, Column Width, Switching Classes, Member Buffers -@comment node-name, next, previous, up -@section Burying a Member Buffer -@cindex burying member buffers - -@table @kbd -@item q -This command is a synonym for @kbd{M-x bury-buffer}. -@end table - - - - -@node Column Width, Redisplay, Killing/Burying, Member Buffers -@comment node-name, next, previous, up -@section Setting the Column Width -@cindex column width -@cindex member indentation -@cindex indentation, member - -@table @kbd -@item D w -This command sets the column width depending on the display form used -(long or short display). -@end table - - - - -@node Redisplay, Getting Help, Column Width, Member Buffers -@comment node-name, next, previous, up -@section Forced Redisplay -@cindex redisplay of member buffers - -@table @kbd -@item C-l -This command forces a redisplay of the member buffer. If the width -of the window displaying the member buffer is changed this command -redraws the member list with the appropriate column widths and number of -columns. -@end table - - - - -@node Getting Help, , Redisplay, Member Buffers -@comment node-name, next, previous, up -@cindex help - -@table @kbd -@item ? -This key is bound to @code{describe-mode}. -@end table - - - - -@comment ************************************************************** -@comment *** TAGS LIKE FUNCTIONS -@comment ************************************************************** - -@node Tags-like Functions, GNU Free Documentation License, Member Buffers, Top -@comment node-name, next, previous, up -@chapter Tags-like Functions - -Ebrowse provides tags functions similar to those of the standard -Emacs Tags facility, but better suited to the needs of C++ programmers. - -@menu -* Finding and Viewing:: Going to a member declaration/definition -* Position Stack:: Moving to previous locations -* Search & Replace:: Searching and replacing over class tree files -* Members in Files:: Listing all members in a given file -* Apropos:: Listing members matching a regular expression -* Symbol Completion:: Completing names while editing -* Member Buffer Display:: Quickly display a member buffer for some - identifier -@end menu - - - -@node Finding and Viewing, Position Stack, Tags-like Functions, Tags-like Functions -@comment node-name, next, previous, up -@section Finding and Viewing Members -@cindex finding class member, in C++ source -@cindex viewing class member, in C++ source -@cindex tags -@cindex member definition, finding, in C++ source -@cindex member declaration, finding, in C++ source - -The functions in this section are similar to those described in -@ref{Source Display}, and also in @ref{Finding/Viewing}, except that -they work in a C++ source buffer, not in member and tree buffers created -by Ebrowse. - -@table @kbd -@item C-c C-m f -Find the definition of the member around point. If you invoke this -function with a prefix argument, the declaration is searched. - -If more than one class contains a member with the given name you can -select the class with completion. If there is a scope declaration in -front of the member name, this class name is used as initial input for -the completion. - -@item C-c C-m F -Find the declaration of the member around point. - -@item C-c C-m v -View the definition of the member around point. - -@item C-c C-m V -View the declaration of the member around point. - -@item C-c C-m 4 f -Find a member's definition in another window. - -@item C-c C-m 4 F -Find a member's declaration in another window. - -@item C-c C-m 4 v -View a member's definition in another window. - -@item C-c C-m 4 V -View a member's declaration in another window. - -@item C-c C-m 5 f -Find a member's definition in another frame. - -@item C-c C-m 5 F -Find a member's declaration in another frame. - -@item C-c C-m 5 v -View a member's definition in another frame. - -@item C-c C-m 5 V -View a member's declaration in another frame. -@end table - - - -@node Position Stack, Search & Replace, Finding and Viewing, Tags-like Functions -@comment node-name, next, previous, up -@section The Position Stack -@cindex position stack - -When jumping to a member declaration or definition with one of -Ebrowse's commands, the position from where you performed the -jump and the position where you jumped to are recorded in a -@dfn{position stack}. There are several ways in which you can quickly -move to positions in the stack:@refill - -@table @kbd -@cindex return to original position -@item C-c C-m - -This command sets point to the previous position in the position stack. -Directly after you performed a jump, this will put you back to the -position where you came from. - -The stack is not popped, i.e.@: you can always switch back and forth -between positions in the stack. To avoid letting the stack grow to -infinite size there is a maximum number of positions defined. When this -number is reached, older positions are discarded when new positions are -pushed on the stack. - -@item C-c C-m + -This command moves forward in the position stack, setting point to -the next position stored in the position stack. - -@item C-c C-m p -Displays an electric buffer showing all positions saved in the stack. -You can select a position by pressing @kbd{SPC} in a line. You can -view a position with @kbd{v}. -@end table - - - - -@node Search & Replace, Members in Files, Position Stack, Tags-like Functions -@comment node-name, next, previous, up -@section Searching and Replacing -@cindex searching multiple C++ files -@cindex replacing in multiple C++ files -@cindex restart tags-operation - -Ebrowse allows you to perform operations on all or a subset of the files -mentioned in a class tree. When you invoke one of the following -functions and more than one class tree is loaded, you must choose a -class tree to use from an electric tree menu. If the selected tree -contains marked classes, the following commands operate on the files -mentioned in the marked classes only. Otherwise all files in the class -tree are used. - -@table @kbd -@item C-c C-m s -This function performs a regular expression search in the chosen set of -files. - -@item C-c C-m u -This command performs a search for calls of a given member which is -selected in the usual way with completion. - -@item C-c C-m % -Perform a query replace over the set of files. - -@item C-c C-m , -All three operations above stop when finding a match. You can restart -the operation with this command. - -@item C-c C-m n -This restarts the last tags operation with the next file in the list. -@end table - - - - -@node Members in Files, Apropos, Search & Replace, Tags-like Functions -@comment node-name, next, previous, up -@section Members in Files -@cindex files -@cindex members in file, listing -@cindex list class members in a file -@cindex file, members - -The command @kbd{C-c C-m l}, lists all members in a given file. The file -name is read from the minibuffer with completion. - - - - -@node Apropos, Symbol Completion, Members in Files, Tags-like Functions -@comment node-name, next, previous, up -@section Member Apropos -@cindex apropos on class members -@cindex members, matching regexp - -The command @kbd{C-c C-m a} can be used to display all members matching a -given regular expression. This command can be very useful if you -remember only part of a member name, and not its beginning. - -A special buffer is popped up containing all identifiers matching the -regular expression, and what kind of symbol it is (e.g.@: a member -function, or a type). You can then switch to this buffer, and use the -command @kbd{C-c C-m f}, for example, to jump to a specific member. - - - - -@node Symbol Completion, Member Buffer Display, Apropos, Tags-like Functions -@comment node-name, next, previous, up -@section Symbol Completion -@cindex completion -@cindex symbol completion - -The command @kbd{C-c C-m @key{TAB}} completes the symbol in front of point. - - - - -@node Member Buffer Display, , Symbol Completion, Tags-like Functions -@section Quick Member Display -@cindex member buffer, for member at point - -You can quickly display a member buffer containing the member the cursor -in on with the command @kbd{C-c C-m m}. - - -@node GNU Free Documentation License, Concept Index, Tags-like Functions, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Concept Index, , GNU Free Documentation License, Top -@unnumbered Concept Index -@printindex cp - -@bye diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi deleted file mode 100644 index f7e39b6c65c..00000000000 --- a/doc/misc/ede.texi +++ /dev/null @@ -1,3792 +0,0 @@ -\input texinfo -@setfilename ../../info/ede -@settitle Emacs Development Environment - -@copying -This file describes EDE, the Emacs Development Environment. - -Copyright @copyright{} 1998-2001, 2004-2005, 2008-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* EDE: (ede). The Emacs Development Environment. -@end direntry - -@titlepage -@center @titlefont{EDE (The Emacs Development Environment)} -@sp 4 -@center by Eric Ludlam -@end titlepage -@page - -@macro cedet{} -@i{CEDET} -@end macro - -@macro semantic{} -@i{Semantic} -@end macro - -@macro srecode{} -@i{SRecode} -@end macro - -@macro eieio{} -@i{EIEIO} -@end macro - -@macro ede{} -@i{EDE} -@end macro - -@macro cogre{} -@i{COGRE} -@end macro - -@macro speedbar{} -@i{Speedbar} -@end macro - -@contents - -@node top, EDE Project Concepts, (dir), (dir) -@top EDE -@comment node-name, next, previous, up - -@ede{} is the Emacs Development Environment: an Emacs extension that -simplifies building and debugging programs in Emacs. It attempts to -emulate a typical IDE (Integrated Development Environment). @ede{} -can manage or create your makefiles and other building environment -duties, allowing you to concentrate on writing code rather than -support files. It aims to make it much easier for new programmers to -learn and adopt GNU ways of doing things. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* EDE Project Concepts:: @ede{} Project Concepts -* EDE Mode:: Turning on @ede{} mode. -* Creating a project:: Creating a project. -* Modifying your project:: Adding and removing files and targets. -* Building and Debugging:: Initiating a build or debug session. -* Miscellaneous commands:: Other project related commands. -* Simple projects:: Projects not managed by @ede{}. -* Extending EDE:: Programming and extending @ede{}. -@end menu - -@node EDE Project Concepts, EDE Mode, top, top -@chapter @ede{} Project Concepts - -@ede{} is a generic interface for managing projects. It specifies a -single set of menus and keybindings, while supporting multiple ways to -express a project via a build system. - -In the subsequent chapters, we will describe the different project -types (@pxref{Creating a project}), as well as the commands to build -and debug projects (@pxref{Building and Debugging}). - -In @ede{}, a project hierarchy matches a directory hierarchy. The -project's topmost directory is called the @dfn{project root}, and its -subdirectories are @dfn{subprojects}. - -Each project can contain multiple @dfn{targets}. A target, at the -simplest level, is a named collection of files within a project. A -target can specify two different types of information: - -@enumerate -@item -A collection of files to be added to a distribution (e.g., a tarball -that you intend to distribute to others). - -@item -A collection of files that can be built into something else (e.g., a -program or compiled documentation). -@end enumerate - -Lastly, @ede{} provides a way for other tools to easily learn file -associations. For example, a program might need to restrict some sort -of search to files in a single target, or to discover the location of -documentation or interface files. @ede{} can provide this -information. - -@node EDE Mode, Creating a project, EDE Project Concepts, top -@chapter @ede{} Mode - -@ede{} is implemented as a minor mode, which augments other modes such -as C mode, and Texinfo mode. You can enable @ede{} for all buffers by -running the command @code{global-ede-mode}, or by putting this in your -init file: - -@example -(global-ede-mode t) -@end example - -Activating @ede{} adds a menu named @samp{Development} to the menu -bar. This menu provides several menu items for high-level @ede{} -commands. These menu items, and their corresponding keybindings, are -independent of the type of project you are actually working on. - -@node Creating a project, Modifying your project, EDE Mode, top -@chapter Creating a project - -To create a new project, first visit a file that you want to include -in that project. If you have a hierarchy of directories, first visit -a file in the topmost directory. From this buffer, type @kbd{M-x -ede-new}, or click on the @samp{Create Project} item in the -@samp{Development} menu. - -The @command{ede-new} command prompts for the type of project you -would like to create. Each project type has its own benefits or -language specific enhancements. @ede{} supports four different -project types: @samp{Make}, @samp{Automake}, @samp{direct Automake}, -and @samp{Simple}. - -@itemize -@item -For the @samp{Make} project type, @ede{} creates a @dfn{project file}, -called @file{Project.ede}, in each project directory. Information -about the project is stored in this file. This project autogenerates -a @file{Makefile}. - -@item -For the @samp{Automake} project type, @ede{} creates a -@file{Project.ede} project file similar to a @samp{Make} project. -Unlike a @samp{Make} project, this project autogenerates a -@file{Makefile.am} file. @ede{} handles the Automake bootstrapping -routines, which import and maintain a @file{configure.am} script and -other required files. - -@item -For the @samp{direct Automake} project type, @ede{} reads directly -from the Automake files. - -You cannot create direct Automake projects with the @command{ede-new} -command. Instead, when you visit a project with existing Automake -files, @ede{} automatically detects them. - -@item -The @samp{Simple} project type provides light-weight constructs for -identifying a project root and looking up files. If you already have -a non-@ede{} project infrastructure, you can use a @samp{Simple} -project to provide other Emacs packages, such as Semantic, with some -information about the project. @xref{Simple projects}. -@end itemize - -A subproject is merely a project in a subdirectory of another project. -You can create a subproject by using the @command{ede-new} command (or -the @samp{Create Project} menu item), while visiting a buffer in a -subdirectory of the project root. This new project is automatically -added to the parent project, and will be automatically loaded when -@ede{} reads the parent project. - -When using a project command that involves a makefile, @ede{} uses -the top-most project's makefile as a starting place for the build. How -the toplevel project handles subprojects in the build process is -dependent on that project's type. - -@node Modifying your project, Building and Debugging, Creating a project, top -@chapter Modifying your project - -In this chapter, we describe the generic features for manipulating -projects, including the targets and files within them. Subsequent -chapters, which describe specific project types, will provide more -detailed information about exactly what these features do. - -@menu -* Add/Remove target:: -* Add/Remove files:: -* Customize Features:: -* EDE Project Features:: -@end menu - -@node Add/Remove target, Add/Remove files, Modifying your project, Modifying your project -@section Add/Remove target - -To create a new target, type @kbd{C-c . t} (@code{ede-new-target}) or -use the @samp{Add Target} menu item in the @samp{Project Options} -submenu. This prompts for a target name, and adds the current buffer -to that target. - -The @command{ede-new-target} command also prompts for a @dfn{target -type}. Each target type has its own build process and class of files -that it will accept. - -To remove a target from the project, type @kbd{M-x ede-delete-target}, -or use the @samp{Remove Target} menu item in the @samp{Project -Options} submenu. - -@node Add/Remove files, Customize Features, Add/Remove target, Modifying your project -@section Add/Remove files - -To add the current file to an existing target, type @kbd{C-c . a} -(@code{ede-add-file}), or use the @samp{Add File} menu item in the -@samp{Target Options} submenu. - -You can add a file to more than one target; this is OK. - -To remove the current file from a target, type @kbd{C-c . d} -(@code{ede-remove-file}), or use the @samp{Remove File} menu item -in the @samp{Target Options} submenu. If the file belongs to multiple -targets, this command prompts for each target it could be removed -from. - -While working in a project, if you visit a file that is not part of an -existing target, @ede{} automatically prompts for a target. If you do -not wish to add the file to any target, you can choose @samp{none}. -You can customize this behavior with the variable -@command{ede-auto-add-method}. - -@node Customize Features, EDE Project Features, Add/Remove files, Modifying your project -@section Customize Features - -A project, and its targets, are objects using the @samp{EIEIO} object -system. @xref{Top,,,eieio,EIEIO manual}. These objects have data -fields containing important information related to your work. - -If the high-level functions aren't enough, you can tweak all -user-customizable fields at any time by running the command -@command{customize-project} or @command{customize-target}. This loads -the current project or target into a customization buffer, where you -can tweak individual slots. This is usually necessary for complex -projects. - -Some project modes do not have a project file, but directly read a -Makefile or other existing file. Instead of directly editing the -object, you can edit the file by typing @kbd{C-c . e} -(@code{ede-edit-file-target}). You should ``rescan'' the project -afterwards (@pxref{Miscellaneous commands}). - -@node EDE Project Features, , Customize Features, Modifying your project -@section EDE Project Features - -This section details user facing features of an @ede{} @samp{Make} -style project. An @samp{Automake} project has similar options (but a -direct Automake project does not). - -To modify any of the specific features mentioned here, you need to -customize the project or target with @command{customize-project} or -@command{customize-target}. - -When you are customizing, you are directly manipulating slot values in -@eieio{} objects. @xref{Extending EDE}, if you are interested in -additional details. - -@menu -* Changing Compilers and Flags:: -* Configurations:: -@end menu - -@node Changing Compilers and Flags, Configurations, EDE Project Features, EDE Project Features -@subsection Changing Compilers and Flags - -Targets that build stuff need compilers. To change compilers, you -need to customize the desired target. - -In the @samp{[Make]} section, you can choose a new compiler or linker -from the list. If a linker you need is not available, you will need -to create a new one. @xref{Compiler and Linker objects}. - -If an existing compiler or linker is close, but you need to modify -some flag set such as adding an include path you will need to add a -configuration variable. - -To start, you should create the basic setup, and construct a makefile -with @command{ede-proj-regenerate}. Look in the @file{Makefile} to -see what commands are inserted. Once you have determined the variable -you need to modify, you can add a configuration for it. -@xref{Configurations}. - -@node Configurations, , Changing Compilers and Flags, EDE Project Features -@subsection Configurations - -Configurations specify different ways to build a project. For -example, you may configure a project to be in ``debug'' mode, or -perhaps in ``release'' mode. - -The project, and each target type all have a slot named -@code{configuration-variables}. To add new variables to a -configuration find this slot in the custom buffer, and insert a new -configuration. Name it either ``debug'' or ``release'', then insert -some number of name/value pairs to it. - -You can have any number of valid configurations too. To add a new -configuration, customize your project. Work in the @samp{[Settings]} -block for ``configurations''. Add a new named configuration here. - -To switch between different active configurations, modify the -``configuration default'' slot. - -@node Building and Debugging, Miscellaneous commands, Modifying your project, top -@chapter Building and Debugging - -@ede{} provides the following ``project-aware'' compilation and -debugging commands: - -@table @kbd -@item C-c . c -Compile the current target (@code{ede-compile-target}). -@item C-c . C -Compile the entire project (@code{ede-compile-project}). -@item c-c . D -Debug the current target (@code{ede-debug-target}). -@item M-x ede-make-dist -Build a distribution file for your project. -@end table - -These commands are also available from the @samp{Development} menu. - -@node Miscellaneous commands, Simple projects, Building and Debugging, top -@chapter Miscellaneous commands - -If you opt to go in and edit @ede{} project files directly---for -instance, by using @kbd{C-c . e} (@pxref{Customize Features})---you -must then ``rescan'' the project files to update the internal data -structures. To rescan the current project, type @kbd{C-c . g} -(@code{ede-rescan-toplevel}). - -@ede{} can help you find files in your project, via the command -@kbd{C-c . f} (@code{ede-find-file}). This prompts for a file name; -you need not specify the directory. EDE then tries to visit a file -with that name somewhere in your project. - -@ede{} can use external tools to help with file finding. To do this, -customize @code{ede-locate-setup-options}. - -@defvar ede-locate-setup-options -@anchor{ede-locate-setup-options} -List of locate objects to try out by default. -Listed in order of preference. If the first item cannot be used in -a particular project, then the next one is tried. -It is always assumed that @dfn{ede-locate-base} is at end of the list. -@end defvar - -@ede{} also provides a project display mode for the speedbar -(@pxref{Speedbar,,,emacs,GNU Emacs Manual}). This allows you to view -your source files as they are structured in your project: as a -hierarchical tree, grouped according to target. - -To activate the speedbar in this mode, type @kbd{C-c . s} -(@code{ede-speedbar}). - -@node Simple projects, Extending EDE, Miscellaneous commands, top -@section Simple Projects - -There is a wide array of Simple projects. The root for simple -projects is the class @code{ede-simple-project}. This handles the -infrastructure of storing a .ede file if needed. - -The class @code{ede-simple-project} is designed to be subclassed. -Then key @ede{} methods can be overridden to provide a quick wrapper -over any project. - -A second project type is @code{ede-cpp-root}. This project type is -designed to be created for a directory hierarchy full of C/C++ code. -It can be configured with minimal lisp knowledge to do header file -lookup for @semantic{}, improving code completion performance. - -@menu -* ede-cpp-root:: This project marks the root of a C/C++ code project. -* ede-simple subclassing:: Create your own simple project. -* ede-emacs:: A project for working with Emacs. -* ede-linux:: A project for working with Linux kernels. -* Custom Locate:: Customizing how to locate files in a simple project -@end menu - -@node ede-cpp-root -@subsection ede-cpp-root - -The @code{ede-cpp-root} project type allows you to create a single -object with no save-file in your @file{.emacs} file. It allows @ede{} -to provide the @semantic{} package with the ability to find header -files quickly. - -The @code{ede-cpp-root} class knows a few things about C++ projects, -such as the prevalence of "include" directories, and typical -file-layout stuff. If this isn't sufficient, you can subclass -@code{ede-cpp-root-project} and add your own tweaks in just a few -lines. See the end of this file for an example. - -In the most basic case, add this to your @file{.emacs} file, modifying -appropriate bits as needed. - -@example -(ede-cpp-root-project "SOMENAME" :file "/dir/to/some/file") -@end example - -Replace @var{SOMENAME} with whatever name you want, and the filename -to an actual file at the root of your project. It might be a -Makefile, a README file. Whatever. It doesn't matter. It's just a -key to hang the rest of @ede{} off of. - -The most likely reason to create this project, is to speed up -searching for includes files, or to simplify bootstrapping @semantic{}'s -ability to find files without much user interaction. In conjunction -with @semantic{} completion, having a short include path is key. You can -override the default include path and system include path like this: - -@example -(ede-cpp-root-project "NAME" :file "FILENAME" - :include-path '( "/include" "../include" "/c/include" ) - :system-include-path '( "/usr/include/c++/3.2.2/" ) - :spp-table '( ("MOOSE" . "") - ("CONST" . "const") ) ) -@end example - - In this case each item in the include path list is searched. If the -directory starts with "/", then that expands to the project root -directory. If a directory does not start with "/", then it is -relative to the default-directory of the current buffer when the file -name is expanded. - - The include path only affects C/C++ header files. Use the slot -@code{:header-match-regexp} to change it. - -The @code{:system-include-path} allows you to specify full directory -names to include directories where system header files can be found. -These will be applied to files in this project only. - -The @code{:spp-table} provides a list of project specific #define -style macros that are unique to this project, passed in to the -compiler on the command line, or are in special headers. -See the @code{semantic-lex-c-preprocessor-symbol-map} for more -on how to format this entry. - -If there is a single file in your project, you can instead set the -@code{:spp-files} to a list of file names relative to the root of your -project. Specifying this is like setting the variable -@code{semantic-lex-c-preprocessor-symbol-file} in semantic. - -If you want to override the file-finding tool with your own -function you can do this: - -@example -(ede-cpp-root-project "NAME" :file "FILENAME" :locate-fcn 'MYFCN) -@end example - -Where @var{MYFCN} is a symbol for a function. The locate function can -be used in place of @code{ede-expand-filename} so you can quickly -customize your custom target to use specialized local routines instead -of the default @ede{} routines. The function symbol must take two -arguments: - -@table @var -@item NAME -The name of the file to find. -@item DIR -The directory root for this cpp-root project. -@end table - - -If the cpp-root project style is right for you, but you want a dynamic -loader, instead of hard-coding path name values in your @file{.emacs}, you -can do that too, but you will need to write some lisp code. - -To do that, you need to add an entry to the -@code{ede-project-class-files} list, and also provide two functions to -teach @ede{} how to load your project pattern - -It would look like this: - -@example -(defun MY-FILE-FOR-DIR (&optional dir) - "Return a full file name to the project file stored in DIR." - - ) - -(defun MY-ROOT-FCN () - "Return the root fcn for `default-directory'" - ;; You might be able to use `ede-cpp-root-project-root' - ;; and not write this at all. - ) - -(defun MY-LOAD (dir) - "Load a project of type `cpp-root' for the directory DIR. -Return nil if there isn't one." - ;; Use your preferred construction method here. - (ede-cpp-root-project "NAME" :file (expand-file-name "FILE" dir) - :locate-fcn 'MYFCN) - ) - -(add-to-list 'ede-project-class-files - (ede-project-autoload "cpp-root" - :name "CPP ROOT" - :file 'ede-cpp-root - :proj-file 'MY-FILE-FOR-DIR - :proj-root 'MY-ROOT-FCN - :load-type 'MY-LOAD - :class-sym 'ede-cpp-root) - t) -@end example - -This example only creates an auto-loader, and does not create a new kind -of project. - -@xref{ede-cpp-root-project}, for details about the class that defines -the @code{ede-cpp-root} project type. - -@node ede-simple subclassing -@subsection ede-simple Subclassing - -todo - Write some doc. - - In the meantime look in the commentary of ede-simple.el - -@node ede-emacs -@subsection ede-emacs - -The @code{ede-emacs} project automatically identifies an Emacs source -tree, and enables EDE project mode for it. - -It pre-populates the C Preprocessor symbol map for correct parsing, -and has an optimized include file identification function. - -@node ede-linux -@subsection ede-linux - -The @code{ede-linux} project will automatically identify a Linux -Kernel source tree, and enable EDE project mode for it. - -It pre-populates the C Preprocessor symbol map for reasonable parsing, -and has an optimized include file identification function. - -@node Custom Locate -@subsection Custom Locate - -The various simple project styles all have one major drawback, which -is that the files in the project are not completely known to EDE. -When the EDE API is used to try and file files by some reference name -in the project, then that could fail. - -@@TODO - Add ID Utils and CScope examples - -@ede{} can therefore use some external locate commands, such as the unix -``locate'' command, or ``GNU Global''. - -Configuration of the tool you want to use such as @code{locate}, or -@code{global} will need to be done without the aid of @ede{}. Once -configured, however, @ede{} can use it. - -To enable one of these tools, set the variable -@code{ede-locate-setup-options} with the names of different locate -objects. @ref{Miscellaneous commands}. - -Configure this in your @file{.emacs} before loading in CEDET or EDE. -If you want to add support for GNU Global, your configuration would -look like this: - -@example -(setq ede-locate-setup-options '(ede-locate-global ede-locate-base)) -@end example - -That way, when a search needs to be done, it will first try using -GLOBAL. If global is not available for that directory, then it will -revert to the base locate object. The base object always fails to -find a file. - -You can add your own locate tool but subclassing from -@code{ede-locate-base}. The subclass should also implement two -methods. See the code in @file{ede-locate.el} for GNU Global as a -simple example. - -@node Extending EDE, , Simple projects, top -@chapter Extending @ede{} - -This chapter is intended for users who want to write new parts or fix -bugs in @ede{}. A knowledge of Emacs Lisp, and some @eieio{}(CLOS) is -required. - -@ede{} uses @eieio{}, the CLOS package for Emacs, to define two object -superclasses, specifically the PROJECT and TARGET. All commands in -@ede{} are usually meant to address the current project, or current -target. - -All specific projects in @ede{} derive subclasses of the @ede{} -superclasses. In this way, specific behaviors such as how a project -is saved, or how a target is compiled can be customized by a project -author in detail. @ede{} communicates to these project objects via an -API using methods. The commands you use in @ede{} mode are high-level -functional wrappers over these methods. @xref{(eieio)Top}. For -details on using @eieio{} to extending classes, and writing methods. - -If you intend to extend @ede{}, it is most likely that a new target type is -needed in one of the existing project types. The rest of this chapter -will discuss extending the @code{ede-project} class, and it's targets. -See @file{project-am.el} for basic details on adding targets to it. - -For the @code{ede-project} type, the core target class is called -@code{ede-proj-target}. Inheriting from this will give you everything -you need to start, including adding your sources into the makefile. If -you also need additional rules in the makefile, you will want to inherit -from @code{ede-proj-target-makefile} instead. You may want to also add -new fields to track important information. - -If you are building currently unsupported code into a program or shared -library, it is unlikely you need a new target at all. Instead you -would need to create a new compiler or linker object that compiles -source code of the desired type. @ref{Compiler and Linker objects}. - -Once your new class exists, you will want to fill in some basic methods. -See the @file{ede-skel.el} file for examples of these. The files -@file{ede-proj-info.el} and @file{ede-proj-elisp.el} are two interesting -examples. - -@menu -* User interface methods:: Methods associated with keybindings -* Base project methods:: The most basic methods on @ede{} objects. -* Sourcecode objects:: Defining new sourcecode classes. -* Compiler and Linker objects:: Defining new compilers and linkers. -* Project:: Details of project classes. -* Targets:: Details of target classes. -* Sourcecode:: Details of source code classes. -* Compilers:: Details of compiler classes. -@end menu - -@node User interface methods -@section User interface methods - -These methods are core behaviors associated with user commands. -If you do not implement a method, there is a reasonable default that -may do what you need. - -@table @code -@item project-add-file -Add a file to your project. Override this if you want to put new -sources into different fields depending on extension, or other details. -@item project-remove-file -Reverse of project-add-file. -@item project-compile-target -Override this if you want to do something special when the user -"compiles" this target. -@item project-debug-target -What to do when a user wants to debug your target. -@item project-update-version -Easily update the version number of your project. -@item project-edit-file-target -Edit the file the project's information is stored in. -@item project-new-target -Create a new target in a project. -@item project-delete-target -Delete a target from a project. -@item project-make-dist -Make a distribution (tar archive) of the project. -@item project-rescan -Rescan a project file, changing the data in the existing objects. -@end table - -@node Base project methods -@section Base project methods - -These methods are important for querying base information from project -and target types: - -@table @code -@item ede-name -Return a string that is the name of this target. -@item ede-target-name -Return a string that is the name of the target used by a Make system. -@item ede-description -A brief description of the project or target. This is currently used -by the @samp{ede-speedbar} interface. -@item ede-want-file-p -Return non-nil if a target will accept a given file. -It is generally unnecessary to override this. See the section on source -code. -@item ede-buffer-mine -Return non-nil if a buffer belongs to this target. Used during -association when a file is loaded. It is generally unnecessary to -override this unless you keep auxiliary files. -@end table - -These methods are used by the semantic package extensions @xref{(semantic)Top}. - -@table @code -@item ede-buffer-header-file -Return a header file belonging to a given buffer. Prototypes are place -there when appropriate -@item ede-buffer-documentation-files -Return the documentation file information about this file would be -stored in. -@item ede-documentation -List all documentation a project or target is responsible for. -@end table - -@node Sourcecode objects -@section Sourcecode objects - -@ede{} projects track source file / target associates via source code -objects. The definitions for this is in @file{ede-source.el}. A source -code object contains methods that know how to identify a file as being -of that class, (ie, a C file ends with @file{.c}). Some targets can -handle many different types of sources which must all be compiled -together. For example, a mixed C and C++ program would have -instantiations of both sourcecode types. - -When a target needs to know if it will accept a source file, it -references its list of source code objects. These objects then make -that decision. - -Source code objects are stored in the target objects as a list of -symbols, where the symbol's value is the object. This enables the -project save file mechanism to work. - -Here is an example for an instantiation of an Emacs Lisp source code object: - -@example -(defvar ede-source-emacs - (ede-sourcecode "ede-emacs-source" - :name "Emacs Lisp" - :sourcepattern "\\.el$" - :garbagepattern '("*.elc")) - "Emacs Lisp source code definition.") -@end example - -If you want to recycle parts of an existing sourcecode object, you can -clone the original, and then just tweak the parts that are different. -For example: - -@example -(defvar ede-source-emacs-autoload - (clone ede-source-emacs "ede-source-emacs-autoload" - :name "Emacs Lisp Autoload" - :sourcepattern "-loaddefs\\.el") - "Emacs Lisp autoload source code.") -@end example - -In this case, the garbage pattern is the same. - -@xref{Sourcecode}. - -@node Compiler and Linker objects -@section Compiler and Linker objects - -In order for a target to create a @file{Makefile}, it must know how to -compile the sources into the program or desired data file, and -possibly link them together. - -A compiler object instantiation is used to associate a given target -with a given source code type. Some targets can handle many types of -sources, and thus has many compilers available to it. Some targets -may have multiple compilers for a given type of source code. - -@ede{} will examine the actual source files in a target, cross reference -that against the compiler list to come up with the final set of -compilers that will be inserted into the Makefile. - -Compiler instantiations must also insert variables specifying the -compiler it plans to use, in addition to creating Automake settings for -@file{configure.in} when appropriate. - -Compiler objects are stored in the target objects as a list of -symbols, where the symbols value is the object. This enables the -project output mechanism to work more efficiently. - -Targets will also have a special "compiler" slot which lets a user -explicitly choose the compiler they want to use. - -Here is an example for texinfo: - -@example -(defvar ede-makeinfo-compiler - (ede-compiler - "ede-makeinfo-compiler" - :name "makeinfo" - :variables '(("MAKEINFO" . "makeinfo")) - :commands '("makeinfo -o $@ $<") - :autoconf '(("AC_CHECK_PROG" . "MAKEINFO, makeinfo")) - :sourcetype '(ede-makeinfo-source) - ) - "Compile texinfo files into info files.") -@end example - -@xref{Compilers}. - -When creating compiler instantiations, it may be useful to @code{clone} -an existing compiler variable. Cloning allows you to only modify -parts of the original, while keeping the rest of the same. -Modification of the original will result in the clone also being -changed for shared value slots. - -The second important object is the linker class. The linker is similar -to the compiler, except several compilers might be used to create some -object files, and only one linker is used to link those objects together. - -See @file{ede-proj-obj.el} for examples of the combination. - -@defindex pj -@defindex tg -@defindex sc -@defindex cm - -@node Project -@section Project - -@menu -* ede-project-placeholder :: -* ede-project :: -* ede-cpp-root-project :: -* ede-simple-project :: -* ede-simple-base-project :: -* ede-proj-project :: -* project-am-makefile :: -* ede-step-project :: -@end menu - -@node ede-project-placeholder -@subsection ede-project-placeholder -@pjindex ede-project-placeholder - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item ede-project-placeholder -@table @asis -@item Children: -@w{@xref{ede-project}.} -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :name -Type: @code{string} @* -Default Value: @code{"Untitled"} - -The name used when generating distribution files. -@refill - -@item :version -Type: @code{string} @* -Default Value: @code{"1.0"} - -The version number used when distributing files. -@refill - -@item :directory -Type: @code{string} - -Directory this project is associated with. -@refill - -@item :file -Type: @code{string} - -File name where this project is stored. -@refill - -@end table - -@end table - -@subsubsection Specialized Methods - -@deffn Method ede--project-inode :AFTER proj -Get the inode of the directory project @var{PROJ} is in. -@end deffn - -@deffn Method ede-project-root :AFTER this -If a project knows it's root, return it here. -Allows for one-project-object-for-a-tree type systems. -@end deffn - -@deffn Method ede-find-subproject-for-directory :AFTER proj dir -Find a subproject of @var{PROJ} that corresponds to @var{DIR}. -@end deffn - -@deffn Method ede-project-root-directory :AFTER this &optional file -If a project knows it's root, return it here. -Allows for one-project-object-for-a-tree type systems. -Optional @var{FILE} is the file to test. It is ignored in preference -of the anchor file for the project. -@end deffn - -@deffn Method ede-project-force-load :AFTER this -Make sure the placeholder @var{THIS} is replaced with the real thing. -Return the new object created in its place. -@end deffn - -@deffn Method project-interactive-select-target :AFTER this prompt -Make sure placeholder @var{THIS} is replaced with the real thing, and pass through. -@end deffn - -@deffn Method project-add-file :AFTER this file -Make sure placeholder @var{THIS} is replaced with the real thing, and pass through. -@end deffn - -@node ede-project -@subsection ede-project -@pjindex ede-project - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item ede-project -@table @asis -@item Children: -@w{@xref{ede-cpp-root-project},} @w{ede-emacs-project,} @w{ede-linux-project,} @w{ede-maven-project,} @w{@xref{ede-simple-project},} @w{@xref{ede-simple-base-project},} @w{@xref{ede-proj-project},} @w{@xref{project-am-makefile},} @w{@xref{ede-step-project}.} -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :targets -Type: @code{list} - -List of top level targets in this project. -@refill - -@item :tool-cache -Type: @code{list} - -List of tool cache configurations in this project. -This allows any tool to create, manage, and persist project-specific settings. -@refill - -@item :web-site-url -Type: @code{string} @* - -URL to this projects web site. -This is a URL to be sent to a web site for documentation. -@refill - -@item :web-site-directory @* - -A directory where web pages can be found by Emacs. -For remote locations use a path compatible with ange-ftp or EFS. -You can also use TRAMP for use with rcp & scp. -@refill - -@item :web-site-file @* - -A file which contains the home page for this project. -This file can be relative to slot @code{web-site-directory}. -This can be a local file, use ange-ftp, EFS, or TRAMP. -@refill - -@item :ftp-site -Type: @code{string} @* - -FTP site where this project's distribution can be found. -This FTP site should be in Emacs form, as needed by @code{ange-ftp}, but can -also be of a form used by TRAMP for use with scp, or rcp. -@refill - -@item :ftp-upload-site -Type: @code{string} @* - -FTP Site to upload new distributions to. -This FTP site should be in Emacs form as needed by @code{ange-ftp}. -If this slot is @code{nil}, then use @code{ftp-site} instead. -@refill - -@item :configurations -Type: @code{list} @* -Default Value: @code{("debug" "release")} - -List of available configuration types. -Individual target/project types can form associations between a configuration, -and target specific elements such as build variables. -@refill - -@item :configuration-default @* -Default Value: @code{"debug"} - -The default configuration. -@refill - -@item :local-variables @* -Default Value: @code{nil} - -Project local variables -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-preprocessor-map :AFTER this -Get the pre-processor map for project @var{THIS}. -@end deffn - -@deffn Method ede-subproject-relative-path :AFTER proj &optional parent-in -Get a path name for @var{PROJ} which is relative to the parent project. -If PARENT is specified, then be relative to the PARENT project. -Specifying PARENT is useful for sub-sub projects relative to the root project. -@end deffn - -@deffn Method eieio-speedbar-description :AFTER obj -Provide a speedbar description for @var{OBJ}. -@end deffn - -@deffn Method ede-map-any-target-p :AFTER this proc -For project @var{THIS}, map @var{PROC} to all targets and return if any non-nil. -Return the first non-@code{nil} value returned by @var{PROC}. -@end deffn - -@deffn Method ede-map-subprojects :AFTER this proc -For object @var{THIS}, execute @var{PROC} on all direct subprojects. -This function does not apply @var{PROC} to sub-sub projects. -See also @dfn{ede-map-all-subprojects}. -@end deffn - -@deffn Method ede-convert-path :AFTER this path -Convert path in a standard way for a given project. -Default to making it project relative. -Argument @var{THIS} is the project to convert @var{PATH} to. -@end deffn - -@deffn Method ede-name :AFTER this -Return a short-name for @var{THIS} project file. -Do this by extracting the lowest directory name. -@end deffn - -@deffn Method ede-set-project-variables :AFTER project &optional buffer -Set variables local to @var{PROJECT} in @var{BUFFER}. -@end deffn - -@deffn Method eieio-speedbar-derive-line-path :AFTER obj &optional depth -Return the path to @var{OBJ}. -Optional @var{DEPTH} is the depth we start at. -@end deffn - -@deffn Method ede-map-all-subprojects :AFTER this allproc -For object @var{THIS}, execute PROC on @var{THIS} and all subprojects. -This function also applies PROC to sub-sub projects. -See also @dfn{ede-map-subprojects}. -@end deffn - -@deffn Method project-update-version :AFTER ot -The @code{:version} of the project @var{OT} has been updated. -Handle saving, or other detail. -@end deffn - -@deffn Method ede-buffer-header-file :AFTER this buffer -Return @code{nil}, projects don't have header files. -@end deffn - -@deffn Method ede-buffer-documentation-files :AFTER this buffer -Return all documentation in project @var{THIS} based on @var{BUFFER}. -@end deffn - -@deffn Method ede-map-targets :AFTER this proc -For object @var{THIS}, execute @var{PROC} on all targets. -@end deffn - -@deffn Method ede-buffer-mine :AFTER this buffer -Return non-@code{nil} if object @var{THIS} lays claim to the file in @var{BUFFER}. -@end deffn - -@deffn Method ede-object-keybindings :BEFORE this -Retrieves the slot @code{keybindings} from an object of class @code{ede-project} -@end deffn - -@deffn Method ede-description :AFTER this -Return a description suitable for the minibuffer about @var{THIS}. -@end deffn - -@deffn Method eieio-speedbar-object-children :AFTER this -Return the list of speedbar display children for @var{THIS}. -@end deffn - -@deffn Method project-make-dist :AFTER this -Build a distribution for the project based on @var{THIS} project. -@end deffn - -@deffn Method ede-system-include-path :AFTER this -Get the system include path used by project @var{THIS}. -@end deffn - -@deffn Method project-new-target-custom :AFTER proj -Create a new target. It is up to the project @var{PROJ} to get the name. -@end deffn - -@deffn Method ede-subproject-p :AFTER proj -Return non-@code{nil} if @var{PROJ} is a sub project. -@end deffn - -@deffn Method ede-expand-filename :AFTER this filename &optional force -Return a fully qualified file name based on project @var{THIS}. -@var{FILENAME} should be just a filename which occurs in a directory controlled -by this project. -Optional argument @var{FORCE} forces the default filename to be provided even if it -doesn't exist. -@end deffn - -@deffn Method ede-menu-items-build :AFTER obj &optional current -Return a list of menu items for building project @var{OBJ}. -If optional argument @var{CURRENT} is non-@code{nil}, return sub-menu code. -@end deffn - -@deffn Method ede-update-version-in-source :AFTER this version -Change occurrences of a version string in sources. -In project @var{THIS}, cycle over all targets to give them a chance to set -their sources to @var{VERSION}. -@end deffn - -@deffn Method project-new-target :AFTER proj &rest args -Create a new target. It is up to the project @var{PROJ} to get the name. -@end deffn - -@deffn Method project-compile-project :AFTER obj &optional command -Compile the entire current project @var{OBJ}. -Argument @var{COMMAND} is the command to use when compiling. -@end deffn - -@deffn Method eieio-speedbar-object-buttonname :AFTER object -Return a string to use as a speedbar button for @var{OBJECT}. -@end deffn - -@deffn Method ede-map-project-buffers :AFTER this proc -For @var{THIS}, execute @var{PROC} on all buffers belonging to @var{THIS}. -@end deffn - -@deffn Method ede-expand-filename-impl :AFTER this filename &optional force -Return a fully qualified file name based on project @var{THIS}. -@var{FILENAME} should be just a filename which occurs in a directory controlled -by this project. -Optional argument @var{FORCE} forces the default filename to be provided even if it -doesn't exist. -@end deffn - -@deffn Method eieio-done-customizing :AFTER proj -Call this when a user finishes customizing @var{PROJ}. -@end deffn - -@deffn Method ede-html-documentation :AFTER this -Return a list of HTML files provided by project @var{THIS}. -@end deffn - -@deffn Method ede-documentation :AFTER this -Return a list of files that provides documentation. -Documentation is not for object @var{THIS}, but is provided by @var{THIS} for other -files in the project. -@end deffn - -@deffn Method project-interactive-select-target :AFTER this prompt -Interactively query for a target that exists in project @var{THIS}. -Argument @var{PROMPT} is the prompt to use when querying the user for a target. -@end deffn - -@deffn Method ede-target-in-project-p :AFTER proj target -Is @var{PROJ} the parent of @var{TARGET}? -If @var{TARGET} belongs to a subproject, return that project file. -@end deffn - -@deffn Method ede-find-target :AFTER proj buffer -Fetch the target in @var{PROJ} belonging to @var{BUFFER} or nil. -@end deffn - -@deffn Method ede-add-subproject :AFTER proj-a proj-b -Add into @var{PROJ-A}, the subproject @var{PROJ-B}. -@end deffn - -@deffn Method ede-commit-project :AFTER proj -Commit any change to @var{PROJ} to its file. -@end deffn - -@deffn Method project-dist-files :AFTER this -Return a list of files that constitutes a distribution of @var{THIS} project. -@end deffn - -@deffn Method ede-object-menu :BEFORE this -Retrieves the slot @code{menu} from an object of class @code{ede-project} -@end deffn - -@deffn Method ede-commit-local-variables :AFTER proj -Commit change to local variables in @var{PROJ}. -@end deffn - -@node ede-cpp-root-project -@subsection ede-cpp-root-project -@pjindex ede-cpp-root-project - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item @w{@xref{ede-project}.} -@table @code -@item ede-cpp-root-project -No children -@end table -@end table -@end table -@end table -@end table -@end table - -This class implements the @code{ede-cpp-root} project type. -@xref{ede-cpp-root}, for information about using this project type. - -@table @asis -@item Slots: - -@table @code -@item :include-path -Type: @code{list} @* -Default Value: @code{(quote ("/include" "../include/"))} - -The default locate function expands filenames within a project. -If a header file (.h, .hh, etc) name is expanded, and -the @code{:locate-fcn} slot is @code{nil}, then the include path is checked -first, and other directories are ignored. For very large -projects, this optimization can save a lot of time. - -Directory names in the path can be relative to the current -buffer's @code{default-directory} (not starting with a /). Directories -that are relative to the project's root should start with a /, such -as "/include", meaning the directory @code{include} off the project root -directory. -@refill - -@item :system-include-path -Type: @code{list} @* -Default Value: @code{nil} - -The system include path for files in this project. -C files initialized in an ede-cpp-root-project have their semantic -system include path set to this value. If this is @code{nil}, then the -semantic path is not modified. -@refill - -@item :spp-table -Type: @code{list} @* -Default Value: @code{nil} - -C Preprocessor macros for your files. -Preprocessor symbols will be used while parsing your files. -These macros might be passed in through the command line compiler, or -are critical symbols derived from header files. Providing header files -macro values through this slot improves accuracy and performance. -Use `:spp-files' to use these files directly. -@refill - -@item :spp-files -Type: @code{list} @* -Default Value: @code{nil} - -C header file with Preprocessor macros for your files. -The PreProcessor symbols appearing in these files will be used while -parsing files in this project. -See @code{semantic-lex-c-preprocessor-symbol-map} for more on how this works. -@refill - -@item :header-match-regexp -Type: @code{string} @* -Default Value: @code{"\\.\\(h\\(h\\|xx\\|pp\\|\\+\\+\\)?\\|H\\)$\\|\\<\\w+$"} - -Regexp used to identify C/C++ header files. -@refill - -@item :locate-fcn -Type: @code{(or null function)} @* -Default Value: @code{nil} - -The locate function can be used in place of -@dfn{ede-expand-filename} so you can quickly customize your custom target -to use specialized local routines instead of the EDE routines. -The function symbol must take two arguments: - NAME - The name of the file to find. - DIR - The directory root for this cpp-root project. - -It should return the fully qualified file name passed in from NAME. If that file does not -exist, it should return nil. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method initialize-instance :AFTER this &rest fields -Make sure the @code{:file} is fully expanded. -@end deffn - -@deffn Method ede-preprocessor-map :AFTER this -Get the pre-processor map for project @var{THIS}. -@end deffn - -@deffn Method ede-cpp-root-header-file-p :AFTER proj name -Non @code{nil} if in @var{PROJ} the filename @var{NAME} is a header. -@end deffn - -@deffn Method ede-system-include-path :AFTER this -Get the system include path used by project @var{THIS}. -@end deffn - -@deffn Method ede-expand-filename-impl :AFTER proj name -Within this project @var{PROJ}, find the file @var{NAME}. -This knows details about or source tree. -@end deffn - -@node ede-simple-project -@subsection ede-simple-project -@pjindex ede-simple-project - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item @w{@xref{ede-project}.} -@table @code -@item ede-simple-project -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method ede-commit-project :AFTER proj -Commit any change to @var{PROJ} to its file. -@end deffn - -@node ede-simple-base-project -@subsection ede-simple-base-project -@pjindex ede-simple-base-project - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item @w{@xref{ede-project}.} -@table @code -@item ede-simple-base-project -No children -@end table -@end table -@end table -@end table -@end table -@end table - - EDE Simple project base class. -This one project could control a tree of subdirectories. - -@table @asis -@end table - -@node ede-proj-project -@subsection ede-proj-project -@pjindex ede-proj-project - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item @w{@xref{ede-project}.} -@table @code -@item ede-proj-project -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :makefile-type -Type: @code{symbol} @* -Default Value: @code{Makefile} - -The type of Makefile to generate. -Can be one of @code{'Makefile}, 'Makefile.in, or 'Makefile.am. -If this value is NOT @code{'Makefile}, then that overrides the @code{:makefile} slot -in targets. -@refill - -@item :variables -Type: @code{list} @* -Default Value: @code{nil} - -Variables to set in this Makefile. -@refill - -@item :configuration-variables -Type: @code{list} @* -Default Value: @code{("debug" (("DEBUG" . "1")))} - -Makefile variables to use in different configurations. -These variables are used in the makefile when a configuration becomes active. -@refill - -@item :inference-rules @* -Default Value: @code{nil} - -Inference rules to add to the makefile. -@refill - -@item :include-file @* -Default Value: @code{nil} - -Additional files to include. -These files can contain additional rules, variables, and customizations. -@refill - -@item :automatic-dependencies -Type: @code{boolean} @* -Default Value: @code{t} - -Non-@code{nil} to do implement automatic dependencies in the Makefile. -@refill - -@item :metasubproject -Type: @code{boolean} @* -Default Value: @code{nil} - -Non-@code{nil} if this is a metasubproject. -Usually, a subproject is determined by a parent project. If multiple top level -projects are grouped into a large project not maintained by EDE, then you need -to set this to non-nil. The only effect is that the @code{dist} rule will then avoid -making a tar file. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-create :AFTER this mfilename -Create a Makefile for all Makefile targets in @var{THIS}. -@var{MFILENAME} is the makefile to generate. -@end deffn - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Insert rules needed by @var{THIS} target. -@end deffn - -@deffn Method ede-proj-makefile-tags :AFTER this targets -Insert into the current location rules to make recursive TAGS files. -Argument @var{THIS} is the project to create tags for. -Argument @var{TARGETS} are the targets we should depend on for TAGS. -@end deffn - -@deffn Method ede-proj-makefile-insert-variables :AFTER this -Insert variables needed by target @var{THIS}. -@end deffn - -@deffn Method project-make-dist :AFTER this -Build a distribution for the project based on @var{THIS} target. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-rules :AFTER this -Insert distribution rules for @var{THIS} in a Makefile, such as CLEAN and DIST. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-dependencies :AFTER this -Insert any symbols that the DIST rule should depend on. -Argument @var{THIS} is the project that should insert stuff. -@end deffn - -@deffn Method ede-proj-makefile-insert-subproj-rules :AFTER this -Insert a rule for the project @var{THIS} which should be a subproject. -@end deffn - -@deffn Method ede-proj-makefile-create-maybe :AFTER this mfilename -Create a Makefile for all Makefile targets in @var{THIS} if needed. -@var{MFILENAME} is the makefile to generate. -@end deffn - -@deffn Method ede-proj-configure-test-required-file :AFTER this file -For project @var{THIS}, test that the file @var{FILE} exists, or create it. -@end deffn - -@deffn Method ede-proj-setup-buildenvironment :AFTER this &optional force -Setup the build environment for project @var{THIS}. -Handles the Makefile, or a Makefile.am configure.in combination. -Optional argument @var{FORCE} will force items to be regenerated. -@end deffn - -@deffn Method ede-proj-makefile-garbage-patterns :AFTER this -Return a list of patterns that are considered garbage to @var{THIS}. -These are removed with make clean. -@end deffn - -@deffn Method ede-proj-configure-synchronize :AFTER this -Synchronize what we know about project @var{THIS} into configure.in. -@end deffn - -@deffn Method ede-proj-makefile-insert-variables-new :AFTER this -Insert variables needed by target @var{THIS}. - -NOTE: Not yet in use! This is part of an SRecode conversion of - EDE that is in progress. -@end deffn - -@deffn Method ede-proj-makefile-configuration-variables :AFTER this configuration -Return a list of configuration variables from @var{THIS}. -Use @var{CONFIGURATION} as the current configuration to query. -@end deffn - -@deffn Method eieio-done-customizing :AFTER proj -Call this when a user finishes customizing this object. -Argument @var{PROJ} is the project to save. -@end deffn - -@deffn Method ede-proj-configure-recreate :AFTER this -Delete project @var{THIS}'s configure script and start over. -@end deffn - -@deffn Method ede-proj-makefile-insert-user-rules :AFTER this -Insert user specified rules needed by @var{THIS} target. -This is different from @dfn{ede-proj-makefile-insert-rules} in that this -function won't create the building rules which are auto created with -automake. -@end deffn - -@deffn Method ede-proj-dist-makefile :AFTER this -Return the name of the Makefile with the DIST target in it for @var{THIS}. -@end deffn - -@deffn Method ede-proj-configure-file :AFTER this -The configure.in script used by project @var{THIS}. -@end deffn - -@deffn Method ede-commit-project :AFTER proj -Commit any change to @var{PROJ} to its file. -@end deffn - -@deffn Method project-dist-files :AFTER this -Return a list of files that constitutes a distribution of @var{THIS} project. -@end deffn - -@deffn Method ede-commit-local-variables :AFTER proj -Commit change to local variables in @var{PROJ}. -@end deffn - -@node project-am-makefile -@subsection project-am-makefile -@pjindex project-am-makefile - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item @w{@xref{ede-project}.} -@table @code -@item project-am-makefile -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-am-subtree :AFTER ampf subdir -Return the sub project in @var{AMPF} specified by @var{SUBDIR}. -@end deffn - -@deffn Method project-targets-for-file :AFTER proj -Return a list of targets the project @var{PROJ}. -@end deffn - -@deffn Method project-new-target :AFTER proj &optional name type -Create a new target named @var{NAME}. -Argument @var{TYPE} is the type of target to insert. This is a string -matching something in @code{project-am-type-alist} or type class symbol. -Despite the fact that this is a method, it depends on the current -buffer being in order to provide a smart default target type. -@end deffn - -@node ede-step-project -@subsection ede-step-project -@pjindex ede-step-project - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item @w{@xref{ede-project}.} -@table @code -@item ede-step-project -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :init-variables -Type: @code{list} @* -Default Value: @code{nil} - -Variables to set in this Makefile, at top of file. -@refill - -@item :additional-variables -Type: @code{(or null list)} @* -Default Value: @code{nil} - -Arbitrary variables needed from this project. -It is safe to leave this blank. -@refill - -@item :additional-rules -Type: @code{(or null list)} @* -Default Value: @code{nil} - -Arbitrary rules and dependencies needed to make this target. -It is safe to leave this blank. -@refill - -@item :installation-domain -Type: @code{symbol} @* -Default Value: @code{user} - -Installation domain specification. -The variable GNUSTEP_INSTALLATION_DOMAIN is set at this value. -@refill - -@item :preamble -Type: @code{(or null list)} @* -Default Value: @code{(quote ("GNUmakefile.preamble"))} - -The auxiliary makefile for additional variables. -Included just before the specific target files. -@refill - -@item :postamble -Type: @code{(or null list)} @* -Default Value: @code{(quote ("GNUmakefile.postamble"))} - -The auxiliary makefile for additional rules. -Included just after the specific target files. -@refill - -@item :metasubproject -Type: @code{boolean} @* -Default Value: @code{nil} - -Non-@code{nil} if this is a metasubproject. -Usually, a subproject is determined by a parent project. If multiple top level -projects are grouped into a large project not maintained by EDE, then you need -to set this to non-nil. The only effect is that the @code{dist} rule will then avoid -making a tar file. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-create :AFTER this mfilename -Create a GNUmakefile for all Makefile targets in @var{THIS}. -@var{MFILENAME} is the makefile to generate. -@end deffn - -@deffn Method project-make-dist :AFTER this -Build a distribution for the project based on @var{THIS} target. -@end deffn - -@deffn Method ede-proj-makefile-create-maybe :AFTER this mfilename -Create a Makefile for all Makefile targets in @var{THIS} if needed. -@var{MFILENAME} is the makefile to generate. -@end deffn - -@deffn Method ede-proj-setup-buildenvironment :AFTER this &optional force -Setup the build environment for project @var{THIS}. -Handles the Makefile, or a Makefile.am configure.in combination. -Optional argument @var{FORCE} will force items to be regenerated. -@end deffn - -@deffn Method eieio-done-customizing :AFTER proj -Call this when a user finishes customizing this object. -Argument @var{PROJ} is the project to save. -@end deffn - -@deffn Method ede-proj-dist-makefile :AFTER this -Return the name of the Makefile with the DIST target in it for @var{THIS}. -@end deffn - -@deffn Method ede-commit-project :AFTER proj -Commit any change to @var{PROJ} to its file. -@end deffn - -@deffn Method project-dist-files :AFTER this -Return a list of files that constitutes a distribution of @var{THIS} project. -@end deffn - -@deffn Method ede-commit-local-variables :AFTER proj -Commit change to local variables in @var{PROJ}. -@end deffn - -@node Targets -@section Targets - -@menu -* ede-target :: -* ede-proj-target :: -* ede-proj-target-makefile :: -* semantic-ede-proj-target-grammar :: -* ede-proj-target-makefile-objectcode :: -* ede-proj-target-makefile-archive :: -* ede-proj-target-makefile-program :: -* ede-proj-target-makefile-shared-object :: -* ede-proj-target-elisp :: -* ede-proj-target-elisp-autoloads :: -* ede-proj-target-makefile-miscelaneous :: -* ede-proj-target-makefile-info :: -* ede-proj-target-scheme :: -* project-am-target :: -* project-am-objectcode :: -* project-am-program :: -* project-am-header-noinst :: -* project-am-header-inst :: -* project-am-lisp :: -* project-am-texinfo :: -* project-am-man :: -@end menu - - -@node ede-target -@subsection ede-target -@tgindex ede-target - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item ede-target -@table @asis -@item Children: -@w{ede-cpp-root-target,} @w{ede-emacs-target-c,} @w{ede-emacs-target-el,} @w{ede-emacs-target-misc,} @w{ede-linux-target-c,} @w{ede-linux-target-misc,} @w{ede-maven-target-java,} @w{ede-maven-target-c,} @w{ede-maven-target-misc,} @w{ede-simple-target,} @w{@xref{ede-proj-target},} @w{@xref{project-am-target}.} -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :name -Type: @code{string} - -Name of this target. -@refill - -@item :path -Type: @code{string} - -The path to the sources of this target. -Relative to the path of the project it belongs to. -@refill - -@item :source -Type: @code{list} @* -Default Value: @code{nil} - -Source files in this target. -@refill - -@item :versionsource -Type: @code{list} @* -Default Value: @code{nil} - -Source files with a version string in them. -These files are checked for a version string whenever the EDE version -of the master project is changed. When strings are found, the version -previously there is updated. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-preprocessor-map :AFTER this -Get the pre-processor map for project @var{THIS}. -@end deffn - -@deffn Method eieio-speedbar-description :AFTER obj -Provide a speedbar description for @var{OBJ}. -@end deffn - -@deffn Method project-compile-target :AFTER obj &optional command -Compile the current target @var{OBJ}. -Argument @var{COMMAND} is the command to use for compiling the target. -@end deffn - -@deffn Method project-debug-target :AFTER obj -Run the current project target @var{OBJ} in a debugger. -@end deffn - -@deffn Method ede-convert-path :AFTER this path -Convert path in a standard way for a given project. -Default to making it project relative. -Argument @var{THIS} is the project to convert @var{PATH} to. -@end deffn - -@deffn Method ede-name :AFTER this -Return the name of @var{THIS} targt. -@end deffn - -@deffn Method ede-target-buffer-in-sourcelist :AFTER this buffer source -Return non-@code{nil} if object @var{THIS} is in @var{BUFFER} to a @var{SOURCE} list. -Handles complex path issues. -@end deffn - -@deffn Method eieio-speedbar-derive-line-path :AFTER obj &optional depth -Return the path to @var{OBJ}. -Optional @var{DEPTH} is the depth we start at. -@end deffn - -@deffn Method ede-buffer-header-file :AFTER this buffer -There are no default header files in EDE. -Do a quick check to see if there is a Header tag in this buffer. -@end deffn - -@deffn Method project-remove-file :AFTER ot fnnd -Remove the current buffer from project target @var{OT}. -Argument @var{FNND} is an argument. -@end deffn - -@deffn Method ede-buffer-documentation-files :AFTER this buffer -Check for some documentation files for @var{THIS}. -Also do a quick check to see if there is a Documentation tag in this @var{BUFFER}. -@end deffn - -@deffn Method ede-map-target-buffers :AFTER this proc -For @var{THIS}, execute @var{PROC} on all buffers belonging to @var{THIS}. -@end deffn - -@deffn Method eieio-speedbar-child-description :AFTER obj -Provide a speedbar description for a plain-child of @var{OBJ}. -A plain child is a child element which is not an EIEIO object. -@end deffn - -@deffn Method ede-object-keybindings :BEFORE this -Retrieves the slot @code{keybindings} from an object of class @code{ede-target} -@end deffn - -@deffn Method ede-description :AFTER this -Return a description suitable for the minibuffer about @var{THIS}. -@end deffn - -@deffn Method eieio-speedbar-object-children :AFTER this -Return the list of speedbar display children for @var{THIS}. -@end deffn - -@deffn Method ede-system-include-path :AFTER this -Get the system include path used by project @var{THIS}. -@end deffn - -@deffn Method ede-object-sourcecode :BEFORE this -Retrieves the slot @code{sourcetype} from an object of class @code{ede-target} -@end deffn - -@deffn Method ede-expand-filename :AFTER this filename &optional force -Return a fully qualified file name based on target @var{THIS}. -@var{FILENAME} should be a filename which occurs in a directory in which @var{THIS} works. -Optional argument @var{FORCE} forces the default filename to be provided even if it -doesn't exist. -@end deffn - -@deffn Method ede-menu-items-build :AFTER obj &optional current -Return a list of menu items for building target @var{OBJ}. -If optional argument @var{CURRENT} is non-@code{nil}, return sub-menu code. -@end deffn - -@deffn Method ede-want-file-p :AFTER this file -Return non-@code{nil} if @var{THIS} target wants @var{FILE}. -@end deffn - -@deffn Method ede-update-version-in-source :AFTER this version -In sources for @var{THIS}, change version numbers to @var{VERSION}. -@end deffn - -@deffn Method project-delete-target :AFTER ot -Delete the current target @var{OT} from it's parent project. -@end deffn - -@deffn Method ede-target-sourcecode :AFTER this -Return the sourcecode objects which @var{THIS} permits. -@end deffn - -@deffn Method eieio-speedbar-child-make-tag-lines :AFTER this depth -Create a speedbar tag line for a child of @var{THIS}. -It has depth @var{DEPTH}. -@end deffn - -@deffn Method eieio-speedbar-object-buttonname :AFTER object -Return a string to use as a speedbar button for @var{OBJECT}. -@end deffn - -@deffn Method eieio-done-customizing :AFTER target -Call this when a user finishes customizing @var{TARGET}. -@end deffn - -@deffn Method project-edit-file-target :AFTER ot -Edit the target @var{OT} associated w/ this file. -@end deffn - -@deffn Method ede-documentation :AFTER this -Return a list of files that provides documentation. -Documentation is not for object @var{THIS}, but is provided by @var{THIS} for other -files in the project. -@end deffn - -@deffn Method ede-want-file-source-p :AFTER this file -Return non-@code{nil} if @var{THIS} target wants @var{FILE}. -@end deffn - -@deffn Method ede-want-file-auxiliary-p :AFTER this file -Return non-@code{nil} if @var{THIS} target wants @var{FILE}. -@end deffn - -@deffn Method project-add-file :AFTER ot file -Add the current buffer into project project target @var{OT}. -Argument @var{FILE} is the file to add. -@end deffn - -@deffn Method ede-target-name :AFTER this -Return the name of @var{THIS} target, suitable for make or debug style commands. -@end deffn - -@deffn Method ede-object-menu :BEFORE this -Retrieves the slot @code{menu} from an object of class @code{ede-target} -@end deffn - -@node ede-proj-target -@subsection ede-proj-target -@tgindex ede-proj-target - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item ede-proj-target -@table @asis -@item Children: -@w{@xref{ede-proj-target-makefile},} @w{ede-proj-target-aux,} @w{@xref{ede-proj-target-scheme}.} -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :name -Type: @code{string} - -Name of this target. -@refill - -@item :path -Type: @code{string} - -The path to the sources of this target. -Relative to the path of the project it belongs to. -@refill - -@item :auxsource -Type: @code{list} @* -Default Value: @code{nil} - -Auxiliary source files included in this target. -Each of these is considered equivalent to a source file, but it is not -distributed, and each should have a corresponding rule to build it. -@refill - -@item :compiler -Type: @code{(or null symbol)} @* -Default Value: @code{nil} - -The compiler to be used to compile this object. -This should be a symbol, which contains the object defining the compiler. -This enables save/restore to do so by name, permitting the sharing -of these compiler resources, and global customization thereof. -@refill - -@item :linker -Type: @code{(or null symbol)} @* -Default Value: @code{nil} - -The linker to be used to link compiled sources for this object. -This should be a symbol, which contains the object defining the linker. -This enables save/restore to do so by name, permitting the sharing -of these linker resources, and global customization thereof. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method project-compile-target :AFTER obj &optional command -Compile the current target @var{OBJ}. -Argument @var{COMMAND} is the command to use for compiling the target. -@end deffn - -@deffn Method project-debug-target :AFTER obj -Run the current project target @var{OBJ} in a debugger. -@end deffn - -@deffn Method ede-proj-configure-add-missing :AFTER this -Query if any files needed by @var{THIS} provided by automake are missing. -Results in --add-missing being passed to automake. -@end deffn - -@deffn Method ede-proj-flush-autoconf :AFTER this -Flush the configure file (current buffer) to accommodate @var{THIS}. -By flushing, remove any cruft that may be in the file. Subsequent -calls to @dfn{ede-proj-tweak-autoconf} can restore items removed by flush. -@end deffn - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Insert rules needed by @var{THIS} target. -@end deffn - -@deffn Method project-remove-file :AFTER target file -For @var{TARGET}, remove @var{FILE}. -@var{FILE} must be massaged by @dfn{ede-convert-path}. -@end deffn - -@deffn Method ede-proj-configure-create-missing :AFTER this -Add any missing files for @var{THIS} by creating them. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-insert-variables :AFTER this &optional moresource -Insert variables needed by target @var{THIS}. -Optional argument @var{MORESOURCE} is a list of additional sources to add to the -sources variable. -@end deffn - -@deffn Method ede-proj-makefile-insert-automake-post-variables :AFTER this -Insert variables needed by target @var{THIS} in Makefile.am after SOURCES. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-dependencies :AFTER this -Insert any symbols that the DIST rule should depend on. -Argument @var{THIS} is the target that should insert stuff. -@end deffn - -@deffn Method ede-proj-linkers :AFTER obj -List of linkers being used by @var{OBJ}. -If the @code{linker} slot is empty, concoct one on a first match found -basis for any given type from the @code{availablelinkers} slot. -Otherwise, return the @code{linker} slot. -Converts all symbols into the objects to be used. -@end deffn - -@deffn Method ede-proj-makefile-garbage-patterns :AFTER this -Return a list of patterns that are considered garbage to @var{THIS}. -These are removed with make clean. -@end deffn - -@deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - -@deffn Method ede-proj-compilers :AFTER obj -List of compilers being used by @var{OBJ}. -If the @code{compiler} slot is empty, concoct one on a first match found -basis for any given type from the @code{availablecompilers} slot. -Otherwise, return the @code{compiler} slot. -Converts all symbols into the objects to be used. -@end deffn - -@deffn Method project-delete-target :AFTER this -Delete the current target @var{THIS} from it's parent project. -@end deffn - -@deffn Method ede-proj-makefile-target-name :AFTER this -Return the name of the main target for @var{THIS} target. -@end deffn - -@deffn Method eieio-done-customizing :AFTER target -Call this when a user finishes customizing this object. -Argument @var{TARGET} is the project we are completing customization on. -@end deffn - -@deffn Method ede-proj-makefile-insert-user-rules :AFTER this -Insert user specified rules needed by @var{THIS} target. -@end deffn - -@deffn Method project-add-file :AFTER this file -Add to target @var{THIS} the current buffer represented as @var{FILE}. -@end deffn - -@deffn Method ede-proj-makefile-insert-automake-pre-variables :AFTER this -Insert variables needed by target @var{THIS} in Makefile.am before SOURCES. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-filepatterns :AFTER this -Insert any symbols that the DIST rule should depend on. -Argument @var{THIS} is the target that should insert stuff. -@end deffn - -@deffn Method ede-proj-makefile-dependency-files :AFTER this -Return a list of source files to convert to dependencies. -Argument @var{THIS} is the target to get sources from. -@end deffn - -@deffn Method ede-proj-makefile-insert-source-variables :AFTER this &optional moresource -Insert the source variables needed by @var{THIS}. -Optional argument @var{MORESOURCE} is a list of additional sources to add to the -sources variable. -@end deffn - - -@node ede-proj-target-makefile -@subsection ede-proj-target-makefile -@tgindex ede-proj-target-makefile - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item ede-proj-target-makefile -@table @asis -@item Children: -@w{@xref{semantic-ede-proj-target-grammar},} @w{@xref{ede-proj-target-makefile-objectcode},} @w{@xref{ede-proj-target-elisp},} @w{@xref{ede-proj-target-makefile-miscelaneous},} @w{@xref{ede-proj-target-makefile-info}.} -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :makefile -Type: @code{string} @* -Default Value: @code{"Makefile"} - -File name of generated Makefile. -@refill - -@item :partofall -Type: @code{boolean} @* -Default Value: @code{t} - -Non @code{nil} means the rule created is part of the all target. -Setting this to @code{nil} creates the rule to build this item, but does not -include it in the ALL`all:' rule. -@refill - -@item :configuration-variables -Type: @code{list} @* -Default Value: @code{nil} - -Makefile variables appended to use in different configurations. -These variables are used in the makefile when a configuration becomes active. -Target variables are always renamed such as foo_CFLAGS, then included into -commands where the variable would usually appear. -@refill - -@item :rules -Type: @code{list} @* -Default Value: @code{nil} - -Arbitrary rules and dependencies needed to make this target. -It is safe to leave this blank. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-dependencies :AFTER this -Return a string representing the dependencies for @var{THIS}. -Some compilers only use the first element in the dependencies, others -have a list of intermediates (object files), and others don't care. -This allows customization of how these elements appear. -@end deffn - -@deffn Method project-compile-target :AFTER obj &optional command -Compile the current target program @var{OBJ}. -Optional argument @var{COMMAND} is the s the alternate command to use. -@end deffn - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Insert rules needed by @var{THIS} target. -@end deffn - -@deffn Method ede-proj-makefile-insert-variables :AFTER this &optional moresource -Insert variables needed by target @var{THIS}. -Optional argument @var{MORESOURCE} is a list of additional sources to add to the -sources variable. -@end deffn - -@deffn Method ede-proj-makefile-insert-commands :AFTER this -Insert the commands needed by target @var{THIS}. -For targets, insert the commands needed by the chosen compiler. -@end deffn - -@deffn Method ede-proj-makefile-configuration-variables :AFTER this configuration -Return a list of configuration variables from @var{THIS}. -Use @var{CONFIGURATION} as the current configuration to query. -@end deffn - -@node semantic-ede-proj-target-grammar -@subsection semantic-ede-proj-target-grammar -@tgindex semantic-ede-proj-target-grammar - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item semantic-ede-proj-target-grammar -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-compile-target :AFTER obj -Compile all sources in a Lisp target @var{OBJ}. -@end deffn - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Insert rules needed by @var{THIS} target. -@end deffn - -@deffn Method ede-buffer-mine :AFTER this buffer -Return @code{t} if object @var{THIS} lays claim to the file in @var{BUFFER}. -Lays claim to all -by.el, and -wy.el files. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-dependencies :AFTER this -Insert dist dependencies, or intermediate targets. -This makes sure that all grammar lisp files are created before the dist -runs, so they are always up to date. -Argument @var{THIS} is the target that should insert stuff. -@end deffn - - -@node ede-proj-target-makefile-objectcode -@subsection ede-proj-target-makefile-objectcode -@tgindex ede-proj-target-makefile-objectcode - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item ede-proj-target-makefile-objectcode -@table @asis -@item Children: -@w{@xref{ede-proj-target-makefile-archive},} @w{@xref{ede-proj-target-makefile-program}.} -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :configuration-variables -Type: @code{list} @* -Default Value: @code{("debug" ("CFLAGS" . "-g") ("LDFLAGS" . "-g"))} - -@xref{ede-proj-target-makefile}. -@end table -@end table -@subsubsection Specialized Methods - -@deffn Method ede-buffer-header-file :AFTER this buffer -There are no default header files. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-insert-variables :AFTER this &optional moresource -Insert variables needed by target @var{THIS}. -Optional argument @var{MORESOURCE} is not used. -@end deffn - -@deffn Method ede-proj-makefile-dependency-files :AFTER this -Return a list of source files to convert to dependencies. -Argument @var{THIS} is the target to get sources from. -@end deffn - - -@node ede-proj-target-makefile-archive -@subsection ede-proj-target-makefile-archive -@tgindex ede-proj-target-makefile-archive - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item @w{@xref{ede-proj-target-makefile-objectcode}.} -@table @code -@item ede-proj-target-makefile-archive -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Create the make rule needed to create an archive for @var{THIS}. -@end deffn - -@deffn Method ede-proj-makefile-insert-source-variables :PRIMARY this -Insert bin_PROGRAMS variables needed by target @var{THIS}. -We aren't actually inserting SOURCE details, but this is used by the -Makefile.am generator, so use it to add this important bin program. -@end deffn - - -@node ede-proj-target-makefile-program -@subsection ede-proj-target-makefile-program -@tgindex ede-proj-target-makefile-program - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item @w{@xref{ede-proj-target-makefile-objectcode}.} -@table @code -@item ede-proj-target-makefile-program -@table @asis -@item Children: -@w{@xref{ede-proj-target-makefile-shared-object}.} -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :ldlibs -Type: @code{list} @* -Default Value: @code{nil} - -Libraries, such as "m" or "Xt" which this program depends on. -The linker flag "-l" is automatically prepended. Do not include a "lib" -prefix, or a ".so" suffix. - -Note: Currently only used for Automake projects. -@refill - -@item :ldflags -Type: @code{list} @* -Default Value: @code{nil} - -Additional flags to add when linking this target. -Use ldlibs to add addition libraries. Use this to specify specific -options to the linker. - -Note: Not currently used. This bug needs to be fixed. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method project-debug-target :AFTER obj -Debug a program target @var{OBJ}. -@end deffn - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Insert rules needed by @var{THIS} target. -@end deffn - -@deffn Method ede-proj-makefile-insert-automake-post-variables :AFTER this -Insert bin_PROGRAMS variables needed by target @var{THIS}. -@end deffn - -@deffn Method ede-proj-makefile-insert-automake-pre-variables :AFTER this -Insert bin_PROGRAMS variables needed by target @var{THIS}. -@end deffn - - -@node ede-proj-target-makefile-shared-object -@subsection ede-proj-target-makefile-shared-object -@tgindex ede-proj-target-makefile-shared-object - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item @w{@xref{ede-proj-target-makefile-objectcode}.} -@table @code -@item @w{@xref{ede-proj-target-makefile-program}.} -@table @code -@item ede-proj-target-makefile-shared-object -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method ede-proj-configure-add-missing :AFTER this -Query if any files needed by @var{THIS} provided by automake are missing. -Results in --add-missing being passed to automake. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-insert-automake-post-variables :AFTER this -Insert bin_PROGRAMS variables needed by target @var{THIS}. -We need to override -program which has an LDADD element. -@end deffn - -@deffn Method ede-proj-makefile-target-name :AFTER this -Return the name of the main target for @var{THIS} target. -@end deffn - -@deffn Method ede-proj-makefile-insert-automake-pre-variables :AFTER this -Insert bin_PROGRAMS variables needed by target @var{THIS}. -We aren't actually inserting SOURCE details, but this is used by the -Makefile.am generator, so use it to add this important bin program. -@end deffn - - -@node ede-proj-target-elisp -@subsection ede-proj-target-elisp -@tgindex ede-proj-target-elisp - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item ede-proj-target-elisp -@table @asis -@item Children: -@w{@xref{ede-proj-target-elisp-autoloads}.} -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :aux-packages -Type: @code{list} @* -Default Value: @code{nil} - -Additional packages needed. -There should only be one toplevel package per auxiliary tool needed. -These packages location is found, and added to the compile time -load path. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method project-compile-target :AFTER obj -Compile all sources in a Lisp target @var{OBJ}. -Bonus: Return a cons cell: (COMPILED . UPTODATE). -@end deffn - -@deffn Method ede-proj-flush-autoconf :AFTER this -Flush the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - -@deffn Method ede-buffer-mine :AFTER this buffer -Return @code{t} if object @var{THIS} lays claim to the file in @var{BUFFER}. -Lays claim to all .elc files that match .el files in this target. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - -@deffn Method ede-update-version-in-source :AFTER this version -In a Lisp file, updated a version string for @var{THIS} to @var{VERSION}. -There are standards in Elisp files specifying how the version string -is found, such as a @code{-version} variable, or the standard header. -@end deffn - -@node ede-proj-target-elisp-autoloads -@subsection ede-proj-target-elisp-autoloads -@tgindex ede-proj-target-elisp-autoloads - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item @w{@xref{ede-proj-target-elisp}.} -@table @code -@item ede-proj-target-elisp-autoloads -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :aux-packages -Type: @code{list} @* -Default Value: @code{("cedet-autogen")} - -@xref{ede-proj-target-elisp}. -@item :autoload-file -Type: @code{string} @* -Default Value: @code{"loaddefs.el"} - -The file that autoload definitions are placed in. -There should be one load defs file for a given package. The load defs are created -for all Emacs Lisp sources that exist in the directory of the created target. -@refill - -@item :autoload-dirs -Type: @code{list} @* -Default Value: @code{nil} - -The directories to scan for autoload definitions. -If @code{nil} defaults to the current directory. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-dependencies :AFTER this -Return a string representing the dependencies for @var{THIS}. -Always return an empty string for an autoloads generator. -@end deffn - -@deffn Method project-compile-target :AFTER obj -Create or update the autoload target. -@end deffn - -@deffn Method ede-proj-flush-autoconf :AFTER this -Flush the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - -@deffn Method ede-buffer-mine :AFTER this buffer -Return @code{t} if object @var{THIS} lays claim to the file in @var{BUFFER}. -Lays claim to all .elc files that match .el files in this target. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-dependencies :AFTER this -Insert any symbols that the DIST rule should depend on. -Emacs Lisp autoload files ship the generated .el files. -Argument @var{THIS} is the target which needs to insert an info file. -@end deffn - -@deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - -@deffn Method ede-update-version-in-source :AFTER this version -In a Lisp file, updated a version string for @var{THIS} to @var{VERSION}. -There are standards in Elisp files specifying how the version string -is found, such as a @code{-version} variable, or the standard header. -@end deffn - -@deffn Method ede-proj-compilers :AFTER obj -List of compilers being used by @var{OBJ}. -If the @code{compiler} slot is empty, get the car of the compilers list. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-filepatterns :AFTER this -Insert any symbols that the DIST rule should distribute. -Emacs Lisp autoload files ship the generated .el files. -Argument @var{THIS} is the target which needs to insert an info file. -@end deffn - -@deffn Method ede-proj-makefile-insert-source-variables :AFTER this &optional moresource -Insert the source variables needed by @var{THIS}. -Optional argument @var{MORESOURCE} is a list of additional sources to add to the -sources variable. -@end deffn - - -@node ede-proj-target-makefile-miscelaneous -@subsection ede-proj-target-makefile-miscelaneous -@tgindex ede-proj-target-makefile-miscelaneous - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item ede-proj-target-makefile-miscelaneous -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :submakefile -Type: @code{string} @* -Default Value: @code{""} - -Miscellaneous sources which have a specialized makefile. -The sub-makefile is used to build this target. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Create the make rule needed to create an archive for @var{THIS}. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-dependency-files :AFTER this -Return a list of files which @var{THIS} target depends on. -@end deffn - - -@node ede-proj-target-makefile-info -@subsection ede-proj-target-makefile-info -@tgindex ede-proj-target-makefile-info - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item ede-proj-target-makefile-info -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :mainmenu -Type: @code{string} @* -Default Value: @code{""} - -The main menu resides in this file. -All other sources should be included independently. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-configure-add-missing :AFTER this -Query if any files needed by @var{THIS} provided by automake are missing. -Results in --add-missing being passed to automake. -@end deffn - -@deffn Method object-write :AFTER this -Before committing any change to @var{THIS}, make sure the mainmenu is first. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-dependencies :AFTER this -Insert any symbols that the DIST rule should depend on. -Texinfo files want to insert generated `.info' files. -Argument @var{THIS} is the target which needs to insert an info file. -@end deffn - -@deffn Method ede-proj-makefile-target-name :AFTER this -Return the name of the main target for @var{THIS} target. -@end deffn - -@deffn Method ede-documentation :AFTER this -Return a list of files that provides documentation. -Documentation is not for object @var{THIS}, but is provided by @var{THIS} for other -files in the project. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-filepatterns :AFTER this -Insert any symbols that the DIST rule should depend on. -Texinfo files want to insert generated `.info' files. -Argument @var{THIS} is the target which needs to insert an info file. -@end deffn - -@deffn Method ede-proj-makefile-insert-source-variables :AFTER this &optional moresource -Insert the source variables needed by @var{THIS} info target. -Optional argument @var{MORESOURCE} is a list of additional sources to add to the -sources variable. -Does the usual for Makefile mode, but splits source into two variables -when working in Automake mode. -@end deffn - -@node ede-proj-target-scheme -@subsection ede-proj-target-scheme -@tgindex ede-proj-target-scheme - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item ede-proj-target-scheme -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :interpreter -Type: @code{string} @* -Default Value: @code{"guile"} - -The preferred interpreter for this code. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - - -@node project-am-target -@subsection project-am-target -@tgindex project-am-target - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item project-am-target -@table @asis -@item Children: -@w{@xref{project-am-objectcode},} @w{project-am-header,} @w{@xref{project-am-lisp},} @w{@xref{project-am-texinfo},} @w{@xref{project-am-man}.} -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-compile-target-command :AFTER this -Default target to use when compiling a given target. -@end deffn - -@deffn Method project-make-dist :AFTER this -Run the current project in the debugger. -@end deffn - -@deffn Method project-edit-file-target :AFTER obj -Edit the target associated w/ this file. -@end deffn - -@node project-am-objectcode -@subsection project-am-objectcode -@tgindex project-am-objectcode - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item project-am-objectcode -@table @asis -@item Children: -@w{@xref{project-am-program},} @w{project-am-lib.} -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-am-macro :AFTER this -Return the default macro to 'edit' for this object type. -@end deffn - -@deffn Method project-debug-target :AFTER obj -Run the current project target in a debugger. -@end deffn - -@deffn Method project-compile-target-command :AFTER this -Default target to use when compiling an object code target. -@end deffn - -@deffn Method ede-buffer-header-file :AFTER this buffer -There are no default header files. -@end deffn - -@node project-am-program -@subsection project-am-program -@tgindex project-am-program - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item @w{@xref{project-am-objectcode}.} -@table @code -@item project-am-program -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :ldadd @* -Default Value: @code{nil} - -Additional LD args. -@refill -@end table -@end table - -@node project-am-header-noinst -@subsection project-am-header-noinst -@tgindex project-am-header-noinst - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item @w{project-am-header.} -@table @code -@item project-am-header-noinst -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-am-macro :AFTER this -Return the default macro to 'edit' for this object. -@end deffn - -@node project-am-header-inst -@subsection project-am-header-inst -@tgindex project-am-header-inst - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item @w{project-am-header.} -@table @code -@item project-am-header-inst -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-am-macro :AFTER this -Return the default macro to 'edit' for this object. -@end deffn - -@node project-am-lisp -@subsection project-am-lisp -@tgindex project-am-lisp - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item project-am-lisp -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-am-macro :AFTER this -Return the default macro to 'edit' for this object. -@end deffn - -@node project-am-texinfo -@subsection project-am-texinfo -@tgindex project-am-texinfo - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item project-am-texinfo -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :include @* -Default Value: @code{nil} - -Additional texinfo included in this one. -@refill - -@end table -@end table -@subsubsection Specialized Methods - -@deffn Method project-am-macro :AFTER this -Return the default macro to 'edit' for this object type. -@end deffn - -@deffn Method project-compile-target-command :AFTER this -Default target t- use when compiling a texinfo file. -@end deffn - -@deffn Method ede-documentation :AFTER this -Return a list of files that provides documentation. -Documentation is not for object @var{THIS}, but is provided by @var{THIS} for other -files in the project. -@end deffn - -@node project-am-man -@comment node-name, next, previous, up -@subsection project-am-man -@tgindex project-am-man - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item project-am-man -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-am-macro :AFTER this -Return the default macro to 'edit' for this object type. -@end deffn - -@node Sourcecode -@section Sourcecode - -The source code type is an object designed to associated files with -targets. - -@menu -* ede-sourcecode :: -@end menu - - -@node ede-sourcecode -@subsection ede-sourcecode -@scindex ede-sourcecode - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-instance-inheritor -@table @code -@item ede-sourcecode -No children -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :parent-instance -Type: @code{eieio-instance-inheritor-child} - -The parent of this instance. -If a slot of this class is reference, and is unbound, then the parent -is checked for a value. -@refill - -@item :name -Type: @code{string} - -The name of this type of source code. -Such as "C" or "Emacs Lisp" -@refill - -@item :sourcepattern -Type: @code{string} @* -Default Value: @code{".*"} - -Emacs regex matching sourcecode this target accepts. -@refill - -@item :auxsourcepattern -Type: @code{(or null string)} @* -Default Value: @code{nil} - -Emacs regex matching auxiliary source code this target accepts. -Aux source are source code files needed for compilation, which are not compiled -themselves. -@refill - -@item :enable-subdirectories -Type: @code{boolean} @* -Default Value: @code{nil} - -Non @code{nil} if this sourcecode type uses subdirectores. -If sourcecode always lives near the target creating it, this should be nil. -If sourcecode can, or typically lives in a subdirectory of the owning -target, set this to t. -@refill - -@item :garbagepattern -Type: @code{list} @* -Default Value: @code{nil} - -Shell file regex matching files considered as garbage. -This is a list of items added to an @code{rm} command when executing a @code{clean} -type directive. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-want-any-files-p :AFTER this filenames -Return non-@code{nil} if @var{THIS} will accept any files in @var{FILENAMES}. -@end deffn - -@deffn Method ede-want-any-source-files-p :AFTER this filenames -Return non-@code{nil} if @var{THIS} will accept any source files in @var{FILENAMES}. -@end deffn - -@deffn Method ede-want-any-auxiliary-files-p :AFTER this filenames -Return non-@code{nil} if @var{THIS} will accept any aux files in @var{FILENAMES}. -@end deffn - -@deffn Method ede-buffer-header-file :AFTER this filename -Return a list of file names of header files for @var{THIS} with @var{FILENAME}. -Used to guess header files, but uses the auxsource regular expression. -@end deffn - -@deffn Method ede-want-file-p :AFTER this filename -Return non-@code{nil} if sourcecode definition @var{THIS} will take @var{FILENAME}. -@end deffn - -@deffn Method ede-want-file-source-p :AFTER this filename -Return non-@code{nil} if @var{THIS} will take @var{FILENAME} as an auxiliary . -@end deffn - -@deffn Method ede-want-file-auxiliary-p :AFTER this filename -Return non-@code{nil} if @var{THIS} will take @var{FILENAME} as an auxiliary . -@end deffn - -@node Compilers -@section Compilers - -The compiler object is designed to associate source code with -compilers. The target then references the compilers it can use. -When the makefile is created, this object type knows how to create -compile commands. - -@menu -* ede-compilation-program :: -* ede-compiler :: -* ede-object-compiler :: -* ede-linker :: -@end menu - - -@node ede-compilation-program -@subsection ede-compilation-program -@cmindex ede-compilation-program - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-instance-inheritor -@table @code -@item ede-compilation-program -@table @asis -@item Children: -@w{@xref{ede-compiler},} @w{@xref{ede-linker}.} -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :parent-instance -Type: @code{eieio-instance-inheritor-child} - -The parent of this instance. -If a slot of this class is reference, and is unbound, then the parent -is checked for a value. -@refill - -@item :name -Type: @code{string} - -Name of this type of compiler. -@refill - -@item :variables -Type: @code{list} - -Variables needed in the Makefile for this compiler. -An assoc list where each element is (VARNAME . VALUE) where VARNAME -is a string, and VALUE is either a string, or a list of strings. -For example, GCC would define CC=gcc, and emacs would define EMACS=emacs. -@refill - -@item :sourcetype -Type: @code{list} - -A list of @code{ede-sourcecode} @xref{ede-sourcecode}. objects this class will handle. -This is used to match target objects with the compilers and linkers -they can use, and which files this object is interested in. -@refill - -@item :rules -Type: @code{list} @* -Default Value: @code{nil} - -Auxiliary rules needed for this compiler to run. -For example, yacc/lex files need additional chain rules, or inferences. -@refill - -@item :commands -Type: @code{list} - -The commands used to execute this compiler. -The object which uses this compiler will place these commands after -it's rule definition. -@refill - -@item :autoconf -Type: @code{list} @* -Default Value: @code{nil} - -Autoconf function to call if this type of compiler is used. -When a project is in Automake mode, this defines the autoconf function to -call to initialize automake to use this compiler. -For example, there may be multiple C compilers, but they all probably -use the same autoconf form. -@refill - -@item :objectextention -Type: @code{string} - -A string which is the extension used for object files. -For example, C code uses .o on unix, and Emacs Lisp uses .elc. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-flush-autoconf :AFTER this -Flush the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Insert rules needed for @var{THIS} compiler object. -@end deffn - -@deffn Method ede-proj-makefile-insert-variables :AFTER this -Insert variables needed by the compiler @var{THIS}. -@end deffn - -@deffn Method ede-proj-makefile-insert-commands :AFTER this -Insert the commands needed to use compiler @var{THIS}. -The object creating makefile rules must call this method for the -compiler it decides to use after inserting in the rule. -@end deffn - -@deffn Method ede-object-sourcecode :AFTER this -Retrieves the slot @code{sourcetype} from an object of class @code{ede-compilation-program} -@end deffn - -@deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - - -@node ede-compiler -@subsection ede-compiler -@cmindex ede-compiler - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-instance-inheritor -@table @code -@item @w{@xref{ede-compilation-program}.} -@table @code -@item ede-compiler -@table @asis -@item Children: -@w{@xref{ede-object-compiler},} @w{semantic-ede-grammar-compiler-class.} -@end table - -@end table - -@end table - -@end table -@end table - - Create a new object with name NAME of class type ede-compiler - -@table @asis -@item Slots: - -@table @code -@item :parent-instance -Type: @code{eieio-instance-inheritor-child} - -The parent of this instance. -If a slot of this class is reference, and is unbound, then the parent -is checked for a value. -@refill - -@item :name -Type: @code{string} - -Name of this type of compiler. -@refill - -@item :variables -Type: @code{list} - -Variables needed in the Makefile for this compiler. -An assoc list where each element is (VARNAME . VALUE) where VARNAME -is a string, and VALUE is either a string, or a list of strings. -For example, GCC would define CC=gcc, and emacs would define EMACS=emacs. -@refill - -@item :sourcetype -Type: @code{list} - -A list of @code{ede-sourcecode} @xref{ede-sourcecode}. objects this class will handle. -This is used to match target objects with the compilers and linkers -they can use, and which files this object is interested in. -@refill - -@item :commands -Type: @code{list} - -The commands used to execute this compiler. -The object which uses this compiler will place these commands after -it's rule definition. -@refill - -@item :objectextention -Type: @code{string} - -A string which is the extension used for object files. -For example, C code uses .o on unix, and Emacs Lisp uses .elc. -@refill - -@item :makedepends -Type: @code{boolean} @* -Default Value: @code{nil} - -Non-@code{nil} if this compiler can make dependencies. -@refill - -@item :uselinker -Type: @code{boolean} @* -Default Value: @code{nil} - -Non-@code{nil} if this compiler creates code that can be linked. -This requires that the containing target also define a list of available -linkers that can be used. -@refill - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-insert-object-variables :AFTER this targetname sourcefiles -Insert an OBJ variable to specify object code to be generated for @var{THIS}. -The name of the target is @var{TARGETNAME} as a string. @var{SOURCEFILES} is the list of -files to be objectified. -Not all compilers do this. -@end deffn - -@deffn Method ede-compiler-intermediate-objects-p :AFTER this -Return non-@code{nil} if @var{THIS} has intermediate object files. -If this compiler creates code that can be linked together, -then the object files created by the compiler are considered intermediate. -@end deffn - -@deffn Method ede-compiler-intermediate-object-variable :AFTER this targetname -Return a string based on @var{THIS} representing a make object variable. -@var{TARGETNAME} is the name of the target that these objects belong to. -@end deffn - - -@node ede-object-compiler -@subsection ede-object-compiler -@cmindex ede-object-compiler - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-instance-inheritor -@table @code -@item @w{@xref{ede-compilation-program}.} -@table @code -@item @w{@xref{ede-compiler}.} -@table @code -@item ede-object-compiler -No children -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :uselinker -Type: @code{boolean} @* -Default Value: @code{t} - -@xref{ede-compiler}. -@item :dependencyvar -Type: @code{list} - -A variable dedicated to dependency generation. -@refill -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-insert-variables :AFTER this -Insert variables needed by the compiler @var{THIS}. -@end deffn - -@node ede-linker -@subsection ede-linker -@cmindex ede-linker - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-instance-inheritor -@table @code -@item @w{@xref{ede-compilation-program}.} -@table @code -@item ede-linker -No children -@end table - -@end table - -@end table -@end table - - Create a new object with name NAME of class type ede-linker - -@table @asis -@item Slots: - -@table @code -@item :name -Type: @code{string} - -Name of this type of compiler. -@refill - -@item :variables -Type: @code{list} - -Variables needed in the Makefile for this compiler. -An assoc list where each element is (VARNAME . VALUE) where VARNAME -is a string, and VALUE is either a string, or a list of strings. -For example, GCC would define CC=gcc, and emacs would define EMACS=emacs. -@refill - -@item :sourcetype -Type: @code{list} - -A list of @code{ede-sourcecode} @xref{ede-sourcecode}. objects this class will handle. -This is used to match target objects with the compilers and linkers -they can use, and which files this object is interested in. -@refill - -@item :commands -Type: @code{list} - -The commands used to execute this compiler. -The object which uses this compiler will place these commands after -it's rule definition. -@refill - -@item :objectextention -Type: @code{string} - -A string which is the extension used for object files. -For example, C code uses .o on unix, and Emacs Lisp uses .elc. -@refill - -@end table -@end table - -@bye diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi deleted file mode 100644 index 01349e31468..00000000000 --- a/doc/misc/ediff.texi +++ /dev/null @@ -1,2533 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c documentation for Ediff -@c Written by Michael Kifer - -@comment %**start of header (This is for running Texinfo on a region.) - -@comment Using ediff.info instead of ediff in setfilename breaks DOS. -@comment @setfilename ediff -@comment @setfilename ediff.info -@setfilename ../../info/ediff - -@settitle Ediff User's Manual -@synindex vr cp -@synindex fn cp -@synindex pg cp -@synindex ky cp - -@iftex -@finalout -@end iftex -@c @smallbook -@comment %**end of header (This is for running Texinfo on a region.) - -@copying -This file documents Ediff, a comprehensive visual interface to Unix diff -and patch utilities. - -Copyright @copyright{} 1995-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Ediff: (ediff). A visual interface for comparing and merging programs. -@end direntry - -@titlepage -@title Ediff User's Manual -@sp 4 -@subtitle Ediff version 2.81.2 -@sp 1 -@subtitle November 2008 -@sp 5 -@author Michael Kifer -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top, Introduction, (dir), (dir) -@top Ediff - -@insertcopying - -@menu -* Introduction:: About Ediff. -* Major Entry Points:: How to use Ediff. -* Session Commands:: Ediff commands used within a session. -* Registry of Ediff Sessions:: Keeping track of multiple Ediff sessions. -* Session Groups:: Comparing and merging directories. -* Remote and Compressed Files:: You may want to know about this. -* Customization:: How to make Ediff work the way YOU want. -* Credits:: Thanks to those who helped. -* GNU Free Documentation License:: The license for this documentation. -* Index:: -@end menu - -@node Introduction, Major Entry Points, Top, Top -@chapter Introduction - -@cindex Comparing files and buffers -@cindex Merging files and buffers -@cindex Patching files and buffers -@cindex Finding differences - -Ediff provides a convenient way for simultaneous browsing through -the differences between a pair (or a triple) of files or buffers -(which are called @samp{variants} for our purposes). The -files being compared, file-A, file-B, and file-C (if applicable) are -shown in separate windows (side by side, one above the another, or in -separate frames), and the differences are highlighted as you step -through them. You can also copy difference regions from one buffer to -another (and recover old differences if you change your mind). - -Another powerful feature is the ability to merge a pair of files into a -third buffer. Merging with an ancestor file is also supported. -Furthermore, Ediff is equipped with directory-level capabilities that -allow the user to conveniently launch browsing or merging sessions on -groups of files in two (or three) different directories. - -In addition, Ediff can apply a patch to a file and then let you step through -both files, the patched and the original one, simultaneously, -difference-by-difference. You can even apply a patch right out of a mail -buffer, i.e., patches received by mail don't even have to be saved. Since -Ediff lets you copy differences between variants, you can, in effect, apply -patches selectively (i.e., you can copy a difference region from -@file{file.orig} to @file{file}, thereby undoing any particular patch that -you don't like). - -Ediff even understands multi-file patches and can apply them interactively! -(Ediff can recognize multi-file patches only if they are in the context -format or GNU unified format. All other patches are treated as 1-file -patches. Ediff is [hopefully] using the same algorithm as @code{patch} to -determine which files need to be patched.) - -Ediff is aware of version control, which lets you compare -files with their older versions. Ediff also works with remote and -compressed files, automatically ftp'ing them over and uncompressing them. -@xref{Remote and Compressed Files}, for details. - -This package builds upon ideas borrowed from Emerge, and several of Ediff's -functions are adaptations from Emerge. Although Ediff subsumes and greatly -extends Emerge, much of the functionality in Ediff is influenced by Emerge. -The architecture and the interface are, of course, drastically different. - -@node Major Entry Points, Session Commands, Introduction, Top -@chapter Major Entry Points - -When Ediff starts up, it displays a small control window, which accepts the -Ediff commands, and two or three windows displaying the files to be compared -or merged. The control window can be in its own small frame or it can be -part of a bigger frame that displays other buffers. In any case, it is -important that the control window be active (i.e., be the one receiving the -keystrokes) when you use Ediff. You can switch to other Emacs buffers at -will and even edit the files currently being compared with Ediff and then -switch back to Ediff at any time by activating the appropriate Emacs windows. - -Ediff can be invoked interactively using the following functions, which can -be run either from the minibuffer or from the menu bar. In the menu bar, -all Ediff's entry points belong to three submenus of the Tools menu: -Compare, Merge, and Apply Patch. - -@table @code -@item ediff-files -@itemx ediff -@findex ediff-files -@findex ediff -Compare two files. - -@item ediff-backup -@findex ediff-backup -Compare a file with its backup. If there are several numerical backups, use -the latest. If the file is itself a backup, then compare it with its -original. - -@item ediff-current-file -@findex ediff-current-file -Compare the buffer with its file on disk. This function can be used as a -safe version of @code{revert-buffer}. - -@item ediff-buffers -@findex ediff-buffers -Compare two buffers. - -@item ediff-files3 -@itemx ediff3 -@findex ediff-files3 -@findex ediff3 -Compare three files. - -@item ediff-buffers3 -@findex ediff-buffers3 -Compare three buffers. - -@item edirs -@itemx ediff-directories -@findex edirs -@findex ediff-directories - Compare files common to two directories. -@item edirs3 -@itemx ediff-directories3 -@findex edirs3 -@findex ediff-directories3 - Compare files common to three directories. -@item edir-revisions -@itemx ediff-directory-revisions -@findex ediff-directory-revisions -@findex edir-revisions - Compare versions of files in a given directory. Ediff selects only the -files that are under version control. -@item edir-merge-revisions -@itemx ediff-merge-directory-revisions -@findex edir-merge-revisions -@findex ediff-merge-directory-revisions - Merge versions of files in a given directory. Ediff selects only the -files that are under version control. -@item edir-merge-revisions-with-ancestor -@itemx ediff-merge-directory-revisions-with-ancestor -@findex edir-merge-revisions-with-ancestor -@findex ediff-merge-directory-revisions-with-ancestor - Merge versions of files in a given directory using other versions as -ancestors. Ediff selects only the files that are under version control. - -@item ediff-windows-wordwise -@findex ediff-windows-wordwise -Compare windows word-by-word. - -@item ediff-windows-linewise -@findex ediff-windows-linewise -Compare windows line-by-line. - -@item ediff-regions-wordwise -@findex ediff-regions-wordwise -Compare regions word-by-word. The regions can come from the same buffer -and they can even overlap. You will be asked to specify the buffers that -contain the regions, which you want to compare. For each buffer, you will -also be asked to mark the regions to be compared. Pay attention to the -messages that appear in the minibuffer. - -@item ediff-regions-linewise -@findex ediff-regions-linewise -Similar to @code{ediff-windows-linewise}, but compares the regions -line-by-line. See @code{ediff-windows-linewise} for more details. - -@item ediff-revision -@findex ediff-revision - Compare versions of the current buffer, if the buffer is visiting - a file under version control. - -@item ediff-patch-file -@itemx epatch -@findex ediff-patch-file -@findex epatch - -Patch a file or multiple files, then compare. If the patch applies to just -one file, Ediff will invoke a regular comparison session. If it is a -multi-file patch, then a session group interface will be used and the user -will be able to patch the files selectively. @xref{Session Groups}, for -more details. - -Since the patch might be in a buffer or a file, you will be asked which is -the case. To avoid this extra prompt, you can invoke this command with a -prefix argument. With an odd prefix argument, Ediff assumes the patch -is in a file; with an even argument, a buffer is assumed. - -Note that @code{ediff-patch-file} will actually use the @code{patch} -utility to change the original files on disk. This is not that -dangerous, since you will always have the original contents of the file -saved in another file that has the extension @file{.orig}. -Furthermore, if the file is under version control, then you can always back -out to one of the previous versions (see the section on Version Control in -the Emacs manual). - -@code{ediff-patch-file} is careful about versions control: if the file -to be patched is checked in, then Ediff will offer to check it out, because -failing to do so may result in the loss of the changes when the file is -checked out the next time. - -If you don't intend to modify the file via the patch and just want to see -what the patch is all about (and decide later), then -@code{ediff-patch-buffer} might be a better choice. - -@item ediff-patch-buffer -@itemx epatch-buffer -@findex ediff-patch-buffer -@findex epatch-buffer -Patch a buffer, then compare. The buffer being patched and the file visited -by that buffer (if any) is @emph{not} modified. The result of the patch -appears in some other buffer that has the name ending with @emph{_patched}. - -This function would refuse to apply a multifile patch to a buffer. Use -@code{ediff-patch-file} for that (and when you want the original file to be -modified by the @code{patch} utility). - -Since the patch might be in a buffer or a file, you will be asked which is -the case. To avoid this extra prompt, you can invoke this command with a -prefix argument. With an odd prefix argument, Ediff assumes the patch -is in a file; with an even argument, a buffer is assumed. - -@item ediff-merge-files -@itemx ediff-merge -@findex ediff-merge-files -@findex ediff-merge -Merge two files. - -@item ediff-merge-files-with-ancestor -@itemx ediff-merge-with-ancestor -@findex ediff-merge-files-with-ancestor -@findex ediff-merge-with-ancestor -Like @code{ediff-merge}, but with a third ancestor file. - -@item ediff-merge-buffers -@findex ediff-merge-buffers -Merge two buffers. - -@item ediff-merge-buffers-with-ancestor -@findex ediff-merge-buffers-with-ancestor -Same but with ancestor. - - -@item edirs-merge -@itemx ediff-merge-directories -@findex edirs-merge -@findex ediff-merge-directories - Merge files common to two directories. -@item edirs-merge-with-ancestor -@itemx ediff-merge-directories-with-ancestor -@findex edirs-merge-with-ancestor -@findex ediff-merge-directories-with-ancestor - Same but using files in a third directory as ancestors. - If a pair of files doesn't have an ancestor in the ancestor-directory, you - will still be able to merge them without the ancestor. - -@item ediff-merge-revisions -@findex ediff-merge-revisions -Merge two versions of the file visited by the current buffer. - -@item ediff-merge-revisions-with-ancestor -@findex ediff-merge-revisions-with-ancestor -Same but with ancestor. - -@item ediff-documentation -@findex ediff-documentation -Brings up this manual. - -@item ediff-show-registry -@itemx eregistry -Brings up Ediff session registry. This feature enables you to quickly find -and restart active Ediff sessions. -@end table - -When the above functions are invoked, the user is prompted for all the -necessary information---typically the files or buffers to compare, merge, or -patch. Ediff tries to be smart about these prompts. For instance, in -comparing/merging files, it will offer the visible buffers as defaults. In -prompting for files, if the user enters a directory, the previously input -file name will be appended to that directory. In addition, if the variable -@code{ediff-use-last-dir} is not @code{nil}, Ediff will offer -previously entered directories as defaults (which will be maintained -separately for each type of file, A, B, or C). -@vindex @code{ediff-use-last-dir} - -All the above functions use the POSIX @code{diff} or @code{diff3} programs -to find differences between two files. They process the @code{diff} output -and display it in a convenient form. At present, Ediff understands only -the plain output from diff. Options such as @samp{-c} are not supported, -nor is the format produced by incompatible file comparison programs such as -the VMS version of @code{diff}. - -The functions @code{ediff-files}, @code{ediff-buffers}, -@code{ediff-files3}, @code{ediff-buffers3} first display the coarse, -line-based difference regions, as reported by the @code{diff} program. The -total number of difference regions and the current difference number are -always displayed in the mode line of the control window. - -Since @code{diff} may report fairly large chunks of text as being different, -even though the difference may be localized to just a few words or even -to the white space or line breaks, Ediff further @emph{refines} the -regions to indicate which exact words differ. If the only difference is -in the white space and line breaks, Ediff says so. - -On a color display, fine differences are highlighted with color; on a -monochrome display, they are underlined. @xref{Highlighting Difference -Regions}, for information on how to customize this. - -The commands @code{ediff-windows-wordwise}, -@code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and -@code{ediff-regions-linewise} do comparison on parts of existing Emacs -buffers. The commands @code{ediff-windows-wordwise} and -@code{ediff-regions-wordwise} are intended for relatively small segments -of buffers (e.g., up to 100 lines, depending on the speed of your machine), -as they perform comparison on the basis of words rather than lines. -(Word-wise comparison of large chunks of text can be slow.) - -To compare large regions, use @code{ediff-regions-linewise}. This -command displays differences much like @code{ediff-files} and -@code{ediff-buffers}. - -The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply a -patch to a file or a buffer and then run Ediff on the appropriate -files/buffers, displaying the difference regions. - -The entry points @code{ediff-directories}, @code{ediff-merge-directories}, -etc., provide a convenient interface for comparing and merging files in -different directories. The user is presented with Dired-like interface from -which one can run a group of related Ediff sessions. - -For files under version control, @code{ediff-revision} lets you compare -the file visited by the current buffer to one of its checked-in versions. -You can also compare two checked-in versions of the visited file. -Moreover, the functions @code{ediff-directory-revisions}, -@code{ediff-merge-directory-revisions}, etc., let you run a group of -related Ediff sessions by taking a directory and comparing (or merging) -versions of files in that directory. - -@node Session Commands, Registry of Ediff Sessions, Major Entry Points, Top -@chapter Session Commands - -All Ediff commands are displayed in a Quick Help window, unless you type -@kbd{?} to shrink the window to just one line. You can redisplay the help -window by typing @kbd{?} again. The Quick Help commands are detailed below. - -Many Ediff commands take numeric prefix arguments. For instance, if you -type a number, say 3, and then @kbd{j} (@code{ediff-jump-to-difference}), -Ediff moves to the third difference region. Typing 3 and then @kbd{a} -(@code{ediff-diff-to-diff}) copies the 3rd difference region from variant A -to variant B. Likewise, 4 followed by @kbd{ra} restores the 4th difference -region in buffer A (if it was previously written over via the command -@kbd{a}). - -Some commands take negative prefix arguments as well. For instance, typing -@kbd{-} and then @kbd{j} will make the last difference region -current. Typing @kbd{-2} then @kbd{j} makes the penultimate difference -region current, etc. - -Without the prefix argument, all commands operate on the currently -selected difference region. You can make any difference region -current using the various commands explained below. - -For some commands, the actual value of the prefix argument is -immaterial. However, if supplied, the prefix argument may modify the -command (see @kbd{ga}, @kbd{gb}, and @kbd{gc}). - -@menu -* Quick Help Commands:: Frequently used commands. -* Other Session Commands:: Commands that are not bound to keys. -@end menu - -@node Quick Help Commands,Other Session Commands,,Session Commands -@section Quick Help Commands -@cindex command help -@cindex important commands - -@table @kbd -@item ? -@kindex ? -Toggles the Ediff Quick Help window ON and OFF. -@item G -@kindex G -Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer. - -@item E -@kindex E -Brings up the top node of this manual, where you can find further -information on the various Ediff functions and advanced issues, such as -customization, session groups, etc. - -@item v -@kindex v -Scrolls up buffers A and B (and buffer C where appropriate) in a -coordinated fashion. -@item V -@kindex V -Scrolls the buffers down. - -@item < -@kindex < -Scrolls the buffers to the left simultaneously. -@item > -@kindex > -Scrolls buffers to the right. - -@item wd -@kindex wd -Saves the output from the diff utility, for further reference. - -With prefix argument, saves the plain output from @code{diff} (see -@code{ediff-diff-program} and @code{ediff-diff-options}). Without the -argument, it saves customized @code{diff} output (see -@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}), if -it is available. - -@item wa -@kindex wa -Saves buffer A, if it was modified. -@item wb -@kindex wb -Saves buffer B, if it was modified. -@item wc -@kindex wc -Saves buffer C, if it was modified (if you are in a session that -compares three files simultaneously). - -@item a -@kindex a -@emph{In comparison sessions:} -Copies the current difference region (or the region specified as the prefix -to this command) from buffer A to buffer B. -Ediff saves the old contents of buffer B's region; it can -be restored via the command @kbd{rb}, which see. - -@emph{In merge sessions:} -Copies the current difference region (or the region specified as the prefix -to this command) from buffer A to the merge buffer. The old contents of -this region in buffer C can be restored via the command @kbd{r}. - -@item b -@kindex b -Works similarly, but copies the current difference region from buffer B to -buffer A (in @emph{comparison sessions}) or the merge buffer (in -@emph{merge sessions}). - -Ediff saves the old contents of the difference region copied over; it can -be reinstated via the command @kbd{ra} in comparison sessions and -@kbd{r} in merge sessions. - -@item ab -@kindex ab -Copies the current difference region (or the region specified as the prefix -to this command) from buffer A to buffer B. This (and the next five) -command is enabled only in sessions that compare three files -simultaneously. The old region in buffer B is saved and can be restored -via the command @kbd{rb}. -@item ac -@kindex ac -Copies the difference region from buffer A to buffer C. -The old region in buffer C is saved and can be restored via the command -@kbd{rc}. -@item ba -@kindex ba -Copies the difference region from buffer B to buffer A. -The old region in buffer A is saved and can be restored via the command -@kbd{ra}. -@item bc -@kindex bc -Copies the difference region from buffer B to buffer C. -The command @kbd{rc} undoes this. -@item ca -@kindex ca -Copies the difference region from buffer C to buffer A. -The command @kbd{ra} undoes this. -@item cb -@kindex cb -Copies the difference region from buffer C to buffer B. -The command @kbd{rb} undoes this. - -@item p -@itemx DEL -@kindex p -@kindex DEL -Makes the previous difference region current. -@item n -@itemx SPC -@kindex n -@kindex SPC -Makes the next difference region current. - -@item j -@itemx -j -@itemx Nj -@kindex j -Makes the very first difference region current. - -@kbd{-j} makes the last region current. Typing a number, N, and then `j' -makes the difference region N current. Typing -N (a negative number) then -`j' makes current the region Last - N. - -@item ga -@kindex ga -Makes current the difference region closest to the position of the point in -buffer A. - -However, with a prefix argument, Ediff would position all variants -around the area indicated by the current point in buffer A: if -the point is inside a difference region, then the variants will be -positioned at this difference region. If the point is not in any difference -region, then it is in an area where all variants agree with each other. In -this case, the variants will be positioned so that each would display this -area (of agreement). -@item gb -@kindex gb -Makes current the difference region closest to the position of the point in -buffer B. - -With a prefix argument, behaves like @kbd{ga}, but with respect to buffer B. -@item gc -@kindex gc -@emph{In merge sessions:} -makes current the difference region closest to the point in the merge buffer. - -@emph{In 3-file comparison sessions:} -makes current the region closest to the point in buffer C. - -With a prefix argument, behaves like @kbd{ga}, but with respect to buffer C. - -@item ! -@kindex ! -Recomputes the difference regions, bringing them up to date. This is often -needed because it is common to do all sorts of editing during Ediff -sessions, so after a while, the highlighted difference regions may no -longer reflect the actual differences among the buffers. - -@item * -@kindex * -Forces refinement of the current difference region, which highlights the exact -words of disagreement among the buffers. With a negative prefix argument, -unhighlights the current region. - -Forceful refinement may be needed if Ediff encounters a difference region -that is larger than @code{ediff-auto-refine-limit}. In this situation, -Ediff doesn't do automatic refinement in order to improve response time. -(Ediff doesn't auto-refine on dumb terminals as well, but @kbd{*} still -works there. However, the only useful piece of information it can tell you -is whether or not the difference regions disagree only in the amount of -white space.) - -This command is also useful when the highlighted fine differences are -no longer current, due to user editing. - -@item m -@kindex m -Displays the current Ediff session in a frame as wide as the physical -display. This is useful when comparing files side-by-side. Typing `m' again -restores the original size of the frame. - -@item | -@kindex | -Toggles the horizontal/vertical split of the Ediff display. Horizontal -split is convenient when it is possible to compare files -side-by-side. If the frame in which files are displayed is too narrow -and lines are cut off, typing @kbd{m} may help some. - -@item @@ -@kindex @@ -Toggles auto-refinement of difference regions (i.e., automatic highlighting -of the exact words that differ among the variants). Auto-refinement is -turned off on devices where Emacs doesn't support highlighting. - -On slow machines, it may be advantageous to turn auto-refinement off. The -user can always forcefully refine specific difference regions by typing -@kbd{*}. - -@item h -@kindex h -Cycles between full highlighting, the mode where fine differences are not -highlighted (but computed), and the mode where highlighting is done with -@acronym{ASCII} strings. The latter is not really recommended, unless on a dumb TTY. - -@item r -@kindex r -Restores the old contents of the region in the merge buffer. -(If you copied a difference region from buffer A or B into the merge buffer -using the commands @kbd{a} or @kbd{b}, Ediff saves the old contents of the -region in case you change your mind.) - -This command is enabled in merge sessions only. - -@item ra -@kindex ra -Restores the old contents of the current difference region in buffer A, -which was previously saved when the user invoked one of these commands: -@kbd{b}, @kbd{ba}, @kbd{ca}, which see. This command is enabled in -comparison sessions only. -@item rb -@kindex rb -Restores the old contents of the current difference region in buffer B, -which was previously saved when the user invoked one of these commands: -@kbd{a}, @kbd{ab}, @kbd{cb}, which see. This command is enabled in -comparison sessions only. -@item rc -@kindex rc -Restores the old contents of the current difference region in buffer C, -which was previously saved when the user invoked one of these commands: -@kbd{ac}, @kbd{bc}, which see. This command is enabled in 3-file -comparison sessions only. - -@item ## -@kindex ## -Tell Ediff to skip over regions that disagree among themselves only in the -amount of white space and line breaks. - -Even though such regions will be skipped over, you can still jump to any -one of them by typing the region number and then `j'. Typing @kbd{##} -again puts Ediff back in the original state. - -@item #c -@kindex #c -@vindex ediff-ignore-case-option -@vindex ediff-ignore-case-option3 -@vindex ediff-ignore-case -Toggle case sensitivity in the diff program. All diffs are recomputed. -Case sensitivity is controlled by the variables -@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3}, -and @code{ediff-ignore-case}, which are explained elsewhere. - -@item #h -@itemx #f -@kindex #f -@kindex #h -Ediff works hard to ameliorate the effects of boredom in the workplace... - -Quite often differences are due to identical replacements (e.g., the word -`foo' is replaced with the word `bar' everywhere). If the number of regions -with such boring differences exceeds your tolerance threshold, you may be -tempted to tell Ediff to skip these regions altogether (you will still be able -to jump to them via the command @kbd{j}). The above commands, @kbd{#h} -and @kbd{#f}, may well save your day! - -@kbd{#h} prompts you to specify regular expressions for each -variant. Difference regions where each variant's region matches the -corresponding regular expression will be skipped from then on. (You can -also tell Ediff to skip regions where at least one variant matches its -regular expression.) - -@kbd{#f} does dual job: it focuses on regions that match the corresponding -regular expressions. All other regions will be skipped -over. @xref{Selective Browsing}, for more. - -@item A -@kindex A -Toggles the read-only property in buffer A. -If file A is under version control and is checked in, it is checked out -(with your permission). -@item B -@kindex B -Toggles the read-only property in buffer B. -If file B is under version control and is checked in, it is checked out. -@item C -@kindex C -Toggles the read-only property in buffer C (in 3-file comparison sessions). -If file C is under version control and is checked in, it is checked out. - -@item ~ -@kindex ~ -Swaps the windows where buffers A and B are displayed. If you are comparing -three buffers at once, then this command would rotate the windows among -buffers A, B, and C. - -@item i -@kindex i -Displays all kinds of useful data about the current Ediff session. -@item D -@kindex D -Runs @code{ediff-custom-diff-program} on the variants and displays the -buffer containing the output. This is useful when you must send the output -to your Mom. - -With a prefix argument, displays the plain @code{diff} output. -@xref{Patch and Diff Programs}, for details. - -@item R -@kindex R -Displays a list of currently active Ediff sessions---the Ediff Registry. -You can then restart any of these sessions by either clicking on a session -record or by putting the cursor over it and then typing the return key. - -(Some poor souls leave so many active Ediff sessions around that they lose -track of them completely... The `R' command is designed to save these -people from the recently discovered Ediff Proficiency Syndrome.) - -Typing @kbd{R} brings up Ediff Registry only if it is typed into an Ediff -Control Panel. If you don't have a control panel handy, type this in the -minibuffer: @kbd{M-x eregistry}. @xref{Registry of Ediff Sessions}. - -@item M -@kindex M -Shows the session group buffer that invoked the current Ediff session. -@xref{Session Groups}, for more information on session groups. - -@item z -@kindex z -Suspends the current Ediff session. (If you develop a condition known as -Repetitive Ediff Injury---a serious but curable illness---you must change -your current activity. This command tries hard to hide all Ediff-related -buffers.) - -The easiest way to resume a suspended Ediff session is through the registry -of active sessions. @xref{Registry of Ediff Sessions}, for details. -@item q -@kindex q -Terminates this Ediff session. With a prefix argument (e.g.,@kbd{1q}), asks -if you also want to delete the buffers of the variants. -Modified files and the results of merges are never deleted. - -@item % -@kindex % -Toggles narrowing in Ediff buffers. Ediff buffers may be narrowed if you -are comparing only parts of these buffers via the commands -@code{ediff-windows-*} and @code{ediff-regions-*}, which see. - -@item C-l -@kindex C-l -Restores the usual Ediff window setup. This is the quickest way to resume -an Ediff session, but it works only if the control panel of that session is -visible. - -@item $$ -@kindex $$ -While merging with an ancestor file, Ediff is determined to reduce user's -wear and tear by saving him and her much of unproductive, repetitive -typing. If it notices that, say, file A's difference region is identical to -the same difference region in the ancestor file, then the merge buffer will -automatically get the difference region taken from buffer B. The rationale -is that this difference region in buffer A is as old as that in the -ancestor buffer, so the contents of that region in buffer B represents real -change. - -You may want to ignore such `obvious' merges and concentrate on difference -regions where both files `clash' with the ancestor, since this means that -two different people have been changing this region independently and they -had different ideas on how to do this. - -The above command does this for you by skipping the regions where only one -of the variants clashes with the ancestor but the other variant agrees with -it. Typing @kbd{$$} again undoes this setting. - -@item $* -@kindex $* -When merging files with large number of differences, it is sometimes -convenient to be able to skip the difference regions for which you already -decided which variant is most appropriate. Typing @kbd{$*} will accomplish -precisely this. - -To be more precise, this toggles the check for whether the current merge is -identical to its default setting, as originally decided by Ediff. For -instance, if Ediff is merging according to the `combined' policy, then the -merge region is skipped over if it is different from the combination of the -regions in buffers A and B. (Warning: swapping buffers A and B will confuse -things in this respect.) If the merge region is marked as `prefer-A' then -this region will be skipped if it differs from the current difference -region in buffer A, etc. - -@item / -@kindex / -Displays the ancestor file during merges. -@item & -@kindex & -In some situations, such as when one of the files agrees with the ancestor file -on a difference region and the other doesn't, Ediff knows what to do: it copies -the current difference region from the second buffer into the merge buffer. - -In other cases, the right course of action is not that clearcut, and Ediff -would use a default action. The above command changes the default action. -The default action can be @samp{default-A} (choose the region from buffer -A), @samp{default-B} (choose the region from buffer B), or @samp{combined} -(combine the regions from the two buffers). -@xref{Merging and diff3}, for further details. - -The command @kbd{&} also affects the regions in the merge buffers that have -@samp{default-A}, @samp{default-B}, or @samp{combined} status, provided -they weren't changed with respect to the original. For instance, if such a -region has the status @samp{default-A} then changing the default action to -@samp{default-B} will also replace this merge-buffer's region with the -corresponding region from buffer B. - -@item s -@kindex s -Causes the merge window shrink to its minimum size, thereby exposing as much -of the variant buffers as possible. Typing `s' again restores -the original size of that window. - -With a positive prefix argument, this command enlarges the merge window. -E.g., @kbd{4s} increases the size of the window by about 4 lines, if -possible. With a negative numeric argument, the size of the merge window -shrinks by that many lines, if possible. Thus, @kbd{-s} shrinks the window -by about 1 line and @kbd{-3s} by about 3 lines. - -This command is intended only for temporary viewing; therefore, Ediff -restores window C to its original size whenever it makes any other change -in the window configuration. However, redisplaying (@kbd{C-l}) or jumping -to another difference does not affect window C's size. - -The split between the merge window and the variant windows is controlled by -the variable @code{ediff-merge-window-share}, which see. - -@item + -@kindex + -Combines the difference regions from buffers A and B and copies the -result into the merge buffer. @xref{Merging and diff3}, and the -variables @code{ediff-combine-diffs} and @code{ediff-combination-pattern}. - - -@item = -@kindex = -You may run into situations when a large chunk of text in one file has been -edited and then moved to a different place in another file. In such a case, -these two chunks of text are unlikely to belong to the same difference -region, so the refinement feature of Ediff will not be able to tell you -what exactly differs inside these chunks. Since eyeballing large pieces of -text is contrary to human nature, Ediff has a special command to help -reduce the risk of developing a cataract. - -In other situations, the currently highlighted region might be big and you -might want to reconcile of them interactively. - -All of this can be done with the above command, @kbd{=}, which -compares regions within Ediff buffers. Typing @kbd{=} creates a -child Ediff session for comparing regions in buffers A, B, or -C as follows. - -First, you will be asked whether you want to compare the fine differences -between the currently highlighted buffers on a word-by-word basis. If you -accept, a child Ediff session will start using the currently highlighted -regions. Ediff will let you step over the differences word-wise. - -If you reject the offer, you will be asked to select regions of your choice. - -@emph{If you are comparing 2 files or buffers:} -Ediff will ask you to select regions in buffers A and B. - -@emph{If you are comparing 3 files or buffers simultaneously:} Ediff will -ask you to choose buffers and then select regions inside those buffers. - -@emph{If you are merging files or buffers (with or without ancestor):} -Ediff will ask you to choose which buffer (A or B) to compare with the -merge buffer and then select regions in those buffers. - -@end table - -@node Other Session Commands,,Quick Help Commands,Session Commands -@section Other Session Commands - -The following commands can be invoked from within any Ediff session, -although some of them are not bound to a key. - -@table @code -@item eregistry -@itemx ediff-show-registry -@findex eregistry -@findex ediff-show-registry -This command brings up the registry of active Ediff sessions. Ediff -registry is a device that can be used to resume any active Ediff session -(which may have been postponed because the user switched to some other -activity). This command is also useful for switching between multiple -active Ediff sessions that are run at the same time. The function -@code{eregistry} is an alias for @code{ediff-show-registry}. -@xref{Registry of Ediff Sessions}, for more information on this registry. - -@item ediff-toggle-multiframe -@findex ediff-toggle-multiframe -Changes the display from the multi-frame mode (where the quick help window -is in a separate frame) to the single-frame mode (where all Ediff buffers -share the same frame), and vice versa. See -@code{ediff-window-setup-function} for details on how to make either of -these modes the default one. - -This function can also be invoked from the Menubar. However, in some -cases, the change will take place only after you execute one of the Ediff -commands, such as going to the next difference or redisplaying. - -@item ediff-toggle-use-toolbar -@findex ediff-toggle-use-toolbar -Available in XEmacs only. The Ediff toolbar provides quick access to some -of the common Ediff functions. This function toggles the display of the -toolbar. If invoked from the menubar, the function may take sometimes -effect only after you execute an Ediff command, such as going to the next -difference. - -@item ediff-use-toolbar-p -@vindex ediff-use-toolbar-p -The use of the toolbar can also be specified via the variable -@code{ediff-use-toolbar-p} (default is @code{t}). This variable can be set -only in @file{.emacs} --- do @strong{not} change it interactively. Use the -function @code{ediff-toggle-use-toolbar} instead. - -@item ediff-revert-buffers-then-recompute-diffs -@findex ediff-revert-buffers-then-recompute-diffs -This command reverts the buffers you are comparing and recomputes their -differences. It is useful when, after making changes, you decided to -make a fresh start, or if at some point you changed the files being -compared but want to discard any changes to comparison buffers that were -done since then. - -This command normally asks for confirmation before reverting files. -With a prefix argument, it reverts files without asking. - - -@item ediff-profile -@findex ediff-profile -Ediff has an admittedly primitive (but useful) facility for profiling -Ediff's commands. It is meant for Ediff maintenance---specifically, for -making it run faster. The function @code{ediff-profile} toggles -profiling of ediff commands. -@end table - -@node Registry of Ediff Sessions, Session Groups, Session Commands, Top -@chapter Registry of Ediff Sessions - -Ediff maintains a registry of all its invocations that are -still @emph{active}. This feature is very convenient for switching among -active Ediff sessions or for quickly restarting a suspended Ediff session. - -The focal point of this activity is a buffer -called @emph{*Ediff Registry*}. You can display this buffer by typing -@kbd{R} in any Ediff Control Buffer or Session Group Buffer -(@pxref{Session Groups}), or by typing -@kbd{M-x eregistry} into the Minibuffer. -The latter would be the fastest way to bring up the registry -buffer if no control or group buffer is displayed in any of the visible -Emacs windows. -If you are in a habit of running multiple long Ediff sessions and often need to -suspend, resume, or switch between them, it may be a good idea to have the -registry buffer permanently displayed in a separate, dedicated window. - -The registry buffer has several convenient key bindings. -For instance, clicking mouse button 2 or typing -@kbd{RET} or @kbd{v} over any session record resumes that session. -Session records in the registry buffer provide a fairly complete -description of each session, so it is usually easy to identify the right -session to resume. - -Other useful commands are bound to @kbd{SPC} (next registry record) -and @kbd{DEL} (previous registry record). There are other commands as well, -but you don't need to memorize them, since they are listed at the top of -the registry buffer. - -@node Session Groups, Remote and Compressed Files, Registry of Ediff Sessions, Top -@chapter Session Groups - -Several major entries of Ediff perform comparison and merging on -directories. On entering @code{ediff-directories}, -@code{ediff-directories3}, -@code{ediff-merge-directories}, -@code{ediff-merge-directories-with-ancestor}, -@code{ediff-directory-revisions}, -@code{ediff-merge-directory-revisions}, or -@code{ediff-merge-directory-revisions-with-ancestor}, -the user is presented with a -Dired-like buffer that lists files common to the directories involved along -with their sizes. (The list of common files can be further filtered through -a regular expression, which the user is prompted for.) We call this buffer -@emph{Session Group Panel} because all Ediff sessions associated with the -listed files will have this buffer as a common focal point. - -Clicking button 2 or typing @kbd{RET} or @kbd{v} over a -record describing files invokes Ediff in the appropriate mode on these -files. You can come back to the session group buffer associated with a -particular invocation of Ediff by typing @kbd{M} in Ediff control buffer of -that invocation. - -Many commands are available in the session group buffer; some are -applicable only to certain types of work. The relevant commands are always -listed at the top of each session group buffer, so there is no need to -memorize them. - -In directory comparison or merging, a session group panel displays only the -files common to all directories involved. The differences are kept in a -separate @emph{directory difference buffer} and are conveniently displayed -by typing @kbd{D} to the corresponding session group panel. Thus, as an -added benefit, Ediff can be used to compare the contents of up to three -directories. - -@cindex Directory difference buffer -Sometimes it is desirable to copy some files from one directory to another -without exiting Ediff. The @emph{directory difference buffer}, which is -displayed by typing @kbd{D} as discussed above, can be used for this -purpose. If a file is, say, in Ediff's Directory A, but is missing in -Ediff's Directory B (Ediff will refuse to override existing files), then -typing @kbd{C} or clicking mouse button 2 over that file (which must be -displayed in directory difference buffer) will copy that file from -Directory A to Directory B. - -Session records in session group panels are also marked with @kbd{+}, for -active sessions, and with @kbd{-}, for finished sessions. - -Sometimes, it is convenient to exclude certain sessions from a group. -Usually this happens when the user doesn't intend to run Ediff of certain -files in the group, and the corresponding session records just add clutter -to the session group buffer. To help alleviate this problem, the user can -type @kbd{h} to mark a session as a candidate for exclusion and @kbd{x} to -actually hide the marked sessions. There actions are reversible: with a -prefix argument, @kbd{h} unmarks the session under the cursor, and @kbd{x} -brings the hidden sessions into the view (@kbd{x} doesn't unmark them, -though, so the user has to explicitly unmark the sessions of interest). - -Group sessions also understand the command @kbd{m}, which marks sessions -for future operations (other than hiding) on a group of sessions. At present, -the only such group-level operation is the creation of a multi-file patch. - -@vindex ediff-autostore-merges -For group sessions created to merge files, Ediff can store all merges -automatically in a directory. The user is asked to specify such directory -if the value of @code{ediff-autostore-merges} is non-@code{nil}. If the value is -@code{nil}, nothing is done to the merge buffers---it will be the user's -responsibility to save them. If the value is @code{t}, the user will be -asked where to save the merge buffers in all merge jobs, even those that do -not originate from a session group. It the value is neither @code{nil} nor -@code{t}, the merge buffer is saved @emph{only} if this merge session was -invoked from a session group. This behavior is implemented in the function -@code{ediff-maybe-save-and-delete-merge}, which is a hook in -@code{ediff-quit-merge-hook}. The user can supply a different hook, if -necessary. - -The variable @code{ediff-autostore-merges} is buffer-local, so it can be -set on a per-buffer basis. Therefore, use @code{setq-default} to change -this variable globally. - -@cindex Multi-file patches -A multi-file patch is a concatenated output of several runs of the Unix -@code{diff} command (some versions of @code{diff} let you create a -multi-file patch in just one run). Ediff facilitates creation of -multi-file patches as follows. If you are in a session group buffer -created in response to @code{ediff-directories} or -@code{ediff-directory-revisions}, you can mark (by typing @kbd{m}) the -desired Ediff sessions and then type @kbd{P} to create a -multi-file patch of those marked sessions. -Ediff will then display a buffer containing the patch. -The patch is generated by invoking @code{diff} on all marked individual -sessions (represented by files) and session groups (represented by -directories). Ediff will also recursively descend into any @emph{unmarked} -session group and will search for marked sessions there. In this way, you -can create multi-file patches that span file subtrees that grow out of -any given directory. - -In an @code{ediff-directories} session, it is enough to just mark the -requisite sessions. In @code{ediff-directory-revisions} revisions, the -marked sessions must also be active, or else Ediff will refuse to produce a -multi-file patch. This is because, in the latter-style sessions, there are -many ways to create diff output, and it is easier to handle by running -Ediff on the inactive sessions. - -Last, but not least, by typing @kbd{==}, you can quickly find out which -sessions have identical entries, so you won't have to run Ediff on those -sessions. This, however, works only on local, uncompressed files. -For compressed or remote files, this command won't report anything. -Likewise, you can use @kbd{=h} to mark sessions with identical entries -for hiding or, with @kbd{=m}, for further operations. - -The comparison operations @kbd{==}, @kbd{=h}, and @kbd{=m} can recurse into -subdirectories to see if they have identical contents (so the user will not -need to descend into those subdirectories manually). These commands ask the -user whether or not to do a recursive descent. - - - -@node Remote and Compressed Files, Customization, Session Groups, Top -@chapter Remote and Compressed Files - -Ediff works with remote, compressed, and encrypted files. Ediff -supports @file{ange-ftp.el}, @file{jka-compr.el}, @file{uncompress.el} -and @file{crypt++.el}, but it may work with other similar packages as -well. This means that you can compare files residing on another -machine, or you can apply a patch to a file on another machine. Even -the patch itself can be a remote file! - -When patching compressed or remote files, Ediff does not rename the source -file (unlike what the @code{patch} utility would usually do). Instead, the -source file retains its name and the result of applying the patch is placed -in a temporary file that has the suffix @file{_patched} attached. -Generally, this applies to files that are handled using black magic, such -as special file handlers (ange-ftp and some compression and encryption -packages also use this method). - -Regular files are treated by the @code{patch} utility in the usual manner, -i.e., the original is renamed into @file{source-name.orig} and the result -of the patch is placed into the file source-name (@file{_orig} is used -on systems like DOS, etc.) - -@node Customization, Credits, Remote and Compressed Files, Top -@chapter Customization - -Ediff has a rather self-explanatory interface, and in most cases you -won't need to change anything. However, should the need arise, there are -extensive facilities for changing the default behavior. - -Most of the customization can be done by setting various variables in the -@file{.emacs} file. Some customization (mostly window-related -customization and faces) can be done by putting appropriate lines in -@file{.Xdefaults}, @file{.xrdb}, or whatever X resource file is in use. - -With respect to the latter, please note that the X resource -for Ediff customization is `Ediff', @emph{not} `emacs'. -@xref{Window and Frame Configuration}, -@xref{Highlighting Difference Regions}, for further details. Please also -refer to Emacs manual for the information on how to set Emacs X resources. - -@menu -* Hooks:: Customization via the hooks. -* Quick Help Customization:: How to customize Ediff's quick help feature. -* Window and Frame Configuration:: Controlling the way Ediff displays things. -* Selective Browsing:: Advanced browsing through difference regions. -* Highlighting Difference Regions:: Controlling highlighting. -* Narrowing:: Comparing regions, windows, etc. -* Refinement of Difference Regions:: How to control the refinement process. -* Patch and Diff Programs:: Changing the utilities that compute differences - and apply patches. -* Merging and diff3:: How to customize Ediff in its Merge Mode. -* Support for Version Control:: Changing the version control package. - You are not likely to do that. -* Customizing the Mode Line:: Changing the look of the mode line in Ediff. -* Miscellaneous:: Other customization. -* Notes on Heavy-duty Customization:: Customization for the gurus. -@end menu - -@node Hooks, Quick Help Customization, Customization, Customization -@section Hooks - -The bulk of customization can be done via the following hooks: - -@table @code -@item ediff-load-hook -@vindex ediff-load-hook -This hook can be used to change defaults after Ediff is loaded. - -@item ediff-before-setup-hook -@vindex ediff-before-setup-hook -Hook that is run just before Ediff rearranges windows to its liking. -Can be used to save windows configuration. - -@item ediff-keymap-setup-hook -@vindex ediff-keymap-setup-hook -@vindex ediff-mode-map -This hook can be used to alter bindings in Ediff's keymap, -@code{ediff-mode-map}. These hooks are -run right after the default bindings are set but before -@code{ediff-load-hook}. The regular user needs not be concerned with this -hook---it is provided for implementers of other Emacs packages built on top -of Ediff. - -@item ediff-before-setup-windows-hook -@itemx ediff-after-setup-windows-hook -@vindex ediff-before-setup-windows-hook -@vindex ediff-after-setup-windows-hook -These two hooks are called before and after Ediff sets up its window -configuration. These hooks are run each time Ediff rearranges windows to -its liking. This happens whenever it detects that the user changed the -windows setup. - -@item ediff-suspend-hook -@itemx ediff-quit-hook -@vindex ediff-suspend-hook -@vindex ediff-quit-hook -These two hooks are run when you suspend or quit Ediff. They can be -used to set desired window configurations, delete files Ediff didn't -want to clean up after exiting, etc. - -By default, @code{ediff-quit-hook} holds one hook function, -@code{ediff-cleanup-mess}, which cleans after Ediff, as appropriate in -most cases. You probably won't want to change it, but you might -want to add other hook functions. - -Keep in mind that hooks executing before @code{ediff-cleanup-mess} start -in @code{ediff-control-buffer;} they should also leave -@code{ediff-control-buffer} as the current buffer when they finish. -Hooks that are executed after @code{ediff-cleanup-mess} should expect -the current buffer be either buffer A or buffer B. -@code{ediff-cleanup-mess} doesn't kill the buffers being compared or -merged (see @code{ediff-cleanup-hook}, below). - -@item ediff-cleanup-hook -@vindex ediff-cleanup-hook -This hook is run just before @code{ediff-quit-hook}. This is a good -place to do various cleanups, such as deleting the variant buffers. -Ediff provides a function, @code{ediff-janitor}, as one such possible -hook, which you can add to @code{ediff-cleanup-hook} with -@code{add-hooks}. - -@findex ediff-janitor -This function kills buffers A, B, and, possibly, C, if these buffers aren't -modified. In merge jobs, buffer C is never deleted. However, the side -effect of using this function is that you may not be able to compare the -same buffer in two separate Ediff sessions: quitting one of them will -delete this buffer in another session as well. - -@item ediff-quit-merge-hook -@vindex ediff-quit-merge-hook -@vindex ediff-autostore-merges -@findex ediff-maybe-save-and-delete-merge -This hook is called when Ediff quits a merge job. By default, the value is -@code{ediff-maybe-save-and-delete-merge}, which is a function that attempts -to save the merge buffer according to the value of -@code{ediff-autostore-merges}, as described later. - -@item ediff-before-setup-control-frame-hook -@itemx ediff-after-setup-control-frame-hook -@vindex ediff-before-setup-control-frame-hook -@vindex ediff-after-setup-control-frame-hook -These two hooks run before and after Ediff sets up the control frame. -They can be used to relocate Ediff control frame when Ediff runs in a -multiframe mode (i.e., when the control buffer is in its own dedicated -frame). Be aware that many variables that drive Ediff are local to -Ediff Control Panel (@code{ediff-control-buffer}), which requires -special care in writing these hooks. Take a look at -@code{ediff-default-suspend-hook} and @code{ediff-default-quit-hook} to -see what's involved. - -@item ediff-startup-hook -@vindex ediff-startup-hook -This hook is run at the end of Ediff startup. - -@item ediff-select-hook -@vindex ediff-select-hook -This hook is run after Ediff selects the next difference region. - -@item ediff-unselect-hook -@vindex ediff-unselect-hook -This hook is run after Ediff unselects the current difference region. - -@item ediff-prepare-buffer-hook -@vindex ediff-prepare-buffer-hook -This hook is run for each Ediff buffer (A, B, C) right after the buffer -is arranged. - -@item ediff-display-help-hook -@vindex ediff-display-help-hook -Ediff runs this hook each time after setting up the help message. It -can be used to alter the help message for custom packages that run on -top of Ediff. - -@item ediff-mode-hook -@vindex ediff-mode-hook -This hook is run just after Ediff mode is set up in the control -buffer. This is done before any Ediff window is created. You can use it to -set local variables that alter the look of the display. - -@item ediff-registry-setup-hook -@vindex ediff-registry-setup-hook -Hooks run after setting up the registry for all active Ediff session. -@xref{Session Groups}, for details. -@item ediff-before-session-group-setup-hook -@vindex ediff-before-session-group-setup-hook -Hooks run before setting up a control panel for a group of related Ediff -sessions. Can be used, for example, to save window configuration to restore -later. -@item ediff-after-session-group-setup-hook -@vindex ediff-after-session-group-setup-hook -Hooks run after setting up a control panel for a group of related Ediff -sessions. @xref{Session Groups}, for details. -@item ediff-quit-session-group-hook -@vindex ediff-quit-session-group-hook -Hooks run just before exiting a session group. -@item ediff-meta-buffer-keymap-setup-hook -@vindex ediff-meta-buffer-keymap-setup-hook -@vindex ediff-meta-buffer-map -Hooks run just after setting up the @code{ediff-meta-buffer-map} --- the -map that controls key bindings in the meta buffer. Since -@code{ediff-meta-buffer-map} is a local variable, you can set different -bindings for different kinds of meta buffers. -@end table - -@node Quick Help Customization, Window and Frame Configuration, Hooks, Customization -@section Quick Help Customization -@vindex ediff-use-long-help-message -@vindex ediff-control-buffer -@vindex ediff-startup-hook -@vindex ediff-help-message - -Ediff provides quick help using its control panel window. Since this window -takes a fair share of the screen real estate, you can toggle it off by -typing @kbd{?}. The control window will then shrink to just one line and a -mode line, displaying a short help message. - -The variable @code{ediff-use-long-help-message} tells Ediff whether -you use the short message or the long one. By default, it -is set to @code{nil}, meaning that the short message is used. -Set this to @code{t}, if you want Ediff to use the long -message by default. This property can always be changed interactively, by -typing @kbd{?} into Ediff Control Buffer. - -If you want to change the appearance of the help message on a per-buffer -basis, you must use @code{ediff-startup-hook} to change the value of -the variable @code{ediff-help-message}, which is local to -@code{ediff-control-buffer}. - -@node Window and Frame Configuration, Selective Browsing, Quick Help Customization, Customization -@section Window and Frame Configuration - -On a non-windowing display, Ediff sets things up in one frame, splitting -it between a small control window and the windows for buffers A, B, and C. -The split between these windows can be horizontal or -vertical, which can be changed interactively by typing @kbd{|} while the -cursor is in the control window. - -On a window display, Ediff sets up a dedicated frame for Ediff Control -Panel and then it chooses windows as follows: If one of the buffers -is invisible, it is displayed in the currently selected frame. If -a buffer is visible, it is displayed in the frame where it is visible. -If, according to the above criteria, the two buffers fall into the same -frame, then so be it---the frame will be shared by the two. The same -algorithm works when you type @kbd{C-l} (@code{ediff-recenter}), @kbd{p} -(@code{ediff-previous-difference}), @kbd{n} -(@code{ediff-next-difference}), etc. - -The above behavior also depends on whether the current frame is splittable, -dedicated, etc. Unfortunately, the margin of this book is too narrow to -present the details of this remarkable algorithm. - -The upshot of all this is that you can compare buffers in one frame or -in different frames. The former is done by default, while the latter can -be achieved by arranging buffers A, B (and C, if applicable) to be seen in -different frames. Ediff respects these arrangements, automatically -adapting itself to the multi-frame mode. - -Ediff uses the following variables to set up its control panel -(a.k.a.@: control buffer, a.k.a.@: quick help window): - -@table @code -@item ediff-control-frame-parameters -@vindex ediff-control-frame-parameters -You can change or augment this variable including the font, color, -etc. The X resource name of Ediff Control Panel frames is @samp{Ediff}. Under -X-windows, you can use this name to set up preferences in your -@file{~/.Xdefaults}, @file{~/.xrdb}, or whatever X resource file is in -use. Usually this is preferable to changing -@code{ediff-control-frame-parameters} directly. For instance, you can -specify in @file{~/.Xdefaults} the color of the control frame -using the resource @samp{Ediff*background}. - -In general, any X resource pertaining the control frame can be reached -via the prefix @code{Ediff*}. - -@item ediff-control-frame-position-function -@vindex ediff-control-frame-position-function -The preferred way of specifying the position of the control frame is by -setting the variable @code{ediff-control-frame-position-function} to an -appropriate function. -The default value of this variable is -@code{ediff-make-frame-position}. This function places the control frame in -the vicinity of the North-East corner of the frame displaying buffer A. - -@findex ediff-make-frame-position -@end table - -The following variables can be used to adjust the location produced by -@code{ediff-make-frame-position} and for related customization. - -@table @code -@item ediff-narrow-control-frame-leftward-shift -@vindex ediff-narrow-control-frame-leftward-shift -Specifies the number of characters for shifting -the control frame from the rightmost edge of frame A when the control -frame is displayed as a small window. - -@item ediff-wide-control-frame-rightward-shift -@vindex ediff-wide-control-frame-rightward-shift -Specifies the rightward shift of the control frame -from the left edge of frame A when the control frame shows the full -menu of options. - -@item ediff-control-frame-upward-shift -@vindex ediff-control-frame-upward-shift -Specifies the number of pixels for the upward shift -of the control frame. - -@item ediff-prefer-iconified-control-frame -@vindex ediff-prefer-iconified-control-frame -If this variable is @code{t}, the control frame becomes iconified -automatically when you toggle the quick help message off. This saves -valuable real estate on the screen. Toggling help back will deiconify -the control frame. - -To start Ediff with an iconified Control Panel, you should set this -variable to @code{t} and @code{ediff-prefer-long-help-message} to -@code{nil} (@pxref{Quick Help Customization}). This behavior is useful -only if icons are allowed to accept keyboard input (which depends on the -window manager and other factors). -@end table - -@findex ediff-setup-windows -To make more creative changes in the way Ediff sets up windows, you can -rewrite the function @code{ediff-setup-windows}. However, we believe -that detaching Ediff Control Panel from the rest and making it into a -separate frame offers an important opportunity by allowing you to -iconify that frame. The icon will usually accept all of the Ediff -commands, but will free up valuable real estate on your screen (this may -depend on your window manager, though). - -The following variable controls how windows are set up: - -@table @code -@item ediff-window-setup-function -@vindex ediff-window-setup-function -The multiframe setup is done by the -@code{ediff-setup-windows-multiframe} function, which is the default on -windowing displays. The plain setup, one where all windows are always -in one frame, is done by @code{ediff-setup-windows-plain}, which is the -default on a non-windowing display (or in an xterm window). In fact, -under Emacs, you can switch freely between these two setups by executing -the command @code{ediff-toggle-multiframe} using the Minibuffer of the -Menubar. -@findex ediff-setup-windows-multiframe -@findex ediff-setup-windows-plain -@findex ediff-toggle-multiframe - -If you don't like any of these setups, write your own function. See the -documentation for @code{ediff-window-setup-function} for the basic -guidelines. However, writing window setups is not easy, so you should -first take a close look at @code{ediff-setup-windows-plain} and -@code{ediff-setup-windows-multiframe}. -@end table - -You can run multiple Ediff sessions at once, by invoking Ediff several -times without exiting previous Ediff sessions. Different sessions -may even operate on the same pair of files. - -Each session has its own Ediff Control Panel and all the regarding a -particular session is local to the associated control panel buffer. You -can switch between sessions by suspending one session and then switching -to another control panel. (Different control panel buffers are -distinguished by a numerical suffix, e.g., @samp{Ediff Control Panel<3>}.) - -@node Selective Browsing, Highlighting Difference Regions, Window and Frame Configuration, Customization -@section Selective Browsing - -Sometimes it is convenient to be able to step through only some difference -regions, those that match certain regular expressions, and to ignore all -others. On other occasions, you may want to ignore difference regions that -match some regular expressions, and to look only at the rest. - -The commands @kbd{#f} and @kbd{#h} let you do precisely this. - -Typing @kbd{#f} lets you specify regular expressions that match difference -regions you want to focus on. -We shall call these regular expressions @var{regexp-A}, @var{regexp-B} and -@var{regexp-C}. -Ediff will then start stepping through only those difference regions -where the region in buffer A matches @var{regexp-A} and/or the region in -buffer B matches @var{regexp-B}, etc. Whether `and' or `or' will be used -depends on how you respond to a question. - -When scanning difference regions for the aforesaid regular expressions, -Ediff narrows the buffers to those regions. This means that you can use -the expressions @kbd{\`} and @kbd{\'} to tie search to the beginning or end -of the difference regions. - -On the other hand, typing @kbd{#h} lets you specify (hide) uninteresting -regions. That is, if a difference region in buffer A matches -@var{regexp-A}, the corresponding region in buffer B matches @var{regexp-B} -and (if applicable) buffer C's region matches @var{regexp-C}, then the -region will be ignored by the commands @kbd{n}/@key{SPC} -(@code{ediff-next-difference}) and @kbd{p}/@key{DEL} -(@code{ediff-previous-difference}) commands. - -Typing @kbd{#f} and @kbd{#h} toggles selective browsing on and off. - -Note that selective browsing affects only @code{ediff-next-difference} -and @code{ediff-previous-difference}, i.e., the commands -@kbd{n}/@key{SPC} and @kbd{p}/@key{DEL}. @kbd{#f} and @kbd{#h} do not -change the position of the point in the buffers. And you can still jump -directly (using @kbd{j}) to any numbered -difference. - -Users can supply their own functions to specify how Ediff should do -selective browsing. To change the default Ediff function, add a function to -@code{ediff-load-hook} which will do the following assignments: - -@example -(setq ediff-hide-regexp-matches-function 'your-hide-function) -(setq ediff-focus-on-regexp-matches-function 'your-focus-function) -@end example - -@strong{Useful hint}: To specify a regexp that matches everything, don't -simply type @key{RET} in response to a prompt. Typing @key{RET} tells Ediff -to accept the default value, which may not be what you want. Instead, you -should enter something like @key{^} or @key{$}. These match every -line. - -You can use the status command, @kbd{i}, to find out whether -selective browsing is currently in effect. - -The regular expressions you specified are kept in the local variables -@code{ediff-regexp-focus-A}, @code{ediff-regexp-focus-B}, -@code{ediff-regexp-focus-C}, @code{ediff-regexp-hide-A}, -@code{ediff-regexp-hide-B}, @code{ediff-regexp-hide-C}. Their default value -is the empty string (i.e., nothing is hidden or focused on). To change the -default, set these variables in @file{.emacs} using @code{setq-default}. - -In addition to the ability to ignore regions that match regular -expressions, Ediff can be ordered to start skipping over certain -``uninteresting'' difference regions. This is controlled by the following -variable: - -@table @code -@item ediff-ignore-similar-regions -@vindex ediff-ignore-similar-regions -If @code{t}, causes Ediff to skip over "uninteresting" difference regions, -which are the regions where the variants differ only in the amount of the -white space and newlines. This feature can be toggled on/off interactively, -via the command @kbd{##}. -@end table - -@strong{Please note:} in order for this feature to work, auto-refining of -difference regions must be on, since otherwise Ediff won't know if there -are fine differences between regions. On devices where Emacs can display -faces, auto-refining is a default, but it is not turned on by default on -text-only terminals. In that case, you must explicitly turn auto-refining -on (such as, by typing @kbd{@@}). - -@strong{Reassurance:} If many such uninteresting regions appear in a row, -Ediff may take a long time to skip over them because it has to compute fine -differences of all intermediate regions. This delay does not indicate any -problem. - -@vindex ediff-ignore-case-option -@vindex ediff-ignore-case-option3 -@vindex ediff-ignore-case -Finally, Ediff can be told to ignore the case of the letters. This behavior -can be toggled with @kbd{#c} and it is controlled with three variables: -@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3}, and -@code{ediff-ignore-case}. - -The variable @code{ediff-ignore-case-option} specifies the option to pass -to the diff program for comparing two files or buffers. For GNU -@code{diff}, this option is @code{"-i"}. The variable -@code{ediff-ignore-case-option3} specifies the option to pass to the -@code{diff3} program in order to make it case-insensitive. GNU @code{diff3} -does not have such an option, so when merging or comparing three files with -this program, ignoring the letter case is not supported. - -The variable @code{ediff-ignore-case} controls whether Ediff starts out by -ignoring letter case or not. It can be set in @file{.emacs} using -@code{setq-default}. - -When case sensitivity is toggled, all difference -regions are recomputed. - -@node Highlighting Difference Regions, Narrowing, Selective Browsing, Customization -@section Highlighting Difference Regions - -The following variables control the way Ediff highlights difference -regions: - -@table @code -@item ediff-before-flag-bol -@itemx ediff-after-flag-eol -@itemx ediff-before-flag-mol -@itemx ediff-after-flag-mol -@vindex ediff-before-flag-bol -@vindex ediff-after-flag-eol -@vindex ediff-before-flag-mol -@vindex ediff-after-flag-mol -These variables hold strings that Ediff uses to mark the beginning and the -end of the differences found in files A, B, and C on devices where Emacs -cannot display faces. Ediff uses different flags to highlight regions that -begin/end at the beginning/end of a line or in a middle of a line. - -@item ediff-current-diff-face-A -@itemx ediff-current-diff-face-B -@itemx ediff-current-diff-face-C -@vindex ediff-current-diff-face-A -@vindex ediff-current-diff-face-B -@vindex ediff-current-diff-face-C -Ediff uses these faces to highlight current differences on devices where -Emacs can display faces. These and subsequently described faces can be set -either in @file{.emacs} or in @file{.Xdefaults}. The X resource for Ediff -is @samp{Ediff}, @emph{not} @samp{emacs}. Please refer to Emacs manual for -the information on how to set X resources. -@item ediff-fine-diff-face-A -@itemx ediff-fine-diff-face-B -@itemx ediff-fine-diff-face-C -@vindex ediff-fine-diff-face-A -@vindex ediff-fine-diff-face-B -@vindex ediff-fine-diff-face-C -Ediff uses these faces to show the fine differences between the current -differences regions in buffers A, B, and C, respectively. - -@item ediff-even-diff-face-A -@itemx ediff-even-diff-face-B -@itemx ediff-even-diff-face-C -@itemx ediff-odd-diff-face-A -@itemx ediff-odd-diff-face-B -@itemx ediff-odd-diff-face-C -@vindex ediff-even-diff-face-A -@vindex ediff-even-diff-face-B -@vindex ediff-even-diff-face-C -@vindex ediff-odd-diff-face-A -@vindex ediff-odd-diff-face-B -@vindex ediff-odd-diff-face-C -Non-current difference regions are displayed using these alternating -faces. The odd and the even faces are actually identical on monochrome -displays, because without colors options are limited. -So, Ediff uses italics to highlight non-current differences. - -@item ediff-force-faces -@vindex ediff-force-faces -Ediff generally can detect when Emacs is running on a device where it can -use highlighting with faces. However, if it fails to determine that faces -can be used, the user can set this variable to @code{t} to make sure that -Ediff uses faces to highlight differences. - -@item ediff-highlight-all-diffs -@vindex ediff-highlight-all-diffs -Indicates whether---on a windowing display---Ediff should highlight -differences using inserted strings (as on text-only terminals) or using -colors and highlighting. Normally, Ediff highlights all differences, but -the selected difference is highlighted more visibly. One can cycle through -various modes of highlighting by typing @kbd{h}. By default, Ediff starts -in the mode where all difference regions are highlighted. If you prefer to -start in the mode where unselected differences are not highlighted, you -should set @code{ediff-highlight-all-diffs} to @code{nil}. Type @kbd{h} to -restore highlighting for all differences. - -Ediff lets you switch between the two modes of highlighting. That is, -you can switch interactively from highlighting using faces to -highlighting using string flags, and back. Of course, switching has -effect only under a windowing system. On a text-only terminal or in an -xterm window, the only available option is highlighting with strings. -@end table - -@noindent -If you want to change the default settings for @code{ediff-force-faces} and -@code{ediff-highlight-all-diffs}, you must do it @strong{before} Ediff is -loaded. - -You can also change the defaults for the faces used to highlight the -difference regions. There are two ways to do this. The simplest and the -preferred way is to use the customization widget accessible from the -menubar. Ediff's customization group is located under "Tools", which in -turn is under "Programming". The faces that are used to highlight -difference regions are located in the "Highlighting" subgroup of the Ediff -customization group. - -The second, much more arcane, method to change default faces is to include -some Lisp code in @file{~/.emacs}. For instance, - -@example -(setq ediff-current-diff-face-A - (copy-face 'bold-italic 'ediff-current-diff-face-A)) -@end example - -@noindent -would use the pre-defined face @code{bold-italic} to highlight the current -difference region in buffer A (this face is not a good choice, by the way). - -If you are unhappy with just @emph{some} of the aspects of the default -faces, you can modify them when Ediff is being loaded using -@code{ediff-load-hook}. For instance: - -@smallexample -(add-hook 'ediff-load-hook - (lambda () - (set-face-foreground - ediff-current-diff-face-B "blue") - (set-face-background - ediff-current-diff-face-B "red") - (make-face-italic - ediff-current-diff-face-B))) -@end smallexample - -@strong{Please note:} to set Ediff's faces, use only @code{copy-face} -or @code{set/make-face-@dots{}} as shown above. Emacs's low-level -face-manipulation functions should be avoided. - -@node Narrowing, Refinement of Difference Regions, Highlighting Difference Regions, Customization -@section Narrowing - -If buffers being compared are narrowed at the time of invocation of -Ediff, @code{ediff-buffers} will preserve the narrowing range. However, -if @code{ediff-files} is invoked on the files visited by these buffers, -that would widen the buffers, since this command is defined to compare the -entire files. - -Calling @code{ediff-regions-linewise} or @code{ediff-windows-linewise}, or -the corresponding @samp{-wordwise} commands, narrows the variants to the -particular regions being compared. The original accessible ranges are -restored when you quit Ediff. During the command, you can toggle this -narrowing on and off with the @kbd{%} command. - -These two variables control this narrowing behavior: - -@table @code -@item ediff-start-narrowed -@vindex ediff-start-narrowed -If @code{t}, Ediff narrows the display to the appropriate range when it -is invoked with an @samp{ediff-regions@dots{}} or -@samp{ediff-windows@dots{}} command. If @code{nil}, these commands do -not automatically narrow, but you can still toggle narrowing on and off -by typing @kbd{%}. - -@item ediff-quit-widened -@vindex ediff-quit-widened -Controls whether on quitting Ediff should restore the accessible range -that existed before the current invocation. -@end table - -@node Refinement of Difference Regions, Patch and Diff Programs, Narrowing, Customization -@section Refinement of Difference Regions - -Ediff has variables to control the way fine differences are -highlighted. This feature gives you control over the process of refinement. -Note that refinement ignores spaces, tabs, and newlines. - -@table @code -@item ediff-auto-refine -@vindex ediff-auto-refine -This variable controls whether fine differences within regions are -highlighted automatically (``auto-refining''). The default is yes -(@samp{on}). - -On a slow machine, automatic refinement may be painful. In that case, -you can turn auto-refining on or off interactively by typing -@kbd{@@}. You can also turn off display of refining that has -already been done. - -When auto-refining is off, fine differences are shown only for regions -for which these differences have been computed and saved before. If -auto-refining and display of refining are both turned off, fine -differences are not shown at all. - -Typing @kbd{*} computes and displays fine differences for the current -difference region, regardless of whether auto-refining is turned on. - -@item ediff-auto-refine-limit -@vindex ediff-auto-refine-limit -If auto-refining is on, this variable limits the size of the regions to -be auto-refined. This guards against the possible slowdown that may be -caused by extraordinary large difference regions. - -You can always refine the current region by typing @kbd{*}. - -@item ediff-forward-word-function -@vindex ediff-forward-word-function -This variable controls how fine differences are computed. The -value must be a Lisp function that determines how the current difference -region should be split into words. - -@vindex ediff-diff-program -@vindex ediff-forward-word-function -@findex ediff-forward-word -Fine differences are computed by first splitting the current difference -region into words and then passing the result to -@code{ediff-diff-program}. For the default forward word function (which is -@code{ediff-forward-word}), a word is a string consisting of letters, -@samp{-}, or @samp{_}; a string of punctuation symbols; a string of digits, -or a string consisting of symbols that are neither space, nor a letter. - -This default behavior is controlled by four variables: @code{ediff-word-1}, -..., @code{ediff-word-4}. See the on-line documentation for these variables -and for the function @code{ediff-forward-word} for an explanation of how to -modify these variables. -@vindex ediff-word-1 -@vindex ediff-word-2 -@vindex ediff-word-3 -@vindex ediff-word-4 -@end table - -Sometimes, when a region has too many differences between the variants, -highlighting of fine differences is inconvenient, especially on -color displays. If that is the case, type @kbd{*} with a negative -prefix argument. This unhighlights fine differences for the current -region. - -To unhighlight fine differences in all difference regions, use the -command @kbd{@@}. Repeated typing of this key cycles through three -different states: auto-refining, no-auto-refining, and no-highlighting -of fine differences. - -@node Patch and Diff Programs, Merging and diff3, Refinement of Difference Regions, Customization -@section Patch and Diff Programs - -This section describes variables that specify the programs to be used for -applying patches and for computing the main difference regions (not the -fine difference regions): - -@table @code -@item ediff-diff-program -@itemx ediff-diff3-program -@vindex ediff-patch-program -@vindex ediff-diff-program -@vindex ediff-diff3-program -These variables specify the programs to use to produce differences -and do patching. - -@item ediff-diff-options -@itemx ediff-diff3-options -@vindex ediff-patch-options -@vindex ediff-diff-options -@vindex ediff-diff3-options -These variables specify the options to pass to the above utilities. - -In @code{ediff-diff-options}, it may be useful to specify options -such as @samp{-w} that ignore certain kinds of changes. However, -Ediff does not let you use the option @samp{-c}, as it doesn't recognize this -format yet. - -@item ediff-coding-system-for-read -@vindex ediff-coding-system-for-read -This variable specifies the coding system to use when reading the output -that the programs @code{diff3} and @code{diff} send to Emacs. The default -is @code{raw-text}, and this should work fine in Unix and in most -cases under Windows NT/95/98/2000. There are @code{diff} programs -for which the default option doesn't work under Windows. In such cases, -@code{raw-text-dos} might work. If not, you will have to experiment with -other coding systems or use GNU diff. - -@item ediff-patch-program -The program to use to apply patches. Since there are certain -incompatibilities between the different versions of the patch program, the -best way to stay out of trouble is to use a GNU-compatible version. -Otherwise, you may have to tune the values of the variables -@code{ediff-patch-options}, @code{ediff-backup-specs}, and -@code{ediff-backup-extension} as described below. -@item ediff-patch-options -Options to pass to @code{ediff-patch-program}. - -Note: the `-b' and `-z' options should be specified in -`ediff-backup-specs', not in @code{ediff-patch-options}. - -It is recommended to pass the `-f' option to the patch program, so it won't -ask questions. However, some implementations don't accept this option, in -which case the default value of this variable should be changed. - -@item ediff-backup-extension -Backup extension used by the patch program. Must be specified, even if -@code{ediff-backup-specs} is given. -@item ediff-backup-specs -Backup directives to pass to the patch program. -Ediff requires that the old version of the file (before applying the patch) -is saved in a file named @file{the-patch-file.extension}. Usually -`extension' is `.orig', but this can be changed by the user, and may also be -system-dependent. Therefore, Ediff needs to know the backup extension used -by the patch program. - -Some versions of the patch program let the user specify `-b backup-extension'. -Other versions only permit `-b', which (usually) assumes the extension `.orig'. -Yet others force you to use `-z'. - -Note that both `ediff-backup-extension' and `ediff-backup-specs' must be -properly set. If your patch program takes the option `-b', but not -`-b extension', the variable `ediff-backup-extension' must still -be set so Ediff will know which extension to use. - -@item ediff-custom-diff-program -@itemx ediff-custom-diff-options -@vindex ediff-custom-diff-program -@vindex ediff-custom-diff-options -@findex ediff-save-buffer -Because Ediff limits the options you may want to pass to the @code{diff} -program, it partially makes up for this drawback by letting you save the -output from @code{diff} in your preferred format, which is specified via -the above two variables. - -The output generated by @code{ediff-custom-diff-program} (which doesn't -even have to be a standard-style @code{diff}!)@: is not used by Ediff. It is -provided exclusively so that you can -refer to -it later, send it over email, etc. For instance, after reviewing the -differences, you may want to send context differences to a colleague. -Since Ediff ignores the @samp{-c} option in -@code{ediff-diff-program}, you would have to run @code{diff -c} separately -just to produce the list of differences. Fortunately, -@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options} -eliminate this nuisance by keeping a copy of a difference list in the -desired format in a buffer that can be displayed via the command @kbd{D}. - -@item ediff-patch-default-directory -@vindex ediff-patch-default-directory -Specifies the default directory to look for patches. - -@end table - -@noindent -@strong{Warning:} Ediff does not support the output format of VMS -@code{diff}. Instead, make sure you are using some implementation of POSIX -@code{diff}, such as @code{gnudiff}. - -@node Merging and diff3, Support for Version Control, Patch and Diff Programs, Customization -@section Merging and diff3 - -Ediff supports three-way comparison via the functions @code{ediff-files3} and -@code{ediff-buffers3}. The interface is the same as for two-way comparison. -In three-way comparison and merging, Ediff reports if any two difference -regions are identical. For instance, if the current region in buffer A -is the same as the region in buffer C, then the mode line of buffer A will -display @samp{[=diff(C)]} and the mode line of buffer C will display -@samp{[=diff(A)]}. - -Merging is done according to the following algorithm. - -If a difference region in one of the buffers, say B, differs from the ancestor -file while the region in the other buffer, A, doesn't, then the merge buffer, -C, gets B's region. Similarly when buffer A's region differs from -the ancestor and B's doesn't, A's region is used. - -@vindex ediff-default-variant -If both regions in buffers A and B differ from the ancestor file, Ediff -chooses the region according to the value of the variable -@code{ediff-default-variant}. If its value is @code{default-A} then A's -region is chosen. If it is @code{default-B} then B's region is chosen. -If it is @code{combined} then the region in buffer C will look like -this: - -@comment Use @set to avoid triggering merge conflict detectors like CVS. -@set seven-left <<<<<<< -@set seven-right >>>>>>> -@example -@value{seven-left} variant A -the difference region from buffer A -@value{seven-right} variant B -the difference region from buffer B -####### Ancestor -the difference region from the ancestor buffer, if available -======= end -@end example - -The above is the default template for the combined region. The user can -customize this template using the variable -@code{ediff-combination-pattern}. - -@vindex ediff-combination-pattern -The variable @code{ediff-combination-pattern} specifies the template that -determines how the combined merged region looks like. The template is -represented as a list of the form @code{(STRING1 Symbol1 STRING2 Symbol2 -STRING3 Symbol3 STRING4)}. The symbols here must be atoms of the form -@code{A}, @code{B}, or @code{Ancestor}. They determine the order in which -the corresponding difference regions (from buffers A, B, and the ancestor -buffer) are displayed in the merged region of buffer C. The strings in the -template determine the text that separates the aforesaid regions. The -default template is - -@smallexample -("@value{seven-left} variant A" A "@value{seven-right} variant B" B - "####### Ancestor" Ancestor "======= end") -@end smallexample - -@noindent -(this is one long line) and the corresponding combined region is shown -above. The order in which the regions are shown (and the separator -strings) can be changed by changing the above template. It is even -possible to add or delete region specifiers in this template (although -the only possibly useful such modification seems to be the deletion of -the ancestor). - -In addition to the state of the difference, Ediff displays the state of the -merge for each region. If a difference came from buffer A by default -(because both regions A and B were different from the ancestor and -@code{ediff-default-variant} was set to @code{default-A}) then -@samp{[=diff(A) default-A]} is displayed in the mode line. If the -difference in buffer C came, say, from buffer B because the difference -region in that buffer differs from the ancestor, but the region in buffer A -does not (if merging with an ancestor) then @samp{[=diff(B) prefer-B]} is -displayed. The indicators default-A/B and prefer-A/B are inspired by -Emerge and have the same meaning. - -Another indicator of the state of merge is @samp{combined}. It appears -with any difference region in buffer C that was obtained by combining -the difference regions in buffers A and B as explained above. - -In addition to the state of merge and state of difference indicators, while -merging with an ancestor file or buffer, Ediff informs the user when the -current difference region in the (normally invisible) ancestor buffer is -empty via the @emph{AncestorEmpty} indicator. This helps determine if the -changes made to the original in variants A and B represent pure insertion -or deletion of text: if the mode line shows @emph{AncestorEmpty} and the -corresponding region in buffers A or B is not empty, this means that new -text was inserted. If this indicator is not present and the difference -regions in buffers A or B are non-empty, this means that text was -modified. Otherwise, the original text was deleted. - -Although the ancestor buffer is normally invisible, Ediff maintains -difference regions there and advances the current difference region -accordingly. All highlighting of difference regions is provided in the -ancestor buffer, except for the fine differences. Therefore, if desired, the -user can put the ancestor buffer in a separate frame and watch it -there. However, on a TTY, only one frame can be visible at any given time, -and Ediff doesn't support any single-frame window configuration where all -buffers, including the ancestor buffer, would be visible. However, the -ancestor buffer can be displayed by typing @kbd{/} to the control -window. (Type @kbd{C-l} to hide it again.) - -Note that the state-of-difference indicators @samp{=diff(A)} and -@samp{=diff(B)} above are not redundant, even in the presence of a -state-of-merge indicator. In fact, the two serve different purposes. - -For instance, if the mode line displays @samp{=diff(B) prefer(B)} and -you copy a difference region from buffer A to buffer C then -@samp{=diff(B)} will change to @samp{diff-A} and the mode line will -display @samp{=diff(A) prefer-B}. This indicates that the difference -region in buffer C is identical to that in buffer A, but originally -buffer C's region came from buffer B. This is useful to know because -you can recover the original difference region in buffer C by typing -@kbd{r}. - - -Ediff never changes the state-of-merge indicator, except in response to -the @kbd{!} command (see below), in which case the indicator is lost. -On the other hand, the state-of-difference indicator is changed -automatically by the copying/recovery commands, @kbd{a}, @kbd{b}, @kbd{r}, -@kbd{+}. - -The @kbd{!} command loses the information about origins of the regions -in the merge buffer (default-A, prefer-B, or combined). This is because -recomputing differences in this case means running @code{diff3} on -buffers A, B, and the merge buffer, not on the ancestor buffer. (It -makes no sense to recompute differences using the ancestor file, since -in the merging mode Ediff assumes that you have not edited buffers A and -B, but that you may have edited buffer C, and these changes are to be -preserved.) Since some difference regions may disappear as a result of -editing buffer C and others may arise, there is generally no simple way -to tell where the various regions in the merge buffer came from. - -In three-way comparison, Ediff tries to disregard regions that consist -entirely of white space. For instance, if, say, the current region in -buffer A consists of the white space only (or if it is empty), Ediff will -not take it into account for the purpose of computing fine differences. The -result is that Ediff can provide a better visual information regarding the -actual fine differences in the non-white regions in buffers B and -C. Moreover, if the regions in buffers B and C differ in the white space -only, then a message to this effect will be displayed. - -@vindex ediff-merge-window-share -In the merge mode, the share of the split between window C (the window -displaying the merge-buffer) and the windows displaying buffers A and B -is controlled by the variable @code{ediff-merge-window-share}. Its -default value is 0.5. To make the merge-buffer window smaller, reduce -this amount. - -We don't recommend increasing the size of the merge-window to more than -half the frame (i.e., to increase the value of -@code{ediff-merge-window-share}) to more than 0.5, since it would be -hard to see the contents of buffers A and B. - -You can temporarily shrink the merge window to just one line by -typing @kbd{s}. This change is temporary, until Ediff finds a reason to -redraw the screen. Typing @kbd{s} again restores the original window size. - -With a positive prefix argument, the @kbd{s} command will make the merge -window slightly taller. This change is persistent. With `@kbd{-}' or -with a negative prefix argument, the command @kbd{s} makes the merge -window slightly shorter. This change also persistent. - -@vindex ediff-show-clashes-only -Ediff lets you automatically ignore the regions where only one of the -buffers A and B disagrees with the ancestor. To do this, set the -variable @code{ediff-show-clashes-only} to non-@code{nil}. - -You can toggle this feature interactively by typing @kbd{$$}. - -Note that this variable affects only the show next/previous difference -commands. You can still jump directly to any difference region directly -using the command @kbd{j} (with a prefix argument specifying the difference -number). - -@vindex ediff-autostore-merges -@vindex ediff-quit-merge-hook -@findex ediff-maybe-save-and-delete-merge -The variable @code{ediff-autostore-merges} controls what happens to the -merge buffer when Ediff quits. If the value is @code{nil}, nothing is done -to the merge buffer---it will be the user's responsibility to save it. -If the value is @code{t}, the user will be asked where to save the buffer -and whether to delete it afterwards. It the value is neither @code{nil} nor -@code{t}, the merge buffer is saved @emph{only} if this merge session was -invoked from a group of related Ediff session, such as those that result -from @code{ediff-merge-directories}, -@code{ediff-merge-directory-revisions}, etc. -@xref{Session Groups}. This behavior is implemented in the function -@code{ediff-maybe-save-and-delete-merge}, which is a hook in -@code{ediff-quit-merge-hook}. The user can supply a different hook, if -necessary. - -The variable @code{ediff-autostore-merges} is buffer-local, so it can be -set in a per-buffer manner. Therefore, use @code{setq-default} to globally -change this variable. - -@vindex ediff-merge-filename-prefix -When merge buffers are saved automatically as directed by -@code{ediff-autostore-merges}, Ediff attaches a prefix to each file, as -specified by the variable @code{ediff-merge-filename-prefix}. The default -is @code{merge_}, but this can be changed by the user. - -@node Support for Version Control, Customizing the Mode Line, Merging and diff3, Customization -@section Support for Version Control - - -Ediff supports version control and lets you compare versions of files -visited by Emacs buffers via the function @code{ediff-revision}. This -feature is controlled by the following variables: - -@table @code -@item ediff-version-control-package -@vindex ediff-version-control-package -A symbol. The default is @samp{vc}. - -If you are like most Emacs users, Ediff will use VC as the version control -package. This is the standard Emacs interface to RCS, CVS, and SCCS. - -However, if your needs are better served by other interfaces, you will -have to tell Ediff which version control package you are using, e.g., -@example -(setq ediff-version-control-package 'rcs) -@end example - -Apart from the standard @file{vc.el}, Ediff supports three other interfaces -to version control: @file{rcs.el}, @file{pcl-cvs.el} (recently renamed -pcvs.el), and @file{generic-sc.el}. The package @file{rcs.el} is written -by Sebastian Kremer and is available as -@example -@file{ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z} -@file{ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z} -@end example -@pindex @file{vc.el} -@pindex @file{rcs.el} -@pindex @file{pcl-cvs.el} -@pindex @file{generic-sc.el} -@end table - -Ediff's interface to the above packages allows the user to compare the -versions of the current buffer or to merge them (with or without an -ancestor-version). These operations can also be performed on directories -containing files under version control. - -In case of @file{pcl-cvs.el}, Ediff can also be invoked via the function -@code{run-ediff-from-cvs-buffer}---see the documentation string for this -function. - -@node Customizing the Mode Line, Miscellaneous, Support for Version Control, Customization -@section Customizing the Mode Line - -When Ediff is running, the mode line of @samp{Ediff Control Panel} -buffer shows the current difference number and the total number of -difference regions in the two files. - -The mode line of the buffers being compared displays the type of the -buffer (@samp{A:}, @samp{B:}, or @samp{C:}) and (usually) the file name. -Ediff tries to be intelligent in choosing the mode line buffer -identification. In particular, it works well with the -@file{uniquify.el} and @file{mode-line.el} packages (which improve on -the default way in which Emacs displays buffer identification). If you -don't like the way Ediff changes the mode line, you can use -@code{ediff-prepare-buffer-hook} to modify the mode line. -@vindex ediff-prepare-buffer-hook -@pindex @file{uniquify.el} -@pindex @file{mode-line.el} - -@node Miscellaneous, Notes on Heavy-duty Customization, Customizing the Mode Line, Customization -@section Miscellaneous - -Here are a few other variables for customizing Ediff: - -@table @code -@item ediff-split-window-function -@vindex ediff-split-window-function -Controls the way you want the window be split between file-A and file-B -(and file-C, if applicable). It defaults to the vertical split -(@code{split-window-vertically}, but you can set it to -@code{split-window-horizontally}, if you so wish. -Ediff also lets you switch from vertical to horizontal split and back -interactively. - -Note that if Ediff detects that all the buffers it compares are displayed in -separate frames, it assumes that the user wants them to be so displayed -and stops splitting windows. Instead, it arranges for each buffer to -be displayed in a separate frame. You can switch to the one-frame mode -by hiding one of the buffers A/B/C. - -You can also swap the windows where buffers are displayed by typing -@kbd{~}. - -@item ediff-merge-split-window-function -@vindex ediff-merge-split-window-function -Controls how windows are -split between buffers A and B in the merge mode. -This variable is like @code{ediff-split-window-function}, but it defaults -to @code{split-window-horizontally} instead of -@code{split-window-vertically}. - -@item ediff-make-wide-display-function -@vindex ediff-make-wide-display-function -The value is a function to be called to widen the frame for displaying -the Ediff buffers. See the on-line documentation for -@code{ediff-make-wide-display-function} for details. It is also -recommended to look into the source of the default function -@code{ediff-make-wide-display}. - -You can toggle wide/regular display by typing @kbd{m}. In the wide -display mode, buffers A, B (and C, when applicable) are displayed in a -single frame that is as wide as the entire workstation screen. This is -useful when files are compared side-by-side. By default, the display is -widened without changing its height. - -@item ediff-use-last-dir -@vindex ediff-use-last-dir -Controls the way Ediff presents the -default directory when it prompts the user for files to compare. If -@code{nil}, -Ediff uses the default directory of the current buffer when it -prompts the user for file names. Otherwise, it will use the -directories it had previously used for files A, B, or C, respectively. - -@item ediff-no-emacs-help-in-control-buffer -@vindex ediff-no-emacs-help-in-control-buffer -If @code{t}, makes @kbd{C-h} -behave like the @key{DEL} key, i.e., it will move you back to the previous -difference rather than invoking help. This is useful when, in an xterm -window or a text-only terminal, the Backspace key is bound to @kbd{C-h} and is -positioned more conveniently than the @key{DEL} key. - -@item ediff-toggle-read-only-function -@vindex ediff-toggle-read-only-function -This variable's value is a function that Ediff uses to toggle -the read-only property in its buffers. - -The default function that Ediff uses simply toggles the read-only property, -unless the file is under version control. For a checked-in file under -version control, Ediff first tries to check the file out. - -@item ediff-make-buffers-readonly-at-startup nil -@vindex ediff-make-buffers-readonly-at-startup -If @code{t}, all variant buffers are made read-only at Ediff startup. - -@item ediff-keep-variants -@vindex @code{ediff-keep-variants} -The default is @code{t}, meaning that the buffers being compared or merged will -be preserved when Ediff quits. Setting this to @code{nil} causes Ediff to -offer the user a chance to delete these buffers (if they are not modified). -Supplying a prefix argument to the quit command (@code{q}) temporarily -reverses the meaning of this variable. This is convenient when the user -prefers one of the behaviors most of the time, but occasionally needs the -other behavior. - -However, Ediff temporarily resets this variable to @code{t} if it is -invoked via one of the "buffer" jobs, such as @code{ediff-buffers}. -This is because it is all too easy to lose a day's work otherwise. -Besides, in a "buffer" job, the variant buffers have already been loaded -prior to starting Ediff, so Ediff just preserves status quo here. - -Using @code{ediff-cleanup-hook}, one can make Ediff delete the variants -unconditionally (e.g., by making @code{ediff-janitor} into one of these hooks). - -@item ediff-keep-tmp-versions -@vindex @code{ediff-keep-tmp-versions} -Default is @code{nil}. If @code{t}, the versions of the files being -compared or merged using operations such as @code{ediff-revision} or -@code{ediff-merge-revisions} are not deleted on exit. The normal action is -to clean up and delete these version files. - -@item ediff-grab-mouse -@vindex @code{ediff-grab-mouse} -Default is @code{t}. Normally, Ediff grabs mouse and puts it in its -control frame. This is useful since the user can be sure that when he -needs to type an Ediff command the focus will be in an appropriate Ediff's -frame. However, some users prefer to move the mouse by themselves. The -above variable, if set to @code{maybe}, will prevent Ediff from grabbing -the mouse in many situations, usually after commands that may take more -time than usual. In other situation, Ediff will continue grabbing the mouse -and putting it where it believes is appropriate. If the value is -@code{nil}, then mouse is entirely user's responsibility. -Try different settings and see which one is for you. -@end table - - -@node Notes on Heavy-duty Customization, , Miscellaneous, Customization -@section Notes on Heavy-duty Customization - -Some users need to customize Ediff in rather sophisticated ways, which -requires different defaults for different kinds of files (e.g., SGML, -etc.). Ediff supports this kind of customization in several ways. First, -most customization variables are buffer-local. Those that aren't are -usually accessible from within Ediff Control Panel, so one can make them -local to the panel by calling make-local-variable from within -@code{ediff-startup-hook}. - -Second, the function @code{ediff-setup} accepts an optional sixth -argument which has the form @code{((@var{var-name-1} .@: @var{val-1}) -(@var{var-name-2} .@: @var{val-2}) @dots{})}. The function -@code{ediff-setup} sets the variables in the list to the respective -values, locally in the Ediff control buffer. This is an easy way to -throw in custom variables (which usually should be buffer-local) that -can then be tested in various hooks. - -Make sure the variable @code{ediff-job-name} and @code{ediff-word-mode} are set -properly in this case, as some things in Ediff depend on this. - -Finally, if you want custom-tailored help messages, you can set the -variables @code{ediff-brief-help-message-function} and -@code{ediff-long-help-message-function} -to functions that return help strings. -@vindex ediff-startup-hook -@findex ediff-setup -@vindex ediff-job-name -@vindex ediff-word-mode -@vindex ediff-brief-help-message-function -@vindex ediff-long-help-message-function - -When customizing Ediff, some other variables are useful, although they are -not user-definable. They are local to the Ediff control buffer, so this -buffer must be current when you access these variables. The control buffer -is accessible via the variable @code{ediff-control-buffer}, which is also -local to that buffer. It is usually used for checking if the current buffer -is also the control buffer. - -Other variables of interest are: -@table @code -@item ediff-buffer-A -The first of the data buffers being compared. - -@item ediff-buffer-B -The second of the data buffers being compared. - -@item ediff-buffer-C -In three-way comparisons, this is the third buffer being compared. -In merging, this is the merge buffer. -In two-way comparison, this variable is @code{nil}. - -@item ediff-window-A -The window displaying buffer A. If buffer A is not visible, this variable -is @code{nil} or it may be a dead window. - -@item ediff-window-B -The window displaying buffer B. - -@item ediff-window-C -The window displaying buffer C, if any. - -@item ediff-control-frame -A dedicated frame displaying the control buffer, if it exists. It is -non-@code{nil} only if Ediff uses the multiframe display, i.e., when -the control buffer is in its own frame. -@end table - -@node Credits, GNU Free Documentation License, Customization, Top -@chapter Credits - -Ediff was written by Michael Kifer . It was inspired -by emerge.el written by Dale R.@: Worley . An idea due to -Boris Goldowsky made it possible to highlight -fine differences in Ediff buffers. Alastair Burt -ported Ediff to XEmacs, Eric Freudenthal -made it work with VC, Marc Paquette wrote the -toolbar support package for Ediff, and Hrvoje Niksic -adapted it to the Emacs customization package. - -Many people provided help with bug reports, feature suggestions, and advice. -Without them, Ediff would not be nearly as useful as it is today. -Here is a hopefully full list of contributors: - -@example -Adrian Aichner (aichner at ecf.teradyne.com), -Drew Adams (drew.adams at oracle.com), -Steve Baur (steve at xemacs.org), -Neal Becker (neal at ctd.comsat.com), -E.@: Jay Berkenbilt (ejb at ql.org), -Lennart Borgman (ennart.borgman at gmail.com) -Alastair Burt (burt at dfki.uni-kl.de), -Paul Bibilo (peb at delcam.co.uk), -Kevin Broadey (KevinB at bartley.demon.co.uk), -Harald Boegeholz (hwb at machnix.mathematik.uni-stuttgart.de), -Bradley A.@: Bosch (brad at lachman.com), -Michael D.@: Carney (carney at ltx-tr.com), -Jin S.@: Choi (jin at atype.com), -Scott Cummings (cummings at adc.com), -Albert Dvornik (bert at mit.edu), -Eric Eide (eeide at asylum.cs.utah.edu), -Paul Eggert (eggert at twinsun.com), -Urban Engberg (ue at cci.dk), -Kevin Esler (esler at ch.hp.com), -Robert Estes (estes at ece.ucdavis.edu), -Jay Finger (jayf at microsoft.com), -Xavier Fornari (xavier at europe.cma.fr), -Eric Freudenthal (freudent at jan.ultra.nyu.edu), -Job Ganzevoort (Job.Ganzevoort at cwi.nl), -Felix Heinrich Gatzemeier (felix.g at tzemeier.info), -Boris Goldowsky (boris at cs.rochester.edu), -Allan Gottlieb (gottlieb at allan.ultra.nyu.edu), -Aaron Gross (aaron at bfr.co.il), -Thorbjoern Hansen (thorbjoern.hansen at mchp.siemens.de), -Marcus Harnisch (marcus_harnisch at mint-tech.com), -Steven E. Harris (seh at panix.com), -Aaron S. Hawley (Aaron.Hawley at uvm.edu), -Xiaoli Huang (hxl at epic.com), -Andreas Jaeger (aj at suse.de), -Lars Magne Ingebrigtsen (larsi at ifi.uio.no), -Larry Gouge (larry at itginc.com), -Karl Heuer (kwzh at gnu.org), -(irvine at lks.csi.com), -(jaffe at chipmunk.cita.utoronto.ca), -David Karr (dkarr at nmo.gtegsc.com), -Norbert Kiesel (norbert at i3.informatik.rwth-aachen.de), -Steffen Kilb (skilb at gmx.net), -Leigh L Klotz (klotz at adoc.xerox.com), -Fritz Knabe (Fritz.Knabe at ecrc.de), -Heinz Knutzen (hk at informatik.uni-kiel.d400.de), -Andrew Koenig (ark at research.att.com), -Hannu Koivisto (azure at iki.fi), -Ken Laprade (laprade at dw3f.ess.harris.com), -Will C Lauer (wcl at cadre.com), -Richard Levitte (levitte at e.kth.se), -Mike Long (mike.long at analog.com), -Dave Love (d.love at dl.ac.uk), -Martin Maechler (maechler at stat.math.ethz.ch), -Simon Marshall (simon at gnu.org), -Paul C. Meuse (pmeuse at delcomsys.com), -Richard Mlynarik (mly at adoc.xerox.com), -Stefan Monnier (monnier at cs.yale.edu), -Chris Murphy (murphycm at sun.aston.ac.uk), -Erik Naggum (erik at naggum.no), -Eyvind Ness (Eyvind.Ness at hrp.no), -Ray Nickson (nickson at cs.uq.oz.au), -Dan Nicolaescu (dann at ics.uci.edu), -David Petchey (petchey_david at jpmorgan.com), -Benjamin Pierce (benjamin.pierce at cl.cam.ac.uk), -Francois Pinard (pinard at iro.umontreal.ca), -Tibor Polgar (tlp00 at spg.amdahl.com), -David Prince (dave0d at fegs.co.uk), -Paul Raines (raines at slac.stanford.edu), -Stefan Reicher (xsteve at riic.at), -Charles Rich (rich at merl.com), -Bill Richter (richter at math.nwu.edu), -C.S.@: Roberson (roberson at aur.alcatel.com), -Kevin Rodgers (kevin.rodgers at ihs.com), -Sandy Rutherford (sandy at ibm550.sissa.it), -Heribert Schuetz (schuetz at ecrc.de), -Andy Scott (ascott at pcocd2.intel.com), -Axel Seibert (axel at tumbolia.ppp.informatik.uni-muenchen.de), -Vin Shelton (acs at xemacs.org), -Scott O. Sherman (Scott.Sherman at mci.com), -Nikolaj Schumacher (n_schumacher at web.de), -Richard Stallman (rms at gnu.org), -Richard Stanton (stanton at haas.berkeley.edu), -Sam Steingold (sds at goems.com), -Ake Stenhoff (etxaksf at aom.ericsson.se), -Stig (stig at hackvan.com), -Peter Stout (Peter_Stout at cs.cmu.edu), -Chuck Thompson (cthomp at cs.uiuc.edu), -Ray Tomlinson (tomlinso at bbn.com), -Raymond Toy (toy at rtp.ericsson.se), -Stephen J. Turnbull (stephen at xemacs.org), -Jan Vroonhof (vroonhof at math.ethz.ch), -Colin Walters (walters at cis.ohio-state.edu), -Philippe Waroquiers (philippe.waroquiers at eurocontrol.be), -Klaus Weber (gizmo at zork.north.de), -Ben Wing (ben at xemacs.org), -Tom Wurgler (twurgler at goodyear.com), -Steve Youngs (youngs at xemacs.org), -Ilya Zakharevich (ilya at math.ohio-state.edu), -Eli Zaretskii (eliz at is.elta.co.il) -@end example - -@node GNU Free Documentation License, Index, Credits, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Index, , GNU Free Documentation License, Top -@unnumbered Index -@printindex cp - -@bye diff --git a/doc/misc/edt.texi b/doc/misc/edt.texi deleted file mode 100644 index af0069fb1bc..00000000000 --- a/doc/misc/edt.texi +++ /dev/null @@ -1,944 +0,0 @@ -\input texinfo -@setfilename ../../info/edt -@settitle EDT Emulation for Emacs - -@copying -This file documents the EDT emulation package for Emacs. - -Copyright @copyright{} 1986, 1992, 1994-1995, 1999-2012 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* EDT: (edt). An Emacs emulation of the EDT editor. -@end direntry - -@titlepage -@title EDT Emulation User's Manual -@author Kevin Gallagher -@author @email{Kevin.Gallagher@@boeing.com} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Emacs EDT emulation -This manual describes the Emacs EDT package, which provides emulation -of DEC's EDT editor. - -@insertcopying -@end ifnottex - -@menu -* Overview:: Overview of the EDT package. -* Supported terminals:: Terminals/keyboards that are supported. -* Starting emulation:: How to get started. -* Platform-specific notes:: Notes specific to certain platforms. -* Differences:: How does this EDT emulation differ from real EDT? -* Highlights:: Some highlights, and comparisons to the - original Emacs EDT emulation. -* Customizing:: Customizing emulation. -* GNU Free Documentation License:: The license for this manual. -@end menu - -@node Overview -@chapter Overview of the EDT Package - -This manual describes version 4.0 of the EDT Emulation for Emacs. -It comes with special functions which replicate nearly all of -EDT's keypad mode behavior. It sets up default keypad and function key -bindings which closely match those found in EDT. Support is provided so -that users may reconfigure most keypad and function key bindings to -their own liking. - -Version 4.0 contains several enhancements (@pxref{Changes}). - -@menu -* Quick start:: How to begin using EDT. -* Changes:: What's new in version 4.0. -* Goals:: The aims of this package. -@end menu - -@node Quick start -@section How to Begin Using EDT - -To start the EDT Emulation, first start Emacs and then enter @kbd{M-x -edt-emulation-on} to begin the emulation. After initialization is -complete, the following message will appear below the status line -informing you that the emulation has been enabled: ``Default EDT keymap -active''. - - You can have the EDT Emulation start up automatically, each time you -initiate an Emacs session, by adding the following line to your -@file{.emacs} file: - -@example -(add-hook term-setup-hook 'edt-emulation-on) -@end example - -@noindent @strong{Important:} Be sure to read the rest of this manual. -It contains very useful information on how the EDT Emulation behaves and -how to customize it to your liking. - -@noindent The EDT emulation consists of the following files: - -@itemize - -@item -@file{edt.texi} - This manual. - -@item -@file{edt-user.el} - An example customization file. - -@item -@file{edt.el} - EDT emulation functions and default configuration. - -@item -@file{edt-lk201.el} - Built-in support for DEC LK-201 keyboards. - -@item -@file{edt-vt100.el} - Built-in support for DEC VT-100 (and above) terminals. - -@item -@file{edt-pc.el} - Built-in support for PC 101 Keyboards under MS-DOS. - -@item -@file{edt-mapper.el} - Create an EDT LK-201 map file for keyboards -without built-in support. - -@end itemize - -@node Changes -@section What's New in Version 4.0 - -Version 4.0 contains the following enhancements: - -@enumerate - -@item -Scroll margins at the top and bottom of the window are now supported. -(The design was copied from @file{tpu-extras.el}.) By default, this -feature is enabled with the top margin set to 10% of the window and the -bottom margin set to 15% of the window. To change these settings, you -can invoke the function @code{edt-set-scroll-margins} in your -@file{.emacs} file. For example, the following line - -@example -(edt-set-scroll-margins "20%" "25%") -@end example - -@noindent sets the top margin to 20% of the window and the bottom margin -to 25% of the window. To disable this feature, set each margin to 0%. -You can also invoke @code{edt-set-scroll-margins} interactively while -EDT Emulation is active to change the settings for that session. - -@strong{Please note:} Another way to set the scroll margins is to use -the Emacs customization feature to set the following two variables -directly: @code{edt-top-scroll-margin} and @code{edt-bottom-scroll-margin}. - -Enter the Emacs @code{customize} command. First select the -@samp{Editing} group and then select the @samp{Emulations} group. -Finally, select the @samp{Edt} group and follow the directions. - -@item -The @samp{SUBS} command is now supported and bound to @kbd{GOLD-Enter} -by default. (This design was copied from @file{tpu-edt.el}.) Note, in -earlier versions of EDT Emulation, @kbd{GOLD-Enter} was assigned to the -Emacs function @code{query-replace}. The binding of -@code{query-replace} has been moved to @kbd{GOLD-/}. If you prefer to -restore @code{query-replace} to @kbd{GOLD-Enter}, then use an EDT user -customization file, @file{edt-user.el}, to do this -(@pxref{Customizing}). - -@item -EDT Emulation now also works in XEmacs, including the highlighting of -selected text. - -@item -If you access a workstation using an X Server, observe that the -initialization file generated by @file{edt-mapper.el} will now contain -the name of the X Server vendor. This is a convenience for those who -have access to their Unix account from more than one type of X Server. -Since different X Servers typically require different EDT emulation -initialization files, @file{edt-mapper.el} will now generate these -different initialization files and save them with different names. -Then, the correct initialization file for the particular X server in use -is loaded correctly automatically. - -@item -Also, @file{edt-mapper.el} is now capable of binding an @acronym{ASCII} -key sequence, providing the @acronym{ASCII} key sequence prefix is -already known by Emacs to be a prefix. As a result of providing this -support, some terminal/keyboard/window system configurations, which -don't have a complete set of sensible function key bindings built into -Emacs in @code{function-key-map}, can still be configured for use with -EDT Emulation. (Note: In a few rare circumstances this does not work -properly. In particular, it does not work if a subset of the leading -@acronym{ASCII} characters in a key sequence are recognized by Emacs as -having an existing binding. For example, if the keypad 7 (@key{KP7}) -key generates the sequence @samp{Ow} and @samp{O} is already -bound to a function, pressing @key{KP7} when told to do so by -@file{edt-mapper.el} will result in @file{edt-mapper.el} incorrectly -mapping @samp{O} to @key{KP7} and @samp{w} to @key{KP8}. If -something like this happens to you, it is probably a bug in the support -for your keyboard within Emacs @strong{or} a bug in the Unix -termcap/terminfo support for your terminal @strong{or} a bug in the -terminal emulation software you are using.) - -@item -The @code{edt-quit} function (bound to @kbd{GOLD-q} by default) has been -modified to warn the user when file-related buffer modifications exist. -It now cautions the user that those modifications will be lost if the -user quits without saving those buffers. - -@end enumerate - -@node Goals -@section The Aims of this Package - -@enumerate - -@item -Emulate EDT Keypad Mode commands closely so that current EDT users will -find that it easy and comfortable to use Emacs with a small learning -curve. - -@item -Make it easy for a user to customize EDT emulation key bindings without -knowing much about Emacs Lisp. - -@item -Make it easy to switch between the original EDT default bindings and the -user's customized EDT bindings, without having to exit Emacs. - -@item -Provide support for some TPU/EVE functions not supported in EDT. - -@item -Provide an easy way to restore @strong{all} original Emacs key bindings, -just as they existed before the EDT emulation was first invoked. - -@item -Support Emacs and XEmacs 19 and higher. - -@item -Supports highlighting of marked text within the EDT emulation on all -platforms on which Emacs supports highlighting of marked text. - -@item -Handle terminal configuration interactively for most terminal -configurations, when the emulation is invoked for the first time. - -@item -Support a PC AT keyboard under MS-DOS. - -@end enumerate - -@node Supported terminals -@chapter Terminals/Keyboards that are Supported - -Keyboards used under a Window System are supported via the -@code{edt-mapper} function. The first time you invoke the emulation -under a window system, the @code{edt-mapper} function is run -automatically and the user is prompted to identify which keys the -emulation is to use for the standard keypad and function keys EDT -expects (e.g., @key{PF1}, @key{PF2}, @key{KP0}, @key{KP1}, @key{F1}, -@key{F2}, etc.). This configuration is saved to disk read each time the -emulation is invoked. - -In character oriented connections not running a window manager, built-in -support for the following terminals/keyboards is provided: - -@enumerate - -@item -DEC VT-100 series and higher. This includes well behaved VT clones and -emulators. If you are using a VT series terminal, be sure that the -@env{TERM} environment variable is set properly before invoking emacs. - -@item -PC AT keyboard under MS-DOS. - -@end enumerate - -Be sure to read @ref{Platform-specific notes} to see if those notes -apply to you. - -@node Starting emulation -@chapter How to Get Started - -Start up Emacs and enter @kbd{M-x edt-emulation-on} to begin the -emulation. After initialization is complete, the following message will -appear below the status line informing you that the emulation has been -enabled: ``Default EDT keymap active''. - -You can have the EDT Emulation start up automatically, each time you -initiate an Emacs session, by adding the following line to your -@file{.emacs} file: - -@example -(add-hook term-setup-hook 'edt-emulation-on) -@end example - -A reference sheet is included (later on) listing the default EDT -Emulation key bindings. This sheet is also accessible on line from -within Emacs by pressing @key{PF2}, @kbd{GOLD-H}, or @samp{HELP} (when -in the EDT Default Mode). - -It is easy to customize key bindings in the EDT Emulation -(@pxref{Customizing}). Customizations are placed in a file called -@file{edt-user.el}. The Emacs @file{etc/} directory contains an -example. If @file{edt-user.el} is found in your Emacs load path -during EDT Emulation initialization, then the following message will -appear below the status line indicating that the emulation has been -enabled, enhanced by your own customizations: ``User EDT custom keymap -active''. - -Once enabled, it is easy to switch back and forth between your -customized EDT Emulation key bindings and the default EDT Emulation key -bindings. (Look at the binding to @kbd{GOLD-Z} in the sample -@file{edt-user.el} file.) It is also easy to turn off the emulation -(via the command @code{edt-emulation-off}). Doing so completely -restores the original key bindings in effect just prior to invoking the -emulation. - -Emacs binds keys to @acronym{ASCII} control characters and so does the -real EDT. Where EDT key bindings and Emacs key bindings conflict, -the default Emacs key bindings are retained by the EDT emulation by -default. If you are a diehard EDT user you may not like this. The -@ref{Control keys} section explains how to change this so that the EDT -bindings to @acronym{ASCII} control characters override the default -Emacs bindings. - -@node Platform-specific notes -@chapter Notes Specific to Certain Platforms - -@menu -* Sun workstations:: Sun workstations running X. -* MS-DOS:: PC users running MS-DOS. -* GNU/Linux:: PC users running GNU/Linux. -* Unix:: Using @key{NumLock} for the @key{PF1} key on Unix systems. -@end menu - -@node Sun workstations -@section Sun Workstations Running X - -Some earlier Sun keyboards do not have arrow keys separate from the -keypad keys. It is difficult to emulate the full EDT keypad and still -retain use of the arrow keys on such keyboards. - -The Sun Type 5 and other more recent Sun keyboards, however, do have -separate arrow keys. This makes them candidates for setting up a -reasonable EDT keypad emulation. - -Depending upon the configuration of the version of X installed on your -system, you may find the default X keynames for the keypad keys don't -permit Emacs to interpret some or all the keypad keys as something other -than arrow keys, numeric keys, @key{Home}, @key{PageUp}, etc. Both Sun -and HP have been particularly guilty of making bizarre keysym -assignments to the keypad keys. - -In most cases, the X Windows command, @code{xmodmap}, can be used to -correct the problem. Here's a sample @file{.xmodmaprc} file which -corrects this problem on one Sun workstation configuration using an -older SunOS release configured with a Sun Type 5 keyboard: - -@example -! File: .xmodmaprc -! -! Set up Sun Type 5 keypad for use with the Emacs EDT Emulation -! -keycode 53 = KP_Divide -keycode 54 = KP_Multiply -keycode 57 = KP_Decimal -keycode 75 = KP_7 -keycode 76 = KP_8 -keycode 77 = KP_9 -keycode 78 = KP_Subtract -keycode 97 = KP_Enter -keycode 98 = KP_4 -keycode 99 = KP_5 -keycode 100 = KP_6 -keycode 101 = KP_0 -keycode 105 = F24 -keycode 119 = KP_1 -keycode 120 = KP_2 -keycode 121 = KP_3 -keycode 132 = KP_Add -@end example - -If @file{edt-mapper.el} does not recognize your keypad keys as unique -keys, use the command @samp{xmodmap -pke} to get a listing of the actual -key codes and the keysyms mapped to them and then generate you own -custom @file{.xmodmaprc} similar to the one above. - -Next, feed @file{.xmodmaprc} to the @code{xmodmap} command and all the -Sun Type 5 keypad keys will now be configurable for the emulation of an -LK-201 keypad (less the @key{,} key). In this example, the line - -@example -keycode 105 = F24 -@end example - -@noindent changes the X Windows name of the keypad @key{NumLock} key to -be known internally as the @key{F24} key. Doing so permits it to be -configured to behave as the @key{PF1} (@key{GOLD}) key. - -The side effect of this change is that you will no longer have a -@key{NumLock} key. If you are using other software under X which -requires a @key{NumLock} key, then examine your keyboard and look for -one you don't use and redefine it to be the @key{NumLock} key. -Basically, you need to clear the @key{NumLock} key from being assigned -as a modifier, assign it to the key of your choice, and then add it back -as a modifier. (@ref{Unix} for further help on how to do this.) - -@node MS-DOS -@section PC Users Running MS-DOS - -By default, F1 is configured to emulate the @key{PF1} (@key{GOLD}) key. -But @key{NumLock} can be used instead if you load a freeware TSR -distributed with MS-Kermit, call @samp{gold.com}. This was once -distributed in a file called @file{gold22.zip} and came with the source -code as well as a loadable binary image. (See @file{edt-pc.el} in the -Emacs @file{lisp/emulation} directory for more information.) - -@node GNU/Linux -@section PC Users Running GNU/Linux - -The default X server configuration varies from distribution to -distribution and release to release of GNU/Linux. If your system fails -to recognize the keypad keys as distinct keys, change the NumLock state, -turning it on or off, as the case may be, then try again. If this -doesn't solve your problem, you may have to modify the X keysym mappings -with @code{xmodmap}. - -On one distribution on an Intel PC, the following @file{.xmodmaprc} set -things up nicely. - -@example -! File: .xmodmaprc -! -! Set up PC keypad under GNU/Linux for the Emacs EDT Emulation -! -clear mod2 -keycode 77 = F12 -keycode 96 = Num_Lock Pointer_EnableKeys -add mod2 = Num_Lock -@end example - -In this example, after feeding the file to the @code{xmodmap} command, -the PC @key{NumLock} keypad key will be configurable for the emulation -of the @key{PF1} key. The PC keypad can now emulate an LK-201 keypad -(less the comma key), the standard keyboard supplied with DEC terminals -VT-200 and above. This @file{.xmodmaprc} file switches the role of the -@key{F12} and @key{NumLock} keys. It has been tested on RedHat -GNU/Linux 5.2. Other versions of GNU/Linux may require different -keycodes. (@ref{Unix} for further help on how to do this.) - -@strong{Please note:} Remember, it may be necessary to have @key{NumLock} in -one position (ON) or the other (OFF) for the PC keypad to emulate the -LK-201 keypad properly. - -@node Unix -@section General Notes on Using @key{NumLock} for the @key{PF1} Key on Unix Systems - -Making the physical @key{NumLock} key available for use in the EDT Emulation -requires some modification to the default X Window settings. Since the -keycode assignments vary from system to system, some investigation is -needed to see how to do this on a particular system. - -You will need to look at the output generated by @code{xmodmap} invoked -with the "-pm" switch. For example, on RedHat GNU/Linux 5.2 on a PC, we -get the following output when running @samp{xmodmap -pm}: - -@example -xmodmap: up to 2 keys per modifier, (keycodes in parentheses): - -shift Shift_L (0x32), Shift_R (0x3e) -lock Caps_Lock (0x42) -control Control_L (0x25), Control_R (0x6d) -mod1 Alt_L (0x40), Alt_R (0x71) -mod2 Num_Lock (0x4d) -mod3 -mod4 -mod5 Scroll_Lock (0x4e) -@end example - -@noindent Note that Num_Lock is assigned to the modifier @samp{mod2}. This is -what hides Num_Lock from being seen by Emacs. - -Now, @samp{xmodmap -pke} yields: - -@example - . - . - . -keycode 77 = Num_Lock Pointer_EnableKeys - . - . - . -keycode 96 = F12 - . - . - . -@end example - -@noindent So, in RedHat GNU/Linux 5.2 on a PC, Num_Lock generates keycode 77. -The following steps are taken: - -@enumerate -@item -clear the assignment of Num_Lock to mod2; -@item -swap the keycodes assigned to F12 and Num_Lock; -@item -assign Num_Lock back to mod2. -@end enumerate - -@noindent The @file{.xmodmaprc} file looks like this: - -@example -! File: .xmodmaprc -! -! Set up PC keypad under GNU/Linux for the Emacs EDT Emulation -! -clear mod2 -keycode 77 = F12 -keycode 96 = Num_Lock Pointer_EnableKeys -add mod2 = Num_Lock -@end example - -So, after executing @samp{xmodmap .xmodmaprc}, a press of the physical -@key{F12} key looks like a Num_Lock keypress to X. Also, a press of the -physical @key{NumLock} key looks like a press of the @key{F12} key to X. - -Now, @file{edt-mapper.el} will see @samp{f12} when the physical -@key{NumLock} key is pressed, allowing the @key{NumLock} key to be used -as the EDT @key{PF1} (@key{GOLD}) key. - -@node Differences -@chapter How Does this EDT Emulation Differ from Real EDT? - -In general, you will find that this emulation of EDT replicates most, -but not all, of EDT's most used Keypad Mode editing functions and -behavior. It is not perfect, but most EDT users who have tried the -emulation agree that it is quite good enough to make it easy for -die-hard EDT users to move over to using Emacs. - -Here's a list of the most important differences between EDT and this GNU -Emacs EDT Emulation. The list is short but you must be aware of these -differences if you are to use the EDT Emulation effectively. - -@enumerate - -@item -Entering repeat counts works a little differently than in EDT. - -EDT allows users to enter a repeat count before entering a command that -accepts repeat counts. For example, when using the real EDT, pressing -these three keys in sequence, @kbd{GOLD 5 KP1}, will move the cursor in -the current direction 5 words. This does @strong{not} work in Emacs! - -Emacs provides two ways to enter repeat counts and neither involves -using the @key{GOLD} key. First, repeat counts can be entered in Emacs -by using the @key{ESC} key. For example, pressing these keys in -sequence, @kbd{ESC 1 0 KP1}, will move the cursor in the current -direction 10 words. Second, Emacs provides another command called -@code{universal-argument} that can be used to do the same thing. -Normally, in Emacs has this bound to @kbd{C-u}. - -@item -EDT's line mode commands and nokeypad mode commands are @strong{not} -supported (with one important exception; see item 8 in -@ref{Highlights}). Although, at first, this may seem like a big -omission, the set of built-in Emacs commands provides a much richer set -of capabilities which more than make up for this omission. - -To enter Emacs commands not bound to keys, you can press @kbd{GOLD KP7} -or the @key{DO} key. Emacs will display its own command prompt "M-x". -This stands for the keypress @kbd{Meta-x}, where @key{Meta} is a special -shift key. The @key{Alt} key is often mapped to behave as a @key{Meta} -key. So, you can also invoke this prompt by pressing @kbd{Meta-x}. -Typing the sequence @kbd{ESC x} will also invoke the prompt. - -@item -Selected text is highlighted @strong{only} on systems where Emacs -supports the highlighting of text. - -@item -Just like in TPU/EVE, the @key{ENTER} key is @strong{not} used to -terminate input when the editor prompts you for input. The @key{RETURN} -key is used, instead. (@key{KP4} and @key{KP5} (the direction keys) do -terminate input for the @samp{FIND} command, just like in EDT, however.) - -@end enumerate - -@node Highlights -@chapter Some Highlights, and Comparisons to the Original Emacs EDT Emulation - -@enumerate - -@item -The EDT define key command is supported (@code{edt-define-key}) and is -bound to @kbd{C-k} in the default EDT mode when EDT control sequence -bindings are enabled, or when the sample @file{edt-user.el} -customization file is used. The TPU/EVE learn command is supported but -not bound to a key in the default EDT mode but is bound in the sample -@file{edt-user.el} file. - -Unlike the TPU/EVE learn command, which uses one key to begin the learn -sequence, @kbd{C-l}, and another command to remember the sequence, -@kbd{C-r}, this version of the learn command (@code{edt-learn}) serves -as a toggle to both begin and to remember the learn sequence. - -Many users who change the meaning of a key with the define key and the -learn commands, would like to be able to restore the original key -binding without having to quit and restart emacs. So a restore key -command is provided to do just that. When invoked, it prompts you to -press the key to which you wish the last replaced key definition -restored. It is bound to @kbd{GOLD C-k} in the default EDT mode when -EDT control sequence bindings are enabled or the sample -@file{edt-user.el} customization file is used. - -@item -Direction support is fully supported. - -@item -All original Emacs bindings are fully restored when EDT emulation is -turned off. So, if a fellow worker comes over to your terminal to help -you with a software problem, for example, and is completely confused by -your EDT emulation bindings, just enter the command, -@code{edt-emulation-off}, at the @samp{M-x} prompt and the original -Emacs bindings will be restored. To resume the EDT emulation, just -enter @code{edt-emulation-on}. - -@item -User custom EDT bindings are kept separate from the default EDT -bindings. One can toggle back and forth between the custom EDT bindings -and default EDT bindings. - -@item -The Emacs functions in @file{edt.el} attempt to emulate, where -practical, the exact behavior of the corresponding EDT keypad mode -commands. In a few cases, the emulation is not exact, but we hope you -will agree it is close enough. In a very few cases, we chose to use the -Emacs way of handling things. As mentioned earlier, we do not emulate -the EDT @samp{SUBS} command. Instead, we chose to use the Emacs -@code{query-replace} function, which we find to be easier to use. - -@item -Emacs uses the regexp assigned to @code{page-delimiter} to determine -what marks a page break. This is normally @samp{^\f}, which causes the -@code{edt-page} command to ignore form feeds not located at the -beginning of a line. To emulate the EDT @samp{PAGE} command exactly, -page-delimiter is set to @samp{\f} when EDT emulation is turned on, and -restored to @samp{^\f} when EDT emulation is turned off. But, since -some users prefer the Emacs definition of a page break, or may wish to -preserve a customized definition of page break, one can override the EDT -definition by placing - -@example -(setq edt-keep-current-page-delimiter t) -@end example - -@noindent in your @file{.emacs} file. Or, you can used the Emacs customize -command to change its setting. - -@item -The EDT definition of a section of a terminal window is hardwired to be -16 lines of its one-and-only 24-line window (the EDT @samp{SECT} command -bound to @key{KP8}). That's two-thirds of the window at a time. Since -Emacs, like TPU/EVE, can handle multiple windows of sizes of other than -24 lines, the definition of section used here has been modified to -two-thirds of the current window. (There is also an -@code{edt-scroll-window} function which you may prefer over the -@samp{SECT} emulation.) - -@item -Cursor movement and deletion involving word entities is identical to -EDT. This, above all else, gives the die-hard EDT user a sense of being -at home. Also, an emulation of EDT's @samp{SET ENTITY WORD} command is -provided, for those users who like to customize movement by a word at a -time to their own liking. - -@item -EDT's @samp{FIND} and @samp{FNDNXT} are supported. - -@item -EDT's @samp{APPEND}, @samp{REPLACE}, and @samp{SUBS} commands are supported. - -@item -@samp{CHNGCASE} is supported. It works on individual characters or -selected text, if @samp{SELECT} is active. In addition, two new -commands are provided: @code{edt-lowercase} and @code{edt-uppercase}. -They work on individual @strong{words} or selected text, if -@samp{SELECT} is active. - -@item -Form feed and tab insert commands are supported. - -@item -A new command, @code{edt-duplicate-word}, is provided. If you -experiment with it, you might find it to be surprisingly useful and may -wonder how you ever got along without it! It is assigned to @kbd{C-j} -in the sample @file{edt-user.el} customization file. - -@item -TPU/EVE's Rectangular Cut and Paste functions (originally from the -EVE-Plus package) are supported. But unlike the TPU/EVE versions, these -here support both insert and overwrite modes. The seven rectangular -functions are bound to @key{F7}, @key{F8}, @kbd{GOLD-F8}, @key{F9}, -@kbd{GOLD-F9}, @key{F10}, and @kbd{GOLD-F10} in the default EDT mode. - -@item -The original EDT emulation package set up many default regular and GOLD -bindings. We tried to preserve most (but not all!) of these, so users -of the original emulation package will feel more at home. - -Nevertheless, there are still many GOLD key sequences which are not -bound to any functions. These are prime candidates to use for your own -customizations. - -Also, there are several commands in @file{edt.el} not bound to any key. -So, you will find it worthwhile to look through @file{edt.el} for -functions you may wish to add to your personal customized bindings. - -@item -The VT200/VT300 series terminals steal the function keys @key{F1} to -@key{F5} for their own use. These do not generate signals which are -sent to the host. So, @file{edt.el} does not assign any default -bindings to @key{F1} through @key{F5}. - -In addition, our VT220 terminals generate an interrupt when the @key{F6} -key is pressed (@samp{^C} or @samp{^Y}, can't remember which) and not -the character sequence documented in the manual. So, binding Emacs -commands to @key{F6} will not work if your terminal behaves the same -way. - -@item -The VT220 terminal has no @key{ESC}, @key{BS}, nor @key{LF} keys, as -does a VT100. So the default EDT bindings adopt the standard DEC -convention of having the @key{F11}, @key{F12}, and @key{F13} keys, on a -VT200 series (and above) terminal, assigned to the same EDT functions -that are bound to @key{ESC}, @key{BS}, and @key{LF} on a VT100 terminal. - -@item -Each user, through the use of a private @file{edt-user.el} file, can -customize, very easily, personal EDT emulation bindings. - -@item -The EDT @samp{SELECT} and @samp{RESET} functions are supported. -However, unlike EDT, pressing @samp{RESET} to cancel text selection does -@strong{not} reset the existing setting of the current direction. - -We also provide a TPU/EVE like version of the single @samp{SELECT/RESET} -function, called @code{edt-toggle-select}, which makes the EDT -@samp{SELECT} function into a toggle on/off switch. That is, if -selection is on, pressing @samp{SELECT} again turns selection off -(cancels selection). This function is used in the sample -@file{edt-user.el} customization file. - -@item -EDT scroll margins are supported, but are disabled by default. -(@ref{Scroll margins} for instructions on how to enable them.) - -@end enumerate - -@node Customizing -@chapter Customizing Emulation - -Most EDT users, at one time or another, make some custom key bindings, -or use someone else's custom key bindings, which they come to depend -upon just as if they were built-in bindings. This EDT Emulation for GNU -Emacs is designed to make it easy to customize bindings. - -If you wish to customize the EDT Emulation to use some of your own key -bindings, you need to make a private version of @file{edt-user.el} in -your own private lisp directory. The Emacs @file{etc/} directory -contains an example for you to use as a template and for ideas. -@c This seems to be untrue. -@ignore -There are two sample files @file{edt-user.el1} and @file{edt-user.el2} -for you to use as templates and for ideas. Look at @file{edt-user.el1} -first. Unless you will be using two or more very different types of -terminals on the same system, you need not look at @file{edt-user.el2}. -@end ignore - -First, you need to have your own private lisp directory, say -@file{~/lisp}, and you should add it to the Emacs load path. - -@strong{Please note:} A few sites have different load-path requirements, -so the above directions may need some modification if your site has such -special needs. - -@menu -* edt-user.el:: Creating your own @file{edt-user.el} file. -* Words:: Specifying word entities. -* Control keys:: Enabling EDT control key sequence bindings. -* Scroll margins:: Setting scroll margins. -@end menu - -@node edt-user.el -@section Creating your own @file{edt-user.el} File - -A sample @file{edt-user.el} file is provided in the Emacs @file{etc/} -directory. You should use it as a guide to learn how you can customize -EDT emulation bindings to your own liking. Names used to identify the -set of LK-201 keypad and function keys are: - -@example -Keypad Keys: - PF1 PF2 PF3 PF4 - KP7 KP8 KP9 KP- - KP4 KP5 KP6 KP, - KP1 KP2 KP3 - KP0 KPP KPE -@end example - -@example -Arrow Keys: - LEFT RIGHT DOWN UP -@end example - -@example -Function Keys: - F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 - HELP DO F17 F18 F19 F20 - - FIND INSERT REMOVE - SELECT PREVIOUS NEXT -@end example - -Note: Many VT-200 terminals, and above, steal function keys @key{F1} -through @key{F5} for terminal setup control and don't send anything to -the host if pressed. So customizing bindings to these keys may not work -for you. - -There are three basic functions that do the EDT emulation custom -bindings: @code{edt-bind-key}, @code{edt-bind-gold-key}, and -@code{edt-bind-function-key}. - -The first two are for binding functions to keys which are standard -across most keyboards. This makes them keyboard independent, making it -possible to define these key bindings for all terminals in the file -@file{edt.el}. - -The first, @code{edt-bind-key}, is used typically to bind emacs commands -to control keys, although some people use it to bind commands to other -keys, as well. (For example, some people use it to bind the VT200 -seldom used back-tick key (@samp{`}) to the function @samp{ESC-prefix} -so it will behave like an @key{ESC} key.) The second function, -@code{edt-bind-gold-key}, is used to bind emacs commands to gold key -sequences involving alpha-numeric keys, special character keys, and -control keys. - -The third function, @code{edt-bind-function-key}, is terminal dependent -and is defined in a terminal specific file (see @file{edt-vt100.el} for -example). It is used to bind emacs commands to LK-201 function keys, to -keypad keys, and to gold sequences of those keys. - -@node Words -@section Specifying Word Entities - -The variable @code{edt-word-entities} is used to emulate EDT's @samp{SET -ENTITY WORD} command. It contains a list of characters to be treated as -words in themselves. If the user does not define -@code{edt-word-entities} in his/her @file{.emacs} file, then it is set -up with the EDT default containing only @key{TAB}. - -The characters are stored in the list by their numerical values, not as -strings. Emacs supports several ways to specify the numerical value of -a character. One method is to use the question mark: @samp{?A} means -the numerical value for @samp{A}, @samp{?/} means the numerical value -for @samp{/}, and so on. Several unprintable characters have special -representations: - -@example -?\b specifies BS, C-h -?\t specifies TAB, C-i -?\n specifies LFD, C-j -?\v specifies VTAB, C-k -?\f specifies FF, C-l -?\r specifies CR, C-m -?\e specifies ESC, C-[ -?\\ specifies \ -@end example - -Here are some examples: - -@example -(setq edt-word-entities '(?\t ?- ?/)) ; specifies TAB, - , and / -(setq edt-word-entities '(?\t) ; specifies TAB, the default -@end example - -@noindent You can also specify characters by their decimal ascii values: - -@example -(setq edt-word-entities '(9 45 47)) ; specifies TAB, - , and / -@end example - -@node Control keys -@section Enabling EDT Control Key Sequence Bindings - -Where EDT key bindings and Emacs key bindings conflict, the default -Emacs key bindings are retained by default. Some diehard EDT users -may not like this. So, if the variable -@code{edt-use-EDT-control-key-bindings} is set to true in a user's -@file{.emacs} file, then the default EDT Emulation mode will enable most -of the original EDT control key sequence bindings. If you wish to do -this, add the following line to your @file{.emacs} file: - -@example -(setq edt-use-EDT-control-key-bindings t) -@end example - -@node Scroll margins -@section Setting Scroll Margins - -Scroll margins at the top and bottom of the window are now supported. -(The design was copied from @file{tpu-extras.el}.) By default, this -feature is enabled with the top margin set to 10% of the window and the -bottom margin set to 15% of the window. To change these settings, you -can invoke the function @code{edt-set-scroll-margins} in your -@file{.emacs} file. For example, the following line - -@example -(edt-set-scroll-margins "20%" "25%") -@end example - -@noindent sets the top margin to 20% of the window and the bottom margin -to 25% of the window. To disable this feature, set each margin to 0%. -You can also invoke @code{edt-set-scroll-margins} interactively while -EDT Emulation is active to change the settings for that session. - -@strong{Please note:} Another way to set the scroll margins is to use -the Emacs customization feature to set the following two variables -directly: @code{edt-top-scroll-margin} and @code{edt-bottom-scroll-margin}. - -Enter the Emacs @code{customize} command. First select the -@samp{Editing} group and then select the @samp{Emulations} group. -Finally, select the @samp{Edt} group and follow the directions. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@bye diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi deleted file mode 100644 index c006e635a78..00000000000 --- a/doc/misc/eieio.texi +++ /dev/null @@ -1,1908 +0,0 @@ -\input texinfo -@setfilename ../../info/eieio -@set TITLE Enhanced Implementation of Emacs Interpreted Objects -@set AUTHOR Eric M. Ludlam -@settitle @value{TITLE} - -@c ************************************************************************* -@c @ Header -@c ************************************************************************* - -@copying -This manual documents EIEIO, an object framework for Emacs Lisp. - -Copyright @copyright{} 2007-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* EIEIO: (eieio). An objects system for Emacs Lisp. -@end direntry - -@titlepage -@center @titlefont{@value{TITLE}} -@sp 4 -@center by @value{AUTHOR} -@end titlepage -@page - -@macro eieio{} -@i{EIEIO} -@end macro - -@node Top, Quick Start, (dir), (dir) -@comment node-name, next, previous, up -@top EIEIO - -@eieio{} (``Enhanced Implementation of Emacs Interpreted Objects'') is -a CLOS (Common Lisp Object System) compatibility layer for Emacs Lisp. -It provides a framework for writing object-oriented applications in -Emacs. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Quick Start:: Quick start for EIEIO. -* Introduction:: Why use @eieio{}? Basic overview, samples list. -* Building Classes:: How to write new class structures. -* Making New Objects:: How to construct new objects. -* Accessing Slots:: How to access a slot. -* Writing Methods:: How to write a method. -@c * Method Invocation:: How methods are invoked. -* Predicates:: Class-p, Object-p, etc-p. -* Association Lists:: List of objects as association lists. -* Customizing:: Customizing objects. -* Introspection:: Looking inside a class. -* Base Classes:: Additional classes you can inherit from. -* Browsing:: Browsing your class lists. -* Class Values:: Displaying information about a class or object. -* Default Superclass:: The root superclasses. -* Signals:: When you make errors -* Naming Conventions:: Name your objects in an Emacs friendly way. -* CLOS compatibility:: What are the differences? -* Wish List:: Things about EIEIO that could be improved. -* Function Index:: -@end menu - -@node Quick Start -@chapter Quick Start - -@eieio{} provides an Object Oriented layer for Emacs Lisp. You can -use @eieio{} to create classes, methods for those classes, and -instances of classes. - -Here is a simple example of a class named @code{record}, containing -three slots named @code{name}, @code{birthday}, and @code{phone}: - -@example -(defclass record () ; No superclasses - ((name :initarg :name - :initform "" - :type string - :custom string - :documentation "The name of a person.") - (birthday :initarg :birthday - :initform "Jan 1, 1970" - :custom string - :type string - :documentation "The person's birthday.") - (phone :initarg :phone - :initform "" - :documentation "Phone number.")) - "A single record for tracking people I know.") -@end example - -Each class can have methods, which are defined like this: - -@example -(defmethod call-record ((rec record) &optional scriptname) - "Dial the phone for the record REC. -Execute the program SCRIPTNAME to dial the phone." - (message "Dialing the phone for %s" (oref rec name)) - (shell-command (concat (or scriptname "dialphone.sh") - " " - (oref rec phone)))) -@end example - -@noindent -In this example, the first argument to @code{call-record} is a list, -of the form (@var{varname} @var{classname}). @var{varname} is the -name of the variable used for the first argument; @var{classname} is -the name of the class that is expected as the first argument for this -method. - -@eieio{} dispatches methods based on the type of the first argument. -You can have multiple methods with the same name for different classes -of object. When the @code{call-record} method is called, the first -argument is examined to determine the class of that argument, and the -method matching the input type is then executed. - -Once the behavior of a class is defined, you can create a new -object of type @code{record}. Objects are created by calling the -constructor. The constructor is a function with the same name as your -class which returns a new instance of that class. Here is an example: - -@example -(setq rec (record "Eric" :name "Eric" :birthday "June" :phone "555-5555")) -@end example - -@noindent -The first argument is the name given to this instance. Each instance -is given a name, so different instances can be easily distinguished -when debugging. - -It can be a bit repetitive to also have a :name slot. To avoid doing -this, it is sometimes handy to use the base class @code{eieio-named}. -@xref{eieio-named}. - -Calling methods on an object is a lot like calling any function. The -first argument should be an object of a class which has had this -method defined for it. In this example it would look like this: - -@example -(call-record rec) -@end example - -@noindent -or - -@example -(call-record rec "my-call-script") -@end example - -In these examples, @eieio{} automatically examines the class of -@code{rec}, and ensures that the method defined above is called. If -@code{rec} is some other class lacking a @code{call-record} method, or -some other data type, Emacs signals a @code{no-method-definition} -error. @ref{Signals}. - -@node Introduction -@comment node-name, next, previous, up -@chapter Introduction - -Due to restrictions in the Emacs Lisp language, CLOS cannot be -completely supported, and a few functions have been added in place of -setf. - -@eieio{} supports the following features: - -@enumerate -@item -A structured framework for the creation of basic classes with attributes -and methods using singular inheritance similar to CLOS. -@item -Type checking, and slot unbinding. -@item -Method definitions similar to CLOS. -@item -Simple and complex class browsers. -@item -Edebug support for methods. -@item -Imenu updates. -@item -Byte compilation support of methods. -@item -Help system extensions for classes and methods. -@item -Automatic texinfo documentation generator. -@item -Several base classes for interesting tasks. -@item -Simple test suite. -@item -Public and private classifications for slots (extensions to CLOS) -@item -Customization support in a class (extension to CLOS) -@end enumerate - -Here are some CLOS features that @eieio{} presently lacks: - -@table @asis -@item Complete @code{defclass} tag support -All CLOS tags are currently supported, but the following are not -currently implemented correctly: - -@table @code -@item :metaclass -There is only one base superclass for all @eieio{} classes, which is -the @code{eieio-default-superclass}. -@item :default-initargs -Each slot has an @code{:initarg} tag, so this is not really necessary. -@end table - -@item Mock object initializers -Each class contains a mock object used for fast initialization of -instantiated objects. Using functions with side effects on object slot -values can potentially cause modifications in the mock object. @eieio{} -should use a deep copy but currently does not. - -@item @code{:around} method tag -This CLOS method tag is non-functional. - -@end table - -@node Building Classes -@comment node-name, next, previous, up -@chapter Building Classes - -A @dfn{class} is a definition for organizing data and methods -together. An @eieio{} class has structures similar to the classes -found in other object-oriented (OO) languages. - -To create a new class, use the @code{defclass} macro: - -@defmac defclass class-name superclass-list slot-list &rest options-and-doc - -Create a new class named @var{class-name}. The class is represented -by a self-referential symbol with the name @var{class-name}. @eieio{} -stores the structure of the class as a symbol property of -@var{class-name} (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp -Reference Manual}). - -The @var{class-name} symbol's variable documentation string is a -modified version of the doc string found in @var{options-and-doc}. -Each time a method is defined, the symbol's documentation string is -updated to include the methods documentation as well. - -The parent classes for @var{class-name} is @var{superclass-list}. -Each element of @var{superclass-list} must be a class. These classes -are the parents of the class being created. Every slot that appears -in each parent class is replicated in the new class. - -If two parents share the same slot name, the parent which appears in -the @var{superclass-list} first sets the tags for that slot. If the -new class has a slot with the same name as the parent, the new slot -overrides the parent's slot. -@end defmac - -@noindent -Whenever defclass is used to create a new class, two predicates are -created for it, named @code{@var{CLASS-NAME}-p} and -@code{@var{CLASS-NAME}-child-p}: - -@defun CLASS-NAME-p object -Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}. -@end defun - -@defun CLASS-NAME-child-p object -Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}, -or is of a subclass of @var{CLASS-NAME}. -@end defun - -@defvar eieio-error-unsupported-class-tags -If non-nil, @code{defclass} signals an error if a tag in a slot -specifier is unsupported. - -This option is here to support programs written with older versions of -@eieio{}, which did not produce such errors. -@end defvar - -@menu -* Inheritance:: How to specify parents classes -* Slot Options:: How to specify features of a slot. -* Class Options:: How to specify features for this class. -@end menu - -@node Inheritance -@section Inheritance - -@dfn{Inheritance} is a basic feature of an object-oriented language. -In @eieio{}, a defined class specifies the super classes from which it -inherits by using the second argument to @code{defclass}. Here is an -example: - -@example -(defclass my-baseclass () - ((slot-A :initarg :slot-A) - (slot-B :initarg :slot-B)) - "My Baseclass.") -@end example - -@noindent -To subclass from @code{my-baseclass}, we specify it in the superclass -list: - -@example -(defclass my-subclass (my-baseclass) - ((specific-slot-A :initarg specific-slot-A) - ) - "My subclass of my-baseclass") -@end example - -@indent -Instances of @code{my-subclass} will inherit @code{slot-A} and -@code{slot-B}, in addition to having @code{specific-slot-A} from the -declaration of @code{my-subclass}. - -@eieio{} also supports multiple inheritance. Suppose we define a -second baseclass, perhaps an ``interface'' class, like this: - -@example -(defclass my-interface () - ((interface-slot :initarg :interface-slot)) - "An interface to special behavior." - :abstract t) -@end example - -@noindent -The interface class defines a special @code{interface-slot}, and also -specifies itself as abstract. Abstract classes cannot be -instantiated. It is not required to make interfaces abstract, but it -is a good programming practice. - -We can now modify our definition of @code{my-subclass} to use this -interface class, together with our original base class: - -@example -(defclass my-subclass (my-baseclass my-interface) - ((specific-slot-A :initarg specific-slot-A) - ) - "My subclass of my-baseclass") -@end example - -@noindent -With this, @code{my-subclass} also has @code{interface-slot}. - -If @code{my-baseclass} and @code{my-interface} had slots with the same -name, then the superclass showing up in the list first defines the -slot attributes. - -Inheritance in @eieio{} is more than just combining different slots. -It is also important in method invocation. @ref{Methods}. - -If a method is called on an instance of @code{my-subclass}, and that -method only has an implementation on @code{my-baseclass}, or perhaps -@code{my-interface}, then the implementation for the baseclass is -called. - -If there is a method implementation for @code{my-subclass}, and -another in @code{my-baseclass}, the implementation for -@code{my-subclass} can call up to the superclass as well. - -@node Slot Options -@section Slot Options - -The @var{slot-list} argument to @code{defclass} is a list of elements -where each element defines one slot. Each slot is a list of the form - -@example - (SLOT-NAME :TAG1 ATTRIB-VALUE1 - :TAG2 ATTRIB-VALUE2 - :TAGN ATTRIB-VALUEN) -@end example - -@noindent -where @var{SLOT-NAME} is a symbol that will be used to refer to the -slot. @var{:TAG} is a symbol that describes a feature to be set -on the slot. @var{ATTRIB-VALUE} is a lisp expression that will be -used for @var{:TAG}. - -Valid tags are: - -@table @code -@item :initarg -A symbol that can be used in the argument list of the constructor to -specify a value for the new instance being created. - -A good symbol to use for initarg is one that starts with a colon @code{:}. - -The slot specified like this: -@example - (myslot :initarg :myslot) -@end example -could then be initialized to the number 1 like this: -@example - (myobject "name" :myslot 1) -@end example - -@xref{Making New Objects}. - -@item :initform -A expression used as the default value for this slot. - -If @code{:initform} is left out, that slot defaults to being unbound. -It is an error to reference an unbound slot, so if you need -slots to always be in a bound state, you should always use an -@code{:initform} specifier. - -Use @code{slot-boundp} to test if a slot is unbound -(@pxref{Predicates}). Use @code{slot-makeunbound} to set a slot to -being unbound after giving it a value (@pxref{Accessing Slots}). - -The value passed to initform is automatically quoted. Thus, -@example -:initform (1 2 3) -@end example -appears as the specified list in the default object. -A symbol that is a function like this: -@example -:initform + -@end example -will set the initial value as that symbol. -A function that is a lambda expression, like this: -@example -:initform (lambda () some-variablename) -@end example - -will be evaluated at instantiation time to the value of -@code{some-variablename}. -@c This feature was more annoying than useful. Use the -@c `initialize-instance' function to do this. -@c -@c On the other hand, if you need code to be -@c executed at instantiation time as the initform, code like this: -@c @example -@c :initform (lambda () (+ 1 some-global-var)) -@c @end example -@c will be identified as a function call, and be executed in place. - -@cindex lambda-default - - -Lastly, using the function @code{lambda-default} instead of -@code{lambda} will let you specify a lambda expression to use as the -value, without evaluation, thus: -@example -:initform (lambda-default () some-variablename) -@end example -@c @@TODO - This will be deleted after fair warning. -will not be evaluated at instantiation time, and the value in this -slot will instead be @code{(lambda () some-variablename)}. - -After a class has been created with @code{defclass}, you can change -that default value with @code{oset-default}. @ref{Accessing Slots}. - -@item :type -An unquoted type specifier used to validate data set into this slot. -@xref{(cl)Type Predicates}. -Here are some examples: - @table @code - @item symbol - A symbol. - @item number - A number type - @item my-class-name - An object of your class type. - @item (or null symbol) - A symbol, or nil. - @item function - A function symbol, or a @code{lambda-default} expression. - - @end table - -@item :allocation -Either :class or :instance (defaults to :instance) used to -specify how data is stored. Slots stored per instance have unique -values for each object. Slots stored per class have shared values for -each object. If one object changes a :class allocated slot, then all -objects for that class gain the new value. - -@item :documentation -Documentation detailing the use of this slot. This documentation is -exposed when the user describes a class, and during customization of an -object. - -@item :accessor -Name of a generic function which can be used to fetch the value of this slot. -You can call this function later on your object and retrieve the value -of the slot. - -This options is in the CLOS spec, but is not fully compliant in @eieio{}. - -@item :writer -Name of a generic function which will write this slot. - -This options is in the CLOS spec, but is not fully compliant in @eieio{}. - -@item :reader -Name of a generic function which will read this slot. - -This options is in the CLOS spec, but is not fully compliant in @eieio{}. - -@item :custom -A custom :type specifier used when editing an object of this type. -See documentation for @code{defcustom} for details. This specifier is -equivalent to the :type spec of a @code{defcustom} call. - -This options is specific to Emacs, and is not in the CLOS spec. - -@item :label -When customizing an object, the value of :label will be used instead -of the slot name. This enables better descriptions of the data than -would usually be afforded. - -This options is specific to Emacs, and is not in the CLOS spec. - -@item :group -Similar to @code{defcustom}'s :group command, this organizes different -slots in an object into groups. When customizing an object, only the -slots belonging to a specific group need be worked with, simplifying the -size of the display. - -This options is specific to Emacs, and is not in the CLOS spec. - -@item :printer -This routine takes a symbol which is a function name. The function -should accept one argument. The argument is the value from the slot -to be printed. The function in @code{object-write} will write the -slot value out to a printable form on @code{standard-output}. - -The output format MUST be something that could in turn be interpreted -with @code{read} such that the object can be brought back in from the -output stream. Thus, if you wanted to output a symbol, you would need -to quote the symbol. If you wanted to run a function on load, you -can output the code to do the construction of the value. - -@item :protection -When using a slot referencing function such as @code{slot-value}, and -the value behind @var{slot} is private or protected, then the current -scope of operation must be within a method of the calling object. - -Valid values are: - -@table @code -@item :public -Access this slot from any scope. -@item :protected -Access this slot only from methods of the same class or a child class. -@item :private -Access this slot only from methods of the same class. -@end table - -This options is specific to Emacs, and is not in the CLOS spec. - -@end table - -@node Class Options -@section Class Options - -In the @var{options-and-doc} arguments to @code{defclass}, the -following class options may be specified: - -@table @code -@item :documentation -A documentation string for this class. - -If an Emacs-style documentation string is also provided, then this -option is ignored. An Emacs-style documentation string is not -prefixed by the @code{:documentation} tag, and appears after the list -of slots, and before the options. - -@item :allow-nil-initform -If this option is non-nil, and the @code{:initform} is @code{nil}, but -the @code{:type} is specifies something such as @code{string} then allow -this to pass. The default is to have this option be off. This is -implemented as an alternative to unbound slots. - -This options is specific to Emacs, and is not in the CLOS spec. - -@item :abstract -A class which is @code{:abstract} cannot be instantiated, and instead -is used to define an interface which subclasses should implement. - -This option is specific to Emacs, and is not in the CLOS spec. - -@item :custom-groups -This is a list of groups that can be customized within this class. This -slot is auto-generated when a class is created and need not be -specified. It can be retrieved with the @code{class-option} command, -however, to see what groups are available. - -This option is specific to Emacs, and is not in the CLOS spec. - -@item :method-invocation-order -This controls the order in which method resolution occurs for -@code{:primary} methods in cases of multiple inheritance. The order -affects which method is called first in a tree, and if -@code{call-next-method} is used, it controls the order in which the -stack of methods are run. - -Valid values are: - -@table @code -@item :breadth-first -Search for methods in the class hierarchy in breadth first order. -This is the default. -@item :depth-first -Search for methods in the class hierarchy in a depth first order. -@end table - -@c @xref{Method Invocation}, for more on method invocation order. - -@item :metaclass -Unsupported CLOS option. Enables the use of a different base class other -than @code{standard-class}. - -@item :default-initargs -Unsupported CLOS option. Specifies a list of initargs to be used when -creating new objects. As far as I can tell, this duplicates the -function of @code{:initform}. -@end table - -@xref{CLOS compatibility}, for more details on CLOS tags versus -@eieio{}-specific tags. - -@node Making New Objects -@comment node-name, next, previous, up -@chapter Making New Objects - -Suppose we have a simple class is defined, such as: - -@example -(defclass record () - ( ) "Doc String") -@end example - -@noindent -It is now possible to create objects of that class type. - -Calling @code{defclass} has defined two new functions. One is the -constructor @var{record}, and the other is the predicate, -@var{record-p}. - -@defun record object-name &rest slots - -This creates and returns a new object. This object is not assigned to -anything, and will be garbage collected if not saved. This object -will be given the string name @var{object-name}. There can be -multiple objects of the same name, but the name slot provides a handy -way to keep track of your objects. @var{slots} is just all the slots -you wish to preset. Any slot set as such @emph{will not} get its -default value, and any side effects from a slot's @code{:initform} -that may be a function will not occur. - -An example pair would appear simply as @code{:value 1}. Of course you -can do any valid Lispy thing you want with it, such as -@code{:value (if (boundp 'special-symbol) special-symbol nil)} - -Example of creating an object from a class: - -@example -(record "test" :value 3 :reference nil) -@end example - -@end defun - -To create an object from a class symbol, use @code{make-instance}. - -@defun make-instance class &rest initargs -@anchor{make-instance} -Make a new instance of @var{class} based on @var{initargs}. -@var{class} is a class symbol. For example: - -@example - (make-instance 'foo) -@end example - - @var{initargs} is a property list with keywords based on the @code{:initarg} -for each slot. For example: - -@example - (make-instance @code{'foo} @code{:slot1} value1 @code{:slotN} valueN) -@end example - -Compatibility note: - -If the first element of @var{initargs} is a string, it is used as the -name of the class. - -In @eieio{}, the class' constructor requires a name for use when printing. -@dfn{make-instance} in CLOS doesn't use names the way Emacs does, so the -class is used as the name slot instead when @var{initargs} doesn't start with -a string. -@end defun - -@node Accessing Slots -@comment node-name, next, previous, up -@chapter Accessing Slots - -There are several ways to access slot values in an object. The naming -and argument-order conventions are similar to those used for -referencing vectors (@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference -Manual}). - -@defmac oset object slot value -This macro sets the value behind @var{slot} to @var{value} in -@var{object}. It returns @var{value}. -@end defmac - -@defmac oset-default class slot value -This macro sets the @code{:initform} for @var{slot} in @var{class} to -@var{value}. - -This allows the user to set both public and private defaults after the -class has been constructed, and provides a way to configure the -default behavior of packages built with classes (the same way -@code{setq-default} does for buffer-local variables). - -For example, if a user wanted all @code{data-objects} (@pxref{Building -Classes}) to inform a special object of his own devising when they -changed, this can be arranged by simply executing this bit of code: - -@example -(oset-default data-object reference (list my-special-object)) -@end example -@end defmac - -@defmac oref obj slot -@anchor{oref} -Retrieve the value stored in @var{obj} in the slot named by @var{slot}. -Slot is the name of the slot when created by @dfn{defclass} or the label -created by the @code{:initarg} tag. -@end defmac - -@defmac oref-default obj slot -@anchor{oref-default} -Gets the default value of @var{obj} (maybe a class) for @var{slot}. -The default value is the value installed in a class with the @code{:initform} -tag. @var{slot} can be the slot name, or the tag specified by the @code{:initarg} -tag in the @dfn{defclass} call. -@end defmac - -The following accessors are defined by CLOS to reference or modify -slot values, and use the previously mentioned set/ref routines. - -@defun slot-value object slot -@anchor{slot-value} -This function retrieves the value of @var{slot} from @var{object}. -Unlike @code{oref}, the symbol for @var{slot} must be quoted. -@end defun - -@defun set-slot-value object slot value -@anchor{set-slot-value} -This is not a CLOS function, but is meant to mirror @code{slot-value} if -you don't want to use the cl package's @code{setf} function. This -function sets the value of @var{slot} from @var{object}. Unlike -@code{oset}, the symbol for @var{slot} must be quoted. -@end defun - -@defun slot-makeunbound object slot -This function unbinds @var{slot} in @var{object}. Referencing an -unbound slot can signal an error. -@end defun - -@defun object-add-to-list object slot item &optional append -@anchor{object-add-to-list} -In OBJECT's @var{slot}, add @var{item} to the list of elements. -Optional argument @var{append} indicates we need to append to the list. -If @var{item} already exists in the list in @var{slot}, then it is not added. -Comparison is done with @dfn{equal} through the @dfn{member} function call. -If @var{slot} is unbound, bind it to the list containing @var{item}. -@end defun - -@defun object-remove-from-list object slot item -@anchor{object-remove-from-list} -In OBJECT's @var{slot}, remove occurrences of @var{item}. -Deletion is done with @dfn{delete}, which deletes by side effect -and comparisons are done with @dfn{equal}. -If @var{slot} is unbound, do nothing. -@end defun - -@defun with-slots spec-list object &rest body -@anchor{with-slots} -Bind @var{spec-list} lexically to slot values in @var{object}, and execute @var{body}. -This establishes a lexical environment for referring to the slots in -the instance named by the given slot-names as though they were -variables. Within such a context the value of the slot can be -specified by using its slot name, as if it were a lexically bound -variable. Both setf and setq can be used to set the value of the -slot. - -@var{spec-list} is of a form similar to @dfn{let}. For example: - -@example - ((VAR1 SLOT1) - SLOT2 - SLOTN - (VARN+1 SLOTN+1)) -@end example - -Where each @var{var} is the local variable given to the associated -@var{slot}. A slot specified without a variable name is given a -variable name of the same name as the slot. - -@example -(defclass myclass () (x :initarg 1)) -(setq mc (make-instance 'myclass)) -(with-slots (x) mc x) => 1 -(with-slots ((something x)) mc something) => 1 -@end example -@end defun - -@node Writing Methods -@comment node-name, next, previous, up -@chapter Writing Methods - -Writing a method in @eieio{} is similar to writing a function. The -differences are that there are some extra options and there can be -multiple definitions under the same function symbol. - -Where a method defines an implementation for a particular data type, a -@dfn{generic method} accepts any argument, but contains no code. It -is used to provide the dispatching to the defined methods. A generic -method has no body, and is merely a symbol upon which methods are -attached. It also provides the base documentation for what methods -with that name do. - -@menu -* Generics:: -* Methods:: -* Static Methods:: -@end menu - -@node Generics -@section Generics - -Each @eieio{} method has one corresponding generic. This generic -provides a function binding and the base documentation for the method -symbol (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp Reference -Manual}). - -@defmac defgeneric method arglist [doc-string] -This macro turns the (unquoted) symbol @var{method} into a function. -@var{arglist} is the default list of arguments to use (not implemented -yet). @var{doc-string} is the documentation used for this symbol. - -A generic function acts as a placeholder for methods. There is no -need to call @code{defgeneric} yourself, as @code{defmethod} will call -it if necessary. Currently the argument list is unused. - -@code{defgeneric} signals an error if you attempt to turn an existing -Emacs Lisp function into a generic function. - -You can also create a generic method with @code{defmethod} -(@pxref{Methods}). When a method is created and there is no generic -method in place with that name, then a new generic will be created, -and the new method will use it. -@end defmac - -In CLOS, a generic call also be used to provide an argument list and -dispatch precedence for all the arguments. In @eieio{}, dispatching -only occurs for the first argument, so the @var{arglist} is not used. - -@node Methods -@section Methods - -A method is a function that is executed if the first argument passed -to it matches the method's class. Different @eieio{} classes may -share the same method names. - -Methods are created with the @code{defmethod} macro, which is similar -to @code{defun}. - -@defmac defmethod method [:before | :primary | :after | :static ] arglist [doc-string] forms - -@var{method} is the name of the function to create. - -@code{:before} and @code{:after} specify execution order (i.e., when -this form is called). If neither of these symbols are present, the -default priority is used (before @code{:after} and after -@code{:before}); this default priority is represented in CLOS as -@code{:primary}. - -@b{Note:} The @code{:BEFORE}, @code{:PRIMARY}, @code{:AFTER}, and -@code{:STATIC} method tags were in all capital letters in previous -versions of @eieio{}. - -@var{arglist} is the list of arguments to this method. The first -argument in this list---and @emph{only} the first argument---may have -a type specifier (see the example below). If no type specifier is -supplied, the method applies to any object. - -@var{doc-string} is the documentation attached to the implementation. -All method doc-strings are incorporated into the generic method's -function documentation. - -@var{forms} is the body of the function. - -@end defmac - -@noindent -In the following example, we create a method @code{mymethod} for the -@code{classname} class: - -@example -(defmethod mymethod ((obj classname) secondarg) - "Doc string" ) -@end example - -@noindent -This method only executes if the @var{obj} argument passed to it is an -@eieio{} object of class @code{classname}. - -A method with no type specifier is a @dfn{default method}. If a given -class has no implementation, then the default method is called when -that method is used on a given object of that class. - -Only one default method per execution specifier (@code{:before}, -@code{:primary}, or @code{:after}) is allowed. If two -@code{defmethod}s appear with @var{arglist}s lacking a type specifier, -and having the same execution specifier, then the first implementation -is replaced. - -When a method is called on an object, but there is no method specified -for that object, but there is a method specified for object's parent -class, the parent class' method is called. If there is a method -defined for both, only the child's method is called. A child method -may call a parent's method using @code{call-next-method}, described -below. - -If multiple methods and default methods are defined for the same -method and class, they are executed in this order: - -@enumerate -@item method :before -@item default :before -@item method :primary -@item default :primary -@item method :after -@item default :after -@end enumerate - -If no methods exist, Emacs signals a @code{no-method-definition} -error. @xref{Signals}. - -@defun call-next-method &rest replacement-args -@anchor{call-next-method} - -This function calls the superclass method from a subclass method. -This is the ``next method'' specified in the current method list. - -If @var{replacement-args} is non-@code{nil}, then use them instead of -@code{eieio-generic-call-arglst}. At the top level, the generic -argument list is passed in. - -Use @code{next-method-p} to find out if there is a next method to -call. -@end defun - -@defun next-method-p -@anchor{next-method-p} -Non-@code{nil} if there is a next method. -Returns a list of lambda expressions which is the @code{next-method} -order. -@end defun - -At present, @eieio{} does not implement all the features of CLOS: - -@enumerate -@item -There is currently no @code{:around} tag. -@item -CLOS allows multiple sets of type-cast arguments, but @eieio{} only -allows the first argument to be cast. -@end enumerate - -@node Static Methods -@section Static Methods - -Static methods do not depend on an object instance, but instead -operate on an object's class. You can create a static method by using -the @code{:static} key with @code{defmethod}. - -Do not treat the first argument of a @code{:static} method as an -object unless you test it first. Use the functions -@code{oref-default} or @code{oset-default} which will work on a class, -or on the class of an object. - -A Class' @code{constructor} method is defined as a @code{:static} -method. - -@b{Note:} The @code{:static} keyword is unique to @eieio{}. - -@c TODO - Write some more about static methods here - -@c @node Method Invocation -@c @chapter Method Invocation - -@c TODO - writeme - -@node Predicates -@comment node-name, next, previous, up -@chapter Predicates and Utilities - -Now that we know how to create classes, access slots, and define -methods, it might be useful to verify that everything is doing ok. To -help with this a plethora of predicates have been created. - -@defun find-class symbol &optional errorp -@anchor{find-class} -Return the class that @var{symbol} represents. -If there is no class, @code{nil} is returned if @var{errorp} is @code{nil}. -If @var{errorp} is non-@code{nil}, @code{wrong-argument-type} is signaled. -@end defun - -@defun class-p class -@anchor{class-p} -Return @code{t} if @var{class} is a valid class vector. -@var{class} is a symbol. -@end defun - -@defun slot-exists-p object-or-class slot -@anchor{slot-exists-p} -Non-@code{nil} if @var{object-or-class} has @var{slot}. -@end defun - -@defun slot-boundp object slot -@anchor{slot-boundp} -Non-@code{nil} if OBJECT's @var{slot} is bound. -Setting a slot's value makes it bound. Calling @dfn{slot-makeunbound} will -make a slot unbound. -@var{object} can be an instance or a class. -@end defun - -@defun class-name class -Return a string of the form @samp{#} which should look -similar to other Lisp objects like buffers and processes. Printing a -class results only in a symbol. -@end defun - -@defun class-option class option -Return the value in @var{CLASS} of a given @var{OPTION}. -For example: - -@example -(class-option eieio-default-superclass :documentation) -@end example - -Will fetch the documentation string for @code{eieio-default-superclass}. -@end defun - -@defun class-constructor class -Return a symbol used as a constructor for @var{class}. The -constructor is a function used to create new instances of -@var{CLASS}. This function provides a way to make an object of a class -without knowing what it is. This is not a part of CLOS. -@end defun - -@defun object-name obj -Return a string of the form @samp{#} for @var{obj}. -This should look like Lisp symbols from other parts of Emacs such as -buffers and processes, and is shorter and cleaner than printing the -object's vector. It is more useful to use @code{object-print} to get -and object's print form, as this allows the object to add extra display -information into the symbol. -@end defun - -@defun object-class obj -Returns the class symbol from @var{obj}. -@end defun - -@defun class-of obj -CLOS symbol which does the same thing as @code{object-class} -@end defun - -@defun object-class-fast obj -Same as @code{object-class} except this is a macro, and no -type-checking is performed. -@end defun - -@defun object-class-name obj -Returns the symbol of @var{obj}'s class. -@end defun - -@defun class-parents class -Returns the direct parents class of @var{class}. Returns @code{nil} if -it is a superclass. -@end defun - -@defun class-parents-fast class -Just like @code{class-parent} except it is a macro and no type checking -is performed. -@end defun - -@defun class-parent class -Deprecated function which returns the first parent of @var{class}. -@end defun - -@defun class-children class -Return the list of classes inheriting from @var{class}. -@end defun - -@defun class-children-fast class -Just like @code{class-children}, but with no checks. -@end defun - -@defun same-class-p obj class -Returns @code{t} if @var{obj}'s class is the same as @var{class}. -@end defun - -@defun same-class-fast-p obj class -Same as @code{same-class-p} except this is a macro and no type checking -is performed. -@end defun - -@defun object-of-class-p obj class -Returns @code{t} if @var{obj} inherits anything from @var{class}. This -is different from @code{same-class-p} because it checks for inheritance. -@end defun - -@defun child-of-class-p child class -Returns @code{t} if @var{child} is a subclass of @var{class}. -@end defun - -@defun generic-p method-symbol -Returns @code{t} if @code{method-symbol} is a generic function, as -opposed to a regular Emacs Lisp function. -@end defun - -@node Association Lists -@chapter Association Lists - -Lisp offers the concept of association lists, with primitives such as -@code{assoc} used to access them. The following functions can be used -to manage association lists of @eieio{} objects: - -@defun object-assoc key slot list -@anchor{object-assoc} -Return an object if @var{key} is @dfn{equal} to SLOT's value of an object in @var{list}. -@var{list} is a list of objects whose slots are searched. -Objects in @var{list} do not need to have a slot named @var{slot}, nor does -@var{slot} need to be bound. If these errors occur, those objects will -be ignored. -@end defun - - -@defun object-assoc-list slot list -Return an association list generated by extracting @var{slot} from all -objects in @var{list}. For each element of @var{list} the @code{car} is -the value of @var{slot}, and the @code{cdr} is the object it was -extracted from. This is useful for generating completion tables. -@end defun - -@defun eieio-build-class-alist &optional base-class -Returns an alist of all currently defined classes. This alist is -suitable for completion lists used by interactive functions to select a -class. The optional argument @var{base-class} allows the programmer to -select only a subset of classes which includes @var{base-class} and -all its subclasses. -@end defun - -@node Customizing -@comment node-name, next, previous, up -@chapter Customizing Objects - -@eieio{} supports the Custom facility through two new widget types. -If a variable is declared as type @code{object}, then full editing of -slots via the widgets is made possible. This should be used -carefully, however, because modified objects are cloned, so if there -are other references to these objects, they will no longer be linked -together. - -If you want in place editing of objects, use the following methods: - -@defun eieio-customize-object object -Create a custom buffer and insert a widget for editing @var{object}. At -the end, an @code{Apply} and @code{Reset} button are available. This -will edit the object "in place" so references to it are also changed. -There is no effort to prevent multiple edits of a singular object, so -care must be taken by the user of this function. -@end defun - -@defun eieio-custom-widget-insert object flags -This method inserts an edit object into the current buffer in place. -It is implemented as @code{(widget-create 'object-edit :value object)}. -This method is provided as a locale for adding tracking, or -specializing the widget insert procedure for any object. -@end defun - -To define a slot with an object in it, use the @code{object} tag. This -widget type will be automatically converted to @code{object-edit} if you -do in place editing of you object. - -If you want to have additional actions taken when a user clicks on the -@code{Apply} button, then overload the method @code{eieio-done-customizing}. -This method does nothing by default, but that may change in the future. -This would be the best way to make your objects persistent when using -in-place editing. - -@section Widget extension - -When widgets are being created, one new widget extension has been added, -called the @code{:slotofchoices}. When this occurs in a widget -definition, all elements after it are removed, and the slot is specifies -is queried and converted into a series of constants. - -@example -(choice (const :tag "None" nil) - :slotofchoices morestuff) -@end example - -and if the slot @code{morestuff} contains @code{(sym1 sym2 sym3)}, the -above example is converted into: - -@example -(choice (const :tag "None" nil) - (const sym1) - (const sym2) - (const sym3)) -@end example - -This is useful when a given item needs to be selected from a list of -items defined in this second slot. - -@node Introspection -@chapter Introspection - -Introspection permits a programmer to peek at the contents of a class -without any previous knowledge of that class. While @eieio{} implements -objects on top of vectors, and thus everything is technically visible, -some functions have been provided. None of these functions are a part -of CLOS. - -@defun object-slots obj -Return the list of public slots for @var{obj}. -@end defun - -@defun class-slot-initarg class slot -For the given @var{class} return the :initarg associated with -@var{slot}. Not all slots have initargs, so the return value can be -nil. -@end defun - -@node Base Classes -@comment node-name, next, previous, up -@chapter Base Classes - -All defined classes, if created with no specified parent class, -inherit from a special class called @code{eieio-default-superclass}. -@xref{Default Superclass}. - -Often, it is more convenient to inherit from one of the other base -classes provided by @eieio{}, which have useful pre-defined -properties. (Since @eieio{} supports multiple inheritance, you can -even inherit from more than one of these classes at once.) - -@menu -* eieio-instance-inheritor:: Enable value inheritance between instances. -* eieio-instance-tracker:: Enable self tracking instances. -* eieio-singleton:: Only one instance of a given class. -* eieio-persistent:: Enable persistence for a class. -* eieio-named:: Use the object name as a :name slot. -* eieio-speedbar:: Enable speedbar support in your objects. -@end menu - -@node eieio-instance-inheritor -@comment node-name, next, previous, up -@section @code{eieio-instance-inheritor} - -This class is defined in the package @file{eieio-base}. - -Instance inheritance is a mechanism whereby the value of a slot in -object instance can reference the parent instance. If the parent's slot -value is changed, then the child instance is also changed. If the -child's slot is set, then the parent's slot is not modified. - -@deftp {Class} eieio-instance-inheritor parent-instance -A class whose instances are enabled with instance inheritance. -The @var{parent-instance} slot indicates the instance which is -considered the parent of the current instance. Default is @code{nil}. -@end deftp - -@cindex clone -To use this class, inherit from it with your own class. -To make a new instance that inherits from and existing instance of your -class, use the @code{clone} method with additional parameters -to specify local values. - -@cindex slot-unbound -The @code{eieio-instance-inheritor} class works by causing cloned -objects to have all slots unbound. This class' @code{slot-unbound} -method will cause references to unbound slots to be redirected to the -parent instance. If the parent slot is also unbound, then -@code{slot-unbound} will signal an error named @code{slot-unbound}. - -@node eieio-instance-tracker -@section @code{eieio-instance-tracker} - -This class is defined in the package @file{eieio-base}. - -Sometimes it is useful to keep a master list of all instances of a given -class. The class @code{eieio-instance-tracker} performs this task. - -@deftp {Class} eieio-instance-tracker tracker-symbol -Enable instance tracking for this class. -The slot @var{tracker-symbol} should be initialized in inheritors of -this class to a symbol created with @code{defvar}. This symbol will -serve as the variable used as a master list of all objects of the given -class. -@end deftp - -@defmethod eieio-instance-tracker initialize-instance obj slot -This method is defined as an @code{:after} method. -It adds new instances to the master list. Do not overload this method -unless you use @code{call-next-method.} -@end defmethod - -@defmethod eieio-instance-tracker delete-instance obj -Remove @var{obj} from the master list of instances of this class. -This may let the garbage collector nab this instance. -@end defmethod - -@deffn eieio-instance-tracker-find key slot list-symbol -This convenience function lets you find instances. @var{key} is the -value to search for. @var{slot} is the slot to compare @var{KEY} -against. The function @code{equal} is used for comparison. -The parameter @var{list-symbol} is the variable symbol which contains the -list of objects to be searched. -@end deffn - -@node eieio-singleton -@comment node-name, next, previous, up -@section @code{eieio-singleton} - -This class is defined in the package @file{eieio-base}. - -@deftp {Class} eieio-singleton -Inheriting from the singleton class will guarantee that there will -only ever be one instance of this class. Multiple calls to -@code{make-instance} will always return the same object. -@end deftp - -@node eieio-persistent -@comment node-name, next, previous, up -@section @code{eieio-persistent} - -This class is defined in the package @file{eieio-base}. - -If you want an object, or set of objects to be persistent, meaning the -slot values are important to keep saved between sessions, then you will -want your top level object to inherit from @code{eieio-persistent}. - -To make sure your persistent object can be moved, make sure all file -names stored to disk are made relative with -@code{eieio-persistent-path-relative}. - -@deftp {Class} eieio-persistent file file-header-line -Enables persistence for instances of this class. -Slot @var{file} with initarg @code{:file} is the file name in which this -object will be saved. -Class allocated slot @var{file-header-line} is used with method -@code{object-write} as a header comment. -@end deftp - -All objects can write themselves to a file, but persistent objects have -several additional methods that aid in maintaining them. - -@defmethod eieio-persistent eieio-persistent-save obj &optional file -Write the object @var{obj} to its file. -If optional argument @var{file} is specified, use that file name -instead. -@end defmethod - -@defmethod eieio-persistent eieio-persistent-path-relative obj file -Return a file name derived from @var{file} which is relative to the -stored location of @var{OBJ}. This method should be used to convert -file names so that they are relative to the save file, making any system -of files movable from one location to another. -@end defmethod - -@defmethod eieio-persistent object-write obj &optional comment -Like @code{object-write} for @code{standard-object}, but will derive -a header line comment from the class allocated slot if one is not -provided. -@end defmethod - -@defun eieio-persistent-read filename -Read @var{filename} which contains an @code{eieio-persistent} object -previously written with @code{eieio-persistent-save}. -@end defun - -@node eieio-named -@comment node-name, next, previous, up -@section @code{eieio-named} - -This class is defined in the package @file{eieio-base}. - -@deftp {Class} eieio-named -Object with a name. -Name storage already occurs in an object. This object provides get/set -access to it. -@end deftp - -@node eieio-speedbar -@comment node-name, next, previous, up -@section @code{eieio-speedbar} - -This class is in package @file{eieio-speedbar}. - -If a series of class instances map to a tree structure, it is possible -to cause your classes to be displayable in Speedbar. @xref{Top,,,speedbar}. -Inheriting from these classes will enable a speedbar major display mode -with a minimum of effort. - -@deftp {Class} eieio-speedbar buttontype buttonface -Enables base speedbar display for a class. -@cindex speedbar-make-tag-line -The slot @var{buttontype} is any of the symbols allowed by the -function @code{speedbar-make-tag-line} for the @var{exp-button-type} -argument @xref{Extending,,,speedbar}. -The slot @var{buttonface} is the face to use for the text of the string -displayed in speedbar. -The slots @var{buttontype} and @var{buttonface} are class allocated -slots, and do not take up space in your instances. -@end deftp - -@deftp {Class} eieio-speedbar-directory-button buttontype buttonface -This class inherits from @code{eieio-speedbar} and initializes -@var{buttontype} and @var{buttonface} to appear as directory level lines. -@end deftp - -@deftp {Class} eieio-speedbar-file-button buttontype buttonface -This class inherits from @code{eieio-speedbar} and initializes -@var{buttontype} and @var{buttonface} to appear as file level lines. -@end deftp - -To use these classes, inherit from one of them in you class. You can -use multiple inheritance with them safely. To customize your class for -speedbar display, override the default values for @var{buttontype} and -@var{buttonface} to get the desired effects. - -Useful methods to define for your new class include: - -@defmethod eieio-speedbar eieio-speedbar-derive-line-path obj depth -Return a string representing a directory associated with an instance -of @var{obj}. @var{depth} can be used to index how many levels of -indentation have been opened by the user where @var{obj} is shown. -@end defmethod - - -@defmethod eieio-speedbar eieio-speedbar-description obj -Return a string description of @var{OBJ}. -This is shown in the minibuffer or tooltip when the mouse hovers over -this instance in speedbar. -@end defmethod - -@defmethod eieio-speedbar eieio-speedbar-child-description obj -Return a string representing a description of a child node of @var{obj} -when that child is not an object. It is often useful to just use -item info helper functions such as @code{speedbar-item-info-file-helper}. -@end defmethod - -@defmethod eieio-speedbar eieio-speedbar-object-buttonname obj -Return a string which is the text displayed in speedbar for @var{obj}. -@end defmethod - -@defmethod eieio-speedbar eieio-speedbar-object-children obj -Return a list of children of @var{obj}. -@end defmethod - -@defmethod eieio-speedbar eieio-speedbar-child-make-tag-lines obj depth -This method inserts a list of speedbar tag lines for @var{obj} to -represent its children. Implement this method for your class -if your children are not objects themselves. You still need to -implement @code{eieio-speedbar-object-children}. - -In this method, use techniques specified in the Speedbar manual. -@xref{Extending,,,speedbar}. -@end defmethod - -Some other functions you will need to learn to use are: - -@deffn eieio-speedbar-create make-map key-map menu name toplevelfn -Register your object display mode with speedbar. -@var{make-map} is a function which initialized you keymap. -@var{key-map} is a symbol you keymap is installed into. -@var{menu} is an easy menu vector representing menu items specific to your -object display. -@var{name} is a short string to use as a name identifying you mode. -@var{toplevelfn} is a function called which must return a list of -objects representing those in the instance system you wish to browse in -speedbar. - -Read the Extending chapter in the speedbar manual for more information -on how speedbar modes work -@xref{Extending,,,speedbar}. -@end deffn - -@node Browsing -@comment node-name, next, previous, up -@chapter Browsing class trees - -The command @kbd{M-x eieio-browse} displays a buffer listing all the -currently loaded classes in Emacs. The classes are listed in an -indented tree structure, starting from @code{eieio-default-superclass} -(@pxref{Default Superclass}). - -With a prefix argument, this command prompts for a class name; it then -lists only that class and its subclasses. - -Here is a sample tree from our current example: - -@example -eieio-default-superclass - +--data-object - +--data-object-symbol -@end example - -Note: new classes are consed into the inheritance lists, so the tree -comes out upside-down. - -@node Class Values -@comment node-name, next, previous, up -@chapter Class Values - -Details about any class or object can be retrieved using the function -@code{eieio-describe-class}. Interactively, type in the name of -a class. In a program, pass it a string with the name of a class, a -class symbol, or an object. The resulting buffer will display all slot -names. - -Additionally, all methods defined to have functionality on this class -are displayed. - -@node Default Superclass -@comment node-name, next, previous, up -@chapter Default Superclass - -All defined classes, if created with no specified parent class, will -inherit from a special class stored in -@code{eieio-default-superclass}. This superclass is quite simple, but -with it, certain default methods or attributes can be added to all -objects. In CLOS, this would be named @code{STANDARD-CLASS}, and that -symbol is an alias to @code{eieio-default-superclass}. -@refill - -Currently, the default superclass is defined as follows: - -@example -(defclass eieio-default-superclass nil - nil - "Default parent class for classes with no specified parent class. -Its slots are automatically adopted by classes with no specified -parents. This class is not stored in the `parent' slot of a class vector." - :abstract t) -@end example - -The default superclass implements several methods providing a default -behavior for all objects created by @eieio{}. - -@menu -* Initialization:: How objects are initialized -* Basic Methods:: Clone, print, and write -* Signal Handling:: Methods for managing signals. -@end menu - -@node Initialization -@section Initialization - -When creating an object of any type, you can use its constructor, or -@code{make-instance}. This, in turns calls the method -@code{initialize-instance}, which then calls the method -@code{shared-initialize}. - -These methods are all implemented on the default superclass so you do -not need to write them yourself, unless you need to override one of -their behaviors. - -Users should not need to call @code{initialize-instance} or -@code{shared-initialize}, as these are used by @code{make-instance} to -initialize the object. They are instead provided so that users can -augment these behaviors. - -@defun initialize-instance obj &rest slots -Initialize @var{obj}. Sets slots of @var{obj} with @var{slots} which -is a list of name/value pairs. These are actually just passed to -@code{shared-initialize}. -@end defun - -@defun shared-initialize obj &rest slots -Sets slots of @var{obj} with @var{slots} which is a list of name/value -pairs. - -This is called from the default @code{constructor}. -@end defun - -@node Basic Methods -@section Basic Methods - -Additional useful methods defined on the base subclass are: - -@defun clone obj &rest params -@anchor{clone} -Make a copy of @var{obj}, and then apply @var{params}. -@var{params} is a parameter list of the same form as @var{initialize-instance} -which are applied to change the object. When overloading @dfn{clone}, be -sure to call @dfn{call-next-method} first and modify the returned object. -@end defun - -@defun object-print this &rest strings -@anchor{object-print} -Pretty printer for object @var{this}. Call function @dfn{object-name} with @var{strings}. -The default method for printing object @var{this} is to use the -function @dfn{object-name}. - -It is sometimes useful to put a summary of the object into the -default # string when using eieio browsing tools. - -Implement this function and specify @var{strings} in a call to -@dfn{call-next-method} to provide additional summary information. -When passing in extra strings from child classes, always remember -to prepend a space. - -@example -(defclass data-object () - (value) - "Object containing one data slot.") - -(defmethod object-print ((this data-object) &optional strings) - "Return a string with a summary of the data object as part of the name." - (apply 'call-next-method this - (cons (format " value: %s" (render this)) strings))) -@end example - -Here is what some output could look like: -@example -(object-print test-object) - => # -@end example -@end defun - -@defun object-write obj &optional comment -Write @var{obj} onto a stream in a readable fashion. The resulting -output will be Lisp code which can be used with @code{read} and -@code{eval} to recover the object. Only slots with @code{:initarg}s -are written to the stream. -@end defun - -@node Signal Handling -@section Signal Handling - -The default superclass defines methods for managing error conditions. -These methods all throw a signal for a particular error condition. - -By implementing one of these methods for a class, you can change the -behavior that occurs during one of these error cases, or even ignore -the error by providing some behavior. - -@defun slot-missing object slot-name operation &optional new-value -@anchor{slot-missing} -Method invoked when an attempt to access a slot in @var{object} fails. -@var{slot-name} is the name of the failed slot, @var{operation} is the type of access -that was requested, and optional @var{new-value} is the value that was desired -to be set. - -This method is called from @code{oref}, @code{oset}, and other functions which -directly reference slots in EIEIO objects. - -The default method signals an error of type @code{invalid-slot-name}. -@xref{Signals}. - -You may override this behavior, but it is not expected to return in the -current implementation. - -This function takes arguments in a different order than in CLOS. -@end defun - -@defun slot-unbound object class slot-name fn -@anchor{slot-unbound} -Slot unbound is invoked during an attempt to reference an unbound slot. -@var{object} is the instance of the object being reference. @var{class} is the -class of @var{object}, and @var{slot-name} is the offending slot. This function -throws the signal @code{unbound-slot}. You can overload this function and -return the value to use in place of the unbound value. -Argument @var{fn} is the function signaling this error. -Use @dfn{slot-boundp} to determine if a slot is bound or not. - -In @var{clos}, the argument list is (@var{class} @var{object} @var{slot-name}), but -@var{eieio} can only dispatch on the first argument, so the first two are swapped. -@end defun - -@defun no-applicable-method object method &rest args -@anchor{no-applicable-method} -Called if there are no implementations for @var{object} in @var{method}. -@var{object} is the object which has no method implementation. -@var{args} are the arguments that were passed to @var{method}. - -Implement this for a class to block this signal. The return -value becomes the return value of the original method call. -@end defun - -@defun no-next-method object &rest args -@anchor{no-next-method} -Called from @dfn{call-next-method} when no additional methods are available. -@var{object} is othe object being called on @dfn{call-next-method}. -@var{args} are the arguments it is called by. -This method signals @dfn{no-next-method} by default. Override this -method to not throw an error, and its return value becomes the -return value of @dfn{call-next-method}. -@end defun - -@node Signals -@comment node-name, next, previous, up -@chapter Signals - -There are new condition names (signals) that can be caught when using -@eieio{}. - -@deffn Signal invalid-slot-name obj-or-class slot -This signal is called when an attempt to reference a slot in an -@var{obj-or-class} is made, and the @var{slot} is not defined for -it. -@end deffn - -@deffn Signal no-method-definition method arguments -This signal is called when @var{method} is called, with @var{arguments} -and nothing is resolved. This occurs when @var{method} has been -defined, but the arguments make it impossible for @eieio{} to determine -which method body to run. - -To prevent this signal from occurring in your class, implement the -method @code{no-applicable-method} for your class. This method is -called when to throw this signal, so implementing this for your class -allows you block the signal, and perform some work. -@end deffn - -@deffn Signal no-next-method class arguments -This signal is called if the function @code{call-next-method} is called -and there is no next method to be called. - -Overload the method @code{no-next-method} to protect against this signal. -@end deffn - -@deffn Signal invalid-slot-type slot spec value -This signal is called when an attempt to set @var{slot} is made, and -@var{value} doesn't match the specified type @var{spec}. - -In @eieio{}, this is also used if a slot specifier has an invalid value -during a @code{defclass}. -@end deffn - -@deffn Signal unbound-slot object class slot -This signal is called when an attempt to reference @var{slot} in -@var{object} is made, and that instance is currently unbound. -@end deffn - -@node Naming Conventions -@comment node-name, next, previous, up -@chapter Naming Conventions - -@xref{Tips,,Tips and Conventions,elisp,GNU Emacs Lisp Reference -Manual}, for a description of Emacs Lisp programming conventions. -These conventions help ensure that Emacs packages work nicely one -another, so an @eieio{}-based program should follow them. Here are -some conventions that apply specifically to @eieio{}-based programs: - -@itemize - -@item Come up with a package prefix that is relatively short. Prefix -all classes, and methods with your prefix. This is a standard -convention for functions and variables in Emacs. - -@item Do not prefix method names with the class name. All methods in -@eieio{} are ``virtual'', and are dynamically dispatched. Anyone can -override your methods at any time. Your methods should be prefixed -with your package name. - -@item Do not prefix slots in your class. The slots are always locally -scoped to your class, and need no prefixing. - -@item If your library inherits from other libraries of classes, you -must ``require'' that library with the @code{require} command. - -@end itemize - -@node CLOS compatibility -@comment node-name, next, previous, up -@chapter CLOS compatibility - -Currently, the following functions should behave almost as expected from -CLOS. - -@table @code - -@item defclass -All slot keywords are available but not all work correctly. -Slot keyword differences are: - -@table @asis - -@item :reader, and :writer tags -Create methods that signal errors instead of creating an unqualified -method. You can still create new ones to do its business. - -@item :accessor -This should create an unqualified method to access a slot, but -instead pre-builds a method that gets the slot's value. - -@item :type -Specifier uses the @code{typep} function from the @file{cl} -package. @xref{(cl)Type Predicates}. It therefore has the same issues as -that package. Extensions include the ability to provide object names. -@end table - -Defclass also supports class options, but does not currently use values -of @code{:metaclass}, and @code{:default-initargs}. - -@item make-instance -Make instance works as expected, however it just uses the @eieio{} instance -creator automatically generated when a new class is created. -@xref{Making New Objects}. - -@item defgeneric -Creates the desired symbol, and accepts all of the expected arguments -except @code{:around}. - -@item defmethod -Calls defgeneric, and accepts most of the expected arguments. Only -the first argument to the created method may have a type specifier. -To type cast against a class, the class must exist before defmethod is -called. In addition, the @code{:around} tag is not supported. - -@item call-next-method -Inside a method, calls the next available method up the inheritance tree -for the given object. This is different than that found in CLOS because -in @eieio{} this function accepts replacement arguments. This permits -subclasses to modify arguments as they are passed up the tree. If no -arguments are given, the expected CLOS behavior is used. -@item setf -If the common-lisp subsystem is loaded, the setf parameters are also -loaded so the form @code{(setf (slot-value object slot) t)} should -work. -@end table - -CLOS supports the @code{describe} command, but @eieio{} only provides -@code{eieio-describe-class}, and @code{eieio-describe-generic}. These -functions are adviced into @code{describe-variable}, and -@code{describe-function}. - -When creating a new class (@pxref{Building Classes}) there are several -new keywords supported by @eieio{}. - -In @eieio{} tags are in lower case, not mixed case. - -@node Wish List -@chapter Wish List - -@eieio{} is an incomplete implementation of CLOS. Finding ways to -improve the compatibility would help make CLOS style programs run -better in Emacs. - -Some important compatibility features that would be good to add are: - -@enumerate -@item -@code{:around} method key. - -@item -Method dispatch for built-in types. -@item -Method dispatch for multiple argument typing. -@item -Improve integration with the @file{cl} package. -@end enumerate - -There are also improvements to be made to allow @eieio{} to operate -better in the Emacs environment. - -@enumerate -@item -Allow subclassing of Emacs built-in types, such as faces, markers, and -buffers. -@item -Allow method overloading of method-like functions in Emacs. -@end enumerate - -@node Function Index -@unnumbered Function Index - -@printindex fn - -@contents -@bye diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi deleted file mode 100644 index 12e65c9e8dd..00000000000 --- a/doc/misc/emacs-gnutls.texi +++ /dev/null @@ -1,198 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@setfilename ../../info/emacs-gnutls -@settitle Emacs GnuTLS Integration @value{VERSION} - -@set VERSION 0.3 - -@copying -This file describes the Emacs GnuTLS integration. - -Copyright @copyright{} 2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License'' -in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* GnuTLS: (emacs-gnutls). The Emacs GnuTLS integration. -@end direntry - -@titlepage -@title Emacs GnuTLS Integration -@author by Ted Zlatanov -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Emacs GnuTLS -This manual describes the Emacs GnuTLS integration. - -GnuTLS is a library that establishes encrypted @acronym{SSL} or -@acronym{TLS} connections. Emacs supports it through the -@file{gnutls.c} and @file{gnutls.h} C files and the @file{gnutls.el} -Emacs Lisp library. - -@insertcopying - -@menu -* Overview:: Overview of the GnuTLS integration. -* Help For Users:: -* Help For Developers:: -* Function Index:: -* Variable Index:: -@end menu -@end ifnottex - -@node Overview -@chapter Overview - -The GnuTLS library is an optional add-on for Emacs. Through it, any -Emacs Lisp program can establish encrypted network connections that -use @dfn{Secure Socket Layer} (@acronym{SSL}) and @dfn{Transport Layer -Security} (@acronym{TLS}) protocols. The process of using -@acronym{SSL} and @acronym{TLS} in establishing connections is as -automated and transparent as possible. - -The user has only a few customization options currently: the log -level, priority string, trustfile list, and the minimum number of bits -to be used in Diffie-Hellman key exchange. Rumors that every Emacs -library requires at least 83 customizable variables are thus proven -false. - -@node Help For Users -@chapter Help For Users - -From the user's perspective, there's nothing to the GnuTLS -integration. It Just Works for any Emacs Lisp code that uses -@code{open-protocol-stream} or @code{open-network-stream} -(@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference -Manual}). The two functions are equivalent, the first one being an -alias of the second. - -There's one way to find out if GnuTLS is available, by calling -@code{gnutls-available-p}. This is a little bit trickier on the W32 -(Windows) platform, but if you have the GnuTLS DLLs (available from -@url{http://sourceforge.net/projects/ezwinports/files/} thanks to Eli -Zaretskii) in the same directory as Emacs, you should be OK. - -@defun gnutls-available-p -This function returns t if GnuTLS is available in this instance of Emacs. -@end defun - -Oh, but sometimes things go wrong. Budgets aren't balanced, -television ads lie, and even TLS and SSL connections can fail to work -properly. Well, there's something to be done in the last case. - -@defvar gnutls-log-level -The @code{gnutls-log-level} variable sets the log level. 1 is -verbose. 2 is very verbose. 5 is crazy. Crazy! Set it to 1 or 2 -and look in the @code{*Messages*} buffer for the debugging -information. -@end defvar - -@defvar gnutls-algorithm-priority -The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority -string. This is global, not per host name (although -@code{gnutls-negotiate} supports a priority string per connection so -it could be done if needed). The priority string syntax is in the -@uref{http://www.gnu.org/software/gnutls/documentation.html, GnuTLS -documentation}. -@end defvar - -@defvar gnutls-trustfiles -The @code{gnutls-trustfiles} variable is a list of trustfiles -(certificates for the issuing authorities). This is global, not per -host name (although @code{gnutls-negotiate} supports a trustfile per -connection so it could be done if needed). The trustfiles can be in -PEM or DER format and examples can be found in most Unix -distributions. By default four locations are tried in this order: -@file{/etc/ssl/certs/ca-certificates.crt} for Debian, Ubuntu, Gentoo -and Arch Linux; @file{/etc/pki/tls/certs/ca-bundle.crt} for Fedora -and RHEL; @file{/etc/ssl/ca-bundle.pem} for Suse; -@file{/usr/ssl/certs/ca-bundle.crt} for Cygwin. You can easily -customize @code{gnutls-trustfiles} to be something else, but let us -know if you do, so we can make the change to benefit the other users -of that platform. -@end defvar - -@defvar gnutls-min-prime-bits -The @code{gnutls-min-prime-bits} variable is a pretty exotic -customization for cases where you want to refuse handshakes with keys -under a specific size. If you don't know for sure that you need it, -you don't. Leave it @code{nil}. -@end defvar - -@node Help For Developers -@chapter Help For Developers - -The GnuTLS library is detected automatically at compile time. You -should see that it's enabled in the @code{configure} output. If not, -follow the standard procedure for finding out why a system library is -not picked up by the Emacs compilation. On the W32 (Windows) -platform, installing the DLLs with a recent build should be enough. - -Just use @code{open-protocol-stream} or @code{open-network-stream} -(the two are equivalent, the first one being an alias to the second). -You should not have to use the @file{gnutls.el} functions directly. -But you can test them with @code{open-gnutls-stream}. - -@defun open-gnutls-stream name buffer host service -This function creates a buffer connected to a specific @var{host} and -@var{service} (port number or service name). The parameters and their -syntax are the same as those given to @code{open-network-stream} -(@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference -Manual}). The connection process is called @var{name} (made unique if -necessary). This function returns the connection process. - -@lisp -;; open a HTTPS connection -(open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https") - -;; open a IMAPS connection -(open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps") -@end lisp - -@end defun - -The function @code{gnutls-negotiate} is not generally useful and it -may change as needed, so please see @file{gnutls.el} for the details. - -@defun gnutls-negotiate spec -Please see @file{gnutls.el} for the @var{spec} details and for usage, -but do not rely on this function's interface if possible. -@end defun - -@node Function Index -@chapter Function Index -@printindex fn - -@node Variable Index -@chapter Variable Index -@printindex vr - -@bye - -@c End: diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi deleted file mode 100644 index 896eba2f1bb..00000000000 --- a/doc/misc/emacs-mime.texi +++ /dev/null @@ -1,1895 +0,0 @@ -\input texinfo - -@include gnus-overrides.texi - -@setfilename ../../info/emacs-mime -@settitle Emacs MIME Manual -@synindex fn cp -@synindex vr cp -@synindex pg cp - -@copying -This file documents the Emacs MIME interface functionality. - -Copyright @copyright{} 1998-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@c Node ``Interface Functions'' uses Latin-1 characters -@documentencoding ISO-8859-1 - -@dircategory Emacs lisp libraries -@direntry -* Emacs MIME: (emacs-mime). Emacs MIME de/composition library. -@end direntry -@iftex -@finalout -@end iftex -@setchapternewpage odd - -@titlepage -@ifset WEBHACKDEVEL -@title Emacs MIME Manual (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title Emacs MIME Manual -@end ifclear - -@author by Lars Magne Ingebrigtsen -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top Emacs MIME - -This manual documents the libraries used to compose and display -@acronym{MIME} messages. - -This manual is directed at users who want to modify the behavior of -the @acronym{MIME} encoding/decoding process or want a more detailed -picture of how the Emacs @acronym{MIME} library works, and people who want -to write functions and commands that manipulate @acronym{MIME} elements. - -@acronym{MIME} is short for @dfn{Multipurpose Internet Mail Extensions}. -This standard is documented in a number of RFCs; mainly RFC2045 (Format -of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message -Header Extensions for Non-@acronym{ASCII} Text), RFC2048 (Registration -Procedures), RFC2049 (Conformance Criteria and Examples). It is highly -recommended that anyone who intends writing @acronym{MIME}-compliant software -read at least RFC2045 and RFC2047. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Decoding and Viewing:: A framework for decoding and viewing. -* Composing:: @acronym{MML}; a language for describing @acronym{MIME} parts. -* Interface Functions:: An abstraction over the basic functions. -* Basic Functions:: Utility and basic parsing functions. -* Standards:: A summary of RFCs and working documents used. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Function and variable index. -@end menu - - -@node Decoding and Viewing -@chapter Decoding and Viewing - -This chapter deals with decoding and viewing @acronym{MIME} messages on a -higher level. - -The main idea is to first analyze a @acronym{MIME} article, and then allow -other programs to do things based on the list of @dfn{handles} that are -returned as a result of this analysis. - -@menu -* Dissection:: Analyzing a @acronym{MIME} message. -* Non-MIME:: Analyzing a non-@acronym{MIME} message. -* Handles:: Handle manipulations. -* Display:: Displaying handles. -* Display Customization:: Variables that affect display. -* Files and Directories:: Saving and naming attachments. -* New Viewers:: How to write your own viewers. -@end menu - - -@node Dissection -@section Dissection - -The @code{mm-dissect-buffer} is the function responsible for dissecting -a @acronym{MIME} article. If given a multipart message, it will recursively -descend the message, following the structure, and return a tree of -@acronym{MIME} handles that describes the structure of the message. - -@node Non-MIME -@section Non-MIME -@vindex mm-uu-configure-list - -Gnus also understands some non-@acronym{MIME} attachments, such as -postscript, uuencode, binhex, yenc, shar, forward, gnatsweb, pgp, -diff. Each of these features can be disabled by add an item into -@code{mm-uu-configure-list}. For example, - -@lisp -(require 'mm-uu) -(add-to-list 'mm-uu-configure-list '(pgp-signed . disabled)) -@end lisp - -@table @code -@item postscript -@findex postscript -PostScript file. - -@item uu -@findex uu -Uuencoded file. - -@item binhex -@findex binhex -Binhex encoded file. - -@item yenc -@findex yenc -Yenc encoded file. - -@item shar -@findex shar -Shar archive file. - -@item forward -@findex forward -Non-@acronym{MIME} forwarded message. - -@item gnatsweb -@findex gnatsweb -Gnatsweb attachment. - -@item pgp-signed -@findex pgp-signed -@acronym{PGP} signed clear text. - -@item pgp-encrypted -@findex pgp-encrypted -@acronym{PGP} encrypted clear text. - -@item pgp-key -@findex pgp-key -@acronym{PGP} public keys. - -@item emacs-sources -@findex emacs-sources -@vindex mm-uu-emacs-sources-regexp -Emacs source code. This item works only in the groups matching -@code{mm-uu-emacs-sources-regexp}. - -@item diff -@vindex diff -@vindex mm-uu-diff-groups-regexp -Patches. This is intended for groups where diffs of committed files -are automatically sent to. It only works in groups matching -@code{mm-uu-diff-groups-regexp}. - -@item verbatim-marks -@cindex verbatim-marks -Slrn-style verbatim marks. - -@item LaTeX -@cindex LaTeX -LaTeX documents. It only works in groups matching -@code{mm-uu-tex-groups-regexp}. - -@end table - -@cindex text/x-verbatim -@c Is @vindex suitable for a face? -@vindex mm-uu-extract -Some inlined non-@acronym{MIME} attachments are displayed using the face -@code{mm-uu-extract}. By default, no @acronym{MIME} button for these -parts is displayed. You can force displaying a button using @kbd{K b} -(@code{gnus-summary-display-buttonized}) or add @code{text/x-verbatim} -to @code{gnus-buttonized-mime-types}, @xref{MIME Commands, ,MIME -Commands, gnus, Gnus Manual}. - -@node Handles -@section Handles - -A @acronym{MIME} handle is a list that fully describes a @acronym{MIME} -component. - -The following macros can be used to access elements in a handle: - -@table @code -@item mm-handle-buffer -@findex mm-handle-buffer -Return the buffer that holds the contents of the undecoded @acronym{MIME} -part. - -@item mm-handle-type -@findex mm-handle-type -Return the parsed @code{Content-Type} of the part. - -@item mm-handle-encoding -@findex mm-handle-encoding -Return the @code{Content-Transfer-Encoding} of the part. - -@item mm-handle-undisplayer -@findex mm-handle-undisplayer -Return the object that can be used to remove the displayed part (if it -has been displayed). - -@item mm-handle-set-undisplayer -@findex mm-handle-set-undisplayer -Set the undisplayer object. - -@item mm-handle-disposition -@findex mm-handle-disposition -Return the parsed @code{Content-Disposition} of the part. - -@item mm-get-content-id -Returns the handle(s) referred to by @code{Content-ID}. - -@end table - - -@node Display -@section Display - -Functions for displaying, removing and saving. - -@table @code -@item mm-display-part -@findex mm-display-part -Display the part. - -@item mm-remove-part -@findex mm-remove-part -Remove the part (if it has been displayed). - -@item mm-inlinable-p -@findex mm-inlinable-p -Say whether a @acronym{MIME} type can be displayed inline. - -@item mm-automatic-display-p -@findex mm-automatic-display-p -Say whether a @acronym{MIME} type should be displayed automatically. - -@item mm-destroy-part -@findex mm-destroy-part -Free all resources occupied by a part. - -@item mm-save-part -@findex mm-save-part -Offer to save the part in a file. - -@item mm-pipe-part -@findex mm-pipe-part -Offer to pipe the part to some process. - -@item mm-interactively-view-part -@findex mm-interactively-view-part -Prompt for a mailcap method to use to view the part. - -@end table - - -@node Display Customization -@section Display Customization - -@table @code - -@item mm-inline-media-tests -@vindex mm-inline-media-tests -This is an alist where the key is a @acronym{MIME} type, the second element -is a function to display the part @dfn{inline} (i.e., inside Emacs), and -the third element is a form to be @code{eval}ed to say whether the part -can be displayed inline. - -This variable specifies whether a part @emph{can} be displayed inline, -and, if so, how to do it. It does not say whether parts are -@emph{actually} displayed inline. - -@item mm-inlined-types -@vindex mm-inlined-types -This, on the other hand, says what types are to be displayed inline, if -they satisfy the conditions set by the variable above. It's a list of -@acronym{MIME} media types. - -@item mm-automatic-display -@vindex mm-automatic-display -This is a list of types that are to be displayed ``automatically'', but -only if the above variable allows it. That is, only inlinable parts can -be displayed automatically. - -@item mm-automatic-external-display -@vindex mm-automatic-external-display -This is a list of types that will be displayed automatically in an -external viewer. - -@item mm-keep-viewer-alive-types -@vindex mm-keep-viewer-alive-types -This is a list of media types for which the external viewer will not -be killed when selecting a different article. - -@item mm-attachment-override-types -@vindex mm-attachment-override-types -Some @acronym{MIME} agents create parts that have a content-disposition of -@samp{attachment}. This variable allows overriding that disposition and -displaying the part inline. (Note that the disposition is only -overridden if we are able to, and want to, display the part inline.) - -@item mm-discouraged-alternatives -@vindex mm-discouraged-alternatives -List of @acronym{MIME} types that are discouraged when viewing -@samp{multipart/alternative}. Viewing agents are supposed to view the -last possible part of a message, as that is supposed to be the richest. -However, users may prefer other types instead, and this list says what -types are most unwanted. If, for instance, @samp{text/html} parts are -very unwanted, and @samp{text/richtext} parts are somewhat unwanted, -you could say something like: - -@lisp -(setq mm-discouraged-alternatives - '("text/html" "text/richtext") - mm-automatic-display - (remove "text/html" mm-automatic-display)) -@end lisp - -Adding @code{"image/.*"} might also be useful. Spammers use images as -the preferred part of @samp{multipart/alternative} messages, so you might -not notice there are other parts. See also -@code{gnus-buttonized-mime-types}, @ref{MIME Commands, ,MIME Commands, -gnus, Gnus Manual}. After adding @code{"multipart/alternative"} to -@code{gnus-buttonized-mime-types} you can choose manually which -alternative you'd like to view. For example, you can set those -variables like: - -@lisp -(setq gnus-buttonized-mime-types - '("multipart/alternative" "multipart/signed") - mm-discouraged-alternatives - '("text/html" "image/.*")) -@end lisp - -In this case, Gnus will display radio buttons for such a kind of spam -message as follows: - -@example -1. (*) multipart/alternative ( ) image/gif - -2. (*) text/plain ( ) text/html -@end example - -@item mm-inline-large-images -@vindex mm-inline-large-images -When displaying inline images that are larger than the window, Emacs -does not enable scrolling, which means that you cannot see the whole -image. To prevent this, the library tries to determine the image size -before displaying it inline, and if it doesn't fit the window, the -library will display it externally (e.g. with @samp{ImageMagick} or -@samp{xv}). Setting this variable to @code{t} disables this check and -makes the library display all inline images as inline, regardless of -their size. If you set this variable to @code{resize}, the image will -be displayed resized to fit in the window, if Emacs has the ability to -resize images. - -@item mm-inline-large-images-proportion -@vindex mm-inline-images-max-proportion -The proportion used when resizing large images. - -@item mm-inline-override-types -@vindex mm-inline-override-types -@code{mm-inlined-types} may include regular expressions, for example to -specify that all @samp{text/.*} parts be displayed inline. If a user -prefers to have a type that matches such a regular expression be treated -as an attachment, that can be accomplished by setting this variable to a -list containing that type. For example assuming @code{mm-inlined-types} -includes @samp{text/.*}, then including @samp{text/html} in this -variable will cause @samp{text/html} parts to be treated as attachments. - -@item mm-text-html-renderer -@vindex mm-text-html-renderer -This selects the function used to render @acronym{HTML}. The predefined -renderers are selected by the symbols @code{gnus-article-html}, @code{w3}, -@code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more -information about emacs-w3m}, @code{links}, @code{lynx}, -@code{w3m-standalone} or @code{html2text}. If @code{nil} use an -external viewer. You can also specify a function, which will be -called with a @acronym{MIME} handle as the argument. - -@item mm-inline-text-html-with-images -@vindex mm-inline-text-html-with-images -Some @acronym{HTML} mails might have the trick of spammers using -@samp{} tags. It is likely to be intended to verify whether you -have read the mail. You can prevent your personal information from -leaking by setting this option to @code{nil} (which is the default). -It is currently ignored by Emacs/w3. For emacs-w3m, you may use the -command @kbd{t} on the image anchor to show an image even if it is -@code{nil}.@footnote{The command @kbd{T} will load all images. If you -have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i} -or @kbd{I} instead.} - -@item mm-w3m-safe-url-regexp -@vindex mm-w3m-safe-url-regexp -A regular expression that matches safe URL names, i.e. URLs that are -unlikely to leak personal information when rendering @acronym{HTML} -email (the default value is @samp{\\`cid:}). If @code{nil} consider -all URLs safe. In Gnus, this will be overridden according to the value -of the variable @code{gnus-safe-html-newsgroups}, @xref{Various -Various, ,Various Various, gnus, Gnus Manual}. - -@item mm-inline-text-html-with-w3m-keymap -@vindex mm-inline-text-html-with-w3m-keymap -You can use emacs-w3m command keys in the inlined text/html part by -setting this option to non-@code{nil}. The default value is @code{t}. - -@item mm-external-terminal-program -@vindex mm-external-terminal-program -The program used to start an external terminal. - -@item mm-enable-external -@vindex mm-enable-external -Indicate whether external @acronym{MIME} handlers should be used. - -If @code{t}, all defined external @acronym{MIME} handlers are used. If -@code{nil}, files are saved to disk (@code{mailcap-save-binary-file}). -If it is the symbol @code{ask}, you are prompted before the external -@acronym{MIME} handler is invoked. - -When you launch an attachment through mailcap (@pxref{mailcap}) an -attempt is made to use a safe viewer with the safest options---this isn't -the case if you save it to disk and launch it in a different way -(command line or double-clicking). Anyhow, if you want to be sure not -to launch any external programs, set this variable to @code{nil} or -@code{ask}. - -@end table - -@node Files and Directories -@section Files and Directories - -@table @code - -@item mm-default-directory -@vindex mm-default-directory -The default directory for saving attachments. If @code{nil} use -@code{default-directory}. - -@item mm-tmp-directory -@vindex mm-tmp-directory -Directory for storing temporary files. - -@item mm-file-name-rewrite-functions -@vindex mm-file-name-rewrite-functions -A list of functions used for rewriting file names of @acronym{MIME} -parts. Each function is applied successively to the file name. -Ready-made functions include - -@table @code -@item mm-file-name-delete-control -@findex mm-file-name-delete-control -Delete all control characters. - -@item mm-file-name-delete-gotchas -@findex mm-file-name-delete-gotchas -Delete characters that could have unintended consequences when used -with flawed shell scripts, i.e. @samp{|}, @samp{>} and @samp{<}; and -@samp{-}, @samp{.} as the first character. - -@item mm-file-name-delete-whitespace -@findex mm-file-name-delete-whitespace -Remove all whitespace. - -@item mm-file-name-trim-whitespace -@findex mm-file-name-trim-whitespace -Remove leading and trailing whitespace. - -@item mm-file-name-collapse-whitespace -@findex mm-file-name-collapse-whitespace -Collapse multiple whitespace characters. - -@item mm-file-name-replace-whitespace -@findex mm-file-name-replace-whitespace -@vindex mm-file-name-replace-whitespace -Replace whitespace with underscores. Set the variable -@code{mm-file-name-replace-whitespace} to any other string if you do -not like underscores. -@end table - -The standard Emacs functions @code{capitalize}, @code{downcase}, -@code{upcase} and @code{upcase-initials} might also prove useful. - -@item mm-path-name-rewrite-functions -@vindex mm-path-name-rewrite-functions -List of functions used for rewriting the full file names of @acronym{MIME} -parts. This is used when viewing parts externally, and is meant for -transforming the absolute name so that non-compliant programs can find -the file where it's saved. - -@end table - -@node New Viewers -@section New Viewers - -Here's an example viewer for displaying @code{text/enriched} inline: - -@lisp -(defun mm-display-enriched-inline (handle) - (let (text) - (with-temp-buffer - (mm-insert-part handle) - (save-window-excursion - (enriched-decode (point-min) (point-max)) - (setq text (buffer-string)))) - (mm-insert-inline handle text))) -@end lisp - -We see that the function takes a @acronym{MIME} handle as its parameter. It -then goes to a temporary buffer, inserts the text of the part, does some -work on the text, stores the result, goes back to the buffer it was -called from and inserts the result. - -The two important helper functions here are @code{mm-insert-part} and -@code{mm-insert-inline}. The first function inserts the text of the -handle in the current buffer. It handles charset and/or content -transfer decoding. The second function just inserts whatever text you -tell it to insert, but it also sets things up so that the text can be -``undisplayed'' in a convenient manner. - - -@node Composing -@chapter Composing -@cindex Composing -@cindex MIME Composing -@cindex MML -@cindex MIME Meta Language - -Creating a @acronym{MIME} message is boring and non-trivial. Therefore, -a library called @code{mml} has been defined that parses a language -called @acronym{MML} (@acronym{MIME} Meta Language) and generates -@acronym{MIME} messages. - -@findex mml-generate-mime -The main interface function is @code{mml-generate-mime}. It will -examine the contents of the current (narrowed-to) buffer and return a -string containing the @acronym{MIME} message. - -@menu -* Simple MML Example:: An example @acronym{MML} document. -* MML Definition:: All valid @acronym{MML} elements. -* Advanced MML Example:: Another example @acronym{MML} document. -* Encoding Customization:: Variables that affect encoding. -* Charset Translation:: How charsets are mapped from @sc{mule} to @acronym{MIME}. -* Conversion:: Going from @acronym{MIME} to @acronym{MML} and vice versa. -* Flowed text:: Soft and hard newlines. -@end menu - - -@node Simple MML Example -@section Simple MML Example - -Here's a simple @samp{multipart/alternative}: - -@example -<#multipart type=alternative> -This is a plain text part. -<#part type=text/enriched> -
This is a centered enriched part
-<#/multipart> -@end example - -After running this through @code{mml-generate-mime}, we get this: - -@example -Content-Type: multipart/alternative; boundary="=-=-=" - - ---=-=-= - - -This is a plain text part. - ---=-=-= -Content-Type: text/enriched - - -
This is a centered enriched part
- ---=-=-=-- -@end example - - -@node MML Definition -@section MML Definition - -The @acronym{MML} language is very simple. It looks a bit like an SGML -application, but it's not. - -The main concept of @acronym{MML} is the @dfn{part}. Each part can be of a -different type or use a different charset. The way to delineate a part -is with a @samp{<#part ...>} tag. Multipart parts can be introduced -with the @samp{<#multipart ...>} tag. Parts are ended by the -@samp{<#/part>} or @samp{<#/multipart>} tags. Parts started with the -@samp{<#part ...>} tags are also closed by the next open tag. - -There's also the @samp{<#external ...>} tag. These introduce -@samp{external/message-body} parts. - -Each tag can contain zero or more parameters on the form -@samp{parameter=value}. The values may be enclosed in quotation marks, -but that's not necessary unless the value contains white space. So -@samp{filename=/home/user/#hello$^yes} is perfectly valid. - -The following parameters have meaning in @acronym{MML}; parameters that have no -meaning are ignored. The @acronym{MML} parameter names are the same as the -@acronym{MIME} parameter names; the things in the parentheses say which -header it will be used in. - -@table @samp -@item type -The @acronym{MIME} type of the part (@code{Content-Type}). - -@item filename -Use the contents of the file in the body of the part -(@code{Content-Disposition}). - -@item charset -The contents of the body of the part are to be encoded in the character -set specified (@code{Content-Type}). @xref{Charset Translation}. - -@item name -Might be used to suggest a file name if the part is to be saved -to a file (@code{Content-Type}). - -@item disposition -Valid values are @samp{inline} and @samp{attachment} -(@code{Content-Disposition}). - -@item encoding -Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and -@samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset -Translation}. - -@item description -A description of the part (@code{Content-Description}). - -@item creation-date -RFC822 date when the part was created (@code{Content-Disposition}). - -@item modification-date -RFC822 date when the part was modified (@code{Content-Disposition}). - -@item read-date -RFC822 date when the part was read (@code{Content-Disposition}). - -@item recipients -Who to encrypt/sign the part to. This field is used to override any -auto-detection based on the To/CC headers. - -@item sender -Identity used to sign the part. This field is used to override the -default key used. - -@item size -The size (in octets) of the part (@code{Content-Disposition}). - -@item sign -What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp} -or @code{pgpmime}) - -@item encrypt -What technology to encrypt this @acronym{MML} part with (@code{smime}, -@code{pgp} or @code{pgpmime}) - -@end table - -Parameters for @samp{text/plain}: - -@table @samp -@item format -Formatting parameter for the text, valid values include @samp{fixed} -(the default) and @samp{flowed}. Normally you do not specify this -manually, since it requires the textual body to be formatted in a -special way described in RFC 2646. @xref{Flowed text}. -@end table - -Parameters for @samp{application/octet-stream}: - -@table @samp -@item type -Type of the part; informal---meant for human readers -(@code{Content-Type}). -@end table - -Parameters for @samp{message/external-body}: - -@table @samp -@item access-type -A word indicating the supported access mechanism by which the file may -be obtained. Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp}, -@samp{localfile}, and @samp{mailserver}. (@code{Content-Type}.) - -@item expiration -The RFC822 date after which the file may no longer be fetched. -(@code{Content-Type}.) - -@item size -The size (in octets) of the file. (@code{Content-Type}.) - -@item permission -Valid values are @samp{read} and @samp{read-write} -(@code{Content-Type}). - -@end table - -Parameters for @samp{sign=smime}: - -@table @samp - -@item keyfile -File containing key and certificate for signer. - -@end table - -Parameters for @samp{encrypt=smime}: - -@table @samp - -@item certfile -File containing certificate for recipient. - -@end table - - -@node Advanced MML Example -@section Advanced MML Example - -Here's a complex multipart message. It's a @samp{multipart/mixed} that -contains many parts, one of which is a @samp{multipart/alternative}. - -@example -<#multipart type=mixed> -<#part type=image/jpeg filename=~/rms.jpg disposition=inline> -<#multipart type=alternative> -This is a plain text part. -<#part type=text/enriched name=enriched.txt> -
This is a centered enriched part
-<#/multipart> -This is a new plain text part. -<#part disposition=attachment> -This plain text part is an attachment. -<#/multipart> -@end example - -And this is the resulting @acronym{MIME} message: - -@example -Content-Type: multipart/mixed; boundary="=-=-=" - - ---=-=-= - - - ---=-=-= -Content-Type: image/jpeg; - filename="~/rms.jpg" -Content-Disposition: inline; - filename="~/rms.jpg" -Content-Transfer-Encoding: base64 - -/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof -Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA -AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR -BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF -RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip -qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB -AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI -AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E -sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m -2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw -5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc -L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw -34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm -tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn -7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC -pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm -jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q== - ---=-=-= -Content-Type: multipart/alternative; boundary="==-=-=" - - ---==-=-= - - -This is a plain text part. - ---==-=-= -Content-Type: text/enriched; - name="enriched.txt" - - -
This is a centered enriched part
- ---==-=-=-- - ---=-=-= - -This is a new plain text part. - ---=-=-= -Content-Disposition: attachment - - -This plain text part is an attachment. - ---=-=-=-- -@end example - -@node Encoding Customization -@section Encoding Customization - -@table @code - -@item mm-body-charset-encoding-alist -@vindex mm-body-charset-encoding-alist -Mapping from @acronym{MIME} charset to encoding to use. This variable is -usually used except, e.g., when other requirements force a specific -encoding (digitally signed messages require 7bit encodings). The -default is - -@lisp -((iso-2022-jp . 7bit) - (iso-2022-jp-2 . 7bit) - (utf-16 . base64) - (utf-16be . base64) - (utf-16le . base64)) -@end lisp - -As an example, if you do not want to have ISO-8859-1 characters -quoted-printable encoded, you may add @code{(iso-8859-1 . 8bit)} to -this variable. You can override this setting on a per-message basis -by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}). - -@item mm-coding-system-priorities -@vindex mm-coding-system-priorities -Prioritize coding systems to use for outgoing messages. The default -is @code{nil}, which means to use the defaults in Emacs, but is -@code{(iso-8859-1 iso-2022-jp iso-2022-jp-2 shift_jis utf-8)} when -running Emacs in the Japanese language environment. It is a list of -coding system symbols (aliases of coding systems are also allowed, use -@kbd{M-x describe-coding-system} to make sure you are specifying correct -coding system names). For example, if you have configured Emacs -to prefer UTF-8, but wish that outgoing messages should be sent in -ISO-8859-1 if possible, you can set this variable to -@code{(iso-8859-1)}. You can override this setting on a per-message -basis by using the @code{charset} @acronym{MML} tag (@pxref{MML Definition}). - -As different hierarchies prefer different charsets, you may want to set -@code{mm-coding-system-priorities} according to the hierarchy in Gnus. -Here's an example: - -@c Corrections about preferred charsets are welcome. de, fr and fj -@c should be correct, I don't know about the rest (so these are only -@c examples): -@lisp -(add-to-list 'gnus-newsgroup-variables 'mm-coding-system-priorities) -(setq gnus-parameters - (nconc - ;; Some charsets are just examples! - '(("^cn\\." ;; Chinese - (mm-coding-system-priorities - '(iso-8859-1 cn-big5 chinese-iso-7bit utf-8))) - ("^cz\\.\\|^pl\\." ;; Central and Eastern European - (mm-coding-system-priorities '(iso-8859-2 utf-8))) - ("^de\\." ;; German language - (mm-coding-system-priorities '(iso-8859-1 iso-8859-15 utf-8))) - ("^fr\\." ;; French - (mm-coding-system-priorities '(iso-8859-15 iso-8859-1 utf-8))) - ("^fj\\." ;; Japanese - (mm-coding-system-priorities - '(iso-8859-1 iso-2022-jp iso-2022-jp-2 shift_jis utf-8))) - ("^ru\\." ;; Cyrillic - (mm-coding-system-priorities - '(koi8-r iso-8859-5 iso-8859-1 utf-8)))) - gnus-parameters)) -@end lisp - -@item mm-content-transfer-encoding-defaults -@vindex mm-content-transfer-encoding-defaults -Mapping from @acronym{MIME} types to encoding to use. This variable is usually -used except, e.g., when other requirements force a safer encoding -(digitally signed messages require 7bit encoding). Besides the normal -@acronym{MIME} encodings, @code{qp-or-base64} may be used to indicate that for -each case the most efficient of quoted-printable and base64 should be -used. - -@code{qp-or-base64} has another effect. It will fold long lines so that -MIME parts may not be broken by MTA. So do @code{quoted-printable} and -@code{base64}. - -Note that it affects body encoding only when a part is a raw forwarded -message (which will be made by @code{gnus-summary-mail-forward} with the -arg 2 for example) or is neither the @samp{text/*} type nor the -@samp{message/*} type. Even though in those cases, you can override -this setting on a per-message basis by using the @code{encoding} -@acronym{MML} tag (@pxref{MML Definition}). - -@item mm-use-ultra-safe-encoding -@vindex mm-use-ultra-safe-encoding -When this is non-@code{nil}, it means that textual parts are encoded as -quoted-printable if they contain lines longer than 76 characters or -starting with "From " in the body. Non-7bit encodings (8bit, binary) -are generally disallowed. This reduce the probability that a non-8bit -clean MTA or MDA changes the message. This should never be set -directly, but bound by other functions when necessary (e.g., when -encoding messages that are to be digitally signed). - -@end table - -@node Charset Translation -@section Charset Translation -@cindex charsets - -During translation from @acronym{MML} to @acronym{MIME}, for each -@acronym{MIME} part which has been composed inside Emacs, an appropriate -charset has to be chosen. - -@vindex mail-parse-charset -If you are running a non-@sc{mule} Emacs, this process is simple: If the -part contains any non-@acronym{ASCII} (8-bit) characters, the @acronym{MIME} charset -given by @code{mail-parse-charset} (a symbol) is used. (Never set this -variable directly, though. If you want to change the default charset, -please consult the documentation of the package which you use to process -@acronym{MIME} messages. -@xref{Various Message Variables, , Various Message Variables, message, - Message Manual}, for example.) -If there are only @acronym{ASCII} characters, the @acronym{MIME} charset US-ASCII is -used, of course. - -@cindex MULE -@cindex UTF-8 -@cindex Unicode -@vindex mm-mime-mule-charset-alist -Things are slightly more complicated when running Emacs with @sc{mule} -support. In this case, a list of the @sc{mule} charsets used in the -part is obtained, and the @sc{mule} charsets are translated to -@acronym{MIME} charsets by consulting the table provided by Emacs itself -or the variable @code{mm-mime-mule-charset-alist} for XEmacs. -If this results in a single @acronym{MIME} charset, this is used to encode -the part. But if the resulting list of @acronym{MIME} charsets contains more -than one element, two things can happen: If it is possible to encode the -part via UTF-8, this charset is used. (For this, Emacs must support -the @code{utf-8} coding system, and the part must consist entirely of -characters which have Unicode counterparts.) If UTF-8 is not available -for some reason, the part is split into several ones, so that each one -can be encoded with a single @acronym{MIME} charset. The part can only be -split at line boundaries, though---if more than one @acronym{MIME} charset is -required to encode a single line, it is not possible to encode the part. - -When running Emacs with @sc{mule} support, the preferences for which -coding system to use is inherited from Emacs itself. This means that -if Emacs is set up to prefer UTF-8, it will be used when encoding -messages. You can modify this by altering the -@code{mm-coding-system-priorities} variable though (@pxref{Encoding -Customization}). - -The charset to be used can be overridden by setting the @code{charset} -@acronym{MML} tag (@pxref{MML Definition}) when composing the message. - -The encoding of characters (quoted-printable, 8bit etc) is orthogonal -to the discussion here, and is controlled by the variables -@code{mm-body-charset-encoding-alist} and -@code{mm-content-transfer-encoding-defaults} (@pxref{Encoding -Customization}). - -@node Conversion -@section Conversion - -@findex mime-to-mml -A (multipart) @acronym{MIME} message can be converted to @acronym{MML} -with the @code{mime-to-mml} function. It works on the message in the -current buffer, and substitutes @acronym{MML} markup for @acronym{MIME} -boundaries. Non-textual parts do not have their contents in the buffer, -but instead have the contents in separate buffers that are referred to -from the @acronym{MML} tags. - -@findex mml-to-mime -An @acronym{MML} message can be converted back to @acronym{MIME} by the -@code{mml-to-mime} function. - -These functions are in certain senses ``lossy''---you will not get back -an identical message if you run @code{mime-to-mml} and then -@code{mml-to-mime}. Not only will trivial things like the order of the -headers differ, but the contents of the headers may also be different. -For instance, the original message may use base64 encoding on text, -while @code{mml-to-mime} may decide to use quoted-printable encoding, and -so on. - -In essence, however, these two functions should be the inverse of each -other. The resulting contents of the message should remain equivalent, -if not identical. - - -@node Flowed text -@section Flowed text -@cindex format=flowed - -The Emacs @acronym{MIME} library will respect the @code{use-hard-newlines} -variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines, -emacs, Emacs Manual}) when encoding a message, and the -``format=flowed'' Content-Type parameter when decoding a message. - -On encoding text, regardless of @code{use-hard-newlines}, lines -terminated by soft newline characters are filled together and wrapped -after the column decided by @code{fill-flowed-encode-column}. -Quotation marks (matching @samp{^>* ?}) are respected. The variable -controls how the text will look in a client that does not support -flowed text, the default is to wrap after 66 characters. If hard -newline characters are not present in the buffer, no flow encoding -occurs. - -You can customize the value of the @code{mml-enable-flowed} variable -to enable or disable the flowed encoding usage when newline -characters are present in the buffer. - -On decoding flowed text, lines with soft newline characters are filled -together and wrapped after the column decided by -@code{fill-flowed-display-column}. The default is to wrap after -@code{fill-column}. - -@table @code -@item mm-fill-flowed -@vindex mm-fill-flowed -If non-@code{nil} a format=flowed article will be displayed flowed. -@end table - - -@node Interface Functions -@chapter Interface Functions -@cindex interface functions -@cindex mail-parse - -The @code{mail-parse} library is an abstraction over the actual -low-level libraries that are described in the next chapter. - -Standards change, and so programs have to change to fit in the new -mold. For instance, RFC2045 describes a syntax for the -@code{Content-Type} header that only allows @acronym{ASCII} characters in the -parameter list. RFC2231 expands on RFC2045 syntax to provide a scheme -for continuation headers and non-@acronym{ASCII} characters. - -The traditional way to deal with this is just to update the library -functions to parse the new syntax. However, this is sometimes the wrong -thing to do. In some instances it may be vital to be able to understand -both the old syntax as well as the new syntax, and if there is only one -library, one must choose between the old version of the library and the -new version of the library. - -The Emacs @acronym{MIME} library takes a different tack. It defines a -series of low-level libraries (@file{rfc2047.el}, @file{rfc2231.el} -and so on) that parses strictly according to the corresponding -standard. However, normal programs would not use the functions -provided by these libraries directly, but instead use the functions -provided by the @code{mail-parse} library. The functions in this -library are just aliases to the corresponding functions in the latest -low-level libraries. Using this scheme, programs get a consistent -interface they can use, and library developers are free to create -write code that handles new standards. - -The following functions are defined by this library: - -@table @code -@item mail-header-parse-content-type -@findex mail-header-parse-content-type -Parse a @code{Content-Type} header and return a list on the following -format: - -@lisp -("type/subtype" - (attribute1 . value1) - (attribute2 . value2) - ...) -@end lisp - -Here's an example: - -@example -(mail-header-parse-content-type - "image/gif; name=\"b980912.gif\"") -@result{} ("image/gif" (name . "b980912.gif")) -@end example - -@item mail-header-parse-content-disposition -@findex mail-header-parse-content-disposition -Parse a @code{Content-Disposition} header and return a list on the same -format as the function above. - -@item mail-content-type-get -@findex mail-content-type-get -Takes two parameters---a list on the format above, and an attribute. -Returns the value of the attribute. - -@example -(mail-content-type-get - '("image/gif" (name . "b980912.gif")) 'name) -@result{} "b980912.gif" -@end example - -@item mail-header-encode-parameter -@findex mail-header-encode-parameter -Takes a parameter string and returns an encoded version of the string. -This is used for parameters in headers like @code{Content-Type} and -@code{Content-Disposition}. - -@item mail-header-remove-comments -@findex mail-header-remove-comments -Return a comment-free version of a header. - -@example -(mail-header-remove-comments - "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)") -@result{} "Gnus/5.070027 " -@end example - -@item mail-header-remove-whitespace -@findex mail-header-remove-whitespace -Remove linear white space from a header. Space inside quoted strings -and comments is preserved. - -@example -(mail-header-remove-whitespace - "image/gif; name=\"Name with spaces\"") -@result{} "image/gif;name=\"Name with spaces\"" -@end example - -@item mail-header-get-comment -@findex mail-header-get-comment -Return the last comment in a header. - -@example -(mail-header-get-comment - "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)") -@result{} "Finnish Landrace" -@end example - -@item mail-header-parse-address -@findex mail-header-parse-address -Parse an address and return a list containing the mailbox and the -plaintext name. - -@example -(mail-header-parse-address - "Hrvoje Niksic ") -@result{} ("hniksic@@srce.hr" . "Hrvoje Niksic") -@end example - -@item mail-header-parse-addresses -@findex mail-header-parse-addresses -Parse a string with list of addresses and return a list of elements like -the one described above. - -@example -(mail-header-parse-addresses - "Hrvoje Niksic , Steinar Bang ") -@result{} (("hniksic@@srce.hr" . "Hrvoje Niksic") - ("sb@@metis.no" . "Steinar Bang")) -@end example - -@item mail-header-parse-date -@findex mail-header-parse-date -Parse a date string and return an Emacs time structure. - -@item mail-narrow-to-head -@findex mail-narrow-to-head -Narrow the buffer to the header section of the buffer. Point is placed -at the beginning of the narrowed buffer. - -@item mail-header-narrow-to-field -@findex mail-header-narrow-to-field -Narrow the buffer to the header under point. Understands continuation -headers. - -@item mail-header-fold-field -@findex mail-header-fold-field -Fold the header under point. - -@item mail-header-unfold-field -@findex mail-header-unfold-field -Unfold the header under point. - -@item mail-header-field-value -@findex mail-header-field-value -Return the value of the field under point. - -@item mail-encode-encoded-word-region -@findex mail-encode-encoded-word-region -Encode the non-@acronym{ASCII} words in the region. For instance, -@samp{Na@"{@dotless{i}}ve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}. - -@item mail-encode-encoded-word-buffer -@findex mail-encode-encoded-word-buffer -Encode the non-@acronym{ASCII} words in the current buffer. This function is -meant to be called narrowed to the headers of a message. - -@item mail-encode-encoded-word-string -@findex mail-encode-encoded-word-string -Encode the words that need encoding in a string, and return the result. - -@example -(mail-encode-encoded-word-string - "This is na@"{@dotless{i}}ve, baby") -@result{} "This is =?iso-8859-1?q?na=EFve,?= baby" -@end example - -@item mail-decode-encoded-word-region -@findex mail-decode-encoded-word-region -Decode the encoded words in the region. - -@item mail-decode-encoded-word-string -@findex mail-decode-encoded-word-string -Decode the encoded words in the string and return the result. - -@example -(mail-decode-encoded-word-string - "This is =?iso-8859-1?q?na=EFve,?= baby") -@result{} "This is na@"{@dotless{i}}ve, baby" -@end example - -@end table - -Currently, @code{mail-parse} is an abstraction over @code{ietf-drums}, -@code{rfc2047}, @code{rfc2045} and @code{rfc2231}. These are documented -in the subsequent sections. - - - -@node Basic Functions -@chapter Basic Functions - -This chapter describes the basic, ground-level functions for parsing and -handling. Covered here is parsing @code{From} lines, removing comments -from header lines, decoding encoded words, parsing date headers and so -on. High-level functionality is dealt with in the first chapter -(@pxref{Decoding and Viewing}). - -@menu -* rfc2045:: Encoding @code{Content-Type} headers. -* rfc2231:: Parsing @code{Content-Type} headers. -* ietf-drums:: Handling mail headers defined by RFC822bis. -* rfc2047:: En/decoding encoded words in headers. -* time-date:: Functions for parsing dates and manipulating time. -* qp:: Quoted-Printable en/decoding. -* base64:: Base64 en/decoding. -* binhex:: Binhex decoding. -* uudecode:: Uuencode decoding. -* yenc:: Yenc decoding. -* rfc1843:: Decoding HZ-encoded text. -* mailcap:: How parts are displayed is specified by the @file{.mailcap} file -@end menu - - -@node rfc2045 -@section rfc2045 - -RFC2045 is the ``main'' @acronym{MIME} document, and as such, one would -imagine that there would be a lot to implement. But there isn't, since -most of the implementation details are delegated to the subsequent -RFCs. - -So @file{rfc2045.el} has only a single function: - -@table @code -@item rfc2045-encode-string -@findex rfc2045-encode-string -Takes a parameter and a value and returns a @samp{PARAM=VALUE} string. -@var{value} will be quoted if there are non-safe characters in it. -@end table - - -@node rfc2231 -@section rfc2231 - -RFC2231 defines a syntax for the @code{Content-Type} and -@code{Content-Disposition} headers. Its snappy name is @dfn{MIME -Parameter Value and Encoded Word Extensions: Character Sets, Languages, -and Continuations}. - -In short, these headers look something like this: - -@example -Content-Type: application/x-stuff; - title*0*=us-ascii'en'This%20is%20even%20more%20; - title*1*=%2A%2A%2Afun%2A%2A%2A%20; - title*2="isn't it!" -@end example - -They usually aren't this bad, though. - -The following functions are defined by this library: - -@table @code -@item rfc2231-parse-string -@findex rfc2231-parse-string -Parse a @code{Content-Type} header and return a list describing its -elements. - -@example -(rfc2231-parse-string - "application/x-stuff; - title*0*=us-ascii'en'This%20is%20even%20more%20; - title*1*=%2A%2A%2Afun%2A%2A%2A%20; - title*2=\"isn't it!\"") -@result{} ("application/x-stuff" - (title . "This is even more ***fun*** isn't it!")) -@end example - -@item rfc2231-get-value -@findex rfc2231-get-value -Takes one of the lists on the format above and returns -the value of the specified attribute. - -@item rfc2231-encode-string -@findex rfc2231-encode-string -Encode a parameter in headers likes @code{Content-Type} and -@code{Content-Disposition}. - -@end table - - -@node ietf-drums -@section ietf-drums - -@dfn{drums} is an IETF working group that is working on the replacement -for RFC822. - -The functions provided by this library include: - -@table @code -@item ietf-drums-remove-comments -@findex ietf-drums-remove-comments -Remove the comments from the argument and return the results. - -@item ietf-drums-remove-whitespace -@findex ietf-drums-remove-whitespace -Remove linear white space from the string and return the results. -Spaces inside quoted strings and comments are left untouched. - -@item ietf-drums-get-comment -@findex ietf-drums-get-comment -Return the last most comment from the string. - -@item ietf-drums-parse-address -@findex ietf-drums-parse-address -Parse an address string and return a list that contains the mailbox and -the plain text name. - -@item ietf-drums-parse-addresses -@findex ietf-drums-parse-addresses -Parse a string that contains any number of comma-separated addresses and -return a list that contains mailbox/plain text pairs. - -@item ietf-drums-parse-date -@findex ietf-drums-parse-date -Parse a date string and return an Emacs time structure. - -@item ietf-drums-narrow-to-header -@findex ietf-drums-narrow-to-header -Narrow the buffer to the header section of the current buffer. - -@end table - - -@node rfc2047 -@section rfc2047 - -RFC2047 (Message Header Extensions for Non-@acronym{ASCII} Text) specifies how -non-@acronym{ASCII} text in headers are to be encoded. This is actually rather -complicated, so a number of variables are necessary to tweak what this -library does. - -The following variables are tweakable: - -@table @code -@item rfc2047-header-encoding-alist -@vindex rfc2047-header-encoding-alist -This is an alist of header / encoding-type pairs. Its main purpose is -to prevent encoding of certain headers. - -The keys can either be header regexps, or @code{t}. - -The values can be @code{nil}, in which case the header(s) in question -won't be encoded, @code{mime}, which means that they will be encoded, or -@code{address-mime}, which means the header(s) will be encoded carefully -assuming they contain addresses. - -@item rfc2047-charset-encoding-alist -@vindex rfc2047-charset-encoding-alist -RFC2047 specifies two forms of encoding---@code{Q} (a -Quoted-Printable-like encoding) and @code{B} (base64). This alist -specifies which charset should use which encoding. - -@item rfc2047-encode-function-alist -@vindex rfc2047-encode-function-alist -This is an alist of encoding / function pairs. The encodings are -@code{Q}, @code{B} and @code{nil}. - -@item rfc2047-encoded-word-regexp -@vindex rfc2047-encoded-word-regexp -When decoding words, this library looks for matches to this regexp. - -@item rfc2047-encoded-word-regexp-loose -@vindex rfc2047-encoded-word-regexp-loose -This is a version from which the regexp for the Q encoding pattern of -@code{rfc2047-encoded-word-regexp} is made loose. - -@item rfc2047-encode-encoded-words -@vindex rfc2047-encode-encoded-words -The boolean variable specifies whether encoded words -(e.g. @samp{=?us-ascii?q?hello?=}) should be encoded again. -@code{rfc2047-encoded-word-regexp} is used to look for such words. - -@item rfc2047-allow-irregular-q-encoded-words -@vindex rfc2047-allow-irregular-q-encoded-words -The boolean variable specifies whether irregular Q encoded words -(e.g. @samp{=?us-ascii?q?hello??=}) should be decoded. If it is -non-@code{nil}, @code{rfc2047-encoded-word-regexp-loose} is used instead -of @code{rfc2047-encoded-word-regexp} to look for encoded words. - -@end table - -Those were the variables, and these are this functions: - -@table @code -@item rfc2047-narrow-to-field -@findex rfc2047-narrow-to-field -Narrow the buffer to the header on the current line. - -@item rfc2047-encode-message-header -@findex rfc2047-encode-message-header -Should be called narrowed to the header of a message. Encodes according -to @code{rfc2047-header-encoding-alist}. - -@item rfc2047-encode-region -@findex rfc2047-encode-region -Encodes all encodable words in the region specified. - -@item rfc2047-encode-string -@findex rfc2047-encode-string -Encode a string and return the results. - -@item rfc2047-decode-region -@findex rfc2047-decode-region -Decode the encoded words in the region. - -@item rfc2047-decode-string -@findex rfc2047-decode-string -Decode a string and return the results. - -@item rfc2047-encode-parameter -@findex rfc2047-encode-parameter -Encode a parameter in the RFC2047-like style. This is a substitution -for the @code{rfc2231-encode-string} function, that is the standard but -many mailers don't support it. @xref{rfc2231}. - -@end table - - -@node time-date -@section time-date - -While not really a part of the @acronym{MIME} library, it is convenient to -document this library here. It deals with parsing @code{Date} headers -and manipulating time. (Not by using tesseracts, though, I'm sorry to -say.) - -These functions convert between five formats: A date string, an Emacs -time structure, a decoded time list, a second number, and a day number. - -Here's a bunch of time/date/second/day examples: - -@example -(parse-time-string "Sat Sep 12 12:21:54 1998 +0200") -@result{} (54 21 12 12 9 1998 6 nil 7200) - -(date-to-time "Sat Sep 12 12:21:54 1998 +0200") -@result{} (13818 19266) - -(time-to-seconds '(13818 19266)) -@result{} 905595714.0 - -(seconds-to-time 905595714.0) -@result{} (13818 19266 0) - -(time-to-days '(13818 19266)) -@result{} 729644 - -(days-to-time 729644) -@result{} (961933 65536) - -(time-since '(13818 19266)) -@result{} (0 430) - -(time-less-p '(13818 19266) '(13818 19145)) -@result{} nil - -(subtract-time '(13818 19266) '(13818 19145)) -@result{} (0 121) - -(days-between "Sat Sep 12 12:21:54 1998 +0200" - "Sat Sep 07 12:21:54 1998 +0200") -@result{} 5 - -(date-leap-year-p 2000) -@result{} t - -(time-to-day-in-year '(13818 19266)) -@result{} 255 - -(time-to-number-of-days - (time-since - (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT"))) -@result{} 4.146122685185185 -@end example - -And finally, we have @code{safe-date-to-time}, which does the same as -@code{date-to-time}, but returns a zero time if the date is -syntactically malformed. - -The five data representations used are the following: - -@table @var -@item date -An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12 -12:21:54 1998 +0200"}. - -@item time -An internal Emacs time. For instance: @code{(13818 26466)}. - -@item seconds -A floating point representation of the internal Emacs time. For -instance: @code{905595714.0}. - -@item days -An integer number representing the number of days since 00000101. For -instance: @code{729644}. - -@item decoded time -A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t -7200)}. -@end table - -All the examples above represent the same moment. - -These are the functions available: - -@table @code -@item date-to-time -Take a date and return a time. - -@item time-to-seconds -Take a time and return seconds. Note that Emacs has a built-in -function, @code{float-time}, that does this. - -@item seconds-to-time -Take seconds and return a time. - -@item time-to-days -Take a time and return days. - -@item days-to-time -Take days and return a time. - -@item date-to-day -Take a date and return days. - -@item time-to-number-of-days -Take a time and return the number of days that represents. - -@item safe-date-to-time -Take a date and return a time. If the date is not syntactically valid, -return a ``zero'' time. - -@item time-less-p -Take two times and say whether the first time is less (i. e., earlier) -than the second time. - -@item time-since -Take a time and return a time saying how long it was since that time. - -@item subtract-time -Take two times and subtract the second from the first. I. e., return -the time between the two times. - -@item days-between -Take two days and return the number of days between those two days. - -@item date-leap-year-p -Take a year number and say whether it's a leap year. - -@item time-to-day-in-year -Take a time and return the day number within the year that the time is -in. - -@end table - - -@node qp -@section qp - -This library deals with decoding and encoding Quoted-Printable text. - -Very briefly explained, qp encoding means translating all 8-bit -characters (and lots of control characters) into things that look like -@samp{=EF}; that is, an equal sign followed by the byte encoded as a hex -string. - -The following functions are defined by the library: - -@table @code -@item quoted-printable-decode-region -@findex quoted-printable-decode-region -QP-decode all the encoded text in the specified region. - -@item quoted-printable-decode-string -@findex quoted-printable-decode-string -Decode the QP-encoded text in a string and return the results. - -@item quoted-printable-encode-region -@findex quoted-printable-encode-region -QP-encode all the encodable characters in the specified region. The third -optional parameter @var{fold} specifies whether to fold long lines. -(Long here means 72.) - -@item quoted-printable-encode-string -@findex quoted-printable-encode-string -QP-encode all the encodable characters in a string and return the -results. - -@end table - - -@node base64 -@section base64 -@cindex base64 - -Base64 is an encoding that encodes three bytes into four characters, -thereby increasing the size by about 33%. The alphabet used for -encoding is very resistant to mangling during transit. - -The following functions are defined by this library: - -@table @code -@item base64-encode-region -@findex base64-encode-region -base64 encode the selected region. Return the length of the encoded -text. Optional third argument @var{no-line-break} means do not break -long lines into shorter lines. - -@item base64-encode-string -@findex base64-encode-string -base64 encode a string and return the result. - -@item base64-decode-region -@findex base64-decode-region -base64 decode the selected region. Return the length of the decoded -text. If the region can't be decoded, return @code{nil} and don't -modify the buffer. - -@item base64-decode-string -@findex base64-decode-string -base64 decode a string and return the result. If the string can't be -decoded, @code{nil} is returned. - -@end table - - -@node binhex -@section binhex -@cindex binhex -@cindex Apple -@cindex Macintosh - -@code{binhex} is an encoding that originated in Macintosh environments. -The following function is supplied to deal with these: - -@table @code -@item binhex-decode-region -@findex binhex-decode-region -Decode the encoded text in the region. If given a third parameter, only -decode the @code{binhex} header and return the filename. - -@end table - -@node uudecode -@section uudecode -@cindex uuencode -@cindex uudecode - -@code{uuencode} is probably still the most popular encoding of binaries -used on Usenet, although @code{base64} rules the mail world. - -The following function is supplied by this package: - -@table @code -@item uudecode-decode-region -@findex uudecode-decode-region -Decode the text in the region. -@end table - - -@node yenc -@section yenc -@cindex yenc - -@code{yenc} is used for encoding binaries on Usenet. The following -function is supplied by this package: - -@table @code -@item yenc-decode-region -@findex yenc-decode-region -Decode the encoded text in the region. - -@end table - - -@node rfc1843 -@section rfc1843 -@cindex rfc1843 -@cindex HZ -@cindex Chinese - -RFC1843 deals with mixing Chinese and @acronym{ASCII} characters in messages. In -essence, RFC1843 switches between @acronym{ASCII} and Chinese by doing this: - -@example -This sentence is in @acronym{ASCII}. -The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye. -@end example - -Simple enough, and widely used in China. - -The following functions are available to handle this encoding: - -@table @code -@item rfc1843-decode-region -Decode HZ-encoded text in the region. - -@item rfc1843-decode-string -Decode a HZ-encoded string and return the result. - -@end table - - -@node mailcap -@section mailcap - -The @file{~/.mailcap} file is parsed by most @acronym{MIME}-aware message -handlers and describes how elements are supposed to be displayed. -Here's an example file: - -@example -image/*; gimp -8 %s -audio/wav; wavplayer %s -application/msword; catdoc %s ; copiousoutput ; nametemplate=%s.doc -@end example - -This says that all image files should be displayed with @code{gimp}, -that WAVE audio files should be played by @code{wavplayer}, and that -MS-WORD files should be inlined by @code{catdoc}. - -The @code{mailcap} library parses this file, and provides functions for -matching types. - -@table @code -@item mailcap-mime-data -@vindex mailcap-mime-data -This variable is an alist of alists containing backup viewing rules. - -@end table - -Interface functions: - -@table @code -@item mailcap-parse-mailcaps -@findex mailcap-parse-mailcaps -Parse the @file{~/.mailcap} file. - -@item mailcap-mime-info -Takes a @acronym{MIME} type as its argument and returns the matching viewer. - -@end table - - - - -@node Standards -@chapter Standards - -The Emacs @acronym{MIME} library implements handling of various elements -according to a (somewhat) large number of RFCs, drafts and standards -documents. This chapter lists the relevant ones. They can all be -fetched from @uref{http://quimby.gnus.org/notes/}. - -@table @dfn -@item RFC822 -@itemx STD11 -Standard for the Format of ARPA Internet Text Messages. - -@item RFC1036 -Standard for Interchange of USENET Messages - -@item RFC2045 -Format of Internet Message Bodies - -@item RFC2046 -Media Types - -@item RFC2047 -Message Header Extensions for Non-@acronym{ASCII} Text - -@item RFC2048 -Registration Procedures - -@item RFC2049 -Conformance Criteria and Examples - -@item RFC2231 -@acronym{MIME} Parameter Value and Encoded Word Extensions: Character Sets, -Languages, and Continuations - -@item RFC1843 -HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and -@acronym{ASCII} characters - -@item draft-ietf-drums-msg-fmt-05.txt -Draft for the successor of RFC822 - -@item RFC2112 -The @acronym{MIME} Multipart/Related Content-type - -@item RFC1892 -The Multipart/Report Content Type for the Reporting of Mail System -Administrative Messages - -@item RFC2183 -Communicating Presentation Information in Internet Messages: The -Content-Disposition Header Field - -@item RFC2646 -Documentation of the text/plain format parameter for flowed text. - -@end table - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include doclicense.texi - -@node Index -@chapter Index -@printindex cp - -@bye - - -@c Local Variables: -@c mode: texinfo -@c coding: iso-8859-1 -@c End: diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi deleted file mode 100644 index bb5e18f1c8b..00000000000 --- a/doc/misc/epa.texi +++ /dev/null @@ -1,498 +0,0 @@ -\input texinfo @c -*- mode: texinfo -*- -@c %**start of header -@setfilename ../../info/epa -@settitle EasyPG Assistant User's Manual -@c %**end of header - -@set VERSION 1.0.0 - -@copying -This file describes EasyPG Assistant @value{VERSION}. - -Copyright @copyright{} 2007-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License'' -in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* EasyPG Assistant: (epa). An Emacs user interface to GNU Privacy Guard. -@end direntry - -@titlepage -@title EasyPG Assistant - -@author by Daiki Ueno -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top EasyPG Assistant user's manual - -EasyPG Assistant is an Emacs user interface to GNU Privacy Guard -(GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}). - -EasyPG Assistant is a part of the package called EasyPG, an all-in-one -GnuPG interface for Emacs. EasyPG also contains the library interface -called EasyPG Library. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: -* Quick start:: -* Commands:: -* Caching Passphrases:: -* Bug Reports:: -@end menu - -@node Overview -@chapter Overview - -EasyPG Assistant provides the following features. - -@itemize @bullet -@item Key management. -@item Cryptographic operations on regions. -@item Cryptographic operations on files. -@item Dired integration. -@item Mail-mode integration. -@item Automatic encryption/decryption of *.gpg files. -@end itemize - -@node Quick start -@chapter Quick start - -EasyPG Assistant commands are prefixed by @samp{epa-}. For example, - -@itemize @bullet -@item To browse your keyring, type @kbd{M-x epa-list-keys} - -@item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region} - -@item To encrypt a file, type @kbd{M-x epa-encrypt-file} -@end itemize - -EasyPG Assistant provides several cryptographic features which can be -integrated into other Emacs functionalities. For example, automatic -encryption/decryption of @samp{*.gpg} files. - -@node Commands -@chapter Commands - -This chapter introduces various commands for typical use cases. - -@menu -* Key management:: -* Cryptographic operations on regions:: -* Cryptographic operations on files:: -* Dired integration:: -* Mail-mode integration:: -* Encrypting/decrypting *.gpg files:: -@end menu - -@node Key management -@section Key management -Probably the first step of using EasyPG Assistant is to browse your -keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg ---list-keys} from the command line. - -@deffn Command epa-list-keys name mode -Show all keys matched with @var{name} from the public keyring. -@end deffn - -@noindent -The output looks as follows. - -@example - u A5B6B2D4B15813FE Daiki Ueno -@end example - -@noindent -A character on the leftmost column indicates the trust level of the -key. If it is @samp{u}, the key is marked as ultimately trusted. The -second column is the key ID, and the rest is the user ID. - -You can move over entries by @key{TAB}. If you type @key{RET} or -click button1 on an entry, you will see more detailed information -about the key you selected. - -@example - u Daiki Ueno - u A5B6B2D4B15813FE 1024bits DSA - Created: 2001-10-09 - Expires: 2007-09-04 - Capabilities: sign certify - Fingerprint: 8003 7CD0 0F1A 9400 03CA 50AA A5B6 B2D4 B158 13FE - u 4447461B2A9BEA2D 2048bits ELGAMAL_E - Created: 2001-10-09 - Expires: 2007-09-04 - Capabilities: encrypt - Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D -@end example - -@noindent -To browse your private keyring, use @kbd{M-x epa-list-secret-keys}. - -@deffn Command epa-list-secret-keys name -Show all keys matched with @var{name} from the private keyring. -@end deffn - -@noindent -In @samp{*Keys*} buffer, several commands are available. The common -use case is to export some keys to a file. To do that, type @kbd{m} -to select keys, type @kbd{o}, and then supply the filename. - -Below are other commands related to key management. Some of them take -a file as input/output, and others take the current region. - -@deffn Command epa-insert-keys keys -Insert selected @var{keys} after the point. It will let you select -keys before insertion. By default, it will encode keys in the OpenPGP -armor format. -@end deffn - -@deffn Command epa-import-keys file -Import keys from @var{file} to your keyring. -@end deffn - -@deffn Command epa-import-keys-region start end -Import keys from the current region between @var{start} and @var{end} -to your keyring. -@end deffn - -@deffn Command epa-import-armor-in-region start end -Import keys in the OpenPGP armor format in the current region between -@var{start} and @var{end}. The difference from -@code{epa-import-keys-region} is that -@code{epa-import-armor-in-region} searches armors in the region and -applies @code{epa-import-keys-region} to each of them. -@end deffn - -@deffn Command epa-delete-keys allow-secret -Delete selected keys. If @var{allow-secret} is non-@code{nil}, it -also delete the secret keys. -@end deffn - -@node Cryptographic operations on regions -@section Cryptographic operations on regions - -@deffn Command epa-decrypt-region start end -Decrypt the current region between @var{start} and @var{end}. It -replaces the region with the decrypted text. -@end deffn - -@deffn Command epa-decrypt-armor-in-region start end -Decrypt OpenPGP armors in the current region between @var{start} and -@var{end}. The difference from @code{epa-decrypt-region} is that -@code{epa-decrypt-armor-in-region} searches armors in the region -and applies @code{epa-decrypt-region} to each of them. That is, this -command does not alter the original text around armors. -@end deffn - -@deffn Command epa-verify-region start end -Verify the current region between @var{start} and @var{end}. It sends -the verification result to the minibuffer or a popup window. It -replaces the region with the signed text. -@end deffn - -@deffn Command epa-verify-cleartext-in-region -Verify OpenPGP cleartext blocks in the current region between -@var{start} and @var{end}. The difference from -@code{epa-verify-region} is that @code{epa-verify-cleartext-in-region} -searches OpenPGP cleartext blocks in the region and applies -@code{epa-verify-region} to each of them. That is, this command does -not alter the original text around OpenPGP cleartext blocks. -@end deffn - -@deffn Command epa-sign-region start end signers type -Sign the current region between @var{start} and @var{end}. By -default, it creates a cleartext signature. If a prefix argument is -given, it will let you select signing keys, and then a signature -type. -@end deffn - -@deffn Command epa-encrypt-region start end recipients sign signers -Encrypt the current region between @var{start} and @var{end}. It will -let you select recipients. If a prefix argument is given, it will -also ask you whether or not to sign the text before encryption and if -you answered yes, it will let you select the signing keys. -@end deffn - -@node Cryptographic operations on files -@section Cryptographic operations on files - -@deffn Command epa-decrypt-file file -Decrypt @var{file}. -@end deffn - -@deffn Command epa-verify-file file -Verify @var{file}. -@end deffn - -@deffn Command epa-sign-file file signers type -Sign @var{file}. If a prefix argument is given, it will let you -select signing keys, and then a signature type. -@end deffn - -@deffn Command epa-encrypt-file file recipients -Encrypt @var{file}. It will let you select recipients. -@end deffn - -@node Dired integration -@section Dired integration - -EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to -easily do cryptographic operations on files. For example, - -@example -M-x dired -(mark some files) -: e (or M-x epa-dired-do-encrypt) -(select recipients by 'm' and click [OK]) -@end example - -@noindent -The following keys are assigned. - -@table @kbd -@item : d -@kindex @kbd{: d} -@findex epa-dired-do-decrypt -Decrypt marked files. - -@item : v -@kindex @kbd{: v} -@findex epa-dired-do-verify -Verify marked files. - -@item : s -@kindex @kbd{: s} -@findex epa-dired-do-sign -Sign marked files. - -@item : e -@kindex @kbd{: e} -@findex epa-dired-do-encrypt -Encrypt marked files. - -@end table - -@node Mail-mode integration -@section Mail-mode integration - -EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help -user compose inline OpenPGP messages. Inline OpenPGP is a traditional -style of sending signed/encrypted emails by embedding raw OpenPGP -blobs inside a message body, not using modern MIME format. - -NOTE: Inline OpenPGP is not recommended and you should consider to use -PGP/MIME. See -@uref{http://josefsson.org/inline-openpgp-considered-harmful.html, -Inline OpenPGP in E-mail is bad@comma{} Mm'kay?}. - -@noindent -Once @code{epa-mail-mode} is enabled, the following keys are assigned. -You can do it by @kbd{C-u 1 M-x epa-mail-mode} or through the Customize -interface. Try @kbd{M-x customize-variable epa-global-mail-mode}. - -@table @kbd -@item C-c C-e C-d and C-c C-e d -@kindex @kbd{C-c C-e C-d} -@kindex @kbd{C-c C-e d} -@findex epa-mail-decrypt -Decrypt OpenPGP armors in the current buffer. - -@item C-c C-e C-v and C-c C-e v -@kindex @kbd{C-c C-e C-v} -@kindex @kbd{C-c C-e v} -@findex epa-mail-verify -Verify OpenPGP cleartext signed messages in the current buffer. - -@item C-c C-e C-s and C-c C-e s -@kindex @kbd{C-c C-e C-s} -@kindex @kbd{C-c C-e s} -@findex epa-mail-sign -Compose a signed message from the current buffer. - -@item C-c C-e C-e and C-c C-e e -@kindex @kbd{C-c C-e C-e} -@kindex @kbd{C-c C-e e} -@findex epa-mail-encrypt -Compose an encrypted message from the current buffer. -By default it tries to build the recipient list from @samp{to}, -@samp{cc}, and @samp{bcc} fields of the mail header. To include your -key in the recipient list, use @samp{encrypt-to} option in -@file{~/.gnupg/gpg.conf}. - -@end table - -@node Encrypting/decrypting *.gpg files -@section Encrypting/decrypting *.gpg files -By default, every file whose name ends with @samp{.gpg} will be -treated as encrypted. That is, when you open such a file, the -decrypted text is inserted in the buffer rather than encrypted one. -Similarly, when you save the buffer to a @samp{foo.gpg} file, -encrypted data is written. - -The file name pattern for encrypted files can be controlled by -@var{epa-file-name-regexp}. - -@defvar epa-file-name-regexp -Regexp which matches filenames treated as encrypted. -@end defvar - -You can disable this behavior with @kbd{M-x epa-file-disable}, and -then get it back with @kbd{M-x epa-file-enable}. - -@deffn Command epa-file-disable -Disable automatic encryption/decryption of *.gpg files. -@end deffn - -@deffn Command epa-file-enable -Enable automatic encryption/decryption of *.gpg files. -@end deffn - -@noindent -By default, @code{epa-file} will try to use symmetric encryption, aka -password-based encryption. If you want to use public key encryption -instead, do @kbd{M-x epa-file-select-keys}, which will pops up the key -selection dialog. - -@deffn Command epa-file-select-keys -Select recipient keys to encrypt the currently visiting file with -public key encryption. -@end deffn - -You can also change the default behavior with the variable -@var{epa-file-select-keys}. - -@defvar epa-file-select-keys -Control whether or not to pop up the key selection dialog. -@end defvar - -For frequently visited files, it might be a good idea to tell Emacs -which encryption method should be used through @xref{File Variables, , -, emacs, the Emacs Manual}. Use the @code{epa-file-encrypt-to} local -variable for this. -@vindex epa-file-encrypt-to - -For example, if you want an Elisp file should be encrypted with a -public key associated with an email address @samp{ueno@@unixuser.org}, -add the following line to the beginning of the file. - -@cartouche -@lisp -;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*- -@end lisp -@end cartouche - -Instead, if you want the file always (regardless of the value of the -@code{epa-file-select-keys} variable) encrypted with symmetric -encryption, change the line as follows. - -@cartouche -@lisp -;; -*- epa-file-encrypt-to: nil -*- -@end lisp -@end cartouche - -Other variables which control the automatic encryption/decryption -behavior are below. - -@defvar epa-file-cache-passphrase-for-symmetric-encryption -If non-@code{nil}, cache passphrase for symmetric encryption. The -default value is @code{nil}. -@end defvar - -@defvar epa-file-inhibit-auto-save -If non-@code{nil}, disable auto-saving when opening an encrypted file. -The default value is @code{t}. -@end defvar - -@node Caching Passphrases -@chapter Caching Passphrases - -Typing passphrases is an irritating task if you frequently open and -close the same file. GnuPG and EasyPG Assistant provide mechanisms to -remember your passphrases. However, the configuration is a bit -confusing since it depends on your GnuPG installation (GnuPG version 1 or -GnuPG version 2), encryption method (symmetric or public key), and whether or -not you want to use gpg-agent. Here are some questions: - -@enumerate -@item Do you use GnuPG version 2 instead of GnuPG version 1? -@item Do you use symmetric encryption rather than public key encryption? -@item Do you want to use gpg-agent? -@end enumerate - -Here are configurations depending on your answers: - -@multitable {111} {222} {333} {configuration configuration configuration} -@item @b{1} @tab @b{2} @tab @b{3} @tab Configuration -@item Yes @tab Yes @tab Yes @tab Set up gpg-agent. -@item Yes @tab Yes @tab No @tab You can't, without gpg-agent. -@item Yes @tab No @tab Yes @tab Set up gpg-agent. -@item Yes @tab No @tab No @tab You can't, without gpg-agent. -@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache. -@item No @tab Yes @tab No @tab Set up elisp passphrase cache. -@item No @tab No @tab Yes @tab Set up gpg-agent. -@item No @tab No @tab No @tab You can't, without gpg-agent. -@end multitable - -To set up gpg-agent, follow the instruction in GnuPG manual. -@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}. - -To set up elisp passphrase cache, set -@code{epa-file-cache-passphrase-for-symmetric-encryption}. -@xref{Encrypting/decrypting *.gpg files}. - -@node Bug Reports -@chapter Bug Reports - -Bugs and problems with EasyPG Assistant are actively worked on by the -Emacs development team. Feature requests and suggestions are also -more than welcome. Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, , -Bugs, emacs, Reporting Bugs}. - -When submitting a bug report, please try to describe in excruciating -detail the steps required to reproduce the problem. Also try to -collect necessary information to fix the bug, such as: - -@itemize @bullet -@item the GnuPG version. Send the output of @samp{gpg --version}. -@item the GnuPG configuration. Send the contents of @file{~/.gnupg/gpg.conf}. -@end itemize - -Before reporting the bug, you should set @code{epg-debug} in the -@file{~/.emacs} file and repeat the bug. Then, include the contents -of the @samp{ *epg-debug*} buffer. Note that the first letter of the -buffer name is a whitespace. - -@bye - -@c End: diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi deleted file mode 100644 index 6d791d7c5f6..00000000000 --- a/doc/misc/erc.texi +++ /dev/null @@ -1,1063 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename ../../info/erc -@settitle ERC Manual -@syncodeindex fn cp -@c %**end of header - -@copying -This manual is for ERC version 5.3. - -Copyright @copyright{} 2005-2012 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -All Emacs Lisp code contained in this document may be used, distributed, -and modified without restriction. -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* ERC: (erc). Powerful and extensible IRC client for Emacs. -@end direntry - -@titlepage -@title ERC manual -@subtitle a full-featured IRC client -@subtitle for Emacs and XEmacs - -@c The following two commands -@c start the copyright page. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up -@top ERC - -@insertcopying -@end ifnottex - -@menu -* Introduction:: What is ERC? -* Obtaining ERC:: How to get ERC releases and development - versions. -* Installation:: Compiling and installing ERC. -* Getting Started:: Quick Start guide to using ERC. -* Keystroke Summary:: Keystrokes used in ERC buffers. -* Modules:: Available modules for ERC. -* Advanced Usage:: Cool ways of using ERC. -* Getting Help and Reporting Bugs:: -* History:: The history of ERC. -* Copying:: The GNU General Public License gives you - permission to redistribute ERC on - certain terms; it also explains that - there is no warranty. -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: Search for terms. - -@detailmenu - --- The Detailed Node Listing --- - -Obtaining ERC - -* Releases:: Released versions of ERC. -* Development:: Latest unreleased development changes. - -Getting Started - -* Sample Session:: Example of connecting to the #emacs channel -* Special Features:: Differences from standalone IRC clients - -Advanced Usage - -* Connecting:: Ways of connecting to an IRC server. -* Sample Configuration:: An example configuration file. -* Options:: Options that are available for ERC. - -@end detailmenu -@end menu - -@node Introduction, Obtaining ERC, Top, Top -@comment node-name, next, previous, up -@chapter Introduction - -ERC is a powerful, modular, and extensible IRC client for Emacs. - -It comes with the following capabilities enabled by default. - -@itemize @bullet -@item Flood control -@item Timestamps -@item Join channels automatically -@item Buttonize URLs, nicknames, and other text -@item Wrap long lines -@item Highlight or remove IRC control characters -@item Highlight pals, fools, and other keywords -@item Detect netsplits -@item Complete nicknames and commands in a programmable fashion -@item Make displayed lines read-only -@item Input history -@item Track channel activity in the mode-line - -@end itemize - -@node Obtaining ERC, Installation, Introduction, Top -@comment node-name, next, previous, up -@chapter Obtaining ERC - -@menu -* Releases:: Released versions of ERC. -* Development:: Latest unreleased development changes. -@end menu - -Note that some ERC files are not included with Emacs due to copyright or -dependency issues. If desired, they may be found at the following -locations, or from your local GNU mirror. - -@itemize @bullet -@item @uref{http://ftp.gnu.org/gnu/erc/erc-5.3-extras.tar.gz} -@item @uref{http://ftp.gnu.org/gnu/erc/erc-5.3-extras.zip} -@end itemize - -The rest of this chapter may be skipped if you are using the version of -ERC that comes with Emacs. - -@node Releases, Development, Obtaining ERC, Obtaining ERC -@comment node-name, next, previous, up -@section Releases - -Choose to install a release if you want to minimize risk. - -Errors are corrected in development first. User-visible changes will be -announced on the @email{erc-discuss@@gnu.org} mailing list. -@pxref{Getting Help and Reporting Bugs}. - -@cindex releases, Debian package -@cindex Debian package for ERC -Debian users can get ERC via apt-get. The @file{erc} package is -available in the official Debian repository. - -@cindex releases, from source -Alternatively, you can download the latest release from -@uref{http://ftp.gnu.org/gnu/erc}, or your local GNU mirror. - -@node Development, , Releases, Obtaining ERC -@comment node-name, next, previous, up -@section Development -@cindex development - -Choose the development version if you want to live on the bleeding edge -of ERC development or try out new features before release. - -@cindex git version control system, using -The git version control system allows you to keep up-to-date with the -latest changes to the development version of ERC. It also allows you -to contribute changes (via commits, if you are have developer access to -the repository, or via patches, otherwise). If you would like to -contribute to ERC development, it is highly recommended that you use -git. - -If you are new to git, you might find this tutorial helpful: -@uref{http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html}. - -Downloading ERC with git and staying up-to-date involves the following -steps. - -@enumerate -@item Install git. - -@itemize @bullet -@item Debian and Ubuntu: @kbd{apt-get install git-core}. -@item Windows: @uref{http://git.or.cz/gitwiki/WindowsInstall}. -@item Other operating systems: download, compile, and install the source -from @uref{http://www.kernel.org/pub/software/scm/git/}, or find a git -package for your operating system. -@end itemize - -@item Download the ERC development branch. - -If you have developer access to ERC, do: - -@example -git clone ssh://loginname@@git.sv.gnu.org/srv/git/erc.git -@end example - -otherwise, do: - -@example -git clone git://git.sv.gnu.org/erc.git -@end example - -If you are behind a restrictive firewall, and do not have developer -access, then do the following instead: - -@example -git clone http://git.sv.gnu.org/r/erc.git -@end example - -@item List upstream changes that are missing from your local copy. -Do this whenever you want to see whether new changes have been committed -to ERC. If you wish, you may skip this step and proceed directly to -the ``update'' step. - -@example -# Change to the source directory you are interested in. -cd erc - -# Fetch new changes from the repository, but don't apply them yet -git fetch origin - -# Display log messages for the new changes -git log HEAD..origin -@end example - -``origin'' is git's name for the location where you originally got ERC -from. You can change this location at any time by editing the -@file{.git/config} file in the directory where the ERC source was -placed. - -@cindex updating ERC with git -@item Update to the latest version by pulling in any missing changes. - -@example -cd erc -git pull origin -@end example - -git will show how many files changed, and will provide a visual display -for how many lines were changed in each file. - -@end enumerate - -There are other ways to interact with the ERC repository. - -@itemize -@item Browse git repo: @uref{http://git.sv.gnu.org/gitweb/?p=erc.git} -@item Latest development snapshot: @uref{http://mwolson.org/static/dist/erc-latest.tar.gz} -@item Latest development snapshot (zip file): @uref{http://mwolson.org/static/dist/erc-latest.zip} -@end itemize - -The latest development snapshot can lag behind the git repo by as much -as 20 minutes, but never more than that. - -For further information on committing changes to ERC and performing -development, please consult -@uref{http://emacswiki.org/cgi-bin/wiki/ErcDevelopment}. - - -@node Installation, Getting Started, Obtaining ERC, Top -@comment node-name, next, previous, up -@chapter Installation - -ERC may be compiled and installed on your machine. - -This section may be skipped if you are using the version of ERC that -comes with Emacs. - -@subsubheading Compilation - -This is an optional step, since Emacs Lisp source code does not -necessarily have to be byte-compiled. It will yield a speed increase, -though. - -A working copy of Emacs or XEmacs is needed in order to compile ERC. By -default, the program that is installed with the name @command{emacs} -will be used. - -If you want to use the @command{xemacs} binary to perform the -compilation, you would need to edit @file{Makefile} in the top-level -directory as follows. You can put either a full path to an Emacs or -XEmacs binary or just the command name, as long as it is in the -@env{PATH}. - -@example -EMACS = xemacs -SITEFLAG = -no-site-file -@end example - -Running @code{make} should compile the ERC source files in the -@file{lisp} directory. - -@subsubheading Installation - -ERC may be installed into your file hierarchy by doing the following. - -Edit the @file{Makefile} file so that @env{ELISPDIR} points to where you -want the source and compiled ERC files to be installed and -@env{INFODIR} indicates where to put the ERC manual. Of course, you -will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the -Compilation section if you are using XEmacs. - -If you are installing ERC on a Debian system, you might want to change -the value of @env{INSTALLINFO} as specified in @file{Makefile}. - -Run @code{make} as a normal user. - -Run @code{make install} as the root user if you have chosen installation -locations that require this. - - -@node Getting Started, Keystroke Summary, Installation, Top -@comment node-name, next, previous, up -@chapter Getting Started -@cindex settings - -To use ERC, add the directory containing its files to your -@code{load-path} variable, in your @file{.emacs} file. Then, load ERC -itself. An example follows. - -@lisp -(require 'erc) -@end lisp - -Once ERC is loaded, the command @kbd{M-x erc} will start ERC and -prompt for the server to connect to. - -If you want to place ERC settings in their own file, you can place them -in @file{~/.emacs.d/.ercrc.el}, creating it if necessary. - -If you would rather use the Customize interface to change how ERC works, -do @kbd{M-x customize-group RET erc RET}. In particular, ERC comes with -lots of modules that may be enabled or disabled; to select which ones -you want, do @kbd{M-x customize-variable RET erc-modules RET}. - -@menu -* Sample Session:: Example of connecting to the #emacs channel -* Special Features:: Differences from standalone IRC clients -@end menu - -@node Sample Session, Special Features, Getting Started, Getting Started -@comment node-name, next, previous, up -@section Sample Session - -This is an example ERC session which shows how to connect to the #emacs -channel on Freenode. Another IRC channel on Freenode that may be of -interest is #erc, which is a channel where ERC users and developers hang -out. - -@itemize @bullet - -@item Connect to Freenode - -Run @kbd{M-x erc}. Use ``irc.freenode.net'' as the IRC server, ``6667'' -as the port, and choose a nickname. - -@item Get used to the interface - -Switch to the ``irc.freenode.net:6667'' buffer, if you're not already -there. You will see first some messages about checking for ident, and -then a bunch of other messages that describe the current IRC server. - -@item Join the #emacs channel - -In that buffer, type ``/join SPC #emacs'' and hit @kbd{RET}. Depending -on how you've set up ERC, either a new buffer for ``#emacs'' will be -displayed, or a new buffer called ``#emacs'' will be created in the -background. If the latter, switch to the ``#emacs'' buffer. You will -see the channel topic and a list of the people who are currently on the -channel. - -@item Register your nickname with Freenode - -If you would like to be able to talk with people privately on the -Freenode network, you will have to ``register'' your nickname. To do -so, switch to the ``irc.freenode.net:6667'' buffer and type ``/msg -NickServ register '', replacing ``'' with your -desired password. It should tell you that the operation was successful. - -@item Talk to people in the channel - -If you switch back to the ``#emacs'' buffer, you can type a message, and -everyone on the channel will see it. - -@item Open a query buffer to talk to someone - -If you want to talk with someone in private (this should usually not be -done for technical help, only for personal questions), type ``/query -'', replacing ``'' with the nickname of the person you would -like to talk to. Depending on how ERC is set up, you will either see a -new buffer with the name of the person, or such a buffer will be created -in the background and you will have to switch to it. Begin typing -messages, and you will be able to have a conversation. - -Note that if the other person is not registered, you will not be able to -talk with them. - -@end itemize - -@node Special Features, , Sample Session, Getting Started -@comment node-name, next, previous, up -@section Special Features - -ERC has some features that distinguish it from some IRC clients. - -@itemize @bullet - -@item multiple channels and multiple servers - -Every channel is put in a separate buffer. Several IRC servers may be -connected to at the same time. - -@cindex query buffers -@item private message separation - -Private conversations are treated as channels, and are put into separate -buffers in Emacs. We call these ``query buffers''. - -@item highlighting - -Some occurrences of words can be highlighted, which makes it easier to -track different kinds of conversations. - -@item notification - -ERC can notify you that certain users are online. - -@item channel tracking - -Channels can be hidden and conversation continue in the background. You -are notified when something is said in such a channel that is not -currently visible. This makes it easy to get Real Work done while still -maintaining an IRC presence. - -@item nick completion - -ERC can complete words upon hitting @kbd{TAB}, which eases the writing -of nicknames in messages. - -@cindex history ring -@item history - -Past actions are kept in history rings for future use. To navigate a -history ring, hit @kbd{M-p} to go backwards and @kbd{M-n} to go -forwards. - -@item multiple languages - -Different channels and servers may have different language encodings. - -In addition, it is possible to translate the messages that ERC uses into -multiple languages. Please contact the developers of ERC at -@email{erc-discuss@@gnu.org} if you are interested in helping with the -translation effort. - -@item user scripting - -Users can load scripts (e.g. auto greeting scripts) when ERC starts up. - -It is also possible to make custom IRC commands, if you know a little -Emacs Lisp. Just make an Emacs Lisp function and call it -@code{erc-cmd-NEWCOMMAND}, where @code{NEWCOMMAND} is the name of the -new command in capital letters. - -@item auto reconnect - -If the connection goes away at some point, ERC will try to reconnect -automatically. If it fails to reconnect, and you want to try to -manually reestablish the connection at some later point, switch to an -ERC buffer and run the @code{/RECONNECT} command. - -@end itemize - - -@node Keystroke Summary, Modules, Getting Started, Top -@comment node-name, next, previous, up -@chapter Keys Used in ERC -@cindex keystrokes - -This is a summary of keystrokes available in every ERC buffer. - -@table @kbd - -@item C-a or (`erc-bol') -Go to beginning of line or end of prompt. - -@item RET (`erc-send-current-line') -Send the current line - -@item TAB (`erc-complete-word') -If at prompt, complete the current word. -Otherwise, move to the next link or button. - -@item M-TAB (`ispell-complete-word') -Complete the given word, using ispell. - -@item C-c C-a (`erc-bol') -Go to beginning of line or end of prompt. - -@item C-c C-b (`erc-iswitchb') -Use `iswitchb-read-buffer' to prompt for a ERC buffer to switch to. - -@item C-c C-c (`erc-toggle-interpret-controls') -Toggle interpretation of control sequences in messages. - -@item C-c C-d (`erc-input-action') -Interactively input a user action and send it to IRC. - -@item C-c C-e (`erc-toggle-ctcp-autoresponse') -Toggle automatic CTCP replies (like VERSION and PING). - -@item C-c C-f (`erc-toggle-flood-control') -Toggle use of flood control on sent messages. - -@item C-c TAB (`erc-invite-only-mode') -Turn on the invite only mode (+i) for the current channel. - -@item C-c C-j (`erc-join-channel') -Join channel. If point is at the beginning of a channel name, use that -as default. - -@item C-c C-k (`erc-go-to-log-matches-buffer') -Interactively open an erc-log-matches buffer - -@item C-c C-l (`erc-save-buffer-in-logs') -Append buffer contents to the log file, if logging is enabled. - -@item C-c C-n (`erc-channel-names') -Run "/names #channel" in the current channel. - -@item C-c C-o (`erc-get-channel-mode-from-keypress') -Read a key sequence and call the corresponding channel mode function. -After doing @kbd{C-c C-o}, type in a channel mode letter. - -@kbd{C-g} means quit. -@kbd{RET} lets you type more than one mode at a time. -If @kbd{l} is pressed, @code{erc-set-channel-limit} gets called. -If @kbd{k} is pressed, @code{erc-set-channel-key} gets called. -Anything else will be sent to `erc-toggle-channel-mode'. - -@item C-c C-p (`erc-part-from-channel') -Part from the current channel and prompt for a reason. - -@item C-c C-q (`erc-quit-server') -Disconnect from current server after prompting for reason. - -@item C-c C-r (`erc-remove-text-properties-region') -Clears the region (start,end) in object from all colors, etc. - -@item C-c C-t (`erc-set-topic') -Prompt for a topic for the current channel. - -@item C-c C-u (`erc-kill-input') -Kill current input line using `erc-bol' followed by `kill-line'. - -@end table - - -@node Modules, Advanced Usage, Keystroke Summary, Top -@comment node-name, next, previous, up -@chapter Modules -@cindex modules - -One way to add functionality to ERC is to customize which of its many -modules are loaded. - -There is a spiffy customize interface, which may be reached by typing -@kbd{M-x customize-option erc-modules RET}. Alternatively, set -@code{erc-modules} manually and then call @code{erc-update-modules}. - -The following is a list of available modules. - -@table @code - -@cindex modules, autoaway -@item autoaway -Set away status automatically - -@cindex modules, autojoin -@item autojoin -Join channels automatically - -@cindex modules, bbdb -@item bbdb -Integrate with the Big Brother Database - -@cindex modules, button -@item button -Buttonize URLs, nicknames, and other text - -@cindex modules, capab-identify -@item capab-identify -Mark unidentified users on freenode and other servers supporting CAPAB. - -@cindex modules, completion -@cindex modules, pcomplete -@item completion (aka pcomplete) -Complete nicknames and commands (programmable) - -@cindex modules, fill -@item fill -Wrap long lines - -@cindex modules, hecomplete -@item hecomplete -Complete nicknames and commands (old). This is the old module---you -might prefer the ``completion'' module instead. - -@cindex modules, identd -@item identd -Launch an identd server on port 8113 - -@cindex modules, irccontrols -@item irccontrols -Highlight or remove IRC control characters - -@cindex modules, log -@item log -Save buffers in logs - -@cindex modules, match -@item match -Highlight pals, fools, and other keywords - -@cindex modules, menu -@item menu -Display a menu in ERC buffers - -@cindex modules, netsplit -@item netsplit -Detect netsplits - -@cindex modules, noncommands -@item noncommands -Don't display non-IRC commands after evaluation - -@cindex modules, notify -@item notify -Notify when the online status of certain users changes - -@cindex modules, page -@item page -Process CTCP PAGE requests from IRC - -@cindex modules, readonly -@item readonly -Make displayed lines read-only - -@cindex modules, replace -@item replace -Replace text in messages - -@cindex modules, ring -@item ring -Enable an input history - -@cindex modules, scrolltobottom -@item scrolltobottom -Scroll to the bottom of the buffer - -@cindex modules, services -@item services -Identify to Nickserv (IRC Services) automatically - -@cindex modules, smiley -@item smiley -Convert smileys to pretty icons - -@cindex modules, sound -@item sound -Play sounds when you receive CTCP SOUND requests - -@cindex modules, spelling -@item spelling -Check spelling of messages - -@cindex modules, stamp -@item stamp -Add timestamps to messages - -@cindex modules, track -@item track -Track channel activity in the mode-line - -@cindex modules, truncate -@item truncate -Truncate buffers to a certain size - -@cindex modules, unmorse -@item unmorse -Translate morse code in messages - -@end table - -@c PRE5_4: Document every option of every module in its own subnode - - -@node Advanced Usage, Getting Help and Reporting Bugs, Modules, Top -@comment node-name, next, previous, up -@chapter Advanced Usage -@cindex advanced topics - -@menu -* Connecting:: Ways of connecting to an IRC server. -* Sample Configuration:: An example configuration file. -* Options:: Options that are available for ERC. -@end menu - -@node Connecting, Sample Configuration, Advanced Usage, Advanced Usage -@comment node-name, next, previous, up -@section Connecting to an IRC Server -@cindex connecting - -The easiest way to connect to an IRC server is to call @kbd{M-x erc}. -If you want to assign this function to a keystroke, the following will -help you figure out its parameters. - -@defun erc -Select connection parameters and run ERC. -Non-interactively, it takes the following keyword arguments. - -@itemize @bullet -@item @var{server} -@item @var{port} -@item @var{nick} -@item @var{password} -@item @var{full-name} -@end itemize - -That is, if called with the following arguments, @var{server} and -@var{full-name} will be set to those values, whereas -@code{erc-compute-port}, @code{erc-compute-nick} and -@code{erc-compute-full-name} will be invoked for the values of the other -parameters. - -@example -(erc :server "irc.freenode.net" :full-name "Harry S Truman") -@end example -@end defun - -@subheading Server - -@defun erc-compute-server &optional server -Return an IRC server name. - -This tries a number of increasingly more default methods until a non-nil -value is found. - -@itemize @bullet -@item @var{server} (the argument passed to this function) -@item The @code{erc-server} option -@item The value of the IRCSERVER environment variable -@item The @code{erc-default-server} variable -@end itemize - -@end defun - -@defopt erc-server nil -IRC server to use if one is not provided. -@end defopt - -@subheading Port - -@defun erc-compute-port &optional port -Return a port for an IRC server. - -This tries a number of increasingly more default methods until a non-nil -value is found. - -@itemize @bullet -@item @var{port} (the argument passed to this function) -@item The @code{erc-port} option -@item The @code{erc-default-port} variable -@end itemize - -@end defun - -@defopt erc-port -IRC port to use if not specified. - -This can be either a string or a number. -@end defopt - -@subheading Nick - -@defun erc-compute-nick &optional nick -Return user's IRC nick. - -This tries a number of increasingly more default methods until a -non-nil value is found. - -@itemize -@item @var{nick} (the argument passed to this function) -@item The @code{erc-nick} option -@item The value of the IRCNICK environment variable -@item The result from the @code{user-login-name} function -@end itemize - -@end defun - -@defopt erc-nick -Nickname to use if one is not provided. - -This can be either a string, or a list of strings. -In the latter case, if the first nick in the list is already in use, -other nicks are tried in the list order. -@end defopt - -@defopt erc-nick-uniquifier -The string to append to the nick if it is already in use. -@end defopt - -@defopt erc-try-new-nick-p -If the nickname you chose isn't available, and this option is non-nil, -ERC should automatically attempt to connect with another nickname. - -You can manually set another nickname with the /NICK command. -@end defopt - -@subheading Full name - -@defun erc-compute-full-name &optional full-name -Return user's full name. - -This tries a number of increasingly more default methods until a -non-nil value is found. - -@itemize @bullet -@item @var{full-name} (the argument passed to this function) -@item The @code{erc-user-full-name} option -@item The value of the IRCNAME environment variable -@item The result from the @code{user-full-name} function -@end itemize - -@end defun - -@defopt erc-user-full-name -User full name. - -This can be either a string or a function to call. -@end defopt - -@node Sample Configuration, Options, Connecting, Advanced Usage -@comment node-name, next, previous, up -@section Sample Configuration -@cindex configuration, sample - -Here is an example of configuration settings for ERC. This can go into -your Emacs configuration file. Everything after the @code{(require -'erc)} command can optionally go into @file{~/.emacs.d/.ercrc.el}. - -@lisp -;;; Sample ERC configuration - -;; Add the ERC directory to load path -- you don't need this if you are -;; using the version of ERC that comes with Emacs -(add-to-list 'load-path "~/elisp/erc") - -;; Load ERC -(require 'erc) - -;; Load authentication info from an external source. Put sensitive -;; passwords and the like in here. -(load "~/.emacs.d/.erc-auth") - -;; This is an example of how to make a new command. Type "/uptime" to -;; use it. -(defun erc-cmd-UPTIME (&rest ignore) - "Display the uptime of the system, as well as some load-related -stuff, to the current ERC buffer." - (let ((uname-output - (replace-regexp-in-string - ", load average: " "] @{Load average@} [" - ;; Collapse spaces, remove - (replace-regexp-in-string - " +" " " - ;; Remove beginning and trailing whitespace - (replace-regexp-in-string - "^ +\\|[ \n]+$" "" - (shell-command-to-string "uptime")))))) - (erc-send-message - (concat "@{Uptime@} [" uname-output "]")))) - -;; This causes ERC to connect to the Freenode network upon hitting -;; C-c e f. Replace MYNICK with your IRC nick. -(global-set-key "\C-cef" (lambda () (interactive) - (erc :server "irc.freenode.net" :port "6667" - :nick "MYNICK"))) - -;; This causes ERC to connect to the IRC server on your own machine (if -;; you have one) upon hitting C-c e b. Replace MYNICK with your IRC -;; nick. Often, people like to run bitlbee (http://bitlbee.org/) as an -;; AIM/Jabber/MSN to IRC gateway, so that they can use ERC to chat with -;; people on those networks. -(global-set-key "\C-ceb" (lambda () (interactive) - (erc :server "localhost" :port "6667" - :nick "MYNICK"))) - -;; Make C-c RET (or C-c C-RET) send messages instead of RET. This has -;; been commented out to avoid confusing new users. -;; (define-key erc-mode-map (kbd "RET") nil) -;; (define-key erc-mode-map (kbd "C-c RET") 'erc-send-current-line) -;; (define-key erc-mode-map (kbd "C-c C-RET") 'erc-send-current-line) - -;;; Options - -;; Join the #emacs and #erc channels whenever connecting to Freenode. -(setq erc-autojoin-channels-alist '(("freenode.net" "#emacs" "#erc"))) - -;; Interpret mIRC-style color commands in IRC chats -(setq erc-interpret-mirc-color t) - -;; The following are commented out by default, but users of other -;; non-Emacs IRC clients might find them useful. -;; Kill buffers for channels after /part -;; (setq erc-kill-buffer-on-part t) -;; Kill buffers for private queries after quitting the server -;; (setq erc-kill-queries-on-quit t) -;; Kill buffers for server messages after quitting the server -;; (setq erc-kill-server-buffer-on-quit t) -@end lisp - -@node Options, , Sample Configuration, Advanced Usage -@comment node-name, next, previous, up -@section Options -@cindex options - -@c PRE5_4: (Node) Document every ERC option (module options go in -@c previous chapter) - -This section has not yet been written. For now, the easiest way to -check out the available options for ERC is to do -@kbd{M-x customize-group erc RET}. - - -@node Getting Help and Reporting Bugs, History, Advanced Usage, Top -@comment node-name, next, previous, up -@chapter Getting Help and Reporting Bugs -@cindex help, getting -@cindex bugs, reporting - -After you have read this guide, if you still have questions about ERC, -or if you have bugs to report, there are several places you can go. - -@itemize @bullet - -@item -@uref{http://www.emacswiki.org/cgi-bin/wiki/ERC} is the -emacswiki.org page for ERC. Anyone may add tips, hints, or bug -descriptions to it. - -@item -There are several mailing lists for ERC. To subscribe, visit -@uref{http://savannah.gnu.org/mail/?group=erc}. - -The mailing lists are also available on Gmane. -(@url{http://gmane.org/}). Gmane provides additional methods for -accessing the mailing lists, adding content to them, and searching them. - -@enumerate -@item gmane.emacs.erc.announce: Announcements - -@item gmane.emacs.erc.discuss: General discussion - -@item gmane.emacs.erc.cvs: Log messages for changes to the ERC source code - -@end enumerate - -@item -You can visit the IRC Freenode channel @samp{#emacs}. Many of the -contributors are frequently around and willing to answer your -questions. - -@end itemize - - -@node History, Copying, Getting Help and Reporting Bugs, Top -@comment node-name, next, previous, up -@chapter History -@cindex history, of ERC - -ERC was originally written by Alexander L. Belikoff -@email{abel@@bfr.co.il} and Sergey Berezin -@email{sergey.berezin@@cs.cmu.edu}. They stopped development around -December 1999. Their last released version was ERC 2.0. - -P.S.: If one of the original developers of ERC reads this, we'd like to -receive additional information for this file and hear comments in -general. - -@itemize -@item 2001 - -In June 2001, Mario Lang @email{mlang@@delysid.org} and Alex Schroeder -@email{alex@@gnu.org} took over development and created a ERC Project at -@uref{http://sourceforge.net/projects/erc}. - -In reaction to a mail about the new ERC development effort, Sergey -Berezin said, ``First of all, I'm glad that my version of ERC is being -used out there. The thing is, I do not have free time and enough -incentive anymore to work on ERC, so I would be happy if you guys take -over the project entirely.'' - -So we happily hacked away on ERC, and soon after (September 2001) -released the next "stable" version, 2.1. - -Most of the development of the new ERC happened on #emacs on -irc.openprojects.net. Over time, many people contributed code, ideas, -bugfixes, and a lot of alpha/beta/gamma testing. - -See the @file{CREDITS} file for a list of contributors. - -@item 2003 - -ERC 3.0 was released. - -@item 2004 - -ERC 4.0 was released. - -@item 2005 - -ERC 5.0 was released. Michael Olson @email{mwolson@@gnu.org} became -the release manager and eventually the maintainer. - -After some discussion between him and the Emacs developers, it was -decided to include ERC in Emacs. - -@item 2006 - -ERC 5.1 was released. It was subsequently included in Emacs 22. - -ERC became an official GNU project, and development moved to -@uref{http://sv.gnu.org/projects/erc}. We switched to using GNU Arch as -our revision control system. Our mailing list address changed as well. - -@item 2007 - -We switched to using git for our version control system. - -@end itemize - -@node Copying, GNU Free Documentation License, History, Top -@comment node-name, next, previous, up -@include gpl.texi - -@node GNU Free Documentation License, Concept Index, Copying, Top -@comment node-name, next, previous, up -@include doclicense.texi - -@node Concept Index, , GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Index - -@printindex cp - -@bye diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi deleted file mode 100644 index b357b3d5e67..00000000000 --- a/doc/misc/ert.texi +++ /dev/null @@ -1,849 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename ../../info/ert -@settitle Emacs Lisp Regression Testing -@c %**end of header - -@dircategory Emacs misc features -@direntry -* ERT: (ert). Emacs Lisp regression testing tool. -@end direntry - -@copying -Copyright @copyright{} 2008, 2010-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License'' -in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@node Top, Introduction, (dir), (dir) -@top ERT: Emacs Lisp Regression Testing - -ERT is a tool for automated testing in Emacs Lisp. Its main features -are facilities for defining tests, running them and reporting the -results, and for debugging test failures interactively. - -ERT is similar to tools for other environments such as JUnit, but has -unique features that take advantage of the dynamic and interactive -nature of Emacs. Despite its name, it works well both for test-driven -development (see -@url{http://en.wikipedia.org/wiki/Test-driven_development}) and for -traditional software development methods. - -@menu -* Introduction:: A simple example of an ERT test. -* How to Run Tests:: Run tests in Emacs or from the command line. -* How to Write Tests:: How to add tests to your Emacs Lisp code. -* How to Debug Tests:: What to do if a test fails. -* Extending ERT:: ERT is extensible in several ways. -* Other Testing Concepts:: Features not in ERT. - -@detailmenu - --- The Detailed Node Listing --- - -How to Run Tests - -* Running Tests Interactively:: Run tests in your current Emacs. -* Running Tests in Batch Mode:: Run tests in emacs -Q. -* Test Selectors:: Choose which tests to run. - -How to Write Tests - -* The @code{should} Macro:: A powerful way to express assertions. -* Expected Failures:: Tests for known bugs. -* Tests and Their Environment:: Don't depend on customizations; no side effects. -* Useful Techniques:: Some examples. - -How to Debug Tests - -* Understanding Explanations:: How ERT gives details on why an assertion failed. -* Interactive Debugging:: Tools available in the ERT results buffer. - -Extending ERT - -* Defining Explanation Functions:: Teach ERT about more predicates. -* Low-Level Functions for Working with Tests:: Use ERT's data for your purposes. - -Other Testing Concepts - -* Mocks and Stubs:: Stubbing out code that is irrelevant to the test. -* Fixtures and Test Suites:: How ERT differs from tools for other languages. - -@end detailmenu -@end menu - -@node Introduction, How to Run Tests, Top, Top -@chapter Introduction - -ERT allows you to define @emph{tests} in addition to functions, -macros, variables, and the other usual Lisp constructs. Tests are -simply Lisp code --- code that invokes other code and checks whether -it behaves as expected. - -ERT keeps track of the tests that are defined and provides convenient -commands to run them to verify whether the definitions that are -currently loaded in Emacs pass the tests. - -Some Lisp files have comments like the following (adapted from the -package @code{pp.el}): - -@lisp -;; (pp-to-string '(quote quote)) ; expected: "'quote" -;; (pp-to-string '((quote a) (quote b))) ; expected: "('a 'b)\n" -;; (pp-to-string '('a 'b)) ; same as above -@end lisp - -The code contained in these comments can be evaluated from time to -time to compare the output with the expected output. ERT formalizes -this and introduces a common convention, which simplifies Emacs -development, since programmers no longer have to manually find and -evaluate such comments. - -An ERT test definition equivalent to the above comments is this: - -@lisp -(ert-deftest pp-test-quote () - "Tests the rendering of `quote' symbols in `pp-to-string'." - (should (equal (pp-to-string '(quote quote)) "'quote")) - (should (equal (pp-to-string '((quote a) (quote b))) "('a 'b)\n")) - (should (equal (pp-to-string '('a 'b)) "('a 'b)\n"))) -@end lisp - -If you know @code{defun}, the syntax of @code{ert-deftest} should look -familiar: This example defines a test named @code{pp-test-quote} that -will pass if the three calls to @code{equal} all return true -(non-nil). - -@code{should} is a macro with the same meaning as @code{assert} but -better error reporting. @xref{The @code{should} Macro}. - -Each test should have a name that describes what functionality it tests. -Test names can be chosen arbitrarily --- they are in a -namespace separate from functions and variables --- but should follow -the usual Emacs Lisp convention of having a prefix that indicates -which package they belong to. Test names are displayed by ERT when -reporting failures and can be used when selecting which tests to run. - -The empty parentheses @code{()} in the first line don't currently have -any meaning and are reserved for future extension. They also make -the syntax of @code{ert-deftest} more similar to that of @code{defun}. - -The docstring describes what feature this test tests. When running -tests interactively, the first line of the docstring is displayed for -tests that fail, so it is good if the first line makes sense on its -own. - -The body of a test can be arbitrary Lisp code. It should have as few -side effects as possible; each test should be written to clean up -after itself, leaving Emacs in the same state as it was before the -test. Tests should clean up even if they fail. @xref{Tests and Their -Environment}. - - -@node How to Run Tests, How to Write Tests, Introduction, Top -@chapter How to Run Tests - -You can run tests either in the Emacs you are working in, or on the -command line in a separate Emacs process in batch mode (i.e., with no -user interface). The former mode is convenient during interactive -development, the latter is useful to make sure that tests pass -independently of your customizations; and it allows you to invoke -tests from makefiles, and to write scripts that run tests in several -different Emacs versions. - -@menu -* Running Tests Interactively:: Run tests in your current Emacs. -* Running Tests in Batch Mode:: Run tests in emacs -Q. -* Test Selectors:: Choose which tests to run. -@end menu - - -@node Running Tests Interactively, Running Tests in Batch Mode, How to Run Tests, How to Run Tests -@section Running Tests Interactively - -You can run the tests that are currently defined in your Emacs with -the command @kbd{@kbd{M-x} ert @kbd{RET} t @kbd{RET}}. (For an -explanation of the @code{t} argument, @pxref{Test Selectors}.) ERT will pop -up a new buffer, the ERT results buffer, showing the results of the -tests run. It looks like this: - -@example -Selector: t -Passed: 31 -Failed: 2 (2 unexpected) -Total: 33/33 - -Started at: 2008-09-11 08:39:25-0700 -Finished. -Finished at: 2008-09-11 08:39:27-0700 - -FF............................... - -F addition-test - (ert-test-failed - ((should - (= - (+ 1 2) - 4)) - :form - (= 3 4) - :value nil)) - -F list-test - (ert-test-failed - ((should - (equal - (list 'a 'b 'c) - '(a b d))) - :form - (equal - (a b c) - (a b d)) - :value nil :explanation - (list-elt 2 - (different-atoms c d)))) -@end example - -At the top, there is a summary of the results: we ran all tests defined -in the current Emacs (@code{Selector: t}), 31 of them passed, and 2 -failed unexpectedly. @xref{Expected Failures}, for an explanation of -the term @emph{unexpected} in this context. - -The line of dots and @code{F}s is a progress bar where each character -represents one test; it fills while the tests are running. A dot -means that the test passed, an @code{F} means that it failed. Below -the progress bar, ERT shows details about each test that had an -unexpected result. In the example above, there are two failures, both -due to failed @code{should} forms. @xref{Understanding Explanations}, -for more details. - -In the ERT results buffer, @kbd{TAB} and @kbd{S-TAB} cycle between -buttons. Each name of a function or macro in this buffer is a button; -moving point to it and typing @kbd{RET} jumps to its definition. - -Pressing @kbd{r} re-runs the test near point on its own. Pressing -@kbd{d} re-runs it with the debugger enabled. @kbd{.} jumps to the -definition of the test near point (@kbd{RET} has the same effect if -point is on the name of the test). On a failed test, @kbd{b} shows -the backtrace of the failure. - -@kbd{l} shows the list of @code{should} forms executed in the test. -If any messages were generated (with the Lisp function @code{message}) -in a test or any of the code that it invoked, @kbd{m} will show them. - -By default, long expressions in the failure details are abbreviated -using @code{print-length} and @code{print-level}. Pressing @kbd{L} -while point is on a test failure will increase the limits to show more -of the expression. - - -@node Running Tests in Batch Mode, Test Selectors, Running Tests Interactively, How to Run Tests -@section Running Tests in Batch Mode - -ERT supports automated invocations from the command line or from -scripts or makefiles. There are two functions for this purpose, -@code{ert-run-tests-batch} and @code{ert-run-tests-batch-and-exit}. -They can be used like this: - -@example -emacs -batch -l ert -l my-tests.el -f ert-run-tests-batch-and-exit -@end example - -This command will start up Emacs in batch mode, load ERT, load -@code{my-tests.el}, and run all tests defined in it. It will exit -with a zero exit status if all tests passed, or nonzero if any tests -failed or if anything else went wrong. It will also print progress -messages and error diagnostics to standard output. - -If ERT is not part of your Emacs distribution, you may need to use -@code{-L /path/to/ert/} so that Emacs can find it. You may need -additional @code{-L} flags to ensure that @code{my-tests.el} and all the -files that it requires are on your @code{load-path}. - - -@node Test Selectors, , Running Tests in Batch Mode, How to Run Tests -@section Test Selectors - -Functions like @code{ert} accept a @emph{test selector}, a Lisp -expression specifying a set of tests. Test selector syntax is similar -to Common Lisp's type specifier syntax: - -@itemize -@item @code{nil} selects no tests. -@item @code{t} selects all tests. -@item @code{:new} selects all tests that have not been run yet. -@item @code{:failed} and @code{:passed} select tests according to their most recent result. -@item @code{:expected}, @code{:unexpected} select tests according to their most recent result. -@item A string is a regular expression that selects all tests with matching names. -@item A test (i.e., an object of @code{ert-test} data type) selects that test. -@item A symbol selects the test that the symbol names. -@item @code{(member TESTS...)} selects the elements of TESTS, a list of -tests or symbols naming tests. -@item @code{(eql TEST)} selects TEST, a test or a symbol naming a test. -@item @code{(and SELECTORS...)} selects the tests that match all SELECTORS. -@item @code{(or SELECTORS...)} selects the tests that match any SELECTOR. -@item @code{(not SELECTOR)} selects all tests that do not match SELECTOR. -@item @code{(tag TAG)} selects all tests that have TAG on their tags list. -(Tags are optional labels you can apply to tests when you define them.) -@item @code{(satisfies PREDICATE)} selects all tests that satisfy PREDICATE, -a function that takes a test as argument and returns non-nil if it is selected. -@end itemize - -Selectors that are frequently useful when selecting tests to run -include @code{t} to run all tests that are currently defined in Emacs, -@code{"^foo-"} to run all tests in package @code{foo} (this assumes -that package @code{foo} uses the prefix @code{foo-} for its test names), -result-based selectors such as @code{(or :new :unexpected)} to -run all tests that have either not run yet or that had an unexpected -result in the last run, and tag-based selectors such as @code{(not -(tag :causes-redisplay))} to run all tests that are not tagged -@code{:causes-redisplay}. - - -@node How to Write Tests, How to Debug Tests, How to Run Tests, Top -@chapter How to Write Tests - -ERT lets you define tests in the same way you define functions. You -can type @code{ert-deftest} forms in a buffer and evaluate them there -with @code{eval-defun} or @code{compile-defun}, or you can save the -file and load it, optionally byte-compiling it first. - -Just like @code{find-function} is only able to find where a function -was defined if the function was loaded from a file, ERT is only able -to find where a test was defined if the test was loaded from a file. - - -@menu -* The @code{should} Macro:: A powerful way to express assertions. -* Expected Failures:: Tests for known bugs. -* Tests and Their Environment:: Don't depend on customizations; no side effects. -* Useful Techniques:: Some examples. -@end menu - -@node The @code{should} Macro, Expected Failures, How to Write Tests, How to Write Tests -@section The @code{should} Macro - -Test bodies can include arbitrary code; but to be useful, they need to -check whether the code being tested (or @emph{code under test}) -does what it is supposed to do. The macro @code{should} is similar to -@code{assert} from the cl package -(@pxref{Assertions,,, cl, Common Lisp Extensions}), -but analyzes its argument form and records information that ERT can -display to help debugging. - -This test definition - -@lisp -(ert-deftest addition-test () - (should (= (+ 1 2) 4))) -@end lisp - -will produce this output when run via @kbd{M-x ert}: - -@example -F addition-test - (ert-test-failed - ((should - (= - (+ 1 2) - 4)) - :form - (= 3 4) - :value nil)) -@end example - -In this example, @code{should} recorded the fact that (= (+ 1 2) 4) -reduced to (= 3 4) before it reduced to nil. When debugging why the -test failed, it helps to know that the function @code{+} returned 3 -here. ERT records the return value for any predicate called directly -within @code{should}. - -In addition to @code{should}, ERT provides @code{should-not}, which -checks that the predicate returns nil, and @code{should-error}, which -checks that the form called within it signals an error. An example -use of @code{should-error}: - -@lisp -(ert-deftest test-divide-by-zero () - (should-error (/ 1 0) - :type 'arith-error)) -@end lisp - -This checks that dividing one by zero signals an error of type -@code{arith-error}. The @code{:type} argument to @code{should-error} -is optional; if absent, any type of error is accepted. -@code{should-error} returns an error description of the error that was -signaled, to allow additional checks to be made. The error -description has the format @code{(ERROR-SYMBOL . DATA)}. - -There is no @code{should-not-error} macro since tests that signal an -error fail anyway, so @code{should-not-error} is effectively the -default. - -@xref{Understanding Explanations}, for more details on what -@code{should} reports. - - -@node Expected Failures, Tests and Their Environment, The @code{should} Macro, How to Write Tests -@section Expected Failures - -Some bugs are complicated to fix, or not very important, and are left as -@emph{known bugs}. If there is a test case that triggers the bug and -fails, ERT will alert you of this failure every time you run all -tests. For known bugs, this alert is a distraction. The way to -suppress it is to add @code{:expected-result :failed} to the test -definition: - -@lisp -(ert-deftest future-bug () - "Test `time-forward' with negative arguments. -Since this functionality isn't implemented, the test is known to fail." - :expected-result :failed - (time-forward -1)) -@end lisp - -ERT will still display a small @code{f} in the progress bar as a -reminder that there is a known bug, and will count the test as failed, -but it will be quiet about it otherwise. - -An alternative to marking the test as a known failure this way is to -delete the test. This is a good idea if there is no intent to fix it, -i.e., if the behavior that was formerly considered a bug has become an -accepted feature. - -In general, however, it can be useful to keep tests that are known to -fail. If someone wants to fix the bug, they will have a very good -starting point: an automated test case that reproduces the bug. This -makes it much easier to fix the bug, demonstrate that it is fixed, and -prevent future regressions. - -ERT displays the same kind of alerts for tests that pass unexpectedly -as it displays for unexpected failures. This way, if you make code -changes that happen to fix a bug that you weren't aware of, you will -know to remove the @code{:expected-result} clause of that test and -close the corresponding bug report, if any. - -Since @code{:expected-result} evaluates its argument when the test is -loaded, tests can be marked as known failures only on certain Emacs -versions, specific architectures, etc.: - -@lisp -(ert-deftest foo () - "A test that is expected to fail on Emacs 23 but succeed elsewhere." - :expected-result (if (string-match "GNU Emacs 23[.]" (emacs-version)) - :failed - :passed) - ...) -@end lisp - - -@node Tests and Their Environment, Useful Techniques, Expected Failures, How to Write Tests -@section Tests and Their Environment - -The outcome of running a test should not depend on the current state -of the environment, and each test should leave its environment in the -same state it found it in. In particular, a test should not depend on -any Emacs customization variables or hooks, and if it has to make any -changes to Emacs's state or state external to Emacs (such as the file -system), it should undo these changes before it returns, regardless of -whether it passed or failed. - -Tests should not depend on the environment because any such -dependencies can make the test brittle or lead to failures that occur -only under certain circumstances and are hard to reproduce. Of -course, the code under test may have settings that affect its -behavior. In that case, it is best to make the test @code{let}-bind -all such setting variables to set up a specific configuration for the -duration of the test. The test can also set up a number of different -configurations and run the code under test with each. - -Tests that have side effects on their environment should restore it to -its original state because any side effects that persist after the -test can disrupt the workflow of the programmer running the tests. If -the code under test has side effects on Emacs's current state, such as -on the current buffer or window configuration, the test should create -a temporary buffer for the code to manipulate (using -@code{with-temp-buffer}), or save and restore the window configuration -(using @code{save-window-excursion}), respectively. For aspects of -the state that can not be preserved with such macros, cleanup should -be performed with @code{unwind-protect}, to ensure that the cleanup -occurs even if the test fails. - -An exception to this are messages that the code under test prints with -@code{message} and similar logging; tests should not bother restoring -the @code{*Message*} buffer to its original state. - -The above guidelines imply that tests should avoid calling highly -customizable commands such as @code{find-file}, except, of course, if -such commands are what they want to test. The exact behavior of -@code{find-file} depends on many settings such as -@code{find-file-wildcards}, @code{enable-local-variables}, and -@code{auto-mode-alist}. It is difficult to write a meaningful test if -its behavior can be affected by so many external factors. Also, -@code{find-file} has side effects that are hard to predict and thus -hard to undo: It may create a new buffer or reuse an existing -buffer if one is already visiting the requested file; and it runs -@code{find-file-hook}, which can have arbitrary side effects. - -Instead, it is better to use lower-level mechanisms with simple and -predictable semantics like @code{with-temp-buffer}, @code{insert} or -@code{insert-file-contents-literally}, and to activate any desired mode -by calling the corresponding function directly --- after binding the -hook variables to nil. This avoids the above problems. - - -@node Useful Techniques, , Tests and Their Environment, How to Write Tests -@section Useful Techniques when Writing Tests - -Testing simple functions that have no side effects and no dependencies -on their environment is easy. Such tests often look like this: - -@lisp -(ert-deftest ert-test-mismatch () - (should (eql (ert--mismatch "" "") nil)) - (should (eql (ert--mismatch "" "a") 0)) - (should (eql (ert--mismatch "a" "a") nil)) - (should (eql (ert--mismatch "ab" "a") 1)) - (should (eql (ert--mismatch "Aa" "aA") 0)) - (should (eql (ert--mismatch '(a b c) '(a b d)) 2))) -@end lisp - -This test calls the function @code{ert--mismatch} several times with -various combinations of arguments and compares the return value to the -expected return value. (Some programmers prefer @code{(should (eql -EXPECTED ACTUAL))} over the @code{(should (eql ACTUAL EXPECTED))} -shown here. ERT works either way.) - -Here's a more complicated test: - -@lisp -(ert-deftest ert-test-record-backtrace () - (let ((test (make-ert-test :body (lambda () (ert-fail "foo"))))) - (let ((result (ert-run-test test))) - (should (ert-test-failed-p result)) - (with-temp-buffer - (ert--print-backtrace (ert-test-failed-backtrace result)) - (goto-char (point-min)) - (end-of-line) - (let ((first-line (buffer-substring-no-properties - (point-min) (point)))) - (should (equal first-line - " signal(ert-test-failed (\"foo\"))"))))))) -@end lisp - -This test creates a test object using @code{make-ert-test} whose body -will immediately signal failure. It then runs that test and asserts -that it fails. Then, it creates a temporary buffer and invokes -@code{ert--print-backtrace} to print the backtrace of the failed test -to the current buffer. Finally, it extracts the first line from the -buffer and asserts that it matches what we expect. It uses -@code{buffer-substring-no-properties} and @code{equal} to ignore text -properties; for a test that takes properties into account, -@code{buffer-substring} and @code{ert-equal-including-properties} -could be used instead. - -The reason why this test only checks the first line of the backtrace -is that the remainder of the backtrace is dependent on ERT's internals -as well as whether the code is running interpreted or compiled. By -looking only at the first line, the test checks a useful property ---- that the backtrace correctly captures the call to @code{signal} that -results from the call to @code{ert-fail} --- without being brittle. - -This example also shows that writing tests is much easier if the code -under test was structured with testing in mind. - -For example, if @code{ert-run-test} accepted only symbols that name -tests rather than test objects, the test would need a name for the -failing test, which would have to be a temporary symbol generated with -@code{make-symbol}, to avoid side effects on Emacs's state. Choosing -the right interface for @code{ert-run-tests} allows the test to be -simpler. - -Similarly, if @code{ert--print-backtrace} printed the backtrace to a -buffer with a fixed name rather than the current buffer, it would be -much harder for the test to undo the side effect. Of course, some -code somewhere needs to pick the buffer name. But that logic is -independent of the logic that prints backtraces, and keeping them in -separate functions allows us to test them independently. - -A lot of code that you will encounter in Emacs was not written with -testing in mind. Sometimes, the easiest way to write tests for such -code is to restructure the code slightly to provide better interfaces -for testing. Usually, this makes the interfaces easier to use as -well. - - -@node How to Debug Tests, Extending ERT, How to Write Tests, Top -@chapter How to Debug Tests - -This section describes how to use ERT's features to understand why -a test failed. - - -@menu -* Understanding Explanations:: How ERT gives details on why an assertion failed. -* Interactive Debugging:: Tools available in the ERT results buffer. -@end menu - - -@node Understanding Explanations, Interactive Debugging, How to Debug Tests, How to Debug Tests -@section Understanding Explanations - -Failed @code{should} forms are reported like this: - -@example -F addition-test - (ert-test-failed - ((should - (= - (+ 1 2) - 4)) - :form - (= 3 4) - :value nil)) -@end example - -ERT shows what the @code{should} expression looked like and what -values its subexpressions had: The source code of the assertion was -@code{(should (= (+ 1 2) 4))}, which applied the function @code{=} to -the arguments @code{3} and @code{4}, resulting in the value -@code{nil}. In this case, the test is wrong; it should expect 3 -rather than 4. - -If a predicate like @code{equal} is used with @code{should}, ERT -provides a so-called @emph{explanation}: - -@example -F list-test - (ert-test-failed - ((should - (equal - (list 'a 'b 'c) - '(a b d))) - :form - (equal - (a b c) - (a b d)) - :value nil :explanation - (list-elt 2 - (different-atoms c d)))) -@end example - -In this case, the function @code{equal} was applied to the arguments -@code{(a b c)} and @code{(a b d)}. ERT's explanation shows that -the item at index 2 differs between the two lists; in one list, it is -the atom c, in the other, it is the atom d. - -In simple examples like the above, the explanation is unnecessary. -But in cases where the difference is not immediately apparent, it can -save time: - -@example -F test1 - (ert-test-failed - ((should - (equal x y)) - :form - (equal a a) - :value nil :explanation - (different-symbols-with-the-same-name a a))) -@end example - -ERT only provides explanations for predicates that have an explanation -function registered. @xref{Defining Explanation Functions}. - - -@node Interactive Debugging, , Understanding Explanations, How to Debug Tests -@section Interactive Debugging - -Debugging failed tests essentially works the same way as debugging any -other problems with Lisp code. Here are a few tricks specific to -tests: - -@itemize -@item Re-run the failed test a few times to see if it fails in the same way -each time. It's good to find out whether the behavior is -deterministic before spending any time looking for a cause. In the -ERT results buffer, @kbd{r} re-runs the selected test. - -@item Use @kbd{.} to jump to the source code of the test to find out exactly -what it does. Perhaps the test is broken rather than the code -under test. - -@item If the test contains a series of @code{should} forms and you can't -tell which one failed, use @kbd{l}, which shows you the list of all -@code{should} forms executed during the test before it failed. - -@item Use @kbd{b} to view the backtrace. You can also use @kbd{d} to re-run -the test with debugging enabled, this will enter the debugger and show -the backtrace as well; but the top few frames shown there will not be -relevant to you since they are ERT's own debugger hook. @kbd{b} -strips them out, so it is more convenient. - -@item If the test or the code under testing prints messages using -@code{message}, use @kbd{m} to see what messages it printed before it -failed. This can be useful to figure out how far it got. - -@item You can instrument tests for debugging the same way you instrument -@code{defun}s for debugging --- go to the source code of the test and -type @kbd{@kbd{C-u} @kbd{C-M-x}}. Then, go back to the ERT buffer and -re-run the test with @kbd{r} or @kbd{d}. - -@item If you have been editing and rearranging tests, it is possible that -ERT remembers an old test that you have since renamed or removed --- -renamings or removals of definitions in the source code leave around a -stray definition under the old name in the running process (this is a -common problem in Lisp). In such a situation, hit @kbd{D} to let ERT -forget about the obsolete test. -@end itemize - - -@node Extending ERT, Other Testing Concepts, How to Debug Tests, Top -@chapter Extending ERT - -There are several ways to add functionality to ERT. - -@menu -* Defining Explanation Functions:: Teach ERT about more predicates. -* Low-Level Functions for Working with Tests:: Use ERT's data for your purposes. -@end menu - - -@node Defining Explanation Functions, Low-Level Functions for Working with Tests, Extending ERT, Extending ERT -@section Defining Explanation Functions - -The explanation function for a predicate is a function that takes the -same arguments as the predicate and returns an @emph{explanation}. -The explanation should explain why the predicate, when invoked with -the arguments given to the explanation function, returns the value -that it returns. The explanation can be any object but should have a -comprehensible printed representation. If the return value of the -predicate needs no explanation for a given list of arguments, the -explanation function should return nil. - -To associate an explanation function with a predicate, add the -property @code{ert-explainer} to the symbol that names the predicate. -The value of the property should be the symbol that names the -explanation function. - - -@node Low-Level Functions for Working with Tests, , Defining Explanation Functions, Extending ERT -@section Low-Level Functions for Working with Tests - -Both @code{ert-run-tests-interactively} and @code{ert-run-tests-batch} -are implemented on top of the lower-level test handling code in the -sections of @file{ert.el} labeled ``Facilities for running a single test'', -``Test selectors'', and ``Facilities for running a whole set of tests''. - -If you want to write code that works with ERT tests, you should take a -look at this lower-level code. Symbols that start with @code{ert--} -are internal to ERT, whereas those that start with @code{ert-} are -meant to be usable by other code. But there is no mature API yet. - -Contributions to ERT are welcome. - - -@node Other Testing Concepts, , Extending ERT, Top -@chapter Other Testing Concepts - -For information on mocks, stubs, fixtures, or test suites, see below. - - -@menu -* Mocks and Stubs:: Stubbing out code that is irrelevant to the test. -* Fixtures and Test Suites:: How ERT differs from tools for other languages. -@end menu - -@node Mocks and Stubs, Fixtures and Test Suites, Other Testing Concepts, Other Testing Concepts -@section Other Tools for Emacs Lisp - -Stubbing out functions or using so-called @emph{mocks} can make it -easier to write tests. See -@url{http://en.wikipedia.org/wiki/Mock_object} for an explanation of -the corresponding concepts in object-oriented languages. - -ERT does not have built-in support for mocks or stubs. The package -@code{el-mock} (see @url{http://www.emacswiki.org/emacs/el-mock.el}) -offers mocks for Emacs Lisp and can be used in conjunction with ERT. - - -@node Fixtures and Test Suites, , Mocks and Stubs, Other Testing Concepts -@section Fixtures and Test Suites - -In many ways, ERT is similar to frameworks for other languages like -SUnit or JUnit. However, two features commonly found in such -frameworks are notably absent from ERT: fixtures and test suites. - -Fixtures are mainly used (e.g., in SUnit or JUnit) to provide an -environment for a set of tests, and consist of set-up and tear-down -functions. - -While fixtures are a useful syntactic simplification in other -languages, this does not apply to Lisp, where higher-order functions -and `unwind-protect' are available. One way to implement and use a -fixture in ERT is - -@lisp -(defun my-fixture (body) - (unwind-protect - (progn [set up] - (funcall body)) - [tear down])) - -(ert-deftest my-test () - (my-fixture - (lambda () - [test code]))) -@end lisp - -(Another way would be a @code{with-my-fixture} macro.) This solves -the set-up and tear-down part, and additionally allows any test -to use any combination of fixtures, so it is more flexible than what -other tools typically allow. - -If the test needs access to the environment the fixture sets up, the -fixture can be modified to pass arguments to the body. - -These are well-known Lisp techniques. Special syntax for them could -be added but would provide only a minor simplification. - -(If you are interested in such syntax, note that splitting set-up and -tear-down into separate functions, like *Unit tools usually do, makes -it impossible to establish dynamic `let' bindings as part of the -fixture. So, blindly imitating the way fixtures are implemented in -other languages would be counter-productive in Lisp.) - -The purpose of test suites is to group related tests together. - -The most common use of this is to run just the tests for one -particular module. Since symbol prefixes are the usual way of -separating module namespaces in Emacs Lisp, test selectors already -solve this by allowing regexp matching on test names; e.g., the -selector "^ert-" selects ERT's self-tests. - -Other uses include grouping tests by their expected execution time, -e.g. to run quick tests during interactive development and slow tests less -often. This can be achieved with the @code{:tag} argument to -@code{ert-deftest} and @code{tag} test selectors. - -@bye - -@c LocalWords: ERT JUnit namespace docstring ERT's -@c LocalWords: backtrace makefiles workflow backtraces API SUnit -@c LocalWords: subexpressions diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi deleted file mode 100644 index d322ca7c3e1..00000000000 --- a/doc/misc/eshell.texi +++ /dev/null @@ -1,1016 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/eshell -@settitle Eshell: The Emacs Shell -@synindex vr fn -@c %**end of header - -@copying -This manual is for Eshell, the Emacs shell. - -Copyright @copyright{} 1999-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Eshell: (eshell). A command shell implemented in Emacs Lisp. -@end direntry - -@titlepage -@sp 4 -@c The title is printed in a large font. -@center @titlefont{User's Guide} -@sp -@center @titlefont{to} -@sp -@center @titlefont{Eshell: The Emacs Shell} -@ignore -@sp 2 -@center release 2.4 -@c -release- -@end ignore -@sp 3 -@center John Wiegley -@c -date- - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@c ================================================================ -@c The real text starts here -@c ================================================================ - -@ifnottex -@node Top, What is Eshell?, (dir), (dir) -@top Eshell - -Eshell is a shell-like command interpreter -implemented in Emacs Lisp. It invokes no external processes except for -those requested by the user. It is intended to be a functional -replacement for command shells such as @command{bash}, @command{zsh}, -@command{rc}, or @command{4dos}; since Emacs itself is capable of -handling the sort of tasks accomplished by those tools. -@c This manual is updated to release 2.4 of Eshell. - -@insertcopying -@end ifnottex - -@menu -* What is Eshell?:: A brief introduction to the Emacs Shell. -* Command basics:: The basics of command usage. -* Commands:: -* Arguments:: -* Input/Output:: -* Process control:: -* Extension modules:: -* Extras and Goodies:: -* Bugs and ideas:: Known problems, and future ideas. -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: -* Function and Variable Index:: -* Key Index:: -@end menu - -@node What is Eshell? -@chapter What is Eshell? -@cindex what is Eshell? -@cindex Eshell, what it is - -Eshell is a @dfn{command shell} written in Emacs Lisp. Everything it -does, it uses Emacs's facilities to do. This means that Eshell is as -portable as Emacs itself. It also means that cooperation with Lisp code -is natural and seamless. - -What is a command shell? To properly understand the role of a shell, -it's necessary to visualize what a computer does for you. Basically, a -computer is a tool; in order to use that tool, you must tell it what to -do---or give it ``commands.'' These commands take many forms, such as -clicking with a mouse on certain parts of the screen. But that is only -one form of command input. - -By far the most versatile way to express what you want the computer to -do is by using an abbreviated language called @dfn{script}. In -script, instead of telling the computer, ``list my files, please'', -one writes a standard abbreviated command word---@samp{ls}. Typing -@samp{ls} in a command shell is a script way of telling the computer -to list your files.@footnote{This is comparable to viewing the -contents of a folder using a graphical display.} - -The real flexibility of this approach is apparent only when you realize -that there are many, many different ways to list files. Perhaps you -want them sorted by name, sorted by date, in reverse order, or grouped -by type. Most graphical browsers have simple ways to express this. But -what about showing only a few files, or only files that meet a certain -criteria? In very complex and specific situations, the request becomes -too difficult to express using a mouse or pointing device. It is just -these kinds of requests that are easily solved using a command shell. - -For example, what if you want to list every Word file on your hard -drive, larger than 100 kilobytes in size, and which hasn't been looked -at in over six months? That is a good candidate list for deletion, when -you go to clean up your hard drive. But have you ever tried asking your -computer for such a list? There is no way to do it! At least, not -without using a command shell. - -The role of a command shell is to give you more control over what your -computer does for you. Not everyone needs this amount of control, and -it does come at a cost: Learning the necessary script commands to -express what you want done. A complicated query, such as the example -above, takes time to learn. But if you find yourself using your -computer frequently enough, it is more than worthwhile in the long run. -Any tool you use often deserves the time spent learning to master it. -@footnote{For the understandably curious, here is what that command -looks like: But don't let it fool you; once you know what's going on, -it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.} - -@menu -* Contributors to Eshell:: People who have helped out! -@end menu - -@node Contributors to Eshell -@section Contributors to Eshell -@cindex contributors -@cindex authors - -Contributions to Eshell are welcome. I have limited time to work on -this project, but I will gladly add any code you contribute to me to -this package. - -The following persons have made contributions to Eshell. - -@itemize @bullet -@item -Eli Zaretskii made it possible for Eshell to run without requiring -asynchronous subprocess support. This is important for MS-DOS, which -does not have such support.@refill - -@item -Miles Bader contributed many fixes during the port to Emacs 21.@refill - -@item -Stefan Monnier fixed the things which bothered him, which of course made -things better for all.@refill - -@item -Gerd Moellmann also helped to contribute bug fixes during the initial -integration with Emacs 21.@refill - -@item -Alex Schroeder contributed code for interactively querying the user -before overwriting files.@refill - -@item -Sudish Joseph helped with some XEmacs compatibility issues.@refill -@end itemize - -Apart from these, a lot of people have sent suggestions, ideas, -requests, bug reports and encouragement. Thanks a lot! Without you -there would be no new releases of Eshell. - -@node Command basics -@chapter Basic overview - -A command shell is a means of entering verbally-formed commands. This -is really all that it does, and every feature described in this manual -is a means to that end. Therefore, it's important to take firm hold on -exactly what a command is, and how it fits in the overall picture of -things. - -@menu -* Commands verbs:: Commands always begin with a verb. -* Command arguments:: Some verbs require arguments. -@end menu - -@node Commands verbs -@section Commands verbs - -Commands are expressed using @dfn{script}, a special shorthand language -computers can understand with no trouble. Script is an extremely simple -language; oddly enough, this is what makes it look so complicated! -Whereas normal languages use a variety of embellishments, the form of a -script command is always: - -@example -@var{verb} [@var{arguments}] -@end example - -The verb expresses what you want your computer to do. There are a fixed -number of verbs, although this number is usually quite large. On the -author's computer, it reaches almost 1400 in number. But of course, -only a handful of these are really necessary. - -Sometimes, the verb is all that's written. A verb is always a single -word, usually related to the task it performs. @command{reboot} is a -good example. Entering that on GNU/Linux will reboot the -computer---assuming you have sufficient privileges. - -Other verbs require more information. These are usually very capable -verbs, and must be told specifically what to do. The extra information -is given in the form of @dfn{arguments}. For example, the -@command{echo} verb prints back whatever arguments you type. It -requires these arguments to know what to echo. A proper use of -@command{echo} looks like this: - -@example -echo This is an example of using echo! -@end example - -This script command causes the computer to echo back: ``This is an -example of using echo!'' - -Although command verbs are always simple words, like @command{reboot} or -@command{echo}, arguments may have a wide variety of forms. There are -textual arguments, numerical arguments---even Lisp arguments. -Distinguishing these different types of arguments requires special -typing, for the computer to know exactly what you mean. - -@node Command arguments -@section Command arguments - -Eshell recognizes several different kinds of command arguments: - -@enumerate -@item Strings (also called textual arguments) -@item Numbers (floating point or integer) -@item Lisp lists -@item Lisp symbols -@item Emacs buffers -@item Emacs process handles -@end enumerate - -Most users need to worry only about the first two. The third, Lisp lists, -occur very frequently, but almost always behind the scenes. - -Strings are the most common type of argument, and consist of nearly any -character. Special characters---those used by Eshell -specifically---must be preceded by a backslash (@samp{\}). When in doubt, it -is safe to add backslashes anywhere and everywhere. - -Here is a more complicated @command{echo} example: - -@example -echo A\ Multi-word\ Argument\ With\ A\ \$\ dollar -@end example - -Beyond this, things get a bit more complicated. While not beyond the -reach of someone wishing to learn, it is definitely beyond the scope of -this manual to present it all in a simplistic manner. Get comfortable -with Eshell as a basic command invocation tool, and learn more about the -commands on your system; then come back when it all sits more familiarly -on your mind. Have fun! - -@node Commands -@chapter Commands - -@menu -* Invocation:: -* Completion:: -* Aliases:: -* History:: -* Scripts:: -* Built-ins:: -@end menu - -Essentially, a command shell is all about invoking commands---and -everything that entails. So understanding how Eshell invokes commands -is the key to comprehending how it all works. - -@node Invocation -@section Invocation - -Unlike regular system shells, Eshell never invokes kernel functions -directly, such as @code{exec(3)}. Instead, it uses the Lisp functions -available in the Emacs Lisp library. It does this by transforming the -command you specify into a callable Lisp form.@footnote{To see the Lisp -form that will be invoked, type: @samp{eshell-parse-command "echo -hello"}} - -This transformation, from the string of text typed at the command -prompt, to the ultimate invocation of either a Lisp function or external -command, follows these steps: - -@enumerate -@item Parse the command string into separate arguments. -@item -@end enumerate - -@node Completion -@section Completion - -@node Aliases -@section Aliases - -@node History -@section History - -Eshell knows a few built-in variables: - -@table @code - -@item $+ -@vindex $+ -This variable always contains the current working directory. - -@item $- -@vindex $- -This variable always contains the previous working directory (the -current working directory from before the last @code{cd} command). - -@item $_ -@vindex $_ -It refers to the last argument of the last command. - -@item $$ -@vindex $$ -This is the result of the last command. In case of an external -command, it is @code{t} or @code{nil}. - -@item $? -@vindex $? -This variable contains the exit code of the last command (0 or 1 for -Lisp functions, based on successful completion). - -@end table - -@node Scripts -@section Scripts - - -@node Built-ins -@section Built-in commands - -Several commands are built-in in Eshell. In order to call the -external variant of a built-in command @code{foo}, you could call -@code{*foo}. Usually, this should not be necessary. You can check -what will be applied by the @code{which} command: - -@example -~ $ which ls -eshell/ls is a compiled Lisp function in `em-ls.el' -~ $ which *ls -/bin/ls -@end example - -If you want to discard a given built-in command, you could declare an -alias, @ref{Aliases}. Eample: - -@example -~ $ which sudo -eshell/sudo is a compiled Lisp function in `em-unix.el' -~ $ alias sudo '*sudo $*' -~ $ which sudo -sudo is an alias, defined as "*sudo $*" -@end example - -Some of the built-in commands have a special behavior in Eshell: - -@table @code - -@item cd -@findex cd -This command changes the current working directory. Usually, it is -invoked as @samp{cd foo} where @file{foo} is the new working -directory. But @code{cd} knows about a few special arguments: - -When it receives no argument at all, it changes to the home directory. - -Giving the command @samp{cd -} changes back to the previous working -directory (this is the same as @samp{cd $-}). - -The command @samp{cd =} shows the directory stack. Each line is -numbered. - -With @samp{cd =foo}, Eshell searches the directory stack for a -directory matching the regular expression @samp{foo} and changes to -that directory. - -With @samp{cd -42}, you can access the directory stack by number. - -@item history -@findex history -The @samp{history} command shows all commands kept in the history ring -as numbered list. If the history ring contains -@code{eshell-history-size} commands, those numbers change after every -command invocation, therefore the @samp{history} command shall be -applied before using the expansion mechanism with history numbers. - -The n-th entry of the history ring can be applied with the @samp{!n} -command. If @code{n} is negative, the entry is counted from the end -of the history ring. - -@samp{!foo} expands to the last command beginning with @code{foo}, and -@samp{!?foo} to the last command containing @code{foo}. The n-th -argument of the last command beginning with @code{foo} is accessible -by @code{!foo:n}. - -@item su -@findex su -@itemx sudo -@findex sudo -@code{su} and @code{sudo} work as expected: they apply the following -commands (@code{su}), or the command being an argument (@code{sudo}) -under the permissions of somebody else. - -This does not work only on -the local host, but even on a remote one, when -@code{default-directory} is a remote file name. The necessary -proxy configuration of Tramp is performed -@ifinfo -automatically, @ref{Multi-hops, , , tramp}. -@end ifinfo -@ifnotinfo -automatically. -@end ifnotinfo -Example: - -@example -~ $ cd /ssh:otherhost:/etc -/ssh:user@@otherhost:/etc $ sudo find-file shadow -@end example - -@end table - - -@node Arguments -@chapter Arguments - -@menu -* The Parser:: -* Variables:: -* Substitution:: -* Globbing:: -* Predicates:: -@end menu - -@node The Parser -@section The Parser - -@node Variables -@section Variables - -@node Substitution -@section Substitution - -@node Globbing -@section Globbing - -@node Predicates -@section Predicates - - -@node Input/Output -@chapter Input/Output - -@node Process control -@chapter Process control - - -@node Extension modules -@chapter Extension modules - -@menu -* Writing a module:: -* Module testing:: -* Directory handling:: -* Key rebinding:: -* Smart scrolling:: -* Terminal emulation:: -* Built-in UNIX commands:: -@end menu - -@node Writing a module -@section Writing a module - -@node Module testing -@section Module testing - -@node Directory handling -@section Directory handling - -@node Key rebinding -@section Key rebinding - -@node Smart scrolling -@section Smart scrolling - -@node Terminal emulation -@section Terminal emulation - -@node Built-in UNIX commands -@section Built-in UNIX commands - - -@node Extras and Goodies -@chapter Extras and Goodies - -@node Bugs and ideas -@chapter Bugs and ideas -@cindex reporting bugs and ideas -@cindex bugs, how to report them -@cindex author, how to reach -@cindex email to the author -@cindex FAQ -@cindex problems, list of common - -If you find a bug or misfeature, don't hesitate to let me know! Send -email to @email{johnw@@gnu.org}. Feature requests should also be sent -there. I prefer discussing one thing at a time. If you find several -unrelated bugs, please report them separately. - -If you have ideas for improvements, or if you have written some -extensions to this package, I would like to hear from you. I hope you -find this package useful! - -@menu -* Known problems:: -@end menu - -@node Known problems -@section Known problems -@cindex known bugs -@cindex bugs, known - -Below is complete list of known problems with Eshell version 2.4.2, -which is the version included with Emacs 22. - -@table @asis -@item Documentation incomplete - -@item Differentiate between aliases and functions - -Allow for a bash-compatible syntax, such as: - -@example -alias arg=blah -function arg () @{ blah $* @} -@end example - -@item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt - -In fact, piping to a process from a looping construct doesn't work in -general. If I change the call to @code{eshell-copy-handles} in -@code{eshell-rewrite-for-command} to use @code{eshell-protect}, it seems -to work, but the output occurs after the prompt is displayed. The whole -structured command thing is too complicated at present. - -@item Error with @command{bc} in @code{eshell-test} - -On some XEmacs system, the subprocess interaction test fails -inexplicably, although @command{bc} works fine at the command prompt. - -@item Eshell does not delete @file{*Help*} buffers in XEmacs 21.1.8+ - -In XEmacs 21.1.8, the @file{*Help*} buffer has been renamed such that -multiple instances of the @file{*Help*} buffer can exist. - -@item Pcomplete sometimes gets stuck - -You press @key{TAB}, but no completions appear, even though the -directory has matching files. This behavior is rare. - -@item @samp{grep python $} doesn't work, but using @samp{*grep} does - -This happens because the @code{grep} Lisp function returns immediately, -and then the asynchronous @command{grep} process expects to examine the -temporary file, which has since been deleted. - -@item Problem with C-r repeating text - -If the text @emph{before point} reads "./run", and you type @kbd{C-r r u -n}, it will repeat the line for every character typed. - -@item Backspace doesn't scroll back after continuing (in smart mode) - -Hitting space during a process invocation, such as @command{make}, will -cause it to track the bottom of the output; but backspace no longer -scrolls back. - -@item It's not possible to fully @code{unload-feature} Eshell - -@item Menu support was removed, but never put back - -@item Using C-p and C-n with rebind gets into a locked state - -This happened a few times in Emacs 21, but has been irreproducible -since. - -@item If an interactive process is currently running, @kbd{M-!} doesn't work - -@item Use a timer instead of @code{sleep-for} when killing child processes - -@item Piping to a Lisp function is not supported - -Make it so that the Lisp command on the right of the pipe is repeatedly -called with the input strings as arguments. This will require changing -@code{eshell-do-pipeline} to handle non-process targets. - -@item Input redirection is not supported - -See the above entry. - -@item Problem running @command{less} without arguments on Windows - -The result in the Eshell buffer is: - -@example -Spawning child process: invalid argument -@end example - -Also a new @command{less} buffer was created with nothing in it@dots{} -(presumably this holds the output of @command{less}). - -If @command{less.exe} is invoked from the Eshell command line, the -expected output is written to the buffer. - -Note that this happens on NT-Emacs 20.6.1 on Windows 2000. The term.el -package and the supplied shell both use the @command{cmdproxy} program -for running shells. - -@item Implement @samp{-r}, @samp{-n} and @samp{-s} switches for @command{cp} - -@item Make @kbd{M-5 M-x eshell} switch to ``*eshell<5>*'', creating if need be - -@item @samp{mv @var{dir} @var{file}.tar} does not remove directories - -This is because the tar option --remove-files doesn't do so. Should it -be Eshell's job? - -@item Bind @code{standard-output} and @code{standard-error} - -This would be so that if a Lisp function calls @code{print}, everything -will happen as it should (albeit slowly). - -@item When an extension module fails to load, @samp{cd /} gives a Lisp error - -@item If a globbing pattern returns one match, should it be a list? - -@item Make sure syntax table is correct in Eshell mode - -So that @kbd{M-DEL} acts in a predictable manner, etc. - -@item Allow all Eshell buffers to share the same history and list-dir - -@item There is a problem with script commands that output to @file{/dev/null} - -If a script file, somewhere in the middle, uses @samp{> /dev/null}, -output from all subsequent commands is swallowed. - -@item Split up parsing of text after @samp{$} in @file{esh-var.el} - -Make it similar to the way that @file{esh-arg.el} is structured. -Then add parsing of @samp{$[?\n]}. - -@item After pressing @kbd{M-RET}, redisplay before running the next command - -@item Argument predicates and modifiers should work anywhere in a path - -@example -/usr/local/src/editors/vim $ vi **/CVS(/)/Root(.) -Invalid regexp: "Unmatched ( or \\(" -@end example - -With @command{zsh}, the glob above expands to all files named -@file{Root} in directories named @file{CVS}. - -@item Typing @samp{echo $@{locate locate@}/bin} results in a Lisp error - -Perhaps it should interpolate all permutations, and make that the -globbing result, since otherwise hitting return here will result in -``(list of filenames)/bin'', which is never valuable. Thus, one could -@command{cat} only C backup files by using @samp{ls $@{identity *.c@}~}. -In that case, having an alias command name @command{glob} for -@command{identity} would be useful. - -@item Once symbolic mode is supported for @command{umask}, implement @command{chmod} in Lisp - -@item Create @code{eshell-expand-file-name} - -This would use a data table to transform things such as @samp{~+}, -@samp{...}, etc. - -@item Abstract @file{em-smart.el} into @file{smart-scroll.el} - -It only really needs: to be hooked onto the output filter and the -pre-command hook, and to have the input-end and input-start markers. -And to know whether the last output group was ``successful.'' - -@item Allow for fully persisting the state of Eshell - -This would include: variables, history, buffer, input, dir stack, etc. - -@item Implement D as an argument predicate - -It means that files beginning with a dot should be included in the -glob match. - -@item A comma in a predicate list should mean OR - -At the moment, this is not supported. - -@item Error if a glob doesn't expand due to a predicate - -An error should be generated only if @code{eshell-error-if-no-glob} is -non-@code{nil}. - -@item @samp{(+ RET SPC TAB} does not cause @code{indent-according-to-mode} to occur - -@item Create @code{eshell-auto-accumulate-list} - -This is a list of commands for which, if the user presses @kbd{RET}, the -text is staged as the next Eshell command, rather than being sent to the -current interactive process. - -@item Display file and line number if an error occurs in a script - -@item @command{wait} doesn't work with process ids at the moment - -@item Enable the direct-to-process input code in @file{em-term.el} - -@item Problem with repeating @samp{echo $@{find /tmp@}} - -With smart display active, if @kbd{RET} is held down, after a while it -can't keep up anymore and starts outputting blank lines. It only -happens if an asynchronous process is involved@dots{} - -I think the problem is that @code{eshell-send-input} is resetting the -input target location, so that if the asynchronous process is not done -by the time the next @kbd{RET} is received, the input processor thinks -that the input is meant for the process; which, when smart display is -enabled, will be the text of the last command line! That is a bug in -itself. - -In holding down @kbd{RET} while an asynchronous process is running, -there will be a point in between termination of the process, and the -running of @code{eshell-post-command-hook}, which would cause -@code{eshell-send-input} to call @code{eshell-copy-old-input}, and then -process that text as a command to be run after the process. Perhaps -there should be a way of killing pending input between the death of the -process, and the @code{post-command-hook}. - -@item Allow for a more aggressive smart display mode - -Perhaps toggled by a command, that makes each output block a smart -display block. - -@item Create more meta variables - -@table @samp -@item $! -The reason for the failure of the last disk command, or the text of the -last Lisp error. - -@item $= -A special associate array, which can take references of the form -@samp{$=[REGEXP]}. It indexes into the directory ring. -@end table - -@item Eshell scripts can't execute in the background - -@item Support zsh's ``Parameter Expansion'' syntax, i.e. @samp{$@{@var{name}:-@var{val}@}} - -@item Write an @command{info} alias that can take arguments - -So that the user can enter @samp{info chmod}, for example. - -@item Create a mode @code{eshell-browse} - -It would treat the Eshell buffer as a outline. Collapsing the outline -hides all of the output text. Collapsing again would show only the -first command run in each directory - -@item Allow other revisions of a file to be referenced using @samp{file@{rev@}} - -This would be expanded by @code{eshell-expand-file-name} (see above). - -@item Print ``You have new mail'' when the ``Mail'' icon is turned on - -@item Implement @kbd{M-|} for Eshell - -@item Implement input redirection - -If it's a Lisp function, input redirection implies @command{xargs} (in a -way@dots{}). If input redirection is added, also update the -@code{file-name-quote-list}, and the delimiter list. - -@item Allow @samp{#<@var{word} @var{arg}>} as a generic syntax - -With the handling of @emph{word} specified by an -@code{eshell-special-alist}. - -@item In @code{eshell-eval-using-options}, allow a @code{:complete} tag - -It would be used to provide completion rules for that command. Then the -macro will automagically define the completion function. - -@item For @code{eshell-command-on-region}, apply redirections to the result - -So that @samp{+ > 'blah} would cause the result of the @code{+} (using -input from the current region) to be inserting into the symbol -@code{blah}. - -If an external command is being invoked, the input is sent as standard -input, as if a @samp{cat |} had been invoked. - -If a Lisp command, or an alias, is invoked, then if the line has no -newline characters, it is divided by whitespace and passed as arguments -to the Lisp function. Otherwise, it is divided at the newline -characters. Thus, invoking @code{+} on a series of numbers will add -them; @code{min} would display the smallest figure, etc. - -@item Write @code{eshell-script-mode} as a minor mode - -It would provide syntax, abbrev, highlighting and indenting support like -@code{emacs-lisp-mode} and @code{shell-mode}. - -@item In the history mechanism, finish the @command{bash}-style support - -This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate -from @samp{!:1*}. - -@item Support the -n command line option for @command{history} - -@item Implement @command{fc} in Lisp - -@item Specifying a frame as a redirection target should imply the currently active window's buffer - -@item Implement @samp{>@var{func-or-func-list}} - -This would allow for an ``output translators'', that take a function to -modify output with, and a target. Devise a syntax that works well with -pipes, and can accommodate multiple functions (i.e., @samp{>'(upcase -regexp-quote)} or @samp{>'upcase}). - -@item Allow Eshell to read/write to/from standard input and output - -This would be optional, rather than always using the Eshell buffer. -This would allow it to be run from the command line (perhaps). - -@item Write a @command{help} command - -It would call subcommands with @option{--help}, or @option{-h} or -@option{/?}, as appropriate. - -@item Implement @command{stty} in Lisp - -@item Support @command{rc}'s matching operator, e.g. @samp{~ (@var{list}) @var{regexp}} - -@item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list} - -Using @command{bg} on a process that is already in the background does -nothing. Specifying redirection targets replaces (or adds) to the list -current being used. - -@item Have @command{jobs} print only the processes for the current shell - -@item How can Eshell learn if a background process has requested input? - -@item Support @samp{2>&1} and @samp{>&} and @samp{2>} and @samp{|&} - -The syntax table for parsing these should be customizable, such that the -user could change it to use rc syntax: @samp{>[2=1]}. - -@item Allow @samp{$_[-1]}, which would indicate the last element of the array - -@item Make @samp{$x[*]} equal to listing out the full contents of @samp{x} - -Return them as a list, so that @samp{$_[*]} is all the arguments of the -last command. - -@item Copy ANSI code handling from @file{term.el} into @file{em-term.el} - -Make it possible for the user to send char-by-char to the underlying -process. Ultimately, I should be able to move away from using term.el -altogether, since everything but the ANSI code handling is already part -of Eshell. Then, things would work correctly on MS-Windows as well -(which doesn't have @file{/bin/sh}, although @file{term.el} tries to use -it). - -@item Make the shell spawning commands be visual - -That is, make (@command{su}, @command{bash}, @command{telnet}, -@command{rlogin}, @command{rsh}, etc.) be part of -@code{eshell-visual-commands}. The only exception is if the shell is -being used to invoke a single command. Then, the behavior should be -based on what that command is. - -@item Create a smart viewing command named @command{open} - -This would search for some way to open its argument (similar to opening -a file in the Windows Explorer). - -@item Alias @command{read} to be the same as @command{open}, only read-only - -@item Write a @command{tail} command which uses @code{view-file} - -It would move point to the end of the buffer, and then turns on -auto-revert mode in that buffer at frequent intervals---and a -@command{head} alias which assumes an upper limit of -@code{eshell-maximum-line-length} characters per line. - -@item Make @command{dgrep} load @code{dired}, mark everything, then invoke @code{dired-do-search} - -@item Write mesh.c - -This would run Emacs with the appropriate arguments to invoke Eshell -only. That way, it could be listed as a login shell. - -@item Use an intangible @code{PS2} string for multi-line input prompts - -@item Auto-detect when a command is visual, by checking @code{TERMCAP} usage - -@item The first keypress after @kbd{M-x watson} triggers `eshell-send-input' - -@item Make @kbd{/} electric - -So that it automatically expands and corrects pathnames. Or make -pathname completion for Pcomplete auto-expand @samp{/u/i/std} to -@samp{/usr/include/std}. - -@item Write the @command{pushd} stack to disk along with @code{last-dir-ring} - -@item Add options to @code{eshell/cat} which would allow it to sort and uniq - -@item Implement @command{wc} in Lisp - -Add support for counting sentences, paragraphs, pages, etc. - -@item Once piping is added, implement @command{sort} and @command{uniq} in Lisp - -@item Implement @command{touch} in Lisp - -@item Implement @command{comm} in Lisp - -@item Implement an @command{epatch} command in Lisp - -This would call @code{ediff-patch-file}, or @code{ediff-patch-buffer}, -depending on its argument. - -@item Have an option such that @samp{ls -l} generates a dired buffer - -@item Write a version of @command{xargs} based on command rewriting - -That is, @samp{find X | xargs Y} would be indicated using @samp{Y -$@{find X@}}. Maybe @code{eshell-do-pipelines} could be changed to -perform this on-thy-fly rewriting. - -@item Write an alias for @command{less} that brings up a @code{view-mode} buffer - -Such that the user can press @key{SPC} and @key{DEL}, and then @key{q} -to return to Eshell. It would be equivalent to: -@samp{X > #; view-buffer #}. - -@item Make @code{eshell-mode} as much a full citizen as @code{shell-mode} - -Everywhere in Emacs where @code{shell-mode} is specially noticed, add -@code{eshell-mode} there. - -@item Permit the umask to be selectively set on a @command{cp} target - -@item Problem using @kbd{M-x eshell} after using @code{eshell-command} - -If the first thing that I do after entering Emacs is to run -@code{eshell-command} and invoke @command{ls}, and then use @kbd{M-x -eshell}, it doesn't display anything. - -@item @kbd{M-RET} during a long command (using smart display) doesn't work - -Since it keeps the cursor up where the command was invoked. - -@end table - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index -@unnumbered Concept Index - -@printindex cp - -@node Function and Variable Index -@unnumbered Function and Variable Index - -@printindex fn - -@node Key Index -@unnumbered Key Index - -@printindex ky -@bye diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi deleted file mode 100644 index dec178c5258..00000000000 --- a/doc/misc/eudc.texi +++ /dev/null @@ -1,960 +0,0 @@ -\input texinfo.tex -@c %**start of header -@setfilename ../../info/eudc -@settitle Emacs Unified Directory Client (EUDC) Manual -@afourpaper -@c %**end of header - -@copying -This file documents EUDC v1.30b. - -EUDC is the Emacs Unified Directory Client, a common interface to -directory servers using various protocols such as LDAP or the CCSO white -pages directory system (PH/QI) - -Copyright @copyright{} 1998, 2000-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* EUDC: (eudc). Emacs client for directory servers (LDAP, PH). -@end direntry - -@footnotestyle end - -@titlepage -@title{EUDC Manual} -@subtitle{The Emacs Unified Directory Client} -@author by Oscar Figueiredo -@code{1.30b} - -@page -@vskip 0pt plus 1fill -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Overview, (dir), (dir) -@top Emacs Unified Directory Client -@comment node-name, next, previous, up - -@insertcopying -@end ifnottex - -@menu -* Overview:: Summary of EUDC features -* Installation:: How to install EUDC -* Usage:: The various usage possibilities explained -* Credits:: Who's done what -* GNU Free Documentation License:: The license for this documentation. -* Command and Function Index:: -* Variables Index:: -@end menu - - - - - -@node Overview, Installation, Top, Top -@comment node-name, next, previous, up -@chapter Overview - -EUDC, the @dfn{Emacs Unified Directory Client}, provides a common user -interface to access directory servers using different directory -protocols. - -Currently supported back-ends are: - -@itemize @bullet -@item -LDAP, Lightweight Directory Access Protocol -@item -CCSO PH/QI -@item -BBDB, Big Brother's Insidious Database -@end itemize - -The main features of the EUDC interface are: - -@itemize @bullet -@item -Queries using a customizable form -@item -Inline query expansion (for instance you can expand a name -to an email address in a mail message buffer using a server as an -address book) -@item -Multiple servers can be tried in turn until a match is found for an -inline query -@item -Fast minibuffer queries for email addresses and phone numbers -@item -Interface to BBDB to let you insert server records into your own BBDB database -(@pxref{Top,,BBDB,bbdb,BBDB Manual}) -@end itemize - -@menu -* LDAP:: What is LDAP ? -* CCSO PH/QI:: What is CCSO, PH, QI ? -* BBDB:: What is BBDB ? -@end menu - - - -@node LDAP, CCSO PH/QI, Overview, Overview -@comment node-name, next, previous, up -@section LDAP - -LDAP, @dfn{the Lightweight Directory Access Protocol}, is a communication -protocol for directory applications defined in RFC 1777. - -Quoted from RFC 1777: - -@quotation -[LDAP] is designed to provide access to the X.500 Directory while not -incurring the resource requirements of the Directory Access Protocol -(DAP). This protocol is specifically targeted at simple management -applications and browser applications that provide simple read/write -interactive access to the X.500 Directory, and is intended to be a -complement to the DAP itself. -@end quotation - -LDAP servers usually store (but are not limited to) information about -people such as their name, phone number, email address, office -location, etc@enddots{} More information about LDAP can be found at -@url{http://www.openldap.org/}. - -EUDC requires external support to access LDAP directory servers -(@pxref{LDAP Requirements}) - - -@node CCSO PH/QI, BBDB, LDAP, Overview -@comment node-name, next, previous, up -@section CCSO PH/QI - -The Central Computing Services Office (CCSO) of the University of -Illinois at Urbana Champaign created and freely distributed a -directory system that was used by many organizations in the 1990s. -The system records information about people such as their address, -phone number, email, academic information or any other details it was -configured to. Nowadays this system is not widely used. - -The system consists of two parts: a database server traditionally called -@samp{qi} and a command-line client called @samp{ph}. As of 2010, the -code can still be downloaded from @url{http://www-dev.cites.uiuc.edu/ph/}. - -The original command-line @samp{ph} client that comes with the -@samp{ph/qi} distribution provides additional features like the -possibility to communicate with the server in login-mode which makes it -possible to change records in the database. This is not implemented in -EUDC. - - -@node BBDB, , CCSO PH/QI, Overview -@comment node-name, next, previous, up -@section BBDB - -BBDB is the @dfn{Big Brother's Insidious Database}, a package for Emacs -originally written by Jamie Zawinski which provides rolodex-like -database functionality featuring tight integration with the Emacs mail -and news readers. - -It is often used as an enhanced email address book. - -EUDC considers BBDB as a directory server back end just like LDAP or -PH/QI servers, though BBDB has no client/server protocol and thus always -resides locally on your machine. The point in this is not to offer an -alternate way to query your BBDB database (BBDB itself provides much -more flexible ways to do that), but rather to offer an interface to your -local directory that is consistent with the interface to external -directories (LDAP, PH/QI). This is particularly interesting when -performing queries on multiple servers. - -EUDC also offers a means to insert results from directory queries into -your own local BBDB (@pxref{Creating BBDB Records}) - -@node Installation, Usage, Overview, Top -@comment node-name, next, previous, up -@chapter Installation - -Add the following to your @file{.emacs} init file: -@lisp -(require 'eudc) -@end lisp -This will install EUDC at startup. - -After installing EUDC you will find (the next time you launch Emacs) a -new @code{Directory Search} submenu in the @samp{Tools} menu that will -give you access to EUDC. - -You may also find it useful to add the following to your @file{.emacs} -initialization file to add a shortcut for email address expansion in -email composition buffers (@pxref{Inline Query Expansion}) - -@lisp -(eval-after-load - "message" - '(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) -(eval-after-load - "sendmail" - '(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) -@end lisp - -@menu -* LDAP Requirements:: EUDC needs external support for LDAP -@end menu - -@node LDAP Requirements, , Installation, Installation -@comment node-name, next, previous, up -@section LDAP Requirements - -LDAP support is added by means of @file{ldap.el}, which is part of Emacs. -@file{ldap.el} needs an external command line utility named -@file{ldapsearch}, available as part of Open LDAP -(@url{http://www.openldap.org/}). - - -@node Usage, Credits, Installation, Top -@comment node-name, next, previous, up -@chapter Usage - -This chapter describes the usage of EUDC. Most functions and -customization options are available through the @samp{Directory Search} -submenu of the @samp{Tools} submenu. - -@menu -* Querying Servers:: How queries are performed and handled -* Query Form:: How to use and customize the query form -* Display of Query Results:: Controlling how query results are presented -* Inline Query Expansion:: How to use and customize inline queries -* The Server Hotlist:: How to use and manage the server hotlist -* Multi-server Queries:: How to query multiple servers successively -* Creating BBDB Records:: How to insert query results into your BBDB -* Server/Protocol Locals:: Customizing on a per server/protocol basis -@end menu - - -@node Querying Servers, Query Form, Usage, Usage -@comment node-name, next, previous, up -@section Querying Servers - -EUDC's basic functionality is to let you query a directory server and -return the results back to you. There are several things you may want -to customize in this process. - - -@menu -* Selecting a Server:: The first thing to do -* Return Attributes:: Configuring what the server should return -* Duplicate Attributes:: What to do when records have duplicate attributes -@end menu - -@node Selecting a Server, Return Attributes, Querying Servers, Querying Servers -@subsection Selecting a Server - -Before doing any query you will need to set the directory server. You -need to specify the name of the host machine running the server software -and the protocol to use. If you do not set the server in any fashion, -EUDC will ask you for one when you make your first query. - -You can set the server by selecting one from your hotlist of servers -(@pxref{The Server Hotlist}) available in the @samp{Server} submenu or -by selecting @samp{New Server} in that same menu. - -LDAP servers generally require some configuration before you can perform -queries on them. In particular, the @dfn{search base} must be -configured. If the server you select has no configured search base then -EUDC will propose you to configure it at this point. A customization -buffer will be displayed where you can edit the search base and other -parameters for the server. - -@defvar eudc-server -The name or IP address of the remote directory server. A TCP port number -may be specified by appending a colon and a number to the name of the -server. You will not need this unless your server runs on a port other -than the default (which depends on the protocol). -If the directory server resides on your own computer (which is the case -if you use the BBDB back end) then `localhost' is a reasonable value but -it will be ignored anyway. -@end defvar - -@defvar eudc-protocol -The directory protocol to use to query the server. Currently supported -protocols in this version of EUDC are @code{ph}, @code{ldap} and @code{bbdb}. -@end defvar - -@deffn Command eudc-set-server -This command accessible from @samp{New Server} submenu lets you specify a -new directory server and protocol. -@end deffn - -@node Return Attributes, Duplicate Attributes, Selecting a Server, Querying Servers -@subsection Return Attributes - -Directory servers may be configured to return a default set of -attributes for each record matching a query if the query specifies none. -The variable @code{eudc-default-return-attributes} controls the return -attributes you want to see, if different from the server defaults. - -@defvar eudc-default-return-attributes -A list of the default attributes to extract from directory entries. If -set to the symbol @code{all} then all available attributes are -returned. A value of @code{nil}, the default, means to return the -default attributes as configured in the server. -@end defvar - -The server may return several matching records to a query. Some of the -records may however not contain all the attributes you requested. You can -discard those records. - -@defopt eudc-strict-return-matches -If non-@code{nil}, entries that do not contain all the requested return -attributes are ignored. Default is @code{t}. -@end defopt - -@node Duplicate Attributes, , Return Attributes, Querying Servers -@subsection Duplicate Attributes - -Directory standards may authorize different instances of the same -attribute in a record. For instance the record of a person may contain -several email fields containing different email addresses. When using -a QI directory server this is difficult to distinguish from attributes -having multi-line values such as the postal address that may contain a -line for the street and another one for the zip code and city name. In -both cases, EUDC will consider the attribute duplicated. - -EUDC has several methods to deal with duplicated attributes. The -available methods are: - -@table @code -@item list -Makes a list with the different values of the duplicate attribute. The -record is returned with only one instance of the attribute with a list -of all the different values as a value. This is the default method that -is used to handle duplicate fields for which no other method has been -specified. -@item first -Discards all the duplicate values of the field keeping only the first -one. -@item concat -Concatenates the different values using a newline as a separator. The -record keeps only one instance of the field the value of which is a -single multi-line string. -@item duplicate -Duplicates the whole record into as many instances as there are different -values for the field. This is the default for the email field. Thus a -record containing 3 different email addresses is duplicated into three -different records each having a single email address. This is -particularly useful in combination with @code{select} as the method to -handle multiple matches in inline expansion queries (@pxref{Inline Query -Expansion}) because you are presented with the 3 addresses in a -selection buffer -@end table - -Because a method may not be applicable to all fields, the variable -@code{eudc-duplicate-attribute-handling-method} lets you specify either a -default method for all fields or a method for each individual field. - -@defvar eudc-duplicate-attribute-handling-method -A method to handle entries containing duplicate attributes. This is -either an alist of elements @code{(@var{attr} . @var{method})}, or a symbol -@var{method}. The alist form of the variable associates a method to an -individual attribute name; the second form specifies a method applicable -to all attribute names. Available methods are: @code{list}, -@code{first}, @code{concat}, and @code{duplicate} (see above). The default is -@code{list}. -@end defvar - - - -@node Query Form, Display of Query Results, Querying Servers, Usage -@comment node-name, next, previous, up -@section Query Form - -The simplest way to query your directory server is to use the query -form. You display the query form with the @samp{Query with Form} menu -item or by invoking the command @kbd{M-x eudc-query-form}. The attribute -names presented in this form are defined by the -@code{eudc-query-form-attributes} variable (unless a non-@code{nil} -argument is supplied to @code{eudc-query-form}). - -Since the different directory protocols to which EUDC interfaces may -use different names for equivalent attributes, EUDC defines its own set -of attribute names and a mapping between these names and their -protocol-specific equivalent through the variable -@code{eudc-protocol-attributes-translation-alist}. Names currently -defined by EUDC are @code{name}, @code{firstname}, @code{email} and -@code{phone}. - -@defvar eudc-query-form-attributes -@findex eudc-get-attribute-list -A list of attributes presented in the query form. Attribute names in -this list should be either EUDC attribute names or valid attribute -names. You can get a list of valid attribute names for the current -protocol with the @samp{List Valid Attribute Names} menu item or the -@kbd{M-x eudc-get-attribute-list} command. Defaults to @code{name}, -@code{email} and @code{phone}. -@end defvar - -@deffn Command eudc-query-form get-fields-from-server -Display a form to query the directory server. If given a non-@code{nil} -argument the function first queries the server for the existing fields -and displays a corresponding form. Not all protocols may support a -non-@code{nil} argument here. -@end deffn - -Since the names of the fields may not be explicit enough or adapted to -be directly displayed as prompt strings in the form, the variable -@code{eudc-user-attribute-names-alist} lets you define more explicit -names for directory attribute names. This variable is ignored if -@code{eudc-use-raw-directory-names} is non-@code{nil}. - -@defvar eudc-user-attribute-names-alist -This is an alist of user-defined names for the directory attributes used in -query/response forms. Prompt strings for attributes that are not in this -alist are derived by splitting the attribute name at underscores and -capitalizing the individual words. -@end defvar - -@defvar eudc-use-raw-directory-names -If non-@code{nil}, use attributes names as defined in the directory. -Otherwise, directory query/response forms display the user attribute -names defined in @code{eudc-user-attribute-names-alist}. -@end defvar - -@node Display of Query Results, Inline Query Expansion, Query Form, Usage -@comment node-name, next, previous, up -@section Display of Query Results - -Upon successful completion of a form query, EUDC will display a buffer -containing the results of the query. - -The fields that are returned for each record -are controlled by @code{eudc-default-return-attributes} (@pxref{Return -Attributes}). - -The display of each individual field can be performed by an arbitrary -function which allows specific processing for binary values, such as -images or audio samples, as well as values with semantics, such as -URLs. - -@defvar eudc-attribute-display-method-alist -An alist specifying methods to display attribute values. Each member of -the list is of the form @code{(@var{name} . @var{func})} where -@var{name} is a lowercased string naming a directory attribute -(translated according to @code{eudc-user-attribute-names-alist} if -@code{eudc-use-raw-directory-names} is non-@code{nil}) and @var{func} a -function that will be passed the corresponding attribute values for -display. -@end defvar - -This variable has protocol-local definitions (see @pxref{Server/Protocol -Locals}). For instance, it is defined as follows for LDAP: - -@lisp -(eudc-protocol-set 'eudc-attribute-display-method-alist - '(("jpegphoto" . eudc-display-jpeg-inline) - ("labeledurl" . eudc-display-url) - ("audio" . eudc-display-sound) - ("labeledurl" . eudc-display-url) - ("url" . eudc-display-url)) - 'ldap) -@end lisp - -EUDC provides a set of built-in functions to display binary value types: - -@defun eudc-display-generic-binary data -Display a button for unidentified binary @var{data}. -@end defun - -@defun eudc-display-url url -Display URL and make it clickable. -@end defun - -@defun eudc-display-sound data -Display a button to play the sound @var{data}. -@end defun - -@defun eudc-display-jpeg-inline data -Display the JPEG @var{data} inline at point if possible. -@end defun - -@defun eudc-display-jpeg-as-button data -Display a button for the JPEG @var{data}. -@end defun - -Right-clicking on a binary value button pops up a contextual menu with -options to process the value. Among these are saving the attribute -value to a file or sending it to an external viewer command. External -viewers should expect the value on their standard input and should -display it or perform arbitrary processing on it. Messages sent to -standard output are discarded. External viewers are listed in the -variable @code{eudc-external-viewers} which you can customize. - -@defvar eudc-external-viewers -This is a list of viewer program specifications. Each specification is -a list whose first element is a string naming the viewer for unique -identification, the second element is the executable program which -should be invoked and the following elements are arguments that should -be passed to the program. -@end defvar - - -@node Inline Query Expansion, The Server Hotlist, Display of Query Results, Usage -@comment node-name, next, previous, up -@section Inline Query Expansion - -Inline query expansion is a powerful method to get completion from your -directory server. The most common usage is for expanding names to email -addresses in mail message buffers. The expansion is performed by the -command @kbd{M-x eudc-expand-inline} which is available from the -@samp{Expand Inline Query} menu item but can also be conveniently -bound to a key shortcut (@pxref{Installation}). The operation is -controlled by the variables @code{eudc-inline-expansion-format}, -@code{eudc-inline-query-format}, -@code{eudc-expanding-overwrites-query} and -@code{eudc-multiple-match-handling-method}. - -If the query fails for a server, other servers may be tried successively -until one of them finds a match (@pxref{Multi-server Queries}). - -@deffn Command eudc-expand-inline replace-p -Query the server and expand the query string before point. The query -string consists of the buffer substring from the point back to the -preceding comma, colon or beginning of -line. @code{eudc-inline-query-format} controls how individual words -are mapped onto directory attribute names. After querying the server -for the given string, the expansion specified by -@code{eudc-inline-expansion-format} is inserted in the buffer at -point. If @var{replace-p} is @code{t} then this expansion replaces the -query string in the buffer. If @code{eudc-expanding-overwrites-query} -is non-@code{nil} then the meaning of @var{replace-p} is negated. -@end deffn - -@defvar eudc-inline-query-format -Format of an inline expansion query. -This is actually a list of @var{format}s. A @var{format} is a list of -one or more EUDC attribute names. A @var{format} applies if it contains -as many attributes as individual words in the inline query string. If -several @var{format}s apply then they are tried in order until a match -is found. If @code{nil} all the words will be mapped onto the default -server/protocol attribute name (generally @code{name}). - -For instance, use the following -@lisp -(setq eudc-inline-query-format '((name) - (firstname) - (firstname name))) -@end lisp -@noindent -to indicate that single word expansion queries are to be considered as -surnames and if no match is found then they should be tried as first -names. Inline queries consisting of two words are considered as -consisting of a first name followed by a surname. If the query consists -of more than two words, then the first one is considered as the first -name and the remaining words are all considered as surname constituents. - -@var{format}s are in fact not limited to EUDC attribute names, you can -use server or protocol specific names in them. It may be safer if you -do so, to set the variable @code{eudc-inline-query-format} in a protocol -or server local fashion (see @pxref{Server/Protocol Locals}). - -For instance you could use the following to match up to three words -against the @code{cn} attribute of LDAP servers: -@lisp -(eudc-protocol-set 'eudc-inline-query-format - '((cn) - (cn cn) - (cn cn cn)) - 'ldap) -@end lisp -@end defvar - -@defvar eudc-inline-expansion-format -This variable lets you control exactly what is inserted into the buffer -upon an inline expansion request. It is a list whose first element is a -string passed to @code{format}. Remaining elements are symbols -corresponding to directory attribute names. The corresponding attribute -values are passed as additional arguments to @code{format}. Default is -@code{("%s" email)} but you may want to consider a value like @code{("%s -<%s>" name email)} -@end defvar - -@defvar eudc-multiple-match-handling-method -This variable controls what to do when multiple entries match a query -for an inline expansion. Possible values are: -@table @code -@item first -The first match is considered as being the only one, the others are -discarded. -@item select -A selection buffer pops up where you can choose a particular match. This -is the default value of the variable. -@item all -The expansion uses all records successively -@item abort -An error is signaled. The expansion aborts. -@end table - -Default is @code{select} -@end defvar - - - -@node The Server Hotlist, Multi-server Queries, Inline Query Expansion, Usage -@comment node-name, next, previous, up -@section The Server Hotlist - -EUDC lets you maintain a list of frequently used servers so that you -can easily switch from one to another. This hotlist appears in the -@samp{Server} submenu. You select a server in this list by clicking on -its name. You can add the current server to the list with the command -@kbd{M-x eudc-bookmark-current-server}. The list is contained in the variable -@code{eudc-server-hotlist} which is stored in and retrieved from the file -designated by @code{eudc-options-file}. EUDC also provides a facility to -edit the hotlist interactively (@pxref{The Hotlist Edit Buffer}). - -The hotlist is also used to make queries on multiple servers -successively (@pxref{Multi-server Queries}). The order in which the -servers are tried is the order they appear in the hotlist, therefore it -is important to sort the hotlist appropriately. - -@deffn Command eudc-bookmark-server server -Add @var{server} to the hotlist of servers -@end deffn - -@deffn Command eudc-bookmark-current-server -Add the current server to the hotlist of servers -@end deffn - -@defvar eudc-options-file -The name of a file where EUDC stores its internal variables -(the hotlist and the current server). EUDC will try to load -that file upon initialization so, if you choose a file name -different from the defaults @file{~/.eudc-options}, be sure to set this -variable to the appropriate value @emph{before} EUDC is itself -loaded. -@end defvar - -@menu -* The Hotlist Edit Buffer:: An interactive hotlist editing facility -@end menu - -@node The Hotlist Edit Buffer, , The Server Hotlist, The Server Hotlist -@comment node-name, next, previous, up -@subsection The Hotlist Edit Buffer - -The hotlist edit buffer offers a means to manage a list of frequently -used servers. Commands are available in the context pop-up menu -generally bound to the right mouse button. Those commands also have -equivalent key bindings. - -@deffn Command eudc-hotlist-add-server -Bound to @kbd{a}. -Add a new server to the hotlist on the line after point -@end deffn - -@deffn Command eudc-hotlist-delete-server -Bound to @kbd{d}. -Delete the server on the line point is on -@end deffn - -@deffn Command eudc-hotlist-select-server -Bound to @kbd{s}. -Select the server the point is on as the current directory server for -the next queries -@end deffn - -@deffn Command eudc-hotlist-transpose-servers -Bound to @kbd{t}. -Bubble up the server the point is on to the top of the list -@end deffn - -@deffn Command eudc-hotlist-quit-edit -Bound to @kbd{q}. -Save the changes and quit the hotlist edit buffer. Use @kbd{x} or -@kbd{M-x kill-buffer} to exit without saving. -@end deffn - - -@node Multi-server Queries, Creating BBDB Records, The Server Hotlist, Usage -@comment node-name, next, previous, up -@section Multi-server Queries - -When using inline query expansion (@pxref{Inline Query Expansion}), EUDC -can try to query successively a sequence of directory servers until one -of them successfully finds a match for the query. - -@defvar eudc-inline-expansion-servers -This variable controls which servers are tried and in which order when -trying to perform an inline query. Possible values are: -@table @code -@item current-server -Only the current directory server is tried -@item hotlist -The servers in the hotlist are tried in order until one finds a match -for the query or `eudc-max-servers-to-query' is reached -@item server-then-hotlist -The current server then the servers in the hotlist are tried in the -order they appear in the hotlist until one of them finds a match or -`eudc-max-servers-to-query' is reached. This is the default. -@end table -@end defvar - -@defvar eudc-max-servers-to-query -This variable indicates the maximum number of servers to query when -performing a multi-server query. The default, @code{nil}, indicates -that all available servers should be tried. -@end defvar - - - -@node Creating BBDB Records, Server/Protocol Locals, Multi-server Queries, Usage -@comment node-name, next, previous, up -@section Creating BBDB Records - -@findex eudc-insert-record-at-point-into-bbdb -@findex eudc-try-bbdb-insert -With EUDC, you can automatically create BBDB records -(@pxref{Top,,BBDB,bbdb,BBDB Manual}) from records you get from a -directory server. You do this by moving point to the appropriate -record in a query result display buffer and invoking the command -@kbd{M-x eudc-insert-record-at-point-into-bbdb} with the -keyboard binding @kbd{b}@footnote{This key binding does not actually -call @code{eudc-insert-record-at-point-into-bbdb} but uses -@code{eudc-try-bbdb-insert} instead.}, or with the menu. EUDC -cannot update an existing BBDB record and will signal an error if you -try to insert a record matching an existing one. - -@findex eudc-batch-export-records-to-bbdb -It is also possible to export to BBDB the whole batch of records -contained in the directory query result with the command -@kbd{M-x eudc-batch-export-records-to-bbdb}. - -Because directory systems may not enforce a strict record format, local -server installations may use different attribute names and have -different ways to organize the information. Furthermore BBDB has its own -record structure. For these reasons converting a record from its -external directory format to the BBDB format is a highly customizable -process. - -@defvar eudc-bbdb-conversion-alist -The value of this variable should be a symbol naming an alist defining a -mapping between BBDB field names onto directory attribute names records. -This is a protocol-local variable and is initialized upon protocol -switch (@pxref{Server/Protocol Locals}). The alist is made of cells of the -form @code{(@var{bbdb-field} . @var{spec-or-list})}. -@var{bbdb-field} is the name of a field -that must be defined in your BBDB environment (standard field names are -@code{name}, @code{company}, @code{net}, @code{phone}, @code{address} -and @code{notes}). -@var{spec-or-list} is either a single mapping specification or a list of -mapping specifications. Lists of mapping specifications are valid for -the @code{phone} and @code{address} BBDB fields only. @var{spec}s are -actually s-expressions which are evaluated as follows: - -@table @asis -@item a string -evaluates to itself -@item a symbol -evaluates to the symbol value. Symbols corresponding to directory -attribute names present in the record evaluate to the value of the field -in the record -@item a form -is evaluated as a function. The argument list may contain attribute -names which evaluate to the corresponding values in the record. The form -evaluation should return something appropriate for the particular -@var{bbdb-field} (see @code{bbdb-create-internal}). -@code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as -convenience functions to parse phones and addresses. -@end table -@end defvar - -The default value of the PH-specific value of that variable is -@code{eudc-ph-bbdb-conversion-alist}: - -@lisp -((name . name) - (net . email) - (address . (eudc-bbdbify-address address "Address")) - (phone . ((eudc-bbdbify-phone phone "Phone") - (eudc-bbdbify-phone office_phone "Office Phone")))) -@end lisp - -This means that: - -@itemize @bullet -@item -the @code{name} field of the BBDB record gets its value -from the @code{name} attribute of the directory record -@item -the @code{net} field of the BBDB record gets its value -from the @code{email} attribute of the directory record -@item -the @code{address} field of the BBDB record is obtained by parsing the -@code{address} attribute of the directory record with the function -@code{eudc-bbdbify-address} -@item -two @code{phone} fields are created (when possible) in the BBDB record. -The first one has @cite{Phone} for location and its value is obtained by -parsing the @code{phone} attribute of the PH/QI record with the function -@code{eudc-bbdbify-phone}. The second one has @cite{Office Phone} for location -its value is obtained by parsing the @code{office_phone} attribute of the -PH/QI record with the function @code{eudc-bbdbify-phone}. -@end itemize - -@defun eudc-bbdbify-phone phone location -This is a convenience function provided for use in -@code{eudc-bbdb-conversion-alist}. It parses @var{phone} into a vector -compatible with @code{bbdb-create-internal}. @var{phone} is either a string -supposedly containing a phone number or a list of such strings which are -concatenated. @var{location} is used as the phone location for BBDB. -@end defun - -@defun eudc-bbdbify-address addr location -This is a convenience function provided for use in -@code{eudc-bbdb-conversion-alist}. It parses @var{addr} into a vector -compatible with @code{bbdb-create-internal}. @var{addr} should be an -address string of no more than four lines or a list of lines. The last -line is searched for the zip code, city and state name. @var{location} -is used as the phone location for BBDB. -@end defun - -Note that only a subset of the attributes you selected with -@code{eudc-default-return-attributes} and that are actually displayed may -actually be inserted as part of the newly created BBDB record. - - -@node Server/Protocol Locals, , Creating BBDB Records, Usage -@comment node-name, next, previous, up -@section Server/Protocol Locals - -EUDC can be customized independently for each server or directory -protocol. All variables can be given local bindings that are activated -when a particular server and/or protocol becomes active. This is much -like buffer-local bindings but on a per server or per protocol basis. - -@menu -* Manipulating local bindings:: Functions to set and query local bindings -@end menu - -@node Manipulating local bindings, , Server/Protocol Locals, Server/Protocol Locals -@comment node-name, next, previous, up -@subsection Manipulating local bindings - -EUDC offers functions that let you set and query variables on a per -server or per protocol basis. - -The following predicates allow you to test the existence of -server/protocol local bindings for a particular variable. - -@defun eudc-server-local-variable-p var -Return non-@code{nil} if @var{var} has server-local bindings -@end defun - -@defun eudc-protocol-local-variable-p var -Return non-@code{nil} if @var{var} has protocol-local bindings -@end defun - -The following functions allow you to set the value of a variable with -various degrees of locality. - -@defun eudc-default-set var val -Set the EUDC default value of @var{var} to @var{val}. -The current binding of @var{var} (if local to the current server or -protocol) is not changed. -@end defun - -@defun eudc-protocol-set var val &optional protocol -Set the binding of @var{var} local to @var{protocol} to @var{val}. If -omitted, @var{protocol} defaults to the current value of -@code{eudc-protocol}. The current binding of @var{var} is changed only -if @var{protocol} is omitted. -@end defun - -@defun eudc-server-set var val &optional server -Set the binding of @var{var} local to @var{server} to @var{val}. If -omitted, @var{server} defaults to the current value of -@code{eudc-server}. The current binding of @var{var} is changed only if -@var{server} is omitted. -@end defun - -@defun eudc-set var val -Set the most local (server, protocol or default) binding of @var{var} to -@var{val}. The current binding of @var{var} is also set to @var{val}. -@end defun - -The following variables allow you to query the various bindings of a -variable (local or non-local). - -@defun eudc-variable-default-value var -Return the default binding of @var{var} (outside of a particular server -or protocol local binding). -Return @code{unbound} if @var{var} has no EUDC default value. -@end defun - -@defun eudc-variable-protocol-value var &optional protocol -Return the value of @var{var} local to @var{protocol}. Return -@code{unbound} if @var{var} has no value local to @var{protocol}. -@var{protocol} defaults to @code{eudc-protocol}. -@end defun - -@defun eudc-variable-server-value var [server] -Return the value of @var{var} local to @var{server}. -Return @code{unbound} if @var{var} has no value local to @var{server}. -@var{server} defaults to @code{eudc-server}. -@end defun - -Changing a protocol-local or server-local value of a variable has no -effect on its current value. The following command is used to -synchronize the current values of variables with their local values -given the current @code{eudc-server} and @code{eudc-protocol}: - -@defun eudc-update-local-variables -Update all EUDC variables according to their local settings. -@end defun - - - -@node Credits, GNU Free Documentation License, Usage, Top -@comment node-name, next, previous, up -@chapter Credits - -EUDC was written by Oscar Figueiredo based on @file{ph.el} by the -same author. - -Thanks to Soren Dayton for his suggestions, his enthusiasm and his help -in testing and proofreading the code and docs of @file{ph.el}. - -@node GNU Free Documentation License, Command and Function Index, Credits, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Command and Function Index, Variables Index, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Command and Function Index - -@printindex fn - -@node Variables Index, , Command and Function Index, Top -@comment node-name, next, previous, up -@unnumbered Variables Index - -@printindex vr - -@bye diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi deleted file mode 100644 index 28fb7864f06..00000000000 --- a/doc/misc/flymake.texi +++ /dev/null @@ -1,759 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename ../../info/flymake -@set VERSION 0.3 -@set UPDATED April 2004 -@settitle GNU Flymake @value{VERSION} -@syncodeindex pg cp -@comment %**end of header - -@copying -This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}), -which is a universal on-the-fly syntax checker for GNU Emacs. - -Copyright @copyright{} 2004-2012 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Flymake: (flymake). A universal on-the-fly syntax checker. -@end direntry - -@titlepage -@title GNU Flymake -@subtitle for version @value{VERSION}, @value{UPDATED} -@author Pavel Kobiakov(@email{pk_at_work@@yahoo.com}) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top GNU Flymake -@insertcopying -@end ifnottex - -@menu -* Overview of Flymake:: -* Installing Flymake:: -* Using Flymake:: -* Configuring Flymake:: -* Flymake Implementation:: -* GNU Free Documentation License:: -* Index:: -@end menu - -@node Overview of Flymake -@chapter Overview -@cindex Overview of Flymake - -Flymake is a universal on-the-fly syntax checker implemented as an -Emacs minor mode. Flymake runs the pre-configured syntax check tool -(compiler for C++ files, @code{perl} for perl files, etc.) in the -background, passing it a temporary copy of the current buffer, and -parses the output for known error/warning message patterns. Flymake -then highlights erroneous lines (i.e. lines for which at least one -error or warning has been reported by the syntax check tool), and -displays an overall buffer status in the mode line. Status information -displayed by Flymake contains total number of errors and warnings -reported for the buffer during the last syntax check. - -@code{flymake-goto-next-error} and @code{flymake-goto-prev-error} -functions allow for easy navigation to the next/previous erroneous -line, respectively. - -Calling @code{flymake-display-err-menu-for-current-line} will popup a -menu containing error messages reported by the syntax check tool for -the current line. Errors/warnings belonging to another file, such as a -@code{.h} header file included by a @code{.c} file, are shown in the -current buffer as belonging to the first line. Menu items for such -messages also contain a filename and a line number. Selecting such a -menu item will automatically open the file and jump to the line with -error. - -Syntax check is done 'on-the-fly'. It is started whenever - -@itemize @bullet -@item buffer is loaded -@item a newline character is added to the buffer -@item some changes were made to the buffer more than @code{0.5} seconds ago (the -delay is configurable). -@end itemize - -Flymake is a universal syntax checker in the sense that it's easily -extended to support new syntax check tools and error message -patterns. @xref{Configuring Flymake}. - -@node Installing Flymake -@chapter Installing -@cindex Installing Flymake - - -Flymake is packaged in a single file, @code{flymake.el}. - -To install/update Flymake, place @code{flymake.el} to a directory -somewhere on Emacs load path. You might also want to byte-compile -@code{flymake.el} to improve performance. - -Also, place the following line in the @code{.emacs} file. - -@lisp -(require 'flymake) -@end lisp - -You might also map the most frequently used Flymake functions, such as -@code{flymake-goto-next-error}, to some keyboard shortcuts: - -@lisp -(global-set-key [f3] 'flymake-display-err-menu-for-current-line) -(global-set-key [f4] 'flymake-goto-next-error) -@end lisp - -@node Using Flymake -@chapter Using Flymake -@cindex Using Flymake - -@menu -* Flymake mode:: -* Running the syntax check:: -* Navigating to error lines:: -* Viewing error messages:: -* Syntax check statuses:: -* Troubleshooting:: -@end menu - -@node Flymake mode -@section Flymake mode -@cindex flymake-mode - -Flymake is an Emacs minor mode. To use Flymake, you -must first activate @code{flymake-mode} by using the -@code{flymake-mode} function. - -Instead of manually activating @code{flymake-mode}, you can configure -Flymake to automatically enable @code{flymake-mode} upon opening any -file for which syntax check is possible. To do so, place the following -line in @code{.emacs}: - -@lisp -(add-hook 'find-file-hook 'flymake-find-file-hook) -@end lisp - -@node Running the syntax check -@section Running the syntax check -@cindex Manually starting the syntax check - -When @code{flymake-mode} is active, syntax check is started -automatically on any of the three conditions mentioned above. Syntax -check can also be started manually by using the -@code{flymake-start-syntax-check-for-current-buffer} function. This -can be used, for example, when changes were made to some other buffer -affecting the current buffer. - -@node Navigating to error lines -@section Navigating to error lines -@cindex Navigating to error lines - -After syntax check is completed, lines for which at least one error or -warning has been reported are highlighted, and total number of errors -and warning is shown in the mode line. Use the following functions to -navigate the highlighted lines. - -@multitable @columnfractions 0.25 0.75 - -@item @code{flymake-goto-next-error} -@tab Moves point to the next erroneous line, if any. - -@item @code{flymake-goto-prev-error} -@tab Moves point to the previous erroneous line. - -@end multitable - -These functions treat erroneous lines as a linked list. Therefore, -@code{flymake-goto-next-error} will go to the first erroneous line -when invoked in the end of the buffer. - -@node Viewing error messages -@section Viewing error messages -@cindex Viewing error messages - -To view error messages belonging to the current line, use the -@code{flymake-display-err-menu-for-current-line} function. If there's -at least one error or warning reported for the current line, this -function will display a popup menu with error/warning texts. -Selecting the menu item whose error belongs to another file brings -forward that file with the help of the -@code{flymake-goto-file-and-line} function. - -@node Syntax check statuses -@section Syntax check statuses -@cindex Syntax check statuses - -After syntax check is finished, its status is displayed in the mode line. -The following statuses are defined. - -@multitable @columnfractions 0.25 0.75 -@item Flymake* or Flymake:E/W* -@tab Flymake is currently running. For the second case, E/W contains the - error and warning count for the previous run. - -@item Flymake -@tab Syntax check is not running. Usually this means syntax check was - successfully passed (no errors, no warnings). Other possibilities are: - syntax check was killed as a result of executing - @code{flymake-compile}, or syntax check cannot start as compilation - is currently in progress. - -@item Flymake:E/W -@tab Number of errors/warnings found by the syntax check process. - -@item Flymake:! -@tab Flymake was unable to find master file for the current buffer. -@end multitable - -The following errors cause a warning message and switch flymake mode -OFF for the buffer. - -@multitable @columnfractions 0.25 0.75 -@item CFGERR -@tab Syntax check process returned nonzero exit code, but no - errors/warnings were reported. This indicates a possible configuration - error (for example, no suitable error message patterns for the - syntax check tool). - -@item NOMASTER -@tab Flymake was unable to find master file for the current buffer. - -@item NOMK -@tab Flymake was unable to find a suitable buildfile for the current buffer. - -@item PROCERR -@tab Flymake was unable to launch a syntax check process. -@end multitable - - -@node Troubleshooting -@section Troubleshooting -@cindex Logging -@cindex Troubleshooting - -Flymake uses a simple logging facility for indicating important points -in the control flow. The logging facility sends logging messages to -the @code{*Messages*} buffer. The information logged can be used for -resolving various problems related to Flymake. - -Logging output is controlled by the @code{flymake-log-level} -variable. @code{3} is the most verbose level, and @code{-1} switches -logging off. - -@node Configuring Flymake -@chapter Configuring and Extending Flymake -@cindex Configuring and Extending Flymake - -@menu -* Customizable variables:: -* Adding support for a new syntax check tool:: -@end menu - -Flymake was designed to be easily extended for supporting new syntax -check tools and error message patterns. - -@node Customizable variables -@section Customizable variables -@cindex Customizable variables - -This section summarizes variables used for Flymake -configuration. - -@table @code -@item flymake-log-level -Controls logging output, see @ref{Troubleshooting}. - -@item flymake-allowed-file-name-masks -A list of @code{(filename-regexp, init-function, cleanup-function -getfname-function)} for configuring syntax check tools. @xref{Adding -support for a new syntax check tool}. - -@item flymake-buildfile-dirs -A list of directories (relative paths) for searching a -buildfile. @xref{Locating the buildfile}. - -@item flymake-master-file-dirs -A list of directories for searching a master file. @xref{Locating a -master file}. - -@item flymake-get-project-include-dirs-function -A function used for obtaining a list of project include dirs (C/C++ -specific). @xref{Getting the include directories}. - -@item flymake-master-file-count-limit -@itemx flymake-check-file-limit -Used when looking for a master file. @xref{Locating a master file}. - -@item flymake-err-line-patterns -Patterns for error/warning messages in the form @code{(regexp file-idx -line-idx col-idx err-text-idx)}. @xref{Parsing the output}. - -@item flymake-compilation-prevents-syntax-check -A flag indicating whether compilation and syntax check of the same -file cannot be run simultaneously. - -@item flymake-no-changes-timeout -If any changes are made to the buffer, syntax check is automatically -started after @code{flymake-no-changes-timeout} seconds. - -@item flymake-gui-warnings-enabled -A boolean flag indicating whether Flymake will show message boxes for -non-recoverable errors. If @code{flymake-gui-warnings-enabled} is -@code{nil}, these errors will only be logged to the @code{*Messages*} -buffer. - -@item flymake-start-syntax-check-on-newline -A boolean flag indicating whether to start syntax check after a -newline character is added to the buffer. - -@item flymake-errline -A custom face for highlighting lines for which at least one error has -been reported. - -@item flymake-warnline -A custom face for highlighting lines for which at least one warning -and no errors have been reported. - -@end table - -@node Adding support for a new syntax check tool -@section Adding support for a new syntax check tool -@cindex Adding support for a new syntax check tool - -@menu -* Example -- Configuring a tool called directly:: -* Example -- Configuring a tool called via make:: -@end menu - -Syntax check tools are configured using the -@code{flymake-allowed-file-name-masks} list. Each item of this list -has the following format: - -@lisp -(filename-regexp, init-function, cleanup-function, getfname-function) -@end lisp - -@table @code -@item filename-regexp -This field is used as a key for locating init/cleanup/getfname -functions for the buffer. Items in -@code{flymake-allowed-file-name-masks} are searched sequentially. The -first item with @code{filename-regexp} matching buffer filename is -selected. If no match is found, @code{flymake-mode} is switched off. - -@item init-function -@code{init-function} is required to initialize the syntax check, -usually by creating a temporary copy of the buffer contents. The -function must return @code{(list cmd-name arg-list)}. If -@code{init-function} returns null, syntax check is aborted, by -@code{flymake-mode} is not switched off. - -@item cleanup-function -@code{cleanup-function} is called after the syntax check process is -complete and should take care of proper deinitialization, which is -usually deleting a temporary copy created by the @code{init-function}. - -@item getfname-function -This function is used for translating filenames reported by the syntax -check tool into ``real'' filenames. Filenames reported by the tool -will be different from the real ones, as actually the tool works with -the temporary copy. In most cases, the default implementation -provided by Flymake, @code{flymake-get-real-file-name}, can be used as -@code{getfname-function}. - -@end table - -To add support for a new syntax check tool, write corresponding -@code{init-function}, and, optionally @code{cleanup-function} and -@code{getfname-function}. If the format of error messages reported by -the new tool is not yet supported by Flymake, add a new entry to -the @code{flymake-err-line-patterns} list. - -The following sections contain some examples of configuring Flymake -support for various syntax check tools. - -@node Example -- Configuring a tool called directly -@subsection Example -- Configuring a tool called directly -@cindex Adding support for perl - -In this example, we will add support for @code{perl} as a syntax check -tool. @code{perl} supports the @code{-c} option which does syntax -checking. - -First, we write the @code{init-function}: - -@lisp -(defun flymake-perl-init () - (let* ((temp-file (flymake-init-create-temp-buffer-copy - 'flymake-create-temp-inplace)) - (local-file (file-relative-name - temp-file - (file-name-directory buffer-file-name)))) - (list "perl" (list "-wc " local-file)))) -@end lisp - -@code{flymake-perl-init} creates a temporary copy of the buffer -contents with the help of -@code{flymake-init-create-temp-buffer-copy}, and builds an appropriate -command line. - -Next, we add a new entry to the -@code{flymake-allowed-file-name-masks}: - -@lisp -(setq flymake-allowed-file-name-masks - (cons '(".+\\.pl$" - flymake-perl-init - flymake-simple-cleanup - flymake-get-real-file-name) - flymake-allowed-file-name-masks)) -@end lisp - -Note that we use standard @code{cleanup-function} and -@code{getfname-function}. - -Finally, we add an entry to @code{flymake-err-line-patterns}: - -@lisp -(setq flymake-err-line-patterns - (cons '("\\(.*\\) at \\([^ \n]+\\) line \\([0-9]+\\)[,.\n]" - 2 3 nil 1) - flymake-err-line-patterns)) -@end lisp - -@node Example -- Configuring a tool called via make -@subsection Example -- Configuring a tool called via make -@cindex Adding support for C (gcc+make) - -In this example we will add support for C files syntax checked by -@command{gcc} called via @command{make}. - -We're not required to write any new functions, as Flymake already has -functions for @command{make}. We just add a new entry to the -@code{flymake-allowed-file-name-masks}: - -@lisp -(setq flymake-allowed-file-name-masks - (cons '(".+\\.c$" - flymake-simple-make-init - flymake-simple-cleanup - flymake-get-real-file-name) - flymake-allowed-file-name-masks)) -@end lisp - -@code{flymake-simple-make-init} builds the following @command{make} -command line: - -@lisp -(list "make" - (list "-s" "-C" - base-dir - (concat "CHK_SOURCES=" source) - "SYNTAX_CHECK_MODE=1" - "check-syntax")) -@end lisp - -@code{base-dir} is a directory containing @code{Makefile}, see @ref{Locating the buildfile}. - -Thus, @code{Makefile} must contain the @code{check-syntax} target. In -our case this target might look like this: - -@verbatim -check-syntax: - gcc -o /dev/null -S ${CHK_SOURCES} -@end verbatim - -@noindent -The format of error messages reported by @command{gcc} is already -supported by Flymake, so we don't have to add a new entry to -@code{flymake-err-line-patterns}. Note that if you are using -Automake, you may want to replace @code{gcc} with the standard -Automake variable @code{COMPILE}: - -@verbatim -check-syntax: - $(COMPILE) -o /dev/null -S ${CHK_SOURCES} -@end verbatim - -@node Flymake Implementation -@chapter Flymake Implementation -@cindex Implementation details - -@menu -* Determining whether syntax check is possible:: -* Making a temporary copy:: -* Locating a master file:: -* Getting the include directories:: -* Locating the buildfile:: -* Starting the syntax check process:: -* Parsing the output:: -* Highlighting erroneous lines:: -* Interaction with other modes:: -@end menu - -Syntax check is started by calling @code{flymake-start-syntax-check-for-current-buffer}. -Flymake first determines whether it is able to do syntax -check. It then saves a copy of the buffer in a temporary file in the -buffer's directory (or in the system temp directory -- for java -files), creates a syntax check command and launches a process with -this command. The output is parsed using a list of error message patterns, -and error information (file name, line number, type and text) is -saved. After the process has finished, Flymake highlights erroneous -lines in the buffer using the accumulated error information. - -@node Determining whether syntax check is possible -@section Determining whether syntax check is possible -@cindex Syntax check models -@cindex Master file - -Syntax check is considered possible if there's an entry in -@code{flymake-allowed-file-name-masks} matching buffer's filename and -its @code{init-function} returns non-@code{nil} value. - -Two syntax check modes are distinguished: - -@enumerate - -@item -Buffer can be syntax checked in a standalone fashion, that is, the -file (its temporary copy, in fact) can be passed over to the compiler to -do the syntax check. Examples are C/C++ (.c, .cpp) and Java (.java) -sources. - -@item -Buffer can be syntax checked, but additional file, called master file, -is required to perform this operation. A master file is a file that -includes the current file, so that running a syntax check tool on it -will also check syntax in the current file. Examples are C/C++ (.h, -.hpp) headers. - -@end enumerate - -These modes are handled inside init/cleanup/getfname functions, see -@ref{Adding support for a new syntax check tool}. - -Flymake contains implementations of all functionality required to -support different syntax check modes described above (making temporary -copies, finding master files, etc.), as well as some tool-specific -(routines for Make, Ant, etc.) code. - - -@node Making a temporary copy -@section Making a temporary copy -@cindex Temporary copy of the buffer -@cindex Master file - -After the possibility of the syntax check has been determined, a -temporary copy of the current buffer is made so that the most recent -unsaved changes could be seen by the syntax check tool. Making a copy -is quite straightforward in a standalone case (mode @code{1}), as it's -just saving buffer contents to a temporary file. - -Things get trickier, however, when master file is involved, as it -requires to - -@itemize @bullet -@item locate a master file -@item patch it to include the current file using its new (temporary) -name. -@end itemize - -Locating a master file is discussed in the following section. - -Patching just changes all appropriate lines of the master file so that they -use the new (temporary) name of the current file. For example, suppose current -file name is @code{file.h}, the master file is @code{file.cpp}, and -it includes current file via @code{#include "file.h"}. Current file's copy -is saved to file @code{file_flymake.h}, so the include line must be -changed to @code{#include "file_flymake.h"}. Finally, patched master file -is saved to @code{file_flymake_master.cpp}, and the last one is passed to -the syntax check tool. - -@node Locating a master file -@section Locating a master file -@cindex Master file - -Master file is located in two steps. - -First, a list of possible master files is built. A simple name -matching is used to find the files. For a C++ header @code{file.h}, -Flymake searches for all @code{.cpp} files in the directories whose relative paths are -stored in a customizable variable @code{flymake-master-file-dirs}, which -usually contains something like @code{("." "./src")}. No more than -@code{flymake-master-file-count-limit} entries is added to the master file -list. The list is then sorted to move files with names @code{file.cpp} to -the top. - -Next, each master file in a list is checked to contain the appropriate -include directives. No more than @code{flymake-check-file-limit} of each -file are parsed. - -For @code{file.h}, the include directives to look for are -@code{#include "file.h"}, @code{#include "../file.h"}, etc. Each -include is checked against a list of include directories -(see @ref{Getting the include directories}) to be sure it points to the -correct @code{file.h}. - -First matching master file found stops the search. The master file is then -patched and saved to disk. In case no master file is found, syntax check is -aborted, and corresponding status (!) is reported in the mode line. - -@node Getting the include directories -@section Getting the include directories -@cindex Include directories (C/C++ specific) - -Two sets of include directories are distinguished: system include directories -and project include directories. The former is just the contents of the -@code{INCLUDE} environment variable. The latter is not so easy to obtain, -and the way it can be obtained can vary greatly for different projects. -Therefore, a customizable variable -@code{flymake-get-project-include-dirs-function} is used to provide the -way to implement the desired behavior. - -The default implementation, @code{flymake-get-project-include-dirs-imp}, -uses a @command{make} call. This requires a correct base directory, that is, a -directory containing a correct @file{Makefile}, to be determined. - -As obtaining the project include directories might be a costly operation, its -return value is cached in the hash table. The cache is cleared in the beginning -of every syntax check attempt. - -@node Locating the buildfile -@section Locating the buildfile -@cindex Locating the buildfile -@cindex buildfile, locating -@cindex Makefile, locating - -Flymake can be configured to use different tools for performing syntax -checks. For example, it can use direct compiler call to syntax check a perl -script or a call to @command{make} for a more complicated case of a -@code{C/C++} source. The general idea is that simple files, like perl -scripts and html pages, can be checked by directly invoking a -corresponding tool. Files that are usually more complex and generally -used as part of larger projects, might require non-trivial options to -be passed to the syntax check tool, like include directories for -C++. The latter files are syntax checked using some build tool, like -Make or Ant. - -All Make configuration data is usually stored in a file called -@code{Makefile}. To allow for future extensions, flymake uses a notion of -buildfile to reference the 'project configuration' file. - -Special function, @code{flymake-find-buildfile} is provided for locating buildfiles. -Searching for a buildfile is done in a manner similar to that of searching -for possible master files. A customizable variable -@code{flymake-buildfile-dirs} holds a list of relative paths to the -buildfile. They are checked sequentially until a buildfile is found. In case -there's no build file, syntax check is aborted. - -Buildfile values are also cached. - -@node Starting the syntax check process -@section Starting the syntax check process -@cindex Syntax check process - -The command line (command name and the list of arguments) for launching a process is returned by the -initialization function. Flymake then just calls @code{start-process} -to start an asynchronous process and configures process filter and -sentinel which is used for processing the output of the syntax check -tool. - -@node Parsing the output -@section Parsing the output -@cindex Parsing the output - -The output generated by the syntax check tool is parsed in the process -filter/sentinel using the error message patterns stored in the -@code{flymake-err-line-patterns} variable. This variable contains a -list of items of the form @code{(regexp file-idx line-idx -err-text-idx)}, used to determine whether a particular line is an -error message and extract file name, line number and error text, -respectively. Error type (error/warning) is also guessed by matching -error text with the '@code{^[wW]arning}' pattern. Anything that was not -classified as a warning is considered an error. Type is then used to -sort error menu items, which shows error messages first. - -Flymake is also able to interpret error message patterns missing err-text-idx -information. This is done by merely taking the rest of the matched line -(@code{(substring line (match-end 0))}) as error text. This trick allows -to make use of a huge collection of error message line patterns from -@code{compile.el}. All these error patterns are appended to -the end of @code{flymake-err-line-patterns}. - -The error information obtained is saved in a buffer local -variable. The buffer for which the process output belongs is -determined from the process-id@w{}->@w{}buffer mapping updated -after every process launch/exit. - -@node Highlighting erroneous lines -@section Highlighting erroneous lines -@cindex Erroneous lines, faces - -Highlighting is implemented with overlays and happens in the process -sentinel, after calling the cleanup function. Two customizable faces -are used: @code{flymake-errline} and -@code{flymake-warnline}. Errors belonging outside the current -buffer are considered to belong to line 1 of the current buffer. - -@node Interaction with other modes -@section Interaction with other modes -@cindex Interaction with other modes -@cindex Interaction with compile mode - -The only mode flymake currently knows about is @code{compile}. - -Flymake can be configured to not start syntax check if it thinks the -compilation is in progress. The check is made by the -@code{flymake-compilation-is-running}, which tests the -@code{compilation-in-progress} variable. The reason why this might be -useful is saving CPU time in case both syntax check and compilation -are very CPU intensive. The original reason for adding this feature, -though, was working around a locking problem with MS Visual C++ compiler. - -Flymake also provides an alternative command for starting compilation, -@code{flymake-compile}: - -@lisp -(defun flymake-compile () - "Kill all flymake syntax checks then start compilation." - (interactive) - (flymake-stop-all-syntax-checks) - (call-interactively 'compile)) -@end lisp - -It just kills all the active syntax check processes before calling -@code{compile}. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index - -@printindex cp - -@bye diff --git a/doc/misc/forms.texi b/doc/misc/forms.texi deleted file mode 100644 index 34c418c14fd..00000000000 --- a/doc/misc/forms.texi +++ /dev/null @@ -1,977 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c documentation for forms-mode -@c Written by Johan Vromans, and edited by Richard Stallman - -@comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/forms -@settitle Forms Mode User's Manual -@syncodeindex vr cp -@syncodeindex fn cp -@syncodeindex ky cp -@iftex -@finalout -@setchapternewpage odd -@end iftex -@c @smallbook -@comment %**end of header (This is for running Texinfo on a region.) - -@copying -This file documents Forms mode, a form-editing major mode for GNU Emacs. - -Copyright @copyright{} 1989, 1997, 2001-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Forms: (forms). Emacs package for editing data bases - by filling in forms. -@end direntry - -@titlepage -@sp 6 -@center @titlefont{Forms Mode User's Manual} -@sp 4 -@center Forms-Mode version 2 -@sp 1 -@center for GNU Emacs 22.1 -@sp 1 -@center April 2007 -@sp 5 -@center Johan Vromans -@center @i{jvromans@@squirrel.nl} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Forms Mode - -Forms mode is an Emacs major mode for working with simple textual data -bases in a forms-oriented manner. In Forms mode, the information in -these files is presented in an Emacs window in a user-defined format, -one record at a time. The user can view records or modify their -contents. - -Forms mode is not a simple major mode, but requires two files to do its -job: a control file and a data file. The data file holds the -actual data to be presented. The control file describes -how to present it. - -@insertcopying - -@menu -* Forms Example:: An example: editing the password data base. -* Entering and Exiting Forms Mode:: - How to visit a file in Forms mode. -* Forms Commands:: Special commands to use while in Forms mode. -* Data File Format:: How to format the data file. -* Control File Format:: How to control forms mode. -* Format Description:: How to define the forms layout. -* Modifying Forms Contents:: How to modify. -* Miscellaneous:: Forms mode messages and other remarks. -* Error Messages:: List of error messages forms mode can produce. -* Long Example:: A more complex control file example. -* GNU Free Documentation License:: The license for this documentation. -* Credits:: Thanks everyone. -* Index:: Index to this manual. -@end menu -@end ifnottex - -@node Forms Example -@chapter Forms Example - -Let's illustrate Forms mode with an example. Suppose you are looking at -the @file{/etc/passwd} file, and the screen looks like this: - -@example -====== /etc/passwd ====== - -User : root Uid: 0 Gid: 1 - -Name : Super User - -Home : / - -Shell: /bin/sh -@end example - -As you can see, the familiar fields from the entry for the super user -are all there, but instead of being colon-separated on one single line, -they make up a forms. - -The contents of the forms consist of the contents of the fields of the -record (e.g. @samp{root}, @samp{0}, @samp{1}, @samp{Super User}) -interspersed with normal text (e.g @samp{User : }, @samp{Uid: }). - -If you modify the contents of the fields, Forms mode will analyze your -changes and update the file appropriately. You cannot modify the -interspersed explanatory text (unless you go to some trouble about it), -because that is marked read-only (@pxref{Text Properties,,, elisp, The -Emacs Lisp Reference Manual}). - -The Forms mode control file specifies the relationship between the -format of @file{/etc/passwd} and what appears on the screen in Forms -mode. @xref{Control File Format}. - -@node Entering and Exiting Forms Mode -@chapter Entering and Exiting Forms Mode - -@table @kbd -@findex forms-find-file -@item M-x forms-find-file @key{RET} @var{control-file} @key{RET} -Visit a database using Forms mode. Specify the name of the -@strong{control file}, not the data file! - -@findex forms-find-file-other-window -@item M-x forms-find-file-other-window @key{RET} @var{control-file} @key{RET} -Similar, but displays the file in another window. -@end table - -The command @code{forms-find-file} evaluates the file -@var{control-file}, and also visits it in Forms mode. What you see in -its buffer is not the contents of this file, but rather a single record -of the corresponding data file that is visited in its own buffer. So -there are two buffers involved in Forms mode: the @dfn{forms buffer} -that is initially used to visit the control file and that shows the -records being browsed, and the @dfn{data buffer} that holds the data -file being visited. The latter buffer is normally not visible. - -Initially, the first record is displayed in the forms buffer. -The mode line displays the major mode name @samp{Forms}, followed by the -minor mode @samp{View} if the data base is read-only. The number of the -current record (@var{n}) and the total number of records in the -file(@var{t}) are shown in the mode line as @samp{@var{n}/@var{t}}. For -example: - -@example ---%%-Emacs: passwd-demo (Forms View 1/54)----All------- -@end example - -If the buffer is not read-only, you may change the buffer to modify the -fields in the record. When you move to a different record, the contents -of the buffer are parsed using the specifications in -@code{forms-format-list}, and the data file is updated. If the record -has fields that aren't included in the display, they are not changed. - -@vindex forms-mode-hooks -Entering Forms mode runs the normal hook @code{forms-mode-hooks} to -perform user-defined customization. - -To save any modified data, you can use @kbd{C-x C-s} -(@code{forms-save-buffer}). This does not save the forms buffer (which would -be rather useless), but instead saves the buffer visiting the data file. - -To terminate Forms mode, you can use @kbd{C-x C-s} (@code{forms-save-buffer}) -and then kill the forms buffer. However, the data buffer will still -remain. If this is not desired, you have to kill this buffer too. - -@node Forms Commands -@chapter Forms Commands - -The commands of Forms mode belong to the @kbd{C-c} prefix, with one -exception: @key{TAB}, which moves to the next field. Forms mode uses -different key maps for normal mode and read-only mode. In read-only -Forms mode, you can access most of the commands without the @kbd{C-c} -prefix, but you must type ordinary letters instead of control -characters; for example, type @kbd{n} instead of @kbd{C-c C-n}. - -If your Emacs has been built with X-toolkit support, Forms mode will -provide its own menu with a number of Forms mode commands. - -@table @kbd -@findex forms-next-record -@kindex C-c C-n -@item C-c C-n -Show the next record (@code{forms-next-record}). With a numeric -argument @var{n}, show the @var{n}th next record. - -@findex forms-prev-record -@kindex C-c C-p -@item C-c C-p -Show the previous record (@code{forms-prev-record}). With a numeric -argument @var{n}, show the @var{n}th previous record. - -@findex forms-jump-record -@kindex C-c C-l -@item C-c C-l -Jump to a record by number (@code{forms-jump-record}). Specify -the record number with a numeric argument. - -@findex forms-first-record -@kindex C-c < -@item C-c < -Jump to the first record (@code{forms-first-record}). - -@findex forms-last-record -@kindex C-c > -@item C-c > -Jump to the last record (@code{forms-last-record}). This command also -recalculates the number of records in the data file. - -@findex forms-next-field -@kindex TAB -@item @key{TAB} -@kindex C-c TAB -@itemx C-c @key{TAB} -Jump to the next field in the current record (@code{forms-next-field}). -With a numeric argument @var{n}, jump forward @var{n} fields. If this command -would move past the last field, it wraps around to the first field. - -@findex forms-toggle-read-only -@kindex C-c C-q -@item C-c C-q -Toggles read-only mode (@code{forms-toggle-read-only}). In read-only -Forms mode, you cannot edit the fields; most Forms mode commands can be -accessed without the prefix @kbd{C-c} if you use the normal letter -instead (for example, type @kbd{n} instead of @kbd{C-c C-n}). In edit -mode, you can edit the fields and thus change the contents of the data -base; you must begin Forms mode commands with @code{C-c}. Switching -to edit mode is allowed only if you have write access to the data file. - -@findex forms-insert-record -@kindex C-c C-o -@item C-c C-o -Create a new record and insert it before the current record -(@code{forms-insert-record}). It starts out with empty (or default) -contents for its fields; you can then edit the fields. With a numeric -argument, the new record is created @emph{after} the current one. -See also @code{forms-modified-record-filter} in @ref{Modifying Forms -Contents}. - -@findex forms-delete-record -@kindex C-c C-k -@item C-c C-k -Delete the current record (@code{forms-delete-record}). You are -prompted for confirmation before the record is deleted unless a numeric -argument has been provided. - -@findex forms-search-forward -@kindex C-c C-s @var{regexp} @key{RET} -@item C-c C-s @var{regexp} @key{RET} -Search forward for @var{regexp} in all records following this one -(@code{forms-search-forward}). If found, this record is shown. -If you give an empty argument, the previous regexp is used again. - -@findex forms-search-backward -@kindex C-c C-r @var{regexp} @key{RET} -@item C-c C-r @var{regexp} @key{RET} -Search backward for @var{regexp} in all records following this one -(@code{forms-search-backward}). If found, this record is shown. -If you give an empty argument, the previous regexp is used again. - -@ignore -@findex forms-exit -@kindex C-c C-x -@item C-c C-x -Terminate Forms mode processing (@code{forms-exit}). The data file is -saved if it has been modified. - -@findex forms-exit-no-save -@item M-x forms-exit-no-save -Terminates forms mode processing without saving modified data first. -@end ignore - -@findex forms-prev-field -@item M-x forms-prev-field -Similar to @code{forms-next-field} but moves backwards. - -@findex forms-save-buffer -@item M-x forms-save-buffer -@kindex C-x C-s -@itemx C-x C-s -Forms mode replacement for @code{save-buffer}. When executed in the -forms buffer it will save the contents of the (modified) data buffer -instead. In Forms mode this function will be bound to @kbd{C-x C-s}. - -@findex forms-print -@item M-x forms-print -This command can be used to make a formatted print -of the contents of the data file. - -@end table - -In addition the command @kbd{M-x revert-buffer} is useful in Forms mode -just as in other modes. - -@ignore -@vindex forms-forms-scroll -@findex scroll-up -@findex scroll-down -If the variable @code{forms-forms-scrolls} is set to a value other -than @code{nil} (which it is, by default), the Emacs functions -@code{scroll-up} and @code{scroll-down} will perform a -@code{forms-next-record} and @code{forms-prev-record} when in forms -mode. So you can use your favorite page commands to page through the -data file. - -@vindex forms-forms-jump -@findex beginning-of-buffer -@findex end-of-buffer -Likewise, if the variable @code{forms-forms-jump} is not @code{nil} -(which it is, by default), Emacs functions @code{beginning-of-buffer} -and @code{end-of-buffer} will perform @code{forms-first-record} and -@code{forms-last-record} when in forms mode. -@end ignore - -The following function key definitions are set up in Forms mode -(whether read-only or not): - -@table @kbd -@kindex next -@item next -forms-next-record - -@kindex prior -@item prior -forms-prev-record - -@kindex begin -@item begin -forms-first-record - -@kindex end -@item end -forms-last-record - -@kindex S-Tab -@findex forms-prev-field -@item S-Tab -forms-prev-field -@end table - -@node Data File Format -@chapter Data File Format - -@cindex record -@cindex field -@vindex forms-field-sep -Files for use with Forms mode are very simple---each @dfn{record} -(usually one line) forms the contents of one form. Each record consists -of a number of @dfn{fields}, which are separated by the value of the -string @code{forms-field-sep}, which is @code{"\t"} (a Tab) by default. - -@vindex forms-read-file-filter -@vindex forms-write-file-filter -If the format of the data file is not suitable enough you can define the -filter functions @code{forms-read-file-filter} and -@code{forms-write-file-filter}. @code{forms-read-file-filter} is called -when the data file is read from disk into the data buffer. It operates -on the data buffer, ignoring read-only protections. When the data file -is saved to disk @code{forms-write-file-filter} is called to cancel the -effects of @code{forms-read-file-filter}. After being saved, -@code{forms-read-file-filter} is called again to prepare the data buffer -for further processing. - -@cindex pseudo-newline -@vindex forms-multi-line -Fields may contain text which shows up in the forms in multiple lines. -These lines are separated in the field using a ``pseudo-newline'' -character which is defined by the value of the string -@code{forms-multi-line}. Its default value is @code{"\^k"} (a Control-K -character). If it is -set to @code{nil}, multiple line fields are prohibited. - -If the data file does not exist, it is automatically created. - -@node Control File Format -@chapter Control File Format - -@cindex control file -The Forms mode @dfn{control file} serves two purposes. First, it names -the data file to use, and defines its format and properties. Second, -the Emacs buffer it occupies is used by Forms mode to display the forms. - -The contents of the control file are evaluated as a Lisp program. It -should set the following Lisp variables to suitable values: - -@table @code -@vindex forms-file -@item forms-file -This variable specifies the name of the data file. Example: - -@example -(setq forms-file "my/data-file") -@end example - -If the control file doesn't set @code{forms-file}, Forms mode -reports an error. - -@vindex forms-format-list -@item forms-format-list -This variable describes the way the fields of the record are formatted on -the screen. For details, see @ref{Format Description}. - -@vindex forms-number-of-fields -@item forms-number-of-fields -This variable holds the number of fields in each record of the data -file. Example: - -@example -(setq forms-number-of-fields 10) -@end example -@end table - -If the control file does not set @code{forms-format-list} a default -format is used. In this situation, Forms mode will deduce the number of -fields from the data file providing this file exists and -@code{forms-number-of-records} has not been set in the control file. - -The control file can optionally set the following additional Forms mode -variables. Most of them have default values that are good for most -applications. - -@table @code -@vindex forms-field-sep -@item forms-field-sep -This variable may be used to designate the string which separates the -fields in the records of the data file. If not set, it defaults to the -string @code{"\t"} (a Tab character). Example: - -@example -(setq forms-field-sep "\t") -@end example - -@vindex forms-read-only -@item forms-read-only -If the value is non-@code{nil}, the data file is treated read-only. (Forms -mode also treats the data file as read-only if you don't have access to -write it.) Example: - -@example -(set forms-read-only t) -@end example - -@vindex forms-multi-line -@item forms-multi-line -This variable specifies the @dfn{pseudo newline} separator that allows -multi-line fields. This separator goes between the ``lines'' within a -field---thus, the field doesn't really contain multiple lines, but it -appears that way when displayed in Forms mode. If the value is -@code{nil}, multi-line text fields are prohibited. The pseudo newline -must not be a character contained in @code{forms-field-sep}. - -The default value is @code{"\^k"}, the character Control-K. Example: - -@example -(setq forms-multi-line "\^k") -@end example - -@ignore -@vindex forms-forms-scroll -@item forms-forms-scroll -@xref{Forms Mode Commands}, for details. - -@vindex forms-forms-jump -@item forms-forms-jump -@xref{Forms Mode Commands}, for details. -@end ignore - -@findex forms-read-file-filter -@item forms-read-file-filter -This variable holds the name of a function to be called after the data -file has been read in. This can be used to transform the contents of the -data file into a format more suitable for forms processing. -If it is @code{nil}, no function is called. For example, to maintain a -gzipped database: - -@example -(defun gzip-read-file-filter () - (shell-command-on-region (point-min) (point-max) - "gzip -d" t t)) -(setq forms-read-file-filter 'gzip-read-file-filter) -@end example - -@findex forms-write-file-filter -@item forms-write-file-filter -This variable holds the name of a function to be called before writing -out the contents of the data file. -This can be used to undo the effects of @code{forms-read-file-filter}. -If it is @code{nil}, no function is called. Example: - -@example -(defun gzip-write-file-filter () - (make-variable-buffer-local 'require-final-newline) - (setq require-final-newline nil) - (shell-command-on-region (point-min) (point-max) - "gzip" t t)) -(setq forms-write-file-filter 'gzip-write-file-filter) -@end example - -@findex forms-new-record-filter -@item forms-new-record-filter -This variable holds a function to be called whenever a new record is created -to supply default values for fields. If it is @code{nil}, no function is -called. -@xref{Modifying Forms Contents}, for details. - -@findex forms-modified-record-filter -@item forms-modified-record-filter -This variable holds a function to be called whenever a record is -modified, just before updating the Forms data file. If it is -@code{nil}, no function is called. -@xref{Modifying Forms Contents}, for details. - -@findex forms-insert-after -@item forms-insert-after -If this variable is not @code{nil}, new records are created @emph{after} the -current record. Also, upon visiting a file, the initial position will be -at the last record instead of the first one. - -@findex forms-check-number-of-fields -@item forms-check-number-of-fields -Normally each record is checked to contain the correct number of fields. -Under certain circumstances, this can be undesirable. -If this variable is set to @code{nil}, these checks will be bypassed. -@end table - -@node Format Description -@chapter The Format Description - -@vindex forms-format-list - The variable @code{forms-format-list} specifies the format of the data -in the data file, and how to convert the data for display in Forms mode. -Its value must be a list of Forms mode @dfn{formatting elements}, each -of which can be a string, a number, a Lisp list, or a Lisp symbol that -evaluates to one of those. The formatting elements are processed in the -order they appear in the list. - -@table @var -@item string -A string formatting element is inserted in the forms ``as is,'' as text -that the user cannot alter. - -@item number -A number element selects a field of the record. The contents of this -field are inserted in the display at this point. Field numbers count -starting from 1 (one). - -@item list -A formatting element that is a list specifies a function call. This -function is called every time a record is displayed, and its result, -which must be a string, is inserted in the display text. The function -should do nothing but returning a string. - -@vindex forms-fields -The function you call can access the fields of the record as a list in -the variable -@code{forms-fields}. - -@item symbol -A symbol used as a formatting element should evaluate to a string, number, -or list; the value is interpreted as a formatting element, as described -above. -@end table - -If a record does not contain the number of fields as specified in -@code{forms-number-of-fields}, a warning message will be printed. Excess -fields are ignored, missing fields are set to empty. - -The control file which displays @file{/etc/passwd} file as demonstrated -in the beginning of this manual might look as follows: - -@example -;; @r{This demo visits @file{/etc/passwd}.} - -(setq forms-file "/etc/passwd") -(setq forms-number-of-fields 7) -(setq forms-read-only t) ; @r{to make sure} -(setq forms-field-sep ":") -;; @r{Don't allow multi-line fields.} -(setq forms-multi-line nil) - -(setq forms-format-list - (list - "====== /etc/passwd ======\n\n" - "User : " 1 - " Uid: " 3 - " Gid: " 4 - "\n\n" - "Name : " 5 - "\n\n" - "Home : " 6 - "\n\n" - "Shell: " 7 - "\n")) -@end example - -When you construct the value of @code{forms-format-list}, you should -usually either quote the whole value, like this, - -@example -(setq forms-format-list - '( - "====== " forms-file " ======\n\n" - "User : " 1 - (make-string 20 ?-) - @dots{} - )) -@end example - -@noindent -or quote the elements which are lists, like this: - -@example -(setq forms-format-list - (list - "====== " forms-file " ======\n\n" - "User : " 1 - '(make-string 20 ?-) - @dots{} - )) -@end example - -Forms mode validates the contents of @code{forms-format-list} when you -visit a database. If there are errors, processing is aborted with an -error message which includes a descriptive text. @xref{Error Messages}, -for a detailed list of error messages. - -If no @code{forms-format-list} is specified, Forms mode will supply a -default format list. This list contains the name of the file being -visited, and a simple label for each field indicating the field number. - -@node Modifying Forms Contents -@chapter Modifying The Forms Contents - -If @code{forms-read-only} is @code{nil}, the user can modify the fields -and records of the database. - -All normal editing commands are available for editing the contents of the -displayed record. You cannot delete or modify the fixed, explanatory -text that comes from string formatting elements, but you can modify the -actual field contents. - -@ignore -@c This is for the Emacs 18 version only. -If the contents of the forms cannot be recognized properly, this is -signaled using a descriptive text. @xref{Error Messages}, for more info. -The cursor will indicate the last part of the forms which was -successfully parsed. It's important to avoid entering field contents -that would cause confusion with the field-separating fixed text. -@end ignore - -If the variable @code{forms-modified-record-filter} is non-@code{nil}, -it is called as a function before the new data is written to the data -file. The function receives one argument, a vector that contains the -contents of the fields of the record. - -The function can refer to fields with @code{aref} and modify them with -@code{aset}. The first field has number 1 (one); thus, element 0 of the -vector is not used. The function should return the same vector it was -passed; the (possibly modified) contents of the vector determine what is -actually written in the file. Here is an example: - -@example -(defun my-modified-record-filter (record) - ;; @r{Modify second field.} - (aset record 2 (current-time-string)) - ;; @r{Return the field vector.} - record) - -(setq forms-modified-record-filter 'my-modified-record-filter) -@end example - -If the variable @code{forms-new-record-filter} is non-@code{nil}, its -value is a function to be called to fill in default values for the -fields of a new record. The function is passed a vector of empty -strings, one for each field; it should return the same vector, with -the desired field values stored in it. Fields are numbered starting -from 1 (one). Example: - -@example -(defun my-new-record-filter (fields) - (aset fields 5 (login-name)) - (aset fields 1 (current-time-string)) - fields) - -(setq forms-new-record-filter 'my-new-record-filter) -@end example - -@node Miscellaneous -@chapter Miscellaneous - -@vindex forms-version -The global variable @code{forms-version} holds the version information -of the Forms mode software. - -@findex forms-enumerate -It is very convenient to use symbolic names for the fields in a record. -The function @code{forms-enumerate} provides an elegant means to define -a series of variables whose values are consecutive integers. The -function returns the highest number used, so it can be used to set -@code{forms-number-of-fields} also. For example: - -@example -(setq forms-number-of-fields - (forms-enumerate - '(field1 field2 field3 @dots{}))) -@end example - -This sets @code{field1} to 1, @code{field2} to 2, and so on. - -Care has been taken to keep the Forms mode variables buffer-local, so it -is possible to visit multiple files in Forms mode simultaneously, even -if they have different properties. - -@findex forms-mode -If you have visited the control file in normal fashion with -@code{find-file} or a like command, you can switch to Forms mode with -the command @code{M-x forms-mode}. If you put @samp{-*- forms -*-} in -the first line of the control file, then visiting it enables Forms mode -automatically. But this makes it hard to edit the control file itself, -so you'd better think twice before using this. - -The default format for the data file, using @code{"\t"} to separate -fields and @code{"\^k"} to separate lines within a field, matches the -file format of some popular database programs, e.g. FileMaker. So -@code{forms-mode} can decrease the need to use proprietary software. - -@node Error Messages -@chapter Error Messages - -This section describes all error messages which can be generated by -forms mode. Error messages that result from parsing the control file -all start with the text @samp{Forms control file error}. Messages -generated while analyzing the definition of @code{forms-format-list} -start with @samp{Forms format error}. - -@table @code -@item Forms control file error: `forms-file' has not been set -The variable @code{forms-file} was not set by the control file. - -@item Forms control file error: `forms-number-of-fields' has not been set -The variable @code{forms-number-of-fields} was not set by the control -file. - -@item Forms control file error: `forms-number-of-fields' must be a number > 0 -The variable @code{forms-number-of-fields} did not contain a positive -number. - -@item Forms control file error: `forms-field-sep' is not a string -@itemx Forms control file error: `forms-multi-line' must be nil or a one-character string -The variable @code{forms-multi-line} was set to something other than -@code{nil} or a single-character string. - -@item Forms control file error: `forms-multi-line' is equal to 'forms-field-sep' -The variable @code{forms-multi-line} may not be equal to -@code{forms-field-sep} for this would make it impossible to distinguish -fields and the lines in the fields. - -@item Forms control file error: `forms-new-record-filter' is not a function -@itemx Forms control file error: `forms-modified-record-filter' is not a function -The variable has been set to something else than a function. - -@item Forms control file error: `forms-format-list' is not a list -The variable @code{forms-format-list} was not set to a Lisp list -by the control file. - -@item Forms format error: field number @var{xx} out of range 1..@var{nn} -A field number was supplied in @code{forms-format-list} with a value of -@var{xx}, which was not greater than zero and smaller than or equal to -the number of fields in the forms, @var{nn}. - -@item Forms format error: @var{fun} is not a function -The first element of a list which is an element of -@code{forms-format-list} was not a valid Lisp function. - -@item Forms format error: invalid element @var{xx} -A list element was supplied in @code{forms-format-list} which was not a -string, number or list. - -@ignore -@c This applies to Emacs 18 only. -@c Error messages generated while a modified form is being analyzed. - -@item Parse error: not looking at `...' -When re-parsing the contents of a forms, the text shown could not -be found. - -@item Parse error: cannot find `...' -When re-parsing the contents of a forms, the text shown, which -separates two fields, could not be found. - -@item Parse error: cannot parse adjacent fields @var{xx} and @var{yy} -Fields @var{xx} and @var{yy} were not separated by text, so could not be -parsed again. -@end ignore - -@item Warning: this record has @var{xx} fields instead of @var{yy} -The number of fields in this record in the data file did not match -@code{forms-number-of-fields}. Missing fields will be made empty. - -@item Multi-line fields in this record - update refused! -The current record contains newline characters, hence can not be written -back to the data file, for it would corrupt it. Probably you inserted a -newline in a field, while @code{forms-multi-line} was @code{nil}. - -@item Field separator occurs in record - update refused! -The current record contains the field separator string inside one of the -fields. It can not be written back to the data file, for it would -corrupt it. Probably you inserted the field separator string in a field. - -@item Record number @var{xx} out of range 1..@var{yy} -A jump was made to non-existing record @var{xx}. @var{yy} denotes the -number of records in the file. - -@item Stuck at record @var{xx} -An internal error prevented a specific record from being retrieved. - -@item No write access to @code{"}@var{file}@code{"} -An attempt was made to enable edit mode on a file that has been write -protected. - -@item Search failed: @var{regexp} -The @var{regexp} could not be found in the data file. Forward searching -is done from the current location until the end of the file, then -retrying from the beginning of the file until the current location. -Backward searching is done from the current location until the beginning -of the file, then retrying from the end of the file until the current -location. - -@item Wrapped -A search completed successfully after wrapping around. - -@item Warning: number of records changed to @var{nn} -Forms mode's idea of the number of records has been adjusted to the -number of records actually present in the data file. - -@item Problem saving buffers? -An error occurred while saving the data file buffer. Most likely, Emacs -did ask to confirm deleting the buffer because it had been modified, and -you said `no'. -@end table - -@node Long Example -@chapter Long Example - -The following example exploits most of the features of Forms mode. -This example is included in the distribution as file @file{forms-d2.el}. - -@example -;; demo2 -- demo forms-mode -*- emacs-lisp -*- - -;; @r{This sample forms exploit most of the features of forms mode.} - -;; @r{Set the name of the data file.} -(setq forms-file "forms-d2.dat") - -;; @r{Use @code{forms-enumerate} to set field names and number thereof.} -(setq forms-number-of-fields - (forms-enumerate - '(arch-newsgroup ; 1 - arch-volume ; 2 - arch-issue ; and ... - arch-article ; ... so - arch-shortname ; ... ... on - arch-parts - arch-from - arch-longname - arch-keywords - arch-date - arch-remarks))) - -;; @r{The following functions are used by this form for layout purposes.} -;; -(defun arch-tocol (target &optional fill) - "Produces a string to skip to column TARGET. -Prepends newline if needed. -The optional FILL should be a character, used to fill to the column." - (if (null fill) - (setq fill ? )) - (if (< target (current-column)) - (concat "\n" (make-string target fill)) - (make-string (- target (current-column)) fill))) -;; -(defun arch-rj (target field &optional fill) - "Produces a string to skip to column TARGET\ - minus the width of field FIELD. -Prepends newline if needed. -The optional FILL should be a character, -used to fill to the column." - (arch-tocol (- target (length (nth field forms-fields))) fill)) - -;; @r{Record filters.} -;; -(defun new-record-filter (the-record) - "Form a new record with some defaults." - (aset the-record arch-from (user-full-name)) - (aset the-record arch-date (current-time-string)) - the-record) ; return it -(setq forms-new-record-filter 'new-record-filter) - -;; @r{The format list.} -(setq forms-format-list - (list - "====== Public Domain Software Archive ======\n\n" - arch-shortname - " - " arch-longname - "\n\n" - "Article: " arch-newsgroup - "/" arch-article - " " - '(arch-tocol 40) - "Issue: " arch-issue - " " - '(arch-rj 73 10) - "Date: " arch-date - "\n\n" - "Submitted by: " arch-from - "\n" - '(arch-tocol 79 ?-) - "\n" - "Keywords: " arch-keywords - "\n\n" - "Parts: " arch-parts - "\n\n====== Remarks ======\n\n" - arch-remarks - )) - -;; @r{That's all, folks!} -@end example - -@node Credits -@chapter Credits - -Bug fixes and other useful suggestions were supplied by -Harald Hanche-Olsen (@code{hanche@@imf.unit.no}), -@code{cwitty@@portia.stanford.edu}, -Jonathan I. Kamens, -Per Cederqvist (@code{ceder@@signum.se}), -Michael Lipka (@code{lipka@@lip.hanse.de}), -Andy Piper (@code{ajp@@eng.cam.ac.uk}), -Frederic Pierresteguy (@code{F.Pierresteguy@@frcl.bull.fr}), -Ignatios Souvatzis -and Richard Stallman (@code{rms@@gnu.org}). - -This documentation was slightly inspired by the documentation of ``rolo -mode'' by Paul Davis at Schlumberger Cambridge Research -(@code{davis%scrsu1%sdr.slb.com@@relay.cs.net}). - -None of this would have been possible without GNU Emacs of the Free -Software Foundation. Thanks, Richard! - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index -@printindex cp - -@bye diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi deleted file mode 100644 index bbaf2c068da..00000000000 --- a/doc/misc/gnus-coding.texi +++ /dev/null @@ -1,393 +0,0 @@ -\input texinfo - -@setfilename gnus-coding -@settitle Gnus Coding Style and Maintenance Guide -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex pg cp - -@copying -Copyright @copyright{} 2004-2005, 2007-2012 Free Software -Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual'', and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Gnus manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - - -@titlepage -@title Gnus Coding Style and Maintenance Guide - -@author by Reiner Steib - -@insertcopying -@end titlepage - -@c Obviously this is only a very rudimentary draft. We put it in the -@c repository anyway hoping that it might annoy someone enough to fix -@c it. ;-) Fixing only a paragraph also is appreciated. - -@ifnottex -@node Top -@top Gnus Coding Style and Maintenance Guide -This manual describes @dots{} - -@insertcopying -@end ifnottex - -@menu -* Gnus Coding Style:: Gnus Coding Style -* Gnus Maintenance Guide:: Gnus Maintenance Guide -@end menu - -@c @ref{Gnus Reference Guide, ,Gnus Reference Guide, gnus, The Gnus Newsreader} - -@node Gnus Coding Style -@chapter Gnus Coding Style -@section Dependencies - -The Gnus distribution contains a lot of libraries that have been written -for Gnus and used intensively for Gnus. But many of those libraries are -useful on their own. E.g. other Emacs Lisp packages might use the -@acronym{MIME} library @xref{Top, ,Top, emacs-mime, The Emacs MIME -Manual}. - -@subsection General purpose libraries - -@table @file - -@item netrc.el -@file{.netrc} parsing functionality. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item format-spec.el -Functions for formatting arbitrary formatting strings. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item hex-util.el -Functions to encode/decode hexadecimal string. -@c As of 2007-08-25... -There are no Gnus dependencies in these files. -@end table - -@subsection Encryption and security - -@table @file -@item encrypt.el -File encryption routines -@c As of 2005-10-25... -There are no Gnus dependencies in this file. - -@item password.el -Read passwords from user, possibly using a password cache. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item tls.el -TLS/SSL support via wrapper around GnuTLS -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item pgg*.el -Glue for the various PGP implementations. -@c As of 2005-10-21... -There are no Gnus dependencies in these files. - -@item sha1.el -SHA1 Secure Hash Algorithm. -@c As of 2007-08-25... -There are no Gnus dependencies in these files. -@end table - -@subsection Networking - -@table @file -@item dig.el -Domain Name System dig interface. -@c As of 2005-10-21... -There are no serious Gnus dependencies in this file. Uses -@code{gnus-run-mode-hooks} (a wrapper function). - -@item dns.el, dns-mode.el -Domain Name Service lookups. -@c As of 2005-10-21... -There are no Gnus dependencies in these files. -@end table - -@subsection Mail and News related RFCs - -@table @file -@item pop3.el -Post Office Protocol (RFC 1460) interface. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item imap.el -@acronym{IMAP} library. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item ietf-drums.el -Functions for parsing RFC822bis headers. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item rfc1843.el -HZ (rfc1843) decoding. HZ is a data format for exchanging files of -arbitrarily mixed Chinese and @acronym{ASCII} characters. -@c As of 2005-10-21... -@code{rfc1843-gnus-setup} seem to be useful only for Gnus. Maybe this -function should be relocated to remove dependencies on Gnus. Other -minor dependencies: @code{gnus-newsgroup-name} could be eliminated by -using an optional argument to @code{rfc1843-decode-article-body}. - -@item rfc2045.el -Functions for decoding rfc2045 headers -@c As of 2007-08-25... -There are no Gnus dependencies in these files. - -@item rfc2047.el -Functions for encoding and decoding rfc2047 messages -@c As of 2007-08-25... -There are no Gnus dependencies in these files. -@c -Only a couple of tests for gnusy symbols. - -@item rfc2104.el -RFC2104 Hashed Message Authentication Codes -@c As of 2007-08-25... -There are no Gnus dependencies in these files. - -@item rfc2231.el -Functions for decoding rfc2231 headers -@c As of 2007-08-25... -There are no Gnus dependencies in these files. - -@item flow-fill.el -Interpret RFC2646 "flowed" text. -@c As of 2005-10-27... -There are no Gnus dependencies in this file. - -@item uudecode.el -Elisp native uudecode. -@c As of 2005-12-06... -There are no Gnus dependencies in this file. -@c ... but the custom group is gnus-extract. - -@item canlock.el -Functions for Cancel-Lock feature -@c Cf. draft-ietf-usefor-cancel-lock-01.txt -@c Although this draft has expired, Canlock-Lock revived in 2007 when -@c major news providers (e.g. news.individual.org) started to use it. -@c As of 2007-08-25... -There are no Gnus dependencies in these files. - -@end table - -@subsection message - -All message composition from Gnus (both mail and news) takes place in -Message mode buffers. Message mode is intended to be a replacement for -Emacs mail mode. There should be no Gnus dependencies in -@file{message.el}. Alas it is not anymore. Patches and suggestions to -remove the dependencies are welcome. - -@c message.el requires nnheader which requires gnus-util. - -@subsection Emacs @acronym{MIME} - -The files @file{mml*.el} and @file{mm-*.el} provide @acronym{MIME} -functionality for Emacs. - -@acronym{MML} (@acronym{MIME} Meta Language) is supposed to be -independent from Gnus. Alas it is not anymore. Patches and suggestions -to remove the dependencies are welcome. - -@subsection Gnus backends - -The files @file{nn*.el} provide functionality for accessing NNTP -(@file{nntp.el}), IMAP (@file{nnimap.el}) and several other Mail back -ends (probably @file{nnml.el}, @file{nnfolder.el} and -@file{nnmaildir.el} are the most widely used mail back ends). - -@c mm-uu requires nnheader which requires gnus-util. message.el also -@c requires nnheader. - - -@section Compatibility - -No Gnus and Gnus 5.10.10 and up should work on: -@itemize @bullet -@item -Emacs 21.1 and up. -@item -XEmacs 21.4 and up. -@end itemize - -Gnus 5.10.8 and below should work on: -@itemize @bullet -@item -Emacs 20.7 and up. -@item -XEmacs 21.1 and up. -@end itemize - -@node Gnus Maintenance Guide -@chapter Gnus Maintenance Guide - -@section Stable and development versions - -The development of Gnus normally is done on the Git repository trunk -as of April 19, 2010 (formerly it was done in CVS; the repository is -at http://git.gnus.org), i.e. there are no separate branches to -develop and test new features. Most of the time, the trunk is -developed quite actively with more or less daily changes. Only after -a new major release, e.g. 5.10.1, there's usually a feature period of -several months. After the release of Gnus 5.10.6 the development of -new features started again on the trunk while the 5.10 series is -continued on the stable branch (v5-10) from which more stable releases -will be done when needed (5.10.8, @dots{}). @ref{Gnus Development, -,Gnus Development, gnus, The Gnus Newsreader} - -Stable releases of Gnus finally become part of Emacs. E.g. Gnus 5.8 -became a part of Emacs 21 (relabeled to Gnus 5.9). The 5.10 series -became part of Emacs 22 as Gnus 5.11. - -@section Syncing - -@c Some MIDs related to this follow. Use http://thread.gmane.org/MID -@c (and click on the subject) to get the thread on Gmane. - -@c Some quotes from Miles Bader follow... - -@c -@c - -In the past, the inclusion of Gnus into Emacs was quite cumbersome. For -each change made to Gnus in Emacs repository, it had to be checked that -it was applied to the new Gnus version, too. Else, bug fixes done in -Emacs repository might have been lost. - -With the inclusion of Gnus 5.10, Miles Bader has set up an Emacs-Gnus -gateway to ensure the bug fixes from Emacs CVS are propagated to Gnus -CVS semi-automatically. - -After Emacs moved to bzr and Gnus moved to git, Katsumi Yamaoka has -taken over the chore of keeping Emacs and Gnus in sync. In general, -changes made to one repository will usually be replicated in the other -within a few days. - -Basically the idea is that the gateway will cause all common files in -Emacs and Gnus v5-13 to be identical except when there's a very good -reason (e.g., the Gnus version string in Emacs says @samp{5.11}, but -the v5-13 version string remains @samp{5.13.x}). Furthermore, all -changes in these files in either Emacs or the v5-13 branch will be -installed into the Gnus git trunk, again except where there's a good -reason. - -@c (typically so far the only exception has been that the changes -@c already exist in the trunk in modified form). -Because of this, when the next major version of Gnus will be included in -Emacs, it should be very easy -- just plonk in the files from the Gnus -trunk without worrying about lost changes from the Emacs tree. - -The effect of this is that as hacker, you should generally only have to -make changes in one place: - -@itemize -@item -If it's a file which is thought of as being outside of Gnus (e.g., the -new @file{encrypt.el}), you should probably make the change in the Emacs -tree, and it will show up in the Gnus tree a few days later. - -If you don't have Emacs bzr access (or it's inconvenient), you can -change such a file in the v5-10 branch, and it should propagate to Emacs -bzr -- however, it will get some extra scrutiny (by Miles) to see if the -changes are possibly controversial and need discussion on the mailing -list. Many changes are obvious bug-fixes however, so often there won't -be any problem. - -@item -If it's to a Gnus file, and it's important enough that it should be part -of Emacs and the v5-10 branch, then you can make the change on the v5-10 -branch, and it will go into Emacs bzr and the Gnus git trunk (a few days -later). The most prominent examples for such changes are bug-fixed -including improvements on the documentation. - -If you know that there will be conflicts (perhaps because the affected -source code is different in v5-10 and the Gnus git trunk), then you can -install your change in both places, and when I try to sync them, there -will be a conflict -- however, since in most such cases there would be a -conflict @emph{anyway}, it's often easier for me to resolve it simply if -I see two @samp{identical} changes, and can just choose the proper one, -rather than having to actually fix the code. - -@item -For general Gnus development changes, of course you just make the -change on the Gnus Git trunk and it goes into Emacs a few years -later... :-) - -@end itemize - -Of course in any case, if you just can't wait for me to sync your -change, you can commit it in more than one place and probably there will -be no problem; usually the changes are textually identical anyway, so -can be easily resolved automatically (sometimes I notice silly things in -such multiple commits, like whitespace differences, and unify those ;-). - - -@c I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to -@c require more manual work. - -@c By default I sync about once a week. I also try to follow any Gnus -@c threads on the mailing lists and make sure any changes being discussed -@c are kept more up-to-date (so say 1-2 days delay for "topical" changes). - -@c - -@c BTW, just to add even more verbose explanation about the syncing thing: - -@section Miscellanea - -@heading @file{GNUS-NEWS} - -Starting from No Gnus, the @file{GNUS-NEWS} is created from -@file{texi/gnus-news.texi}. Don't edit @file{GNUS-NEWS}. Edit -@file{texi/gnus-news.texi}, type @command{make GNUS-NEWS} in the -@file{texi} directory and commit @file{GNUS-NEWS} and -@file{texi/gnus-news.texi}. - -@heading Conventions for version information in defcustoms - -For new customizable variables introduced in Oort Gnus (including the -v5-10 branch) use @code{:version "22.1" ;; Oort Gnus} (including the -comment) or e.g. @code{:version "22.2" ;; Gnus 5.10.10} if the feature -was added for Emacs 22.2 and Gnus 5.10.10. -@c -If the variable is new in No Gnus use @code{:version "23.1" ;; No Gnus}. - -The same applies for customizable variables when its default value was -changed. - -@c Local Variables: -@c mode: texinfo -@c coding: iso-8859-1 -@c End: diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi deleted file mode 100644 index 0c8c8505e27..00000000000 --- a/doc/misc/gnus-faq.texi +++ /dev/null @@ -1,2310 +0,0 @@ -@c \input texinfo @c -*-texinfo-*- -@c Uncomment 1st line before texing this file alone. -@c %**start of header -@c Copyright (C) 1995, 2001-2012 Free Software Foundation, Inc. -@c -@setfilename gnus-faq.info -@settitle Frequently Asked Questions -@c %**end of header -@c - -@node Frequently Asked Questions -@section Frequently Asked Questions - -@menu -* FAQ - Changes:: -* FAQ - Introduction:: About Gnus and this FAQ. -* FAQ 1 - Installation FAQ:: Installation of Gnus. -* FAQ 2 - Startup / Group buffer:: Start up questions and the - first buffer Gnus shows you. -* FAQ 3 - Getting Messages:: Making Gnus read your mail - and news. -* FAQ 4 - Reading messages:: How to efficiently read - messages. -* FAQ 5 - Composing messages:: Composing mails or Usenet - postings. -* FAQ 6 - Old messages:: Importing, archiving, - searching and deleting messages. -* FAQ 7 - Gnus in a dial-up environment:: Reading mail and news while - offline. -* FAQ 8 - Getting help:: When this FAQ isn't enough. -* FAQ 9 - Tuning Gnus:: How to make Gnus faster. -* FAQ - Glossary:: Terms used in the FAQ - explained. -@end menu - -@subheading Abstract - -This is the new Gnus Frequently Asked Questions list. - -Please submit features and suggestions to the -@email{ding@@gnus.org, ding list}. - -@node FAQ - Changes -@subheading Changes - - - -@itemize @bullet - -@item -2008-06-15: Adjust for message-fill-column. Add x-face-file. -Clarify difference between ding and gnu.emacs.gnus. Remove -reference to discontinued service. - -@item -2006-04-15: Added tip on how to delete sent buffer on exit. -@end itemize - -@node FAQ - Introduction -@subheading Introduction - -This is the Gnus Frequently Asked Questions list. - -Gnus is a Usenet Newsreader and Electronic Mail User Agent implemented -as a part of Emacs. It's been around in some form for almost a decade -now, and has been distributed as a standard part of Emacs for much of -that time. Gnus 5 is the latest (and greatest) incarnation. The -original version was called GNUS, and was written by Masanobu UMEDA. -When autumn crept up in '94, Lars Magne Ingebrigtsen grew bored and -decided to rewrite Gnus. - -Its biggest strength is the fact that it is extremely -customizable. It is somewhat intimidating at first glance, but -most of the complexity can be ignored until you're ready to take -advantage of it. If you receive a reasonable volume of e-mail -(you're on various mailing lists), or you would like to read -high-volume mailing lists but cannot keep up with them, or read -high volume newsgroups or are just bored, then Gnus is what you -want. - -This FAQ was maintained by Justin Sheehy until March 2002. He -would like to thank Steve Baur and Per Abrahamsen for doing a wonderful -job with this FAQ before him. We would like to do the same - thanks, -Justin! - -This version is much nicer than the unofficial hypertext -versions that are archived at Utrecht, Oxford, Smart Pages, Ohio -State, and other FAQ archives. See the resources question below -if you want information on obtaining it in another format. - -The information contained here was compiled with the assistance -of the Gnus development mailing list, and any errors or -misprints are the Gnus team's fault, sorry. - -@node FAQ 1 - Installation FAQ -@subsection Installation FAQ - -@menu -* FAQ 1-1:: What is the latest version of Gnus? -* FAQ 1-2:: What's new in 5.10? -* FAQ 1-3:: Where and how to get Gnus? -* FAQ 1-4:: What to do with the tarball now? -* FAQ 1-5:: I sometimes read references to No Gnus and Oort Gnus, - what are those? -* FAQ 1-6:: Which version of Emacs do I need? -* FAQ 1-7:: How do I run Gnus on both Emacs and XEmacs? -@end menu - -@node FAQ 1-1 -@subsubheading Question 1.1 - -What is the latest version of Gnus? - -@subsubheading Answer - -Jingle please: Gnus 5.10 is released, get it while it's -hot! As well as the step in version number is rather -small, Gnus 5.10 has tons of new features which you -shouldn't miss. The current release (5.13) should be at -least as stable as the latest release of the 5.8 series. - -@node FAQ 1-2 -@subsubheading Question 1.2 - -What's new in 5.10? - -@subsubheading Answer - -First of all, you should have a look into the file -GNUS-NEWS in the toplevel directory of the Gnus tarball, -there the most important changes are listed. Here's a -short list of the changes I find especially -important/interesting: - -@itemize @bullet - -@item -Major rewrite of the Gnus agent, Gnus agent is now -active by default. - -@item -Many new article washing functions for dealing with -ugly formatted articles. - -@item -Anti Spam features. - -@item -Message-utils now included in Gnus. - -@item -New format specifiers for summary lines, e.g. %B for -a complex trn-style thread tree. -@end itemize - -@node FAQ 1-3 -@subsubheading Question 1.3 - -Where and how to get Gnus? - -@subsubheading Answer - -Gnus is released independent from releases of Emacs and XEmacs. -Therefore, the version bundled with Emacs or the version in XEmacs's -package system might not be up to date (e.g. Gnus 5.9 bundled with Emacs -21 is outdated). -You can get the latest released version of Gnus from -@uref{http://www.gnus.org/dist/gnus.tar.gz} -or via anonymous FTP from -@uref{ftp://ftp.gnus.org/pub/gnus/gnus.tar.gz}. - -@node FAQ 1-4 -@subsubheading Question 1.4 - -What to do with the tarball now? - -@subsubheading Answer - -Untar it via @samp{tar xvzf gnus.tar.gz} and do the common -@samp{./configure; make; make install} circle. -(under MS-Windows either get the Cygwin environment from -@uref{http://www.cygwin.com} -which allows you to do what's described above or unpack the -tarball with some packer (e.g. Winace from -@uref{http://www.winace.com}) -and use the batch-file make.bat included in the tarball to install -Gnus.) If you don't want to (or aren't allowed to) install Gnus -system-wide, you can install it in your home directory and add the -following lines to your ~/.xemacs/init.el or ~/.emacs: - -@example -(add-to-list 'load-path "/path/to/gnus/lisp") -(if (featurep 'xemacs) - (add-to-list 'Info-directory-list "/path/to/gnus/texi/") - (add-to-list 'Info-default-directory-list "/path/to/gnus/texi/")) -@end example -@noindent - -Make sure that you don't have any Gnus related stuff -before this line, on MS Windows use something like -"C:/path/to/lisp" (yes, "/"). - -@node FAQ 1-5 -@subsubheading Question 1.5 - -I sometimes read references to No Gnus and Oort Gnus, -what are those? - -@subsubheading Answer - -Oort Gnus was the name of the development version of -Gnus, which became Gnus 5.10 in autumn 2003. No Gnus is -the name of the current development version which will -once become Gnus 5.12 or Gnus 6. (If you're wondering why -not 5.11, the odd version numbers are normally used for -the Gnus versions bundled with Emacs) - -@node FAQ 1-6 -@subsubheading Question 1.6 - -Which version of Emacs do I need? - -@subsubheading Answer - -Gnus 5.10 requires an Emacs version that is greater than or equal -to Emacs 20.7 or XEmacs 21.1. -The development versions of Gnus (aka No Gnus) requires Emacs 21 -or XEmacs 21.4. - -@node FAQ 1-7 -@subsubheading Question 1.7 - -How do I run Gnus on both Emacs and XEmacs? - -@subsubheading Answer - -You can't use the same copy of Gnus in both as the Lisp -files are byte-compiled to a format which is different -depending on which Emacs did the compilation. Get one copy -of Gnus for Emacs and one for XEmacs. - -@node FAQ 2 - Startup / Group buffer -@subsection Startup / Group buffer - -@menu -* FAQ 2-1:: Every time I start Gnus I get a message "Gnus auto-save - file exists. Do you want to read it?", what does this mean and - how to prevent it? -* FAQ 2-2:: Gnus doesn't remember which groups I'm subscribed to, - what's this? -* FAQ 2-3:: How to change the format of the lines in Group buffer? -* FAQ 2-4:: My group buffer becomes a bit crowded, is there a way to - sort my groups into categories so I can easier browse through - them? -* FAQ 2-5:: How to manually sort the groups in Group buffer? How to - sort the groups in a topic? -@end menu - -@node FAQ 2-1 -@subsubheading Question 2.1 - -Every time I start Gnus I get a message "Gnus auto-save -file exists. Do you want to read it?", what does this mean -and how to prevent it? - -@subsubheading Answer - -This message means that the last time you used Gnus, it -wasn't properly exited and therefore couldn't write its -information to disk (e.g. which messages you read), you -are now asked if you want to restore that information -from the auto-save file. - -To prevent this message make sure you exit Gnus -via @samp{q} in group buffer instead of -just killing Emacs. - -@node FAQ 2-2 -@subsubheading Question 2.2 - -Gnus doesn't remember which groups I'm subscribed to, -what's this? - -@subsubheading Answer - -You get the message described in the q/a pair above while -starting Gnus, right? It's an other symptom for the same -problem, so read the answer above. - -@node FAQ 2-3 -@subsubheading Question 2.3 - -How to change the format of the lines in Group buffer? - -@subsubheading Answer - -You've got to tweak the value of the variable -gnus-group-line-format. See the manual node "Group Line -Specification" for information on how to do this. An -example for this (guess from whose .gnus :-)): - -@example -(setq gnus-group-line-format "%P%M%S[%5t]%5y : %(%g%)\n") -@end example -@noindent - -@node FAQ 2-4 -@subsubheading Question 2.4 - -My group buffer becomes a bit crowded, is there a way to -sort my groups into categories so I can easier browse -through them? - -@subsubheading Answer - -Gnus offers the topic mode, it allows you to sort your -groups in, well, topics, e.g. all groups dealing with -Linux under the topic linux, all dealing with music under -the topic music and all dealing with scottish music under -the topic scottish which is a subtopic of music. - -To enter topic mode, just hit t while in Group buffer. Now -you can use @samp{T n} to create a topic -at point and @samp{T m} to move a group to -a specific topic. For more commands see the manual or the -menu. You might want to include the %P specifier at the -beginning of your gnus-group-line-format variable to have -the groups nicely indented. - -@node FAQ 2-5 -@subsubheading Question 2.5 - -How to manually sort the groups in Group buffer? How to -sort the groups in a topic? - -@subsubheading Answer - -Move point over the group you want to move and -hit @samp{C-k}, now move point to the -place where you want the group to be and -hit @samp{C-y}. - -@node FAQ 3 - Getting Messages -@subsection Getting Messages - -@menu -* FAQ 3-1:: I just installed Gnus, started it via @samp{M-x gnus} - but it only says "nntp (news) open error", what to do? -* FAQ 3-2:: I'm working under Windows and have no idea what - ~/.gnus.el means. -* FAQ 3-3:: My news server requires authentication, how to store - user name and password on disk? -* FAQ 3-4:: Gnus seems to start up OK, but I can't find out how to - subscribe to a group. -* FAQ 3-5:: Gnus doesn't show all groups / Gnus says I'm not allowed - to post on this server as well as I am, what's that? -* FAQ 3-6:: I want Gnus to fetch news from several servers, is this - possible? -* FAQ 3-7:: And how about local spool files? -* FAQ 3-8:: OK, reading news works now, but I want to be able to - read my mail with Gnus, too. How to do it? -* FAQ 3-9:: And what about IMAP? -* FAQ 3-10:: At the office we use one of those MS Exchange servers, - can I use Gnus to read my mail from it? -* FAQ 3-11:: Can I tell Gnus not to delete the mails on the server it - retrieves via POP3? -@end menu - -@node FAQ 3-1 -@subsubheading Question 3.1 - -I just installed Gnus, started it via -@samp{M-x gnus} -but it only says "nntp (news) open error", what to do? - -@subsubheading Answer - -You've got to tell Gnus where to fetch the news from. Read -the documentation for information on how to do this. As a -first start, put those lines in ~/.gnus.el: - -@example -(setq gnus-select-method '(nntp "news.yourprovider.net")) -(setq user-mail-address "you@@yourprovider.net") -(setq user-full-name "Your Name") -@end example -@noindent - -@node FAQ 3-2 -@subsubheading Question 3.2 - -I'm working under Windows and have no idea what ~/.gnus.el means. - -@subsubheading Answer - -The ~/ means the home directory where Gnus and Emacs look -for the configuration files. However, you don't really -need to know what this means, it suffices that Emacs knows -what it means :-) You can type -@samp{C-x C-f ~/.gnus.el RET } -(yes, with the forward slash, even on Windows), and -Emacs will open the right file for you. (It will most -likely be new, and thus empty.) -However, I'd discourage you from doing so, since the -directory Emacs chooses will most certainly not be what -you want, so let's do it the correct way. -The first thing you've got to do is to -create a suitable directory (no blanks in directory name -please) e.g. c:\myhome. Then you must set the environment -variable HOME to this directory. To do this under Win9x -or Me include the line - -@example -SET HOME=C:\myhome -@end example -@noindent - -in your autoexec.bat and reboot. Under NT, 2000 and XP, hit -Winkey+Pause/Break to enter system options (if it doesn't work, go -to Control Panel -> System -> Advanced). There you'll find the -possibility to set environment variables. Create a new one with -name HOME and value C:\myhome. Rebooting is not necessary. - -Now to create ~/.gnus.el, say -@samp{C-x C-f ~/.gnus.el RET C-x C-s}. -in Emacs. - -@node FAQ 3-3 -@subsubheading Question 3.3 - -My news server requires authentication, how to store -user name and password on disk? - -@subsubheading Answer - -Create a file ~/.authinfo which includes for each server a line like this - -@example -machine news.yourprovider.net login YourUserName password YourPassword -@end example -@noindent -. -Make sure that the file isn't readable to others if you -work on a OS which is capable of doing so. (Under Unix -say -@example -chmod 600 ~/.authinfo -@end example -@noindent - -in a shell.) - -@node FAQ 3-4 -@subsubheading Question 3.4 - -Gnus seems to start up OK, but I can't find out how to -subscribe to a group. - -@subsubheading Answer - -If you know the name of the group say @samp{U -name.of.group RET} in group buffer (use the -tab-completion Luke). Otherwise hit ^ in group buffer, -this brings you to the server buffer. Now place point (the -cursor) over the server which carries the group you want, -hit @samp{RET}, move point to the group -you want to subscribe to and say @samp{u} -to subscribe to it. - -@node FAQ 3-5 -@subsubheading Question 3.5 - -Gnus doesn't show all groups / Gnus says I'm not allowed to -post on this server as well as I am, what's that? - -@subsubheading Answer - -Some providers allow restricted anonymous access and full -access only after authorization. To make Gnus send authinfo -to those servers append - -@example -force yes -@end example -@noindent - -to the line for those servers in ~/.authinfo. - -@node FAQ 3-6 -@subsubheading Question 3.6 - -I want Gnus to fetch news from several servers, is this possible? - -@subsubheading Answer - -Of course. You can specify more sources for articles in the -variable gnus-secondary-select-methods. Add something like -this in ~/.gnus.el: - -@example -(add-to-list 'gnus-secondary-select-methods - '(nntp "news.yourSecondProvider.net")) -(add-to-list 'gnus-secondary-select-methods - '(nntp "news.yourThirdProvider.net")) -@end example -@noindent - -@node FAQ 3-7 -@subsubheading Question 3.7 - -And how about local spool files? - -@subsubheading Answer - -No problem, this is just one more select method called -nnspool, so you want this: - -@example -(add-to-list 'gnus-secondary-select-methods '(nnspool "")) -@end example -@noindent - -Or this if you don't want an NNTP Server as primary news source: - -@example -(setq gnus-select-method '(nnspool "")) -@end example -@noindent - -Gnus will look for the spool file in /usr/spool/news, if you -want something different, change the line above to something like this: - -@example -(add-to-list 'gnus-secondary-select-methods - '(nnspool "" - (nnspool-directory "/usr/local/myspoolddir"))) -@end example -@noindent - -This sets the spool directory for this server only. -You might have to specify more stuff like the program used -to post articles, see the Gnus manual on how to do this. - -@node FAQ 3-8 -@subsubheading Question 3.8 - -OK, reading news works now, but I want to be able to read my mail -with Gnus, too. How to do it? - -@subsubheading Answer - -That's a bit harder since there are many possible sources -for mail, many possible ways for storing mail and many -different ways for sending mail. The most common cases are -these: 1: You want to read your mail from a pop3 server and -send them directly to a SMTP Server 2: Some program like -fetchmail retrieves your mail and stores it on disk from -where Gnus shall read it. Outgoing mail is sent by -Sendmail, Postfix or some other MTA. Sometimes, you even -need a combination of the above cases. - -However, the first thing to do is to tell Gnus in which way -it should store the mail, in Gnus terminology which back end -to use. Gnus supports many different back ends, the most -commonly used one is nnml. It stores every mail in one file -and is therefore quite fast. However you might prefer a one -file per group approach if your file system has problems with -many small files, the nnfolder back end is then probably the -choice for you. To use nnml add the following to ~/.gnus.el: - -@example -(add-to-list 'gnus-secondary-select-methods '(nnml "")) -@end example -@noindent - -As you might have guessed, if you want nnfolder, it's - -@example -(add-to-list 'gnus-secondary-select-methods '(nnfolder "")) -@end example -@noindent - -Now we need to tell Gnus, where to get its mail from. If -it's a POP3 server, then you need something like this: - -@example -(eval-after-load "mail-source" - '(add-to-list 'mail-sources '(pop :server "pop.YourProvider.net" - :user "yourUserName" - :password "yourPassword"))) -@end example -@noindent - -Make sure ~/.gnus.el isn't readable to others if you store -your password there. If you want to read your mail from a -traditional spool file on your local machine, it's - -@example -(eval-after-load "mail-source" - '(add-to-list 'mail-sources '(file :path "/path/to/spool/file")) -@end example -@noindent - -If it's a Maildir, with one file per message as used by -postfix, Qmail and (optionally) fetchmail it's - -@example -(eval-after-load "mail-source" - '(add-to-list 'mail-sources '(maildir :path "/path/to/Maildir/" - :subdirs ("cur" "new"))) -@end example -@noindent - -And finally if you want to read your mail from several files -in one directory, for example because procmail already split your -mail, it's - -@example -(eval-after-load "mail-source" - '(add-to-list 'mail-sources - '(directory :path "/path/to/procmail-dir/" - :suffix ".prcml"))) -@end example -@noindent - -Where :suffix ".prcml" tells Gnus only to use files with the -suffix .prcml. - -OK, now you only need to tell Gnus how to send mail. If you -want to send mail via sendmail (or whichever MTA is playing -the role of sendmail on your system), you don't need to do -anything. However, if you want to send your mail to an -SMTP Server you need the following in your ~/.gnus.el - -@example -(setq send-mail-function 'smtpmail-send-it) -(setq message-send-mail-function 'smtpmail-send-it) -(setq smtpmail-default-smtp-server "smtp.yourProvider.net") -@end example -@noindent - -@node FAQ 3-9 -@subsubheading Question 3.9 - -And what about IMAP? - -@subsubheading Answer - -There are two ways of using IMAP with Gnus. The first one is -to use IMAP like POP3, that means Gnus fetches the mail from -the IMAP server and stores it on disk. If you want to do -this (you don't really want to do this) add the following to -~/.gnus.el - -@example -(add-to-list 'mail-sources '(imap :server "mail.mycorp.com" - :user "username" - :pass "password" - :stream network - :authentication login - :mailbox "INBOX" - :fetchflag "\\Seen")) -@end example -@noindent - -You might have to tweak the values for stream and/or -authentication, see the Gnus manual node "Mail Source -Specifiers" for possible values. - -If you want to use IMAP the way it's intended, you've got to -follow a different approach. You've got to add the nnimap -back end to your select method and give the information -about the server there. - -@example -(add-to-list 'gnus-secondary-select-methods - '(nnimap "Give the baby a name" - (nnimap-address "imap.yourProvider.net") - (nnimap-port 143) - (nnimap-list-pattern "archive.*"))) -@end example -@noindent - -Again, you might have to specify how to authenticate to the -server if Gnus can't guess the correct way, see the Manual -Node "IMAP" for detailed information. - -@node FAQ 3-10 -@subsubheading Question 3.10 - -At the office we use one of those MS Exchange servers, can I use -Gnus to read my mail from it? - -@subsubheading Answer - -Offer your administrator a pair of new running shoes for -activating IMAP on the server and follow the instructions -above. - -@node FAQ 3-11 -@subsubheading Question 3.11 - -Can I tell Gnus not to delete the mails on the server it -retrieves via POP3? - -@subsubheading Answer - -First of all, that's not the way POP3 is intended to work, -if you have the possibility, you should use the IMAP -Protocol if you want your messages to stay on the -server. Nevertheless there might be situations where you -need the feature, but sadly Gnus itself has no predefined -functionality to do so. - -However this is Gnus county so there are possibilities to -achieve what you want. The easiest way is to get an external -program which retrieves copies of the mail and stores them -on disk, so Gnus can read it from there. On Unix systems you -could use e.g. fetchmail for this, on MS Windows you can use -Hamster, an excellent local news and mail server. - -The other solution would be, to replace the method Gnus -uses to get mail from POP3 servers by one which is capable -of leaving the mail on the server. If you use XEmacs, get -the package mail-lib, it includes an enhanced pop3.el, -look in the file, there's documentation on how to tell -Gnus to use it and not to delete the retrieved mail. For -GNU Emacs look for the file epop3.el which can do the same -(If you know the home of this file, please send me an -e-mail). You can also tell Gnus to use an external program -(e.g. fetchmail) to fetch your mail, see the info node -"Mail Source Specifiers" in the Gnus manual on how to do -it. - -@node FAQ 4 - Reading messages -@subsection Reading messages - -@menu -* FAQ 4-1:: When I enter a group, all read messages are gone. How to - view them again? -* FAQ 4-2:: How to tell Gnus to show an important message every time - I enter a group, even when it's read? -* FAQ 4-3:: How to view the headers of a message? -* FAQ 4-4:: How to view the raw unformatted message? -* FAQ 4-5:: How can I change the headers Gnus displays by default at - the top of the article buffer? -* FAQ 4-6:: I'd like Gnus NOT to render HTML-mails but show me the - text part if it's available. How to do it? -* FAQ 4-7:: Can I use some other browser than w3 to render my - HTML-mails? -* FAQ 4-8:: Is there anything I can do to make poorly formatted - mails more readable? -* FAQ 4-9:: Is there a way to automatically ignore posts by specific - authors or with specific words in the subject? And can I - highlight more interesting ones in some way? -* FAQ 4-10:: How can I disable threading in some (e.g. mail-) groups, - or set other variables specific for some groups? -* FAQ 4-11:: Can I highlight messages written by me and follow-ups to - those? -* FAQ 4-12:: The number of total messages in a group which Gnus - displays in group buffer is by far to high, especially in mail - groups. Is this a bug? -* FAQ 4-13:: I don't like the layout of summary and article buffer, - how to change it? Perhaps even a three pane display? -* FAQ 4-14:: I don't like the way the Summary buffer looks, how to - tweak it? -* FAQ 4-15:: How to split incoming mails in several groups? -@end menu - -@node FAQ 4-1 -@subsubheading Question 4.1 - -When I enter a group, all read messages are gone. How to view them again? - -@subsubheading Answer - -If you enter the group by saying -@samp{RET} -in group buffer with point over the group, only unread and ticked messages are loaded. Say -@samp{C-u RET} -instead to load all available messages. If you want only the e.g. 300 newest say -@samp{C-u 300 RET} - -Loading only unread messages can be annoying if you have threaded view enabled, say - -@example -(setq gnus-fetch-old-headers 'some) -@end example -@noindent - -in ~/.gnus.el to load enough old articles to prevent teared threads, replace 'some with t to load -all articles (Warning: Both settings enlarge the amount of data which is -fetched when you enter a group and slow down the process of entering a group). - -If you already use Gnus 5.10, you can say -@samp{/o N} -In summary buffer to load the last N messages, this feature is not available in 5.8.8 - -If you don't want all old messages, but the parent of the message you're just reading, -you can say @samp{^}, if you want to retrieve the whole thread -the message you're just reading belongs to, @samp{A T} is your friend. - -@node FAQ 4-2 -@subsubheading Question 4.2 - -How to tell Gnus to show an important message every time I -enter a group, even when it's read? - -@subsubheading Answer - -You can tick important messages. To do this hit -@samp{u} while point is in summary buffer -over the message. When you want to remove the mark, hit -either @samp{d} (this deletes the tick -mark and set's unread mark) or @samp{M c} -(which deletes all marks for the message). - -@node FAQ 4-3 -@subsubheading Question 4.3 - -How to view the headers of a message? - -@subsubheading Answer - -Say @samp{t} -to show all headers, one more -@samp{t} -hides them again. - -@node FAQ 4-4 -@subsubheading Question 4.4 - -How to view the raw unformatted message? - -@subsubheading Answer - -Say -@samp{C-u g} -to show the raw message -@samp{g} -returns to normal view. - -@node FAQ 4-5 -@subsubheading Question 4.5 - -How can I change the headers Gnus displays by default at -the top of the article buffer? - -@subsubheading Answer - -The variable gnus-visible-headers controls which headers -are shown, its value is a regular expression, header lines -which match it are shown. So if you want author, subject, -date, and if the header exists, Followup-To and MUA / NUA -say this in ~/.gnus.el: - -@example -(setq gnus-visible-headers - '("^From" "^Subject" "^Date" "^Newsgroups" "^Followup-To" - "^User-Agent" "^X-Newsreader" "^X-Mailer")) -@end example -@noindent - -@node FAQ 4-6 -@subsubheading Question 4.6 - -I'd like Gnus NOT to render HTML-mails but show me the -text part if it's available. How to do it? - -@subsubheading Answer - -Say - -@example -(eval-after-load "mm-decode" - '(progn - (add-to-list 'mm-discouraged-alternatives "text/html") - (add-to-list 'mm-discouraged-alternatives "text/richtext"))) -@end example -@noindent - -in ~/.gnus.el. If you don't want HTML rendered, even if there's no text alternative add - -@example -(setq mm-automatic-display (remove "text/html" mm-automatic-display)) -@end example -@noindent - -too. - -@node FAQ 4-7 -@subsubheading Question 4.7 - -Can I use some other browser than w3 to render my HTML-mails? - -@subsubheading Answer - -Only if you use Gnus 5.10 or younger. In this case you've got the -choice between w3, w3m, links, lynx and html2text, which -one is used can be specified in the variable -mm-text-html-renderer, so if you want links to render your -mail say - -@example -(setq mm-text-html-renderer 'links) -@end example -@noindent - -@node FAQ 4-8 -@subsubheading Question 4.8 - -Is there anything I can do to make poorly formatted mails -more readable? - -@subsubheading Answer - -Gnus offers you several functions to "wash" incoming mail, you can -find them if you browse through the menu, item -Article->Washing. The most interesting ones are probably "Wrap -long lines" (@samp{W w}), "Decode ROT13" -(@samp{W r}) and "Outlook Deuglify" which repairs -the dumb quoting used by many users of Microsoft products -(@samp{W Y f} gives you full deuglify. -See @samp{W Y C-h} or have a look at the menus for -other deuglifications). Outlook deuglify is only available since -Gnus 5.10. - -@node FAQ 4-9 -@subsubheading Question 4.9 - -Is there a way to automatically ignore posts by specific -authors or with specific words in the subject? And can I -highlight more interesting ones in some way? - -@subsubheading Answer - -You want Scoring. Scoring means, that you define rules -which assign each message an integer value. Depending on -the value the message is highlighted in summary buffer (if -it's high, say +2000) or automatically marked read (if the -value is low, say -800) or some other action happens. - -There are basically three ways of setting up rules which assign -the scoring-value to messages. The first and easiest way is to set -up rules based on the article you are just reading. Say you're -reading a message by a guy who always writes nonsense and you want -to ignore his messages in the future. Hit -@samp{L}, to set up a rule which lowers the score. -Now Gnus asks you which the criteria for lowering the Score shall -be. Hit @samp{?} twice to see all possibilities, -we want @samp{a} which means the author (the from -header). Now Gnus wants to know which kind of matching we want. -Hit either @samp{e} for an exact match or -@samp{s} for substring-match and delete afterwards -everything but the name to score down all authors with the given -name no matter which email address is used. Now you need to tell -Gnus when to apply the rule and how long it should last, hit e.g. -@samp{p} to apply the rule now and let it last -forever. If you want to raise the score instead of lowering it say -@samp{I} instead of @samp{L}. - -You can also set up rules by hand. To do this say @samp{V -f} in summary buffer. Then you are asked for the name -of the score file, it's name.of.group.SCORE for rules valid in -only one group or all.Score for rules valid in all groups. See the -Gnus manual for the exact syntax, basically it's one big list -whose elements are lists again. the first element of those lists -is the header to score on, then one more list with what to match, -which score to assign, when to expire the rule and how to do the -matching. If you find me very interesting, you could e.g. add the -following to your all.Score: - -@example -(("references" ("hschmi22.userfqdn.rz-online.de" 500 nil s)) - ("message-id" ("hschmi22.userfqdn.rz-online.de" 999 nil s))) -@end example -@noindent - -This would add 999 to the score of messages written by me -and 500 to the score of messages which are a (possibly -indirect) answer to a message written by me. Of course -nobody with a sane mind would do this :-) - -The third alternative is adaptive scoring. This means Gnus -watches you and tries to find out what you find -interesting and what annoying and sets up rules -which reflect this. Adaptive scoring can be a huge help -when reading high traffic groups. If you want to activate -adaptive scoring say - -@example -(setq gnus-use-adaptive-scoring t) -@end example -@noindent - -in ~/.gnus.el. - -@node FAQ 4-10 -@subsubheading Question 4.10 - -How can I disable threading in some (e.g. mail-) groups, or -set other variables specific for some groups? - -@subsubheading Answer - -While in group buffer move point over the group and hit -@samp{G c}, this opens a buffer where you -can set options for the group. At the bottom of the buffer -you'll find an item that allows you to set variables -locally for the group. To disable threading enter -gnus-show-threads as name of variable and nil as -value. Hit button done at the top of the buffer when -you're ready. - -@node FAQ 4-11 -@subsubheading Question 4.11 - -Can I highlight messages written by me and follow-ups to -those? - -@subsubheading Answer - -Stop those "Can I ..." questions, the answer is always yes -in Gnus Country :-). It's a three step process: First we -make faces (specifications of how summary-line shall look -like) for those postings, then we'll give them some -special score and finally we'll tell Gnus to use the new -faces. - -@node FAQ 4-12 -@subsubheading Question 4.12 - -The number of total messages in a group which Gnus -displays in group buffer is by far to high, especially in -mail groups. Is this a bug? - -@subsubheading Answer - -No, that's a matter of design of Gnus, fixing this would -mean reimplementation of major parts of Gnus' -back ends. Gnus thinks "highest-article-number - -lowest-article-number = total-number-of-articles". This -works OK for Usenet groups, but if you delete and move -many messages in mail groups, this fails. To cure the -symptom, enter the group via @samp{C-u RET} -(this makes Gnus get all messages), then -hit @samp{M P b} to mark all messages and -then say @samp{B m name.of.group} to move -all messages to the group they have been in before, they -get new message numbers in this process and the count is -right again (until you delete and move your mail to other -groups again). - -@node FAQ 4-13 -@subsubheading Question 4.13 - -I don't like the layout of summary and article buffer, how -to change it? Perhaps even a three pane display? - -@subsubheading Answer - -You can control the windows configuration by calling the -function gnus-add-configuration. The syntax is a bit -complicated but explained very well in the manual node -"Window Layout". Some popular examples: - -Instead 25% summary 75% article buffer 35% summary and 65% -article (the 1.0 for article means "take the remaining -space"): - -@example -(gnus-add-configuration - '(article (vertical 1.0 (summary .35 point) (article 1.0)))) -@end example -@noindent - -A three pane layout, Group buffer on the left, summary -buffer top-right, article buffer bottom-right: - -@example -(gnus-add-configuration - '(article - (horizontal 1.0 - (vertical 25 - (group 1.0)) - (vertical 1.0 - (summary 0.25 point) - (article 1.0))))) -(gnus-add-configuration - '(summary - (horizontal 1.0 - (vertical 25 - (group 1.0)) - (vertical 1.0 - (summary 1.0 point))))) -@end example -@noindent - -@node FAQ 4-14 -@subsubheading Question 4.14 - -I don't like the way the Summary buffer looks, how to tweak it? - -@subsubheading Answer - -You've got to play around with the variable -gnus-summary-line-format. Its value is a string of -symbols which stand for things like author, date, subject -etc. A list of the available specifiers can be found in the -manual node "Summary Buffer Lines" and the often forgotten -node "Formatting Variables" and its sub-nodes. There -you'll find useful things like positioning the cursor and -tabulators which allow you a summary in table form, but -sadly hard tabulators are broken in 5.8.8. - -Since 5.10, Gnus offers you some very nice new specifiers, -e.g. %B which draws a thread-tree and %&user-date which -gives you a date where the details are dependent of the -articles age. Here's an example which uses both: - -@example -(setq gnus-summary-line-format ":%U%R %B %s %-60=|%4L |%-20,20f |%&user-date; \n") -@end example -@noindent - -resulting in: - -@example -:O Re: [Richard Stallman] rfc2047.el | 13 |Lars Magne Ingebrigt |Sat 23:06 -:O Re: Revival of the ding-patches list | 13 |Lars Magne Ingebrigt |Sat 23:12 -:R > Re: Find correct list of articles for a gro| 25 |Lars Magne Ingebrigt |Sat 23:16 -:O \-> ... | 21 |Kai Grossjohann | 0:01 -:R > Re: Cry for help: deuglify.el - moving stuf| 28 |Lars Magne Ingebrigt |Sat 23:34 -:O \-> ... | 115 |Raymond Scholz | 1:24 -:O \-> ... | 19 |Lars Magne Ingebrigt |15:33 -:O Slow mailing list | 13 |Lars Magne Ingebrigt |Sat 23:49 -:O Re: `@@' mark not documented | 13 |Lars Magne Ingebrigt |Sat 23:50 -:R > Re: Gnus still doesn't count messages prope| 23 |Lars Magne Ingebrigt |Sat 23:57 -:O \-> ... | 18 |Kai Grossjohann | 0:35 -:O \-> ... | 13 |Lars Magne Ingebrigt | 0:56 -@end example -@noindent - -@node FAQ 4-15 -@subsubheading Question 4.15 - -How to split incoming mails in several groups? - -@subsubheading Answer - -Gnus offers two possibilities for splitting mail, the easy -nnmail-split-methods and the more powerful Fancy Mail -Splitting. I'll only talk about the first one, refer to -the manual, node "Fancy Mail Splitting" for the latter. - -The value of nnmail-split-methods is a list, each element -is a list which stands for a splitting rule. Each rule has -the form "group where matching articles should go to", -"regular expression which has to be matched", the first -rule which matches wins. The last rule must always be a -general rule (regular expression .*) which denotes where -articles should go which don't match any other rule. If -the folder doesn't exist yet, it will be created as soon -as an article lands there. By default the mail will be -send to all groups whose rules match. If you -don't want that (you probably don't want), say - -@example -(setq nnmail-crosspost nil) -@end example -@noindent - -in ~/.gnus.el. - -An example might be better than thousand words, so here's -my nnmail-split-methods. Note that I send duplicates in a -special group and that the default group is spam, since I -filter all mails out which are from some list I'm -subscribed to or which are addressed directly to me -before. Those rules kill about 80% of the Spam which -reaches me (Email addresses are changed to prevent spammers -from using them): - -@example -(setq nnmail-split-methods - '(("duplicates" "^Gnus-Warning:.*duplicate") - ("XEmacs-NT" "^\\(To:\\|CC:\\).*localpart@@xemacs.invalid.*") - ("Gnus-Tut" "^\\(To:\\|CC:\\).*localpart@@socha.invalid.*") - ("tcsh" "^\\(To:\\|CC:\\).*localpart@@mx.gw.invalid.*") - ("BAfH" "^\\(To:\\|CC:\\).*localpart@@.*uni-muenchen.invalid.*") - ("Hamster-src" "^\\(CC:\\|To:\\).*hamster-sourcen@@yahoogroups.\\(de\\|com\\).*") - ("Tagesschau" "^From: tagesschau $") - ("Replies" "^\\(CC:\\|To:\\).*localpart@@Frank-Schmitt.invalid.*") - ("EK" "^From:.*\\(localpart@@privateprovider.invalid\\|localpart@@workplace.invalid\\).*") - ("Spam" "^Content-Type:.*\\(ks_c_5601-1987\\|EUC-KR\\|big5\\|iso-2022-jp\\).*") - ("Spam" "^Subject:.*\\(This really work\\|XINGA\\|ADV:\\|XXX\\|adult\\|sex\\).*") - ("Spam" "^Subject:.*\\(\=\?ks_c_5601-1987\?\\|\=\?euc-kr\?\\|\=\?big5\?\\).*") - ("Spam" "^X-Mailer:\\(.*BulkMailer.*\\|.*MIME::Lite.*\\|\\)") - ("Spam" "^X-Mailer:\\(.*CyberCreek Avalanche\\|.*http\:\/\/GetResponse\.com\\)") - ("Spam" "^From:.*\\(verizon\.net\\|prontomail\.com\\|money\\|ConsumerDirect\\).*") - ("Spam" "^Delivered-To: GMX delivery to spamtrap@@gmx.invalid$") - ("Spam" "^Received: from link2buy.com") - ("Spam" "^CC: .*azzrael@@t-online.invalid") - ("Spam" "^X-Mailer-Version: 1.50 BETA") - ("Uni" "^\\(CC:\\|To:\\).*localpart@@uni-koblenz.invalid.*") - ("Inbox" "^\\(CC:\\|To:\\).*\\(my\ name\\|address@@one.invalid\\|address@@two.invalid\\)") - ("Spam" ""))) -@end example -@noindent - -@node FAQ 5 - Composing messages -@subsection Composing messages - -@menu -* FAQ 5-1:: What are the basic commands I need to know for sending - mail and postings? -* FAQ 5-2:: How to enable automatic word-wrap when composing - messages? -* FAQ 5-3:: How to set stuff like From, Organization, Reply-To, - signature...? -* FAQ 5-4:: Can I set things like From, Signature etc group based on - the group I post too? -* FAQ 5-5:: Is there a spell-checker? Perhaps even on-the-fly - spell-checking? -* FAQ 5-6:: Can I set the dictionary based on the group I'm posting - to? -* FAQ 5-7:: Is there some kind of address-book, so I needn't - remember all those email addresses? -* FAQ 5-8:: Sometimes I see little images at the top of article - buffer. What's that and how can I send one with my postings, - too? -* FAQ 5-9:: Sometimes I accidentally hit r instead of f in - newsgroups. Can Gnus warn me, when I'm replying by mail in - newsgroups? -* FAQ 5-10:: How to tell Gnus not to generate a sender header? -* FAQ 5-11:: I want Gnus to locally store copies of my send mail and - news, how to do it? -* FAQ 5-12:: I want Gnus to kill the buffer after successful sending - instead of keeping it alive as "Sent mail to...", how to do it? -* FAQ 5-13:: People tell me my Message-IDs are not correct, why - aren't they and how to fix it? -@end menu - -@node FAQ 5-1 -@subsubheading Question 5.1 - -What are the basic commands I need to know for sending mail and postings? - -@subsubheading Answer - -To start composing a new mail hit @samp{m} -either in Group or Summary buffer, for a posting, it's -either @samp{a} in Group buffer and -filling the Newsgroups header manually -or @samp{a} in the Summary buffer of the -group where the posting shall be send to. Replying by mail -is -@samp{r} if you don't want to cite the -author, or import the cited text manually and -@samp{R} to cite the text of the original -message. For a follow up to a newsgroup, it's -@samp{f} and @samp{F} -(analogously to @samp{r} and -@samp{R}). - -Enter new headers above the line saying "--text follows -this line--", enter the text below the line. When ready -hit @samp{C-c C-c}, to send the message, -if you want to finish it later hit @samp{C-c -C-d} to save it in the drafts group, where you -can start editing it again by saying @samp{D -e}. - -@node FAQ 5-2 -@subsubheading Question 5.2 - -How to enable automatic word-wrap when composing messages? - -@subsubheading Answer - -Starting from No Gnus, automatic word-wrap is already enabled by -default, see the variable message-fill-column. - -For other versions of Gnus, say - -@example -(unless (boundp 'message-fill-column) - (add-hook 'message-mode-hook - (lambda () - (setq fill-column 72) - (turn-on-auto-fill)))) -@end example -@noindent - -in ~/.gnus.el. - -You can reformat a paragraph by hitting @samp{M-q} -(as usual). - -@node FAQ 5-3 -@subsubheading Question 5.3 - -How to set stuff like From, Organization, Reply-To, signature...? - -@subsubheading Answer - -There are other ways, but you should use posting styles -for this. (See below why). -This example should make the syntax clear: - -@example -(setq gnus-posting-styles - '((".*" - (name "Frank Schmitt") - (address "me@@there.invalid") - (organization "Hamme net, kren mer och nimmi") - (signature-file "~/.signature") - ("X-SampleHeader" "foobar") - (eval (setq some-variable "Foo bar"))))) -@end example -@noindent - -The ".*" means that this settings are the default ones -(see below), valid values for the first element of the -following lists are signature, signature-file, -organization, address, name or body. The attribute name -can also be a string. In that case, this will be used as -a header name, and the value will be inserted in the -headers of the article; if the value is `nil', the header -name will be removed. You can also say (eval (foo bar)), -then the function foo will be evaluated with argument bar -and the result will be thrown away. - -@node FAQ 5-4 -@subsubheading Question 5.4 - -Can I set things like From, Signature etc group based on the group I post too? - -@subsubheading Answer - -That's the strength of posting styles. Before, we used ".*" -to set the default for all groups. You can use a regexp -like "^gmane" and the following settings are only applied -to postings you send to the gmane hierarchy, use -".*binaries" instead and they will be applied to postings -send to groups containing the string binaries in their -name etc. - -You can instead of specifying a regexp specify a function -which is evaluated, only if it returns true, the -corresponding settings take effect. Two interesting -candidates for this are message-news-p which returns t if -the current Group is a newsgroup and the corresponding -message-mail-p. - -Note that all forms that match are applied, that means in -the example below, when I post to -gmane.mail.spam.spamassassin.general, the settings under -".*" are applied and the settings under message-news-p and -those under "^gmane" and those under -"^gmane\\.mail\\.spam\\.spamassassin\\.general$". Because -of this put general settings at the top and specific ones -at the bottom. - -@example -(setq gnus-posting-styles - '((".*" ;;default - (name "Frank Schmitt") - (organization "Hamme net, kren mer och nimmi") - (signature-file "~/.signature")) - ((message-news-p) ;;Usenet news? - (address "mySpamTrap@@Frank-Schmitt.invalid") - (reply-to "hereRealRepliesOnlyPlease@@Frank-Schmitt.invalid")) - ((message-mail-p) ;;mail? - (address "usedForMails@@Frank-Schmitt.invalid")) - ("^gmane" ;;this is mail, too in fact - (address "usedForMails@@Frank-Schmitt.invalid") - (reply-to nil)) - ("^gmane\\.mail\\.spam\\.spamassassin\\.general$" - (eval (set (make-local-variable 'message-sendmail-envelope-from) - "Azzrael@@rz-online.de"))))) -@end example -@noindent - -@node FAQ 5-5 -@subsubheading Question 5.5 - -Is there a spell-checker? Perhaps even on-the-fly spell-checking? - -@subsubheading Answer - -You can use ispell.el to spell-check stuff in Emacs. So the -first thing to do is to make sure that you've got either -@uref{http://fmg-www.cs.ucla.edu/fmg-members/geoff/ispell.html, ispell} -or @uref{http://aspell.sourceforge.net/, aspell} -installed and in your Path. Then you need -@uref{http://www.kdstevens.com/~stevens/ispell-page.html, ispell.el} -and for on-the-fly spell-checking -@uref{http://www-sop.inria.fr/members/Manuel.Serrano/flyspell/flyspell.html, flyspell.el}. -Ispell.el is shipped with Emacs and available through the XEmacs package system, -flyspell.el is shipped with Emacs and part of XEmacs text-modes package which is -available through the package system, so there should be no need to install them -manually. - -Ispell.el assumes you use ispell, if you choose aspell say - -@example -(setq ispell-program-name "aspell") -@end example -@noindent - -in your Emacs configuration file. - -If you want your outgoing messages to be spell-checked, say - -@example -(add-hook 'message-send-hook 'ispell-message) -@end example -@noindent - -In your ~/.gnus.el, if you prefer on-the-fly spell-checking say - -@example -(add-hook 'message-mode-hook (lambda () (flyspell-mode 1))) -@end example -@noindent - -@node FAQ 5-6 -@subsubheading Question 5.6 - -Can I set the dictionary based on the group I'm posting to? - -@subsubheading Answer - -Yes, say something like - -@example -(add-hook 'gnus-select-group-hook - (lambda () - (cond - ((string-match - "^de\\." (gnus-group-real-name gnus-newsgroup-name)) - (ispell-change-dictionary "deutsch8")) - (t - (ispell-change-dictionary "english"))))) -@end example -@noindent - -in ~/.gnus.el. Change "^de\\." and "deutsch8" to something -that suits your needs. - -@node FAQ 5-7 -@subsubheading Question 5.7 - -Is there some kind of address-book, so I needn't remember -all those email addresses? - -@subsubheading Answer - -There's an very basic solution for this, mail aliases. -You can store your mail addresses in a ~/.mailrc file using a simple -alias syntax: - -@example -alias al "Al " -@end example -@noindent - -Then typing your alias (followed by a space or punctuation -character) on a To: or Cc: line in the message buffer will -cause Gnus to insert the full address for you. See the -node "Mail Aliases" in Message (not Gnus) manual for -details. - -However, what you really want is the Insidious Big Brother -Database bbdb. Get it through the XEmacs package system or from -@uref{http://bbdb.sourceforge.net/, bbdb's homepage}. -Now place the following in ~/.gnus.el, to activate bbdb for Gnus: - -@example -(require 'bbdb) -(bbdb-initialize 'gnus 'message) -@end example -@noindent - -Now you probably want some general bbdb configuration, -place them in ~/.emacs: - -@example -(require 'bbdb) -;;If you don't live in Northern America, you should disable the -;;syntax check for telephone numbers by saying -(setq bbdb-north-american-phone-numbers-p nil) -;;Tell bbdb about your email address: -(setq bbdb-user-mail-names - (regexp-opt '("Your.Email@@here.invalid" - "Your.other@@mail.there.invalid"))) -;;cycling while completing email addresses -(setq bbdb-complete-name-allow-cycling t) -;;No popup-buffers -(setq bbdb-use-pop-up nil) -@end example -@noindent - -Now you should be ready to go. Say @samp{M-x bbdb RET -RET} to open a bbdb buffer showing all -entries. Say @samp{c} to create a new -entry, @samp{b} to search your BBDB and -@samp{C-o} to add a new field to an -entry. If you want to add a sender to the BBDB you can -also just hit `:' on the posting in the summary buffer and -you are done. When you now compose a new mail, -hit @samp{TAB} to cycle through know -recipients. - -@node FAQ 5-8 -@subsubheading Question 5.8 - -Sometimes I see little images at the top of article -buffer. What's that and how can I send one with my -postings, too? - -@subsubheading Answer - -Those images are called X-Faces. They are 48*48 pixel b/w -pictures, encoded in a header line. If you want to include -one in your posts, you've got to convert some image to a -X-Face. So fire up some image manipulation program (say -Gimp), open the image you want to include, cut out the -relevant part, reduce color depth to 1 bit, resize to -48*48 and save as bitmap. Now you should get the compface -package from -@uref{ftp://ftp.cs.indiana.edu:/pub/faces/, this site}. -and create the actual X-face by saying - -@example -cat file.xbm | xbm2ikon | compface > file.face -cat file.face | sed 's/\\/\\\\/g;s/\"/\\\"/g;' > file.face.quoted -@end example -@noindent - -If you can't use compface, there's an online X-face converter at -@uref{http://www.dairiki.org/xface/}. -If you use MS Windows, you could also use the WinFace program from -@uref{http://www.xs4all.nl/~walterln/winface/}. -Now you only have to tell Gnus to include the X-face in your postings by saying - -@example -(setq message-default-headers - (with-temp-buffer - (insert "X-Face: ") - (insert-file-contents "~/.xface") - (buffer-string))) -@end example -@noindent - -in ~/.gnus.el. If you use Gnus 5.10, you can simply add an entry - -@example -(x-face-file "~/.xface") -@end example -@noindent - -to gnus-posting-styles. - -@node FAQ 5-9 -@subsubheading Question 5.9 - -Sometimes I accidentally hit r instead of f in -newsgroups. Can Gnus warn me, when I'm replying by mail in -newsgroups? - -@subsubheading Answer - -Put this in ~/.gnus.el: - -@example -(setq gnus-confirm-mail-reply-to-news t) -@end example -@noindent - -if you already use Gnus 5.10, if you still use 5.8.8 or -5.9 try this instead: - -@example -(eval-after-load "gnus-msg" - '(unless (boundp 'gnus-confirm-mail-reply-to-news) - (defadvice gnus-summary-reply (around reply-in-news activate) - "Request confirmation when replying to news." - (interactive) - (when (or (not (gnus-news-group-p gnus-newsgroup-name)) - (y-or-n-p "Really reply by mail to article author? ")) - ad-do-it)))) -@end example -@noindent - -@node FAQ 5-10 -@subsubheading Question 5.10 - -How to tell Gnus not to generate a sender header? - -@subsubheading Answer - -Since 5.10 Gnus doesn't generate a sender header by -default. For older Gnus' try this in ~/.gnus.el: - -@example -(eval-after-load "message" - '(add-to-list 'message-syntax-checks '(sender . disabled))) -@end example -@noindent - -@node FAQ 5-11 -@subsubheading Question 5.11 - -I want Gnus to locally store copies of my send mail and -news, how to do it? - -@subsubheading Answer - -You must set the variable gnus-message-archive-group to do -this. You can set it to a string giving the name of the -group where the copies shall go or like in the example -below use a function which is evaluated and which returns -the group to use. - -@example -(setq gnus-message-archive-group - '((if (message-news-p) - "nnml:Send-News" - "nnml:Send-Mail"))) -@end example -@noindent - -@node FAQ 5-12 -@subsubheading Question 5.12 - -I want Gnus to kill the buffer after successful sending instead of keeping -it alive as "Sent mail to...", how to do it? - -@subsubheading Answer - -Add this to your ~/.gnus: - -@example -(setq message-kill-buffer-on-exit t) -@end example -@noindent - -@node FAQ 5-13 -@subsubheading Question 5.13 - -People tell me my Message-IDs are not correct, why -aren't they and how to fix it? - -@subsubheading Answer - -The message-ID is an unique identifier for messages you -send. To make it unique, Gnus need to know which machine -name to put after the "@@". If the name of the machine -where Gnus is running isn't suitable (it probably isn't -at most private machines) you can tell Gnus what to use -by saying: - -@example -(setq message-user-fqdn "yourmachine.yourdomain.tld") -@end example -@noindent - -in ~/.gnus.el. If you use Gnus 5.9 or earlier, you can use this -instead (works for newer versions as well): - -@example -(eval-after-load "message" - '(let ((fqdn "yourmachine.yourdomain.tld"));; <-- Edit this! - (if (boundp 'message-user-fqdn) - (setq message-user-fqdn fqdn) - (gnus-message 1 "Redefining `message-make-fqdn'.") - (defun message-make-fqdn () - "Return user's fully qualified domain name." - fqdn)))) -@end example -@noindent - -If you have no idea what to insert for -"yourmachine.yourdomain.tld", you've got several -choices. You can either ask your provider if he allows -you to use something like -yourUserName.userfqdn.provider.net, or you can use -somethingUnique.yourdomain.tld if you own the domain -yourdomain.tld, or you can register at a service which -gives private users a FQDN for free. - -Finally you can tell Gnus not to generate a Message-ID -for News at all (and letting the server do the job) by saying - -@example -(setq message-required-news-headers - (remove' Message-ID message-required-news-headers)) -@end example -@noindent - -you can also tell Gnus not to generate Message-IDs for mail by saying - -@example -(setq message-required-mail-headers - (remove' Message-ID message-required-mail-headers)) -@end example -@noindent - -, however some mail servers don't generate proper -Message-IDs, too, so test if your Mail Server behaves -correctly by sending yourself a Mail and looking at the Message-ID. - -@node FAQ 6 - Old messages -@subsection Old messages - -@menu -* FAQ 6-1:: How to import my old mail into Gnus? -* FAQ 6-2:: How to archive interesting messages? -* FAQ 6-3:: How to search for a specific message? -* FAQ 6-4:: How to get rid of old unwanted mail? -* FAQ 6-5:: I want that all read messages are expired (at least in - some groups). How to do it? -* FAQ 6-6:: I don't want expiration to delete my mails but to move - them to another group. -@end menu - -@node FAQ 6-1 -@subsubheading Question 6.1 - -How to import my old mail into Gnus? - -@subsubheading Answer - -The easiest way is to tell your old mail program to -export the messages in mbox format. Most Unix mailers -are able to do this, if you come from the MS Windows -world, you may find tools at -@uref{http://mbx2mbox.sourceforge.net/}. - -Now you've got to import this mbox file into Gnus. To do -this, create a nndoc group based on the mbox file by -saying @samp{G f /path/file.mbox RET} in -Group buffer. You now have read-only access to your -mail. If you want to import the messages to your normal -Gnus mail groups hierarchy, enter the nndoc group you've -just created by saying @samp{C-u RET} -(thus making sure all messages are retrieved), mark all -messages by saying @samp{M P b} and -either copy them to the desired group by saying -@samp{B c name.of.group RET} or send them -through nnmail-split-methods (respool them) by saying -@samp{B r}. - -@node FAQ 6-2 -@subsubheading Question 6.2 - -How to archive interesting messages? - -@subsubheading Answer - -If you stumble across an interesting message, say in -gnu.emacs.gnus and want to archive it there are several -solutions. The first and easiest is to save it to a file -by saying @samp{O f}. However, wouldn't -it be much more convenient to have more direct access to -the archived message from Gnus? If you say yes, put this -snippet by Frank Haun in -~/.gnus.el: - -@example -(defun my-archive-article (&optional n) - "Copies one or more article(s) to a corresponding `nnml:' group, e.g. -`gnus.ding' goes to `nnml:1.gnus.ding'. And `nnml:List-gnus.ding' goes -to `nnml:1.List-gnus-ding'. - -Use process marks or mark a region in the summary buffer to archive -more then one article." - (interactive "P") - (let ((archive-name - (format - "nnml:1.%s" - (if (featurep 'xemacs) - (replace-in-string gnus-newsgroup-name "^.*:" "") - (replace-regexp-in-string "^.*:" "" gnus-newsgroup-name))))) - (gnus-summary-copy-article n archive-name))) -@end example -@noindent - -You can now say @samp{M-x -my-archive-article} in summary buffer to -archive the article under the cursor in a nnml -group. (Change nnml to your preferred back end) - -Of course you can also make sure the cache is enabled by saying - -@example -(setq gnus-use-cache t) -@end example -@noindent - -then you only have to set either the tick or the dormant -mark for articles you want to keep, setting the read -mark will remove them from cache. - -@node FAQ 6-3 -@subsubheading Question 6.3 - -How to search for a specific message? - -@subsubheading Answer - -There are several ways for this, too. For a posting from -a Usenet group the easiest solution is probably to ask -@uref{http://groups.google.com, groups.google.com}, -if you found the posting there, tell Google to display -the raw message, look for the message-id, and say -@samp{M-^ the@@message.id RET} in a -summary buffer. -Since Gnus 5.10 there's also a Gnus interface for -groups.google.com which you can call with -@samp{G W}) in group buffer. - -Another idea which works for both mail and news groups -is to enter the group where the message you are -searching is and use the standard Emacs search -@samp{C-s}, it's smart enough to look at -articles in collapsed threads, too. If you want to -search bodies, too try @samp{M-s} -instead. Further on there are the -gnus-summary-limit-to-foo functions, which can help you, -too. - -Of course you can also use grep to search through your -local mail, but this is both slow for big archives and -inconvenient since you are not displaying the found mail -in Gnus. Here comes nnir into action. Nnir is a front end -to search engines like swish-e or swish++ and -others. You index your mail with one of those search -engines and with the help of nnir you can search through -the indexed mail and generate a temporary group with all -messages which met your search criteria. If this sound -cool to you get nnir.el from -@uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/} -or @uref{ftp://ftp.is.informatik.uni-duisburg.de/pub/src/emacs/}. -Instructions on how to use it are at the top of the file. - -@node FAQ 6-4 -@subsubheading Question 6.4 - -How to get rid of old unwanted mail? - -@subsubheading Answer - -You can of course just mark the mail you don't need -anymore by saying @samp{#} with point -over the mail and then say @samp{B DEL} -to get rid of them forever. You could also instead of -actually deleting them, send them to a junk-group by -saying @samp{B m nnml:trash-bin} which -you clear from time to time, but both are not the intended -way in Gnus. - -In Gnus, we let mail expire like news expires on a news -server. That means you tell Gnus the message is -expirable (you tell Gnus "I don't need this mail -anymore") by saying @samp{E} with point -over the mail in summary buffer. Now when you leave the -group, Gnus looks at all messages which you marked as -expirable before and if they are old enough (default is -older than a week) they are deleted. - -@node FAQ 6-5 -@subsubheading Question 6.5 - -I want that all read messages are expired (at least in -some groups). How to do it? - -@subsubheading Answer - -If you want all read messages to be expired (e.g. in -mailing lists where there's an online archive), you've -got two choices: auto-expire and -total-expire. Auto-expire means, that every article -which has no marks set and is selected for reading is -marked as expirable, Gnus hits @samp{E} -for you every time you read a message. Total-expire -follows a slightly different approach, here all article -where the read mark is set are expirable. - -To activate auto-expire, include auto-expire in the -Group parameters for the group. (Hit @samp{G -c} in summary buffer with point over the -group to change group parameters). For total-expire add -total-expire to the group-parameters. - -Which method you choose is merely a matter of taste: -Auto-expire is faster, but it doesn't play together with -Adaptive Scoring, so if you want to use this feature, -you should use total-expire. - -If you want a message to be excluded from expiration in -a group where total or auto expire is active, set either -tick (hit @samp{u}) or dormant mark (hit -@samp{u}), when you use auto-expire, you -can also set the read mark (hit -@samp{d}). - -@node FAQ 6-6 -@subsubheading Question 6.6 - -I don't want expiration to delete my mails but to move them -to another group. - -@subsubheading Answer - -Say something like this in ~/.gnus.el: - -@example -(setq nnmail-expiry-target "nnml:expired") -@end example -@noindent - -(If you want to change the value of nnmail-expiry-target -on a per group basis see the question "How can I disable -threading in some (e.g. mail-) groups, or set other -variables specific for some groups?") - -@node FAQ 7 - Gnus in a dial-up environment -@subsection Gnus in a dial-up environment - -@menu -* FAQ 7-1:: I don't have a permanent connection to the net, how can I - minimize the time I've got to be connected? -* FAQ 7-2:: So what was this thing about the Agent? -* FAQ 7-3:: I want to store article bodies on disk, too. How to do - it? -* FAQ 7-4:: How to tell Gnus not to try to send mails / postings - while I'm offline? -@end menu - -@node FAQ 7-1 -@subsubheading Question 7.1 - -I don't have a permanent connection to the net, how can -I minimize the time I've got to be connected? - -@subsubheading Answer - -You've got basically two options: Either you use the -Gnus Agent (see below) for this, or you can install -programs which fetch your news and mail to your local -disk and Gnus reads the stuff from your local -machine. - -If you want to follow the second approach, you need a -program which fetches news and offers them to Gnus, a -program which does the same for mail and a program which -receives the mail you write from Gnus and sends them -when you're online. - -Let's talk about Unix systems first: For the news part, -the easiest solution is a small nntp server like -@uref{http://www.leafnode.org/, Leafnode} or -@uref{http://infa.abo.fi/~patrik/sn/, sn}, -of course you can also install a full featured news -server like -@uref{http://www.isc.org/products/INN/, inn}. -Then you want to fetch your Mail, popular choices -are @uref{http://www.catb.org/~esr/fetchmail/, fetchmail} -and @uref{http://pyropus.ca/software/getmail/, getmail}. -You should tell those to write the mail to your disk and -Gnus to read it from there. Last but not least the mail -sending part: This can be done with every MTA like -@uref{http://www.sendmail.org/, sendmail}, -@uref{http://www.qmail.org/, postfix}, -@uref{http://www.exim.org/, exim} or -@uref{http://www.qmail.org/, qmail}. - -On windows boxes I'd vote for -@uref{http://www.tglsoft.de/, Hamster}, -it's a small freeware, open-source program which fetches -your mail and news from remote servers and offers them -to Gnus (or any other mail and/or news reader) via nntp -respectively POP3 or IMAP. It also includes a smtp -server for receiving mails from Gnus. - -@node FAQ 7-2 -@subsubheading Question 7.2 - -So what was this thing about the Agent? - -@subsubheading Answer - -The Gnus agent is part of Gnus, it allows you to fetch -mail and news and store them on disk for reading them -later when you're offline. It kind of mimics offline -newsreaders like e.g. Forte Agent. If you want to use -the Agent place the following in ~/.gnus.el if you are -still using 5.8.8 or 5.9 (it's the default since 5.10): - -@example -(setq gnus-agent t) -@end example -@noindent - -Now you've got to select the servers whose groups can be -stored locally. To do this, open the server buffer -(that is press @samp{^} while in the -group buffer). Now select a server by moving point to -the line naming that server. Finally, agentize the -server by typing @samp{J a}. If you -make a mistake, or change your mind, you can undo this -action by typing @samp{J r}. When -you're done, type 'q' to return to the group buffer. -Now the next time you enter a group on a agentized -server, the headers will be stored on disk and read from -there the next time you enter the group. - -@node FAQ 7-3 -@subsubheading Question 7.3 - -I want to store article bodies on disk, too. How to do it? - -@subsubheading Answer - -You can tell the agent to automatically fetch the bodies -of articles which fulfill certain predicates, this is -done in a special buffer which can be reached by -saying @samp{J c} in group -buffer. Please refer to the documentation for -information which predicates are possible and how -exactly to do it. - -Further on you can tell the agent manually which -articles to store on disk. There are two ways to do -this: Number one: In the summary buffer, process mark a -set of articles that shall be stored in the agent by -saying @samp{#} with point over the -article and then type @samp{J s}. The -other possibility is to set, again in the summary -buffer, downloadable (%) marks for the articles you -want by typing @samp{@@} with point over -the article and then typing @samp{J u}. -What's the difference? Well, process marks are erased as -soon as you exit the summary buffer while downloadable -marks are permanent. You can actually set downloadable -marks in several groups then use fetch session ('J s' in -the GROUP buffer) to fetch all of those articles. The -only downside is that fetch session also fetches all of -the headers for every selected group on an agentized -server. Depending on the volume of headers, the initial -fetch session could take hours. - -@node FAQ 7-4 -@subsubheading Question 7.4 - -How to tell Gnus not to try to send mails / postings -while I'm offline? - -@subsubheading Answer - -All you've got to do is to tell Gnus when you are online -(plugged) and when you are offline (unplugged), the rest -works automatically. You can toggle plugged/unplugged -state by saying @samp{J j} in group -buffer. To start Gnus unplugged say @samp{M-x -gnus-unplugged} instead of -@samp{M-x gnus}. Note that for this to -work, the agent must be active. - -@node FAQ 8 - Getting help -@subsection Getting help - -@menu -* FAQ 8-1:: How to find information and help inside Emacs? -* FAQ 8-2:: I can't find anything in the Gnus manual about X (e.g. - attachments, PGP, MIME...), is it not documented? -* FAQ 8-3:: Which websites should I know? -* FAQ 8-4:: Which mailing lists and newsgroups are there? -* FAQ 8-5:: Where to report bugs? -* FAQ 8-6:: I need real-time help, where to find it? -@end menu - -@node FAQ 8-1 -@subsubheading Question 8.1 - -How to find information and help inside Emacs? - -@subsubheading Answer - -The first stop should be the Gnus manual (Say -@samp{C-h i d m Gnus RET} to start the -Gnus manual, then walk through the menus or do a -full-text search with @samp{s}). Then -there are the general Emacs help commands starting with -C-h, type @samp{C-h ? ?} to get a list -of all available help commands and their meaning. Finally -@samp{M-x apropos-command} lets you -search through all available functions and @samp{M-x -apropos} searches the bound variables. - -@node FAQ 8-2 -@subsubheading Question 8.2 - -I can't find anything in the Gnus manual about X -(e.g. attachments, PGP, MIME...), is it not documented? - -@subsubheading Answer - -There's not only the Gnus manual but also the manuals for message, -emacs-mime, sieve, EasyPG Assistant, and pgg. Those packages are -distributed with Gnus and used by Gnus but aren't really part of core -Gnus, so they are documented in different info files, you should have -a look in those manuals, too. - -@node FAQ 8-3 -@subsubheading Question 8.3 - -Which websites should I know? - -@subsubheading Answer - -The most important one is the -@uref{http://www.gnus.org, official Gnus website}. - -Tell me about other sites which are interesting. - -@node FAQ 8-4 -@subsubheading Question 8.4 - -Which mailing lists and newsgroups are there? - -@subsubheading Answer - -There's the newsgroup gnu.emacs.gnus (also available as -@uref{http://dir.gmane.org/gmane.emacs.gnus.user, -gmane.emacs.gnus.user}) which deals with general Gnus -questions. If you have questions about development versions of -Gnus, you should better ask on the ding mailing list, see below. - -If you want to stay in the big8, -news.software.readers is also read by some Gnus -users (but chances for qualified help are much better in -the above groups). If you speak German, there's -de.comm.software.gnus. - -The ding mailing list (ding@@gnus.org) deals with development of -Gnus. You can read the ding list via NNTP, too under the name -@uref{http://dir.gmane.org/gmane.emacs.gnus.general, -gmane.emacs.gnus.general} from news.gmane.org. - -@node FAQ 8-5 -@subsubheading Question 8.5 - -Where to report bugs? - -@subsubheading Answer - -Say @samp{M-x gnus-bug}, this will start -a message to the -@email{bugs@@gnus.org, gnus bug mailing list} -including information about your environment which make -it easier to help you. - -@node FAQ 8-6 -@subsubheading Question 8.6 - -I need real-time help, where to find it? - -@subsubheading Answer - -Point your IRC client to irc.freenode.net, channel #gnus. - -@node FAQ 9 - Tuning Gnus -@subsection Tuning Gnus - -@menu -* FAQ 9-1:: Starting Gnus is really slow, how to speed it up? -* FAQ 9-2:: How to speed up the process of entering a group? -* FAQ 9-3:: Sending mail becomes slower and slower, what's up? -@end menu - -@node FAQ 9-1 -@subsubheading Question 9.1 - -Starting Gnus is really slow, how to speed it up? - -@subsubheading Answer - -The reason for this could be the way Gnus reads its -active file, see the node "The Active File" in the Gnus -manual for things you might try to speed the process up. -An other idea would be to byte compile your ~/.gnus.el (say -@samp{M-x byte-compile-file RET ~/.gnus.el -RET} to do it). Finally, if you have require -statements in your .gnus, you could replace them with -eval-after-load, which loads the stuff not at startup -time, but when it's needed. Say you've got this in your -~/.gnus.el: - -@example -(require 'message) -(add-to-list 'message-syntax-checks '(sender . disabled)) -@end example -@noindent - -then as soon as you start Gnus, message.el is loaded. If -you replace it with - -@example -(eval-after-load "message" - '(add-to-list 'message-syntax-checks '(sender . disabled))) -@end example -@noindent - -it's loaded when it's needed. - -@node FAQ 9-2 -@subsubheading Question 9.2 - -How to speed up the process of entering a group? - -@subsubheading Answer - -A speed killer is setting the variable -gnus-fetch-old-headers to anything different from nil, -so don't do this if speed is an issue. To speed up -building of summary say - -@example -(gnus-compile) -@end example -@noindent - -at the bottom of your ~/.gnus.el, this will make gnus -byte-compile things like -gnus-summary-line-format. -then you could increase the value of gc-cons-threshold -by saying something like - -@example -(setq gc-cons-threshold 3500000) -@end example -@noindent - -in ~/.emacs. If you don't care about width of CJK -characters or use Gnus 5.10 or younger together with a -recent GNU Emacs, you should say - -@example -(setq gnus-use-correct-string-widths nil) -@end example -@noindent - -in ~/.gnus.el (thanks to Jesper harder for the last -two suggestions). Finally if you are still using 5.8.8 -or 5.9 and experience speed problems with summary -buffer generation, you definitely should update to -5.10 since there quite some work on improving it has -been done. - -@node FAQ 9-3 -@subsubheading Question 9.3 - -Sending mail becomes slower and slower, what's up? - -@subsubheading Answer - -The reason could be that you told Gnus to archive the -messages you wrote by setting -gnus-message-archive-group. Try to use a nnml group -instead of an archive group, this should bring you back -to normal speed. - -@node FAQ - Glossary -@subsection Glossary - -@table @dfn - -@item ~/.gnus.el -When the term ~/.gnus.el is used it just means your Gnus -configuration file. You might as well call it ~/.gnus or -specify another name. - -@item Back End -In Gnus terminology a back end is a virtual server, a layer -between core Gnus and the real NNTP-, POP3-, IMAP- or -whatever-server which offers Gnus a standardized interface -to functions like "get message", "get Headers" etc. - -@item Emacs -When the term Emacs is used in this FAQ, it means either GNU -Emacs or XEmacs. - -@item Message -In this FAQ message means a either a mail or a posting to a -Usenet Newsgroup or to some other fancy back end, no matter -of which kind it is. - -@item MUA -MUA is an acronym for Mail User Agent, it's the program you -use to read and write e-mails. - -@item NUA -NUA is an acronym for News User Agent, it's the program you -use to read and write Usenet news. - -@end table diff --git a/doc/misc/gnus-news.texi b/doc/misc/gnus-news.texi deleted file mode 100644 index 19bbe01667c..00000000000 --- a/doc/misc/gnus-news.texi +++ /dev/null @@ -1,371 +0,0 @@ -@c -*-texinfo-*- - -@c Copyright (C) 2004-2012 Free Software Foundation, Inc. - -@c Permission is granted to anyone to make or distribute verbatim copies -@c of this document as received, in any medium, provided that the -@c copyright notice and this permission notice are preserved, -@c thus giving the recipient permission to redistribute in turn. - -@c Permission is granted to distribute modified versions -@c of this document, or of portions of it, -@c under the above conditions, provided also that they -@c carry prominent notices stating who last changed them. - -@c This file contains a list of news features Gnus. It is supposed to be -@c included in `gnus.texi'. `GNUS-NEWS' is automatically generated from -@c this file (see `gnus-news.el'). - -@itemize @bullet - -@item Supported Emacs versions -The following Emacs versions are supported by No Gnus: -@itemize @bullet - -@item Emacs 22 and up -@item XEmacs 21.4 -@item XEmacs 21.5 -@item SXEmacs - -@end itemize - -@item Installation changes - -@itemize @bullet -@item Upgrading from previous (stable) version if you have used No Gnus. - -If you have tried No Gnus (the unstable Gnus branch leading to this -release) but went back to a stable version, be careful when upgrading -to this version. In particular, you will probably want to remove the -@file{~/News/marks} directory (perhaps selectively), so that flags are -read from your @file{~/.newsrc.eld} instead of from the stale marks -file, where this release will store flags for nntp. See a later entry -for more information about nntp marks. Note that downgrading isn't -safe in general. - -@item Incompatibility when switching from Emacs 23 to Emacs 22 -In Emacs 23, Gnus uses Emacs's new internal coding system @code{utf-8-emacs} -for saving articles drafts and @file{~/.newsrc.eld}. These files may not -be read correctly in Emacs 22 and below. If you want to use Gnus across -different Emacs versions, you may set @code{mm-auto-save-coding-system} -to @code{emacs-mule}. -@c FIXME: Untested. (Or did anyone test it?) -@c Cf. http://thread.gmane.org/gmane.emacs.gnus.general/66251/focus=66344 - -@item Lisp files are now installed in @file{.../site-lisp/gnus/} by default. -It defaulted to @file{.../site-lisp/} formerly. In addition to this, -the new installer issues a warning if other Gnus installations which -will shadow the latest one are detected. You can then remove those -shadows manually or remove them using @code{make -remove-installed-shadows}. - -@item The installation directory name is allowed to have spaces and/or tabs. -@end itemize - -@item New packages and libraries within Gnus - -@itemize @bullet - -@item New version of @code{nnimap} - -@code{nnimap} has been reimplemented in a mostly-compatible way. See -the Gnus manual for a description of the new interface. In -particular, @code{nnimap-inbox} and the client side split method has -changed. - -@item Gnus includes the Emacs Lisp @acronym{SASL} library. - -This provides a clean @acronym{API} to @acronym{SASL} mechanisms from -within Emacs. The user visible aspects of this, compared to the earlier -situation, include support for @acronym{DIGEST}-@acronym{MD5} and -@acronym{NTLM}. @xref{Top, ,Emacs SASL, sasl, Emacs SASL}. - -@item ManageSieve connections uses the @acronym{SASL} library by default. - -The primary change this brings is support for @acronym{DIGEST-MD5} and -@acronym{NTLM}, when the server supports it. - -@item Gnus includes a password cache mechanism in password.el. - -It is enabled by default (see @code{password-cache}), with a short -timeout of 16 seconds (see @code{password-cache-expiry}). If -@acronym{PGG} is used as the @acronym{PGP} back end, the @acronym{PGP} -passphrase is managed by this mechanism. Passwords for ManageSieve -connections are managed by this mechanism, after querying the user -about whether to do so. - -@item Using EasyPG with Gnus -When EasyPG, is available, Gnus will use it instead of @acronym{PGG}. -EasyPG is an Emacs user interface to GNU Privacy Guard. @xref{Top, -,EasyPG Assistant user's manual, epa, EasyPG Assistant user's manual}. -EasyPG is included in Emacs 23 and available separately as well. -@end itemize - -@item Changes in group mode -@c ************************ - -@itemize @bullet - -@item -Symbols like @code{gcc-self} now have the same precedence rules in -@code{gnus-parameters} as other ``real'' variables: The last match -wins instead of the first match. - -@item -Old intermediate incoming mail files (@file{Incoming*}) are deleted -after a couple of days, not immediately. @xref{Mail Source -Customization}. -(New in Gnus 5.10.10 / No Gnus 0.8) -@c This entry is also present in the node "Oort Gnus". - -@end itemize - -@item Changes in summary and article mode - -@itemize @bullet - -@item There's now only one variable that determines how @acronym{HTML} -is rendered: @code{mm-text-html-renderer}. - -@item Gnus now supports sticky article buffers. Those are article buffers -that are not reused when you select another article. @xref{Sticky -Articles}. - -@c @item Bookmarks -@c FIXME: To be added - -@item Gnus can selectively display @samp{text/html} articles -with a WWW browser with @kbd{K H}. @xref{MIME Commands}. - -@c gnus-registry-marks -@c FIXME: To be added - -@item International host names (@acronym{IDNA}) can now be decoded -inside article bodies using @kbd{W i} -(@code{gnus-summary-idna-message}). This requires that GNU Libidn -(@url{http://www.gnu.org/software/libidn/}) has been installed. -@c FIXME: Also mention @code{message-use-idna}? - -@item The non-@acronym{ASCII} group names handling has been much -improved. The back ends that fully support non-@acronym{ASCII} group -names are now @code{nntp}, @code{nnml}, and @code{nnrss}. Also the -agent, the cache, and the marks features work with those back ends. -@xref{Non-ASCII Group Names}. - -@item Gnus now displays @acronym{DNS} master files sent as text/dns -using dns-mode. - -@item Gnus supports new limiting commands in the Summary buffer: -@kbd{/ r} (@code{gnus-summary-limit-to-replied}) and @kbd{/ R} -(@code{gnus-summary-limit-to-recipient}). @xref{Limiting}. - -@item You can now fetch all ticked articles from the server using -@kbd{Y t} (@code{gnus-summary-insert-ticked-articles}). @xref{Summary -Generation Commands}. - -@item Gnus supports a new sort command in the Summary buffer: -@kbd{C-c C-s C-t} (@code{gnus-summary-sort-by-recipient}). @xref{Summary -Sorting}. - -@item @acronym{S/MIME} now features @acronym{LDAP} user certificate searches. -You need to configure the server in @code{smime-ldap-host-list}. - -@item URLs inside Open@acronym{PGP} headers are retrieved and imported -to your PGP key ring when you click on them. - -@item -Picons can be displayed right from the textual address, see -@code{gnus-picon-style}. @xref{Picons}. - -@item @acronym{ANSI} @acronym{SGR} control sequences can be transformed -using @kbd{W A}. - -@acronym{ANSI} sequences are used in some Chinese hierarchies for -highlighting articles (@code{gnus-article-treat-ansi-sequences}). - -@item Gnus now MIME decodes articles even when they lack "MIME-Version" header. -This changes the default of @code{gnus-article-loose-mime}. - -@item @code{gnus-decay-scores} can be a regexp matching score files. -For example, set it to @samp{\\.ADAPT\\'} and only adaptive score files -will be decayed. @xref{Score Decays}. - -@item Strings prefixing to the @code{To} and @code{Newsgroup} headers in -summary lines when using @code{gnus-ignored-from-addresses} can be -customized with @code{gnus-summary-to-prefix} and -@code{gnus-summary-newsgroup-prefix}. @xref{To From Newsgroups}. - -@item You can replace @acronym{MIME} parts with external bodies. -See @code{gnus-mime-replace-part} and @code{gnus-article-replace-part}. -@xref{MIME Commands}, @ref{Using MIME}. - -@item -The option @code{mm-fill-flowed} can be used to disable treatment of -format=flowed messages. Also, flowed text is disabled when sending -inline @acronym{PGP} signed messages. @xref{Flowed text, ,Flowed text, -emacs-mime, The Emacs MIME Manual}. (New in Gnus 5.10.7) -@c This entry is also present in the node "Oort Gnus". - -@item Now the new command @kbd{S W} -(@code{gnus-article-wide-reply-with-original}) for a wide reply in the -article buffer yanks a text that is in the active region, if it is set, -as well as the @kbd{R} (@code{gnus-article-reply-with-original}) command. -Note that the @kbd{R} command in the article buffer no longer accepts a -prefix argument, which was used to make it do a wide reply. -@xref{Article Keymap}. - -@item The new command @kbd{C-h b} -(@code{gnus-article-describe-bindings}) used in the article buffer now -shows not only the article commands but also the real summary commands -that are accessible from the article buffer. - -@end itemize - -@item Changes in Message mode - -@itemize @bullet -@item Gnus now defaults to saving all outgoing messages in per-month -nnfolder archives. - -@item Gnus now supports the ``hashcash'' client puzzle anti-spam mechanism. -Use @code{(setq message-generate-hashcash t)} to enable. -@xref{Hashcash}. - -@item You can now drag and drop attachments to the Message buffer. -See @code{mml-dnd-protocol-alist} and @code{mml-dnd-attach-options}. -@xref{MIME, ,MIME, message, Message Manual}. - -@item The option @code{message-yank-empty-prefix} now controls how -empty lines are prefixed in cited text. @xref{Insertion Variables, -,Insertion Variables, message, Message Manual}. - -@item Gnus uses narrowing to hide headers in Message buffers. -The @code{References} header is hidden by default. To make all -headers visible, use @code{(setq message-hidden-headers nil)}. -@xref{Message Headers, ,Message Headers, message, Message Manual}. - -@item You can highlight different levels of citations like in the -article buffer. See @code{gnus-message-highlight-citation}. - -@item @code{auto-fill-mode} is enabled by default in Message mode. -See @code{message-fill-column}. @xref{Various Message Variables, , -Message Headers, message, Message Manual}. - -@item You can now store signature files in a special directory -named @code{message-signature-directory}. - -@item The option @code{message-citation-line-format} controls the format -of the "Whomever writes:" line. You need to set -@code{message-citation-line-function} to -@code{message-insert-formatted-citation-line} as well. -@end itemize - -@item Changes in Browse Server mode - -@itemize @bullet -@item Gnus' sophisticated subscription methods are now available in -Browse Server buffers as well using the variable -@code{gnus-browse-subscribe-newsgroup-method}. - -@end itemize - - -@item Changes in back ends - -@itemize @bullet -@item The nntp back end stores article marks in @file{~/News/marks}. - -The directory can be changed using the (customizable) variable -@code{nntp-marks-directory}, and marks can be disabled using the -(back end) variable @code{nntp-marks-is-evil}. The advantage of this -is that you can copy @file{~/News/marks} (using rsync, scp or -whatever) to another Gnus installation, and it will realize what -articles you have read and marked. The data in @file{~/News/marks} -has priority over the same data in @file{~/.newsrc.eld}. - -@item -You can import and export your @acronym{RSS} subscriptions from -@acronym{OPML} files. @xref{RSS}. - -@item @acronym{IMAP} identity (@acronym{RFC} 2971) is supported. - -By default, Gnus does not send any information about itself, but you can -customize it using the variable @code{nnimap-id}. - -@item The @code{nnrss} back end now supports multilingual text. -Non-@acronym{ASCII} group names for the @code{nnrss} groups are also -supported. @xref{RSS}. - -@item Retrieving mail with @acronym{POP3} is supported over @acronym{SSL}/@acronym{TLS} and with StartTLS. - -@item The nnml back end allows other compression programs beside @file{gzip} -for compressed message files. @xref{Mail Spool}. - -@item The nnml back end supports group compaction. - -This feature, accessible via the functions -@code{gnus-group-compact-group} (@kbd{G z} in the group buffer) and -@code{gnus-server-compact-server} (@kbd{z} in the server buffer) -renumbers all articles in a group, starting from 1 and removing gaps. -As a consequence, you get a correct total article count (until -messages are deleted again). - -@c @item nnmairix.el -@c FIXME - -@c @item nnir.el -@c FIXME - -@end itemize - -@item Appearance -@c Maybe it's not worth to separate this from "Miscellaneous"? - -@itemize @bullet - -@item The tool bar has been updated to use GNOME icons. -You can also customize the tool bars: @kbd{M-x customize-apropos RET --tool-bar$} should get you started. (Only for Emacs, not in XEmacs.) -@c FIXME: Document this in the manual - -@item The tool bar icons are now (de)activated correctly -in the group buffer, see the variable @code{gnus-group-update-tool-bar}. -Its default value depends on your Emacs version. -@c FIXME: Document this in the manual - -@item You can change the location of XEmacs's toolbars in Gnus buffers. -See @code{gnus-use-toolbar} and @code{message-use-toolbar}. - -@end itemize - -@item Miscellaneous changes - -@itemize @bullet -@item Having edited the select-method for the foreign server in the -server buffer is immediately reflected to the subscription of the groups -which use the server in question. For instance, if you change -@code{nntp-via-address} into @samp{bar.example.com} from -@samp{foo.example.com}, Gnus will connect to the news host by way of the -intermediate host @samp{bar.example.com} from next time. - -@item The @file{all.SCORE} file can be edited from the group buffer -using @kbd{W e}. - -@item You can set @code{gnus-mark-copied-or-moved-articles-as-expirable} -to a non-@code{nil} value so that articles that have been read may be -marked as expirable automatically when copying or moving them to a group -that has auto-expire turned on. The default is @code{nil} and copying -and moving of articles behave as before; i.e., the expirable marks will -be unchanged except that the marks will be removed when copying or -moving articles to a group that has not turned auto-expire on. -@xref{Expiring Mail}. - -@item NoCeM support has been removed. - -@item Carpal mode has been removed. - -@end itemize - -@end itemize - -@c gnus-news.texi ends here. diff --git a/doc/misc/gnus-overrides.texi b/doc/misc/gnus-overrides.texi deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi deleted file mode 100644 index b0839906df5..00000000000 --- a/doc/misc/gnus.texi +++ /dev/null @@ -1,30641 +0,0 @@ -\input texinfo - -@include gnus-overrides.texi - -@setfilename ../../info/gnus -@settitle Gnus Manual -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex pg cp - -@documentencoding ISO-8859-1 - -@copying -Copyright @copyright{} 1995-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@iftex -@iflatex -\documentclass[twoside,a4paper,openright,11pt]{book} -\usepackage[latin1]{inputenc} -\usepackage{pagestyle} -\usepackage{epsfig} -\usepackage{pixidx} -\input{gnusconfig.tex} - -\ifx\pdfoutput\undefined -\else -\usepackage[pdftex,bookmarks,colorlinks=true]{hyperref} -\usepackage{thumbpdf} -\pdfcompresslevel=9 -\fi - -\makeindex -\begin{document} - -% Adjust ../Makefile.in if you change the following line: -\newcommand{\gnusversionname}{Gnus v5.13} -\newcommand{\gnuschaptername}{} -\newcommand{\gnussectionname}{} - -\newcommand{\gnusbackslash}{/} - -\newcommand{\gnusref}[1]{``#1'' on page \pageref{#1}} -\ifx\pdfoutput\undefined -\newcommand{\gnusuref}[1]{\gnustt{#1}} -\else -\newcommand{\gnusuref}[1]{\href{#1}{\gnustt{#1}}} -\fi -\newcommand{\gnusxref}[1]{See ``#1'' on page \pageref{#1}} -\newcommand{\gnuspxref}[1]{see ``#1'' on page \pageref{#1}} - -\newcommand{\gnuskindex}[1]{\index{#1}} -\newcommand{\gnusindex}[1]{\index{#1}} - -\newcommand{\gnustt}[1]{{\gnusselectttfont{}#1}} -\newcommand{\gnuscode}[1]{\gnustt{#1}} -\newcommand{\gnusasis}[1]{\gnustt{#1}} -\newcommand{\gnusurl}[1]{\gnustt{#1}} -\newcommand{\gnuscommand}[1]{\gnustt{#1}} -\newcommand{\gnusenv}[1]{\gnustt{#1}} -\newcommand{\gnussamp}[1]{``{\fontencoding{OT1}\gnusselectttfont{}#1}''} -\newcommand{\gnuslisp}[1]{\gnustt{#1}} -\newcommand{\gnuskbd}[1]{`\gnustt{#1}'} -\newcommand{\gnuskey}[1]{`\gnustt{#1}'} -\newcommand{\gnusfile}[1]{`\gnustt{#1}'} -\newcommand{\gnusdfn}[1]{\textit{#1}} -\newcommand{\gnusi}[1]{\textit{#1}} -\newcommand{\gnusr}[1]{\textrm{#1}} -\newcommand{\gnusstrong}[1]{\textbf{#1}} -\newcommand{\gnusemph}[1]{\textit{#1}} -\newcommand{\gnusvar}[1]{{\fontsize{10pt}{10}\selectfont\textsl{\textsf{#1}}}} -\newcommand{\gnussc}[1]{\textsc{#1}} -\newcommand{\gnustitle}[1]{{\huge\textbf{#1}}} -\newcommand{\gnusversion}[1]{{\small\textit{#1}}} -\newcommand{\gnusauthor}[1]{{\large\textbf{#1}}} -\newcommand{\gnusresult}[1]{\gnustt{=> #1}} -\newcommand{\gnusacronym}[1]{\textsc{#1}} -\newcommand{\gnusemail}[1]{\textit{#1}} - -\newcommand{\gnusbullet}{{${\bullet}$}} -\newcommand{\gnusdollar}{\$} -\newcommand{\gnusampersand}{\&} -\newcommand{\gnuspercent}{\%} -\newcommand{\gnushash}{\#} -\newcommand{\gnushat}{\symbol{"5E}} -\newcommand{\gnusunderline}{\symbol{"5F}} -\newcommand{\gnusnot}{$\neg$} -\newcommand{\gnustilde}{\symbol{"7E}} -\newcommand{\gnusless}{{$<$}} -\newcommand{\gnusgreater}{{$>$}} -\newcommand{\gnusbraceleft}{{$>$}} -\newcommand{\gnusbraceright}{{$>$}} - -\newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=ps/gnus-head,height=1cm}}} -\newcommand{\gnusinteresting}{ -\marginpar[\mbox{}\hfill\gnushead]{\gnushead} -} - -\newcommand{\gnuscleardoublepage}{\ifodd\count0\mbox{}\clearpage\thispagestyle{empty}\mbox{}\clearpage\else\clearpage\fi} - -\newcommand{\gnuspagechapter}[1]{ -{\mbox{}} -} - -\newdimen{\gnusdimen} -\gnusdimen 0pt - -\newcommand{\gnuschapter}[2]{ -\gnuscleardoublepage -\ifdim \gnusdimen = 0pt\setcounter{page}{1}\pagestyle{gnus}\pagenumbering{arabic} \gnusdimen 1pt\fi -\chapter{#2} -\renewcommand{\gnussectionname}{} -\renewcommand{\gnuschaptername}{#2} -\thispagestyle{empty} -\hspace*{-2cm} -\begin{picture}(500,500)(0,0) -\put(480,350){\makebox(0,0)[tr]{#1}} -\put(40,300){\makebox(500,50)[bl]{{\Huge\bf{#2}}}} -\end{picture} -\clearpage -} - -\newcommand{\gnusfigure}[3]{ -\begin{figure} -\mbox{}\ifodd\count0\hspace*{-0.8cm}\else\hspace*{-3cm}\fi\begin{picture}(440,#2) -#3 -\end{picture} -\caption{#1} -\end{figure} -} - -\newcommand{\gnusicon}[1]{ -\marginpar[\mbox{}\hfill\raisebox{-1.5cm}{\epsfig{figure=ps/#1-up,height=1.5cm}}]{\raisebox{-1cm}{\epsfig{figure=ps/#1-up,height=1cm}}} -} - -\newcommand{\gnuspicon}[1]{ -\margindex{\epsfig{figure=#1,width=2cm}} -} - -\newcommand{\gnusxface}[2]{ -\margindex{\epsfig{figure=#1,width=1cm}\epsfig{figure=#2,width=1cm}} -} - -\newcommand{\gnussmiley}[2]{ -\margindex{\makebox[2cm]{\hfill\epsfig{figure=#1,width=0.5cm}\hfill\epsfig{figure=#2,width=0.5cm}\hfill}} -} - -\newcommand{\gnusitemx}[1]{\mbox{}\vspace*{-\itemsep}\vspace*{-\parsep}\item#1} - -\newcommand{\gnussection}[1]{ -\renewcommand{\gnussectionname}{#1} -\section{#1} -} - -\newenvironment{codelist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{asislist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{kbdlist}% -{\begin{list}{}{ -\labelwidth=0cm -} -}{\end{list}} - -\newenvironment{dfnlist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{stronglist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{samplist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{varlist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{emphlist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newlength\gnusheadtextwidth -\setlength{\gnusheadtextwidth}{\headtextwidth} -\addtolength{\gnusheadtextwidth}{1cm} - -\newpagestyle{gnuspreamble}% -{ -{ -\ifodd\count0 -{ -\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\mbox{}}\textbf{\hfill\roman{page}}} -} -\else -{ -\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\roman{page}\hfill\mbox{}}} -} -} -\fi -} -} -{ -\ifodd\count0 -\mbox{} \hfill -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\else -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\hfill \mbox{} -\fi -} - -\newpagestyle{gnusindex}% -{ -{ -\ifodd\count0 -{ -\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\gnuschaptername\hfill\arabic{page}}}} -} -\else -{ -\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}} -} -\fi -} -} -{ -\ifodd\count0 -\mbox{} \hfill -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\else -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\hfill \mbox{} -\fi -} - -\newpagestyle{gnus}% -{ -{ -\ifodd\count0 -{ -\makebox[12cm]{\hspace*{3.1cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{chapter}.\arabic{section}} \textbf{\gnussectionname\hfill\arabic{page}}}}} -} -\else -{ -\makebox[12cm]{\hspace*{-2.95cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}} -} -\fi -} -} -{ -\ifodd\count0 -\mbox{} \hfill -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\else -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\hfill \mbox{} -\fi -} - -\pagenumbering{roman} -\pagestyle{gnuspreamble} - -@end iflatex -@end iftex - -@iftex -@iflatex - -\begin{titlepage} -{ - -%\addtolength{\oddsidemargin}{-5cm} -%\addtolength{\evensidemargin}{-5cm} -\parindent=0cm -\addtolength{\textheight}{2cm} - -\gnustitle{\gnustitlename}\hfill\gnusversion{\gnusversionname}\\ -\rule{15cm}{1mm}\\ -\vfill -\hspace*{0cm}\epsfig{figure=ps/gnus-big-logo,height=15cm} -\vfill -\rule{15cm}{1mm}\\ -\gnusauthor{by Lars Magne Ingebrigtsen} -\newpage -} - -\mbox{} -\vfill - -\thispagestyle{empty} - -@c @insertcopying -\newpage -\end{titlepage} -@end iflatex -@end iftex - -@dircategory Emacs network features -@direntry -* Gnus: (gnus). The newsreader Gnus. -@end direntry -@iftex -@finalout -@end iftex - - -@titlepage -@ifset WEBHACKDEVEL -@title Gnus Manual (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title Gnus Manual -@end ifclear - -@author by Lars Magne Ingebrigtsen -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@node Top -@top The Gnus Newsreader - -@ifinfo - -You can read news (and mail) from within Emacs by using Gnus. The news -can be gotten by any nefarious means you can think of---@acronym{NNTP}, local -spool or your mbox file. All at the same time, if you want to push your -luck. - -@c Adjust ../Makefile.in if you change the following line: -This manual corresponds to Gnus v5.13 - -@ifnottex -@insertcopying -@end ifnottex - -@end ifinfo - -@iftex - -@iflatex -\tableofcontents -\gnuscleardoublepage -@end iflatex - -Gnus is the advanced, self-documenting, customizable, extensible -unreal-time newsreader for GNU Emacs. - -Oops. That sounds oddly familiar, so let's start over again to avoid -being accused of plagiarism: - -Gnus is a message-reading laboratory. It will let you look at just -about anything as if it were a newsgroup. You can read mail with it, -you can browse directories with it, you can @code{ftp} with it---you -can even read news with it! - -Gnus tries to empower people who read news the same way Emacs empowers -people who edit text. Gnus sets no limits to what the user should be -allowed to do. Users are encouraged to extend Gnus to make it behave -like they want it to behave. A program should not control people; -people should be empowered to do what they want by using (or abusing) -the program. - -@c Adjust ../Makefile.in if you change the following line: -This manual corresponds to Gnus v5.13 - -@heading Other related manuals -@itemize -@item Message manual: Composing messages -@item Emacs-MIME: Composing messages; @acronym{MIME}-specific parts. -@item Sieve: Managing Sieve scripts in Emacs. -@item EasyPG: @acronym{PGP/MIME} with Gnus. -@item SASL: @acronym{SASL} authentication in Emacs. -@end itemize - -@end iftex - -@menu -* Starting Up:: Finding news can be a pain. -* Group Buffer:: Selecting, subscribing and killing groups. -* Summary Buffer:: Reading, saving and posting articles. -* Article Buffer:: Displaying and handling articles. -* Composing Messages:: Information on sending mail and news. -* Select Methods:: Gnus reads all messages from various select methods. -* Scoring:: Assigning values to articles. -* Searching:: Mail and News search engines. -* Various:: General purpose settings. -* The End:: Farewell and goodbye. -* Appendices:: Terminology, Emacs intro, @acronym{FAQ}, History, Internals. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Variable, function and concept index. -* Key Index:: Key Index. - -Other related manuals - -* Message:(message). Composing messages. -* Emacs-MIME:(emacs-mime). Composing messages; @acronym{MIME}-specific parts. -* Sieve:(sieve). Managing Sieve scripts in Emacs. -* EasyPG:(epa). @acronym{PGP/MIME} with Gnus. -* SASL:(sasl). @acronym{SASL} authentication in Emacs. - -@detailmenu - --- The Detailed Node Listing --- - -Starting Gnus - -* Finding the News:: Choosing a method for getting news. -* The Server is Down:: How can I read my mail then? -* Slave Gnusae:: You can have more than one Gnus active at a time. -* Fetching a Group:: Starting Gnus just to read a group. -* New Groups:: What is Gnus supposed to do with new groups? -* Changing Servers:: You may want to move from one server to another. -* Startup Files:: Those pesky startup files---@file{.newsrc}. -* Auto Save:: Recovering from a crash. -* The Active File:: Reading the active file over a slow line Takes Time. -* Startup Variables:: Other variables you might change. - -New Groups - -* Checking New Groups:: Determining what groups are new. -* Subscription Methods:: What Gnus should do with new groups. -* Filtering New Groups:: Making Gnus ignore certain new groups. - -Group Buffer - -* Group Buffer Format:: Information listed and how you can change it. -* Group Maneuvering:: Commands for moving in the group buffer. -* Selecting a Group:: Actually reading news. -* Subscription Commands:: Unsubscribing, killing, subscribing. -* Group Data:: Changing the info for a group. -* Group Levels:: Levels? What are those, then? -* Group Score:: A mechanism for finding out what groups you like. -* Marking Groups:: You can mark groups for later processing. -* Foreign Groups:: Creating and editing groups. -* Group Parameters:: Each group may have different parameters set. -* Listing Groups:: Gnus can list various subsets of the groups. -* Sorting Groups:: Re-arrange the group order. -* Group Maintenance:: Maintaining a tidy @file{.newsrc} file. -* Browse Foreign Server:: You can browse a server. See what it has to offer. -* Exiting Gnus:: Stop reading news and get some work done. -* Group Topics:: A folding group mode divided into topics. -* Non-ASCII Group Names:: Accessing groups of non-English names. -* Misc Group Stuff:: Other stuff that you can to do. - -Group Buffer Format - -* Group Line Specification:: Deciding how the group buffer is to look. -* Group Mode Line Specification:: The group buffer mode line. -* Group Highlighting:: Having nice colors in the group buffer. - -Group Topics - -* Topic Commands:: Interactive E-Z commands. -* Topic Variables:: How to customize the topics the Lisp Way. -* Topic Sorting:: Sorting each topic individually. -* Topic Topology:: A map of the world. -* Topic Parameters:: Parameters that apply to all groups in a topic. - -Misc Group Stuff - -* Scanning New Messages:: Asking Gnus to see whether new messages have arrived. -* Group Information:: Information and help on groups and Gnus. -* Group Timestamp:: Making Gnus keep track of when you last read a group. -* File Commands:: Reading and writing the Gnus files. -* Sieve Commands:: Managing Sieve scripts. - -Summary Buffer - -* Summary Buffer Format:: Deciding how the summary buffer is to look. -* Summary Maneuvering:: Moving around the summary buffer. -* Choosing Articles:: Reading articles. -* Paging the Article:: Scrolling the current article. -* Reply Followup and Post:: Posting articles. -* Delayed Articles:: Send articles at a later time. -* Marking Articles:: Marking articles as read, expirable, etc. -* Limiting:: You can limit the summary buffer. -* Threading:: How threads are made. -* Sorting the Summary Buffer:: How articles and threads are sorted. -* Asynchronous Fetching:: Gnus might be able to pre-fetch articles. -* Article Caching:: You may store articles in a cache. -* Persistent Articles:: Making articles expiry-resistant. -* Sticky Articles:: Article buffers that are not reused. -* Article Backlog:: Having already read articles hang around. -* Saving Articles:: Ways of customizing article saving. -* Decoding Articles:: Gnus can treat series of (uu)encoded articles. -* Article Treatment:: The article buffer can be mangled at will. -* MIME Commands:: Doing MIMEy things with the articles. -* Charsets:: Character set issues. -* Article Commands:: Doing various things with the article buffer. -* Summary Sorting:: Sorting the summary buffer in various ways. -* Finding the Parent:: No child support? Get the parent. -* Alternative Approaches:: Reading using non-default summaries. -* Tree Display:: A more visual display of threads. -* Mail Group Commands:: Some commands can only be used in mail groups. -* Various Summary Stuff:: What didn't fit anywhere else. -* Exiting the Summary Buffer:: Returning to the Group buffer, - or reselecting the current group. -* Crosspost Handling:: How crossposted articles are dealt with. -* Duplicate Suppression:: An alternative when crosspost handling fails. -* Security:: Decrypt and Verify. -* Mailing List:: Mailing list minor mode. - -Summary Buffer Format - -* Summary Buffer Lines:: You can specify how summary lines should look. -* To From Newsgroups:: How to not display your own name. -* Summary Buffer Mode Line:: You can say how the mode line should look. -* Summary Highlighting:: Making the summary buffer all pretty and nice. - -Choosing Articles - -* Choosing Commands:: Commands for choosing articles. -* Choosing Variables:: Variables that influence these commands. - -Reply, Followup and Post - -* Summary Mail Commands:: Sending mail. -* Summary Post Commands:: Sending news. -* Summary Message Commands:: Other Message-related commands. -* Canceling and Superseding:: - -Marking Articles - -* Unread Articles:: Marks for unread articles. -* Read Articles:: Marks for read articles. -* Other Marks:: Marks that do not affect readedness. -* Setting Marks:: How to set and remove marks. -* Generic Marking Commands:: How to customize the marking. -* Setting Process Marks:: How to mark articles for later processing. - -Threading - -* Customizing Threading:: Variables you can change to affect the threading. -* Thread Commands:: Thread based commands in the summary buffer. - -Customizing Threading - -* Loose Threads:: How Gnus gathers loose threads into bigger threads. -* Filling In Threads:: Making the threads displayed look fuller. -* More Threading:: Even more variables for fiddling with threads. -* Low-Level Threading:: You thought it was over@dots{} but you were wrong! - -Decoding Articles - -* Uuencoded Articles:: Uudecode articles. -* Shell Archives:: Unshar articles. -* PostScript Files:: Split PostScript. -* Other Files:: Plain save and binhex. -* Decoding Variables:: Variables for a happy decoding. -* Viewing Files:: You want to look at the result of the decoding? - -Decoding Variables - -* Rule Variables:: Variables that say how a file is to be viewed. -* Other Decode Variables:: Other decode variables. -* Uuencoding and Posting:: Variables for customizing uuencoding. - -Article Treatment - -* Article Highlighting:: You want to make the article look like fruit salad. -* Article Fontisizing:: Making emphasized text look nice. -* Article Hiding:: You also want to make certain info go away. -* Article Washing:: Lots of way-neat functions to make life better. -* Article Header:: Doing various header transformations. -* Article Buttons:: Click on URLs, Message-IDs, addresses and the like. -* Article Button Levels:: Controlling appearance of buttons. -* Article Date:: Grumble, UT! -* Article Display:: Display various stuff---X-Face, Picons, Smileys, Gravatars -* Article Signature:: What is a signature? -* Article Miscellanea:: Various other stuff. - -Alternative Approaches - -* Pick and Read:: First mark articles and then read them. -* Binary Groups:: Auto-decode all articles. - -Various Summary Stuff - -* Summary Group Information:: Information oriented commands. -* Searching for Articles:: Multiple article commands. -* Summary Generation Commands:: -* Really Various Summary Commands:: Those pesky non-conformant commands. - -Article Buffer - -* Hiding Headers:: Deciding what headers should be displayed. -* Using MIME:: Pushing articles through @acronym{MIME} before reading them. -* Customizing Articles:: Tailoring the look of the articles. -* Article Keymap:: Keystrokes available in the article buffer. -* Misc Article:: Other stuff. - -Composing Messages - -* Mail:: Mailing and replying. -* Posting Server:: What server should you post and mail via? -* POP before SMTP:: You cannot send a mail unless you read a mail. -* Mail and Post:: Mailing and posting at the same time. -* Archived Messages:: Where Gnus stores the messages you've sent. -* Posting Styles:: An easier way to specify who you are. -* Drafts:: Postponing messages and rejected messages. -* Rejected Articles:: What happens if the server doesn't like your article? -* Signing and encrypting:: How to compose secure messages. - -Select Methods - -* Server Buffer:: Making and editing virtual servers. -* Getting News:: Reading USENET news with Gnus. -* Using IMAP:: Reading mail from @acronym{IMAP}. -* Getting Mail:: Reading your personal mail with Gnus. -* Browsing the Web:: Getting messages from a plethora of Web sources. -* Other Sources:: Reading directories, files. -* Combined Groups:: Combining groups into one group. -* Email Based Diary:: Using mails to manage diary events in Gnus. -* Gnus Unplugged:: Reading news and mail offline. - -Server Buffer - -* Server Buffer Format:: You can customize the look of this buffer. -* Server Commands:: Commands to manipulate servers. -* Example Methods:: Examples server specifications. -* Creating a Virtual Server:: An example session. -* Server Variables:: Which variables to set. -* Servers and Methods:: You can use server names as select methods. -* Unavailable Servers:: Some servers you try to contact may be down. - -Getting News - -* NNTP:: Reading news from an @acronym{NNTP} server. -* News Spool:: Reading news from the local spool. - -@acronym{NNTP} - -* Direct Functions:: Connecting directly to the server. -* Indirect Functions:: Connecting indirectly to the server. -* Common Variables:: Understood by several connection functions. -* NNTP marks:: Storing marks for @acronym{NNTP} servers. - -Getting Mail - -* Mail in a Newsreader:: Important introductory notes. -* Getting Started Reading Mail:: A simple cookbook example. -* Splitting Mail:: How to create mail groups. -* Mail Sources:: How to tell Gnus where to get mail from. -* Mail Back End Variables:: Variables for customizing mail handling. -* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. -* Group Mail Splitting:: Use group customize to drive mail splitting. -* Incorporating Old Mail:: What about the old mail you have? -* Expiring Mail:: Getting rid of unwanted mail. -* Washing Mail:: Removing cruft from the mail you get. -* Duplicates:: Dealing with duplicated mail. -* Not Reading Mail:: Using mail back ends for reading other files. -* Choosing a Mail Back End:: Gnus can read a variety of mail formats. - -Mail Sources - -* Mail Source Specifiers:: How to specify what a mail source is. -* Mail Source Customization:: Some variables that influence things. -* Fetching Mail:: Using the mail source specifiers. - -Choosing a Mail Back End - -* Unix Mail Box:: Using the (quite) standard Un*x mbox. -* Babyl:: Babyl was used by older versions of Rmail. -* Mail Spool:: Store your mail in a private spool? -* MH Spool:: An mhspool-like back end. -* Maildir:: Another one-file-per-message format. -* Mail Folders:: Having one file for each group. -* Comparing Mail Back Ends:: An in-depth looks at pros and cons. - -Browsing the Web - -* Archiving Mail:: -* Web Searches:: Creating groups from articles that match a string. -* RSS:: Reading RDF site summary. -* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. - -Other Sources - -* Directory Groups:: You can read a directory as if it was a newsgroup. -* Anything Groups:: Dired? Who needs dired? -* Document Groups:: Single files can be the basis of a group. -* Mail-To-News Gateways:: Posting articles via mail-to-news gateways. -* The Empty Backend:: The backend that never has any news. - -Document Groups - -* Document Server Internals:: How to add your own document types. - -Combined Groups - -* Virtual Groups:: Combining articles from many groups. - -Email Based Diary - -* The NNDiary Back End:: Basic setup and usage. -* The Gnus Diary Library:: Utility toolkit on top of nndiary. -* Sending or Not Sending:: A final note on sending diary messages. - -The NNDiary Back End - -* Diary Messages:: What makes a message valid for nndiary. -* Running NNDiary:: NNDiary has two modes of operation. -* Customizing NNDiary:: Bells and whistles. - -The Gnus Diary Library - -* Diary Summary Line Format:: A nicer summary buffer line format. -* Diary Articles Sorting:: A nicer way to sort messages. -* Diary Headers Generation:: Not doing it manually. -* Diary Group Parameters:: Not handling them manually. - -Gnus Unplugged - -* Agent Basics:: How it all is supposed to work. -* Agent Categories:: How to tell the Gnus Agent what to download. -* Agent Commands:: New commands for all the buffers. -* Agent Visuals:: Ways that the agent may effect your summary buffer. -* Agent as Cache:: The Agent is a big cache too. -* Agent Expiry:: How to make old articles go away. -* Agent Regeneration:: How to recover from lost connections and other accidents. -* Agent and flags:: How the Agent maintains flags. -* Agent and IMAP:: How to use the Agent with @acronym{IMAP}. -* Outgoing Messages:: What happens when you post/mail something? -* Agent Variables:: Customizing is fun. -* Example Setup:: An example @file{~/.gnus.el} file for offline people. -* Batching Agents:: How to fetch news from a @code{cron} job. -* Agent Caveats:: What you think it'll do and what it does. - -Agent Categories - -* Category Syntax:: What a category looks like. -* Category Buffer:: A buffer for maintaining categories. -* Category Variables:: Customize'r'Us. - -Agent Commands - -* Group Agent Commands:: Configure groups and fetch their contents. -* Summary Agent Commands:: Manually select then fetch specific articles. -* Server Agent Commands:: Select the servers that are supported by the agent. - -Scoring - -* Summary Score Commands:: Adding score entries for the current group. -* Group Score Commands:: General score commands. -* Score Variables:: Customize your scoring. (My, what terminology). -* Score File Format:: What a score file may contain. -* Score File Editing:: You can edit score files by hand as well. -* Adaptive Scoring:: Big Sister Gnus knows what you read. -* Home Score File:: How to say where new score entries are to go. -* Followups To Yourself:: Having Gnus notice when people answer you. -* Scoring On Other Headers:: Scoring on non-standard headers. -* Scoring Tips:: How to score effectively. -* Reverse Scoring:: That problem child of old is not problem. -* Global Score Files:: Earth-spanning, ear-splitting score files. -* Kill Files:: They are still here, but they can be ignored. -* Converting Kill Files:: Translating kill files to score files. -* Advanced Scoring:: Using logical expressions to build score rules. -* Score Decays:: It can be useful to let scores wither away. - -Advanced Scoring - -* Advanced Scoring Syntax:: A definition. -* Advanced Scoring Examples:: What they look like. -* Advanced Scoring Tips:: Getting the most out of it. - -Searching - -* nnir:: Searching with various engines. -* nnmairix:: Searching with Mairix. - -nnir - -* What is nnir?:: What does nnir do. -* Basic Usage:: How to perform simple searches. -* Setting up nnir:: How to set up nnir. - -Setting up nnir - -* Associating Engines:: How to associate engines. - -Various - -* Process/Prefix:: A convention used by many treatment commands. -* Interactive:: Making Gnus ask you many questions. -* Symbolic Prefixes:: How to supply some Gnus functions with options. -* Formatting Variables:: You can specify what buffers should look like. -* Window Layout:: Configuring the Gnus buffer windows. -* Faces and Fonts:: How to change how faces look. -* Compilation:: How to speed Gnus up. -* Mode Lines:: Displaying information in the mode lines. -* Highlighting and Menus:: Making buffers look all nice and cozy. -* Daemons:: Gnus can do things behind your back. -* Undo:: Some actions can be undone. -* Predicate Specifiers:: Specifying predicates. -* Moderation:: What to do if you're a moderator. -* Image Enhancements:: Modern versions of Emacs/XEmacs can display images. -* Fuzzy Matching:: What's the big fuzz? -* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. -* Spam Package:: A package for filtering and processing spam. -* The Gnus Registry:: A package for tracking messages by Message-ID. -* Other modes:: Interaction with other modes. -* Various Various:: Things that are really various. - -Formatting Variables - -* Formatting Basics:: A formatting variable is basically a format string. -* Mode Line Formatting:: Some rules about mode line formatting variables. -* Advanced Formatting:: Modifying output in various ways. -* User-Defined Specs:: Having Gnus call your own functions. -* Formatting Fonts:: Making the formatting look colorful and nice. -* Positioning Point:: Moving point to a position after an operation. -* Tabulation:: Tabulating your output. -* Wide Characters:: Dealing with wide characters. - -Image Enhancements - -* X-Face:: Display a funky, teensy black-and-white image. -* Face:: Display a funkier, teensier colored image. -* Smileys:: Show all those happy faces the way they were - meant to be shown. -* Picons:: How to display pictures of what you're reading. -* Gravatars:: Display the avatar of people you read. -* XVarious:: Other XEmacsy Gnusey variables. - -Thwarting Email Spam - -* The problem of spam:: Some background, and some solutions -* Anti-Spam Basics:: Simple steps to reduce the amount of spam. -* SpamAssassin:: How to use external anti-spam tools. -* Hashcash:: Reduce spam by burning CPU time. - -Spam Package - -* Spam Package Introduction:: -* Filtering Incoming Mail:: -* Detecting Spam in Groups:: -* Spam and Ham Processors:: -* Spam Package Configuration Examples:: -* Spam Back Ends:: -* Extending the Spam package:: -* Spam Statistics Package:: - -Spam Statistics Package - -* Creating a spam-stat dictionary:: -* Splitting mail using spam-stat:: -* Low-level interface to the spam-stat dictionary:: - -Appendices - -* XEmacs:: Requirements for installing under XEmacs. -* History:: How Gnus got where it is today. -* On Writing Manuals:: Why this is not a beginner's guide. -* Terminology:: We use really difficult, like, words here. -* Customization:: Tailoring Gnus to your needs. -* Troubleshooting:: What you might try if things do not work. -* Gnus Reference Guide:: Rilly, rilly technical stuff. -* Emacs for Heathens:: A short introduction to Emacsian terms. -* Frequently Asked Questions:: The Gnus FAQ - -History - -* Gnus Versions:: What Gnus versions have been released. -* Why?:: What's the point of Gnus? -* Compatibility:: Just how compatible is Gnus with @sc{gnus}? -* Conformity:: Gnus tries to conform to all standards. -* Emacsen:: Gnus can be run on a few modern Emacsen. -* Gnus Development:: How Gnus is developed. -* Contributors:: Oodles of people. -* New Features:: Pointers to some of the new stuff in Gnus. - -New Features - -* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus. -* September Gnus:: The Thing Formally Known As Gnus 5.2/5.3. -* Red Gnus:: Third time best---Gnus 5.4/5.5. -* Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7. -* Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9. -* Oort Gnus:: It's big. It's far out. Gnus 5.10/5.11. -* No Gnus:: Very punny. - -Customization - -* Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere. -* Slow Terminal Connection:: You run a remote Emacs. -* Little Disk Space:: You feel that having large setup files is icky. -* Slow Machine:: You feel like buying a faster machine. - -Gnus Reference Guide - -* Gnus Utility Functions:: Common functions and variable to use. -* Back End Interface:: How Gnus communicates with the servers. -* Score File Syntax:: A BNF definition of the score file standard. -* Headers:: How Gnus stores headers internally. -* Ranges:: A handy format for storing mucho numbers. -* Group Info:: The group info format. -* Extended Interactive:: Symbolic prefixes and stuff. -* Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen. -* Various File Formats:: Formats of files that Gnus use. - -Back End Interface - -* Required Back End Functions:: Functions that must be implemented. -* Optional Back End Functions:: Functions that need not be implemented. -* Error Messaging:: How to get messages and report errors. -* Writing New Back Ends:: Extending old back ends. -* Hooking New Back Ends Into Gnus:: What has to be done on the Gnus end. -* Mail-like Back Ends:: Some tips on mail back ends. - -Various File Formats - -* Active File Format:: Information on articles and groups available. -* Newsgroups File Format:: Group descriptions. - -Emacs for Heathens - -* Keystrokes:: Entering text and executing commands. -* Emacs Lisp:: The built-in Emacs programming language. - -@end detailmenu -@end menu - -@node Starting Up -@chapter Starting Gnus -@cindex starting up - -If you haven't used Emacs much before using Gnus, read @ref{Emacs for -Heathens} first. - -@kindex M-x gnus -@findex gnus -If your system administrator has set things up properly, starting Gnus -and reading news is extremely easy---you just type @kbd{M-x gnus} in -your Emacs. If not, you should customize the variable -@code{gnus-select-method} as described in @ref{Finding the News}. For a -minimal setup for posting should also customize the variables -@code{user-full-name} and @code{user-mail-address}. - -@findex gnus-other-frame -@kindex M-x gnus-other-frame -If you want to start Gnus in a different frame, you can use the command -@kbd{M-x gnus-other-frame} instead. - -If things do not go smoothly at startup, you have to twiddle some -variables in your @file{~/.gnus.el} file. This file is similar to -@file{~/.emacs}, but is read when Gnus starts. - -If you puzzle at any terms used in this manual, please refer to the -terminology section (@pxref{Terminology}). - -@menu -* Finding the News:: Choosing a method for getting news. -* The Server is Down:: How can I read my mail then? -* Slave Gnusae:: You can have more than one Gnus active at a time. -* New Groups:: What is Gnus supposed to do with new groups? -* Changing Servers:: You may want to move from one server to another. -* Startup Files:: Those pesky startup files---@file{.newsrc}. -* Auto Save:: Recovering from a crash. -* The Active File:: Reading the active file over a slow line Takes Time. -* Startup Variables:: Other variables you might change. -@end menu - - -@node Finding the News -@section Finding the News -@cindex finding news - -First of all, you should know that there is a special buffer called -@code{*Server*} that lists all the servers Gnus knows about. You can -press @kbd{^} from the Group buffer to see it. In the Server buffer, -you can press @kbd{RET} on a defined server to see all the groups it -serves (subscribed or not!). You can also add or delete servers, edit -a foreign server's definition, agentize or de-agentize a server, and -do many other neat things. @xref{Server Buffer}. -@xref{Foreign Groups}. @xref{Agent Basics}. - -@vindex gnus-select-method -@c @head -The @code{gnus-select-method} variable says where Gnus should look for -news. This variable should be a list where the first element says -@dfn{how} and the second element says @dfn{where}. This method is your -native method. All groups not fetched with this method are -secondary or foreign groups. - -For instance, if the @samp{news.somewhere.edu} @acronym{NNTP} server is where -you want to get your daily dosage of news from, you'd say: - -@lisp -(setq gnus-select-method '(nntp "news.somewhere.edu")) -@end lisp - -If you want to read directly from the local spool, say: - -@lisp -(setq gnus-select-method '(nnspool "")) -@end lisp - -If you can use a local spool, you probably should, as it will almost -certainly be much faster. But do not use the local spool if your -server is running Leafnode (which is a simple, standalone private news -server); in this case, use @code{(nntp "localhost")}. - -@vindex gnus-nntpserver-file -@cindex NNTPSERVER -@cindex @acronym{NNTP} server -If this variable is not set, Gnus will take a look at the -@env{NNTPSERVER} environment variable. If that variable isn't set, -Gnus will see whether @code{gnus-nntpserver-file} -(@file{/etc/nntpserver} by default) has any opinions on the matter. -If that fails as well, Gnus will try to use the machine running Emacs -as an @acronym{NNTP} server. That's a long shot, though. - -@findex gnus-group-browse-foreign-server -@kindex B (Group) -However, if you use one @acronym{NNTP} server regularly and are just -interested in a couple of groups from a different server, you would be -better served by using the @kbd{B} command in the group buffer. It will -let you have a look at what groups are available, and you can subscribe -to any of the groups you want to. This also makes @file{.newsrc} -maintenance much tidier. @xref{Foreign Groups}. - -@vindex gnus-secondary-select-methods -@c @head -A slightly different approach to foreign groups is to set the -@code{gnus-secondary-select-methods} variable. The select methods -listed in this variable are in many ways just as native as the -@code{gnus-select-method} server. They will also be queried for active -files during startup (if that's required), and new newsgroups that -appear on these servers will be subscribed (or not) just as native -groups are. - -For instance, if you use the @code{nnmbox} back end to read your mail, -you would typically set this variable to - -@lisp -(setq gnus-secondary-select-methods '((nnmbox ""))) -@end lisp - -Note: the @acronym{NNTP} back end stores marks in marks files -(@pxref{NNTP marks}). This feature makes it easy to share marks between -several Gnus installations, but may slow down things a bit when fetching -new articles. @xref{NNTP marks}, for more information. - - -@node The Server is Down -@section The Server is Down -@cindex server errors - -If the default server is down, Gnus will understandably have some -problems starting. However, if you have some mail groups in addition to -the news groups, you may want to start Gnus anyway. - -Gnus, being the trusting sort of program, will ask whether to proceed -without a native select method if that server can't be contacted. This -will happen whether the server doesn't actually exist (i.e., you have -given the wrong address) or the server has just momentarily taken ill -for some reason or other. If you decide to continue and have no foreign -groups, you'll find it difficult to actually do anything in the group -buffer. But, hey, that's your problem. Blllrph! - -@findex gnus-no-server -@kindex M-x gnus-no-server -@c @head -If you know that the server is definitely down, or you just want to read -your mail without bothering with the server at all, you can use the -@code{gnus-no-server} command to start Gnus. That might come in handy -if you're in a hurry as well. This command will not attempt to contact -your primary server---instead, it will just activate all groups on level -1 and 2. (You should preferably keep no native groups on those two -levels.) Also @pxref{Group Levels}. - - -@node Slave Gnusae -@section Slave Gnusae -@cindex slave - -You might want to run more than one Emacs with more than one Gnus at the -same time. If you are using different @file{.newsrc} files (e.g., if you -are using the two different Gnusae to read from two different servers), -that is no problem whatsoever. You just do it. - -The problem appears when you want to run two Gnusae that use the same -@file{.newsrc} file. - -To work around that problem some, we here at the Think-Tank at the Gnus -Towers have come up with a new concept: @dfn{Masters} and -@dfn{slaves}. (We have applied for a patent on this concept, and have -taken out a copyright on those words. If you wish to use those words in -conjunction with each other, you have to send $1 per usage instance to -me. Usage of the patent (@dfn{Master/Slave Relationships In Computer -Applications}) will be much more expensive, of course.) - -@findex gnus-slave -Anyway, you start one Gnus up the normal way with @kbd{M-x gnus} (or -however you do it). Each subsequent slave Gnusae should be started with -@kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc} -files, but instead save @dfn{slave files} that contain information only -on what groups have been read in the slave session. When a master Gnus -starts, it will read (and delete) these slave files, incorporating all -information from them. (The slave files will be read in the sequence -they were created, so the latest changes will have precedence.) - -Information from the slave files has, of course, precedence over the -information in the normal (i.e., master) @file{.newsrc} file. - -If the @file{.newsrc*} files have not been saved in the master when the -slave starts, you may be prompted as to whether to read an auto-save -file. If you answer ``yes'', the unsaved changes to the master will be -incorporated into the slave. If you answer ``no'', the slave may see some -messages as unread that have been read in the master. - - - -@node New Groups -@section New Groups -@cindex new groups -@cindex subscription - -@vindex gnus-check-new-newsgroups -If you are satisfied that you really never want to see any new groups, -you can set @code{gnus-check-new-newsgroups} to @code{nil}. This will -also save you some time at startup. Even if this variable is -@code{nil}, you can always subscribe to the new groups just by pressing -@kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable -is @code{ask-server} by default. If you set this variable to -@code{always}, then Gnus will query the back ends for new groups even -when you do the @kbd{g} command (@pxref{Scanning New Messages}). - -@menu -* Checking New Groups:: Determining what groups are new. -* Subscription Methods:: What Gnus should do with new groups. -* Filtering New Groups:: Making Gnus ignore certain new groups. -@end menu - - -@node Checking New Groups -@subsection Checking New Groups - -Gnus normally determines whether a group is new or not by comparing -the list of groups from the active file(s) with the lists of -subscribed and dead groups. This isn't a particularly fast method. -If @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will -ask the server for new groups since the last time. This is both -faster and cheaper. This also means that you can get rid of the list -of killed groups (@pxref{Group Levels}) altogether, so you may set -@code{gnus-save-killed-list} to @code{nil}, which will save time both -at startup, at exit, and all over. Saves disk space, too. Why isn't -this the default, then? Unfortunately, not all servers support this -command. - -I bet I know what you're thinking now: How do I find out whether my -server supports @code{ask-server}? No? Good, because I don't have a -fail-safe answer. I would suggest just setting this variable to -@code{ask-server} and see whether any new groups appear within the next -few days. If any do, then it works. If none do, then it doesn't -work. I could write a function to make Gnus guess whether the server -supports @code{ask-server}, but it would just be a guess. So I won't. -You could @code{telnet} to the server and say @code{HELP} and see -whether it lists @samp{NEWGROUPS} among the commands it understands. If -it does, then it might work. (But there are servers that lists -@samp{NEWGROUPS} without supporting the function properly.) - -This variable can also be a list of select methods. If so, Gnus will -issue an @code{ask-server} command to each of the select methods, and -subscribe them (or not) using the normal methods. This might be handy -if you are monitoring a few servers for new groups. A side effect is -that startup will take much longer, so you can meditate while waiting. -Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss. - - -@node Subscription Methods -@subsection Subscription Methods - -@vindex gnus-subscribe-newsgroup-method -What Gnus does when it encounters a new group is determined by the -@code{gnus-subscribe-newsgroup-method} variable. - -This variable should contain a function. This function will be called -with the name of the new group as the only parameter. - -Some handy pre-fab functions are: - -@table @code - -@item gnus-subscribe-zombies -@vindex gnus-subscribe-zombies -Make all new groups zombies (@pxref{Group Levels}). This is the -default. You can browse the zombies later (with @kbd{A z}) and either -kill them all off properly (with @kbd{S z}), or subscribe to them -(with @kbd{u}). - -@item gnus-subscribe-randomly -@vindex gnus-subscribe-randomly -Subscribe all new groups in arbitrary order. This really means that all -new groups will be added at ``the top'' of the group buffer. - -@item gnus-subscribe-alphabetically -@vindex gnus-subscribe-alphabetically -Subscribe all new groups in alphabetical order. - -@item gnus-subscribe-hierarchically -@vindex gnus-subscribe-hierarchically -Subscribe all new groups hierarchically. The difference between this -function and @code{gnus-subscribe-alphabetically} is slight. -@code{gnus-subscribe-alphabetically} will subscribe new groups in a strictly -alphabetical fashion, while this function will enter groups into its -hierarchy. So if you want to have the @samp{rec} hierarchy before the -@samp{comp} hierarchy, this function will not mess that configuration -up. Or something like that. - -@item gnus-subscribe-interactively -@vindex gnus-subscribe-interactively -Subscribe new groups interactively. This means that Gnus will ask -you about @strong{all} new groups. The groups you choose to subscribe -to will be subscribed hierarchically. - -@item gnus-subscribe-killed -@vindex gnus-subscribe-killed -Kill all new groups. - -@item gnus-subscribe-topics -@vindex gnus-subscribe-topics -Put the groups into the topic that has a matching @code{subscribe} topic -parameter (@pxref{Topic Parameters}). For instance, a @code{subscribe} -topic parameter that looks like - -@example -"nnml" -@end example - -will mean that all groups that match that regex will be subscribed under -that topic. - -If no topics match the groups, the groups will be subscribed in the -top-level topic. - -@end table - -@vindex gnus-subscribe-hierarchical-interactive -A closely related variable is -@code{gnus-subscribe-hierarchical-interactive}. (That's quite a -mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a -hierarchical fashion whether to subscribe to new groups or not. Gnus -will ask you for each sub-hierarchy whether you want to descend the -hierarchy or not. - -One common mistake is to set the variable a few paragraphs above -(@code{gnus-subscribe-newsgroup-method}) to -@code{gnus-subscribe-hierarchical-interactive}. This is an error. This -will not work. This is ga-ga. So don't do it. - - -@node Filtering New Groups -@subsection Filtering New Groups - -A nice and portable way to control which new newsgroups should be -subscribed (or ignored) is to put an @dfn{options} line at the start of -the @file{.newsrc} file. Here's an example: - -@example -options -n !alt.all !rec.all sci.all -@end example - -@vindex gnus-subscribe-options-newsgroup-method -This line obviously belongs to a serious-minded intellectual scientific -person (or she may just be plain old boring), because it says that all -groups that have names beginning with @samp{alt} and @samp{rec} should -be ignored, and all groups with names beginning with @samp{sci} should -be subscribed. Gnus will not use the normal subscription method for -subscribing these groups. -@code{gnus-subscribe-options-newsgroup-method} is used instead. This -variable defaults to @code{gnus-subscribe-alphabetically}. - -The ``options -n'' format is very simplistic. The syntax above is all -that is supports -- you can force-subscribe hierarchies, or you can -deny hierarchies, and that's it. - -@vindex gnus-options-not-subscribe -@vindex gnus-options-subscribe -If you don't want to mess with your @file{.newsrc} file, you can just -set the two variables @code{gnus-options-subscribe} and -@code{gnus-options-not-subscribe}. These two variables do exactly the -same as the @file{.newsrc} @samp{options -n} trick. Both are regexps, -and if the new group matches the former, it will be unconditionally -subscribed, and if it matches the latter, it will be ignored. - -@vindex gnus-auto-subscribed-groups -Yet another variable that meddles here is -@code{gnus-auto-subscribed-groups}. It works exactly like -@code{gnus-options-subscribe}, and is therefore really superfluous, -but I thought it would be nice to have two of these. This variable is -more meant for setting some ground rules, while the other variable is -used more for user fiddling. By default this variable makes all new -groups that come from mail back ends (@code{nnml}, @code{nnbabyl}, -@code{nnfolder}, @code{nnmbox}, @code{nnmh}, @code{nnimap}, and -@code{nnmaildir}) subscribed. If you don't like that, just set this -variable to @code{nil}. - -@vindex gnus-auto-subscribed-categories -As if that wasn't enough, @code{gnus-auto-subscribed-categories} also -allows you to specify that new groups should be subscribed based on the -category their select methods belong to. The default is @samp{(mail -post-mail)}, meaning that all new groups from mail-like backends -should be subscribed automatically. - -New groups that match these variables are subscribed using -@code{gnus-subscribe-options-newsgroup-method}. - - -@node Changing Servers -@section Changing Servers -@cindex changing servers - -Sometimes it is necessary to move from one @acronym{NNTP} server to another. -This happens very rarely, but perhaps you change jobs, or one server is -very flaky and you want to use another. - -Changing the server is pretty easy, right? You just change -@code{gnus-select-method} to point to the new server? - -@emph{Wrong!} - -Article numbers are not (in any way) kept synchronized between different -@acronym{NNTP} servers, and the only way Gnus keeps track of what articles -you have read is by keeping track of article numbers. So when you -change @code{gnus-select-method}, your @file{.newsrc} file becomes -worthless. - -@kindex M-x gnus-group-clear-data-on-native-groups -@findex gnus-group-clear-data-on-native-groups -You can use the @kbd{M-x gnus-group-clear-data-on-native-groups} -command to clear out all data that you have on your native groups. -Use with caution. - -@kindex M-x gnus-group-clear-data -@findex gnus-group-clear-data -Clear the data from the current group only---nix out marks and the -list of read articles (@code{gnus-group-clear-data}). - -After changing servers, you @strong{must} move the cache hierarchy away, -since the cached articles will have wrong article numbers, which will -affect which articles Gnus thinks are read. -@code{gnus-group-clear-data-on-native-groups} will ask you if you want -to have it done automatically; for @code{gnus-group-clear-data}, you -can use @kbd{M-x gnus-cache-move-cache} (but beware, it will move the -cache for all groups). - - -@node Startup Files -@section Startup Files -@cindex startup files -@cindex .newsrc -@cindex .newsrc.el -@cindex .newsrc.eld - -Most common Unix news readers use a shared startup file called -@file{.newsrc}. This file contains all the information about what -groups are subscribed, and which articles in these groups have been -read. - -Things got a bit more complicated with @sc{gnus}. In addition to -keeping the @file{.newsrc} file updated, it also used a file called -@file{.newsrc.el} for storing all the information that didn't fit into -the @file{.newsrc} file. (Actually, it also duplicated everything in -the @file{.newsrc} file.) @sc{gnus} would read whichever one of these -files was the most recently saved, which enabled people to swap between -@sc{gnus} and other newsreaders. - -That was kinda silly, so Gnus went one better: In addition to the -@file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called -@file{.newsrc.eld}. It will read whichever of these files that are most -recent, but it will never write a @file{.newsrc.el} file. You should -never delete the @file{.newsrc.eld} file---it contains much information -not stored in the @file{.newsrc} file. - -@vindex gnus-save-newsrc-file -@vindex gnus-read-newsrc-file -You can turn off writing the @file{.newsrc} file by setting -@code{gnus-save-newsrc-file} to @code{nil}, which means you can delete -the file and save some space, as well as exiting from Gnus faster. -However, this will make it impossible to use other newsreaders than -Gnus. But hey, who would want to, right? Similarly, setting -@code{gnus-read-newsrc-file} to @code{nil} makes Gnus ignore the -@file{.newsrc} file and any @file{.newsrc-SERVER} files, which can be -convenient if you use a different news reader occasionally, and you -want to read a different subset of the available groups with that -news reader. - -@vindex gnus-save-killed-list -If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus -will not save the list of killed groups to the startup file. This will -save both time (when starting and quitting) and space (on disk). It -will also mean that Gnus has no record of what groups are new or old, -so the automatic new groups subscription methods become meaningless. -You should always set @code{gnus-check-new-newsgroups} to @code{nil} or -@code{ask-server} if you set this variable to @code{nil} (@pxref{New -Groups}). This variable can also be a regular expression. If that's -the case, remove all groups that do not match this regexp before -saving. This can be useful in certain obscure situations that involve -several servers where not all servers support @code{ask-server}. - -@vindex gnus-startup-file -@vindex gnus-backup-startup-file -@vindex version-control -The @code{gnus-startup-file} variable says where the startup files are. -The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup -file being whatever that one is, with a @samp{.eld} appended. -If you want to keep multiple numbered backups of this file, set -@code{gnus-backup-startup-file}. It respects the same values as the -@code{version-control} variable. - -@vindex gnus-save-newsrc-hook -@vindex gnus-save-quick-newsrc-hook -@vindex gnus-save-standard-newsrc-hook -@code{gnus-save-newsrc-hook} is called before saving any of the newsrc -files, while @code{gnus-save-quick-newsrc-hook} is called just before -saving the @file{.newsrc.eld} file, and -@code{gnus-save-standard-newsrc-hook} is called just before saving the -@file{.newsrc} file. The latter two are commonly used to turn version -control on or off. Version control is on by default when saving the -startup files. If you want to turn backup creation off, say something like: - -@lisp -(defun turn-off-backup () - (set (make-local-variable 'backup-inhibited) t)) - -(add-hook 'gnus-save-quick-newsrc-hook 'turn-off-backup) -(add-hook 'gnus-save-standard-newsrc-hook 'turn-off-backup) -@end lisp - -@vindex gnus-init-file -@vindex gnus-site-init-file -When Gnus starts, it will read the @code{gnus-site-init-file} -(@file{.../site-lisp/gnus-init} by default) and @code{gnus-init-file} -(@file{~/.gnus} by default) files. These are normal Emacs Lisp files -and can be used to avoid cluttering your @file{~/.emacs} and -@file{site-init} files with Gnus stuff. Gnus will also check for files -with the same names as these, but with @file{.elc} and @file{.el} -suffixes. In other words, if you have set @code{gnus-init-file} to -@file{~/.gnus}, it will look for @file{~/.gnus.elc}, @file{~/.gnus.el}, -and finally @file{~/.gnus} (in this order). If Emacs was invoked with -the @option{-q} or @option{--no-init-file} options (@pxref{Initial -Options, ,Initial Options, emacs, The Emacs Manual}), Gnus doesn't read -@code{gnus-init-file}. - - -@node Auto Save -@section Auto Save -@cindex dribble file -@cindex auto-save - -Whenever you do something that changes the Gnus data (reading articles, -catching up, killing/subscribing groups), the change is added to a -special @dfn{dribble buffer}. This buffer is auto-saved the normal -Emacs way. If your Emacs should crash before you have saved the -@file{.newsrc} files, all changes you have made can be recovered from -this file. - -If Gnus detects this file at startup, it will ask the user whether to -read it. The auto save file is deleted whenever the real startup file is -saved. - -@vindex gnus-use-dribble-file -If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and -maintain a dribble buffer. The default is @code{t}. - -@vindex gnus-dribble-directory -Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If -this variable is @code{nil}, which it is by default, Gnus will dribble -into the directory where the @file{.newsrc} file is located. (This is -normally the user's home directory.) The dribble file will get the same -file permissions as the @file{.newsrc} file. - -@vindex gnus-always-read-dribble-file -If @code{gnus-always-read-dribble-file} is non-@code{nil}, Gnus will -read the dribble file on startup without querying the user. - - -@node The Active File -@section The Active File -@cindex active file -@cindex ignored groups - -When Gnus starts, or indeed whenever it tries to determine whether new -articles have arrived, it reads the active file. This is a very large -file that lists all the active groups and articles on the server. - -@vindex gnus-ignored-newsgroups -Before examining the active file, Gnus deletes all lines that match the -regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject -any groups with bogus names, but you can use this variable to make Gnus -ignore hierarchies you aren't ever interested in. However, this is not -recommended. In fact, it's highly discouraged. Instead, @pxref{New -Groups} for an overview of other variables that can be used instead. - -@c This variable is -@c @code{nil} by default, and will slow down active file handling somewhat -@c if you set it to anything else. - -@vindex gnus-read-active-file -@c @head -The active file can be rather Huge, so if you have a slow network, you -can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from -reading the active file. This variable is @code{some} by default. - -Gnus will try to make do by getting information just on the groups that -you actually subscribe to. - -Note that if you subscribe to lots and lots of groups, setting this -variable to @code{nil} will probably make Gnus slower, not faster. At -present, having this variable @code{nil} will slow Gnus down -considerably, unless you read news over a 2400 baud modem. - -This variable can also have the value @code{some}. Gnus will then -attempt to read active info only on the subscribed groups. On some -servers this is quite fast (on sparkling, brand new INN servers that -support the @code{LIST ACTIVE group} command), on others this isn't fast -at all. In any case, @code{some} should be faster than @code{nil}, and -is certainly faster than @code{t} over slow lines. - -Some news servers (old versions of Leafnode and old versions of INN, for -instance) do not support the @code{LIST ACTIVE group}. For these -servers, @code{nil} is probably the most efficient value for this -variable. - -If this variable is @code{nil}, Gnus will ask for group info in total -lock-step, which isn't very fast. If it is @code{some} and you use an -@acronym{NNTP} server, Gnus will pump out commands as fast as it can, and -read all the replies in one swoop. This will normally result in better -performance, but if the server does not support the aforementioned -@code{LIST ACTIVE group} command, this isn't very nice to the server. - -If you think that starting up Gnus takes too long, try all the three -different values for this variable and see what works best for you. - -In any case, if you use @code{some} or @code{nil}, you should definitely -kill all groups that you aren't interested in to speed things up. - -Note that this variable also affects active file retrieval from -secondary select methods. - - -@node Startup Variables -@section Startup Variables - -@table @code - -@item gnus-load-hook -@vindex gnus-load-hook -A hook run while Gnus is being loaded. Note that this hook will -normally be run just once in each Emacs session, no matter how many -times you start Gnus. - -@item gnus-before-startup-hook -@vindex gnus-before-startup-hook -A hook called as the first thing when Gnus is started. - -@item gnus-startup-hook -@vindex gnus-startup-hook -A hook run as the very last thing after starting up Gnus - -@item gnus-started-hook -@vindex gnus-started-hook -A hook that is run as the very last thing after starting up Gnus -successfully. - -@item gnus-setup-news-hook -@vindex gnus-setup-news-hook -A hook that is run after reading the @file{.newsrc} file(s), but before -generating the group buffer. - -@item gnus-check-bogus-newsgroups -@vindex gnus-check-bogus-newsgroups -If non-@code{nil}, Gnus will check for and delete all bogus groups at -startup. A @dfn{bogus group} is a group that you have in your -@file{.newsrc} file, but doesn't exist on the news server. Checking for -bogus groups can take quite a while, so to save time and resources it's -best to leave this option off, and do the checking for bogus groups once -in a while from the group buffer instead (@pxref{Group Maintenance}). - -@item gnus-inhibit-startup-message -@vindex gnus-inhibit-startup-message -If non-@code{nil}, the startup message won't be displayed. That way, -your boss might not notice as easily that you are reading news instead -of doing your job. Note that this variable is used before -@file{~/.gnus.el} is loaded, so it should be set in @file{.emacs} instead. - -@item gnus-no-groups-message -@vindex gnus-no-groups-message -Message displayed by Gnus when no groups are available. - -@item gnus-use-backend-marks -@vindex gnus-use-backend-marks -If non-@code{nil}, Gnus will store article marks both in the -@file{.newsrc.eld} file and in the backends. This will slow down -group operation some. - -@end table - - -@node Group Buffer -@chapter Group Buffer -@cindex group buffer - -@c Alex Schroeder suggests to rearrange this as follows: -@c -@c ok, just save it for reference. I'll go to bed in a minute. -@c 1. Selecting a Group, 2. (new) Finding a Group, 3. Group Levels, -@c 4. Subscription Commands, 5. Group Maneuvering, 6. Group Data, -@c 7. Group Score, 8. Group Buffer Format -@c Group Levels should have more information on levels 5 to 9. I -@c suggest to split the 4th paragraph ("Gnus considers groups...") as follows: -@c First, "Gnus considers groups... (default 9)." -@c New, a table summarizing what levels 1 to 9 mean. -@c Third, "Gnus treats subscribed ... reasons of efficiency" -@c Then expand the next paragraph or add some more to it. -@c This short one sentence explains levels 1 and 2, therefore I understand -@c that I should keep important news at 3 and boring news at 4. -@c Say so! Then go on to explain why I should bother with levels 6 to 9. -@c Maybe keep those that you don't want to read temporarily at 6, -@c those that you never want to read at 8, those that offend your -@c human rights at 9... - - -The @dfn{group buffer} lists all (or parts) of the available groups. It -is the first buffer shown when Gnus starts, and will never be killed as -long as Gnus is active. - -@iftex -@iflatex -\gnusfigure{The Group Buffer}{320}{ -\put(75,50){\epsfig{figure=ps/group,height=9cm}} -\put(120,37){\makebox(0,0)[t]{Buffer name}} -\put(120,38){\vector(1,2){10}} -\put(40,60){\makebox(0,0)[r]{Mode line}} -\put(40,58){\vector(1,0){30}} -\put(200,28){\makebox(0,0)[t]{Native select method}} -\put(200,26){\vector(-1,2){15}} -} -@end iflatex -@end iftex - -@menu -* Group Buffer Format:: Information listed and how you can change it. -* Group Maneuvering:: Commands for moving in the group buffer. -* Selecting a Group:: Actually reading news. -* Subscription Commands:: Unsubscribing, killing, subscribing. -* Group Data:: Changing the info for a group. -* Group Levels:: Levels? What are those, then? -* Group Score:: A mechanism for finding out what groups you like. -* Marking Groups:: You can mark groups for later processing. -* Foreign Groups:: Creating and editing groups. -* Group Parameters:: Each group may have different parameters set. -* Listing Groups:: Gnus can list various subsets of the groups. -* Sorting Groups:: Re-arrange the group order. -* Group Maintenance:: Maintaining a tidy @file{.newsrc} file. -* Browse Foreign Server:: You can browse a server. See what it has to offer. -* Exiting Gnus:: Stop reading news and get some work done. -* Group Topics:: A folding group mode divided into topics. -* Non-ASCII Group Names:: Accessing groups of non-English names. -* Misc Group Stuff:: Other stuff that you can to do. -@end menu - - -@node Group Buffer Format -@section Group Buffer Format - -@menu -* Group Line Specification:: Deciding how the group buffer is to look. -* Group Mode Line Specification:: The group buffer mode line. -* Group Highlighting:: Having nice colors in the group buffer. -@end menu - -You can customize the Group Mode tool bar, see @kbd{M-x -customize-apropos RET gnus-group-tool-bar}. This feature is only -available in Emacs. - -The tool bar icons are now (de)activated correctly depending on the -cursor position. Therefore, moving around in the Group Buffer is -slower. You can disable this via the variable -@code{gnus-group-update-tool-bar}. Its default value depends on your -Emacs version. - -@node Group Line Specification -@subsection Group Line Specification -@cindex group buffer format - -The default format of the group buffer is nice and dull, but you can -make it as exciting and ugly as you feel like. - -Here's a couple of example group lines: - -@example - 25: news.announce.newusers - * 0: alt.fan.andrea-dworkin -@end example - -Quite simple, huh? - -You can see that there are 25 unread articles in -@samp{news.announce.newusers}. There are no unread articles, but some -ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little -asterisk at the beginning of the line?). - -@vindex gnus-group-line-format -You can change that format to whatever you want by fiddling with the -@code{gnus-group-line-format} variable. This variable works along the -lines of a @code{format} specification, which is pretty much the same as -a @code{printf} specifications, for those of you who use (feh!) C. -@xref{Formatting Variables}. - -@samp{%M%S%5y:%B%(%g%)\n} is the value that produced those lines above. - -There should always be a colon on the line; the cursor always moves to -the colon after performing an operation. @xref{Positioning -Point}. Nothing else is required---not even the group name. All -displayed text is just window dressing, and is never examined by Gnus. -Gnus stores all real information it needs using text properties. - -(Note that if you make a really strange, wonderful, spreadsheet-like -layout, everybody will believe you are hard at work with the accounting -instead of wasting time reading news.) - -Here's a list of all available format characters: - -@table @samp - -@item M -An asterisk if the group only has marked articles. - -@item S -Whether the group is subscribed. - -@item L -Level of subscribedness. - -@item N -Number of unread articles. - -@item I -Number of dormant articles. - -@item T -Number of ticked articles. - -@item R -Number of read articles. - -@item U -Number of unseen articles. - -@item t -Estimated total number of articles. (This is really @var{max-number} -minus @var{min-number} plus 1.) - -Gnus uses this estimation because the @acronym{NNTP} protocol provides -efficient access to @var{max-number} and @var{min-number} but getting -the true unread message count is not possible efficiently. For -hysterical raisins, even the mail back ends, where the true number of -unread messages might be available efficiently, use the same limited -interface. To remove this restriction from Gnus means that the back -end interface has to be changed, which is not an easy job. - -The nnml backend (@pxref{Mail Spool}) has a feature called ``group -compaction'' which circumvents this deficiency: the idea is to -renumber all articles from 1, removing all gaps between numbers, hence -getting a correct total count. Other backends may support this in the -future. In order to keep your total article count relatively up to -date, you might want to compact your groups (or even directly your -server) from time to time. @xref{Misc Group Stuff}, @xref{Server Commands}. - -@item y -Number of unread, unticked, non-dormant articles. - -@item i -Number of ticked and dormant articles. - -@item g -Full group name. - -@item G -Group name. - -@item C -Group comment (@pxref{Group Parameters}) or group name if there is no -comment element in the group parameters. - -@item D -Newsgroup description. You need to read the group descriptions -before these will appear, and to do that, you either have to set -@code{gnus-read-active-file} or use the group buffer @kbd{M-d} -command. - -@item o -@samp{m} if moderated. - -@item O -@samp{(m)} if moderated. - -@item s -Select method. - -@item B -If the summary buffer for the group is open or not. - -@item n -Select from where. - -@item z -A string that looks like @samp{<%s:%n>} if a foreign select method is -used. - -@item P -Indentation based on the level of the topic (@pxref{Group Topics}). - -@item c -@vindex gnus-group-uncollapsed-levels -Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels} -variable says how many levels to leave at the end of the group name. -The default is 1---this will mean that group names like -@samp{gnu.emacs.gnus} will be shortened to @samp{g.e.gnus}. - -@item m -@vindex gnus-new-mail-mark -@cindex % -@samp{%} (@code{gnus-new-mail-mark}) if there has arrived new mail to -the group lately. - -@item p -@samp{#} (@code{gnus-process-mark}) if the group is process marked. - -@item d -A string that says when you last read the group (@pxref{Group -Timestamp}). - -@item F -The disk space used by the articles fetched by both the cache and -agent. The value is automatically scaled to bytes(B), kilobytes(K), -megabytes(M), or gigabytes(G) to minimize the column width. A format -of %7F is sufficient for a fixed-width column. - -@item u -User defined specifier. The next character in the format string should -be a letter. Gnus will call the function -@code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter -following @samp{%u}. The function will be passed a single dummy -parameter as argument. The function should return a string, which will -be inserted into the buffer just like information from any other -specifier. -@end table - -@cindex * -All the ``number-of'' specs will be filled with an asterisk (@samp{*}) -if no info is available---for instance, if it is a non-activated foreign -group, or a bogus native group. - - -@node Group Mode Line Specification -@subsection Group Mode Line Specification -@cindex group mode line - -@vindex gnus-group-mode-line-format -The mode line can be changed by setting -@code{gnus-group-mode-line-format} (@pxref{Mode Line Formatting}). It -doesn't understand that many format specifiers: - -@table @samp -@item S -The native news server. -@item M -The native select method. -@end table - - -@node Group Highlighting -@subsection Group Highlighting -@cindex highlighting -@cindex group highlighting - -@vindex gnus-group-highlight -Highlighting in the group buffer is controlled by the -@code{gnus-group-highlight} variable. This is an alist with elements -that look like @code{(@var{form} . @var{face})}. If @var{form} evaluates to -something non-@code{nil}, the @var{face} will be used on the line. - -Here's an example value for this variable that might look nice if the -background is dark: - -@lisp -(cond (window-system - (setq custom-background-mode 'light) - (defface my-group-face-1 - '((t (:foreground "Red" :bold t))) "First group face") - (defface my-group-face-2 - '((t (:foreground "DarkSeaGreen4" :bold t))) - "Second group face") - (defface my-group-face-3 - '((t (:foreground "Green4" :bold t))) "Third group face") - (defface my-group-face-4 - '((t (:foreground "SteelBlue" :bold t))) "Fourth group face") - (defface my-group-face-5 - '((t (:foreground "Blue" :bold t))) "Fifth group face"))) - -(setq gnus-group-highlight - '(((> unread 200) . my-group-face-1) - ((and (< level 3) (zerop unread)) . my-group-face-2) - ((< level 3) . my-group-face-3) - ((zerop unread) . my-group-face-4) - (t . my-group-face-5))) -@end lisp - -Also @pxref{Faces and Fonts}. - -Variables that are dynamically bound when the forms are evaluated -include: - -@table @code -@item group -The group name. -@item unread -The number of unread articles in the group. -@item method -The select method. -@item mailp -Whether the group is a mail group. -@item level -The level of the group. -@item score -The score of the group. -@item ticked -The number of ticked articles in the group. -@item total -The total number of articles in the group. Or rather, -@var{max-number} minus @var{min-number} plus one. -@item topic -When using the topic minor mode, this variable is bound to the current -topic being inserted. -@end table - -When the forms are @code{eval}ed, point is at the beginning of the line -of the group in question, so you can use many of the normal Gnus -functions for snarfing info on the group. - -@vindex gnus-group-update-hook -@findex gnus-group-highlight-line -@code{gnus-group-update-hook} is called when a group line is changed. -It will not be called when @code{gnus-visual} is @code{nil}. - - -@node Group Maneuvering -@section Group Maneuvering -@cindex group movement - -All movement commands understand the numeric prefix and will behave as -expected, hopefully. - -@table @kbd - -@item n -@kindex n (Group) -@findex gnus-group-next-unread-group -Go to the next group that has unread articles -(@code{gnus-group-next-unread-group}). - -@item p -@itemx DEL -@kindex DEL (Group) -@kindex p (Group) -@findex gnus-group-prev-unread-group -Go to the previous group that has unread articles -(@code{gnus-group-prev-unread-group}). - -@item N -@kindex N (Group) -@findex gnus-group-next-group -Go to the next group (@code{gnus-group-next-group}). - -@item P -@kindex P (Group) -@findex gnus-group-prev-group -Go to the previous group (@code{gnus-group-prev-group}). - -@item M-n -@kindex M-n (Group) -@findex gnus-group-next-unread-group-same-level -Go to the next unread group on the same (or lower) level -(@code{gnus-group-next-unread-group-same-level}). - -@item M-p -@kindex M-p (Group) -@findex gnus-group-prev-unread-group-same-level -Go to the previous unread group on the same (or lower) level -(@code{gnus-group-prev-unread-group-same-level}). -@end table - -Three commands for jumping to groups: - -@table @kbd - -@item j -@kindex j (Group) -@findex gnus-group-jump-to-group -Jump to a group (and make it visible if it isn't already) -(@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just -like living groups. - -@item , -@kindex , (Group) -@findex gnus-group-best-unread-group -Jump to the unread group with the lowest level -(@code{gnus-group-best-unread-group}). - -@item . -@kindex . (Group) -@findex gnus-group-first-unread-group -Jump to the first group with unread articles -(@code{gnus-group-first-unread-group}). -@end table - -@vindex gnus-group-goto-unread -If @code{gnus-group-goto-unread} is @code{nil}, all the movement -commands will move to the next group, not the next unread group. Even -the commands that say they move to the next unread group. The default -is @code{t}. - -@vindex gnus-summary-next-group-on-exit -If @code{gnus-summary-next-group-on-exit} is @code{t}, when a summary is -exited, the point in the group buffer is moved to the next unread group. -Otherwise, the point is set to the group just exited. The default is -@code{t}. - -@node Selecting a Group -@section Selecting a Group -@cindex group selection - -@table @kbd - -@item SPACE -@kindex SPACE (Group) -@findex gnus-group-read-group -Select the current group, switch to the summary buffer and display the -first unread article (@code{gnus-group-read-group}). If there are no -unread articles in the group, or if you give a non-numerical prefix to -this command, Gnus will offer to fetch all the old articles in this -group from the server. If you give a numerical prefix @var{n}, @var{n} -determines the number of articles Gnus will fetch. If @var{n} is -positive, Gnus fetches the @var{n} newest articles, if @var{n} is -negative, Gnus fetches the @code{abs(@var{n})} oldest articles. - -Thus, @kbd{SPC} enters the group normally, @kbd{C-u SPC} offers old -articles, @kbd{C-u 4 2 SPC} fetches the 42 newest articles, and @kbd{C-u -- 4 2 SPC} fetches the 42 oldest ones. - -When you are in the group (in the Summary buffer), you can type -@kbd{M-g} to fetch new articles, or @kbd{C-u M-g} to also show the old -ones. - -@item RET -@kindex RET (Group) -@findex gnus-group-select-group -Select the current group and switch to the summary buffer -(@code{gnus-group-select-group}). Takes the same arguments as -@code{gnus-group-read-group}---the only difference is that this command -does not display the first unread article automatically upon group -entry. - -@item M-RET -@kindex M-RET (Group) -@findex gnus-group-quick-select-group -This does the same as the command above, but tries to do it with the -minimum amount of fuzz (@code{gnus-group-quick-select-group}). No -scoring/killing will be performed, there will be no highlights and no -expunging. This might be useful if you're in a real hurry and have to -enter some humongous group. If you give a 0 prefix to this command -(i.e., @kbd{0 M-RET}), Gnus won't even generate the summary buffer, -which is useful if you want to toggle threading before generating the -summary buffer (@pxref{Summary Generation Commands}). - -@item M-SPACE -@kindex M-SPACE (Group) -@findex gnus-group-visible-select-group -This is yet one more command that does the same as the @kbd{RET} -command, but this one does it without expunging and hiding dormants -(@code{gnus-group-visible-select-group}). - -@item C-M-RET -@kindex C-M-RET (Group) -@findex gnus-group-select-group-ephemerally -Finally, this command selects the current group ephemerally without -doing any processing of its contents -(@code{gnus-group-select-group-ephemerally}). Even threading has been -turned off. Everything you do in the group after selecting it in this -manner will have no permanent effects. - -@end table - -@vindex gnus-large-newsgroup -The @code{gnus-large-newsgroup} variable says what Gnus should -consider to be a big group. If it is @code{nil}, no groups are -considered big. The default value is 200. If the group has more -(unread and/or ticked) articles than this, Gnus will query the user -before entering the group. The user can then specify how many -articles should be fetched from the server. If the user specifies a -negative number (@var{-n}), the @var{n} oldest articles will be -fetched. If it is positive, the @var{n} articles that have arrived -most recently will be fetched. - -@vindex gnus-large-ephemeral-newsgroup -@code{gnus-large-ephemeral-newsgroup} is the same as -@code{gnus-large-newsgroup}, but is only used for ephemeral -newsgroups. - -@vindex gnus-newsgroup-maximum-articles -In groups in some news servers, there might be a big gap between a few -very old articles that will never be expired and the recent ones. In -such a case, the server will return the data like @code{(1 . 30000000)} -for the @code{LIST ACTIVE group} command, for example. Even if there -are actually only the articles 1-10 and 29999900-30000000, Gnus doesn't -know it at first and prepares for getting 30000000 articles. However, -it will consume hundreds megabytes of memories and might make Emacs get -stuck as the case may be. If you use such news servers, set the -variable @code{gnus-newsgroup-maximum-articles} to a positive number. -The value means that Gnus ignores articles other than this number of the -latest ones in every group. For instance, the value 10000 makes Gnus -get only the articles 29990001-30000000 (if the latest article number is -30000000 in a group). Note that setting this variable to a number might -prevent you from reading very old articles. The default value of the -variable @code{gnus-newsgroup-maximum-articles} is @code{nil}, which -means Gnus never ignores old articles. - -@vindex gnus-select-group-hook -@vindex gnus-auto-select-first -@vindex gnus-auto-select-subject -If @code{gnus-auto-select-first} is non-@code{nil}, select an article -automatically when entering a group with the @kbd{SPACE} command. -Which article this is controlled by the -@code{gnus-auto-select-subject} variable. Valid values for this -variable are: - -@table @code - -@item unread -Place point on the subject line of the first unread article. - -@item first -Place point on the subject line of the first article. - -@item unseen -Place point on the subject line of the first unseen article. - -@item unseen-or-unread -Place point on the subject line of the first unseen article, and if -there is no such article, place point on the subject line of the first -unread article. - -@item best -Place point on the subject line of the highest-scored unread article. - -@end table - -This variable can also be a function. In that case, that function -will be called to place point on a subject line. - -If you want to prevent automatic selection in some group (say, in a -binary group with Huge articles) you can set the -@code{gnus-auto-select-first} variable to @code{nil} in -@code{gnus-select-group-hook}, which is called when a group is -selected. - - -@node Subscription Commands -@section Subscription Commands -@cindex subscription - -The following commands allow for managing your subscriptions in the -Group buffer. If you want to subscribe to many groups, it's probably -more convenient to go to the @ref{Server Buffer}, and choose the -server there using @kbd{RET} or @kbd{SPC}. Then you'll have the -commands listed in @ref{Browse Foreign Server} at hand. - -@table @kbd - -@item S t -@itemx u -@kindex S t (Group) -@kindex u (Group) -@findex gnus-group-unsubscribe-current-group -@c @icon{gnus-group-unsubscribe} -Toggle subscription to the current group -(@code{gnus-group-unsubscribe-current-group}). - -@item S s -@itemx U -@kindex S s (Group) -@kindex U (Group) -@findex gnus-group-unsubscribe-group -Prompt for a group to subscribe, and then subscribe it. If it was -subscribed already, unsubscribe it instead -(@code{gnus-group-unsubscribe-group}). - -@item S k -@itemx C-k -@kindex S k (Group) -@kindex C-k (Group) -@findex gnus-group-kill-group -@c @icon{gnus-group-kill-group} -Kill the current group (@code{gnus-group-kill-group}). - -@item S y -@itemx C-y -@kindex S y (Group) -@kindex C-y (Group) -@findex gnus-group-yank-group -Yank the last killed group (@code{gnus-group-yank-group}). - -@item C-x C-t -@kindex C-x C-t (Group) -@findex gnus-group-transpose-groups -Transpose two groups (@code{gnus-group-transpose-groups}). This isn't -really a subscription command, but you can use it instead of a -kill-and-yank sequence sometimes. - -@item S w -@itemx C-w -@kindex S w (Group) -@kindex C-w (Group) -@findex gnus-group-kill-region -Kill all groups in the region (@code{gnus-group-kill-region}). - -@item S z -@kindex S z (Group) -@findex gnus-group-kill-all-zombies -Kill all zombie groups (@code{gnus-group-kill-all-zombies}). - -@item S C-k -@kindex S C-k (Group) -@findex gnus-group-kill-level -Kill all groups on a certain level (@code{gnus-group-kill-level}). -These groups can't be yanked back after killing, so this command should -be used with some caution. The only time where this command comes in -really handy is when you have a @file{.newsrc} with lots of unsubscribed -groups that you want to get rid off. @kbd{S C-k} on level 7 will -kill off all unsubscribed groups that do not have message numbers in the -@file{.newsrc} file. - -@end table - -Also @pxref{Group Levels}. - - -@node Group Data -@section Group Data - -@table @kbd - -@item c -@kindex c (Group) -@findex gnus-group-catchup-current -@vindex gnus-group-catchup-group-hook -@c @icon{gnus-group-catchup-current} -Mark all unticked articles in this group as read -(@code{gnus-group-catchup-current}). -@code{gnus-group-catchup-group-hook} is called when catching up a group from -the group buffer. - -@item C -@kindex C (Group) -@findex gnus-group-catchup-current-all -Mark all articles in this group, even the ticked ones, as read -(@code{gnus-group-catchup-current-all}). - -@item M-c -@kindex M-c (Group) -@findex gnus-group-clear-data -Clear the data from the current group---nix out marks and the list of -read articles (@code{gnus-group-clear-data}). - -@item M-x gnus-group-clear-data-on-native-groups -@kindex M-x gnus-group-clear-data-on-native-groups -@findex gnus-group-clear-data-on-native-groups -If you have switched from one @acronym{NNTP} server to another, all your marks -and read ranges have become worthless. You can use this command to -clear out all data that you have on your native groups. Use with -caution. - -@end table - - -@node Group Levels -@section Group Levels -@cindex group level -@cindex level - -All groups have a level of @dfn{subscribedness}. For instance, if a -group is on level 2, it is more subscribed than a group on level 5. You -can ask Gnus to just list groups on a given level or lower -(@pxref{Listing Groups}), or to just check for new articles in groups on -a given level or lower (@pxref{Scanning New Messages}). - -Remember: The higher the level of the group, the less important it is. - -@table @kbd - -@item S l -@kindex S l (Group) -@findex gnus-group-set-current-level -Set the level of the current group. If a numeric prefix is given, the -next @var{n} groups will have their levels set. The user will be -prompted for a level. -@end table - -@vindex gnus-level-killed -@vindex gnus-level-zombie -@vindex gnus-level-unsubscribed -@vindex gnus-level-subscribed -Gnus considers groups from levels 1 to -@code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed, -@code{gnus-level-subscribed} (exclusive) and -@code{gnus-level-unsubscribed} (inclusive) (default 7) to be -unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead) -(default 8) and @code{gnus-level-killed} to be killed (completely dead) -(default 9). Gnus treats subscribed and unsubscribed groups exactly the -same, but zombie and killed groups have no information on what articles -you have read, etc, stored. This distinction between dead and living -groups isn't done because it is nice or clever, it is done purely for -reasons of efficiency. - -It is recommended that you keep all your mail groups (if any) on quite -low levels (e.g. 1 or 2). - -Maybe the following description of the default behavior of Gnus helps to -understand what these levels are all about. By default, Gnus shows you -subscribed nonempty groups, but by hitting @kbd{L} you can have it show -empty subscribed groups and unsubscribed groups, too. Type @kbd{l} to -go back to showing nonempty subscribed groups again. Thus, unsubscribed -groups are hidden, in a way. - -@cindex zombie groups -Zombie and killed groups are similar to unsubscribed groups in that they -are hidden by default. But they are different from subscribed and -unsubscribed groups in that Gnus doesn't ask the news server for -information (number of messages, number of unread messages) on zombie -and killed groups. Normally, you use @kbd{C-k} to kill the groups you -aren't interested in. If most groups are killed, Gnus is faster. - -Why does Gnus distinguish between zombie and killed groups? Well, when -a new group arrives on the server, Gnus by default makes it a zombie -group. This means that you are normally not bothered with new groups, -but you can type @kbd{A z} to get a list of all new groups. Subscribe -the ones you like and kill the ones you don't want. (@kbd{A k} shows a -list of killed groups.) - -If you want to play with the level variables, you should show some care. -Set them once, and don't touch them ever again. Better yet, don't touch -them at all unless you know exactly what you're doing. - -@vindex gnus-level-default-unsubscribed -@vindex gnus-level-default-subscribed -Two closely related variables are @code{gnus-level-default-subscribed} -(default 3) and @code{gnus-level-default-unsubscribed} (default 6), -which are the levels that new groups will be put on if they are -(un)subscribed. These two variables should, of course, be inside the -relevant valid ranges. - -@vindex gnus-keep-same-level -If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands -will only move to groups of the same level (or lower). In -particular, going from the last article in one group to the next group -will go to the next group of the same level (or lower). This might be -handy if you want to read the most important groups before you read the -rest. - -If this variable is @code{best}, Gnus will make the next newsgroup the -one with the best level. - -@vindex gnus-group-default-list-level -All groups with a level less than or equal to -@code{gnus-group-default-list-level} will be listed in the group buffer -by default. -This variable can also be a function. In that case, that function will -be called and the result will be used as value. - - -@vindex gnus-group-list-inactive-groups -If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active -groups will be listed along with the unread groups. This variable is -@code{t} by default. If it is @code{nil}, inactive groups won't be -listed. - -@vindex gnus-group-use-permanent-levels -If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you -give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will -use this level as the ``work'' level. - -@vindex gnus-activate-level -Gnus will normally just activate (i. e., query the server about) groups -on level @code{gnus-activate-level} or less. If you don't want to -activate unsubscribed groups, for instance, you might set this variable -to 5. The default is 6. - - -@node Group Score -@section Group Score -@cindex group score -@cindex group rank -@cindex rank - -You would normally keep important groups on high levels, but that scheme -is somewhat restrictive. Don't you wish you could have Gnus sort the -group buffer according to how often you read groups, perhaps? Within -reason? - -This is what @dfn{group score} is for. You can have Gnus assign a score -to each group through the mechanism described below. You can then sort -the group buffer based on this score. Alternatively, you can sort on -score and then level. (Taken together, the level and the score is -called the @dfn{rank} of the group. A group that is on level 4 and has -a score of 1 has a higher rank than a group on level 5 that has a score -of 300. (The level is the most significant part and the score is the -least significant part.)) - -@findex gnus-summary-bubble-group -If you want groups you read often to get higher scores than groups you -read seldom you can add the @code{gnus-summary-bubble-group} function to -the @code{gnus-summary-exit-hook} hook. This will result (after -sorting) in a bubbling sort of action. If you want to see that in -action after each summary exit, you can add -@code{gnus-group-sort-groups-by-rank} or -@code{gnus-group-sort-groups-by-score} to the same hook, but that will -slow things down somewhat. - - -@node Marking Groups -@section Marking Groups -@cindex marking groups - -If you want to perform some command on several groups, and they appear -subsequently in the group buffer, you would normally just give a -numerical prefix to the command. Most group commands will then do your -bidding on those groups. - -However, if the groups are not in sequential order, you can still -perform a command on several groups. You simply mark the groups first -with the process mark and then execute the command. - -@table @kbd - -@item # -@kindex # (Group) -@itemx M m -@kindex M m (Group) -@findex gnus-group-mark-group -Set the mark on the current group (@code{gnus-group-mark-group}). - -@item M-# -@kindex M-# (Group) -@itemx M u -@kindex M u (Group) -@findex gnus-group-unmark-group -Remove the mark from the current group -(@code{gnus-group-unmark-group}). - -@item M U -@kindex M U (Group) -@findex gnus-group-unmark-all-groups -Remove the mark from all groups (@code{gnus-group-unmark-all-groups}). - -@item M w -@kindex M w (Group) -@findex gnus-group-mark-region -Mark all groups between point and mark (@code{gnus-group-mark-region}). - -@item M b -@kindex M b (Group) -@findex gnus-group-mark-buffer -Mark all groups in the buffer (@code{gnus-group-mark-buffer}). - -@item M r -@kindex M r (Group) -@findex gnus-group-mark-regexp -Mark all groups that match some regular expression -(@code{gnus-group-mark-regexp}). -@end table - -Also @pxref{Process/Prefix}. - -@findex gnus-group-universal-argument -If you want to execute some command on all groups that have been marked -with the process mark, you can use the @kbd{M-&} -(@code{gnus-group-universal-argument}) command. It will prompt you for -the command to be executed. - - -@node Foreign Groups -@section Foreign Groups -@cindex foreign groups - -If you recall how to subscribe to servers (@pxref{Finding the News}) -you will remember that @code{gnus-secondary-select-methods} and -@code{gnus-select-method} let you write a definition in Emacs Lisp of -what servers you want to see when you start up. The alternate -approach is to use foreign servers and groups. ``Foreign'' here means -they are not coming from the select methods. All foreign server -configuration and subscriptions are stored only in the -@file{~/.newsrc.eld} file. - -Below are some group mode commands for making and editing general foreign -groups, as well as commands to ease the creation of a few -special-purpose groups. All these commands insert the newly created -groups under point---@code{gnus-subscribe-newsgroup-method} is not -consulted. - -Changes from the group editing commands are stored in -@file{~/.newsrc.eld} (@code{gnus-startup-file}). An alternative is the -variable @code{gnus-parameters}, @xref{Group Parameters}. - -@table @kbd - -@item G m -@kindex G m (Group) -@findex gnus-group-make-group -@cindex making groups -Make a new group (@code{gnus-group-make-group}). Gnus will prompt you -for a name, a method and possibly an @dfn{address}. For an easier way -to subscribe to @acronym{NNTP} groups (@pxref{Browse Foreign Server}). - -@item G M -@kindex G M (Group) -@findex gnus-group-read-ephemeral-group -Make an ephemeral group (@code{gnus-group-read-ephemeral-group}). Gnus -will prompt you for a name, a method and an @dfn{address}. - -@item G r -@kindex G r (Group) -@findex gnus-group-rename-group -@cindex renaming groups -Rename the current group to something else -(@code{gnus-group-rename-group}). This is valid only on some -groups---mail groups mostly. This command might very well be quite slow -on some back ends. - -@item G c -@kindex G c (Group) -@cindex customizing -@findex gnus-group-customize -Customize the group parameters (@code{gnus-group-customize}). - -@item G e -@kindex G e (Group) -@findex gnus-group-edit-group-method -@cindex renaming groups -Enter a buffer where you can edit the select method of the current -group (@code{gnus-group-edit-group-method}). - -@item G p -@kindex G p (Group) -@findex gnus-group-edit-group-parameters -Enter a buffer where you can edit the group parameters -(@code{gnus-group-edit-group-parameters}). - -@item G E -@kindex G E (Group) -@findex gnus-group-edit-group -Enter a buffer where you can edit the group info -(@code{gnus-group-edit-group}). - -@item G d -@kindex G d (Group) -@findex gnus-group-make-directory-group -@cindex nndir -Make a directory group (@pxref{Directory Groups}). You will be prompted -for a directory name (@code{gnus-group-make-directory-group}). - -@item G h -@kindex G h (Group) -@cindex help group -@findex gnus-group-make-help-group -Make the Gnus help group (@code{gnus-group-make-help-group}). - -@item G D -@kindex G D (Group) -@findex gnus-group-enter-directory -@cindex nneething -Read an arbitrary directory as if it were a newsgroup with the -@code{nneething} back end (@code{gnus-group-enter-directory}). -@xref{Anything Groups}. - -@item G f -@kindex G f (Group) -@findex gnus-group-make-doc-group -@cindex ClariNet Briefs -@cindex nndoc -Make a group based on some file or other -(@code{gnus-group-make-doc-group}). If you give a prefix to this -command, you will be prompted for a file name and a file type. -Currently supported types are @code{mbox}, @code{babyl}, -@code{digest}, @code{news}, @code{rnews}, @code{mmdf}, @code{forward}, -@code{rfc934}, @code{rfc822-forward}, @code{mime-parts}, -@code{standard-digest}, @code{slack-digest}, @code{clari-briefs}, -@code{nsmail}, @code{outlook}, @code{oe-dbx}, and @code{mailman}. If -you run this command without a prefix, Gnus will guess at the file -type. @xref{Document Groups}. - -@item G u -@kindex G u (Group) -@vindex gnus-useful-groups -@findex gnus-group-make-useful-group -Create one of the groups mentioned in @code{gnus-useful-groups} -(@code{gnus-group-make-useful-group}). - -@item G w -@kindex G w (Group) -@findex gnus-group-make-web-group -@cindex Google -@cindex nnweb -@cindex gmane -Make an ephemeral group based on a web search -(@code{gnus-group-make-web-group}). If you give a prefix to this -command, make a solid group instead. You will be prompted for the -search engine type and the search string. Valid search engine types -include @code{google}, @code{dejanews}, and @code{gmane}. -@xref{Web Searches}. - -If you use the @code{google} search engine, you can limit the search -to a particular group by using a match string like -@samp{shaving group:alt.sysadmin.recovery}. - -@item G R -@kindex G R (Group) -@findex gnus-group-make-rss-group -Make a group based on an @acronym{RSS} feed -(@code{gnus-group-make-rss-group}). You will be prompted for an URL. -@xref{RSS}. - -@item G DEL -@kindex G DEL (Group) -@findex gnus-group-delete-group -This function will delete the current group -(@code{gnus-group-delete-group}). If given a prefix, this function will -actually delete all the articles in the group, and forcibly remove the -group itself from the face of the Earth. Use a prefix only if you are -absolutely sure of what you are doing. This command can't be used on -read-only groups (like @code{nntp} groups), though. - -@item G V -@kindex G V (Group) -@findex gnus-group-make-empty-virtual -Make a new, fresh, empty @code{nnvirtual} group -(@code{gnus-group-make-empty-virtual}). @xref{Virtual Groups}. - -@item G v -@kindex G v (Group) -@findex gnus-group-add-to-virtual -Add the current group to an @code{nnvirtual} group -(@code{gnus-group-add-to-virtual}). Uses the process/prefix convention. -@end table - -@xref{Select Methods}, for more information on the various select -methods. - -@vindex gnus-activate-foreign-newsgroups -If @code{gnus-activate-foreign-newsgroups} is a positive number, -Gnus will check all foreign groups with this level or lower at startup. -This might take quite a while, especially if you subscribe to lots of -groups from different @acronym{NNTP} servers. Also @pxref{Group Levels}; -@code{gnus-activate-level} also affects activation of foreign -newsgroups. - - -The following commands create ephemeral groups. They can be called not -only from the Group buffer, but in any Gnus buffer. - -@table @code -@item gnus-read-ephemeral-gmane-group -@findex gnus-read-ephemeral-gmane-group -@vindex gnus-gmane-group-download-format -Read an ephemeral group on Gmane.org. The articles are downloaded via -HTTP using the URL specified by @code{gnus-gmane-group-download-format}. -Gnus will prompt you for a group name, the start article number and an -the article range. - -@item gnus-read-ephemeral-gmane-group-url -@findex gnus-read-ephemeral-gmane-group-url -This command is similar to @code{gnus-read-ephemeral-gmane-group}, but -the group name and the article number and range are constructed from a -given @acronym{URL}. Supported @acronym{URL} formats include e.g. -@url{http://thread.gmane.org/gmane.foo.bar/12300/focus=12399}, -@url{http://thread.gmane.org/gmane.foo.bar/12345/}, -@url{http://article.gmane.org/gmane.foo.bar/12345/}, -@url{http://permalink.gmane.org/gmane.foo.bar/12345/}, and -@url{http://news.gmane.org/group/gmane.foo.bar/thread=12345}. - -@item gnus-read-ephemeral-emacs-bug-group -@findex gnus-read-ephemeral-emacs-bug-group -Read an Emacs bug report in an ephemeral group. Gnus will prompt for a -bug number. The default is the number at point. The @acronym{URL} is -specified in @code{gnus-bug-group-download-format-alist}. - -@item gnus-read-ephemeral-debian-bug-group -@findex gnus-read-ephemeral-debian-bug-group -Read a Debian bug report in an ephemeral group. Analog to -@code{gnus-read-ephemeral-emacs-bug-group}. -@end table - -Some of these command are also useful for article buttons, @xref{Article -Buttons}. - -Here is an example: -@lisp -(require 'gnus-art) -(add-to-list - 'gnus-button-alist - '("#\\([0-9]+\\)\\>" 1 - (string-match "\\" (or gnus-newsgroup-name "")) - gnus-read-ephemeral-emacs-bug-group 1)) -@end lisp - - -@node Group Parameters -@section Group Parameters -@cindex group parameters - -The group parameters store information local to a particular group. - -Use the @kbd{G p} or the @kbd{G c} command to edit group parameters of a -group. (@kbd{G p} presents you with a Lisp-based interface, @kbd{G c} -presents you with a Customize-like interface. The latter helps avoid -silly Lisp errors.) You might also be interested in reading about topic -parameters (@pxref{Topic Parameters}). -Additionally, you can set group parameters via the -@code{gnus-parameters} variable, see below. - -Here's an example group parameter list: - -@example -((to-address . "ding@@gnus.org") - (auto-expire . t)) -@end example - -We see that each element consists of a ``dotted pair''---the thing before -the dot is the key, while the thing after the dot is the value. All the -parameters have this form @emph{except} local variable specs, which are -not dotted pairs, but proper lists. - -Some parameters have correspondent customizable variables, each of which -is an alist of regexps and values. - -The following group parameters can be used: - -@table @code -@item to-address -@cindex to-address -Address used by when doing followups and new posts. - -@example -(to-address . "some@@where.com") -@end example - -This is primarily useful in mail groups that represent closed mailing -lists---mailing lists where it's expected that everybody that writes to -the mailing list is subscribed to it. Since using this parameter -ensures that the mail only goes to the mailing list itself, it means -that members won't receive two copies of your followups. - -Using @code{to-address} will actually work whether the group is foreign -or not. Let's say there's a group on the server that is called -@samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten -the articles from a mail-to-news gateway. Posting directly to this -group is therefore impossible---you have to send mail to the mailing -list address instead. - -See also @code{gnus-parameter-to-address-alist}. - -@item to-list -@cindex to-list -Address used when doing @kbd{a} in that group. - -@example -(to-list . "some@@where.com") -@end example - -It is totally ignored -when doing a followup---except that if it is present in a news group, -you'll get mail group semantics when doing @kbd{f}. - -If you do an @kbd{a} command in a mail group and you have neither a -@code{to-list} group parameter nor a @code{to-address} group parameter, -then a @code{to-list} group parameter will be added automatically upon -sending the message if @code{gnus-add-to-list} is set to @code{t}. -@vindex gnus-add-to-list - -@findex gnus-mailing-list-mode -@cindex mail list groups -If this variable is set, @code{gnus-mailing-list-mode} is turned on when -entering summary buffer. - -See also @code{gnus-parameter-to-list-alist}. - -@anchor{subscribed} -@item subscribed -@cindex subscribed -@cindex Mail-Followup-To -@findex gnus-find-subscribed-addresses -If this parameter is set to @code{t}, Gnus will consider the -to-address and to-list parameters for this group as addresses of -mailing lists you are subscribed to. Giving Gnus this information is -(only) a first step in getting it to generate correct Mail-Followup-To -headers for your posts to these lists. The second step is to put the -following in your @file{.gnus.el} - -@lisp -(setq message-subscribed-address-functions - '(gnus-find-subscribed-addresses)) -@end lisp - -@xref{Mailing Lists, ,Mailing Lists, message, The Message Manual}, for -a complete treatment of available MFT support. - -@item visible -@cindex visible -If the group parameter list has the element @code{(visible . t)}, -that group will always be visible in the Group buffer, regardless -of whether it has any unread articles. - -This parameter cannot be set via @code{gnus-parameters}. See -@code{gnus-permanently-visible-groups} as an alternative. - -@item broken-reply-to -@cindex broken-reply-to -Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To} -headers in this group are to be ignored, and for the header to be hidden -if @code{reply-to} is part of @code{gnus-boring-article-headers}. This -can be useful if you're reading a mailing list group where the listserv -has inserted @code{Reply-To} headers that point back to the listserv -itself. That is broken behavior. So there! - -@item to-group -@cindex to-group -Elements like @code{(to-group . "some.group.name")} means that all -posts in that group will be sent to @code{some.group.name}. - -@item newsgroup -@cindex newsgroup -If you have @code{(newsgroup . t)} in the group parameter list, Gnus -will treat all responses as if they were responses to news articles. -This can be useful if you have a mail group that's really a mirror of a -news group. - -@item gcc-self -@cindex gcc-self -If @code{(gcc-self . t)} is present in the group parameter list, newly -composed messages will be @code{Gcc}'d to the current group. If -@code{(gcc-self . none)} is present, no @code{Gcc:} header will be -generated, if @code{(gcc-self . "string")} is present, this string will -be inserted literally as a @code{gcc} header. This parameter takes -precedence over any default @code{Gcc} rules as described later -(@pxref{Archived Messages}). - -@strong{Caveat}: Adding @code{(gcc-self . t)} to the parameter list of -@code{nntp} groups (or the like) isn't valid. An @code{nntp} server -doesn't accept articles. - -@item auto-expire -@cindex auto-expire -@cindex expiring mail -If the group parameter has an element that looks like @code{(auto-expire -. t)}, all articles read will be marked as expirable. For an -alternative approach, @pxref{Expiring Mail}. - -See also @code{gnus-auto-expirable-newsgroups}. - -@item total-expire -@cindex total-expire -@cindex expiring mail -If the group parameter has an element that looks like -@code{(total-expire . t)}, all read articles will be put through the -expiry process, even if they are not marked as expirable. Use with -caution. Unread, ticked and dormant articles are not eligible for -expiry. - -See also @code{gnus-total-expirable-newsgroups}. - -@item expiry-wait -@cindex expiry-wait -@vindex nnmail-expiry-wait-function -If the group parameter has an element that looks like -@code{(expiry-wait . 10)}, this value will override any -@code{nnmail-expiry-wait} and @code{nnmail-expiry-wait-function} -(@pxref{Expiring Mail}) when expiring expirable messages. The value -can either be a number of days (not necessarily an integer) or the -symbols @code{never} or @code{immediate}. - -@item expiry-target -@cindex expiry-target -Where expired messages end up. This parameter overrides -@code{nnmail-expiry-target}. - -@item score-file -@cindex score file group parameter -Elements that look like @code{(score-file . "file")} will make -@file{file} into the current score file for the group in question. All -interactive score entries will be put into this file. - -@item adapt-file -@cindex adapt file group parameter -Elements that look like @code{(adapt-file . "file")} will make -@file{file} into the current adaptive file for the group in question. -All adaptive score entries will be put into this file. - -@item admin-address -@cindex admin-address -When unsubscribing from a mailing list you should never send the -unsubscription notice to the mailing list itself. Instead, you'd send -messages to the administrative address. This parameter allows you to -put the admin address somewhere convenient. - -@item display -@cindex display -Elements that look like @code{(display . MODE)} say which articles to -display on entering the group. Valid values are: - -@table @code -@item all -Display all articles, both read and unread. - -@item an integer -Display the last @var{integer} articles in the group. This is the same as -entering the group with @kbd{C-u @var{integer}}. - -@item default -Display the default visible articles, which normally includes unread and -ticked articles. - -@item an array -Display articles that satisfy a predicate. - -Here are some examples: - -@table @code -@item [unread] -Display only unread articles. - -@item [not expire] -Display everything except expirable articles. - -@item [and (not reply) (not expire)] -Display everything except expirable and articles you've already -responded to. -@end table - -The available operators are @code{not}, @code{and} and @code{or}. -Predicates include @code{tick}, @code{unsend}, @code{undownload}, -@code{unread}, @code{dormant}, @code{expire}, @code{reply}, -@code{killed}, @code{bookmark}, @code{score}, @code{save}, -@code{cache}, @code{forward}, and @code{unseen}. - -@end table - -The @code{display} parameter works by limiting the summary buffer to -the subset specified. You can pop the limit by using the @kbd{/ w} -command (@pxref{Limiting}). - -@item comment -@cindex comment -Elements that look like @code{(comment . "This is a comment")} are -arbitrary comments on the group. You can display comments in the -group line (@pxref{Group Line Specification}). - -@item charset -@cindex charset -Elements that look like @code{(charset . iso-8859-1)} will make -@code{iso-8859-1} the default charset; that is, the charset that will be -used for all articles that do not specify a charset. - -See also @code{gnus-group-charset-alist}. - -@item ignored-charsets -@cindex ignored-charset -Elements that look like @code{(ignored-charsets x-unknown iso-8859-1)} -will make @code{iso-8859-1} and @code{x-unknown} ignored; that is, the -default charset will be used for decoding articles. - -See also @code{gnus-group-ignored-charsets-alist}. - -@item posting-style -@cindex posting-style -You can store additional posting style information for this group -here (@pxref{Posting Styles}). The format is that of an entry in the -@code{gnus-posting-styles} alist, except that there's no regexp matching -the group name (of course). Style elements in this group parameter will -take precedence over the ones found in @code{gnus-posting-styles}. - -For instance, if you want a funky name and signature in this group only, -instead of hacking @code{gnus-posting-styles}, you could put something -like this in the group parameters: - -@example -(posting-style - (name "Funky Name") - ("X-My-Header" "Funky Value") - (signature "Funky Signature")) -@end example - -If you're using topics to organize your group buffer -(@pxref{Group Topics}), note that posting styles can also be set in -the topics parameters. Posting styles in topic parameters apply to all -groups in this topic. More precisely, the posting-style settings for a -group result from the hierarchical merging of all posting-style -entries in the parameters of this group and all the topics it belongs -to. - - -@item post-method -@cindex post-method -If it is set, the value is used as the method for posting message -instead of @code{gnus-post-method}. - -@item mail-source -@cindex mail-source -If it is set, and the setting of @code{mail-sources} includes a -@code{group} mail source (@pxref{Mail Sources}), the value is a -mail source for this group. - -@item banner -@cindex banner -An item like @code{(banner . @var{regexp})} causes any part of an article -that matches the regular expression @var{regexp} to be stripped. Instead of -@var{regexp}, you can also use the symbol @code{signature} which strips the -last signature or any of the elements of the alist -@code{gnus-article-banner-alist}. - -@item sieve -@cindex sieve -This parameter contains a Sieve test that should match incoming mail -that should be placed in this group. From this group parameter, a -Sieve @samp{IF} control structure is generated, having the test as the -condition and @samp{fileinto "group.name";} as the body. - -For example, if the @samp{INBOX.list.sieve} group has the @code{(sieve -address "sender" "sieve-admin@@extundo.com")} group parameter, when -translating the group parameter into a Sieve script (@pxref{Sieve -Commands}) the following Sieve code is generated: - -@example -if address "sender" "sieve-admin@@extundo.com" @{ - fileinto "INBOX.list.sieve"; -@} -@end example - -To generate tests for multiple email-addresses use a group parameter -like @code{(sieve address "sender" ("name@@one.org" else@@two.org"))}. -When generating a sieve script (@pxref{Sieve Commands}) Sieve code -like the following is generated: - -@example -if address "sender" ["name@@one.org", "else@@two.org"] @{ - fileinto "INBOX.list.sieve"; -@} -@end example - -See @pxref{Sieve Commands} for commands and variables that might be of -interest in relation to the sieve parameter. - -The Sieve language is described in RFC 3028. @xref{Top, Emacs Sieve, -Top, sieve, Emacs Sieve}. - -@item (agent parameters) -If the agent has been enabled, you can set any of its parameters to -control the behavior of the agent in individual groups. See Agent -Parameters in @ref{Category Syntax}. Most users will choose to set -agent parameters in either an agent category or group topic to -minimize the configuration effort. - -@item (@var{variable} @var{form}) -You can use the group parameters to set variables local to the group you -are entering. If you want to turn threading off in @samp{news.answers}, -you could put @code{(gnus-show-threads nil)} in the group parameters of -that group. @code{gnus-show-threads} will be made into a local variable -in the summary buffer you enter, and the form @code{nil} will be -@code{eval}ed there. - -Note that this feature sets the variable locally to the summary buffer -if and only if @var{variable} has been bound as a variable. Otherwise, -only evaluating the form will take place. So, you may want to bind the -variable in advance using @code{defvar} or other if the result of the -form needs to be set to it. - -But some variables are evaluated in the article buffer, or in the -message buffer (of a reply or followup or otherwise newly created -message). As a workaround, it might help to add the variable in -question to @code{gnus-newsgroup-variables}. @xref{Various Summary -Stuff}. So if you want to set @code{message-from-style} via the group -parameters, then you may need the following statement elsewhere in your -@file{~/.gnus.el} file: - -@lisp -(add-to-list 'gnus-newsgroup-variables 'message-from-style) -@end lisp - -@vindex gnus-list-identifiers -A use for this feature is to remove a mailing list identifier tag in -the subject fields of articles. E.g. if the news group - -@example -nntp+news.gnus.org:gmane.text.docbook.apps -@end example - -has the tag @samp{DOC-BOOK-APPS:} in the subject of all articles, this -tag can be removed from the article subjects in the summary buffer for -the group by putting @code{(gnus-list-identifiers "DOCBOOK-APPS:")} -into the group parameters for the group. - -This can also be used as a group-specific hook function. If you want to -hear a beep when you enter a group, you could put something like -@code{(dummy-variable (ding))} in the parameters of that group. If -@code{dummy-variable} has been bound (see above), it will be set to the -(meaningless) result of the @code{(ding)} form. - -Alternatively, since the VARIABLE becomes local to the group, this -pattern can be used to temporarily change a hook. For example, if the -following is added to a group parameter - -@lisp -(gnus-summary-prepared-hook - '(lambda nil (local-set-key "d" (local-key-binding "n")))) -@end lisp - -when the group is entered, the 'd' key will not mark the article as -expired. - -@end table - -@vindex gnus-parameters -Group parameters can be set via the @code{gnus-parameters} variable too. -But some variables, such as @code{visible}, have no effect (For this -case see @code{gnus-permanently-visible-groups} as an alternative.). -For example: - -@lisp -(setq gnus-parameters - '(("mail\\..*" - (gnus-show-threads nil) - (gnus-use-scoring nil) - (gnus-summary-line-format - "%U%R%z%I%(%[%d:%ub%-23,23f%]%) %s\n") - (gcc-self . t) - (display . all)) - - ("^nnimap:\\(foo.bar\\)$" - (to-group . "\\1")) - - ("mail\\.me" - (gnus-use-scoring t)) - - ("list\\..*" - (total-expire . t) - (broken-reply-to . t)))) -@end lisp - -All clauses that matches the group name will be used, but the last -setting ``wins''. So if you have two clauses that both match the -group name, and both set, say @code{display}, the last setting will -override the first. - -Parameters that are strings will be subjected to regexp substitution, -as the @code{to-group} example shows. - -@vindex gnus-parameters-case-fold-search -By default, whether comparing the group name and one of those regexps -specified in @code{gnus-parameters} is done in a case-sensitive manner -or a case-insensitive manner depends on the value of -@code{case-fold-search} at the time when the comparison is done. The -value of @code{case-fold-search} is typically @code{t}; it means, for -example, the element @code{("INBOX\\.FOO" (total-expire . t))} might be -applied to both the @samp{INBOX.FOO} group and the @samp{INBOX.foo} -group. If you want to make those regexps always case-sensitive, set the -value of the @code{gnus-parameters-case-fold-search} variable to -@code{nil}. Otherwise, set it to @code{t} if you want to compare them -always in a case-insensitive manner. - -You can define different sorting to different groups via -@code{gnus-parameters}. Here is an example to sort an @acronym{NNTP} -group by reverse date to see the latest news at the top and an -@acronym{RSS} group by subject. In this example, the first group is the -Debian daily news group @code{gmane.linux.debian.user.news} from -news.gmane.org. The @acronym{RSS} group corresponds to the Debian -weekly news RSS feed -@url{http://packages.debian.org/unstable/newpkg_main.en.rdf}, -@xref{RSS}. - -@lisp -(setq - gnus-parameters - '(("nntp.*gmane\\.debian\\.user\\.news" - (gnus-show-threads nil) - (gnus-article-sort-functions '((not gnus-article-sort-by-date))) - (gnus-use-adaptive-scoring nil) - (gnus-use-scoring nil)) - ("nnrss.*debian" - (gnus-show-threads nil) - (gnus-article-sort-functions 'gnus-article-sort-by-subject) - (gnus-use-adaptive-scoring nil) - (gnus-use-scoring t) - (gnus-score-find-score-files-function 'gnus-score-find-single) - (gnus-summary-line-format "%U%R%z%d %I%(%[ %s %]%)\n")))) -@end lisp - - -@node Listing Groups -@section Listing Groups -@cindex group listing - -These commands all list various slices of the groups available. - -@table @kbd - -@item l -@itemx A s -@kindex A s (Group) -@kindex l (Group) -@findex gnus-group-list-groups -List all groups that have unread articles -(@code{gnus-group-list-groups}). If the numeric prefix is used, this -command will list only groups of level ARG and lower. By default, it -only lists groups of level five (i.e., -@code{gnus-group-default-list-level}) or lower (i.e., just subscribed -groups). - -@item L -@itemx A u -@kindex A u (Group) -@kindex L (Group) -@findex gnus-group-list-all-groups -List all groups, whether they have unread articles or not -(@code{gnus-group-list-all-groups}). If the numeric prefix is used, -this command will list only groups of level ARG and lower. By default, -it lists groups of level seven or lower (i.e., just subscribed and -unsubscribed groups). - -@item A l -@kindex A l (Group) -@findex gnus-group-list-level -List all unread groups on a specific level -(@code{gnus-group-list-level}). If given a prefix, also list the groups -with no unread articles. - -@item A k -@kindex A k (Group) -@findex gnus-group-list-killed -List all killed groups (@code{gnus-group-list-killed}). If given a -prefix argument, really list all groups that are available, but aren't -currently (un)subscribed. This could entail reading the active file -from the server. - -@item A z -@kindex A z (Group) -@findex gnus-group-list-zombies -List all zombie groups (@code{gnus-group-list-zombies}). - -@item A m -@kindex A m (Group) -@findex gnus-group-list-matching -List all unread, subscribed groups with names that match a regexp -(@code{gnus-group-list-matching}). - -@item A M -@kindex A M (Group) -@findex gnus-group-list-all-matching -List groups that match a regexp (@code{gnus-group-list-all-matching}). - -@item A A -@kindex A A (Group) -@findex gnus-group-list-active -List absolutely all groups in the active file(s) of the -server(s) you are connected to (@code{gnus-group-list-active}). This -might very well take quite a while. It might actually be a better idea -to do a @kbd{A M} to list all matching, and just give @samp{.} as the -thing to match on. Also note that this command may list groups that -don't exist (yet)---these will be listed as if they were killed groups. -Take the output with some grains of salt. - -@item A a -@kindex A a (Group) -@findex gnus-group-apropos -List all groups that have names that match a regexp -(@code{gnus-group-apropos}). - -@item A d -@kindex A d (Group) -@findex gnus-group-description-apropos -List all groups that have names or descriptions that match a regexp -(@code{gnus-group-description-apropos}). - -@item A c -@kindex A c (Group) -@findex gnus-group-list-cached -List all groups with cached articles (@code{gnus-group-list-cached}). - -@item A ? -@kindex A ? (Group) -@findex gnus-group-list-dormant -List all groups with dormant articles (@code{gnus-group-list-dormant}). - -@item A ! -@kindex A ! (Group) -@findex gnus-group-list-ticked -List all groups with ticked articles (@code{gnus-group-list-ticked}). - -@item A / -@kindex A / (Group) -@findex gnus-group-list-limit -Further limit groups within the current selection -(@code{gnus-group-list-limit}). If you've first limited to groups -with dormant articles with @kbd{A ?}, you can then further limit with -@kbd{A / c}, which will then limit to groups with cached articles, -giving you the groups that have both dormant articles and cached -articles. - -@item A f -@kindex A f (Group) -@findex gnus-group-list-flush -Flush groups from the current selection (@code{gnus-group-list-flush}). - -@item A p -@kindex A p (Group) -@findex gnus-group-list-plus -List groups plus the current selection (@code{gnus-group-list-plus}). - -@end table - -@vindex gnus-permanently-visible-groups -@cindex visible group parameter -Groups that match the @code{gnus-permanently-visible-groups} regexp will -always be shown, whether they have unread articles or not. You can also -add the @code{visible} element to the group parameters in question to -get the same effect. - -@vindex gnus-list-groups-with-ticked-articles -Groups that have just ticked articles in it are normally listed in the -group buffer. If @code{gnus-list-groups-with-ticked-articles} is -@code{nil}, these groups will be treated just like totally empty -groups. It is @code{t} by default. - - -@node Sorting Groups -@section Sorting Groups -@cindex sorting groups - -@kindex C-c C-s (Group) -@findex gnus-group-sort-groups -@vindex gnus-group-sort-function -The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the -group buffer according to the function(s) given by the -@code{gnus-group-sort-function} variable. Available sorting functions -include: - -@table @code - -@item gnus-group-sort-by-alphabet -@findex gnus-group-sort-by-alphabet -Sort the group names alphabetically. This is the default. - -@item gnus-group-sort-by-real-name -@findex gnus-group-sort-by-real-name -Sort the group alphabetically on the real (unprefixed) group names. - -@item gnus-group-sort-by-level -@findex gnus-group-sort-by-level -Sort by group level. - -@item gnus-group-sort-by-score -@findex gnus-group-sort-by-score -Sort by group score. @xref{Group Score}. - -@item gnus-group-sort-by-rank -@findex gnus-group-sort-by-rank -Sort by group score and then the group level. The level and the score -are, when taken together, the group's @dfn{rank}. @xref{Group Score}. - -@item gnus-group-sort-by-unread -@findex gnus-group-sort-by-unread -Sort by number of unread articles. - -@item gnus-group-sort-by-method -@findex gnus-group-sort-by-method -Sort alphabetically on the select method. - -@item gnus-group-sort-by-server -@findex gnus-group-sort-by-server -Sort alphabetically on the Gnus server name. - - -@end table - -@code{gnus-group-sort-function} can also be a list of sorting -functions. In that case, the most significant sort key function must be -the last one. - - -There are also a number of commands for sorting directly according to -some sorting criteria: - -@table @kbd -@item G S a -@kindex G S a (Group) -@findex gnus-group-sort-groups-by-alphabet -Sort the group buffer alphabetically by group name -(@code{gnus-group-sort-groups-by-alphabet}). - -@item G S u -@kindex G S u (Group) -@findex gnus-group-sort-groups-by-unread -Sort the group buffer by the number of unread articles -(@code{gnus-group-sort-groups-by-unread}). - -@item G S l -@kindex G S l (Group) -@findex gnus-group-sort-groups-by-level -Sort the group buffer by group level -(@code{gnus-group-sort-groups-by-level}). - -@item G S v -@kindex G S v (Group) -@findex gnus-group-sort-groups-by-score -Sort the group buffer by group score -(@code{gnus-group-sort-groups-by-score}). @xref{Group Score}. - -@item G S r -@kindex G S r (Group) -@findex gnus-group-sort-groups-by-rank -Sort the group buffer by group rank -(@code{gnus-group-sort-groups-by-rank}). @xref{Group Score}. - -@item G S m -@kindex G S m (Group) -@findex gnus-group-sort-groups-by-method -Sort the group buffer alphabetically by back end name@* -(@code{gnus-group-sort-groups-by-method}). - -@item G S n -@kindex G S n (Group) -@findex gnus-group-sort-groups-by-real-name -Sort the group buffer alphabetically by real (unprefixed) group name -(@code{gnus-group-sort-groups-by-real-name}). - -@end table - -All the commands below obey the process/prefix convention -(@pxref{Process/Prefix}). - -When given a symbolic prefix (@pxref{Symbolic Prefixes}), all these -commands will sort in reverse order. - -You can also sort a subset of the groups: - -@table @kbd -@item G P a -@kindex G P a (Group) -@findex gnus-group-sort-selected-groups-by-alphabet -Sort the groups alphabetically by group name -(@code{gnus-group-sort-selected-groups-by-alphabet}). - -@item G P u -@kindex G P u (Group) -@findex gnus-group-sort-selected-groups-by-unread -Sort the groups by the number of unread articles -(@code{gnus-group-sort-selected-groups-by-unread}). - -@item G P l -@kindex G P l (Group) -@findex gnus-group-sort-selected-groups-by-level -Sort the groups by group level -(@code{gnus-group-sort-selected-groups-by-level}). - -@item G P v -@kindex G P v (Group) -@findex gnus-group-sort-selected-groups-by-score -Sort the groups by group score -(@code{gnus-group-sort-selected-groups-by-score}). @xref{Group Score}. - -@item G P r -@kindex G P r (Group) -@findex gnus-group-sort-selected-groups-by-rank -Sort the groups by group rank -(@code{gnus-group-sort-selected-groups-by-rank}). @xref{Group Score}. - -@item G P m -@kindex G P m (Group) -@findex gnus-group-sort-selected-groups-by-method -Sort the groups alphabetically by back end name@* -(@code{gnus-group-sort-selected-groups-by-method}). - -@item G P n -@kindex G P n (Group) -@findex gnus-group-sort-selected-groups-by-real-name -Sort the groups alphabetically by real (unprefixed) group name -(@code{gnus-group-sort-selected-groups-by-real-name}). - -@item G P s -@kindex G P s (Group) -@findex gnus-group-sort-selected-groups -Sort the groups according to @code{gnus-group-sort-function}. - -@end table - -And finally, note that you can use @kbd{C-k} and @kbd{C-y} to manually -move groups around. - - -@node Group Maintenance -@section Group Maintenance -@cindex bogus groups - -@table @kbd -@item b -@kindex b (Group) -@findex gnus-group-check-bogus-groups -Find bogus groups and delete them -(@code{gnus-group-check-bogus-groups}). - -@item F -@kindex F (Group) -@findex gnus-group-find-new-groups -Find new groups and process them (@code{gnus-group-find-new-groups}). -With 1 @kbd{C-u}, use the @code{ask-server} method to query the server -for new groups. With 2 @kbd{C-u}'s, use most complete method possible -to query the server for new groups, and subscribe the new groups as -zombies. - -@item C-c C-x -@kindex C-c C-x (Group) -@findex gnus-group-expire-articles -@cindex expiring mail -Run all expirable articles in the current group through the expiry -process (if any) (@code{gnus-group-expire-articles}). That is, delete -all expirable articles in the group that have been around for a while. -(@pxref{Expiring Mail}). - -@item C-c C-M-x -@kindex C-c C-M-x (Group) -@findex gnus-group-expire-all-groups -@cindex expiring mail -Run all expirable articles in all groups through the expiry process -(@code{gnus-group-expire-all-groups}). - -@end table - - -@node Browse Foreign Server -@section Browse Foreign Server -@cindex foreign servers -@cindex browsing servers - -@table @kbd -@item B -@kindex B (Group) -@findex gnus-group-browse-foreign-server -You will be queried for a select method and a server name. Gnus will -then attempt to contact this server and let you browse the groups there -(@code{gnus-group-browse-foreign-server}). -@end table - -@findex gnus-browse-mode -A new buffer with a list of available groups will appear. This buffer -will use the @code{gnus-browse-mode}. This buffer looks a bit (well, -a lot) like a normal group buffer. - -Here's a list of keystrokes available in the browse mode: - -@table @kbd -@item n -@kindex n (Browse) -@findex gnus-group-next-group -Go to the next group (@code{gnus-group-next-group}). - -@item p -@kindex p (Browse) -@findex gnus-group-prev-group -Go to the previous group (@code{gnus-group-prev-group}). - -@item SPACE -@kindex SPACE (Browse) -@findex gnus-browse-read-group -Enter the current group and display the first article -(@code{gnus-browse-read-group}). - -@item RET -@kindex RET (Browse) -@findex gnus-browse-select-group -Enter the current group (@code{gnus-browse-select-group}). - -@item u -@kindex u (Browse) -@findex gnus-browse-unsubscribe-current-group -@vindex gnus-browse-subscribe-newsgroup-method -Unsubscribe to the current group, or, as will be the case here, -subscribe to it (@code{gnus-browse-unsubscribe-current-group}). You -can affect the way the new group is entered into the Group buffer -using the variable @code{gnus-browse-subscribe-newsgroup-method}. See -@pxref{Subscription Methods} for available options. - -@item l -@itemx q -@kindex q (Browse) -@kindex l (Browse) -@findex gnus-browse-exit -Exit browse mode (@code{gnus-browse-exit}). - -@item d -@kindex d (Browse) -@findex gnus-browse-describe-group -Describe the current group (@code{gnus-browse-describe-group}). - -@item ? -@kindex ? (Browse) -@findex gnus-browse-describe-briefly -Describe browse mode briefly (well, there's not much to describe, is -there) (@code{gnus-browse-describe-briefly}). -@end table - - -@node Exiting Gnus -@section Exiting Gnus -@cindex exiting Gnus - -Yes, Gnus is ex(c)iting. - -@table @kbd -@item z -@kindex z (Group) -@findex gnus-group-suspend -Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus, -but it kills all buffers except the Group buffer. I'm not sure why this -is a gain, but then who am I to judge? - -@item q -@kindex q (Group) -@findex gnus-group-exit -@c @icon{gnus-group-exit} -Quit Gnus (@code{gnus-group-exit}). - -@item Q -@kindex Q (Group) -@findex gnus-group-quit -Quit Gnus without saving the @file{.newsrc} files (@code{gnus-group-quit}). -The dribble file will be saved, though (@pxref{Auto Save}). -@end table - -@vindex gnus-exit-gnus-hook -@vindex gnus-suspend-gnus-hook -@vindex gnus-after-exiting-gnus-hook -@code{gnus-suspend-gnus-hook} is called when you suspend Gnus and -@code{gnus-exit-gnus-hook} is called when you quit Gnus, while -@code{gnus-after-exiting-gnus-hook} is called as the final item when -exiting Gnus. - -Note: - -@quotation -Miss Lisa Cannifax, while sitting in English class, felt her feet go -numbly heavy and herself fall into a hazy trance as the boy sitting -behind her drew repeated lines with his pencil across the back of her -plastic chair. -@end quotation - - -@node Group Topics -@section Group Topics -@cindex topics - -If you read lots and lots of groups, it might be convenient to group -them hierarchically according to topics. You put your Emacs groups over -here, your sex groups over there, and the rest (what, two groups or so?) -you put in some misc section that you never bother with anyway. You can -even group the Emacs sex groups as a sub-topic to either the Emacs -groups or the sex groups---or both! Go wild! - -@iftex -@iflatex -\gnusfigure{Group Topics}{400}{ -\put(75,50){\epsfig{figure=ps/group-topic,height=9cm}} -} -@end iflatex -@end iftex - -Here's an example: - -@example -Gnus - Emacs -- I wuw it! - 3: comp.emacs - 2: alt.religion.emacs - Naughty Emacs - 452: alt.sex.emacs - 0: comp.talk.emacs.recovery - Misc - 8: comp.binaries.fractals - 13: comp.sources.unix -@end example - -@findex gnus-topic-mode -@kindex t (Group) -To get this @emph{fab} functionality you simply turn on (ooh!) the -@code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This -is a toggling command.) - -Go ahead, just try it. I'll still be here when you get back. La de -dum@dots{} Nice tune, that@dots{} la la la@dots{} What, you're back? -Yes, and now press @kbd{l}. There. All your groups are now listed -under @samp{misc}. Doesn't that make you feel all warm and fuzzy? -Hot and bothered? - -If you want this permanently enabled, you should add that minor mode to -the hook for the group mode. Put the following line in your -@file{~/.gnus.el} file: - -@lisp -(add-hook 'gnus-group-mode-hook 'gnus-topic-mode) -@end lisp - -@menu -* Topic Commands:: Interactive E-Z commands. -* Topic Variables:: How to customize the topics the Lisp Way. -* Topic Sorting:: Sorting each topic individually. -* Topic Topology:: A map of the world. -* Topic Parameters:: Parameters that apply to all groups in a topic. -@end menu - - -@node Topic Commands -@subsection Topic Commands -@cindex topic commands - -When the topic minor mode is turned on, a new @kbd{T} submap will be -available. In addition, a few of the standard keys change their -definitions slightly. - -In general, the following kinds of operations are possible on topics. -First of all, you want to create topics. Secondly, you want to put -groups in topics and to move them around until you have an order you -like. The third kind of operation is to show/hide parts of the whole -shebang. You might want to hide a topic including its subtopics and -groups, to get a better overview of the other groups. - -Here is a list of the basic keys that you might need to set up topics -the way you like. - -@table @kbd - -@item T n -@kindex T n (Topic) -@findex gnus-topic-create-topic -Prompt for a new topic name and create it -(@code{gnus-topic-create-topic}). - -@item T TAB -@itemx TAB -@kindex T TAB (Topic) -@kindex TAB (Topic) -@findex gnus-topic-indent -``Indent'' the current topic so that it becomes a sub-topic of the -previous topic (@code{gnus-topic-indent}). If given a prefix, -``un-indent'' the topic instead. - -@item M-TAB -@kindex M-TAB (Topic) -@findex gnus-topic-unindent -``Un-indent'' the current topic so that it becomes a sub-topic of the -parent of its current parent (@code{gnus-topic-unindent}). - -@end table - -The following two keys can be used to move groups and topics around. -They work like the well-known cut and paste. @kbd{C-k} is like cut and -@kbd{C-y} is like paste. Of course, this being Emacs, we use the terms -kill and yank rather than cut and paste. - -@table @kbd - -@item C-k -@kindex C-k (Topic) -@findex gnus-topic-kill-group -Kill a group or topic (@code{gnus-topic-kill-group}). All groups in the -topic will be removed along with the topic. - -@item C-y -@kindex C-y (Topic) -@findex gnus-topic-yank-group -Yank the previously killed group or topic -(@code{gnus-topic-yank-group}). Note that all topics will be yanked -before all groups. - -So, to move a topic to the beginning of the list of topics, just hit -@kbd{C-k} on it. This is like the ``cut'' part of cut and paste. Then, -move the cursor to the beginning of the buffer (just below the ``Gnus'' -topic) and hit @kbd{C-y}. This is like the ``paste'' part of cut and -paste. Like I said -- E-Z. - -You can use @kbd{C-k} and @kbd{C-y} on groups as well as on topics. So -you can move topics around as well as groups. - -@end table - -After setting up the topics the way you like them, you might wish to -hide a topic, or to show it again. That's why we have the following -key. - -@table @kbd - -@item RET -@kindex RET (Topic) -@findex gnus-topic-select-group -@itemx SPACE -Either select a group or fold a topic (@code{gnus-topic-select-group}). -When you perform this command on a group, you'll enter the group, as -usual. When done on a topic line, the topic will be folded (if it was -visible) or unfolded (if it was folded already). So it's basically a -toggling command on topics. In addition, if you give a numerical -prefix, group on that level (and lower) will be displayed. - -@end table - -Now for a list of other commands, in no particular order. - -@table @kbd - -@item T m -@kindex T m (Topic) -@findex gnus-topic-move-group -Move the current group to some other topic -(@code{gnus-topic-move-group}). This command uses the process/prefix -convention (@pxref{Process/Prefix}). - -@item T j -@kindex T j (Topic) -@findex gnus-topic-jump-to-topic -Go to a topic (@code{gnus-topic-jump-to-topic}). - -@item T c -@kindex T c (Topic) -@findex gnus-topic-copy-group -Copy the current group to some other topic -(@code{gnus-topic-copy-group}). This command uses the process/prefix -convention (@pxref{Process/Prefix}). - -@item T h -@kindex T h (Topic) -@findex gnus-topic-hide-topic -Hide the current topic (@code{gnus-topic-hide-topic}). If given -a prefix, hide the topic permanently. - -@item T s -@kindex T s (Topic) -@findex gnus-topic-show-topic -Show the current topic (@code{gnus-topic-show-topic}). If given -a prefix, show the topic permanently. - -@item T D -@kindex T D (Topic) -@findex gnus-topic-remove-group -Remove a group from the current topic (@code{gnus-topic-remove-group}). -This command is mainly useful if you have the same group in several -topics and wish to remove it from one of the topics. You may also -remove a group from all topics, but in that case, Gnus will add it to -the root topic the next time you start Gnus. In fact, all new groups -(which, naturally, don't belong to any topic) will show up in the root -topic. - -This command uses the process/prefix convention -(@pxref{Process/Prefix}). - -@item T M -@kindex T M (Topic) -@findex gnus-topic-move-matching -Move all groups that match some regular expression to a topic -(@code{gnus-topic-move-matching}). - -@item T C -@kindex T C (Topic) -@findex gnus-topic-copy-matching -Copy all groups that match some regular expression to a topic -(@code{gnus-topic-copy-matching}). - -@item T H -@kindex T H (Topic) -@findex gnus-topic-toggle-display-empty-topics -Toggle hiding empty topics -(@code{gnus-topic-toggle-display-empty-topics}). - -@item T # -@kindex T # (Topic) -@findex gnus-topic-mark-topic -Mark all groups in the current topic with the process mark -(@code{gnus-topic-mark-topic}). This command works recursively on -sub-topics unless given a prefix. - -@item T M-# -@kindex T M-# (Topic) -@findex gnus-topic-unmark-topic -Remove the process mark from all groups in the current topic -(@code{gnus-topic-unmark-topic}). This command works recursively on -sub-topics unless given a prefix. - -@item C-c C-x -@kindex C-c C-x (Topic) -@findex gnus-topic-expire-articles -@cindex expiring mail -Run all expirable articles in the current group or topic through the -expiry process (if any) -(@code{gnus-topic-expire-articles}). (@pxref{Expiring Mail}). - -@item T r -@kindex T r (Topic) -@findex gnus-topic-rename -Rename a topic (@code{gnus-topic-rename}). - -@item T DEL -@kindex T DEL (Topic) -@findex gnus-topic-delete -Delete an empty topic (@code{gnus-topic-delete}). - -@item A T -@kindex A T (Topic) -@findex gnus-topic-list-active -List all groups that Gnus knows about in a topics-ified way -(@code{gnus-topic-list-active}). - -@item T M-n -@kindex T M-n (Topic) -@findex gnus-topic-goto-next-topic -Go to the next topic (@code{gnus-topic-goto-next-topic}). - -@item T M-p -@kindex T M-p (Topic) -@findex gnus-topic-goto-previous-topic -Go to the previous topic (@code{gnus-topic-goto-previous-topic}). - -@item G p -@kindex G p (Topic) -@findex gnus-topic-edit-parameters -@cindex group parameters -@cindex topic parameters -@cindex parameters -Edit the topic parameters (@code{gnus-topic-edit-parameters}). -@xref{Topic Parameters}. - -@end table - - -@node Topic Variables -@subsection Topic Variables -@cindex topic variables - -The previous section told you how to tell Gnus which topics to display. -This section explains how to tell Gnus what to display about each topic. - -@vindex gnus-topic-line-format -The topic lines themselves are created according to the -@code{gnus-topic-line-format} variable (@pxref{Formatting Variables}). -Valid elements are: - -@table @samp -@item i -Indentation. -@item n -Topic name. -@item v -Visibility. -@item l -Level. -@item g -Number of groups in the topic. -@item a -Number of unread articles in the topic. -@item A -Number of unread articles in the topic and all its subtopics. -@end table - -@vindex gnus-topic-indent-level -Each sub-topic (and the groups in the sub-topics) will be indented with -@code{gnus-topic-indent-level} times the topic level number of spaces. -The default is 2. - -@vindex gnus-topic-mode-hook -@code{gnus-topic-mode-hook} is called in topic minor mode buffers. - -@vindex gnus-topic-display-empty-topics -The @code{gnus-topic-display-empty-topics} says whether to display even -topics that have no unread articles in them. The default is @code{t}. - - -@node Topic Sorting -@subsection Topic Sorting -@cindex topic sorting - -You can sort the groups in each topic individually with the following -commands: - - -@table @kbd -@item T S a -@kindex T S a (Topic) -@findex gnus-topic-sort-groups-by-alphabet -Sort the current topic alphabetically by group name -(@code{gnus-topic-sort-groups-by-alphabet}). - -@item T S u -@kindex T S u (Topic) -@findex gnus-topic-sort-groups-by-unread -Sort the current topic by the number of unread articles -(@code{gnus-topic-sort-groups-by-unread}). - -@item T S l -@kindex T S l (Topic) -@findex gnus-topic-sort-groups-by-level -Sort the current topic by group level -(@code{gnus-topic-sort-groups-by-level}). - -@item T S v -@kindex T S v (Topic) -@findex gnus-topic-sort-groups-by-score -Sort the current topic by group score -(@code{gnus-topic-sort-groups-by-score}). @xref{Group Score}. - -@item T S r -@kindex T S r (Topic) -@findex gnus-topic-sort-groups-by-rank -Sort the current topic by group rank -(@code{gnus-topic-sort-groups-by-rank}). @xref{Group Score}. - -@item T S m -@kindex T S m (Topic) -@findex gnus-topic-sort-groups-by-method -Sort the current topic alphabetically by back end name -(@code{gnus-topic-sort-groups-by-method}). - -@item T S e -@kindex T S e (Topic) -@findex gnus-topic-sort-groups-by-server -Sort the current topic alphabetically by server name -(@code{gnus-topic-sort-groups-by-server}). - -@item T S s -@kindex T S s (Topic) -@findex gnus-topic-sort-groups -Sort the current topic according to the function(s) given by the -@code{gnus-group-sort-function} variable -(@code{gnus-topic-sort-groups}). - -@end table - -When given a prefix argument, all these commands will sort in reverse -order. @xref{Sorting Groups}, for more information about group -sorting. - - -@node Topic Topology -@subsection Topic Topology -@cindex topic topology -@cindex topology - -So, let's have a look at an example group buffer: - -@example -@group -Gnus - Emacs -- I wuw it! - 3: comp.emacs - 2: alt.religion.emacs - Naughty Emacs - 452: alt.sex.emacs - 0: comp.talk.emacs.recovery - Misc - 8: comp.binaries.fractals - 13: comp.sources.unix -@end group -@end example - -So, here we have one top-level topic (@samp{Gnus}), two topics under -that, and one sub-topic under one of the sub-topics. (There is always -just one (1) top-level topic). This topology can be expressed as -follows: - -@lisp -(("Gnus" visible) - (("Emacs -- I wuw it!" visible) - (("Naughty Emacs" visible))) - (("Misc" visible))) -@end lisp - -@vindex gnus-topic-topology -This is in fact how the variable @code{gnus-topic-topology} would look -for the display above. That variable is saved in the @file{.newsrc.eld} -file, and shouldn't be messed with manually---unless you really want -to. Since this variable is read from the @file{.newsrc.eld} file, -setting it in any other startup files will have no effect. - -This topology shows what topics are sub-topics of what topics (right), -and which topics are visible. Two settings are currently -allowed---@code{visible} and @code{invisible}. - - -@node Topic Parameters -@subsection Topic Parameters -@cindex topic parameters - -All groups in a topic will inherit group parameters from the parent -(and ancestor) topic parameters. All valid group parameters are valid -topic parameters (@pxref{Group Parameters}). When the agent is -enabled, all agent parameters (See Agent Parameters in @ref{Category -Syntax}) are also valid topic parameters. - -In addition, the following parameters are only valid as topic -parameters: - -@table @code -@item subscribe -When subscribing new groups by topic (@pxref{Subscription Methods}), the -@code{subscribe} topic parameter says what groups go in what topic. Its -value should be a regexp to match the groups that should go in that -topic. - -@item subscribe-level -When subscribing new groups by topic (see the @code{subscribe} parameter), -the group will be subscribed with the level specified in the -@code{subscribe-level} instead of @code{gnus-level-default-subscribed}. - -@end table - -Group parameters (of course) override topic parameters, and topic -parameters in sub-topics override topic parameters in super-topics. You -know. Normal inheritance rules. (@dfn{Rules} is here a noun, not a -verb, although you may feel free to disagree with me here.) - -@example -@group -Gnus - Emacs - 3: comp.emacs - 2: alt.religion.emacs - 452: alt.sex.emacs - Relief - 452: alt.sex.emacs - 0: comp.talk.emacs.recovery - Misc - 8: comp.binaries.fractals - 13: comp.sources.unix - 452: alt.sex.emacs -@end group -@end example - -The @samp{Emacs} topic has the topic parameter @code{(score-file -. "emacs.SCORE")}; the @samp{Relief} topic has the topic parameter -@code{(score-file . "relief.SCORE")}; and the @samp{Misc} topic has the -topic parameter @code{(score-file . "emacs.SCORE")}. In addition, -@* @samp{alt.religion.emacs} has the group parameter @code{(score-file -. "religion.SCORE")}. - -Now, when you enter @samp{alt.sex.emacs} in the @samp{Relief} topic, you -will get the @file{relief.SCORE} home score file. If you enter the same -group in the @samp{Emacs} topic, you'll get the @file{emacs.SCORE} home -score file. If you enter the group @samp{alt.religion.emacs}, you'll -get the @file{religion.SCORE} home score file. - -This seems rather simple and self-evident, doesn't it? Well, yes. But -there are some problems, especially with the @code{total-expiry} -parameter. Say you have a mail group in two topics; one with -@code{total-expiry} and one without. What happens when you do @kbd{M-x -gnus-expire-all-expirable-groups}? Gnus has no way of telling which one -of these topics you mean to expire articles from, so anything may -happen. In fact, I hereby declare that it is @dfn{undefined} what -happens. You just have to be careful if you do stuff like that. - - -@node Non-ASCII Group Names -@section Accessing groups of non-English names -@cindex non-ascii group names - -There are some news servers that provide groups of which the names are -expressed with their native languages in the world. For instance, in a -certain news server there are some newsgroups of which the names are -spelled in Chinese, where people are talking in Chinese. You can, of -course, subscribe to such news groups using Gnus. Currently Gnus -supports non-@acronym{ASCII} group names not only with the @code{nntp} -back end but also with the @code{nnml} back end and the @code{nnrss} -back end. - -Every such group name is encoded by a certain charset in the server -side (in an @acronym{NNTP} server its administrator determines the -charset, but for groups in the other back ends it is determined by you). -Gnus has to display the decoded ones for you in the group buffer and the -article buffer, and needs to use the encoded ones when communicating -with servers. However, Gnus doesn't know what charset is used for each -non-@acronym{ASCII} group name. The following two variables are just -the ones for telling Gnus what charset should be used for each group: - -@table @code -@item gnus-group-name-charset-method-alist -@vindex gnus-group-name-charset-method-alist -An alist of select methods and charsets. The default value is -@code{nil}. The names of groups in the server specified by that select -method are all supposed to use the corresponding charset. For example: - -@lisp -(setq gnus-group-name-charset-method-alist - '(((nntp "news.com.cn") . cn-gb-2312))) -@end lisp - -Charsets specified for groups with this variable are preferred to the -ones specified for the same groups with the -@code{gnus-group-name-charset-group-alist} variable (see below). - -A select method can be very long, like: - -@lisp -(nntp "gmane" - (nntp-address "news.gmane.org") - (nntp-end-of-line "\n") - (nntp-open-connection-function - nntp-open-via-rlogin-and-telnet) - (nntp-via-rlogin-command "ssh") - (nntp-via-rlogin-command-switches - ("-C" "-t" "-e" "none")) - (nntp-via-address @dots{})) -@end lisp - -In that case, you can truncate it into @code{(nntp "gmane")} in this -variable. That is, it is enough to contain only the back end name and -the server name. - -@item gnus-group-name-charset-group-alist -@cindex UTF-8 group names -@vindex gnus-group-name-charset-group-alist -An alist of regexp of group name and the charset for group names. -@code{((".*" . utf-8))} is the default value if UTF-8 is supported, -otherwise the default is @code{nil}. For example: - -@lisp -(setq gnus-group-name-charset-group-alist - '(("\\.com\\.cn:" . cn-gb-2312) - (".*" . utf-8))) -@end lisp - -Note that this variable is ignored if the match is made with -@code{gnus-group-name-charset-method-alist}. -@end table - -Those two variables are used also to determine the charset for encoding -and decoding non-@acronym{ASCII} group names that are in the back ends -other than @code{nntp}. It means that it is you who determine it. If -you do nothing, the charset used for group names in those back ends will -all be @code{utf-8} because of the last element of -@code{gnus-group-name-charset-group-alist}. - -There is one more important variable for non-@acronym{ASCII} group -names: - -@table @code -@item nnmail-pathname-coding-system -@vindex nnmail-pathname-coding-system -The value of this variable should be a coding system or @code{nil}. The -default is @code{nil} in Emacs, or is the aliasee of the coding system -named @code{file-name} (a certain coding system of which an alias is -@code{file-name}) in XEmacs. - -The @code{nnml} back end, the @code{nnrss} back end, the @acronym{NNTP} -marks feature (@pxref{NNTP marks}), the agent, and the cache use -non-@acronym{ASCII} group names in those files and directories. This -variable overrides the value of @code{file-name-coding-system} which -specifies the coding system used when encoding and decoding those file -names and directory names. - -In XEmacs (with the @code{mule} feature), @code{file-name-coding-system} -is the only means to specify the coding system used to encode and decode -file names. On the other hand, Emacs uses the value of -@code{default-file-name-coding-system} if @code{file-name-coding-system} -is @code{nil} or it is bound to the value of -@code{nnmail-pathname-coding-system} which is @code{nil}. - -Normally the value of @code{default-file-name-coding-system} in Emacs or -@code{nnmail-pathname-coding-system} in XEmacs is initialized according -to the locale, so you will need to do nothing if the value is suitable -to encode and decode non-@acronym{ASCII} group names. - -The value of this variable (or @code{default-file-name-coding-system}) -does not necessarily need to be the same value that is determined by -@code{gnus-group-name-charset-method-alist} and -@code{gnus-group-name-charset-group-alist}. - -If @code{default-file-name-coding-system} or this variable is -initialized by default to @code{iso-latin-1} for example, although you -want to subscribe to the groups spelled in Chinese, that is the most -typical case where you have to customize -@code{nnmail-pathname-coding-system}. The @code{utf-8} coding system is -a good candidate for it. Otherwise, you may change the locale in your -system so that @code{default-file-name-coding-system} or this variable -may be initialized to an appropriate value. -@end table - -Note that when you copy or move articles from a non-@acronym{ASCII} -group to another group, the charset used to encode and decode group -names should be the same in both groups. Otherwise the Newsgroups -header will be displayed incorrectly in the article buffer. - - -@node Misc Group Stuff -@section Misc Group Stuff - -@menu -* Scanning New Messages:: Asking Gnus to see whether new messages have arrived. -* Group Information:: Information and help on groups and Gnus. -* Group Timestamp:: Making Gnus keep track of when you last read a group. -* File Commands:: Reading and writing the Gnus files. -* Sieve Commands:: Managing Sieve scripts. -@end menu - -@table @kbd - -@item v -@kindex v (Group) -@cindex keys, reserved for users (Group) -The key @kbd{v} is reserved for users. You can bind it to some -command or better use it as a prefix key. For example: - -@lisp -(define-key gnus-group-mode-map (kbd "v j d") - (lambda () - (interactive) - (gnus-group-jump-to-group "nndraft:drafts"))) -@end lisp - -On keys reserved for users in Emacs and on keybindings in general -@xref{Keymaps, Keymaps, , emacs, The Emacs Editor}. - -@item ^ -@kindex ^ (Group) -@findex gnus-group-enter-server-mode -Enter the server buffer (@code{gnus-group-enter-server-mode}). -@xref{Server Buffer}. - -@item a -@kindex a (Group) -@findex gnus-group-post-news -Start composing a message (a news by default) -(@code{gnus-group-post-news}). If given a prefix, post to the group -under the point. If the prefix is 1, prompt for a group to post to. -Contrary to what the name of this function suggests, the prepared -article might be a mail instead of a news, if a mail group is specified -with the prefix argument. @xref{Composing Messages}. - -@item m -@kindex m (Group) -@findex gnus-group-mail -Mail a message somewhere (@code{gnus-group-mail}). If given a prefix, -use the posting style of the group under the point. If the prefix is 1, -prompt for a group name to find the posting style. -@xref{Composing Messages}. - -@item i -@kindex i (Group) -@findex gnus-group-news -Start composing a news (@code{gnus-group-news}). If given a prefix, -post to the group under the point. If the prefix is 1, prompt -for group to post to. @xref{Composing Messages}. - -This function actually prepares a news even when using mail groups. -This is useful for ``posting'' messages to mail groups without actually -sending them over the network: they're just saved directly to the group -in question. The corresponding back end must have a request-post method -for this to work though. - -@item G z -@kindex G z (Group) -@findex gnus-group-compact-group - -Compact the group under point (@code{gnus-group-compact-group}). -Currently implemented only in nnml (@pxref{Mail Spool}). This removes -gaps between article numbers, hence getting a correct total article -count. - -@end table - -Variables for the group buffer: - -@table @code - -@item gnus-group-mode-hook -@vindex gnus-group-mode-hook -is called after the group buffer has been -created. - -@item gnus-group-prepare-hook -@vindex gnus-group-prepare-hook -is called after the group buffer is -generated. It may be used to modify the buffer in some strange, -unnatural way. - -@item gnus-group-prepared-hook -@vindex gnus-group-prepare-hook -is called as the very last thing after the group buffer has been -generated. It may be used to move point around, for instance. - -@item gnus-permanently-visible-groups -@vindex gnus-permanently-visible-groups -Groups matching this regexp will always be listed in the group buffer, -whether they are empty or not. - -@end table - -@node Scanning New Messages -@subsection Scanning New Messages -@cindex new messages -@cindex scanning new news - -@table @kbd - -@item g -@kindex g (Group) -@findex gnus-group-get-new-news -@c @icon{gnus-group-get-new-news} -Check the server(s) for new articles. If the numerical prefix is used, -this command will check only groups of level @var{arg} and lower -(@code{gnus-group-get-new-news}). If given a non-numerical prefix, this -command will force a total re-reading of the active file(s) from the -back end(s). - -@item M-g -@kindex M-g (Group) -@findex gnus-group-get-new-news-this-group -@vindex gnus-goto-next-group-when-activating -@c @icon{gnus-group-get-new-news-this-group} -Check whether new articles have arrived in the current group -(@code{gnus-group-get-new-news-this-group}). -@code{gnus-goto-next-group-when-activating} says whether this command is -to move point to the next group or not. It is @code{t} by default. - -@findex gnus-activate-all-groups -@cindex activating groups -@item C-c M-g -@kindex C-c M-g (Group) -Activate absolutely all groups (@code{gnus-activate-all-groups}). - -@item R -@kindex R (Group) -@cindex restarting -@findex gnus-group-restart -Restart Gnus (@code{gnus-group-restart}). This saves the @file{.newsrc} -file(s), closes the connection to all servers, clears up all run-time -Gnus variables, and then starts Gnus all over again. - -@end table - -@vindex gnus-get-new-news-hook -@code{gnus-get-new-news-hook} is run just before checking for new news. - -@vindex gnus-after-getting-new-news-hook -@code{gnus-after-getting-new-news-hook} is run after checking for new -news. - - -@node Group Information -@subsection Group Information -@cindex group information -@cindex information on groups - -@table @kbd - - -@item H d -@itemx C-c C-d -@c @icon{gnus-group-describe-group} -@kindex H d (Group) -@kindex C-c C-d (Group) -@cindex describing groups -@cindex group description -@findex gnus-group-describe-group -Describe the current group (@code{gnus-group-describe-group}). If given -a prefix, force Gnus to re-read the description from the server. - -@item M-d -@kindex M-d (Group) -@findex gnus-group-describe-all-groups -Describe all groups (@code{gnus-group-describe-all-groups}). If given a -prefix, force Gnus to re-read the description file from the server. - -@item H v -@itemx V -@kindex V (Group) -@kindex H v (Group) -@cindex version -@findex gnus-version -Display current Gnus version numbers (@code{gnus-version}). - -@item ? -@kindex ? (Group) -@findex gnus-group-describe-briefly -Give a very short help message (@code{gnus-group-describe-briefly}). - -@item C-c C-i -@kindex C-c C-i (Group) -@cindex info -@cindex manual -@findex gnus-info-find-node -Go to the Gnus info node (@code{gnus-info-find-node}). -@end table - - -@node Group Timestamp -@subsection Group Timestamp -@cindex timestamps -@cindex group timestamps - -It can be convenient to let Gnus keep track of when you last read a -group. To set the ball rolling, you should add -@code{gnus-group-set-timestamp} to @code{gnus-select-group-hook}: - -@lisp -(add-hook 'gnus-select-group-hook 'gnus-group-set-timestamp) -@end lisp - -After doing this, each time you enter a group, it'll be recorded. - -This information can be displayed in various ways---the easiest is to -use the @samp{%d} spec in the group line format: - -@lisp -(setq gnus-group-line-format - "%M\%S\%p\%P\%5y: %(%-40,40g%) %d\n") -@end lisp - -This will result in lines looking like: - -@example -* 0: mail.ding 19961002T012943 - 0: custom 19961002T012713 -@end example - -As you can see, the date is displayed in compact ISO 8601 format. This -may be a bit too much, so to just display the date, you could say -something like: - -@lisp -(setq gnus-group-line-format - "%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n") -@end lisp - -If you would like greater control of the time format, you can use a -user-defined format spec. Something like the following should do the -trick: - -@lisp -(setq gnus-group-line-format - "%M\%S\%p\%P\%5y: %(%-40,40g%) %ud\n") -(defun gnus-user-format-function-d (headers) - (let ((time (gnus-group-timestamp gnus-tmp-group))) - (if time - (format-time-string "%b %d %H:%M" time) - ""))) -@end lisp - - -@node File Commands -@subsection File Commands -@cindex file commands - -@table @kbd - -@item r -@kindex r (Group) -@findex gnus-group-read-init-file -@vindex gnus-init-file -@cindex reading init file -Re-read the init file (@code{gnus-init-file}, which defaults to -@file{~/.gnus.el}) (@code{gnus-group-read-init-file}). - -@item s -@kindex s (Group) -@findex gnus-group-save-newsrc -@cindex saving .newsrc -Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted) -(@code{gnus-group-save-newsrc}). If given a prefix, force saving the -file(s) whether Gnus thinks it is necessary or not. - -@c @item Z -@c @kindex Z (Group) -@c @findex gnus-group-clear-dribble -@c Clear the dribble buffer (@code{gnus-group-clear-dribble}). - -@end table - - -@node Sieve Commands -@subsection Sieve Commands -@cindex group sieve commands - -Sieve is a server-side mail filtering language. In Gnus you can use -the @code{sieve} group parameter (@pxref{Group Parameters}) to specify -sieve rules that should apply to each group. Gnus provides two -commands to translate all these group parameters into a proper Sieve -script that can be transferred to the server somehow. - -@vindex gnus-sieve-file -@vindex gnus-sieve-region-start -@vindex gnus-sieve-region-end -The generated Sieve script is placed in @code{gnus-sieve-file} (by -default @file{~/.sieve}). The Sieve code that Gnus generate is placed -between two delimiters, @code{gnus-sieve-region-start} and -@code{gnus-sieve-region-end}, so you may write additional Sieve code -outside these delimiters that will not be removed the next time you -regenerate the Sieve script. - -@vindex gnus-sieve-crosspost -The variable @code{gnus-sieve-crosspost} controls how the Sieve script -is generated. If it is non-@code{nil} (the default) articles is -placed in all groups that have matching rules, otherwise the article -is only placed in the group with the first matching rule. For -example, the group parameter @samp{(sieve address "sender" -"owner-ding@@hpc.uh.edu")} will generate the following piece of Sieve -code if @code{gnus-sieve-crosspost} is @code{nil}. (When -@code{gnus-sieve-crosspost} is non-@code{nil}, it looks the same -except that the line containing the call to @code{stop} is removed.) - -@example -if address "sender" "owner-ding@@hpc.uh.edu" @{ - fileinto "INBOX.ding"; - stop; -@} -@end example - -@xref{Top, Emacs Sieve, Top, sieve, Emacs Sieve}. - -@table @kbd - -@item D g -@kindex D g (Group) -@findex gnus-sieve-generate -@vindex gnus-sieve-file -@cindex generating sieve script -Regenerate a Sieve script from the @code{sieve} group parameters and -put you into the @code{gnus-sieve-file} without saving it. - -@item D u -@kindex D u (Group) -@findex gnus-sieve-update -@vindex gnus-sieve-file -@cindex updating sieve script -Regenerates the Gnus managed part of @code{gnus-sieve-file} using the -@code{sieve} group parameters, save the file and upload it to the -server using the @code{sieveshell} program. - -@end table - - -@node Summary Buffer -@chapter Summary Buffer -@cindex summary buffer - -A line for each article is displayed in the summary buffer. You can -move around, read articles, post articles and reply to articles. - -The most common way to a summary buffer is to select a group from the -group buffer (@pxref{Selecting a Group}). - -You can have as many summary buffers open as you wish. - -You can customize the Summary Mode tool bar, see @kbd{M-x -customize-apropos RET gnus-summary-tool-bar}. This feature is only -available in Emacs. - -@kindex v (Summary) -@cindex keys, reserved for users (Summary) -The key @kbd{v} is reserved for users. You can bind it to some -command or better use it as a prefix key. For example: -@lisp -(define-key gnus-summary-mode-map (kbd "v -") "LrS") ;; lower subthread -@end lisp - -@menu -* Summary Buffer Format:: Deciding how the summary buffer is to look. -* Summary Maneuvering:: Moving around the summary buffer. -* Choosing Articles:: Reading articles. -* Paging the Article:: Scrolling the current article. -* Reply Followup and Post:: Posting articles. -* Delayed Articles:: Send articles at a later time. -* Marking Articles:: Marking articles as read, expirable, etc. -* Limiting:: You can limit the summary buffer. -* Threading:: How threads are made. -* Sorting the Summary Buffer:: How articles and threads are sorted. -* Asynchronous Fetching:: Gnus might be able to pre-fetch articles. -* Article Caching:: You may store articles in a cache. -* Persistent Articles:: Making articles expiry-resistant. -* Sticky Articles:: Article buffers that are not reused. -* Article Backlog:: Having already read articles hang around. -* Saving Articles:: Ways of customizing article saving. -* Decoding Articles:: Gnus can treat series of (uu)encoded articles. -* Article Treatment:: The article buffer can be mangled at will. -* MIME Commands:: Doing MIMEy things with the articles. -* Charsets:: Character set issues. -* Article Commands:: Doing various things with the article buffer. -* Summary Sorting:: Sorting the summary buffer in various ways. -* Finding the Parent:: No child support? Get the parent. -* Alternative Approaches:: Reading using non-default summaries. -* Tree Display:: A more visual display of threads. -* Mail Group Commands:: Some commands can only be used in mail groups. -* Various Summary Stuff:: What didn't fit anywhere else. -* Exiting the Summary Buffer:: Returning to the Group buffer, - or reselecting the current group. -* Crosspost Handling:: How crossposted articles are dealt with. -* Duplicate Suppression:: An alternative when crosspost handling fails. -* Security:: Decrypt and Verify. -* Mailing List:: Mailing list minor mode. -@end menu - - -@node Summary Buffer Format -@section Summary Buffer Format -@cindex summary buffer format - -@iftex -@iflatex -\gnusfigure{The Summary Buffer}{180}{ -\put(0,0){\epsfig{figure=ps/summary,width=7.5cm}} -\put(445,0){\makebox(0,0)[br]{\epsfig{figure=ps/summary-article,width=7.5cm}}} -} -@end iflatex -@end iftex - -@menu -* Summary Buffer Lines:: You can specify how summary lines should look. -* To From Newsgroups:: How to not display your own name. -* Summary Buffer Mode Line:: You can say how the mode line should look. -* Summary Highlighting:: Making the summary buffer all pretty and nice. -@end menu - -@findex mail-extract-address-components -@findex gnus-extract-address-components -@vindex gnus-extract-address-components -Gnus will use the value of the @code{gnus-extract-address-components} -variable as a function for getting the name and address parts of a -@code{From} header. Two pre-defined functions exist: -@code{gnus-extract-address-components}, which is the default, quite -fast, and too simplistic solution; and -@code{mail-extract-address-components}, which works very nicely, but is -slower. The default function will return the wrong answer in 5% of the -cases. If this is unacceptable to you, use the other function instead: - -@lisp -(setq gnus-extract-address-components - 'mail-extract-address-components) -@end lisp - -@vindex gnus-summary-same-subject -@code{gnus-summary-same-subject} is a string indicating that the current -article has the same subject as the previous. This string will be used -with those specs that require it. The default is @code{""}. - - -@node Summary Buffer Lines -@subsection Summary Buffer Lines - -@vindex gnus-summary-line-format -You can change the format of the lines in the summary buffer by changing -the @code{gnus-summary-line-format} variable. It works along the same -lines as a normal @code{format} string, with some extensions -(@pxref{Formatting Variables}). - -There should always be a colon or a point position marker on the line; -the cursor always moves to the point position marker or the colon after -performing an operation. (Of course, Gnus wouldn't be Gnus if it wasn't -possible to change this. Just write a new function -@code{gnus-goto-colon} which does whatever you like with the cursor.) -@xref{Positioning Point}. - -The default string is @samp{%U%R%z%I%(%[%4L: %-23,23f%]%) %s\n}. - -The following format specification characters and extended format -specification(s) are understood: - -@table @samp -@item N -Article number. -@item S -Subject string. List identifiers stripped, -@code{gnus-list-identifiers}. @xref{Article Hiding}. -@item s -Subject if the article is the root of the thread or the previous article -had a different subject, @code{gnus-summary-same-subject} otherwise. -(@code{gnus-summary-same-subject} defaults to @code{""}.) -@item F -Full @code{From} header. -@item n -The name (from the @code{From} header). -@item f -The name, @code{To} header or the @code{Newsgroups} header (@pxref{To -From Newsgroups}). -@item a -The name (from the @code{From} header). This differs from the @code{n} -spec in that it uses the function designated by the -@code{gnus-extract-address-components} variable, which is slower, but -may be more thorough. -@item A -The address (from the @code{From} header). This works the same way as -the @code{a} spec. -@item L -Number of lines in the article. -@item c -Number of characters in the article. This specifier is not supported -in some methods (like nnfolder). -@item k -Pretty-printed version of the number of characters in the article; -for example, @samp{1.2k} or @samp{0.4M}. -@item I -Indentation based on thread level (@pxref{Customizing Threading}). -@item B -A complex trn-style thread tree, showing response-connecting trace -lines. A thread could be drawn like this: - -@example -> -+-> -| +-> -| | \-> -| | \-> -| \-> -+-> -\-> -@end example - -You can customize the appearance with the following options. Note -that it is possible to make the thread display look really neat by -replacing the default @acronym{ASCII} characters with graphic -line-drawing glyphs. -@table @code -@item gnus-sum-thread-tree-root -@vindex gnus-sum-thread-tree-root -Used for the root of a thread. If @code{nil}, use subject -instead. The default is @samp{> }. - -@item gnus-sum-thread-tree-false-root -@vindex gnus-sum-thread-tree-false-root -Used for the false root of a thread (@pxref{Loose Threads}). If -@code{nil}, use subject instead. The default is @samp{> }. - -@item gnus-sum-thread-tree-single-indent -@vindex gnus-sum-thread-tree-single-indent -Used for a thread with just one message. If @code{nil}, use subject -instead. The default is @samp{}. - -@item gnus-sum-thread-tree-vertical -@vindex gnus-sum-thread-tree-vertical -Used for drawing a vertical line. The default is @samp{| }. - -@item gnus-sum-thread-tree-indent -@vindex gnus-sum-thread-tree-indent -Used for indenting. The default is @samp{ }. - -@item gnus-sum-thread-tree-leaf-with-other -@vindex gnus-sum-thread-tree-leaf-with-other -Used for a leaf with brothers. The default is @samp{+-> }. - -@item gnus-sum-thread-tree-single-leaf -@vindex gnus-sum-thread-tree-single-leaf -Used for a leaf without brothers. The default is @samp{\-> } - -@end table - -@item T -Nothing if the article is a root and lots of spaces if it isn't (it -pushes everything after it off the screen). -@item [ -Opening bracket, which is normally @samp{[}, but can also be @samp{<} -for adopted articles (@pxref{Customizing Threading}). -@item ] -Closing bracket, which is normally @samp{]}, but can also be @samp{>} -for adopted articles. -@item > -One space for each thread level. -@item < -Twenty minus thread level spaces. -@item U -Unread. @xref{Read Articles}. - -@item R -This misleadingly named specifier is the @dfn{secondary mark}. This -mark will say whether the article has been replied to, has been cached, -or has been saved. @xref{Other Marks}. - -@item i -Score as a number (@pxref{Scoring}). -@item z -@vindex gnus-summary-zcore-fuzz -Zcore, @samp{+} if above the default level and @samp{-} if below the -default level. If the difference between -@code{gnus-summary-default-score} and the score is less than -@code{gnus-summary-zcore-fuzz}, this spec will not be used. -@item V -Total thread score. -@item x -@code{Xref}. -@item D -@code{Date}. -@item d -The @code{Date} in @code{DD-MMM} format. -@item o -The @code{Date} in @var{YYYYMMDD}@code{T}@var{HHMMSS} format. -@item M -@code{Message-ID}. -@item r -@code{References}. -@item t -Number of articles in the current sub-thread. Using this spec will slow -down summary buffer generation somewhat. -@item e -An @samp{=} (@code{gnus-not-empty-thread-mark}) will be displayed if the -article has any children. -@item P -The line number. -@item O -Download mark. -@item * -Desired cursor position (instead of after first colon). -@item &user-date; -Age sensitive date format. Various date format is defined in -@code{gnus-user-date-format-alist}. -@item u -User defined specifier. The next character in the format string should -be a letter. Gnus will call the function -@code{gnus-user-format-function-@var{x}}, where @var{x} is the letter -following @samp{%u}. The function will be passed the current header as -argument. The function should return a string, which will be inserted -into the summary just like information from any other summary specifier. -@end table - -Text between @samp{%(} and @samp{%)} will be highlighted with -@code{gnus-mouse-face} when the mouse point is placed inside the area. -There can only be one such area. - -The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs -have to be handled with care. For reasons of efficiency, Gnus will -compute what column these characters will end up in, and ``hard-code'' -that. This means that it is invalid to have these specs after a -variable-length spec. Well, you might not be arrested, but your summary -buffer will look strange, which is bad enough. - -The smart choice is to have these specs as far to the left as possible. -(Isn't that the case with everything, though? But I digress.) - -This restriction may disappear in later versions of Gnus. - - -@node To From Newsgroups -@subsection To From Newsgroups -@cindex To -@cindex Newsgroups - -In some groups (particularly in archive groups), the @code{From} header -isn't very interesting, since all the articles there are written by -you. To display the information in the @code{To} or @code{Newsgroups} -headers instead, you need to decide three things: What information to -gather; where to display it; and when to display it. - -@enumerate -@item -@vindex gnus-extra-headers -The reading of extra header information is controlled by the -@code{gnus-extra-headers}. This is a list of header symbols. For -instance: - -@lisp -(setq gnus-extra-headers - '(To Newsgroups X-Newsreader)) -@end lisp - -This will result in Gnus trying to obtain these three headers, and -storing it in header structures for later easy retrieval. - -@item -@findex gnus-extra-header -The value of these extra headers can be accessed via the -@code{gnus-extra-header} function. Here's a format line spec that will -access the @code{X-Newsreader} header: - -@example -"%~(form (gnus-extra-header 'X-Newsreader))@@" -@end example - -@item -@vindex gnus-ignored-from-addresses -The @code{gnus-ignored-from-addresses} variable says when the @samp{%f} -summary line spec returns the @code{To}, @code{Newsreader} or -@code{From} header. If this regexp matches the contents of the -@code{From} header, the value of the @code{To} or @code{Newsreader} -headers are used instead. - -To distinguish regular articles from those where the @code{From} field -has been swapped, a string is prefixed to the @code{To} or -@code{Newsgroups} header in the summary line. By default the string is -@samp{-> } for @code{To} and @samp{=> } for @code{Newsgroups}, you can -customize these strings with @code{gnus-summary-to-prefix} and -@code{gnus-summary-newsgroup-prefix}. - -@end enumerate - -@vindex nnmail-extra-headers -A related variable is @code{nnmail-extra-headers}, which controls when -to include extra headers when generating overview (@acronym{NOV}) files. -If you have old overview files, you should regenerate them after -changing this variable, by entering the server buffer using @kbd{^}, -and then @kbd{g} on the appropriate mail server (e.g. nnml) to cause -regeneration. - -@vindex gnus-summary-line-format -You also have to instruct Gnus to display the data by changing the -@code{%n} spec to the @code{%f} spec in the -@code{gnus-summary-line-format} variable. - -In summary, you'd typically put something like the following in -@file{~/.gnus.el}: - -@lisp -(setq gnus-extra-headers - '(To Newsgroups)) -(setq nnmail-extra-headers gnus-extra-headers) -(setq gnus-summary-line-format - "%U%R%z%I%(%[%4L: %-23,23f%]%) %s\n") -(setq gnus-ignored-from-addresses - "Your Name Here") -@end lisp - -(The values listed above are the default values in Gnus. Alter them -to fit your needs.) - -A note for news server administrators, or for users who wish to try to -convince their news server administrator to provide some additional -support: - -The above is mostly useful for mail groups, where you have control over -the @acronym{NOV} files that are created. However, if you can persuade your -nntp admin to add (in the usual implementation, notably INN): - -@example -Newsgroups:full -@end example - -to the end of her @file{overview.fmt} file, then you can use that just -as you would the extra headers from the mail groups. - - -@node Summary Buffer Mode Line -@subsection Summary Buffer Mode Line - -@vindex gnus-summary-mode-line-format -You can also change the format of the summary mode bar (@pxref{Mode Line -Formatting}). Set @code{gnus-summary-mode-line-format} to whatever you -like. The default is @samp{Gnus: %%b [%A] %Z}. - -Here are the elements you can play with: - -@table @samp -@item G -Group name. -@item p -Unprefixed group name. -@item A -Current article number. -@item z -Current article score. -@item V -Gnus version. -@item U -Number of unread articles in this group. -@item e -Number of unread articles in this group that aren't displayed in the -summary buffer. -@item Z -A string with the number of unread and unselected articles represented -either as @samp{<%U(+%e) more>} if there are both unread and unselected -articles, and just as @samp{<%U more>} if there are just unread articles -and no unselected ones. -@item g -Shortish group name. For instance, @samp{rec.arts.anime} will be -shortened to @samp{r.a.anime}. -@item S -Subject of the current article. -@item u -User-defined spec (@pxref{User-Defined Specs}). -@item s -Name of the current score file (@pxref{Scoring}). -@item d -Number of dormant articles (@pxref{Unread Articles}). -@item t -Number of ticked articles (@pxref{Unread Articles}). -@item r -Number of articles that have been marked as read in this session. -@item E -Number of articles expunged by the score files. -@end table - - -@node Summary Highlighting -@subsection Summary Highlighting - -@table @code - -@item gnus-visual-mark-article-hook -@vindex gnus-visual-mark-article-hook -This hook is run after selecting an article. It is meant to be used for -highlighting the article in some way. It is not run if -@code{gnus-visual} is @code{nil}. - -@item gnus-summary-update-hook -@vindex gnus-summary-update-hook -This hook is called when a summary line is changed. It is not run if -@code{gnus-visual} is @code{nil}. - -@item gnus-summary-selected-face -@vindex gnus-summary-selected-face -This is the face (or @dfn{font} as some people call it) used to -highlight the current article in the summary buffer. - -@item gnus-summary-highlight -@vindex gnus-summary-highlight -Summary lines are highlighted according to this variable, which is a -list where the elements are of the format @code{(@var{form} -. @var{face})}. If you would, for instance, like ticked articles to be -italic and high-scored articles to be bold, you could set this variable -to something like -@lisp -(((eq mark gnus-ticked-mark) . italic) - ((> score default) . bold)) -@end lisp -As you may have guessed, if @var{form} returns a non-@code{nil} value, -@var{face} will be applied to the line. -@end table - - -@node Summary Maneuvering -@section Summary Maneuvering -@cindex summary movement - -All the straight movement commands understand the numeric prefix and -behave pretty much as you'd expect. - -None of these commands select articles. - -@table @kbd -@item G M-n -@itemx M-n -@kindex M-n (Summary) -@kindex G M-n (Summary) -@findex gnus-summary-next-unread-subject -Go to the next summary line of an unread article -(@code{gnus-summary-next-unread-subject}). - -@item G M-p -@itemx M-p -@kindex M-p (Summary) -@kindex G M-p (Summary) -@findex gnus-summary-prev-unread-subject -Go to the previous summary line of an unread article -(@code{gnus-summary-prev-unread-subject}). - -@item G g -@kindex G g (Summary) -@findex gnus-summary-goto-subject -Ask for an article number and then go to the summary line of that article -without displaying the article (@code{gnus-summary-goto-subject}). -@end table - -If Gnus asks you to press a key to confirm going to the next group, you -can use the @kbd{C-n} and @kbd{C-p} keys to move around the group -buffer, searching for the next group to read without actually returning -to the group buffer. - -Variables related to summary movement: - -@table @code - -@vindex gnus-auto-select-next -@item gnus-auto-select-next -If you issue one of the movement commands (like @kbd{n}) and there are -no more unread articles after the current one, Gnus will offer to go to -the next group. If this variable is @code{t} and the next group is -empty, Gnus will exit summary mode and return to the group buffer. If -this variable is neither @code{t} nor @code{nil}, Gnus will select the -next group with unread articles. As a special case, if this variable -is @code{quietly}, Gnus will select the next group without asking for -confirmation. If this variable is @code{almost-quietly}, the same -will happen only if you are located on the last article in the group. -Finally, if this variable is @code{slightly-quietly}, the @kbd{Z n} -command will go to the next group without confirmation. Also -@pxref{Group Levels}. - -@item gnus-auto-select-same -@vindex gnus-auto-select-same -If non-@code{nil}, all the movement commands will try to go to the next -article with the same subject as the current. (@dfn{Same} here might -mean @dfn{roughly equal}. See @code{gnus-summary-gather-subject-limit} -for details (@pxref{Customizing Threading}).) If there are no more -articles with the same subject, go to the first unread article. - -This variable is not particularly useful if you use a threaded display. - -@item gnus-summary-check-current -@vindex gnus-summary-check-current -If non-@code{nil}, all the ``unread'' movement commands will not proceed -to the next (or previous) article if the current article is unread. -Instead, they will choose the current article. - -@item gnus-auto-center-summary -@vindex gnus-auto-center-summary -If non-@code{nil}, Gnus will keep the point in the summary buffer -centered at all times. This makes things quite tidy, but if you have a -slow network connection, or simply do not like this un-Emacsism, you can -set this variable to @code{nil} to get the normal Emacs scrolling -action. This will also inhibit horizontal re-centering of the summary -buffer, which might make it more inconvenient to read extremely long -threads. - -This variable can also be a number. In that case, center the window at -the given number of lines from the top. - -@item gnus-summary-stop-at-end-of-message -@vindex gnus-summary-stop-at-end-of-message -If non-@code{nil}, don't go to the next article when hitting -@kbd{SPC}, and you're at the end of the article. - -@end table - - -@node Choosing Articles -@section Choosing Articles -@cindex selecting articles - -@menu -* Choosing Commands:: Commands for choosing articles. -* Choosing Variables:: Variables that influence these commands. -@end menu - - -@node Choosing Commands -@subsection Choosing Commands - -None of the following movement commands understand the numeric prefix, -and they all select and display an article. - -If you want to fetch new articles or redisplay the group, see -@ref{Exiting the Summary Buffer}. - -@table @kbd -@item SPACE -@kindex SPACE (Summary) -@findex gnus-summary-next-page -Select the current article, or, if that one's read already, the next -unread article (@code{gnus-summary-next-page}). - -If you have an article window open already and you press @kbd{SPACE} -again, the article will be scrolled. This lets you conveniently -@kbd{SPACE} through an entire newsgroup. @xref{Paging the Article}. - -@item G n -@itemx n -@kindex n (Summary) -@kindex G n (Summary) -@findex gnus-summary-next-unread-article -@c @icon{gnus-summary-next-unread} -Go to next unread article (@code{gnus-summary-next-unread-article}). - -@item G p -@itemx p -@kindex p (Summary) -@findex gnus-summary-prev-unread-article -@c @icon{gnus-summary-prev-unread} -Go to previous unread article (@code{gnus-summary-prev-unread-article}). - -@item G N -@itemx N -@kindex N (Summary) -@kindex G N (Summary) -@findex gnus-summary-next-article -Go to the next article (@code{gnus-summary-next-article}). - -@item G P -@itemx P -@kindex P (Summary) -@kindex G P (Summary) -@findex gnus-summary-prev-article -Go to the previous article (@code{gnus-summary-prev-article}). - -@item G C-n -@kindex G C-n (Summary) -@findex gnus-summary-next-same-subject -Go to the next article with the same subject -(@code{gnus-summary-next-same-subject}). - -@item G C-p -@kindex G C-p (Summary) -@findex gnus-summary-prev-same-subject -Go to the previous article with the same subject -(@code{gnus-summary-prev-same-subject}). - -@item G f -@itemx . -@kindex G f (Summary) -@kindex . (Summary) -@findex gnus-summary-first-unread-article -Go to the first unread article -(@code{gnus-summary-first-unread-article}). - -@item G b -@itemx , -@kindex G b (Summary) -@kindex , (Summary) -@findex gnus-summary-best-unread-article -Go to the unread article with the highest score -(@code{gnus-summary-best-unread-article}). If given a prefix argument, -go to the first unread article that has a score over the default score. - -@item G l -@itemx l -@kindex l (Summary) -@kindex G l (Summary) -@findex gnus-summary-goto-last-article -Go to the previous article read (@code{gnus-summary-goto-last-article}). - -@item G o -@kindex G o (Summary) -@findex gnus-summary-pop-article -@cindex history -@cindex article history -Pop an article off the summary history and go to this article -(@code{gnus-summary-pop-article}). This command differs from the -command above in that you can pop as many previous articles off the -history as you like, while @kbd{l} toggles the two last read articles. -For a somewhat related issue (if you use these commands a lot), -@pxref{Article Backlog}. - -@item G j -@itemx j -@kindex j (Summary) -@kindex G j (Summary) -@findex gnus-summary-goto-article -Ask for an article number or @code{Message-ID}, and then go to that -article (@code{gnus-summary-goto-article}). - -@end table - - -@node Choosing Variables -@subsection Choosing Variables - -Some variables relevant for moving and selecting articles: - -@table @code -@item gnus-auto-extend-newsgroup -@vindex gnus-auto-extend-newsgroup -All the movement commands will try to go to the previous (or next) -article, even if that article isn't displayed in the Summary buffer if -this variable is non-@code{nil}. Gnus will then fetch the article from -the server and display it in the article buffer. - -@item gnus-select-article-hook -@vindex gnus-select-article-hook -This hook is called whenever an article is selected. The default is -@code{nil}. If you would like each article to be saved in the Agent as -you read it, putting @code{gnus-agent-fetch-selected-article} on this -hook will do so. - -@item gnus-mark-article-hook -@vindex gnus-mark-article-hook -@findex gnus-summary-mark-unread-as-read -@findex gnus-summary-mark-read-and-unread-as-read -@findex gnus-unread-mark -This hook is called whenever an article is selected. It is intended to -be used for marking articles as read. The default value is -@code{gnus-summary-mark-read-and-unread-as-read}, and will change the -mark of almost any article you read to @code{gnus-read-mark}. The only -articles not affected by this function are ticked, dormant, and -expirable articles. If you'd instead like to just have unread articles -marked as read, you can use @code{gnus-summary-mark-unread-as-read} -instead. It will leave marks like @code{gnus-low-score-mark}, -@code{gnus-del-mark} (and so on) alone. - -@end table - - -@node Paging the Article -@section Scrolling the Article -@cindex article scrolling - -@table @kbd - -@item SPACE -@kindex SPACE (Summary) -@findex gnus-summary-next-page -Pressing @kbd{SPACE} will scroll the current article forward one page, -or, if you have come to the end of the current article, will choose the -next article (@code{gnus-summary-next-page}). - -@vindex gnus-article-boring-faces -@vindex gnus-article-skip-boring -If @code{gnus-article-skip-boring} is non-@code{nil} and the rest of -the article consists only of citations and signature, then it will be -skipped; the next article will be shown instead. You can customize -what is considered uninteresting with -@code{gnus-article-boring-faces}. You can manually view the article's -pages, no matter how boring, using @kbd{C-M-v}. - -@item DEL -@kindex DEL (Summary) -@findex gnus-summary-prev-page -Scroll the current article back one page (@code{gnus-summary-prev-page}). - -@item RET -@kindex RET (Summary) -@findex gnus-summary-scroll-up -Scroll the current article one line forward -(@code{gnus-summary-scroll-up}). - -@item M-RET -@kindex M-RET (Summary) -@findex gnus-summary-scroll-down -Scroll the current article one line backward -(@code{gnus-summary-scroll-down}). - -@item A g -@itemx g -@kindex A g (Summary) -@kindex g (Summary) -@findex gnus-summary-show-article -@vindex gnus-summary-show-article-charset-alist -(Re)fetch the current article (@code{gnus-summary-show-article}). If -given a prefix, show a completely ``raw'' article, just the way it -came from the server. If given a prefix twice (i.e., @kbd{C-u C-u -g'}), fetch the current article, but don't run any of the article -treatment functions. - -@cindex charset, view article with different charset -If given a numerical prefix, you can do semi-manual charset stuff. -@kbd{C-u 0 g cn-gb-2312 RET} will decode the message as if it were -encoded in the @code{cn-gb-2312} charset. If you have - -@lisp -(setq gnus-summary-show-article-charset-alist - '((1 . cn-gb-2312) - (2 . big5))) -@end lisp - -then you can say @kbd{C-u 1 g} to get the same effect. - -@item A < -@itemx < -@kindex < (Summary) -@kindex A < (Summary) -@findex gnus-summary-beginning-of-article -Scroll to the beginning of the article -(@code{gnus-summary-beginning-of-article}). - -@item A > -@itemx > -@kindex > (Summary) -@kindex A > (Summary) -@findex gnus-summary-end-of-article -Scroll to the end of the article (@code{gnus-summary-end-of-article}). - -@item A s -@itemx s -@kindex A s (Summary) -@kindex s (Summary) -@findex gnus-summary-isearch-article -Perform an isearch in the article buffer -(@code{gnus-summary-isearch-article}). - -@item h -@kindex h (Summary) -@findex gnus-summary-select-article-buffer -Select the article buffer (@code{gnus-summary-select-article-buffer}). - -@end table - - -@node Reply Followup and Post -@section Reply, Followup and Post - -@menu -* Summary Mail Commands:: Sending mail. -* Summary Post Commands:: Sending news. -* Summary Message Commands:: Other Message-related commands. -* Canceling and Superseding:: -@end menu - - -@node Summary Mail Commands -@subsection Summary Mail Commands -@cindex mail -@cindex composing mail - -Commands for composing a mail message: - -@table @kbd - -@item S r -@itemx r -@kindex S r (Summary) -@kindex r (Summary) -@findex gnus-summary-reply -@c @icon{gnus-summary-mail-reply} -@c @icon{gnus-summary-reply} -Mail a reply to the author of the current article -(@code{gnus-summary-reply}). - -@item S R -@itemx R -@kindex R (Summary) -@kindex S R (Summary) -@findex gnus-summary-reply-with-original -@c @icon{gnus-summary-reply-with-original} -Mail a reply to the author of the current article and include the -original message (@code{gnus-summary-reply-with-original}). This -command uses the process/prefix convention. - -@item S w -@kindex S w (Summary) -@findex gnus-summary-wide-reply -Mail a wide reply to the author of the current article -(@code{gnus-summary-wide-reply}). A @dfn{wide reply} is a reply that -goes out to all people listed in the @code{To}, @code{From} (or -@code{Reply-to}) and @code{Cc} headers. If @code{Mail-Followup-To} is -present, that's used instead. - -@item S W -@kindex S W (Summary) -@findex gnus-summary-wide-reply-with-original -Mail a wide reply to the current article and include the original -message (@code{gnus-summary-wide-reply-with-original}). This command uses -the process/prefix convention, but only uses the headers from the -first article to determine the recipients. - -@item S L -@kindex S L (Summary) -@findex gnus-summary-reply-to-list-with-original -When replying to a message from a mailing list, send a reply to that -message to the mailing list, and include the original message -(@code{gnus-summary-reply-to-list-with-original}). - -@item S v -@kindex S v (Summary) -@findex gnus-summary-very-wide-reply -Mail a very wide reply to the author of the current article -(@code{gnus-summary-wide-reply}). A @dfn{very wide reply} is a reply -that goes out to all people listed in the @code{To}, @code{From} (or -@code{Reply-to}) and @code{Cc} headers in all the process/prefixed -articles. This command uses the process/prefix convention. - -@item S V -@kindex S V (Summary) -@findex gnus-summary-very-wide-reply-with-original -Mail a very wide reply to the author of the current article and include the -original message (@code{gnus-summary-very-wide-reply-with-original}). This -command uses the process/prefix convention. - -@item S B r -@kindex S B r (Summary) -@findex gnus-summary-reply-broken-reply-to -Mail a reply to the author of the current article but ignore the -@code{Reply-To} field (@code{gnus-summary-reply-broken-reply-to}). -If you need this because a mailing list incorrectly sets a -@code{Reply-To} header pointing to the list, you probably want to set -the @code{broken-reply-to} group parameter instead, so things will work -correctly. @xref{Group Parameters}. - -@item S B R -@kindex S B R (Summary) -@findex gnus-summary-reply-broken-reply-to-with-original -Mail a reply to the author of the current article and include the -original message but ignore the @code{Reply-To} field -(@code{gnus-summary-reply-broken-reply-to-with-original}). - -@item S o m -@itemx C-c C-f -@kindex S o m (Summary) -@kindex C-c C-f (Summary) -@findex gnus-summary-mail-forward -@c @icon{gnus-summary-mail-forward} -Forward the current article to some other person -(@code{gnus-summary-mail-forward}). If no prefix is given, the message -is forwarded according to the value of (@code{message-forward-as-mime}) -and (@code{message-forward-show-mml}); if the prefix is 1, decode the -message and forward directly inline; if the prefix is 2, forward message -as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and -forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message -directly inline; otherwise, the message is forwarded as no prefix given -but use the flipped value of (@code{message-forward-as-mime}). By -default, the message is decoded and forwarded as an rfc822 @acronym{MIME} -section. - -@item S m -@itemx m -@kindex m (Summary) -@kindex S m (Summary) -@findex gnus-summary-mail-other-window -@c @icon{gnus-summary-mail-originate} -Prepare a mail (@code{gnus-summary-mail-other-window}). By default, use -the posting style of the current group. If given a prefix, disable that. -If the prefix is 1, prompt for a group name to find the posting style. - -@item S i -@kindex S i (Summary) -@findex gnus-summary-news-other-window -Prepare a news (@code{gnus-summary-news-other-window}). By default, -post to the current group. If given a prefix, disable that. If the -prefix is 1, prompt for a group to post to. - -This function actually prepares a news even when using mail groups. -This is useful for ``posting'' messages to mail groups without actually -sending them over the network: they're just saved directly to the group -in question. The corresponding back end must have a request-post method -for this to work though. - -@item S D b -@kindex S D b (Summary) -@findex gnus-summary-resend-bounced-mail -@cindex bouncing mail -If you have sent a mail, but the mail was bounced back to you for some -reason (wrong address, transient failure), you can use this command to -resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You -will be popped into a mail buffer where you can edit the headers before -sending the mail off again. If you give a prefix to this command, and -the bounced mail is a reply to some other mail, Gnus will try to fetch -that mail and display it for easy perusal of its headers. This might -very well fail, though. - -@item S D r -@kindex S D r (Summary) -@findex gnus-summary-resend-message -Not to be confused with the previous command, -@code{gnus-summary-resend-message} will prompt you for an address to -send the current message off to, and then send it to that place. The -headers of the message won't be altered---but lots of headers that say -@code{Resent-To}, @code{Resent-From} and so on will be added. This -means that you actually send a mail to someone that has a @code{To} -header that (probably) points to yourself. This will confuse people. -So, natcherly you'll only do that if you're really eVIl. - -This command is mainly used if you have several accounts and want to -ship a mail to a different account of yours. (If you're both -@code{root} and @code{postmaster} and get a mail for @code{postmaster} -to the @code{root} account, you may want to resend it to -@code{postmaster}. Ordnung muss sein! - -This command understands the process/prefix convention -(@pxref{Process/Prefix}). - -@item S D e -@kindex S D e (Summary) -@findex gnus-summary-resend-message-edit - -Like the previous command, but will allow you to edit the message as -if it were a new message before resending. - -@item S O m -@kindex S O m (Summary) -@findex gnus-uu-digest-mail-forward -Digest the current series (@pxref{Decoding Articles}) and forward the -result using mail (@code{gnus-uu-digest-mail-forward}). This command -uses the process/prefix convention (@pxref{Process/Prefix}). - -@item S M-c -@kindex S M-c (Summary) -@findex gnus-summary-mail-crosspost-complaint -@cindex crossposting -@cindex excessive crossposting -Send a complaint about excessive crossposting to the author of the -current article (@code{gnus-summary-mail-crosspost-complaint}). - -@findex gnus-crosspost-complaint -This command is provided as a way to fight back against the current -crossposting pandemic that's sweeping Usenet. It will compose a reply -using the @code{gnus-crosspost-complaint} variable as a preamble. This -command understands the process/prefix convention -(@pxref{Process/Prefix}) and will prompt you before sending each mail. - -@end table - -Also @xref{Header Commands, ,Header Commands, message, The Message -Manual}, for more information. - - -@node Summary Post Commands -@subsection Summary Post Commands -@cindex post -@cindex composing news - -Commands for posting a news article: - -@table @kbd -@item S p -@itemx a -@kindex a (Summary) -@kindex S p (Summary) -@findex gnus-summary-post-news -@c @icon{gnus-summary-post-news} -Prepare for posting an article (@code{gnus-summary-post-news}). By -default, post to the current group. If given a prefix, disable that. -If the prefix is 1, prompt for another group instead. - -@item S f -@itemx f -@kindex f (Summary) -@kindex S f (Summary) -@findex gnus-summary-followup -@c @icon{gnus-summary-followup} -Post a followup to the current article (@code{gnus-summary-followup}). - -@item S F -@itemx F -@kindex S F (Summary) -@kindex F (Summary) -@c @icon{gnus-summary-followup-with-original} -@findex gnus-summary-followup-with-original -Post a followup to the current article and include the original message -(@code{gnus-summary-followup-with-original}). This command uses the -process/prefix convention. - -@item S n -@kindex S n (Summary) -@findex gnus-summary-followup-to-mail -Post a followup to the current article via news, even if you got the -message through mail (@code{gnus-summary-followup-to-mail}). - -@item S N -@kindex S N (Summary) -@findex gnus-summary-followup-to-mail-with-original -Post a followup to the current article via news, even if you got the -message through mail and include the original message -(@code{gnus-summary-followup-to-mail-with-original}). This command uses -the process/prefix convention. - -@item S o p -@kindex S o p (Summary) -@findex gnus-summary-post-forward -Forward the current article to a newsgroup -(@code{gnus-summary-post-forward}). - If no prefix is given, the message is forwarded according to the value -of (@code{message-forward-as-mime}) and -(@code{message-forward-show-mml}); if the prefix is 1, decode the -message and forward directly inline; if the prefix is 2, forward message -as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and -forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message -directly inline; otherwise, the message is forwarded as no prefix given -but use the flipped value of (@code{message-forward-as-mime}). By -default, the message is decoded and forwarded as an rfc822 @acronym{MIME} section. - -@item S O p -@kindex S O p (Summary) -@findex gnus-uu-digest-post-forward -@cindex digests -@cindex making digests -Digest the current series and forward the result to a newsgroup -(@code{gnus-uu-digest-post-forward}). This command uses the -process/prefix convention. - -@item S u -@kindex S u (Summary) -@findex gnus-uu-post-news -@c @icon{gnus-uu-post-news} -Uuencode a file, split it into parts, and post it as a series -(@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}). -@end table - -Also @xref{Header Commands, ,Header Commands, message, The Message -Manual}, for more information. - - -@node Summary Message Commands -@subsection Summary Message Commands - -@table @kbd -@item S y -@kindex S y (Summary) -@findex gnus-summary-yank-message -Yank the current article into an already existing Message composition -buffer (@code{gnus-summary-yank-message}). This command prompts for -what message buffer you want to yank into, and understands the -process/prefix convention (@pxref{Process/Prefix}). - -@end table - - -@node Canceling and Superseding -@subsection Canceling Articles -@cindex canceling articles -@cindex superseding articles - -Have you ever written something, and then decided that you really, -really, really wish you hadn't posted that? - -Well, you can't cancel mail, but you can cancel posts. - -@findex gnus-summary-cancel-article -@kindex C (Summary) -@c @icon{gnus-summary-cancel-article} -Find the article you wish to cancel (you can only cancel your own -articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S -c} (@code{gnus-summary-cancel-article}). Your article will be -canceled---machines all over the world will be deleting your article. -This command uses the process/prefix convention (@pxref{Process/Prefix}). - -Be aware, however, that not all sites honor cancels, so your article may -live on here and there, while most sites will delete the article in -question. - -Gnus will use the ``current'' select method when canceling. If you -want to use the standard posting method, use the @samp{a} symbolic -prefix (@pxref{Symbolic Prefixes}). - -Gnus ensures that only you can cancel your own messages using a -@code{Cancel-Lock} header (@pxref{Canceling News, Canceling News, , -message, Message Manual}). - -If you discover that you have made some mistakes and want to do some -corrections, you can post a @dfn{superseding} article that will replace -your original article. - -@findex gnus-summary-supersede-article -@kindex S (Summary) -Go to the original article and press @kbd{S s} -(@code{gnus-summary-supersede-article}). You will be put in a buffer -where you can edit the article all you want before sending it off the -usual way. - -The same goes for superseding as for canceling, only more so: Some -sites do not honor superseding. On those sites, it will appear that you -have posted almost the same article twice. - -If you have just posted the article, and change your mind right away, -there is a trick you can use to cancel/supersede the article without -waiting for the article to appear on your site first. You simply return -to the post buffer (which is called @code{*sent ...*}). There you will -find the article you just posted, with all the headers intact. Change -the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes} -header by substituting one of those words for the word -@code{Message-ID}. Then just press @kbd{C-c C-c} to send the article as -you would do normally. The previous article will be -canceled/superseded. - -Just remember, kids: There is no 'c' in 'supersede'. - -@node Delayed Articles -@section Delayed Articles -@cindex delayed sending -@cindex send delayed - -Sometimes, you might wish to delay the sending of a message. For -example, you might wish to arrange for a message to turn up just in time -to remind your about the birthday of your Significant Other. For this, -there is the @code{gnus-delay} package. Setup is simple: - -@lisp -(gnus-delay-initialize) -@end lisp - -@findex gnus-delay-article -Normally, to send a message you use the @kbd{C-c C-c} command from -Message mode. To delay a message, use @kbd{C-c C-j} -(@code{gnus-delay-article}) instead. This will ask you for how long the -message should be delayed. Possible answers are: - -@itemize @bullet -@item -A time span. Consists of an integer and a letter. For example, -@code{42d} means to delay for 42 days. Available letters are @code{m} -(minutes), @code{h} (hours), @code{d} (days), @code{w} (weeks), @code{M} -(months) and @code{Y} (years). - -@item -A specific date. Looks like @code{YYYY-MM-DD}. The message will be -delayed until that day, at a specific time (eight o'clock by default). -See also @code{gnus-delay-default-hour}. - -@item -A specific time of day. Given in @code{hh:mm} format, 24h, no am/pm -stuff. The deadline will be at that time today, except if that time has -already passed, then it's at the given time tomorrow. So if it's ten -o'clock in the morning and you specify @code{11:15}, then the deadline -is one hour and fifteen minutes hence. But if you specify @code{9:20}, -that means a time tomorrow. -@end itemize - -The action of the @code{gnus-delay-article} command is influenced by a -couple of variables: - -@table @code -@item gnus-delay-default-hour -@vindex gnus-delay-default-hour -When you specify a specific date, the message will be due on that hour -on the given date. Possible values are integers 0 through 23. - -@item gnus-delay-default-delay -@vindex gnus-delay-default-delay -This is a string and gives the default delay. It can be of any of the -formats described above. - -@item gnus-delay-group -@vindex gnus-delay-group -Delayed articles will be kept in this group on the drafts server until -they are due. You probably don't need to change this. The default -value is @code{"delayed"}. - -@item gnus-delay-header -@vindex gnus-delay-header -The deadline for each article will be stored in a header. This variable -is a string and gives the header name. You probably don't need to -change this. The default value is @code{"X-Gnus-Delayed"}. -@end table - -The way delaying works is like this: when you use the -@code{gnus-delay-article} command, you give a certain delay. Gnus -calculates the deadline of the message and stores it in the -@code{X-Gnus-Delayed} header and puts the message in the -@code{nndraft:delayed} group. - -@findex gnus-delay-send-queue -And whenever you get new news, Gnus looks through the group for articles -which are due and sends them. It uses the @code{gnus-delay-send-queue} -function for this. By default, this function is added to the hook -@code{gnus-get-new-news-hook}. But of course, you can change this. -Maybe you want to use the demon to send drafts? Just tell the demon to -execute the @code{gnus-delay-send-queue} function. - -@table @code -@item gnus-delay-initialize -@findex gnus-delay-initialize -By default, this function installs @code{gnus-delay-send-queue} in -@code{gnus-get-new-news-hook}. But it accepts the optional second -argument @code{no-check}. If it is non-@code{nil}, -@code{gnus-get-new-news-hook} is not changed. The optional first -argument is ignored. - -For example, @code{(gnus-delay-initialize nil t)} means to do nothing. -Presumably, you want to use the demon for sending due delayed articles. -Just don't forget to set that up :-) -@end table - -When delaying an article with @kbd{C-c C-j}, Message mode will -automatically add a @code{"Date"} header with the current time. In -many cases you probably want the @code{"Date"} header to reflect the -time the message is sent instead. To do this, you have to delete -@code{Date} from @code{message-draft-headers}. - - -@node Marking Articles -@section Marking Articles -@cindex article marking -@cindex article ticking -@cindex marks - -There are several marks you can set on an article. - -You have marks that decide the @dfn{readedness} (whoo, neato-keano -neologism ohoy!) of the article. Alphabetic marks generally mean -@dfn{read}, while non-alphabetic characters generally mean @dfn{unread}. - -In addition, you also have marks that do not affect readedness. - -@ifinfo -There's a plethora of commands for manipulating these marks. -@end ifinfo - -@menu -* Unread Articles:: Marks for unread articles. -* Read Articles:: Marks for read articles. -* Other Marks:: Marks that do not affect readedness. -* Setting Marks:: How to set and remove marks. -* Generic Marking Commands:: How to customize the marking. -* Setting Process Marks:: How to mark articles for later processing. -@end menu - - -@node Unread Articles -@subsection Unread Articles - -The following marks mark articles as (kinda) unread, in one form or -other. - -@table @samp -@item ! -@vindex gnus-ticked-mark -Marked as ticked (@code{gnus-ticked-mark}). - -@dfn{Ticked articles} are articles that will remain visible always. If -you see an article that you find interesting, or you want to put off -reading it, or replying to it, until sometime later, you'd typically -tick it. However, articles can be expired (from news servers by the -news server software, Gnus itself never expires ticked messages), so if -you want to keep an article forever, you'll have to make it persistent -(@pxref{Persistent Articles}). - -@item ? -@vindex gnus-dormant-mark -Marked as dormant (@code{gnus-dormant-mark}). - -@dfn{Dormant articles} will only appear in the summary buffer if there -are followups to it. If you want to see them even if they don't have -followups, you can use the @kbd{/ D} command (@pxref{Limiting}). -Otherwise (except for the visibility issue), they are just like ticked -messages. - -@item SPACE -@vindex gnus-unread-mark -Marked as unread (@code{gnus-unread-mark}). - -@dfn{Unread articles} are articles that haven't been read at all yet. -@end table - - -@node Read Articles -@subsection Read Articles -@cindex expirable mark - -All the following marks mark articles as read. - -@table @samp - -@item r -@vindex gnus-del-mark -These are articles that the user has marked as read with the @kbd{d} -command manually, more or less (@code{gnus-del-mark}). - -@item R -@vindex gnus-read-mark -Articles that have actually been read (@code{gnus-read-mark}). - -@item O -@vindex gnus-ancient-mark -Articles that were marked as read in previous sessions and are now -@dfn{old} (@code{gnus-ancient-mark}). - -@item K -@vindex gnus-killed-mark -Marked as killed (@code{gnus-killed-mark}). - -@item X -@vindex gnus-kill-file-mark -Marked as killed by kill files (@code{gnus-kill-file-mark}). - -@item Y -@vindex gnus-low-score-mark -Marked as read by having too low a score (@code{gnus-low-score-mark}). - -@item C -@vindex gnus-catchup-mark -Marked as read by a catchup (@code{gnus-catchup-mark}). - -@item G -@vindex gnus-canceled-mark -Canceled article (@code{gnus-canceled-mark}) - -@item Q -@vindex gnus-sparse-mark -Sparsely reffed article (@code{gnus-sparse-mark}). @xref{Customizing -Threading}. - -@item M -@vindex gnus-duplicate-mark -Article marked as read by duplicate suppression -(@code{gnus-duplicate-mark}). @xref{Duplicate Suppression}. - -@end table - -All these marks just mean that the article is marked as read, really. -They are interpreted differently when doing adaptive scoring, though. - -One more special mark, though: - -@table @samp -@item E -@vindex gnus-expirable-mark -Marked as expirable (@code{gnus-expirable-mark}). - -Marking articles as @dfn{expirable} (or have them marked as such -automatically) doesn't make much sense in normal groups---a user doesn't -control expiring of news articles, but in mail groups, for instance, -articles marked as @dfn{expirable} can be deleted by Gnus at -any time. -@end table - - -@node Other Marks -@subsection Other Marks -@cindex process mark -@cindex bookmarks - -There are some marks that have nothing to do with whether the article is -read or not. - -@itemize @bullet - -@item -You can set a bookmark in the current article. Say you are reading a -long thesis on cats' urinary tracts, and have to go home for dinner -before you've finished reading the thesis. You can then set a bookmark -in the article, and Gnus will jump to this bookmark the next time it -encounters the article. @xref{Setting Marks}. - -@item -@vindex gnus-replied-mark -All articles that you have replied to or made a followup to (i.e., have -answered) will be marked with an @samp{A} in the second column -(@code{gnus-replied-mark}). - -@item -@vindex gnus-forwarded-mark -All articles that you have forwarded will be marked with an @samp{F} in -the second column (@code{gnus-forwarded-mark}). - -@item -@vindex gnus-cached-mark -Articles stored in the article cache will be marked with an @samp{*} in -the second column (@code{gnus-cached-mark}). @xref{Article Caching}. - -@item -@vindex gnus-saved-mark -Articles ``saved'' (in some manner or other; not necessarily -religiously) are marked with an @samp{S} in the second column -(@code{gnus-saved-mark}). - -@item -@vindex gnus-unseen-mark -Articles that haven't been seen before in Gnus by the user are marked -with a @samp{.} in the second column (@code{gnus-unseen-mark}). - -@item -@vindex gnus-downloaded-mark -When using the Gnus agent (@pxref{Agent Basics}), articles may be -downloaded for unplugged (offline) viewing. If you are using the -@samp{%O} spec, these articles get the @samp{+} mark in that spec. -(The variable @code{gnus-downloaded-mark} controls which character to -use.) - -@item -@vindex gnus-undownloaded-mark -When using the Gnus agent (@pxref{Agent Basics}), some articles might -not have been downloaded. Such articles cannot be viewed while you -are unplugged (offline). If you are using the @samp{%O} spec, these -articles get the @samp{-} mark in that spec. (The variable -@code{gnus-undownloaded-mark} controls which character to use.) - -@item -@vindex gnus-downloadable-mark -The Gnus agent (@pxref{Agent Basics}) downloads some articles -automatically, but it is also possible to explicitly mark articles for -download, even if they would not be downloaded automatically. Such -explicitly-marked articles get the @samp{%} mark in the first column. -(The variable @code{gnus-downloadable-mark} controls which character to -use.) - -@item -@vindex gnus-not-empty-thread-mark -@vindex gnus-empty-thread-mark -If the @samp{%e} spec is used, the presence of threads or not will be -marked with @code{gnus-not-empty-thread-mark} and -@code{gnus-empty-thread-mark} in the third column, respectively. - -@item -@vindex gnus-process-mark -Finally we have the @dfn{process mark} (@code{gnus-process-mark}). A -variety of commands react to the presence of the process mark. For -instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view -all articles that have been marked with the process mark. Articles -marked with the process mark have a @samp{#} in the second column. - -@end itemize - -You might have noticed that most of these ``non-readedness'' marks -appear in the second column by default. So if you have a cached, saved, -replied article that you have process-marked, what will that look like? - -Nothing much. The precedence rules go as follows: process -> cache -> -replied -> saved. So if the article is in the cache and is replied, -you'll only see the cache mark and not the replied mark. - - -@node Setting Marks -@subsection Setting Marks -@cindex setting marks - -All the marking commands understand the numeric prefix. - -@table @kbd -@item M c -@itemx M-u -@kindex M c (Summary) -@kindex M-u (Summary) -@findex gnus-summary-clear-mark-forward -@cindex mark as unread -Clear all readedness-marks from the current article -(@code{gnus-summary-clear-mark-forward}). In other words, mark the -article as unread. - -@item M t -@itemx ! -@kindex ! (Summary) -@kindex M t (Summary) -@findex gnus-summary-tick-article-forward -Tick the current article (@code{gnus-summary-tick-article-forward}). -@xref{Article Caching}. - -@item M ? -@itemx ? -@kindex ? (Summary) -@kindex M ? (Summary) -@findex gnus-summary-mark-as-dormant -Mark the current article as dormant -(@code{gnus-summary-mark-as-dormant}). @xref{Article Caching}. - -@item M d -@itemx d -@kindex M d (Summary) -@kindex d (Summary) -@findex gnus-summary-mark-as-read-forward -Mark the current article as read -(@code{gnus-summary-mark-as-read-forward}). - -@item D -@kindex D (Summary) -@findex gnus-summary-mark-as-read-backward -Mark the current article as read and move point to the previous line -(@code{gnus-summary-mark-as-read-backward}). - -@item M k -@itemx k -@kindex k (Summary) -@kindex M k (Summary) -@findex gnus-summary-kill-same-subject-and-select -Mark all articles that have the same subject as the current one as read, -and then select the next unread article -(@code{gnus-summary-kill-same-subject-and-select}). - -@item M K -@itemx C-k -@kindex M K (Summary) -@kindex C-k (Summary) -@findex gnus-summary-kill-same-subject -Mark all articles that have the same subject as the current one as read -(@code{gnus-summary-kill-same-subject}). - -@item M C -@kindex M C (Summary) -@findex gnus-summary-catchup -@c @icon{gnus-summary-catchup} -Mark all unread articles as read (@code{gnus-summary-catchup}). - -@item M C-c -@kindex M C-c (Summary) -@findex gnus-summary-catchup-all -Mark all articles in the group as read---even the ticked and dormant -articles (@code{gnus-summary-catchup-all}). - -@item M H -@kindex M H (Summary) -@findex gnus-summary-catchup-to-here -Catchup the current group to point (before the point) -(@code{gnus-summary-catchup-to-here}). - -@item M h -@kindex M h (Summary) -@findex gnus-summary-catchup-from-here -Catchup the current group from point (after the point) -(@code{gnus-summary-catchup-from-here}). - -@item C-w -@kindex C-w (Summary) -@findex gnus-summary-mark-region-as-read -Mark all articles between point and mark as read -(@code{gnus-summary-mark-region-as-read}). - -@item M V k -@kindex M V k (Summary) -@findex gnus-summary-kill-below -Kill all articles with scores below the default score (or below the -numeric prefix) (@code{gnus-summary-kill-below}). - -@item M e -@itemx E -@kindex M e (Summary) -@kindex E (Summary) -@findex gnus-summary-mark-as-expirable -Mark the current article as expirable -(@code{gnus-summary-mark-as-expirable}). - -@item M b -@kindex M b (Summary) -@findex gnus-summary-set-bookmark -Set a bookmark in the current article -(@code{gnus-summary-set-bookmark}). - -@item M B -@kindex M B (Summary) -@findex gnus-summary-remove-bookmark -Remove the bookmark from the current article -(@code{gnus-summary-remove-bookmark}). - -@item M V c -@kindex M V c (Summary) -@findex gnus-summary-clear-above -Clear all marks from articles with scores over the default score (or -over the numeric prefix) (@code{gnus-summary-clear-above}). - -@item M V u -@kindex M V u (Summary) -@findex gnus-summary-tick-above -Tick all articles with scores over the default score (or over the -numeric prefix) (@code{gnus-summary-tick-above}). - -@item M V m -@kindex M V m (Summary) -@findex gnus-summary-mark-above -Prompt for a mark, and mark all articles with scores over the default -score (or over the numeric prefix) with this mark -(@code{gnus-summary-clear-above}). -@end table - -@vindex gnus-summary-goto-unread -The @code{gnus-summary-goto-unread} variable controls what action should -be taken after setting a mark. If non-@code{nil}, point will move to -the next/previous unread article. If @code{nil}, point will just move -one line up or down. As a special case, if this variable is -@code{never}, all the marking commands as well as other commands (like -@kbd{SPACE}) will move to the next article, whether it is unread or not. -The default is @code{t}. - - -@node Generic Marking Commands -@subsection Generic Marking Commands - -Some people would like the command that ticks an article (@kbd{!}) go to -the next article. Others would like it to go to the next unread -article. Yet others would like it to stay on the current article. And -even though I haven't heard of anybody wanting it to go to the -previous (unread) article, I'm sure there are people that want that as -well. - -Multiply these five behaviors with five different marking commands, and -you get a potentially complex set of variable to control what each -command should do. - -To sidestep that mess, Gnus provides commands that do all these -different things. They can be found on the @kbd{M M} map in the summary -buffer. Type @kbd{M M C-h} to see them all---there are too many of them -to list in this manual. - -While you can use these commands directly, most users would prefer -altering the summary mode keymap. For instance, if you would like the -@kbd{!} command to go to the next article instead of the next unread -article, you could say something like: - -@lisp -@group -(add-hook 'gnus-summary-mode-hook 'my-alter-summary-map) -(defun my-alter-summary-map () - (local-set-key "!" 'gnus-summary-put-mark-as-ticked-next)) -@end group -@end lisp - -@noindent -or - -@lisp -(defun my-alter-summary-map () - (local-set-key "!" "MM!n")) -@end lisp - - -@node Setting Process Marks -@subsection Setting Process Marks -@cindex setting process marks - -Process marks are displayed as @code{#} in the summary buffer, and are -used for marking articles in such a way that other commands will -process these articles. For instance, if you process mark four -articles and then use the @kbd{*} command, Gnus will enter these four -articles into the cache. For more information, -@pxref{Process/Prefix}. - -@table @kbd - -@item M P p -@itemx # -@kindex # (Summary) -@kindex M P p (Summary) -@findex gnus-summary-mark-as-processable -Mark the current article with the process mark -(@code{gnus-summary-mark-as-processable}). -@findex gnus-summary-unmark-as-processable - -@item M P u -@itemx M-# -@kindex M P u (Summary) -@kindex M-# (Summary) -Remove the process mark, if any, from the current article -(@code{gnus-summary-unmark-as-processable}). - -@item M P U -@kindex M P U (Summary) -@findex gnus-summary-unmark-all-processable -Remove the process mark from all articles -(@code{gnus-summary-unmark-all-processable}). - -@item M P i -@kindex M P i (Summary) -@findex gnus-uu-invert-processable -Invert the list of process marked articles -(@code{gnus-uu-invert-processable}). - -@item M P R -@kindex M P R (Summary) -@findex gnus-uu-mark-by-regexp -Mark articles that have a @code{Subject} header that matches a regular -expression (@code{gnus-uu-mark-by-regexp}). - -@item M P G -@kindex M P G (Summary) -@findex gnus-uu-unmark-by-regexp -Unmark articles that have a @code{Subject} header that matches a regular -expression (@code{gnus-uu-unmark-by-regexp}). - -@item M P r -@kindex M P r (Summary) -@findex gnus-uu-mark-region -Mark articles in region (@code{gnus-uu-mark-region}). - -@item M P g -@kindex M P g (Summary) -@findex gnus-uu-unmark-region -Unmark articles in region (@code{gnus-uu-unmark-region}). - -@item M P t -@kindex M P t (Summary) -@findex gnus-uu-mark-thread -Mark all articles in the current (sub)thread -(@code{gnus-uu-mark-thread}). - -@item M P T -@kindex M P T (Summary) -@findex gnus-uu-unmark-thread -Unmark all articles in the current (sub)thread -(@code{gnus-uu-unmark-thread}). - -@item M P v -@kindex M P v (Summary) -@findex gnus-uu-mark-over -Mark all articles that have a score above the prefix argument -(@code{gnus-uu-mark-over}). - -@item M P s -@kindex M P s (Summary) -@findex gnus-uu-mark-series -Mark all articles in the current series (@code{gnus-uu-mark-series}). - -@item M P S -@kindex M P S (Summary) -@findex gnus-uu-mark-sparse -Mark all series that have already had some articles marked -(@code{gnus-uu-mark-sparse}). - -@item M P a -@kindex M P a (Summary) -@findex gnus-uu-mark-all -Mark all articles in series order (@code{gnus-uu-mark-all}). - -@item M P b -@kindex M P b (Summary) -@findex gnus-uu-mark-buffer -Mark all articles in the buffer in the order they appear -(@code{gnus-uu-mark-buffer}). - -@item M P k -@kindex M P k (Summary) -@findex gnus-summary-kill-process-mark -Push the current process mark set onto the stack and unmark all articles -(@code{gnus-summary-kill-process-mark}). - -@item M P y -@kindex M P y (Summary) -@findex gnus-summary-yank-process-mark -Pop the previous process mark set from the stack and restore it -(@code{gnus-summary-yank-process-mark}). - -@item M P w -@kindex M P w (Summary) -@findex gnus-summary-save-process-mark -Push the current process mark set onto the stack -(@code{gnus-summary-save-process-mark}). - -@end table - -Also see the @kbd{&} command in @ref{Searching for Articles}, for how to -set process marks based on article body contents. - - -@node Limiting -@section Limiting -@cindex limiting - -It can be convenient to limit the summary buffer to just show some -subset of the articles currently in the group. The effect most limit -commands have is to remove a few (or many) articles from the summary -buffer. - -Limiting commands work on subsets of the articles already fetched from -the servers. These commands don't query the server for additional -articles. - -@table @kbd - -@item / / -@itemx / s -@kindex / / (Summary) -@findex gnus-summary-limit-to-subject -Limit the summary buffer to articles that match some subject -(@code{gnus-summary-limit-to-subject}). If given a prefix, exclude -matching articles. - -@item / a -@kindex / a (Summary) -@findex gnus-summary-limit-to-author -Limit the summary buffer to articles that match some author -(@code{gnus-summary-limit-to-author}). If given a prefix, exclude -matching articles. - -@item / R -@kindex / R (Summary) -@findex gnus-summary-limit-to-recipient -Limit the summary buffer to articles that match some recipient -(@code{gnus-summary-limit-to-recipient}). If given a prefix, exclude -matching articles. - -@item / A -@kindex / A (Summary) -@findex gnus-summary-limit-to-address -Limit the summary buffer to articles in which contents of From, To or Cc -header match a given address (@code{gnus-summary-limit-to-address}). If -given a prefix, exclude matching articles. - -@item / S -@kindex / S (Summary) -@findex gnus-summary-limit-to-singletons -Limit the summary buffer to articles that aren't part of any displayed -threads (@code{gnus-summary-limit-to-singletons}). If given a prefix, -limit to articles that are part of displayed threads. - -@item / x -@kindex / x (Summary) -@findex gnus-summary-limit-to-extra -Limit the summary buffer to articles that match one of the ``extra'' -headers (@pxref{To From Newsgroups}) -(@code{gnus-summary-limit-to-extra}). If given a prefix, exclude -matching articles. - -@item / u -@itemx x -@kindex / u (Summary) -@kindex x (Summary) -@findex gnus-summary-limit-to-unread -Limit the summary buffer to articles not marked as read -(@code{gnus-summary-limit-to-unread}). If given a prefix, limit the -buffer to articles strictly unread. This means that ticked and -dormant articles will also be excluded. - -@item / m -@kindex / m (Summary) -@findex gnus-summary-limit-to-marks -Ask for a mark and then limit to all articles that have been marked -with that mark (@code{gnus-summary-limit-to-marks}). - -@item / t -@kindex / t (Summary) -@findex gnus-summary-limit-to-age -Ask for a number and then limit the summary buffer to articles older than (or equal to) that number of days -(@code{gnus-summary-limit-to-age}). If given a prefix, limit to -articles younger than that number of days. - -@item / n -@kindex / n (Summary) -@findex gnus-summary-limit-to-articles -With prefix @samp{n}, limit the summary buffer to the next @samp{n} -articles. If not given a prefix, use the process marked articles -instead. (@code{gnus-summary-limit-to-articles}). - -@item / w -@kindex / w (Summary) -@findex gnus-summary-pop-limit -Pop the previous limit off the stack and restore it -(@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off -the stack. - -@item / . -@kindex / . (Summary) -@findex gnus-summary-limit-to-unseen -Limit the summary buffer to the unseen articles -(@code{gnus-summary-limit-to-unseen}). - -@item / v -@kindex / v (Summary) -@findex gnus-summary-limit-to-score -Limit the summary buffer to articles that have a score at or above some -score (@code{gnus-summary-limit-to-score}). - -@item / p -@kindex / p (Summary) -@findex gnus-summary-limit-to-display-predicate -Limit the summary buffer to articles that satisfy the @code{display} -group parameter predicate -(@code{gnus-summary-limit-to-display-predicate}). @xref{Group -Parameters}, for more on this predicate. - -@item / r -@kindex / r (Summary) -@findex gnus-summary-limit-to-replied -Limit the summary buffer to replied articles -(@code{gnus-summary-limit-to-replied}). If given a prefix, exclude -replied articles. - -@item / E -@itemx M S -@kindex M S (Summary) -@kindex / E (Summary) -@findex gnus-summary-limit-include-expunged -Include all expunged articles in the limit -(@code{gnus-summary-limit-include-expunged}). - -@item / D -@kindex / D (Summary) -@findex gnus-summary-limit-include-dormant -Include all dormant articles in the limit -(@code{gnus-summary-limit-include-dormant}). - -@item / * -@kindex / * (Summary) -@findex gnus-summary-limit-include-cached -Include all cached articles in the limit -(@code{gnus-summary-limit-include-cached}). - -@item / d -@kindex / d (Summary) -@findex gnus-summary-limit-exclude-dormant -Exclude all dormant articles from the limit -(@code{gnus-summary-limit-exclude-dormant}). - -@item / M -@kindex / M (Summary) -@findex gnus-summary-limit-exclude-marks -Exclude all marked articles (@code{gnus-summary-limit-exclude-marks}). - -@item / T -@kindex / T (Summary) -@findex gnus-summary-limit-include-thread -Include all the articles in the current thread in the limit. - -@item / c -@kindex / c (Summary) -@findex gnus-summary-limit-exclude-childless-dormant -Exclude all dormant articles that have no children from the limit@* -(@code{gnus-summary-limit-exclude-childless-dormant}). - -@item / C -@kindex / C (Summary) -@findex gnus-summary-limit-mark-excluded-as-read -Mark all excluded unread articles as read -(@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix, -also mark excluded ticked and dormant articles as read. - -@item / b -@kindex / b (Summary) -@findex gnus-summary-limit-to-bodies -Limit the summary buffer to articles that have bodies that match a -certain regexp (@code{gnus-summary-limit-to-bodies}). If given a -prefix, reverse the limit. This command is quite slow since it -requires selecting each article to find the matches. - -@item / h -@kindex / h (Summary) -@findex gnus-summary-limit-to-headers -Like the previous command, only limit to headers instead -(@code{gnus-summary-limit-to-headers}). - -@end table - - -The following commands aren't limiting commands, but use the @kbd{/} -prefix as well. - -@table @kbd -@item / N -@kindex / N (Summary) -@findex gnus-summary-insert-new-articles -Insert all new articles in the summary buffer. It scans for new emails -if @var{back-end}@code{-get-new-mail} is non-@code{nil}. - -@item / o -@kindex / o (Summary) -@findex gnus-summary-insert-old-articles -Insert all old articles in the summary buffer. If given a numbered -prefix, fetch this number of articles. - -@end table - - -@node Threading -@section Threading -@cindex threading -@cindex article threading - -Gnus threads articles by default. @dfn{To thread} is to put responses -to articles directly after the articles they respond to---in a -hierarchical fashion. - -Threading is done by looking at the @code{References} headers of the -articles. In a perfect world, this would be enough to build pretty -trees, but unfortunately, the @code{References} header is often broken -or simply missing. Weird news propagation exacerbates the problem, -so one has to employ other heuristics to get pleasing results. A -plethora of approaches exists, as detailed in horrible detail in -@ref{Customizing Threading}. - -First, a quick overview of the concepts: - -@table @dfn -@item root -The top-most article in a thread; the first article in the thread. - -@item thread -A tree-like article structure. - -@item sub-thread -A small(er) section of this tree-like structure. - -@item loose threads -Threads often lose their roots due to article expiry, or due to the root -already having been read in a previous session, and not displayed in the -summary buffer. We then typically have many sub-threads that really -belong to one thread, but are without connecting roots. These are -called loose threads. - -@item thread gathering -An attempt to gather loose threads into bigger threads. - -@item sparse threads -A thread where the missing articles have been ``guessed'' at, and are -displayed as empty lines in the summary buffer. - -@end table - - -@menu -* Customizing Threading:: Variables you can change to affect the threading. -* Thread Commands:: Thread based commands in the summary buffer. -@end menu - - -@node Customizing Threading -@subsection Customizing Threading -@cindex customizing threading - -@menu -* Loose Threads:: How Gnus gathers loose threads into bigger threads. -* Filling In Threads:: Making the threads displayed look fuller. -* More Threading:: Even more variables for fiddling with threads. -* Low-Level Threading:: You thought it was over@dots{} but you were wrong! -@end menu - - -@node Loose Threads -@subsubsection Loose Threads -@cindex < -@cindex > -@cindex loose threads - -@table @code -@item gnus-summary-make-false-root -@vindex gnus-summary-make-false-root -If non-@code{nil}, Gnus will gather all loose subtrees into one big tree -and create a dummy root at the top. (Wait a minute. Root at the top? -Yup.) Loose subtrees occur when the real root has expired, or you've -read or killed the root in a previous session. - -When there is no real root of a thread, Gnus will have to fudge -something. This variable says what fudging method Gnus should use. -There are four possible values: - -@iftex -@iflatex -\gnusfigure{The Summary Buffer}{390}{ -\put(0,0){\epsfig{figure=ps/summary-adopt,width=7.5cm}} -\put(445,0){\makebox(0,0)[br]{\epsfig{figure=ps/summary-empty,width=7.5cm}}} -\put(0,400){\makebox(0,0)[tl]{\epsfig{figure=ps/summary-none,width=7.5cm}}} -\put(445,400){\makebox(0,0)[tr]{\epsfig{figure=ps/summary-dummy,width=7.5cm}}} -} -@end iflatex -@end iftex - -@cindex adopting articles - -@table @code - -@item adopt -Gnus will make the first of the orphaned articles the parent. This -parent will adopt all the other articles. The adopted articles will be -marked as such by pointy brackets (@samp{<>}) instead of the standard -square brackets (@samp{[]}). This is the default method. - -@item dummy -@vindex gnus-summary-dummy-line-format -@vindex gnus-summary-make-false-root-always -Gnus will create a dummy summary line that will pretend to be the -parent. This dummy line does not correspond to any real article, so -selecting it will just select the first real article after the dummy -article. @code{gnus-summary-dummy-line-format} is used to specify the -format of the dummy roots. It accepts only one format spec: @samp{S}, -which is the subject of the article. @xref{Formatting Variables}. -If you want all threads to have a dummy root, even the non-gathered -ones, set @code{gnus-summary-make-false-root-always} to @code{t}. - -@item empty -Gnus won't actually make any article the parent, but simply leave the -subject field of all orphans except the first empty. (Actually, it will -use @code{gnus-summary-same-subject} as the subject (@pxref{Summary -Buffer Format}).) - -@item none -Don't make any article parent at all. Just gather the threads and -display them after one another. - -@item nil -Don't gather loose threads. -@end table - -@item gnus-summary-gather-subject-limit -@vindex gnus-summary-gather-subject-limit -Loose threads are gathered by comparing subjects of articles. If this -variable is @code{nil}, Gnus requires an exact match between the -subjects of the loose threads before gathering them into one big -super-thread. This might be too strict a requirement, what with the -presence of stupid newsreaders that chop off long subject lines. If -you think so, set this variable to, say, 20 to require that only the -first 20 characters of the subjects have to match. If you set this -variable to a really low number, you'll find that Gnus will gather -everything in sight into one thread, which isn't very helpful. - -@cindex fuzzy article gathering -If you set this variable to the special value @code{fuzzy}, Gnus will -use a fuzzy string comparison algorithm on the subjects (@pxref{Fuzzy -Matching}). - -@item gnus-simplify-subject-fuzzy-regexp -@vindex gnus-simplify-subject-fuzzy-regexp -This can either be a regular expression or list of regular expressions -that match strings that will be removed from subjects if fuzzy subject -simplification is used. - -@item gnus-simplify-ignored-prefixes -@vindex gnus-simplify-ignored-prefixes -If you set @code{gnus-summary-gather-subject-limit} to something as low -as 10, you might consider setting this variable to something sensible: - -@c Written by Michael Ernst -@lisp -(setq gnus-simplify-ignored-prefixes - (concat - "\\`\\[?\\(" - (mapconcat - 'identity - '("looking" - "wanted" "followup" "summary\\( of\\)?" - "help" "query" "problem" "question" - "answer" "reference" "announce" - "How can I" "How to" "Comparison of" - ;; ... - ) - "\\|") - "\\)\\s *\\(" - (mapconcat 'identity - '("for" "for reference" "with" "about") - "\\|") - "\\)?\\]?:?[ \t]*")) -@end lisp - -All words that match this regexp will be removed before comparing two -subjects. - -@item gnus-simplify-subject-functions -@vindex gnus-simplify-subject-functions -If non-@code{nil}, this variable overrides -@code{gnus-summary-gather-subject-limit}. This variable should be a -list of functions to apply to the @code{Subject} string iteratively to -arrive at the simplified version of the string. - -Useful functions to put in this list include: - -@table @code -@item gnus-simplify-subject-re -@findex gnus-simplify-subject-re -Strip the leading @samp{Re:}. - -@item gnus-simplify-subject-fuzzy -@findex gnus-simplify-subject-fuzzy -Simplify fuzzily. - -@item gnus-simplify-whitespace -@findex gnus-simplify-whitespace -Remove excessive whitespace. - -@item gnus-simplify-all-whitespace -@findex gnus-simplify-all-whitespace -Remove all whitespace. -@end table - -You may also write your own functions, of course. - - -@item gnus-summary-gather-exclude-subject -@vindex gnus-summary-gather-exclude-subject -Since loose thread gathering is done on subjects only, that might lead -to many false hits, especially with certain common subjects like -@samp{} and @samp{(none)}. To make the situation slightly better, -you can use the regexp @code{gnus-summary-gather-exclude-subject} to say -what subjects should be excluded from the gathering process.@* -The default is @samp{^ *$\\|^(none)$}. - -@item gnus-summary-thread-gathering-function -@vindex gnus-summary-thread-gathering-function -Gnus gathers threads by looking at @code{Subject} headers. This means -that totally unrelated articles may end up in the same ``thread'', which -is confusing. An alternate approach is to look at all the -@code{Message-ID}s in all the @code{References} headers to find matches. -This will ensure that no gathered threads ever include unrelated -articles, but it also means that people who have posted with broken -newsreaders won't be gathered properly. The choice is yours---plague or -cholera: - -@table @code -@item gnus-gather-threads-by-subject -@findex gnus-gather-threads-by-subject -This function is the default gathering function and looks at -@code{Subject}s exclusively. - -@item gnus-gather-threads-by-references -@findex gnus-gather-threads-by-references -This function looks at @code{References} headers exclusively. -@end table - -If you want to test gathering by @code{References}, you could say -something like: - -@lisp -(setq gnus-summary-thread-gathering-function - 'gnus-gather-threads-by-references) -@end lisp - -@end table - - -@node Filling In Threads -@subsubsection Filling In Threads - -@table @code -@item gnus-fetch-old-headers -@vindex gnus-fetch-old-headers -If non-@code{nil}, Gnus will attempt to build old threads by fetching -more old headers---headers to articles marked as read. If you would -like to display as few summary lines as possible, but still connect as -many loose threads as possible, you should set this variable to -@code{some} or a number. If you set it to a number, no more than that -number of extra old headers will be fetched. In either case, fetching -old headers only works if the back end you are using carries overview -files---this would normally be @code{nntp}, @code{nnspool}, -@code{nnml}, and @code{nnmaildir}. Also remember that if the root of -the thread has been expired by the server, there's not much Gnus can -do about that. - -This variable can also be set to @code{invisible}. This won't have any -visible effects, but is useful if you use the @kbd{A T} command a lot -(@pxref{Finding the Parent}). - -The server has to support @acronym{NOV} for any of this to work. - -@cindex Gmane, gnus-fetch-old-headers -This feature can seriously impact performance it ignores all locally -cached header entries. Setting it to @code{t} for groups for a server -that doesn't expire articles (such as news.gmane.org), leads to very -slow summary generation. - -@item gnus-fetch-old-ephemeral-headers -@vindex gnus-fetch-old-ephemeral-headers -Same as @code{gnus-fetch-old-headers}, but only used for ephemeral -newsgroups. - -@item gnus-build-sparse-threads -@vindex gnus-build-sparse-threads -Fetching old headers can be slow. A low-rent similar effect can be -gotten by setting this variable to @code{some}. Gnus will then look at -the complete @code{References} headers of all articles and try to string -together articles that belong in the same thread. This will leave -@dfn{gaps} in the threading display where Gnus guesses that an article -is missing from the thread. (These gaps appear like normal summary -lines. If you select a gap, Gnus will try to fetch the article in -question.) If this variable is @code{t}, Gnus will display all these -``gaps'' without regard for whether they are useful for completing the -thread or not. Finally, if this variable is @code{more}, Gnus won't cut -off sparse leaf nodes that don't lead anywhere. This variable is -@code{nil} by default. - -@item gnus-read-all-available-headers -@vindex gnus-read-all-available-headers -This is a rather obscure variable that few will find useful. It's -intended for those non-news newsgroups where the back end has to fetch -quite a lot to present the summary buffer, and where it's impossible to -go back to parents of articles. This is mostly the case in the -web-based groups. - -If you don't use those, then it's safe to leave this as the default -@code{nil}. If you want to use this variable, it should be a regexp -that matches the group name, or @code{t} for all groups. - -@end table - - -@node More Threading -@subsubsection More Threading - -@table @code -@item gnus-show-threads -@vindex gnus-show-threads -If this variable is @code{nil}, no threading will be done, and all of -the rest of the variables here will have no effect. Turning threading -off will speed group selection up a bit, but it is sure to make reading -slower and more awkward. - -@item gnus-thread-hide-subtree -@vindex gnus-thread-hide-subtree -If non-@code{nil}, all threads will be hidden when the summary buffer is -generated. - -This can also be a predicate specifier (@pxref{Predicate Specifiers}). -Available predicates are @code{gnus-article-unread-p} and -@code{gnus-article-unseen-p}. - -Here's an example: - -@lisp -(setq gnus-thread-hide-subtree - '(or gnus-article-unread-p - gnus-article-unseen-p)) -@end lisp - -(It's a pretty nonsensical example, since all unseen articles are also -unread, but you get my drift.) - - -@item gnus-thread-expunge-below -@vindex gnus-thread-expunge-below -All threads that have a total score (as defined by -@code{gnus-thread-score-function}) less than this number will be -expunged. This variable is @code{nil} by default, which means that no -threads are expunged. - -@item gnus-thread-hide-killed -@vindex gnus-thread-hide-killed -if you kill a thread and this variable is non-@code{nil}, the subtree -will be hidden. - -@item gnus-thread-ignore-subject -@vindex gnus-thread-ignore-subject -Sometimes somebody changes the subject in the middle of a thread. If -this variable is non-@code{nil}, which is the default, the subject -change is ignored. If it is @code{nil}, a change in the subject will -result in a new thread. - -@item gnus-thread-indent-level -@vindex gnus-thread-indent-level -This is a number that says how much each sub-thread should be indented. -The default is 4. - -@item gnus-sort-gathered-threads-function -@vindex gnus-sort-gathered-threads-function -Sometimes, particularly with mailing lists, the order in which mails -arrive locally is not necessarily the same as the order in which they -arrived on the mailing list. Consequently, when sorting sub-threads -using the default @code{gnus-thread-sort-by-number}, responses can end -up appearing before the article to which they are responding to. -Setting this variable to an alternate value -(e.g. @code{gnus-thread-sort-by-date}), in a group's parameters or in an -appropriate hook (e.g. @code{gnus-summary-generate-hook}) can produce a -more logical sub-thread ordering in such instances. - -@end table - - -@node Low-Level Threading -@subsubsection Low-Level Threading - -@table @code - -@item gnus-parse-headers-hook -@vindex gnus-parse-headers-hook -Hook run before parsing any headers. - -@item gnus-alter-header-function -@vindex gnus-alter-header-function -If non-@code{nil}, this function will be called to allow alteration of -article header structures. The function is called with one parameter, -the article header vector, which it may alter in any way. For instance, -if you have a mail-to-news gateway which alters the @code{Message-ID}s -in systematic ways (by adding prefixes and such), you can use this -variable to un-scramble the @code{Message-ID}s so that they are more -meaningful. Here's one example: - -@lisp -(setq gnus-alter-header-function 'my-alter-message-id) - -(defun my-alter-message-id (header) - (let ((id (mail-header-id header))) - (when (string-match - "\\(<[^<>@@]*\\)\\.?cygnus\\..*@@\\([^<>@@]*>\\)" id) - (mail-header-set-id - (concat (match-string 1 id) "@@" (match-string 2 id)) - header)))) -@end lisp - -@end table - - -@node Thread Commands -@subsection Thread Commands -@cindex thread commands - -@table @kbd - -@item T k -@itemx C-M-k -@kindex T k (Summary) -@kindex C-M-k (Summary) -@findex gnus-summary-kill-thread -Mark all articles in the current (sub-)thread as read -(@code{gnus-summary-kill-thread}). If the prefix argument is positive, -remove all marks instead. If the prefix argument is negative, tick -articles instead. - -@item T l -@itemx C-M-l -@kindex T l (Summary) -@kindex C-M-l (Summary) -@findex gnus-summary-lower-thread -Lower the score of the current (sub-)thread -(@code{gnus-summary-lower-thread}). - -@item T i -@kindex T i (Summary) -@findex gnus-summary-raise-thread -Increase the score of the current (sub-)thread -(@code{gnus-summary-raise-thread}). - -@item T # -@kindex T # (Summary) -@findex gnus-uu-mark-thread -Set the process mark on the current (sub-)thread -(@code{gnus-uu-mark-thread}). - -@item T M-# -@kindex T M-# (Summary) -@findex gnus-uu-unmark-thread -Remove the process mark from the current (sub-)thread -(@code{gnus-uu-unmark-thread}). - -@item T T -@kindex T T (Summary) -@findex gnus-summary-toggle-threads -Toggle threading (@code{gnus-summary-toggle-threads}). - -@item T s -@kindex T s (Summary) -@findex gnus-summary-show-thread -Expose the (sub-)thread hidden under the current article, if any@* -(@code{gnus-summary-show-thread}). - -@item T h -@kindex T h (Summary) -@findex gnus-summary-hide-thread -Hide the current (sub-)thread (@code{gnus-summary-hide-thread}). - -@item T S -@kindex T S (Summary) -@findex gnus-summary-show-all-threads -Expose all hidden threads (@code{gnus-summary-show-all-threads}). - -@item T H -@kindex T H (Summary) -@findex gnus-summary-hide-all-threads -Hide all threads (@code{gnus-summary-hide-all-threads}). - -@item T t -@kindex T t (Summary) -@findex gnus-summary-rethread-current -Re-thread the current article's thread -(@code{gnus-summary-rethread-current}). This works even when the -summary buffer is otherwise unthreaded. - -@item T ^ -@kindex T ^ (Summary) -@findex gnus-summary-reparent-thread -Make the current article the child of the marked (or previous) article -(@code{gnus-summary-reparent-thread}). - -@item T M-^ -@kindex T M-^ (Summary) -@findex gnus-summary-reparent-children -Make the current article the parent of the marked articles -(@code{gnus-summary-reparent-children}). - -@end table - -The following commands are thread movement commands. They all -understand the numeric prefix. - -@table @kbd - -@item T n -@kindex T n (Summary) -@itemx C-M-f -@kindex C-M-n (Summary) -@itemx M-down -@kindex M-down (Summary) -@findex gnus-summary-next-thread -Go to the next thread (@code{gnus-summary-next-thread}). - -@item T p -@kindex T p (Summary) -@itemx C-M-b -@kindex C-M-p (Summary) -@itemx M-up -@kindex M-up (Summary) -@findex gnus-summary-prev-thread -Go to the previous thread (@code{gnus-summary-prev-thread}). - -@item T d -@kindex T d (Summary) -@findex gnus-summary-down-thread -Descend the thread (@code{gnus-summary-down-thread}). - -@item T u -@kindex T u (Summary) -@findex gnus-summary-up-thread -Ascend the thread (@code{gnus-summary-up-thread}). - -@item T o -@kindex T o (Summary) -@findex gnus-summary-top-thread -Go to the top of the thread (@code{gnus-summary-top-thread}). -@end table - -@vindex gnus-thread-operation-ignore-subject -If you ignore subject while threading, you'll naturally end up with -threads that have several different subjects in them. If you then issue -a command like @kbd{T k} (@code{gnus-summary-kill-thread}) you might not -wish to kill the entire thread, but just those parts of the thread that -have the same subject as the current article. If you like this idea, -you can fiddle with @code{gnus-thread-operation-ignore-subject}. If it -is non-@code{nil} (which it is by default), subjects will be ignored -when doing thread commands. If this variable is @code{nil}, articles in -the same thread with different subjects will not be included in the -operation in question. If this variable is @code{fuzzy}, only articles -that have subjects fuzzily equal will be included (@pxref{Fuzzy -Matching}). - - -@node Sorting the Summary Buffer -@section Sorting the Summary Buffer - -@findex gnus-thread-sort-by-total-score -@findex gnus-thread-sort-by-date -@findex gnus-thread-sort-by-score -@findex gnus-thread-sort-by-subject -@findex gnus-thread-sort-by-author -@findex gnus-thread-sort-by-recipient -@findex gnus-thread-sort-by-number -@findex gnus-thread-sort-by-random -@vindex gnus-thread-sort-functions -@findex gnus-thread-sort-by-most-recent-number -@findex gnus-thread-sort-by-most-recent-date -If you are using a threaded summary display, you can sort the threads by -setting @code{gnus-thread-sort-functions}, which can be either a single -function, a list of functions, or a list containing functions and -@code{(not some-function)} elements. - -By default, sorting is done on article numbers. Ready-made sorting -predicate functions include @code{gnus-thread-sort-by-number}, -@code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-recipient}, -@code{gnus-thread-sort-by-subject}, -@code{gnus-thread-sort-by-date}, -@code{gnus-thread-sort-by-score}, -@code{gnus-thread-sort-by-most-recent-number}, -@code{gnus-thread-sort-by-most-recent-date}, -@code{gnus-thread-sort-by-random} and -@code{gnus-thread-sort-by-total-score}. - -Each function takes two threads and returns non-@code{nil} if the first -thread should be sorted before the other. Note that sorting really is -normally done by looking only at the roots of each thread. Exceptions -to this rule are @code{gnus-thread-sort-by-most-recent-number} and -@code{gnus-thread-sort-by-most-recent-date}. - -If you use more than one function, the primary sort key should be the -last function in the list. You should probably always include -@code{gnus-thread-sort-by-number} in the list of sorting -functions---preferably first. This will ensure that threads that are -equal with respect to the other sort criteria will be displayed in -ascending article order. - -If you would like to sort by reverse score, then by subject, and finally -by number, you could do something like: - -@lisp -(setq gnus-thread-sort-functions - '(gnus-thread-sort-by-number - gnus-thread-sort-by-subject - (not gnus-thread-sort-by-total-score))) -@end lisp - -The threads that have highest score will be displayed first in the -summary buffer. When threads have the same score, they will be sorted -alphabetically. The threads that have the same score and the same -subject will be sorted by number, which is (normally) the sequence in -which the articles arrived. - -If you want to sort by score and then reverse arrival order, you could -say something like: - -@lisp -(setq gnus-thread-sort-functions - '((not gnus-thread-sort-by-number) - gnus-thread-sort-by-score)) -@end lisp - -@vindex gnus-thread-score-function -The function in the @code{gnus-thread-score-function} variable (default -@code{+}) is used for calculating the total score of a thread. Useful -functions might be @code{max}, @code{min}, or squared means, or whatever -tickles your fancy. - -@findex gnus-article-sort-functions -@findex gnus-article-sort-by-date -@findex gnus-article-sort-by-most-recent-date -@findex gnus-article-sort-by-score -@findex gnus-article-sort-by-subject -@findex gnus-article-sort-by-author -@findex gnus-article-sort-by-random -@findex gnus-article-sort-by-number -@findex gnus-article-sort-by-most-recent-number -If you are using an unthreaded display for some strange reason or -other, you have to fiddle with the @code{gnus-article-sort-functions} -variable. It is very similar to the -@code{gnus-thread-sort-functions}, except that it uses slightly -different functions for article comparison. Available sorting -predicate functions are @code{gnus-article-sort-by-number}, -@code{gnus-article-sort-by-author}, -@code{gnus-article-sort-by-subject}, @code{gnus-article-sort-by-date}, -@code{gnus-article-sort-by-random}, and -@code{gnus-article-sort-by-score}. - -If you want to sort an unthreaded summary display by subject, you could -say something like: - -@lisp -(setq gnus-article-sort-functions - '(gnus-article-sort-by-number - gnus-article-sort-by-subject)) -@end lisp - -You can define group specific sorting via @code{gnus-parameters}, -@xref{Group Parameters}. - - -@node Asynchronous Fetching -@section Asynchronous Article Fetching -@cindex asynchronous article fetching -@cindex article pre-fetch -@cindex pre-fetch - -If you read your news from an @acronym{NNTP} server that's far away, the -network latencies may make reading articles a chore. You have to wait -for a while after pressing @kbd{n} to go to the next article before the -article appears. Why can't Gnus just go ahead and fetch the article -while you are reading the previous one? Why not, indeed. - -First, some caveats. There are some pitfalls to using asynchronous -article fetching, especially the way Gnus does it. - -Let's say you are reading article 1, which is short, and article 2 is -quite long, and you are not interested in reading that. Gnus does not -know this, so it goes ahead and fetches article 2. You decide to read -article 3, but since Gnus is in the process of fetching article 2, the -connection is blocked. - -To avoid these situations, Gnus will open two (count 'em two) -connections to the server. Some people may think this isn't a very nice -thing to do, but I don't see any real alternatives. Setting up that -extra connection takes some time, so Gnus startup will be slower. - -Gnus will fetch more articles than you will read. This will mean that -the link between your machine and the @acronym{NNTP} server will become more -loaded than if you didn't use article pre-fetch. The server itself will -also become more loaded---both with the extra article requests, and the -extra connection. - -Ok, so now you know that you shouldn't really use this thing@dots{} unless -you really want to. - -@vindex gnus-asynchronous -Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should -happen automatically. - -@vindex gnus-use-article-prefetch -You can control how many articles are to be pre-fetched by setting -@code{gnus-use-article-prefetch}. This is 30 by default, which means -that when you read an article in the group, the back end will pre-fetch -the next 30 articles. If this variable is @code{t}, the back end will -pre-fetch all the articles it can without bound. If it is -@code{nil}, no pre-fetching will be done. - -@vindex gnus-async-prefetch-article-p -@findex gnus-async-unread-p -There are probably some articles that you don't want to pre-fetch---read -articles, for instance. The @code{gnus-async-prefetch-article-p} -variable controls whether an article is to be pre-fetched. This -function should return non-@code{nil} when the article in question is -to be pre-fetched. The default is @code{gnus-async-unread-p}, which -returns @code{nil} on read articles. The function is called with an -article data structure as the only parameter. - -If, for instance, you wish to pre-fetch only unread articles shorter -than 100 lines, you could say something like: - -@lisp -(defun my-async-short-unread-p (data) - "Return non-nil for short, unread articles." - (and (gnus-data-unread-p data) - (< (mail-header-lines (gnus-data-header data)) - 100))) - -(setq gnus-async-prefetch-article-p 'my-async-short-unread-p) -@end lisp - -These functions will be called many, many times, so they should -preferably be short and sweet to avoid slowing down Gnus too much. -It's probably a good idea to byte-compile things like this. - -@vindex gnus-async-post-fetch-function -@findex gnus-html-prefetch-images -After an article has been prefetched, this -@code{gnus-async-post-fetch-function} will be called. The buffer will -be narrowed to the region of the article that was fetched. A useful -value would be @code{gnus-html-prefetch-images}, which will prefetch -and store images referenced in the article, so that you don't have to -wait for them to be fetched when you read the article. This is useful -for @acronym{HTML} messages that have external images. - -@vindex gnus-prefetched-article-deletion-strategy -Articles have to be removed from the asynch buffer sooner or later. The -@code{gnus-prefetched-article-deletion-strategy} says when to remove -articles. This is a list that may contain the following elements: - -@table @code -@item read -Remove articles when they are read. - -@item exit -Remove articles when exiting the group. -@end table - -The default value is @code{(read exit)}. - -@c @vindex gnus-use-header-prefetch -@c If @code{gnus-use-header-prefetch} is non-@code{nil}, prefetch articles -@c from the next group. - - -@node Article Caching -@section Article Caching -@cindex article caching -@cindex caching - -If you have an @emph{extremely} slow @acronym{NNTP} connection, you may -consider turning article caching on. Each article will then be stored -locally under your home directory. As you may surmise, this could -potentially use @emph{huge} amounts of disk space, as well as eat up all -your inodes so fast it will make your head swim. In vodka. - -Used carefully, though, it could be just an easier way to save articles. - -@vindex gnus-use-long-file-name -@vindex gnus-cache-directory -@vindex gnus-use-cache -To turn caching on, set @code{gnus-use-cache} to @code{t}. By default, -all articles ticked or marked as dormant will then be copied -over to your local cache (@code{gnus-cache-directory}). Whether this -cache is flat or hierarchical is controlled by the -@code{gnus-use-long-file-name} variable, as usual. - -When re-selecting a ticked or dormant article, it will be fetched from the -cache instead of from the server. As articles in your cache will never -expire, this might serve as a method of saving articles while still -keeping them where they belong. Just mark all articles you want to save -as dormant, and don't worry. - -When an article is marked as read, is it removed from the cache. - -@vindex gnus-cache-remove-articles -@vindex gnus-cache-enter-articles -The entering/removal of articles from the cache is controlled by the -@code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles} -variables. Both are lists of symbols. The first is @code{(ticked -dormant)} by default, meaning that ticked and dormant articles will be -put in the cache. The latter is @code{(read)} by default, meaning that -articles marked as read are removed from the cache. Possibly -symbols in these two lists are @code{ticked}, @code{dormant}, -@code{unread} and @code{read}. - -@findex gnus-jog-cache -So where does the massive article-fetching and storing come into the -picture? The @code{gnus-jog-cache} command will go through all -subscribed newsgroups, request all unread articles, score them, and -store them in the cache. You should only ever, ever ever ever, use this -command if 1) your connection to the @acronym{NNTP} server is really, really, -really slow and 2) you have a really, really, really huge disk. -Seriously. One way to cut down on the number of articles downloaded is -to score unwanted articles down and have them marked as read. They will -not then be downloaded by this command. - -@vindex gnus-uncacheable-groups -@vindex gnus-cacheable-groups -It is likely that you do not want caching on all groups. For instance, -if your @code{nnml} mail is located under your home directory, it makes no -sense to cache it somewhere else under your home directory. Unless you -feel that it's neat to use twice as much space. - -To limit the caching, you could set @code{gnus-cacheable-groups} to a -regexp of groups to cache, @samp{^nntp} for instance, or set the -@code{gnus-uncacheable-groups} regexp to @samp{^nnml}, for instance. -Both variables are @code{nil} by default. If a group matches both -variables, the group is not cached. - -@findex gnus-cache-generate-nov-databases -@findex gnus-cache-generate-active -@vindex gnus-cache-active-file -The cache stores information on what articles it contains in its active -file (@code{gnus-cache-active-file}). If this file (or any other parts -of the cache) becomes all messed up for some reason or other, Gnus -offers two functions that will try to set things right. @kbd{M-x -gnus-cache-generate-nov-databases} will (re)build all the @acronym{NOV} -files, and @kbd{gnus-cache-generate-active} will (re)generate the active -file. - -@findex gnus-cache-move-cache -@code{gnus-cache-move-cache} will move your whole -@code{gnus-cache-directory} to some other location. You get asked to -where, isn't that cool? - -@node Persistent Articles -@section Persistent Articles -@cindex persistent articles - -Closely related to article caching, we have @dfn{persistent articles}. -In fact, it's just a different way of looking at caching, and much more -useful in my opinion. - -Say you're reading a newsgroup, and you happen on to some valuable gem -that you want to keep and treasure forever. You'd normally just save it -(using one of the many saving commands) in some file. The problem with -that is that it's just, well, yucky. Ideally you'd prefer just having -the article remain in the group where you found it forever; untouched by -the expiry going on at the news server. - -This is what a @dfn{persistent article} is---an article that just won't -be deleted. It's implemented using the normal cache functions, but -you use two explicit commands for managing persistent articles: - -@table @kbd - -@item * -@kindex * (Summary) -@findex gnus-cache-enter-article -Make the current article persistent (@code{gnus-cache-enter-article}). - -@item M-* -@kindex M-* (Summary) -@findex gnus-cache-remove-article -Remove the current article from the persistent articles -(@code{gnus-cache-remove-article}). This will normally delete the -article. -@end table - -Both these commands understand the process/prefix convention. - -To avoid having all ticked articles (and stuff) entered into the cache, -you should set @code{gnus-use-cache} to @code{passive} if you're just -interested in persistent articles: - -@lisp -(setq gnus-use-cache 'passive) -@end lisp - -@node Sticky Articles -@section Sticky Articles -@cindex sticky articles - -When you select an article the current article buffer will be reused -according to the value of the variable -@code{gnus-single-article-buffer}. If its value is non-@code{nil} (the -default) all articles reuse the same article buffer. Else each group -has its own article buffer. - -This implies that it's not possible to have more than one article buffer -in a group at a time. But sometimes you might want to display all the -latest emails from your mother, your father, your aunt, your uncle and -your 17 cousins to coordinate the next Christmas party. - -That's where sticky articles come in handy. A sticky article buffer -basically is a normal article buffer, but it won't be reused when you -select another article. You can make an article sticky with: - -@table @kbd -@item A S -@kindex A S (Summary) -@findex gnus-sticky-article -Make the current article sticky. If a prefix arg is given, ask for a -name for this sticky article buffer. -@end table - -To close a sticky article buffer you can use these commands: - -@table @kbd -@item q -@kindex q (Article) -@findex bury-buffer -Puts this sticky article buffer at the end of the list of all buffers. - -@item k -@kindex k (Article) -@findex gnus-kill-sticky-article-buffer -Kills this sticky article buffer. -@end table - -To kill all sticky article buffers you can use: - -@defun gnus-kill-sticky-article-buffers ARG -Kill all sticky article buffers. -If a prefix ARG is given, ask for confirmation. -@end defun - -@node Article Backlog -@section Article Backlog -@cindex backlog -@cindex article backlog - -If you have a slow connection, but the idea of using caching seems -unappealing to you (and it is, really), you can help the situation some -by switching on the @dfn{backlog}. This is where Gnus will buffer -already read articles so that it doesn't have to re-fetch articles -you've already read. This only helps if you are in the habit of -re-selecting articles you've recently read, of course. If you never do -that, turning the backlog on will slow Gnus down a little bit, and -increase memory usage some. - -@vindex gnus-keep-backlog -If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store -at most @var{n} old articles in a buffer for later re-fetching. If this -variable is non-@code{nil} and is not a number, Gnus will store -@emph{all} read articles, which means that your Emacs will grow without -bound before exploding and taking your machine down with you. I put -that in there just to keep y'all on your toes. - -The default value is 20. - - -@node Saving Articles -@section Saving Articles -@cindex saving articles - -Gnus can save articles in a number of ways. Below is the documentation -for saving articles in a fairly straight-forward fashion (i.e., little -processing of the article is done before it is saved). For a different -approach (uudecoding, unsharing) you should use @code{gnus-uu} -(@pxref{Decoding Articles}). - -For the commands listed here, the target is a file. If you want to -save to a group, see the @kbd{B c} (@code{gnus-summary-copy-article}) -command (@pxref{Mail Group Commands}). - -@vindex gnus-save-all-headers -If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete -unwanted headers before saving the article. - -@vindex gnus-saved-headers -If the preceding variable is @code{nil}, all headers that match the -@code{gnus-saved-headers} regexp will be kept, while the rest will be -deleted before saving. - -@table @kbd - -@item O o -@itemx o -@kindex O o (Summary) -@kindex o (Summary) -@findex gnus-summary-save-article -@c @icon{gnus-summary-save-article} -Save the current article using the default article saver -(@code{gnus-summary-save-article}). - -@item O m -@kindex O m (Summary) -@findex gnus-summary-save-article-mail -Save the current article in a Unix mail box (mbox) file -(@code{gnus-summary-save-article-mail}). - -@item O r -@kindex O r (Summary) -@findex gnus-summary-save-article-rmail -Save the current article in Rmail format -(@code{gnus-summary-save-article-rmail}). This is mbox since Emacs 23, -Babyl in older versions. - -@item O f -@kindex O f (Summary) -@findex gnus-summary-save-article-file -@c @icon{gnus-summary-save-article-file} -Save the current article in plain file format -(@code{gnus-summary-save-article-file}). - -@item O F -@kindex O F (Summary) -@findex gnus-summary-write-article-file -Write the current article in plain file format, overwriting any previous -file contents (@code{gnus-summary-write-article-file}). - -@item O b -@kindex O b (Summary) -@findex gnus-summary-save-article-body-file -Save the current article body in plain file format -(@code{gnus-summary-save-article-body-file}). - -@item O h -@kindex O h (Summary) -@findex gnus-summary-save-article-folder -Save the current article in mh folder format -(@code{gnus-summary-save-article-folder}). - -@item O v -@kindex O v (Summary) -@findex gnus-summary-save-article-vm -Save the current article in a VM folder -(@code{gnus-summary-save-article-vm}). - -@item O p -@itemx | -@kindex O p (Summary) -@kindex | (Summary) -@findex gnus-summary-pipe-output -@vindex gnus-summary-pipe-output-default-command -Save the current article in a pipe. Uhm, like, what I mean is---Pipe -the current article to a process (@code{gnus-summary-pipe-output}). -If given a symbolic prefix (@pxref{Symbolic Prefixes}), include the -complete headers in the piped output. The symbolic prefix @code{r} is -special; it lets this command pipe a raw article including all headers. -The @code{gnus-summary-pipe-output-default-command} variable can be set -to a string containing the default command and options (default -@code{nil}). - -@item O P -@kindex O P (Summary) -@findex gnus-summary-muttprint -@vindex gnus-summary-muttprint-program -Save the current article into muttprint. That is, print it using the -external program @uref{http://muttprint.sourceforge.net/, -Muttprint}. The program name and options to use is controlled by the -variable @code{gnus-summary-muttprint-program}. -(@code{gnus-summary-muttprint}). - -@end table - -@vindex gnus-prompt-before-saving -All these commands use the process/prefix convention -(@pxref{Process/Prefix}). If you save bunches of articles using these -functions, you might get tired of being prompted for files to save each -and every article in. The prompting action is controlled by -the @code{gnus-prompt-before-saving} variable, which is @code{always} by -default, giving you that excessive prompting action you know and -loathe. If you set this variable to @code{t} instead, you'll be prompted -just once for each series of articles you save. If you like to really -have Gnus do all your thinking for you, you can even set this variable -to @code{nil}, which means that you will never be prompted for files to -save articles in. Gnus will simply save all the articles in the default -files. - - -@vindex gnus-default-article-saver -You can customize the @code{gnus-default-article-saver} variable to make -Gnus do what you want it to. You can use any of the eight ready-made -functions below, or you can create your own. - -@table @code - -@item gnus-summary-save-in-rmail -@findex gnus-summary-save-in-rmail -@vindex gnus-rmail-save-name -@findex gnus-plain-save-name -This is the default format, that used by the Rmail package. Since Emacs -23, Rmail uses standard mbox format. Before this, it used the -@dfn{Babyl} format. Accordingly, this command writes mbox format since -Emacs 23, unless appending to an existing Babyl file. In older versions -of Emacs, it always uses Babyl format. Uses the function in the -@code{gnus-rmail-save-name} variable to get a file name to save the -article in. The default is @code{gnus-plain-save-name}. - -@item gnus-summary-save-in-mail -@findex gnus-summary-save-in-mail -@vindex gnus-mail-save-name -Save in a Unix mail (mbox) file. Uses the function in the -@code{gnus-mail-save-name} variable to get a file name to save the -article in. The default is @code{gnus-plain-save-name}. - -@item gnus-summary-save-in-file -@findex gnus-summary-save-in-file -@vindex gnus-file-save-name -@findex gnus-numeric-save-name -Append the article straight to an ordinary file. Uses the function in -the @code{gnus-file-save-name} variable to get a file name to save the -article in. The default is @code{gnus-numeric-save-name}. - -@item gnus-summary-write-to-file -@findex gnus-summary-write-to-file -Write the article straight to an ordinary file. The file is -overwritten if it exists. Uses the function in the -@code{gnus-file-save-name} variable to get a file name to save the -article in. The default is @code{gnus-numeric-save-name}. - -@item gnus-summary-save-body-in-file -@findex gnus-summary-save-body-in-file -Append the article body to an ordinary file. Uses the function in the -@code{gnus-file-save-name} variable to get a file name to save the -article in. The default is @code{gnus-numeric-save-name}. - -@item gnus-summary-write-body-to-file -@findex gnus-summary-write-body-to-file -Write the article body straight to an ordinary file. The file is -overwritten if it exists. Uses the function in the -@code{gnus-file-save-name} variable to get a file name to save the -article in. The default is @code{gnus-numeric-save-name}. - -@item gnus-summary-save-in-folder -@findex gnus-summary-save-in-folder -@findex gnus-folder-save-name -@findex gnus-Folder-save-name -@vindex gnus-folder-save-name -@cindex rcvstore -@cindex MH folders -Save the article to an MH folder using @code{rcvstore} from the MH -library. Uses the function in the @code{gnus-folder-save-name} variable -to get a file name to save the article in. The default is -@code{gnus-folder-save-name}, but you can also use -@code{gnus-Folder-save-name}, which creates capitalized names. - -@item gnus-summary-save-in-vm -@findex gnus-summary-save-in-vm -Save the article in a VM folder. You have to have the VM mail -reader to use this setting. - -@item gnus-summary-save-in-pipe -@findex gnus-summary-save-in-pipe -Pipe the article to a shell command. This function takes optional two -arguments COMMAND and RAW. Valid values for COMMAND include: - -@itemize @bullet -@item a string@* -The executable command name and possibly arguments. -@item @code{nil}@* -You will be prompted for the command in the minibuffer. -@item the symbol @code{default}@* -It will be replaced with the command which the variable -@code{gnus-summary-pipe-output-default-command} holds or the command -last used for saving. -@end itemize - -Non-@code{nil} value for RAW overrides @code{:decode} and -@code{:headers} properties (see below) and the raw article including all -headers will be piped. -@end table - -The symbol of each function may have the following properties: - -@table @code -@item :decode -The value non-@code{nil} means save decoded articles. This is -meaningful only with @code{gnus-summary-save-in-file}, -@code{gnus-summary-save-body-in-file}, -@code{gnus-summary-write-to-file}, -@code{gnus-summary-write-body-to-file}, and -@code{gnus-summary-save-in-pipe}. - -@item :function -The value specifies an alternative function which appends, not -overwrites, articles to a file. This implies that when saving many -articles at a time, @code{gnus-prompt-before-saving} is bound to -@code{t} and all articles are saved in a single file. This is -meaningful only with @code{gnus-summary-write-to-file} and -@code{gnus-summary-write-body-to-file}. - -@item :headers -The value specifies the symbol of a variable of which the value -specifies headers to be saved. If it is omitted, -@code{gnus-save-all-headers} and @code{gnus-saved-headers} control what -headers should be saved. -@end table - -@vindex gnus-article-save-directory -All of these functions, except for the last one, will save the article -in the @code{gnus-article-save-directory}, which is initialized from the -@env{SAVEDIR} environment variable. This is @file{~/News/} by -default. - -As you can see above, the functions use different functions to find a -suitable name of a file to save the article in. Below is a list of -available functions that generate names: - -@table @code - -@item gnus-Numeric-save-name -@findex gnus-Numeric-save-name -File names like @file{~/News/Alt.andrea-dworkin/45}. - -@item gnus-numeric-save-name -@findex gnus-numeric-save-name -File names like @file{~/News/alt.andrea-dworkin/45}. - -@item gnus-Plain-save-name -@findex gnus-Plain-save-name -File names like @file{~/News/Alt.andrea-dworkin}. - -@item gnus-plain-save-name -@findex gnus-plain-save-name -File names like @file{~/News/alt.andrea-dworkin}. - -@item gnus-sender-save-name -@findex gnus-sender-save-name -File names like @file{~/News/larsi}. -@end table - -@vindex gnus-split-methods -You can have Gnus suggest where to save articles by plonking a regexp into -the @code{gnus-split-methods} alist. For instance, if you would like to -save articles related to Gnus in the file @file{gnus-stuff}, and articles -related to VM in @file{vm-stuff}, you could set this variable to something -like: - -@lisp -(("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff") - ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff") - (my-choosing-function "../other-dir/my-stuff") - ((equal gnus-newsgroup-name "mail.misc") "mail-stuff")) -@end lisp - -We see that this is a list where each element is a list that has two -elements---the @dfn{match} and the @dfn{file}. The match can either be -a string (in which case it is used as a regexp to match on the article -head); it can be a symbol (which will be called as a function with the -group name as a parameter); or it can be a list (which will be -@code{eval}ed). If any of these actions have a non-@code{nil} result, -the @dfn{file} will be used as a default prompt. In addition, the -result of the operation itself will be used if the function or form -called returns a string or a list of strings. - -You basically end up with a list of file names that might be used when -saving the current article. (All ``matches'' will be used.) You will -then be prompted for what you really want to use as a name, with file -name completion over the results from applying this variable. - -This variable is @code{((gnus-article-archive-name))} by default, which -means that Gnus will look at the articles it saves for an -@code{Archive-name} line and use that as a suggestion for the file -name. - -Here's an example function to clean up file names somewhat. If you have -lots of mail groups called things like -@samp{nnml:mail.whatever}, you may want to chop off the beginning of -these group names before creating the file name to save to. The -following will do just that: - -@lisp -(defun my-save-name (group) - (when (string-match "^nnml:mail." group) - (substring group (match-end 0)))) - -(setq gnus-split-methods - '((gnus-article-archive-name) - (my-save-name))) -@end lisp - - -@vindex gnus-use-long-file-name -Finally, you have the @code{gnus-use-long-file-name} variable. If it is -@code{nil}, all the preceding functions will replace all periods -(@samp{.}) in the group names with slashes (@samp{/})---which means that -the functions will generate hierarchies of directories instead of having -all the files in the top level directory -(@file{~/News/alt/andrea-dworkin} instead of -@file{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default -on most systems. However, for historical reasons, this is @code{nil} on -Xenix and usg-unix-v machines by default. - -This function also affects kill and score file names. If this variable -is a list, and the list contains the element @code{not-score}, long file -names will not be used for score files, if it contains the element -@code{not-save}, long file names will not be used for saving, and if it -contains the element @code{not-kill}, long file names will not be used -for kill files. - -If you'd like to save articles in a hierarchy that looks something like -a spool, you could - -@lisp -(setq gnus-use-long-file-name '(not-save)) ; @r{to get a hierarchy} -(setq gnus-default-article-saver - 'gnus-summary-save-in-file) ; @r{no encoding} -@end lisp - -Then just save with @kbd{o}. You'd then read this hierarchy with -ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and -the top level directory as the argument (@file{~/News/}). Then just walk -around to the groups/directories with @code{nneething}. - - -@node Decoding Articles -@section Decoding Articles -@cindex decoding articles - -Sometime users post articles (or series of articles) that have been -encoded in some way or other. Gnus can decode them for you. - -@menu -* Uuencoded Articles:: Uudecode articles. -* Shell Archives:: Unshar articles. -* PostScript Files:: Split PostScript. -* Other Files:: Plain save and binhex. -* Decoding Variables:: Variables for a happy decoding. -* Viewing Files:: You want to look at the result of the decoding? -@end menu - -@cindex series -@cindex article series -All these functions use the process/prefix convention -(@pxref{Process/Prefix}) for finding out what articles to work on, with -the extension that a ``single article'' means ``a single series''. Gnus -can find out by itself what articles belong to a series, decode all the -articles and unpack/view/save the resulting file(s). - -Gnus guesses what articles are in the series according to the following -simplish rule: The subjects must be (nearly) identical, except for the -last two numbers of the line. (Spaces are largely ignored, however.) - -For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus -will find all the articles that match the regexp @samp{^cat.gif -([0-9]+/[0-9]+).*$}. - -Subjects that are non-standard, like @samp{cat.gif (2/3) Part 6 of a -series}, will not be properly recognized by any of the automatic viewing -commands, and you have to mark the articles manually with @kbd{#}. - - -@node Uuencoded Articles -@subsection Uuencoded Articles -@cindex uudecode -@cindex uuencoded articles - -@table @kbd - -@item X u -@kindex X u (Summary) -@findex gnus-uu-decode-uu -@c @icon{gnus-uu-decode-uu} -Uudecodes the current series (@code{gnus-uu-decode-uu}). - -@item X U -@kindex X U (Summary) -@findex gnus-uu-decode-uu-and-save -Uudecodes and saves the current series -(@code{gnus-uu-decode-uu-and-save}). - -@item X v u -@kindex X v u (Summary) -@findex gnus-uu-decode-uu-view -Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}). - -@item X v U -@kindex X v U (Summary) -@findex gnus-uu-decode-uu-and-save-view -Uudecodes, views and saves the current series -(@code{gnus-uu-decode-uu-and-save-view}). - -@end table - -Remember that these all react to the presence of articles marked with -the process mark. If, for instance, you'd like to decode and save an -entire newsgroup, you'd typically do @kbd{M P a} -(@code{gnus-uu-mark-all}) and then @kbd{X U} -(@code{gnus-uu-decode-uu-and-save}). - -All this is very much different from how @code{gnus-uu} worked with -@sc{gnus 4.1}, where you had explicit keystrokes for everything under -the sun. This version of @code{gnus-uu} generally assumes that you mark -articles in some way (@pxref{Setting Process Marks}) and then press -@kbd{X u}. - -@vindex gnus-uu-notify-files -Note: When trying to decode articles that have names matching -@code{gnus-uu-notify-files}, which is hard-coded to -@samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will -automatically post an article on @samp{comp.unix.wizards} saying that -you have just viewed the file in question. This feature can't be turned -off. - - -@node Shell Archives -@subsection Shell Archives -@cindex unshar -@cindex shell archives -@cindex shared articles - -Shell archives (``shar files'') used to be a popular way to distribute -sources, but it isn't used all that much today. In any case, we have -some commands to deal with these: - -@table @kbd - -@item X s -@kindex X s (Summary) -@findex gnus-uu-decode-unshar -Unshars the current series (@code{gnus-uu-decode-unshar}). - -@item X S -@kindex X S (Summary) -@findex gnus-uu-decode-unshar-and-save -Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}). - -@item X v s -@kindex X v s (Summary) -@findex gnus-uu-decode-unshar-view -Unshars and views the current series (@code{gnus-uu-decode-unshar-view}). - -@item X v S -@kindex X v S (Summary) -@findex gnus-uu-decode-unshar-and-save-view -Unshars, views and saves the current series -(@code{gnus-uu-decode-unshar-and-save-view}). -@end table - - -@node PostScript Files -@subsection PostScript Files -@cindex PostScript - -@table @kbd - -@item X p -@kindex X p (Summary) -@findex gnus-uu-decode-postscript -Unpack the current PostScript series (@code{gnus-uu-decode-postscript}). - -@item X P -@kindex X P (Summary) -@findex gnus-uu-decode-postscript-and-save -Unpack and save the current PostScript series -(@code{gnus-uu-decode-postscript-and-save}). - -@item X v p -@kindex X v p (Summary) -@findex gnus-uu-decode-postscript-view -View the current PostScript series -(@code{gnus-uu-decode-postscript-view}). - -@item X v P -@kindex X v P (Summary) -@findex gnus-uu-decode-postscript-and-save-view -View and save the current PostScript series -(@code{gnus-uu-decode-postscript-and-save-view}). -@end table - - -@node Other Files -@subsection Other Files - -@table @kbd -@item X o -@kindex X o (Summary) -@findex gnus-uu-decode-save -Save the current series -(@code{gnus-uu-decode-save}). - -@item X b -@kindex X b (Summary) -@findex gnus-uu-decode-binhex -Unbinhex the current series (@code{gnus-uu-decode-binhex}). This -doesn't really work yet. - -@item X Y -@kindex X Y (Summary) -@findex gnus-uu-decode-yenc -yEnc-decode the current series and save it (@code{gnus-uu-decode-yenc}). -@end table - - -@node Decoding Variables -@subsection Decoding Variables - -Adjective, not verb. - -@menu -* Rule Variables:: Variables that say how a file is to be viewed. -* Other Decode Variables:: Other decode variables. -* Uuencoding and Posting:: Variables for customizing uuencoding. -@end menu - - -@node Rule Variables -@subsubsection Rule Variables -@cindex rule variables - -Gnus uses @dfn{rule variables} to decide how to view a file. All these -variables are of the form - -@lisp - (list '(regexp1 command2) - '(regexp2 command2) - ...) -@end lisp - -@table @code - -@item gnus-uu-user-view-rules -@vindex gnus-uu-user-view-rules -@cindex sox -This variable is consulted first when viewing files. If you wish to use, -for instance, @code{sox} to convert an @file{.au} sound file, you could -say something like: -@lisp -(setq gnus-uu-user-view-rules - (list '("\\\\.au$" "sox %s -t .aiff > /dev/audio"))) -@end lisp - -@item gnus-uu-user-view-rules-end -@vindex gnus-uu-user-view-rules-end -This variable is consulted if Gnus couldn't make any matches from the -user and default view rules. - -@item gnus-uu-user-archive-rules -@vindex gnus-uu-user-archive-rules -This variable can be used to say what commands should be used to unpack -archives. -@end table - - -@node Other Decode Variables -@subsubsection Other Decode Variables - -@table @code -@vindex gnus-uu-grabbed-file-functions - -@item gnus-uu-grabbed-file-functions -All functions in this list will be called right after each file has been -successfully decoded---so that you can move or view files right away, -and don't have to wait for all files to be decoded before you can do -anything. Ready-made functions you can put in this list are: - -@table @code - -@item gnus-uu-grab-view -@findex gnus-uu-grab-view -View the file. - -@item gnus-uu-grab-move -@findex gnus-uu-grab-move -Move the file (if you're using a saving function.) -@end table - -@item gnus-uu-be-dangerous -@vindex gnus-uu-be-dangerous -Specifies what to do if unusual situations arise during decoding. If -@code{nil}, be as conservative as possible. If @code{t}, ignore things -that didn't work, and overwrite existing files. Otherwise, ask each -time. - -@item gnus-uu-ignore-files-by-name -@vindex gnus-uu-ignore-files-by-name -Files with name matching this regular expression won't be viewed. - -@item gnus-uu-ignore-files-by-type -@vindex gnus-uu-ignore-files-by-type -Files with a @acronym{MIME} type matching this variable won't be viewed. -Note that Gnus tries to guess what type the file is based on the name. -@code{gnus-uu} is not a @acronym{MIME} package (yet), so this is slightly -kludgy. - -@item gnus-uu-tmp-dir -@vindex gnus-uu-tmp-dir -Where @code{gnus-uu} does its work. - -@item gnus-uu-do-not-unpack-archives -@vindex gnus-uu-do-not-unpack-archives -Non-@code{nil} means that @code{gnus-uu} won't peek inside archives -looking for files to display. - -@item gnus-uu-view-and-save -@vindex gnus-uu-view-and-save -Non-@code{nil} means that the user will always be asked to save a file -after viewing it. - -@item gnus-uu-ignore-default-view-rules -@vindex gnus-uu-ignore-default-view-rules -Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing -rules. - -@item gnus-uu-ignore-default-archive-rules -@vindex gnus-uu-ignore-default-archive-rules -Non-@code{nil} means that @code{gnus-uu} will ignore the default archive -unpacking commands. - -@item gnus-uu-kill-carriage-return -@vindex gnus-uu-kill-carriage-return -Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns -from articles. - -@item gnus-uu-unmark-articles-not-decoded -@vindex gnus-uu-unmark-articles-not-decoded -Non-@code{nil} means that @code{gnus-uu} will mark unsuccessfully -decoded articles as unread. - -@item gnus-uu-correct-stripped-uucode -@vindex gnus-uu-correct-stripped-uucode -Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix -uuencoded files that have had trailing spaces deleted. - -@item gnus-uu-pre-uudecode-hook -@vindex gnus-uu-pre-uudecode-hook -Hook run before sending a message to @code{uudecode}. - -@item gnus-uu-view-with-metamail -@vindex gnus-uu-view-with-metamail -@cindex metamail -Non-@code{nil} means that @code{gnus-uu} will ignore the viewing -commands defined by the rule variables and just fudge a @acronym{MIME} -content type based on the file name. The result will be fed to -@code{metamail} for viewing. - -@item gnus-uu-save-in-digest -@vindex gnus-uu-save-in-digest -Non-@code{nil} means that @code{gnus-uu}, when asked to save without -decoding, will save in digests. If this variable is @code{nil}, -@code{gnus-uu} will just save everything in a file without any -embellishments. The digesting almost conforms to RFC 1153---no easy way -to specify any meaningful volume and issue numbers were found, so I -simply dropped them. - -@end table - - -@node Uuencoding and Posting -@subsubsection Uuencoding and Posting - -@table @code - -@item gnus-uu-post-include-before-composing -@vindex gnus-uu-post-include-before-composing -Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode -before you compose the article. If this variable is @code{t}, you can -either include an encoded file with @kbd{C-c C-i} or have one included -for you when you post the article. - -@item gnus-uu-post-length -@vindex gnus-uu-post-length -Maximum length of an article. The encoded file will be split into how -many articles it takes to post the entire file. - -@item gnus-uu-post-threaded -@vindex gnus-uu-post-threaded -Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a -thread. This may not be smart, as no other decoder I have seen is able -to follow threads when collecting uuencoded articles. (Well, I have -seen one package that does that---@code{gnus-uu}, but somehow, I don't -think that counts@dots{}) Default is @code{nil}. - -@item gnus-uu-post-separate-description -@vindex gnus-uu-post-separate-description -Non-@code{nil} means that the description will be posted in a separate -article. The first article will typically be numbered (0/x). If this -variable is @code{nil}, the description the user enters will be included -at the beginning of the first article, which will be numbered (1/x). -Default is @code{t}. - -@end table - - -@node Viewing Files -@subsection Viewing Files -@cindex viewing files -@cindex pseudo-articles - -After decoding, if the file is some sort of archive, Gnus will attempt -to unpack the archive and see if any of the files in the archive can be -viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz} -containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will -uncompress and de-tar the main file, and then view the two pictures. -This unpacking process is recursive, so if the archive contains archives -of archives, it'll all be unpacked. - -Finally, Gnus will normally insert a @dfn{pseudo-article} for each -extracted file into the summary buffer. If you go to these -``articles'', you will be prompted for a command to run (usually Gnus -will make a suggestion), and then the command will be run. - -@vindex gnus-view-pseudo-asynchronously -If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait -until the viewing is done before proceeding. - -@vindex gnus-view-pseudos -If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert -the pseudo-articles into the summary buffer, but view them -immediately. If this variable is @code{not-confirm}, the user won't even -be asked for a confirmation before viewing is done. - -@vindex gnus-view-pseudos-separately -If @code{gnus-view-pseudos-separately} is non-@code{nil}, one -pseudo-article will be created for each file to be viewed. If -@code{nil}, all files that use the same viewing command will be given as -a list of parameters to that command. - -@vindex gnus-insert-pseudo-articles -If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert -pseudo-articles when decoding. It is @code{t} by default. - -So; there you are, reading your @emph{pseudo-articles} in your -@emph{virtual newsgroup} from the @emph{virtual server}; and you think: -Why isn't anything real anymore? How did we get here? - - -@node Article Treatment -@section Article Treatment - -Reading through this huge manual, you may have quite forgotten that the -object of newsreaders is to actually, like, read what people have -written. Reading articles. Unfortunately, people are quite bad at -writing, so there are tons of functions and variables to make reading -these articles easier. - -@menu -* Article Highlighting:: You want to make the article look like fruit salad. -* Article Fontisizing:: Making emphasized text look nice. -* Article Hiding:: You also want to make certain info go away. -* Article Washing:: Lots of way-neat functions to make life better. -* Article Header:: Doing various header transformations. -* Article Buttons:: Click on URLs, Message-IDs, addresses and the like. -* Article Button Levels:: Controlling appearance of buttons. -* Article Date:: Grumble, UT! -* Article Display:: Display various stuff: - X-Face, Picons, Gravatars, Smileys. -* Article Signature:: What is a signature? -* Article Miscellanea:: Various other stuff. -@end menu - - -@node Article Highlighting -@subsection Article Highlighting -@cindex highlighting - -Not only do you want your article buffer to look like fruit salad, but -you want it to look like technicolor fruit salad. - -@table @kbd - -@item W H a -@kindex W H a (Summary) -@findex gnus-article-highlight -@findex gnus-article-maybe-highlight -Do much highlighting of the current article -(@code{gnus-article-highlight}). This function highlights header, cited -text, the signature, and adds buttons to the body and the head. - -@item W H h -@kindex W H h (Summary) -@findex gnus-article-highlight-headers -@vindex gnus-header-face-alist -Highlight the headers (@code{gnus-article-highlight-headers}). The -highlighting will be done according to the @code{gnus-header-face-alist} -variable, which is a list where each element has the form -@code{(@var{regexp} @var{name} @var{content})}. -@var{regexp} is a regular expression for matching the -header, @var{name} is the face used for highlighting the header name -(@pxref{Faces and Fonts}) and @var{content} is the face for highlighting -the header value. The first match made will be used. Note that -@var{regexp} shouldn't have @samp{^} prepended---Gnus will add one. - -@item W H c -@kindex W H c (Summary) -@findex gnus-article-highlight-citation -Highlight cited text (@code{gnus-article-highlight-citation}). - -Some variables to customize the citation highlights: - -@table @code -@vindex gnus-cite-parse-max-size - -@item gnus-cite-parse-max-size -If the article size in bytes is bigger than this variable (which is -25000 by default), no citation highlighting will be performed. - -@item gnus-cite-max-prefix -@vindex gnus-cite-max-prefix -Maximum possible length for a citation prefix (default 20). - -@item gnus-cite-face-list -@vindex gnus-cite-face-list -List of faces used for highlighting citations (@pxref{Faces and Fonts}). -When there are citations from multiple articles in the same message, -Gnus will try to give each citation from each article its own face. -This should make it easier to see who wrote what. - -@item gnus-supercite-regexp -@vindex gnus-supercite-regexp -Regexp matching normal Supercite attribution lines. - -@item gnus-supercite-secondary-regexp -@vindex gnus-supercite-secondary-regexp -Regexp matching mangled Supercite attribution lines. - -@item gnus-cite-minimum-match-count -@vindex gnus-cite-minimum-match-count -Minimum number of identical prefixes we have to see before we believe -that it's a citation. - -@item gnus-cite-attribution-prefix -@vindex gnus-cite-attribution-prefix -Regexp matching the beginning of an attribution line. - -@item gnus-cite-attribution-suffix -@vindex gnus-cite-attribution-suffix -Regexp matching the end of an attribution line. - -@item gnus-cite-attribution-face -@vindex gnus-cite-attribution-face -Face used for attribution lines. It is merged with the face for the -cited text belonging to the attribution. - -@item gnus-cite-ignore-quoted-from -@vindex gnus-cite-ignore-quoted-from -If non-@code{nil}, no citation highlighting will be performed on lines -beginning with @samp{>From }. Those lines may have been quoted by MTAs -in order not to mix up with the envelope From line. The default value -is @code{t}. - -@end table - - -@item W H s -@kindex W H s (Summary) -@vindex gnus-signature-separator -@vindex gnus-signature-face -@findex gnus-article-highlight-signature -Highlight the signature (@code{gnus-article-highlight-signature}). -Everything after @code{gnus-signature-separator} (@pxref{Article -Signature}) in an article will be considered a signature and will be -highlighted with @code{gnus-signature-face}, which is @code{italic} by -default. - -@end table - -@xref{Customizing Articles}, for how to highlight articles automatically. - - -@node Article Fontisizing -@subsection Article Fontisizing -@cindex emphasis -@cindex article emphasis - -@findex gnus-article-emphasize -@kindex W e (Summary) -People commonly add emphasis to words in news articles by writing things -like @samp{_this_} or @samp{*this*} or @samp{/this/}. Gnus can make -this look nicer by running the article through the @kbd{W e} -(@code{gnus-article-emphasize}) command. - -@vindex gnus-emphasis-alist -How the emphasis is computed is controlled by the -@code{gnus-emphasis-alist} variable. This is an alist where the first -element is a regular expression to be matched. The second is a number -that says what regular expression grouping is used to find the entire -emphasized word. The third is a number that says what regexp grouping -should be displayed and highlighted. (The text between these two -groupings will be hidden.) The fourth is the face used for -highlighting. - -@lisp -(setq gnus-emphasis-alist - '(("_\\(\\w+\\)_" 0 1 gnus-emphasis-underline) - ("\\*\\(\\w+\\)\\*" 0 1 gnus-emphasis-bold))) -@end lisp - -@cindex slash -@cindex asterisk -@cindex underline -@cindex / -@cindex * - -@vindex gnus-emphasis-underline -@vindex gnus-emphasis-bold -@vindex gnus-emphasis-italic -@vindex gnus-emphasis-underline-bold -@vindex gnus-emphasis-underline-italic -@vindex gnus-emphasis-bold-italic -@vindex gnus-emphasis-underline-bold-italic -By default, there are seven rules, and they use the following faces: -@code{gnus-emphasis-bold}, @code{gnus-emphasis-italic}, -@code{gnus-emphasis-underline}, @code{gnus-emphasis-bold-italic}, -@code{gnus-emphasis-underline-italic}, -@code{gnus-emphasis-underline-bold}, and -@code{gnus-emphasis-underline-bold-italic}. - -If you want to change these faces, you can either use @kbd{M-x -customize}, or you can use @code{copy-face}. For instance, if you want -to make @code{gnus-emphasis-italic} use a red face instead, you could -say something like: - -@lisp -(copy-face 'red 'gnus-emphasis-italic) -@end lisp - -@vindex gnus-group-highlight-words-alist - -If you want to highlight arbitrary words, you can use the -@code{gnus-group-highlight-words-alist} variable, which uses the same -syntax as @code{gnus-emphasis-alist}. The @code{highlight-words} group -parameter (@pxref{Group Parameters}) can also be used. - -@xref{Customizing Articles}, for how to fontize articles automatically. - - -@node Article Hiding -@subsection Article Hiding -@cindex article hiding - -Or rather, hiding certain things in each article. There usually is much -too much cruft in most articles. - -@table @kbd - -@item W W a -@kindex W W a (Summary) -@findex gnus-article-hide -Do quite a lot of hiding on the article buffer -(@kbd{gnus-article-hide}). In particular, this function will hide -headers, @acronym{PGP}, cited text and the signature. - -@item W W h -@kindex W W h (Summary) -@findex gnus-article-hide-headers -Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding -Headers}. - -@item W W b -@kindex W W b (Summary) -@findex gnus-article-hide-boring-headers -Hide headers that aren't particularly interesting -(@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}. - -@item W W s -@kindex W W s (Summary) -@findex gnus-article-hide-signature -Hide signature (@code{gnus-article-hide-signature}). @xref{Article -Signature}. - -@item W W l -@kindex W W l (Summary) -@findex gnus-article-hide-list-identifiers -@vindex gnus-list-identifiers -Strip list identifiers specified in @code{gnus-list-identifiers}. These -are strings some mailing list servers add to the beginning of all -@code{Subject} headers---for example, @samp{[zebra 4711]}. Any leading -@samp{Re: } is skipped before stripping. @code{gnus-list-identifiers} -may not contain @code{\\(..\\)}. - -@table @code - -@item gnus-list-identifiers -@vindex gnus-list-identifiers -A regular expression that matches list identifiers to be removed from -subject. This can also be a list of regular expressions. - -@end table - -@item W W P -@kindex W W P (Summary) -@findex gnus-article-hide-pem -Hide @acronym{PEM} (privacy enhanced messages) cruft -(@code{gnus-article-hide-pem}). - -@item W W B -@kindex W W B (Summary) -@findex gnus-article-strip-banner -@vindex gnus-article-banner-alist -@vindex gnus-article-address-banner-alist -@cindex banner -@cindex OneList -@cindex stripping advertisements -@cindex advertisements -Strip the banner specified by the @code{banner} group parameter -(@code{gnus-article-strip-banner}). This is mainly used to hide those -annoying banners and/or signatures that some mailing lists and moderated -groups adds to all the messages. The way to use this function is to add -the @code{banner} group parameter (@pxref{Group Parameters}) to the -group you want banners stripped from. The parameter either be a string, -which will be interpreted as a regular expression matching text to be -removed, or the symbol @code{signature}, meaning that the (last) -signature should be removed, or other symbol, meaning that the -corresponding regular expression in @code{gnus-article-banner-alist} is -used. - -For instance: - -@lisp -(setq gnus-article-banner-alist - ((googleGroups . - "^\n*--~--~---------\\(.+\n\\)+"))) -@end lisp - -Regardless of a group, you can hide things like advertisements only when -the sender of an article has a certain mail address specified in -@code{gnus-article-address-banner-alist}. - -@table @code - -@item gnus-article-address-banner-alist -@vindex gnus-article-address-banner-alist -Alist of mail addresses and banners. Each element has the form -@code{(@var{address} . @var{banner})}, where @var{address} is a regexp -matching a mail address in the From header, @var{banner} is one of a -symbol @code{signature}, an item in @code{gnus-article-banner-alist}, -a regexp and @code{nil}. If @var{address} matches author's mail -address, it will remove things like advertisements. For example, if a -sender has the mail address @samp{hail@@yoo-hoo.co.jp} and there is a -banner something like @samp{Do You Yoo-hoo!?} in all articles he -sends, you can use the following element to remove them: - -@lisp -("@@yoo-hoo\\.co\\.jp\\'" . - "\n_+\nDo You Yoo-hoo!\\?\n.*\n.*\n") -@end lisp - -@end table - -@item W W c -@kindex W W c (Summary) -@findex gnus-article-hide-citation -Hide citation (@code{gnus-article-hide-citation}). Some variables for -customizing the hiding: - -@table @code - -@item gnus-cited-opened-text-button-line-format -@itemx gnus-cited-closed-text-button-line-format -@vindex gnus-cited-closed-text-button-line-format -@vindex gnus-cited-opened-text-button-line-format -Gnus adds buttons to show where the cited text has been hidden, and to -allow toggle hiding the text. The format of the variable is specified -by these format-like variable (@pxref{Formatting Variables}). These -specs are valid: - -@table @samp -@item b -Starting point of the hidden text. -@item e -Ending point of the hidden text. -@item l -Number of characters in the hidden region. -@item n -Number of lines of hidden text. -@end table - -@item gnus-cited-lines-visible -@vindex gnus-cited-lines-visible -The number of lines at the beginning of the cited text to leave -shown. This can also be a cons cell with the number of lines at the top -and bottom of the text, respectively, to remain visible. - -@end table - -@item W W C-c -@kindex W W C-c (Summary) -@findex gnus-article-hide-citation-maybe - -Hide citation (@code{gnus-article-hide-citation-maybe}) depending on the -following two variables: - -@table @code -@item gnus-cite-hide-percentage -@vindex gnus-cite-hide-percentage -If the cited text is of a bigger percentage than this variable (default -50), hide the cited text. - -@item gnus-cite-hide-absolute -@vindex gnus-cite-hide-absolute -The cited text must have at least this length (default 10) before it -is hidden. -@end table - -@item W W C -@kindex W W C (Summary) -@findex gnus-article-hide-citation-in-followups -Hide cited text in articles that aren't roots -(@code{gnus-article-hide-citation-in-followups}). This isn't very -useful as an interactive command, but might be a handy function to stick -have happen automatically (@pxref{Customizing Articles}). - -@end table - -All these ``hiding'' commands are toggles, but if you give a negative -prefix to these commands, they will show what they have previously -hidden. If you give a positive prefix, they will always hide. - -Also @pxref{Article Highlighting} for further variables for -citation customization. - -@xref{Customizing Articles}, for how to hide article elements -automatically. - - -@node Article Washing -@subsection Article Washing -@cindex washing -@cindex article washing - -We call this ``article washing'' for a really good reason. Namely, the -@kbd{A} key was taken, so we had to use the @kbd{W} key instead. - -@dfn{Washing} is defined by us as ``changing something from something to -something else'', but normally results in something looking better. -Cleaner, perhaps. - -@xref{Customizing Articles}, if you want to change how Gnus displays -articles by default. - -@table @kbd - -@item C-u g -This is not really washing, it's sort of the opposite of washing. If -you type this, you see the article exactly as it exists on disk or on -the server. - -@item g -Force redisplaying of the current article -(@code{gnus-summary-show-article}). This is also not really washing. -If you type this, you see the article without any previously applied -interactive Washing functions but with all default treatments -(@pxref{Customizing Articles}). - -@item W l -@kindex W l (Summary) -@findex gnus-summary-stop-page-breaking -Remove page breaks from the current article -(@code{gnus-summary-stop-page-breaking}). @xref{Misc Article}, for page -delimiters. - -@item W r -@kindex W r (Summary) -@findex gnus-summary-caesar-message -@c @icon{gnus-summary-caesar-message} -Do a Caesar rotate (rot13) on the article buffer -(@code{gnus-summary-caesar-message}). -Unreadable articles that tell you to read them with Caesar rotate or rot13. -(Typically offensive jokes and such.) - -It's commonly called ``rot13'' because each letter is rotated 13 -positions in the alphabet, e. g. @samp{B} (letter #2) -> @samp{O} (letter -#15). It is sometimes referred to as ``Caesar rotate'' because Caesar -is rumored to have employed this form of, uh, somewhat weak encryption. - -@item W m -@kindex W m (Summary) -@findex gnus-summary-morse-message -Morse decode the article buffer (@code{gnus-summary-morse-message}). - -@item W i -@kindex W i (Summary) -@findex gnus-summary-idna-message -Decode IDNA encoded domain names in the current articles. IDNA -encoded domain names looks like @samp{xn--bar}. If a string remain -unencoded after running invoking this, it is likely an invalid IDNA -string (@samp{xn--bar} is invalid). You must have GNU Libidn -(@url{http://www.gnu.org/software/libidn/}) installed for this command -to work. - -@item W t -@item t -@kindex W t (Summary) -@kindex t (Summary) -@findex gnus-summary-toggle-header -Toggle whether to display all headers in the article buffer -(@code{gnus-summary-toggle-header}). - -@item W v -@kindex W v (Summary) -@findex gnus-summary-verbose-headers -Toggle whether to display all headers in the article buffer permanently -(@code{gnus-summary-verbose-headers}). - -@item W o -@kindex W o (Summary) -@findex gnus-article-treat-overstrike -Treat overstrike (@code{gnus-article-treat-overstrike}). - -@item W d -@kindex W d (Summary) -@findex gnus-article-treat-dumbquotes -@vindex gnus-article-dumbquotes-map -@cindex Smartquotes -@cindex M****s*** sm*rtq**t*s -@cindex Latin 1 -Treat M****s*** sm*rtq**t*s according to -@code{gnus-article-dumbquotes-map} -(@code{gnus-article-treat-dumbquotes}). Note that this function guesses -whether a character is a sm*rtq**t* or not, so it should only be used -interactively. - -Sm*rtq**t*s are M****s***'s unilateral extension to the character map in -an attempt to provide more quoting characters. If you see something -like @code{\222} or @code{\264} where you're expecting some kind of -apostrophe or quotation mark, then try this wash. - -@item W U -@kindex W U (Summary) -@findex gnus-article-treat-non-ascii -@cindex Unicode -@cindex Non-@acronym{ASCII} -Translate many non-@acronym{ASCII} characters into their -@acronym{ASCII} equivalents (@code{gnus-article-treat-non-ascii}). -This is mostly useful if you're on a terminal that has a limited font -and doesn't show accented characters, ``advanced'' punctuation, and the -like. For instance, @samp{»} is translated into @samp{>>}, and so on. - -@item W Y f -@kindex W Y f (Summary) -@findex gnus-article-outlook-deuglify-article -@cindex Outlook Express -Full deuglify of broken Outlook (Express) articles: Treat dumbquotes, -unwrap lines, repair attribution and rearrange citation. -(@code{gnus-article-outlook-deuglify-article}). - -@item W Y u -@kindex W Y u (Summary) -@findex gnus-article-outlook-unwrap-lines -@vindex gnus-outlook-deuglify-unwrap-min -@vindex gnus-outlook-deuglify-unwrap-max -Unwrap lines that appear to be wrapped citation lines. You can control -what lines will be unwrapped by frobbing -@code{gnus-outlook-deuglify-unwrap-min} and -@code{gnus-outlook-deuglify-unwrap-max}, indicating the minimum and -maximum length of an unwrapped citation line. -(@code{gnus-article-outlook-unwrap-lines}). - -@item W Y a -@kindex W Y a (Summary) -@findex gnus-article-outlook-repair-attribution -Repair a broken attribution line.@* -(@code{gnus-article-outlook-repair-attribution}). - -@item W Y c -@kindex W Y c (Summary) -@findex gnus-article-outlook-rearrange-citation -Repair broken citations by rearranging the text. -(@code{gnus-article-outlook-rearrange-citation}). - -@item W w -@kindex W w (Summary) -@findex gnus-article-fill-cited-article -Do word wrap (@code{gnus-article-fill-cited-article}). - -You can give the command a numerical prefix to specify the width to use -when filling. - -@item W Q -@kindex W Q (Summary) -@findex gnus-article-fill-long-lines -Fill long lines (@code{gnus-article-fill-long-lines}). - -@item W C -@kindex W C (Summary) -@findex gnus-article-capitalize-sentences -Capitalize the first word in each sentence -(@code{gnus-article-capitalize-sentences}). - -@item W c -@kindex W c (Summary) -@findex gnus-article-remove-cr -Translate CRLF pairs (i. e., @samp{^M}s on the end of the lines) into LF -(this takes care of DOS line endings), and then translate any remaining -CRs into LF (this takes care of Mac line endings) -(@code{gnus-article-remove-cr}). - -@item W q -@kindex W q (Summary) -@findex gnus-article-de-quoted-unreadable -Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}). -Quoted-Printable is one common @acronym{MIME} encoding employed when -sending non-@acronym{ASCII} (i.e., 8-bit) articles. It typically -makes strings like @samp{d@'ej@`a vu} look like @samp{d=E9j=E0 vu}, -which doesn't look very readable to me. Note that this is usually -done automatically by Gnus if the message in question has a -@code{Content-Transfer-Encoding} header that says that this encoding -has been done. If a prefix is given, a charset will be asked for. - -@item W 6 -@kindex W 6 (Summary) -@findex gnus-article-de-base64-unreadable -Treat base64 (@code{gnus-article-de-base64-unreadable}). Base64 is -one common @acronym{MIME} encoding employed when sending -non-@acronym{ASCII} (i.e., 8-bit) articles. Note that this is -usually done automatically by Gnus if the message in question has a -@code{Content-Transfer-Encoding} header that says that this encoding -has been done. If a prefix is given, a charset will be asked for. - -@item W Z -@kindex W Z (Summary) -@findex gnus-article-decode-HZ -Treat HZ or HZP (@code{gnus-article-decode-HZ}). HZ (or HZP) is one -common encoding employed when sending Chinese articles. It typically -makes strings look like @samp{~@{<:Ky2;S@{#,NpJ)l6HK!#~@}}. - -@item W A -@kindex W A (Summary) -@findex gnus-article-treat-ansi-sequences -@cindex @acronym{ANSI} control sequences -Translate @acronym{ANSI} SGR control sequences into overlays or -extents (@code{gnus-article-treat-ansi-sequences}). @acronym{ANSI} -sequences are used in some Chinese hierarchies for highlighting. - -@item W u -@kindex W u (Summary) -@findex gnus-article-unsplit-urls -Remove newlines from within URLs. Some mailers insert newlines into -outgoing email messages to keep lines short. This reformatting can -split long URLs onto multiple lines. Repair those URLs by removing -the newlines (@code{gnus-article-unsplit-urls}). - -@item W h -@kindex W h (Summary) -@findex gnus-article-wash-html -Treat @acronym{HTML} (@code{gnus-article-wash-html}). Note that this is -usually done automatically by Gnus if the message in question has a -@code{Content-Type} header that says that the message is @acronym{HTML}. - -If a prefix is given, a charset will be asked for. If it is a number, -the charset defined in @code{gnus-summary-show-article-charset-alist} -(@pxref{Paging the Article}) will be used. - -The default is to use the function specified by -@code{mm-text-html-renderer} (@pxref{Display Customization, ,Display -Customization, emacs-mime, The Emacs MIME Manual}) to convert the -@acronym{HTML}. Pre-defined functions you can use include: - -@table @code -@item shr -Use Gnus simple html renderer. - -@item gnus-w3m -Use Gnus rendered based on w3m. - -@item w3 -Use Emacs/W3. - -@item w3m -Use @uref{http://emacs-w3m.namazu.org/, emacs-w3m}. - -@item w3m-standalone -Use @uref{http://w3m.sourceforge.net/, w3m}. - -@item links -Use @uref{http://links.sf.net/, Links}. - -@item lynx -Use @uref{http://lynx.isc.org/, Lynx}. - -@item html2text -Use html2text---a simple @acronym{HTML} converter included with Gnus. - -@end table - -@item W b -@kindex W b (Summary) -@findex gnus-article-add-buttons -Add clickable buttons to the article (@code{gnus-article-add-buttons}). -@xref{Article Buttons}. - -@item W B -@kindex W B (Summary) -@findex gnus-article-add-buttons-to-head -Add clickable buttons to the article headers -(@code{gnus-article-add-buttons-to-head}). - -@item W p -@kindex W p (Summary) -@findex gnus-article-verify-x-pgp-sig -Verify a signed control message -(@code{gnus-article-verify-x-pgp-sig}). Control messages such as -@code{newgroup} and @code{checkgroups} are usually signed by the -hierarchy maintainer. You need to add the @acronym{PGP} public key of -the maintainer to your keyring to verify the -message.@footnote{@acronym{PGP} keys for many hierarchies are -available at @uref{ftp://ftp.isc.org/pub/pgpcontrol/README.html}} - -@item W s -@kindex W s (Summary) -@findex gnus-summary-force-verify-and-decrypt -Verify a signed (@acronym{PGP}, @acronym{PGP/MIME} or -@acronym{S/MIME}) message -(@code{gnus-summary-force-verify-and-decrypt}). @xref{Security}. - -@item W a -@kindex W a (Summary) -@findex gnus-article-strip-headers-in-body -Strip headers like the @code{X-No-Archive} header from the beginning of -article bodies (@code{gnus-article-strip-headers-in-body}). - -@item W E l -@kindex W E l (Summary) -@findex gnus-article-strip-leading-blank-lines -Remove all blank lines from the beginning of the article -(@code{gnus-article-strip-leading-blank-lines}). - -@item W E m -@kindex W E m (Summary) -@findex gnus-article-strip-multiple-blank-lines -Replace all blank lines with empty lines and then all multiple empty -lines with a single empty line. -(@code{gnus-article-strip-multiple-blank-lines}). - -@item W E t -@kindex W E t (Summary) -@findex gnus-article-remove-trailing-blank-lines -Remove all blank lines at the end of the article -(@code{gnus-article-remove-trailing-blank-lines}). - -@item W E a -@kindex W E a (Summary) -@findex gnus-article-strip-blank-lines -Do all the three commands above -(@code{gnus-article-strip-blank-lines}). - -@item W E A -@kindex W E A (Summary) -@findex gnus-article-strip-all-blank-lines -Remove all blank lines -(@code{gnus-article-strip-all-blank-lines}). - -@item W E s -@kindex W E s (Summary) -@findex gnus-article-strip-leading-space -Remove all white space from the beginning of all lines of the article -body (@code{gnus-article-strip-leading-space}). - -@item W E e -@kindex W E e (Summary) -@findex gnus-article-strip-trailing-space -Remove all white space from the end of all lines of the article -body (@code{gnus-article-strip-trailing-space}). - -@end table - -@xref{Customizing Articles}, for how to wash articles automatically. - - -@node Article Header -@subsection Article Header - -These commands perform various transformations of article header. - -@table @kbd - -@item W G u -@kindex W G u (Summary) -@findex gnus-article-treat-unfold-headers -Unfold folded header lines (@code{gnus-article-treat-unfold-headers}). - -@item W G n -@kindex W G n (Summary) -@findex gnus-article-treat-fold-newsgroups -Fold the @code{Newsgroups} and @code{Followup-To} headers -(@code{gnus-article-treat-fold-newsgroups}). - -@item W G f -@kindex W G f (Summary) -@findex gnus-article-treat-fold-headers -Fold all the message headers -(@code{gnus-article-treat-fold-headers}). - -@item W E w -@kindex W E w (Summary) -@findex gnus-article-remove-leading-whitespace -Remove excessive whitespace from all headers -(@code{gnus-article-remove-leading-whitespace}). - -@end table - - -@node Article Buttons -@subsection Article Buttons -@cindex buttons - -People often include references to other stuff in articles, and it would -be nice if Gnus could just fetch whatever it is that people talk about -with the minimum of fuzz when you hit @kbd{RET} or use the middle mouse -button on these references. - -@vindex gnus-button-man-handler -Gnus adds @dfn{buttons} to certain standard references by default: -Well-formed URLs, mail addresses, Message-IDs, Info links, man pages and -Emacs or Gnus related references. This is controlled by two variables, -one that handles article bodies and one that handles article heads: - -@table @code - -@item gnus-button-alist -@vindex gnus-button-alist -This is an alist where each entry has this form: - -@lisp -(@var{regexp} @var{button-par} @var{use-p} @var{function} @var{data-par}) -@end lisp - -@table @var - -@item regexp -All text that match this regular expression (case insensitive) will be -considered an external reference. Here's a typical regexp that matches -embedded URLs: @samp{]*\\)>}. This can also be a -variable containing a regexp, useful variables to use include -@code{gnus-button-url-regexp} and @code{gnus-button-mid-or-mail-regexp}. - -@item button-par -Gnus has to know which parts of the matches is to be highlighted. This -is a number that says what sub-expression of the regexp is to be -highlighted. If you want it all highlighted, you use 0 here. - -@item use-p -This form will be @code{eval}ed, and if the result is non-@code{nil}, -this is considered a match. This is useful if you want extra sifting to -avoid false matches. Often variables named -@code{gnus-button-@var{*}-level} are used here, @xref{Article Button -Levels}, but any other form may be used too. - -@c @code{use-p} is @code{eval}ed only if @code{regexp} matches. - -@item function -This function will be called when you click on this button. - -@item data-par -As with @var{button-par}, this is a sub-expression number, but this one -says which part of the match is to be sent as data to @var{function}. - -@end table - -So the full entry for buttonizing URLs is then - -@lisp -("]*\\)>" 0 t gnus-button-url 1) -@end lisp - -@item gnus-header-button-alist -@vindex gnus-header-button-alist -This is just like the other alist, except that it is applied to the -article head only, and that each entry has an additional element that is -used to say what headers to apply the buttonize coding to: - -@lisp -(@var{header} @var{regexp} @var{button-par} @var{use-p} @var{function} @var{data-par}) -@end lisp - -@var{header} is a regular expression. -@end table - -@subsubsection Related variables and functions - -@table @code -@item gnus-button-@var{*}-level -@xref{Article Button Levels}. - -@c Stuff related to gnus-button-browse-level - -@item gnus-button-url-regexp -@vindex gnus-button-url-regexp -A regular expression that matches embedded URLs. It is used in the -default values of the variables above. - -@c Stuff related to gnus-button-man-level - -@item gnus-button-man-handler -@vindex gnus-button-man-handler -The function to use for displaying man pages. It must take at least one -argument with a string naming the man page. - -@c Stuff related to gnus-button-message-level - -@item gnus-button-mid-or-mail-regexp -@vindex gnus-button-mid-or-mail-regexp -Regular expression that matches a message ID or a mail address. - -@item gnus-button-prefer-mid-or-mail -@vindex gnus-button-prefer-mid-or-mail -This variable determines what to do when the button on a string as -@samp{foo123@@bar.invalid} is pushed. Strings like this can be either a -message ID or a mail address. If it is one of the symbols @code{mid} or -@code{mail}, Gnus will always assume that the string is a message ID or -a mail address, respectively. If this variable is set to the symbol -@code{ask}, always query the user what to do. If it is a function, this -function will be called with the string as its only argument. The -function must return @code{mid}, @code{mail}, @code{invalid} or -@code{ask}. The default value is the function -@code{gnus-button-mid-or-mail-heuristic}. - -@item gnus-button-mid-or-mail-heuristic -@findex gnus-button-mid-or-mail-heuristic -Function that guesses whether its argument is a message ID or a mail -address. Returns @code{mid} if it's a message IDs, @code{mail} if -it's a mail address, @code{ask} if unsure and @code{invalid} if the -string is invalid. - -@item gnus-button-mid-or-mail-heuristic-alist -@vindex gnus-button-mid-or-mail-heuristic-alist -An alist of @code{(RATE . REGEXP)} pairs used by the function -@code{gnus-button-mid-or-mail-heuristic}. - -@c Misc stuff - -@item gnus-article-button-face -@vindex gnus-article-button-face -Face used on buttons. - -@item gnus-article-mouse-face -@vindex gnus-article-mouse-face -Face used when the mouse cursor is over a button. - -@end table - -@xref{Customizing Articles}, for how to buttonize articles automatically. - - -@node Article Button Levels -@subsection Article button levels -@cindex button levels -The higher the value of the variables @code{gnus-button-@var{*}-level}, -the more buttons will appear. If the level is zero, no corresponding -buttons are displayed. With the default value (which is 5) you should -already see quite a lot of buttons. With higher levels, you will see -more buttons, but you may also get more false positives. To avoid them, -you can set the variables @code{gnus-button-@var{*}-level} local to -specific groups (@pxref{Group Parameters}). Here's an example for the -variable @code{gnus-parameters}: - -@lisp -;; @r{increase @code{gnus-button-*-level} in some groups:} -(setq gnus-parameters - '(("\\<\\(emacs\\|gnus\\)\\>" (gnus-button-emacs-level 10)) - ("\\" (gnus-button-man-level 10)) - ("\\" (gnus-button-tex-level 10)))) -@end lisp - -@table @code - -@item gnus-button-browse-level -@vindex gnus-button-browse-level -Controls the display of references to message IDs, mail addresses and -news URLs. Related variables and functions include -@code{gnus-button-url-regexp}, @code{browse-url}, and -@code{browse-url-browser-function}. - -@item gnus-button-emacs-level -@vindex gnus-button-emacs-level -Controls the display of Emacs or Gnus references. Related functions are -@code{gnus-button-handle-custom}, -@code{gnus-button-handle-describe-function}, -@code{gnus-button-handle-describe-variable}, -@code{gnus-button-handle-symbol}, -@code{gnus-button-handle-describe-key}, -@code{gnus-button-handle-apropos}, -@code{gnus-button-handle-apropos-command}, -@code{gnus-button-handle-apropos-variable}, -@code{gnus-button-handle-apropos-documentation}, and -@code{gnus-button-handle-library}. - -@item gnus-button-man-level -@vindex gnus-button-man-level -Controls the display of references to (Unix) man pages. -See @code{gnus-button-man-handler}. - -@item gnus-button-message-level -@vindex gnus-button-message-level -Controls the display of message IDs, mail addresses and news URLs. -Related variables and functions include -@code{gnus-button-mid-or-mail-regexp}, -@code{gnus-button-prefer-mid-or-mail}, -@code{gnus-button-mid-or-mail-heuristic}, and -@code{gnus-button-mid-or-mail-heuristic-alist}. - -@end table - - -@node Article Date -@subsection Article Date - -The date is most likely generated in some obscure timezone you've never -heard of, so it's quite nice to be able to find out what the time was -when the article was sent. - -@table @kbd - -@item W T u -@kindex W T u (Summary) -@findex gnus-article-date-ut -Display the date in UT (aka. GMT, aka ZULU) -(@code{gnus-article-date-ut}). - -@item W T i -@kindex W T i (Summary) -@findex gnus-article-date-iso8601 -@cindex ISO 8601 -Display the date in international format, aka. ISO 8601 -(@code{gnus-article-date-iso8601}). - -@item W T l -@kindex W T l (Summary) -@findex gnus-article-date-local -Display the date in the local timezone (@code{gnus-article-date-local}). - -@item W T p -@kindex W T p (Summary) -@findex gnus-article-date-english -Display the date in a format that's easily pronounceable in English -(@code{gnus-article-date-english}). - -@item W T s -@kindex W T s (Summary) -@vindex gnus-article-time-format -@findex gnus-article-date-user -@findex format-time-string -Display the date using a user-defined format -(@code{gnus-article-date-user}). The format is specified by the -@code{gnus-article-time-format} variable, and is a string that's passed -to @code{format-time-string}. See the documentation of that variable -for a list of possible format specs. - -@item W T e -@kindex W T e (Summary) -@findex gnus-article-date-lapsed -@findex gnus-start-date-timer -@findex gnus-stop-date-timer -Say how much time has elapsed between the article was posted and now -(@code{gnus-article-date-lapsed}). It looks something like: - -@example -Date: 6 weeks, 4 days, 1 hour, 3 minutes, 8 seconds ago -@end example - -This line is updated continually by default. The frequency (in -seconds) is controlled by the @code{gnus-article-update-date-headers} -variable. - -If you wish to switch updating off, say: - -@vindex gnus-article-update-date-headers -@lisp -(setq gnus-article-update-date-headers nil) -@end lisp - -in your @file{~/.gnus.el} file. - -@item W T o -@kindex W T o (Summary) -@findex gnus-article-date-original -Display the original date (@code{gnus-article-date-original}). This can -be useful if you normally use some other conversion function and are -worried that it might be doing something totally wrong. Say, claiming -that the article was posted in 1854. Although something like that is -@emph{totally} impossible. Don't you trust me? *titter* - -@end table - -@xref{Customizing Articles}, for how to display the date in your -preferred format automatically. - - -@node Article Display -@subsection Article Display -@cindex picons -@cindex x-face -@cindex smileys -@cindex gravatars - -These commands add various frivolous display gimmicks to the article -buffer in Emacs versions that support them. - -@code{X-Face} headers are small black-and-white images supplied by the -message headers (@pxref{X-Face}). - -@code{Face} headers are small colored images supplied by the message -headers (@pxref{Face}). - -Smileys are those little @samp{:-)} symbols that people like to litter -their messages with (@pxref{Smileys}). - -Picons, on the other hand, reside on your own system, and Gnus will -try to match the headers to what you have (@pxref{Picons}). - -Gravatars reside on-line and are fetched from -@uref{http://www.gravatar.com/} (@pxref{Gravatars}). - -All these functions are toggles---if the elements already exist, -they'll be removed. - -@table @kbd -@item W D x -@kindex W D x (Summary) -@findex gnus-article-display-x-face -Display an @code{X-Face} in the @code{From} header. -(@code{gnus-article-display-x-face}). - -@item W D d -@kindex W D d (Summary) -@findex gnus-article-display-face -Display a @code{Face} in the @code{From} header. -(@code{gnus-article-display-face}). - -@item W D s -@kindex W D s (Summary) -@findex gnus-treat-smiley -Display smileys (@code{gnus-treat-smiley}). - -@item W D f -@kindex W D f (Summary) -@findex gnus-treat-from-picon -Piconify the @code{From} header (@code{gnus-treat-from-picon}). - -@item W D m -@kindex W D m (Summary) -@findex gnus-treat-mail-picon -Piconify all mail headers (i. e., @code{Cc}, @code{To}) -(@code{gnus-treat-mail-picon}). - -@item W D n -@kindex W D n (Summary) -@findex gnus-treat-newsgroups-picon -Piconify all news headers (i. e., @code{Newsgroups} and -@code{Followup-To}) (@code{gnus-treat-newsgroups-picon}). - -@item W D g -@kindex W D g (Summary) -@findex gnus-treat-from-gravatar -Gravatarify the @code{From} header (@code{gnus-treat-from-gravatar}). - -@item W D h -@kindex W D h (Summary) -@findex gnus-treat-mail-gravatar -Gravatarify all mail headers (i. e., @code{Cc}, @code{To}) -(@code{gnus-treat-from-gravatar}). - -@item W D D -@kindex W D D (Summary) -@findex gnus-article-remove-images -Remove all images from the article buffer -(@code{gnus-article-remove-images}). - -@item W D W -@kindex W D W (Summary) -@findex gnus-html-show-images -If you're reading an @acronym{HTML} article rendered with -@code{gnus-article-html}, then you can insert any blocked images in -the buffer with this command. -(@code{gnus-html-show-images}). - -@end table - - - -@node Article Signature -@subsection Article Signature -@cindex signatures -@cindex article signature - -@vindex gnus-signature-separator -Each article is divided into two parts---the head and the body. The -body can be divided into a signature part and a text part. The variable -that says what is to be considered a signature is -@code{gnus-signature-separator}. This is normally the standard -@samp{^-- $} as mandated by son-of-RFC 1036. However, many people use -non-standard signature separators, so this variable can also be a list -of regular expressions to be tested, one by one. (Searches are done -from the end of the body towards the beginning.) One likely value is: - -@lisp -(setq gnus-signature-separator - '("^-- $" ; @r{The standard} - "^-- *$" ; @r{A common mangling} - "^-------*$" ; @r{Many people just use a looong} - ; @r{line of dashes. Shame!} - "^ *--------*$" ; @r{Double-shame!} - "^________*$" ; @r{Underscores are also popular} - "^========*$")) ; @r{Pervert!} -@end lisp - -The more permissive you are, the more likely it is that you'll get false -positives. - -@vindex gnus-signature-limit -@code{gnus-signature-limit} provides a limit to what is considered a -signature when displaying articles. - -@enumerate -@item -If it is an integer, no signature may be longer (in characters) than -that integer. -@item -If it is a floating point number, no signature may be longer (in lines) -than that number. -@item -If it is a function, the function will be called without any parameters, -and if it returns @code{nil}, there is no signature in the buffer. -@item -If it is a string, it will be used as a regexp. If it matches, the text -in question is not a signature. -@end enumerate - -This variable can also be a list where the elements may be of the types -listed above. Here's an example: - -@lisp -(setq gnus-signature-limit - '(200.0 "^---*Forwarded article")) -@end lisp - -This means that if there are more than 200 lines after the signature -separator, or the text after the signature separator is matched by -the regular expression @samp{^---*Forwarded article}, then it isn't a -signature after all. - - -@node Article Miscellanea -@subsection Article Miscellanea - -@table @kbd -@item A t -@kindex A t (Summary) -@findex gnus-article-babel -Translate the article from one language to another -(@code{gnus-article-babel}). - -@end table - - -@node MIME Commands -@section MIME Commands -@cindex MIME decoding -@cindex attachments -@cindex viewing attachments - -The following commands all understand the numerical prefix. For -instance, @kbd{3 K v} means ``view the third @acronym{MIME} part''. - -@table @kbd -@item b -@itemx K v -@kindex b (Summary) -@kindex K v (Summary) -View the @acronym{MIME} part. - -@item K o -@kindex K o (Summary) -Save the @acronym{MIME} part. - -@item K O -@kindex K O (Summary) -Prompt for a file name, then save the @acronym{MIME} part and strip it -from the article. The stripped @acronym{MIME} object will be referred -via the message/external-body @acronym{MIME} type. - -@item K r -@kindex K r (Summary) -Replace the @acronym{MIME} part with an external body. - -@item K d -@kindex K d (Summary) -Delete the @acronym{MIME} part and add some information about the -removed part. - -@item K c -@kindex K c (Summary) -Copy the @acronym{MIME} part. - -@item K e -@kindex K e (Summary) -View the @acronym{MIME} part externally. - -@item K i -@kindex K i (Summary) -View the @acronym{MIME} part internally. - -@item K | -@kindex K | (Summary) -Pipe the @acronym{MIME} part to an external command. -@end table - -The rest of these @acronym{MIME} commands do not use the numerical prefix in -the same manner: - -@table @kbd -@item K H -@kindex K H (Summary) -@findex gnus-article-browse-html-article -View @samp{text/html} parts of the current article with a WWW browser. -Inline images embedded in a message using the @code{cid} scheme, as they -are generally considered to be safe, will be processed properly. The -message header is added to the beginning of every @acronym{HTML} part -unless the prefix argument is given. - -Warning: Spammers use links to images (using the @code{http} scheme) in -@acronym{HTML} articles to verify whether you have read the message. As -this command passes the @acronym{HTML} content to the browser without -eliminating these ``web bugs'' you should only use it for mails from -trusted senders. - -If you always want to display @acronym{HTML} parts in the browser, set -@code{mm-text-html-renderer} to @code{nil}. - -This command creates temporary files to pass @acronym{HTML} contents -including images if any to the browser, and deletes them when exiting -the group (if you want). - -@item K b -@kindex K b (Summary) -Make all the @acronym{MIME} parts have buttons in front of them. This is -mostly useful if you wish to save (or perform other actions) on inlined -parts. - -@item K m -@kindex K m (Summary) -@findex gnus-summary-repair-multipart -Some multipart messages are transmitted with missing or faulty headers. -This command will attempt to ``repair'' these messages so that they can -be viewed in a more pleasant manner -(@code{gnus-summary-repair-multipart}). - -@item X m -@kindex X m (Summary) -@findex gnus-summary-save-parts -Save all parts matching a @acronym{MIME} type to a directory -(@code{gnus-summary-save-parts}). Understands the process/prefix -convention (@pxref{Process/Prefix}). - -@item M-t -@kindex M-t (Summary) -@findex gnus-summary-toggle-display-buttonized -Toggle the buttonized display of the article buffer -(@code{gnus-summary-toggle-display-buttonized}). - -@item W M w -@kindex W M w (Summary) -@findex gnus-article-decode-mime-words -Decode RFC 2047-encoded words in the article headers -(@code{gnus-article-decode-mime-words}). - -@item W M c -@kindex W M c (Summary) -@findex gnus-article-decode-charset -Decode encoded article bodies as well as charsets -(@code{gnus-article-decode-charset}). - -This command looks in the @code{Content-Type} header to determine the -charset. If there is no such header in the article, you can give it a -prefix, which will prompt for the charset to decode as. In regional -groups where people post using some common encoding (but do not -include @acronym{MIME} headers), you can set the @code{charset} group/topic -parameter to the required charset (@pxref{Group Parameters}). - -@item W M v -@kindex W M v (Summary) -@findex gnus-mime-view-all-parts -View all the @acronym{MIME} parts in the current article -(@code{gnus-mime-view-all-parts}). - -@end table - -Relevant variables: - -@table @code -@item gnus-ignored-mime-types -@vindex gnus-ignored-mime-types -This is a list of regexps. @acronym{MIME} types that match a regexp from -this list will be completely ignored by Gnus. The default value is -@code{nil}. - -To have all Vcards be ignored, you'd say something like this: - -@lisp -(setq gnus-ignored-mime-types - '("text/x-vcard")) -@end lisp - -@item gnus-article-loose-mime -@vindex gnus-article-loose-mime -If non-@code{nil}, Gnus won't require the @samp{MIME-Version} header -before interpreting the message as a @acronym{MIME} message. This helps -when reading messages from certain broken mail user agents. The -default is @code{t}. - -@item gnus-article-emulate-mime -@vindex gnus-article-emulate-mime -@cindex uuencode -@cindex yEnc -There are other, non-@acronym{MIME} encoding methods used. The most common -is @samp{uuencode}, but yEncode is also getting to be popular. If -this variable is non-@code{nil}, Gnus will look in message bodies to -see if it finds these encodings, and if so, it'll run them through the -Gnus @acronym{MIME} machinery. The default is @code{t}. Only -single-part yEnc encoded attachments can be decoded. There's no support -for encoding in Gnus. - -@item gnus-unbuttonized-mime-types -@vindex gnus-unbuttonized-mime-types -This is a list of regexps. @acronym{MIME} types that match a regexp from -this list won't have @acronym{MIME} buttons inserted unless they aren't -displayed or this variable is overridden by -@code{gnus-buttonized-mime-types}. The default value is -@code{(".*/.*")}. This variable is only used when -@code{gnus-inhibit-mime-unbuttonizing} is @code{nil}. - -@item gnus-buttonized-mime-types -@vindex gnus-buttonized-mime-types -This is a list of regexps. @acronym{MIME} types that match a regexp from -this list will have @acronym{MIME} buttons inserted unless they aren't -displayed. This variable overrides -@code{gnus-unbuttonized-mime-types}. The default value is @code{nil}. -This variable is only used when @code{gnus-inhibit-mime-unbuttonizing} -is @code{nil}. - -To see e.g. security buttons but no other buttons, you could set this -variable to @code{("multipart/signed")} and leave -@code{gnus-unbuttonized-mime-types} at the default value. - -You could also add @code{"multipart/alternative"} to this list to -display radio buttons that allow you to choose one of two media types -those mails include. See also @code{mm-discouraged-alternatives} -(@pxref{Display Customization, ,Display Customization, emacs-mime, The -Emacs MIME Manual}). - -@item gnus-inhibit-mime-unbuttonizing -@vindex gnus-inhibit-mime-unbuttonizing -If this is non-@code{nil}, then all @acronym{MIME} parts get buttons. The -default value is @code{nil}. - -@item gnus-article-mime-part-function -@vindex gnus-article-mime-part-function -For each @acronym{MIME} part, this function will be called with the @acronym{MIME} -handle as the parameter. The function is meant to be used to allow -users to gather information from the article (e. g., add Vcard info to -the bbdb database) or to do actions based on parts (e. g., automatically -save all jpegs into some directory). - -Here's an example function the does the latter: - -@lisp -(defun my-save-all-jpeg-parts (handle) - (when (equal (car (mm-handle-type handle)) "image/jpeg") - (with-temp-buffer - (insert (mm-get-part handle)) - (write-region (point-min) (point-max) - (read-file-name "Save jpeg to: "))))) -(setq gnus-article-mime-part-function - 'my-save-all-jpeg-parts) -@end lisp - -@vindex gnus-mime-multipart-functions -@item gnus-mime-multipart-functions -Alist of @acronym{MIME} multipart types and functions to handle them. - -@vindex gnus-mime-display-multipart-alternative-as-mixed -@item gnus-mime-display-multipart-alternative-as-mixed -Display "multipart/alternative" parts as "multipart/mixed". - -@vindex gnus-mime-display-multipart-related-as-mixed -@item gnus-mime-display-multipart-related-as-mixed -Display "multipart/related" parts as "multipart/mixed". - -If displaying @samp{text/html} is discouraged, see -@code{mm-discouraged-alternatives}, images or other material inside a -"multipart/related" part might be overlooked when this variable is -@code{nil}. @ref{Display Customization, Display Customization, , -emacs-mime, Emacs-Mime Manual}. - -@vindex gnus-mime-display-multipart-as-mixed -@item gnus-mime-display-multipart-as-mixed -Display "multipart" parts as "multipart/mixed". If @code{t}, it -overrides @code{nil} values of -@code{gnus-mime-display-multipart-alternative-as-mixed} and -@code{gnus-mime-display-multipart-related-as-mixed}. - -@vindex mm-file-name-rewrite-functions -@item mm-file-name-rewrite-functions -List of functions used for rewriting file names of @acronym{MIME} parts. -Each function takes a file name as input and returns a file name. - -Ready-made functions include@* -@code{mm-file-name-delete-whitespace}, -@code{mm-file-name-trim-whitespace}, -@code{mm-file-name-collapse-whitespace}, and -@code{mm-file-name-replace-whitespace}. The later uses the value of -the variable @code{mm-file-name-replace-whitespace} to replace each -whitespace character in a file name with that string; default value -is @code{"_"} (a single underscore). -@findex mm-file-name-delete-whitespace -@findex mm-file-name-trim-whitespace -@findex mm-file-name-collapse-whitespace -@findex mm-file-name-replace-whitespace -@vindex mm-file-name-replace-whitespace - -The standard functions @code{capitalize}, @code{downcase}, -@code{upcase}, and @code{upcase-initials} may be useful, too. - -Everybody knows that whitespace characters in file names are evil, -except those who don't know. If you receive lots of attachments from -such unenlightened users, you can make live easier by adding - -@lisp -(setq mm-file-name-rewrite-functions - '(mm-file-name-trim-whitespace - mm-file-name-collapse-whitespace - mm-file-name-replace-whitespace)) -@end lisp - -@noindent -to your @file{~/.gnus.el} file. - -@end table - - -@node Charsets -@section Charsets -@cindex charsets - -People use different charsets, and we have @acronym{MIME} to let us know what -charsets they use. Or rather, we wish we had. Many people use -newsreaders and mailers that do not understand or use @acronym{MIME}, and -just send out messages without saying what character sets they use. To -help a bit with this, some local news hierarchies have policies that say -what character set is the default. For instance, the @samp{fj} -hierarchy uses @code{iso-2022-jp}. - -@vindex gnus-group-charset-alist -This knowledge is encoded in the @code{gnus-group-charset-alist} -variable, which is an alist of regexps (use the first item to match full -group names) and default charsets to be used when reading these groups. - -@vindex gnus-newsgroup-ignored-charsets -In addition, some people do use soi-disant @acronym{MIME}-aware agents that -aren't. These blithely mark messages as being in @code{iso-8859-1} -even if they really are in @code{koi-8}. To help here, the -@code{gnus-newsgroup-ignored-charsets} variable can be used. The -charsets that are listed here will be ignored. The variable can be -set on a group-by-group basis using the group parameters (@pxref{Group -Parameters}). The default value is @code{(unknown-8bit x-unknown)}, -which includes values some agents insist on having in there. - -@vindex gnus-group-posting-charset-alist -When posting, @code{gnus-group-posting-charset-alist} is used to -determine which charsets should not be encoded using the @acronym{MIME} -encodings. For instance, some hierarchies discourage using -quoted-printable header encoding. - -This variable is an alist of regexps and permitted unencoded charsets -for posting. Each element of the alist has the form @code{(}@var{test -header body-list}@code{)}, where: - -@table @var -@item test -is either a regular expression matching the newsgroup header or a -variable to query, -@item header -is the charset which may be left unencoded in the header (@code{nil} -means encode all charsets), -@item body-list -is a list of charsets which may be encoded using 8bit content-transfer -encoding in the body, or one of the special values @code{nil} (always -encode using quoted-printable) or @code{t} (always use 8bit). -@end table - -@cindex Russian -@cindex koi8-r -@cindex koi8-u -@cindex iso-8859-5 -@cindex coding system aliases -@cindex preferred charset - -@xref{Encoding Customization, , Encoding Customization, emacs-mime, -The Emacs MIME Manual}, for additional variables that control which -MIME charsets are used when sending messages. - -Other charset tricks that may be useful, although not Gnus-specific: - -If there are several @acronym{MIME} charsets that encode the same Emacs -charset, you can choose what charset to use by saying the following: - -@lisp -(put-charset-property 'cyrillic-iso8859-5 - 'preferred-coding-system 'koi8-r) -@end lisp - -This means that Russian will be encoded using @code{koi8-r} instead of -the default @code{iso-8859-5} @acronym{MIME} charset. - -If you want to read messages in @code{koi8-u}, you can cheat and say - -@lisp -(define-coding-system-alias 'koi8-u 'koi8-r) -@end lisp - -This will almost do the right thing. - -And finally, to read charsets like @code{windows-1251}, you can say -something like - -@lisp -(codepage-setup 1251) -(define-coding-system-alias 'windows-1251 'cp1251) -@end lisp - - -@node Article Commands -@section Article Commands - -@table @kbd - -@item A P -@cindex PostScript -@cindex printing -@kindex A P (Summary) -@vindex gnus-ps-print-hook -@findex gnus-summary-print-article -Generate and print a PostScript image of the article buffer -(@code{gnus-summary-print-article}). @code{gnus-ps-print-hook} will -be run just before printing the buffer. An alternative way to print -article is to use Muttprint (@pxref{Saving Articles}). - -@item A C -@vindex gnus-fetch-partial-articles -@findex gnus-summary-show-complete-article -If @code{-fetch-partial-articles} is non-@code{nil}, Gnus will -fetch partial articles, if the backend it fetches them from supports -it. Currently only @code{nnimap} does. If you're looking at a -partial article, and want to see the complete article instead, then -the @kbd{A C} command (@code{gnus-summary-show-complete-article}) will -do so. - -@end table - - -@node Summary Sorting -@section Summary Sorting -@cindex summary sorting - -You can have the summary buffer sorted in various ways, even though I -can't really see why you'd want that. - -@table @kbd - -@item C-c C-s C-n -@kindex C-c C-s C-n (Summary) -@findex gnus-summary-sort-by-number -Sort by article number (@code{gnus-summary-sort-by-number}). - -@item C-c C-s C-m C-n -@kindex C-c C-s C-n (Summary) -@findex gnus-summary-sort-by-most-recent-number -Sort by most recent article number -(@code{gnus-summary-sort-by-most-recent-number}). - -@item C-c C-s C-a -@kindex C-c C-s C-a (Summary) -@findex gnus-summary-sort-by-author -Sort by author (@code{gnus-summary-sort-by-author}). - -@item C-c C-s C-t -@kindex C-c C-s C-t (Summary) -@findex gnus-summary-sort-by-recipient -Sort by recipient (@code{gnus-summary-sort-by-recipient}). - -@item C-c C-s C-s -@kindex C-c C-s C-s (Summary) -@findex gnus-summary-sort-by-subject -Sort by subject (@code{gnus-summary-sort-by-subject}). - -@item C-c C-s C-d -@kindex C-c C-s C-d (Summary) -@findex gnus-summary-sort-by-date -Sort by date (@code{gnus-summary-sort-by-date}). - -@item C-c C-s C-m C-d -@kindex C-c C-s C-m C-d (Summary) -@findex gnus-summary-sort-by-most-recent-date -Sort by most recent date (@code{gnus-summary-sort-by-most-recent-date}). - -@item C-c C-s C-l -@kindex C-c C-s C-l (Summary) -@findex gnus-summary-sort-by-lines -Sort by lines (@code{gnus-summary-sort-by-lines}). - -@item C-c C-s C-c -@kindex C-c C-s C-c (Summary) -@findex gnus-summary-sort-by-chars -Sort by article length (@code{gnus-summary-sort-by-chars}). - -@item C-c C-s C-i -@kindex C-c C-s C-i (Summary) -@findex gnus-summary-sort-by-score -Sort by score (@code{gnus-summary-sort-by-score}). - -@item C-c C-s C-r -@kindex C-c C-s C-r (Summary) -@findex gnus-summary-sort-by-random -Randomize (@code{gnus-summary-sort-by-random}). - -@item C-c C-s C-o -@kindex C-c C-s C-o (Summary) -@findex gnus-summary-sort-by-original -Sort using the default sorting method -(@code{gnus-summary-sort-by-original}). -@end table - -These functions will work both when you use threading and when you don't -use threading. In the latter case, all summary lines will be sorted, -line by line. In the former case, sorting will be done on a -root-by-root basis, which might not be what you were looking for. To -toggle whether to use threading, type @kbd{T T} (@pxref{Thread -Commands}). - -If a prefix argument if given, the sort order is reversed. - - -@node Finding the Parent -@section Finding the Parent -@cindex parent articles -@cindex referring articles - -@table @kbd -@item ^ -@kindex ^ (Summary) -@findex gnus-summary-refer-parent-article -If you'd like to read the parent of the current article, and it is not -displayed in the summary buffer, you might still be able to. That is, -if the current group is fetched by @acronym{NNTP}, the parent hasn't expired -and the @code{References} in the current article are not mangled, you -can just press @kbd{^} or @kbd{A r} -(@code{gnus-summary-refer-parent-article}). If everything goes well, -you'll get the parent. If the parent is already displayed in the -summary buffer, point will just move to this article. - -If given a positive numerical prefix, fetch that many articles back into -the ancestry. If given a negative numerical prefix, fetch just that -ancestor. So if you say @kbd{3 ^}, Gnus will fetch the parent, the -grandparent and the grandgrandparent of the current article. If you say -@kbd{-3 ^}, Gnus will only fetch the grandgrandparent of the current -article. - -@item A R (Summary) -@findex gnus-summary-refer-references -@kindex A R (Summary) -Fetch all articles mentioned in the @code{References} header of the -article (@code{gnus-summary-refer-references}). - -@item A T (Summary) -@findex gnus-summary-refer-thread -@kindex A T (Summary) -Display the full thread where the current article appears -(@code{gnus-summary-refer-thread}). This command has to fetch all the -headers in the current group to work, so it usually takes a while. If -you do it often, you may consider setting @code{gnus-fetch-old-headers} -to @code{invisible} (@pxref{Filling In Threads}). This won't have any -visible effects normally, but it'll make this command work a whole lot -faster. Of course, it'll make group entry somewhat slow. - -@vindex gnus-refer-thread-limit -The @code{gnus-refer-thread-limit} variable says how many old (i. e., -articles before the first displayed in the current group) headers to -fetch when doing this command. The default is 200. If @code{t}, all -the available headers will be fetched. This variable can be overridden -by giving the @kbd{A T} command a numerical prefix. - -@item M-^ (Summary) -@findex gnus-summary-refer-article -@kindex M-^ (Summary) -@cindex Message-ID -@cindex fetching by Message-ID -You can also ask Gnus for an arbitrary article, no matter what group it -belongs to. @kbd{M-^} (@code{gnus-summary-refer-article}) will ask you -for a @code{Message-ID}, which is one of those long, hard-to-read -thingies that look something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. -You have to get it all exactly right. No fuzzy searches, I'm afraid. - -Gnus looks for the @code{Message-ID} in the headers that have already -been fetched, but also tries all the select methods specified by -@code{gnus-refer-article-method} if it is not found. -@end table - -@vindex gnus-refer-article-method -If the group you are reading is located on a back end that does not -support fetching by @code{Message-ID} very well (like @code{nnspool}), -you can set @code{gnus-refer-article-method} to an @acronym{NNTP} method. It -would, perhaps, be best if the @acronym{NNTP} server you consult is the one -updating the spool you are reading from, but that's not really -necessary. - -It can also be a list of select methods, as well as the special symbol -@code{current}, which means to use the current select method. If it -is a list, Gnus will try all the methods in the list until it finds a -match. - -Here's an example setting that will first try the current method, and -then ask Google if that fails: - -@lisp -(setq gnus-refer-article-method - '(current - (nnweb "google" (nnweb-type google)))) -@end lisp - -Most of the mail back ends support fetching by @code{Message-ID}, but -do not do a particularly excellent job at it. That is, @code{nnmbox}, -@code{nnbabyl}, @code{nnmaildir}, @code{nnml}, are able to locate -articles from any groups, while @code{nnfolder}, and @code{nnimap} are -only able to locate articles that have been posted to the current -group. @code{nnmh} does not support this at all. - -Fortunately, the special @code{nnregistry} back end is able to locate -articles in any groups, regardless of their back end (@pxref{Registry -Article Refer Method, fetching by @code{Message-ID} using the -registry}). - -@node Alternative Approaches -@section Alternative Approaches - -Different people like to read news using different methods. This being -Gnus, we offer a small selection of minor modes for the summary buffers. - -@menu -* Pick and Read:: First mark articles and then read them. -* Binary Groups:: Auto-decode all articles. -@end menu - - -@node Pick and Read -@subsection Pick and Read -@cindex pick and read - -Some newsreaders (like @code{nn} and, uhm, @code{Netnews} on VM/CMS) use -a two-phased reading interface. The user first marks in a summary -buffer the articles she wants to read. Then she starts reading the -articles with just an article buffer displayed. - -@findex gnus-pick-mode -@kindex M-x gnus-pick-mode -Gnus provides a summary buffer minor mode that allows -this---@code{gnus-pick-mode}. This basically means that a few process -mark commands become one-keystroke commands to allow easy marking, and -it provides one additional command for switching to the summary buffer. - -Here are the available keystrokes when using pick mode: - -@table @kbd -@item . -@kindex . (Pick) -@findex gnus-pick-article-or-thread -Pick the article or thread on the current line -(@code{gnus-pick-article-or-thread}). If the variable -@code{gnus-thread-hide-subtree} is true, then this key selects the -entire thread when used at the first article of the thread. Otherwise, -it selects just the article. If given a numerical prefix, go to that -thread or article and pick it. (The line number is normally displayed -at the beginning of the summary pick lines.) - -@item SPACE -@kindex SPACE (Pick) -@findex gnus-pick-next-page -Scroll the summary buffer up one page (@code{gnus-pick-next-page}). If -at the end of the buffer, start reading the picked articles. - -@item u -@kindex u (Pick) -@findex gnus-pick-unmark-article-or-thread. -Unpick the thread or article -(@code{gnus-pick-unmark-article-or-thread}). If the variable -@code{gnus-thread-hide-subtree} is true, then this key unpicks the -thread if used at the first article of the thread. Otherwise it unpicks -just the article. You can give this key a numerical prefix to unpick -the thread or article at that line. - -@item RET -@kindex RET (Pick) -@findex gnus-pick-start-reading -@vindex gnus-pick-display-summary -Start reading the picked articles (@code{gnus-pick-start-reading}). If -given a prefix, mark all unpicked articles as read first. If -@code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer -will still be visible when you are reading. - -@end table - -All the normal summary mode commands are still available in the -pick-mode, with the exception of @kbd{u}. However @kbd{!} is available -which is mapped to the same function -@code{gnus-summary-tick-article-forward}. - -If this sounds like a good idea to you, you could say: - -@lisp -(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) -@end lisp - -@vindex gnus-pick-mode-hook -@code{gnus-pick-mode-hook} is run in pick minor mode buffers. - -@vindex gnus-mark-unpicked-articles-as-read -If @code{gnus-mark-unpicked-articles-as-read} is non-@code{nil}, mark -all unpicked articles as read. The default is @code{nil}. - -@vindex gnus-summary-pick-line-format -The summary line format in pick mode is slightly different from the -standard format. At the beginning of each line the line number is -displayed. The pick mode line format is controlled by the -@code{gnus-summary-pick-line-format} variable (@pxref{Formatting -Variables}). It accepts the same format specs that -@code{gnus-summary-line-format} does (@pxref{Summary Buffer Lines}). - - -@node Binary Groups -@subsection Binary Groups -@cindex binary groups - -@findex gnus-binary-mode -@kindex M-x gnus-binary-mode -If you spend much time in binary groups, you may grow tired of hitting -@kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode} -is a minor mode for summary buffers that makes all ordinary Gnus article -selection functions uudecode series of articles and display the result -instead of just displaying the articles the normal way. - -@kindex g (Binary) -@findex gnus-binary-show-article -The only way, in fact, to see the actual articles is the @kbd{g} -command, when you have turned on this mode -(@code{gnus-binary-show-article}). - -@vindex gnus-binary-mode-hook -@code{gnus-binary-mode-hook} is called in binary minor mode buffers. - - -@node Tree Display -@section Tree Display -@cindex trees - -@vindex gnus-use-trees -If you don't like the normal Gnus summary display, you might try setting -@code{gnus-use-trees} to @code{t}. This will create (by default) an -additional @dfn{tree buffer}. You can execute all summary mode commands -in the tree buffer. - -There are a few variables to customize the tree display, of course: - -@table @code -@item gnus-tree-mode-hook -@vindex gnus-tree-mode-hook -A hook called in all tree mode buffers. - -@item gnus-tree-mode-line-format -@vindex gnus-tree-mode-line-format -A format string for the mode bar in the tree mode buffers (@pxref{Mode -Line Formatting}). The default is @samp{Gnus: %%b %S %Z}. For a list -of valid specs, @pxref{Summary Buffer Mode Line}. - -@item gnus-selected-tree-face -@vindex gnus-selected-tree-face -Face used for highlighting the selected article in the tree buffer. The -default is @code{modeline}. - -@item gnus-tree-line-format -@vindex gnus-tree-line-format -A format string for the tree nodes. The name is a bit of a misnomer, -though---it doesn't define a line, but just the node. The default value -is @samp{%(%[%3,3n%]%)}, which displays the first three characters of -the name of the poster. It is vital that all nodes are of the same -length, so you @emph{must} use @samp{%4,4n}-like specifiers. - -Valid specs are: - -@table @samp -@item n -The name of the poster. -@item f -The @code{From} header. -@item N -The number of the article. -@item [ -The opening bracket. -@item ] -The closing bracket. -@item s -The subject. -@end table - -@xref{Formatting Variables}. - -Variables related to the display are: - -@table @code -@item gnus-tree-brackets -@vindex gnus-tree-brackets -This is used for differentiating between ``real'' articles and -``sparse'' articles. The format is -@example -((@var{real-open} . @var{real-close}) - (@var{sparse-open} . @var{sparse-close}) - (@var{dummy-open} . @var{dummy-close})) -@end example -and the default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}) (?< . ?>))}. - -@item gnus-tree-parent-child-edges -@vindex gnus-tree-parent-child-edges -This is a list that contains the characters used for connecting parent -nodes to their children. The default is @code{(?- ?\\ ?|)}. - -@end table - -@item gnus-tree-minimize-window -@vindex gnus-tree-minimize-window -If this variable is non-@code{nil}, Gnus will try to keep the tree -buffer as small as possible to allow more room for the other Gnus -windows. If this variable is a number, the tree buffer will never be -higher than that number. The default is @code{t}. Note that if you -have several windows displayed side-by-side in a frame and the tree -buffer is one of these, minimizing the tree window will also resize all -other windows displayed next to it. - -You may also wish to add the following hook to keep the window minimized -at all times: - -@lisp -(add-hook 'gnus-configure-windows-hook - 'gnus-tree-perhaps-minimize) -@end lisp - -@item gnus-generate-tree-function -@vindex gnus-generate-tree-function -@findex gnus-generate-horizontal-tree -@findex gnus-generate-vertical-tree -The function that actually generates the thread tree. Two predefined -functions are available: @code{gnus-generate-horizontal-tree} and -@code{gnus-generate-vertical-tree} (which is the default). - -@end table - -Here's an example from a horizontal tree buffer: - -@example -@{***@}-(***)-[odd]-[Gun] - | \[Jan] - | \[odd]-[Eri] - | \(***)-[Eri] - | \[odd]-[Paa] - \[Bjo] - \[Gun] - \[Gun]-[Jor] -@end example - -Here's the same thread displayed in a vertical tree buffer: - -@example -@group -@{***@} - |--------------------------\-----\-----\ -(***) [Bjo] [Gun] [Gun] - |--\-----\-----\ | -[odd] [Jan] [odd] (***) [Jor] - | | |--\ -[Gun] [Eri] [Eri] [odd] - | - [Paa] -@end group -@end example - -If you're using horizontal trees, it might be nice to display the trees -side-by-side with the summary buffer. You could add something like the -following to your @file{~/.gnus.el} file: - -@lisp -(setq gnus-use-trees t - gnus-generate-tree-function 'gnus-generate-horizontal-tree - gnus-tree-minimize-window nil) -(gnus-add-configuration - '(article - (vertical 1.0 - (horizontal 0.25 - (summary 0.75 point) - (tree 1.0)) - (article 1.0)))) -@end lisp - -@xref{Window Layout}. - - -@node Mail Group Commands -@section Mail Group Commands -@cindex mail group commands - -Some commands only make sense in mail groups. If these commands are -invalid in the current group, they will raise a hell and let you know. - -All these commands (except the expiry and edit commands) use the -process/prefix convention (@pxref{Process/Prefix}). - -@table @kbd - -@item B e -@kindex B e (Summary) -@findex gnus-summary-expire-articles -@cindex expiring mail -Run all expirable articles in the current group through the expiry -process (@code{gnus-summary-expire-articles}). That is, delete all -expirable articles in the group that have been around for a while. -(@pxref{Expiring Mail}). - -@item B C-M-e -@kindex B C-M-e (Summary) -@findex gnus-summary-expire-articles-now -@cindex expiring mail -Delete all the expirable articles in the group -(@code{gnus-summary-expire-articles-now}). This means that @strong{all} -articles eligible for expiry in the current group will -disappear forever into that big @file{/dev/null} in the sky. - -@item B DEL -@kindex B DEL (Summary) -@cindex deleting mail -@findex gnus-summary-delete-article -@c @icon{gnus-summary-mail-delete} -Delete the mail article. This is ``delete'' as in ``delete it from your -disk forever and ever, never to return again.'' Use with caution. -(@code{gnus-summary-delete-article}). - -@item B m -@kindex B m (Summary) -@cindex move mail -@findex gnus-summary-move-article -@vindex gnus-preserve-marks -Move the article from one mail group to another -(@code{gnus-summary-move-article}). Marks will be preserved if -@code{gnus-preserve-marks} is non-@code{nil} (which is the default). - -@item B c -@kindex B c (Summary) -@cindex copy mail -@findex gnus-summary-copy-article -@c @icon{gnus-summary-mail-copy} -Copy the article from one group (mail group or not) to a mail group -(@code{gnus-summary-copy-article}). Marks will be preserved if -@code{gnus-preserve-marks} is non-@code{nil} (which is the default). - -@item B B -@kindex B B (Summary) -@cindex crosspost mail -@findex gnus-summary-crosspost-article -Crosspost the current article to some other group -(@code{gnus-summary-crosspost-article}). This will create a new copy of -the article in the other group, and the Xref headers of the article will -be properly updated. - -@item B i -@kindex B i (Summary) -@findex gnus-summary-import-article -Import an arbitrary file into the current mail newsgroup -(@code{gnus-summary-import-article}). You will be prompted for a file -name, a @code{From} header and a @code{Subject} header. - -@item B I -@kindex B I (Summary) -@findex gnus-summary-create-article -Create an empty article in the current mail newsgroups -(@code{gnus-summary-create-article}). You will be prompted for a -@code{From} header and a @code{Subject} header. - -@item B r -@kindex B r (Summary) -@findex gnus-summary-respool-article -@vindex gnus-summary-respool-default-method -Respool the mail article (@code{gnus-summary-respool-article}). -@code{gnus-summary-respool-default-method} will be used as the default -select method when respooling. This variable is @code{nil} by default, -which means that the current group select method will be used instead. -Marks will be preserved if @code{gnus-preserve-marks} is non-@code{nil} -(which is the default). - -@item B w -@itemx e -@kindex B w (Summary) -@kindex e (Summary) -@findex gnus-summary-edit-article -@kindex C-c C-c (Article) -@findex gnus-summary-edit-article-done -Edit the current article (@code{gnus-summary-edit-article}). To finish -editing and make the changes permanent, type @kbd{C-c C-c} -(@code{gnus-summary-edit-article-done}). If you give a prefix to the -@kbd{C-c C-c} command, Gnus won't re-highlight the article. - -@item B q -@kindex B q (Summary) -@findex gnus-summary-respool-query -If you want to re-spool an article, you might be curious as to what group -the article will end up in before you do the re-spooling. This command -will tell you (@code{gnus-summary-respool-query}). - -@item B t -@kindex B t (Summary) -@findex gnus-summary-respool-trace -Similarly, this command will display all fancy splitting patterns used -when respooling, if any (@code{gnus-summary-respool-trace}). - -@item B p -@kindex B p (Summary) -@findex gnus-summary-article-posted-p -Some people have a tendency to send you ``courtesy'' copies when they -follow up to articles you have posted. These usually have a -@code{Newsgroups} header in them, but not always. This command -(@code{gnus-summary-article-posted-p}) will try to fetch the current -article from your news server (or rather, from -@code{gnus-refer-article-method} or @code{gnus-select-method}) and will -report back whether it found the article or not. Even if it says that -it didn't find the article, it may have been posted anyway---mail -propagation is much faster than news propagation, and the news copy may -just not have arrived yet. - -@item K E -@kindex K E (Summary) -@findex gnus-article-encrypt-body -@vindex gnus-article-encrypt-protocol -Encrypt the body of an article (@code{gnus-article-encrypt-body}). -The body is encrypted with the encryption protocol specified by the -variable @code{gnus-article-encrypt-protocol}. - -@end table - -@vindex gnus-move-split-methods -@cindex moving articles -If you move (or copy) articles regularly, you might wish to have Gnus -suggest where to put the articles. @code{gnus-move-split-methods} is a -variable that uses the same syntax as @code{gnus-split-methods} -(@pxref{Saving Articles}). You may customize that variable to create -suggestions you find reasonable. (Note that -@code{gnus-move-split-methods} uses group names where -@code{gnus-split-methods} uses file names.) - -@lisp -(setq gnus-move-split-methods - '(("^From:.*Lars Magne" "nnml:junk") - ("^Subject:.*gnus" "nnfolder:important") - (".*" "nnml:misc"))) -@end lisp - - -@node Various Summary Stuff -@section Various Summary Stuff - -@menu -* Summary Group Information:: Information oriented commands. -* Searching for Articles:: Multiple article commands. -* Summary Generation Commands:: -* Really Various Summary Commands:: Those pesky non-conformant commands. -@end menu - -@table @code -@vindex gnus-summary-display-while-building -@item gnus-summary-display-while-building -If non-@code{nil}, show and update the summary buffer as it's being -built. If @code{t}, update the buffer after every line is inserted. -If the value is an integer, @var{n}, update the display every @var{n} -lines. The default is @code{nil}. - -@vindex gnus-summary-display-arrow -@item gnus-summary-display-arrow -If non-@code{nil}, display an arrow in the fringe to indicate the -current article. - -@vindex gnus-summary-mode-hook -@item gnus-summary-mode-hook -This hook is called when creating a summary mode buffer. - -@vindex gnus-summary-generate-hook -@item gnus-summary-generate-hook -This is called as the last thing before doing the threading and the -generation of the summary buffer. It's quite convenient for customizing -the threading variables based on what data the newsgroup has. This hook -is called from the summary buffer after most summary buffer variables -have been set. - -@vindex gnus-summary-prepare-hook -@item gnus-summary-prepare-hook -It is called after the summary buffer has been generated. You might use -it to, for instance, highlight lines or modify the look of the buffer in -some other ungodly manner. I don't care. - -@vindex gnus-summary-prepared-hook -@item gnus-summary-prepared-hook -A hook called as the very last thing after the summary buffer has been -generated. - -@vindex gnus-summary-ignore-duplicates -@item gnus-summary-ignore-duplicates -When Gnus discovers two articles that have the same @code{Message-ID}, -it has to do something drastic. No articles are allowed to have the -same @code{Message-ID}, but this may happen when reading mail from some -sources. Gnus allows you to customize what happens with this variable. -If it is @code{nil} (which is the default), Gnus will rename the -@code{Message-ID} (for display purposes only) and display the article as -any other article. If this variable is @code{t}, it won't display the -article---it'll be as if it never existed. - -@vindex gnus-alter-articles-to-read-function -@item gnus-alter-articles-to-read-function -This function, which takes two parameters (the group name and the list -of articles to be selected), is called to allow the user to alter the -list of articles to be selected. - -For instance, the following function adds the list of cached articles to -the list in one particular group: - -@lisp -(defun my-add-cached-articles (group articles) - (if (string= group "some.group") - (append gnus-newsgroup-cached articles) - articles)) -@end lisp - -@vindex gnus-newsgroup-variables -@item gnus-newsgroup-variables -A list of newsgroup (summary buffer) local variables, or cons of -variables and their default expressions to be evalled (when the default -values are not @code{nil}), that should be made global while the summary -buffer is active. - -Note: The default expressions will be evaluated (using function -@code{eval}) before assignment to the local variable rather than just -assigned to it. If the default expression is the symbol @code{global}, -that symbol will not be evaluated but the global value of the local -variable will be used instead. - -These variables can be used to set variables in the group parameters -while still allowing them to affect operations done in other -buffers. For example: - -@lisp -(setq gnus-newsgroup-variables - '(message-use-followup-to - (gnus-visible-headers . - "^From:\\|^Newsgroups:\\|^Subject:\\|^Date:\\|^To:"))) -@end lisp - -Also @pxref{Group Parameters}. - -@vindex gnus-propagate-marks -@item gnus-propagate-marks -If non-@code{nil}, propagate marks to the backends for possible -storing. @xref{NNTP marks}, and friends, for a more fine-grained -sieve. - -@end table - - -@node Summary Group Information -@subsection Summary Group Information - -@table @kbd - -@item H d -@kindex H d (Summary) -@findex gnus-summary-describe-group -Give a brief description of the current group -(@code{gnus-summary-describe-group}). If given a prefix, force -rereading the description from the server. - -@item H h -@kindex H h (Summary) -@findex gnus-summary-describe-briefly -Give an extremely brief description of the most important summary -keystrokes (@code{gnus-summary-describe-briefly}). - -@item H i -@kindex H i (Summary) -@findex gnus-info-find-node -Go to the Gnus info node (@code{gnus-info-find-node}). -@end table - - -@node Searching for Articles -@subsection Searching for Articles - -@table @kbd - -@item M-s -@kindex M-s (Summary) -@findex gnus-summary-search-article-forward -Search through all subsequent (raw) articles for a regexp -(@code{gnus-summary-search-article-forward}). - -@item M-r -@kindex M-r (Summary) -@findex gnus-summary-search-article-backward -Search through all previous (raw) articles for a regexp -(@code{gnus-summary-search-article-backward}). - -@item M-S -@kindex M-S (Summary) -@findex gnus-summary-repeat-search-article-forward -Repeat the previous search forwards -(@code{gnus-summary-repeat-search-article-forward}). - -@item M-R -@kindex M-R (Summary) -@findex gnus-summary-repeat-search-article-backward -Repeat the previous search backwards -(@code{gnus-summary-repeat-search-article-backward}). - -@item & -@kindex & (Summary) -@findex gnus-summary-execute-command -This command will prompt you for a header, a regular expression to match -on this field, and a command to be executed if the match is made -(@code{gnus-summary-execute-command}). If the header is an empty -string, the match is done on the entire article. If given a prefix, -search backward instead. - -For instance, @kbd{& RET some.*string RET #} will put the process mark on -all articles that have heads or bodies that match @samp{some.*string}. - -@item M-& -@kindex M-& (Summary) -@findex gnus-summary-universal-argument -Perform any operation on all articles that have been marked with -the process mark (@code{gnus-summary-universal-argument}). -@end table - -@node Summary Generation Commands -@subsection Summary Generation Commands - -@table @kbd - -@item Y g -@kindex Y g (Summary) -@findex gnus-summary-prepare -Regenerate the current summary buffer (@code{gnus-summary-prepare}). - -@item Y c -@kindex Y c (Summary) -@findex gnus-summary-insert-cached-articles -Pull all cached articles (for the current group) into the summary buffer -(@code{gnus-summary-insert-cached-articles}). - -@item Y d -@kindex Y d (Summary) -@findex gnus-summary-insert-dormant-articles -Pull all dormant articles (for the current group) into the summary buffer -(@code{gnus-summary-insert-dormant-articles}). - -@item Y t -@kindex Y t (Summary) -@findex gnus-summary-insert-ticked-articles -Pull all ticked articles (for the current group) into the summary buffer -(@code{gnus-summary-insert-ticked-articles}). - -@end table - - -@node Really Various Summary Commands -@subsection Really Various Summary Commands - -@table @kbd - -@item A D -@itemx C-d -@kindex C-d (Summary) -@kindex A D (Summary) -@findex gnus-summary-enter-digest-group -If the current article is a collection of other articles (for instance, -a digest), you might use this command to enter a group based on the that -article (@code{gnus-summary-enter-digest-group}). Gnus will try to -guess what article type is currently displayed unless you give a prefix -to this command, which forces a ``digest'' interpretation. Basically, -whenever you see a message that is a collection of other messages of -some format, you @kbd{C-d} and read these messages in a more convenient -fashion. - -@vindex gnus-auto-select-on-ephemeral-exit -The variable @code{gnus-auto-select-on-ephemeral-exit} controls what -article should be selected after exiting a digest group. Valid values -include: - -@table @code -@item next -Select the next article. - -@item next-unread -Select the next unread article. - -@item next-noselect -Move the cursor to the next article. This is the default. - -@item next-unread-noselect -Move the cursor to the next unread article. -@end table - -If it has any other value or there is no next (unread) article, the -article selected before entering to the digest group will appear. - -@item C-M-d -@kindex C-M-d (Summary) -@findex gnus-summary-read-document -This command is very similar to the one above, but lets you gather -several documents into one biiig group -(@code{gnus-summary-read-document}). It does this by opening several -@code{nndoc} groups for each document, and then opening an -@code{nnvirtual} group on top of these @code{nndoc} groups. This -command understands the process/prefix convention -(@pxref{Process/Prefix}). - -@item C-t -@kindex C-t (Summary) -@findex gnus-summary-toggle-truncation -Toggle truncation of summary lines -(@code{gnus-summary-toggle-truncation}). This will probably confuse the -line centering function in the summary buffer, so it's not a good idea -to have truncation switched off while reading articles. - -@item = -@kindex = (Summary) -@findex gnus-summary-expand-window -Expand the summary buffer window (@code{gnus-summary-expand-window}). -If given a prefix, force an @code{article} window configuration. - -@item C-M-e -@kindex C-M-e (Summary) -@findex gnus-summary-edit-parameters -Edit the group parameters (@pxref{Group Parameters}) of the current -group (@code{gnus-summary-edit-parameters}). - -@item C-M-a -@kindex C-M-a (Summary) -@findex gnus-summary-customize-parameters -Customize the group parameters (@pxref{Group Parameters}) of the current -group (@code{gnus-summary-customize-parameters}). - -@end table - - -@node Exiting the Summary Buffer -@section Exiting the Summary Buffer -@cindex summary exit -@cindex exiting groups - -Exiting from the summary buffer will normally update all info on the -group and return you to the group buffer. - -@table @kbd - -@item Z Z -@itemx Z Q -@itemx q -@kindex Z Z (Summary) -@kindex Z Q (Summary) -@kindex q (Summary) -@findex gnus-summary-exit -@vindex gnus-summary-exit-hook -@vindex gnus-summary-prepare-exit-hook -@vindex gnus-group-no-more-groups-hook -@c @icon{gnus-summary-exit} -Exit the current group and update all information on the group -(@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is -called before doing much of the exiting, which calls -@code{gnus-summary-expire-articles} by default. -@code{gnus-summary-exit-hook} is called after finishing the exit -process. @code{gnus-group-no-more-groups-hook} is run when returning to -group mode having no more (unread) groups. - -@item Z E -@itemx Q -@kindex Z E (Summary) -@kindex Q (Summary) -@findex gnus-summary-exit-no-update -Exit the current group without updating any information on the group -(@code{gnus-summary-exit-no-update}). - -@item Z c -@itemx c -@kindex Z c (Summary) -@kindex c (Summary) -@findex gnus-summary-catchup-and-exit -@c @icon{gnus-summary-catchup-and-exit} -Mark all unticked articles in the group as read and then exit -(@code{gnus-summary-catchup-and-exit}). - -@item Z C -@kindex Z C (Summary) -@findex gnus-summary-catchup-all-and-exit -Mark all articles, even the ticked ones, as read and then exit -(@code{gnus-summary-catchup-all-and-exit}). - -@item Z n -@kindex Z n (Summary) -@findex gnus-summary-catchup-and-goto-next-group -Mark all articles as read and go to the next group -(@code{gnus-summary-catchup-and-goto-next-group}). - -@item Z p -@kindex Z p (Summary) -@findex gnus-summary-catchup-and-goto-prev-group -Mark all articles as read and go to the previous group -(@code{gnus-summary-catchup-and-goto-prev-group}). - -@item Z R -@itemx C-x C-s -@kindex Z R (Summary) -@kindex C-x C-s (Summary) -@findex gnus-summary-reselect-current-group -Exit this group, and then enter it again -(@code{gnus-summary-reselect-current-group}). If given a prefix, select -all articles, both read and unread. - -@item Z G -@itemx M-g -@kindex Z G (Summary) -@kindex M-g (Summary) -@findex gnus-summary-rescan-group -@c @icon{gnus-summary-mail-get} -Exit the group, check for new articles in the group, and select the -group (@code{gnus-summary-rescan-group}). If given a prefix, select all -articles, both read and unread. - -@item Z N -@kindex Z N (Summary) -@findex gnus-summary-next-group -Exit the group and go to the next group -(@code{gnus-summary-next-group}). - -@item Z P -@kindex Z P (Summary) -@findex gnus-summary-prev-group -Exit the group and go to the previous group -(@code{gnus-summary-prev-group}). - -@item Z s -@kindex Z s (Summary) -@findex gnus-summary-save-newsrc -Save the current number of read/marked articles in the dribble buffer -and then save the dribble buffer (@code{gnus-summary-save-newsrc}). If -given a prefix, also save the @file{.newsrc} file(s). Using this -command will make exit without updating (the @kbd{Q} command) worthless. -@end table - -@vindex gnus-exit-group-hook -@code{gnus-exit-group-hook} is called when you exit the current group -with an ``updating'' exit. For instance @kbd{Q} -(@code{gnus-summary-exit-no-update}) does not call this hook. - -@findex gnus-summary-wake-up-the-dead -@findex gnus-dead-summary-mode -@vindex gnus-kill-summary-on-exit -If you're in the habit of exiting groups, and then changing your mind -about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}. -If you do that, Gnus won't kill the summary buffer when you exit it. -(Quelle surprise!) Instead it will change the name of the buffer to -something like @samp{*Dead Summary ... *} and install a minor mode -called @code{gnus-dead-summary-mode}. Now, if you switch back to this -buffer, you'll find that all keys are mapped to a function called -@code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead -summary buffer will result in a live, normal summary buffer. - -There will never be more than one dead summary buffer at any one time. - -@vindex gnus-use-cross-reference -The data on the current group will be updated (which articles you have -read, which articles you have replied to, etc.) when you exit the -summary buffer. If the @code{gnus-use-cross-reference} variable is -@code{t} (which is the default), articles that are cross-referenced to -this group and are marked as read, will also be marked as read in the -other subscribed groups they were cross-posted to. If this variable is -neither @code{nil} nor @code{t}, the article will be marked as read in -both subscribed and unsubscribed groups (@pxref{Crosspost Handling}). - - -@node Crosspost Handling -@section Crosspost Handling - -@cindex velveeta -@cindex spamming -Marking cross-posted articles as read ensures that you'll never have to -read the same article more than once. Unless, of course, somebody has -posted it to several groups separately. Posting the same article to -several groups (not cross-posting) is called @dfn{spamming}, and you are -by law required to send nasty-grams to anyone who perpetrates such a -heinous crime. - -Remember: Cross-posting is kinda ok, but posting the same article -separately to several groups is not. Massive cross-posting (aka. -@dfn{velveeta}) is to be avoided at all costs, and you can even use the -@code{gnus-summary-mail-crosspost-complaint} command to complain about -excessive crossposting (@pxref{Summary Mail Commands}). - -@cindex cross-posting -@cindex Xref -@cindex @acronym{NOV} -One thing that may cause Gnus to not do the cross-posting thing -correctly is if you use an @acronym{NNTP} server that supports @sc{xover} -(which is very nice, because it speeds things up considerably) which -does not include the @code{Xref} header in its @acronym{NOV} lines. This is -Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing -even with @sc{xover} by registering the @code{Xref} lines of all -articles you actually read, but if you kill the articles, or just mark -them as read without reading them, Gnus will not get a chance to snoop -the @code{Xref} lines out of these articles, and will be unable to use -the cross reference mechanism. - -@cindex LIST overview.fmt -@cindex overview.fmt -To check whether your @acronym{NNTP} server includes the @code{Xref} header -in its overview files, try @samp{telnet your.nntp.server nntp}, -@samp{MODE READER} on @code{inn} servers, and then say @samp{LIST -overview.fmt}. This may not work, but if it does, and the last line you -get does not read @samp{Xref:full}, then you should shout and whine at -your news admin until she includes the @code{Xref} header in the -overview files. - -If you want Gnus to get the @code{Xref}s right all the time, you have to -set @code{nntp-nov-is-evil} to @code{t}, which slows things down -considerably. Also @pxref{Slow/Expensive Connection}. - -C'est la vie. - -For an alternative approach, @pxref{Duplicate Suppression}. - - -@node Duplicate Suppression -@section Duplicate Suppression - -By default, Gnus tries to make sure that you don't have to read the same -article more than once by utilizing the crossposting mechanism -(@pxref{Crosspost Handling}). However, that simple and efficient -approach may not work satisfactory for some users for various -reasons. - -@enumerate -@item -The @acronym{NNTP} server may fail to generate the @code{Xref} header. This -is evil and not very common. - -@item -The @acronym{NNTP} server may fail to include the @code{Xref} header in the -@file{.overview} data bases. This is evil and all too common, alas. - -@item -You may be reading the same group (or several related groups) from -different @acronym{NNTP} servers. - -@item -You may be getting mail that duplicates articles posted to groups. -@end enumerate - -I'm sure there are other situations where @code{Xref} handling fails as -well, but these four are the most common situations. - -If, and only if, @code{Xref} handling fails for you, then you may -consider switching on @dfn{duplicate suppression}. If you do so, Gnus -will remember the @code{Message-ID}s of all articles you have read or -otherwise marked as read, and then, as if by magic, mark them as read -all subsequent times you see them---in @emph{all} groups. Using this -mechanism is quite likely to be somewhat inefficient, but not overly -so. It's certainly preferable to reading the same articles more than -once. - -Duplicate suppression is not a very subtle instrument. It's more like a -sledge hammer than anything else. It works in a very simple -fashion---if you have marked an article as read, it adds this Message-ID -to a cache. The next time it sees this Message-ID, it will mark the -article as read with the @samp{M} mark. It doesn't care what group it -saw the article in. - -@table @code -@item gnus-suppress-duplicates -@vindex gnus-suppress-duplicates -If non-@code{nil}, suppress duplicates. - -@item gnus-save-duplicate-list -@vindex gnus-save-duplicate-list -If non-@code{nil}, save the list of duplicates to a file. This will -make startup and shutdown take longer, so the default is @code{nil}. -However, this means that only duplicate articles read in a single Gnus -session are suppressed. - -@item gnus-duplicate-list-length -@vindex gnus-duplicate-list-length -This variable says how many @code{Message-ID}s to keep in the duplicate -suppression list. The default is 10000. - -@item gnus-duplicate-file -@vindex gnus-duplicate-file -The name of the file to store the duplicate suppression list in. The -default is @file{~/News/suppression}. -@end table - -If you have a tendency to stop and start Gnus often, setting -@code{gnus-save-duplicate-list} to @code{t} is probably a good idea. If -you leave Gnus running for weeks on end, you may have it @code{nil}. On -the other hand, saving the list makes startup and shutdown much slower, -so that means that if you stop and start Gnus often, you should set -@code{gnus-save-duplicate-list} to @code{nil}. Uhm. I'll leave this up -to you to figure out, I think. - -@node Security -@section Security - -Gnus is able to verify signed messages or decrypt encrypted messages. -The formats that are supported are @acronym{PGP}, @acronym{PGP/MIME} -and @acronym{S/MIME}, however you need some external programs to get -things to work: - -@enumerate -@item -To handle @acronym{PGP} and @acronym{PGP/MIME} messages, you have to -install an OpenPGP implementation such as GnuPG. The Lisp interface -to GnuPG included with Emacs is called EasyPG (@pxref{Top, ,EasyPG, -epa, EasyPG Assistant user's manual}), but PGG (@pxref{Top, ,PGG, pgg, -PGG Manual}), and Mailcrypt are also supported. - -@item -To handle @acronym{S/MIME} message, you need to install OpenSSL. OpenSSL 0.9.6 -or newer is recommended. - -@end enumerate - -The variables that control security functionality on reading/composing -messages include: - -@table @code -@item mm-verify-option -@vindex mm-verify-option -Option of verifying signed parts. @code{never}, not verify; -@code{always}, always verify; @code{known}, only verify known -protocols. Otherwise, ask user. - -@item mm-decrypt-option -@vindex mm-decrypt-option -Option of decrypting encrypted parts. @code{never}, no decryption; -@code{always}, always decrypt; @code{known}, only decrypt known -protocols. Otherwise, ask user. - -@item mm-sign-option -@vindex mm-sign-option -Option of creating signed parts. @code{nil}, use default signing -keys; @code{guided}, ask user to select signing keys from the menu. - -@item mm-encrypt-option -@vindex mm-encrypt-option -Option of creating encrypted parts. @code{nil}, use the first -public-key matching the @samp{From:} header as the recipient; -@code{guided}, ask user to select recipient keys from the menu. - -@item mml1991-use -@vindex mml1991-use -Symbol indicating elisp interface to OpenPGP implementation for -@acronym{PGP} messages. The default is @code{epg}, but @code{pgg}, -and @code{mailcrypt} are also supported although -deprecated. By default, Gnus uses the first available interface in -this order. - -@item mml2015-use -@vindex mml2015-use -Symbol indicating elisp interface to OpenPGP implementation for -@acronym{PGP/MIME} messages. The default is @code{epg}, but -@code{pgg}, and @code{mailcrypt} are also supported -although deprecated. By default, Gnus uses the first available -interface in this order. - -@end table - -By default the buttons that display security information are not -shown, because they clutter reading the actual e-mail. You can type -@kbd{K b} manually to display the information. Use the -@code{gnus-buttonized-mime-types} and -@code{gnus-unbuttonized-mime-types} variables to control this -permanently. @ref{MIME Commands} for further details, and hints on -how to customize these variables to always display security -information. - -@cindex snarfing keys -@cindex importing PGP keys -@cindex PGP key ring import -Snarfing OpenPGP keys (i.e., importing keys from articles into your -key ring) is not supported explicitly through a menu item or command, -rather Gnus do detect and label keys as @samp{application/pgp-keys}, -allowing you to specify whatever action you think is appropriate -through the usual @acronym{MIME} infrastructure. You can use a -@file{~/.mailcap} entry (@pxref{mailcap, , mailcap, emacs-mime, The -Emacs MIME Manual}) such as the following to import keys using GNU -Privacy Guard when you click on the @acronym{MIME} button -(@pxref{Using MIME}). - -@example -application/pgp-keys; gpg --import --interactive --verbose; needsterminal -@end example -@noindent -This happens to also be the default action defined in -@code{mailcap-mime-data}. - -More information on how to set things for sending outgoing signed and -encrypted messages up can be found in the message manual -(@pxref{Security, ,Security, message, Message Manual}). - -@node Mailing List -@section Mailing List -@cindex mailing list -@cindex RFC 2396 - -@kindex A M (summary) -@findex gnus-mailing-list-insinuate -Gnus understands some mailing list fields of RFC 2369. To enable it, -add a @code{to-list} group parameter (@pxref{Group Parameters}), -possibly using @kbd{A M} (@code{gnus-mailing-list-insinuate}) in the -summary buffer. - -That enables the following commands to the summary buffer: - -@table @kbd - -@item C-c C-n h -@kindex C-c C-n h (Summary) -@findex gnus-mailing-list-help -Send a message to fetch mailing list help, if List-Help field exists. - -@item C-c C-n s -@kindex C-c C-n s (Summary) -@findex gnus-mailing-list-subscribe -Send a message to subscribe the mailing list, if List-Subscribe field exists. - -@item C-c C-n u -@kindex C-c C-n u (Summary) -@findex gnus-mailing-list-unsubscribe -Send a message to unsubscribe the mailing list, if List-Unsubscribe -field exists. - -@item C-c C-n p -@kindex C-c C-n p (Summary) -@findex gnus-mailing-list-post -Post to the mailing list, if List-Post field exists. - -@item C-c C-n o -@kindex C-c C-n o (Summary) -@findex gnus-mailing-list-owner -Send a message to the mailing list owner, if List-Owner field exists. - -@item C-c C-n a -@kindex C-c C-n a (Summary) -@findex gnus-mailing-list-archive -Browse the mailing list archive, if List-Archive field exists. - -@end table - - -@node Article Buffer -@chapter Article Buffer -@cindex article buffer - -The articles are displayed in the article buffer, of which there is only -one. All the summary buffers share the same article buffer unless you -tell Gnus otherwise. - -@menu -* Hiding Headers:: Deciding what headers should be displayed. -* Using MIME:: Pushing articles through @acronym{MIME} before reading them. -* HTML:: Reading @acronym{HTML} messages. -* Customizing Articles:: Tailoring the look of the articles. -* Article Keymap:: Keystrokes available in the article buffer. -* Misc Article:: Other stuff. -@end menu - - -@node Hiding Headers -@section Hiding Headers -@cindex hiding headers -@cindex deleting headers - -The top section of each article is the @dfn{head}. (The rest is the -@dfn{body}, but you may have guessed that already.) - -@vindex gnus-show-all-headers -There is a lot of useful information in the head: the name of the person -who wrote the article, the date it was written and the subject of the -article. That's well and nice, but there's also lots of information -most people do not want to see---what systems the article has passed -through before reaching you, the @code{Message-ID}, the -@code{References}, etc. ad nauseam---and you'll probably want to get rid -of some of those lines. If you want to keep all those lines in the -article buffer, you can set @code{gnus-show-all-headers} to @code{t}. - -Gnus provides you with two variables for sifting headers: - -@table @code - -@item gnus-visible-headers -@vindex gnus-visible-headers -If this variable is non-@code{nil}, it should be a regular expression -that says what headers you wish to keep in the article buffer. All -headers that do not match this variable will be hidden. - -For instance, if you only want to see the name of the person who wrote -the article and the subject, you'd say: - -@lisp -(setq gnus-visible-headers "^From:\\|^Subject:") -@end lisp - -This variable can also be a list of regexps to match headers to -remain visible. - -@item gnus-ignored-headers -@vindex gnus-ignored-headers -This variable is the reverse of @code{gnus-visible-headers}. If this -variable is set (and @code{gnus-visible-headers} is @code{nil}), it -should be a regular expression that matches all lines that you want to -hide. All lines that do not match this variable will remain visible. - -For instance, if you just want to get rid of the @code{References} line -and the @code{Xref} line, you might say: - -@lisp -(setq gnus-ignored-headers "^References:\\|^Xref:") -@end lisp - -This variable can also be a list of regexps to match headers to -be removed. - -Note that if @code{gnus-visible-headers} is non-@code{nil}, this -variable will have no effect. - -@end table - -@vindex gnus-sorted-header-list -Gnus can also sort the headers for you. (It does this by default.) You -can control the sorting by setting the @code{gnus-sorted-header-list} -variable. It is a list of regular expressions that says in what order -the headers are to be displayed. - -For instance, if you want the name of the author of the article first, -and then the subject, you might say something like: - -@lisp -(setq gnus-sorted-header-list '("^From:" "^Subject:")) -@end lisp - -Any headers that are to remain visible, but are not listed in this -variable, will be displayed in random order after all the headers listed in this variable. - -@findex gnus-article-hide-boring-headers -@vindex gnus-boring-article-headers -You can hide further boring headers by setting -@code{gnus-treat-hide-boring-headers} to @code{head}. What this function -does depends on the @code{gnus-boring-article-headers} variable. It's a -list, but this list doesn't actually contain header names. Instead it -lists various @dfn{boring conditions} that Gnus can check and remove -from sight. - -These conditions are: -@table @code -@item empty -Remove all empty headers. -@item followup-to -Remove the @code{Followup-To} header if it is identical to the -@code{Newsgroups} header. -@item reply-to -Remove the @code{Reply-To} header if it lists the same addresses as -the @code{From} header, or if the @code{broken-reply-to} group -parameter is set. -@item newsgroups -Remove the @code{Newsgroups} header if it only contains the current group -name. -@item to-address -Remove the @code{To} header if it only contains the address identical to -the current group's @code{to-address} parameter. -@item to-list -Remove the @code{To} header if it only contains the address identical to -the current group's @code{to-list} parameter. -@item cc-list -Remove the @code{Cc} header if it only contains the address identical to -the current group's @code{to-list} parameter. -@item date -Remove the @code{Date} header if the article is less than three days -old. -@item long-to -Remove the @code{To} and/or @code{Cc} header if it is very long. -@item many-to -Remove all @code{To} and/or @code{Cc} headers if there are more than one. -@end table - -To include these three elements, you could say something like: - -@lisp -(setq gnus-boring-article-headers - '(empty followup-to reply-to)) -@end lisp - -This is also the default value for this variable. - - -@node Using MIME -@section Using MIME -@cindex @acronym{MIME} - -Mime is a standard for waving your hands through the air, aimlessly, -while people stand around yawning. - -@acronym{MIME}, however, is a standard for encoding your articles, aimlessly, -while all newsreaders die of fear. - -@acronym{MIME} may specify what character set the article uses, the encoding -of the characters, and it also makes it possible to embed pictures and -other naughty stuff in innocent-looking articles. - -@vindex gnus-display-mime-function -@findex gnus-display-mime -Gnus pushes @acronym{MIME} articles through @code{gnus-display-mime-function} -to display the @acronym{MIME} parts. This is @code{gnus-display-mime} by -default, which creates a bundle of clickable buttons that can be used to -display, save and manipulate the @acronym{MIME} objects. - -The following commands are available when you have placed point over a -@acronym{MIME} button: - -@table @kbd -@findex gnus-article-press-button -@item RET (Article) -@kindex RET (Article) -@itemx BUTTON-2 (Article) -Toggle displaying of the @acronym{MIME} object -(@code{gnus-article-press-button}). If built-in viewers can not display -the object, Gnus resorts to external viewers in the @file{mailcap} -files. If a viewer has the @samp{copiousoutput} specification, the -object is displayed inline. - -@findex gnus-mime-view-part -@item M-RET (Article) -@kindex M-RET (Article) -@itemx v (Article) -Prompt for a method, and then view the @acronym{MIME} object using this -method (@code{gnus-mime-view-part}). - -@findex gnus-mime-view-part-as-type -@item t (Article) -@kindex t (Article) -View the @acronym{MIME} object as if it were a different @acronym{MIME} media type -(@code{gnus-mime-view-part-as-type}). - -@findex gnus-mime-view-part-as-charset -@item C (Article) -@kindex C (Article) -Prompt for a charset, and then view the @acronym{MIME} object using this -charset (@code{gnus-mime-view-part-as-charset}). - -@findex gnus-mime-save-part -@item o (Article) -@kindex o (Article) -Prompt for a file name, and then save the @acronym{MIME} object -(@code{gnus-mime-save-part}). - -@findex gnus-mime-save-part-and-strip -@item C-o (Article) -@kindex C-o (Article) -Prompt for a file name, then save the @acronym{MIME} object and strip it from -the article. Then proceed to article editing, where a reasonable -suggestion is being made on how the altered article should look -like. The stripped @acronym{MIME} object will be referred via the -message/external-body @acronym{MIME} type. -(@code{gnus-mime-save-part-and-strip}). - -@findex gnus-mime-replace-part -@item r (Article) -@kindex r (Article) -Prompt for a file name, replace the @acronym{MIME} object with an -external body referring to the file via the message/external-body -@acronym{MIME} type. (@code{gnus-mime-replace-part}). - -@findex gnus-mime-delete-part -@item d (Article) -@kindex d (Article) -Delete the @acronym{MIME} object from the article and replace it with some -information about the removed @acronym{MIME} object -(@code{gnus-mime-delete-part}). - -@c FIXME: gnus-auto-select-part should be documented here - -@findex gnus-mime-copy-part -@item c (Article) -@kindex c (Article) -Copy the @acronym{MIME} object to a fresh buffer and display this buffer -(@code{gnus-mime-copy-part}). If given a prefix, copy the raw contents -without decoding. If given a numerical prefix, you can do semi-manual -charset stuff (see @code{gnus-summary-show-article-charset-alist} in -@ref{Paging the Article}). Compressed files like @file{.gz} and -@file{.bz2} are automatically decompressed if -@code{auto-compression-mode} is enabled (@pxref{Compressed Files,, -Accessing Compressed Files, emacs, The Emacs Editor}). - -@findex gnus-mime-print-part -@item p (Article) -@kindex p (Article) -Print the @acronym{MIME} object (@code{gnus-mime-print-part}). This -command respects the @samp{print=} specifications in the -@file{.mailcap} file. - -@findex gnus-mime-inline-part -@item i (Article) -@kindex i (Article) -Insert the contents of the @acronym{MIME} object into the buffer -(@code{gnus-mime-inline-part}) as @samp{text/plain}. If given a prefix, insert -the raw contents without decoding. If given a numerical prefix, you can -do semi-manual charset stuff (see -@code{gnus-summary-show-article-charset-alist} in @ref{Paging the -Article}). Compressed files like @file{.gz} and @file{.bz2} are -automatically decompressed depending on @code{jka-compr} regardless of -@code{auto-compression-mode} (@pxref{Compressed Files,, Accessing -Compressed Files, emacs, The Emacs Editor}). - -@findex gnus-mime-view-part-internally -@item E (Article) -@kindex E (Article) -View the @acronym{MIME} object with an internal viewer. If no internal -viewer is available, use an external viewer -(@code{gnus-mime-view-part-internally}). - -@findex gnus-mime-view-part-externally -@item e (Article) -@kindex e (Article) -View the @acronym{MIME} object with an external viewer. -(@code{gnus-mime-view-part-externally}). - -@findex gnus-mime-pipe-part -@item | (Article) -@kindex | (Article) -Output the @acronym{MIME} object to a process (@code{gnus-mime-pipe-part}). - -@findex gnus-mime-action-on-part -@item . (Article) -@kindex . (Article) -Interactively run an action on the @acronym{MIME} object -(@code{gnus-mime-action-on-part}). - -@end table - -Gnus will display some @acronym{MIME} objects automatically. The way Gnus -determines which parts to do this with is described in the Emacs -@acronym{MIME} manual. - -It might be best to just use the toggling functions from the article -buffer to avoid getting nasty surprises. (For instance, you enter the -group @samp{alt.sing-a-long} and, before you know it, @acronym{MIME} has -decoded the sound file in the article and some horrible sing-a-long song -comes screaming out your speakers, and you can't find the volume button, -because there isn't one, and people are starting to look at you, and you -try to stop the program, but you can't, and you can't find the program -to control the volume, and everybody else in the room suddenly decides -to look at you disdainfully, and you'll feel rather stupid.) - -Any similarity to real events and people is purely coincidental. Ahem. - -Also @pxref{MIME Commands}. - - -@node HTML -@section @acronym{HTML} -@cindex @acronym{HTML} - -If you have @code{w3m} installed on your system, Gnus can display -@acronym{HTML} articles in the article buffer. There are many Gnus -add-ons for doing this, using various approaches, but there's one -(sort of) built-in method that's used by default. - -For a complete overview, consult @xref{Display Customization, -,Display Customization, emacs-mime, The Emacs MIME Manual}. This -section only describes the default method. - -@table @code -@item mm-text-html-renderer -@vindex mm-text-html-renderer -If set to @code{gnus-article-html}, Gnus will use the built-in method, -that's based on @code{w3m}. - -@item gnus-blocked-images -@vindex gnus-blocked-images -External images that have @acronym{URL}s that match this regexp won't -be fetched and displayed. For instance, do block all @acronym{URL}s -that have the string ``ads'' in them, do the following: - -@lisp -(setq gnus-blocked-images "ads") -@end lisp - -This can also be a function to be evaluated. If so, it will be -called with the group name as the parameter. The default value is -@code{gnus-block-private-groups}, which will return @samp{"."} for -anything that isn't a newsgroup. This means that no external images -will be fetched as a result of reading mail, so that nobody can use -web bugs (and the like) to track whether you've read email. - -Also @pxref{Misc Article} for @code{gnus-inhibit-images}. - -@item gnus-html-cache-directory -@vindex gnus-html-cache-directory -Gnus will download and cache images according to how -@code{gnus-blocked-images} is set. These images will be stored in -this directory. - -@item gnus-html-cache-size -@vindex gnus-html-cache-size -When @code{gnus-html-cache-size} bytes have been used in that -directory, the oldest files will be deleted. The default is 500MB. - -@item gnus-html-frame-width -@vindex gnus-html-frame-width -The width to use when rendering HTML. The default is 70. - -@item gnus-max-image-proportion -@vindex gnus-max-image-proportion -How big pictures displayed are in relation to the window they're in. -A value of 0.7 (the default) means that they are allowed to take up -70% of the width and height of the window. If they are larger than -this, and Emacs supports it, then the images will be rescaled down to -fit these criteria. - -@end table - -To use this, make sure that you have @code{w3m} and @code{curl} -installed. If you have, then Gnus should display @acronym{HTML} -automatically. - - - -@node Customizing Articles -@section Customizing Articles -@cindex article customization - -A slew of functions for customizing how the articles are to look like -exist. You can call these functions interactively -(@pxref{Article Washing}), or you can have them -called automatically when you select the articles. - -To have them called automatically, you should set the corresponding -``treatment'' variable. For instance, to have headers hidden, you'd set -@code{gnus-treat-hide-headers}. Below is a list of variables that can -be set, but first we discuss the values these variables can have. - -Note: Some values, while valid, make little sense. Check the list below -for sensible values. - -@enumerate -@item -@code{nil}: Don't do this treatment. - -@item -@code{t}: Do this treatment on all body parts. - -@item -@code{head}: Do the treatment on the headers. - -@item -@code{first}: Do this treatment on the first body part. - -@item -@code{last}: Do this treatment on the last body part. - -@item -An integer: Do this treatment on all body parts that have a length less -than this number. - -@item -A list of strings: Do this treatment on all body parts that are in -articles that are read in groups that have names that match one of the -regexps in the list. - -@item -A list where the first element is not a string: - -The list is evaluated recursively. The first element of the list is a -predicate. The following predicates are recognized: @code{or}, -@code{and}, @code{not} and @code{typep}. Here's an example: - -@lisp -(or last - (typep "text/x-vcard")) -@end lisp - -@end enumerate - -You may have noticed that the word @dfn{part} is used here. This refers -to the fact that some messages are @acronym{MIME} multipart articles that may -be divided into several parts. Articles that are not multiparts are -considered to contain just a single part. - -@vindex gnus-article-treat-types -Are the treatments applied to all sorts of multipart parts? Yes, if you -want to, but by default, only @samp{text/plain} parts are given the -treatment. This is controlled by the @code{gnus-article-treat-types} -variable, which is a list of regular expressions that are matched to the -type of the part. This variable is ignored if the value of the -controlling variable is a predicate list, as described above. - -@ifinfo -@c Avoid sort of redundant entries in the same section for the printed -@c manual, but add them in info to allow `i gnus-treat-foo-bar RET' or -@c `i foo-bar'. -@vindex gnus-treat-buttonize -@vindex gnus-treat-buttonize-head -@vindex gnus-treat-capitalize-sentences -@vindex gnus-treat-overstrike -@vindex gnus-treat-strip-cr -@vindex gnus-treat-strip-headers-in-body -@vindex gnus-treat-strip-leading-blank-lines -@vindex gnus-treat-strip-multiple-blank-lines -@vindex gnus-treat-strip-pem -@vindex gnus-treat-strip-trailing-blank-lines -@vindex gnus-treat-unsplit-urls -@vindex gnus-treat-wash-html -@vindex gnus-treat-date -@vindex gnus-treat-from-picon -@vindex gnus-treat-mail-picon -@vindex gnus-treat-newsgroups-picon -@vindex gnus-treat-from-gravatar -@vindex gnus-treat-mail-gravatar -@vindex gnus-treat-display-smileys -@vindex gnus-treat-body-boundary -@vindex gnus-treat-display-x-face -@vindex gnus-treat-display-face -@vindex gnus-treat-emphasize -@vindex gnus-treat-fill-article -@vindex gnus-treat-fill-long-lines -@vindex gnus-treat-hide-boring-headers -@vindex gnus-treat-hide-citation -@vindex gnus-treat-hide-citation-maybe -@vindex gnus-treat-hide-headers -@vindex gnus-treat-hide-signature -@vindex gnus-treat-strip-banner -@vindex gnus-treat-strip-list-identifiers -@vindex gnus-treat-highlight-citation -@vindex gnus-treat-highlight-headers -@vindex gnus-treat-highlight-signature -@vindex gnus-treat-play-sounds -@vindex gnus-treat-x-pgp-sig -@vindex gnus-treat-unfold-headers -@vindex gnus-treat-fold-headers -@vindex gnus-treat-fold-newsgroups -@vindex gnus-treat-leading-whitespace -@end ifinfo - -The following treatment options are available. The easiest way to -customize this is to examine the @code{gnus-article-treat} customization -group. Values in parenthesis are suggested sensible values. Others are -possible but those listed are probably sufficient for most people. - -@table @code -@item gnus-treat-buttonize (t, integer) -@item gnus-treat-buttonize-head (head) - -@xref{Article Buttons}. - -@item gnus-treat-capitalize-sentences (t, integer) -@item gnus-treat-overstrike (t, integer) -@item gnus-treat-strip-cr (t, integer) -@item gnus-treat-strip-headers-in-body (t, integer) -@item gnus-treat-strip-leading-blank-lines (t, first, integer) -@item gnus-treat-strip-multiple-blank-lines (t, integer) -@item gnus-treat-strip-pem (t, last, integer) -@item gnus-treat-strip-trailing-blank-lines (t, last, integer) -@item gnus-treat-unsplit-urls (t, integer) -@item gnus-treat-wash-html (t, integer) - -@xref{Article Washing}. - -@item gnus-treat-date (head) - -This will transform/add date headers according to the -@code{gnus-article-date-headers} variable. This is a list of Date -headers to display. The formats available are: - -@table @code -@item ut -Universal time, aka GMT, aka ZULU. - -@item local -The user's local time zone. - -@item english -A semi-readable English sentence. - -@item lapsed -The time elapsed since the message was posted. - -@item combined-lapsed -Both the original date header and a (shortened) elapsed time. - -@item original -The original date header. - -@item iso8601 -ISO8601 format, i.e., ``2010-11-23T22:05:21''. - -@item user-defined -A format done according to the @code{gnus-article-time-format} -variable. - -@end table - -@xref{Article Date}. - -@item gnus-treat-from-picon (head) -@item gnus-treat-mail-picon (head) -@item gnus-treat-newsgroups-picon (head) - -@xref{Picons}. - -@item gnus-treat-from-gravatar (head) -@item gnus-treat-mail-gravatar (head) - -@xref{Gravatars}. - -@item gnus-treat-display-smileys (t, integer) - -@item gnus-treat-body-boundary (head) - -@vindex gnus-body-boundary-delimiter -Adds a delimiter between header and body, the string used as delimiter -is controlled by @code{gnus-body-boundary-delimiter}. - -@xref{Smileys}. - -@vindex gnus-treat-display-x-face -@item gnus-treat-display-x-face (head) - -@xref{X-Face}. - -@vindex gnus-treat-display-face -@item gnus-treat-display-face (head) - -@xref{Face}. - -@vindex gnus-treat-emphasize -@item gnus-treat-emphasize (t, head, integer) -@vindex gnus-treat-fill-article -@item gnus-treat-fill-article (t, integer) -@vindex gnus-treat-fill-long-lines -@item gnus-treat-fill-long-lines (t, integer) -@vindex gnus-treat-hide-boring-headers -@item gnus-treat-hide-boring-headers (head) -@vindex gnus-treat-hide-citation -@item gnus-treat-hide-citation (t, integer) -@vindex gnus-treat-hide-citation-maybe -@item gnus-treat-hide-citation-maybe (t, integer) -@vindex gnus-treat-hide-headers -@item gnus-treat-hide-headers (head) -@vindex gnus-treat-hide-signature -@item gnus-treat-hide-signature (t, last) -@vindex gnus-treat-strip-banner -@item gnus-treat-strip-banner (t, last) -@vindex gnus-treat-strip-list-identifiers -@item gnus-treat-strip-list-identifiers (head) - -@xref{Article Hiding}. - -@vindex gnus-treat-highlight-citation -@item gnus-treat-highlight-citation (t, integer) -@vindex gnus-treat-highlight-headers -@item gnus-treat-highlight-headers (head) -@vindex gnus-treat-highlight-signature -@item gnus-treat-highlight-signature (t, last, integer) - -@xref{Article Highlighting}. - -@vindex gnus-treat-play-sounds -@item gnus-treat-play-sounds -@item gnus-treat-ansi-sequences (t) -@vindex gnus-treat-x-pgp-sig -@item gnus-treat-x-pgp-sig (head) - -@vindex gnus-treat-unfold-headers -@item gnus-treat-unfold-headers (head) -@vindex gnus-treat-fold-headers -@item gnus-treat-fold-headers (head) -@vindex gnus-treat-fold-newsgroups -@item gnus-treat-fold-newsgroups (head) -@vindex gnus-treat-leading-whitespace -@item gnus-treat-leading-whitespace (head) - -@xref{Article Header}. - - -@end table - -@vindex gnus-part-display-hook -You can, of course, write your own functions to be called from -@code{gnus-part-display-hook}. The functions are called narrowed to the -part, and you can do anything you like, pretty much. There is no -information that you have to keep in the buffer---you can change -everything. - - -@node Article Keymap -@section Article Keymap - -Most of the keystrokes in the summary buffer can also be used in the -article buffer. They should behave as if you typed them in the summary -buffer, which means that you don't actually have to have a summary -buffer displayed while reading. You can do it all from the article -buffer. - -@kindex v (Article) -@cindex keys, reserved for users (Article) -The key @kbd{v} is reserved for users. You can bind it to some -command or better use it as a prefix key. - -A few additional keystrokes are available: - -@table @kbd - -@item SPACE -@kindex SPACE (Article) -@findex gnus-article-next-page -Scroll forwards one page (@code{gnus-article-next-page}). -This is exactly the same as @kbd{h SPACE h}. - -@item DEL -@kindex DEL (Article) -@findex gnus-article-prev-page -Scroll backwards one page (@code{gnus-article-prev-page}). -This is exactly the same as @kbd{h DEL h}. - -@item C-c ^ -@kindex C-c ^ (Article) -@findex gnus-article-refer-article -If point is in the neighborhood of a @code{Message-ID} and you press -@kbd{C-c ^}, Gnus will try to get that article from the server -(@code{gnus-article-refer-article}). - -@item C-c C-m -@kindex C-c C-m (Article) -@findex gnus-article-mail -Send a reply to the address near point (@code{gnus-article-mail}). If -given a prefix, include the mail. - -@item s -@kindex s (Article) -@findex gnus-article-show-summary -Reconfigure the buffers so that the summary buffer becomes visible -(@code{gnus-article-show-summary}). - -@item ? -@kindex ? (Article) -@findex gnus-article-describe-briefly -Give a very brief description of the available keystrokes -(@code{gnus-article-describe-briefly}). - -@item TAB -@kindex TAB (Article) -@findex gnus-article-next-button -Go to the next button, if any (@code{gnus-article-next-button}). This -only makes sense if you have buttonizing turned on. - -@item M-TAB -@kindex M-TAB (Article) -@findex gnus-article-prev-button -Go to the previous button, if any (@code{gnus-article-prev-button}). - -@item R -@kindex R (Article) -@findex gnus-article-reply-with-original -Send a reply to the current article and yank the current article -(@code{gnus-article-reply-with-original}). If the region is active, -only yank the text in the region. - -@item S W -@kindex S W (Article) -@findex gnus-article-wide-reply-with-original -Send a wide reply to the current article and yank the current article -(@code{gnus-article-wide-reply-with-original}). If the region is -active, only yank the text in the region. - -@item F -@kindex F (Article) -@findex gnus-article-followup-with-original -Send a followup to the current article and yank the current article -(@code{gnus-article-followup-with-original}). If the region is active, -only yank the text in the region. - - -@end table - - -@node Misc Article -@section Misc Article - -@table @code - -@item gnus-single-article-buffer -@vindex gnus-single-article-buffer -@cindex article buffers, several -If non-@code{nil}, use the same article buffer for all the groups. -(This is the default.) If @code{nil}, each group will have its own -article buffer. - -@item gnus-widen-article-window -@cindex gnus-widen-article-window -If non-@code{nil}, selecting the article buffer with the @kbd{h} -command will ``widen'' the article window to take the entire frame. - -@vindex gnus-article-decode-hook -@item gnus-article-decode-hook -@cindex @acronym{MIME} -Hook used to decode @acronym{MIME} articles. The default value is -@code{(article-decode-charset article-decode-encoded-words)} - -@vindex gnus-article-prepare-hook -@item gnus-article-prepare-hook -This hook is called right after the article has been inserted into the -article buffer. It is mainly intended for functions that do something -depending on the contents; it should probably not be used for changing -the contents of the article buffer. - -@item gnus-article-mode-hook -@vindex gnus-article-mode-hook -Hook called in article mode buffers. - -@item gnus-article-mode-syntax-table -@vindex gnus-article-mode-syntax-table -Syntax table used in article buffers. It is initialized from -@code{text-mode-syntax-table}. - -@vindex gnus-article-over-scroll -@item gnus-article-over-scroll -If non-@code{nil}, allow scrolling the article buffer even when there -no more new text to scroll in. The default is @code{nil}. - -@vindex gnus-article-mode-line-format -@item gnus-article-mode-line-format -This variable is a format string along the same lines as -@code{gnus-summary-mode-line-format} (@pxref{Summary Buffer Mode -Line}). It accepts the same format specifications as that variable, -with two extensions: - -@table @samp - -@item w -The @dfn{wash status} of the article. This is a short string with one -character for each possible article wash operation that may have been -performed. The characters and their meaning: - -@table @samp - -@item c -Displayed when cited text may be hidden in the article buffer. - -@item h -Displayed when headers are hidden in the article buffer. - -@item p -Displayed when article is digitally signed or encrypted, and Gnus has -hidden the security headers. (N.B. does not tell anything about -security status, i.e. good or bad signature.) - -@item s -Displayed when the signature has been hidden in the Article buffer. - -@item o -Displayed when Gnus has treated overstrike characters in the article buffer. - -@item e -Displayed when Gnus has treated emphasized strings in the article buffer. - -@end table - -@item m -The number of @acronym{MIME} parts in the article. - -@end table - -@vindex gnus-break-pages - -@item gnus-break-pages -Controls whether @dfn{page breaking} is to take place. If this variable -is non-@code{nil}, the articles will be divided into pages whenever a -page delimiter appears in the article. If this variable is @code{nil}, -paging will not be done. - -@item gnus-page-delimiter -@vindex gnus-page-delimiter -This is the delimiter mentioned above. By default, it is @samp{^L} -(formfeed). - -@cindex IDNA -@cindex internationalized domain names -@vindex gnus-use-idna -@item gnus-use-idna -This variable controls whether Gnus performs IDNA decoding of -internationalized domain names inside @samp{From}, @samp{To} and -@samp{Cc} headers. @xref{IDNA, ,IDNA,message, The Message Manual}, -for how to compose such messages. This requires -@uref{http://www.gnu.org/software/libidn/, GNU Libidn}, and this -variable is only enabled if you have installed it. - -@vindex gnus-inhibit-images -@item gnus-inhibit-images -If this is non-@code{nil}, inhibit displaying of images inline in the -article body. It is effective to images that are in articles as -@acronym{MIME} parts, and images in @acronym{HTML} articles rendered -when @code{mm-text-html-renderer} (@pxref{Display Customization, -,Display Customization, emacs-mime, The Emacs MIME Manual}) is -@code{shr} or @code{gnus-w3m}. - -@end table - - -@node Composing Messages -@chapter Composing Messages -@cindex composing messages -@cindex messages -@cindex mail -@cindex sending mail -@cindex reply -@cindex followup -@cindex post -@cindex using gpg -@cindex using s/mime -@cindex using smime - -@kindex C-c C-c (Post) -All commands for posting and mailing will put you in a message buffer -where you can edit the article all you like, before you send the -article by pressing @kbd{C-c C-c}. @xref{Top, , Overview, message, -Message Manual}. Where the message will be posted/mailed to depends -on your setup (@pxref{Posting Server}). - -@menu -* Mail:: Mailing and replying. -* Posting Server:: What server should you post and mail via? -* POP before SMTP:: You cannot send a mail unless you read a mail. -* Mail and Post:: Mailing and posting at the same time. -* Archived Messages:: Where Gnus stores the messages you've sent. -* Posting Styles:: An easier way to specify who you are. -* Drafts:: Postponing messages and rejected messages. -* Rejected Articles:: What happens if the server doesn't like your article? -* Signing and encrypting:: How to compose secure messages. -@end menu - -Also @pxref{Canceling and Superseding} for information on how to -remove articles you shouldn't have posted. - - -@node Mail -@section Mail - -Variables for customizing outgoing mail: - -@table @code -@item gnus-uu-digest-headers -@vindex gnus-uu-digest-headers -List of regexps to match headers included in digested messages. The -headers will be included in the sequence they are matched. If -@code{nil} include all headers. - -@item gnus-add-to-list -@vindex gnus-add-to-list -If non-@code{nil}, add a @code{to-list} group parameter to mail groups -that have none when you do a @kbd{a}. - -@item gnus-confirm-mail-reply-to-news -@vindex gnus-confirm-mail-reply-to-news -If non-@code{nil}, Gnus will ask you for a confirmation when you are -about to reply to news articles by mail. If it is @code{nil}, nothing -interferes in what you want to do. This can also be a function -receiving the group name as the only parameter which should return -non-@code{nil} if a confirmation is needed, or a regular expression -matching group names, where confirmation should be asked for. - -If you find yourself never wanting to reply to mail, but occasionally -press @kbd{R} anyway, this variable might be for you. - -@item gnus-confirm-treat-mail-like-news -@vindex gnus-confirm-treat-mail-like-news -If non-@code{nil}, Gnus also requests confirmation according to -@code{gnus-confirm-mail-reply-to-news} when replying to mail. This is -useful for treating mailing lists like newsgroups. - -@end table - - -@node Posting Server -@section Posting Server - -When you press those magical @kbd{C-c C-c} keys to ship off your latest -(extremely intelligent, of course) article, where does it go? - -Thank you for asking. I hate you. - -It can be quite complicated. - -@vindex gnus-post-method -When posting news, Message usually invokes @code{message-send-news} -(@pxref{News Variables, , News Variables, message, Message Manual}). -Normally, Gnus will post using the same select method as you're -reading from (which might be convenient if you're reading lots of -groups from different private servers). However. If the server -you're reading from doesn't allow posting, just reading, you probably -want to use some other server to post your (extremely intelligent and -fabulously interesting) articles. You can then set the -@code{gnus-post-method} to some other method: - -@lisp -(setq gnus-post-method '(nnspool "")) -@end lisp - -Now, if you've done this, and then this server rejects your article, or -this server is down, what do you do then? To override this variable you -can use a non-zero prefix to the @kbd{C-c C-c} command to force using -the ``current'' server, to get back the default behavior, for posting. - -If you give a zero prefix (i.e., @kbd{C-u 0 C-c C-c}) to that command, -Gnus will prompt you for what method to use for posting. - -You can also set @code{gnus-post-method} to a list of select methods. -If that's the case, Gnus will always prompt you for what method to use -for posting. - -Finally, if you want to always post using the native select method, -you can set this variable to @code{native}. - -@vindex message-send-mail-function -When sending mail, Message invokes the function specified by the -variable @code{message-send-mail-function}. Gnus tries to set it to a -value suitable for your system. -@xref{Mail Variables, ,Mail Variables,message,Message manual}, for more -information. - -@node POP before SMTP -@section POP before SMTP -@cindex pop before smtp -@findex message-smtpmail-send-it -@findex mail-source-touch-pop - -Does your @acronym{ISP} require the @acronym{POP}-before-@acronym{SMTP} -authentication? It is whether you need to connect to the @acronym{POP} -mail server within a certain time before sending mails. If so, there is -a convenient way. To do that, put the following lines in your -@file{~/.gnus.el} file: - -@lisp -(setq message-send-mail-function 'message-smtpmail-send-it) -(add-hook 'message-send-mail-hook 'mail-source-touch-pop) -@end lisp - -@noindent -It means to let Gnus connect to the @acronym{POP} mail server in advance -whenever you send a mail. The @code{mail-source-touch-pop} function -does only a @acronym{POP} authentication according to the value of -@code{mail-sources} without fetching mails, just before sending a mail. -Note that you have to use @code{message-smtpmail-send-it} which runs -@code{message-send-mail-hook} rather than @code{smtpmail-send-it} and -set the value of @code{mail-sources} for a @acronym{POP} connection -correctly. @xref{Mail Sources}. - -If you have two or more @acronym{POP} mail servers set in -@code{mail-sources}, you may want to specify one of them to -@code{mail-source-primary-source} as the @acronym{POP} mail server to be -used for the @acronym{POP}-before-@acronym{SMTP} authentication. If it -is your primary @acronym{POP} mail server (i.e., you are fetching mails -mainly from that server), you can set it permanently as follows: - -@lisp -(setq mail-source-primary-source - '(pop :server "pop3.mail.server" - :password "secret")) -@end lisp - -@noindent -Otherwise, bind it dynamically only when performing the -@acronym{POP}-before-@acronym{SMTP} authentication as follows: - -@lisp -(add-hook 'message-send-mail-hook - (lambda () - (let ((mail-source-primary-source - '(pop :server "pop3.mail.server" - :password "secret"))) - (mail-source-touch-pop)))) -@end lisp - -@node Mail and Post -@section Mail and Post - -Here's a list of variables relevant to both mailing and -posting: - -@table @code -@item gnus-mailing-list-groups -@findex gnus-mailing-list-groups -@cindex mailing lists - -If your news server offers groups that are really mailing lists -gatewayed to the @acronym{NNTP} server, you can read those groups without -problems, but you can't post/followup to them without some difficulty. -One solution is to add a @code{to-address} to the group parameters -(@pxref{Group Parameters}). An easier thing to do is set the -@code{gnus-mailing-list-groups} to a regexp that matches the groups that -really are mailing lists. Then, at least, followups to the mailing -lists will work most of the time. Posting to these groups (@kbd{a}) is -still a pain, though. - -@item gnus-user-agent -@vindex gnus-user-agent -@cindex User-Agent - -This variable controls which information should be exposed in the -User-Agent header. It can be a list of symbols or a string. Valid -symbols are @code{gnus} (show Gnus version) and @code{emacs} (show Emacs -version). In addition to the Emacs version, you can add @code{codename} -(show (S)XEmacs codename) or either @code{config} (show system -configuration) or @code{type} (show system type). If you set it to a -string, be sure to use a valid format, see RFC 2616. - -@end table - -You may want to do spell-checking on messages that you send out. Or, if -you don't want to spell-check by hand, you could add automatic -spell-checking via the @code{ispell} package: - -@cindex ispell -@findex ispell-message -@lisp -(add-hook 'message-send-hook 'ispell-message) -@end lisp - -If you want to change the @code{ispell} dictionary based on what group -you're in, you could say something like the following: - -@lisp -(add-hook 'gnus-select-group-hook - (lambda () - (cond - ((string-match - "^de\\." (gnus-group-real-name gnus-newsgroup-name)) - (ispell-change-dictionary "deutsch")) - (t - (ispell-change-dictionary "english"))))) -@end lisp - -Modify to suit your needs. - -@vindex gnus-message-highlight-citation -If @code{gnus-message-highlight-citation} is t, different levels of -citations are highlighted like in Gnus article buffers also in message -mode buffers. - -@node Archived Messages -@section Archived Messages -@cindex archived messages -@cindex sent messages - -Gnus provides a few different methods for storing the mail and news you -send. The default method is to use the @dfn{archive virtual server} to -store the messages. If you want to disable this completely, the -@code{gnus-message-archive-group} variable should be @code{nil}. The -default is "sent.%Y-%m", which gives you one archive group per month. - -For archiving interesting messages in a group you read, see the -@kbd{B c} (@code{gnus-summary-copy-article}) command (@pxref{Mail -Group Commands}). - -@vindex gnus-message-archive-method -@code{gnus-message-archive-method} says what virtual server Gnus is to -use to store sent messages. The default is @code{"archive"}, and when -actually being used it is expanded into: - -@lisp -(nnfolder "archive" - (nnfolder-directory "~/Mail/archive") - (nnfolder-active-file "~/Mail/archive/active") - (nnfolder-get-new-mail nil) - (nnfolder-inhibit-expiry t)) -@end lisp - -@quotation -@vindex gnus-update-message-archive-method -Note: a server like this is saved in the @file{~/.newsrc.eld} file first -so that it may be used as a real method of the server which is named -@code{"archive"} (that is, for the case where -@code{gnus-message-archive-method} is set to @code{"archive"}) ever -since. If it once has been saved, it will never be updated by default -even if you change the value of @code{gnus-message-archive-method} -afterward. Therefore, the server @code{"archive"} doesn't necessarily -mean the @code{nnfolder} server like this at all times. If you want the -saved method to reflect always the value of -@code{gnus-message-archive-method}, set the -@code{gnus-update-message-archive-method} variable to a non-@code{nil} -value. The default value of this variable is @code{nil}. -@end quotation - -You can, however, use any mail select method (@code{nnml}, -@code{nnmbox}, etc.). @code{nnfolder} is a quite likable select method -for doing this sort of thing, though. If you don't like the default -directory chosen, you could say something like: - -@lisp -(setq gnus-message-archive-method - '(nnfolder "archive" - (nnfolder-inhibit-expiry t) - (nnfolder-active-file "~/News/sent-mail/active") - (nnfolder-directory "~/News/sent-mail/"))) -@end lisp - -@vindex gnus-message-archive-group -@cindex Gcc -Gnus will insert @code{Gcc} headers in all outgoing messages that point -to one or more group(s) on that server. Which group to use is -determined by the @code{gnus-message-archive-group} variable. - -This variable can be used to do the following: - -@table @asis -@item a string -Messages will be saved in that group. - -Note that you can include a select method in the group name, then the -message will not be stored in the select method given by -@code{gnus-message-archive-method}, but in the select method specified -by the group name, instead. Suppose @code{gnus-message-archive-method} -has the default value shown above. Then setting -@code{gnus-message-archive-group} to @code{"foo"} means that outgoing -messages are stored in @samp{nnfolder+archive:foo}, but if you use the -value @code{"nnml:foo"}, then outgoing messages will be stored in -@samp{nnml:foo}. - -@item a list of strings -Messages will be saved in all those groups. - -@item an alist of regexps, functions and forms -When a key ``matches'', the result is used. - -@item @code{nil} -No message archiving will take place. -@end table - -Let's illustrate: - -Just saving to a single group called @samp{MisK}: -@lisp -(setq gnus-message-archive-group "MisK") -@end lisp - -Saving to two groups, @samp{MisK} and @samp{safe}: -@lisp -(setq gnus-message-archive-group '("MisK" "safe")) -@end lisp - -Save to different groups based on what group you are in: -@lisp -(setq gnus-message-archive-group - '(("^alt" "sent-to-alt") - ("mail" "sent-to-mail") - (".*" "sent-to-misc"))) -@end lisp - -More complex stuff: -@lisp -(setq gnus-message-archive-group - '((if (message-news-p) - "misc-news" - "misc-mail"))) -@end lisp - -How about storing all news messages in one file, but storing all mail -messages in one file per month: - -@lisp -(setq gnus-message-archive-group - '((if (message-news-p) - "misc-news" - (concat "mail." (format-time-string "%Y-%m"))))) -@end lisp - -Now, when you send a message off, it will be stored in the appropriate -group. (If you want to disable storing for just one particular message, -you can just remove the @code{Gcc} header that has been inserted.) The -archive group will appear in the group buffer the next time you start -Gnus, or the next time you press @kbd{F} in the group buffer. You can -enter it and read the articles in it just like you'd read any other -group. If the group gets really big and annoying, you can simply rename -if (using @kbd{G r} in the group buffer) to something -nice---@samp{misc-mail-september-1995}, or whatever. New messages will -continue to be stored in the old (now empty) group. - -@table @code -@item gnus-gcc-mark-as-read -@vindex gnus-gcc-mark-as-read -If non-@code{nil}, automatically mark @code{Gcc} articles as read. - -@item gnus-gcc-externalize-attachments -@vindex gnus-gcc-externalize-attachments -If @code{nil}, attach files as normal parts in Gcc copies; if a regexp -and matches the Gcc group name, attach files as external parts; if it is -@code{all}, attach local files as external parts; if it is other -non-@code{nil}, the behavior is the same as @code{all}, but it may be -changed in the future. - -@end table - - -@node Posting Styles -@section Posting Styles -@cindex posting styles -@cindex styles - -All them variables, they make my head swim. - -So what if you want a different @code{Organization} and signature based -on what groups you post to? And you post both from your home machine -and your work machine, and you want different @code{From} lines, and so -on? - -@vindex gnus-posting-styles -One way to do stuff like that is to write clever hooks that change the -variables you need to have changed. That's a bit boring, so somebody -came up with the bright idea of letting the user specify these things in -a handy alist. Here's an example of a @code{gnus-posting-styles} -variable: - -@lisp -((".*" - (signature "Peace and happiness") - (organization "What me?")) - ("^comp" - (signature "Death to everybody")) - ("comp.emacs.i-love-it" - (organization "Emacs is it"))) -@end lisp - -As you might surmise from this example, this alist consists of several -@dfn{styles}. Each style will be applicable if the first element -``matches'', in some form or other. The entire alist will be iterated -over, from the beginning towards the end, and each match will be -applied, which means that attributes in later styles that match override -the same attributes in earlier matching styles. So -@samp{comp.programming.literate} will have the @samp{Death to everybody} -signature and the @samp{What me?} @code{Organization} header. - -The first element in each style is called the @code{match}. If it's a -string, then Gnus will try to regexp match it against the group name. -If it is the form @code{(header @var{match} @var{regexp})}, then Gnus -will look in the original article for a header whose name is -@var{match} and compare that @var{regexp}. @var{match} and -@var{regexp} are strings. (The original article is the one you are -replying or following up to. If you are not composing a reply or a -followup, then there is nothing to match against.) If the -@code{match} is a function symbol, that function will be called with -no arguments. If it's a variable symbol, then the variable will be -referenced. If it's a list, then that list will be @code{eval}ed. In -any case, if this returns a non-@code{nil} value, then the style is -said to @dfn{match}. - -Each style may contain an arbitrary amount of @dfn{attributes}. Each -attribute consists of a @code{(@var{name} @var{value})} pair. In -addition, you can also use the @code{(@var{name} :file @var{value})} -form or the @code{(@var{name} :value @var{value})} form. Where -@code{:file} signifies @var{value} represents a file name and its -contents should be used as the attribute value, @code{:value} signifies -@var{value} does not represent a file name explicitly. The attribute -name can be one of: - -@itemize @bullet -@item @code{signature} -@item @code{signature-file} -@item @code{x-face-file} -@item @code{address}, overriding @code{user-mail-address} -@item @code{name}, overriding @code{(user-full-name)} -@item @code{body} -@end itemize - -Note that the @code{signature-file} attribute honors the variable -@code{message-signature-directory}. - -The attribute name can also be a string or a symbol. In that case, -this will be used as a header name, and the value will be inserted in -the headers of the article; if the value is @code{nil}, the header -name will be removed. If the attribute name is @code{eval}, the form -is evaluated, and the result is thrown away. - -The attribute value can be a string, a function with zero arguments -(the return value will be used), a variable (its value will be used) -or a list (it will be @code{eval}ed and the return value will be -used). The functions and sexps are called/@code{eval}ed in the -message buffer that is being set up. The headers of the current -article are available through the @code{message-reply-headers} -variable, which is a vector of the following headers: number subject -from date id references chars lines xref extra. - -In the case of a string value, if the @code{match} is a regular -expression, a @samp{gnus-match-substitute-replacement} is proceed on -the value to replace the positional parameters @samp{\@var{n}} by the -corresponding parenthetical matches (see @xref{Replacing Match,, -Replacing the Text that Matched, elisp, The Emacs Lisp Reference Manual}.) - -@vindex message-reply-headers - -If you wish to check whether the message you are about to compose is -meant to be a news article or a mail message, you can check the values -of the @code{message-news-p} and @code{message-mail-p} functions. - -@findex message-mail-p -@findex message-news-p - -So here's a new example: - -@lisp -(setq gnus-posting-styles - '((".*" - (signature-file "~/.signature") - (name "User Name") - (x-face-file "~/.xface") - (x-url (getenv "WWW_HOME")) - (organization "People's Front Against MWM")) - ("^rec.humor" - (signature my-funny-signature-randomizer)) - ((equal (system-name) "gnarly") ;; @r{A form} - (signature my-quote-randomizer)) - (message-news-p ;; @r{A function symbol} - (signature my-news-signature)) - (window-system ;; @r{A value symbol} - ("X-Window-System" (format "%s" window-system))) - ;; @r{If I'm replying to Larsi, set the Organization header.} - ((header "from" "larsi.*org") - (Organization "Somewhere, Inc.")) - ((posting-from-work-p) ;; @r{A user defined function} - (signature-file "~/.work-signature") - (address "user@@bar.foo") - (body "You are fired.\n\nSincerely, your boss.") - (organization "Important Work, Inc")) - ("nnml:.*" - (From (with-current-buffer gnus-article-buffer - (message-fetch-field "to")))) - ("^nn.+:" - (signature-file "~/.mail-signature")))) -@end lisp - -The @samp{nnml:.*} rule means that you use the @code{To} address as the -@code{From} address in all your outgoing replies, which might be handy -if you fill many roles. -You may also use @code{message-alternative-emails} instead. -@xref{Message Headers, ,Message Headers, message, Message Manual}. - -@node Drafts -@section Drafts -@cindex drafts - -If you are writing a message (mail or news) and suddenly remember that -you have a steak in the oven (or some pesto in the food processor, you -craaazy vegetarians), you'll probably wish there was a method to save -the message you are writing so that you can continue editing it some -other day, and send it when you feel its finished. - -Well, don't worry about it. Whenever you start composing a message of -some sort using the Gnus mail and post commands, the buffer you get will -automatically associate to an article in a special @dfn{draft} group. -If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the -article will be saved there. (Auto-save files also go to the draft -group.) - -@cindex nndraft -@vindex nndraft-directory -The draft group is a special group (which is implemented as an -@code{nndraft} group, if you absolutely have to know) called -@samp{nndraft:drafts}. The variable @code{nndraft-directory} says where -@code{nndraft} is to store its files. What makes this group special is -that you can't tick any articles in it or mark any articles as -read---all articles in the group are permanently unread. - -If the group doesn't exist, it will be created and you'll be subscribed -to it. The only way to make it disappear from the Group buffer is to -unsubscribe it. The special properties of the draft group comes from -a group property (@pxref{Group Parameters}), and if lost the group -behaves like any other group. This means the commands below will not -be available. To restore the special properties of the group, the -simplest way is to kill the group, using @kbd{C-k}, and restart -Gnus. The group is automatically created again with the -correct parameters. The content of the group is not lost. - -@c @findex gnus-dissociate-buffer-from-draft -@c @kindex C-c M-d (Mail) -@c @kindex C-c M-d (Post) -@c @findex gnus-associate-buffer-with-draft -@c @kindex C-c C-d (Mail) -@c @kindex C-c C-d (Post) -@c If you're writing some super-secret message that you later want to -@c encode with PGP before sending, you may wish to turn the auto-saving -@c (and association with the draft group) off. You never know who might be -@c interested in reading all your extremely valuable and terribly horrible -@c and interesting secrets. The @kbd{C-c M-d} -@c (@code{gnus-dissociate-buffer-from-draft}) command does that for you. -@c If you change your mind and want to turn the auto-saving back on again, -@c @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that. -@c -@c @vindex gnus-use-draft -@c To leave association with the draft group off by default, set -@c @code{gnus-use-draft} to @code{nil}. It is @code{t} by default. - -@findex gnus-draft-edit-message -@kindex D e (Draft) -When you want to continue editing the article, you simply enter the -draft group and push @kbd{D e} (@code{gnus-draft-edit-message}) to do -that. You will be placed in a buffer where you left off. - -Rejected articles will also be put in this draft group (@pxref{Rejected -Articles}). - -@findex gnus-draft-send-all-messages -@kindex D s (Draft) -@findex gnus-draft-send-message -@kindex D S (Draft) -If you have lots of rejected messages you want to post (or mail) without -doing further editing, you can use the @kbd{D s} command -(@code{gnus-draft-send-message}). This command understands the -process/prefix convention (@pxref{Process/Prefix}). The @kbd{D S} -command (@code{gnus-draft-send-all-messages}) will ship off all messages -in the buffer. - -@findex gnus-draft-toggle-sending -@kindex D t (Draft) -If you have some messages that you wish not to send, you can use the -@kbd{D t} (@code{gnus-draft-toggle-sending}) command to mark the message -as unsendable. This is a toggling command. - -Finally, if you want to delete a draft, use the normal @kbd{B DEL} -command (@pxref{Mail Group Commands}). - - -@node Rejected Articles -@section Rejected Articles -@cindex rejected articles - -Sometimes a news server will reject an article. Perhaps the server -doesn't like your face. Perhaps it just feels miserable. Perhaps -@emph{there be demons}. Perhaps you have included too much cited text. -Perhaps the disk is full. Perhaps the server is down. - -These situations are, of course, totally beyond the control of Gnus. -(Gnus, of course, loves the way you look, always feels great, has angels -fluttering around inside of it, doesn't care about how much cited text -you include, never runs full and never goes down.) So Gnus saves these -articles until some later time when the server feels better. - -The rejected articles will automatically be put in a special draft group -(@pxref{Drafts}). When the server comes back up again, you'd then -typically enter that group and send all the articles off. - -@node Signing and encrypting -@section Signing and encrypting -@cindex using gpg -@cindex using s/mime -@cindex using smime - -Gnus can digitally sign and encrypt your messages, using vanilla -@acronym{PGP} format or @acronym{PGP/MIME} or @acronym{S/MIME}. For -decoding such messages, see the @code{mm-verify-option} and -@code{mm-decrypt-option} options (@pxref{Security}). - -@vindex gnus-message-replysign -@vindex gnus-message-replyencrypt -@vindex gnus-message-replysignencrypted -Often, you would like to sign replies to people who send you signed -messages. Even more often, you might want to encrypt messages which -are in reply to encrypted messages. Gnus offers -@code{gnus-message-replysign} to enable the former, and -@code{gnus-message-replyencrypt} for the latter. In addition, setting -@code{gnus-message-replysignencrypted} (on by default) will sign -automatically encrypted messages. - -Instructing @acronym{MML} to perform security operations on a -@acronym{MIME} part is done using the @kbd{C-c C-m s} key map for -signing and the @kbd{C-c C-m c} key map for encryption, as follows. - -@table @kbd - -@item C-c C-m s s -@kindex C-c C-m s s (Message) -@findex mml-secure-message-sign-smime - -Digitally sign current message using @acronym{S/MIME}. - -@item C-c C-m s o -@kindex C-c C-m s o (Message) -@findex mml-secure-message-sign-pgp - -Digitally sign current message using @acronym{PGP}. - -@item C-c C-m s p -@kindex C-c C-m s p (Message) -@findex mml-secure-message-sign-pgp - -Digitally sign current message using @acronym{PGP/MIME}. - -@item C-c C-m c s -@kindex C-c C-m c s (Message) -@findex mml-secure-message-encrypt-smime - -Digitally encrypt current message using @acronym{S/MIME}. - -@item C-c C-m c o -@kindex C-c C-m c o (Message) -@findex mml-secure-message-encrypt-pgp - -Digitally encrypt current message using @acronym{PGP}. - -@item C-c C-m c p -@kindex C-c C-m c p (Message) -@findex mml-secure-message-encrypt-pgpmime - -Digitally encrypt current message using @acronym{PGP/MIME}. - -@item C-c C-m C-n -@kindex C-c C-m C-n (Message) -@findex mml-unsecure-message -Remove security related @acronym{MML} tags from message. - -@end table - -@xref{Security, ,Security, message, Message Manual}, for more information. - -@node Select Methods -@chapter Select Methods -@cindex foreign groups -@cindex select methods - -A @dfn{foreign group} is a group not read by the usual (or -default) means. It could be, for instance, a group from a different -@acronym{NNTP} server, it could be a virtual group, or it could be your own -personal mail group. - -A foreign group (or any group, really) is specified by a @dfn{name} and -a @dfn{select method}. To take the latter first, a select method is a -list where the first element says what back end to use (e.g. @code{nntp}, -@code{nnspool}, @code{nnml}) and the second element is the @dfn{server -name}. There may be additional elements in the select method, where the -value may have special meaning for the back end in question. - -One could say that a select method defines a @dfn{virtual server}---so -we do just that (@pxref{Server Buffer}). - -The @dfn{name} of the group is the name the back end will recognize the -group as. - -For instance, the group @samp{soc.motss} on the @acronym{NNTP} server -@samp{some.where.edu} will have the name @samp{soc.motss} and select -method @code{(nntp "some.where.edu")}. Gnus will call this group -@samp{nntp+some.where.edu:soc.motss}, even though the @code{nntp} -back end just knows this group as @samp{soc.motss}. - -The different methods all have their peculiarities, of course. - -@menu -* Server Buffer:: Making and editing virtual servers. -* Getting News:: Reading USENET news with Gnus. -* Using IMAP:: Reading mail from @acronym{IMAP}. -* Getting Mail:: Reading your personal mail with Gnus. -* Browsing the Web:: Getting messages from a plethora of Web sources. -* Other Sources:: Reading directories, files. -* Combined Groups:: Combining groups into one group. -* Email Based Diary:: Using mails to manage diary events in Gnus. -* Gnus Unplugged:: Reading news and mail offline. -@end menu - - -@node Server Buffer -@section Server Buffer - -Traditionally, a @dfn{server} is a machine or a piece of software that -one connects to, and then requests information from. Gnus does not -connect directly to any real servers, but does all transactions through -one back end or other. But that's just putting one layer more between -the actual media and Gnus, so we might just as well say that each -back end represents a virtual server. - -For instance, the @code{nntp} back end may be used to connect to several -different actual @acronym{NNTP} servers, or, perhaps, to many different ports -on the same actual @acronym{NNTP} server. You tell Gnus which back end to -use, and what parameters to set by specifying a @dfn{select method}. - -These select method specifications can sometimes become quite -complicated---say, for instance, that you want to read from the -@acronym{NNTP} server @samp{news.funet.fi} on port number 13, which -hangs if queried for @acronym{NOV} headers and has a buggy select. Ahem. -Anyway, if you had to specify that for each group that used this -server, that would be too much work, so Gnus offers a way of naming -select methods, which is what you do in the server buffer. - -To enter the server buffer, use the @kbd{^} -(@code{gnus-group-enter-server-mode}) command in the group buffer. - -@menu -* Server Buffer Format:: You can customize the look of this buffer. -* Server Commands:: Commands to manipulate servers. -* Example Methods:: Examples server specifications. -* Creating a Virtual Server:: An example session. -* Server Variables:: Which variables to set. -* Servers and Methods:: You can use server names as select methods. -* Unavailable Servers:: Some servers you try to contact may be down. -@end menu - -@vindex gnus-server-mode-hook -@code{gnus-server-mode-hook} is run when creating the server buffer. - - -@node Server Buffer Format -@subsection Server Buffer Format -@cindex server buffer format - -@vindex gnus-server-line-format -You can change the look of the server buffer lines by changing the -@code{gnus-server-line-format} variable. This is a @code{format}-like -variable, with some simple extensions: - -@table @samp - -@item h -How the news is fetched---the back end name. - -@item n -The name of this server. - -@item w -Where the news is to be fetched from---the address. - -@item s -The opened/closed/denied status of the server. - -@item a -Whether this server is agentized. -@end table - -@vindex gnus-server-mode-line-format -The mode line can also be customized by using the -@code{gnus-server-mode-line-format} variable (@pxref{Mode Line -Formatting}). The following specs are understood: - -@table @samp -@item S -Server name. - -@item M -Server method. -@end table - -Also @pxref{Formatting Variables}. - - -@node Server Commands -@subsection Server Commands -@cindex server commands - -@table @kbd - -@item v -@kindex v (Server) -@cindex keys, reserved for users (Server) -The key @kbd{v} is reserved for users. You can bind it to some -command or better use it as a prefix key. - -@item a -@kindex a (Server) -@findex gnus-server-add-server -Add a new server (@code{gnus-server-add-server}). - -@item e -@kindex e (Server) -@findex gnus-server-edit-server -Edit a server (@code{gnus-server-edit-server}). - -@item S -@kindex S (Server) -@findex gnus-server-show-server -Show the definition of a server (@code{gnus-server-show-server}). - -@item SPACE -@kindex SPACE (Server) -@findex gnus-server-read-server -Browse the current server (@code{gnus-server-read-server}). - -@item q -@kindex q (Server) -@findex gnus-server-exit -Return to the group buffer (@code{gnus-server-exit}). - -@item k -@kindex k (Server) -@findex gnus-server-kill-server -Kill the current server (@code{gnus-server-kill-server}). - -@item y -@kindex y (Server) -@findex gnus-server-yank-server -Yank the previously killed server (@code{gnus-server-yank-server}). - -@item c -@kindex c (Server) -@findex gnus-server-copy-server -Copy the current server (@code{gnus-server-copy-server}). - -@item l -@kindex l (Server) -@findex gnus-server-list-servers -List all servers (@code{gnus-server-list-servers}). - -@item s -@kindex s (Server) -@findex gnus-server-scan-server -Request that the server scan its sources for new articles -(@code{gnus-server-scan-server}). This is mainly sensible with mail -servers. - -@item g -@kindex g (Server) -@findex gnus-server-regenerate-server -Request that the server regenerate all its data structures -(@code{gnus-server-regenerate-server}). This can be useful if you have -a mail back end that has gotten out of sync. - -@item z -@kindex z (Server) -@findex gnus-server-compact-server - -Compact all groups in the server under point -(@code{gnus-server-compact-server}). Currently implemented only in -nnml (@pxref{Mail Spool}). This removes gaps between article numbers, -hence getting a correct total article count. - -@end table - -Some more commands for closing, disabling, and re-opening servers are -listed in @ref{Unavailable Servers}. - - -@node Example Methods -@subsection Example Methods - -Most select methods are pretty simple and self-explanatory: - -@lisp -(nntp "news.funet.fi") -@end lisp - -Reading directly from the spool is even simpler: - -@lisp -(nnspool "") -@end lisp - -As you can see, the first element in a select method is the name of the -back end, and the second is the @dfn{address}, or @dfn{name}, if you -will. - -After these two elements, there may be an arbitrary number of -@code{(@var{variable} @var{form})} pairs. - -To go back to the first example---imagine that you want to read from -port 15 on that machine. This is what the select method should -look like then: - -@lisp -(nntp "news.funet.fi" (nntp-port-number 15)) -@end lisp - -You should read the documentation to each back end to find out what -variables are relevant, but here's an @code{nnmh} example: - -@code{nnmh} is a mail back end that reads a spool-like structure. Say -you have two structures that you wish to access: One is your private -mail spool, and the other is a public one. Here's the possible spec for -your private mail: - -@lisp -(nnmh "private" (nnmh-directory "~/private/mail/")) -@end lisp - -(This server is then called @samp{private}, but you may have guessed -that.) - -Here's the method for a public spool: - -@lisp -(nnmh "public" - (nnmh-directory "/usr/information/spool/") - (nnmh-get-new-mail nil)) -@end lisp - -@cindex proxy -@cindex firewall - -If you are behind a firewall and only have access to the @acronym{NNTP} -server from the firewall machine, you can instruct Gnus to @code{rlogin} -on the firewall machine and connect with -@uref{http://netcat.sourceforge.net/, netcat} from there to the -@acronym{NNTP} server. -Doing this can be rather fiddly, but your virtual server definition -should probably look something like this: - -@lisp -(nntp "firewall" - (nntp-open-connection-function nntp-open-via-rlogin-and-netcat) - (nntp-via-address "the.firewall.machine") - (nntp-address "the.real.nntp.host")) -@end lisp - -If you want to use the wonderful @code{ssh} program to provide a -compressed connection over the modem line, you could add the following -configuration to the example above: - -@lisp - (nntp-via-rlogin-command "ssh") -@end lisp - -See also @code{nntp-via-rlogin-command-switches}. Here's an example for -an indirect connection: - -@lisp -(setq gnus-select-method - '(nntp "indirect" - (nntp-address "news.server.example") - (nntp-via-user-name "intermediate_user_name") - (nntp-via-address "intermediate.host.example") - (nntp-via-rlogin-command "ssh") - (nntp-via-rlogin-command-switches ("-C")) - (nntp-open-connection-function nntp-open-via-rlogin-and-netcat))) -@end lisp - -This means that you have to have set up @code{ssh-agent} correctly to -provide automatic authorization, of course. - -If you're behind a firewall, but have direct access to the outside world -through a wrapper command like "runsocks", you could open a socksified -netcat connection to the news server as follows: - -@lisp -(nntp "outside" - (nntp-pre-command "runsocks") - (nntp-open-connection-function nntp-open-netcat-stream) - (nntp-address "the.news.server")) -@end lisp - - -@node Creating a Virtual Server -@subsection Creating a Virtual Server - -If you're saving lots of articles in the cache by using persistent -articles, you may want to create a virtual server to read the cache. - -First you need to add a new server. The @kbd{a} command does that. It -would probably be best to use @code{nnml} to read the cache. You -could also use @code{nnspool} or @code{nnmh}, though. - -Type @kbd{a nnml RET cache RET}. - -You should now have a brand new @code{nnml} virtual server called -@samp{cache}. You now need to edit it to have the right definitions. -Type @kbd{e} to edit the server. You'll be entered into a buffer that -will contain the following: - -@lisp -(nnml "cache") -@end lisp - -Change that to: - -@lisp -(nnml "cache" - (nnml-directory "~/News/cache/") - (nnml-active-file "~/News/cache/active")) -@end lisp - -Type @kbd{C-c C-c} to return to the server buffer. If you now press -@kbd{RET} over this virtual server, you should be entered into a browse -buffer, and you should be able to enter any of the groups displayed. - - -@node Server Variables -@subsection Server Variables -@cindex server variables -@cindex server parameters - -One sticky point when defining variables (both on back ends and in Emacs -in general) is that some variables are typically initialized from other -variables when the definition of the variables is being loaded. If you -change the ``base'' variable after the variables have been loaded, you -won't change the ``derived'' variables. - -This typically affects directory and file variables. For instance, -@code{nnml-directory} is @file{~/Mail/} by default, and all @code{nnml} -directory variables are initialized from that variable, so -@code{nnml-active-file} will be @file{~/Mail/active}. If you define a -new virtual @code{nnml} server, it will @emph{not} suffice to set just -@code{nnml-directory}---you have to explicitly set all the file -variables to be what you want them to be. For a complete list of -variables for each back end, see each back end's section later in this -manual, but here's an example @code{nnml} definition: - -@lisp -(nnml "public" - (nnml-directory "~/my-mail/") - (nnml-active-file "~/my-mail/active") - (nnml-newsgroups-file "~/my-mail/newsgroups")) -@end lisp - -Server variables are often called @dfn{server parameters}. - -@node Servers and Methods -@subsection Servers and Methods - -Wherever you would normally use a select method -(e.g. @code{gnus-secondary-select-method}, in the group select method, -when browsing a foreign server) you can use a virtual server name -instead. This could potentially save lots of typing. And it's nice all -over. - - -@node Unavailable Servers -@subsection Unavailable Servers - -If a server seems to be unreachable, Gnus will mark that server as -@code{denied}. That means that any subsequent attempt to make contact -with that server will just be ignored. ``It can't be opened,'' Gnus -will tell you, without making the least effort to see whether that is -actually the case or not. - -That might seem quite naughty, but it does make sense most of the time. -Let's say you have 10 groups subscribed to on server -@samp{nephelococcygia.com}. This server is located somewhere quite far -away from you and the machine is quite slow, so it takes 1 minute just -to find out that it refuses connection to you today. If Gnus were to -attempt to do that 10 times, you'd be quite annoyed, so Gnus won't -attempt to do that. Once it has gotten a single ``connection refused'', -it will regard that server as ``down''. - -So, what happens if the machine was only feeling unwell temporarily? -How do you test to see whether the machine has come up again? - -You jump to the server buffer (@pxref{Server Buffer}) and poke it -with the following commands: - -@table @kbd - -@item O -@kindex O (Server) -@findex gnus-server-open-server -Try to establish connection to the server on the current line -(@code{gnus-server-open-server}). - -@item C -@kindex C (Server) -@findex gnus-server-close-server -Close the connection (if any) to the server -(@code{gnus-server-close-server}). - -@item D -@kindex D (Server) -@findex gnus-server-deny-server -Mark the current server as unreachable -(@code{gnus-server-deny-server}). - -@item M-o -@kindex M-o (Server) -@findex gnus-server-open-all-servers -Open the connections to all servers in the buffer -(@code{gnus-server-open-all-servers}). - -@item M-c -@kindex M-c (Server) -@findex gnus-server-close-all-servers -Close the connections to all servers in the buffer -(@code{gnus-server-close-all-servers}). - -@item R -@kindex R (Server) -@findex gnus-server-remove-denials -Remove all marks to whether Gnus was denied connection from any servers -(@code{gnus-server-remove-denials}). - -@item c -@kindex c (Server) -@findex gnus-server-copy-server -Copy a server and give it a new name -(@code{gnus-server-copy-server}). This can be useful if you have a -complex method definition, and want to use the same definition towards -a different (physical) server. - -@item L -@kindex L (Server) -@findex gnus-server-offline-server -Set server status to offline (@code{gnus-server-offline-server}). - -@end table - - -@node Getting News -@section Getting News -@cindex reading news -@cindex news back ends - -A newsreader is normally used for reading news. Gnus currently provides -only two methods of getting news---it can read from an @acronym{NNTP} server, -or it can read from a local spool. - -@menu -* NNTP:: Reading news from an @acronym{NNTP} server. -* News Spool:: Reading news from the local spool. -@end menu - - -@node NNTP -@subsection NNTP -@cindex nntp - -Subscribing to a foreign group from an @acronym{NNTP} server is rather easy. -You just specify @code{nntp} as method and the address of the @acronym{NNTP} -server as the, uhm, address. - -If the @acronym{NNTP} server is located at a non-standard port, setting the -third element of the select method to this port number should allow you -to connect to the right port. You'll have to edit the group info for -that (@pxref{Foreign Groups}). - -The name of the foreign group can be the same as a native group. In -fact, you can subscribe to the same group from as many different servers -you feel like. There will be no name collisions. - -The following variables can be used to create a virtual @code{nntp} -server: - -@table @code - -@item nntp-server-opened-hook -@vindex nntp-server-opened-hook -@cindex @sc{mode reader} -@cindex authinfo -@cindex authentication -@cindex nntp authentication -@findex nntp-send-authinfo -@findex nntp-send-mode-reader -is run after a connection has been made. It can be used to send -commands to the @acronym{NNTP} server after it has been contacted. By -default it sends the command @code{MODE READER} to the server with the -@code{nntp-send-mode-reader} function. This function should always be -present in this hook. - -@item nntp-authinfo-function -@vindex nntp-authinfo-function -@findex nntp-send-authinfo -@vindex nntp-authinfo-file -This function will be used to send @samp{AUTHINFO} to the @acronym{NNTP} -server. The default function is @code{nntp-send-authinfo}, which looks -through your @file{~/.authinfo} (or whatever you've set the -@code{nntp-authinfo-file} variable to) for applicable entries. If none -are found, it will prompt you for a login name and a password. The -format of the @file{~/.authinfo} file is (almost) the same as the -@code{ftp} @file{~/.netrc} file, which is defined in the @code{ftp} -manual page, but here are the salient facts: - -@enumerate -@item -The file contains one or more line, each of which define one server. - -@item -Each line may contain an arbitrary number of token/value pairs. - -The valid tokens include @samp{machine}, @samp{login}, @samp{password}, -@samp{default}. In addition Gnus introduces two new tokens, not present -in the original @file{.netrc}/@code{ftp} syntax, namely @samp{port} and -@samp{force}. (This is the only way the @file{.authinfo} file format -deviates from the @file{.netrc} file format.) @samp{port} is used to -indicate what port on the server the credentials apply to and -@samp{force} is explained below. - -@end enumerate - -Here's an example file: - -@example -machine news.uio.no login larsi password geheimnis -machine nntp.ifi.uio.no login larsi force yes -@end example - -The token/value pairs may appear in any order; @samp{machine} doesn't -have to be first, for instance. - -In this example, both login name and password have been supplied for the -former server, while the latter has only the login name listed, and the -user will be prompted for the password. The latter also has the -@samp{force} tag, which means that the authinfo will be sent to the -@var{nntp} server upon connection; the default (i.e., when there is not -@samp{force} tag) is to not send authinfo to the @var{nntp} server -until the @var{nntp} server asks for it. - -You can also add @samp{default} lines that will apply to all servers -that don't have matching @samp{machine} lines. - -@example -default force yes -@end example - -This will force sending @samp{AUTHINFO} commands to all servers not -previously mentioned. - -Remember to not leave the @file{~/.authinfo} file world-readable. - -@item nntp-server-action-alist -@vindex nntp-server-action-alist -This is a list of regexps to match on server types and actions to be -taken when matches are made. For instance, if you want Gnus to beep -every time you connect to innd, you could say something like: - -@lisp -(setq nntp-server-action-alist - '(("innd" (ding)))) -@end lisp - -You probably don't want to do that, though. - -The default value is - -@lisp -'(("nntpd 1\\.5\\.11t" - (remove-hook 'nntp-server-opened-hook - 'nntp-send-mode-reader))) -@end lisp - -This ensures that Gnus doesn't send the @code{MODE READER} command to -nntpd 1.5.11t, since that command chokes that server, I've been told. - -@item nntp-maximum-request -@vindex nntp-maximum-request -If the @acronym{NNTP} server doesn't support @acronym{NOV} headers, this back end -will collect headers by sending a series of @code{head} commands. To -speed things up, the back end sends lots of these commands without -waiting for reply, and then reads all the replies. This is controlled -by the @code{nntp-maximum-request} variable, and is 400 by default. If -your network is buggy, you should set this to 1. - -@item nntp-connection-timeout -@vindex nntp-connection-timeout -If you have lots of foreign @code{nntp} groups that you connect to -regularly, you're sure to have problems with @acronym{NNTP} servers not -responding properly, or being too loaded to reply within reasonable -time. This is can lead to awkward problems, which can be helped -somewhat by setting @code{nntp-connection-timeout}. This is an integer -that says how many seconds the @code{nntp} back end should wait for a -connection before giving up. If it is @code{nil}, which is the default, -no timeouts are done. - -@item nntp-nov-is-evil -@vindex nntp-nov-is-evil -If the @acronym{NNTP} server does not support @acronym{NOV}, you could set this -variable to @code{t}, but @code{nntp} usually checks automatically whether @acronym{NOV} -can be used. - -@item nntp-xover-commands -@vindex nntp-xover-commands -@cindex @acronym{NOV} -@cindex XOVER -List of strings used as commands to fetch @acronym{NOV} lines from a -server. The default value of this variable is @code{("XOVER" -"XOVERVIEW")}. - -@item nntp-nov-gap -@vindex nntp-nov-gap -@code{nntp} normally sends just one big request for @acronym{NOV} lines to -the server. The server responds with one huge list of lines. However, -if you have read articles 2-5000 in the group, and only want to read -article 1 and 5001, that means that @code{nntp} will fetch 4999 @acronym{NOV} -lines that you will not need. This variable says how -big a gap between two consecutive articles is allowed to be before the -@code{XOVER} request is split into several request. Note that if your -network is fast, setting this variable to a really small number means -that fetching will probably be slower. If this variable is @code{nil}, -@code{nntp} will never split requests. The default is 5. - -@item nntp-xref-number-is-evil -@vindex nntp-xref-number-is-evil -When Gnus refers to an article having the @code{Message-ID} that a user -specifies or having the @code{Message-ID} of the parent article of the -current one (@pxref{Finding the Parent}), Gnus sends a @code{HEAD} -command to the @acronym{NNTP} server to know where it is, and the server -returns the data containing the pairs of a group and an article number -in the @code{Xref} header. Gnus normally uses the article number to -refer to the article if the data shows that that article is in the -current group, while it uses the @code{Message-ID} otherwise. However, -some news servers, e.g., ones running Diablo, run multiple engines -having the same articles but article numbers are not kept synchronized -between them. In that case, the article number that appears in the -@code{Xref} header varies by which engine is chosen, so you cannot refer -to the parent article that is in the current group, for instance. If -you connect to such a server, set this variable to a non-@code{nil} -value, and Gnus never uses article numbers. For example: - -@lisp -(setq gnus-select-method - '(nntp "newszilla" - (nntp-address "newszilla.example.com") - (nntp-xref-number-is-evil t) - @dots{})) -@end lisp - -The default value of this server variable is @code{nil}. - -@item nntp-prepare-server-hook -@vindex nntp-prepare-server-hook -A hook run before attempting to connect to an @acronym{NNTP} server. - -@item nntp-record-commands -@vindex nntp-record-commands -If non-@code{nil}, @code{nntp} will log all commands it sends to the -@acronym{NNTP} server (along with a timestamp) in the @samp{*nntp-log*} -buffer. This is useful if you are debugging a Gnus/@acronym{NNTP} connection -that doesn't seem to work. - -@item nntp-open-connection-function -@vindex nntp-open-connection-function -It is possible to customize how the connection to the nntp server will -be opened. If you specify an @code{nntp-open-connection-function} -parameter, Gnus will use that function to establish the connection. -Seven pre-made functions are supplied. These functions can be grouped -in two categories: direct connection functions (four pre-made), and -indirect ones (three pre-made). - -@item nntp-never-echoes-commands -@vindex nntp-never-echoes-commands -Non-@code{nil} means the nntp server never echoes commands. It is -reported that some nntps server doesn't echo commands. So, you may want -to set this to non-@code{nil} in the method for such a server setting -@code{nntp-open-connection-function} to @code{nntp-open-ssl-stream} for -example. The default value is @code{nil}. Note that the -@code{nntp-open-connection-functions-never-echo-commands} variable -overrides the @code{nil} value of this variable. - -@item nntp-open-connection-functions-never-echo-commands -@vindex nntp-open-connection-functions-never-echo-commands -List of functions that never echo commands. Add or set a function which -you set to @code{nntp-open-connection-function} to this list if it does -not echo commands. Note that a non-@code{nil} value of the -@code{nntp-never-echoes-commands} variable overrides this variable. The -default value is @code{(nntp-open-network-stream)}. - -@item nntp-prepare-post-hook -@vindex nntp-prepare-post-hook -A hook run just before posting an article. If there is no -@code{Message-ID} header in the article and the news server provides the -recommended ID, it will be added to the article before running this -hook. It is useful to make @code{Cancel-Lock} headers even if you -inhibit Gnus to add a @code{Message-ID} header, you could say: - -@lisp -(add-hook 'nntp-prepare-post-hook 'canlock-insert-header) -@end lisp - -Note that not all servers support the recommended ID. This works for -INN versions 2.3.0 and later, for instance. - -@item nntp-server-list-active-group -If @code{nil}, then always use @samp{GROUP} instead of @samp{LIST -ACTIVE}. This is usually slower, but on misconfigured servers that -don't update their active files often, this can help. - - -@end table - -@menu -* Direct Functions:: Connecting directly to the server. -* Indirect Functions:: Connecting indirectly to the server. -* Common Variables:: Understood by several connection functions. -* NNTP marks:: Storing marks for @acronym{NNTP} servers. -@end menu - - -@node Direct Functions -@subsubsection Direct Functions -@cindex direct connection functions - -These functions are called direct because they open a direct connection -between your machine and the @acronym{NNTP} server. The behavior of these -functions is also affected by commonly understood variables -(@pxref{Common Variables}). - -@table @code -@findex nntp-open-network-stream -@item nntp-open-network-stream -This is the default, and simply connects to some port or other on the -remote system. If both Emacs and the server supports it, the -connection will be upgraded to an encrypted @acronym{STARTTLS} -connection automatically. - -@item network-only -The same as the above, but don't do automatic @acronym{STARTTLS} upgrades. - -@findex nntp-open-tls-stream -@item nntp-open-tls-stream -Opens a connection to a server over a @dfn{secure} channel. To use -this you must have @uref{http://www.gnu.org/software/gnutls/, GnuTLS} -installed. You then define a server as follows: - -@lisp -;; @r{"nntps" is port 563 and is predefined in our @file{/etc/services}} -;; @r{however, @samp{gnutls-cli -p} doesn't like named ports.} -;; -(nntp "snews.bar.com" - (nntp-open-connection-function nntp-open-tls-stream) - (nntp-port-number 563) - (nntp-address "snews.bar.com")) -@end lisp - -@findex nntp-open-ssl-stream -@item nntp-open-ssl-stream -Opens a connection to a server over a @dfn{secure} channel. To use -this you must have @uref{http://www.openssl.org, OpenSSL} or -@uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL, SSLeay} installed. You -then define a server as follows: - -@lisp -;; @r{"snews" is port 563 and is predefined in our @file{/etc/services}} -;; @r{however, @samp{openssl s_client -port} doesn't like named ports.} -;; -(nntp "snews.bar.com" - (nntp-open-connection-function nntp-open-ssl-stream) - (nntp-port-number 563) - (nntp-address "snews.bar.com")) -@end lisp - -@findex nntp-open-netcat-stream -@item nntp-open-netcat-stream -Opens a connection to an @acronym{NNTP} server using the @code{netcat} -program. You might wonder why this function exists, since we have -the default @code{nntp-open-network-stream} which would do the job. (One -of) the reason(s) is that if you are behind a firewall but have direct -connections to the outside world thanks to a command wrapper like -@code{runsocks}, you can use it like this: - -@lisp -(nntp "socksified" - (nntp-pre-command "runsocks") - (nntp-open-connection-function nntp-open-netcat-stream) - (nntp-address "the.news.server")) -@end lisp - -With the default method, you would need to wrap your whole Emacs -session, which is not a good idea. - -@findex nntp-open-telnet-stream -@item nntp-open-telnet-stream -Like @code{nntp-open-netcat-stream}, but uses @code{telnet} rather than -@code{netcat}. @code{telnet} is a bit less robust because of things -like line-end-conversion, but sometimes netcat is simply -not available. The previous example would turn into: - -@lisp -(nntp "socksified" - (nntp-pre-command "runsocks") - (nntp-open-connection-function nntp-open-telnet-stream) - (nntp-address "the.news.server") - (nntp-end-of-line "\n")) -@end lisp -@end table - - -@node Indirect Functions -@subsubsection Indirect Functions -@cindex indirect connection functions - -These functions are called indirect because they connect to an -intermediate host before actually connecting to the @acronym{NNTP} server. -All of these functions and related variables are also said to belong to -the ``via'' family of connection: they're all prefixed with ``via'' to make -things cleaner. The behavior of these functions is also affected by -commonly understood variables (@pxref{Common Variables}). - -@table @code -@item nntp-open-via-rlogin-and-netcat -@findex nntp-open-via-rlogin-and-netcat -Does an @samp{rlogin} on a remote system, and then uses @code{netcat} to connect -to the real @acronym{NNTP} server from there. This is useful for instance if -you need to connect to a firewall machine first. - -@code{nntp-open-via-rlogin-and-netcat}-specific variables: - -@table @code -@item nntp-via-rlogin-command -@vindex nntp-via-rlogin-command -Command used to log in on the intermediate host. The default is -@samp{rsh}, but @samp{ssh} is a popular alternative. - -@item nntp-via-rlogin-command-switches -@vindex nntp-via-rlogin-command-switches -List of strings to be used as the switches to -@code{nntp-via-rlogin-command}. The default is @code{nil}. If you use -@samp{ssh} for @code{nntp-via-rlogin-command}, you may set this to -@samp{("-C")} in order to compress all data connections. -@end table - -@item nntp-open-via-rlogin-and-telnet -@findex nntp-open-via-rlogin-and-telnet -Does essentially the same, but uses @code{telnet} instead of @samp{netcat} -to connect to the real @acronym{NNTP} server from the intermediate host. -@code{telnet} is a bit less robust because of things like -line-end-conversion, but sometimes @code{netcat} is simply not available. - -@code{nntp-open-via-rlogin-and-telnet}-specific variables: - -@table @code -@item nntp-telnet-command -@vindex nntp-telnet-command -Command used to connect to the real @acronym{NNTP} server from the -intermediate host. The default is @samp{telnet}. - -@item nntp-telnet-switches -@vindex nntp-telnet-switches -List of strings to be used as the switches to the -@code{nntp-telnet-command} command. The default is @code{("-8")}. - -@item nntp-via-rlogin-command -@vindex nntp-via-rlogin-command -Command used to log in on the intermediate host. The default is -@samp{rsh}, but @samp{ssh} is a popular alternative. - -@item nntp-via-rlogin-command-switches -@vindex nntp-via-rlogin-command-switches -List of strings to be used as the switches to -@code{nntp-via-rlogin-command}. If you use @samp{ssh}, you may need to set -this to @samp{("-t" "-e" "none")} or @samp{("-C" "-t" "-e" "none")} if -the telnet command requires a pseudo-tty allocation on an intermediate -host. The default is @code{nil}. -@end table - -Note that you may want to change the value for @code{nntp-end-of-line} -to @samp{\n} (@pxref{Common Variables}). - -@item nntp-open-via-telnet-and-telnet -@findex nntp-open-via-telnet-and-telnet -Does essentially the same, but uses @samp{telnet} instead of -@samp{rlogin} to connect to the intermediate host. - -@code{nntp-open-via-telnet-and-telnet}-specific variables: - -@table @code -@item nntp-via-telnet-command -@vindex nntp-via-telnet-command -Command used to @code{telnet} the intermediate host. The default is -@samp{telnet}. - -@item nntp-via-telnet-switches -@vindex nntp-via-telnet-switches -List of strings to be used as the switches to the -@code{nntp-via-telnet-command} command. The default is @samp{("-8")}. - -@item nntp-via-user-password -@vindex nntp-via-user-password -Password to use when logging in on the intermediate host. - -@item nntp-via-envuser -@vindex nntp-via-envuser -If non-@code{nil}, the intermediate @code{telnet} session (client and -server both) will support the @code{ENVIRON} option and not prompt for -login name. This works for Solaris @code{telnet}, for instance. - -@item nntp-via-shell-prompt -@vindex nntp-via-shell-prompt -Regexp matching the shell prompt on the intermediate host. The default -is @samp{bash\\|\$ *\r?$\\|> *\r?}. - -@end table - -Note that you may want to change the value for @code{nntp-end-of-line} -to @samp{\n} (@pxref{Common Variables}). -@end table - - -Here are some additional variables that are understood by all the above -functions: - -@table @code - -@item nntp-via-user-name -@vindex nntp-via-user-name -User name to use when connecting to the intermediate host. - -@item nntp-via-address -@vindex nntp-via-address -Address of the intermediate host to connect to. - -@end table - - -@node Common Variables -@subsubsection Common Variables - -The following variables affect the behavior of all, or several of the -pre-made connection functions. When not specified, all functions are -affected (the values of the following variables will be used as the -default if each virtual @code{nntp} server doesn't specify those server -variables individually). - -@table @code - -@item nntp-pre-command -@vindex nntp-pre-command -A command wrapper to use when connecting through a non native -connection function (all except @code{nntp-open-network-stream}, -@code{nntp-open-tls-stream}, and @code{nntp-open-ssl-stream}). This is -where you would put a @samp{SOCKS} wrapper for instance. - -@item nntp-address -@vindex nntp-address -The address of the @acronym{NNTP} server. - -@item nntp-port-number -@vindex nntp-port-number -Port number to connect to the @acronym{NNTP} server. The default is -@samp{nntp}. If you use @acronym{NNTP} over -@acronym{TLS}/@acronym{SSL}, you may want to use integer ports rather -than named ports (i.e, use @samp{563} instead of @samp{snews} or -@samp{nntps}), because external @acronym{TLS}/@acronym{SSL} tools may -not work with named ports. - -@item nntp-end-of-line -@vindex nntp-end-of-line -String to use as end-of-line marker when talking to the @acronym{NNTP} -server. This is @samp{\r\n} by default, but should be @samp{\n} when -using a non native telnet connection function. - -@item nntp-netcat-command -@vindex nntp-netcat-command -Command to use when connecting to the @acronym{NNTP} server through -@samp{netcat}. This is @emph{not} for an intermediate host. This is -just for the real @acronym{NNTP} server. The default is -@samp{nc}. - -@item nntp-netcat-switches -@vindex nntp-netcat-switches -A list of switches to pass to @code{nntp-netcat-command}. The default -is @samp{()}. - -@end table - -@node NNTP marks -@subsubsection NNTP marks -@cindex storing NNTP marks - -Gnus stores marks (@pxref{Marking Articles}) for @acronym{NNTP} -servers in marks files. A marks file records what marks you have set -in a group and each file is specific to the corresponding server. -Marks files are stored in @file{~/News/marks} -(@code{nntp-marks-directory}) under a classic hierarchy resembling -that of a news server, for example marks for the group -@samp{gmane.discuss} on the news.gmane.org server will be stored in -the file @file{~/News/marks/news.gmane.org/gmane/discuss/.marks}. - -Marks files are useful because you can copy the @file{~/News/marks} -directory (using rsync, scp or whatever) to another Gnus installation, -and it will realize what articles you have read and marked. The data -in @file{~/News/marks} has priority over the same data in -@file{~/.newsrc.eld}. - -Note that marks files are very much server-specific: Gnus remembers -the article numbers so if you don't use the same servers on both -installations things are most likely to break (most @acronym{NNTP} -servers do not use the same article numbers as any other server). -However, if you use servers A, B, C on one installation and servers A, -D, E on the other, you can sync the marks files for A and then you'll -get synchronization for that server between the two installations. - -Using @acronym{NNTP} marks can possibly incur a performance penalty so -if Gnus feels sluggish, try setting the @code{nntp-marks-is-evil} -variable to @code{t}. Marks will then be stored in @file{~/.newsrc.eld}. - -Related variables: - -@table @code - -@item nntp-marks-is-evil -@vindex nntp-marks-is-evil -If non-@code{nil}, this back end will ignore any marks files. The -default is @code{nil}. - -@item nntp-marks-directory -@vindex nntp-marks-directory -The directory where marks for nntp groups will be stored. - -@end table - - -@node News Spool -@subsection News Spool -@cindex nnspool -@cindex news spool - -Subscribing to a foreign group from the local spool is extremely easy, -and might be useful, for instance, to speed up reading groups that -contain very big articles---@samp{alt.binaries.pictures.furniture}, for -instance. - -Anyway, you just specify @code{nnspool} as the method and @code{""} (or -anything else) as the address. - -If you have access to a local spool, you should probably use that as the -native select method (@pxref{Finding the News}). It is normally faster -than using an @code{nntp} select method, but might not be. It depends. -You just have to try to find out what's best at your site. - -@table @code - -@item nnspool-inews-program -@vindex nnspool-inews-program -Program used to post an article. - -@item nnspool-inews-switches -@vindex nnspool-inews-switches -Parameters given to the inews program when posting an article. - -@item nnspool-spool-directory -@vindex nnspool-spool-directory -Where @code{nnspool} looks for the articles. This is normally -@file{/usr/spool/news/}. - -@item nnspool-nov-directory -@vindex nnspool-nov-directory -Where @code{nnspool} will look for @acronym{NOV} files. This is normally@* -@file{/usr/spool/news/over.view/}. - -@item nnspool-lib-dir -@vindex nnspool-lib-dir -Where the news lib dir is (@file{/usr/lib/news/} by default). - -@item nnspool-active-file -@vindex nnspool-active-file -The name of the active file. - -@item nnspool-newsgroups-file -@vindex nnspool-newsgroups-file -The name of the group descriptions file. - -@item nnspool-history-file -@vindex nnspool-history-file -The name of the news history file. - -@item nnspool-active-times-file -@vindex nnspool-active-times-file -The name of the active date file. - -@item nnspool-nov-is-evil -@vindex nnspool-nov-is-evil -If non-@code{nil}, @code{nnspool} won't try to use any @acronym{NOV} files -that it finds. - -@item nnspool-sift-nov-with-sed -@vindex nnspool-sift-nov-with-sed -@cindex sed -If non-@code{nil}, which is the default, use @code{sed} to get the -relevant portion from the overview file. If @code{nil}, -@code{nnspool} will load the entire file into a buffer and process it -there. - -@end table - - -@node Using IMAP -@section Using IMAP -@cindex imap - -The most popular mail backend is probably @code{nnimap}, which -provides access to @acronym{IMAP} servers. @acronym{IMAP} servers -store mail remotely, so the client doesn't store anything locally. -This means that it's a convenient choice when you're reading your mail -from different locations, or with different user agents. - -@menu -* Connecting to an IMAP Server:: Getting started with @acronym{IMAP}. -* Customizing the IMAP Connection:: Variables for @acronym{IMAP} connection. -* Client-Side IMAP Splitting:: Put mail in the correct mail box. -@end menu - - -@node Connecting to an IMAP Server -@subsection Connecting to an IMAP Server - -Connecting to an @acronym{IMAP} can be very easy. Type @kbd{B} in the -group buffer, or (if your primary interest is reading email), say -something like: - -@example -(setq gnus-select-method - '(nnimap "imap.gmail.com")) -@end example - -You'll be prompted for a user name and password. If you grow tired of -that, then add the following to your @file{~/.authinfo} file: - -@example -machine imap.gmail.com login password port imap -@end example - -That should basically be it for most users. - - -@node Customizing the IMAP Connection -@subsection Customizing the IMAP Connection - -Here's an example method that's more complex: - -@example -(nnimap "imap.gmail.com" - (nnimap-inbox "INBOX") - (nnimap-split-methods default) - (nnimap-expunge t) - (nnimap-stream ssl)) -@end example - -@table @code -@item nnimap-address -The address of the server, like @samp{imap.gmail.com}. - -@item nnimap-server-port -If the server uses a non-standard port, that can be specified here. A -typical port would be @code{"imap"} or @code{"imaps"}. - -@item nnimap-stream -How @code{nnimap} should connect to the server. Possible values are: - -@table @code -@item undecided -This is the default, and this first tries the @code{ssl} setting, and -then tries the @code{network} setting. - -@item ssl -This uses standard @acronym{TLS}/@acronym{SSL} connections. - -@item network -Non-encrypted and unsafe straight socket connection, but will upgrade -to encrypted @acronym{STARTTLS} if both Emacs and the server -supports it. - -@item starttls -Encrypted @acronym{STARTTLS} over the normal @acronym{IMAP} port. - -@item shell -If you need to tunnel via other systems to connect to the server, you -can use this option, and customize @code{nnimap-shell-program} to be -what you need. - -@end table - -@item nnimap-authenticator -Some @acronym{IMAP} servers allow anonymous logins. In that case, -this should be set to @code{anonymous}. - -@item nnimap-expunge -If non-@code{nil}, expunge articles after deleting them. This is always done -if the server supports UID EXPUNGE, but it's not done by default on -servers that doesn't support that command. - -@item nnimap-streaming -Virtually all @acronym{IMAP} server support fast streaming of data. -If you have problems connecting to the server, try setting this to -@code{nil}. - -@item nnimap-fetch-partial-articles -If non-@code{nil}, fetch partial articles from the server. If set to -a string, then it's interpreted as a regexp, and parts that have -matching types will be fetched. For instance, @samp{"text/"} will -fetch all textual parts, while leaving the rest on the server. - -@item nnimap-record-commands -If non-@code{nil}, record all @acronym{IMAP} commands in the -@samp{"*imap log*"} buffer. - -@end table - - -@node Client-Side IMAP Splitting -@subsection Client-Side IMAP Splitting - -Many people prefer to do the sorting/splitting of mail into their mail -boxes on the @acronym{IMAP} server. That way they don't have to -download the mail they're not all that interested in. - -If you do want to do client-side mail splitting, then the following -variables are relevant: - -@table @code -@item nnimap-inbox -This is the @acronym{IMAP} mail box that will be scanned for new mail. - -@item nnimap-split-methods -Uses the same syntax as @code{nnmail-split-methods} (@pxref{Splitting -Mail}), except the symbol @code{default}, which means that it should -use the value of the @code{nnmail-split-methods} variable. - -@item nnimap-split-fancy -Uses the same syntax as @code{nnmail-split-fancy}. - -@item nnimap-unsplittable-articles -List of flag symbols to ignore when doing splitting. That is, -articles that have these flags won't be considered when splitting. -The default is @samp{(%Deleted %Seen)}. - -@end table - -Here's a complete example @code{nnimap} backend with a client-side -``fancy'' splitting method: - -@example -(nnimap "imap.example.com" - (nnimap-inbox "INBOX") - (nnimap-split-methods - (| ("MailScanner-SpamCheck" "spam" "spam.detected") - (to "foo@@bar.com" "foo") - "undecided"))) -@end example - - -@node Getting Mail -@section Getting Mail -@cindex reading mail -@cindex mail - -Reading mail with a newsreader---isn't that just plain WeIrD? But of -course. - -@menu -* Mail in a Newsreader:: Important introductory notes. -* Getting Started Reading Mail:: A simple cookbook example. -* Splitting Mail:: How to create mail groups. -* Mail Sources:: How to tell Gnus where to get mail from. -* Mail Back End Variables:: Variables for customizing mail handling. -* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. -* Group Mail Splitting:: Use group customize to drive mail splitting. -* Incorporating Old Mail:: What about the old mail you have? -* Expiring Mail:: Getting rid of unwanted mail. -* Washing Mail:: Removing cruft from the mail you get. -* Duplicates:: Dealing with duplicated mail. -* Not Reading Mail:: Using mail back ends for reading other files. -* Choosing a Mail Back End:: Gnus can read a variety of mail formats. -@end menu - - -@node Mail in a Newsreader -@subsection Mail in a Newsreader - -If you are used to traditional mail readers, but have decided to switch -to reading mail with Gnus, you may find yourself experiencing something -of a culture shock. - -Gnus does not behave like traditional mail readers. If you want to make -it behave that way, you can, but it's an uphill battle. - -Gnus, by default, handles all its groups using the same approach. This -approach is very newsreaderly---you enter a group, see the new/unread -messages, and when you read the messages, they get marked as read, and -you don't see them any more. (Unless you explicitly ask for them.) - -In particular, you do not do anything explicitly to delete messages. - -Does this mean that all the messages that have been marked as read are -deleted? How awful! - -But, no, it means that old messages are @dfn{expired} according to some -scheme or other. For news messages, the expire process is controlled by -the news administrator; for mail, the expire process is controlled by -you. The expire process for mail is covered in depth in @ref{Expiring -Mail}. - -What many Gnus users find, after using it a while for both news and -mail, is that the transport mechanism has very little to do with how -they want to treat a message. - -Many people subscribe to several mailing lists. These are transported -via @acronym{SMTP}, and are therefore mail. But we might go for weeks without -answering, or even reading these messages very carefully. We may not -need to save them because if we should need to read one again, they are -archived somewhere else. - -Some people have local news groups which have only a handful of readers. -These are transported via @acronym{NNTP}, and are therefore news. But we may need -to read and answer a large fraction of the messages very carefully in -order to do our work. And there may not be an archive, so we may need -to save the interesting messages the same way we would personal mail. - -The important distinction turns out to be not the transport mechanism, -but other factors such as how interested we are in the subject matter, -or how easy it is to retrieve the message if we need to read it again. - -Gnus provides many options for sorting mail into ``groups'' which behave -like newsgroups, and for treating each group (whether mail or news) -differently. - -Some users never get comfortable using the Gnus (ahem) paradigm and wish -that Gnus should grow up and be a male, er, mail reader. It is possible -to whip Gnus into a more mailreaderly being, but, as said before, it's -not easy. People who prefer proper mail readers should try @sc{vm} -instead, which is an excellent, and proper, mail reader. - -I don't mean to scare anybody off, but I want to make it clear that you -may be required to learn a new way of thinking about messages. After -you've been subjected to The Gnus Way, you will come to love it. I can -guarantee it. (At least the guy who sold me the Emacs Subliminal -Brain-Washing Functions that I've put into Gnus did guarantee it. You -Will Be Assimilated. You Love Gnus. You Love The Gnus Mail Way. -You Do.) - - -@node Getting Started Reading Mail -@subsection Getting Started Reading Mail - -It's quite easy to use Gnus to read your new mail. You just plonk the -mail back end of your choice into @code{gnus-secondary-select-methods}, -and things will happen automatically. - -For instance, if you want to use @code{nnml} (which is a ``one file per -mail'' back end), you could put the following in your @file{~/.gnus.el} file: - -@lisp -(setq gnus-secondary-select-methods '((nnml ""))) -@end lisp - -Now, the next time you start Gnus, this back end will be queried for new -articles, and it will move all the messages in your spool file to its -directory, which is @file{~/Mail/} by default. The new group that will -be created (@samp{mail.misc}) will be subscribed, and you can read it -like any other group. - -You will probably want to split the mail into several groups, though: - -@lisp -(setq nnmail-split-methods - '(("junk" "^From:.*Lars Ingebrigtsen") - ("crazy" "^Subject:.*die\\|^Organization:.*flabby") - ("other" ""))) -@end lisp - -This will result in three new @code{nnml} mail groups being created: -@samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the -mail that doesn't fit into the first two groups will be placed in the -last group. - -This should be sufficient for reading mail with Gnus. You might want to -give the other sections in this part of the manual a perusal, though. -Especially @pxref{Choosing a Mail Back End} and @pxref{Expiring Mail}. - - -@node Splitting Mail -@subsection Splitting Mail -@cindex splitting mail -@cindex mail splitting -@cindex mail filtering (splitting) - -@vindex nnmail-split-methods -The @code{nnmail-split-methods} variable says how the incoming mail is -to be split into groups. - -@lisp -(setq nnmail-split-methods - '(("mail.junk" "^From:.*Lars Ingebrigtsen") - ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby") - ("mail.other" ""))) -@end lisp - -This variable is a list of lists, where the first element of each of -these lists is the name of the mail group (they do not have to be called -something beginning with @samp{mail}, by the way), and the second -element is a regular expression used on the header of each mail to -determine if it belongs in this mail group. The first string may -contain @samp{\\1} forms, like the ones used by @code{replace-match} to -insert sub-expressions from the matched text. For instance: - -@lisp -("list.\\1" "From:.* \\(.*\\)-list@@majordomo.com") -@end lisp - -@noindent -In that case, @code{nnmail-split-lowercase-expanded} controls whether -the inserted text should be made lowercase. @xref{Fancy Mail Splitting}. - -The second element can also be a function. In that case, it will be -called narrowed to the headers with the first element of the rule as the -argument. It should return a non-@code{nil} value if it thinks that the -mail belongs in that group. - -@cindex @samp{bogus} group -The last of these groups should always be a general one, and the regular -expression should @emph{always} be @samp{""} so that it matches any mails -that haven't been matched by any of the other regexps. (These rules are -processed from the beginning of the alist toward the end. The first rule -to make a match will ``win'', unless you have crossposting enabled. In -that case, all matching rules will ``win''.) If no rule matched, the mail -will end up in the @samp{bogus} group. When new groups are created by -splitting mail, you may want to run @code{gnus-group-find-new-groups} to -see the new groups. This also applies to the @samp{bogus} group. - -If you like to tinker with this yourself, you can set this variable to a -function of your choice. This function will be called without any -arguments in a buffer narrowed to the headers of an incoming mail -message. The function should return a list of group names that it -thinks should carry this mail message. - -This variable can also be a fancy split method. For the syntax, -see @ref{Fancy Mail Splitting}. - -Note that the mail back ends are free to maul the poor, innocent, -incoming headers all they want to. They all add @code{Lines} headers; -some add @code{X-Gnus-Group} headers; most rename the Unix mbox -@code{From} line to something else. - -@vindex nnmail-crosspost -The mail back ends all support cross-posting. If several regexps match, -the mail will be ``cross-posted'' to all those groups. -@code{nnmail-crosspost} says whether to use this mechanism or not. Note -that no articles are crossposted to the general (@samp{""}) group. - -@vindex nnmail-crosspost-link-function -@cindex crosspost -@cindex links -@code{nnmh} and @code{nnml} makes crossposts by creating hard links to -the crossposted articles. However, not all file systems support hard -links. If that's the case for you, set -@code{nnmail-crosspost-link-function} to @code{copy-file}. (This -variable is @code{add-name-to-file} by default.) - -@kindex M-x nnmail-split-history -@findex nnmail-split-history -If you wish to see where the previous mail split put the messages, you -can use the @kbd{M-x nnmail-split-history} command. If you wish to see -where re-spooling messages would put the messages, you can use -@code{gnus-summary-respool-trace} and related commands (@pxref{Mail -Group Commands}). - -@vindex nnmail-split-header-length-limit -Header lines longer than the value of -@code{nnmail-split-header-length-limit} are excluded from the split -function. - -@vindex nnmail-mail-splitting-decodes -@vindex nnmail-mail-splitting-charset -By default, splitting does not decode headers, so you can not match on -non-@acronym{ASCII} strings. But it is useful if you want to match -articles based on the raw header data. To enable it, set the -@code{nnmail-mail-splitting-decodes} variable to a non-@code{nil} value. -In addition, the value of the @code{nnmail-mail-splitting-charset} -variable is used for decoding non-@acronym{MIME} encoded string when -@code{nnmail-mail-splitting-decodes} is non-@code{nil}. The default -value is @code{nil} which means not to decode non-@acronym{MIME} encoded -string. A suitable value for you will be @code{undecided} or be the -charset used normally in mails you are interested in. - -@vindex nnmail-resplit-incoming -By default, splitting is performed on all incoming messages. If you -specify a @code{directory} entry for the variable @code{mail-sources} -(@pxref{Mail Source Specifiers}), however, then splitting does -@emph{not} happen by default. You can set the variable -@code{nnmail-resplit-incoming} to a non-@code{nil} value to make -splitting happen even in this case. (This variable has no effect on -other kinds of entries.) - -Gnus gives you all the opportunity you could possibly want for shooting -yourself in the foot. Let's say you create a group that will contain -all the mail you get from your boss. And then you accidentally -unsubscribe from the group. Gnus will still put all the mail from your -boss in the unsubscribed group, and so, when your boss mails you ``Have -that report ready by Monday or you're fired!'', you'll never see it and, -come Tuesday, you'll still believe that you're gainfully employed while -you really should be out collecting empty bottles to save up for next -month's rent money. - - -@node Mail Sources -@subsection Mail Sources - -Mail can be gotten from many different sources---the mail spool, from -a @acronym{POP} mail server, from a procmail directory, or from a -maildir, for instance. - -@menu -* Mail Source Specifiers:: How to specify what a mail source is. -* Mail Source Customization:: Some variables that influence things. -* Fetching Mail:: Using the mail source specifiers. -@end menu - - -@node Mail Source Specifiers -@subsubsection Mail Source Specifiers -@cindex POP -@cindex mail server -@cindex procmail -@cindex mail spool -@cindex mail source - -You tell Gnus how to fetch mail by setting @code{mail-sources} -(@pxref{Fetching Mail}) to a @dfn{mail source specifier}. - -Here's an example: - -@lisp -(pop :server "pop3.mailserver.com" :user "myname") -@end lisp - -As can be observed, a mail source specifier is a list where the first -element is a @dfn{mail source type}, followed by an arbitrary number of -@dfn{keywords}. Keywords that are not explicitly specified are given -default values. - -The @code{mail-sources} is global for all mail groups. You can specify -an additional mail source for a particular group by including the -@code{group} mail specifier in @code{mail-sources}, and setting a -@code{mail-source} group parameter (@pxref{Group Parameters}) specifying -a single mail source. When this is used, @code{mail-sources} is -typically just @code{(group)}; the @code{mail-source} parameter for a -group might look like this: - -@lisp -(mail-source . (file :path "home/user/spools/foo.spool")) -@end lisp - -This means that the group's (and only this group's) messages will be -fetched from the spool file @samp{/user/spools/foo.spool}. - -The following mail source types are available: - -@table @code -@item file -Get mail from a single file; typically from the mail spool. - -Keywords: - -@table @code -@item :path -The file name. Defaults to the value of the @env{MAIL} -environment variable or the value of @code{rmail-spool-directory} -(usually something like @file{/usr/mail/spool/user-name}). - -@item :prescript -@itemx :postscript -Script run before/after fetching mail. -@end table - -An example file mail source: - -@lisp -(file :path "/usr/spool/mail/user-name") -@end lisp - -Or using the default file name: - -@lisp -(file) -@end lisp - -If the mail spool file is not located on the local machine, it's best -to use @acronym{POP} or @acronym{IMAP} or the like to fetch the mail. -You can not use ange-ftp file names here---it has no way to lock the -mail spool while moving the mail. - -If it's impossible to set up a proper server, you can use ssh instead. - -@lisp -(setq mail-sources - '((file :prescript "ssh host bin/getmail >%t"))) -@end lisp - -The @samp{getmail} script would look something like the following: - -@example -#!/bin/sh -# getmail - move mail from spool to stdout -# flu@@iki.fi - -MOVEMAIL=/usr/lib/emacs/20.3/i386-redhat-linux/movemail -TMP=$HOME/Mail/tmp -rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP -@end example - -Alter this script to fit the @samp{movemail} and temporary -file you want to use. - - -@item directory -@vindex nnmail-scan-directory-mail-source-once -Get mail from several files in a directory. This is typically used -when you have procmail split the incoming mail into several files. -That is, there is a one-to-one correspondence between files in that -directory and groups, so that mail from the file @file{foo.bar.spool} -will be put in the group @code{foo.bar}. (You can change the suffix -to be used instead of @code{.spool}.) Setting -@code{nnmail-scan-directory-mail-source-once} to non-@code{nil} forces -Gnus to scan the mail source only once. This is particularly useful -if you want to scan mail groups at a specified level. - -@vindex nnmail-resplit-incoming -There is also the variable @code{nnmail-resplit-incoming}, if you set -that to a non-@code{nil} value, then the normal splitting process is -applied to all the files from the directory, @ref{Splitting Mail}. - -Keywords: - -@table @code -@item :path -The name of the directory where the files are. There is no default -value. - -@item :suffix -Only files ending with this suffix are used. The default is -@samp{.spool}. - -@item :predicate -Only files that have this predicate return non-@code{nil} are returned. -The default is @code{identity}. This is used as an additional -filter---only files that have the right suffix @emph{and} satisfy this -predicate are considered. - -@item :prescript -@itemx :postscript -Script run before/after fetching mail. - -@end table - -An example directory mail source: - -@lisp -(directory :path "/home/user-name/procmail-dir/" - :suffix ".prcml") -@end lisp - -@item pop -Get mail from a @acronym{POP} server. - -Keywords: - -@table @code -@item :server -The name of the @acronym{POP} server. The default is taken from the -@env{MAILHOST} environment variable. - -@item :port -The port number of the @acronym{POP} server. This can be a number (eg, -@samp{:port 1234}) or a string (eg, @samp{:port "pop3"}). If it is a -string, it should be a service name as listed in @file{/etc/services} on -Unix systems. The default is @samp{"pop3"}. On some systems you might -need to specify it as @samp{"pop-3"} instead. - -@item :user -The user name to give to the @acronym{POP} server. The default is the login -name. - -@item :password -The password to give to the @acronym{POP} server. If not specified, -the user is prompted. - -@item :program -The program to use to fetch mail from the @acronym{POP} server. This -should be a @code{format}-like string. Here's an example: - -@example -fetchmail %u@@%s -P %p %t -@end example - -The valid format specifier characters are: - -@table @samp -@item t -The name of the file the mail is to be moved to. This must always be -included in this string. - -@item s -The name of the server. - -@item P -The port number of the server. - -@item u -The user name to use. - -@item p -The password to use. -@end table - -The values used for these specs are taken from the values you give the -corresponding keywords. - -@item :prescript -A script to be run before fetching the mail. The syntax is the same as -the @code{:program} keyword. This can also be a function to be run. - -One popular way to use this is to set up an SSH tunnel to access the -@acronym{POP} server. Here's an example: - -@lisp -(pop :server "127.0.0.1" - :port 1234 - :user "foo" - :password "secret" - :prescript - "nohup ssh -f -L 1234:pop.server:110 remote.host sleep 3600 &") -@end lisp - -@item :postscript -A script to be run after fetching the mail. The syntax is the same as -the @code{:program} keyword. This can also be a function to be run. - -@item :function -The function to use to fetch mail from the @acronym{POP} server. The -function is called with one parameter---the name of the file where the -mail should be moved to. - -@item :authentication -This can be either the symbol @code{password} or the symbol @code{apop} -and says what authentication scheme to use. The default is -@code{password}. - -@end table - -@vindex pop3-movemail -@vindex pop3-leave-mail-on-server -If the @code{:program} and @code{:function} keywords aren't specified, -@code{pop3-movemail} will be used. If @code{pop3-leave-mail-on-server} -is non-@code{nil} the mail is to be left on the @acronym{POP} server -after fetching when using @code{pop3-movemail}. Note that POP servers -maintain no state information between sessions, so what the client -believes is there and what is actually there may not match up. If they -do not, then you may get duplicate mails or the whole thing can fall -apart and leave you with a corrupt mailbox. - -Here are some examples for getting mail from a @acronym{POP} server. -Fetch from the default @acronym{POP} server, using the default user -name, and default fetcher: - -@lisp -(pop) -@end lisp - -Fetch from a named server with a named user and password: - -@lisp -(pop :server "my.pop.server" - :user "user-name" :password "secret") -@end lisp - -Use @samp{movemail} to move the mail: - -@lisp -(pop :program "movemail po:%u %t %p") -@end lisp - -@item maildir -Get mail from a maildir. This is a type of mailbox that is supported by -at least qmail and postfix, where each file in a special directory -contains exactly one mail. - -Keywords: - -@table @code -@item :path -The name of the directory where the mails are stored. The default is -taken from the @env{MAILDIR} environment variable or -@file{~/Maildir/}. -@item :subdirs -The subdirectories of the Maildir. The default is -@samp{("new" "cur")}. - -@c If you sometimes look at your mail through a pop3 daemon before fetching -@c them with Gnus, you may also have to fetch your mails from the -@c @code{cur} directory inside the maildir, like in the first example -@c below. - -You can also get mails from remote hosts (because maildirs don't suffer -from locking problems). - -@end table - -Two example maildir mail sources: - -@lisp -(maildir :path "/home/user-name/Maildir/" - :subdirs ("cur" "new")) -@end lisp - -@lisp -(maildir :path "/user@@remotehost.org:~/Maildir/" - :subdirs ("new")) -@end lisp - -@item imap -Get mail from a @acronym{IMAP} server. If you don't want to use -@acronym{IMAP} as intended, as a network mail reading protocol (ie -with nnimap), for some reason or other, Gnus let you treat it similar -to a @acronym{POP} server and fetches articles from a given -@acronym{IMAP} mailbox. @xref{Using IMAP}, for more information. - -Keywords: - -@table @code -@item :server -The name of the @acronym{IMAP} server. The default is taken from the -@env{MAILHOST} environment variable. - -@item :port -The port number of the @acronym{IMAP} server. The default is @samp{143}, or -@samp{993} for @acronym{TLS}/@acronym{SSL} connections. - -@item :user -The user name to give to the @acronym{IMAP} server. The default is the login -name. - -@item :password -The password to give to the @acronym{IMAP} server. If not specified, the user is -prompted. - -@item :stream -What stream to use for connecting to the server, this is one of the -symbols in @code{imap-stream-alist}. Right now, this means -@samp{gssapi}, @samp{kerberos4}, @samp{starttls}, @samp{tls}, -@samp{ssl}, @samp{shell} or the default @samp{network}. - -@item :authentication -Which authenticator to use for authenticating to the server, this is -one of the symbols in @code{imap-authenticator-alist}. Right now, -this means @samp{gssapi}, @samp{kerberos4}, @samp{digest-md5}, -@samp{cram-md5}, @samp{anonymous} or the default @samp{login}. - -@item :program -When using the `shell' :stream, the contents of this variable is -mapped into the @code{imap-shell-program} variable. This should be a -@code{format}-like string (or list of strings). Here's an example: - -@example -ssh %s imapd -@end example - -Make sure nothing is interfering with the output of the program, e.g., -don't forget to redirect the error output to the void. The valid format -specifier characters are: - -@table @samp -@item s -The name of the server. - -@item l -User name from @code{imap-default-user}. - -@item p -The port number of the server. -@end table - -The values used for these specs are taken from the values you give the -corresponding keywords. - -@item :mailbox -The name of the mailbox to get mail from. The default is @samp{INBOX} -which normally is the mailbox which receives incoming mail. - -@item :predicate -The predicate used to find articles to fetch. The default, @samp{UNSEEN -UNDELETED}, is probably the best choice for most people, but if you -sometimes peek in your mailbox with a @acronym{IMAP} client and mark some -articles as read (or; SEEN) you might want to set this to @samp{1:*}. -Then all articles in the mailbox is fetched, no matter what. For a -complete list of predicates, see RFC 2060 section 6.4.4. - -@item :fetchflag -How to flag fetched articles on the server, the default @samp{\Deleted} -will mark them as deleted, an alternative would be @samp{\Seen} which -would simply mark them as read. These are the two most likely choices, -but more flags are defined in RFC 2060 section 2.3.2. - -@item :dontexpunge -If non-@code{nil}, don't remove all articles marked as deleted in the -mailbox after finishing the fetch. - -@end table - -An example @acronym{IMAP} mail source: - -@lisp -(imap :server "mail.mycorp.com" - :stream kerberos4 - :fetchflag "\\Seen") -@end lisp - -@item group -Get the actual mail source from the @code{mail-source} group parameter, -@xref{Group Parameters}. - -@end table - -@table @dfn -@item Common Keywords -Common keywords can be used in any type of mail source. - -Keywords: - -@table @code -@item :plugged -If non-@code{nil}, fetch the mail even when Gnus is unplugged. If you -use directory source to get mail, you can specify it as in this -example: - -@lisp -(setq mail-sources - '((directory :path "/home/pavel/.Spool/" - :suffix "" - :plugged t))) -@end lisp - -Gnus will then fetch your mail even when you are unplugged. This is -useful when you use local mail and news. - -@end table -@end table - -@subsubsection Function Interface - -Some of the above keywords specify a Lisp function to be executed. -For each keyword @code{:foo}, the Lisp variable @code{foo} is bound to -the value of the keyword while the function is executing. For example, -consider the following mail-source setting: - -@lisp -(setq mail-sources '((pop :user "jrl" - :server "pophost" :function fetchfunc))) -@end lisp - -While the function @code{fetchfunc} is executing, the symbol @code{user} -is bound to @code{"jrl"}, and the symbol @code{server} is bound to -@code{"pophost"}. The symbols @code{port}, @code{password}, -@code{program}, @code{prescript}, @code{postscript}, @code{function}, -and @code{authentication} are also bound (to their default values). - -See above for a list of keywords for each type of mail source. - - -@node Mail Source Customization -@subsubsection Mail Source Customization - -The following is a list of variables that influence how the mail is -fetched. You would normally not need to set or change any of these -variables. - -@table @code -@item mail-source-crash-box -@vindex mail-source-crash-box -File where mail will be stored while processing it. The default is@* -@file{~/.emacs-mail-crash-box}. - -@cindex Incoming* -@item mail-source-delete-incoming -@vindex mail-source-delete-incoming -If non-@code{nil}, delete incoming files after handling them. If -@code{t}, delete the files immediately, if @code{nil}, never delete any -files. If a positive number, delete files older than number of days -(the deletion will only happen when receiving new mail). You may also -set @code{mail-source-delete-incoming} to @code{nil} and call -@code{mail-source-delete-old-incoming} from a hook or interactively. -@code{mail-source-delete-incoming} defaults to @code{10} in alpha Gnusae -and @code{2} in released Gnusae. @xref{Gnus Development}. - -@item mail-source-delete-old-incoming-confirm -@vindex mail-source-delete-old-incoming-confirm -If non-@code{nil}, ask for confirmation before deleting old incoming -files. This variable only applies when -@code{mail-source-delete-incoming} is a positive number. - -@item mail-source-ignore-errors -@vindex mail-source-ignore-errors -If non-@code{nil}, ignore errors when reading mail from a mail source. - -@item mail-source-directory -@vindex mail-source-directory -Directory where incoming mail source files (if any) will be stored. The -default is @file{~/Mail/}. At present, the only thing this is used for -is to say where the incoming files will be stored if the variable -@code{mail-source-delete-incoming} is @code{nil} or a number. - -@item mail-source-incoming-file-prefix -@vindex mail-source-incoming-file-prefix -Prefix for file name for storing incoming mail. The default is -@file{Incoming}, in which case files will end up with names like -@file{Incoming30630D_} or @file{Incoming298602ZD}. This is really only -relevant if @code{mail-source-delete-incoming} is @code{nil} or a -number. - -@item mail-source-default-file-modes -@vindex mail-source-default-file-modes -All new mail files will get this file mode. The default is @code{#o600}. - -@item mail-source-movemail-program -@vindex mail-source-movemail-program -If non-@code{nil}, name of program for fetching new mail. If -@code{nil}, @code{movemail} in @var{exec-directory}. - -@end table - - -@node Fetching Mail -@subsubsection Fetching Mail - -@vindex mail-sources -The way to actually tell Gnus where to get new mail from is to set -@code{mail-sources} to a list of mail source specifiers -(@pxref{Mail Source Specifiers}). - -If this variable is @code{nil}, the mail back ends will never attempt to -fetch mail by themselves. - -If you want to fetch mail both from your local spool as well as a -@acronym{POP} mail server, you'd say something like: - -@lisp -(setq mail-sources - '((file) - (pop :server "pop3.mail.server" - :password "secret"))) -@end lisp - -Or, if you don't want to use any of the keyword defaults: - -@lisp -(setq mail-sources - '((file :path "/var/spool/mail/user-name") - (pop :server "pop3.mail.server" - :user "user-name" - :port "pop3" - :password "secret"))) -@end lisp - - -When you use a mail back end, Gnus will slurp all your mail from your -inbox and plonk it down in your home directory. Gnus doesn't move any -mail if you're not using a mail back end---you have to do a lot of magic -invocations first. At the time when you have finished drawing the -pentagram, lightened the candles, and sacrificed the goat, you really -shouldn't be too surprised when Gnus moves your mail. - - - -@node Mail Back End Variables -@subsection Mail Back End Variables - -These variables are (for the most part) pertinent to all the various -mail back ends. - -@table @code -@vindex nnmail-read-incoming-hook -@item nnmail-read-incoming-hook -The mail back ends all call this hook after reading new mail. You can -use this hook to notify any mail watch programs, if you want to. - -@vindex nnmail-split-hook -@item nnmail-split-hook -@findex gnus-article-decode-encoded-words -@cindex RFC 1522 decoding -@cindex RFC 2047 decoding -Hook run in the buffer where the mail headers of each message is kept -just before the splitting based on these headers is done. The hook is -free to modify the buffer contents in any way it sees fit---the buffer -is discarded after the splitting has been done, and no changes performed -in the buffer will show up in any files. -@code{gnus-article-decode-encoded-words} is one likely function to add -to this hook. - -@vindex nnmail-pre-get-new-mail-hook -@vindex nnmail-post-get-new-mail-hook -@item nnmail-pre-get-new-mail-hook -@itemx nnmail-post-get-new-mail-hook -These are two useful hooks executed when treating new incoming -mail---@code{nnmail-pre-get-new-mail-hook} (is called just before -starting to handle the new mail) and -@code{nnmail-post-get-new-mail-hook} (is called when the mail handling -is done). Here's and example of using these two hooks to change the -default file modes the new mail files get: - -@lisp -(add-hook 'nnmail-pre-get-new-mail-hook - (lambda () (set-default-file-modes #o700))) - -(add-hook 'nnmail-post-get-new-mail-hook - (lambda () (set-default-file-modes #o775))) -@end lisp - -@item nnmail-use-long-file-names -@vindex nnmail-use-long-file-names -If non-@code{nil}, the mail back ends will use long file and directory -names. Groups like @samp{mail.misc} will end up in directories -(assuming use of @code{nnml} back end) or files (assuming use of -@code{nnfolder} back end) like @file{mail.misc}. If it is @code{nil}, -the same group will end up in @file{mail/misc}. - -@item nnmail-delete-file-function -@vindex nnmail-delete-file-function -@findex delete-file -Function called to delete files. It is @code{delete-file} by default. - -@item nnmail-cache-accepted-message-ids -@vindex nnmail-cache-accepted-message-ids -If non-@code{nil}, put the @code{Message-ID}s of articles imported into -the back end (via @code{Gcc}, for instance) into the mail duplication -discovery cache. The default is @code{nil}. - -@item nnmail-cache-ignore-groups -@vindex nnmail-cache-ignore-groups -This can be a regular expression or a list of regular expressions. -Group names that match any of the regular expressions will never be -recorded in the @code{Message-ID} cache. - -This can be useful, for example, when using Fancy Splitting -(@pxref{Fancy Mail Splitting}) together with the function -@code{nnmail-split-fancy-with-parent}. - -@end table - - -@node Fancy Mail Splitting -@subsection Fancy Mail Splitting -@cindex mail splitting -@cindex fancy mail splitting - -@vindex nnmail-split-fancy -@findex nnmail-split-fancy -If the rather simple, standard method for specifying how to split mail -doesn't allow you to do what you want, you can set -@code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can -play with the @code{nnmail-split-fancy} variable. - -Let's look at an example value of this variable first: - -@lisp -;; @r{Messages from the mailer daemon are not crossposted to any of} -;; @r{the ordinary groups. Warnings are put in a separate group} -;; @r{from real errors.} -(| ("from" mail (| ("subject" "warn.*" "mail.warning") - "mail.misc")) - ;; @r{Non-error messages are crossposted to all relevant} - ;; @r{groups, but we don't crosspost between the group for the} - ;; @r{(ding) list and the group for other (ding) related mail.} - (& (| (any "ding@@ifi\\.uio\\.no" "ding.list") - ("subject" "ding" "ding.misc")) - ;; @r{Other mailing lists@dots{}} - (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list") - (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list") - ;; @r{Both lists below have the same suffix, so prevent} - ;; @r{cross-posting to mkpkg.list of messages posted only to} - ;; @r{the bugs- list, but allow cross-posting when the} - ;; @r{message was really cross-posted.} - (any "bugs-mypackage@@somewhere" "mypkg.bugs") - (any "mypackage@@somewhere" - "bugs-mypackage" "mypkg.list") - ;; @r{People@dots{}} - (any "larsi@@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen")) - ;; @r{Unmatched mail goes to the catch all group.} - "misc.misc") -@end lisp - -This variable has the format of a @dfn{split}. A split is a -(possibly) recursive structure where each split may contain other -splits. Here are the possible split syntaxes: - -@table @code - -@item group -If the split is a string, that will be taken as a group name. Normal -regexp match expansion will be done. See below for examples. - -@c Don't fold this line. -@item (@var{field} @var{value} [- @var{restrict} [@dots{}] ] @var{split} [@var{invert-partial}]) -The split can be a list containing at least three elements. If the -first element @var{field} (a regexp matching a header) contains -@var{value} (also a regexp) then store the message as specified by -@var{split}. - -If @var{restrict} (yet another regexp) matches some string after -@var{field} and before the end of the matched @var{value}, the -@var{split} is ignored. If none of the @var{restrict} clauses match, -@var{split} is processed. - -The last element @var{invert-partial} is optional. If it is -non-@code{nil}, the match-partial-words behavior controlled by the -variable @code{nnmail-split-fancy-match-partial-words} (see below) is -be inverted. (New in Gnus 5.10.7) - -@item (| @var{split} @dots{}) -If the split is a list, and the first element is @code{|} (vertical -bar), then process each @var{split} until one of them matches. A -@var{split} is said to match if it will cause the mail message to be -stored in one or more groups. - -@item (& @var{split} @dots{}) -If the split is a list, and the first element is @code{&}, then -process all @var{split}s in the list. - -@item junk -If the split is the symbol @code{junk}, then don't save (i.e., delete) -this message. Use with extreme caution. - -@item (: @var{function} @var{arg1} @var{arg2} @dots{}) -If the split is a list, and the first element is @samp{:}, then the -second element will be called as a function with @var{args} given as -arguments. The function should return a @var{split}. - -@cindex body split -For instance, the following function could be used to split based on the -body of the messages: - -@lisp -(defun split-on-body () - (save-excursion - (save-restriction - (widen) - (goto-char (point-min)) - (when (re-search-forward "Some.*string" nil t) - "string.group")))) -@end lisp - -The buffer is narrowed to the header of the message in question when -@var{function} is run. That's why @code{(widen)} needs to be called -after @code{save-excursion} and @code{save-restriction} in the example -above. Also note that with the nnimap backend, message bodies will -not be downloaded by default. You need to set -@code{nnimap-split-download-body} to @code{t} to do that -(@pxref{Client-Side IMAP Splitting}). - -@item (! @var{func} @var{split}) -If the split is a list, and the first element is @code{!}, then -@var{split} will be processed, and @var{func} will be called as a -function with the result of @var{split} as argument. @var{func} -should return a split. - -@item nil -If the split is @code{nil}, it is ignored. - -@end table - -In these splits, @var{field} must match a complete field name. - -Normally, @var{value} in these splits must match a complete @emph{word} -according to the fundamental mode syntax table. In other words, all -@var{value}'s will be implicitly surrounded by @code{\<...\>} markers, -which are word delimiters. Therefore, if you use the following split, -for example, - -@example -(any "joe" "joemail") -@end example - -@noindent -messages sent from @samp{joedavis@@foo.org} will normally not be filed -in @samp{joemail}. If you want to alter this behavior, you can use any -of the following three ways: - -@enumerate -@item -@vindex nnmail-split-fancy-match-partial-words -You can set the @code{nnmail-split-fancy-match-partial-words} variable -to non-@code{nil} in order to ignore word boundaries and instead the -match becomes more like a grep. This variable controls whether partial -words are matched during fancy splitting. The default value is -@code{nil}. - -Note that it influences all @var{value}'s in your split rules. - -@item -@var{value} beginning with @code{.*} ignores word boundaries in front of -a word. Similarly, if @var{value} ends with @code{.*}, word boundaries -in the rear of a word will be ignored. For example, the @var{value} -@code{"@@example\\.com"} does not match @samp{foo@@example.com} but -@code{".*@@example\\.com"} does. - -@item -You can set the @var{invert-partial} flag in your split rules of the -@samp{(@var{field} @var{value} @dots{})} types, aforementioned in this -section. If the flag is set, word boundaries on both sides of a word -are ignored even if @code{nnmail-split-fancy-match-partial-words} is -@code{nil}. Contrarily, if the flag is set, word boundaries are not -ignored even if @code{nnmail-split-fancy-match-partial-words} is -non-@code{nil}. (New in Gnus 5.10.7) -@end enumerate - -@vindex nnmail-split-abbrev-alist -@var{field} and @var{value} can also be Lisp symbols, in that case -they are expanded as specified by the variable -@code{nnmail-split-abbrev-alist}. This is an alist of cons cells, -where the @sc{car} of a cell contains the key, and the @sc{cdr} -contains the associated value. Predefined entries in -@code{nnmail-split-abbrev-alist} include: - -@table @code -@item from -Matches the @samp{From}, @samp{Sender} and @samp{Resent-From} fields. -@item to -Matches the @samp{To}, @samp{Cc}, @samp{Apparently-To}, -@samp{Resent-To} and @samp{Resent-Cc} fields. -@item any -Is the union of the @code{from} and @code{to} entries. -@end table - -@vindex nnmail-split-fancy-syntax-table -@code{nnmail-split-fancy-syntax-table} is the syntax table in effect -when all this splitting is performed. - -If you want to have Gnus create groups dynamically based on some -information in the headers (i.e., do @code{replace-match}-like -substitutions in the group names), you can say things like: - -@example -(any "debian-\\b\\(\\w+\\)@@lists.debian.org" "mail.debian.\\1") -@end example - -In this example, messages sent to @samp{debian-foo@@lists.debian.org} -will be filed in @samp{mail.debian.foo}. - -If the string contains the element @samp{\&}, then the previously -matched string will be substituted. Similarly, the elements @samp{\\1} -up to @samp{\\9} will be substituted with the text matched by the -groupings 1 through 9. - -@vindex nnmail-split-lowercase-expanded -Where @code{nnmail-split-lowercase-expanded} controls whether the -lowercase of the matched string should be used for the substitution. -Setting it as non-@code{nil} is useful to avoid the creation of multiple -groups when users send to an address using different case -(i.e. mailing-list@@domain vs Mailing-List@@Domain). The default value -is @code{t}. - -@findex nnmail-split-fancy-with-parent -@code{nnmail-split-fancy-with-parent} is a function which allows you to -split followups into the same groups their parents are in. Sometimes -you can't make splitting rules for all your mail. For example, your -boss might send you personal mail regarding different projects you are -working on, and as you can't tell your boss to put a distinguishing -string into the subject line, you have to resort to manually moving the -messages into the right group. With this function, you only have to do -it once per thread. - -To use this feature, you have to set @code{nnmail-treat-duplicates} -and @code{nnmail-cache-accepted-message-ids} to a non-@code{nil} -value. And then you can include @code{nnmail-split-fancy-with-parent} -using the colon feature, like so: -@lisp -(setq nnmail-treat-duplicates 'warn ; @r{or @code{delete}} - nnmail-cache-accepted-message-ids t - nnmail-split-fancy - '(| (: nnmail-split-fancy-with-parent) - ;; @r{other splits go here} - )) -@end lisp - -This feature works as follows: when @code{nnmail-treat-duplicates} is -non-@code{nil}, Gnus records the message id of every message it sees -in the file specified by the variable -@code{nnmail-message-id-cache-file}, together with the group it is in -(the group is omitted for non-mail messages). When mail splitting is -invoked, the function @code{nnmail-split-fancy-with-parent} then looks -at the References (and In-Reply-To) header of each message to split -and searches the file specified by @code{nnmail-message-id-cache-file} -for the message ids. When it has found a parent, it returns the -corresponding group name unless the group name matches the regexp -@code{nnmail-split-fancy-with-parent-ignore-groups}. It is -recommended that you set @code{nnmail-message-id-cache-length} to a -somewhat higher number than the default so that the message ids are -still in the cache. (A value of 5000 appears to create a file some -300 kBytes in size.) -@vindex nnmail-cache-accepted-message-ids -When @code{nnmail-cache-accepted-message-ids} is non-@code{nil}, Gnus -also records the message ids of moved articles, so that the followup -messages goes into the new group. - -Also see the variable @code{nnmail-cache-ignore-groups} if you don't -want certain groups to be recorded in the cache. For example, if all -outgoing messages are written to an ``outgoing'' group, you could set -@code{nnmail-cache-ignore-groups} to match that group name. -Otherwise, answers to all your messages would end up in the -``outgoing'' group. - - -@node Group Mail Splitting -@subsection Group Mail Splitting -@cindex mail splitting -@cindex group mail splitting - -@findex gnus-group-split -If you subscribe to dozens of mailing lists but you don't want to -maintain mail splitting rules manually, group mail splitting is for you. -You just have to set @code{to-list} and/or @code{to-address} in group -parameters or group customization and set @code{nnmail-split-methods} to -@code{gnus-group-split}. This splitting function will scan all groups -for those parameters and split mail accordingly, i.e., messages posted -from or to the addresses specified in the parameters @code{to-list} or -@code{to-address} of a mail group will be stored in that group. - -Sometimes, mailing lists have multiple addresses, and you may want mail -splitting to recognize them all: just set the @code{extra-aliases} group -parameter to the list of additional addresses and it's done. If you'd -rather use a regular expression, set @code{split-regexp}. - -All these parameters in a group will be used to create an -@code{nnmail-split-fancy} split, in which the @var{field} is @samp{any}, -the @var{value} is a single regular expression that matches -@code{to-list}, @code{to-address}, all of @code{extra-aliases} and all -matches of @code{split-regexp}, and the @var{split} is the name of the -group. @var{restrict}s are also supported: just set the -@code{split-exclude} parameter to a list of regular expressions. - -If you can't get the right split to be generated using all these -parameters, or you just need something fancier, you can set the -parameter @code{split-spec} to an @code{nnmail-split-fancy} split. In -this case, all other aforementioned parameters will be ignored by -@code{gnus-group-split}. In particular, @code{split-spec} may be set to -@code{nil}, in which case the group will be ignored by -@code{gnus-group-split}. - -@vindex gnus-group-split-default-catch-all-group -@code{gnus-group-split} will do cross-posting on all groups that match, -by defining a single @code{&} fancy split containing one split for each -group. If a message doesn't match any split, it will be stored in the -group named in @code{gnus-group-split-default-catch-all-group}, unless -some group has @code{split-spec} set to @code{catch-all}, in which case -that group is used as the catch-all group. Even though this variable is -often used just to name a group, it may also be set to an arbitrarily -complex fancy split (after all, a group name is a fancy split), and this -may be useful to split mail that doesn't go to any mailing list to -personal mail folders. Note that this fancy split is added as the last -element of a @code{|} split list that also contains a @code{&} split -with the rules extracted from group parameters. - -It's time for an example. Assume the following group parameters have -been defined: - -@example -nnml:mail.bar: -((to-address . "bar@@femail.com") - (split-regexp . ".*@@femail\\.com")) -nnml:mail.foo: -((to-list . "foo@@nowhere.gov") - (extra-aliases "foo@@localhost" "foo-redist@@home") - (split-exclude "bugs-foo" "rambling-foo") - (admin-address . "foo-request@@nowhere.gov")) -nnml:mail.others: -((split-spec . catch-all)) -@end example - -Setting @code{nnmail-split-methods} to @code{gnus-group-split} will -behave as if @code{nnmail-split-fancy} had been selected and variable -@code{nnmail-split-fancy} had been set as follows: - -@lisp -(| (& (any "\\(bar@@femail\\.com\\|.*@@femail\\.com\\)" "mail.bar") - (any "\\(foo@@nowhere\\.gov\\|foo@@localhost\\|foo-redist@@home\\)" - - "bugs-foo" - "rambling-foo" "mail.foo")) - "mail.others") -@end lisp - -@findex gnus-group-split-fancy -If you'd rather not use group splitting for all your mail groups, you -may use it for only some of them, by using @code{nnmail-split-fancy} -splits like this: - -@lisp -(: gnus-group-split-fancy @var{groups} @var{no-crosspost} @var{catch-all}) -@end lisp - -@var{groups} may be a regular expression or a list of group names whose -parameters will be scanned to generate the output split. -@var{no-crosspost} can be used to disable cross-posting; in this case, a -single @code{|} split will be output. @var{catch-all} is the fall back -fancy split, used like @code{gnus-group-split-default-catch-all-group}. -If @var{catch-all} is @code{nil}, or if @code{split-regexp} matches the -empty string in any selected group, no catch-all split will be issued. -Otherwise, if some group has @code{split-spec} set to @code{catch-all}, -this group will override the value of the @var{catch-all} argument. - -@findex gnus-group-split-setup -Unfortunately, scanning all groups and their parameters can be quite -slow, especially considering that it has to be done for every message. -But don't despair! The function @code{gnus-group-split-setup} can be -used to enable @code{gnus-group-split} in a much more efficient way. It -sets @code{nnmail-split-methods} to @code{nnmail-split-fancy} and sets -@code{nnmail-split-fancy} to the split produced by -@code{gnus-group-split-fancy}. Thus, the group parameters are only -scanned once, no matter how many messages are split. - -@findex gnus-group-split-update -However, if you change group parameters, you'd have to update -@code{nnmail-split-fancy} manually. You can do it by running -@code{gnus-group-split-update}. If you'd rather have it updated -automatically, just tell @code{gnus-group-split-setup} to do it for -you. For example, add to your @file{~/.gnus.el}: - -@lisp -(gnus-group-split-setup @var{auto-update} @var{catch-all}) -@end lisp - -If @var{auto-update} is non-@code{nil}, @code{gnus-group-split-update} -will be added to @code{nnmail-pre-get-new-mail-hook}, so you won't ever -have to worry about updating @code{nnmail-split-fancy} again. If you -don't omit @var{catch-all} (it's optional, equivalent to @code{nil}), -@code{gnus-group-split-default-catch-all-group} will be set to its -value. - -@vindex gnus-group-split-updated-hook -Because you may want to change @code{nnmail-split-fancy} after it is set -by @code{gnus-group-split-update}, this function will run -@code{gnus-group-split-updated-hook} just before finishing. - -@node Incorporating Old Mail -@subsection Incorporating Old Mail -@cindex incorporating old mail -@cindex import old mail - -Most people have lots of old mail stored in various file formats. If -you have set up Gnus to read mail using one of the spiffy Gnus mail -back ends, you'll probably wish to have that old mail incorporated into -your mail groups. - -Doing so can be quite easy. - -To take an example: You're reading mail using @code{nnml} -(@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a -satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox -file filled with important, but old, mail. You want to move it into -your @code{nnml} groups. - -Here's how: - -@enumerate -@item -Go to the group buffer. - -@item -Type @kbd{G f} and give the file name to the mbox file when prompted to create an -@code{nndoc} group from the mbox file (@pxref{Foreign Groups}). - -@item -Type @kbd{SPACE} to enter the newly created group. - -@item -Type @kbd{M P b} to process-mark all articles in this group's buffer -(@pxref{Setting Process Marks}). - -@item -Type @kbd{B r} to respool all the process-marked articles, and answer -@samp{nnml} when prompted (@pxref{Mail Group Commands}). -@end enumerate - -All the mail messages in the mbox file will now also be spread out over -all your @code{nnml} groups. Try entering them and check whether things -have gone without a glitch. If things look ok, you may consider -deleting the mbox file, but I wouldn't do that unless I was absolutely -sure that all the mail has ended up where it should be. - -Respooling is also a handy thing to do if you're switching from one mail -back end to another. Just respool all the mail in the old mail groups -using the new mail back end. - - -@node Expiring Mail -@subsection Expiring Mail -@cindex article expiry -@cindex expiring mail - -Traditional mail readers have a tendency to remove mail articles when -you mark them as read, in some way. Gnus takes a fundamentally -different approach to mail reading. - -Gnus basically considers mail just to be news that has been received in -a rather peculiar manner. It does not think that it has the power to -actually change the mail, or delete any mail messages. If you enter a -mail group, and mark articles as ``read'', or kill them in some other -fashion, the mail articles will still exist on the system. I repeat: -Gnus will not delete your old, read mail. Unless you ask it to, of -course. - -To make Gnus get rid of your unwanted mail, you have to mark the -articles as @dfn{expirable}. (With the default key bindings, this means -that you have to type @kbd{E}.) This does not mean that the articles -will disappear right away, however. In general, a mail article will be -deleted from your system if, 1) it is marked as expirable, AND 2) it is -more than one week old. If you do not mark an article as expirable, it -will remain on your system until hell freezes over. This bears -repeating one more time, with some spurious capitalizations: IF you do -NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES. - -@vindex gnus-auto-expirable-marks -You do not have to mark articles as expirable by hand. Gnus provides -two features, called ``auto-expire'' and ``total-expire'', that can help you -with this. In a nutshell, ``auto-expire'' means that Gnus hits @kbd{E} -for you when you select an article. And ``total-expire'' means that Gnus -considers all articles as expirable that are read. So, in addition to -the articles marked @samp{E}, also the articles marked @samp{r}, -@samp{R}, @samp{O}, @samp{K}, @samp{Y} (and so on) are considered -expirable. @code{gnus-auto-expirable-marks} has the full list of -these marks. - -When should either auto-expire or total-expire be used? Most people -who are subscribed to mailing lists split each list into its own group -and then turn on auto-expire or total-expire for those groups. -(@xref{Splitting Mail}, for more information on splitting each list -into its own group.) - -Which one is better, auto-expire or total-expire? It's not easy to -answer. Generally speaking, auto-expire is probably faster. Another -advantage of auto-expire is that you get more marks to work with: for -the articles that are supposed to stick around, you can still choose -between tick and dormant and read marks. But with total-expire, you -only have dormant and ticked to choose from. The advantage of -total-expire is that it works well with adaptive scoring (@pxref{Adaptive -Scoring}). Auto-expire works with normal scoring but not with adaptive -scoring. - -@vindex gnus-auto-expirable-newsgroups -Groups that match the regular expression -@code{gnus-auto-expirable-newsgroups} will have all articles that you -read marked as expirable automatically. All articles marked as -expirable have an @samp{E} in the first column in the summary buffer. - -By default, if you have auto expiry switched on, Gnus will mark all the -articles you read as expirable, no matter if they were read or unread -before. To avoid having articles marked as read marked as expirable -automatically, you can put something like the following in your -@file{~/.gnus.el} file: - -@vindex gnus-mark-article-hook -@lisp -(remove-hook 'gnus-mark-article-hook - 'gnus-summary-mark-read-and-unread-as-read) -(add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read) -@end lisp - -Note that making a group auto-expirable doesn't mean that all read -articles are expired---only the articles marked as expirable -will be expired. Also note that using the @kbd{d} command won't make -articles expirable---only semi-automatic marking of articles as read will -mark the articles as expirable in auto-expirable groups. - -Let's say you subscribe to a couple of mailing lists, and you want the -articles you have read to disappear after a while: - -@lisp -(setq gnus-auto-expirable-newsgroups - "mail.nonsense-list\\|mail.nice-list") -@end lisp - -Another way to have auto-expiry happen is to have the element -@code{auto-expire} in the group parameters of the group. - -If you use adaptive scoring (@pxref{Adaptive Scoring}) and -auto-expiring, you'll have problems. Auto-expiring and adaptive scoring -don't really mix very well. - -@vindex nnmail-expiry-wait -The @code{nnmail-expiry-wait} variable supplies the default time an -expirable article has to live. Gnus starts counting days from when the -message @emph{arrived}, not from when it was sent. The default is seven -days. - -Gnus also supplies a function that lets you fine-tune how long articles -are to live, based on what group they are in. Let's say you want to -have one month expiry period in the @samp{mail.private} group, a one day -expiry period in the @samp{mail.junk} group, and a six day expiry period -everywhere else: - -@vindex nnmail-expiry-wait-function -@lisp -(setq nnmail-expiry-wait-function - (lambda (group) - (cond ((string= group "mail.private") - 31) - ((string= group "mail.junk") - 1) - ((string= group "important") - 'never) - (t - 6)))) -@end lisp - -The group names this function is fed are ``unadorned'' group -names---no @samp{nnml:} prefixes and the like. - -The @code{nnmail-expiry-wait} variable and -@code{nnmail-expiry-wait-function} function can either be a number (not -necessarily an integer) or one of the symbols @code{immediate} or -@code{never}. - -You can also use the @code{expiry-wait} group parameter to selectively -change the expiry period (@pxref{Group Parameters}). - -@vindex nnmail-expiry-target -The normal action taken when expiring articles is to delete them. -However, in some circumstances it might make more sense to move them -to other groups instead of deleting them. The variable -@code{nnmail-expiry-target} (and the @code{expiry-target} group -parameter) controls this. The variable supplies a default value for -all groups, which can be overridden for specific groups by the group -parameter. default value is @code{delete}, but this can also be a -string (which should be the name of the group the message should be -moved to), or a function (which will be called in a buffer narrowed to -the message in question, and with the name of the group being moved -from as its parameter) which should return a target---either a group -name or @code{delete}. - -Here's an example for specifying a group name: -@lisp -(setq nnmail-expiry-target "nnml:expired") -@end lisp - -@findex nnmail-fancy-expiry-target -@vindex nnmail-fancy-expiry-targets -Gnus provides a function @code{nnmail-fancy-expiry-target} which will -expire mail to groups according to the variable -@code{nnmail-fancy-expiry-targets}. Here's an example: - -@lisp - (setq nnmail-expiry-target 'nnmail-fancy-expiry-target - nnmail-fancy-expiry-targets - '((to-from "boss" "nnfolder:Work") - ("subject" "IMPORTANT" "nnfolder:IMPORTANT.%Y.%b") - ("from" ".*" "nnfolder:Archive-%Y"))) -@end lisp - -With this setup, any mail that has @code{IMPORTANT} in its Subject -header and was sent in the year @code{YYYY} and month @code{MMM}, will -get expired to the group @code{nnfolder:IMPORTANT.YYYY.MMM}. If its -From or To header contains the string @code{boss}, it will get expired -to @code{nnfolder:Work}. All other mail will get expired to -@code{nnfolder:Archive-YYYY}. - -@vindex nnmail-keep-last-article -If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never -expire the final article in a mail newsgroup. This is to make life -easier for procmail users. - -@vindex gnus-total-expirable-newsgroups -By the way: That line up there, about Gnus never expiring non-expirable -articles, is a lie. If you put @code{total-expire} in the group -parameters, articles will not be marked as expirable, but all read -articles will be put through the expiry process. Use with extreme -caution. Even more dangerous is the -@code{gnus-total-expirable-newsgroups} variable. All groups that match -this regexp will have all read articles put through the expiry process, -which means that @emph{all} old mail articles in the groups in question -will be deleted after a while. Use with extreme caution, and don't come -crying to me when you discover that the regexp you used matched the -wrong group and all your important mail has disappeared. Be a -@emph{man}! Or a @emph{woman}! Whatever you feel more comfortable -with! So there! - -Most people make most of their mail groups total-expirable, though. - -@vindex gnus-inhibit-user-auto-expire -If @code{gnus-inhibit-user-auto-expire} is non-@code{nil}, user marking -commands will not mark an article as expirable, even if the group has -auto-expire turned on. - -@vindex gnus-mark-copied-or-moved-articles-as-expirable -The expirable marks of articles will be removed when copying or moving -them to a group in which auto-expire is not turned on. This is for -preventing articles from being expired unintentionally. On the other -hand, to a group that has turned auto-expire on, the expirable marks of -articles that are copied or moved will not be changed by default. I.e., -when copying or moving to such a group, articles that were expirable -will be left expirable and ones that were not expirable will not be -marked as expirable. So, even though in auto-expire groups, some -articles will never get expired (unless you read them again). If you -don't side with that behavior that unexpirable articles may be mixed -into auto-expire groups, you can set -@code{gnus-mark-copied-or-moved-articles-as-expirable} to a -non-@code{nil} value. In that case, articles that have been read will -be marked as expirable automatically when being copied or moved to a -group that has auto-expire turned on. The default value is @code{nil}. - - -@node Washing Mail -@subsection Washing Mail -@cindex mail washing -@cindex list server brain damage -@cindex incoming mail treatment - -Mailers and list servers are notorious for doing all sorts of really, -really stupid things with mail. ``Hey, RFC 822 doesn't explicitly -prohibit us from adding the string @code{wE aRe ElItE!!!!!1!!} to the -end of all lines passing through our server, so let's do that!!!!1!'' -Yes, but RFC 822 wasn't designed to be read by morons. Things that were -considered to be self-evident were not discussed. So. Here we are. - -Case in point: The German version of Microsoft Exchange adds @samp{AW: -} to the subjects of replies instead of @samp{Re: }. I could pretend to -be shocked and dismayed by this, but I haven't got the energy. It is to -laugh. - -Gnus provides a plethora of functions for washing articles while -displaying them, but it might be nicer to do the filtering before -storing the mail to disk. For that purpose, we have three hooks and -various functions that can be put in these hooks. - -@table @code -@item nnmail-prepare-incoming-hook -@vindex nnmail-prepare-incoming-hook -This hook is called before doing anything with the mail and is meant for -grand, sweeping gestures. It is called in a buffer that contains all -the new, incoming mail. Functions to be used include: - -@table @code -@item nnheader-ms-strip-cr -@findex nnheader-ms-strip-cr -Remove trailing carriage returns from each line. This is default on -Emacs running on MS machines. - -@end table - -@item nnmail-prepare-incoming-header-hook -@vindex nnmail-prepare-incoming-header-hook -This hook is called narrowed to each header. It can be used when -cleaning up the headers. Functions that can be used include: - -@table @code -@item nnmail-remove-leading-whitespace -@findex nnmail-remove-leading-whitespace -Clear leading white space that ``helpful'' listservs have added to the -headers to make them look nice. Aaah. - -(Note that this function works on both the header on the body of all -messages, so it is a potentially dangerous function to use (if a body -of a message contains something that looks like a header line). So -rather than fix the bug, it is of course the right solution to make it -into a feature by documenting it.) - -@item nnmail-remove-list-identifiers -@findex nnmail-remove-list-identifiers -Some list servers add an identifier---for example, @samp{(idm)}---to the -beginning of all @code{Subject} headers. I'm sure that's nice for -people who use stone age mail readers. This function will remove -strings that match the @code{nnmail-list-identifiers} regexp, which can -also be a list of regexp. @code{nnmail-list-identifiers} may not contain -@code{\\(..\\)}. - -For instance, if you want to remove the @samp{(idm)} and the -@samp{nagnagnag} identifiers: - -@lisp -(setq nnmail-list-identifiers - '("(idm)" "nagnagnag")) -@end lisp - -This can also be done non-destructively with -@code{gnus-list-identifiers}, @xref{Article Hiding}. - -@item nnmail-remove-tabs -@findex nnmail-remove-tabs -Translate all @samp{TAB} characters into @samp{SPACE} characters. - -@item nnmail-ignore-broken-references -@findex nnmail-ignore-broken-references -@c @findex nnmail-fix-eudora-headers -@cindex Eudora -@cindex Pegasus -Some mail user agents (e.g. Eudora and Pegasus) produce broken -@code{References} headers, but correct @code{In-Reply-To} headers. This -function will get rid of the @code{References} header if the headers -contain a line matching the regular expression -@code{nnmail-broken-references-mailers}. - -@end table - -@item nnmail-prepare-incoming-message-hook -@vindex nnmail-prepare-incoming-message-hook -This hook is called narrowed to each message. Functions to be used -include: - -@table @code -@item article-de-quoted-unreadable -@findex article-de-quoted-unreadable -Decode Quoted Readable encoding. - -@end table -@end table - - -@node Duplicates -@subsection Duplicates - -@vindex nnmail-treat-duplicates -@vindex nnmail-message-id-cache-length -@vindex nnmail-message-id-cache-file -@cindex duplicate mails -If you are a member of a couple of mailing lists, you will sometimes -receive two copies of the same mail. This can be quite annoying, so -@code{nnmail} checks for and treats any duplicates it might find. To do -this, it keeps a cache of old @code{Message-ID}s--- -@code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by -default. The approximate maximum number of @code{Message-ID}s stored -there is controlled by the @code{nnmail-message-id-cache-length} -variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be -stored.) If all this sounds scary to you, you can set -@code{nnmail-treat-duplicates} to @code{warn} (which is what it is by -default), and @code{nnmail} won't delete duplicate mails. Instead it -will insert a warning into the head of the mail saying that it thinks -that this is a duplicate of a different message. - -This variable can also be a function. If that's the case, the function -will be called from a buffer narrowed to the message in question with -the @code{Message-ID} as a parameter. The function must return either -@code{nil}, @code{warn}, or @code{delete}. - -You can turn this feature off completely by setting the variable to -@code{nil}. - -If you want all the duplicate mails to be put into a special -@dfn{duplicates} group, you could do that using the normal mail split -methods: - -@lisp -(setq nnmail-split-fancy - '(| ;; @r{Messages duplicates go to a separate group.} - ("gnus-warning" "duplicat\\(e\\|ion\\) of message" "duplicate") - ;; @r{Message from daemons, postmaster, and the like to another.} - (any mail "mail.misc") - ;; @r{Other rules.} - [...] )) -@end lisp -@noindent -Or something like: -@lisp -(setq nnmail-split-methods - '(("duplicates" "^Gnus-Warning:.*duplicate") - ;; @r{Other rules.} - [...])) -@end lisp - -Here's a neat feature: If you know that the recipient reads her mail -with Gnus, and that she has @code{nnmail-treat-duplicates} set to -@code{delete}, you can send her as many insults as you like, just by -using a @code{Message-ID} of a mail that you know that she's already -received. Think of all the fun! She'll never see any of it! Whee! - - -@node Not Reading Mail -@subsection Not Reading Mail - -If you start using any of the mail back ends, they have the annoying -habit of assuming that you want to read mail with them. This might not -be unreasonable, but it might not be what you want. - -If you set @code{mail-sources} and @code{nnmail-spool-file} to -@code{nil}, none of the back ends will ever attempt to read incoming -mail, which should help. - -@vindex nnbabyl-get-new-mail -@vindex nnmbox-get-new-mail -@vindex nnml-get-new-mail -@vindex nnmh-get-new-mail -@vindex nnfolder-get-new-mail -This might be too much, if, for instance, you are reading mail quite -happily with @code{nnml} and just want to peek at some old (pre-Emacs -23) Rmail file you have stashed away with @code{nnbabyl}. All back ends have -variables called back-end-@code{get-new-mail}. If you want to disable -the @code{nnbabyl} mail reading, you edit the virtual server for the -group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}. - -All the mail back ends will call @code{nn}*@code{-prepare-save-mail-hook} -narrowed to the article to be saved before saving it when reading -incoming mail. - - -@node Choosing a Mail Back End -@subsection Choosing a Mail Back End - -Gnus will read the mail spool when you activate a mail group. The mail -file is first copied to your home directory. What happens after that -depends on what format you want to store your mail in. - -There are six different mail back ends in the standard Gnus, and more -back ends are available separately. The mail back end most people use -(because it is possibly the fastest) is @code{nnml} (@pxref{Mail -Spool}). - -@menu -* Unix Mail Box:: Using the (quite) standard Un*x mbox. -* Babyl:: Babyl was used by older versions of Rmail. -* Mail Spool:: Store your mail in a private spool? -* MH Spool:: An mhspool-like back end. -* Maildir:: Another one-file-per-message format. -* Mail Folders:: Having one file for each group. -* Comparing Mail Back Ends:: An in-depth looks at pros and cons. -@end menu - - - -@node Unix Mail Box -@subsubsection Unix Mail Box -@cindex nnmbox -@cindex unix mail box - -@vindex nnmbox-active-file -@vindex nnmbox-mbox-file -The @dfn{nnmbox} back end will use the standard Un*x mbox file to store -mail. @code{nnmbox} will add extra headers to each mail article to say -which group it belongs in. - -Virtual server settings: - -@table @code -@item nnmbox-mbox-file -@vindex nnmbox-mbox-file -The name of the mail box in the user's home directory. Default is -@file{~/mbox}. - -@item nnmbox-active-file -@vindex nnmbox-active-file -The name of the active file for the mail box. Default is -@file{~/.mbox-active}. - -@item nnmbox-get-new-mail -@vindex nnmbox-get-new-mail -If non-@code{nil}, @code{nnmbox} will read incoming mail and split it -into groups. Default is @code{t}. -@end table - - -@node Babyl -@subsubsection Babyl -@cindex nnbabyl - -@vindex nnbabyl-active-file -@vindex nnbabyl-mbox-file -The @dfn{nnbabyl} back end will use a Babyl mail box to store mail. -@code{nnbabyl} will add extra headers to each mail article to say which -group it belongs in. - -Virtual server settings: - -@table @code -@item nnbabyl-mbox-file -@vindex nnbabyl-mbox-file -The name of the Babyl file. The default is @file{~/RMAIL} - -@item nnbabyl-active-file -@vindex nnbabyl-active-file -The name of the active file for the Babyl file. The default is -@file{~/.rmail-active} - -@item nnbabyl-get-new-mail -@vindex nnbabyl-get-new-mail -If non-@code{nil}, @code{nnbabyl} will read incoming mail. Default is -@code{t} -@end table - - -@node Mail Spool -@subsubsection Mail Spool -@cindex nnml -@cindex mail @acronym{NOV} spool - -The @dfn{nnml} spool mail format isn't compatible with any other known -format. It should be used with some caution. - -@vindex nnml-directory -If you use this back end, Gnus will split all incoming mail into files, -one file for each mail, and put the articles into the corresponding -directories under the directory specified by the @code{nnml-directory} -variable. The default value is @file{~/Mail/}. - -You do not have to create any directories beforehand; Gnus will take -care of all that. - -If you have a strict limit as to how many files you are allowed to store -in your account, you should not use this back end. As each mail gets its -own file, you might very well occupy thousands of inodes within a few -weeks. If this is no problem for you, and it isn't a problem for you -having your friendly systems administrator walking around, madly, -shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should -know that this is probably the fastest format to use. You do not have -to trudge through a big mbox file just to read your new mail. - -@code{nnml} is probably the slowest back end when it comes to article -splitting. It has to create lots of files, and it also generates -@acronym{NOV} databases for the incoming mails. This makes it possibly the -fastest back end when it comes to reading mail. - -@cindex self contained nnml servers -@cindex marks -When the marks file is used (which it is by default), @code{nnml} -servers have the property that you may backup them using @code{tar} or -similar, and later be able to restore them into Gnus (by adding the -proper @code{nnml} server) and have all your marks be preserved. Marks -for a group are usually stored in the @code{.marks} file (but see -@code{nnml-marks-file-name}) within each @code{nnml} group's directory. -Individual @code{nnml} groups are also possible to backup, use @kbd{G m} -to restore the group (after restoring the backup into the nnml -directory). - -If for some reason you believe your @file{.marks} files are screwed -up, you can just delete them all. Gnus will then correctly regenerate -them next time it starts. - -Virtual server settings: - -@table @code -@item nnml-directory -@vindex nnml-directory -All @code{nnml} directories will be placed under this directory. The -default is the value of @code{message-directory} (whose default value -is @file{~/Mail}). - -@item nnml-active-file -@vindex nnml-active-file -The active file for the @code{nnml} server. The default is -@file{~/Mail/active}. - -@item nnml-newsgroups-file -@vindex nnml-newsgroups-file -The @code{nnml} group descriptions file. @xref{Newsgroups File -Format}. The default is @file{~/Mail/newsgroups}. - -@item nnml-get-new-mail -@vindex nnml-get-new-mail -If non-@code{nil}, @code{nnml} will read incoming mail. The default is -@code{t}. - -@item nnml-nov-is-evil -@vindex nnml-nov-is-evil -If non-@code{nil}, this back end will ignore any @acronym{NOV} files. The -default is @code{nil}. - -@item nnml-nov-file-name -@vindex nnml-nov-file-name -The name of the @acronym{NOV} files. The default is @file{.overview}. - -@item nnml-prepare-save-mail-hook -@vindex nnml-prepare-save-mail-hook -Hook run narrowed to an article before saving. - -@item nnml-marks-is-evil -@vindex nnml-marks-is-evil -If non-@code{nil}, this back end will ignore any @sc{marks} files. The -default is @code{nil}. - -@item nnml-marks-file-name -@vindex nnml-marks-file-name -The name of the @dfn{marks} files. The default is @file{.marks}. - -@item nnml-use-compressed-files -@vindex nnml-use-compressed-files -If non-@code{nil}, @code{nnml} will allow using compressed message -files. This requires @code{auto-compression-mode} to be enabled -(@pxref{Compressed Files, ,Compressed Files, emacs, The Emacs Manual}). -If the value of @code{nnml-use-compressed-files} is a string, it is used -as the file extension specifying the compression program. You can set it -to @samp{.bz2} if your Emacs supports it. A value of @code{t} is -equivalent to @samp{.gz}. - -@item nnml-compressed-files-size-threshold -@vindex nnml-compressed-files-size-threshold -Default size threshold for compressed message files. Message files with -bodies larger than that many characters will be automatically compressed -if @code{nnml-use-compressed-files} is non-@code{nil}. - -@end table - -@findex nnml-generate-nov-databases -If your @code{nnml} groups and @acronym{NOV} files get totally out of -whack, you can do a complete update by typing @kbd{M-x -nnml-generate-nov-databases}. This command will trawl through the -entire @code{nnml} hierarchy, looking at each and every article, so it -might take a while to complete. A better interface to this -functionality can be found in the server buffer (@pxref{Server -Commands}). - - -@node MH Spool -@subsubsection MH Spool -@cindex nnmh -@cindex mh-e mail spool - -@code{nnmh} is just like @code{nnml}, except that is doesn't generate -@acronym{NOV} databases and it doesn't keep an active file or marks -file. This makes @code{nnmh} a @emph{much} slower back end than -@code{nnml}, but it also makes it easier to write procmail scripts -for. - -Virtual server settings: - -@table @code -@item nnmh-directory -@vindex nnmh-directory -All @code{nnmh} directories will be located under this directory. The -default is the value of @code{message-directory} (whose default is -@file{~/Mail}) - -@item nnmh-get-new-mail -@vindex nnmh-get-new-mail -If non-@code{nil}, @code{nnmh} will read incoming mail. The default is -@code{t}. - -@item nnmh-be-safe -@vindex nnmh-be-safe -If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make -sure that the articles in the folder are actually what Gnus thinks -they are. It will check date stamps and stat everything in sight, so -setting this to @code{t} will mean a serious slow-down. If you never -use anything but Gnus to read the @code{nnmh} articles, you do not -have to set this variable to @code{t}. The default is @code{nil}. -@end table - - -@node Maildir -@subsubsection Maildir -@cindex nnmaildir -@cindex maildir - -@code{nnmaildir} stores mail in the maildir format, with each maildir -corresponding to a group in Gnus. This format is documented here: -@uref{http://cr.yp.to/proto/maildir.html} and here: -@uref{http://www.qmail.org/man/man5/maildir.html}. @code{nnmaildir} -also stores extra information in the @file{.nnmaildir/} directory -within a maildir. - -Maildir format was designed to allow concurrent deliveries and -reading, without needing locks. With other back ends, you would have -your mail delivered to a spool of some kind, and then you would -configure Gnus to split mail from that spool into your groups. You -can still do that with @code{nnmaildir}, but the more common -configuration is to have your mail delivered directly to the maildirs -that appear as group in Gnus. - -@code{nnmaildir} is designed to be perfectly reliable: @kbd{C-g} will -never corrupt its data in memory, and @code{SIGKILL} will never -corrupt its data in the filesystem. - -@code{nnmaildir} stores article marks and @acronym{NOV} data in each -maildir. So you can copy a whole maildir from one Gnus setup to -another, and you will keep your marks. - -Virtual server settings: - -@table @code -@item directory -For each of your @code{nnmaildir} servers (it's very unlikely that -you'd need more than one), you need to create a directory and populate -it with maildirs or symlinks to maildirs (and nothing else; do not -choose a directory already used for other purposes). Each maildir -will be represented in Gnus as a newsgroup on that server; the -filename of the symlink will be the name of the group. Any filenames -in the directory starting with @samp{.} are ignored. The directory is -scanned when you first start Gnus, and each time you type @kbd{g} in -the group buffer; if any maildirs have been removed or added, -@code{nnmaildir} notices at these times. - -The value of the @code{directory} parameter should be a Lisp form -which is processed by @code{eval} and @code{expand-file-name} to get -the path of the directory for this server. The form is @code{eval}ed -only when the server is opened; the resulting string is used until the -server is closed. (If you don't know about forms and @code{eval}, -don't worry---a simple string will work.) This parameter is not -optional; you must specify it. I don't recommend using -@code{"~/Mail"} or a subdirectory of it; several other parts of Gnus -use that directory by default for various things, and may get confused -if @code{nnmaildir} uses it too. @code{"~/.nnmaildir"} is a typical -value. - -@item target-prefix -This should be a Lisp form which is processed by @code{eval} and -@code{expand-file-name}. The form is @code{eval}ed only when the -server is opened; the resulting string is used until the server is -closed. - -When you create a group on an @code{nnmaildir} server, the maildir is -created with @code{target-prefix} prepended to its name, and a symlink -pointing to that maildir is created, named with the plain group name. -So if @code{directory} is @code{"~/.nnmaildir"} and -@code{target-prefix} is @code{"../maildirs/"}, then when you create -the group @code{foo}, @code{nnmaildir} will create -@file{~/.nnmaildir/../maildirs/foo} as a maildir, and will create -@file{~/.nnmaildir/foo} as a symlink pointing to -@file{../maildirs/foo}. - -You can set @code{target-prefix} to a string without any slashes to -create both maildirs and symlinks in the same @code{directory}; in -this case, any maildirs found in @code{directory} whose names start -with @code{target-prefix} will not be listed as groups (but the -symlinks pointing to them will be). - -As a special case, if @code{target-prefix} is @code{""} (the default), -then when you create a group, the maildir will be created in -@code{directory} without a corresponding symlink. Beware that you -cannot use @code{gnus-group-delete-group} on such groups without the -@code{force} argument. - -@item directory-files -This should be a function with the same interface as -@code{directory-files} (such as @code{directory-files} itself). It is -used to scan the server's @code{directory} for maildirs. This -parameter is optional; the default is -@code{nnheader-directory-files-safe} if -@code{nnheader-directory-files-is-safe} is @code{nil}, and -@code{directory-files} otherwise. -(@code{nnheader-directory-files-is-safe} is checked only once when the -server is opened; if you want to check it each time the directory is -scanned, you'll have to provide your own function that does that.) - -@item get-new-mail -If non-@code{nil}, then after scanning for new mail in the group -maildirs themselves as usual, this server will also incorporate mail -the conventional Gnus way, from @code{mail-sources} according to -@code{nnmail-split-methods} or @code{nnmail-split-fancy}. The default -value is @code{nil}. - -Do @emph{not} use the same maildir both in @code{mail-sources} and as -an @code{nnmaildir} group. The results might happen to be useful, but -that would be by chance, not by design, and the results might be -different in the future. If your split rules create new groups, -remember to supply a @code{create-directory} server parameter. -@end table - -@subsubsection Group parameters - -@code{nnmaildir} uses several group parameters. It's safe to ignore -all this; the default behavior for @code{nnmaildir} is the same as the -default behavior for other mail back ends: articles are deleted after -one week, etc. Except for the expiry parameters, all this -functionality is unique to @code{nnmaildir}, so you can ignore it if -you're just trying to duplicate the behavior you already have with -another back end. - -If the value of any of these parameters is a vector, the first element -is evaluated as a Lisp form and the result is used, rather than the -original value. If the value is not a vector, the value itself is -evaluated as a Lisp form. (This is why these parameters use names -different from those of other, similar parameters supported by other -back ends: they have different, though similar, meanings.) (For -numbers, strings, @code{nil}, and @code{t}, you can ignore the -@code{eval} business again; for other values, remember to use an extra -quote and wrap the value in a vector when appropriate.) - -@table @code -@item expire-age -An integer specifying the minimum age, in seconds, of an article -before it will be expired, or the symbol @code{never} to specify that -articles should never be expired. If this parameter is not set, -@code{nnmaildir} falls back to the usual -@code{nnmail-expiry-wait}(@code{-function}) variables (the -@code{expiry-wait} group parameter overrides @code{nnmail-expiry-wait} -and makes @code{nnmail-expiry-wait-function} ineffective). If you -wanted a value of 3 days, you could use something like @code{[(* 3 24 -60 60)]}; @code{nnmaildir} will evaluate the form and use the result. -An article's age is measured starting from the article file's -modification time. Normally, this is the same as the article's -delivery time, but editing an article makes it younger. Moving an -article (other than via expiry) may also make an article younger. - -@item expire-group -If this is set to a string such as a full Gnus group name, like -@example -"backend+server.address.string:group.name" -@end example -and if it is not the name of the same group that the parameter belongs -to, then articles will be moved to the specified group during expiry -before being deleted. @emph{If this is set to an @code{nnmaildir} -group, the article will be just as old in the destination group as it -was in the source group.} So be careful with @code{expire-age} in the -destination group. If this is set to the name of the same group that -the parameter belongs to, then the article is not expired at all. If -you use the vector form, the first element is evaluated once for each -article. So that form can refer to -@code{nnmaildir-article-file-name}, etc., to decide where to put the -article. @emph{Even if this parameter is not set, @code{nnmaildir} -does not fall back to the @code{expiry-target} group parameter or the -@code{nnmail-expiry-target} variable.} - -@item read-only -If this is set to @code{t}, @code{nnmaildir} will treat the articles -in this maildir as read-only. This means: articles are not renamed -from @file{new/} into @file{cur/}; articles are only found in -@file{new/}, not @file{cur/}; articles are never deleted; articles -cannot be edited. @file{new/} is expected to be a symlink to the -@file{new/} directory of another maildir---e.g., a system-wide mailbox -containing a mailing list of common interest. Everything in the -maildir outside @file{new/} is @emph{not} treated as read-only, so for -a shared mailbox, you do still need to set up your own maildir (or -have write permission to the shared mailbox); your maildir just won't -contain extra copies of the articles. - -@item directory-files -A function with the same interface as @code{directory-files}. It is -used to scan the directories in the maildir corresponding to this -group to find articles. The default is the function specified by the -server's @code{directory-files} parameter. - -@item distrust-Lines: -If non-@code{nil}, @code{nnmaildir} will always count the lines of an -article, rather than use the @code{Lines:} header field. If -@code{nil}, the header field will be used if present. - -@item always-marks -A list of mark symbols, such as @code{['(read expire)]}. Whenever -Gnus asks @code{nnmaildir} for article marks, @code{nnmaildir} will -say that all articles have these marks, regardless of whether the -marks stored in the filesystem say so. This is a proof-of-concept -feature that will probably be removed eventually; it ought to be done -in Gnus proper, or abandoned if it's not worthwhile. - -@item never-marks -A list of mark symbols, such as @code{['(tick expire)]}. Whenever -Gnus asks @code{nnmaildir} for article marks, @code{nnmaildir} will -say that no articles have these marks, regardless of whether the marks -stored in the filesystem say so. @code{never-marks} overrides -@code{always-marks}. This is a proof-of-concept feature that will -probably be removed eventually; it ought to be done in Gnus proper, or -abandoned if it's not worthwhile. - -@item nov-cache-size -An integer specifying the size of the @acronym{NOV} memory cache. To -speed things up, @code{nnmaildir} keeps @acronym{NOV} data in memory -for a limited number of articles in each group. (This is probably not -worthwhile, and will probably be removed in the future.) This -parameter's value is noticed only the first time a group is seen after -the server is opened---i.e., when you first start Gnus, typically. -The @acronym{NOV} cache is never resized until the server is closed -and reopened. The default is an estimate of the number of articles -that would be displayed in the summary buffer: a count of articles -that are either marked with @code{tick} or not marked with -@code{read}, plus a little extra. -@end table - -@subsubsection Article identification -Articles are stored in the @file{cur/} subdirectory of each maildir. -Each article file is named like @code{uniq:info}, where @code{uniq} -contains no colons. @code{nnmaildir} ignores, but preserves, the -@code{:info} part. (Other maildir readers typically use this part of -the filename to store marks.) The @code{uniq} part uniquely -identifies the article, and is used in various places in the -@file{.nnmaildir/} subdirectory of the maildir to store information -about the corresponding article. The full pathname of an article is -available in the variable @code{nnmaildir-article-file-name} after you -request the article in the summary buffer. - -@subsubsection NOV data -An article identified by @code{uniq} has its @acronym{NOV} data (used -to generate lines in the summary buffer) stored in -@code{.nnmaildir/nov/uniq}. There is no -@code{nnmaildir-generate-nov-databases} function. (There isn't much -need for it---an article's @acronym{NOV} data is updated automatically -when the article or @code{nnmail-extra-headers} has changed.) You can -force @code{nnmaildir} to regenerate the @acronym{NOV} data for a -single article simply by deleting the corresponding @acronym{NOV} -file, but @emph{beware}: this will also cause @code{nnmaildir} to -assign a new article number for this article, which may cause trouble -with @code{seen} marks, the Agent, and the cache. - -@subsubsection Article marks -An article identified by @code{uniq} is considered to have the mark -@code{flag} when the file @file{.nnmaildir/marks/flag/uniq} exists. -When Gnus asks @code{nnmaildir} for a group's marks, @code{nnmaildir} -looks for such files and reports the set of marks it finds. When Gnus -asks @code{nnmaildir} to store a new set of marks, @code{nnmaildir} -creates and deletes the corresponding files as needed. (Actually, -rather than create a new file for each mark, it just creates hard -links to @file{.nnmaildir/markfile}, to save inodes.) - -You can invent new marks by creating a new directory in -@file{.nnmaildir/marks/}. You can tar up a maildir and remove it from -your server, untar it later, and keep your marks. You can add and -remove marks yourself by creating and deleting mark files. If you do -this while Gnus is running and your @code{nnmaildir} server is open, -it's best to exit all summary buffers for @code{nnmaildir} groups and -type @kbd{s} in the group buffer first, and to type @kbd{g} or -@kbd{M-g} in the group buffer afterwards. Otherwise, Gnus might not -pick up the changes, and might undo them. - - -@node Mail Folders -@subsubsection Mail Folders -@cindex nnfolder -@cindex mbox folders -@cindex mail folders - -@code{nnfolder} is a back end for storing each mail group in a -separate file. Each file is in the standard Un*x mbox format. -@code{nnfolder} will add extra headers to keep track of article -numbers and arrival dates. - -@cindex self contained nnfolder servers -@cindex marks -When the marks file is used (which it is by default), @code{nnfolder} -servers have the property that you may backup them using @code{tar} or -similar, and later be able to restore them into Gnus (by adding the -proper @code{nnfolder} server) and have all your marks be preserved. -Marks for a group are usually stored in a file named as the mbox file -with @code{.mrk} concatenated to it (but see -@code{nnfolder-marks-file-suffix}) within the @code{nnfolder} -directory. Individual @code{nnfolder} groups are also possible to -backup, use @kbd{G m} to restore the group (after restoring the backup -into the @code{nnfolder} directory). - -Virtual server settings: - -@table @code -@item nnfolder-directory -@vindex nnfolder-directory -All the @code{nnfolder} mail boxes will be stored under this -directory. The default is the value of @code{message-directory} -(whose default is @file{~/Mail}) - -@item nnfolder-active-file -@vindex nnfolder-active-file -The name of the active file. The default is @file{~/Mail/active}. - -@item nnfolder-newsgroups-file -@vindex nnfolder-newsgroups-file -The name of the group descriptions file. @xref{Newsgroups File -Format}. The default is @file{~/Mail/newsgroups} - -@item nnfolder-get-new-mail -@vindex nnfolder-get-new-mail -If non-@code{nil}, @code{nnfolder} will read incoming mail. The -default is @code{t} - -@item nnfolder-save-buffer-hook -@vindex nnfolder-save-buffer-hook -@cindex backup files -Hook run before saving the folders. Note that Emacs does the normal -backup renaming of files even with the @code{nnfolder} buffers. If -you wish to switch this off, you could say something like the -following in your @file{.emacs} file: - -@lisp -(defun turn-off-backup () - (set (make-local-variable 'backup-inhibited) t)) - -(add-hook 'nnfolder-save-buffer-hook 'turn-off-backup) -@end lisp - -@item nnfolder-delete-mail-hook -@vindex nnfolder-delete-mail-hook -Hook run in a buffer narrowed to the message that is to be deleted. -This function can be used to copy the message to somewhere else, or to -extract some information from it before removing it. - -@item nnfolder-nov-is-evil -@vindex nnfolder-nov-is-evil -If non-@code{nil}, this back end will ignore any @acronym{NOV} files. The -default is @code{nil}. - -@item nnfolder-nov-file-suffix -@vindex nnfolder-nov-file-suffix -The extension for @acronym{NOV} files. The default is @file{.nov}. - -@item nnfolder-nov-directory -@vindex nnfolder-nov-directory -The directory where the @acronym{NOV} files should be stored. If -@code{nil}, @code{nnfolder-directory} is used. - -@item nnfolder-marks-is-evil -@vindex nnfolder-marks-is-evil -If non-@code{nil}, this back end will ignore any @sc{marks} files. The -default is @code{nil}. - -@item nnfolder-marks-file-suffix -@vindex nnfolder-marks-file-suffix -The extension for @sc{marks} files. The default is @file{.mrk}. - -@item nnfolder-marks-directory -@vindex nnfolder-marks-directory -The directory where the @sc{marks} files should be stored. If -@code{nil}, @code{nnfolder-directory} is used. - -@end table - - -@findex nnfolder-generate-active-file -@kindex M-x nnfolder-generate-active-file -If you have lots of @code{nnfolder}-like files you'd like to read with -@code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file} -command to make @code{nnfolder} aware of all likely files in -@code{nnfolder-directory}. This only works if you use long file names, -though. - -@node Comparing Mail Back Ends -@subsubsection Comparing Mail Back Ends - -First, just for terminology, the @dfn{back end} is the common word for a -low-level access method---a transport, if you will, by which something -is acquired. The sense is that one's mail has to come from somewhere, -and so selection of a suitable back end is required in order to get that -mail within spitting distance of Gnus. - -The same concept exists for Usenet itself: Though access to articles is -typically done by @acronym{NNTP} these days, once upon a midnight dreary, everyone -in the world got at Usenet by running a reader on the machine where the -articles lay (the machine which today we call an @acronym{NNTP} server), and -access was by the reader stepping into the articles' directory spool -area directly. One can still select between either the @code{nntp} or -@code{nnspool} back ends, to select between these methods, if one happens -actually to live on the server (or can see its spool directly, anyway, -via NFS). - -The goal in selecting a mail back end is to pick one which -simultaneously represents a suitable way of dealing with the original -format plus leaving mail in a form that is convenient to use in the -future. Here are some high and low points on each: - -@table @code -@item nnmbox - -UNIX systems have historically had a single, very common, and well- -defined format. All messages arrive in a single @dfn{spool file}, and -they are delineated by a line whose regular expression matches -@samp{^From_}. (My notational use of @samp{_} is to indicate a space, -to make it clear in this instance that this is not the RFC-specified -@samp{From:} header.) Because Emacs and therefore Gnus emanate -historically from the Unix environment, it is simplest if one does not -mess a great deal with the original mailbox format, so if one chooses -this back end, Gnus' primary activity in getting mail from the real spool -area to Gnus' preferred directory is simply to copy it, with no -(appreciable) format change in the process. It is the ``dumbest'' way -to move mail into availability in the Gnus environment. This makes it -fast to move into place, but slow to parse, when Gnus has to look at -what's where. - -@item nnbabyl - -Once upon a time, there was the DEC-10 and DEC-20, running operating -systems called TOPS and related things, and the usual (only?) mail -reading environment was a thing called Babyl. I don't know what format -was used for mail landing on the system, but Babyl had its own internal -format to which mail was converted, primarily involving creating a -spool-file-like entity with a scheme for inserting Babyl-specific -headers and status bits above the top of each message in the file. -Rmail was Emacs's first mail reader, it was written by Richard Stallman, -and Stallman came out of that TOPS/Babyl environment, so he wrote Rmail -to understand the mail files folks already had in existence. Gnus (and -VM, for that matter) continue to support this format because it's -perceived as having some good qualities in those mailer-specific -headers/status bits stuff. Rmail itself still exists as well, of -course, and is still maintained within Emacs. Since Emacs 23, it -uses standard mbox format rather than Babyl. - -Both of the above forms leave your mail in a single file on your -file system, and they must parse that entire file each time you take a -look at your mail. - -@item nnml - -@code{nnml} is the back end which smells the most as though you were -actually operating with an @code{nnspool}-accessed Usenet system. (In -fact, I believe @code{nnml} actually derived from @code{nnspool} code, -lo these years ago.) One's mail is taken from the original spool file, -and is then cut up into individual message files, 1:1. It maintains a -Usenet-style active file (analogous to what one finds in an INN- or -CNews-based news system in (for instance) @file{/var/lib/news/active}, -or what is returned via the @samp{NNTP LIST} verb) and also creates -@dfn{overview} files for efficient group entry, as has been defined for -@acronym{NNTP} servers for some years now. It is slower in mail-splitting, -due to the creation of lots of files, updates to the @code{nnml} active -file, and additions to overview files on a per-message basis, but it is -extremely fast on access because of what amounts to the indexing support -provided by the active file and overviews. - -@code{nnml} costs @dfn{inodes} in a big way; that is, it soaks up the -resource which defines available places in the file system to put new -files. Sysadmins take a dim view of heavy inode occupation within -tight, shared file systems. But if you live on a personal machine where -the file system is your own and space is not at a premium, @code{nnml} -wins big. - -It is also problematic using this back end if you are living in a -FAT16-based Windows world, since much space will be wasted on all these -tiny files. - -@item nnmh - -The Rand MH mail-reading system has been around UNIX systems for a very -long time; it operates by splitting one's spool file of messages into -individual files, but with little or no indexing support---@code{nnmh} -is considered to be semantically equivalent to ``@code{nnml} without -active file or overviews''. This is arguably the worst choice, because -one gets the slowness of individual file creation married to the -slowness of access parsing when learning what's new in one's groups. - -@item nnfolder - -Basically the effect of @code{nnfolder} is @code{nnmbox} (the first -method described above) on a per-group basis. That is, @code{nnmbox} -itself puts @emph{all} one's mail in one file; @code{nnfolder} provides a -little bit of optimization to this so that each of one's mail groups has -a Unix mail box file. It's faster than @code{nnmbox} because each group -can be parsed separately, and still provides the simple Unix mail box -format requiring minimal effort in moving the mail around. In addition, -it maintains an ``active'' file making it much faster for Gnus to figure -out how many messages there are in each separate group. - -If you have groups that are expected to have a massive amount of -messages, @code{nnfolder} is not the best choice, but if you receive -only a moderate amount of mail, @code{nnfolder} is probably the most -friendly mail back end all over. - -@item nnmaildir - -For configuring expiry and other things, @code{nnmaildir} uses -incompatible group parameters, slightly different from those of other -mail back ends. - -@code{nnmaildir} is largely similar to @code{nnml}, with some notable -differences. Each message is stored in a separate file, but the -filename is unrelated to the article number in Gnus. @code{nnmaildir} -also stores the equivalent of @code{nnml}'s overview files in one file -per article, so it uses about twice as many inodes as @code{nnml}. -(Use @code{df -i} to see how plentiful your inode supply is.) If this -slows you down or takes up very much space, a non-block-structured -file system. - -Since maildirs don't require locking for delivery, the maildirs you use -as groups can also be the maildirs your mail is directly delivered to. -This means you can skip Gnus' mail splitting if your mail is already -organized into different mailboxes during delivery. A @code{directory} -entry in @code{mail-sources} would have a similar effect, but would -require one set of mailboxes for spooling deliveries (in mbox format, -thus damaging message bodies), and another set to be used as groups (in -whatever format you like). A maildir has a built-in spool, in the -@code{new/} subdirectory. Beware that currently, mail moved from -@code{new/} to @code{cur/} instead of via mail splitting will not -undergo treatment such as duplicate checking. - -@code{nnmaildir} stores article marks for a given group in the -corresponding maildir, in a way designed so that it's easy to manipulate -them from outside Gnus. You can tar up a maildir, unpack it somewhere -else, and still have your marks. @code{nnml} also stores marks, but -it's not as easy to work with them from outside Gnus as with -@code{nnmaildir}. - -@code{nnmaildir} uses a significant amount of memory to speed things up. -(It keeps in memory some of the things that @code{nnml} stores in files -and that @code{nnmh} repeatedly parses out of message files.) If this -is a problem for you, you can set the @code{nov-cache-size} group -parameter to something small (0 would probably not work, but 1 probably -would) to make it use less memory. This caching will probably be -removed in the future. - -Startup is likely to be slower with @code{nnmaildir} than with other -back ends. Everything else is likely to be faster, depending in part -on your file system. - -@code{nnmaildir} does not use @code{nnoo}, so you cannot use @code{nnoo} -to write an @code{nnmaildir}-derived back end. - -@end table - - -@node Browsing the Web -@section Browsing the Web -@cindex web -@cindex browsing the web -@cindex www -@cindex http - -Web-based discussion forums are getting more and more popular. On many -subjects, the web-based forums have become the most important forums, -eclipsing the importance of mailing lists and news groups. The reason -is easy to understand---they are friendly to new users; you just point -and click, and there's the discussion. With mailing lists, you have to -go through a cumbersome subscription procedure, and most people don't -even know what a news group is. - -The problem with this scenario is that web browsers are not very good at -being newsreaders. They do not keep track of what articles you've read; -they do not allow you to score on subjects you're interested in; they do -not allow off-line browsing; they require you to click around and drive -you mad in the end. - -So---if web browsers suck at reading discussion forums, why not use Gnus -to do it instead? - -Gnus has been getting a bit of a collection of back ends for providing -interfaces to these sources. - -@menu -* Archiving Mail:: -* Web Searches:: Creating groups from articles that match a string. -* RSS:: Reading RDF site summary. -* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. -@end menu - -All the web sources require Emacs/W3 and the url library or those -alternatives to work. - -The main caveat with all these web sources is that they probably won't -work for a very long time. Gleaning information from the @acronym{HTML} data -is guesswork at best, and when the layout is altered, the Gnus back end -will fail. If you have reasonably new versions of these back ends, -though, you should be ok. - -One thing all these Web methods have in common is that the Web sources -are often down, unavailable or just plain too slow to be fun. In those -cases, it makes a lot of sense to let the Gnus Agent (@pxref{Gnus -Unplugged}) handle downloading articles, and then you can read them at -leisure from your local disk. No more World Wide Wait for you. - -@node Archiving Mail -@subsection Archiving Mail -@cindex archiving mail -@cindex backup of mail - -Some of the back ends, notably @code{nnml}, @code{nnfolder}, and -@code{nnmaildir}, now actually store the article marks with each group. -For these servers, archiving and restoring a group while preserving -marks is fairly simple. - -(Preserving the group level and group parameters as well still -requires ritual dancing and sacrifices to the @file{.newsrc.eld} deity -though.) - -To archive an entire @code{nnml}, @code{nnfolder}, or @code{nnmaildir} -server, take a recursive copy of the server directory. There is no need -to shut down Gnus, so archiving may be invoked by @code{cron} or -similar. You restore the data by restoring the directory tree, and -adding a server definition pointing to that directory in Gnus. The -@ref{Article Backlog}, @ref{Asynchronous Fetching} and other things -might interfere with overwriting data, so you may want to shut down Gnus -before you restore the data. - -It is also possible to archive individual @code{nnml}, -@code{nnfolder}, or @code{nnmaildir} groups, while preserving marks. -For @code{nnml} or @code{nnmaildir}, you copy all files in the group's -directory. For @code{nnfolder} you need to copy both the base folder -file itself (@file{FOO}, say), and the marks file (@file{FOO.mrk} in -this example). Restoring the group is done with @kbd{G m} from the Group -buffer. The last step makes Gnus notice the new directory. -@code{nnmaildir} notices the new directory automatically, so @kbd{G m} -is unnecessary in that case. - -@node Web Searches -@subsection Web Searches -@cindex nnweb -@cindex Google -@cindex dejanews -@cindex gmane -@cindex Usenet searches -@cindex searching the Usenet - -It's, like, too neat to search the Usenet for articles that match a -string, but it, like, totally @emph{sucks}, like, totally, to use one of -those, like, Web browsers, and you, like, have to, rilly, like, look at -the commercials, so, like, with Gnus you can do @emph{rad}, rilly, -searches without having to use a browser. - -The @code{nnweb} back end allows an easy interface to the mighty search -engine. You create an @code{nnweb} group, enter a search pattern, and -then enter the group and read the articles like you would any normal -group. The @kbd{G w} command in the group buffer (@pxref{Foreign -Groups}) will do this in an easy-to-use fashion. - -@code{nnweb} groups don't really lend themselves to being solid -groups---they have a very fleeting idea of article numbers. In fact, -each time you enter an @code{nnweb} group (not even changing the search -pattern), you are likely to get the articles ordered in a different -manner. Not even using duplicate suppression (@pxref{Duplicate -Suppression}) will help, since @code{nnweb} doesn't even know the -@code{Message-ID} of the articles before reading them using some search -engines (Google, for instance). The only possible way to keep track -of which articles you've read is by scoring on the @code{Date} -header---mark all articles posted before the last date you read the -group as read. - -If the search engine changes its output substantially, @code{nnweb} -won't be able to parse it and will fail. One could hardly fault the Web -providers if they were to do this---their @emph{raison d'@^etre} is to -make money off of advertisements, not to provide services to the -community. Since @code{nnweb} washes the ads off all the articles, one -might think that the providers might be somewhat miffed. We'll see. - -You must have the @code{url} and @code{W3} package or those alternatives -(try @code{customize-group} on the @samp{mm-url} variable group) -installed to be able to use @code{nnweb}. - -Virtual server variables: - -@table @code -@item nnweb-type -@vindex nnweb-type -What search engine type is being used. The currently supported types -are @code{google}, @code{dejanews}, and @code{gmane}. Note that -@code{dejanews} is an alias to @code{google}. - -@item nnweb-search -@vindex nnweb-search -The search string to feed to the search engine. - -@item nnweb-max-hits -@vindex nnweb-max-hits -Advisory maximum number of hits per search to display. The default is -999. - -@item nnweb-type-definition -@vindex nnweb-type-definition -Type-to-definition alist. This alist says what @code{nnweb} should do -with the various search engine types. The following elements must be -present: - -@table @code -@item article -Function to decode the article and provide something that Gnus -understands. - -@item map -Function to create an article number to message header and URL alist. - -@item search -Function to send the search string to the search engine. - -@item address -The address the aforementioned function should send the search string -to. - -@item id -Format string URL to fetch an article by @code{Message-ID}. -@end table - -@end table - - -@node RSS -@subsection RSS -@cindex nnrss -@cindex RSS - -Some web sites have an RDF Site Summary (@acronym{RSS}). -@acronym{RSS} is a format for summarizing headlines from news related -sites (such as BBC or CNN). But basically anything list-like can be -presented as an @acronym{RSS} feed: weblogs, changelogs or recent -changes to a wiki (e.g. @url{http://cliki.net/recent-changes.rdf}). - -@acronym{RSS} has a quite regular and nice interface, and it's -possible to get the information Gnus needs to keep groups updated. - -Note: you had better use Emacs which supports the @code{utf-8} coding -system because @acronym{RSS} uses UTF-8 for encoding non-@acronym{ASCII} -text by default. It is also used by default for non-@acronym{ASCII} -group names. - -@kindex G R (Group) -Use @kbd{G R} from the group buffer to subscribe to a feed---you will be -prompted for the location, the title and the description of the feed. -The title, which allows any characters, will be used for the group name -and the name of the group data file. The description can be omitted. - -An easy way to get started with @code{nnrss} is to say something like -the following in the group buffer: @kbd{B nnrss RET RET y}, then -subscribe to groups. - -The @code{nnrss} back end saves the group data file in -@code{nnrss-directory} (see below) for each @code{nnrss} group. File -names containing non-@acronym{ASCII} characters will be encoded by the -coding system specified with the @code{nnmail-pathname-coding-system} -variable or other. Also @xref{Non-ASCII Group Names}, for more -information. - -The @code{nnrss} back end generates @samp{multipart/alternative} -@acronym{MIME} articles in which each contains a @samp{text/plain} part -and a @samp{text/html} part. - -@cindex OPML -You can also use the following commands to import and export your -subscriptions from a file in @acronym{OPML} format (Outline Processor -Markup Language). - -@defun nnrss-opml-import file -Prompt for an @acronym{OPML} file, and subscribe to each feed in the -file. -@end defun - -@defun nnrss-opml-export -Write your current @acronym{RSS} subscriptions to a buffer in -@acronym{OPML} format. -@end defun - -The following @code{nnrss} variables can be altered: - -@table @code -@item nnrss-directory -@vindex nnrss-directory -The directory where @code{nnrss} stores its files. The default is -@file{~/News/rss/}. - -@item nnrss-file-coding-system -@vindex nnrss-file-coding-system -The coding system used when reading and writing the @code{nnrss} groups -data files. The default is the value of -@code{mm-universal-coding-system} (which defaults to @code{emacs-mule} -in Emacs or @code{escape-quoted} in XEmacs). - -@item nnrss-ignore-article-fields -@vindex nnrss-ignore-article-fields -Some feeds update constantly article fields during their publications, -e.g. to indicate the number of comments. However, if there is -a difference between the local article and the distant one, the latter -is considered to be new. To avoid this and discard some fields, set this -variable to the list of fields to be ignored. The default is -@code{'(slash:comments)}. - -@item nnrss-use-local -@vindex nnrss-use-local -@findex nnrss-generate-download-script -If you set @code{nnrss-use-local} to @code{t}, @code{nnrss} will read -the feeds from local files in @code{nnrss-directory}. You can use -the command @code{nnrss-generate-download-script} to generate a -download script using @command{wget}. -@end table - -The following code may be helpful, if you want to show the description in -the summary buffer. - -@lisp -(add-to-list 'nnmail-extra-headers nnrss-description-field) -(setq gnus-summary-line-format "%U%R%z%I%(%[%4L: %-15,15f%]%) %s%uX\n") - -(defun gnus-user-format-function-X (header) - (let ((descr - (assq nnrss-description-field (mail-header-extra header)))) - (if descr (concat "\n\t" (cdr descr)) ""))) -@end lisp - -The following code may be useful to open an nnrss url directly from the -summary buffer. - -@lisp -(require 'browse-url) - -(defun browse-nnrss-url (arg) - (interactive "p") - (let ((url (assq nnrss-url-field - (mail-header-extra - (gnus-data-header - (assq (gnus-summary-article-number) - gnus-newsgroup-data)))))) - (if url - (progn - (browse-url (cdr url)) - (gnus-summary-mark-as-read-forward 1)) - (gnus-summary-scroll-up arg)))) - -(eval-after-load "gnus" - #'(define-key gnus-summary-mode-map - (kbd "") 'browse-nnrss-url)) -(add-to-list 'nnmail-extra-headers nnrss-url-field) -@end lisp - -Even if you have added @samp{text/html} to the -@code{mm-discouraged-alternatives} variable (@pxref{Display -Customization, ,Display Customization, emacs-mime, The Emacs MIME -Manual}) since you don't want to see @acronym{HTML} parts, it might be -more useful especially in @code{nnrss} groups to display -@samp{text/html} parts. Here's an example of setting -@code{mm-discouraged-alternatives} as a group parameter (@pxref{Group -Parameters}) in order to display @samp{text/html} parts only in -@code{nnrss} groups: - -@lisp -;; @r{Set the default value of @code{mm-discouraged-alternatives}.} -(eval-after-load "gnus-sum" - '(add-to-list - 'gnus-newsgroup-variables - '(mm-discouraged-alternatives - . '("text/html" "image/.*")))) - -;; @r{Display @samp{text/html} parts in @code{nnrss} groups.} -(add-to-list - 'gnus-parameters - '("\\`nnrss:" (mm-discouraged-alternatives nil))) -@end lisp - - -@node Customizing W3 -@subsection Customizing W3 -@cindex W3 -@cindex html -@cindex url -@cindex Netscape - -Gnus uses the url library to fetch web pages and Emacs/W3 (or those -alternatives) to display web pages. Emacs/W3 is documented in its own -manual, but there are some things that may be more relevant for Gnus -users. - -For instance, a common question is how to make Emacs/W3 follow links -using the @code{browse-url} functions (which will call some external web -browser like Netscape). Here's one way: - -@lisp -(eval-after-load "w3" - '(progn - (fset 'w3-fetch-orig (symbol-function 'w3-fetch)) - (defun w3-fetch (&optional url target) - (interactive (list (w3-read-url-with-default))) - (if (eq major-mode 'gnus-article-mode) - (browse-url url) - (w3-fetch-orig url target))))) -@end lisp - -Put that in your @file{.emacs} file, and hitting links in W3-rendered -@acronym{HTML} in the Gnus article buffers will use @code{browse-url} to -follow the link. - - -@node Other Sources -@section Other Sources - -Gnus can do more than just read news or mail. The methods described -below allow Gnus to view directories and files as if they were -newsgroups. - -@menu -* Directory Groups:: You can read a directory as if it was a newsgroup. -* Anything Groups:: Dired? Who needs dired? -* Document Groups:: Single files can be the basis of a group. -* Mail-To-News Gateways:: Posting articles via mail-to-news gateways. -* The Empty Backend:: The backend that never has any news. -@end menu - - -@node Directory Groups -@subsection Directory Groups -@cindex nndir -@cindex directory groups - -If you have a directory that has lots of articles in separate files in -it, you might treat it as a newsgroup. The files have to have numerical -names, of course. - -This might be an opportune moment to mention @code{ange-ftp} (and its -successor @code{efs}), that most wonderful of all wonderful Emacs -packages. When I wrote @code{nndir}, I didn't think much about it---a -back end to read directories. Big deal. - -@code{ange-ftp} changes that picture dramatically. For instance, if you -enter the @code{ange-ftp} file name -@file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name, -@code{ange-ftp} or @code{efs} will actually allow you to read this -directory over at @samp{sina} as a newsgroup. Distributed news ahoy! - -@code{nndir} will use @acronym{NOV} files if they are present. - -@code{nndir} is a ``read-only'' back end---you can't delete or expire -articles with this method. You can use @code{nnmh} or @code{nnml} for -whatever you use @code{nndir} for, so you could switch to any of those -methods if you feel the need to have a non-read-only @code{nndir}. - - -@node Anything Groups -@subsection Anything Groups -@cindex nneething - -From the @code{nndir} back end (which reads a single spool-like -directory), it's just a hop and a skip to @code{nneething}, which -pretends that any arbitrary directory is a newsgroup. Strange, but -true. - -When @code{nneething} is presented with a directory, it will scan this -directory and assign article numbers to each file. When you enter such -a group, @code{nneething} must create ``headers'' that Gnus can use. -After all, Gnus is a newsreader, in case you're forgetting. -@code{nneething} does this in a two-step process. First, it snoops each -file in question. If the file looks like an article (i.e., the first -few lines look like headers), it will use this as the head. If this is -just some arbitrary file without a head (e.g. a C source file), -@code{nneething} will cobble up a header out of thin air. It will use -file ownership, name and date and do whatever it can with these -elements. - -All this should happen automatically for you, and you will be presented -with something that looks very much like a newsgroup. Totally like a -newsgroup, to be precise. If you select an article, it will be displayed -in the article buffer, just as usual. - -If you select a line that represents a directory, Gnus will pop you into -a new summary buffer for this @code{nneething} group. And so on. You can -traverse the entire disk this way, if you feel like, but remember that -Gnus is not dired, really, and does not intend to be, either. - -There are two overall modes to this action---ephemeral or solid. When -doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus -will not store information on what files you have read, and what files -are new, and so on. If you create a solid @code{nneething} group the -normal way with @kbd{G m}, Gnus will store a mapping table between -article numbers and file names, and you can treat this group like any -other groups. When you activate a solid @code{nneething} group, you will -be told how many unread articles it contains, etc., etc. - -Some variables: - -@table @code -@item nneething-map-file-directory -@vindex nneething-map-file-directory -All the mapping files for solid @code{nneething} groups will be stored -in this directory, which defaults to @file{~/.nneething/}. - -@item nneething-exclude-files -@vindex nneething-exclude-files -All files that match this regexp will be ignored. Nice to use to exclude -auto-save files and the like, which is what it does by default. - -@item nneething-include-files -@vindex nneething-include-files -Regexp saying what files to include in the group. If this variable is -non-@code{nil}, only files matching this regexp will be included. - -@item nneething-map-file -@vindex nneething-map-file -Name of the map files. -@end table - - -@node Document Groups -@subsection Document Groups -@cindex nndoc -@cindex documentation group -@cindex help group - -@code{nndoc} is a cute little thing that will let you read a single file -as a newsgroup. Several files types are supported: - -@table @code -@cindex Babyl -@item babyl -The Babyl format. - -@cindex mbox -@cindex Unix mbox -@item mbox -The standard Unix mbox file. - -@cindex MMDF mail box -@item mmdf -The MMDF mail box format. - -@item news -Several news articles appended into a file. - -@cindex rnews batch files -@item rnews -The rnews batch transport format. - -@item nsmail -Netscape mail boxes. - -@item mime-parts -@acronym{MIME} multipart messages. - -@item standard-digest -The standard (RFC 1153) digest format. - -@item mime-digest -A @acronym{MIME} digest of messages. - -@item lanl-gov-announce -Announcement messages from LANL Gov Announce. - -@cindex git commit messages -@item git -@code{git} commit messages. - -@cindex forwarded messages -@item rfc822-forward -A message forwarded according to RFC822. - -@item outlook -The Outlook mail box. - -@item oe-dbx -The Outlook Express dbx mail box. - -@item exim-bounce -A bounce message from the Exim MTA. - -@item forward -A message forwarded according to informal rules. - -@item rfc934 -An RFC934-forwarded message. - -@item mailman -A mailman digest. - -@item clari-briefs -A digest of Clarinet brief news items. - -@item slack-digest -Non-standard digest format---matches most things, but does it badly. - -@item mail-in-mail -The last resort. -@end table - -You can also use the special ``file type'' @code{guess}, which means -that @code{nndoc} will try to guess what file type it is looking at. -@code{digest} means that @code{nndoc} should guess what digest type the -file is. - -@code{nndoc} will not try to change the file or insert any extra headers into -it---it will simply, like, let you use the file as the basis for a -group. And that's it. - -If you have some old archived articles that you want to insert into your -new & spiffy Gnus mail back end, @code{nndoc} can probably help you with -that. Say you have an old @file{RMAIL} file with mail that you now want -to split into your new @code{nnml} groups. You look at that file using -@code{nndoc} (using the @kbd{G f} command in the group buffer -(@pxref{Foreign Groups})), set the process mark on all the articles in -the buffer (@kbd{M P b}, for instance), and then re-spool (@kbd{B r}) -using @code{nnml}. If all goes well, all the mail in the @file{RMAIL} -file is now also stored in lots of @code{nnml} directories, and you can -delete that pesky @file{RMAIL} file. If you have the guts! - -Virtual server variables: - -@table @code -@item nndoc-article-type -@vindex nndoc-article-type -This should be one of @code{mbox}, @code{babyl}, @code{digest}, -@code{news}, @code{rnews}, @code{mmdf}, @code{forward}, @code{rfc934}, -@code{rfc822-forward}, @code{mime-parts}, @code{standard-digest}, -@code{slack-digest}, @code{clari-briefs}, @code{nsmail}, @code{outlook}, -@code{oe-dbx}, @code{mailman}, and @code{mail-in-mail} or @code{guess}. - -@item nndoc-post-type -@vindex nndoc-post-type -This variable says whether Gnus is to consider the group a news group or -a mail group. There are two valid values: @code{mail} (the default) -and @code{news}. -@end table - -@menu -* Document Server Internals:: How to add your own document types. -@end menu - - -@node Document Server Internals -@subsubsection Document Server Internals - -Adding new document types to be recognized by @code{nndoc} isn't -difficult. You just have to whip up a definition of what the document -looks like, write a predicate function to recognize that document type, -and then hook into @code{nndoc}. - -First, here's an example document type definition: - -@example -(mmdf - (article-begin . "^\^A\^A\^A\^A\n") - (body-end . "^\^A\^A\^A\^A\n")) -@end example - -The definition is simply a unique @dfn{name} followed by a series of -regexp pseudo-variable settings. Below are the possible -variables---don't be daunted by the number of variables; most document -types can be defined with very few settings: - -@table @code -@item first-article -If present, @code{nndoc} will skip past all text until it finds -something that match this regexp. All text before this will be -totally ignored. - -@item article-begin -This setting has to be present in all document type definitions. It -says what the beginning of each article looks like. To do more -complicated things that cannot be dealt with a simple regexp, you can -use @code{article-begin-function} instead of this. - -@item article-begin-function -If present, this should be a function that moves point to the beginning -of each article. This setting overrides @code{article-begin}. - -@item head-begin -If present, this should be a regexp that matches the head of the -article. To do more complicated things that cannot be dealt with a -simple regexp, you can use @code{head-begin-function} instead of this. - -@item head-begin-function -If present, this should be a function that moves point to the head of -the article. This setting overrides @code{head-begin}. - -@item head-end -This should match the end of the head of the article. It defaults to -@samp{^$}---the empty line. - -@item body-begin -This should match the beginning of the body of the article. It defaults -to @samp{^\n}. To do more complicated things that cannot be dealt with -a simple regexp, you can use @code{body-begin-function} instead of this. - -@item body-begin-function -If present, this function should move point to the beginning of the body -of the article. This setting overrides @code{body-begin}. - -@item body-end -If present, this should match the end of the body of the article. To do -more complicated things that cannot be dealt with a simple regexp, you -can use @code{body-end-function} instead of this. - -@item body-end-function -If present, this function should move point to the end of the body of -the article. This setting overrides @code{body-end}. - -@item file-begin -If present, this should match the beginning of the file. All text -before this regexp will be totally ignored. - -@item file-end -If present, this should match the end of the file. All text after this -regexp will be totally ignored. - -@end table - -So, using these variables @code{nndoc} is able to dissect a document -file into a series of articles, each with a head and a body. However, a -few more variables are needed since not all document types are all that -news-like---variables needed to transform the head or the body into -something that's palatable for Gnus: - -@table @code -@item prepare-body-function -If present, this function will be called when requesting an article. It -will be called with point at the start of the body, and is useful if the -document has encoded some parts of its contents. - -@item article-transform-function -If present, this function is called when requesting an article. It's -meant to be used for more wide-ranging transformation of both head and -body of the article. - -@item generate-head-function -If present, this function is called to generate a head that Gnus can -understand. It is called with the article number as a parameter, and is -expected to generate a nice head for the article in question. It is -called when requesting the headers of all articles. - -@item generate-article-function -If present, this function is called to generate an entire article that -Gnus can understand. It is called with the article number as a -parameter when requesting all articles. - -@item dissection-function -If present, this function is called to dissect a document by itself, -overriding @code{first-article}, @code{article-begin}, -@code{article-begin-function}, @code{head-begin}, -@code{head-begin-function}, @code{head-end}, @code{body-begin}, -@code{body-begin-function}, @code{body-end}, @code{body-end-function}, -@code{file-begin}, and @code{file-end}. - -@end table - -Let's look at the most complicated example I can come up with---standard -digests: - -@example -(standard-digest - (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+")) - (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+")) - (prepare-body-function . nndoc-unquote-dashes) - (body-end-function . nndoc-digest-body-end) - (head-end . "^ ?$") - (body-begin . "^ ?\n") - (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$") - (subtype digest guess)) -@end example - -We see that all text before a 70-width line of dashes is ignored; all -text after a line that starts with that @samp{^End of} is also ignored; -each article begins with a 30-width line of dashes; the line separating -the head from the body may contain a single space; and that the body is -run through @code{nndoc-unquote-dashes} before being delivered. - -To hook your own document definition into @code{nndoc}, use the -@code{nndoc-add-type} function. It takes two parameters---the first -is the definition itself and the second (optional) parameter says -where in the document type definition alist to put this definition. -The alist is traversed sequentially, and -@code{nndoc-@var{type}-type-p} is called for a given type @var{type}. -So @code{nndoc-mmdf-type-p} is called to see whether a document is of -@code{mmdf} type, and so on. These type predicates should return -@code{nil} if the document is not of the correct type; @code{t} if it -is of the correct type; and a number if the document might be of the -correct type. A high number means high probability; a low number -means low probability with @samp{0} being the lowest valid number. - - -@node Mail-To-News Gateways -@subsection Mail-To-News Gateways -@cindex mail-to-news gateways -@cindex gateways - -If your local @code{nntp} server doesn't allow posting, for some reason -or other, you can post using one of the numerous mail-to-news gateways. -The @code{nngateway} back end provides the interface. - -Note that you can't read anything from this back end---it can only be -used to post with. - -Server variables: - -@table @code -@item nngateway-address -@vindex nngateway-address -This is the address of the mail-to-news gateway. - -@item nngateway-header-transformation -@vindex nngateway-header-transformation -News headers often have to be transformed in some odd way or other -for the mail-to-news gateway to accept it. This variable says what -transformation should be called, and defaults to -@code{nngateway-simple-header-transformation}. The function is called -narrowed to the headers to be transformed and with one parameter---the -gateway address. - -This default function just inserts a new @code{To} header based on the -@code{Newsgroups} header and the gateway address. -For instance, an article with this @code{Newsgroups} header: - -@example -Newsgroups: alt.religion.emacs -@end example - -will get this @code{To} header inserted: - -@example -To: alt-religion-emacs@@GATEWAY -@end example - -The following pre-defined functions exist: - -@findex nngateway-simple-header-transformation -@table @code - -@item nngateway-simple-header-transformation -Creates a @code{To} header that looks like -@var{newsgroup}@@@code{nngateway-address}. - -@findex nngateway-mail2news-header-transformation - -@item nngateway-mail2news-header-transformation -Creates a @code{To} header that looks like -@code{nngateway-address}. -@end table - -@end table - -Here's an example: - -@lisp -(setq gnus-post-method - '(nngateway - "mail2news@@replay.com" - (nngateway-header-transformation - nngateway-mail2news-header-transformation))) -@end lisp - -So, to use this, simply say something like: - -@lisp -(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS")) -@end lisp - - -@node The Empty Backend -@subsection The Empty Backend -@cindex nnnil - -@code{nnnil} is a backend that can be used as a placeholder if you -have to specify a backend somewhere, but don't really want to. The -classical example is if you don't want to have a primary select -methods, but want to only use secondary ones: - -@lisp -(setq gnus-select-method '(nnnil "")) -(setq gnus-secondary-select-methods - '((nnimap "foo") - (nnml ""))) -@end lisp - - -@node Combined Groups -@section Combined Groups - -Gnus allows combining a mixture of all the other group types into bigger -groups. - -@menu -* Virtual Groups:: Combining articles from many groups. -@end menu - - -@node Virtual Groups -@subsection Virtual Groups -@cindex nnvirtual -@cindex virtual groups -@cindex merging groups - -An @dfn{nnvirtual group} is really nothing more than a collection of -other groups. - -For instance, if you are tired of reading many small groups, you can -put them all in one big group, and then grow tired of reading one -big, unwieldy group. The joys of computing! - -You specify @code{nnvirtual} as the method. The address should be a -regexp to match component groups. - -All marks in the virtual group will stick to the articles in the -component groups. So if you tick an article in a virtual group, the -article will also be ticked in the component group from whence it -came. (And vice versa---marks from the component groups will also be -shown in the virtual group.). To create an empty virtual group, run -@kbd{G V} (@code{gnus-group-make-empty-virtual}) in the group buffer -and edit the method regexp with @kbd{M-e} -(@code{gnus-group-edit-group-method}) - -Here's an example @code{nnvirtual} method that collects all Andrea Dworkin -newsgroups into one, big, happy newsgroup: - -@lisp -(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*") -@end lisp - -The component groups can be native or foreign; everything should work -smoothly, but if your computer explodes, it was probably my fault. - -Collecting the same group from several servers might actually be a good -idea if users have set the Distribution header to limit distribution. -If you would like to read @samp{soc.motss} both from a server in Japan -and a server in Norway, you could use the following as the group regexp: - -@example -"^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$" -@end example - -(Remember, though, that if you're creating the group with @kbd{G m}, you -shouldn't double the backslashes, and you should leave off the quote -characters at the beginning and the end of the string.) - -This should work kinda smoothly---all articles from both groups should -end up in this one, and there should be no duplicates. Threading (and -the rest) will still work as usual, but there might be problems with the -sequence of articles. Sorting on date might be an option here -(@pxref{Selecting a Group}). - -One limitation, however---all groups included in a virtual -group have to be alive (i.e., subscribed or unsubscribed). Killed or -zombie groups can't be component groups for @code{nnvirtual} groups. - -@vindex nnvirtual-always-rescan -If the @code{nnvirtual-always-rescan} variable is non-@code{nil} (which -is the default), @code{nnvirtual} will always scan groups for unread -articles when entering a virtual group. If this variable is @code{nil} -and you read articles in a component group after the virtual group has -been activated, the read articles from the component group will show up -when you enter the virtual group. You'll also see this effect if you -have two virtual groups that have a component group in common. If -that's the case, you should set this variable to @code{t}. Or you can -just tap @code{M-g} on the virtual group every time before you enter -it---it'll have much the same effect. - -@code{nnvirtual} can have both mail and news groups as component groups. -When responding to articles in @code{nnvirtual} groups, @code{nnvirtual} -has to ask the back end of the component group the article comes from -whether it is a news or mail back end. However, when you do a @kbd{^}, -there is typically no sure way for the component back end to know this, -and in that case @code{nnvirtual} tells Gnus that the article came from a -not-news back end. (Just to be on the safe side.) - -@kbd{C-c C-n} in the message buffer will insert the @code{Newsgroups} -line from the article you respond to in these cases. - -@code{nnvirtual} groups do not inherit anything but articles and marks -from component groups---group parameters, for instance, are not -inherited. - - -@node Email Based Diary -@section Email Based Diary -@cindex diary -@cindex email based diary -@cindex calendar - -This section describes a special mail back end called @code{nndiary}, -and its companion library @code{gnus-diary}. It is ``special'' in the -sense that it is not meant to be one of the standard alternatives for -reading mail with Gnus. See @ref{Choosing a Mail Back End} for that. -Instead, it is used to treat @emph{some} of your mails in a special way, -namely, as event reminders. - -Here is a typical scenario: - -@itemize @bullet -@item -You've got a date with Andy Mc Dowell or Bruce Willis (select according -to your sexual preference) in one month. You don't want to forget it. -@item -So you send a ``reminder'' message (actually, a diary one) to yourself. -@item -You forget all about it and keep on getting and reading new mail, as usual. -@item -From time to time, as you type `g' in the group buffer and as the date -is getting closer, the message will pop up again to remind you of your -appointment, just as if it were new and unread. -@item -Read your ``new'' messages, this one included, and start dreaming again -of the night you're gonna have. -@item -Once the date is over (you actually fell asleep just after dinner), the -message will be automatically deleted if it is marked as expirable. -@end itemize - -The Gnus Diary back end has the ability to handle regular appointments -(that wouldn't ever be deleted) as well as punctual ones, operates as a -real mail back end and is configurable in many ways. All of this is -explained in the sections below. - -@menu -* The NNDiary Back End:: Basic setup and usage. -* The Gnus Diary Library:: Utility toolkit on top of nndiary. -* Sending or Not Sending:: A final note on sending diary messages. -@end menu - - -@node The NNDiary Back End -@subsection The NNDiary Back End -@cindex nndiary -@cindex the nndiary back end - -@code{nndiary} is a back end very similar to @code{nnml} (@pxref{Mail -Spool}). Actually, it could appear as a mix of @code{nnml} and -@code{nndraft}. If you know @code{nnml}, you're already familiar with -the message storing scheme of @code{nndiary}: one file per message, one -directory per group. - - Before anything, there is one requirement to be able to run -@code{nndiary} properly: you @emph{must} use the group timestamp feature -of Gnus. This adds a timestamp to each group's parameters. @ref{Group -Timestamp} to see how it's done. - -@menu -* Diary Messages:: What makes a message valid for nndiary. -* Running NNDiary:: NNDiary has two modes of operation. -* Customizing NNDiary:: Bells and whistles. -@end menu - -@node Diary Messages -@subsubsection Diary Messages -@cindex nndiary messages -@cindex nndiary mails - -@code{nndiary} messages are just normal ones, except for the mandatory -presence of 7 special headers. These headers are of the form -@code{X-Diary-}, @code{} being one of -@code{Minute}, @code{Hour}, @code{Dom}, @code{Month}, @code{Year}, -@code{Time-Zone} and @code{Dow}. @code{Dom} means ``Day of Month'', and -@code{dow} means ``Day of Week''. These headers actually behave like -crontab specifications and define the event date(s): - -@itemize @bullet -@item -For all headers except the @code{Time-Zone} one, a header value is -either a star (meaning all possible values), or a list of fields -(separated by a comma). -@item -A field is either an integer, or a range. -@item -A range is two integers separated by a dash. -@item -Possible integer values are 0--59 for @code{Minute}, 0--23 for -@code{Hour}, 1--31 for @code{Dom}, 1--12 for @code{Month}, above 1971 -for @code{Year} and 0--6 for @code{Dow} (0 meaning Sunday). -@item -As a special case, a star in either @code{Dom} or @code{Dow} doesn't -mean ``all possible values'', but ``use only the other field''. Note -that if both are star'ed, the use of either one gives the same result. -@item -The @code{Time-Zone} header is special in that it can only have one -value (@code{GMT}, for instance). A star doesn't mean ``all possible -values'' (because it makes no sense), but ``the current local time -zone''. Most of the time, you'll be using a star here. However, for a -list of available time zone values, see the variable -@code{nndiary-headers}. -@end itemize - -As a concrete example, here are the diary headers to add to your message -for specifying ``Each Monday and each 1st of month, at 12:00, 20:00, -21:00, 22:00, 23:00 and 24:00, from 1999 to 2010'' (I'll let you find -what to do then): - -@example -X-Diary-Minute: 0 -X-Diary-Hour: 12, 20-24 -X-Diary-Dom: 1 -X-Diary-Month: * -X-Diary-Year: 1999-2010 -X-Diary-Dow: 1 -X-Diary-Time-Zone: * -@end example - -@node Running NNDiary -@subsubsection Running NNDiary -@cindex running nndiary -@cindex nndiary operation modes - -@code{nndiary} has two modes of operation: ``traditional'' (the default) -and ``autonomous''. In traditional mode, @code{nndiary} does not get new -mail by itself. You have to move (@kbd{B m}) or copy (@kbd{B c}) mails -from your primary mail back end to nndiary groups in order to handle them -as diary messages. In autonomous mode, @code{nndiary} retrieves its own -mail and handles it independently from your primary mail back end. - -One should note that Gnus is not inherently designed to allow several -``master'' mail back ends at the same time. However, this does make -sense with @code{nndiary}: you really want to send and receive diary -messages to your diary groups directly. So, @code{nndiary} supports -being sort of a ``second primary mail back end'' (to my knowledge, it is -the only back end offering this feature). However, there is a limitation -(which I hope to fix some day): respooling doesn't work in autonomous -mode. - -In order to use @code{nndiary} in autonomous mode, you have several -things to do: - -@itemize @bullet -@item -Allow @code{nndiary} to retrieve new mail by itself. Put the following -line in your @file{~/.gnus.el} file: - -@lisp -(setq nndiary-get-new-mail t) -@end lisp -@item -You must arrange for diary messages (those containing @code{X-Diary-*} -headers) to be split in a private folder @emph{before} Gnus treat them. -Again, this is needed because Gnus cannot (yet ?) properly handle -multiple primary mail back ends. Getting those messages from a separate -source will compensate this misfeature to some extent. - -As an example, here's my procmailrc entry to store diary files in -@file{~/.nndiary} (the default @code{nndiary} mail source file): - -@example -:0 HD : -* ^X-Diary -.nndiary -@end example -@end itemize - -Once this is done, you might want to customize the following two options -that affect the diary mail retrieval and splitting processes: - -@defvar nndiary-mail-sources -This is the diary-specific replacement for the standard -@code{mail-sources} variable. It obeys the same syntax, and defaults to -@code{(file :path "~/.nndiary")}. -@end defvar - -@defvar nndiary-split-methods -This is the diary-specific replacement for the standard -@code{nnmail-split-methods} variable. It obeys the same syntax. -@end defvar - - Finally, you may add a permanent @code{nndiary} virtual server -(something like @code{(nndiary "diary")} should do) to your -@code{gnus-secondary-select-methods}. - - Hopefully, almost everything (see the TODO section in -@file{nndiary.el}) will work as expected when you restart Gnus: in -autonomous mode, typing @kbd{g} and @kbd{M-g} in the group buffer, will -also get your new diary mails and split them according to your -diary-specific rules, @kbd{F} will find your new diary groups etc. - -@node Customizing NNDiary -@subsubsection Customizing NNDiary -@cindex customizing nndiary -@cindex nndiary customization - -Now that @code{nndiary} is up and running, it's time to customize it. -The custom group is called @code{nndiary} (no, really ?!). You should -browse it to figure out which options you'd like to tweak. The following -two variables are probably the only ones you will want to change: - -@defvar nndiary-reminders -This is the list of times when you want to be reminded of your -appointments (e.g. 3 weeks before, then 2 days before, then 1 hour -before and that's it). Remember that ``being reminded'' means that the -diary message will pop up as brand new and unread again when you get new -mail. -@end defvar - -@defvar nndiary-week-starts-on-monday -Rather self-explanatory. Otherwise, Sunday is assumed (this is the -default). -@end defvar - - -@node The Gnus Diary Library -@subsection The Gnus Diary Library -@cindex gnus-diary -@cindex the gnus diary library - -Using @code{nndiary} manually (I mean, writing the headers by hand and -so on) would be rather boring. Fortunately, there is a library called -@code{gnus-diary} written on top of @code{nndiary}, that does many -useful things for you. - - In order to use it, add the following line to your @file{~/.gnus.el} file: - -@lisp -(require 'gnus-diary) -@end lisp - - Also, you shouldn't use any @code{gnus-user-format-function-[d|D]} -(@pxref{Summary Buffer Lines}). @code{gnus-diary} provides both of these -(sorry if you used them before). - - -@menu -* Diary Summary Line Format:: A nicer summary buffer line format. -* Diary Articles Sorting:: A nicer way to sort messages. -* Diary Headers Generation:: Not doing it manually. -* Diary Group Parameters:: Not handling them manually. -@end menu - -@node Diary Summary Line Format -@subsubsection Diary Summary Line Format -@cindex diary summary buffer line -@cindex diary summary line format - -Displaying diary messages in standard summary line format (usually -something like @samp{From Joe: Subject}) is pretty useless. Most of -the time, you're the one who wrote the message, and you mostly want to -see the event's date. - - @code{gnus-diary} provides two supplemental user formats to be used in -summary line formats. @code{D} corresponds to a formatted time string -for the next occurrence of the event (e.g. ``Sat, Sep 22 01, 12:00''), -while @code{d} corresponds to an approximate remaining time until the -next occurrence of the event (e.g. ``in 6 months, 1 week''). - - For example, here's how Joe's birthday is displayed in my -@code{nndiary+diary:birthdays} summary buffer (note that the message is -expirable, but will never be deleted, as it specifies a periodic event): - -@example - E Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week) -@end example - -In order to get something like the above, you would normally add the -following line to your diary groups'parameters: - -@lisp -(gnus-summary-line-format "%U%R%z %uD: %(%s%) (%ud)\n") -@end lisp - -However, @code{gnus-diary} does it automatically (@pxref{Diary Group -Parameters}). You can however customize the provided summary line format -with the following user options: - -@defvar gnus-diary-summary-line-format -Defines the summary line format used for diary groups (@pxref{Summary -Buffer Lines}). @code{gnus-diary} uses it to automatically update the -diary groups'parameters. -@end defvar - -@defvar gnus-diary-time-format -Defines the format to display dates in diary summary buffers. This is -used by the @code{D} user format. See the docstring for details. -@end defvar - -@defvar gnus-diary-delay-format-function -Defines the format function to use for displaying delays (remaining -times) in diary summary buffers. This is used by the @code{d} user -format. There are currently built-in functions for English and French; -you can also define your own. See the docstring for details. -@end defvar - -@node Diary Articles Sorting -@subsubsection Diary Articles Sorting -@cindex diary articles sorting -@cindex diary summary lines sorting -@findex gnus-summary-sort-by-schedule -@findex gnus-thread-sort-by-schedule -@findex gnus-article-sort-by-schedule - -@code{gnus-diary} provides new sorting functions (@pxref{Sorting the -Summary Buffer} ) called @code{gnus-summary-sort-by-schedule}, -@code{gnus-thread-sort-by-schedule} and -@code{gnus-article-sort-by-schedule}. These functions let you organize -your diary summary buffers from the closest event to the farthest one. - -@code{gnus-diary} automatically installs -@code{gnus-summary-sort-by-schedule} as a menu item in the summary -buffer's ``sort'' menu, and the two others as the primary (hence -default) sorting functions in the group parameters (@pxref{Diary Group -Parameters}). - -@node Diary Headers Generation -@subsubsection Diary Headers Generation -@cindex diary headers generation -@findex gnus-diary-check-message - -@code{gnus-diary} provides a function called -@code{gnus-diary-check-message} to help you handle the @code{X-Diary-*} -headers. This function ensures that the current message contains all the -required diary headers, and prompts you for values or corrections if -needed. - - This function is hooked into the @code{nndiary} back end, so that -moving or copying an article to a diary group will trigger it -automatically. It is also bound to @kbd{C-c C-f d} in -@code{message-mode} and @code{article-edit-mode} in order to ease the -process of converting a usual mail to a diary one. - - This function takes a prefix argument which will force prompting of -all diary headers, regardless of their presence or validity. That way, -you can very easily reschedule an already valid diary message, for -instance. - -@node Diary Group Parameters -@subsubsection Diary Group Parameters -@cindex diary group parameters - -When you create a new diary group, or visit one, @code{gnus-diary} -automatically checks your group parameters and if needed, sets the -summary line format to the diary-specific value, installs the -diary-specific sorting functions, and also adds the different -@code{X-Diary-*} headers to the group's posting-style. It is then easier -to send a diary message, because if you use @kbd{C-u a} or @kbd{C-u m} -on a diary group to prepare a message, these headers will be inserted -automatically (although not filled with proper values yet). - -@node Sending or Not Sending -@subsection Sending or Not Sending - -Well, assuming you've read all of the above, here are two final notes on -mail sending with @code{nndiary}: - -@itemize @bullet -@item -@code{nndiary} is a @emph{real} mail back end. You really send real diary -messages for real. This means for instance that you can give -appointments to anybody (provided they use Gnus and @code{nndiary}) by -sending the diary message to them as well. -@item -However, since @code{nndiary} also has a @code{request-post} method, you -can also use @kbd{C-u a} instead of @kbd{C-u m} on a diary group and the -message won't actually be sent; just stored locally in the group. This -comes in very handy for private appointments. -@end itemize - -@node Gnus Unplugged -@section Gnus Unplugged -@cindex offline -@cindex unplugged -@cindex agent -@cindex Gnus agent -@cindex Gnus unplugged - -In olden times (ca. February '88), people used to run their newsreaders -on big machines with permanent connections to the net. News transport -was dealt with by news servers, and all the newsreaders had to do was to -read news. Believe it or not. - -Nowadays most people read news and mail at home, and use some sort of -modem to connect to the net. To avoid running up huge phone bills, it -would be nice to have a way to slurp down all the news and mail, hang up -the phone, read for several hours, and then upload any responses you -have to make. And then you repeat the procedure. - -Of course, you can use news servers for doing this as well. I've used -@code{inn} together with @code{slurp}, @code{pop} and @code{sendmail} -for some years, but doing that's a bore. Moving the news server -functionality up to the newsreader makes sense if you're the only person -reading news on a machine. - -Setting up Gnus as an ``offline'' newsreader is quite simple. In -fact, you don't have to configure anything as the agent is now enabled -by default (@pxref{Agent Variables, gnus-agent}). - -Of course, to use it as such, you have to learn a few new commands. - -@menu -* Agent Basics:: How it all is supposed to work. -* Agent Categories:: How to tell the Gnus Agent what to download. -* Agent Commands:: New commands for all the buffers. -* Agent Visuals:: Ways that the agent may effect your summary buffer. -* Agent as Cache:: The Agent is a big cache too. -* Agent Expiry:: How to make old articles go away. -* Agent Regeneration:: How to recover from lost connections and other accidents. -* Agent and flags:: How the Agent maintains flags. -* Agent and IMAP:: How to use the Agent with @acronym{IMAP}. -* Outgoing Messages:: What happens when you post/mail something? -* Agent Variables:: Customizing is fun. -* Example Setup:: An example @file{~/.gnus.el} file for offline people. -* Batching Agents:: How to fetch news from a @code{cron} job. -* Agent Caveats:: What you think it'll do and what it does. -@end menu - - -@node Agent Basics -@subsection Agent Basics - -First, let's get some terminology out of the way. - -The Gnus Agent is said to be @dfn{unplugged} when you have severed the -connection to the net (and notified the Agent that this is the case). -When the connection to the net is up again (and Gnus knows this), the -Agent is @dfn{plugged}. - -The @dfn{local} machine is the one you're running on, and which isn't -connected to the net continuously. - -@dfn{Downloading} means fetching things from the net to your local -machine. @dfn{Uploading} is doing the opposite. - -You know that Gnus gives you all the opportunity you'd ever want for -shooting yourself in the foot. Some people call it flexibility. Gnus -is also customizable to a great extent, which means that the user has a -say on how Gnus behaves. Other newsreaders might unconditionally shoot -you in your foot, but with Gnus, you have a choice! - -Gnus is never really in plugged or unplugged state. Rather, it applies -that state to each server individually. This means that some servers -can be plugged while others can be unplugged. Additionally, some -servers can be ignored by the Agent altogether (which means that -they're kinda like plugged always). - -So when you unplug the Agent and then wonder why is Gnus opening a -connection to the Net, the next step to do is to look whether all -servers are agentized. If there is an unagentized server, you found -the culprit. - -Another thing is the @dfn{offline} state. Sometimes, servers aren't -reachable. When Gnus notices this, it asks you whether you want the -server to be switched to offline state. If you say yes, then the -server will behave somewhat as if it was unplugged, except that Gnus -will ask you whether you want to switch it back online again. - -Let's take a typical Gnus session using the Agent. - -@itemize @bullet - -@item -@findex gnus-unplugged -You start Gnus with @code{gnus-unplugged}. This brings up the Gnus -Agent in a disconnected state. You can read all the news that you have -already fetched while in this mode. - -@item -You then decide to see whether any new news has arrived. You connect -your machine to the net (using PPP or whatever), and then hit @kbd{J j} -to make Gnus become @dfn{plugged} and use @kbd{g} to check for new mail -as usual. To check for new mail in unplugged mode (@pxref{Mail -Source Specifiers}). - -@item -You can then read the new news immediately, or you can download the -news onto your local machine. If you want to do the latter, you press -@kbd{g} to check if there are any new news and then @kbd{J s} to fetch -all the eligible articles in all the groups. (To let Gnus know which -articles you want to download, @pxref{Agent Categories}). - -@item -After fetching the articles, you press @kbd{J j} to make Gnus become -unplugged again, and you shut down the PPP thing (or whatever). And -then you read the news offline. - -@item -And then you go to step 2. -@end itemize - -Here are some things you should do the first time (or so) that you use -the Agent. - -@itemize @bullet - -@item -Decide which servers should be covered by the Agent. If you have a mail -back end, it would probably be nonsensical to have it covered by the -Agent. Go to the server buffer (@kbd{^} in the group buffer) and press -@kbd{J a} on the server (or servers) that you wish to have covered by the -Agent (@pxref{Server Agent Commands}), or @kbd{J r} on automatically -added servers you do not wish to have covered by the Agent. By default, -no servers are agentized. - -@item -Decide on download policy. It's fairly simple once you decide whether -you are going to use agent categories, topic parameters, and/or group -parameters to implement your policy. If you're new to gnus, it -is probably best to start with a category, @xref{Agent Categories}. - -Both topic parameters (@pxref{Topic Parameters}) and agent categories -(@pxref{Agent Categories}) provide for setting a policy that applies -to multiple groups. Which you use is entirely up to you. Topic -parameters do override categories so, if you mix the two, you'll have -to take that into account. If you have a few groups that deviate from -your policy, you can use group parameters (@pxref{Group Parameters}) to -configure them. - -@item -Uhm@dots{} that's it. -@end itemize - - -@node Agent Categories -@subsection Agent Categories - -One of the main reasons to integrate the news transport layer into the -newsreader is to allow greater control over what articles to download. -There's not much point in downloading huge amounts of articles, just to -find out that you're not interested in reading any of them. It's better -to be somewhat more conservative in choosing what to download, and then -mark the articles for downloading manually if it should turn out that -you're interested in the articles anyway. - -One of the more effective methods for controlling what is to be -downloaded is to create a @dfn{category} and then assign some (or all) -groups to this category. Groups that do not belong in any other -category belong to the @code{default} category. Gnus has its own -buffer for creating and managing categories. - -If you prefer, you can also use group parameters (@pxref{Group -Parameters}) and topic parameters (@pxref{Topic Parameters}) for an -alternative approach to controlling the agent. The only real -difference is that categories are specific to the agent (so there is -less to learn) while group and topic parameters include the kitchen -sink. - -Since you can set agent parameters in several different places we have -a rule to decide which source to believe. This rule specifies that -the parameter sources are checked in the following order: group -parameters, topic parameters, agent category, and finally customizable -variables. So you can mix all of these sources to produce a wide range -of behavior, just don't blame me if you don't remember where you put -your settings. - -@menu -* Category Syntax:: What a category looks like. -* Category Buffer:: A buffer for maintaining categories. -* Category Variables:: Customize'r'Us. -@end menu - - -@node Category Syntax -@subsubsection Category Syntax - -A category consists of a name, the list of groups belonging to the -category, and a number of optional parameters that override the -customizable variables. The complete list of agent parameters are -listed below. - -@cindex Agent Parameters -@table @code -@item agent-groups -The list of groups that are in this category. - -@item agent-predicate -A predicate which (generally) gives a rough outline of which articles -are eligible for downloading; and - -@item agent-score -a score rule which (generally) gives you a finer granularity when -deciding what articles to download. (Note that this @dfn{download -score} is not necessarily related to normal scores.) - -@item agent-enable-expiration -a boolean indicating whether the agent should expire old articles in -this group. Most groups should be expired to conserve disk space. In -fact, its probably safe to say that the gnus.* hierarchy contains the -only groups that should not be expired. - -@item agent-days-until-old -an integer indicating the number of days that the agent should wait -before deciding that a read article is safe to expire. - -@item agent-low-score -an integer that overrides the value of @code{gnus-agent-low-score}. - -@item agent-high-score -an integer that overrides the value of @code{gnus-agent-high-score}. - -@item agent-short-article -an integer that overrides the value of -@code{gnus-agent-short-article}. - -@item agent-long-article -an integer that overrides the value of @code{gnus-agent-long-article}. - -@item agent-enable-undownloaded-faces -a symbol indicating whether the summary buffer should display -undownloaded articles using the @code{gnus-summary-*-undownloaded-face} -faces. Any symbol other than @code{nil} will enable the use of -undownloaded faces. -@end table - -The name of a category can not be changed once the category has been -created. - -Each category maintains a list of groups that are exclusive members of -that category. The exclusivity rule is automatically enforced, add a -group to a new category and it is automatically removed from its old -category. - -A predicate in its simplest form can be a single predicate such as -@code{true} or @code{false}. These two will download every available -article or nothing respectively. In the case of these two special -predicates an additional score rule is superfluous. - -Predicates of @code{high} or @code{low} download articles in respect of -their scores in relationship to @code{gnus-agent-high-score} and -@code{gnus-agent-low-score} as described below. - -To gain even finer control of what is to be regarded eligible for -download a predicate can consist of a number of predicates with logical -operators sprinkled in between. - -Perhaps some examples are in order. - -Here's a simple predicate. (It's the default predicate, in fact, used -for all groups that don't belong to any other category.) - -@lisp -short -@end lisp - -Quite simple, eh? This predicate is true if and only if the article is -short (for some value of ``short''). - -Here's a more complex predicate: - -@lisp -(or high - (and - (not low) - (not long))) -@end lisp - -This means that an article should be downloaded if it has a high score, -or if the score is not low and the article is not long. You get the -drift. - -The available logical operators are @code{or}, @code{and} and -@code{not}. (If you prefer, you can use the more ``C''-ish operators -@samp{|}, @code{&} and @code{!} instead.) - -The following predicates are pre-defined, but if none of these fit what -you want to do, you can write your own. - -When evaluating each of these predicates, the named constant will be -bound to the value determined by calling -@code{gnus-agent-find-parameter} on the appropriate parameter. For -example, gnus-agent-short-article will be bound to -@code{(gnus-agent-find-parameter group 'agent-short-article)}. This -means that you can specify a predicate in your category then tune that -predicate to individual groups. - -@table @code -@item short -True if the article is shorter than @code{gnus-agent-short-article} -lines; default 100. - -@item long -True if the article is longer than @code{gnus-agent-long-article} -lines; default 200. - -@item low -True if the article has a download score less than -@code{gnus-agent-low-score}; default 0. - -@item high -True if the article has a download score greater than -@code{gnus-agent-high-score}; default 0. - -@item spam -True if the Gnus Agent guesses that the article is spam. The -heuristics may change over time, but at present it just computes a -checksum and sees whether articles match. - -@item true -Always true. - -@item false -Always false. -@end table - -If you want to create your own predicate function, here's what you have -to know: The functions are called with no parameters, but the -@code{gnus-headers} and @code{gnus-score} dynamic variables are bound to -useful values. - -For example, you could decide that you don't want to download articles -that were posted more than a certain number of days ago (e.g. posted -more than @code{gnus-agent-expire-days} ago) you might write a function -something along the lines of the following: - -@lisp -(defun my-article-old-p () - "Say whether an article is old." - (< (time-to-days (date-to-time (mail-header-date gnus-headers))) - (- (time-to-days (current-time)) gnus-agent-expire-days))) -@end lisp - -with the predicate then defined as: - -@lisp -(not my-article-old-p) -@end lisp - -or you could append your predicate to the predefined -@code{gnus-category-predicate-alist} in your @file{~/.gnus.el} or -wherever. - -@lisp -(require 'gnus-agent) -(setq gnus-category-predicate-alist - (append gnus-category-predicate-alist - '((old . my-article-old-p)))) -@end lisp - -and simply specify your predicate as: - -@lisp -(not old) -@end lisp - -If/when using something like the above, be aware that there are many -misconfigured systems/mailers out there and so an article's date is not -always a reliable indication of when it was posted. Hell, some people -just don't give a damn. - -The above predicates apply to @emph{all} the groups which belong to the -category. However, if you wish to have a specific predicate for an -individual group within a category, or you're just too lazy to set up a -new category, you can enter a group's individual predicate in its group -parameters like so: - -@lisp -(agent-predicate . short) -@end lisp - -This is the group/topic parameter equivalent of the agent category default. -Note that when specifying a single word predicate like this, the -@code{agent-predicate} specification must be in dotted pair notation. - -The equivalent of the longer example from above would be: - -@lisp -(agent-predicate or high (and (not low) (not long))) -@end lisp - -The outer parenthesis required in the category specification are not -entered here as, not being in dotted pair notation, the value of the -predicate is assumed to be a list. - - -Now, the syntax of the download score is the same as the syntax of -normal score files, except that all elements that require actually -seeing the article itself are verboten. This means that only the -following headers can be scored on: @code{Subject}, @code{From}, -@code{Date}, @code{Message-ID}, @code{References}, @code{Chars}, -@code{Lines}, and @code{Xref}. - -As with predicates, the specification of the @code{download score rule} -to use in respect of a group can be in either the category definition if -it's to be applicable to all groups in therein, or a group's parameters -if it's to be specific to that group. - -In both of these places the @code{download score rule} can take one of -three forms: - -@enumerate -@item -Score rule - -This has the same syntax as a normal Gnus score file except only a -subset of scoring keywords are available as mentioned above. - -example: - -@itemize @bullet -@item -Category specification - -@lisp -(("from" - ("Lars Ingebrigtsen" 1000000 nil s)) -("lines" - (500 -100 nil <))) -@end lisp - -@item -Group/Topic Parameter specification - -@lisp -(agent-score ("from" - ("Lars Ingebrigtsen" 1000000 nil s)) - ("lines" - (500 -100 nil <))) -@end lisp - -Again, note the omission of the outermost parenthesis here. -@end itemize - -@item -Agent score file - -These score files must @emph{only} contain the permitted scoring -keywords stated above. - -example: - -@itemize @bullet -@item -Category specification - -@lisp -("~/News/agent.SCORE") -@end lisp - -or perhaps - -@lisp -("~/News/agent.SCORE" "~/News/agent.group.SCORE") -@end lisp - -@item -Group Parameter specification - -@lisp -(agent-score "~/News/agent.SCORE") -@end lisp - -Additional score files can be specified as above. Need I say anything -about parenthesis? -@end itemize - -@item -Use @code{normal} score files - -If you don't want to maintain two sets of scoring rules for a group, and -your desired @code{downloading} criteria for a group are the same as your -@code{reading} criteria then you can tell the agent to refer to your -@code{normal} score files when deciding what to download. - -These directives in either the category definition or a group's -parameters will cause the agent to read in all the applicable score -files for a group, @emph{filtering out} those sections that do not -relate to one of the permitted subset of scoring keywords. - -@itemize @bullet -@item -Category Specification - -@lisp -file -@end lisp - -@item -Group Parameter specification - -@lisp -(agent-score . file) -@end lisp -@end itemize -@end enumerate - -@node Category Buffer -@subsubsection Category Buffer - -You'd normally do all category maintenance from the category buffer. -When you enter it for the first time (with the @kbd{J c} command from -the group buffer), you'll only see the @code{default} category. - -The following commands are available in this buffer: - -@table @kbd -@item q -@kindex q (Category) -@findex gnus-category-exit -Return to the group buffer (@code{gnus-category-exit}). - -@item e -@kindex e (Category) -@findex gnus-category-customize-category -Use a customization buffer to set all of the selected category's -parameters at one time (@code{gnus-category-customize-category}). - -@item k -@kindex k (Category) -@findex gnus-category-kill -Kill the current category (@code{gnus-category-kill}). - -@item c -@kindex c (Category) -@findex gnus-category-copy -Copy the current category (@code{gnus-category-copy}). - -@item a -@kindex a (Category) -@findex gnus-category-add -Add a new category (@code{gnus-category-add}). - -@item p -@kindex p (Category) -@findex gnus-category-edit-predicate -Edit the predicate of the current category -(@code{gnus-category-edit-predicate}). - -@item g -@kindex g (Category) -@findex gnus-category-edit-groups -Edit the list of groups belonging to the current category -(@code{gnus-category-edit-groups}). - -@item s -@kindex s (Category) -@findex gnus-category-edit-score -Edit the download score rule of the current category -(@code{gnus-category-edit-score}). - -@item l -@kindex l (Category) -@findex gnus-category-list -List all the categories (@code{gnus-category-list}). -@end table - - -@node Category Variables -@subsubsection Category Variables - -@table @code -@item gnus-category-mode-hook -@vindex gnus-category-mode-hook -Hook run in category buffers. - -@item gnus-category-line-format -@vindex gnus-category-line-format -Format of the lines in the category buffer (@pxref{Formatting -Variables}). Valid elements are: - -@table @samp -@item c -The name of the category. - -@item g -The number of groups in the category. -@end table - -@item gnus-category-mode-line-format -@vindex gnus-category-mode-line-format -Format of the category mode line (@pxref{Mode Line Formatting}). - -@item gnus-agent-short-article -@vindex gnus-agent-short-article -Articles that have fewer lines than this are short. Default 100. - -@item gnus-agent-long-article -@vindex gnus-agent-long-article -Articles that have more lines than this are long. Default 200. - -@item gnus-agent-low-score -@vindex gnus-agent-low-score -Articles that have a score lower than this have a low score. Default -0. - -@item gnus-agent-high-score -@vindex gnus-agent-high-score -Articles that have a score higher than this have a high score. Default -0. - -@item gnus-agent-expire-days -@vindex gnus-agent-expire-days -The number of days that a @samp{read} article must stay in the agent's -local disk before becoming eligible for expiration (While the name is -the same, this doesn't mean expiring the article on the server. It -just means deleting the local copy of the article). What is also -important to understand is that the counter starts with the time the -article was written to the local disk and not the time the article was -read. -Default 7. - -@item gnus-agent-enable-expiration -@vindex gnus-agent-enable-expiration -Determines whether articles in a group are, by default, expired or -retained indefinitely. The default is @code{ENABLE} which means that -you'll have to disable expiration when desired. On the other hand, -you could set this to @code{DISABLE}. In that case, you would then -have to enable expiration in selected groups. - -@end table - - -@node Agent Commands -@subsection Agent Commands -@findex gnus-agent-toggle-plugged -@kindex J j (Agent) - -All the Gnus Agent commands are on the @kbd{J} submap. The @kbd{J j} -(@code{gnus-agent-toggle-plugged}) command works in all modes, and -toggles the plugged/unplugged state of the Gnus Agent. - - -@menu -* Group Agent Commands:: Configure groups and fetch their contents. -* Summary Agent Commands:: Manually select then fetch specific articles. -* Server Agent Commands:: Select the servers that are supported by the agent. -@end menu - - - - -@node Group Agent Commands -@subsubsection Group Agent Commands - -@table @kbd -@item J u -@kindex J u (Agent Group) -@findex gnus-agent-fetch-groups -Fetch all eligible articles in the current group -(@code{gnus-agent-fetch-groups}). - -@item J c -@kindex J c (Agent Group) -@findex gnus-enter-category-buffer -Enter the Agent category buffer (@code{gnus-enter-category-buffer}). - -@item J s -@kindex J s (Agent Group) -@findex gnus-agent-fetch-session -Fetch all eligible articles in all groups -(@code{gnus-agent-fetch-session}). - -@item J S -@kindex J S (Agent Group) -@findex gnus-group-send-queue -Send all sendable messages in the queue group -(@code{gnus-group-send-queue}). @xref{Drafts}. - -@item J a -@kindex J a (Agent Group) -@findex gnus-agent-add-group -Add the current group to an Agent category -(@code{gnus-agent-add-group}). This command understands the -process/prefix convention (@pxref{Process/Prefix}). - -@item J r -@kindex J r (Agent Group) -@findex gnus-agent-remove-group -Remove the current group from its category, if any -(@code{gnus-agent-remove-group}). This command understands the -process/prefix convention (@pxref{Process/Prefix}). - -@item J Y -@kindex J Y (Agent Group) -@findex gnus-agent-synchronize-flags -Synchronize flags changed while unplugged with remote server, if any. - - -@end table - - -@node Summary Agent Commands -@subsubsection Summary Agent Commands - -@table @kbd -@item J # -@kindex J # (Agent Summary) -@findex gnus-agent-mark-article -Mark the article for downloading (@code{gnus-agent-mark-article}). - -@item J M-# -@kindex J M-# (Agent Summary) -@findex gnus-agent-unmark-article -Remove the downloading mark from the article -(@code{gnus-agent-unmark-article}). - -@cindex % -@item @@ -@kindex @@ (Agent Summary) -@findex gnus-agent-toggle-mark -Toggle whether to download the article -(@code{gnus-agent-toggle-mark}). The download mark is @samp{%} by -default. - -@item J c -@kindex J c (Agent Summary) -@findex gnus-agent-catchup -Mark all articles as read (@code{gnus-agent-catchup}) that are neither cached, downloaded, nor downloadable. - -@item J S -@kindex J S (Agent Summary) -@findex gnus-agent-fetch-group -Download all eligible (@pxref{Agent Categories}) articles in this group. -(@code{gnus-agent-fetch-group}). - -@item J s -@kindex J s (Agent Summary) -@findex gnus-agent-summary-fetch-series -Download all processable articles in this group. -(@code{gnus-agent-summary-fetch-series}). - -@item J u -@kindex J u (Agent Summary) -@findex gnus-agent-summary-fetch-group -Download all downloadable articles in the current group -(@code{gnus-agent-summary-fetch-group}). - -@end table - - -@node Server Agent Commands -@subsubsection Server Agent Commands - -@table @kbd -@item J a -@kindex J a (Agent Server) -@findex gnus-agent-add-server -Add the current server to the list of servers covered by the Gnus Agent -(@code{gnus-agent-add-server}). - -@item J r -@kindex J r (Agent Server) -@findex gnus-agent-remove-server -Remove the current server from the list of servers covered by the Gnus -Agent (@code{gnus-agent-remove-server}). - -@end table - - -@node Agent Visuals -@subsection Agent Visuals - -If you open a summary while unplugged and, Gnus knows from the group's -active range that there are more articles than the headers currently -stored in the Agent, you may see some articles whose subject looks -something like @samp{[Undownloaded article #####]}. These are -placeholders for the missing headers. Aside from setting a mark, -there is not much that can be done with one of these placeholders. -When Gnus finally gets a chance to fetch the group's headers, the -placeholders will automatically be replaced by the actual headers. -You can configure the summary buffer's maneuvering to skip over the -placeholders if you care (See @code{gnus-auto-goto-ignores}). - -While it may be obvious to all, the only headers and articles -available while unplugged are those headers and articles that were -fetched into the Agent while previously plugged. To put it another -way, ``If you forget to fetch something while plugged, you might have a -less than satisfying unplugged session''. For this reason, the Agent -adds two visual effects to your summary buffer. These effects display -the download status of each article so that you always know which -articles will be available when unplugged. - -The first visual effect is the @samp{%O} spec. If you customize -@code{gnus-summary-line-format} to include this specifier, you will add -a single character field that indicates an article's download status. -Articles that have been fetched into either the Agent or the Cache, -will display @code{gnus-downloaded-mark} (defaults to @samp{+}). All -other articles will display @code{gnus-undownloaded-mark} (defaults to -@samp{-}). If you open a group that has not been agentized, a space -(@samp{ }) will be displayed. - -The second visual effect are the undownloaded faces. The faces, there -are three indicating the article's score (low, normal, high), seem to -result in a love/hate response from many Gnus users. The problem is -that the face selection is controlled by a list of condition tests and -face names (See @code{gnus-summary-highlight}). Each condition is -tested in the order in which it appears in the list so early -conditions have precedence over later conditions. All of this means -that, if you tick an undownloaded article, the article will continue -to be displayed in the undownloaded face rather than the ticked face. - -If you use the Agent as a cache (to avoid downloading the same article -each time you visit it or to minimize your connection time), the -undownloaded face will probably seem like a good idea. The reason -being that you do all of our work (marking, reading, deleting) with -downloaded articles so the normal faces always appear. For those -users using the agent to improve online performance by caching the NOV -database (most users since 5.10.2), the undownloaded faces may appear -to be an absolutely horrible idea. The issue being that, since none -of their articles have been fetched into the Agent, all of the -normal faces will be obscured by the undownloaded faces. - -If you would like to use the undownloaded faces, you must enable the -undownloaded faces by setting the @code{agent-enable-undownloaded-faces} -group parameter to @code{t}. This parameter, like all other agent -parameters, may be set on an Agent Category (@pxref{Agent Categories}), -a Group Topic (@pxref{Topic Parameters}), or an individual group -(@pxref{Group Parameters}). - -The one problem common to all users using the agent is how quickly it -can consume disk space. If you using the agent on many groups, it is -even more difficult to effectively recover disk space. One solution -is the @samp{%F} format available in @code{gnus-group-line-format}. -This format will display the actual disk space used by articles -fetched into both the agent and cache. By knowing which groups use -the most space, users know where to focus their efforts when ``agent -expiring'' articles. - -@node Agent as Cache -@subsection Agent as Cache - -When Gnus is plugged, it is not efficient to download headers or -articles from the server again, if they are already stored in the -Agent. So, Gnus normally only downloads headers once, and stores them -in the Agent. These headers are later used when generating the summary -buffer, regardless of whether you are plugged or unplugged. Articles -are not cached in the Agent by default though (that would potentially -consume lots of disk space), but if you have already downloaded an -article into the Agent, Gnus will not download the article from the -server again but use the locally stored copy instead. - -If you so desire, you can configure the agent (see @code{gnus-agent-cache} -@pxref{Agent Variables}) to always download headers and articles while -plugged. Gnus will almost certainly be slower, but it will be kept -synchronized with the server. That last point probably won't make any -sense if you are using a nntp or nnimap back end. - -@node Agent Expiry -@subsection Agent Expiry - -@vindex gnus-agent-expire-days -@findex gnus-agent-expire -@kindex M-x gnus-agent-expire -@kindex M-x gnus-agent-expire-group -@findex gnus-agent-expire-group -@cindex agent expiry -@cindex Gnus agent expiry -@cindex expiry, in Gnus agent - -The Agent back end, @code{nnagent}, doesn't handle expiry. Well, at -least it doesn't handle it like other back ends. Instead, there are -special @code{gnus-agent-expire} and @code{gnus-agent-expire-group} -commands that will expire all read articles that are older than -@code{gnus-agent-expire-days} days. They can be run whenever you feel -that you're running out of space. Neither are particularly fast or -efficient, and it's not a particularly good idea to interrupt them (with -@kbd{C-g} or anything else) once you've started one of them. - -Note that other functions might run @code{gnus-agent-expire} for you -to keep the agent synchronized with the group. - -The agent parameter @code{agent-enable-expiration} may be used to -prevent expiration in selected groups. - -@vindex gnus-agent-expire-all -If @code{gnus-agent-expire-all} is non-@code{nil}, the agent -expiration commands will expire all articles---unread, read, ticked -and dormant. If @code{nil} (which is the default), only read articles -are eligible for expiry, and unread, ticked and dormant articles will -be kept indefinitely. - -If you find that some articles eligible for expiry are never expired, -perhaps some Gnus Agent files are corrupted. There's are special -commands, @code{gnus-agent-regenerate} and -@code{gnus-agent-regenerate-group}, to fix possible problems. - -@node Agent Regeneration -@subsection Agent Regeneration - -@cindex agent regeneration -@cindex Gnus agent regeneration -@cindex regeneration - -The local data structures used by @code{nnagent} may become corrupted -due to certain exceptional conditions. When this happens, -@code{nnagent} functionality may degrade or even fail. The solution -to this problem is to repair the local data structures by removing all -internal inconsistencies. - -For example, if your connection to your server is lost while -downloaded articles into the agent, the local data structures will not -know about articles successfully downloaded prior to the connection -failure. Running @code{gnus-agent-regenerate} or -@code{gnus-agent-regenerate-group} will update the data structures -such that you don't need to download these articles a second time. - -@findex gnus-agent-regenerate -@kindex M-x gnus-agent-regenerate -The command @code{gnus-agent-regenerate} will perform -@code{gnus-agent-regenerate-group} on every agentized group. While -you can run @code{gnus-agent-regenerate} in any buffer, it is strongly -recommended that you first close all summary buffers. - -@findex gnus-agent-regenerate-group -@kindex M-x gnus-agent-regenerate-group -The command @code{gnus-agent-regenerate-group} uses the local copies -of individual articles to repair the local @acronym{NOV}(header) database. It -then updates the internal data structures that document which articles -are stored locally. An optional argument will mark articles in the -agent as unread. - -@node Agent and flags -@subsection Agent and flags - -The Agent works with any Gnus back end including those, such as -nnimap, that store flags (read, ticked, etc) on the server. Sadly, -the Agent does not actually know which backends keep their flags in -the backend server rather than in @file{.newsrc}. This means that the -Agent, while unplugged or disconnected, will always record all changes -to the flags in its own files. - -When you plug back in, Gnus will then check to see if you have any -changed any flags and ask if you wish to synchronize these with the -server. This behavior is customizable by @code{gnus-agent-synchronize-flags}. - -@vindex gnus-agent-synchronize-flags -If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will -never automatically synchronize flags. If it is @code{ask}, which is -the default, the Agent will check if you made any changes and if so -ask if you wish to synchronize these when you re-connect. If it has -any other value, all flags will be synchronized automatically. - -If you do not wish to synchronize flags automatically when you -re-connect, you can do it manually with the -@code{gnus-agent-synchronize-flags} command that is bound to @kbd{J Y} -in the group buffer. - -Technical note: the synchronization algorithm does not work by ``pushing'' -all local flags to the server, but rather by incrementally updated the -server view of flags by changing only those flags that were changed by -the user. Thus, if you set one flag on an article, quit the group then -re-select the group and remove the flag; the flag will be set and -removed from the server when you ``synchronize''. The queued flag -operations can be found in the per-server @code{flags} file in the Agent -directory. It's emptied when you synchronize flags. - -@node Agent and IMAP -@subsection Agent and IMAP - -The Agent works with any Gnus back end, including nnimap. However, -since there are some conceptual differences between @acronym{NNTP} and -@acronym{IMAP}, this section (should) provide you with some information to -make Gnus Agent work smoother as a @acronym{IMAP} Disconnected Mode client. - -Some things are currently not implemented in the Agent that you'd might -expect from a disconnected @acronym{IMAP} client, including: - -@itemize @bullet - -@item -Copying/moving articles into nnimap groups when unplugged. - -@item -Creating/deleting nnimap groups when unplugged. - -@end itemize - -@node Outgoing Messages -@subsection Outgoing Messages - -By default, when Gnus is unplugged, all outgoing messages (both mail -and news) are stored in the draft group ``queue'' (@pxref{Drafts}). -You can view them there after posting, and edit them at will. - -You can control the circumstances under which outgoing mail is queued -(see @code{gnus-agent-queue-mail}, @pxref{Agent Variables}). Outgoing -news is always queued when Gnus is unplugged, and never otherwise. - -You can send the messages either from the draft group with the special -commands available there, or you can use the @kbd{J S} command in the -group buffer to send all the sendable messages in the draft group. -Posting news will only work when Gnus is plugged, but you can send -mail at any time. - -If sending mail while unplugged does not work for you and you worry -about hitting @kbd{J S} by accident when unplugged, you can have Gnus -ask you to confirm your action (see -@code{gnus-agent-prompt-send-queue}, @pxref{Agent Variables}). - -@node Agent Variables -@subsection Agent Variables - -@table @code -@item gnus-agent -@vindex gnus-agent -Is the agent enabled? The default is @code{t}. When first enabled, -the agent will use @code{gnus-agent-auto-agentize-methods} to -automatically mark some back ends as agentized. You may change which -back ends are agentized using the agent commands in the server buffer. - -To enter the server buffer, use the @kbd{^} -(@code{gnus-group-enter-server-mode}) command in the group buffer. - - -@item gnus-agent-directory -@vindex gnus-agent-directory -Where the Gnus Agent will store its files. The default is -@file{~/News/agent/}. - -@item gnus-agent-handle-level -@vindex gnus-agent-handle-level -Groups on levels (@pxref{Group Levels}) higher than this variable will -be ignored by the Agent. The default is @code{gnus-level-subscribed}, -which means that only subscribed group will be considered by the Agent -by default. - -@item gnus-agent-plugged-hook -@vindex gnus-agent-plugged-hook -Hook run when connecting to the network. - -@item gnus-agent-unplugged-hook -@vindex gnus-agent-unplugged-hook -Hook run when disconnecting from the network. - -@item gnus-agent-fetched-hook -@vindex gnus-agent-fetched-hook -Hook run when finished fetching articles. - -@item gnus-agent-cache -@vindex gnus-agent-cache -Variable to control whether use the locally stored @acronym{NOV} and -articles when plugged, e.g. essentially using the Agent as a cache. -The default is non-@code{nil}, which means to use the Agent as a cache. - -@item gnus-agent-go-online -@vindex gnus-agent-go-online -If @code{gnus-agent-go-online} is @code{nil}, the Agent will never -automatically switch offline servers into online status. If it is -@code{ask}, the default, the Agent will ask if you wish to switch -offline servers into online status when you re-connect. If it has any -other value, all offline servers will be automatically switched into -online status. - -@item gnus-agent-mark-unread-after-downloaded -@vindex gnus-agent-mark-unread-after-downloaded -If @code{gnus-agent-mark-unread-after-downloaded} is non-@code{nil}, -mark articles as unread after downloading. This is usually a safe -thing to do as the newly downloaded article has obviously not been -read. The default is @code{t}. - -@item gnus-agent-synchronize-flags -@vindex gnus-agent-synchronize-flags -If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will -never automatically synchronize flags. If it is @code{ask}, which is -the default, the Agent will check if you made any changes and if so -ask if you wish to synchronize these when you re-connect. If it has -any other value, all flags will be synchronized automatically. - -@item gnus-agent-consider-all-articles -@vindex gnus-agent-consider-all-articles -If @code{gnus-agent-consider-all-articles} is non-@code{nil}, the -agent will let the agent predicate decide whether articles need to be -downloaded or not, for all articles. When @code{nil}, the default, -the agent will only let the predicate decide whether unread articles -are downloaded or not. If you enable this, you may also want to look -into the agent expiry settings (@pxref{Category Variables}), so that -the agent doesn't download articles which the agent will later expire, -over and over again. - -@item gnus-agent-max-fetch-size -@vindex gnus-agent-max-fetch-size -The agent fetches articles into a temporary buffer prior to parsing -them into individual files. To avoid exceeding the max. buffer size, -the agent alternates between fetching and parsing until all articles -have been fetched. @code{gnus-agent-max-fetch-size} provides a size -limit to control how often the cycling occurs. A large value improves -performance. A small value minimizes the time lost should the -connection be lost while fetching (You may need to run -@code{gnus-agent-regenerate-group} to update the group's state. -However, all articles parsed prior to losing the connection will be -available while unplugged). The default is 10M so it is unusual to -see any cycling. - -@item gnus-server-unopen-status -@vindex gnus-server-unopen-status -Perhaps not an Agent variable, but closely related to the Agent, this -variable says what will happen if Gnus cannot open a server. If the -Agent is enabled, the default, @code{nil}, makes Gnus ask the user -whether to deny the server or whether to unplug the agent. If the -Agent is disabled, Gnus always simply deny the server. Other choices -for this variable include @code{denied} and @code{offline} the latter -is only valid if the Agent is used. - -@item gnus-auto-goto-ignores -@vindex gnus-auto-goto-ignores -Another variable that isn't an Agent variable, yet so closely related -that most will look for it here, this variable tells the summary -buffer how to maneuver around undownloaded (only headers stored in the -agent) and unfetched (neither article nor headers stored) articles. - -The valid values are @code{nil} (maneuver to any article), -@code{undownloaded} (maneuvering while unplugged ignores articles that -have not been fetched), @code{always-undownloaded} (maneuvering always -ignores articles that have not been fetched), @code{unfetched} -(maneuvering ignores articles whose headers have not been fetched). - -@item gnus-agent-queue-mail -@vindex gnus-agent-queue-mail -When @code{gnus-agent-queue-mail} is @code{always}, Gnus will always -queue mail rather than sending it straight away. When @code{t}, Gnus -will queue mail when unplugged only. When @code{nil}, never queue -mail. The default is @code{t}. - -@item gnus-agent-prompt-send-queue -@vindex gnus-agent-prompt-send-queue -When @code{gnus-agent-prompt-send-queue} is non-@code{nil} Gnus will -prompt you to confirm that you really wish to proceed if you hit -@kbd{J S} while unplugged. The default is @code{nil}. - -@item gnus-agent-auto-agentize-methods -@vindex gnus-agent-auto-agentize-methods -If you have never used the Agent before (or more technically, if -@file{~/News/agent/lib/servers} does not exist), Gnus will -automatically agentize a few servers for you. This variable control -which back ends should be auto-agentized. It is typically only useful -to agentize remote back ends. The auto-agentizing has the same effect -as running @kbd{J a} on the servers (@pxref{Server Agent Commands}). -If the file exist, you must manage the servers manually by adding or -removing them, this variable is only applicable the first time you -start Gnus. The default is @samp{nil}. - -@end table - - -@node Example Setup -@subsection Example Setup - -If you don't want to read this manual, and you have a fairly standard -setup, you may be able to use something like the following as your -@file{~/.gnus.el} file to get started. - -@lisp -;; @r{Define how Gnus is to fetch news. We do this over @acronym{NNTP}} -;; @r{from your ISP's server.} -(setq gnus-select-method '(nntp "news.your-isp.com")) - -;; @r{Define how Gnus is to read your mail. We read mail from} -;; @r{your ISP's @acronym{POP} server.} -(setq mail-sources '((pop :server "pop.your-isp.com"))) - -;; @r{Say how Gnus is to store the mail. We use nnml groups.} -(setq gnus-secondary-select-methods '((nnml ""))) - -;; @r{Make Gnus into an offline newsreader.} -;; (gnus-agentize) ; @r{The obsolete setting.} -;; (setq gnus-agent t) ; @r{Now the default.} -@end lisp - -That should be it, basically. Put that in your @file{~/.gnus.el} file, -edit to suit your needs, start up PPP (or whatever), and type @kbd{M-x -gnus}. - -If this is the first time you've run Gnus, you will be subscribed -automatically to a few default newsgroups. You'll probably want to -subscribe to more groups, and to do that, you have to query the -@acronym{NNTP} server for a complete list of groups with the @kbd{A A} -command. This usually takes quite a while, but you only have to do it -once. - -After reading and parsing a while, you'll be presented with a list of -groups. Subscribe to the ones you want to read with the @kbd{u} -command. @kbd{l} to make all the killed groups disappear after you've -subscribe to all the groups you want to read. (@kbd{A k} will bring -back all the killed groups.) - -You can now read the groups at once, or you can download the articles -with the @kbd{J s} command. And then read the rest of this manual to -find out which of the other gazillion things you want to customize. - - -@node Batching Agents -@subsection Batching Agents -@findex gnus-agent-batch - -Having the Gnus Agent fetch articles (and post whatever messages you've -written) is quite easy once you've gotten things set up properly. The -following shell script will do everything that is necessary: - -You can run a complete batch command from the command line with the -following incantation: - -@example -#!/bin/sh -emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-agent-batch >/dev/null 2>&1 -@end example - - -@node Agent Caveats -@subsection Agent Caveats - -The Gnus Agent doesn't seem to work like most other offline -newsreaders. Here are some common questions that some imaginary people -may ask: - -@table @dfn -@item If I read an article while plugged, do they get entered into the Agent? - -@strong{No}. If you want this behavior, add -@code{gnus-agent-fetch-selected-article} to -@code{gnus-select-article-hook}. - -@item If I read an article while plugged, and the article already exists in -the Agent, will it get downloaded once more? - -@strong{No}, unless @code{gnus-agent-cache} is @code{nil}. - -@end table - -In short, when Gnus is unplugged, it only looks into the locally stored -articles; when it's plugged, it talks to your ISP and may also use the -locally stored articles. - - -@node Scoring -@chapter Scoring -@cindex scoring - -Other people use @dfn{kill files}, but we here at Gnus Towers like -scoring better than killing, so we'd rather switch than fight. They do -something completely different as well, so sit up straight and pay -attention! - -@vindex gnus-summary-mark-below -All articles have a default score (@code{gnus-summary-default-score}), -which is 0 by default. This score may be raised or lowered either -interactively or by score files. Articles that have a score lower than -@code{gnus-summary-mark-below} are marked as read. - -Gnus will read any @dfn{score files} that apply to the current group -before generating the summary buffer. - -There are several commands in the summary buffer that insert score -entries based on the current article. You can, for instance, ask Gnus to -lower or increase the score of all articles with a certain subject. - -There are two sorts of scoring entries: Permanent and temporary. -Temporary score entries are self-expiring entries. Any entries that are -temporary and have not been used for, say, a week, will be removed -silently to help keep the sizes of the score files down. - -@menu -* Summary Score Commands:: Adding score entries for the current group. -* Group Score Commands:: General score commands. -* Score Variables:: Customize your scoring. (My, what terminology). -* Score File Format:: What a score file may contain. -* Score File Editing:: You can edit score files by hand as well. -* Adaptive Scoring:: Big Sister Gnus knows what you read. -* Home Score File:: How to say where new score entries are to go. -* Followups To Yourself:: Having Gnus notice when people answer you. -* Scoring On Other Headers:: Scoring on non-standard headers. -* Scoring Tips:: How to score effectively. -* Reverse Scoring:: That problem child of old is not problem. -* Global Score Files:: Earth-spanning, ear-splitting score files. -* Kill Files:: They are still here, but they can be ignored. -* Converting Kill Files:: Translating kill files to score files. -* Advanced Scoring:: Using logical expressions to build score rules. -* Score Decays:: It can be useful to let scores wither away. -@end menu - - -@node Summary Score Commands -@section Summary Score Commands -@cindex score commands - -The score commands that alter score entries do not actually modify real -score files. That would be too inefficient. Gnus maintains a cache of -previously loaded score files, one of which is considered the -@dfn{current score file alist}. The score commands simply insert -entries into this list, and upon group exit, this list is saved. - -The current score file is by default the group's local score file, even -if no such score file actually exists. To insert score commands into -some other score file (e.g. @file{all.SCORE}), you must first make this -score file the current one. - -General score commands that don't actually change the score file: - -@table @kbd - -@item V s -@kindex V s (Summary) -@findex gnus-summary-set-score -Set the score of the current article (@code{gnus-summary-set-score}). - -@item V S -@kindex V S (Summary) -@findex gnus-summary-current-score -Display the score of the current article -(@code{gnus-summary-current-score}). - -@item V t -@kindex V t (Summary) -@findex gnus-score-find-trace -Display all score rules that have been used on the current article -(@code{gnus-score-find-trace}). In the @code{*Score Trace*} buffer, you -may type @kbd{e} to edit score file corresponding to the score rule on -current line and @kbd{f} to format (@code{gnus-score-pretty-print}) the -score file and edit it. - -@item V w -@kindex V w (Summary) -@findex gnus-score-find-favourite-words -List words used in scoring (@code{gnus-score-find-favourite-words}). - -@item V R -@kindex V R (Summary) -@findex gnus-summary-rescore -Run the current summary through the scoring process -(@code{gnus-summary-rescore}). This might be useful if you're playing -around with your score files behind Gnus' back and want to see the -effect you're having. - -@item V c -@kindex V c (Summary) -@findex gnus-score-change-score-file -Make a different score file the current -(@code{gnus-score-change-score-file}). - -@item V e -@kindex V e (Summary) -@findex gnus-score-edit-current-scores -Edit the current score file (@code{gnus-score-edit-current-scores}). -You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score -File Editing}). - -@item V f -@kindex V f (Summary) -@findex gnus-score-edit-file -Edit a score file and make this score file the current one -(@code{gnus-score-edit-file}). - -@item V F -@kindex V F (Summary) -@findex gnus-score-flush-cache -Flush the score cache (@code{gnus-score-flush-cache}). This is useful -after editing score files. - -@item V C -@kindex V C (Summary) -@findex gnus-score-customize -Customize a score file in a visually pleasing manner -(@code{gnus-score-customize}). - -@end table - -The rest of these commands modify the local score file. - -@table @kbd - -@item V m -@kindex V m (Summary) -@findex gnus-score-set-mark-below -Prompt for a score, and mark all articles with a score below this as -read (@code{gnus-score-set-mark-below}). - -@item V x -@kindex V x (Summary) -@findex gnus-score-set-expunge-below -Prompt for a score, and add a score rule to the current score file to -expunge all articles below this score -(@code{gnus-score-set-expunge-below}). -@end table - -The keystrokes for actually making score entries follow a very regular -pattern, so there's no need to list all the commands. (Hundreds of -them.) - -@findex gnus-summary-increase-score -@findex gnus-summary-lower-score - -@enumerate -@item -The first key is either @kbd{I} (upper case i) for increasing the score -or @kbd{L} for lowering the score. -@item -The second key says what header you want to score on. The following -keys are available: -@table @kbd - -@item a -Score on the author name. - -@item s -Score on the subject line. - -@item x -Score on the @code{Xref} line---i.e., the cross-posting line. - -@item r -Score on the @code{References} line. - -@item d -Score on the date. - -@item l -Score on the number of lines. - -@item i -Score on the @code{Message-ID} header. - -@item e -Score on an ``extra'' header, that is, one of those in gnus-extra-headers, -if your @acronym{NNTP} server tracks additional header data in overviews. - -@item f -Score on followups---this matches the author name, and adds scores to -the followups to this author. (Using this key leads to the creation of -@file{ADAPT} files.) - -@item b -Score on the body. - -@item h -Score on the head. - -@item t -Score on thread. (Using this key leads to the creation of @file{ADAPT} -files.) - -@end table - -@item -The third key is the match type. Which match types are valid depends on -what headers you are scoring on. - -@table @code - -@item strings - -@table @kbd - -@item e -Exact matching. - -@item s -Substring matching. - -@item f -Fuzzy matching (@pxref{Fuzzy Matching}). - -@item r -Regexp matching -@end table - -@item date -@table @kbd - -@item b -Before date. - -@item a -After date. - -@item n -This date. -@end table - -@item number -@table @kbd - -@item < -Less than number. - -@item = -Equal to number. - -@item > -Greater than number. -@end table -@end table - -@item -The fourth and usually final key says whether this is a temporary (i.e., -expiring) score entry, or a permanent (i.e., non-expiring) score entry, -or whether it is to be done immediately, without adding to the score -file. -@table @kbd - -@item t -Temporary score entry. - -@item p -Permanent score entry. - -@item i -Immediately scoring. -@end table - -@item -If you are scoring on `e' (extra) headers, you will then be prompted for -the header name on which you wish to score. This must be a header named -in gnus-extra-headers, and @samp{TAB} completion is available. - -@end enumerate - -So, let's say you want to increase the score on the current author with -exact matching permanently: @kbd{I a e p}. If you want to lower the -score based on the subject line, using substring matching, and make a -temporary score entry: @kbd{L s s t}. Pretty easy. - -To make things a bit more complicated, there are shortcuts. If you use -a capital letter on either the second or third keys, Gnus will use -defaults for the remaining one or two keystrokes. The defaults are -``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s -t}, and @kbd{I a R} is the same as @kbd{I a r t}. - -These functions take both the numerical prefix and the symbolic prefix -(@pxref{Symbolic Prefixes}). A numerical prefix says how much to lower -(or increase) the score of the article. A symbolic prefix of @code{a} -says to use the @file{all.SCORE} file for the command instead of the -current score file. - -@vindex gnus-score-mimic-keymap -The @code{gnus-score-mimic-keymap} says whether these commands will -pretend they are keymaps or not. - - -@node Group Score Commands -@section Group Score Commands -@cindex group score commands - -There aren't many of these as yet, I'm afraid. - -@table @kbd - -@item W e -@kindex W e (Group) -@findex gnus-score-edit-all-score -Edit the apply-to-all-groups all.SCORE file. You will be popped into -a @code{gnus-score-mode} buffer (@pxref{Score File Editing}). - -@item W f -@kindex W f (Group) -@findex gnus-score-flush-cache -Gnus maintains a cache of score alists to avoid having to reload them -all the time. This command will flush the cache -(@code{gnus-score-flush-cache}). - -@end table - -You can do scoring from the command line by saying something like: - -@findex gnus-batch-score -@cindex batch scoring -@example -$ emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-batch-score -@end example - - -@node Score Variables -@section Score Variables -@cindex score variables - -@table @code - -@item gnus-use-scoring -@vindex gnus-use-scoring -If @code{nil}, Gnus will not check for score files, and will not, in -general, do any score-related work. This is @code{t} by default. - -@item gnus-kill-killed -@vindex gnus-kill-killed -If this variable is @code{nil}, Gnus will never apply score files to -articles that have already been through the kill process. While this -may save you lots of time, it also means that if you apply a kill file -to a group, and then change the kill file and want to run it over you -group again to kill more articles, it won't work. You have to set this -variable to @code{t} to do that. (It is @code{t} by default.) - -@item gnus-kill-files-directory -@vindex gnus-kill-files-directory -All kill and score files will be stored in this directory, which is -initialized from the @env{SAVEDIR} environment variable by default. -This is @file{~/News/} by default. - -@item gnus-score-file-suffix -@vindex gnus-score-file-suffix -Suffix to add to the group name to arrive at the score file name -(@file{SCORE} by default.) - -@item gnus-score-uncacheable-files -@vindex gnus-score-uncacheable-files -@cindex score cache -All score files are normally cached to avoid excessive re-loading of -score files. However, this might make your Emacs grow big and -bloated, so this regexp can be used to weed out score files unlikely -to be needed again. It would be a bad idea to deny caching of -@file{all.SCORE}, while it might be a good idea to not cache -@file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this -variable is @samp{ADAPT$} by default, so no adaptive score files will -be cached. - -@item gnus-save-score -@vindex gnus-save-score -If you have really complicated score files, and do lots of batch -scoring, then you might set this variable to @code{t}. This will make -Gnus save the scores into the @file{.newsrc.eld} file. - -If you do not set this to @code{t}, then manual scores (like those set -with @kbd{V s} (@code{gnus-summary-set-score})) will not be preserved -across group visits. - -@item gnus-score-interactive-default-score -@vindex gnus-score-interactive-default-score -Score used by all the interactive raise/lower commands to raise/lower -score with. Default is 1000, which may seem excessive, but this is to -ensure that the adaptive scoring scheme gets enough room to play with. -We don't want the small changes from the adaptive scoring to overwrite -manually entered data. - -@item gnus-summary-default-score -@vindex gnus-summary-default-score -Default score of an article, which is 0 by default. - -@item gnus-summary-expunge-below -@vindex gnus-summary-expunge-below -Don't display the summary lines of articles that have scores lower than -this variable. This is @code{nil} by default, which means that no -articles will be hidden. This variable is local to the summary buffers, -and has to be set from @code{gnus-summary-mode-hook}. - -@item gnus-score-over-mark -@vindex gnus-score-over-mark -Mark (in the third column) used for articles with a score over the -default. Default is @samp{+}. - -@item gnus-score-below-mark -@vindex gnus-score-below-mark -Mark (in the third column) used for articles with a score below the -default. Default is @samp{-}. - -@item gnus-score-find-score-files-function -@vindex gnus-score-find-score-files-function -Function used to find score files for the current group. This function -is called with the name of the group as the argument. - -Predefined functions available are: -@table @code - -@item gnus-score-find-single -@findex gnus-score-find-single -Only apply the group's own score file. - -@item gnus-score-find-bnews -@findex gnus-score-find-bnews -Apply all score files that match, using bnews syntax. This is the -default. If the current group is @samp{gnu.emacs.gnus}, for instance, -@file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and -@file{gnu.all.SCORE} would all apply. In short, the instances of -@samp{all} in the score file names are translated into @samp{.*}, and -then a regexp match is done. - -This means that if you have some score entries that you want to apply to -all groups, then you put those entries in the @file{all.SCORE} file. - -The score files are applied in a semi-random order, although Gnus will -try to apply the more general score files before the more specific score -files. It does this by looking at the number of elements in the score -file names---discarding the @samp{all} elements. - -@item gnus-score-find-hierarchical -@findex gnus-score-find-hierarchical -Apply all score files from all the parent groups. This means that you -can't have score files like @file{all.SCORE}, but you can have -@file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE} for each -server. - -@end table -This variable can also be a list of functions. In that case, all -these functions will be called with the group name as argument, and -all the returned lists of score files will be applied. These -functions can also return lists of lists of score alists directly. In -that case, the functions that return these non-file score alists -should probably be placed before the ``real'' score file functions, to -ensure that the last score file returned is the local score file. -Phu. - -For example, to do hierarchical scoring but use a non-server-specific -overall score file, you could use the value -@example -(list (lambda (group) ("all.SCORE")) - 'gnus-score-find-hierarchical) -@end example - -@item gnus-score-expiry-days -@vindex gnus-score-expiry-days -This variable says how many days should pass before an unused score file -entry is expired. If this variable is @code{nil}, no score file entries -are expired. It's 7 by default. - -@item gnus-update-score-entry-dates -@vindex gnus-update-score-entry-dates -If this variable is non-@code{nil}, temporary score entries that have -been triggered (matched) will have their dates updated. (This is how Gnus -controls expiry---all non-matched-entries will become too old while -matched entries will stay fresh and young.) However, if you set this -variable to @code{nil}, even matched entries will grow old and will -have to face that oh-so grim reaper. - -@item gnus-score-after-write-file-function -@vindex gnus-score-after-write-file-function -Function called with the name of the score file just written. - -@item gnus-score-thread-simplify -@vindex gnus-score-thread-simplify -If this variable is non-@code{nil}, article subjects will be -simplified for subject scoring purposes in the same manner as with -threading---according to the current value of -@code{gnus-simplify-subject-functions}. If the scoring entry uses -@code{substring} or @code{exact} matching, the match will also be -simplified in this manner. - -@end table - - -@node Score File Format -@section Score File Format -@cindex score file format - -A score file is an @code{emacs-lisp} file that normally contains just a -single form. Casual users are not expected to edit these files; -everything can be changed from the summary buffer. - -Anyway, if you'd like to dig into it yourself, here's an example: - -@lisp -(("from" - ("Lars Ingebrigtsen" -10000) - ("Per Abrahamsen") - ("larsi\\|lmi" -50000 nil R)) - ("subject" - ("Ding is Badd" nil 728373)) - ("xref" - ("alt.politics" -1000 728372 s)) - ("lines" - (2 -100 nil <)) - (mark 0) - (expunge -1000) - (mark-and-expunge -10) - (read-only nil) - (orphan -10) - (adapt t) - (files "/hom/larsi/News/gnu.SCORE") - (exclude-files "all.SCORE") - (local (gnus-newsgroup-auto-expire t) - (gnus-summary-make-false-root empty)) - (eval (ding))) -@end lisp - -This example demonstrates most score file elements. @xref{Advanced -Scoring}, for a different approach. - -Even though this looks much like Lisp code, nothing here is actually -@code{eval}ed. The Lisp reader is used to read this form, though, so it -has to be valid syntactically, if not semantically. - -Six keys are supported by this alist: - -@table @code - -@item STRING -If the key is a string, it is the name of the header to perform the -match on. Scoring can only be performed on these eight headers: -@code{From}, @code{Subject}, @code{References}, @code{Message-ID}, -@code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to -these headers, there are three strings to tell Gnus to fetch the entire -article and do the match on larger parts of the article: @code{Body} -will perform the match on the body of the article, @code{Head} will -perform the match on the head of the article, and @code{All} will -perform the match on the entire article. Note that using any of these -last three keys will slow down group entry @emph{considerably}. The -final ``header'' you can score on is @code{Followup}. These score -entries will result in new score entries being added for all follow-ups -to articles that matches these score entries. - -Following this key is an arbitrary number of score entries, where each -score entry has one to four elements. -@enumerate - -@item -The first element is the @dfn{match element}. On most headers this will -be a string, but on the Lines and Chars headers, this must be an -integer. - -@item -If the second element is present, it should be a number---the @dfn{score -element}. This number should be an integer in the neginf to posinf -interval. This number is added to the score of the article if the match -is successful. If this element is not present, the -@code{gnus-score-interactive-default-score} number will be used -instead. This is 1000 by default. - -@item -If the third element is present, it should be a number---the @dfn{date -element}. This date says when the last time this score entry matched, -which provides a mechanism for expiring the score entries. It this -element is not present, the score entry is permanent. The date is -represented by the number of days since December 31, 1 BCE. - -@item -If the fourth element is present, it should be a symbol---the @dfn{type -element}. This element specifies what function should be used to see -whether this score entry matches the article. What match types that can -be used depends on what header you wish to perform the match on. -@table @dfn - -@item From, Subject, References, Xref, Message-ID -For most header types, there are the @code{r} and @code{R} (regexp), as -well as @code{s} and @code{S} (substring) types, and @code{e} and -@code{E} (exact match), and @code{w} (word match) types. If this -element is not present, Gnus will assume that substring matching should -be used. @code{R}, @code{S}, and @code{E} differ from the others in -that the matches will be done in a case-sensitive manner. All these -one-letter types are really just abbreviations for the @code{regexp}, -@code{string}, @code{exact}, and @code{word} types, which you can use -instead, if you feel like. - -@item Extra -Just as for the standard string overview headers, if you are using -gnus-extra-headers, you can score on these headers' values. In this -case, there is a 5th element in the score entry, being the name of the -header to be scored. The following entry is useful in your -@file{all.SCORE} file in case of spam attacks from a single origin -host, if your @acronym{NNTP} server tracks @samp{NNTP-Posting-Host} in -overviews: - -@lisp -("111.222.333.444" -1000 nil s - "NNTP-Posting-Host") -@end lisp - -@item Lines, Chars -These two headers use different match types: @code{<}, @code{>}, -@code{=}, @code{>=} and @code{<=}. - -These predicates are true if - -@example -(PREDICATE HEADER MATCH) -@end example - -evaluates to non-@code{nil}. For instance, the advanced match -@code{("lines" 4 <)} (@pxref{Advanced Scoring}) will result in the -following form: - -@lisp -(< header-value 4) -@end lisp - -Or to put it another way: When using @code{<} on @code{Lines} with 4 as -the match, we get the score added if the article has less than 4 lines. -(It's easy to get confused and think it's the other way around. But -it's not. I think.) - -When matching on @code{Lines}, be careful because some back ends (like -@code{nndir}) do not generate @code{Lines} header, so every article ends -up being marked as having 0 lines. This can lead to strange results if -you happen to lower score of the articles with few lines. - -@item Date -For the Date header we have three kinda silly match types: -@code{before}, @code{at} and @code{after}. I can't really imagine this -ever being useful, but, like, it would feel kinda silly not to provide -this function. Just in case. You never know. Better safe than sorry. -Once burnt, twice shy. Don't judge a book by its cover. Never not have -sex on a first date. (I have been told that at least one person, and I -quote, ``found this function indispensable'', however.) - -@cindex ISO8601 -@cindex date -A more useful match type is @code{regexp}. With it, you can match the -date string using a regular expression. The date is normalized to -ISO8601 compact format first---@var{YYYYMMDD}@code{T}@var{HHMMSS}. If -you want to match all articles that have been posted on April 1st in -every year, you could use @samp{....0401.........} as a match string, -for instance. (Note that the date is kept in its original time zone, so -this will match articles that were posted when it was April 1st where -the article was posted from. Time zones are such wholesome fun for the -whole family, eh?) - -@item Head, Body, All -These three match keys use the same match types as the @code{From} (etc) -header uses. - -@item Followup -This match key is somewhat special, in that it will match the -@code{From} header, and affect the score of not only the matching -articles, but also all followups to the matching articles. This allows -you e.g. increase the score of followups to your own articles, or -decrease the score of followups to the articles of some known -trouble-maker. Uses the same match types as the @code{From} header -uses. (Using this match key will lead to creation of @file{ADAPT} -files.) - -@item Thread -This match key works along the same lines as the @code{Followup} match -key. If you say that you want to score on a (sub-)thread started by an -article with a @code{Message-ID} @var{x}, then you add a @samp{thread} -match. This will add a new @samp{thread} match for each article that -has @var{x} in its @code{References} header. (These new @samp{thread} -matches will use the @code{Message-ID}s of these matching articles.) -This will ensure that you can raise/lower the score of an entire thread, -even though some articles in the thread may not have complete -@code{References} headers. Note that using this may lead to -nondeterministic scores of the articles in the thread. (Using this match -key will lead to creation of @file{ADAPT} files.) -@end table -@end enumerate - -@cindex score file atoms -@item mark -The value of this entry should be a number. Any articles with a score -lower than this number will be marked as read. - -@item expunge -The value of this entry should be a number. Any articles with a score -lower than this number will be removed from the summary buffer. - -@item mark-and-expunge -The value of this entry should be a number. Any articles with a score -lower than this number will be marked as read and removed from the -summary buffer. - -@item thread-mark-and-expunge -The value of this entry should be a number. All articles that belong to -a thread that has a total score below this number will be marked as read -and removed from the summary buffer. @code{gnus-thread-score-function} -says how to compute the total score for a thread. - -@item files -The value of this entry should be any number of file names. These files -are assumed to be score files as well, and will be loaded the same way -this one was. - -@item exclude-files -The clue of this entry should be any number of files. These files will -not be loaded, even though they would normally be so, for some reason or -other. - -@item eval -The value of this entry will be @code{eval}ed. This element will be -ignored when handling global score files. - -@item read-only -Read-only score files will not be updated or saved. Global score files -should feature this atom (@pxref{Global Score Files}). (Note: -@dfn{Global} here really means @dfn{global}; not your personal -apply-to-all-groups score files.) - -@item orphan -The value of this entry should be a number. Articles that do not have -parents will get this number added to their scores. Imagine you follow -some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you -will only follow a few of the threads, also want to see any new threads. - -You can do this with the following two score file entries: - -@example - (orphan -500) - (mark-and-expunge -100) -@end example - -When you enter the group the first time, you will only see the new -threads. You then raise the score of the threads that you find -interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{c y}) the -rest. Next time you enter the group, you will see new articles in the -interesting threads, plus any new threads. - -I.e.---the orphan score atom is for high-volume groups where a few -interesting threads which can't be found automatically by ordinary -scoring rules exist. - -@item adapt -This entry controls the adaptive scoring. If it is @code{t}, the -default adaptive scoring rules will be used. If it is @code{ignore}, no -adaptive scoring will be performed on this group. If it is a list, this -list will be used as the adaptive scoring rules. If it isn't present, -or is something other than @code{t} or @code{ignore}, the default -adaptive scoring rules will be used. If you want to use adaptive -scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to -@code{t}, and insert an @code{(adapt ignore)} in the groups where you do -not want adaptive scoring. If you only want adaptive scoring in a few -groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and -insert @code{(adapt t)} in the score files of the groups where you want -it. - -@item adapt-file -All adaptive score entries will go to the file named by this entry. It -will also be applied when entering the group. This atom might be handy -if you want to adapt on several groups at once, using the same adaptive -file for a number of groups. - -@item local -@cindex local variables -The value of this entry should be a list of @code{(@var{var} -@var{value})} pairs. Each @var{var} will be made buffer-local to the -current summary buffer, and set to the value specified. This is a -convenient, if somewhat strange, way of setting variables in some -groups if you don't like hooks much. Note that the @var{value} won't -be evaluated. -@end table - - -@node Score File Editing -@section Score File Editing - -You normally enter all scoring commands from the summary buffer, but you -might feel the urge to edit them by hand as well, so we've supplied you -with a mode for that. - -It's simply a slightly customized @code{emacs-lisp} mode, with these -additional commands: - -@table @kbd - -@item C-c C-c -@kindex C-c C-c (Score) -@findex gnus-score-edit-exit -Save the changes you have made and return to the summary buffer -(@code{gnus-score-edit-exit}). - -@item C-c C-d -@kindex C-c C-d (Score) -@findex gnus-score-edit-insert-date -Insert the current date in numerical format -(@code{gnus-score-edit-insert-date}). This is really the day number, if -you were wondering. - -@item C-c C-p -@kindex C-c C-p (Score) -@findex gnus-score-pretty-print -The adaptive score files are saved in an unformatted fashion. If you -intend to read one of these files, you want to @dfn{pretty print} it -first. This command (@code{gnus-score-pretty-print}) does that for -you. - -@end table - -Type @kbd{M-x gnus-score-mode} to use this mode. - -@vindex gnus-score-mode-hook -@code{gnus-score-menu-hook} is run in score mode buffers. - -In the summary buffer you can use commands like @kbd{V f}, @kbd{V e} and -@kbd{V t} to begin editing score files. - - -@node Adaptive Scoring -@section Adaptive Scoring -@cindex adaptive scoring - -If all this scoring is getting you down, Gnus has a way of making it all -happen automatically---as if by magic. Or rather, as if by artificial -stupidity, to be precise. - -@vindex gnus-use-adaptive-scoring -When you read an article, or mark an article as read, or kill an -article, you leave marks behind. On exit from the group, Gnus can sniff -these marks and add score elements depending on what marks it finds. -You turn on this ability by setting @code{gnus-use-adaptive-scoring} to -@code{t} or @code{(line)}. If you want score adaptively on separate -words appearing in the subjects, you should set this variable to -@code{(word)}. If you want to use both adaptive methods, set this -variable to @code{(word line)}. - -@vindex gnus-default-adaptive-score-alist -To give you complete control over the scoring process, you can customize -the @code{gnus-default-adaptive-score-alist} variable. For instance, it -might look something like this: - -@lisp -(setq gnus-default-adaptive-score-alist - '((gnus-unread-mark) - (gnus-ticked-mark (from 4)) - (gnus-dormant-mark (from 5)) - (gnus-del-mark (from -4) (subject -1)) - (gnus-read-mark (from 4) (subject 2)) - (gnus-expirable-mark (from -1) (subject -1)) - (gnus-killed-mark (from -1) (subject -3)) - (gnus-kill-file-mark) - (gnus-ancient-mark) - (gnus-low-score-mark) - (gnus-catchup-mark (from -1) (subject -1)))) -@end lisp - -As you see, each element in this alist has a mark as a key (either a -variable name or a ``real'' mark---a character). Following this key is -a arbitrary number of header/score pairs. If there are no header/score -pairs following the key, no adaptive scoring will be done on articles -that have that key as the article mark. For instance, articles with -@code{gnus-unread-mark} in the example above will not get adaptive score -entries. - -Each article can have only one mark, so just a single of these rules -will be applied to each article. - -To take @code{gnus-del-mark} as an example---this alist says that all -articles that have that mark (i.e., are marked with @samp{e}) will have a -score entry added to lower based on the @code{From} header by -4, and -lowered by @code{Subject} by -1. Change this to fit your prejudices. - -If you have marked 10 articles with the same subject with -@code{gnus-del-mark}, the rule for that mark will be applied ten times. -That means that that subject will get a score of ten times -1, which -should be, unless I'm much mistaken, -10. - -If you have auto-expirable (mail) groups (@pxref{Expiring Mail}), all -the read articles will be marked with the @samp{E} mark. This'll -probably make adaptive scoring slightly impossible, so auto-expiring and -adaptive scoring doesn't really mix very well. - -The headers you can score on are @code{from}, @code{subject}, -@code{message-id}, @code{references}, @code{xref}, @code{lines}, -@code{chars} and @code{date}. In addition, you can score on -@code{followup}, which will create an adaptive score entry that matches -on the @code{References} header using the @code{Message-ID} of the -current article, thereby matching the following thread. - -If you use this scheme, you should set the score file atom @code{mark} -to something small---like -300, perhaps, to avoid having small random -changes result in articles getting marked as read. - -After using adaptive scoring for a week or so, Gnus should start to -become properly trained and enhance the authors you like best, and kill -the authors you like least, without you having to say so explicitly. - -You can control what groups the adaptive scoring is to be performed on -by using the score files (@pxref{Score File Format}). This will also -let you use different rules in different groups. - -@vindex gnus-adaptive-file-suffix -The adaptive score entries will be put into a file where the name is the -group name with @code{gnus-adaptive-file-suffix} appended. The default -is @file{ADAPT}. - -@vindex gnus-adaptive-pretty-print -Adaptive score files can get huge and are not meant to be edited by -human hands. If @code{gnus-adaptive-pretty-print} is @code{nil} (the -default) those files will not be written in a human readable way. - -@vindex gnus-score-exact-adapt-limit -When doing adaptive scoring, substring or fuzzy matching would probably -give you the best results in most cases. However, if the header one -matches is short, the possibility for false positives is great, so if -the length of the match is less than -@code{gnus-score-exact-adapt-limit}, exact matching will be used. If -this variable is @code{nil}, exact matching will always be used to avoid -this problem. - -@vindex gnus-default-adaptive-word-score-alist -As mentioned above, you can adapt either on individual words or entire -headers. If you adapt on words, the -@code{gnus-default-adaptive-word-score-alist} variable says what score -each instance of a word should add given a mark. - -@lisp -(setq gnus-default-adaptive-word-score-alist - `((,gnus-read-mark . 30) - (,gnus-catchup-mark . -10) - (,gnus-killed-mark . -20) - (,gnus-del-mark . -15))) -@end lisp - -This is the default value. If you have adaption on words enabled, every -word that appears in subjects of articles marked with -@code{gnus-read-mark} will result in a score rule that increase the -score with 30 points. - -@vindex gnus-default-ignored-adaptive-words -@vindex gnus-ignored-adaptive-words -Words that appear in the @code{gnus-default-ignored-adaptive-words} list -will be ignored. If you wish to add more words to be ignored, use the -@code{gnus-ignored-adaptive-words} list instead. - -@vindex gnus-adaptive-word-length-limit -Some may feel that short words shouldn't count when doing adaptive -scoring. If so, you may set @code{gnus-adaptive-word-length-limit} to -an integer. Words shorter than this number will be ignored. This -variable defaults to @code{nil}. - -@vindex gnus-adaptive-word-syntax-table -When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the -syntax table in effect. It is similar to the standard syntax table, but -it considers numbers to be non-word-constituent characters. - -@vindex gnus-adaptive-word-minimum -If @code{gnus-adaptive-word-minimum} is set to a number, the adaptive -word scoring process will never bring down the score of an article to -below this number. The default is @code{nil}. - -@vindex gnus-adaptive-word-no-group-words -If @code{gnus-adaptive-word-no-group-words} is set to @code{t}, gnus -won't adaptively word score any of the words in the group name. Useful -for groups like @samp{comp.editors.emacs}, where most of the subject -lines contain the word @samp{emacs}. - -After using this scheme for a while, it might be nice to write a -@code{gnus-psychoanalyze-user} command to go through the rules and see -what words you like and what words you don't like. Or perhaps not. - -Note that the adaptive word scoring thing is highly experimental and is -likely to change in the future. Initial impressions seem to indicate -that it's totally useless as it stands. Some more work (involving more -rigorous statistical methods) will have to be done to make this useful. - - -@node Home Score File -@section Home Score File - -The score file where new score file entries will go is called the -@dfn{home score file}. This is normally (and by default) the score file -for the group itself. For instance, the home score file for -@samp{gnu.emacs.gnus} is @file{gnu.emacs.gnus.SCORE}. - -However, this may not be what you want. It is often convenient to share -a common home score file among many groups---all @samp{emacs} groups -could perhaps use the same home score file. - -@vindex gnus-home-score-file -The variable that controls this is @code{gnus-home-score-file}. It can -be: - -@enumerate -@item -A string. Then this file will be used as the home score file for all -groups. - -@item -A function. The result of this function will be used as the home score -file. The function will be called with the name of the group as the -parameter. - -@item -A list. The elements in this list can be: - -@enumerate -@item -@code{(@var{regexp} @var{file-name})}. If the @var{regexp} matches the -group name, the @var{file-name} will be used as the home score file. - -@item -A function. If the function returns non-@code{nil}, the result will -be used as the home score file. The function will be called with the -name of the group as the parameter. - -@item -A string. Use the string as the home score file. -@end enumerate - -The list will be traversed from the beginning towards the end looking -for matches. - -@end enumerate - -So, if you want to use just a single score file, you could say: - -@lisp -(setq gnus-home-score-file - "my-total-score-file.SCORE") -@end lisp - -If you want to use @file{gnu.SCORE} for all @samp{gnu} groups and -@file{rec.SCORE} for all @samp{rec} groups (and so on), you can say: - -@findex gnus-hierarchial-home-score-file -@lisp -(setq gnus-home-score-file - 'gnus-hierarchial-home-score-file) -@end lisp - -This is a ready-made function provided for your convenience. -Other functions include - -@table @code -@item gnus-current-home-score-file -@findex gnus-current-home-score-file -Return the ``current'' regular score file. This will make scoring -commands add entry to the ``innermost'' matching score file. - -@end table - -If you want to have one score file for the @samp{emacs} groups and -another for the @samp{comp} groups, while letting all other groups use -their own home score files: - -@lisp -(setq gnus-home-score-file - ;; @r{All groups that match the regexp @code{"\\.emacs"}} - '(("\\.emacs" "emacs.SCORE") - ;; @r{All the comp groups in one score file} - ("^comp" "comp.SCORE"))) -@end lisp - -@vindex gnus-home-adapt-file -@code{gnus-home-adapt-file} works exactly the same way as -@code{gnus-home-score-file}, but says what the home adaptive score file -is instead. All new adaptive file entries will go into the file -specified by this variable, and the same syntax is allowed. - -In addition to using @code{gnus-home-score-file} and -@code{gnus-home-adapt-file}, you can also use group parameters -(@pxref{Group Parameters}) and topic parameters (@pxref{Topic -Parameters}) to achieve much the same. Group and topic parameters take -precedence over this variable. - - -@node Followups To Yourself -@section Followups To Yourself - -Gnus offers two commands for picking out the @code{Message-ID} header in -the current buffer. Gnus will then add a score rule that scores using -this @code{Message-ID} on the @code{References} header of other -articles. This will, in effect, increase the score of all articles that -respond to the article in the current buffer. Quite useful if you want -to easily note when people answer what you've said. - -@table @code - -@item gnus-score-followup-article -@findex gnus-score-followup-article -This will add a score to articles that directly follow up your own -article. - -@item gnus-score-followup-thread -@findex gnus-score-followup-thread -This will add a score to all articles that appear in a thread ``below'' -your own article. -@end table - -@vindex message-sent-hook -These two functions are both primarily meant to be used in hooks like -@code{message-sent-hook}, like this: -@lisp -(add-hook 'message-sent-hook 'gnus-score-followup-thread) -@end lisp - - -If you look closely at your own @code{Message-ID}, you'll notice that -the first two or three characters are always the same. Here's two of -mine: - -@example - - -@end example - -So ``my'' ident on this machine is @samp{x6}. This can be -exploited---the following rule will raise the score on all followups to -myself: - -@lisp -("references" - ("" - 1000 nil r)) -@end lisp - -Whether it's the first two or first three characters that are ``yours'' -is system-dependent. - - -@node Scoring On Other Headers -@section Scoring On Other Headers -@cindex scoring on other headers - -Gnus is quite fast when scoring the ``traditional'' -headers---@samp{From}, @samp{Subject} and so on. However, scoring -other headers requires writing a @code{head} scoring rule, which means -that Gnus has to request every single article from the back end to find -matches. This takes a long time in big groups. - -@vindex gnus-inhibit-slow-scoring -You can inhibit this slow scoring on headers or body by setting the -variable @code{gnus-inhibit-slow-scoring}. If -@code{gnus-inhibit-slow-scoring} is regexp, slow scoring is inhibited if -the group matches the regexp. If it is t, slow scoring on it is -inhibited for all groups. - -Now, there's not much you can do about the slowness for news groups, but for -mail groups, you have greater control. In @ref{To From Newsgroups}, -it's explained in greater detail what this mechanism does, but here's -a cookbook example for @code{nnml} on how to allow scoring on the -@samp{To} and @samp{Cc} headers. - -Put the following in your @file{~/.gnus.el} file. - -@lisp -(setq gnus-extra-headers '(To Cc Newsgroups Keywords) - nnmail-extra-headers gnus-extra-headers) -@end lisp - -Restart Gnus and rebuild your @code{nnml} overview files with the -@kbd{M-x nnml-generate-nov-databases} command. This will take a long -time if you have much mail. - -Now you can score on @samp{To} and @samp{Cc} as ``extra headers'' like -so: @kbd{I e s p To RET RET}. - -See? Simple. - - -@node Scoring Tips -@section Scoring Tips -@cindex scoring tips - -@table @dfn - -@item Crossposts -@cindex crossposts -@cindex scoring crossposts -If you want to lower the score of crossposts, the line to match on is -the @code{Xref} header. -@lisp -("xref" (" talk.politics.misc:" -1000)) -@end lisp - -@item Multiple crossposts -If you want to lower the score of articles that have been crossposted to -more than, say, 3 groups: -@lisp -("xref" - ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" - -1000 nil r)) -@end lisp - -@item Matching on the body -This is generally not a very good idea---it takes a very long time. -Gnus actually has to fetch each individual article from the server. But -you might want to anyway, I guess. Even though there are three match -keys (@code{Head}, @code{Body} and @code{All}), you should choose one -and stick with it in each score file. If you use any two, each article -will be fetched @emph{twice}. If you want to match a bit on the -@code{Head} and a bit on the @code{Body}, just use @code{All} for all -the matches. - -@item Marking as read -You will probably want to mark articles that have scores below a certain -number as read. This is most easily achieved by putting the following -in your @file{all.SCORE} file: -@lisp -((mark -100)) -@end lisp -You may also consider doing something similar with @code{expunge}. - -@item Negated character classes -If you say stuff like @code{[^abcd]*}, you may get unexpected results. -That will match newlines, which might lead to, well, The Unknown. Say -@code{[^abcd\n]*} instead. -@end table - - -@node Reverse Scoring -@section Reverse Scoring -@cindex reverse scoring - -If you want to keep just articles that have @samp{Sex with Emacs} in the -subject header, and expunge all other articles, you could put something -like this in your score file: - -@lisp -(("subject" - ("Sex with Emacs" 2)) - (mark 1) - (expunge 1)) -@end lisp - -So, you raise all articles that match @samp{Sex with Emacs} and mark the -rest as read, and expunge them to boot. - - -@node Global Score Files -@section Global Score Files -@cindex global score files - -Sure, other newsreaders have ``global kill files''. These are usually -nothing more than a single kill file that applies to all groups, stored -in the user's home directory. Bah! Puny, weak newsreaders! - -What I'm talking about here are Global Score Files. Score files from -all over the world, from users everywhere, uniting all nations in one -big, happy score file union! Ange-score! New and untested! - -@vindex gnus-global-score-files -All you have to do to use other people's score files is to set the -@code{gnus-global-score-files} variable. One entry for each score file, -or each score file directory. Gnus will decide by itself what score -files are applicable to which group. - -To use the score file -@file{/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE} and -all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory, -say this: - -@lisp -(setq gnus-global-score-files - '("/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE" - "/ftp@@ftp.some-where:/pub/score/")) -@end lisp - -@findex gnus-score-search-global-directories -@noindent -Simple, eh? Directory names must end with a @samp{/}. These -directories are typically scanned only once during each Gnus session. -If you feel the need to manually re-scan the remote directories, you can -use the @code{gnus-score-search-global-directories} command. - -Note that, at present, using this option will slow down group entry -somewhat. (That is---a lot.) - -If you want to start maintaining score files for other people to use, -just put your score file up for anonymous ftp and announce it to the -world. Become a retro-moderator! Participate in the retro-moderator -wars sure to ensue, where retro-moderators battle it out for the -sympathy of the people, luring them to use their score files on false -premises! Yay! The net is saved! - -Here are some tips for the would-be retro-moderator, off the top of my -head: - -@itemize @bullet - -@item -Articles heavily crossposted are probably junk. -@item -To lower a single inappropriate article, lower by @code{Message-ID}. -@item -Particularly brilliant authors can be raised on a permanent basis. -@item -Authors that repeatedly post off-charter for the group can safely be -lowered out of existence. -@item -Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest -articles completely. - -@item -Use expiring score entries to keep the size of the file down. You -should probably have a long expiry period, though, as some sites keep -old articles for a long time. -@end itemize - -@dots{} I wonder whether other newsreaders will support global score files -in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue -Wave, xrn and 1stReader are bound to implement scoring. Should we start -holding our breath yet? - - -@node Kill Files -@section Kill Files -@cindex kill files - -Gnus still supports those pesky old kill files. In fact, the kill file -entries can now be expiring, which is something I wrote before Daniel -Quinlan thought of doing score files, so I've left the code in there. - -In short, kill processing is a lot slower (and I do mean @emph{a lot}) -than score processing, so it might be a good idea to rewrite your kill -files into score files. - -Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any -forms into this file, which means that you can use kill files as some -sort of primitive hook function to be run on group entry, even though -that isn't a very good idea. - -Normal kill files look like this: - -@lisp -(gnus-kill "From" "Lars Ingebrigtsen") -(gnus-kill "Subject" "ding") -(gnus-expunge "X") -@end lisp - -This will mark every article written by me as read, and remove the -marked articles from the summary buffer. Very useful, you'll agree. - -Other programs use a totally different kill file syntax. If Gnus -encounters what looks like a @code{rn} kill file, it will take a stab at -interpreting it. - -Two summary functions for editing a @sc{gnus} kill file: - -@table @kbd - -@item M-k -@kindex M-k (Summary) -@findex gnus-summary-edit-local-kill -Edit this group's kill file (@code{gnus-summary-edit-local-kill}). - -@item M-K -@kindex M-K (Summary) -@findex gnus-summary-edit-global-kill -Edit the general kill file (@code{gnus-summary-edit-global-kill}). -@end table - -Two group mode functions for editing the kill files: - -@table @kbd - -@item M-k -@kindex M-k (Group) -@findex gnus-group-edit-local-kill -Edit this group's kill file (@code{gnus-group-edit-local-kill}). - -@item M-K -@kindex M-K (Group) -@findex gnus-group-edit-global-kill -Edit the general kill file (@code{gnus-group-edit-global-kill}). -@end table - -Kill file variables: - -@table @code -@item gnus-kill-file-name -@vindex gnus-kill-file-name -A kill file for the group @samp{soc.motss} is normally called -@file{soc.motss.KILL}. The suffix appended to the group name to get -this file name is detailed by the @code{gnus-kill-file-name} variable. -The ``global'' kill file (not in the score file sense of ``global'', of -course) is just called @file{KILL}. - -@vindex gnus-kill-save-kill-file -@item gnus-kill-save-kill-file -If this variable is non-@code{nil}, Gnus will save the -kill file after processing, which is necessary if you use expiring -kills. - -@item gnus-apply-kill-hook -@vindex gnus-apply-kill-hook -@findex gnus-apply-kill-file-unless-scored -@findex gnus-apply-kill-file -A hook called to apply kill files to a group. It is -@code{(gnus-apply-kill-file)} by default. If you want to ignore the -kill file if you have a score file for the same group, you can set this -hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want -kill files to be processed, you should set this variable to @code{nil}. - -@item gnus-kill-file-mode-hook -@vindex gnus-kill-file-mode-hook -A hook called in kill-file mode buffers. - -@end table - - -@node Converting Kill Files -@section Converting Kill Files -@cindex kill files -@cindex converting kill files - -If you have loads of old kill files, you may want to convert them into -score files. If they are ``regular'', you can use -the @file{gnus-kill-to-score.el} package; if not, you'll have to do it -by hand. - -The kill to score conversion package isn't included in Emacs by default. -You can fetch it from the contrib directory of the Gnus distribution or -from -@uref{http://heim.ifi.uio.no/~larsi/ding-various/gnus-kill-to-score.el}. - -If your old kill files are very complex---if they contain more -non-@code{gnus-kill} forms than not, you'll have to convert them by -hand. Or just let them be as they are. Gnus will still use them as -before. - - -@node Advanced Scoring -@section Advanced Scoring - -Scoring on Subjects and From headers is nice enough, but what if you're -really interested in what a person has to say only when she's talking -about a particular subject? Or what if you really don't want to -read what person A has to say when she's following up to person B, but -want to read what she says when she's following up to person C? - -By using advanced scoring rules you may create arbitrarily complex -scoring patterns. - -@menu -* Advanced Scoring Syntax:: A definition. -* Advanced Scoring Examples:: What they look like. -* Advanced Scoring Tips:: Getting the most out of it. -@end menu - - -@node Advanced Scoring Syntax -@subsection Advanced Scoring Syntax - -Ordinary scoring rules have a string as the first element in the rule. -Advanced scoring rules have a list as the first element. The second -element is the score to be applied if the first element evaluated to a -non-@code{nil} value. - -These lists may consist of three logical operators, one redirection -operator, and various match operators. - -Logical operators: - -@table @code -@item & -@itemx and -This logical operator will evaluate each of its arguments until it finds -one that evaluates to @code{false}, and then it'll stop. If all arguments -evaluate to @code{true} values, then this operator will return -@code{true}. - -@item | -@itemx or -This logical operator will evaluate each of its arguments until it finds -one that evaluates to @code{true}. If no arguments are @code{true}, -then this operator will return @code{false}. - -@item ! -@itemx not -@itemx ¬ -This logical operator only takes a single argument. It returns the -logical negation of the value of its argument. - -@end table - -There is an @dfn{indirection operator} that will make its arguments -apply to the ancestors of the current article being scored. For -instance, @code{1-} will make score rules apply to the parent of the -current article. @code{2-} will make score rules apply to the -grandparent of the current article. Alternatively, you can write -@code{^^}, where the number of @code{^}s (carets) says how far back into -the ancestry you want to go. - -Finally, we have the match operators. These are the ones that do the -real work. Match operators are header name strings followed by a match -and a match type. A typical match operator looks like @samp{("from" -"Lars Ingebrigtsen" s)}. The header names are the same as when using -simple scoring, and the match types are also the same. - - -@node Advanced Scoring Examples -@subsection Advanced Scoring Examples - -Please note that the following examples are score file rules. To -make a complete score file from them, surround them with another pair -of parentheses. - -Let's say you want to increase the score of articles written by Lars -when he's talking about Gnus: - -@example -@group -((& - ("from" "Lars Ingebrigtsen") - ("subject" "Gnus")) - 1000) -@end group -@end example - -Quite simple, huh? - -When he writes long articles, he sometimes has something nice to say: - -@example -((& - ("from" "Lars Ingebrigtsen") - (| - ("subject" "Gnus") - ("lines" 100 >))) - 1000) -@end example - -However, when he responds to things written by Reig Eigil Logge, you -really don't want to read what he's written: - -@example -((& - ("from" "Lars Ingebrigtsen") - (1- ("from" "Reig Eigil Logge"))) - -100000) -@end example - -Everybody that follows up Redmondo when he writes about disappearing -socks should have their scores raised, but only when they talk about -white socks. However, when Lars talks about socks, it's usually not -very interesting: - -@example -((& - (1- - (& - ("from" "redmondo@@.*no" r) - ("body" "disappearing.*socks" t))) - (! ("from" "Lars Ingebrigtsen")) - ("body" "white.*socks")) - 1000) -@end example - -Suppose you're reading a high volume group and you're only interested -in replies. The plan is to score down all articles that don't have -subject that begin with "Re:", "Fw:" or "Fwd:" and then score up all -parents of articles that have subjects that begin with reply marks. - -@example -((! ("subject" "re:\\|fwd?:" r)) - -200) -((1- ("subject" "re:\\|fwd?:" r)) - 200) -@end example - -The possibilities are endless. - -@node Advanced Scoring Tips -@subsection Advanced Scoring Tips - -The @code{&} and @code{|} logical operators do short-circuit logic. -That is, they stop processing their arguments when it's clear what the -result of the operation will be. For instance, if one of the arguments -of an @code{&} evaluates to @code{false}, there's no point in evaluating -the rest of the arguments. This means that you should put slow matches -(@samp{body}, @samp{header}) last and quick matches (@samp{from}, -@samp{subject}) first. - -The indirection arguments (@code{1-} and so on) will make their -arguments work on previous generations of the thread. If you say -something like: - -@example -... -(1- - (1- - ("from" "lars"))) -... -@end example - -Then that means ``score on the from header of the grandparent of the -current article''. An indirection is quite fast, but it's better to say: - -@example -(1- - (& - ("from" "Lars") - ("subject" "Gnus"))) -@end example - -than it is to say: - -@example -(& - (1- ("from" "Lars")) - (1- ("subject" "Gnus"))) -@end example - - -@node Score Decays -@section Score Decays -@cindex score decays -@cindex decays - -You may find that your scores have a tendency to grow without -bounds, especially if you're using adaptive scoring. If scores get too -big, they lose all meaning---they simply max out and it's difficult to -use them in any sensible way. - -@vindex gnus-decay-scores -@findex gnus-decay-score -@vindex gnus-decay-score-function -Gnus provides a mechanism for decaying scores to help with this problem. -When score files are loaded and @code{gnus-decay-scores} is -non-@code{nil}, Gnus will run the score files through the decaying -mechanism thereby lowering the scores of all non-permanent score rules. -If @code{gnus-decay-scores} is a regexp, only score files matching this -regexp are treated. E.g. you may set it to @samp{\\.ADAPT\\'} if only -@emph{adaptive} score files should be decayed. The decay itself if -performed by the @code{gnus-decay-score-function} function, which is -@code{gnus-decay-score} by default. Here's the definition of that -function: - -@lisp -(defun gnus-decay-score (score) - "Decay SCORE according to `gnus-score-decay-constant' -and `gnus-score-decay-scale'." - (let ((n (- score - (* (if (< score 0) -1 1) - (min (abs score) - (max gnus-score-decay-constant - (* (abs score) - gnus-score-decay-scale))))))) - (if (and (featurep 'xemacs) - ;; XEmacs's floor can handle only the floating point - ;; number below the half of the maximum integer. - (> (abs n) (lsh -1 -2))) - (string-to-number - (car (split-string (number-to-string n) "\\."))) - (floor n)))) -@end lisp - -@vindex gnus-score-decay-scale -@vindex gnus-score-decay-constant -@code{gnus-score-decay-constant} is 3 by default and -@code{gnus-score-decay-scale} is 0.05. This should cause the following: - -@enumerate -@item -Scores between -3 and 3 will be set to 0 when this function is called. - -@item -Scores with magnitudes between 3 and 60 will be shrunk by 3. - -@item -Scores with magnitudes greater than 60 will be shrunk by 5% of the -score. -@end enumerate - -If you don't like this decay function, write your own. It is called -with the score to be decayed as its only parameter, and it should return -the new score, which should be an integer. - -Gnus will try to decay scores once a day. If you haven't run Gnus for -four days, Gnus will decay the scores four times, for instance. - -@node Searching -@chapter Searching -@cindex searching - -FIXME: Add a brief overview of Gnus search capabilities. A brief -comparison of nnir, nnmairix, contrib/gnus-namazu would be nice -as well. - -This chapter describes tools for searching groups and servers for -articles matching a query and then retrieving those articles. Gnus -provides a simpler mechanism for searching through articles in a summary buffer -to find those matching a pattern. @xref{Searching for Articles}. - -@menu -* nnir:: Searching with various engines. -* nnmairix:: Searching with Mairix. -@end menu - -@node nnir -@section nnir -@cindex nnir - -This section describes how to use @code{nnir} to search for articles -within gnus. - -@menu -* What is nnir?:: What does @code{nnir} do? -* Basic Usage:: How to perform simple searches. -* Setting up nnir:: How to set up @code{nnir}. -@end menu - -@node What is nnir? -@subsection What is nnir? - -@code{nnir} is a Gnus interface to a number of tools for searching -through mail and news repositories. Different backends (like -@code{nnimap} and @code{nntp}) work with different tools (called -@dfn{engines} in @code{nnir} lingo), but all use the same basic search -interface. - -The @code{nnimap} and @code{gmane} search engines should work with no -configuration. Other engines require a local index that needs to be -created and maintained outside of Gnus. - - -@node Basic Usage -@subsection Basic Usage - -In the group buffer typing @kbd{G G} will search the group on the -current line by calling @code{gnus-group-make-nnir-group}. This prompts -for a query string, creates an ephemeral @code{nnir} group containing -the articles that match this query, and takes you to a summary buffer -showing these articles. Articles may then be read, moved and deleted -using the usual commands. - -The @code{nnir} group made in this way is an @code{ephemeral} group, and -some changes are not permanent: aside from reading, moving, and -deleting, you can't act on the original article. But there is an -alternative: you can @emph{warp} to the original group for the article -on the current line with @kbd{A W}, aka -@code{gnus-warp-to-article}. Even better, the function -@code{gnus-summary-refer-thread}, bound by default in summary buffers to -@kbd{A T}, will first warp to the original group before it works its -magic and includes all the articles in the thread. From here you can -read, move and delete articles, but also copy them, alter article marks, -whatever. Go nuts. - -You say you want to search more than just the group on the current line? -No problem: just process-mark the groups you want to search. You want -even more? Calling for an nnir search with the cursor on a topic heading -will search all the groups under that heading. - -Still not enough? OK, in the server buffer -@code{gnus-group-make-nnir-group} (now bound to @kbd{G}) will search all -groups from the server on the current line. Too much? Want to ignore -certain groups when searching, like spam groups? Just customize -@code{nnir-ignored-newsgroups}. - -One more thing: individual search engines may have special search -features. You can access these special features by giving a prefix-arg -to @code{gnus-group-make-nnir-group}. If you are searching multiple -groups with different search engines you will be prompted for the -special search features for each engine separately. - - -@node Setting up nnir -@subsection Setting up nnir - -To set up nnir you may need to do some prep work. Firstly, you may need -to configure the search engines you plan to use. Some of them, like -@code{imap} and @code{gmane}, need no special configuration. Others, -like @code{namazu} and @code{swish}, require configuration as described -below. Secondly, you need to associate a search engine with a server or -a backend. - -If you just want to use the @code{imap} engine to search @code{nnimap} -servers, and the @code{gmane} engine to search @code{gmane} then you -don't have to do anything. But you might want to read the details of the -query language anyway. - -@menu -* Associating Engines:: How to associate engines. -* The imap Engine:: Imap configuration and usage. -* The gmane Engine:: Gmane configuration and usage. -* The swish++ Engine:: Swish++ configuration and usage. -* The swish-e Engine:: Swish-e configuration and usage. -* The namazu Engine:: Namazu configuration and usage. -* The hyrex Engine:: Hyrex configuration and usage. -* Customizations:: User customizable settings. -@end menu - -@node Associating Engines -@subsubsection Associating Engines - - -When searching a group, @code{nnir} needs to know which search engine to -use. You can configure a given server to use a particular engine by -setting the server variable @code{nnir-search-engine} to the engine -name. For example to use the @code{namazu} engine to search the server -named @code{home} you can use - -@lisp -(setq gnus-secondary-select-methods - '((nnml "home" - (nnimap-address "localhost") - (nnir-search-engine namazu)))) -@end lisp - -Alternatively you might want to use a particular engine for all servers -with a given backend. For example, you might want to use the @code{imap} -engine for all servers using the @code{nnimap} backend. In this case you -can customize the variable @code{nnir-method-default-engines}. This is -an alist of pairs of the form @code{(backend . engine)}. By default this -variable is set to use the @code{imap} engine for all servers using the -@code{nnimap} backend, and the @code{gmane} backend for @code{nntp} -servers. (Don't worry, the @code{gmane} search engine won't actually try -to search non-gmane @code{nntp} servers.) But if you wanted to use -@code{namazu} for all your servers with an @code{nnimap} backend you -could change this to - -@lisp -'((nnimap . namazu) - (nntp . gmane)) -@end lisp - -@node The imap Engine -@subsubsection The imap Engine - -The @code{imap} engine requires no configuration. - -Queries using the @code{imap} engine follow a simple query language. -The search is always case-insensitive and supports the following -features (inspired by the Google search input language): - -@table @samp - -@item Boolean query operators -AND, OR, and NOT are supported, and parentheses can be used to control -operator precedence, e.g. (emacs OR xemacs) AND linux. Note that -operators must be written with all capital letters to be -recognized. Also preceding a term with a - sign is equivalent to NOT -term. - -@item Automatic AND queries -If you specify multiple words then they will be treated as an AND -expression intended to match all components. - -@item Phrase searches -If you wrap your query in double-quotes then it will be treated as a -literal string. - -@end table - -By default the whole message will be searched. The query can be limited -to a specific part of a message by using a prefix-arg. After inputting -the query this will prompt (with completion) for a message part. -Choices include ``Whole message'', ``Subject'', ``From'', and -``To''. Any unrecognized input is interpreted as a header name. For -example, typing @kbd{Message-ID} in response to this prompt will limit -the query to the Message-ID header. - -Finally selecting ``Imap'' will interpret the query as a raw -@acronym{IMAP} search query. The format of such queries can be found in -RFC3501. - -If you don't like the default of searching whole messages you can -customize @code{nnir-imap-default-search-key}. For example to use -@acronym{IMAP} queries by default - -@lisp -(setq nnir-imap-default-search-key "Imap") -@end lisp - -@node The gmane Engine -@subsubsection The gmane Engine - -The @code{gmane} engine requires no configuration. - -Gmane queries follow a simple query language: - -@table @samp -@item Boolean query operators -AND, OR, NOT (or AND NOT), and XOR are supported, and brackets can be -used to control operator precedence, e.g. (emacs OR xemacs) AND linux. -Note that operators must be written with all capital letters to be -recognized. - -@item Required and excluded terms -+ and - can be used to require or exclude terms, e.g. football -american - -@item Unicode handling -The search engine converts all text to utf-8, so searching should work -in any language. - -@item Stopwords -Common English words (like 'the' and 'a') are ignored by default. You -can override this by prefixing such words with a + (e.g. +the) or -enclosing the word in quotes (e.g. "the"). - -@end table - -The query can be limited to articles by a specific author using a -prefix-arg. After inputting the query this will prompt for an author -name (or part of a name) to match. - -@node The swish++ Engine -@subsubsection The swish++ Engine - -FIXME: Say something more here. - -Documentation for swish++ may be found at the swish++ sourceforge page: -@uref{http://swishplusplus.sourceforge.net} - -@table @code - -@item nnir-swish++-program -The name of the swish++ executable. Defaults to @code{search} - -@item nnir-swish++-additional-switches -A list of strings to be given as additional arguments to -swish++. @code{nil} by default. - -@item nnir-swish++-remove-prefix -The prefix to remove from each file name returned by swish++ in order -to get a group name. By default this is @code{$HOME/Mail}. - -@end table - -@node The swish-e Engine -@subsubsection The swish-e Engine - -FIXME: Say something more here. - -Documentation for swish-e may be found at the swish-e homepage -@uref{http://swish-e.org} - -@table @code - -@item nnir-swish-e-program -The name of the swish-e search program. Defaults to @code{swish-e}. - -@item nnir-swish-e-additional-switches -A list of strings to be given as additional arguments to -swish-e. @code{nil} by default. - -@item nnir-swish-e-remove-prefix -The prefix to remove from each file name returned by swish-e in order -to get a group name. By default this is @code{$HOME/Mail}. - -@end table - -@node The namazu Engine -@subsubsection The namazu Engine - -Using the namazu engine requires creating and maintaining index files. -One directory should contain all the index files, and nnir must be told -where to find them by setting the @code{nnir-namazu-index-directory} -variable. - -To work correctly the @code{nnir-namazu-remove-prefix} variable must -also be correct. This is the prefix to remove from each file name -returned by Namazu in order to get a proper group name (albeit with `/' -instead of `.'). - -For example, suppose that Namazu returns file names such as -@samp{/home/john/Mail/mail/misc/42}. For this example, use the -following setting: @code{(setq nnir-namazu-remove-prefix -"/home/john/Mail/")} Note the trailing slash. Removing this prefix from -the directory gives @samp{mail/misc/42}. @code{nnir} knows to remove -the @samp{/42} and to replace @samp{/} with @samp{.} to arrive at the -correct group name @samp{mail.misc}. - -Extra switches may be passed to the namazu search command by setting the -variable @code{nnir-namazu-additional-switches}. It is particularly -important not to pass any any switches to namazu that will change the -output format. Good switches to use include `--sort', `--ascending', -`--early' and `--late'. Refer to the Namazu documentation for further -information on valid switches. - -Mail must first be indexed with the `mknmz' program. Read the documentation -for namazu to create a configuration file. Here is an example: - -@cartouche -@example - package conf; # Don't remove this line! - - # Paths which will not be indexed. Don't use `^' or `$' anchors. - $EXCLUDE_PATH = "spam|sent"; - - # Header fields which should be searchable. case-insensitive - $REMAIN_HEADER = "from|date|message-id|subject"; - - # Searchable fields. case-insensitive - $SEARCH_FIELD = "from|date|message-id|subject"; - - # The max length of a word. - $WORD_LENG_MAX = 128; - - # The max length of a field. - $MAX_FIELD_LENGTH = 256; -@end example -@end cartouche - -For this example, mail is stored in the directories @samp{~/Mail/mail/}, -@samp{~/Mail/lists/} and @samp{~/Mail/archive/}, so to index them go to -the index directory set in @code{nnir-namazu-index-directory} and issue -the following command: - -@example -mknmz --mailnews ~/Mail/archive/ ~/Mail/mail/ ~/Mail/lists/ -@end example - -For maximum searching efficiency you might want to have a cron job run -this command periodically, say every four hours. - -@node The hyrex Engine -@subsubsection The hyrex Engine -This engine is obsolete. - -@node Customizations -@subsubsection Customizations - -@table @code - -@item nnir-method-default-engines -Alist of server backend - search engine pairs. The default associations -are -@example -(nnimap . imap) -(nntp . gmane) -@end example - -@item nnir-ignored-newsgroups -A regexp to match newsgroups in the active file that should be skipped -when searching all groups on a server. - -@item nnir-summary-line-format -The format specification to be used for lines in an nnir summary buffer. -All the items from `gnus-summary-line-format' are available, along with -three items unique to nnir summary buffers: - -@example -%Z Search retrieval score value (integer) -%G Article original full group name (string) -%g Article original short group name (string) -@end example - -If nil (the default) this will use @code{gnus-summary-line-format}. - -@item nnir-retrieve-headers-override-function -If non-nil, a function that retrieves article headers rather than using -the gnus built-in function. This function takes an article list and -group as arguments and populates the `nntp-server-buffer' with the -retrieved headers. It should then return either 'nov or 'headers -indicating the retrieved header format. Failure to retrieve headers -should return @code{nil} - -If this variable is nil, or if the provided function returns nil for a -search result, @code{gnus-retrieve-headers} will be called instead." - - -@end table - - -@node nnmairix -@section nnmairix - -@cindex mairix -@cindex nnmairix -This paragraph describes how to set up mairix and the back end -@code{nnmairix} for indexing and searching your mail from within -Gnus. Additionally, you can create permanent ``smart'' groups which are -bound to mairix searches and are automatically updated. - -@menu -* About mairix:: About the mairix mail search engine -* nnmairix requirements:: What you will need for using nnmairix -* What nnmairix does:: What does nnmairix actually do? -* Setting up mairix:: Set up your mairix installation -* Configuring nnmairix:: Set up the nnmairix back end -* nnmairix keyboard shortcuts:: List of available keyboard shortcuts -* Propagating marks:: How to propagate marks from nnmairix groups -* nnmairix tips and tricks:: Some tips, tricks and examples -* nnmairix caveats:: Some more stuff you might want to know -@end menu - -@c FIXME: The markup in this section might need improvement. -@c E.g. adding @samp, @var, @file, @command, etc. -@c Cf. (info "(texinfo)Indicating") - -@node About mairix -@subsection About mairix - -Mairix is a tool for indexing and searching words in locally stored -mail. It was written by Richard Curnow and is licensed under the -GPL. Mairix comes with most popular GNU/Linux distributions, but it also -runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can -be found at -@uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} - -Though mairix might not be as flexible as other search tools like -swish++ or namazu, which you can use via the @code{nnir} back end, it -has the prime advantage of being incredibly fast. On current systems, it -can easily search through headers and message bodies of thousands and -thousands of mails in well under a second. Building the database -necessary for searching might take a minute or two, but only has to be -done once fully. Afterwards, the updates are done incrementally and -therefore are really fast, too. Additionally, mairix is very easy to set -up. - -For maximum speed though, mairix should be used with mails stored in -@code{Maildir} or @code{MH} format (this includes the @code{nnml} back -end), although it also works with mbox. Mairix presents the search -results by populating a @emph{virtual} maildir/MH folder with symlinks -which point to the ``real'' message files (if mbox is used, copies are -made). Since mairix already presents search results in such a virtual -mail folder, it is very well suited for using it as an external program -for creating @emph{smart} mail folders, which represent certain mail -searches. - -@node nnmairix requirements -@subsection nnmairix requirements - -Mairix searches local mail---that means, mairix absolutely must have -direct access to your mail folders. If your mail resides on another -server (e.g. an @acronym{IMAP} server) and you happen to have shell -access, @code{nnmairix} supports running mairix remotely, e.g. via ssh. - -Additionally, @code{nnmairix} only supports the following Gnus back -ends: @code{nnml}, @code{nnmaildir}, and @code{nnimap}. You must use -one of these back ends for using @code{nnmairix}. Other back ends, like -@code{nnmbox}, @code{nnfolder} or @code{nnmh}, won't work. - -If you absolutely must use mbox and still want to use @code{nnmairix}, -you can set up a local @acronym{IMAP} server, which you then access via -@code{nnimap}. This is a rather massive setup for accessing some mbox -files, so just change to MH or Maildir already... However, if you're -really, really passionate about using mbox, you might want to look into -the package @file{mairix.el}, which comes with Emacs 23. - -@node What nnmairix does -@subsection What nnmairix does - -The back end @code{nnmairix} enables you to call mairix from within Gnus, -either to query mairix with a search term or to update the -database. While visiting a message in the summary buffer, you can use -several pre-defined shortcuts for calling mairix, e.g. to quickly -search for all mails from the sender of the current message or to -display the whole thread associated with the message, even if the -mails are in different folders. - -Additionally, you can create permanent @code{nnmairix} groups which are bound -to certain mairix searches. This way, you can easily create a group -containing mails from a certain sender, with a certain subject line or -even for one specific thread based on the Message-ID. If you check for -new mail in these folders (e.g. by pressing @kbd{g} or @kbd{M-g}), they -automatically update themselves by calling mairix. - -You might ask why you need @code{nnmairix} at all, since mairix already -creates the group, populates it with links to the mails so that you can -then access it with Gnus, right? Well, this @emph{might} work, but often -does not---at least not without problems. Most probably you will get -strange article counts, and sometimes you might see mails which Gnus -claims have already been canceled and are inaccessible. This is due to -the fact that Gnus isn't really amused when things are happening behind -its back. Another problem can be the mail back end itself, e.g. if you -use mairix with an @acronym{IMAP} server (I had Dovecot complaining -about corrupt index files when mairix changed the contents of the search -group). Using @code{nnmairix} should circumvent these problems. - -@code{nnmairix} is not really a mail back end---it's actually more like -a wrapper, sitting between a ``real'' mail back end where mairix stores -the searches and the Gnus front end. You can choose between three -different mail back ends for the mairix folders: @code{nnml}, -@code{nnmaildir} or @code{nnimap}. @code{nnmairix} will call the mairix -binary so that the search results are stored in folders named -@code{zz_mairix--} on this mail back end, but it will -present these folders in the Gnus front end only with @code{}. -You can use an existing mail back end where you already store your mail, -but if you're uncomfortable with @code{nnmairix} creating new mail -groups alongside your other mail, you can also create e.g. a new -@code{nnmaildir} or @code{nnml} server exclusively for mairix, but then -make sure those servers do not accidentally receive your new mail -(@pxref{nnmairix caveats}). A special case exists if you want to use -mairix remotely on an IMAP server with @code{nnimap}---here the mairix -folders and your other mail must be on the same @code{nnimap} back end. - -@node Setting up mairix -@subsection Setting up mairix - -First: create a backup of your mail folders (@pxref{nnmairix caveats}). - -Setting up mairix is easy: simply create a @file{.mairixrc} file with -(at least) the following entries: - -@example -# Your Maildir/MH base folder -base=~/Maildir -@end example - -This is the base folder for your mails. All the following directories -are relative to this base folder. If you want to use @code{nnmairix} -with @code{nnimap}, this base directory has to point to the mail -directory where the @acronym{IMAP} server stores the mail folders! - -@example -maildir= ... your maildir folders which should be indexed ... -mh= ... your nnml/mh folders which should be indexed ... -mbox = ... your mbox files which should be indexed ... -@end example - -This specifies all your mail folders and mbox files (relative to the -base directory!) you want to index with mairix. Note that the -@code{nnml} back end saves mails in MH format, so you have to put those -directories in the @code{mh} line. See the example at the end of this -section and mairixrc's man-page for further details. - -@example -omit=zz_mairix-* -@end example - -@vindex nnmairix-group-prefix -This should make sure that you don't accidentally index the mairix -search results. You can change the prefix of these folders with the -variable @code{nnmairix-group-prefix}. - -@example -mformat= ... 'maildir' or 'mh' ... -database= ... location of database file ... -@end example - -The @code{format} setting specifies the output format for the mairix -search folder. Set this to @code{mh} if you want to access search results -with @code{nnml}. Otherwise choose @code{maildir}. - -To summarize, here is my shortened @file{.mairixrc} file as an example: - -@example -base=~/Maildir -maildir=.personal:.work:.logcheck:.sent -mh=../Mail/nnml/*... -mbox=../mboxmail/mailarchive_year* -mformat=maildir -omit=zz_mairix-* -database=~/.mairixdatabase -@end example - -In this case, the base directory is @file{~/Maildir}, where all my Maildir -folders are stored. As you can see, the folders are separated by -colons. If you wonder why every folder begins with a dot: this is -because I use Dovecot as @acronym{IMAP} server, which again uses -@code{Maildir++} folders. For testing nnmairix, I also have some -@code{nnml} mail, which is saved in @file{~/Mail/nnml}. Since this has -to be specified relative to the @code{base} directory, the @code{../Mail} -notation is needed. Note that the line ends in @code{*...}, which means -to recursively scan all files under this directory. Without the three -dots, the wildcard @code{*} will not work recursively. I also have some -old mbox files with archived mail lying around in @file{~/mboxmail}. -The other lines should be obvious. - -See the man page for @code{mairixrc} for details and further options, -especially regarding wildcard usage, which may be a little different -than you are used to. - -Now simply call @code{mairix} to create the index for the first time. -Note that this may take a few minutes, but every following index will do -the updates incrementally and hence is very fast. - -@node Configuring nnmairix -@subsection Configuring nnmairix - -In group mode, type @kbd{G b c} -(@code{nnmairix-create-server-and-default-group}). This will ask you for all -necessary information and create a @code{nnmairix} server as a foreign -server. You will have to specify the following: - -@itemize @bullet - -@item -The @strong{name} of the @code{nnmairix} server---choose whatever you -want. - -@item -The name of the @strong{back end server} where mairix should store its -searches. This must be a full server name, like @code{nnml:mymail}. -Just hit @kbd{TAB} to see the available servers. Currently, servers -which are accessed through @code{nnmaildir}, @code{nnimap} and -@code{nnml} are supported. As explained above, for locally stored -mails, this can be an existing server where you store your mails. -However, you can also create e.g. a new @code{nnmaildir} or @code{nnml} -server exclusively for @code{nnmairix} in your secondary select methods -(@pxref{Finding the News}). If you use a secondary @code{nnml} server -just for mairix, make sure that you explicitly set the server variable -@code{nnml-get-new-mail} to @code{nil}, or you might lose mail -(@pxref{nnmairix caveats}). If you want to use mairix remotely on an -@acronym{IMAP} server, you have to choose the corresponding -@code{nnimap} server here. - -@item -@vindex nnmairix-mairix-search-options -The @strong{command} to call the mairix binary. This will usually just -be @code{mairix}, but you can also choose something like @code{ssh -SERVER mairix} if you want to call mairix remotely, e.g. on your -@acronym{IMAP} server. If you want to add some default options to -mairix, you could do this here, but better use the variable -@code{nnmairix-mairix-search-options} instead. - -@item -The name of the @strong{default search group}. This will be the group -where all temporary mairix searches are stored, i.e. all searches which -are not bound to permanent @code{nnmairix} groups. Choose whatever you -like. - -@item -If the mail back end is @code{nnimap} or @code{nnmaildir}, you will be -asked if you work with @strong{Maildir++}, i.e. with hidden maildir -folders (=beginning with a dot). For example, you have to answer -@samp{yes} here if you work with the Dovecot @acronym{IMAP} -server. Otherwise, you should answer @samp{no} here. - -@end itemize - -@node nnmairix keyboard shortcuts -@subsection nnmairix keyboard shortcuts - -In group mode: - -@table @kbd - -@item G b c -@kindex G b c (Group) -@findex nnmairix-create-server-and-default-group -Creates @code{nnmairix} server and default search group for this server -(@code{nnmairix-create-server-and-default-group}). You should have done -this by now (@pxref{Configuring nnmairix}). - -@item G b s -@kindex G b s (Group) -@findex nnmairix-search -Prompts for query which is then sent to the mairix binary. Search -results are put into the default search group which is automatically -displayed (@code{nnmairix-search}). - -@item G b m -@kindex G b m (Group) -@findex nnmairix-widget-search -Allows you to create a mairix search or a permanent group more -comfortably using graphical widgets, similar to a customization -group. Just try it to see how it works (@code{nnmairix-widget-search}). - -@item G b i -@kindex G b i (Group) -@findex nnmairix-search-interactive -Another command for creating a mairix query more comfortably, but uses -only the minibuffer (@code{nnmairix-search-interactive}). - -@item G b g -@kindex G b g (Group) -@findex nnmairix-create-search-group -Creates a permanent group which is associated with a search query -(@code{nnmairix-create-search-group}). The @code{nnmairix} back end -automatically calls mairix when you update this group with @kbd{g} or -@kbd{M-g}. - -@item G b q -@kindex G b q (Group) -@findex nnmairix-group-change-query-this-group -Changes the search query for the @code{nnmairix} group under cursor -(@code{nnmairix-group-change-query-this-group}). - -@item G b t -@kindex G b t (Group) -@findex nnmairix-group-toggle-threads-this-group -Toggles the 'threads' parameter for the @code{nnmairix} group under cursor, -i.e. if you want see the whole threads of the found messages -(@code{nnmairix-group-toggle-threads-this-group}). - -@item G b u -@kindex G b u (Group) -@findex nnmairix-update-database -@vindex nnmairix-mairix-update-options -Calls mairix binary for updating the database -(@code{nnmairix-update-database}). The default parameters are @code{-F} -and @code{-Q} for making this as fast as possible (see variable -@code{nnmairix-mairix-update-options} for defining these default -options). - -@item G b r -@kindex G b r (Group) -@findex nnmairix-group-toggle-readmarks-this-group -Keep articles in this @code{nnmairix} group always read or unread, or leave the -marks unchanged (@code{nnmairix-group-toggle-readmarks-this-group}). - -@item G b d -@kindex G b d (Group) -@findex nnmairix-group-delete-recreate-this-group -Recreate @code{nnmairix} group on the ``real'' mail back end -(@code{nnmairix-group-delete-recreate-this-group}). You can do this if -you always get wrong article counts with a @code{nnmairix} group. - -@item G b a -@kindex G b a (Group) -@findex nnmairix-group-toggle-allowfast-this-group -Toggles the @code{allow-fast} parameters for group under cursor -(@code{nnmairix-group-toggle-allowfast-this-group}). The default -behavior of @code{nnmairix} is to do a mairix search every time you -update or enter the group. With the @code{allow-fast} parameter set, -mairix will only be called when you explicitly update the group, but not -upon entering. This makes entering the group faster, but it may also -lead to dangling symlinks if something changed between updating and -entering the group which is not yet in the mairix database. - -@item G b p -@kindex G b p (Group) -@findex nnmairix-group-toggle-propmarks-this-group -Toggle marks propagation for this group -(@code{nnmairix-group-toggle-propmarks-this-group}). (@pxref{Propagating -marks}). - -@item G b o -@kindex G b o (Group) -@findex nnmairix-propagate-marks -Manually propagate marks (@code{nnmairix-propagate-marks}); needed only when -@code{nnmairix-propagate-marks-upon-close} is set to @code{nil}. - -@end table - -In summary mode: - -@table @kbd - -@item $ m -@kindex $ m (Summary) -@findex nnmairix-widget-search-from-this-article -Allows you to create a mairix query or group based on the current -message using graphical widgets (same as @code{nnmairix-widget-search}) -(@code{nnmairix-widget-search-from-this-article}). - -@item $ g -@kindex $ g (Summary) -@findex nnmairix-create-search-group-from-message -Interactively creates a new search group with query based on the current -message, but uses the minibuffer instead of graphical widgets -(@code{nnmairix-create-search-group-from-message}). - -@item $ t -@kindex $ t (Summary) -@findex nnmairix-search-thread-this-article -Searches thread for the current article -(@code{nnmairix-search-thread-this-article}). This is effectively a -shortcut for calling @code{nnmairix-search} with @samp{m:msgid} of the -current article and enabled threads. - -@item $ f -@kindex $ f (Summary) -@findex nnmairix-search-from-this-article -Searches all messages from sender of the current article -(@code{nnmairix-search-from-this-article}). This is a shortcut for -calling @code{nnmairix-search} with @samp{f:From}. - -@item $ o -@kindex $ o (Summary) -@findex nnmairix-goto-original-article -(Only in @code{nnmairix} groups!) Tries determine the group this article -originally came from and displays the article in this group, so that -e.g. replying to this article the correct posting styles/group -parameters are applied (@code{nnmairix-goto-original-article}). This -function will use the registry if available, but can also parse the -article file name as a fallback method. - -@item $ u -@kindex $ u (Summary) -@findex nnmairix-remove-tick-mark-original-article -Remove possibly existing tick mark from original article -(@code{nnmairix-remove-tick-mark-original-article}). (@pxref{nnmairix -tips and tricks}). - -@end table - -@node Propagating marks -@subsection Propagating marks - -First of: you really need a patched mairix binary for using the marks -propagation feature efficiently. Otherwise, you would have to update -the mairix database all the time. You can get the patch at - -@uref{http://www.randomsample.de/mairix-maildir-patch.tar} - -You need the mairix v0.21 source code for this patch; everything else -is explained in the accompanied readme file. If you don't want to use -marks propagation, you don't have to apply these patches, but they also -fix some annoyances regarding changing maildir flags, so it might still -be useful to you. - -With the patched mairix binary, you can use @code{nnmairix} as an -alternative to mail splitting (@pxref{Fancy Mail Splitting}). For -example, instead of splitting all mails from @samp{david@@foobar.com} -into a group, you can simply create a search group with the query -@samp{f:david@@foobar.com}. This is actually what ``smart folders'' are -all about: simply put everything in one mail folder and dynamically -create searches instead of splitting. This is more flexible, since you -can dynamically change your folders any time you want to. This also -implies that you will usually read your mails in the @code{nnmairix} -groups instead of your ``real'' mail groups. - -There is one problem, though: say you got a new mail from -@samp{david@@foobar.com}; it will now show up in two groups, the -``real'' group (your INBOX, for example) and in the @code{nnmairix} -search group (provided you have updated the mairix database). Now you -enter the @code{nnmairix} group and read the mail. The mail will be -marked as read, but only in the @code{nnmairix} group---in the ``real'' -mail group it will be still shown as unread. - -You could now catch up the mail group (@pxref{Group Data}), but this is -tedious and error prone, since you may overlook mails you don't have -created @code{nnmairix} groups for. Of course, you could first use -@code{nnmairix-goto-original-article} (@pxref{nnmairix keyboard -shortcuts}) and then read the mail in the original group, but that's -even more cumbersome. - -Clearly, the easiest way would be if marks could somehow be -automatically set for the original article. This is exactly what -@emph{marks propagation} is about. - -Marks propagation is inactive by default. You can activate it for a -certain @code{nnmairix} group with -@code{nnmairix-group-toggle-propmarks-this-group} (bound to @kbd{G b -p}). This function will warn you if you try to use it with your default -search group; the reason is that the default search group is used for -temporary searches, and it's easy to accidentally propagate marks from -this group. However, you can ignore this warning if you really want to. - -With marks propagation enabled, all the marks you set in a @code{nnmairix} -group should now be propagated to the original article. For example, -you can now tick an article (by default with @kbd{!}) and this mark should -magically be set for the original article, too. - -A few more remarks which you may or may not want to know: - -@vindex nnmairix-propagate-marks-upon-close -Marks will not be set immediately, but only upon closing a group. This -not only makes marks propagation faster, it also avoids problems with -dangling symlinks when dealing with maildir files (since changing flags -will change the file name). You can also control when to propagate marks -via @code{nnmairix-propagate-marks-upon-close} (see the doc-string for -details). - -Obviously, @code{nnmairix} will have to look up the original group for every -article you want to set marks for. If available, @code{nnmairix} will first use -the registry for determining the original group. The registry is very -fast, hence you should really, really enable the registry when using -marks propagation. If you don't have to worry about RAM and disc space, -set @code{gnus-registry-max-entries} to a large enough value; to be on -the safe side, choose roughly the amount of mails you index with mairix. - -@vindex nnmairix-only-use-registry -If you don't want to use the registry or the registry hasn't seen the -original article yet, @code{nnmairix} will use an additional mairix -search for determining the file name of the article. This, of course, is -way slower than the registry---if you set hundreds or even thousands of -marks this way, it might take some time. You can avoid this situation by -setting @code{nnmairix-only-use-registry} to t. - -Maybe you also want to propagate marks the other way round, i.e. if you -tick an article in a "real" mail group, you'd like to have the same -article in a @code{nnmairix} group ticked, too. For several good -reasons, this can only be done efficiently if you use maildir. To -immediately contradict myself, let me mention that it WON'T work with -@code{nnmaildir}, since @code{nnmaildir} stores the marks externally and -not in the file name. Therefore, propagating marks to @code{nnmairix} -groups will usually only work if you use an IMAP server which uses -maildir as its file format. - -@vindex nnmairix-propagate-marks-to-nnmairix-groups -If you work with this setup, just set -@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t} and see what -happens. If you don't like what you see, just set it to @code{nil} again. One -problem might be that you get a wrong number of unread articles; this -usually happens when you delete or expire articles in the original -groups. When this happens, you can recreate the @code{nnmairix} group on the -back end using @kbd{G b d}. - -@node nnmairix tips and tricks -@subsection nnmairix tips and tricks - -@itemize -@item -Checking Mail - -@findex nnmairix-update-groups -I put all my important mail groups at group level 1. The mairix groups -have group level 5, so they do not get checked at start up (@pxref{Group -Levels}). - -I use the following to check for mails: - -@lisp -(defun my-check-mail-mairix-update (level) - (interactive "P") - ;; if no prefix given, set level=1 - (gnus-group-get-new-news (or level 1)) - (nnmairix-update-groups "mairixsearch" t t) - (gnus-group-list-groups)) - -(define-key gnus-group-mode-map "g" 'my-check-mail-mairix-update) -@end lisp - -Instead of @samp{"mairixsearch"} use the name of your @code{nnmairix} -server. See the doc string for @code{nnmairix-update-groups} for -details. - -@item -Example: search group for ticked articles - -For example, you can create a group for all ticked articles, where the -articles always stay unread: - -Hit @kbd{G b g}, enter group name (e.g. @samp{important}), use -@samp{F:f} as query and do not include threads. - -Now activate marks propagation for this group by using @kbd{G b p}. Then -activate the always-unread feature by using @kbd{G b r} twice. - -So far so good---but how do you remove the tick marks in the @code{nnmairix} -group? There are two options: You may simply use -@code{nnmairix-remove-tick-mark-original-article} (bound to @kbd{$ u}) to remove -tick marks from the original article. The other possibility is to set -@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t}, but see the above -comments about this option. If it works for you, the tick marks should -also exist in the @code{nnmairix} group and you can remove them as usual, -e.g. by marking an article as read. - -When you have removed a tick mark from the original article, this -article should vanish from the @code{nnmairix} group after you have updated the -mairix database and updated the group. Fortunately, there is a function -for doing exactly that: @code{nnmairix-update-groups}. See the previous code -snippet and the doc string for details. - -@item -Dealing with auto-subscription of mail groups - -As described before, all @code{nnmairix} groups are in fact stored on -the mail back end in the form @samp{zz_mairix--}. You can -see them when you enter the back end server in the server buffer. You -should not subscribe these groups! Unfortunately, these groups will -usually get @emph{auto-subscribed} when you use @code{nnmaildir} or -@code{nnml}, i.e. you will suddenly see groups of the form -@samp{zz_mairix*} pop up in your group buffer. If this happens to you, -simply kill these groups with C-k. For avoiding this, turn off -auto-subscription completely by setting the variable -@code{gnus-auto-subscribed-groups} to @code{nil} (@pxref{Filtering New -Groups}), or if you like to keep this feature use the following kludge -for turning it off for all groups beginning with @samp{zz_}: - -@lisp -(setq gnus-auto-subscribed-groups - "^\\(nnml\\|nnfolder\\|nnmbox\\|nnmh\\|nnbabyl\\|nnmaildir\\).*:\\([^z]\\|z$\\|\\z[^z]\\|zz$\\|zz[^_]\\|zz_$\\).*") -@end lisp - -@end itemize - -@node nnmairix caveats -@subsection nnmairix caveats - -@itemize -@item -You can create a secondary @code{nnml} server just for nnmairix, but then -you have to explicitly set the corresponding server variable -@code{nnml-get-new-mail} to @code{nil}. Otherwise, new mail might get -put into this secondary server (and would never show up again). Here's -an example server definition: - -@lisp -(nnml "mairix" (nnml-directory "mairix") (nnml-get-new-mail nil)) -@end lisp - -(The @code{nnmaildir} back end also has a server variable -@code{get-new-mail}, but its default value is @code{nil}, so you don't -have to explicitly set it if you use a @code{nnmaildir} server just for -mairix.) - -@item -If you use the Gnus registry: don't use the registry with -@code{nnmairix} groups (put them in -@code{gnus-registry-unfollowed-groups}; this is the default). Be -@emph{extra careful} if you use -@code{gnus-registry-split-fancy-with-parent}; mails which are split -into @code{nnmairix} groups are usually gone for good as soon as you -check the group for new mail (yes, it has happened to me...). - -@item -Therefore: @emph{Never ever} put ``real'' mails into @code{nnmairix} -groups (you shouldn't be able to, anyway). - -@item -If you use the Gnus agent (@pxref{Gnus Unplugged}): don't agentize -@code{nnmairix} groups (though I have no idea what happens if you do). - -@item -mairix does only support us-ascii characters. - -@item -@code{nnmairix} uses a rather brute force method to force Gnus to -completely reread the group on the mail back end after mairix was -called---it simply deletes and re-creates the group on the mail -back end. So far, this has worked for me without any problems, and I -don't see how @code{nnmairix} could delete other mail groups than its -own, but anyway: you really should have a backup of your mail -folders. - -@item -All necessary information is stored in the group parameters -(@pxref{Group Parameters}). This has the advantage that no active file -is needed, but also implies that when you kill a @code{nnmairix} group, -it is gone for good. - -@item -@findex nnmairix-purge-old-groups -If you create and kill a lot of @code{nnmairix} groups, the -``zz_mairix-*'' groups will accumulate on the mail back end server. To -delete old groups which are no longer needed, call -@code{nnmairix-purge-old-groups}. Note that this assumes that you don't -save any ``real'' mail in folders of the form -@code{zz_mairix--}. You can change the prefix of -@code{nnmairix} groups by changing the variable -@code{nnmairix-group-prefix}. - -@item -The following only applies if you @emph{don't} use the mentioned patch -for mairix (@pxref{Propagating marks}): - -A problem can occur when using @code{nnmairix} with maildir folders and -comes with the fact that maildir stores mail flags like @samp{Seen} or -@samp{Replied} by appending chars @samp{S} and @samp{R} to the message -file name, respectively. This implies that currently you would have to -update the mairix database not only when new mail arrives, but also when -mail flags are changing. The same applies to new mails which are indexed -while they are still in the @samp{new} folder but then get moved to -@samp{cur} when Gnus has seen the mail. If you don't update the database -after this has happened, a mairix query can lead to symlinks pointing to -non-existing files. In Gnus, these messages will usually appear with -``(none)'' entries in the header and can't be accessed. If this happens -to you, using @kbd{G b u} and updating the group will usually fix this. - -@end itemize - -@iftex -@iflatex -@chapter Message -@include message.texi -@chapter Emacs MIME -@include emacs-mime.texi -@chapter Sieve -@include sieve.texi -@chapter EasyPG -@include epa.texi -@chapter SASL -@include sasl.texi -@end iflatex -@end iftex - -@node Various -@chapter Various - -@menu -* Process/Prefix:: A convention used by many treatment commands. -* Interactive:: Making Gnus ask you many questions. -* Symbolic Prefixes:: How to supply some Gnus functions with options. -* Formatting Variables:: You can specify what buffers should look like. -* Window Layout:: Configuring the Gnus buffer windows. -* Faces and Fonts:: How to change how faces look. -* Compilation:: How to speed Gnus up. -* Mode Lines:: Displaying information in the mode lines. -* Highlighting and Menus:: Making buffers look all nice and cozy. -* Daemons:: Gnus can do things behind your back. -* Undo:: Some actions can be undone. -* Predicate Specifiers:: Specifying predicates. -* Moderation:: What to do if you're a moderator. -* Fetching a Group:: Starting Gnus just to read a group. -* Image Enhancements:: Modern versions of Emacs/XEmacs can display images. -* Fuzzy Matching:: What's the big fuzz? -* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. -* Spam Package:: A package for filtering and processing spam. -* The Gnus Registry:: A package for tracking messages by Message-ID. -* Other modes:: Interaction with other modes. -* Various Various:: Things that are really various. -@end menu - - -@node Process/Prefix -@section Process/Prefix -@cindex process/prefix convention - -Many functions, among them functions for moving, decoding and saving -articles, use what is known as the @dfn{Process/Prefix convention}. - -This is a method for figuring out what articles the user wants the -command to be performed on. - -It goes like this: - -If the numeric prefix is N, perform the operation on the next N -articles, starting with the current one. If the numeric prefix is -negative, perform the operation on the previous N articles, starting -with the current one. - -@vindex transient-mark-mode -If @code{transient-mark-mode} in non-@code{nil} and the region is -active, all articles in the region will be worked upon. - -If there is no numeric prefix, but some articles are marked with the -process mark, perform the operation on the articles marked with -the process mark. - -If there is neither a numeric prefix nor any articles marked with the -process mark, just perform the operation on the current article. - -Quite simple, really, but it needs to be made clear so that surprises -are avoided. - -Commands that react to the process mark will push the current list of -process marked articles onto a stack and will then clear all process -marked articles. You can restore the previous configuration with the -@kbd{M P y} command (@pxref{Setting Process Marks}). - -@vindex gnus-summary-goto-unread -One thing that seems to shock & horrify lots of people is that, for -instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}. -Since each @kbd{d} (which marks the current article as read) by default -goes to the next unread article after marking, this means that @kbd{3 d} -will mark the next three unread articles as read, no matter what the -summary buffer looks like. Set @code{gnus-summary-goto-unread} to -@code{nil} for a more straightforward action. - -Many commands do not use the process/prefix convention. All commands -that do explicitly say so in this manual. To apply the process/prefix -convention to commands that do not use it, you can use the @kbd{M-&} -command. For instance, to mark all the articles in the group as -expirable, you could say @kbd{M P b M-& E}. - - -@node Interactive -@section Interactive -@cindex interaction - -@table @code - -@item gnus-novice-user -@vindex gnus-novice-user -If this variable is non-@code{nil}, you are either a newcomer to the -World of Usenet, or you are very cautious, which is a nice thing to be, -really. You will be given questions of the type ``Are you sure you want -to do this?'' before doing anything dangerous. This is @code{t} by -default. - -@item gnus-expert-user -@vindex gnus-expert-user -If this variable is non-@code{nil}, you will seldom be asked any -questions by Gnus. It will simply assume you know what you're doing, -no matter how strange. For example, quitting Gnus, exiting a group -without an update, catching up with a group, deleting expired -articles, and replying by mail to a news message will not require -confirmation. - -@item gnus-interactive-catchup -@vindex gnus-interactive-catchup -Require confirmation before catching up a group if non-@code{nil}. It -is @code{t} by default. - -@item gnus-interactive-exit -@vindex gnus-interactive-exit -If non-@code{nil}, require a confirmation when exiting Gnus. If -@code{quiet}, update any active summary buffers automatically without -querying. The default value is @code{t}. -@end table - - -@node Symbolic Prefixes -@section Symbolic Prefixes -@cindex symbolic prefixes - -Quite a lot of Emacs commands react to the (numeric) prefix. For -instance, @kbd{C-u 4 C-f} moves point four characters forward, and -@kbd{C-u 9 0 0 I s s p} adds a permanent @code{Subject} substring score -rule of 900 to the current article. - -This is all nice and well, but what if you want to give a command some -additional information? Well, what most commands do is interpret the -``raw'' prefix in some special way. @kbd{C-u 0 C-x C-s} means that one -doesn't want a backup file to be created when saving the current buffer, -for instance. But what if you want to save without making a backup -file, and you want Emacs to flash lights and play a nice tune at the -same time? You can't, and you're probably perfectly happy that way. - -@kindex M-i (Summary) -@findex gnus-symbolic-argument -I'm not, so I've added a second prefix---the @dfn{symbolic prefix}. The -prefix key is @kbd{M-i} (@code{gnus-symbolic-argument}), and the next -character typed in is the value. You can stack as many @kbd{M-i} -prefixes as you want. @kbd{M-i a C-M-u} means ``feed the @kbd{C-M-u} -command the symbolic prefix @code{a}''. @kbd{M-i a M-i b C-M-u} means -``feed the @kbd{C-M-u} command the symbolic prefixes @code{a} and -@code{b}''. You get the drift. - -Typing in symbolic prefixes to commands that don't accept them doesn't -hurt, but it doesn't do any good either. Currently not many Gnus -functions make use of the symbolic prefix. - -If you're interested in how Gnus implements this, @pxref{Extended -Interactive}. - - -@node Formatting Variables -@section Formatting Variables -@cindex formatting variables - -Throughout this manual you've probably noticed lots of variables called -things like @code{gnus-group-line-format} and -@code{gnus-summary-mode-line-format}. These control how Gnus is to -output lines in the various buffers. There's quite a lot of them. -Fortunately, they all use the same syntax, so there's not that much to -be annoyed by. - -Here's an example format spec (from the group buffer): @samp{%M%S%5y: -%(%g%)\n}. We see that it is indeed extremely ugly, and that there are -lots of percentages everywhere. - -@menu -* Formatting Basics:: A formatting variable is basically a format string. -* Mode Line Formatting:: Some rules about mode line formatting variables. -* Advanced Formatting:: Modifying output in various ways. -* User-Defined Specs:: Having Gnus call your own functions. -* Formatting Fonts:: Making the formatting look colorful and nice. -* Positioning Point:: Moving point to a position after an operation. -* Tabulation:: Tabulating your output. -* Wide Characters:: Dealing with wide characters. -@end menu - -Currently Gnus uses the following formatting variables: -@code{gnus-group-line-format}, @code{gnus-summary-line-format}, -@code{gnus-server-line-format}, @code{gnus-topic-line-format}, -@code{gnus-group-mode-line-format}, -@code{gnus-summary-mode-line-format}, -@code{gnus-article-mode-line-format}, -@code{gnus-server-mode-line-format}, and -@code{gnus-summary-pick-line-format}. - -All these format variables can also be arbitrary elisp forms. In that -case, they will be @code{eval}ed to insert the required lines. - -@kindex M-x gnus-update-format -@findex gnus-update-format -Gnus includes a command to help you while creating your own format -specs. @kbd{M-x gnus-update-format} will @code{eval} the current form, -update the spec in question and pop you to a buffer where you can -examine the resulting Lisp code to be run to generate the line. - - - -@node Formatting Basics -@subsection Formatting Basics - -Each @samp{%} element will be replaced by some string or other when the -buffer in question is generated. @samp{%5y} means ``insert the @samp{y} -spec, and pad with spaces to get a 5-character field''. - -As with normal C and Emacs Lisp formatting strings, the numerical -modifier between the @samp{%} and the formatting type character will -@dfn{pad} the output so that it is always at least that long. -@samp{%5y} will make the field always (at least) five characters wide by -padding with spaces to the left. If you say @samp{%-5y}, it will pad to -the right instead. - -You may also wish to limit the length of the field to protect against -particularly wide values. For that you can say @samp{%4,6y}, which -means that the field will never be more than 6 characters wide and never -less than 4 characters wide. - -Also Gnus supports some extended format specifications, such as -@samp{%&user-date;}. - - -@node Mode Line Formatting -@subsection Mode Line Formatting - -Mode line formatting variables (e.g., -@code{gnus-summary-mode-line-format}) follow the same rules as other, -buffer line oriented formatting variables (@pxref{Formatting Basics}) -with the following two differences: - -@enumerate - -@item -There must be no newline (@samp{\n}) at the end. - -@item -The special @samp{%%b} spec can be used to display the buffer name. -Well, it's no spec at all, really---@samp{%%} is just a way to quote -@samp{%} to allow it to pass through the formatting machinery unmangled, -so that Emacs receives @samp{%b}, which is something the Emacs mode line -display interprets to mean ``show the buffer name''. For a full list of -mode line specs Emacs understands, see the documentation of the -@code{mode-line-format} variable. - -@end enumerate - - -@node Advanced Formatting -@subsection Advanced Formatting - -It is frequently useful to post-process the fields in some way. -Padding, limiting, cutting off parts and suppressing certain values can -be achieved by using @dfn{tilde modifiers}. A typical tilde spec might -look like @samp{%~(cut 3)~(ignore "0")y}. - -These are the valid modifiers: - -@table @code -@item pad -@itemx pad-left -Pad the field to the left with spaces until it reaches the required -length. - -@item pad-right -Pad the field to the right with spaces until it reaches the required -length. - -@item max -@itemx max-left -Cut off characters from the left until it reaches the specified length. - -@item max-right -Cut off characters from the right until it reaches the specified -length. - -@item cut -@itemx cut-left -Cut off the specified number of characters from the left. - -@item cut-right -Cut off the specified number of characters from the right. - -@item ignore -Return an empty string if the field is equal to the specified value. - -@item form -Use the specified form as the field value when the @samp{@@} spec is -used. - -Here's an example: - -@lisp -"~(form (current-time-string))@@" -@end lisp - -@end table - -Let's take an example. The @samp{%o} spec in the summary mode lines -will return a date in compact ISO8601 format---@samp{19960809T230410}. -This is quite a mouthful, so we want to shave off the century number and -the time, leaving us with a six-character date. That would be -@samp{%~(cut-left 2)~(max-right 6)~(pad 6)o}. (Cutting is done before -maxing, and we need the padding to ensure that the date is never less -than 6 characters to make it look nice in columns.) - -Ignoring is done first; then cutting; then maxing; and then as the very -last operation, padding. - -If you use lots of these advanced thingies, you'll find that Gnus gets -quite slow. This can be helped enormously by running @kbd{M-x -gnus-compile} when you are satisfied with the look of your lines. -@xref{Compilation}. - - -@node User-Defined Specs -@subsection User-Defined Specs - -All the specs allow for inserting user defined specifiers---@samp{u}. -The next character in the format string should be a letter. Gnus -will call the function @code{gnus-user-format-function-}@samp{X}, where -@samp{X} is the letter following @samp{%u}. The function will be passed -a single parameter---what the parameter means depends on what buffer -it's being called from. The function should return a string, which will -be inserted into the buffer just like information from any other -specifier. This function may also be called with dummy values, so it -should protect against that. - -Also Gnus supports extended user-defined specs, such as @samp{%u&foo;}. -Gnus will call the function @code{gnus-user-format-function-}@samp{foo}. - -You can also use tilde modifiers (@pxref{Advanced Formatting} to achieve -much the same without defining new functions. Here's an example: -@samp{%~(form (count-lines (point-min) (point)))@@}. The form -given here will be evaluated to yield the current line number, and then -inserted. - - -@node Formatting Fonts -@subsection Formatting Fonts - -@cindex %(, %) -@vindex gnus-mouse-face -There are specs for highlighting, and these are shared by all the format -variables. Text inside the @samp{%(} and @samp{%)} specifiers will get -the special @code{mouse-face} property set, which means that it will be -highlighted (with @code{gnus-mouse-face}) when you put the mouse pointer -over it. - -@cindex %@{, %@} -@vindex gnus-face-0 -Text inside the @samp{%@{} and @samp{%@}} specifiers will have their -normal faces set using @code{gnus-face-0}, which is @code{bold} by -default. If you say @samp{%1@{}, you'll get @code{gnus-face-1} instead, -and so on. Create as many faces as you wish. The same goes for the -@code{mouse-face} specs---you can say @samp{%3(hello%)} to have -@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}. - -@cindex %<<, %>>, guillemets -@c @cindex %<<, %>>, %«, %», guillemets -@vindex gnus-balloon-face-0 -Text inside the @samp{%<<} and @samp{%>>} specifiers will get the -special @code{balloon-help} property set to -@code{gnus-balloon-face-0}. If you say @samp{%1<<}, you'll get -@code{gnus-balloon-face-1} and so on. The @code{gnus-balloon-face-*} -variables should be either strings or symbols naming functions that -return a string. When the mouse passes over text with this property -set, a balloon window will appear and display the string. Please -refer to @ref{Tooltips, ,Tooltips, emacs, The Emacs Manual}, -(in Emacs) or the doc string of @code{balloon-help-mode} (in -XEmacs) for more information on this. (For technical reasons, the -guillemets have been approximated as @samp{<<} and @samp{>>} in this -paragraph.) - -Here's an alternative recipe for the group buffer: - -@lisp -;; @r{Create three face types.} -(setq gnus-face-1 'bold) -(setq gnus-face-3 'italic) - -;; @r{We want the article count to be in} -;; @r{a bold and green face. So we create} -;; @r{a new face called @code{my-green-bold}.} -(copy-face 'bold 'my-green-bold) -;; @r{Set the color.} -(set-face-foreground 'my-green-bold "ForestGreen") -(setq gnus-face-2 'my-green-bold) - -;; @r{Set the new & fancy format.} -(setq gnus-group-line-format - "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n") -@end lisp - -I'm sure you'll be able to use this scheme to create totally unreadable -and extremely vulgar displays. Have fun! - -Note that the @samp{%(} specs (and friends) do not make any sense on the -mode-line variables. - -@node Positioning Point -@subsection Positioning Point - -Gnus usually moves point to a pre-defined place on each line in most -buffers. By default, point move to the first colon character on the -line. You can customize this behavior in three different ways. - -You can move the colon character to somewhere else on the line. - -@findex gnus-goto-colon -You can redefine the function that moves the point to the colon. The -function is called @code{gnus-goto-colon}. - -But perhaps the most convenient way to deal with this, if you don't want -to have a colon in your line, is to use the @samp{%*} specifier. If you -put a @samp{%*} somewhere in your format line definition, Gnus will -place point there. - - -@node Tabulation -@subsection Tabulation - -You can usually line up your displays by padding and cutting your -strings. However, when combining various strings of different size, it -can often be more convenient to just output the strings, and then worry -about lining up the following text afterwards. - -To do that, Gnus supplies tabulator specs---@samp{%=}. There are two -different types---@dfn{hard tabulators} and @dfn{soft tabulators}. - -@samp{%50=} will insert space characters to pad the line up to column -50. If the text is already past column 50, nothing will be inserted. -This is the soft tabulator. - -@samp{%-50=} will insert space characters to pad the line up to column -50. If the text is already past column 50, the excess text past column -50 will be removed. This is the hard tabulator. - - -@node Wide Characters -@subsection Wide Characters - -Fixed width fonts in most countries have characters of the same width. -Some countries, however, use Latin characters mixed with wider -characters---most notable East Asian countries. - -The problem is that when formatting, Gnus assumes that if a string is 10 -characters wide, it'll be 10 Latin characters wide on the screen. In -these countries, that's not true. - -@vindex gnus-use-correct-string-widths -To help fix this, you can set @code{gnus-use-correct-string-widths} to -@code{t}. This makes buffer generation slower, but the results will be -prettier. The default value under XEmacs is @code{t} but @code{nil} -for Emacs. - - -@node Window Layout -@section Window Layout -@cindex window layout - -No, there's nothing here about X, so be quiet. - -@vindex gnus-use-full-window -If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all -other windows and occupy the entire Emacs screen by itself. It is -@code{t} by default. - -Setting this variable to @code{nil} kinda works, but there are -glitches. Use at your own peril. - -@vindex gnus-buffer-configuration -@code{gnus-buffer-configuration} describes how much space each Gnus -buffer should be given. Here's an excerpt of this variable: - -@lisp -((group (vertical 1.0 (group 1.0 point))) - (article (vertical 1.0 (summary 0.25 point) - (article 1.0)))) -@end lisp - -This is an alist. The @dfn{key} is a symbol that names some action or -other. For instance, when displaying the group buffer, the window -configuration function will use @code{group} as the key. A full list of -possible names is listed below. - -The @dfn{value} (i.e., the @dfn{split}) says how much space each buffer -should occupy. To take the @code{article} split as an example - - -@lisp -(article (vertical 1.0 (summary 0.25 point) - (article 1.0))) -@end lisp - -This @dfn{split} says that the summary buffer should occupy 25% of upper -half of the screen, and that it is placed over the article buffer. As -you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all -reaching for that calculator there). However, the special number -@code{1.0} is used to signal that this buffer should soak up all the -rest of the space available after the rest of the buffers have taken -whatever they need. There should be only one buffer with the @code{1.0} -size spec per split. - -Point will be put in the buffer that has the optional third element -@code{point}. In a @code{frame} split, the last subsplit having a leaf -split where the tag @code{frame-focus} is a member (i.e. is the third or -fourth element in the list, depending on whether the @code{point} tag is -present) gets focus. - -Here's a more complicated example: - -@lisp -(article (vertical 1.0 (group 4) - (summary 0.25 point) - (article 1.0))) -@end lisp - -If the size spec is an integer instead of a floating point number, -then that number will be used to say how many lines a buffer should -occupy, not a percentage. - -If the @dfn{split} looks like something that can be @code{eval}ed (to be -precise---if the @code{car} of the split is a function or a subr), this -split will be @code{eval}ed. If the result is non-@code{nil}, it will -be used as a split. - -Not complicated enough for you? Well, try this on for size: - -@lisp -(article (horizontal 1.0 - (vertical 0.5 - (group 1.0)) - (vertical 1.0 - (summary 0.25 point) - (article 1.0)))) -@end lisp - -Whoops. Two buffers with the mystery 100% tag. And what's that -@code{horizontal} thingie? - -If the first element in one of the split is @code{horizontal}, Gnus will -split the window horizontally, giving you two windows side-by-side. -Inside each of these strips you may carry on all you like in the normal -fashion. The number following @code{horizontal} says what percentage of -the screen is to be given to this strip. - -For each split, there @emph{must} be one element that has the 100% tag. -The splitting is never accurate, and this buffer will eat any leftover -lines from the splits. - -To be slightly more formal, here's a definition of what a valid split -may look like: - -@example -@group -split = frame | horizontal | vertical | buffer | form -frame = "(frame " size *split ")" -horizontal = "(horizontal " size *split ")" -vertical = "(vertical " size *split ")" -buffer = "(" buf-name " " size *[ "point" ] *[ "frame-focus"] ")" -size = number | frame-params -buf-name = group | article | summary ... -@end group -@end example - -The limitations are that the @code{frame} split can only appear as the -top-level split. @var{form} should be an Emacs Lisp form that should -return a valid split. We see that each split is fully recursive, and -may contain any number of @code{vertical} and @code{horizontal} splits. - -@vindex gnus-window-min-width -@vindex gnus-window-min-height -@cindex window height -@cindex window width -Finding the right sizes can be a bit complicated. No window may be less -than @code{gnus-window-min-height} (default 1) characters high, and all -windows must be at least @code{gnus-window-min-width} (default 1) -characters wide. Gnus will try to enforce this before applying the -splits. If you want to use the normal Emacs window width/height limit, -you can just set these two variables to @code{nil}. - -If you're not familiar with Emacs terminology, @code{horizontal} and -@code{vertical} splits may work the opposite way of what you'd expect. -Windows inside a @code{horizontal} split are shown side-by-side, and -windows within a @code{vertical} split are shown above each other. - -@findex gnus-configure-frame -If you want to experiment with window placement, a good tip is to call -@code{gnus-configure-frame} directly with a split. This is the function -that does all the real work when splitting buffers. Below is a pretty -nonsensical configuration with 5 windows; two for the group buffer and -three for the article buffer. (I said it was nonsensical.) If you -@code{eval} the statement below, you can get an idea of how that would -look straight away, without going through the normal Gnus channels. -Play with it until you're satisfied, and then use -@code{gnus-add-configuration} to add your new creation to the buffer -configuration list. - -@lisp -(gnus-configure-frame - '(horizontal 1.0 - (vertical 10 - (group 1.0) - (article 0.3 point)) - (vertical 1.0 - (article 1.0) - (horizontal 4 - (group 1.0) - (article 10))))) -@end lisp - -You might want to have several frames as well. No prob---just use the -@code{frame} split: - -@lisp -(gnus-configure-frame - '(frame 1.0 - (vertical 1.0 - (summary 0.25 point frame-focus) - (article 1.0)) - (vertical ((height . 5) (width . 15) - (user-position . t) - (left . -1) (top . 1)) - (picon 1.0)))) - -@end lisp - -This split will result in the familiar summary/article window -configuration in the first (or ``main'') frame, while a small additional -frame will be created where picons will be shown. As you can see, -instead of the normal @code{1.0} top-level spec, each additional split -should have a frame parameter alist as the size spec. -@xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp -Reference Manual}. Under XEmacs, a frame property list will be -accepted, too---for instance, @code{(height 5 width 15 left -1 top 1)} -is such a plist. -The list of all possible keys for @code{gnus-buffer-configuration} can -be found in its default value. - -Note that the @code{message} key is used for both -@code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If -it is desirable to distinguish between the two, something like this -might be used: - -@lisp -(message (horizontal 1.0 - (vertical 1.0 (message 1.0 point)) - (vertical 0.24 - (if (buffer-live-p gnus-summary-buffer) - '(summary 0.5)) - (group 1.0)))) -@end lisp - -One common desire for a multiple frame split is to have a separate frame -for composing mail and news while leaving the original frame intact. To -accomplish that, something like the following can be done: - -@lisp -(message - (frame 1.0 - (if (not (buffer-live-p gnus-summary-buffer)) - (car (cdr (assoc 'group gnus-buffer-configuration))) - (car (cdr (assoc 'summary gnus-buffer-configuration)))) - (vertical ((user-position . t) (top . 1) (left . 1) - (name . "Message")) - (message 1.0 point)))) -@end lisp - -@findex gnus-add-configuration -Since the @code{gnus-buffer-configuration} variable is so long and -complicated, there's a function you can use to ease changing the config -of a single setting: @code{gnus-add-configuration}. If, for instance, -you want to change the @code{article} setting, you could say: - -@lisp -(gnus-add-configuration - '(article (vertical 1.0 - (group 4) - (summary .25 point) - (article 1.0)))) -@end lisp - -You'd typically stick these @code{gnus-add-configuration} calls in your -@file{~/.gnus.el} file or in some startup hook---they should be run after -Gnus has been loaded. - -@vindex gnus-always-force-window-configuration -If all windows mentioned in the configuration are already visible, Gnus -won't change the window configuration. If you always want to force the -``right'' window configuration, you can set -@code{gnus-always-force-window-configuration} to non-@code{nil}. - -If you're using tree displays (@pxref{Tree Display}), and the tree -window is displayed vertically next to another window, you may also want -to fiddle with @code{gnus-tree-minimize-window} to avoid having the -windows resized. - -@subsection Window Configuration Names - -Here's a list of most of the currently known window configurations, -and when they're used: - -@table @code -@item group -The group buffer. - -@item summary -Entering a group and showing only the summary. - -@item article -Selecting an article. - -@item server -The server buffer. - -@item browse -Browsing groups from the server buffer. - -@item message -Composing a (new) message. - -@item only-article -Showing only the article buffer. - -@item edit-article -Editing an article. - -@item edit-form -Editing group parameters and the like. - -@item edit-score -Editing a server definition. - -@item post -Composing a news message. - -@item reply -Replying or following up an article without yanking the text. - -@item forward -Forwarding a message. - -@item reply-yank -Replying or following up an article with yanking the text. - -@item mail-bound -Bouncing a message. - -@item pipe -Sending an article to an external process. - -@item bug -Sending a bug report. - -@item score-trace -Displaying the score trace. - -@item score-words -Displaying the score words. - -@item split-trace -Displaying the split trace. - -@item compose-bounce -Composing a bounce message. - -@item mml-preview -Previewing a @acronym{MIME} part. - -@end table - - -@subsection Example Window Configurations - -@itemize @bullet -@item -Narrow left hand side occupied by group buffer. Right hand side split -between summary buffer (top one-sixth) and article buffer (bottom). - -@ifinfo -@example -+---+---------+ -| G | Summary | -| r +---------+ -| o | | -| u | Article | -| p | | -+---+---------+ -@end example -@end ifinfo - -@lisp -(gnus-add-configuration - '(article - (horizontal 1.0 - (vertical 25 (group 1.0)) - (vertical 1.0 - (summary 0.16 point) - (article 1.0))))) - -(gnus-add-configuration - '(summary - (horizontal 1.0 - (vertical 25 (group 1.0)) - (vertical 1.0 (summary 1.0 point))))) -@end lisp - -@end itemize - - -@node Faces and Fonts -@section Faces and Fonts -@cindex faces -@cindex fonts -@cindex colors - -Fiddling with fonts and faces used to be very difficult, but these days -it is very simple. You simply say @kbd{M-x customize-face}, pick out -the face you want to alter, and alter it via the standard Customize -interface. - - -@node Compilation -@section Compilation -@cindex compilation -@cindex byte-compilation - -@findex gnus-compile - -Remember all those line format specification variables? -@code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so -on. Now, Gnus will of course heed whatever these variables are, but, -unfortunately, changing them will mean a quite significant slow-down. -(The default values of these variables have byte-compiled functions -associated with them, while the user-generated versions do not, of -course.) - -To help with this, you can run @kbd{M-x gnus-compile} after you've -fiddled around with the variables and feel that you're (kind of) -satisfied. This will result in the new specs being byte-compiled, and -you'll get top speed again. Gnus will save these compiled specs in the -@file{.newsrc.eld} file. (User-defined functions aren't compiled by -this function, though---you should compile them yourself by sticking -them into the @file{~/.gnus.el} file and byte-compiling that file.) - - -@node Mode Lines -@section Mode Lines -@cindex mode lines - -@vindex gnus-updated-mode-lines -@code{gnus-updated-mode-lines} says what buffers should keep their mode -lines updated. It is a list of symbols. Supported symbols include -@code{group}, @code{article}, @code{summary}, @code{server}, -@code{browse}, and @code{tree}. If the corresponding symbol is present, -Gnus will keep that mode line updated with information that may be -pertinent. If this variable is @code{nil}, screen refresh may be -quicker. - -@cindex display-time - -@vindex gnus-mode-non-string-length -By default, Gnus displays information on the current article in the mode -lines of the summary and article buffers. The information Gnus wishes -to display (e.g. the subject of the article) is often longer than the -mode lines, and therefore have to be cut off at some point. The -@code{gnus-mode-non-string-length} variable says how long the other -elements on the line is (i.e., the non-info part). If you put -additional elements on the mode line (e.g. a clock), you should modify -this variable: - -@c Hook written by Francesco Potorti` -@lisp -(add-hook 'display-time-hook - (lambda () (setq gnus-mode-non-string-length - (+ 21 - (if line-number-mode 5 0) - (if column-number-mode 4 0) - (length display-time-string))))) -@end lisp - -If this variable is @code{nil} (which is the default), the mode line -strings won't be chopped off, and they won't be padded either. Note -that the default is unlikely to be desirable, as even the percentage -complete in the buffer may be crowded off the mode line; the user should -configure this variable appropriately for her configuration. - - -@node Highlighting and Menus -@section Highlighting and Menus -@cindex visual -@cindex highlighting -@cindex menus - -@vindex gnus-visual -The @code{gnus-visual} variable controls most of the Gnus-prettifying -aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy -colors or fonts. This will also inhibit loading the @file{gnus-vis.el} -file. - -This variable can be a list of visual properties that are enabled. The -following elements are valid, and are all included by default: - -@table @code -@item group-highlight -Do highlights in the group buffer. -@item summary-highlight -Do highlights in the summary buffer. -@item article-highlight -Do highlights in the article buffer. -@item highlight -Turn on highlighting in all buffers. -@item group-menu -Create menus in the group buffer. -@item summary-menu -Create menus in the summary buffers. -@item article-menu -Create menus in the article buffer. -@item browse-menu -Create menus in the browse buffer. -@item server-menu -Create menus in the server buffer. -@item score-menu -Create menus in the score buffers. -@item menu -Create menus in all buffers. -@end table - -So if you only want highlighting in the article buffer and menus in all -buffers, you could say something like: - -@lisp -(setq gnus-visual '(article-highlight menu)) -@end lisp - -If you want highlighting only and no menus whatsoever, you'd say: - -@lisp -(setq gnus-visual '(highlight)) -@end lisp - -If @code{gnus-visual} is @code{t}, highlighting and menus will be used -in all Gnus buffers. - -Other general variables that influence the look of all buffers include: - -@table @code -@item gnus-mouse-face -@vindex gnus-mouse-face -This is the face (i.e., font) used for mouse highlighting in Gnus. No -mouse highlights will be done if @code{gnus-visual} is @code{nil}. - -@end table - -There are hooks associated with the creation of all the different menus: - -@table @code - -@item gnus-article-menu-hook -@vindex gnus-article-menu-hook -Hook called after creating the article mode menu. - -@item gnus-group-menu-hook -@vindex gnus-group-menu-hook -Hook called after creating the group mode menu. - -@item gnus-summary-menu-hook -@vindex gnus-summary-menu-hook -Hook called after creating the summary mode menu. - -@item gnus-server-menu-hook -@vindex gnus-server-menu-hook -Hook called after creating the server mode menu. - -@item gnus-browse-menu-hook -@vindex gnus-browse-menu-hook -Hook called after creating the browse mode menu. - -@item gnus-score-menu-hook -@vindex gnus-score-menu-hook -Hook called after creating the score mode menu. - -@end table - - -@node Daemons -@section Daemons -@cindex demons -@cindex daemons - -Gnus, being larger than any program ever written (allegedly), does lots -of strange stuff that you may wish to have done while you're not -present. For instance, you may want it to check for new mail once in a -while. Or you may want it to close down all connections to all servers -when you leave Emacs idle. And stuff like that. - -Gnus will let you do stuff like that by defining various -@dfn{handlers}. Each handler consists of three elements: A -@var{function}, a @var{time}, and an @var{idle} parameter. - -Here's an example of a handler that closes connections when Emacs has -been idle for thirty minutes: - -@lisp -(gnus-demon-close-connections nil 30) -@end lisp - -Here's a handler that scans for @acronym{PGP} headers every hour when -Emacs is idle: - -@lisp -(gnus-demon-scan-pgp 60 t) -@end lisp - -This @var{time} parameter and that @var{idle} parameter work together -in a strange, but wonderful fashion. Basically, if @var{idle} is -@code{nil}, then the function will be called every @var{time} minutes. - -If @var{idle} is @code{t}, then the function will be called after -@var{time} minutes only if Emacs is idle. So if Emacs is never idle, -the function will never be called. But once Emacs goes idle, the -function will be called every @var{time} minutes. - -If @var{idle} is a number and @var{time} is a number, the function will -be called every @var{time} minutes only when Emacs has been idle for -@var{idle} minutes. - -If @var{idle} is a number and @var{time} is @code{nil}, the function -will be called once every time Emacs has been idle for @var{idle} -minutes. - -And if @var{time} is a string, it should look like @samp{07:31}, and -the function will then be called once every day somewhere near that -time. Modified by the @var{idle} parameter, of course. - -@vindex gnus-demon-timestep -(When I say ``minute'' here, I really mean @code{gnus-demon-timestep} -seconds. This is 60 by default. If you change that variable, -all the timings in the handlers will be affected.) - -So, if you want to add a handler, you could put something like this in -your @file{~/.gnus.el} file: - -@findex gnus-demon-add-handler -@lisp -(gnus-demon-add-handler 'gnus-demon-close-connections 30 t) -@end lisp - -@findex gnus-demon-add-scanmail -@findex gnus-demon-add-rescan -@findex gnus-demon-add-scan-timestamps -@findex gnus-demon-add-disconnection -Some ready-made functions to do this have been created: -@code{gnus-demon-add-disconnection}, -@code{gnus-demon-add-nntp-close-connection}, -@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and -@code{gnus-demon-add-scanmail}. Just put those functions in your -@file{~/.gnus.el} if you want those abilities. - -@findex gnus-demon-init -@findex gnus-demon-cancel -@vindex gnus-demon-handlers -If you add handlers to @code{gnus-demon-handlers} directly, you should -run @code{gnus-demon-init} to make the changes take hold. To cancel all -daemons, you can use the @code{gnus-demon-cancel} function. - -Note that adding daemons can be pretty naughty if you over do it. Adding -functions that scan all news and mail from all servers every two seconds -is a sure-fire way of getting booted off any respectable system. So -behave. - - -@node Undo -@section Undo -@cindex undo - -It is very useful to be able to undo actions one has done. In normal -Emacs buffers, it's easy enough---you just push the @code{undo} button. -In Gnus buffers, however, it isn't that simple. - -The things Gnus displays in its buffer is of no value whatsoever to -Gnus---it's all just data designed to look nice to the user. -Killing a group in the group buffer with @kbd{C-k} makes the line -disappear, but that's just a side-effect of the real action---the -removal of the group in question from the internal Gnus structures. -Undoing something like that can't be done by the normal Emacs -@code{undo} function. - -Gnus tries to remedy this somewhat by keeping track of what the user -does and coming up with actions that would reverse the actions the user -takes. When the user then presses the @code{undo} key, Gnus will run -the code to reverse the previous action, or the previous actions. -However, not all actions are easily reversible, so Gnus currently offers -a few key functions to be undoable. These include killing groups, -yanking groups, and changing the list of read articles of groups. -That's it, really. More functions may be added in the future, but each -added function means an increase in data to be stored, so Gnus will -never be totally undoable. - -@findex gnus-undo-mode -@vindex gnus-use-undo -@findex gnus-undo -The undoability is provided by the @code{gnus-undo-mode} minor mode. It -is used if @code{gnus-use-undo} is non-@code{nil}, which is the -default. The @kbd{C-M-_} key performs the @code{gnus-undo} -command, which should feel kinda like the normal Emacs @code{undo} -command. - - -@node Predicate Specifiers -@section Predicate Specifiers -@cindex predicate specifiers - -Some Gnus variables are @dfn{predicate specifiers}. This is a special -form that allows flexible specification of predicates without having -to type all that much. - -These specifiers are lists consisting of functions, symbols and lists. - -Here's an example: - -@lisp -(or gnus-article-unseen-p - gnus-article-unread-p) -@end lisp - -The available symbols are @code{or}, @code{and} and @code{not}. The -functions all take one parameter. - -@findex gnus-make-predicate -Internally, Gnus calls @code{gnus-make-predicate} on these specifiers -to create a function that can be called. This input parameter to this -function will be passed along to all the functions in the predicate -specifier. - - -@node Moderation -@section Moderation -@cindex moderation - -If you are a moderator, you can use the @file{gnus-mdrtn.el} package. -It is not included in the standard Gnus package. Write a mail to -@samp{larsi@@gnus.org} and state what group you moderate, and you'll -get a copy. - -The moderation package is implemented as a minor mode for summary -buffers. Put - -@lisp -(add-hook 'gnus-summary-mode-hook 'gnus-moderate) -@end lisp - -in your @file{~/.gnus.el} file. - -If you are the moderator of @samp{rec.zoofle}, this is how it's -supposed to work: - -@enumerate -@item -You split your incoming mail by matching on -@samp{Newsgroups:.*rec.zoofle}, which will put all the to-be-posted -articles in some mail group---for instance, @samp{nnml:rec.zoofle}. - -@item -You enter that group once in a while and post articles using the @kbd{e} -(edit-and-post) or @kbd{s} (just send unedited) commands. - -@item -If, while reading the @samp{rec.zoofle} newsgroup, you happen upon some -articles that weren't approved by you, you can cancel them with the -@kbd{c} command. -@end enumerate - -To use moderation mode in these two groups, say: - -@lisp -(setq gnus-moderated-list - "^nnml:rec.zoofle$\\|^rec.zoofle$") -@end lisp - - -@node Fetching a Group -@section Fetching a Group -@cindex fetching a group - -@findex gnus-fetch-group -It is sometimes convenient to be able to just say ``I want to read this -group and I don't care whether Gnus has been started or not''. This is -perhaps more useful for people who write code than for users, but the -command @code{gnus-fetch-group} provides this functionality in any case. -It takes the group name as a parameter. - - -@node Image Enhancements -@section Image Enhancements - -XEmacs, as well as Emacs 21@footnote{Emacs 21 on MS Windows doesn't -support images, Emacs 22 does.} and up, are able to display pictures and -stuff, so Gnus has taken advantage of that. - -@menu -* X-Face:: Display a funky, teensy black-and-white image. -* Face:: Display a funkier, teensier colored image. -* Smileys:: Show all those happy faces the way they were meant to be shown. -* Picons:: How to display pictures of what you're reading. -* Gravatars:: Display the avatar of people you read. -* XVarious:: Other XEmacsy Gnusey variables. -@end menu - - -@node X-Face -@subsection X-Face -@cindex x-face - -@code{X-Face} headers describe a 48x48 pixel black-and-white (1 bit -depth) image that's supposed to represent the author of the message. -It seems to be supported by an ever-growing number of mail and news -readers. - -@cindex x-face -@findex gnus-article-display-x-face -@vindex gnus-article-x-face-command -@vindex gnus-article-x-face-too-ugly -@iftex -@iflatex -\include{xface} -@end iflatex -@end iftex -@c @anchor{X-Face} - -Viewing an @code{X-Face} header either requires an Emacs that has -@samp{compface} support (which most XEmacs versions have), or that you -have suitable conversion or display programs installed. If your Emacs -has image support the default action is to display the face before the -@code{From} header. If there's no native @code{X-Face} support, Gnus -will try to convert the @code{X-Face} header using external programs -from the @code{pbmplus} package and friends, see below. For XEmacs it's -faster if XEmacs has been compiled with @code{X-Face} support. The -default action under Emacs without image support is to fork off the -@code{display} program. - -On a GNU/Linux system, the @code{display} program is included in the -ImageMagick package. For external conversion programs look for packages -with names like @code{netpbm}, @code{libgr-progs} and @code{compface}. -On Windows, you may use the packages @code{netpbm} and @code{compface} -from @url{http://gnuwin32.sourceforge.net}. You need to add the -@code{bin} directory to your @code{PATH} environment variable. -@c In fact only the following DLLs and binaries seem to be required: -@c compface1.dll uncompface.exe libnetpbm10.dll icontopbm.exe - -The variable @code{gnus-article-x-face-command} controls which programs -are used to display the @code{X-Face} header. If this variable is a -string, this string will be executed in a sub-shell. If it is a -function, this function will be called with the face as the argument. -If @code{gnus-article-x-face-too-ugly} (which is a regexp) matches the -@code{From} header, the face will not be shown. - -(Note: @code{x-face} is used in the variable/function names, not -@code{xface}). - -@noindent -Face and variable: - -@table @code -@item gnus-x-face -@vindex gnus-x-face -Face to show X-Face. The colors from this face are used as the -foreground and background colors of the displayed X-Faces. The -default colors are black and white. - -@item gnus-face-properties-alist -@vindex gnus-face-properties-alist -Alist of image types and properties applied to Face (@pxref{Face}) and -X-Face images. The default value is @code{((pbm . (:face gnus-x-face)) -(png . nil))} for Emacs or @code{((xface . (:face gnus-x-face)))} for -XEmacs. Here are examples: - -@lisp -;; Specify the altitude of Face and X-Face images in the From header. -(setq gnus-face-properties-alist - '((pbm . (:face gnus-x-face :ascent 80)) - (png . (:ascent 80)))) - -;; Show Face and X-Face images as pressed buttons. -(setq gnus-face-properties-alist - '((pbm . (:face gnus-x-face :relief -2)) - (png . (:relief -2)))) -@end lisp - -@pxref{Image Descriptors, ,Image Descriptors, elisp, The Emacs Lisp -Reference Manual} for the valid properties for various image types. -Currently, @code{pbm} is used for X-Face images and @code{png} is used -for Face images in Emacs. Only the @code{:face} property is effective -on the @code{xface} image type in XEmacs if it is built with the -@samp{libcompface} library. -@end table - -If you use posting styles, you can use an @code{x-face-file} entry in -@code{gnus-posting-styles}, @xref{Posting Styles}. If you don't, Gnus -provides a few convenience functions and variables to allow easier -insertion of X-Face headers in outgoing messages. You also need the -above mentioned ImageMagick, netpbm or other image conversion packages -(depending the values of the variables below) for these functions. - -@findex gnus-random-x-face -@vindex gnus-convert-pbm-to-x-face-command -@vindex gnus-x-face-directory -@code{gnus-random-x-face} goes through all the @samp{pbm} files in -@code{gnus-x-face-directory} and picks one at random, and then -converts it to the X-Face format by using the -@code{gnus-convert-pbm-to-x-face-command} shell command. The -@samp{pbm} files should be 48x48 pixels big. It returns the X-Face -header data as a string. - -@findex gnus-insert-random-x-face-header -@code{gnus-insert-random-x-face-header} calls -@code{gnus-random-x-face} and inserts a @samp{X-Face} header with the -randomly generated data. - -@findex gnus-x-face-from-file -@vindex gnus-convert-image-to-x-face-command -@code{gnus-x-face-from-file} takes a GIF file as the parameter, and then -converts the file to X-Face format by using the -@code{gnus-convert-image-to-x-face-command} shell command. - -Here's how you would typically use the first function. Put something -like the following in your @file{~/.gnus.el} file: - -@lisp -(setq message-required-news-headers - (nconc message-required-news-headers - (list '(X-Face . gnus-random-x-face)))) -@end lisp - -Using the last function would be something like this: - -@lisp -(setq message-required-news-headers - (nconc message-required-news-headers - (list '(X-Face . (lambda () - (gnus-x-face-from-file - "~/My-face.gif")))))) -@end lisp - - -@node Face -@subsection Face -@cindex face - -@c #### FIXME: faces and x-faces' implementations should really be harmonized. - -@code{Face} headers are essentially a funkier version of @code{X-Face} -ones. They describe a 48x48 pixel colored image that's supposed to -represent the author of the message. - -@cindex face -@findex gnus-article-display-face -The contents of a @code{Face} header must be a base64 encoded PNG image. -See @uref{http://quimby.gnus.org/circus/face/} for the precise -specifications. - -The @code{gnus-face-properties-alist} variable affects the appearance of -displayed Face images. @xref{X-Face}. - -Viewing a @code{Face} header requires an Emacs that is able to display -PNG images. -@c Maybe add this: -@c (if (featurep 'xemacs) -@c (featurep 'png) -@c (image-type-available-p 'png)) - -Gnus provides a few convenience functions and variables to allow -easier insertion of Face headers in outgoing messages. - -@findex gnus-convert-png-to-face -@code{gnus-convert-png-to-face} takes a 48x48 PNG image, no longer than -726 bytes long, and converts it to a face. - -@findex gnus-face-from-file -@vindex gnus-convert-image-to-face-command -@code{gnus-face-from-file} takes a JPEG file as the parameter, and then -converts the file to Face format by using the -@code{gnus-convert-image-to-face-command} shell command. - -Here's how you would typically use this function. Put something like the -following in your @file{~/.gnus.el} file: - -@lisp -(setq message-required-news-headers - (nconc message-required-news-headers - (list '(Face . (lambda () - (gnus-face-from-file "~/face.jpg")))))) -@end lisp - - -@node Smileys -@subsection Smileys -@cindex smileys - -@iftex -@iflatex -\gnusfig{-3cm}{0.5cm}{\epsfig{figure=ps/BigFace,height=20cm}} -\input{smiley} -@end iflatex -@end iftex - -@dfn{Smiley} is a package separate from Gnus, but since Gnus is -currently the only package that uses Smiley, it is documented here. - -In short---to use Smiley in Gnus, put the following in your -@file{~/.gnus.el} file: - -@lisp -(setq gnus-treat-display-smileys t) -@end lisp - -Smiley maps text smiley faces---@samp{:-)}, @samp{8-)}, @samp{:-(} and -the like---to pictures and displays those instead of the text smiley -faces. The conversion is controlled by a list of regexps that matches -text and maps that to file names. - -@vindex smiley-regexp-alist -The alist used is specified by the @code{smiley-regexp-alist} -variable. The first item in each element is the regexp to be matched; -the second element is the regexp match group that is to be replaced by -the picture; and the third element is the name of the file to be -displayed. - -The following variables customize the appearance of the smileys: - -@table @code - -@item smiley-style -@vindex smiley-style -Specifies the smiley style. Predefined smiley styles include -@code{low-color} (small 13x14 pixel, three-color images), @code{medium} -(more colorful images, 16x16 pixel), and @code{grayscale} (grayscale -images, 14x14 pixel). The default depends on the height of the default -face. - -@item smiley-data-directory -@vindex smiley-data-directory -Where Smiley will look for smiley faces files. You shouldn't set this -variable anymore. Customize @code{smiley-style} instead. - -@item gnus-smiley-file-types -@vindex gnus-smiley-file-types -List of suffixes on smiley file names to try. - -@end table - - -@node Picons -@subsection Picons - -@iftex -@iflatex -\include{picons} -@end iflatex -@end iftex - -So@dots{} You want to slow down your news reader even more! This is a -good way to do so. It's also a great way to impress people staring -over your shoulder as you read news. - -What are Picons? To quote directly from the Picons Web site: - -@iftex -@iflatex -\margindex{} -@end iflatex -@end iftex - -@quotation -@dfn{Picons} is short for ``personal icons''. They're small, -constrained images used to represent users and domains on the net, -organized into databases so that the appropriate image for a given -e-mail address can be found. Besides users and domains, there are picon -databases for Usenet newsgroups and weather forecasts. The picons are -in either monochrome @code{XBM} format or color @code{XPM} and -@code{GIF} formats. -@end quotation - -@vindex gnus-picon-databases -For instructions on obtaining and installing the picons databases, -point your Web browser at -@uref{http://www.cs.indiana.edu/picons/ftp/index.html}. - -If you are using Debian GNU/Linux, saying @samp{apt-get install -picons.*} will install the picons where Gnus can find them. - -To enable displaying picons, simply make sure that -@code{gnus-picon-databases} points to the directory containing the -Picons databases. - -@vindex gnus-picon-style -The variable @code{gnus-picon-style} controls how picons are displayed. -If @code{inline}, the textual representation is replaced. If -@code{right}, picons are added right to the textual representation. - -The following variables offer control over where things are located. - -@table @code - -@item gnus-picon-databases -@vindex gnus-picon-databases -The location of the picons database. This is a list of directories -containing the @file{news}, @file{domains}, @file{users} (and so on) -subdirectories. Defaults to @code{("/usr/lib/picon" -"/usr/local/faces")}. - -@item gnus-picon-news-directories -@vindex gnus-picon-news-directories -List of subdirectories to search in @code{gnus-picon-databases} for -newsgroups faces. @code{("news")} is the default. - -@item gnus-picon-user-directories -@vindex gnus-picon-user-directories -List of subdirectories to search in @code{gnus-picon-databases} for user -faces. @code{("users" "usenix" "local" "misc")} is the default. - -@item gnus-picon-domain-directories -@vindex gnus-picon-domain-directories -List of subdirectories to search in @code{gnus-picon-databases} for -domain name faces. Defaults to @code{("domains")}. Some people may -want to add @samp{"unknown"} to this list. - -@item gnus-picon-file-types -@vindex gnus-picon-file-types -Ordered list of suffixes on picon file names to try. Defaults to -@code{("xpm" "gif" "xbm")} minus those not built-in your Emacs. - -@item gnus-picon-inhibit-top-level-domains -@vindex gnus-picon-inhibit-top-level-domains -If non-@code{nil} (which is the default), don't display picons for -things like @samp{.net} and @samp{.de}, which aren't usually very -interesting. - -@end table - -@node Gravatars -@subsection Gravatars - -@iftex -@iflatex -\include{gravatars} -@end iflatex -@end iftex - -A gravatar is an image registered to an e-mail address. - -You can submit yours on-line at @uref{http://www.gravatar.com}. - -The following variables offer control over how things are displayed. - -@table @code - -@item gnus-gravatar-size -@vindex gnus-gravatar-size -The size in pixels of gravatars. Gravatars are always square, so one -number for the size is enough. - -@item gnus-gravatar-properties -@vindex gnus-gravatar-properties -List of image properties applied to Gravatar images. - -@item gnus-gravatar-too-ugly -@vindex gnus-gravatar-too-ugly -Regexp that matches mail addresses or names of people of which avatars -should not be displayed, or @code{nil}. It default to the value of -@code{gnus-article-x-face-too-ugly} (@pxref{X-Face}). - -@end table - -If you want to see them in the From field, set: -@lisp -(setq gnus-treat-from-gravatar 'head) -@end lisp - -If you want to see them in the Cc and To fields, set: - -@lisp -(setq gnus-treat-mail-gravatar 'head) -@end lisp - - -@node XVarious -@subsection Various XEmacs Variables - -@table @code -@item gnus-xmas-glyph-directory -@vindex gnus-xmas-glyph-directory -This is where Gnus will look for pictures. Gnus will normally -auto-detect this directory, but you may set it manually if you have an -unusual directory structure. - -@item gnus-xmas-modeline-glyph -@vindex gnus-xmas-modeline-glyph -A glyph displayed in all Gnus mode lines. It is a tiny gnu head by -default. - -@end table - -@subsubsection Toolbar - -@table @code - -@item gnus-use-toolbar -@vindex gnus-use-toolbar -This variable specifies the position to display the toolbar. If -@code{nil}, don't display toolbars. If it is non-@code{nil}, it should -be one of the symbols @code{default}, @code{top}, @code{bottom}, -@code{right}, and @code{left}. @code{default} means to use the default -toolbar, the rest mean to display the toolbar on the place which those -names show. The default is @code{default}. - -@item gnus-toolbar-thickness -@vindex gnus-toolbar-thickness -Cons of the height and the width specifying the thickness of a toolbar. -The height is used for the toolbar displayed on the top or the bottom, -the width is used for the toolbar displayed on the right or the left. -The default is that of the default toolbar. - -@item gnus-group-toolbar -@vindex gnus-group-toolbar -The toolbar in the group buffer. - -@item gnus-summary-toolbar -@vindex gnus-summary-toolbar -The toolbar in the summary buffer. - -@item gnus-summary-mail-toolbar -@vindex gnus-summary-mail-toolbar -The toolbar in the summary buffer of mail groups. - -@end table - -@iftex -@iflatex -\margindex{} -@end iflatex -@end iftex - - -@node Fuzzy Matching -@section Fuzzy Matching -@cindex fuzzy matching - -Gnus provides @dfn{fuzzy matching} of @code{Subject} lines when doing -things like scoring, thread gathering and thread comparison. - -As opposed to regular expression matching, fuzzy matching is very fuzzy. -It's so fuzzy that there's not even a definition of what @dfn{fuzziness} -means, and the implementation has changed over time. - -Basically, it tries to remove all noise from lines before comparing. -@samp{Re: }, parenthetical remarks, white space, and so on, are filtered -out of the strings before comparing the results. This often leads to -adequate results---even when faced with strings generated by text -manglers masquerading as newsreaders. - - -@node Thwarting Email Spam -@section Thwarting Email Spam -@cindex email spam -@cindex spam -@cindex UCE -@cindex unsolicited commercial email - -In these last days of the Usenet, commercial vultures are hanging about -and grepping through news like crazy to find email addresses they can -foist off their scams and products to. As a reaction to this, many -people have started putting nonsense addresses into their @code{From} -lines. I think this is counterproductive---it makes it difficult for -people to send you legitimate mail in response to things you write, as -well as making it difficult to see who wrote what. This rewriting may -perhaps be a bigger menace than the unsolicited commercial email itself -in the end. - -The biggest problem I have with email spam is that it comes in under -false pretenses. I press @kbd{g} and Gnus merrily informs me that I -have 10 new emails. I say ``Golly gee! Happy is me!'' and select the -mail group, only to find two pyramid schemes, seven advertisements -(``New! Miracle tonic for growing full, lustrous hair on your toes!'') -and one mail asking me to repent and find some god. - -This is annoying. Here's what you can do about it. - -@menu -* The problem of spam:: Some background, and some solutions -* Anti-Spam Basics:: Simple steps to reduce the amount of spam. -* SpamAssassin:: How to use external anti-spam tools. -* Hashcash:: Reduce spam by burning CPU time. -@end menu - -@node The problem of spam -@subsection The problem of spam -@cindex email spam -@cindex spam filtering approaches -@cindex filtering approaches, spam -@cindex UCE -@cindex unsolicited commercial email - -First, some background on spam. - -If you have access to e-mail, you are familiar with spam (technically -termed @acronym{UCE}, Unsolicited Commercial E-mail). Simply put, it -exists because e-mail delivery is very cheap compared to paper mail, -so only a very small percentage of people need to respond to an UCE to -make it worthwhile to the advertiser. Ironically, one of the most -common spams is the one offering a database of e-mail addresses for -further spamming. Senders of spam are usually called @emph{spammers}, -but terms like @emph{vermin}, @emph{scum}, @emph{sociopaths}, and -@emph{morons} are in common use as well. - -Spam comes from a wide variety of sources. It is simply impossible to -dispose of all spam without discarding useful messages. A good -example is the TMDA system, which requires senders -unknown to you to confirm themselves as legitimate senders before -their e-mail can reach you. Without getting into the technical side -of TMDA, a downside is clearly that e-mail from legitimate sources may -be discarded if those sources can't or won't confirm themselves -through the TMDA system. Another problem with TMDA is that it -requires its users to have a basic understanding of e-mail delivery -and processing. - -The simplest approach to filtering spam is filtering, at the mail -server or when you sort through incoming mail. If you get 200 spam -messages per day from @samp{random-address@@vmadmin.com}, you block -@samp{vmadmin.com}. If you get 200 messages about @samp{VIAGRA}, you -discard all messages with @samp{VIAGRA} in the message. If you get -lots of spam from Bulgaria, for example, you try to filter all mail -from Bulgarian IPs. - -This, unfortunately, is a great way to discard legitimate e-mail. The -risks of blocking a whole country (Bulgaria, Norway, Nigeria, China, -etc.) or even a continent (Asia, Africa, Europe, etc.) from contacting -you should be obvious, so don't do it if you have the choice. - -In another instance, the very informative and useful RISKS digest has -been blocked by overzealous mail filters because it @strong{contained} -words that were common in spam messages. Nevertheless, in isolated -cases, with great care, direct filtering of mail can be useful. - -Another approach to filtering e-mail is the distributed spam -processing, for instance DCC implements such a system. In essence, -@var{N} systems around the world agree that a machine @var{X} in -Ghana, Estonia, or California is sending out spam e-mail, and these -@var{N} systems enter @var{X} or the spam e-mail from @var{X} into a -database. The criteria for spam detection vary---it may be the number -of messages sent, the content of the messages, and so on. When a user -of the distributed processing system wants to find out if a message is -spam, he consults one of those @var{N} systems. - -Distributed spam processing works very well against spammers that send -a large number of messages at once, but it requires the user to set up -fairly complicated checks. There are commercial and free distributed -spam processing systems. Distributed spam processing has its risks as -well. For instance legitimate e-mail senders have been accused of -sending spam, and their web sites and mailing lists have been shut -down for some time because of the incident. - -The statistical approach to spam filtering is also popular. It is -based on a statistical analysis of previous spam messages. Usually -the analysis is a simple word frequency count, with perhaps pairs of -words or 3-word combinations thrown into the mix. Statistical -analysis of spam works very well in most of the cases, but it can -classify legitimate e-mail as spam in some cases. It takes time to -run the analysis, the full message must be analyzed, and the user has -to store the database of spam analysis. Statistical analysis on the -server is gaining popularity. This has the advantage of letting the -user Just Read Mail, but has the disadvantage that it's harder to tell -the server that it has misclassified mail. - -Fighting spam is not easy, no matter what anyone says. There is no -magic switch that will distinguish Viagra ads from Mom's e-mails. -Even people are having a hard time telling spam apart from non-spam, -because spammers are actively looking to fool us into thinking they -are Mom, essentially. Spamming is irritating, irresponsible, and -idiotic behavior from a bunch of people who think the world owes them -a favor. We hope the following sections will help you in fighting the -spam plague. - -@node Anti-Spam Basics -@subsection Anti-Spam Basics -@cindex email spam -@cindex spam -@cindex UCE -@cindex unsolicited commercial email - -One way of dealing with spam is having Gnus split out all spam into a -@samp{spam} mail group (@pxref{Splitting Mail}). - -First, pick one (1) valid mail address that you can be reached at, and -put it in your @code{From} header of all your news articles. (I've -chosen @samp{larsi@@trym.ifi.uio.no}, but for many addresses on the form -@samp{larsi+usenet@@ifi.uio.no} will be a better choice. Ask your -sysadmin whether your sendmail installation accepts keywords in the local -part of the mail address.) - -@lisp -(setq message-default-news-headers - "From: Lars Magne Ingebrigtsen \n") -@end lisp - -Then put the following split rule in @code{nnmail-split-fancy} -(@pxref{Fancy Mail Splitting}): - -@lisp -(... - (to "larsi@@trym.ifi.uio.no" - (| ("subject" "re:.*" "misc") - ("references" ".*@@.*" "misc") - "spam")) - ...) -@end lisp - -This says that all mail to this address is suspect, but if it has a -@code{Subject} that starts with a @samp{Re:} or has a @code{References} -header, it's probably ok. All the rest goes to the @samp{spam} group. -(This idea probably comes from Tim Pierce.) - -In addition, many mail spammers talk directly to your @acronym{SMTP} server -and do not include your email address explicitly in the @code{To} -header. Why they do this is unknown---perhaps it's to thwart this -thwarting scheme? In any case, this is trivial to deal with---you just -put anything not addressed to you in the @samp{spam} group by ending -your fancy split rule in this way: - -@lisp -( - ... - (to "larsi" "misc") - "spam") -@end lisp - -In my experience, this will sort virtually everything into the right -group. You still have to check the @samp{spam} group from time to time to -check for legitimate mail, though. If you feel like being a good net -citizen, you can even send off complaints to the proper authorities on -each unsolicited commercial email---at your leisure. - -This works for me. It allows people an easy way to contact me (they can -just press @kbd{r} in the usual way), and I'm not bothered at all with -spam. It's a win-win situation. Forging @code{From} headers to point -to non-existent domains is yucky, in my opinion. - -Be careful with this approach. Spammers are wise to it. - - -@node SpamAssassin -@subsection SpamAssassin, Vipul's Razor, DCC, etc -@cindex SpamAssassin -@cindex Vipul's Razor -@cindex DCC - -The days where the hints in the previous section were sufficient in -avoiding spam are coming to an end. There are many tools out there -that claim to reduce the amount of spam you get. This section could -easily become outdated fast, as new products replace old, but -fortunately most of these tools seem to have similar interfaces. Even -though this section will use SpamAssassin as an example, it should be -easy to adapt it to most other tools. - -Note that this section does not involve the @code{spam.el} package, -which is discussed in the next section. If you don't care for all -the features of @code{spam.el}, you can make do with these simple -recipes. - -If the tool you are using is not installed on the mail server, you -need to invoke it yourself. Ideas on how to use the -@code{:postscript} mail source parameter (@pxref{Mail Source -Specifiers}) follow. - -@lisp -(setq mail-sources - '((file :prescript "formail -bs spamassassin < /var/mail/%u") - (pop :user "jrl" - :server "pophost" - :postscript - "mv %t /tmp/foo; formail -bs spamc < /tmp/foo > %t"))) -@end lisp - -Once you manage to process your incoming spool somehow, thus making -the mail contain e.g.@: a header indicating it is spam, you are ready to -filter it out. Using normal split methods (@pxref{Splitting Mail}): - -@lisp -(setq nnmail-split-methods '(("spam" "^X-Spam-Flag: YES") - ...)) -@end lisp - -Or using fancy split methods (@pxref{Fancy Mail Splitting}): - -@lisp -(setq nnmail-split-methods 'nnmail-split-fancy - nnmail-split-fancy '(| ("X-Spam-Flag" "YES" "spam") - ...)) -@end lisp - -Some people might not like the idea of piping the mail through various -programs using a @code{:prescript} (if some program is buggy, you -might lose all mail). If you are one of them, another solution is to -call the external tools during splitting. Example fancy split method: - -@lisp -(setq nnmail-split-fancy '(| (: kevin-spamassassin) - ...)) -(defun kevin-spamassassin () - (save-excursion - (save-restriction - (widen) - (if (eq 1 (call-process-region (point-min) (point-max) - "spamc" nil nil nil "-c")) - "spam")))) -@end lisp - -Note that with the nnimap back end, message bodies will not be -downloaded by default. You need to set -@code{nnimap-split-download-body} to @code{t} to do that -(@pxref{Client-Side IMAP Splitting}). - -That is about it. As some spam is likely to get through anyway, you -might want to have a nifty function to call when you happen to read -spam. And here is the nifty function: - -@lisp -(defun my-gnus-raze-spam () - "Submit SPAM to Vipul's Razor, then mark it as expirable." - (interactive) - (gnus-summary-save-in-pipe "razor-report -f -d" t) - (gnus-summary-mark-as-expirable 1)) -@end lisp - -@node Hashcash -@subsection Hashcash -@cindex hashcash - -A novel technique to fight spam is to require senders to do something -costly and demonstrably unique for each message they send. This has -the obvious drawback that you cannot rely on everyone in the world -using this technique, since it is not part of the Internet standards, -but it may be useful in smaller communities. - -While the tools in the previous section work well in practice, they -work only because the tools are constantly maintained and updated as -new form of spam appears. This means that a small percentage of spam -will always get through. It also means that somewhere, someone needs -to read lots of spam to update these tools. Hashcash avoids that, but -instead prefers that everyone you contact through e-mail supports the -scheme. You can view the two approaches as pragmatic vs dogmatic. -The approaches have their own advantages and disadvantages, but as -often in the real world, a combination of them is stronger than either -one of them separately. - -@cindex X-Hashcash -The ``something costly'' is to burn CPU time, more specifically to -compute a hash collision up to a certain number of bits. The -resulting hashcash cookie is inserted in a @samp{X-Hashcash:} header. -For more details, and for the external application @code{hashcash} you -need to install to use this feature, see -@uref{http://www.hashcash.org/}. Even more information can be found -at @uref{http://www.camram.org/}. - -If you wish to generate hashcash for each message you send, you can -customize @code{message-generate-hashcash} (@pxref{Mail Headers, ,Mail -Headers,message, The Message Manual}), as in: - -@lisp -(setq message-generate-hashcash t) -@end lisp - -You will need to set up some additional variables as well: - -@table @code - -@item hashcash-default-payment -@vindex hashcash-default-payment -This variable indicates the default number of bits the hash collision -should consist of. By default this is 20. Suggested useful values -include 17 to 29. - -@item hashcash-payment-alist -@vindex hashcash-payment-alist -Some receivers may require you to spend burn more CPU time than the -default. This variable contains a list of @samp{(@var{addr} -@var{amount})} cells, where @var{addr} is the receiver (email address -or newsgroup) and @var{amount} is the number of bits in the collision -that is needed. It can also contain @samp{(@var{addr} @var{string} -@var{amount})} cells, where the @var{string} is the string to use -(normally the email address or newsgroup name is used). - -@item hashcash-path -@vindex hashcash-path -Where the @code{hashcash} binary is installed. This variable should -be automatically set by @code{executable-find}, but if it's @code{nil} -(usually because the @code{hashcash} binary is not in your path) -you'll get a warning when you check hashcash payments and an error -when you generate hashcash payments. - -@end table - -Gnus can verify hashcash cookies, although this can also be done by -hand customized mail filtering scripts. To verify a hashcash cookie -in a message, use the @code{mail-check-payment} function in the -@code{hashcash.el} library. You can also use the @code{spam.el} -package with the @code{spam-use-hashcash} back end to validate hashcash -cookies in incoming mail and filter mail accordingly (@pxref{Anti-spam -Hashcash Payments}). - -@node Spam Package -@section Spam Package -@cindex spam filtering -@cindex spam - -The Spam package provides Gnus with a centralized mechanism for -detecting and filtering spam. It filters new mail, and processes -messages according to whether they are spam or ham. (@dfn{Ham} is the -name used throughout this manual to indicate non-spam messages.) - -@menu -* Spam Package Introduction:: -* Filtering Incoming Mail:: -* Detecting Spam in Groups:: -* Spam and Ham Processors:: -* Spam Package Configuration Examples:: -* Spam Back Ends:: -* Extending the Spam package:: -* Spam Statistics Package:: -@end menu - -@node Spam Package Introduction -@subsection Spam Package Introduction -@cindex spam filtering -@cindex spam filtering sequence of events -@cindex spam - -You must read this section to understand how the Spam package works. -Do not skip, speed-read, or glance through this section. - -Make sure you read the section on the @code{spam.el} sequence of -events. See @xref{Extending the Spam package}. - -@cindex spam-initialize -@vindex spam-use-stat -To use the Spam package, you @strong{must} first run the function -@code{spam-initialize}: - -@example -(spam-initialize) -@end example - -This autoloads @code{spam.el} and installs the various hooks necessary -to let the Spam package do its job. In order to make use of the Spam -package, you have to set up certain group parameters and variables, -which we will describe below. All of the variables controlling the -Spam package can be found in the @samp{spam} customization group. - -There are two ``contact points'' between the Spam package and the rest -of Gnus: checking new mail for spam, and leaving a group. - -Checking new mail for spam is done in one of two ways: while splitting -incoming mail, or when you enter a group. - -The first way, checking for spam while splitting incoming mail, is -suited to mail back ends such as @code{nnml} or @code{nnimap}, where -new mail appears in a single spool file. The Spam package processes -incoming mail, and sends mail considered to be spam to a designated -``spam'' group. @xref{Filtering Incoming Mail}. - -The second way is suited to back ends such as @code{nntp}, which have -no incoming mail spool, or back ends where the server is in charge of -splitting incoming mail. In this case, when you enter a Gnus group, -the unseen or unread messages in that group are checked for spam. -Detected spam messages are marked as spam. @xref{Detecting Spam in -Groups}. - -@cindex spam back ends -In either case, you have to tell the Spam package what method to use -to detect spam messages. There are several methods, or @dfn{spam back -ends} (not to be confused with Gnus back ends!) to choose from: spam -``blacklists'' and ``whitelists'', dictionary-based filters, and so -forth. @xref{Spam Back Ends}. - -In the Gnus summary buffer, messages that have been identified as spam -always appear with a @samp{$} symbol. - -The Spam package divides Gnus groups into three categories: ham -groups, spam groups, and unclassified groups. You should mark each of -the groups you subscribe to as either a ham group or a spam group, -using the @code{spam-contents} group parameter (@pxref{Group -Parameters}). Spam groups have a special property: when you enter a -spam group, all unseen articles are marked as spam. Thus, mail split -into a spam group is automatically marked as spam. - -Identifying spam messages is only half of the Spam package's job. The -second half comes into play whenever you exit a group buffer. At this -point, the Spam package does several things: - -First, it calls @dfn{spam and ham processors} to process the articles -according to whether they are spam or ham. There is a pair of spam -and ham processors associated with each spam back end, and what the -processors do depends on the back end. At present, the main role of -spam and ham processors is for dictionary-based spam filters: they add -the contents of the messages in the group to the filter's dictionary, -to improve its ability to detect future spam. The @code{spam-process} -group parameter specifies what spam processors to use. @xref{Spam and -Ham Processors}. - -If the spam filter failed to mark a spam message, you can mark it -yourself, so that the message is processed as spam when you exit the -group: - -@table @kbd -@item $ -@itemx M-d -@itemx M s x -@itemx S x -@kindex $ (Summary) -@kindex M-d (Summary) -@kindex S x (Summary) -@kindex M s x (Summary) -@findex gnus-summary-mark-as-spam -@findex gnus-summary-mark-as-spam -Mark current article as spam, showing it with the @samp{$} mark -(@code{gnus-summary-mark-as-spam}). -@end table - -@noindent -Similarly, you can unmark an article if it has been erroneously marked -as spam. @xref{Setting Marks}. - -Normally, a ham message found in a non-ham group is not processed as -ham---the rationale is that it should be moved into a ham group for -further processing (see below). However, you can force these articles -to be processed as ham by setting -@code{spam-process-ham-in-spam-groups} and -@code{spam-process-ham-in-nonham-groups}. - -@vindex gnus-ham-process-destinations -@vindex gnus-spam-process-destinations -The second thing that the Spam package does when you exit a group is -to move ham articles out of spam groups, and spam articles out of ham -groups. Ham in a spam group is moved to the group specified by the -variable @code{gnus-ham-process-destinations}, or the group parameter -@code{ham-process-destination}. Spam in a ham group is moved to the -group specified by the variable @code{gnus-spam-process-destinations}, -or the group parameter @code{spam-process-destination}. If these -variables are not set, the articles are left in their current group. -If an article cannot be moved (e.g., with a read-only backend such -as @acronym{NNTP}), it is copied. - -If an article is moved to another group, it is processed again when -you visit the new group. Normally, this is not a problem, but if you -want each article to be processed only once, load the -@code{gnus-registry.el} package and set the variable -@code{spam-log-to-registry} to @code{t}. @xref{Spam Package -Configuration Examples}. - -Normally, spam groups ignore @code{gnus-spam-process-destinations}. -However, if you set @code{spam-move-spam-nonspam-groups-only} to -@code{nil}, spam will also be moved out of spam groups, depending on -the @code{spam-process-destination} parameter. - -The final thing the Spam package does is to mark spam articles as -expired, which is usually the right thing to do. - -If all this seems confusing, don't worry. Soon it will be as natural -as typing Lisp one-liners on a neural interface@dots{} err, sorry, that's -50 years in the future yet. Just trust us, it's not so bad. - -@node Filtering Incoming Mail -@subsection Filtering Incoming Mail -@cindex spam filtering -@cindex spam filtering incoming mail -@cindex spam - -To use the Spam package to filter incoming mail, you must first set up -fancy mail splitting. @xref{Fancy Mail Splitting}. The Spam package -defines a special splitting function that you can add to your fancy -split variable (either @code{nnmail-split-fancy} or -@code{nnimap-split-fancy}, depending on your mail back end): - -@example -(: spam-split) -@end example - -@vindex spam-split-group -@noindent -The @code{spam-split} function scans incoming mail according to your -chosen spam back end(s), and sends messages identified as spam to a -spam group. By default, the spam group is a group named @samp{spam}, -but you can change this by customizing @code{spam-split-group}. Make -sure the contents of @code{spam-split-group} are an unqualified group -name. For instance, in an @code{nnimap} server @samp{your-server}, -the value @samp{spam} means @samp{nnimap+your-server:spam}. The value -@samp{nnimap+server:spam} is therefore wrong---it gives the group -@samp{nnimap+your-server:nnimap+server:spam}. - -@code{spam-split} does not modify the contents of messages in any way. - -@vindex nnimap-split-download-body -Note for IMAP users: if you use the @code{spam-check-bogofilter}, -@code{spam-check-ifile}, and @code{spam-check-stat} spam back ends, -you should also set the variable @code{nnimap-split-download-body} to -@code{t}. These spam back ends are most useful when they can ``scan'' -the full message body. By default, the nnimap back end only retrieves -the message headers; @code{nnimap-split-download-body} tells it to -retrieve the message bodies as well. We don't set this by default -because it will slow @acronym{IMAP} down, and that is not an -appropriate decision to make on behalf of the user. @xref{Client-Side -IMAP Splitting}. - -You have to specify one or more spam back ends for @code{spam-split} -to use, by setting the @code{spam-use-*} variables. @xref{Spam Back -Ends}. Normally, @code{spam-split} simply uses all the spam back ends -you enabled in this way. However, you can tell @code{spam-split} to -use only some of them. Why this is useful? Suppose you are using the -@code{spam-use-regex-headers} and @code{spam-use-blackholes} spam back -ends, and the following split rule: - -@example - nnimap-split-fancy '(| - (any "ding" "ding") - (: spam-split) - ;; @r{default mailbox} - "mail") -@end example - -@noindent -The problem is that you want all ding messages to make it to the ding -folder. But that will let obvious spam (for example, spam detected by -SpamAssassin, and @code{spam-use-regex-headers}) through, when it's -sent to the ding list. On the other hand, some messages to the ding -list are from a mail server in the blackhole list, so the invocation -of @code{spam-split} can't be before the ding rule. - -The solution is to let SpamAssassin headers supersede ding rules, and -perform the other @code{spam-split} rules (including a second -invocation of the regex-headers check) after the ding rule. This is -done by passing a parameter to @code{spam-split}: - -@example -nnimap-split-fancy - '(| - ;; @r{spam detected by @code{spam-use-regex-headers} goes to @samp{regex-spam}} - (: spam-split "regex-spam" 'spam-use-regex-headers) - (any "ding" "ding") - ;; @r{all other spam detected by spam-split goes to @code{spam-split-group}} - (: spam-split) - ;; @r{default mailbox} - "mail") -@end example - -@noindent -This lets you invoke specific @code{spam-split} checks depending on -your particular needs, and target the results of those checks to a -particular spam group. You don't have to throw all mail into all the -spam tests. Another reason why this is nice is that messages to -mailing lists you have rules for don't have to have resource-intensive -blackhole checks performed on them. You could also specify different -spam checks for your nnmail split vs. your nnimap split. Go crazy. - -You should set the @code{spam-use-*} variables for whatever spam back -ends you intend to use. The reason is that when loading -@file{spam.el}, some conditional loading is done depending on what -@code{spam-use-xyz} variables you have set. @xref{Spam Back Ends}. - -@c @emph{TODO: spam.el needs to provide a uniform way of training all the -@c statistical databases. Some have that functionality built-in, others -@c don't.} - -@node Detecting Spam in Groups -@subsection Detecting Spam in Groups - -To detect spam when visiting a group, set the group's -@code{spam-autodetect} and @code{spam-autodetect-methods} group -parameters. These are accessible with @kbd{G c} or @kbd{G p}, as -usual (@pxref{Group Parameters}). - -You should set the @code{spam-use-*} variables for whatever spam back -ends you intend to use. The reason is that when loading -@file{spam.el}, some conditional loading is done depending on what -@code{spam-use-xyz} variables you have set. - -By default, only unseen articles are processed for spam. You can -force Gnus to recheck all messages in the group by setting the -variable @code{spam-autodetect-recheck-messages} to @code{t}. - -If you use the @code{spam-autodetect} method of checking for spam, you -can specify different spam detection methods for different groups. -For instance, the @samp{ding} group may have @code{spam-use-BBDB} as -the autodetection method, while the @samp{suspect} group may have the -@code{spam-use-blacklist} and @code{spam-use-bogofilter} methods -enabled. Unlike with @code{spam-split}, you don't have any control -over the @emph{sequence} of checks, but this is probably unimportant. - -@node Spam and Ham Processors -@subsection Spam and Ham Processors -@cindex spam filtering -@cindex spam filtering variables -@cindex spam variables -@cindex spam - -@vindex gnus-spam-process-newsgroups -Spam and ham processors specify special actions to take when you exit -a group buffer. Spam processors act on spam messages, and ham -processors on ham messages. At present, the main role of these -processors is to update the dictionaries of dictionary-based spam back -ends such as Bogofilter (@pxref{Bogofilter}) and the Spam Statistics -package (@pxref{Spam Statistics Filtering}). - -The spam and ham processors that apply to each group are determined by -the group's@code{spam-process} group parameter. If this group -parameter is not defined, they are determined by the variable -@code{gnus-spam-process-newsgroups}. - -@vindex gnus-spam-newsgroup-contents -Gnus learns from the spam you get. You have to collect your spam in -one or more spam groups, and set or customize the variable -@code{spam-junk-mailgroups} as appropriate. You can also declare -groups to contain spam by setting their group parameter -@code{spam-contents} to @code{gnus-group-spam-classification-spam}, or -by customizing the corresponding variable -@code{gnus-spam-newsgroup-contents}. The @code{spam-contents} group -parameter and the @code{gnus-spam-newsgroup-contents} variable can -also be used to declare groups as @emph{ham} groups if you set their -classification to @code{gnus-group-spam-classification-ham}. If -groups are not classified by means of @code{spam-junk-mailgroups}, -@code{spam-contents}, or @code{gnus-spam-newsgroup-contents}, they are -considered @emph{unclassified}. All groups are unclassified by -default. - -@vindex gnus-spam-mark -@cindex $ -In spam groups, all messages are considered to be spam by default: -they get the @samp{$} mark (@code{gnus-spam-mark}) when you enter the -group. If you have seen a message, had it marked as spam, then -unmarked it, it won't be marked as spam when you enter the group -thereafter. You can disable that behavior, so all unread messages -will get the @samp{$} mark, if you set the -@code{spam-mark-only-unseen-as-spam} parameter to @code{nil}. You -should remove the @samp{$} mark when you are in the group summary -buffer for every message that is not spam after all. To remove the -@samp{$} mark, you can use @kbd{M-u} to ``unread'' the article, or -@kbd{d} for declaring it read the non-spam way. When you leave a -group, all spam-marked (@samp{$}) articles are sent to a spam -processor which will study them as spam samples. - -Messages may also be deleted in various other ways, and unless -@code{ham-marks} group parameter gets overridden below, marks @samp{R} -and @samp{r} for default read or explicit delete, marks @samp{X} and -@samp{K} for automatic or explicit kills, as well as mark @samp{Y} for -low scores, are all considered to be associated with articles which -are not spam. This assumption might be false, in particular if you -use kill files or score files as means for detecting genuine spam, you -should then adjust the @code{ham-marks} group parameter. - -@defvar ham-marks -You can customize this group or topic parameter to be the list of -marks you want to consider ham. By default, the list contains the -deleted, read, killed, kill-filed, and low-score marks (the idea is -that these articles have been read, but are not spam). It can be -useful to also include the tick mark in the ham marks. It is not -recommended to make the unread mark a ham mark, because it normally -indicates a lack of classification. But you can do it, and we'll be -happy for you. -@end defvar - -@defvar spam-marks -You can customize this group or topic parameter to be the list of -marks you want to consider spam. By default, the list contains only -the spam mark. It is not recommended to change that, but you can if -you really want to. -@end defvar - -When you leave @emph{any} group, regardless of its -@code{spam-contents} classification, all spam-marked articles are sent -to a spam processor, which will study these as spam samples. If you -explicit kill a lot, you might sometimes end up with articles marked -@samp{K} which you never saw, and which might accidentally contain -spam. Best is to make sure that real spam is marked with @samp{$}, -and nothing else. - -@vindex gnus-ham-process-destinations -When you leave a @emph{spam} group, all spam-marked articles are -marked as expired after processing with the spam processor. This is -not done for @emph{unclassified} or @emph{ham} groups. Also, any -@strong{ham} articles in a spam group will be moved to a location -determined by either the @code{ham-process-destination} group -parameter or a match in the @code{gnus-ham-process-destinations} -variable, which is a list of regular expressions matched with group -names (it's easiest to customize this variable with @kbd{M-x -customize-variable @key{RET} gnus-ham-process-destinations}). Each -group name list is a standard Lisp list, if you prefer to customize -the variable manually. If the @code{ham-process-destination} -parameter is not set, ham articles are left in place. If the -@code{spam-mark-ham-unread-before-move-from-spam-group} parameter is -set, the ham articles are marked as unread before being moved. - -If ham can not be moved---because of a read-only back end such as -@acronym{NNTP}, for example, it will be copied. - -Note that you can use multiples destinations per group or regular -expression! This enables you to send your ham to a regular mail -group and to a @emph{ham training} group. - -When you leave a @emph{ham} group, all ham-marked articles are sent to -a ham processor, which will study these as non-spam samples. - -@vindex spam-process-ham-in-spam-groups -By default the variable @code{spam-process-ham-in-spam-groups} is -@code{nil}. Set it to @code{t} if you want ham found in spam groups -to be processed. Normally this is not done, you are expected instead -to send your ham to a ham group and process it there. - -@vindex spam-process-ham-in-nonham-groups -By default the variable @code{spam-process-ham-in-nonham-groups} is -@code{nil}. Set it to @code{t} if you want ham found in non-ham (spam -or unclassified) groups to be processed. Normally this is not done, -you are expected instead to send your ham to a ham group and process -it there. - -@vindex gnus-spam-process-destinations -When you leave a @emph{ham} or @emph{unclassified} group, all -@strong{spam} articles are moved to a location determined by either -the @code{spam-process-destination} group parameter or a match in the -@code{gnus-spam-process-destinations} variable, which is a list of -regular expressions matched with group names (it's easiest to -customize this variable with @kbd{M-x customize-variable @key{RET} -gnus-spam-process-destinations}). Each group name list is a standard -Lisp list, if you prefer to customize the variable manually. If the -@code{spam-process-destination} parameter is not set, the spam -articles are only expired. The group name is fully qualified, meaning -that if you see @samp{nntp:servername} before the group name in the -group buffer then you need it here as well. - -If spam can not be moved---because of a read-only back end such as -@acronym{NNTP}, for example, it will be copied. - -Note that you can use multiples destinations per group or regular -expression! This enables you to send your spam to multiple @emph{spam -training} groups. - -@vindex spam-log-to-registry -The problem with processing ham and spam is that Gnus doesn't track -this processing by default. Enable the @code{spam-log-to-registry} -variable so @code{spam.el} will use @code{gnus-registry.el} to track -what articles have been processed, and avoid processing articles -multiple times. Keep in mind that if you limit the number of registry -entries, this won't work as well as it does without a limit. - -@vindex spam-mark-only-unseen-as-spam -Set this variable if you want only unseen articles in spam groups to -be marked as spam. By default, it is set. If you set it to -@code{nil}, unread articles will also be marked as spam. - -@vindex spam-mark-ham-unread-before-move-from-spam-group -Set this variable if you want ham to be unmarked before it is moved -out of the spam group. This is very useful when you use something -like the tick mark @samp{!} to mark ham---the article will be placed -in your @code{ham-process-destination}, unmarked as if it came fresh -from the mail server. - -@vindex spam-autodetect-recheck-messages -When autodetecting spam, this variable tells @code{spam.el} whether -only unseen articles or all unread articles should be checked for -spam. It is recommended that you leave it off. - -@node Spam Package Configuration Examples -@subsection Spam Package Configuration Examples -@cindex spam filtering -@cindex spam filtering configuration examples -@cindex spam configuration examples -@cindex spam - -@subsubheading Ted's setup - -From Ted Zlatanov . -@example -;; @r{for @code{gnus-registry-split-fancy-with-parent} and spam autodetection} -;; @r{see @file{gnus-registry.el} for more information} -(gnus-registry-initialize) -(spam-initialize) - -(setq - spam-log-to-registry t ; @r{for spam autodetection} - spam-use-BBDB t - spam-use-regex-headers t ; @r{catch X-Spam-Flag (SpamAssassin)} - ;; @r{all groups with @samp{spam} in the name contain spam} - gnus-spam-newsgroup-contents - '(("spam" gnus-group-spam-classification-spam)) - ;; @r{see documentation for these} - spam-move-spam-nonspam-groups-only nil - spam-mark-only-unseen-as-spam t - spam-mark-ham-unread-before-move-from-spam-group t - ;; @r{understand what this does before you copy it to your own setup!} - ;; @r{for nnimap you'll probably want to set nnimap-split-methods, see the manual} - nnimap-split-fancy '(| - ;; @r{trace references to parents and put in their group} - (: gnus-registry-split-fancy-with-parent) - ;; @r{this will catch server-side SpamAssassin tags} - (: spam-split 'spam-use-regex-headers) - (any "ding" "ding") - ;; @r{note that spam by default will go to @samp{spam}} - (: spam-split) - ;; @r{default mailbox} - "mail")) - -;; @r{my parameters, set with @kbd{G p}} - -;; @r{all nnml groups, and all nnimap groups except} -;; @r{@samp{nnimap+mail.lifelogs.com:train} and} -;; @r{@samp{nnimap+mail.lifelogs.com:spam}: any spam goes to nnimap training,} -;; @r{because it must have been detected manually} - -((spam-process-destination . "nnimap+mail.lifelogs.com:train")) - -;; @r{all @acronym{NNTP} groups} -;; @r{autodetect spam with the blacklist and ham with the BBDB} -((spam-autodetect-methods spam-use-blacklist spam-use-BBDB) -;; @r{send all spam to the training group} - (spam-process-destination . "nnimap+mail.lifelogs.com:train")) - -;; @r{only some @acronym{NNTP} groups, where I want to autodetect spam} -((spam-autodetect . t)) - -;; @r{my nnimap @samp{nnimap+mail.lifelogs.com:spam} group} - -;; @r{this is a spam group} -((spam-contents gnus-group-spam-classification-spam) - - ;; @r{any spam (which happens when I enter for all unseen messages,} - ;; @r{because of the @code{gnus-spam-newsgroup-contents} setting above), goes to} - ;; @r{@samp{nnimap+mail.lifelogs.com:train} unless I mark it as ham} - - (spam-process-destination "nnimap+mail.lifelogs.com:train") - - ;; @r{any ham goes to my @samp{nnimap+mail.lifelogs.com:mail} folder, but} - ;; @r{also to my @samp{nnimap+mail.lifelogs.com:trainham} folder for training} - - (ham-process-destination "nnimap+mail.lifelogs.com:mail" - "nnimap+mail.lifelogs.com:trainham") - ;; @r{in this group, only @samp{!} marks are ham} - (ham-marks - (gnus-ticked-mark)) - ;; @r{remembers senders in the blacklist on the way out---this is} - ;; @r{definitely not needed, it just makes me feel better} - (spam-process (gnus-group-spam-exit-processor-blacklist))) - -;; @r{Later, on the @acronym{IMAP} server I use the @samp{train} group for training} -;; @r{SpamAssassin to recognize spam, and the @samp{trainham} group fora} -;; @r{recognizing ham---but Gnus has nothing to do with it.} - -@end example - -@subsubheading Using @code{spam.el} on an IMAP server with a statistical filter on the server -From Reiner Steib . - -My provider has set up bogofilter (in combination with @acronym{DCC}) on -the mail server (@acronym{IMAP}). Recognized spam goes to -@samp{spam.detected}, the rest goes through the normal filter rules, -i.e. to @samp{some.folder} or to @samp{INBOX}. Training on false -positives or negatives is done by copying or moving the article to -@samp{training.ham} or @samp{training.spam} respectively. A cron job on -the server feeds those to bogofilter with the suitable ham or spam -options and deletes them from the @samp{training.ham} and -@samp{training.spam} folders. - -With the following entries in @code{gnus-parameters}, @code{spam.el} -does most of the job for me: - -@lisp - ("nnimap:spam\\.detected" - (gnus-article-sort-functions '(gnus-article-sort-by-chars)) - (ham-process-destination "nnimap:INBOX" "nnimap:training.ham") - (spam-contents gnus-group-spam-classification-spam)) - ("nnimap:\\(INBOX\\|other-folders\\)" - (spam-process-destination . "nnimap:training.spam") - (spam-contents gnus-group-spam-classification-ham)) -@end lisp - -@itemize - -@item @b{The Spam folder:} - -In the folder @samp{spam.detected}, I have to check for false positives -(i.e. legitimate mails, that were wrongly judged as spam by -bogofilter or DCC). - -Because of the @code{gnus-group-spam-classification-spam} entry, all -messages are marked as spam (with @code{$}). When I find a false -positive, I mark the message with some other ham mark -(@code{ham-marks}, @ref{Spam and Ham Processors}). On group exit, -those messages are copied to both groups, @samp{INBOX} (where I want -to have the article) and @samp{training.ham} (for training bogofilter) -and deleted from the @samp{spam.detected} folder. - -The @code{gnus-article-sort-by-chars} entry simplifies detection of -false positives for me. I receive lots of worms (sweN, @dots{}), that all -have a similar size. Grouping them by size (i.e. chars) makes finding -other false positives easier. (Of course worms aren't @i{spam} -(@acronym{UCE}, @acronym{UBE}) strictly speaking. Anyhow, bogofilter is -an excellent tool for filtering those unwanted mails for me.) - -@item @b{Ham folders:} - -In my ham folders, I just hit @kbd{S x} -(@code{gnus-summary-mark-as-spam}) whenever I see an unrecognized spam -mail (false negative). On group exit, those messages are moved to -@samp{training.spam}. -@end itemize - -@subsubheading Reporting spam articles in Gmane groups with @code{spam-report.el} - -From Reiner Steib . - -With following entry in @code{gnus-parameters}, @kbd{S x} -(@code{gnus-summary-mark-as-spam}) marks articles in @code{gmane.*} -groups as spam and reports the to Gmane at group exit: - -@lisp - ("^gmane\\." - (spam-process (gnus-group-spam-exit-processor-report-gmane))) -@end lisp - -Additionally, I use @code{(setq spam-report-gmane-use-article-number nil)} -because I don't read the groups directly from news.gmane.org, but -through my local news server (leafnode). I.e. the article numbers are -not the same as on news.gmane.org, thus @code{spam-report.el} has to check -the @code{X-Report-Spam} header to find the correct number. - -@node Spam Back Ends -@subsection Spam Back Ends -@cindex spam back ends - -The spam package offers a variety of back ends for detecting spam. -Each back end defines a set of methods for detecting spam -(@pxref{Filtering Incoming Mail}, @pxref{Detecting Spam in Groups}), -and a pair of spam and ham processors (@pxref{Spam and Ham -Processors}). - -@menu -* Blacklists and Whitelists:: -* BBDB Whitelists:: -* Gmane Spam Reporting:: -* Anti-spam Hashcash Payments:: -* Blackholes:: -* Regular Expressions Header Matching:: -* Bogofilter:: -* SpamAssassin back end:: -* ifile spam filtering:: -* Spam Statistics Filtering:: -* SpamOracle:: -@end menu - -@node Blacklists and Whitelists -@subsubsection Blacklists and Whitelists -@cindex spam filtering -@cindex whitelists, spam filtering -@cindex blacklists, spam filtering -@cindex spam - -@defvar spam-use-blacklist - -Set this variable to @code{t} if you want to use blacklists when -splitting incoming mail. Messages whose senders are in the blacklist -will be sent to the @code{spam-split-group}. This is an explicit -filter, meaning that it acts only on mail senders @emph{declared} to -be spammers. - -@end defvar - -@defvar spam-use-whitelist - -Set this variable to @code{t} if you want to use whitelists when -splitting incoming mail. Messages whose senders are not in the -whitelist will be sent to the next spam-split rule. This is an -explicit filter, meaning that unless someone is in the whitelist, their -messages are not assumed to be spam or ham. - -@end defvar - -@defvar spam-use-whitelist-exclusive - -Set this variable to @code{t} if you want to use whitelists as an -implicit filter, meaning that every message will be considered spam -unless the sender is in the whitelist. Use with care. - -@end defvar - -@defvar gnus-group-spam-exit-processor-blacklist - -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the senders of -spam-marked articles will be added to the blacklist. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-blacklist}, it is recommended -that you use @code{(spam spam-use-blacklist)}. Everything will work -the same way, we promise. - -@end defvar - -@defvar gnus-group-ham-exit-processor-whitelist - -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the senders of -ham-marked articles in @emph{ham} groups will be added to the -whitelist. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-whitelist}, it is recommended -that you use @code{(ham spam-use-whitelist)}. Everything will work -the same way, we promise. - -@end defvar - -Blacklists are lists of regular expressions matching addresses you -consider to be spam senders. For instance, to block mail from any -sender at @samp{vmadmin.com}, you can put @samp{vmadmin.com} in your -blacklist. You start out with an empty blacklist. Blacklist entries -use the Emacs regular expression syntax. - -Conversely, whitelists tell Gnus what addresses are considered -legitimate. All messages from whitelisted addresses are considered -non-spam. Also see @ref{BBDB Whitelists}. Whitelist entries use the -Emacs regular expression syntax. - -The blacklist and whitelist file locations can be customized with the -@code{spam-directory} variable (@file{~/News/spam} by default), or -the @code{spam-whitelist} and @code{spam-blacklist} variables -directly. The whitelist and blacklist files will by default be in the -@code{spam-directory} directory, named @file{whitelist} and -@file{blacklist} respectively. - -@node BBDB Whitelists -@subsubsection BBDB Whitelists -@cindex spam filtering -@cindex BBDB whitelists, spam filtering -@cindex BBDB, spam filtering -@cindex spam - -@defvar spam-use-BBDB - -Analogous to @code{spam-use-whitelist} (@pxref{Blacklists and -Whitelists}), but uses the BBDB as the source of whitelisted -addresses, without regular expressions. You must have the BBDB loaded -for @code{spam-use-BBDB} to work properly. Messages whose senders are -not in the BBDB will be sent to the next spam-split rule. This is an -explicit filter, meaning that unless someone is in the BBDB, their -messages are not assumed to be spam or ham. - -@end defvar - -@defvar spam-use-BBDB-exclusive - -Set this variable to @code{t} if you want to use the BBDB as an -implicit filter, meaning that every message will be considered spam -unless the sender is in the BBDB. Use with care. Only sender -addresses in the BBDB will be allowed through; all others will be -classified as spammers. - -While @code{spam-use-BBDB-exclusive} @emph{can} be used as an alias -for @code{spam-use-BBDB} as far as @code{spam.el} is concerned, it is -@emph{not} a separate back end. If you set -@code{spam-use-BBDB-exclusive} to t, @emph{all} your BBDB splitting -will be exclusive. - -@end defvar - -@defvar gnus-group-ham-exit-processor-BBDB - -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the senders of -ham-marked articles in @emph{ham} groups will be added to the -BBDB. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-BBDB}, it is recommended -that you use @code{(ham spam-use-BBDB)}. Everything will work -the same way, we promise. - -@end defvar - -@node Gmane Spam Reporting -@subsubsection Gmane Spam Reporting -@cindex spam reporting -@cindex Gmane, spam reporting -@cindex Gmane, spam reporting -@cindex spam - -@defvar gnus-group-spam-exit-processor-report-gmane - -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the spam-marked -articles groups will be reported to the Gmane administrators via a -HTTP request. - -Gmane can be found at @uref{http://gmane.org}. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-report-gmane}, it is recommended -that you use @code{(spam spam-use-gmane)}. Everything will work the -same way, we promise. - -@end defvar - -@defvar spam-report-gmane-use-article-number - -This variable is @code{t} by default. Set it to @code{nil} if you are -running your own news server, for instance, and the local article -numbers don't correspond to the Gmane article numbers. When -@code{spam-report-gmane-use-article-number} is @code{nil}, -@code{spam-report.el} will fetch the number from the article headers. - -@end defvar - -@defvar spam-report-user-mail-address - -Mail address exposed in the User-Agent spam reports to Gmane. It allows -the Gmane administrators to contact you in case of misreports. The -default is @code{user-mail-address}. - -@end defvar - -@node Anti-spam Hashcash Payments -@subsubsection Anti-spam Hashcash Payments -@cindex spam filtering -@cindex hashcash, spam filtering -@cindex spam - -@defvar spam-use-hashcash - -Similar to @code{spam-use-whitelist} (@pxref{Blacklists and -Whitelists}), but uses hashcash tokens for whitelisting messages -instead of the sender address. Messages without a hashcash payment -token will be sent to the next spam-split rule. This is an explicit -filter, meaning that unless a hashcash token is found, the messages -are not assumed to be spam or ham. - -@end defvar - -@node Blackholes -@subsubsection Blackholes -@cindex spam filtering -@cindex blackholes, spam filtering -@cindex spam - -@defvar spam-use-blackholes - -This option is disabled by default. You can let Gnus consult the -blackhole-type distributed spam processing systems (DCC, for instance) -when you set this option. The variable @code{spam-blackhole-servers} -holds the list of blackhole servers Gnus will consult. The current -list is fairly comprehensive, but make sure to let us know if it -contains outdated servers. - -The blackhole check uses the @code{dig.el} package, but you can tell -@code{spam.el} to use @code{dns.el} instead for better performance if -you set @code{spam-use-dig} to @code{nil}. It is not recommended at -this time to set @code{spam-use-dig} to @code{nil} despite the -possible performance improvements, because some users may be unable to -use it, but you can try it and see if it works for you. - -@end defvar - -@defvar spam-blackhole-servers - -The list of servers to consult for blackhole checks. - -@end defvar - -@defvar spam-blackhole-good-server-regex - -A regular expression for IPs that should not be checked against the -blackhole server list. When set to @code{nil}, it has no effect. - -@end defvar - -@defvar spam-use-dig - -Use the @code{dig.el} package instead of the @code{dns.el} package. -The default setting of @code{t} is recommended. - -@end defvar - -Blackhole checks are done only on incoming mail. There is no spam or -ham processor for blackholes. - -@node Regular Expressions Header Matching -@subsubsection Regular Expressions Header Matching -@cindex spam filtering -@cindex regular expressions header matching, spam filtering -@cindex spam - -@defvar spam-use-regex-headers - -This option is disabled by default. You can let Gnus check the -message headers against lists of regular expressions when you set this -option. The variables @code{spam-regex-headers-spam} and -@code{spam-regex-headers-ham} hold the list of regular expressions. -Gnus will check against the message headers to determine if the -message is spam or ham, respectively. - -@end defvar - -@defvar spam-regex-headers-spam - -The list of regular expressions that, when matched in the headers of -the message, positively identify it as spam. - -@end defvar - -@defvar spam-regex-headers-ham - -The list of regular expressions that, when matched in the headers of -the message, positively identify it as ham. - -@end defvar - -Regular expression header checks are done only on incoming mail. -There is no specific spam or ham processor for regular expressions. - -@node Bogofilter -@subsubsection Bogofilter -@cindex spam filtering -@cindex bogofilter, spam filtering -@cindex spam - -@defvar spam-use-bogofilter - -Set this variable if you want @code{spam-split} to use Eric Raymond's -speedy Bogofilter. - -With a minimum of care for associating the @samp{$} mark for spam -articles only, Bogofilter training all gets fairly automatic. You -should do this until you get a few hundreds of articles in each -category, spam or not. The command @kbd{S t} in summary mode, either -for debugging or for curiosity, shows the @emph{spamicity} score of -the current article (between 0.0 and 1.0). - -Bogofilter determines if a message is spam based on a specific -threshold. That threshold can be customized, consult the Bogofilter -documentation. - -If the @code{bogofilter} executable is not in your path, Bogofilter -processing will be turned off. - -You should not enable this if you use @code{spam-use-bogofilter-headers}. - -@end defvar - -@table @kbd -@item M s t -@itemx S t -@kindex M s t -@kindex S t -@findex spam-bogofilter-score -Get the Bogofilter spamicity score (@code{spam-bogofilter-score}). -@end table - -@defvar spam-use-bogofilter-headers - -Set this variable if you want @code{spam-split} to use Eric Raymond's -speedy Bogofilter, looking only at the message headers. It works -similarly to @code{spam-use-bogofilter}, but the @code{X-Bogosity} header -must be in the message already. Normally you would do this with a -procmail recipe or something similar; consult the Bogofilter -installation documents for details. - -You should not enable this if you use @code{spam-use-bogofilter}. - -@end defvar - -@defvar gnus-group-spam-exit-processor-bogofilter -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, spam-marked articles -will be added to the Bogofilter spam database. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-bogofilter}, it is recommended -that you use @code{(spam spam-use-bogofilter)}. Everything will work -the same way, we promise. -@end defvar - -@defvar gnus-group-ham-exit-processor-bogofilter -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the ham-marked -articles in @emph{ham} groups will be added to the Bogofilter database -of non-spam messages. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-bogofilter}, it is recommended -that you use @code{(ham spam-use-bogofilter)}. Everything will work -the same way, we promise. -@end defvar - -@defvar spam-bogofilter-database-directory - -This is the directory where Bogofilter will store its databases. It -is not specified by default, so Bogofilter will use its own default -database directory. - -@end defvar - -The Bogofilter mail classifier is similar to @command{ifile} in intent and -purpose. A ham and a spam processor are provided, plus the -@code{spam-use-bogofilter} and @code{spam-use-bogofilter-headers} -variables to indicate to spam-split that Bogofilter should either be -used, or has already been used on the article. The 0.9.2.1 version of -Bogofilter was used to test this functionality. - -@node SpamAssassin back end -@subsubsection SpamAssassin back end -@cindex spam filtering -@cindex spamassassin, spam filtering -@cindex spam - -@defvar spam-use-spamassassin - -Set this variable if you want @code{spam-split} to use SpamAssassin. - -SpamAssassin assigns a score to each article based on a set of rules -and tests, including a Bayesian filter. The Bayesian filter can be -trained by associating the @samp{$} mark for spam articles. The -spam score can be viewed by using the command @kbd{S t} in summary -mode. - -If you set this variable, each article will be processed by -SpamAssassin when @code{spam-split} is called. If your mail is -preprocessed by SpamAssassin, and you want to just use the -SpamAssassin headers, set @code{spam-use-spamassassin-headers} -instead. - -You should not enable this if you use -@code{spam-use-spamassassin-headers}. - -@end defvar - -@defvar spam-use-spamassassin-headers - -Set this variable if your mail is preprocessed by SpamAssassin and -want @code{spam-split} to split based on the SpamAssassin headers. - -You should not enable this if you use @code{spam-use-spamassassin}. - -@end defvar - -@defvar spam-spamassassin-program - -This variable points to the SpamAssassin executable. If you have -@code{spamd} running, you can set this variable to the @code{spamc} -executable for faster processing. See the SpamAssassin documentation -for more information on @code{spamd}/@code{spamc}. - -@end defvar - -SpamAssassin is a powerful and flexible spam filter that uses a wide -variety of tests to identify spam. A ham and a spam processors are -provided, plus the @code{spam-use-spamassassin} and -@code{spam-use-spamassassin-headers} variables to indicate to -spam-split that SpamAssassin should be either used, or has already -been used on the article. The 2.63 version of SpamAssassin was used -to test this functionality. - -@node ifile spam filtering -@subsubsection ifile spam filtering -@cindex spam filtering -@cindex ifile, spam filtering -@cindex spam - -@defvar spam-use-ifile - -Enable this variable if you want @code{spam-split} to use @command{ifile}, a -statistical analyzer similar to Bogofilter. - -@end defvar - -@defvar spam-ifile-all-categories - -Enable this variable if you want @code{spam-use-ifile} to give you all -the ifile categories, not just spam/non-spam. If you use this, make -sure you train ifile as described in its documentation. - -@end defvar - -@defvar spam-ifile-spam-category - -This is the category of spam messages as far as ifile is concerned. -The actual string used is irrelevant, but you probably want to leave -the default value of @samp{spam}. -@end defvar - -@defvar spam-ifile-database - -This is the filename for the ifile database. It is not specified by -default, so ifile will use its own default database name. - -@end defvar - -The ifile mail classifier is similar to Bogofilter in intent and -purpose. A ham and a spam processor are provided, plus the -@code{spam-use-ifile} variable to indicate to spam-split that ifile -should be used. The 1.2.1 version of ifile was used to test this -functionality. - -@node Spam Statistics Filtering -@subsubsection Spam Statistics Filtering -@cindex spam filtering -@cindex spam-stat, spam filtering -@cindex spam-stat -@cindex spam - -This back end uses the Spam Statistics Emacs Lisp package to perform -statistics-based filtering (@pxref{Spam Statistics Package}). Before -using this, you may want to perform some additional steps to -initialize your Spam Statistics dictionary. @xref{Creating a -spam-stat dictionary}. - -@defvar spam-use-stat - -@end defvar - -@defvar gnus-group-spam-exit-processor-stat -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the spam-marked -articles will be added to the spam-stat database of spam messages. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-stat}, it is recommended -that you use @code{(spam spam-use-stat)}. Everything will work -the same way, we promise. -@end defvar - -@defvar gnus-group-ham-exit-processor-stat -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the ham-marked -articles in @emph{ham} groups will be added to the spam-stat database -of non-spam messages. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-stat}, it is recommended -that you use @code{(ham spam-use-stat)}. Everything will work -the same way, we promise. -@end defvar - -This enables @code{spam.el} to cooperate with @file{spam-stat.el}. -@file{spam-stat.el} provides an internal (Lisp-only) spam database, -which unlike ifile or Bogofilter does not require external programs. -A spam and a ham processor, and the @code{spam-use-stat} variable for -@code{spam-split} are provided. - -@node SpamOracle -@subsubsection Using SpamOracle with Gnus -@cindex spam filtering -@cindex SpamOracle -@cindex spam - -An easy way to filter out spam is to use SpamOracle. SpamOracle is an -statistical mail filtering tool written by Xavier Leroy and needs to be -installed separately. - -There are several ways to use SpamOracle with Gnus. In all cases, your -mail is piped through SpamOracle in its @emph{mark} mode. SpamOracle will -then enter an @samp{X-Spam} header indicating whether it regards the -mail as a spam mail or not. - -One possibility is to run SpamOracle as a @code{:prescript} from the -@xref{Mail Source Specifiers}, (@pxref{SpamAssassin}). This method has -the advantage that the user can see the @emph{X-Spam} headers. - -The easiest method is to make @file{spam.el} (@pxref{Spam Package}) -call SpamOracle. - -@vindex spam-use-spamoracle -To enable SpamOracle usage by @code{spam.el}, set the variable -@code{spam-use-spamoracle} to @code{t} and configure the -@code{nnmail-split-fancy} or @code{nnimap-split-fancy}. @xref{Spam -Package}. In this example the @samp{INBOX} of an nnimap server is -filtered using SpamOracle. Mails recognized as spam mails will be -moved to @code{spam-split-group}, @samp{Junk} in this case. Ham -messages stay in @samp{INBOX}: - -@example -(setq spam-use-spamoracle t - spam-split-group "Junk" - ;; @r{for nnimap you'll probably want to set nnimap-split-methods, see the manual} - nnimap-split-inbox '("INBOX") - nnimap-split-fancy '(| (: spam-split) "INBOX")) -@end example - -@defvar spam-use-spamoracle -Set to @code{t} if you want Gnus to enable spam filtering using -SpamOracle. -@end defvar - -@defvar spam-spamoracle-binary -Gnus uses the SpamOracle binary called @file{spamoracle} found in the -user's PATH. Using the variable @code{spam-spamoracle-binary}, this -can be customized. -@end defvar - -@defvar spam-spamoracle-database -By default, SpamOracle uses the file @file{~/.spamoracle.db} as a database to -store its analysis. This is controlled by the variable -@code{spam-spamoracle-database} which defaults to @code{nil}. That means -the default SpamOracle database will be used. In case you want your -database to live somewhere special, set -@code{spam-spamoracle-database} to this path. -@end defvar - -SpamOracle employs a statistical algorithm to determine whether a -message is spam or ham. In order to get good results, meaning few -false hits or misses, SpamOracle needs training. SpamOracle learns -the characteristics of your spam mails. Using the @emph{add} mode -(training mode) one has to feed good (ham) and spam mails to -SpamOracle. This can be done by pressing @kbd{|} in the Summary -buffer and pipe the mail to a SpamOracle process or using -@file{spam.el}'s spam- and ham-processors, which is much more -convenient. For a detailed description of spam- and ham-processors, -@xref{Spam Package}. - -@defvar gnus-group-spam-exit-processor-spamoracle -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameter or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is added -to a group's @code{spam-process} parameter, spam-marked articles will be -sent to SpamOracle as spam samples. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-spamoracle}, it is recommended -that you use @code{(spam spam-use-spamoracle)}. Everything will work -the same way, we promise. -@end defvar - -@defvar gnus-group-ham-exit-processor-spamoracle -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameter or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is added -to a group's @code{spam-process} parameter, the ham-marked articles in -@emph{ham} groups will be sent to the SpamOracle as samples of ham -messages. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-spamoracle}, it is recommended -that you use @code{(ham spam-use-spamoracle)}. Everything will work -the same way, we promise. -@end defvar - -@emph{Example:} These are the Group Parameters of a group that has been -classified as a ham group, meaning that it should only contain ham -messages. -@example - ((spam-contents gnus-group-spam-classification-ham) - (spam-process ((ham spam-use-spamoracle) - (spam spam-use-spamoracle)))) -@end example -For this group the @code{spam-use-spamoracle} is installed for both -ham and spam processing. If the group contains spam message -(e.g. because SpamOracle has not had enough sample messages yet) and -the user marks some messages as spam messages, these messages will be -processed by SpamOracle. The processor sends the messages to -SpamOracle as new samples for spam. - -@node Extending the Spam package -@subsection Extending the Spam package -@cindex spam filtering -@cindex spam elisp package, extending -@cindex extending the spam elisp package - -Say you want to add a new back end called blackbox. For filtering -incoming mail, provide the following: - -@enumerate - -@item -Code - -@lisp -(defvar spam-use-blackbox nil - "True if blackbox should be used.") -@end lisp - -Write @code{spam-check-blackbox} if Blackbox can check incoming mail. - -Write @code{spam-blackbox-register-routine} and -@code{spam-blackbox-unregister-routine} using the bogofilter -register/unregister routines as a start, or other register/unregister -routines more appropriate to Blackbox, if Blackbox can -register/unregister spam and ham. - -@item -Functionality - -The @code{spam-check-blackbox} function should return @samp{nil} or -@code{spam-split-group}, observing the other conventions. See the -existing @code{spam-check-*} functions for examples of what you can -do, and stick to the template unless you fully understand the reasons -why you aren't. - -@end enumerate - -For processing spam and ham messages, provide the following: - -@enumerate - -@item -Code - -Note you don't have to provide a spam or a ham processor. Only -provide them if Blackbox supports spam or ham processing. - -Also, ham and spam processors are being phased out as single -variables. Instead the form @code{(spam spam-use-blackbox)} or -@code{(ham spam-use-blackbox)} is favored. For now, spam/ham -processor variables are still around but they won't be for long. - -@lisp -(defvar gnus-group-spam-exit-processor-blackbox "blackbox-spam" - "The Blackbox summary exit spam processor. -Only applicable to spam groups.") - -(defvar gnus-group-ham-exit-processor-blackbox "blackbox-ham" - "The whitelist summary exit ham processor. -Only applicable to non-spam (unclassified and ham) groups.") - -@end lisp - -@item -Gnus parameters - -Add -@lisp -(const :tag "Spam: Blackbox" (spam spam-use-blackbox)) -(const :tag "Ham: Blackbox" (ham spam-use-blackbox)) -@end lisp -to the @code{spam-process} group parameter in @code{gnus.el}. Make -sure you do it twice, once for the parameter and once for the -variable customization. - -Add -@lisp -(variable-item spam-use-blackbox) -@end lisp -to the @code{spam-autodetect-methods} group parameter in -@code{gnus.el} if Blackbox can check incoming mail for spam contents. - -Finally, use the appropriate @code{spam-install-*-backend} function in -@code{spam.el}. Here are the available functions. - - -@enumerate - -@item -@code{spam-install-backend-alias} - -This function will simply install an alias for a back end that does -everything like the original back end. It is currently only used to -make @code{spam-use-BBDB-exclusive} act like @code{spam-use-BBDB}. - -@item -@code{spam-install-nocheck-backend} - -This function installs a back end that has no check function, but can -register/unregister ham or spam. The @code{spam-use-gmane} back end is -such a back end. - -@item -@code{spam-install-checkonly-backend} - -This function will install a back end that can only check incoming mail -for spam contents. It can't register or unregister messages. -@code{spam-use-blackholes} and @code{spam-use-hashcash} are such -back ends. - -@item -@code{spam-install-statistical-checkonly-backend} - -This function installs a statistical back end (one which requires the -full body of a message to check it) that can only check incoming mail -for contents. @code{spam-use-regex-body} is such a filter. - -@item -@code{spam-install-statistical-backend} - -This function install a statistical back end with incoming checks and -registration/unregistration routines. @code{spam-use-bogofilter} is -set up this way. - -@item -@code{spam-install-backend} - -This is the most normal back end installation, where a back end that can -check and register/unregister messages is set up without statistical -abilities. The @code{spam-use-BBDB} is such a back end. - -@item -@code{spam-install-mover-backend} - -Mover back ends are internal to @code{spam.el} and specifically move -articles around when the summary is exited. You will very probably -never install such a back end. -@end enumerate - -@end enumerate - -@node Spam Statistics Package -@subsection Spam Statistics Package -@cindex Paul Graham -@cindex Graham, Paul -@cindex naive Bayesian spam filtering -@cindex Bayesian spam filtering, naive -@cindex spam filtering, naive Bayesian - -Paul Graham has written an excellent essay about spam filtering using -statistics: @uref{http://www.paulgraham.com/spam.html,A Plan for -Spam}. In it he describes the inherent deficiency of rule-based -filtering as used by SpamAssassin, for example: Somebody has to write -the rules, and everybody else has to install these rules. You are -always late. It would be much better, he argues, to filter mail based -on whether it somehow resembles spam or non-spam. One way to measure -this is word distribution. He then goes on to describe a solution -that checks whether a new mail resembles any of your other spam mails -or not. - -The basic idea is this: Create a two collections of your mail, one -with spam, one with non-spam. Count how often each word appears in -either collection, weight this by the total number of mails in the -collections, and store this information in a dictionary. For every -word in a new mail, determine its probability to belong to a spam or a -non-spam mail. Use the 15 most conspicuous words, compute the total -probability of the mail being spam. If this probability is higher -than a certain threshold, the mail is considered to be spam. - -The Spam Statistics package adds support to Gnus for this kind of -filtering. It can be used as one of the back ends of the Spam package -(@pxref{Spam Package}), or by itself. - -Before using the Spam Statistics package, you need to set it up. -First, you need two collections of your mail, one with spam, one with -non-spam. Then you need to create a dictionary using these two -collections, and save it. And last but not least, you need to use -this dictionary in your fancy mail splitting rules. - -@menu -* Creating a spam-stat dictionary:: -* Splitting mail using spam-stat:: -* Low-level interface to the spam-stat dictionary:: -@end menu - -@node Creating a spam-stat dictionary -@subsubsection Creating a spam-stat dictionary - -Before you can begin to filter spam based on statistics, you must -create these statistics based on two mail collections, one with spam, -one with non-spam. These statistics are then stored in a dictionary -for later use. In order for these statistics to be meaningful, you -need several hundred emails in both collections. - -Gnus currently supports only the nnml back end for automated dictionary -creation. The nnml back end stores all mails in a directory, one file -per mail. Use the following: - -@defun spam-stat-process-spam-directory -Create spam statistics for every file in this directory. Every file -is treated as one spam mail. -@end defun - -@defun spam-stat-process-non-spam-directory -Create non-spam statistics for every file in this directory. Every -file is treated as one non-spam mail. -@end defun - -Usually you would call @code{spam-stat-process-spam-directory} on a -directory such as @file{~/Mail/mail/spam} (this usually corresponds to -the group @samp{nnml:mail.spam}), and you would call -@code{spam-stat-process-non-spam-directory} on a directory such as -@file{~/Mail/mail/misc} (this usually corresponds to the group -@samp{nnml:mail.misc}). - -When you are using @acronym{IMAP}, you won't have the mails available -locally, so that will not work. One solution is to use the Gnus Agent -to cache the articles. Then you can use directories such as -@file{"~/News/agent/nnimap/mail.yourisp.com/personal_spam"} for -@code{spam-stat-process-spam-directory}. @xref{Agent as Cache}. - -@defvar spam-stat -This variable holds the hash-table with all the statistics---the -dictionary we have been talking about. For every word in either -collection, this hash-table stores a vector describing how often the -word appeared in spam and often it appeared in non-spam mails. -@end defvar - -If you want to regenerate the statistics from scratch, you need to -reset the dictionary. - -@defun spam-stat-reset -Reset the @code{spam-stat} hash-table, deleting all the statistics. -@end defun - -When you are done, you must save the dictionary. The dictionary may -be rather large. If you will not update the dictionary incrementally -(instead, you will recreate it once a month, for example), then you -can reduce the size of the dictionary by deleting all words that did -not appear often enough or that do not clearly belong to only spam or -only non-spam mails. - -@defun spam-stat-reduce-size -Reduce the size of the dictionary. Use this only if you do not want -to update the dictionary incrementally. -@end defun - -@defun spam-stat-save -Save the dictionary. -@end defun - -@defvar spam-stat-file -The filename used to store the dictionary. This defaults to -@file{~/.spam-stat.el}. -@end defvar - -@node Splitting mail using spam-stat -@subsubsection Splitting mail using spam-stat - -This section describes how to use the Spam statistics -@emph{independently} of the @xref{Spam Package}. - -First, add the following to your @file{~/.gnus.el} file: - -@lisp -(require 'spam-stat) -(spam-stat-load) -@end lisp - -This will load the necessary Gnus code, and the dictionary you -created. - -Next, you need to adapt your fancy splitting rules: You need to -determine how to use @code{spam-stat}. The following examples are for -the nnml back end. Using the nnimap back end works just as well. Just -use @code{nnimap-split-fancy} instead of @code{nnmail-split-fancy}. - -In the simplest case, you only have two groups, @samp{mail.misc} and -@samp{mail.spam}. The following expression says that mail is either -spam or it should go into @samp{mail.misc}. If it is spam, then -@code{spam-stat-split-fancy} will return @samp{mail.spam}. - -@lisp -(setq nnmail-split-fancy - `(| (: spam-stat-split-fancy) - "mail.misc")) -@end lisp - -@defvar spam-stat-split-fancy-spam-group -The group to use for spam. Default is @samp{mail.spam}. -@end defvar - -If you also filter mail with specific subjects into other groups, use -the following expression. Only mails not matching the regular -expression are considered potential spam. - -@lisp -(setq nnmail-split-fancy - `(| ("Subject" "\\bspam-stat\\b" "mail.emacs") - (: spam-stat-split-fancy) - "mail.misc")) -@end lisp - -If you want to filter for spam first, then you must be careful when -creating the dictionary. Note that @code{spam-stat-split-fancy} must -consider both mails in @samp{mail.emacs} and in @samp{mail.misc} as -non-spam, therefore both should be in your collection of non-spam -mails, when creating the dictionary! - -@lisp -(setq nnmail-split-fancy - `(| (: spam-stat-split-fancy) - ("Subject" "\\bspam-stat\\b" "mail.emacs") - "mail.misc")) -@end lisp - -You can combine this with traditional filtering. Here, we move all -HTML-only mails into the @samp{mail.spam.filtered} group. Note that since -@code{spam-stat-split-fancy} will never see them, the mails in -@samp{mail.spam.filtered} should be neither in your collection of spam mails, -nor in your collection of non-spam mails, when creating the -dictionary! - -@lisp -(setq nnmail-split-fancy - `(| ("Content-Type" "text/html" "mail.spam.filtered") - (: spam-stat-split-fancy) - ("Subject" "\\bspam-stat\\b" "mail.emacs") - "mail.misc")) -@end lisp - - -@node Low-level interface to the spam-stat dictionary -@subsubsection Low-level interface to the spam-stat dictionary - -The main interface to using @code{spam-stat}, are the following functions: - -@defun spam-stat-buffer-is-spam -Called in a buffer, that buffer is considered to be a new spam mail. -Use this for new mail that has not been processed before. -@end defun - -@defun spam-stat-buffer-is-no-spam -Called in a buffer, that buffer is considered to be a new non-spam -mail. Use this for new mail that has not been processed before. -@end defun - -@defun spam-stat-buffer-change-to-spam -Called in a buffer, that buffer is no longer considered to be normal -mail but spam. Use this to change the status of a mail that has -already been processed as non-spam. -@end defun - -@defun spam-stat-buffer-change-to-non-spam -Called in a buffer, that buffer is no longer considered to be spam but -normal mail. Use this to change the status of a mail that has already -been processed as spam. -@end defun - -@defun spam-stat-save -Save the hash table to the file. The filename used is stored in the -variable @code{spam-stat-file}. -@end defun - -@defun spam-stat-load -Load the hash table from a file. The filename used is stored in the -variable @code{spam-stat-file}. -@end defun - -@defun spam-stat-score-word -Return the spam score for a word. -@end defun - -@defun spam-stat-score-buffer -Return the spam score for a buffer. -@end defun - -@defun spam-stat-split-fancy -Use this function for fancy mail splitting. Add the rule @samp{(: -spam-stat-split-fancy)} to @code{nnmail-split-fancy} -@end defun - -Make sure you load the dictionary before using it. This requires the -following in your @file{~/.gnus.el} file: - -@lisp -(require 'spam-stat) -(spam-stat-load) -@end lisp - -Typical test will involve calls to the following functions: - -@smallexample -Reset: (setq spam-stat (make-hash-table :test 'equal)) -Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam") -Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc") -Save table: (spam-stat-save) -File size: (nth 7 (file-attributes spam-stat-file)) -Number of words: (hash-table-count spam-stat) -Test spam: (spam-stat-test-directory "~/Mail/mail/spam") -Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") -Reduce table size: (spam-stat-reduce-size) -Save table: (spam-stat-save) -File size: (nth 7 (file-attributes spam-stat-file)) -Number of words: (hash-table-count spam-stat) -Test spam: (spam-stat-test-directory "~/Mail/mail/spam") -Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") -@end smallexample - -Here is how you would create your dictionary: - -@smallexample -Reset: (setq spam-stat (make-hash-table :test 'equal)) -Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam") -Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc") -Repeat for any other non-spam group you need... -Reduce table size: (spam-stat-reduce-size) -Save table: (spam-stat-save) -@end smallexample - -@node The Gnus Registry -@section The Gnus Registry -@cindex registry -@cindex split -@cindex track - -The Gnus registry is a package that tracks messages by their -Message-ID across all backends. This allows Gnus users to do several -cool things, be the envy of the locals, get free haircuts, and be -experts on world issues. Well, maybe not all of those, but the -features are pretty cool. - -Although they will be explained in detail shortly, here's a quick list -of said features in case your attention span is... never mind. - -@enumerate -@item -Split messages to their parent - -This keeps discussions in the same group. You can use the subject and -the sender in addition to the Message-ID. Several strategies are -available. - -@item -Refer to messages by ID - -Commands like @code{gnus-summary-refer-parent-article} can take -advantage of the registry to jump to the referred article, regardless -of the group the message is in. - -@item -Store custom flags and keywords - -The registry can store custom flags and keywords for a message. For -instance, you can mark a message ``To-Do'' this way and the flag will -persist whether the message is in the nnimap, nnml, nnmaildir, -etc. backends. - -@item -Store arbitrary data - -Through a simple ELisp API, the registry can remember any data for a -message. A built-in inverse map, when activated, allows quick lookups -of all messages matching a particular set of criteria. -@end enumerate - -@menu -* Gnus Registry Setup:: -* Fancy splitting to parent:: -* Registry Article Refer Method:: -* Store custom flags and keywords:: -* Store arbitrary data:: -@end menu - -@node Gnus Registry Setup -@subsection Gnus Registry Setup - -Fortunately, setting up the Gnus registry is pretty easy: - -@lisp -(setq gnus-registry-max-entries 2500) - -(gnus-registry-initialize) -@end lisp - -This adds registry saves to Gnus newsrc saves (which happen on exit -and when you press @kbd{s} from the @code{*Group*} buffer. It also -adds registry calls to article actions in Gnus (copy, move, etc.) so -it's not easy to undo the initialization. See -@code{gnus-registry-initialize} for the gory details. - -Here are other settings used by the author of the registry (understand -what they do before you copy them blindly). - -@lisp -(setq - gnus-registry-split-strategy 'majority - gnus-registry-ignored-groups '(("nntp" t) - ("nnrss" t) - ("spam" t) - ("train" t)) - gnus-registry-max-entries 500000 - ;; this is the default - gnus-registry-track-extra '(sender subject)) -@end lisp - -They say: keep a lot of messages around, track messages by sender and -subject (not just parent Message-ID), and when the registry splits -incoming mail, use a majority rule to decide where messages should go -if there's more than one possibility. In addition, the registry -should ignore messages in groups that match ``nntp'', ``nnrss'', -``spam'', or ``train.'' - -You are doubtless impressed by all this, but you ask: ``I am a Gnus -user, I customize to live. Give me more.'' Here you go, these are -the general settings. - -@defvar gnus-registry-unfollowed-groups -The groups that will not be followed by -@code{gnus-registry-split-fancy-with-parent}. They will still be -remembered by the registry. This is a list of regular expressions. -By default any group name that ends with ``delayed'', ``drafts'', -``queue'', or ``INBOX'', belongs to the nnmairix backend, or contains -the word ``archive'' is not followed. -@end defvar - -@defvar gnus-registry-max-entries -The number (an integer or @code{nil} for unlimited) of entries the -registry will keep. -@end defvar - -@defvar gnus-registry-max-pruned-entries -The maximum number (an integer or @code{nil} for unlimited) of entries -the registry will keep after pruning. -@end defvar - -@defvar gnus-registry-cache-file -The file where the registry will be stored between Gnus sessions. By -default the file name is @code{.gnus.registry.eioio} in the same -directory as your @code{.newsrc.eld}. -@end defvar - -@node Registry Article Refer Method -@subsection Fetching by @code{Message-ID} Using the Registry - -The registry knows how to map each @code{Message-ID} to the group it's -in. This can be leveraged to enhance the ``article refer method'', -the thing that tells Gnus how to look up an article given its -Message-ID (@pxref{Finding the Parent}). - -@vindex nnregistry -@vindex gnus-refer-article-method - -The @code{nnregistry} refer method does exactly that. It has the -advantage that an article may be found regardless of the group it's -in---provided its @code{Message-ID} is known to the registry. It can -be enabled by augmenting the start-up file with something along these -lines: - -@example -;; Keep enough entries to have a good hit rate when referring to an -;; article using the registry. Use long group names so that Gnus -;; knows where the article is. -(setq gnus-registry-max-entries 2500) - -(gnus-registry-initialize) - -(setq gnus-refer-article-method - '(current - (nnregistry) - (nnweb "gmane" (nnweb-type gmane)))) -@end example - -The example above instructs Gnus to first look up the article in the -current group, or, alternatively, using the registry, and finally, if -all else fails, using Gmane. - -@node Fancy splitting to parent -@subsection Fancy splitting to parent - -Simply put, this lets you put followup e-mail where it belongs. - -Every message has a Message-ID, which is unique, and the registry -remembers it. When the message is moved or copied, the registry will -notice this and offer the new group as a choice to the splitting -strategy. - -When a followup is made, usually it mentions the original message's -Message-ID in the headers. The registry knows this and uses that -mention to find the group where the original message lives. You only -have to put a rule like this: - -@lisp -(setq nnimap-my-split-fancy '(| - - ;; split to parent: you need this - (: gnus-registry-split-fancy-with-parent) - - ;; other rules, as an example - (: spam-split) - ;; default mailbox - "mail") -@end lisp - -in your fancy split setup. In addition, you may want to customize the -following variables. - -@defvar gnus-registry-track-extra -This is a list of symbols, so it's best to change it from the -Customize interface. By default it's @code{(subject sender)}, which -may work for you. It can be annoying if your mail flow is large and -people don't stick to the same groups. -@end defvar - -@defvar gnus-registry-split-strategy -This is a symbol, so it's best to change it from the Customize -interface. By default it's @code{nil}, but you may want to set it to -@code{majority} or @code{first} to split by sender or subject based on -the majority of matches or on the first found. I find @code{majority} -works best. -@end defvar - -@node Store custom flags and keywords -@subsection Store custom flags and keywords - -The registry lets you set custom flags and keywords per message. You -can use the Gnus->Registry Marks menu or the @kbd{M M x} keyboard -shortcuts, where @code{x} is the first letter of the mark's name. - -@defvar gnus-registry-marks -The custom marks that the registry can use. You can modify the -default list, if you like. If you do, you'll have to exit Emacs -before they take effect (you can also unload the registry and reload -it or evaluate the specific macros you'll need, but you probably don't -want to bother). Use the Customize interface to modify the list. - -By default this list has the @code{Important}, @code{Work}, -@code{Personal}, @code{To-Do}, and @code{Later} marks. They all have -keyboard shortcuts like @kbd{M M i} for Important, using the first -letter. -@end defvar - -@defun gnus-registry-mark-article -Call this function to mark an article with a custom registry mark. It -will offer the available marks for completion. -@end defun - -You can use @code{defalias} to install a summary line formatting -function that will show the registry marks. There are two flavors of -this function, either showing the marks as single characters, using -their @code{:char} property, or showing the marks as full strings. - -@lisp -;; show the marks as single characters (see the :char property in -;; `gnus-registry-marks'): -;; (defalias 'gnus-user-format-function-M 'gnus-registry-article-marks-to-chars) - -;; show the marks by name (see `gnus-registry-marks'): -;; (defalias 'gnus-user-format-function-M 'gnus-registry-article-marks-to-names) -@end lisp - - -@node Store arbitrary data -@subsection Store arbitrary data - -The registry has a simple API that uses a Message-ID as the key to -store arbitrary data (as long as it can be converted to a list for -storage). - -@defun gnus-registry-set-id-key (id key value) -Store @code{value} under @code{key} for message @code{id}. -@end defun - -@defun gnus-registry-get-id-key (id key) -Get the data under @code{key} for message @code{id}. -@end defun - -@defvar gnus-registry-extra-entries-precious -If any extra entries are precious, their presence will make the -registry keep the whole entry forever, even if there are no groups for -the Message-ID and if the size limit of the registry is reached. By -default this is just @code{(marks)} so the custom registry marks are -precious. -@end defvar - -@node Other modes -@section Interaction with other modes - -@subsection Dired -@cindex dired - -@code{gnus-dired-minor-mode} provides some useful functions for dired -buffers. It is enabled with -@lisp -(add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode) -@end lisp - -@table @kbd -@item C-c C-m C-a -@findex gnus-dired-attach -@cindex attachments, selection via dired -Send dired's marked files as an attachment (@code{gnus-dired-attach}). -You will be prompted for a message buffer. - -@item C-c C-m C-l -@findex gnus-dired-find-file-mailcap -Visit a file according to the appropriate mailcap entry -(@code{gnus-dired-find-file-mailcap}). With prefix, open file in a new -buffer. - -@item C-c C-m C-p -@findex gnus-dired-print -Print file according to the mailcap entry (@code{gnus-dired-print}). If -there is no print command, print in a PostScript image. -@end table - -@node Various Various -@section Various Various -@cindex mode lines -@cindex highlights - -@table @code - -@item gnus-home-directory -@vindex gnus-home-directory -All Gnus file and directory variables will be initialized from this -variable, which defaults to @file{~/}. - -@item gnus-directory -@vindex gnus-directory -Most Gnus storage file and directory variables will be initialized from -this variable, which defaults to the @env{SAVEDIR} environment -variable, or @file{~/News/} if that variable isn't set. - -Note that Gnus is mostly loaded when the @file{~/.gnus.el} file is read. -This means that other directory variables that are initialized from this -variable won't be set properly if you set this variable in -@file{~/.gnus.el}. Set this variable in @file{.emacs} instead. - -@item gnus-default-directory -@vindex gnus-default-directory -Not related to the above variable at all---this variable says what the -default directory of all Gnus buffers should be. If you issue commands -like @kbd{C-x C-f}, the prompt you'll get starts in the current buffer's -default directory. If this variable is @code{nil} (which is the -default), the default directory will be the default directory of the -buffer you were in when you started Gnus. - -@item gnus-verbose -@vindex gnus-verbose -This variable is an integer between zero and ten. The higher the value, -the more messages will be displayed. If this variable is zero, Gnus -will never flash any messages, if it is seven (which is the default), -most important messages will be shown, and if it is ten, Gnus won't ever -shut up, but will flash so many messages it will make your head swim. - -@item gnus-verbose-backends -@vindex gnus-verbose-backends -This variable works the same way as @code{gnus-verbose}, but it applies -to the Gnus back ends instead of Gnus proper. - -@item gnus-add-timestamp-to-message -@vindex gnus-add-timestamp-to-message -This variable controls whether to add timestamps to messages that are -controlled by @code{gnus-verbose} and @code{gnus-verbose-backends} and -are issued. The default value is @code{nil} which means never to add -timestamp. If it is @code{log}, add timestamps to only the messages -that go into the @samp{*Messages*} buffer (in XEmacs, it is the -@w{@samp{ *Message-Log*}} buffer). If it is neither @code{nil} nor -@code{log}, add timestamps not only to log messages but also to the ones -displayed in the echo area. - -@item nnheader-max-head-length -@vindex nnheader-max-head-length -When the back ends read straight heads of articles, they all try to read -as little as possible. This variable (default 8192) specifies -the absolute max length the back ends will try to read before giving up -on finding a separator line between the head and the body. If this -variable is @code{nil}, there is no upper read bound. If it is -@code{t}, the back ends won't try to read the articles piece by piece, -but read the entire articles. This makes sense with some versions of -@code{ange-ftp} or @code{efs}. - -@item nnheader-head-chop-length -@vindex nnheader-head-chop-length -This variable (default 2048) says how big a piece of each article to -read when doing the operation described above. - -@item nnheader-file-name-translation-alist -@vindex nnheader-file-name-translation-alist -@cindex file names -@cindex invalid characters in file names -@cindex characters in file names -This is an alist that says how to translate characters in file names. -For instance, if @samp{:} is invalid as a file character in file names -on your system (you OS/2 user you), you could say something like: - -@lisp -@group -(setq nnheader-file-name-translation-alist - '((?: . ?_))) -@end group -@end lisp - -In fact, this is the default value for this variable on OS/2 and MS -Windows (phooey) systems. - -@item gnus-hidden-properties -@vindex gnus-hidden-properties -This is a list of properties to use to hide ``invisible'' text. It is -@code{(invisible t intangible t)} by default on most systems, which -makes invisible text invisible and intangible. - -@item gnus-parse-headers-hook -@vindex gnus-parse-headers-hook -A hook called before parsing headers. It can be used, for instance, to -gather statistics on the headers fetched, or perhaps you'd like to prune -some headers. I don't see why you'd want that, though. - -@item gnus-shell-command-separator -@vindex gnus-shell-command-separator -String used to separate two shell commands. The default is @samp{;}. - -@item gnus-invalid-group-regexp -@vindex gnus-invalid-group-regexp - -Regexp to match ``invalid'' group names when querying user for a group -name. The default value catches some @strong{really} invalid group -names who could possibly mess up Gnus internally (like allowing -@samp{:} in a group name, which is normally used to delimit method and -group). - -@acronym{IMAP} users might want to allow @samp{/} in group names though. - -@item gnus-safe-html-newsgroups -@vindex gnus-safe-html-newsgroups -Groups in which links in html articles are considered all safe. The -value may be a regexp matching those groups, a list of group names, or -@code{nil}. This overrides @code{mm-w3m-safe-url-regexp}. The default -value is @code{"\\`nnrss[+:]"}. This is effective only when emacs-w3m -renders html articles, i.e., in the case @code{mm-text-html-renderer} is -set to @code{w3m}. @xref{Display Customization, ,Display Customization, -emacs-mime, The Emacs MIME Manual}. - -@end table - -@node The End -@chapter The End - -Well, that's the manual---you can get on with your life now. Keep in -touch. Say hello to your cats from me. - -My @strong{ghod}---I just can't stand goodbyes. Sniffle. - -Ol' Charles Reznikoff said it pretty well, so I leave the floor to him: - -@quotation -@strong{Te Deum} - -@sp 1 -Not because of victories @* -I sing,@* -having none,@* -but for the common sunshine,@* -the breeze,@* -the largess of the spring. - -@sp 1 -Not for victory@* -but for the day's work done@* -as well as I was able;@* -not for a seat upon the dais@* -but at the common table.@* -@end quotation - - -@node Appendices -@chapter Appendices - -@menu -* XEmacs:: Requirements for installing under XEmacs. -* History:: How Gnus got where it is today. -* On Writing Manuals:: Why this is not a beginner's guide. -* Terminology:: We use really difficult, like, words here. -* Customization:: Tailoring Gnus to your needs. -* Troubleshooting:: What you might try if things do not work. -* Gnus Reference Guide:: Rilly, rilly technical stuff. -* Emacs for Heathens:: A short introduction to Emacsian terms. -* Frequently Asked Questions:: The Gnus FAQ -@end menu - - -@node XEmacs -@section XEmacs -@cindex XEmacs -@cindex installing under XEmacs - -XEmacs is distributed as a collection of packages. You should install -whatever packages the Gnus XEmacs package requires. The current -requirements are @samp{gnus}, @samp{mail-lib}, @samp{xemacs-base}, -@samp{eterm}, @samp{sh-script}, @samp{net-utils}, @samp{os-utils}, -@samp{dired}, @samp{mh-e}, @samp{sieve}, @samp{ps-print}, @samp{W3}, -@samp{pgg}, @samp{mailcrypt}, @samp{ecrypto}, and @samp{sasl}. - - -@node History -@section History - -@cindex history -@sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in -'94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus. - -If you want to investigate the person responsible for this outrage, -you can point your (feh!) web browser to -@uref{http://quimby.gnus.org/}. This is also the primary -distribution point for the new and spiffy versions of Gnus, and is -known as The Site That Destroys Newsrcs And Drives People Mad. - -During the first extended alpha period of development, the new Gnus was -called ``(ding) Gnus''. @dfn{(ding)} is, of course, short for -@dfn{ding is not Gnus}, which is a total and utter lie, but who cares? -(Besides, the ``Gnus'' in this abbreviation should probably be -pronounced ``news'' as @sc{Umeda} intended, which makes it a more -appropriate name, don't you think?) - -In any case, after spending all that energy on coming up with a new and -spunky name, we decided that the name was @emph{too} spunky, so we -renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs. -``@sc{gnus}''. New vs. old. - -@menu -* Gnus Versions:: What Gnus versions have been released. -* Why?:: What's the point of Gnus? -* Compatibility:: Just how compatible is Gnus with @sc{gnus}? -* Conformity:: Gnus tries to conform to all standards. -* Emacsen:: Gnus can be run on a few modern Emacsen. -* Gnus Development:: How Gnus is developed. -* Contributors:: Oodles of people. -* New Features:: Pointers to some of the new stuff in Gnus. -@end menu - - -@node Gnus Versions -@subsection Gnus Versions -@cindex ding Gnus -@cindex September Gnus -@cindex Red Gnus -@cindex Quassia Gnus -@cindex Pterodactyl Gnus -@cindex Oort Gnus -@cindex No Gnus -@cindex Gnus versions - -The first ``proper'' release of Gnus 5 was done in November 1995 when it -was included in the Emacs 19.30 distribution (132 (ding) Gnus releases -plus 15 Gnus 5.0 releases). - -In May 1996 the next Gnus generation (aka. ``September Gnus'' (after 99 -releases)) was released under the name ``Gnus 5.2'' (40 releases). - -On July 28th 1996 work on Red Gnus was begun, and it was released on -January 25th 1997 (after 84 releases) as ``Gnus 5.4'' (67 releases). - -On September 13th 1997, Quassia Gnus was started and lasted 37 releases. -It was released as ``Gnus 5.6'' on March 8th 1998 (46 releases). - -Gnus 5.6 begat Pterodactyl Gnus on August 29th 1998 and was released as -``Gnus 5.8'' (after 99 releases and a CVS repository) on December 3rd -1999. - -On the 26th of October 2000, Oort Gnus was begun and was released as -Gnus 5.10 on May 1st 2003 (24 releases). - -On the January 4th 2004, No Gnus was begun. - -On April 19, 2010 Gnus development was moved to Git. See -http://git.gnus.org for details (http://www.gnus.org will be updated -with the information when possible). - -If you happen upon a version of Gnus that has a prefixed name -- -``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'', -``Pterodactyl Gnus'', ``Oort Gnus'', ``No Gnus'' -- don't panic. -Don't let it know that you're frightened. Back away. Slowly. Whatever -you do, don't run. Walk away, calmly, until you're out of its reach. -Find a proper released version of Gnus and snuggle up to that instead. - - -@node Why? -@subsection Why? - -What's the point of Gnus? - -I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep'' -newsreader, that lets you do anything you can think of. That was my -original motivation, but while working on Gnus, it has become clear to -me that this generation of newsreaders really belong in the stone age. -Newsreaders haven't developed much since the infancy of the net. If the -volume continues to rise with the current rate of increase, all current -newsreaders will be pretty much useless. How do you deal with -newsgroups that have thousands of new articles each day? How do you -keep track of millions of people who post? - -Gnus offers no real solutions to these questions, but I would very much -like to see Gnus being used as a testing ground for new methods of -reading and fetching news. Expanding on @sc{Umeda}-san's wise decision -to separate the newsreader from the back ends, Gnus now offers a simple -interface for anybody who wants to write new back ends for fetching mail -and news from different sources. I have added hooks for customizations -everywhere I could imagine it being useful. By doing so, I'm inviting -every one of you to explore and invent. - -May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs} and -@kbd{C-u 100 M-x all-hail-xemacs}. - - -@node Compatibility -@subsection Compatibility - -@cindex compatibility -Gnus was designed to be fully compatible with @sc{gnus}. Almost all key -bindings have been kept. More key bindings have been added, of course, -but only in one or two obscure cases have old bindings been changed. - -Our motto is: -@quotation -@cartouche -@center In a cloud bones of steel. -@end cartouche -@end quotation - -All commands have kept their names. Some internal functions have changed -their names. - -The @code{gnus-uu} package has changed drastically. @xref{Decoding -Articles}. - -One major compatibility question is the presence of several summary -buffers. All variables relevant while reading a group are -buffer-local to the summary buffer they belong in. Although many -important variables have their values copied into their global -counterparts whenever a command is executed in the summary buffer, this -change might lead to incorrect values being used unless you are careful. - -All code that relies on knowledge of @sc{gnus} internals will probably -fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or -changing it in any way, as a matter of fact) is strictly verboten. Gnus -maintains a hash table that points to the entries in this alist (which -speeds up many functions), and changing the alist directly will lead to -peculiar results. - -@cindex hilit19 -@cindex highlighting -Old hilit19 code does not work at all. In fact, you should probably -remove all hilit code from all Gnus hooks -(@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}). -Gnus provides various integrated functions for highlighting. These are -faster and more accurate. To make life easier for everybody, Gnus will -by default remove all hilit calls from all hilit hooks. Uncleanliness! -Away! - -Packages like @code{expire-kill} will no longer work. As a matter of -fact, you should probably remove all old @sc{gnus} packages (and other -code) when you start using Gnus. More likely than not, Gnus already -does what you have written code to make @sc{gnus} do. (Snicker.) - -Even though old methods of doing things are still supported, only the -new methods are documented in this manual. If you detect a new method of -doing something while reading this manual, that does not mean you have -to stop doing it the old way. - -Gnus understands all @sc{gnus} startup files. - -@kindex M-x gnus-bug -@findex gnus-bug -@cindex reporting bugs -@cindex bugs -Overall, a casual user who hasn't written much code that depends on -@sc{gnus} internals should suffer no problems. If problems occur, -please let me know by issuing that magic command @kbd{M-x gnus-bug}. - -@vindex gnus-bug-create-help-buffer -If you are in the habit of sending bug reports @emph{very} often, you -may find the helpful help buffer annoying after a while. If so, set -@code{gnus-bug-create-help-buffer} to @code{nil} to avoid having it pop -up at you. - - -@node Conformity -@subsection Conformity - -No rebels without a clue here, ma'am. We conform to all standards known -to (wo)man. Except for those standards and/or conventions we disagree -with, of course. - -@table @strong - -@item RFC (2)822 -@cindex RFC 822 -@cindex RFC 2822 -There are no known breaches of this standard. - -@item RFC 1036 -@cindex RFC 1036 -There are no known breaches of this standard, either. - -@item Son-of-RFC 1036 -@cindex Son-of-RFC 1036 -We do have some breaches to this one. - -@table @emph - -@item X-Newsreader -@itemx User-Agent -These are considered to be ``vanity headers'', while I consider them -to be consumer information. After seeing so many badly formatted -articles coming from @code{tin} and @code{Netscape} I know not to use -either of those for posting articles. I would not have known that if -it wasn't for the @code{X-Newsreader} header. -@end table - -@item USEFOR -@cindex USEFOR -USEFOR is an IETF working group writing a successor to RFC 1036, based -on Son-of-RFC 1036. They have produced a number of drafts proposing -various changes to the format of news articles. The Gnus towers will -look into implementing the changes when the draft is accepted as an RFC. - -@item MIME - RFC 2045-2049 etc -@cindex @acronym{MIME} -All the various @acronym{MIME} RFCs are supported. - -@item Disposition Notifications - RFC 2298 -Message Mode is able to request notifications from the receiver. - -@item PGP - RFC 1991 and RFC 2440 -@cindex RFC 1991 -@cindex RFC 2440 -RFC 1991 is the original @acronym{PGP} message specification, -published as an informational RFC. RFC 2440 was the follow-up, now -called Open PGP, and put on the Standards Track. Both document a -non-@acronym{MIME} aware @acronym{PGP} format. Gnus supports both -encoding (signing and encryption) and decoding (verification and -decryption). - -@item PGP/MIME - RFC 2015/3156 -RFC 2015 (superseded by 3156 which references RFC 2440 instead of RFC -1991) describes the @acronym{MIME}-wrapping around the RFC 1991/2440 format. -Gnus supports both encoding and decoding. - -@item S/MIME - RFC 2633 -RFC 2633 describes the @acronym{S/MIME} format. - -@item IMAP - RFC 1730/2060, RFC 2195, RFC 2086, RFC 2359, RFC 2595, RFC 1731 -RFC 1730 is @acronym{IMAP} version 4, updated somewhat by RFC 2060 -(@acronym{IMAP} 4 revision 1). RFC 2195 describes CRAM-MD5 -authentication for @acronym{IMAP}. RFC 2086 describes access control -lists (ACLs) for @acronym{IMAP}. RFC 2359 describes a @acronym{IMAP} -protocol enhancement. RFC 2595 describes the proper @acronym{TLS} -integration (STARTTLS) with @acronym{IMAP}. RFC 1731 describes the -GSSAPI/Kerberos4 mechanisms for @acronym{IMAP}. - -@end table - -If you ever notice Gnus acting non-compliant with regards to the texts -mentioned above, don't hesitate to drop a note to Gnus Towers and let us -know. - - -@node Emacsen -@subsection Emacsen -@cindex Emacsen -@cindex XEmacs -@cindex Mule -@cindex Emacs - -This version of Gnus should work on: - -@itemize @bullet - -@item -Emacs 21.1 and up. - -@item -XEmacs 21.4 and up. - -@end itemize - -This Gnus version will absolutely not work on any Emacsen older than -that. Not reliably, at least. Older versions of Gnus may work on older -Emacs versions. Particularly, Gnus 5.10.8 should also work on Emacs -20.7 and XEmacs 21.1. - -@c No-merge comment: The paragraph added in v5-10 here must not be -@c synced here! - -@node Gnus Development -@subsection Gnus Development - -Gnus is developed in a two-phased cycle. The first phase involves much -discussion on the development mailing list @samp{ding@@gnus.org}, where people -propose changes and new features, post patches and new back ends. This -phase is called the @dfn{alpha} phase, since the Gnusae released in this -phase are @dfn{alpha releases}, or (perhaps more commonly in other -circles) @dfn{snapshots}. During this phase, Gnus is assumed to be -unstable and should not be used by casual users. Gnus alpha releases -have names like ``Oort Gnus'' and ``No Gnus''. @xref{Gnus Versions}. - -After futzing around for 10-100 alpha releases, Gnus is declared -@dfn{frozen}, and only bug fixes are applied. Gnus loses the prefix, -and is called things like ``Gnus 5.10.1'' instead. Normal people are -supposed to be able to use these, and these are mostly discussed on the -@samp{gnu.emacs.gnus} newsgroup. This newgroup is mirrored to the -mailing list @samp{info-gnus-english@@gnu.org} which is carried on Gmane -as @samp{gmane.emacs.gnus.user}. These releases are finally integrated -in Emacs. - -@cindex Incoming* -@vindex mail-source-delete-incoming -Some variable defaults differ between alpha Gnusae and released Gnusae, -in particular, @code{mail-source-delete-incoming}. This is to prevent -lossage of mail if an alpha release hiccups while handling the mail. -@xref{Mail Source Customization}. - -The division of discussion between the ding mailing list and the Gnus -newsgroup is not purely based on publicity concerns. It's true that -having people write about the horrible things that an alpha Gnus release -can do (sometimes) in a public forum may scare people off, but more -importantly, talking about new experimental features that have been -introduced may confuse casual users. New features are frequently -introduced, fiddled with, and judged to be found wanting, and then -either discarded or totally rewritten. People reading the mailing list -usually keep up with these rapid changes, while people on the newsgroup -can't be assumed to do so. - -So if you have problems with or questions about the alpha versions, -direct those to the ding mailing list @samp{ding@@gnus.org}. This list -is also available on Gmane as @samp{gmane.emacs.gnus.general}. - -@cindex Incoming* -@vindex mail-source-delete-incoming -Some variable defaults differ between alpha Gnusae and released Gnusae, -in particular, @code{mail-source-delete-incoming}. This is to prevent -lossage of mail if an alpha release hiccups while handling the mail. -@xref{Mail Source Customization}. - -@node Contributors -@subsection Contributors -@cindex contributors - -The new Gnus version couldn't have been done without the help of all the -people on the (ding) mailing list. Every day for over a year I have -gotten billions of nice bug reports from them, filling me with joy, -every single one of them. Smooches. The people on the list have been -tried beyond endurance, what with my ``oh, that's a neat idea , yup, I'll release it right away no wait, that doesn't -work at all , yup, I'll ship that one off right away no, wait, that absolutely does not work'' policy for releases. -Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that -``worser''? ``much worser''? ``worsest''?) - -I would like to take this opportunity to thank the Academy for@dots{} oops, -wrong show. - -@itemize @bullet - -@item -Masanobu @sc{Umeda}---the writer of the original @sc{gnus}. - -@item -Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.el, -nnwarchive and many, many other things connected with @acronym{MIME} and -other types of en/decoding, as well as general bug fixing, new -functionality and stuff. - -@item -Per Abrahamsen---custom, scoring, highlighting and @sc{soup} code (as -well as numerous other things). - -@item -Luis Fernandes---design and graphics. - -@item -Joe Reiss---creator of the smiley faces. - -@item -Justin Sheehy---the @acronym{FAQ} maintainer. - -@item -Erik Naggum---help, ideas, support, code and stuff. - -@item -Wes Hardaker---@file{gnus-picon.el} and the manual section on -@dfn{picons} (@pxref{Picons}). - -@item -Kim-Minh Kaplan---further work on the picon code. - -@item -Brad Miller---@file{gnus-gl.el} and the GroupLens manual section. - -@item -Sudish Joseph---innumerable bug fixes. - -@item -Ilja Weis---@file{gnus-topic.el}. - -@item -Steven L. Baur---lots and lots and lots of bug detection and fixes. - -@item -Vladimir Alexiev---the refcard and reference booklets. - -@item -Felix Lee & Jamie Zawinski---I stole some pieces from the XGnus -distribution by Felix Lee and JWZ. - -@item -Scott Byer---@file{nnfolder.el} enhancements & rewrite. - -@item -Peter Mutsaers---orphan article scoring code. - -@item -Ken Raeburn---POP mail support. - -@item -Hallvard B Furuseth---various bits and pieces, especially dealing with -.newsrc files. - -@item -Brian Edmonds---@file{gnus-bbdb.el}. - -@item -David Moore---rewrite of @file{nnvirtual.el} and many other things. - -@item -Kevin Davidson---came up with the name @dfn{ding}, so blame him. - -@item -Fran@,{c}ois Pinard---many, many interesting and thorough bug reports, as -well as autoconf support. - -@end itemize - -This manual was proof-read by Adrian Aichner, with Ricardo Nassif, Mark -Borges, and Jost Krieger proof-reading parts of the manual. - -The following people have contributed many patches and suggestions: - -Christopher Davis, -Andrew Eskilsson, -Kai Grossjohann, -Kevin Greiner, -Jesper Harder, -Paul Jarc, -Simon Josefsson, -David K@aa{}gedal, -Richard Pieri, -Fabrice Popineau, -Daniel Quinlan, -Michael Shields, -Reiner Steib, -Jason L. Tibbitts, III, -Jack Vinson, -Katsumi Yamaoka, @c Yamaoka -and -Teodor Zlatanov. - -Also thanks to the following for patches and stuff: - -Jari Aalto, -Adrian Aichner, -Vladimir Alexiev, -Russ Allbery, -Peter Arius, -Matt Armstrong, -Marc Auslander, -Miles Bader, -Alexei V. Barantsev, -Frank Bennett, -Robert Bihlmeyer, -Chris Bone, -Mark Borges, -Mark Boyns, -Lance A. Brown, -Rob Browning, -Kees de Bruin, -Martin Buchholz, -Joe Buehler, -Kevin Buhr, -Alastair Burt, -Joao Cachopo, -Zlatko Calusic, -Massimo Campostrini, -Castor, -David Charlap, -Dan Christensen, -Kevin Christian, -Jae-you Chung, @c ? -James H. Cloos, Jr., -Laura Conrad, -Michael R. Cook, -Glenn Coombs, -Andrew J. Cosgriff, -Neil Crellin, -Frank D. Cringle, -Geoffrey T. Dairiki, -Andre Deparade, -Ulrik Dickow, -Dave Disser, -Rui-Tao Dong, @c ? -Joev Dubach, -Michael Welsh Duggan, -Dave Edmondson, -Paul Eggert, -Mark W. Eichin, -Karl Eichwalder, -Enami Tsugutomo, @c Enami -Michael Ernst, -Luc Van Eycken, -Sam Falkner, -Nelson Jose dos Santos Ferreira, -Sigbjorn Finne, -Sven Fischer, -Paul Fisher, -Decklin Foster, -Gary D. Foster, -Paul Franklin, -Guy Geens, -Arne Georg Gleditsch, -David S. Goldberg, -Michelangelo Grigni, -Dale Hagglund, -D. Hall, -Magnus Hammerin, -Kenichi Handa, @c Handa -Raja R. Harinath, -Yoshiki Hayashi, @c Hayashi -P. E. Jareth Hein, -Hisashige Kenji, @c Hisashige -Scott Hofmann, -Tassilo Horn, -Marc Horowitz, -Gunnar Horrigmo, -Richard Hoskins, -Brad Howes, -Miguel de Icaza, -Fran@,{c}ois Felix Ingrand, -Tatsuya Ichikawa, @c Ichikawa -Ishikawa Ichiro, @c Ishikawa -Lee Iverson, -Iwamuro Motonori, @c Iwamuro -Rajappa Iyer, -Andreas Jaeger, -Adam P. Jenkins, -Randell Jesup, -Fred Johansen, -Gareth Jones, -Greg Klanderman, -Karl Kleinpaste, -Michael Klingbeil, -Peter Skov Knudsen, -Shuhei Kobayashi, @c Kobayashi -Petr Konecny, -Koseki Yoshinori, @c Koseki -Thor Kristoffersen, -Jens Lautenbacher, -Martin Larose, -Seokchan Lee, @c Lee -Joerg Lenneis, -Carsten Leonhardt, -James LewisMoss, -Christian Limpach, -Markus Linnala, -Dave Love, -Mike McEwan, -Tonny Madsen, -Shlomo Mahlab, -Nat Makarevitch, -Istvan Marko, -David Martin, -Jason R. Mastaler, -Gordon Matzigkeit, -Timo Metzemakers, -Richard Mlynarik, -Lantz Moore, -Morioka Tomohiko, @c Morioka -Erik Toubro Nielsen, -Hrvoje Niksic, -Andy Norman, -Fred Oberhauser, -C. R. Oldham, -Alexandre Oliva, -Ken Olstad, -Masaharu Onishi, @c Onishi -Hideki Ono, @c Ono -Ettore Perazzoli, -William Perry, -Stephen Peters, -Jens-Ulrik Holger Petersen, -Ulrich Pfeifer, -Matt Pharr, -Andy Piper, -John McClary Prevost, -Bill Pringlemeir, -Mike Pullen, -Jim Radford, -Colin Rafferty, -Lasse Rasinen, -Lars Balker Rasmussen, -Joe Reiss, -Renaud Rioboo, -Roland B. Roberts, -Bart Robinson, -Christian von Roques, -Markus Rost, -Jason Rumney, -Wolfgang Rupprecht, -Jay Sachs, -Dewey M. Sasser, -Conrad Sauerwald, -Loren Schall, -Dan Schmidt, -Ralph Schleicher, -Philippe Schnoebelen, -Andreas Schwab, -Randal L. Schwartz, -Danny Siu, -Matt Simmons, -Paul D. Smith, -Jeff Sparkes, -Toby Speight, -Michael Sperber, -Darren Stalder, -Richard Stallman, -Greg Stark, -Sam Steingold, -Paul Stevenson, -Jonas Steverud, -Paul Stodghill, -Kiyokazu Suto, @c Suto -Kurt Swanson, -Samuel Tardieu, -Teddy, -Chuck Thompson, -Tozawa Akihiko, @c Tozawa -Philippe Troin, -James Troup, -Trung Tran-Duc, -Jack Twilley, -Aaron M. Ucko, -Aki Vehtari, -Didier Verna, -Vladimir Volovich, -Jan Vroonhof, -Stefan Waldherr, -Pete Ware, -Barry A. Warsaw, -Christoph Wedler, -Joe Wells, -Lee Willis, -and -Lloyd Zusman. - - -For a full overview of what each person has done, the ChangeLogs -included in the Gnus alpha distributions should give ample reading -(550kB and counting). - -Apologies to everybody that I've forgotten, of which there are many, I'm -sure. - -Gee, that's quite a list of people. I guess that must mean that there -actually are people who are using Gnus. Who'd'a thunk it! - - -@node New Features -@subsection New Features -@cindex new features - -@menu -* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus. -* September Gnus:: The Thing Formally Known As Gnus 5.2/5.3. -* Red Gnus:: Third time best---Gnus 5.4/5.5. -* Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7. -* Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9. -* Oort Gnus:: It's big. It's far out. Gnus 5.10/5.11. -* No Gnus:: Very punny. -@end menu - -These lists are, of course, just @emph{short} overviews of the -@emph{most} important new features. No, really. There are tons more. -Yes, we have feeping creaturism in full effect. - -@node ding Gnus -@subsubsection (ding) Gnus - -New features in Gnus 5.0/5.1: - -@itemize @bullet - -@item -The look of all buffers can be changed by setting format-like variables -(@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}). - -@item -Local spool and several @acronym{NNTP} servers can be used at once -(@pxref{Select Methods}). - -@item -You can combine groups into virtual groups (@pxref{Virtual Groups}). - -@item -You can read a number of different mail formats (@pxref{Getting Mail}). -All the mail back ends implement a convenient mail expiry scheme -(@pxref{Expiring Mail}). - -@item -Gnus can use various strategies for gathering threads that have lost -their roots (thereby gathering loose sub-threads into one thread) or it -can go back and retrieve enough headers to build a complete thread -(@pxref{Customizing Threading}). - -@item -Killed groups can be displayed in the group buffer, and you can read -them as well (@pxref{Listing Groups}). - -@item -Gnus can do partial group updates---you do not have to retrieve the -entire active file just to check for new articles in a few groups -(@pxref{The Active File}). - -@item -Gnus implements a sliding scale of subscribedness to groups -(@pxref{Group Levels}). - -@item -You can score articles according to any number of criteria -(@pxref{Scoring}). You can even get Gnus to find out how to score -articles for you (@pxref{Adaptive Scoring}). - -@item -Gnus maintains a dribble buffer that is auto-saved the normal Emacs -manner, so it should be difficult to lose much data on what you have -read if your machine should go down (@pxref{Auto Save}). - -@item -Gnus now has its own startup file (@file{~/.gnus.el}) to avoid -cluttering up the @file{.emacs} file. - -@item -You can set the process mark on both groups and articles and perform -operations on all the marked items (@pxref{Process/Prefix}). - -@item -You can list subsets of groups according to, well, anything -(@pxref{Listing Groups}). - -@item -You can browse foreign servers and subscribe to groups from those -servers (@pxref{Browse Foreign Server}). - -@item -Gnus can fetch articles, asynchronously, on a second connection to the -server (@pxref{Asynchronous Fetching}). - -@item -You can cache articles locally (@pxref{Article Caching}). - -@item -The uudecode functions have been expanded and generalized -(@pxref{Decoding Articles}). - -@item -You can still post uuencoded articles, which was a little-known feature -of @sc{gnus}' past (@pxref{Uuencoding and Posting}). - -@item -Fetching parents (and other articles) now actually works without -glitches (@pxref{Finding the Parent}). - -@item -Gnus can fetch @acronym{FAQ}s and group descriptions (@pxref{Group Information}). - -@item -Digests (and other files) can be used as the basis for groups -(@pxref{Document Groups}). - -@item -Articles can be highlighted and customized (@pxref{Customizing -Articles}). - -@item -URLs and other external references can be buttonized (@pxref{Article -Buttons}). - -@item -You can do lots of strange stuff with the Gnus window & frame -configuration (@pxref{Window Layout}). - -@end itemize - - -@node September Gnus -@subsubsection September Gnus - -@iftex -@iflatex -\gnusfig{-28cm}{0cm}{\epsfig{figure=ps/september,height=20cm}} -@end iflatex -@end iftex - -New features in Gnus 5.2/5.3: - -@itemize @bullet - -@item -A new message composition mode is used. All old customization variables -for @code{mail-mode}, @code{rnews-reply-mode} and @code{gnus-msg} are -now obsolete. - -@item -Gnus is now able to generate @dfn{sparse} threads---threads where -missing articles are represented by empty nodes (@pxref{Customizing -Threading}). - -@lisp -(setq gnus-build-sparse-threads 'some) -@end lisp - -@item -Outgoing articles are stored on a special archive server -(@pxref{Archived Messages}). - -@item -Partial thread regeneration now happens when articles are -referred. - -@item -Gnus can make use of GroupLens predictions. - -@item -Picons (personal icons) can be displayed under XEmacs (@pxref{Picons}). - -@item -A @code{trn}-like tree buffer can be displayed (@pxref{Tree Display}). - -@lisp -(setq gnus-use-trees t) -@end lisp - -@item -An @code{nn}-like pick-and-read minor mode is available for the summary -buffers (@pxref{Pick and Read}). - -@lisp -(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) -@end lisp - -@item -In binary groups you can use a special binary minor mode (@pxref{Binary -Groups}). - -@item -Groups can be grouped in a folding topic hierarchy (@pxref{Group -Topics}). - -@lisp -(add-hook 'gnus-group-mode-hook 'gnus-topic-mode) -@end lisp - -@item -Gnus can re-send and bounce mail (@pxref{Summary Mail Commands}). - -@item -Groups can now have a score, and bubbling based on entry frequency -is possible (@pxref{Group Score}). - -@lisp -(add-hook 'gnus-summary-exit-hook 'gnus-summary-bubble-group) -@end lisp - -@item -Groups can be process-marked, and commands can be performed on -groups of groups (@pxref{Marking Groups}). - -@item -Caching is possible in virtual groups. - -@item -@code{nndoc} now understands all kinds of digests, mail boxes, rnews -news batches, ClariNet briefs collections, and just about everything -else (@pxref{Document Groups}). - -@item -Gnus has a new back end (@code{nnsoup}) to create/read SOUP packets. - -@item -The Gnus cache is much faster. - -@item -Groups can be sorted according to many criteria (@pxref{Sorting -Groups}). - -@item -New group parameters have been introduced to set list-addresses and -expiry times (@pxref{Group Parameters}). - -@item -All formatting specs allow specifying faces to be used -(@pxref{Formatting Fonts}). - -@item -There are several more commands for setting/removing/acting on process -marked articles on the @kbd{M P} submap (@pxref{Setting Process Marks}). - -@item -The summary buffer can be limited to show parts of the available -articles based on a wide range of criteria. These commands have been -bound to keys on the @kbd{/} submap (@pxref{Limiting}). - -@item -Articles can be made persistent with the @kbd{*} command -(@pxref{Persistent Articles}). - -@item -All functions for hiding article elements are now toggles. - -@item -Article headers can be buttonized (@pxref{Article Washing}). - -@item -All mail back ends support fetching articles by @code{Message-ID}. - -@item -Duplicate mail can now be treated properly (@pxref{Duplicates}). - -@item -All summary mode commands are available directly from the article -buffer (@pxref{Article Keymap}). - -@item -Frames can be part of @code{gnus-buffer-configuration} (@pxref{Window -Layout}). - -@item -Mail can be re-scanned by a daemonic process (@pxref{Daemons}). -@iftex -@iflatex -\marginpar[\mbox{}\hfill\epsfig{figure=ps/fseptember,height=5cm}]{\epsfig{figure=ps/fseptember,height=5cm}} -@end iflatex -@end iftex - -@item -Groups can be made permanently visible (@pxref{Listing Groups}). - -@lisp -(setq gnus-permanently-visible-groups "^nnml:") -@end lisp - -@item -Many new hooks have been introduced to make customizing easier. - -@item -Gnus respects the @code{Mail-Copies-To} header. - -@item -Threads can be gathered by looking at the @code{References} header -(@pxref{Customizing Threading}). - -@lisp -(setq gnus-summary-thread-gathering-function - 'gnus-gather-threads-by-references) -@end lisp - -@item -Read articles can be stored in a special backlog buffer to avoid -refetching (@pxref{Article Backlog}). - -@lisp -(setq gnus-keep-backlog 50) -@end lisp - -@item -A clean copy of the current article is always stored in a separate -buffer to allow easier treatment. - -@item -Gnus can suggest where to save articles (@pxref{Saving Articles}). - -@item -Gnus doesn't have to do as much prompting when saving (@pxref{Saving -Articles}). - -@lisp -(setq gnus-prompt-before-saving t) -@end lisp - -@item -@code{gnus-uu} can view decoded files asynchronously while fetching -articles (@pxref{Other Decode Variables}). - -@lisp -(setq gnus-uu-grabbed-file-functions 'gnus-uu-grab-view) -@end lisp - -@item -Filling in the article buffer now works properly on cited text -(@pxref{Article Washing}). - -@item -Hiding cited text adds buttons to toggle hiding, and how much -cited text to hide is now customizable (@pxref{Article Hiding}). - -@lisp -(setq gnus-cited-lines-visible 2) -@end lisp - -@item -Boring headers can be hidden (@pxref{Article Hiding}). - -@item -Default scoring values can now be set from the menu bar. - -@item -Further syntax checking of outgoing articles have been added. - -@end itemize - - -@node Red Gnus -@subsubsection Red Gnus - -New features in Gnus 5.4/5.5: - -@iftex -@iflatex -\gnusfig{-5.5cm}{-4cm}{\epsfig{figure=ps/red,height=20cm}} -@end iflatex -@end iftex - -@itemize @bullet - -@item -@file{nntp.el} has been totally rewritten in an asynchronous fashion. - -@item -Article prefetching functionality has been moved up into -Gnus (@pxref{Asynchronous Fetching}). - -@item -Scoring can now be performed with logical operators like @code{and}, -@code{or}, @code{not}, and parent redirection (@pxref{Advanced -Scoring}). - -@item -Article washing status can be displayed in the -article mode line (@pxref{Misc Article}). - -@item -@file{gnus.el} has been split into many smaller files. - -@item -Suppression of duplicate articles based on Message-ID can be done -(@pxref{Duplicate Suppression}). - -@lisp -(setq gnus-suppress-duplicates t) -@end lisp - -@item -New variables for specifying what score and adapt files are to be -considered home score and adapt files (@pxref{Home Score File}) have -been added. - -@item -@code{nndoc} was rewritten to be easily extensible (@pxref{Document -Server Internals}). - -@item -Groups can inherit group parameters from parent topics (@pxref{Topic -Parameters}). - -@item -Article editing has been revamped and is now actually usable. - -@item -Signatures can be recognized in more intelligent fashions -(@pxref{Article Signature}). - -@item -Summary pick mode has been made to look more @code{nn}-like. Line -numbers are displayed and the @kbd{.} command can be used to pick -articles (@code{Pick and Read}). - -@item -Commands for moving the @file{.newsrc.eld} from one server to -another have been added (@pxref{Changing Servers}). - -@item -There's a way now to specify that ``uninteresting'' fields be suppressed -when generating lines in buffers (@pxref{Advanced Formatting}). - -@item -Several commands in the group buffer can be undone with @kbd{C-M-_} -(@pxref{Undo}). - -@item -Scoring can be done on words using the new score type @code{w} -(@pxref{Score File Format}). - -@item -Adaptive scoring can be done on a Subject word-by-word basis -(@pxref{Adaptive Scoring}). - -@lisp -(setq gnus-use-adaptive-scoring '(word)) -@end lisp - -@item -Scores can be decayed (@pxref{Score Decays}). - -@lisp -(setq gnus-decay-scores t) -@end lisp - -@item -Scoring can be performed using a regexp on the Date header. The Date is -normalized to compact ISO 8601 format first (@pxref{Score File Format}). - -@item -A new command has been added to remove all data on articles from -the native server (@pxref{Changing Servers}). - -@item -A new command for reading collections of documents -(@code{nndoc} with @code{nnvirtual} on top) has been added---@kbd{C-M-d} -(@pxref{Really Various Summary Commands}). - -@item -Process mark sets can be pushed and popped (@pxref{Setting Process -Marks}). - -@item -A new mail-to-news back end makes it possible to post even when the @acronym{NNTP} -server doesn't allow posting (@pxref{Mail-To-News Gateways}). - -@item -A new back end for reading searches from Web search engines -(@dfn{DejaNews}, @dfn{Alta Vista}, @dfn{InReference}) has been added -(@pxref{Web Searches}). - -@item -Groups inside topics can now be sorted using the standard sorting -functions, and each topic can be sorted independently (@pxref{Topic -Sorting}). - -@item -Subsets of the groups can be sorted independently (@code{Sorting -Groups}). - -@item -Cached articles can be pulled into the groups (@pxref{Summary Generation -Commands}). -@iftex -@iflatex -\marginpar[\mbox{}\hfill\epsfig{figure=ps/fred,width=3cm}]{\epsfig{figure=ps/fred,width=3cm}} -@end iflatex -@end iftex - -@item -Score files are now applied in a more reliable order (@pxref{Score -Variables}). - -@item -Reports on where mail messages end up can be generated (@pxref{Splitting -Mail}). - -@item -More hooks and functions have been added to remove junk from incoming -mail before saving the mail (@pxref{Washing Mail}). - -@item -Emphasized text can be properly fontisized: - -@end itemize - - -@node Quassia Gnus -@subsubsection Quassia Gnus - -New features in Gnus 5.6: - -@itemize @bullet - -@item -New functionality for using Gnus as an offline newsreader has been -added. A plethora of new commands and modes have been added. -@xref{Gnus Unplugged}, for the full story. - -@item -The @code{nndraft} back end has returned, but works differently than -before. All Message buffers are now also articles in the @code{nndraft} -group, which is created automatically. - -@item -@code{gnus-alter-header-function} can now be used to alter header -values. - -@item -@code{gnus-summary-goto-article} now accept Message-ID's. - -@item -A new Message command for deleting text in the body of a message -outside the region: @kbd{C-c C-v}. - -@item -You can now post to component group in @code{nnvirtual} groups with -@kbd{C-u C-c C-c}. - -@item - @code{nntp-rlogin-program}---new variable to ease customization. - -@item -@code{C-u C-c C-c} in @code{gnus-article-edit-mode} will now inhibit -re-highlighting of the article buffer. - -@item -New element in @code{gnus-boring-article-headers}---@code{long-to}. - -@item -@kbd{M-i} symbolic prefix command. @xref{Symbolic Prefixes}, for -details. - -@item -@kbd{L} and @kbd{I} in the summary buffer now take the symbolic prefix -@kbd{a} to add the score rule to the @file{all.SCORE} file. - -@item -@code{gnus-simplify-subject-functions} variable to allow greater -control over simplification. - -@item -@kbd{A T}---new command for fetching the current thread. - -@item -@kbd{/ T}---new command for including the current thread in the -limit. - -@item -@kbd{M-RET} is a new Message command for breaking cited text. - -@item -@samp{\\1}-expressions are now valid in @code{nnmail-split-methods}. - -@item -The @code{custom-face-lookup} function has been removed. -If you used this function in your initialization files, you must -rewrite them to use @code{face-spec-set} instead. - -@item -Canceling now uses the current select method. Symbolic prefix -@kbd{a} forces normal posting method. - -@item -New command to translate M******** sm*rtq**t*s into proper -text---@kbd{W d}. - -@item -For easier debugging of @code{nntp}, you can set -@code{nntp-record-commands} to a non-@code{nil} value. - -@item -@code{nntp} now uses @file{~/.authinfo}, a @file{.netrc}-like file, for -controlling where and how to send @sc{authinfo} to @acronym{NNTP} servers. - -@item -A command for editing group parameters from the summary buffer -has been added. - -@item -A history of where mails have been split is available. - -@item -A new article date command has been added---@code{article-date-iso8601}. - -@item -Subjects can be simplified when threading by setting -@code{gnus-score-thread-simplify}. - -@item -A new function for citing in Message has been -added---@code{message-cite-original-without-signature}. - -@item -@code{article-strip-all-blank-lines}---new article command. - -@item -A new Message command to kill to the end of the article has -been added. - -@item -A minimum adaptive score can be specified by using the -@code{gnus-adaptive-word-minimum} variable. - -@item -The ``lapsed date'' article header can be kept continually -updated by the @code{gnus-start-date-timer} command. - -@item -Web listserv archives can be read with the @code{nnlistserv} back end. - -@item -Old dejanews archives can now be read by @code{nnweb}. - -@end itemize - -@node Pterodactyl Gnus -@subsubsection Pterodactyl Gnus - -New features in Gnus 5.8: - -@itemize @bullet - -@item -The mail-fetching functions have changed. See the manual for the -many details. In particular, all procmail fetching variables are gone. - -If you used procmail like in - -@lisp -(setq nnmail-use-procmail t) -(setq nnmail-spool-file 'procmail) -(setq nnmail-procmail-directory "~/mail/incoming/") -(setq nnmail-procmail-suffix "\\.in") -@end lisp - -this now has changed to - -@lisp -(setq mail-sources - '((directory :path "~/mail/incoming/" - :suffix ".in"))) -@end lisp - -@xref{Mail Source Specifiers}. - -@item -Gnus is now a @acronym{MIME}-capable reader. This affects many parts of -Gnus, and adds a slew of new commands. See the manual for details. - -@item -Gnus has also been multilingualized. This also affects too -many parts of Gnus to summarize here, and adds many new variables. - -@item -@code{gnus-auto-select-first} can now be a function to be -called to position point. - -@item -The user can now decide which extra headers should be included in -summary buffers and @acronym{NOV} files. - -@item -@code{gnus-article-display-hook} has been removed. Instead, a number -of variables starting with @code{gnus-treat-} have been added. - -@item -The Gnus posting styles have been redone again and now works in a -subtly different manner. - -@item -New web-based back ends have been added: @code{nnslashdot}, -@code{nnwarchive} and @code{nnultimate}. nnweb has been revamped, -again, to keep up with ever-changing layouts. - -@item -Gnus can now read @acronym{IMAP} mail via @code{nnimap}. - -@end itemize - -@node Oort Gnus -@subsubsection Oort Gnus -@cindex Oort Gnus - -New features in Gnus 5.10: - -@itemize @bullet - -@item Installation changes -@c *********************** - -@itemize @bullet -@item -Upgrading from previous (stable) version if you have used Oort. - -If you have tried Oort (the unstable Gnus branch leading to this -release) but went back to a stable version, be careful when upgrading to -this version. In particular, you will probably want to remove all -@file{.marks} (nnml) and @file{.mrk} (nnfolder) files, so that flags are -read from your @file{.newsrc.eld} instead of from the -@file{.marks}/@file{.mrk} file where this release store flags. See a -later entry for more information about marks. Note that downgrading -isn't save in general. - -@item -Lisp files are now installed in @file{.../site-lisp/gnus/} by default. -It defaulted to @file{.../site-lisp/} formerly. In addition to this, -the new installer issues a warning if other Gnus installations which -will shadow the latest one are detected. You can then remove those -shadows manually or remove them using @code{make -remove-installed-shadows}. - -@item -New @file{make.bat} for compiling and installing Gnus under MS Windows - -Use @file{make.bat} if you want to install Gnus under MS Windows, the -first argument to the batch-program should be the directory where -@file{xemacs.exe} respectively @file{emacs.exe} is located, if you want -to install Gnus after compiling it, give @file{make.bat} @code{/copy} as -the second parameter. - -@file{make.bat} has been rewritten from scratch, it now features -automatic recognition of XEmacs and Emacs, generates -@file{gnus-load.el}, checks if errors occur while compilation and -generation of info files and reports them at the end of the build -process. It now uses @code{makeinfo} if it is available and falls -back to @file{infohack.el} otherwise. @file{make.bat} should now -install all files which are necessary to run Gnus and be generally a -complete replacement for the @code{configure; make; make install} -cycle used under Unix systems. - -The new @file{make.bat} makes @file{make-x.bat} and @file{xemacs.mak} -superfluous, so they have been removed. - -@item -@file{~/News/overview/} not used. - -As a result of the following change, the @file{~/News/overview/} -directory is not used any more. You can safely delete the entire -hierarchy. - -@c FIXME: `gnus-load' is mentioned in README, which is not included in -@c the repository. We should find a better place for this item. -@item -@code{(require 'gnus-load)} - -If you use a stand-alone Gnus distribution, you'd better add -@code{(require 'gnus-load)} into your @file{~/.emacs} after adding the Gnus -lisp directory into load-path. - -File @file{gnus-load.el} contains autoload commands, functions and variables, -some of which may not be included in distributions of Emacsen. - -@end itemize - -@item New packages and libraries within Gnus -@c ***************************************** - -@itemize @bullet - -@item -The revised Gnus @acronym{FAQ} is included in the manual, -@xref{Frequently Asked Questions}. - -@item -@acronym{TLS} wrapper shipped with Gnus - -@acronym{TLS}/@acronym{SSL} is now supported in @acronym{IMAP} and -@acronym{NNTP} via @file{tls.el} and GnuTLS. - -@item -Improved anti-spam features. - -Gnus is now able to take out spam from your mail and news streams -using a wide variety of programs and filter rules. Among the supported -methods are RBL blocklists, bogofilter and white/blacklists. Hooks -for easy use of external packages such as SpamAssassin and Hashcash -are also new. @ref{Thwarting Email Spam} and @ref{Spam Package}. -@c FIXME: @xref{Spam Package}?. Should this be under Misc? - -@item -Gnus supports server-side mail filtering using Sieve. - -Sieve rules can be added as Group Parameters for groups, and the -complete Sieve script is generated using @kbd{D g} from the Group -buffer, and then uploaded to the server using @kbd{C-c C-l} in the -generated Sieve buffer. @xref{Sieve Commands}, and the new Sieve -manual @ref{Top, , Top, sieve, Emacs Sieve}. - -@end itemize - -@item Changes in group mode -@c ************************ - -@itemize @bullet - -@item -@code{gnus-group-read-ephemeral-group} can be called interactively, -using @kbd{G M}. - -@item -Retrieval of charters and control messages - -There are new commands for fetching newsgroup charters (@kbd{H c}) and -control messages (@kbd{H C}). - -@item -The new variable @code{gnus-parameters} can be used to set group parameters. - -Earlier this was done only via @kbd{G p} (or @kbd{G c}), which stored -the parameters in @file{~/.newsrc.eld}, but via this variable you can -enjoy the powers of customize, and simplified backups since you set the -variable in @file{~/.gnus.el} instead of @file{~/.newsrc.eld}. The -variable maps regular expressions matching group names to group -parameters, a'la: -@lisp -(setq gnus-parameters - '(("mail\\..*" - (gnus-show-threads nil) - (gnus-use-scoring nil)) - ("^nnimap:\\(foo.bar\\)$" - (to-group . "\\1")))) -@end lisp - -@item -Unread count correct in nnimap groups. - -The estimated number of unread articles in the group buffer should now -be correct for nnimap groups. This is achieved by calling -@code{nnimap-fixup-unread-after-getting-new-news} from the -@code{gnus-setup-news-hook} (called on startup) and -@code{gnus-after-getting-new-news-hook}. (called after getting new -mail). If you have modified those variables from the default, you may -want to add @code{nnimap-fixup-unread-after-getting-new-news} again. If -you were happy with the estimate and want to save some (minimal) time -when getting new mail, remove the function. - -@item -Group names are treated as UTF-8 by default. - -This is supposedly what USEFOR wanted to migrate to. See -@code{gnus-group-name-charset-group-alist} and -@code{gnus-group-name-charset-method-alist} for customization. - -@item -@code{gnus-group-charset-alist} and -@code{gnus-group-ignored-charsets-alist}. - -The regexps in these variables are compared with full group names -instead of real group names in 5.8. Users who customize these -variables should change those regexps accordingly. For example: -@lisp -("^han\\>" euc-kr) -> ("\\(^\\|:\\)han\\>" euc-kr) -@end lisp - -@item -Old intermediate incoming mail files (@file{Incoming*}) are deleted -after a couple of days, not immediately. @xref{Mail Source -Customization}. (New in Gnus 5.10.10 / Emacs 22.2) - -@end itemize - -@item Changes in summary and article mode -@c ************************************** - -@itemize @bullet - -@item -@kbd{F} (@code{gnus-article-followup-with-original}) and @kbd{R} -(@code{gnus-article-reply-with-original}) only yank the text in the -region if the region is active. - -@item -In draft groups, @kbd{e} is now bound to @code{gnus-draft-edit-message}. -Use @kbd{B w} for @code{gnus-summary-edit-article} instead. - -@item -Article Buttons - -More buttons for URLs, mail addresses, Message-IDs, Info links, man -pages and Emacs or Gnus related references. @xref{Article Buttons}. The -variables @code{gnus-button-@var{*}-level} can be used to control the -appearance of all article buttons. @xref{Article Button Levels}. - -@item -Single-part yenc encoded attachments can be decoded. - -@item -Picons - -The picons code has been reimplemented to work in GNU Emacs---some of -the previous options have been removed or renamed. - -Picons are small ``personal icons'' representing users, domain and -newsgroups, which can be displayed in the Article buffer. -@xref{Picons}. - -@item -If the new option @code{gnus-treat-body-boundary} is non-@code{nil}, a -boundary line is drawn at the end of the headers. - -@item -Signed article headers (X-PGP-Sig) can be verified with @kbd{W p}. - -@item -The Summary Buffer uses an arrow in the fringe to indicate the current -article. Use @code{(setq gnus-summary-display-arrow nil)} to disable it. - -@item -Warn about email replies to news - -Do you often find yourself replying to news by email by mistake? Then -the new option @code{gnus-confirm-mail-reply-to-news} is just the thing for -you. - -@item -If the new option @code{gnus-summary-display-while-building} is -non-@code{nil}, the summary buffer is shown and updated as it's being -built. - -@item -Gnus supports RFC 2369 mailing list headers, and adds a number of -related commands in mailing list groups. @xref{Mailing List}. - -@item -The Date header can be displayed in a format that can be read aloud -in English. @xref{Article Date}. - -@item -diffs are automatically highlighted in groups matching -@code{mm-uu-diff-groups-regexp} - -@item -Better handling of Microsoft citation styles - -Gnus now tries to recognize the mangled header block that some Microsoft -mailers use to indicate that the rest of the message is a citation, even -though it is not quoted in any way. The variable -@code{gnus-cite-unsightly-citation-regexp} matches the start of these -citations. - -The new command @kbd{W Y f} -(@code{gnus-article-outlook-deuglify-article}) allows deuglifying broken -Outlook (Express) articles. - -@item -@code{gnus-article-skip-boring} - -If you set @code{gnus-article-skip-boring} to @code{t}, then Gnus will -not scroll down to show you a page that contains only boring text, -which by default means cited text and signature. You can customize -what is skippable using @code{gnus-article-boring-faces}. - -This feature is especially useful if you read many articles that -consist of a little new content at the top with a long, untrimmed -message cited below. - -@item -Smileys (@samp{:-)}, @samp{;-)} etc) are now displayed graphically in -Emacs too. - -Put @code{(setq gnus-treat-display-smileys nil)} in @file{~/.gnus.el} to -disable it. - -@item -Face headers handling. @xref{Face}. - -@item -In the summary buffer, the new command @kbd{/ N} inserts new messages -and @kbd{/ o} inserts old messages. - -@item -Gnus decodes morse encoded messages if you press @kbd{W m}. - -@item -@code{gnus-summary-line-format} - -The default value changed to @samp{%U%R%z%I%(%[%4L: %-23,23f%]%) -%s\n}. Moreover @code{gnus-extra-headers}, -@code{nnmail-extra-headers} and @code{gnus-ignored-from-addresses} -changed their default so that the users name will be replaced by the -recipient's name or the group name posting to for @acronym{NNTP} -groups. - -@item -Deleting of attachments. - -The command @code{gnus-mime-save-part-and-strip} (bound to @kbd{C-o} -on @acronym{MIME} buttons) saves a part and replaces the part with an -external one. @code{gnus-mime-delete-part} (bound to @kbd{d} on -@acronym{MIME} buttons) removes a part. It works only on back ends -that support editing. - -@item -@code{gnus-default-charset} - -The default value is determined from the -@code{current-language-environment} variable, instead of -@code{iso-8859-1}. Also the @samp{.*} item in -@code{gnus-group-charset-alist} is removed. - -@item -Printing capabilities are enhanced. - -Gnus supports Muttprint natively with @kbd{O P} from the Summary and -Article buffers. Also, each individual @acronym{MIME} part can be -printed using @kbd{p} on the @acronym{MIME} button. - -@item -Extended format specs. - -Format spec @samp{%&user-date;} is added into -@code{gnus-summary-line-format-alist}. Also, user defined extended -format specs are supported. The extended format specs look like -@samp{%u&foo;}, which invokes function -@code{gnus-user-format-function-@var{foo}}. Because @samp{&} is used as the -escape character, old user defined format @samp{%u&} is no longer supported. - -@item -@kbd{/ *} (@code{gnus-summary-limit-include-cached}) is rewritten. -@c FIXME: Was this a user-visible change? - -It was aliased to @kbd{Y c} -(@code{gnus-summary-insert-cached-articles}). The new function filters -out other articles. - -@item -Some limiting commands accept a @kbd{C-u} prefix to negate the match. - -If @kbd{C-u} is used on subject, author or extra headers, i.e., @kbd{/ -s}, @kbd{/ a}, and @kbd{/ x} -(@code{gnus-summary-limit-to-@{subject,author,extra@}}) respectively, the -result will be to display all articles that do not match the expression. - -@item -Gnus inlines external parts (message/external). - -@end itemize - -@item Changes in Message mode and related Gnus features -@c **************************************************** - -@itemize @bullet - -@item -Delayed articles - -You can delay the sending of a message with @kbd{C-c C-j} in the Message -buffer. The messages are delivered at specified time. This is useful -for sending yourself reminders. @xref{Delayed Articles}. - -@item -If the new option @code{nnml-use-compressed-files} is non-@code{nil}, -the nnml back end allows compressed message files. - -@item -The new option @code{gnus-gcc-mark-as-read} automatically marks -Gcc articles as read. - -@item -Externalizing of attachments - -If @code{gnus-gcc-externalize-attachments} or -@code{message-fcc-externalize-attachments} is non-@code{nil}, attach -local files as external parts. - -@item -The envelope sender address can be customized when using Sendmail. -@xref{Mail Variables, Mail Variables,, message, Message Manual}. - -@item -Gnus no longer generate the Sender: header automatically. - -Earlier it was generated when the user configurable email address was -different from the Gnus guessed default user address. As the guessing -algorithm is rarely correct these days, and (more controversially) the -only use of the Sender: header was to check if you are entitled to -cancel/supersede news (which is now solved by Cancel Locks instead, -see another entry), generation of the header has been disabled by -default. See the variables @code{message-required-headers}, -@code{message-required-news-headers}, and -@code{message-required-mail-headers}. - -@item -Features from third party @file{message-utils.el} added to @file{message.el}. - -Message now asks if you wish to remove @samp{(was: )} from -subject lines (see @code{message-subject-trailing-was-query}). @kbd{C-c -M-m} and @kbd{C-c M-f} inserts markers indicating included text. -@kbd{C-c C-f a} adds a X-No-Archive: header. @kbd{C-c C-f x} inserts -appropriate headers and a note in the body for cross-postings and -followups (see the variables @code{message-cross-post-@var{*}}). - -@item -References and X-Draft-From headers are no longer generated when you -start composing messages and @code{message-generate-headers-first} is -@code{nil}. - -@item -Easy inclusion of X-Faces headers. @xref{X-Face}. - -@item -Group Carbon Copy (GCC) quoting - -To support groups that contains SPC and other weird characters, groups -are quoted before they are placed in the Gcc: header. This means -variables such as @code{gnus-message-archive-group} should no longer -contain quote characters to make groups containing SPC work. Also, if -you are using the string @samp{nnml:foo, nnml:bar} (indicating Gcc -into two groups) you must change it to return the list -@code{("nnml:foo" "nnml:bar")}, otherwise the Gcc: line will be quoted -incorrectly. Note that returning the string @samp{nnml:foo, nnml:bar} -was incorrect earlier, it just didn't generate any problems since it -was inserted directly. - -@item -@code{message-insinuate-rmail} - -@c FIXME should that not be 'message-user-agent? -Adding @code{(message-insinuate-rmail)} and @code{(setq -mail-user-agent 'gnus-user-agent)} in @file{.emacs} convinces Rmail to -compose, reply and forward messages in message-mode, where you can -enjoy the power of @acronym{MML}. - -@item -@code{message-minibuffer-local-map} - -The line below enables BBDB in resending a message: -@lisp -(define-key message-minibuffer-local-map [(tab)] - 'bbdb-complete-name) -@end lisp - -@item -@code{gnus-posting-styles} - -Add a new format of match like -@lisp -((header "to" "larsi.*org") - (Organization "Somewhere, Inc.")) -@end lisp -The old format like the lines below is obsolete, but still accepted. -@lisp -(header "to" "larsi.*org" - (Organization "Somewhere, Inc.")) -@end lisp - -@item -@code{message-ignored-news-headers} and @code{message-ignored-mail-headers} - -@samp{X-Draft-From} and @samp{X-Gnus-Agent-Meta-Information} have been -added into these two variables. If you customized those, perhaps you -need add those two headers too. - -@item -Gnus supports the ``format=flowed'' (RFC 2646) parameter. On -composing messages, it is enabled by @code{use-hard-newlines}. -Decoding format=flowed was present but not documented in earlier -versions. - -@item -The option @code{mm-fill-flowed} can be used to disable treatment of -``format=flowed'' messages. Also, flowed text is disabled when sending -inline PGP signed messages. @xref{Flowed text, , Flowed text, -emacs-mime, The Emacs MIME Manual}. (New in Gnus 5.10.7) -@c This entry is also present in the node "No Gnus". - -@item -Gnus supports the generation of RFC 2298 Disposition Notification requests. - -This is invoked with the @kbd{C-c M-n} key binding from message mode. - -@item -Message supports the Importance: (RFC 2156) header. - -In the message buffer, @kbd{C-c C-f C-i} or @kbd{C-c C-u} cycles through -the valid values. - -@item -Gnus supports Cancel Locks in News. - -This means a header @samp{Cancel-Lock} is inserted in news posting. It is -used to determine if you wrote an article or not (for canceling and -superseding). Gnus generates a random password string the first time -you post a message, and saves it in your @file{~/.emacs} using the Custom -system. While the variable is called @code{canlock-password}, it is not -security sensitive data. Publishing your canlock string on the web -will not allow anyone to be able to anything she could not already do. -The behavior can be changed by customizing @code{message-insert-canlock}. - -@item -Gnus supports @acronym{PGP} (RFC 1991/2440), @acronym{PGP/MIME} (RFC -2015/3156) and @acronym{S/MIME} (RFC 2630-2633). - -It needs an external @acronym{S/MIME} and OpenPGP implementation, but no -additional Lisp libraries. This add several menu items to the -Attachments menu, and @kbd{C-c RET} key bindings, when composing -messages. This also obsoletes @code{gnus-article-hide-pgp-hook}. - -@item -@acronym{MML} (Mime compose) prefix changed from @kbd{M-m} to @kbd{C-c -C-m}. - -This change was made to avoid conflict with the standard binding of -@code{back-to-indentation}, which is also useful in message mode. - -@item -The default for @code{message-forward-show-mml} changed to the symbol -@code{best}. - -The behavior for the @code{best} value is to show @acronym{MML} (i.e., -convert to @acronym{MIME}) when appropriate. @acronym{MML} will not be -used when forwarding signed or encrypted messages, as the conversion -invalidate the digital signature. - -@item -If @code{auto-compression-mode} is enabled, attachments are automatically -decompressed when activated. -@c FIXME: Does this affect article or message mode? - -@item -Support for non-@acronym{ASCII} domain names - -Message supports non-@acronym{ASCII} domain names in From:, To: and -Cc: and will query you whether to perform encoding when you try to -send a message. The variable @code{message-use-idna} controls this. -Gnus will also decode non-@acronym{ASCII} domain names in From:, To: -and Cc: when you view a message. The variable @code{gnus-use-idna} -controls this. - -@item You can now drag and drop attachments to the Message buffer. -See @code{mml-dnd-protocol-alist} and @code{mml-dnd-attach-options}. -@xref{MIME, ,MIME, message, Message Manual}. -@c New in 5.10.9 / 5.11 (Emacs 22.1) - -@item @code{auto-fill-mode} is enabled by default in Message mode. -See @code{message-fill-column}. @xref{Various Message Variables, , -Message Headers, message, Message Manual}. -@c New in Gnus 5.10.12 / 5.11 (Emacs 22.3) - -@end itemize - -@item Changes in back ends -@c *********************** - -@itemize @bullet -@item -Gnus can display RSS newsfeeds as a newsgroup. @xref{RSS}. - -@item -The nndoc back end now supports mailman digests and exim bounces. - -@item -Gnus supports Maildir groups. - -Gnus includes a new back end @file{nnmaildir.el}. @xref{Maildir}. - -@item -The nnml and nnfolder back ends store marks for each groups. - -This makes it possible to take backup of nnml/nnfolder servers/groups -separately of @file{~/.newsrc.eld}, while preserving marks. It also -makes it possible to share articles and marks between users (without -sharing the @file{~/.newsrc.eld} file) within e.g. a department. It -works by storing the marks stored in @file{~/.newsrc.eld} in a per-group -file @file{.marks} (for nnml) and @file{@var{groupname}.mrk} (for -nnfolder, named @var{groupname}). If the nnml/nnfolder is moved to -another machine, Gnus will automatically use the @file{.marks} or -@file{.mrk} file instead of the information in @file{~/.newsrc.eld}. -The new server variables @code{nnml-marks-is-evil} and -@code{nnfolder-marks-is-evil} can be used to disable this feature. - -@end itemize - -@item Appearance -@c ************* - -@itemize @bullet - -@item -The menu bar item (in Group and Summary buffer) named ``Misc'' has -been renamed to ``Gnus''. - -@item -The menu bar item (in Message mode) named ``@acronym{MML}'' has been -renamed to ``Attachments''. Note that this menu also contains security -related stuff, like signing and encryption (@pxref{Security, Security,, -message, Message Manual}). - -@item -The tool bars have been updated to use GNOME icons in Group, Summary and -Message mode. You can also customize the tool bars: @kbd{M-x -customize-apropos RET -tool-bar$} should get you started. This is a new -feature in Gnus 5.10.10. (Only for Emacs, not in XEmacs.) - -@item The tool bar icons are now (de)activated correctly -in the group buffer, see the variable @code{gnus-group-update-tool-bar}. -Its default value depends on your Emacs version. This is a new feature -in Gnus 5.10.9. -@end itemize - - -@item Miscellaneous changes -@c ************************ - -@itemize @bullet - -@item -@code{gnus-agent} - -The Gnus Agent has seen a major updated and is now enabled by default, -and all nntp and nnimap servers from @code{gnus-select-method} and -@code{gnus-secondary-select-method} are agentized by default. Earlier -only the server in @code{gnus-select-method} was agentized by the -default, and the agent was disabled by default. When the agent is -enabled, headers are now also retrieved from the Agent cache instead -of the back ends when possible. Earlier this only happened in the -unplugged state. You can enroll or remove servers with @kbd{J a} and -@kbd{J r} in the server buffer. Gnus will not download articles into -the Agent cache, unless you instruct it to do so, though, by using -@kbd{J u} or @kbd{J s} from the Group buffer. You revert to the old -behavior of having the Agent disabled with @code{(setq gnus-agent -nil)}. Note that putting @code{(gnus-agentize)} in @file{~/.gnus.el} -is not needed any more. - -@item -Gnus reads the @acronym{NOV} and articles in the Agent if plugged. - -If one reads an article while plugged, and the article already exists -in the Agent, it won't get downloaded once more. @code{(setq -gnus-agent-cache nil)} reverts to the old behavior. - -@item -Dired integration - -@code{gnus-dired-minor-mode} (see @ref{Other modes}) installs key -bindings in dired buffers to send a file as an attachment, open a file -using the appropriate mailcap entry, and print a file using the mailcap -entry. - -@item -The format spec @code{%C} for positioning point has changed to @code{%*}. - -@item -@code{gnus-slave-unplugged} - -A new command which starts Gnus offline in slave mode. - -@end itemize - -@end itemize - -@node No Gnus -@subsubsection No Gnus -@cindex No Gnus - -New features in No Gnus: -@c FIXME: Gnus 5.12? - -@include gnus-news.texi - -@iftex - -@page -@node The Manual -@section The Manual -@cindex colophon -@cindex manual - -This manual was generated from a TeXinfo file and then run through -either @code{texi2dvi} -@iflatex -or my own home-brewed TeXinfo to \LaTeX\ transformer, -and then run through @code{latex} and @code{dvips} -@end iflatex -to get what you hold in your hands now. - -The following conventions have been used: - -@enumerate - -@item -This is a @samp{string} - -@item -This is a @kbd{keystroke} - -@item -This is a @file{file} - -@item -This is a @code{symbol} - -@end enumerate - -So if I were to say ``set @code{flargnoze} to @samp{yes}'', that would -mean: - -@lisp -(setq flargnoze "yes") -@end lisp - -If I say ``set @code{flumphel} to @code{yes}'', that would mean: - -@lisp -(setq flumphel 'yes) -@end lisp - -@samp{yes} and @code{yes} are two @emph{very} different things---don't -ever get them confused. - -@iflatex -@c @head -Of course, everything in this manual is of vital interest, so you should -read it all. Several times. However, if you feel like skimming the -manual, look for that gnu head you should see in the margin over -there---it means that what's being discussed is of more importance than -the rest of the stuff. (On the other hand, if everything is infinitely -important, how can anything be more important than that? Just one more -of the mysteries of this world, I guess.) -@end iflatex - -@end iftex - - -@node On Writing Manuals -@section On Writing Manuals - -I guess most manuals are written after-the-fact; documenting a program -that's already there. This is not how this manual is written. When -implementing something, I write the manual entry for that something -straight away. I then see that it's difficult to explain the -functionality, so I write how it's supposed to be, and then I change the -implementation. Writing the documentation and writing the code go hand -in hand. - -This, of course, means that this manual has no, or little, flow. It -documents absolutely everything in Gnus, but often not where you're -looking for it. It is a reference manual, and not a guide to how to get -started with Gnus. - -That would be a totally different book, that should be written using the -reference manual as source material. It would look quite different. - - -@page -@node Terminology -@section Terminology - -@cindex terminology -@table @dfn - -@item news -@cindex news -This is what you are supposed to use this thing for---reading news. -News is generally fetched from a nearby @acronym{NNTP} server, and is -generally publicly available to everybody. If you post news, the entire -world is likely to read just what you have written, and they'll all -snigger mischievously. Behind your back. - -@item mail -@cindex mail -Everything that's delivered to you personally is mail. Some news/mail -readers (like Gnus) blur the distinction between mail and news, but -there is a difference. Mail is private. News is public. Mailing is -not posting, and replying is not following up. - -@item reply -@cindex reply -Send a mail to the person who has written what you are reading. - -@item follow up -@cindex follow up -Post an article to the current newsgroup responding to the article you -are reading. - -@item back end -@cindex back end -Gnus considers mail and news to be mostly the same, really. The only -difference is how to access the actual articles. News articles are -commonly fetched via the protocol @acronym{NNTP}, whereas mail -messages could be read from a file on the local disk. The internal -architecture of Gnus thus comprises a ``front end'' and a number of -``back ends''. Internally, when you enter a group (by hitting -@key{RET}, say), you thereby invoke a function in the front end in -Gnus. The front end then ``talks'' to a back end and says things like -``Give me the list of articles in the foo group'' or ``Show me article -number 4711''. - -So a back end mainly defines either a protocol (the @code{nntp} back -end accesses news via @acronym{NNTP}, the @code{nnimap} back end -accesses mail via @acronym{IMAP}) or a file format and directory -layout (the @code{nnspool} back end accesses news via the common -``spool directory'' format, the @code{nnml} back end access mail via a -file format and directory layout that's quite similar). - -Gnus does not handle the underlying media, so to speak---this is all -done by the back ends. A back end is a collection of functions to -access the articles. - -However, sometimes the term ``back end'' is also used where ``server'' -would have been more appropriate. And then there is the term ``select -method'' which can mean either. The Gnus terminology can be quite -confusing. - -@item native -@cindex native -Gnus will always use one method (and back end) as the @dfn{native}, or -default, way of getting news. Groups from the native select method -have names like @samp{gnu.emacs.gnus}. - -@item foreign -@cindex foreign -You can also have any number of foreign groups active at the same -time. These are groups that use non-native non-secondary back ends -for getting news. Foreign groups have names like -@samp{nntp+news.gmane.org:gmane.emacs.gnus.devel}. - -@item secondary -@cindex secondary -Secondary back ends are somewhere half-way between being native and -being foreign, but they mostly act like they are native, but they, too -have names like @samp{nntp+news.gmane.org:gmane.emacs.gnus.devel}. - -@item article -@cindex article -A message that has been posted as news. - -@item mail message -@cindex mail message -A message that has been mailed. - -@item message -@cindex message -A mail message or news article - -@item head -@cindex head -The top part of a message, where administrative information (etc.) is -put. - -@item body -@cindex body -The rest of an article. Everything not in the head is in the -body. - -@item header -@cindex header -A line from the head of an article. - -@item headers -@cindex headers -A collection of such lines, or a collection of heads. Or even a -collection of @acronym{NOV} lines. - -@item @acronym{NOV} -@cindex @acronym{NOV} -@acronym{NOV} stands for News OverView, which is a type of news server -header which provide datas containing the condensed header information -of articles. They are produced by the server itself; in the @code{nntp} -back end Gnus uses the ones that the @acronym{NNTP} server makes, but -Gnus makes them by itself for some backends (in particular, @code{nnml}). - -When Gnus enters a group, it asks the back end for the headers of all -unread articles in the group. Most servers support the News OverView -format, which is more compact and much faster to read and parse than the -normal @sc{head} format. - -The @acronym{NOV} data consist of one or more text lines (@pxref{Text -Lines, ,Motion by Text Lines, elisp, The Emacs Lisp Reference Manual}) -where each line has the header information of one article. The header -information is a tab-separated series of the header's contents including -an article number, a subject, an author, a date, a message-id, -references, etc. - -Those data enable Gnus to generate summary lines quickly. However, if -the server does not support @acronym{NOV} or you disable it purposely or -for some reason, Gnus will try to generate the header information by -parsing each article's headers one by one. It will take time. -Therefore, it is not usually a good idea to set nn*-nov-is-evil -(@pxref{Slow/Expensive Connection}) to a non-@code{nil} value unless you -know that the server makes wrong @acronym{NOV} data. - -@item level -@cindex levels -Each group is subscribed at some @dfn{level} or other (1-9). The ones -that have a lower level are ``more'' subscribed than the groups with a -higher level. In fact, groups on levels 1-5 are considered -@dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9 -are @dfn{killed}. Commands for listing groups and scanning for new -articles will all use the numeric prefix as @dfn{working level}. - -@item killed groups -@cindex killed groups -No information on killed groups is stored or updated, which makes killed -groups much easier to handle than subscribed groups. - -@item zombie groups -@cindex zombie groups -Just like killed groups, only slightly less dead. - -@item active file -@cindex active file -The news server has to keep track of what articles it carries, and what -groups exist. All this information in stored in the active file, which -is rather large, as you might surmise. - -@item bogus groups -@cindex bogus groups -A group that exists in the @file{.newsrc} file, but isn't known to the -server (i.e., it isn't in the active file), is a @emph{bogus group}. -This means that the group probably doesn't exist (any more). - -@item activating -@cindex activating groups -The act of asking the server for info on a group and computing the -number of unread articles is called @dfn{activating the group}. -Un-activated groups are listed with @samp{*} in the group buffer. - -@item spool -@cindex spool -News servers store their articles locally in one fashion or other. -One old-fashioned storage method is to have just one file per -article. That's called a ``traditional spool''. - -@item server -@cindex server -A machine one can connect to and get news (or mail) from. - -@item select method -@cindex select method -A structure that specifies the back end, the server and the virtual -server settings. - -@item virtual server -@cindex virtual server -A named select method. Since a select method defines all there is to -know about connecting to a (physical) server, taking the thing as a -whole is a virtual server. - -@item washing -@cindex washing -Taking a buffer and running it through a filter of some sort. The -result will (more often than not) be cleaner and more pleasing than the -original. - -@item ephemeral groups -@cindex ephemeral groups -@cindex temporary groups -Most groups store data on what articles you have read. @dfn{Ephemeral} -groups are groups that will have no data stored---when you exit the -group, it'll disappear into the aether. - -@item solid groups -@cindex solid groups -This is the opposite of ephemeral groups. All groups listed in the -group buffer are solid groups. - -@item sparse articles -@cindex sparse articles -These are article placeholders shown in the summary buffer when -@code{gnus-build-sparse-threads} has been switched on. - -@item threading -@cindex threading -To put responses to articles directly after the articles they respond -to---in a hierarchical fashion. - -@item root -@cindex root -@cindex thread root -The first article in a thread is the root. It is the ancestor of all -articles in the thread. - -@item parent -@cindex parent -An article that has responses. - -@item child -@cindex child -An article that responds to a different article---its parent. - -@item digest -@cindex digest -A collection of messages in one file. The most common digest format is -specified by RFC 1153. - -@item splitting -@cindex splitting, terminology -@cindex mail sorting -@cindex mail filtering (splitting) -The action of sorting your emails according to certain rules. Sometimes -incorrectly called mail filtering. - -@end table - - -@page -@node Customization -@section Customization -@cindex general customization - -All variables are properly documented elsewhere in this manual. This -section is designed to give general pointers on how to customize Gnus -for some quite common situations. - -@menu -* Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere. -* Slow Terminal Connection:: You run a remote Emacs. -* Little Disk Space:: You feel that having large setup files is icky. -* Slow Machine:: You feel like buying a faster machine. -@end menu - - -@node Slow/Expensive Connection -@subsection Slow/Expensive Connection - -If you run Emacs on a machine locally, and get your news from a machine -over some very thin strings, you want to cut down on the amount of data -Gnus has to get from the server. - -@table @code - -@item gnus-read-active-file -Set this to @code{nil}, which will inhibit Gnus from requesting the -entire active file from the server. This file is often very large. You -also have to set @code{gnus-check-new-newsgroups} and -@code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus -doesn't suddenly decide to fetch the active file anyway. - -@item gnus-nov-is-evil -@vindex gnus-nov-is-evil -Usually this one must @emph{always} be @code{nil} (which is the -default). If, for example, you wish to not use @acronym{NOV} -(@pxref{Terminology}) with the @code{nntp} back end (@pxref{Crosspost -Handling}), set @code{nntp-nov-is-evil} to a non-@code{nil} value -instead of setting this. But you normally do not need to set -@code{nntp-nov-is-evil} since Gnus by itself will detect whether the -@acronym{NNTP} server supports @acronym{NOV}. Anyway, grabbing article -headers from the @acronym{NNTP} server will not be very fast if you tell -Gnus not to use @acronym{NOV}. - -As the variables for the other back ends, there are -@code{nndiary-nov-is-evil}, @code{nndir-nov-is-evil}, -@code{nnfolder-nov-is-evil}, @code{nnimap-nov-is-evil}, -@code{nnml-nov-is-evil}, and @code{nnspool-nov-is-evil}. Note that a -non-@code{nil} value for @code{gnus-nov-is-evil} overrides all those -variables. -@end table - - -@node Slow Terminal Connection -@subsection Slow Terminal Connection - -Let's say you use your home computer for dialing up the system that runs -Emacs and Gnus. If your modem is slow, you want to reduce (as much as -possible) the amount of data sent over the wires. - -@table @code - -@item gnus-auto-center-summary -Set this to @code{nil} to inhibit Gnus from re-centering the summary -buffer all the time. If it is @code{vertical}, do only vertical -re-centering. If it is neither @code{nil} nor @code{vertical}, do both -horizontal and vertical recentering. - -@item gnus-visible-headers -Cut down on the headers included in the articles to the -minimum. You can, in fact, make do without them altogether---most of the -useful data is in the summary buffer, anyway. Set this variable to -@samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need. - -Use the following to enable all the available hiding features: -@lisp -(setq gnus-treat-hide-headers 'head - gnus-treat-hide-signature t - gnus-treat-hide-citation t) -@end lisp - -@item gnus-use-full-window -By setting this to @code{nil}, you can make all the windows smaller. -While this doesn't really cut down much generally, it means that you -have to see smaller portions of articles before deciding that you didn't -want to read them anyway. - -@item gnus-thread-hide-subtree -If this is non-@code{nil}, all threads in the summary buffer will be -hidden initially. - - -@item gnus-updated-mode-lines -If this is @code{nil}, Gnus will not put information in the buffer mode -lines, which might save some time. -@end table - - -@node Little Disk Space -@subsection Little Disk Space -@cindex disk space - -The startup files can get rather large, so you may want to cut their -sizes a bit if you are running out of space. - -@table @code - -@item gnus-save-newsrc-file -If this is @code{nil}, Gnus will never save @file{.newsrc}---it will -only save @file{.newsrc.eld}. This means that you will not be able to -use any other newsreaders than Gnus. This variable is @code{t} by -default. - -@item gnus-read-newsrc-file -If this is @code{nil}, Gnus will never read @file{.newsrc}---it will -only read @file{.newsrc.eld}. This means that you will not be able to -use any other newsreaders than Gnus. This variable is @code{t} by -default. - -@item gnus-save-killed-list -If this is @code{nil}, Gnus will not save the list of dead groups. You -should also set @code{gnus-check-new-newsgroups} to @code{ask-server} -and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this -variable to @code{nil}. This variable is @code{t} by default. - -@end table - - -@node Slow Machine -@subsection Slow Machine -@cindex slow machine - -If you have a slow machine, or are just really impatient, there are a -few things you can do to make Gnus run faster. - -Set @code{gnus-check-new-newsgroups} and -@code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster. - -Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and -@code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the -summary buffer faster. Also @pxref{Slow/Expensive Connection}. - - -@page -@node Troubleshooting -@section Troubleshooting -@cindex troubleshooting - -Gnus works @emph{so} well straight out of the box---I can't imagine any -problems, really. - -Ahem. - -@enumerate - -@item -Make sure your computer is switched on. - -@item -Make sure that you really load the current Gnus version. If you have -been running @sc{gnus}, you need to exit Emacs and start it up again before -Gnus will work. - -@item -Try doing an @kbd{M-x gnus-version}. If you get something that looks -like @c -@samp{Gnus v5.13} @c Adjust ../Makefile.in if you change this line! -@c -you have the right files loaded. Otherwise you have some old @file{.el} -files lying around. Delete these. - -@item -Read the help group (@kbd{G h} in the group buffer) for a -@acronym{FAQ} and a how-to. - -@item -@vindex max-lisp-eval-depth -Gnus works on many recursive structures, and in some extreme (and very -rare) cases Gnus may recurse down ``too deeply'' and Emacs will beep at -you. If this happens to you, set @code{max-lisp-eval-depth} to 500 or -something like that. -@end enumerate - -If all else fails, report the problem as a bug. - -@cindex bugs -@cindex reporting bugs - -@kindex M-x gnus-bug -@findex gnus-bug -If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug} -command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send -me the backtrace. I will fix bugs, but I can only fix them if you send -me a precise description as to how to reproduce the bug. - -You really can never be too detailed in a bug report. Always use the -@kbd{M-x gnus-bug} command when you make bug reports, even if it creates -a 10Kb mail each time you use it, and even if you have sent me your -environment 500 times before. I don't care. I want the full info each -time. - -It is also important to remember that I have no memory whatsoever. If -you send a bug report, and I send you a reply, and then you just send -back ``No, it's not! Moron!'', I will have no idea what you are -insulting me about. Always over-explain everything. It's much easier -for all of us---if I don't have all the information I need, I will just -mail you and ask for more info, and everything takes more time. - -If the problem you're seeing is very visual, and you can't quite explain -it, copy the Emacs window to a file (with @code{xwd}, for instance), put -it somewhere it can be reached, and include the URL of the picture in -the bug report. - -@cindex patches -If you would like to contribute a patch to fix bugs or make -improvements, please produce the patch using @samp{diff -u}. - -@cindex edebug -If you want to debug your problem further before reporting, possibly -in order to solve the problem yourself and send a patch, you can use -edebug. Debugging Lisp code is documented in the Elisp manual -(@pxref{Debugging, , Debugging Lisp Programs, elisp, The GNU Emacs -Lisp Reference Manual}). To get you started with edebug, consider if -you discover some weird behavior when pressing @kbd{c}, the first -step is to do @kbd{C-h k c} and click on the hyperlink (Emacs only) in -the documentation buffer that leads you to the function definition, -then press @kbd{M-x edebug-defun RET} with point inside that function, -return to Gnus and press @kbd{c} to invoke the code. You will be -placed in the lisp buffer and can single step using @kbd{SPC} and -evaluate expressions using @kbd{M-:} or inspect variables using -@kbd{C-h v}, abort execution with @kbd{q}, and resume execution with -@kbd{c} or @kbd{g}. - -@cindex elp -@cindex profile -@cindex slow -Sometimes, a problem do not directly generate an elisp error but -manifests itself by causing Gnus to be very slow. In these cases, you -can use @kbd{M-x toggle-debug-on-quit} and press @kbd{C-g} when things are -slow, and then try to analyze the backtrace (repeating the procedure -helps isolating the real problem areas). - -A fancier approach is to use the elisp profiler, ELP. The profiler is -(or should be) fully documented elsewhere, but to get you started -there are a few steps that need to be followed. First, instrument the -part of Gnus you are interested in for profiling, e.g. @kbd{M-x -elp-instrument-package RET gnus} or @kbd{M-x elp-instrument-package -RET message}. Then perform the operation that is slow and press -@kbd{M-x elp-results}. You will then see which operations that takes -time, and can debug them further. If the entire operation takes much -longer than the time spent in the slowest function in the profiler -output, you probably profiled the wrong part of Gnus. To reset -profiling statistics, use @kbd{M-x elp-reset-all}. @kbd{M-x -elp-restore-all} is supposed to remove profiling, but given the -complexities and dynamic code generation in Gnus, it might not always -work perfectly. - -@cindex gnu.emacs.gnus -@cindex ding mailing list -If you just need help, you are better off asking on -@samp{gnu.emacs.gnus}. I'm not very helpful. You can also ask on -@email{ding@@gnus.org, the ding mailing list}. Write to -@email{ding-request@@gnus.org} to subscribe. - - -@page -@node Gnus Reference Guide -@section Gnus Reference Guide - -It is my hope that other people will figure out smart stuff that Gnus -can do, and that other people will write those smart things as well. To -facilitate that I thought it would be a good idea to describe the inner -workings of Gnus. And some of the not-so-inner workings, while I'm at -it. - -You can never expect the internals of a program not to change, but I -will be defining (in some details) the interface between Gnus and its -back ends (this is written in stone), the format of the score files -(ditto), data structures (some are less likely to change than others) -and general methods of operation. - -@menu -* Gnus Utility Functions:: Common functions and variable to use. -* Back End Interface:: How Gnus communicates with the servers. -* Score File Syntax:: A BNF definition of the score file standard. -* Headers:: How Gnus stores headers internally. -* Ranges:: A handy format for storing mucho numbers. -* Group Info:: The group info format. -* Extended Interactive:: Symbolic prefixes and stuff. -* Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen. -* Various File Formats:: Formats of files that Gnus use. -@end menu - - -@node Gnus Utility Functions -@subsection Gnus Utility Functions -@cindex Gnus utility functions -@cindex utility functions -@cindex functions -@cindex internal variables - -When writing small functions to be run from hooks (and stuff), it's -vital to have access to the Gnus internal functions and variables. -Below is a list of the most common ones. - -@table @code - -@item gnus-newsgroup-name -@vindex gnus-newsgroup-name -This variable holds the name of the current newsgroup. - -@item gnus-find-method-for-group -@findex gnus-find-method-for-group -A function that returns the select method for @var{group}. - -@item gnus-group-real-name -@findex gnus-group-real-name -Takes a full (prefixed) Gnus group name, and returns the unprefixed -name. - -@item gnus-group-prefixed-name -@findex gnus-group-prefixed-name -Takes an unprefixed group name and a select method, and returns the full -(prefixed) Gnus group name. - -@item gnus-get-info -@findex gnus-get-info -Returns the group info list for @var{group} (@pxref{Group Info}). - -@item gnus-group-unread -@findex gnus-group-unread -The number of unread articles in @var{group}, or @code{t} if that is -unknown. - -@item gnus-active -@findex gnus-active -The active entry (i.e., a cons cell containing the lowest and highest -article numbers) for @var{group}. - -@item gnus-set-active -@findex gnus-set-active -Set the active entry for @var{group}. - -@item gnus-add-current-to-buffer-list -@findex gnus-add-current-to-buffer-list -Adds the current buffer to the list of buffers to be killed on Gnus -exit. - -@item gnus-continuum-version -@findex gnus-continuum-version -Takes a Gnus version string as a parameter and returns a floating point -number. Earlier versions will always get a lower number than later -versions. - -@item gnus-group-read-only-p -@findex gnus-group-read-only-p -Says whether @var{group} is read-only or not. - -@item gnus-news-group-p -@findex gnus-news-group-p -Says whether @var{group} came from a news back end. - -@item gnus-ephemeral-group-p -@findex gnus-ephemeral-group-p -Says whether @var{group} is ephemeral or not. - -@item gnus-server-to-method -@findex gnus-server-to-method -Returns the select method corresponding to @var{server}. - -@item gnus-server-equal -@findex gnus-server-equal -Says whether two virtual servers are essentially equal. For instance, -two virtual servers may have server parameters in different order, but -this function will consider them equal. - -@item gnus-group-native-p -@findex gnus-group-native-p -Says whether @var{group} is native or not. - -@item gnus-group-secondary-p -@findex gnus-group-secondary-p -Says whether @var{group} is secondary or not. - -@item gnus-group-foreign-p -@findex gnus-group-foreign-p -Says whether @var{group} is foreign or not. - -@item gnus-group-find-parameter -@findex gnus-group-find-parameter -Returns the parameter list of @var{group} (@pxref{Group Parameters}). -If given a second parameter, returns the value of that parameter for -@var{group}. - -@item gnus-group-set-parameter -@findex gnus-group-set-parameter -Takes three parameters; @var{group}, @var{parameter} and @var{value}. - -@item gnus-narrow-to-body -@findex gnus-narrow-to-body -Narrows the current buffer to the body of the article. - -@item gnus-check-backend-function -@findex gnus-check-backend-function -Takes two parameters, @var{function} and @var{group}. If the back end -@var{group} comes from supports @var{function}, return non-@code{nil}. - -@lisp -(gnus-check-backend-function "request-scan" "nnml:misc") -@result{} t -@end lisp - -@item gnus-read-method -@findex gnus-read-method -Prompts the user for a select method. - -@end table - - -@node Back End Interface -@subsection Back End Interface - -Gnus doesn't know anything about @acronym{NNTP}, spools, mail or virtual -groups. It only knows how to talk to @dfn{virtual servers}. A virtual -server is a @dfn{back end} and some @dfn{back end variables}. As examples -of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As -examples of the latter we have @code{nntp-port-number} and -@code{nnmbox-directory}. - -When Gnus asks for information from a back end---say @code{nntp}---on -something, it will normally include a virtual server name in the -function parameters. (If not, the back end should use the ``current'' -virtual server.) For instance, @code{nntp-request-list} takes a virtual -server as its only (optional) parameter. If this virtual server hasn't -been opened, the function should fail. - -Note that a virtual server name has no relation to some physical server -name. Take this example: - -@lisp -(nntp "odd-one" - (nntp-address "ifi.uio.no") - (nntp-port-number 4324)) -@end lisp - -Here the virtual server name is @samp{odd-one} while the name of -the physical server is @samp{ifi.uio.no}. - -The back ends should be able to switch between several virtual servers. -The standard back ends implement this by keeping an alist of virtual -server environments that they pull down/push up when needed. - -There are two groups of interface functions: @dfn{required functions}, -which must be present, and @dfn{optional functions}, which Gnus will -always check for presence before attempting to call 'em. - -All these functions are expected to return data in the buffer -@code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat -unfortunately named, but we'll have to live with it. When I talk about -@dfn{resulting data}, I always refer to the data in that buffer. When I -talk about @dfn{return value}, I talk about the function value returned by -the function call. Functions that fail should return @code{nil} as the -return value. - -Some back ends could be said to be @dfn{server-forming} back ends, and -some might be said not to be. The latter are back ends that generally -only operate on one group at a time, and have no concept of ``server'' ----they have a group, and they deliver info on that group and nothing -more. - -Gnus identifies each message by way of group name and article number. A -few remarks about these article numbers might be useful. First of all, -the numbers are positive integers. Secondly, it is normally not -possible for later articles to ``re-use'' older article numbers without -confusing Gnus. That is, if a group has ever contained a message -numbered 42, then no other message may get that number, or Gnus will get -mightily confused.@footnote{See the function -@code{nnchoke-request-update-info}, @ref{Optional Back End Functions}.} -Third, article numbers must be assigned in order of arrival in the -group; this is not necessarily the same as the date of the message. - -The previous paragraph already mentions all the ``hard'' restrictions that -article numbers must fulfill. But it seems that it might be useful to -assign @emph{consecutive} article numbers, for Gnus gets quite confused -if there are holes in the article numbering sequence. However, due to -the ``no-reuse'' restriction, holes cannot be avoided altogether. It's -also useful for the article numbers to start at 1 to avoid running out -of numbers as long as possible. - -Note that by convention, back ends are named @code{nnsomething}, but -Gnus also comes with some @code{nnnotbackends}, such as -@file{nnheader.el}, @file{nnmail.el} and @file{nnoo.el}. - -In the examples and definitions I will refer to the imaginary back end -@code{nnchoke}. - -@cindex @code{nnchoke} - -@menu -* Required Back End Functions:: Functions that must be implemented. -* Optional Back End Functions:: Functions that need not be implemented. -* Error Messaging:: How to get messages and report errors. -* Writing New Back Ends:: Extending old back ends. -* Hooking New Back Ends Into Gnus:: What has to be done on the Gnus end. -* Mail-like Back Ends:: Some tips on mail back ends. -@end menu - - -@node Required Back End Functions -@subsubsection Required Back End Functions - -@table @code - -@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD) - -@var{articles} is either a range of article numbers or a list of -@code{Message-ID}s. Current back ends do not fully support either---only -sequences (lists) of article numbers, and most back ends do not support -retrieval of @code{Message-ID}s. But they should try for both. - -The result data should either be HEADs or @acronym{NOV} lines, and the result -value should either be @code{headers} or @code{nov} to reflect this. -This might later be expanded to @code{various}, which will be a mixture -of HEADs and @acronym{NOV} lines, but this is currently not supported by Gnus. - -If @var{fetch-old} is non-@code{nil} it says to try fetching ``extra -headers'', in some meaning of the word. This is generally done by -fetching (at most) @var{fetch-old} extra headers less than the smallest -article number in @code{articles}, and filling the gaps as well. The -presence of this parameter can be ignored if the back end finds it -cumbersome to follow the request. If this is non-@code{nil} and not a -number, do maximum fetches. - -Here's an example HEAD: - -@example -221 1056 Article retrieved. -Path: ifi.uio.no!sturles -From: sturles@@ifi.uio.no (Sturle Sunde) -Newsgroups: ifi.discussion -Subject: Re: Something very droll -Date: 27 Oct 1994 14:02:57 +0100 -Organization: Dept. of Informatics, University of Oslo, Norway -Lines: 26 -Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no> -References: <38jdmq$4qu@@visbur.ifi.uio.no> -NNTP-Posting-Host: holmenkollen.ifi.uio.no -. -@end example - -So a @code{headers} return value would imply that there's a number of -these in the data buffer. - -Here's a BNF definition of such a buffer: - -@example -headers = *head -head = error / valid-head -error-message = [ "4" / "5" ] 2number " " eol -valid-head = valid-message *header "." eol -valid-message = "221 " " Article retrieved." eol -header = eol -@end example - -@cindex BNF -(The version of BNF used here is the one used in RFC822.) - -If the return value is @code{nov}, the data buffer should contain -@dfn{network overview database} lines. These are basically fields -separated by tabs. - -@example -nov-buffer = *nov-line -nov-line = field 7*8[ field ] eol -field = -@end example - -For a closer look at what should be in those fields, -@pxref{Headers}. - - -@item (nnchoke-open-server SERVER &optional DEFINITIONS) - -@var{server} is here the virtual server name. @var{definitions} is a -list of @code{(VARIABLE VALUE)} pairs that define this virtual server. - -If the server can't be opened, no error should be signaled. The back end -may then choose to refuse further attempts at connecting to this -server. In fact, it should do so. - -If the server is opened already, this function should return a -non-@code{nil} value. There should be no data returned. - - -@item (nnchoke-close-server &optional SERVER) - -Close connection to @var{server} and free all resources connected -to it. Return @code{nil} if the server couldn't be closed for some -reason. - -There should be no data returned. - - -@item (nnchoke-request-close) - -Close connection to all servers and free all resources that the back end -have reserved. All buffers that have been created by that back end -should be killed. (Not the @code{nntp-server-buffer}, though.) This -function is generally only called when Gnus is shutting down. - -There should be no data returned. - - -@item (nnchoke-server-opened &optional SERVER) - -If @var{server} is the current virtual server, and the connection to the -physical server is alive, then this function should return a -non-@code{nil} value. This function should under no circumstances -attempt to reconnect to a server we have lost connection to. - -There should be no data returned. - - -@item (nnchoke-status-message &optional SERVER) - -This function should return the last error message from @var{server}. - -There should be no data returned. - - -@item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER) - -The result data from this function should be the article specified by -@var{article}. This might either be a @code{Message-ID} or a number. -It is optional whether to implement retrieval by @code{Message-ID}, but -it would be nice if that were possible. - -If @var{to-buffer} is non-@code{nil}, the result data should be returned -in this buffer instead of the normal data buffer. This is to make it -possible to avoid copying large amounts of data from one buffer to -another, while Gnus mainly requests articles to be inserted directly -into its article buffer. - -If it is at all possible, this function should return a cons cell where -the @code{car} is the group name the article was fetched from, and the @code{cdr} is -the article number. This will enable Gnus to find out what the real -group and article numbers are when fetching articles by -@code{Message-ID}. If this isn't possible, @code{t} should be returned -on successful article retrieval. - - -@item (nnchoke-request-group GROUP &optional SERVER FAST INFO) - -Get data on @var{group}. This function also has the side effect of -making @var{group} the current group. - -If @var{fast}, don't bother to return useful data, just make @var{group} -the current group. - -If @var{info}, it allows the backend to update the group info -structure. - -Here's an example of some result data and a definition of the same: - -@example -211 56 1000 1059 ifi.discussion -@end example - -The first number is the status, which should be 211. Next is the -total number of articles in the group, the lowest article number, the -highest article number, and finally the group name. Note that the total -number of articles may be less than one might think while just -considering the highest and lowest article numbers, but some articles -may have been canceled. Gnus just discards the total-number, so -whether one should take the bother to generate it properly (if that is a -problem) is left as an exercise to the reader. If the group contains no -articles, the lowest article number should be reported as 1 and the -highest as 0. - -@example -group-status = [ error / info ] eol -error = [ "4" / "5" ] 2 " " -info = "211 " 3* [ " " ] -@end example - - -@item (nnchoke-close-group GROUP &optional SERVER) - -Close @var{group} and free any resources connected to it. This will be -a no-op on most back ends. - -There should be no data returned. - - -@item (nnchoke-request-list &optional SERVER) - -Return a list of all groups available on @var{server}. And that means -@emph{all}. - -Here's an example from a server that only carries two groups: - -@example -ifi.test 0000002200 0000002000 y -ifi.discussion 3324 3300 n -@end example - -On each line we have a group name, then the highest article number in -that group, the lowest article number, and finally a flag. If the group -contains no articles, the lowest article number should be reported as 1 -and the highest as 0. - -@example -active-file = *active-line -active-line = name " " " " " " flags eol -name = -flags = "n" / "y" / "m" / "x" / "j" / "=" name -@end example - -The flag says whether the group is read-only (@samp{n}), is moderated -(@samp{m}), is dead (@samp{x}), is aliased to some other group -(@samp{=other-group}) or none of the above (@samp{y}). - - -@item (nnchoke-request-post &optional SERVER) - -This function should post the current buffer. It might return whether -the posting was successful or not, but that's not required. If, for -instance, the posting is done asynchronously, it has generally not been -completed by the time this function concludes. In that case, this -function should set up some kind of sentinel to beep the user loud and -clear if the posting could not be completed. - -There should be no result data from this function. - -@end table - - -@node Optional Back End Functions -@subsubsection Optional Back End Functions - -@table @code - -@item (nnchoke-retrieve-groups GROUPS &optional SERVER) - -@var{groups} is a list of groups, and this function should request data -on all those groups. How it does it is of no concern to Gnus, but it -should attempt to do this in a speedy fashion. - -The return value of this function can be either @code{active} or -@code{group}, which says what the format of the result data is. The -former is in the same format as the data from -@code{nnchoke-request-list}, while the latter is a buffer full of lines -in the same format as @code{nnchoke-request-group} gives. - -@example -group-buffer = *active-line / *group-status -@end example - - -@item (nnchoke-request-update-info GROUP INFO &optional SERVER) - -A Gnus group info (@pxref{Group Info}) is handed to the back end for -alterations. This comes in handy if the back end really carries all -the information (as is the case with virtual and imap groups). This -function should destructively alter the info to suit its needs, and -should return a non-@code{nil} value (exceptionally, -@code{nntp-request-update-info} always returns @code{nil} not to waste -the network resources). - -There should be no result data from this function. - - -@item (nnchoke-request-type GROUP &optional ARTICLE) - -When the user issues commands for ``sending news'' (@kbd{F} in the -summary buffer, for instance), Gnus has to know whether the article the -user is following up on is news or mail. This function should return -@code{news} if @var{article} in @var{group} is news, @code{mail} if it -is mail and @code{unknown} if the type can't be decided. (The -@var{article} parameter is necessary in @code{nnvirtual} groups which -might very well combine mail groups and news groups.) Both @var{group} -and @var{article} may be @code{nil}. - -There should be no result data from this function. - - -@item (nnchoke-request-set-mark GROUP ACTION &optional SERVER) - -Set/remove/add marks on articles. Normally Gnus handles the article -marks (such as read, ticked, expired etc) internally, and store them in -@file{~/.newsrc.eld}. Some back ends (such as @acronym{IMAP}) however carry -all information about the articles on the server, so Gnus need to -propagate the mark information to the server. - -@var{action} is a list of mark setting requests, having this format: - -@example -(RANGE ACTION MARK) -@end example - -@var{range} is a range of articles you wish to update marks on. -@var{action} is @code{add} or @code{del}, used to add marks or remove -marks (preserving all marks not mentioned). @var{mark} is a list of -marks; where each mark is a symbol. Currently used marks are -@code{read}, @code{tick}, @code{reply}, @code{expire}, @code{killed}, -@code{dormant}, @code{save}, @code{download}, @code{unsend}, and -@code{forward}, but your back end should, if possible, not limit -itself to these. - -Given contradictory actions, the last action in the list should be the -effective one. That is, if your action contains a request to add the -@code{tick} mark on article 1 and, later in the list, a request to -remove the mark on the same article, the mark should in fact be removed. - -An example action list: - -@example -(((5 12 30) 'del '(tick)) - ((10 . 90) 'add '(read expire)) - ((92 94) 'del '(read))) -@end example - -The function should return a range of articles it wasn't able to set the -mark on (currently not used for anything). - -There should be no result data from this function. - -@item (nnchoke-request-update-mark GROUP ARTICLE MARK) - -If the user tries to set a mark that the back end doesn't like, this -function may change the mark. Gnus will use whatever this function -returns as the mark for @var{article} instead of the original -@var{mark}. If the back end doesn't care, it must return the original -@var{mark}, and not @code{nil} or any other type of garbage. - -The only use for this I can see is what @code{nnvirtual} does with -it---if a component group is auto-expirable, marking an article as read -in the virtual group should result in the article being marked as -expirable. - -There should be no result data from this function. - - -@item (nnchoke-request-scan &optional GROUP SERVER) - -This function may be called at any time (by Gnus or anything else) to -request that the back end check for incoming articles, in one way or -another. A mail back end will typically read the spool file or query -the @acronym{POP} server when this function is invoked. The -@var{group} doesn't have to be heeded---if the back end decides that -it is too much work just scanning for a single group, it may do a -total scan of all groups. It would be nice, however, to keep things -local if that's practical. - -There should be no result data from this function. - - -@item (nnchoke-request-group-description GROUP &optional SERVER) - -The result data from this function should be a description of -@var{group}. - -@example -description-line = name description eol -name = -description = -@end example - -@item (nnchoke-request-list-newsgroups &optional SERVER) - -The result data from this function should be the description of all -groups available on the server. - -@example -description-buffer = *description-line -@end example - - -@item (nnchoke-request-newgroups DATE &optional SERVER) - -The result data from this function should be all groups that were -created after @samp{date}, which is in normal human-readable date format -(i.e., the date format used in mail and news headers, and returned by -the function @code{message-make-date} by default). The data should be -in the active buffer format. - -It is okay for this function to return ``too many'' groups; some back ends -might find it cheaper to return the full list of groups, rather than -just the new groups. But don't do this for back ends with many groups. -Normally, if the user creates the groups herself, there won't be too -many groups, so @code{nnml} and the like are probably safe. But for -back ends like @code{nntp}, where the groups have been created by the -server, it is quite likely that there can be many groups. - - -@item (nnchoke-request-create-group GROUP &optional SERVER) - -This function should create an empty group with name @var{group}. - -There should be no return data. - - -@item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE) - -This function should run the expiry process on all articles in the -@var{articles} range (which is currently a simple list of article -numbers.) It is left up to the back end to decide how old articles -should be before they are removed by this function. If @var{force} is -non-@code{nil}, all @var{articles} should be deleted, no matter how new -they are. - -This function should return a list of articles that it did not/was not -able to delete. - -There should be no result data returned. - - -@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM &optional LAST) - -This function should move @var{article} (which is a number) from -@var{group} by calling @var{accept-form}. - -This function should ready the article in question for moving by -removing any header lines it has added to the article, and generally -should ``tidy up'' the article. Then it should @code{eval} -@var{accept-form} in the buffer where the ``tidy'' article is. This -will do the actual copying. If this @code{eval} returns a -non-@code{nil} value, the article should be removed. - -If @var{last} is @code{nil}, that means that there is a high likelihood -that there will be more requests issued shortly, so that allows some -optimizations. - -The function should return a cons where the @code{car} is the group name and -the @code{cdr} is the article number that the article was entered as. - -There should be no data returned. - - -@item (nnchoke-request-accept-article GROUP &optional SERVER LAST) - -This function takes the current buffer and inserts it into @var{group}. -If @var{last} in @code{nil}, that means that there will be more calls to -this function in short order. - -The function should return a cons where the @code{car} is the group name and -the @code{cdr} is the article number that the article was entered as. - -The group should exist before the back end is asked to accept the -article for that group. - -There should be no data returned. - - -@item (nnchoke-request-replace-article ARTICLE GROUP BUFFER) - -This function should remove @var{article} (which is a number) from -@var{group} and insert @var{buffer} there instead. - -There should be no data returned. - - -@item (nnchoke-request-delete-group GROUP FORCE &optional SERVER) - -This function should delete @var{group}. If @var{force}, it should -really delete all the articles in the group, and then delete the group -itself. (If there is such a thing as ``the group itself''.) - -There should be no data returned. - - -@item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER) - -This function should rename @var{group} into @var{new-name}. All -articles in @var{group} should move to @var{new-name}. - -There should be no data returned. - -@end table - - -@node Error Messaging -@subsubsection Error Messaging - -@findex nnheader-report -@findex nnheader-get-report -The back ends should use the function @code{nnheader-report} to report -error conditions---they should not raise errors when they aren't able to -perform a request. The first argument to this function is the back end -symbol, and the rest are interpreted as arguments to @code{format} if -there are multiple of them, or just a string if there is one of them. -This function must always returns @code{nil}. - -@lisp -(nnheader-report 'nnchoke "You did something totally bogus") - -(nnheader-report 'nnchoke "Could not request group %s" group) -@end lisp - -Gnus, in turn, will call @code{nnheader-get-report} when it gets a -@code{nil} back from a server, and this function returns the most -recently reported message for the back end in question. This function -takes one argument---the server symbol. - -Internally, these functions access @var{back-end}@code{-status-string}, -so the @code{nnchoke} back end will have its error message stored in -@code{nnchoke-status-string}. - - -@node Writing New Back Ends -@subsubsection Writing New Back Ends - -Many back ends are quite similar. @code{nnml} is just like -@code{nnspool}, but it allows you to edit the articles on the server. -@code{nnmh} is just like @code{nnml}, but it doesn't use an active file, -and it doesn't maintain overview databases. @code{nndir} is just like -@code{nnml}, but it has no concept of ``groups'', and it doesn't allow -editing articles. - -It would make sense if it were possible to ``inherit'' functions from -back ends when writing new back ends. And, indeed, you can do that if you -want to. (You don't have to if you don't want to, of course.) - -All the back ends declare their public variables and functions by using a -package called @code{nnoo}. - -To inherit functions from other back ends (and allow other back ends to -inherit functions from the current back end), you should use the -following macros: - -@table @code - -@item nnoo-declare -This macro declares the first parameter to be a child of the subsequent -parameters. For instance: - -@lisp -(nnoo-declare nndir - nnml nnmh) -@end lisp - -@code{nndir} has declared here that it intends to inherit functions from -both @code{nnml} and @code{nnmh}. - -@item defvoo -This macro is equivalent to @code{defvar}, but registers the variable as -a public server variable. Most state-oriented variables should be -declared with @code{defvoo} instead of @code{defvar}. - -In addition to the normal @code{defvar} parameters, it takes a list of -variables in the parent back ends to map the variable to when executing -a function in those back ends. - -@lisp -(defvoo nndir-directory nil - "Where nndir will look for groups." - nnml-current-directory nnmh-current-directory) -@end lisp - -This means that @code{nnml-current-directory} will be set to -@code{nndir-directory} when an @code{nnml} function is called on behalf -of @code{nndir}. (The same with @code{nnmh}.) - -@item nnoo-define-basics -This macro defines some common functions that almost all back ends should -have. - -@lisp -(nnoo-define-basics nndir) -@end lisp - -@item deffoo -This macro is just like @code{defun} and takes the same parameters. In -addition to doing the normal @code{defun} things, it registers the -function as being public so that other back ends can inherit it. - -@item nnoo-map-functions -This macro allows mapping of functions from the current back end to -functions from the parent back ends. - -@lisp -(nnoo-map-functions nndir - (nnml-retrieve-headers 0 nndir-current-group 0 0) - (nnmh-request-article 0 nndir-current-group 0 0)) -@end lisp - -This means that when @code{nndir-retrieve-headers} is called, the first, -third, and fourth parameters will be passed on to -@code{nnml-retrieve-headers}, while the second parameter is set to the -value of @code{nndir-current-group}. - -@item nnoo-import -This macro allows importing functions from back ends. It should be the -last thing in the source file, since it will only define functions that -haven't already been defined. - -@lisp -(nnoo-import nndir - (nnmh - nnmh-request-list - nnmh-request-newgroups) - (nnml)) -@end lisp - -This means that calls to @code{nndir-request-list} should just be passed -on to @code{nnmh-request-list}, while all public functions from -@code{nnml} that haven't been defined in @code{nndir} yet should be -defined now. - -@end table - -Below is a slightly shortened version of the @code{nndir} back end. - -@lisp -;;; @r{nndir.el --- single directory newsgroup access for Gnus} -;; @r{Copyright (C) 1995,1996 Free Software Foundation, Inc.} - -;;; @r{Code:} - -(require 'nnheader) -(require 'nnmh) -(require 'nnml) -(require 'nnoo) -(eval-when-compile (require 'cl)) - -(nnoo-declare nndir - nnml nnmh) - -(defvoo nndir-directory nil - "Where nndir will look for groups." - nnml-current-directory nnmh-current-directory) - -(defvoo nndir-nov-is-evil nil - "*Non-nil means that nndir will never retrieve NOV headers." - nnml-nov-is-evil) - -(defvoo nndir-current-group "" - nil - nnml-current-group nnmh-current-group) -(defvoo nndir-top-directory nil nil nnml-directory nnmh-directory) -(defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail) - -(defvoo nndir-status-string "" nil nnmh-status-string) -(defconst nndir-version "nndir 1.0") - -;;; @r{Interface functions.} - -(nnoo-define-basics nndir) - -(deffoo nndir-open-server (server &optional defs) - (setq nndir-directory - (or (cadr (assq 'nndir-directory defs)) - server)) - (unless (assq 'nndir-directory defs) - (push `(nndir-directory ,server) defs)) - (push `(nndir-current-group - ,(file-name-nondirectory - (directory-file-name nndir-directory))) - defs) - (push `(nndir-top-directory - ,(file-name-directory (directory-file-name nndir-directory))) - defs) - (nnoo-change-server 'nndir server defs)) - -(nnoo-map-functions nndir - (nnml-retrieve-headers 0 nndir-current-group 0 0) - (nnmh-request-article 0 nndir-current-group 0 0) - (nnmh-request-group nndir-current-group 0 0) - (nnmh-close-group nndir-current-group 0)) - -(nnoo-import nndir - (nnmh - nnmh-status-message - nnmh-request-list - nnmh-request-newgroups)) - -(provide 'nndir) -@end lisp - - -@node Hooking New Back Ends Into Gnus -@subsubsection Hooking New Back Ends Into Gnus - -@vindex gnus-valid-select-methods -@findex gnus-declare-backend -Having Gnus start using your new back end is rather easy---you just -declare it with the @code{gnus-declare-backend} functions. This will -enter the back end into the @code{gnus-valid-select-methods} variable. - -@code{gnus-declare-backend} takes two parameters---the back end name and -an arbitrary number of @dfn{abilities}. - -Here's an example: - -@lisp -(gnus-declare-backend "nnchoke" 'mail 'respool 'address) -@end lisp - -The above line would then go in the @file{nnchoke.el} file. - -The abilities can be: - -@table @code -@item mail -This is a mailish back end---followups should (probably) go via mail. -@item post -This is a newsish back end---followups should (probably) go via news. -@item post-mail -This back end supports both mail and news. -@item none -This is neither a post nor mail back end---it's something completely -different. -@item respool -It supports respooling---or rather, it is able to modify its source -articles and groups. -@item address -The name of the server should be in the virtual server name. This is -true for almost all back ends. -@item prompt-address -The user should be prompted for an address when doing commands like -@kbd{B} in the group buffer. This is true for back ends like -@code{nntp}, but not @code{nnmbox}, for instance. -@end table - - -@node Mail-like Back Ends -@subsubsection Mail-like Back Ends - -One of the things that separate the mail back ends from the rest of the -back ends is the heavy dependence by most of the mail back ends on -common functions in @file{nnmail.el}. For instance, here's the -definition of @code{nnml-request-scan}: - -@lisp -(deffoo nnml-request-scan (&optional group server) - (setq nnml-article-file-alist nil) - (nnmail-get-new-mail 'nnml 'nnml-save-nov nnml-directory group)) -@end lisp - -It simply calls @code{nnmail-get-new-mail} with a few parameters, -and @code{nnmail} takes care of all the moving and splitting of the -mail. - -This function takes four parameters. - -@table @var -@item method -This should be a symbol to designate which back end is responsible for -the call. - -@item exit-function -This function should be called after the splitting has been performed. - -@item temp-directory -Where the temporary files should be stored. - -@item group -This optional argument should be a group name if the splitting is to be -performed for one group only. -@end table - -@code{nnmail-get-new-mail} will call @var{back-end}@code{-save-mail} to -save each article. @var{back-end}@code{-active-number} will be called to -find the article number assigned to this article. - -The function also uses the following variables: -@var{back-end}@code{-get-new-mail} (to see whether to get new mail for -this back end); and @var{back-end}@code{-group-alist} and -@var{back-end}@code{-active-file} to generate the new active file. -@var{back-end}@code{-group-alist} should be a group-active alist, like -this: - -@example -(("a-group" (1 . 10)) - ("some-group" (34 . 39))) -@end example - - -@node Score File Syntax -@subsection Score File Syntax - -Score files are meant to be easily parsable, but yet extremely -malleable. It was decided that something that had the same read syntax -as an Emacs Lisp list would fit that spec. - -Here's a typical score file: - -@lisp -(("summary" - ("win95" -10000 nil s) - ("Gnus")) - ("from" - ("Lars" -1000)) - (mark -100)) -@end lisp - -BNF definition of a score file: - -@example -score-file = "" / "(" *element ")" -element = rule / atom -rule = string-rule / number-rule / date-rule -string-rule = "(" quote string-header quote space *string-match ")" -number-rule = "(" quote number-header quote space *number-match ")" -date-rule = "(" quote date-header quote space *date-match ")" -quote = -string-header = "subject" / "from" / "references" / "message-id" / - "xref" / "body" / "head" / "all" / "followup" -number-header = "lines" / "chars" -date-header = "date" -string-match = "(" quote quote [ "" / [ space score [ "" / - space date [ "" / [ space string-match-t ] ] ] ] ] ")" -score = "nil" / -date = "nil" / -string-match-t = "nil" / "s" / "substring" / "S" / "Substring" / - "r" / "regex" / "R" / "Regex" / - "e" / "exact" / "E" / "Exact" / - "f" / "fuzzy" / "F" / "Fuzzy" -number-match = "(" [ "" / [ space score [ "" / - space date [ "" / [ space number-match-t ] ] ] ] ] ")" -number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<=" -date-match = "(" quote quote [ "" / [ space score [ "" / - space date [ "" / [ space date-match-t ] ] ] ] ")" -date-match-t = "nil" / "at" / "before" / "after" -atom = "(" [ required-atom / optional-atom ] ")" -required-atom = mark / expunge / mark-and-expunge / files / - exclude-files / read-only / touched -optional-atom = adapt / local / eval -mark = "mark" space nil-or-number -nil-or-number = "nil" / -expunge = "expunge" space nil-or-number -mark-and-expunge = "mark-and-expunge" space nil-or-number -files = "files" *[ space ] -exclude-files = "exclude-files" *[ space ] -read-only = "read-only" [ space "nil" / space "t" ] -adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ] -adapt-rule = "(" *[ *[ "(" ")" ] ")" -local = "local" *[ space "(" space
")" ] -eval = "eval" space -space = *[ " " / / ] -@end example - -Any unrecognized elements in a score file should be ignored, but not -discarded. - -As you can see, white space is needed, but the type and amount of white -space is irrelevant. This means that formatting of the score file is -left up to the programmer---if it's simpler to just spew it all out on -one looong line, then that's ok. - -The meaning of the various atoms are explained elsewhere in this -manual (@pxref{Score File Format}). - - -@node Headers -@subsection Headers - -Internally Gnus uses a format for storing article headers that -corresponds to the @acronym{NOV} format in a mysterious fashion. One could -almost suspect that the author looked at the @acronym{NOV} specification and -just shamelessly @emph{stole} the entire thing, and one would be right. - -@dfn{Header} is a severely overloaded term. ``Header'' is used in -RFC 1036 to talk about lines in the head of an article (e.g., -@code{From}). It is used by many people as a synonym for -``head''---``the header and the body''. (That should be avoided, in my -opinion.) And Gnus uses a format internally that it calls ``header'', -which is what I'm talking about here. This is a 9-element vector, -basically, with each header (ouch) having one slot. - -These slots are, in order: @code{number}, @code{subject}, @code{from}, -@code{date}, @code{id}, @code{references}, @code{chars}, @code{lines}, -@code{xref}, and @code{extra}. There are macros for accessing and -setting these slots---they all have predictable names beginning with -@code{mail-header-} and @code{mail-header-set-}, respectively. - -All these slots contain strings, except the @code{extra} slot, which -contains an alist of header/value pairs (@pxref{To From Newsgroups}). - - -@node Ranges -@subsection Ranges - -@sc{gnus} introduced a concept that I found so useful that I've started -using it a lot and have elaborated on it greatly. - -The question is simple: If you have a large amount of objects that are -identified by numbers (say, articles, to take a @emph{wild} example) -that you want to qualify as being ``included'', a normal sequence isn't -very useful. (A 200,000 length sequence is a bit long-winded.) - -The solution is as simple as the question: You just collapse the -sequence. - -@example -(1 2 3 4 5 6 10 11 12) -@end example - -is transformed into - -@example -((1 . 6) (10 . 12)) -@end example - -To avoid having those nasty @samp{(13 . 13)} elements to denote a -lonesome object, a @samp{13} is a valid element: - -@example -((1 . 6) 7 (10 . 12)) -@end example - -This means that comparing two ranges to find out whether they are equal -is slightly tricky: - -@example -((1 . 5) 7 8 (10 . 12)) -@end example - -and - -@example -((1 . 5) (7 . 8) (10 . 12)) -@end example - -are equal. In fact, any non-descending list is a range: - -@example -(1 2 3 4 5) -@end example - -is a perfectly valid range, although a pretty long-winded one. This is -also valid: - -@example -(1 . 5) -@end example - -and is equal to the previous range. - -Here's a BNF definition of ranges. Of course, one must remember the -semantic requirement that the numbers are non-descending. (Any number -of repetition of the same number is allowed, but apt to disappear in -range handling.) - -@example -range = simple-range / normal-range -simple-range = "(" number " . " number ")" -normal-range = "(" start-contents ")" -contents = "" / simple-range *[ " " contents ] / - number *[ " " contents ] -@end example - -Gnus currently uses ranges to keep track of read articles and article -marks. I plan on implementing a number of range operators in C if The -Powers That Be are willing to let me. (I haven't asked yet, because I -need to do some more thinking on what operators I need to make life -totally range-based without ever having to convert back to normal -sequences.) - - -@node Group Info -@subsection Group Info - -Gnus stores all permanent info on groups in a @dfn{group info} list. -This list is from three to six elements (or more) long and exhaustively -describes the group. - -Here are two example group infos; one is a very simple group while the -second is a more complex one: - -@example -("no.group" 5 ((1 . 54324))) - -("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55)) - ((tick (15 . 19)) (replied 3 6 (19 . 3))) - (nnml "") - ((auto-expire . t) (to-address . "ding@@gnus.org"))) -@end example - -The first element is the @dfn{group name}---as Gnus knows the group, -anyway. The second element is the @dfn{subscription level}, which -normally is a small integer. (It can also be the @dfn{rank}, which is a -cons cell where the @code{car} is the level and the @code{cdr} is the -score.) The third element is a list of ranges of read articles. The -fourth element is a list of lists of article marks of various kinds. -The fifth element is the select method (or virtual server, if you like). -The sixth element is a list of @dfn{group parameters}, which is what -this section is about. - -Any of the last three elements may be missing if they are not required. -In fact, the vast majority of groups will normally only have the first -three elements, which saves quite a lot of cons cells. - -Here's a BNF definition of the group info format: - -@example -info = "(" group space ralevel space read - [ "" / [ space marks-list [ "" / [ space method [ "" / - space parameters ] ] ] ] ] ")" -group = quote quote -ralevel = rank / level -level = -rank = "(" level "." score ")" -score = -read = range -marks-lists = nil / "(" *marks ")" -marks = "(" range ")" -method = "(" *elisp-forms ")" -parameters = "(" *elisp-forms ")" -@end example - -Actually that @samp{marks} rule is a fib. A @samp{marks} is a -@samp{} consed on to a @samp{range}, but that's a bitch to say -in pseudo-BNF. - -If you have a Gnus info and want to access the elements, Gnus offers a -series of macros for getting/setting these elements. - -@table @code -@item gnus-info-group -@itemx gnus-info-set-group -@findex gnus-info-group -@findex gnus-info-set-group -Get/set the group name. - -@item gnus-info-rank -@itemx gnus-info-set-rank -@findex gnus-info-rank -@findex gnus-info-set-rank -Get/set the group rank (@pxref{Group Score}). - -@item gnus-info-level -@itemx gnus-info-set-level -@findex gnus-info-level -@findex gnus-info-set-level -Get/set the group level. - -@item gnus-info-score -@itemx gnus-info-set-score -@findex gnus-info-score -@findex gnus-info-set-score -Get/set the group score (@pxref{Group Score}). - -@item gnus-info-read -@itemx gnus-info-set-read -@findex gnus-info-read -@findex gnus-info-set-read -Get/set the ranges of read articles. - -@item gnus-info-marks -@itemx gnus-info-set-marks -@findex gnus-info-marks -@findex gnus-info-set-marks -Get/set the lists of ranges of marked articles. - -@item gnus-info-method -@itemx gnus-info-set-method -@findex gnus-info-method -@findex gnus-info-set-method -Get/set the group select method. - -@item gnus-info-params -@itemx gnus-info-set-params -@findex gnus-info-params -@findex gnus-info-set-params -Get/set the group parameters. -@end table - -All the getter functions take one parameter---the info list. The setter -functions take two parameters---the info list and the new value. - -The last three elements in the group info aren't mandatory, so it may be -necessary to extend the group info before setting the element. If this -is necessary, you can just pass on a non-@code{nil} third parameter to -the three final setter functions to have this happen automatically. - - -@node Extended Interactive -@subsection Extended Interactive -@cindex interactive -@findex gnus-interactive - -Gnus extends the standard Emacs @code{interactive} specification -slightly to allow easy use of the symbolic prefix (@pxref{Symbolic -Prefixes}). Here's an example of how this is used: - -@lisp -(defun gnus-summary-increase-score (&optional score symp) - (interactive (gnus-interactive "P\ny")) - ... - ) -@end lisp - -The best thing to do would have been to implement -@code{gnus-interactive} as a macro which would have returned an -@code{interactive} form, but this isn't possible since Emacs checks -whether a function is interactive or not by simply doing an @code{assq} -on the lambda form. So, instead we have @code{gnus-interactive} -function that takes a string and returns values that are usable to -@code{interactive}. - -This function accepts (almost) all normal @code{interactive} specs, but -adds a few more. - -@table @samp -@item y -@vindex gnus-current-prefix-symbol -The current symbolic prefix---the @code{gnus-current-prefix-symbol} -variable. - -@item Y -@vindex gnus-current-prefix-symbols -A list of the current symbolic prefixes---the -@code{gnus-current-prefix-symbol} variable. - -@item A -The current article number---the @code{gnus-summary-article-number} -function. - -@item H -The current article header---the @code{gnus-summary-article-header} -function. - -@item g -The current group name---the @code{gnus-group-group-name} -function. - -@end table - - -@node Emacs/XEmacs Code -@subsection Emacs/XEmacs Code -@cindex XEmacs -@cindex Emacsen - -While Gnus runs under Emacs, XEmacs and Mule, I decided that one of the -platforms must be the primary one. I chose Emacs. Not because I don't -like XEmacs or Mule, but because it comes first alphabetically. - -This means that Gnus will byte-compile under Emacs with nary a warning, -while XEmacs will pump out gigabytes of warnings while byte-compiling. -As I use byte-compilation warnings to help me root out trivial errors in -Gnus, that's very useful. - -I've also consistently used Emacs function interfaces, but have used -Gnusey aliases for the functions. To take an example: Emacs defines a -@code{run-at-time} function while XEmacs defines a @code{start-itimer} -function. I then define a function called @code{gnus-run-at-time} that -takes the same parameters as the Emacs @code{run-at-time}. When running -Gnus under Emacs, the former function is just an alias for the latter. -However, when running under XEmacs, the former is an alias for the -following function: - -@lisp -(defun gnus-xmas-run-at-time (time repeat function &rest args) - (start-itimer - "gnus-run-at-time" - `(lambda () - (,function ,@@args)) - time repeat)) -@end lisp - -This sort of thing has been done for bunches of functions. Gnus does -not redefine any native Emacs functions while running under XEmacs---it -does this @code{defalias} thing with Gnus equivalents instead. Cleaner -all over. - -In the cases where the XEmacs function interface was obviously cleaner, -I used it instead. For example @code{gnus-region-active-p} is an alias -for @code{region-active-p} in XEmacs, whereas in Emacs it is a function. - -Of course, I could have chosen XEmacs as my native platform and done -mapping functions the other way around. But I didn't. The performance -hit these indirections impose on Gnus under XEmacs should be slight. - - -@node Various File Formats -@subsection Various File Formats - -@menu -* Active File Format:: Information on articles and groups available. -* Newsgroups File Format:: Group descriptions. -@end menu - - -@node Active File Format -@subsubsection Active File Format - -The active file lists all groups available on the server in -question. It also lists the highest and lowest current article numbers -in each group. - -Here's an excerpt from a typical active file: - -@example -soc.motss 296030 293865 y -alt.binaries.pictures.fractals 3922 3913 n -comp.sources.unix 1605 1593 m -comp.binaries.ibm.pc 5097 5089 y -no.general 1000 900 y -@end example - -Here's a pseudo-BNF definition of this file: - -@example -active = *group-line -group-line = group spc high-number spc low-number spc flag -group = -spc = " " -high-number = -low-number = -flag = "y" / "n" / "m" / "j" / "x" / "=" group -@end example - -For a full description of this file, see the manual pages for -@samp{innd}, in particular @samp{active(5)}. - - -@node Newsgroups File Format -@subsubsection Newsgroups File Format - -The newsgroups file lists groups along with their descriptions. Not all -groups on the server have to be listed, and not all groups in the file -have to exist on the server. The file is meant purely as information to -the user. - -The format is quite simple; a group name, a tab, and the description. -Here's the definition: - -@example -newsgroups = *line -line = group tab description -group = -tab = -description = -@end example - - -@page -@node Emacs for Heathens -@section Emacs for Heathens - -Believe it or not, but some people who use Gnus haven't really used -Emacs much before they embarked on their journey on the Gnus Love Boat. -If you are one of those unfortunates whom ``@kbd{C-M-a}'', ``kill the -region'', and ``set @code{gnus-flargblossen} to an alist where the key -is a regexp that is used for matching on the group name'' are magical -phrases with little or no meaning, then this appendix is for you. If -you are already familiar with Emacs, just ignore this and go fondle your -cat instead. - -@menu -* Keystrokes:: Entering text and executing commands. -* Emacs Lisp:: The built-in Emacs programming language. -@end menu - - -@node Keystrokes -@subsection Keystrokes - -@itemize @bullet -@item -Q: What is an experienced Emacs user? - -@item -A: A person who wishes that the terminal had pedals. -@end itemize - -Yes, when you use Emacs, you are apt to use the control key, the shift -key and the meta key a lot. This is very annoying to some people -(notably @code{vi}le users), and the rest of us just love the hell out -of it. Just give up and submit. Emacs really does stand for -``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you -may have heard from other disreputable sources (like the Emacs author). - -The shift keys are normally located near your pinky fingers, and are -normally used to get capital letters and stuff. You probably use it all -the time. The control key is normally marked ``CTRL'' or something like -that. The meta key is, funnily enough, never marked as such on any -keyboard. The one I'm currently at has a key that's marked ``Alt'', -which is the meta key on this keyboard. It's usually located somewhere -to the left hand side of the keyboard, usually on the bottom row. - -Now, us Emacs people don't say ``press the meta-control-m key'', -because that's just too inconvenient. We say ``press the @kbd{C-M-m} -key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the -prefix that means ``control''. So ``press @kbd{C-k}'' means ``press -down the control key, and hold it down while you press @kbd{k}''. -``Press @kbd{C-M-k}'' means ``press down and hold down the meta key and -the control key and then press @kbd{k}''. Simple, ay? - -This is somewhat complicated by the fact that not all keyboards have a -meta key. In that case you can use the ``escape'' key. Then @kbd{M-k} -means ``press escape, release escape, press @kbd{k}''. That's much more -work than if you have a meta key, so if that's the case, I respectfully -suggest you get a real keyboard with a meta key. You can't live without -it. - - - -@node Emacs Lisp -@subsection Emacs Lisp - -Emacs is the King of Editors because it's really a Lisp interpreter. -Each and every key you tap runs some Emacs Lisp code snippet, and since -Emacs Lisp is an interpreted language, that means that you can configure -any key to run any arbitrary code. You just, like, do it. - -Gnus is written in Emacs Lisp, and is run as a bunch of interpreted -functions. (These are byte-compiled for speed, but it's still -interpreted.) If you decide that you don't like the way Gnus does -certain things, it's trivial to have it do something a different way. -(Well, at least if you know how to write Lisp code.) However, that's -beyond the scope of this manual, so we are simply going to talk about -some common constructs that you normally use in your @file{~/.gnus.el} -file to customize Gnus. (You can also use the @file{~/.emacs} file, but -in order to set things of Gnus up, it is much better to use the -@file{~/.gnus.el} file, @xref{Startup Files}.) - -If you want to set the variable @code{gnus-florgbnize} to four (4), you -write the following: - -@lisp -(setq gnus-florgbnize 4) -@end lisp - -This function (really ``special form'') @code{setq} is the one that can -set a variable to some value. This is really all you need to know. Now -you can go and fill your @file{~/.gnus.el} file with lots of these to -change how Gnus works. - -If you have put that thing in your @file{~/.gnus.el} file, it will be -read and @code{eval}ed (which is Lisp-ese for ``run'') the next time you -start Gnus. If you want to change the variable right away, simply say -@kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the -previous ``form'', which is a simple @code{setq} statement here. - -Go ahead---just try it, if you're located at your Emacs. After you -@kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which -is the return value of the form you @code{eval}ed. - -Some pitfalls: - -If the manual says ``set @code{gnus-read-active-file} to @code{some}'', -that means: - -@lisp -(setq gnus-read-active-file 'some) -@end lisp - -On the other hand, if the manual says ``set @code{gnus-nntp-server-file} to -@samp{/etc/nntpserver}'', that means: - -@lisp -(setq gnus-nntp-server-file "/etc/nntpserver") -@end lisp - -So be careful not to mix up strings (the latter) with symbols (the -former). The manual is unambiguous, but it can be confusing. - -@page -@include gnus-faq.texi - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include doclicense.texi - -@node Index -@chapter Index -@printindex cp - -@node Key Index -@chapter Key Index -@printindex ky - -@bye - -@iftex -@iflatex -\end{document} -@end iflatex -@end iftex - -@c Local Variables: -@c mode: texinfo -@c coding: iso-8859-1 -@c End: diff --git a/doc/misc/gpl.texi b/doc/misc/gpl.texi deleted file mode 100644 index 1908d1f8f98..00000000000 --- a/doc/misc/gpl.texi +++ /dev/null @@ -1,717 +0,0 @@ -@c The GNU General Public License. -@center Version 3, 29 June 2007 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. -@end display - -@heading Preamble - -The GNU General Public License is a free, copyleft license for -software and other kinds of works. - -The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom -to share and change all versions of a program---to make sure it remains -free software for all its users. We, the Free Software Foundation, -use the GNU General Public License for most of our software; it -applies also to any other work released this way by its authors. You -can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - -To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you -have certain responsibilities if you distribute copies of the -software, or if you modify it: responsibilities to respect the freedom -of others. - -For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, -receive or can get the source code. And you must show them these -terms so they know their rights. - -Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - -For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - -Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the -manufacturer can do so. This is fundamentally incompatible with the -aim of protecting users' freedom to change the software. The -systematic pattern of such abuse occurs in the area of products for -individuals to use, which is precisely where it is most unacceptable. -Therefore, we have designed this version of the GPL to prohibit the -practice for those products. If such problems arise substantially in -other domains, we stand ready to extend this provision to those -domains in future versions of the GPL, as needed to protect the -freedom of users. - -Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish -to avoid the special danger that patents applied to a free program -could make it effectively proprietary. To prevent this, the GPL -assures that patents cannot be used to render the program non-free. - -The precise terms and conditions for copying, distribution and -modification follow. - -@heading TERMS AND CONDITIONS - -@enumerate 0 -@item Definitions. - -``This License'' refers to version 3 of the GNU General Public License. - -``Copyright'' also means copyright-like laws that apply to other kinds -of works, such as semiconductor masks. - -``The Program'' refers to any copyrightable work licensed under this -License. Each licensee is addressed as ``you''. ``Licensees'' and -``recipients'' may be individuals or organizations. - -To ``modify'' a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of -an exact copy. The resulting work is called a ``modified version'' of -the earlier work or a work ``based on'' the earlier work. - -A ``covered work'' means either the unmodified Program or a work based -on the Program. - -To ``propagate'' a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - -To ``convey'' a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user -through a computer network, with no transfer of a copy, is not -conveying. - -An interactive user interface displays ``Appropriate Legal Notices'' to -the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - -@item Source Code. - -The ``source code'' for a work means the preferred form of the work for -making modifications to it. ``Object code'' means any non-source form -of a work. - -A ``Standard Interface'' means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - -The ``System Libraries'' of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -``Major Component'', in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - -The ``Corresponding Source'' for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - -The Corresponding Source need not include anything that users can -regenerate automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same -work. - -@item Basic Permissions. - -All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - -You may make, run and propagate covered works that you do not convey, -without conditions so long as your license otherwise remains in force. -You may convey covered works to others for the sole purpose of having -them make modifications exclusively for you, or provide you with -facilities for running those works, provided that you comply with the -terms of this License in conveying all material for which you do not -control copyright. Those thus making or running the covered works for -you must do so exclusively on your behalf, under your direction and -control, on terms that prohibit them from making any copies of your -copyrighted material outside their relationship with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - -@item Protecting Users' Legal Rights From Anti-Circumvention Law. - -No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such -circumvention is effected by exercising rights under this License with -respect to the covered work, and you disclaim any intention to limit -operation or modification of the work as a means of enforcing, against -the work's users, your or third parties' legal rights to forbid -circumvention of technological measures. - -@item Conveying Verbatim Copies. - -You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - -@item Conveying Modified Source Versions. - -You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these -conditions: - -@enumerate a -@item -The work must carry prominent notices stating that you modified it, -and giving a relevant date. - -@item -The work must carry prominent notices stating that it is released -under this License and any conditions added under section 7. This -requirement modifies the requirement in section 4 to ``keep intact all -notices''. - -@item -You must license the entire work, as a whole, under this License to -anyone who comes into possession of a copy. This License will -therefore apply, along with any applicable section 7 additional terms, -to the whole of the work, and all its parts, regardless of how they -are packaged. This License gives no permission to license the work in -any other way, but it does not invalidate such permission if you have -separately received it. - -@item -If the work has interactive user interfaces, each must display -Appropriate Legal Notices; however, if the Program has interactive -interfaces that do not display Appropriate Legal Notices, your work -need not make them do so. -@end enumerate - -A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -``aggregate'' if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -@item Conveying Non-Source Forms. - -You may convey a covered work in object code form under the terms of -sections 4 and 5, provided that you also convey the machine-readable -Corresponding Source under the terms of this License, in one of these -ways: - -@enumerate a -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by the -Corresponding Source fixed on a durable physical medium customarily -used for software interchange. - -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by a written -offer, valid for at least three years and valid for as long as you -offer spare parts or customer support for that product model, to give -anyone who possesses the object code either (1) a copy of the -Corresponding Source for all the software in the product that is -covered by this License, on a durable physical medium customarily used -for software interchange, for a price no more than your reasonable -cost of physically performing this conveying of source, or (2) access -to copy the Corresponding Source from a network server at no charge. - -@item -Convey individual copies of the object code with a copy of the written -offer to provide the Corresponding Source. This alternative is -allowed only occasionally and noncommercially, and only if you -received the object code with such an offer, in accord with subsection -6b. - -@item -Convey the object code by offering access from a designated place -(gratis or for a charge), and offer equivalent access to the -Corresponding Source in the same way through the same place at no -further charge. You need not require recipients to copy the -Corresponding Source along with the object code. If the place to copy -the object code is a network server, the Corresponding Source may be -on a different server (operated by you or a third party) that supports -equivalent copying facilities, provided you maintain clear directions -next to the object code saying where to find the Corresponding Source. -Regardless of what server hosts the Corresponding Source, you remain -obligated to ensure that it is available for as long as needed to -satisfy these requirements. - -@item -Convey the object code using peer-to-peer transmission, provided you -inform other peers where the object code and Corresponding Source of -the work are being offered to the general public at no charge under -subsection 6d. - -@end enumerate - -A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - -A ``User Product'' is either (1) a ``consumer product'', which means any -tangible personal property which is normally used for personal, -family, or household purposes, or (2) anything designed or sold for -incorporation into a dwelling. In determining whether a product is a -consumer product, doubtful cases shall be resolved in favor of -coverage. For a particular product received by a particular user, -``normally used'' refers to a typical or common use of that class of -product, regardless of the status of the particular user or of the way -in which the particular user actually uses, or expects or is expected -to use, the product. A product is a consumer product regardless of -whether the product has substantial commercial, industrial or -non-consumer uses, unless such uses represent the only significant -mode of use of the product. - -``Installation Information'' for a User Product means any methods, -procedures, authorization keys, or other information required to -install and execute modified versions of a covered work in that User -Product from a modified version of its Corresponding Source. The -information must suffice to ensure that the continued functioning of -the modified object code is in no case prevented or interfered with -solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - -The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or -updates for a work that has been modified or installed by the -recipient, or for the User Product in which it has been modified or -installed. Access to a network may be denied when the modification -itself materially and adversely affects the operation of the network -or violates the rules and protocols for communication across the -network. - -Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - -@item Additional Terms. - -``Additional permissions'' are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - -Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders -of that material) supplement the terms of this License with terms: - -@enumerate a -@item -Disclaiming warranty or limiting liability differently from the terms -of sections 15 and 16 of this License; or - -@item -Requiring preservation of specified reasonable legal notices or author -attributions in that material or in the Appropriate Legal Notices -displayed by works containing it; or - -@item -Prohibiting misrepresentation of the origin of that material, or -requiring that modified versions of such material be marked in -reasonable ways as different from the original version; or - -@item -Limiting the use for publicity purposes of names of licensors or -authors of the material; or - -@item -Declining to grant rights under trademark law for use of some trade -names, trademarks, or service marks; or - -@item -Requiring indemnification of licensors and authors of that material by -anyone who conveys the material (or modified versions of it) with -contractual assumptions of liability to the recipient, for any -liability that these contractual assumptions directly impose on those -licensors and authors. -@end enumerate - -All other non-permissive additional terms are considered ``further -restrictions'' within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; the -above requirements apply either way. - -@item Termination. - -You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - -@item Acceptance Not Required for Having Copies. - -You are not required to accept this License in order to receive or run -a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - -@item Automatic Licensing of Downstream Recipients. - -Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - -An ``entity transaction'' is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - -You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - -@item Patents. - -A ``contributor'' is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's ``contributor version''. - -A contributor's ``essential patent claims'' are all patent claims owned -or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, ``control'' includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - -In the following three paragraphs, a ``patent license'' is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To ``grant'' such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - -If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. ``Knowingly relying'' means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - -If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - -A patent license is ``discriminatory'' if it does not include within the -scope of its coverage, prohibits the exercise of, or is conditioned on -the non-exercise of one or more of the rights that are specifically -granted under this License. You may not convey a covered work if you -are a party to an arrangement with a third party that is in the -business of distributing software, under which you make payment to the -third party based on the extent of your activity of conveying the -work, and under which the third party grants, to any of the parties -who would receive the covered work from you, a discriminatory patent -license (a) in connection with copies of the covered work conveyed by -you (or copies made from those copies), or (b) primarily for and in -connection with specific products or compilations that contain the -covered work, unless you entered into that arrangement, or that patent -license was granted, prior to 28 March 2007. - -Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - -@item No Surrender of Others' Freedom. - -If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey -a covered work so as to satisfy simultaneously your obligations under -this License and any other pertinent obligations, then as a -consequence you may not convey it at all. For example, if you agree -to terms that obligate you to collect a royalty for further conveying -from those to whom you convey the Program, the only way you could -satisfy both those terms and this License would be to refrain entirely -from conveying the Program. - -@item Use with the GNU Affero General Public License. - -Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - -@item Revised Versions of this License. - -The Free Software Foundation may publish revised and/or new versions -of the GNU General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies that a certain numbered version of the GNU General Public -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that numbered version or -of any later version published by the Free Software Foundation. If -the Program does not specify a version number of the GNU General -Public License, you may choose any version ever published by the Free -Software Foundation. - -If the Program specifies that a proxy can decide which future versions -of the GNU General Public License can be used, that proxy's public -statement of acceptance of a version permanently authorizes you to -choose that version for the Program. - -Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - -@item Disclaimer of Warranty. - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT -WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND -PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -@item Limitation of Liability. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR -CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT -NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR -LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM -TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER -PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -@item Interpretation of Sections 15 and 16. - -If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - -@end enumerate - -@heading END OF TERMS AND CONDITIONS - -@heading How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or (at -your option) any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see @url{http://www.gnu.org/licenses/}. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - -@smallexample -@var{program} Copyright (C) @var{year} @var{name of author} -This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. -This is free software, and you are welcome to redistribute it -under certain conditions; type @samp{show c} for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, your -program's commands might be different; for a GUI interface, you would -use an ``about box''. - -You should also get your employer (if you work as a programmer) or school, -if any, to sign a ``copyright disclaimer'' for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -@url{http://www.gnu.org/licenses/}. - -The GNU General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use -the GNU Lesser General Public License instead of this License. But -first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi deleted file mode 100644 index 736c6ce7f91..00000000000 --- a/doc/misc/idlwave.texi +++ /dev/null @@ -1,4297 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/idlwave -@settitle IDLWAVE User Manual -@synindex ky cp -@syncodeindex vr cp -@syncodeindex fn cp -@set VERSION 6.1 -@set EDITION 6.1 -@set IDLVERSION 6.3 -@set NSYSROUTINES 4346 -@set DATE April, 2007 -@set AUTHOR J.D. Smith & Carsten Dominik -@set MAINTAINER J.D. Smith -@c %**end of header -@finalout - -@copying -This file documents IDLWAVE, a major mode for editing IDL files with -Emacs, and interacting with an IDL shell run as a subprocess. - -This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE -@value{VERSION}. - -Copyright @copyright{} 1999-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs editing modes -@direntry -* IDLWAVE: (idlwave). Major mode and shell for IDL files. -@end direntry - -@titlepage -@title IDLWAVE User Manual -@subtitle Emacs major mode and shell for IDL -@subtitle Edition @value{EDITION}, @value{DATE} -@author by J.D. Smith & Carsten Dominik -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top IDLWAVE - -IDLWAVE is a package which supports editing source code written in the -Interactive Data Language (IDL), and running IDL as an inferior shell. - -@insertcopying -@end ifnottex - -@menu -* Introduction:: What IDLWAVE is, and what it is not -* IDLWAVE in a Nutshell:: One page quick-start guide -* Getting Started:: Tutorial -* The IDLWAVE Major Mode:: The mode for editing IDL programs -* The IDLWAVE Shell:: The mode for running IDL as an inferior program -* Acknowledgements:: Who did what -* Sources of Routine Info:: How does IDLWAVE know about routine XYZ -* HTML Help Browser Tips:: -* Configuration Examples:: The user is king -* Windows and MacOS:: What still works, and how -* Troubleshooting:: When good computers turn bad -* GNU Free Documentation License:: The license for this documentation. -* Index:: Fast access - -@detailmenu - --- The Detailed Node Listing --- - -Getting Started (Tutorial) - -* Lesson I -- Development Cycle:: -* Lesson II -- Customization:: -* Lesson III -- User Catalog:: - -The IDLWAVE Major Mode - -* Code Formatting:: Making code look nice -* Routine Info:: Calling Sequence and Keyword List -* Online Help:: One key press from source to help -* Completion:: Completing routine names and Keywords -* Routine Source:: Finding routines, the easy way -* Resolving Routines:: Force the Shell to compile a routine -* Code Templates:: Frequent code constructs -* Abbreviations:: Abbreviations for common commands -* Actions:: Changing case, Padding, End checking -* Doc Header:: Inserting a standard header -* Motion Commands:: Moving through the structure of a program -* Misc Options:: Things that fit nowhere else - -Code Formatting - -* Code Indentation:: Reflecting the logical structure -* Continued Statement Indentation:: -* Comment Indentation:: Special indentation for comment lines -* Continuation Lines:: Splitting statements over lines -* Syntax Highlighting:: Font-lock support -* Octals and Highlighting:: Why "123 causes problems - -Online Help - -* Help with HTML Documentation:: -* Help with Source:: - -Completion - -* Case of Completed Words:: CaseOFcomPletedWords -* Object Method Completion and Class Ambiguity:: obj->Method, what? -* Object Method Completion in the Shell:: -* Class and Keyword Inheritance:: obj->Method, _EXTRA=e -* Structure Tag Completion:: Completing state.Tag - -Actions - -* Block Boundary Check:: Is the END statement correct? -* Padding Operators:: Enforcing space around `=' etc -* Case Changes:: Enforcing upper case keywords - -The IDLWAVE Shell - -* Starting the Shell:: How to launch IDL as a subprocess -* Using the Shell:: Interactively working with the Shell -* Commands Sent to the Shell:: -* Debugging IDL Programs:: -* Examining Variables:: -* Custom Expression Examination:: - -Debugging IDL Programs - -* A Tale of Two Modes:: -* Debug Key Bindings:: -* Breakpoints and Stepping:: -* Compiling Programs:: -* Walking the Calling Stack:: -* Electric Debug Mode:: - -Sources of Routine Info - -* Routine Definitions:: Where IDL Routines are defined. -* Routine Information Sources:: So how does IDLWAVE know about... -* Catalogs:: -* Load-Path Shadows:: Routines defined in several places -* Documentation Scan:: Scanning the IDL Manuals - -Catalogs - -* Library Catalogs:: -* User Catalog:: - -@end detailmenu -@end menu - -@node Introduction, IDLWAVE in a Nutshell, Top, Top -@chapter Introduction -@cindex Introduction -@cindex CORBA (Common Object Request Broker Architecture) -@cindex Interface Definition Language -@cindex Interactive Data Language -@cindex cc-mode.el -@cindex @file{idl.el} -@cindex @file{idl-shell.el} -@cindex Feature overview - -IDLWAVE is a package which supports editing source files written in -the Interactive Data Language (IDL), and running IDL as an inferior shell@footnote{IDLWAVE can also be used -for editing source files for the related WAVE/CL language, but with only -limited support.}. It is a feature-rich replacement for the IDLDE -development environment included with IDL, and uses the full power of -Emacs to make editing and running IDL programs easier, quicker, and more -structured. - -IDLWAVE consists of two main parts: a major mode for editing IDL -source files (@code{idlwave-mode}) and a mode for running the IDL -program as an inferior shell (@code{idlwave-shell-mode}). Although -one mode can be used without the other, both work together closely to -form a complete development environment. Here is a brief summary of -what IDLWAVE does: - -@itemize @bullet -@item -Smart code indentation and automatic-formatting. -@item -Three level syntax highlighting support. -@item -Context-sensitive display of calling sequences and keywords for more -than 1000 native IDL routines, extensible to any additional number of -local routines, and already available with many pre-scanned libraries. -@item -Fast, context-sensitive online HTML help, or source-header help for -undocumented routines. -@item -Context sensitive completion of routine names, keywords, system -variables, class names and much more. -@item -Easy insertion of code templates and abbreviations of common constructs. -@item -Automatic corrections to enforce a variety of customizable coding -standards. -@item -Integrity checks and auto-termination of logical blocks. -@item -Routine name space conflict search with likelihood-of-use ranking. -@item -Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs). -@item -Documentation support. -@item -Running IDL as an inferior Shell with history search, command line -editing and all the completion and routine info capabilities present in -IDL source buffers. -@item -Full handling of debugging with breakpoints, with interactive setting -of break conditions, and easy stepping through code. -@item -Compilation, execution and interactive single-keystroke debugging of -programs directly from the source buffer. -@item -Quick, source-guided navigation of the calling stack, with variable -inspection, etc. -@item -Examining variables and expressions with a mouse click. -@item -And much, much more... -@end itemize - -@ifnottex -@cindex Screenshots -Here are a number of screenshots showing IDLWAVE in action: - -@itemize @bullet -@item -@uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer} -@item -@uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed} -@item -@uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.} -@item -@uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed} -@item -@uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code -stopped at a breakpoint} -@end itemize -@end ifnottex - -IDLWAVE is the distant successor to the @file{idl.el} and -@file{idl-shell.el} files written by Chris Chase. The modes and files -had to be renamed because of a name space conflict with CORBA's -@code{idl-mode}, defined in Emacs in the file @file{cc-mode.el}. - -In this manual, each section ends with a list of related user options. -Don't be confused by the sheer number of options available --- in most -cases the default settings are just fine. The variables are listed here -to make sure you know where to look if you want to change anything. For -a full description of what a particular variable does and how to -configure it, see the documentation string of that variable (available -with @kbd{C-h v}). Some configuration examples are also given in the -appendix. - -@node IDLWAVE in a Nutshell, Getting Started, Introduction, Top -@chapter IDLWAVE in a Nutshell -@cindex Summary of important commands -@cindex IDLWAVE in a Nutshell -@cindex Nutshell, IDLWAVE in a - -@subheading Editing IDL Programs - -@multitable @columnfractions .15 .85 -@item @key{TAB} -@tab Indent the current line relative to context. -@item @kbd{C-M-\} -@tab Re-indent all lines in the current region. -@item @kbd{C-M-q} -@tab Re-indent all lines in the current routine. -@item @kbd{C-u @key{TAB}} -@tab Re-indent all lines in the current statement. -@item @kbd{M-@key{RET}} -@tab Start a continuation line, splitting the current line at point. -@item @kbd{M-;} -@tab Start new comment at line beginning or after code, or (un)comment -highlighted region. -@item @kbd{M-q} -@tab Fill the current comment paragraph. -@item @kbd{C-c ?} -@tab Display calling sequence and keywords for the procedure or function call -at point. -@item @kbd{M-?} -@tab Load context sensitive online help for nearby routine, keyword, etc. -@item @kbd{M-@key{TAB}} -@tab Complete a procedure name, function name or keyword in the buffer. -@item @kbd{C-c C-i} -@tab Update IDLWAVE's knowledge about functions and procedures. -@item @kbd{C-c C-v} -@tab Visit the source code of a procedure/function. -@item @kbd{C-u C-c C-v} -@tab Visit the source code of a procedure/function in this buffer. -@item @kbd{C-c C-h} -@tab Insert a standard documentation header. -@item @kbd{C-c @key{RET}} -@tab Insert a new timestamp and history item in the documentation header. -@end multitable - -@subheading Running the IDLWAVE Shell, Debugging Programs - -@multitable @columnfractions .15 .85 -@item @kbd{C-c C-s} -@tab Start IDL as a subprocess and/or switch to the shell buffer. -@item @key{Up}, @kbd{M-p} -@tab Cycle back through IDL command history. -@item @key{Down},@kbd{M-n} -@tab Cycle forward. -@item @kbd{@key{TAB}} -@tab Complete a procedure name, function name or keyword in the shell buffer. -@item @kbd{C-c C-d C-c} -@tab Save and compile the source file in the current buffer. -@item @kbd{C-c C-d C-e} -@tab Compile and run the current region. -@item @kbd{C-c C-d C-x} -@tab Go to next syntax error. -@item @kbd{C-c C-d C-v} -@tab Switch to electric debug mode. -@item @kbd{C-c C-d C-b} -@tab Set a breakpoint at the nearest viable source line. -@item @kbd{C-c C-d C-d} -@tab Clear the nearest breakpoint. -@item @kbd{C-c C-d [} -@tab Go to the previous breakpoint. -@item @kbd{C-c C-d ]} -@tab Go to the next breakpoint. -@item @kbd{C-c C-d C-p} -@tab Print the value of the expression near point in IDL. -@end multitable - -@subheading Commonly used Settings in @file{.emacs} -@lisp -;; Change the indentation preferences -;; Start autoloading routine info after 2 idle seconds -(setq idlwave-init-rinfo-when-idle-after 2) -;; Pad operators with spaces -(setq idlwave-do-actions t - idlwave-surround-by-blank t) -;; Syntax Highlighting -(add-hook 'idlwave-mode-hook 'turn-on-font-lock) -;; Automatically start the shell when needed -(setq idlwave-shell-automatic-start t) -;; Bind debugging commands with CONTROL and SHIFT modifiers -(setq idlwave-shell-debug-modifiers '(control shift)) -@end lisp - -@html - -@end html - -@node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top -@chapter Getting Started (Tutorial) -@cindex Quick-Start -@cindex Tutorial -@cindex Getting Started - -@menu -* Lesson I -- Development Cycle:: -* Lesson II -- Customization:: -* Lesson III -- User Catalog:: -@end menu - -@node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started -@section Lesson I: Development Cycle - -The purpose of this tutorial is to guide you through a very basic -development cycle using IDLWAVE. We will paste a simple program into -a buffer and use the shell to compile, debug and run it. On the way -we will use many of the important IDLWAVE commands. Note, however, -that IDLWAVE has many more capabilities than covered here, which can -be discovered by reading the entire manual, or hovering over the -shoulder of your nearest IDLWAVE guru for a few days. - -It is assumed that you have access to Emacs or XEmacs with the full -IDLWAVE package including online help. We also assume that you are -familiar with Emacs and can read the nomenclature of key presses in -Emacs (in particular, @kbd{C} stands for @key{CONTROL} and @kbd{M} for -@key{META} (often the @key{ALT} key carries this functionality)). - -Open a new source file by typing: - -@example -@kbd{C-x C-f tutorial.pro @key{RET}} -@end example - -A buffer for this file will pop up, and it should be in IDLWAVE mode, -indicated in the mode line just below the editing window. Also, the -menu bar should contain @samp{IDLWAVE}. - -Now cut-and-paste the following code, also available as -@file{tutorial.pro} in the IDLWAVE distribution. - -@example -function daynr,d,m,y - ;; compute a sequence number for a date - ;; works 1901-2099. - if y lt 100 then y = y+1900 - if m le 2 then delta = 1 else delta = 0 - m1 = m + delta*12 + 1 - y1 = y * delta - return, d + floor(m1*30.6)+floor(y1*365.25)+5 -end - -function weekday,day,month,year - ;; compute weekday number for date - nr = daynr(day,month,year) - return, nr mod 7 -end - -pro plot_wday,day,month - ;; Plot the weekday of a date in the first 10 years of this century. - years = 2000,+indgen(10) - wdays = intarr(10) - for i=0,n_elements(wdays)-1 do begin - wdays[i] = weekday(day,month,years[i]) - end - plot,years,wdays,YS=2,YT="Wday (0=Sunday)" -end -@end example - -The indentation probably looks funny, since it's different from the -settings you use, so use the @key{TAB} key in each line to -automatically line it up (or, more quickly, @emph{select} the entire -buffer with @kbd{C-x h}, and indent the whole region with -@kbd{C-M-\}). Notice how different syntactical elements are -highlighted in different colors, if you have set up support for -font-lock. - -Let's check out two particular editing features of IDLWAVE. Place the -cursor after the @code{end} statement of the @code{for} loop and press -@key{SPC}. IDLWAVE blinks back to the beginning of the block and -changes the generic @code{end} to the specific @code{endfor} -automatically (as long as the variable @code{idlwave-expand-generic-end} -is turned on --- @pxref{Lesson II -- Customization}). Now place the -cursor in any line you would like to split and press @kbd{M-@key{RET}}. -The line is split at the cursor position, with the continuation @samp{$} -and indentation all taken care of. Use @kbd{C-/} to undo the last -change. - -The procedure @code{plot_wday} is supposed to plot the day of the week -of a given date for the first 10 years of the 21st century. As in -most code, there are a few bugs, which we are going to use IDLWAVE to -help us fix. - -First, let's launch the IDLWAVE shell. You do this with the command -@kbd{C-c C-s}. The Emacs window will split or another window will popup -to display IDL running in a shell interaction buffer. Type a few -commands like @code{print,!PI} to convince yourself that you can work -there just as well as in a terminal, or the IDLDE. Use the arrow keys -to cycle through your command history. Are we having fun now? - -Now go back to the source window and type @kbd{C-c C-d C-c} to compile -the program. If you watch the shell buffer, you see that IDLWAVE types -@samp{.run "tutorial.pro"} for you. But the compilation fails because -there is a comma in the line @samp{years=...}. The line with the error -is highlighted and the cursor positioned at the error, so remove the -comma (you should only need to hit @kbd{Delete}!). Compile again, using -the same keystrokes as before. Notice that the file is automatically -saved for you. This time everything should work fine, and you should -see the three routines compile. - -Now we want to use the command to plot the day of the week on January -1st. We could type the full command ourselves, but why do that? Go -back to the shell window, type @samp{plot_} and hit @key{TAB}. After -a bit of a delay (while IDLWAVE initializes its routine info database, -if necessary), the window will split to show all procedures it knows -starting with that string, and @w{@code{plot_wday}} should be one of -them. Saving the buffer alerted IDLWAVE about this new routine. -Click with the middle mouse button on @code{plot_wday} and it will be -copied to the shell buffer, or if you prefer, add @samp{w} to -@samp{plot_} to make it unambiguous (depending on what other routines -starting with @samp{plot_} you have installed on your system), hit -@key{TAB} again, and the full routine name will be completed. Now -provide the two arguments: - -@example -plot_wday,1,1 -@end example - -@noindent and press @key{RET}. This fails with an error message telling -you the @code{YT} keyword to plot is ambiguous. What are the allowed -keywords again? Go back to the source window and put the cursor into -the `plot' line and press @kbd{C-c ?}. This shows the routine info -window for the plot routine, which contains a list of keywords, along -with the argument list. Oh, we wanted @code{YTITLE}. Fix that up. -Recompile with @kbd{C-c C-d C-c}. Jump back into the shell with -@kbd{C-c C-s}, press the @key{UP} arrow to recall the previous command -and execute again. - -This time we get a plot, but it is pretty ugly --- the points are all -connected with a line. Hmm, isn't there a way for @code{plot} to use -symbols instead? What was that keyword? Position the cursor on the -plot line after a comma (where you'd normally type a keyword), and hit -@kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha, -there it is, @code{PSYM}. Middle click to insert it. An @samp{=} -sign is included for you too. Now what were the values of @code{PSYM} -supposed to be? With the cursor on or after the keyword, press -@kbd{M-?} for online help (alternatively, you could have right clicked -on the colored keyword itself in the completion list). A browser will -pop up showing the HTML documentation for the @code{PYSM} keyword. -OK, let's use diamonds=4. Fix this, recompile (you know the command -by now: @kbd{C-c C-d C-c}), go back to the shell (if it's vanished, -you know what to do: @kbd{C-c C-s}) and execute again. Now things -look pretty good. - -Let's try a different day --- how about April fool's day? - -@example -plot_wday,1,4 -@end example - -Oops, this looks very wrong. All April Fool's days cannot be Fridays! -We've got a bug in the program, perhaps in the @code{daynr} function. -Let's put a breakpoint on the last line there. Position the cursor on -the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a -breakpoint (as you see in the shell window), and the break line is -indicated. Back to the shell buffer, re-execute the previous command. -IDL stops at the line with the breakpoint. Now hold down the SHIFT -key and click with the middle mouse button on a few variables there: -@samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe @code{d} isn't -the correct type. CONTROL-SHIFT middle-click on it for help. Well, -it's an integer, so that's not the problem. Aha, @samp{y1} is zero, -but it should be the year, depending on delta. Shift click -@samp{delta} to see that it's 0. Below, we see the offending line: -@samp{y1=y*delta...} the multiplication should have been a minus sign! -Hit @kbd{q} to exit the debugging mode, and fix the line to read: - -@example -y1 = y - delta -@end example - -Now remove all breakpoints: @kbd{C-c C-d C-a}. Recompile and rerun the -command. Everything should now work fine. How about those leap years? -Change the code to plot 100 years and see that every 28 years, the -sequence of weekdays repeats. - -@node Lesson II -- Customization, Lesson III -- User Catalog, Lesson I -- Development Cycle, Getting Started -@section Lesson II: Customization - -Emacs is probably the most customizable piece of software ever written, -and it would be a shame if you did not make use of this to adapt IDLWAVE -to your own preferences. Customizing Emacs or IDLWAVE is accomplished -by setting Lisp variables in the @file{.emacs} file in your home -directory --- but do not be dismayed; for the most part, you can just -copy and work from the examples given here. - -Let's first use a boolean variable. These are variables which you turn -on or off, much like a checkbox. A value of @samp{t} means on, a value -of @samp{nil} means off. Copy the following line into your -@file{.emacs} file, exit and restart Emacs. - -@lisp -(setq idlwave-reserved-word-upcase t) -@end lisp - -When this option is turned on, each reserved word you type into an IDL -source buffer will be converted to upper case when you press @key{SPC} -or @key{RET} right after the word. Try it out! @samp{if} changes to -@samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this -behavior, remove the option again from your @file{.emacs} file and -restart Emacs. - -You likely have your own indentation preferences for IDL code. For -example, some may prefer to indent the main block of an IDL program -slightly from the margin and use only 3 spaces as indentation between -@code{BEGIN} and @code{END}. Try the following lines in @file{.emacs}: - -@lisp -(setq idlwave-main-block-indent 1) -(setq idlwave-block-indent 3) -(setq idlwave-end-offset -3) -@end lisp - -Restart Emacs, and re-indent the program we developed in the first part -of this tutorial with @kbd{C-c h} and @kbd{C-M-\}. You may want to keep -these lines in @file{.emacs}, with values adjusted to your likings. If -you want to get more information about any of these variables, type, -e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}. To find which -variables can be customized, look for items marked @samp{User Option:} -throughout this manual. - -If you cannot seem to master this Lisp customization in @file{.emacs}, -there is another, more user-friendly way to customize all the IDLWAVE -variables. You can access it through the IDLWAVE menu in one of the -@file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE -Group}. Here you'll be presented with all the various variables grouped -into categories. You can navigate the hierarchy (e.g. @samp{IDLWAVE -Code Formatting->Idlwave Abbrev And Indent Action->Idlwave Expand -Generic End} to turn on @code{END} expansion), read about the variables, -change them, and `Save for Future Sessions'. Few of these variables -need customization, but you can exercise considerable control over -IDLWAVE's functionality with them. - -You may also find the key bindings used for the debugging commands too -long and complicated. Often we have heard complaints along the lines -of, ``Do I really have to go through the finger gymnastics of @kbd{C-c -C-d C-c} to run a simple command?'' Due to Emacs rules and -conventions, shorter bindings cannot be set by default, but you can -easily enable them. First, there is a way to assign all debugging -commands in a single sweep to another simpler combination. The only -problem is that we have to use something which Emacs does not need for -other important commands. One good option is to execute debugging -commands by holding down @key{CONTROL} and @key{SHIFT} while pressing -a single character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} -for compiling the current source file, @kbd{C-S-a} for deleting all -breakpoints (try it, it's easier). You can enable this with: - -@lisp -(setq idlwave-shell-debug-modifiers '(shift control)) -@end lisp - -@noindent If you have a special keyboard with, for example, a -@key{SUPER} key, you could even shorten that: - -@lisp -(setq idlwave-shell-debug-modifiers '(super)) -@end lisp - -@noindent to get compilation on @kbd{S-c}. Often, a modifier key like -@key{SUPER} or @key{HYPER} is bound or can be bound to an otherwise -unused key on your keyboard --- consult your system documentation. - -You can also assign specific commands to keys. This you must do in the -@emph{mode-hook}, a special function which is run when a new IDLWAVE -buffer gets set up. The possibilities for key customization are -endless. Here we set function keys f4-f8 to common debugging commands. - -@lisp -;; First for the source buffer -(add-hook 'idlwave-mode-hook - (lambda () - (local-set-key [f4] 'idlwave-shell-retall) - (local-set-key [f5] 'idlwave-shell-break-here) - (local-set-key [f6] 'idlwave-shell-clear-current-bp) - (local-set-key [f7] 'idlwave-shell-cont) - (local-set-key [f8] 'idlwave-shell-clear-all-bp))) -;; Then for the shell buffer -(add-hook 'idlwave-shell-mode-hook - (lambda () - (local-set-key [f4] 'idlwave-shell-retall) - (local-set-key [f5] 'idlwave-shell-break-here) - (local-set-key [f6] 'idlwave-shell-clear-current-bp) - (local-set-key [f7] 'idlwave-shell-cont) - (local-set-key [f8] 'idlwave-shell-clear-all-bp))) -@end lisp - -@node Lesson III -- User Catalog, , Lesson II -- Customization, Getting Started -@section Lesson III: User and Library Catalogs - -We have already used the routine info display in the first part of this -tutorial. This was the invoked using @kbd{C-c ?}, and displays -information about the IDL routine near the cursor position. Wouldn't it -be nice to have the same kind of information available for your own -routines and for the huge amount of code in major libraries like JHUAPL -or the IDL-Astro library? In many cases, you may already have this -information. Files named @file{.idlwave_catalog} in library directories -contain scanned information on the routines in that directory; many -popular libraries ship with these ``library catalogs'' pre-scanned. -Users can scan their own routines in one of two ways: either using the -supplied tool to scan directories and build their own -@file{.idlwave_catalog} files, or using the built-in method to create a -single ``user catalog'', which we'll show here. @xref{Catalogs}, for -more information on choosing which method to use. - -To build a user catalog, select @code{Routine Info/Select Catalog -Directories} from the IDLWAVE entry in the menu bar. If necessary, -start the shell first with @kbd{C-c C-s} (@pxref{Starting the Shell}). -IDLWAVE will find out about the IDL @code{!PATH} variable and offer a -list of directories on the path. Simply select them all (or whichever -you want --- directories with existing library catalogs will not be -selected by default) and click on the @samp{Scan&Save} button. Then -go for a cup of coffee while IDLWAVE collects information for each and -every IDL routine on your search path. All this information is -written to the file @file{.idlwave/idlusercat.el} in your home -directory and will from now on automatically load whenever you use -IDLWAVE. You may find it necessary to rebuild the catalog on occasion -as your local libraries change, or build a library catalog for those -directories instead. Invoke routine info (@kbd{C-c ?}) or completion -(@kbd{M-@key{TAB}}) on any routine or partial routine name you know to -be located in the library. E.g., if you have scanned the IDL-Astro -library: - -@example - a=readf@key{M-@key{TAB}} -@end example - -expands to `readfits('. Then try - -@example - a=readfits(@key{C-c ?} -@end example - -and you get: - -@example -Usage: Result = READFITS(filename, header, heap) -... -@end example - -I hope you made it until here. Now you are set to work with IDLWAVE. -On the way you will want to change other things, and to learn more -about the possibilities not discussed in this short tutorial. Read -the manual, look at the documentation strings of interesting variables -(with @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the -remaining questions on the newsgroup @code{comp.lang.idl-pvwave}. - -@node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top -@chapter The IDLWAVE Major Mode -@cindex IDLWAVE major mode -@cindex Major mode, @code{idlwave-mode} - -The IDLWAVE major mode supports editing IDL source files. In this -chapter we describe the main features of the mode and how to customize -them. - -@menu -* Code Formatting:: Making code look nice -* Routine Info:: Calling Sequence and Keyword List -* Online Help:: One key press from source to help -* Completion:: Completing routine names and Keywords -* Routine Source:: Finding routines, the easy way -* Resolving Routines:: Force the Shell to compile a routine -* Code Templates:: Frequent code constructs -* Abbreviations:: Abbreviations for common commands -* Actions:: Changing case, Padding, End checking -* Doc Header:: Inserting a standard header -* Motion Commands:: Moving through the structure of a program -* Misc Options:: Things that fit nowhere else -@end menu - -@node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode -@section Code Formatting -@cindex Code formatting -@cindex Formatting, of code - -@menu -* Code Indentation:: Reflecting the logical structure -* Continued Statement Indentation:: -* Comment Indentation:: Special indentation for comment lines -* Continuation Lines:: Splitting statements over lines -* Syntax Highlighting:: Font-lock support -* Octals and Highlighting:: Why "123 causes problems -@end menu - -The IDL language, with its early roots in FORTRAN, modern -implementation in C, and liberal borrowing of features of many vector -and other languages along its 25+ year history, has inherited an -unusual mix of syntax elements. Left to his or her own devices, a -novice IDL programmer will often conjure code which is very difficult -to read and impossible to adapt. Much can be gleaned from studying -available IDL code libraries for coding style pointers, but, due to -the variety of IDL syntax elements, replicating this style can be -challenging at best. Luckily, IDLWAVE understands the structure of -IDL code very well, and takes care of almost all formatting issues for -you. After configuring it to match your coding standards, you can -rely on it to help keep your code neat and organized. - - -@node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting -@subsection Code Indentation -@cindex Code indentation -@cindex Indentation - -Like all Emacs programming modes, IDLWAVE performs code indentation. -The @key{TAB} key indents the current line relative to context. -@key{LFD} insert a newline and indents the new line. The indentation is -governed by a number of variables. IDLWAVE indents blocks (between -@code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and -continuation lines. - -@cindex Foreign code, adapting -@cindex Indentation, of foreign code -@kindex C-M-\ -To re-indent a larger portion of code (e.g. when working with foreign -code written with different conventions), use @kbd{C-M-\} -(@code{indent-region}) after marking the relevant code. Useful marking -commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current -subprogram). The command @kbd{C-M-q} reindents the entire current -routine. @xref{Actions}, for information how to impose additional -formatting conventions on foreign code. - -@defopt idlwave-main-block-indent (@code{2}) -Extra indentation for the main block of code. That is the block between -the FUNCTION/PRO statement and the END statement for that program -unit. -@end defopt - -@defopt idlwave-block-indent (@code{3}) -Extra indentation applied to block lines. If you change this, you -probably also want to change @code{idlwave-end-offset}. -@end defopt - -@defopt idlwave-end-offset (@code{-3}) -Extra indentation applied to block END lines. A value equal to negative -@code{idlwave-block-indent} will make END lines line up with the block -BEGIN lines. -@end defopt - -@node Continued Statement Indentation, Comment Indentation, Code Indentation, Code Formatting -@subsection Continued Statement Indentation -@cindex Indentation, continued statement -@cindex Continued statement indentation -Continuation lines (following a line ending with @code{$}) can receive a -fixed indentation offset from the main level, but in several situations -IDLWAVE can use a special form of indentation which aligns continued -statements more naturally. Special indentation is calculated for -continued routine definition statements and calls, enclosing parentheses -(like function calls, structure/class definitions, explicit structures -or lists, etc.), and continued assignments. An attempt is made to line -up with the first non-whitespace character after the relevant opening -punctuation mark (@code{,},@code{(},@code{@{},@code{[},@code{=}). For -lines without any non-comment characters on the line with the opening -punctuation, the continued line(s) are aligned just past the -punctuation. An example: - -@example -function foo, a, b, $ - c, d - bar = sin( a + b + $ - c + d) -end -@end example -@noindent - -The only drawback to this special continued statement indentation is -that it consumes more space, e.g., for long function names or left hand -sides of an assignment: - -@example -function thisfunctionnameisverylongsoitwillleavelittleroom, a, b, $ - c, d -@end example - -You can instruct IDLWAVE when to avoid using this special continuation -indentation by setting the variable -@code{idlwave-max-extra-continuation-indent}, which specifies the -maximum additional indentation beyond the basic indent to be -tolerated, otherwise defaulting to a fixed-offset from the enclosing -indent (the size of which offset is set in -@code{idlwave-continuation-indent}). As a special case, continuations -of routine calls without any arguments or keywords will @emph{not} -align the continued line, under the assumption that you continued -because you needed the space. - -Also, since the indentation level can be somewhat dynamic in continued -statements with special continuation indentation, especially if -@code{idlwave-max-extra-continuation-indent} is small, the key -@kbd{C-u @key{TAB}} will re-indent all lines in the current statement. -Note that @code{idlwave-indent-to-open-paren}, if non-@code{nil}, -overrides the @code{idlwave-max-extra-continuation-indent} limit, for -parentheses only, forcing them always to line up. - - -@defopt idlwave-continuation-indent (@code{2}) -Extra indentation applied to normal continuation lines. -@end defopt - -@defopt idlwave-max-extra-continuation-indent (@code{20}) -The maximum additional indentation (over the basic continuation-indent) -that will be permitted for special continues. To effectively disable -special continuation indentation, set to @code{0}. To enable it -constantly, set to a large number (like @code{100}). Note that the -indentation in a long continued statement never decreases from line to -line, outside of nested parentheses statements. -@end defopt - -@defopt idlwave-indent-to-open-paren (@code{t}) -Non-@code{nil} means indent continuation lines to innermost open -parenthesis, regardless of whether the -@code{idlwave-max-extra-continuation-indent} limit is satisfied. -@end defopt - -@node Comment Indentation, Continuation Lines, Continued Statement Indentation, Code Formatting -@subsection Comment Indentation -@cindex Comment indentation -@cindex Hanging paragraphs -@cindex Paragraphs, filling -@cindex Paragraphs, hanging - -In IDL, lines starting with a @samp{;} are called @emph{comment lines}. -Comment lines are indented as follows: - -@multitable @columnfractions .1 .90 -@item @code{;;;} -@tab The indentation of lines starting with three semicolons remains -unchanged. -@item @code{;;} -@tab Lines starting with two semicolons are indented like the surrounding code. -@item @code{;} -@tab Lines starting with a single semicolon are indented to a minimum column. -@end multitable - -@noindent -The indentation of comments starting in column 0 is never changed. - -@defopt idlwave-no-change-comment -The indentation of a comment starting with this regexp will not be -changed. -@end defopt - -@defopt idlwave-begin-line-comment -A comment anchored at the beginning of line. -@end defopt - -@defopt idlwave-code-comment -A comment that starts with this regexp is indented as if it is a part of -IDL code. -@end defopt - -@node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting -@subsection Continuation Lines and Filling -@cindex Continuation lines -@cindex Line splitting -@cindex String splitting -@cindex Splitting, of lines - -@kindex M-@key{RET} -In IDL, a newline character terminates a statement unless preceded by a -@samp{$}. If you would like to start a continuation line, use -@kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}. -It inserts the continuation character @samp{$}, terminates the line and -indents the new line. The command @kbd{M-@key{RET}} can also be invoked -inside a string to split it at that point, in which case the @samp{+} -concatenation operator is used. - -@cindex Filling -@cindex @code{auto-fill-mode} -@cindex Hanging paragraphs -When filling comment paragraphs, IDLWAVE overloads the normal filling -functions and uses a function which creates the hanging paragraphs -customary in IDL routine headers. When @code{auto-fill-mode} is turned -on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If the -first line of a paragraph contains a match for -@code{idlwave-hang-indent-regexp} (a dash-space by default), subsequent -lines are positioned to line up after it, as in the following example. - -@example -@group -;================================= -; x - an array containing -; lots of interesting numbers. -; -; y - another variable where -; a hanging paragraph is used -; to describe it. -;================================= -@end group -@end example - -@kindex M-q -You can also refill a comment at any time paragraph with @kbd{M-q}. -Comment delimiting lines as in the above example, consisting of one or -more @samp{;} followed by one or more of the characters @samp{+=-_*}, -are kept in place, as is. - -@defopt idlwave-fill-comment-line-only (@code{t}) -Non-@code{nil} means auto fill will only operate on comment lines. -@end defopt - -@defopt idlwave-auto-fill-split-string (@code{t}) -Non-@code{nil} means auto fill will split strings with the IDL @samp{+} -operator. -@end defopt - -@defopt idlwave-split-line-string (@code{t}) -Non-@code{nil} means @code{idlwave-split-line} will split strings with -@samp{+}. -@end defopt - -@defopt idlwave-hanging-indent (@code{t}) -Non-@code{nil} means comment paragraphs are indented under the hanging -indent given by @code{idlwave-hang-indent-regexp} match in the first -line of the paragraph. -@end defopt - -@defopt idlwave-hang-indent-regexp (@code{"- "}) -Regular expression matching the position of the hanging indent -in the first line of a comment paragraph. -@end defopt - -@defopt idlwave-use-last-hang-indent (@code{nil}) -Non-@code{nil} means use last match on line for -@code{idlwave-indent-regexp}. -@end defopt - -@node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting -@subsection Syntax Highlighting -@cindex Syntax highlighting -@cindex Highlighting of syntax -@cindex Font lock - -Highlighting of keywords, comments, strings etc. can be accomplished -with @code{font-lock}. If you are using @code{global-font-lock-mode} -(in Emacs), or have @code{font-lock} turned on in any other buffer in -XEmacs, it should also automatically work in IDLWAVE buffers. If you'd -prefer invoking font-lock individually by mode, you can enforce it in -@code{idlwave-mode} with the following line in your @file{.emacs}: - -@lisp -(add-hook 'idlwave-mode-hook 'turn-on-font-lock) -@end lisp - -@noindent IDLWAVE supports 3 increasing levels of syntax highlighting. -The variable @code{font-lock-maximum-decoration} determines which level -is selected. Individual categories of special tokens can be selected -for highlighting using the variable -@code{idlwave-default-font-lock-items}. - -@defopt idlwave-default-font-lock-items -Items which should be fontified on the default fontification level -2. -@end defopt - -@node Octals and Highlighting, , Syntax Highlighting, Code Formatting -@subsection Octals and Highlighting -@cindex Syntax highlighting, Octals -@cindex Highlighting of syntax, Octals - -A rare syntax highlighting problem results from an extremely unfortunate -notation for octal numbers in IDL: @code{"123}. This unpaired quotation -mark is very difficult to parse, given that it can be mixed on a single -line with any number of strings. Emacs will incorrectly identify this -as a string, and the highlighting of following lines of code can be -distorted, since the string is never terminated. - -One solution to this involves terminating the mistakenly identified -string yourself by providing a closing quotation mark in a comment: - -@example - string("305B) + $ ;" <--- for font-lock - ' is an Angstrom.' -@end example - -@noindent A far better solution is to abandon this notation for octals -altogether, and use the more sensible alternative IDL provides: - -@example - string('305'OB) + ' is an Angstrom.' -@end example - -@noindent This simultaneously solves the font-lock problem and is more -consistent with the notation for hexadecimal numbers, e.g. @code{'C5'XB}. - -@node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode -@section Routine Info -@cindex Routine info -@cindex Updating routine info -@cindex Scanning buffers for routine info -@cindex Buffers, scanning for routine info -@cindex Shell, querying for routine info - -@kindex C-c C-i -IDL comes bundled with more than one thousand procedures, functions -and object methods, and large libraries typically contain hundreds or -even thousands more (each with a few to tens of keywords and -arguments). This large command set can make it difficult to remember -the calling sequence and keywords for the routines you use, but -IDLWAVE can help. It builds up routine information from a wide -variety of sources; IDLWAVE in fact knows far more about the -@samp{.pro} routines on your system than IDL itself! It maintains a -list of all built-in routines, with calling sequences and -keywords@footnote{This list is created by scanning the IDL manuals and -might contain (very few) errors. Please report any errors to the -maintainer, so that they can be fixed.}. It also scans Emacs buffers -for routine definitions, queries the IDLWAVE-Shell for information -about routines currently compiled there, and automatically locates -library and user-created catalogs. This information is updated -automatically, and so should usually be current. To force a global -update and refresh the routine information, use @kbd{C-c C-i} -(@code{idlwave-update-routine-info}). - -@kindex C-c ? -To display the information about a routine, press @kbd{C-c ?}, which -calls the command @code{idlwave-routine-info}. When the current cursor -position is on the name or in the argument list of a procedure or -function, information will be displayed about the routine. For example, -consider the indicated cursor positions in the following line: - -@example -plot,x,alog(x+5*sin(x) + 2), - | | | | | | | | - 1 2 3 4 5 6 7 8 -@end example - -@cindex Default routine, for info and help -On positions 1,2 and 8, information about the @samp{plot} procedure will -be shown. On positions 3,4, and 7, the @samp{alog} function will be -described, while positions 5 and 6 will investigate the @samp{sin} -function. - -When you ask for routine information about an object method, and the -method exists in several classes, IDLWAVE queries for the class of the -object, unless the class is already known through a text property on the -@samp{->} operator (@pxref{Object Method Completion and Class -Ambiguity}), or by having been explicitly included in the call -(e.g. @code{a->myclass::Foo}). - -@cindex Calling sequences -@cindex Keywords of a routine -@cindex Routine source information -The description displayed contains the calling sequence, the list of -keywords and the source location of this routine. It looks like this: - -@example -Usage: XMANAGER, NAME, ID -Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER - JUST_REG MODAL NO_BLOCK -Source: SystemLib [LCSB] /soft1/idl53/lib/xmanager.pro -@end example - -@cindex Categories, of routines -@cindex Load-path shadows -@cindex Shadows, load-path -@cindex IDL variable @code{!PATH} -@cindex @code{!PATH}, IDL variable -@cindex IDL variable @code{!DIR} -@cindex @code{!DIR}, IDL variable - -If a definition of this routine exists in several files accessible to -IDLWAVE, several @samp{Source} lines will point to the different -files. This may indicate that your routine is shadowing a system -library routine, which may or may not be what you want -(@pxref{Load-Path Shadows}). The information about the calling -sequence and keywords is derived from the first source listed. -Library routines are available only if you have scanned your local IDL -directories or are using pre-scanned libraries (@pxref{Catalogs}). -The source entry consists of a @emph{source category}, a set of -@emph{flags} and the path to the @emph{source file}. The following -default categories exist: - -@multitable @columnfractions .15 .85 -@item @i{System} -@tab A system routine of unknown origin. When the system library has -been scanned as part of a catalog (@pxref{Catalogs}), this category -will automatically split into the next two. -@item @i{Builtin} -@tab A builtin system routine with no source code available. -@item @i{SystemLib} -@tab A library system routine in the official lib directory @file{!DIR/lib}. -@item @i{Obsolete} -@tab A library routine in the official lib directory @file{!DIR/lib/obsolete}. -@item @i{Library} -@tab A routine in a file on IDL's search path @code{!PATH}. -@item @i{Other} -@tab Any other routine with a file not known to be on the search path. -@item @i{Unresolved} -@tab An otherwise unknown routine the shell lists as unresolved -(referenced, but not compiled). -@end multitable - -Any routines discovered in library catalogs (@pxref{Library -Catalogs}), will display the category assigned during creation, -e.g. @samp{NasaLib}. For routines not discovered in this way, you can -create additional categories based on the routine's filename using the -variable @code{idlwave-special-lib-alist}. - -@cindex Flags, in routine info -@cindex Duplicate routines -@cindex Multiply defined routines -@cindex Routine definitions, multiple -The flags @code{[LCSB]} indicate the source of the information IDLWAVE -has regarding the file: from a library catalog (@w{@code{[L---]}}), -from a user catalog (@w{@code{[-C--]}}, from the IDL Shell -(@w{@code{[--S-]}}) or from an Emacs buffer (@w{@code{[---B]}}). -Combinations are possible (a compiled library routine visited in a -buffer might read @w{@code{[L-SB]}}). If a file contains multiple -definitions of the same routine, the file name will be prefixed with -@samp{(Nx)} where @samp{N} is the number of definitions. - -@cindex Online Help from the routine info buffer -@cindex Active text, in routine info -@cindex Inserting keywords, from routine info -@cindex Source file, access from routine info -Some of the text in the @file{*Help*} routine info buffer will be active -(it is highlighted when the mouse moves over it). Typically, clicking -with the right mouse button invokes online help lookup, and clicking -with the middle mouse button inserts keywords or visits files: - -@multitable @columnfractions 0.15 0.85 -@item @i{Usage} -@tab If online help is installed, a click with the @emph{right} mouse -button on the @i{Usage:} line will access the help for the -routine (@pxref{Online Help}). -@item @i{Keyword} -@tab Online help about keywords is also available with the -@emph{right} mouse button. Clicking on a keyword with the @emph{middle} -mouse button will insert this keyword in the buffer from where -@code{idlwave-routine-info} was called. Holding down @key{SHIFT} while -clicking also adds the initial @samp{/}. -@item @i{Source} -@tab Clicking with the @emph{middle} mouse button on a @samp{Source} line -finds the source file of the routine and visits it in another window. -Another click on the same line switches back to the buffer from which -@kbd{C-c ?} was called. If you use the @emph{right} mouse button, the -source will not be visited by a buffer, but displayed in the online help -window. -@item @i{Classes} -@tab The @i{Classes} line is only included in the routine info window if -the current class inherits from other classes. You can click with the -@emph{middle} mouse button to display routine info about the current -method in other classes on the inheritance chain, if such a method -exists there. -@end multitable - -@defopt idlwave-resize-routine-help-window (@code{t}) -Non-@code{nil} means resize the Routine-info @file{*Help*} window to -fit the content. -@end defopt - -@defopt idlwave-special-lib-alist -Alist of regular expressions matching special library directories. -@end defopt - -@defopt idlwave-rinfo-max-source-lines (@code{5}) -Maximum number of source files displayed in the Routine Info window. -@end defopt - - -@html - -@end html -@node Online Help, Completion, Routine Info, The IDLWAVE Major Mode -@section Online Help - -@cindex Online Help -@cindex @file{idlw-help.txt} -@cindex @file{idlw-help.el} -@cindex Installing online help -@cindex Online Help, Installation -@cindex Speed, of online help -@cindex XML Help Catalog - -For IDL system routines, extensive documentation is supplied with IDL. -IDLWAVE can access the HTML version of this documentation very quickly -and accurately, based on the local context. This can be @emph{much} -faster than using the IDL online help application, because IDLWAVE -usually gets you to the right place in the documentation directly --- -e.g. a specific keyword of a routine --- without any additional browsing -and scrolling. - -For this online help to work, an HTML version of the IDL documentation -is required. Beginning with IDL 6.2, HTML documentation is distributed -directly with IDL, along with an XML-based catalog of routine -information. By default, IDLWAVE automatically attempts to convert this -XML catalog into a format Emacs can more easily understand, and caches -this information in your @code{idlwave_config_directory} -(@file{~/.idlwave/}, by default). It also re-scans the XML catalog if -it is newer than the current cached version. You can force rescan with -the menu entry @code{IDLWAVE->Routine Info->Rescan XML Help Catalog}. - -Before IDL 6.2, the HTML help was not distributed with IDL, and was not -part of the standalone IDLWAVE distribution, but had to be downloaded -separately. This is no longer necessary: all help and routine -information is supplied with IDL versions 6.2 and later. - -There are a variety of options for displaying the HTML help: see below. -Help for routines without HTML documentation is also available, by using -the routine documentation header and/or routine source. - -@kindex M-? -In any IDL program (or, as with most IDLWAVE commands, in the IDL -Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with -@kbd{S-Mouse-3} to access context sensitive online help. The following -locations are recognized context for help: - -@cindex Context, for online help -@multitable @columnfractions .25 .75 -@item @i{Routine names} -@tab The name of a routine (function, procedure, method). -@item @i{Keyword Parameters} -@tab A keyword parameter of a routine. -@item @i{System Variables} -@tab System variables like @code{!DPI}. -@item @i{System Variable Tags} -@tab System variables tags like @code{!D.X_SIZE}. -@item @i{IDL Statements} -@tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc. -@item @i{IDL Controls} -@tab Control structures like @code{FOR}, @code{SWITCH}, etc. -@item @i{Class names} -@tab A class name in an @code{OBJ_NEW} call. -@item @i{Class Init Keywords} -@tab Beyond the class name in an @code{OBJ_NEW} call. -@item @i{Executive Command} -@tab An executive command like @code{.RUN}. Mostly useful in the shell. -@item @i{Structure Tags} -@tab Structure tags like @code{state.xsize} -@item @i{Class Tags} -@tab Class tags like @code{self.value}. -@item @i{Default} -@tab The routine that would be selected for routine info display. -@end multitable - -@cindex @code{OBJ_NEW}, special online help -Note that the @code{OBJ_NEW} function is special in that the help -displayed depends on the cursor position. If the cursor is on the -@samp{OBJ_NEW}, this function is described. If it is on the class -name inside the quotes, the documentation for the class is pulled up. -If the cursor is @emph{after} the class name, anywhere in the argument -list, the documentation for the corresponding @code{Init} method and -its keywords is targeted. - -Apart from an IDLWAVE buffer or shell, there are two more places from -which online help can be accessed. - -@itemize @bullet -@item -Online help for routines and keywords can be accessed through the -Routine Info display. Click with @kbd{Mouse-3} on an item to see the -corresponding help (@pxref{Routine Info}). -@item -When using completion and Emacs pops up a @file{*Completions*} buffer -with possible completions, clicking with @kbd{Mouse-3} on a completion -item invokes help on that item (@pxref{Completion}). Items for which -help is available in the online system documentation (vs. just the -program source itself) will be emphasized (e.g. colored blue). -@end itemize -@noindent -In both cases, a blue face indicates that the item is documented in -the IDL manual, but an attempt will be made to visit non-blue items -directly in the originating source file. - - -@menu -* Help with HTML Documentation:: -* Help with Source:: -@end menu - -@node Help with HTML Documentation, Help with Source, Online Help, Online Help -@subsection Help with HTML Documentation -@cindex HTML Help -@cindex Help using HTML manuals -@cindex IDL manual, HTML version -@cindex IDL Assistant - -Help using the HTML documentation is invoked with the built-in Emacs -command @code{browse-url}, which displays the relevant help topic in a -browser of your choosing. Beginning with version 6.2, IDL comes with -the help browser @emph{IDL Assistant}, which it uses by default for -displaying online help on all supported platforms. This browser -offers topical searches, an index, and is also now the default and -recommended IDLWAVE help browser. The variable -@code{idlwave-help-use-assistant} controls whether this browser is -used. Note that, due to limitations in the Assistant, invoking help -within IDLWAVE and @code{? topic} within IDL will result in two -running copies of Assistant. - -Aside from the IDL Assistant, there are many possible browsers to choose -among, with differing advantages and disadvantages. The variable -@code{idlwave-help-browser-function} controls which browser help is sent -to (as long as @code{idlwave-help-use-assistant} is not set). This -function is used to set the variable @code{browse-url-browser-function} -locally for IDLWAVE help only. Customize the latter variable to see -what choices of browsers your system offers. Certain browsers like -@code{w3} (bundled with many versions of Emacs) and @code{w3m} -(@uref{http://emacs-w3m.namazu.org/}) are run within Emacs, and use -Emacs buffers to display the HTML help. This can be convenient, -especially on small displays, and images can even be displayed in-line -on newer Emacs versions. However, better formatting results are often -achieved with external browsers, like Mozilla. IDLWAVE assumes any -browser function containing "w3" is displayed in a local buffer. If you -are using another Emacs-local browser for which this is not true, set -the variable @code{idlwave-help-browser-is-local}. - -With IDL 6.2 or later, it is important to ensure that the variable -@code{idlwave-system-directory} is set (@pxref{Catalogs}). One easy way -to ensure this is to run the IDL Shell (@kbd{C-c C-s}). It will be -queried for this directory, and the results will be cached to file for -subsequent use. - -@xref{HTML Help Browser Tips}, for more information on selecting and -configuring a browser for use with IDL's HTML help system. - -@defopt idlwave-html-system-help-location @file{help/online_help} -Relative directory of the system-supplied HTML help directory, -considered with respect to @code{idlwave-system-directory}. Relevant -for IDL 6.2 and greater. Should not change. -@end defopt - -@defopt idlwave-html-help-location @file{/usr/local/etc/} -The directory where the @file{idl_html_help} HTML directory live. -Obsolete and ignored for IDL 6.2 and greater -(@code{idlwave-html-system-help-location} is used instead). -@end defopt - -@defopt idlwave-help-use-assistant @code{t} -If set, use the IDL Assistant if possible for online HTML help, -otherwise use the browser function specified in -@code{idlwave-help-browser-function}. -@end defopt - -@defopt idlwave-help-browser-function -The browser function to use to display IDLWAVE HTML help. Should be -one of the functions available for setting -@code{browse-url-browser-function}, which see. -@end defopt - -@defopt idlwave-help-browser-is-local -Is the browser selected in @code{idlwave-help-browser-function} run in a -local Emacs buffer or window? Defaults to @code{t} if the function -contains "-w3". -@end defopt - -@defopt idlwave-help-link-face -The face for links to IDLWAVE online help. -@end defopt - -@node Help with Source, , Help with HTML Documentation, Online Help -@subsection Help with Source -@cindex Help using routine source - -@cindex Source code, as online help -@cindex DocLib header, as online help -For routines which are not documented in an HTML manual (for example -personal or library routines), the source code itself is used as help -text. If the requested information can be found in a (more or less) -standard DocLib file header, IDLWAVE shows the header (scrolling down to -a keyword, if appropriate). Otherwise the routine definition statement -(@code{pro}/@code{function}) is shown. The doclib header sections which -are searched for include @samp{NAME} and @samp{KEYWORDS}. Localization -support can be added by customizing the @code{idlwave-help-doclib-name} -and @code{idlwave-help-doclib-keyword} variables. - -@cindex Structure tags, in online help -@cindex Class tags, in online help -Help is also available for class structure tags (@code{self.TAG}), and -generic structure tags, if structure tag completion is enabled -(@pxref{Structure Tag Completion}). This is implemented by visiting the -tag within the class or structure definition source itself. Help is not -available on built-in system class tags. - -The help window is normally displayed in the same frame, but can be -popped-up in a separate frame. The following commands can be used to -navigate inside the help system for source files: - -@multitable @columnfractions .15 .85 -@item @kbd{@key{SPACE}} -@tab Scroll forward one page. -@item @kbd{@key{RET}} -@tab Scroll forward one line. -@item @kbd{@key{DEL}} -@tab Scroll back one page. -@item @kbd{h} -@tab Jump to DocLib Header of the routine whose source is displayed -as help. -@item @kbd{H} -@tab Jump to the first DocLib Header in the file. -@item @kbd{.} @r{(Dot)} -@tab Jump back and forth between the routine definition (the -@code{pro}/@code{function} statement) and the description of the help -item in the DocLib header. -@item @kbd{F} -@tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}. -@item @kbd{q} -@tab Kill the help window. -@end multitable - - -@defopt idlwave-help-use-dedicated-frame (@code{nil}) -Non-@code{nil} means use a separate frame for Online Help if possible. -@end defopt - -@defopt idlwave-help-frame-parameters -The frame parameters for the special Online Help frame. -@end defopt - -@defopt idlwave-max-popup-menu-items (@code{20}) -Maximum number of items per pane in pop-up menus. -@end defopt - -@defopt idlwave-extra-help-function -Function to call for help if the normal help fails. -@end defopt - -@defopt idlwave-help-fontify-source-code (@code{nil}) -Non-@code{nil} means fontify source code displayed as help. -@end defopt - -@defopt idlwave-help-source-try-header (@code{t}) -Non-@code{nil} means try to find help in routine header when -displaying source file. -@end defopt - -@defopt idlwave-help-doclib-name (@code{"name"}) -The case-insensitive heading word in doclib headers to locate the -@emph{name} section. Can be a regexp, e.g. @code{"\\(name\\|nom\\)"}. -@end defopt - -@defopt idlwave-help-doclib-keyword (@code{"KEYWORD"}) -The case-insensitive heading word in doclib headers to locate the -@emph{keywords} section. Can be a regexp. -@end defopt - - -@node Completion, Routine Source, Online Help, The IDLWAVE Major Mode -@section Completion -@cindex Completion -@cindex Keyword completion -@cindex Method completion -@cindex Object method completion -@cindex Class name completion -@cindex Function name completion -@cindex Procedure name completion - -@kindex M-@key{TAB} -@kindex C-c C-i -IDLWAVE offers completion for class names, routine names, keywords, -system variables, system variable tags, class structure tags, regular -structure tags and file names. As in many programming modes, completion -is bound to @kbd{M-@key{TAB}} (or simply @kbd{@key{TAB}} in the IDLWAVE -Shell --- @pxref{Using the Shell}). Completion uses exactly the same -internal information as routine info, so when necessary (rarely) it can -be updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}). - -The completion function is context sensitive and figures out what to -complete based on the location of the point. Here are example lines and -what @kbd{M-@key{TAB}} would try to complete when the cursor is on the -position marked with a @samp{_}: - -@example -plo_ @r{Procedure} -x = a_ @r{Function} -plot,xra_ @r{Keyword of @code{plot} procedure} -plot,x,y,/x_ @r{Keyword of @code{plot} procedure} -plot,min(_ @r{Keyword of @code{min} function} -obj -> a_ @r{Object method (procedure)} -a[2,3] = obj -> a_ @r{Object method (function)} -x = obj_new('IDL_ @r{Class name} -x = obj_new('MyCl',a_ @r{Keyword to @code{Init} method in class @code{MyCl}} -pro A_ @r{Class name} -pro _ @r{Fill in @code{Class::} of first method in this file} -!v_ @r{System variable} -!version.t_ @r{Structure tag of system variable} -self.g_ @r{Class structure tag in methods} -state.w_ @r{Structure tag, if tag completion enabled} -name = 'a_ @r{File name (default inside quotes)} -@end example - -@cindex Completion, ambiguity -@cindex Completion, forcing function name -The only place where completion is ambiguous is procedure/function -@emph{keywords} versus @emph{functions}. After @samp{plot,x,_}, IDLWAVE -will always assume a keyword to @samp{plot}. However, a function is -also a possible completion here. You can force completion of a function -name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}. - -Giving two prefix arguments (@kbd{C-u C-u M-@key{TAB}}) prompts for a -regular expression to search among the commands to be completed. As -an example, completing a blank line in this way will allow you to -search for a procedure matching a regexp. - -@cindex Scrolling the @file{*Completions*} window -@cindex Completion, scrolling -@cindex Completion, Online Help -@cindex Online Help in @file{*Completions*} buffer -If the list of completions is too long to fit in the -@file{*Completions*} window, the window can be scrolled by pressing -@kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each -possible completion is available by clicking with @kbd{Mouse-3} on the -item. Items for which system online help (from the IDL manual) is -available will be emphasized (e.g. colored blue). For other items, the -corresponding source code or DocLib header will be used as the help -text. - -@cindex Completion, canceling -@cindex Canceling completion -Completion is not a blocking operation --- you are free to continue -editing, enter commands, or simply ignore the @file{*Completions*} -buffer during a completion operation. If, however, the most recent -command was a completion, @kbd{C-g} will remove the buffer and restore -the window configuration. You can also remove the buffer at any time -with no negative consequences. - -@defopt idlwave-keyword-completion-adds-equal (@code{t}) -Non-@code{nil} means completion automatically adds @samp{=} after -completed keywords. -@end defopt - -@defopt idlwave-function-completion-adds-paren (@code{t}) -Non-@code{nil} means completion automatically adds @samp{(} after -completed function. A value of `2' means also add the closing -parenthesis and position the cursor between the two. -@end defopt - -@defopt idlwave-completion-restore-window-configuration (@code{t}) -Non-@code{nil} means restore window configuration after successful -completion. -@end defopt - -@defopt idlwave-highlight-help-links-in-completion (@code{t}) -Non-@code{nil} means highlight completions for which system help is -available. -@end defopt - -@menu -* Case of Completed Words:: CaseOFcomPletedWords -* Object Method Completion and Class Ambiguity:: obj->Method, what? -* Object Method Completion in the Shell:: -* Class and Keyword Inheritance:: obj->Method, _EXTRA=e -* Structure Tag Completion:: Completing state.Tag -@end menu - -@node Case of Completed Words, Object Method Completion and Class Ambiguity, Completion, Completion -@subsection Case of Completed Words -@cindex Case of completed words -@cindex Mixed case completion -IDL is a case-insensitive language, so casing is a matter of style -only. IDLWAVE helps maintain a consistent casing style for completed -items. The case of the completed words is determined by what is -already in the buffer. As an exception, when the partial word being -completed is all lower case, the completion will be lower case as -well. If at least one character is upper case, the string will be -completed in upper case or mixed case, depending on the value of the -variable @code{idlwave-completion-case}. The default is to use upper -case for procedures, functions and keywords, and mixed case for object -class names and methods, similar to the conventions in the IDL -manuals. For instance, to enable mixed-case completion for routines -in addition to classes and methods, you need an entry such as -@code{(routine . preserve)} in that variable. To enable total control -over the case of completed items, independent of buffer context, set -@code{idlwave-completion-force-default-case} to non-@code{nil}. - -@defopt idlwave-completion-case -Association list setting the case (UPPER/lower/Capitalized/MixedCase...) -of completed words. -@end defopt - -@defopt idlwave-completion-force-default-case (@code{nil}) -Non-@code{nil} means completion will always honor the settings in -@code{idlwave-completion-case}. When nil (the default), entirely lower -case strings will always be completed to lower case, no matter what the -settings in @code{idlwave-completion-case}. -@end defopt - -@defopt idlwave-complete-empty-string-as-lower-case (@code{nil}) -Non-@code{nil} means the empty string is considered lower case for -completion. -@end defopt - -@node Object Method Completion and Class Ambiguity, Object Method Completion in the Shell, Case of Completed Words, Completion -@subsection Object Method Completion and Class Ambiguity -@cindex Object methods -@cindex Class ambiguity -@cindex @code{self} object, default class -An object method is not uniquely determined without the object's class. -Since the class is almost always omitted in the calling source (as -required to obtain the true benefits of object-based programming), -IDLWAVE considers all available methods in all classes as possible -method name completions. The combined list of keywords of the current -method in @emph{all} known classes which contain that method will be -considered for keyword completion. In the @file{*Completions*} buffer, -the matching classes will be shown next to each item (see option -@code{idlwave-completion-show-classes}). As a special case, the class -of an object called @samp{self} is always taken to be the class of the -current routine, when in an IDLWAVE buffer. All inherits classes are -considered as well. - -@cindex Forcing class query. -@cindex Class query, forcing -You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u -M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to -narrow down the number of possible completions. The variable -@code{idlwave-query-class} can be configured to make such prompting the -default for all methods (not recommended), or selectively for very -common methods for which the number of completing keywords would be too -large (e.g. @code{Init,SetProperty,GetProperty}). - -@cindex Saving object class on @code{->} -@cindex @code{->} -After you have specified the class for a particular statement (e.g. when -completing the method), IDLWAVE can remember it for the rest of the -editing session. Subsequent completions in the same statement -(e.g. keywords) can then reuse this class information. This works by -placing a text property on the method invocation operator @samp{->}, -after which the operator will be shown in a different face (bold by -default). The variable @code{idlwave-store-inquired-class} can be used -to turn it off or on. - -@defopt idlwave-completion-show-classes (@code{1}) -Non-@code{nil} means show up to that many classes in -@file{*Completions*} buffer when completing object methods and -keywords. -@end defopt - -@defopt idlwave-completion-fontify-classes (@code{t}) -Non-@code{nil} means fontify the classes in completions buffer. -@end defopt - -@defopt idlwave-query-class (@code{nil}) -Association list governing query for object classes during completion. -@end defopt - -@defopt idlwave-store-inquired-class (@code{t}) -Non-@code{nil} means store class of a method call as text property on -@samp{->}. -@end defopt - -@defopt idlwave-class-arrow-face -Face to highlight object operator arrows @samp{->} which carry a saved -class text property. -@end defopt - -@node Object Method Completion in the Shell, Class and Keyword Inheritance, Object Method Completion and Class Ambiguity, Completion -@subsection Object Method Completion in the Shell -@cindex Method Completion in Shell -In the IDLWAVE Shell (@pxref{The IDLWAVE Shell}), objects on which -methods are being invoked have a special property: they must exist as -variables, and so their class can be determined (for instance, using the -@code{obj_class()} function). In the Shell, when attempting completion, -routine info, or online help within a method routine, a query is sent to -determine the class of the object. If this query is successful, the -class found will be used to select appropriate completions, routine -info, or help. If unsuccessful, information from all known classes will -be used (as in the buffer). - -@node Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion -@subsection Class and Keyword Inheritance -@cindex Inheritance, class -@cindex Keyword inheritance -@cindex Inheritance, keyword - -Class inheritance affects which methods are called in IDL. An object of -a class which inherits methods from one or more superclasses can -override that method by defining its own method of the same name, extend -the method by calling the method(s) of its superclass(es) in its -version, or inherit the method directly by making no modifications. -IDLWAVE examines class definitions during completion and routine -information display, and records all inheritance information it finds. -This information is displayed if appropriate with the calling sequence -for methods (@pxref{Routine Info}), as long as variable -@code{idlwave-support-inheritance} is non-@code{nil}. - -In many class methods, @emph{keyword} inheritance (@code{_EXTRA} and -@code{_REF_EXTRA}) is used hand-in-hand with class inheritance and -method overriding. E.g., in a @code{SetProperty} method, this technique -allows a single call @code{obj->SetProperty} to set properties up the -entire class inheritance chain. This is often referred to as -@emph{chaining}, and is characterized by chained method calls like -@w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}. - -IDLWAVE can accommodate this special synergy between class and keyword -inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a -method's keyword parameters, all keywords of superclass versions of -the method being considered can be included in completion. There is -of course no guarantee that this type of keyword chaining actually -occurs, but for some methods it's a very convenient assumption. The -variable @code{idlwave-keyword-class-inheritance} can be used to -configure which methods have keyword inheritance treated in this -simple, class-driven way. By default, only @code{Init} and -@code{(Get|Set)Property} are. The completion buffer will label -keywords based on their originating class. - -@defopt idlwave-support-inheritance (@code{t}) -Non-@code{nil} means consider inheritance during completion, online help etc. -@end defopt - -@defopt idlwave-keyword-class-inheritance -A list of regular expressions to match methods for which simple -class-driven keyword inheritance will be used for Completion. -@end defopt - -@node Structure Tag Completion, , Class and Keyword Inheritance, Completion -@subsection Structure Tag Completion -@cindex Completion, structure tag -@cindex Structure tag completion - -In many programs, especially those involving widgets, large structures -(e.g. the @samp{state} structure) are used to communicate among -routines. It is very convenient to be able to complete structure tags, -in the same way as for instance variables (tags) of the @samp{self} -object (@pxref{Object Method Completion and Class Ambiguity}). Add-in -code for structure tag completion is available in the form of a loadable -completion module: @file{idlw-complete-structtag.el}. Tag completion in -structures is highly ambiguous (much more so than @samp{self} -completion), so @code{idlw-complete-structtag} makes an unusual and very -specific assumption: the exact same variable name is used to refer to -the structure in all parts of the program. This is entirely unenforced -by the IDL language, but is a typical convention. If you consistently -refer to the same structure with the same variable name -(e.g. @samp{state}), structure tags which are read from its definition -in the same file can be used for completion. - -Structure tag completion is not enabled by default. To enable it, -simply add the following to your @file{.emacs}: - -@lisp - (add-hook 'idlwave-load-hook - (lambda () (require 'idlw-complete-structtag))) -@end lisp - -Once enabled, you'll also be able to access online help on the structure -tags, using the usual methods (@pxref{Online Help}). In addition, -structure variables in the shell will be queried for tag names, similar -to the way object variables in the shell are queried for method names. -So, e.g.: - -@example -IDL> st.[Tab] -@end example - -@noindent will complete with all structure fields of the structure -@code{st}. - -@node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode -@section Routine Source -@cindex Routine source file -@cindex Module source file -@cindex Source file, of a routine -@kindex C-c C-v -In addition to clicking on a @i{Source:} line in the routine info -window, there is another way to quickly visit the source file of a -routine. The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks -for a module name, offering the same default as -@code{idlwave-routine-info} would have used, taken from nearby buffer -contents. In the minibuffer, specify a complete routine name (including -any class part). IDLWAVE will display the source file in another -window, positioned at the routine in question. You can also limit this -to a routine in the current buffer only, with completion, and a -context-sensitive default, by using a single prefix (@kbd{C-u C-c C-v}) -or the convenience binding @kbd{C-c C-t}. - -@cindex Buffers, killing -@cindex Killing autoloaded buffers -Since getting the source of a routine into a buffer is so easy with -IDLWAVE, too many buffers visiting different IDL source files are -sometimes created. The special command @kbd{C-c C-k} -(@code{idlwave-kill-autoloaded-buffers}) can be used to easily remove -these buffers. - -@node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode -@section Resolving Routines -@cindex @code{RESOLVE_ROUTINE} -@cindex Compiling library modules -@cindex Routines, resolving - -The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve} -and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL -in order to resolve (compile) it. The default routine to be resolved is -taken from context, but you get a chance to edit it. Usually this is -not necessary, since IDL automatically discovers routines on its path. - -@code{idlwave-resolve} is one way to get a library module within reach -of IDLWAVE's routine info collecting functions. A better way is to -keep routine information available in catalogs (@pxref{Catalogs}). -Routine info on modules will then be available without the need to -compile the modules first, and even without a running shell. - -@xref{Sources of Routine Info}, for more information on the ways IDLWAVE -collects data about routines, and how to update this information. - -@node Code Templates, Abbreviations, Resolving Routines, The IDLWAVE Major Mode -@section Code Templates -@cindex Code templates -@cindex Templates - -IDLWAVE can insert IDL code templates into the buffer. For a few -templates, this is done with direct key bindings: - -@multitable @columnfractions .15 .85 -@item @kbd{C-c C-c} -@tab @code{CASE} statement template -@item @kbd{C-c C-f} -@tab @code{FOR} loop template -@item @kbd{C-c C-r} -@tab @code{REPEAT} loop template -@item @kbd{C-c C-w} -@tab @code{WHILE} loop template -@end multitable - -All code templates are also available as abbreviations -(@pxref{Abbreviations}). - -@node Abbreviations, Actions, Code Templates, The IDLWAVE Major Mode -@section Abbreviations -@cindex Abbreviations - -Special abbreviations exist to enable rapid entry of commonly used -commands. Emacs abbreviations are expanded by typing text into the -buffer and pressing @key{SPC} or @key{RET}. The special abbreviations -used to insert code templates all start with a @samp{\} (the backslash), -or, optionally, any other character set in -@code{idlwave-abbrev-start-char}. IDLWAVE ensures that abbreviations are -only expanded where they should be (i.e., not in a string or comment), -and permits the point to be moved after an abbreviation expansion --- -very useful for positioning the mark inside of parentheses, etc. - -Special abbreviations are pre-defined for code templates and other -useful items. To visit the full list of abbreviations, use @kbd{M-x -idlwave-list-abbrevs}. - -Template abbreviations: - -@multitable @columnfractions .15 .85 -@item @code{\pr} -@tab @code{PROCEDURE} template -@item @code{\fu} -@tab @code{FUNCTION} template -@item @code{\c} -@tab @code{CASE} statement template -@item @code{\f} -@tab @code{FOR} loop template -@item @code{\r} -@tab @code{REPEAT} loop template -@item @code{\w} -@tab @code{WHILE} loop template -@item @code{\i} -@tab @code{IF} statement template -@item @code{\elif} -@tab @code{IF-ELSE} statement template -@end multitable - -String abbreviations: - -@multitable @columnfractions .15 .85 -@item @code{\ap} -@tab @code{arg_present()} -@item @code{\b} -@tab @code{begin} -@item @code{\cb} -@tab @code{byte()} -@item @code{\cc} -@tab @code{complex()} -@item @code{\cd} -@tab @code{double()} -@item @code{\cf} -@tab @code{float()} -@item @code{\cl} -@tab @code{long()} -@item @code{\co} -@tab @code{common} -@item @code{\cs} -@tab @code{string()} -@item @code{\cx} -@tab @code{fix()} -@item @code{\e} -@tab @code{else} -@item @code{\ec} -@tab @code{endcase} -@item @code{\ee} -@tab @code{endelse} -@item @code{\ef} -@tab @code{endfor} -@item @code{\ei} -@tab @code{endif else if} -@item @code{\el} -@tab @code{endif else} -@item @code{\en} -@tab @code{endif} -@item @code{\er} -@tab @code{endrep} -@item @code{\es} -@tab @code{endswitch} -@item @code{\ew} -@tab @code{endwhile} -@item @code{\g} -@tab @code{goto,} -@item @code{\h} -@tab @code{help,} -@item @code{\ik} -@tab @code{if keyword_set() then} -@item @code{\iap} -@tab @code{if arg_present() then} -@item @code{\ine} -@tab @code{if n_elements() eq 0 then} -@item @code{\inn} -@tab @code{if n_elements() ne 0 then} -@item @code{\k} -@tab @code{keyword_set()} -@item @code{\n} -@tab @code{n_elements()} -@item @code{\np} -@tab @code{n_params()} -@item @code{\oi} -@tab @code{on_ioerror,} -@item @code{\or} -@tab @code{openr,} -@item @code{\ou} -@tab @code{openu,} -@item @code{\ow} -@tab @code{openw,} -@item @code{\p} -@tab @code{print,} -@item @code{\pt} -@tab @code{plot,} -@item @code{\pv} -@tab @code{ptr_valid()} -@item @code{\re} -@tab @code{read,} -@item @code{\rf} -@tab @code{readf,} -@item @code{\rt} -@tab @code{return} -@item @code{\ru} -@tab @code{readu,} -@item @code{\s} -@tab @code{size()} -@item @code{\sc} -@tab @code{strcompress()} -@item @code{\sl} -@tab @code{strlowcase()} -@item @code{\sm} -@tab @code{strmid()} -@item @code{\sn} -@tab @code{strlen()} -@item @code{\sp} -@tab @code{strpos()} -@item @code{\sr} -@tab @code{strtrim()} -@item @code{\st} -@tab @code{strput()} -@item @code{\su} -@tab @code{strupcase()} -@item @code{\t} -@tab @code{then} -@item @code{\u} -@tab @code{until} -@item @code{\wc} -@tab @code{widget_control,} -@item @code{\wi} -@tab @code{widget_info()} -@item @code{\wu} -@tab @code{writeu,} -@end multitable - -@noindent You can easily add your own abbreviations or override existing -abbrevs with @code{define-abbrev} in your mode hook, using the -convenience function @code{idlwave-define-abbrev}: - -@lisp -(add-hook 'idlwave-mode-hook - (lambda () - (idlwave-define-abbrev "wb" "widget_base()" - (idlwave-keyword-abbrev 1)) - (idlwave-define-abbrev "ine" "IF N_Elements() EQ 0 THEN" - (idlwave-keyword-abbrev 11)))) -@end lisp - -Notice how the abbreviation (here @emph{wb}) and its expansion -(@emph{widget_base()}) are given as arguments, and the single argument to -@code{idlwave-keyword-abbrev} (here @emph{1}) specifies how far back to -move the point upon expansion (in this example, to put it between the -parentheses). - -The abbreviations are expanded in upper or lower case, depending upon -the variables @code{idlwave-abbrev-change-case} and, for reserved word -templates, @code{idlwave-reserved-word-upcase} (@pxref{Case Changes}). - -@defopt idlwave-abbrev-start-char (@code{"\"}) -A single character string used to start abbreviations in abbrev mode. -Beware of common characters which might naturally occur in sequence with -abbreviation strings. -@end defopt - -@defopt idlwave-abbrev-move (@code{t}) -Non-@code{nil} means the abbrev hook can move point, e.g. to end up -between the parentheses of a function call. -@end defopt - -@node Actions, Doc Header, Abbreviations, The IDLWAVE Major Mode -@section Actions -@cindex Actions -@cindex Coding standards, enforcing - -@emph{Actions} are special formatting commands which are executed -automatically while you write code in order to check the structure of -the program or to enforce coding standards. Most actions which have -been implemented in IDLWAVE are turned off by default, assuming that the -average user wants her code the way she writes it. But if you are a -lazy typist and want your code to adhere to certain standards, actions -can be helpful. - -Actions can be applied in three ways: - -@itemize @bullet -@item -Some actions are applied directly while typing. For example, pressing -@samp{=} can run a check to make sure that this operator is surrounded -by spaces and insert these spaces if necessary. Pressing @key{SPC} -after a reserved word can call a command to change the word to upper -case. -@item -When a line is re-indented with @key{TAB}, actions can be applied to the -entire line. To enable this, the variable @code{idlwave-do-actions} -must be non-@code{nil}. -@item -@cindex Foreign code, adapting -@cindex Actions, applied to foreign code -Actions can also be applied to a larger piece of code, e.g. to convert -foreign code to your own style. To do this, mark the relevant part of -the code and execute @kbd{M-x expand-region-abbrevs}. Useful marking -commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current -subprogram). @xref{Code Indentation}, for information how to adjust the -indentation of the code. -@end itemize - -@defopt idlwave-do-actions (@code{nil}) -Non-@code{nil} means performs actions when indenting. Individual action -settings are described below and set separately. -@end defopt - -@menu -* Block Boundary Check:: Is the END statement correct? -* Padding Operators:: Enforcing space around `=' etc -* Case Changes:: Enforcing upper case keywords -@end menu - -@node Block Boundary Check, Padding Operators, Actions, Actions -@subsection Block Boundary Check -@cindex Block boundary check -@cindex @code{END} type checking -@cindex @code{END}, automatic insertion -@cindex @code{END}, expanding -@cindex Block, closing -@cindex Closing a block - -Whenever you type an @code{END} statement, IDLWAVE finds the -corresponding start of the block and the cursor blinks back to that -location for a second. If you have typed a specific @code{END}, like -@code{ENDIF} or @code{ENDCASE}, you get a warning if that terminator -does not match the type of block it terminates. - -Set the variable @code{idlwave-expand-generic-end} in order to have all -generic @code{END} statements automatically expanded to the appropriate -type. You can also type @kbd{C-c ]} to close the current block by -inserting the appropriate @code{END} statement. - -@defopt idlwave-show-block (@code{t}) -Non-@code{nil} means point blinks to block beginning for -@code{idlwave-show-begin}. -@end defopt - -@defopt idlwave-expand-generic-end (@code{t}) -Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc. -@end defopt - -@defopt idlwave-reindent-end (@code{t}) -Non-@code{nil} means re-indent line after END was typed. -@end defopt - -@node Padding Operators, Case Changes, Block Boundary Check, Actions -@subsection Padding Operators -@cindex Padding operators with spaces -@cindex Operators, padding with spaces -@cindex Space, around operators - -Some operators can be automatically surrounded by spaces. This can -happen when the operator is typed, or later when the line is indented. -IDLWAVE can pad the operators @samp{<}, @samp{>}, @samp{,}, @samp{=}, -and @samp{->}, as well as the modified assignment operators -(@samp{AND=}, @samp{OR=}, etc.). This feature is turned off by default. -If you want to turn it on, customize the variables -@code{idlwave-surround-by-blank} and @code{idlwave-do-actions} and turn -both on. You can also define similar actions for other operators by -using the function @code{idlwave-action-and-binding} in the mode hook. -For example, to enforce space padding of the @samp{+} and @samp{*} -operators (outside of strings and comments, of course), try this in -@file{.emacs} - -@lisp -(add-hook 'idlwave-mode-hook - (lambda () - (setq idlwave-surround-by-blank t) ; Turn this type of actions on - (idlwave-action-and-binding "*" '(idlwave-surround 1 1)) - (idlwave-action-and-binding "+" '(idlwave-surround 1 1)))) -@end lisp - -Note that the modified assignment operators which begin with a word -(@samp{AND=}, @samp{OR=}, @samp{NOT=}, etc.) require a leading space to -be recognized (e.g @code{vAND=4} would be interpreted as a variable -@code{vAND}). Also note that, since e.g., @code{>} and @code{>=} are -both valid operators, it is impossible to surround both by blanks while -they are being typed. Similarly with @code{&} and @code{&&}. For -these, a compromise is made: the padding is placed on the left, and if -the longer operator is keyed in, on the right as well (otherwise you -must insert spaces to pad right yourself, or press simply press Tab to -repad everything if @code{idlwave-do-actions} is on). - -@defopt idlwave-surround-by-blank (@code{nil}) -Non-@code{nil} means enable @code{idlwave-surround}. If non-@code{nil}, -@samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->}, and the -modified assignment operators (@samp{AND=}, @samp{OR=}, etc.) are -surrounded with spaces by @code{idlwave-surround}. -@end defopt - -@defopt idlwave-pad-keyword (@code{t}) -Non-@code{nil} means space-pad the @samp{=} in keyword assignments. -@end defopt - -@node Case Changes, , Padding Operators, Actions -@subsection Case Changes -@cindex Case changes -@cindex Upcase, enforcing for reserved words -@cindex Downcase, enforcing for reserved words - -Actions can be used to change the case of reserved words or expanded -abbreviations by customizing the variables -@code{idlwave-abbrev-change-case} and -@code{idlwave-reserved-word-upcase}. If you want to change the case of -additional words automatically, put something like the following into -your @file{.emacs} file: - -@lisp -(add-hook 'idlwave-mode-hook - (lambda () - ;; Capitalize system vars - (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t) - ;; Capitalize procedure name - (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" - '(capitalize-word 1) t) - ;; Capitalize common block name - (idlwave-action-and-binding "\\[ \t]+\\<" - '(capitalize-word 1) t))) -@end lisp - -For more information, see the documentation string for the function -@code{idlwave-action-and-binding}. For information on controlling the -case of routines, keywords, classes, and methods as they are completed, see -@ref{Completion}. - -@defopt idlwave-abbrev-change-case (@code{nil}) -Non-@code{nil} means all abbrevs will be forced to either upper or lower -case. Valid values are @code{nil}, @code{t}, and @code{down}. -@end defopt - -@defopt idlwave-reserved-word-upcase (@code{nil}) -Non-@code{nil} means reserved words will be made upper case via abbrev -expansion. -@end defopt - - -@node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode -@section Documentation Header -@cindex Documentation header -@cindex DocLib header -@cindex Modification timestamp -@cindex Header, for file documentation -@cindex Timestamp, in doc header. -@cindex Changelog, in doc header. - -@kindex C-c C-h -@kindex C-c C-m -The command @kbd{C-c C-h} inserts a standard routine header into the -buffer, with the usual fields for documentation (a different header can -be specified with @code{idlwave-file-header}). One of the keywords is -@samp{MODIFICATION HISTORY} under which the changes to a routine can be -recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION -HISTORY} of the current routine or file and inserts the user name with a -timestamp. - -@defopt idlwave-file-header -The doc-header template or a path to a file containing it. -@end defopt - -@defopt idlwave-header-to-beginning-of-file (@code{nil}) -Non-@code{nil} means the documentation header will always be at start -of file. -@end defopt - -@defopt idlwave-timestamp-hook -The hook function used to update the timestamp of a function. -@end defopt - -@defopt idlwave-doc-modifications-keyword -The modifications keyword to use with the log documentation commands. -@end defopt - -@defopt idlwave-doclib-start -Regexp matching the start of a document library header. -@end defopt - -@defopt idlwave-doclib-end -Regexp matching the start of a document library header. -@end defopt - -@node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode -@section Motion Commands -@cindex Motion commands -@cindex Program structure, moving through -@cindex Code structure, moving through -@cindex @file{Func-menu}, XEmacs package -@cindex @file{Imenu}, Emacs package -@cindex Function definitions, jumping to -@cindex Procedure definitions, jumping to - -IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages -which make it easy to jump to the definitions of functions and -procedures in the current file with a pop-up selection. To bind -@file{Imenu} to a mouse-press, use in your @file{.emacs}: - -@lisp -(define-key global-map [S-down-mouse-3] 'imenu) -@end lisp - -@cindex @file{Speedbar}, Emacs package - -In addition, @file{Speedbar} support allows convenient navigation of a -source tree of IDL routine files, quickly stepping to routine -definitions. See @code{Tools->Display Speedbar}. - -Several commands allow you to move quickly through the structure of an -IDL program: - -@multitable @columnfractions .15 .85 -@item @kbd{C-M-a} -@tab Beginning of subprogram -@item @kbd{C-M-e} -@tab End of subprogram -@item @kbd{C-c @{} -@tab Beginning of block (stay inside the block) -@item @kbd{C-c @}} -@tab End of block (stay inside the block) -@item @kbd{C-M-n} -@tab Forward block (on same level) -@item @kbd{C-M-p} -@tab Backward block (on same level) -@item @kbd{C-M-d} -@tab Down block (enters a block) -@item @kbd{C-M-u} -@tab Backward up block (leaves a block) -@item @kbd{C-c C-n} -@tab Next Statement -@end multitable - - -@node Misc Options, , Motion Commands, The IDLWAVE Major Mode -@section Miscellaneous Options -@cindex Hooks - -@defopt idlwave-help-application -The external application providing reference help for programming. -@end defopt - -@defopt idlwave-startup-message (@code{t}) -Non-@code{nil} means display a startup message when @code{idlwave-mode}' -is first called. -@end defopt - -@defopt idlwave-mode-hook -Normal hook. Executed when a buffer is put into @code{idlwave-mode}. -@end defopt - -@defopt idlwave-load-hook -Normal hook. Executed when @file{idlwave.el} is loaded. -@end defopt - -@node The IDLWAVE Shell, Acknowledgements, The IDLWAVE Major Mode, Top -@chapter The IDLWAVE Shell -@cindex IDLWAVE shell -@cindex Major mode, @code{idlwave-shell-mode} -@cindex IDL, as Emacs subprocess -@cindex Subprocess of Emacs, IDL -@cindex Comint, Emacs package -@cindex Windows -@cindex MacOS - -The IDLWAVE shell is an Emacs major mode which permits running the IDL -program as an inferior process of Emacs, and works closely with the -IDLWAVE major mode in buffers. It can be used to work with IDL -interactively, to compile and run IDL programs in Emacs buffers and to -debug these programs. The IDLWAVE shell is built on @file{comint}, an -Emacs packages which handles the communication with the IDL program. -Unfortunately, IDL for Windows does not have command-prompt versions and -thus do not allow the interaction with Emacs --- so the IDLWAVE shell -currently only works under Unix and MacOSX. - -@menu -* Starting the Shell:: How to launch IDL as a subprocess -* Using the Shell:: Interactively working with the Shell -* Commands Sent to the Shell:: -* Debugging IDL Programs:: -* Examining Variables:: -* Custom Expression Examination:: -@end menu - -@node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell -@section Starting the Shell -@cindex Starting the shell -@cindex Shell, starting -@cindex Dedicated frame, for shell buffer -@cindex Frame, for shell buffer -@cindex Subprocess of Emacs, IDL - -@kindex C-c C-s -The IDLWAVE shell can be started with the command @kbd{M-x -idlwave-shell}. In @code{idlwave-mode} the function is bound to -@kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to -interact with the shell. If the shell is already running, @kbd{C-c -C-s} will simply switch to the shell buffer. The command @kbd{C-c -C-l} (@code{idlwave-shell-recenter-shell-window}) displays the shell -window without selecting it. The shell can also be started -automatically when another command tries to send a command to it. To -enable auto start, set the variable -@code{idlwave-shell-automatic-start} to @code{t}. - -In order to create a separate frame for the IDLWAVE shell buffer, call -@code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or -@kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell -window, configure the variable -@code{idlwave-shell-use-dedicated-frame}. - -To launch a quick IDLWAVE shell directly from a shell prompt without -an IDLWAVE buffer (e.g., as a replacement for running inside an -xterm), define a system alias with the following content: - -@example -emacs -geometry 80x32 -eval "(idlwave-shell 'quick)" -@end example - -Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer -the Emacs process to run directly inside the terminal window. - -@cindex ENVI -@cindex IDL> Prompt - -To use IDLWAVE with ENVI or other custom packages which change the -@samp{IDL> } prompt, you must change the -@code{idlwave-shell-prompt-pattern}, which defaults to @samp{"^ ?IDL> -"}. Normally, you can just replace the @samp{IDL} in this expression -with the prompt you see. A suitable pattern which matches the prompt -for both ENVI and IDL simultaneously is @samp{"^ ?\\(ENVI\\|IDL\\)> "}. - -@defopt idlwave-shell-explicit-file-name (@file{idl}) -This is the command to run IDL. -@end defopt - -@defopt idlwave-shell-command-line-options -A list of command line options for calling the IDL program. -@end defopt - -@defopt idlwave-shell-prompt-pattern -Regexp to match IDL prompt at beginning of a line. -@end defopt - -@defopt idlwave-shell-process-name -Name to be associated with the IDL process. -@end defopt - -@defopt idlwave-shell-automatic-start (@code{nil}) -Non-@code{nil} means attempt to invoke idlwave-shell if not already -running. -@end defopt - -@defopt idlwave-shell-initial-commands -Initial commands, separated by newlines, to send to IDL. -@end defopt - -@defopt idlwave-shell-save-command-history (@code{t}) -Non-@code{nil} means preserve command history between sessions. -@end defopt - -@defopt idlwave-shell-command-history-file (@file{~/.idlwave/.idlwhist}) -The file in which the command history of the idlwave shell is saved. -Unless it's an absolute path, it goes in -@code{idlwave-config-directory}. -@end defopt - -@defopt idlwave-shell-use-dedicated-frame (@code{nil}) -Non-@code{nil} means IDLWAVE should use a special frame to display the -shell buffer. -@end defopt - -@defopt idlwave-shell-use-dedicated-window (@code{nil}) -Non-@code{nil} means use a dedicated window for the shell, taking care -not it replace it with other buffers. -@end defopt - -@defopt idlwave-shell-frame-parameters -The frame parameters for a dedicated idlwave-shell frame. -@end defopt - -@defopt idlwave-shell-raise-frame (@code{t}) -Non-@code{nil} means `idlwave-shell' raises the frame showing the shell -window. -@end defopt - -@defopt idlwave-shell-temp-pro-prefix -The prefix for temporary IDL files used when compiling regions. -@end defopt - -@cindex Hooks -@defopt idlwave-shell-mode-hook -Hook for customizing @code{idlwave-shell-mode}. -@end defopt - -@node Using the Shell, Commands Sent to the Shell, Starting the Shell, The IDLWAVE Shell -@section Using the Shell -@cindex Comint -@cindex Shell, basic commands - -The IDLWAVE shell works in the same fashion as other shell modes in -Emacs. It provides command history, command line editing and job -control. The @key{UP} and @key{DOWN} arrows cycle through the input -history just like in an X terminal@footnote{This is different from -normal Emacs/Comint behavior, but more like an xterm. If you prefer the -default comint functionality, check the variable -@code{idlwave-shell-arrows-do-history}.}. The history is preserved -between emacs and IDL sessions. Here is a list of commonly used -commands: - -@multitable @columnfractions .12 .88 -@item @key{UP}, @key{M-p} -@tab Cycle backwards in input history -@item @key{DOWN}, @key{M-n} -@tab Cycle forwards in input history -@item @kbd{M-r} -@tab Previous input matching a regexp -@item @kbd{M-s} -@tab Next input matching a regexp -@item @kbd{return} -@tab Send input or copy line to current prompt -@item @kbd{C-c C-a} -@tab Beginning of line; skip prompt -@item @kbd{C-c C-u} -@tab Kill input to beginning of line -@item @kbd{C-c C-w} -@tab Kill word before cursor -@item @kbd{C-c C-c} -@tab Send ^C -@item @kbd{C-c C-z} -@tab Send ^Z -@item @kbd{C-c C-\} -@tab Send ^\ -@item @kbd{C-c C-o} -@tab Delete last batch of process output -@item @kbd{C-c C-r} -@tab Show last batch of process output -@item @kbd{C-c C-l} -@tab List input history -@end multitable - -In addition to these standard @file{comint} commands, -@code{idlwave-shell-mode} provides many of the same commands which -simplify writing IDL code available in IDLWAVE buffers. This includes -abbreviations, online help, and completion. See @ref{Routine Info} and -@ref{Online Help} and @ref{Completion} for more information on these -commands. - -@cindex Completion, in the shell -@cindex Routine info, in the shell -@cindex Online Help, in the shell -@multitable @columnfractions .12 .88 -@item @kbd{@key{TAB}} -@tab Completion of file names (between quotes and after executive -commands @samp{.run} and @samp{.compile}), routine names, class names, -keywords, system variables, system variable tags etc. -(@code{idlwave-shell-complete}). -@item @kbd{M-@key{TAB}} -@tab Same as @key{TAB} -@item @kbd{C-c ?} -@tab Routine Info display (@code{idlwave-routine-info}) -@item @kbd{M-?} -@tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp}) -@item @kbd{C-c C-i} -@tab Update routine info from buffers and shell -(@code{idlwave-update-routine-info}) -@item @kbd{C-c C-v} -@tab Find the source file of a routine (@code{idlwave-find-module}) -@item @kbd{C-c C-t} -@tab Find the source file of a routine in the currently visited file -(@code{idlwave-find-module-this-file}). -@item @kbd{C-c =} -@tab Compile a library routine (@code{idlwave-resolve}) -@end multitable - -@defopt idlwave-shell-arrows-do-history (@code{t}) -Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command -history like xterm. -@end defopt - -@defopt idlwave-shell-comint-settings -Alist of special settings for the comint variables in the IDLWAVE Shell. -@end defopt - -@defopt idlwave-shell-file-name-chars -The characters allowed in file names, as a string. Used for file name -completion. -@end defopt - -@defopt idlwave-shell-graphics-window-size -Size of IDL graphics windows popped up by special IDLWAVE command. -@end defopt - -@cindex Input mode -@cindex Character input mode (Shell) -@cindex Line input mode (Shell) -@cindex Magic spells, for input mode -@cindex Spells, magic -IDLWAVE works in line input mode: You compose a full command line, using -all the power Emacs gives you to do this. When you press @key{RET}, the -whole line is sent to IDL. Sometimes it is necessary to send single -characters (without a newline), for example when an IDL program is -waiting for single character input with the @code{GET_KBRD} function. -You can send a single character to IDL with the command @kbd{C-c C-x} -(@code{idlwave-shell-send-char}). When you press @kbd{C-c C-y} -(@code{idlwave-shell-char-mode-loop}), IDLWAVE runs a blocking loop -which accepts characters and immediately sends them to IDL. The loop -can be exited with @kbd{C-g}. It terminates also automatically when the -current IDL command is finished. Check the documentation of the two -variables described below for a way to make IDL programs trigger -automatic switches of the input mode. - -@defopt idlwave-shell-use-input-mode-magic (@code{nil}) -Non-@code{nil} means IDLWAVE should check for input mode spells in -output. -@end defopt - -@defopt idlwave-shell-input-mode-spells -The three regular expressions which match the magic spells for input -modes. -@end defopt - -@node Commands Sent to the Shell, Debugging IDL Programs, Using the Shell, The IDLWAVE Shell -@section Commands Sent to the Shell -@cindex Commands in shell, showing -@cindex Showing commands in shell - -The IDLWAVE buffers and shell interact very closely. In addition to the -normal commands you enter at the @code{IDL>} prompt, many other special -commands are sent to the shell, sometimes as a direct result of invoking -a key command, menu item, or toolbar button, but also automatically, as -part of the normal flow of information updates between the buffer and -shell. - -The commands sent include @code{breakpoint}, @code{.step} and other -debug commands (@pxref{Debugging IDL Programs}), @code{.run} and other -compilation statements (@pxref{Compiling Programs}), examination -commands like @code{print} and @code{help} (@pxref{Examining -Variables}), and other special purpose commands designed to keep -information on the running shell current. - -By default, much of this background shell input and output is hidden -from the user, but this is configurable. The custom variable -@code{idlwave-abbrev-show-commands} allows you to configure which -commands sent to the shell are shown there. For a related customization -for separating the output of @emph{examine} commands, see @ref{Examining -Variables}. - -@defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)}) -A list of command types to echo in the shell when sent. Possible values -are @code{run} for @code{.run}, @code{.compile} and other run commands, -@code{misc} for lesser used commands like @code{window}, -@code{retall},@code{close}, etc., @code{breakpoint} for breakpoint -setting and clearing commands, and @code{debug} for other debug, -stepping, and continue commands. In addition, if the variable is set to -the single symbol @code{'everything}, all the copious shell input is -displayed (which is probably only useful for debugging purposes). -N.B. For hidden commands which produce output by side-effect, that -output remains hidden (e.g., stepping through a @code{print} command). -As a special case, any error message in the output will be displayed -(e.g., stepping to an error). -@end defopt - -@node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell -@section Debugging IDL Programs -@cindex Debugging -@cindex Keybindings for debugging -@cindex Toolbar - -Programs can be compiled, run, and debugged directly from the source -buffer in Emacs, walking through arbitrarily deeply nested code, -printing expressions and skipping up and down the calling stack along -the way. IDLWAVE makes compiling and debugging IDL programs far less -cumbersome by providing a full-featured, key/menu/toolbar-driven -interface to commands like @code{breakpoint}, @code{.step}, -@code{.run}, etc. It can even perform complex debug operations not -natively supported by IDL (like continuing to the line at the cursor). - -The IDLWAVE shell installs key bindings both in the shell buffer and -in all IDL code buffers of the current Emacs session, so debug -commands work in both places (in the shell, commands operate on the -last file compiled). On Emacs versions which support it, a debugging -toolbar is also installed. The toolbar display can be toggled with -@kbd{C-c C-d C-t} (@code{idlwave-shell-toggle-toolbar}). - - -@defopt idlwave-shell-use-toolbar (@code{t}) -Non-@code{nil} means use the debugging toolbar in all IDL related -buffers. -@end defopt - -@menu -* A Tale of Two Modes:: -* Debug Key Bindings:: -* Breakpoints and Stepping:: -* Compiling Programs:: -* Walking the Calling Stack:: -* Electric Debug Mode:: -@end menu - - -@node A Tale of Two Modes, Debug Key Bindings, Debugging IDL Programs, Debugging IDL Programs -@subsection A Tale of Two Modes -@cindex Electric Debug Mode -@cindex Debugging Interface - -The many debugging, compiling, and examination commands provided in -IDLWAVE are available simultaneously through two different interfaces: -the original, multi-key command interface, and the new Electric Debug -Mode. The functionality they offer is similar, but the way you interact -with them is quite different. The main difference is that, in Electric -Debug Mode, the source buffers are made read-only, and single -key-strokes are used to step through, examine expressions, set and -remove breakpoints, etc. The same variables, prefix arguments, and -settings apply to both versions, and both can be used interchangeably. -By default, when breakpoints are hit, Electric Debug Mode is enabled. -The traditional interface is described first. @xref{Electric Debug -Mode}, for more on that mode. Note that electric debug mode can be -prevented from activating automatically by customizing the variable -@code{idlwave-shell-automatic-electric-debug}. - -@node Debug Key Bindings, Breakpoints and Stepping, A Tale of Two Modes, Debugging IDL Programs -@subsection Debug Key Bindings -@kindex C-c C-d -@cindex Key bindings - -The standard debugging key bindings are always available by default on -the prefix key @kbd{C-c C-d}, so, for example, setting a breakpoint is -done with @kbd{C-c C-d C-b}, and compiling a source file with @kbd{C-c -C-d C-c}. You can also easily configure IDLWAVE to use one or more -modifier keys not in use by other commands, in lieu of the prefix -@kbd{C-c C-d} (though these bindings will typically also be available ---- see @code{idlwave-shell-activate-prefix-keybindings}). For -example, if you include in @file{.emacs}: - -@lisp -(setq idlwave-shell-debug-modifiers '(control shift)) -@end lisp - -@noindent a breakpoint can then be set by pressing @kbd{b} while holding down -@kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a -source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d}, -etc. In the remainder of this chapter we will assume that the -@kbd{C-c C-d} bindings are active, but each of these bindings will -have an equivalent shortcut if modifiers are given in the -@code{idlwave-shell-debug-modifiers} variable (@pxref{Lesson II -- -Customization}). A much simpler and faster form of debugging for -running code is also available by default --- see @ref{Electric Debug -Mode}. - -@defopt idlwave-shell-prefix-key (@kbd{C-c C-d}) -The prefix key for the debugging map -@code{idlwave-shell-mode-prefix-map}. -@end defopt - -@defopt idlwave-shell-activate-prefix-keybindings (@code{t}) -Non-@code{nil} means debug commands will be bound to the prefix -key, like @kbd{C-c C-d C-b}. -@end defopt - -@defopt idlwave-shell-debug-modifiers (@code{nil}) -List of modifier keys to use for additional, alternative binding of -debugging commands in the shell and source buffers. Can be one or -more of @code{control}, @code{meta}, @code{super}, @code{hyper}, -@code{alt}, and @code{shift}. -@end defopt - -@node Breakpoints and Stepping, Compiling Programs, Debug Key Bindings, Debugging IDL Programs -@subsection Breakpoints and Stepping -@cindex Breakpoints -@cindex Stepping -@cindex Execution, controlled - -@kindex C-c C-d C-b -@kindex C-c C-d C-b -IDLWAVE helps you set breakpoints and step through code. Setting a -breakpoint in the current line of the source buffer is accomplished -with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a -prefix arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a -@code{/ONCE} keyword, meaning that it will be deleted after first use. -With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}), -the breakpoint will only be active the @code{nth} time it is hit. -With a single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt -for a condition --- an IDL expression to be evaluated and trigger the -breakpoint only if true. To clear the breakpoint in the current line, -use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When -executed from the shell window, the breakpoint where IDL is currently -stopped will be deleted. To clear all breakpoints, use @kbd{C-c C-d -C-a} (@code{idlwave-clear-all-bp}). Breakpoints can also be disabled -and re-enabled: @kbd{C-c C-d C-\} -(@code{idlwave-shell-toggle-enable-current-bp}). - -Breakpoint lines are highlighted or indicated with an icon in the source -code (different icons for conditional, after, and other break types). -Disabled breakpoints are @emph{grayed out} by default. Note that IDL -places breakpoints as close as possible on or after the line you -specify. IDLWAVE queries the shell for the actual breakpoint location -which was set, so the exact line you specify may not be marked. You can -re-sync the breakpoint list and update the display at any time (e.g., if -you add or remove some on the command line) using @kbd{C-c C-d C-l}. - -In recent IDLWAVE versions, the breakpoint line is highlighted when the -mouse is moved over it, and a tooltip pops up describing the break -details. @kbd{Mouse-3} on the breakpoint line pops up a menu of -breakpoint actions, including clearing, disabling, and adding or -changing break conditions or ``after'' break count. - -Once the program has stopped somewhere, you can step through it. The -most important stepping commands are @kbd{C-c C-d C-s} to execute one -line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line, -treating procedure and function calls as a single step ("step over"); -@kbd{C-c C-d C-h} to continue execution to the line at the cursor and -@kbd{C-c C-d C-r} to continue execution. @xref{Commands Sent to the -Shell}, for information on displaying or hiding the breakpoint and -stepping commands the shell receives. Here is a summary of the -breakpoint and stepping commands: - -@multitable @columnfractions .23 .77 -@item @kbd{C-c C-d C-b} -@tab Set breakpoint (@code{idlwave-shell-break-here}) -@item @kbd{C-c C-d C-i} -@tab Set breakpoint in module named here (@code{idlwave-shell-break-in}) -@item @kbd{C-c C-d C-d} -@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) -@item @kbd{C-c C-d C-a} -@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) -@item @kbd{C-c C-d [} -@tab Go to the previous breakpoint (@code{idlwave-shell-goto-previous-bp}) -@item @kbd{C-c C-d ]} -@tab Go to the next breakpoint (@code{idlwave-shell-goto-next-bp}) -@item @kbd{C-c C-d C-\} -@tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp}) -@item @kbd{C-c C-d C-j} -@tab Set a breakpoint at the beginning of the enclosing routine. -@item @kbd{C-c C-d C-s} -@tab Step, into function calls (@code{idlwave-shell-step}) -@item @kbd{C-c C-d C-n} -@tab Step, over function calls (@code{idlwave-shell-stepover}) -@item @kbd{C-c C-d C-k} -@tab Skip one statement (@code{idlwave-shell-skip}) -@item @kbd{C-c C-d C-u} -@tab Continue to end of block (@code{idlwave-shell-up}) -@item @kbd{C-c C-d C-m} -@tab Continue to end of function (@code{idlwave-shell-return}) -@item @kbd{C-c C-d C-o} -@tab Continue past end of function (@code{idlwave-shell-out}) -@item @kbd{C-c C-d C-h} -@tab Continue to line at cursor position (@code{idlwave-shell-to-here}) -@item @kbd{C-c C-d C-r} -@tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont}) -@item @kbd{C-c C-d C-up} -@tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) -@item @kbd{C-c C-d C-down} -@tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) -@end multitable - -All of these commands have equivalents in Electric Debug Mode, which -provides faster single-key access (@pxref{Electric Debug Mode}). - -The line where IDL is currently stopped, at breakpoints, halts, and -errors, etc., is marked with a color overlay or arrow, depending on the -setting in @code{idlwave-shell-mark-stop-line}. If an overlay face is -used to mark the stop line (as it is by default), when stepping through -code, the face color is temporarily changed to gray, until IDL completes -the next command and moves to the new line. - -@defopt idlwave-shell-mark-breakpoints (@code{t}) -Non-@code{nil} means mark breakpoints in the source file buffers. The -value indicates the preferred method. Valid values are @code{nil}, -@code{t}, @code{face}, and @code{glyph}. -@end defopt - -@defopt idlwave-shell-breakpoint-face -The face for breakpoint lines in the source code if -@code{idlwave-shell-mark-breakpoints} has the value @code{face}. -@end defopt - -@defopt idlwave-shell-breakpoint-popup-menu (@code{t}) -Whether to pop-up a menu and present a tooltip description on -breakpoint lines. -@end defopt - -@defopt idlwave-shell-mark-stop-line (@code{t}) -Non-@code{nil} means mark the source code line where IDL is currently -stopped. The value specifies the preferred method. Valid values are -@code{nil}, @code{t}, @code{arrow}, and @code{face}. -@end defopt - -@defopt idlwave-shell-overlay-arrow (@code{">"}) -The overlay arrow to display at source lines where execution halts, if -configured in @code{idlwave-shell-mark-stop-line}. -@end defopt - -@defopt idlwave-shell-stop-line-face -The face which highlights the source line where IDL is stopped, if -configured in @code{idlwave-shell-mark-stop-line}. -@end defopt - - -@node Compiling Programs, Walking the Calling Stack, Breakpoints and Stepping, Debugging IDL Programs -@subsection Compiling Programs -@cindex Compiling programs -@cindex Programs, compiling -@cindex Default command line, executing -@cindex Executing a default command line - -@kindex C-c C-d C-c -In order to compile the current buffer under the IDLWAVE shell, press -@kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the -current buffer and then sends the command @samp{.run path/to/file} to the -shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in -which case the most recently compiled buffer will be saved and -re-compiled. - -When developing or debugging a program, it is often necessary to execute -the same command line many times. A convenient way to do this is -@kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}). -This command first resets IDL from a state of interrupted execution by -closing all files and returning to the main interpreter level. Then a -default command line is send to the shell. To edit the default command -line, call @code{idlwave-shell-execute-default-command-line} with a -prefix argument: @kbd{C-u C-c C-d C-y}. If no default command line has -been set (or you give two prefix arguments), the last command on the -@code{comint} input history is sent. - -@kindex C-c C-d C-e -@cindex Compiling regions -For quickly compiling and running the currently marked region as a main -level program @kbd{C-c C-d C-e} (@code{idlwave-shell-run-region}) is -very useful. A temporary file is created holding the contents of the -current region (with @code{END} appended), and run from the shell. - -@node Walking the Calling Stack, Electric Debug Mode, Compiling Programs, Debugging IDL Programs -@subsection Walking the Calling Stack -@cindex Calling stack, walking - -While debugging a program, it can be very useful to check the context in -which the current routine was called, for instance to help understand -the value of the arguments passed. To do so conveniently you need to -examine the calling stack. If execution is stopped somewhere deep in a -program, you can use the commands @kbd{C-c C-d C-@key{UP}} -(@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}} -(@code{idlwave-shell-stack-down}), or the corresponding toolbar buttons, -to move up or down through the calling stack. The mode line of the -shell window will indicate the position within the stack with a label -like @samp{[-3:MYPRO]}. The line of IDL code at that stack position -will be highlighted. If you continue execution, IDLWAVE will -automatically return to the current level. @xref{Examining Variables}, -for information how to examine the value of variables and expressions on -higher calling stack levels. - -@html - -@end html -@node Electric Debug Mode, , Walking the Calling Stack, Debugging IDL Programs -@subsection Electric Debug Mode -@cindex Electric Debug Mode -@cindex @samp{*Debugging*} - -Even with a convenient debug key prefix enabled, repetitive stepping, -variable examination (@pxref{Examining Variables}), and other debugging -activities can be awkward and slow using commands which require multiple -keystrokes. Luckily, there's a better way, inspired by the lisp e-debug -mode, and available through the @emph{Electric Debug Mode}. By default, -as soon as a breakpoint is hit, this minor mode is enabled. The buffer -showing the line where execution has halted is switched to Electric -Debug Mode. This mode is visible as @samp{*Debugging*} in the mode -line, and a different face (violet by default, if color is available) -for the line stopped at point. The buffer is made read-only and -single-character bindings for the most commonly used debugging commands -are enabled. These character commands (a list of which is available -with @kbd{C-?}) are: - -@multitable @columnfractions .2 .8 -@item @kbd{a} -@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) -@item @kbd{b} -@tab Set breakpoint, @kbd{C-u b} for a conditional break, @kbd{C-n b} for nth hit (@code{idlwave-shell-break-here}) -@item @kbd{d} -@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) -@item @kbd{e} -@tab Prompt for expression to print (@code{idlwave-shell-clear-current-bp}). -@item @kbd{h} -@tab Continue to the line at cursor position (@code{idlwave-shell-to-here}) -@item @kbd{i} -@tab Set breakpoint in module named here (@code{idlwave-shell-break-in}) -@item @kbd{[} -@tab Go to the previous breakpoint in the file (@code{idlwave-shell-goto-previous-bp}) -@item @kbd{]} -@tab Go to the next breakpoint in the file -(@code{idlwave-shell-goto-next-bp}) -@item @kbd{\} -@tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp}) -@item @kbd{j} -@tab Set breakpoint at beginning of enclosing routine (@code{idlwave-shell-break-this-module}) -@item @kbd{k} -@tab Skip one statement (@code{idlwave-shell-skip}) -@item @kbd{m} -@tab Continue to end of function (@code{idlwave-shell-return}) -@item @kbd{n} -@tab Step, over function calls (@code{idlwave-shell-stepover}) -@item @kbd{o} -@tab Continue past end of function (@code{idlwave-shell-out}) -@item @kbd{p} -@tab Print expression near point or in region with @kbd{C-u p} (@code{idlwave-shell-print}) -@item @kbd{q} -@tab End the debugging session and return to the Shell's main level -(@code{idlwave-shell-retall}) -@item @kbd{r} -@tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont}) -@item @kbd{s} or @kbd{@key{SPACE}} -@tab Step, into function calls (@code{idlwave-shell-step}) -@item @kbd{t} -@tab Print a calling-level traceback in the shell -@item @kbd{u} -@tab Continue to end of block (@code{idlwave-shell-up}) -@item @kbd{v} -@tab Turn Electric Debug Mode off -(@code{idlwave-shell-electric-debug-mode}) -@item @kbd{x} -@tab Examine expression near point (or in region with @kbd{C-u x}) -with shortcut of examine type. -@item @kbd{z} -@tab Reset IDL (@code{idlwave-shell-reset}) -@item @kbd{+} or @kbd{=} -@tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) -@item @kbd{-} or @kbd{_} -@tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) -@item @kbd{?} -@tab Help on expression near point or in region with @kbd{C-u ?} -(@code{idlwave-shell-help-expression}) -@item @kbd{C-?} -@tab Show help on the commands available. -@end multitable - -Most single-character electric debug bindings use the final keystroke -of the equivalent multiple key commands (which are of course also -still available), but some differ (e.g. @kbd{e},@kbd{t},@kbd{q},@kbd{x}). -Some have additional convenience bindings (like @kbd{@key{SPACE}} for -stepping). All prefix and other argument options described in this -section for the commands invoked by electric debug bindings are still -valid. For example, @kbd{C-u b} sets a conditional breakpoint, just -as it did with @kbd{C-u C-c C-d C-b}. - -You can toggle the electric debug mode at any time in a buffer using -@kbd{C-c C-d C-v} (@kbd{v} to turn it off while in the mode), or from -the Debug menu. Normally the mode will be enabled and disabled at the -appropriate times, but occasionally you might want to edit a file -while still debugging it, or switch to the mode for conveniently -setting lots of breakpoints. - -To quickly abandon a debugging session and return to normal editing at -the Shell's main level, use @kbd{q} (@code{idlwave-shell-retall}). -This disables electric debug mode in all IDLWAVE buffers@footnote{Note -that this binding is not symmetric: @kbd{C-c C-d C-q} is bound to -@code{idlwave-shell-quit}, which quits your IDL session.}. Help is -available for the command shortcuts with @kbd{C-?}. If you find this -mode gets in your way, you can keep it from automatically activating -by setting the variable @code{idlwave-shell-automatic-electric-debug} -to @code{nil}, or @code{'breakpoint}. If you'd like the convenient -electric debug shortcuts available also when run-time errors are -encountered, set to @code{t}. - -@defopt idlwave-shell-automatic-electric-debug (@code{'breakpoint}) -Whether to enter electric debug mode automatically when a breakpoint -or run-time error is encountered, and then disable it in all buffers -when the $MAIN$ level is reached (either through normal program -execution, or retall). In addition to @code{nil} for never, and -@code{t} for both breakpoints and errors, this can be -@code{'breakpoint} (the default) to enable it only at breakpoint -halts. -@end defopt - -@defopt idlwave-shell-electric-stop-color (Violet) -Default color of the stopped line overlay when in electric debug mode. -@end defopt - -@defopt idlwave-shell-electric-stop-line-face -The face to use for the stopped line. Defaults to a face similar to the -modeline, with color @code{idlwave-shell-electric-stop-color}. -@end defopt - -@defopt idlwave-shell-electric-zap-to-file (@code{t}) -If set, when entering electric debug mode, select the window displaying -the file where point is stopped. This takes point away from the shell -window, but is useful for immediate stepping, etc. -@end defopt - -@html - -@end html -@node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell -@section Examining Variables -@cindex @code{PRINT} expressions -@cindex @code{HELP}, on expressions -@cindex Expressions, printing & help -@cindex Examining expressions -@cindex Printing expressions -@cindex Mouse binding to print expressions - -@kindex C-c C-d C-p -Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)}, -and similar statements to remind yourself of the -type/size/structure/value/etc. of variables and expressions in your code -or at the command line? IDLWAVE has a suite of special commands to -automate these types of variable or expression examinations. They work -by sending statements to the shell formatted to include the indicated -expression, and can be accessed in several ways. - -These @emph{examine} commands can be used in the shell or buffer at any -time (as long as the shell is running), and are very useful when -execution is stopped in a buffer due to a triggered breakpoint or error, -or while composing a long command in the IDLWAVE shell. In the latter -case, the command is sent to the shell and its output is visible, but -point remains unmoved in the command being composed --- you can inspect -the constituents of a command you're building without interrupting the -process of building it! You can even print arbitrary expressions from -older input or output further up in the shell window --- any expression, -variable, number, or function you see can be examined. - -If the variable @code{idlwave-shell-separate-examine-output} is -non-@code{nil} (the default), all examine output will be sent to a -special @file{*Examine*} buffer, rather than the shell. The output of -prior examine commands is saved in this buffer. In this buffer @key{c} -clears the contents, and @key{q} hides the buffer. - -The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to -print the expression at point, and @kbd{C-c C-d ?}, to invoke help on -this expression@footnote{Available as @kbd{p} and @kbd{?} in Electric -Debug Mode (@pxref{Electric Debug Mode})}. The expression at point is -either an array expression or a function call, or the contents of a pair -of parentheses. The chosen expression is highlighted, and -simultaneously the resulting output is highlighted in the shell or -separate output buffer. Calling the above commands with a prefix -argument will use the current region as expression instead of using the -one at point. which can be useful for examining complicated, multi-line -expressions. Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will -prompt for an expression to print directly. By default, when invoking -print, only an initial portion of long arrays will be printed, up to -@code{idlwave-shell-max-print-length}. - -For added speed and convenience, there are mouse bindings which allow -you to click on expressions and examine their values. Use -@kbd{S-Mouse-2} to print an expression and @kbd{C-M-Mouse-2} to invoke -help (i.e. you need to hold down @key{META} and @key{CONTROL} while -clicking with the middle mouse button). If you simply click, the -nearest expression will be selected in the same manner as described -above. You can also @emph{drag} the mouse in order to highlight -exactly the specific expression or sub-expression you want to examine. -For custom expression examination, and the powerful customizable -pop-up examine selection, @xref{Custom Expression Examination}. - -@cindex Printing expressions, on calling stack -@cindex Restrictions for expression printing -The same variable inspection commands work both in the IDL Shell and -IDLWAVE buffers, and even for variables at higher levels of the calling -stack. For instance, if you're stopped at a breakpoint in a routine, -you can examine the values of variables and expressions inside its -calling routine, and so on, all the way up through the calling stack. -Simply step up the stack, and print variables as you see them -(@pxref{Walking the Calling Stack}, for information on stepping back -through the calling stack). The following restrictions apply for all -levels except the current: - -@itemize @bullet -@item -Array expressions must use the @samp{[ ]} index delimiters. Identifiers -with a @samp{( )} will be interpreted as function calls. -@item -@cindex ROUTINE_NAMES, IDL procedure -N.B.: printing values of expressions on higher levels of the calling -stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, -which may or may not be available in future versions of IDL. Caveat -Examinor. -@end itemize - -@defopt idlwave-shell-expression-face -The face for @code{idlwave-shell-expression-overlay}. -Allows you to choose the font, color and other properties for -the expression printed by IDL. -@end defopt - -@defopt idlwave-shell-output-face -The face for @code{idlwave-shell-output-overlay}. -Allows to choose the font, color and other properties for the most -recent output of IDL when examining an expression." -@end defopt - -@defopt idlwave-shell-separate-examine-output (@code{t}) -If non-@code{nil}, re-direct the output of examine commands to a special -@file{*Examine*} buffer, instead of in the shell itself. -@end defopt - -@defopt idlwave-shell-max-print-length (200) -The maximum number of leading array entries to print, when examining -array expressions. -@end defopt - -@node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell -@section Custom Expression Examination -@cindex Expressions, custom examination -@cindex Custom expression examination - -The variety of possible variable and expression examination commands is -endless (just look, for instance, at the keyword list to -@code{widget_info()}). Rather than attempt to include them all, IDLWAVE -provides two easy methods to customize your own commands, with a special -mouse examine command, and two macros for generating your own examine -key and mouse bindings. - -The most powerful and flexible mouse examine command of all is -available on @kbd{C-S-Mouse-2}. Just as for all the other mouse -examine commands, it permits click or drag expression selection, but -instead of sending hard-coded commands to the shell, it pops-up a -customizable selection list of examine functions to choose among, -configured with the @code{idlwave-shell-examine-alist} -variable@footnote{In Electric Debug Mode (@pxref{Electric Debug -Mode}), the key @kbd{x} provides a single-character shortcut interface -to the same examine functions for the expression at point or marked by -the region.}. This variable is a list of key-value pairs (an -@emph{alist} in Emacs parlance), where the key gives a name to be -shown for the examine command, and the value is the command strings -itself, in which the text @code{___} (three underscores) will be -replaced by the selected expression before being sent to the shell. -An example might be key @code{Structure Help} with value -@code{help,___,/STRUCTURE}. In that case, you'd be prompted with -@emph{Structure Help}, which might send something like -@code{help,var,/STRUCTURE} to the shell for output. -@code{idlwave-shell-examine-alist} comes configured by default with a -large list of examine commands, but you can easily customize it to add -your own. - -In addition to configuring the functions available to the pop-up mouse -command, you can easily create your own customized bindings to inspect -expressions using the two convenience macros -@code{idlwave-shell-examine} and @code{idlwave-shell-mouse-examine}. -These create keyboard or mouse-based custom inspections of variables, -sharing all the same properties of the built-in examine commands. -Both functions take a single string argument sharing the syntax of the -@code{idlwave-shell-examine-alist} values, e.g.: - -@lisp -(add-hook 'idlwave-shell-mode-hook - (lambda () - (idlwave-shell-define-key-both [s-down-mouse-2] - (idlwave-shell-mouse-examine - "print, size(___,/DIMENSIONS)")) - (idlwave-shell-define-key-both [f9] (idlwave-shell-examine - "print, size(___,/DIMENSIONS)")) - (idlwave-shell-define-key-both [f10] (idlwave-shell-examine - "print,size(___,/TNAME)")) - (idlwave-shell-define-key-both [f11] (idlwave-shell-examine - "help,___,/STRUCTURE")))) -@end lisp - -@noindent Now pressing @key{f9}, or middle-mouse dragging with the -@key{SUPER} key depressed, will print the dimensions of the nearby or -highlighted expression. Pressing @key{f10} will give the type string, -and @key{f11} will show the contents of a nearby structure. As you can -see, the possibilities are only marginally finite. - -@defopt idlwave-shell-examine-alist -An alist of examine commands in which the keys name the command and -are displayed in the selection pop-up, and the values are custom IDL -examine command strings to send, after all instances of @code{___} -(three underscores) are replaced by the indicated expression. -@end defopt - -@node Acknowledgements, Sources of Routine Info, The IDLWAVE Shell, Top -@chapter Acknowledgements -@cindex Acknowledgements -@cindex Maintainer, of IDLWAVE -@cindex Authors, of IDLWAVE -@cindex Contributors, to IDLWAVE -@cindex Email address, of Maintainer -@cindex Thanks - -@noindent -The main contributors to the IDLWAVE package have been: - -@itemize @minus -@item -@uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author. -Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them -for several years. - -@item -@uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} was in charge -of the package from version 3.0, during which time he overhauled almost -everything, modernized IDLWAVE with many new features, and developed the -manual. - -@item -@uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current -maintainer, as of version 4.10, helped shape object method completion -and most new features introduced in versions 4.x, and introduced many -new features for IDLWAVE versions 5.x and 6.x. -@end itemize - -@noindent -The following people have also contributed to the development of IDLWAVE -with patches, ideas, bug reports and suggestions. - -@itemize @minus -@item -Ulrik Dickow -@item -Eric E. Dors -@item -Stein Vidar H. Haugan -@item -David Huenemoerder -@item -Kevin Ivory -@item -Dick Jackson -@item -Xuyong Liu -@item -Simon Marshall -@item -Craig Markwardt -@item -Laurent Mugnier -@item -Lubos Pochman -@item -Bob Portmann -@item -Patrick M. Ryan -@item -Marty Ryba -@item -Phil Williams -@item -Phil Sterne -@item -Paul Sorenson -@end itemize - -Doug Dirks was instrumental in providing the crucial IDL XML catalog to -support HTML help with IDL v6.2 and later, and Ali Bahrami provided -scripts and documentation to interface with the IDL Assistant. - -@noindent -Thanks to everyone! - -@node Sources of Routine Info, HTML Help Browser Tips, Acknowledgements, Top -@appendix Sources of Routine Info - -@cindex Sources of routine information -In @ref{Routine Info} and @ref{Completion} we showed how IDLWAVE -displays the calling sequence and keywords of routines, and completes -routine names and keywords. For these features to work, IDLWAVE must -know about the accessible routines. - -@menu -* Routine Definitions:: Where IDL Routines are defined. -* Routine Information Sources:: So how does IDLWAVE know about... -* Catalogs:: -* Load-Path Shadows:: Routines defined in several places -* Documentation Scan:: Scanning the IDL Manuals -@end menu - -@node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info -@appendixsec Routine Definitions -@cindex Routine definitions -@cindex IDL variable @code{!PATH} -@cindex @code{!PATH}, IDL variable -@cindex @code{CALL_EXTERNAL}, IDL routine -@cindex @code{LINKIMAGE}, IDL routine -@cindex External routines - -@noindent Routines which can be used in an IDL program can be defined in -several places: - -@enumerate -@item -@emph{Builtin routines} are defined inside IDL itself. The source code -of such routines is not available, but instead are learned about through -the IDL documentation. -@item -Routines which are @emph{part of the current program}, are defined in a -file explicitly compiled by the user. This file may or may not be -located on the IDL search path. -@item -@emph{Library routines} are defined in files located on IDL's search -path. When a library routine is called for the first time, IDL will -find the source file and compile it dynamically. A special sub-category -of library routines are the @emph{system routines} distributed with IDL, -and usually available in the @file{lib} subdirectory of the IDL -distribution. -@item -External routines written in other languages (like Fortran or C) can be -called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE}, -or included as dynamically loaded modules (DLMs). Currently IDLWAVE -cannot provide routine info and completion for such external routines, -except by querying the Shell for calling information (DLMs only). -@end enumerate - -@node Routine Information Sources, Catalogs, Routine Definitions, Sources of Routine Info -@appendixsec Routine Information Sources -@cindex Routine info sources -@cindex Builtin list of routines -@cindex Updating routine info -@cindex Scanning buffers for routine info -@cindex Buffers, scanning for routine info -@cindex Shell, querying for routine info - -@noindent To maintain the most comprehensive information about all IDL -routines on a system, IDLWAVE collects data from many sources: - -@enumerate - -@item -It has a @emph{builtin list} with information about the routines IDL -ships with. IDLWAVE @value{VERSION} is distributed with a list of -@value{NSYSROUTINES} routines and object methods, reflecting IDL version -@value{IDLVERSION}. As of IDL v6.2, the routine info is distributed -directly with IDL in the form of an XML catalog which IDLWAVE scans. -Formerly, this list was created by scanning the IDL manuals to produce -the file @file{idlw-rinfo.el}. - -@item -IDLWAVE @emph{scans} all its @emph{buffers} in the current Emacs session -for routine definitions. This is done automatically when routine -information or completion is first requested by the user. Each new -buffer and each buffer saved after making changes is also scanned. The -command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used -at any time to rescan all buffers. - -@item -If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will -@emph{query the shell} for compiled routines and their arguments. This -happens automatically when routine information or completion is first -requested by the user. Each time an Emacs buffer is compiled with -@kbd{C-c C-d C-c}, the routine info for that file is queried. Though -rarely necessary, the command @kbd{C-c C-i} -(@code{idlwave-update-routine-info}) can be used to explicitly update -the shell routine data. - -@item -Many popular libraries are distributed with routine information already -scanned into @emph{library catalogs} (@pxref{Library Catalogs}). These -per-directory catalog files can also be built by the user with the -supplied @file{idlwave_catalog} tool. They are automatically discovered -by IDLWAVE. - -@item -IDLWAVE can scan selected directories of source files and store the -result in a single @emph{user catalog} file which will be -automatically loaded just like @file{idlw-rinfo.el}. @xref{User -Catalog}, for information on how to scan files in this way. -@end enumerate - -Loading all the routine and catalog information can be a time consuming -process, especially over slow networks. Depending on the system and -network configuration it could take up to 30 seconds (though locally on -fast systems is usually only a few seconds). In order to minimize the -wait time upon your first completion or routine info command in a -session, IDLWAVE uses Emacs idle time to do the initialization in six -steps, yielding to user input in between. If this gets into your way, -set the variable @code{idlwave-init-rinfo-when-idle-after} to 0 (zero). -The more routines documented in library and user catalogs, the slower -the loading will be, so reducing this number can help alleviate any long -load times. - -@defopt idlwave-init-rinfo-when-idle-after (@code{10}) -Seconds of idle time before routine info is automatically initialized. -@end defopt - -@defopt idlwave-scan-all-buffers-for-routine-info (@code{t}) -Non-@code{nil} means scan all buffers for IDL programs when updating -info. -@end defopt - -@defopt idlwave-query-shell-for-routine-info (@code{t}) -Non-@code{nil} means query the shell for info about compiled routines. -@end defopt - -@defopt idlwave-auto-routine-info-updates -Controls under what circumstances routine info is updated automatically. -@end defopt - -@html - -@end html -@node Catalogs, Load-Path Shadows, Routine Information Sources, Sources of Routine Info -@appendixsec Catalogs -@cindex Catalogs - -@emph{Catalogs} are files containing scanned information on individual -routines, including arguments and keywords, calling sequence, file path, -class and procedure vs. function type, etc. They represent a way of -extending the internal built-in information available for IDL system -routines (@pxref{Routine Info}) to other source collections. - -Starting with version 5.0, there are two types of catalogs available -with IDLWAVE. The traditional @emph{user catalog} and the newer -@emph{library catalogs}. Although they can be used interchangeably, the -library catalogs are more flexible, and preferred. There are few -occasions when a user catalog might be preferred --- read below. Both -types of catalogs can coexist without causing problems. - -To facilitate the catalog systems, IDLWAVE stores information it gathers -from the shell about the IDL search paths, and can write this -information out automatically, or on-demand (menu @code{Debug->Save Path -Info}). On systems with no shell from which to discover the path -information (e.g. Windows), a library path must be specified in -@code{idlwave-library-path} to allow library catalogs to be located, and -to setup directories for user catalog scan (@pxref{User Catalog} for -more on this variable). Note that, before the shell is running, IDLWAVE -can only know about the IDL search path by consulting the file pointed -to by @code{idlwave-path-file} (@file{~/.idlwave/idlpath.el}, by -default). If @code{idlwave-auto-write-path} is enabled (which is the -default), the paths are written out whenever the IDLWAVE shell is -started. - -@defopt idlwave-auto-write-path (@code{t}) -Write out information on the !PATH and !DIR paths from IDL automatically -when they change and when the Shell is closed. These paths are needed -to locate library catalogs. -@end defopt - -@defopt idlwave-library-path -IDL library path for Windows and MacOS. Under Unix/MacOSX, will be -obtained from the Shell when run. -@end defopt - -@defopt idlwave-system-directory -The IDL system directory for Windows and MacOS. Also needed for -locating HTML help and the IDL Assistant for IDL v6.2 and later. Under -Unix/MacOSX, will be obtained from the Shell and recorded, if run. -@end defopt - -@defopt idlwave-config-directory (@file{~/.idlwave}) -Default path where IDLWAVE saves configuration information, a user -catalog (if any), and a cached scan of the XML catalog (IDL v6.2 and -later). -@end defopt - -@menu -* Library Catalogs:: -* User Catalog:: -@end menu - -@html - -@end html -@node Library Catalogs, User Catalog, Catalogs, Catalogs -@appendixsubsec Library Catalogs -@cindex @file{.idlwave_catalog} -@cindex Library catalogs -@cindex @code{idlwave_catalog} - -Library catalogs consist of files named @file{.idlwave_catalog} stored -in directories containing @code{.pro} routine files. They are -discovered on the IDL search path and loaded automatically when routine -information is read. Each catalog file documents the routines found in -that directory --- one catalog per directory. Every catalog has a -library name associated with it (e.g. @emph{AstroLib}). This name will -be shown briefly when the catalog is found, and in the routine info of -routines it documents. - -Many popular libraries of routines are shipped with IDLWAVE catalog -files by default, and so will be automatically discovered. Library -catalogs are scanned externally to Emacs using a tool provided with -IDLWAVE. Each catalog can be re-scanned independently of any other. -Catalogs can easily be made available system-wide with a common source -repository, providing uniform routine information, and lifting the -burden of scanning from the user (who may not even know they're using a -scanned catalog). Since all catalogs are independent, they can be -re-scanned automatically to gather updates, e.g. in a @file{cron} job. -Scanning is much faster than with the built-in user catalog method. One -minor disadvantage: the entire IDL search path is scanned for catalog -files every time IDLWAVE starts up, which might be slow if accessing IDL -routines over a slow network. - -A Perl tool to create library catalogs is distributed with IDLWAVE: -@code{idlwave_catalog}. It can be called quite simply: -@example -idlwave_catalog MyLib -@end example - -@noindent This will scan all directories recursively beneath the current and -populate them with @file{.idlwave_catalog} files, tagging the routines -found there with the name library ``MyLib''. The full usage -information: - -@example -Usage: idlwave_catalog [-l] [-v] [-d] [-s] [-f] [-h] libname - libname - Unique name of the catalog (4 or more alphanumeric - characters). - -l - Scan local directory only, otherwise recursively - catalog all directories at or beneath this one. - -v - Print verbose information. - -d - Instead of scanning, delete all .idlwave_catalog files - here or below. - -s - Be silent. - -f - Force overwriting any catalogs found with a different - library name. - -h - Print this usage. -@end example - -To re-load the library catalogs on the IDL path, force a system routine -info update using a single prefix to @code{idlwave-update-routine-info}: -@kbd{C-u C-c C-i}. - -@defopt idlwave-use-library-catalogs (@code{t}) -Whether to search for and load library catalogs. Disable if load -performance is a problem and/or the catalogs are not needed. -@end defopt - -@node User Catalog, , Library Catalogs, Catalogs -@appendixsubsec User Catalog -@cindex User catalog -@cindex IDL library routine info -@cindex Windows -@cindex MacOS -@cindex IDL variable @code{!DIR} -@cindex @code{!DIR}, IDL variable - -The user catalog is the old routine catalog system. It is produced -within Emacs, and stored in a single file in the user's home directory -(@file{.idlwave/idlusercat.el} by default). Although library catalogs -are more flexible, there may be reasons to prefer a user catalog -instead, including: - -@itemize @bullet -@item The scan is internal to Emacs, so you don't need a working Perl -installation, as you do for library catalogs. -@item Can be used to scan directories for which the user has no write -privileges. -@item Easy widget-based path selection. -@end itemize - -However, no routine info is available in the user catalog by default; -the user must actively complete a scan. In addition, this type of -catalog is all or nothing: if a single routine changes, the entire -catalog must be rescanned to update it. Creating the user catalog is -also much slower than scanning library catalogs. - -You can scan any of the directories on the currently known path. Under -Windows and MacOS (not OSX), you need to specify the IDL search path in -the variable @code{idlwave-library-path}, and the location of the IDL -directory (the value of the @code{!DIR} system variable) in the variable -@code{idlwave-system-directory}, like this@footnote{The initial @samp{+} -leads to recursive expansion of the path, just like in IDL}: - -@lisp -(setq idlwave-library-path - '("+c:/RSI/IDL56/lib/" "+c:/user/me/idllibs")) -(setq idlwave-system-directory "c:/RSI/IDL56/") -@end lisp - -@noindent Under GNU/Linux and UNIX, these values will be automatically -gathered from the IDLWAVE shell, if run. - -The command @kbd{M-x idlwave-create-user-catalog-file} (or the menu item -@samp{IDLWAVE->Routine Info->Select Catalog Directories}) can then be -used to create a user catalog. It brings up a widget in which you can -select some or all directories on the search path. Directories which -already contain a library catalog are marked with @samp{[LIB]}, and need -not be scanned (although there is no harm if you do so, other than the -additional memory used for the duplication). - -After selecting directories, click on the @w{@samp{[Scan & Save]}} -button in the widget to scan all files in the selected directories and -write out the resulting routine information. In order to update the -library information using the directory selection, call the command -@code{idlwave-update-routine-info} with a double prefix argument: -@w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously -selected directories, write an updated version of the user catalog file -and rebuild IDLWAVE's internal lists. If you give three prefix -arguments @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a -background job@footnote{Unix systems only, I think.}. You can continue -to work, and the library catalog will be re-read when it is ready. If -you find you need to update the user catalog often, you should consider -building a library catalog for your routines instead (@pxref{Library -Catalogs}). - -@defopt idlwave-special-lib-alist -Alist of regular expressions matching special library directories for -labeling in routine-info display. -@end defopt - -@node Load-Path Shadows, Documentation Scan, Catalogs, Sources of Routine Info -@appendixsec Load-Path Shadows -@cindex Load-path shadows -@cindex Shadows, load-path -@cindex Duplicate routines -@cindex Multiply defined routines -@cindex Routine definitions, multiple -@cindex Application, testing for shadowing -@cindex Buffer, testing for shadowing - -IDLWAVE can compile a list of routines which are (re-)defined in more -than one file. Since one definition will hide (shadow) the others -depending on which file is compiled first, such multiple definitions are -called "load-path shadows". IDLWAVE has several routines to scan for -load path shadows. The output is placed into the special buffer -@file{*Shadows*}. The format of the output is identical to the source -section of the routine info buffer (@pxref{Routine Info}). The -different definitions of a routine are ordered by @emph{likelihood of -use}. So the first entry will be most likely the one you'll get if an -unsuspecting command uses that routine. Before listing shadows, you -should make sure that routine info is up-to-date by pressing @kbd{C-c -C-i}. Here are the different routines (also available in the Menu -@samp{IDLWAVE->Routine Info}): - -@table @asis -@item @kbd{M-x idlwave-list-buffer-load-path-shadows} -This command checks the names of all routines defined in the current -buffer for shadowing conflicts with other routines accessible to -IDLWAVE. The command also has a key binding: @kbd{C-c C-b} -@item @kbd{M-x idlwave-list-shell-load-path-shadows}. -Checks all routines compiled under the shell for shadowing. This is -very useful when you have written a complete application. Just compile -the application, use @code{RESOLVE_ALL} to compile any routines used by -your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and -then check for shadowing. -@item @kbd{M-x idlwave-list-all-load-path-shadows} -This command checks all routines accessible to IDLWAVE for conflicts. -@end table - -For these commands to work fully you need to scan the entire load path -in either a user or library catalog. Also, IDLWAVE should be able to -distinguish between the system library files (normally installed in -@file{/usr/local/rsi/idl/lib}) and any site specific or user specific -files. Therefore, such local files should not be installed inside the -@file{lib} directory of the IDL directory. This is also advisable for -many other reasons. - -@cindex Windows -@cindex MacOS -@cindex IDL variable @code{!DIR} -@cindex @code{!DIR}, IDL variable -Users of Windows and MacOS (not X) also must set the variable -@code{idlwave-system-directory} to the value of the @code{!DIR} system -variable in IDL. IDLWAVE appends @file{lib} to the value of this -variable and assumes that all files found on that path are system -routines. - -Another way to find out if a specific routine has multiple definitions -on the load path is routine info display (@pxref{Routine Info}). - -@node Documentation Scan, , Load-Path Shadows, Sources of Routine Info -@appendixsec Documentation Scan -@cindex @file{get_html_rinfo} -@cindex @file{idlw-rinfo.el} -@cindex Scanning the documentation -@cindex Perl program, to create @file{idlw-rinfo.el} - -@strong{Starting with version 6.2, IDL is distributed directly with HTML -online help, and an XML-based catalog of routine information}. This -makes scanning the manuals with the tool @file{get_html_rinfo}, and the -@file{idlw-rinfo.el} file it produced, as described here, entirely -unnecessary. The information is left here for users wishing to produce -a catalog of older IDL versions' help. - - -IDLWAVE derives its knowledge about system routines from the IDL -manuals. The file @file{idlw-rinfo.el} contains the routine information -for the IDL system routines, and links to relevant sections of the HTML -documentation. The Online Help feature of IDLWAVE requires HTML -versions of the IDL manuals to be available; the HTML documentation is -not distributed with IDLWAVE by default, but must be downloaded -separately. - -The HTML files and related images can be produced from the -@file{idl.chm} HTMLHelp file distributed with IDL using the free -Microsoft HTML Help Workshop. If you are lucky, the maintainer of -IDLWAVE will always have access to the newest version of IDL and provide -updates. The IDLWAVE distribution also contains the Perl program -@file{get_html_rinfo} which constructs the @file{idlw-rinfo.el} file by -scanning the HTML documents produced from the IDL documentation. -Instructions on how to use @file{get_html_rinfo} are in the program -itself. - -@node HTML Help Browser Tips, Configuration Examples, Sources of Routine Info, Top -@appendix HTML Help Browser Tips -@cindex Browser Tips - -There are a wide variety of possible browsers to use for displaying -the online HTML help available with IDLWAVE (starting with version -5.0). Since IDL v6.2, a single cross-platform HTML help browser, the -@emph{IDL Assistant} is distributed with IDL. If this help browser is -available, it is the preferred choice, and the default. The variable -@code{idlwave-help-use-assistant}, enabled by default, controls -whether this help browser is used. If you use the IDL Assistant, the -tips here are not relevant. - -Since IDLWAVE runs on a many different system types, a single browser -configuration is not possible, but choices abound. On many systems, -the default browser configured in @code{browse-url-browser-function}, -and hence inherited by default by -@code{idlwave-help-browser-function}, is Netscape. Unfortunately, the -HTML manuals decompiled from the original source contain formatting -structures which Netscape 4.x does not handle well, though they are -still readable. A much better choice is Mozilla, or one of the -Mozilla-derived browsers such as -@uref{http://galeon.sourceforge.net/,Galeon} (GNU/Linux), -@uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or -@uref{http://www.mozilla.org/projects/firebird/,Firebird} (all -platforms). Newer versions of Emacs provide a browser-function choice -@code{browse-url-gnome-moz} which uses the Gnome-configured browser. - -Note that the HTML files decompiled from the help sources contain -specific references to the @samp{Symbol} font, which by default is not -permitted in normal encodings (it's invalid, technically). Though it -only impacts a few symbols, you can trick Mozilla-based browsers into -recognizing @samp{Symbol} by following the directions -@uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}. With -this fix in place, HTML help pages look almost identical to their PDF -equivalents (yet can be bookmarked, browsed as history, searched, -etc.). - -@noindent Individual platform recommendations: - -@itemize @bullet -@item Unix/MacOSX: The @uref{http://www.w3m.org,@code{w3m}} browser -and its associated -@uref{http://emacs-w3m.namazu.org/,@code{emacs-w3m}} emacs mode -provide in-buffer browsing with image display, and excellent speed and -formatting. Both the Emacs mode and the browser itself must be -downloaded separately. To use this browser, include - -@lisp -(setq idlwave-help-browser-function 'w3m-browse-url) -@end lisp - -in your @file{.emacs}. Setting a few other nice @code{w3m} options -cuts down on screen clutter: - -@lisp -(setq w3m-use-tab nil - w3m-use-header-line nil - w3m-use-toolbar nil) -@end lisp - -If you use a dedicated frame for help, you might want to add the -following, to get consistent behavior with the @kbd{q} key: - -@lisp -;; Close my help window when w3m closes. -(defadvice w3m-close-window (after idlwave-close activate) - (if (boundp 'idlwave-help-frame) - (idlwave-help-quit))) -@end lisp - -Note that you can open the file in an external browser from within -@code{w3m} using @kbd{M}. -@end itemize - -@node Configuration Examples, Windows and MacOS, HTML Help Browser Tips, Top -@appendix Configuration Examples -@cindex Configuration examples -@cindex Example configuration -@cindex @file{.emacs} -@cindex Default settings, of options -@cindex Interview, with the maintainer - -@noindent -@b{Question:} You have all these complicated configuration options in -your package, but which ones do @emph{you} as the maintainer actually -set in your own configuration? - -@noindent -@b{Answer:} Not many, beyond custom key bindings. I set most defaults -the way that seems best. However, the default settings do not turn on -features which: - -@itemize @minus -@item -are not self-evident (i.e. too magic) when used by an unsuspecting user. -@item -are too intrusive. -@item -will not work properly on all Emacs installations. -@item -break with widely used standards. -@item -use function or other non-standard keys. -@item -are purely personal customizations, like additional key bindings, and -library names. -@end itemize - -@noindent To see what I mean, here is the @emph{entire} configuration -the old maintainer had in his @file{.emacs}: - -@lisp -(setq idlwave-shell-debug-modifiers '(control shift) - idlwave-store-inquired-class t - idlwave-shell-automatic-start t - idlwave-main-block-indent 2 - idlwave-init-rinfo-when-idle-after 2 - idlwave-help-dir "~/lib/emacs/idlwave" - idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib") - ("/jhuapl/" . "JHUAPL-Lib") - ("/dominik/lib/idl/" . "MyLib"))) -@end lisp - -However, if you are an Emacs power-user and want IDLWAVE to work -completely differently, you can change almost every aspect of it. Here -is an example of a much more extensive configuration of IDLWAVE. The -user is King! - -@example -;;; Settings for IDLWAVE mode - -(setq idlwave-block-indent 3) ; Indentation settings -(setq idlwave-main-block-indent 3) -(setq idlwave-end-offset -3) -(setq idlwave-continuation-indent 1) -(setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" - ; anchored at start of line. -(setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> -(setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' -(setq idlwave-expand-generic-end t) ; convert END to ENDIF etc... -(setq idlwave-reserved-word-upcase t) ; Make reserved words upper case - ; (with abbrevs only) -(setq idlwave-abbrev-change-case nil) ; Don't force case of expansions -(setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill -(setq idlwave-show-block nil) ; Turn off blinking to begin -(setq idlwave-abbrev-move t) ; Allow abbrevs to move point -(setq idlwave-query-class '((method-default . nil) ; No query for method - (keyword-default . nil); or keyword completion - ("INIT" . t) ; except for these - ("CLEANUP" . t) - ("SETPROPERTY" .t) - ("GETPROPERTY" .t))) - -;; Using w3m for help (must install w3m and emacs-w3m) -(autoload 'w3m-browse-url "w3m" "Interface for w3m on Emacs." t) -(setq idlwave-help-browser-function 'w3m-browse-url - w3m-use-tab nil ; no tabs, location line, or toolbar - w3m-use-header-line nil - w3m-use-toolbar nil) - -;; Close my help window or frame when w3m closes with `q' -(defadvice w3m-close-window (after idlwave-close activate) - (if (boundp 'idlwave-help-frame) - (idlwave-help-quit))) - -;; Some setting can only be done from a mode hook. Here is an example: -(add-hook 'idlwave-mode-hook - (lambda () - (setq case-fold-search nil) ; Make searches case sensitive - ;; Run other functions here - (font-lock-mode 1) ; Turn on font-lock mode - (idlwave-auto-fill-mode 0) ; Turn off auto filling - (setq idlwave-help-browser-function 'browse-url-w3) - - ;; Pad with 1 space (if -n is used then make the - ;; padding a minimum of n spaces.) The defaults use -1 - ;; instead of 1. - (idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1)) - (idlwave-action-and-binding "<" '(idlwave-surround 1 1)) - (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-))) - (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) - - ;; Only pad after comma and with exactly 1 space - (idlwave-action-and-binding "," '(idlwave-surround nil 1)) - (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) - - ;; Pad only after `->', remove any space before the arrow - (idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2)) - - ;; Set some personal bindings - ;; (In this case, makes `,' have the normal self-insert behavior.) - (local-set-key "," 'self-insert-command) - (local-set-key [f5] 'idlwave-shell-break-here) - (local-set-key [f6] 'idlwave-shell-clear-current-bp) - - ;; Create a newline, indenting the original and new line. - ;; A similar function that does _not_ reindent the original - ;; line is on "\C-j" (The default for emacs programming modes). - (local-set-key "\n" 'idlwave-newline) - ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. - - ;; Some personal abbreviations - (define-abbrev idlwave-mode-abbrev-table - (concat idlwave-abbrev-start-char "wb") "widget_base()" - (idlwave-keyword-abbrev 1)) - (define-abbrev idlwave-mode-abbrev-table - (concat idlwave-abbrev-start-char "on") "obj_new()" - (idlwave-keyword-abbrev 1)) - )) - -;;; Settings for IDLWAVE SHELL mode - -(setq idlwave-shell-overlay-arrow "=>") ; default is ">" -(setq idlwave-shell-use-dedicated-frame t) ; Make a dedicated frame -(setq idlwave-shell-prompt-pattern "^WAVE> ") ; default is "^IDL> " -(setq idlwave-shell-explicit-file-name "wave") -(setq idlwave-shell-process-name "wave") -(setq idlwave-shell-use-toolbar nil) ; No toolbar - -;; Most shell interaction settings can be done from the shell-mode-hook. -(add-hook 'idlwave-shell-mode-hook - (lambda () - ;; Set up some custom key and mouse examine commands - (idlwave-shell-define-key-both [s-down-mouse-2] - (idlwave-shell-mouse-examine - "print, size(___,/DIMENSIONS)")) - (idlwave-shell-define-key-both [f9] (idlwave-shell-examine - "print, size(___,/DIMENSIONS)")) - (idlwave-shell-define-key-both [f10] (idlwave-shell-examine - "print,size(___,/TNAME)")) - (idlwave-shell-define-key-both [f11] (idlwave-shell-examine - "help,___,/STRUCTURE")))) -@end example - -@html - -@end html -@node Windows and MacOS, Troubleshooting, Configuration Examples, Top -@appendix Windows and MacOS -@cindex Windows -@cindex MacOS -@cindex MacOSX - -IDLWAVE was developed on a UNIX system. However, thanks to the -portability of Emacs, much of IDLWAVE does also work under different -operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS. - -The only real problem is that there is no command-line version of IDL -for Windows or MacOS(<=9) with which IDLWAVE can interact. As a -result, the IDLWAVE Shell does not work and you have to rely on IDLDE -to run and debug your programs. However, editing IDL source files -with Emacs/IDLWAVE works with all bells and whistles, including -routine info, completion and fast online help. Only a small amount of -additional information must be specified in your @file{.emacs} file: -the path names which, on a UNIX system, are automatically gathered by -talking to the IDL program. - -Here is an example of the additional configuration needed for a Windows -system. I am assuming that IDLWAVE has been installed in -@w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in -@w{@samp{C:\RSI\IDL63}}. - -@lisp -;; location of the lisp files (only needed if IDLWAVE is not part of -;; your default X/Emacs installation) -(setq load-path (cons "c:/program files/IDLWAVE" load-path)) - -;; The location of the IDL library directories, both standard, and your own. -;; note that the initial "+" expands the path recursively -(setq idlwave-library-path - '("+c:/RSI/IDL63/lib/" "+c:/path/to/my/idllibs" )) - -;; location of the IDL system directory (try "print,!DIR") -(setq idlwave-system-directory "c:/RSI/IDL63/") - -@end lisp - -@noindent Furthermore, Windows sometimes tries to outsmart you --- make -sure you check the following things: - -@itemize @bullet -@item When you download the IDLWAVE distribution, make sure you save the -file under the names @file{idlwave.tar.gz}. -@item M-TAB switches among running programs --- use Esc-TAB -instead. -@item Other issues as yet unnamed... -@end itemize - -Windows users who'd like to make use of IDLWAVE's context-aware HTML -help can skip the browser and use the HTMLHelp functionality directly. -@xref{Help with HTML Documentation}. - -@html - -@end html -@node Troubleshooting, GNU Free Documentation License, Windows and MacOS, Top -@appendix Troubleshooting -@cindex Troubleshooting - -Although IDLWAVE usually installs and works without difficulty, a few -common problems and their solutions are documented below. - -@enumerate - -@item @strong{Whenever an IDL error occurs or a breakpoint is hit, I get -errors or strange behavior when I try to type anything into some of my -IDLWAVE buffers.} - -This is a @emph{feature}, not an error. You're in @emph{Electric -Debug Mode} (@pxref{Electric Debug Mode}). You should see -@code{*Debugging*} in the mode-line. The buffer is read-only and all -debugging and examination commands are available as single keystrokes; -@kbd{C-?} lists these shortcuts. Use @kbd{q} to quit the mode, and -customize the variable @code{idlwave-shell-automatic-electric-debug} -if you prefer not to enter electric debug on breakpoints@dots{} but -you really should try it before you disable it! You can also -customize this variable to enter debug mode when errors are -encountered. - -@item @strong{I get errors like @samp{Searching for program: no such -file or directory, idl} when attempting to start the IDL shell.} - -IDLWAVE needs to know where IDL is in order to run it as a process. -By default, it attempts to invoke it simply as @samp{idl}, which -presumes such an executable is on your search path. You need to -ensure @samp{idl} is on your @samp{$PATH}, or specify the full -pathname to the idl program with the variable -@code{idlwave-shell-explicit-file-name}. Note that you may need to -set your shell search path in two places when running Emacs as an Aqua -application with MacOSX; see the next topic. - -@item @strong{IDLWAVE is disregarding my @samp{IDL_PATH} which I set -under MacOSX} - -If you run Emacs directly as an Aqua application, rather than from the -console shell, the environment is set not from your usual shell -configuration files (e.g. @file{.cshrc}), but from the file -@file{~/.MacOSX/environment.plist}. Either include your path settings -there, or start Emacs and IDLWAVE from the shell. - -@item @strong{I get errors like @samp{Symbol's function is void: -overlayp}} - -You don't have the @samp{fsf-compat} package installed, which IDLWAVE -needs to run under XEmacs. Install it, or find an XEmacs distribution -which includes it by default. - -@item @strong{I'm getting errors like @samp{Symbol's value as variable is void: -cl-builtin-gethash} on completion or routine info.} - -This error arises if you upgraded Emacs from 20.x to 21.x without -re-installing IDLWAVE. Old Emacs and new Emacs are not byte-compatible -in compiled lisp files. Presumably, you kept the original .elc files in -place, and this is the source of the error. If you recompile (or just -"make; make install") from source, it should resolve this problem. -Another option is to recompile the @file{idlw*.el} files by hand using -@kbd{M-x byte-compile-file}. - -@item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches -windows on my desktop.} - -Your system is trapping @kbd{M-@key{TAB}} and using it for its own -nefarious purposes: Emacs never sees the keystrokes. On many Unix -systems, you can reconfigure your window manager to use another key -sequence for switching among windows. Another option is to use the -equivalent sequence @kbd{@key{ESC}-@key{TAB}}. - -@item @strong{When stopping at breakpoints or errors, IDLWAVE does not -seem to highlight the relevant line in the source.} - -IDLWAVE scans for error and halt messages and highlights the stop -location in the correct file. However, if you've changed the system -variable @samp{!ERROR_STATE.MSG_PREFIX}, it is unable to parse these -message correctly. Don't do that. - -@item @strong{IDLWAVE doesn't work correctly when using ENVI.} - -Though IDLWAVE was not written with ENVI in mind, it works just fine -with it, as long as you update the prompt it's looking for (@samp{IDL> -} by default). You can do this with the variable -@code{idlwave-shell-prompt-pattern} (@pxref{Starting the Shell}), e.g., -in your @file{.emacs}: - -@lisp -(setq idlwave-shell-prompt-pattern "^\r? ?\\(ENVI\\|IDL\\)> ") -@end lisp - -@item @strong{Attempts to set breakpoints fail: no breakpoint is -indicated in the IDLWAVE buffer.} - -IDL changed its breakpoint reporting format starting with IDLv5.5. The -first version of IDLWAVE to support the new format is IDLWAVE v4.10. If -you have an older version and are using IDL >v5.5, you need to upgrade, -and/or make sure your recent version of IDLWAVE is being found on the -Emacs load-path (see the next entry). You can list the version being -used with @kbd{C-h v idlwave-mode-version @key{RET}}. - -@item @strong{I installed a new version of IDLWAVE, but the old -version is still being used} or @strong{IDLWAVE works, but when I -tried to install the optional modules @file{idlw-roprompt.el} or -@file{idlw-complete-structtag}, I get errors like @samp{Cannot open -load file}}. - -The problem is that your Emacs is not finding the version of IDLWAVE you -installed. Many Emacsen come with an older bundled copy of IDLWAVE -(e.g. v4.7 for Emacs 21.x), which is likely what's being used instead. -You need to make sure your Emacs @emph{load-path} contains the directory -where IDLWAVE is installed (@file{/usr/local/share/emacs/site-lisp}, by -default), @emph{before} Emacs's default search directories. You can -accomplish this by putting the following in your @file{.emacs}: - -@lisp -(setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path)) -@end lisp - -@noindent You can check on your load-path value using @kbd{C-h v -load-path @key{RET}}, and @kbd{C-h m} in an IDLWAVE buffer should show -you the version Emacs is using. - -@item @strong{IDLWAVE is screwing up the formatting of my @file{.idl} files.} - -Actually, this isn't IDLWAVE at all, but @samp{idl-mode}, an unrelated -programming mode for CORBA's Interface Definition Language (you should -see @samp{(IDL)}, not @samp{(IDLWAVE)} in the mode-line). One -solution: don't name your file @file{.idl}, but rather @file{.pro}. -Another solution: make sure @file{.idl} files load IDLWAVE instead of -@samp{idl-mode} by adding the following to your @file{.emacs}: - -@lisp -(setcdr (rassoc 'idl-mode auto-mode-alist) 'idlwave-mode) -@end lisp - -@item @strong{The routine info for my local routines is out of date!} - -IDLWAVE collects routine info from various locations (@pxref{Routine -Information Sources}). Routines in files visited in a buffer or -compiled in the shell should be up to date. For other routines, the -information is only as current as the most recent scan. If you have a -rapidly changing set of routines, and you'd like the latest routine -information to be available for it, one powerful technique is to make -use of the library catalog tool, @samp{idlwave_catalog}. Simply add a -line to your @samp{cron} file (@samp{crontab -e} will let you edit this -on some systems), like this - -@example -45 3 * * 1-5 (cd /path/to/myidllib; /path/to/idlwave_catalog MyLib) -@end example - -@noindent where @samp{MyLib} is the name of your library. This will -rescan all @file{.pro} files at or below @file{/path/to/myidllib} every -week night at 3:45am. You can even scan site-wide libraries with this -method, and the most recent information will be available to all users. -Since the scanning is very fast, there is very little impact. - -@item @strong{All the Greek-font characters in the HTML help are -displayed as Latin characters!} - -Unfortunately, the HTMLHelp files RSI provides attempt to switch to -@samp{Symbol} font to display Greek characters, which is not really an -permitted method for doing this in HTML. There is a "workaround" for -some browsers: @xref{HTML Help Browser Tips}. - -@item @strong{In the shell, my long commands are truncated at 256 characters!} - -This actually happens when running IDL in an XTerm as well. There are -a couple of workarounds: @code{define_key,/control,'^d'} (e.g. in -your @file{$IDL_STARTUP} file) will disable the @samp{EOF} character -and give you a 512 character limit. You won't be able to use -@key{C-d} to quit the shell, however. Another possibility is -@code{!EDIT_INPUT=0}, which gives you an @emph{infinite} limit (OK, a -memory-bounded limit), but disables the processing of background -widget events (those with @code{/NO_BLOCK} passed to @code{XManager}). - -@item @strong{When I invoke IDL HTML help on a routine, the page which -is loaded is one page off, e.g. for @code{CONVERT_COORD}, I get -@code{CONTOUR}.} - -You have a mismatch between your help index and the HTML help package -you downloaded. You need to ensure you download a ``downgrade kit'' if -you are using anything older than the latest HTML help package. A new -help package appears with each IDL release (assuming the documentation -is updated). -Starting with IDL 6.2, the HTML help and its catalog are -distributed with IDL, and so should never be inconsistent. - -@item @strong{I get errors such as @samp{void-variable -browse-url-browser-function} or similar when attempting to load IDLWAVE -under XEmacs.} - -You don't have the @samp{browse-url} (or other required) XEmacs package. -Unlike Emacs, XEmacs distributes many packages separately from the -main program. IDLWAVE is actually among these, but is not always the -most up to date. When installing IDLWAVE as an XEmacs package, it -should prompt you for required additional packages. When installing it -from source, it won't and you'll get this error. The easiest solution -is to install all the packages when you install XEmacs (the so-called -@samp{sumo} bundle). The minimum set of XEmacs packages required by -IDLWAVE is @samp{fsf-compat, xemacs-base, mail-lib}. - -@end enumerate - -@node GNU Free Documentation License, Index, Troubleshooting, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index, , GNU Free Documentation License, Top -@unnumbered Index -@printindex cp - -@bye diff --git a/doc/misc/info.texi b/doc/misc/info.texi deleted file mode 100644 index 8952bfb9122..00000000000 --- a/doc/misc/info.texi +++ /dev/null @@ -1,1515 +0,0 @@ -\input texinfo.tex @c -*-texinfo-*- -@c We must \input texinfo.tex instead of texinfo, otherwise make -@c distcheck in the Texinfo distribution fails, because the texinfo Info -@c file is made first, and texi2dvi must include . first in the path. -@comment %**start of header -@setfilename info.info -@settitle Info -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@comment %**end of header - -@copying -This file describes how to use Info, the on-line, menu-driven GNU -documentation system. - -Copyright @copyright{} 1989, 1992, 1996-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Texinfo documentation system -@direntry -* Info: (info). How to use the documentation browsing system. -@end direntry - -@titlepage -@title Info -@subtitle The online, hyper-text GNU documentation system -@author Brian Fox -@author and the GNU Texinfo community -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Info: An Introduction - -The GNU Project distributes most of its on-line manuals in the -@dfn{Info format}, which you read using an @dfn{Info reader}. You are -probably using an Info reader to read this now. - -There are two primary Info readers: @code{info}, a stand-alone program -designed just to read Info files (@pxref{Top,,What is Info?, -info-stnd, GNU Info}), and the @code{info} package in GNU Emacs, a -general-purpose editor. At present, only the Emacs reader supports -using a mouse. - -@ifinfo -If you are new to the Info reader and want to learn how to use it, -type the command @kbd{h} now. It brings you to a programmed -instruction sequence. - -To read about advanced Info commands, type @kbd{n} twice. This -brings you to @cite{Advanced Info Commands}, skipping over the `Getting -Started' chapter. -@end ifinfo -@end ifnottex - -@insertcopying - -@menu -* Getting Started:: Getting started using an Info reader. -* Advanced:: Advanced Info commands. -* Expert Info:: Info commands for experts. -* Index:: An index of topics, commands, and variables. -@end menu - -@node Getting Started, Advanced, Top, Top -@comment node-name, next, previous, up -@chapter Getting Started - -This first part of this Info manual describes how to get around inside -of Info. The second part of the manual describes various advanced -Info commands. The third part briefly explains how to generate Info -files from Texinfo files, and describes how to write an Info file -by hand. - -@ifnotinfo -This manual is primarily designed for browsing with an Info reader -program on a computer, so that you can try Info commands while reading -about them. Reading it on paper or with an HTML browser is less -effective, since you must take it on faith that the commands described -really do what the manual says. By all means go through this manual -now that you have it; but please try going through the on-line version -as well. - -@cindex Info reader, how to invoke -@cindex entering Info -There are two ways of looking at the online version of this manual: - -@enumerate -@item -Type @code{info} at your shell's command line. This approach uses a -stand-alone program designed just to read Info files. - -@item -Type @code{emacs} at the command line; then type @kbd{C-h i} -(@kbd{Control-h}, followed by @kbd{i}). This approach uses the Info -mode of the Emacs editor. -@end enumerate - -In either case, then type @kbd{mInfo} (just the letters), followed by -@key{RET}---the ``Return'' or ``Enter'' key. At this point, you should -be ready to follow the instructions in this manual as you read them on -the screen. -@c FIXME! (pesch@cygnus.com, 14 dec 1992) -@c Is it worth worrying about what-if the beginner goes to somebody -@c else's Emacs session, which already has an Info running in the middle -@c of something---in which case these simple instructions won't work? -@end ifnotinfo - -@menu -* Help-Small-Screen:: Starting Info on a Small Screen. -* Help:: How to use Info. -* Help-P:: Returning to the Previous node. -* Help-^L:: The Space, DEL, B and ^L commands. -* Help-Inv:: Invisible text in Emacs Info. -* Help-M:: Menus. -* Help-Xref:: Following cross-references. -* Help-Int:: Some intermediate Info commands. -* Help-Q:: Quitting Info. -@end menu - -@node Help-Small-Screen -@section Starting Info on a Small Screen - -@ifnotinfo -(In Info, you only see this section if your terminal has a small -number of lines; most readers pass by it without seeing it.) -@end ifnotinfo - -@cindex small screen, moving around -Since your terminal has a relatively small number of lines on its -screen, it is necessary to give you special advice at the beginning. - -If the entire text you are looking at fits on the screen, the text -@samp{All} will be displayed at the bottom of the screen. In the -stand-alone Info reader, it is displayed at the bottom right corner of -the screen; in Emacs, it is displayed on the modeline. If you see the -text @samp{Top} instead, it means that there is more text below that -does not fit. To move forward through the text and see another screen -full, press @key{SPC}, the Space bar. To move back up, press the key -labeled @samp{Backspace} or @samp{DEL} (on some keyboards, this key -might be labeled @samp{Delete}). - -@ifinfo -Here are 40 lines of junk, so you can try @key{SPC} and @key{DEL} and -see what they do. At the end are instructions of what you should do -next. - -@format -This is line 20 -This is line 21 -This is line 22 -This is line 23 -This is line 24 -This is line 25 -This is line 26 -This is line 27 -This is line 28 -This is line 29 -This is line 30 -This is line 31 -This is line 32 -This is line 33 -This is line 34 -This is line 35 -This is line 36 -This is line 37 -This is line 38 -This is line 39 -This is line 40 -This is line 41 -This is line 42 -This is line 43 -This is line 44 -This is line 45 -This is line 46 -This is line 47 -This is line 48 -This is line 49 -This is line 50 -This is line 51 -This is line 52 -This is line 53 -This is line 54 -This is line 55 -This is line 56 -This is line 57 -This is line 58 -This is line 59 -@end format - -If you have managed to get here, go back to the beginning with -@kbd{DEL} (or @key{BACKSPACE}), and come back here again, then you -understand the about the @samp{Space} and @samp{Backspace} keys. So -now type an @kbd{n}---just one character; don't type the quotes and -don't type the Return key afterward---to get to the normal start of -the course. -@end ifinfo - -@node Help, Help-P, Help-Small-Screen, Getting Started -@comment node-name, next, previous, up -@section How to use Info - -You are talking to the program Info, for reading documentation. - - There are two ways to use Info: from within Emacs or as a -stand-alone reader that you can invoke from a shell using the command -@command{info}. - -@cindex node, in Info documents - Right now you are looking at one @dfn{Node} of Information. -A node contains text describing a specific topic at a specific -level of detail. This node's topic is ``how to use Info''. The mode -line says that this is node @samp{Help} in the file @file{info}. - -@cindex header of Info node - The top line of a node is its @dfn{header}. This node's header -(look at it now) says that the @samp{Next} node after this one is the -node called @samp{Help-P}. An advanced Info command lets you go to -any node whose name you know. In the stand-alone Info reader program, -the header line shows the names of this node and the Info file as -well. In Emacs, the header line is displayed with a special typeface, -and remains at the top of the window all the time even if you scroll -through the node. - - Besides a @samp{Next}, a node can have a @samp{Previous} link, or an -@samp{Up} link, or both. As you can see, this node has all of these -links. - -@kindex n @r{(Info mode)} - Now it is time to move on to the @samp{Next} node, named @samp{Help-P}. - -@format ->> Type @kbd{n} to move there. Type just one character; - do not type the quotes and do not type a @key{RET} afterward. -@end format - -@noindent -@samp{>>} in the margin means it is really time to try a command. - -@format ->> If you are in Emacs and have a mouse, and if you already practiced - typing @kbd{n} to get to the next node, click now with the left - mouse button on the @samp{Next} link to do the same ``the mouse way''. -@end format - -@node Help-P, Help-^L, Help, Getting Started -@comment node-name, next, previous, up -@section Returning to the Previous node - -@kindex p @r{(Info mode)} -This node is called @samp{Help-P}. The @samp{Previous} node, as you see, -is @samp{Help}, which is the one you just came from using the @kbd{n} -command. Another @kbd{n} command now would take you to the next -node, @samp{Help-^L}. - -@format ->> But do not type @kbd{n} yet. First, try the @kbd{p} command, or - (in Emacs) click on the @samp{Prev} link. That takes you to - the @samp{Previous} node. Then use @kbd{n} to return here. -@end format - - If you read this in Emacs, you will see an @samp{Info} item in the -menu bar, close to its right edge. Clicking the mouse on the -@samp{Info} menu-bar item opens a menu of commands which include -@samp{Next} and @samp{Previous} (and also some others which you didn't yet -learn about). - - This all probably seems insultingly simple so far, but @emph{please -don't} start skimming. Things will get complicated soon enough! -Also, please do not try a new command until you are told it is time -to. You could make Info skip past an important warning that was -coming up. - -@format ->> Now do an @kbd{n}, or (in Emacs) click the middle mouse button on - the @samp{Next} link, to get to the node @samp{Help-^L} and learn more. -@end format - -@node Help-^L, Help-Inv, Help-P, Getting Started -@comment node-name, next, previous, up -@section The Space, DEL, B and ^L commands - - This node's mode line tells you that you are now at node -@samp{Help-^L}, and the header line tells you that @kbd{p} would get -you back to @samp{Help-P}. The node's title is highlighted and may be -underlined as well; it says what the node is about. - - This is a big node and it does not all fit on your display screen. -You can tell that there is more that is not visible because you -can see the text @samp{Top} rather than @samp{All} near the bottom of -the screen. - -@kindex SPC @r{(Info mode)} -@kindex DEL @r{(Info mode)} -@kindex BACKSPACE @r{(Info mode)} -@findex Info-scroll-up -@findex Info-scroll-down - The @key{SPC}, @key{BACKSPACE} (or @key{DEL})@footnote{The key which -we call ``Backspace or DEL'' in this manual is labeled differently on -different keyboards. Look for a key which is a little ways above the -@key{ENTER} or @key{RET} key and which you normally use outside Emacs -to erase the character before the cursor, i.e.@: the character you -typed last. It might be labeled @samp{Backspace} or @samp{<-} or -@samp{DEL}, or sometimes @samp{Delete}.} and @kbd{b} commands exist to -allow you to ``move around'' in a node that does not all fit on the -screen at once. @key{SPC} moves forward, to show what was below the -bottom of the screen. @key{DEL} or @key{BACKSPACE} moves backward, to -show what was above the top of the screen (there is not anything above -the top until you have typed some spaces). - -@format ->> Now try typing a @key{SPC} (afterward, type a @key{BACKSPACE} to - return here). -@end format - - When you type the @key{SPC}, the two lines that were at the bottom of -the screen appear at the top, followed by more lines. @key{DEL} or -@key{BACKSPACE} takes the two lines from the top and moves them to the -bottom, @emph{usually}, but if there are not a full screen's worth of -lines above them they may not make it all the way to the bottom. - - If you are reading this in Emacs, note that the header line is -always visible, never scrolling off the display. That way, you can -always see the @samp{Next}, @samp{Prev}, and @samp{Up} links, and you -can conveniently go to one of these links at any time by -clicking the middle mouse button on the link. - -@cindex reading Info documents top to bottom -@cindex Info documents as tutorials - @key{SPC} and @key{DEL} not only move forward and backward through -the current node. They also move between nodes. @key{SPC} at the end -of a node moves to the next node; @key{DEL} (or @key{BACKSPACE}) at -the beginning of a node moves to the previous node. In effect, these -commands scroll through all the nodes in an Info file as a single -logical sequence. You can read an entire manual top to bottom by just -typing @key{SPC}, and move backward through the entire manual from -bottom to top by typing @key{DEL} (or @key{BACKSPACE}). - - In this sequence, a node's subnodes appear following their parent. -If a node has a menu, @key{SPC} takes you into the subnodes listed in -the menu, one by one. Once you reach the end of a node, and have seen -all of its subnodes, @key{SPC} takes you to the next node or to the -parent's next node. - -@kindex PAGEUP @r{(Info mode)} -@kindex PAGEDOWN @r{(Info mode)} - Many keyboards nowadays have two scroll keys labeled @samp{PageUp} -and @samp{PageDown} (or maybe @samp{Prior} and @samp{Next}). If your -keyboard has these keys, you can use them to move forward and backward -through the text of one node, like @key{SPC} and @key{BACKSPACE} (or -@key{DEL}). However, @key{PAGEUP} and @key{PAGEDOWN} keys never -scroll beyond the beginning or the end of the current node. - -@kindex C-l @r{(Info mode)} - If your screen is ever garbaged, you can tell Info to display it -again by typing @kbd{C-l} (@kbd{Control-L}---that is, hold down -@key{CTRL} and type @kbd{L} or @kbd{l}). - -@format ->> Type @kbd{C-l} now. -@end format - -@kindex b @r{(Info mode)} - To move back to the beginning of the node you are on, you can type -the @key{BACKSPACE} key (or @key{DEL}) many times. You can also type -@kbd{b} just once. @kbd{b} stands for ``beginning.'' - -@format ->> Try that now. (We have put in enough verbiage to push this past - the first screenful, but screens are so big nowadays that perhaps it - isn't enough. You may need to shrink your Emacs or Info window.) - Then come back, by typing @key{SPC} one or more times. -@end format - -@kindex ? @r{(Info mode)} -@findex Info-summary - You have just learned a considerable number of commands. If you -want to use one but have trouble remembering which, you should type -@kbd{?}, which displays a brief list of commands. When you are -finished looking at the list, make it go away by typing @key{SPC} -repeatedly. - -@format ->> Type a @key{?} now. Press @key{SPC} to see consecutive screenfuls of - the list until finished. Then type @key{SPC} several times. If - you are using Emacs, the help will then go away automatically. -@end format - - (If you are using the stand-alone Info reader, type @kbd{C-x 0} to -return here, that is---press and hold @key{CTRL}, type an @kbd{x}, -then release @key{CTRL} and @kbd{x}, and press @kbd{0}; that's a zero, -not the letter ``o''.) - - From now on, you will encounter large nodes without warning, and -will be expected to know how to use @key{SPC} and @key{BACKSPACE} to -move around in them without being told. Since not all terminals have -the same size screen, it would be impossible to warn you anyway. - -@format ->> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link, - to visit the next node. -@end format - -@node Help-Inv, Help-M, Help-^L, Getting Started -@comment node-name, next, previous, up -@section Invisible text in Emacs Info - - Before discussing menus, we need to make some remarks that are only -relevant to users reading Info using Emacs. Users of the stand-alone -version can skip this node by typing @kbd{]} now. - -@cindex invisible text in Emacs - In Emacs, certain text that appears in the stand-alone version is -normally hidden, technically because it has the @samp{invisibility} -property. Invisible text is really a part of the text. It becomes -visible (by default) after killing and yanking, it appears in printed -output, it gets saved to file just like any other text, and so on. -Thus it is useful to know it is there. - -@findex visible-mode -You can make invisible text visible by using the command @kbd{M-x -visible-mode}. Visible mode is a minor mode, so using the command a -second time will make the text invisible again. Watch the effects of -the command on the ``menu'' below and the top line of this node. - -If you prefer to @emph{always} see the invisible text, you can set -@code{Info-hide-note-references} to @code{nil}. Enabling Visible mode -permanently is not a real alternative, because Emacs Info also uses -(although less extensively) another text property that can change the -text being displayed, the @samp{display} property. Only the -invisibility property is affected by Visible mode. When, in this -tutorial, we refer to the @samp{Emacs} behavior, we mean the -@emph{default} Emacs behavior. - -Now type @kbd{]}, to learn about the @kbd{]} and @kbd{[} commands. - -@menu -* ]: Help-]. Node telling about ]. -* stuff: Help-]. Same node. -* Help-]:: Yet again, same node. -@end menu - -@node Help-], , , Help-Inv -@subsection The @kbd{]} and @kbd{[} commands - -If you type @kbd{n} now, you get an error message saying that this -node has no next node. Similarly, if you type @kbd{p}, the error -message tells you that there is no previous node. (The exact message -depends on the Info reader you use.) This is because @kbd{n} and -@kbd{p} carry you to the next and previous node @emph{at the same -level}. The present node is contained in a menu (see next) of the -node you came from, and hence is considered to be at a lower level. -It is the only node in the previous node's menu (even though it was -listed three times). Hence it has no next or previous node that -@kbd{n} or @kbd{p} could move to. - -If you systematically move through a manual by typing @kbd{n}, you run -the risk of skipping many nodes. You do not run this risk if you -systematically use @kbd{@key{SPC}}, because, when you scroll to the -bottom of a node and type another @kbd{@key{SPC}}, then this carries -you to the following node in the manual @emph{regardless of level}. -If you immediately want to go to that node, without having to scroll -to the bottom of the screen first, you can type @kbd{]}. - -Similarly, @kbd{@key{BACKSPACE}} carries you to the preceding node -regardless of level, after you scrolled to the beginning of the -present node. If you want to go to the preceding node immediately, -you can type @kbd{[}. - -For instance, typing this sequence will come back here in three steps: -@kbd{[ n [}. To do the same backward, type @kbd{] p ]}. - -Now type @kbd{]} to go to the next node and learn about menus. - -@node Help-M, Help-Xref, Help-Inv, Getting Started -@comment node-name, next, previous, up -@section Menus and the @kbd{m} command - -@cindex menus in an Info document -@cindex Info menus - With only the @kbd{n} (next), @kbd{p} (previous), @kbd{@key{SPC}}, -@kbd{@key{BACKSPACE}}, @kbd{]} and @kbd{[} commands for moving between -nodes, nodes are restricted to a linear sequence. Menus allow a -branching structure. A menu is a list of other nodes you can move to. -It is actually just part of the text of the node formatted specially -so that Info can interpret it. The beginning of a menu is always -identified by a line which starts with @w{@samp{* Menu:}}. A node -contains a menu if and only if it has a line in it which starts that -way. The only menu you can use at any moment is the one in the node -you are in. To use a menu in any other node, you must move to that -node first. - - After the start of the menu, each line that starts with a @samp{*} -identifies one subtopic. The line usually contains a brief name for -the subtopic (followed by a @samp{:}, normally hidden in Emacs), the -name of the node that talks about that subtopic (again, normally -hidden in Emacs), and optionally some further description of the -subtopic. Lines in the menu that do not start with a @samp{*} have no -special meaning---they are only for the human reader's benefit and do -not define additional subtopics. Here is an example: - -@example -* Foo: Node about FOO. This tells about FOO. -@end example - -The subtopic name is Foo, and the node describing it is @samp{Node -about FOO}. The rest of the line is just for the reader's -Information. [[ But this line is not a real menu item, simply because -there is no line above it which starts with @w{@samp{* Menu:}}. Also, -in a real menu item, the @samp{*} would appear at the very start of -the line. This is why the ``normally hidden'' text in Emacs, namely -@samp{: Node about FOO.}, is actually visible in this example, even -when Visible mode is off.]] - - When you use a menu to go to another node (in a way that will be -described soon), what you specify is the subtopic name, the first -thing in the menu line. Info uses it to find the menu line, extracts -the node name from it, and goes to that node. The reason that there -is both a subtopic name and a node name is that the node name must be -meaningful to the computer and may therefore have to be ugly looking. -The subtopic name can be chosen just to be convenient for the user to -specify. Often the node name is convenient for the user to specify -and so both it and the subtopic name are the same. There is an -abbreviation for this: - -@example -* Foo:: This tells about FOO. -@end example - -@noindent -This means that the subtopic name and node name are the same; they are -both @samp{Foo}. (The @samp{::} is normally hidden in Emacs.) - -@format ->> Now use @key{SPC} to find the menu in this node, then come back to - the front with a @kbd{b} and some @key{SPC}s. As you see, a menu is - actually visible in its node. If you cannot find a menu in a node - by looking at it, then the node does not have a menu and the - @kbd{m} command is not available. -@end format - -If you keep typing @key{SPC} once the menu appears on the screen, it -will move to another node (the first one in the menu). If that -happens, type @key{BACKSPACE} to come back. - -@kindex m @r{(Info mode)} - The command to go to one of the subnodes is @kbd{m}. This is very -different from the commands you have used: it is a command that -prompts you for more input. - - The Info commands you know do not need additional input; when you -type one of them, Info processes it instantly and then is ready for -another command. The @kbd{m} command is different: it needs to know -the @dfn{name of the subtopic}. Once you have typed @kbd{m}, Info -tries to read the subtopic name. - - Now, in the stand-alone Info, look for the line containing many -dashes near the bottom of the screen. (This is the stand-alone -equivalent for the mode line in Emacs.) There is one more line -beneath that one, but usually it is blank. (In Emacs, this is the -echo area.) When it is blank, Info is ready for a command, such as -@kbd{n} or @kbd{b} or @key{SPC} or @kbd{m}. If that line contains -text ending in a colon, it means Info is reading more input for the -last command. You can't type an Info command then, because Info is -trying to read input, not commands. You must either give the input -and finish the command you started, or type @kbd{Control-g} to cancel -the command. When you have done one of those things, the input entry -line becomes blank again. Then you can type Info commands again. - -@findex Info-menu - The command to go to a subnode via a menu is @kbd{m}. After you type -the @kbd{m}, the line at the bottom of the screen says @samp{Menu item: }. -You must then type the name of the subtopic you want, and end it with -a @key{RET}. - -@cindex abbreviating Info subnodes - You can abbreviate the subtopic name. If the abbreviation is not -unique, the first matching subtopic is chosen. Some menus put -the shortest possible abbreviation for each subtopic name in capital -letters, so you can see how much you need to type. It does not -matter whether you use upper case or lower case when you type the -subtopic. You should not put any spaces at the end, or inside of the -item name, except for one space where a space appears in the item in -the menu. - -@cindex completion of Info node names - You can also use the @dfn{completion} feature to help enter the -subtopic name. If you type the @key{TAB} key after entering part of a -name, it will fill in more of the name---as much as Info can deduce -from the part you have entered. - - If you move the cursor to one of the menu subtopic lines, then you do -not need to type the argument: you just type a @key{RET}, and it -stands for the subtopic of the line you are on. You can also click -the middle mouse button directly on the subtopic line to go there. - -Here is a menu to give you a chance to practice. This menu gives you -three ways of going to one place, Help-FOO: - -@menu -* Foo: Help-FOO. A node you can visit for fun. -* Bar: Help-FOO. We have made two ways to get to the same place. -* Help-FOO:: And yet another! -@end menu - -(Turn Visible mode on if you are using Emacs.) - -@format ->> Now type just an @kbd{m} and see what happens: -@end format - - Now you are ``inside'' an @kbd{m} command. Commands cannot be used -now; the next thing you will type must be the name of a subtopic. - - You can change your mind about doing the @kbd{m} by typing -@kbd{Control-g}. - -@format ->> Try that now; notice the bottom line clear. -@end format - -@format ->> Then type another @kbd{m}. -@end format - -@format ->> Now type @kbd{BAR}, the item name. Do not type @key{RET} yet. -@end format - - While you are typing the item name, you can use the @key{DEL} (or -@key{BACKSPACE}) key to cancel one character at a time if you make a -mistake. - -@format ->> Press @key{DEL} to cancel the @samp{R}. You could type another @kbd{R} - to replace it. But you do not have to, since @samp{BA} is a valid - abbreviation. -@end format - -@format ->> Now you are ready to go. Type a @key{RET}. -@end format - - After visiting @samp{Help-FOO}, you should return here. - - Another way to move to the menu subtopic lines and between them is -to type @key{TAB}. Each time you type a @key{TAB}, you move to the -next subtopic line. To move to a previous subtopic line in the -stand-alone reader, type @kbd{M-@key{TAB}}---that is, press and hold -the @key{META} key and then press @key{TAB}. (On some keyboards, the -@key{META} key might be labeled @samp{Alt}.) In Emacs Info, type -@kbd{S-@key{TAB}} to move to a previous subtopic line (press and hold -the @key{Shift} key and then press @key{TAB}). - - Once you move cursor to a subtopic line, press @key{RET} to go to -that subtopic's node. - -@cindex mouse support in Info mode -@kindex Mouse-2 @r{(Info mode)} - If your terminal supports a mouse, you have yet another way of going -to a subtopic. Move your mouse pointer to the subtopic line, -somewhere between the beginning @samp{*} and the colon @samp{:} which -ends the subtopic's brief name. You will see the subtopic's name -change its appearance (usually, its background color will change), and -the shape of the mouse pointer will change if your platform supports -that. After a while, if you leave the mouse on that spot, a small -window will pop up, saying ``Mouse-2: go to that node,'' or the same -message may appear at the bottom of the screen. - - @kbd{Mouse-2} is the second button of your mouse counting from the -left---the middle button on a 3-button mouse. (On a 2-button mouse, -you may have to press both buttons together to ``press the middle -button''.) The message tells you pressing @kbd{Mouse-2} with the -current position of the mouse pointer (on subtopic in the menu) will -go to that subtopic. - -@findex Info-mouse-follow-nearest-node - More generally, @kbd{Mouse-2} in an Info buffer finds the nearest -link to another node and goes there. For example, near a cross -reference it acts like @kbd{f}, in a menu it acts like @kbd{m}, on the -node's header line it acts like @kbd{n}, @kbd{p}, or @kbd{u}, etc. At -end of the node's text @kbd{Mouse-2} moves to the next node, or up if -there's no next node. - -@format ->> Type @kbd{n} to see more commands. -@end format - -@node Help-FOO, , , Help-M -@subsection The @kbd{u} command - - Congratulations! This is the node @samp{Help-FOO}. It has an @samp{Up} -pointer @samp{Help-M}, the node you just came from via the @kbd{m} -command. This is the usual convention---the nodes you reach from a menu -have @samp{Up} nodes that lead back to the menu. Menus move Down in the -tree, and @samp{Up} moves Up. @samp{Previous}, on the other hand, is -usually used to ``stay on the same level but go backwards''. - -@kindex u @r{(Info mode)} -@findex Info-up - You can go back to the node @samp{Help-M} by typing the command -@kbd{u} for ``Up''. This puts you at the menu subtopic line pointing -to the subnode that the @kbd{u} command brought you from. (Some Info -readers may put you at the @emph{front} of the node instead---to get -back to where you were reading, you have to type some @key{SPC}s.) - - Another way to go Up is to click @kbd{Mouse-2} on the @samp{Up} -pointer shown in the header line (provided that you have a mouse). - -@format ->> Now type @kbd{u} to move back up to @samp{Help-M}. -@end format - -@node Help-Xref, Help-Int, Help-M, Getting Started -@comment node-name, next, previous, up -@section Following Cross-References - -@cindex cross references in Info documents - In Info documentation, you will see many @dfn{cross references}. -Cross references look like this: @xref{Help-Cross, Cross}. That text -is a real, live cross reference, whose name is @samp{Cross} and which -points to the node named @samp{Help-Cross}. (The node name is hidden -in Emacs. Do @kbd{M-x visible-mode} to show or hide it.) - -@kindex f @r{(Info mode)} -@findex Info-follow-reference - You can follow a cross reference by moving the cursor to it and -press @key{RET}, just as in a menu. In Emacs, you can also click -@kbd{Mouse-1} on a cross reference to follow it; you can see that the -cross reference is mouse-sensitive by moving the mouse pointer to the -reference and watching how the underlying text and the mouse pointer -change in response. - - Another way to follow a cross reference is to type @kbd{f} and then -specify the name of the cross reference (in this case, @samp{Cross}) -as an argument. For this command, it does not matter where the cursor -was. If the cursor is on or near a cross reference, @kbd{f} suggests -that reference name in parentheses as the default; typing @key{RET} -will follow that reference. However, if you type a different -reference name, @kbd{f} will follow the other reference which has that -name. - -@format ->> Type @kbd{f}, followed by @kbd{Cross}, and then @key{RET}. -@end format - - As you enter the reference name, you can use the @key{DEL} (or -@key{BACKSPACE}) key to edit your input. If you change your mind -about following any reference, you can use @kbd{Control-g} to cancel -the command. Completion is available in the @kbd{f} command; you can -complete among all the cross reference names in the current node by -typing a @key{TAB}. - - To get a list of all the cross references in the current node, you -can type @kbd{?} after an @kbd{f}. The @kbd{f} continues to await a -cross reference name even after displaying the list, so if you don't -actually want to follow a reference, you should type a @kbd{Control-g} -to cancel the @kbd{f}. - -@format ->> Type @kbd{f?} to get a list of the cross references in this node. Then - type a @kbd{Control-g} and see how the @samp{f} gives up. -@end format - - The @key{TAB}, @kbd{M-@key{TAB}} and @kbd{S-@key{TAB}} keys, -which move between menu items in a menu, also move between cross -references outside of menus. - - Sometimes a cross reference (or a node) can lead to another file (in -other words another ``manual''), or, on occasion, even a file on a -remote machine (although Info files distributed with Emacs or the -stand-alone Info avoid using remote links). Such a cross reference -looks like this: @xref{Top,, Overview of Texinfo, texinfo, Texinfo: -The GNU Documentation Format}. (After following this link, type -@kbd{l} to get back to this node.) Here the name @samp{texinfo} -between parentheses refers to the file name. This file name appears -in cross references and node names if it differs from the current -file, so you can always know that you are going to be switching to -another manual and which one. - -However, Emacs normally hides some other text in cross-references. -If you put your mouse over the cross reference, then the information -appearing in a separate box (tool tip) or in the echo area will show -the full cross-reference including the file name and the node name of -the cross reference. If you have a mouse, just leave it over the -cross reference @xref{Top,, Overview of Texinfo, texinfo, Texinfo: -The GNU Documentation Format}, and watch what happens. If you -always like to have that information visible without having to move -your mouse over the cross reference, use @kbd{M-x visible-mode}, or -set @code{Info-hide-note-references} to a value other than @code{t} -(@pxref{Emacs Info Variables}). - -@format ->> Now type @kbd{n} to learn more commands. -@end format - -@node Help-Int, Help-Q, Help-Xref, Getting Started -@comment node-name, next, previous, up -@section Some intermediate Info commands - - The introductory course is almost over; please continue -a little longer to learn some intermediate-level commands. - - Most Info files have an index, which is actually a large node -containing little but a menu. The menu has one menu item for each -topic listed in the index. (As a special feature, menus for indices -may also include the line number within the node of the index entry. -This allows Info readers to go to the exact line of an entry, not just -the start of the containing node.) - - You can get to the index from the main menu of the file with the -@kbd{m} command and the name of the index node; then you can use the -@kbd{m} command again in the index node to go to the node that -describes the topic you want. - - There is also a short-cut Info command, @kbd{i}, which does all of -that for you. It searches the index for a given topic (a string) and -goes to the node which is listed in the index for that topic. -@xref{Search Index}, for a full explanation. - -@kindex l @r{(Info mode)} -@findex Info-history-back -@cindex going back in Info history - If you have been moving around to different nodes and wish to -retrace your steps, the @kbd{l} command (@kbd{l} for @dfn{last}) will -do that, one node-step at a time. As you move from node to node, Info -records the nodes where you have been in a special history list. The -@kbd{l} command revisits nodes in the history list; each successive -@kbd{l} command moves one step back through the history. - -@format ->> Try typing @kbd{p p n} and then three @kbd{l}'s, pausing in between -to see what each @kbd{l} does. You should wind up right back here. -@end format - - Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to -where @emph{you} last were, whereas @kbd{p} always moves to the node -which the header says is the @samp{Previous} node (from this node, the -@samp{Prev} link leads to @samp{Help-Xref}). - -@kindex r @r{(Info mode)} -@findex Info-history-forward -@cindex going forward in Info history - You can use the @kbd{r} command (@code{Info-history-forward} in Emacs) -to revisit nodes in the history list in the forward direction, so that -@kbd{r} will return you to the node you came from by typing @kbd{l}. - -@kindex L @r{(Info mode)} -@findex Info-history -@cindex history list of visited nodes - The @kbd{L} command (@code{Info-history} in Emacs) creates a virtual -node that contains a list of all nodes you visited. You can select -a previously visited node from this menu to revisit it. - -@kindex d @r{(Info mode)} -@findex Info-directory -@cindex go to Directory node - The @kbd{d} command (@code{Info-directory} in Emacs) gets you -instantly to the Directory node. This node, which is the first one -you saw when you entered Info, has a menu which leads (directly or -indirectly, through other menus), to all the nodes that exist. The -Directory node lists all the manuals and other Info documents that -are, or could be, installed on your system. - -@format ->> Try doing a @kbd{d}, then do an @kbd{l} to return here (yes, - @emph{do} return). -@end format - -@kindex t @r{(Info mode)} -@findex Info-top-node -@cindex go to Top node - The @kbd{t} command moves to the @samp{Top} node of the manual. -This is useful if you want to browse the manual's main menu, or select -some specific top-level menu item. The Emacs command run by @kbd{t} -is @code{Info-top-node}. - -@format ->> Now type @kbd{n} to see the last node of the course. -@end format - - @xref{Advanced}, for more advanced Info features. - -@c If a menu appears at the end of this node, remove it. -@c It is an accident of the menu updating command. - -@node Help-Q, , Help-Int, Getting Started -@comment node-name, next, previous, up -@section Quitting Info - -@kindex q @r{(Info mode)} -@findex Info-exit -@cindex quitting Info mode - To get out of Info, back to what you were doing before, type @kbd{q} -for @dfn{Quit}. This runs @code{Info-exit} in Emacs. - - This is the end of the basic course on using Info. You have learned -how to move in an Info document, and how to follow menus and cross -references. This makes you ready for reading manuals top to bottom, -as new users should do when they learn a new package. - - Another set of Info commands is useful when you need to find -something quickly in a manual---that is, when you need to use a manual -as a reference rather than as a tutorial. We urge you to learn -these search commands as well. If you want to do that now, follow this -cross reference to @ref{Advanced}. - -Yet another set of commands are meant for experienced users; you can -find them by looking in the Directory node for documentation on Info. -Finding them will be a good exercise in using Info in the usual -manner. - -@format ->> Type @kbd{d} to go to the Info directory node; then type - @kbd{mInfo} and Return, to get to the node about Info and - see what other help is available. -@end format - - -@node Advanced -@chapter Advanced Info Commands - - This chapter describes various advanced Info commands. (If you -are using a stand-alone Info reader, there are additional commands -specific to it, which are documented in several chapters of @ref{Top,, -GNU Info, info-stnd, GNU Info}.) - -@kindex C-q @r{(Info mode)} - One advanced command useful with most of the others described here -is @kbd{C-q}, which ``quotes'' the next character so that it is -entered literally (@pxref{Inserting Text,,,emacs,The GNU Emacs -Manual}). For example, pressing @kbd{?} ordinarily brings up a list -of completion possibilities. If you want to (for example) search for -an actual @samp{?} character, the simplest way is to insert it using -@kbd{C-q ?}. This works the same in Emacs and stand-alone Info. - -@menu -* Search Text:: How to search Info documents. -* Search Index:: How to search the indices for specific subjects. -* Go to node:: How to go to a node by name. -* Choose menu subtopic:: How to choose a menu subtopic by its number. -* Create Info buffer:: How to create a new Info buffer in Emacs. -* Emacs Info Variables:: Variables modifying the behavior of Emacs Info. -@end menu - - -@node Search Text, Search Index, , Advanced -@comment node-name, next, previous, up -@section @kbd{s} searches Info documents - -@cindex searching Info documents -@cindex Info document as a reference - The commands which move between and inside nodes allow you to read -the entire manual or its large portions. But what if you need to find -some information in the manual as fast as you can, and you don't know -or don't remember in what node to look for it? This need arises when -you use a manual as a @dfn{reference}, or when it is impractical to -read the entire manual before you start using the programs it -describes. - - Info has powerful searching facilities that let you find things -quickly. You can search either the manual text or its indices. - -@kindex s @r{(Info mode)} -@findex Info-search - The @kbd{s} command allows you to search a whole Info file for a string. -It switches to the next node if and when that is necessary. You -type @kbd{s} followed by the string to search for, terminated by -@key{RET}. To search for the same string again, just @kbd{s} followed -by @key{RET} will do. The file's nodes are scanned in the order -they are in the file, which has no necessary relationship to the -order that they may be in the tree structure of menus and @samp{next} -pointers. But normally the two orders are not very different. In any -case, you can always look at the mode line to find out what node you have -reached, if the header is not visible (this can happen, because @kbd{s} -puts your cursor at the occurrence of the string, not at the beginning -of the node). - -@kindex C-s @r{(Info mode)} -@kindex C-r @r{(Info mode)} -@findex isearch - Instead of using @kbd{s} in Emacs Info and in the stand-alone Info, -you can use an incremental search started with @kbd{C-s} or @kbd{C-r}. -It can search through multiple Info nodes. @xref{Incremental Search,,, -emacs, The GNU Emacs Manual}. In Emacs, you can disable this behavior -by setting the variable @code{Info-isearch-search} to @code{nil} -(@pxref{Emacs Info Variables}). - -@node Search Index, Go to node, Search Text, Advanced -@comment node-name, next, previous, up -@section @kbd{i} searches the indices for specific subjects - -@cindex searching Info indices -@kindex i @r{(Info mode)} -@findex Info-index - Since most topics in the manual should be indexed, you should try -the index search first before the text search. The @kbd{i} command -prompts you for a subject and then looks up that subject in the -indices. If it finds an index entry with the subject you typed, it -goes to the node to which that index entry points. You should browse -through that node to see whether the issue you are looking for is -described there. If it isn't, type @kbd{,} one or more times to go -through additional index entries which match your subject. - - The @kbd{i} command and subsequent @kbd{,} commands find all index -entries which include the string you typed @emph{as a substring}. -For each match, Info shows in the echo area the full index entry it -found. Often, the text of the full index entry already gives you -enough information to decide whether it is relevant to what you are -looking for, so we recommend that you read what Info shows in the echo -area before looking at the node it displays. - - Since @kbd{i} looks for a substring, you can search for subjects even -if you are not sure how they are spelled in the index. For example, -suppose you want to find something that is pertinent to commands which -complete partial input (e.g., when you type @key{TAB}). If you want -to catch index entries that refer to ``complete,'' ``completion,'' and -``completing,'' you could type @kbd{icomplet@key{RET}}. - - Info documents which describe programs should index the commands, -options, and key sequences that the program provides. If you are -looking for a description of a command, an option, or a key, just type -their names when @kbd{i} prompts you for a topic. For example, if you -want to read the description of what the @kbd{C-l} key does, type -@kbd{iC-l@key{RET}} literally. - -@findex Info-virtual-index -@kindex I @r{(Info mode)} -Emacs provides the command @code{Info-virtual-index}, bound to the -@kbd{I} key. This behaves like @kbd{i}, but constructs a virtual -info node displaying the results of an index search, making it easier -to select the one you want. - -@findex info-apropos -@findex index-apropos -If you aren't sure which manual documents the topic you are looking -for, try the @kbd{M-x info-apropos} command in Emacs, or the @kbd{M-x -index-apropos} command in the stand-alone reader. It prompts for -a string and then looks up that string in all the indices of all the -Info documents installed on your system. - -@node Go to node, Choose menu subtopic, Search Index, Advanced -@comment node-name, next, previous, up -@section @kbd{g} goes to a node by name - -@kindex g @r{(Info mode)} -@findex Info-goto-node -@cindex go to a node by name - If you know a node's name, you can go there by typing @kbd{g}, the -name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node -called @samp{Top} in this file. (This is equivalent to @kbd{t}, see -@ref{Help-Int}.) @kbd{gGo to node@key{RET}} would come back here. - - Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations. -But it does allow completion, so you can type @key{TAB} to complete a -partial node name. - -@cindex go to another Info file - To go to a node in another file, you can include the file name in the -node name by putting it at the front, in parentheses. Thus, -@kbd{g(dir)Top@key{RET}} would go to the Info Directory node, which is -the node @samp{Top} in the Info file @file{dir}. Likewise, -@kbd{g(emacs)Top@key{RET}} goes to the top node of the Emacs manual. - - The node name @samp{*} specifies the whole file. So you can look at -all of the current file by typing @kbd{g*@key{RET}} or all of any -other file with @kbd{g(@var{filename})*@key{RET}}. - -@node Choose menu subtopic, Create Info buffer, Go to node, Advanced -@comment node-name, next, previous, up -@section @kbd{1}--@kbd{9} choose a menu subtopic by its number - -@kindex 1 @r{through} 9 @r{(Info mode)} -@findex Info-nth-menu-item -@cindex select @var{n}'th menu item - If you begrudge each character of type-in which your system requires, -you might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, -@dots{}, @kbd{9}. They are short for the @kbd{m} command together -with a name of a menu subtopic. @kbd{1} goes through the first item -in the current node's menu; @kbd{2} goes through the second item, etc. -In the stand-alone reader, @kbd{0} goes through the last menu item; -this is so you need not count how many entries are there. - - If your display supports multiple fonts, colors or underlining, and -you are using Emacs's Info mode to read Info files, the third, sixth -and ninth menu items have a @samp{*} that stands out, either in color -or in some other attribute, such as underline; this makes it easy to -see at a glance which number to use for an item. - - Some terminals don't support either multiple fonts, colors or -underlining. If you need to actually count items, it is better to use -@kbd{m} instead, and specify the name, or use @key{TAB} to quickly -move between menu items. - -@node Create Info buffer, Emacs Info Variables, Choose menu subtopic, Advanced -@comment node-name, next, previous, up -@section @kbd{M-n} creates a new independent Info buffer in Emacs - -@kindex M-n @r{(Info mode)} -@findex clone-buffer -@cindex multiple Info buffers - If you are reading Info in Emacs, you can select a new independent -Info buffer in a new Emacs window by typing @kbd{M-n}. The new buffer -starts out as an exact copy of the old one, but you will be able to -move independently between nodes in the two buffers. (In Info mode, -@kbd{M-n} runs the Emacs command @code{clone-buffer}.) - - In Emacs Info, you can also produce new Info buffers by giving a -numeric prefix argument to the @kbd{m} and @kbd{g} commands. @kbd{C-u -m} and @kbd{C-u g} go to a new node in exactly the same way that -@kbd{m} and @kbd{g} do, but they do so in a new Info buffer which they -select in another window. - - Another way to produce new Info buffers in Emacs is to use a numeric -prefix argument for the @kbd{C-h i} command (@code{info}) which -switches to the Info buffer with that number. Thus, @kbd{C-u 2 C-h i} -switches to the buffer @samp{*info*<2>}, creating it if necessary. - -@findex info-display-manual - If you have created many Info buffers in Emacs, you might find it -difficult to remember which buffer is showing which manual. You can -use the command @kbd{M-x info-display-manual} to show an Info manual -by name, reusing an existing buffer if there is one. - -@node Emacs Info Variables, , Create Info buffer, Advanced -@comment node-name, next, previous, up -@section Emacs Info-mode Variables - -The following variables may modify the behavior of Info-mode in Emacs; -you may wish to set one or several of these variables interactively, -or in your init file. @xref{Examining, Examining and Setting -Variables, Examining and Setting Variables, emacs, The GNU Emacs -Manual}. The stand-alone Info reader program has its own set of -variables, described in @ref{Variables,, Manipulating Variables, -info-stnd, GNU Info}. - -@vtable @code -@item Info-directory-list -The list of directories to search for Info files. Each element is a -string (directory name) or @code{nil} (try default directory). If not -initialized Info uses the environment variable @env{INFOPATH} to -initialize it, or @code{Info-default-directory-list} if there is no -@env{INFOPATH} variable in the environment. - -If you wish to customize the Info directory search list for both Emacs -Info and stand-alone Info, it is best to set the @env{INFOPATH} -environment variable, since that applies to both programs. - -@item Info-additional-directory-list -A list of additional directories to search for Info documentation files. -These directories are not searched for merging the @file{dir} file. - -@item Info-mode-hook -Hooks run when @code{Info-mode} is called. By default, it contains -the hook @code{turn-on-font-lock} which enables highlighting of Info -files. You can change how the highlighting looks by customizing the -faces @code{info-node}, @code{info-xref}, @code{info-xref-visited}, -@code{info-header-xref}, @code{info-header-node}, @code{info-menu-header}, -@code{info-menu-star}, and @code{info-title-@var{n}} (where @var{n} -is the level of the section, a number between 1 and 4). To customize -a face, type @kbd{M-x customize-face @key{RET} @var{face} @key{RET}}, -where @var{face} is one of the face names listed here. - -@item Info-fontify-maximum-menu-size -Maximum size of menu to fontify if @code{font-lock-mode} is non-@code{nil}. - -@item Info-fontify-visited-nodes -If non-@code{nil}, menu items and cross-references pointing to visited -nodes are displayed in the @code{info-xref-visited} face. - -@item Info-use-header-line -If non-@code{nil}, Emacs puts in the Info buffer a header line showing -the @samp{Next}, @samp{Prev}, and @samp{Up} links. A header line does -not scroll with the rest of the buffer, making these links always -visible. - -@item Info-hide-note-references -As explained in earlier nodes, the Emacs version of Info normally -hides some text in menus and cross-references. You can completely -disable this feature, by setting this option to @code{nil}. Setting -it to a value that is neither @code{nil} nor @code{t} produces an -intermediate behavior, hiding a limited amount of text, but showing -all text that could potentially be useful. - -@item Info-scroll-prefer-subnodes -If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or -@key{DEL}) keys in a menu visit subnodes of the current node before -scrolling to its end or beginning, respectively. For example, if the -node's menu appears on the screen, the next @key{SPC} moves to a -subnode indicated by the following menu item. Setting this option to -@code{nil} results in behavior similar to the stand-alone Info reader -program, which visits the first subnode from the menu only when you -hit the end of the current node. The default is @code{nil}. - -@item Info-isearch-search -If non-@code{nil}, isearch in Info searches through multiple nodes. - -@item Info-enable-active-nodes -When set to a non-@code{nil} value, allows Info to execute Lisp code -associated with nodes. The Lisp code is executed when the node is -selected. The Lisp code to be executed should follow the node -delimiter (the @samp{DEL} character) and an @samp{execute: } tag, like -this: - -@example -^_execute: (message "This is an active node!") -@end example -@end vtable - - -@node Expert Info -@chapter Info for Experts -@cindex Texinfo - - This chapter explains how to write an Info file by hand. However, -in most cases, writing a Texinfo file is better, since you can use it -to make a printed manual or produce other formats, such as HTML and -DocBook, as well as for generating Info files. - -The @code{makeinfo} command converts a Texinfo file into an Info file; -@code{texinfo-format-region} and @code{texinfo-format-buffer} are GNU -Emacs functions that do the same. - -@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU -Documentation Format}, for how to write a Texinfo file. - -@xref{Creating an Info File,,, texinfo, Texinfo: The GNU Documentation -Format}, for how to create an Info file from a Texinfo file. - -@xref{Installing an Info File,,, texinfo, Texinfo: The GNU -Documentation Format}, for how to install an Info file after you -have created one. - -However, if you want to edit an Info file manually and install it manually, -here is how. - -@menu -* Add:: Describes how to add new nodes to the hierarchy. - Also tells what nodes look like. -* Menus:: How to add to or create menus in Info nodes. -* Cross-refs:: How to add cross-references to Info nodes. -* Tags:: How to make tags tables for Info files. -* Checking:: Checking an Info File. -@end menu - -@node Add, Menus, , Expert Info -@comment node-name, next, previous, up -@section Adding a new node to Info - -To add a new topic to the list in the Info directory, you must: - -@enumerate -@item -Create some nodes, in some file, to document that topic. -@item -Put that topic in the menu in the directory. @xref{Menus, Menu}. -@end enumerate - -@cindex node delimiters - The new node can live in an existing documentation file, or in a new -one. It must have a @samp{^_} character before it (invisible to the -user; this node has one but you cannot see it), and it ends with either -a @samp{^_}, a @samp{^L} (``formfeed''), or the end of file.@footnote{If -you put in a @samp{^L} to end a new node, be sure that there is a -@samp{^_} after it to start the next one, since @samp{^L} cannot -@emph{start} a node. Also, a nicer way to make a node boundary be a -page boundary as well is to put a @samp{^L} @emph{right after} the -@samp{^_}.} - - The @samp{^_} starting a node must be followed by a newline or a -@samp{^L} newline, after which comes the node's header line. The -header line must give the node's name (by which Info finds it), and -state the names of the @samp{Next}, @samp{Previous}, and @samp{Up} -nodes (if there are any). As you can see, this node's @samp{Up} node -is the node @samp{Expert Info}. The @samp{Next} node is @samp{Menus}. - -@cindex node header line format -@cindex format of node headers - The keywords @dfn{Node}, @dfn{Next}, @dfn{Previous}, and @dfn{Up} -may appear in any order, anywhere in the header line, but the -recommended order is the one in this sentence. Each keyword must be -followed by a colon, spaces and tabs, and then the appropriate name. -The name may be terminated with a tab, a comma, or a newline. A space -does not end it; node names may contain spaces. The case of letters -in the names is insignificant. - -@cindex node name format -@cindex Directory node - A node name has two forms. A node in the current file is named by -what appears after the @samp{Node: } in that node's first line. For -example, this node's name is @samp{Add}. A node in another file is -named by @samp{(@var{filename})@var{node-within-file}}, as in -@samp{(info)Add} for this node. If the file name starts with @samp{./}, -then it is relative to the current directory; otherwise, it is -relative starting from the standard directory for Info files of your -site. The name @samp{(@var{filename})Top} can be abbreviated to just -@samp{(@var{filename})}. By convention, the name @samp{Top} is used -for the ``highest'' node in any single file---the node whose @samp{Up} -points out of the file. The @samp{Directory} node is @file{(dir)}, it -points to a file @file{dir} which holds a large menu listing all the -Info documents installed on your site. The @samp{Top} node of a -document file listed in the @samp{Directory} should have an @samp{Up: -(dir)} in it. - -@cindex unstructured documents - The node name @kbd{*} is special: it refers to the entire file. -Thus, @kbd{g*} shows you the whole current file. The use of the -node @kbd{*} is to make it possible to make old-fashioned, -unstructured files into nodes of the tree. - - The @samp{Node:} name, in which a node states its own name, must not -contain a file name, since when Info searches for a node, it does not -expect a file name to be there. The @samp{Next}, @samp{Previous} and -@samp{Up} names may contain them. In this node, since the @samp{Up} -node is in the same file, it was not necessary to use one. - - Note that the nodes in this file have a file name in the header -line. The file names are ignored by Info, but they serve as comments -to help identify the node for the user. - -@node Menus, Cross-refs, Add, Expert Info -@comment node-name, next, previous, up -@section How to Create Menus - - Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes. -The @kbd{m} command searches the current node's menu for the topic which it -reads from the terminal. - -@cindex menu and menu entry format - A menu begins with a line starting with @w{@samp{* Menu:}}. The -rest of the line is a comment. After the starting line, every line -that begins with a @samp{* } lists a single topic. The name of the -topic---what the user must type at the @kbd{m}'s command prompt to -select this topic---comes right after the star and space, and is -followed by a colon, spaces and tabs, and the name of the node which -discusses that topic. The node name, like node names following -@samp{Next}, @samp{Previous} and @samp{Up}, may be terminated with a -tab, comma, or newline; it may also be terminated with a period. - - If the node name and topic name are the same, then rather than -giving the name twice, the abbreviation @samp{* @var{name}::} may be -used (and should be used, whenever possible, as it reduces the visual -clutter in the menu). - - It is considerate to choose the topic names so that they differ -from each other very near the beginning---this allows the user to type -short abbreviations. In a long menu, it is a good idea to capitalize -the beginning of each item name which is the minimum acceptable -abbreviation for it (a long menu is more than 5 or so entries). - - The nodes listed in a node's menu are called its ``subnodes,'' and it -is their ``superior''. They should each have an @samp{Up:} pointing at -the superior. It is often useful to arrange all or most of the subnodes -in a sequence of @samp{Next} and @samp{Previous} pointers so that -someone who wants to see them all need not keep revisiting the Menu. - - The Info Directory is simply the menu of the node @samp{(dir)Top}---that -is, node @samp{Top} in file @file{.../info/dir}. You can put new entries -in that menu just like any other menu. The Info Directory is @emph{not} the -same as the file directory called @file{info}. It happens that many of -Info's files live in that file directory, but they do not have to; and -files in that directory are not automatically listed in the Info -Directory node. - - Also, although the Info node graph is claimed to be a ``hierarchy,'' -in fact it can be @emph{any} directed graph. Shared structures and -pointer cycles are perfectly possible, and can be used if they are -appropriate to the meaning to be expressed. There is no need for all -the nodes in a file to form a connected structure. In fact, this file -has two connected components. You are in one of them, which is under -the node @samp{Top}; the other contains the node @samp{Help} which the -@kbd{h} command goes to. In fact, since there is no garbage -collector on the node graph, nothing terrible happens if a substructure -is not pointed to, but such a substructure is rather useless since nobody -can ever find out that it exists. - -@node Cross-refs, Tags, Menus, Expert Info -@comment node-name, next, previous, up -@section Creating Cross References - -@cindex cross reference format - A cross reference can be placed anywhere in the text, unlike a menu -item which must go at the front of a line. A cross reference looks -like a menu item except that it has @samp{*note} instead of @samp{*}. -It @emph{cannot} be terminated by a @samp{)}, because @samp{)}'s are -so often part of node names. If you wish to enclose a cross reference -in parentheses, terminate it with a period first. Here are two -examples of cross references pointers: - -@example -*Note details: commands. (See *note 3: Full Proof.) -@end example - -@noindent -@emph{These are just examples.} The places they ``lead to'' do not -really exist! - -@menu -* Help-Cross:: Target of a cross-reference. -@end menu - - -@node Help-Cross, , , Cross-refs -@subsection The node reached by the cross reference in Info - - This is the node reached by the cross reference named @samp{Cross}. - - While this node is specifically intended to be reached by a cross -reference, most cross references lead to nodes that ``belong'' -someplace else far away in the structure of an Info document. So you -cannot expect this node to have a @samp{Next}, @samp{Previous} or -@samp{Up} links pointing back to where you came from. In general, the -@kbd{l} (el) command is the only way to get back there. - -@format ->> Type @kbd{l} to return to the node where the cross reference was. -@end format - -@node Tags, Checking, Cross-refs, Expert Info -@comment node-name, next, previous, up -@section Tags Tables for Info Files - -@cindex tags tables in Info files - You can speed up the access to nodes of a large Info file by giving -it a tags table. Unlike the tags table for a program, the tags table for -an Info file lives inside the file itself and is used -automatically whenever Info reads in the file. - -@findex Info-tagify - To make a tags table, go to a node in the file using Emacs Info mode and type -@kbd{M-x Info-tagify}. Then you must use @kbd{C-x C-s} to save the -file. Info files produced by the @code{makeinfo} command that is part -of the Texinfo package always have tags tables to begin with. - -@cindex stale tags tables -@cindex update Info tags table - Once the Info file has a tags table, you must make certain it is up -to date. If you edit an Info file directly (as opposed to editing its -Texinfo source), and, as a result of deletion of text, any node moves back -more than a thousand characters in the file from the position -recorded in the tags table, Info will no longer be able to find that -node. To update the tags table, use the @code{Info-tagify} command -again. - - An Info file tags table appears at the end of the file and looks like -this: - -@example -^_^L -Tag Table: -File: info, Node: Cross-refs^?21419 -File: info, Node: Tags^?22145 -^_ -End Tag Table -@end example - -@noindent -Note that it contains one line per node, and this line contains -the beginning of the node's header (ending just after the node name), -a @samp{DEL} character, and the character position in the file of the -beginning of the node. - -@node Checking, , Tags, Expert Info -@section Checking an Info File - -When creating an Info file, it is easy to forget the name of a node when -you are making a pointer to it from another node. If you put in the -wrong name for a node, this is not detected until someone tries to go -through the pointer using Info. Verification of the Info file is an -automatic process which checks all pointers to nodes and reports any -pointers which are invalid. Every @samp{Next}, @samp{Previous}, and -@samp{Up} is checked, as is every menu item and every cross reference. In -addition, any @samp{Next} which does not have a @samp{Previous} pointing -back is reported. Only pointers within the file are checked, because -checking pointers to other files would be terribly slow. But those are -usually few. - -@findex Info-validate -To check an Info file, do @kbd{M-x Info-validate} while looking at any -node of the file with Emacs Info mode. - -@node Index -@unnumbered Index - -This is an alphabetical listing of all the commands, variables, and -topics discussed in this document. - -@printindex cp - -@bye diff --git a/doc/misc/mairix-el.texi b/doc/misc/mairix-el.texi deleted file mode 100644 index 468283ffd93..00000000000 --- a/doc/misc/mairix-el.texi +++ /dev/null @@ -1,351 +0,0 @@ -\input texinfo.tex - -@setfilename ../../info/mairix-el -@settitle Emacs Interface for Mairix - -@documentencoding ISO-8859-1 - -@copying -Copyright @copyright{} 2008-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* Mairix: (mairix-el). Emacs interface to the Mairix mail indexer. -@end direntry - -@titlepage -@title mairix.el - Mairix interface for Emacs - -@author David Engster -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top mairix.el - Mairix interface for Emacs - -Mairix is a tool for indexing and searching words in locally stored -mail. It was written by Richard Curnow and is licensed under the -GPL. - -@code{mairix.el} is an interface to the mairix search engine. It allows you to -call mairix with a search term, easily create searches based on the -currently displayed mail, save regularly used searches in your -@file{.emacs} for future use and lets you call mairix for updating the -database. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* About mairix and mairix.el:: About the mairix search engine and mairix.el -* Configuring mairix:: How to configure mairix -* Setting up mairix.el:: Set up mairix.el -* Using mairix.el:: List of interactive functions -* Extending mairix.el:: Support your favorite mail reader! -@end menu - -@node About mairix and mairix.el -@chapter About mairix and mairix.el - -Mairix is a tool for indexing and searching words in locally stored -mail. It was written by Richard Curnow and is licensed under the -GPL. Mairix comes with most popular GNU/Linux distributions, but it also -runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can -be found at -@uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} - -Though mairix might not be as flexible as other search tools like -swish++ or namazu, it has the prime advantage of being incredibly fast. -On current systems, it can easily search through headers and message -bodies of thousands and thousands of mails in well under a second. -Building the database necessary for searching might take a minute or -two, but only has to be done once fully. Afterwards, the updates are -done incrementally and therefore are really fast, too. Additionally, -mairix is very easy to set up. - -Mairix presents the search results by either populating a @emph{virtual} -maildir/MH folder with symlinks which point to the ``real'' message -files, or if mbox is used, it creates a new mbox file which contains -copies of the found messages. - -@code{mairix.el} is an interface to the mairix search engine. It allows -you to call mairix with a search term, easily create searches based on -the currently displayed mail, save regularly used searches in your -@file{.emacs} for future use and lets you call mairix for updating the -database. It also lets you easily create search queries using graphical -widgets, similar to a customization buffer. - -Currently, @code{mairix.el} is only tested with mbox output together -with RMail, Gnus, or VM as the Emacs mail program. However, it should -also work with Maildir or MH, and it should be very easy to integrate -other Emacs mail programs into @code{mairix.el} -(@pxref{Extending mairix.el}). - -If you use Gnus with maildir or MH, you should really use the native -Gnus back end @code{nnmairix} instead, since it is more tightly -integrated into Gnus and has more features. - -@node Configuring mairix -@chapter Configuring mairix - -Setting up mairix is easy: simply create a @file{.mairixrc} file with -(at least) the following entries: - -@example -# Your mail base folder -base=~/Mail -@end example - -This is the base folder for your mails. All the following directories, -except the one for the database, are relative to this base folder. - -@example -mbox = ... your mbox files which should be indexed ... -maildir= ... your maildir folders which should be indexed ... -mh= ... your nnml/mh folders which should be indexed ... -@end example - -Specify all your maildir/nnml folders and mbox files (relative to the -base directory!) you want to index with mairix. Use colons to separate -different files. See the man-page for @code{mairixrc} for details. - -@example -mformat = mbox -database = ... location of database file ... -@end example - -This chooses @code{mbox} as the output format for the mairix search -results. Currently, this is the supported format by mairix.el, but -technically it should be possible to also use maildir or mh; it's just -not tested (yet). - -You should make sure that you don't accidentally index the search -results produced by mairix. This can be done by pointing -`mairix-file-path' to a directory which is surely not indexed by mairix. -Another possibility is to use something like - -@example -omit = mairix* -@end example - -in the @file{.mairixrc} file, and prefix every search file you use with -``mairix''. - -@example -database = /home/user/.mairixdatabase -@end example - -This specifies the name of the database file. Note that this is not -relative to the @code{base} folder. - -See the man page for @code{mairixrc} for details and further options, -especially regarding wildcard usage, which may be a little different -than you are used to. - -Now simply call @code{mairix} to create the index for the first time. -Note that this may take a few minutes, but every following index will do -the updates incrementally and hence is very fast. - -@node Setting up mairix.el -@chapter Setting up mairix.el - -First, put @code{mairix.el} in your Emacs search path and put -@code{(require 'mairix)} into your @file{.emacs} file. Then, use -@kbd{M-x customize-group mairix RET} to set your preferences for -mairix.el. The most important items are @emph{Mairix File Path}, -@emph{Mairix Search File} and @emph{Mairix Mail Program}. The latter -specifies which mail program should be used to display the mairix search -results. Currently, RMail, Gnus with mbox files, and VM are supported. -If you use Gnus with maildir or mh, use the native Gnus back end -nnmairix instead. - -If you use another Emacs mail program which is not yet supported by -mairix.el, it is pretty easy to integrate it. @xref{Extending -mairix.el}, on how to integrate it into mairix.el. - -Now you should be ready to go. @xref{Using mairix.el}, for the available -commands. - -@node Using mairix.el -@chapter Using mairix.el - -There are currently no default key bindings for mairix.el, since those -should depend on the used mail program and I personally do not use -RMail, so I wouldn't know which key bindings are reasonable. I hope some -day this will change and @code{mairix.el} will come with some good -key bindings for the different mail programs. Feel free to send me your -suggestions. Until then, define some bindings yourself. Here's a quick -and dirty solution with global key definitions I currently use, which -might or might not collide with some other modes. Simply include them -in your @file{.emacs} and adapt to your needs: - -@lisp -(global-set-key (kbd "C-c C-o m") 'mairix-search) -(global-set-key (kbd "C-c C-o w") 'mairix-widget-search) -(global-set-key (kbd "C-c C-o u") 'mairix-update-database) -(global-set-key (kbd "C-c C-o f") 'mairix-search-from-this-article) -(global-set-key (kbd "C-c C-o t") 'mairix-search-thread-this-article) -(global-set-key (kbd "C-c C-o b") 'mairix-widget-search-based-on-article) -(global-set-key (kbd "C-c C-o s") 'mairix-save-search) -(global-set-key (kbd "C-c C-o i") 'mairix-use-saved-search) -(global-set-key (kbd "C-c C-o e") 'mairix-edit-saved-searches) -@end lisp - -Here's a description of the available interactive functions: - -@table @code - -@item mairix-search -@kindex M-x mairix-search -@findex mairix-search -@vindex mairix-search-file -@vindex mairix-file-path -@vindex mairix-command -@vindex mairix-search-options -Call mairix with a search query. You will also be asked if you want to -include whole threads. The results are saved by mairix in the default -mail file, which is set through the variable `mairix-search-file', which -again is prefixed by `mairix-file-path'. The results will then be -displayed with the chosen mail program. The command used to call mairix -is specified by the variable `mairix-command', together with the options -`mairix-search-options'. The latter has the default ``-F'' for making -searching faster. - -@item mairix-widget-search -@kindex M-x mairix-widget-search -@findex mairix-widget-search -@vindex mairix-widget-fields-list -Creates a mairix query using graphical widgets. Very handy if you're -not (yet) familiar with the mairix search syntax. Just call it to see -how it works. You can then directly call mairix with the search term or -save it for future use. Since mairix allows almost arbitrary -combinations of search commands (like ``tc'' for ``to or cc''), you -might want to include some other fields. This can be easily done by -modifying `mairix-widget-fields-list'. - -@item mairix-widget-search-based-on-article -@kindex M-x mairix-widget-search-based-on-article -@findex mairix-widget-search-based-on-article -Create a mairix query using graphical widgets, but based on the -currently displayed article, i.e. the available fields will be filled -with the current header values. - -@item mairix-search-from-this-article -@kindex M-x mairix-search-from-this-article -@findex mairix-search-from-this-article -Search messages from sender of the current article. This is effectively -a shortcut for calling @code{mairix-search} with @code{f:current_from}. -If used with a prefix, include whole threads of the found messages. - -@item mairix-search-thread-this-article -@kindex M-x mairix-search-thread-this-article -@findex mairix-search-thread-this-article -Search thread for the current article. This is effectively a shortcut -for calling @code{mairix-search} with @code{m:msgid} of the current article and -enabled threads. - -@item mairix-save-search -@kindex M-x mairix-save-search -@findex mairix-save-search -Save the last search for future use. You will have to specify a name -for the search and will then be asked if you want to save your saved -searches in your @file{.emacs}. If you answer with yes, the variable -@code{mairix-saved-searches} will be saved in the customize section of -your @file{.emacs}. You can also do this later by using -`mairix-edit-saved-searches'. - -@item mairix-use-saved-search -@kindex M-x mairix-use-saved-search -@findex mairix-use-saved-search -Call mairix with a previously saved search. You will be asked for the -name of the saved search (use @kbd{TAB} for completion). - -@item mairix-edit-saved-searches -@kindex M-x mairix-edit-saved-searches -@findex mairix-edit-saved-searches -Edit your current mairix searches. This is a simple major mode for -editing the contents of the variable @code{mairix-saved-searches}. You -can edit and delete searches and save them in your @file{.emacs}. You -can also use this mode to call mairix with one of the saved searches. -Additionally, you can specify a file name for mairix to use for a -certain search instead of the default one. This is useful if you want -to open different searches at the same time, or if you want to regularly -access certain searches without the need to call mairix. - -@item mairix-edit-saved-searches-customize -@kindex M-x mairix-edit-saved-searches-customize -@findex mairix-edit-saved-searches-customize -Edit the variable @code{mairix-saved-searches} in a normal customization -buffer. This function exists more or less for historic reasons, but -maybe you like it. - -@item mairix-update-database -@kindex M-x mairix-update-database -@findex mairix-update-database -@vindex mairix-update-options -@vindex mairix-synchronous-update -Call mairix to update the database. Mairix will be called with the -options `mairix-update-options'; the default is ``-F'' and ``-Q'' to -make updates as fast as possible. Note that by using these options, -absolutely no integrity checking is done. If your database somehow gets -corrupted, simply delete it and update. If `mairix-synchronous-update' -is nil (the default), mairix will be called in a subprocess so Emacs -will still be usable while the update is done. - -@end table - - -@node Extending mairix.el -@chapter Extending mairix.el - -Your favorite Emacs mail program is not supported? Shame on me. But -it is really easy to integrate other mail programs into mairix.el. Just -do the following: - -@table @strong -@item Write a display function -Write a function that displays the mairix search results. This function -will be called from @code{mairix.el} with the mail file/folder as the -single argument. For example, the function @code{mairix-rmail-display} -is currently used for RMail and @code{mairix-gnus-ephemeral-nndoc} is -used for Gnus. - -@item Write a get-header function -Write a function that retrieves a header from the currently active mail. -The single argument for this function is a string with the header name. -For examples, see @code{mairix-rmail-fetch-field} and -@code{mairix-gnus-fetch-field} for RMail and Gnus, respectively. - -@item Integrate the functions into mairix.el -Add your mail program to the defcustom of @code{mairix-mail-program}. -Then add the functions to @code{mairix-display-functions} and -@code{mairix-get-mail-header-functions}. - -@item Let me know... -...so that I can eventually integrate it into future versions of mairix.el. -@end table - -And that's it! - - - -@bye diff --git a/doc/misc/message.texi b/doc/misc/message.texi deleted file mode 100644 index ac5811a0ce8..00000000000 --- a/doc/misc/message.texi +++ /dev/null @@ -1,2502 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@include gnus-overrides.texi - -@setfilename ../../info/message -@settitle Message Manual -@synindex fn cp -@synindex vr cp -@synindex pg cp -@copying -This file documents Message, the Emacs message composition mode. - -Copyright @copyright{} 1996-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* Message: (message). Mail and news composition mode that - goes with Gnus. -@end direntry -@iftex -@finalout -@end iftex - -@titlepage -@ifset WEBHACKDEVEL -@title Message Manual (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title Message Manual -@end ifclear - -@author by Lars Magne Ingebrigtsen -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@node Top -@top Message - -@ifnottex -@insertcopying -@end ifnottex - -All message composition from Gnus (both mail and news) takes place in -Message mode buffers. - -@menu -* Interface:: Setting up message buffers. -* Commands:: Commands you can execute in message mode buffers. -* Variables:: Customizing the message buffers. -* Compatibility:: Making Message backwards compatible. -* Appendices:: More technical things. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Variable, function and concept index. -* Key Index:: List of Message mode keys. -@end menu - -@c Adjust ../Makefile.in if you change the following lines: -Message is distributed with Gnus. The Gnus distribution -@c -corresponding to this manual is Gnus v5.13 - - -@node Interface -@chapter Interface - -When a program (or a person) wants to respond to a message---reply, -follow up, forward, cancel---the program (or person) should just put -point in the buffer where the message is and call the required command. -@code{Message} will then pop up a new @code{message} mode buffer with -appropriate headers filled out, and the user can edit the message before -sending it. - -@menu -* New Mail Message:: Editing a brand new mail message. -* New News Message:: Editing a brand new news message. -* Reply:: Replying via mail. -* Wide Reply:: Responding to all people via mail. -* Followup:: Following up via news. -* Canceling News:: Canceling a news article. -* Superseding:: Superseding a message. -* Forwarding:: Forwarding a message via news or mail. -* Resending:: Resending a mail message. -* Bouncing:: Bouncing a mail message. -* Mailing Lists:: Send mail to mailing lists. -@end menu - -You can customize the Message Mode tool bar, see @kbd{M-x -customize-apropos RET message-tool-bar}. This feature is only available -in Emacs. - -@node New Mail Message -@section New Mail Message - -@findex message-mail -The @code{message-mail} command pops up a new message buffer. - -Two optional parameters are accepted: The first will be used as the -@code{To} header and the second as the @code{Subject} header. If these -are @code{nil}, those two headers will be empty. - - -@node New News Message -@section New News Message - -@findex message-news -The @code{message-news} command pops up a new message buffer. - -This function accepts two optional parameters. The first will be used -as the @code{Newsgroups} header and the second as the @code{Subject} -header. If these are @code{nil}, those two headers will be empty. - - -@node Reply -@section Reply - -@findex message-reply -The @code{message-reply} function pops up a message buffer that's a -reply to the message in the current buffer. - -@vindex message-reply-to-function -Message uses the normal methods to determine where replies are to go -(@pxref{Responses}), but you can change the behavior to suit your needs -by fiddling with the @code{message-reply-to-function} variable. - -If you want the replies to go to the @code{Sender} instead of the -@code{From}, you could do something like this: - -@lisp -(setq message-reply-to-function - (lambda () - (cond ((equal (mail-fetch-field "from") "somebody") - (list (cons 'To (mail-fetch-field "sender")))) - (t - nil)))) -@end lisp - -This function will be called narrowed to the head of the article that is -being replied to. - -As you can see, this function should return a list. In this case, it -returns @code{((To . "Whom"))} if it has an opinion as to what the To -header should be. If it does not, it should just return @code{nil}, and -the normal methods for determining the To header will be used. - -Each list element should be a cons, where the @sc{car} should be the -name of a header (e.g. @code{Cc}) and the @sc{cdr} should be the header -value (e.g. @samp{larsi@@ifi.uio.no}). All these headers will be -inserted into the head of the outgoing mail. - - -@node Wide Reply -@section Wide Reply - -@findex message-wide-reply -The @code{message-wide-reply} pops up a message buffer that's a wide -reply to the message in the current buffer. A @dfn{wide reply} is a -reply that goes out to all people listed in the @code{To}, @code{From} -(or @code{Reply-to}) and @code{Cc} headers. - -@vindex message-wide-reply-to-function -Message uses the normal methods to determine where wide replies are to go, -but you can change the behavior to suit your needs by fiddling with the -@code{message-wide-reply-to-function}. It is used in the same way as -@code{message-reply-to-function} (@pxref{Reply}). - -@vindex message-dont-reply-to-names -Addresses that match the @code{message-dont-reply-to-names} regular -expression (or list of regular expressions) will be removed from the -@code{Cc} header. A value of @code{nil} means exclude your name only. - -@vindex message-prune-recipient-rules -@code{message-prune-recipient-rules} is used to prune the addresses -used when doing a wide reply. It's meant to be used to remove -duplicate addresses and the like. It's a list of lists, where the -first element is a regexp to match the address to trigger the rule, -and the second is a regexp that will be expanded based on the first, -to match addresses to be pruned. - -It's complicated to explain, but it's easy to use. - -For instance, if you get an email from @samp{foo@@example.org}, but -@samp{foo@@zot.example.org} is also in the @code{Cc} list, then your -wide reply will go out to both these addresses, since they are unique. - -To avoid this, do something like the following: - -@lisp -(setq message-prune-recipient-rules - '(("^\\([^@@]+\\)@@\\(.*\\)" "\\1@@.*[.]\\2"))) -@end lisp - -If, for instance, you want all wide replies that involve messages from -@samp{cvs@@example.org} to go to that address, and nowhere else (i.e., -remove all other recipients if @samp{cvs@@example.org} is in the -recipient list: - -@lisp -(setq message-prune-recipient-rules - '(("cvs@@example.org" "."))) -@end lisp - -@vindex message-wide-reply-confirm-recipients -If @code{message-wide-reply-confirm-recipients} is non-@code{nil} you -will be asked to confirm that you want to reply to multiple -recipients. The default is @code{nil}. - -@node Followup -@section Followup - -@findex message-followup -The @code{message-followup} command pops up a message buffer that's a -followup to the message in the current buffer. - -@vindex message-followup-to-function -Message uses the normal methods to determine where followups are to go, -but you can change the behavior to suit your needs by fiddling with the -@code{message-followup-to-function}. It is used in the same way as -@code{message-reply-to-function} (@pxref{Reply}). - -@vindex message-use-followup-to -The @code{message-use-followup-to} variable says what to do about -@code{Followup-To} headers. If it is @code{use}, always use the value. -If it is @code{ask} (which is the default), ask whether to use the -value. If it is @code{t}, use the value unless it is @samp{poster}. If -it is @code{nil}, don't use the value. - - -@node Canceling News -@section Canceling News - -@findex message-cancel-news -The @code{message-cancel-news} command cancels the article in the -current buffer. - -@vindex message-cancel-message -The value of @code{message-cancel-message} is inserted in the body of -the cancel message. The default is @samp{I am canceling my own -article.}. - -@cindex Cancel Locks -@vindex message-insert-canlock -@cindex canlock -When Message posts news messages, it inserts @code{Cancel-Lock} -headers by default. This is a cryptographic header that ensures that -only you can cancel your own messages, which is nice. The downside -is that if you lose your @file{.emacs} file (which is where Gnus -stores the secret cancel lock password (which is generated -automatically the first time you use this feature)), you won't be -able to cancel your message. If you want to manage a password yourself, -you can put something like the following in your @file{~/.gnus.el} file: - -@lisp -(setq canlock-password "geheimnis" - canlock-password-for-verify canlock-password) -@end lisp - -Whether to insert the header or not is controlled by the -@code{message-insert-canlock} variable. - -Not many news servers respect the @code{Cancel-Lock} header yet, but -this is expected to change in the future. - - -@node Superseding -@section Superseding - -@findex message-supersede -The @code{message-supersede} command pops up a message buffer that will -supersede the message in the current buffer. - -@vindex message-ignored-supersedes-headers -Headers matching the @code{message-ignored-supersedes-headers} are -removed before popping up the new message buffer. The default is@* -@samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|@* -^Received:\\|^X-From-Line:\\|^X-Trace:\\|^X-Complaints-To:\\|@* -Return-Path:\\|^Supersedes:\\|^NNTP-Posting-Date:\\|^X-Trace:\\|@* -^X-Complaints-To:\\|^Cancel-Lock:\\|^Cancel-Key:\\|^X-Hashcash:\\|@* -^X-Payment:\\|^Approved:}. - - - -@node Forwarding -@section Forwarding - -@findex message-forward -The @code{message-forward} command pops up a message buffer to forward -the message in the current buffer. If given a prefix, forward using -news. - -@table @code -@item message-forward-ignored-headers -@vindex message-forward-ignored-headers -All headers that match this regexp will be deleted when forwarding a message. - -@item message-make-forward-subject-function -@vindex message-make-forward-subject-function -A list of functions that are called to generate a subject header for -forwarded messages. The subject generated by the previous function is -passed into each successive function. - -The provided functions are: - -@table @code -@item message-forward-subject-author-subject -@findex message-forward-subject-author-subject -Source of article (author or newsgroup), in brackets followed by the -subject. - -@item message-forward-subject-fwd -Subject of article with @samp{Fwd:} prepended to it. -@end table - -@item message-wash-forwarded-subjects -@vindex message-wash-forwarded-subjects -If this variable is @code{t}, the subjects of forwarded messages have -the evidence of previous forwards (such as @samp{Fwd:}, @samp{Re:}, -@samp{(fwd)}) removed before the new subject is -constructed. The default value is @code{nil}. - -@item message-forward-as-mime -@vindex message-forward-as-mime -If this variable is @code{t} (the default), forwarded messages are -included as inline @acronym{MIME} RFC822 parts. If it's @code{nil}, forwarded -messages will just be copied inline to the new message, like previous, -non @acronym{MIME}-savvy versions of Gnus would do. - -@item message-forward-before-signature -@vindex message-forward-before-signature -If non-@code{nil}, put forwarded message before signature, else after. - -@end table - - -@node Resending -@section Resending - -@findex message-resend -The @code{message-resend} command will prompt the user for an address -and resend the message in the current buffer to that address. - -@vindex message-ignored-resent-headers -Headers that match the @code{message-ignored-resent-headers} regexp will -be removed before sending the message. - - -@node Bouncing -@section Bouncing - -@findex message-bounce -The @code{message-bounce} command will, if the current buffer contains a -bounced mail message, pop up a message buffer stripped of the bounce -information. A @dfn{bounced message} is typically a mail you've sent -out that has been returned by some @code{mailer-daemon} as -undeliverable. - -@vindex message-ignored-bounced-headers -Headers that match the @code{message-ignored-bounced-headers} regexp -will be removed before popping up the buffer. The default is -@samp{^\\(Received\\|Return-Path\\|Delivered-To\\):}. - - -@node Mailing Lists -@section Mailing Lists - -@cindex Mail-Followup-To -Sometimes while posting to mailing lists, the poster needs to direct -followups to the post to specific places. The Mail-Followup-To (MFT) -was created to enable just this. Three example scenarios where this is -useful: - -@itemize @bullet -@item -A mailing list poster can use MFT to express that responses should be -sent to just the list, and not the poster as well. This will happen -if the poster is already subscribed to the list. - -@item -A mailing list poster can use MFT to express that responses should be -sent to the list and the poster as well. This will happen if the poster -is not subscribed to the list. - -@item -If a message is posted to several mailing lists, MFT may also be used -to direct the following discussion to one list only, because -discussions that are spread over several lists tend to be fragmented -and very difficult to follow. - -@end itemize - -Gnus honors the MFT header in other's messages (i.e. while following -up to someone else's post) and also provides support for generating -sensible MFT headers for outgoing messages as well. - -@c @menu -@c * Honoring an MFT post:: What to do when one already exists -@c * Composing with a MFT header:: Creating one from scratch. -@c @end menu - -@c @node Composing with a MFT header -@subsection Composing a correct MFT header automagically - -The first step in getting Gnus to automagically generate a MFT header -in posts you make is to give Gnus a list of the mailing lists -addresses you are subscribed to. You can do this in more than one -way. The following variables would come in handy. - -@table @code - -@vindex message-subscribed-addresses -@item message-subscribed-addresses -This should be a list of addresses the user is subscribed to. Its -default value is @code{nil}. Example: -@lisp -(setq message-subscribed-addresses - '("ding@@gnus.org" "bing@@noose.org")) -@end lisp - -@vindex message-subscribed-regexps -@item message-subscribed-regexps -This should be a list of regexps denoting the addresses of mailing -lists subscribed to. Default value is @code{nil}. Example: If you -want to achieve the same result as above: -@lisp -(setq message-subscribed-regexps - '("\\(ding@@gnus\\)\\|\\(bing@@noose\\)\\.org") -@end lisp - -@vindex message-subscribed-address-functions -@item message-subscribed-address-functions -This can be a list of functions to be called (one at a time!!) to -determine the value of MFT headers. It is advisable that these -functions not take any arguments. Default value is @code{nil}. - -There is a pre-defined function in Gnus that is a good candidate for -this variable. @code{gnus-find-subscribed-addresses} is a function -that returns a list of addresses corresponding to the groups that have -the @code{subscribed} (@pxref{Group Parameters, ,Group Parameters, -gnus, The Gnus Manual}) group parameter set to a non-@code{nil} value. -This is how you would do it. - -@lisp -(setq message-subscribed-address-functions - '(gnus-find-subscribed-addresses)) -@end lisp - -@vindex message-subscribed-address-file -@item message-subscribed-address-file -You might be one organized human freak and have a list of addresses of -all subscribed mailing lists in a separate file! Then you can just -set this variable to the name of the file and life would be good. - -@end table - -You can use one or more of the above variables. All their values are -``added'' in some way that works :-) - -Now you are all set. Just start composing a message as you normally do. -And just send it; as always. Just before the message is sent out, Gnus' -MFT generation thingy kicks in and checks if the message already has a -MFT field. If there is one, it is left alone. (Except if it's empty - -in that case, the field is removed and is not replaced with an -automatically generated one. This lets you disable MFT generation on a -per-message basis.) If there is none, then the list of recipient -addresses (in the To: and Cc: headers) is checked to see if one of them -is a list address you are subscribed to. If none of them is a list -address, then no MFT is generated; otherwise, a MFT is added to the -other headers and set to the value of all addresses in To: and Cc: - -@kindex C-c C-f C-a -@findex message-generate-unsubscribed-mail-followup-to -@kindex C-c C-f C-m -@findex message-goto-mail-followup-to -Hm. ``So'', you ask, ``what if I send an email to a list I am not -subscribed to? I want my MFT to say that I want an extra copy.'' (This -is supposed to be interpreted by others the same way as if there were no -MFT, but you can use an explicit MFT to override someone else's -to-address group parameter.) The function -@code{message-generate-unsubscribed-mail-followup-to} might come in -handy. It is bound to @kbd{C-c C-f C-a} by default. In any case, you -can insert a MFT of your own choice; @kbd{C-c C-f C-m} -(@code{message-goto-mail-followup-to}) will help you get started. - -@c @node Honoring an MFT post -@subsection Honoring an MFT post - -@vindex message-use-mail-followup-to -When you followup to a post on a mailing list, and the post has a MFT -header, Gnus' action will depend on the value of the variable -@code{message-use-mail-followup-to}. This variable can be one of: - -@table @code -@item use - Always honor MFTs. The To: and Cc: headers in your followup will be - derived from the MFT header of the original post. This is the default. - -@item nil - Always dishonor MFTs (just ignore the darned thing) - -@item ask -Gnus will prompt you for an action. - -@end table - -It is considered good netiquette to honor MFT, as it is assumed the -fellow who posted a message knows where the followups need to go -better than you do. - -@node Commands -@chapter Commands - -@menu -* Buffer Entry:: Commands after entering a Message buffer. -* Header Commands:: Commands for moving headers or changing headers. -* Movement:: Moving around in message buffers. -* Insertion:: Inserting things into message buffers. -* MIME:: @acronym{MIME} considerations. -* IDNA:: Non-@acronym{ASCII} domain name considerations. -* Security:: Signing and encrypting messages. -* Various Commands:: Various things. -* Sending:: Actually sending the message. -* Mail Aliases:: How to use mail aliases. -* Spelling:: Having Emacs check your spelling. -@end menu - - -@node Buffer Entry -@section Buffer Entry -@cindex undo -@kindex C-_ - -You most often end up in a Message buffer when responding to some other -message of some sort. Message does lots of handling of quoted text, and -may remove signatures, reformat the text, or the like---depending on -which used settings you're using. Message usually gets things right, -but sometimes it stumbles. To help the user unwind these stumblings, -Message sets the undo boundary before each major automatic action it -takes. If you press the undo key (usually located at @kbd{C-_}) a few -times, you will get back the un-edited message you're responding to. - - -@node Header Commands -@section Header Commands - -@subsection Commands for moving to headers - -These following commands move to the header in question. If it doesn't -exist, it will be inserted. - -@table @kbd - -@item C-c ? -@kindex C-c ? -@findex describe-mode -Describe the message mode. - -@item C-c C-f C-t -@kindex C-c C-f C-t -@findex message-goto-to -Go to the @code{To} header (@code{message-goto-to}). - -@item C-c C-f C-o -@kindex C-c C-f C-o -@findex message-goto-from -Go to the @code{From} header (@code{message-goto-from}). (The ``o'' -in the key binding is for Originator.) - -@item C-c C-f C-b -@kindex C-c C-f C-b -@findex message-goto-bcc -Go to the @code{Bcc} header (@code{message-goto-bcc}). - -@item C-c C-f C-w -@kindex C-c C-f C-w -@findex message-goto-fcc -Go to the @code{Fcc} header (@code{message-goto-fcc}). - -@item C-c C-f C-c -@kindex C-c C-f C-c -@findex message-goto-cc -Go to the @code{Cc} header (@code{message-goto-cc}). - -@item C-c C-f C-s -@kindex C-c C-f C-s -@findex message-goto-subject -Go to the @code{Subject} header (@code{message-goto-subject}). - -@item C-c C-f C-r -@kindex C-c C-f C-r -@findex message-goto-reply-to -Go to the @code{Reply-To} header (@code{message-goto-reply-to}). - -@item C-c C-f C-n -@kindex C-c C-f C-n -@findex message-goto-newsgroups -Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}). - -@item C-c C-f C-d -@kindex C-c C-f C-d -@findex message-goto-distribution -Go to the @code{Distribution} header (@code{message-goto-distribution}). - -@item C-c C-f C-f -@kindex C-c C-f C-f -@findex message-goto-followup-to -Go to the @code{Followup-To} header (@code{message-goto-followup-to}). - -@item C-c C-f C-k -@kindex C-c C-f C-k -@findex message-goto-keywords -Go to the @code{Keywords} header (@code{message-goto-keywords}). - -@item C-c C-f C-u -@kindex C-c C-f C-u -@findex message-goto-summary -Go to the @code{Summary} header (@code{message-goto-summary}). - -@item C-c C-f C-i -@kindex C-c C-f C-i -@findex message-insert-or-toggle-importance -This inserts the @samp{Importance:} header with a value of -@samp{high}. This header is used to signal the importance of the -message to the receiver. If the header is already present in the -buffer, it cycles between the three valid values according to RFC -1376: @samp{low}, @samp{normal} and @samp{high}. - -@item C-c C-f C-a -@kindex C-c C-f C-a -@findex message-generate-unsubscribed-mail-followup-to -Insert a reasonable @samp{Mail-Followup-To:} header -(@pxref{Mailing Lists}) in a post to an -unsubscribed list. When making original posts to a mailing list you are -not subscribed to, you have to type in a @samp{Mail-Followup-To:} header -by hand. The contents, usually, are the addresses of the list and your -own address. This function inserts such a header automatically. It -fetches the contents of the @samp{To:} header in the current mail -buffer, and appends the current @code{user-mail-address}. - -If the optional argument @code{include-cc} is non-@code{nil}, the -addresses in the @samp{Cc:} header are also put into the -@samp{Mail-Followup-To:} header. - -@end table - -@subsection Commands to change headers - -@table @kbd - -@item C-c C-o -@kindex C-c C-o -@findex message-sort-headers -@vindex message-header-format-alist -Sort headers according to @code{message-header-format-alist} -(@code{message-sort-headers}). - -@item C-c C-t -@kindex C-c C-t -@findex message-insert-to -Insert a @code{To} header that contains the @code{Reply-To} or -@code{From} header of the message you're following up -(@code{message-insert-to}). - -@item C-c C-n -@kindex C-c C-n -@findex message-insert-newsgroups -Insert a @code{Newsgroups} header that reflects the @code{Followup-To} -or @code{Newsgroups} header of the article you're replying to -(@code{message-insert-newsgroups}). - -@item C-c C-l -@kindex C-c C-l -@findex message-to-list-only -Send a message to the list only. Remove all addresses but the list -address from @code{To:} and @code{Cc:} headers. - -@item C-c M-n -@kindex C-c M-n -@findex message-insert-disposition-notification-to -Insert a request for a disposition -notification. (@code{message-insert-disposition-notification-to}). -This means that if the recipient supports RFC 2298 she might send you a -notification that she received the message. - -@item M-x message-insert-importance-high -@kindex M-x message-insert-importance-high -@findex message-insert-importance-high -@cindex Importance -Insert an @samp{Importance} header with a value of @samp{high}, -deleting headers if necessary. - -@item M-x message-insert-importance-low -@kindex M-x message-insert-importance-low -@findex message-insert-importance-low -@cindex Importance -Insert an @samp{Importance} header with a value of @samp{low}, deleting -headers if necessary. - -@item C-c C-f s -@kindex C-c C-f s -@findex message-change-subject -@cindex Subject -Change the current @samp{Subject} header. Ask for new @samp{Subject} -header and append @samp{(was: )}. The old subject can be -stripped on replying, see @code{message-subject-trailing-was-query} -(@pxref{Message Headers}). - -@item C-c C-f x -@kindex C-c C-f x -@findex message-cross-post-followup-to -@vindex message-cross-post-default -@vindex message-cross-post-note-function -@cindex X-Post -@cindex cross-post -Set up the @samp{FollowUp-To} header with a target newsgroup for a -cross-post, add that target newsgroup to the @samp{Newsgroups} header if -it is not a member of @samp{Newsgroups}, and insert a note in the body. -If @code{message-cross-post-default} is @code{nil} or if this command is -called with a prefix-argument, only the @samp{FollowUp-To} header will -be set but the target newsgroup will not be added to the -@samp{Newsgroups} header. The function to insert a note is controlled -by the @code{message-cross-post-note-function} variable. - -@item C-c C-f t -@kindex C-c C-f t -@findex message-reduce-to-to-cc -Replace contents of @samp{To} header with contents of @samp{Cc} or -@samp{Bcc} header. (Iff @samp{Cc} header is not present, @samp{Bcc} -header will be used instead.) - -@item C-c C-f w -@kindex C-c C-f w -@findex message-insert-wide-reply -Insert @samp{To} and @samp{Cc} headers as if you were doing a wide -reply even if the message was not made for a wide reply first. - -@item C-c C-f a -@kindex C-c C-f a -@findex message-add-archive-header -@vindex message-archive-header -@vindex message-archive-note -@cindex X-No-Archive -Insert @samp{X-No-Archive: Yes} in the header and a note in the body. -The header and the note can be customized using -@code{message-archive-header} and @code{message-archive-note}. When -called with a prefix argument, ask for a text to insert. If you don't -want the note in the body, set @code{message-archive-note} to -@code{nil}. - -@end table - - -@node Movement -@section Movement - -@table @kbd -@item C-c C-b -@kindex C-c C-b -@findex message-goto-body -Move to the beginning of the body of the message -(@code{message-goto-body}). - -@item C-c C-i -@kindex C-c C-i -@findex message-goto-signature -Move to the signature of the message (@code{message-goto-signature}). - -@item C-a -@kindex C-a -@findex message-beginning-of-line -@vindex message-beginning-of-line -If at beginning of header value, go to beginning of line, else go to -beginning of header value. (The header value comes after the header -name and the colon.) This behavior can be disabled by toggling -the variable @code{message-beginning-of-line}. - -@end table - - -@node Insertion -@section Insertion - -@table @kbd - -@item C-c C-y -@kindex C-c C-y -@findex message-yank-original -Yank the message that's being replied to into the message buffer -(@code{message-yank-original}). - -@item C-c C-M-y -@kindex C-c C-M-y -@findex message-yank-buffer -Prompt for a buffer name and yank the contents of that buffer into the -message buffer (@code{message-yank-buffer}). - -@item C-c C-q -@kindex C-c C-q -@findex message-fill-yanked-message -Fill the yanked message (@code{message-fill-yanked-message}). Warning: -Can severely mess up the yanked text if its quoting conventions are -strange. You'll quickly get a feel for when it's safe, though. Anyway, -just remember that @kbd{C-x u} (@code{undo}) is available and you'll be -all right. - -@item C-c C-w -@kindex C-c C-w -@findex message-insert-signature -Insert a signature at the end of the buffer -(@code{message-insert-signature}). - -@item C-c M-h -@kindex C-c M-h -@findex message-insert-headers -Insert the message headers (@code{message-insert-headers}). - -@item C-c M-m -@kindex C-c M-m -@findex message-mark-inserted-region -Mark some region in the current article with enclosing tags. See -@code{message-mark-insert-begin} and @code{message-mark-insert-end}. -When called with a prefix argument, use slrn style verbatim marks -(@samp{#v+} and @samp{#v-}). - -@item C-c M-f -@kindex C-c M-f -@findex message-mark-insert-file -Insert a file in the current article with enclosing tags. -See @code{message-mark-insert-begin} and @code{message-mark-insert-end}. -When called with a prefix argument, use slrn style verbatim marks -(@samp{#v+} and @samp{#v-}). - -@end table - - -@node MIME -@section MIME -@cindex MML -@cindex MIME -@cindex multipart -@cindex attachment - -Message is a @acronym{MIME}-compliant posting agent. The user generally -doesn't have to do anything to make the @acronym{MIME} happen---Message will -automatically add the @code{Content-Type} and -@code{Content-Transfer-Encoding} headers. - -@findex mml-attach-file -@kindex C-c C-a -The most typical thing users want to use the multipart things in -@acronym{MIME} for is to add ``attachments'' to mail they send out. -This can be done with the @kbd{C-c C-a} command (@kbd{M-x mml-attach-file}), -which will prompt for a file name and a @acronym{MIME} type. - -@vindex mml-dnd-protocol-alist -@vindex mml-dnd-attach-options -If your Emacs supports drag and drop, you can also drop the file in the -Message buffer. The variable @code{mml-dnd-protocol-alist} specifies -what kind of action is done when you drop a file into the Message -buffer. The variable @code{mml-dnd-attach-options} controls which -@acronym{MIME} options you want to specify when dropping a file. If it -is a list, valid members are @code{type}, @code{description} and -@code{disposition}. @code{disposition} implies @code{type}. If it is -@code{nil}, don't ask for options. If it is @code{t}, ask the user -whether or not to specify options. - -You can also create arbitrarily complex multiparts using the @acronym{MML} -language (@pxref{Composing, , Composing, emacs-mime, The Emacs MIME -Manual}). - -@node IDNA -@section IDNA -@cindex IDNA -@cindex internationalized domain names -@cindex non-ascii domain names - -@acronym{IDNA} is a standard way to encode non-@acronym{ASCII} domain -names into a readable @acronym{ASCII} string. The details can be -found in RFC 3490. - -Message is a @acronym{IDNA}-compliant posting agent. The user -generally doesn't have to do anything to make the @acronym{IDNA} -happen---Message will encode non-@acronym{ASCII} domain names in @code{From}, -@code{To}, and @code{Cc} headers automatically. - -Until @acronym{IDNA} becomes more well known, Message queries you -whether @acronym{IDNA} encoding of the domain name really should -occur. Some users might not be aware that domain names can contain -non-@acronym{ASCII} now, so this gives them a safety net if they accidentally -typed a non-@acronym{ASCII} domain name. - -@vindex message-use-idna -The @code{message-use-idna} variable control whether @acronym{IDNA} is -used. If the variable is @code{nil} no @acronym{IDNA} encoding will -ever happen, if it is set to the symbol @code{ask} the user will be -queried, and if set to @code{t} (which is the default if @acronym{IDNA} -is fully available) @acronym{IDNA} encoding happens automatically. - -@findex message-idna-to-ascii-rhs -If you want to experiment with the @acronym{IDNA} encoding, you can -invoke @kbd{M-x message-idna-to-ascii-rhs RET} in the message buffer -to have the non-@acronym{ASCII} domain names encoded while you edit -the message. - -Note that you must have @uref{http://www.gnu.org/software/libidn/, GNU -Libidn} installed in order to use this functionality. - -@node Security -@section Security -@cindex Security -@cindex S/MIME -@cindex PGP -@cindex PGP/MIME -@cindex sign -@cindex encrypt -@cindex secure - -Using the @acronym{MML} language, Message is able to create digitally -signed and digitally encrypted messages. Message (or rather -@acronym{MML}) currently support @acronym{PGP} (RFC 1991), -@acronym{PGP/MIME} (RFC 2015/3156) and @acronym{S/MIME}. - -@menu -* Signing and encryption:: Signing and encrypting commands. -* Using S/MIME:: Using S/MIME -* Using PGP/MIME:: Using PGP/MIME -* PGP Compatibility:: Compatibility with older implementations -@end menu - -@node Signing and encryption -@subsection Signing and encrypting commands - -Instructing @acronym{MML} to perform security operations on a -@acronym{MIME} part is done using the @kbd{C-c C-m s} key map for -signing and the @kbd{C-c C-m c} key map for encryption, as follows. -@table @kbd - -@item C-c C-m s s -@kindex C-c C-m s s -@findex mml-secure-message-sign-smime - -Digitally sign current message using @acronym{S/MIME}. - -@item C-c C-m s o -@kindex C-c C-m s o -@findex mml-secure-message-sign-pgp - -Digitally sign current message using @acronym{PGP}. - -@item C-c C-m s p -@kindex C-c C-m s p -@findex mml-secure-message-sign-pgpmime - -Digitally sign current message using @acronym{PGP/MIME}. - -@item C-c C-m c s -@kindex C-c C-m c s -@findex mml-secure-message-encrypt-smime - -Digitally encrypt current message using @acronym{S/MIME}. - -@item C-c C-m c o -@kindex C-c C-m c o -@findex mml-secure-message-encrypt-pgp - -Digitally encrypt current message using @acronym{PGP}. - -@item C-c C-m c p -@kindex C-c C-m c p -@findex mml-secure-message-encrypt-pgpmime - -Digitally encrypt current message using @acronym{PGP/MIME}. - -@item C-c C-m C-n -@kindex C-c C-m C-n -@findex mml-unsecure-message -Remove security related @acronym{MML} tags from message. - -@end table - -These commands do not immediately sign or encrypt the message, they -merely insert the proper @acronym{MML} secure tag to instruct the -@acronym{MML} engine to perform that operation when the message is -actually sent. They may perform other operations too, such as locating -and retrieving a @acronym{S/MIME} certificate of the person you wish to -send encrypted mail to. When the mml parsing engine converts your -@acronym{MML} into a properly encoded @acronym{MIME} message, the secure -tag will be replaced with either a part or a multipart tag. If your -message contains other mml parts, a multipart tag will be used; if no -other parts are present in your message a single part tag will be used. -This way, message mode will do the Right Thing (TM) with -signed/encrypted multipart messages. - -Since signing and especially encryption often is used when sensitive -information is sent, you may want to have some way to ensure that your -mail is actually signed or encrypted. After invoking the above -sign/encrypt commands, it is possible to preview the raw article by -using @kbd{C-u C-c RET P} (@code{mml-preview}). Then you can -verify that your long rant about what your ex-significant other or -whomever actually did with that funny looking person at that strange -party the other night, actually will be sent encrypted. - -@emph{Note!} Neither @acronym{PGP/MIME} nor @acronym{S/MIME} encrypt/signs -RFC822 headers. They only operate on the @acronym{MIME} object. Keep this -in mind before sending mail with a sensitive Subject line. - -By default, when encrypting a message, Gnus will use the -``signencrypt'' mode, which means the message is both signed and -encrypted. If you would like to disable this for a particular -message, give the @code{mml-secure-message-encrypt-*} command a prefix -argument, e.g., @kbd{C-u C-c C-m c p}. - -Actually using the security commands above is not very difficult. At -least not compared with making sure all involved programs talk with each -other properly. Thus, we now describe what external libraries or -programs are required to make things work, and some small general hints. - -@node Using S/MIME -@subsection Using S/MIME - -@emph{Note!} This section assume you have a basic familiarity with -modern cryptography, @acronym{S/MIME}, various PKCS standards, OpenSSL and -so on. - -The @acronym{S/MIME} support in Message (and @acronym{MML}) require -OpenSSL. OpenSSL performs the actual @acronym{S/MIME} sign/encrypt -operations. OpenSSL can be found at @uref{http://www.openssl.org/}. -OpenSSL 0.9.6 and later should work. Version 0.9.5a cannot extract mail -addresses from certificates, and it insert a spurious CR character into -@acronym{MIME} separators so you may wish to avoid it if you would like -to avoid being regarded as someone who send strange mail. (Although by -sending @acronym{S/MIME} messages you've probably already lost that -contest.) - -To be able to send encrypted mail, a personal certificate is not -required. Message (@acronym{MML}) need a certificate for the person to whom you -wish to communicate with though. You're asked for this when you type -@kbd{C-c C-m c s}. Currently there are two ways to retrieve this -certificate, from a local file or from DNS. If you chose a local -file, it need to contain a X.509 certificate in @acronym{PEM} format. -If you chose DNS, you're asked for the domain name where the -certificate is stored, the default is a good guess. To my belief, -Message (@acronym{MML}) is the first mail agent in the world to support -retrieving @acronym{S/MIME} certificates from DNS, so you're not -likely to find very many certificates out there. At least there -should be one, stored at the domain @code{simon.josefsson.org}. LDAP -is a more popular method of distributing certificates, support for it -is planned. (Meanwhile, you can use @code{ldapsearch} from the -command line to retrieve a certificate into a file and use it.) - -As for signing messages, OpenSSL can't perform signing operations -without some kind of configuration. Especially, you need to tell it -where your private key and your certificate is stored. @acronym{MML} -uses an Emacs interface to OpenSSL, aptly named @code{smime.el}, and it -contain a @code{custom} group used for this configuration. So, try -@kbd{M-x customize-group RET smime RET} and look around. - -Currently there is no support for talking to a CA (or RA) to create -your own certificate. None is planned either. You need to do this -manually with OpenSSL or using some other program. I used Netscape -and got a free @acronym{S/MIME} certificate from one of the big CA's on the -net. Netscape is able to export your private key and certificate in -PKCS #12 format. Use OpenSSL to convert this into a plain X.509 -certificate in PEM format as follows. - -@example -$ openssl pkcs12 -in ns.p12 -clcerts -nodes > key+cert.pem -@end example - -The @file{key+cert.pem} file should be pointed to from the -@code{smime-keys} variable. You should now be able to send signed mail. - -@emph{Note!} Your private key is now stored unencrypted in the file, -so take care in handling it. Storing encrypted keys on the disk are -supported, and Gnus will ask you for a passphrase before invoking -OpenSSL. Read the OpenSSL documentation for how to achieve this. If -you use unencrypted keys (e.g., if they are on a secure storage, or if -you are on a secure single user machine) simply press @code{RET} at -the passphrase prompt. - -@node Using PGP/MIME -@subsection Using PGP/MIME - -@acronym{PGP/MIME} requires an external OpenPGP implementation, such -as @uref{http://www.gnupg.org/, GNU Privacy Guard}. Pre-OpenPGP -implementations such as PGP 2.x and PGP 5.x are also supported. The -default Emacs interface to the PGP implementation is EasyPG -(@pxref{Top,,EasyPG Assistant User's Manual, epa, EasyPG Assistant -User's Manual}), but PGG (@pxref{Top, ,PGG, pgg, PGG Manual}) and -Mailcrypt are also supported. @xref{PGP Compatibility}. - -@cindex gpg-agent -Message internally calls GnuPG (the @command{gpg} command) to perform -data encryption, and in certain cases (decrypting or signing for -example), @command{gpg} requires user's passphrase. Currently the -recommended way to supply your passphrase to @command{gpg} is to use the -@command{gpg-agent} program. - -To use @command{gpg-agent} in Emacs, you need to run the following -command from the shell before starting Emacs. - -@example -eval `gpg-agent --daemon` -@end example - -This will invoke @command{gpg-agent} and set the environment variable -@code{GPG_AGENT_INFO} to allow @command{gpg} to communicate with it. -It might be good idea to put this command in your @file{.xsession} or -@file{.bash_profile}. @xref{Invoking GPG-AGENT, , , gnupg, Using the -GNU Privacy Guard}. - -Once your @command{gpg-agent} is set up, it will ask you for a -passphrase as needed for @command{gpg}. Under the X Window System, -you will see a new passphrase input dialog appear. The dialog is -provided by PIN Entry (the @command{pinentry} command), and as of -version 0.7.2, @command{pinentry} cannot cooperate with Emacs on a -single tty. So, if you are using a text console, you may need to put -a passphrase into gpg-agent's cache beforehand. The following command -does the trick. - -@example -gpg --use-agent --sign < /dev/null > /dev/null -@end example - -@node PGP Compatibility -@subsection Compatibility with older implementations - -@vindex gpg-temp-directory -Note, if you are using the @code{gpg.el} you must make sure that the -directory specified by @code{gpg-temp-directory} have permissions -0700. - -Creating your own key is described in detail in the documentation of -your PGP implementation, so we refer to it. - -If you have imported your old PGP 2.x key into GnuPG, and want to send -signed and encrypted messages to your fellow PGP 2.x users, you'll -discover that the receiver cannot understand what you send. One -solution is to use PGP 2.x instead (e.g.@: if you use @code{pgg}, set -@code{pgg-default-scheme} to @code{pgp}). You could also convince your -fellow PGP 2.x users to convert to GnuPG. -@vindex mml-signencrypt-style-alist -As a final workaround, you can make the sign and encryption work in -two steps; separately sign, then encrypt a message. If you would like -to change this behavior you can customize the -@code{mml-signencrypt-style-alist} variable. For example: - -@lisp -(setq mml-signencrypt-style-alist '(("smime" separate) - ("pgp" separate) - ("pgpauto" separate) - ("pgpmime" separate))) -@end lisp - -This causes to sign and encrypt in two passes, thus generating a -message that can be understood by PGP version 2. - -(Refer to @uref{http://www.gnupg.org/gph/en/pgp2x.html} for more -information about the problem.) - -@node Various Commands -@section Various Commands - -@table @kbd - -@item C-c C-r -@kindex C-c C-r -@findex message-caesar-buffer-body -Caesar rotate (aka. rot13) the current message -(@code{message-caesar-buffer-body}). If narrowing is in effect, just -rotate the visible portion of the buffer. A numerical prefix says how -many places to rotate the text. The default is 13. - -@item C-c C-e -@kindex C-c C-e -@findex message-elide-region -@vindex message-elide-ellipsis -Elide the text between point and mark (@code{message-elide-region}). -The text is killed and replaced with the contents of the variable -@code{message-elide-ellipsis}. The default value is to use an ellipsis -(@samp{[...]}). - -This is a format-spec string, and you can use @samp{%l} to say how -many lines were removed, and @samp{%c} to say how many characters were -removed. - -@item C-c M-k -@kindex C-c M-k -@findex message-kill-address -Kill the address under point. - -@item C-c C-z -@kindex C-c C-z -@findex message-kill-to-signature -Kill all the text up to the signature, or if that's missing, up to the -end of the message (@code{message-kill-to-signature}). - -@item C-c C-v -@kindex C-c C-v -@findex message-delete-not-region -Delete all text in the body of the message that is outside the region -(@code{message-delete-not-region}). - -@item M-RET -@kindex M-RET -@findex message-newline-and-reformat -Insert four newlines, and then reformat if inside quoted text. - -Here's an example: - -@example -> This is some quoted text. And here's more quoted text. -@end example - -If point is before @samp{And} and you press @kbd{M-RET}, you'll get: - -@example -> This is some quoted text. - -* - -> And here's more quoted text. -@end example - -@samp{*} says where point will be placed. - -@item C-c M-r -@kindex C-c M-r -@findex message-rename-buffer -Rename the buffer (@code{message-rename-buffer}). If given a prefix, -prompt for a new buffer name. - -@item TAB -@kindex TAB -@findex message-tab -@vindex message-tab-body-function -If @code{message-tab-body-function} is non-@code{nil}, execute the -function it specifies. Otherwise use the function bound to @kbd{TAB} in -@code{text-mode-map} or @code{global-map}. - -@end table - - -@node Sending -@section Sending - -@table @kbd -@item C-c C-c -@kindex C-c C-c -@findex message-send-and-exit -Send the message and bury the current buffer -(@code{message-send-and-exit}). - -@item C-c C-s -@kindex C-c C-s -@findex message-send -Send the message (@code{message-send}). - -@item C-c C-d -@kindex C-c C-d -@findex message-dont-send -Bury the message buffer and exit (@code{message-dont-send}). - -@item C-c C-k -@kindex C-c C-k -@findex message-kill-buffer -Kill the message buffer and exit (@code{message-kill-buffer}). - -@end table - - - -@node Mail Aliases -@section Mail Aliases -@cindex mail aliases -@cindex aliases -@cindex completion -@cindex ecomplete - -@vindex message-mail-alias-type -The @code{message-mail-alias-type} variable controls what type of mail -alias expansion to use. Currently two forms are supported: -@code{mailabbrev} and @code{ecomplete}. If this variable is -@code{nil}, no mail alias expansion will be performed. - -@code{mailabbrev} works by parsing the @file{/etc/mailrc} and -@file{~/.mailrc} files. These files look like: - -@example -alias lmi "Lars Magne Ingebrigtsen " -alias ding "ding@@ifi.uio.no (ding mailing list)" -@end example - -After adding lines like this to your @file{~/.mailrc} file, you should -be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so -on) headers and press @kbd{SPC} to expand the alias. - -No expansion will be performed upon sending of the message---all -expansions have to be done explicitly. - -If you're using @code{ecomplete}, all addresses from @code{To} and -@code{Cc} headers will automatically be put into the -@file{~/.ecompleterc} file. When you enter text in the @code{To} and -@code{Cc} headers, @code{ecomplete} will check out the values stored -there and ``electrically'' say what completions are possible. To -choose one of these completions, use the @kbd{M-n} command to move -down to the list. Use @kbd{M-n} and @kbd{M-p} to move down and up the -list, and @kbd{RET} to choose a completion. - -@node Spelling -@section Spelling -@cindex spelling -@findex ispell-message - -There are two popular ways to have Emacs spell-check your messages: -@code{ispell} and @code{flyspell}. @code{ispell} is the older and -probably more popular package. You typically first write the message, -and then run the entire thing through @code{ispell} and fix all the -typos. To have this happen automatically when you send a message, put -something like the following in your @file{.emacs} file: - -@lisp -(add-hook 'message-send-hook 'ispell-message) -@end lisp - -@vindex ispell-message-dictionary-alist -If you're in the habit of writing in different languages, this can be -controlled by the @code{ispell-message-dictionary-alist} variable: - -@lisp -(setq ispell-message-dictionary-alist - '(("^Newsgroups:.*\\bde\\." . "deutsch8") - (".*" . "default"))) -@end lisp - -@code{ispell} depends on having the external @samp{ispell} command -installed. - -The other popular method is using @code{flyspell}. This package checks -your spelling while you're writing, and marks any mis-spelled words in -various ways. - -To use @code{flyspell}, put something like the following in your -@file{.emacs} file: - -@lisp -(defun my-message-setup-routine () - (flyspell-mode 1)) -(add-hook 'message-setup-hook 'my-message-setup-routine) -@end lisp - -@code{flyspell} depends on having the external @samp{ispell} command -installed. - - -@node Variables -@chapter Variables - -@menu -* Message Headers:: General message header stuff. -* Mail Headers:: Customizing mail headers. -* Mail Variables:: Other mail variables. -* News Headers:: Customizing news headers. -* News Variables:: Other news variables. -* Insertion Variables:: Customizing how things are inserted. -* Various Message Variables:: Other message variables. -* Sending Variables:: Variables for sending. -* Message Buffers:: How Message names its buffers. -* Message Actions:: Actions to be performed when exiting. -@end menu - - -@node Message Headers -@section Message Headers - -Message is quite aggressive on the message generation front. It has to -be---it's a combined news and mail agent. To be able to send combined -messages, it has to generate all headers itself (instead of letting the -mail/news system do it) to ensure that mail and news copies of messages -look sufficiently similar. - -@table @code - -@item message-generate-headers-first -@vindex message-generate-headers-first -If @code{t}, generate all required headers before starting to -compose the message. This can also be a list of headers to generate: - -@lisp -(setq message-generate-headers-first - '(References)) -@end lisp - -@vindex message-required-headers -The variables @code{message-required-headers}, -@code{message-required-mail-headers} and -@code{message-required-news-headers} specify which headers are -required. - -Note that some headers will be removed and re-generated before posting, -because of the variable @code{message-deletable-headers} (see below). - -@item message-draft-headers -@vindex message-draft-headers -When running Message from Gnus, the message buffers are associated -with a draft group. @code{message-draft-headers} says which headers -should be generated when a draft is written to the draft group. - -@item message-from-style -@vindex message-from-style -Specifies how @code{From} headers should look. There are four valid -values: - -@table @code -@item nil -Just the address---@samp{king@@grassland.com}. - -@item parens -@samp{king@@grassland.com (Elvis Parsley)}. - -@item angles -@samp{Elvis Parsley }. - -@item default -Look like @code{angles} if that doesn't require quoting, and -@code{parens} if it does. If even @code{parens} requires quoting, use -@code{angles} anyway. - -@end table - -@item message-deletable-headers -@vindex message-deletable-headers -Headers in this list that were previously generated by Message will be -deleted before posting. Let's say you post an article. Then you decide -to post it again to some other group, you naughty boy, so you jump back -to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and -ship it off again. By default, this variable makes sure that the old -generated @code{Message-ID} is deleted, and a new one generated. If -this isn't done, the entire empire would probably crumble, anarchy would -prevail, and cats would start walking on two legs and rule the world. -Allegedly. - -@item message-default-headers -@vindex message-default-headers -Header lines to be inserted in outgoing messages before you edit the -message, so you can edit or delete their lines. If set to a string, it -is directly inserted. If set to a function, it is called and its -result is inserted. - -@item message-subject-re-regexp -@vindex message-subject-re-regexp -@cindex Aw -@cindex Sv -@cindex Re -Responses to messages have subjects that start with @samp{Re: }. This -is @emph{not} an abbreviation of the English word ``response'', but is -Latin, and means ``in response to''. Some illiterate nincompoops have -failed to grasp this fact, and have ``internationalized'' their software -to use abominations like @samp{Aw: } (``antwort'') or @samp{Sv: } -(``svar'') instead, which is meaningless and evil. However, you may -have to deal with users that use these evil tools, in which case you may -set this variable to a regexp that matches these prefixes. Myself, I -just throw away non-compliant mail. - -Here's an example of a value to deal with these headers when -responding to a message: - -@lisp -(setq message-subject-re-regexp - (concat - "^[ \t]*" - "\\(" - "\\(" - "[Aa][Nn][Tt][Ww]\\.?\\|" ; antw - "[Aa][Ww]\\|" ; aw - "[Ff][Ww][Dd]?\\|" ; fwd - "[Oo][Dd][Pp]\\|" ; odp - "[Rr][Ee]\\|" ; re - "[Rr][\311\351][Ff]\\.?\\|" ; ref - "[Ss][Vv]" ; sv - "\\)" - "\\(\\[[0-9]*\\]\\)" - "*:[ \t]*" - "\\)" - "*[ \t]*" - )) -@end lisp - -@item message-subject-trailing-was-query -@vindex message-subject-trailing-was-query -@vindex message-subject-trailing-was-ask-regexp -@vindex message-subject-trailing-was-regexp -Controls what to do with trailing @samp{(was: )} in subject -lines. If @code{nil}, leave the subject unchanged. If it is the symbol -@code{ask}, query the user what to do. In this case, the subject is -matched against @code{message-subject-trailing-was-ask-regexp}. If -@code{message-subject-trailing-was-query} is @code{t}, always strip the -trailing old subject. In this case, -@code{message-subject-trailing-was-regexp} is used. - -@item message-alternative-emails -@vindex message-alternative-emails -Regexp matching alternative email addresses. The first address in the -To, Cc or From headers of the original article matching this variable is -used as the From field of outgoing messages, replacing the default From -value. - -For example, if you have two secondary email addresses john@@home.net -and john.doe@@work.com and want to use them in the From field when -composing a reply to a message addressed to one of them, you could set -this variable like this: - -@lisp -(setq message-alternative-emails - (regexp-opt '("john@@home.net" "john.doe@@work.com"))) -@end lisp - -This variable has precedence over posting styles and anything that runs -off @code{message-setup-hook}. - -@item message-allow-no-recipients -@vindex message-allow-no-recipients -Specifies what to do when there are no recipients other than -@code{Gcc} or @code{Fcc}. If it is @code{always}, the posting is -allowed. If it is @code{never}, the posting is not allowed. If it is -@code{ask} (the default), you are prompted. - -@item message-hidden-headers -@vindex message-hidden-headers -A regexp, a list of regexps, or a list where the first element is -@code{not} and the rest are regexps. It says which headers to keep -hidden when composing a message. - -@lisp -(setq message-hidden-headers - '(not "From" "Subject" "To" "Cc" "Newsgroups")) -@end lisp - -Headers are hidden using narrowing, you can use @kbd{M-x widen} to -expose them in the buffer. - -@item message-header-synonyms -@vindex message-header-synonyms -A list of lists of header synonyms. E.g., if this list contains a -member list with elements @code{Cc} and @code{To}, then -@code{message-carefully-insert-headers} will not insert a @code{To} -header when the message is already @code{Cc}ed to the recipient. - -@end table - - -@node Mail Headers -@section Mail Headers - -@table @code -@item message-required-mail-headers -@vindex message-required-mail-headers -@xref{News Headers}, for the syntax of this variable. It is -@code{(From Subject Date (optional . In-Reply-To) Message-ID -(optional . User-Agent))} by default. - -@item message-ignored-mail-headers -@vindex message-ignored-mail-headers -Regexp of headers to be removed before mailing. The default is@* -@samp{^[GF]cc:\\|^Resent-Fcc:\\|^Xref:\\|^X-Draft-From:\\|@* -^X-Gnus-Agent-Meta-Information:}. - -@item message-default-mail-headers -@vindex message-default-mail-headers -This string is inserted at the end of the headers in all message -buffers that are initialized as mail. - -@item message-generate-hashcash -@vindex message-generate-hashcash -Variable that indicates whether @samp{X-Hashcash} headers -should be computed for the message. @xref{Hashcash, ,Hashcash,gnus, -The Gnus Manual}. If @code{opportunistic}, only generate the headers -when it doesn't lead to the user having to wait. - -@end table - - -@node Mail Variables -@section Mail Variables - -@table @code -@item message-send-mail-function -@vindex message-send-mail-function -@findex message-send-mail-function -@findex message-send-mail-with-sendmail -@findex message-send-mail-with-mh -@findex message-send-mail-with-qmail -@findex message-smtpmail-send-it -@findex smtpmail-send-it -@findex feedmail-send-it -@findex message-send-mail-with-mailclient -Function used to send the current buffer as mail. The default is -@code{message-send-mail-with-sendmail}, or @code{smtpmail-send-it} -according to the system. Other valid values include -@code{message-send-mail-with-mailclient}, -@code{message-send-mail-with-mh}, @code{message-send-mail-with-qmail}, -@code{message-smtpmail-send-it} and @code{feedmail-send-it}. - -The function -@code{message-send-mail-with-sendmail} pipes your article to the -@code{sendmail} binary for further queuing and sending. When your local -system is not configured for sending mail using @code{sendmail}, and you -have access to a remote @acronym{SMTP} server, you can set -@code{message-send-mail-function} to @code{smtpmail-send-it} and make -sure to setup the @code{smtpmail} package correctly. An example: - -@lisp -(setq message-send-mail-function 'smtpmail-send-it - smtpmail-default-smtp-server "YOUR SMTP HOST") -@end lisp - -To the thing similar to this, there is -@code{message-smtpmail-send-it}. It is useful if your @acronym{ISP} -requires the @acronym{POP}-before-@acronym{SMTP} authentication. -@xref{POP before SMTP, , POP before SMTP, gnus, The Gnus Manual}. - -@item message-mh-deletable-headers -@vindex message-mh-deletable-headers -Most versions of MH doesn't like being fed messages that contain the -headers in this variable. If this variable is non-@code{nil} (which is -the default), these headers will be removed before mailing when sending -messages via MH. Set it to @code{nil} if your MH can handle these -headers. - -@item message-qmail-inject-program -@vindex message-qmail-inject-program -@cindex qmail -Location of the qmail-inject program. - -@item message-qmail-inject-args -@vindex message-qmail-inject-args -Arguments passed to qmail-inject programs. -This should be a list of strings, one string for each argument. It -may also be a function. - -For e.g., if you wish to set the envelope sender address so that bounces -go to the right place or to deal with listserv's usage of that address, you -might set this variable to @code{'("-f" "you@@some.where")}. - -@item message-sendmail-f-is-evil -@vindex message-sendmail-f-is-evil -@cindex sendmail -Non-@code{nil} means don't add @samp{-f username} to the sendmail -command line. Doing so would be even more evil than leaving it out. - -@item message-sendmail-envelope-from -@vindex message-sendmail-envelope-from -When @code{message-sendmail-f-is-evil} is @code{nil}, this specifies -the address to use in the @acronym{SMTP} envelope. If it is -@code{nil}, use @code{user-mail-address}. If it is the symbol -@code{header}, use the @samp{From} header of the message. - -@item message-mailer-swallows-blank-line -@vindex message-mailer-swallows-blank-line -Set this to non-@code{nil} if the system's mailer runs the header and -body together. (This problem exists on SunOS 4 when sendmail is run -in remote mode.) The value should be an expression to test whether -the problem will actually occur. - -@item message-send-mail-partially-limit -@vindex message-send-mail-partially-limit -@cindex split large message -The limitation of messages sent as message/partial. The lower bound -of message size in characters, beyond which the message should be sent -in several parts. If it is @code{nil} (which is the default), the -size is unlimited. - -@end table - - -@node News Headers -@section News Headers - -@vindex message-required-news-headers -@code{message-required-news-headers} a list of header symbols. These -headers will either be automatically generated, or, if that's -impossible, they will be prompted for. The following symbols are valid: - -@table @code - -@item From -@cindex From -@findex user-full-name -@findex user-mail-address -This required header will be filled out with the result of the -@code{message-make-from} function, which depends on the -@code{message-from-style}, @code{user-full-name}, -@code{user-mail-address} variables. - -@item Subject -@cindex Subject -This required header will be prompted for if not present already. - -@item Newsgroups -@cindex Newsgroups -This required header says which newsgroups the article is to be posted -to. If it isn't present already, it will be prompted for. - -@item Organization -@cindex organization -@vindex message-user-organization -@vindex message-user-organization-file -This optional header will be filled out depending on the -@code{message-user-organization} variable. -@code{message-user-organization-file} will be used if this variable is -@code{t}. This variable can also be a string (in which case this string -will be used), or it can be a function (which will be called with no -parameters and should return a string to be used). - -@item Lines -@cindex Lines -This optional header will be computed by Message. - -@item Message-ID -@cindex Message-ID -@vindex message-user-fqdn -@vindex mail-host-address -@vindex user-mail-address -@findex system-name -@cindex Sun -@cindex i-did-not-set--mail-host-address--so-tickle-me -This required header will be generated by Message. A unique ID will be -created based on the date, time, user name (for the local part) and the -domain part. For the domain part, message will look (in this order) at -@code{message-user-fqdn}, @code{system-name}, @code{mail-host-address} -and @code{message-user-mail-address} (i.e. @code{user-mail-address}) -until a probably valid fully qualified domain name (FQDN) was found. - -@item User-Agent -@cindex User-Agent -This optional header will be filled out according to the -@code{message-newsreader} local variable. - -@item In-Reply-To -This optional header is filled out using the @code{Date} and @code{From} -header of the article being replied to. - -@item Expires -@cindex Expires -@vindex message-expires -This extremely optional header will be inserted according to the -@code{message-expires} variable. It is highly deprecated and shouldn't -be used unless you know what you're doing. - -@item Distribution -@cindex Distribution -@vindex message-distribution-function -This optional header is filled out according to the -@code{message-distribution-function} variable. It is a deprecated and -much misunderstood header. - -@item Path -@cindex path -@vindex message-user-path -This extremely optional header should probably never be used. -However, some @emph{very} old servers require that this header is -present. @code{message-user-path} further controls how this -@code{Path} header is to look. If it is @code{nil}, use the server name -as the leaf node. If it is a string, use the string. If it is neither -a string nor @code{nil}, use the user name only. However, it is highly -unlikely that you should need to fiddle with this variable at all. -@end table - -@findex yow -@cindex Mime-Version -In addition, you can enter conses into this list. The @sc{car} of this cons -should be a symbol. This symbol's name is the name of the header, and -the @sc{cdr} can either be a string to be entered verbatim as the value of -this header, or it can be a function to be called. This function should -return a string to be inserted. For instance, if you want to insert -@code{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")} -into the list. If you want to insert a funny quote, you could enter -something like @code{(X-Yow . yow)} into the list. The function -@code{yow} will then be called without any arguments. - -If the list contains a cons where the @sc{car} of the cons is -@code{optional}, the @sc{cdr} of this cons will only be inserted if it is -non-@code{nil}. - -If you want to delete an entry from this list, the following Lisp -snippet might be useful. Adjust accordingly if you want to remove -another element. - -@lisp -(setq message-required-news-headers - (delq 'Message-ID message-required-news-headers)) -@end lisp - -Other variables for customizing outgoing news articles: - -@table @code - -@item message-syntax-checks -@vindex message-syntax-checks -Controls what syntax checks should not be performed on outgoing posts. -To disable checking of long signatures, for instance, add - -@lisp -(signature . disabled) -@end lisp - -to this list. - -Valid checks are: - -@table @code -@item approved -@cindex approved -Check whether the article has an @code{Approved} header, which is -something only moderators should include. -@item continuation-headers -Check whether there are continuation header lines that don't begin with -whitespace. -@item control-chars -Check for invalid characters. -@item empty -Check whether the article is empty. -@item existing-newsgroups -Check whether the newsgroups mentioned in the @code{Newsgroups} and -@code{Followup-To} headers exist. -@item from -Check whether the @code{From} header seems nice. -@item illegible-text -Check whether there is any non-printable character in the body. -@item invisible-text -Check whether there is any invisible text in the buffer. -@item long-header-lines -Check for too long header lines. -@item long-lines -@cindex long lines -Check for too long lines in the body. -@item message-id -Check whether the @code{Message-ID} looks syntactically ok. -@item multiple-headers -Check for the existence of multiple equal headers. -@item new-text -Check whether there is any new text in the messages. -@item newsgroups -Check whether the @code{Newsgroups} header exists and is not empty. -@item quoting-style -Check whether text follows last quoted portion. -@item repeated-newsgroups -Check whether the @code{Newsgroups} and @code{Followup-to} headers -contains repeated group names. -@item reply-to -Check whether the @code{Reply-To} header looks ok. -@item sender -@cindex Sender -Insert a new @code{Sender} header if the @code{From} header looks odd. -@item sendsys -@cindex sendsys -Check for the existence of version and sendsys commands. -@item shoot -Check whether the domain part of the @code{Message-ID} header looks ok. -@item shorten-followup-to -Check whether to add a @code{Followup-to} header to shorten the number -of groups to post to. -@item signature -Check the length of the signature. -@item size -Check for excessive size. -@item subject -Check whether the @code{Subject} header exists and is not empty. -@item subject-cmsg -Check the subject for commands. -@item valid-newsgroups -Check whether the @code{Newsgroups} and @code{Followup-to} headers -are valid syntactically. -@end table - -All these conditions are checked by default, except for @code{sender} -for which the check is disabled by default if -@code{message-insert-canlock} is non-@code{nil} (@pxref{Canceling News}). - -@item message-ignored-news-headers -@vindex message-ignored-news-headers -Regexp of headers to be removed before posting. The default is@* -@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:\\|@* -^X-Draft-From:\\|^X-Gnus-Agent-Meta-Information:}. - -@item message-default-news-headers -@vindex message-default-news-headers -This string is inserted at the end of the headers in all message -buffers that are initialized as news. - -@end table - - -@node News Variables -@section News Variables - -@table @code -@item message-send-news-function -@vindex message-send-news-function -Function used to send the current buffer as news. The default is -@code{message-send-news}. - -@item message-post-method -@vindex message-post-method -Gnusish @dfn{select method} (see the Gnus manual for details) used for -posting a prepared news message. - -@end table - - -@node Insertion Variables -@section Insertion Variables - -@table @code -@item message-cite-style -@vindex message-cite-style -The overall style to be used when replying to messages. This controls -things like where the reply should be put relative to the original, -how the citation is formatted, where the signature goes, etc. - -Value is either @code{nil} (no variable overrides) or a let-style list -of pairs @code{(VARIABLE VALUE)} to override default values. - -See @code{gnus-posting-styles} to set this variable for specific -groups. Presets to impersonate popular mail agents are available in the -@code{message-cite-style-*} variables. - -@item message-cite-reply-position -@vindex message-cite-reply-position -Where the reply should be positioned. Available styles are -@code{traditional} to reply inline, @code{above} for top-posting, and -@code{below} for bottom-posting - -@item message-ignored-cited-headers -@vindex message-ignored-cited-headers -All headers that match this regexp will be removed from yanked -messages. The default is @samp{.}, which means that all headers will be -removed. - -@item message-cite-prefix-regexp -@vindex message-cite-prefix-regexp -Regexp matching the longest possible citation prefix on a line. - -@item message-citation-line-function -@vindex message-citation-line-function -@cindex attribution line -Function called to insert the citation line. The default is -@code{message-insert-citation-line}, which will lead to citation lines -that look like: - -@example -Hallvard B Furuseth writes: -@end example - -@c FIXME: Add `message-insert-formatted-citation-line' and -@c `message-citation-line-format' - -Point will be at the beginning of the body of the message when this -function is called. - -Note that Gnus provides a feature where clicking on `writes:' hides the -cited text. If you change the citation line too much, readers of your -messages will have to adjust their Gnus, too. See the variable -@code{gnus-cite-attribution-suffix}. @xref{Article Highlighting, , -Article Highlighting, gnus, The Gnus Manual}, for details. - -@item message-yank-prefix -@vindex message-yank-prefix -@cindex yanking -@cindex quoting -When you are replying to or following up an article, you normally want -to quote the person you are answering. Inserting quoted text is done by -@dfn{yanking}, and each line you yank will have -@code{message-yank-prefix} prepended to it (except for quoted lines -which use @code{message-yank-cited-prefix} and empty lines which use -@code{message-yank-empty-prefix}). The default is @samp{> }. - -@item message-yank-cited-prefix -@vindex message-yank-cited-prefix -@cindex yanking -@cindex cited -@cindex quoting -When yanking text from an article which contains already cited text, -each line will be prefixed with the contents of this variable. The -default is @samp{>}. See also @code{message-yank-prefix}. - -@item message-yank-empty-prefix -@vindex message-yank-empty-prefix -@cindex yanking -@cindex quoting -When yanking text from an article, each empty line will be prefixed with -the contents of this variable. The default is @samp{>}. You can set -this variable to an empty string to split the cited text into paragraphs -automatically. See also @code{message-yank-prefix}. - -@item message-indentation-spaces -@vindex message-indentation-spaces -Number of spaces to indent yanked messages. - -@item message-cite-function -@vindex message-cite-function -@findex message-cite-original -@findex message-cite-original-without-signature -Function for citing an original message. The default is -@code{message-cite-original}, which simply inserts the original message -and prepends @samp{> } to each line. -@code{message-cite-original-without-signature} does the same, but elides -the signature. - -@item message-indent-citation-function -@vindex message-indent-citation-function -Function for modifying a citation just inserted in the mail buffer. -This can also be a list of functions. Each function can find the -citation between @code{(point)} and @code{(mark t)}. And each function -should leave point and mark around the citation text as modified. - -@item message-mark-insert-begin -@vindex message-mark-insert-begin -String to mark the beginning of some inserted text. - -@item message-mark-insert-end -@vindex message-mark-insert-end -String to mark the end of some inserted text. - -@item message-signature -@vindex message-signature -String to be inserted at the end of the message buffer. If @code{t} -(which is the default), the @code{message-signature-file} file will be -inserted instead. If a function, the result from the function will be -used instead. If a form, the result from the form will be used instead. -If this variable is @code{nil}, no signature will be inserted at all. - -@item message-signature-file -@vindex message-signature-file -File containing the signature to be inserted at the end of the buffer. -If a path is specified, the value of -@code{message-signature-directory} is ignored, even if set. -The default is @file{~/.signature}. - -@item message-signature-directory -@vindex message-signature-directory -Name of directory containing signature files. Comes in handy if you -have many such files, handled via Gnus posting styles for instance. -If @code{nil} (the default), @code{message-signature-file} is expected -to specify the directory if needed. - - -@item message-signature-insert-empty-line -@vindex message-signature-insert-empty-line -If @code{t} (the default value) an empty line is inserted before the -signature separator. - -@end table - -Note that RFC1036bis says that a signature should be preceded by the three -characters @samp{-- } on a line by themselves. This is to make it -easier for the recipient to automatically recognize and process the -signature. So don't remove those characters, even though you might feel -that they ruin your beautiful design, like, totally. - -Also note that no signature should be more than four lines long. -Including @acronym{ASCII} graphics is an efficient way to get -everybody to believe that you are silly and have nothing important to -say. - - -@node Various Message Variables -@section Various Message Variables - -@table @code -@item message-default-charset -@vindex message-default-charset -@cindex charset -Symbol naming a @acronym{MIME} charset. Non-@acronym{ASCII} characters -in messages are assumed to be encoded using this charset. The default -is @code{iso-8859-1} on non-@sc{mule} Emacsen; otherwise @code{nil}, -which means ask the user. (This variable is used only on non-@sc{mule} -Emacsen.) @xref{Charset Translation, , Charset Translation, emacs-mime, -Emacs MIME Manual}, for details on the @sc{mule}-to-@acronym{MIME} -translation process. - -@item message-fill-column -@vindex message-fill-column -@cindex auto-fill -Local value for the column beyond which automatic line-wrapping should -happen for message buffers. If non-nil (the default), also turn on -auto-fill in message buffers. - -@item message-signature-separator -@vindex message-signature-separator -Regexp matching the signature separator. It is @samp{^-- *$} by -default. - -@item mail-header-separator -@vindex mail-header-separator -String used to separate the headers from the body. It is @samp{--text -follows this line--} by default. - -@item message-directory -@vindex message-directory -Directory used by many mailish things. The default is @file{~/Mail/}. -All other mail file variables are derived from @code{message-directory}. - -@item message-auto-save-directory -@vindex message-auto-save-directory -Directory where Message auto-saves buffers if Gnus isn't running. If -@code{nil}, Message won't auto-save. The default is @file{~/Mail/drafts/}. - -@item message-signature-setup-hook -@vindex message-signature-setup-hook -Hook run when initializing the message buffer. It is run after the -headers have been inserted but before the signature has been inserted. - -@item message-setup-hook -@vindex message-setup-hook -Hook run as the last thing when the message buffer has been initialized, -but before yanked text is inserted. - -@item message-header-setup-hook -@vindex message-header-setup-hook -Hook called narrowed to the headers after initializing the headers. - -For instance, if you're running Gnus and wish to insert a -@samp{Mail-Copies-To} header in all your news articles and all messages -you send to mailing lists, you could do something like the following: - -@lisp -(defun my-message-header-setup-hook () - (let ((group (or gnus-newsgroup-name ""))) - (when (or (message-fetch-field "newsgroups") - (gnus-group-find-parameter group 'to-address) - (gnus-group-find-parameter group 'to-list)) - (insert "Mail-Copies-To: never\n")))) - -(add-hook 'message-header-setup-hook - 'my-message-header-setup-hook) -@end lisp - -@item message-send-hook -@vindex message-send-hook -Hook run before sending messages. - -If you want to add certain headers before sending, you can use the -@code{message-add-header} function in this hook. For instance: -@findex message-add-header - -@lisp -(add-hook 'message-send-hook 'my-message-add-content) -(defun my-message-add-content () - (message-add-header "X-In-No-Sense: Nonsense") - (message-add-header "X-Whatever: no")) -@end lisp - -This function won't add the header if the header is already present. - -@item message-send-mail-hook -@vindex message-send-mail-hook -Hook run before sending mail messages. This hook is run very late -- -just before the message is actually sent as mail. - -@item message-send-news-hook -@vindex message-send-news-hook -Hook run before sending news messages. This hook is run very late -- -just before the message is actually sent as news. - -@item message-sent-hook -@vindex message-sent-hook -Hook run after sending messages. - -@item message-cancel-hook -@vindex message-cancel-hook -Hook run when canceling news articles. - -@item message-mode-syntax-table -@vindex message-mode-syntax-table -Syntax table used in message mode buffers. - -@item message-cite-articles-with-x-no-archive -@vindex message-cite-articles-with-x-no-archive -If non-@code{nil}, don't strip quoted text from articles that have -@samp{X-No-Archive} set. Even if this variable isn't set, you can -undo the stripping by hitting the @code{undo} keystroke. - -@item message-strip-special-text-properties -@vindex message-strip-special-text-properties -Emacs has a number of special text properties which can break message -composing in various ways. If this option is set, message will strip -these properties from the message composition buffer. However, some -packages requires these properties to be present in order to work. If -you use one of these packages, turn this option off, and hope the -message composition doesn't break too bad. - -@item message-send-method-alist -@vindex message-send-method-alist -@findex message-mail-p -@findex message-news-p -@findex message-send-via-mail -@findex message-send-via-news -Alist of ways to send outgoing messages. Each element has the form: - -@lisp -(@var{type} @var{predicate} @var{function}) -@end lisp - -@table @var -@item type -A symbol that names the method. - -@item predicate -A function called without any parameters to determine whether the -message is a message of type @var{type}. The function will be called in -the buffer where the message is. - -@item function -A function to be called if @var{predicate} returns non-@code{nil}. -@var{function} is called with one parameter---the prefix. -@end table - -The default is: - -@lisp -((news message-news-p message-send-via-news) - (mail message-mail-p message-send-via-mail)) -@end lisp - -The @code{message-news-p} function returns non-@code{nil} if the message -looks like news, and the @code{message-send-via-news} function sends the -message according to the @code{message-send-news-function} variable -(@pxref{News Variables}). The @code{message-mail-p} function returns -non-@code{nil} if the message looks like mail, and the -@code{message-send-via-mail} function sends the message according to the -@code{message-send-mail-function} variable (@pxref{Mail Variables}). - -All the elements in this alist will be tried in order, so a message -containing both a valid @samp{Newsgroups} header and a valid @samp{To} -header, for example, will be sent as news, and then as mail. -@end table - - - -@node Sending Variables -@section Sending Variables - -@table @code - -@item message-fcc-handler-function -@vindex message-fcc-handler-function -A function called to save outgoing articles. This function will be -called with the name of the file to store the article in. The default -function is @code{message-output} which saves in Unix mailbox format. - -@item message-courtesy-message -@vindex message-courtesy-message -When sending combined messages, this string is inserted at the start of -the mailed copy. If the string contains the format spec @samp{%s}, the -newsgroups the article has been posted to will be inserted there. If -this variable is @code{nil}, no such courtesy message will be added. -The default value is @samp{"The following message is a courtesy copy of -an article\\nthat has been posted to %s as well.\\n\\n"}. - -@item message-fcc-externalize-attachments -@vindex message-fcc-externalize-attachments -If @code{nil}, attach files as normal parts in Fcc copies; if it is -non-@code{nil}, attach local files as external parts. - -@item message-interactive -@vindex message-interactive -If non-@code{nil} wait for and display errors when sending a message; -if @code{nil} let the mailer mail back a message to report errors. - -@item message-confirm-send -@vindex message-confirm-send -When non-@code{nil}, Gnus will ask for confirmation when sending a -message. - -@end table - - -@node Message Buffers -@section Message Buffers - -Message will generate new buffers with unique buffer names when you -request a message buffer. When you send the message, the buffer isn't -normally killed off. Its name is changed and a certain number of old -message buffers are kept alive. - -@table @code -@item message-generate-new-buffers -@vindex message-generate-new-buffers -Controls whether to create a new message buffer to compose a message. -Valid values include: - -@table @code -@item nil -Generate the buffer name in the Message way (e.g., *mail*, *news*, *mail -to whom*, *news on group*, etc.) and continue editing in the existing -buffer of that name. If there is no such buffer, it will be newly -created. - -@item unique -@item t -Create the new buffer with the name generated in the Message way. - -@item unsent -Similar to @code{unique} but the buffer name begins with "*unsent ". - -@item standard -Similar to @code{nil} but the buffer name is simpler like *mail -message*. -@end table -@table @var -@item function -If this is a function, call that function with three parameters: The -type, the To address and the group name (any of these may be -@code{nil}). The function should return the new buffer name. -@end table - -The default value is @code{unsent}. - -@item message-max-buffers -@vindex message-max-buffers -This variable says how many old message buffers to keep. If there are -more message buffers than this, the oldest buffer will be killed. The -default is 10. If this variable is @code{nil}, no old message buffers -will ever be killed. - -@item message-send-rename-function -@vindex message-send-rename-function -After sending a message, the buffer is renamed from, for instance, -@samp{*reply to Lars*} to @samp{*sent reply to Lars*}. If you don't -like this, set this variable to a function that renames the buffer in a -manner you like. If you don't want to rename the buffer at all, you can -say: - -@lisp -(setq message-send-rename-function 'ignore) -@end lisp - -@item message-kill-buffer-on-exit -@findex message-kill-buffer-on-exit -If non-@code{nil}, kill the buffer immediately on exit. - -@end table - - -@node Message Actions -@section Message Actions - -When Message is being used from a news/mail reader, the reader is likely -to want to perform some task after the message has been sent. Perhaps -return to the previous window configuration or mark an article as -replied. - -@vindex message-kill-actions -@vindex message-postpone-actions -@vindex message-exit-actions -@vindex message-send-actions -The user may exit from the message buffer in various ways. The most -common is @kbd{C-c C-c}, which sends the message and exits. Other -possibilities are @kbd{C-c C-s} which just sends the message, @kbd{C-c -C-d} which postpones the message editing and buries the message buffer, -and @kbd{C-c C-k} which kills the message buffer. Each of these actions -have lists associated with them that contains actions to be executed: -@code{message-send-actions}, @code{message-exit-actions}, -@code{message-postpone-actions}, and @code{message-kill-actions}. - -Message provides a function to interface with these lists: -@code{message-add-action}. The first parameter is the action to be -added, and the rest of the arguments are which lists to add this action -to. Here's an example from Gnus: - -@lisp - (message-add-action - `(set-window-configuration ,(current-window-configuration)) - 'exit 'postpone 'kill) -@end lisp - -This restores the Gnus window configuration when the message buffer is -killed, postponed or exited. - -An @dfn{action} can be either: a normal function, or a list where the -@sc{car} is a function and the @sc{cdr} is the list of arguments, or -a form to be @code{eval}ed. - - -@node Compatibility -@chapter Compatibility -@cindex compatibility - -Message uses virtually only its own variables---older @code{mail-} -variables aren't consulted. To force Message to take those variables -into account, you can put the following in your @file{.emacs} file: - -@lisp -(require 'messcompat) -@end lisp - -This will initialize many Message variables from the values in the -corresponding mail variables. - - -@node Appendices -@chapter Appendices - -@menu -* Responses:: Standard rules for determining where responses go. -@end menu - - -@node Responses -@section Responses - -To determine where a message is to go, the following algorithm is used -by default. - -@table @dfn -@item reply -A @dfn{reply} is when you want to respond @emph{just} to the person who -sent the message via mail. There will only be one recipient. To -determine who the recipient will be, the following headers are -consulted, in turn: - -@table @code -@item Reply-To - -@item From -@end table - - -@item wide reply -A @dfn{wide reply} is a mail response that includes @emph{all} entities -mentioned in the message you are responding to. All mailboxes from the -following headers will be concatenated to form the outgoing -@code{To}/@code{Cc} headers: - -@table @code -@item From -(unless there's a @code{Reply-To}, in which case that is used instead). - -@item Cc - -@item To -@end table - -If a @code{Mail-Copies-To} header is present, it will also be included -in the list of mailboxes. If this header is @samp{never}, that means -that the @code{From} (or @code{Reply-To}) mailbox will be suppressed. - - -@item followup -A @dfn{followup} is a response sent via news. The following headers -(listed in order of precedence) determine where the response is to be -sent: - -@table @code - -@item Followup-To - -@item Newsgroups - -@end table - -If a @code{Mail-Copies-To} header is present, it will be used as the -basis of the new @code{Cc} header, except if this header is -@samp{never}. - -@end table - - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include doclicense.texi - -@node Index -@chapter Index -@printindex cp - -@node Key Index -@chapter Key Index -@printindex ky - -@bye - -@c End: diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi deleted file mode 100644 index 538c3f1ba82..00000000000 --- a/doc/misc/mh-e.texi +++ /dev/null @@ -1,9064 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c -@c Note: This document requires makeinfo version 4.6 or greater to build. -@c -@c %**start of header -@setfilename ../../info/mh-e -@settitle The MH-E Manual -@c %**end of header - -@c Version of the software and manual. -@set VERSION 8.3 -@c Edition of the manual. It is either empty for the first edition or -@c has the form ", nth Edition" (without the quotes). -@set EDITION -@set UPDATED 2011-09-20 -@set UPDATE-MONTH September, 2011 - -@c Other variables. -@set MH-BOOK-HOME http://rand-mh.sourceforge.net/book/mh -@set MH-E-HOME http://mh-e.sourceforge.net/ - -@c Copyright -@copying -This is version @value{VERSION}@value{EDITION} of @cite{The MH-E -Manual}, last updated @value{UPDATED}. - -Copyright @copyright{} 1995, 2001-2003, 2005-2012 Free Software Foundation, Inc. - -@c This dual license has been agreed upon by the FSF. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of either: - -@enumerate a -@item -the GNU Free Documentation License, Version 1.3 or any later version -published by the Free Software Foundation; with no Invariant Sections, -with the Front-Cover texts being ``A GNU Manual,'' and with the -Back-Cover Texts as in (a) below. A copy of the license is included in -the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -@item -the GNU General Public License as published by the Free Software -Foundation; either version 3, or (at your option) any later version. A -copy of the license is included in the section entitled ``GNU General -Public License.'' -@end enumerate - -@end quotation -@end copying - -@c Info Directory Entry -@dircategory Emacs network features -@direntry -* MH-E: (mh-e). Emacs interface to the MH mail system. -@end direntry - -@c Title Page -@titlepage -@title The MH-E Manual -@subtitle Version @value{VERSION}@value{EDITION} -@subtitle @value{UPDATE-MONTH} -@author Bill Wohler - -@c Copyright Page -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@ifnottex -@html - -@end html -@insertcopying -@end ifnottex - -@c Table of Contents -@contents - -@html - -@end html - -@node Preface, Conventions, Top, Top -@unnumbered Preface - -@cindex Emacs -@cindex Unix commands, Emacs -@cindex preface - -This manual introduces another interface to the MH mail system that is -accessible through the GNU Emacs editor, namely, @emph{MH-E}. MH-E is -easy to use. I don't assume that you know GNU Emacs or even MH at this -point, since I didn't know either of them when I discovered MH-E. -However, MH-E was the tip of the iceberg, and I discovered more and -more niceties about GNU Emacs and MH@. Now I'm fully hooked on both of -them. - -The MH-E package is distributed with Emacs@footnote{Version -@value{VERSION} of MH-E appeared in Emacs 24.1. It is supported in GNU -Emacs 23 and higher, as well as XEmacs 21.4.22 and 21.5.31. MH-E is -known not to work with GNU Emacs versions 20 and below, and XEmacs -version 21.5.9 - 21.5.16. It is compatible with MH versions 6.8.4 and -higher, all versions of nmh, and GNU mailutils 1.0 and higher}, so you -shouldn't have to do anything special to use it. Gnus is also -required; version 5.10 or higher is recommended. This manual covers -MH-E version @value{VERSION}. To help you decide which version you -have, see @ref{Getting Started}. - -@findex help-with-tutorial -@kindex C-h t - -If you don't already use GNU Emacs but want to learn more, you can -read an online tutorial by starting GNU Emacs and typing @kbd{C-h t} -(@code{help-with-tutorial}). (To learn about this notation, see -@ref{Conventions}.) If you want to take the plunge, consult the -@iftex -@cite{GNU Emacs Manual}, -@end iftex -@ifinfo -@ref{top, , GNU Emacs Manual, emacs, GNU Emacs Manual}, -@end ifinfo -@ifhtml -@uref{http://www.gnu.org/software/emacs/manual/html_node/, -@cite{GNU Emacs Manual}}, -@end ifhtml -from the Free Software Foundation. - -If more information is needed, you can go to the Unix manual pages of -the individual MH commands. When the name is not obvious, I'll guide -you to a relevant MH manual page that describes the action more fully. - -@cindex @cite{MH & nmh: Email for Users & Programmers} -@cindex MH book -@cindex info -@kindex C-h i - -This manual is available in both Info and online formats. The Info -version is distributed with Emacs and can be accessed with the -@command{info} command (@samp{info mh-e}) or within Emacs (@kbd{C-h i -m mh-e @key{RET}}). The online version is available at -@uref{http://mh-e.sourceforge.net/manual/, SourceForge}. Another great -online resource is the book @uref{http://www.ics.uci.edu/~mh/book/, -@cite{MH & nmh: Email for Users & Programmers}} (also known as -@dfn{the MH book}). - -I hope you enjoy this manual! If you have any comments, or suggestions -for this document, please let me know. - -@cindex Bill Wohler -@cindex Wohler, Bill - -@noindent -Bill Wohler <@i{wohler at newt.com}>@* -8 February 1995@* -24 February 2006 - -@node Conventions, Getting Started, Preface, Top -@chapter GNU Emacs Terms and Conventions - -@cindex Emacs -@cindex Emacs, conventions -@cindex Emacs, terms -@cindex Unix commands, Emacs -@cindex conventions, Emacs -@cindex terms, Emacs - -If you're an experienced Emacs user, you can skip the following -conventions and definition of terms and go directly to the next -section (@pxref{Getting Started}). - -@cindex Emacs commands -@cindex MH commands -@cindex Unix commands -@cindex commands -@cindex commands, MH -@cindex commands, Unix -@cindex commands, shell -@cindex functions -@cindex shell commands - -In general, @dfn{functions} in this text refer to Emacs Lisp functions -that one would call from within Emacs Lisp programs (for example, -@code{(mh-inc-folder)}). On the other hand, @dfn{commands} are those -things that are run by the user, such as @kbd{i} or @kbd{M-x -mh-inc-folder}. Programs outside of Emacs are specifically called MH -commands, shell commands, or Unix commands. - -@cindex conventions, key names -@cindex key names - -The conventions for key names are as follows: - -@table @kbd -@item C-x -Hold down the @key{CTRL} (Control) key and press the @kbd{x} key. -@c ------------------------- -@item M-x -Hold down the @key{META} or @key{ALT} key and press the @kbd{x} key. - -Since some keyboards don't have a @key{META} key, you can generate -@kbd{M-x}, for example, by pressing @key{ESC} (Escape), -@emph{releasing it}, and then pressing the @kbd{x} key. -@c ------------------------- -@item @key{RET} -Press the @key{RETURN} or @key{ENTER} key. This is normally used to -complete a command. -@c ------------------------- -@item @key{SPC} -Press the space bar. -@c ------------------------- -@item @key{TAB} -Press the @key{TAB} key. -@c ------------------------- -@item @key{DEL} -Press the @key{DELETE} key. -@c ------------------------- -@item @key{BS} -Press the @key{BACKSPACE} key@footnote{If you are using Version 20 or -earlier of Emacs, you will need to use the @key{DEL} key.}. -@end table - -@cindex Emacs, prefix argument -@cindex prefix argument -@kindex C-u - -A @dfn{prefix argument} allows you to pass an argument to any Emacs -function. To pass an argument, type @kbd{C-u} before the Emacs command -or keystroke. Numeric arguments can be passed as well. For example, to -insert five f's, use @kbd{C-u 5 f}. There is a default of four when -using @kbd{C-u}, and you can use multiple prefix arguments to provide -arguments of powers of four. To continue our example, you could insert -four f's with @kbd{C-u f}, 16 f's with @kbd{C-u C-u f}, 64 f's with -@kbd{C-u C-u C-u f}, and so on. Numeric and valueless negative -arguments can also be inserted with the @key{META} key. Examples -include @kbd{M-5} to specify an argument of 5, or @kbd{M--} which -specifies a negative argument with no particular value. - -@sp 1 -@center @strong{NOTE} - -@quotation -The prefix @kbd{C-u} or @kbd{M-} is not necessary in MH-E's MH-Folder -mode (@pxref{Reading Mail Tour}). In this mode, simply enter the -numerical argument before entering the command. -@end quotation -@sp 1 - -@cindex @file{.emacs} -@cindex Emacs, variables -@cindex files, @file{.emacs} -@cindex variables -@findex setq - -Emacs uses @dfn{variables} to hold values. These can be changed via -calls to the function @code{setq} in @file{~/.emacs}. - -@cindex Emacs, options -@cindex options -@findex customize-group -@findex customize-option - -Variables in MH-E that are normally modified by the user are called -@dfn{options} and are modified through the customize functions (such -as @kbd{M-x customize-option} or @kbd{M-x customize-group}). -@ifnothtml -@xref{Easy Customization,,,emacs,The GNU Emacs Manual}, in @cite{The -GNU Emacs Manual}. -@end ifnothtml -@ifhtml -See section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Easy-Customization.html, -Easy Customization} in @cite{The GNU Emacs Manual}. -@end ifhtml -@xref{Options}. - -@cindex Emacs, faces -@cindex faces -@cindex highlighting -@findex customize-face - -You can specify various styles for displaying text using @dfn{faces}. -MH-E provides a set of faces that you can use to personalize the look -of your MH-E buffers. Use the command @kbd{M-x customize-face} to do -this. -@ifnothtml -@xref{Face Customization,,,emacs,The GNU Emacs Manual}, in @cite{The -GNU Emacs Manual}. -@end ifnothtml -@ifhtml -See section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Face-Customization.html, -Face Customization} in @cite{The GNU Emacs Manual}. -@end ifhtml - -@cindex abnormal hooks -@cindex hooks -@cindex normal hooks -@findex add-hook -@findex customize-option - -Commands often offer @dfn{hooks} which enable you to extend or modify -the way a command works. -@ifnothtml -@ref{Hooks, , Hooks, emacs, The GNU Emacs Manual}, in @cite{The GNU -Emacs Manual} -@end ifnothtml -@ifhtml -See section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Hooks.html, -Hooks} in @cite{The GNU Emacs Manual} -@end ifhtml -for a description about @dfn{normal hooks} and @dfn{abnormal hooks}. -MH-E uses normal hooks in nearly all cases, so you can assume that we -are talking about normal hooks unless we explicitly mention that a -hook is abnormal. We also follow the conventions described in that -section: the name of the abnormal hooks end in @code{-hooks} and all -the rest of the MH-E hooks end in @code{-hook}. You can add hooks with -either @code{customize-option} or @code{add-hook}. - -@cindex Emacs, mark -@cindex Emacs, point -@cindex Emacs, region -@cindex mark -@cindex point -@cindex region -@kindex C-@@ -@kindex C-@key{SPC} - -There are several other terms that are used in Emacs that you should -know. The @dfn{point} is where the cursor currently is. You can save -your current place in the file by setting a @dfn{mark}. This operation -is useful in several ways. The mark can be later used when defining a -@dfn{region}, which is the text between the point and mark. Many -commands operate on regions, such as those for deleting text or -filling paragraphs. A mark can be set with @kbd{C-@@} (or -@kbd{C-@key{SPC}}). - -@cindex completion -@cindex Emacs, completion -@cindex Emacs, file completion -@cindex Emacs, folder completion -@cindex Emacs, minibuffer -@cindex file completion -@cindex folder completion -@cindex minibuffer -@kindex SPC -@kindex TAB - -The @dfn{minibuffer} is the bottom line of the Emacs window, where all -prompting and multiple-character input is directed. You can use -@dfn{completion} to enter values such as folders. Completion means -that Emacs fills in text for you when you type @key{SPC} or @key{TAB}. -A second @key{SPC} or @key{TAB} will list all possibilities at that -point. -@ifnothtml -@xref{Completion, , Completion, emacs, The GNU Emacs Manual}. -@end ifnothtml -@ifhtml -See the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Completion.html, -Completion} in @cite{The GNU Emacs Manual}. -@end ifhtml -Note that @key{SPC} cannot be used for completing filenames and -folders. - -@findex help-with-tutorial -@kindex C-h t -@kindex M-x - -The minibuffer is also where you enter Emacs function names after -typing @kbd{M-x}. For example, in the preface, I mentioned that you -could obtain help with @kbd{C-h t} (@code{help-with-tutorial}). What -this means is that you can get a tutorial by typing either @kbd{C-h t} -or @kbd{M-x help-with-tutorial}. In the latter case, you are prompted -for @samp{help-with-tutorial} in the minibuffer after typing -@kbd{M-x}. - -@cindex ~ - -The @samp{~} notation in filenames represents your home directory. -This notation is used by many shells including @command{bash}, -@code{tcsh}, and @command{csh}. It is analogous to the environment -variable @samp{$HOME}. For example, @file{~/.emacs} can be written -@file{$HOME/.emacs} or using the absolute path as in -@file{/home/wohler/.emacs} instead. - -@cindex Emacs, interrupting -@cindex Emacs, quitting -@cindex interrupting -@cindex quitting - -@i{In case of trouble:} Emacs can be interrupted at any time with -@kbd{C-g}. For example, if you've started a command that requests that -you enter something in the minibuffer, but then you change your mind, -type @kbd{C-g} and you'll be back where you started. If you want to -exit Emacs entirely, use @kbd{C-x C-c}. - -@node Getting Started, Tour Through MH-E, Conventions, Top -@chapter Getting Started - -@cindex MH-E, versions -@cindex history -@cindex versions of MH-E - -Because there are many old versions of MH-E out there, it is important -to know which version you have. I'll be talking about @w{Version 8} -which is pretty close to @w{Version 6} and @w{Version 7}. It differs -from @w{Version 4} and @w{Version 5} and is vastly different from -@w{Version 3}. @xref{History}. - -@findex mh-version - -To determine which version of MH-E that you have, enter @kbd{M-x -mh-version @key{RET}}. Hopefully it says that you're running -@w{Version @value{VERSION}} which is the latest version as of this -printing. - -If your version is much older than this, please consider upgrading. -You can have your system administrator upgrade the system-wide -version, or you can install your own personal version. It's really -quite easy. @xref{Getting MH-E}, for instructions for getting and -installing MH-E. - -If the @code{mh-version} command displays @samp{No MH variant -detected}@footnote{In very old versions of MH-E, you may get the error -message, @samp{Cannot find the commands `inc' and `mhl' and the file -`components'} if MH-E can't find MH. In this case, you need to update -MH-E, and you may need to install MH too. However, newer versions of -MH-E are better at finding MH if it is on your system.}, then you need -to install MH or tell MH-E where to find MH. - -@cindex Debian -@cindex nmh -@cindex GNU mailutils MH - -If you don't have MH on your system already, you must install a -variant of MH. The Debian mh-e package does this for you automatically -(@pxref{Getting MH-E}). Most people use -@uref{http://www.nongnu.org/nmh/, nmh}, but you may be interested in -trying out @uref{http://www.gnu.org/software/mailutils/, GNU mailutils -MH}, which supports IMAP. Your GNU/Linux distribution probably has -packages for both of these. - -@cindex @command{install-mh} -@cindex MH commands, @command{install-mh} -@cindex MH book - -If you've never run MH before, you need to run @command{install-mh} -from the shell before you continue. This sets up your personal MH -environment@footnote{See the section -@uref{@value{MH-BOOK-HOME}/../overall/setup.html, Setting Up MH} in the -MH book.}. If you don't, you'll be greeted with the error message: -@samp{Install MH and run install-mh before running MH-E}. This is all -you need to know about MH to use MH-E, but the more you know about MH, -the more you can leverage its power. See the -@uref{@value{MH-BOOK-HOME}/../, MH book} to learn more about MH. - -@cindex @samp{Path:} MH profile component -@cindex MH profile -@cindex MH profile component -@cindex MH profile component, @samp{Path:} - -Your MH environment includes your @dfn{MH profile} which is found in -the file @file{~/.mh_profile}, or the file named in the environment -variable @samp{$MH}. This file contains a number of @dfn{MH -profile components}. For example, the @samp{Path:} MH profile -component contains the path to your mail directory, which is -@file{~/Mail} by default. - -@cindex @command{mhparam} -@cindex MH commands, @command{mhparam} -@vindex exec-path -@vindex mh-path -@vindex mh-sys-path -@vindex mh-variant -@vindex mh-variant-in-use - -There are several options MH-E uses to interact with your MH -installation. The option @code{mh-variant} specifies the variant used -by MH-E (@pxref{Options}). The default setting of this option is -@samp{Auto-detect} which means that MH-E will automatically choose the -first of nmh, MH, or GNU mailutils MH that it finds in the directories -listed in @code{mh-path} (which you can customize), -@code{mh-sys-path}, and @code{exec-path}. If MH-E can't find MH at -all, you may have to customize @code{mh-path} and add the directory in -which the command @command{mhparam} is located. If, on the other hand, -you have both nmh and GNU mailutils MH installed (for example) and -@code{mh-variant-in-use} was initialized to nmh but you want to use -GNU mailutils MH, then you can set @code{mh-variant} to -@samp{gnu-mh}. - -@vindex mh-flists-present-flag -@vindex mh-lib -@vindex mh-lib-progs -@vindex mh-progs - -When @code{mh-variant} is changed, MH-E resets @code{mh-progs}, -@code{mh-lib}, @code{mh-lib-progs}, @code{mh-flists-present-flag}, and -@code{mh-variant-in-use} accordingly. - -@cindex @file{.emacs} -@cindex files, @file{.emacs} - -@sp 1 -@center @strong{NOTE} - -@quotation -Prior to version 8, it was often necessary to set some of these -variables in @file{~/.emacs}; now it is no longer necessary and can -actually cause problems. -@end quotation -@sp 1 - -@cindex MH profile component, @samp{Draft-Folder:} -@cindex MH profile component, @samp{Path:} -@cindex MH profile component, @samp{Previous-Sequence:} -@cindex MH profile component, @samp{Unseen-Sequence:} -@cindex @samp{Draft-Folder:} MH profile component -@cindex @samp{Path:} MH profile component -@cindex @samp{Previous-Sequence:} MH profile component -@cindex @samp{Unseen-Sequence:} MH profile component -@findex mh-find-path -@vindex mh-draft-folder -@vindex mh-find-path-hook -@vindex mh-inbox -@vindex mh-previous-seq -@vindex mh-unseen-seq -@vindex mh-user-path - -In addition to setting variables that point to MH itself, MH-E also -sets a handful of variables that point to where you keep your mail. -During initialization, the function @code{mh-find-path} sets -@code{mh-user-path} from your @samp{Path:} MH profile component (but -defaults to @samp{Mail} if one isn't present), @code{mh-draft-folder} -from @samp{Draft-Folder:}, @code{mh-unseen-seq} from -@samp{Unseen-Sequence:}, @code{mh-previous-seq} from -@samp{Previous-Sequence:}, and @code{mh-inbox} from @samp{Inbox:} -(defaults to @samp{+inbox}). The hook @code{mh-find-path-hook} is run -after these variables have been set. This hook can be used the change -the value of these variables if you need to run with different values -between MH and MH-E. - -@node Tour Through MH-E, Using This Manual, Getting Started, Top -@chapter Tour Through MH-E - -@cindex introduction -@cindex tour -@cindex tutorial - -This chapter introduces some of the terms you'll need to know and then -takes you on a tour of MH-E@footnote{The keys mentioned in these -chapters refer to the default key bindings. If you've changed the -bindings, refer to the command summaries at the beginning of each -chapter for a mapping between default key bindings and function -names.}. When you're done, you'll be able to send, read, and file -mail, which is all that a lot of people ever do. But if you're the -curious or adventurous type, read the rest of the manual to be able to -use all the features of MH-E. I suggest you read this chapter first to -get the big picture, and then you can read the manual as you wish. - -@menu -* Sending Mail Tour:: -* Reading Mail Tour:: -* Processing Mail Tour:: -* Leaving MH-E:: -* More About MH-E:: -@end menu - -@node Sending Mail Tour, Reading Mail Tour, Tour Through MH-E, Tour Through MH-E -@section Sending Mail - -@cindex MH-Letter mode -@cindex mode -@cindex modes, MH-Letter -@cindex sending mail -@findex mh-smail -@kindex M-x mh-smail - -Let's start our tour by sending ourselves a message which we can later -read and process. Enter @kbd{M-x mh-smail} to invoke the MH-E program -to send messages. Your message appears in an Emacs buffer whose -mode@footnote{A @dfn{mode} changes Emacs to make it easier to edit a -particular type of text.} is MH-Letter. - -Enter your login name in the @samp{To:} header field. Press the -@key{TAB} twice to move the cursor past the @samp{Cc:} field, since no -carbon copies are to be sent, and on to the @samp{Subject:} field. -Enter @kbd{Test} or anything else that comes to mind. - -Press @key{TAB} again to move the cursor to the body of the message. -Enter some text, using normal Emacs commands. You should now have -something like this@footnote{If you're running Emacs under the X -Window System, then you would also see a menu bar and a tool bar. I've -left out the menu bar and tool bar in all of the example screens.}: - -@cartouche -@smallexample - - - - - - ---:-- *scratch* All L1 (Lisp Interaction)------------------------- -To: wohler -cc: -Subject: Test -X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 --------- -This is a test message to get the wheels churning...# - - ---:** @{draft@} All L5 (MH-Letter)---------------------------------- -Type C-c C-c to send message, C-C ? for help -@end smallexample -@end cartouche -@i{MH-E message composition window} - -Note the line of dashes that separates the header and the body of the -message. It is essential that these dashes (or a blank line) are -present or the body of your message will be considered to be part of -the header. - -@cindex help -@findex describe-mode -@kindex C-c ? -@kindex C-c C-c -@kindex C-h m - -There are several commands specific to MH-Letter mode@footnote{You can -get quick help for the commands used most often with @kbd{C-c ?} or -more complete help with the @kbd{C-h m} (@code{describe-mode}) -command.}, but at this time we'll only use @kbd{C-c C-c} to send your -message. Type @kbd{C-c C-c} now. That's all there is to it! - -@node Reading Mail Tour, Processing Mail Tour, Sending Mail Tour, Tour Through MH-E -@section Receiving Mail - -@cindex @command{inc} -@cindex @command{scan} -@cindex MH commands, @command{inc} -@cindex MH commands, @command{scan} -@cindex MH-Folder mode -@cindex modes, MH-Folder -@cindex reading mail -@findex mh-rmail -@kindex M-x mh-rmail - -To read the mail you've just sent yourself, enter @kbd{M-x mh-rmail}. -This incorporates the new mail and puts the output from -@command{inc}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next -prev} in the MH book.} (called @dfn{scan lines} after the MH program -@command{scan}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/faswsprs.html, Find and Specify with scan -pick Ranges Sequences} in the MH book.} which prints a one-line -summary of each message) into a buffer called @samp{+inbox} whose -major mode is MH-Folder. - -@findex mh-rmail -@kindex F r -@kindex M-x mh-rmail - -@sp 1 -@center @strong{NOTE} - -@quotation - -The @kbd{M-x mh-rmail} command will show you only new mail, not mail -you have already read. If you were to run this tour again, you would -use @kbd{F r} to pull all your messages into MH-E. -@end quotation -@sp 1 - -@kindex @key{RET} -@kindex n -@kindex p - -You should see the scan line for your message, and perhaps others. Use -@kbd{n} or @kbd{p} to move the cursor to your test message and type -@key{RET} to read your message. You should see something like: - -@cartouche -@smallexample - 3 t08/24 root received fax files on Wed Aug 24 11:00:13 PDT 1 -# 4+t08/24 To:wohler Test< - -This is a test message to get the wheels churning... - - - ---:-- @{show-+inbox@} 4 All L1 (MH-Show)---------------------------- - -@end smallexample -@end cartouche -@i{After incorporating new messages} - -@kindex @key{DEL} -@kindex @key{SPC} - -If you typed a long message, you can view subsequent pages with -@key{SPC} and previous pages with @key{DEL}. - -@node Processing Mail Tour, Leaving MH-E, Reading Mail Tour, Tour Through MH-E -@section Processing Mail - -@cindex processing mail -@kindex @key{RET} -@kindex r - -The first thing we want to do is reply to the message that we sent -ourselves. Ensure that the cursor is still on the same line as your -test message and type @kbd{r}. You are prompted in the minibuffer with -@samp{Reply to whom:}. Here MH-E is asking whether you'd like to reply -to the original sender only, to the sender and primary recipients, or -to the sender and all recipients. You can press @key{TAB} to see these -choices. If you simply press @key{RET}, you'll reply only to the -sender. Press @key{RET} now. - -You'll find yourself in an Emacs buffer similar to that when you were -sending the original message, like this: - -@cartouche -@smallexample -To: -cc: -Subject: Re: Test -In-reply-to: <31054.1142621351@@stop.mail-abuse.org> -References: <31054.1142621351@@stop.mail-abuse.org> -Comments: In-reply-to Bill Wohler - message dated "Fri, 17 Mar 2006 10:49:11 -0800." -X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 --------- -# - ---:-- @{draft@} All L10 (MH-Letter)---------------------------------- -To: wohler -Subject: Test -X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 -Date: Fri, 17 Mar 2006 10:49:11 -0800 -From: Bill Wohler - -This is a test message to get the wheels churning... - ---:-- @{show-+inbox@} 4 All L1 (MH-Show)---------------------------- -Type C-c C-c to send message, C-c ? for help -@end smallexample -@end cartouche -@i{Composition window during reply} - -@findex backward-char -@findex forward-char -@findex next-line -@findex previous-line -@kindex C-b -@kindex C-c C-c -@kindex C-c C-f C-t -@kindex C-f -@kindex C-n -@kindex C-p -@kindex @key{BS} - -By default, MH will not add you to the address list of your replies, -so if you find that the @samp{To:} header field is missing, don't -worry. In this case, type @kbd{C-c C-f C-t} to create and go to the -@samp{To:} field, where you can type your login name again. You can -move around with the arrow keys or with @kbd{C-p} -(@code{previous-line}), @kbd{C-n} (@code{next-line}), @kbd{C-b} -(@code{backward-char}), and @kbd{C-f} (@code{forward-char}) and can -delete the previous character with @key{BS}. When you're finished -editing your message, send it with @kbd{C-c C-c} as before. - -@cindex @command{refile} -@cindex MH commands, @command{refile} -@cindex folders -@kindex @key{SPC} -@kindex o - -You'll often want to save messages that were sent to you in an -organized fashion. This is done with @dfn{folders}. You can use -folders to keep messages from your friends, or messages related to a -particular topic. With your cursor in the MH-Folder buffer and -positioned on the message you sent to yourself, type @kbd{o} to output -(@command{refile} in MH parlance) that message to a folder. Enter -@kbd{test} at the @samp{Destination folder:} prompt and type @kbd{y} -(or @key{SPC}) when MH-E asks to create the folder @samp{+test}. Note -that a @samp{^} (caret) appears next to the message number, which -means that the message has been marked for refiling but has not yet -been refiled. We'll talk about how the refile is actually carried out -in a moment. - -@cindex MH-Folder mode -@cindex modes, MH-Folder -@kindex d -@kindex i -@kindex @key{RET} -@kindex n -@kindex p -@kindex x - -Your previous reply is now waiting in the system mailbox. You -incorporate this mail into your MH-Folder buffer named @samp{+inbox} -with the @kbd{i} command. Do this now. After the mail is incorporated, -use @kbd{n} or @kbd{p} to move the cursor to the new message, and read -it with @key{RET}. Let's delete this message by typing @kbd{d}. Note -that a @samp{D} appears next to the message number. This means that -the message is marked for deletion but is not yet deleted. To perform -the deletion (and the refile we did previously), use the @kbd{x} -command. - -@findex mh-smail -@kindex m -@kindex M-x mh-smail - -If you want to send another message you can use @kbd{m} instead of -@kbd{M-x mh-smail}. So go ahead, send some mail to your friends! - -@cindex help -@cindex prefix characters -@findex describe-mode -@kindex ? -@kindex C-h m -@kindex F ? - -You can get a quick reminder about these commands by typing @kbd{?}. -This lists several @dfn{prefix characters}. To list the commands -available via the prefix characters, type the prefix character -followed by a @kbd{?}, for example, @kbd{F ?}. More complete help is -available with the @kbd{C-h m} (@code{describe-mode}) command. - -@node Leaving MH-E, More About MH-E, Processing Mail Tour, Tour Through MH-E -@section Leaving MH-E - -@cindex Emacs, quitting -@cindex quitting -@kindex C-x C-c -@kindex x - -You may now wish to exit @command{emacs} entirely. Use @kbd{C-x C-c} -to exit @command{emacs}. If you exited without running @kbd{x} in the -@samp{+inbox} buffer, Emacs will offer to save it for you. Type -@kbd{y} or @key{SPC} to save @samp{+inbox} changes, which means to -perform any refiles and deletes that you did there. - -@findex mh-rmail -@kindex C-x b -@kindex C-x k -@kindex M-x mh-rmail -@kindex q - -If you don't want to leave Emacs, you can type @kbd{q} to bury (hide) -the MH-E folder or delete it entirely with @kbd{C-x k}. You can then -later recall it with @kbd{C-x b} or @kbd{M-x mh-rmail}. - -@cindex @command{packf} -@cindex MH commands, @command{packf} -@cindex exporting folders -@cindex folders, exporting -@cindex mbox-style folder - -On the other hand, if you no longer want to use MH and MH-E, you can -take your mail with you. You can copy all of your mail into a single -file, mbox-style, by using the MH command @command{packf}. For -example, to create a file called @file{msgbox} with the messages in -your @samp{+inbox} folder, use @samp{packf +inbox}. The -@command{packf} command will append the messages to the file if it -already exists, so you can use @samp{folders -recurse -fast} in a -script to copy all of your messages into a single file, or using the -@samp{-file} argument, a file for each folder. - -@node More About MH-E, , Leaving MH-E, Tour Through MH-E -@section More About MH-E - -These are the basic commands to get you going, but there are plenty -more. If you think that MH-E is for you, read the rest of the manual -to find out how you can: - -@itemize @bullet -@item -Print your messages (@pxref{Printing}). -@c ------------------------- -@item -Edit messages and include your signature (@pxref{Editing Drafts}). -@c ------------------------- -@item -Forward messages (@pxref{Forwarding}). -@c ------------------------- -@item -Read digests (@pxref{Digests}). -@c ------------------------- -@item -Edit bounced messages (@pxref{Editing Again}). -@c ------------------------- -@item -Send multimedia messages (@pxref{Adding Attachments}). -@c ------------------------- -@item -Read HTML messages (@pxref{HTML}). -@c ------------------------- -@item -Use aliases and identities (see @ref{Aliases}, @pxref{Identities}). -@c ------------------------- -@item -Create different views of your mail (see @ref{Threading}, @pxref{Limits}). -@c ------------------------- -@item -Deal with junk mail (@pxref{Junk}). -@c ------------------------- -@item -Handle signed and encrypted messages (see @ref{Reading PGP}, -@pxref{Sending PGP}). -@c ------------------------- -@item -Process mail that was sent with @command{shar} or @command{uuencode} -(@pxref{Files and Pipes}). -@c ------------------------- -@item -Use sequences conveniently (@pxref{Sequences}). -@c ------------------------- -@item -Use the speedbar, tool bar, and menu bar (see @ref{Speedbar}, see @ref{Tool -Bar}, @pxref{Menu Bar}). -@c ------------------------- -@item -Show header fields in different fonts (@pxref{Reading Mail}). -@c ------------------------- -@item -Find previously refiled messages (@pxref{Searching}). -@c ------------------------- -@item -Place messages in a file (@pxref{Files and Pipes}). -@end itemize - -Remember that you can also use MH commands when you're not running -MH-E (and when you are!). - -@node Using This Manual, Incorporating Mail, Tour Through MH-E, Top -@chapter Using This Manual - -This chapter begins the meat of the manual which goes into more detail -about every MH-E command and option. - -@cindex Emacs, info -@cindex Emacs, online help -@cindex info -@cindex online help -@findex describe-mode -@findex mh-help -@kindex ? -@kindex C-c ? -@kindex C-h C-h -@kindex C-h C-k i -@kindex C-h i -@kindex C-h m - -There are many commands, but don't get intimidated. There are command -summaries at the beginning of each chapter. In case you have or would -like to rebind the keys, the command summaries also list the -associated Emacs Lisp function. Furthermore, even if you're stranded -on a desert island with a laptop and are without your manuals, you can -get a summary of all these commands with GNU Emacs online help: use -@kbd{C-h m} (@code{describe-mode}) for a brief summary of commands, -@kbd{?} (@code{mh-help}) for an even briefer summary@footnote{This -help appears in a buffer called @samp{*MH-E Help*} -(@pxref{Miscellaneous}).} (@kbd{C-c ?} in MH-Letter mode), or @kbd{C-h -i} to read this manual via Info. The online help is quite good; try -running @kbd{C-h C-h}. This brings up a list of available help topics, -one of which displays the documentation for a given key (like @kbd{C-h -k C-n}). Another useful help feature is to view the manual section -that describes a given key (such as @kbd{C-h K i}). In addition, -review @ref{Conventions}, if any of the GNU Emacs conventions are -strange to you. - -In addition to all of the commands, it is also possible to reconfigure -MH-E to fit the needs of even the most demanding user. The following -chapters also describe all of the options, show the defaults, and make -recommendations for customization. - -However, when customizing your mail environment, first try to change -what you want in MH, and only change MH-E if changing MH is not -possible. That way you will get the same behavior inside and outside -GNU Emacs. Note that MH-E does not provide hooks for customizations -that can be done in MH; this omission is intentional. - -@cindex Emacs Lisp Manual -@cindex Emacs, Emacs Lisp Manual -@cindex Emacs, info -@cindex Emacs, online help -@cindex info -@cindex online help - -I hope I've included enough examples here to get you well on your way. -If you want to explore Emacs Lisp further, a programming manual does -exist, -@c Yes, some of the stuff in the following sections is redundant, but -@c TeX barfs if the @ifs are inside the @footnote. -@iftex -@footnote{The @cite{GNU Emacs Lisp Reference Manual} may be available -online in the Info system by typing @kbd{C-h i m Emacs Lisp -@key{RET}}. It is also available online at @* -@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/}. You -can also order a printed manual, which has the desirable side-effect -of helping to support the Free Software Foundation which made all this -great software available. You can find an order form by running -@kbd{C-h C-d}, or you can request an order form from @i{gnu at -gnu.org}.} -@end iftex -@ifinfo -@footnote{@xref{Top, The GNU Emacs Lisp Reference Manual, , elisp, GNU -Emacs Lisp Reference Manual}, which may be available online in the -Info system. It is also available online at -@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/}. You -can also order a printed manual, which has the desirable side-effect -of helping to support the Free Software Foundation which made all this -great software available. You can find an order form by running -@kbd{C-h C-d}, or you can request an order form from @i{gnu at -gnu.org}.} -@end ifinfo -@ifhtml -@footnote{The -@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/, -The GNU Emacs Lisp Reference Manual} may also be available online in -the Info system by typing @kbd{C-h i m Emacs Lisp @key{RET}}. You can -also order a printed manual, which has the desirable side-effect of -helping to support the Free Software Foundation which made all this -great software available. You can find an order form by running -@kbd{C-h C-d}, or you can request an order form from @i{gnu at -gnu.org}.} -@end ifhtml -and you can look at the code itself for examples. Look in the Emacs -Lisp directory on your system (such as -@file{/usr/local/lib/emacs/lisp/mh-e}) and find all the @file{mh-*.el} -files there. When calling MH-E and other Emacs Lisp functions directly -from Emacs Lisp code, you'll need to know the correct arguments. Use -the online help for this. For example, try @kbd{C-h f -mh-execute-commands @key{RET}}. If you write your own functions, -please do not prefix your symbols (variables and functions) with -@samp{mh-}. This prefix is reserved for the MH-E package. To avoid -conflicts with existing MH-E symbols, use a prefix like @samp{my-} or -your initials. (Unless, of course, your initials happen to be @emph{mh}!) - -@menu -* Options:: -* Ranges:: -* Folder Selection:: -@end menu - -@node Options, Ranges, Using This Manual, Using This Manual -@section Options - -@cindex Emacs, customizing -@cindex Emacs, setting options -@cindex customizing MH-E -@cindex setting options -@findex customize-option -@vindex mh-lpr-command-format, example - -Many string or integer options are easy to modify using @kbd{M-x -customize-option}. For example, to modify the option that controls -printing, you would run @kbd{M-x customize-option @key{RET} -mh-lpr-command-format @key{RET}}. In the buffer that appears, modify -the string to the right of the variable. For example, you may change -the @command{lpr} command with @samp{nenscript -G -r -2 -i'%s'}. Then -use the @samp{State} combo box and select @samp{Save for Future -Sessions}. To read more about @code{mh-lpr-command-format}, see -@ref{Printing}. - -@cindex nil -@cindex off, option -@cindex on, option -@cindex option, turning on and off -@cindex t -@findex customize-option -@vindex mh-bury-show-buffer-flag, example - -Options can also hold boolean values. In Emacs Lisp, the boolean -values are @code{nil}, which means false, and @code{t}, which means -true. The @code{customize-option} function makes it easy to change -boolean values; simply click on the toggle button in the customize -buffer to switch between @samp{on} (@code{t}) and @samp{off} -(@code{nil}). For example, try setting @code{mh-bury-show-buffer-flag} -to @samp{off} to keep the MH-Show buffer at the top of the buffer -stack. Use the @samp{State} combo box and choose @samp{Set for Current -Session} to see how the option affects the show buffer. Then choose -the @samp{Erase Customization} menu item to reset the option to the -default, which places the MH-Show buffer at the bottom of the buffer -stack. - -@vindex mh-mhl-format-file, example - -The text usually says to turn on an option by setting it to a -@emph{non-@code{nil}} value, because sometimes values other than -@samp{on} are meaningful. An example of this is the variable -@code{mh-mhl-format-file} (@pxref{Viewing}). Other options, such as -hooks, involve a little more Emacs Lisp programming expertise. - -@cindex customization group, @samp{mh} -@cindex @samp{mh} customization group -@findex customize-group -@findex mh-customize - -You can browse all of the MH-E options with the @code{customize-group} -function. Try entering @kbd{M-x customize-group @key{RET} mh -@key{RET}} to view the top-level options as well as buttons for all of -the MH-E customization groups. Another way to view the MH-E -customization group is to use @kbd{M-x mh-customize @key{RET}}. - -@node Ranges, Folder Selection, Options, Using This Manual -@section Ranges - -@c Sync with mh-folder-mode docstring. - -@cindex message abbreviations -@cindex message ranges -@cindex ranges - -Many commands that operate on individual messages, such as -@code{mh-forward} or @code{mh-refile-msg} take a @code{RANGE} -argument. This argument can be used in several ways. - -@kindex C-u, with ranges - -If you provide the prefix argument @kbd{C-u} to these commands, then -you will be prompted for the message range. This can be any valid MH -range which can include messages, sequences (@pxref{Sequences}), and -the abbreviations (described in the @command{mh}(1) man page): - -@table @samp -@item - -Indicates all messages in the range to , inclusive. The -range must be nonempty. -@c ------------------------- -@item :N -@itemx :+N -@itemx :-N -Up to N messages beginning with (or ending with) message num. Num may -be any of the predefined symbols: first, prev, cur, next or last. -@c ------------------------- -@item first:N -@itemx prev:N -@itemx next:N -@itemx last:N -The first, previous, next or last messages, if they exist. -@c ------------------------- -@item all -All of the messages. -@end table - -For example, a range that shows all of these things is @samp{1 2 3 -5-10 last:5 unseen}. - -@vindex transient-mark-mode - -If the option @code{transient-mark-mode} is turned on and you set a -region in the MH-Folder buffer, then the MH-E command will perform the -operation on all messages in that region. - -@cindex @samp{mh-range} customization group -@cindex customization group, @samp{mh-range} - -The @samp{mh-range} customization group contains a single option which -affects how ranges are interpreted. - -@vtable @code -@item mh-interpret-number-as-range-flag -On means interpret a number as a range (default: @samp{on}). -@end vtable - -@vindex mh-interpret-number-as-range-flag - -Since one of the most frequent ranges used is @samp{last:N}, MH-E will -interpret input such as @samp{200} as @samp{last:200} if the -@code{mh-interpret-number-as-range-flag} option is on (which is the -default). If you need to scan just the message 200, then use the range -@samp{200:1} or @samp{200-200}. - -@node Folder Selection, , Ranges, Using This Manual -@section Folder Selection - -@cindex completion, folders -@cindex folders, completion -@cindex folders, selecting - -When you choose a folder in MH-E via a command such as @kbd{o} -(@code{mh-refile-msg}), completion is used to enter the folder -@ifnothtml -(@pxref{Completion, , , emacs, The GNU Emacs Manual}). -@end ifnothtml -@ifhtml -(see the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Completion.html, -Completion} in @cite{The GNU Emacs Manual}). -@end ifhtml -In addition, MH-E has several ways of choosing a suitable default so -that the folder can often be selected with a single @key{RET} key. - -@cindex customization group, @samp{mh-folder-selection} -@cindex @samp{mh-folder-selection} customization group - -The @samp{mh-folder-selection} customization group contains some -options which are used to help with this. - -@vtable @code -@item mh-default-folder-for-message-function -Function to select a default folder for refiling or @samp{Fcc:} -(default: @code{nil}). -@c ------------------------- -@item mh-default-folder-list -List of addresses and folders (default: @code{nil}). -@c ------------------------- -@item mh-default-folder-must-exist-flag -On means guessed folder name must exist to be used (default: -@samp{on}). -@c ------------------------- -@item mh-default-folder-prefix -Prefix used for folder names generated from aliases (default: @code{""}). -@end vtable - -@vindex mh-default-folder-for-message-function - -You can set the option @code{mh-default-folder-for-message-function} -to a function that provides a default folder for the message to be -refiled. When this function is called, the current buffer contains the -message being refiled and point is at the start of the message. This -function should return the default folder as a string with a leading -@samp{+} sign. It can also return @code{nil} so that the last folder -name is used as the default, or an empty string to suppress the -default entirely. - -Otherwise, the name of the destination folder is derived from the -sender as follows: - -@enumerate -@vindex mh-default-folder-list -@item -The folder name associated with the first address found in the list -@code{mh-default-folder-list} is used. Each element in this list -contains a @samp{Check Recipient} item. If this item is turned on, -then the address is checked against the recipient instead of the -sender. This is useful for mailing lists. -@c ------------------------- -@vindex mh-default-folder-prefix -@item -An alias prefixed by @code{mh-default-folder-prefix} corresponding to -the address is used. The prefix is used to prevent clutter in your -mail directory. @xref{Aliases}. -@end enumerate - -@vindex mh-default-folder-must-exist-flag - -If the derived folder does not exist, and -@code{mh-default-folder-must-exist-flag} is @code{t}, then the last -folder name used is suggested. This is useful if you get mail from -various people for whom you have an alias, but file them all in the -same project folder. - -@node Incorporating Mail, Reading Mail, Using This Manual, Top -@chapter Incorporating Your Mail - -@cindex @samp{Folder} menu -@cindex incorporating -@cindex menu, @samp{Folder} - -This chapter talks about getting mail from your system mailbox into -your MH @samp{+inbox} folder. The following command accomplishes that -and is found in the @samp{Folder} menu. - -@table @kbd -@cindex @samp{Folder > Incorporate New Mail} menu item -@cindex menu item, @samp{Folder > Incorporate New Mail} -@findex mh-inc-folder -@kindex i -@item i -Incorporate new mail into a folder (@code{mh-inc-folder}). -@end table - -@cindex @samp{mh-inc} customization group -@cindex customization group, @samp{mh-inc} - -The following options in the @samp{mh-inc} customization group are -used. - -@vtable @code -@item mh-inc-prog -Program to incorporate mail (default: @code{"inc"}). -@c ------------------------- -@item mh-inc-spool-list -Alternate spool files (default: @code{nil}). -@end vtable - -The following hook is available. - -@vtable @code -@findex mh-inc-folder -@item mh-inc-folder-hook -Hook run by @code{mh-inc-folder} after incorporating mail into a -folder (default: @code{nil}). -@end vtable - -@cindex @samp{+inbox} -@findex mh-inc-folder -@kindex i - -If at any time you receive new mail, incorporate the new mail into -your @samp{+inbox} buffer with @kbd{i} (@code{mh-inc-folder}). Note -that @kbd{i} will display the @samp{+inbox} buffer, even if there -isn't any new mail. You can incorporate mail from any file into the -current folder by specifying a prefix argument; you'll be prompted for -the name of the file to use as well as the destination folder (for -example, @kbd{C-u i ~/mbox @key{RET} +tmp @key{RET}}). - -@cindex @file{.emacs} -@cindex Emacs, notification of new mail -@cindex files, @file{.emacs} -@cindex new mail -@cindex notification of new mail - -Emacs can notify you when you have new mail by displaying @samp{Mail} -in the mode line. To enable this behavior, and to have a clock in the -mode line as well, add the following to @file{~/.emacs}: - -@findex display-time - -@smalllisp -(display-time) -@end smalllisp - -@cindex @command{inc} -@cindex incorporating -@cindex MH commands, @command{inc} -@vindex mh-inc-prog -@vindex mh-progs - -The name of the program that incorporates new mail is stored in -@code{mh-inc-prog}; it is @code{"inc"} by default. This program -generates a one-line summary for each of the new messages. Unless it -is an absolute pathname, the file is assumed to be in the -@code{mh-progs} directory (@pxref{Getting Started}). You may also link -a file to @command{inc} that uses a different format (see -@samp{mh-profile}(5), and sections -@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next -prev} and @uref{@value{MH-BOOK-HOME}/mhstr.html, MH Format Strings} in -the MH book). You'll then need to modify several variables -appropriately (@pxref{Scan Line Formats}). - -@vindex mh-inc-spool-list - -You can use the @code{mh-inc-spool-list} variable to direct MH-E to -retrieve mail from arbitrary spool files other than your system -mailbox, file it in folders other than your @samp{+inbox}, and assign -key bindings to incorporate this mail. - -@cindex @command{procmail} -@cindex @file{.procmailrc} -@cindex Unix commands, @command{procmail} -@cindex files, @file{.procmailrc} - -Suppose you are subscribed to the @i{mh-e-devel} mailing list and you -use @command{procmail} to filter this mail into @file{~/mail/mh-e} -with the following recipe in @file{.procmailrc}: - -@smallexample -PATH=$PATH:/usr/bin/mh -MAILDIR=$HOME/`mhparam Path` -:0: -* ^From mh-e-devel-admin@@stop.mail-abuse.org -mh-e -@end smallexample - -@findex mh-inc-spool-* -@kindex I * - -In order to incorporate @file{~/mail/mh-e} into @samp{+mh-e} with an -@kbd{I m} (@code{mh-inc-spool-mh-e}) command, customize this option, -and click on the @samp{INS} button. Enter a @samp{Spool File} of -@samp{~/mail/mh-e}, a @samp{Folder} of @samp{mh-e}, and a @samp{Key -Binding} of @samp{m}. - -@cindex @command{emacsclient} -@cindex @command{gnuclient} -@cindex @command{xbuffy} -@cindex @samp{gnuserv} -@cindex Unix commands, @command{emacsclient} -@cindex Unix commands, @command{gnuclient} -@cindex Unix commands, @command{xbuffy} - -You can use @command{xbuffy} to automate the incorporation of this -mail using the Emacs 23 command @command{emacsclient} as follows: - -@smallexample -box ~/mail/mh-e - title mh-e - origMode - polltime 10 - headertime 0 - command emacsclient --eval '(mh-inc-spool-mh-e)' -@end smallexample - -In XEmacs, the command @command{gnuclient} is used in a similar -fashion. - -@findex mh-inc-folder -@kindex i -@vindex mh-inc-folder-hook - -You can set the hook @code{mh-inc-folder-hook}, which is called after -new mail is incorporated by the @kbd{i} (@code{mh-inc-folder}) -command. A good use of this hook is to rescan the whole folder either -after running @kbd{M-x mh-rmail} the first time or when you've changed -the message numbers from outside of MH-E. - -@findex mh-execute-commands -@findex mh-rescan-folder, example -@findex mh-show, example -@vindex mh-inc-folder-hook, example - -@smalllisp -@group -(defun my-mh-inc-folder-hook () - "Hook to rescan folder after incorporating mail." - (if (buffer-modified-p) ; @r{if outstanding refiles and deletes,} - (mh-execute-commands)) ; @r{carry them out} - (mh-rescan-folder) ; @r{synchronize with +inbox} - (mh-show)) ; @r{show the current message} - -(add-hook 'mh-inc-folder-hook 'my-mh-inc-folder-hook) - -@i{Rescan folder after incorporating new mail via mh-inc-folder-hook} - -@end group -@end smalllisp - -@node Reading Mail, Folders, Incorporating Mail, Top -@chapter Reading Your Mail - -@cindex @samp{+inbox} -@cindex MH-Folder mode -@cindex MH-Show mode -@cindex modes, MH-Folder -@cindex modes, MH-Show -@cindex reading mail -@findex mh-rmail -@kindex F r -@kindex F v -@kindex M-x mh-rmail - -The MH-E entry point for reading mail is @kbd{M-x mh-rmail}. This -command incorporates your mail and creates a buffer called -@samp{+inbox} in MH-Folder mode. The command @kbd{M-x mh-rmail} shows -you only new mail, not mail you have already read@footnote{If you want -to see your old mail as well, use @kbd{F r} to pull all your messages -into MH-E. Or, give a prefix argument to @code{mh-rmail} so it will -prompt you for folder to visit like @kbd{F v} (for example, @kbd{C-u -M-x mh-rmail @key{RET} bob @key{RET}}). @xref{Folders}.}. - -@findex display-time -@vindex read-mail-command - -There are some commands that need to read mail, such as @kbd{Mouse-2} -over the @samp{Mail} button that @code{display-time} adds to the mode -line. You can configure Emacs to have these commands use MH-E by -setting the option @code{read-mail-command} to @samp{mh-rmail}. - -@cindex @command{scan} -@cindex @samp{Message} menu -@cindex MH commands, @command{scan} -@cindex menu, @samp{Message} -@cindex scan lines - -The @samp{+inbox} buffer contains @dfn{scan lines}, which are one-line -summaries of each incorporated message. You can perform most MH -commands on these messages via one- or two-letter commands in either -the MH-Folder or MH-Show buffers or by using the @samp{Message} menu. -See @command{scan}(1) for a description of the contents of the scan -lines, and see the Figure in @ref{Reading Mail Tour}, for an example. - -@table @kbd -@kindex ? -@findex mh-help -@item ? -Display cheat sheet for the MH-E commands (@code{mh-help}). -@c ------------------------- -@cindex @samp{Message > Show Message} menu item -@cindex menu item, @samp{Message > Show Message} -@kindex @key{RET} -@findex mh-show -@item @key{RET} -Display message (@code{mh-show}). -@c ------------------------- -@cindex @samp{Message > Show Message with Header} menu item -@cindex menu item, @samp{Message > Show Message with Header} -@kindex , (comma) -@findex mh-header-display -@item , (comma) -Display message with all header fields (@code{mh-header-display}). -@c ------------------------- -@cindex @samp{Message > Show Message with Preferred Alternative} menu item -@cindex menu item, @samp{Message > Show Message with Preferred Alternative} -@kindex : (colon) -@findex mh-show-preferred-alternative -@item : (colon) -Display message with the default preferred alternative -(@code{mh-show-preferred-alternative}). -@c ------------------------- -@kindex ; (semicolon) -@findex mh-toggle-mh-decode-mime-flag -@item ; (semicolon) -Toggle the value of @code{mh-decode-mime-flag} -(@code{mh-toggle-mh-decode-mime-flag}). -@c ------------------------- -@kindex @key{SPC} -@findex mh-page-msg -@item @key{SPC} -Display next page in message (@code{mh-page-msg}). -@c ------------------------- -@kindex @key{BS} -@findex mh-previous-page -@item @key{BS} -Display previous page in message (@code{mh-previous-page}). -@c ------------------------- -@cindex @samp{Message > Write Message to File...} menu item -@cindex menu item, @samp{Message > Write Message to File...} -@kindex > -@findex mh-write-msg-to-file -@item > -Append message to end of file (@code{mh-write-msg-to-file}). -@c ------------------------- -@cindex @samp{Message > Pipe Message to Command...} menu item -@cindex menu item, @samp{Message > Pipe Message to Command...} -@kindex | -@findex mh-pipe-msg -@item | -Pipe message through shell command (@code{mh-pipe-msg}). -@c ------------------------- -@kindex C-d -@findex mh-delete-msg-no-motion -@item C-d -Delete range, don't move to next message -(@code{mh-delete-msg-no-motion}). -@c ------------------------- -@cindex @samp{Message > Delete Message} menu item -@cindex menu item, @samp{Message > Delete Message} -@kindex d -@findex mh-delete-msg -@item d -Delete range (@code{mh-delete-msg}). -@c ------------------------- -@kindex D ? -@findex mh-prefix-help -@item D ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@kindex D @key{SPC} -@findex mh-page-digest -@item D @key{SPC} -Display next message in digest (@code{mh-page-digest}). -@c ------------------------- -@kindex D @key{BS} -@findex mh-page-digest-backwards -@item D @key{BS} -Display previous message in digest (@code{mh-page-digest-backwards}). -@c ------------------------- -@cindex @samp{Message > Burst Digest Message} menu item -@cindex menu item, @samp{Message > Burst Digest Message} -@kindex D b -@findex mh-burst-digest -@item D b -Break up digest into separate messages (@code{mh-burst-digest}). -@c ------------------------- -@cindex @samp{Message > Go to Message by Number...} menu item -@cindex menu item, @samp{Message > Go to Message by Number...} -@kindex g -@findex mh-goto-msg -@item g -Go to a message (@code{mh-goto-msg}). -@c ------------------------- -@kindex k -@findex mh-delete-subject-or-thread -@item k -Delete messages with same subject or thread -(@code{mh-delete-subject-or-thread}). -@c ------------------------- -@kindex K ? -@findex mh-prefix-help -@item K ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@kindex K @key{TAB} -@findex mh-next-button -@item K @key{TAB} -Go to the next button (@code{mh-next-button}). -@c ------------------------- -@kindex K S-@key{TAB} -@findex mh-prev-button -@item K S-@key{TAB} -Go to the previous button (@code{mh-prev-button}). -@c ------------------------- -@kindex K a -@findex mh-mime-save-parts -@item K a -Save attachments (@code{mh-mime-save-parts}). -@c ------------------------- -@kindex K e -@findex mh-display-with-external-viewer -@item K e -View attachment externally (@code{mh-display-with-external-viewer}). -@c ------------------------- -@kindex K i -@findex mh-folder-inline-mime-part -@item K i -Show attachment verbatim (@code{mh-folder-inline-mime-part}). -@c ------------------------- -@kindex K o -@findex mh-folder-save-mime-part -@item K o -Save (output) attachment (@code{mh-folder-save-mime-part}). -@c ------------------------- -@kindex K t -@findex mh-toggle-mime-buttons -@item K t -Toggle option @code{mh-display-buttons-for-inline-parts-flag} -(@code{mh-toggle-mime-buttons}). -@c ------------------------- -@kindex K v -@findex mh-folder-toggle-mime-part -@item K v -View attachment (@code{mh-folder-toggle-mime-part}). -@c ------------------------- -@cindex @samp{Message > Modify Message} menu item -@cindex menu item, @samp{Message > Modify Message} -@kindex M -@findex mh-modify -@item M -Edit message (@code{mh-modify}). -@c ------------------------- -@cindex @samp{Message > Go to First Message} menu item -@cindex menu item, @samp{Message > Go to First Message} -@kindex M-< -@findex mh-first-msg -@item M-< -Display first message (@code{mh-first-msg}). -@c ------------------------- -@cindex @samp{Message > Go to Last Message} menu item -@cindex menu item, @samp{Message > Go to Last Message} -@kindex M-> -@findex mh-last-msg -@item M-> -Display last message (@code{mh-last-msg}). -@c ------------------------- -@kindex M-n -@findex mh-next-unread-msg -@item M-n -Display next unread message (@code{mh-next-unread-msg}). -@c ------------------------- -@kindex M-p -@findex mh-previous-unread-msg -@item M-p -Display previous unread message (@code{mh-previous-unread-msg}). -@c ------------------------- -@cindex @samp{Message > Next Message} menu item -@cindex menu item, @samp{Message > Next Message} -@kindex n -@findex mh-next-undeleted-msg -@item n -Display next message (@code{mh-next-undeleted-msg}). -@c ------------------------- -@cindex @samp{Message > Previous Message} menu item -@cindex menu item, @samp{Message > Previous Message} -@kindex p -@findex mh-previous-undeleted-msg -@item p -Display previous message (@code{mh-previous-undeleted-msg}). -@c ------------------------- -@kindex P ? -@findex mh-prefix-help -@item P ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@kindex P C -@findex mh-ps-print-toggle-color -@item P C -Toggle whether color is used in printing messages -(@code{mh-ps-print-toggle-color}). -@c ------------------------- -@kindex P F -@findex mh-ps-print-toggle-faces -@item P F -Toggle whether printing is done with faces or not -(@code{mh-ps-print-toggle-faces}). -@c ------------------------- -@kindex P f -@findex mh-ps-print-msg-file -@item P f -Print range to file (@code{mh-ps-print-msg-file}). -@c ------------------------- -@cindex @samp{Message > Print Message} menu item -@cindex menu item, @samp{Message > Print Message} -@kindex P l -@findex mh-print-msg -@item P l -Print range the old fashioned way -(@code{mh-print-msg}). -@c ------------------------- -@kindex P p -@findex mh-ps-print-msg -@item P p -Print range (@code{mh-ps-print-msg}). -@c ------------------------- -@kindex X ? -@findex mh-prefix-help -@item X ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@cindex @samp{Message > Unpack Uuencoded Message...} menu item -@cindex menu item, @samp{Message > Unpack Uuencoded Message...} -@kindex X s -@kindex X u -@findex mh-store-msg -@item X s -@itemx X u -Unpack message created with @command{uudecode} or @command{shar} -(@code{mh-store-msg}). -@c ------------------------- -@kindex Mouse-2 -@findex mh-show-mouse -@item Mouse-2 -Move point to mouse event and show message (@code{mh-show-mouse}). -@end table - -Within the MH-Show buffer, the following command is defined. - -@table @kbd -@kindex @key{RET} -@kindex Mouse-1 -@kindex Mouse-2 -@findex mh-press-button -@item @key{RET} -@itemx Mouse-1 -@itemx Mouse-2 -View contents of button (@code{mh-press-button}). -@end table - -@cindex @samp{mh-show} customization group -@cindex customization group, @samp{mh-show} - -The following table lists options in the @samp{mh-show} customization -group that are used while reading mail. - -@vtable @code -@item mh-bury-show-buffer-flag -On means show buffer is buried (default: @samp{on}). -@c ------------------------- -@item mh-clean-message-header-flag -On means remove extraneous header fields (default: @samp{on}). -@c ------------------------- -@item mh-decode-mime-flag -On means attachments are handled (default: @samp{on} if the Gnus -@samp{mm-decode} package is present). -@c ------------------------- -@item mh-display-buttons-for-alternatives-flag -On means display buttons for all alternative attachments (default: -@samp{off}). -@c ------------------------- -@item mh-display-buttons-for-inline-parts-flag -On means display buttons for all inline attachments (default: -@samp{off}). -@c ------------------------- -@item mh-do-not-confirm-flag -On means non-reversible commands do not prompt for confirmation -(default: @samp{off}). -@c ------------------------- -@item mh-fetch-x-image-url -Control fetching of @samp{X-Image-URL:} header field image (default: -@samp{Never Fetch}). -@c ------------------------- -@item mh-graphical-smileys-flag -On means graphical smileys are displayed (default: @samp{on}). -@c ------------------------- -@item mh-graphical-emphasis-flag -On means graphical emphasis is displayed (default: @samp{on}). -@c ------------------------- -@item mh-highlight-citation-style -Style for highlighting citations (default: @samp{Multicolor}). -@c ------------------------- -@item mh-invisible-header-fields-default -List of hidden header fields (default: a checklist too long to list -here). -@c ------------------------- -@item mh-invisible-header-fields -Additional header fields to hide (default: @code{nil}). -@c ------------------------- -@item mh-lpr-command-format -Command used to print (default: @code{"lpr -J '%s'"}). -@c ------------------------- -@item mh-max-inline-image-height -Maximum inline image height if @samp{Content-Disposition:} is not -present (default: 0). -@c ------------------------- -@item mh-max-inline-image-width -Maximum inline image width if @samp{Content-Disposition:} is not -present(default: 0). -@c ------------------------- -@item mh-mhl-format-file -Specifies the format file to pass to the @command{mhl} program -(default: @samp{Use Default mhl Format (Printing Only)}). -@c ------------------------- -@item mh-mime-save-parts-default-directory -Default directory to use for @kbd{K a}. -@c ------------------------- -@item mh-print-background-flag -On means messages should be printed in the background (default: -@samp{off}). -@c ------------------------- -@item mh-show-buffer-mode-line-buffer-id -Format string to produce @code{mode-line-buffer-identification} for -show buffers (default: @code{" @{show-%s@} %d"}). -@c ------------------------- -@item mh-show-maximum-size -Maximum size of message (in bytes) to display automatically (default: -0). -@c ------------------------- -@item mh-show-use-xface-flag -On means display face images in MH-Show buffers (default: @samp{on}). -@c ------------------------- -@item mh-store-default-directory -Default directory for @kbd{X s} (default: @samp{Current}). -@c ------------------------- -@item mh-summary-height -Number of lines in MH-Folder buffer (including the mode line) -(default: depends on size of frame). -@end vtable - -The following hooks are available. - -@vtable @code -@item mh-delete-msg-hook -Hook run after marking each message for deletion (default: @code{nil}). -@c ------------------------- -@item mh-show-hook -Hook run after @key{RET} shows a message (default: @code{nil}). -@c ------------------------- -@item mh-show-mode-hook -Hook run upon entry to @code{mh-show-mode} (default: @code{nil}). -@end vtable - -The following faces are available. - -@vtable @code -@item mh-show-cc -Face used to highlight @samp{cc:} header fields. -@c ------------------------- -@item mh-show-date -Face used to highlight @samp{Date:} header fields. -@c ------------------------- -@item mh-show-from -Face used to highlight @samp{From:} header fields. -@c ------------------------- -@item mh-show-header -Face used to deemphasize less interesting header fields. -@c ------------------------- -@item mh-show-pgg-bad -Bad PGG signature face. -@c ------------------------- -@item mh-show-pgg-good -Good PGG signature face. -@c ------------------------- -@item mh-show-pgg-unknown -Unknown or untrusted PGG signature face. -@c ------------------------- -@item mh-show-signature -Signature face. -@c ------------------------- -@item mh-show-subject -Face used to highlight @samp{Subject:} header fields. -@c ------------------------- -@item mh-show-to -Face used to highlight @samp{To:} header fields. -@c ------------------------- -@item mh-show-xface -X-Face image face. -@end vtable - -The functions and variables introduced here are explained in more -detail in the following sections. - -@menu -* Viewing:: -* Viewing Attachments:: -* HTML:: -* Digests:: -* Reading PGP:: -* Printing:: -* Files and Pipes:: -* Navigating:: -* Miscellaneous Commands and Options:: -@end menu - -@node Viewing, Viewing Attachments, Reading Mail, Reading Mail -@section Viewing Your Mail - -@findex mh-header-display -@findex mh-page-msg -@findex mh-previous-page -@findex mh-show -@findex mh-show-mouse -@kindex , (comma) -@kindex . (period) -@kindex @key{BS} -@kindex @key{RET} -@kindex @key{SPC} -@kindex Mouse-2 - -The command @key{RET} (@code{mh-show}) displays the message that the -cursor is on while @kbd{Mouse-2} (@code{mh-show-mouse}) displays the -message that the mouse cursor is on. If the message is already -displayed, it scrolls to the beginning of the message. Use @key{SPC} -(@code{mh-page-msg}) and @key{BS} (@code{mh-previous-page}) to move -forwards and backwards one page at a time through the message. You can -give either of these commands a prefix argument that specifies the -number of lines to scroll (such as @kbd{10 @key{SPC}}). The @key{SPC} -command will also show the next undeleted message if it is used at the -bottom of a message. MH-E normally hides a lot of the superfluous -header fields that mailers add to a message, but if you wish to see -all of them, use the command @kbd{,} (comma; -@code{mh-header-display}). - -@vindex mh-show-maximum-size - -The option @code{mh-show-maximum-size} provides an opportunity to skip -over large messages which may be slow to load. The default value of 0 -means that all message are shown regardless of size. - -A litany of options control what displayed messages look like. - -@vindex mh-show-cc -@vindex mh-show-date -@vindex mh-show-from -@vindex mh-show-header -@vindex mh-show-subject -@vindex mh-show-to - -First, the appearance of the header fields can be modified by -customizing the associated face: @code{mh-show-to}, @code{mh-show-cc}, -@code{mh-show-from}, @code{mh-show-date}, and @code{mh-show-subject}. -The face @code{mh-show-header} is used to deemphasize the other, less -interesting, header fields. - -@cindex regular expressions, @code{mh-invisible-header-fields} -@vindex mh-clean-message-header-flag -@vindex mh-invisible-header-fields -@vindex mh-invisible-header-fields-default - -Normally messages are delivered with a handful of uninteresting header -fields. These are hidden by turning on the option -@code{mh-clean-message-header-flag} (which it is by default). The -header fields listed in the option -@code{mh-invisible-header-fields-default} are hidden, although you can -check off any field that you would like to see. Header fields that you -would like to hide that aren't listed can be added to the option -@code{mh-invisible-header-fields} with a couple of caveats. Regular -expressions are not allowed. Unique fields should have a @samp{:} -suffix; otherwise, the element can be used to render invisible an -entire class of fields that start with the same prefix. If you think a -header field should be generally ignored, please update -@uref{https://sourceforge.net/tracker/index.php?func=detail&aid=1916032&group_id=13357&atid=113357, -SF #1916032}. - -@cindex header field, @samp{Face:} -@cindex header field, @samp{X-Face:} -@cindex header field, @samp{X-Image-URL:} -@cindex @samp{Face:} header field -@cindex @samp{X-Face:} header field -@cindex @samp{X-Image-URL:} header field -@vindex mh-show-use-xface-flag - -MH-E can display the content of @samp{Face:}, @samp{X-Face:}, and -@samp{X-Image-URL:} header fields. If any of these fields occur in the -header of your message, the sender's face will appear in the -@samp{From:} header field. If more than one of these fields appear, -then the first field found in the order @samp{Face:}, @samp{X-Face:}, -and @samp{X-Image-URL:} will be used. The option -@code{mh-show-use-xface-flag} is used to turn this feature on and off. -This feature will be turned on by default if your system supports it. - -The first header field used, if present, is the Gnus-specific -@samp{Face:} field@footnote{The @samp{Face:} field appeared in GNU -Emacs 21 and XEmacs. For more information, see -@uref{http://quimby.gnus.org/circus/face/}.}. - -@cindex @command{uncompface} -@cindex Emacs, packages, x-face -@cindex Unix commands, @command{uncompface} -@cindex x-face package -@vindex mh-show-xface - -Next is the traditional @samp{X-Face:} header field@footnote{The -display of this field requires the -@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z, -@command{uncompface} program}. Recent versions of XEmacs have internal -support for @samp{X-Face:} images. If your version of XEmacs does not, -then you'll need both @command{uncompface} and the -@uref{ftp://ftp.jpl.org/pub/elisp/, @samp{x-face} package}.}. MH-E -renders the foreground and background of the image using the -associated attributes of the face @code{mh-show-xface}. - -@cindex @command{convert} -@cindex @command{wget} -@cindex ImageMagick -@cindex Unix commands, @command{convert} -@cindex Unix commands, @command{wget} -@vindex mh-fetch-x-image-url - -Finally, MH-E will display images referenced by the -@samp{X-Image-URL:} header field if neither the @samp{Face:} nor the -@samp{X-Face:} fields are present@footnote{The display of the images -requires the @uref{http://www.gnu.org/software/wget/wget.html, -@command{wget} program} to fetch the image and the @command{convert} -program from the @uref{http://www.imagemagick.org/, ImageMagick -suite}.}. Of the three header fields this is the most efficient in -terms of network usage since the image doesn't need to be transmitted -with every single mail. The option @code{mh-fetch-x-image-url} -controls the fetching of the @samp{X-Image-URL:} header field image -with the following values: - -@table @samp -@item Ask Before Fetching -You are prompted before the image is fetched. MH-E will remember your -reply and will either use the already fetched image the next time the -same URL is encountered or silently skip it if you didn't fetch it the -first time. This is a good setting. -@c ------------------------- -@item Never Fetch -Images are never fetched and only displayed if they are already -present in the cache. This is the default. -@end table - -There isn't a value of @samp{Always Fetch} for privacy and DOS (denial -of service) reasons. For example, fetching a URL can tip off a spammer -that you've read his email (which is why you shouldn't blindly answer -yes if you've set this option to @samp{Ask Before Fetching}). Someone -may also flood your network and fill your disk drive by sending a -torrent of messages, each specifying a unique URL to a very large -file. - -@cindex @file{.mhe-x-image-cache} -@cindex files, @file{.mhe-x-image-cache} - -The cache of images is found in the directory -@file{.mhe-x-image-cache} within your MH directory. You can add your -own face to the @samp{From:} field too. @xref{Picture}. - -@cindex @command{mhl} -@cindex MH commands, @command{mhl} -@vindex mh-mhl-format-file - -Normally MH-E takes care of displaying messages itself (rather than -calling an MH program to do the work). If you'd rather have -@command{mhl} display the message (within MH-E), change the option -@code{mh-mhl-format-file} from its default value of @samp{Use Default -mhl Format (Printing Only)}. You can set this option to @samp{Use -Default mhl Format} to get the same output as you would get if you ran -@command{mhl} from the shell. If you have a format file that you want -MH-E to use, you can set this option to @samp{Specify an mhl Format -File} and enter the name of your format file (@command{mhl}(1) or -section @uref{@value{MH-BOOK-HOME}/shomes.html#Usisho, Using mhl} in -the MH book tells you how to write one). Your format file should -specify a non-zero value for @samp{overflowoffset} to allow MH-E to -parse the header. Note that @command{mhl} is always used for printing -and forwarding; in this case, the value of @code{mh-mhl-format-file} -is consulted if you have specified a format file. - -@cindex citations, highlighting -@cindex highlighting citations -@vindex mh-highlight-citation-style - -If the sender of the message has cited other messages in his message, -then MH-E will highlight these citations to emphasize the sender's -actual response. The option @code{mh-highlight-citation-style} can be -customized to change the highlighting style. The @samp{Multicolor} -method uses a different color for each indentation while the -@samp{Monotone} method highlights all citations in red. To disable -highlighting of citations entirely, choose @samp{None}. - -@cindex URLs, highlighting -@cindex email addresses, highlighting -@cindex highlighting URLs -@cindex highlighting email addresses -@cindex links, following -@findex goto-address-at-point -@kindex C-c @key{RET} -@kindex Mouse-2 -@vindex goto-address-highlight-p - -Email addresses and URLs in the message are highlighted if the option -@code{goto-address-highlight-p} is on, which it is by default. To view -the web page for a highlighted URL or to send a message using a -highlighted email address, use @kbd{Mouse-2} or @kbd{C-c @key{RET}} -(@code{goto-address-at-point}). @xref{Sending Mail}, to see how to -configure Emacs to send the message using MH-E. - -@cindex boldface, showing -@cindex emphasis -@cindex italics, showing -@cindex smileys -@cindex typesetting -@cindex underline, showing -@vindex gnus-emphasis-alist -@vindex mh-decode-mime-flag -@vindex mh-graphical-emphasis-flag -@vindex mh-graphical-smileys-flag - -It is a long standing custom to inject body language using a -cornucopia of punctuation, also known as the @dfn{smileys}. MH-E can -render these as graphical widgets if the option -@code{mh-graphical-smileys-flag} is turned on, which it is by default. -Smileys include patterns such as :-) and ;-). Similarly, a few -typesetting features are indicated in ASCII text with certain -characters. If your terminal supports it, MH-E can render these -typesetting directives naturally if the option -@code{mh-graphical-emphasis-flag} is turned on, which it is by -default. For example, _underline_ will be -@ifhtml -@html -underlined, -@end html -@end ifhtml -@ifnothtml -underlined, -@end ifnothtml -*bold* will appear in @b{bold}, /italics/ will appear in @i{italics}, -and so on. See the option @code{gnus-emphasis-alist} for the whole -list. Both of these options are disabled if the option -@code{mh-decode-mime-flag} is turned off. @xref{Viewing Attachments}. - -@cindex signature separator -@cindex vCard -@vindex mh-show-signature - -MH-E normally renders signatures and vCards in italics so that the -body of the message stands out more. MH-E depends on the presence of -the @dfn{signature separator} (@code{"-- "}) to do this. You can also -customize the face @code{mh-show-signature} so the appearance of the -signature block is more to your liking. - -@vindex mh-show-hook -@vindex mh-show-mode-hook - -Two hooks can be used to control how messages are displayed. The first -hook, @code{mh-show-mode-hook}, is called early on in the process of -the message display. It is usually used to perform some action on the -message's content. The second hook, @code{mh-show-hook}, is the last -thing called after messages are displayed. It's used to affect the -behavior of MH-E in general or when @code{mh-show-mode-hook} is too -early. - -@cindex MH-Show mode -@cindex modes, MH-Show -@vindex mh-show-buffer-mode-line-buffer-id - -For those who like to modify their mode lines, use -@code{mh-show-buffer-mode-line-buffer-id} to modify the mode line in -the MH-Show buffers. Place the two escape strings @samp{%s} and -@samp{%d}, which will display the folder name and the message number, -respectively, somewhere in the string in that order. The default value -of @code{"@{show-%s@} %d"} yields a mode line of - -@smallexample ------@{show-+inbox@} 4 (MH-Show)--Bot-------------------------------- -@end smallexample - -@node Viewing Attachments, HTML, Viewing, Reading Mail -@section Viewing Attachments - -@cindex attachments -@cindex body parts -@cindex @command{mhshow} -@cindex @command{show} -@cindex MH commands, @command{mhshow} -@cindex MH commands, @command{show} -@cindex MIME -@cindex multimedia mail - -MH has the ability to display @dfn{@sc{mime}} (Multipurpose Internet -Mail Extensions) messages which are simply messages with additional -@dfn{body parts} or @dfn{attachments}. You can use the MH commands -@command{show}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next -prev} in the MH book.} or @command{mhshow}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/usimim.html#ReMIMa, Reading MIME Mail} in -the MH book.} from the shell to read @sc{mime} messages@footnote{You -can call them directly from Emacs if you're running the X Window -System: type @kbd{M-! xterm -e mhshow @var{message-number}}. You can -leave out the @samp{xterm -e} if you use @command{mhlist} or -@command{mhstore}.}. - -@cindex Emacs, packages, mm-decode -@cindex mm-decode package -@findex mh-toggle-mh-decode-mime-flag -@kindex ; (semicolon) -@vindex mh-decode-mime-flag - -MH-E can handle attachments as well if the Gnus @samp{mm-decode} -package is present. If so, the option @code{mh-decode-mime-flag} will -be on. Otherwise, you'll see the @sc{mime} body parts rather than text -or attachments. There isn't much point in turning off the option -@code{mh-decode-mime-flag}; however, you can inspect it if it appears -that the body parts are not being interpreted correctly or toggle it -with the command @kbd{;} (semicolon; -@code{mh-toggle-mh-decode-mime-flag}) to view the raw message. This -option also controls the display of quoted-printable messages and -other graphical widgets. @xref{Viewing}. - -@cindex buttons - -Attachments in MH-E are indicated by @dfn{buttons} like this: - -@smallexample -[1. image/jpeg; foo.jpg]... -@end smallexample - -@findex mh-next-button -@findex mh-press-button -@findex mh-prev-button -@kindex @key{RET} -@kindex K @key{TAB} -@kindex K S-@key{TAB} -@kindex Mouse-1 -@kindex Mouse-2 - -To view the contents of the button, use either @kbd{Mouse-1} or -@kbd{Mouse-2} on the button or @key{RET} (@code{mh-press-button}) when -the cursor is over the button. This command is a toggle so if you use -it again on the same attachment, it is hidden. If Emacs does not know -how to display the attachment, then Emacs offers to save the -attachment in a file. To move the cursor to the next button, use the -command @kbd{K @key{TAB}} (@code{mh-next-button}). If the end of the -buffer is reached then the search wraps over to the start of the -buffer. To move the cursor to the previous button, use the command -@kbd{K S-@key{TAB}} (@code{mh-prev-button}). If the beginning of the -buffer is reached then the search wraps over to the end of the buffer. - -@cindex attachments, viewing -@cindex viewing attachments -@findex mh-folder-toggle-mime-part -@kindex K v - -Another way to view the contents of a button is to use the command -@kbd{K v} (@code{mh-folder-toggle-mime-part}). This command displays -(or hides) the attachment associated with the button under the cursor. -If the cursor is not located over a button, then the cursor first -moves to the next button, wrapping to the beginning of the message if -necessary. This command has the advantage over the previous commands -of working from the MH-Folder buffer. You can also provide a numeric -prefix argument (as in @kbd{4 K v}) to view the attachment labeled -with that number. If Emacs does not know how to display the -attachment, then Emacs offers to save the attachment in a file. - -@cindex @file{/etc/mailcap} -@cindex files, @file{/etc/mailcap} -@findex mailcap-mime-info -@findex mh-display-with-external-viewer -@kindex K e - -If Emacs does not know how to view an attachment, you could save it -into a file and then run some program to open it. It is easier, -however, to launch the program directly from MH-E with the command -@kbd{K e} (@code{mh-display-with-external-viewer}). While you'll most -likely use this to view spreadsheets and documents, it is also useful -to use your browser to view HTML attachments with higher fidelity than -what Emacs can provide. This command displays the attachment -associated with the button under the cursor. If the cursor is not -located over a button, then the cursor first moves to the next button, -wrapping to the beginning of the message if necessary. You can provide -a numeric prefix argument (as in @kbd{4 K e}) to view the attachment -labeled with that number. This command tries to provide a reasonable -default for the viewer by calling the Emacs function -@code{mailcap-mime-info}. This function usually reads the file -@file{/etc/mailcap}. - -@cindex attachments, saving -@cindex saving attachments -@findex mh-folder-save-mime-part -@kindex K o - -Use the command @kbd{K o} (@code{mh-folder-save-mime-part}) to save -attachments (the mnemonic is ``output''). This command saves the -attachment associated with the button under the cursor. If the cursor -is not located over a button, then the cursor first moves to the next -button, wrapping to the beginning of the message if necessary. You can -also provide a numeric prefix argument (as in @kbd{3 K o}) to save the -attachment labeled with that number. This command prompts you for a -filename and suggests a specific name if it is available. - -@cindex @command{mhn} -@cindex @command{mhstore} -@cindex MH commands, @command{mhn} -@cindex MH commands, @command{mhstore} -@findex mh-mime-save-parts -@kindex K a -@vindex mh-mime-save-parts-default-directory - -You can save all of the attachments at once with the command @kbd{K a} -(@code{mh-mime-save-parts}). The attachments are saved in the -directory specified by the option -@code{mh-mime-save-parts-default-directory} unless you use a prefix -argument (as in @kbd{C-u K a}) in which case you are prompted for the -directory. These directories may be superseded by MH profile -components, since this function calls on @command{mhstore} -(@command{mhn}) to do the work. - -@vindex mh-mime-save-parts-default-directory - -The default value for the option -@code{mh-mime-save-parts-default-directory} is @samp{Prompt Always} so -that you are always prompted for the directory in which to save the -attachments. However, if you usually use the same directory within a -session, then you can set this option to @samp{Prompt the First Time} -to avoid the prompt each time. you can make this directory permanent -by choosing @samp{Directory} and entering the directory's name. - -@cindex attachments, inline -@cindex inline attachments -@findex mh-toggle-mime-buttons -@kindex K t -@vindex mh-display-buttons-for-inline-parts-flag - -The sender can request that attachments should be viewed inline so -that they do not really appear like an attachment at all to the -reader. Most of the time, this is desirable, so by default MH-E -suppresses the buttons for inline attachments. On the other hand, you -may receive code or HTML which the sender has added to his message as -inline attachments so that you can read them in MH-E. In this case, it -is useful to see the buttons so that you know you don't have to cut -and paste the code into a file; you can simply save the attachment. If -you want to make the buttons visible for inline attachments, you can -use the command @kbd{K t} (@code{mh-toggle-mime-buttons}) to toggle -the visibility of these buttons. You can turn on these buttons -permanently by turning on the option -@code{mh-display-buttons-for-inline-parts-flag}. - -MH-E cannot display all attachments inline however. It can display -text (including @sc{html}) and images. - -@cindex header field, @samp{Content-Disposition:} -@cindex inline images -@cindex @samp{Content-Disposition:} header field -@vindex mh-max-inline-image-height -@vindex mh-max-inline-image-width - -Some older mail programs do not insert the needed -plumbing@footnote{This plumbing is the @samp{Content-Disposition:} -header field.} to tell MH-E whether to display the attachments inline -or not. If this is the case, MH-E will display these images inline if -they are smaller than the window. However, you might want to allow -larger images to be displayed inline. To do this, you can change the -options @code{mh-max-inline-image-width} and -@code{mh-max-inline-image-height} from their default value of zero to -a large number. The size of your screen is a good choice for these -numbers. - -@cindex alternatives -@cindex attachments, alternatives -@vindex mh-display-buttons-for-alternatives-flag - -Sometimes, a mail program will produce multiple alternatives of an -attachment in increasing degree of faithfulness to the original -content. By default, only the preferred alternative is displayed. If -the option @code{mh-display-buttons-for-alternatives-flag} is on, then -the preferred part is shown inline and buttons are shown for each of -the other alternatives. - -@vindex mm-discouraged-alternatives - -Many people prefer to see the @samp{text/plain} alternative rather -than the @samp{text/html} alternative. To do this in MH-E, customize -the option @code{mm-discouraged-alternatives}, and add -@samp{text/html}. The next best alternative, if any, will be shown. - -@findex mh-show-preferred-alternative -@kindex : (colon) - -Occasionally, though, you might want to see the preferred alternative. -The command @kbd{:} (@code{mh-show-preferred-alternative}) displays -the message with the default preferred alternative. This is as if -@code{mm-discouraged-alternatives} is set to @samp{nil}. Use the -command @key{RET} (@code{mh-show}) to show the message normally again. - -@kindex K i -@findex mh-folder-inline-mime-part - -You can view the raw contents of an attachment with the command @kbd{K -i} (@code{mh-folder-inline-mime-part}). This command displays (or -hides) the contents of the attachment associated with the button under -the cursor verbatim. If the cursor is not located over a button, then -the cursor first moves to the next button, wrapping to the beginning -of the message if necessary. You can also provide a numeric prefix -argument (as in @kbd{4 K i}) to view the attachment labeled with that -number. - -For additional information on buttons, see -@ifinfo -@ref{Article Buttons,,,gnus}, and @ref{MIME Commands,,,gnus}. -@end ifinfo -@ifnotinfo -the chapters @uref{http://www.gnus.org/manual/gnus_101.html#SEC101, -Article Buttons} and -@uref{http://www.gnus.org/manual/gnus_108.html#SEC108, MIME Commands} -in the @cite{The Gnus Manual}. -@end ifnotinfo - -@node HTML, Digests, Viewing Attachments, Reading Mail -@section HTML - -@cindex HTML -@cindex Gnus - -MH-E can display messages that have been sent in HTML@footnote{This -feature depends on a version of Gnus that is at least 5.10.}. The -content of the message will appear in the MH-Show buffer as you would -expect if the entire message is HTML, or there is an inline HTML body -part. However, if there is an HTML body part that is an attachment, -then you'll see a button like this: - -@smallexample -[1. text/html; foo.html]... -@end smallexample - -To see how to read the contents of this body part, see @ref{Viewing -Attachments}. - -@vindex mm-text-html-renderer - -The browser that MH-E uses is determined by the option -@code{mm-text-html-renderer}. The default setting is set automatically -based upon the presence of a known browser on your system. If you wish -to use a different browser, then set this option accordingly. See the -documentation for the browser you use for additional information on -how to use it. In particular, find and disable the option to render -images as this can tip off spammers that the email address they have -used is valid. - -@vindex mm-text-html-renderer - -If you're confused about which @code{mm-text-html-renderer} to use, -here's a brief description of each, sorted by popularity, that -includes the results of a quick poll of MH-E users from 2005-12-23. - -@table @asis -@cindex browser, @samp{w3m} -@cindex @samp{w3m} -@kindex Mouse-2 -@item @samp{w3m} 7 -The @samp{w3m} browser requires an external program. It's quick, -produces pretty nice output, and best of all, it's the only browser -that highlights links. These can be clicked with @kbd{Mouse-2} to view -the content of the link in @samp{w3m}. The @samp{w3m} browser handles -tables well and actually respects the table's width parameter (which -can cause text to wrap if the author didn't anticipate that the page -would be viewed in Emacs). -@c ------------------------- -@cindex browser, @samp{w3m-standalone} -@cindex @samp{w3m-standalone} -@item @samp{w3m-standalone} 3 -This browser, along with @samp{nil} for the external browser, are the -only choices that work without having to download a separate lisp -package or external program. This browser is quick, but does not show -links. It handles simple tables but some tables get rendered much -wider than the Emacs frame. This browser was the only one not to -handle the escape @samp{–} (it printed a @samp{?}), but it did -render @samp{®}. -@c ------------------------- -@cindex browser, @samp{links} -@cindex @samp{links} -@item @samp{links} 1 -The @samp{links} browser requires an external program. It's quick, and -produces nicer output than @samp{lynx} on single column mails in -tables. However, it doesn't show links and it doesn't do as nice a job -on multi-column tables as some lines wrap. At least it fits in 80 -columns and thus seems better than @samp{w3} and -@samp{w3m-standalone}. Converts escapes such as @samp{®} to (R). -@c ------------------------- -@cindex browser, @samp{lynx} -@cindex @samp{lynx} -@item @samp{lynx} 1 -The @samp{lynx} browser requires an external program. It's quick and -produces pretty decent output but it doesn't show links. It doesn't -seem to do multi-column tables which makes output much cleaner. It -centers the output and wraps long lines more than most. Handles -@samp{®}. -@c ------------------------- -@item @samp{nil} 1 -This choice obviously requires an external browser. Like -@samp{w3m-standalone}, it works out of the box. With this setting, -HTML messages have a button for the body part which you can view with -@kbd{K v} (@code{mh-folder-toggle-mime-part}). -@c ------------------------- -@cindex browser, @samp{w3} -@cindex @samp{w3} -@item @samp{w3} 0 -This choice does not require an external program as all of the -rendering is done in lisp. You do need to get the package separately. -This browser is @strong{slow}, and doesn't appear to have been updated -since 2001 and the author hasn't responded to my emails. It displays -unknown tags instead of hiding them, so you get to see all the -Microsoft crap in certain messages. Tends to make multi-column tables -wider than even a full-screen Emacs can handle. Like @samp{w3m}, you -can follow links, but you have to find them first as they are not -highlighted. Performs well on single-column tables and handles escapes -such as @samp{®}. -@c ------------------------- -@cindex browser, @samp{html2text} -@cindex @samp{html2text} -@item @samp{html2text} 0 -The @samp{html2text} browser requires an external program. I noticed -that it can do some nasty things with simple HTML mails (like filling -the entire message as if it were one paragraph, including signature). -On another message, it displayed half of the HTML tags for some -reason. -@end table - -@vindex mm-text-html-renderer - -For a couple more sources of information about -@code{mm-text-html-renderer}, -@ifinfo -@xref{Display Customization,,,emacs-mime}, and the documentation for -the Gnus command @kbd{W h} (@pxref{Article Washing,,,gnus},). -@end ifinfo -@ifnotinfo -see section @uref{http://www.gnus.org/manual/emacs-mime_6.html, -Display Customization} in the @cite{The Emacs MIME Manual} and the -documentation for the Gnus command @kbd{W h} (see section -@uref{http://www.gnus.org/manual/gnus_99.html, Article Washing} in the -@cite{The Gnus Manual}). -@end ifnotinfo - -@cindex @file{.emacs} -@cindex files, @file{.emacs} -@findex browse-url-at-mouse -@kindex S-Mouse-2 - -A useful key binding that you can add to @file{~/.emacs} is the -following which displays an HTML link or textual URL in an external -browser when clicked with @kbd{S-mouse-2}. This binding works in any -buffer, including HTML buffers. - -@smalllisp -(global-set-key [S-mouse-2] 'browse-url-at-mouse) -@end smalllisp - -@node Digests, Reading PGP, HTML, Reading Mail -@section Digests - -@cindex digests -@findex mh-page-digest -@findex mh-page-digest-backwards -@kindex D @key{BS} -@kindex D @key{SPC} -@kindex @key{BS} -@kindex @key{SPC} - -A digest is a message that contains other messages. Special MH-E -commands let you read digests conveniently. You can use @key{SPC} and -@key{BS} to page through the digest as if it were a normal message, -but if you wish to skip to the next message in the digest, use -@kbd{D @key{SPC}} (@code{mh-page-digest}). To return to a previous message, -use @kbd{D @key{BS}} (@code{mh-page-digest-backwards}). - -@cindex @command{burst} -@cindex MH commands, @command{burst} -@cindex MH-Folder Show mode -@cindex modes, MH-Folder Show -@findex mh-burst-digest -@kindex d -@kindex D b -@kindex t - -Another handy command is @kbd{D b} (@code{mh-burst-digest}). This -command uses the MH command @command{burst}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/burdig.html, Bursting Messages} in the MH -book.} to break out each message in the digest into its own message. -Using this command, you can quickly delete unwanted messages, like -this: Once the digest is split up, toggle out of MH-Folder Show mode -with @kbd{t} (@pxref{Folders}) so that the scan lines fill the screen -and messages aren't displayed. Then use @kbd{d} (@pxref{Reading Mail}) -to quickly delete messages that you don't want to read (based on the -@samp{Subject:} header field). You can also burst the digest to reply -directly to the people who posted the messages in the digest. One -problem you may encounter is that the @samp{From:} header fields are -preceded with a @samp{>} so that your reply can't create the -@samp{To:} field correctly. In this case, you must correct the -@samp{To:} field yourself. This is described later (@pxref{Editing -Drafts}). - -@node Reading PGP, Printing, Digests, Reading Mail -@section Signed and Encrypted Messages - -@cindex GPG -@cindex GnuPG -@cindex Gnus -@cindex OpenPGP -@cindex PGP -@cindex RFC 3156 -@cindex encrypted messages -@cindex security -@cindex signed messages - -You can read encrypted or signed PGP or GPG messages with -MH-E@footnote{This feature depends on post-5.10 versions of Gnus. -@cite{MIME Security with OpenPGP} is documented in -@uref{http://www.rfc-editor.org/rfc/rfc3156.txt, RFC 3156}. However, -MH-E can also decrypt old-style PGP messages that are not in MIME -format.}. This section assumes that you already have a good -understanding of GPG and have set up your keys appropriately. - -If someone sends you a signed message, here is what you'll see: - -@smallexample -@group -[[PGP Signed Part:Bill Wohler ]] -This is a signed message. - -[[End of PGP Signed Part]] -@end group -@end smallexample - -@cindex keychain -@cindex key server -@cindex signed messages - -If the key for the given signature is not in your keychain, you'll be -given the opportunity to fetch the key from a key server and verify -the key. If the message is really large, the verification process can -take a long time. You can press @kbd{C-g} at any time to -cancel@footnote{Unfortunately in the current version, the validation -process doesn't display a message so it appears that MH-E has hung. We -hope that this will be fixed in the future.}. - -If the signature doesn't check out, you might see something like this: - -@smallexample -@group -[[PGP Signed Part:Failed]] -This is a signed message. -This is garbage added after the signature was made. - -[[End of PGP Signed Part]] -@end group -@end smallexample - -@cindex decrypting messages - -If someone sends you an encrypted message, MH-E will ask for your -passphrase to decrypt the message. You should see something like this: - -@smallexample -@group -[[PGP Encrypted Part:OK]] - -[[PGP Signed Part:Bill Wohler ]] -This is the secret message. - -[[End of PGP Signed Part]] - -[[End of PGP Encrypted Part]] -@end group -@end smallexample - -If there is a problem decrypting the message, the button will say: - -@smallexample -[[PGP Encrypted Part:Failed]] -@end smallexample - -You can read the contents of this button using the methods described in -@ref{Viewing Attachments}. If the message were corrupted, you'd see -this: - -@smallexample -[[PGP Encrypted Part:Failed] -Invalid base64 data] -@end smallexample - -If your passphrase were incorrect, you'd see something like this: - -@smallexample -[GNUPG:] ENC_TO CD9C88BB610BD9AD 1 0 -[GNUPG:] USERID_HINT CD9C88BB610BD9AD Bill Wohler -[GNUPG:] NEED_PASSPHRASE CD9C88BB610BD9AD CD9C88BB610BD9AD 1 0 -[GNUPG:] BAD_PASSPHRASE CD9C88BB610BD9AD -gpg: encrypted with 1024-bit RSA key, ID 610BD9AD, created 1997-09-09 - "Bill Wohler " -gpg: public key decryption failed: bad passphrase -[GNUPG:] BEGIN_DECRYPTION -[GNUPG:] DECRYPTION_FAILED -gpg: decryption failed: secret key not available -[GNUPG:] END_DECRYPTION - -gpg exited abnormally: '2' -@end smallexample - -@vindex mh-show-pgg-bad -@vindex mh-show-pgg-good -@vindex mh-show-pgg-unknown - -The appearance of the buttons is controlled by the faces -@code{mh-show-pgg-good}, @code{mh-show-pgg-bad}, and -@code{mh-show-pgg-unknown} depending on the validity of the signature. -The latter is used whether the signature is unknown or untrusted. - -@cindex @samp{pgg} customization group -@cindex PGG -@cindex customization group, @samp{pgg} - -The @samp{pgg} customization group may have some settings which may -interest you. -@iftex -See @cite{The PGG Manual}. -@end iftex -@ifinfo -@xref{Top, , The PGG Manual, pgg, The PGG Manual}. -@end ifinfo -@ifhtml -See -@uref{http://www.dk.xemacs.org/Documentation/packages/html/pgg.html, -@cite{The PGG Manual}}. -@end ifhtml - -@node Printing, Files and Pipes, Reading PGP, Reading Mail -@section Printing Your Mail - -@cindex printing -@findex mh-ps-print-msg -@findex mh-ps-print-msg-file -@kindex P f -@kindex P p -@vindex mh-lpr-command-format -@vindex mh-print-background-flag - -To print messages in MH-E, use the command @kbd{P p} -(@code{mh-ps-print-msg}). You can print all the messages in a range -(as in @kbd{C-u P p 1 3 5-7 last:5 frombob @key{RET}}, -@pxref{Ranges}). You can also send the output to a file with @kbd{P f} -(@code{mh-ps-print-msg-file}). This command will print inline text -attachments but will not decrypt messages. However, when a message is -displayed in an MH-Show buffer, then that buffer is used verbatim for -printing with the caveat that only text attachments, if opened inline, -are printed. Therefore, encrypted messages can be printed by showing -and decrypting them first. The commands @kbd{P p} and @kbd{P f} do not -use the options @code{mh-lpr-command-format} or -@code{mh-print-background-flag}, described below. - -@findex mh-ps-print-toggle-color -@kindex P C -@vindex ps-print-color-p - -Colors are emulated on black-and-white printers with shades of gray. -This might produce illegible output, even if your screen colors only -use shades of gray. If this is the case, try using the command @kbd{P -C} (@code{mh-ps-print-toggle-color}) to toggle between color, no -color, and a black and white representation of the colors and see -which works best. You change this setting permanently by customizing -the option @code{ps-print-color-p}. - -@findex mh-ps-print-toggle-faces -@kindex P F - -Another related function is the command @kbd{P F} -(@code{mh-ps-print-toggle-faces}). This command toggles between using -faces and not. When faces are enabled, the printed message will look -very similar to the message in the MH-Show buffer. - -@cindex ps-print package -@cindex Emacs, packages, ps-print - -MH-E uses the @samp{ps-print} package to do the printing, so you can -customize the printing further by going to the @samp{ps-print} -customization group. - -@cindex @command{lpr} -@cindex @command{mhl} -@cindex MH commands, @command{mhl} -@cindex Unix commands, @command{lpr} -@findex mh-print-msg -@kindex P l - -An alternative to using the @samp{ps-print} package is the command -@kbd{P l} (@code{mh-print-msg}) (the @i{l} is for @i{l}ine printer or -@i{l}pr). You can print all the messages in a range. The message is -formatted with @command{mhl}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/shomes.html#Usisho, Using mhl} in the MH -book.} and printed with the @command{lpr} command. - -@kindex P f -@kindex P l -@kindex P p -@vindex mh-lpr-command-format -@vindex mh-print-background-flag - -The command @kbd{P l} uses two options. The option -@code{mh-lpr-command-format} contains the Unix command line which -performs the actual printing. The string can contain one escape, -@samp{%s}, which is replaced by the name of the folder and the message -number and is useful for print job names. The default setting is -@code{"lpr -J '%s'"}. I use @code{"mpage -h'%s' -b Letter -H1of -mlrtb --P"} which produces a nice header and adds a bit of margin so the text -fits within my printer's margins. Normally messages are printed in the -foreground. If this is slow on your system, you may elect to turn on -the option @code{mh-print-background-flag} to print in the background. -If you do this, do not delete the message until it is printed or else -the output may be truncated. These options are not used by the -commands @kbd{P p} or @kbd{P f}. - -@node Files and Pipes, Navigating, Printing, Reading Mail -@section Files and Pipes - -@cindex files -@cindex pipes -@findex mh-refile-or-write-again -@findex mh-write-msg-to-file -@kindex > -@kindex ! - -MH-E does offer a couple of commands that are not a part of MH@. The -first one, @kbd{>} (@code{mh-write-msg-to-file}), writes a message to -a file. You are prompted for the filename. If the file already exists, -the message is appended to it. You can also write the message to the -file without the header by specifying a prefix argument (such as -@kbd{C-u > /tmp/foobar @key{RET}}). Subsequent writes to the same file -can be made with the command @kbd{!} -(@code{mh-refile-or-write-again}). - -@findex mh-pipe-msg -@kindex | -@kindex l - -You can also pipe the message through a Unix shell command with the -command @kbd{|} (@code{mh-pipe-msg}). You are prompted for the Unix -command through which you wish to run your message. If you give a -prefix argument to this command, the message header is included in the -text passed to the command (the contrived example @kbd{C-u | lpr} -would be done with the @kbd{l} command instead). - -@cindex @command{shar} -@cindex @command{uuencode} -@cindex Unix commands, @command{shar} -@cindex Unix commands, @command{uuencode} -@findex mh-store-msg -@kindex X s -@vindex mh-store-default-directory - -If the message is a shell archive @command{shar} or has been run -through @command{uuencode} use @kbd{X s} (@code{mh-store-msg}) to -extract the body of the message. The default directory for extraction -is the current directory; however, you have a chance to specify a -different extraction directory. The next time you use this command, -the default directory is the last directory you used. If you would -like to change the initial default directory, customize the option -@code{mh-store-default-directory}, change the value from -@samp{Current} to @samp{Directory}, and then enter the name of the -directory for storing the content of these messages. - -@findex mh-store-buffer -@kindex @key{RET} -@kindex X s - -By the way, @kbd{X s} calls the Emacs Lisp function -@code{mh-store-buffer}. I mention this because you can use it directly -if you're editing a buffer that contains a file that has been run -through @command{uuencode} or @command{shar}. For example, you can -extract the contents of the current buffer in your home directory by -typing @kbd{M-x mh-store-buffer @key{RET} ~ @key{RET}}. - -@node Navigating, Miscellaneous Commands and Options, Files and Pipes, Reading Mail -@section Navigating - -@cindex moving between messages -@cindex navigation -@findex mh-first-msg -@findex mh-goto-msg -@findex mh-last-msg -@findex mh-next-undeleted-msg -@findex mh-next-unread-msg -@findex mh-previous-undeleted-msg -@findex mh-previous-unread-msg -@kindex g -@kindex M-< -@kindex M-> -@kindex M-n -@kindex M-p -@kindex n -@kindex p - -To move on to the next message, use the command @kbd{n} -(@code{mh-next-undeleted-msg}); use @kbd{p} -(@code{mh-previous-undeleted-msg}) to read the previous message. To -move to the next unread message, use @kbd{M-n} -(@code{mh-next-unread-msg}); use @kbd{M-p} -(@code{mh-previous-unread-msg}) to move to the previous unread -message. These commands can be given a prefix argument to specify how -many messages to skip (for example, @kbd{5 n}). You can also move to a -specific message with @kbd{g} (@code{mh-goto-msg}). You can enter the -message number either before or after typing @kbd{g}. In the latter -case, Emacs prompts you. Finally, you can go to the first or last -message with @kbd{M-<} (@code{mh-first-msg}) and @kbd{M->} -(@code{mh-last-msg}) respectively. - -@cindex MH-Folder mode -@cindex modes, MH-Folder -@findex next-line -@findex previous-line -@kindex C-n -@kindex C-p -@kindex @key{RET} - -You can also use the Emacs commands @kbd{C-p} (@code{previous-line}) -and @kbd{C-n} (@code{next-line}) to move up and down the scan lines in -the MH-Folder window. These commands can be used in conjunction with -@key{RET} to look at deleted or refiled messages. - -@cindex deleting messages -@findex mh-delete-msg -@kindex d -@kindex n -@kindex p - -To mark a message for deletion, use the command @kbd{d} -(@code{mh-delete-msg}). A @samp{D} is placed by the message in the -scan window, and the next undeleted message is displayed. If the -previous command had been @kbd{p}, then the next message displayed is -the first undeleted message previous to the message just deleted. Use -@kbd{n} to force subsequent @kbd{d} commands to move forward to the -next undeleted message after deleting the message under the cursor. -You may also specify a range (for example, @kbd{C-u d 1 3 5-7 last:5 -frombob @key{RET}}, @pxref{Ranges}). - -@findex mh-delete-msg-no-motion -@kindex C-d - -The command @kbd{C-d} (@code{mh-delete-msg-no-motion}) marks the -message (or messages in range) for deletion but leaves the cursor at -the current message in case you wish to perform other operations on -the message. - -@findex mh-delete-subject -@findex mh-delete-subject-or-thread -@findex mh-thread-delete -@findex mh-undo -@kindex k -@kindex T d -@kindex u - -And to delete more messages faster, you can use @kbd{k} -(@code{mh-delete-subject-or-thread}) to delete all the messages with -the same subject as the current message. This command puts these -messages in a sequence named @samp{subject}. You can undo this action -by using @kbd{u} (@code{mh-undo}) with a prefix argument and then -specifying the @samp{subject} sequence. However, if the buffer is -displaying a threaded view of the folder then @kbd{k} behaves like -@kbd{T d} (@code{mh-thread-delete}). @xref{Threading}. - -@findex mh-execute-commands -@kindex x - -However you mark a message for deletion, the command @kbd{x} -(@code{mh-execute-commands}) actually carries out the deletion -(@pxref{Folders}). - -@vindex mh-delete-msg-hook - -The hook @code{mh-delete-msg-hook} is called after you mark a message -for deletion. For example, a past maintainer of MH-E used this once -when he kept statistics on his mail usage. - -@node Miscellaneous Commands and Options, , Navigating, Reading Mail -@section Miscellaneous Commands and Options - -This section contains a few more miscellaneous commands and options. - -@cindex editing message -@findex mh-modify -@kindex M - -There are times when you need to edit a message. For example, you may -need to fix a broken Content-Type header field. You can do this with -the command @kbd{M} (@code{mh-modify}). It displays the raw message in -an editable buffer. When you are done editing, save and kill the -buffer as you would any other. - -@findex mh-kill-folder -@findex mh-pack-folder -@vindex mh-do-not-confirm-flag - -Commands such as @code{mh-pack-folder} prompt to confirm whether to -process outstanding moves and deletes or not before continuing. -Turning on the option @code{mh-do-not-confirm-flag} means that these -actions will be performed---which is usually desired but cannot be -retracted---without question@footnote{In previous versions of MH-E, -this option suppressed the confirmation in @code{mh-kill-folder}. -Since this kept most users from setting this option, -@code{mh-kill-folder} was modified in version 6.0 to always ask for -confirmation subject to @code{mh-kill-folder-suppress-prompt-hook}. -@xref{Folders}.}. - -@cindex MH-Folder mode -@cindex modes, MH-Folder -@vindex mh-summary-height - -The option @code{mh-summary-height} controls the number of scan lines -displayed in the MH-Folder window, including the mode line. The -default value of this option is @samp{Automatic} which means that the -MH-Folder buffer will maintain the same proportional size if the frame -is resized. If you'd prefer a fixed height, then choose the -@samp{Fixed Size} option and enter the number of lines you'd like to -see. - -@vindex mh-bury-show-buffer-flag - -Normally the buffer for displaying messages is buried at the bottom at -the buffer stack. You may wish to disable this feature by turning off -the option @code{mh-bury-show-buffer-flag}. One advantage of not -burying the show buffer is that one can delete the show buffer more -easily in an electric buffer list because of its proximity to its -associated MH-Folder buffer. Try running @kbd{M-x -electric-buffer-list} to see what I mean. - -@cindex @file{.emacs} -@cindex files, @file{.emacs} -@cindex reading mail - -Before we leave this section, I'll include a function that I use as a -front end to MH-E@footnote{Stephen Gildea's favorite binding is -@kbd{(global-set-key "\C-cr" 'mh-rmail)}.}. It toggles between your -working window configuration, which may be quite involved---windows -filled with source, compilation output, man pages, and other -documentation---and your MH-E window configuration. Like the rest of -the customization described in this section, simply add the following -code to @file{~/.emacs}. - -@iftex -@filbreak -@end iftex - -@findex mh-rmail, example - -@smalllisp -@group -(defvar my-mh-screen-saved nil - "Set to non-@code{nil} when MH-E window configuration shown.") -(defvar my-normal-screen nil "Normal window configuration.") -(defvar my-mh-screen nil "MH-E window configuration.") - -(defun my-mh-rmail (&optional arg) - "Toggle between MH-E and normal screen configurations. -With non-@code{nil} or prefix argument, @i{inc} mailbox as well -when going into mail." - (interactive "P") ; @r{user callable function, P=prefix arg} - (setq my-mh-screen-saved ; @r{save state} - (cond - ;; @r{Bring up MH-E screen if arg or normal window configuration.} - ;; @r{If arg or +inbox buffer doesn't exist, run mh-rmail.} - ((or arg (null my-mh-screen-saved)) - (setq my-normal-screen (current-window-configuration)) - (if (or arg (null (get-buffer "+inbox"))) - (mh-rmail) - (set-window-configuration my-mh-screen)) - t) ; @r{set my-mh-screen-saved to @code{t}} - ;; @r{Otherwise, save MH-E screen and restore normal screen.} - (t - (setq my-mh-screen (current-window-configuration)) - (set-window-configuration my-normal-screen) - nil)))) ; @r{set my-mh-screen-saved to nil} - -(global-set-key "\C-x\r" 'my-mh-rmail) ;@r{ call with C-x @key{RET}} - -@i{Starting MH-E} - -@end group -@end smalllisp - -If you type an argument (@kbd{C-u}) or if @code{my-mh-screen-saved} is -@code{nil} (meaning a non-MH-E window configuration), the current -window configuration is saved, either the @samp{+inbox} buffer is -displayed or @code{mh-rmail} is run, and the MH-E window configuration -is shown. Otherwise, the MH-E window configuration is saved and the -original configuration is displayed. - -@node Folders, Sending Mail, Reading Mail, Top -@chapter Organizing Your Mail with Folders - -@cindex @samp{Folder} menu -@cindex @samp{Message} menu -@cindex folders -@cindex menu, @samp{Folder} -@cindex menu, @samp{Message} -@cindex using folders - -This chapter discusses the things you can do with folders within MH-E. -The commands in this chapter are also found in the @samp{Folder} and -@samp{Message} menus. - -@table @kbd -@kindex ? -@findex mh-help -@item ? -Display cheat sheet for the MH-E commands (@code{mh-help}). -@c ------------------------- -@kindex ! -@findex mh-refile-or-write-again -@item ! -Repeat last output command (@code{mh-refile-or-write-again}). -@c ------------------------- -@cindex @samp{Message > Copy Message to Folder...} menu item -@cindex menu item, @samp{Message > Copy Message to Folder...} -@kindex c -@findex mh-copy-msg -@item c -Copy range to folder (@code{mh-copy-msg}). -@c ------------------------- -@kindex F ? -@findex mh-prefix-help -@item F ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@kindex F ' -@findex mh-index-ticked-messages -@item F ' -Display ticked messages (@code{mh-index-ticked-messages}). -@c ------------------------- -@kindex F c -@findex mh-catchup -@item F c -Delete range from the @samp{unseen} sequence (@code{mh-catchup}). -@c ------------------------- -@kindex F k -@findex mh-kill-folder -@item F k -Remove folder (@code{mh-kill-folder}). -@c ------------------------- -@cindex @samp{Folder > List Folders} menu item -@cindex menu item, @samp{Folder > List Folders} -@kindex F l -@findex mh-list-folders -@item F l -List all folders (@code{mh-list-folders}). -@c ------------------------- -@cindex @samp{Folder > View New Messages} menu item -@cindex menu item, @samp{Folder > View New Messages} -@kindex F n -@findex mh-index-new-messages -@item F n -Display unseen messages (@code{mh-index-new-messages}). -@c ------------------------- -@cindex @samp{Folder > Pack Folder} menu item -@cindex menu item, @samp{Folder > Pack Folder} -@kindex F p -@findex mh-pack-folder -@item F p -Pack folder (@code{mh-pack-folder}). -@c ------------------------- -@kindex F q -@findex mh-index-sequenced-messages -@item F q -Display messages in any sequence (@code{mh-index-sequenced-messages}). -@c ------------------------- -@cindex @samp{Folder > Rescan Folder} menu item -@cindex menu item, @samp{Folder > Rescan Folder} -@kindex F r -@findex mh-rescan-folder -@item F r -Rescan folder (@code{mh-rescan-folder}). -@c ------------------------- -@cindex @samp{Folder > Search...} menu item -@cindex menu item, @samp{Folder > Search...} -@kindex F s -@findex mh-search -@item F s -Search your MH mail (@code{mh-search}). -@c ------------------------- -@cindex @samp{Folder > Sort Folder} menu item -@cindex menu item, @samp{Folder > Sort Folder} -@kindex F S -@findex mh-sort-folder -@item F S -Sort folder (@code{mh-sort-folder}). -@c ------------------------- -@kindex F u -@findex mh-undo-folder -@item F u -Undo all refiles and deletes in the current folder (@code{mh-undo-folder}). -@c ------------------------- -@cindex @samp{Folder > Visit a Folder...} menu item -@cindex menu item, @samp{Folder > Visit a Folder...} -@kindex F v -@findex mh-visit-folder -@item F v -Visit folder (@code{mh-visit-folder}). -@c ------------------------- -@cindex @samp{Message > Refile Message} menu item -@cindex menu item, @samp{Message > Refile Message} -@kindex o -@findex mh-refile-msg -@item o -Refile (output) range into folder (@code{mh-refile-msg}). -@c ------------------------- -@cindex @samp{Folder > Quit MH-E} menu item -@cindex menu item, @samp{Folder > Quit MH-E} -@kindex q -@findex mh-quit -@item q -Quit the current MH-E folder (@code{mh-quit}). -@c ------------------------- -@cindex @samp{Folder > Toggle Show/Folder} menu item -@cindex menu item, @samp{Folder > Toggle Show/Folder} -@kindex t -@findex mh-toggle-showing -@item t -Toggle between MH-Folder and MH-Folder Show modes -(@code{mh-toggle-showing}). -@c ------------------------- -@cindex @samp{Message > Undo Delete/Refile} menu item -@cindex menu item, @samp{Message > Undo Delete/Refile} -@kindex u -@findex mh-undo -@item u -Undo pending deletes or refiles in range (@code{mh-undo}). -@c ------------------------- -@cindex @samp{Message > Execute Delete/Refile} menu item -@cindex menu item, @samp{Message > Execute Delete/Refile} -@kindex x -@findex mh-execute-commands -@item x -Process outstanding delete and refile requests -(@code{mh-execute-commands}). -@end table - -@cindex @samp{mh-folder} customization group -@cindex customization group, @samp{mh-folder} - -The @samp{mh-folder} customization group is used to tune these -commands. - -@vtable @code -@item mh-new-messages-folders -Folders searched for the @samp{unseen} sequence (default: -@code{Inbox}). -@c ------------------------- -@item mh-ticked-messages-folders -Folders searched for @code{mh-tick-seq} (default: @code{t}). -@c ------------------------- -@item mh-large-folder -The number of messages that indicates a large folder (default: 200). -@c ------------------------- -@item mh-recenter-summary-flag -On means to recenter the summary window (default: @samp{off}). -@c ------------------------- -@item mh-recursive-folders-flag -On means that commands which operate on folders do so recursively -(default: @samp{off}). -@c ------------------------- -@item mh-sortm-args -Additional arguments for @command{sortm} (default: @code{nil}). -@end vtable - -The following hooks are available. - -@vtable @code -@item mh-after-commands-processed-hook -Hook run by @kbd{x} after performing outstanding refile and delete -requests (default: @code{nil}). -@c ------------------------- -@item mh-before-commands-processed-hook -Hook run by @kbd{x} before performing outstanding refile and delete -requests (default: @code{nil}). -@c ------------------------- -@item mh-before-quit-hook -Hook run by q before quitting MH-E (default: @code{nil}). -@c ------------------------- -@item mh-folder-mode-hook -Hook run by @code{mh-folder-mode} when visiting a new folder (default: -@code{nil}). -@c ------------------------- -@item mh-kill-folder-suppress-prompt-hook -Abnormal hook run at the beginning of @code{mh-kill-folder} (default: -@code{'mh-search-p}). -@c ------------------------- -@item mh-pack-folder-hook -Hook run by @code{mh-pack-folder} after renumbering the messages -(default: @code{nil}). -@c ------------------------- -@item mh-quit-hook -Hook run by q after quitting MH-E (default: @code{nil}). -@c ------------------------- -@item mh-refile-msg-hook -Hook run by o after marking each message for refiling (default: -@code{nil}). -@end vtable - -The following faces are available for customizing the appearance of -the MH-Folder buffer. @xref{Scan Line Formats}. - -@vtable @code -@item mh-folder-address -Recipient face. -@c ------------------------- -@item mh-folder-body -Body text face. -@c ------------------------- -@item mh-folder-cur-msg-number -Current message number face. -@c ------------------------- -@item mh-folder-date -Date face. -@c ------------------------- -@item mh-folder-deleted -Deleted message face. -@c ------------------------- -@item mh-folder-followup -@samp{Re:} face. -@c ------------------------- -@item mh-folder-msg-number -Message number face. -@c ------------------------- -@item mh-folder-refiled -Refiled message face. -@c ------------------------- -@vindex mh-scan-format-nmh -@vindex mh-scan-sent-to-me-sender-regexp -@item mh-folder-sent-to-me-hint -Fontification hint face in messages sent directly to us. The detection -of messages sent to us is governed by the scan format -@code{mh-scan-format-nmh} and regular expression -@code{mh-scan-sent-to-me-sender-regexp}. -@c ------------------------- -@vindex mh-scan-format-nmh -@vindex mh-scan-sent-to-me-sender-regexp -@item mh-folder-scan-format -Sender face in messages sent directly to us. The detection of messages -sent to us is governed by the scan format @code{mh-scan-format-nmh} -and regular expression @code{mh-scan-sent-to-me-sender-regexp}. -@c ------------------------- -@item mh-folder-subject -Subject face. -@c ------------------------- -@item mh-folder-tick -Ticked message face. -@c ------------------------- -@item mh-folder-to -@samp{To:} face. -@end vtable - -@vindex mh-folder-mode-hook - -The hook @code{mh-folder-mode-hook} is called when visiting a new -folder in MH-Folder mode. This could be used to set your own key -bindings, for example: - -@vindex mh-folder-mode-hook, example - -@smalllisp -@group -(defvar my-mh-init-done nil - "Non-@code{nil} when one-time MH-E settings made.") - -(defun my-mh-folder-mode-hook () - "Hook to set key bindings in MH-Folder mode." - (if (not my-mh-init-done) ; @r{only need to bind the keys once } - (progn - (local-set-key "//" 'my-search-msg) - (local-set-key "b" 'mh-burst-digest) ; @r{better use of @kbd{b}} - (setq my-mh-init-done t)))) - -(add-hook 'mh-folder-mode-hook 'my-mh-folder-mode-hook) - -(defun my-search-msg () - "Search for a regexp in the current message." - (interactive) ; @r{user function} - (save-window-excursion - (other-window 1) ; @r{go to next window} - (isearch-forward-regexp))) ; @r{string search; hit return} - ; @r{ when done} - -@i{Create additional key bindings via mh-folder-mode-hook} - -@end group -@end smalllisp - -@cindex @command{folder} -@cindex @command{refile} -@cindex MH commands, @command{folder} -@cindex MH commands, @command{refile} -@findex mh-refile-msg -@kindex o -@vindex mh-refile-msg-hook - -MH-E has analogies for each of the MH @command{folder} and -@command{refile} commands@footnote{See the sections -@uref{@value{MH-BOOK-HOME}/fol.html#Youfol, Your Current Folder: -folder} and @uref{@value{MH-BOOK-HOME}/fol.html#Movref, Moving and -Linking Messages: refile} in the MH book.}. To refile a message in -another folder, use the command @kbd{o} (@code{mh-refile-msg}) -(mnemonic: ``output''). You are prompted for the folder name -(@pxref{Folder Selection}). Note that this command can also be used to -create folders. If you specify a folder that does not exist, you will -be prompted to create it. The hook @code{mh-refile-msg-hook} is called -after a message is marked to be refiled. - -@findex mh-write-msg-to-file -@kindex ! - -If you are refiling several messages into the same folder, you can use -the command @kbd{!} (@code{mh-refile-or-write-again}) to repeat the -last refile or write (for the description of @kbd{>} -(@code{mh-write-msg-to-file}), @pxref{Files and Pipes}). You can use a -range in either case (for example, @kbd{C-u o 1 3 5-7 last:5 frombob -@key{RET}}, @pxref{Ranges}). - -@cindex expunging refiles and deletes -@cindex undoing refiles and deletes -@findex mh-undo -@kindex u - -If you've deleted a message or refiled it, but changed your mind, you -can cancel the action before you've executed it. Use @kbd{u} -(@code{mh-undo}) to undo a refile on or deletion of a single message. -You can also undo refiles and deletes for messages that are found in a -given range (@pxref{Ranges}). - -@findex mh-undo-folder -@kindex F u - -Alternatively, you can use @kbd{F u} (@code{mh-undo-folder}) to undo -all refiles and deletes in the current folder. - -@findex mh-execute-commands -@kindex x - -If you've marked messages to be deleted or refiled and you want to go -ahead and delete or refile the messages, use @kbd{x} -(@code{mh-execute-commands}). Many MH-E commands that may affect the -numbering of the messages (such as @kbd{F r} or @kbd{F p}) will ask if -you want to process refiles or deletes first and then either run -@kbd{x} for you or undo the pending refiles and deletes. - -@kindex x -@vindex mh-after-commands-processed-hook -@vindex mh-before-commands-processed-hook -@vindex mh-current-folder - -The command @kbd{x} runs @code{mh-before-commands-processed-hook} -before the commands are processed and -@code{mh-after-commands-processed-hook} after the commands are -processed. Variables that are useful with the former hook include -@code{mh-delete-list} and @code{mh-refile-list} which can be used to -see which changes will be made to the current folder, -@code{mh-current-folder}. Variables that are useful with the latter -hook include @code{mh-folders-changed}, which lists which folders were -affected by deletes and refiles. This list will always include the -current folder @code{mh-current-folder}. - -@findex mh-copy-msg -@kindex c -@kindex o - -If you wish to copy a message to another folder, you can use the -command @kbd{c} (@code{mh-copy-msg}) (see the @option{-link} argument -to @command{refile}(1)). Like the command @kbd{o}, this command -prompts you for the name of the target folder and you can specify a -range (@pxref{Ranges}). Note that unlike the command @kbd{o}, the copy -takes place immediately. The original copy remains in the current -folder. - -@cindex junk mail -@cindex MH-Folder mode -@cindex MH-Folder Show mode -@cindex modes, MH-Folder -@cindex modes, MH-Folder Show -@cindex spam -@findex mh-toggle-showing -@kindex t - -The command @kbd{t} (@code{mh-toggle-showing}) switches between -MH-Folder mode and MH-Folder Show mode@footnote{For you Emacs wizards, -this is implemented as an Emacs minor mode.}. MH-Folder mode turns off -the associated show buffer so that you can perform operations on the -messages quickly without reading them. This is an excellent way to -prune out your junk mail or to refile a group of messages to another -folder for later examination. - -@cindex MH-Folder mode -@cindex MH-Show mode -@cindex modes, MH-Folder -@cindex modes, MH-Show -@cindex moving between messages -@kindex t -@vindex mh-recenter-summary-flag - -When you use @kbd{t} to toggle from MH-Folder Show mode to MH-Folder -mode, the MH-Show buffer is hidden and the MH-Folder buffer is left -alone. Setting @code{mh-recenter-summary-flag} to a non-@code{nil} -value causes the toggle to display as many scan lines as possible, -with the cursor at the middle. The effect of -@code{mh-recenter-summary-flag} is rather useful, but it can be -annoying on a slow network connection. - -@findex mh-visit-folder -@kindex F v -@vindex mh-large-folder - -When you want to read the messages that you have refiled into folders, -use the command @kbd{F v} (@code{mh-visit-folder}) to visit the -folder. You are prompted for the folder name. The folder buffer will -show just unseen messages if there are any; otherwise, it will show -all the messages in the buffer as long there are fewer than -@code{mh-large-folder} messages. If there are more, then you are -prompted for a range of messages to scan. You can provide a prefix -argument in order to specify a range of messages to show when you -visit the folder (@pxref{Ranges}). In this case, regions are not used -to specify the range and @code{mh-large-folder} is ignored. Note that -this command can also be used to create folders. If you specify a -folder that does not exist, you will be prompted to create it. - -@findex mh-search -@kindex F s - -If you forget where you've refiled your messages, you can find them -using @kbd{F s} (@code{mh-search}). @xref{Searching}. - -@cindex @command{procmail} -@cindex @samp{unseen} sequence -@cindex sequence, @samp{unseen} -@cindex Unix commands, @command{procmail} -@cindex unseen messages, viewing -@findex mh-index-new-messages -@kindex F n -@vindex mh-new-messages-folders - -If you use a program such as @command{procmail} to file your incoming -mail automatically, you can display new, unseen, messages using the -command @kbd{F n} (@code{mh-index-new-messages}). All messages in the -@samp{unseen} sequence from the folders in -@code{mh-new-messages-folders} are listed. However, this list of -folders can be overridden with a prefix argument: with a prefix -argument, enter a space-separated list of folders, or nothing to -search all folders. - -@cindex @samp{tick} sequence -@cindex sequence, @samp{tick} -@cindex ticked messages, viewing -@findex mh-index-ticked-messages -@kindex F ' -@vindex mh-ticked-messages-folders - -If you have ticked messages (@pxref{Sequences}), you can display them -using the command @kbd{F '} (@code{mh-index-ticked-messages}). All -messages in the @samp{tick} sequence from the folders in -@code{mh-ticked-messages-folders} are listed. With a prefix argument, -enter a space-separated list of folders, or nothing to search all -folders. - -@findex mh-index-sequenced-messages -@kindex F q -@vindex mh-new-messages-folders - -You can display messages in any sequence with the command @kbd{F q} -(@code{mh-index-sequenced-messages}). All messages from the folders in -@code{mh-new-messages-folders} in the sequence you provide are listed. -With a prefix argument, enter a space-separated list of folders at the -prompt, or nothing to search all folders. - -@vindex mh-new-messages-folders -@vindex mh-recursive-folders-flag -@vindex mh-ticked-messages-folders - -Set the options @code{mh-new-messages-folders} and -@code{mh-ticked-messages-folders} to @samp{Inbox} to search the -@samp{+inbox} folder or @samp{All} to search all of the top level -folders. Otherwise, list the folders that should be searched with the -@samp{Choose Folders} menu item. See @code{mh-recursive-folders-flag}. - -@cindex buffers, @samp{*MH-E Folders*} -@cindex @samp{*MH-E Folders*} -@findex mh-kill-folder -@findex mh-list-folders -@findex mh-pack-folder -@findex mh-rescan-folder -@findex mh-sort-folder -@kindex F k -@kindex F l -@kindex F p -@kindex F r -@kindex F S - -Other commands you can perform on folders include: @kbd{F l} -(@code{mh-list-folders}), to place a listing of all the folders in -your mail directory in a buffer called @samp{*MH-E Folders*} -(@pxref{Miscellaneous}); @kbd{F k} (@code{mh-kill-folder}), to remove -a folder; @kbd{F S} (@code{mh-sort-folder}), to sort the messages by -date (see @command{sortm}(1) to see how to sort by other criteria); -@kbd{F p} (@code{mh-pack-folder}), to pack a folder, removing gaps -from the numbering sequence; and @kbd{F r} (@code{mh-rescan-folder}), -to rescan the folder, which is useful to grab all messages in your -@samp{+inbox} after processing your new mail for the first time. If -you don't want to rescan the entire folder, the commands @kbd{F r} or -@kbd{F p} will accept a range (@pxref{Ranges}). - -@kindex F p -@vindex mh-pack-folder-hook - -The command @kbd{F p} runs @code{mh-pack-folder-hook} after -renumbering the messages. A variable that is useful with this hook -is @code{mh-current-folder}. - -@kindex @key{TAB} -@vindex mh-recursive-folders-flag - -By default, operations on folders work only one level at a time. Set -@code{mh-recursive-folders-flag} to non-@code{nil} to operate on all -folders. This mostly means that you'll be able to see all your folders -when you press @key{TAB} when prompted for a folder name. - -@findex mh-search-p -@kindex k -@vindex mh-kill-folder-suppress-prompt-hooks - -The hook @code{mh-kill-folder-suppress-prompt-hooks} is an abnormal -hook run at the beginning of the command @kbd{k}. The hook functions -are called with no arguments and should return a non-nil value to -suppress the normal prompt when you remove a folder. This is useful -for folders that are easily regenerated. The default value of -@code{mh-search-p} suppresses the prompt on folders generated by -searching. - -@sp 1 -@center @strong{NOTE} - -@quotation -Use this hook with care. If there is a bug in your hook which returns -@code{t} on @samp{+inbox} and you press @kbd{k} by accident in the -@code{+inbox} folder, you will not be happy. -@end quotation -@sp 1 - -@cindex @command{sortm} -@cindex @file{.mh_profile} -@cindex files, @file{.mh_profile} -@cindex MH commands, @command{sortm} -@cindex MH profile component, @samp{sortm:} -@cindex @samp{sortm:} MH profile component -@kindex F S -@vindex mh-sortm-args - -The option @code{mh-sortm-args} holds extra arguments to pass on to -the command @command{sortm}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/sorsor.html, Sorting Messages: sortm} in the -MH book.} when a prefix argument is used with @kbd{F S}. Normally -default arguments to @command{sortm} are specified in the MH profile. -This option may be used to provide an alternate view. For example, -@samp{'(\"-nolimit\" \"-textfield\" \"subject\")} is a useful setting. - -@cindex exiting -@cindex quitting -@findex mh-quit -@kindex q - -When you want to quit using MH-E and go back to editing, you can use -the @kbd{q} (@code{mh-quit}) command. This buries the buffers of the -current MH-E folder and restores the buffers that were present when -you first ran @kbd{M-x mh-rmail}. It also removes any MH-E working -buffers whose name begins with @samp{ *mh-} or @samp{*MH-E } -(@pxref{Miscellaneous}). You can later restore your MH-E session by -selecting the @samp{+inbox} buffer or by running @kbd{M-x mh-rmail} -again. - -@findex mh-execute-commands -@kindex q -@vindex mh-before-quit-hook -@vindex mh-before-quit-hook, example -@vindex mh-quit-hook -@vindex mh-quit-hook, example - -The two hooks @code{mh-before-quit-hook} and @code{mh-quit-hook} are -called by @kbd{q}. The former one is called before the quit occurs, so -you might use it to perform any MH-E operations; you could perform -some query and abort the quit or call @code{mh-execute-commands}, for -example. The latter is not run in an MH-E context, so you might use it -to modify the window setup. If you find that @kbd{q} buries a lot of -buffers that you would rather remove, you can use both -@code{mh-before-quit-hook} and @code{mh-quit-hook} to accomplish that. - -@smalllisp -@group -(defvar my-mh-folder-buffer-to-delete nil - "Folder buffer that is being quit.") - -(defun my-mh-before-quit-hook () - "Save folder buffer that is to be deleted." - (setq my-mh-folder-buffer-to-delete (current-buffer))) - -(defun my-mh-quit-hook () - "Kill folder buffer rather than just bury it." - (set-buffer my-mh-folder-buffer-to-delete) - (if (get-buffer mh-show-buffer) - (kill-buffer mh-show-buffer)) - (kill-buffer (current-buffer))) - -@i{Kill MH-Folder buffer instead of burying it} -@end group -@end smalllisp - -@cindex folders, renaming -@cindex renaming folders -@findex dired -@findex dired-do-rename - -You can use dired to manipulate the folders themselves. For example, I -renamed my @samp{+out} folder to the more common @samp{+outbox} by -running dired on my mail directory (@kbd{M-x dired RET ~/Mail RET}), -moving my cursor to @samp{out} and using the command @kbd{R} -(@code{dired-do-rename}). - -@node Sending Mail, Editing Drafts, Folders, Top -@chapter Sending Mail - -@cindex sending mail -@findex mh-smail -@kindex M-x mh-smail - -You can send a mail message in several ways. You can call @kbd{M-x -mh-smail} directly, or from the command line like this: - -@cindex starting from command line - -@smallexample -$ @kbd{emacs -f mh-smail} -@end smallexample - -@findex goto-address-at-point -@vindex mail-user-agent - -There are some commands that need to send a mail message, such as -@code{goto-address-at-point}. You can configure Emacs to have these -commands use MH-E by setting the option @code{mail-user-agent} to -@samp{Emacs interface to MH}. - -@cindex @samp{Message} menu -@cindex menu, @samp{Message} - -From within MH-E's MH-Folder mode, other methods of sending mail are -available as well. These can also be found in the @samp{Message} menu. - -@table @kbd -@cindex @samp{Message > Edit Message Again} menu item -@cindex menu item, @samp{Message > Edit Message Again} -@kindex e -@findex mh-edit-again -@item e -Edit a message to send it again (@code{mh-edit-again}). -@c ------------------------- -@cindex @samp{Message > Re-edit a Bounced Message} menu item -@cindex menu item, @samp{Message > Re-edit a Bounced Message} -@kindex E -@findex mh-extract-rejected-mail -@item E -Edit a message that was returned by the mail system -(@code{mh-extract-rejected-mail}). -@c ------------------------- -@cindex @samp{Message > Forward Message...} menu item -@cindex menu item, @samp{Message > Forward Message...} -@kindex f -@findex mh-forward -@item f -Forward message (@code{mh-forward}). -@c ------------------------- -@cindex @samp{Message > Reply to Message...} menu item -@cindex menu item, @samp{Message > Reply to Message...} -@kindex r -@findex mh-reply -@item r -Reply to a message (@code{mh-reply}). -@c ------------------------- -@cindex @samp{Message > Compose a New Message} menu item -@cindex menu item, @samp{Message > Compose a New Message} -@kindex s -@findex mh-send -@item s -Compose a message (@code{mh-send}). -@c ------------------------- -@cindex @samp{Message > Redistribute Message...} menu item -@cindex menu item, @samp{Message > Redistribute Message...} -@kindex M-d -@findex mh-redistribute -@item M-d -Redistribute a message (@code{mh-redistribute}). -@c ------------------------- -@findex mh-smail -@item M-x mh-smail -Compose a message with the MH mail system. -@c ------------------------- -@findex mh-smail-other-window -@item M-x mh-smail-other-window -Compose a message with the MH mail system in other window. -@end table - -@cindex @samp{mh-sending-mail} customization group -@cindex customization group, @samp{mh-sending-mail} - -In addition, several options from the @samp{mh-sending-mail} -customization group are useful when sending mail or replying to mail. -They are summarized in the following table. - -@vtable @code -@item mh-compose-forward-as-mime-flag -On means that messages are forwarded as attachments (default: -@samp{on}). -@c ------------------------- -@item mh-compose-letter-function -Hook run when starting a new draft (default: @code{nil}). -@c ------------------------- -@item mh-compose-prompt-flag -On means prompt for header fields when composing a new draft (default: -@samp{off}). -@c ------------------------- -@item mh-forward-subject-format -Format string for forwarded message subject (default: @code{"%s: -%s"}). -@c ------------------------- -@item mh-insert-x-mailer-flag -On means append an @samp{X-Mailer:} header field to the header -(default: @samp{on}). -@c ------------------------- -@item mh-redist-full-contents-flag -On means the @command{dist} command needs entire letter for -redistribution (default: @samp{off}). -@c ------------------------- -@item mh-reply-default-reply-to -Sets the person or persons to whom a reply will be sent (default: -@samp{Prompt}). -@c ------------------------- -@item mh-reply-show-message-flag -On means the MH-Show buffer is displayed using @kbd{r} -(@code{mh-reply}) (default: @samp{on}). -@end vtable - -The following hooks are available. - -@vtable @code -@item mh-annotate-msg-hook -Hook run by @code{mh-annotate-msg} after annotation (default: -@code{nil}). -@c ------------------------- -@item mh-forward-hook -Hook run by @code{mh-forward} on a forwarded letter (default: -@code{nil}). -@c ------------------------- -@item mh-letter-mode-hook -Hook run by @code{mh-letter-mode} on a new letter (default: -@code{nil}). -@end vtable - -@findex mh-annotate-msg -@vindex mh-annotate-list -@vindex mh-annotate-msg-hook -@vindex mh-current-folder - -A hook that is called whenever a message is sent and after the scan -lines and message are annotated is @code{mh-annotate-msg-hook}. Hook -functions can access the current folder name with -@code{mh-current-folder} and obtain the message numbers of the -annotated messages with @code{mh-annotate-list}. - -The rest of the functions and options introduced here are explained in -more detail in the following sections. - -@menu -* Composing:: -* Replying:: -* Forwarding:: -* Redistributing:: -* Editing Again:: -@end menu - -@node Composing, Replying, Sending Mail, Sending Mail -@section Composing - -@cindex @file{.emacs} -@cindex MH-Folder mode -@cindex composing mail -@cindex draft -@cindex files, @file{.emacs} -@cindex modes, MH-Folder -@cindex sending mail -@findex mh-smail -@findex mh-smail-other-window -@kindex M-x mh-smail -@kindex M-x mh-smail-other-window - -Outside of an MH-Folder buffer, you must call either @kbd{M-x -mh-smail} or @kbd{M-x mh-smail-other-window} to compose a new message. -The former command always creates a two-window layout with the current -buffer on top and the draft on the bottom. Use the latter command if -you would rather preserve the window layout. You may find adding the -following key bindings to @file{~/.emacs} useful: - -@smalllisp -(global-set-key "\C-xm" 'mh-smail) -(global-set-key "\C-x4m" 'mh-smail-other-window) -@end smalllisp - -@cindex draft folder -@cindex MH-Letter mode -@cindex modes, MH-Letter -@findex mh-send -@kindex m - -From within a MH-Folder buffer, you can simply use the command @kbd{m} -(@code{mh-send}). However you invoke @code{mh-send}, your letter -appears in an Emacs buffer whose mode is MH-Letter (to see what the -buffer looks like, @pxref{Sending Mail Tour}). MH-Letter mode allows -you to edit your message, to check the validity of the recipients, to -insert attachments and other messages into your message, and to send -the message. We'll go more into depth about editing a -@dfn{draft}@footnote{I highly recommend that you use a @dfn{draft -folder} so that you can edit several drafts in parallel. To do so, -create a folder named @samp{+drafts} for example, and add the profile -component @samp{Draft-Folder: drafts} (see @code{mh-profile}(5)).} (a -message you're composing) in just a moment (@pxref{Editing Drafts}). - -@vindex mh-compose-prompt-flag - -If you prefer to be prompted for the recipient and subject fields -before the MH-Letter buffer appears, turn on the option -@code{mh-compose-prompt-flag}. - -@cindex header field, @samp{X-Mailer:} -@cindex @samp{X-Mailer:} header field -@vindex mh-insert-x-mailer-flag - -MH-E adds an @samp{X-Mailer:} header field to the header that includes -the version of MH-E and Emacs that you are using. If you don't want to -participate in our marketing, you can turn off the option -@code{mh-insert-x-mailer-flag}. - -@cindex @command{repl} -@cindex @file{components} -@cindex MH commands, @command{repl} -@cindex MH-Letter mode -@cindex Mail mode -@cindex files, @file{components} -@cindex modes, MH-Letter -@cindex modes, Mail -@vindex mail-mode-hook -@vindex mh-letter-mode-hook -@vindex text-mode-hook - -Two hooks are provided to run commands on your freshly created draft. -The first hook, @code{mh-letter-mode-hook}, allows you to do some -processing before editing a letter@footnote{Actually, because -MH-Letter mode inherits from Mail mode, the hooks -@code{text-mode-hook} and @code{mail-mode-hook} are run (in that -order) before @code{mh-letter-mode-hook}.}. For example, you may wish -to modify the header after @command{repl} has done its work, or you -may have a complicated @file{components} file and need to tell MH-E -where the cursor should go. Here's an example of how you would use -this hook. - -@findex mh-insert-signature, example - -@smalllisp -@group -(defvar letter-mode-init-done-flag nil - "Non-nil means one-time MH-E settings have been made.") - -(defun my-mh-letter-mode-hook () - "Prepare letter for editing." - (when (not letter-mode-init-done) ; @r{only need to bind the keys once} - (local-set-key "\C-ctb" 'add-enriched-text) - (local-set-key "\C-cti" 'add-enriched-text) - (local-set-key "\C-ctf" 'add-enriched-text) - (local-set-key "\C-cts" 'add-enriched-text) - (local-set-key "\C-ctB" 'add-enriched-text) - (local-set-key "\C-ctu" 'add-enriched-text) - (local-set-key "\C-ctc" 'add-enriched-text) - (setq letter-mode-init-done t)) - (save-excursion - (goto-char (point-max)) ; @r{go to end of message to} - (mh-insert-signature))) ; @r{insert signature} - -@i{Prepare draft for editing via mh-letter-mode-hook} - -@end group -@end smalllisp - -The function, @code{add-enriched-text} is defined in the example in -@ref{Adding Attachments}. - -@vindex mh-compose-letter-function -@vindex mh-letter-mode-hook - -The second hook, a function really, is -@code{mh-compose-letter-function}. Like @code{mh-letter-mode-hook}, it -is called just before editing a new message; however, it is the last -function called before you edit your message. The consequence of this -is that you can write a function to write and send the message for -you. This function is passed three arguments: the contents of the -@samp{To:}, @samp{Subject:}, and @samp{Cc:} header fields. - -@node Replying, Forwarding, Composing, Sending Mail -@section Replying to Mail - -@cindex @command{mhl} -@cindex @file{mhl.reply} -@cindex MH commands, @command{mhl} -@cindex files, @file{mhl.reply} -@cindex replying -@findex mh-reply -@kindex r - -To compose a reply to a message, use the @kbd{r} (@code{mh-reply}) -command. - -When you reply to a message, you are first prompted with @samp{Reply -to whom?}. You have several choices here. - -@quotation -@multitable @columnfractions .20 .80 -@c @headitem Response @tab Reply Goes To -@c XXX @headitem not yet supported by SourceForge's texi2pdf. -@item @b{Response} @tab @b{Reply Goes To} -@c ------------------------- -@item @kbd{from} -@tab -The person who sent the message. This is the default, so @key{RET} is -sufficient. -@c ------------------------- -@item @kbd{to} -@tab -Replies to the sender, plus all recipients in the @samp{To:} header field. -@c ------------------------- -@item @kbd{cc}@*@kbd{all} -@tab -Forms a reply to the addresses in the @samp{Mail-Followup-To:} header -field if one exists; otherwise forms a reply to the sender, plus all -recipients. -@end multitable -@end quotation - -@cindex @command{repl} -@cindex MH commands, @command{repl} -@vindex mh-reply-default-reply-to - -Depending on your answer, @command{repl}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/reprep.html, Replying to Messages: repl} in -the MH book.} is given a different argument to form your reply. -Specifically, a choice of @kbd{from} or none at all runs @samp{repl --nocc all}, and a choice of @kbd{to} runs @samp{repl -cc to}. Finally, -either @kbd{cc} or @kbd{all} runs @samp{repl -cc all -nocc me}. If you -find that most of the time you specify one of these choices when you -reply to a message, you can change the option -@code{mh-reply-default-reply-to} from its default value of -@samp{Prompt} to one of the choices listed above. You can always edit -the recipients in the draft. - -@cindex @samp{repl:} MH profile component -@cindex MH profile component, @samp{repl:} -@cindex MH-Letter mode -@cindex MH-Show mode -@cindex draft -@cindex modes, MH-Letter -@cindex modes, MH-Show - -Two windows are then created. One window contains the message to which -you are replying in an MH-Show buffer. Your draft, in MH-Letter mode -(@pxref{Editing Drafts}), is in the other window. If the reply draft -was not one that you expected, check the things that affect the -behavior of @command{repl} which include the @samp{repl:} profile -component and the @file{replcomps} and @file{replgroupcomps} files. - -If you supply a prefix argument (as in @kbd{C-u r}), the message you -are replying to is inserted in your reply after having first been run -through @command{mhl} with the format file @file{mhl.reply}. See -@command{mhl}(1) or the section -@uref{@value{MH-BOOK-HOME}/shomes.html#Usisho, Using mhl} in the MH -book to see how you can modify the default @file{mhl.reply} file. - -@vindex mh-yank-behavior - -Alternatively, you can customize the option @code{mh-yank-behavior} -and choose one of its @samp{Automatically} variants to do the same -thing. @xref{Inserting Letter}. If you do so, the prefix argument has -no effect. - -Another way to include the message automatically in your draft is to -use @samp{repl: -filter repl.filter} in your MH profile. - -@vindex mh-reply-show-message-flag - -If you include the message automatically, you can hide the MH-Show -buffer by turning off the option @code{mh-reply-show-message-flag}. - -If you wish to customize the header or other parts of the reply draft, -please see @command{repl}(1) and @code{mh-format}(5). - -@node Forwarding, Redistributing, Replying, Sending Mail -@section Forwarding Mail - -@cindex @command{forw} -@cindex draft -@cindex forwarding -@cindex MH commands, @command{forw} -@findex mh-forward -@kindex f -@vindex mh-forward-hook - -To forward a message, use the @kbd{f} (@code{mh-forward}) command. You -are prompted for the @samp{To:} and @samp{cc:} recipients. You are -given a draft to edit that looks like it would if you had run the MH -command @command{forw}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/forfor.html, Forwarding Messages: forw} in -the MH book.}. You can then add some text (@pxref{Editing Drafts}). -You can forward several messages by using a range (@pxref{Ranges}). -All of the messages in the range are inserted into your draft. The -hook @code{mh-forward-hook} is called on the draft. - -@cindex @file{.mh_profile} -@cindex files, @file{.mh_profile} -@cindex MH profile component, @samp{forw:} -@cindex @samp{forw:} MH profile component -@vindex mh-compose-forward-as-mime-flag - -By default, the option @code{mh-compose-forward-as-mime-flag} is on -which means that the forwarded messages are included as attachments. -These are inline attachments so the forwarded message should appear in -the body of your recipient's mail program. If you would prefer to -forward your messages verbatim (as text, inline), then turn off this -option. Forwarding messages verbatim works well for short, textual -messages, but your recipient won't be able to view any non-textual -attachments that were in the forwarded message. Be aware that if you -have @samp{forw: -mime} in your MH profile, then forwarded messages -will always be included as attachments regardless of the settings of -@code{mh-compose-forward-as-mime-flag}. - -@vindex mh-forward-subject-format - -The format of the @samp{Subject:} header field for forwarded messages -is controlled by the option @code{mh-forward-subject-format}. This -option is a string which includes two escapes (@samp{%s}). The first -@samp{%s} is replaced with the sender of the original message, and the -second one is replaced with the original @samp{Subject:}. The default -value of @code{"%s: %s"} takes a message with the header: - -@smallexample -@group -To: Bill Wohler -Subject: Re: 49er football -From: Greg DesBrisay -@end group -@end smallexample - -and creates a subject header field of: - -@smallexample -Subject: Greg DesBrisay: Re: 49er football -@end smallexample - -@node Redistributing, Editing Again, Forwarding, Sending Mail -@section Redistributing Your Mail - -@cindex @command{dist} -@cindex MH commands, @command{dist} -@cindex redistributing -@findex mh-redistribute -@kindex M-d - -The command @kbd{M-d} (@code{mh-redistribute}) is similar in function -to forwarding mail, but it does not allow you to edit the message, nor -does it add your name to the @samp{From:} header field. It appears to -the recipient as if the message had come from the original sender. -When you run this command, you are prompted for the recipients. - -@findex mh-edit-again -@kindex e - -For more information on redistributing messages, see -@command{dist}(1). Also investigate the command @kbd{e} -(@code{mh-edit-again}) for another way to redistribute messages -(@pxref{Editing Again}). - -@cindex @command{send} -@cindex MH commands, @command{send} -@vindex mh-redist-full-contents-flag - -The option @code{mh-redist-full-contents-flag} must be turned on if -@command{dist}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/disdis.html, Distributing Messages with -dist} in the MH book.} requires the whole letter for redistribution, -which is the case if @command{send}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/sensen.html, Sending Some Mail: comp send} -in the MH book.} is compiled with the @sc{berk} option (which many -people abhor). If you find that MH will not allow you to redistribute -a message that has been redistributed before, turn off this option. - -The hook @code{mh-annotate-msg-hook} is run after annotating the -message and scan line (@pxref{Sending Mail}). - -@node Editing Again, , Redistributing, Sending Mail -@section Editing Old Drafts and Bounced Messages - -@cindex @file{draft} -@cindex files, @file{draft} -@cindex re-editing drafts -@findex mh-edit-again -@kindex F v drafts -@kindex e -@kindex n - -If you don't complete a draft for one reason or another, and if the -draft buffer is no longer available, you can pick your draft up again -with @kbd{e} (@code{mh-edit-again}). If you don't use a draft -folder, your last @file{draft} file will be used. If you use draft -folders, you'll need to visit the draft folder with @kbd{F v drafts -@key{RET}}, use @kbd{n} to move to the appropriate message, and then -use @kbd{e} to prepare the message for editing. - -@kindex e - -The @kbd{e} command can also be used to take messages that were sent -to you and to send them to more people. - -@cindex Mailer-Daemon -@findex mh-extract-rejected-mail -@kindex C-c C-c -@kindex E - -Don't use @kbd{e} to re-edit a message from a @i{Mailer-Daemon} who -complained that your mail wasn't posted for some reason or another. In -this case, use @kbd{E} (@code{mh-extract-rejected-mail}) to prepare -the message for editing by removing the @i{Mailer-Daemon} envelope and -unneeded header fields. Fix whatever addressing problem you had, and -send the message again with @kbd{C-c C-c}. - -@node Editing Drafts, Aliases, Sending Mail, Top -@chapter Editing a Draft - -@cindex @samp{Letter} menu -@cindex MH-Letter mode -@cindex draft -@cindex editing draft -@cindex menu, @samp{Letter} -@cindex modes, MH-Letter - -When you edit a message that you want to send (called a @dfn{draft} in -this case), the mode used is MH-Letter. This mode provides several -commands in addition to the normal Emacs editing commands to help you -edit your draft. These can also be found in the @samp{Letter} menu. - -@table @kbd -@kindex @key{SPC} -@findex mh-letter-complete-or-space -@item @key{SPC} -Perform completion or insert space (@code{mh-letter-complete-or-space}). -@c ------------------------- -@kindex M-@key{TAB} -@findex mh-letter-complete -@item M-@key{TAB} -Perform completion on header field or word preceding point -(@code{mh-letter-complete}). -@c ------------------------- -@kindex , (comma) -@findex mh-letter-confirm-address -@item , (comma) -Flash alias expansion (@code{mh-letter-confirm-address}). -@c ------------------------- -@kindex @key{TAB} -@findex mh-letter-next-header-field-or-indent -@item @key{TAB} -Cycle to next field (@code{mh-letter-next-header-field-or-indent}). -@c ------------------------- -@kindex S-@key{TAB} -@findex mh-letter-previous-header-field -@item S-@key{TAB} -Cycle to the previous header field -(@code{mh-letter-previous-header-field}). -@c ------------------------- -@kindex C-c ? -@findex mh-help -@item C-c ? -Display cheat sheet for the MH-E commands (@code{mh-help}). -@c ------------------------- -@cindex @samp{Letter > Send This Draft} menu item -@cindex menu item, @samp{Letter > Send This Draft} -@kindex C-c C-c -@findex mh-send-letter -@item C-c C-c -Save draft and send message (@code{mh-send-letter}). -@c ------------------------- -@kindex C-c C-d -@findex mh-insert-identity -@item C-c C-d -Insert fields specified by the given identity -(@code{mh-insert-identity}). @xref{Identities}. -@c ------------------------- -@cindex @samp{Letter > Pull in All Compositions (MH)} menu item -@cindex menu item, @samp{Letter > Pull in All Compositions (MH)} -@kindex C-c C-e -@findex mh-mh-to-mime -@item C-c C-e -Compose @sc{mime} message from MH-style directives -(@code{mh-mh-to-mime}). -@c ------------------------- -@kindex C-c C-f C-a -@kindex C-c C-f a -@findex mh-to-field -@item C-c C-f C-a -@itemx C-c C-f a -Move to @samp{Mail-Reply-To:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-b -@kindex C-c C-f b -@item C-c C-f C-b -@itemx C-c C-f b -Move to @samp{Bcc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-c -@kindex C-c C-f c -@item C-c C-f C-c -@itemx C-c C-f c -Move to @samp{Cc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-d -@kindex C-c C-f d -@item C-c C-f C-d -@itemx C-c C-f d -Move to @samp{Dcc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-f -@kindex C-c C-f f -@findex mh-to-fcc -@item C-c C-f C-f -@itemx C-c C-f f -Move to @samp{Fcc:} header field (@code{mh-to-fcc}). -@c ------------------------- -@kindex C-c C-f C-l -@kindex C-c C-f l -@item C-c C-f C-l -@itemx C-c C-f l -Move to @samp{Mail-Followup-To:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-m -@kindex C-c C-f m -@item C-c C-f C-m -@itemx C-c C-f m -Move to @samp{From:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-r -@kindex C-c C-f r -@item C-c C-f C-r -@itemx C-c C-f r -Move to @samp{Reply-To:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-s -@kindex C-c C-f s -@item C-c C-f C-s -@itemx C-c C-f s -Move to @samp{Subject:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-t -@kindex C-c C-f t -@item C-c C-f C-t -@itemx C-c C-f t -Move to @samp{To:} header field (@code{mh-to-field}). -@c ------------------------- -@cindex @samp{Letter > Insert a Message...} menu item -@cindex menu item, @samp{Letter > Insert a Message...} -@kindex C-c C-i -@findex mh-insert-letter -@item C-c C-i -Insert a message (@code{mh-insert-letter}). -@c ------------------------- -@kindex C-c C-m C-e -@findex mh-mml-secure-message-encrypt -@item C-c C-m C-e -Add tag to encrypt the message (@code{mh-mml-secure-message-encrypt}). -@c ------------------------- -@cindex @samp{Letter > Compose Forward...} menu item -@cindex menu item, @samp{Letter > Compose Forward...} -@kindex C-c C-m C-f -@kindex C-c C-m f -@findex mh-compose-forward -@item C-c C-m C-f -@itemx C-c C-m f -Add tag to forward a message (@code{mh-compose-forward}). -@c ------------------------- -@cindex @samp{Letter > Compose Get File (MH)...} menu item -@cindex menu item, @samp{Letter > Compose Get File (MH)...} -@kindex C-c C-m C-g -@kindex C-c C-m g -@findex mh-mh-compose-anon-ftp -@item C-c C-m C-g -@itemx C-c C-m g -Add tag to include anonymous ftp reference to a file -(@code{mh-mh-compose-anon-ftp}). -@c ------------------------- -@cindex @samp{Letter > Compose Insertion...} menu item -@cindex menu item, @samp{Letter > Compose Insertion...} -@kindex C-c C-m C-i -@kindex C-c C-m i -@findex mh-compose-insertion -@item C-c C-m C-i -@itemx C-c C-m i -Add tag to include a file such as an image or sound -(@code{mh-compose-insertion}). -@c ------------------------- -@cindex @samp{Letter > Pull in All Compositions (MML)} menu item -@cindex menu item, @samp{Letter > Pull in All Compositions (MML)} -@kindex C-c C-m C-m -@kindex C-c C-m m -@findex mh-mml-to-mime -@item C-c C-m C-m -@itemx C-c C-m m -Compose @sc{mime} message from MML tags (@code{mh-mml-to-mime}). -@c ------------------------- -@kindex C-c C-m C-n -@kindex C-c C-m n -@findex mh-mml-unsecure-message -@item C-c C-m C-n -@itemx C-c C-m n -Remove any secure message tags (@code{mh-mml-unsecure-message}). -@c ------------------------- -@kindex C-c C-m C-s -@findex mh-mml-secure-message-sign -@item C-c C-m C-s -Add tag to sign the message (@code{mh-mml-secure-message-sign}). -@c ------------------------- -@cindex @samp{Letter > Compose Compressed tar (MH)...} menu item -@cindex menu item, @samp{Letter > Compose Compressed tar (MH)...} -@kindex C-c C-m C-t -@kindex C-c C-m t -@findex mh-mh-compose-external-compressed-tar -@item C-c C-m C-t -@itemx C-c C-m t -Add tag to include anonymous ftp reference to a compressed tar file -(@code{mh-mh-compose-external-compressed-tar}). -@c ------------------------- -@cindex @samp{Letter > Revert to Non-MIME Edit (MH)} menu item -@cindex menu item, @samp{Letter > Revert to Non-MIME Edit (MH)} -@kindex C-c C-m C-u -@kindex C-c C-m u -@findex mh-mh-to-mime-undo -@item C-c C-m C-u -@itemx C-c C-m u -Undo effects of @kbd{C-c C-e} (@code{mh-mh-to-mime-undo}). -@c ------------------------- -@kindex C-c C-m C-x -@kindex C-c C-m x -@findex mh-mh-compose-external-type -@item C-c C-m C-x -@itemx C-c C-m x -Add tag to refer to a remote file -(@code{mh-mh-compose-external-type}). -@c ------------------------- -@kindex C-c C-m e e -@findex mh-mml-secure-message-encrypt -@item C-c C-m e e -Add tag to encrypt the message (@code{mh-mml-secure-message-encrypt}). -@c ------------------------- -@kindex C-c C-m e s -@findex mh-mml-secure-message-signencrypt -@item C-c C-m e s -Add tag to encrypt and sign the message@* -(@code{mh-mml-secure-message-signencrypt}). -@c ------------------------- -@kindex C-c C-m s e -@findex mh-mml-secure-message-signencrypt -@item C-c C-m s e -Add tag to encrypt and sign the message@* -(@code{mh-mml-secure-message-signencrypt}). -@c ------------------------- -@kindex C-c C-m s s -@findex mh-mml-secure-message-sign -@item C-c C-m s s -Add tag to sign the message (@code{mh-mml-secure-message-sign}). -@c ------------------------- -@cindex @samp{Letter > Split Current Line} menu item -@cindex menu item, @samp{Letter > Split Current Line} -@kindex C-c C-o -@findex mh-open-line -@item C-c C-o -Insert a newline and leave point before it (@code{mh-open-line}). -@c ------------------------- -@cindex @samp{Letter > Kill This Draft} menu item -@cindex menu item, @samp{Letter > Kill This Draft} -@kindex C-c C-q -@findex mh-fully-kill-draft -@item C-c C-q -Quit editing and delete draft message (@code{mh-fully-kill-draft}). -@c ------------------------- -@cindex @samp{Letter > Insert Signature} menu item -@cindex menu item, @samp{Letter > Insert Signature} -@kindex C-c C-s -@findex mh-insert-signature -@item C-c C-s -Insert signature in message (@code{mh-insert-signature}). -@c ------------------------- -@kindex C-c C-t -@findex mh-letter-toggle-header-field-display -@item C-c C-t -Toggle display of header field at point -(@code{mh-letter-toggle-header-field-display}). -@c ------------------------- -@cindex @samp{Letter > Check Recipient} menu item -@cindex menu item, @samp{Letter > Check Recipient} -@kindex C-c C-w -@findex mh-check-whom -@item C-c C-w -Verify recipients, showing expansion of any aliases -(@code{mh-check-whom}). -@c ------------------------- -@cindex @samp{Letter > Yank Current Message} menu item -@cindex menu item, @samp{Letter > Yank Current Message} -@kindex C-c C-y -@findex mh-yank-cur-msg -@item C-c C-y -Insert the current message into the draft buffer -(@code{mh-yank-cur-msg}). -@c ------------------------- -@kindex C-c M-d -@findex mh-insert-auto-fields -@item C-c M-d -Insert custom fields if recipient is found in -@code{mh-auto-fields-list} (@code{mh-insert-auto-fields}). -@xref{Identities}. -@end table - -@cindex @samp{mh-letter} customization group -@cindex customization group, @samp{mh-letter} - -Several options from the @samp{mh-letter} customization group are used -while editing a draft. - -@vtable @code -@item mh-compose-insertion -Type of @sc{mime} message tags in messages (default: @samp{MML} if -available; otherwise @samp{MH}). -@c ------------------------- -@item mh-compose-skipped-header-fields -List of header fields to skip over when navigating in draft (default: -@code{'("From"} @code{"Organization"} @code{"References"} -@code{"In-Reply-To"} @code{"X-Face"} @code{"Face"} -@code{"X-Image-URL"} @code{"X-Mailer")}. -@c ------------------------- -@item mh-compose-space-does-completion-flag -On means @key{SPC} does completion in message header (default: -@samp{off}). -@c ------------------------- -@item mh-delete-yanked-msg-window-flag -On means delete any window displaying the message (default: @samp{off}). -@c ------------------------- -@item mh-extract-from-attribution-verb -Verb to use for attribution when a message is yanked by @kbd{C-c C-y} -(default: @code{"wrote:"}). -@c ------------------------- -@item mh-ins-buf-prefix -String to put before each line of a yanked or inserted message -(default: @code{"> "}). -@c ------------------------- -@item mh-letter-complete-function -Function to call when completing outside of address or folder fields -(default: @code{ispell-complete-word}). -@c ------------------------- -@item mh-letter-fill-column -Fill column to use in MH-Letter mode (default: 72). -@c ------------------------- -@item mh-mml-method-default -Default method to use in security tags (default: @samp{PGP (MIME)} if -support for it is available; otherwise @samp{None}). -@c ------------------------- -@item mh-signature-file-name -Source of user's signature (default: @code{"~/.signature"}). -@c ------------------------- -@item mh-signature-separator-flag -On means a signature separator should be inserted (default: -@samp{on}). -@c ------------------------- -@item mh-x-face-file -File containing X-Face or Face header field to insert in outgoing mail. -(default: @code{"~/.face"}). -@c ------------------------- -@item mh-yank-behavior -Controls which part of a message is yanked by @kbd{C-c C-y} (default: -@samp{Body With Attribution}). -@end vtable - -The following hooks are available. - -@vtable @code -@item mail-citation-hook -Hook for modifying a citation just inserted in the mail buffer -(default: @code{nil}). -@c ------------------------- -@item mh-before-send-letter-hook -Hook run at the beginning of the @kbd{C-c C-c} command (default: -@samp{nil}). -@c ------------------------- -@item mh-mh-to-mime-hook -Hook run on the formatted letter by @kbd{C-c C-e} (default: -@samp{nil}). -@c ------------------------- -@item mh-insert-signature-hook -Hook run by @kbd{C-c C-s} after signature has been inserted (default: -@code{nil}). -@end vtable - -The following face is available. - -@vtable @code -@item mh-letter-header-field -Editable header field value face in draft buffers. -@end vtable - -The commands and options introduced here are explained in more -detail in the following sections. - -@menu -* Editing Message:: -* Inserting Letter:: -* Inserting Messages:: -* Signature:: -* Picture:: -* Adding Attachments:: -* Sending PGP:: -* Checking Recipients:: -* Sending Message:: -* Killing Draft:: -@end menu - -@node Editing Message, Inserting Letter, Editing Drafts, Editing Drafts -@section Editing the Message - -@cindex @samp{Bcc:} header field -@cindex @samp{Cc:} header field -@cindex @samp{Dcc:} header field -@cindex @samp{From:} header field -@cindex @samp{Mail-Followup-To:} header field -@cindex @samp{Mail-Reply-To:} header field -@cindex @samp{Reply-To:} header field -@cindex @samp{Subject:} header field -@cindex @samp{To:} header field -@cindex editing header -@cindex header field, @samp{Bcc:} -@cindex header field, @samp{Cc:} -@cindex header field, @samp{Dcc:} -@cindex header field, @samp{From:} -@cindex header field, @samp{Mail-Followup-To:} -@cindex header field, @samp{Mail-Reply-To:} -@cindex header field, @samp{Reply-To:} -@cindex header field, @samp{Subject:} -@cindex header field, @samp{To:} -@findex mh-to-field -@kindex C-c C-f C-t -@kindex C-c C-f t - -Because the header is part of the message, you can edit the header -fields as you wish. However, several convenience commands exist to -help you create and edit them. For example, the command @kbd{C-c C-f -C-t} (@code{mh-to-field}; alternatively, @kbd{C-c C-f t}) moves the -cursor to the @samp{To:} header field, creating it if necessary. The -commands for moving to the @samp{Cc:}, @samp{Subject:}, @samp{From:}, -@samp{Reply-To:}, @samp{Mail-Reply-To:}, @samp{Mail-Followup-To}, -@samp{Bcc:}, and @samp{Dcc:} header fields are similar. - -@findex mh-to-fcc -@kindex C-c C-f C-f -@kindex C-c C-f f - -One command behaves differently from the others, namely, @kbd{C-c C-f -C-f} (@code{mh-to-fcc}; alternatively, @kbd{C-c C-f f}). This command -will prompt you for the folder name in which to file a copy of the -draft. @xref{Folder Selection}. - -@findex indent-relative -@findex mh-letter-next-header-field-or-indent -@findex mh-letter-previous-header-field -@kindex @key{TAB} -@kindex S-@key{TAB} -@vindex mh-compose-skipped-header-fields -@vindex mh-letter-header-field - -Within the header of the message, the command@* @key{TAB} -(@code{mh-letter-next-header-field-or-indent}) moves between fields -that are highlighted with the face @code{mh-letter-header-field}, -skipping those fields listed in -@code{mh-compose-skipped-header-fields}. After the last field, this -command then moves point to the message body before cycling back to -the first field. If point is already past the first line of the -message body, then this command indents by calling -@code{indent-relative} with the given prefix argument. The command -@kbd{S-@key{TAB}} (@code{mh-letter-previous-header-field}) moves -backwards between the fields and cycles to the body of the message -after the first field. Unlike the command @key{TAB}, it will always -take point to the last field from anywhere in the body. - -@cindex alias completion -@cindex completion -@cindex spell check -@findex ispell-complete-word -@findex mh-letter-complete -@findex mh-letter-complete-or-space -@findex mh-letter-confirm-address -@kindex , (comma) -@kindex @key{SPC} -@kindex M-@key{TAB} -@vindex mh-alias-flash-on-comma -@vindex mh-compose-space-does-completion-flag -@vindex mh-letter-complete-function - -If the field contains addresses (for example, @samp{To:} or -@samp{Cc:}) or folders (for example, @samp{Fcc:}) then the command -@kbd{M-@key{TAB}} (@code{mh-letter-complete}) will provide alias -completion (@pxref{Aliases}). In the body of the message, -@kbd{M-@key{TAB}} runs @code{mh-letter-complete-function} instead, -which is set to @samp{'ispell-complete-word} by default. The command -@kbd{M-@key{TAB}} (@code{mh-letter-complete}) takes a prefix argument -that is passed to the @code{mh-letter-complete-function}. In addition, -turn on the option @code{mh-compose-space-does-completion-flag} to use -the command @key{SPC} (@code{mh-letter-complete-or-space}) to perform -completion in the header as well; use a prefix argument to specify -more than one space. Addresses are separated by a comma; when you -press the comma, the command @code{mh-letter-confirm-address} flashes -the alias expansion in the minibuffer if -@code{mh-alias-flash-on-comma} is turned on. - -@c XXX Document the replacement for the inaccessible 'long argument. - -@findex mh-letter-toggle-header-field-display -@kindex C-c C-t - -Use the command @kbd{C-c C-t} -@code{mh-letter-toggle-header-field-display} to display truncated -header fields. This command is a toggle so entering it again will hide -the field. This command takes a prefix argument: if negative then the -field is hidden, if positive then the field is displayed (for example, -@kbd{C-u C-c C-t}). - -Be sure to leave a row of dashes or a blank line between the header -and the body of the message. - -@vindex mh-letter-fill-column - -The body of the message is edited as you would edit any Emacs buffer -although there are a few commands and options to assist you. You can -change the fill column in MH-Letter mode with the option -@code{mh-letter-fill-column}. By default, this option is 72 to allow -others to quote your message without line wrapping. - -@cindex filling paragraphs -@cindex paragraphs, filling -@findex fill-paragraph -@kindex M-q -@vindex mh-ins-buf-prefix - -You'll often include messages that were sent from user agents that -haven't yet realized that paragraphs consist of more than a single -line. This makes for long lines that wrap in an ugly fashion. You'll -find that @kbd{M-q} (@code{fill-paragraph}) works well even on these -quoted messages, even if they are nested, just as long as all of the -quotes match the value of @code{mh-ins-buf-prefix} (@pxref{Inserting -Letter}). For example, let's assume you have the following in your -draft: - -@smallexample -@group -> Hopefully this gives you an idea of what I'm currently doing. I'm \ -not sure yet whether I'm completely satisfied with my setup, but \ -it's worked okay for me so far. -@end group -@end smallexample - -Running @kbd{M-q} on this paragraph produces: - -@smallexample -@group -> Hopefully this gives you an idea of what I'm currently doing. I'm not -> sure yet whether I'm completely satisfied with my setup, but it's -> worked okay for me so far. -@end group -@end smallexample - -@findex mh-open-line -@findex open-line -@kindex C-c C-o -@kindex C-o - -The command @kbd{C-c C-o} (@code{mh-open-line}) is similar to the -command @kbd{C-o} (@code{open-line}) in that it inserts a newline -after point. It differs in that it also inserts the right number of -quoting characters and spaces so that the next line begins in the same -column as it was. This is useful when breaking up paragraphs in -replies. For example, if this command was used when point was after -the first period in the paragraph above, the result would be this: - -@smallexample -@group -> Hopefully this gives you an idea of what I'm currently doing. - -> I'm not -> sure yet whether I'm completely satisfied with my setup, but it's -> worked okay for me so far. -@end group -@end smallexample - -@node Inserting Letter, Inserting Messages, Editing Message, Editing Drafts -@section Inserting Letter to Which You're Replying - -@cindex inserting messages -@cindex replying to messages -@cindex yanking messages -@findex mh-yank-cur-msg -@kindex C-c C-y -@vindex mh-ins-buf-prefix - -It is often useful to insert a snippet of text from a letter that -someone mailed to provide some context for your reply. The command -@kbd{C-c C-y} (@code{mh-yank-cur-msg}) does this by adding an -attribution, yanking a portion of text from the message to which -you're replying, and inserting @code{mh-ins-buf-prefix} (@samp{> }) -before each line. - -@smallexample -@group -Michael W Thelen wrote: - -> Hopefully this gives you an idea of what I'm currently doing. I'm not -> sure yet whether I'm completely satisfied with my setup, but it's -> worked okay for me so far. -@end group -@end smallexample - -@vindex mh-extract-from-attribution-verb - -The attribution consists of the sender's name and email address -followed by the content of the option -@code{mh-extract-from-attribution-verb}. This option can be set to -@samp{wrote:}, @samp{a écrit:}, and @samp{schrieb:}. You can also use -the @samp{Custom String} menu item to enter your own verb. - -@vindex mail-citation-hook -@vindex mh-ins-buf-prefix -@vindex mh-yank-behavior - -The prefix @code{"> "} is the default setting for the option -@code{mh-ins-buf-prefix}. I suggest that you not modify this option -since it is used by many mailers and news readers: messages are far -easier to read if several included messages have all been indented by -the same string. This prefix is not inserted if you use one of the -supercite flavors of @code{mh-yank-behavior} or you have added a -@code{mail-citation-hook} as described below. - -@vindex mh-delete-yanked-msg-window-flag - -You can also turn on the @code{mh-delete-yanked-msg-window-flag} -option to delete the window containing the original message after -yanking it to make more room on your screen for your reply. - -@cindex Emacs, packages, supercite -@cindex supercite package -@kindex r -@vindex mail-citation-hook -@vindex mh-yank-behavior - -You can control how the message to which you are replying is yanked -into your reply using @code{mh-yank-behavior}. To include the entire -message, including the entire header, use @samp{Body and -Header}@footnote{If you'd rather have the header cleaned up, use -@kbd{C-u r} instead of @kbd{r} when replying -(@pxref{Replying}).}@footnote{In the past you would use this setting -and set @code{mail-citation-hook} to @samp{supercite}, but this usage -is now deprecated in favor of the @samp{Invoke supercite} setting.}. -Use @samp{Body} to yank just the body without the header. To yank only -the portion of the message following the point, set this option to -@samp{Below Point}. - -Choose @samp{Invoke supercite}@footnote{@emph{Supercite} is a -full-bodied, full-featured, citation package that comes standard with -Emacs.} to pass the entire message and header through supercite. - -@vindex mh-extract-from-attribution-verb - -If the @samp{Body With Attribution} setting is used, then the message -minus the header is yanked and a simple attribution line is added at -the top using the value of the option -@code{mh-extract-from-attribution-verb}. This is the default. - -@kindex C-c C-y -@vindex mh-delete-yanked-msg-window-flag - -If the @samp{Invoke supercite} or @samp{Body With Attribution} -settings are used, the @samp{-noformat} argument is passed to the -@command{repl} program to override a @samp{-filter} or @samp{-format} -argument. These settings also have @samp{Automatically} variants that -perform the action automatically when you reply so that you don't need -to use @kbd{C-c C-y} at all. Note that this automatic action is only -performed if the show buffer matches the message being replied to. -People who use the automatic variants tend to turn on the option -@code{mh-delete-yanked-msg-window-flag} as well so that the show -window is never displayed. - -@vindex mh-yank-behavior - -If the show buffer has a region, the option @code{mh-yank-behavior} is -ignored unless its value is one of @samp{Attribution} variants in -which case the attribution is added to the yanked region. - -@findex trivial-cite -@vindex mail-citation-hook -@vindex mh-ins-buf-prefix -@vindex mh-yank-behavior - -If this isn't enough, you can gain full control over the appearance of -the included text by setting @code{mail-citation-hook} to a function -that modifies it. This hook is ignored if the option -@code{mh-yank-behavior} is set to one of the supercite flavors. -Otherwise, this option controls how much of the message is passed to -the hook. The function can find the citation between point and mark -and it should leave point and mark around the modified citation text -for the next hook function. The standard prefix -@code{mh-ins-buf-prefix} is not added if this hook is set. - -@cindex Emacs, packages, trivial-cite -@cindex trivial-cite package -@vindex mh-yank-behavior - -For example, if you use the hook function -@uref{http://shasta.cs.uiuc.edu/~lrclause/tc.html, -@code{trivial-cite}} (which is NOT part of Emacs), set -@code{mh-yank-behavior} to @samp{Body and Header}. - -@node Inserting Messages, Signature, Inserting Letter, Editing Drafts -@section Inserting Messages - -@cindex inserting messages -@findex mh-insert-letter -@findex mh-yank-behavior -@kindex C-c C-i -@vindex mh-ins-buf-prefix -@vindex mh-invisible-header-fields-compiled -@vindex mh-yank-behavior - -Messages can be inserted with @kbd{C-c C-i} (@code{mh-insert-letter}). -This command prompts you for the folder and message number, which -defaults to the current message in that folder. It then inserts the -messages, indented by @code{mh-ins-buf-prefix} (@samp{> }) unless -@code{mh-yank-behavior} is set to one of the supercite flavors in -which case supercite is used to format the message. Certain -undesirable header fields (see -@code{mh-invisible-header-fields-compiled}) are removed before -insertion. - -If given a prefix argument (like @kbd{C-u C-c C-i}), the header is -left intact, the message is not indented, and @samp{> } is not -inserted before each line. This command leaves the mark before the -letter and point after it. - -@node Signature, Picture, Inserting Messages, Editing Drafts -@section Inserting Your Signature - -@cindex signature -@findex mh-insert-signature -@kindex C-c C-s - -You can insert your signature at the current cursor location with the -command @kbd{C-c C-s} (@code{mh-insert-signature}). - -@cindex files, @file{.signature} -@cindex @file{.signature} -@cindex vCard -@vindex mh-signature-file-name - -By default, the text of your signature is taken from the file -@file{~/.signature}. You can read from other sources by changing the -option @code{mh-signature-file-name}. This file may contain a -@dfn{vCard} in which case an attachment is added with the vCard. - -@findex mh-signature-separator-p -@vindex mh-signature-file-name -@vindex mh-signature-separator -@vindex mh-signature-separator-regexp - -The option @code{mh-signature-file-name} may also be a symbol, in -which case that function is called. You may not want a signature -separator to be added for you; instead you may want to insert one -yourself. Options that you may find useful to do this include -@code{mh-signature-separator} (when inserting a signature separator) -and @code{mh-signature-separator-regexp} (for finding said separator). -The function @code{mh-signature-separator-p}, which reports @code{t} -if the buffer contains a separator, may be useful as well. - -@cindex signature separator -@vindex mh-signature-separator-flag - -A signature separator (@code{"-- "}) will be added if the signature -block does not contain one and @code{mh-signature-separator-flag} is -on. It is not recommended that you change this option since various -mail user agents, including MH-E, use the separator to present the -signature differently, and to suppress the signature when replying or -yanking a letter into a draft. - -@vindex mh-insert-signature-hook -@vindex mh-signature-file-name - -The hook @code{mh-insert-signature-hook} is run after the signature is -inserted. Hook functions may access the actual name of the file or the -function used to insert the signature with -@code{mh-signature-file-name}. - -The signature can also be inserted using Identities. -@xref{Identities}. - -@node Picture, Adding Attachments, Signature, Editing Drafts -@section Inserting Your Picture - -@cindex @file{.face} -@cindex files, @file{.face} -@vindex mh-x-face-file - -You can insert your picture in the header of your mail message so that -recipients see your face in the @samp{From:} header field if their -mail user agent is sophisticated enough. In MH-E, this is done by -placing your image in the file named by the option -@code{mh-x-face-file} which is @file{~/.face} by default. - -@cindex @samp{Face:} header field -@cindex @samp{X-Face:} header field -@cindex @samp{X-Image-URL:} header field -@cindex header field, @samp{Face:} -@cindex header field, @samp{X-Face:} -@cindex header field, @samp{X-Image-URL:} - -If the file starts with either of the strings @samp{X-Face:}, -@samp{Face:} or @samp{X-Image-URL:} then the contents are added to the -message header verbatim. Otherwise it is assumed that the file -contains the value of the @samp{X-Face:} header field. - -@cindex @command{compface} -@cindex Unix commands, @command{compface} - -The @samp{X-Face:} header field, which is a low-resolution, black and -white image, can be generated using the -@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z, -@command{compface}} command. The @uref{http://www.dairiki.org/xface/, -@cite{Online X-Face Converter}} is a useful resource for quick -conversion of images into @samp{X-Face:} header fields. - -Use the @uref{http://quimby.gnus.org/circus/face/make-face, -@command{make-face}} script to convert a JPEG image to the higher -resolution, color, @samp{Face:} header field. - -The URL of any image can be used for the @samp{X-Image-URL:} field and -no processing of the image is required. - -@vindex mh-x-face-file - -To prevent the setting of any of these header fields, either set -@code{mh-x-face-file} to @code{nil}, or simply ensure that the file -defined by this option doesn't exist. - -@xref{Viewing}, to see how these header fields are displayed in MH-E. - -@node Adding Attachments, Sending PGP, Picture, Editing Drafts -@section Adding Attachments - -@cindex @command{mhbuild} -@cindex @command{mhn} -@cindex MH commands, @command{mhbuild} -@cindex MH commands, @command{mhn} -@cindex MIME -@cindex multimedia mail - -MH-E has the capability to create multimedia messages. It uses the -@sc{mime} (Multipurpose Internet Mail Extensions) -protocol@footnote{@sc{mime} is defined in -@uref{http://www.rfc-editor.org/rfc/rfc2045.txt, RFC 2045}.} The -@sc{mime} protocol allows you to incorporate images, sound, video, -binary files, and even commands that fetch a file with @samp{ftp} when -your recipient reads the message! - -@kindex C-c C-m - -If you were to create a multimedia message with plain MH commands, you -would insert @command{mhbuild} or @command{mhn} directives (henceforth -called @dfn{MH-style directives} into your draft and use the -@command{mhbuild} command in nmh or @command{mhn} command in MH and -GNU mailutils to expand them. MH-E works in much the same way, -although it provides a handful of commands prefixed with @kbd{C-c C-m} -to insert the directives so you don't need to remember the syntax of -them. Remember: you can always add MH-style directives by -hand@footnote{See the section -@uref{@value{MH-BOOK-HOME}/usimim.html#SeMIMa, Sending MIME Mail} in -the MH book.}. - -@cindex MIME Meta Language (MML) -@cindex MML -@vindex mh-compose-insertion - -In addition to MH-style directives, MH-E also supports MML (@sc{mime} -Meta Language) tags@footnote{ -@ifinfo -@c Although the third argument should default to the -@c first, makeinfo goes to the wrong Info file without it being -@c different--it seems to be getting our own Composing node. -@xref{Composing,,Composing with MML,emacs-mime}. -@end ifinfo -@ifnotinfo -See the section Composing in -@uref{http://www.gnus.org/manual/emacs-mime.html, @cite{The Emacs MIME -Manual}}. -@end ifnotinfo -}. The option @code{mh-compose-insertion} can be used to choose -between them. By default, this option is set to @samp{MML} if it is -supported since it provides a lot more functionality. This option can -also be set to @samp{MH} if MH-style directives are preferred. - -@cindex media types -@cindex MIME, media types - -The MH-E @sc{mime} commands require a @dfn{media type} for each body -part or attachment. For example, a PDF document is of type -@samp{application/pdf} and an HTML document is of type -@samp{text/html}. Some commands fill in the media type for you, -whereas others require you to enter one. - -@cindex @command{file} -@cindex @file{/etc/mime.types} -@cindex files, @file{/etc/mime.types} -@cindex Unix commands, @command{file} -@findex mailcap-mime-types - -In the cases where MH-E can do so, it will determine the media type -automatically. It uses the @command{file} command to do this. Failing -that, the Emacs function @code{mailcap-mime-types} is used to provide -a list from which to choose. This function usually reads the file -@file{/etc/mime.types}. - -Whether the media type is chosen automatically, or you choose it from -a list, use the type that seems to match best the file that you are -including. In the case of binaries, the media type -@samp{application/x-executable} can be useful. If you can't find an -appropriate media type, use @samp{text/plain} for text messages and -@samp{application/octet-stream} for everything else. - -@cindex content description -@cindex MIME, content description - -You are also sometimes asked for a @dfn{content description}. This is -simply an optional brief phrase, in your own words, that describes the -object. If you don't care to enter a content description, just press -return and none will be included; however, a reader may skip over -multimedia fields unless the content description is compelling. - -You can also create your own @sc{mime} body parts. In the following -example, I describe how you can create and edit a @samp{text/enriched} -body part to liven up your plain text messages with boldface, -underlining, and italics. I include an Emacs function which inserts -enriched text tags. - -@smalllisp -@group -(defvar enriched-text-types '(("b" . "bold") ("i" . "italic") - ("u" . "underline") - ("s" . "smaller") ("B" . "bigger") - ("f" . "fixed") - ("c" . "center")) - "Alist of (final-character . tag) choices for add-enriched-text. -Additional types can be found in RFC 1563.") - -(defun add-enriched-text (begin end) - "Add enriched text tags around region. -The tag used comes from the list enriched-text-types and is -specified by the last keystroke of the command. When called from Lisp, -arguments are BEGIN and END@." - (interactive "r") - ;; @r{Set type to the tag indicated by the last keystroke.} - (let ((type (cdr (assoc (char-to-string (logior last-input-char ?@w{`})) - enriched-text-types)))) - (save-restriction ; @r{restores state from narrow-to-region} - (narrow-to-region begin end) ; @r{narrow view to region} - (goto-char (point-min)) ; @r{move to beginning of text} - (insert "<" type ">") ; @r{insert beginning tag} - (goto-char (point-max)) ; @r{move to end of text} - (insert "")))) ; @r{insert terminating tag} -@i{Emacs function for entering enriched text} - -@end group -@end smalllisp - -To use the function @code{add-enriched-text}, first add it to -@file{~/.emacs} and create key bindings for it (@pxref{Composing}). - -Then, in your plain text message, set the mark with @kbd{C-@@} or -@kbd{C-@key{SPC}}, type in the text to be highlighted, and type @kbd{C-c t -b}. This adds @samp{} where you set the mark and adds -@samp{} at the location of your cursor, giving you something -like: @samp{You should be very}. - -Before sending this message, use @kbd{C-c C-m C-m} -(@code{mh-mml-to-mime})@footnote{Use @kbd{C-c C-e} -(@code{mh-mh-to-mime}) if you're using MH-style directives.} to add -MIME header fields. Then replace @samp{text/plain} with -@samp{text/enriched} in the @samp{Content-Type:} header field. - -You may also be interested in investigating @code{sgml-mode}. - -@subheading Including Files - -@cindex attachments, inserting -@cindex images -@cindex MIME, images -@cindex MIME, sound -@cindex MIME, video -@cindex sound -@cindex video -@findex mh-compose-insertion -@kindex C-c C-m C-i -@kindex C-c C-m i -@vindex mh-compose-insertion - -Binaries, images, sound, and video can be inserted in your message -with the command @kbd{C-c C-m C-i} (@code{mh-compose-insertion}). You -are prompted for the filename containing the object, the media type if -it cannot be determined automatically, and a content description. If -you're using MH-style directives, you will also be prompted for -additional attributes. - -@subheading Forwarding Multimedia Messages - -@findex mh-compose-forward -@kindex C-c C-m C-f -@kindex C-c C-m f - -Mail may be forwarded with @sc{mime} using the command @kbd{C-c C-m -C-f} (@code{mh-compose-forward}). You are prompted for a content -description, the name of the folder in which the messages to forward -are located, and a range of messages, which defaults to the current -message in that folder. @xref{Ranges}. - -@subheading Including an FTP Reference - -@cindex @command{ftp} -@cindex MIME, @command{ftp} -@cindex Unix commands, @command{ftp} -@findex mh-mh-compose-anon-ftp -@kindex C-c C-m C-g -@kindex C-c C-m g - -You can have your message initiate an @command{ftp} transfer when the -recipient reads the message. To do this, use the command @kbd{C-c C-m -C-g} (@code{mh-mh-compose-anon-ftp}). You are prompted for the remote -host and filename, the media type, and the content description. - -@subheading Including tar Files - -@cindex @command{ftp} -@cindex @command{tar} -@cindex MIME, @command{ftp} -@cindex MIME, @command{tar} -@cindex Unix commands, @command{ftp} -@cindex Unix commands, @command{tar} -@findex mh-mh-compose-anon-ftp -@findex mh-mh-compose-external-compressed-tar -@kindex C-c C-m C-g -@kindex C-c C-m C-t -@kindex C-c C-m t - -If the remote file is a compressed tar file, you can use @kbd{C-c C-m -C-t} (@code{mh-mh-compose-external-compressed-tar}). Then, in addition -to retrieving the file via anonymous @emph{ftp} as per the command -@kbd{C-c C-m C-g} (@code{mh-mh-compose-anon-ftp}), the file will also -be uncompressed and untarred. You are prompted for the remote host and -filename and the content description. - -@subheading Including Other External Files - -@findex mh-mh-compose-external-type -@kindex C-c C-m C-x -@kindex C-c C-m x - -The command @kbd{C-c C-m C-x} (@code{mh-mh-compose-external-type}) is -a general utility for referencing external files. In fact, all of the -other commands that insert tags to access external files call this -command. You are prompted for the access type, remote host and -filename, and content type. If you provide a prefix argument, you are -also prompted for a content description, attributes, parameters, and a -comment. - -@subheading Previewing Multimedia Messages - -When you are finished editing a @sc{mime} message, it might look like this: - -@cartouche -@smallexample -3 t08/24 root received fax files on Wed Aug 24 11:00: -4+t08/24 To:wohler Test< -<#/part> ---:** @{draft@} All L8 (MH-Letter)---------------------------------- - -@end smallexample -@end cartouche -@i{MH-E @sc{mime} draft} - -@findex mh-mml-to-mime -@kindex C-c C-m C-m -@kindex C-c C-m m - -Typically, you send a message with attachments just like any other -message (@pxref{Sending Message}). - -@findex mh-mml-to-mime -@kindex C-c C-m C-m - -However, you may take a sneak preview of the @sc{mime} encoding if you -wish by running the command @kbd{C-c C-m C-m} (@code{mh-mml-to-mime}). -The following screen shows the @sc{mime} encoding specified by the -tags. You can see why mail user agents are usually built to hide these -details from the user. - -@cartouche -@smallexample -To: wohler -cc: -Subject: Test of MIME -X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 -MIME-Version: 1.0 -Content-Type: multipart/mixed; boundary="=-=-=" --------- ---=-=-= - -Here is the SETI@@Home logo: - - ---=-=-= -Content-Type: image/x-xpm -Content-Disposition: inline; filename=setiathome.xpm -Content-Transfer-Encoding: base64 -Content-Description: SETI@@home logo - -LyogWFBNICovCnN0YXRpYyBjaGFyICogc2V0aWF0aG9tZV94cG1bXSA9IHsKIjQ1IDQ1IDc2N ---:-- @{draft@} Top L1 (MH-Letter)---------------------------------- - -@end smallexample -@end cartouche -@i{MH-E @sc{mime} draft ready to send} - -@cindex undo effects of mh-mml-to-mime - -This action can be undone by running @kbd{C-_} (@code{undo}). - -@cindex @command{mhbuild} -@cindex @command{mhn} -@cindex MH commands, @command{mhbuild} -@cindex MH commands, @command{mhn} -@cindex undo effects of mh-mh-to-mime -@findex mh-mh-to-mime -@findex mh-mh-to-mime-undo -@kindex C-c C-e -@kindex C-c C-m C-m -@kindex C-c C-m C-u -@kindex C-c C-m u - -If you're using MH-style directives, use @kbd{C-c C-e} -(@code{mh-mh-to-mime}) instead of @kbd{C-c C-m C-m}. This runs the -command @command{mhbuild} (@command{mhn}) on the message which expands -the tags@footnote{See the section -@uref{@value{MH-BOOK-HOME}/usimim.html#SeMIMa, Sending MIME Mail} in -the MH book.}. This action can be undone by running @kbd{C-c C-m C-u} -(@code{mh-mh-to-mime-undo}), which works by reverting to a backup -file. You are prompted to confirm this action, but you can avoid the -confirmation by adding an argument (for example, @kbd{C-u C-c C-m -C-u}). - -@kindex C-c C-e -@vindex mh-mh-to-mime-args - -If you wish to pass additional arguments to @command{mhbuild} -(@command{mhn}) to affect how it builds your message, use the option -@code{mh-mh-to-mime-args}. For example, you can build a consistency -check into the message by setting @code{mh-mh-to-mime-args} to -@samp{-check}. The recipient of your message can then run -@samp{mhbuild -check} on the message---@command{mhbuild} -(@command{mhn}) will complain if the message has been corrupted on the -way. The command @kbd{C-c C-e} only consults this option when given a -prefix argument (as in @kbd{C-u C-c C-e}). - -@kindex C-c C-e -@vindex mh-mh-to-mime-hook - -The hook @code{mh-mh-to-mime-hook} is called after the message has -been formatted by @kbd{C-c C-e}. - -@node Sending PGP, Checking Recipients, Adding Attachments, Editing Drafts -@section Signing and Encrypting Messages - -@cindex signing messages -@cindex encrypting messages -@cindex RFC 3156 - -MH-E can sign and encrypt messages as defined in -@uref{http://www.rfc-editor.org/rfc/rfc3156.txt, RFC 3156}. If you -should choose to sign or encrypt your message, use one of the -following commands to do so any time before sending your message. - -@findex mh-mml-secure-message-encrypt -@findex mh-mml-secure-message-sign -@findex mh-mml-secure-message-signencrypt -@kindex C-c C-m C-e -@kindex C-c C-m C-s -@kindex C-c C-m e e -@kindex C-c C-m e s -@kindex C-c C-m s e -@kindex C-c C-m s s - -The command @kbd{C-c C-m C-s} (@code{mh-mml-secure-message-sign}) -inserts the following tag: - -@smallexample -<#secure method=pgpmime mode=sign> -@end smallexample - -This is used to sign your message digitally. Likewise, the command -@kbd{C-c C-m C-e} (@code{mh-mml-secure-message-encrypt}) inserts the -following tag: - -@smallexample -<#secure method=pgpmime mode=encrypt> -@end smallexample - -This is used to encrypt your message. Finally, the command @kbd{C-c -C-m s e} (@code{mh-mml-secure-message-signencrypt}) inserts the -following tag: - -@smallexample -<#secure method=pgpmime mode=signencrypt> -@end smallexample - -@findex mh-mml-unsecure-message -@kindex C-c C-m C-n -@kindex C-c C-m n -@vindex mh-mml-method-default - -This is used to sign and encrypt your message. In each of these cases, -a proper multipart message is created for you when you send the -message. Use the command @kbd{C-c C-m C-n} -(@code{mh-mml-unsecure-message}) to remove these tags. Use a prefix -argument (as in @kbd{C-u C-c C-m s e}) to be prompted for one of the -possible security methods (see @code{mh-mml-method-default}). - -@vindex mh-mml-method-default - -The option @code{mh-mml-method-default} is used to select between a -variety of mail security mechanisms. The default is @samp{PGP (MIME)} -if it is supported; otherwise, the default is @samp{None}. Other -mechanisms include vanilla @samp{PGP} and @samp{S/MIME}. - -@cindex @samp{pgg} customization group -@cindex PGG -@cindex customization group, @samp{pgg} - -The @samp{pgg} customization group may have some settings which may -interest you. -@iftex -See @cite{The PGG Manual}. -@end iftex -@ifinfo -@xref{Top, , The PGG Manual, pgg, The PGG Manual}. -@end ifinfo -@ifhtml -See -@uref{http://www.dk.xemacs.org/Documentation/packages/html/pgg.html, -@cite{The PGG Manual}}. -@end ifhtml - -@cindex header field, @samp{Fcc:} -@cindex @samp{Fcc:} header field -@vindex pgg-encrypt-for-me - -In particular, I turn on the option @code{pgg-encrypt-for-me} so that -all messages I encrypt are encrypted with my public key as well. If -you keep a copy of all of your outgoing mail with a @samp{Fcc:} header -field, this setting is vital so that you can read the mail you write! - -@node Checking Recipients, Sending Message, Sending PGP, Editing Drafts -@section Checking Recipients - -@cindex @samp{*MH-E Recipients*} -@cindex @command{whom} -@cindex MH commands, @command{whom} -@cindex buffers, @samp{*MH-E Recipients*} -@cindex checking recipients -@cindex recipients, checking -@findex mh-check-whom -@kindex C-c C-w - -The command @kbd{C-c C-w} (@code{mh-check-whom}) expands aliases so -you can check the actual address(es) in the alias. A new buffer named -@samp{*MH-E Recipients*} is created with the output of @command{whom} -(@pxref{Miscellaneous})@footnote{See the section -@uref{@value{MH-BOOK-HOME}/senove.html#WhaPro, What now? -- and the -whatnow Program} in the MH book.}. - -@node Sending Message, Killing Draft, Checking Recipients, Editing Drafts -@section Sending a Message - -@cindex buffers, @samp{*MH-E Mail Delivery*} -@cindex @samp{*MH-E Mail Delivery*} -@cindex sending mail -@findex mh-send-letter -@kindex C-c C-c - -When you are all through editing a message, you send it with the -command @kbd{C-c C-c} (@code{mh-send-letter}). You can give a prefix -argument (as in @kbd{C-u C-c C-c}) to monitor the first stage of the -delivery; this output can be found in a buffer called @samp{*MH-E Mail -Delivery*} (@pxref{Miscellaneous}). - -@cindex sending mail -@cindex spell check -@findex ispell-message -@kindex C-c C-c -@vindex mh-before-send-letter-hook - -The hook @code{mh-before-send-letter-hook} is run at the beginning of -the command @kbd{C-c C-c}. For example, if you want to check your -spelling in your message before sending, add the function -@code{ispell-message}. - -@cindex @command{send} -@cindex MH commands, @command{send} -@vindex mh-send-prog - -In case the MH @command{send} program@footnote{See the section -@uref{@value{MH-BOOK-HOME}/sensen.html, Sending Some Mail: comp send} -in the MH book.} is installed under a different name, use -@code{mh-send-prog} to tell MH-E the name. - -The hook @code{mh-annotate-msg-hook} is run after annotating the -message and scan line (@pxref{Sending Mail}). - -@node Killing Draft, , Sending Message, Editing Drafts -@section Killing the Draft - -@cindex killing draft -@findex kill-buffer -@findex mh-fully-kill-draft -@kindex C-c C-q -@kindex C-x k - -If for some reason you are not happy with the draft, you can use the -command @kbd{C-c C-q} (@code{mh-fully-kill-draft}) to kill the draft -buffer and delete the draft message. Use the command @kbd{C-x k} -(@code{kill-buffer}) if you don't want to delete the draft message. - -@node Aliases, Identities, Editing Drafts, Top -@chapter Aliases - -@cindex aliases - -MH aliases are used in the same way in MH-E as they are in MH. Any -alias listed as a recipient will be expanded when the message is sent. -This chapter discusses other things you can do with aliases in MH-E. - -@cindex MH-Letter mode -@cindex modes, MH-Letter - -The following commands are available in MH-Letter mode with the -exception of @code{mh-alias-reload} which can be called from anywhere. - -@table @kbd -@kindex @key{SPC} -@findex mh-letter-complete-or-space -@item @key{SPC} -Perform completion or insert space (@code{mh-letter-complete-or-space}). -@c ------------------------- -@kindex M-@key{TAB} -@findex mh-letter-complete -@item M-@key{TAB} -Perform completion on header field or word preceding point -(@code{mh-letter-complete}). -@c ------------------------- -@findex mh-alias-apropos -@item mh-alias-apropos -Show all aliases or addresses that match a regular expression. -@c ------------------------- -@findex mh-alias-grab-from-field -@item mh-alias-grab-from-field -Add alias for the sender of the current message -@c ------------------------- -@findex mh-alias-reload -@item mh-alias-reload -Reload MH aliases. -@end table - -@cindex @samp{mh-alias} customization group -@cindex customization group, @samp{mh-alias} - -The @samp{mh-alias} customization group contains options associated -with aliases. - -@vtable @code -@item mh-alias-completion-ignore-case-flag -On means don't consider case significant in MH alias completion -(default: @samp{on}). -@c ------------------------- -@item mh-alias-expand-aliases-flag -On means to expand aliases entered in the minibuffer (default: -@samp{off}). -@c ------------------------- -@item mh-alias-flash-on-comma -Specify whether to flash address or warn on translation (default: @samp{Flash -but Don't Warn If No Alias}). -@c ------------------------- -@item mh-alias-insert-file -Filename used to store a new MH-E alias (default: @samp{Use Aliasfile -Profile Component}). -@c ------------------------- -@item mh-alias-insertion-location -Specifies where new aliases are entered in alias files (default: -@samp{Alphabetical}). -@c ------------------------- -@item mh-alias-local-users -If @samp{on}, local users are added to alias completion (default: -@samp{on}). -@c ------------------------- -@item mh-alias-local-users-prefix -String prefixed to the real names of users from the password file -(default: @code{"local."}. -@c ------------------------- -@item mh-alias-passwd-gecos-comma-separator-flag -On means the GECOS field in the password file uses a comma separator -(default: @samp{on}). -@end vtable - -The following hook is available. - -@vtable @code -@item mh-alias-reloaded-hook -Hook run by @code{mh-alias-reload} after loading aliases (default: -@code{nil}). -@end vtable - -@subheading Adding Addresses to Draft - -You can use aliases when you are adding recipients to a message. - -@findex minibuffer-complete -@kindex @key{TAB} -@vindex mh-alias-expand-aliases-flag -@vindex mh-compose-prompt-flag - -In order to use minibuffer prompting for recipients and the subject -line in the minibuffer, turn on the option -@code{mh-compose-prompt-flag} (@pxref{Composing}), and use the -@key{TAB} (@code{minibuffer-complete}) command to complete aliases -(and optionally local logins) when prompted for the recipients. Turn -on the option @code{mh-alias-expand-aliases-flag} if you want these -aliases to be expanded to their respective addresses in the draft. - -@findex mh-letter-complete -@findex mh-letter-complete-or-space -@kindex @key{SPC} -@kindex M-@key{TAB} - -Otherwise, you can complete aliases in the header of the draft with -@kbd{M-@key{TAB}} (@code{mh-letter-complete}) or @key{SPC} -(@code{mh-letter-complete-or-space}). - -@vindex mh-alias-completion-ignore-case-flag - -As MH ignores case in the aliases, so too does MH-E. However, you may -turn off the option @code{mh-alias-completion-ignore-case-flag} to -make case significant which can be used to segregate completion of -your aliases. You might use uppercase for mailing lists and lowercase -for people. For example, you might have: - -@smallexample -mark.baushke: Mark Baushke -MH-E: MH-E Mailing List -@end smallexample - -When this option is turned off, if you were to type @kbd{M} in the -@samp{To:} field and then @kbd{M-@key{TAB}}, then you'd get the list; -if you started with @kbd{m} and then entered @kbd{M-@key{TAB}}, then -you'd get Mark's address. Note that this option affects completion -only. If you were to enter @kbd{Mark.Baushke}, it would still be -identified with your @samp{mark.baushke} alias. - -@findex mh-alias-minibuffer-confirm-address -@findex mh-letter-confirm-address -@vindex mh-alias-flash-on-comma -@vindex mh-compose-prompt-flag - -To verify that the alias you've entered is valid, the alias will be -displayed in the minibuffer when you type a comma -(@code{mh-letter-confirm-address} or -@code{mh-alias-minibuffer-confirm-address} if the option -@code{mh-compose-prompt-flag} is turned on). @xref{Composing}. This -behavior can be controlled with the option -@code{mh-alias-flash-on-comma} which provides three choices: -@samp{Flash but Don't Warn If No Alias}, @samp{Flash and Warn If No -Alias}, and @samp{Don't Flash Nor Warn If No Alias}. - -For another way to verify the alias expansion, see @ref{Checking -Recipients}. - -@subheading Loading Aliases - -@cindex @command{ali} -@cindex @file{/etc/nmh/MailAliases} -@cindex @samp{Aliasfile:} MH profile component -@cindex MH commands, @command{ali} -@cindex MH profile component, @samp{Aliasfile:} -@cindex files, @file{/etc/nmh/MailAliases} - -MH-E loads aliases for completion and folder name hints from various -places. It uses the MH command @command{ali}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/mh.html, MH Aliases} in the MH book.} to -read aliases from the files listed in the profile component -@samp{Aliasfile:} as well as system-wide aliases (for example, -@file{/etc/nmh/MailAliases}). - -@cindex @file{/etc/passwd} -@cindex files, @file{/etc/passwd} - -In addition, aliases are created from @file{/etc/passwd} entries with -a user ID larger than a magical number, typically 200. This can be a -handy tool on a machine where you and co-workers exchange messages. -These aliases have the form @samp{local.@var{first.last}} if a real -name is present in the password file. Otherwise, the alias will have -the form @samp{local.@var{login}}. - -@vindex mh-alias-local-users-prefix - -The prefix @samp{local.} can be modified via the option -@code{mh-alias-local-users-prefix}. This option can also be set to -@samp{Use Login}. - -For example, consider the following password file entry: - -@smallexample -psg:x:1000:1000:Peter S Galbraith,,,:/home/psg:/bin/tcsh -@end smallexample - -@vindex mh-alias-local-users-prefix - -The following settings of option @code{mh-alias-local-users-prefix} -will produce the associated aliases: - -@table @code -@item "local." -local.peter.galbraith -@c ------------------------- -@item "" -peter.galbraith -@c ------------------------- -@item Use Login -psg -@end table - -@vindex mh-alias-passwd-gecos-comma-separator-flag - -In the example above, commas are used to separate different values -within the so-called GECOS field. This is a fairly common usage. -However, in the rare case that the GECOS field in your password file -is not separated by commas and whose contents may contain commas, you -can turn the option @code{mh-alias-passwd-gecos-comma-separator-flag} -off. - -@cindex NIS, obtaining local aliases from -@cindex @samp{ypcat passwd} -@vindex mh-alias-local-users - -If you're on a system with thousands of users you don't know, and the -loading of local aliases slows MH-E down noticeably, then the local -alias feature can be disabled by turning off the option -@code{mh-alias-local-users}. This option also takes a string which is -executed to generate the password file. For example, use @samp{ypcat -passwd} to obtain the NIS password file. - -@findex mh-alias-reload -@kindex M-x mh-alias-reload -@vindex mh-alias-reloaded-hook - -Since aliases are updated frequently, MH-E reloads aliases -automatically whenever an alias lookup occurs if an alias source has -changed. However, you can reload your aliases manually by calling the -command @kbd{M-x mh-alias-reload} directly. This command runs -@code{mh-alias-reloaded-hook} after the aliases have been loaded. - -@subheading Adding Aliases - -In the past, you have manually added aliases to your alias file(s) -listed in your @samp{Aliasfile:} profile component. MH-E provides -other methods for maintaining your alias file(s). - -@findex mh-alias-add-alias -@kindex M-x mh-alias-add-alias - -You can use the @kbd{M-x mh-alias-add-alias} command which will prompt -you for the alias and address that you would like to add. If the alias -exists already, you will have the choice of inserting the new alias -before or after the old alias. In the former case, this alias will be -used when sending mail to this alias. In the latter case, the alias -serves as an additional folder name hint when filing messages -(@pxref{Folder Selection}). - -Earlier, the alias prefix @samp{local} was presented. You can use -other prefixes to organize your aliases or disambiguate entries. You -might use prefixes for locales, jobs, or activities. For example, I -have: - -@smallexample -@group -; Work -attensity.don.mitchell: Don Mitchell -isharp.don.mitchell: Don Mitchell -... -; Sport -diving.ken.mayer: Ken Mayer -sailing.mike.maloney: Mike Maloney -... -; Personal -ariane.kolkmann: Ariane Kolkmann -... -@end group -@end smallexample - -Using prefixes instead of postfixes helps you explore aliases during -completion. If you forget the name of an old dive buddy, you can enter -@samp{div} and then @key{SPC} to get a listing of all your dive buddies. - -@kindex M-x mh-alias-add-address-under-point -@kindex M-x mh-alias-grab-from-field - -An alias for the sender of the current message is added automatically -by clicking on the @samp{Grab From alias} tool bar button or by running -the @kbd{M-x mh-alias-grab-from-field} command. Aliases for other -recipients of the current message are added by placing your cursor -over the desired recipient and giving the @kbd{M-x -mh-alias-add-address-under-point} command. - -@vindex mh-alias-insert-file -@vindex mh-alias-insertion-location - -The options @code{mh-alias-insert-file} and -@code{mh-alias-insertion-location} controls how and where these aliases -are inserted. - -@vindex mh-alias-insert-file - -The default setting of option @code{mh-alias-insert-file} is @samp{Use -Aliasfile Profile Component}. This option can also hold the name of a -file or a list a file names. If this option is set to a list of file -names, or the @samp{Aliasfile:} profile component contains more than -one file name, MH-E will prompt for one of them. - -@vindex mh-alias-insertion-location - -The option @code{mh-alias-insertion-location} is set to -@samp{Alphabetical} by default. If you organize your alias file in -other ways, then the settings @samp{Top} and @samp{Bottom} might be -more appropriate. - -@subheading Querying Aliases - -@cindex regular expressions, @code{mh-alias-apropos} -@findex mh-alias-apropos -@kindex M-x mh-alias-apropos - -If you can't quite remember an alias, you can use @kbd{M-x -mh-alias-apropos} to show all aliases or addresses that match a -regular expression -@ifnothtml -(@pxref{Regexps, , Syntax of Regular Expressions, emacs, The -GNU Emacs Manual}). -@end ifnothtml -@ifhtml -(see the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html, -Syntax of Regular Expressions} in -@cite{The GNU Emacs Manual}). -@end ifhtml - -@node Identities, Speedbar, Aliases, Top -@chapter Identities - -@cindex identities -@cindex multiple personalities - -MH-E supports the concept of multiple personalities or identities. -This means that you can easily have a different header and signature -at home and at work. - -@cindex @samp{Identity} menu -@cindex menu, @samp{Identity} - -A couple of commands are used to insert identities in MH-Letter mode -which are also found in the @samp{Identity} menu. - -@table @kbd -@kindex C-c C-d -@findex mh-insert-identity -@item C-c C-d -Insert fields specified by given identity (@code{mh-insert-identity}). -@c ------------------------- -@cindex @samp{Identity > Insert Auto Fields} menu item -@cindex menu item, @samp{Identity > Insert Auto Fields} -@kindex C-c M-d -@findex mh-insert-auto-fields -@item C-c M-d -Insert custom fields if recipient found in @code{mh-auto-fields-list} -(@code{mh-insert-auto-fields}). -@end table - -@cindex @samp{mh-identity} customization group -@cindex customization group, @samp{mh-identity} - -The @samp{mh-identity} customization group contains the following -options. - -@vtable @code -@item mh-auto-fields-list -List of recipients for which header lines are automatically inserted -(default: @code{nil}). -@c ------------------------- -@item mh-auto-fields-prompt-flag -On means to prompt before sending if fields inserted (default: -@samp{on}) -@c ------------------------- -@item mh-identity-default -Default identity to use when @code{mh-letter-mode} is called (default: -@samp{None}). -@c ------------------------- -@item mh-identity-handlers -Handler functions for fields in @code{mh-identity-list}. -@c ------------------------- -@item mh-identity-list -List of identities (default: @code{nil}). -@end vtable - -Some of the common header fields that people change depending on the -context are the @samp{From:} and @samp{Organization:} fields, as well -as the signature. - -@vindex mh-identity-list - -This is done by customizing the option @code{mh-identity-list}. In the -customization buffer for this option, click on the @samp{INS} button -and enter a label such as @samp{Home} or @samp{Work}. Then click on -the @samp{INS} button with the label @samp{Add at least one item -below}. The @samp{Value Menu} has the following menu items: - -@table @samp -@cindex header field, @samp{From:} -@cindex @samp{From:} header field -@item From Field -Specify an alternate @samp{From:} header field. You must include a -valid email address. A standard format is @samp{First Last -}. If you use an initial with a period, then you -must quote your name as in @samp{"First I. Last" -}. -@c ------------------------- -@cindex header field, @samp{Organization:} -@cindex @samp{Organization:} header field -@item Organization Field -People usually list the name of the company where they work here. -@c ------------------------- -@item Other Field -Set any arbitrary header field and value here. Unless the header field -is a standard one, precede the name of your field's label with -@samp{X-}, as in @samp{X-Fruit-of-the-Day:}. -@c ------------------------- -@item Attribution Verb -This value overrides the setting of -@code{mh-extract-from-attribution-verb}. @xref{Inserting Letter}. -@c ------------------------- -@cindex signature -@vindex mh-signature-file-name -@item Signature -Set your signature with this item. You can specify the contents of -@code{mh-signature-file-name}, a file, or a function. -@xref{Signature}. -@c ------------------------- -@item GPG Key ID -Specify a different key to sign or encrypt messages. -@end table - -@cindex Identity menu -@cindex menu, Identity -@findex mh-insert-identity -@kindex C-c C-d - -You can select the identities you have added via the menu called -@samp{Identity} in the MH-Letter buffer. You can also use @kbd{C-c -C-d} (@code{mh-insert-identity}). To clear the fields and signature -added by the identity, select the @samp{None} identity. - -@cindex menu item, @samp{Identity > Customize Identities} -@cindex menu item, @samp{Identity > Save as Default} -@cindex menu item, @samp{Identity > Set Default for Session} -@cindex @samp{Identity > Customize Identities} menu item -@cindex @samp{Identity > Save as Default} menu item -@cindex @samp{Identity > Set Default for Session} menu item -@vindex mh-identity-default - -The @samp{Identity} menu contains two other items to save you from -having to set the identity on every message. The menu item @samp{Set -Default for Session} can be used to set the default identity to the -current identity until you exit Emacs. The menu item @samp{Save as -Default} sets the option @code{mh-identity-default} to the current -identity setting. You can also customize the option -@code{mh-identity-default} in the usual fashion. If you find that you -need to add another identity, the menu item @samp{Customize -Identities} is available for your convenience. - -@cindex regular expressions, @code{mh-auto-fields-list} -@vindex mh-auto-fields-list - -The option @code{mh-auto-fields-list} can also be used to set the -identity depending on the recipient to provide even more control. To -customize @code{mh-auto-fields-list}, click on the @samp{INS} button -and enter a regular expression for the recipient's address -@ifnothtml -(@pxref{Regexps, , Syntax of Regular Expressions, emacs, The -GNU Emacs Manual}). -@end ifnothtml -@ifhtml -(see the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html, -Syntax of Regular Expressions} in -@cite{The GNU Emacs Manual}). -@end ifhtml -Click on the @samp{INS} button with the @samp{Add at least one item -below} label. The @samp{Value Menu} contains the following menu items: - -@table @samp -@item Identity -Select an identity from those configured in @code{mh-identity-list}. -All of the information for that identity will be added if the -recipient matches. -@c ------------------------- -@cindex @samp{Fcc:} header field -@cindex header field, @samp{Fcc:} -@item Fcc Field -Insert an @samp{Fcc:} header field with the folder you provide. When -you send the message, MH will put a copy of your message in this -folder. -@c ------------------------- -@cindex @samp{Mail-Followup-To:} header field -@cindex header field, @samp{Mail-Followup-To:} -@item Mail-Followup-To Field -Insert an @samp{Mail-Followup-To:} header field with the recipients -you provide. If the recipient's mail user agent supports this header -field@footnote{@samp{Mail-Followup-To:} is supported by nmh.}, then -their replies will go to the addresses listed. This is useful if their -replies go both to the list and to you and you don't have a mechanism -to suppress duplicates. If you reply to someone not on the list, you -must either remove the @samp{Mail-Followup-To:} field, or ensure the -recipient is also listed there so that he receives replies to your -reply. -@c ------------------------- -@item Other Field -Other header fields may be added using this menu item. -@end table - -@findex mh-insert-auto-fields -@kindex C-c M-d -@vindex mh-auto-fields-prompt-flag - -These fields can only be added after the recipient is known. Because -you can continue to add recipients as you edit the draft, MH-E waits -until the message is sent to perform the auto-insertions. This seems -strange at first, but you'll get used to it. There are two ways to -help you feel that the desired fields are added. The first is the -action when the message is sent: if any fields are added -automatically, you are given a chance to see and to confirm these -fields before the message is actually sent. You can do away with this -confirmation by turning off the option -@code{mh-auto-fields-prompt-flag}. The second method is manual: once -the header contains one or more recipients, you may run the command -@kbd{C-c M-d} (@code{mh-insert-auto-fields}) or choose the -@samp{Identity -> Insert Auto Fields} menu item to insert these fields -manually. However, if you use this command, the automatic insertion -when the message is sent is disabled. - -@vindex mh-auto-fields-list -@vindex mh-identity-list - -You should avoid using the same header field in -@code{mh-auto-fields-list} and @code{mh-identity-list} definitions -that may apply to the same message as the result is undefined. - -@vindex mh-identity-handlers -@vindex mh-identity-list - -The option @code{mh-identity-handlers} is used to change the way that -fields, signatures, and attributions in @code{mh-identity-list} are -added. To customize @code{mh-identity-handlers}, replace the name of -an existing handler function associated with the field you want to -change with the name of a function you have written. You can also -click on an @samp{INS} button and insert a field of your choice and -the name of the function you have written to handle it. - -@vindex mh-identity-list - -The @samp{Field} field can be any field that you've used in your -@code{mh-identity-list}. The special fields @samp{:attribution-verb}, -@samp{:signature}, or @samp{:pgg-default-user-id} are used for the -@code{mh-identity-list} choices @samp{Attribution Verb}, -@samp{Signature}, and @samp{GPG Key ID} respectively. - -The handler associated with the @samp{:default} field is used when no -other field matches. - -The handler functions are passed two or three arguments: the field -itself (for example, @samp{From}), or one of the special fields (for -example, @samp{:signature}), and the action @samp{'remove} or -@samp{'add}. If the action is @samp{'add}, an additional argument -containing the value for the field is given. - -@node Speedbar, Menu Bar, Identities, Top -@chapter The Speedbar - -@cindex folder navigation -@cindex speedbar -@findex mh-visit-folder -@kindex F v -@kindex M-x speedbar -@kindex Mouse-2 - -You can also use the speedbar -@ifnothtml -(@pxref{Speedbar, , Speedbar Frames, emacs, The GNU Emacs Manual},) -@end ifnothtml -@ifhtml -(see the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Speedbar.html, -Speedbar Frames} in @cite{The GNU Emacs Manual}) -@end ifhtml -to view your folders. To bring up the speedbar, run @kbd{M-x speedbar -@key{RET}}. You will see a new frame appear with all of your MH -folders. Folders with unseen messages appear in boldface. Click on a -folder name with @kbd{Mouse-2} to visit that folder in a similar -fashion to the command @kbd{F v} (@code{mh-visit-folder}) -(@pxref{Folders}). Click on the @samp{+} icon to expand and view the -sub-folders of that folder. - -The speedbar can be manipulated with the keyboard as well. Use the -Emacs navigational keys (like the arrow keys, or @kbd{C-n}) to move -the cursor over the desired folder and then use the shortcuts for the -menu items listed in the table below. - -@table @samp -@findex mh-speed-view -@item Visit Folder (@key{RET}) -Visits the selected folder just as if you had used @kbd{F v} -(@code{mh-speed-view}). -@c ------------------------- -@findex mh-speed-expand-folder -@item Expand Nested Folders (@kbd{+}) -Expands the selected folder in the speedbar, exposing the children -folders inside it (@code{mh-speed-expand-folder}). -@c ------------------------- -@findex mh-speed-contract-folder -@item Contract Nested Folders (@kbd{-}) -Contracts or collapses the selected folder in the speedbar, hiding the -children folders inside it (@code{mh-speed-contract-folder}). -@c ------------------------- -@findex mh-speed-refresh -@item Refresh Speedbar (@kbd{r}) -Regenerates the list of folders in the speedbar. Run this command if -you've added or deleted a folder, or want to update the unseen message -count before the next automatic update (@code{mh-speed-refresh}). -@end table - -@findex delete-frame -@kindex C-x 5 0 -@kindex Mouse-3 - -You can click on @kbd{Mouse-3} to bring up a context menu that -contains these items. Dismiss the speedbar with @kbd{C-x 5 0} -(@code{delete-frame}). - -@cindex @command{flists} -@cindex MH commands, @command{flists} -@cindex @samp{mh-speedbar} customization group -@cindex customization group, @samp{mh-speedbar} - -The MH-E speedbar uses the MH command @command{flists}@footnote{See -the section @uref{@value{MH-BOOK-HOME}/morseq.html#flist, Searching for -Sequences with flist} in the MH book.} to generate the list of -folders. The @samp{mh-speedbar} customization group contains the -following option which controls how often the speedbar calls -@command{flists}. - -@vtable @code -@item mh-speed-update-interval -Time between speedbar updates in seconds (default: 60). Set to 0 to -disable automatic update. -@end vtable - -You can modify the appearance of the folders in the speedbar by -customizing the following faces. - -@vtable @code -@item mh-speedbar-folder -Basic folder face. -@c ------------------------- -@item mh-speedbar-folder-with-unseen-messages -Folder face when folder contains unread messages. -@c ------------------------- -@item mh-speedbar-selected-folder -Selected folder face. -@c ------------------------- -@item mh-speedbar-selected-folder-with-unseen-messages -Selected folder face when folder contains unread messages. -@end vtable - -@node Menu Bar, Tool Bar, Speedbar, Top -@chapter The Menu Bar - -@cindex @samp{Folder} menu -@cindex @samp{Identity} menu -@cindex @samp{Letter} menu -@cindex @samp{Message} menu -@cindex @samp{Search} menu -@cindex @samp{Sequence} menu -@cindex Folder menu -@cindex Identity menu -@cindex Letter menu -@cindex MH-Folder mode -@cindex MH-Letter mode -@cindex MH-Search mode -@cindex Message menu -@cindex Search menu -@cindex Sequence menu -@cindex menu bar -@cindex menu, Folder -@cindex menu, Identity -@cindex menu, Letter -@cindex menu, Message -@cindex menu, Search -@cindex menu, Sequence -@cindex menu, @samp{Folder} -@cindex menu, @samp{Identity} -@cindex menu, @samp{Letter} -@cindex menu, @samp{Message} -@cindex menu, @samp{Search} -@cindex menu, @samp{Sequence} -@cindex modes, MH-Folder -@cindex modes, MH-Letter -@cindex modes, MH-Search - -For those of you who prefer to mouse and menu instead of using the -meta-coke-bottle-bucky keys, MH-E provides menu items for most of its -functions. The MH-Folder buffer adds the @samp{Folder}, -@samp{Message}, and @samp{Sequence} menus. The MH-Letter buffer adds -the @samp{Identity} and @samp{Letter} menus. The MH-Search buffer adds -the @samp{Search} menu. There's no need to list the actual items here, -as you can more easily see them for yourself, and the functions are -already described elsewhere in this manual. - -For a description of the menu bar, please -@ifnothtml -@xref{Menu Bar, , The Menu Bar, emacs, The GNU Emacs Manual}. -@end ifnothtml -@ifhtml -see the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Menu-Bar.html, -The Menu Bar} in @cite{The GNU Emacs Manual}. -@end ifhtml - -The Emacs manual describes how to get online help for a particular -menu item. You can also look up a menu item in the index of this -manual in two ways: all of the menu items are listed alphabetically, -and you can also browse all of the items under the index entry -@samp{menu item}. - -@node Tool Bar, Searching, Menu Bar, Top -@chapter The Tool Bar - -@cindex tool bar - -Emacs also provides a graphical tool bar. For a description of the -tool bar, please -@ifnothtml -@xref{Tool Bars, , Tool Bars, emacs, The GNU Emacs Manual}. -@end ifnothtml -@ifhtml -see the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Tool-Bars.html, -Tool Bars} in @cite{The GNU Emacs Manual}. -@end ifhtml - -@cindex @samp{mh-tool-bar} customization group -@cindex customization group, @samp{mh-tool-bar} - -MH-E adds several icons to this tool bar; you can modify the MH-E -aspects of the tool bar via the @samp{mh-tool-bar} customization group. - -@vtable @code -@item mh-tool-bar-folder-buttons -List of buttons to include in MH-Folder tool bar (default: a checklist -too long to list here). -@c ------------------------- -@item mh-tool-bar-letter-buttons -List of buttons to include in MH-Letter tool bar (default: a checklist -too long to list here). -@c ------------------------- -@item mh-tool-bar-search-function -Function called by the tool bar search button (default: -@code{mh-search}). -@c ------------------------- -@item mh-xemacs-tool-bar-position -Tool bar location (default: @samp{Same As Default Tool Bar}). -@c ------------------------- -@item mh-xemacs-use-tool-bar-flag -If @samp{on}, use tool bar (default: @samp{on}, if supported). -@end vtable - -In GNU Emacs, icons for some of MH-E's functions are added to the tool -bar. In XEmacs, you have the opportunity to create a separate tool bar for -the MH-E icons. - -@vindex mh-tool-bar-folder-buttons -@vindex mh-tool-bar-letter-buttons - -In either case, you can select which of these functions you'd like to -see by customizing the options @code{mh-tool-bar-folder-buttons} and -@code{mh-tool-bar-letter-buttons}. As you probably guessed, the former -customizes the tool bar in MH-Folder mode and the latter in MH-Letter -mode. Both of these options present you with a list of functions; -check the functions whose icons you want to see and clear the check -boxes for those you don't. - -@findex mh-search -@vindex mh-tool-bar-search-function - -The function associated with the searching icon can be set via the -option @code{mh-tool-bar-search-function}. By default, this is set to -@code{mh-search}. @xref{Searching}. You can also choose @samp{Other -Function} from the @samp{Value Menu} and enter a function of your own -choosing. - -@vindex mh-xemacs-use-tool-bar-flag - -XEmacs provides a couple of extra options. The first, -@code{mh-xemacs-use-tool-bar-flag}, controls whether to show the MH-E -icons at all. By default, this option is turned on if the window -system supports tool bars. If your system doesn't support tool bars, -then you won't be able to turn on this option. - -@vindex mh-xemacs-tool-bar-position - -The second extra option is @code{mh-xemacs-tool-bar-position} which -controls the placement of the tool bar along the four edges of the -frame. You can choose from one of @samp{Same As Default Tool Bar}, -@samp{Top}, @samp{Bottom}, @samp{Left}, or @samp{Right}. If this -variable is set to anything other than @samp{Same As Default Tool Bar} -and the default tool bar is in a different location, then two tool -bars will be displayed: the MH-E tool bar and the default tool bar. - -@node Searching, Threading, Tool Bar, Top -@chapter Searching Through Messages - -@cindex @samp{Search} menu -@cindex menu, @samp{Search} -@cindex searching -@findex mh-search -@kindex F s - -Earlier, the command @kbd{F s} (@code{mh-search}) was introduced which -helps you find messages that lie buried in your folders -(@pxref{Folders}). This chapter covers this command in more detail. -Several commands are used to compose the search criteria and to start -searching. A couple of them can be found in the @samp{Search} menu. - -@table @kbd -@kindex C-c ? -@findex mh-help -@item C-c ? -Display cheat sheet for the MH-E commands (@code{mh-help}). -@c ------------------------- -@cindex @samp{Search > Perform Search} menu item -@cindex menu item, @samp{Search > Perform Search} -@kindex C-c C-c -@findex mh-index-do-search -@item C-c C-c -Find messages using @code{mh-search-program} -(@code{mh-index-do-search}). -@c ------------------------- -@cindex @samp{Search > Search with pick} menu item -@cindex menu item, @samp{Search > Search with pick} -@kindex C-c C-p -@findex mh-pick-do-search -@item C-c C-p -Find messages using @command{pick} (@code{mh-pick-do-search}). -@c ------------------------- -@kindex C-c ? -@findex mh-help -@item C-c ? -Display cheat sheet for the MH-E commands (@code{mh-help}). -@c ------------------------- -@kindex C-c C-f C-a -@kindex C-c C-f a -@findex mh-to-field -@item C-c C-f a -@itemx C-c C-f C-a -Move to @samp{Mail-Reply-To:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-b -@kindex C-c C-f b -@item C-c C-f b -@itemx C-c C-f C-b -Move to @samp{Bcc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-c -@kindex C-c C-f c -@item C-c C-f c -@itemx C-c C-f C-c -Move to @samp{Cc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-d -@kindex C-c C-f d -@item C-c C-f d -@itemx C-c C-f C-d -Move to @samp{Dcc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-f -@kindex C-c C-f f -@item C-c C-f f -@itemx C-c C-f C-f -Move to @samp{Fcc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-l -@kindex C-c C-f l -@item C-c C-f l -@itemx C-c C-f C-l -Move to @samp{Mail-Followup-To:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-m -@kindex C-c C-f m -@item C-c C-f m -@itemx C-c C-f C-m -Move to @samp{From:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-r -@kindex C-c C-f r -@item C-c C-f r -@itemx C-c C-f C-r -Move to @samp{Reply-To:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-s -@kindex C-c C-f s -@item C-c C-f s -@itemx C-c C-f C-s -Move to @samp{Subject:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-t -@kindex C-c C-f t -@item C-c C-f t -@itemx C-c C-f C-t -Move to @samp{To:} header field (@code{mh-to-field}). -@end table - -Another few commands are available in the MH-Folder buffer resulting -from a search. - -@table @kbd -@kindex @key{TAB} -@findex mh-index-next-folder -@item @key{TAB} -Jump to the next folder marker (@code{mh-index-next-folder}). -@c ------------------------- -@kindex S-@key{TAB} -@findex mh-index-previous-folder -@item S-@key{TAB} -Jump to the previous folder marker (@code{mh-index-previous-folder}). -@c ------------------------- -@kindex v -@findex mh-index-visit-folder -@item v -Visit original folder from where the message at point was found -(@code{mh-index-visit-folder}). -@end table - -@cindex @samp{mh-search} customization group -@cindex customization group, @samp{mh-search} - -There is one option from the @samp{mh-search} customization group used -in searching. - -@vtable @code -@item mh-search-program -Search program that MH-E shall use (default: @samp{Auto-detect}). -@end vtable - -The following hook is available. - -@vtable @code -@item mh-search-mode-hook -Hook run upon entry to @code{mh-search-mode} (default: @code{nil}). -@end vtable - -The following face is available. - -@vtable @code -@item mh-search-folder -Folder heading face in MH-Folder buffers created by searches. -@end vtable - -@findex mh-search-folder -@kindex F s - -The command @kbd{F s} (@code{mh-search-folder}) helps you find -messages in your entire corpus of mail. You can search for messages to -or from a particular person or about a particular subject. In fact, -you can also search for messages containing selected strings in any -arbitrary header field or any string found within the messages. - -@cindex @command{pick} -@cindex MH commands, @command{pick} - -Out of the box, MH-E uses @command{pick} to find messages. With a -little extra effort, you can set an indexing program which rewards you -with extremely quick results. The drawback is that sometimes the index -does not contain the words you're looking for. You can still use -@command{pick} in these situations. - -You are prompted for the folder to search. This can be @samp{all} to -search all folders. Note that the search works recursively on the -listed folder. - -@cindex MH-Search mode -@cindex modes, MH-Search - -Next, an MH-Search buffer appears where you can enter search criteria. - -@cartouche -@smallexample -From: -To: -Cc: -Date: -Subject: --------- -# - - - - - - - - ---:** search-pattern All L7 (MH-Search)--------------------------- -Type C-c C-c to search messages, C-c C-p to use pick, C-c ? for help -@end smallexample -@end cartouche -@i{Search window} - -@cindex @command{pick} -@cindex MH commands, @command{pick} - -Edit this template by entering your search criteria in an appropriate -header field that is already there, or create a new field yourself. If -the string you're looking for could be anywhere in a message, then -place the string underneath the row of dashes. - -As an example, let's say that we want to find messages from Ginnean -about horseback riding in the Kosciusko National Park (Australia) -during January, 1994. Normally we would start with a broad search and -narrow it down if necessary to produce a manageable amount of data, -but we'll cut to the chase and create a fairly restrictive set of -criteria as follows: - -@smallexample -@group -From: ginnean -To: -Cc: -Date: Jan 1994 -Subject: --------- -horse -kosciusko -@end group -@end smallexample - -@findex mh-to-field -@kindex C-c C-f C-t - -As with MH-Letter mode, MH-Search provides commands like @kbd{C-c C-f -C-t} (@code{mh-to-field}) to help you fill in the blanks. -@xref{Editing Message}. - -@kindex F s -@vindex mh-search-mode-hook - -If you find that you do the same thing over and over when editing the -search template, you may wish to bind some shortcuts to keys. This can -be done with the variable @code{mh-search-mode-hook}, which is called -when @kbd{F s} is run on a new pattern. - -@findex mh-index-do-search -@findex mh-pick-do-search -@kindex C-c C-c -@kindex C-c C-p - -To perform the search, type @kbd{C-c C-c} (@code{mh-index-do-search}). -Sometimes you're searching for text that is either not indexed, or -hasn't been indexed yet. In this case you can override the default -method with the pick method by running the command @kbd{C-c C-p} -(@code{mh-pick-do-search}). - -@cindex folders, @samp{+mhe-index} -@cindex @samp{+mhe-index} -@findex mh-index-next-folder -@findex mh-index-previous-folder -@kindex @key{TAB} -@kindex S-@key{TAB} -@vindex mh-search-folder - -The messages that are found are put in a temporary sub-folder of -@samp{+mhe-index} and are displayed in an MH-Folder buffer. This -buffer is special because it displays messages from multiple folders; -each set of messages from a given folder has a heading with the folder -name. The appearance of the heading can be modified by customizing the -face @code{mh-search-folder}. You can jump back and forth between the -headings using the commands @kbd{@key{TAB}} -(@code{mh-index-next-folder}) and @kbd{S-@key{TAB}} -(@code{mh-index-previous-folder}). - -@findex mh-index-visit-folder -@findex mh-rescan-folder -@kindex F r -@kindex v - -In addition, the command @kbd{v} (@code{mh-index-visit-folder}) can be -used to visit the folder of the message at point. Initially, only the -messages that matched the search criteria are displayed in the folder. -While the temporary buffer has its own set of message numbers, the -actual messages numbers are shown in the visited folder. Thus, the -command @kbd{v} is useful to find the actual message number of an -interesting message, or to view surrounding messages with the command -@kbd{F r} @code{mh-rescan-folder}. @xref{Folders}. - -@findex mh-kill-folder -@kindex F k - -Because this folder is temporary, you'll probably get in the habit of -killing it when you're done with @kbd{F k} (@code{mh-kill-folder}). -@xref{Folders}. - -@kindex F s - -You can regenerate the results by running @kbd{F s} with a prefix -argument. - -@cindex @command{procmail} -@cindex Unix commands, @command{procmail} -@cindex @samp{X-MHE-Checksum:} header field -@cindex header field, @samp{X-MHE-Checksum:} - -Note: This command uses an @samp{X-MHE-Checksum:} header field to -cache the MD5 checksum of a message. This means that if an incoming -message already contains an @samp{X-MHE-Checksum:} field, that message -might not be found by this command. The following @command{procmail} -recipe avoids this problem by renaming the existing header field: - -@smallexample -@group -:0 wf -| formail -R "X-MHE-Checksum" "X-Old-MHE-Checksum" -@end group -@end smallexample - -@xref{Limits}, for an alternative interface to searching. - -@section Configuring Indexed Searches - -@cindex @command{grep} -@cindex @command{mairix} -@cindex @command{namazu} -@cindex @command{pick} -@cindex @command{swish++} -@cindex @command{swish-e} -@cindex Unix commands, @command{grep} -@cindex Unix commands, @command{mairix} -@cindex Unix commands, @command{namazu} -@cindex Unix commands, @command{pick} -@cindex Unix commands, @command{swish++} -@cindex Unix commands, @command{swish-e} -@findex mh-search -@kindex F s -@vindex mh-search-program - -The command @kbd{F s} (@code{mh-search}) runs the command defined by -the option @code{mh-search-program}. The default value is -@samp{Auto-detect} which means that MH-E will automatically choose one -of @command{swish++}, @command{swish-e}, @command{mairix}, -@command{namazu}, @command{pick} and @command{grep} in that order. If, -for example, you have both @command{swish++} and @command{mairix} -installed and you want to use @command{mairix}, then you can set this -option to @samp{mairix}. - -The following sub-sections describe how to set up the various indexing -programs to use with MH-E. - -@subsection swish++ - -@cindex @command{swish++} -@cindex Unix commands, @command{swish++} - -In the examples below, replace @file{/home/user/Mail} with the path to -your MH directory. - -First create the directory @file{/home/user/Mail/.swish++}. Then -create the file @file{/home/user/Mail/.swish++/swish++.conf} with the -following contents: - -@smallexample -@group -IncludeMeta Bcc Cc Comments Content-Description From Keywords -IncludeMeta Newsgroups Resent-To Subject To -IncludeMeta Message-Id References In-Reply-To -IncludeFile Mail * -IndexFile /home/user/Mail/.swish++/swish++.index -@end group -@end smallexample - -Use the following command line to generate the swish index. Run this -daily from cron: - -@smallexample -@group -find /home/user/Mail -path /home/user/Mail/mhe-index -prune \ - -o -path /home/user/Mail/.swish++ -prune \ - -o -name "[0-9]*" -print \ - | index -c /home/user/Mail/.swish++/swish++.conf - -@end group -@end smallexample - -This command does not index the folders that hold the results of your -searches in @samp{+mhe-index} since they tend to be ephemeral and the -original messages are indexed anyway. - -@cindex @command{index} -@cindex Unix commands, @command{index} -@cindex @command{index++} -@cindex Unix commands, @command{index++} - -On some systems (Debian GNU/Linux, for example), use @command{index++} -instead of @command{index}. - -@subsection swish - -@cindex @command{swish-e} -@cindex Unix commands, @command{swish-e} - -In the examples below, replace @file{/home/user/Mail} with the path to -your MH directory. - -First create the directory @file{/home/user/Mail/.swish}. Then create -the file @file{/home/user/Mail/.swish/config} with the following -contents: - -@smallexample -@group -DefaultContents TXT* -IndexDir /home/user/Mail -IndexFile /home/user/Mail/.swish/index -IndexName "Mail Index" -IndexDescription "Mail Index" -IndexPointer "http://nowhere" -IndexAdmin "nobody" -#MetaNames automatic -IndexReport 3 -FollowSymLinks no -UseStemming no -IgnoreTotalWordCountWhenRanking yes -WordCharacters abcdefghijklmnopqrstuvwxyz0123456789- -BeginCharacters abcdefghijklmnopqrstuvwxyz -EndCharacters abcdefghijklmnopqrstuvwxyz0123456789 -IgnoreLimit 50 1000 -IndexComments 0 -FileRules filename contains \D -FileRules pathname contains /home/user/Mail/.swish -FileRules pathname contains /home/user/Mail/mhe-index -FileRules filename is index -@end group -@end smallexample - -This configuration does not index the folders that hold the results of -your searches in @samp{+mhe-index} since they tend to be ephemeral and -the original messages are indexed anyway. - -If there are any directories you would like to ignore, append lines -like the following to @file{config}: - -@smallexample -FileRules pathname contains /home/user/Mail/scripts -@end smallexample - -@cindex @command{swish-e} -@cindex Unix commands, @command{swish-e} - -Use the following command line to generate the swish index. Run this -daily from cron: - -@smallexample -swish-e -c /home/user/Mail/.swish/config -@end smallexample - -@subsection mairix - -@cindex @command{mairix} -@cindex Unix commands, @command{mairix} - -In the examples below, replace @file{/home/user/Mail} with the path to -your MH directory. - -First create the directory @file{/home/user/Mail/.mairix}. Then create -the file @file{/home/user/Mail/.mairix/config} with the following -contents: - -@smallexample -@group -base=/home/user/Mail - -# List of folders that should be indexed. 3 dots at the end means there -# are subfolders within the folder -mh=archive...:inbox:drafts:news:sent:trash - -vfolder_format=mh -database=/home/user/Mail/.mairix/database -@end group -@end smallexample - -Use the following command line to generate the mairix index. Run this daily -from cron: - -@smallexample -mairix -f /home/user/Mail/.mairix/config -@end smallexample - -@subsection namazu - -@cindex @command{namazu} -@cindex Unix commands, @command{namazu} - -In the examples below, replace @file{/home/user/Mail} with the path to -your MH directory. - -First create the directory @file{/home/user/Mail/.namazu}. Then create -the file @file{/home/user/Mail/.namazu/mknmzrc} with the following -contents: - -@smallexample -@group -package conf; # Don't remove this line! -$ADDRESS = 'user@@localhost'; -$ALLOW_FILE = "[0-9]*"; -$EXCLUDE_PATH = "^/home/user/Mail/(mhe-index|spam)"; -@end group -@end smallexample - -This configuration does not index the folders that hold the results of -your searches in @samp{+mhe-index} since they tend to be ephemeral and -the original messages are indexed anyway. - -Use the following command line to generate the namazu index. Run this -daily from cron: - -@smallexample -mknmz -f /home/user/Mail/.namazu/mknmzrc -O /home/user/Mail/.namazu \ - -q /home/user/Mail -@end smallexample - -@subsection pick - -@cindex @command{pick} -@cindex MH commands, @command{pick} - -This search method does not require any setup. - -Read @command{pick}(1) or the section -@uref{@value{MH-BOOK-HOME}/finpic.html, Finding Messages with pick} in -the MH book to find out more about how to enter the criteria. - -@subsection grep - -@cindex @command{grep} -@cindex Unix commands, @command{grep} - -This search method does not require any setup. - -Unlike the other search methods, this method does not use the -MH-Search buffer. Instead, you simply enter a regular expression in -the minibuffer. For help in constructing regular expressions, see your -man page for @command{grep}. - -@node Threading, Limits, Searching, Top -@chapter Viewing Message Threads - -@cindex threading - -MH-E groups messages by @dfn{threads} which are messages that are part -of the same discussion and usually all have the same @samp{Subject:} -header field. Other ways to organize messages in a folder include -limiting (@pxref{Limits}) or using full-text indexed searches -(@pxref{Searching}). - -@cindex root, in threads -@cindex siblings, in threads -@cindex ancestor, in threads - -A thread begins with a single message called a @dfn{root}. All replies -to the same message are @dfn{siblings} of each other. Any message that -has replies to it is an @dfn{ancestor} of those replies. - -There are several commands that you can use to navigate and operate on -threads. - -@table @kbd -@kindex T ? -@findex mh-prefix-help -@item T ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@kindex T o -@findex mh-thread-refile -@item T o -Refile (output) thread into folder (@code{mh-thread-refile}). -@c ------------------------- -@kindex T d -@findex mh-thread-delete -@item T d -Delete thread (@code{mh-thread-delete}). -@c ------------------------- -@kindex T t -@findex mh-toggle-threads -@item T t -Toggle threaded view of folder (@code{mh-toggle-threads}). -@c ------------------------- -@kindex T n -@findex mh-thread-next-sibling -@item T n -Display next sibling (@code{mh-thread-next-sibling}). -@c ------------------------- -@kindex T p -@findex mh-thread-previous-sibling -@item T p -Display previous sibling (@code{mh-thread-previous-sibling}). -@c ------------------------- -@kindex T u -@findex mh-thread-ancestor -@item T u -Display ancestor of current message (@code{mh-thread-ancestor}). -@end table - -@cindex @samp{mh-thread} customization group -@cindex customization group, @samp{mh-thread} - -The @samp{mh-thread} customization group contains one option. - -@vtable @code -@item mh-show-threads-flag -On means new folders start in threaded mode (default: @samp{off}). -@end vtable - -@findex mh-toggle-threads -@kindex T t -@vindex mh-large-folder -@vindex mh-show-threads-flag - -Threading large number of messages can be time consuming so the option -@code{mh-show-threads-flag} is turned off by default. If you turn on -this option, then threading will be done only if the number of -messages being threaded is less than @code{mh-large-folder}. In any -event, threading can be turned on (and off) with the command @kbd{T t} -(@code{mh-toggle-threads}). - -@findex mh-thread-ancestor -@findex mh-thread-next-sibling -@findex mh-thread-previous-sibling -@kindex T n -@kindex T p -@kindex T u - -There are a few commands to help you navigate threads. If you do not -care for the way a particular thread has turned, you can move up the -chain of messages with the command @kbd{T u} -(@code{mh-thread-ancestor}. At any point you can use @kbd{T n} -(@code{mh-thread-next-sibling} or @kbd{T p} -(@code{mh-thread-previous-sibling}) to jump to the next or previous -sibling, skipping the sub-threads. The command @kbd{T u} can also take -a prefix argument to jump to the message that started everything. - -@findex mh-delete-subject-or-thread -@findex mh-thread-delete -@findex mh-thread-refile -@kindex k -@kindex T d -@kindex T o - -There are threaded equivalents for the commands that delete and refile -messages. For example, @kbd{T o} (@code{mh-thread-refile}) refiles the -current message and all its children. Similarly, the command @kbd{T d} -(@code{mh-thread-delete}) deletes the current message and all its -children. These commands do not refile or delete sibling messages. -@xref{Navigating}, for a description of the similar command @kbd{k} -(@code{mh-delete-subject-or-thread}). - -@vindex mh-large-folder - -If you find that threading is too slow, it may be that you have -@code{mh-large-folder} set too high. Also, threading is one of the few -features of MH-E that really benefits from compiling. If you haven't -compiled MH-E, I encourage you to do so@footnote{If you're not sure if -MH-E has been byte-compiled, you could try running @samp{locate -mh-thread.elc} or otherwise find MH-E on your system and ensure that -@file{mh-thread.elc} exists. If you have multiple versions and you -find that one is compiled but the other is not, then go into your -@samp{*scratch*} buffer in Emacs, enter @kbd{load-path C-j}, and -ensure that the byte-compiled version appears first in the -@code{load-path}. If you find that MH-E is not compiled and you -installed MH-E yourself, please refer to the installation directions -in the file @file{README} in the distribution.}. - -@node Limits, Sequences, Threading, Top -@chapter Limiting Display - -@cindex limits -@cindex filters - -Another way to organize messages in a folder besides threading -(@pxref{Threading}) or using full-text indexed searches -(@pxref{Searching}) is by limiting the folder display to messages that -are similar to the current message. - -@table @kbd -@kindex / ? -@findex mh-prefix-help -@item / ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@cindex @samp{Sequence > Narrow to Tick Sequence} menu item -@cindex menu item, @samp{Sequence > Narrow to Tick Sequence} -@kindex / ' -@findex mh-narrow-to-tick -@item / ' -Limit to messages in the @samp{tick} sequence -(@code{mh-narrow-to-tick}). -@c ------------------------- -@kindex / c -@findex mh-narrow-to-cc -@item / c -Limit to messages with the same @samp{Cc:} field -(@code{mh-narrow-to-cc}). -@c ------------------------- -@kindex / m -@findex mh-narrow-to-from -@item / m -Limit to messages with the same @samp{From:} field -(@code{mh-narrow-to-from}). -@c ------------------------- -@kindex / g -@findex mh-narrow-to-range -@item / g -Limit to range (@code{mh-narrow-to-range}). -@c ------------------------- -@cindex @samp{Sequence > Narrow to Subject Sequence} menu item -@cindex menu item, @samp{Sequence > Narrow to Subject Sequence} -@kindex / s -@findex mh-narrow-to-subject -@item / s -Limit to messages with the same @samp{Subject:} field -(@code{mh-narrow-to-subject}). -@c ------------------------- -@kindex / t -@findex mh-narrow-to-to -@item / t -Limit to messages with the same @samp{To:} field -(@code{mh-narrow-to-to}). -@c ------------------------- -@cindex @samp{Sequence > Widen from Sequence} menu item -@cindex menu item, @samp{Sequence > Widen from Sequence} -@kindex / w -@findex mh-widen -@item / w -Remove last restriction (@code{mh-widen}). -@end table - -All of the limiting commands above refine the display in some way. - -@cindex @command{pick} -@cindex MH commands, @command{pick} -@findex mh-narrow-to-cc -@findex mh-narrow-to-from -@findex mh-narrow-to-subject -@findex mh-narrow-to-to -@kindex / c -@kindex / m -@kindex / s -@kindex / t - -The commands @kbd{/ c} (@code{mh-narrow-to-cc}), @kbd{/ m} -(@code{mh-narrow-to-from}), @kbd{/ s} (@code{mh-narrow-to-subject}), -and @kbd{/ t} (@code{mh-narrow-to-to}) restrict the display to -messages matching the content of the respective field in the current -message. However, you can give any of these a prefix argument to edit -the @command{pick} expression used to narrow the view@footnote{See -@command{pick}(1) or the section -@uref{@value{MH-BOOK-HOME}/finpic.html, Finding Messages with pick} in -the MH book.}. - -@cindex @samp{tick} sequence -@cindex sequence, @samp{tick} -@cindex ticked messages, viewing -@findex mh-narrow-to-range -@findex mh-narrow-to-tick -@kindex / ' -@kindex / g - -You can also limit the display to messages in the @samp{tick} sequence -with the command @kbd{/ '} (@code{mh-narrow-to-tick}). -@xref{Sequences}, for information on putting message into the -@samp{tick} sequence. Use the @kbd{/ g} (@code{mh-narrow-to-range}) -command to limit the display to messages in a range (@pxref{Ranges}). - -@findex mh-widen -@kindex / w - -Each limit can be undone in turn with the @kbd{/ w} (@code{mh-widen}) -command. Give this command a prefix argument to remove all limits. - -@node Sequences, Junk, Limits, Top -@chapter Using Sequences - -@cindex @samp{Sequence} menu -@cindex menu, @samp{Sequence} -@cindex sequences - -For the whole scoop on MH sequences, refer to -@samp{mh-sequence}(5)@footnote{See the section -@uref{@value{MH-BOOK-HOME}/morseq.html, More About Sequences} in the MH -book.}. As you've read, several of the MH-E commands can operate on a -sequence, which is a shorthand for a range or group of messages. For -example, you might want to forward several messages to a friend or -colleague. Here's how to manipulate sequences. These commands are also -available in the @samp{Sequence} menu. - -@table @kbd -@cindex @samp{Sequence > Toggle Tick Mark} menu item -@cindex menu item, @samp{Sequence > Toggle Tick Mark} -@kindex ' -@findex mh-toggle-tick -@item ' -Toggle tick mark of range (@code{mh-toggle-tick}). -@c ------------------------- -@kindex S ? -@findex mh-prefix-help -@item S ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@cindex @samp{Sequence > Narrow to Tick Sequence} menu item -@cindex menu item, @samp{Sequence > Narrow to Tick Sequence} -@kindex S ' -@findex mh-narrow-to-tick -@item S ' -Limit to ticked messages (@code{mh-narrow-to-tick}). -@c ------------------------- -@cindex @samp{Sequence > Delete Message from Sequence...} menu item -@cindex menu item, @samp{Sequence > Delete Message from Sequence...} -@kindex S d -@findex mh-delete-msg-from-seq -@item S d -Delete range from sequence (@code{mh-delete-msg-from-seq}). -@c ------------------------- -@cindex @samp{Sequence > Delete Sequence...} menu item -@cindex menu item, @samp{Sequence > Delete Sequence...} -@kindex S k -@findex mh-delete-seq -@item S k -Delete sequence (@code{mh-delete-seq}). -@c ------------------------- -@cindex @samp{Sequence > List Sequences in Folder...} menu item -@cindex menu item, @samp{Sequence > List Sequences in Folder...} -@kindex S l -@findex mh-list-sequences -@item S l -List all sequences in folder (@code{mh-list-sequences}). -@c ------------------------- -@cindex @samp{Sequence > Narrow to Sequence...} menu item -@cindex menu item, @samp{Sequence > Narrow to Sequence...} -@kindex S n -@findex mh-narrow-to-seq -@item S n -Restrict display to messages in sequence (@code{mh-narrow-to-seq}). -@c ------------------------- -@cindex @samp{Sequence > Add Message to Sequence...} menu item -@cindex menu item, @samp{Sequence > Add Message to Sequence...} -@kindex S p -@findex mh-put-msg-in-seq -@item S p -Add range to sequence (@code{mh-put-msg-in-seq}). -@c ------------------------- -@cindex @samp{Sequence > List Sequences for Message} menu item -@cindex menu item, @samp{Sequence > List Sequences for Message} -@kindex S s -@findex mh-msg-is-in-seq -@item S s -Display the sequences in which the current message appears -(@code{mh-msg-is-in-seq}). -@c ------------------------- -@cindex @samp{Sequence > Widen from Sequence} menu item -@cindex menu item, @samp{Sequence > Widen from Sequence} -@kindex S w -@findex mh-widen -@item S w -Remove last restriction (@code{mh-widen}). -@c ------------------------- -@findex mh-update-sequences -@item M-x mh-update-sequences -Flush MH-E's state out to MH@. -@end table - -@cindex @samp{mh-sequences} customization group -@cindex customization group, @samp{mh-sequences} - -The @samp{mh-sequences} customization group contains the options -associated with sequences. - -@vtable @code -@item mh-refile-preserves-sequences-flag -On means that sequences are preserved when messages are refiled -(default: @samp{on}). -@c ------------------------- -@item mh-tick-seq -The name of the MH sequence for ticked messages (default: @samp{'tick}). -@c ------------------------- -@item mh-update-sequences-after-mh-show-flag -On means flush MH sequences to disk after message is shown (default: -@samp{on}). -@end vtable - -The following hook is available. - -@vtable @code -@item mh-unseen-updated-hook -Hook run after the unseen sequence has been updated (default: @code{nil}). -@end vtable - -@cindex @command{pick} -@cindex MH commands, @command{pick} -@findex mh-put-msg-in-seq -@kindex S p - -To place a message in a sequence, use @kbd{S p} -(@code{mh-put-msg-in-seq}). Give @kbd{S p} a range and you can add all -the messages in a sequence to another sequence (for example, @kbd{C-u -S p SourceSequence @key{RET} DestSequence @key{RET}}, @pxref{Ranges}). - -@cindex @samp{tick} sequence -@cindex sequence, @samp{tick} -@cindex ticking messages -@findex mh-index-ticked-messages -@findex mh-toggle-tick -@kindex ' -@kindex F ' -@kindex S p - -One specific use of the @kbd{S p} command is @kbd{'} -(@code{mh-toggle-tick}) which adds messages to the @samp{tick} -sequence. This sequence can be viewed later with the @kbd{F '} -(@code{mh-index-ticked-messages}) command (@pxref{Folders}). - -@vindex mh-tick-seq - -You can customize the option @code{mh-tick-seq} if you already use the -@samp{tick} sequence for your own use. You can also disable all of the -ticking functions by choosing the @samp{Disable Ticking} item but -there isn't much advantage to that. - -@cindex MH-Folder mode -@cindex modes, MH-Folder -@findex mh-narrow-to-seq -@findex mh-narrow-to-tick -@findex mh-widen -@kindex S ' -@kindex S n -@kindex S w - -Once you've placed some messages in a sequence, you may wish to narrow -the field of view to just those messages in the sequence you've -created. To do this, use @kbd{S n} (@code{mh-narrow-to-seq}). You are -prompted for the name of the sequence. What this does is show only -those messages that are in the selected sequence in the MH-Folder -buffer. In addition, it limits further MH-E searches to just those -messages. To narrow the view to the messages in the @samp{tick} -sequence, use @kbd{S '} (@code{mh-narrow-to-tick}). When you want to -widen the view to all your messages again, use @kbd{S w} -(@code{mh-widen}). - -@cindex buffers, @samp{*MH-E Sequences*} -@cindex @samp{*MH-E Sequences*} -@findex mh-list-sequences -@findex mh-msg-is-in-seq -@kindex S l -@kindex S s - -You can see which sequences in which a message appears with the -command @kbd{S s} (@code{mh-msg-is-in-seq}). Use a prefix argument to -display the sequences in which another message appears (as in @kbd{C-u -42 S s @key{RET}}). Or, you can list all sequences in a selected -folder (default is current folder) with @kbd{S l} -(@code{mh-list-sequences}). The list appears in a buffer named -@samp{*MH-E Sequences*} (@pxref{Miscellaneous}). - -@cindex MH profile component, @samp{Previous-Sequence:} -@cindex @samp{cur} sequence -@cindex @samp{Previous-Sequence:} MH profile component -@cindex sequence, @samp{cur} -@cindex sequence, @samp{Previous-Sequence} -@vindex mh-refile-preserves-sequences-flag - -If a message is in any sequence (except -@samp{Previous-Sequence:}@footnote{See @samp{mh-profile}(5)).} and -@samp{cur}) when it is refiled, then it will still be in those -sequences in the destination folder. If this behavior is not desired, -then turn off the option @code{mh-refile-preserves-sequences-flag}. - -@findex mh-delete-msg-from-seq -@findex mh-delete-seq -@kindex d -@kindex S d -@kindex S k - -If you want to remove a message (or range, @pxref{Ranges}) from a -sequence, use @kbd{S d} (@code{mh-delete-msg-from-seq}). If you want -to delete an entire sequence, use @kbd{S k} (@code{mh-delete-seq}). In -the latter case you are prompted for the sequence to delete. Note that -this deletes only the sequence, not the messages in the sequence. If -you want to delete the messages, use @kbd{C-u d} (@pxref{Reading -Mail}). - -@cindex @samp{Unseen-Sequence:} MH profile component -@cindex @samp{cur} sequence -@cindex @samp{tick} sequence -@cindex MH profile component, @samp{Unseen-Sequence:} -@cindex sequence, @samp{Unseen-Sequence} -@cindex sequence, @samp{cur} -@cindex sequence, @samp{tick} -@findex mh-update-sequences -@kindex M-x mh-update-sequences -@kindex q -@kindex x -@vindex mh-tick-seq -@vindex mh-update-sequences-after-mh-show-flag - -Three sequences are maintained internally by MH-E and pushed out to MH -when a message is shown. They include the sequence specified by your -@samp{Unseen-Sequence:} profile component, @samp{cur}, and the -sequence listed by the option @code{mh-tick-seq} which is @samp{tick} -by default. If you do not like this behavior, turn off the option -@code{mh-update-sequences-after-mh-show-flag}. You can then update the -state manually with the @kbd{x}, @kbd{q}, or @kbd{M-x -mh-update-sequences} commands. - -@vindex mh-seen-list -@vindex mh-unseen-updated-hook - -The hook @code{mh-unseen-updated-hook} is run after the unseen -sequence has been updated. The variable @code{mh-seen-list} can be -used by this hook to obtain the list of messages which were removed -from the unseen sequence. - -@cindex @command{mark} -@cindex MH commands, @command{mark} -@kindex S n -@kindex S w - -With the exceptions of @kbd{S n} and @kbd{S w}, the underlying MH -command dealing with sequences is @command{mark}@footnote{See the -section @uref{@value{MH-BOOK-HOME}/mmbwm.html, Make Message Bookmarks -with mark} in the MH book.}. - -@node Junk, Miscellaneous, Sequences, Top -@chapter Dealing With Junk Mail - -@cindex Marshall Rose -@cindex junk mail -@cindex spam - -Marshall Rose once wrote a paper on MH entitled, @cite{How to process -200 messages a day and still get some real work done}. This chapter -could be entitled, @cite{How to process 1000 spams a day and still get -some real work done}. - -@cindex blacklisting -@cindex ham -@cindex viruses -@cindex whitelisting -@cindex worms - -We use the terms @dfn{junk mail} and @dfn{spam} interchangeably for -any unwanted message which includes spam, @dfn{viruses}, and -@dfn{worms}. The opposite of spam is @dfn{ham}. The act of classifying -a sender as one who sends junk mail is called @dfn{blacklisting}; the -opposite is called @dfn{whitelisting}. - -@table @kbd -@kindex J ? -@findex mh-prefix-help -@item J ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@kindex J b -@findex mh-junk-blacklist -@item J b -Blacklist range as spam (@code{mh-junk-blacklist}). -@c ------------------------- -@kindex J w -@findex mh-junk-whitelist -@item J w -Whitelist range as ham (@code{mh-junk-whitelist}). -@c ------------------------- -@item @code{mh-spamassassin-identify-spammers} -Identify spammers who are repeat offenders. -@end table - -@cindex @samp{mh-junk} customization group -@cindex customization group, @samp{mh-junk} - -The following table lists the options from the @samp{mh-junk} -customization group. - -@vtable @code -@item mh-junk-background -If on, spam programs are run in background (default: @samp{off}). -@c ------------------------- -@item mh-junk-disposition -Disposition of junk mail (default: @samp{Delete Spam}). -@c ------------------------- -@item mh-junk-program -Spam program that MH-E should use (default: @samp{Auto-detect}). -@end vtable - -@cindex SpamProbe -@cindex Spamassassin -@cindex bogofilter -@cindex spam filters, SpamProbe -@cindex spam filters, Spamassassin -@cindex spam filters, bogofilter - -MH-E depends on @uref{http://spamassassin.apache.org/, SpamAssassin}, -@uref{http://bogofilter.sourceforge.net/, bogofilter}, or -@uref{http://spamprobe.sourceforge.net/, SpamProbe} to throw the dreck -away. This chapter describes briefly how to configure these programs -to work well with MH-E and how to use MH-E's interface that provides -continuing education for these programs. - -@vindex mh-junk-program - -The default setting of the option @code{mh-junk-program} is -@samp{Auto-detect} which means that MH-E will automatically choose one -of SpamAssassin, bogofilter, or SpamProbe in that order. If, for -example, you have both SpamAssassin and bogofilter installed and you -want to use bogofilter, then you can set this option to -@samp{Bogofilter}. - -@findex mh-junk-blacklist -@kindex J b -@vindex mh-junk-disposition - -The command @kbd{J b} (@code{mh-junk-blacklist}) trains the spam -program in use with the content of the range (@pxref{Ranges}) and then -handles the message(s) as specified by the option -@code{mh-junk-disposition}. By default, this option is set to -@samp{Delete Spam} but you can also specify the name of the folder -which is useful for building a corpus of spam for training purposes. - -@findex mh-junk-whitelist -@kindex J w - -In contrast, the command @kbd{J w} (@code{mh-junk-whitelist}) -reclassifies a range of messages (@pxref{Ranges}) as ham if it were -incorrectly classified as spam. It then refiles the message into the -@file{+inbox} folder. - -@cindex @samp{*MH-E Log*} -@cindex buffers, @samp{*MH-E Log*} -@findex call-process -@vindex mh-junk-background - -By default, the programs are run in the foreground, but this can be -slow when junking large numbers of messages. If you have enough memory -or don't junk that many messages at the same time, you might try -turning on the option @code{mh-junk-background}. @footnote{Note that -the option @code{mh-junk-background} is used as the @code{display} -argument in the call to @code{call-process}. Therefore, turning on -this option means setting its value to @samp{0}. You can also set its -value to @samp{t} to direct the programs' output to the @samp{*MH-E -Log*} buffer; this may be useful for debugging.} - -The following sections discuss the various counter-spam measures that -MH-E can work with. - -@cindex @file{.procmailrc} -@cindex files, @file{.procmailrc} - -@subheading SpamAssassin - -@cindex Spamassassin -@cindex spam filters, Spamassassin - -SpamAssassin is one of the more popular spam filtering programs. Get -it from your local distribution or from the -@uref{http://spamassassin.apache.org/, SpamAssassin web site}. - -To use SpamAssassin, add the following recipes to @file{~/.procmailrc}: - -@cindex @command{spamc} -@cindex @samp{X-Spam-Level:} header field -@cindex @samp{X-Spam-Status:} header field -@cindex header field, @samp{X-Spam-Level:} -@cindex header field, @samp{X-Spam-Status:} - -@smallexample -PATH=$PATH:/usr/bin/mh -MAILDIR=$HOME/`mhparam Path` - -# Fight spam with SpamAssassin. -:0fw -| spamc - -# Anything with a spam level of 10 or more is junked immediately. -:0: -* ^X-Spam-Level: .......... -/dev/null - -:0: -* ^X-Spam-Status: Yes -spam/. -@end smallexample - -If you don't use @command{spamc}, use @samp{spamassassin -P -a}. - -Note that one of the recipes above throws away messages with a score -greater than or equal to 10. Here's how you can determine a value that -works best for you. - -First, run @samp{spamassassin -t} on every mail message in your -archive and use @command{gnumeric} to verify that the average plus the -standard deviation of good mail is under 5, the SpamAssassin default -for ``spam''. - -Using @command{gnumeric}, sort the messages by score and view the -messages with the highest score. Determine the score which encompasses -all of your interesting messages and add a couple of points to be -conservative. Add that many dots to the @samp{X-Spam-Level:} header -field above to send messages with that score down the drain. - -In the example above, messages with a score of 5-9 are set aside in -the @samp{+spam} folder for later review. The major weakness of -rules-based filters is a plethora of false positives so it is -worthwhile to check. - -@findex mh-junk-blacklist -@findex mh-junk-whitelist -@kindex J b -@kindex J w - -If SpamAssassin classifies a message incorrectly, or is unsure, you can -use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and -@kbd{J w} (@code{mh-junk-whitelist}). - -@cindex @command{sa-learn} -@cindex @file{.spamassassin/user_prefs} -@cindex files, @file{.spamassassin/user_prefs} - -The command @kbd{J b} (@code{mh-junk-blacklist}) adds a -@samp{blacklist_from} entry to @file{~/spamassassin/user_prefs}, -deletes the message, and sends the message to the Razor, so that -others might not see this spam. If the @command{sa-learn} command is -available, the message is also recategorized as spam. - -The command@kbd{J w} (@code{mh-junk-whitelist}) adds a -@samp{whitelist_from} rule to @samp{~/.spamassassin/user_prefs}. If -the @command{sa-learn} command is available, the message is also -recategorized as ham. - -Over time, you'll observe that the same host or domain occurs -repeatedly in the @samp{blacklist_from} entries, so you might think -that you could avoid future spam by blacklisting all mail from a -particular domain. The utility function -@code{mh-spamassassin-identify-spammers} helps you do precisely that. -This function displays a frequency count of the hosts and domains in -the @samp{blacklist_from} entries from the last blank line in -@file{~/.spamassassin/user_prefs} to the end of the file. This -information can be used so that you can replace multiple -@samp{blacklist_from} entries with a single wildcard entry such as: - -@smallexample -blacklist_from *@@*amazingoffersdirect2u.com -@end smallexample - -In versions of SpamAssassin (2.50 and on) that support a Bayesian -classifier, @kbd{J b} @code{(mh-junk-blacklist}) uses the program -@command{sa-learn} to recategorize the message as spam. Neither MH-E, -nor SpamAssassin, rebuilds the database after adding words, so you -will need to run @samp{sa-learn --rebuild} periodically. This can be -done by adding the following to your @file{crontab}: - -@smallexample -0 * * * * sa-learn --rebuild > /dev/null 2>&1 -@end smallexample - -@subheading Bogofilter - -@cindex bogofilter -@cindex spam filters, bogofilter - -Bogofilter is a Bayesian spam filtering program. Get it from your -local distribution or from the -@uref{http://bogofilter.sourceforge.net/, bogofilter web site}. - -Bogofilter is taught by running: - -@smallexample -bogofilter -n < good-message -@end smallexample - -on every good message, and - -@smallexample -bogofilter -s < spam-message -@end smallexample - -@cindex full training - -on every spam message. This is called a @dfn{full training}; three -other training methods are described in the FAQ that is distributed -with bogofilter. Note that most Bayesian filters need 1000 to 5000 of -each type of message to start doing a good job. - -To use bogofilter, add the following recipes to @file{~/.procmailrc}: - -@cindex @samp{X-Bogosity:} header field -@cindex header field, @samp{X-Bogosity:} - -@smallexample -PATH=$PATH:/usr/bin/mh -MAILDIR=$HOME/`mhparam Path` - -# Fight spam with Bogofilter. -:0fw -| bogofilter -3 -e -p - -:0: -* ^X-Bogosity: Yes, tests=bogofilter -spam/. - -:0: -* ^X-Bogosity: Unsure, tests=bogofilter -spam/unsure/. -@end smallexample - -@findex mh-junk-blacklist -@findex mh-junk-whitelist -@kindex J b -@kindex J w - -If bogofilter classifies a message incorrectly, or is unsure, you can -use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J -w} (@code{mh-junk-whitelist}) to update bogofilter's training. - -The @cite{Bogofilter FAQ} suggests that you run the following -occasionally to shrink the database: - -@smallexample -bogoutil -d wordlist.db | bogoutil -l wordlist.db.new -mv wordlist.db wordlist.db.prv -mv wordlist.db.new wordlist.db -@end smallexample - -The @cite{Bogofilter tuning HOWTO} describes how you can fine-tune -bogofilter. - -@subheading SpamProbe - -@cindex SpamProbe -@cindex spam filters, SpamProbe - -SpamProbe is a Bayesian spam filtering program. Get it from your local -distribution or from the @uref{http://spamprobe.sourceforge.net, -SpamProbe web site}. - -To use SpamProbe, add the following recipes to @file{~/.procmailrc}: - -@cindex @command{formail} -@cindex @samp{X-SpamProbe:} header field -@cindex header field, @samp{X-SpamProbe:} - -@smallexample -PATH=$PATH:/usr/bin/mh -MAILDIR=$HOME/`mhparam Path` - -# Fight spam with SpamProbe. -:0 -SCORE=| spamprobe receive - -:0 wf -| formail -I "X-SpamProbe: $SCORE" - -:0: -*^X-SpamProbe: SPAM -spam/. -@end smallexample - -@findex mh-junk-blacklist -@findex mh-junk-whitelist -@kindex J b -@kindex J w - -If SpamProbe classifies a message incorrectly, you can use the MH-E -commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J w} -(@code{mh-junk-whitelist}) to update SpamProbe's training. - -@subheading Other Things You Can Do - -There are a couple of things that you can add to @file{~/.procmailrc} -in order to filter out a lot of spam and viruses. The first is to -eliminate any message with a Windows executable (which is most likely -a virus). The second is to eliminate mail in character sets that you -can't read. - -@cindex @samp{Content-Transfer-Encoding:} header field -@cindex @samp{Content-Type:} header field -@cindex @samp{Subject:} header field -@cindex header field, @samp{Content-Transfer-Encoding:} -@cindex header field, @samp{Content-Type:} -@cindex header field, @samp{Subject:} - -@smallexample -PATH=$PATH:/usr/bin/mh -MAILDIR=$HOME/`mhparam Path` - -# -# Filter messages with win32 executables/virii. -# -# These attachments are base64 and have a TVqQAAMAAAAEAAAA//8AALg -# pattern. The string "this program cannot be run in MS-DOS mode" -# encoded in base64 is 4fug4AtAnNIbg and helps to avoid false -# positives (Roland Smith via Pete from the bogofilter mailing list). -# -:0 B: -* ^Content-Transfer-Encoding:.*base64 -* ^TVqQAAMAAAAEAAAA//8AALg -* 4fug4AtAnNIbg -spam/exe/. - -# -# Filter mail in unreadable character sets (from the Bogofilter FAQ). -# -UNREADABLE='[^?"]*big5|iso-2022-jp|ISO-2022-KR|euc-kr|gb2312|ks_c_5601-1987' - -:0: -* 1^0 $ ^Subject:.*=\?($UNREADABLE) -* 1^0 $ ^Content-Type:.*charset="?($UNREADABLE) -spam/unreadable/. - -:0: -* ^Content-Type:.*multipart -* B ?? $ ^Content-Type:.*^?.*charset="?($UNREADABLE) -spam/unreadable/. -@end smallexample - -@node Miscellaneous, Scan Line Formats, Junk, Top -@chapter Miscellaneous Commands, Variables, and Buffers - -This chapter covers the following command and the various MH-E -buffers, - -@ftable @code -@item mh-version -Display version information about MH-E and the MH mail handling -system. -@end ftable - -@cindex buffers, @samp{*MH-E Info*} -@cindex MH-E version -@cindex @samp{*MH-E Info*} -@cindex version -@kindex M-x mh-version - -One command worth noting is @kbd{M-x mh-version}. You can compare the -version this command prints to the latest release (@pxref{Getting -MH-E}). The output of @kbd{M-x mh-version}, found in a buffer named -@samp{*MH-E Info*}, should usually be included with any bug report you -submit (@pxref{Bug Reports}). - -@subheading MH-E Buffers - -Besides the MH-Folder, MH-Show, and MH-Letter buffers, MH-E creates -several other buffers. They are: - -@table @samp -@cindex @samp{*MH-E Folders*} -@cindex buffers, @samp{*MH-E Folders*} -@findex mh-list-folders -@item *MH-E Folders* -@kindex F l -This buffer contains the output of @kbd{F l} (@code{mh-list-folders}). -@xref{Folders}. -@c ------------------------- -@cindex @samp{*MH-E Help*} -@cindex buffers, @samp{*MH-E Help*} -@findex mh-help -@item *MH-E Help* -@kindex ? -@kindex C-c ? -This buffer contains the output of @kbd{?} (@code{mh-help}) and -@kbd{C-c ?} in MH-Letter mode. @xref{Using This Manual}. -@c ------------------------- -@cindex @samp{*MH-E Info*} -@cindex buffers, @samp{*MH-E Info*} -@item *MH-E Info* -This buffer contains the output of @kbd{M-x mh-version @key{RET}}. -@c ------------------------- -@cindex @samp{*MH-E Log*} -@cindex buffers, @samp{*MH-E Log*} -@item *MH-E Log* -This buffer contains the last 100 lines of the output of the various -MH commands. -@c ------------------------- -@cindex @samp{*MH-E Mail Delivery*} -@cindex buffers, @samp{*MH-E Mail Delivery*} -@item *MH-E Mail Delivery* -This buffer contains the transcript of a mail delivery. @xref{Sending -Message}. -@c ------------------------- -@cindex @samp{*MH-E Recipients*} -@cindex buffers, @samp{*MH-E Recipients*} -@findex mh-check-whom -@item *MH-E Recipients* -@kindex C-c C-w -This buffer contains the output of @kbd{C-c C-w} -(@code{mh-check-whom}) and is killed when draft is sent. -@xref{Checking Recipients}. -@c ------------------------- -@cindex @samp{*MH-E Sequences*} -@cindex buffers, @samp{*MH-E Sequences*} -@item *MH-E Sequences* -This buffer contains the output of @kbd{S l} -(@code{mh-list-sequences}). @xref{Sequences}. -@c ------------------------- -@cindex @samp{*mh-temp*} -@cindex buffers, @samp{*mh-temp*} -@item *mh-temp* -This is a scratch, ephemeral, buffer used by MH-E functions. Note that -it is hidden because the first character in the name is a space. -You'll generally not have any need for this buffer. -@end table - -@node Scan Line Formats, Procmail, Miscellaneous, Top -@appendix Scan Line Formats - -@cindex scan line formats - -This appendix discusses how MH-E creates, parses, and manipulates scan -lines. If you have your own MH scan or inc format files, you -@strong{can} teach MH-E how to handle them, but it isn't easy as -you'll see. - -@cindex @samp{mh-scan-line-formats} customization group -@cindex customization group, @samp{mh-scan-line-formats} - -This table lists the options in the @samp{mh-scan-line-formats} -customization group. - -@vtable @code -@item mh-adaptive-cmd-note-flag -On means that the message number width is determined dynamically -(default: @samp{on}). -@c ------------------------- -@item mh-scan-format-file -Specifies the format file to pass to the scan program (default: -@samp{Use MH-E scan Format}). -@c ------------------------- -@item mh-scan-prog -Program used to scan messages (default: @code{"scan"}). -@end vtable - -@vindex mh-adaptive-cmd-note-flag - -There are a couple of caveats when creating your own scan format file. -First, MH-E will not work if your scan lines do not include message -numbers. It will work poorly if you don't dedicate a column for -showing the current message and notations. It is also best to keep the -first column empty to make room for the cursor and so that text isn't -obscured by the current message's overlay arrow when running in a -terminal. You won't be able to use the option -@code{mh-adaptive-cmd-note-flag} or the threading features -(@pxref{Threading}). - -@cindex message numbers -@findex mh-set-cmd-note -@vindex mh-adaptive-cmd-note-flag -@vindex mh-scan-format-file - -If you've created your own format to handle long message numbers, -you'll be pleased to know you no longer need it since MH-E adapts its -internal format based upon the largest message number if -@code{mh-adaptive-cmd-note-flag} is on (the default). If you prefer -fixed-width message numbers, turn off @code{mh-adaptive-cmd-note-flag} -and call @code{mh-set-cmd-note} with the width specified by your -format file (see @code{mh-scan-format-file}). For example, the default -width is 4, so you would use @samp{(mh-set-cmd-note 4)}. - -@vindex mh-adaptive-cmd-note-flag -@vindex mh-scan-format-file -@vindex mh-scan-format-mh -@vindex mh-scan-format-nmh - -The default setting for @code{mh-scan-format-file} is @samp{Use MH-E -scan Format}. This means that the format string will be taken from the -either @code{mh-scan-format-mh} or @code{mh-scan-format-nmh} depending -on whether MH or nmh (or GNU mailutils MH) is in use. This setting -also enables you to turn on the option -@code{mh-adaptive-cmd-note-flag}. You can also set this option to -@samp{Use Default scan Format} to get the same output as you would get -if you ran @command{scan} from the shell. If you have a format file -that you want MH-E to use but not MH, you can set this option to -@samp{Specify a scan Format File} and enter the name of your format -file. - -@vindex mh-scan-format-file -@vindex mh-scan-format-mh -@vindex mh-scan-format-nmh - -The scan format that MH-E uses when @code{mh-scan-format-file} is set -to its default of @samp{Use MH-E scan Format} is held in the variables -@code{mh-scan-format-nmh} and @code{mh-scan-format-mh} depending on -whether you are using nmh (or GNU mailutils MH) or not. Typically, you -create your own format files rather than modifying these variables. -The value of @code{mh-scan-format-nmh} is: - -@smallexample -(concat - "%4(msg)" - "%<(cur)+%| %>" - "%<@{replied@}-" - "%?(nonnull(comp@{to@}))%<(mymbox@{to@})t%>" - "%?(nonnull(comp@{cc@}))%<(mymbox@{cc@})c%>" - "%?(nonnull(comp@{bcc@}))%<(mymbox@{bcc@})b%>" - "%?(nonnull(comp@{newsgroups@}))n%>" - "%<(zero) %>" - "%02(mon@{date@})/%02(mday@{date@})%<@{date@} %|*%>" - "%<(mymbox@{from@})%<@{to@}To:%14(decode(friendly@{to@}))%>%>" - "%<(zero)%17(decode(friendly@{from@}))%> " - "%(decode@{subject@})%<@{body@}<<%@{body@}%>") -@end smallexample - -@cindex decoding RFC 2047 -@cindex RFC 2047, decoding -@vindex mh-scan-format-mh - -The setting for @code{mh-scan-format-mh} is similar, except that MH -doesn't have the function @code{decode} (which is used to decode RFC -2047 encodings). - -@cindex notations, scan line -@cindex scan line notations - -These strings are passed to the @command{scan} program via the -@option{-format} argument. The formats are identical to the defaults -except that additional hints for fontification have been added to the -existing notations in the fifth column (remember that in Emacs, the -columns start at 0). The values of the fifth column, in priority -order, are: @samp{-} if the message has been replied to, @samp{t} if -an address in the @samp{To:} field matches one of the mailboxes of the -current user, @samp{c} if the @samp{Cc:} field matches, @samp{b} if -the @samp{Bcc:} field matches, and @samp{n} if a non-empty -@samp{Newsgroups:} field is present. - -@cindex @command{scan} -@cindex MH commands, @command{scan} -@vindex mh-progs -@vindex mh-scan-prog - -The name of the program that generates a listing of one line per -message is held in @code{mh-scan-prog} (default: @code{"scan"}). -Unless this variable contains an absolute pathname, it is assumed to -be in the @code{mh-progs} directory (@pxref{Getting Started}). You may -link another program to @command{scan} (see @samp{mh-profile}(5)) to -produce a different type of listing@footnote{See the section -@uref{@value{MH-BOOK-HOME}/faswsprs.html, Find and Specify with scan -pick Ranges Sequences} in the MH book.}. - -@cindex regular expressions, scan line formats -@findex mh-set-cmd-note -@findex setq - -If you change the format of the scan lines you'll need to tell MH-E -how to parse the new format. As you will see, quite a lot of variables -are involved to do that. Use @kbd{M-x apropos @key{RET} -mh-scan.*regexp @key{RET}} to obtain a list of these variables. You -will also have to call @code{mh-set-cmd-note} if your notations are -not in column 4 (columns in Emacs start with 0). Note that unlike most -of the user options described in this manual, these are variables and -must be set with @code{setq} instead of in a customization buffer. For -help with regular expressions, see -@ifnothtml -@ref{Regexps, , Syntax of Regular Expressions, emacs, The -GNU Emacs Manual}. -@end ifnothtml -@ifhtml -section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html, -Syntax of Regular Expressions} in @cite{The GNU Emacs Manual}. -@end ifhtml - -The first variable has to do with pruning out garbage. - -@vtable @code -@cindex @command{inc} -@cindex MH commands, @command{inc} -@cindex @command{scan} -@cindex MH commands, @command{scan} -@item mh-scan-valid-regexp -This regular expression describes a valid scan line. This is used to -eliminate error messages that are occasionally produced by -@command{inc}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next -prev} in the MH book.} or @command{scan} (default: @code{"^ *[0-9]"}). -@end vtable - -Next, many variables control how the scan lines are parsed. - -@vtable @code -@vindex mh-folder-body -@vindex mh-folder-font-lock-keywords -@item mh-scan-body-regexp -This regular expression matches the message body fragment. Note that -the default setting of @code{mh-folder-font-lock-keywords} expects -this expression to contain at least one parenthesized expression which -matches the body text as in the default of -@code{"\\(<<\\([^\n]+\\)?\\)"}. If this regular expression is not -correct, the body fragment will not be highlighted with the face -@code{mh-folder-body}. -@c ------------------------- -@vindex mh-folder-cur-msg-number -@vindex mh-folder-font-lock-keywords -@vindex mh-note-cur -@item mh-scan-cur-msg-number-regexp -This regular expression matches the current message. It must match -from the beginning of the line. Note that the default setting of -@code{mh-folder-font-lock-keywords} expects this expression to contain -at least one parenthesized expression which matches the message number -as in the default of @w{@code{"^\\( *[0-9]+\\+\\).*"}}. This -expression includes the leading space and current message marker -@samp{+} within the parenthesis since it looks better to highlight -these items as well. The highlighting is done with the face -@code{mh-folder-cur-msg-number}. This regular expression should be -correct as it is needed by non-fontification functions. See also -@code{mh-note-cur}. -@c ------------------------- -@vindex mh-folder-date -@vindex mh-folder-font-lock-keywords -@vindex mh-scan-sent-to-me-sender-regexp -@item mh-scan-date-regexp -This regular expression matches a valid date. It must @strong{not} be -anchored to the beginning or the end of the line. Note that the -default setting of @code{mh-folder-font-lock-keywords} expects this -expression to contain only one parenthesized expression which matches -the date field as in the default of -@code{"\\([0-9][0-9]/[0-9][0-9]\\)"}. If this regular expression is -not correct, the date will not be highlighted with the face -@code{mh-folder-date}. -@c ------------------------- -@vindex mh-folder-deleted -@vindex mh-folder-font-lock-keywords -@vindex mh-note-deleted -@item mh-scan-deleted-msg-regexp -This regular expression matches deleted messages. It must match from -the beginning of the line. Note that the default setting of -@code{mh-folder-font-lock-keywords} expects this expression to contain -at least one parenthesized expression which matches the message number -as in the default of @code{"^\\( *[0-9]+\\)D"}. This expression -includes the leading space within the parenthesis since it looks -better to highlight it as well. The highlighting is done with the face -@code{mh-folder-deleted}. This regular expression should be correct as -it is needed by non-fontification functions. See also -@code{mh-note-deleted}. -@c ------------------------- -@vindex mh-folder-font-lock-keywords -@vindex mh-folder-msg-number -@item mh-scan-good-msg-regexp -This regular expression matches ``good'' messages. It must match from -the beginning of the line. Note that the default setting of -@code{mh-folder-font-lock-keywords} expects this expression to contain -at least one parenthesized expression which matches the message number -as in the default of @w{@code{"^\\( *[0-9]+\\)[^D^0-9]"}}. This -expression includes the leading space within the parenthesis since it -looks better to highlight it as well. The highlighting is done with -the face @code{mh-folder-msg-number}. This regular expression should -be correct as it is needed by non-fontification functions. -@c ------------------------- -@vindex mh-scan-format-file -@item mh-scan-msg-format-regexp -This regular expression finds the message number width in a scan -format. Note that the message number must be placed in a parenthesized -expression as in the default of @code{"%\\([0-9]*\\)(msg)"}. This -variable is only consulted if @code{mh-scan-format-file} is set to -@samp{Use MH-E scan Format}. -@c ------------------------- -@vindex mh-scan-format-file -@item mh-scan-msg-format-string -This is a format string for the width of the message number in a scan -format. Use @samp{0%d} for zero-filled message numbers. This variable -is only consulted if @code{mh-scan-format-file} is set to @samp{Use -MH-E scan Format} (default: @code{"%d"}). -@c ------------------------- -@item mh-scan-msg-number-regexp -This regular expression extracts the message number. It must match -from the beginning of the line. Note that the message number must be -placed in a parenthesized expression as in the default of @w{@code{"^ -*\\([0-9]+\\)"}}. -@c ------------------------- -@item mh-scan-msg-overflow-regexp -This regular expression matches overflowed message numbers (default: -@code{"^[?0-9][0-9]"}). -@c ------------------------- -@item mh-scan-msg-search-regexp -This regular expression matches a particular message. It is a format -string; use @samp{%d} to represent the location of the message number -within the expression as in the default of @code{"^[^0-9]*%d[^0-9]"}. -@c ------------------------- -@vindex mh-folder-address -@vindex mh-folder-font-lock-keywords -@vindex mh-folder-to -@item mh-scan-rcpt-regexp -This regular expression specifies the recipient in messages you sent. -Note that the default setting of @code{mh-folder-font-lock-keywords} -expects this expression to contain two parenthesized expressions. The -first is expected to match the @samp{To:} that the default scan format -file generates. The second is expected to match the recipient's name -as in the default of @code{"\\(To:\\)\\(..............\\)"}. If this -regular expression is not correct, the @samp{To:} string will not be -highlighted with the face @code{mh-folder-to} and the recipient will not be -highlighted with the face @code{mh-folder-address}. -@c ------------------------- -@vindex mh-folder-font-lock-keywords -@vindex mh-folder-refiled -@vindex mh-note-refiled -@item mh-scan-refiled-msg-regexp -This regular expression matches refiled messages. It must match from -the beginning of the line. Note that the default setting of -@code{mh-folder-font-lock-keywords} expects this expression to contain -at least one parenthesized expression which matches the message number -as in the default of @w{@code{"^\\( *[0-9]+\\)\\^"}}. This expression -includes the leading space within the parenthesis since it looks -better to highlight it as well. The highlighting is done with the face -@code{mh-folder-refiled}. This regular expression should be correct as -it is needed by non-fontification functions. See also -@code{mh-note-refiled}. -@c ------------------------- -@vindex mh-folder-font-lock-keywords -@vindex mh-folder-sent-to-me-sender -@vindex mh-mh-folder-sent-to-me-hint -@vindex mh-scan-format-nmh -@item mh-scan-sent-to-me-sender-regexp -This regular expression matches messages sent to us. Note that the -default setting of @code{mh-folder-font-lock-keywords} expects this -expression to contain at least two parenthesized expressions. The -first should match the fontification hint (see -@code{mh-scan-format-nmh}) and the second should match the user name -as in the default of -@w{@code{"^ *[0-9]+.\\([bct]\\).....[ ]*\\(..................\\)"}}. -If this regular expression is not correct, the notation hints will not -be highlighted with the face @code{mh-mh-folder-sent-to-me-hint} and -the sender will not be highlighted with the face -@code{mh-folder-sent-to-me-sender}. -@c ------------------------- -@vindex mh-folder-followup -@vindex mh-folder-font-lock-keywords -@vindex mh-folder-subject -@item mh-scan-subject-regexp -This regular expression matches the subject. It must match from the -beginning of the line. Note that the default setting of -@samp{mh-folder-font-lock-keywords} expects this expression to contain -at least three parenthesized expressions. The first is expected to -match the @samp{Re:} string, if any, and is highlighted with the face -@code{mh-folder-followup}. The second matches an optional bracketed -number after @samp{Re:}, such as in @samp{Re[2]:} (and is thus a -sub-expression of the first expression). The third is expected to -match the subject line itself which is highlighted with the face -@code{mh-folder-subject}. For example, the default is -@w{@code{"^ *[0-9]+........[ ]*...................}}@* -@w{@code{\\([Rr][Ee]\\(\\[[0-9]+\\]\\)?:\\s-*\\)*\\([^<\n]*\\)"}}. -This regular expression should be correct as it is needed by -non-fontification functions. Note that this example is broken up on -two lines for readability, but is actually a single string. -@end vtable - -Finally, there are a slew of variables that control how MH-E annotates -the scan lines. - -@vtable @code -@findex mh-set-cmd-note -@vindex mh-adaptive-cmd-note-flag -@item mh-cmd-note -Column for notations (default: 4). This variable should be set with -the function @code{mh-set-cmd-note}. This variable may be updated -dynamically if @code{mh-adaptive-cmd-note-flag} is on. The following -variables contain the notational characters. Note that columns in -Emacs start with 0. -@c ------------------------- -@item mh-note-copied -Messages that have been copied are marked by this character (default: -@code{?C}). -@c ------------------------- -@vindex mh-scan-cur-msg-number-regexp -@item mh-note-cur -The current message (in MH, not in MH-E) is marked by this character -(default: @code{?+}). See also @code{mh-scan-cur-msg-number-regexp}. -@c ------------------------- -@vindex mh-scan-deleted-msg-regexp -@item mh-note-deleted -Messages that have been deleted are marked by this character (default: -@code{?D}). See also @code{mh-scan-deleted-msg-regexp}. -@c ------------------------- -@item mh-note-dist -Messages that have been redistributed are marked by this character -(default: @code{?R}). -@c ------------------------- -@item mh-note-forw -Messages that have been forwarded are marked by this character -(default: @code{?F}). -@c ------------------------- -@item mh-note-printed -Messages that have been printed are marked by this character (default: -@code{?P}). -@c ------------------------- -@vindex mh-scan-refiled-msg-regexp -@item mh-note-refiled -Messages that have been refiled are marked by this character (default: -@code{?^}). See also @code{mh-scan-refiled-msg-regexp}. -@c ------------------------- -@item mh-note-repl -Messages that have been replied to are marked by this character -(default: @code{?-}). -@c ------------------------- -@item mh-note-seq -Messages in a user-defined sequence are marked by this character -(default: @code{?%}). Messages in the @samp{search} sequence are -marked by this character as well. -@end vtable - -For example, let's say I have the following in @file{scan.format} -which displays the sender, the subject, and the message number. This -format places a @samp{+} after the message number for the current -message according to MH; it also uses that column for notations. - -@smallexample -%20(decode(friendly@{from@})) %50(decode@{subject@}) %4(msg)%<(cur)+%| %> -@end smallexample - -@vindex mh-adaptive-cmd-note-flag -@vindex mh-scan-format-file -@vindex mh-scan-format-file, example - -The first thing you have to do is tell MH-E to use this file. -Customize @code{mh-scan-format-file} and set its value to @samp{Use -Default scan Format}. If you didn't get already turn off -@code{mh-adaptive-cmd-note-flag}, you'll need to do that first. - -Next, tell MH-E what a valid scan line looks like so that you can at -least display the output of scan in your MH-Folder buffer. - -@vindex mh-scan-valid-regexp, example - -@smalllisp -(setq mh-scan-valid-regexp "[0-9]+[+D^ ]$") -@end smalllisp - -Now, in order to get rid of the @samp{Cursor not pointing to message} -message, you need to tell MH-E how to access the message number. You -should also see why MH-E requires that you include a message number in -the first place. - -@vindex mh-scan-msg-number-regexp, example -@vindex mh-scan-msg-search-regexp, example - -@smalllisp -(setq mh-scan-msg-number-regexp "^.* \\([0-9]+\\)[+D^ ]$") -(setq mh-scan-msg-search-regexp " %d[+D^ ]$") -@end smalllisp - -In order to get the next and previous commands working, add this. - -@vindex mh-scan-good-msg-regexp, example - -@smalllisp -(setq mh-scan-good-msg-regexp "^.* \\([0-9]+\\)[+D^ ]$") -@end smalllisp - -Note that the current message isn't marked with a @samp{+} when moving -between the next and previous messages. Here is the code required to -get this working. - -@vindex set-mh-cmd-note, example -@vindex mh-scan-cur-msg-number-regexp, example - -@smalllisp -(set-mh-cmd-note 76) -(setq mh-scan-cur-msg-number-regexp "^.* \\([0-9]+\\)\\+$") -@end smalllisp - -Finally, add the following to delete and refile messages. - -@vindex mh-scan-deleted-msg-regexp, example -@vindex mh-scan-refiled-msg-regexp, example - -@smalllisp -(setq mh-scan-deleted-msg-regexp "^.* \\([0-9]+\\)D$") -(setq mh-scan-refiled-msg-regexp "^.* \\([0-9]+\\)\\^$") -@end smalllisp - -This is just a bare minimum; it's best to adjust all of the regular -expressions to ensure that MH-E and highlighting perform well. - -@node Procmail, Odds and Ends, Scan Line Formats, Top -@appendix Reading Mailing Lists Effectively - -@cindex @command{procmail} -@cindex @command{slocal} -@cindex Gnus -@cindex MH commands, @command{slocal} -@cindex Unix commands, @command{procmail} -@cindex mailing lists, reading - -This appendix explains how to use @uref{http://www.procmail.org/, -procmail} to file mail from mailing lists into folders which can then -be read easily with MH-E@footnote{The MH equivalent, @command{slocal}, -can be used as well, but procmail is more flexible and more packages -exist for procmail than for slocal.}. Some mailing lists have such -high traffic that Gnus must be used and I discuss how to use Gnus -side-by-side with MH-E. - -@cindex @file{.procmailrc} -@cindex files, @file{.procmailrc} - -First, I'll describe how to put mail from your mailing lists directly -into an MH folder using @command{procmail}. First, add the following -to @file{~/.procmailrc}. While the logging variables aren't strictly -necessary, they are extremely useful. - -@smallexample -[1] # Update PATH so procmail can find myrcvstore, rcvstore and mhparam. -[2] PATH=$PATH:/usr/lib/mh:/usr/bin/mh:$HOME/bin -[3] -[4] # Point LOGFILE at the actual log file. -[5] LOGFILE=$HOME/.procmail.log -[6] -[7] # This setting provides just the right amount of information. -[8] LOGABSTRACT=all -[9] -[10] # Uncomment the following line to see how your patterns match. -[11] #VERBOSE=yes -[12] -[13] # Place mail sent to any MH-E mailing list in +mh-e. -[14] :0 w: mh-e$LOCKEXT -[15] * ^TO.*mh-e-.*@.*sourceforge.net -[16] | myrcvstore -create +mh-e -@end smallexample - -@cindex @command{rcvstore} -@cindex MH commands, @command{rcvstore} - -Line 14 creates a lock file in your mail directory based upon the name -of the folder. This is done because @command{rcvstore} does not -perform locking. While this lock file will prevent @command{procmail} -from writing to a folder concurrently, there is a slight chance that -you might lose a message if you're performing operations on a folder -at the same time @command{rcvstore} is placing a message there. You -have been warned. Now that that disclaimer is out of the way, note -that I've been using this set-up for over a decade and haven't lost -anything to my knowledge@footnote{See -@uref{https://savannah.nongnu.org/bugs/?func=detailbug&bug_id=4361&group_id=2166, -Savannah issue #4361} to see if @command{rcvstore} locking is still an -issue.}. - -@cindex @samp{Unseen-Sequence:} MH profile component -@cindex MH profile component, @samp{Unseen-Sequence:} - -Line 16 uses the following script, @code{myrcvstore}, to massage the -message as described in the comment and file the message in the given -folder@footnote{The @samp{-create} argument wasn't always the default -to @command{rcvstore}.}. - -@smallexample -#! /bin/sh - -# Accepts a message on standard input and passes it through rcvstore -# after first passing it through any filters. All arguments are passed -# on to rcvstore. - -# Force the "From user date" to become part of header. One reason this -# is done is because the presence of the From field confuses dist so -# that dist adds a new header, rather than using the existing header. -# Note that this should not be done for any message that goes into a -# Gnus incoming file (Gnus will thrown an error) nor should it be -# applied to any message that goes to the system mailbox because the -# entire mailbox will be incorporated as a single message. -formail -c -z -R 'From ' X-Envelope-From: | -rcvstore $@@ -@end smallexample - -If your version of @command{rcvstore} doesn't add messages to the -@samp{unseen} sequence by default, add the following line to your MH -profile: - -@smallexample -Unseen-Sequence: unseen -@end smallexample - -Now view your new messages with the speedbar (@pxref{Speedbar}) or with -@kbd{F n} (@code{mh-index-new-messages}). @xref{Folders}. - -If you're on a mailing list that is so voluminous that it is -impossible to read every message, it usually better to read the -mailing list like a newsgroup in a news reader. Emacs has a built-in -newsreader called Gnus. The remainder of this appendix talks about how -to use Gnus with an MH message store. The version of Gnus that was -used to prepare this manual was 5.10. Versions 5.8 through 5.10 should -work but versions prior to 5.8 use different options. - -This table contains a list of Gnus options that you will have to -modify. Note that for them to become accessible, you'll have to load -@file{nnml.el} first. This can be done with @kbd{M-x load-library -@key{RET} nnml @key{RET}}. - -@vtable @code -@item gnus-secondary-select-methods -Select the @samp{nnml} value. This select method uses directories for -folders and individual files for messages, just like MH. You do not -have to set an address. -@c ------------------------- -@item mail-sources -Select the @samp{Several files in a directory} value, check the -@samp{Path} box and enter @file{~/Mail} to tell Gnus where to find -your mail. -@c ------------------------- -@vindex mail-user-agent -@item message-mail-user-agent -In order to send mail within Gnus using MH-E, set this option to -@samp{mail-user-agent} and set the @code{mail-user-agent} option to -@samp{Emacs interface to MH}. -@c ------------------------- -@item nnmail-keep-last-article -Since Gnus keeps track of which messages you have read, it would be -bad if Gnus expired the last message, for example, message 100, and -@command{rcvstore} gave the next new message number 1. Gnus would then -ignore it since it thinks that you've read messages 1-100. Turning on -this option ensures that the last message is never removed thereby -eliminating this problem. -@end vtable - -Next add the following to @file{~/.procmailrc}. If you don't subscribe -to the GnuCash mailing list, substitute one to which you are -subscribed. - -@smallexample -PATH=$PATH:/usr/bin/mh -MAILDIR=$HOME/`mhparam Path` -# Place mail sent to the GnuCash mailing list in gnucash.spool, where -# Gnus will pick it up. -:0: -* ^TO.*gnucash.*@.*gnucash.org -gnucash.spool -@end smallexample - -Wait for some messages to appear in @file{gnucash.spool} and run Gnus -with @kbd{M-x gnus @key{RET}}. To view the folder created in the -example above, you would tell Gnus about it the first time only with -@kbd{G m gnucash @key{RET} nnml @key{RET}}. In MH-E, this folder is -known as @samp{+gnucash}. - -@node Odds and Ends, History, Procmail, Top -@appendix Odds and Ends - -This appendix covers a few topics that don't fit elsewhere. Here I -tell you how to report bugs and how to get on the MH-E mailing lists. -I also point out some additional sources of information. - -@menu -* Bug Reports:: -* Mailing Lists:: -* MH FAQ and Support:: -* Getting MH-E:: -@end menu - -@node Bug Reports, Mailing Lists, Odds and Ends, Odds and Ends -@appendixsec Bug Reports - -@cindex bugs -@cindex SourceForge -@kindex M-x mh-version - -Bug reports should be filed at -@uref{https://sourceforge.net/tracker/?group_id=13357&atid=113357, -SourceForge}. You need to be a SourceForge user to submit bug reports, -but this is easy enough to do that it shouldn't be a restriction for -you. Please include the output of @kbd{M-x mh-version} -(@pxref{Miscellaneous}) in any bug report you send unless you're 110% -positive we won't ask for it. - -@node Mailing Lists, MH FAQ and Support, Bug Reports, Odds and Ends -@appendixsec MH-E Mailing Lists - -@cindex SourceForge -@cindex mailing lists - -There are several mailing lists for MH-E. They are @i{mh-e-users at -lists.sourceforge.net}, @i{mh-e-announce at lists.sourceforge.net}, -and @i{mh-e-devel at lists.sourceforge.net}. You can subscribe or view -the archives at @uref{https://sourceforge.net/mail/?group_id=13357, -SourceForge}. Do not report bugs on these lists; please submit them -via SourceForge (@pxref{Bug Reports}). - -@node MH FAQ and Support, Getting MH-E, Mailing Lists, Odds and Ends -@appendixsec MH FAQ and Support - -@cindex FAQ -@cindex MH FAQ - -The article @uref{http://www.newt.com/faq/mh.html, @cite{MH Frequently -Asked Questions (FAQ) with Answers}} appears monthly in the newsgroup -@samp{comp.mail.mh}. While very little is there that deals with MH-E -specifically, there is an incredible wealth of material about MH -itself which you will find useful. - -@cindex support - -You can find FAQs on MH-E at the -@uref{https://sourceforge.net/tracker/?group_id=13357&atid=213357, -Support Requests} page on SourceForge. If you don't find the answer to -your question, file a support request and your question will become a -new FAQ! - -@node Getting MH-E, , MH FAQ and Support, Odds and Ends -@appendixsec Getting MH-E - -@cindex MH-E, obtaining -@cindex getting MH-E -@cindex obtaining MH-E - -Because MH-E is undergoing a phase of sustained growth, the version of -MH-E in your Emacs is likely to be out of date although it is most -likely to be more up to date than the copy that comes with the MH -distribution in @file{miscellany/mh-e}. - -@cindex change log -@cindex release notes - -New MH-E releases are always available for downloading at -@uref{https://sourceforge.net/project/showfiles.php?group_id=13357, -SourceForge} before they appear in an Emacs release. You can read the -release notes on that page to determine if the given release of MH-E -is already installed in your version of Emacs. You can also read the -change log to see if you are interested in what the given release of -MH-E has to offer (although we have no doubt that you will be -extremely interested in all new releases). - -@cindex Debian - -If you use Debian, you can install the Debian -@uref{http://packages.debian.org/unstable/mail/mh-e, mh-e package} -instead. - -@cindex files, @samp{MH-E-NEWS} -@cindex files, @samp{README} -@cindex news -@cindex @samp{MH-E-NEWS} -@cindex @samp{README} -@kindex M-x mh-version - -After you download and extract the MH-E tarball, read the -@file{README} file and @file{MH-E-NEWS}. These correspond to the -release notes and change log mentioned above. The file @file{README} -contains instructions on installing MH-E. If you're already running -Emacs, please quit that session and start again to load in the new -MH-E. Check that you're running the new version with the command -@kbd{M-x mh-version}. - -@cindex contributed software -@cindex manual -@cindex documentation - -In addition to the mh-e package, the -@uref{https://sourceforge.net/project/showfiles.php?group_id=13357, -SourceForge} site also contains doc and contrib packages. The former -is the latest release of this manual, and the latter contains a few -contributed packages you might find useful. - -@node History, GFDL, Odds and Ends, Top -@appendix History of MH-E - -@cindex Bill Wohler -@cindex Brian Reid -@cindex Gildea, Stephen -@cindex Jim Larus -@cindex Larus, Jim -@cindex MH-E, versions -@cindex Reid, Brian -@cindex SourceForge -@cindex Stephen Gildea -@cindex Wohler, Bill -@cindex history of MH-E -@cindex versions of MH-E - -MH-E was originally written by Brian Reid in 1983 and has changed -hands several times since then. Jim Larus wanted to do something -similar for GNU Emacs, and ended up completely rewriting it that same -year. In 1989, Stephen Gildea picked it up and added many -improvements. Bill Wohler then took over in 2000 and moved its -development to @uref{http://sourceforge.net/, SourceForge} where it -lives today. - -@menu -* From Brian Reid:: -* From Jim Larus:: -* From Stephen Gildea:: -* From Bill Wohler:: -@end menu - -@node From Brian Reid, From Jim Larus, History, History -@appendixsec From Brian Reid - -@cindex Brian Reid -@cindex Reid, Brian - -One day in 1983 I got the flu and had to stay home from work for three -days with nothing to do. I used that time to write MHE@. The -fundamental idea behind MHE was that it was a ``puppeteer'' driving -the MH programs underneath it. MH had a model that the editor was -supposed to run as a sub-process of the mailer, which seemed to me at -the time to be the tail wagging the dog. So I turned it around and -made the editor drive the MH programs. I made sure that the UCI people -(who were maintaining MH at the time) took in my changes and made them -stick. - -Today, I still use my own version of MHE because I don't at all like -the way that GNU MH-E works and I've never gotten to be good enough at -hacking Emacs Lisp to make GNU MH-E do what I want. The Gosling-emacs -version of MHE and the GNU Emacs version of MH-E have almost nothing -in common except similar names. They work differently, have different -conceptual models, and have different key bindings@footnote{After -reading this article, I questioned Brian about his version of MHE, and -received some great ideas for improving MH-E such as a dired-like -method of selecting folders; and removing the prompting when sending -mail, filling in the blanks in the draft buffer instead. I passed them -on to Stephen Gildea, the current maintainer, and he was excited about -the ideas as well. Perhaps one day, MH-E will again resemble MHE -(draft form editing was introduced in version 7.4).}. - -Brian Reid, June 1994 - -@node From Jim Larus, From Stephen Gildea, From Brian Reid, History -@appendixsec From Jim Larus - -@cindex Jim Larus -@cindex Larus, Jim - -Brian Reid, while at CMU or shortly after going to Stanford wrote a -mail reading program called MHE for Gosling Emacs. It had much the -same structure as MH-E (i.e., invoked MH programs), though it was -simpler and the commands were slightly different. Unfortunately, I no -longer have a copy so the differences are lost in the mists of time. - -In '82-83, I was working at BBN and wrote a lot of mlisp code in -Gosling Emacs to make it look more like Tennex Emacs. One of the -packages that I picked up and improved was Reid's mail system. In '83, -I went back to Berkeley. About that time, Stallman's first version of -GNU Emacs came out and people started to move to it from Gosling Emacs -(as I recall, the transition took a year or two). I decided to port -Reid's MHE and used the mlisp to Emacs Lisp translator that came with -GNU Emacs. It did a lousy job and the resulting code didn't work, so I -bit the bullet and rewrote the code by hand (it was a lot smaller and -simpler then, so it took only a day or two). - -Soon after that, MH-E became part of the standard Emacs distribution -and suggestions kept dribbling in for improvements. MH-E soon reached -sufficient functionality to keep me happy, but I kept on improving it -because I was a graduate student with plenty of time on my hands and -it was more fun than my dissertation. In retrospect, the one thing -that I regret is not writing any documentation, which seriously -limited the use and appeal of the package. - -@cindex @command{xmh}, in MH-E history - -In '89, I came to Wisconsin as a professor and decided not to work on -MH-E. It was stable, except for minor bugs, and had enough -functionality, so I let it be for a few years. Stephen Gildea of BBN -began to pester me about the bugs, but I ignored them. In 1990, he -went off to the X Consortium, said good bye, and said that he would -now be using @command{xmh}. A few months later, he came back and said -that he couldn't stand @command{xmh} and could I put a few more bug fixes -into MH-E. At that point, I had no interest in fixing MH-E, so I gave -the responsibility of maintenance to him and he has done a fine job -since then. - -Jim Larus, June 1994 - -@node From Stephen Gildea, From Bill Wohler, From Jim Larus, History -@appendixsec From Stephen Gildea - -@cindex Gildea, Stephen -@cindex Stephen Gildea - -In 1987 I went to work for Bolt Beranek and Newman, as Jim had before -me. In my previous job, I had been using RMAIL, but as my folders tend -to run large, I was frustrated with the speed of RMAIL@. However, I -stuck with it because I wanted the GNU Emacs interface. I am very -familiar and comfortable with the Emacs interface (with just a few -modifications of my own) and dislike having to use applications with -embedded editors; they never live up to Emacs. - -MH is the mail reader of choice at BBN, so I converted to it. Since I -didn't want to give up using an Emacs interface, I started using MH-E. -As is my wont, I started hacking on it almost immediately. I first -used version 3.4m. One of the first features I added was to treat the -folder buffer as a file-visiting buffer: you could lock it, save it, -and be warned of unsaved changes when killing it. I also worked to -bring its functionality a little closer to RMAIL@. Jim Larus was very -cooperative about merging in my changes, and my efforts first appeared -in version 3.6, distributed with Emacs 18.52 in 1988. Next I decided -MH-E was too slow and optimized it a lot. Version, 3.7, distributed -with Emacs 18.56 in 1990, was noticeably faster. - -When I moved to the X Consortium I became the first person there to -not use xmh. (There is now one other engineer there using MH-E.) About -this point I took over maintenance of MH-E from Jim and was finally -able to add some features Jim hadn't accepted, such as the backward -searching undo. My first release was 3.8 (Emacs 18.58) in 1992. - -Now, in 1994, we see a flurry of releases, with both 4.0 and 5.0. -Version 4.0 added many new features, including background folder -collection and support for composing @sc{mime} messages. (Reading -@sc{mime} messages remains to be done, alas.) While writing this book, -Bill Wohler gave MH-E its closest examination ever, uncovering bugs -and inconsistencies that required a new major version to fix, and so -version 5 was released. - -Stephen Gildea, June 1994 - -@node From Bill Wohler, , From Stephen Gildea, History -@appendixsec From Bill Wohler - -@cindex Wohler, Bill -@cindex Bill Wohler - -The preface originally included the following text which I use to -begin my story: - -@quotation -But it's important to note a brief history of MH-E. - -@w{Version 3} was prevalent through the @w{Emacs 18} and early -@w{Emacs 19} years. Then @w{Version 4} came out (@w{Emacs 19.23}), -which introduced several new and changed commands. Next, @w{Version -5.0} was released, which fixed some bugs and incompatibilities, and -was incorporated into @w{Emacs 19.29}. -@end quotation - -After a long break, Stephen handed the reins over to me in 2000. I -moved the project to a new site called SourceForge and organized a -great team of developers. Our first release in late 2001 was version -6. It appeared around the time of Emacs 21.2 and had menus and tool -bar buttons. - -Then, indexed searches, improved MIME handling, a speedbar, multiple -identities, alias completion, an index view of unseen messages, spam -software support, Face and X-Image-URL header field support, Fcc -completion, arbitrary range handling, and draft form editing were -introduced in the version 7 series around the time of Emacs 21.4 -(2004). Still, Emacs itself contained version 5 of MH-E released back -in 1994. - -Version 8 development was mostly driven by the rewrite of the manual. -It also brought GNU mailutils MH support, S/MIME support, picon -support, and an improved interface for hiding header fields. The CVS -repository was migrated from SourceForge to Savannah (only for those -files that were already part of Emacs) and the software was completely -reorganized to push back two decades of entropy. Version 8 appeared in -Emacs 22.1 in 2006. - -Development was then quiet for a couple of years. Emacs 23.1, which is -due out in 2009, will contain version 8.1. This version includes a few -new features and several bug fixes. - -Bill Wohler, August 2008 - -@node GFDL, GPL, History, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node GPL, Key Index, GFDL, Top -@appendix GNU General Public License -@include gpl.texi - -@node Key Index, Command Index, GPL, Top -@unnumbered Key (Character) Index -@printindex ky - -@node Command Index, Option Index, Key Index, Top -@unnumbered Command Index -@printindex fn - -@node Option Index, Concept Index, Command Index, Top -@unnumbered Option (Variable) Index -@printindex vr - -@node Concept Index, , Option Index, Top -@unnumbered Concept Index -@printindex cp - -@bye - -@c Ispell Helpers -@c -@c The following are words that ispell should ignore that would not -@c normally be in a dictionary (global or personal). Be careful not to -@c include words here that could potentially be typos of other words -@c (such as url, elisp, or MHE). -@c -@c LocalWords: CTRL ESC SPC f's -@c LocalWords: addr Aliasfile alist -@c LocalWords: Baushke Bcc BBN Beranek bogofilter bogofilter's -@c LocalWords: cmd CMU contrib cron -@c LocalWords: DesBrisay Dcc devel dir dired docstring filll forw -@c LocalWords: GECOS Gildea Gildea's Ginnean GnuCash goto gnuserv htm -@c LocalWords: ImageMagick inbox ispell keychain -@c LocalWords: Larus licensor LocalWords lookup lpr -@c LocalWords: makeinfo mairix mbox mh mhbuild mhl mhpath mlisp -@c LocalWords: MML msg multipart -@c LocalWords: Namazu NIS nenscript nnml num -@c LocalWords: packmbox passphrase pathname prev procmail prog repl -@c LocalWords: slocal sortm SpamAssassin spammers SpamProbe SpamProbe's -@c LocalWords: sublicense supercite speedbar -@c LocalWords: Tennex texi texinfo Thelen thelenm -@c LocalWords: UCI undeleted whatnow wohler xmh ypcat -@c -@c See http://www.oreilly.com/oreilly/author/stylesheet.html. -@c See http://en.wikipedia.org/. -@c -@c Note the lowercase mh which is needed to avoid hits in the -@c functions and variables. Occasionally, check for accidental -@c inclusion of mh in text by uncommenting the following and executing -@c it with C-x C-e. You want to see "Search failed" -@c (let ((case-fold-search nil)) -@c (goto-char (point-min)) -@c (search-forward-regexp "^mh\\( \\|$\\)")) -@c -@c An extremely useful setting for texinfo-mode-hook is: -@c (add-to-list -@c 'ispell-skip-region-alist -@c (list -@c (concat "\\(@\\(small\\)?\\(example\\|lisp\\)" -@c "\\(@\\([irw]\\|code\\|var\\){[^}]+}\\|" -@c "@[@{}.]\\|" -@c "[^@]\\|" -@c "@\\(end \\)?group\\|" -@c "@\\(end \\)?cartouche\\)+" -@c "@end \\(small\\)?\\(example\\|lisp\\)\\|" -@c "@\\(code\\|command\\|file\\|kbd\\|sc\\){[^}]+}\\|" -@c "^@end [a-z]+$\\|" -@c "^@\\([fv]\\|print\\)index .*$\\|" -@c "@uref{[^,]+,\\|" -@c "@[a-z]+\\|" -@c "/[a-z.]+[/}]\\)"))))) -@c -@c Cross References -@c -@c See existing cross-references to the Emacs manual and the Emacs -@c Lisp manual (search for ``GNU Emacs Manual'' and ``GNU -@c Emacs Lisp Reference Manual'' respectively). - -@c @ftable Sorting -@c -@c As per index (sort of): Punctuation, keyboard characters (such as -@c RET and BS) upper and lowercase mixed (lower comes before -@c uppercase), control characters go with uppercase C, meta characters -@c go with uppercase M. -@c In some cases, the sort isn't strictly ASCII. -@c For example, SPC (mh-page-msg) reads better before BS -@c (mh-previous-page) and . (mh-show) is better before , -@c (mh-header-display). - -@c @vtable Sorting -@c -@c Alphabetical, pull hooks into their own table. - -@c Local Variables: -@c sentence-end-double-space: nil -@c End: - - diff --git a/doc/misc/newsticker.texi b/doc/misc/newsticker.texi deleted file mode 100644 index 919ca21cc3e..00000000000 --- a/doc/misc/newsticker.texi +++ /dev/null @@ -1,314 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename ../../info/newsticker -@set VERSION 1.99 -@set UPDATED June 2008 -@settitle Newsticker @value{VERSION} -@syncodeindex vr cp -@syncodeindex fn cp -@syncodeindex pg cp -@comment %**end of header - -@copying -This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}). - -@noindent -Copyright @copyright{} 2004-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* Newsticker: (newsticker). A Newsticker for Emacs. -@end direntry - -@titlepage -@title Newsticker -- a Newsticker for Emacs -@subtitle for version @value{VERSION}, @value{UPDATED} -@author Ulf Jasper -@author @email{ulf.jasper@@web.de} -@author @uref{http://ulf.epplejasper.de/} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Newsticker - -@insertcopying - -@end ifnottex - -@menu -* Overview:: General description of newsticker. -* Requirements:: Requirements for using newsticker. -* Installation:: Installing newsticker on your system. -* Usage:: Basic newsticker instructions. -* Configuration:: Customizable newsticker settings. -* Remarks:: Remarks about newsticker. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Variable, function, and concept index. -@end menu - -@node Overview -@chapter Overview - -Newsticker provides a newsticker for Emacs. A newsticker is a thing -that asynchronously retrieves headlines from a list of news sites, -prepares these headlines for reading, and allows for loading the -corresponding articles in a web browser. - - -Headlines consist of a title and (possibly) a small description. They -are contained in "RSS" (RDF Site Summary) or "Atom" files. Newsticker -works with the following RSS formats: - -@itemize -@item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or -@uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}), -@item RSS 0.92 (see @uref{http://backend.userland.com/rss092}), -@item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec} -@item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}), -@end itemize -@itemize -as well as the following Atom formats: -@item Atom 0.3 -@item Atom 1.0 (see -@uref{http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-11.txt}). -@end itemize - -That makes Newsticker.el an ``Atom aggregator'', ``RSS reader'', ``Feed -aggregator'', or ``Feed reader''. - -Newsticker provides several commands for reading headlines, navigating -through them, marking them as read/unread, hiding old headlines etc. -Headlines can be displayed as plain text or as rendered HTML. - -Headlines can be displayed in the echo area, either scrolling like -messages in a stock-quote ticker, or just changing. - -Newsticker allows for automatic processing of headlines by providing -hooks and (sample) functions for automatically downloading images and -enclosed files (as delivered by podcasts, e.g.). - -@ifhtml -Here are screen shots of the @uref{newsticker-1.7.png, version 1.7 -(current version)} and some older screen shots: -@uref{newsticker-1.6.png, version 1.6}, -@uref{newsticker-1.5.png, version 1.5}, -@uref{newsticker-1.4.png, version 1.4} -@uref{newsticker-1.3.png, version 1.3}, -@uref{newsticker-1.0.png, version 1.0}. -@end ifhtml - -@node Requirements -@chapter Requirements - -Newsticker can be used with -@uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version -21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}. It -requires an XML-parser (@file{xml.el}) which is part of GNU Emacs. If -you are using XEmacs you want to get the @file{net-utils} package -which contains @file{xml.el} for XEmacs. - -Newsticker retrieves headlines either via Emacs's built-in retrieval -functions, by an arbitrary external program that retrieves files via -http and prints them to stdout (like -@uref{http://www.gnu.org/software/wget/wget.html, wget}, or -- on a -per feed basis -- via an arbitrary Lisp command. - - -@node Installation -@chapter Installation - -As Newsticker is part of GNU Emacs there is no need to perform any -installation steps in order to use Newsticker. - -However, if you are using imenu, which allows for navigating with the -help of a menu, you should add the following to your Emacs startup file -(@file{~/.emacs}). - -@lisp -(add-hook 'newsticker-mode-hook 'imenu-add-menubar-index) -@end lisp - -That's it. - -@node Usage -@chapter Usage - -@findex newsticker-show-news -The command @code{newsticker-show-news} will display all available -headlines. It will also start the asynchronous download of headlines. - -You can choose between two different frontends for reading headlines: -@itemize -@item Newsticker's @emph{treeview} uses separate windows for the -feeds (in tree form), a list of headlines for the current feed, and -the content of the current headline. Feeds can be placed into groups -which itself can be placed in groups and so on. -@item Newsticker's @emph{plainview} displays all headlines in a -single buffer, called @samp{*newsticker*}. The modeline in the -@samp{*newsticker*} buffer informs whenever new headlines have -arrived. -@end itemize -In both views clicking mouse-button 2 or pressing RET on a headline -will call @code{browse-url} to load the corresponding news story in -your favorite web browser. - -@findex newsticker-start-ticker -@findex newsticker-stop-ticker -The scrolling, or flashing of headlines in the echo area, can be -started with the command @code{newsticker-start-ticker}. It can be -stopped with @code{newsticker-stop-ticker}. - -@findex newsticker-start -@findex newsticker-stop -If you just want to start the periodic download of headlines use the -command @code{newsticker-start}. Calling @code{newsticker-stop} will -stop the periodic download, but will call -@code{newsticker-stop-ticker} as well. - -@node Configuration -@chapter Configuration - -All Newsticker options are customizable, i.e. they can be changed with -Emacs customization methods: Call the command -@code{customize-group} and enter @samp{newsticker} for the customization -group. - -All Newsticker options have reasonable default values, so that in most -cases it is not necessary to customize settings before starting Newsticker -for the first time. - -The following list shows the available groups of newsticker options -and some of the most important options. - -@itemize - -@item -@code{newsticker-retrieval} contains options that define which news -feeds are retrieved and how this is done. - -@itemize -@item -@vindex newsticker-url-list -@code{newsticker-url-list} defines the list of headlines which are -retrieved. -@item -@vindex newsticker-retrieval-method -@code{newsticker-retrieval-method} defines how headlines are -retrieved. This is either done using Emacs's built-in download -capabilities or using an external tool. -@item -@vindex newsticker-retrieval-interval -@code{newsticker-retrieval-interval} defines how often headlines -are retrieved. -@end itemize - -@item -@code{newsticker-headline-processing} contains options that define -how the retrieved headlines are processed. - -@itemize -@item -@vindex newsticker-keep-obsolete-items -@code{newsticker-keep-obsolete-items} decides whether unread -headlines that have been removed from the feed are kept in the -Newsticker cache. -@item -@vindex newsticker-auto-mark-filter-list -@code{newsticker-auto-mark-filter-list} provides the possibility to -automatically mark headlines as immortal or old. -@end itemize - -@item -@code{newsticker-hooks} contains options for hooking other Emacs -commands to newsticker functions. -@itemize -@item -@vindex newsticker-new-item-functions -@code{newsticker-new-item-functions} allows for automatic -processing of headlines. See `newsticker-download-images', and -`newsticker-download-enclosures' for sample functions. -@item -@vindex newsticker-plainview-hooks -The subgroup @code{newsticker-plainview-hooks} contains hook which -apply to the plainview reader only. -@end itemize - -@item -@code{newsticker-miscellaneous} contains other Newsticker options. - -@item -@code{newsticker-ticker} contains options that define how headlines -are shown in the echo area, i.e. the ``ticker''. - -@itemize -@item -@vindex newsticker-display-interval -@vindex newsticker-scroll-smoothly -@code{newsticker-ticker-interval} and -@code{newsticker-scroll-smoothly} define how headlines are shown in -the echo area. -@end itemize - - -@item -@code{newsticker-reader} contains options for adjusting the headline reader. - -@itemize -@item -@vindex newsticker-frontend -@code{newsticker-frontend} determines the actual headline reader. The -``plainview'' reader uses a single buffer, the ``treeview'' uses -separate buffers and windows. -@end itemize - -@itemize -@item -@vindex newsticker-plainview -The subgroup @code{newsticker-plainview} contains options for the -plainview reader. -@item -@vindex newsticker-treeview -The subgroup @code{newsticker-treeview} contains options for the -treeview reader. -@end itemize - -@end itemize - -For the complete list of options please have a look at the -customization buffers. - -@node Remarks -@chapter Remarks - -Byte-compiling newsticker.el is recommended. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index - -@printindex cp - -@bye diff --git a/doc/misc/nxml-mode.texi b/doc/misc/nxml-mode.texi deleted file mode 100644 index c8d159e2363..00000000000 --- a/doc/misc/nxml-mode.texi +++ /dev/null @@ -1,902 +0,0 @@ -\input texinfo @c -*- texinfo -*- -@c %**start of header -@setfilename ../../info/nxml-mode -@settitle nXML Mode -@c %**end of header - -@copying -This manual documents nXML mode, an Emacs major mode for editing -XML with RELAX NG support. - -Copyright @copyright{} 2007-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs editing modes -@direntry -* nXML Mode: (nxml-mode). XML editing mode with RELAX NG support. -@end direntry - -@node Top -@top nXML Mode - -@insertcopying - -This manual is not yet complete. - -@menu -* Introduction:: -* Completion:: -* Inserting end-tags:: -* Paragraphs:: -* Outlining:: -* Locating a schema:: -* DTDs:: -* Limitations:: -@end menu - -@node Introduction -@chapter Introduction - -nXML mode is an Emacs major-mode for editing XML documents. It supports -editing well-formed XML documents, and provides schema-sensitive editing -using RELAX NG Compact Syntax. To get started, visit a file containing an -XML document, and, if necessary, use @kbd{M-x nxml-mode} to switch to nXML -mode. By default, @code{auto-mode-alist} and @code{magic-fallback-alist} -put buffers in nXML mode if they have recognizable XML content or file -extensions. You may wish to customize the settings, for example to -recognize different file extensions. - -Once in nXML mode, you can type @kbd{C-h m} for basic information on the -mode. - -The @file{etc/nxml} directory in the Emacs distribution contains some data -files used by nXML mode, and includes two files (@file{test-valid.xml} and -@file{test-invalid.xml}) that provide examples of valid and invalid XML -documents. - -To get validation and schema-sensitive editing, you need a RELAX NG Compact -Syntax (RNC) schema for your document (@pxref{Locating a schema}). The -@file{etc/schema} directory includes some schemas for popular document -types. See @url{http://relaxng.org/} for more information on RELAX NG. -You can use the @samp{Trang} program from -@url{http://www.thaiopensource.com/relaxng/trang.html} to -automatically create RNC schemas. This program can: - -@itemize @bullet -@item -infer an RNC schema from an instance document; -@item -convert a DTD to an RNC schema; -@item -convert a RELAX NG XML syntax schema to an RNC schema. -@end itemize - -@noindent To convert a RELAX NG XML syntax (@samp{.rng}) schema to a RNC -one, you can also use the XSLT stylesheet from -@url{http://www.pantor.com/download.html}. - -To convert a W3C XML Schema to an RNC schema, you need first to convert it -to RELAX NG XML syntax using the RELAX NG converter tool @code{rngconv} -(built on top of MSV). See @url{https://github.com/kohsuke/msv} -and @url{https://msv.dev.java.net/}. - -For historical discussions only, see the mailing list archives at -@url{http://groups.yahoo.com/group/emacs-nxml-mode/}. Please make all new -discussions on the @samp{help-gnu-emacs} and @samp{emacs-devel} mailing -lists. Report any bugs with @kbd{M-x report-emacs-bug}. - - -@node Completion -@chapter Completion - -Apart from real-time validation, the most important feature that nXML -mode provides for assisting in document creation is "completion". -Completion assists the user in inserting characters at point, based on -knowledge of the schema and on the contents of the buffer before -point. - -nXML mode adapts the standard GNU Emacs command for completion in a -buffer: @code{completion-at-point}, which is bound to @kbd{C-M-i} and -@kbd{M-@key{TAB}}. Note that many window systems and window managers -use @kbd{M-@key{TAB}} themselves (typically for switching between -windows) and do not pass it to applications. In that case, you should -type @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} for completion, or bind -@code{completion-at-point} to a key that is convenient for you. In -the following, I will assume that you type @kbd{C-M-i}. - -nXML mode completion works by examining the symbol preceding point. -This is the symbol to be completed. The symbol to be completed may be -the empty. Completion considers what symbols starting with the symbol -to be completed would be valid replacements for the symbol to be -completed, given the schema and the contents of the buffer before -point. These symbols are the possible completions. An example may -make this clearer. Suppose the buffer looks like this (where @point{} -indicates point): - -@example - - - -<@point{} -@end example - -@noindent -In this case, the symbol to be completed is empty, and the possible -completions are @samp{base}, @samp{isindex}, -@samp{link}, @samp{meta}, @samp{script}, -@samp{style}, @samp{title}. Another example is: - -@example - -<@point{} -@end example - -@noindent -@kbd{C-M-i} will yield - -@example - - - - - - -@end example - -@noindent -This says to use the schema @samp{xhtml.rnc} for a document with -namespace @samp{http://www.w3.org/1999/xhtml}, and to use the -schema @samp{docbook.rnc} for a document whose local name is -@samp{book}. If the document element had both a namespace URI -of @samp{http://www.w3.org/1999/xhtml} and a local name of -@samp{book}, then the matching rule that comes first will be -used and so the schema @samp{xhtml.rnc} would be used. There is -no precedence between different types of rule; the first matching rule -of any type is used. - -As usual with XML-related technologies, resources are identified -by URIs. The @samp{uri} attribute identifies the schema by -specifying the URI. The URI may be relative. If so, it is resolved -relative to the URI of the schema locating file that contains -attribute. This means that if the value of @samp{uri} attribute -does not contain a @samp{/}, then it will refer to a filename in -the same directory as the schema locating file. - -@node Using the document's URI to locate a schema -@subsection Using the document's URI to locate a schema - -A @samp{uri} rule locates a schema based on the URI of the -document. The @samp{uri} attribute specifies the URI of the -schema. The @samp{resource} attribute can be used to specify -the schema for a particular document. For example, - -@example - -@end example - -@noindent -specifies that the schema for @samp{spec.xml} is -@samp{docbook.rnc}. - -The @samp{pattern} attribute can be used instead of the -@samp{resource} attribute to specify the schema for any document -whose URI matches a pattern. The pattern has the same syntax as an -absolute or relative URI except that the path component of the URI can -use a @samp{*} character to stand for zero or more characters -within a path segment (i.e. any character other @samp{/}). -Typically, the URI pattern looks like a relative URI, but, whereas a -relative URI in the @samp{resource} attribute is resolved into a -particular absolute URI using the base URI of the schema locating -file, a relative URI pattern matches if it matches some number of -complete path segments of the document's URI ending with the last path -segment of the document's URI. For example, - -@example - -@end example - -@noindent -specifies that the schema for documents with a URI whose path ends -with @samp{.xsl} is @samp{xslt.rnc}. - -A @samp{transformURI} rule locates a schema by -transforming the URI of the document. The @samp{fromPattern} -attribute specifies a URI pattern with the same meaning as the -@samp{pattern} attribute of the @samp{uri} element. The -@samp{toPattern} attribute is a URI pattern that is used to -generate the URI of the schema. Each @samp{*} in the -@samp{toPattern} is replaced by the string that matched the -corresponding @samp{*} in the @samp{fromPattern}. The -resulting string is appended to the initial part of the document's URI -that was not explicitly matched by the @samp{fromPattern}. The -rule matches only if the transformed URI identifies an existing -resource. For example, the rule - -@example - -@end example - -@noindent -would transform the URI @samp{file:///home/jjc/docs/spec.xml} -into the URI @samp{file:///home/jjc/docs/spec.rnc}. Thus, this -rule specifies that to locate a schema for a document -@samp{@var{foo}.xml}, Emacs should test whether a file -@samp{@var{foo}.rnc} exists in the same directory as -@samp{@var{foo}.xml}, and, if so, should use it as the -schema. - -@node Using the document element to locate a schema -@subsection Using the document element to locate a schema - -A @samp{documentElement} rule locates a schema based on -the local name and prefix of the document element. For example, a rule - -@example - -@end example - -@noindent -specifies that when the name of the document element is -@samp{xsl:stylesheet}, then @samp{xslt.rnc} should be used -as the schema. Either the @samp{prefix} or -@samp{localName} attribute may be omitted to allow any prefix or -local name. - -A @samp{namespace} rule locates a schema based on the -namespace URI of the document element. For example, a rule - -@example - -@end example - -@noindent -specifies that when the namespace URI of the document is -@samp{http://www.w3.org/1999/XSL/Transform}, then -@samp{xslt.rnc} should be used as the schema. - -@node Using type identifiers in schema locating files -@subsection Using type identifiers in schema locating files - -Type identifiers allow a level of indirection in locating the -schema for a document. Instead of associating the document directly -with a schema URI, the document is associated with a type identifier, -which is in turn associated with a schema URI. nXML mode does not -constrain the format of type identifiers. They can be simply strings -without any formal structure or they can be public identifiers or -URIs. Note that these type identifiers have nothing to do with the -DOCTYPE declaration. When comparing type identifiers, whitespace is -normalized in the same way as with the @samp{xsd:token} -datatype: leading and trailing whitespace is stripped; other sequences -of whitespace are normalized to a single space character. - -Each of the rules described in previous sections that uses a -@samp{uri} attribute to specify a schema, can instead use a -@samp{typeId} attribute to specify a type identifier. The type -identifier can be associated with a URI using a @samp{typeId} -element. For example, - -@example - - - - - - -@end example - -@noindent -declares three type identifiers @samp{XHTML} (representing the -default variant of XHTML to be used), @samp{XHTML Strict} and -@samp{XHTML Transitional}. Such a schema locating file would -use @samp{xhtml-strict.rnc} for a document whose namespace is -@samp{http://www.w3.org/1999/xhtml}. But it is considerably -more flexible than a schema locating file that simply specified - -@example - -@end example - -@noindent -A user can easily use @kbd{C-c C-s C-t} to select between XHTML -Strict and XHTML Transitional. Also, a user can easily add a catalog - -@example - - - -@end example - -@noindent -that makes the default variant of XHTML be XHTML Transitional. - -@node Using multiple schema locating files -@subsection Using multiple schema locating files - -The @samp{include} element includes rules from another -schema locating file. The behavior is exactly as if the rules from -that file were included in place of the @samp{include} element. -Relative URIs are resolved into absolute URIs before the inclusion is -performed. For example, - -@example - -@end example - -@noindent -includes the rules from @samp{rules.xml}. - -The process of locating a schema takes as input a list of schema -locating files. The rules in all these files and in the files they -include are resolved into a single list of rules, which are applied -strictly in order. Sometimes this order is not what is needed. -For example, suppose you have two schema locating files, a private -file - -@example - - - -@end example - -@noindent -followed by a public file - -@example - - - - -@end example - -@noindent -The effect of these two files is that the XHTML @samp{namespace} -rule takes precedence over the @samp{transformURI} rule, which -is almost certainly not what is needed. This can be solved by adding -an @samp{applyFollowingRules} to the private file. - -@example - - - - -@end example - -@node DTDs -@chapter DTDs - -nXML mode is designed to support the creation of standalone XML -documents that do not depend on a DTD. Although it is common practice -to insert a DOCTYPE declaration referencing an external DTD, this has -undesirable side-effects. It means that the document is no longer -self-contained. It also means that different XML parsers may interpret -the document in different ways, since the XML Recommendation does not -require XML parsers to read the DTD. With DTDs, it was impractical to -get validation without using an external DTD or reference to an -parameter entity. With RELAX NG and other schema languages, you can -simultaneously get the benefits of validation and standalone XML -documents. Therefore, I recommend that you do not reference an -external DOCTYPE in your XML documents. - -One problem is entities for characters. Typically, as well as -providing validation, DTDs also provide a set of character entities -for documents to use. Schemas cannot provide this functionality, -because schema validation happens after XML parsing. The recommended -solution is to either use the Unicode characters directly, or, if this -is impractical, use character references. nXML mode supports this by -providing commands for entering characters and character references -using the Unicode names, and can display the glyph corresponding to a -character reference. - -@node Limitations -@chapter Limitations - -nXML mode has some limitations: - -@itemize @bullet -@item -DTD support is limited. Internal parsed general entities declared -in the internal subset are supported provided they do not contain -elements. Other usage of DTDs is ignored. -@item -The restrictions on RELAX NG schemas in section 7 of the RELAX NG -specification are not enforced. -@end itemize - -@bye diff --git a/doc/misc/org.texi b/doc/misc/org.texi deleted file mode 100644 index 575b9cbebe6..00000000000 --- a/doc/misc/org.texi +++ /dev/null @@ -1,16640 +0,0 @@ - -\input texinfo -@c %**start of header -@setfilename ../../info/org -@settitle The Org Manual - -@set VERSION 7.8.11 -@set DATE May 2012 - -@c Use proper quote and backtick for code sections in PDF output -@c Cf. Texinfo manual 14.2 -@set txicodequoteundirected -@set txicodequotebacktick - -@c Version and Contact Info -@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage} -@set AUTHOR Carsten Dominik -@set MAINTAINER Carsten Dominik -@set MAINTAINEREMAIL @email{carsten at orgmode dot org} -@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer} -@c %**end of header -@finalout - - -@c ----------------------------------------------------------------------------- - -@c Macro definitions for commands and keys -@c ======================================= - -@c The behavior of the key/command macros will depend on the flag cmdnames -@c When set, commands names are shown. When clear, they are not shown. - -@set cmdnames - -@c Below we define the following macros for Org key tables: - -@c orgkey{key} A key item -@c orgcmd{key,cmd} Key with command name -@c xorgcmd{key,cmd} Key with command name as @itemx -@c orgcmdnki{key,cmd} Like orgcmd, but do not index the key -@c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key -@c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or" -@c orgcmdkxkc{key1,key2,cmd} Two keys with one command name, but -@c different functions, so format as @itemx -@c orgcmdkskc{key1,key2,cmd} Same as orgcmdkkc, but use "or short" -@c xorgcmdkskc{key1,key2,cmd} Same as previous, but use @itemx -@c orgcmdkkcc{key1,key2,cmd1,cmd2} Two keys and two commands - -@c a key but no command -@c Inserts: @item key -@macro orgkey{key} -@kindex \key\ -@item @kbd{\key\} -@end macro - -@macro xorgkey{key} -@kindex \key\ -@itemx @kbd{\key\} -@end macro - -@c one key with a command -@c Inserts: @item KEY COMMAND -@macro orgcmd{key,command} -@ifset cmdnames -@kindex \key\ -@findex \command\ -@iftex -@item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\} -@end iftex -@ifnottex -@item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) -@end ifnottex -@end ifset -@ifclear cmdnames -@kindex \key\ -@item @kbd{\key\} -@end ifclear -@end macro - -@c One key with one command, formatted using @itemx -@c Inserts: @itemx KEY COMMAND -@macro xorgcmd{key,command} -@ifset cmdnames -@kindex \key\ -@findex \command\ -@iftex -@itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\} -@end iftex -@ifnottex -@itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) -@end ifnottex -@end ifset -@ifclear cmdnames -@kindex \key\ -@itemx @kbd{\key\} -@end ifclear -@end macro - -@c one key with a command, bit do not index the key -@c Inserts: @item KEY COMMAND -@macro orgcmdnki{key,command} -@ifset cmdnames -@findex \command\ -@iftex -@item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\} -@end iftex -@ifnottex -@item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) -@end ifnottex -@end ifset -@ifclear cmdnames -@item @kbd{\key\} -@end ifclear -@end macro - -@c one key with a command, and special text to replace key in item -@c Inserts: @item TEXT COMMAND -@macro orgcmdtkc{text,key,command} -@ifset cmdnames -@kindex \key\ -@findex \command\ -@iftex -@item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\} -@end iftex -@ifnottex -@item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) -@end ifnottex -@end ifset -@ifclear cmdnames -@kindex \key\ -@item @kbd{\text\} -@end ifclear -@end macro - -@c two keys with one command -@c Inserts: @item KEY1 or KEY2 COMMAND -@macro orgcmdkkc{key1,key2,command} -@ifset cmdnames -@kindex \key1\ -@kindex \key2\ -@findex \command\ -@iftex -@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\} -@end iftex -@ifnottex -@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) -@end ifnottex -@end ifset -@ifclear cmdnames -@kindex \key1\ -@kindex \key2\ -@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} -@end ifclear -@end macro - -@c Two keys with one command name, but different functions, so format as -@c @itemx -@c Inserts: @item KEY1 -@c @itemx KEY2 COMMAND -@macro orgcmdkxkc{key1,key2,command} -@ifset cmdnames -@kindex \key1\ -@kindex \key2\ -@findex \command\ -@iftex -@item @kbd{\key1\} -@itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\} -@end iftex -@ifnottex -@item @kbd{\key1\} -@itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) -@end ifnottex -@end ifset -@ifclear cmdnames -@kindex \key1\ -@kindex \key2\ -@item @kbd{\key1\} -@itemx @kbd{\key2\} -@end ifclear -@end macro - -@c Same as previous, but use "or short" -@c Inserts: @item KEY1 or short KEY2 COMMAND -@macro orgcmdkskc{key1,key2,command} -@ifset cmdnames -@kindex \key1\ -@kindex \key2\ -@findex \command\ -@iftex -@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\} -@end iftex -@ifnottex -@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) -@end ifnottex -@end ifset -@ifclear cmdnames -@kindex \key1\ -@kindex \key2\ -@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} -@end ifclear -@end macro - -@c Same as previous, but use @itemx -@c Inserts: @itemx KEY1 or short KEY2 COMMAND -@macro xorgcmdkskc{key1,key2,command} -@ifset cmdnames -@kindex \key1\ -@kindex \key2\ -@findex \command\ -@iftex -@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\} -@end iftex -@ifnottex -@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) -@end ifnottex -@end ifset -@ifclear cmdnames -@kindex \key1\ -@kindex \key2\ -@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} -@end ifclear -@end macro - -@c two keys with two commands -@c Inserts: @item KEY1 COMMAND1 -@c @itemx KEY2 COMMAND2 -@macro orgcmdkkcc{key1,key2,command1,command2} -@ifset cmdnames -@kindex \key1\ -@kindex \key2\ -@findex \command1\ -@findex \command2\ -@iftex -@item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\} -@itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\} -@end iftex -@ifnottex -@item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\}) -@itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\}) -@end ifnottex -@end ifset -@ifclear cmdnames -@kindex \key1\ -@kindex \key2\ -@item @kbd{\key1\} -@itemx @kbd{\key2\} -@end ifclear -@end macro -@c ----------------------------------------------------------------------------- - -@iftex -@c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed} -@end iftex - -@c Subheadings inside a table. -@macro tsubheading{text} -@ifinfo -@subsubheading \text\ -@end ifinfo -@ifnotinfo -@item @b{\text\} -@end ifnotinfo -@end macro - -@copying -This manual is for Org version @value{VERSION}. - -Copyright @copyright{} 2004-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs editing modes -@direntry -* Org Mode: (org). Outline-based notes management and organizer -@end direntry - -@titlepage -@title The Org Manual - -@subtitle Release @value{VERSION} -@author by Carsten Dominik -with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, Thomas Dye and Jambunathan K. - -@c The following two commands start the copyright page. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@c Output the table of contents at the beginning. -@contents - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top Org Mode Manual - -@insertcopying -@end ifnottex - -@menu -* Introduction:: Getting started -* Document Structure:: A tree works like your brain -* Tables:: Pure magic for quick formatting -* Hyperlinks:: Notes in context -* TODO Items:: Every tree branch can be a TODO item -* Tags:: Tagging headlines and matching sets of tags -* Properties and Columns:: Storing information about an entry -* Dates and Times:: Making items useful for planning -* Capture - Refile - Archive:: The ins and outs for projects -* Agenda Views:: Collecting information into views -* Markup:: Prepare text for rich export -* Exporting:: Sharing and publishing of notes -* Publishing:: Create a web site of linked Org files -* Working With Source Code:: Export, evaluate, and tangle code blocks -* Miscellaneous:: All the rest which did not fit elsewhere -* Hacking:: How to hack your way around -* MobileOrg:: Viewing and capture on a mobile device -* History and Acknowledgments:: How Org came into being -* Main Index:: An index of Org's concepts and features -* Key Index:: Key bindings and where they are described -* Command and Function Index:: Command names and some internal functions -* Variable Index:: Variables mentioned in the manual - -@detailmenu - --- The Detailed Node Listing --- - -Introduction - -* Summary:: Brief summary of what Org does -* Installation:: How to install a downloaded version of Org -* Activation:: How to activate Org for certain buffers -* Feedback:: Bug reports, ideas, patches etc. -* Conventions:: Type-setting conventions in the manual - -Document structure - -* Outlines:: Org is based on Outline mode -* Headlines:: How to typeset Org tree headlines -* Visibility cycling:: Show and hide, much simplified -* Motion:: Jumping to other headlines -* Structure editing:: Changing sequence and level of headlines -* Sparse trees:: Matches embedded in context -* Plain lists:: Additional structure within an entry -* Drawers:: Tucking stuff away -* Blocks:: Folding blocks -* Footnotes:: How footnotes are defined in Org's syntax -* Orgstruct mode:: Structure editing outside Org - -Tables - -* Built-in table editor:: Simple tables -* Column width and alignment:: Overrule the automatic settings -* Column groups:: Grouping to trigger vertical lines -* Orgtbl mode:: The table editor as minor mode -* The spreadsheet:: The table editor has spreadsheet capabilities -* Org-Plot:: Plotting from org tables - -The spreadsheet - -* References:: How to refer to another field or range -* Formula syntax for Calc:: Using Calc to compute stuff -* Formula syntax for Lisp:: Writing formulas in Emacs Lisp -* Durations and time values:: How to compute durations and time values -* Field and range formulas:: Formula for specific (ranges of) fields -* Column formulas:: Formulas valid for an entire column -* Editing and debugging formulas:: Fixing formulas -* Updating the table:: Recomputing all dependent fields -* Advanced features:: Field and column names, parameters and automatic recalc - -Hyperlinks - -* Link format:: How links in Org are formatted -* Internal links:: Links to other places in the current file -* External links:: URL-like links to the world -* Handling links:: Creating, inserting and following -* Using links outside Org:: Linking from my C source code? -* Link abbreviations:: Shortcuts for writing complex links -* Search options:: Linking to a specific location -* Custom searches:: When the default search is not enough - -Internal links - -* Radio targets:: Make targets trigger links in plain text - -TODO items - -* TODO basics:: Marking and displaying TODO entries -* TODO extensions:: Workflow and assignments -* Progress logging:: Dates and notes for progress -* Priorities:: Some things are more important than others -* Breaking down tasks:: Splitting a task into manageable pieces -* Checkboxes:: Tick-off lists - -Extended use of TODO keywords - -* Workflow states:: From TODO to DONE in steps -* TODO types:: I do this, Fred does the rest -* Multiple sets in one file:: Mixing it all, and still finding your way -* Fast access to TODO states:: Single letter selection of a state -* Per-file keywords:: Different files, different requirements -* Faces for TODO keywords:: Highlighting states -* TODO dependencies:: When one task needs to wait for others - -Progress logging - -* Closing items:: When was this entry marked DONE? -* Tracking TODO state changes:: When did the status change? -* Tracking your habits:: How consistent have you been? - -Tags - -* Tag inheritance:: Tags use the tree structure of the outline -* Setting tags:: How to assign tags to a headline -* Tag searches:: Searching for combinations of tags - -Properties and columns - -* Property syntax:: How properties are spelled out -* Special properties:: Access to other Org mode features -* Property searches:: Matching property values -* Property inheritance:: Passing values down the tree -* Column view:: Tabular viewing and editing -* Property API:: Properties for Lisp programmers - -Column view - -* Defining columns:: The COLUMNS format property -* Using column view:: How to create and use column view -* Capturing column view:: A dynamic block for column view - -Defining columns - -* Scope of column definitions:: Where defined, where valid? -* Column attributes:: Appearance and content of a column - -Dates and times - -* Timestamps:: Assigning a time to a tree entry -* Creating timestamps:: Commands which insert timestamps -* Deadlines and scheduling:: Planning your work -* Clocking work time:: Tracking how long you spend on a task -* Effort estimates:: Planning work effort in advance -* Relative timer:: Notes with a running timer -* Countdown timer:: Starting a countdown timer for a task - -Creating timestamps - -* The date/time prompt:: How Org mode helps you entering date and time -* Custom time format:: Making dates look different - -Deadlines and scheduling - -* Inserting deadline/schedule:: Planning items -* Repeated tasks:: Items that show up again and again - -Clocking work time - -* Clocking commands:: Starting and stopping a clock -* The clock table:: Detailed reports -* Resolving idle time:: Resolving time when you've been idle - -Capture - Refile - Archive - -* Capture:: Capturing new stuff -* Attachments:: Add files to tasks -* RSS Feeds:: Getting input from RSS feeds -* Protocols:: External (e.g.@: Browser) access to Emacs and Org -* Refiling notes:: Moving a tree from one place to another -* Archiving:: What to do with finished projects - -Capture - -* Setting up capture:: Where notes will be stored -* Using capture:: Commands to invoke and terminate capture -* Capture templates:: Define the outline of different note types - -Capture templates - -* Template elements:: What is needed for a complete template entry -* Template expansion:: Filling in information about time and context - -Archiving - -* Moving subtrees:: Moving a tree to an archive file -* Internal archiving:: Switch off a tree but keep it in the file - -Agenda views - -* Agenda files:: Files being searched for agenda information -* Agenda dispatcher:: Keyboard access to agenda views -* Built-in agenda views:: What is available out of the box? -* Presentation and sorting:: How agenda items are prepared for display -* Agenda commands:: Remote editing of Org trees -* Custom agenda views:: Defining special searches and views -* Exporting Agenda Views:: Writing a view to a file -* Agenda column view:: Using column view for collected entries - -The built-in agenda views - -* Weekly/daily agenda:: The calendar page with current tasks -* Global TODO list:: All unfinished action items -* Matching tags and properties:: Structured information with fine-tuned search -* Timeline:: Time-sorted view for single file -* Search view:: Find entries by searching for text -* Stuck projects:: Find projects you need to review - -Presentation and sorting - -* Categories:: Not all tasks are equal -* Time-of-day specifications:: How the agenda knows the time -* Sorting of agenda items:: The order of things - -Custom agenda views - -* Storing searches:: Type once, use often -* Block agenda:: All the stuff you need in a single buffer -* Setting Options:: Changing the rules - -Markup for rich export - -* Structural markup elements:: The basic structure as seen by the exporter -* Images and tables:: Tables and Images will be included -* Literal examples:: Source code examples with special formatting -* Include files:: Include additional files into a document -* Index entries:: Making an index -* Macro replacement:: Use macros to create complex output -* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents - -Structural markup elements - -* Document title:: Where the title is taken from -* Headings and sections:: The document structure as seen by the exporter -* Table of contents:: The if and where of the table of contents -* Initial text:: Text before the first heading? -* Lists:: Lists -* Paragraphs:: Paragraphs -* Footnote markup:: Footnotes -* Emphasis and monospace:: Bold, italic, etc. -* Horizontal rules:: Make a line -* Comment lines:: What will *not* be exported - -Embedded @LaTeX{} - -* Special symbols:: Greek letters and other symbols -* Subscripts and superscripts:: Simple syntax for raising/lowering text -* @LaTeX{} fragments:: Complex formulas made easy -* Previewing @LaTeX{} fragments:: What will this snippet look like? -* CDLaTeX mode:: Speed up entering of formulas - -Exporting - -* Selective export:: Using tags to select and exclude trees -* Export options:: Per-file export settings -* The export dispatcher:: How to access exporter commands -* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding -* HTML export:: Exporting to HTML -* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF -* DocBook export:: Exporting to DocBook -* OpenDocument Text export:: Exporting to OpenDocument Text -* TaskJuggler export:: Exporting to TaskJuggler -* Freemind export:: Exporting to Freemind mind maps -* XOXO export:: Exporting to XOXO -* iCalendar export:: Exporting in iCalendar format - -HTML export - -* HTML Export commands:: How to invoke HTML export -* HTML preamble and postamble:: How to insert a preamble and a postamble -* Quoting HTML tags:: Using direct HTML in Org mode -* Links in HTML export:: How links will be interpreted and formatted -* Tables in HTML export:: How to modify the formatting of tables -* Images in HTML export:: How to insert figures into HTML output -* Math formatting in HTML export:: Beautiful math also on the web -* Text areas in HTML export:: An alternative way to show an example -* CSS support:: Changing the appearance of the output -* JavaScript support:: Info and Folding in a web browser - -@LaTeX{} and PDF export - -* @LaTeX{}/PDF export commands:: -* Header and sectioning:: Setting up the export file structure -* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code -* Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{} -* Images in @LaTeX{} export:: How to insert figures into @LaTeX{} output -* Beamer class export:: Turning the file into a presentation - -DocBook export - -* DocBook export commands:: How to invoke DocBook export -* Quoting DocBook code:: Incorporating DocBook code in Org files -* Recursive sections:: Recursive sections in DocBook -* Tables in DocBook export:: Tables are exported as HTML tables -* Images in DocBook export:: How to insert figures into DocBook output -* Special characters:: How to handle special characters - -OpenDocument Text export - -* Pre-requisites for ODT export:: What packages ODT exporter relies on -* ODT export commands:: How to invoke ODT export -* Extending ODT export:: How to produce @samp{doc}, @samp{pdf} files -* Applying custom styles:: How to apply custom styles to the output -* Links in ODT export:: How links will be interpreted and formatted -* Tables in ODT export:: How Tables are exported -* Images in ODT export:: How to insert images -* Math formatting in ODT export:: How @LaTeX{} fragments are formatted -* Labels and captions in ODT export:: How captions are rendered -* Literal examples in ODT export:: How source and example blocks are formatted -* Advanced topics in ODT export:: Read this if you are a power user - -Math formatting in ODT export - -* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments -* Working with MathML or OpenDocument formula files:: How to embed equations in native format - -Advanced topics in ODT export - -* Configuring a document converter:: How to register a document converter -* Working with OpenDocument style files:: Explore the internals -* Creating one-off styles:: How to produce custom highlighting etc -* Customizing tables in ODT export:: How to define and use Table templates -* Validating OpenDocument XML:: How to debug corrupt OpenDocument files - -Publishing - -* Configuration:: Defining projects -* Uploading files:: How to get files up on the server -* Sample configuration:: Example projects -* Triggering publication:: Publication commands - -Configuration - -* Project alist:: The central configuration variable -* Sources and destinations:: From here to there -* Selecting files:: What files are part of the project? -* Publishing action:: Setting the function doing the publishing -* Publishing options:: Tweaking HTML/@LaTeX{} export -* Publishing links:: Which links keep working after publishing? -* Sitemap:: Generating a list of all pages -* Generating an index:: An index that reaches across pages - -Sample configuration - -* Simple example:: One-component publishing -* Complex example:: A multi-component publishing example - -Working with source code - -* Structure of code blocks:: Code block syntax described -* Editing source code:: Language major-mode editing -* Exporting code blocks:: Export contents and/or results -* Extracting source code:: Create pure source code files -* Evaluating code blocks:: Place results of evaluation in the Org mode buffer -* Library of Babel:: Use and contribute to a library of useful code blocks -* Languages:: List of supported code block languages -* Header arguments:: Configure code block functionality -* Results of evaluation:: How evaluation results are handled -* Noweb reference syntax:: Literate programming in Org mode -* Key bindings and useful functions:: Work quickly with code blocks -* Batch execution:: Call functions from the command line - -Header arguments - -* Using header arguments:: Different ways to set header arguments -* Specific header arguments:: List of header arguments - -Using header arguments - -* System-wide header arguments:: Set global default values -* Language-specific header arguments:: Set default values by language -* Buffer-wide header arguments:: Set default values for a specific buffer -* Header arguments in Org mode properties:: Set default values for a buffer or heading -* Code block specific header arguments:: The most common way to set values -* Header arguments in function calls:: The most specific level - -Specific header arguments - -* var:: Pass arguments to code blocks -* results:: Specify the type of results and how they will - be collected and handled -* file:: Specify a path for file output -* dir:: Specify the default (possibly remote) - directory for code block execution -* exports:: Export code and/or results -* tangle:: Toggle tangling and specify file name -* mkdirp:: Toggle creation of parent directories of target - files during tangling -* comments:: Toggle insertion of comments in tangled - code files -* padline:: Control insertion of padding lines in tangled - code files -* no-expand:: Turn off variable assignment and noweb - expansion during tangling -* session:: Preserve the state of code evaluation -* noweb:: Toggle expansion of noweb references -* noweb-ref:: Specify block's noweb reference resolution target -* noweb-sep:: String used to separate noweb references -* cache:: Avoid re-evaluating unchanged code blocks -* sep:: Delimiter for writing tabular results outside Org -* hlines:: Handle horizontal lines in tables -* colnames:: Handle column names in tables -* rownames:: Handle row names in tables -* shebang:: Make tangled files executable -* eval:: Limit evaluation of specific code blocks - -Miscellaneous - -* Completion:: M-TAB knows what you need -* Easy Templates:: Quick insertion of structural elements -* Speed keys:: Electric commands at the beginning of a headline -* Code evaluation security:: Org mode files evaluate inline code -* Customization:: Adapting Org to your taste -* In-buffer settings:: Overview of the #+KEYWORDS -* The very busy C-c C-c key:: When in doubt, press C-c C-c -* Clean view:: Getting rid of leading stars in the outline -* TTY keys:: Using Org on a tty -* Interaction:: Other Emacs packages -* org-crypt.el:: Encrypting Org files - -Interaction with other packages - -* Cooperation:: Packages Org cooperates with -* Conflicts:: Packages that lead to conflicts - -Hacking - -* Hooks:: Who to reach into Org's internals -* Add-on packages:: Available extensions -* Adding hyperlink types:: New custom link types -* Context-sensitive commands:: How to add functionality to such commands -* Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs -* Dynamic blocks:: Automatically filled blocks -* Special agenda views:: Customized views -* Extracting agenda information:: Postprocessing of agenda information -* Using the property API:: Writing programs that use entry properties -* Using the mapping API:: Mapping over all or selected entries - -Tables and lists in arbitrary syntax - -* Radio tables:: Sending and receiving radio tables -* A @LaTeX{} example:: Step by step, almost a tutorial -* Translator functions:: Copy and modify -* Radio lists:: Doing the same for lists - -MobileOrg - -* Setting up the staging area:: Where to interact with the mobile device -* Pushing to MobileOrg:: Uploading Org files and agendas -* Pulling from MobileOrg:: Integrating captured and flagged items - -@end detailmenu -@end menu - -@node Introduction, Document Structure, Top, Top -@chapter Introduction -@cindex introduction - -@menu -* Summary:: Brief summary of what Org does -* Installation:: How to install a downloaded version of Org -* Activation:: How to activate Org for certain buffers -* Feedback:: Bug reports, ideas, patches etc. -* Conventions:: Type-setting conventions in the manual -@end menu - -@node Summary, Installation, Introduction, Introduction -@section Summary -@cindex summary - -Org is a mode for keeping notes, maintaining TODO lists, and doing -project planning with a fast and effective plain-text system. - -Org develops organizational tasks around NOTES files that contain -lists or information about projects as plain text. Org is -implemented on top of Outline mode, which makes it possible to keep the -content of large files well structured. Visibility cycling and -structure editing help to work with the tree. Tables are easily created -with a built-in table editor. Org supports TODO items, deadlines, -timestamps, and scheduling. It dynamically compiles entries into an -agenda that utilizes and smoothly integrates much of the Emacs calendar -and diary. Plain text URL-like links connect to websites, emails, -Usenet messages, BBDB entries, and any files related to the projects. -For printing and sharing of notes, an Org file can be exported as a -structured ASCII file, as HTML, or (TODO and agenda items only) as an -iCalendar file. It can also serve as a publishing tool for a set of -linked web pages. - -As a project planning environment, Org works by adding metadata to outline -nodes. Based on this data, specific entries can be extracted in queries and -create dynamic @i{agenda views}. - -Org mode contains the Org Babel environment which allows you to work with -embedded source code blocks in a file, to facilitate code evaluation, -documentation, and literate programming techniques. - -Org's automatic, context-sensitive table editor with spreadsheet -capabilities can be integrated into any major mode by activating the -minor Orgtbl mode. Using a translation step, it can be used to maintain -tables in arbitrary file types, for example in @LaTeX{}. The structure -editing and list creation capabilities can be used outside Org with -the minor Orgstruct mode. - -Org keeps simple things simple. When first fired up, it should -feel like a straightforward, easy to use outliner. Complexity is not -imposed, but a large amount of functionality is available when you need -it. Org is a toolbox and can be used in different ways and for different -ends, for example: - -@example -@r{@bullet{} an outline extension with visibility cycling and structure editing} -@r{@bullet{} an ASCII system and table editor for taking structured notes} -@r{@bullet{} a TODO list editor} -@r{@bullet{} a full agenda and planner with deadlines and work scheduling} -@pindex GTD, Getting Things Done -@r{@bullet{} an environment in which to implement David Allen's GTD system} -@r{@bullet{} a simple hypertext system, with HTML and @LaTeX{} export} -@r{@bullet{} a publishing tool to create a set of interlinked webpages} -@r{@bullet{} an environment for literate programming} -@end example - - -@cindex FAQ -There is a website for Org which provides links to the newest -version of Org, as well as additional information, frequently asked -questions (FAQ), links to tutorials, etc@. This page is located at -@uref{http://orgmode.org}. - -@cindex print edition -The version 7.3 of this manual is available as a -@uref{http://www.network-theory.co.uk/org/manual/, paperback book from Network -Theory Ltd.} - -@page - - -@node Installation, Activation, Summary, Introduction -@section Installation -@cindex installation -@cindex XEmacs - -@b{Important:} @i{If you are using a version of Org that is part of the Emacs -distribution or an XEmacs package, please skip this section and go directly -to @ref{Activation}. To see what version of Org (if any) is part of your -Emacs distribution, type @kbd{M-x load-library RET org} and then @kbd{M-x -org-version}.} - -If you have downloaded Org from the Web, either as a distribution @file{.zip} -or @file{.tar} file, or as a Git archive, you must take the following steps -to install it: go into the unpacked Org distribution directory and edit the -top section of the file @file{Makefile}. You must set the name of the Emacs -binary (likely either @file{emacs} or @file{xemacs}), and the paths to the -directories where local Lisp and Info files are kept. If you don't have -access to the system-wide directories, you can simply run Org directly from -the distribution directory by adding the @file{lisp} subdirectory to the -Emacs load path. To do this, add the following line to @file{.emacs}: - -@example -(setq load-path (cons "~/path/to/orgdir/lisp" load-path)) -@end example - -@noindent -If you plan to use code from the @file{contrib} subdirectory, do a similar -step for this directory: - -@example -(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path)) -@end example - -@noindent Now byte-compile the Lisp files with the shell command: - -@example -make -@end example - -@noindent If you are running Org from the distribution directory, this is -all. If you want to install Org into the system directories, use (as -administrator) - -@example -make install -@end example - -Installing Info files is system dependent, because of differences in the -@file{install-info} program. The following should correctly install the Info -files on most systems, please send a bug report if not@footnote{The output -from install-info (if any) is also system dependent. In particular Debian -and its derivatives use two different versions of install-info and you may -see the message: - -@example -This is not dpkg install-info anymore, but GNU install-info -See the man page for ginstall-info for command line arguments -@end example - -@noindent which can be safely ignored.}. - -@example -make install-info -@end example - -Then add the following line to @file{.emacs}. It is needed so that -Emacs can autoload functions that are located in files not immediately loaded -when Org mode starts. -@lisp -(require 'org-install) -@end lisp - -Do not forget to activate Org as described in the following section. -@page - -@node Activation, Feedback, Installation, Introduction -@section Activation -@cindex activation -@cindex autoload -@cindex global key bindings -@cindex key bindings, global - -To make sure files with extension @file{.org} use Org mode, add the following -line to your @file{.emacs} file. -@lisp -(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode)) -@end lisp -@noindent Org mode buffers need font-lock to be turned on - this is the -default in Emacs@footnote{If you don't use font-lock globally, turn it on in -Org buffer with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}. - -The four Org commands @command{org-store-link}, @command{org-capture}, -@command{org-agenda}, and @command{org-iswitchb} should be accessible through -global keys (i.e.@: anywhere in Emacs, not just in Org buffers). Here are -suggested bindings for these keys, please modify the keys to your own -liking. -@lisp -(global-set-key "\C-cl" 'org-store-link) -(global-set-key "\C-cc" 'org-capture) -(global-set-key "\C-ca" 'org-agenda) -(global-set-key "\C-cb" 'org-iswitchb) -@end lisp - -@cindex Org mode, turning on -With this setup, all files with extension @samp{.org} will be put -into Org mode. As an alternative, make the first line of a file look -like this: - -@example -MY PROJECTS -*- mode: org; -*- -@end example - -@vindex org-insert-mode-line-in-empty-file -@noindent which will select Org mode for this buffer no matter what -the file's name is. See also the variable -@code{org-insert-mode-line-in-empty-file}. - -Many commands in Org work on the region if the region is @i{active}. To make -use of this, you need to have @code{transient-mark-mode} -(@code{zmacs-regions} in XEmacs) turned on. In Emacs 23 this is the default, -in Emacs 22 you need to do this yourself with -@lisp -(transient-mark-mode 1) -@end lisp -@noindent If you do not like @code{transient-mark-mode}, you can create an -active region by using the mouse to select a region, or pressing -@kbd{C-@key{SPC}} twice before moving the cursor. - -@node Feedback, Conventions, Activation, Introduction -@section Feedback -@cindex feedback -@cindex bug reports -@cindex maintainer -@cindex author - -If you find problems with Org, or if you have questions, remarks, or ideas -about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}. -If you are not a member of the mailing list, your mail will be passed to the -list after a moderator has approved it@footnote{Please consider subscribing -to the mailing list, in order to minimize the work the mailing list -moderators have to do.}. - -For bug reports, please first try to reproduce the bug with the latest -version of Org available---if you are running an outdated version, it is -quite possible that the bug has been fixed already. If the bug persists, -prepare a report and provide as much information as possible, including the -version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org -(@kbd{M-x org-version @key{RET}}), as well as the Org related setup in -@file{.emacs}. The easiest way to do this is to use the command -@example -@kbd{M-x org-submit-bug-report} -@end example -@noindent which will put all this information into an Emacs mail buffer so -that you only need to add your description. If you re not sending the Email -from within Emacs, please copy and paste the content into your Email program. - -Sometimes you might face a problem due to an error in your Emacs or Org mode -setup. Before reporting a bug, it is very helpful to start Emacs with minimal -customizations and reproduce the problem. Doing so often helps you determine -if the problem is with your customization or with Org mode itself. You can -start a typical minimal session with a command like the example below. - -@example -$ emacs -Q -l /path/to/minimal-org.el -@end example - -However if you are using Org mode as distributed with Emacs, a minimal setup -is not necessary. In that case it is sufficient to start Emacs as @code{emacs --Q}. The @code{minimal-org.el} setup file can have contents as shown below. - -@example -;;; Minimal setup to load latest `org-mode' - -;; activate debugging -(setq debug-on-error t - debug-on-signal nil - debug-on-quit nil) - -;; add latest org-mode to load path -(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp")) -(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp")) - -;; activate org -(require 'org-install) -@end example - -If an error occurs, a backtrace can be very useful (see below on how to -create one). Often a small example file helps, along with clear information -about: - -@enumerate -@item What exactly did you do? -@item What did you expect to happen? -@item What happened instead? -@end enumerate -@noindent Thank you for helping to improve this program. - -@subsubheading How to create a useful backtrace - -@cindex backtrace of an error -If working with Org produces an error with a message you don't -understand, you may have hit a bug. The best way to report this is by -providing, in addition to what was mentioned above, a @emph{backtrace}. -This is information from the built-in debugger about where and how the -error occurred. Here is how to produce a useful backtrace: - -@enumerate -@item -Reload uncompiled versions of all Org mode Lisp files. The backtrace -contains much more information if it is produced with uncompiled code. -To do this, use -@example -C-u M-x org-reload RET -@end example -@noindent -or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the -menu. -@item -Go to the @code{Options} menu and select @code{Enter Debugger on Error} -(XEmacs has this option in the @code{Troubleshooting} sub-menu). -@item -Do whatever you have to do to hit the error. Don't forget to -document the steps you take. -@item -When you hit the error, a @file{*Backtrace*} buffer will appear on the -screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and -attach it to your bug report. -@end enumerate - -@node Conventions, , Feedback, Introduction -@section Typesetting conventions used in this manual - -Org uses three types of keywords: TODO keywords, tags, and property -names. In this manual we use the following conventions: - -@table @code -@item TODO -@itemx WAITING -TODO keywords are written with all capitals, even if they are -user-defined. -@item boss -@itemx ARCHIVE -User-defined tags are written in lowercase; built-in tags with special -meaning are written with all capitals. -@item Release -@itemx PRIORITY -User-defined properties are capitalized; built-in properties with -special meaning are written with all capitals. -@end table - -The manual lists both the keys and the corresponding commands for accessing -functionality. Org mode often uses the same key for different functions, -depending on context. The command that is bound to such keys has a generic -name, like @code{org-metaright}. In the manual we will, wherever possible, -give the function that is internally called by the generic command. For -example, in the chapter on document structure, @kbd{M-@key{right}} will be -listed to call @code{org-do-demote}, while in the chapter on tables, it will -be listed to call org-table-move-column-right. - -If you prefer, you can compile the manual without the command names by -unsetting the flag @code{cmdnames} in @file{org.texi}. - -@node Document Structure, Tables, Introduction, Top -@chapter Document structure -@cindex document structure -@cindex structure of document - -Org is based on Outline mode and provides flexible commands to -edit the structure of the document. - -@menu -* Outlines:: Org is based on Outline mode -* Headlines:: How to typeset Org tree headlines -* Visibility cycling:: Show and hide, much simplified -* Motion:: Jumping to other headlines -* Structure editing:: Changing sequence and level of headlines -* Sparse trees:: Matches embedded in context -* Plain lists:: Additional structure within an entry -* Drawers:: Tucking stuff away -* Blocks:: Folding blocks -* Footnotes:: How footnotes are defined in Org's syntax -* Orgstruct mode:: Structure editing outside Org -@end menu - -@node Outlines, Headlines, Document Structure, Document Structure -@section Outlines -@cindex outlines -@cindex Outline mode - -Org is implemented on top of Outline mode. Outlines allow a -document to be organized in a hierarchical structure, which (at least -for me) is the best representation of notes and thoughts. An overview -of this structure is achieved by folding (hiding) large parts of the -document to show only the general document structure and the parts -currently being worked on. Org greatly simplifies the use of -outlines by compressing the entire show/hide functionality into a single -command, @command{org-cycle}, which is bound to the @key{TAB} key. - -@node Headlines, Visibility cycling, Outlines, Document Structure -@section Headlines -@cindex headlines -@cindex outline tree -@vindex org-special-ctrl-a/e -@vindex org-special-ctrl-k -@vindex org-ctrl-k-protect-subtree - -Headlines define the structure of an outline tree. The headlines in Org -start with one or more stars, on the left margin@footnote{See the variables -@code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and -@code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a}, -@kbd{C-e}, and @kbd{C-k} in headlines.}. For example: - -@example -* Top level headline -** Second level -*** 3rd level - some text -*** 3rd level - more text - -* Another top level headline -@end example - -@noindent Some people find the many stars too noisy and would prefer an -outline that has whitespace followed by a single star as headline -starters. @ref{Clean view}, describes a setup to realize this. - -@vindex org-cycle-separator-lines -An empty line after the end of a subtree is considered part of it and -will be hidden when the subtree is folded. However, if you leave at -least two empty lines, one empty line will remain visible after folding -the subtree, in order to structure the collapsed view. See the -variable @code{org-cycle-separator-lines} to modify this behavior. - -@node Visibility cycling, Motion, Headlines, Document Structure -@section Visibility cycling -@cindex cycling, visibility -@cindex visibility cycling -@cindex trees, visibility -@cindex show hidden text -@cindex hide text - -Outlines make it possible to hide parts of the text in the buffer. -Org uses just two commands, bound to @key{TAB} and -@kbd{S-@key{TAB}} to change the visibility in the buffer. - -@cindex subtree visibility states -@cindex subtree cycling -@cindex folded, subtree visibility state -@cindex children, subtree visibility state -@cindex subtree, subtree visibility state -@table @asis -@orgcmd{@key{TAB},org-cycle} -@emph{Subtree cycling}: Rotate current subtree among the states - -@example -,-> FOLDED -> CHILDREN -> SUBTREE --. -'-----------------------------------' -@end example - -@vindex org-cycle-emulate-tab -@vindex org-cycle-global-at-bob -The cursor must be on a headline for this to work@footnote{see, however, -the option @code{org-cycle-emulate-tab}.}. When the cursor is at the -beginning of the buffer and the first line is not a headline, then -@key{TAB} actually runs global cycling (see below)@footnote{see the -option @code{org-cycle-global-at-bob}.}. Also when called with a prefix -argument (@kbd{C-u @key{TAB}}), global cycling is invoked. - -@cindex global visibility states -@cindex global cycling -@cindex overview, global visibility state -@cindex contents, global visibility state -@cindex show all, global visibility state -@orgcmd{S-@key{TAB},org-global-cycle} -@itemx C-u @key{TAB} -@emph{Global cycling}: Rotate the entire buffer among the states - -@example -,-> OVERVIEW -> CONTENTS -> SHOW ALL --. -'--------------------------------------' -@end example - -When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the -CONTENTS view up to headlines of level N will be shown. Note that inside -tables, @kbd{S-@key{TAB}} jumps to the previous field. - -@cindex show all, command -@orgcmd{C-u C-u C-u @key{TAB},show-all} -Show all, including drawers. -@orgcmd{C-c C-r,org-reveal} -Reveal context around point, showing the current entry, the following heading -and the hierarchy above. Useful for working near a location that has been -exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command -(@pxref{Agenda commands}). With a prefix argument show, on each -level, all sibling headings. With a double prefix argument, also show the -entire subtree of the parent. -@orgcmd{C-c C-k,show-branches} -Expose all the headings of the subtree, CONTENT view for just one subtree. -@orgcmd{C-c C-x b,org-tree-to-indirect-buffer} -Show the current subtree in an indirect buffer@footnote{The indirect -buffer -@ifinfo -(@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual}) -@end ifinfo -@ifnotinfo -(see the Emacs manual for more information about indirect buffers) -@end ifnotinfo -will contain the entire buffer, but will be narrowed to the current -tree. Editing the indirect buffer will also change the original buffer, -but without affecting visibility in that buffer.}. With a numeric -prefix argument N, go up to level N and then take that tree. If N is -negative then go up that many levels. With a @kbd{C-u} prefix, do not remove -the previously used indirect buffer. -@orgcmd{C-c C-x v,org-copy-visible} -Copy the @i{visible} text in the region into the kill ring. -@end table - -@vindex org-startup-folded -@cindex @code{overview}, STARTUP keyword -@cindex @code{content}, STARTUP keyword -@cindex @code{showall}, STARTUP keyword -@cindex @code{showeverything}, STARTUP keyword - -When Emacs first visits an Org file, the global state is set to -OVERVIEW, i.e.@: only the top level headlines are visible. This can be -configured through the variable @code{org-startup-folded}, or on a -per-file basis by adding one of the following lines anywhere in the -buffer: - -@example -#+STARTUP: overview -#+STARTUP: content -#+STARTUP: showall -#+STARTUP: showeverything -@end example - -@cindex property, VISIBILITY -@noindent -Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties -and Columns}) will get their visibility adapted accordingly. Allowed values -for this property are @code{folded}, @code{children}, @code{content}, and -@code{all}. -@table @asis -@orgcmd{C-u C-u @key{TAB},org-set-startup-visibility} -Switch back to the startup visibility of the buffer, i.e.@: whatever is -requested by startup options and @samp{VISIBILITY} properties in individual -entries. -@end table - -@node Motion, Structure editing, Visibility cycling, Document Structure -@section Motion -@cindex motion, between headlines -@cindex jumping, to headlines -@cindex headline navigation -The following commands jump to other headlines in the buffer. - -@table @asis -@orgcmd{C-c C-n,outline-next-visible-heading} -Next heading. -@orgcmd{C-c C-p,outline-previous-visible-heading} -Previous heading. -@orgcmd{C-c C-f,org-forward-same-level} -Next heading same level. -@orgcmd{C-c C-b,org-backward-same-level} -Previous heading same level. -@orgcmd{C-c C-u,outline-up-heading} -Backward to higher level heading. -@orgcmd{C-c C-j,org-goto} -Jump to a different place without changing the current outline -visibility. Shows the document structure in a temporary buffer, where -you can use the following keys to find your destination: -@vindex org-goto-auto-isearch -@example -@key{TAB} @r{Cycle visibility.} -@key{down} / @key{up} @r{Next/previous visible headline.} -@key{RET} @r{Select this location.} -@kbd{/} @r{Do a Sparse-tree search} -@r{The following keys work if you turn off @code{org-goto-auto-isearch}} -n / p @r{Next/previous visible headline.} -f / b @r{Next/previous headline same level.} -u @r{One level up.} -0-9 @r{Digit argument.} -q @r{Quit} -@end example -@vindex org-goto-interface -@noindent -See also the variable @code{org-goto-interface}. -@end table - -@node Structure editing, Sparse trees, Motion, Document Structure -@section Structure editing -@cindex structure editing -@cindex headline, promotion and demotion -@cindex promotion, of subtrees -@cindex demotion, of subtrees -@cindex subtree, cut and paste -@cindex pasting, of subtrees -@cindex cutting, of subtrees -@cindex copying, of subtrees -@cindex sorting, of subtrees -@cindex subtrees, cut and paste - -@table @asis -@orgcmd{M-@key{RET},org-insert-heading} -@vindex org-M-RET-may-split-line -Insert new heading with same level as current. If the cursor is in a plain -list item, a new item is created (@pxref{Plain lists}). To force creation of -a new headline, use a prefix argument. When this command is used in the -middle of a line, the line is split and the rest of the line becomes the new -headline@footnote{If you do not want the line to be split, customize the -variable @code{org-M-RET-may-split-line}.}. If the command is used at the -beginning of a headline, the new headline is created before the current line. -If at the beginning of any other line, the content of that line is made the -new heading. If the command is used at the end of a folded subtree (i.e.@: -behind the ellipses at the end of a headline), then a headline like the -current one will be inserted after the end of the subtree. -@orgcmd{C-@key{RET},org-insert-heading-respect-content} -Just like @kbd{M-@key{RET}}, except when adding a new heading below the -current heading, the new heading is placed after the body instead of before -it. This command works from anywhere in the entry. -@orgcmd{M-S-@key{RET},org-insert-todo-heading} -@vindex org-treat-insert-todo-heading-as-state-change -Insert new TODO entry with same level as current heading. See also the -variable @code{org-treat-insert-todo-heading-as-state-change}. -@orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content} -Insert new TODO entry with same level as current heading. Like -@kbd{C-@key{RET}}, the new headline will be inserted after the current -subtree. -@orgcmd{@key{TAB},org-cycle} -In a new entry with no text yet, the first @key{TAB} demotes the entry to -become a child of the previous one. The next @key{TAB} makes it a parent, -and so on, all the way to top level. Yet another @key{TAB}, and you are back -to the initial level. -@orgcmd{M-@key{left},org-do-promote} -Promote current heading by one level. -@orgcmd{M-@key{right},org-do-demote} -Demote current heading by one level. -@orgcmd{M-S-@key{left},org-promote-subtree} -Promote the current subtree by one level. -@orgcmd{M-S-@key{right},org-demote-subtree} -Demote the current subtree by one level. -@orgcmd{M-S-@key{up},org-move-subtree-up} -Move subtree up (swap with previous subtree of same -level). -@orgcmd{M-S-@key{down},org-move-subtree-down} -Move subtree down (swap with next subtree of same level). -@orgcmd{C-c C-x C-w,org-cut-subtree} -Kill subtree, i.e.@: remove it from buffer but save in kill ring. -With a numeric prefix argument N, kill N sequential subtrees. -@orgcmd{C-c C-x M-w,org-copy-subtree} -Copy subtree to kill ring. With a numeric prefix argument N, copy the N -sequential subtrees. -@orgcmd{C-c C-x C-y,org-paste-subtree} -Yank subtree from kill ring. This does modify the level of the subtree to -make sure the tree fits in nicely at the yank position. The yank level can -also be specified with a numeric prefix argument, or by yanking after a -headline marker like @samp{****}. -@orgcmd{C-y,org-yank} -@vindex org-yank-adjusted-subtrees -@vindex org-yank-folded-subtrees -Depending on the variables @code{org-yank-adjusted-subtrees} and -@code{org-yank-folded-subtrees}, Org's internal @code{yank} command will -paste subtrees folded and in a clever way, using the same command as @kbd{C-c -C-x C-y}. With the default settings, no level adjustment will take place, -but the yanked tree will be folded unless doing so would swallow text -previously visible. Any prefix argument to this command will force a normal -@code{yank} to be executed, with the prefix passed along. A good way to -force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a -yank, it will yank previous kill items plainly, without adjustment and -folding. -@orgcmd{C-c C-x c,org-clone-subtree-with-time-shift} -Clone a subtree by making a number of sibling copies of it. You will be -prompted for the number of copies to make, and you can also specify if any -timestamps in the entry should be shifted. This can be useful, for example, -to create a number of tasks related to a series of lectures to prepare. For -more details, see the docstring of the command -@code{org-clone-subtree-with-time-shift}. -@orgcmd{C-c C-w,org-refile} -Refile entry or region to a different location. @xref{Refiling notes}. -@orgcmd{C-c ^,org-sort-entries-or-items} -Sort same-level entries. When there is an active region, all entries in the -region will be sorted. Otherwise the children of the current headline are -sorted. The command prompts for the sorting method, which can be -alphabetically, numerically, by time (first timestamp with active preferred, -creation time, scheduled time, deadline time), by priority, by TODO keyword -(in the sequence the keywords have been defined in the setup) or by the value -of a property. Reverse sorting is possible as well. You can also supply -your own function to extract the sorting key. With a @kbd{C-u} prefix, -sorting will be case-sensitive. -@orgcmd{C-x n s,org-narrow-to-subtree} -Narrow buffer to current subtree. -@orgcmd{C-x n b,org-narrow-to-block} -Narrow buffer to current block. -@orgcmd{C-x n w,widen} -Widen buffer to remove narrowing. -@orgcmd{C-c *,org-toggle-heading} -Turn a normal line or plain list item into a headline (so that it becomes a -subheading at its location). Also turn a headline into a normal line by -removing the stars. If there is an active region, turn all lines in the -region into headlines. If the first line in the region was an item, turn -only the item lines into headlines. Finally, if the first line is a -headline, remove the stars from all headlines in the region. -@end table - -@cindex region, active -@cindex active region -@cindex transient mark mode -When there is an active region (Transient Mark mode), promotion and -demotion work on all headlines in the region. To select a region of -headlines, it is best to place both point and mark at the beginning of a -line, mark at the beginning of the first headline, and point at the line -just after the last headline to change. Note that when the cursor is -inside a table (@pxref{Tables}), the Meta-Cursor keys have different -functionality. - - -@node Sparse trees, Plain lists, Structure editing, Document Structure -@section Sparse trees -@cindex sparse trees -@cindex trees, sparse -@cindex folding, sparse trees -@cindex occur, command - -@vindex org-show-hierarchy-above -@vindex org-show-following-heading -@vindex org-show-siblings -@vindex org-show-entry-below -An important feature of Org mode is the ability to construct @emph{sparse -trees} for selected information in an outline tree, so that the entire -document is folded as much as possible, but the selected information is made -visible along with the headline structure above it@footnote{See also the -variables @code{org-show-hierarchy-above}, @code{org-show-following-heading}, -@code{org-show-siblings}, and @code{org-show-entry-below} for detailed -control on how much context is shown around each match.}. Just try it out -and you will see immediately how it works. - -Org mode contains several commands creating such trees, all these -commands can be accessed through a dispatcher: - -@table @asis -@orgcmd{C-c /,org-sparse-tree} -This prompts for an extra key to select a sparse-tree creating command. -@orgcmd{C-c / r,org-occur} -@vindex org-remove-highlights-with-change -Prompts for a regexp and shows a sparse tree with all matches. If -the match is in a headline, the headline is made visible. If the match is in -the body of an entry, headline and body are made visible. In order to -provide minimal context, also the full hierarchy of headlines above the match -is shown, as well as the headline following the match. Each match is also -highlighted; the highlights disappear when the buffer is changed by an -editing command@footnote{This depends on the option -@code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}. -When called with a @kbd{C-u} prefix argument, previous highlights are kept, -so several calls to this command can be stacked. -@orgcmdkkc{M-g n,M-g M-n,next-error} -Jump to the next sparse tree match in this buffer. -@orgcmdkkc{M-g p,M-g M-p,previous-error} -Jump to the previous sparse tree match in this buffer. -@end table - - -@noindent -@vindex org-agenda-custom-commands -For frequently used sparse trees of specific search strings, you can -use the variable @code{org-agenda-custom-commands} to define fast -keyboard access to specific sparse trees. These commands will then be -accessible through the agenda dispatcher (@pxref{Agenda dispatcher}). -For example: - -@lisp -(setq org-agenda-custom-commands - '(("f" occur-tree "FIXME"))) -@end lisp - -@noindent will define the key @kbd{C-c a f} as a shortcut for creating -a sparse tree matching the string @samp{FIXME}. - -The other sparse tree commands select headings based on TODO keywords, -tags, or properties and will be discussed later in this manual. - -@kindex C-c C-e v -@cindex printing sparse trees -@cindex visible text, printing -To print a sparse tree, you can use the Emacs command -@code{ps-print-buffer-with-faces} which does not print invisible parts -of the document @footnote{This does not work under XEmacs, because -XEmacs uses selective display for outlining, not text properties.}. -Or you can use the command @kbd{C-c C-e v} to export only the visible -part of the document and print the resulting file. - -@node Plain lists, Drawers, Sparse trees, Document Structure -@section Plain lists -@cindex plain lists -@cindex lists, plain -@cindex lists, ordered -@cindex ordered lists - -Within an entry of the outline tree, hand-formatted lists can provide -additional structure. They also provide a way to create lists of checkboxes -(@pxref{Checkboxes}). Org supports editing such lists, and every exporter -(@pxref{Exporting}) can parse and format them. - -Org knows ordered lists, unordered lists, and description lists. -@itemize @bullet -@item -@emph{Unordered} list items start with @samp{-}, @samp{+}, or -@samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or -they will be seen as top-level headlines. Also, when you are hiding leading -stars to get a clean outline view, plain list items starting with a star may -be hard to distinguish from true headlines. In short: even though @samp{*} -is supported, it may be better to not use it for plain list items.} as -bullets. -@item -@vindex org-plain-list-ordered-item-terminator -@vindex org-alphabetical-lists -@emph{Ordered} list items start with a numeral followed by either a period or -a right parenthesis@footnote{You can filter out any of them by configuring -@code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or -@samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and -@samp{A)} by configuring @code{org-alphabetical-lists}. To minimize -confusion with normal text, those are limited to one character only. Beyond -that limit, bullets will automatically fallback to numbers.}. If you want a -list to start with a different value (e.g.@: 20), start the text of the item -with @code{[@@20]}@footnote{If there's a checkbox in the item, the cookie -must be put @emph{before} the checkbox. If you have activated alphabetical -lists, you can also use counters like @code{[@@b]}.}. Those constructs can -be used in any item of the list in order to enforce a particular numbering. -@item -@emph{Description} list items are unordered list items, and contain the -separator @samp{ :: } to distinguish the description @emph{term} from the -description. -@end itemize - -Items belonging to the same list must have the same indentation on the first -line. In particular, if an ordered list reaches number @samp{10.}, then the -2--digit numbers must be written left-aligned with the other numbers in the -list. An item ends before the next line that is less or equally indented -than its bullet/number. - -@vindex org-empty-line-terminates-plain-lists -A list ends whenever every item has ended, which means before any line less -or equally indented than items at top level. It also ends before two blank -lines@footnote{See also @code{org-empty-line-terminates-plain-lists}.}. In -that case, all items are closed. Here is an example: - -@example -@group -** Lord of the Rings - My favorite scenes are (in this order) - 1. The attack of the Rohirrim - 2. Eowyn's fight with the witch king - + this was already my favorite scene in the book - + I really like Miranda Otto. - 3. Peter Jackson being shot by Legolas - - on DVD only - He makes a really funny face when it happens. - But in the end, no individual scenes matter but the film as a whole. - Important actors in this film are: - - @b{Elijah Wood} :: He plays Frodo - - @b{Sean Austin} :: He plays Sam, Frodo's friend. I still remember - him very well from his role as Mikey Walsh in @i{The Goonies}. -@end group -@end example - -Org supports these lists by tuning filling and wrapping commands to deal with -them correctly@footnote{Org only changes the filling settings for Emacs. For -XEmacs, you should use Kyle E. Jones' @file{filladapt.el}. To turn this on, -put into @file{.emacs}: @code{(require 'filladapt)}}, and by exporting them -properly (@pxref{Exporting}). Since indentation is what governs the -structure of these lists, many structural constructs like @code{#+BEGIN_...} -blocks can be indented to signal that they belong to a particular item. - -@vindex org-list-demote-modify-bullet -@vindex org-list-indent-offset -If you find that using a different bullet for a sub-list (than that used for -the current list-level) improves readability, customize the variable -@code{org-list-demote-modify-bullet}. To get a greater difference of -indentation between items and theirs sub-items, customize -@code{org-list-indent-offset}. - -@vindex org-list-automatic-rules -The following commands act on items when the cursor is in the first line of -an item (the line with the bullet or number). Some of them imply the -application of automatic rules to keep list structure intact. If some of -these actions get in your way, configure @code{org-list-automatic-rules} -to disable them individually. - -@table @asis -@orgcmd{@key{TAB},org-cycle} -@cindex cycling, in plain lists -@vindex org-cycle-include-plain-lists -Items can be folded just like headline levels. Normally this works only if -the cursor is on a plain list item. For more details, see the variable -@code{org-cycle-include-plain-lists}. If this variable is set to -@code{integrate}, plain list items will be treated like low-level -headlines. The level of an item is then given by the indentation of the -bullet/number. Items are always subordinate to real headlines, however; the -hierarchies remain completely separated. In a new item with no text yet, the -first @key{TAB} demotes the item to become a child of the previous -one. Subsequent @key{TAB}s move the item to meaningful levels in the list -and eventually get it back to its initial position. -@orgcmd{M-@key{RET},org-insert-heading} -@vindex org-M-RET-may-split-line -@vindex org-list-automatic-rules -Insert new item at current level. With a prefix argument, force a new -heading (@pxref{Structure editing}). If this command is used in the middle -of an item, that item is @emph{split} in two, and the second part becomes the -new item@footnote{If you do not want the item to be split, customize the -variable @code{org-M-RET-may-split-line}.}. If this command is executed -@emph{before item's body}, the new item is created @emph{before} the current -one. -@end table - -@table @kbd -@kindex M-S-@key{RET} -@item M-S-RET -Insert a new item with a checkbox (@pxref{Checkboxes}). -@kindex S-@key{down} -@item S-up -@itemx S-down -@cindex shift-selection-mode -@vindex org-support-shift-select -@vindex org-list-use-circular-motion -Jump to the previous/next item in the current list@footnote{If you want to -cycle around items that way, you may customize -@code{org-list-use-circular-motion}.}, but only if -@code{org-support-shift-select} is off. If not, you can still use paragraph -jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite -similar effect. -@kindex M-@key{up} -@kindex M-@key{down} -@item M-up -@itemx M-down -Move the item including subitems up/down@footnote{See -@code{org-liste-use-circular-motion} for a cyclic behavior.} (swap with -previous/next item of same indentation). If the list is ordered, renumbering -is automatic. -@kindex M-@key{left} -@kindex M-@key{right} -@item M-left -@itemx M-right -Decrease/increase the indentation of an item, leaving children alone. -@kindex M-S-@key{left} -@kindex M-S-@key{right} -@item M-S-left -@itemx M-S-right -Decrease/increase the indentation of the item, including subitems. -Initially, the item tree is selected based on current indentation. When -these commands are executed several times in direct succession, the initially -selected region is used, even if the new indentation would imply a different -hierarchy. To use the new hierarchy, break the command chain with a cursor -motion or so. - -As a special case, using this command on the very first item of a list will -move the whole list. This behavior can be disabled by configuring -@code{org-list-automatic-rules}. The global indentation of a list has no -influence on the text @emph{after} the list. -@kindex C-c C-c -@item C-c C-c -If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the -state of the checkbox. In any case, verify bullets and indentation -consistency in the whole list. -@kindex C-c - -@vindex org-plain-list-ordered-item-terminator -@vindex org-list-automatic-rules -@item C-c - -Cycle the entire list level through the different itemize/enumerate bullets -(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them, -depending on @code{org-plain-list-ordered-item-terminator}, the type of list, -and its position@footnote{See @code{bullet} rule in -@code{org-list-automatic-rules} for more information.}. With a numeric -prefix argument N, select the Nth bullet from this list. If there is an -active region when calling this, selected text will be changed into an item. -With a prefix argument, all lines will be converted to list items. If the -first line already was a list item, any item marker will be removed from the -list. Finally, even without an active region, a normal line will be -converted into a list item. -@kindex C-c * -@item C-c * -Turn a plain list item into a headline (so that it becomes a subheading at -its location). @xref{Structure editing}, for a detailed explanation. -@kindex C-c C-* -@item C-c C-* -Turn the whole plain list into a subtree of the current heading. Checkboxes -(@pxref{Checkboxes}) will become TODO (resp. DONE) keywords when unchecked -(resp. checked). -@kindex S-@key{left} -@kindex S-@key{right} -@item S-left/right -@vindex org-support-shift-select -This command also cycles bullet styles when the cursor in on the bullet or -anywhere in an item line, details depending on -@code{org-support-shift-select}. -@kindex C-c ^ -@item C-c ^ -Sort the plain list. You will be prompted for the sorting method: -numerically, alphabetically, by time, or by custom function. -@end table - -@node Drawers, Blocks, Plain lists, Document Structure -@section Drawers -@cindex drawers -@cindex #+DRAWERS -@cindex visibility cycling, drawers - -@vindex org-drawers -Sometimes you want to keep information associated with an entry, but you -normally don't want to see it. For this, Org mode has @emph{drawers}. -Drawers need to be configured with the variable -@code{org-drawers}@footnote{You can define drawers on a per-file basis -with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers -look like this: - -@example -** This is a headline - Still outside the drawer - :DRAWERNAME: - This is inside the drawer. - :END: - After the drawer. -@end example - -Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and -show the entry, but keep the drawer collapsed to a single line. In order to -look inside the drawer, you need to move the cursor to the drawer line and -press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for -storing properties (@pxref{Properties and Columns}), and you can also arrange -for state change notes (@pxref{Tracking TODO state changes}) and clock times -(@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you -want to store a quick note in the LOGBOOK drawer, in a similar way to state changes, use - -@table @kbd -@kindex C-c C-z -@item C-c C-z -Add a time-stamped note to the LOGBOOK drawer. -@end table - -@node Blocks, Footnotes, Drawers, Document Structure -@section Blocks - -@vindex org-hide-block-startup -@cindex blocks, folding -Org mode uses begin...end blocks for various purposes from including source -code examples (@pxref{Literal examples}) to capturing time logging -information (@pxref{Clocking work time}). These blocks can be folded and -unfolded by pressing TAB in the begin line. You can also get all blocks -folded at startup by configuring the variable @code{org-hide-block-startup} -or on a per-file basis by using - -@cindex @code{hideblocks}, STARTUP keyword -@cindex @code{nohideblocks}, STARTUP keyword -@example -#+STARTUP: hideblocks -#+STARTUP: nohideblocks -@end example - -@node Footnotes, Orgstruct mode, Blocks, Document Structure -@section Footnotes -@cindex footnotes - -Org mode supports the creation of footnotes. In contrast to the -@file{footnote.el} package, Org mode's footnotes are designed for work on a -larger document, not only for one-off documents like emails. The basic -syntax is similar to the one used by @file{footnote.el}, i.e.@: a footnote is -defined in a paragraph that is started by a footnote marker in square -brackets in column 0, no indentation allowed. If you need a paragraph break -inside a footnote, use the @LaTeX{} idiom @samp{\par}. The footnote reference -is simply the marker in square brackets, inside text. For example: - -@example -The Org homepage[fn:1] now looks a lot better than it used to. -... -[fn:1] The link is: http://orgmode.org -@end example - -Org mode extends the number-based syntax to @emph{named} footnotes and -optional inline definition. Using plain numbers as markers (as -@file{footnote.el} does) is supported for backward compatibility, but not -encouraged because of possible conflicts with @LaTeX{} snippets (@pxref{Embedded -@LaTeX{}}). Here are the valid references: - -@table @code -@item [1] -A plain numeric footnote marker. Compatible with @file{footnote.el}, but not -recommended because something like @samp{[1]} could easily be part of a code -snippet. -@item [fn:name] -A named footnote reference, where @code{name} is a unique label word, or, for -simplicity of automatic creation, a number. -@item [fn:: This is the inline definition of this footnote] -A @LaTeX{}-like anonymous footnote where the definition is given directly at the -reference point. -@item [fn:name: a definition] -An inline definition of a footnote, which also specifies a name for the note. -Since Org allows multiple references to the same note, you can then use -@code{[fn:name]} to create additional references. -@end table - -@vindex org-footnote-auto-label -Footnote labels can be created automatically, or you can create names yourself. -This is handled by the variable @code{org-footnote-auto-label} and its -corresponding @code{#+STARTUP} keywords. See the docstring of that variable -for details. - -@noindent The following command handles footnotes: - -@table @kbd -@kindex C-c C-x f -@item C-c C-x f -The footnote action command. - -When the cursor is on a footnote reference, jump to the definition. When it -is at a definition, jump to the (first) reference. - -@vindex org-footnote-define-inline -@vindex org-footnote-section -@vindex org-footnote-auto-adjust -Otherwise, create a new footnote. Depending on the variable -@code{org-footnote-define-inline}@footnote{The corresponding in-buffer -setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the -definition will be placed right into the text as part of the reference, or -separately into the location determined by the variable -@code{org-footnote-section}. - -When this command is called with a prefix argument, a menu of additional -options is offered: -@example -s @r{Sort the footnote definitions by reference sequence. During editing,} - @r{Org makes no effort to sort footnote definitions into a particular} - @r{sequence. If you want them sorted, use this command, which will} - @r{also move entries according to @code{org-footnote-section}. Automatic} - @r{sorting after each insertion/deletion can be configured using the} - @r{variable @code{org-footnote-auto-adjust}.} -r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering} - @r{after each insertion/deletion can be configured using the variable} - @r{@code{org-footnote-auto-adjust}.} -S @r{Short for first @code{r}, then @code{s} action.} -n @r{Normalize the footnotes by collecting all definitions (including} - @r{inline definitions) into a special section, and then numbering them} - @r{in sequence. The references will then also be numbers. This is} - @r{meant to be the final step before finishing a document (e.g.@: sending} - @r{off an email). The exporters do this automatically, and so could} - @r{something like @code{message-send-hook}.} -d @r{Delete the footnote at point, and all definitions of and references} - @r{to it.} -@end example -Depending on the variable @code{org-footnote-auto-adjust}@footnote{the -corresponding in-buffer options are @code{fnadjust} and @code{nofnadjust}.}, -renumbering and sorting footnotes can be automatic after each insertion or -deletion. - -@kindex C-c C-c -@item C-c C-c -If the cursor is on a footnote reference, jump to the definition. If it is a -the definition, jump back to the reference. When called at a footnote -location with a prefix argument, offer the same menu as @kbd{C-c C-x f}. -@kindex C-c C-o -@kindex mouse-1 -@kindex mouse-2 -@item C-c C-o @r{or} mouse-1/2 -Footnote labels are also links to the corresponding definition/reference, and -you can use the usual commands to follow these links. -@end table - -@node Orgstruct mode, , Footnotes, Document Structure -@section The Orgstruct minor mode -@cindex Orgstruct mode -@cindex minor mode for structure editing - -If you like the intuitive way the Org mode structure editing and list -formatting works, you might want to use these commands in other modes like -Text mode or Mail mode as well. The minor mode @code{orgstruct-mode} makes -this possible. Toggle the mode with @kbd{M-x orgstruct-mode}, or -turn it on by default, for example in Message mode, with one of: - -@lisp -(add-hook 'message-mode-hook 'turn-on-orgstruct) -(add-hook 'message-mode-hook 'turn-on-orgstruct++) -@end lisp - -When this mode is active and the cursor is on a line that looks to Org like a -headline or the first line of a list item, most structure editing commands -will work, even if the same keys normally have different functionality in the -major mode you are using. If the cursor is not in one of those special -lines, Orgstruct mode lurks silently in the shadows. When you use -@code{orgstruct++-mode}, Org will also export indentation and autofill -settings into that mode, and detect item context after the first line of an -item. - -@node Tables, Hyperlinks, Document Structure, Top -@chapter Tables -@cindex tables -@cindex editing tables - -Org comes with a fast and intuitive table editor. Spreadsheet-like -calculations are supported using the Emacs @file{calc} package -(@pxref{Top, Calc, , calc, Gnu Emacs Calculator Manual}). - -@menu -* Built-in table editor:: Simple tables -* Column width and alignment:: Overrule the automatic settings -* Column groups:: Grouping to trigger vertical lines -* Orgtbl mode:: The table editor as minor mode -* The spreadsheet:: The table editor has spreadsheet capabilities -* Org-Plot:: Plotting from org tables -@end menu - -@node Built-in table editor, Column width and alignment, Tables, Tables -@section The built-in table editor -@cindex table editor, built-in - -Org makes it easy to format tables in plain ASCII. Any line with @samp{|} as -the first non-whitespace character is considered part of a table. @samp{|} -is also the column separator@footnote{To insert a vertical bar into a table -field, use @code{\vert} or, inside a word @code{abc\vert@{@}def}.}. A table -might look like this: - -@example -| Name | Phone | Age | -|-------+-------+-----| -| Peter | 1234 | 17 | -| Anna | 4321 | 25 | -@end example - -A table is re-aligned automatically each time you press @key{TAB} or -@key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to -the next field (@key{RET} to the next row) and creates new table rows -at the end of the table or before horizontal lines. The indentation -of the table is set by the first line. Any line starting with -@samp{|-} is considered as a horizontal separator line and will be -expanded on the next re-align to span the whole table width. So, to -create the above table, you would only type - -@example -|Name|Phone|Age| -|- -@end example - -@noindent and then press @key{TAB} to align the table and start filling in -fields. Even faster would be to type @code{|Name|Phone|Age} followed by -@kbd{C-c @key{RET}}. - -@vindex org-enable-table-editor -@vindex org-table-auto-blank-field -When typing text into a field, Org treats @key{DEL}, -@key{Backspace}, and all character keys in a special way, so that -inserting and deleting avoids shifting other fields. Also, when -typing @emph{immediately after the cursor was moved into a new field -with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the -field is automatically made blank. If this behavior is too -unpredictable for you, configure the variables -@code{org-enable-table-editor} and @code{org-table-auto-blank-field}. - -@table @kbd -@tsubheading{Creation and conversion} -@orgcmd{C-c |,org-table-create-or-convert-from-region} -Convert the active region to table. If every line contains at least one -TAB character, the function assumes that the material is tab separated. -If every line contains a comma, comma-separated values (CSV) are assumed. -If not, lines are split at whitespace into fields. You can use a prefix -argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u -C-u} forces TAB, and a numeric argument N indicates that at least N -consecutive spaces, or alternatively a TAB will be the separator. -@* -If there is no active region, this command creates an empty Org -table. But it is easier just to start typing, like -@kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}. - -@tsubheading{Re-aligning and field motion} -@orgcmd{C-c C-c,org-table-align} -Re-align the table without moving the cursor. -@c -@orgcmd{,org-table-next-field} -Re-align the table, move to the next field. Creates a new row if -necessary. -@c -@orgcmd{S-@key{TAB},org-table-previous-field} -Re-align, move to previous field. -@c -@orgcmd{@key{RET},org-table-next-row} -Re-align the table and move down to next row. Creates a new row if -necessary. At the beginning or end of a line, @key{RET} still does -NEWLINE, so it can be used to split a table. -@c -@orgcmd{M-a,org-table-beginning-of-field} -Move to beginning of the current table field, or on to the previous field. -@orgcmd{M-e,org-table-end-of-field} -Move to end of the current table field, or on to the next field. - -@tsubheading{Column and row editing} -@orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right} -Move the current column left/right. -@c -@orgcmd{M-S-@key{left},org-table-delete-column} -Kill the current column. -@c -@orgcmd{M-S-@key{right},org-table-insert-column} -Insert a new column to the left of the cursor position. -@c -@orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down} -Move the current row up/down. -@c -@orgcmd{M-S-@key{up},org-table-kill-row} -Kill the current row or horizontal line. -@c -@orgcmd{M-S-@key{down},org-table-insert-row} -Insert a new row above the current row. With a prefix argument, the line is -created below the current one. -@c -@orgcmd{C-c -,org-table-insert-hline} -Insert a horizontal line below current row. With a prefix argument, the line -is created above the current line. -@c -@orgcmd{C-c @key{RET},org-table-hline-and-move} -Insert a horizontal line below current row, and move the cursor into the row -below that line. -@c -@orgcmd{C-c ^,org-table-sort-lines} -Sort the table lines in the region. The position of point indicates the -column to be used for sorting, and the range of lines is the range -between the nearest horizontal separator lines, or the entire table. If -point is before the first column, you will be prompted for the sorting -column. If there is an active region, the mark specifies the first line -and the sorting column, while point should be in the last line to be -included into the sorting. The command prompts for the sorting type -(alphabetically, numerically, or by time). When called with a prefix -argument, alphabetic sorting will be case-sensitive. - -@tsubheading{Regions} -@orgcmd{C-c C-x M-w,org-table-copy-region} -Copy a rectangular region from a table to a special clipboard. Point and -mark determine edge fields of the rectangle. If there is no active region, -copy just the current field. The process ignores horizontal separator lines. -@c -@orgcmd{C-c C-x C-w,org-table-cut-region} -Copy a rectangular region from a table to a special clipboard, and -blank all fields in the rectangle. So this is the ``cut'' operation. -@c -@orgcmd{C-c C-x C-y,org-table-paste-rectangle} -Paste a rectangular region into a table. -The upper left corner ends up in the current field. All involved fields -will be overwritten. If the rectangle does not fit into the present table, -the table is enlarged as needed. The process ignores horizontal separator -lines. -@c -@orgcmd{M-@key{RET},org-table-wrap-region} -Split the current field at the cursor position and move the rest to the line -below. If there is an active region, and both point and mark are in the same -column, the text in the column is wrapped to minimum width for the given -number of lines. A numeric prefix argument may be used to change the number -of desired lines. If there is no region, but you specify a prefix argument, -the current field is made blank, and the content is appended to the field -above. - -@tsubheading{Calculations} -@cindex formula, in tables -@cindex calculations, in tables -@cindex region, active -@cindex active region -@cindex transient mark mode -@orgcmd{C-c +,org-table-sum} -Sum the numbers in the current column, or in the rectangle defined by -the active region. The result is shown in the echo area and can -be inserted with @kbd{C-y}. -@c -@orgcmd{S-@key{RET},org-table-copy-down} -@vindex org-table-copy-increment -When current field is empty, copy from first non-empty field above. When not -empty, copy current field down to next row and move cursor along with it. -Depending on the variable @code{org-table-copy-increment}, integer field -values will be incremented during copy. Integers that are too large will not -be incremented. Also, a @code{0} prefix argument temporarily disables the -increment. This key is also used by shift-selection and related modes -(@pxref{Conflicts}). - -@tsubheading{Miscellaneous} -@orgcmd{C-c `,org-table-edit-field} -Edit the current field in a separate window. This is useful for fields that -are not fully visible (@pxref{Column width and alignment}). When called with -a @kbd{C-u} prefix, just make the full field visible, so that it can be -edited in place. When called with two @kbd{C-u} prefixes, make the editor -window follow the cursor through the table and always show the current -field. The follow mode exits automatically when the cursor leaves the table, -or when you repeat this command with @kbd{C-u C-u C-c `}. -@c -@item M-x org-table-import -Import a file as a table. The table should be TAB or whitespace -separated. Use, for example, to import a spreadsheet table or data -from a database, because these programs generally can write -TAB-separated text files. This command works by inserting the file into -the buffer and then converting the region to a table. Any prefix -argument is passed on to the converter, which uses it to determine the -separator. -@orgcmd{C-c |,org-table-create-or-convert-from-region} -Tables can also be imported by pasting tabular text into the Org -buffer, selecting the pasted text with @kbd{C-x C-x} and then using the -@kbd{C-c |} command (see above under @i{Creation and conversion}). -@c -@item M-x org-table-export -@findex org-table-export -@vindex org-table-export-default-format -Export the table, by default as a TAB-separated file. Use for data -exchange with, for example, spreadsheet or database programs. The format -used to export the file can be configured in the variable -@code{org-table-export-default-format}. You may also use properties -@code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file -name and the format for table export in a subtree. Org supports quite -general formats for exported tables. The exporter format is the same as the -format used by Orgtbl radio tables, see @ref{Translator functions}, for a -detailed description. -@end table - -If you don't like the automatic table editor because it gets in your -way on lines which you would like to start with @samp{|}, you can turn -it off with - -@lisp -(setq org-enable-table-editor nil) -@end lisp - -@noindent Then the only table command that still works is -@kbd{C-c C-c} to do a manual re-align. - -@node Column width and alignment, Column groups, Built-in table editor, Tables -@section Column width and alignment -@cindex narrow columns in tables -@cindex alignment in tables - -The width of columns is automatically determined by the table editor. And -also the alignment of a column is determined automatically from the fraction -of number-like versus non-number fields in the column. - -Sometimes a single field or a few fields need to carry more text, leading to -inconveniently wide columns. Or maybe you want to make a table with several -columns having a fixed width, regardless of content. To set@footnote{This -feature does not work on XEmacs.} the width of a column, one field anywhere -in the column may contain just the string @samp{} where @samp{N} is an -integer specifying the width of the column in characters. The next re-align -will then set the width of this column to this value. - -@example -@group -|---+------------------------------| |---+--------| -| | | | | <6> | -| 1 | one | | 1 | one | -| 2 | two | ----\ | 2 | two | -| 3 | This is a long chunk of text | ----/ | 3 | This=> | -| 4 | four | | 4 | four | -|---+------------------------------| |---+--------| -@end group -@end example - -@noindent -Fields that are wider become clipped and end in the string @samp{=>}. -Note that the full text is still in the buffer but is hidden. -To see the full text, hold the mouse over the field---a tool-tip window -will show the full content. To edit such a field, use the command -@kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This will -open a new window with the full field. Edit it and finish with @kbd{C-c -C-c}. - -@vindex org-startup-align-all-tables -When visiting a file containing a table with narrowed columns, the -necessary character hiding has not yet happened, and the table needs to -be aligned before it looks nice. Setting the option -@code{org-startup-align-all-tables} will realign all tables in a file -upon visiting, but also slow down startup. You can also set this option -on a per-file basis with: - -@example -#+STARTUP: align -#+STARTUP: noalign -@end example - -If you would like to overrule the automatic alignment of number-rich columns -to the right and of string-rich column to the left, you can use @samp{}, -@samp{c}@footnote{Centering does not work inside Emacs, but it does have an -effect when exporting to HTML.} or @samp{} in a similar fashion. You may -also combine alignment and field width like this: @samp{}. - -Lines which only contain these formatting cookies will be removed -automatically when exporting the document. - -@node Column groups, Orgtbl mode, Column width and alignment, Tables -@section Column groups -@cindex grouping columns in tables - -When Org exports tables, it does so by default without vertical -lines because that is visually more satisfying in general. Occasionally -however, vertical lines can be useful to structure a table into groups -of columns, much like horizontal lines can do for groups of rows. In -order to specify column groups, you can use a special row where the -first field contains only @samp{/}. The further fields can either -contain @samp{<} to indicate that this column should start a group, -@samp{>} to indicate the end of a column, or @samp{<>} (no space between @samp{<} -and @samp{>}) to make a column -a group of its own. Boundaries between column groups will upon export be -marked with vertical lines. Here is an example: - -@example -| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | -|---+-----+-----+-----+---------+------------| -| / | < | | > | < | > | -| 1 | 1 | 1 | 1 | 1 | 1 | -| 2 | 4 | 8 | 16 | 1.4142 | 1.1892 | -| 3 | 9 | 27 | 81 | 1.7321 | 1.3161 | -|---+-----+-----+-----+---------+------------| -#+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1))) -@end example - -It is also sufficient to just insert the column group starters after -every vertical line you would like to have: - -@example -| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | -|----+-----+-----+-----+---------+------------| -| / | < | | | < | | -@end example - -@node Orgtbl mode, The spreadsheet, Column groups, Tables -@section The Orgtbl minor mode -@cindex Orgtbl mode -@cindex minor mode for tables - -If you like the intuitive way the Org table editor works, you -might also want to use it in other modes like Text mode or Mail mode. -The minor mode Orgtbl mode makes this possible. You can always toggle -the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for -example in Message mode, use - -@lisp -(add-hook 'message-mode-hook 'turn-on-orgtbl) -@end lisp - -Furthermore, with some special setup, it is possible to maintain tables -in arbitrary syntax with Orgtbl mode. For example, it is possible to -construct @LaTeX{} tables with the underlying ease and power of -Orgtbl mode, including spreadsheet capabilities. For details, see -@ref{Tables in arbitrary syntax}. - -@node The spreadsheet, Org-Plot, Orgtbl mode, Tables -@section The spreadsheet -@cindex calculations, in tables -@cindex spreadsheet capabilities -@cindex @file{calc} package - -The table editor makes use of the Emacs @file{calc} package to implement -spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to -derive fields from other fields. While fully featured, Org's implementation -is not identical to other spreadsheets. For example, Org knows the concept -of a @emph{column formula} that will be applied to all non-header fields in a -column without having to copy the formula to each relevant field. There is -also a formula debugger, and a formula editor with features for highlighting -fields in the table corresponding to the references at the point in the -formula, moving these references by arrow keys - -@menu -* References:: How to refer to another field or range -* Formula syntax for Calc:: Using Calc to compute stuff -* Formula syntax for Lisp:: Writing formulas in Emacs Lisp -* Durations and time values:: How to compute durations and time values -* Field and range formulas:: Formula for specific (ranges of) fields -* Column formulas:: Formulas valid for an entire column -* Editing and debugging formulas:: Fixing formulas -* Updating the table:: Recomputing all dependent fields -* Advanced features:: Field and column names, parameters and automatic recalc -@end menu - -@node References, Formula syntax for Calc, The spreadsheet, The spreadsheet -@subsection References -@cindex references - -To compute fields in the table from other fields, formulas must -reference other fields or ranges. In Org, fields can be referenced -by name, by absolute coordinates, and by relative coordinates. To find -out what the coordinates of a field are, press @kbd{C-c ?} in that -field, or press @kbd{C-c @}} to toggle the display of a grid. - -@subsubheading Field references -@cindex field references -@cindex references, to fields - -Formulas can reference the value of another field in two ways. Like in -any other spreadsheet, you may reference fields with a letter/number -combination like @code{B3}, meaning the 2nd field in the 3rd row. -@vindex org-table-use-standard-references -However, Org prefers@footnote{Org will understand references typed by the -user as @samp{B4}, but it will not use this syntax when offering a formula -for editing. You can customize this behavior using the variable -@code{org-table-use-standard-references}.} to use another, more general -representation that looks like this: -@example -@@@var{row}$@var{column} -@end example - -Column specifications can be absolute like @code{$1}, -@code{$2},...@code{$@var{N}}, or relative to the current column (i.e.@: the -column of the field which is being computed) like @code{$+1} or @code{$-2}. -@code{$<} and @code{$>} are immutable references to the first and last -column, respectively, and you can use @code{$>>>} to indicate the third -column from the right. - -The row specification only counts data lines and ignores horizontal separator -lines (hlines). Like with columns, you can use absolute row numbers -@code{@@1}, @code{@@2},...@code{@@@var{N}}, and row numbers relative to the -current row like @code{@@+3} or @code{@@-1}. @code{@@<} and @code{@@>} are -immutable references the first and last@footnote{For backward compatibility -you can also use special names like @code{$LR5} and @code{$LR12} to refer in -a stable way to the 5th and 12th field in the last row of the table. -However, this syntax is deprecated, it should not be used for new documents. -Use @code{@@>$} instead.} row in the table, respectively. You may also -specify the row relative to one of the hlines: @code{@@I} refers to the first -hline, @code{@@II} to the second, etc@. @code{@@-I} refers to the first such -line above the current line, @code{@@+I} to the first such line below the -current line. You can also write @code{@@III+2} which is the second data line -after the third hline in the table. - -@code{@@0} and @code{$0} refer to the current row and column, respectively, -i.e. to the row/column for the field being computed. Also, if you omit -either the column or the row part of the reference, the current row/column is -implied. - -Org's references with @emph{unsigned} numbers are fixed references -in the sense that if you use the same reference in the formula for two -different fields, the same field will be referenced each time. -Org's references with @emph{signed} numbers are floating -references because the same reference operator can reference different -fields depending on the field being calculated by the formula. - -Here are a few examples: - -@example -@@2$3 @r{2nd row, 3rd column (same as @code{C2})} -$5 @r{column 5 in the current row (same as @code{E&})} -@@2 @r{current column, row 2} -@@-1$-3 @r{the field one row up, three columns to the left} -@@-I$2 @r{field just under hline above current row, column 2} -@@>$5 @r{field in the last row, in column 5} -@end example - -@subsubheading Range references -@cindex range references -@cindex references, to ranges - -You may reference a rectangular range of fields by specifying two field -references connected by two dots @samp{..}. If both fields are in the -current row, you may simply use @samp{$2..$7}, but if at least one field -is in a different row, you need to use the general @code{@@row$column} -format at least for the first field (i.e the reference must start with -@samp{@@} in order to be interpreted correctly). Examples: - -@example -$1..$3 @r{first three fields in the current row} -$P..$Q @r{range, using column names (see under Advanced)} -$<<<..$>> @r{start in third column, continue to the one but last} -@@2$1..@@4$3 @r{6 fields between these two fields (same as @code{A2..C4})} -@@-1$-2..@@-1 @r{3 numbers from the column to the left, 2 up to current row} -@@I..II @r{between first and second hline, short for @code{@@I..@@II}} -@end example - -@noindent Range references return a vector of values that can be fed -into Calc vector functions. Empty fields in ranges are normally -suppressed, so that the vector contains only the non-empty fields (but -see the @samp{E} mode switch below). If there are no non-empty fields, -@samp{[0]} is returned to avoid syntax errors in formulas. - -@subsubheading Field coordinates in formulas -@cindex field coordinates -@cindex coordinates, of field -@cindex row, of field coordinates -@cindex column, of field coordinates - -For Calc formulas and Lisp formulas @code{@@#} and @code{$#} can be used to -get the row or column number of the field where the formula result goes. -The traditional Lisp formula equivalents are @code{org-table-current-dline} -and @code{org-table-current-column}. Examples: - -@example -if(@@# % 2, $#, string("")) @r{column number on odd lines only} -$3 = remote(FOO, @@@@#$2) @r{copy column 2 from table FOO into} - @r{column 3 of the current table} -@end example - -@noindent For the second example, table FOO must have at least as many rows -as the current table. Note that this is inefficient@footnote{The computation time scales as -O(N^2) because table FOO is parsed for each field to be copied.} for large -number of rows. - -@subsubheading Named references -@cindex named references -@cindex references, named -@cindex name, of column or field -@cindex constants, in calculations -@cindex #+CONSTANTS - -@vindex org-table-formula-constants -@samp{$name} is interpreted as the name of a column, parameter or -constant. Constants are defined globally through the variable -@code{org-table-formula-constants}, and locally (for the file) through a -line like - -@example -#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6 -@end example - -@noindent -@vindex constants-unit-system -@pindex constants.el -Also properties (@pxref{Properties and Columns}) can be used as -constants in table formulas: for a property @samp{:Xyz:} use the name -@samp{$PROP_Xyz}, and the property will be searched in the current -outline entry and in the hierarchy above it. If you have the -@file{constants.el} package, it will also be used to resolve constants, -including natural constants like @samp{$h} for Planck's constant, and -units like @samp{$km} for kilometers@footnote{@file{constants.el} can -supply the values of constants in two different unit systems, @code{SI} -and @code{cgs}. Which one is used depends on the value of the variable -@code{constants-unit-system}. You can use the @code{#+STARTUP} options -@code{constSI} and @code{constcgs} to set this value for the current -buffer.}. Column names and parameters can be specified in special table -lines. These are described below, see @ref{Advanced features}. All -names must start with a letter, and further consist of letters and -numbers. - -@subsubheading Remote references -@cindex remote references -@cindex references, remote -@cindex references, to a different table -@cindex name, of column or field -@cindex constants, in calculations -@cindex #+TBLNAME - -You may also reference constants, fields and ranges from a different table, -either in the current file or even in a different file. The syntax is - -@example -remote(NAME-OR-ID,REF) -@end example - -@noindent -where NAME can be the name of a table in the current file as set by a -@code{#+TBLNAME: NAME} line before the table. It can also be the ID of an -entry, even in a different file, and the reference then refers to the first -table in that entry. REF is an absolute field or range reference as -described above for example @code{@@3$3} or @code{$somename}, valid in the -referenced table. - -@node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet -@subsection Formula syntax for Calc -@cindex formula syntax, Calc -@cindex syntax, of formulas - -A formula can be any algebraic expression understood by the Emacs -@file{Calc} package. @b{Note that @file{calc} has the -non-standard convention that @samp{/} has lower precedence than -@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Before -evaluation by @code{calc-eval} (@pxref{Calling Calc from -Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc, GNU -Emacs Calc Manual}), -variable substitution takes place according to the rules described above. -@cindex vectors, in table calculations -The range vectors can be directly fed into the Calc vector functions -like @samp{vmean} and @samp{vsum}. - -@cindex format specifier -@cindex mode, for @file{calc} -@vindex org-calc-default-modes -A formula can contain an optional mode string after a semicolon. This -string consists of flags to influence Calc and other modes during -execution. By default, Org uses the standard Calc modes (precision -12, angular units degrees, fraction and symbolic modes off). The display -format, however, has been changed to @code{(float 8)} to keep tables -compact. The default settings can be configured using the variable -@code{org-calc-default-modes}. - -@example -p20 @r{set the internal Calc calculation precision to 20 digits} -n3 s3 e2 f4 @r{Normal, scientific, engineering, or fixed} - @r{format of the result of Calc passed back to Org.} - @r{Calc formatting is unlimited in precision as} - @r{long as the Calc calculation precision is greater.} -D R @r{angle modes: degrees, radians} -F S @r{fraction and symbolic modes} -N @r{interpret all fields as numbers, use 0 for non-numbers} -E @r{keep empty fields in ranges} -L @r{literal} -@end example - -@noindent -Unless you use large integer numbers or high-precision-calculation -and -display for floating point numbers you may alternatively provide a -@code{printf} format specifier to reformat the Calc result after it has been -passed back to Org instead of letting Calc already do the -formatting@footnote{The @code{printf} reformatting is limited in precision -because the value passed to it is converted into an @code{integer} or -@code{double}. The @code{integer} is limited in size by truncating the -signed value to 32 bits. The @code{double} is limited in precision to 64 -bits overall which leaves approximately 16 significant decimal digits.}. -A few examples: - -@example -$1+$2 @r{Sum of first and second field} -$1+$2;%.2f @r{Same, format result to two decimals} -exp($2)+exp($1) @r{Math functions can be used} -$0;%.1f @r{Reformat current cell to 1 decimal} -($3-32)*5/9 @r{Degrees F -> C conversion} -$c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}} -tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1} -sin($1);Dp3%.1e @r{Same, but use printf specifier for display} -vmean($2..$7) @r{Compute column range mean, using vector function} -vmean($2..$7);EN @r{Same, but treat empty fields as 0} -taylor($3,x=7,2) @r{Taylor series of $3, at x=7, second degree} -@end example - -Calc also contains a complete set of logical operations. For example - -@example -if($1<20,teen,string("")) @r{"teen" if age $1 less than 20, else empty} -@end example - -Note that you can also use two org-specific flags @code{T} and @code{t} for -durations computations @ref{Durations and time values}. - -@node Formula syntax for Lisp, Durations and time values, Formula syntax for Calc, The spreadsheet -@subsection Emacs Lisp forms as formulas -@cindex Lisp forms, as table formulas - -It is also possible to write a formula in Emacs Lisp; this can be useful for -string manipulation and control structures, if Calc's functionality is not -enough. If a formula starts with a single-quote followed by an opening -parenthesis, then it is evaluated as a Lisp form. The evaluation should -return either a string or a number. Just as with @file{calc} formulas, you -can specify modes and a printf format after a semicolon. With Emacs Lisp -forms, you need to be conscious about the way field references are -interpolated into the form. By default, a reference will be interpolated as -a Lisp string (in double-quotes) containing the field. If you provide the -@samp{N} mode switch, all referenced elements will be numbers (non-number -fields will be zero) and interpolated as Lisp numbers, without quotes. If -you provide the @samp{L} flag, all fields will be interpolated literally, -without quotes. I.e., if you want a reference to be interpreted as a string -by the Lisp form, enclose the reference operator itself in double-quotes, -like @code{"$3"}. Ranges are inserted as space-separated fields, so you can -embed them in list or vector syntax. Here are a few examples---note how the -@samp{N} mode is used when we do computations in Lisp: - -@example -@r{Swap the first two characters of the content of column 1} - '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2)) -@r{Add columns 1 and 2, equivalent to Calc's @code{$1+$2}} - '(+ $1 $2);N -@r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}} - '(apply '+ '($1..$4));N -@end example - -@node Durations and time values, Field and range formulas, Formula syntax for Lisp, The spreadsheet -@subsection Durations and time values -@cindex Duration, computing -@cindex Time, computing -@vindex org-table-duration-custom-format - -If you want to compute time values use the @code{T} flag, either in Calc -formulas or Elisp formulas: - -@example -@group - | Task 1 | Task 2 | Total | - |---------+----------+----------| - | 2:12 | 1:47 | 03:59:00 | - | 3:02:20 | -2:07:00 | 0.92 | - #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;t -@end group -@end example - -Input duration values must be of the form @code{[HH:MM[:SS]}, where seconds -are optional. With the @code{T} flag, computed durations will be displayed -as @code{HH:MM:SS} (see the first formula above). With the @code{t} flag, -computed durations will be displayed according to the value of the variable -@code{org-table-duration-custom-format}, which defaults to @code{'hours} and -will display the result as a fraction of hours (see the second formula in the -example above). - -Negative duration values can be manipulated as well, and integers will be -considered as seconds in addition and subtraction. - -@node Field and range formulas, Column formulas, Durations and time values, The spreadsheet -@subsection Field and range formulas -@cindex field formula -@cindex range formula -@cindex formula, for individual table field -@cindex formula, for range of fields - -To assign a formula to a particular field, type it directly into the field, -preceded by @samp{:=}, for example @samp{:=vsum(@@II..III)}. When you press -@key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field, -the formula will be stored as the formula for this field, evaluated, and the -current field will be replaced with the result. - -@cindex #+TBLFM -Formulas are stored in a special line starting with @samp{#+TBLFM:} directly -below the table. If you type the equation in the 4th field of the 3rd data -line in the table, the formula will look like @samp{@@3$4=$1+$2}. When -inserting/deleting/swapping column and rows with the appropriate commands, -@i{absolute references} (but not relative ones) in stored formulas are -modified in order to still reference the same field. To avoid this from -happening, in particular in range references, anchor ranges at the table -borders (using @code{@@<}, @code{@@>}, @code{$<}, @code{$>}), or at hlines -using the @code{@@I} notation. Automatic adaptation of field references does -of cause not happen if you edit the table structure with normal editing -commands---then you must fix the equations yourself. - -Instead of typing an equation into the field, you may also use the following -command - -@table @kbd -@orgcmd{C-u C-c =,org-table-eval-formula} -Install a new formula for the current field. The command prompts for a -formula with default taken from the @samp{#+TBLFM:} line, applies -it to the current field, and stores it. -@end table - -The left-hand side of a formula can also be a special expression in order to -assign the formula to a number of different fields. There is no keyboard -shortcut to enter such range formulas. To add them, use the formula editor -(@pxref{Editing and debugging formulas}) or edit the @code{#+TBLFM:} line -directly. - -@table @code -@item $2= -Column formula, valid for the entire column. This is so common that Org -treats these formulas in a special way, see @ref{Column formulas}. -@item @@3= -Row formula, applies to all fields in the specified row. @code{@@>=} means -the last row. -@item @@1$2..@@4$3= -Range formula, applies to all fields in the given rectangular range. This -can also be used to assign a formula to some but not all fields in a row. -@item $name= -Named field, see @ref{Advanced features}. -@end table - -@node Column formulas, Editing and debugging formulas, Field and range formulas, The spreadsheet -@subsection Column formulas -@cindex column formula -@cindex formula, for table column - -When you assign a formula to a simple column reference like @code{$3=}, the -same formula will be used in all fields of that column, with the following -very convenient exceptions: (i) If the table contains horizontal separator -hlines, everything before the first such line is considered part of the table -@emph{header} and will not be modified by column formulas. (ii) Fields that -already get a value from a field/range formula will be left alone by column -formulas. These conditions make column formulas very easy to use. - -To assign a formula to a column, type it directly into any field in the -column, preceded by an equal sign, like @samp{=$1+$2}. When you press -@key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field, -the formula will be stored as the formula for the current column, evaluated -and the current field replaced with the result. If the field contains only -@samp{=}, the previously stored formula for this column is used. For each -column, Org will only remember the most recently used formula. In the -@samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The -left-hand side of a column formula can not be the name of column, it must be -the numeric column reference or @code{$>}. - -Instead of typing an equation into the field, you may also use the -following command: - -@table @kbd -@orgcmd{C-c =,org-table-eval-formula} -Install a new formula for the current column and replace current field with -the result of the formula. The command prompts for a formula, with default -taken from the @samp{#+TBLFM} line, applies it to the current field and -stores it. With a numeric prefix argument(e.g.@: @kbd{C-5 C-c =}) the command -will apply it to that many consecutive fields in the current column. -@end table - -@node Editing and debugging formulas, Updating the table, Column formulas, The spreadsheet -@subsection Editing and debugging formulas -@cindex formula editing -@cindex editing, of table formulas - -@vindex org-table-use-standard-references -You can edit individual formulas in the minibuffer or directly in the -field. Org can also prepare a special buffer with all active -formulas of a table. When offering a formula for editing, Org -converts references to the standard format (like @code{B3} or @code{D&}) -if possible. If you prefer to only work with the internal format (like -@code{@@3$2} or @code{$4}), configure the variable -@code{org-table-use-standard-references}. - -@table @kbd -@orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula} -Edit the formula associated with the current column/field in the -minibuffer. See @ref{Column formulas}, and @ref{Field and range formulas}. -@orgcmd{C-u C-u C-c =,org-table-eval-formula} -Re-insert the active formula (either a -field formula, or a column formula) into the current field, so that you -can edit it directly in the field. The advantage over editing in the -minibuffer is that you can use the command @kbd{C-c ?}. -@orgcmd{C-c ?,org-table-field-info} -While editing a formula in a table field, highlight the field(s) -referenced by the reference at the cursor position in the formula. -@kindex C-c @} -@findex org-table-toggle-coordinate-overlays -@item C-c @} -Toggle the display of row and column numbers for a table, using overlays -(@command{org-table-toggle-coordinate-overlays}). These are updated each -time the table is aligned; you can force it with @kbd{C-c C-c}. -@kindex C-c @{ -@findex org-table-toggle-formula-debugger -@item C-c @{ -Toggle the formula debugger on and off -(@command{org-table-toggle-formula-debugger}). See below. -@orgcmd{C-c ',org-table-edit-formulas} -Edit all formulas for the current table in a special buffer, where the -formulas will be displayed one per line. If the current field has an -active formula, the cursor in the formula editor will mark it. -While inside the special buffer, Org will automatically highlight -any field or range reference at the cursor position. You may edit, -remove and add formulas, and use the following commands: -@table @kbd -@orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish} -Exit the formula editor and store the modified formulas. With @kbd{C-u} -prefix, also apply the new formulas to the entire table. -@orgcmd{C-c C-q,org-table-fedit-abort} -Exit the formula editor without installing changes. -@orgcmd{C-c C-r,org-table-fedit-toggle-ref-type} -Toggle all references in the formula editor between standard (like -@code{B3}) and internal (like @code{@@3$2}). -@orgcmd{@key{TAB},org-table-fedit-lisp-indent} -Pretty-print or indent Lisp formula at point. When in a line containing -a Lisp formula, format the formula according to Emacs Lisp rules. -Another @key{TAB} collapses the formula back again. In the open -formula, @key{TAB} re-indents just like in Emacs Lisp mode. -@orgcmd{M-@key{TAB},lisp-complete-symbol} -Complete Lisp symbols, just like in Emacs Lisp mode. -@kindex S-@key{up} -@kindex S-@key{down} -@kindex S-@key{left} -@kindex S-@key{right} -@findex org-table-fedit-ref-up -@findex org-table-fedit-ref-down -@findex org-table-fedit-ref-left -@findex org-table-fedit-ref-right -@item S-@key{up}/@key{down}/@key{left}/@key{right} -Shift the reference at point. For example, if the reference is -@code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}. -This also works for relative references and for hline references. -@orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down} -Move the test line for column formulas in the Org buffer up and -down. -@orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up} -Scroll the window displaying the table. -@kindex C-c @} -@findex org-table-toggle-coordinate-overlays -@item C-c @} -Turn the coordinate grid in the table on and off. -@end table -@end table - -Making a table field blank does not remove the formula associated with -the field, because that is stored in a different line (the @samp{#+TBLFM} -line)---during the next recalculation the field will be filled again. -To remove a formula from a field, you have to give an empty reply when -prompted for the formula, or to edit the @samp{#+TBLFM} line. - -@kindex C-c C-c -You may edit the @samp{#+TBLFM} directly and re-apply the changed -equations with @kbd{C-c C-c} in that line or with the normal -recalculation commands in the table. - -@subsubheading Debugging formulas -@cindex formula debugging -@cindex debugging, of table formulas -When the evaluation of a formula leads to an error, the field content -becomes the string @samp{#ERROR}. If you would like see what is going -on during variable substitution and calculation in order to find a bug, -turn on formula debugging in the @code{Tbl} menu and repeat the -calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a -field. Detailed information will be displayed. - -@node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet -@subsection Updating the table -@cindex recomputing table fields -@cindex updating, table - -Recalculation of a table is normally not automatic, but needs to be -triggered by a command. See @ref{Advanced features}, for a way to make -recalculation at least semi-automatic. - -In order to recalculate a line of a table or the entire table, use the -following commands: - -@table @kbd -@orgcmd{C-c *,org-table-recalculate} -Recalculate the current row by first applying the stored column formulas -from left to right, and all field/range formulas in the current row. -@c -@kindex C-u C-c * -@item C-u C-c * -@kindex C-u C-c C-c -@itemx C-u C-c C-c -Recompute the entire table, line by line. Any lines before the first -hline are left alone, assuming that these are part of the table header. -@c -@orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate} -Iterate the table by recomputing it until no further changes occur. -This may be necessary if some computed fields use the value of other -fields that are computed @i{later} in the calculation sequence. -@item M-x org-table-recalculate-buffer-tables -@findex org-table-recalculate-buffer-tables -Recompute all tables in the current buffer. -@item M-x org-table-iterate-buffer-tables -@findex org-table-iterate-buffer-tables -Iterate all tables in the current buffer, in order to converge table-to-table -dependencies. -@end table - -@node Advanced features, , Updating the table, The spreadsheet -@subsection Advanced features - -If you want the recalculation of fields to happen automatically, or if you -want to be able to assign @i{names}@footnote{Such names must start by an -alphabetic character and use only alphanumeric/underscore characters.} to -fields and columns, you need to reserve the first column of the table for -special marking characters. - -@table @kbd -@orgcmd{C-#,org-table-rotate-recalc-marks} -Rotate the calculation mark in first column through the states @samp{ }, -@samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region, -change all marks in the region. -@end table - -Here is an example of a table that collects exam results of students and -makes use of these features: - -@example -@group -|---+---------+--------+--------+--------+-------+------| -| | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note | -|---+---------+--------+--------+--------+-------+------| -| ! | | P1 | P2 | P3 | Tot | | -| # | Maximum | 10 | 15 | 25 | 50 | 10.0 | -| ^ | | m1 | m2 | m3 | mt | | -|---+---------+--------+--------+--------+-------+------| -| # | Peter | 10 | 8 | 23 | 41 | 8.2 | -| # | Sam | 2 | 4 | 3 | 9 | 1.8 | -|---+---------+--------+--------+--------+-------+------| -| | Average | | | | 29.7 | | -| ^ | | | | | at | | -| $ | max=50 | | | | | | -|---+---------+--------+--------+--------+-------+------| -#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f -@end group -@end example - -@noindent @b{Important}: please note that for these special tables, -recalculating the table with @kbd{C-u C-c *} will only affect rows that -are marked @samp{#} or @samp{*}, and fields that have a formula assigned -to the field itself. The column formulas are not applied in rows with -empty first field. - -@cindex marking characters, tables -The marking characters have the following meaning: -@table @samp -@item ! -The fields in this line define names for the columns, so that you may -refer to a column as @samp{$Tot} instead of @samp{$6}. -@item ^ -This row defines names for the fields @emph{above} the row. With such -a definition, any formula in the table may use @samp{$m1} to refer to -the value @samp{10}. Also, if you assign a formula to a names field, it -will be stored as @samp{$name=...}. -@item _ -Similar to @samp{^}, but defines names for the fields in the row -@emph{below}. -@item $ -Fields in this row can define @emph{parameters} for formulas. For -example, if a field in a @samp{$} row contains @samp{max=50}, then -formulas in this table can refer to the value 50 using @samp{$max}. -Parameters work exactly like constants, only that they can be defined on -a per-table basis. -@item # -Fields in this row are automatically recalculated when pressing -@key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row -is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked -lines will be left alone by this command. -@item * -Selects this line for global recalculation with @kbd{C-u C-c *}, but -not for automatic recalculation. Use this when automatic -recalculation slows down editing too much. -@item -Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}. -All lines that should be recalculated should be marked with @samp{#} -or @samp{*}. -@item / -Do not export this line. Useful for lines that contain the narrowing -@samp{} markers or column group markers. -@end table - -Finally, just to whet your appetite for what can be done with the -fantastic @file{calc.el} package, here is a table that computes the Taylor -series of degree @code{n} at location @code{x} for a couple of -functions. - -@example -@group -|---+-------------+---+-----+--------------------------------------| -| | Func | n | x | Result | -|---+-------------+---+-----+--------------------------------------| -| # | exp(x) | 1 | x | 1 + x | -| # | exp(x) | 2 | x | 1 + x + x^2 / 2 | -| # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 | -| # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 | -| # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 | -| * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 | -|---+-------------+---+-----+--------------------------------------| -#+TBLFM: $5=taylor($2,$4,$3);n3 -@end group -@end example - -@node Org-Plot, , The spreadsheet, Tables -@section Org-Plot -@cindex graph, in tables -@cindex plot tables using Gnuplot -@cindex #+PLOT - -Org-Plot can produce 2D and 3D graphs of information stored in org tables -using @file{Gnuplot} @uref{http://www.gnuplot.info/} and @file{gnuplot-mode} -@uref{http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html}. To see -this in action, ensure that you have both Gnuplot and Gnuplot mode installed -on your system, then call @code{org-plot/gnuplot} on the following table. - -@example -@group -#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]" -| Sede | Max cites | H-index | -|-----------+-----------+---------| -| Chile | 257.72 | 21.39 | -| Leeds | 165.77 | 19.68 | -| Sao Paolo | 71.00 | 11.50 | -| Stockholm | 134.19 | 14.33 | -| Morelia | 257.56 | 17.67 | -@end group -@end example - -Notice that Org Plot is smart enough to apply the table's headers as labels. -Further control over the labels, type, content, and appearance of plots can -be exercised through the @code{#+PLOT:} lines preceding a table. See below -for a complete list of Org-plot options. For more information and examples -see the Org-plot tutorial at -@uref{http://orgmode.org/worg/org-tutorials/org-plot.html}. - -@subsubheading Plot Options - -@table @code -@item set -Specify any @command{gnuplot} option to be set when graphing. - -@item title -Specify the title of the plot. - -@item ind -Specify which column of the table to use as the @code{x} axis. - -@item deps -Specify the columns to graph as a Lisp style list, surrounded by parentheses -and separated by spaces for example @code{dep:(3 4)} to graph the third and -fourth columns (defaults to graphing all other columns aside from the @code{ind} -column). - -@item type -Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}. - -@item with -Specify a @code{with} option to be inserted for every col being plotted -(e.g.@: @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...). -Defaults to @code{lines}. - -@item file -If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}. - -@item labels -List of labels to be used for the @code{deps} (defaults to the column headers -if they exist). - -@item line -Specify an entire line to be inserted in the Gnuplot script. - -@item map -When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a -flat mapping rather than a @code{3d} slope. - -@item timefmt -Specify format of Org mode timestamps as they will be parsed by Gnuplot. -Defaults to @samp{%Y-%m-%d-%H:%M:%S}. - -@item script -If you want total control, you can specify a script file (place the file name -between double-quotes) which will be used to plot. Before plotting, every -instance of @code{$datafile} in the specified script will be replaced with -the path to the generated data file. Note: even if you set this option, you -may still want to specify the plot type, as that can impact the content of -the data file. -@end table - -@node Hyperlinks, TODO Items, Tables, Top -@chapter Hyperlinks -@cindex hyperlinks - -Like HTML, Org provides links inside a file, external links to -other files, Usenet articles, emails, and much more. - -@menu -* Link format:: How links in Org are formatted -* Internal links:: Links to other places in the current file -* External links:: URL-like links to the world -* Handling links:: Creating, inserting and following -* Using links outside Org:: Linking from my C source code? -* Link abbreviations:: Shortcuts for writing complex links -* Search options:: Linking to a specific location -* Custom searches:: When the default search is not enough -@end menu - -@node Link format, Internal links, Hyperlinks, Hyperlinks -@section Link format -@cindex link format -@cindex format, of links - -Org will recognize plain URL-like links and activate them as -clickable links. The general link format, however, looks like this: - -@example -[[link][description]] @r{or alternatively} [[link]] -@end example - -@noindent -Once a link in the buffer is complete (all brackets present), Org -will change the display so that @samp{description} is displayed instead -of @samp{[[link][description]]} and @samp{link} is displayed instead of -@samp{[[link]]}. Links will be highlighted in the face @code{org-link}, -which by default is an underlined face. You can directly edit the -visible part of a link. Note that this can be either the @samp{link} -part (if there is no description) or the @samp{description} part. To -edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the -cursor on the link. - -If you place the cursor at the beginning or just behind the end of the -displayed text and press @key{BACKSPACE}, you will remove the -(invisible) bracket at that location. This makes the link incomplete -and the internals are again displayed as plain text. Inserting the -missing bracket hides the link internals again. To show the -internal structure of all links, use the menu entry -@code{Org->Hyperlinks->Literal links}. - -@node Internal links, External links, Link format, Hyperlinks -@section Internal links -@cindex internal links -@cindex links, internal -@cindex targets, for links - -@cindex property, CUSTOM_ID -If the link does not look like a URL, it is considered to be internal in the -current file. The most important case is a link like -@samp{[[#my-custom-id]]} which will link to the entry with the -@code{CUSTOM_ID} property @samp{my-custom-id}. Such custom IDs are very good -for HTML export (@pxref{HTML export}) where they produce pretty section -links. You are responsible yourself to make sure these custom IDs are unique -in a file. - -Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]} -lead to a text search in the current file. - -The link can be followed with @kbd{C-c C-o} when the cursor is on the link, -or with a mouse click (@pxref{Handling links}). Links to custom IDs will -point to the corresponding headline. The preferred match for a text link is -a @i{dedicated target}: the same string in double angular brackets. Targets -may be located anywhere; sometimes it is convenient to put them into a -comment line. For example - -@example -# <> -@end example - -@noindent In HTML export (@pxref{HTML export}), such targets will become -named anchors for direct access through @samp{http} links@footnote{Note that -text before the first headline is usually not exported, so the first such -target should be after the first headline, or in the line directly before the -first headline.}. - -If no dedicated target exists, Org will search for a headline that is exactly -the link text but may also include a TODO keyword and tags@footnote{To insert -a link targeting a headline, in-buffer completion can be used. Just type a -star followed by a few optional letters into the buffer and press -@kbd{M-@key{TAB}}. All headlines in the current buffer will be offered as -completions.}. In non-Org files, the search will look for the words in the -link text. In the above example the search would be for @samp{my target}. - -Following a link pushes a mark onto Org's own mark ring. You can -return to the previous position with @kbd{C-c &}. Using this command -several times in direct succession goes back to positions recorded -earlier. - -@menu -* Radio targets:: Make targets trigger links in plain text -@end menu - -@node Radio targets, , Internal links, Internal links -@subsection Radio targets -@cindex radio targets -@cindex targets, radio -@cindex links, radio targets - -Org can automatically turn any occurrences of certain target names -in normal text into a link. So without explicitly creating a link, the -text connects to the target radioing its position. Radio targets are -enclosed by triple angular brackets. For example, a target @samp{<<>>} causes each occurrence of @samp{my target} in normal text to -become activated as a link. The Org file is scanned automatically -for radio targets only when the file is first loaded into Emacs. To -update the target list during editing, press @kbd{C-c C-c} with the -cursor on or at a target. - -@node External links, Handling links, Internal links, Hyperlinks -@section External links -@cindex links, external -@cindex external links -@cindex links, external -@cindex Gnus links -@cindex BBDB links -@cindex IRC links -@cindex URL links -@cindex file links -@cindex VM links -@cindex RMAIL links -@cindex WANDERLUST links -@cindex MH-E links -@cindex USENET links -@cindex SHELL links -@cindex Info links -@cindex Elisp links - -Org supports links to files, websites, Usenet and email messages, -BBDB database entries and links to both IRC conversations and their -logs. External links are URL-like locators. They start with a short -identifying string followed by a colon. There can be no space after -the colon. The following list shows examples for each link type. - -@example -http://www.astro.uva.nl/~dominik @r{on the web} -doi:10.1000/182 @r{DOI for an electronic resource} -file:/home/dominik/images/jupiter.jpg @r{file, absolute path} -/home/dominik/images/jupiter.jpg @r{same as above} -file:papers/last.pdf @r{file, relative path} -./papers/last.pdf @r{same as above} -file:/myself@@some.where:papers/last.pdf @r{file, path on remote machine} -/myself@@some.where:papers/last.pdf @r{same as above} -file:sometextfile::NNN @r{file, jump to line number} -file:projects.org @r{another Org file} -file:projects.org::some words @r{text search in Org file}@footnote{ -The actual behavior of the search will depend on the value of -the variable @code{org-link-search-must-match-exact-headline}. If its value -is nil, then a fuzzy text search will be done. If it is t, then only the -exact headline will be matched. If the value is @code{'query-to-create}, -then an exact headline will be searched; if it is not found, then the user -will be queried to create it.} -file:projects.org::*task title @r{heading search in Org file} -file+sys:/path/to/file @r{open via OS, like double-click} -file+emacs:/path/to/file @r{force opening by Emacs} -docview:papers/last.pdf::NNN @r{open in doc-view mode at page} -id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID} -news:comp.emacs @r{Usenet link} -mailto:adent@@galaxy.net @r{Mail link} -vm:folder @r{VM folder link} -vm:folder#id @r{VM message link} -vm://myself@@some.where.org/folder#id @r{VM on remote machine} -wl:folder @r{WANDERLUST folder link} -wl:folder#id @r{WANDERLUST message link} -mhe:folder @r{MH-E folder link} -mhe:folder#id @r{MH-E message link} -rmail:folder @r{RMAIL folder link} -rmail:folder#id @r{RMAIL message link} -gnus:group @r{Gnus group link} -gnus:group#id @r{Gnus article link} -bbdb:R.*Stallman @r{BBDB link (with regexp)} -irc:/irc.com/#emacs/bob @r{IRC link} -info:org#External links @r{Info node link} -shell:ls *.org @r{A shell command} -elisp:org-agenda @r{Interactive Elisp command} -elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate} -@end example - -For customizing Org to add new link types @ref{Adding hyperlink types}. - -A link should be enclosed in double brackets and may contain a -descriptive text to be displayed instead of the URL (@pxref{Link -format}), for example: - -@example -[[http://www.gnu.org/software/emacs/][GNU Emacs]] -@end example - -@noindent -If the description is a file name or URL that points to an image, HTML -export (@pxref{HTML export}) will inline the image as a clickable -button. If there is no description at all and the link points to an -image, -that image will be inlined into the exported HTML file. - -@cindex square brackets, around links -@cindex plain text external links -Org also finds external links in the normal text and activates them -as links. If spaces must be part of the link (for example in -@samp{bbdb:Richard Stallman}), or if you need to remove ambiguities -about the end of the link, enclose them in square brackets. - -@node Handling links, Using links outside Org, External links, Hyperlinks -@section Handling links -@cindex links, handling - -Org provides methods to create a link in the correct syntax, to -insert it into an Org file, and to follow the link. - -@table @kbd -@orgcmd{C-c l,org-store-link} -@cindex storing links -Store a link to the current location. This is a @emph{global} command (you -must create the key binding yourself) which can be used in any buffer to -create a link. The link will be stored for later insertion into an Org -buffer (see below). What kind of link will be created depends on the current -buffer: - -@b{Org mode buffers}@* -For Org files, if there is a @samp{<>} at the cursor, the link points -to the target. Otherwise it points to the current headline, which will also -be the description@footnote{If the headline contains a timestamp, it will be -removed from the link and result in a wrong link -- you should avoid putting -timestamp in the headline.}. - -@vindex org-link-to-org-use-id -@cindex property, CUSTOM_ID -@cindex property, ID -If the headline has a @code{CUSTOM_ID} property, a link to this custom ID -will be stored. In addition or alternatively (depending on the value of -@code{org-link-to-org-use-id}), a globally unique @code{ID} property will be -created and/or used to construct a link. So using this command in Org -buffers will potentially create two links: a human-readable from the custom -ID, and one that is globally unique and works even if the entry is moved from -file to file. Later, when inserting the link, you need to decide which one -to use. - -@b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@* -Pretty much all Emacs mail clients are supported. The link will point to the -current article, or, in some GNUS buffers, to the group. The description is -constructed from the author and the subject. - -@b{Web browsers: W3 and W3M}@* -Here the link will be the current URL, with the page title as description. - -@b{Contacts: BBDB}@* -Links created in a BBDB buffer will point to the current entry. - -@b{Chat: IRC}@* -@vindex org-irc-link-to-logs -For IRC links, if you set the variable @code{org-irc-link-to-logs} to -@code{t}, a @samp{file:/} style link to the relevant point in the logs for -the current conversation is created. Otherwise an @samp{irc:/} style link to -the user/channel/server under the point will be stored. - -@b{Other files}@* -For any other files, the link will point to the file, with a search string -(@pxref{Search options}) pointing to the contents of the current line. If -there is an active region, the selected words will form the basis of the -search string. If the automatically created link is not working correctly or -accurately enough, you can write custom functions to select the search string -and to do the search for particular file types---see @ref{Custom searches}. -The key binding @kbd{C-c l} is only a suggestion---see @ref{Installation}. - -@b{Agenda view}@* -When the cursor is in an agenda view, the created link points to the -entry referenced by the current line. - -@c -@orgcmd{C-c C-l,org-insert-link} -@cindex link completion -@cindex completion, of links -@cindex inserting links -@vindex org-keep-stored-link-after-insertion -Insert a link@footnote{ Note that you don't have to use this command to -insert a link. Links in Org are plain text, and you can type or paste them -straight into the buffer. By using this command, the links are automatically -enclosed in double brackets, and you will be asked for the optional -descriptive text.}. This prompts for a link to be inserted into the buffer. -You can just type a link, using text for an internal link, or one of the link -type prefixes mentioned in the examples above. The link will be inserted -into the buffer@footnote{After insertion of a stored link, the link will be -removed from the list of stored links. To keep it in the list later use, use -a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option -@code{org-keep-stored-link-after-insertion}.}, along with a descriptive text. -If some text was selected when this command is called, the selected text -becomes the default description. - -@b{Inserting stored links}@* -All links stored during the -current session are part of the history for this prompt, so you can access -them with @key{up} and @key{down} (or @kbd{M-p/n}). - -@b{Completion support}@* Completion with @key{TAB} will help you to insert -valid link prefixes like @samp{http:} or @samp{ftp:}, including the prefixes -defined through link abbreviations (@pxref{Link abbreviations}). If you -press @key{RET} after inserting only the @var{prefix}, Org will offer -specific completion support for some link types@footnote{This works by -calling a special function @code{org-PREFIX-complete-link}.} For -example, if you type @kbd{file @key{RET}}, file name completion (alternative -access: @kbd{C-u C-c C-l}, see below) will be offered, and after @kbd{bbdb -@key{RET}} you can complete contact names. -@orgkey C-u C-c C-l -@cindex file name completion -@cindex completion, of file names -When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to -a file will be inserted and you may use file name completion to select -the name of the file. The path to the file is inserted relative to the -directory of the current Org file, if the linked file is in the current -directory or in a sub-directory of it, or if the path is written relative -to the current directory using @samp{../}. Otherwise an absolute path -is used, if possible with @samp{~/} for your home directory. You can -force an absolute path with two @kbd{C-u} prefixes. -@c -@item C-c C-l @ @r{(with cursor on existing link)} -When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the -link and description parts of the link. -@c -@cindex following links -@orgcmd{C-c C-o,org-open-at-point} -@vindex org-file-apps -@vindex org-link-frame-setup -Open link at point. This will launch a web browser for URLs (using -@command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for -the corresponding links, and execute the command in a shell link. When the -cursor is on an internal link, this command runs the corresponding search. -When the cursor is on a TAG list in a headline, it creates the corresponding -TAGS view. If the cursor is on a timestamp, it compiles the agenda for that -date. Furthermore, it will visit text and remote files in @samp{file:} links -with Emacs and select a suitable application for local non-text files. -Classification of files is based on file extension only. See option -@code{org-file-apps}. If you want to override the default application and -visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid -opening in Emacs, use a @kbd{C-u C-u} prefix.@* -If the cursor is on a headline, but not on a link, offer all links in the -headline and entry text. If you want to setup the frame configuration for -following links, customize @code{org-link-frame-setup}. - -@orgkey @key{RET} -@vindex org-return-follows-link -When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow -the link at point. -@c -@kindex mouse-2 -@kindex mouse-1 -@item mouse-2 -@itemx mouse-1 -On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o} -would. Under Emacs 22 and later, @kbd{mouse-1} will also follow a link. -@c -@kindex mouse-3 -@item mouse-3 -@vindex org-display-internal-link-with-indirect-buffer -Like @kbd{mouse-2}, but force file links to be opened with Emacs, and -internal links to be displayed in another window@footnote{See the -variable @code{org-display-internal-link-with-indirect-buffer}}. -@c -@orgcmd{C-c C-x C-v,org-toggle-inline-images} -@cindex inlining images -@cindex images, inlining -@vindex org-startup-with-inline-images -@cindex @code{inlineimages}, STARTUP keyword -@cindex @code{noinlineimages}, STARTUP keyword -Toggle the inline display of linked images. Normally this will only inline -images that have no description part in the link, i.e.@: images that will also -be inlined during export. When called with a prefix argument, also display -images that do have a link description. You can ask for inline images to be -displayed at startup by configuring the variable -@code{org-startup-with-inline-images}@footnote{with corresponding -@code{#+STARTUP} keywords @code{inlineimages} and @code{inlineimages}}. -@orgcmd{C-c %,org-mark-ring-push} -@cindex mark ring -Push the current position onto the mark ring, to be able to return -easily. Commands following an internal link do this automatically. -@c -@orgcmd{C-c &,org-mark-ring-goto} -@cindex links, returning to -Jump back to a recorded position. A position is recorded by the -commands following internal links, and by @kbd{C-c %}. Using this -command several times in direct succession moves through a ring of -previously recorded positions. -@c -@orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link} -@cindex links, finding next/previous -Move forward/backward to the next link in the buffer. At the limit of -the buffer, the search fails once, and then wraps around. The key -bindings for this are really too long; you might want to bind this also -to @kbd{C-n} and @kbd{C-p} -@lisp -(add-hook 'org-load-hook - (lambda () - (define-key org-mode-map "\C-n" 'org-next-link) - (define-key org-mode-map "\C-p" 'org-previous-link))) -@end lisp -@end table - -@node Using links outside Org, Link abbreviations, Handling links, Hyperlinks -@section Using links outside Org - -You can insert and follow links that have Org syntax not only in -Org, but in any Emacs buffer. For this, you should create two -global commands, like this (please select suitable global keys -yourself): - -@lisp -(global-set-key "\C-c L" 'org-insert-link-global) -(global-set-key "\C-c o" 'org-open-at-point-global) -@end lisp - -@node Link abbreviations, Search options, Using links outside Org, Hyperlinks -@section Link abbreviations -@cindex link abbreviations -@cindex abbreviation, links - -Long URLs can be cumbersome to type, and often many similar links are -needed in a document. For this you can use link abbreviations. An -abbreviated link looks like this - -@example -[[linkword:tag][description]] -@end example - -@noindent -@vindex org-link-abbrev-alist -where the tag is optional. -The @i{linkword} must be a word, starting with a letter, followed by -letters, numbers, @samp{-}, and @samp{_}. Abbreviations are resolved -according to the information in the variable @code{org-link-abbrev-alist} -that relates the linkwords to replacement text. Here is an example: - -@smalllisp -@group -(setq org-link-abbrev-alist - '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") - ("google" . "http://www.google.com/search?q=") - ("gmap" . "http://maps.google.com/maps?q=%s") - ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1") - ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST"))) -@end group -@end smalllisp - -If the replacement text contains the string @samp{%s}, it will be -replaced with the tag. Otherwise the tag will be appended to the string -in order to create the link. You may also specify a function that will -be called with the tag as the only argument to create the link. - -With the above setting, you could link to a specific bug with -@code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with -@code{[[google:OrgMode]]}, show the map location of the Free Software -Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office -@code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out -what the Org author is doing besides Emacs hacking with -@code{[[ads:Dominik,C]]}. - -If you need special abbreviations just for a single Org buffer, you -can define them in the file with - -@cindex #+LINK -@example -#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id= -#+LINK: google http://www.google.com/search?q=%s -@end example - -@noindent -In-buffer completion (@pxref{Completion}) can be used after @samp{[} to -complete link abbreviations. You may also define a function -@code{org-PREFIX-complete-link} that implements special (e.g.@: completion) -support for inserting such a link with @kbd{C-c C-l}. Such a function should -not accept any arguments, and return the full link with prefix. - -@node Search options, Custom searches, Link abbreviations, Hyperlinks -@section Search options in file links -@cindex search option in file links -@cindex file links, searching - -File links can contain additional information to make Emacs jump to a -particular location in the file when following a link. This can be a -line number or a search option after a double@footnote{For backward -compatibility, line numbers can also follow a single colon.} colon. For -example, when the command @kbd{C-c l} creates a link (@pxref{Handling -links}) to a file, it encodes the words in the current line as a search -string that can be used to find this line back later when following the -link with @kbd{C-c C-o}. - -Here is the syntax of the different ways to attach a search to a file -link, together with an explanation: - -@example -[[file:~/code/main.c::255]] -[[file:~/xx.org::My Target]] -[[file:~/xx.org::*My Target]] -[[file:~/xx.org::#my-custom-id]] -[[file:~/xx.org::/regexp/]] -@end example - -@table @code -@item 255 -Jump to line 255. -@item My Target -Search for a link target @samp{<>}, or do a text search for -@samp{my target}, similar to the search in internal links, see -@ref{Internal links}. In HTML export (@pxref{HTML export}), such a file -link will become an HTML reference to the corresponding named anchor in -the linked file. -@item *My Target -In an Org file, restrict search to headlines. -@item #my-custom-id -Link to a heading with a @code{CUSTOM_ID} property -@item /regexp/ -Do a regular expression search for @code{regexp}. This uses the Emacs -command @code{occur} to list all matches in a separate window. If the -target file is in Org mode, @code{org-occur} is used to create a -sparse tree with the matches. -@c If the target file is a directory, -@c @code{grep} will be used to search all files in the directory. -@end table - -As a degenerate case, a file link with an empty file name can be used -to search the current file. For example, @code{[[file:::find me]]} does -a search for @samp{find me} in the current file, just as -@samp{[[find me]]} would. - -@node Custom searches, , Search options, Hyperlinks -@section Custom Searches -@cindex custom search strings -@cindex search strings, custom - -The default mechanism for creating search strings and for doing the -actual search related to a file link may not work correctly in all -cases. For example, Bib@TeX{} database files have many entries like -@samp{year="1993"} which would not result in good search strings, -because the only unique identification for a Bib@TeX{} entry is the -citation key. - -@vindex org-create-file-search-functions -@vindex org-execute-file-search-functions -If you come across such a problem, you can write custom functions to set -the right search string for a particular file type, and to do the search -for the string in the file. Using @code{add-hook}, these functions need -to be added to the hook variables -@code{org-create-file-search-functions} and -@code{org-execute-file-search-functions}. See the docstring for these -variables for more information. Org actually uses this mechanism -for Bib@TeX{} database files, and you can use the corresponding code as -an implementation example. See the file @file{org-bibtex.el}. - -@node TODO Items, Tags, Hyperlinks, Top -@chapter TODO items -@cindex TODO items - -Org mode does not maintain TODO lists as separate documents@footnote{Of -course, you can make a document that contains only long lists of TODO items, -but this is not required.}. Instead, TODO items are an integral part of the -notes file, because TODO items usually come up while taking notes! With Org -mode, simply mark any entry in a tree as being a TODO item. In this way, -information is not duplicated, and the entire context from which the TODO -item emerged is always present. - -Of course, this technique for managing TODO items scatters them -throughout your notes file. Org mode compensates for this by providing -methods to give you an overview of all the things that you have to do. - -@menu -* TODO basics:: Marking and displaying TODO entries -* TODO extensions:: Workflow and assignments -* Progress logging:: Dates and notes for progress -* Priorities:: Some things are more important than others -* Breaking down tasks:: Splitting a task into manageable pieces -* Checkboxes:: Tick-off lists -@end menu - -@node TODO basics, TODO extensions, TODO Items, TODO Items -@section Basic TODO functionality - -Any headline becomes a TODO item when it starts with the word -@samp{TODO}, for example: - -@example -*** TODO Write letter to Sam Fortune -@end example - -@noindent -The most important commands to work with TODO entries are: - -@table @kbd -@orgcmd{C-c C-t,org-todo} -@cindex cycling, of TODO states -Rotate the TODO state of the current item among - -@example -,-> (unmarked) -> TODO -> DONE --. -'--------------------------------' -@end example - -The same rotation can also be done ``remotely'' from the timeline and -agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). - -@orgkey{C-u C-c C-t} -Select a specific keyword using completion or (if it has been set up) -the fast selection interface. For the latter, you need to assign keys -to TODO states, see @ref{Per-file keywords}, and @ref{Setting tags}, for -more information. - -@kindex S-@key{right} -@kindex S-@key{left} -@item S-@key{right} @ @r{/} @ S-@key{left} -@vindex org-treat-S-cursor-todo-selection-as-state-change -Select the following/preceding TODO state, similar to cycling. Useful -mostly if more than two TODO states are possible (@pxref{TODO -extensions}). See also @ref{Conflicts}, for a discussion of the interaction -with @code{shift-selection-mode}. See also the variable -@code{org-treat-S-cursor-todo-selection-as-state-change}. -@orgcmd{C-c / t,org-show-todo-key} -@cindex sparse tree, for TODO -@vindex org-todo-keywords -View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the -entire buffer, but shows all TODO items (with not-DONE state) and the -headings hierarchy above them. With a prefix argument (or by using @kbd{C-c -/ T}), search for a specific TODO. You will be prompted for the keyword, and -you can also give a list of keywords like @code{KWD1|KWD2|...} to list -entries that match any one of these keywords. With a numeric prefix argument -N, show the tree for the Nth keyword in the variable -@code{org-todo-keywords}. With two prefix arguments, find all TODO states, -both un-done and done. -@orgcmd{C-c a t,org-todo-list} -Show the global TODO list. Collects the TODO items (with not-DONE states) -from all agenda files (@pxref{Agenda Views}) into a single buffer. The new -buffer will be in @code{agenda-mode}, which provides commands to examine and -manipulate the TODO entries from the new buffer (@pxref{Agenda commands}). -@xref{Global TODO list}, for more information. -@orgcmd{S-M-@key{RET},org-insert-todo-heading} -Insert a new TODO entry below the current one. -@end table - -@noindent -@vindex org-todo-state-tags-triggers -Changing a TODO state can also trigger tag changes. See the docstring of the -option @code{org-todo-state-tags-triggers} for details. - -@node TODO extensions, Progress logging, TODO basics, TODO Items -@section Extended use of TODO keywords -@cindex extended TODO keywords - -@vindex org-todo-keywords -By default, marked TODO entries have one of only two states: TODO and -DONE. Org mode allows you to classify TODO items in more complex ways -with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With -special setup, the TODO keyword system can work differently in different -files. - -Note that @i{tags} are another way to classify headlines in general and -TODO items in particular (@pxref{Tags}). - -@menu -* Workflow states:: From TODO to DONE in steps -* TODO types:: I do this, Fred does the rest -* Multiple sets in one file:: Mixing it all, and still finding your way -* Fast access to TODO states:: Single letter selection of a state -* Per-file keywords:: Different files, different requirements -* Faces for TODO keywords:: Highlighting states -* TODO dependencies:: When one task needs to wait for others -@end menu - -@node Workflow states, TODO types, TODO extensions, TODO extensions -@subsection TODO keywords as workflow states -@cindex TODO workflow -@cindex workflow states as TODO keywords - -You can use TODO keywords to indicate different @emph{sequential} states -in the process of working on an item, for example@footnote{Changing -this variable only becomes effective after restarting Org mode in a -buffer.}: - -@lisp -(setq org-todo-keywords - '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) -@end lisp - -The vertical bar separates the TODO keywords (states that @emph{need -action}) from the DONE states (which need @emph{no further action}). If -you don't provide the separator bar, the last state is used as the DONE -state. -@cindex completion, of TODO keywords -With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO -to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You may -also use a numeric prefix argument to quickly select a specific state. For -example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY. -Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you -define many keywords, you can use in-buffer completion -(@pxref{Completion}) or even a special one-key selection scheme -(@pxref{Fast access to TODO states}) to insert these words into the -buffer. Changing a TODO state can be logged with a timestamp, see -@ref{Tracking TODO state changes}, for more information. - -@node TODO types, Multiple sets in one file, Workflow states, TODO extensions -@subsection TODO keywords as types -@cindex TODO types -@cindex names as TODO keywords -@cindex types as TODO keywords - -The second possibility is to use TODO keywords to indicate different -@emph{types} of action items. For example, you might want to indicate -that items are for ``work'' or ``home''. Or, when you work with several -people on a single project, you might want to assign action items -directly to persons, by using their names as TODO keywords. This would -be set up like this: - -@lisp -(setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE"))) -@end lisp - -In this case, different keywords do not indicate a sequence, but rather -different types. So the normal work flow would be to assign a task to a -person, and later to mark it DONE. Org mode supports this style by adapting -the workings of the command @kbd{C-c C-t}@footnote{This is also true for the -@kbd{t} command in the timeline and agenda buffers.}. When used several -times in succession, it will still cycle through all names, in order to first -select the right type for a task. But when you return to the item after some -time and execute @kbd{C-c C-t} again, it will switch from any name directly -to DONE. Use prefix arguments or completion to quickly select a specific -name. You can also review the items of a specific TODO type in a sparse tree -by using a numeric prefix to @kbd{C-c / t}. For example, to see all things -Lucy has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items -from all agenda files into a single buffer, you would use the numeric prefix -argument as well when creating the global TODO list: @kbd{C-3 C-c a t}. - -@node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions -@subsection Multiple keyword sets in one file -@cindex TODO keyword sets - -Sometimes you may want to use different sets of TODO keywords in -parallel. For example, you may want to have the basic -@code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a -separate state indicating that an item has been canceled (so it is not -DONE, but also does not require action). Your setup would then look -like this: - -@lisp -(setq org-todo-keywords - '((sequence "TODO" "|" "DONE") - (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED") - (sequence "|" "CANCELED"))) -@end lisp - -The keywords should all be different, this helps Org mode to keep track -of which subsequence should be used for a given entry. In this setup, -@kbd{C-c C-t} only operates within a subsequence, so it switches from -@code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to -(nothing) to @code{REPORT}. Therefore you need a mechanism to initially -select the correct sequence. Besides the obvious ways like typing a -keyword or using completion, you may also apply the following commands: - -@table @kbd -@kindex C-S-@key{right} -@kindex C-S-@key{left} -@kindex C-u C-u C-c C-t -@item C-u C-u C-c C-t -@itemx C-S-@key{right} -@itemx C-S-@key{left} -These keys jump from one TODO subset to the next. In the above example, -@kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or -@code{DONE} to @code{REPORT}, and any of the words in the second row to -@code{CANCELED}. Note that the @kbd{C-S-} key binding conflict with -@code{shift-selection-mode} (@pxref{Conflicts}). -@kindex S-@key{right} -@kindex S-@key{left} -@item S-@key{right} -@itemx S-@key{left} -@kbd{S-@key{}} and @kbd{S-@key{}} and walk through @emph{all} -keywords from all sets, so for example @kbd{S-@key{}} would switch -from @code{DONE} to @code{REPORT} in the example above. See also -@ref{Conflicts}, for a discussion of the interaction with -@code{shift-selection-mode}. -@end table - -@node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions -@subsection Fast access to TODO states - -If you would like to quickly change an entry to an arbitrary TODO state -instead of cycling through the states, you can set up keys for -single-letter access to the states. This is done by adding the section -key after each keyword, in parentheses. For example: - -@lisp -(setq org-todo-keywords - '((sequence "TODO(t)" "|" "DONE(d)") - (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") - (sequence "|" "CANCELED(c)"))) -@end lisp - -@vindex org-fast-tag-selection-include-todo -If you then press @kbd{C-c C-t} followed by the selection key, the entry -will be switched to this state. @kbd{SPC} can be used to remove any TODO -keyword from an entry.@footnote{Check also the variable -@code{org-fast-tag-selection-include-todo}, it allows you to change the TODO -state through the tags interface (@pxref{Setting tags}), in case you like to -mingle the two concepts. Note that this means you need to come up with -unique keys across both sets of keywords.} - -@node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions -@subsection Setting up keywords for individual files -@cindex keyword options -@cindex per-file keywords -@cindex #+TODO -@cindex #+TYP_TODO -@cindex #+SEQ_TODO - -It can be very useful to use different aspects of the TODO mechanism in -different files. For file-local settings, you need to add special lines -to the file which set the keywords and interpretation for that file -only. For example, to set one of the two examples discussed above, you -need one of the following lines, starting in column zero anywhere in the -file: - -@example -#+TODO: TODO FEEDBACK VERIFY | DONE CANCELED -@end example -@noindent (you may also write @code{#+SEQ_TODO} to be explicit about the -interpretation, but it means the same as @code{#+TODO}), or -@example -#+TYP_TODO: Fred Sara Lucy Mike | DONE -@end example - -A setup for using several sets in parallel would be: - -@example -#+TODO: TODO | DONE -#+TODO: REPORT BUG KNOWNCAUSE | FIXED -#+TODO: | CANCELED -@end example - -@cindex completion, of option keywords -@kindex M-@key{TAB} -@noindent To make sure you are using the correct keyword, type -@samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion. - -@cindex DONE, final TODO keyword -Remember that the keywords after the vertical bar (or the last keyword -if no bar is there) must always mean that the item is DONE (although you -may use a different word). After changing one of these lines, use -@kbd{C-c C-c} with the cursor still in the line to make the changes -known to Org mode@footnote{Org mode parses these lines only when -Org mode is activated after visiting a file. @kbd{C-c C-c} with the -cursor in a line starting with @samp{#+} is simply restarting Org mode -for the current buffer.}. - -@node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions -@subsection Faces for TODO keywords -@cindex faces, for TODO keywords - -@vindex org-todo @r{(face)} -@vindex org-done @r{(face)} -@vindex org-todo-keyword-faces -Org mode highlights TODO keywords with special faces: @code{org-todo} -for keywords indicating that an item still has to be acted upon, and -@code{org-done} for keywords indicating that an item is finished. If -you are using more than 2 different states, you might want to use -special faces for some of them. This can be done using the variable -@code{org-todo-keyword-faces}. For example: - -@lisp -@group -(setq org-todo-keyword-faces - '(("TODO" . org-warning) ("STARTED" . "yellow") - ("CANCELED" . (:foreground "blue" :weight bold)))) -@end group -@end lisp - -While using a list with face properties as shown for CANCELED @emph{should} -work, this does not always seem to be the case. If necessary, define a -special face and use that. A string is interpreted as a color. The variable -@code{org-faces-easy-properties} determines if that color is interpreted as a -foreground or a background color. - -@node TODO dependencies, , Faces for TODO keywords, TODO extensions -@subsection TODO dependencies -@cindex TODO dependencies -@cindex dependencies, of TODO states - -@vindex org-enforce-todo-dependencies -@cindex property, ORDERED -The structure of Org files (hierarchy and lists) makes it easy to define TODO -dependencies. Usually, a parent TODO task should not be marked DONE until -all subtasks (defined as children tasks) are marked as DONE. And sometimes -there is a logical sequence to a number of (sub)tasks, so that one task -cannot be acted upon before all siblings above it are done. If you customize -the variable @code{org-enforce-todo-dependencies}, Org will block entries -from changing state to DONE while they have children that are not DONE. -Furthermore, if an entry has a property @code{ORDERED}, each of its children -will be blocked until all earlier siblings are marked DONE. Here is an -example: - -@example -* TODO Blocked until (two) is done -** DONE one -** TODO two - -* Parent - :PROPERTIES: - :ORDERED: t - :END: -** TODO a -** TODO b, needs to wait for (a) -** TODO c, needs to wait for (a) and (b) -@end example - -@table @kbd -@orgcmd{C-c C-x o,org-toggle-ordered-property} -@vindex org-track-ordered-property-with-tag -@cindex property, ORDERED -Toggle the @code{ORDERED} property of the current entry. A property is used -for this behavior because this should be local to the current entry, not -inherited like a tag. However, if you would like to @i{track} the value of -this property with a tag for better visibility, customize the variable -@code{org-track-ordered-property-with-tag}. -@orgkey{C-u C-u C-u C-c C-t} -Change TODO state, circumventing any state blocking. -@end table - -@vindex org-agenda-dim-blocked-tasks -If you set the variable @code{org-agenda-dim-blocked-tasks}, TODO entries -that cannot be closed because of such dependencies will be shown in a dimmed -font or even made invisible in agenda views (@pxref{Agenda Views}). - -@cindex checkboxes and TODO dependencies -@vindex org-enforce-todo-dependencies -You can also block changes of TODO states by looking at checkboxes -(@pxref{Checkboxes}). If you set the variable -@code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked -checkboxes will be blocked from switching to DONE. - -If you need more complex dependency structures, for example dependencies -between entries in different trees or files, check out the contributed -module @file{org-depend.el}. - -@page -@node Progress logging, Priorities, TODO extensions, TODO Items -@section Progress logging -@cindex progress logging -@cindex logging, of progress - -Org mode can automatically record a timestamp and possibly a note when -you mark a TODO item as DONE, or even each time you change the state of -a TODO item. This system is highly configurable, settings can be on a -per-keyword basis and can be localized to a file or even a subtree. For -information on how to clock working time for a task, see @ref{Clocking -work time}. - -@menu -* Closing items:: When was this entry marked DONE? -* Tracking TODO state changes:: When did the status change? -* Tracking your habits:: How consistent have you been? -@end menu - -@node Closing items, Tracking TODO state changes, Progress logging, Progress logging -@subsection Closing items - -The most basic logging is to keep track of @emph{when} a certain TODO -item was finished. This is achieved with@footnote{The corresponding -in-buffer setting is: @code{#+STARTUP: logdone}} - -@lisp -(setq org-log-done 'time) -@end lisp - -@noindent -Then each time you turn an entry from a TODO (not-done) state into any -of the DONE states, a line @samp{CLOSED: [timestamp]} will be inserted -just after the headline. If you turn the entry back into a TODO item -through further state cycling, that line will be removed again. If you -want to record a note along with the timestamp, use@footnote{The -corresponding in-buffer setting is: @code{#+STARTUP: lognotedone}} - -@lisp -(setq org-log-done 'note) -@end lisp - -@noindent -You will then be prompted for a note, and that note will be stored below -the entry with a @samp{Closing Note} heading. - -In the timeline (@pxref{Timeline}) and in the agenda -(@pxref{Weekly/daily agenda}), you can then use the @kbd{l} key to -display the TODO items with a @samp{CLOSED} timestamp on each day, -giving you an overview of what has been done. - -@node Tracking TODO state changes, Tracking your habits, Closing items, Progress logging -@subsection Tracking TODO state changes -@cindex drawer, for state change recording - -@vindex org-log-states-order-reversed -@vindex org-log-into-drawer -@cindex property, LOG_INTO_DRAWER -When TODO keywords are used as workflow states (@pxref{Workflow states}), you -might want to keep track of when a state change occurred and maybe take a -note about this change. You can either record just a timestamp, or a -time-stamped note for a change. These records will be inserted after the -headline as an itemized list, newest first@footnote{See the variable -@code{org-log-states-order-reversed}}. When taking a lot of notes, you might -want to get the notes out of the way into a drawer (@pxref{Drawers}). -Customize the variable @code{org-log-into-drawer} to get this -behavior---the recommended drawer for this is called @code{LOGBOOK}. You can -also overrule the setting of this variable for a subtree by setting a -@code{LOG_INTO_DRAWER} property. - -Since it is normally too much to record a note for every state, Org mode -expects configuration on a per-keyword basis for this. This is achieved by -adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a note -with timestamp) in parentheses after each keyword. For example, with the -setting - -@lisp -(setq org-todo-keywords - '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)"))) -@end lisp - -To record a timestamp without a note for TODO keywords configured with -@samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted. - -@noindent -@vindex org-log-done -you not only define global TODO keywords and fast access keys, but also -request that a time is recorded when the entry is set to -DONE@footnote{It is possible that Org mode will record two timestamps -when you are using both @code{org-log-done} and state change logging. -However, it will never prompt for two notes---if you have configured -both, the state change recording note will take precedence and cancel -the @samp{Closing Note}.}, and that a note is recorded when switching to -WAIT or CANCELED. The setting for WAIT is even more special: the -@samp{!} after the slash means that in addition to the note taken when -entering the state, a timestamp should be recorded when @i{leaving} the -WAIT state, if and only if the @i{target} state does not configure -logging for entering it. So it has no effect when switching from WAIT -to DONE, because DONE is configured to record a timestamp only. But -when switching from WAIT back to TODO, the @samp{/!} in the WAIT -setting now triggers a timestamp even though TODO has no logging -configured. - -You can use the exact same syntax for setting logging preferences local -to a buffer: -@example -#+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@) -@end example - -@cindex property, LOGGING -In order to define logging settings that are local to a subtree or a -single item, define a LOGGING property in this entry. Any non-empty -LOGGING property resets all logging settings to nil. You may then turn -on logging for this specific tree using STARTUP keywords like -@code{lognotedone} or @code{logrepeat}, as well as adding state specific -settings like @code{TODO(!)}. For example - -@example -* TODO Log each state with only a time - :PROPERTIES: - :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!) - :END: -* TODO Only log when switching to WAIT, and when repeating - :PROPERTIES: - :LOGGING: WAIT(@@) logrepeat - :END: -* TODO No logging at all - :PROPERTIES: - :LOGGING: nil - :END: -@end example - -@node Tracking your habits, , Tracking TODO state changes, Progress logging -@subsection Tracking your habits -@cindex habits - -Org has the ability to track the consistency of a special category of TODOs, -called ``habits''. A habit has the following properties: - -@enumerate -@item -You have enabled the @code{habits} module by customizing the variable -@code{org-modules}. -@item -The habit is a TODO item, with a TODO keyword representing an open state. -@item -The property @code{STYLE} is set to the value @code{habit}. -@item -The TODO has a scheduled date, usually with a @code{.+} style repeat -interval. A @code{++} style may be appropriate for habits with time -constraints, e.g., must be done on weekends, or a @code{+} style for an -unusual habit that can have a backlog, e.g., weekly reports. -@item -The TODO may also have minimum and maximum ranges specified by using the -syntax @samp{.+2d/3d}, which says that you want to do the task at least every -three days, but at most every two days. -@item -You must also have state logging for the @code{DONE} state enabled, in order -for historical data to be represented in the consistency graph. If it is not -enabled it is not an error, but the consistency graphs will be largely -meaningless. -@end enumerate - -To give you an idea of what the above rules look like in action, here's an -actual habit with some history: - -@example -** TODO Shave - SCHEDULED: <2009-10-17 Sat .+2d/4d> - - State "DONE" from "TODO" [2009-10-15 Thu] - - State "DONE" from "TODO" [2009-10-12 Mon] - - State "DONE" from "TODO" [2009-10-10 Sat] - - State "DONE" from "TODO" [2009-10-04 Sun] - - State "DONE" from "TODO" [2009-10-02 Fri] - - State "DONE" from "TODO" [2009-09-29 Tue] - - State "DONE" from "TODO" [2009-09-25 Fri] - - State "DONE" from "TODO" [2009-09-19 Sat] - - State "DONE" from "TODO" [2009-09-16 Wed] - - State "DONE" from "TODO" [2009-09-12 Sat] - :PROPERTIES: - :STYLE: habit - :LAST_REPEAT: [2009-10-19 Mon 00:36] - :END: -@end example - -What this habit says is: I want to shave at most every 2 days (given by the -@code{SCHEDULED} date and repeat interval) and at least every 4 days. If -today is the 15th, then the habit first appears in the agenda on Oct 17, -after the minimum of 2 days has elapsed, and will appear overdue on Oct 19, -after four days have elapsed. - -What's really useful about habits is that they are displayed along with a -consistency graph, to show how consistent you've been at getting that task -done in the past. This graph shows every day that the task was done over the -past three weeks, with colors for each day. The colors used are: - -@table @code -@item Blue -If the task wasn't to be done yet on that day. -@item Green -If the task could have been done on that day. -@item Yellow -If the task was going to be overdue the next day. -@item Red -If the task was overdue on that day. -@end table - -In addition to coloring each day, the day is also marked with an asterisk if -the task was actually done that day, and an exclamation mark to show where -the current day falls in the graph. - -There are several configuration variables that can be used to change the way -habits are displayed in the agenda. - -@table @code -@item org-habit-graph-column -The buffer column at which the consistency graph should be drawn. This will -overwrite any text in that column, so it is a good idea to keep your habits' -titles brief and to the point. -@item org-habit-preceding-days -The amount of history, in days before today, to appear in consistency graphs. -@item org-habit-following-days -The number of days after today that will appear in consistency graphs. -@item org-habit-show-habits-only-for-today -If non-nil, only show habits in today's agenda view. This is set to true by -default. -@end table - -Lastly, pressing @kbd{K} in the agenda buffer will cause habits to -temporarily be disabled and they won't appear at all. Press @kbd{K} again to -bring them back. They are also subject to tag filtering, if you have habits -which should only be done in certain contexts, for example. - -@node Priorities, Breaking down tasks, Progress logging, TODO Items -@section Priorities -@cindex priorities - -If you use Org mode extensively, you may end up with enough TODO items that -it starts to make sense to prioritize them. Prioritizing can be done by -placing a @emph{priority cookie} into the headline of a TODO item, like this - -@example -*** TODO [#A] Write letter to Sam Fortune -@end example - -@noindent -@vindex org-priority-faces -By default, Org mode supports three priorities: @samp{A}, @samp{B}, and -@samp{C}. @samp{A} is the highest priority. An entry without a cookie is -treated just like priority @samp{B}. Priorities make a difference only for -sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they -have no inherent meaning to Org mode. The cookies can be highlighted with -special faces by customizing the variable @code{org-priority-faces}. - -Priorities can be attached to any outline node; they do not need to be TODO -items. - -@table @kbd -@item @kbd{C-c ,} -@kindex @kbd{C-c ,} -@findex org-priority -Set the priority of the current headline (@command{org-priority}). The -command prompts for a priority character @samp{A}, @samp{B} or @samp{C}. -When you press @key{SPC} instead, the priority cookie is removed from the -headline. The priorities can also be changed ``remotely'' from the timeline -and agenda buffer with the @kbd{,} command (@pxref{Agenda commands}). -@c -@orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down} -@vindex org-priority-start-cycle-with-default -Increase/decrease priority of current headline@footnote{See also the option -@code{org-priority-start-cycle-with-default}.}. Note that these keys are -also used to modify timestamps (@pxref{Creating timestamps}). See also -@ref{Conflicts}, for a discussion of the interaction with -@code{shift-selection-mode}. -@end table - -@vindex org-highest-priority -@vindex org-lowest-priority -@vindex org-default-priority -You can change the range of allowed priorities by setting the variables -@code{org-highest-priority}, @code{org-lowest-priority}, and -@code{org-default-priority}. For an individual buffer, you may set -these values (highest, lowest, default) like this (please make sure that -the highest priority is earlier in the alphabet than the lowest -priority): - -@cindex #+PRIORITIES -@example -#+PRIORITIES: A C B -@end example - -@node Breaking down tasks, Checkboxes, Priorities, TODO Items -@section Breaking tasks down into subtasks -@cindex tasks, breaking down -@cindex statistics, for TODO items - -@vindex org-agenda-todo-list-sublevels -It is often advisable to break down large tasks into smaller, manageable -subtasks. You can do this by creating an outline tree below a TODO item, -with detailed subtasks on the tree@footnote{To keep subtasks out of the -global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep -the overview over the fraction of subtasks that are already completed, insert -either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will -be updated each time the TODO status of a child changes, or when pressing -@kbd{C-c C-c} on the cookie. For example: - -@example -* Organize Party [33%] -** TODO Call people [1/2] -*** TODO Peter -*** DONE Sarah -** TODO Buy food -** DONE Talk to neighbor -@end example - -@cindex property, COOKIE_DATA -If a heading has both checkboxes and TODO children below it, the meaning of -the statistics cookie become ambiguous. Set the property -@code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve -this issue. - -@vindex org-hierarchical-todo-statistics -If you would like to have the statistics cookie count any TODO entries in the -subtree (not just direct children), configure the variable -@code{org-hierarchical-todo-statistics}. To do this for a single subtree, -include the word @samp{recursive} into the value of the @code{COOKIE_DATA} -property. - -@example -* Parent capturing statistics [2/20] - :PROPERTIES: - :COOKIE_DATA: todo recursive - :END: -@end example - -If you would like a TODO entry to automatically change to DONE -when all children are done, you can use the following setup: - -@example -(defun org-summary-todo (n-done n-not-done) - "Switch entry to DONE when all subentries are done, to TODO otherwise." - (let (org-log-done org-log-states) ; turn off logging - (org-todo (if (= n-not-done 0) "DONE" "TODO")))) - -(add-hook 'org-after-todo-statistics-hook 'org-summary-todo) -@end example - - -Another possibility is the use of checkboxes to identify (a hierarchy of) a -large number of subtasks (@pxref{Checkboxes}). - - -@node Checkboxes, , Breaking down tasks, TODO Items -@section Checkboxes -@cindex checkboxes - -@vindex org-list-automatic-rules -Every item in a plain list@footnote{With the exception of description -lists. But you can allow it by modifying @code{org-list-automatic-rules} -accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting -it with the string @samp{[ ]}. This feature is similar to TODO items -(@pxref{TODO Items}), but is more lightweight. Checkboxes are not included -into the global TODO list, so they are often great to split a task into a -number of simple steps. Or you can use them in a shopping list. To toggle a -checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's -@file{org-mouse.el}). - -Here is an example of a checkbox list. - -@example -* TODO Organize party [2/4] - - [-] call people [1/3] - - [ ] Peter - - [X] Sarah - - [ ] Sam - - [X] order food - - [ ] think about what music to play - - [X] talk to the neighbors -@end example - -Checkboxes work hierarchically, so if a checkbox item has children that -are checkboxes, toggling one of the children checkboxes will make the -parent checkbox reflect if none, some, or all of the children are -checked. - -@cindex statistics, for checkboxes -@cindex checkbox statistics -@cindex property, COOKIE_DATA -@vindex org-hierarchical-checkbox-statistics -The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies -indicating how many checkboxes present in this entry have been checked off, -and the total number of checkboxes present. This can give you an idea on how -many checkboxes remain, even without opening a folded entry. The cookies can -be placed into a headline or into (the first line of) a plain list item. -Each cookie covers checkboxes of direct children structurally below the -headline/item on which the cookie appears@footnote{Set the variable -@code{org-hierarchical-checkbox-statistics} if you want such cookies to -count all checkboxes below the cookie, not just those belonging to direct -children.}. You have to insert the cookie yourself by typing either -@samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m} -result, as in the examples above. With @samp{[%]} you get information about -the percentage of checkboxes checked (in the above example, this would be -@samp{[50%]} and @samp{[33%]}, respectively). In a headline, a cookie can -count either checkboxes below the heading or TODO states of children, and it -will display whatever was changed last. Set the property @code{COOKIE_DATA} -to either @samp{checkbox} or @samp{todo} to resolve this issue. - -@cindex blocking, of checkboxes -@cindex checkbox blocking -@cindex property, ORDERED -If the current outline node has an @code{ORDERED} property, checkboxes must -be checked off in sequence, and an error will be thrown if you try to check -off a box while there are unchecked boxes above it. - -@noindent The following commands work with checkboxes: - -@table @kbd -@orgcmd{C-c C-c,org-toggle-checkbox} -Toggle checkbox status or (with prefix arg) checkbox presence at point. -With a single prefix argument, add an empty checkbox or remove the current -one@footnote{`C-u C-c C-c' on the @emph{first} item of a list with no checkbox -will add checkboxes to the rest of the list.}. With a double prefix argument, set it to @samp{[-]}, which is -considered to be an intermediate state. -@orgcmd{C-c C-x C-b,org-toggle-checkbox} -Toggle checkbox status or (with prefix arg) checkbox presence at point. With -double prefix argument, set it to @samp{[-]}, which is considered to be an -intermediate state. -@itemize @minus -@item -If there is an active region, toggle the first checkbox in the region -and set all remaining boxes to the same status as the first. With a prefix -arg, add or remove the checkbox for all items in the region. -@item -If the cursor is in a headline, toggle checkboxes in the region between -this headline and the next (so @emph{not} the entire subtree). -@item -If there is no active region, just toggle the checkbox at point. -@end itemize -@orgcmd{M-S-@key{RET},org-insert-todo-heading} -Insert a new item with a checkbox. This works only if the cursor is already -in a plain list item (@pxref{Plain lists}). -@orgcmd{C-c C-x o,org-toggle-ordered-property} -@vindex org-track-ordered-property-with-tag -@cindex property, ORDERED -Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must -be checked off in sequence. A property is used for this behavior because -this should be local to the current entry, not inherited like a tag. -However, if you would like to @i{track} the value of this property with a tag -for better visibility, customize the variable -@code{org-track-ordered-property-with-tag}. -@orgcmd{C-c #,org-update-statistics-cookies} -Update the statistics cookie in the current outline entry. When called with -a @kbd{C-u} prefix, update the entire file. Checkbox statistic cookies are -updated automatically if you toggle checkboxes with @kbd{C-c C-c} and make -new ones with @kbd{M-S-@key{RET}}. TODO statistics cookies update when -changing TODO states. If you delete boxes/entries or add/change them by -hand, use this command to get things back into sync. -@end table - -@node Tags, Properties and Columns, TODO Items, Top -@chapter Tags -@cindex tags -@cindex headline tagging -@cindex matching, tags -@cindex sparse tree, tag based - -An excellent way to implement labels and contexts for cross-correlating -information is to assign @i{tags} to headlines. Org mode has extensive -support for tags. - -@vindex org-tag-faces -Every headline can contain a list of tags; they occur at the end of the -headline. Tags are normal words containing letters, numbers, @samp{_}, and -@samp{@@}. Tags must be preceded and followed by a single colon, e.g., -@samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}. -Tags will by default be in bold face with the same color as the headline. -You may specify special faces for specific tags using the variable -@code{org-tag-faces}, in much the same way as you can for TODO keywords -(@pxref{Faces for TODO keywords}). - -@menu -* Tag inheritance:: Tags use the tree structure of the outline -* Setting tags:: How to assign tags to a headline -* Tag searches:: Searching for combinations of tags -@end menu - -@node Tag inheritance, Setting tags, Tags, Tags -@section Tag inheritance -@cindex tag inheritance -@cindex inheritance, of tags -@cindex sublevels, inclusion into tags match - -@i{Tags} make use of the hierarchical structure of outline trees. If a -heading has a certain tag, all subheadings will inherit the tag as -well. For example, in the list - -@example -* Meeting with the French group :work: -** Summary by Frank :boss:notes: -*** TODO Prepare slides for him :action: -@end example - -@noindent -the final heading will have the tags @samp{:work:}, @samp{:boss:}, -@samp{:notes:}, and @samp{:action:} even though the final heading is not -explicitly marked with those tags. You can also set tags that all entries in -a file should inherit just as if these tags were defined in a hypothetical -level zero that surrounds the entire file. Use a line like this@footnote{As -with all these in-buffer settings, pressing @kbd{C-c C-c} activates any -changes in the line.}: - -@cindex #+FILETAGS -@example -#+FILETAGS: :Peter:Boss:Secret: -@end example - -@noindent -@vindex org-use-tag-inheritance -@vindex org-tags-exclude-from-inheritance -To limit tag inheritance to specific tags, or to turn it off entirely, use -the variables @code{org-use-tag-inheritance} and -@code{org-tags-exclude-from-inheritance}. - -@vindex org-tags-match-list-sublevels -When a headline matches during a tags search while tag inheritance is turned -on, all the sublevels in the same tree will (for a simple match form) match -as well@footnote{This is only true if the search does not involve more -complex tests including properties (@pxref{Property searches}).}. The list -of matches may then become very long. If you only want to see the first tags -match in a subtree, configure the variable -@code{org-tags-match-list-sublevels} (not recommended). - -@node Setting tags, Tag searches, Tag inheritance, Tags -@section Setting tags -@cindex setting tags -@cindex tags, setting - -@kindex M-@key{TAB} -Tags can simply be typed into the buffer at the end of a headline. -After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is -also a special command for inserting tags: - -@table @kbd -@orgcmd{C-c C-q,org-set-tags-command} -@cindex completion, of tags -@vindex org-tags-column -Enter new tags for the current headline. Org mode will either offer -completion or a special single-key interface for setting tags, see -below. After pressing @key{RET}, the tags will be inserted and aligned -to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all -tags in the current buffer will be aligned to that column, just to make -things look nice. TAGS are automatically realigned after promotion, -demotion, and TODO state changes (@pxref{TODO basics}). -@orgcmd{C-c C-c,org-set-tags-command} -When the cursor is in a headline, this does the same as @kbd{C-c C-q}. -@end table - -@vindex org-tag-alist -Org supports tag insertion based on a @emph{list of tags}. By -default this list is constructed dynamically, containing all tags -currently used in the buffer. You may also globally specify a hard list -of tags with the variable @code{org-tag-alist}. Finally you can set -the default tags for a given file with lines like - -@cindex #+TAGS -@example -#+TAGS: @@work @@home @@tennisclub -#+TAGS: laptop car pc sailboat -@end example - -If you have globally defined your preferred set of tags using the -variable @code{org-tag-alist}, but would like to use a dynamic tag list -in a specific file, add an empty TAGS option line to that file: - -@example -#+TAGS: -@end example - -@vindex org-tag-persistent-alist -If you have a preferred set of tags that you would like to use in every file, -in addition to those defined on a per-file basis by TAGS option lines, then -you may specify a list of tags with the variable -@code{org-tag-persistent-alist}. You may turn this off on a per-file basis -by adding a STARTUP option line to that file: - -@example -#+STARTUP: noptag -@end example - -By default Org mode uses the standard minibuffer completion facilities for -entering tags. However, it also implements another, quicker, tag selection -method called @emph{fast tag selection}. This allows you to select and -deselect tags with just a single key press. For this to work well you should -assign unique letters to most of your commonly used tags. You can do this -globally by configuring the variable @code{org-tag-alist} in your -@file{.emacs} file. For example, you may find the need to tag many items in -different files with @samp{:@@home:}. In this case you can set something -like: - -@lisp -(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l))) -@end lisp - -@noindent If the tag is only relevant to the file you are working on, then you -can instead set the TAGS option line as: - -@example -#+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p) -@end example - -@noindent The tags interface will show the available tags in a splash -window. If you want to start a new line after a specific tag, insert -@samp{\n} into the tag list - -@example -#+TAGS: @@work(w) @@home(h) @@tennisclub(t) \n laptop(l) pc(p) -@end example - -@noindent or write them in two lines: - -@example -#+TAGS: @@work(w) @@home(h) @@tennisclub(t) -#+TAGS: laptop(l) pc(p) -@end example - -@noindent -You can also group together tags that are mutually exclusive by using -braces, as in: - -@example -#+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p) -@end example - -@noindent you indicate that at most one of @samp{@@work}, @samp{@@home}, -and @samp{@@tennisclub} should be selected. Multiple such groups are allowed. - -@noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of -these lines to activate any changes. - -@noindent -To set these mutually exclusive groups in the variable @code{org-tags-alist}, -you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead -of the braces. Similarly, you can use @code{:newline} to indicate a line -break. The previous example would be set globally by the following -configuration: - -@lisp -(setq org-tag-alist '((:startgroup . nil) - ("@@work" . ?w) ("@@home" . ?h) - ("@@tennisclub" . ?t) - (:endgroup . nil) - ("laptop" . ?l) ("pc" . ?p))) -@end lisp - -If at least one tag has a selection key then pressing @kbd{C-c C-c} will -automatically present you with a special interface, listing inherited tags, -the tags of the current headline, and a list of all valid tags with -corresponding keys@footnote{Keys will automatically be assigned to tags which -have no configured keys.}. In this interface, you can use the following -keys: - -@table @kbd -@item a-z... -Pressing keys assigned to tags will add or remove them from the list of -tags in the current line. Selecting a tag in a group of mutually -exclusive tags will turn off any other tags from that group. -@kindex @key{TAB} -@item @key{TAB} -Enter a tag in the minibuffer, even if the tag is not in the predefined -list. You will be able to complete on all tags present in the buffer. -You can also add several tags: just separate them with a comma. - -@kindex @key{SPC} -@item @key{SPC} -Clear all tags for this line. -@kindex @key{RET} -@item @key{RET} -Accept the modified set. -@item C-g -Abort without installing changes. -@item q -If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}. -@item ! -Turn off groups of mutually exclusive tags. Use this to (as an -exception) assign several tags from such a group. -@item C-c -Toggle auto-exit after the next change (see below). -If you are using expert mode, the first @kbd{C-c} will display the -selection window. -@end table - -@noindent -This method lets you assign tags to a headline with very few keys. With -the above setup, you could clear the current tags and set @samp{@@home}, -@samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c -C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to -@samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or -alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag -@samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h -@key{RET} @key{RET}}. - -@vindex org-fast-tag-selection-single-key -If you find that most of the time you need only a single key press to -modify your list of tags, set the variable -@code{org-fast-tag-selection-single-key}. Then you no longer have to -press @key{RET} to exit fast tag selection---it will immediately exit -after the first change. If you then occasionally need more keys, press -@kbd{C-c} to turn off auto-exit for the current tag selection process -(in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c -C-c}). If you set the variable to the value @code{expert}, the special -window is not even shown for single-key tag selection, it comes up only -when you press an extra @kbd{C-c}. - -@node Tag searches, , Setting tags, Tags -@section Tag searches -@cindex tag searches -@cindex searching for tags - -Once a system of tags has been set up, it can be used to collect related -information into special lists. - -@table @kbd -@orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree} -Create a sparse tree with all headlines matching a tags search. With a -@kbd{C-u} prefix argument, ignore headlines that are not a TODO line. -@orgcmd{C-c a m,org-tags-view} -Create a global list of tag matches from all agenda files. -@xref{Matching tags and properties}. -@orgcmd{C-c a M,org-tags-view} -@vindex org-tags-match-list-sublevels -Create a global list of tag matches from all agenda files, but check -only TODO items and force checking subitems (see variable -@code{org-tags-match-list-sublevels}). -@end table - -These commands all prompt for a match string which allows basic Boolean logic -like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and -@samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries -which are tagged, like @samp{Kathy} or @samp{Sally}. The full syntax of the search -string is rich and allows also matching against TODO keywords, entry levels -and properties. For a complete description with many examples, see -@ref{Matching tags and properties}. - - -@node Properties and Columns, Dates and Times, Tags, Top -@chapter Properties and columns -@cindex properties - -A property is a key-value pair associated with an entry. Properties can be -set so they are associated with a single entry, with every entry in a tree, -or with every entry in an Org mode file. - -There are two main applications for properties in Org mode. First, -properties are like tags, but with a value. Imagine maintaining a file where -you document bugs and plan releases for a piece of software. Instead of -using tags like @code{:release_1:}, @code{:release_2:}, you can use a -property, say @code{:Release:}, that in different subtrees has different -values, such as @code{1.0} or @code{2.0}. Second, you can use properties to -implement (very basic) database capabilities in an Org buffer. Imagine -keeping track of your music CDs, where properties could be things such as the -album, artist, date of release, number of tracks, and so on. - -Properties can be conveniently edited and viewed in column view -(@pxref{Column view}). - -@menu -* Property syntax:: How properties are spelled out -* Special properties:: Access to other Org mode features -* Property searches:: Matching property values -* Property inheritance:: Passing values down the tree -* Column view:: Tabular viewing and editing -* Property API:: Properties for Lisp programmers -@end menu - -@node Property syntax, Special properties, Properties and Columns, Properties and Columns -@section Property syntax -@cindex property syntax -@cindex drawer, for properties - -Properties are key-value pairs. When they are associated with a single entry -or with a tree they need to be inserted into a special -drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property -is specified on a single line, with the key (surrounded by colons) -first, and the value after it. Here is an example: - -@example -* CD collection -** Classic -*** Goldberg Variations - :PROPERTIES: - :Title: Goldberg Variations - :Composer: J.S. Bach - :Artist: Glen Gould - :Publisher: Deutsche Grammophon - :NDisks: 1 - :END: -@end example - -Depending on the value of @code{org-use-property-inheritance}, a property set -this way will either be associated with a single entry, or the sub-tree -defined by the entry, see @ref{Property inheritance}. - -You may define the allowed values for a particular property @samp{:Xyz:} -by setting a property @samp{:Xyz_ALL:}. This special property is -@emph{inherited}, so if you set it in a level 1 entry, it will apply to -the entire tree. When allowed values are defined, setting the -corresponding property becomes easier and is less prone to typing -errors. For the example with the CD collection, we can predefine -publishers and the number of disks in a box like this: - -@example -* CD collection - :PROPERTIES: - :NDisks_ALL: 1 2 3 4 - :Publisher_ALL: "Deutsche Grammophon" Philips EMI - :END: -@end example - -If you want to set properties that can be inherited by any entry in a -file, use a line like -@cindex property, _ALL -@cindex #+PROPERTY -@example -#+PROPERTY: NDisks_ALL 1 2 3 4 -@end example - -If you want to add to the value of an existing property, append a @code{+} to -the property name. The following results in the property @code{var} having -the value ``foo=1 bar=2''. -@cindex property, + -@example -#+PROPERTY: var foo=1 -#+PROPERTY: var+ bar=2 -@end example - -It is also possible to add to the values of inherited properties. The -following results in the @code{genres} property having the value ``Classic -Baroque'' under the @code{Goldberg Variations} subtree. -@cindex property, + -@example -* CD collection -** Classic - :PROPERTIES: - :GENRES: Classic - :END: -*** Goldberg Variations - :PROPERTIES: - :Title: Goldberg Variations - :Composer: J.S. Bach - :Artist: Glen Gould - :Publisher: Deutsche Grammophon - :NDisks: 1 - :GENRES+: Baroque - :END: -@end example -Note that a property can only have one entry per Drawer. - -@vindex org-global-properties -Property values set with the global variable -@code{org-global-properties} can be inherited by all entries in all -Org files. - -@noindent -The following commands help to work with properties: - -@table @kbd -@orgcmd{M-@key{TAB},pcomplete} -After an initial colon in a line, complete property keys. All keys used -in the current file will be offered as possible completions. -@orgcmd{C-c C-x p,org-set-property} -Set a property. This prompts for a property name and a value. If -necessary, the property drawer is created as well. -@item M-x org-insert-property-drawer -@findex org-insert-property-drawer -Insert a property drawer into the current entry. The drawer will be -inserted early in the entry, but after the lines with planning -information like deadlines. -@orgcmd{C-c C-c,org-property-action} -With the cursor in a property drawer, this executes property commands. -@orgcmd{C-c C-c s,org-set-property} -Set a property in the current entry. Both the property and the value -can be inserted using completion. -@orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value} -Switch property at point to the next/previous allowed value. -@orgcmd{C-c C-c d,org-delete-property} -Remove a property from the current entry. -@orgcmd{C-c C-c D,org-delete-property-globally} -Globally remove a property, from all entries in the current file. -@orgcmd{C-c C-c c,org-compute-property-at-point} -Compute the property at point, using the operator and scope from the -nearest column format definition. -@end table - -@node Special properties, Property searches, Property syntax, Properties and Columns -@section Special properties -@cindex properties, special - -Special properties provide an alternative access method to Org mode features, -like the TODO state or the priority of an entry, discussed in the previous -chapters. This interface exists so that you can include these states in a -column view (@pxref{Column view}), or to use them in queries. The following -property names are special and (except for @code{:CATEGORY:}) should not be -used as keys in the properties drawer: - -@cindex property, special, TODO -@cindex property, special, TAGS -@cindex property, special, ALLTAGS -@cindex property, special, CATEGORY -@cindex property, special, PRIORITY -@cindex property, special, DEADLINE -@cindex property, special, SCHEDULED -@cindex property, special, CLOSED -@cindex property, special, TIMESTAMP -@cindex property, special, TIMESTAMP_IA -@cindex property, special, CLOCKSUM -@cindex property, special, BLOCKED -@c guessing that ITEM is needed in this area; also, should this list be sorted? -@cindex property, special, ITEM -@cindex property, special, FILE -@example -TODO @r{The TODO keyword of the entry.} -TAGS @r{The tags defined directly in the headline.} -ALLTAGS @r{All tags, including inherited ones.} -CATEGORY @r{The category of an entry.} -PRIORITY @r{The priority of the entry, a string with a single letter.} -DEADLINE @r{The deadline time string, without the angular brackets.} -SCHEDULED @r{The scheduling timestamp, without the angular brackets.} -CLOSED @r{When was this entry closed?} -TIMESTAMP @r{The first keyword-less timestamp in the entry.} -TIMESTAMP_IA @r{The first inactive timestamp in the entry.} -CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}} - @r{must be run first to compute the values in the current buffer.} -BLOCKED @r{"t" if task is currently blocked by children or siblings} -ITEM @r{The content of the entry.} -FILE @r{The filename the entry is located in.} -@end example - -@node Property searches, Property inheritance, Special properties, Properties and Columns -@section Property searches -@cindex properties, searching -@cindex searching, of properties - -To create sparse trees and special lists with selection based on properties, -the same commands are used as for tag searches (@pxref{Tag searches}). -@table @kbd -@orgcmdkkc{C-c / m,C-c \,org-match-sparse-tree} -Create a sparse tree with all matching entries. With a -@kbd{C-u} prefix argument, ignore headlines that are not a TODO line. -@orgcmd{C-c a m,org-tags-view} -Create a global list of tag/property matches from all agenda files. -@xref{Matching tags and properties}. -@orgcmd{C-c a M,org-tags-view} -@vindex org-tags-match-list-sublevels -Create a global list of tag matches from all agenda files, but check -only TODO items and force checking of subitems (see variable -@code{org-tags-match-list-sublevels}). -@end table - -The syntax for the search string is described in @ref{Matching tags and -properties}. - -There is also a special command for creating sparse trees based on a -single property: - -@table @kbd -@orgkey{C-c / p} -Create a sparse tree based on the value of a property. This first -prompts for the name of a property, and then for a value. A sparse tree -is created with all entries that define this property with the given -value. If you enclose the value in curly braces, it is interpreted as -a regular expression and matched against the property values. -@end table - -@node Property inheritance, Column view, Property searches, Properties and Columns -@section Property Inheritance -@cindex properties, inheritance -@cindex inheritance, of properties - -@vindex org-use-property-inheritance -The outline structure of Org mode documents lends itself to an -inheritance model of properties: if the parent in a tree has a certain -property, the children can inherit this property. Org mode does not -turn this on by default, because it can slow down property searches -significantly and is often not needed. However, if you find inheritance -useful, you can turn it on by setting the variable -@code{org-use-property-inheritance}. It may be set to @code{t} to make -all properties inherited from the parent, to a list of properties -that should be inherited, or to a regular expression that matches -inherited properties. If a property has the value @samp{nil}, this is -interpreted as an explicit undefine of the property, so that inheritance -search will stop at this value and return @code{nil}. - -Org mode has a few properties for which inheritance is hard-coded, at -least for the special applications for which they are used: - -@cindex property, COLUMNS -@table @code -@item COLUMNS -The @code{:COLUMNS:} property defines the format of column view -(@pxref{Column view}). It is inherited in the sense that the level -where a @code{:COLUMNS:} property is defined is used as the starting -point for a column view table, independently of the location in the -subtree from where columns view is turned on. -@item CATEGORY -@cindex property, CATEGORY -For agenda view, a category set through a @code{:CATEGORY:} property -applies to the entire subtree. -@item ARCHIVE -@cindex property, ARCHIVE -For archiving, the @code{:ARCHIVE:} property may define the archive -location for the entire subtree (@pxref{Moving subtrees}). -@item LOGGING -@cindex property, LOGGING -The LOGGING property may define logging settings for an entry or a -subtree (@pxref{Tracking TODO state changes}). -@end table - -@node Column view, Property API, Property inheritance, Properties and Columns -@section Column view - -A great way to view and edit properties in an outline tree is -@emph{column view}. In column view, each outline node is turned into a -table row. Columns in this table provide access to properties of the -entries. Org mode implements columns by overlaying a tabular structure -over the headline of each item. While the headlines have been turned -into a table row, you can still change the visibility of the outline -tree. For example, you get a compact table by switching to CONTENTS -view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view -is active), but you can still open, read, and edit the entry below each -headline. Or, you can switch to column view after executing a sparse -tree command and in this way get a table only for the selected items. -Column view also works in agenda buffers (@pxref{Agenda Views}) where -queries have collected selected items, possibly from a number of files. - -@menu -* Defining columns:: The COLUMNS format property -* Using column view:: How to create and use column view -* Capturing column view:: A dynamic block for column view -@end menu - -@node Defining columns, Using column view, Column view, Column view -@subsection Defining columns -@cindex column view, for properties -@cindex properties, column view - -Setting up a column view first requires defining the columns. This is -done by defining a column format line. - -@menu -* Scope of column definitions:: Where defined, where valid? -* Column attributes:: Appearance and content of a column -@end menu - -@node Scope of column definitions, Column attributes, Defining columns, Defining columns -@subsubsection Scope of column definitions - -To define a column format for an entire file, use a line like - -@cindex #+COLUMNS -@example -#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO -@end example - -To specify a format that only applies to a specific tree, add a -@code{:COLUMNS:} property to the top node of that tree, for example: - -@example -** Top node for columns view - :PROPERTIES: - :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO - :END: -@end example - -If a @code{:COLUMNS:} property is present in an entry, it defines columns -for the entry itself, and for the entire subtree below it. Since the -column definition is part of the hierarchical structure of the document, -you can define columns on level 1 that are general enough for all -sublevels, and more specific columns further down, when you edit a -deeper part of the tree. - -@node Column attributes, , Scope of column definitions, Defining columns -@subsubsection Column attributes -A column definition sets the attributes of a column. The general -definition looks like this: - -@example - %[@var{width}]@var{property}[(@var{title})][@{@var{summary-type}@}] -@end example - -@noindent -Except for the percent sign and the property name, all items are -optional. The individual parts have the following meaning: - -@example -@var{width} @r{An integer specifying the width of the column in characters.} - @r{If omitted, the width will be determined automatically.} -@var{property} @r{The property that should be edited in this column.} - @r{Special properties representing meta data are allowed here} - @r{as well (@pxref{Special properties})} -@var{title} @r{The header text for the column. If omitted, the property} - @r{name is used.} -@{@var{summary-type}@} @r{The summary type. If specified, the column values for} - @r{parent nodes are computed from the children.} - @r{Supported summary types are:} - @{+@} @r{Sum numbers in this column.} - @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.} - @{$@} @r{Currency, short for @samp{+;%.2f}.} - @{:@} @r{Sum times, HH:MM, plain numbers are hours.} - @{X@} @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.} - @{X/@} @r{Checkbox status, @samp{[n/m]}.} - @{X%@} @r{Checkbox status, @samp{[n%]}.} - @{min@} @r{Smallest number in column.} - @{max@} @r{Largest number.} - @{mean@} @r{Arithmetic mean of numbers.} - @{:min@} @r{Smallest time value in column.} - @{:max@} @r{Largest time value.} - @{:mean@} @r{Arithmetic mean of time values.} - @{@@min@} @r{Minimum age (in days/hours/mins/seconds).} - @{@@max@} @r{Maximum age (in days/hours/mins/seconds).} - @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).} - @{est+@} @r{Add low-high estimates.} -@end example - -@noindent -Be aware that you can only have one summary type for any property you -include. Subsequent columns referencing the same property will all display the -same summary information. - -The @code{est+} summary type requires further explanation. It is used for -combining estimates, expressed as low-high ranges. For example, instead -of estimating a particular task will take 5 days, you might estimate it as -5-6 days if you're fairly confident you know how much work is required, or -1-10 days if you don't really know what needs to be done. Both ranges -average at 5.5 days, but the first represents a more predictable delivery. - -When combining a set of such estimates, simply adding the lows and highs -produces an unrealistically wide result. Instead, @code{est+} adds the -statistical mean and variance of the sub-tasks, generating a final estimate -from the sum. For example, suppose you had ten tasks, each of which was -estimated at 0.5 to 2 days of work. Straight addition produces an estimate -of 5 to 20 days, representing what to expect if everything goes either -extremely well or extremely poorly. In contrast, @code{est+} estimates the -full job more realistically, at 10-15 days. - -Here is an example for a complete columns definition, along with allowed -values. - -@example -:COLUMNS: %25ITEM %9Approved(Approved?)@{X@} %Owner %11Status \@footnote{Please note that the COLUMNS definition must be on a single line---it is wrapped here only because of formatting constraints.} - %10Time_Estimate@{:@} %CLOCKSUM -:Owner_ALL: Tammy Mark Karl Lisa Don -:Status_ALL: "In progress" "Not started yet" "Finished" "" -:Approved_ALL: "[ ]" "[X]" -@end example - -@noindent -The first column, @samp{%25ITEM}, means the first 25 characters of the -item itself, i.e.@: of the headline. You probably always should start the -column definition with the @samp{ITEM} specifier. The other specifiers -create columns @samp{Owner} with a list of names as allowed values, for -@samp{Status} with four different possible values, and for a checkbox -field @samp{Approved}. When no width is given after the @samp{%} -character, the column will be exactly as wide as it needs to be in order -to fully display all values. The @samp{Approved} column does have a -modified title (@samp{Approved?}, with a question mark). Summaries will -be created for the @samp{Time_Estimate} column by adding time duration -expressions like HH:MM, and for the @samp{Approved} column, by providing -an @samp{[X]} status if all children have been checked. The -@samp{CLOCKSUM} column is special, it lists the sum of CLOCK intervals -in the subtree. - -@node Using column view, Capturing column view, Defining columns, Column view -@subsection Using column view - -@table @kbd -@tsubheading{Turning column view on and off} -@orgcmd{C-c C-x C-c,org-columns} -@vindex org-columns-default-format -Turn on column view. If the cursor is before the first headline in the file, -column view is turned on for the entire file, using the @code{#+COLUMNS} -definition. If the cursor is somewhere inside the outline, this command -searches the hierarchy, up from point, for a @code{:COLUMNS:} property that -defines a format. When one is found, the column view table is established -for the tree starting at the entry that contains the @code{:COLUMNS:} -property. If no such property is found, the format is taken from the -@code{#+COLUMNS} line or from the variable @code{org-columns-default-format}, -and column view is established for the current entry and its subtree. -@orgcmd{r,org-columns-redo} -Recreate the column view, to include recent changes made in the buffer. -@orgcmd{g,org-columns-redo} -Same as @kbd{r}. -@orgcmd{q,org-columns-quit} -Exit column view. -@tsubheading{Editing values} -@item @key{left} @key{right} @key{up} @key{down} -Move through the column view from field to field. -@kindex S-@key{left} -@kindex S-@key{right} -@item S-@key{left}/@key{right} -Switch to the next/previous allowed value of the field. For this, you -have to have specified allowed values for a property. -@item 1..9,0 -Directly select the Nth allowed value, @kbd{0} selects the 10th value. -@orgcmdkkcc{n,p,org-columns-next-allowed-value,org-columns-previous-allowed-value} -Same as @kbd{S-@key{left}/@key{right}} -@orgcmd{e,org-columns-edit-value} -Edit the property at point. For the special properties, this will -invoke the same interface that you normally use to change that -property. For example, when editing a TAGS property, the tag completion -or fast selection interface will pop up. -@orgcmd{C-c C-c,org-columns-set-tags-or-toggle} -When there is a checkbox at point, toggle it. -@orgcmd{v,org-columns-show-value} -View the full value of this property. This is useful if the width of -the column is smaller than that of the value. -@orgcmd{a,org-columns-edit-allowed} -Edit the list of allowed values for this property. If the list is found -in the hierarchy, the modified values is stored there. If no list is -found, the new value is stored in the first entry that is part of the -current column view. -@tsubheading{Modifying the table structure} -@orgcmdkkcc{<,>,org-columns-narrow,org-columns-widen} -Make the column narrower/wider by one character. -@orgcmd{S-M-@key{right},org-columns-new} -Insert a new column, to the left of the current column. -@orgcmd{S-M-@key{left},org-columns-delete} -Delete the current column. -@end table - -@node Capturing column view, , Using column view, Column view -@subsection Capturing column view - -Since column view is just an overlay over a buffer, it cannot be -exported or printed directly. If you want to capture a column view, use -a @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame -of this block looks like this: - -@cindex #+BEGIN, columnview -@example -* The column view -#+BEGIN: columnview :hlines 1 :id "label" - -#+END: -@end example - -@noindent This dynamic block has the following parameters: - -@table @code -@item :id -This is the most important parameter. Column view is a feature that is -often localized to a certain (sub)tree, and the capture block might be -at a different location in the file. To identify the tree whose view to -capture, you can use 4 values: -@cindex property, ID -@example -local @r{use the tree in which the capture block is located} -global @r{make a global view, including all headings in the file} -"file:@var{path-to-file}" - @r{run column view at the top of this file} -"@var{ID}" @r{call column view in the tree that has an @code{:ID:}} - @r{property with the value @i{label}. You can use} - @r{@kbd{M-x org-id-copy} to create a globally unique ID for} - @r{the current entry and copy it to the kill-ring.} -@end example -@item :hlines -When @code{t}, insert an hline after every line. When a number @var{N}, insert -an hline before each headline with level @code{<= @var{N}}. -@item :vlines -When set to @code{t}, force column groups to get vertical lines. -@item :maxlevel -When set to a number, don't capture entries below this level. -@item :skip-empty-rows -When set to @code{t}, skip rows where the only non-empty specifier of the -column view is @code{ITEM}. - -@end table - -@noindent -The following commands insert or update the dynamic block: - -@table @kbd -@orgcmd{C-c C-x i,org-insert-columns-dblock} -Insert a dynamic block capturing a column view. You will be prompted -for the scope or ID of the view. -@orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update} -Update dynamic block at point. The cursor needs to be in the -@code{#+BEGIN} line of the dynamic block. -@orgcmd{C-u C-c C-x C-u,org-update-all-dblocks} -Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if -you have several clock table blocks, column-capturing blocks or other dynamic -blocks in a buffer. -@end table - -You can add formulas to the column view table and you may add plotting -instructions in front of the table---these will survive an update of the -block. If there is a @code{#+TBLFM:} after the table, the table will -actually be recalculated automatically after an update. - -An alternative way to capture and process property values into a table is -provided by Eric Schulte's @file{org-collector.el} which is a contributed -package@footnote{Contributed packages are not part of Emacs, but are -distributed with the main distribution of Org (visit -@uref{http://orgmode.org}).}. It provides a general API to collect -properties from entries in a certain scope, and arbitrary Lisp expressions to -process these values before inserting them into a table or a dynamic block. - -@node Property API, , Column view, Properties and Columns -@section The Property API -@cindex properties, API -@cindex API, for properties - -There is a full API for accessing and changing properties. This API can -be used by Emacs Lisp programs to work with properties and to implement -features based on them. For more information see @ref{Using the -property API}. - -@node Dates and Times, Capture - Refile - Archive, Properties and Columns, Top -@chapter Dates and times -@cindex dates -@cindex times -@cindex timestamp -@cindex date stamp - -To assist project planning, TODO items can be labeled with a date and/or -a time. The specially formatted string carrying the date and time -information is called a @emph{timestamp} in Org mode. This may be a -little confusing because timestamp is often used as indicating when -something was created or last changed. However, in Org mode this term -is used in a much wider sense. - -@menu -* Timestamps:: Assigning a time to a tree entry -* Creating timestamps:: Commands which insert timestamps -* Deadlines and scheduling:: Planning your work -* Clocking work time:: Tracking how long you spend on a task -* Effort estimates:: Planning work effort in advance -* Relative timer:: Notes with a running timer -* Countdown timer:: Starting a countdown timer for a task -@end menu - - -@node Timestamps, Creating timestamps, Dates and Times, Dates and Times -@section Timestamps, deadlines, and scheduling -@cindex timestamps -@cindex ranges, time -@cindex date stamps -@cindex deadlines -@cindex scheduling - -A timestamp is a specification of a date (possibly with a time or a range of -times) in a special format, either @samp{<2003-09-16 Tue>}@footnote{In this -simplest form, the day name is optional when you type the date yourself. -However, any dates inserted or modified by Org will add that day name, for -reading convenience.} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 -Tue 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601 -date/time format. To use an alternative format, see @ref{Custom time -format}.}. A timestamp can appear anywhere in the headline or body of an Org -tree entry. Its presence causes entries to be shown on specific dates in the -agenda (@pxref{Weekly/daily agenda}). We distinguish: - -@table @var -@item Plain timestamp; Event; Appointment -@cindex timestamp -@cindex appointment -A simple timestamp just assigns a date/time to an item. This is just -like writing down an appointment or event in a paper agenda. In the -timeline and agenda displays, the headline of an entry associated with a -plain timestamp will be shown exactly on that date. - -@example -* Meet Peter at the movies <2006-11-01 Wed 19:15> -* Discussion on climate change <2006-11-02 Thu 20:00-22:00> -@end example - -@item Timestamp with repeater interval -@cindex timestamp, with repeater interval -A timestamp may contain a @emph{repeater interval}, indicating that it -applies not only on the given date, but again and again after a certain -interval of N days (d), weeks (w), months (m), or years (y). The -following will show up in the agenda every Wednesday: - -@example -* Pick up Sam at school <2007-05-16 Wed 12:30 +1w> -@end example - -@item Diary-style sexp entries -For more complex date specifications, Org mode supports using the special -sexp diary entries implemented in the Emacs calendar/diary -package@footnote{When working with the standard diary sexp functions, you -need to be very careful with the order of the arguments. That order depend -evilly on the variable @code{calendar-date-style} (or, for older Emacs -versions, @code{european-calendar-style}). For example, to specify a date -December 12, 2005, the call might look like @code{(diary-date 12 1 2005)} or -@code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on -the settings. This has been the source of much confusion. Org mode users -can resort to special versions of these functions like @code{org-date} or -@code{org-anniversary}. These work just like the corresponding @code{diary-} -functions, but with stable ISO order of arguments (year, month, day) wherever -applicable, independent of the value of @code{calendar-date-style}.}. For -example with optional time - -@example -* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month - <%%(org-float t 4 2)> -@end example - -@item Time/Date range -@cindex timerange -@cindex date range -Two timestamps connected by @samp{--} denote a range. The headline -will be shown on the first and last day of the range, and on any dates -that are displayed and fall in the range. Here is an example: - -@example -** Meeting in Amsterdam - <2004-08-23 Mon>--<2004-08-26 Thu> -@end example - -@item Inactive timestamp -@cindex timestamp, inactive -@cindex inactive timestamp -Just like a plain timestamp, but with square brackets instead of -angular ones. These timestamps are inactive in the sense that they do -@emph{not} trigger an entry to show up in the agenda. - -@example -* Gillian comes late for the fifth time [2006-11-01 Wed] -@end example - -@end table - -@node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times -@section Creating timestamps -@cindex creating timestamps -@cindex timestamps, creating - -For Org mode to recognize timestamps, they need to be in the specific -format. All commands listed below produce timestamps in the correct -format. - -@table @kbd -@orgcmd{C-c .,org-time-stamp} -Prompt for a date and insert a corresponding timestamp. When the cursor is -at an existing timestamp in the buffer, the command is used to modify this -timestamp instead of inserting a new one. When this command is used twice in -succession, a time range is inserted. -@c -@orgcmd{C-c !,org-time-stamp-inactive} -Like @kbd{C-c .}, but insert an inactive timestamp that will not cause -an agenda entry. -@c -@kindex C-u C-c . -@kindex C-u C-c ! -@item C-u C-c . -@itemx C-u C-c ! -@vindex org-time-stamp-rounding-minutes -Like @kbd{C-c .} and @kbd{C-c !}, but use the alternative format which -contains date and time. The default time can be rounded to multiples of 5 -minutes, see the option @code{org-time-stamp-rounding-minutes}. -@c -@orgkey{C-c C-c} -Normalize timestamp, insert/fix day name if missing or wrong. -@c -@orgcmd{C-c <,org-date-from-calendar} -Insert a timestamp corresponding to the cursor date in the Calendar. -@c -@orgcmd{C-c >,org-goto-calendar} -Access the Emacs calendar for the current date. If there is a -timestamp in the current line, go to the corresponding date -instead. -@c -@orgcmd{C-c C-o,org-open-at-point} -Access the agenda for the date given by the timestamp or -range at -point (@pxref{Weekly/daily agenda}). -@c -@orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day} -Change date at cursor by one day. These key bindings conflict with -shift-selection and related modes (@pxref{Conflicts}). -@c -@orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down} -Change the item under the cursor in a timestamp. The cursor can be on a -year, month, day, hour or minute. When the timestamp contains a time range -like @samp{15:30-16:30}, modifying the first time will also shift the second, -shifting the time block with constant length. To change the length, modify -the second time. Note that if the cursor is in a headline and not at a -timestamp, these same keys modify the priority of an item. -(@pxref{Priorities}). The key bindings also conflict with shift-selection and -related modes (@pxref{Conflicts}). -@c -@orgcmd{C-c C-y,org-evaluate-time-range} -@cindex evaluate time range -Evaluate a time range by computing the difference between start and end. -With a prefix argument, insert result after the time range (in a table: into -the following column). -@end table - - -@menu -* The date/time prompt:: How Org mode helps you entering date and time -* Custom time format:: Making dates look different -@end menu - -@node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps -@subsection The date/time prompt -@cindex date, reading in minibuffer -@cindex time, reading in minibuffer - -@vindex org-read-date-prefer-future -When Org mode prompts for a date/time, the default is shown in default -date/time format, and the prompt therefore seems to ask for a specific -format. But it will in fact accept any string containing some date and/or -time information, and it is really smart about interpreting your input. You -can, for example, use @kbd{C-y} to paste a (possibly multi-line) string -copied from an email message. Org mode will find whatever information is in -there and derive anything you have not specified from the @emph{default date -and time}. The default is usually the current date and time, but when -modifying an existing timestamp, or when entering the second stamp of a -range, it is taken from the stamp in the buffer. When filling in -information, Org mode assumes that most of the time you will want to enter a -date in the future: if you omit the month/year and the given day/month is -@i{before} today, it will assume that you mean a future date@footnote{See the -variable @code{org-read-date-prefer-future}. You may set that variable to -the symbol @code{time} to even make a time before now shift the date to -tomorrow.}. If the date has been automatically shifted into the future, the -time prompt will show this with @samp{(=>F).} - -For example, let's assume that today is @b{June 13, 2006}. Here is how -various inputs will be interpreted, the items filled in by Org mode are -in @b{bold}. - -@example -3-2-5 @result{} 2003-02-05 -2/5/3 @result{} 2003-02-05 -14 @result{} @b{2006}-@b{06}-14 -12 @result{} @b{2006}-@b{07}-12 -2/5 @result{} @b{2007}-02-05 -Fri @result{} nearest Friday (default date or later) -sep 15 @result{} @b{2006}-09-15 -feb 15 @result{} @b{2007}-02-15 -sep 12 9 @result{} 2009-09-12 -12:45 @result{} @b{2006}-@b{06}-@b{13} 12:45 -22 sept 0:34 @result{} @b{2006}-09-22 0:34 -w4 @result{} ISO week for of the current year @b{2006} -2012 w4 fri @result{} Friday of ISO week 4 in 2012 -2012-w04-5 @result{} Same as above -@end example - -Furthermore you can specify a relative date by giving, as the -@emph{first} thing in the input: a plus/minus sign, a number and a -letter ([dwmy]) to indicate change in days, weeks, months, or years. With a -single plus or minus, the date is always relative to today. With a -double plus or minus, it is relative to the default date. If instead of -a single letter, you use the abbreviation of day name, the date will be -the Nth such day, e.g.@: - -@example -+0 @result{} today -. @result{} today -+4d @result{} four days from today -+4 @result{} same as above -+2w @result{} two weeks from today -++5 @result{} five days from default date -+2tue @result{} second Tuesday from now. -@end example - -@vindex parse-time-months -@vindex parse-time-weekdays -The function understands English month and weekday abbreviations. If -you want to use unabbreviated names and/or other languages, configure -the variables @code{parse-time-months} and @code{parse-time-weekdays}. - -@vindex org-read-date-force-compatible-dates -Not all dates can be represented in a given Emacs implementation. By default -Org mode forces dates into the compatibility range 1970--2037 which works on -all Emacs implementations. If you want to use dates outside of this range, -read the docstring of the variable -@code{org-read-date-force-compatible-dates}. - -You can specify a time range by giving start and end times or by giving a -start time and a duration (in HH:MM format). Use one or two dash(es) as the -separator in the former case and use '+' as the separator in the latter -case, e.g.@: - -@example -11am-1:15pm @result{} 11:00-13:15 -11am--1:15pm @result{} same as above -11am+2:15 @result{} same as above -@end example - -@cindex calendar, for selecting date -@vindex org-popup-calendar-for-date-prompt -Parallel to the minibuffer prompt, a calendar is popped up@footnote{If -you don't need/want the calendar, configure the variable -@code{org-popup-calendar-for-date-prompt}.}. When you exit the date -prompt, either by clicking on a date in the calendar, or by pressing -@key{RET}, the date selected in the calendar will be combined with the -information entered at the prompt. You can control the calendar fully -from the minibuffer: - -@kindex < -@kindex > -@kindex M-v -@kindex C-v -@kindex mouse-1 -@kindex S-@key{right} -@kindex S-@key{left} -@kindex S-@key{down} -@kindex S-@key{up} -@kindex M-S-@key{right} -@kindex M-S-@key{left} -@kindex @key{RET} -@example -@key{RET} @r{Choose date at cursor in calendar.} -mouse-1 @r{Select date by clicking on it.} -S-@key{right}/@key{left} @r{One day forward/backward.} -S-@key{down}/@key{up} @r{One week forward/backward.} -M-S-@key{right}/@key{left} @r{One month forward/backward.} -> / < @r{Scroll calendar forward/backward by one month.} -M-v / C-v @r{Scroll calendar forward/backward by 3 months.} -@end example - -@vindex org-read-date-display-live -The actions of the date/time prompt may seem complex, but I assure you they -will grow on you, and you will start getting annoyed by pretty much any other -way of entering a date/time out there. To help you understand what is going -on, the current interpretation of your input will be displayed live in the -minibuffer@footnote{If you find this distracting, turn the display of with -@code{org-read-date-display-live}.}. - -@node Custom time format, , The date/time prompt, Creating timestamps -@subsection Custom time format -@cindex custom date/time format -@cindex time format, custom -@cindex date format, custom - -@vindex org-display-custom-times -@vindex org-time-stamp-custom-formats -Org mode uses the standard ISO notation for dates and times as it is -defined in ISO 8601. If you cannot get used to this and require another -representation of date and time to keep you happy, you can get it by -customizing the variables @code{org-display-custom-times} and -@code{org-time-stamp-custom-formats}. - -@table @kbd -@orgcmd{C-c C-x C-t,org-toggle-time-stamp-overlays} -Toggle the display of custom formats for dates and times. -@end table - -@noindent -Org mode needs the default format for scanning, so the custom date/time -format does not @emph{replace} the default format---instead it is put -@emph{over} the default format using text properties. This has the -following consequences: -@itemize @bullet -@item -You cannot place the cursor onto a timestamp anymore, only before or -after. -@item -The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust -each component of a timestamp. If the cursor is at the beginning of -the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day, -just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the -time will be changed by one minute. -@item -If the timestamp contains a range of clock times or a repeater, these -will not be overlaid, but remain in the buffer as they were. -@item -When you delete a timestamp character-by-character, it will only -disappear from the buffer after @emph{all} (invisible) characters -belonging to the ISO timestamp have been removed. -@item -If the custom timestamp format is longer than the default and you are -using dates in tables, table alignment will be messed up. If the custom -format is shorter, things do work as expected. -@end itemize - - -@node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times -@section Deadlines and scheduling - -A timestamp may be preceded by special keywords to facilitate planning: - -@table @var -@item DEADLINE -@cindex DEADLINE keyword - -Meaning: the task (most likely a TODO item, though not necessarily) is supposed -to be finished on that date. - -@vindex org-deadline-warning-days -On the deadline date, the task will be listed in the agenda. In -addition, the agenda for @emph{today} will carry a warning about the -approaching or missed deadline, starting -@code{org-deadline-warning-days} before the due date, and continuing -until the entry is marked DONE. An example: - -@example -*** TODO write article about the Earth for the Guide - DEADLINE: <2004-02-29 Sun> - The editor in charge is [[bbdb:Ford Prefect]] -@end example - -You can specify a different lead time for warnings for a specific -deadlines using the following syntax. Here is an example with a warning -period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. - -@item SCHEDULED -@cindex SCHEDULED keyword - -Meaning: you are planning to start working on that task on the given -date. - -@vindex org-agenda-skip-scheduled-if-done -The headline will be listed under the given date@footnote{It will still -be listed on that date after it has been marked DONE. If you don't like -this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In -addition, a reminder that the scheduled date has passed will be present -in the compilation for @emph{today}, until the entry is marked DONE, i.e.@: -the task will automatically be forwarded until completed. - -@example -*** TODO Call Trillian for a date on New Years Eve. - SCHEDULED: <2004-12-25 Sat> -@end example - -@noindent -@b{Important:} Scheduling an item in Org mode should @i{not} be -understood in the same way that we understand @i{scheduling a meeting}. -Setting a date for a meeting is just a simple appointment, you should -mark this entry with a simple plain timestamp, to get this item shown -on the date where it applies. This is a frequent misunderstanding by -Org users. In Org mode, @i{scheduling} means setting a date when you -want to start working on an action item. -@end table - -You may use timestamps with repeaters in scheduling and deadline -entries. Org mode will issue early and late warnings based on the -assumption that the timestamp represents the @i{nearest instance} of -the repeater. However, the use of diary sexp entries like -@c -@code{<%%(org-float t 42)>} -@c -in scheduling and deadline timestamps is limited. Org mode does not -know enough about the internals of each sexp function to issue early and -late warnings. However, it will show the item on each day where the -sexp entry matches. - -@menu -* Inserting deadline/schedule:: Planning items -* Repeated tasks:: Items that show up again and again -@end menu - -@node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling -@subsection Inserting deadlines or schedules - -The following commands allow you to quickly insert@footnote{The @samp{SCHEDULED} and -@samp{DEADLINE} dates are inserted on the line right below the headline. Don't put -any text between this line and the headline.} a deadline or to schedule -an item: - -@table @kbd -@c -@orgcmd{C-c C-d,org-deadline} -Insert @samp{DEADLINE} keyword along with a stamp. The insertion will happen -in the line directly following the headline. Any CLOSED timestamp will be -removed. When called with a prefix arg, an existing deadline will be removed -from the entry. Depending on the variable @code{org-log-redeadline}@footnote{with corresponding -@code{#+STARTUP} keywords @code{logredeadline}, @code{lognoteredeadline}, -and @code{nologredeadline}}, a note will be taken when changing an existing -deadline. - -@orgcmd{C-c C-s,org-schedule} -Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will -happen in the line directly following the headline. Any CLOSED timestamp -will be removed. When called with a prefix argument, remove the scheduling -date from the entry. Depending on the variable -@code{org-log-reschedule}@footnote{with corresponding @code{#+STARTUP} -keywords @code{logreschedule}, @code{lognotereschedule}, and -@code{nologreschedule}}, a note will be taken when changing an existing -scheduling time. -@c -@orgcmd{C-c C-x C-k,org-mark-entry-for-agenda-action} -@kindex k a -@kindex k s -Mark the current entry for agenda action. After you have marked the entry -like this, you can open the agenda or the calendar to find an appropriate -date. With the cursor on the selected date, press @kbd{k s} or @kbd{k d} to -schedule the marked item. -@c -@orgcmd{C-c / d,org-check-deadlines} -@cindex sparse tree, for deadlines -@vindex org-deadline-warning-days -Create a sparse tree with all deadlines that are either past-due, or -which will become due within @code{org-deadline-warning-days}. -With @kbd{C-u} prefix, show all deadlines in the file. With a numeric -prefix, check that many days. For example, @kbd{C-1 C-c / d} shows -all deadlines due tomorrow. -@c -@orgcmd{C-c / b,org-check-before-date} -Sparse tree for deadlines and scheduled items before a given date. -@c -@orgcmd{C-c / a,org-check-after-date} -Sparse tree for deadlines and scheduled items after a given date. -@end table - -Note that @code{org-schedule} and @code{org-deadline} supports -setting the date by indicating a relative time: e.g. +1d will set -the date to the next day after today, and --1w will set the date -to the previous week before any current timestamp. - -@node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling -@subsection Repeated tasks -@cindex tasks, repeated -@cindex repeated tasks - -Some tasks need to be repeated again and again. Org mode helps to -organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, -or plain timestamp. In the following example -@example -** TODO Pay the rent - DEADLINE: <2005-10-01 Sat +1m> -@end example -@noindent -the @code{+1m} is a repeater; the intended interpretation is that the task -has a deadline on <2005-10-01> and repeats itself every (one) month starting -from that time. If you need both a repeater and a special warning period in -a deadline entry, the repeater should come first and the warning period last: -@code{DEADLINE: <2005-10-01 Sat +1m -3d>}. - -@vindex org-todo-repeat-to-state -Deadlines and scheduled items produce entries in the agenda when they are -over-due, so it is important to be able to mark such an entry as completed -once you have done so. When you mark a DEADLINE or a SCHEDULE with the TODO -keyword DONE, it will no longer produce entries in the agenda. The problem -with this is, however, that then also the @emph{next} instance of the -repeated entry will not be active. Org mode deals with this in the following -way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will -shift the base date of the repeating timestamp by the repeater interval, and -immediately set the entry state back to TODO@footnote{In fact, the target -state is taken from, in this sequence, the @code{REPEAT_TO_STATE} property or -the variable @code{org-todo-repeat-to-state}. If neither of these is -specified, the target state defaults to the first state of the TODO state -sequence.}. In the example above, setting the state to DONE would actually -switch the date like this: - -@example -** TODO Pay the rent - DEADLINE: <2005-11-01 Tue +1m> -@end example - -@vindex org-log-repeat -A timestamp@footnote{You can change this using the option -@code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat}, -@code{lognoterepeat}, and @code{nologrepeat}. With @code{lognoterepeat}, you -will also be prompted for a note.} will be added under the deadline, to keep -a record that you actually acted on the previous instance of this deadline. - -As a consequence of shifting the base date, this entry will no longer be -visible in the agenda when checking past dates, but all future instances -will be visible. - -With the @samp{+1m} cookie, the date shift will always be exactly one -month. So if you have not paid the rent for three months, marking this -entry DONE will still keep it as an overdue deadline. Depending on the -task, this may not be the best way to handle it. For example, if you -forgot to call your father for 3 weeks, it does not make sense to call -him 3 times in a single day to make up for it. Finally, there are tasks -like changing batteries which should always repeat a certain time -@i{after} the last time you did it. For these tasks, Org mode has -special repeaters @samp{++} and @samp{.+}. For example: - -@example -** TODO Call Father - DEADLINE: <2008-02-10 Sun ++1w> - Marking this DONE will shift the date by at least one week, - but also by as many weeks as it takes to get this date into - the future. However, it stays on a Sunday, even if you called - and marked it done on Saturday. -** TODO Check the batteries in the smoke detectors - DEADLINE: <2005-11-01 Tue .+1m> - Marking this DONE will shift the date to one month after - today. -@end example - -You may have both scheduling and deadline information for a specific -task---just make sure that the repeater intervals on both are the same. - -An alternative to using a repeater is to create a number of copies of a task -subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was -created for this purpose, it is described in @ref{Structure editing}. - - -@node Clocking work time, Effort estimates, Deadlines and scheduling, Dates and Times -@section Clocking work time -@cindex clocking time -@cindex time clocking - -Org mode allows you to clock the time you spend on specific tasks in a -project. When you start working on an item, you can start the clock. -When you stop working on that task, or when you mark the task done, the -clock is stopped and the corresponding time interval is recorded. It -also computes the total time spent on each subtree of a project. And it -remembers a history or tasks recently clocked, to that you can jump quickly -between a number of tasks absorbing your time. - -To save the clock history across Emacs sessions, use -@lisp -(setq org-clock-persist 'history) -(org-clock-persistence-insinuate) -@end lisp -When you clock into a new task after resuming Emacs, the incomplete -clock@footnote{To resume the clock under the assumption that you have worked -on this task while outside Emacs, use @code{(setq org-clock-persist t)}.} -will be found (@pxref{Resolving idle time}) and you will be prompted about -what to do with it. - -@menu -* Clocking commands:: Starting and stopping a clock -* The clock table:: Detailed reports -* Resolving idle time:: Resolving time when you've been idle -@end menu - -@node Clocking commands, The clock table, Clocking work time, Clocking work time -@subsection Clocking commands - -@table @kbd -@orgcmd{C-c C-x C-i,org-clock-in} -@vindex org-clock-into-drawer -@cindex property, LOG_INTO_DRAWER -Start the clock on the current item (clock-in). This inserts the CLOCK -keyword together with a timestamp. If this is not the first clocking of -this item, the multiple CLOCK lines will be wrapped into a -@code{:LOGBOOK:} drawer (see also the variable -@code{org-clock-into-drawer}). You can also overrule -the setting of this variable for a subtree by setting a -@code{CLOCK_INTO_DRAWER} or @code{LOG_INTO_DRAWER} property. -When called with a @kbd{C-u} prefix argument, -select the task from a list of recently clocked tasks. With two @kbd{C-u -C-u} prefixes, clock into the task at point and mark it as the default task. -The default task will always be available when selecting a clocking task, -with letter @kbd{d}.@* -@cindex property: CLOCK_MODELINE_TOTAL -@cindex property: LAST_REPEAT -@vindex org-clock-modeline-total -While the clock is running, the current clocking time is shown in the mode -line, along with the title of the task. The clock time shown will be all -time ever clocked for this task and its children. If the task has an effort -estimate (@pxref{Effort estimates}), the mode line displays the current -clocking time against it@footnote{To add an effort estimate ``on the fly'', -hook a function doing this to @code{org-clock-in-prepare-hook}.} If the task -is a repeating one (@pxref{Repeated tasks}), only the time since the last -reset of the task @footnote{as recorded by the @code{LAST_REPEAT} property} -will be shown. More control over what time is shown can be exercised with -the @code{CLOCK_MODELINE_TOTAL} property. It may have the values -@code{current} to show only the current clocking instance, @code{today} to -show all time clocked on this tasks today (see also the variable -@code{org-extend-today-until}), @code{all} to include all time, or -@code{auto} which is the default@footnote{See also the variable -@code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the -mode line entry will pop up a menu with clocking options. -@c -@orgcmd{C-c C-x C-o,org-clock-out} -@vindex org-log-note-clock-out -Stop the clock (clock-out). This inserts another timestamp at the same -location where the clock was last started. It also directly computes -the resulting time in inserts it after the time range as @samp{=> -HH:MM}. See the variable @code{org-log-note-clock-out} for the -possibility to record an additional note together with the clock-out -timestamp@footnote{The corresponding in-buffer setting is: -@code{#+STARTUP: lognoteclock-out}}. -@orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate} -Update the effort estimate for the current clock task. -@kindex C-c C-y -@kindex C-c C-c -@orgcmdkkc{C-c C-c,C-c C-y,org-evaluate-time-range} -Recompute the time interval after changing one of the timestamps. This -is only necessary if you edit the timestamps directly. If you change -them with @kbd{S-@key{cursor}} keys, the update is automatic. -@orgcmd{C-S-@key{up/down},org-clock-timestamps-up/down} -On @code{CLOCK} log lines, increase/decrease both timestamps at the same -time so that duration keeps the same. -@orgcmd{C-c C-t,org-todo} -Changing the TODO state of an item to DONE automatically stops the clock -if it is running in this same item. -@orgcmd{C-c C-x C-x,org-clock-cancel} -Cancel the current clock. This is useful if a clock was started by -mistake, or if you ended up working on something else. -@orgcmd{C-c C-x C-j,org-clock-goto} -Jump to the headline of the currently clocked in task. With a @kbd{C-u} -prefix arg, select the target task from a list of recently clocked tasks. -@orgcmd{C-c C-x C-d,org-clock-display} -@vindex org-remove-highlights-with-change -Display time summaries for each subtree in the current buffer. This puts -overlays at the end of each headline, showing the total time recorded under -that heading, including the time of any subheadings. You can use visibility -cycling to study the tree, but the overlays disappear when you change the -buffer (see variable @code{org-remove-highlights-with-change}) or press -@kbd{C-c C-c}. -@end table - -The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in -the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been -worked on or closed during a day. - -@node The clock table, Resolving idle time, Clocking commands, Clocking work time -@subsection The clock table -@cindex clocktable, dynamic block -@cindex report, of clocked time - -Org mode can produce quite complex reports based on the time clocking -information. Such a report is called a @emph{clock table}, because it is -formatted as one or several Org tables. - -@table @kbd -@orgcmd{C-c C-x C-r,org-clock-report} -Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock -report as an Org mode table into the current file. When the cursor is -at an existing clock table, just update it. When called with a prefix -argument, jump to the first clock report in the current document and -update it. The clock table always includes also trees with -@code{:ARCHIVE:} tag. -@orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update} -Update dynamic block at point. The cursor needs to be in the -@code{#+BEGIN} line of the dynamic block. -@orgkey{C-u C-c C-x C-u} -Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if -you have several clock table blocks in a buffer. -@orgcmdkxkc{S-@key{left},S-@key{right},org-clocktable-try-shift} -Shift the current @code{:block} interval and update the table. The cursor -needs to be in the @code{#+BEGIN: clocktable} line for this command. If -@code{:block} is @code{today}, it will be shifted to @code{today-1} etc. -@end table - - -Here is an example of the frame for a clock table as it is inserted into the -buffer with the @kbd{C-c C-x C-r} command: - -@cindex #+BEGIN, clocktable -@example -#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file -#+END: clocktable -@end example -@noindent -@vindex org-clocktable-defaults -The @samp{BEGIN} line and specify a number of options to define the scope, -structure, and formatting of the report. Defaults for all these options can -be configured in the variable @code{org-clocktable-defaults}. - -@noindent First there are options that determine which clock entries are to -be selected: -@example -:maxlevel @r{Maximum level depth to which times are listed in the table.} - @r{Clocks at deeper levels will be summed into the upper level.} -:scope @r{The scope to consider. This can be any of the following:} - nil @r{the current buffer or narrowed region} - file @r{the full current buffer} - subtree @r{the subtree where the clocktable is located} - tree@var{N} @r{the surrounding level @var{N} tree, for example @code{tree3}} - tree @r{the surrounding level 1 tree} - agenda @r{all agenda files} - ("file"..) @r{scan these files} - file-with-archives @r{current file and its archives} - agenda-with-archives @r{all agenda files, including archives} -:block @r{The time block to consider. This block is specified either} - @r{absolute, or relative to the current time and may be any of} - @r{these formats:} - 2007-12-31 @r{New year eve 2007} - 2007-12 @r{December 2007} - 2007-W50 @r{ISO-week 50 in 2007} - 2007-Q2 @r{2nd quarter in 2007} - 2007 @r{the year 2007} - today, yesterday, today-@var{N} @r{a relative day} - thisweek, lastweek, thisweek-@var{N} @r{a relative week} - thismonth, lastmonth, thismonth-@var{N} @r{a relative month} - thisyear, lastyear, thisyear-@var{N} @r{a relative year} - @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.} -:tstart @r{A time string specifying when to start considering times.} -:tend @r{A time string specifying when to stop considering times.} -:step @r{@code{week} or @code{day}, to split the table into chunks.} - @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.} -:stepskip0 @r{Do not show steps that have zero time.} -:fileskip0 @r{Do not show table sections from files which did not contribute.} -:tags @r{A tags match to select entries that should contribute. See} - @r{@ref{Matching tags and properties} for the match syntax.} -@end example - -Then there are options which determine the formatting of the table. There -options are interpreted by the function @code{org-clocktable-write-default}, -but you can specify your own function using the @code{:formatter} parameter. -@example -:emphasize @r{When @code{t}, emphasize level one and level two items.} -:lang @r{Language@footnote{Language terms can be set through the variable @code{org-clock-clocktable-language-setup}.} to use for descriptive cells like "Task".} -:link @r{Link the item headlines in the table to their origins.} -:narrow @r{An integer to limit the width of the headline column in} - @r{the org table. If you write it like @samp{50!}, then the} - @r{headline will also be shortened in export.} -:indent @r{Indent each headline field according to its level.} -:tcolumns @r{Number of columns to be used for times. If this is smaller} - @r{than @code{:maxlevel}, lower levels will be lumped into one column.} -:level @r{Should a level number column be included?} -:compact @r{Abbreviation for @code{:level nil :indent t :narrow 40! :tcolumns 1}} - @r{All are overwritten except if there is an explicit @code{:narrow}} -:timestamp @r{A timestamp for the entry, when available. Look for SCHEDULED,} - @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.} -:properties @r{List of properties that should be shown in the table. Each} - @r{property will get its own column.} -:inherit-props @r{When this flag is @code{t}, the values for @code{:properties} will be inherited.} -:formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.} - @r{As a special case, @samp{:formula %} adds a column with % time.} - @r{If you do not specify a formula here, any existing formula} - @r{below the clock table will survive updates and be evaluated.} -:formatter @r{A function to format clock data and insert it into the buffer.} -@end example -To get a clock summary of the current level 1 tree, for the current -day, you could write -@example -#+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t -#+END: clocktable -@end example -@noindent -and to use a specific time range you could write@footnote{Note that all -parameters must be specified in a single line---the line is broken here -only to fit it into the manual.} -@example -#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>" - :tend "<2006-08-10 Thu 12:00>" -#+END: clocktable -@end example -A summary of the current subtree with % times would be -@example -#+BEGIN: clocktable :scope subtree :link t :formula % -#+END: clocktable -@end example -A horizontally compact representation of everything clocked during last week -would be -@example -#+BEGIN: clocktable :scope agenda :block lastweek :compact t -#+END: clocktable -@end example - -@node Resolving idle time, , The clock table, Clocking work time -@subsection Resolving idle time -@cindex resolve idle time - -@cindex idle, resolve, dangling -If you clock in on a work item, and then walk away from your -computer---perhaps to take a phone call---you often need to ``resolve'' the -time you were away by either subtracting it from the current clock, or -applying it to another one. - -@vindex org-clock-idle-time -By customizing the variable @code{org-clock-idle-time} to some integer, such -as 10 or 15, Emacs can alert you when you get back to your computer after -being idle for that many minutes@footnote{On computers using Mac OS X, -idleness is based on actual user idleness, not just Emacs' idle time. For -X11, you can install a utility program @file{x11idle.c}, available in the -UTILITIES directory of the Org git distribution, to get the same general -treatment of idleness. On other systems, idle time refers to Emacs idle time -only.}, and ask what you want to do with the idle time. There will be a -question waiting for you when you get back, indicating how much idle time has -passed (constantly updated with the current amount), as well as a set of -choices to correct the discrepancy: - -@table @kbd -@item k -To keep some or all of the minutes and stay clocked in, press @kbd{k}. Org -will ask how many of the minutes to keep. Press @key{RET} to keep them all, -effectively changing nothing, or enter a number to keep that many minutes. -@item K -If you use the shift key and press @kbd{K}, it will keep however many minutes -you request and then immediately clock out of that task. If you keep all of -the minutes, this is the same as just clocking out of the current task. -@item s -To keep none of the minutes, use @kbd{s} to subtract all the away time from -the clock, and then check back in from the moment you returned. -@item S -To keep none of the minutes and just clock out at the start of the away time, -use the shift key and press @kbd{S}. Remember that using shift will always -leave you clocked out, no matter which option you choose. -@item C -To cancel the clock altogether, use @kbd{C}. Note that if instead of -canceling you subtract the away time, and the resulting clock amount is less -than a minute, the clock will still be canceled rather than clutter up the -log with an empty entry. -@end table - -What if you subtracted those away minutes from the current clock, and now -want to apply them to a new clock? Simply clock in to any task immediately -after the subtraction. Org will notice that you have subtracted time ``on -the books'', so to speak, and will ask if you want to apply those minutes to -the next task you clock in on. - -There is one other instance when this clock resolution magic occurs. Say you -were clocked in and hacking away, and suddenly your cat chased a mouse who -scared a hamster that crashed into your UPS's power button! You suddenly -lose all your buffers, but thanks to auto-save you still have your recent Org -mode changes, including your last clock in. - -If you restart Emacs and clock into any task, Org will notice that you have a -dangling clock which was never clocked out from your last session. Using -that clock's starting time as the beginning of the unaccounted-for period, -Org will ask how you want to resolve that time. The logic and behavior is -identical to dealing with away time due to idleness; it is just happening due -to a recovery event rather than a set amount of idle time. - -You can also check all the files visited by your Org agenda for dangling -clocks at any time using @kbd{M-x org-resolve-clocks}. - -@node Effort estimates, Relative timer, Clocking work time, Dates and Times -@section Effort estimates -@cindex effort estimates - -@cindex property, Effort -@vindex org-effort-property -If you want to plan your work in a very detailed way, or if you need to -produce offers with quotations of the estimated work effort, you may want to -assign effort estimates to entries. If you are also clocking your work, you -may later want to compare the planned effort with the actual working time, a -great way to improve planning estimates. Effort estimates are stored in a -special property @samp{Effort}@footnote{You may change the property being -used with the variable @code{org-effort-property}.}. You can set the effort -for an entry with the following commands: - -@table @kbd -@orgcmd{C-c C-x e,org-set-effort} -Set the effort estimate for the current entry. With a numeric prefix -argument, set it to the Nth allowed value (see below). This command is also -accessible from the agenda with the @kbd{e} key. -@orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate} -Modify the effort estimate of the item currently being clocked. -@end table - -Clearly the best way to work with effort estimates is through column view -(@pxref{Column view}). You should start by setting up discrete values for -effort estimates, and a @code{COLUMNS} format that displays these values -together with clock sums (if you want to clock your time). For a specific -buffer you can use - -@example -#+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00 -#+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM -@end example - -@noindent -@vindex org-global-properties -@vindex org-columns-default-format -or, even better, you can set up these values globally by customizing the -variables @code{org-global-properties} and @code{org-columns-default-format}. -In particular if you want to use this setup also in the agenda, a global -setup may be advised. - -The way to assign estimates to individual items is then to switch to column -mode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change the -value. The values you enter will immediately be summed up in the hierarchy. -In the column next to it, any clocked time will be displayed. - -@vindex org-agenda-columns-add-appointments-to-effort-sum -If you switch to column view in the daily/weekly agenda, the effort column -will summarize the estimated work effort for each day@footnote{Please note -the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda -column view}).}, and you can use this to find space in your schedule. To get -an overview of the entire part of the day that is committed, you can set the -option @code{org-agenda-columns-add-appointments-to-effort-sum}. The -appointments on a day that take place over a specified time interval will -then also be added to the load estimate of the day. - -Effort estimates can be used in secondary agenda filtering that is triggered -with the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you have -these estimates defined consistently, two or three key presses will narrow -down the list to stuff that fits into an available time slot. - -@node Relative timer, Countdown timer, Effort estimates, Dates and Times -@section Taking notes with a relative timer -@cindex relative timer - -When taking notes during, for example, a meeting or a video viewing, it can -be useful to have access to times relative to a starting time. Org provides -such a relative timer and make it easy to create timed notes. - -@table @kbd -@orgcmd{C-c C-x .,org-timer} -Insert a relative time into the buffer. The first time you use this, the -timer will be started. When called with a prefix argument, the timer is -restarted. -@orgcmd{C-c C-x -,org-timer-item} -Insert a description list item with the current relative time. With a prefix -argument, first reset the timer to 0. -@orgcmd{M-@key{RET},org-insert-heading} -Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert -new timer items. -@c for key sequences with a comma, command name macros fail :( -@kindex C-c C-x , -@item C-c C-x , -Pause the timer, or continue it if it is already paused -(@command{org-timer-pause-or-continue}). -@c removed the sentence because it is redundant to the following item -@kindex C-u C-c C-x , -@item C-u C-c C-x , -Stop the timer. After this, you can only start a new timer, not continue the -old one. This command also removes the timer from the mode line. -@orgcmd{C-c C-x 0,org-timer-start} -Reset the timer without inserting anything into the buffer. By default, the -timer is reset to 0. When called with a @kbd{C-u} prefix, reset the timer to -specific starting offset. The user is prompted for the offset, with a -default taken from a timer string at point, if any, So this can be used to -restart taking notes after a break in the process. When called with a double -prefix argument @kbd{C-u C-u}, change all timer strings in the active region -by a certain amount. This can be used to fix timer strings if the timer was -not started at exactly the right moment. -@end table - -@node Countdown timer, , Relative timer, Dates and Times -@section Countdown timer -@cindex Countdown timer -@kindex C-c C-x ; -@kindex ; - -Calling @code{org-timer-set-timer} from an Org mode buffer runs a countdown -timer. Use @kbd{;} from agenda buffers, @key{C-c C-x ;} everywhere else. - -@code{org-timer-set-timer} prompts the user for a duration and displays a -countdown timer in the modeline. @code{org-timer-default-timer} sets the -default countdown value. Giving a prefix numeric argument overrides this -default value. - -@node Capture - Refile - Archive, Agenda Views, Dates and Times, Top -@chapter Capture - Refile - Archive -@cindex capture - -An important part of any organization system is the ability to quickly -capture new ideas and tasks, and to associate reference material with them. -Org does this using a process called @i{capture}. It also can store files -related to a task (@i{attachments}) in a special directory. Once in the -system, tasks and projects need to be moved around. Moving completed project -trees to an archive file keeps the system compact and fast. - -@menu -* Capture:: Capturing new stuff -* Attachments:: Add files to tasks -* RSS Feeds:: Getting input from RSS feeds -* Protocols:: External (e.g.@: Browser) access to Emacs and Org -* Refiling notes:: Moving a tree from one place to another -* Archiving:: What to do with finished projects -@end menu - -@node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive -@section Capture -@cindex capture - -Org's method for capturing new items is heavily inspired by John Wiegley -excellent remember package. Up to version 6.36 Org used a special setup -for @file{remember.el}. @file{org-remember.el} is still part of Org mode for -backward compatibility with existing setups. You can find the documentation -for org-remember at @url{http://orgmode.org/org-remember.pdf}. - -The new capturing setup described here is preferred and should be used by new -users. To convert your @code{org-remember-templates}, run the command -@example -@kbd{M-x org-capture-import-remember-templates @key{RET}} -@end example -@noindent and then customize the new variable with @kbd{M-x -customize-variable org-capture-templates}, check the result, and save the -customization. You can then use both remember and capture until -you are familiar with the new mechanism. - -Capture lets you quickly store notes with little interruption of your work -flow. The basic process of capturing is very similar to remember, but Org -does enhance it with templates and more. - -@menu -* Setting up capture:: Where notes will be stored -* Using capture:: Commands to invoke and terminate capture -* Capture templates:: Define the outline of different note types -@end menu - -@node Setting up capture, Using capture, Capture, Capture -@subsection Setting up capture - -The following customization sets a default target file for notes, and defines -a global key@footnote{Please select your own key, @kbd{C-c c} is only a -suggestion.} for capturing new material. - -@vindex org-default-notes-file -@example -(setq org-default-notes-file (concat org-directory "/notes.org")) -(define-key global-map "\C-cc" 'org-capture) -@end example - -@node Using capture, Capture templates, Setting up capture, Capture -@subsection Using capture - -@table @kbd -@orgcmd{C-c c,org-capture} -Call the command @code{org-capture}. Note that this keybinding is global and -not active by default - you need to install it. If you have templates -@cindex date tree -defined @pxref{Capture templates}, it will offer these templates for -selection or use a new Org outline node as the default template. It will -insert the template into the target file and switch to an indirect buffer -narrowed to this new node. You may then insert the information you want. - -@orgcmd{C-c C-c,org-capture-finalize} -Once you have finished entering information into the capture buffer, @kbd{C-c -C-c} will return you to the window configuration before the capture process, -so that you can resume your work without further distraction. When called -with a prefix arg, finalize and then jump to the captured item. - -@orgcmd{C-c C-w,org-capture-refile} -Finalize the capture process by refiling (@pxref{Refiling notes}) the note to -a different place. Please realize that this is a normal refiling command -that will be executed---so the cursor position at the moment you run this -command is important. If you have inserted a tree with a parent and -children, first move the cursor back to the parent. Any prefix argument -given to this command will be passed on to the @code{org-refile} command. - -@orgcmd{C-c C-k,org-capture-kill} -Abort the capture process and return to the previous state. - -@end table - -You can also call @code{org-capture} in a special way from the agenda, using -the @kbd{k c} key combination. With this access, any timestamps inserted by -the selected capture template will default to the cursor date in the agenda, -rather than to the current date. - -To find the locations of the last stored capture, use @code{org-capture} with -prefix commands: - -@table @kbd -@orgkey{C-u C-c c} -Visit the target location of a capture template. You get to select the -template in the usual way. -@orgkey{C-u C-u C-c c} -Visit the last stored capture item in its buffer. -@end table - -@node Capture templates, , Using capture, Capture -@subsection Capture templates -@cindex templates, for Capture - -You can use templates for different types of capture items, and -for different target locations. The easiest way to create such templates is -through the customize interface. - -@table @kbd -@orgkey{C-c c C} -Customize the variable @code{org-capture-templates}. -@end table - -Before we give the formal description of template definitions, let's look at -an example. Say you would like to use one template to create general TODO -entries, and you want to put these entries under the heading @samp{Tasks} in -your file @file{~/org/gtd.org}. Also, a date tree in the file -@file{journal.org} should capture journal entries. A possible configuration -would look like: - -@example -(setq org-capture-templates - '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") - "* TODO %?\n %i\n %a") - ("j" "Journal" entry (file+datetree "~/org/journal.org") - "* %?\nEntered on %U\n %i\n %a"))) -@end example - -@noindent If you then press @kbd{C-c c t}, Org will prepare the template -for you like this: -@example -* TODO - [[file:@var{link to where you initiated capture}]] -@end example - -@noindent -During expansion of the template, @code{%a} has been replaced by a link to -the location from where you called the capture command. This can be -extremely useful for deriving tasks from emails, for example. You fill in -the task definition, press @code{C-c C-c} and Org returns you to the same -place where you started the capture process. - -To define special keys to capture to a particular template without going -through the interactive template selection, you can create your key binding -like this: - -@lisp -(define-key global-map "\C-cx" - (lambda () (interactive) (org-capture nil "x"))) -@end lisp - -@menu -* Template elements:: What is needed for a complete template entry -* Template expansion:: Filling in information about time and context -@end menu - -@node Template elements, Template expansion, Capture templates, Capture templates -@subsubsection Template elements - -Now lets look at the elements of a template definition. Each entry in -@code{org-capture-templates} is a list with the following items: - -@table @var -@item keys -The keys that will select the template, as a string, characters -only, for example @code{"a"} for a template to be selected with a -single key, or @code{"bt"} for selection with two keys. When using -several keys, keys using the same prefix key must be sequential -in the list and preceded by a 2-element entry explaining the -prefix key, for example -@example - ("b" "Templates for marking stuff to buy") -@end example -@noindent If you do not define a template for the @kbd{C} key, this key will -be used to open the customize buffer for this complex variable. - -@item description -A short string describing the template, which will be shown during -selection. - -@item type -The type of entry, a symbol. Valid values are: -@table @code -@item entry -An Org mode node, with a headline. Will be filed as the child of the target -entry or as a top-level entry. The target file should be an Org mode file. -@item item -A plain list item, placed in the first plain list at the target -location. Again the target file should be an Org file. -@item checkitem -A checkbox item. This only differs from the plain list item by the -default template. -@item table-line -a new line in the first table at the target location. Where exactly the -line will be inserted depends on the properties @code{:prepend} and -@code{:table-line-pos} (see below). -@item plain -Text to be inserted as it is. -@end table - -@item target -@vindex org-default-notes-file -Specification of where the captured item should be placed. In Org mode -files, targets usually define a node. Entries will become children of this -node. Other types will be added to the table or list in the body of this -node. Most target specifications contain a file name. If that file name is -the empty string, it defaults to @code{org-default-notes-file}. A file can -also be given as a variable, function, or Emacs Lisp form. - -Valid values are: -@table @code -@item (file "path/to/file") -Text will be placed at the beginning or end of that file. - -@item (id "id of existing org entry") -Filing as child of this entry, or in the body of the entry. - -@item (file+headline "path/to/file" "node headline") -Fast configuration if the target heading is unique in the file. - -@item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...) -For non-unique headings, the full path is safer. - -@item (file+regexp "path/to/file" "regexp to find location") -Use a regular expression to position the cursor. - -@item (file+datetree "path/to/file") -Will create a heading in a date tree for today's date. - -@item (file+datetree+prompt "path/to/file") -Will create a heading in a date tree, but will prompt for the date. - -@item (file+function "path/to/file" function-finding-location) -A function to find the right location in the file. - -@item (clock) -File to the entry that is currently being clocked. - -@item (function function-finding-location) -Most general way, write your own function to find both -file and location. -@end table - -@item template -The template for creating the capture item. If you leave this empty, an -appropriate default template will be used. Otherwise this is a string with -escape codes, which will be replaced depending on time and context of the -capture call. The string with escapes may be loaded from a template file, -using the special syntax @code{(file "path/to/template")}. See below for -more details. - -@item properties -The rest of the entry is a property list of additional options. -Recognized properties are: -@table @code -@item :prepend -Normally new captured information will be appended at -the target location (last child, last table line, last list item...). -Setting this property will change that. - -@item :immediate-finish -When set, do not offer to edit the information, just -file it away immediately. This makes sense if the template only needs -information that can be added automatically. - -@item :empty-lines -Set this to the number of lines to insert -before and after the new item. Default 0, only common other value is 1. - -@item :clock-in -Start the clock in this item. - -@item :clock-keep -Keep the clock running when filing the captured entry. - -@item :clock-resume -If starting the capture interrupted a clock, restart that clock when finished -with the capture. Note that @code{:clock-keep} has precedence over -@code{:clock-resume}. When setting both to @code{t}, the current clock will -run and the previous one will not be resumed. - -@item :unnarrowed -Do not narrow the target buffer, simply show the full buffer. Default is to -narrow it so that you only see the new material. - -@item :table-line-pos -Specification of the location in the table where the new line should be -inserted. It should be a string like @code{"II-3"} meaning that the new -line should become the third line before the second horizontal separator -line. - -@item :kill-buffer -If the target file was not yet visited when capture was invoked, kill the -buffer again after capture is completed. -@end table -@end table - -@node Template expansion, , Template elements, Capture templates -@subsubsection Template expansion - -In the template itself, special @kbd{%}-escapes@footnote{If you need one of -these sequences literally, escape the @kbd{%} with a backslash.} allow -dynamic insertion of content. The templates are expanded in the order given here: - -@smallexample -%[@var{file}] @r{insert the contents of the file given by @var{file}.} -%(@var{sexp}) @r{evaluate Elisp @var{sexp} and replace with the result.} -%<...> @r{the result of format-time-string on the ... format specification.} -%t @r{timestamp, date only.} -%T @r{timestamp with date and time.} -%u, %U @r{like the above, but inactive timestamps.} -%a @r{annotation, normally the link created with @code{org-store-link}.} -%i @r{initial content, the region when capture is called while the} - @r{region is active.} - @r{The entire text will be indented like @code{%i} itself.} -%A @r{like @code{%a}, but prompt for the description part.} -%c @r{Current kill ring head.} -%x @r{Content of the X clipboard.} -%k @r{title of the currently clocked task.} -%K @r{link to the currently clocked task.} -%n @r{user name (taken from @code{user-full-name}).} -%f @r{file visited by current buffer when org-capture was called.} -%F @r{full path of the file or directory visited by current buffer.} -%:keyword @r{specific information for certain link types, see below.} -%^g @r{prompt for tags, with completion on tags in target file.} -%^G @r{prompt for tags, with completion all tags in all agenda files.} -%^t @r{like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}.} - @r{You may define a prompt like @code{%^@{Birthday@}t}.} -%^C @r{Interactive selection of which kill or clip to use.} -%^L @r{Like @code{%^C}, but insert as link.} -%^@{@var{prop}@}p @r{Prompt the user for a value for property @var{prop}.} -%^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.} - @r{You may specify a default value and a completion table with} - @r{%^@{prompt|default|completion2|completion3...@}.} - @r{The arrow keys access a prompt-specific history.} -@end smallexample - -@noindent -For specific link types, the following keywords will be -defined@footnote{If you define your own link types (@pxref{Adding -hyperlink types}), any property you store with -@code{org-store-link-props} can be accessed in capture templates in a -similar way.}: - -@vindex org-from-is-user-regexp -@smallexample -Link type | Available keywords -------------------------+---------------------------------------------- -bbdb | %:name %:company -irc | %:server %:port %:nick -vm, wl, mh, mew, rmail | %:type %:subject %:message-id - | %:from %:fromname %:fromaddress - | %:to %:toname %:toaddress - | %:date @r{(message date header field)} - | %:date-timestamp @r{(date as active timestamp)} - | %:date-timestamp-inactive @r{(date as inactive timestamp)} - | %:fromto @r{(either "to NAME" or "from NAME")@footnote{This will always be the other, not the user. See the variable @code{org-from-is-user-regexp}.}} -gnus | %:group, @r{for messages also all email fields} -w3, w3m | %:url -info | %:file %:node -calendar | %:date -@end smallexample - -@noindent -To place the cursor after template expansion use: - -@smallexample -%? @r{After completing the template, position cursor here.} -@end smallexample - - -@node Attachments, RSS Feeds, Capture, Capture - Refile - Archive -@section Attachments -@cindex attachments - -@vindex org-attach-directory -It is often useful to associate reference material with an outline node/task. -Small chunks of plain text can simply be stored in the subtree of a project. -Hyperlinks (@pxref{Hyperlinks}) can establish associations with -files that live elsewhere on your computer or in the cloud, like emails or -source code files belonging to a project. Another method is @i{attachments}, -which are files located in a directory belonging to an outline node. Org -uses directories named by the unique ID of each entry. These directories are -located in the @file{data} directory which lives in the same directory where -your Org file lives@footnote{If you move entries or Org files from one -directory to another, you may want to configure @code{org-attach-directory} -to contain an absolute path.}. If you initialize this directory with -@code{git init}, Org will automatically commit changes when it sees them. -The attachment system has been contributed to Org by John Wiegley. - -In cases where it seems better to do so, you can also attach a directory of your -choice to an entry. You can also make children inherit the attachment -directory from a parent, so that an entire subtree uses the same attached -directory. - -@noindent The following commands deal with attachments: - -@table @kbd - -@orgcmd{C-c C-a,org-attach} -The dispatcher for commands related to the attachment system. After these -keys, a list of commands is displayed and you must press an additional key -to select a command: - -@table @kbd -@orgcmdtkc{a,C-c C-a a,org-attach-attach} -@vindex org-attach-method -Select a file and move it into the task's attachment directory. The file -will be copied, moved, or linked, depending on @code{org-attach-method}. -Note that hard links are not supported on all systems. - -@kindex C-c C-a c -@kindex C-c C-a m -@kindex C-c C-a l -@item c/m/l -Attach a file using the copy/move/link method. -Note that hard links are not supported on all systems. - -@orgcmdtkc{n,C-c C-a n,org-attach-new} -Create a new attachment as an Emacs buffer. - -@orgcmdtkc{z,C-c C-a z,org-attach-sync} -Synchronize the current task with its attachment directory, in case you added -attachments yourself. - -@orgcmdtkc{o,C-c C-a o,org-attach-open} -@vindex org-file-apps -Open current task's attachment. If there is more than one, prompt for a -file name first. Opening will follow the rules set by @code{org-file-apps}. -For more details, see the information on following hyperlinks -(@pxref{Handling links}). - -@orgcmdtkc{O,C-c C-a O,org-attach-open-in-emacs} -Also open the attachment, but force opening the file in Emacs. - -@orgcmdtkc{f,C-c C-a f,org-attach-reveal} -Open the current task's attachment directory. - -@orgcmdtkc{F,C-c C-a F,org-attach-reveal-in-emacs} -Also open the directory, but force using @command{dired} in Emacs. - -@orgcmdtkc{d,C-c C-a d,org-attach-delete-one} -Select and delete a single attachment. - -@orgcmdtkc{D,C-c C-a D,org-attach-delete-all} -Delete all of a task's attachments. A safer way is to open the directory in -@command{dired} and delete from there. - -@orgcmdtkc{s,C-c C-a s,org-attach-set-directory} -@cindex property, ATTACH_DIR -Set a specific directory as the entry's attachment directory. This works by -putting the directory path into the @code{ATTACH_DIR} property. - -@orgcmdtkc{i,C-c C-a i,org-attach-set-inherit} -@cindex property, ATTACH_DIR_INHERIT -Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the -same directory for attachments as the parent does. -@end table -@end table - -@node RSS Feeds, Protocols, Attachments, Capture - Refile - Archive -@section RSS feeds -@cindex RSS feeds -@cindex Atom feeds - -Org can add and change entries based on information found in RSS feeds and -Atom feeds. You could use this to make a task out of each new podcast in a -podcast feed. Or you could use a phone-based note-creating service on the -web to import tasks into Org. To access feeds, configure the variable -@code{org-feed-alist}. The docstring of this variable has detailed -information. Here is just an example: - -@example -(setq org-feed-alist - '(("Slashdot" - "http://rss.slashdot.org/Slashdot/slashdot" - "~/txt/org/feeds.org" "Slashdot Entries"))) -@end example - -@noindent -will configure that new items from the feed provided by -@code{rss.slashdot.org} will result in new entries in the file -@file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever -the following command is used: - -@table @kbd -@orgcmd{C-c C-x g,org-feed-update-all} -@item C-c C-x g -Collect items from the feeds configured in @code{org-feed-alist} and act upon -them. -@orgcmd{C-c C-x G,org-feed-goto-inbox} -Prompt for a feed name and go to the inbox configured for this feed. -@end table - -Under the same headline, Org will create a drawer @samp{FEEDSTATUS} in which -it will store information about the status of items in the feed, to avoid -adding the same item several times. You should add @samp{FEEDSTATUS} to the -list of drawers in that file: - -@example -#+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS -@end example - -For more information, including how to read atom feeds, see -@file{org-feed.el} and the docstring of @code{org-feed-alist}. - -@node Protocols, Refiling notes, RSS Feeds, Capture - Refile - Archive -@section Protocols for external access -@cindex protocols, for external access -@cindex emacsserver - -You can set up Org for handling protocol calls from outside applications that -are passed to Emacs through the @file{emacsserver}. For example, you can -configure bookmarks in your web browser to send a link to the current page to -Org and create a note from it using capture (@pxref{Capture}). Or you -could create a bookmark that will tell Emacs to open the local source file of -a remote website you are looking at with the browser. See -@uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed -documentation and setup instructions. - -@node Refiling notes, Archiving, Protocols, Capture - Refile - Archive -@section Refiling notes -@cindex refiling notes - -When reviewing the captured data, you may want to refile some of the entries -into a different list, for example into a project. Cutting, finding the -right location, and then pasting the note is cumbersome. To simplify this -process, you can use the following special command: - -@table @kbd -@orgcmd{C-c C-w,org-refile} -@vindex org-reverse-note-order -@vindex org-refile-targets -@vindex org-refile-use-outline-path -@vindex org-outline-path-complete-in-steps -@vindex org-refile-allow-creating-parent-nodes -@vindex org-log-refile -@vindex org-refile-use-cache -Refile the entry or region at point. This command offers possible locations -for refiling the entry and lets you select one with completion. The item (or -all items in the region) is filed below the target heading as a subitem. -Depending on @code{org-reverse-note-order}, it will be either the first or -last subitem.@* -By default, all level 1 headlines in the current buffer are considered to be -targets, but you can have more complex definitions across a number of files. -See the variable @code{org-refile-targets} for details. If you would like to -select a location via a file-path-like completion along the outline path, see -the variables @code{org-refile-use-outline-path} and -@code{org-outline-path-complete-in-steps}. If you would like to be able to -create new nodes as new parents for refiling on the fly, check the -variable @code{org-refile-allow-creating-parent-nodes}. -When the variable @code{org-log-refile}@footnote{with corresponding -@code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile}, -and @code{nologrefile}} is set, a timestamp or a note will be -recorded when an entry has been refiled. -@orgkey{C-u C-c C-w} -Use the refile interface to jump to a heading. -@orgcmd{C-u C-u C-c C-w,org-refile-goto-last-stored} -Jump to the location where @code{org-refile} last moved a tree to. -@item C-2 C-c C-w -Refile as the child of the item currently being clocked. -@orgcmdtkc{C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w,C-0 C-c C-w,org-refile-cache-clear} -Clear the target cache. Caching of refile targets can be turned on by -setting @code{org-refile-use-cache}. To make the command see new possible -targets, you have to clear the cache with this command. -@end table - -@node Archiving, , Refiling notes, Capture - Refile - Archive -@section Archiving -@cindex archiving - -When a project represented by a (sub)tree is finished, you may want -to move the tree out of the way and to stop it from contributing to the -agenda. Archiving is important to keep your working files compact and global -searches like the construction of agenda views fast. - -@table @kbd -@orgcmd{C-c C-x C-a,org-archive-subtree-default} -@vindex org-archive-default-command -Archive the current entry using the command specified in the variable -@code{org-archive-default-command}. -@end table - -@menu -* Moving subtrees:: Moving a tree to an archive file -* Internal archiving:: Switch off a tree but keep it in the file -@end menu - -@node Moving subtrees, Internal archiving, Archiving, Archiving -@subsection Moving a tree to the archive file -@cindex external archiving - -The most common archiving action is to move a project tree to another file, -the archive file. - -@table @kbd -@orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree} -@vindex org-archive-location -Archive the subtree starting at the cursor position to the location -given by @code{org-archive-location}. -@orgkey{C-u C-c C-x C-s} -Check if any direct children of the current headline could be moved to -the archive. To do this, each subtree is checked for open TODO entries. -If none are found, the command offers to move it to the archive -location. If the cursor is @emph{not} on a headline when this command -is invoked, the level 1 trees will be checked. -@end table - -@cindex archive locations -The default archive location is a file in the same directory as the -current file, with the name derived by appending @file{_archive} to the -current file name. For information and examples on how to change this, -see the documentation string of the variable -@code{org-archive-location}. There is also an in-buffer option for -setting this variable, for example@footnote{For backward compatibility, -the following also works: If there are several such lines in a file, -each specifies the archive location for the text below it. The first -such line also applies to any text before its definition. However, -using this method is @emph{strongly} deprecated as it is incompatible -with the outline structure of the document. The correct method for -setting multiple archive locations in a buffer is using properties.}: - -@cindex #+ARCHIVE -@example -#+ARCHIVE: %s_done:: -@end example - -@cindex property, ARCHIVE -@noindent -If you would like to have a special ARCHIVE location for a single entry -or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the -location as the value (@pxref{Properties and Columns}). - -@vindex org-archive-save-context-info -When a subtree is moved, it receives a number of special properties that -record context information like the file from where the entry came, its -outline path the archiving time etc. Configure the variable -@code{org-archive-save-context-info} to adjust the amount of information -added. - - -@node Internal archiving, , Moving subtrees, Archiving -@subsection Internal archiving - -If you want to just switch off (for agenda views) certain subtrees without -moving them to a different file, you can use the @code{ARCHIVE tag}. - -A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at -its location in the outline tree, but behaves in the following way: -@itemize @minus -@item -@vindex org-cycle-open-archived-trees -It does not open when you attempt to do so with a visibility cycling -command (@pxref{Visibility cycling}). You can force cycling archived -subtrees with @kbd{C-@key{TAB}}, or by setting the option -@code{org-cycle-open-archived-trees}. Also normal outline commands like -@code{show-all} will open archived subtrees. -@item -@vindex org-sparse-tree-open-archived-trees -During sparse tree construction (@pxref{Sparse trees}), matches in -archived subtrees are not exposed, unless you configure the option -@code{org-sparse-tree-open-archived-trees}. -@item -@vindex org-agenda-skip-archived-trees -During agenda view construction (@pxref{Agenda Views}), the content of -archived trees is ignored unless you configure the option -@code{org-agenda-skip-archived-trees}, in which case these trees will always -be included. In the agenda you can press @kbd{v a} to get archives -temporarily included. -@item -@vindex org-export-with-archived-trees -Archived trees are not exported (@pxref{Exporting}), only the headline -is. Configure the details using the variable -@code{org-export-with-archived-trees}. -@item -@vindex org-columns-skip-archived-trees -Archived trees are excluded from column view unless the variable -@code{org-columns-skip-archived-trees} is configured to @code{nil}. -@end itemize - -The following commands help manage the ARCHIVE tag: - -@table @kbd -@orgcmd{C-c C-x a,org-toggle-archive-tag} -Toggle the ARCHIVE tag for the current headline. When the tag is set, -the headline changes to a shadowed face, and the subtree below it is -hidden. -@orgkey{C-u C-c C-x a} -Check if any direct children of the current headline should be archived. -To do this, each subtree is checked for open TODO entries. If none are -found, the command offers to set the ARCHIVE tag for the child. If the -cursor is @emph{not} on a headline when this command is invoked, the -level 1 trees will be checked. -@orgcmd{C-@kbd{TAB},org-force-cycle-archived} -Cycle a tree even if it is tagged with ARCHIVE. -@orgcmd{C-c C-x A,org-archive-to-archive-sibling} -Move the current entry to the @emph{Archive Sibling}. This is a sibling of -the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}. The -entry becomes a child of that sibling and in this way retains a lot of its -original context, including inherited tags and approximate position in the -outline. -@end table - - -@node Agenda Views, Markup, Capture - Refile - Archive, Top -@chapter Agenda views -@cindex agenda views - -Due to the way Org works, TODO items, time-stamped items, and -tagged headlines can be scattered throughout a file or even a number of -files. To get an overview of open action items, or of events that are -important for a particular date, this information must be collected, -sorted and displayed in an organized way. - -Org can select items based on various criteria and display them -in a separate buffer. Seven different view types are provided: - -@itemize @bullet -@item -an @emph{agenda} that is like a calendar and shows information -for specific dates, -@item -a @emph{TODO list} that covers all unfinished -action items, -@item -a @emph{match view}, showings headlines based on the tags, properties, and -TODO state associated with them, -@item -a @emph{timeline view} that shows all events in a single Org file, -in time-sorted view, -@item -a @emph{text search view} that shows all entries from multiple files -that contain specified keywords, -@item -a @emph{stuck projects view} showing projects that currently don't move -along, and -@item -@emph{custom views} that are special searches and combinations of different -views. -@end itemize - -@noindent -The extracted information is displayed in a special @emph{agenda -buffer}. This buffer is read-only, but provides commands to visit the -corresponding locations in the original Org files, and even to -edit these files remotely. - -@vindex org-agenda-window-setup -@vindex org-agenda-restore-windows-after-quit -Two variables control how the agenda buffer is displayed and whether the -window configuration is restored when the agenda exits: -@code{org-agenda-window-setup} and -@code{org-agenda-restore-windows-after-quit}. - -@menu -* Agenda files:: Files being searched for agenda information -* Agenda dispatcher:: Keyboard access to agenda views -* Built-in agenda views:: What is available out of the box? -* Presentation and sorting:: How agenda items are prepared for display -* Agenda commands:: Remote editing of Org trees -* Custom agenda views:: Defining special searches and views -* Exporting Agenda Views:: Writing a view to a file -* Agenda column view:: Using column view for collected entries -@end menu - -@node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views -@section Agenda files -@cindex agenda files -@cindex files for agenda - -@vindex org-agenda-files -The information to be shown is normally collected from all @emph{agenda -files}, the files listed in the variable -@code{org-agenda-files}@footnote{If the value of that variable is not a -list, but a single file name, then the list of agenda files will be -maintained in that external file.}. If a directory is part of this list, -all files with the extension @file{.org} in this directory will be part -of the list. - -Thus, even if you only work with a single Org file, that file should -be put into the list@footnote{When using the dispatcher, pressing -@kbd{<} before selecting a command will actually limit the command to -the current file, and ignore @code{org-agenda-files} until the next -dispatcher command.}. You can customize @code{org-agenda-files}, but -the easiest way to maintain it is through the following commands - -@cindex files, adding to agenda list -@table @kbd -@orgcmd{C-c [,org-agenda-file-to-front} -Add current file to the list of agenda files. The file is added to -the front of the list. If it was already in the list, it is moved to -the front. With a prefix argument, file is added/moved to the end. -@orgcmd{C-c ],org-remove-file} -Remove current file from the list of agenda files. -@kindex C-, -@cindex cycling, of agenda files -@orgcmd{C-',org-cycle-agenda-files} -@itemx C-, -Cycle through agenda file list, visiting one file after the other. -@kindex M-x org-iswitchb -@item M-x org-iswitchb -Command to use an @code{iswitchb}-like interface to switch to and between Org -buffers. -@end table - -@noindent -The Org menu contains the current list of files and can be used -to visit any of them. - -If you would like to focus the agenda temporarily on a file not in -this list, or on just one file in the list, or even on only a subtree in a -file, then this can be done in different ways. For a single agenda command, -you may press @kbd{<} once or several times in the dispatcher -(@pxref{Agenda dispatcher}). To restrict the agenda scope for an -extended period, use the following commands: - -@table @kbd -@orgcmd{C-c C-x <,org-agenda-set-restriction-lock} -Permanently restrict the agenda to the current subtree. When with a -prefix argument, or with the cursor before the first headline in a file, -the agenda scope is set to the entire file. This restriction remains in -effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<} -or @kbd{>} in the agenda dispatcher. If there is a window displaying an -agenda view, the new restriction takes effect immediately. -@orgcmd{C-c C-x >,org-agenda-remove-restriction-lock} -Remove the permanent restriction created by @kbd{C-c C-x <}. -@end table - -@noindent -When working with @file{speedbar.el}, you can use the following commands in -the Speedbar frame: -@table @kbd -@orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction} -Permanently restrict the agenda to the item---either an Org file or a subtree -in such a file---at the cursor in the Speedbar frame. -If there is a window displaying an agenda view, the new restriction takes -effect immediately. -@orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock} -Lift the restriction. -@end table - -@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views -@section The agenda dispatcher -@cindex agenda dispatcher -@cindex dispatching agenda commands -The views are created through a dispatcher, which should be bound to a -global key---for example @kbd{C-c a} (@pxref{Activation}). In the -following we will assume that @kbd{C-c a} is indeed how the dispatcher -is accessed and list keyboard access to commands accordingly. After -pressing @kbd{C-c a}, an additional letter is required to execute a -command. The dispatcher offers the following default commands: -@table @kbd -@item a -Create the calendar-like agenda (@pxref{Weekly/daily agenda}). -@item t @r{/} T -Create a list of all TODO items (@pxref{Global TODO list}). -@item m @r{/} M -Create a list of headlines matching a TAGS expression (@pxref{Matching -tags and properties}). -@item L -Create the timeline view for the current buffer (@pxref{Timeline}). -@item s -Create a list of entries selected by a boolean expression of keywords -and/or regular expressions that must or must not occur in the entry. -@item / -@vindex org-agenda-text-search-extra-files -Search for a regular expression in all agenda files and additionally in -the files listed in @code{org-agenda-text-search-extra-files}. This -uses the Emacs command @code{multi-occur}. A prefix argument can be -used to specify the number of context lines for each match, default is -1. -@item # @r{/} ! -Create a list of stuck projects (@pxref{Stuck projects}). -@item < -Restrict an agenda command to the current buffer@footnote{For backward -compatibility, you can also press @kbd{1} to restrict to the current -buffer.}. After pressing @kbd{<}, you still need to press the character -selecting the command. -@item < < -If there is an active region, restrict the following agenda command to -the region. Otherwise, restrict it to the current subtree@footnote{For -backward compatibility, you can also press @kbd{0} to restrict to the -current region/subtree.}. After pressing @kbd{< <}, you still need to press the -character selecting the command. -@end table - -You can also define custom commands that will be accessible through the -dispatcher, just like the default commands. This includes the -possibility to create extended agenda buffers that contain several -blocks together, for example the weekly agenda, the global TODO list and -a number of special tags matches. @xref{Custom agenda views}. - -@node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda Views -@section The built-in agenda views - -In this section we describe the built-in views. - -@menu -* Weekly/daily agenda:: The calendar page with current tasks -* Global TODO list:: All unfinished action items -* Matching tags and properties:: Structured information with fine-tuned search -* Timeline:: Time-sorted view for single file -* Search view:: Find entries by searching for text -* Stuck projects:: Find projects you need to review -@end menu - -@node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views -@subsection The weekly/daily agenda -@cindex agenda -@cindex weekly agenda -@cindex daily agenda - -The purpose of the weekly/daily @emph{agenda} is to act like a page of a -paper agenda, showing all the tasks for the current week or day. - -@table @kbd -@cindex org-agenda, command -@orgcmd{C-c a a,org-agenda-list} -Compile an agenda for the current week from a list of Org files. The agenda -shows the entries for each day. With a numeric prefix@footnote{For backward -compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be -listed before the agenda. This feature is deprecated, use the dedicated TODO -list, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1 -C-c a a}) you may set the number of days to be displayed. -@end table - -@vindex org-agenda-span -@vindex org-agenda-ndays -The default number of days displayed in the agenda is set by the variable -@code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}). This -variable can be set to any number of days you want to see by default in the -agenda, or to a span name, such a @code{day}, @code{week}, @code{month} or -@code{year}. - -Remote editing from the agenda buffer means, for example, that you can -change the dates of deadlines and appointments from the agenda buffer. -The commands available in the Agenda buffer are listed in @ref{Agenda -commands}. - -@subsubheading Calendar/Diary integration -@cindex calendar integration -@cindex diary integration - -Emacs contains the calendar and diary by Edward M. Reingold. The -calendar displays a three-month calendar with holidays from different -countries and cultures. The diary allows you to keep track of -anniversaries, lunar phases, sunrise/set, recurrent appointments -(weekly, monthly) and more. In this way, it is quite complementary to -Org. It can be very useful to combine output from Org with -the diary. - -In order to include entries from the Emacs diary into Org mode's -agenda, you only need to customize the variable - -@lisp -(setq org-agenda-include-diary t) -@end lisp - -@noindent After that, everything will happen automatically. All diary -entries including holidays, anniversaries, etc., will be included in the -agenda buffer created by Org mode. @key{SPC}, @key{TAB}, and -@key{RET} can be used from the agenda buffer to jump to the diary -file in order to edit existing diary entries. The @kbd{i} command to -insert new entries for the current date works in the agenda buffer, as -well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display -Sunrise/Sunset times, show lunar phases and to convert to other -calendars, respectively. @kbd{c} can be used to switch back and forth -between calendar and agenda. - -If you are using the diary only for sexp entries and holidays, it is -faster to not use the above setting, but instead to copy or even move -the entries into an Org file. Org mode evaluates diary-style sexp -entries, and does it faster because there is no overhead for first -creating the diary display. Note that the sexp entries must start at -the left margin, no whitespace is allowed before them. For example, -the following segment of an Org file will be processed and entries -will be made in the agenda: - -@example -* Birthdays and similar stuff -#+CATEGORY: Holiday -%%(org-calendar-holiday) ; special function for holiday names -#+CATEGORY: Ann -%%(org-anniversary 1956 5 14)@footnote{@code{org-anniversary} is just like @code{diary-anniversary}, but the argument order is always according to ISO and therefore independent of the value of @code{calendar-date-style}.} Arthur Dent is %d years old -%%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old -@end example - -@subsubheading Anniversaries from BBDB -@cindex BBDB, anniversaries -@cindex anniversaries, from BBDB - -If you are using the Big Brothers Database to store your contacts, you will -very likely prefer to store anniversaries in BBDB rather than in a -separate Org or diary file. Org supports this and will show BBDB -anniversaries as part of the agenda. All you need to do is to add the -following to one of your agenda files: - -@example -* Anniversaries - :PROPERTIES: - :CATEGORY: Anniv - :END: -%%(org-bbdb-anniversaries) -@end example - -You can then go ahead and define anniversaries for a BBDB record. Basically, -you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB -record and then add the date in the format @code{YYYY-MM-DD} or @code{MM-DD}, -followed by a space and the class of the anniversary (@samp{birthday} or -@samp{wedding}, or a format string). If you omit the class, it will default to -@samp{birthday}. Here are a few examples, the header for the file -@file{org-bbdb.el} contains more detailed information. - -@example -1973-06-22 -06-22 -1955-08-02 wedding -2008-04-14 %s released version 6.01 of org mode, %d years ago -@end example - -After a change to BBDB, or for the first agenda display during an Emacs -session, the agenda display will suffer a short delay as Org updates its -hash with anniversaries. However, from then on things will be very fast---much -faster in fact than a long list of @samp{%%(diary-anniversary)} entries -in an Org or Diary file. - -@subsubheading Appointment reminders -@cindex @file{appt.el} -@cindex appointment reminders -@cindex appointment -@cindex reminders - -Org can interact with Emacs appointments notification facility. To add all -the appointments of your agenda files, use the command -@code{org-agenda-to-appt}. This command also lets you filter through the -list of your appointments and add only those belonging to a specific category -or matching a regular expression. See the docstring for details. - -@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views -@subsection The global TODO list -@cindex global TODO list -@cindex TODO list, global - -The global TODO list contains all unfinished TODO items formatted and -collected into a single place. - -@table @kbd -@orgcmd{C-c a t,org-todo-list} -Show the global TODO list. This collects the TODO items from all agenda -files (@pxref{Agenda Views}) into a single buffer. By default, this lists -items with a state the is not a DONE state. The buffer is in -@code{agenda-mode}, so there are commands to examine and manipulate the TODO -entries directly from that buffer (@pxref{Agenda commands}). -@orgcmd{C-c a T,org-todo-list} -@cindex TODO keyword matching -@vindex org-todo-keywords -Like the above, but allows selection of a specific TODO keyword. You can -also do this by specifying a prefix argument to @kbd{C-c a t}. You are -prompted for a keyword, and you may also specify several keywords by -separating them with @samp{|} as the boolean OR operator. With a numeric -prefix, the Nth keyword in @code{org-todo-keywords} is selected. -@kindex r -The @kbd{r} key in the agenda buffer regenerates it, and you can give -a prefix argument to this command to change the selected TODO keyword, -for example @kbd{3 r}. If you often need a search for a specific -keyword, define a custom command for it (@pxref{Agenda dispatcher}).@* -Matching specific TODO keywords can also be done as part of a tags -search (@pxref{Tag searches}). -@end table - -Remote editing of TODO items means that you can change the state of a -TODO entry with a single key press. The commands available in the -TODO list are described in @ref{Agenda commands}. - -@cindex sublevels, inclusion into TODO list -Normally the global TODO list simply shows all headlines with TODO -keywords. This list can become very long. There are two ways to keep -it more compact: -@itemize @minus -@item -@vindex org-agenda-todo-ignore-scheduled -@vindex org-agenda-todo-ignore-deadlines -@vindex org-agenda-todo-ignore-timestamp -@vindex org-agenda-todo-ignore-with-date -Some people view a TODO item that has been @emph{scheduled} for execution or -have a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}. -Configure the variables @code{org-agenda-todo-ignore-scheduled}, -@code{org-agenda-todo-ignore-deadlines}, -@code{org-agenda-todo-ignore-timestamp} and/or -@code{org-agenda-todo-ignore-with-date} to exclude such items from the global -TODO list. -@item -@vindex org-agenda-todo-list-sublevels -TODO items may have sublevels to break up the task into subtasks. In -such cases it may be enough to list only the highest level TODO headline -and omit the sublevels from the global list. Configure the variable -@code{org-agenda-todo-list-sublevels} to get this behavior. -@end itemize - -@node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views -@subsection Matching tags and properties -@cindex matching, of tags -@cindex matching, of properties -@cindex tags view -@cindex match view - -If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}), -or have properties (@pxref{Properties and Columns}), you can select headlines -based on this metadata and collect them into an agenda buffer. The match -syntax described here also applies when creating sparse trees with @kbd{C-c / -m}. - -@table @kbd -@orgcmd{C-c a m,org-tags-view} -Produce a list of all headlines that match a given set of tags. The -command prompts for a selection criterion, which is a boolean logic -expression with tags, like @samp{+work+urgent-withboss} or -@samp{work|home} (@pxref{Tags}). If you often need a specific search, -define a custom command for it (@pxref{Agenda dispatcher}). -@orgcmd{C-c a M,org-tags-view} -@vindex org-tags-match-list-sublevels -@vindex org-agenda-tags-todo-honor-ignore-options -Like @kbd{C-c a m}, but only select headlines that are also TODO items in a -not-DONE state and force checking subitems (see variable -@code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items, -see the variable @code{org-agenda-tags-todo-honor-ignore-options}. Matching -specific TODO keywords together with a tags match is also possible, see -@ref{Tag searches}. -@end table - -The commands available in the tags list are described in @ref{Agenda -commands}. - -@subsubheading Match syntax - -@cindex Boolean logic, for tag/property searches -A search string can use Boolean operators @samp{&} for AND and @samp{|} for -OR. @samp{&} binds more strongly than @samp{|}. Parentheses are currently -not implemented. Each element in the search is either a tag, a regular -expression matching tags, or an expression like @code{PROPERTY OPERATOR -VALUE} with a comparison operator, accessing a property value. Each element -may be preceded by @samp{-}, to select against it, and @samp{+} is syntactic -sugar for positive selection. The AND operator @samp{&} is optional when -@samp{+} or @samp{-} is present. Here are some examples, using only tags. - -@table @samp -@item +work-boss -Select headlines tagged @samp{:work:}, but discard those also tagged -@samp{:boss:}. -@item work|laptop -Selects lines tagged @samp{:work:} or @samp{:laptop:}. -@item work|laptop+night -Like before, but require the @samp{:laptop:} lines to be tagged also -@samp{:night:}. -@end table - -@cindex regular expressions, with tags search -Instead of a tag, you may also specify a regular expression enclosed in curly -braces. For example, -@samp{work+@{^boss.*@}} matches headlines that contain the tag -@samp{:work:} and any tag @i{starting} with @samp{boss}. - -@cindex TODO keyword matching, with tags search -@cindex level, require for tags/property match -@cindex category, require for tags/property match -@vindex org-odd-levels-only -You may also test for properties (@pxref{Properties and Columns}) at the same -time as matching tags. The properties may be real properties, or special -properties that represent other metadata (@pxref{Special properties}). For -example, the ``property'' @code{TODO} represents the TODO keyword of the -entry. Or, the ``property'' @code{LEVEL} represents the level of an entry. -So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines -that have the tag @samp{boss} and are @emph{not} marked with the TODO keyword -DONE. In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not -count the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc. - -Here are more examples: -@table @samp -@item work+TODO="WAITING" -Select @samp{:work:}-tagged TODO lines with the specific TODO -keyword @samp{WAITING}. -@item work+TODO="WAITING"|home+TODO="WAITING" -Waiting tasks both at work and at home. -@end table - -When matching properties, a number of different operators can be used to test -the value of a property. Here is a complex example: - -@example -+work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \ - +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>" -@end example - -@noindent -The type of comparison will depend on how the comparison value is written: -@itemize @minus -@item -If the comparison value is a plain number, a numerical comparison is done, -and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=}, -@samp{>=}, and @samp{<>}. -@item -If the comparison value is enclosed in double-quotes, -a string comparison is done, and the same operators are allowed. -@item -If the comparison value is enclosed in double-quotes @emph{and} angular -brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are -assumed to be date/time specifications in the standard Org way, and the -comparison will be done accordingly. Special values that will be recognized -are @code{""} for now (including time), and @code{""}, and -@code{""} for these days at 0:00 hours, i.e.@: without a time -specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units -@code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year, -respectively, can be used. -@item -If the comparison value is enclosed -in curly braces, a regexp match is performed, with @samp{=} meaning that the -regexp matches the property value, and @samp{<>} meaning that it does not -match. -@end itemize - -So the search string in the example finds entries tagged @samp{:work:} but -not @samp{:boss:}, which also have a priority value @samp{A}, a -@samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort} -property that is numerically smaller than 2, a @samp{:With:} property that is -matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled -on or after October 11, 2008. - -Accessing TODO, LEVEL, and CATEGORY during a search is fast. Accessing any -other properties will slow down the search. However, once you have paid the -price by accessing one property, testing additional properties is cheap -again. - -You can configure Org mode to use property inheritance during a search, but -beware that this can slow down searches considerably. See @ref{Property -inheritance}, for details. - -For backward compatibility, and also for typing speed, there is also a -different way to test TODO states in a search. For this, terminate the -tags/property part of the search string (which may include several terms -connected with @samp{|}) with a @samp{/} and then specify a Boolean -expression just for TODO keywords. The syntax is then similar to that for -tags, but should be applied with care: for example, a positive selection on -several TODO keywords cannot meaningfully be combined with boolean AND. -However, @emph{negative selection} combined with AND can be meaningful. To -make sure that only lines are checked that actually have any TODO keyword -(resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO -part after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} will -not match TODO keywords in a DONE state. Examples: - -@table @samp -@item work/WAITING -Same as @samp{work+TODO="WAITING"} -@item work/!-WAITING-NEXT -Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING} -nor @samp{NEXT} -@item work/!+WAITING|+NEXT -Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or -@samp{NEXT}. -@end table - -@node Timeline, Search view, Matching tags and properties, Built-in agenda views -@subsection Timeline for a single file -@cindex timeline, single file -@cindex time-sorted view - -The timeline summarizes all time-stamped items from a single Org mode -file in a @emph{time-sorted view}. The main purpose of this command is -to give an overview over events in a project. - -@table @kbd -@orgcmd{C-c a L,org-timeline} -Show a time-sorted view of the Org file, with all time-stamped items. -When called with a @kbd{C-u} prefix, all unfinished TODO entries -(scheduled or not) are also listed under the current date. -@end table - -@noindent -The commands available in the timeline buffer are listed in -@ref{Agenda commands}. - -@node Search view, Stuck projects, Timeline, Built-in agenda views -@subsection Search view -@cindex search view -@cindex text search -@cindex searching, for text - -This agenda view is a general text search facility for Org mode entries. -It is particularly useful to find notes. - -@table @kbd -@orgcmd{C-c a s,org-search-view} -This is a special search that lets you select entries by matching a substring -or specific words using a boolean logic. -@end table -For example, the search string @samp{computer equipment} will find entries -that contain @samp{computer equipment} as a substring. If the two words are -separated by more space or a line break, the search will still match. -Search view can also search for specific keywords in the entry, using Boolean -logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}} -will search for note entries that contain the keywords @code{computer} -and @code{wifi}, but not the keyword @code{ethernet}, and which are also -not matched by the regular expression @code{8\.11[bg]}, meaning to -exclude both 8.11b and 8.11g. The first @samp{+} is necessary to turn on -word search, other @samp{+} characters are optional. For more details, see -the docstring of the command @code{org-search-view}. - -@vindex org-agenda-text-search-extra-files -Note that in addition to the agenda files, this command will also search -the files listed in @code{org-agenda-text-search-extra-files}. - -@node Stuck projects, , Search view, Built-in agenda views -@subsection Stuck projects -@pindex GTD, Getting Things Done - -If you are following a system like David Allen's GTD to organize your -work, one of the ``duties'' you have is a regular review to make sure -that all projects move along. A @emph{stuck} project is a project that -has no defined next actions, so it will never show up in the TODO lists -Org mode produces. During the review, you need to identify such -projects and define next actions for them. - -@table @kbd -@orgcmd{C-c a #,org-agenda-list-stuck-projects} -List projects that are stuck. -@kindex C-c a ! -@item C-c a ! -@vindex org-stuck-projects -Customize the variable @code{org-stuck-projects} to define what a stuck -project is and how to find it. -@end table - -You almost certainly will have to configure this view before it will -work for you. The built-in default assumes that all your projects are -level-2 headlines, and that a project is not stuck if it has at least -one entry marked with a TODO keyword TODO or NEXT or NEXTACTION. - -Let's assume that you, in your own way of using Org mode, identify -projects with a tag PROJECT, and that you use a TODO keyword MAYBE to -indicate a project that should not be considered yet. Let's further -assume that the TODO keyword DONE marks finished projects, and that NEXT -and TODO indicate next actions. The tag @@SHOP indicates shopping and -is a next action even without the NEXT tag. Finally, if the project -contains the special word IGNORE anywhere, it should not be listed -either. In this case you would start by identifying eligible projects -with a tags/todo match@footnote{@xref{Tag searches}.} -@samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT, @@SHOP, and -IGNORE in the subtree to identify projects that are not stuck. The -correct customization for this is - -@lisp -(setq org-stuck-projects - '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP") - "\\")) -@end lisp - -Note that if a project is identified as non-stuck, the subtree of this entry -will still be searched for stuck projects. - -@node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda Views -@section Presentation and sorting -@cindex presentation, of agenda items - -@vindex org-agenda-prefix-format -@vindex org-agenda-tags-column -Before displaying items in an agenda view, Org mode visually prepares the -items and sorts them. Each item occupies a single line. The line starts -with a @emph{prefix} that contains the @emph{category} (@pxref{Categories}) -of the item and other important information. You can customize in which -column tags will be displayed through @code{org-agenda-tags-column}. You can -also customize the prefix using the option @code{org-agenda-prefix-format}. -This prefix is followed by a cleaned-up version of the outline headline -associated with the item. - -@menu -* Categories:: Not all tasks are equal -* Time-of-day specifications:: How the agenda knows the time -* Sorting of agenda items:: The order of things -@end menu - -@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting -@subsection Categories - -@cindex category -@cindex #+CATEGORY -The category is a broad label assigned to each agenda item. By default, -the category is simply derived from the file name, but you can also -specify it with a special line in the buffer, like this@footnote{For -backward compatibility, the following also works: if there are several -such lines in a file, each specifies the category for the text below it. -The first category also applies to any text before the first CATEGORY -line. However, using this method is @emph{strongly} deprecated as it is -incompatible with the outline structure of the document. The correct -method for setting multiple categories in a buffer is using a -property.}: - -@example -#+CATEGORY: Thesis -@end example - -@noindent -@cindex property, CATEGORY -If you would like to have a special CATEGORY for a single entry or a -(sub)tree, give the entry a @code{:CATEGORY:} property with the -special category you want to apply as the value. - -@noindent -The display in the agenda buffer looks best if the category is not -longer than 10 characters. - -@noindent -You can set up icons for category by customizing the -@code{org-agenda-category-icon-alist} variable. - -@node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting -@subsection Time-of-day specifications -@cindex time-of-day specification - -Org mode checks each agenda item for a time-of-day specification. The -time can be part of the timestamp that triggered inclusion into the -agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time -ranges can be specified with two timestamps, like -@c -@w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}. - -In the headline of the entry itself, a time(range) may also appear as -plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda -integrates the Emacs diary (@pxref{Weekly/daily agenda}), time -specifications in diary entries are recognized as well. - -For agenda display, Org mode extracts the time and displays it in a -standard 24 hour format as part of the prefix. The example times in -the previous paragraphs would end up in the agenda like this: - -@example - 8:30-13:00 Arthur Dent lies in front of the bulldozer - 12:45...... Ford Prefect arrives and takes Arthur to the pub - 19:00...... The Vogon reads his poem - 20:30-22:15 Marvin escorts the Hitchhikers to the bridge -@end example - -@cindex time grid -If the agenda is in single-day mode, or for the display of today, the -timed entries are embedded in a time grid, like - -@example - 8:00...... ------------------ - 8:30-13:00 Arthur Dent lies in front of the bulldozer - 10:00...... ------------------ - 12:00...... ------------------ - 12:45...... Ford Prefect arrives and takes Arthur to the pub - 14:00...... ------------------ - 16:00...... ------------------ - 18:00...... ------------------ - 19:00...... The Vogon reads his poem - 20:00...... ------------------ - 20:30-22:15 Marvin escorts the Hitchhikers to the bridge -@end example - -@vindex org-agenda-use-time-grid -@vindex org-agenda-time-grid -The time grid can be turned on and off with the variable -@code{org-agenda-use-time-grid}, and can be configured with -@code{org-agenda-time-grid}. - -@node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting -@subsection Sorting of agenda items -@cindex sorting, of agenda items -@cindex priorities, of agenda items -Before being inserted into a view, the items are sorted. How this is -done depends on the type of view. -@itemize @bullet -@item -@vindex org-agenda-files -For the daily/weekly agenda, the items for each day are sorted. The -default order is to first collect all items containing an explicit -time-of-day specification. These entries will be shown at the beginning -of the list, as a @emph{schedule} for the day. After that, items remain -grouped in categories, in the sequence given by @code{org-agenda-files}. -Within each category, items are sorted by priority (@pxref{Priorities}), -which is composed of the base priority (2000 for priority @samp{A}, 1000 -for @samp{B}, and 0 for @samp{C}), plus additional increments for -overdue scheduled or deadline items. -@item -For the TODO list, items remain in the order of categories, but within -each category, sorting takes place according to priority -(@pxref{Priorities}). The priority used for sorting derives from the -priority cookie, with additions depending on how close an item is to its due -or scheduled date. -@item -For tags matches, items are not sorted at all, but just appear in the -sequence in which they are found in the agenda files. -@end itemize - -@vindex org-agenda-sorting-strategy -Sorting can be customized using the variable -@code{org-agenda-sorting-strategy}, and may also include criteria based on -the estimated effort of an entry (@pxref{Effort estimates}). - -@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views -@section Commands in the agenda buffer -@cindex commands, in agenda buffer - -Entries in the agenda buffer are linked back to the Org file or diary -file where they originate. You are not allowed to edit the agenda -buffer itself, but commands are provided to show and jump to the -original entry location, and to edit the Org files ``remotely'' from -the agenda buffer. In this way, all information is stored only once, -removing the risk that your agenda and note files may diverge. - -Some commands can be executed with mouse clicks on agenda lines. For -the other commands, the cursor needs to be in the desired line. - -@table @kbd -@tsubheading{Motion} -@cindex motion commands in agenda -@orgcmd{n,org-agenda-next-line} -Next line (same as @key{down} and @kbd{C-n}). -@orgcmd{p,org-agenda-previous-line} -Previous line (same as @key{up} and @kbd{C-p}). -@tsubheading{View/Go to Org file} -@orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up} -Display the original location of the item in another window. -With prefix arg, make sure that the entire entry is made visible in the -outline, not only the heading. -@c -@orgcmd{L,org-agenda-recenter} -Display original location and recenter that window. -@c -@orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto} -Go to the original location of the item in another window. -@c -@orgcmd{@key{RET},org-agenda-switch-to} -Go to the original location of the item and delete other windows. -@c -@orgcmd{F,org-agenda-follow-mode} -@vindex org-agenda-start-with-follow-mode -Toggle Follow mode. In Follow mode, as you move the cursor through -the agenda buffer, the other window always shows the corresponding -location in the Org file. The initial setting for this mode in new -agenda buffers can be set with the variable -@code{org-agenda-start-with-follow-mode}. -@c -@orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer} -Display the entire subtree of the current item in an indirect buffer. With a -numeric prefix argument N, go up to level N and then take that tree. If N is -negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the -previously used indirect buffer. - -@orgcmd{C-c C-o,org-agenda-open-link} -Follow a link in the entry. This will offer a selection of any links in the -text belonging to the referenced Org node. If there is only one link, it -will be followed without a selection prompt. - -@tsubheading{Change display} -@cindex display changing, in agenda -@kindex A -@item A -Interactively select another agenda view and append it to the current view. -@c -@kindex o -@item o -Delete other windows. -@c -@orgcmdkskc{v d,d,org-agenda-day-view} -@xorgcmdkskc{v w,w,org-agenda-week-view} -@xorgcmd{v m,org-agenda-month-view} -@xorgcmd{v y,org-agenda-year-view} -@xorgcmd{v SPC,org-agenda-reset-view} -@vindex org-agenda-span -Switch to day/week/month/year view. When switching to day or week view, this -setting becomes the default for subsequent agenda refreshes. Since month and -year views are slow to create, they do not become the default. A numeric -prefix argument may be used to jump directly to a specific day of the year, -ISO week, month, or year, respectively. For example, @kbd{32 d} jumps to -February 1st, @kbd{9 w} to ISO week number 9. When setting day, week, or -month view, a year may be encoded in the prefix argument as well. For -example, @kbd{200712 w} will jump to week 12 in 2007. If such a year -specification has only one or two digits, it will be mapped to the interval -1938-2037. @kbd{v @key{SPC}} will reset to what is set in -@code{org-agenda-span}. -@c -@orgcmd{f,org-agenda-later} -Go forward in time to display the following @code{org-agenda-current-span} days. -For example, if the display covers a week, switch to the following week. -With prefix arg, go forward that many times @code{org-agenda-current-span} days. -@c -@orgcmd{b,org-agenda-earlier} -Go backward in time to display earlier dates. -@c -@orgcmd{.,org-agenda-goto-today} -Go to today. -@c -@orgcmd{j,org-agenda-goto-date} -Prompt for a date and go there. -@c -@orgcmd{J,org-agenda-clock-goto} -Go to the currently clocked-in task @i{in the agenda buffer}. -@c -@orgcmd{D,org-agenda-toggle-diary} -Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}. -@c -@orgcmdkskc{v l,l,org-agenda-log-mode} -@kindex v L -@vindex org-log-done -@vindex org-agenda-log-mode-items -Toggle Logbook mode. In Logbook mode, entries that were marked DONE while -logging was on (variable @code{org-log-done}) are shown in the agenda, as are -entries that have been clocked on that day. You can configure the entry -types that should be included in log mode using the variable -@code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show -all possible logbook entries, including state changes. When called with two -prefix args @kbd{C-u C-u}, show only logging information, nothing else. -@kbd{v L} is equivalent to @kbd{C-u v l}. -@c -@orgcmdkskc{v [,[,org-agenda-manipulate-query-add} -Include inactive timestamps into the current view. Only for weekly/daily -agenda and timeline views. -@c -@orgcmd{v a,org-agenda-archives-mode} -@xorgcmd{v A,org-agenda-archives-mode 'files} -Toggle Archives mode. In Archives mode, trees that are marked -@code{ARCHIVED} are also scanned when producing the agenda. When you use the -capital @kbd{A}, even all archive files are included. To exit archives mode, -press @kbd{v a} again. -@c -@orgcmdkskc{v R,R,org-agenda-clockreport-mode} -@vindex org-agenda-start-with-clockreport-mode -@vindex org-clock-report-include-clocking-task -Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will -always show a table with the clocked times for the timespan and file scope -covered by the current agenda view. The initial setting for this mode in new -agenda buffers can be set with the variable -@code{org-agenda-start-with-clockreport-mode}. By using a prefix argument -when toggling this mode (i.e.@: @kbd{C-u R}), the clock table will not show -contributions from entries that are hidden by agenda filtering@footnote{Only -tags filtering will be respected here, effort filtering is ignored.}. See -also the variable @code{org-clock-report-include-clocking-task}. -@c -@orgkey{v c} -@vindex org-agenda-clock-consistency-checks -Show overlapping clock entries, clocking gaps, and other clocking problems in -the current agenda range. You can then visit clocking lines and fix them -manually. See the variable @code{org-agenda-clock-consistency-checks} for -information on how to customize the definition of what constituted a clocking -problem. To return to normal agenda display, press @kbd{l} to exit Logbook -mode. -@c -@orgcmdkskc{v E,E,org-agenda-entry-text-mode} -@vindex org-agenda-start-with-entry-text-mode -@vindex org-agenda-entry-text-maxlines -Toggle entry text mode. In entry text mode, a number of lines from the Org -outline node referenced by an agenda line will be displayed below the line. -The maximum number of lines is given by the variable -@code{org-agenda-entry-text-maxlines}. Calling this command with a numeric -prefix argument will temporarily modify that number to the prefix value. -@c -@orgcmd{G,org-agenda-toggle-time-grid} -@vindex org-agenda-use-time-grid -@vindex org-agenda-time-grid -Toggle the time grid on and off. See also the variables -@code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}. -@c -@orgcmd{r,org-agenda-redo} -Recreate the agenda buffer, for example to reflect the changes after -modification of the timestamps of items with @kbd{S-@key{left}} and -@kbd{S-@key{right}}. When the buffer is the global TODO list, a prefix -argument is interpreted to create a selective list for a specific TODO -keyword. -@orgcmd{g,org-agenda-redo} -Same as @kbd{r}. -@c -@orgcmdkskc{C-x C-s,s,org-save-all-org-buffers} -Save all Org buffers in the current Emacs session, and also the locations of -IDs. -@c -@orgcmd{C-c C-x C-c,org-agenda-columns} -@vindex org-columns-default-format -Invoke column view (@pxref{Column view}) in the agenda buffer. The column -view format is taken from the entry at point, or (if there is no entry at -point), from the first entry in the agenda view. So whatever the format for -that entry would be in the original buffer (taken from a property, from a -@code{#+COLUMNS} line, or from the default variable -@code{org-columns-default-format}), will be used in the agenda. - -@orgcmd{C-c C-x >,org-agenda-remove-restriction-lock} -Remove the restriction lock on the agenda, if it is currently restricted to a -file or subtree (@pxref{Agenda files}). - -@tsubheading{Secondary filtering and query editing} -@cindex filtering, by tag category and effort, in agenda -@cindex tag filtering, in agenda -@cindex category filtering, in agenda -@cindex effort filtering, in agenda -@cindex query editing, in agenda - -@orgcmd{<,org-agenda-filter-by-category} -@vindex org-agenda-category-filter-preset - -Filter the current agenda view with respect to the category of the item at -point. Pressing @code{<} another time will remove this filter. You can add -a filter preset through the option @code{org-agenda-category-filter-preset} -(see below.) - -@orgcmd{/,org-agenda-filter-by-tag} -@vindex org-agenda-tag-filter-preset -Filter the current agenda view with respect to a tag and/or effort estimates. -The difference between this and a custom agenda command is that filtering is -very fast, so that you can switch quickly between different filters without -having to recreate the agenda.@footnote{Custom commands can preset a filter by -binding the variable @code{org-agenda-tag-filter-preset} as an option. This -filter will then be applied to the view and persist as a basic filter through -refreshes and more secondary filtering. The filter is a global property of -the entire agenda view---in a block agenda, you should only set this in the -global options section, not in the section of an individual block.} - -You will be prompted for a tag selection letter; @key{SPC} will mean any tag at -all. Pressing @key{TAB} at that prompt will offer use completion to select a -tag (including any tags that do not have a selection character). The command -then hides all entries that do not contain or inherit this tag. When called -with prefix arg, remove the entries that @emph{do} have the tag. A second -@kbd{/} at the prompt will turn off the filter and unhide any hidden entries. -If the first key you press is either @kbd{+} or @kbd{-}, the previous filter -will be narrowed by requiring or forbidding the selected additional tag. -Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also -immediately use the @kbd{\} command. - -@vindex org-sort-agenda-noeffort-is-high -In order to filter for effort estimates, you should set up allowed -efforts globally, for example -@lisp -(setq org-global-properties - '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00"))) -@end lisp -You can then filter for an effort by first typing an operator, one of -@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort -estimate in your array of allowed values, where @kbd{0} means the 10th value. -The filter will then restrict to entries with effort smaller-or-equal, equal, -or larger-or-equal than the selected value. If the digits 0-9 are not used -as fast access keys to tags, you can also simply press the index digit -directly without an operator. In this case, @kbd{<} will be assumed. For -application of the operator, entries without a defined effort will be treated -according to the value of @code{org-sort-agenda-noeffort-is-high}. To filter -for tasks without effort definition, press @kbd{?} as the operator. - -Org also supports automatic, context-aware tag filtering. If the variable -@code{org-agenda-auto-exclude-function} is set to a user-defined function, -that function can decide which tags should be excluded from the agenda -automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET} -as a sub-option key and runs the auto exclusion logic. For example, let's -say you use a @code{Net} tag to identify tasks which need network access, an -@code{Errand} tag for errands in town, and a @code{Call} tag for making phone -calls. You could auto-exclude these tags based on the availability of the -Internet, and outside of business hours, with something like this: - -@lisp -@group -(defun org-my-auto-exclude-function (tag) - (and (cond - ((string= tag "Net") - (/= 0 (call-process "/sbin/ping" nil nil nil - "-c1" "-q" "-t1" "mail.gnu.org"))) - ((or (string= tag "Errand") (string= tag "Call")) - (let ((hour (nth 2 (decode-time)))) - (or (< hour 8) (> hour 21))))) - (concat "-" tag))) - -(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function) -@end group -@end lisp - -@orgcmd{\\,org-agenda-filter-by-tag-refine} -Narrow the current agenda filter by an additional condition. When called with -prefix arg, remove the entries that @emph{do} have the tag, or that do match -the effort criterion. You can achieve the same effect by pressing @kbd{+} or -@kbd{-} as the first key after the @kbd{/} command. - -@c -@kindex [ -@kindex ] -@kindex @{ -@kindex @} -@item [ ] @{ @} -@table @i -@item @r{in} search view -add new search words (@kbd{[} and @kbd{]}) or new regular expressions -(@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will -add a positive search term prefixed by @samp{+}, indicating that this search -term @i{must} occur/match in the entry. The closing bracket/brace will add a -negative search term which @i{must not} occur/match in the entry for it to be -selected. -@end table - -@tsubheading{Remote editing} -@cindex remote editing, from agenda - -@item 0-9 -Digit argument. -@c -@cindex undoing remote-editing events -@cindex remote editing, undo -@orgcmd{C-_,org-agenda-undo} -Undo a change due to a remote editing command. The change is undone -both in the agenda buffer and in the remote buffer. -@c -@orgcmd{t,org-agenda-todo} -Change the TODO state of the item, both in the agenda and in the -original org file. -@c -@orgcmd{C-S-@key{right},org-agenda-todo-nextset} -@orgcmd{C-S-@key{left},org-agenda-todo-previousset} -Switch to the next/previous set of TODO keywords. -@c -@orgcmd{C-k,org-agenda-kill} -@vindex org-agenda-confirm-kill -Delete the current agenda item along with the entire subtree belonging -to it in the original Org file. If the text to be deleted remotely -is longer than one line, the kill needs to be confirmed by the user. See -variable @code{org-agenda-confirm-kill}. -@c -@orgcmd{C-c C-w,org-agenda-refile} -Refile the entry at point. -@c -@orgcmdkskc{C-c C-x C-a,a,org-agenda-archive-default-with-confirmation} -@vindex org-archive-default-command -Archive the subtree corresponding to the entry at point using the default -archiving command set in @code{org-archive-default-command}. When using the -@code{a} key, confirmation will be required. -@c -@orgcmd{C-c C-x a,org-agenda-toggle-archive-tag} -Toggle the ARCHIVE tag for the current headline. -@c -@orgcmd{C-c C-x A,org-agenda-archive-to-archive-sibling} -Move the subtree corresponding to the current entry to its @emph{archive -sibling}. -@c -@orgcmdkskc{C-c C-x C-s,$,org-agenda-archive} -Archive the subtree corresponding to the current headline. This means the -entry will be moved to the configured archive location, most likely a -different file. -@c -@orgcmd{T,org-agenda-show-tags} -@vindex org-agenda-show-inherited-tags -Show all tags associated with the current item. This is useful if you have -turned off @code{org-agenda-show-inherited-tags}, but still want to see all -tags of a headline occasionally. -@c -@orgcmd{:,org-agenda-set-tags} -Set tags for the current headline. If there is an active region in the -agenda, change a tag for all headings in the region. -@c -@kindex , -@item , -Set the priority for the current item (@command{org-agenda-priority}). -Org mode prompts for the priority character. If you reply with @key{SPC}, -the priority cookie is removed from the entry. -@c -@orgcmd{P,org-agenda-show-priority} -Display weighted priority of current item. -@c -@orgcmdkkc{+,S-@key{up},org-agenda-priority-up} -Increase the priority of the current item. The priority is changed in -the original buffer, but the agenda is not resorted. Use the @kbd{r} -key for this. -@c -@orgcmdkkc{-,S-@key{down},org-agenda-priority-down} -Decrease the priority of the current item. -@c -@orgcmdkkc{z,C-c C-z,org-agenda-add-note} -@vindex org-log-into-drawer -Add a note to the entry. This note will be recorded, and then filed to the -same location where state change notes are put. Depending on -@code{org-log-into-drawer}, this may be inside a drawer. -@c -@orgcmd{C-c C-a,org-attach} -Dispatcher for all command related to attachments. -@c -@orgcmd{C-c C-s,org-agenda-schedule} -Schedule this item. With prefix arg remove the scheduling timestamp -@c -@orgcmd{C-c C-d,org-agenda-deadline} -Set a deadline for this item. With prefix arg remove the deadline. -@c -@orgcmd{k,org-agenda-action} -Agenda actions, to set dates for selected items to the cursor date. -This command also works in the calendar! The command prompts for an -additional key: -@example -m @r{Mark the entry at point for action. You can also make entries} - @r{in Org files with @kbd{C-c C-x C-k}.} -d @r{Set the deadline of the marked entry to the date at point.} -s @r{Schedule the marked entry at the date at point.} -r @r{Call @code{org-capture} with the cursor date as default date.} -@end example -@noindent -Press @kbd{r} afterward to refresh the agenda and see the effect of the -command. -@c -@orgcmd{S-@key{right},org-agenda-do-date-later} -Change the timestamp associated with the current line by one day into the -future. If the date is in the past, the first call to this command will move -it to today.@* -With a numeric prefix argument, change it by that many days. For example, -@kbd{3 6 5 S-@key{right}} will change it by a year. With a @kbd{C-u} prefix, -change the time by one hour. If you immediately repeat the command, it will -continue to change hours even without the prefix arg. With a double @kbd{C-u -C-u} prefix, do the same for changing minutes.@* -The stamp is changed in the original Org file, but the change is not directly -reflected in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer. -@c -@orgcmd{S-@key{left},org-agenda-do-date-earlier} -Change the timestamp associated with the current line by one day -into the past. -@c -@orgcmd{>,org-agenda-date-prompt} -Change the timestamp associated with the current line. The key @kbd{>} has -been chosen, because it is the same as @kbd{S-.} on my keyboard. -@c -@orgcmd{I,org-agenda-clock-in} -Start the clock on the current item. If a clock is running already, it -is stopped first. -@c -@orgcmd{O,org-agenda-clock-out} -Stop the previously started clock. -@c -@orgcmd{X,org-agenda-clock-cancel} -Cancel the currently running clock. -@c -@orgcmd{J,org-agenda-clock-goto} -Jump to the running clock in another window. - -@tsubheading{Bulk remote editing selected entries} -@cindex remote editing, bulk, from agenda - -@orgcmd{m,org-agenda-bulk-mark} -Mark the entry at point for bulk action. With prefix arg, mark that many -successive entries. -@c -@orgcmd{%,org-agenda-bulk-mark-regexp} -Mark entries matching a regular expression for bulk action. -@c -@orgcmd{u,org-agenda-bulk-unmark} -Unmark entry for bulk action. -@c -@orgcmd{U,org-agenda-bulk-remove-all-marks} -Unmark all marked entries for bulk action. -@c -@orgcmd{B,org-agenda-bulk-action} -Bulk action: act on all marked entries in the agenda. This will prompt for -another key to select the action to be applied. The prefix arg to @kbd{B} -will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-remove -these special timestamps. -@example -r @r{Prompt for a single refile target and move all entries. The entries} - @r{will no longer be in the agenda; refresh (@kbd{g}) to bring them back.} -$ @r{Archive all selected entries.} -A @r{Archive entries by moving them to their respective archive siblings.} -t @r{Change TODO state. This prompts for a single TODO keyword and} - @r{changes the state of all selected entries, bypassing blocking and} - @r{suppressing logging notes (but not timestamps).} -+ @r{Add a tag to all selected entries.} -- @r{Remove a tag from all selected entries.} -s @r{Schedule all items to a new date. To shift existing schedule dates} - @r{by a fixed number of days, use something starting with double plus} - @r{at the prompt, for example @samp{++8d} or @samp{++2w}.} -S @r{Reschedule randomly into the coming N days. N will be prompted for.} - @r{With prefix arg (@kbd{C-u B S}), scatter only across weekdays.} -d @r{Set deadline to a specific date.} -f @r{Apply a function to marked entries.} - @r{For example, the function below sets the CATEGORY property of the} - @r{entries to web.} - @r{(defun set-category ()} - @r{ (interactive "P")} - @r{ (let* ((marker (or (org-get-at-bol 'org-hd-marker)} - @r{ (org-agenda-error)))} - @r{ (buffer (marker-buffer marker)))} - @r{ (with-current-buffer buffer} - @r{ (save-excursion} - @r{ (save-restriction} - @r{ (widen)} - @r{ (goto-char marker)} - @r{ (org-back-to-heading t)} - @r{ (org-set-property "CATEGORY" "web"))))))} -@end example - - -@tsubheading{Calendar commands} -@cindex calendar commands, from agenda - -@orgcmd{c,org-agenda-goto-calendar} -Open the Emacs calendar and move to the date at the agenda cursor. -@c -@orgcmd{c,org-calendar-goto-agenda} -When in the calendar, compute and show the Org mode agenda for the -date at the cursor. -@c -@cindex diary entries, creating from agenda -@orgcmd{i,org-agenda-diary-entry} -@vindex org-agenda-diary-file -Insert a new entry into the diary, using the date at the cursor and (for -block entries) the date at the mark. This will add to the Emacs diary -file@footnote{This file is parsed for the agenda when -@code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i} -command in the calendar. The diary file will pop up in another window, where -you can add the entry. - -If you configure @code{org-agenda-diary-file} to point to an Org mode file, -Org will create entries (in Org mode syntax) in that file instead. Most -entries will be stored in a date-based outline tree that will later make it -easy to archive appointments from previous months/years. The tree will be -built under an entry with a @code{DATE_TREE} property, or else with years as -top-level entries. Emacs will prompt you for the entry text---if you specify -it, the entry will be created in @code{org-agenda-diary-file} without further -interaction. If you directly press @key{RET} at the prompt without typing -text, the target file will be shown in another window for you to finish the -entry there. See also the @kbd{k r} command. -@c -@orgcmd{M,org-agenda-phases-of-moon} -Show the phases of the moon for the three months around current date. -@c -@orgcmd{S,org-agenda-sunrise-sunset} -Show sunrise and sunset times. The geographical location must be set -with calendar variables, see the documentation for the Emacs calendar. -@c -@orgcmd{C,org-agenda-convert-date} -Convert the date at cursor into many other cultural and historic -calendars. -@c -@orgcmd{H,org-agenda-holidays} -Show holidays for three months around the cursor date. - -@item M-x org-export-icalendar-combine-agenda-files -Export a single iCalendar file containing entries from all agenda files. -This is a globally available command, and also available in the agenda menu. - -@tsubheading{Exporting to a file} -@orgcmd{C-x C-w,org-write-agenda} -@cindex exporting agenda views -@cindex agenda views, exporting -@vindex org-agenda-exporter-settings -Write the agenda view to a file. Depending on the extension of the selected -file name, the view will be exported as HTML (extension @file{.html} or -@file{.htm}), Postscript (extension @file{.ps}), PDF (extension @file{.pdf}), -and plain text (any other extension). When called with a @kbd{C-u} prefix -argument, immediately open the newly created file. Use the variable -@code{org-agenda-exporter-settings} to set options for @file{ps-print} and -for @file{htmlize} to be used during export. - -@tsubheading{Quit and Exit} -@orgcmd{q,org-agenda-quit} -Quit agenda, remove the agenda buffer. -@c -@cindex agenda files, removing buffers -@orgcmd{x,org-agenda-exit} -Exit agenda, remove the agenda buffer and all buffers loaded by Emacs -for the compilation of the agenda. Buffers created by the user to -visit Org files will not be removed. -@end table - - -@node Custom agenda views, Exporting Agenda Views, Agenda commands, Agenda Views -@section Custom agenda views -@cindex custom agenda views -@cindex agenda views, custom - -Custom agenda commands serve two purposes: to store and quickly access -frequently used TODO and tags searches, and to create special composite -agenda buffers. Custom agenda commands will be accessible through the -dispatcher (@pxref{Agenda dispatcher}), just like the default commands. - -@menu -* Storing searches:: Type once, use often -* Block agenda:: All the stuff you need in a single buffer -* Setting Options:: Changing the rules -@end menu - -@node Storing searches, Block agenda, Custom agenda views, Custom agenda views -@subsection Storing searches - -The first application of custom searches is the definition of keyboard -shortcuts for frequently used searches, either creating an agenda -buffer, or a sparse tree (the latter covering of course only the current -buffer). -@kindex C-c a C -@vindex org-agenda-custom-commands -Custom commands are configured in the variable -@code{org-agenda-custom-commands}. You can customize this variable, for -example by pressing @kbd{C-c a C}. You can also directly set it with -Emacs Lisp in @file{.emacs}. The following example contains all valid -search types: - -@lisp -@group -(setq org-agenda-custom-commands - '(("w" todo "WAITING") - ("W" todo-tree "WAITING") - ("u" tags "+boss-urgent") - ("v" tags-todo "+boss-urgent") - ("U" tags-tree "+boss-urgent") - ("f" occur-tree "\\") - ("h" . "HOME+Name tags searches") ; description for "h" prefix - ("hl" tags "+home+Lisa") - ("hp" tags "+home+Peter") - ("hk" tags "+home+Kim"))) -@end group -@end lisp - -@noindent -The initial string in each entry defines the keys you have to press -after the dispatcher command @kbd{C-c a} in order to access the command. -Usually this will be just a single character, but if you have many -similar commands, you can also define two-letter combinations where the -first character is the same in several combinations and serves as a -prefix key@footnote{You can provide a description for a prefix key by -inserting a cons cell with the prefix and the description.}. The second -parameter is the search type, followed by the string or regular -expression to be used for the matching. The example above will -therefore define: - -@table @kbd -@item C-c a w -as a global search for TODO entries with @samp{WAITING} as the TODO -keyword -@item C-c a W -as the same search, but only in the current buffer and displaying the -results as a sparse tree -@item C-c a u -as a global tags search for headlines marked @samp{:boss:} but not -@samp{:urgent:} -@item C-c a v -as the same search as @kbd{C-c a u}, but limiting the search to -headlines that are also TODO items -@item C-c a U -as the same search as @kbd{C-c a u}, but only in the current buffer and -displaying the result as a sparse tree -@item C-c a f -to create a sparse tree (again: current buffer only) with all entries -containing the word @samp{FIXME} -@item C-c a h -as a prefix command for a HOME tags search where you have to press an -additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa, -Peter, or Kim) as additional tag to match. -@end table - -@node Block agenda, Setting Options, Storing searches, Custom agenda views -@subsection Block agenda -@cindex block agenda -@cindex agenda, with block views - -Another possibility is the construction of agenda views that comprise -the results of @emph{several} commands, each of which creates a block in -the agenda buffer. The available commands include @code{agenda} for the -daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo} -for the global TODO list (as constructed with @kbd{C-c a t}), and the -matching commands discussed above: @code{todo}, @code{tags}, and -@code{tags-todo}. Here are two examples: - -@lisp -@group -(setq org-agenda-custom-commands - '(("h" "Agenda and Home-related tasks" - ((agenda "") - (tags-todo "home") - (tags "garden"))) - ("o" "Agenda and Office-related tasks" - ((agenda "") - (tags-todo "work") - (tags "office"))))) -@end group -@end lisp - -@noindent -This will define @kbd{C-c a h} to create a multi-block view for stuff -you need to attend to at home. The resulting agenda buffer will contain -your agenda for the current week, all TODO items that carry the tag -@samp{home}, and also all lines tagged with @samp{garden}. Finally the -command @kbd{C-c a o} provides a similar view for office tasks. - -@node Setting Options, , Block agenda, Custom agenda views -@subsection Setting options for custom commands -@cindex options, for custom agenda views - -@vindex org-agenda-custom-commands -Org mode contains a number of variables regulating agenda construction -and display. The global variables define the behavior for all agenda -commands, including the custom commands. However, if you want to change -some settings just for a single custom view, you can do so. Setting -options requires inserting a list of variable names and values at the -right spot in @code{org-agenda-custom-commands}. For example: - -@lisp -@group -(setq org-agenda-custom-commands - '(("w" todo "WAITING" - ((org-agenda-sorting-strategy '(priority-down)) - (org-agenda-prefix-format " Mixed: "))) - ("U" tags-tree "+boss-urgent" - ((org-show-following-heading nil) - (org-show-hierarchy-above nil))) - ("N" search "" - ((org-agenda-files '("~org/notes.org")) - (org-agenda-text-search-extra-files nil))))) -@end group -@end lisp - -@noindent -Now the @kbd{C-c a w} command will sort the collected entries only by -priority, and the prefix format is modified to just say @samp{ Mixed: } -instead of giving the category of the entry. The sparse tags tree of -@kbd{C-c a U} will now turn out ultra-compact, because neither the -headline hierarchy above the match, nor the headline following the match -will be shown. The command @kbd{C-c a N} will do a text search limited -to only a single file. - -@vindex org-agenda-custom-commands -For command sets creating a block agenda, -@code{org-agenda-custom-commands} has two separate spots for setting -options. You can add options that should be valid for just a single -command in the set, and options that should be valid for all commands in -the set. The former are just added to the command entry; the latter -must come after the list of command entries. Going back to the block -agenda example (@pxref{Block agenda}), let's change the sorting strategy -for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort -the results for GARDEN tags query in the opposite order, -@code{priority-up}. This would look like this: - -@lisp -@group -(setq org-agenda-custom-commands - '(("h" "Agenda and Home-related tasks" - ((agenda) - (tags-todo "home") - (tags "garden" - ((org-agenda-sorting-strategy '(priority-up))))) - ((org-agenda-sorting-strategy '(priority-down)))) - ("o" "Agenda and Office-related tasks" - ((agenda) - (tags-todo "work") - (tags "office"))))) -@end group -@end lisp - -As you see, the values and parentheses setting is a little complex. -When in doubt, use the customize interface to set this variable---it -fully supports its structure. Just one caveat: when setting options in -this interface, the @emph{values} are just Lisp expressions. So if the -value is a string, you need to add the double-quotes around the value -yourself. - - -@node Exporting Agenda Views, Agenda column view, Custom agenda views, Agenda Views -@section Exporting Agenda Views -@cindex agenda views, exporting - -If you are away from your computer, it can be very useful to have a printed -version of some agenda views to carry around. Org mode can export custom -agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's -@file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the -ghostscript @file{ps2pdf} utility must be installed on the system. Selecting -a PDF file will also create the postscript file.}, and iCalendar files. If -you want to do this only occasionally, use the command - -@table @kbd -@orgcmd{C-x C-w,org-write-agenda} -@cindex exporting agenda views -@cindex agenda views, exporting -@vindex org-agenda-exporter-settings -Write the agenda view to a file. Depending on the extension of the selected -file name, the view will be exported as HTML (extension @file{.html} or -@file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension -@file{.ics}), or plain text (any other extension). Use the variable -@code{org-agenda-exporter-settings} to set options for @file{ps-print} and -for @file{htmlize} to be used during export, for example - -@vindex org-agenda-add-entry-text-maxlines -@vindex htmlize-output-type -@vindex ps-number-of-columns -@vindex ps-landscape-mode -@lisp -(setq org-agenda-exporter-settings - '((ps-number-of-columns 2) - (ps-landscape-mode t) - (org-agenda-add-entry-text-maxlines 5) - (htmlize-output-type 'css))) -@end lisp -@end table - -If you need to export certain agenda views frequently, you can associate -any custom agenda command with a list of output file names -@footnote{If you want to store standard views like the weekly agenda -or the global TODO list as well, you need to define custom commands for -them in order to be able to specify file names.}. Here is an example -that first defines custom commands for the agenda and the global -TODO list, together with a number of files to which to export them. -Then we define two block agenda commands and specify file names for them -as well. File names can be relative to the current working directory, -or absolute. - -@lisp -@group -(setq org-agenda-custom-commands - '(("X" agenda "" nil ("agenda.html" "agenda.ps")) - ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps")) - ("h" "Agenda and Home-related tasks" - ((agenda "") - (tags-todo "home") - (tags "garden")) - nil - ("~/views/home.html")) - ("o" "Agenda and Office-related tasks" - ((agenda) - (tags-todo "work") - (tags "office")) - nil - ("~/views/office.ps" "~/calendars/office.ics")))) -@end group -@end lisp - -The extension of the file name determines the type of export. If it is -@file{.html}, Org mode will use the @file{htmlize.el} package to convert -the buffer to HTML and save it to this file name. If the extension is -@file{.ps}, @code{ps-print-buffer-with-faces} is used to produce -Postscript output. If the extension is @file{.ics}, iCalendar export is -run export over all files that were used to construct the agenda, and -limit the export to entries listed in the agenda. Any other -extension produces a plain ASCII file. - -The export files are @emph{not} created when you use one of those -commands interactively because this might use too much overhead. -Instead, there is a special command to produce @emph{all} specified -files in one step: - -@table @kbd -@orgcmd{C-c a e,org-store-agenda-views} -Export all agenda views that have export file names associated with -them. -@end table - -You can use the options section of the custom agenda commands to also -set options for the export commands. For example: - -@lisp -(setq org-agenda-custom-commands - '(("X" agenda "" - ((ps-number-of-columns 2) - (ps-landscape-mode t) - (org-agenda-prefix-format " [ ] ") - (org-agenda-with-colors nil) - (org-agenda-remove-tags t)) - ("theagenda.ps")))) -@end lisp - -@noindent -This command sets two options for the Postscript exporter, to make it -print in two columns in landscape format---the resulting page can be cut -in two and then used in a paper agenda. The remaining settings modify -the agenda prefix to omit category and scheduling information, and -instead include a checkbox to check off items. We also remove the tags -to make the lines compact, and we don't want to use colors for the -black-and-white printer. Settings specified in -@code{org-agenda-exporter-settings} will also apply, but the settings -in @code{org-agenda-custom-commands} take precedence. - -@noindent -From the command line you may also use -@example -emacs -eval (org-batch-store-agenda-views) -kill -@end example -@noindent -or, if you need to modify some parameters@footnote{Quoting depends on the -system you use, please check the FAQ for examples.} -@example -emacs -eval '(org-batch-store-agenda-views \ - org-agenda-span (quote month) \ - org-agenda-start-day "2007-11-01" \ - org-agenda-include-diary nil \ - org-agenda-files (quote ("~/org/project.org")))' \ - -kill -@end example -@noindent -which will create the agenda views restricted to the file -@file{~/org/project.org}, without diary entries and with a 30-day -extent. - -You can also extract agenda information in a way that allows further -processing by other programs. See @ref{Extracting agenda information}, for -more information. - - -@node Agenda column view, , Exporting Agenda Views, Agenda Views -@section Using column view in the agenda -@cindex column view, in agenda -@cindex agenda, column view - -Column view (@pxref{Column view}) is normally used to view and edit -properties embedded in the hierarchical structure of an Org file. It can be -quite useful to use column view also from the agenda, where entries are -collected by certain criteria. - -@table @kbd -@orgcmd{C-c C-x C-c,org-agenda-columns} -Turn on column view in the agenda. -@end table - -To understand how to use this properly, it is important to realize that the -entries in the agenda are no longer in their proper outline environment. -This causes the following issues: - -@enumerate -@item -@vindex org-columns-default-format -@vindex org-overriding-columns-format -Org needs to make a decision which @code{COLUMNS} format to use. Since the -entries in the agenda are collected from different files, and different files -may have different @code{COLUMNS} formats, this is a non-trivial problem. -Org first checks if the variable @code{org-agenda-overriding-columns-format} is -currently set, and if so, takes the format from there. Otherwise it takes -the format associated with the first item in the agenda, or, if that item -does not have a specific format (defined in a property, or in its file), it -uses @code{org-columns-default-format}. -@item -@cindex property, special, CLOCKSUM -If any of the columns has a summary type defined (@pxref{Column attributes}), -turning on column view in the agenda will visit all relevant agenda files and -make sure that the computations of this property are up to date. This is -also true for the special @code{CLOCKSUM} property. Org will then sum the -values displayed in the agenda. In the daily/weekly agenda, the sums will -cover a single day; in all other views they cover the entire block. It is -vital to realize that the agenda may show the same entry @emph{twice} (for -example as scheduled and as a deadline), and it may show two entries from the -same hierarchy (for example a @emph{parent} and its @emph{child}). In these -cases, the summation in the agenda will lead to incorrect results because -some values will count double. -@item -When the column view in the agenda shows the @code{CLOCKSUM}, that is always -the entire clocked time for this item. So even in the daily/weekly agenda, -the clocksum listed in column view may originate from times outside the -current view. This has the advantage that you can compare these values with -a column listing the planned total effort for a task---one of the major -applications for column view in the agenda. If you want information about -clocked time in the displayed period use clock table mode (press @kbd{R} in -the agenda). -@end enumerate - - -@node Markup, Exporting, Agenda Views, Top -@chapter Markup for rich export - -When exporting Org mode documents, the exporter tries to reflect the -structure of the document as accurately as possible in the backend. Since -export targets like HTML, @LaTeX{}, or DocBook allow much richer formatting, -Org mode has rules on how to prepare text for rich export. This section -summarizes the markup rules used in an Org mode buffer. - -@menu -* Structural markup elements:: The basic structure as seen by the exporter -* Images and tables:: Tables and Images will be included -* Literal examples:: Source code examples with special formatting -* Include files:: Include additional files into a document -* Index entries:: Making an index -* Macro replacement:: Use macros to create complex output -* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents -@end menu - -@node Structural markup elements, Images and tables, Markup, Markup -@section Structural markup elements - -@menu -* Document title:: Where the title is taken from -* Headings and sections:: The document structure as seen by the exporter -* Table of contents:: The if and where of the table of contents -* Initial text:: Text before the first heading? -* Lists:: Lists -* Paragraphs:: Paragraphs -* Footnote markup:: Footnotes -* Emphasis and monospace:: Bold, italic, etc. -* Horizontal rules:: Make a line -* Comment lines:: What will *not* be exported -@end menu - -@node Document title, Headings and sections, Structural markup elements, Structural markup elements -@subheading Document title -@cindex document title, markup rules - -@noindent -The title of the exported document is taken from the special line - -@cindex #+TITLE -@example -#+TITLE: This is the title of the document -@end example - -@noindent -If this line does not exist, the title is derived from the first non-empty, -non-comment line in the buffer. If no such line exists, or if you have -turned off exporting of the text before the first headline (see below), the -title will be the file name without extension. - -@cindex property, EXPORT_TITLE -If you are exporting only a subtree by marking is as the region, the heading -of the subtree will become the title of the document. If the subtree has a -property @code{EXPORT_TITLE}, that will take precedence. - -@node Headings and sections, Table of contents, Document title, Structural markup elements -@subheading Headings and sections -@cindex headings and sections, markup rules - -@vindex org-export-headline-levels -The outline structure of the document as described in @ref{Document -Structure}, forms the basis for defining sections of the exported document. -However, since the outline structure is also used for (for example) lists of -tasks, only the first three outline levels will be used as headings. Deeper -levels will become itemized lists. You can change the location of this -switch globally by setting the variable @code{org-export-headline-levels}, or on a -per-file basis with a line - -@cindex #+OPTIONS -@example -#+OPTIONS: H:4 -@end example - -@node Table of contents, Initial text, Headings and sections, Structural markup elements -@subheading Table of contents -@cindex table of contents, markup rules - -@vindex org-export-with-toc -The table of contents is normally inserted directly before the first headline -of the file. If you would like to get it to a different location, insert the -string @code{[TABLE-OF-CONTENTS]} on a line by itself at the desired -location. The depth of the table of contents is by default the same as the -number of headline levels, but you can choose a smaller number, or turn off -the table of contents entirely, by configuring the variable -@code{org-export-with-toc}, or on a per-file basis with a line like - -@example -#+OPTIONS: toc:2 (only to two levels in TOC) -#+OPTIONS: toc:nil (no TOC at all) -@end example - -@node Initial text, Lists, Table of contents, Structural markup elements -@subheading Text before the first headline -@cindex text before first headline, markup rules -@cindex #+TEXT - -Org mode normally exports the text before the first headline, and even uses -the first line as the document title. The text will be fully marked up. If -you need to include literal HTML, @LaTeX{}, or DocBook code, use the special -constructs described below in the sections for the individual exporters. - -@vindex org-export-skip-text-before-1st-heading -Some people like to use the space before the first headline for setup and -internal links and therefore would like to control the exported text before -the first headline in a different way. You can do so by setting the variable -@code{org-export-skip-text-before-1st-heading} to @code{t}. On a per-file -basis, you can get the same effect with @samp{#+OPTIONS: skip:t}. - -@noindent -If you still want to have some text before the first headline, use the -@code{#+TEXT} construct: - -@example -#+OPTIONS: skip:t -#+TEXT: This text will go before the *first* headline. -#+TEXT: [TABLE-OF-CONTENTS] -#+TEXT: This goes between the table of contents and the *first* headline -@end example - -@node Lists, Paragraphs, Initial text, Structural markup elements -@subheading Lists -@cindex lists, markup rules - -Plain lists as described in @ref{Plain lists}, are translated to the backend's -syntax for such lists. Most backends support unordered, ordered, and -description lists. - -@node Paragraphs, Footnote markup, Lists, Structural markup elements -@subheading Paragraphs, line breaks, and quoting -@cindex paragraphs, markup rules - -Paragraphs are separated by at least one empty line. If you need to enforce -a line break within a paragraph, use @samp{\\} at the end of a line. - -To keep the line breaks in a region, but otherwise use normal formatting, you -can use this construct, which can also be used to format poetry. - -@cindex #+BEGIN_VERSE -@example -#+BEGIN_VERSE - Great clouds overhead - Tiny black birds rise and fall - Snow covers Emacs - - -- AlexSchroeder -#+END_VERSE -@end example - -When quoting a passage from another document, it is customary to format this -as a paragraph that is indented on both the left and the right margin. You -can include quotations in Org mode documents like this: - -@cindex #+BEGIN_QUOTE -@example -#+BEGIN_QUOTE -Everything should be made as simple as possible, -but not any simpler -- Albert Einstein -#+END_QUOTE -@end example - -If you would like to center some text, do it like this: -@cindex #+BEGIN_CENTER -@example -#+BEGIN_CENTER -Everything should be made as simple as possible, \\ -but not any simpler -#+END_CENTER -@end example - - -@node Footnote markup, Emphasis and monospace, Paragraphs, Structural markup elements -@subheading Footnote markup -@cindex footnotes, markup rules -@cindex @file{footnote.el} - -Footnotes defined in the way described in @ref{Footnotes}, will be exported -by all backends. Org allows multiple references to the same note, and -multiple footnotes side by side. - -@node Emphasis and monospace, Horizontal rules, Footnote markup, Structural markup elements -@subheading Emphasis and monospace - -@cindex underlined text, markup rules -@cindex bold text, markup rules -@cindex italic text, markup rules -@cindex verbatim text, markup rules -@cindex code text, markup rules -@cindex strike-through text, markup rules -You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} -and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text -in the code and verbatim string is not processed for Org mode specific -syntax; it is exported verbatim. - -@node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements -@subheading Horizontal rules -@cindex horizontal rules, markup rules -A line consisting of only dashes, and at least 5 of them, will be exported as -a horizontal line (@samp{
} in HTML and @code{\hrule} in @LaTeX{}). - -@node Comment lines, , Horizontal rules, Structural markup elements -@subheading Comment lines -@cindex comment lines -@cindex exporting, not -@cindex #+BEGIN_COMMENT - -Lines starting with @samp{#} in column zero are treated as comments and will -never be exported. If you want an indented line to be treated as a comment, -start it with @samp{#+ }. Also entire subtrees starting with the word -@samp{COMMENT} will never be exported. Finally, regions surrounded by -@samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported. - -@table @kbd -@kindex C-c ; -@item C-c ; -Toggle the COMMENT keyword at the beginning of an entry. -@end table - - -@node Images and tables, Literal examples, Structural markup elements, Markup -@section Images and Tables - -@cindex tables, markup rules -@cindex #+CAPTION -@cindex #+LABEL -Both the native Org mode tables (@pxref{Tables}) and tables formatted with -the @file{table.el} package will be exported properly. For Org mode tables, -the lines before the first horizontal separator line will become table header -lines. You can use the following lines somewhere before the table to assign -a caption and a label for cross references, and in the text you can refer to -the object with @code{\ref@{tab:basic-data@}}: - -@example -#+CAPTION: This is the caption for the next table (or link) -#+LABEL: tbl:basic-data - | ... | ...| - |-----|----| -@end example - -Optionally, the caption can take the form: -@example -#+CAPTION: [Caption for list of figures]@{Caption for table (or link).@} -@end example - -@cindex inlined images, markup rules -Some backends (HTML, @LaTeX{}, and DocBook) allow you to directly include -images into the exported document. Org does this, if a link to an image -files does not have a description part, for example @code{[[./img/a.jpg]]}. -If you wish to define a caption for the image and maybe a label for internal -cross references, make sure that the link is on a line by itself and precede -it with @code{#+CAPTION} and @code{#+LABEL} as follows: - -@example -#+CAPTION: This is the caption for the next figure link (or table) -#+LABEL: fig:SED-HR4049 -[[./img/a.jpg]] -@end example - -You may also define additional attributes for the figure. As this is -backend-specific, see the sections about the individual backends for more -information. - -@xref{Handling links,the discussion of image links}. - -@node Literal examples, Include files, Images and tables, Markup -@section Literal examples -@cindex literal examples, markup rules -@cindex code line references, markup rules - -You can include literal examples that should not be subjected to -markup. Such examples will be typeset in monospace, so this is well suited -for source code and similar examples. -@cindex #+BEGIN_EXAMPLE - -@example -#+BEGIN_EXAMPLE -Some example from a text file. -#+END_EXAMPLE -@end example - -Note that such blocks may be @i{indented} in order to align nicely with -indented text and in particular with plain list structure (@pxref{Plain -lists}). For simplicity when using small examples, you can also start the -example lines with a colon followed by a space. There may also be additional -whitespace before the colon: - -@example -Here is an example - : Some example from a text file. -@end example - -@cindex formatting source code, markup rules -If the example is source code from a programming language, or any other text -that can be marked up by font-lock in Emacs, you can ask for the example to -look like the fontified Emacs buffer@footnote{This works automatically for -the HTML backend (it requires version 1.34 of the @file{htmlize.el} package, -which is distributed with Org). Fontified code chunks in @LaTeX{} can be -achieved using either the listings or the -@url{http://code.google.com/p/minted, minted,} package. To use listings, turn -on the variable @code{org-export-latex-listings} and ensure that the listings -package is included by the @LaTeX{} header (e.g.@: by configuring -@code{org-export-latex-packages-alist}). See the listings documentation for -configuration options, including obtaining colored output. For minted it is -necessary to install the program @url{http://pygments.org, pygments}, in -addition to setting @code{org-export-latex-minted}, ensuring that the minted -package is included by the @LaTeX{} header, and ensuring that the -@code{-shell-escape} option is passed to @file{pdflatex} (see -@code{org-latex-to-pdf-process}). See the documentation of the variables -@code{org-export-latex-listings} and @code{org-export-latex-minted} for -further details.}. This is done with the @samp{src} block, where you also -need to specify the name of the major mode that should be used to fontify the -example@footnote{Code in @samp{src} blocks may also be evaluated either -interactively or on export. See @pxref{Working With Source Code} for more -information on evaluating code blocks.}, see @ref{Easy Templates} for -shortcuts to easily insert code blocks. -@cindex #+BEGIN_SRC - -@example -#+BEGIN_SRC emacs-lisp - (defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) -#+END_SRC -@end example - -Both in @code{example} and in @code{src} snippets, you can add a @code{-n} -switch to the end of the @code{BEGIN} line, to get the lines of the example -numbered. If you use a @code{+n} switch, the numbering from the previous -numbered snippet will be continued in the current one. In literal examples, -Org will interpret strings like @samp{(ref:name)} as labels, and use them as -targets for special hyperlinks like @code{[[(name)]]} (i.e.@: the reference name -enclosed in single parenthesis). In HTML, hovering the mouse over such a -link will remote-highlight the corresponding code line, which is kind of -cool. - -You can also add a @code{-r} switch which @i{removes} the labels from the -source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the -labels in the source code while using line numbers for the links, which might -be useful to explain those in an Org mode example code.}. With the @code{-n} -switch, links to these references will be labeled by the line numbers from -the code listing, otherwise links will use the labels with no parentheses. -Here is an example: - -@example -#+BEGIN_SRC emacs-lisp -n -r -(save-excursion (ref:sc) - (goto-char (point-min)) (ref:jump) -#+END_SRC -In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]] -jumps to point-min. -@end example - -@vindex org-coderef-label-format -If the syntax for the label format conflicts with the language syntax, use a -@code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal --n -r -l "((%s))"}. See also the variable @code{org-coderef-label-format}. - -HTML export also allows examples to be published as text areas (@pxref{Text -areas in HTML export}). - -Because the @code{#+BEGIN_...} and @code{#+END_...} patterns need to be added -so often, shortcuts are provided using the Easy Templates facility -(@pxref{Easy Templates}). - -@table @kbd -@kindex C-c ' -@item C-c ' -Edit the source code example at point in its native mode. This works by -switching to a temporary buffer with the source code. You need to exit by -pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*} -or @samp{#} will get a comma prepended, to keep them from being interpreted -by Org as outline nodes or special comments. These commas will be stripped -for editing with @kbd{C-c '}, and also for export.}. The edited version will -then replace the old version in the Org buffer. Fixed-width regions -(where each line starts with a colon followed by a space) will be edited -using @code{artist-mode}@footnote{You may select a different-mode with the -variable @code{org-edit-fixed-width-region-mode}.} to allow creating ASCII -drawings easily. Using this command in an empty line will create a new -fixed-width region. -@kindex C-c l -@item C-c l -Calling @code{org-store-link} while editing a source code example in a -temporary buffer created with @kbd{C-c '} will prompt for a label. Make sure -that it is unique in the current buffer, and insert it with the proper -formatting like @samp{(ref:label)} at the end of the current line. Then the -label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}. -@end table - - -@node Include files, Index entries, Literal examples, Markup -@section Include files -@cindex include files, markup rules - -During export, you can include the content of another file. For example, to -include your @file{.emacs} file, you could use: -@cindex #+INCLUDE - -@example -#+INCLUDE: "~/.emacs" src emacs-lisp -@end example -@noindent -The optional second and third parameter are the markup (e.g.@: @samp{quote}, -@samp{example}, or @samp{src}), and, if the markup is @samp{src}, the -language for formatting the contents. The markup is optional; if it is not -given, the text will be assumed to be in Org mode format and will be -processed normally. The include line will also allow additional keyword -parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the -first line and for each following line, @code{:minlevel} in order to get -Org mode content demoted to a specified level, as well as any options -accepted by the selected markup. For example, to include a file as an item, -use - -@example -#+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " " -@end example - -You can also include a portion of a file by specifying a lines range using -the @code{:lines} parameter. The line at the upper end of the range will not -be included. The start and/or the end of the range may be omitted to use the -obvious defaults. - -@example -#+INCLUDE: "~/.emacs" :lines "5-10" @r{Include lines 5 to 10, 10 excluded} -#+INCLUDE: "~/.emacs" :lines "-10" @r{Include lines 1 to 10, 10 excluded} -#+INCLUDE: "~/.emacs" :lines "10-" @r{Include lines from 10 to EOF} -@end example - -@table @kbd -@kindex C-c ' -@item C-c ' -Visit the include file at point. -@end table - -@node Index entries, Macro replacement, Include files, Markup -@section Index entries -@cindex index entries, for publishing - -You can specify entries that will be used for generating an index during -publishing. This is done by lines starting with @code{#+INDEX}. An entry -the contains an exclamation mark will create a sub item. See @ref{Generating -an index} for more information. - -@example -* Curriculum Vitae -#+INDEX: CV -#+INDEX: Application!CV -@end example - - - - -@node Macro replacement, Embedded @LaTeX{}, Index entries, Markup -@section Macro replacement -@cindex macro replacement, during export -@cindex #+MACRO - -You can define text snippets with - -@example -#+MACRO: name replacement text $1, $2 are arguments -@end example - -@noindent which can be referenced anywhere in the document (even in -code examples) with @code{@{@{@{name(arg1,arg2)@}@}@}}. In addition to -defined macros, @code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc., -will reference information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, and -similar lines. Also, @code{@{@{@{date(@var{FORMAT})@}@}@}} and -@code{@{@{@{modification-time(@var{FORMAT})@}@}@}} refer to current date time -and to the modification time of the file being exported, respectively. -@var{FORMAT} should be a format string understood by -@code{format-time-string}. - -Macro expansion takes place during export, and some people use it to -construct complex HTML code. - - -@node Embedded @LaTeX{}, , Macro replacement, Markup -@section Embedded @LaTeX{} -@cindex @TeX{} interpretation -@cindex @LaTeX{} interpretation - -Plain ASCII is normally sufficient for almost all note taking. Exceptions -include scientific notes, which often require mathematical symbols and the -occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on -Donald E. Knuth's @TeX{} system. Many of the features described here as -``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this -distinction.} is widely used to typeset scientific documents. Org mode -supports embedding @LaTeX{} code into its files, because many academics are -used to writing and reading @LaTeX{} source code, and because it can be -readily processed to produce pretty output for a number of export backends. - -@menu -* Special symbols:: Greek letters and other symbols -* Subscripts and superscripts:: Simple syntax for raising/lowering text -* @LaTeX{} fragments:: Complex formulas made easy -* Previewing @LaTeX{} fragments:: What will this snippet look like? -* CDLaTeX mode:: Speed up entering of formulas -@end menu - -@node Special symbols, Subscripts and superscripts, Embedded @LaTeX{}, Embedded @LaTeX{} -@subsection Special symbols -@cindex math symbols -@cindex special symbols -@cindex @TeX{} macros -@cindex @LaTeX{} fragments, markup rules -@cindex HTML entities -@cindex @LaTeX{} entities - -You can use @LaTeX{} macros to insert special symbols like @samp{\alpha} to -indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion -for these macros is available, just type @samp{\} and maybe a few letters, -and press @kbd{M-@key{TAB}} to see possible completions. Unlike @LaTeX{} -code, Org mode allows these macros to be present without surrounding math -delimiters, for example: - -@example -Angles are written as Greek letters \alpha, \beta and \gamma. -@end example - -@vindex org-entities -During export, these symbols will be transformed into the native format of -the exporter backend. Strings like @code{\alpha} will be exported as -@code{α} in the HTML output, and as @code{$\alpha$} in the @LaTeX{} -output. Similarly, @code{\nbsp} will become @code{ } in HTML and -@code{~} in @LaTeX{}. If you need such a symbol inside a word, terminate it -like this: @samp{\Aacute@{@}stor}. - -A large number of entities is provided, with names taken from both HTML and -@LaTeX{}; see the variable @code{org-entities} for the complete list. -@samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and -@samp{...} are all converted into special commands creating hyphens of -different lengths or a compact set of dots. - -If you would like to see entities displayed as UTF8 characters, use the -following command@footnote{You can turn this on by default by setting the -variable @code{org-pretty-entities}, or on a per-file base with the -@code{#+STARTUP} option @code{entitiespretty}.}: - -@table @kbd -@kindex C-c C-x \ -@item C-c C-x \ -Toggle display of entities as UTF-8 characters. This does not change the -buffer content which remains plain ASCII, but it overlays the UTF-8 character -for display purposes only. -@end table - -@node Subscripts and superscripts, @LaTeX{} fragments, Special symbols, Embedded @LaTeX{} -@subsection Subscripts and superscripts -@cindex subscript -@cindex superscript - -Just like in @LaTeX{}, @samp{^} and @samp{_} are used to indicate super- -and subscripts. Again, these can be used without embedding them in -math-mode delimiters. To increase the readability of ASCII text, it is -not necessary (but OK) to surround multi-character sub- and superscripts -with curly braces. For example - -@example -The mass of the sun is M_sun = 1.989 x 10^30 kg. The radius of -the sun is R_@{sun@} = 6.96 x 10^8 m. -@end example - -@vindex org-export-with-sub-superscripts -To avoid interpretation as raised or lowered text, you can quote @samp{^} and -@samp{_} with a backslash: @samp{\^} and @samp{\_}. If you write a text -where the underscore is often used in a different context, Org's convention -to always interpret these as subscripts can get in your way. Configure the -variable @code{org-export-with-sub-superscripts} to globally change this -convention, or use, on a per-file basis: - -@example -#+OPTIONS: ^:@{@} -@end example - -@noindent With this setting, @samp{a_b} will not be interpreted as a -subscript, but @samp{a_@{b@}} will. - -@table @kbd -@kindex C-c C-x \ -@item C-c C-x \ -In addition to showing entities as UTF-8 characters, this command will also -format sub- and superscripts in a WYSIWYM way. -@end table - -@node @LaTeX{} fragments, Previewing @LaTeX{} fragments, Subscripts and superscripts, Embedded @LaTeX{} -@subsection @LaTeX{} fragments -@cindex @LaTeX{} fragments - -@vindex org-format-latex-header -Going beyond symbols and sub- and superscripts, a full formula language is -needed. Org mode can contain @LaTeX{} math fragments, and it supports ways -to process these for several export backends. When exporting to @LaTeX{}, -the code is obviously left as it is. When exporting to HTML, Org invokes the -@uref{http://www.mathjax.org, MathJax library} (@pxref{Math formatting in -HTML export}) to process and display the math@footnote{If you plan to use -this regularly or on pages with significant page views, you should install -@file{MathJax} on your own -server in order to limit the load of our server.}. Finally, it can also -process the mathematical expressions into images@footnote{For this to work -you need to be on a system with a working @LaTeX{} installation. You also -need the @file{dvipng} program, available at -@url{http://sourceforge.net/projects/dvipng/}. The @LaTeX{} header that will -be used when processing a fragment can be configured with the variable -@code{org-format-latex-header}.} that can be displayed in a browser or in -DocBook documents. - -@LaTeX{} fragments don't need any special marking at all. The following -snippets will be identified as @LaTeX{} source code: -@itemize @bullet -@item -Environments of any kind@footnote{When @file{MathJax} is used, only the -environment recognized by @file{MathJax} will be processed. When -@file{dvipng} is used to create images, any @LaTeX{} environments will be -handled.}. The only requirement is that the @code{\begin} statement appears -on a new line, preceded by only whitespace. -@item -Text within the usual @LaTeX{} math delimiters. To avoid conflicts with -currency specifications, single @samp{$} characters are only recognized as -math delimiters if the enclosed text contains at most two line breaks, is -directly attached to the @samp{$} characters with no whitespace in between, -and if the closing @samp{$} is followed by whitespace, punctuation or a dash. -For the other delimiters, there is no such restriction, so when in doubt, use -@samp{\(...\)} as inline math delimiters. -@end itemize - -@noindent For example: - -@example -\begin@{equation@} % arbitrary environments, -x=\sqrt@{b@} % even tables, figures -\end@{equation@} % etc - -If $a^2=b$ and \( b=2 \), then the solution must be -either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \]. -@end example - -@noindent -@vindex org-format-latex-options -If you need any of the delimiter ASCII sequences for other purposes, you -can configure the option @code{org-format-latex-options} to deselect the -ones you do not wish to have interpreted by the @LaTeX{} converter. - -@vindex org-export-with-LaTeX-fragments -@LaTeX{} processing can be configured with the variable -@code{org-export-with-LaTeX-fragments}. The default setting is @code{t} -which means @file{MathJax} for HTML, and no processing for DocBook, ASCII and -@LaTeX{} backends. You can also set this variable on a per-file basis using one -of these lines: - -@example -#+OPTIONS: LaTeX:t @r{Do the right thing automatically (MathJax)} -#+OPTIONS: LaTeX:dvipng @r{Force using dvipng images} -#+OPTIONS: LaTeX:nil @r{Do not process @LaTeX{} fragments at all} -#+OPTIONS: LaTeX:verbatim @r{Verbatim export, for jsMath or so} -@end example - -@node Previewing @LaTeX{} fragments, CDLaTeX mode, @LaTeX{} fragments, Embedded @LaTeX{} -@subsection Previewing @LaTeX{} fragments -@cindex @LaTeX{} fragments, preview - -If you have @file{dvipng} installed, @LaTeX{} fragments can be processed to -produce preview images of the typeset expressions: - -@table @kbd -@kindex C-c C-x C-l -@item C-c C-x C-l -Produce a preview image of the @LaTeX{} fragment at point and overlay it -over the source code. If there is no fragment at point, process all -fragments in the current entry (between two headlines). When called -with a prefix argument, process the entire subtree. When called with -two prefix arguments, or when the cursor is before the first headline, -process the entire buffer. -@kindex C-c C-c -@item C-c C-c -Remove the overlay preview images. -@end table - -@vindex org-format-latex-options -You can customize the variable @code{org-format-latex-options} to influence -some aspects of the preview. In particular, the @code{:scale} (and for HTML -export, @code{:html-scale}) property can be used to adjust the size of the -preview images. - -@node CDLaTeX mode, , Previewing @LaTeX{} fragments, Embedded @LaTeX{} -@subsection Using CD@LaTeX{} to enter math -@cindex CD@LaTeX{} - -CD@LaTeX{} mode is a minor mode that is normally used in combination with a -major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of -environments and math templates. Inside Org mode, you can make use of -some of the features of CD@LaTeX{} mode. You need to install -@file{cdlatex.el} and @file{texmathp.el} (the latter comes also with -AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. -Don't use CD@LaTeX{} mode itself under Org mode, but use the light -version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it -on for the current buffer with @code{M-x org-cdlatex-mode}, or for all -Org files with - -@lisp -(add-hook 'org-mode-hook 'turn-on-org-cdlatex) -@end lisp - -When this mode is enabled, the following features are present (for more -details see the documentation of CD@LaTeX{} mode): -@itemize @bullet -@kindex C-c @{ -@item -Environment templates can be inserted with @kbd{C-c @{}. -@item -@kindex @key{TAB} -The @key{TAB} key will do template expansion if the cursor is inside a -@LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is -inside such a fragment, see the documentation of the function -@code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will -expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor -correctly inside the first brace. Another @key{TAB} will get you into -the second brace. Even outside fragments, @key{TAB} will expand -environment abbreviations at the beginning of a line. For example, if -you write @samp{equ} at the beginning of a line and press @key{TAB}, -this abbreviation will be expanded to an @code{equation} environment. -To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}. -@item -@kindex _ -@kindex ^ -@vindex cdlatex-simplify-sub-super-scripts -Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} fragment will insert these -characters together with a pair of braces. If you use @key{TAB} to move -out of the braces, and if the braces surround only a single character or -macro, they are removed again (depending on the variable -@code{cdlatex-simplify-sub-super-scripts}). -@item -@kindex ` -Pressing the backquote @kbd{`} followed by a character inserts math -macros, also outside @LaTeX{} fragments. If you wait more than 1.5 seconds -after the backquote, a help window will pop up. -@item -@kindex ' -Pressing the single-quote @kbd{'} followed by another character modifies -the symbol before point with an accent or a font. If you wait more than -1.5 seconds after the single-quote, a help window will pop up. Character -modification will work only inside @LaTeX{} fragments; outside the quote -is normal. -@end itemize - -@node Exporting, Publishing, Markup, Top -@chapter Exporting -@cindex exporting - -Org mode documents can be exported into a variety of other formats. For -printing and sharing of notes, ASCII export produces a readable and simple -version of an Org file. HTML export allows you to publish a notes file on -the web, while the XOXO format provides a solid base for exchange with a -broad range of other applications. @LaTeX{} export lets you use Org mode and -its structured editing functions to easily create @LaTeX{} files. DocBook -export makes it possible to convert Org files to many other formats using -DocBook tools. OpenDocument Text (ODT) export allows seamless -collaboration across organizational boundaries. For project management you -can create gantt and resource charts by using TaskJuggler export. To -incorporate entries with associated times like deadlines or appointments into -a desktop calendar program like iCal, Org mode can also produce extracts in -the iCalendar format. Currently, Org mode only supports export, not import of -these different formats. - -Org supports export of selected regions when @code{transient-mark-mode} is -enabled (default in Emacs 23). - -@menu -* Selective export:: Using tags to select and exclude trees -* Export options:: Per-file export settings -* The export dispatcher:: How to access exporter commands -* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding -* HTML export:: Exporting to HTML -* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF -* DocBook export:: Exporting to DocBook -* OpenDocument Text export:: Exporting to OpenDocument Text -* TaskJuggler export:: Exporting to TaskJuggler -* Freemind export:: Exporting to Freemind mind maps -* XOXO export:: Exporting to XOXO -* iCalendar export:: Exporting in iCalendar format -@end menu - -@node Selective export, Export options, Exporting, Exporting -@section Selective export -@cindex export, selective by tags or TODO keyword - -@vindex org-export-select-tags -@vindex org-export-exclude-tags -@cindex org-export-with-tasks -You may use tags to select the parts of a document that should be exported, -or to exclude parts from export. This behavior is governed by two variables: -@code{org-export-select-tags} and @code{org-export-exclude-tags}, -respectively defaulting to @code{'(:export:)} and @code{'(:noexport:)}. - -@enumerate -@item -Org first checks if any of the @emph{select} tags is present in the -buffer. If yes, all trees that do not carry one of these tags will be -excluded. If a selected tree is a subtree, the heading hierarchy above it -will also be selected for export, but not the text below those headings. - -@item -If none of the select tags is found, the whole buffer will be selected for -export. - -@item -Finally, all subtrees that are marked by any of the @emph{exclude} tags will -be removed from the export buffer. -@end enumerate - -The variable @code{org-export-with-tasks} can be configured to select which -kind of tasks should be included for export. See the docstring of the -variable for more information. - -@node Export options, The export dispatcher, Selective export, Exporting -@section Export options -@cindex options, for export - -@cindex completion, of option keywords -The exporter recognizes special lines in the buffer which provide -additional information. These lines may be put anywhere in the file. -The whole set of lines can be inserted into the buffer with @kbd{C-c -C-e t}. For individual lines, a good way to make sure the keyword is -correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion -(@pxref{Completion}). For a summary of other in-buffer settings not -specifically related to export, see @ref{In-buffer settings}. -In particular, note that you can place commonly-used (export) options in -a separate file which can be included using @code{#+SETUPFILE}. - -@table @kbd -@orgcmd{C-c C-e t,org-insert-export-options-template} -Insert template with export options, see example below. -@end table - -@cindex #+TITLE -@cindex #+AUTHOR -@cindex #+DATE -@cindex #+EMAIL -@cindex #+DESCRIPTION -@cindex #+KEYWORDS -@cindex #+LANGUAGE -@cindex #+TEXT -@cindex #+OPTIONS -@cindex #+BIND -@cindex #+LINK_UP -@cindex #+LINK_HOME -@cindex #+EXPORT_SELECT_TAGS -@cindex #+EXPORT_EXCLUDE_TAGS -@cindex #+XSLT -@cindex #+LATEX_HEADER -@vindex user-full-name -@vindex user-mail-address -@vindex org-export-default-language -@vindex org-export-date-timestamp-format -@example -#+TITLE: the title to be shown (default is the buffer name) -#+AUTHOR: the author (default taken from @code{user-full-name}) -#+DATE: a date, an Org timestamp@footnote{@code{org-export-date-timestamp-format} defines how this timestamp will be exported.}, or a format string for @code{format-time-string} -#+EMAIL: his/her email address (default from @code{user-mail-address}) -#+DESCRIPTION: the page description, e.g.@: for the XHTML meta tag -#+KEYWORDS: the page keywords, e.g.@: for the XHTML meta tag -#+LANGUAGE: language for HTML, e.g.@: @samp{en} (@code{org-export-default-language}) -#+TEXT: Some descriptive text to be inserted at the beginning. -#+TEXT: Several lines may be given. -#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ... -#+BIND: lisp-var lisp-val, e.g.@:: @code{org-export-latex-low-levels itemize} - @r{You need to confirm using these, or configure @code{org-export-allow-BIND}} -#+LINK_UP: the ``up'' link of an exported page -#+LINK_HOME: the ``home'' link of an exported page -#+LATEX_HEADER: extra line(s) for the @LaTeX{} header, like \usepackage@{xyz@} -#+EXPORT_SELECT_TAGS: Tags that select a tree for export -#+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export -#+XSLT: the XSLT stylesheet used by DocBook exporter to generate FO file -@end example - -@noindent -The @code{#+OPTIONS} line is a compact@footnote{If you want to configure many options -this way, you can use several @code{#+OPTIONS} lines.} form to specify export -settings. Here you can: -@cindex headline levels -@cindex section-numbers -@cindex table of contents -@cindex line-break preservation -@cindex quoted HTML tags -@cindex fixed-width sections -@cindex tables -@cindex @TeX{}-like syntax for sub- and superscripts -@cindex footnotes -@cindex special strings -@cindex emphasized text -@cindex @TeX{} macros -@cindex @LaTeX{} fragments -@cindex author info, in export -@cindex time info, in export -@vindex org-export-plist-vars -@vindex org-export-author-info -@vindex org-export-creator-info -@vindex org-export-email-info -@vindex org-export-time-stamp-file -@example -H: @r{set the number of headline levels for export} -num: @r{turn on/off section-numbers} -toc: @r{turn on/off table of contents, or set level limit (integer)} -\n: @r{turn on/off line-break-preservation (DOES NOT WORK)} -@@: @r{turn on/off quoted HTML tags} -:: @r{turn on/off fixed-width sections} -|: @r{turn on/off tables} -^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If} - @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but} - @r{the simple @code{a_b} will be left as it is.} --: @r{turn on/off conversion of special strings.} -f: @r{turn on/off footnotes like this[1].} -todo: @r{turn on/off inclusion of TODO keywords into exported text} -tasks: @r{turn on/off inclusion of tasks (TODO items), can be nil to remove} - @r{all tasks, @code{todo} to remove DONE tasks, or list of kwds to keep} -pri: @r{turn on/off priority cookies} -tags: @r{turn on/off inclusion of tags, may also be @code{not-in-toc}} -<: @r{turn on/off inclusion of any time/date stamps like DEADLINES} -*: @r{turn on/off emphasized text (bold, italic, underlined)} -TeX: @r{turn on/off simple @TeX{} macros in plain text} -LaTeX: @r{configure export of @LaTeX{} fragments. Default @code{auto}} -skip: @r{turn on/off skipping the text before the first heading} -author: @r{turn on/off inclusion of author name/email into exported file} -email: @r{turn on/off inclusion of author email into exported file} -creator: @r{turn on/off inclusion of creator info into exported file} -timestamp: @r{turn on/off inclusion creation time into exported file} -d: @r{turn on/off inclusion of drawers} -@end example -@noindent -These options take effect in both the HTML and @LaTeX{} export, except for -@code{TeX} and @code{LaTeX} options, which are respectively @code{t} and -@code{nil} for the @LaTeX{} export. - -The default values for these and many other options are given by a set of -variables. For a list of such variables, the corresponding OPTIONS keys and -also the publishing keys (@pxref{Project alist}), see the constant -@code{org-export-plist-vars}. - -When exporting only a single subtree by selecting it with @kbd{C-c @@} before -calling an export command, the subtree can overrule some of the file's export -settings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE}, -@code{EXPORT_TEXT}, @code{EXPORT_AUTHOR}, @code{EXPORT_DATE}, and -@code{EXPORT_OPTIONS}. - -@node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting -@section The export dispatcher -@cindex dispatcher, for export commands - -All export commands can be reached using the export dispatcher, which is a -prefix key that prompts for an additional key specifying the command. -Normally the entire file is exported, but if there is an active region that -contains one outline tree, the first heading is used as document title and -the subtrees are exported. - -@table @kbd -@orgcmd{C-c C-e,org-export} -@vindex org-export-run-in-background -Dispatcher for export and publishing commands. Displays a help-window -listing the additional key(s) needed to launch an export or publishing -command. The prefix arg is passed through to the exporter. A double prefix -@kbd{C-u C-u} causes most commands to be executed in the background, in a -separate Emacs process@footnote{To make this behavior the default, customize -the variable @code{org-export-run-in-background}.}. -@orgcmd{C-c C-e v,org-export-visible} -Like @kbd{C-c C-e}, but only export the text that is currently visible -(i.e.@: not hidden by outline visibility). -@orgcmd{C-u C-u C-c C-e,org-export} -@vindex org-export-run-in-background -Call the exporter, but reverse the setting of -@code{org-export-run-in-background}, i.e.@: request background processing if -not set, or force processing in the current Emacs process if set. -@end table - -@node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting -@section ASCII/Latin-1/UTF-8 export -@cindex ASCII export -@cindex Latin-1 export -@cindex UTF-8 export - -ASCII export produces a simple and very readable version of an Org mode -file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file -with special characters and symbols available in these encodings. - -@cindex region, active -@cindex active region -@cindex transient-mark-mode -@table @kbd -@orgcmd{C-c C-e a,org-export-as-ascii} -@cindex property, EXPORT_FILE_NAME -Export as ASCII file. For an Org file, @file{myfile.org}, the ASCII file -will be @file{myfile.txt}. The file will be overwritten without -warning. If there is an active region@footnote{This requires -@code{transient-mark-mode} be turned on.}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will -become the document title. If the tree head entry has or inherits an -@code{EXPORT_FILE_NAME} property, that name will be used for the -export. -@orgcmd{C-c C-e A,org-export-as-ascii-to-buffer} -Export to a temporary buffer. Do not create a file. -@orgcmd{C-c C-e n,org-export-as-latin1} -@xorgcmd{C-c C-e N,org-export-as-latin1-to-buffer} -Like the above commands, but use Latin-1 encoding. -@orgcmd{C-c C-e u,org-export-as-utf8} -@xorgcmd{C-c C-e U,org-export-as-utf8-to-buffer} -Like the above commands, but use UTF-8 encoding. -@item C-c C-e v a/n/u -Export only the visible part of the document. -@end table - -@cindex headline levels, for exporting -In the exported version, the first 3 outline levels will become -headlines, defining a general document structure. Additional levels -will be exported as itemized lists. If you want that transition to occur -at a different level, specify it with a prefix argument. For example, - -@example -@kbd{C-1 C-c C-e a} -@end example - -@noindent -creates only top level headlines and does the rest as items. When -headlines are converted to items, the indentation of the text following -the headline is changed to fit nicely under the item. This is done with -the assumption that the first body line indicates the base indentation of -the body text. Any indentation larger than this is adjusted to preserve -the layout relative to the first line. Should there be lines with less -indentation than the first, these are left alone. - -@vindex org-export-ascii-links-to-notes -Links will be exported in a footnote-like style, with the descriptive part in -the text and the link in a note before the next heading. See the variable -@code{org-export-ascii-links-to-notes} for details and other options. - -@node HTML export, @LaTeX{} and PDF export, ASCII/Latin-1/UTF-8 export, Exporting -@section HTML export -@cindex HTML export - -Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive -HTML formatting, in ways similar to John Gruber's @emph{markdown} -language, but with additional support for tables. - -@menu -* HTML Export commands:: How to invoke HTML export -* HTML preamble and postamble:: How to insert a preamble and a postamble -* Quoting HTML tags:: Using direct HTML in Org mode -* Links in HTML export:: How links will be interpreted and formatted -* Tables in HTML export:: How to modify the formatting of tables -* Images in HTML export:: How to insert figures into HTML output -* Math formatting in HTML export:: Beautiful math also on the web -* Text areas in HTML export:: An alternative way to show an example -* CSS support:: Changing the appearance of the output -* JavaScript support:: Info and Folding in a web browser -@end menu - -@node HTML Export commands, HTML preamble and postamble, HTML export, HTML export -@subsection HTML export commands - -@cindex region, active -@cindex active region -@cindex transient-mark-mode -@table @kbd -@orgcmd{C-c C-e h,org-export-as-html} -@cindex property, EXPORT_FILE_NAME -Export as HTML file. For an Org file @file{myfile.org}, -the HTML file will be @file{myfile.html}. The file will be overwritten -without warning. If there is an active region@footnote{This requires -@code{transient-mark-mode} be turned on.}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will become the document -title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME} -property, that name will be used for the export. -@orgcmd{C-c C-e b,org-export-as-html-and-open} -Export as HTML file and immediately open it with a browser. -@orgcmd{C-c C-e H,org-export-as-html-to-buffer} -Export to a temporary buffer. Do not create a file. -@orgcmd{C-c C-e R,org-export-region-as-html} -Export the active region to a temporary buffer. With a prefix argument, do -not produce the file header and footer, but just the plain HTML section for -the region. This is good for cut-and-paste operations. -@item C-c C-e v h/b/H/R -Export only the visible part of the document. -@item M-x org-export-region-as-html -Convert the region to HTML under the assumption that it was Org mode -syntax before. This is a global command that can be invoked in any -buffer. -@item M-x org-replace-region-by-HTML -Replace the active region (assumed to be in Org mode syntax) by HTML -code. -@end table - -@cindex headline levels, for exporting -In the exported version, the first 3 outline levels will become headlines, -defining a general document structure. Additional levels will be exported as -itemized lists. If you want that transition to occur at a different level, -specify it with a numeric prefix argument. For example, - -@example -@kbd{C-2 C-c C-e b} -@end example - -@noindent -creates two levels of headings and does the rest as items. - - -@node HTML preamble and postamble, Quoting HTML tags, HTML Export commands, HTML export -@subsection HTML preamble and postamble -@vindex org-export-html-preamble -@vindex org-export-html-postamble -@vindex org-export-html-preamble-format -@vindex org-export-html-postamble-format -@vindex org-export-html-validation-link -@vindex org-export-author-info -@vindex org-export-email-info -@vindex org-export-creator-info -@vindex org-export-time-stamp-file - -The HTML exporter lets you define a preamble and a postamble. - -The default value for @code{org-export-html-preamble} is @code{t}, which -means that the preamble is inserted depending on the relevant formatting -string in @code{org-export-html-preamble-format}. - -Setting @code{org-export-html-preamble} to a string will override the default -formatting string. Setting it to a function, will insert the output of the -function, which must be a string; such a function takes no argument but you -can check against the value of @code{opt-plist}, which contains the list of -publishing properties for the current file. Setting to @code{nil} will not -insert any preamble. - -The default value for @code{org-export-html-postamble} is @code{'auto}, which -means that the HTML exporter will look for the value of -@code{org-export-author-info}, @code{org-export-email-info}, -@code{org-export-creator-info} and @code{org-export-time-stamp-file}, -@code{org-export-html-validation-link} and build the postamble from these -values. Setting @code{org-export-html-postamble} to @code{t} will insert the -postamble from the relevant formatting string found in -@code{org-export-html-postamble-format}. Setting it to @code{nil} will not -insert any postamble. - -@node Quoting HTML tags, Links in HTML export, HTML preamble and postamble, HTML export -@subsection Quoting HTML tags - -Plain @samp{<} and @samp{>} are always transformed to @samp{<} and -@samp{>} in HTML export. If you want to include simple HTML tags -which should be interpreted as such, mark them with @samp{@@} as in -@samp{@@bold text@@}. Note that this really works only for -simple tags. For more extensive HTML that should be copied verbatim to -the exported file use either - -@cindex #+HTML -@cindex #+BEGIN_HTML -@example -#+HTML: Literal HTML code for export -@end example - -@noindent or -@cindex #+BEGIN_HTML - -@example -#+BEGIN_HTML -All lines between these markers are exported literally -#+END_HTML -@end example - - -@node Links in HTML export, Tables in HTML export, Quoting HTML tags, HTML export -@subsection Links in HTML export - -@cindex links, in HTML export -@cindex internal links, in HTML export -@cindex external links, in HTML export -Internal links (@pxref{Internal links}) will continue to work in HTML. This -includes automatic links created by radio targets (@pxref{Radio -targets}). Links to external files will still work if the target file is on -the same @i{relative} path as the published Org file. Links to other -@file{.org} files will be translated into HTML links under the assumption -that an HTML version also exists of the linked file, at the same relative -path. @samp{id:} links can then be used to jump to specific entries across -files. For information related to linking files while publishing them to a -publishing directory see @ref{Publishing links}. - -If you want to specify attributes for links, you can do so using a special -@code{#+ATTR_HTML} line to define attributes that will be added to the -@code{} or @code{} tags. Here is an example that sets @code{title} -and @code{style} attributes for a link: - -@cindex #+ATTR_HTML -@example -#+ATTR_HTML: title="The Org mode homepage" style="color:red;" -[[http://orgmode.org]] -@end example - -@node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export -@subsection Tables -@cindex tables, in HTML -@vindex org-export-html-table-tag - -Org mode tables are exported to HTML using the table tag defined in -@code{org-export-html-table-tag}. The default setting makes tables without -cell borders and frame. If you would like to change this for individual -tables, place something like the following before the table: - -@cindex #+CAPTION -@cindex #+ATTR_HTML -@example -#+CAPTION: This is a table with lines around and between cells -#+ATTR_HTML: border="2" rules="all" frame="border" -@end example - -@node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export -@subsection Images in HTML export - -@cindex images, inline in HTML -@cindex inlining images in HTML -@vindex org-export-html-inline-images -HTML export can inline images given as links in the Org file, and -it can make an image the clickable part of a link. By -default@footnote{But see the variable -@code{org-export-html-inline-images}.}, images are inlined if a link does -not have a description. So @samp{[[file:myimg.jpg]]} will be inlined, -while @samp{[[file:myimg.jpg][the image]]} will just produce a link -@samp{the image} that points to the image. If the description part -itself is a @code{file:} link or a @code{http:} URL pointing to an -image, this image will be inlined and activated so that clicking on the -image will activate the link. For example, to include a thumbnail that -will link to a high resolution version of the image, you could use: - -@example -[[file:highres.jpg][file:thumb.jpg]] -@end example - -If you need to add attributes to an inlined image, use a @code{#+ATTR_HTML}. -In the example below we specify the @code{alt} and @code{title} attributes to -support text viewers and accessibility, and align it to the right. - -@cindex #+CAPTION -@cindex #+ATTR_HTML -@example -#+CAPTION: A black cat stalking a spider -#+ATTR_HTML: alt="cat/spider image" title="Action!" align="right" -[[./img/a.jpg]] -@end example - -@noindent -You could use @code{http} addresses just as well. - -@node Math formatting in HTML export, Text areas in HTML export, Images in HTML export, HTML export -@subsection Math formatting in HTML export -@cindex MathJax -@cindex dvipng - -@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be displayed in two -different ways on HTML pages. The default is to use the -@uref{http://www.mathjax.org, MathJax system} which should work out of the -box with Org mode installation because @code{http://orgmode.org} serves -@file{MathJax} for Org mode users for small applications and for testing -purposes. @b{If you plan to use this regularly or on pages with significant -page views, you should install@footnote{Installation instructions can be -found on the MathJax website, see -@uref{http://www.mathjax.org/resources/docs/?installation.html}.} MathJax on -your own server in order to limit the load of our server.} To configure -@file{MathJax}, use the variable @code{org-export-html-mathjax-options} or -insert something like the following into the buffer: - -@example -#+MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js" -@end example - -@noindent See the docstring of the variable -@code{org-export-html-mathjax-options} for the meaning of the parameters in -this line. - -If you prefer, you can also request that @LaTeX{} fragments are processed -into small images that will be inserted into the browser page. Before the -availability of MathJax, this was the default method for Org files. This -method requires that the @file{dvipng} program is available on your system. -You can still get this processing with - -@example -#+OPTIONS: LaTeX:dvipng -@end example - -@node Text areas in HTML export, CSS support, Math formatting in HTML export, HTML export -@subsection Text areas in HTML export - -@cindex text areas, in HTML -An alternative way to publish literal code examples in HTML is to use text -areas, where the example can even be edited before pasting it into an -application. It is triggered by a @code{-t} switch at an @code{example} or -@code{src} block. Using this switch disables any options for syntax and -label highlighting, and line numbering, which may be present. You may also -use @code{-h} and @code{-w} switches to specify the height and width of the -text area, which default to the number of lines in the example, and 80, -respectively. For example - -@example -#+BEGIN_EXAMPLE -t -w 40 - (defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) -#+END_EXAMPLE -@end example - - -@node CSS support, JavaScript support, Text areas in HTML export, HTML export -@subsection CSS support -@cindex CSS, for HTML export -@cindex HTML export, CSS - -@vindex org-export-html-todo-kwd-class-prefix -@vindex org-export-html-tag-class-prefix -You can also give style information for the exported file. The HTML exporter -assigns the following special CSS classes@footnote{If the classes on TODO -keywords and tags lead to conflicts, use the variables -@code{org-export-html-todo-kwd-class-prefix} and -@code{org-export-html-tag-class-prefix} to make them unique.} to appropriate -parts of the document---your style specifications may change these, in -addition to any of the standard classes like for headlines, tables, etc. -@example -p.author @r{author information, including email} -p.date @r{publishing date} -p.creator @r{creator info, about org mode version} -.title @r{document title} -.todo @r{TODO keywords, all not-done states} -.done @r{the DONE keywords, all states that count as done} -.WAITING @r{each TODO keyword also uses a class named after itself} -.timestamp @r{timestamp} -.timestamp-kwd @r{keyword associated with a timestamp, like SCHEDULED} -.timestamp-wrapper @r{span around keyword plus timestamp} -.tag @r{tag in a headline} -._HOME @r{each tag uses itself as a class, "@@" replaced by "_"} -.target @r{target for links} -.linenr @r{the line number in a code example} -.code-highlighted @r{for highlighting referenced code lines} -div.outline-N @r{div for outline level N (headline plus text))} -div.outline-text-N @r{extra div for text at outline level N} -.section-number-N @r{section number in headlines, different for each level} -div.figure @r{how to format an inlined image} -pre.src @r{formatted source code} -pre.example @r{normal example} -p.verse @r{verse paragraph} -div.footnotes @r{footnote section headline} -p.footnote @r{footnote definition paragraph, containing a footnote} -.footref @r{a footnote reference number (always a )} -.footnum @r{footnote number in footnote definition (always )} -@end example - -@vindex org-export-html-style-default -@vindex org-export-html-style-include-default -@vindex org-export-html-style -@vindex org-export-html-extra -@vindex org-export-html-style-default -Each exported file contains a compact default style that defines these -classes in a basic way@footnote{This style is defined in the constant -@code{org-export-html-style-default}, which you should not modify. To turn -inclusion of these defaults off, customize -@code{org-export-html-style-include-default}}. You may overwrite these -settings, or add to them by using the variables @code{org-export-html-style} -(for Org-wide settings) and @code{org-export-html-style-extra} (for more -fine-grained settings, like file-local settings). To set the latter variable -individually for each file, you can use - -@cindex #+STYLE -@example -#+STYLE: -@end example - -@noindent -For longer style definitions, you can use several such lines. You could also -directly write a @code{} section in this way, without -referring to an external file. - -In order to add styles to a subtree, use the @code{:HTML_CONTAINER_CLASS:} -property to assign a class to the tree. In order to specify CSS styles for a -particular headline, you can use the id specified in a @code{:CUSTOM_ID:} -property. - -@c FIXME: More about header and footer styles -@c FIXME: Talk about links and targets. - -@node JavaScript support, , CSS support, HTML export -@subsection JavaScript supported display of web pages - -@cindex Rose, Sebastian -Sebastian Rose has written a JavaScript program especially designed to -enhance the web viewing experience of HTML files created with Org. This -program allows you to view large files in two different ways. The first one -is an @emph{Info}-like mode where each section is displayed separately and -navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys -as well, press @kbd{?} for an overview of the available keys). The second -view type is a @emph{folding} view much like Org provides inside Emacs. The -script is available at @url{http://orgmode.org/org-info.js} and you can find -the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}. -We host the script at our site, but if you use it a lot, you might -not want to be dependent on @url{orgmode.org} and prefer to install a local -copy on your own web server. - -To use the script, you need to make sure that the @file{org-jsinfo.el} module -gets loaded. It should be loaded by default, but you can try @kbd{M-x -customize-variable @key{RET} org-modules @key{RET}} to convince yourself that -this is indeed the case. All it then takes to make use of the program is -adding a single line to the Org file: - -@cindex #+INFOJS_OPT -@example -#+INFOJS_OPT: view:info toc:nil -@end example - -@noindent -If this line is found, the HTML header will automatically contain the code -needed to invoke the script. Using the line above, you can set the following -viewing options: - -@example -path: @r{The path to the script. The default is to grab the script from} - @r{@url{http://orgmode.org/org-info.js}, but you might want to have} - @r{a local copy and use a path like @samp{../scripts/org-info.js}.} -view: @r{Initial view when website is first shown. Possible values are:} - info @r{Info-like interface with one section per page.} - overview @r{Folding interface, initially showing only top-level.} - content @r{Folding interface, starting with all headlines visible.} - showall @r{Folding interface, all headlines and text visible.} -sdepth: @r{Maximum headline level that will still become an independent} - @r{section for info and folding modes. The default is taken from} - @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).} - @r{If this is smaller than in @code{org-export-headline-levels}, each} - @r{info/folding section can still contain child headlines.} -toc: @r{Should the table of contents @emph{initially} be visible?} - @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.} -tdepth: @r{The depth of the table of contents. The defaults are taken from} - @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.} -ftoc: @r{Does the CSS of the page specify a fixed position for the "toc"?} - @r{If yes, the toc will never be displayed as a section.} -ltoc: @r{Should there be short contents (children) in each section?} - @r{Make this @code{above} if the section should be above initial text.} -mouse: @r{Headings are highlighted when the mouse is over them. Should be} - @r{@samp{underline} (default) or a background color like @samp{#cccccc}.} -buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the} - @r{default), only one such button will be present.} -@end example -@noindent -@vindex org-infojs-options -@vindex org-export-html-use-infojs -You can choose default values for these options by customizing the variable -@code{org-infojs-options}. If you always want to apply the script to your -pages, configure the variable @code{org-export-html-use-infojs}. - -@node @LaTeX{} and PDF export, DocBook export, HTML export, Exporting -@section @LaTeX{} and PDF export -@cindex @LaTeX{} export -@cindex PDF export -@cindex Guerry, Bastien - -Org mode contains a @LaTeX{} exporter written by Bastien Guerry. With -further processing@footnote{The default @LaTeX{} output is designed for -processing with @code{pdftex} or @LaTeX{}. It includes packages that are not -compatible with @code{xetex} and possibly @code{luatex}. See the variables -@code{org-export-latex-default-packages-alist} and -@code{org-export-latex-packages-alist}.}, this backend is also used to -produce PDF output. Since the @LaTeX{} output uses @file{hyperref} to -implement links and cross references, the PDF output file will be fully -linked. Beware of the fact that your @code{org} file has to be properly -structured in order to be correctly exported: respect the hierarchy of -sections. - -@menu -* @LaTeX{}/PDF export commands:: -* Header and sectioning:: Setting up the export file structure -* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code -* Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{} -* Images in @LaTeX{} export:: How to insert figures into @LaTeX{} output -* Beamer class export:: Turning the file into a presentation -@end menu - -@node @LaTeX{}/PDF export commands, Header and sectioning, @LaTeX{} and PDF export, @LaTeX{} and PDF export -@subsection @LaTeX{} export commands - -@cindex region, active -@cindex active region -@cindex transient-mark-mode -@table @kbd -@orgcmd{C-c C-e l,org-export-as-latex} -@cindex property EXPORT_FILE_NAME -Export as @LaTeX{} file. For an Org file -@file{myfile.org}, the @LaTeX{} file will be @file{myfile.tex}. The file will -be overwritten without warning. If there is an active region@footnote{This -requires @code{transient-mark-mode} be turned on.}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will become the document -title. If the tree head entry has or inherits an @code{EXPORT_FILE_NAME} -property, that name will be used for the export. -@orgcmd{C-c C-e L,org-export-as-latex-to-buffer} -Export to a temporary buffer. Do not create a file. -@item C-c C-e v l/L -Export only the visible part of the document. -@item M-x org-export-region-as-latex -Convert the region to @LaTeX{} under the assumption that it was Org mode -syntax before. This is a global command that can be invoked in any -buffer. -@item M-x org-replace-region-by-latex -Replace the active region (assumed to be in Org mode syntax) by @LaTeX{} -code. -@orgcmd{C-c C-e p,org-export-as-pdf} -Export as @LaTeX{} and then process to PDF. -@orgcmd{C-c C-e d,org-export-as-pdf-and-open} -Export as @LaTeX{} and then process to PDF, then open the resulting PDF file. -@end table - -@cindex headline levels, for exporting -@vindex org-latex-low-levels -In the exported version, the first 3 outline levels will become -headlines, defining a general document structure. Additional levels -will be exported as description lists. The exporter can ignore them or -convert them to a custom string depending on -@code{org-latex-low-levels}. - -If you want that transition to occur at a different level, specify it -with a numeric prefix argument. For example, - -@example -@kbd{C-2 C-c C-e l} -@end example - -@noindent -creates two levels of headings and does the rest as items. - -@node Header and sectioning, Quoting @LaTeX{} code, @LaTeX{}/PDF export commands, @LaTeX{} and PDF export -@subsection Header and sectioning structure -@cindex @LaTeX{} class -@cindex @LaTeX{} sectioning structure -@cindex @LaTeX{} header -@cindex header, for @LaTeX{} files -@cindex sectioning structure, for @LaTeX{} export - -By default, the @LaTeX{} output uses the class @code{article}. - -@vindex org-export-latex-default-class -@vindex org-export-latex-classes -@vindex org-export-latex-default-packages-alist -@vindex org-export-latex-packages-alist -@cindex #+LATEX_HEADER -@cindex #+LATEX_CLASS -@cindex #+LATEX_CLASS_OPTIONS -@cindex property, LATEX_CLASS -@cindex property, LATEX_CLASS_OPTIONS -You can change this globally by setting a different value for -@code{org-export-latex-default-class} or locally by adding an option like -@code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:} -property that applies when exporting a region containing only this (sub)tree. -The class must be listed in @code{org-export-latex-classes}. This variable -defines a header template for each class@footnote{Into which the values of -@code{org-export-latex-default-packages-alist} and -@code{org-export-latex-packages-alist} are spliced.}, and allows you to -define the sectioning structure for each class. You can also define your own -classes there. @code{#+LaTeX_CLASS_OPTIONS} or a @code{LaTeX_CLASS_OPTIONS} -property can specify the options for the @code{\documentclass} macro. You -can also use @code{#+LATEX_HEADER: \usepackage@{xyz@}} to add lines to the -header. See the docstring of @code{org-export-latex-classes} for more -information. - -@node Quoting @LaTeX{} code, Tables in @LaTeX{} export, Header and sectioning, @LaTeX{} and PDF export -@subsection Quoting @LaTeX{} code - -Embedded @LaTeX{} as described in @ref{Embedded @LaTeX{}}, will be correctly -inserted into the @LaTeX{} file. This includes simple macros like -@samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore, -you can add special code that should only be present in @LaTeX{} export with -the following constructs: - -@cindex #+LaTeX -@cindex #+BEGIN_LaTeX -@example -#+LaTeX: Literal @LaTeX{} code for export -@end example - -@noindent or -@cindex #+BEGIN_LaTeX - -@example -#+BEGIN_LaTeX -All lines between these markers are exported literally -#+END_LaTeX -@end example - - -@node Tables in @LaTeX{} export, Images in @LaTeX{} export, Quoting @LaTeX{} code, @LaTeX{} and PDF export -@subsection Tables in @LaTeX{} export -@cindex tables, in @LaTeX{} export - -For @LaTeX{} export of a table, you can specify a label, a caption and -placement options (@pxref{Images and tables}). You can also use the -@code{ATTR_LaTeX} line to request a @code{longtable} environment for the -table, so that it may span several pages, or to change the default table -environment from @code{table} to @code{table*} or to change the default inner -tabular environment to @code{tabularx} or @code{tabulary}. Finally, you can -set the alignment string, and (with @code{tabularx} or @code{tabulary}) the -width: - -@cindex #+CAPTION -@cindex #+LABEL -@cindex #+ATTR_LaTeX -@example -#+CAPTION: A long table -#+LABEL: tbl:long -#+ATTR_LaTeX: longtable align=l|lp@{3cm@}r|l -| ..... | ..... | -| ..... | ..... | -@end example - -or to specify a multicolumn table with @code{tabulary} - -@cindex #+CAPTION -@cindex #+LABEL -@cindex #+ATTR_LaTeX -@example -#+CAPTION: A wide table with tabulary -#+LABEL: tbl:wide -#+ATTR_LaTeX: table* tabulary width=\textwidth -| ..... | ..... | -| ..... | ..... | -@end example - -@node Images in @LaTeX{} export, Beamer class export, Tables in @LaTeX{} export, @LaTeX{} and PDF export -@subsection Images in @LaTeX{} export -@cindex images, inline in @LaTeX{} -@cindex inlining images in @LaTeX{} - -Images that are linked to without a description part in the link, like -@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF -output file resulting from @LaTeX{} processing. Org will use an -@code{\includegraphics} macro to insert the image. If you have specified a -caption and/or a label as described in @ref{Images and tables}, the figure -will be wrapped into a @code{figure} environment and thus become a floating -element. You can use an @code{#+ATTR_LaTeX:} line to specify various other -options. You can ask org to export an image as a float without specifying -a label or a caption by using the keyword @code{float} in this line. Various -optional arguments to the @code{\includegraphics} macro can also be specified -in this fashion. To modify the placement option of the floating environment, -add something like @samp{placement=[h!]} to the attributes. It is to be noted -this option can be used with tables as well@footnote{One can also take -advantage of this option to pass other, unrelated options into the figure or -table environment. For an example see the section ``Exporting org files'' in -@url{http://orgmode.org/worg/org-hacks.html}}. For example the -@code{#+ATTR_LaTeX:} line below is exported as the @code{figure} environment -below it. - -If you would like to let text flow around the image, add the word @samp{wrap} -to the @code{#+ATTR_LaTeX:} line, which will make the figure occupy the left -half of the page. To fine-tune, the @code{placement} field will be the set -of additional arguments needed by the @code{wrapfigure} environment. Note -that if you change the size of the image, you need to use compatible settings -for @code{\includegraphics} and @code{wrapfigure}. - -@cindex #+CAPTION -@cindex #+LABEL -@cindex #+ATTR_LaTeX -@example -#+CAPTION: The black-body emission of the disk around HR 4049 -#+LABEL: fig:SED-HR4049 -#+ATTR_LaTeX: width=5cm,angle=90 -[[./img/sed-hr4049.pdf]] - -#+ATTR_LaTeX: width=0.38\textwidth wrap placement=@{r@}@{0.4\textwidth@} -[[./img/hst.png]] -@end example - -If you wish to include an image which spans multiple columns in a page, you -can use the keyword @code{multicolumn} in the @code{#+ATTR_LaTeX} line. This -will export the image wrapped in a @code{figure*} environment. - -If you need references to a label created in this way, write -@samp{\ref@{fig:SED-HR4049@}} just like in @LaTeX{}. - -@node Beamer class export, , Images in @LaTeX{} export, @LaTeX{} and PDF export -@subsection Beamer class export - -The @LaTeX{} class @file{beamer} allows production of high quality presentations -using @LaTeX{} and pdf processing. Org mode has special support for turning an -Org mode file or tree into a @file{beamer} presentation. - -When the @LaTeX{} class for the current buffer (as set with @code{#+LaTeX_CLASS: -beamer}) or subtree (set with a @code{LaTeX_CLASS} property) is -@code{beamer}, a special export mode will turn the file or tree into a beamer -presentation. Any tree with not-too-deep level nesting should in principle be -exportable as a beamer presentation. By default, the top-level entries (or -the first level below the selected subtree heading) will be turned into -frames, and the outline structure below this level will become itemize lists. -You can also configure the variable @code{org-beamer-frame-level} to a -different level---then the hierarchy above frames will produce the sectioning -structure of the presentation. - -A template for useful in-buffer settings or properties can be inserted into -the buffer with @kbd{M-x org-insert-beamer-options-template}. Among other -things, this will install a column view format which is very handy for -editing special properties used by beamer. - -You can influence the structure of the presentation using the following -properties: - -@table @code -@item BEAMER_env -The environment that should be used to format this entry. Valid environments -are defined in the constant @code{org-beamer-environments-default}, and you -can define more in @code{org-beamer-environments-extra}. If this property is -set, the entry will also get a @code{:B_environment:} tag to make this -visible. This tag has no semantic meaning, it is only a visual aid. -@item BEAMER_envargs -The beamer-special arguments that should be used for the environment, like -@code{[t]} or @code{[<+->]} of @code{<2-3>}. If the @code{BEAMER_col} -property is also set, something like @code{C[t]} can be added here as well to -set an options argument for the implied @code{columns} environment. -@code{c[t]} or @code{c<2->} will set an options for the implied @code{column} -environment. -@item BEAMER_col -The width of a column that should start with this entry. If this property is -set, the entry will also get a @code{:BMCOL:} property to make this visible. -Also this tag is only a visual aid. When this is a plain number, it will be -interpreted as a fraction of @code{\textwidth}. Otherwise it will be assumed -that you have specified the units, like @samp{3cm}. The first such property -in a frame will start a @code{columns} environment to surround the columns. -This environment is closed when an entry has a @code{BEAMER_col} property -with value 0 or 1, or automatically at the end of the frame. -@item BEAMER_extra -Additional commands that should be inserted after the environment has been -opened. For example, when creating a frame, this can be used to specify -transitions. -@end table - -Frames will automatically receive a @code{fragile} option if they contain -source code that uses the verbatim environment. Special @file{beamer} -specific code can be inserted using @code{#+BEAMER:} and -@code{#+BEGIN_beamer...#+end_beamer} constructs, similar to other export -backends, but with the difference that @code{#+LaTeX:} stuff will be included -in the presentation as well. - -Outline nodes with @code{BEAMER_env} property value @samp{note} or -@samp{noteNH} will be formatted as beamer notes, i,e, they will be wrapped -into @code{\note@{...@}}. The former will include the heading as part of the -note text, the latter will ignore the heading of that node. To simplify note -generation, it is actually enough to mark the note with a @emph{tag} (either -@code{:B_note:} or @code{:B_noteNH:}) instead of creating the -@code{BEAMER_env} property. - -You can turn on a special minor mode @code{org-beamer-mode} for editing -support with - -@example -#+STARTUP: beamer -@end example - -@table @kbd -@orgcmd{C-c C-b,org-beamer-select-environment} -In @code{org-beamer-mode}, this key offers fast selection of a beamer -environment or the @code{BEAMER_col} property. -@end table - -Column view provides a great way to set the environment of a node and other -important parameters. Make sure you are using a COLUMN format that is geared -toward this special purpose. The command @kbd{M-x -org-insert-beamer-options-template} defines such a format. - -Here is a simple example Org document that is intended for beamer export. - -@smallexample -#+LaTeX_CLASS: beamer -#+TITLE: Example Presentation -#+AUTHOR: Carsten Dominik -#+LaTeX_CLASS_OPTIONS: [presentation] -#+BEAMER_FRAME_LEVEL: 2 -#+BEAMER_HEADER_EXTRA: \usetheme@{Madrid@}\usecolortheme@{default@} -#+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex) - -* This is the first structural section - -** Frame 1 \\ with a subtitle -*** Thanks to Eric Fraga :BMCOL:B_block: - :PROPERTIES: - :BEAMER_env: block - :BEAMER_envargs: C[t] - :BEAMER_col: 0.5 - :END: - for the first viable beamer setup in Org -*** Thanks to everyone else :BMCOL:B_block: - :PROPERTIES: - :BEAMER_col: 0.5 - :BEAMER_env: block - :BEAMER_envargs: <2-> - :END: - for contributing to the discussion -**** This will be formatted as a beamer note :B_note: -** Frame 2 \\ where we will not use columns -*** Request :B_block: - Please test this stuff! - :PROPERTIES: - :BEAMER_env: block - :END: -@end smallexample - -For more information, see the documentation on Worg. - -@node DocBook export, OpenDocument Text export, @LaTeX{} and PDF export, Exporting -@section DocBook export -@cindex DocBook export -@cindex PDF export -@cindex Cui, Baoqiu - -Org contains a DocBook exporter written by Baoqiu Cui. Once an Org file is -exported to DocBook format, it can be further processed to produce other -formats, including PDF, HTML, man pages, etc., using many available DocBook -tools and stylesheets. - -Currently DocBook exporter only supports DocBook V5.0. - -@menu -* DocBook export commands:: How to invoke DocBook export -* Quoting DocBook code:: Incorporating DocBook code in Org files -* Recursive sections:: Recursive sections in DocBook -* Tables in DocBook export:: Tables are exported as HTML tables -* Images in DocBook export:: How to insert figures into DocBook output -* Special characters:: How to handle special characters -@end menu - -@node DocBook export commands, Quoting DocBook code, DocBook export, DocBook export -@subsection DocBook export commands - -@cindex region, active -@cindex active region -@cindex transient-mark-mode -@table @kbd -@orgcmd{C-c C-e D,org-export-as-docbook} -@cindex property EXPORT_FILE_NAME -Export as DocBook file. For an Org file, @file{myfile.org}, the DocBook XML -file will be @file{myfile.xml}. The file will be overwritten without -warning. If there is an active region@footnote{This requires -@code{transient-mark-mode} to be turned on}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will become the document -title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME} -property, that name will be used for the export. -@orgcmd{C-c C-e V,org-export-as-docbook-pdf-and-open} -Export as DocBook file, process to PDF, then open the resulting PDF file. - -@vindex org-export-docbook-xslt-proc-command -@vindex org-export-docbook-xsl-fo-proc-command -Note that, in order to produce PDF output based on exported DocBook file, you -need to have XSLT processor and XSL-FO processor software installed on your -system. Check variables @code{org-export-docbook-xslt-proc-command} and -@code{org-export-docbook-xsl-fo-proc-command}. - -@vindex org-export-docbook-xslt-stylesheet -The stylesheet argument @code{%s} in variable -@code{org-export-docbook-xslt-proc-command} is replaced by the value of -variable @code{org-export-docbook-xslt-stylesheet}, which needs to be set by -the user. You can also overrule this global setting on a per-file basis by -adding an in-buffer setting @code{#+XSLT:} to the Org file. - -@orgkey{C-c C-e v D} -Export only the visible part of the document. -@end table - -@node Quoting DocBook code, Recursive sections, DocBook export commands, DocBook export -@subsection Quoting DocBook code - -You can quote DocBook code in Org files and copy it verbatim into exported -DocBook file with the following constructs: - -@cindex #+DOCBOOK -@cindex #+BEGIN_DOCBOOK -@example -#+DOCBOOK: Literal DocBook code for export -@end example - -@noindent or -@cindex #+BEGIN_DOCBOOK - -@example -#+BEGIN_DOCBOOK -All lines between these markers are exported by DocBook exporter -literally. -#+END_DOCBOOK -@end example - -For example, you can use the following lines to include a DocBook warning -admonition. As to what this warning says, you should pay attention to the -document context when quoting DocBook code in Org files. You may make -exported DocBook XML files invalid by not quoting DocBook code correctly. - -@example -#+BEGIN_DOCBOOK - - You should know what you are doing when quoting DocBook XML code - in your Org file. Invalid DocBook XML may be generated by - DocBook exporter if you are not careful! - -#+END_DOCBOOK -@end example - -@node Recursive sections, Tables in DocBook export, Quoting DocBook code, DocBook export -@subsection Recursive sections -@cindex DocBook recursive sections - -DocBook exporter exports Org files as articles using the @code{article} -element in DocBook. Recursive sections, i.e.@: @code{section} elements, are -used in exported articles. Top level headlines in Org files are exported as -top level sections, and lower level headlines are exported as nested -sections. The entire structure of Org files will be exported completely, no -matter how many nested levels of headlines there are. - -Using recursive sections makes it easy to port and reuse exported DocBook -code in other DocBook document types like @code{book} or @code{set}. - -@node Tables in DocBook export, Images in DocBook export, Recursive sections, DocBook export -@subsection Tables in DocBook export -@cindex tables, in DocBook export - -Tables in Org files are exported as HTML tables, which have been supported since -DocBook V4.3. - -If a table does not have a caption, an informal table is generated using the -@code{informaltable} element; otherwise, a formal table will be generated -using the @code{table} element. - -@node Images in DocBook export, Special characters, Tables in DocBook export, DocBook export -@subsection Images in DocBook export -@cindex images, inline in DocBook -@cindex inlining images in DocBook - -Images that are linked to without a description part in the link, like -@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]}, will be exported to DocBook -using @code{mediaobject} elements. Each @code{mediaobject} element contains -an @code{imageobject} that wraps an @code{imagedata} element. If you have -specified a caption for an image as described in @ref{Images and tables}, a -@code{caption} element will be added in @code{mediaobject}. If a label is -also specified, it will be exported as an @code{xml:id} attribute of the -@code{mediaobject} element. - -@vindex org-export-docbook-default-image-attributes -Image attributes supported by the @code{imagedata} element, like @code{align} -or @code{width}, can be specified in two ways: you can either customize -variable @code{org-export-docbook-default-image-attributes} or use the -@code{#+ATTR_DOCBOOK:} line. Attributes specified in variable -@code{org-export-docbook-default-image-attributes} are applied to all inline -images in the Org file to be exported (unless they are overridden by image -attributes specified in @code{#+ATTR_DOCBOOK:} lines). - -The @code{#+ATTR_DOCBOOK:} line can be used to specify additional image -attributes or override default image attributes for individual images. If -the same attribute appears in both the @code{#+ATTR_DOCBOOK:} line and -variable @code{org-export-docbook-default-image-attributes}, the former -takes precedence. Here is an example about how image attributes can be -set: - -@cindex #+CAPTION -@cindex #+LABEL -@cindex #+ATTR_DOCBOOK -@example -#+CAPTION: The logo of Org mode -#+LABEL: unicorn-svg -#+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%" -[[./img/org-mode-unicorn.svg]] -@end example - -@vindex org-export-docbook-inline-image-extensions -By default, DocBook exporter recognizes the following image file types: -@file{jpeg}, @file{jpg}, @file{png}, @file{gif}, and @file{svg}. You can -customize variable @code{org-export-docbook-inline-image-extensions} to add -more types to this list as long as DocBook supports them. - -@node Special characters, , Images in DocBook export, DocBook export -@subsection Special characters in DocBook export -@cindex Special characters in DocBook export - -@vindex org-export-docbook-doctype -@vindex org-entities -Special characters that are written in @TeX{}-like syntax, such as @code{\alpha}, -@code{\Gamma}, and @code{\Zeta}, are supported by DocBook exporter. These -characters are rewritten to XML entities, like @code{α}, -@code{Γ}, and @code{Ζ}, based on the list saved in variable -@code{org-entities}. As long as the generated DocBook file includes the -corresponding entities, these special characters are recognized. - -You can customize variable @code{org-export-docbook-doctype} to include the -entities you need. For example, you can set variable -@code{org-export-docbook-doctype} to the following value to recognize all -special characters included in XHTML entities: - -@example -" -%xhtml1-symbol; -]> -" -@end example - -@c begin opendocument - -@node OpenDocument Text export, TaskJuggler export, DocBook export, Exporting -@section OpenDocument Text export -@cindex K, Jambunathan -@cindex ODT -@cindex OpenDocument -@cindex export, OpenDocument -@cindex LibreOffice -@cindex org-odt.el -@cindex org-modules - -Orgmode@footnote{Versions 7.8 or later} supports export to OpenDocument Text -(ODT) format using the @file{org-odt.el} module. Documents created -by this exporter use the @cite{OpenDocument-v1.2 -specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, -Open Document Format for Office Applications (OpenDocument) Version 1.2}} and -are compatible with LibreOffice 3.4. - -@menu -* Pre-requisites for ODT export:: What packages ODT exporter relies on -* ODT export commands:: How to invoke ODT export -* Extending ODT export:: How to produce @samp{doc}, @samp{pdf} files -* Applying custom styles:: How to apply custom styles to the output -* Links in ODT export:: How links will be interpreted and formatted -* Tables in ODT export:: How Tables are exported -* Images in ODT export:: How to insert images -* Math formatting in ODT export:: How @LaTeX{} fragments are formatted -* Labels and captions in ODT export:: How captions are rendered -* Literal examples in ODT export:: How source and example blocks are formatted -* Advanced topics in ODT export:: Read this if you are a power user -@end menu - -@node Pre-requisites for ODT export, ODT export commands, OpenDocument Text export, OpenDocument Text export -@subsection Pre-requisites for ODT export -@cindex zip -The ODT exporter relies on the @file{zip} program to create the final -output. Check the availability of this program before proceeding further. - -@node ODT export commands, Extending ODT export, Pre-requisites for ODT export, OpenDocument Text export -@subsection ODT export commands - -@subsubheading Exporting to ODT -@anchor{x-export-to-odt} - -@cindex region, active -@cindex active region -@cindex transient-mark-mode -@table @kbd -@orgcmd{C-c C-e o,org-export-as-odt} -@cindex property EXPORT_FILE_NAME - -Export as OpenDocument Text file. - -@vindex org-export-odt-preferred-output-format -If @code{org-export-odt-preferred-output-format} is specified, automatically -convert the exported file to that format. @xref{x-export-to-other-formats, , -Automatically exporting to other formats}. - -For an Org file @file{myfile.org}, the ODT file will be -@file{myfile.odt}. The file will be overwritten without warning. If there -is an active region,@footnote{This requires @code{transient-mark-mode} to be -turned on} only the region will be exported. If the selected region is a -single tree,@footnote{To select the current subtree, use @kbd{C-c @@}} the -tree head will become the document title. If the tree head entry has, or -inherits, an @code{EXPORT_FILE_NAME} property, that name will be used for the -export. - -@orgcmd{C-c C-e O,org-export-as-odt-and-open} -Export as OpenDocument Text file and open the resulting file. - -@vindex org-export-odt-preferred-output-format -If @code{org-export-odt-preferred-output-format} is specified, open the -converted file instead. @xref{x-export-to-other-formats, , Automatically -exporting to other formats}. -@end table - -@node Extending ODT export, Applying custom styles, ODT export commands, OpenDocument Text export -@subsection Extending ODT export - -The ODT exporter can interface with a variety of document -converters and supports popular converters out of the box. As a result, you -can use it to export to formats like @samp{doc} or convert a document from -one format (say @samp{csv}) to another format (say @samp{ods} or @samp{xls}). - -@cindex @file{unoconv} -@cindex LibreOffice -If you have a working installation of LibreOffice, a document converter is -pre-configured for you and you can use it right away. If you would like to -use @file{unoconv} as your preferred converter, customize the variable -@code{org-export-odt-convert-process} to point to @code{unoconv}. You can -also use your own favorite converter or tweak the default settings of the -@file{LibreOffice} and @samp{unoconv} converters. @xref{Configuring a -document converter}. - -@subsubsection Automatically exporting to other formats -@anchor{x-export-to-other-formats} - -@vindex org-export-odt-preferred-output-format -Very often, you will find yourself exporting to ODT format, only to -immediately save the exported document to other formats like @samp{doc}, -@samp{docx}, @samp{rtf}, @samp{pdf} etc. In such cases, you can specify your -preferred output format by customizing the variable -@code{org-export-odt-preferred-output-format}. This way, the export commands -(@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to export to a -format that is of immediate interest to you. - -@subsubsection Converting between document formats -@anchor{x-convert-to-other-formats} - -There are many document converters in the wild which support conversion to -and from various file formats, including, but not limited to the -ODT format. LibreOffice converter, mentioned above, is one such -converter. Once a converter is configured, you can interact with it using -the following command. - -@vindex org-export-odt-convert -@table @kbd - -@item M-x org-export-odt-convert -Convert an existing document from one format to another. With a prefix -argument, also open the newly produced file. -@end table - -@node Applying custom styles, Links in ODT export, Extending ODT export, OpenDocument Text export -@subsection Applying custom styles -@cindex styles, custom -@cindex template, custom - -The ODT exporter ships with a set of OpenDocument styles -(@pxref{Working with OpenDocument style files}) that ensure a well-formatted -output. These factory styles, however, may not cater to your specific -tastes. To customize the output, you can either modify the above styles -files directly, or generate the required styles using an application like -LibreOffice. The latter method is suitable for expert and non-expert -users alike, and is described here. - -@subsubsection Applying custom styles - the easy way - -@enumerate -@item -Create a sample @file{example.org} file with the below settings and export it -to ODT format. - -@example -#+OPTIONS: H:10 num:t -@end example - -@item -Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist} -to locate the target styles - these typically have the @samp{Org} prefix - -and modify those to your taste. Save the modified file either as an -OpenDocument Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file. - -@item -@cindex #+ODT_STYLES_FILE -@vindex org-export-odt-styles-file -Customize the variable @code{org-export-odt-styles-file} and point it to the -newly created file. For additional configuration options -@pxref{x-overriding-factory-styles,,Overriding factory styles}. - -If you would like to choose a style on a per-file basis, you can use the -@code{#+ODT_STYLES_FILE} option. A typical setting will look like - -@example -#+ODT_STYLES_FILE: "/path/to/example.ott" -@end example - -or - -@example -#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png")) -@end example - -@end enumerate - -@subsubsection Using third-party styles and templates - -You can use third-party styles and templates for customizing your output. -This will produce the desired output only if the template provides all -style names that the @samp{ODT} exporter relies on. Unless this condition is -met, the output is going to be less than satisfactory. So it is highly -recommended that you only work with templates that are directly derived from -the factory settings. - -@node Links in ODT export, Tables in ODT export, Applying custom styles, OpenDocument Text export -@subsection Links in ODT export -@cindex tables, in DocBook export - -ODT exporter creates native cross-references for internal links. It creates -Internet-style links for all other links. - -A link with no description and destined to a regular (un-itemized) outline -heading is replaced with a cross-reference and section number of the heading. - -A @samp{\ref@{label@}}-style reference to an image, table etc. is replaced -with a cross-reference and sequence number of the labeled entity. -@xref{Labels and captions in ODT export}. - -@node Tables in ODT export, Images in ODT export, Links in ODT export, OpenDocument Text export -@subsection Tables in ODT export -@cindex tables, in DocBook export - -Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el} -tables is supported. However, export of complex @file{table.el} tables - -tables that have column or row spans - is not supported. Such tables are -stripped from the exported document. - -By default, a table is exported with top and bottom frames and with rules -separating row and column groups (@pxref{Column groups}). Furthermore, all -tables are typeset to occupy the same width. If the table specifies -alignment and relative width for its columns (@pxref{Column width and -alignment}) then these are honored on export.@footnote{The column widths are -interpreted as weighted ratios with the default weight being 1} - -@cindex #+ATTR_ODT -You can control the width of the table by specifying @code{:rel-width} -property using an @code{#+ATTR_ODT} line. - -For example, consider the following table which makes use of all the rules -mentioned above. - -@example -#+ATTR_ODT: :rel-width 50 -| Area/Month | Jan | Feb | Mar | Sum | -|---------------+-------+-------+-------+-------| -| / | < | | | < | -| | | | | | -| North America | 1 | 21 | 926 | 948 | -| Middle East | 6 | 75 | 844 | 925 | -| Asia Pacific | 9 | 27 | 790 | 826 | -|---------------+-------+-------+-------+-------| -| Sum | 16 | 123 | 2560 | 2699 | -@end example - -On export, the table will occupy 50% of text area. The columns will be sized -(roughly) in the ratio of 13:5:5:5:6. The first column will be left-aligned -and rest of the columns will be right-aligned. There will be vertical rules -after separating the header and last columns from other columns. There will -be horizontal rules separating the header and last rows from other rows. - -If you are not satisfied with the above formatting options, you can create -custom table styles and associate them with a table using the -@code{#+ATTR_ODT} line. @xref{Customizing tables in ODT export}. - -@node Images in ODT export, Math formatting in ODT export, Tables in ODT export, OpenDocument Text export -@subsection Images in ODT export -@cindex images, embedding in ODT -@cindex embedding images in ODT - -@subsubheading Embedding images -You can embed images within the exported document by providing a link to the -desired image file with no link description. For example, to embed -@samp{img.png} do either of the following: - -@example -[[file:img.png]] -@end example - -@example -[[./img.png]] -@end example - -@subsubheading Embedding clickable images -You can create clickable images by providing a link whose description is a -link to an image file. For example, to embed a image -@file{org-mode-unicorn.png} which when clicked jumps to -@uref{http://Orgmode.org} website, do the following - -@example -[[http://orgmode.org][./org-mode-unicorn.png]] -@end example - -@subsubheading Sizing and scaling of embedded images - -@cindex #+ATTR_ODT -You can control the size and scale of the embedded images using the -@code{#+ATTR_ODT} attribute. - -@cindex identify, ImageMagick -@vindex org-export-odt-pixels-per-inch -The exporter specifies the desired size of the image in the final document in -units of centimeters. In order to scale the embedded images, the exporter -queries for pixel dimensions of the images using one of a) ImageMagick's -@file{identify} program or b) Emacs `create-image' and `image-size' -APIs.@footnote{Use of @file{ImageMagick} is only desirable. However, if you -routinely produce documents that have large images or you export your Org -files that has images using a Emacs batch script, then the use of -@file{ImageMagick} is mandatory.} The pixel dimensions are subsequently -converted in to units of centimeters using -@code{org-export-odt-pixels-per-inch}. The default value of this variable is -set to @code{display-pixels-per-inch}. You can tweak this variable to -achieve the best results. - -The examples below illustrate the various possibilities. - -@table @asis -@item Explicitly size the image -To embed @file{img.png} as a 10 cm x 10 cm image, do the following: - -@example -#+ATTR_ODT: :width 10 :height 10 -[[./img.png]] -@end example - -@item Scale the image -To embed @file{img.png} at half its size, do the following: - -@example -#+ATTR_ODT: :scale 0.5 -[[./img.png]] -@end example - -@item Scale the image to a specific width -To embed @file{img.png} with a width of 10 cm while retaining the original -height:width ratio, do the following: - -@example -#+ATTR_ODT: :width 10 -[[./img.png]] -@end example - -@item Scale the image to a specific height -To embed @file{img.png} with a height of 10 cm while retaining the original -height:width ratio, do the following - -@example -#+ATTR_ODT: :height 10 -[[./img.png]] -@end example -@end table - -@subsubheading Anchoring of images - -@cindex #+ATTR_ODT -You can control the manner in which an image is anchored by setting the -@code{:anchor} property of it's @code{#+ATTR_ODT} line. You can specify one -of the the following three values for the @code{:anchor} property - -@samp{"as-char"}, @samp{"paragraph"} and @samp{"page"}. - -To create an image that is anchored to a page, do the following: -@example -#+ATTR_ODT: :anchor "page" -[[./img.png]] -@end example - -@node Math formatting in ODT export, Labels and captions in ODT export, Images in ODT export, OpenDocument Text export -@subsection Math formatting in ODT export - -The ODT exporter has special support for handling math. - -@menu -* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments -* Working with MathML or OpenDocument formula files:: How to embed equations in native format -@end menu - -@node Working with @LaTeX{} math snippets, Working with MathML or OpenDocument formula files, Math formatting in ODT export, Math formatting in ODT export -@subsubsection Working with @LaTeX{} math snippets - -@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in the ODT -document in one of the following ways: - -@cindex MathML -@enumerate -@item MathML - -This option is activated on a per-file basis with - -@example -#+OPTIONS: LaTeX:t -@end example - -With this option, @LaTeX{} fragments are first converted into MathML -fragments using an external @LaTeX{}-to-MathML converter program. The -resulting MathML fragments are then embedded as an OpenDocument Formula in -the exported document. - -@vindex org-latex-to-mathml-convert-command -@vindex org-latex-to-mathml-jar-file - -You can specify the @LaTeX{}-to-MathML converter by customizing the variables -@code{org-latex-to-mathml-convert-command} and -@code{org-latex-to-mathml-jar-file}. - -If you prefer to use @file{MathToWeb}@footnote{See -@uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}} as your -converter, you can configure the above variables as shown below. - -@lisp -(setq org-latex-to-mathml-convert-command - "java -jar %j -unicode -force -df %o %I" - org-latex-to-mathml-jar-file - "/path/to/mathtoweb.jar") -@end lisp - -You can use the following commands to quickly verify the reliability of -the @LaTeX{}-to-MathML converter. - -@table @kbd - -@item M-x org-export-as-odf -Convert a @LaTeX{} math snippet to OpenDocument formula (@file{.odf}) file. - -@item M-x org-export-as-odf-and-open -Convert a @LaTeX{} math snippet to OpenDocument formula (@file{.odf}) file and -open the formula file with the system-registered application. -@end table - -@cindex dvipng -@item PNG images - -This option is activated on a per-file basis with - -@example -#+OPTIONS: LaTeX:dvipng -@end example - -With this option, @LaTeX{} fragments are processed into PNG images and the -resulting images are embedded in the exported document. This method requires -that the @file{dvipng} program be available on your system. -@end enumerate - -@node Working with MathML or OpenDocument formula files, , Working with @LaTeX{} math snippets, Math formatting in ODT export -@subsubsection Working with MathML or OpenDocument formula files - -For various reasons, you may find embedding @LaTeX{} math snippets in an -ODT document less than reliable. In that case, you can embed a -math equation by linking to its MathML (@file{.mml}) source or its -OpenDocument formula (@file{.odf}) file as shown below: - -@example -[[./equation.mml]] -@end example - -or - -@example -[[./equation.odf]] -@end example - -@node Labels and captions in ODT export, Literal examples in ODT export, Math formatting in ODT export, OpenDocument Text export -@subsection Labels and captions in ODT export - -You can label and caption various category of objects - an inline image, a -table, a @LaTeX{} fragment or a Math formula - using @code{#+LABEL} and -@code{#+CAPTION} lines. @xref{Images and tables}. ODT exporter enumerates -each labeled or captioned object of a given category separately. As a -result, each such object is assigned a sequence number based on order of it's -appearance in the Org file. - -In the exported document, a user-provided caption is augmented with the -category and sequence number. Consider the following inline image in an Org -file. - -@example -#+CAPTION: Bell curve -#+LABEL: fig:SED-HR4049 -[[./img/a.png]] -@end example - -It could be rendered as shown below in the exported document. - -@example -Figure 2: Bell curve -@end example - -@vindex org-export-odt-category-strings -You can modify the category component of the caption by customizing the -variable @code{org-export-odt-category-strings}. For example, to tag all -embedded images with the string @samp{Illustration} (instead of the default -@samp{Figure}) use the following setting. - -@lisp -(setq org-export-odt-category-strings - '(("en" "Table" "Illustration" "Equation" "Equation"))) -@end lisp - -With this, previous image will be captioned as below in the exported -document. - -@example -Illustration 2: Bell curve -@end example - -@node Literal examples in ODT export, Advanced topics in ODT export, Labels and captions in ODT export, OpenDocument Text export -@subsection Literal examples in ODT export - -Export of literal examples (@pxref{Literal examples}) with full fontification -is supported. Internally, the exporter relies on @file{htmlfontify.el} to -generate all style definitions needed for a fancy listing.@footnote{Your -@file{htmlfontify.el} library must at least be at Emacs 24.1 levels for -fontification to be turned on.} The auto-generated styles have @samp{OrgSrc} -as prefix and inherit their color from the faces used by Emacs -@code{font-lock} library for the source language. - -@vindex org-export-odt-fontify-srcblocks -If you prefer to use your own custom styles for fontification, you can do so -by customizing the variable -@code{org-export-odt-create-custom-styles-for-srcblocks}. - -@vindex org-export-odt-create-custom-styles-for-srcblocks -You can turn off fontification of literal examples by customizing the -variable @code{org-export-odt-fontify-srcblocks}. - -@node Advanced topics in ODT export, , Literal examples in ODT export, OpenDocument Text export -@subsection Advanced topics in ODT export - -If you rely heavily on ODT export, you may want to exploit the full -set of features that the exporter offers. This section describes features -that would be of interest to power users. - -@menu -* Configuring a document converter:: How to register a document converter -* Working with OpenDocument style files:: Explore the internals -* Creating one-off styles:: How to produce custom highlighting etc -* Customizing tables in ODT export:: How to define and use Table templates -* Validating OpenDocument XML:: How to debug corrupt OpenDocument files -@end menu - -@node Configuring a document converter, Working with OpenDocument style files, Advanced topics in ODT export, Advanced topics in ODT export -@subsubsection Configuring a document converter -@cindex convert -@cindex doc, docx, rtf -@cindex converter - -The ODT exporter can work with popular converters with little or no -extra configuration from your side. @xref{Extending ODT export}. -If you are using a converter that is not supported by default or if you would -like to tweak the default converter settings, proceed as below. - -@enumerate -@item Register the converter - -@vindex org-export-odt-convert-processes -Name your converter and add it to the list of known converters by customizing -the variable @code{org-export-odt-convert-processes}. Also specify how the -converter can be invoked via command-line to effect the conversion. - -@item Configure its capabilities - -@vindex org-export-odt-convert-capabilities -@anchor{x-odt-converter-capabilities} -Specify the set of formats the converter can handle by customizing the -variable @code{org-export-odt-convert-capabilities}. Use the default value -for this variable as a guide for configuring your converter. As suggested by -the default setting, you can specify the full set of formats supported by the -converter and not limit yourself to specifying formats that are related to -just the OpenDocument Text format. - -@item Choose the converter - -@vindex org-export-odt-convert-process -Select the newly added converter as the preferred one by customizing the -variable @code{org-export-odt-convert-process}. -@end enumerate - -@node Working with OpenDocument style files, Creating one-off styles, Configuring a document converter, Advanced topics in ODT export -@subsubsection Working with OpenDocument style files -@cindex styles, custom -@cindex template, custom - -This section explores the internals of the ODT exporter and the -means by which it produces styled documents. Read this section if you are -interested in exploring the automatic and custom OpenDocument styles used by -the exporter. - -@anchor{x-factory-styles} -@subsubheading Factory styles - -The ODT exporter relies on two files for generating its output. -These files are bundled with the distribution under the directory pointed to -by the variable @code{org-odt-styles-dir}. The two files are: - -@itemize -@anchor{x-orgodtstyles-xml} -@item -@file{OrgOdtStyles.xml} - -This file contributes to the @file{styles.xml} file of the final @samp{ODT} -document. This file gets modified for the following purposes: -@enumerate - -@item -To control outline numbering based on user settings. - -@item -To add styles generated by @file{htmlfontify.el} for fontification of code -blocks. -@end enumerate - -@anchor{x-orgodtcontenttemplate-xml} -@item -@file{OrgOdtContentTemplate.xml} - -This file contributes to the @file{content.xml} file of the final @samp{ODT} -document. The contents of the Org outline are inserted between the -@samp{}@dots{}@samp{} elements of this file. - -Apart from serving as a template file for the final @file{content.xml}, the -file serves the following purposes: -@enumerate - -@item -It contains automatic styles for formatting of tables which are referenced by -the exporter. - -@item -It contains @samp{}@dots{}@samp{} -elements that control how various entities - tables, images, equations etc - -are numbered. -@end enumerate -@end itemize - -@anchor{x-overriding-factory-styles} -@subsubheading Overriding factory styles -The following two variables control the location from which the ODT -exporter picks up the custom styles and content template files. You can -customize these variables to override the factory styles used by the -exporter. - -@itemize -@anchor{x-org-export-odt-styles-file} -@item -@code{org-export-odt-styles-file} - -Use this variable to specify the @file{styles.xml} that will be used in the -final output. You can specify one of the following values: - -@enumerate -@item A @file{styles.xml} file - -Use this file instead of the default @file{styles.xml} - -@item A @file{.odt} or @file{.ott} file - -Use the @file{styles.xml} contained in the specified OpenDocument Text or -Template file - -@item A @file{.odt} or @file{.ott} file and a subset of files contained within them - -Use the @file{styles.xml} contained in the specified OpenDocument Text or -Template file. Additionally extract the specified member files and embed -those within the final @samp{ODT} document. - -Use this option if the @file{styles.xml} file references additional files -like header and footer images. - -@item @code{nil} - -Use the default @file{styles.xml} -@end enumerate - -@anchor{x-org-export-odt-content-template-file} -@item -@code{org-export-odt-content-template-file} - -Use this variable to specify the blank @file{content.xml} that will be used -in the final output. -@end itemize - -@node Creating one-off styles, Customizing tables in ODT export, Working with OpenDocument style files, Advanced topics in ODT export -@subsubsection Creating one-off styles - -There are times when you would want one-off formatting in the exported -document. You can achieve this by embedding raw OpenDocument XML in the Org -file. The use of this feature is better illustrated with couple of examples. - -@enumerate -@item Embedding ODT tags as part of regular text - -You can include simple OpenDocument tags by prefixing them with -@samp{@@}. For example, to highlight a region of text do the following: - -@example -@@This is a -highlighted text@@. But this is a -regular text. -@end example - -@strong{Hint:} To see the above example in action, edit your -@file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a -custom @samp{Highlight} style as shown below. - -@example - - - -@end example - -@item Embedding a one-line OpenDocument XML - -You can add a simple OpenDocument one-liner using the @code{#+ODT:} -directive. For example, to force a page break do the following: - -@example -#+ODT: -@end example - -@strong{Hint:} To see the above example in action, edit your -@file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a -custom @samp{PageBreak} style as shown below. - -@example - - - -@end example - -@item Embedding a block of OpenDocument XML - -You can add a large block of OpenDocument XML using the -@code{#+BEGIN_ODT}@dots{}@code{#+END_ODT} construct. - -For example, to create a one-off paragraph that uses bold text, do the -following: - -@example -#+BEGIN_ODT - -This paragraph is specially formatted and uses bold text. - -#+END_ODT -@end example - -@end enumerate - -@node Customizing tables in ODT export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in ODT export -@subsubsection Customizing tables in ODT export -@cindex tables, in ODT export - -@cindex #+ATTR_ODT -You can override the default formatting of the table by specifying a custom -table style with the @code{#+ATTR_ODT} line. For a discussion on default -formatting of tables @pxref{Tables in ODT export}. - -This feature closely mimics the way table templates are defined in the -OpenDocument-v1.2 -specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, -OpenDocument-v1.2 Specification}} - - - -@subsubheading Custom table styles - an illustration - -To have a quick preview of this feature, install the below setting and export -the table that follows. - -@lisp -(setq org-export-odt-table-styles - (append org-export-odt-table-styles - '(("TableWithHeaderRowAndColumn" "Custom" - ((use-first-row-styles . t) - (use-first-column-styles . t))) - ("TableWithFirstRowandLastRow" "Custom" - ((use-first-row-styles . t) - (use-last-row-styles . t)))))) -@end lisp - -@example -#+ATTR_ODT: :style "TableWithHeaderRowAndColumn" -| Name | Phone | Age | -| Peter | 1234 | 17 | -| Anna | 4321 | 25 | -@end example - -In the above example, you used a template named @samp{Custom} and installed -two table styles with the names @samp{TableWithHeaderRowAndColumn} and -@samp{TableWithFirstRowandLastRow}. (@strong{Important:} The OpenDocument -styles needed for producing the above template have been pre-defined for you. -These styles are available under the section marked @samp{Custom Table -Template} in @file{OrgOdtContentTemplate.xml} -(@pxref{x-orgodtcontenttemplate-xml,,Factory styles}). If you need -additional templates you have to define these styles yourselves. - -@subsubheading Custom table styles - the nitty-gritty -To use this feature proceed as follows: - -@enumerate -@item -Create a table template@footnote{See the @code{} -element of the OpenDocument-v1.2 specification} - -A table template is nothing but a set of @samp{table-cell} and -@samp{paragraph} styles for each of the following table cell categories: - -@itemize @minus -@item Body -@item First column -@item Last column -@item First row -@item Last row -@item Even row -@item Odd row -@item Even column -@item Odd Column -@end itemize - -The names for the above styles must be chosen based on the name of the table -template using a well-defined convention. - -The naming convention is better illustrated with an example. For a table -template with the name @samp{Custom}, the needed style names are listed in -the following table. - -@multitable {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph} -@headitem Table cell type -@tab @code{table-cell} style -@tab @code{paragraph} style -@item -@tab -@tab -@item Body -@tab @samp{CustomTableCell} -@tab @samp{CustomTableParagraph} -@item First column -@tab @samp{CustomFirstColumnTableCell} -@tab @samp{CustomFirstColumnTableParagraph} -@item Last column -@tab @samp{CustomLastColumnTableCell} -@tab @samp{CustomLastColumnTableParagraph} -@item First row -@tab @samp{CustomFirstRowTableCell} -@tab @samp{CustomFirstRowTableParagraph} -@item Last row -@tab @samp{CustomLastRowTableCell} -@tab @samp{CustomLastRowTableParagraph} -@item Even row -@tab @samp{CustomEvenRowTableCell} -@tab @samp{CustomEvenRowTableParagraph} -@item Odd row -@tab @samp{CustomOddRowTableCell} -@tab @samp{CustomOddRowTableParagraph} -@item Even column -@tab @samp{CustomEvenColumnTableCell} -@tab @samp{CustomEvenColumnTableParagraph} -@item Odd column -@tab @samp{CustomOddColumnTableCell} -@tab @samp{CustomOddColumnTableParagraph} -@end multitable - -To create a table template with the name @samp{Custom}, define the above -styles in the -@code{}...@code{} element -of the content template file (@pxref{x-orgodtcontenttemplate-xml,,Factory -styles}). - -@item -Define a table style@footnote{See the attributes @code{table:template-name}, -@code{table:use-first-row-styles}, @code{table:use-last-row-styles}, -@code{table:use-first-column-styles}, @code{table:use-last-column-styles}, -@code{table:use-banding-rows-styles}, and -@code{table:use-banding-column-styles} of the @code{} element in -the OpenDocument-v1.2 specification} - -@vindex org-export-odt-table-styles -To define a table style, create an entry for the style in the variable -@code{org-export-odt-table-styles} and specify the following: - -@itemize @minus -@item the name of the table template created in step (1) -@item the set of cell styles in that template that are to be activated -@end itemize - -For example, the entry below defines two different table styles -@samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow} -based on the same template @samp{Custom}. The styles achieve their intended -effect by selectively activating the individual cell styles in that template. - -@lisp -(setq org-export-odt-table-styles - (append org-export-odt-table-styles - '(("TableWithHeaderRowAndColumn" "Custom" - ((use-first-row-styles . t) - (use-first-column-styles . t))) - ("TableWithFirstRowandLastRow" "Custom" - ((use-first-row-styles . t) - (use-last-row-styles . t)))))) -@end lisp - -@item -Associate a table with the table style - -To do this, specify the table style created in step (2) as part of -the @code{ATTR_ODT} line as shown below. - -@example -#+ATTR_ODT: :style "TableWithHeaderRowAndColumn" -| Name | Phone | Age | -| Peter | 1234 | 17 | -| Anna | 4321 | 25 | -@end example -@end enumerate - -@node Validating OpenDocument XML, , Customizing tables in ODT export, Advanced topics in ODT export -@subsubsection Validating OpenDocument XML - -Occasionally, you will discover that the document created by the -ODT exporter cannot be opened by your favorite application. One of -the common reasons for this is that the @file{.odt} file is corrupt. In such -cases, you may want to validate the document against the OpenDocument RELAX -NG Compact Syntax (RNC) schema. - -For de-compressing the @file{.odt} file@footnote{@file{.odt} files are -nothing but @samp{zip} archives}: @inforef{File Archives,,emacs}. For -general help with validation (and schema-sensitive editing) of XML files: -@inforef{Introduction,,nxml-mode}. - -@vindex org-export-odt-schema-dir -If you have ready access to OpenDocument @file{.rnc} files and the needed -schema-locating rules in a single folder, you can customize the variable -@code{org-export-odt-schema-dir} to point to that directory. The -ODT exporter will take care of updating the -@code{rng-schema-locating-files} for you. - -@c end opendocument - -@node TaskJuggler export, Freemind export, OpenDocument Text export, Exporting -@section TaskJuggler export -@cindex TaskJuggler export -@cindex Project management - -@uref{http://www.taskjuggler.org/, TaskJuggler} is a project management tool. -It provides an optimizing scheduler that computes your project time lines and -resource assignments based on the project outline and the constraints that -you have provided. - -The TaskJuggler exporter is a bit different from other exporters, such as the -@code{HTML} and @LaTeX{} exporters for example, in that it does not export all the -nodes of a document or strictly follow the order of the nodes in the -document. - -Instead the TaskJuggler exporter looks for a tree that defines the tasks and -a optionally tree that defines the resources for this project. It then -creates a TaskJuggler file based on these trees and the attributes defined in -all the nodes. - -@subsection TaskJuggler export commands - -@table @kbd -@orgcmd{C-c C-e j,org-export-as-taskjuggler} -Export as TaskJuggler file. - -@orgcmd{C-c C-e J,org-export-as-taskjuggler-and-open} -Export as TaskJuggler file and then open the file with TaskJugglerUI. -@end table - -@subsection Tasks - -@vindex org-export-taskjuggler-project-tag -Create your tasks as you usually do with Org mode. Assign efforts to each -task using properties (it is easiest to do this in the column view). You -should end up with something similar to the example by Peter Jones in -@url{http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org}. -Now mark the top node of your tasks with a tag named -@code{:taskjuggler_project:} (or whatever you customized -@code{org-export-taskjuggler-project-tag} to). You are now ready to export -the project plan with @kbd{C-c C-e J} which will export the project plan and -open a gantt chart in TaskJugglerUI. - -@subsection Resources - -@vindex org-export-taskjuggler-resource-tag -Next you can define resources and assign those to work on specific tasks. You -can group your resources hierarchically. Tag the top node of the resources -with @code{:taskjuggler_resource:} (or whatever you customized -@code{org-export-taskjuggler-resource-tag} to). You can optionally assign an -identifier (named @samp{resource_id}) to the resources (using the standard -Org properties commands, @pxref{Property syntax}) or you can let the exporter -generate identifiers automatically (the exporter picks the first word of the -headline as the identifier as long as it is unique---see the documentation of -@code{org-taskjuggler-get-unique-id}). Using that identifier you can then -allocate resources to tasks. This is again done with the @samp{allocate} -property on the tasks. Do this in column view or when on the task type -@kbd{C-c C-x p allocate @key{RET} @key{RET}}. - -Once the allocations are done you can again export to TaskJuggler and check -in the Resource Allocation Graph which person is working on what task at what -time. - -@subsection Export of properties - -The exporter also takes TODO state information into consideration, i.e.@: if a -task is marked as done it will have the corresponding attribute in -TaskJuggler (@samp{complete 100}). Also it will export any property on a task -resource or resource node which is known to TaskJuggler, such as -@samp{limits}, @samp{vacation}, @samp{shift}, @samp{booking}, -@samp{efficiency}, @samp{journalentry}, @samp{rate} for resources or -@samp{account}, @samp{start}, @samp{note}, @samp{duration}, @samp{end}, -@samp{journalentry}, @samp{milestone}, @samp{reference}, @samp{responsible}, -@samp{scheduling}, etc for tasks. - -@subsection Dependencies - -The exporter will handle dependencies that are defined in the tasks either -with the @samp{ORDERED} attribute (@pxref{TODO dependencies}), with the -@samp{BLOCKER} attribute (see @file{org-depend.el}) or alternatively with a -@samp{depends} attribute. Both the @samp{BLOCKER} and the @samp{depends} -attribute can be either @samp{previous-sibling} or a reference to an -identifier (named @samp{task_id}) which is defined for another task in the -project. @samp{BLOCKER} and the @samp{depends} attribute can define multiple -dependencies separated by either space or comma. You can also specify -optional attributes on the dependency by simply appending it. The following -examples should illustrate this: - -@example -* Preparation - :PROPERTIES: - :task_id: preparation - :ORDERED: t - :END: -* Training material - :PROPERTIES: - :task_id: training_material - :ORDERED: t - :END: -** Markup Guidelines - :PROPERTIES: - :Effort: 2d - :END: -** Workflow Guidelines - :PROPERTIES: - :Effort: 2d - :END: -* Presentation - :PROPERTIES: - :Effort: 2d - :BLOCKER: training_material @{ gapduration 1d @} preparation - :END: -@end example - -@subsection Reports - -@vindex org-export-taskjuggler-default-reports -TaskJuggler can produce many kinds of reports (e.g.@: gantt chart, resource -allocation, etc). The user defines what kind of reports should be generated -for a project in the TaskJuggler file. The exporter will automatically insert -some default reports in the file. These defaults are defined in -@code{org-export-taskjuggler-default-reports}. They can be modified using -customize along with a number of other options. For a more complete list, see -@kbd{M-x customize-group @key{RET} org-export-taskjuggler @key{RET}}. - -For more information and examples see the Org-taskjuggler tutorial at -@uref{http://orgmode.org/worg/org-tutorials/org-taskjuggler.html}. - -@node Freemind export, XOXO export, TaskJuggler export, Exporting -@section Freemind export -@cindex Freemind export -@cindex mind map - -The Freemind exporter was written by Lennart Borgman. - -@table @kbd -@orgcmd{C-c C-e m,org-export-as-freemind} -Export as Freemind mind map. For an Org file @file{myfile.org}, the Freemind -file will be @file{myfile.mm}. -@end table - -@node XOXO export, iCalendar export, Freemind export, Exporting -@section XOXO export -@cindex XOXO export - -Org mode contains an exporter that produces XOXO-style output. -Currently, this exporter only handles the general outline structure and -does not interpret any additional Org mode features. - -@table @kbd -@orgcmd{C-c C-e x,org-export-as-xoxo} -Export as XOXO file. For an Org file @file{myfile.org}, the XOXO file will be -@file{myfile.html}. -@orgkey{C-c C-e v x} -Export only the visible part of the document. -@end table - -@node iCalendar export, , XOXO export, Exporting -@section iCalendar export -@cindex iCalendar export - -@vindex org-icalendar-include-todo -@vindex org-icalendar-use-deadline -@vindex org-icalendar-use-scheduled -@vindex org-icalendar-categories -@vindex org-icalendar-alarm-time -Some people use Org mode for keeping track of projects, but still prefer a -standard calendar application for anniversaries and appointments. In this -case it can be useful to show deadlines and other time-stamped items in Org -files in the calendar application. Org mode can export calendar information -in the standard iCalendar format. If you also want to have TODO entries -included in the export, configure the variable -@code{org-icalendar-include-todo}. Plain timestamps are exported as VEVENT, -and TODO items as VTODO. It will also create events from deadlines that are -in non-TODO items. Deadlines and scheduling dates in TODO items will be used -to set the start and due dates for the TODO entry@footnote{See the variables -@code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}.}. -As categories, it will use the tags locally defined in the heading, and the -file/tree category@footnote{To add inherited tags or the TODO state, -configure the variable @code{org-icalendar-categories}.}. See the variable -@code{org-icalendar-alarm-time} for a way to assign alarms to entries with a -time. - -@vindex org-icalendar-store-UID -@cindex property, ID -The iCalendar standard requires each entry to have a globally unique -identifier (UID). Org creates these identifiers during export. If you set -the variable @code{org-icalendar-store-UID}, the UID will be stored in the -@code{:ID:} property of the entry and re-used next time you report this -entry. Since a single entry can give rise to multiple iCalendar entries (as -a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds -prefixes to the UID, depending on what triggered the inclusion of the entry. -In this way the UID remains unique, but a synchronization program can still -figure out from which entry all the different instances originate. - -@table @kbd -@orgcmd{C-c C-e i,org-export-icalendar-this-file} -Create iCalendar entries for the current file and store them in the same -directory, using a file extension @file{.ics}. -@orgcmd{C-c C-e I, org-export-icalendar-all-agenda-files} -@vindex org-agenda-files -Like @kbd{C-c C-e i}, but do this for all files in -@code{org-agenda-files}. For each of these files, a separate iCalendar -file will be written. -@orgcmd{C-c C-e c,org-export-icalendar-combine-agenda-files} -@vindex org-combined-agenda-icalendar-file -Create a single large iCalendar file from all files in -@code{org-agenda-files} and write it to the file given by -@code{org-combined-agenda-icalendar-file}. -@end table - -@vindex org-use-property-inheritance -@vindex org-icalendar-include-body -@cindex property, SUMMARY -@cindex property, DESCRIPTION -@cindex property, LOCATION -The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION -property can be inherited from higher in the hierarchy if you configure -@code{org-use-property-inheritance} accordingly.} properties if the selected -entries have them. If not, the summary will be derived from the headline, -and the description from the body (limited to -@code{org-icalendar-include-body} characters). - -How this calendar is best read and updated, depends on the application -you are using. The FAQ covers this issue. - -@node Publishing, Working With Source Code, Exporting, Top -@chapter Publishing -@cindex publishing - -Org includes a publishing management system that allows you to configure -automatic HTML conversion of @emph{projects} composed of interlinked org -files. You can also configure Org to automatically upload your exported HTML -pages and related attachments, such as images and source code files, to a web -server. - -You can also use Org to convert files into PDF, or even combine HTML and PDF -conversion so that files are available in both formats on the server. - -Publishing has been contributed to Org by David O'Toole. - -@menu -* Configuration:: Defining projects -* Uploading files:: How to get files up on the server -* Sample configuration:: Example projects -* Triggering publication:: Publication commands -@end menu - -@node Configuration, Uploading files, Publishing, Publishing -@section Configuration - -Publishing needs significant configuration to specify files, destination -and many other properties of a project. - -@menu -* Project alist:: The central configuration variable -* Sources and destinations:: From here to there -* Selecting files:: What files are part of the project? -* Publishing action:: Setting the function doing the publishing -* Publishing options:: Tweaking HTML/@LaTeX{} export -* Publishing links:: Which links keep working after publishing? -* Sitemap:: Generating a list of all pages -* Generating an index:: An index that reaches across pages -@end menu - -@node Project alist, Sources and destinations, Configuration, Configuration -@subsection The variable @code{org-publish-project-alist} -@cindex org-publish-project-alist -@cindex projects, for publishing - -@vindex org-publish-project-alist -Publishing is configured almost entirely through setting the value of one -variable, called @code{org-publish-project-alist}. Each element of the list -configures one project, and may be in one of the two following forms: - -@lisp - ("project-name" :property value :property value ...) - @r{i.e.@: a well-formed property list with alternating keys and values} -@r{or} - ("project-name" :components ("project-name" "project-name" ...)) - -@end lisp - -In both cases, projects are configured by specifying property values. A -project defines the set of files that will be published, as well as the -publishing configuration to use when publishing those files. When a project -takes the second form listed above, the individual members of the -@code{:components} property are taken to be sub-projects, which group -together files requiring different publishing options. When you publish such -a ``meta-project'', all the components will also be published, in the -sequence given. - -@node Sources and destinations, Selecting files, Project alist, Configuration -@subsection Sources and destinations for files -@cindex directories, for publishing - -Most properties are optional, but some should always be set. In -particular, Org needs to know where to look for source files, -and where to put published files. - -@multitable @columnfractions 0.3 0.7 -@item @code{:base-directory} -@tab Directory containing publishing source files -@item @code{:publishing-directory} -@tab Directory where output files will be published. You can directly -publish to a webserver using a file name syntax appropriate for -the Emacs @file{tramp} package. Or you can publish to a local directory and -use external tools to upload your website (@pxref{Uploading files}). -@item @code{:preparation-function} -@tab Function or list of functions to be called before starting the -publishing process, for example, to run @code{make} for updating files to be -published. The project property list is scoped into this call as the -variable @code{project-plist}. -@item @code{:completion-function} -@tab Function or list of functions called after finishing the publishing -process, for example, to change permissions of the resulting files. The -project property list is scoped into this call as the variable -@code{project-plist}. -@end multitable -@noindent - -@node Selecting files, Publishing action, Sources and destinations, Configuration -@subsection Selecting files -@cindex files, selecting for publishing - -By default, all files with extension @file{.org} in the base directory -are considered part of the project. This can be modified by setting the -properties -@multitable @columnfractions 0.25 0.75 -@item @code{:base-extension} -@tab Extension (without the dot!) of source files. This actually is a -regular expression. Set this to the symbol @code{any} if you want to get all -files in @code{:base-directory}, even without extension. - -@item @code{:exclude} -@tab Regular expression to match file names that should not be -published, even though they have been selected on the basis of their -extension. - -@item @code{:include} -@tab List of files to be included regardless of @code{:base-extension} -and @code{:exclude}. - -@item @code{:recursive} -@tab Non-nil means, check base-directory recursively for files to publish. -@end multitable - -@node Publishing action, Publishing options, Selecting files, Configuration -@subsection Publishing action -@cindex action, for publishing - -Publishing means that a file is copied to the destination directory and -possibly transformed in the process. The default transformation is to export -Org files as HTML files, and this is done by the function -@code{org-publish-org-to-html} which calls the HTML exporter (@pxref{HTML -export}). But you also can publish your content as PDF files using -@code{org-publish-org-to-pdf}, or as @code{ascii}, @code{latin1} or -@code{utf8} encoded files using the corresponding functions. If you want to -publish the Org file itself, but with @i{archived}, @i{commented}, and -@i{tag-excluded} trees removed, use @code{org-publish-org-to-org} and set the -parameters @code{:plain-source} and/or @code{:htmlized-source}. This will -produce @file{file.org} and @file{file.org.html} in the publishing -directory@footnote{@file{file-source.org} and @file{file-source.org.html} if -source and publishing directories are equal. Note that with this kind of -setup, you need to add @code{:exclude "-source\\.org"} to the project -definition in @code{org-publish-project-alist} to prevent the published -source files from being considered as new org files the next time the project -is published.}. Other files like images only need to be copied to the -publishing destination; for this you may use @code{org-publish-attachment}. -For non-Org files, you always need to specify the publishing function: - -@multitable @columnfractions 0.3 0.7 -@item @code{:publishing-function} -@tab Function executing the publication of a file. This may also be a -list of functions, which will all be called in turn. -@item @code{:plain-source} -@tab Non-nil means, publish plain source. -@item @code{:htmlized-source} -@tab Non-nil means, publish htmlized source. -@end multitable - -The function must accept three arguments: a property list containing at least -a @code{:publishing-directory} property, the name of the file to be -published, and the path to the publishing directory of the output file. It -should take the specified file, make the necessary transformation (if any) -and place the result into the destination folder. - -@node Publishing options, Publishing links, Publishing action, Configuration -@subsection Options for the HTML/@LaTeX{} exporters -@cindex options, for publishing - -The property list can be used to set many export options for the HTML -and @LaTeX{} exporters. In most cases, these properties correspond to user -variables in Org. The table below lists these properties along -with the variable they belong to. See the documentation string for the -respective variable for details. - -@vindex org-export-html-link-up -@vindex org-export-html-link-home -@vindex org-export-default-language -@vindex org-display-custom-times -@vindex org-export-headline-levels -@vindex org-export-with-section-numbers -@vindex org-export-section-number-format -@vindex org-export-with-toc -@vindex org-export-preserve-breaks -@vindex org-export-with-archived-trees -@vindex org-export-with-emphasize -@vindex org-export-with-sub-superscripts -@vindex org-export-with-special-strings -@vindex org-export-with-footnotes -@vindex org-export-with-drawers -@vindex org-export-with-tags -@vindex org-export-with-todo-keywords -@vindex org-export-with-tasks -@vindex org-export-with-done-tasks -@vindex org-export-with-priority -@vindex org-export-with-TeX-macros -@vindex org-export-with-LaTeX-fragments -@vindex org-export-skip-text-before-1st-heading -@vindex org-export-with-fixed-width -@vindex org-export-with-timestamps -@vindex org-export-author-info -@vindex org-export-email-info -@vindex org-export-creator-info -@vindex org-export-time-stamp-file -@vindex org-export-with-tables -@vindex org-export-highlight-first-table-line -@vindex org-export-html-style-include-default -@vindex org-export-html-style-include-scripts -@vindex org-export-html-style -@vindex org-export-html-style-extra -@vindex org-export-html-link-org-files-as-html -@vindex org-export-html-inline-images -@vindex org-export-html-extension -@vindex org-export-html-table-tag -@vindex org-export-html-expand -@vindex org-export-html-with-timestamp -@vindex org-export-publishing-directory -@vindex org-export-html-preamble -@vindex org-export-html-postamble -@vindex user-full-name -@vindex user-mail-address -@vindex org-export-select-tags -@vindex org-export-exclude-tags - -@multitable @columnfractions 0.32 0.68 -@item @code{:link-up} @tab @code{org-export-html-link-up} -@item @code{:link-home} @tab @code{org-export-html-link-home} -@item @code{:language} @tab @code{org-export-default-language} -@item @code{:customtime} @tab @code{org-display-custom-times} -@item @code{:headline-levels} @tab @code{org-export-headline-levels} -@item @code{:section-numbers} @tab @code{org-export-with-section-numbers} -@item @code{:section-number-format} @tab @code{org-export-section-number-format} -@item @code{:table-of-contents} @tab @code{org-export-with-toc} -@item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks} -@item @code{:archived-trees} @tab @code{org-export-with-archived-trees} -@item @code{:emphasize} @tab @code{org-export-with-emphasize} -@item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts} -@item @code{:special-strings} @tab @code{org-export-with-special-strings} -@item @code{:footnotes} @tab @code{org-export-with-footnotes} -@item @code{:drawers} @tab @code{org-export-with-drawers} -@item @code{:tags} @tab @code{org-export-with-tags} -@item @code{:todo-keywords} @tab @code{org-export-with-todo-keywords} -@item @code{:tasks} @tab @code{org-export-with-tasks} -@item @code{:priority} @tab @code{org-export-with-priority} -@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros} -@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments} -@item @code{:latex-listings} @tab @code{org-export-latex-listings} -@item @code{:skip-before-1st-heading} @tab @code{org-export-skip-text-before-1st-heading} -@item @code{:fixed-width} @tab @code{org-export-with-fixed-width} -@item @code{:timestamps} @tab @code{org-export-with-timestamps} -@item @code{:author} @tab @code{user-full-name} -@item @code{:email} @tab @code{user-mail-address} : @code{addr;addr;..} -@item @code{:author-info} @tab @code{org-export-author-info} -@item @code{:email-info} @tab @code{org-export-email-info} -@item @code{:creator-info} @tab @code{org-export-creator-info} -@item @code{:tables} @tab @code{org-export-with-tables} -@item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line} -@item @code{:style-include-default} @tab @code{org-export-html-style-include-default} -@item @code{:style-include-scripts} @tab @code{org-export-html-style-include-scripts} -@item @code{:style} @tab @code{org-export-html-style} -@item @code{:style-extra} @tab @code{org-export-html-style-extra} -@item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html} -@item @code{:inline-images} @tab @code{org-export-html-inline-images} -@item @code{:html-extension} @tab @code{org-export-html-extension} -@item @code{:html-preamble} @tab @code{org-export-html-preamble} -@item @code{:html-postamble} @tab @code{org-export-html-postamble} -@item @code{:xml-declaration} @tab @code{org-export-html-xml-declaration} -@item @code{:html-table-tag} @tab @code{org-export-html-table-tag} -@item @code{:expand-quoted-html} @tab @code{org-export-html-expand} -@item @code{:timestamp} @tab @code{org-export-html-with-timestamp} -@item @code{:publishing-directory} @tab @code{org-export-publishing-directory} -@item @code{:select-tags} @tab @code{org-export-select-tags} -@item @code{:exclude-tags} @tab @code{org-export-exclude-tags} -@item @code{:latex-image-options} @tab @code{org-export-latex-image-default-option} -@end multitable - -Most of the @code{org-export-with-*} variables have the same effect in -both HTML and @LaTeX{} exporters, except for @code{:TeX-macros} and -@code{:LaTeX-fragments} options, respectively @code{nil} and @code{t} in the -@LaTeX{} export. See @code{org-export-plist-vars} to check this list of -options. - - - -@vindex org-publish-project-alist -When a property is given a value in @code{org-publish-project-alist}, -its setting overrides the value of the corresponding user variable (if -any) during publishing. Options set within a file (@pxref{Export -options}), however, override everything. - -@node Publishing links, Sitemap, Publishing options, Configuration -@subsection Links between published files -@cindex links, publishing - -To create a link from one Org file to another, you would use -something like @samp{[[file:foo.org][The foo]]} or simply -@samp{file:foo.org.} (@pxref{Hyperlinks}). When published, this link -becomes a link to @file{foo.html}. In this way, you can interlink the -pages of your "org web" project and the links will work as expected when -you publish them to HTML. If you also publish the Org source file and want -to link to that, use an @code{http:} link instead of a @code{file:} link, -because @code{file:} links are converted to link to the corresponding -@file{html} file. - -You may also link to related files, such as images. Provided you are careful -with relative file names, and provided you have also configured Org to upload -the related files, these links will work too. See @ref{Complex example}, for -an example of this usage. - -Sometimes an Org file to be published may contain links that are -only valid in your production environment, but not in the publishing -location. In this case, use the property - -@multitable @columnfractions 0.4 0.6 -@item @code{:link-validation-function} -@tab Function to validate links -@end multitable - -@noindent -to define a function for checking link validity. This function must -accept two arguments, the file name and a directory relative to which -the file name is interpreted in the production environment. If this -function returns @code{nil}, then the HTML generator will only insert a -description into the HTML file, but no link. One option for this -function is @code{org-publish-validate-link} which checks if the given -file is part of any project in @code{org-publish-project-alist}. - -@node Sitemap, Generating an index, Publishing links, Configuration -@subsection Generating a sitemap -@cindex sitemap, of published pages - -The following properties may be used to control publishing of -a map of files for a given project. - -@multitable @columnfractions 0.35 0.65 -@item @code{:auto-sitemap} -@tab When non-nil, publish a sitemap during @code{org-publish-current-project} -or @code{org-publish-all}. - -@item @code{:sitemap-filename} -@tab Filename for output of sitemap. Defaults to @file{sitemap.org} (which -becomes @file{sitemap.html}). - -@item @code{:sitemap-title} -@tab Title of sitemap page. Defaults to name of file. - -@item @code{:sitemap-function} -@tab Plug-in function to use for generation of the sitemap. -Defaults to @code{org-publish-org-sitemap}, which generates a plain list -of links to all files in the project. - -@item @code{:sitemap-sort-folders} -@tab Where folders should appear in the sitemap. Set this to @code{first} -(default) or @code{last} to display folders first or last, -respectively. Any other value will mix files and folders. - -@item @code{:sitemap-sort-files} -@tab How the files are sorted in the site map. Set this to -@code{alphabetically} (default), @code{chronologically} or -@code{anti-chronologically}. @code{chronologically} sorts the files with -older date first while @code{anti-chronologically} sorts the files with newer -date first. @code{alphabetically} sorts the files alphabetically. The date of -a file is retrieved with @code{org-publish-find-date}. - -@item @code{:sitemap-ignore-case} -@tab Should sorting be case-sensitive? Default @code{nil}. - -@item @code{:sitemap-file-entry-format} -@tab With this option one can tell how a sitemap's entry is formatted in the -sitemap. This is a format string with some escape sequences: @code{%t} stands -for the title of the file, @code{%a} stands for the author of the file and -@code{%d} stands for the date of the file. The date is retrieved with the -@code{org-publish-find-date} function and formatted with -@code{org-publish-sitemap-date-format}. Default @code{%t}. - -@item @code{:sitemap-date-format} -@tab Format string for the @code{format-time-string} function that tells how -a sitemap entry's date is to be formatted. This property bypasses -@code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}. - -@item @code{:sitemap-sans-extension} -@tab When non-nil, remove filenames' extensions from the generated sitemap. -Useful to have cool URIs (see @uref{http://www.w3.org/Provider/Style/URI}). -Defaults to @code{nil}. - -@end multitable - -@node Generating an index, , Sitemap, Configuration -@subsection Generating an index -@cindex index, in a publishing project - -Org mode can generate an index across the files of a publishing project. - -@multitable @columnfractions 0.25 0.75 -@item @code{:makeindex} -@tab When non-nil, generate in index in the file @file{theindex.org} and -publish it as @file{theindex.html}. -@end multitable - -The file will be created when first publishing a project with the -@code{:makeindex} set. The file only contains a statement @code{#+include: -"theindex.inc"}. You can then build around this include statement by adding -a title, style information, etc. - -@node Uploading files, Sample configuration, Configuration, Publishing -@section Uploading files -@cindex rsync -@cindex unison - -For those people already utilizing third party sync tools such as -@command{rsync} or @command{unison}, it might be preferable not to use the built in -@i{remote} publishing facilities of Org mode which rely heavily on -Tramp. Tramp, while very useful and powerful, tends not to be -so efficient for multiple file transfer and has been known to cause problems -under heavy usage. - -Specialized synchronization utilities offer several advantages. In addition -to timestamp comparison, they also do content and permissions/attribute -checks. For this reason you might prefer to publish your web to a local -directory (possibly even @i{in place} with your Org files) and then use -@file{unison} or @file{rsync} to do the synchronization with the remote host. - -Since Unison (for example) can be configured as to which files to transfer to -a certain remote destination, it can greatly simplify the project publishing -definition. Simply keep all files in the correct location, process your Org -files with @code{org-publish} and let the synchronization tool do the rest. -You do not need, in this scenario, to include attachments such as @file{jpg}, -@file{css} or @file{gif} files in the project definition since the 3rd party -tool syncs them. - -Publishing to a local directory is also much faster than to a remote one, so -that you can afford more easily to republish entire projects. If you set -@code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main -benefit of re-including any changed external files such as source example -files you might include with @code{#+INCLUDE}. The timestamp mechanism in -Org is not smart enough to detect if included files have been modified. - -@node Sample configuration, Triggering publication, Uploading files, Publishing -@section Sample configuration - -Below we provide two example configurations. The first one is a simple -project publishing only a set of Org files. The second example is -more complex, with a multi-component project. - -@menu -* Simple example:: One-component publishing -* Complex example:: A multi-component publishing example -@end menu - -@node Simple example, Complex example, Sample configuration, Sample configuration -@subsection Example: simple publishing configuration - -This example publishes a set of Org files to the @file{public_html} -directory on the local machine. - -@lisp -(setq org-publish-project-alist - '(("org" - :base-directory "~/org/" - :publishing-directory "~/public_html" - :section-numbers nil - :table-of-contents nil - :style ""))) -@end lisp - -@node Complex example, , Simple example, Sample configuration -@subsection Example: complex publishing configuration - -This more complicated example publishes an entire website, including -Org files converted to HTML, image files, Emacs Lisp source code, and -style sheets. The publishing directory is remote and private files are -excluded. - -To ensure that links are preserved, care should be taken to replicate -your directory structure on the web server, and to use relative file -paths. For example, if your Org files are kept in @file{~/org} and your -publishable images in @file{~/images}, you would link to an image with -@c -@example -file:../images/myimage.png -@end example -@c -On the web server, the relative path to the image should be the -same. You can accomplish this by setting up an "images" folder in the -right place on the web server, and publishing images to it. - -@lisp -(setq org-publish-project-alist - '(("orgfiles" - :base-directory "~/org/" - :base-extension "org" - :publishing-directory "/ssh:user@@host:~/html/notebook/" - :publishing-function org-publish-org-to-html - :exclude "PrivatePage.org" ;; regexp - :headline-levels 3 - :section-numbers nil - :table-of-contents nil - :style "" - :html-preamble t) - - ("images" - :base-directory "~/images/" - :base-extension "jpg\\|gif\\|png" - :publishing-directory "/ssh:user@@host:~/html/images/" - :publishing-function org-publish-attachment) - - ("other" - :base-directory "~/other/" - :base-extension "css\\|el" - :publishing-directory "/ssh:user@@host:~/html/other/" - :publishing-function org-publish-attachment) - ("website" :components ("orgfiles" "images" "other")))) -@end lisp - -@node Triggering publication, , Sample configuration, Publishing -@section Triggering publication - -Once properly configured, Org can publish with the following commands: - -@table @kbd -@orgcmd{C-c C-e X,org-publish} -Prompt for a specific project and publish all files that belong to it. -@orgcmd{C-c C-e P,org-publish-current-project} -Publish the project containing the current file. -@orgcmd{C-c C-e F,org-publish-current-file} -Publish only the current file. -@orgcmd{C-c C-e E,org-publish-all} -Publish every project. -@end table - -@vindex org-publish-use-timestamps-flag -Org uses timestamps to track when a file has changed. The above functions -normally only publish changed files. You can override this and force -publishing of all files by giving a prefix argument to any of the commands -above, or by customizing the variable @code{org-publish-use-timestamps-flag}. -This may be necessary in particular if files include other files via -@code{#+SETUPFILE:} or @code{#+INCLUDE:}. - -@comment node-name, next, previous, up -@comment Working With Source Code, Miscellaneous, Publishing, Top - -@node Working With Source Code, Miscellaneous, Publishing, Top -@chapter Working with source code -@cindex Schulte, Eric -@cindex Davison, Dan -@cindex source code, working with - -Source code can be included in Org mode documents using a @samp{src} block, -e.g.@: - -@example -#+BEGIN_SRC emacs-lisp - (defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) -#+END_SRC -@end example - -Org mode provides a number of features for working with live source code, -including editing of code blocks in their native major-mode, evaluation of -code blocks, converting code blocks into source files (known as @dfn{tangling} -in literate programming), and exporting code blocks and their -results in several formats. This functionality was contributed by Eric -Schulte and Dan Davison, and was originally named Org-babel. - -The following sections describe Org mode's code block handling facilities. - -@menu -* Structure of code blocks:: Code block syntax described -* Editing source code:: Language major-mode editing -* Exporting code blocks:: Export contents and/or results -* Extracting source code:: Create pure source code files -* Evaluating code blocks:: Place results of evaluation in the Org mode buffer -* Library of Babel:: Use and contribute to a library of useful code blocks -* Languages:: List of supported code block languages -* Header arguments:: Configure code block functionality -* Results of evaluation:: How evaluation results are handled -* Noweb reference syntax:: Literate programming in Org mode -* Key bindings and useful functions:: Work quickly with code blocks -* Batch execution:: Call functions from the command line -@end menu - -@comment node-name, next, previous, up -@comment Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code - -@node Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code -@section Structure of code blocks -@cindex code block, structure -@cindex source code, block structure -@cindex #+NAME -@cindex #+BEGIN_SRC - -Live code blocks can be specified with a @samp{src} block or -inline.@footnote{Note that @samp{src} blocks may be inserted using Org mode's -@ref{Easy Templates} system} The structure of a @samp{src} block is - -@example -#+NAME: -#+BEGIN_SRC
- -#+END_SRC -@end example - -The @code{#+NAME:} line is optional, and can be used to name the code -block. Live code blocks require that a language be specified on the -@code{#+BEGIN_SRC} line. Switches and header arguments are optional. -@cindex source code, inline - -Live code blocks can also be specified inline using - -@example -src_@{@} -@end example - -or - -@example -src_[
]@{@} -@end example - -@table @code -@item <#+NAME: name> -This line associates a name with the code block. This is similar to the -@code{#+TBLNAME: NAME} lines that can be used to name tables in Org mode -files. Referencing the name of a code block makes it possible to evaluate -the block from other places in the file, from other files, or from Org mode -table formulas (see @ref{The spreadsheet}). Names are assumed to be unique -and the behavior of Org mode when two or more blocks share the same name is -undefined. -@cindex #+NAME -@item -The language of the code in the block (see @ref{Languages}). -@cindex source code, language -@item -Optional switches control code block export (see the discussion of switches in -@ref{Literal examples}) -@cindex source code, switches -@item
-Optional header arguments control many aspects of evaluation, export and -tangling of code blocks (see @ref{Header arguments}). -Header arguments can also be set on a per-buffer or per-subtree -basis using properties. -@item source code, header arguments -@item -Source code in the specified language. -@end table - -@comment node-name, next, previous, up -@comment Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code - -@node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code -@section Editing source code -@cindex code block, editing -@cindex source code, editing - -@kindex C-c ' -Use @kbd{C-c '} to edit the current code block. This brings up -a language major-mode edit buffer containing the body of the code -block. Saving this buffer will write the new contents back to the Org -buffer. Use @kbd{C-c '} again to exit. - -The @code{org-src-mode} minor mode will be active in the edit buffer. The -following variables can be used to configure the behavior of the edit -buffer. See also the customization group @code{org-edit-structure} for -further configuration options. - -@table @code -@item org-src-lang-modes -If an Emacs major-mode named @code{-mode} exists, where -@code{} is the language named in the header line of the code block, -then the edit buffer will be placed in that major-mode. This variable -can be used to map arbitrary language names to existing major modes. -@item org-src-window-setup -Controls the way Emacs windows are rearranged when the edit buffer is created. -@item org-src-preserve-indentation -This variable is especially useful for tangling languages such as -Python, in which whitespace indentation in the output is critical. -@item org-src-ask-before-returning-to-edit-buffer -By default, Org will ask before returning to an open edit buffer. Set this -variable to nil to switch without asking. -@end table - -To turn on native code fontification in the @emph{Org} buffer, configure the -variable @code{org-src-fontify-natively}. - -@comment node-name, next, previous, up -@comment Exporting code blocks, Extracting source code, Editing source code, Working With Source Code - -@node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code -@section Exporting code blocks -@cindex code block, exporting -@cindex source code, exporting - -It is possible to export the @emph{code} of code blocks, the @emph{results} -of code block evaluation, @emph{both} the code and the results of code block -evaluation, or @emph{none}. For most languages, the default exports code. -However, for some languages (e.g.@: @code{ditaa}) the default exports the -results of code block evaluation. For information on exporting code block -bodies, see @ref{Literal examples}. - -The @code{:exports} header argument can be used to specify export -behavior: - -@subsubheading Header arguments: -@table @code -@item :exports code -The default in most languages. The body of the code block is exported, as -described in @ref{Literal examples}. -@item :exports results -The code block will be evaluated and the results will be placed in the -Org mode buffer for export, either updating previous results of the code -block located anywhere in the buffer or, if no previous results exist, -placing the results immediately after the code block. The body of the code -block will not be exported. -@item :exports both -Both the code block and its results will be exported. -@item :exports none -Neither the code block nor its results will be exported. -@end table - -It is possible to inhibit the evaluation of code blocks during export. -Setting the @code{org-export-babel-evaluate} variable to @code{nil} will -ensure that no code blocks are evaluated as part of the export process. This -can be useful in situations where potentially untrusted Org mode files are -exported in an automated fashion, for example when Org mode is used as the -markup language for a wiki. - -@comment node-name, next, previous, up -@comment Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code -@node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code -@section Extracting source code -@cindex tangling -@cindex source code, extracting -@cindex code block, extracting source code - -Creating pure source code files by extracting code from source blocks is -referred to as ``tangling''---a term adopted from the literate programming -community. During ``tangling'' of code blocks their bodies are expanded -using @code{org-babel-expand-src-block} which can expand both variable and -``noweb'' style references (see @ref{Noweb reference syntax}). - -@subsubheading Header arguments -@table @code -@item :tangle no -The default. The code block is not included in the tangled output. -@item :tangle yes -Include the code block in the tangled output. The output file name is the -name of the org file with the extension @samp{.org} replaced by the extension -for the block language. -@item :tangle filename -Include the code block in the tangled output to file @samp{filename}. -@end table - -@kindex C-c C-v t -@subsubheading Functions -@table @code -@item org-babel-tangle -Tangle the current file. Bound to @kbd{C-c C-v t}. -@item org-babel-tangle-file -Choose a file to tangle. Bound to @kbd{C-c C-v f}. -@end table - -@subsubheading Hooks -@table @code -@item org-babel-post-tangle-hook -This hook is run from within code files tangled by @code{org-babel-tangle}. -Example applications could include post-processing, compilation or evaluation -of tangled code files. -@end table - -@node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code -@section Evaluating code blocks -@cindex code block, evaluating -@cindex source code, evaluating -@cindex #+RESULTS - -Code blocks can be evaluated@footnote{Whenever code is evaluated there is a -potential for that code to do harm. Org mode provides safeguards to ensure -that code is only evaluated after explicit confirmation from the user. For -information on these safeguards (and on how to disable them) see @ref{Code -evaluation security}.} and the results of evaluation optionally placed in the -Org mode buffer. The results of evaluation are placed following a line that -begins by default with @code{#+RESULTS} and optionally a cache identifier -and/or the name of the evaluated code block. The default value of -@code{#+RESULTS} can be changed with the customizable variable -@code{org-babel-results-keyword}. - -By default, the evaluation facility is only enabled for Lisp code blocks -specified as @code{emacs-lisp}. However, source code blocks in many languages -can be evaluated within Org mode (see @ref{Languages} for a list of supported -languages and @ref{Structure of code blocks} for information on the syntax -used to define a code block). - -@kindex C-c C-c -There are a number of ways to evaluate code blocks. The simplest is to press -@kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The -@code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove code -evaluation from the @kbd{C-c C-c} key binding.}. This will call the -@code{org-babel-execute-src-block} function to evaluate the block and insert -its results into the Org mode buffer. -@cindex #+CALL - -It is also possible to evaluate named code blocks from anywhere in an -Org mode buffer or an Org mode table. Live code blocks located in the current -Org mode buffer or in the ``Library of Babel'' (see @ref{Library of Babel}) -can be executed. Named code blocks can be executed with a separate -@code{#+CALL:} line or inline within a block of text. - -The syntax of the @code{#+CALL:} line is - -@example -#+CALL: () -#+CALL: []() -@end example - -The syntax for inline evaluation of named code blocks is - -@example -... call_() ... -... call_[]()[] ... -@end example - -@table @code -@item -The name of the code block to be evaluated (see @ref{Structure of code blocks}). -@item -Arguments specified in this section will be passed to the code block. These -arguments use standard function call syntax, rather than -header argument syntax. For example, a @code{#+CALL:} line that passes the -number four to a code block named @code{double}, which declares the header -argument @code{:var n=2}, would be written as @code{#+CALL: double(n=4)}. -@item -Inside header arguments are passed through and applied to the named code -block. These arguments use header argument syntax rather than standard -function call syntax. Inside header arguments affect how the code block is -evaluated. For example, @code{[:results output]} will collect the results of -everything printed to @code{STDOUT} during execution of the code block. -@item -End header arguments are applied to the calling instance and do not affect -evaluation of the named code block. They affect how the results are -incorporated into the Org mode buffer and how the call line is exported. For -example, @code{:results html} will insert the results of the call line -evaluation in the Org buffer, wrapped in a @code{BEGIN_HTML:} block. - -For more examples of passing header arguments to @code{#+CALL:} lines see -@ref{Header arguments in function calls}. -@end table - -@node Library of Babel, Languages, Evaluating code blocks, Working With Source Code -@section Library of Babel -@cindex babel, library of -@cindex source code, library -@cindex code block, library - -The ``Library of Babel'' consists of code blocks that can be called from any -Org mode file. Code blocks defined in the ``Library of Babel'' can be called -remotely as if they were in the current Org mode buffer (see @ref{Evaluating -code blocks} for information on the syntax of remote code block evaluation). - - -The central repository of code blocks in the ``Library of Babel'' is housed -in an Org mode file located in the @samp{contrib} directory of Org mode. - -Users can add code blocks they believe to be generally useful to their -``Library of Babel.'' The code blocks can be stored in any Org mode file and -then loaded into the library with @code{org-babel-lob-ingest}. - - -@kindex C-c C-v i -Code blocks located in any Org mode file can be loaded into the ``Library of -Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v -i}. - -@node Languages, Header arguments, Library of Babel, Working With Source Code -@section Languages -@cindex babel, languages -@cindex source code, languages -@cindex code block, languages - -Code blocks in the following languages are supported. - -@multitable @columnfractions 0.28 0.3 0.22 0.2 -@item @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier} -@item Asymptote @tab asymptote @tab Awk @tab awk -@item Emacs Calc @tab calc @tab C @tab C -@item C++ @tab C++ @tab Clojure @tab clojure -@item CSS @tab css @tab ditaa @tab ditaa -@item Graphviz @tab dot @tab Emacs Lisp @tab emacs-lisp -@item gnuplot @tab gnuplot @tab Haskell @tab haskell -@item Java @tab java @tab @tab -@item Javascript @tab js @tab LaTeX @tab latex -@item Ledger @tab ledger @tab Lisp @tab lisp -@item Lilypond @tab lilypond @tab MATLAB @tab matlab -@item Mscgen @tab mscgen @tab Objective Caml @tab ocaml -@item Octave @tab octave @tab Org mode @tab org -@item Oz @tab oz @tab Perl @tab perl -@item Plantuml @tab plantuml @tab Python @tab python -@item R @tab R @tab Ruby @tab ruby -@item Sass @tab sass @tab Scheme @tab scheme -@item GNU Screen @tab screen @tab shell @tab sh -@item SQL @tab sql @tab SQLite @tab sqlite -@end multitable - -Language-specific documentation is available for some languages. If -available, it can be found at -@uref{http://orgmode.org/worg/org-contrib/babel/languages}. - -The @code{org-babel-load-languages} controls which languages are enabled for -evaluation (by default only @code{emacs-lisp} is enabled). This variable can -be set using the customization interface or by adding code like the following -to your emacs configuration. - -@quotation -The following disables @code{emacs-lisp} evaluation and enables evaluation of -@code{R} code blocks. -@end quotation - -@lisp -(org-babel-do-load-languages - 'org-babel-load-languages - '((emacs-lisp . nil) - (R . t))) -@end lisp - -It is also possible to enable support for a language by loading the related -elisp file with @code{require}. - -@quotation -The following adds support for evaluating @code{clojure} code blocks. -@end quotation - -@lisp -(require 'ob-clojure) -@end lisp - -@node Header arguments, Results of evaluation, Languages, Working With Source Code -@section Header arguments -@cindex code block, header arguments -@cindex source code, block header arguments - -Code block functionality can be configured with header arguments. This -section provides an overview of the use of header arguments, and then -describes each header argument in detail. - -@menu -* Using header arguments:: Different ways to set header arguments -* Specific header arguments:: List of header arguments -@end menu - -@node Using header arguments, Specific header arguments, Header arguments, Header arguments -@subsection Using header arguments - -The values of header arguments can be set in six different ways, each more -specific (and having higher priority) than the last. -@menu -* System-wide header arguments:: Set global default values -* Language-specific header arguments:: Set default values by language -* Buffer-wide header arguments:: Set default values for a specific buffer -* Header arguments in Org mode properties:: Set default values for a buffer or heading -* Code block specific header arguments:: The most common way to set values -* Header arguments in function calls:: The most specific level -@end menu - - -@node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments -@subsubheading System-wide header arguments -@vindex org-babel-default-header-args -System-wide values of header arguments can be specified by customizing the -@code{org-babel-default-header-args} variable: - -@example -:session => "none" -:results => "replace" -:exports => "code" -:cache => "no" -:noweb => "no" -@end example - -@c @example -@c org-babel-default-header-args is a variable defined in `org-babel.el'. -@c Its value is -@c ((:session . "none") -@c (:results . "replace") -@c (:exports . "code") -@c (:cache . "no") -@c (:noweb . "no")) - - -@c Documentation: -@c Default arguments to use when evaluating a code block. -@c @end example - -For example, the following example could be used to set the default value of -@code{:noweb} header arguments to @code{yes}. This would have the effect of -expanding @code{:noweb} references by default when evaluating source code -blocks. - -@lisp -(setq org-babel-default-header-args -(cons '(:noweb . "yes") -(assq-delete-all :noweb org-babel-default-header-args))) -@end lisp - -@node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments -@subsubheading Language-specific header arguments -Each language can define its own set of default header arguments. See the -language-specific documentation available online at -@uref{http://orgmode.org/worg/org-contrib/babel}. - -@node Buffer-wide header arguments, Header arguments in Org mode properties, Language-specific header arguments, Using header arguments -@subsubheading Buffer-wide header arguments -Buffer-wide header arguments may be specified as properties through the use -of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see -@ref{Property syntax}). - -For example the following would set @code{session} to @code{*R*}, and -@code{results} to @code{silent} for every code block in the buffer, ensuring -that all execution took place in the same session, and no results would be -inserted into the buffer. - -@example -#+PROPERTY: session *R* -#+PROPERTY: results silent -@end example - -@node Header arguments in Org mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments -@subsubheading Header arguments in Org mode properties - -Header arguments are also read from Org mode properties (see @ref{Property -syntax}), which can be set on a buffer-wide or per-heading basis. An example -of setting a header argument for all code blocks in a buffer is - -@example -#+PROPERTY: tangle yes -@end example - -@vindex org-use-property-inheritance -When properties are used to set default header arguments, they are looked up -with inheritance, regardless of the value of -@code{org-use-property-inheritance}. In the following example the value of -the @code{:cache} header argument will default to @code{yes} in all code -blocks in the subtree rooted at the following heading: - -@example -* outline header -:PROPERTIES: -:cache: yes -:END: -@end example - -@kindex C-c C-x p -@vindex org-babel-default-header-args -Properties defined in this way override the properties set in -@code{org-babel-default-header-args}. It is convenient to use the -@code{org-set-property} function bound to @kbd{C-c C-x p} to set properties -in Org mode documents. - -@node Code block specific header arguments, Header arguments in function calls, Header arguments in Org mode properties, Using header arguments -@subsubheading Code block specific header arguments - -The most common way to assign values to header arguments is at the -code block level. This can be done by listing a sequence of header -arguments and their values as part of the @code{#+BEGIN_SRC} line. -Properties set in this way override both the values of -@code{org-babel-default-header-args} and header arguments specified as -properties. In the following example, the @code{:results} header argument -is set to @code{silent}, meaning the results of execution will not be -inserted in the buffer, and the @code{:exports} header argument is set to -@code{code}, meaning only the body of the code block will be -preserved on export to HTML or @LaTeX{}. - -@example -#+NAME: factorial -#+BEGIN_SRC haskell :results silent :exports code :var n=0 -fac 0 = 1 -fac n = n * fac (n-1) -#+END_SRC -@end example -Similarly, it is possible to set header arguments for inline code blocks - -@example -src_haskell[:exports both]@{fac 5@} -@end example - -Code block header arguments can span multiple lines using @code{#+HEADER:} or -@code{#+HEADERS:} lines preceding a code block or nested between the -@code{#+NAME:} line and the @code{#+BEGIN_SRC} line of a named code block. -@cindex #+HEADER: -@cindex #+HEADERS: - -Multi-line header arguments on an un-named code block: -@example - #+HEADERS: :var data1=1 - #+BEGIN_SRC emacs-lisp :var data2=2 - (message "data1:%S, data2:%S" data1 data2) - #+END_SRC - - #+results: - : data1:1, data2:2 -@end example - -Multi-line header arguments on a named code block: -@example - #+NAME: named-block - #+HEADER: :var data=2 - #+BEGIN_SRC emacs-lisp - (message "data:%S" data) - #+END_SRC - - #+results: named-block - : data:2 -@end example - -@node Header arguments in function calls, , Code block specific header arguments, Using header arguments -@comment node-name, next, previous, up -@subsubheading Header arguments in function calls - -At the most specific level, header arguments for ``Library of Babel'' or -@code{#+CALL:} lines can be set as shown in the two examples below. For more -information on the structure of @code{#+CALL:} lines see @ref{Evaluating code -blocks}. - -The following will apply the @code{:exports results} header argument to the -evaluation of the @code{#+CALL:} line. -@example -#+CALL: factorial(n=5) :exports results -@end example - -The following will apply the @code{:session special} header argument to the -evaluation of the @code{factorial} code block. -@example -#+CALL: factorial[:session special](n=5) -@end example - -@node Specific header arguments, , Using header arguments, Header arguments -@subsection Specific header arguments -Header arguments consist of an initial colon followed by the name of the -argument in lowercase letters. The following header arguments are defined: - -@menu -* var:: Pass arguments to code blocks -* results:: Specify the type of results and how they will - be collected and handled -* file:: Specify a path for file output -* dir:: Specify the default (possibly remote) - directory for code block execution -* exports:: Export code and/or results -* tangle:: Toggle tangling and specify file name -* mkdirp:: Toggle creation of parent directories of target - files during tangling -* comments:: Toggle insertion of comments in tangled - code files -* padline:: Control insertion of padding lines in tangled - code files -* no-expand:: Turn off variable assignment and noweb - expansion during tangling -* session:: Preserve the state of code evaluation -* noweb:: Toggle expansion of noweb references -* noweb-ref:: Specify block's noweb reference resolution target -* noweb-sep:: String used to separate noweb references -* cache:: Avoid re-evaluating unchanged code blocks -* sep:: Delimiter for writing tabular results outside Org -* hlines:: Handle horizontal lines in tables -* colnames:: Handle column names in tables -* rownames:: Handle row names in tables -* shebang:: Make tangled files executable -* eval:: Limit evaluation of specific code blocks -@end menu - -Additional header arguments are defined on a language-specific basis, see -@ref{Languages}. - -@node var, results, Specific header arguments, Specific header arguments -@subsubsection @code{:var} -The @code{:var} header argument is used to pass arguments to code blocks. -The specifics of how arguments are included in a code block vary by language; -these are addressed in the language-specific documentation. However, the -syntax used to specify arguments is the same across all languages. In every -case, variables require a default value when they are declared. - -The values passed to arguments can either be literal values, references, or -Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}). References -include anything in the Org mode file that takes a @code{#+NAME:}, -@code{#+TBLNAME:}, or @code{#+RESULTS:} line. This includes tables, lists, -@code{#+BEGIN_EXAMPLE} blocks, other code blocks, and the results of other -code blocks. - -Argument values can be indexed in a manner similar to arrays (see @ref{var, -Indexable variable values}). - -The following syntax is used to pass arguments to code blocks using the -@code{:var} header argument. - -@example -:var name=assign -@end example - -The argument, @code{assign}, can either be a literal value, such as a string -@samp{"string"} or a number @samp{9}, or a reference to a table, a list, a -literal example, another code block (with or without arguments), or the -results of evaluating another code block. - -Here are examples of passing values by reference: - -@table @dfn - -@item table -an Org mode table named with either a @code{#+NAME:} or @code{#+TBLNAME:} line -@example -#+TBLNAME: example-table -| 1 | -| 2 | -| 3 | -| 4 | - -#+NAME: table-length -#+BEGIN_SRC emacs-lisp :var table=example-table -(length table) -#+END_SRC - -#+results: table-length -: 4 -@end example - -@item list -a simple list named with a @code{#+NAME:} line (note that nesting is not -carried through to the source code block) - -@example -#+NAME: example-list - - simple - - not - - nested - - list - -#+BEGIN_SRC emacs-lisp :var x=example-list - (print x) -#+END_SRC - -#+results: -| simple | list | -@end example - -@item code block without arguments -a code block name (from the example above), as assigned by @code{#+NAME:}, -optionally followed by parentheses - -@example -#+BEGIN_SRC emacs-lisp :var length=table-length() -(* 2 length) -#+END_SRC - -#+results: -: 8 -@end example - -@item code block with arguments -a code block name, as assigned by @code{#+NAME:}, followed by parentheses and -optional arguments passed within the parentheses following the -code block name using standard function call syntax - -@example -#+NAME: double -#+BEGIN_SRC emacs-lisp :var input=8 -(* 2 input) -#+END_SRC - -#+results: double -: 16 - -#+NAME: squared -#+BEGIN_SRC emacs-lisp :var input=double(input=1) -(* input input) -#+END_SRC - -#+results: squared -: 4 -@end example - -@item literal example -a literal example block named with a @code{#+NAME:} line - -@example -#+NAME: literal-example -#+BEGIN_EXAMPLE -A literal example -on two lines -#+END_EXAMPLE - -#+NAME: read-literal-example -#+BEGIN_SRC emacs-lisp :var x=literal-example - (concatenate 'string x " for you.") -#+END_SRC - -#+results: read-literal-example -: A literal example -: on two lines for you. - -@end example - -@end table - -@subsubheading Alternate argument syntax -It is also possible to specify arguments in a potentially more natural way -using the @code{#+NAME:} line of a code block. As in the following -example, arguments can be packed inside of parentheses, separated by commas, -following the source name. - -@example -#+NAME: double(input=0, x=2) -#+BEGIN_SRC emacs-lisp -(* 2 (+ input x)) -#+END_SRC -@end example - -@subsubheading Indexable variable values -It is possible to reference portions of variable values by ``indexing'' into -the variables. Indexes are 0 based with negative values counting back from -the end. If an index is separated by @code{,}s then each subsequent section -will index into the next deepest nesting or dimension of the value. Note -that this indexing occurs @emph{before} other table related header arguments -like @code{:hlines}, @code{:colnames} and @code{:rownames} are applied. The -following example assigns the last cell of the first row the table -@code{example-table} to the variable @code{data}: - -@example -#+NAME: example-table -| 1 | a | -| 2 | b | -| 3 | c | -| 4 | d | - -#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1] - data -#+END_SRC - -#+results: -: a -@end example - -Ranges of variable values can be referenced using two integers separated by a -@code{:}, in which case the entire inclusive range is referenced. For -example the following assigns the middle three rows of @code{example-table} -to @code{data}. - -@example -#+NAME: example-table -| 1 | a | -| 2 | b | -| 3 | c | -| 4 | d | -| 5 | 3 | - -#+BEGIN_SRC emacs-lisp :var data=example-table[1:3] - data -#+END_SRC - -#+results: -| 2 | b | -| 3 | c | -| 4 | d | -@end example - -Additionally, an empty index, or the single character @code{*}, are both -interpreted to mean the entire range and as such are equivalent to -@code{0:-1}, as shown in the following example in which the entire first -column is referenced. - -@example -#+NAME: example-table -| 1 | a | -| 2 | b | -| 3 | c | -| 4 | d | - -#+BEGIN_SRC emacs-lisp :var data=example-table[,0] - data -#+END_SRC - -#+results: -| 1 | 2 | 3 | 4 | -@end example - -It is possible to index into the results of code blocks as well as tables. -Any number of dimensions can be indexed. Dimensions are separated from one -another by commas, as shown in the following example. - -@example -#+NAME: 3D -#+BEGIN_SRC emacs-lisp - '(((1 2 3) (4 5 6) (7 8 9)) - ((10 11 12) (13 14 15) (16 17 18)) - ((19 20 21) (22 23 24) (25 26 27))) -#+END_SRC - -#+BEGIN_SRC emacs-lisp :var data=3D[1,,1] - data -#+END_SRC - -#+results: -| 11 | 14 | 17 | -@end example - -@subsubheading Emacs Lisp evaluation of variables - -Emacs lisp code can be used to initialize variable values. When a variable -value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be -evaluated as Emacs Lisp and the result of the evaluation will be assigned as -the variable value. The following example demonstrates use of this -evaluation to reliably pass the file-name of the Org mode buffer to a code -block---note that evaluation of header arguments is guaranteed to take place -in the original Org mode file, while there is no such guarantee for -evaluation of the code block body. - -@example -#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both - wc -w $filename -#+END_SRC -@end example - -Note that values read from tables and lists will not be evaluated as -Emacs Lisp, as shown in the following example. - -@example -#+NAME: table -| (a b c) | - -#+HEADERS: :var data=table[0,0] -#+BEGIN_SRC perl - $data -#+END_SRC - -#+results: -: (a b c) -@end example - -@node results, file, var, Specific header arguments -@subsubsection @code{:results} - -There are three classes of @code{:results} header argument. Only one option -per class may be supplied per code block. - -@itemize @bullet -@item -@b{collection} header arguments specify how the results should be collected -from the code block -@item -@b{type} header arguments specify what type of result the code block will -return---which has implications for how they will be inserted into the -Org mode buffer -@item -@b{handling} header arguments specify how the results of evaluating the code -block should be handled. -@end itemize - -@subsubheading Collection -The following options are mutually exclusive, and specify how the results -should be collected from the code block. - -@itemize @bullet -@item @code{value} -This is the default. The result is the value of the last statement in the -code block. This header argument places the evaluation in functional -mode. Note that in some languages, e.g., Python, use of this result type -requires that a @code{return} statement be included in the body of the source -code block. E.g., @code{:results value}. -@item @code{output} -The result is the collection of everything printed to STDOUT during the -execution of the code block. This header argument places the -evaluation in scripting mode. E.g., @code{:results output}. -@end itemize - -@subsubheading Type - -The following options are mutually exclusive and specify what type of results -the code block will return. By default, results are inserted as either a -table or scalar depending on their value. - -@itemize @bullet -@item @code{table}, @code{vector} -The results should be interpreted as an Org mode table. If a single value is -returned, it will be converted into a table with one row and one column. -E.g., @code{:results value table}. -@item @code{list} -The results should be interpreted as an Org mode list. If a single scalar -value is returned it will be converted into a list with only one element. -@item @code{scalar}, @code{verbatim} -The results should be interpreted literally---they will not be -converted into a table. The results will be inserted into the Org mode -buffer as quoted text. E.g., @code{:results value verbatim}. -@item @code{file} -The results will be interpreted as the path to a file, and will be inserted -into the Org mode buffer as a file link. E.g., @code{:results value file}. -@item @code{raw}, @code{org} -The results are interpreted as raw Org mode code and are inserted directly -into the buffer. If the results look like a table they will be aligned as -such by Org mode. E.g., @code{:results value raw}. -@item @code{html} -Results are assumed to be HTML and will be enclosed in a @code{begin_html} -block. E.g., @code{:results value html}. -@item @code{latex} -Results assumed to be @LaTeX{} and are enclosed in a @code{begin_latex} block. -E.g., @code{:results value latex}. -@item @code{code} -Result are assumed to be parsable code and are enclosed in a code block. -E.g., @code{:results value code}. -@item @code{pp} -The result is converted to pretty-printed code and is enclosed in a code -block. This option currently supports Emacs Lisp, Python, and Ruby. E.g., -@code{:results value pp}. -@item @code{wrap} -The result is wrapped in a RESULTS drawer. This can be useful for -inserting @code{raw} or @code{org} syntax results in such a way that their -extent is known and they can be automatically removed or replaced. -@end itemize - -@subsubheading Handling -The following results options indicate what happens with the -results once they are collected. - -@itemize @bullet -@item @code{silent} -The results will be echoed in the minibuffer but will not be inserted into -the Org mode buffer. E.g., @code{:results output silent}. -@item @code{replace} -The default value. Any existing results will be removed, and the new results -will be inserted into the Org mode buffer in their place. E.g., -@code{:results output replace}. -@item @code{append} -If there are pre-existing results of the code block then the new results will -be appended to the existing results. Otherwise the new results will be -inserted as with @code{replace}. -@item @code{prepend} -If there are pre-existing results of the code block then the new results will -be prepended to the existing results. Otherwise the new results will be -inserted as with @code{replace}. -@end itemize - -@node file, dir, results, Specific header arguments -@subsubsection @code{:file} - -The header argument @code{:file} is used to specify an external file in which -to save code block results. After code block evaluation an Org mode style -@code{[[file:]]} link (see @ref{Link format}) to the file will be inserted -into the Org mode buffer. Some languages including R, gnuplot, dot, and -ditaa provide special handling of the @code{:file} header argument -automatically wrapping the code block body in the boilerplate code required -to save output to the specified file. This is often useful for saving -graphical output of a code block to the specified file. - -The argument to @code{:file} should be either a string specifying the path to -a file, or a list of two strings in which case the first element of the list -should be the path to a file and the second a description for the link. - -@node dir, exports, file, Specific header arguments -@subsubsection @code{:dir} and remote execution - -While the @code{:file} header argument can be used to specify the path to the -output file, @code{:dir} specifies the default directory during code block -execution. If it is absent, then the directory associated with the current -buffer is used. In other words, supplying @code{:dir path} temporarily has -the same effect as changing the current directory with @kbd{M-x cd path}, and -then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets -the value of the Emacs variable @code{default-directory}. - -When using @code{:dir}, you should supply a relative path for file output -(e.g.@: @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which -case that path will be interpreted relative to the default directory. - -In other words, if you want your plot to go into a folder called @file{Work} -in your home directory, you could use - -@example -#+BEGIN_SRC R :file myplot.png :dir ~/Work -matplot(matrix(rnorm(100), 10), type="l") -#+END_SRC -@end example - -@subsubheading Remote execution -A directory on a remote machine can be specified using tramp file syntax, in -which case the code will be evaluated on the remote machine. An example is - -@example -#+BEGIN_SRC R :file plot.png :dir /dand@@yakuba.princeton.edu: -plot(1:10, main=system("hostname", intern=TRUE)) -#+END_SRC -@end example - -Text results will be returned to the local Org mode buffer as usual, and file -output will be created on the remote machine with relative paths interpreted -relative to the remote directory. An Org mode link to the remote file will be -created. - -So, in the above example a plot will be created on the remote machine, -and a link of the following form will be inserted in the org buffer: - -@example -[[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] -@end example - -Most of this functionality follows immediately from the fact that @code{:dir} -sets the value of the Emacs variable @code{default-directory}, thanks to -tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to -install tramp separately in order for these features to work correctly. - -@subsubheading Further points - -@itemize @bullet -@item -If @code{:dir} is used in conjunction with @code{:session}, although it will -determine the starting directory for a new session as expected, no attempt is -currently made to alter the directory associated with an existing session. -@item -@code{:dir} should typically not be used to create files during export with -@code{:exports results} or @code{:exports both}. The reason is that, in order -to retain portability of exported material between machines, during export -links inserted into the buffer will @emph{not} be expanded against @code{default -directory}. Therefore, if @code{default-directory} is altered using -@code{:dir}, it is probable that the file will be created in a location to -which the link does not point. -@end itemize - -@node exports, tangle, dir, Specific header arguments -@subsubsection @code{:exports} - -The @code{:exports} header argument specifies what should be included in HTML -or @LaTeX{} exports of the Org mode file. - -@itemize @bullet -@item @code{code} -The default. The body of code is included into the exported file. E.g., -@code{:exports code}. -@item @code{results} -The result of evaluating the code is included in the exported file. E.g., -@code{:exports results}. -@item @code{both} -Both the code and results are included in the exported file. E.g., -@code{:exports both}. -@item @code{none} -Nothing is included in the exported file. E.g., @code{:exports none}. -@end itemize - -@node tangle, mkdirp, exports, Specific header arguments -@subsubsection @code{:tangle} - -The @code{:tangle} header argument specifies whether or not the code -block should be included in tangled extraction of source code files. - -@itemize @bullet -@item @code{tangle} -The code block is exported to a source code file named after the full path -(including the directory) and file name (w/o extension) of the Org mode file. -E.g., @code{:tangle yes}. -@item @code{no} -The default. The code block is not exported to a source code file. -E.g., @code{:tangle no}. -@item other -Any other string passed to the @code{:tangle} header argument is interpreted -as a path (directory and file name relative to the directory of the Org mode -file) to which the block will be exported. E.g., @code{:tangle path}. -@end itemize - -@node mkdirp, comments, tangle, Specific header arguments -@subsubsection @code{:mkdirp} - -The @code{:mkdirp} header argument can be used to create parent directories -of tangled files when missing. This can be set to @code{yes} to enable -directory creation or to @code{no} to inhibit directory creation. - -@node comments, padline, mkdirp, Specific header arguments -@subsubsection @code{:comments} -By default code blocks are tangled to source-code files without any insertion -of comments beyond those which may already exist in the body of the code -block. The @code{:comments} header argument can be set as follows to control -the insertion of extra comments into the tangled code file. - -@itemize @bullet -@item @code{no} -The default. No extra comments are inserted during tangling. -@item @code{link} -The code block is wrapped in comments which contain pointers back to the -original Org file from which the code was tangled. -@item @code{yes} -A synonym for ``link'' to maintain backwards compatibility. -@item @code{org} -Include text from the Org mode file as a comment. - -The text is picked from the leading context of the tangled code and is -limited by the nearest headline or source block as the case may be. -@item @code{both} -Turns on both the ``link'' and ``org'' comment options. -@item @code{noweb} -Turns on the ``link'' comment option, and additionally wraps expanded noweb -references in the code block body in link comments. -@end itemize - -@node padline, no-expand, comments, Specific header arguments -@subsubsection @code{:padline} -Control in insertion of padding lines around code block bodies in tangled -code files. The default value is @code{yes} which results in insertion of -newlines before and after each tangled code block. The following arguments -are accepted. - -@itemize @bullet -@item @code{yes} -Insert newlines before and after each code block body in tangled code files. -@item @code{no} -Do not insert any newline padding in tangled output. -@end itemize - -@node no-expand, session, padline, Specific header arguments -@subsubsection @code{:no-expand} - -By default, code blocks are expanded with @code{org-babel-expand-src-block} -during tangling. This has the effect of assigning values to variables -specified with @code{:var} (see @ref{var}), and of replacing ``noweb'' -references (see @ref{Noweb reference syntax}) with their targets. The -@code{:no-expand} header argument can be used to turn off this behavior. - -@node session, noweb, no-expand, Specific header arguments -@subsubsection @code{:session} - -The @code{:session} header argument starts a session for an interpreted -language where state is preserved. - -By default, a session is not started. - -A string passed to the @code{:session} header argument will give the session -a name. This makes it possible to run concurrent sessions for each -interpreted language. - -@node noweb, noweb-ref, session, Specific header arguments -@subsubsection @code{:noweb} - -The @code{:noweb} header argument controls expansion of ``noweb'' style (see -@ref{Noweb reference syntax}) references in a code block. This header -argument can have one of three values: @code{yes}, @code{no}, or @code{tangle}. - -@itemize @bullet -@item @code{yes} -All ``noweb'' syntax references in the body of the code block will be -expanded before the block is evaluated, tangled or exported. -@item @code{no} -The default. No ``noweb'' syntax specific action is taken when the code -block is evaluated, tangled or exported. -@item @code{tangle} -All ``noweb'' syntax references in the body of the code block will be -expanded before the block is tangled, however ``noweb'' references will not -be expanded when the block is evaluated or exported. -@end itemize - -@subsubheading Noweb prefix lines -Noweb insertions are now placed behind the line prefix of the -@code{<>}. -This behavior is illustrated in the following example. Because the -@code{<>} noweb reference appears behind the SQL comment syntax, -each line of the expanded noweb reference will be commented. - -This code block: - -@example --- <> -@end example - - -expands to: - -@example --- this is the --- multi-line body of example -@end example - -Note that noweb replacement text that does not contain any newlines will not -be affected by this change, so it is still possible to use inline noweb -references. - -@node noweb-ref, noweb-sep, noweb, Specific header arguments -@subsubsection @code{:noweb-ref} -When expanding ``noweb'' style references the bodies of all code block with -@emph{either} a block name matching the reference name @emph{or} a -@code{:noweb-ref} header argument matching the reference name will be -concatenated together to form the replacement text. - -By setting this header argument at the sub-tree or file level, simple code -block concatenation may be achieved. For example, when tangling the -following Org mode file, the bodies of code blocks will be concatenated into -the resulting pure code file@footnote{(The example needs property inheritance -to be turned on for the @code{noweb-ref} property, see @ref{Property -inheritance}).}. - -@example - #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh - <> - #+END_SRC - * the mount point of the fullest disk - :PROPERTIES: - :noweb-ref: fullest-disk - :END: - - ** query all mounted disks - #+BEGIN_SRC sh - df \ - #+END_SRC - - ** strip the header row - #+BEGIN_SRC sh - |sed '1d' \ - #+END_SRC - - ** sort by the percent full - #+BEGIN_SRC sh - |awk '@{print $5 " " $6@}'|sort -n |tail -1 \ - #+END_SRC - - ** extract the mount point - #+BEGIN_SRC sh - |awk '@{print $2@}' - #+END_SRC -@end example - -The @code{:noweb-sep} (see @ref{noweb-sep}) header argument holds the string -used to separate accumulate noweb references like those above. By default a -newline is used. - -@node noweb-sep, cache, noweb-ref, Specific header arguments -@subsubsection @code{:noweb-sep} - -The @code{:noweb-sep} header argument holds the string used to separate -accumulate noweb references (see @ref{noweb-ref}). By default a newline is -used. - -@node cache, sep, noweb-sep, Specific header arguments -@subsubsection @code{:cache} - -The @code{:cache} header argument controls the use of in-buffer caching of -the results of evaluating code blocks. It can be used to avoid re-evaluating -unchanged code blocks. Note that the @code{:cache} header argument will not -attempt to cache results when the @code{:session} header argument is used, -because the results of the code block execution may be stored in the session -outside of the Org-mode buffer. The @code{:cache} header argument can have -one of two values: @code{yes} or @code{no}. - -@itemize @bullet -@item @code{no} -The default. No caching takes place, and the code block will be evaluated -every time it is called. -@item @code{yes} -Every time the code block is run a SHA1 hash of the code and arguments -passed to the block will be generated. This hash is packed into the -@code{#+results:} line and will be checked on subsequent -executions of the code block. If the code block has not -changed since the last time it was evaluated, it will not be re-evaluated. -@end itemize - -Code block caches notice if the value of a variable argument -to the code block has changed. If this is the case, the cache is -invalidated and the code block is re-run. In the following example, -@code{caller} will not be re-run unless the results of @code{random} have -changed since it was last run. - -@example - #+NAME: random - #+BEGIN_SRC R :cache yes - runif(1) - #+END_SRC - - #+results[a2a72cd647ad44515fab62e144796432793d68e1]: random - 0.4659510825295 - - #+NAME: caller - #+BEGIN_SRC emacs-lisp :var x=random :cache yes - x - #+END_SRC - - #+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller - 0.254227238707244 -@end example - -@node sep, hlines, cache, Specific header arguments -@subsubsection @code{:sep} - -The @code{:sep} header argument can be used to control the delimiter used -when writing tabular results out to files external to Org mode. This is used -either when opening tabular results of a code block by calling the -@code{org-open-at-point} function bound to @kbd{C-c C-o} on the code block, -or when writing code block results to an external file (see @ref{file}) -header argument. - -By default, when @code{:sep} is not specified output tables are tab -delimited. - -@node hlines, colnames, sep, Specific header arguments -@subsubsection @code{:hlines} - -Tables are frequently represented with one or more horizontal lines, or -hlines. The @code{:hlines} argument to a code block accepts the -values @code{yes} or @code{no}, with a default value of @code{no}. - -@itemize @bullet -@item @code{no} -Strips horizontal lines from the input table. In most languages this is the -desired effect because an @code{hline} symbol is interpreted as an unbound -variable and raises an error. Setting @code{:hlines no} or relying on the -default value yields the following results. - -@example -#+TBLNAME: many-cols -| a | b | c | -|---+---+---| -| d | e | f | -|---+---+---| -| g | h | i | - -#+NAME: echo-table -#+BEGIN_SRC python :var tab=many-cols - return tab -#+END_SRC - -#+results: echo-table -| a | b | c | -| d | e | f | -| g | h | i | -@end example - -@item @code{yes} -Leaves hlines in the table. Setting @code{:hlines yes} has this effect. - -@example -#+TBLNAME: many-cols -| a | b | c | -|---+---+---| -| d | e | f | -|---+---+---| -| g | h | i | - -#+NAME: echo-table -#+BEGIN_SRC python :var tab=many-cols :hlines yes - return tab -#+END_SRC - -#+results: echo-table -| a | b | c | -|---+---+---| -| d | e | f | -|---+---+---| -| g | h | i | -@end example -@end itemize - -@node colnames, rownames, hlines, Specific header arguments -@subsubsection @code{:colnames} - -The @code{:colnames} header argument accepts the values @code{yes}, -@code{no}, or @code{nil} for unassigned. The default value is @code{nil}. -Note that the behavior of the @code{:colnames} header argument may differ -across languages. For example Emacs Lisp code blocks ignore the -@code{:colnames} header argument entirely given the ease with which tables -with column names may be handled directly in Emacs Lisp. - -@itemize @bullet -@item @code{nil} -If an input table looks like it has column names -(because its second row is an hline), then the column -names will be removed from the table before -processing, then reapplied to the results. - -@example -#+TBLNAME: less-cols -| a | -|---| -| b | -| c | - -#+NAME: echo-table-again -#+BEGIN_SRC python :var tab=less-cols - return [[val + '*' for val in row] for row in tab] -#+END_SRC - -#+results: echo-table-again -| a | -|----| -| b* | -| c* | -@end example - -Please note that column names are not removed before the table is indexed -using variable indexing @xref{var, Indexable variable values}. - -@item @code{no} -No column name pre-processing takes place - -@item @code{yes} -Column names are removed and reapplied as with @code{nil} even if the table -does not ``look like'' it has column names (i.e.@: the second row is not an -hline) -@end itemize - -@node rownames, shebang, colnames, Specific header arguments -@subsubsection @code{:rownames} - -The @code{:rownames} header argument can take on the values @code{yes} -or @code{no}, with a default value of @code{no}. - -@itemize @bullet -@item @code{no} -No row name pre-processing will take place. - -@item @code{yes} -The first column of the table is removed from the table before processing, -and is then reapplied to the results. - -@example -#+TBLNAME: with-rownames -| one | 1 | 2 | 3 | 4 | 5 | -| two | 6 | 7 | 8 | 9 | 10 | - -#+NAME: echo-table-once-again -#+BEGIN_SRC python :var tab=with-rownames :rownames yes - return [[val + 10 for val in row] for row in tab] -#+END_SRC - -#+results: echo-table-once-again -| one | 11 | 12 | 13 | 14 | 15 | -| two | 16 | 17 | 18 | 19 | 20 | -@end example - -Please note that row names are not removed before the table is indexed using -variable indexing @xref{var, Indexable variable values}. - -@end itemize - -@node shebang, eval, rownames, Specific header arguments -@subsubsection @code{:shebang} - -Setting the @code{:shebang} header argument to a string value -(e.g.@: @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the -first line of any tangled file holding the code block, and the file -permissions of the tangled file are set to make it executable. - -@node eval, , shebang, Specific header arguments -@subsubsection @code{:eval} -The @code{:eval} header argument can be used to limit the evaluation of -specific code blocks. The @code{:eval} header argument can be useful for -protecting against the evaluation of dangerous code blocks or to ensure that -evaluation will require a query regardless of the value of the -@code{org-confirm-babel-evaluate} variable. The possible values of -@code{:eval} and their effects are shown below. - -@table @code -@item never or no -The code block will not be evaluated under any circumstances. -@item query -Evaluation of the code block will require a query. -@item never-export or no-export -The code block will not be evaluated during export but may still be called -interactively. -@item query-export -Evaluation of the code block during export will require a query. -@end table - -If this header argument is not set then evaluation is determined by the value -of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation -security}. - -@node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code -@section Results of evaluation -@cindex code block, results of evaluation -@cindex source code, results of evaluation - -The way in which results are handled depends on whether a session is invoked, -as well as on whether @code{:results value} or @code{:results output} is -used. The following table shows the table possibilities. For a full listing -of the possible results header arguments see @ref{results}. - -@multitable @columnfractions 0.26 0.33 0.41 -@item @tab @b{Non-session} @tab @b{Session} -@item @code{:results value} @tab value of last expression @tab value of last expression -@item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output -@end multitable - -Note: With @code{:results value}, the result in both @code{:session} and -non-session is returned to Org mode as a table (a one- or two-dimensional -vector of strings or numbers) when appropriate. - -@subsection Non-session -@subsubsection @code{:results value} -This is the default. Internally, the value is obtained by wrapping the code -in a function definition in the external language, and evaluating that -function. Therefore, code should be written as if it were the body of such a -function. In particular, note that Python does not automatically return a -value from a function unless a @code{return} statement is present, and so a -@samp{return} statement will usually be required in Python. - -This is the only one of the four evaluation contexts in which the code is -automatically wrapped in a function definition. - -@subsubsection @code{:results output} -The code is passed to the interpreter as an external process, and the -contents of the standard output stream are returned as text. (In certain -languages this also contains the error output stream; this is an area for -future work.) - -@subsection Session -@subsubsection @code{:results value} -The code is passed to an interpreter running as an interactive Emacs inferior -process. Only languages which provide tools for interactive evaluation of -code have session support, so some language (e.g., C and ditaa) do not -support the @code{:session} header argument, and in other languages (e.g., -Python and Haskell) which have limitations on the code which may be entered -into interactive sessions, those limitations apply to the code in code blocks -using the @code{:session} header argument as well. - -Unless the @code{:results output} option is supplied (see below) the result -returned is the result of the last evaluation performed by the -interpreter. (This is obtained in a language-specific manner: the value of -the variable @code{_} in Python and Ruby, and the value of @code{.Last.value} -in R). - -@subsubsection @code{:results output} -The code is passed to the interpreter running as an interactive Emacs -inferior process. The result returned is the concatenation of the sequence of -(text) output from the interactive interpreter. Notice that this is not -necessarily the same as what would be sent to @code{STDOUT} if the same code -were passed to a non-interactive interpreter running as an external -process. For example, compare the following two blocks: - -@example -#+BEGIN_SRC python :results output - print "hello" - 2 - print "bye" -#+END_SRC - -#+results: -: hello -: bye -@end example - -In non-session mode, the `2' is not printed and does not appear. -@example -#+BEGIN_SRC python :results output :session - print "hello" - 2 - print "bye" -#+END_SRC - -#+results: -: hello -: 2 -: bye -@end example - -But in @code{:session} mode, the interactive interpreter receives input `2' -and prints out its value, `2'. (Indeed, the other print statements are -unnecessary here). - -@node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working With Source Code -@section Noweb reference syntax -@cindex code block, noweb reference -@cindex syntax, noweb -@cindex source code, noweb reference - -The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate -Programming system allows named blocks of code to be referenced by using the -familiar Noweb syntax: - -@example -<> -@end example - -When a code block is tangled or evaluated, whether or not ``noweb'' -references are expanded depends upon the value of the @code{:noweb} header -argument. If @code{:noweb yes}, then a Noweb reference is expanded before -evaluation. If @code{:noweb no}, the default, then the reference is not -expanded before evaluation. See the @ref{noweb-ref} header argument for -a more flexible way to resolve noweb references. - -It is possible to include the @emph{results} of a code block rather than the -body. This is done by appending parenthesis to the code block name which may -optionally contain arguments to the code block as shown below. - -@example -<> -@end example - -Note: the default value, @code{:noweb no}, was chosen to ensure that -correct code is not broken in a language, such as Ruby, where -@code{<>} is a syntactically valid construct. If @code{<>} is not -syntactically valid in languages that you use, then please consider setting -the default value. - -Note: if noweb tangling is slow in large Org-mode files consider setting the -@code{*org-babel-use-quick-and-dirty-noweb-expansion*} variable to true. -This will result in faster noweb reference resolution at the expense of not -correctly resolving inherited values of the @code{:noweb-ref} header -argument. - -@node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code -@section Key bindings and useful functions -@cindex code block, key bindings - -Many common Org mode key sequences are re-bound depending on -the context. - -Within a code block, the following key bindings -are active: - -@multitable @columnfractions 0.25 0.75 -@kindex C-c C-c -@item @kbd{C-c C-c} @tab @code{org-babel-execute-src-block} -@kindex C-c C-o -@item @kbd{C-c C-o} @tab @code{org-babel-open-src-block-result} -@kindex C-up -@item @kbd{C-@key{up}} @tab @code{org-babel-load-in-session} -@kindex M-down -@item @kbd{M-@key{down}} @tab @code{org-babel-pop-to-session} -@end multitable - -In an Org mode buffer, the following key bindings are active: - -@multitable @columnfractions 0.45 0.55 -@kindex C-c C-v p -@kindex C-c C-v C-p -@item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-previous-src-block} -@kindex C-c C-v n -@kindex C-c C-v C-n -@item @kbd{C-c C-v n} @ @ @r{or} @ @ @kbd{C-c C-v C-n} @tab @code{org-babel-next-src-block} -@kindex C-c C-v e -@kindex C-c C-v C-e -@item @kbd{C-c C-v e} @ @ @r{or} @ @ @kbd{C-c C-v C-e} @tab @code{org-babel-execute-maybe} -@kindex C-c C-v o -@kindex C-c C-v C-o -@item @kbd{C-c C-v o} @ @ @r{or} @ @ @kbd{C-c C-v C-o} @tab @code{org-babel-open-src-block-result} -@kindex C-c C-v v -@kindex C-c C-v C-v -@item @kbd{C-c C-v v} @ @ @r{or} @ @ @kbd{C-c C-v C-v} @tab @code{org-babel-expand-src-block} -@kindex C-c C-v u -@kindex C-c C-v C-u -@item @kbd{C-c C-v u} @ @ @r{or} @ @ @kbd{C-c C-v C-u} @tab @code{org-babel-goto-src-block-head} -@kindex C-c C-v g -@kindex C-c C-v C-g -@item @kbd{C-c C-v g} @ @ @r{or} @ @ @kbd{C-c C-v C-g} @tab @code{org-babel-goto-named-src-block} -@kindex C-c C-v r -@kindex C-c C-v C-r -@item @kbd{C-c C-v r} @ @ @r{or} @ @ @kbd{C-c C-v C-r} @tab @code{org-babel-goto-named-result} -@kindex C-c C-v b -@kindex C-c C-v C-b -@item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer} -@kindex C-c C-v s -@kindex C-c C-v C-s -@item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree} -@kindex C-c C-v d -@kindex C-c C-v C-d -@item @kbd{C-c C-v d} @ @ @r{or} @ @ @kbd{C-c C-v C-d} @tab @code{org-babel-demarcate-block} -@kindex C-c C-v t -@kindex C-c C-v C-t -@item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle} -@kindex C-c C-v f -@kindex C-c C-v C-f -@item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file} -@kindex C-c C-v c -@kindex C-c C-v C-c -@item @kbd{C-c C-v c} @ @ @r{or} @ @ @kbd{C-c C-v C-c} @tab @code{org-babel-check-src-block} -@kindex C-c C-v j -@kindex C-c C-v C-j -@item @kbd{C-c C-v j} @ @ @r{or} @ @ @kbd{C-c C-v C-j} @tab @code{org-babel-insert-header-arg} -@kindex C-c C-v l -@kindex C-c C-v C-l -@item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-load-in-session} -@kindex C-c C-v i -@kindex C-c C-v C-i -@item @kbd{C-c C-v i} @ @ @r{or} @ @ @kbd{C-c C-v C-i} @tab @code{org-babel-lob-ingest} -@kindex C-c C-v I -@kindex C-c C-v C-I -@item @kbd{C-c C-v I} @ @ @r{or} @ @ @kbd{C-c C-v C-I} @tab @code{org-babel-view-src-block-info} -@kindex C-c C-v z -@kindex C-c C-v C-z -@item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session-with-code} -@kindex C-c C-v a -@kindex C-c C-v C-a -@item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash} -@kindex C-c C-v h -@kindex C-c C-v C-h -@item @kbd{C-c C-v h} @ @ @r{or} @ @ @kbd{C-c C-v C-h} @tab @code{org-babel-describe-bindings} -@kindex C-c C-v x -@kindex C-c C-v C-x -@item @kbd{C-c C-v x} @ @ @r{or} @ @ @kbd{C-c C-v C-x} @tab @code{org-babel-do-key-sequence-in-edit-buffer} -@end multitable - -@c When possible these keybindings were extended to work when the control key is -@c kept pressed, resulting in the following additional keybindings. - -@c @multitable @columnfractions 0.25 0.75 -@c @item @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash} -@c @item @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer} -@c @item @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file} -@c @item @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest} -@c @item @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block} -@c @item @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree} -@c @item @kbd{C-c C-v C-t} @tab @code{org-babel-tangle} -@c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session} -@c @end multitable - -@node Batch execution, , Key bindings and useful functions, Working With Source Code -@section Batch execution -@cindex code block, batch execution -@cindex source code, batch execution - -It is possible to call functions from the command line. This shell -script calls @code{org-babel-tangle} on every one of its arguments. - -Be sure to adjust the paths to fit your system. - -@example -#!/bin/sh -# -*- mode: shell-script -*- -# -# tangle files with org-mode -# -DIR=`pwd` -FILES="" -ORGINSTALL="~/src/org/lisp/org-install.el" - -# wrap each argument in the code required to call tangle on it -for i in $@@; do - FILES="$FILES \"$i\"" -done - -emacs -Q --batch -l $ORGINSTALL \ ---eval "(progn -(add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\")) -(add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\")) -(require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle) -(mapc (lambda (file) - (find-file (expand-file-name file \"$DIR\")) - (org-babel-tangle) - (kill-buffer)) '($FILES)))" 2>&1 |grep tangled -@end example - -@node Miscellaneous, Hacking, Working With Source Code, Top -@chapter Miscellaneous - -@menu -* Completion:: M-TAB knows what you need -* Easy Templates:: Quick insertion of structural elements -* Speed keys:: Electric commands at the beginning of a headline -* Code evaluation security:: Org mode files evaluate inline code -* Customization:: Adapting Org to your taste -* In-buffer settings:: Overview of the #+KEYWORDS -* The very busy C-c C-c key:: When in doubt, press C-c C-c -* Clean view:: Getting rid of leading stars in the outline -* TTY keys:: Using Org on a tty -* Interaction:: Other Emacs packages -* org-crypt.el:: Encrypting Org files -@end menu - - -@node Completion, Easy Templates, Miscellaneous, Miscellaneous -@section Completion -@cindex completion, of @TeX{} symbols -@cindex completion, of TODO keywords -@cindex completion, of dictionary words -@cindex completion, of option keywords -@cindex completion, of tags -@cindex completion, of property keys -@cindex completion, of link abbreviations -@cindex @TeX{} symbol completion -@cindex TODO keywords completion -@cindex dictionary word completion -@cindex option keyword completion -@cindex tag completion -@cindex link abbreviations, completion of - -Emacs would not be Emacs without completion, and Org mode uses it whenever it -makes sense. If you prefer an @i{iswitchb}- or @i{ido}-like interface for -some of the completion prompts, you can specify your preference by setting at -most one of the variables @code{org-completion-use-iswitchb} -@code{org-completion-use-ido}. - -Org supports in-buffer completion. This type of completion does -not make use of the minibuffer. You simply type a few letters into -the buffer and use the key to complete text right there. - -@table @kbd -@kindex M-@key{TAB} -@item M-@key{TAB} -Complete word at point -@itemize @bullet -@item -At the beginning of a headline, complete TODO keywords. -@item -After @samp{\}, complete @TeX{} symbols supported by the exporter. -@item -After @samp{*}, complete headlines in the current buffer so that they -can be used in search links like @samp{[[*find this headline]]}. -@item -After @samp{:} in a headline, complete tags. The list of tags is taken -from the variable @code{org-tag-alist} (possibly set through the -@samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created -dynamically from all tags used in the current buffer. -@item -After @samp{:} and not in a headline, complete property keys. The list -of keys is constructed dynamically from all keys used in the current -buffer. -@item -After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}). -@item -After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or -@samp{OPTIONS} which set file-specific options for Org mode. When the -option keyword is already complete, pressing @kbd{M-@key{TAB}} again -will insert example settings for this keyword. -@item -In the line after @samp{#+STARTUP: }, complete startup keywords, -i.e.@: valid keys for this line. -@item -Elsewhere, complete dictionary words using Ispell. -@end itemize -@end table - -@node Easy Templates, Speed keys, Completion, Miscellaneous -@section Easy Templates -@cindex template insertion -@cindex insertion, of templates - -Org mode supports insertion of empty structural elements (like -@code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key -strokes. This is achieved through a native template expansion mechanism. -Note that Emacs has several other template mechanisms which could be used in -a similar way, for example @file{yasnippet}. - -To insert a structural element, type a @samp{<}, followed by a template -selector and @kbd{@key{TAB}}. Completion takes effect only when the above -keystrokes are typed on a line by itself. - -The following template selectors are currently supported. - -@multitable @columnfractions 0.1 0.9 -@item @kbd{s} @tab @code{#+begin_src ... #+end_src} -@item @kbd{e} @tab @code{#+begin_example ... #+end_example} -@item @kbd{q} @tab @code{#+begin_quote ... #+end_quote} -@item @kbd{v} @tab @code{#+begin_verse ... #+end_verse} -@item @kbd{c} @tab @code{#+begin_center ... #+end_center} -@item @kbd{l} @tab @code{#+begin_latex ... #+end_latex} -@item @kbd{L} @tab @code{#+latex:} -@item @kbd{h} @tab @code{#+begin_html ... #+end_html} -@item @kbd{H} @tab @code{#+html:} -@item @kbd{a} @tab @code{#+begin_ascii ... #+end_ascii} -@item @kbd{A} @tab @code{#+ascii:} -@item @kbd{i} @tab @code{#+index:} line -@item @kbd{I} @tab @code{#+include:} line -@end multitable - -For example, on an empty line, typing "Customization} menu. Many -settings can also be activated on a per-file basis, by putting special -lines into the buffer (@pxref{In-buffer settings}). - -@node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous -@section Summary of in-buffer settings -@cindex in-buffer settings -@cindex special keywords - -Org mode uses special lines in the buffer to define settings on a -per-file basis. These lines start with a @samp{#+} followed by a -keyword, a colon, and then individual words defining a setting. Several -setting words can be in the same line, but you can also have multiple -lines for the keyword. While these settings are described throughout -the manual, here is a summary. After changing any of those lines in the -buffer, press @kbd{C-c C-c} with the cursor still in the line to -activate the changes immediately. Otherwise they become effective only -when the file is visited again in a new Emacs session. - -@vindex org-archive-location -@table @kbd -@item #+ARCHIVE: %s_done:: -This line sets the archive location for the agenda file. It applies for -all subsequent lines until the next @samp{#+ARCHIVE} line, or the end -of the file. The first such line also applies to any entries before it. -The corresponding variable is @code{org-archive-location}. -@item #+CATEGORY: -This line sets the category for the agenda file. The category applies -for all subsequent lines until the next @samp{#+CATEGORY} line, or the -end of the file. The first such line also applies to any entries before it. -@item #+COLUMNS: %25ITEM ..... -@cindex property, COLUMNS -Set the default format for columns view. This format applies when -columns view is invoked in locations where no @code{COLUMNS} property -applies. -@item #+CONSTANTS: name1=value1 ... -@vindex org-table-formula-constants -@vindex org-table-formula -Set file-local values for constants to be used in table formulas. This -line sets the local variable @code{org-table-formula-constants-local}. -The global version of this variable is -@code{org-table-formula-constants}. -@item #+FILETAGS: :tag1:tag2:tag3: -Set tags that can be inherited by any entry in the file, including the -top-level entries. -@item #+DRAWERS: NAME1 ..... -@vindex org-drawers -Set the file-local set of drawers. The corresponding global variable is -@code{org-drawers}. -@item #+LINK: linkword replace -@vindex org-link-abbrev-alist -These lines (several are allowed) specify link abbreviations. -@xref{Link abbreviations}. The corresponding variable is -@code{org-link-abbrev-alist}. -@item #+PRIORITIES: highest lowest default -@vindex org-highest-priority -@vindex org-lowest-priority -@vindex org-default-priority -This line sets the limits and the default for the priorities. All three -must be either letters A-Z or numbers 0-9. The highest priority must -have a lower ASCII number than the lowest priority. -@item #+PROPERTY: Property_Name Value -This line sets a default inheritance value for entries in the current -buffer, most useful for specifying the allowed values of a property. -@cindex #+SETUPFILE -@item #+SETUPFILE: file -This line defines a file that holds more in-buffer setup. Normally this is -entirely ignored. Only when the buffer is parsed for option-setting lines -(i.e.@: when starting Org mode for a file, when pressing @kbd{C-c C-c} in a -settings line, or when exporting), then the contents of this file are parsed -as if they had been included in the buffer. In particular, the file can be -any other Org mode file with internal setup. You can visit the file the -cursor is in the line with @kbd{C-c '}. -@item #+STARTUP: -@cindex #+STARTUP: -This line sets options to be used at startup of Org mode, when an -Org file is being visited. - -The first set of options deals with the initial visibility of the outline -tree. The corresponding variable for global default settings is -@code{org-startup-folded}, with a default value @code{t}, which means -@code{overview}. -@vindex org-startup-folded -@cindex @code{overview}, STARTUP keyword -@cindex @code{content}, STARTUP keyword -@cindex @code{showall}, STARTUP keyword -@cindex @code{showeverything}, STARTUP keyword -@example -overview @r{top-level headlines only} -content @r{all headlines} -showall @r{no folding of any entries} -showeverything @r{show even drawer contents} -@end example - -@vindex org-startup-indented -@cindex @code{indent}, STARTUP keyword -@cindex @code{noindent}, STARTUP keyword -Dynamic virtual indentation is controlled by the variable -@code{org-startup-indented}@footnote{Emacs 23 and Org mode 6.29 are required} -@example -indent @r{start with @code{org-indent-mode} turned on} -noindent @r{start with @code{org-indent-mode} turned off} -@end example - -@vindex org-startup-align-all-tables -Then there are options for aligning tables upon visiting a file. This -is useful in files containing narrowed table columns. The corresponding -variable is @code{org-startup-align-all-tables}, with a default value -@code{nil}. -@cindex @code{align}, STARTUP keyword -@cindex @code{noalign}, STARTUP keyword -@example -align @r{align all tables} -noalign @r{don't align tables on startup} -@end example - -@vindex org-startup-with-inline-images -When visiting a file, inline images can be automatically displayed. The -corresponding variable is @code{org-startup-with-inline-images}, with a -default value @code{nil} to avoid delays when visiting a file. -@cindex @code{inlineimages}, STARTUP keyword -@cindex @code{noinlineimages}, STARTUP keyword -@example -inlineimages @r{show inline images} -noinlineimages @r{don't show inline images on startup} -@end example - -@vindex org-log-done -@vindex org-log-note-clock-out -@vindex org-log-repeat -Logging the closing and reopening of TODO items and clock intervals can be -configured using these options (see variables @code{org-log-done}, -@code{org-log-note-clock-out} and @code{org-log-repeat}) -@cindex @code{logdone}, STARTUP keyword -@cindex @code{lognotedone}, STARTUP keyword -@cindex @code{nologdone}, STARTUP keyword -@cindex @code{lognoteclock-out}, STARTUP keyword -@cindex @code{nolognoteclock-out}, STARTUP keyword -@cindex @code{logrepeat}, STARTUP keyword -@cindex @code{lognoterepeat}, STARTUP keyword -@cindex @code{nologrepeat}, STARTUP keyword -@cindex @code{logreschedule}, STARTUP keyword -@cindex @code{lognotereschedule}, STARTUP keyword -@cindex @code{nologreschedule}, STARTUP keyword -@cindex @code{logredeadline}, STARTUP keyword -@cindex @code{lognoteredeadline}, STARTUP keyword -@cindex @code{nologredeadline}, STARTUP keyword -@cindex @code{logrefile}, STARTUP keyword -@cindex @code{lognoterefile}, STARTUP keyword -@cindex @code{nologrefile}, STARTUP keyword -@example -logdone @r{record a timestamp when an item is marked DONE} -lognotedone @r{record timestamp and a note when DONE} -nologdone @r{don't record when items are marked DONE} -logrepeat @r{record a time when reinstating a repeating item} -lognoterepeat @r{record a note when reinstating a repeating item} -nologrepeat @r{do not record when reinstating repeating item} -lognoteclock-out @r{record a note when clocking out} -nolognoteclock-out @r{don't record a note when clocking out} -logreschedule @r{record a timestamp when scheduling time changes} -lognotereschedule @r{record a note when scheduling time changes} -nologreschedule @r{do not record when a scheduling date changes} -logredeadline @r{record a timestamp when deadline changes} -lognoteredeadline @r{record a note when deadline changes} -nologredeadline @r{do not record when a deadline date changes} -logrefile @r{record a timestamp when refiling} -lognoterefile @r{record a note when refiling} -nologrefile @r{do not record when refiling} -@end example -@vindex org-hide-leading-stars -@vindex org-odd-levels-only -Here are the options for hiding leading stars in outline headings, and for -indenting outlines. The corresponding variables are -@code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with a -default setting @code{nil} (meaning @code{showstars} and @code{oddeven}). -@cindex @code{hidestars}, STARTUP keyword -@cindex @code{showstars}, STARTUP keyword -@cindex @code{odd}, STARTUP keyword -@cindex @code{even}, STARTUP keyword -@example -hidestars @r{make all but one of the stars starting a headline invisible.} -showstars @r{show all stars starting a headline} -indent @r{virtual indentation according to outline level} -noindent @r{no virtual indentation according to outline level} -odd @r{allow only odd outline levels (1,3,...)} -oddeven @r{allow all outline levels} -@end example -@vindex org-put-time-stamp-overlays -@vindex org-time-stamp-overlay-formats -To turn on custom format overlays over timestamps (variables -@code{org-put-time-stamp-overlays} and -@code{org-time-stamp-overlay-formats}), use -@cindex @code{customtime}, STARTUP keyword -@example -customtime @r{overlay custom time format} -@end example -@vindex constants-unit-system -The following options influence the table spreadsheet (variable -@code{constants-unit-system}). -@cindex @code{constcgs}, STARTUP keyword -@cindex @code{constSI}, STARTUP keyword -@example -constcgs @r{@file{constants.el} should use the c-g-s unit system} -constSI @r{@file{constants.el} should use the SI unit system} -@end example -@vindex org-footnote-define-inline -@vindex org-footnote-auto-label -@vindex org-footnote-auto-adjust -To influence footnote settings, use the following keywords. The -corresponding variables are @code{org-footnote-define-inline}, -@code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}. -@cindex @code{fninline}, STARTUP keyword -@cindex @code{nofninline}, STARTUP keyword -@cindex @code{fnlocal}, STARTUP keyword -@cindex @code{fnprompt}, STARTUP keyword -@cindex @code{fnauto}, STARTUP keyword -@cindex @code{fnconfirm}, STARTUP keyword -@cindex @code{fnplain}, STARTUP keyword -@cindex @code{fnadjust}, STARTUP keyword -@cindex @code{nofnadjust}, STARTUP keyword -@example -fninline @r{define footnotes inline} -fnnoinline @r{define footnotes in separate section} -fnlocal @r{define footnotes near first reference, but not inline} -fnprompt @r{prompt for footnote labels} -fnauto @r{create @code{[fn:1]}-like labels automatically (default)} -fnconfirm @r{offer automatic label for editing or confirmation} -fnplain @r{create @code{[1]}-like labels automatically} -fnadjust @r{automatically renumber and sort footnotes} -nofnadjust @r{do not renumber and sort automatically} -@end example -@cindex org-hide-block-startup -To hide blocks on startup, use these keywords. The corresponding variable is -@code{org-hide-block-startup}. -@cindex @code{hideblocks}, STARTUP keyword -@cindex @code{nohideblocks}, STARTUP keyword -@example -hideblocks @r{Hide all begin/end blocks on startup} -nohideblocks @r{Do not hide blocks on startup} -@end example -@cindex org-pretty-entities -The display of entities as UTF-8 characters is governed by the variable -@code{org-pretty-entities} and the keywords -@cindex @code{entitiespretty}, STARTUP keyword -@cindex @code{entitiesplain}, STARTUP keyword -@example -entitiespretty @r{Show entities as UTF-8 characters where possible} -entitiesplain @r{Leave entities plain} -@end example -@item #+TAGS: TAG1(c1) TAG2(c2) -@vindex org-tag-alist -These lines (several such lines are allowed) specify the valid tags in -this file, and (potentially) the corresponding @emph{fast tag selection} -keys. The corresponding variable is @code{org-tag-alist}. -@item #+TBLFM: -This line contains the formulas for the table directly above the line. -@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+DATE:, -@itemx #+OPTIONS:, #+BIND:, #+XSLT:, -@itemx #+DESCRIPTION:, #+KEYWORDS:, -@itemx #+LATEX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:, -@itemx #+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS: -These lines provide settings for exporting files. For more details see -@ref{Export options}. -@item #+TODO: #+SEQ_TODO: #+TYP_TODO: -@vindex org-todo-keywords -These lines set the TODO keywords and their interpretation in the -current file. The corresponding variable is @code{org-todo-keywords}. -@end table - -@node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous -@section The very busy C-c C-c key -@kindex C-c C-c -@cindex C-c C-c, overview - -The key @kbd{C-c C-c} has many purposes in Org, which are all -mentioned scattered throughout this manual. One specific function of -this key is to add @emph{tags} to a headline (@pxref{Tags}). In many -other circumstances it means something like @emph{``Hey Org, look -here and update according to what you see here''}. Here is a summary of -what this means in different contexts. - -@itemize @minus -@item -If there are highlights in the buffer from the creation of a sparse -tree, or from clock display, remove these highlights. -@item -If the cursor is in one of the special @code{#+KEYWORD} lines, this -triggers scanning the buffer for these lines and updating the -information. -@item -If the cursor is inside a table, realign the table. This command -works even if the automatic table editor has been turned off. -@item -If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to -the entire table. -@item -If the current buffer is a capture buffer, close the note and file it. -With a prefix argument, file it, without further interaction, to the -default location. -@item -If the cursor is on a @code{<<>>}, update radio targets and -corresponding links in this buffer. -@item -If the cursor is in a property line or at the start or end of a property -drawer, offer property commands. -@item -If the cursor is at a footnote reference, go to the corresponding -definition, and vice versa. -@item -If the cursor is on a statistics cookie, update it. -@item -If the cursor is in a plain list item with a checkbox, toggle the status -of the checkbox. -@item -If the cursor is on a numbered item in a plain list, renumber the -ordered list. -@item -If the cursor is on the @code{#+BEGIN} line of a dynamic block, the -block is updated. -@item -If the cursor is at a timestamp, fix the day name in the timestamp. -@end itemize - -@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous -@section A cleaner outline view -@cindex hiding leading stars -@cindex dynamic indentation -@cindex odd-levels-only outlines -@cindex clean outline view - -Some people find it noisy and distracting that the Org headlines start with a -potentially large number of stars, and that text below the headlines is not -indented. While this is no problem when writing a @emph{book-like} document -where the outline headings are really section headings, in a more -@emph{list-oriented} outline, indented structure is a lot cleaner: - -@example -@group -* Top level headline | * Top level headline -** Second level | * Second level -*** 3rd level | * 3rd level -some text | some text -*** 3rd level | * 3rd level -more text | more text -* Another top level headline | * Another top level headline -@end group -@end example - -@noindent - -If you are using at least Emacs 23.2@footnote{Emacs 23.1 can actually crash -with @code{org-indent-mode}} and version 6.29 of Org, this kind of view can -be achieved dynamically at display time using @code{org-indent-mode}. In -this minor mode, all lines are prefixed for display with the necessary amount -of space@footnote{@code{org-indent-mode} also sets the @code{wrap-prefix} -property, such that @code{visual-line-mode} (or purely setting -@code{word-wrap}) wraps long lines (including headlines) correctly indented. -}. Also headlines are prefixed with additional stars, so that the amount of -indentation shifts by two@footnote{See the variable -@code{org-indent-indentation-per-level}.} spaces per level. All headline -stars but the last one are made invisible using the @code{org-hide} -face@footnote{Turning on @code{org-indent-mode} sets -@code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to -@code{nil}.} - see below under @samp{2.} for more information on how this -works. You can turn on @code{org-indent-mode} for all files by customizing -the variable @code{org-startup-indented}, or you can turn it on for -individual files using - -@example -#+STARTUP: indent -@end example - -If you want a similar effect in an earlier version of Emacs and/or Org, or if -you want the indentation to be hard space characters so that the plain text -file looks as similar as possible to the Emacs display, Org supports you in -the following way: - -@enumerate -@item -@emph{Indentation of text below headlines}@* -You may indent text below each headline to make the left boundary line up -with the headline, like - -@example -*** 3rd level - more text, now indented -@end example - -@vindex org-adapt-indentation -Org supports this with paragraph filling, line wrapping, and structure -editing@footnote{See also the variable @code{org-adapt-indentation}.}, -preserving or adapting the indentation as appropriate. - -@item -@vindex org-hide-leading-stars -@emph{Hiding leading stars}@* You can modify the display in such a way that -all leading stars become invisible. To do this in a global way, configure -the variable @code{org-hide-leading-stars} or change this on a per-file basis -with - -@example -#+STARTUP: hidestars -#+STARTUP: showstars -@end example - -With hidden stars, the tree becomes: - -@example -@group -* Top level headline - * Second level - * 3rd level - ... -@end group -@end example - -@noindent -@vindex org-hide @r{(face)} -The leading stars are not truly replaced by whitespace, they are only -fontified with the face @code{org-hide} that uses the background color as -font color. If you are not using either white or black background, you may -have to customize this face to get the wanted effect. Another possibility is -to set this font such that the extra stars are @i{almost} invisible, for -example using the color @code{grey90} on a white background. - -@item -@vindex org-odd-levels-only -Things become cleaner still if you skip all the even levels and use only odd -levels 1, 3, 5..., effectively adding two stars to go from one outline level -to the next@footnote{When you need to specify a level for a property search -or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc@.}. In this -way we get the outline view shown at the beginning of this section. In order -to make the structure editing and export commands handle this convention -correctly, configure the variable @code{org-odd-levels-only}, or set this on -a per-file basis with one of the following lines: - -@example -#+STARTUP: odd -#+STARTUP: oddeven -@end example - -You can convert an Org file from single-star-per-level to the -double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels -RET} in that file. The reverse operation is @kbd{M-x -org-convert-to-oddeven-levels}. -@end enumerate - -@node TTY keys, Interaction, Clean view, Miscellaneous -@section Using Org on a tty -@cindex tty key bindings - -Because Org contains a large number of commands, by default many of -Org's core commands are bound to keys that are generally not -accessible on a tty, such as the cursor keys (@key{left}, @key{right}, -@key{up}, @key{down}), @key{TAB} and @key{RET}, in particular when used -together with modifiers like @key{Meta} and/or @key{Shift}. To access -these commands on a tty when special keys are unavailable, the following -alternative bindings can be used. The tty bindings below will likely be -more cumbersome; you may find for some of the bindings below that a -customized workaround suits you better. For example, changing a timestamp -is really only fun with @kbd{S-@key{cursor}} keys, whereas on a -tty you would rather use @kbd{C-c .} to re-insert the timestamp. - -@multitable @columnfractions 0.15 0.2 0.1 0.2 -@item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2} -@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab -@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}} -@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab -@item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}} -@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab -@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}} -@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab -@item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}} -@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab -@item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab -@item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}} -@item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab -@item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab @kbd{ } @tab -@item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab @kbd{ } @tab -@item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab @kbd{ } @tab -@item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab @kbd{ } @tab -@item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab @kbd{ } @tab -@item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab -@end multitable - - -@node Interaction, org-crypt.el, TTY keys, Miscellaneous -@section Interaction with other packages -@cindex packages, interaction with other -Org lives in the world of GNU Emacs and interacts in various ways -with other code out there. - -@menu -* Cooperation:: Packages Org cooperates with -* Conflicts:: Packages that lead to conflicts -@end menu - -@node Cooperation, Conflicts, Interaction, Interaction -@subsection Packages that Org cooperates with - -@table @asis -@cindex @file{calc.el} -@cindex Gillespie, Dave -@item @file{calc.el} by Dave Gillespie -Org uses the Calc package for implementing spreadsheet -functionality in its tables (@pxref{The spreadsheet}). Org -checks for the availability of Calc by looking for the function -@code{calc-eval} which will have been autoloaded during setup if Calc has -been installed properly. As of Emacs 22, Calc is part of the Emacs -distribution. Another possibility for interaction between the two -packages is using Calc for embedded calculations. @xref{Embedded Mode, -, Embedded Mode, calc, GNU Emacs Calc Manual}. -@item @file{constants.el} by Carsten Dominik -@cindex @file{constants.el} -@cindex Dominik, Carsten -@vindex org-table-formula-constants -In a table formula (@pxref{The spreadsheet}), it is possible to use -names for natural constants or units. Instead of defining your own -constants in the variable @code{org-table-formula-constants}, install -the @file{constants} package which defines a large number of constants -and units, and lets you use unit prefixes like @samp{M} for -@samp{Mega}, etc@. You will need version 2.0 of this package, available -at @url{http://www.astro.uva.nl/~dominik/Tools}. Org checks for -the function @code{constants-get}, which has to be autoloaded in your -setup. See the installation instructions in the file -@file{constants.el}. -@item @file{cdlatex.el} by Carsten Dominik -@cindex @file{cdlatex.el} -@cindex Dominik, Carsten -Org mode can make use of the CD@LaTeX{} package to efficiently enter -@LaTeX{} fragments into Org files. See @ref{CDLaTeX mode}. -@item @file{imenu.el} by Ake Stenhoff and Lars Lindberg -@cindex @file{imenu.el} -Imenu allows menu access to an index of items in a file. Org mode -supports Imenu---all you need to do to get the index is the following: -@lisp -(add-hook 'org-mode-hook - (lambda () (imenu-add-to-menubar "Imenu"))) -@end lisp -@vindex org-imenu-depth -By default the index is two levels deep---you can modify the depth using -the option @code{org-imenu-depth}. -@item @file{remember.el} by John Wiegley -@cindex @file{remember.el} -@cindex Wiegley, John -Org used to use this package for capture, but no longer does. -@item @file{speedbar.el} by Eric M. Ludlam -@cindex @file{speedbar.el} -@cindex Ludlam, Eric M. -Speedbar is a package that creates a special frame displaying files and -index items in files. Org mode supports Speedbar and allows you to -drill into Org files directly from the Speedbar. It also allows you to -restrict the scope of agenda commands to a file or a subtree by using -the command @kbd{<} in the Speedbar frame. -@cindex @file{table.el} -@item @file{table.el} by Takaaki Ota -@kindex C-c C-c -@cindex table editor, @file{table.el} -@cindex @file{table.el} -@cindex Ota, Takaaki - -Complex ASCII tables with automatic line wrapping, column- and row-spanning, -and alignment can be created using the Emacs table package by Takaaki Ota -(@uref{http://sourceforge.net/projects/table}, and also part of Emacs 22). -Org mode will recognize these tables and export them properly. Because of -interference with other Org mode functionality, you unfortunately cannot edit -these tables directly in the buffer. Instead, you need to use the command -@kbd{C-c '} to edit them, similar to source code snippets. - -@table @kbd -@orgcmd{C-c ',org-edit-special} -Edit a @file{table.el} table. Works when the cursor is in a table.el table. -@c -@orgcmd{C-c ~,org-table-create-with-table.el} -Insert a @file{table.el} table. If there is already a table at point, this -command converts it between the @file{table.el} format and the Org mode -format. See the documentation string of the command -@code{org-convert-table} for the restrictions under which this is -possible. -@end table -@file{table.el} is part of Emacs since Emacs 22. -@item @file{footnote.el} by Steven L. Baur -@cindex @file{footnote.el} -@cindex Baur, Steven L. -Org mode recognizes numerical footnotes as provided by this package. -However, Org mode also has its own footnote support (@pxref{Footnotes}), -which makes using @file{footnote.el} unnecessary. -@end table - -@node Conflicts, , Cooperation, Interaction -@subsection Packages that lead to conflicts with Org mode - -@table @asis - -@cindex @code{shift-selection-mode} -@vindex org-support-shift-select -In Emacs 23, @code{shift-selection-mode} is on by default, meaning that -cursor motions combined with the shift key should start or enlarge regions. -This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change -timestamps, TODO keywords, priorities, and item bullet types if the cursor is -at such a location. By default, @kbd{S-@key{cursor}} commands outside -special contexts don't do anything, but you can customize the variable -@code{org-support-shift-select}. Org mode then tries to accommodate shift -selection by (i) using it outside of the special contexts where special -commands apply, and by (ii) extending an existing active region even if the -cursor moves across a special context. - -@item @file{CUA.el} by Kim. F. Storm -@cindex @file{CUA.el} -@cindex Storm, Kim. F. -@vindex org-replace-disputed-keys -Key bindings in Org conflict with the @kbd{S-} keys used by CUA mode -(as well as @code{pc-select-mode} and @code{s-region-mode}) to select and extend the -region. In fact, Emacs 23 has this built-in in the form of -@code{shift-selection-mode}, see previous paragraph. If you are using Emacs -23, you probably don't want to use another package for this purpose. However, -if you prefer to leave these keys to a different package while working in -Org mode, configure the variable @code{org-replace-disputed-keys}. When set, -Org will move the following key bindings in Org files, and in the agenda -buffer (but not during date selection). - -@example -S-UP @result{} M-p S-DOWN @result{} M-n -S-LEFT @result{} M-- S-RIGHT @result{} M-+ -C-S-LEFT @result{} M-S-- C-S-RIGHT @result{} M-S-+ -@end example - -@vindex org-disputed-keys -Yes, these are unfortunately more difficult to remember. If you want -to have other replacement keys, look at the variable -@code{org-disputed-keys}. - -@item @file{yasnippet.el} -@cindex @file{yasnippet.el} -The way Org mode binds the TAB key (binding to @code{[tab]} instead of -@code{"\t"}) overrules YASnippet's access to this key. The following code -fixed this problem: - -@lisp -(add-hook 'org-mode-hook - (lambda () - (org-set-local 'yas/trigger-key [tab]) - (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand))) -@end lisp - -The latest version of yasnippet doesn't play well with Org mode. If the -above code does not fix the conflict, start by defining the following -function: - -@lisp -(defun yas/org-very-safe-expand () - (let ((yas/fallback-behavior 'return-nil)) (yas/expand))) -@end lisp - -Then, tell Org mode what to do with the new function: - -@lisp -(add-hook 'org-mode-hook - (lambda () - (make-variable-buffer-local 'yas/trigger-key) - (setq yas/trigger-key [tab]) - (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand) - (define-key yas/keymap [tab] 'yas/next-field))) -@end lisp - -@item @file{windmove.el} by Hovav Shacham -@cindex @file{windmove.el} -This package also uses the @kbd{S-} keys, so everything written -in the paragraph above about CUA mode also applies here. If you want make -the windmove function active in locations where Org mode does not have -special functionality on @kbd{S-@key{cursor}}, add this to your -configuration: - -@lisp -;; Make windmove work in org-mode: -(add-hook 'org-shiftup-final-hook 'windmove-up) -(add-hook 'org-shiftleft-final-hook 'windmove-left) -(add-hook 'org-shiftdown-final-hook 'windmove-down) -(add-hook 'org-shiftright-final-hook 'windmove-right) -@end lisp - -@item @file{viper.el} by Michael Kifer -@cindex @file{viper.el} -@kindex C-c / -Viper uses @kbd{C-c /} and therefore makes this key not access the -corresponding Org mode command @code{org-sparse-tree}. You need to find -another key for this command, or override the key in -@code{viper-vi-global-user-map} with - -@lisp -(define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree) -@end lisp - -@end table - -@node org-crypt.el, , Interaction, Miscellaneous -@section org-crypt.el -@cindex @file{org-crypt.el} -@cindex @code{org-decrypt-entry} - -Org-crypt will encrypt the text of an entry, but not the headline, or -properties. Org-crypt uses the Emacs EasyPG library to encrypt and decrypt -files. - -Any text below a headline that has a @samp{:crypt:} tag will be automatically -be encrypted when the file is saved. If you want to use a different tag just -customize the @code{org-crypt-tag-matcher} setting. - -To use org-crypt it is suggested that you have the following in your -@file{.emacs}: - -@example -(require 'org-crypt) -(org-crypt-use-before-save-magic) -(setq org-tags-exclude-from-inheritance (quote ("crypt"))) - -(setq org-crypt-key nil) - ;; GPG key to use for encryption - ;; Either the Key ID or set to nil to use symmetric encryption. - -(setq auto-save-default nil) - ;; Auto-saving does not cooperate with org-crypt.el: so you need - ;; to turn it off if you plan to use org-crypt.el quite often. - ;; Otherwise, you'll get an (annoying) message each time you - ;; start Org. - - ;; To turn it off only locally, you can insert this: - ;; - ;; # -*- buffer-auto-save-file-name: nil; -*- -@end example - -Excluding the crypt tag from inheritance prevents already encrypted text -being encrypted again. - -@node Hacking, MobileOrg, Miscellaneous, Top -@appendix Hacking -@cindex hacking - -This appendix covers some aspects where users can extend the functionality of -Org. - -@menu -* Hooks:: Who to reach into Org's internals -* Add-on packages:: Available extensions -* Adding hyperlink types:: New custom link types -* Context-sensitive commands:: How to add functionality to such commands -* Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs -* Dynamic blocks:: Automatically filled blocks -* Special agenda views:: Customized views -* Extracting agenda information:: Postprocessing of agenda information -* Using the property API:: Writing programs that use entry properties -* Using the mapping API:: Mapping over all or selected entries -@end menu - -@node Hooks, Add-on packages, Hacking, Hacking -@section Hooks -@cindex hooks - -Org has a large number of hook variables that can be used to add -functionality. This appendix about hacking is going to illustrate the -use of some of them. A complete list of all hooks with documentation is -maintained by the Worg project and can be found at -@uref{http://orgmode.org/worg/org-configs/org-hooks.php}. - -@node Add-on packages, Adding hyperlink types, Hooks, Hacking -@section Add-on packages -@cindex add-on packages - -A large number of add-on packages have been written by various authors. -These packages are not part of Emacs, but they are distributed as contributed -packages with the separate release available at the Org mode home page at -@uref{http://orgmode.org}. The list of contributed packages, along with -documentation about each package, is maintained by the Worg project at -@uref{http://orgmode.org/worg/org-contrib/}. - - - -@node Adding hyperlink types, Context-sensitive commands, Add-on packages, Hacking -@section Adding hyperlink types -@cindex hyperlinks, adding new types - -Org has a large number of hyperlink types built-in -(@pxref{Hyperlinks}). If you would like to add new link types, Org -provides an interface for doing so. Let's look at an example file, -@file{org-man.el}, that will add support for creating links like -@samp{[[man:printf][The printf manpage]]} to show Unix manual pages inside -Emacs: - -@lisp -;;; org-man.el - Support for links to manpages in Org - -(require 'org) - -(org-add-link-type "man" 'org-man-open) -(add-hook 'org-store-link-functions 'org-man-store-link) - -(defcustom org-man-command 'man - "The Emacs command to be used to display a man page." - :group 'org-link - :type '(choice (const man) (const woman))) - -(defun org-man-open (path) - "Visit the manpage on PATH. -PATH should be a topic that can be thrown at the man command." - (funcall org-man-command path)) - -(defun org-man-store-link () - "Store a link to a manpage." - (when (memq major-mode '(Man-mode woman-mode)) - ;; This is a man page, we do make this link - (let* ((page (org-man-get-page-name)) - (link (concat "man:" page)) - (description (format "Manpage for %s" page))) - (org-store-link-props - :type "man" - :link link - :description description)))) - -(defun org-man-get-page-name () - "Extract the page name from the buffer name." - ;; This works for both `Man-mode' and `woman-mode'. - (if (string-match " \\(\\S-+\\)\\*" (buffer-name)) - (match-string 1 (buffer-name)) - (error "Cannot create link to this man page"))) - -(provide 'org-man) - -;;; org-man.el ends here -@end lisp - -@noindent -You would activate this new link type in @file{.emacs} with - -@lisp -(require 'org-man) -@end lisp - -@noindent -Let's go through the file and see what it does. -@enumerate -@item -It does @code{(require 'org)} to make sure that @file{org.el} has been -loaded. -@item -The next line calls @code{org-add-link-type} to define a new link type -with prefix @samp{man}. The call also contains the name of a function -that will be called to follow such a link. -@item -@vindex org-store-link-functions -The next line adds a function to @code{org-store-link-functions}, in -order to allow the command @kbd{C-c l} to record a useful link in a -buffer displaying a man page. -@end enumerate - -The rest of the file defines the necessary variables and functions. -First there is a customization variable that determines which Emacs -command should be used to display man pages. There are two options, -@code{man} and @code{woman}. Then the function to follow a link is -defined. It gets the link path as an argument---in this case the link -path is just a topic for the manual command. The function calls the -value of @code{org-man-command} to display the man page. - -Finally the function @code{org-man-store-link} is defined. When you try -to store a link with @kbd{C-c l}, this function will be called to -try to make a link. The function must first decide if it is supposed to -create the link for this buffer type; we do this by checking the value -of the variable @code{major-mode}. If not, the function must exit and -return the value @code{nil}. If yes, the link is created by getting the -manual topic from the buffer name and prefixing it with the string -@samp{man:}. Then it must call the command @code{org-store-link-props} -and set the @code{:type} and @code{:link} properties. Optionally you -can also set the @code{:description} property to provide a default for -the link description when the link is later inserted into an Org -buffer with @kbd{C-c C-l}. - -When it makes sense for your new link type, you may also define a function -@code{org-PREFIX-complete-link} that implements special (e.g.@: completion) -support for inserting such a link with @kbd{C-c C-l}. Such a function should -not accept any arguments, and return the full link with prefix. - -@node Context-sensitive commands, Tables in arbitrary syntax, Adding hyperlink types, Hacking -@section Context-sensitive commands -@cindex context-sensitive commands, hooks -@cindex add-ons, context-sensitive commands -@vindex org-ctrl-c-ctrl-c-hook - -Org has several commands that act differently depending on context. The most -important example is the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}). -Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property. - -Add-ons can tap into this functionality by providing a function that detects -special context for that add-on and executes functionality appropriate for -the context. Here is an example from Dan Davison's @file{org-R.el} which -allows you to evaluate commands based on the @file{R} programming language -@footnote{@file{org-R.el} has been replaced by the Org mode functionality -described in @ref{Working With Source Code} and is now obsolete.}. For this -package, special contexts are lines that start with @code{#+R:} or -@code{#+RR:}. - -@lisp -(defun org-R-apply-maybe () - "Detect if this is context for org-R and execute R commands." - (if (save-excursion - (beginning-of-line 1) - (looking-at "#\\+RR?:")) - (progn (call-interactively 'org-R-apply) - t) ;; to signal that we took action - nil)) ;; to signal that we did not - -(add-hook 'org-ctrl-c-ctrl-c-hook 'org-R-apply-maybe) -@end lisp - -The function first checks if the cursor is in such a line. If that is the -case, @code{org-R-apply} is called and the function returns @code{t} to -signal that action was taken, and @kbd{C-c C-c} will stop looking for other -contexts. If the function finds it should do nothing locally, it returns -@code{nil} so that other, similar functions can have a try. - - -@node Tables in arbitrary syntax, Dynamic blocks, Context-sensitive commands, Hacking -@section Tables and lists in arbitrary syntax -@cindex tables, in other modes -@cindex lists, in other modes -@cindex Orgtbl mode - -Since Orgtbl mode can be used as a minor mode in arbitrary buffers, a -frequent feature request has been to make it work with native tables in -specific languages, for example @LaTeX{}. However, this is extremely -hard to do in a general way, would lead to a customization nightmare, -and would take away much of the simplicity of the Orgtbl mode table -editor. - -This appendix describes a different approach. We keep the Orgtbl mode -table in its native format (the @i{source table}), and use a custom -function to @i{translate} the table to the correct syntax, and to -@i{install} it in the right location (the @i{target table}). This puts -the burden of writing conversion functions on the user, but it allows -for a very flexible system. - -Bastien added the ability to do the same with lists, in Orgstruct mode. You -can use Org's facilities to edit and structure lists by turning -@code{orgstruct-mode} on, then locally exporting such lists in another format -(HTML, @LaTeX{} or Texinfo.) - - -@menu -* Radio tables:: Sending and receiving radio tables -* A @LaTeX{} example:: Step by step, almost a tutorial -* Translator functions:: Copy and modify -* Radio lists:: Doing the same for lists -@end menu - -@node Radio tables, A @LaTeX{} example, Tables in arbitrary syntax, Tables in arbitrary syntax -@subsection Radio tables -@cindex radio tables - -To define the location of the target table, you first need to create two -lines that are comments in the current mode, but contain magic words for -Orgtbl mode to find. Orgtbl mode will insert the translated table -between these lines, replacing whatever was there before. For example: - -@example -/* BEGIN RECEIVE ORGTBL table_name */ -/* END RECEIVE ORGTBL table_name */ -@end example - -@noindent -Just above the source table, we put a special line that tells -Orgtbl mode how to translate this table and where to install it. For -example: -@cindex #+ORGTBL -@example -#+ORGTBL: SEND table_name translation_function arguments.... -@end example - -@noindent -@code{table_name} is the reference name for the table that is also used -in the receiver lines. @code{translation_function} is the Lisp function -that does the translation. Furthermore, the line can contain a list of -arguments (alternating key and value) at the end. The arguments will be -passed as a property list to the translation function for -interpretation. A few standard parameters are already recognized and -acted upon before the translation function is called: - -@table @code -@item :skip N -Skip the first N lines of the table. Hlines do count as separate lines for -this parameter! - -@item :skipcols (n1 n2 ...) -List of columns that should be skipped. If the table has a column with -calculation marks, that column is automatically discarded as well. -Please note that the translator function sees the table @emph{after} the -removal of these columns, the function never knows that there have been -additional columns. -@end table - -@noindent -The one problem remaining is how to keep the source table in the buffer -without disturbing the normal workings of the file, for example during -compilation of a C file or processing of a @LaTeX{} file. There are a -number of different solutions: - -@itemize @bullet -@item -The table could be placed in a block comment if that is supported by the -language. For example, in C mode you could wrap the table between -@samp{/*} and @samp{*/} lines. -@item -Sometimes it is possible to put the table after some kind of @i{END} -statement, for example @samp{\bye} in @TeX{} and @samp{\end@{document@}} -in @LaTeX{}. -@item -You can just comment the table line-by-line whenever you want to process -the file, and uncomment it whenever you need to edit the table. This -only sounds tedious---the command @kbd{M-x orgtbl-toggle-comment} -makes this comment-toggling very easy, in particular if you bind it to a -key. -@end itemize - -@node A @LaTeX{} example, Translator functions, Radio tables, Tables in arbitrary syntax -@subsection A @LaTeX{} example of radio tables -@cindex @LaTeX{}, and Orgtbl mode - -The best way to wrap the source table in @LaTeX{} is to use the -@code{comment} environment provided by @file{comment.sty}. It has to be -activated by placing @code{\usepackage@{comment@}} into the document -header. Orgtbl mode can insert a radio table skeleton@footnote{By -default this works only for @LaTeX{}, HTML, and Texinfo. Configure the -variable @code{orgtbl-radio-tables} to install templates for other -modes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You will -be prompted for a table name, let's say we use @samp{salesfigures}. You -will then get the following template: - -@cindex #+ORGTBL, SEND -@example -% BEGIN RECEIVE ORGTBL salesfigures -% END RECEIVE ORGTBL salesfigures -\begin@{comment@} -#+ORGTBL: SEND salesfigures orgtbl-to-latex -| | | -\end@{comment@} -@end example - -@noindent -@vindex @LaTeX{}-verbatim-environments -The @code{#+ORGTBL: SEND} line tells Orgtbl mode to use the function -@code{orgtbl-to-latex} to convert the table into @LaTeX{} and to put it -into the receiver location with name @code{salesfigures}. You may now -fill in the table---feel free to use the spreadsheet features@footnote{If -the @samp{#+TBLFM} line contains an odd number of dollar characters, -this may cause problems with font-lock in @LaTeX{} mode. As shown in the -example you can fix this by adding an extra line inside the -@code{comment} environment that is used to balance the dollar -expressions. If you are using AUC@TeX{} with the font-latex library, a -much better solution is to add the @code{comment} environment to the -variable @code{LaTeX-verbatim-environments}.}: - -@example -% BEGIN RECEIVE ORGTBL salesfigures -% END RECEIVE ORGTBL salesfigures -\begin@{comment@} -#+ORGTBL: SEND salesfigures orgtbl-to-latex -| Month | Days | Nr sold | per day | -|-------+------+---------+---------| -| Jan | 23 | 55 | 2.4 | -| Feb | 21 | 16 | 0.8 | -| March | 22 | 278 | 12.6 | -#+TBLFM: $4=$3/$2;%.1f -% $ (optional extra dollar to keep font-lock happy, see footnote) -\end@{comment@} -@end example - -@noindent -When you are done, press @kbd{C-c C-c} in the table to get the converted -table inserted between the two marker lines. - -Now let's assume you want to make the table header by hand, because you -want to control how columns are aligned, etc@. In this case we make sure -that the table translator skips the first 2 lines of the source -table, and tell the command to work as a @i{splice}, i.e.@: to not produce -header and footer commands of the target table: - -@example -\begin@{tabular@}@{lrrr@} -Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\ -% BEGIN RECEIVE ORGTBL salesfigures -% END RECEIVE ORGTBL salesfigures -\end@{tabular@} -% -\begin@{comment@} -#+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2 -| Month | Days | Nr sold | per day | -|-------+------+---------+---------| -| Jan | 23 | 55 | 2.4 | -| Feb | 21 | 16 | 0.8 | -| March | 22 | 278 | 12.6 | -#+TBLFM: $4=$3/$2;%.1f -\end@{comment@} -@end example - -The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of -Orgtbl mode. It uses a @code{tabular} environment to typeset the table -and marks horizontal lines with @code{\hline}. Furthermore, it -interprets the following parameters (see also @pxref{Translator functions}): - -@table @code -@item :splice nil/t -When set to t, return only table body lines, don't wrap them into a -tabular environment. Default is nil. - -@item :fmt fmt -A format to be used to wrap each field, it should contain @code{%s} for the -original field value. For example, to wrap each field value in dollars, -you could use @code{:fmt "$%s$"}. This may also be a property list with -column numbers and formats, for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}. -A function of one argument can be used in place of the strings; the -function must return a formatted string. - -@item :efmt efmt -Use this format to print numbers with exponentials. The format should -have @code{%s} twice for inserting mantissa and exponent, for example -@code{"%s\\times10^@{%s@}"}. The default is @code{"%s\\,(%s)"}. This -may also be a property list with column numbers and formats, for example -@code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After -@code{efmt} has been applied to a value, @code{fmt} will also be -applied. Similar to @code{fmt}, functions of two arguments can be -supplied instead of strings. -@end table - -@node Translator functions, Radio lists, A @LaTeX{} example, Tables in arbitrary syntax -@subsection Translator functions -@cindex HTML, and Orgtbl mode -@cindex translator function - -Orgtbl mode has several translator functions built-in: @code{orgtbl-to-csv} -(comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values) -@code{orgtbl-to-latex}, @code{orgtbl-to-html}, and @code{orgtbl-to-texinfo}. -Except for @code{orgtbl-to-html}@footnote{The HTML translator uses the same -code that produces tables during HTML export.}, these all use a generic -translator, @code{orgtbl-to-generic}. For example, @code{orgtbl-to-latex} -itself is a very short function that computes the column definitions for the -@code{tabular} environment, defines a few field and line separators and then -hands processing over to the generic translator. Here is the entire code: - -@lisp -@group -(defun orgtbl-to-latex (table params) - "Convert the Orgtbl mode TABLE to LaTeX." - (let* ((alignment (mapconcat (lambda (x) (if x "r" "l")) - org-table-last-alignment "")) - (params2 - (list - :tstart (concat "\\begin@{tabular@}@{" alignment "@}") - :tend "\\end@{tabular@}" - :lstart "" :lend " \\\\" :sep " & " - :efmt "%s\\,(%s)" :hline "\\hline"))) - (orgtbl-to-generic table (org-combine-plists params2 params)))) -@end group -@end lisp - -As you can see, the properties passed into the function (variable -@var{PARAMS}) are combined with the ones newly defined in the function -(variable @var{PARAMS2}). The ones passed into the function (i.e.@: the -ones set by the @samp{ORGTBL SEND} line) take precedence. So if you -would like to use the @LaTeX{} translator, but wanted the line endings to -be @samp{\\[2mm]} instead of the default @samp{\\}, you could just -overrule the default with - -@example -#+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]" -@end example - -For a new language, you can either write your own converter function in -analogy with the @LaTeX{} translator, or you can use the generic function -directly. For example, if you have a language where a table is started -with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are -started with @samp{!BL!}, ended with @samp{!EL!}, and where the field -separator is a TAB, you could call the generic translator like this (on -a single line!): - -@example -#+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!" - :lstart "!BL! " :lend " !EL!" :sep "\t" -@end example - -@noindent -Please check the documentation string of the function -@code{orgtbl-to-generic} for a full list of parameters understood by -that function, and remember that you can pass each of them into -@code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function -using the generic function. - -Of course you can also write a completely new function doing complicated -things the generic translator cannot do. A translator function takes -two arguments. The first argument is the table, a list of lines, each -line either the symbol @code{hline} or a list of fields. The second -argument is the property list containing all parameters specified in the -@samp{#+ORGTBL: SEND} line. The function must return a single string -containing the formatted table. If you write a generally useful -translator, please post it on @email{emacs-orgmode@@gnu.org} so that -others can benefit from your work. - -@node Radio lists, , Translator functions, Tables in arbitrary syntax -@subsection Radio lists -@cindex radio lists -@cindex org-list-insert-radio-list - -Sending and receiving radio lists works exactly the same way as sending and -receiving radio tables (@pxref{Radio tables}). As for radio tables, you can -insert radio list templates in HTML, @LaTeX{} and Texinfo modes by calling -@code{org-list-insert-radio-list}. - -Here are the differences with radio tables: - -@itemize @minus -@item -Orgstruct mode must be active. -@item -Use the @code{ORGLST} keyword instead of @code{ORGTBL}. -@item -The available translation functions for radio lists don't take -parameters. -@item -@kbd{C-c C-c} will work when pressed on the first item of the list. -@end itemize - -Here is a @LaTeX{} example. Let's say that you have this in your -@LaTeX{} file: - -@cindex #+ORGLST -@example -% BEGIN RECEIVE ORGLST to-buy -% END RECEIVE ORGLST to-buy -\begin@{comment@} -#+ORGLST: SEND to-buy org-list-to-latex -- a new house -- a new computer - + a new keyboard - + a new mouse -- a new life -\end@{comment@} -@end example - -Pressing `C-c C-c' on @code{a new house} and will insert the converted -@LaTeX{} list between the two marker lines. - -@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking -@section Dynamic blocks -@cindex dynamic blocks - -Org documents can contain @emph{dynamic blocks}. These are -specially marked regions that are updated by some user-written function. -A good example for such a block is the clock table inserted by the -command @kbd{C-c C-x C-r} (@pxref{Clocking work time}). - -Dynamic blocks are enclosed by a BEGIN-END structure that assigns a name -to the block and can also specify parameters for the function producing -the content of the block. - -@cindex #+BEGIN:dynamic block -@example -#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ... - -#+END: -@end example - -Dynamic blocks are updated with the following commands - -@table @kbd -@orgcmd{C-c C-x C-u,org-dblock-update} -Update dynamic block at point. -@orgkey{C-u C-c C-x C-u} -Update all dynamic blocks in the current file. -@end table - -Updating a dynamic block means to remove all the text between BEGIN and -END, parse the BEGIN line for parameters and then call the specific -writer function for this block to insert the new content. If you want -to use the original content in the writer function, you can use the -extra parameter @code{:content}. - -For a block with name @code{myblock}, the writer function is -@code{org-dblock-write:myblock} with as only parameter a property list -with the parameters given in the begin line. Here is a trivial example -of a block that keeps track of when the block update function was last -run: - -@example -#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M" - -#+END: -@end example - -@noindent -The corresponding block writer function could look like this: - -@lisp -(defun org-dblock-write:block-update-time (params) - (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) - (insert "Last block update at: " - (format-time-string fmt (current-time))))) -@end lisp - -If you want to make sure that all dynamic blocks are always up-to-date, -you could add the function @code{org-update-all-dblocks} to a hook, for -example @code{before-save-hook}. @code{org-update-all-dblocks} is -written in a way such that it does nothing in buffers that are not in -@code{org-mode}. - -You can narrow the current buffer to the current dynamic block (like any -other block) with @code{org-narrow-to-block}. - -@node Special agenda views, Extracting agenda information, Dynamic blocks, Hacking -@section Special agenda views -@cindex agenda views, user-defined - -@vindex org-agenda-skip-function -@vindex org-agenda-skip-function-global -Org provides a special hook that can be used to narrow down the selection -made by these agenda views: @code{agenda}, @code{todo}, @code{alltodo}, -@code{tags}, @code{tags-todo}, @code{tags-tree}. You may specify a function -that is used at each match to verify if the match should indeed be part of -the agenda view, and if not, how much should be skipped. You can specify a -global condition that will be applied to all agenda views, this condition -would be stored in the variable @code{org-agenda-skip-function-global}. More -commonly, such a definition is applied only to specific custom searches, -using @code{org-agenda-skip-function}. - -Let's say you want to produce a list of projects that contain a WAITING -tag anywhere in the project tree. Let's further assume that you have -marked all tree headings that define a project with the TODO keyword -PROJECT. In this case you would run a TODO search for the keyword -PROJECT, but skip the match unless there is a WAITING tag anywhere in -the subtree belonging to the project line. - -To achieve this, you must write a function that searches the subtree for -the tag. If the tag is found, the function must return @code{nil} to -indicate that this match should not be skipped. If there is no such -tag, return the location of the end of the subtree, to indicate that -search should continue from there. - -@lisp -(defun my-skip-unless-waiting () - "Skip trees that are not waiting" - (let ((subtree-end (save-excursion (org-end-of-subtree t)))) - (if (re-search-forward ":waiting:" subtree-end t) - nil ; tag found, do not skip - subtree-end))) ; tag not found, continue after end of subtree -@end lisp - -Now you may use this function in an agenda custom command, for example -like this: - -@lisp -(org-add-agenda-custom-command - '("b" todo "PROJECT" - ((org-agenda-skip-function 'my-skip-unless-waiting) - (org-agenda-overriding-header "Projects waiting for something: ")))) -@end lisp - -@vindex org-agenda-overriding-header -Note that this also binds @code{org-agenda-overriding-header} to get a -meaningful header in the agenda view. - -@vindex org-odd-levels-only -@vindex org-agenda-skip-function -A general way to create custom searches is to base them on a search for -entries with a certain level limit. If you want to study all entries with -your custom search function, simply do a search for -@samp{LEVEL>0}@footnote{Note that, when using @code{org-odd-levels-only}, a -level number corresponds to order in the hierarchy, not to the number of -stars.}, and then use @code{org-agenda-skip-function} to select the entries -you really want to have. - -You may also put a Lisp form into @code{org-agenda-skip-function}. In -particular, you may use the functions @code{org-agenda-skip-entry-if} -and @code{org-agenda-skip-subtree-if} in this form, for example: - -@table @code -@item (org-agenda-skip-entry-if 'scheduled) -Skip current entry if it has been scheduled. -@item (org-agenda-skip-entry-if 'notscheduled) -Skip current entry if it has not been scheduled. -@item (org-agenda-skip-entry-if 'deadline) -Skip current entry if it has a deadline. -@item (org-agenda-skip-entry-if 'scheduled 'deadline) -Skip current entry if it has a deadline, or if it is scheduled. -@item (org-agenda-skip-entry-if 'todo '("TODO" "WAITING")) -Skip current entry if the TODO keyword is TODO or WAITING. -@item (org-agenda-skip-entry-if 'todo 'done) -Skip current entry if the TODO keyword marks a DONE state. -@item (org-agenda-skip-entry-if 'timestamp) -Skip current entry if it has any timestamp, may also be deadline or scheduled. -@item (org-agenda-skip-entry 'regexp "regular expression") -Skip current entry if the regular expression matches in the entry. -@item (org-agenda-skip-entry 'notregexp "regular expression") -Skip current entry unless the regular expression matches. -@item (org-agenda-skip-subtree-if 'regexp "regular expression") -Same as above, but check and skip the entire subtree. -@end table - -Therefore we could also have written the search for WAITING projects -like this, even without defining a special function: - -@lisp -(org-add-agenda-custom-command - '("b" todo "PROJECT" - ((org-agenda-skip-function '(org-agenda-skip-subtree-if - 'regexp ":waiting:")) - (org-agenda-overriding-header "Projects waiting for something: ")))) -@end lisp - -@node Extracting agenda information, Using the property API, Special agenda views, Hacking -@section Extracting agenda information -@cindex agenda, pipe -@cindex Scripts, for agenda processing - -@vindex org-agenda-custom-commands -Org provides commands to access agenda information for the command -line in Emacs batch mode. This extracted information can be sent -directly to a printer, or it can be read by a program that does further -processing of the data. The first of these commands is the function -@code{org-batch-agenda}, that produces an agenda view and sends it as -ASCII text to STDOUT. The command takes a single string as parameter. -If the string has length 1, it is used as a key to one of the commands -you have configured in @code{org-agenda-custom-commands}, basically any -key you can use after @kbd{C-c a}. For example, to directly print the -current TODO list, you could use - -@example -emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr -@end example - -If the parameter is a string with 2 or more characters, it is used as a -tags/TODO match string. For example, to print your local shopping list -(all items with the tag @samp{shop}, but excluding the tag -@samp{NewYork}), you could use - -@example -emacs -batch -l ~/.emacs \ - -eval '(org-batch-agenda "+shop-NewYork")' | lpr -@end example - -@noindent -You may also modify parameters on the fly like this: - -@example -emacs -batch -l ~/.emacs \ - -eval '(org-batch-agenda "a" \ - org-agenda-span (quote month) \ - org-agenda-include-diary nil \ - org-agenda-files (quote ("~/org/project.org")))' \ - | lpr -@end example - -@noindent -which will produce a 30-day agenda, fully restricted to the Org file -@file{~/org/projects.org}, not even including the diary. - -If you want to process the agenda data in more sophisticated ways, you -can use the command @code{org-batch-agenda-csv} to get a comma-separated -list of values for each agenda item. Each line in the output will -contain a number of fields separated by commas. The fields in a line -are: - -@example -category @r{The category of the item} -head @r{The headline, without TODO keyword, TAGS and PRIORITY} -type @r{The type of the agenda entry, can be} - todo @r{selected in TODO match} - tagsmatch @r{selected in tags match} - diary @r{imported from diary} - deadline @r{a deadline} - scheduled @r{scheduled} - timestamp @r{appointment, selected by timestamp} - closed @r{entry was closed on date} - upcoming-deadline @r{warning about nearing deadline} - past-scheduled @r{forwarded scheduled item} - block @r{entry has date block including date} -todo @r{The TODO keyword, if any} -tags @r{All tags including inherited ones, separated by colons} -date @r{The relevant date, like 2007-2-14} -time @r{The time, like 15:00-16:50} -extra @r{String with extra planning info} -priority-l @r{The priority letter if any was given} -priority-n @r{The computed numerical priority} -@end example - -@noindent -Time and date will only be given if a timestamp (or deadline/scheduled) -led to the selection of the item. - -A CSV list like this is very easy to use in a post-processing script. -For example, here is a Perl program that gets the TODO list from -Emacs/Org and prints all the items, preceded by a checkbox: - -@example -#!/usr/bin/perl - -# define the Emacs command to run -$cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'"; - -# run it and capture the output -$agenda = qx@{$cmd 2>/dev/null@}; - -# loop over all lines -foreach $line (split(/\n/,$agenda)) @{ - # get the individual values - ($category,$head,$type,$todo,$tags,$date,$time,$extra, - $priority_l,$priority_n) = split(/,/,$line); - # process and print - print "[ ] $head\n"; -@} -@end example - -@node Using the property API, Using the mapping API, Extracting agenda information, Hacking -@section Using the property API -@cindex API, for properties -@cindex properties, API - -Here is a description of the functions that can be used to work with -properties. - -@defun org-entry-properties &optional pom which -Get all properties of the entry at point-or-marker POM.@* -This includes the TODO keyword, the tags, time strings for deadline, -scheduled, and clocking, and any additional properties defined in the -entry. The return value is an alist. Keys may occur multiple times -if the property key was used several times.@* -POM may also be nil, in which case the current entry is used. -If WHICH is nil or `all', get all properties. If WHICH is -`special' or `standard', only get that subclass. -@end defun -@vindex org-use-property-inheritance -@defun org-entry-get pom property &optional inherit -Get value of PROPERTY for entry at point-or-marker POM. By default, -this only looks at properties defined locally in the entry. If INHERIT -is non-nil and the entry does not have the property, then also check -higher levels of the hierarchy. If INHERIT is the symbol -@code{selective}, use inheritance if and only if the setting of -@code{org-use-property-inheritance} selects PROPERTY for inheritance. -@end defun - -@defun org-entry-delete pom property -Delete the property PROPERTY from entry at point-or-marker POM. -@end defun - -@defun org-entry-put pom property value -Set PROPERTY to VALUE for entry at point-or-marker POM. -@end defun - -@defun org-buffer-property-keys &optional include-specials -Get all property keys in the current buffer. -@end defun - -@defun org-insert-property-drawer -Insert a property drawer at point. -@end defun - -@defun org-entry-put-multivalued-property pom property &rest values -Set PROPERTY at point-or-marker POM to VALUES. VALUES should be a list of -strings. They will be concatenated, with spaces as separators. -@end defun - -@defun org-entry-get-multivalued-property pom property -Treat the value of the property PROPERTY as a whitespace-separated list of -values and return the values as a list of strings. -@end defun - -@defun org-entry-add-to-multivalued-property pom property value -Treat the value of the property PROPERTY as a whitespace-separated list of -values and make sure that VALUE is in this list. -@end defun - -@defun org-entry-remove-from-multivalued-property pom property value -Treat the value of the property PROPERTY as a whitespace-separated list of -values and make sure that VALUE is @emph{not} in this list. -@end defun - -@defun org-entry-member-in-multivalued-property pom property value -Treat the value of the property PROPERTY as a whitespace-separated list of -values and check if VALUE is in this list. -@end defun - -@defopt org-property-allowed-value-functions -Hook for functions supplying allowed values for a specific property. -The functions must take a single argument, the name of the property, and -return a flat list of allowed values. If @samp{:ETC} is one of -the values, use the values as completion help, but allow also other values -to be entered. The functions must return @code{nil} if they are not -responsible for this property. -@end defopt - -@node Using the mapping API, , Using the property API, Hacking -@section Using the mapping API -@cindex API, for mapping -@cindex mapping entries, API - -Org has sophisticated mapping capabilities to find all entries satisfying -certain criteria. Internally, this functionality is used to produce agenda -views, but there is also an API that can be used to execute arbitrary -functions for each or selected entries. The main entry point for this API -is: - -@defun org-map-entries func &optional match scope &rest skip -Call FUNC at each headline selected by MATCH in SCOPE. - -FUNC is a function or a Lisp form. The function will be called without -arguments, with the cursor positioned at the beginning of the headline. -The return values of all calls to the function will be collected and -returned as a list. - -The call to FUNC will be wrapped into a save-excursion form, so FUNC -does not need to preserve point. After evaluation, the cursor will be -moved to the end of the line (presumably of the headline of the -processed entry) and search continues from there. Under some -circumstances, this may not produce the wanted results. For example, -if you have removed (e.g.@: archived) the current (sub)tree it could -mean that the next entry will be skipped entirely. In such cases, you -can specify the position from where search should continue by making -FUNC set the variable `org-map-continue-from' to the desired buffer -position. - -MATCH is a tags/property/todo match as it is used in the agenda match view. -Only headlines that are matched by this query will be considered during -the iteration. When MATCH is nil or t, all headlines will be -visited by the iteration. - -SCOPE determines the scope of this command. It can be any of: - -@example -nil @r{the current buffer, respecting the restriction if any} -tree @r{the subtree started with the entry at point} -region @r{The entries within the active region, if any} -file @r{the current buffer, without restriction} -file-with-archives - @r{the current buffer, and any archives associated with it} -agenda @r{all agenda files} -agenda-with-archives - @r{all agenda files with any archive files associated with them} -(file1 file2 ...) - @r{if this is a list, all files in the list will be scanned} -@end example -@noindent -The remaining args are treated as settings for the skipping facilities of -the scanner. The following items can be given here: - -@vindex org-agenda-skip-function -@example -archive @r{skip trees with the archive tag} -comment @r{skip trees with the COMMENT keyword} -function or Lisp form - @r{will be used as value for @code{org-agenda-skip-function},} - @r{so whenever the function returns t, FUNC} - @r{will not be called for that entry and search will} - @r{continue from the point where the function leaves it} -@end example -@end defun - -The function given to that mapping routine can really do anything you like. -It can use the property API (@pxref{Using the property API}) to gather more -information about the entry, or in order to change metadata in the entry. -Here are a couple of functions that might be handy: - -@defun org-todo &optional arg -Change the TODO state of the entry. See the docstring of the functions for -the many possible values for the argument ARG. -@end defun - -@defun org-priority &optional action -Change the priority of the entry. See the docstring of this function for the -possible values for ACTION. -@end defun - -@defun org-toggle-tag tag &optional onoff -Toggle the tag TAG in the current entry. Setting ONOFF to either @code{on} -or @code{off} will not toggle tag, but ensure that it is either on or off. -@end defun - -@defun org-promote -Promote the current entry. -@end defun - -@defun org-demote -Demote the current entry. -@end defun - -Here is a simple example that will turn all entries in the current file with -a tag @code{TOMORROW} into TODO entries with the keyword @code{UPCOMING}. -Entries in comment trees and in archive trees will be ignored. - -@lisp -(org-map-entries - '(org-todo "UPCOMING") - "+TOMORROW" 'file 'archive 'comment) -@end lisp - -The following example counts the number of entries with TODO keyword -@code{WAITING}, in all agenda files. - -@lisp -(length (org-map-entries t "/+WAITING" 'agenda)) -@end lisp - -@node MobileOrg, History and Acknowledgments, Hacking, Top -@appendix MobileOrg -@cindex iPhone -@cindex MobileOrg - -@uref{http://mobileorg.ncogni.to/, MobileOrg} is an application for the -@i{iPhone/iPod Touch} series of devices, developed by Richard Moreland. -@i{MobileOrg} offers offline viewing and capture support for an Org mode -system rooted on a ``real'' computer. It does also allow you to record -changes to existing entries. Android users should check out -@uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android} -by Matt Jones. - -This appendix describes the support Org has for creating agenda views in a -format that can be displayed by @i{MobileOrg}, and for integrating notes -captured and changes made by @i{MobileOrg} into the main system. - -For changing tags and TODO states in MobileOrg, you should have set up the -customization variables @code{org-todo-keywords} and @code{org-tags-alist} to -cover all important tags and TODO keywords, even if individual files use only -part of these. MobileOrg will also offer you states and tags set up with -in-buffer settings, but it will understand the logistics of TODO state -@i{sets} (@pxref{Per-file keywords}) and @i{mutually exclusive} tags -(@pxref{Setting tags}) only for those set in these variables. - -@menu -* Setting up the staging area:: Where to interact with the mobile device -* Pushing to MobileOrg:: Uploading Org files and agendas -* Pulling from MobileOrg:: Integrating captured and flagged items -@end menu - -@node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg -@section Setting up the staging area - -MobileOrg needs to interact with Emacs through a directory on a server. If you -are using a public server, you should consider to encrypt the files that are -uploaded to the server. This can be done with Org mode 7.02 and with -@i{MobileOrg 1.5} (iPhone version), and you need an @file{openssl} -installation on your system. To turn on encryption, set a password in -@i{MobileOrg} and, on the Emacs side, configure the variable -@code{org-mobile-use-encryption}@footnote{If you can safely store the -password in your Emacs setup, you might also want to configure -@code{org-mobile-encryption-password}. Please read the docstring of that -variable. Note that encryption will apply only to the contents of the -@file{.org} files. The file names themselves will remain visible.}. - -The easiest way to create that directory is to use a free -@uref{http://dropbox.com,Dropbox.com} account@footnote{If you cannot use -Dropbox, or if your version of MobileOrg does not support it, you can use a -webdav server. For more information, check out the documentation of MobileOrg and also this -@uref{http://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}. -When MobileOrg first connects to your Dropbox, it will create a directory -@i{MobileOrg} inside the Dropbox. After the directory has been created, tell -Emacs about it: - -@lisp -(setq org-mobile-directory "~/Dropbox/MobileOrg") -@end lisp - -Org mode has commands to put files for @i{MobileOrg} into that directory, -and to read captured notes from there. - -@node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg -@section Pushing to MobileOrg - -This operation copies all files currently listed in @code{org-mobile-files} -to the directory @code{org-mobile-directory}. By default this list contains -all agenda files (as listed in @code{org-agenda-files}), but additional files -can be included by customizing @code{org-mobile-files}. File names will be -staged with paths relative to @code{org-directory}, so all files should be -inside this directory. The push operation also creates a special Org file -@file{agendas.org} with all custom agenda view defined by the -user@footnote{While creating the agendas, Org mode will force ID properties -on all referenced entries, so that these entries can be uniquely identified -if @i{MobileOrg} flags them for further action. If you do not want to get -these properties in so many entries, you can set the variable -@code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode will then -rely on outline paths, in the hope that these will be unique enough.}. -Finally, Org writes the file @file{index.org}, containing links to all other -files. @i{MobileOrg} first reads this file from the server, and then -downloads all agendas and Org files listed in it. To speed up the download, -MobileOrg will only read files whose checksums@footnote{stored automatically -in the file @file{checksums.dat}} have changed. - -@node Pulling from MobileOrg, , Pushing to MobileOrg, MobileOrg -@section Pulling from MobileOrg - -When @i{MobileOrg} synchronizes with the server, it not only pulls the Org -files for viewing. It also appends captured entries and pointers to flagged -and changed entries to the file @file{mobileorg.org} on the server. Org has -a @emph{pull} operation that integrates this information into an inbox file -and operates on the pointers to flagged entries. Here is how it works: - -@enumerate -@item -Org moves all entries found in -@file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after this -operation.} and appends them to the file pointed to by the variable -@code{org-mobile-inbox-for-pull}. Each captured entry and each editing event -will be a top-level entry in the inbox file. -@item -After moving the entries, Org will attempt to implement the changes made in -@i{MobileOrg}. Some changes are applied directly and without user -interaction. Examples are all changes to tags, TODO state, headline and body -text that can be cleanly applied. Entries that have been flagged for further -action will receive a tag @code{:FLAGGED:}, so that they can be easily found -again. When there is a problem finding an entry or applying the change, the -pointer entry will remain in the inbox and will be marked with an error -message. You need to later resolve these issues by hand. -@item -Org will then generate an agenda view with all flagged entries. The user -should then go through these entries and do whatever actions are necessary. -If a note has been stored while flagging an entry in @i{MobileOrg}, that note -will be displayed in the echo area when the cursor is on the corresponding -agenda line. -@table @kbd -@kindex ? -@item ? -Pressing @kbd{?} in that special agenda will display the full flagging note in -another window and also push it onto the kill ring. So you could use @kbd{? -z C-y C-c C-c} to store that flagging note as a normal note in the entry. -Pressing @kbd{?} twice in succession will offer to remove the -@code{:FLAGGED:} tag along with the recorded flagging note (which is stored -in a property). In this way you indicate that the intended processing for -this flagged entry is finished. -@end table -@end enumerate - -@kindex C-c a ? -If you are not able to process all flagged entries directly, you can always -return to this agenda view@footnote{Note, however, that there is a subtle -difference. The view created automatically by @kbd{M-x org-mobile-pull -@key{RET}} is guaranteed to search all files that have been addressed by the -last pull. This might include a file that is not currently in your list of -agenda files. If you later use @kbd{C-c a ?} to regenerate the view, only -the current agenda files will be searched.} using @kbd{C-c a ?}. - -@node History and Acknowledgments, Main Index, MobileOrg, Top -@appendix History and acknowledgments -@cindex acknowledgments -@cindex history -@cindex thanks - -Org was born in 2003, out of frustration over the user interface of the Emacs -Outline mode. I was trying to organize my notes and projects, and using -Emacs seemed to be the natural way to go. However, having to remember eleven -different commands with two or three keys per command, only to hide and show -parts of the outline tree, that seemed entirely unacceptable to me. Also, -when using outlines to take notes, I constantly wanted to restructure the -tree, organizing it parallel to my thoughts and plans. @emph{Visibility -cycling} and @emph{structure editing} were originally implemented in the -package @file{outline-magic.el}, but quickly moved to the more general -@file{org.el}. As this environment became comfortable for project planning, -the next step was adding @emph{TODO entries}, basic @emph{timestamps}, and -@emph{table support}. These areas highlighted the two main goals that Org -still has today: to be a new, outline-based, plain text mode with innovative -and intuitive editing features, and to incorporate project planning -functionality directly into a notes file. - -Since the first release, literally thousands of emails to me or to -@email{emacs-orgmode@@gnu.org} have provided a constant stream of bug -reports, feedback, new ideas, and sometimes patches and add-on code. -Many thanks to everyone who has helped to improve this package. I am -trying to keep here a list of the people who had significant influence -in shaping one or more aspects of Org. The list may not be -complete, if I have forgotten someone, please accept my apologies and -let me know. - -Before I get to this list, a few special mentions are in order: - -@table @i -@item Bastien Guerry -Bastien has written a large number of extensions to Org (most of them -integrated into the core by now), including the @LaTeX{} exporter and the plain -list parser. His support during the early days, when he basically acted as -co-maintainer, was central to the success of this project. Bastien also -invented Worg, helped establishing the Web presence of Org, and sponsors -hosting costs for the orgmode.org website. -@item Eric Schulte and Dan Davison -Eric and Dan are jointly responsible for the Org-babel system, which turns -Org into a multi-language environment for evaluating code and doing literate -programming and reproducible research. -@item John Wiegley -John has contributed a number of great ideas and patches directly to Org, -including the attachment system (@file{org-attach.el}), integration with -Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO -items, habit tracking (@file{org-habits.el}), and encryption -(@file{org-crypt.el}). Also, the capture system is really an extended copy -of his great @file{remember.el}. -@item Sebastian Rose -Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work -of an ignorant amateur. Sebastian has pushed this part of Org onto a much -higher level. He also wrote @file{org-info.js}, a Java script for displaying -webpages derived from Org using an Info-like or a folding interface with -single-key navigation. -@end table - -@noindent OK, now to the full list of contributions! Again, please let me -know what I am missing here! - -@itemize @bullet - -@item -@i{Russel Adams} came up with the idea for drawers. -@item -@i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}. -@item -@i{Christophe Bataillon} created the great unicorn logo that we use on the -Org mode website. -@item -@i{Alex Bochannek} provided a patch for rounding timestamps. -@item -@i{Jan Böcker} wrote @file{org-docview.el}. -@item -@i{Brad Bozarth} showed how to pull RSS feed data into Org mode files. -@item -@i{Tom Breton} wrote @file{org-choose.el}. -@item -@i{Charles Cave}'s suggestion sparked the implementation of templates -for Remember, which are now templates for capture. -@item -@i{Pavel Chalmoviansky} influenced the agenda treatment of items with -specified time. -@item -@i{Gregory Chernov} patched support for Lisp forms into table -calculations and improved XEmacs compatibility, in particular by porting -@file{nouline.el} to XEmacs. -@item -@i{Sacha Chua} suggested copying some linking code from Planner. -@item -@i{Baoqiu Cui} contributed the DocBook exporter. -@item -@i{Eddward DeVilla} proposed and tested checkbox statistics. He also -came up with the idea of properties, and that there should be an API for -them. -@item -@i{Nick Dokos} tracked down several nasty bugs. -@item -@i{Kees Dullemond} used to edit projects lists directly in HTML and so -inspired some of the early development, including HTML export. He also -asked for a way to narrow wide table columns. -@item -@i{Thomas S. Dye} contributed documentation on Worg and helped integrating -the Org-Babel documentation into the manual. -@item -@i{Christian Egli} converted the documentation into Texinfo format, inspired -the agenda, patched CSS formatting into the HTML exporter, and wrote -@file{org-taskjuggler.el}. -@item -@i{David Emery} provided a patch for custom CSS support in exported -HTML agendas. -@item -@i{Nic Ferrier} contributed mailcap and XOXO support. -@item -@i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes. -@item -@i{John Foerch} figured out how to make incremental search show context -around a match in a hidden outline tree. -@item -@i{Raimar Finken} wrote @file{org-git-line.el}. -@item -@i{Mikael Fornius} works as a mailing list moderator. -@item -@i{Austin Frank} works as a mailing list moderator. -@item -@i{Eric Fraga} drove the development of BEAMER export with ideas and -testing. -@item -@i{Barry Gidden} did proofreading the manual in preparation for the book -publication through Network Theory Ltd. -@item -@i{Niels Giesen} had the idea to automatically archive DONE trees. -@item -@i{Nicolas Goaziou} rewrote much of the plain list code. -@item -@i{Kai Grossjohann} pointed out key-binding conflicts with other packages. -@item -@i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a -book. -@item -@i{Bernt Hansen} has driven much of the support for auto-repeating tasks, -task state change logging, and the clocktable. His clear explanations have -been critical when we started to adopt the Git version control system. -@item -@i{Manuel Hermenegildo} has contributed various ideas, small fixes and -patches. -@item -@i{Phil Jackson} wrote @file{org-irc.el}. -@item -@i{Scott Jaderholm} proposed footnotes, control over whitespace between -folded entries, and column view for properties. -@item -@i{Matt Jones} wrote @i{MobileOrg Android}. -@item -@i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}. -@item -@i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also -provided frequent feedback and some patches. -@item -@i{Matt Lundin} has proposed last-row references for table formulas and named -invisible anchors. He has also worked a lot on the FAQ. -@item -@i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org, -and is a prolific contributor on the mailing list with competent replies, -small fixes and patches. -@item -@i{Jason F. McBrayer} suggested agenda export to CSV format. -@item -@i{Max Mikhanosha} came up with the idea of refiling. -@item -@i{Dmitri Minaev} sent a patch to set priority limits on a per-file -basis. -@item -@i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler -happy. -@item -@i{Richard Moreland} wrote @i{MobileOrg} for the iPhone. -@item -@i{Rick Moynihan} proposed allowing multiple TODO sequences in a file -and being able to quickly restrict the agenda to a subtree. -@item -@i{Todd Neal} provided patches for links to Info files and Elisp forms. -@item -@i{Greg Newman} refreshed the unicorn logo into its current form. -@item -@i{Tim O'Callaghan} suggested in-file links, search options for general -file links, and TAGS. -@item -@i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text -version of the reference card. -@item -@i{Takeshi Okano} translated the manual and David O'Toole's tutorial -into Japanese. -@item -@i{Oliver Oppitz} suggested multi-state TODO items. -@item -@i{Scott Otterson} sparked the introduction of descriptive text for -links, among other things. -@item -@i{Pete Phillips} helped during the development of the TAGS feature, and -provided frequent feedback. -@item -@i{Martin Pohlack} provided the code snippet to bundle character insertion -into bundles of 20 for undo. -@item -@i{T.V. Raman} reported bugs and suggested improvements. -@item -@i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality -control. -@item -@i{Paul Rivier} provided the basic implementation of named footnotes. He -also acted as mailing list moderator for some time. -@item -@i{Kevin Rogers} contributed code to access VM files on remote hosts. -@item -@i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a -conflict with @file{allout.el}. -@item -@i{Jason Riedy} generalized the send-receive mechanism for Orgtbl tables with -extensive patches. -@item -@i{Philip Rooke} created the Org reference card, provided lots -of feedback, developed and applied standards to the Org documentation. -@item -@i{Christian Schlauer} proposed angular brackets around links, among -other things. -@item -@i{Paul Sexton} wrote @file{org-ctags.el}. -@item -Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s -@file{organizer-mode.el}. -@item -@i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal -examples, and remote highlighting for referenced code lines. -@item -@i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is -now packaged into Org's @file{contrib} directory. -@item -@i{Daniel Sinder} came up with the idea of internal archiving by locking -subtrees. -@item -@i{Dale Smith} proposed link abbreviations. -@item -@i{James TD Smith} has contributed a large number of patches for useful -tweaks and features. -@item -@i{Adam Spiers} asked for global linking commands, inspired the link -extension system, added support for mairix, and proposed the mapping API. -@item -@i{Ulf Stegemann} created the table to translate special symbols to HTML, -@LaTeX{}, UTF-8, Latin-1 and ASCII. -@item -@i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content -with links transformation to Org syntax. -@item -@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual -chapter about publishing. -@item -@i{Jambunathan K} contributed the ODT exporter. -@item -@i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and -enabled source code highlighting in Gnus. -@item -@i{Stefan Vollmar} organized a video-recorded talk at the -Max-Planck-Institute for Neurology. He also inspired the creation of a -concept index for HTML export. -@item -@i{J@"urgen Vollmer} contributed code generating the table of contents -in HTML output. -@item -@i{Samuel Wales} has provided important feedback and bug reports. -@item -@i{Chris Wallace} provided a patch implementing the @samp{QUOTE} -keyword. -@item -@i{David Wainberg} suggested archiving, and improvements to the linking -system. -@item -@i{Carsten Wimmer} suggested some changes and helped fix a bug in -linking to Gnus. -@item -@i{Roland Winkler} requested additional key bindings to make Org -work on a tty. -@item -@i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks -and contributed various ideas and code snippets. -@item -@end itemize - - -@node Main Index, Key Index, History and Acknowledgments, Top -@unnumbered Concept index - -@printindex cp - -@node Key Index, Command and Function Index, Main Index, Top -@unnumbered Key index - -@printindex ky - -@node Command and Function Index, Variable Index, Key Index, Top -@unnumbered Command and function index - -@printindex fn - -@node Variable Index, , Command and Function Index, Top -@unnumbered Variable index - -This is not a complete index of variables and faces, only the ones that are -mentioned in the manual. For a more complete list, use @kbd{M-x -org-customize @key{RET}} and then click yourself through the tree. - -@printindex vr - -@bye - -@c Local variables: -@c fill-column: 77 -@c indent-tabs-mode: nil -@c paragraph-start: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$" -@c paragraph-separate: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$" -@c End: - - -@c LocalWords: webdavhost pre diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi deleted file mode 100644 index 92c309f5e98..00000000000 --- a/doc/misc/pcl-cvs.texi +++ /dev/null @@ -1,1431 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/pcl-cvs -@settitle PCL-CVS --- Emacs Front-End to CVS -@syncodeindex vr fn -@c %**end of header - -@copying -Copyright @copyright{} 1991-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* PCL-CVS: (pcl-cvs). Emacs front-end to CVS. -@end direntry - -@c The titlepage section does not appear in the Info file. -@titlepage -@sp 4 -@c The title is printed in a large font. -@center @titlefont{User's Guide} -@sp -@center @titlefont{to} -@sp -@center @titlefont{PCL-CVS --- The Emacs Front-End to CVS} -@ignore -@sp 2 -@center release 2.9 -@c -release- -@end ignore -@sp 3 -@center Per Cederqvist -@center Stefan Monnier -@c -date- - -@c The following two commands start the copyright page -@c for the printed manual. This will not appear in the Info file. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@c ================================================================ -@c The real text starts here -@c ================================================================ - -@node Top, About PCL-CVS, (dir), (dir) -@ifnottex -@top PCL-CVS - -This manual describes PCL-CVS, the GNU Emacs front-end to CVS. It -is nowhere near complete, so you are advised to use @kbd{M-x -customize-group RET pcl-cvs @key{RET}} and to look at the documentation strings -of the various commands and major modes for further information. -@c This manual is updated to release 2.5 of PCL-CVS. - -@insertcopying - -@end ifnottex - -@menu -* About PCL-CVS:: Credits, history, @dots{} - -* Getting started:: An introduction with a walk-through example. -* Buffer contents:: An explanation of the buffer contents. -* Selected files:: To which files are commands applied. -* Commands:: All commands, grouped by type. - -* Log Edit Mode:: Major mode to edit log messages. -* Log View Mode:: Major mode to browse log changes. -@c * CVS Status Mode:: Major mode to view CVS' status output. -* Customization:: How you can tailor PCL-CVS to suit your needs. -* Bugs:: Bugs (known and unknown). - -* GNU Free Documentation License:: The license for this documentation. -* Function and Variable Index:: List of functions and variables. -* Concept Index:: List of concepts. -* Key Index:: List of keystrokes. - -@detailmenu - --- The Detailed Node Listing --- - -About PCL-CVS - -* Contributors:: Contributors to PCL-CVS. - -Commands - -* Entering PCL-CVS:: Commands to invoke PCL-CVS -* Setting flags:: Setting flags for CVS commands -* Updating the buffer:: -* Movement commands:: How to move up and down in the buffer -* Marking files:: How to mark files that other commands - will later operate on. -* Committing changes:: Checking in your modifications to the - CVS repository. -* Editing files:: Loading files into Emacs. -* Getting info about files:: Display the log and status of files. -* Adding and removing files:: Adding and removing files -* Undoing changes:: Undoing changes -* Removing handled entries:: Uninteresting lines can easily be removed. -* Ignoring files:: Telling CVS to ignore generated files. -* Viewing differences:: Commands to @samp{diff} different versions. -* Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer. -* Updating files:: Updating files that Need-update. -* Tagging files:: Tagging files. -* Miscellaneous commands:: Miscellaneous commands. - -Customization - -* Customizing Faces:: - -@end detailmenu -@end menu - -@node About PCL-CVS, Getting started, Top, Top -@chapter About PCL-CVS -@cindex About PCL-CVS - -PCL-CVS is a front-end to CVS versions 1.9 and later. -It concisely shows the present status of a checked out module in an -Emacs buffer and provides single-key access to the most frequently used CVS -commands. Note that the @code{vc-dir} command (@pxref{VC Directory -Mode, , , emacs, The GNU Emacs Manual}) provides similar -functionality, but for several version control systems, including CVS. - -PCL-CVS was originally written many years ago by Per Cederqvist who -proudly maintained it until January 1996, at which point he released the -beta version 2.0b2 and passed on the maintainership to Greg A Woods. -Development stayed mostly dormant for a few years during which -version 2.0 never seemed to be able to leave the ``beta'' stage while a -separate XEmacs version was slowly splitting away. In late 1998, -Stefan Monnier picked up development again, adding some major new -functionality and taking over the maintenance. - -@menu -* Contributors:: Contributors to PCL-CVS. -@end menu - -@node Contributors,, About PCL-CVS, About PCL-CVS -@section Contributors to PCL-CVS -@cindex Contributors -@cindex Authors - -Contributions to the package are welcome. I have limited time to work -on this project, but I will gladly add any code that you contribute to -me to this package (@pxref{Bugs}). - -The following persons have made contributions to PCL-CVS. - -@itemize @bullet -@item -Brian Berliner wrote CVS, together with some other contributors. -Without his work on CVS this package would be useless@dots{} - -@item -Per Cederqvist wrote most of the otherwise unattributed functions in -PCL-CVS as well as all the documentation. - -@item -@email{inge@@lysator.liu.se, Inge Wallin} wrote the skeleton of -@file{pcl-cvs.texi}, and gave useful comments on it. He also wrote -the files @file{elib-node.el} and @file{compile-all.el}. The file -@file{cookie.el} was inspired by Inge.@refill - -@item -@email{linus@@lysator.liu.se, Linus Tolke} contributed useful comments -on both the functionality and the documentation.@refill - -@item -@email{jwz@@jwz.com, Jamie Zawinski} contributed -@file{pcl-cvs-lucid.el}, which was later renamed to -@file{pcl-cvs-xemacs.el}.@refill - -@item -Leif Lonnblad contributed RCVS support (since superseded by the new -remote CVS support). - -@item -@email{jimb@@cyclic.com, Jim Blandy} contributed hooks to automatically -guess CVS log entries from @file{ChangeLog} contents, and initial support of -the new Cygnus / Cyclic remote CVS, as well as various sundry bug fixes -and cleanups. - -@item -@email{kingdon@@cyclic.com, Jim Kingdon} contributed lots of fixes to -the build and installation procedure. - -@item -@email{woods@@weird.com, Greg A.@: Woods} contributed code to implement -the use of per-file diff buffers, and vendor join diffs with emerge and -ediff, as well as various and sundry bug fixes and cleanups. - -@item -@email{greg.klanderman@@alum.mit.edu, Greg Klanderman} implemented -toggling of marked files, setting of CVS command flags via prefix -arguments, updated the XEmacs support, updated the manual, and fixed -numerous bugs. - -@item -@email{monnier@@gnu.org, Stefan Monnier} added a slew of other -features and introduced even more new bugs. If there's any bug left, -you can be sure it's his. - -@item -@c wordy to avoid an underfull hbox -@email{masata-y@@is.aist-nara.ac.jp, Masatake YAMATO} made a gracious -contribution of his cvstree code to display a tree of tags which was later -superseded by the new @code{cvs-status-mode}. -@end itemize - -Apart from these, a lot of people have sent us suggestions, ideas, -requests, bug reports and encouragement. Thanks a lot! Without you -there would be no new releases of PCL-CVS. - - -@node Getting started, Buffer contents, About PCL-CVS, Top -@chapter Getting started -@cindex Introduction -@cindex Example run -@cindex Sample session - -This document assumes that you know what CVS is, and that you at least -know the fundamental concepts of CVS. If that is not the case, you -should read the CVS documentation. Type @kbd{info -f cvs} or @kbd{man -cvs}. - -PCL-CVS is only useful once you have checked out a module. So before -you invoke it, you must have a copy of a module somewhere in the file -system. - -You can invoke PCL-CVS by typing @kbd{M-x cvs-examine @key{RET}}. -You can also invoke it via the menu bar, under @samp{Tools}. -Or, if you prefer, you can also invoke PCL-CVS by simply visiting the -CVS administrative subdirectory of your module, with a prefix argument. -For example, to invoke PCL-CVS in a separate frame, type @kbd{C-u C-x 5 -f ~/my/project/CVS @key{RET}}. - -The function @code{cvs-examine} will ask for a directory. The command -@samp{cvs -n update} will be run in that directory. (It should contain -files that have been checked out from a CVS archive.) The output from -@code{cvs} will be parsed and presented in a table in a buffer called -@samp{*cvs*}. It might look something like this: - -@example -Repository : /usr/CVSroot -Module : test -Working dir: /users/ceder/FOO/test - - -In directory .: - Need-Update bar - Need-Update file.txt - Modified namechange - Need-Update newer -In directory sub: - Modified ChangeLog - ---------------------- End --------------------- --- last cmd: cvs -f -z6 -n update -d -P -- -@end example - -In this example, your repository is in @file{/usr/CVSroot} and CVS has -been run in the directory @file{/users/ceder/FOO/test}. The three files -(@file{bar}, @file{file.txt} and -@file{newer}) that are marked with @samp{Need-Update} have been changed -by someone else in the CVS repository. Two files (@file{namechange} -and @file{sub/ChangeLog}) have been modified locally, and need to be -checked in. - -You can move the cursor up and down in the buffer with @kbd{C-n} and -@kbd{C-p} or @kbd{n} and @kbd{p}. If you press @kbd{c} on one of the -@samp{Modified} files, that file will be checked in to the CVS -repository. @xref{Committing changes}. You can also press @kbd{O} to -update any of the files that are marked @samp{Need-Update}. You can -also run @kbd{M-x cvs-update @key{RET}} (bound to @kbd{M-u} in the -@samp{*cvs*} buffer) to update all the files.@refill - -You can then press @kbd{=} to easily get a @samp{diff} between your -modified file and the base version that you started from, or you can -press @kbd{l} to get the output from @samp{cvs log}. Many more such -commands are available simply by pressing a key (@pxref{Getting info -about files}). - -@node Buffer contents, Selected files, Getting started, Top -@chapter Buffer contents -@cindex Buffer contents -@cindex @code{*cvs*} buffer contents - -The display contains several columns, some of which are optional. -These columns are, from left to right: - -@itemize @bullet - -@item -Optionally, the head revision of the file. This is the latest version -found in the repository. It might also contain (instead of the head -revision) a sub status which typically gives further information about -how we got to the current state, for example @samp{patched}, -@samp{merged}, @dots{} - -@item -An asterisk when the file is @dfn{marked} (@pxref{Selected -files}).@refill - -@item -The actual status of the file wrt the repository. See below. - -@item -Optionally, the base revision of the file. This is the version -which the copy in your working directory is based upon. - -@item -The file name. - -@end itemize - -The @samp{file status} field can have the following values: - -@table @samp -@item Modified -The file is modified in your working directory, and there was no -modification to the same file in the repository. This status can have -the following substatus: - -@table @samp -@item merged -The file was modified in your working directory, and there were -modifications in the repository as well, but they were merged -successfully, without conflict, in your working directory.@refill -@end table - -@item Conflict -A conflict was detected while trying to merge your changes to @var{file} -with changes from the repository. @var{file} (the copy in your -working directory) is now the output of the @code{rcsmerge} command on -the two versions; an unmodified copy of your file is also in your -working directory, with the name @file{.#@var{file}.@var{version}}, -where @var{version} is the RCS revision that your modified file started -from. @xref{Viewing differences}, for more details.@refill - -A conflict can also come from a disagreement on the existence of the file -rather than on its content. This case is indicated by the following -possible substatus: - -@table @samp -@item removed -The file is locally removed but a new revision has been committed to -the repository by someone else. - -@item added -The file is locally added and has also been added to the repository -by someone else. - -@item modified -The file is locally modified but someone else has removed it from the -repository. -@end table - -@item Added -The file has been added by you, but it still needs to be checked in to -the repository.@refill - -@item Removed -The file has been removed by you, but it still needs to be checked in to -the repository. You can resurrect it by typing @kbd{a} (@pxref{Adding -and removing files}).@refill - -@item Unknown -A file that was detected in your directory, but that neither appears in -the repository, nor is present on the list of files that CVS should -ignore.@refill - -@item Up-to-date -The file is up to date with respect to the version in the repository. -This status can have a substatus of: - -@table @samp -@item added -You have just added the file to the repository.@refill - -@item updated -The file was brought up to date with respect to the repository. This is -done for any file that exists in the repository but not in your source, -and for files that you haven't changed but are not the most recent -versions available in the repository.@refill - -@item patched -The file was brought up to date with respect to the remote repository by -way of fetching and applying a patch to the file in your source. This -is equivalent to @samp{updated} except that CVS decided to use a hopefully -more efficient method.@refill - -@item committed -You just committed the file.@refill -@end table - -@item Need-Update -Either a newer version than the one in your source is available in the -repository and you have not modified your checked out version, or the -file exists in the repository but not in your source. Use -@samp{cvs-mode-update} bound to @kbd{O} to update the file.@refill - -@item Need-Merge -You have modified the checked out version of the file, and a newer -version is available in the repository. A merge will take place when -you run a @samp{cvs-update}. - -@item Missing -The file has been unexpectedly removed from your working directory -although it has not been @samp{cvs remove}d. -@end table - -@node Selected files, Commands, Buffer contents, Top -@chapter Selected files -@cindex Selected files -@cindex Marked files -@cindex File selection -@cindex Active files -@cindex Applicable - -Many of the commands work on the current set of @dfn{selected} files -which can be either the set of marked files (if any file is marked and -marks are not ignored) or whichever file or directory the cursor is on. - -If a directory is selected but the command cannot be applied to a -directory, then it will be applied to the set of files under this -directory which are in the @samp{*cvs*} buffer. - -@findex cvs-mode-force-command -@findex cvs-allow-dir-commit -Furthermore, each command only operates on a subset of the selected -files, depending on whether or not the command is @dfn{applicable} to -each file (based on the file's status). For example, -@code{cvs-mode-commit} is not applicable to a file whose status is -@samp{Need-Update}. If it should happen that PCL-CVS guesses the -applicability wrong, you can override it with the special prefix -@code{cvs-mode-force-command} normally bound to @kbd{M-f} (and file a -bug report). The applicability rule can be slightly changed with -@code{cvs-allow-dir-commit} and @code{cvs-force-dir-tag}. - -By default, marks are always in effect (you may change this, however, by -setting the variable @code{cvs-default-ignore-marks}) except for the -commands that @samp{tag} or @samp{diff} a file (which can be changed -with the variable @code{cvs-invert-ignore-marks}). - -In addition, you may use the special prefix @code{cvs-mode-toggle-marks} -normally bound to @key{T} to toggle the use of marks for the following -command. - -This scheme might seem a little complicated, but once one gets used to -it, it is quite powerful. - -For commands to mark and unmark files, see @ref{Marking files}. - -@node Commands, Log Edit Mode, Selected files, Top -@chapter Commands - -@iftex -This chapter describes all the commands that you can use in PCL-CVS. -@end iftex -@ifnottex -The nodes in this menu contains explanations about all the commands that -you can use in PCL-CVS. They are grouped together by type. -@end ifnottex - -@menu -* Entering PCL-CVS:: Commands to invoke PCL-CVS -* Setting flags:: Setting flags for CVS commands -* Updating the buffer:: -* Movement commands:: How to move up and down in the buffer -* Marking files:: How to mark files that other commands - will later operate on. -* Committing changes:: Checking in your modifications to the - CVS repository. -* Editing files:: Loading files into Emacs. -* Getting info about files:: Display the log and status of files. -* Adding and removing files:: Adding and removing files -* Undoing changes:: Undoing changes -* Removing handled entries:: Uninteresting lines can easily be removed. -* Ignoring files:: Telling CVS to ignore generated files. -* Viewing differences:: Commands to @samp{diff} different versions. -* Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer. -* Updating files:: Updating files that Need-update. -* Tagging files:: Tagging files. -* Miscellaneous commands:: Miscellaneous commands. -@end menu - - -@node Entering PCL-CVS, Setting flags, Commands, Commands -@section Entering PCL-CVS -@findex cvs-update -@findex cvs-examine -@findex cvs-status -@findex cvs-checkout -@findex cvs-quickdir -@cindex Creating the *cvs* buffer - -Most commands in PCL-CVS require that you have a @samp{*cvs*} -buffer. The commands that you use to get one are listed below. -For each, a @samp{cvs} process will be run, the output will be parsed by -PCL-CVS, and the result will be printed in the @samp{*cvs*} buffer (see -@ref{Buffer contents}, for a description of the buffer's contents). - -@table @kbd -@item M-x cvs-update -Run a @samp{cvs update} command. You will be asked for the directory -in which the @samp{cvs update} will be run. - -@item M-x cvs-examine -Run a @samp{cvs -n update} command. This is identical to the previous -command, except that it will only check what needs to be done but will -not change anything. You will be asked for the directory in -which the @samp{cvs -n update} will be run. - -@item M-x cvs-status -Run a @samp{cvs status} command. You will be asked for the directory -in which the @samp{cvs status} will be run. - -@item M-x cvs-checkout -Run a @samp{cvs checkout} command. You will be asked for the directory -in which the @samp{cvs update} will be run and the module to be checked -out. - -@item M-x cvs-quickdir -Populate the @samp{*cvs*} buffer by just looking at the @file{CVS/Entries} -files. This is very much like @code{cvs-examine} except that it does -not access the CVS repository, which is a major advantage when the -repository is far away. But of course, it will not be able to detect -when a file needs to be updated or merged. -@end table - -@findex cvs-dired-action -@findex cvs-dired-use-hook -The first four of -those commands are also reachable from the menu bar -under @samp{Tools->PCL-CVS}. Finally, an alternative way is to visit -the CVS administrative subdirectory in your work area with a simple -prefix argument. For example @kbd{C-u C-x C-f ~/my/work/CVS @key{RET}}. This -by default runs @code{cvs-quickdir} but the specific behavior can be -changed with @code{cvs-dired-action} and @code{cvs-dired-use-hook}. - -By default, the commands above will descend recursively into -subdirectories. You can avoid that behavior by including @samp{-l} in -the flags for the command. These flags can be set by giving a prefix -argument to the command (e.g., by typing -@kbd{C-u M-x cvs-update @key{RET} -l @key{RET}}). - - -@node Setting flags, Updating the buffer, Entering PCL-CVS, Commands -@section Setting flags for CVS commands -@cindex Optional switches to CVS -@cindex Command-line options to CVS - -This section describes the convention used by nearly all PCL-CVS -commands for setting optional flags sent to CVS. A single @kbd{C-u} -prefix argument is used to cause the command to prompt for flags to be -used for the current invocation of the command only. Two @kbd{C-u} prefix -arguments are used to prompt for flags which will be set permanently, for the -current invocation and all that follow, until the flags are changed, or -unless temporary flags are set which override them. - -Perhaps an example or two is in order. Say you are about to add a -binary file to the repository, and want to specify the flags @samp{-kb} -to @samp{cvs add}. You can type @kbd{C-u a -kb @key{RET}}, -and the file will be added. Subsequent @samp{cvs add} -commands will use the previously prevailing flags. - -As a second example, say you are about to perform a diff and want to see -the result in unified diff format, i.e. you'd like to pass the flag -@samp{-u} to both @samp{cvs diff} and @samp{diff}. You'd also like all -subsequent diffs to use this flag. You can type @kbd{C-u C-u = -u @key{RET}} -and the diff will be performed, and the default flags will be set to -@code{("-u")}. You can of course override this flag for a single diff -by using a single @kbd{C-u} prefix argument. - -@cindex Special prefix -In addition to this, some commands can take @dfn{special prefix} arguments. -These work as follows: When called with a @kbd{C-u} prefix, the user is -prompted for a new value of the special prefix and the special prefix is -activated for the next command. When called without the @kbd{C-u} -prefix, the special prefix is re-activated (with the same value as last -time) for the next command. Calling the prefix command again when it's -already activated deactivates it. Calling it with the @kbd{C-u C-u} -prefix activates it for all subsequent commands until you deactivate it -explicitly. The special prefixes are: - -@table @kbd -@item T -Toggles whether or not marks will be active in the next command.@refill - -@item b -Provide the next command with a branch (can be any version -specifier) to work on.@refill - -@item B -Secondary branch argument. Only meaningful if @kbd{b} is also used. -It can be used to provide a second branch argument to -@code{cvs-mode-diff} or to @code{cvs-mode-update}. - -@item M-f -Forces the next command to apply to every selected file rather than only -to the ones PCL-CVS thinks are relevant. -@end table - -@node Updating the buffer, Movement commands, Setting flags, Commands -@section Updating the @samp{*cvs*} buffer -@findex cvs-update -@findex cvs-examine -@findex cvs-status -@findex cvs-mode-update -@findex cvs-mode-examine -@findex cvs-mode-status - -The following commands can be used from within the @samp{*cvs*} buffer -to update the display: - -@table @kbd -@item M-u -Runs the command @samp{cvs-update}.@refill - -@item M-e -Runs the command @samp{cvs-examine}.@refill - -@item M-s -Runs the command @samp{cvs-status}.@refill -@end table - -In addition to the above commands which operate on the whole module, -you can run the equivalent CVS command on just a subset of the -files/directories with these keys: - -@table @kbd -@item O -Runs @code{cvs-mode-update} on the selected files. When run on the -top-level directory, this is equivalent to @kbd{M-u}.@refill - -@item e -Runs @code{cvs-mode-examine} on the selected files. When run on the -top-level directory, this is equivalent to @kbd{M-e}.@refill - -@findex cvs-status-mode -@item s -Runs @code{cvs-mode-status} on the selected files. When run on the -top-level directory, this is equivalent to @kbd{M-s}, except that -CVS output will be shown in a @samp{*cvs-info*} buffer that will be -put in @samp{cvs-status-mode}.@refill -@end table - - -@node Movement commands, Marking files, Updating the buffer, Commands -@section Movement Commands -@cindex Movement Commands -@findex cvs-mode-next-line -@findex cvs-mode-previous-line -@kindex SPC@r{--Move down one file} -@kindex n@r{--Move down one file} -@kindex p@r{--Move up one file} - -You can use most normal Emacs commands to move forward and backward in -the buffer. Some keys are rebound to functions that take advantage of -the fact that the buffer is a PCL-CVS buffer: - - -@table @kbd -@item @key{SPC} -@itemx n -These keys move the cursor one file forward, towards the end of the -buffer (@code{cvs-mode-next-line}).@refill - -@itemx p -This key moves one file backward, towards the beginning of the buffer -(@code{cvs-mode-previous-line}). -@end table - - -@node Marking files, Committing changes, Movement commands, Commands -@section Marking files -@cindex Selecting files (commands to mark files) -@cindex Marking files -@kindex m@r{--marking a file} -@kindex M@r{--marking all files} -@kindex u@r{--unmark a file} -@kindex ESC DEL@r{--unmark all files} -@kindex DEL@r{--unmark previous file} -@kindex %@r{--mark files matching regexp} -@kindex S@r{--mark files in a particular state} -@kindex T@r{--toggle marks} -@findex cvs-mode-mark -@findex cvs-mode-unmark -@findex cvs-mode-mark-all-files -@findex cvs-mode-unmark-all-files -@findex cvs-mode-unmark-up -@findex cvs-mode-mark-matching-files -@findex cvs-mode-mark-on-state -@findex cvs-mode-toggle-marks - -PCL-CVS works on a set of @dfn{selected files} (@pxref{Selected files}). -You can mark and unmark files with these commands: - -@table @kbd -@item m -This marks the file that the cursor is positioned on. If the cursor is -positioned on a directory all files in that directory are marked -(@code{cvs-mode-mark}).@refill - -@item u -Unmark the file that the cursor is positioned on. If the cursor is on a -directory, all files in that directory are unmarked -(@code{cvs-mode-unmark}).@refill - -@item M -Mark @emph{all} files in the buffer (@code{cvs-mode-mark-all-files}). - -@item M-@key{DEL} -Unmark @emph{all} files (@code{cvs-mode-unmark-all-files}). - -@item @key{DEL} -Unmark the file on the previous line, and move point to that line -(@code{cvs-mode-unmark-up}). - -@item % -Mark all files matching a regular expression -(@code{cvs-mode-mark-matching-files}). - -@item S -Mark all files in a particular state, such as ``Modified'' or -``Removed'' (@code{cvs-mode-mark-on-state}). - -@item T -Toggle use of marks for the next command (@code{cvs-mode-toggle-marks}). -@end table - - -@node Committing changes, Editing files, Marking files, Commands -@section Committing changes -@cindex Committing changes -@findex cvs-mode-commit -@findex cvs-mode-commit-setup -@kindex c@r{--commit files} -@kindex C@r{--commit files with @file{ChangeLog} message} -@vindex cvs-auto-revert@r{ (variable)} -@cindex Commit buffer -@cindex Edit buffer -@cindex Erasing commit message -@cindex Reverting buffers after commit - -Committing changes basically works as follows: - -@enumerate -@item -After having selected the files you want to commit, you type either -@kbd{c} or @kbd{C} which brings up a special buffer -@samp{*cvs-commit*}.@refill - -@item -You type in the log message describing the changes you're about to -commit (@pxref{Log Edit Mode}). - -@item -When you're happy with it, you type @kbd{C-c C-c} to do the actual -commit.@refill -@end enumerate - -There's no hidden state, so you can abort the process or pick it up -again at any time. - -@vindex log-edit-confirm@r{ (variable)} -The set of files actually committed is really decided only during the -very last step, which is a mixed blessing. It allows you to go back and -change your mind about which files to commit, but it also means that you -might inadvertently change the set of selected files. To reduce the -risk of error, @kbd{C-c C-c} will ask for confirmation if the set of -selected files has changed between the first step and the last. You can -change this last detail with @code{log-edit-confirm}. - -As for the difference between @kbd{c} (i.e. @code{cvs-mode-commit}) and -@kbd{C} (i.e. @code{cvs-mode-commit-setup}) is that the first gets you -straight to @samp{*cvs-commit*} without erasing it or changing anything -to its content, while the second first erases @samp{*cvs-commit*} -and tries to initialize it with a sane default (it does that by either -using a template provided by the CVS administrator or by extracting a -relevant log message from a @file{ChangeLog} file). - -If you are editing the files in your Emacs, an automatic -@samp{revert-buffer} will be performed. (If the file contains -@samp{$@asis{Id}$} keywords, @samp{cvs commit} will write a new file with -the new values substituted. The auto-revert makes sure that you get -them into your buffer.) The revert will not occur if you have modified -your buffer, or if @samp{cvs-auto-revert} is set to -@samp{nil}. - - -@node Editing files, Getting info about files, Committing changes, Commands -@section Editing files -@cindex Editing files -@cindex Finding files -@cindex Loading files -@cindex Dired -@cindex Invoking dired -@findex cvs-mode-find-file -@findex cvs-mode-find-file-other-window -@findex cvs-mode-add-change-log-entry-other-window -@kindex f@r{--find file or directory} -@kindex o@r{--find file in other window} -@kindex A@r{--add @file{ChangeLog} entry} - -There are currently three commands that can be used to find a file (that -is, load it into a buffer and start editing it there). These commands -work on the line that the cursor is situated at. They always ignore any marked -files. - -@table @kbd -@item f -Find the file that the cursor points to (@code{cvs-mode-find-file}). If -the cursor points to a directory, run @code{dired} on that directory; -@inforef{Dired, , emacs}. - -@item o -Like @kbd{f}, but use another window -(@code{cvs-mode-find-file-other-window}).@refill - -@item A -Invoke @samp{add-change-log-entry-other-window} to edit a -@file{ChangeLog} file. The @file{ChangeLog} file will be found in the -directory of the file the cursor points to, or in a parent of that -directory (@code{cvs-mode-add-change-log-entry-other-window}).@refill -@end table - - -@node Getting info about files, Adding and removing files, Editing files, Commands -@section Getting info about files -@cindex Status (cvs command) -@cindex Log (RCS/cvs command) -@cindex Getting status -@kindex l@r{--run @samp{cvs log}} -@kindex s@r{--run @samp{cvs status}} -@findex cvs-mode-log -@findex cvs-mode-status - -@table @kbd -@item l -Call the command @code{cvs-mode-log} which runs @samp{cvs log} on all -selected files, and show the result in a temporary buffer -@samp{*cvs-info*} (@pxref{Log View Mode}). - -@item s -Call the command @code{cvs-mode-status} which runs @samp{cvs status} on -all selected files, and show the result in a temporary buffer -@samp{*cvs-info*}. -@c Fixme: reinstate when node is written: -@c (@pxref{CVS Status Mode}). -@end table - - -@node Adding and removing files, Undoing changes, Getting info about files, Commands -@section Adding and removing files -@cindex Adding files -@cindex Removing files -@cindex Resurrecting files -@cindex Deleting files -@cindex Putting files under CVS control -@kindex a@r{--add a file} -@kindex r@r{--remove a file} -@findex cvs-mode-add -@findex cvs-mode-remove-file - -The following commands are available to make it easy to add files to -and remove them from the CVS repository. - -@table @kbd -@item a -Add all selected files. This command can be used on @samp{Unknown} -files (@pxref{Buffer contents}). The status of the file will change to -@samp{Added}, and you will have to use @kbd{c} (@samp{cvs-mode-commit} -@pxref{Committing changes}), to really add the file to the -repository.@refill - -This command can also be used on @samp{Removed} files (before you commit -them) to resurrect them. - -The command that is run is @code{cvs-mode-add}. - -@item r -This command removes the selected files (after prompting for -confirmation). The files are deleted from your directory and -(unless the status was @samp{Unknown}; @pxref{Buffer contents}) they will -also be @samp{cvs remove}d. If the files' status was @samp{Unknown} -they will disappear from the buffer. Otherwise their status will change to -@samp{Removed}, and you must use @kbd{c} (@samp{cvs-mode-commit}, -@pxref{Committing changes}) to commit the removal.@refill - -The command that is run is @code{cvs-mode-remove-file}. -@end table - - -@node Undoing changes, Removing handled entries, Adding and removing files, Commands -@section Undoing changes -@cindex Undo changes -@cindex Flush changes -@kindex U@r{--undo changes} -@findex cvs-mode-undo-local-changes - -@table @kbd -@item U -If you have modified a file, and for some reason decide that you don't -want to keep the changes, you can undo them with this command. It works -by removing your working copy of the file and then getting the latest -version from the repository (@code{cvs-mode-undo-local-changes}). -@end table - - -@node Removing handled entries, Ignoring files, Undoing changes, Commands -@section Removing handled entries -@cindex Expunging uninteresting entries -@cindex Uninteresting entries, getting rid of them -@cindex Getting rid of uninteresting lines -@cindex Removing uninteresting (processed) lines -@cindex Handled lines, removing them -@kindex x@r{--remove processed entries} -@kindex C-k@r{--remove selected entries} -@findex cvs-mode-remove-handled -@findex cvs-mode-acknowledge -@findex cvs-mode-ignore - -@table @kbd -@item x -This command allows you to remove all entries that you have processed. -More specifically, the lines for @samp{Up-to-date} files (@pxref{Buffer -contents}) are removed from the buffer. If a directory becomes empty -the heading for that directory is also removed. This makes it easier to -get an overview of what needs to be done. - -@vindex cvs-mode-remove-handled@r{ (variable)} -@kbd{x} invokes @code{cvs-mode-remove-handled}. If -@samp{cvs-auto-remove-handled} is set to non-@code{nil}, this will -automatically be performed after every commit.@refill - -@item C-k -This command can be used for lines that @samp{cvs-mode-remove-handled} would -not delete, but that you want to delete (@code{cvs-mode-acknowledge}). -@end table - - -@node Ignoring files, Viewing differences, Removing handled entries, Commands -@section Ignoring files -@cindex Ignoring files -@kindex i@r{--ignoring files} -@findex cvs-mode-ignore - -@table @kbd -@item i -Arrange so that CVS will ignore the selected files. The file names are -added to the @file{.cvsignore} file in the corresponding directory. If -the @file{.cvsignore} file doesn't exist, it will be created. - -The @file{.cvsignore} file should normally be added to the repository, -but you could ignore it as well, if you like it better that way. - -This runs @code{cvs-mode-ignore}. -@end table - -@node Viewing differences, Invoking Ediff, Ignoring files, Commands -@section Viewing differences -@cindex Diff -@cindex Invoking @code{diff} -@cindex Conflicts, how to resolve them -@cindex Viewing differences -@kindex d=@r{--run @samp{cvs diff}} -@kindex =@r{--run @samp{cvs diff}} -@kindex db@r{--diff against base version} -@kindex dh@r{--diff against head of repository} -@kindex dr@r{--diff between base and head of repository} -@kindex dv@r{--diff against vendor branch} -@kindex dy@r{--diff against yesterday's head} -@findex cvs-mode-diff -@findex cvs-mode-diff-backup -@findex cvs-mode-diff-head -@findex cvs-mode-diff-repository -@findex cvs-mode-diff-vendor -@findex cvs-mode-diff-yesterday -@vindex cvs-invert-ignore-marks@r{ (variable)} - -@table @kbd -@item = -@itemx d = -Display a @samp{cvs diff} between the selected files and the version -that they are based on (@code{cvs-mode-diff}).@refill - -@item d b -If CVS finds a conflict while merging two versions of a file (during a -@samp{cvs update}, @pxref{Updating the buffer}) it will save the -original file in a file called @file{.#@var{file}.@var{version}} where -@var{file} is the name of the file, and @var{version} is the revision -number that @var{file} was based on.@refill - -With the @kbd{d b} command you can run a @samp{diff} on the files -@file{.#@var{file}.@var{version}} and @file{@var{file}}.@refill - -@item d h -Display a @samp{cvs diff} between the selected files and the head -revision (the most recent version on the current -branch) in the repository (@code{cvs-mode-diff-head}).@refill - -@item d r -Display a @samp{cvs diff} between the base revision of the selected -files and the head revision in the repository. This displays the -changes anyone has committed to the repository since you last executed -a checkout, update or commit operation -(@code{cvs-mode-diff-repository}). - -@item d v -Display a @samp{cvs diff} between the selected files and the head -revision of the vendor branch in the repository -(@code{cvs-mode-diff-vendor}).@refill - -@item d y -Display a @samp{cvs diff} between the selected files and yesterday's -head revision in the repository -(@code{cvs-mode-diff-yesterday}).@refill -@end table - -By default, @samp{diff} commands ignore the marks. This can be changed -with @code{cvs-invert-ignore-marks}. - -@node Invoking Ediff, Updating files, Viewing differences, Commands -@section Running ediff -@cindex Ediff -@cindex Invoking ediff -@cindex Viewing differences -@cindex Conflicts, how to resolve them -@cindex Resolving conflicts -@kindex e@r{--invoke @samp{ediff}} -@findex cvs-mode-idiff -@findex cvs-mode-imerge - -@table @kbd -@vindex cvs-idiff-imerge-handlers@r{ (variable)} -@item d e -This uses @code{ediff} (or @code{emerge}, depending on -@samp{cvs-idiff-imerge-handlers}) to allow you to view diffs. -If a prefix argument is given, PCL-CVS will prompt for a revision against -which the diff should be made, else the default will be to use the BASE -revision. - -@cindex Merging with @code{ediff} and @code{emerge} -@item d E -This command use @code{ediff} (or @code{emerge}, see above) to allow you -to do an interactive 3-way merge. - -@strong{Please note:} when the file status is @samp{Conflict}, -CVS has already performed a merge. The resulting file is not used in -any way if you use this command. If you use the @kbd{q} command inside -@samp{ediff} (to successfully terminate a merge) the file that CVS -created will be overwritten.@refill -@end table - -@node Updating files, Tagging files, Invoking Ediff, Commands -@section Updating files -@findex cvs-mode-update -@cindex Updating files -@kindex O@r{--update files} - -@table @kbd -@item O -Update all selected files with status @samp{Need-update} by running -@samp{cvs update} on them (@code{cvs-mode-update}). -@end table - - -@node Tagging files, Miscellaneous commands, Updating files, Commands -@section Tagging files -@findex cvs-mode-tag -@findex cvs-mode-untag -@findex cvs-rtag -@cindex Tagging files -@kindex M-t@r{--repository tag files} -@kindex t@r{--tag files} -@vindex cvs-invert-ignore-marks@r{ (variable)} -@vindex cvs-force-dir-tag@r{ (variable)} - -@table @kbd -@item t -Tag all selected files by running @samp{cvs tag} on -them (@code{cvs-mode-tag}). It's usually preferable to tag a directory -at a time. Rather than selecting all files (which too often doesn't -select all files but only the few that are displayed), clear the -selection with @kbd{M-DEL} (@code{cvs-mode-unmark-all-files}), position -the cursor on the directory you want to tag and hit @kbd{t}. -@end table - -By default, @samp{tag} commands ignore the marks. This can be changed -with @code{cvs-invert-ignore-marks}. Also, by default @samp{tag} can -only be applied to directories, see @code{cvs-force-dir-tag} if you want -to change this behavior. - - -@node Miscellaneous commands, , Tagging files, Commands -@section Miscellaneous commands -@findex cvs-mode-byte-compile-files -@cindex Recompiling elisp files -@cindex Byte compilation -@findex cvs-mode-delete-lock -@cindex Getting rid of lock files -@cindex Lock files -@kindex q@r{--bury the PCL-CVS buffer} -@findex cvs-bury-buffer -@findex cvs-mode-quit -@cindex Quitting -@kindex h@r{--help} -@kindex ?@r{--help} -@findex cvs-help -@cindex Help - -@table @kbd -@item M-x cvs-mode-byte-compile-files -Byte compile all selected files that end in @file{.el}. - -@item M-x cvs-mode-delete-lock -This command deletes the lock files that -the @samp{*cvs*} buffer informs you about. You should normally never have to -use this command, since CVS tries very carefully to always remove the -lock files itself. - -You can only use this command when a message in the @samp{*cvs*} buffer tells -you so. You should wait a while before using this command in case -someone else is running a @code{cvs} command. - -Also note that this only works if the repository is local. - -@item ? -@itemx h -Show a summary of common command key bindings in the echo -area (@code{cvs-help}). - -@item q -Bury the PCL-CVS buffer (@code{cvs-bury-buffer}). - -@item M-x cvs-mode-quit -Quit PCL-CVS, killing the @samp{*cvs*} buffer. -@end table - -@node Log Edit Mode, Log View Mode, Commands, Top -@chapter Editing a Log Message - -@cindex Log Edit mode -@cindex mode, Log Edit -Buffers for entering/editing log messages for changes which are about -to be committed are put into Log Edit mode. - -Sometimes the log buffer contains default text when you enter it, -typically the last log message entered. If it does, mark and point -are set around the entire contents of the buffer so that it is easy to -kill the contents of the buffer with @kbd{C-w}. - -@findex log-edit-insert-changelog -If you work by writing entries in the @file{ChangeLog} -(@pxref{(emacs)Change Log}) and then commit the change under revision -control, you can generate the Log Edit text from the ChangeLog using -@kbd{C-c C-a} (@kbd{log-edit-insert-changelog}). This looks for -entries for the file(s) concerned in the top entry in the ChangeLog -and uses those paragraphs as the log text. This text is only inserted -if the top entry was made under your user name on the current date. -@xref{(emacs)Change Logs and VC}, for the opposite way of -working---generating ChangeLog entries from the revision control log. - -In the Log Edit buffer, @kbd{C-c C-f} (@kbd{M-x log-edit-show-files}) -shows the list of files to be committed in case you need to check -that. - -When you have finished editing the log message, type @kbd{C-c C-c} to -exit the buffer and commit the change. - -@c Fixme: customization variables - -@node Log View Mode, Customization, Log Edit Mode, Top -@chapter Browsing a Log of Changes - -@cindex Log View mode -@cindex mode, Log View -@cindex output, logs - -@findex cvs-mode-log -@findex vc-print-log -Log View mode provides a few useful commands for navigating revision -control log output. It is used for the output buffers of both -@code{cvs-mode-log} and @code{vc-print-log}. - -In this mode, @kbd{n} goes to the next message and @kbd{p} goes to the -previous message and @kbd{N} and @kbd{P} go to the next and previous -files, respectively, in multi-file output. With a numeric prefix -argument, these commands move that many messages of files. - -@c @node CVS Status Mode -@c @chapter Viewing CVS' Status output - -@node Customization, Bugs, Log View Mode, Top -@chapter Customization -@vindex log-edit-changelog-full-paragraphs@r{ (variable)} -@vindex cvs-auto-remove-handled@r{ (variable)} -@vindex cvs-auto-remove-directories@r{ (variable)} -@vindex cvs-update-prog-output-skip-regexp@r{ (variable)} -@vindex cvs-cvsroot@r{ (variable)} -@vindex cvs-auto-revert@r{ (variable)} -@vindex log-edit-require-final-newline@r{ (variable)} -@vindex cvs-sort-ignore-file@r{ (variable)} -@cindex Customization -@cindex Variables, list of all -@cindex Erasing input buffer -@cindex Context diff, how to get -@cindex Unidiff, how to get -@cindex Automatically remove handled files -@cindex @samp{-u} option in modules file -@cindex Modules file (@samp{-u} option) -@cindex Update program (@samp{-u} option in modules file) -@cindex Reverting buffers after commit -@cindex Require final newline -@cindex Automatically inserting newline -@cindex Commit message, inserting newline -@cindex Sorting @file{.cvsignore} file -@cindex @file{.cvsignore} file, sorting -@cindex Automatically sorting @file{.cvsignore} -@cindex @samp{CVSROOT}, overriding - -If you have an idea about any customization that would be handy but -isn't present in this list, please tell us! -For info on how to reach us, see @ref{Bugs}.@refill - -@table @samp -@item cvs-auto-remove-handled -If this variable is set to any non-@code{nil} value, -@samp{cvs-mode-remove-handled} will be called every time you check in -files, after the check-in is ready. @xref{Removing handled -entries}.@refill - -@item cvs-auto-remove-directories -If this variable is set to any non-@code{nil} value, directories that do -not contain any files to be checked in will not be listed in the -@samp{*cvs*} buffer.@refill - -@item cvs-auto-revert -If this variable is set to any non-@samp{nil} value any buffers you have -that visit a file that is committed will be automatically reverted. -This variable defaults to @samp{t}. @xref{Committing changes}.@refill - -@item cvs-update-prog-output-skip-regexp -The @samp{-u} flag in the @file{modules} file can be used to run a command -whenever a @samp{cvs update} is performed (see @code{cvs(5)}). This regexp -is used to search for the last line in that output. It is normally set -to @samp{$}. That setting is only correct if the command outputs -nothing. Note that PCL-CVS will get very confused if the command -outputs @emph{anything} to @code{stderr}. - -@item cvs-cvsroot -This variable can be set to override @samp{CVSROOT}. It should be a -string. If it is set, then every time a @code{cvs} command is run, it -will be called as @samp{cvs -d @var{cvs-cvsroot}@dots{}}. This can be -useful if your site has several repositories. - -@item log-edit-require-final-newline -@c wordy to avoid underfull hbox -When you enter a log message by typing into the -@samp{*cvs-commit-message*} buffer, PCL-CVS normally automatically -inserts a trailing newline, unless there already is one. This behavior -can be controlled via @samp{cvs-commit-buffer-require-final-newline}. -If it is @samp{t} (the default behavior), a newline will always be -appended. If it is @samp{nil}, newlines will never be appended. Any -other value causes PCL-CVS to ask the user whenever there is no trailing -newline in the commit message buffer. - -@findex cvs-mode-changelog-commit -@item log-edit-changelog-full-paragraphs -If this variable is non-@code{nil}, include full @file{ChangeLog} -paragraphs in the CVS log created by @samp{cvs-mode-changelog-commit}. -This may be set in the local variables section of a @file{ChangeLog} -file, to indicate the policy for that @file{ChangeLog}. - -@cindex @file{ChangeLog} paragraphs -A @dfn{@file{ChangeLog} paragraph} is a bunch of log text containing no -blank lines; a paragraph usually describes a set of changes with a -single purpose, but perhaps spanning several functions in several files. -Changes in different paragraphs are unrelated. - -You could argue that the CVS log entry for a file should contain the -full @file{ChangeLog} paragraph mentioning the change to the file, even though -it may mention other files, because that gives you the full context you -need to understand the change. This is the behavior you get when this -variable is set to @code{t}, the default. - -On the other hand, you could argue that the CVS log entry for a change -should contain only the text for the changes which occurred in that -file, because the CVS log is per-file. This is the behavior you get -when this variable is set to @code{nil}. - -@findex cvs-mode-ignore@r{, and @file{.cvsignore} sorting} -@item cvs-sort-ignore-file -If this variable is set to any non-@samp{nil} value, the -@file{.cvsignore} file will always be sorted whenever you use -@samp{cvs-mode-ignore} to add a file to it. This option is on by -default. -@end table - - -@menu -* Customizing Faces:: -@end menu - -@node Customizing Faces, , Customization, Customization -@section Customizing Faces -@vindex cvs-header (face) -@vindex cvs-filename (face) -@vindex cvs-unknown (face) -@vindex cvs-handled (face) -@vindex cvs-need-action (face) -@vindex cvs-marked (face) -@vindex cvs-msg (face) - -PCL-CVS adds a few extra features, including menus, mouse bindings, and -fontification of the @samp{*cvs*} buffer. The faces defined for -fontification are listed below: - -@table @samp -@item cvs-header -used to highlight directory changes. - -@item cvs-filename -Used to highlight file names. - -@item cvs-unknown -Used to highlight the status of files which are @samp{Unknown}. - -@item cvs-handled -Used to highlight the status of files which are handled and -need no further action. - -@item cvs-need-action -Used to highlight the status of files which still need action. - -@item cvs-marked -Used to highlight the marked file indicator (@samp{*}). - -@item cvs-msg -Used to highlight CVS messages. -@end table - - -@node Bugs, GNU Free Documentation License, Customization, Top -@chapter Bugs (known and unknown) -@cindex Reporting bugs and ideas -@cindex Bugs, how to report them -@cindex Author, how to reach -@cindex Email to the author -@cindex Known bugs -@cindex Bugs, known -@cindex FAQ -@cindex Problems, list of common - -If you find a bug or misfeature, don't hesitate to tell us! Send email -to @email{bug-gnu-emacs@@gnu.org} which is gatewayed to the newsgroup -@samp{gnu.emacs.bugs}. Feature requests should also be sent there. We -prefer discussing one thing at a time. If you find several unrelated -bugs, please report them separately. If you are running PCL-CVS under -XEmacs, you should also send a copy of bug reports to -@email{xemacs-beta@@xemacs.org}. - -If you have problems using PCL-CVS or other questions, send them to -@email{help-gnu-emacs@@gnu.org}, which is gatewayed to the -@samp{gnu.emacs.help} newsgroup. This is a good place to get help, as -is @email{cvs-info@@gnu.org}, gatewayed to @samp{gnu.cvs.help}. - -If you have ideas for improvements, or if you have written some -extensions to this package, we would like to hear from you. We hope that -you find this package useful! - -Below is a partial list of currently known problems with PCL-CVS. - -@table @asis -@item Unexpected output from CVS -Unexpected output from CVS may confuse PCL-CVS. It will create -warning messages in the @samp{*cvs*} buffer alerting you to any parse errors. -If you get these messages, please send a bug report to the email -addresses listed above. Include the contents of the @samp{*cvs*} buffer, the -output of the CVS process (which should be found in the @samp{ *cvs-tmp*} -buffer), and the versions of Emacs, PCL-CVS and CVS you are using. -@end table - -@node GNU Free Documentation License, Function and Variable Index, Bugs, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - - -@node Function and Variable Index, Concept Index, GNU Free Documentation License, Top -@unnumbered Function and Variable Index - -This is an index of all the functions and variables documented in this -manual. - -@printindex fn - -@node Concept Index, Key Index, Function and Variable Index, Top -@unnumbered Concept Index - -This is an index of concepts discussed in this manual. - -@printindex cp - -@node Key Index, , Concept Index, Top -@unnumbered Key Index - -This index includes an entry for each PCL-CVS key sequence documented in -this manual. - -@printindex ky - -@bye diff --git a/doc/misc/pgg.texi b/doc/misc/pgg.texi deleted file mode 100644 index 5aa9b1eb230..00000000000 --- a/doc/misc/pgg.texi +++ /dev/null @@ -1,506 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@include gnus-overrides.texi - -@setfilename ../../info/pgg -@settitle PGG @value{VERSION} - -@set VERSION 0.1 - -@copying -This file describes PGG @value{VERSION}, an Emacs interface to various -PGP implementations. - -Copyright @copyright{} 2001, 2003-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* PGG: (pgg). Emacs interface to various PGP implementations. -@end direntry - -@titlepage -@ifset WEBHACKDEVEL -@title PGG (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title PGG -@end ifclear - -@author by Daiki Ueno -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top PGG - -PGG is an interface library between Emacs -and various tools for secure communication. PGG also provides a simple -user interface to encrypt, decrypt, sign, and verify MIME messages. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: What PGG is. -* Prerequisites:: Complicated stuff you may have to do. -* How to use:: Getting started quickly. -* Architecture:: -* Parsing OpenPGP packets:: -* GNU Free Documentation License:: The license for this documentation. -* Function Index:: -* Variable Index:: -@end menu - -@node Overview -@chapter Overview - -PGG is an interface library between Emacs and various tools for secure -communication. Even though Mailcrypt has similar feature, it does not -deal with detached PGP messages, normally used in PGP/MIME -infrastructure. This was the main reason why I wrote the new library. - -PGP/MIME is an application of MIME Object Security Services (RFC1848). -The standard is documented in RFC2015. - -@node Prerequisites -@chapter Prerequisites - -PGG requires at least one implementation of privacy guard system. -This document assumes that you have already obtained and installed them -and that you are familiar with its basic functions. - -By default, PGG uses GnuPG. If you are new to such a system, I -recommend that you should look over the GNU Privacy Handbook (GPH) -which is available at @uref{http://www.gnupg.org/documentation/}. - -When using GnuPG, we recommend the use of the @code{gpg-agent} -program, which is distributed with versions 2.0 and later of GnuPG. -This is a daemon to manage private keys independently from any -protocol, and provides the most secure way to input and cache your -passphrases (@pxref{Caching passphrase}). By default, PGG will -attempt to use @code{gpg-agent} if it is running. @xref{Invoking -GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}. - -PGG also supports Pretty Good Privacy version 2 or version 5. - -@node How to use -@chapter How to use - -The toplevel interface of this library is quite simple, and only -intended to use with public-key cryptographic operation. - -To use PGG, evaluate following expression at the beginning of your -application program. - -@lisp -(require 'pgg) -@end lisp - -If you want to check existence of pgg.el at runtime, instead you can -list autoload setting for desired functions as follows. - -@lisp -(autoload 'pgg-encrypt-region "pgg" - "Encrypt the current region." t) -(autoload 'pgg-encrypt-symmetric-region "pgg" - "Encrypt the current region with symmetric algorithm." t) -(autoload 'pgg-decrypt-region "pgg" - "Decrypt the current region." t) -(autoload 'pgg-sign-region "pgg" - "Sign the current region." t) -(autoload 'pgg-verify-region "pgg" - "Verify the current region." t) -(autoload 'pgg-insert-key "pgg" - "Insert the ASCII armored public key." t) -(autoload 'pgg-snarf-keys-region "pgg" - "Import public keys in the current region." t) -@end lisp - -@menu -* User Commands:: -* Selecting an implementation:: -* Caching passphrase:: -* Default user identity:: -@end menu - -@node User Commands -@section User Commands - -At this time you can use some cryptographic commands. The behavior of -these commands relies on a fashion of invocation because they are also -intended to be used as library functions. In case you don't have the -signer's public key, for example, the function @code{pgg-verify-region} -fails immediately, but if the function had been called interactively, it -would ask you to retrieve the signer's public key from the server. - -@deffn Command pgg-encrypt-region start end recipients &optional sign passphrase -Encrypt the current region between @var{start} and @var{end} for -@var{recipients}. When the function were called interactively, you -would be asked about the recipients. - -If encryption is successful, it replaces the current region contents (in -the accessible portion) with the resulting data. - -If optional argument @var{sign} is non-@code{nil}, the function is -request to do a combined sign and encrypt. This currently is -confirmed to work with GnuPG, but might not work with PGP or PGP5. - -If optional @var{passphrase} is @code{nil}, the passphrase will be -obtained from the passphrase cache or user. -@end deffn - -@deffn Command pgg-encrypt-symmetric-region &optional start end passphrase -Encrypt the current region between @var{start} and @var{end} using a -symmetric cipher. After invocation you are asked for a passphrase. - -If optional @var{passphrase} is @code{nil}, the passphrase will be -obtained from the passphrase cache or user. - -symmetric-cipher encryption is currently only implemented for GnuPG. -@end deffn - -@deffn Command pgg-decrypt-region start end &optional passphrase -Decrypt the current region between @var{start} and @var{end}. If -decryption is successful, it replaces the current region contents (in -the accessible portion) with the resulting data. - -If optional @var{passphrase} is @code{nil}, the passphrase will be -obtained from the passphrase cache or user. -@end deffn - -@deffn Command pgg-sign-region start end &optional cleartext passphrase -Make the signature from text between @var{start} and @var{end}. If the -optional third argument @var{cleartext} is non-@code{nil}, or the -function is called interactively, it does not create a detached -signature. In such a case, it replaces the current region contents (in -the accessible portion) with the resulting data. - -If optional @var{passphrase} is @code{nil}, the passphrase will be -obtained from the passphrase cache or user. -@end deffn - -@deffn Command pgg-verify-region start end &optional signature fetch -Verify the current region between @var{start} and @var{end}. If the -optional third argument @var{signature} is non-@code{nil}, it is treated -as the detached signature file of the current region. - -If the optional 4th argument @var{fetch} is non-@code{nil}, or the -function is called interactively, we attempt to fetch the signer's -public key from the key server. -@end deffn - -@deffn Command pgg-insert-key -Retrieve the user's public key and insert it as ASCII-armored format. -@end deffn - -@deffn Command pgg-snarf-keys-region start end -Collect public keys in the current region between @var{start} and -@var{end}, and add them into the user's keyring. -@end deffn - -@node Selecting an implementation -@section Selecting an implementation - -Since PGP has a long history and there are a number of PGP -implementations available today, the function which each one has differs -considerably. For example, if you are using GnuPG, you know you can -select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on -the other hand the version 2 of PGP only supports IDEA. - -Which implementation is used is controlled by the @code{pgg-scheme} -variable. If it is @code{nil} (the default), the value of the -@code{pgg-default-scheme} variable will be used instead. - -@defvar pgg-scheme -Force specify the scheme of PGP implementation. The value can be set to -@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{nil}. -@end defvar - -@defvar pgg-default-scheme -The default scheme of PGP implementation. The value should be one of -@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{gpg}. -@end defvar - -@node Caching passphrase -@section Caching passphrase - -When using GnuPG (gpg) as the PGP scheme, we recommend using a program -called @code{gpg-agent} for entering and caching -passphrases@footnote{Actually, @code{gpg-agent} does not cache -passphrases but private keys. On the other hand, from a user's point -of view, this technical difference isn't visible.}. - -@defvar pgg-gpg-use-agent -If non-@code{nil}, attempt to use @code{gpg-agent} whenever possible. -The default is @code{t}. If @code{gpg-agent} is not running, or GnuPG -is not the current PGP scheme, PGG's own passphrase-caching mechanism -is used (see below). -@end defvar - -To use @code{gpg-agent} with PGG, you must first ensure that -@code{gpg-agent} is running. For example, if you are running in the X -Window System, you can do this by putting the following line in your -@file{.xsession} file: - -@smallexample -eval "$(gpg-agent --daemon)" -@end smallexample - -For more details on invoking @code{gpg-agent}, @xref{Invoking -GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}. - -Whenever you perform a PGG operation that requires a GnuPG passphrase, -GnuPG will contact @code{gpg-agent}, which prompts you for the -passphrase. Furthermore, @code{gpg-agent} ``caches'' the result, so -that subsequent uses will not require you to enter the passphrase -again. (This cache usually expires after a certain time has passed; -you can change this using the @code{--default-cache-ttl} option when -invoking @code{gpg-agent}.) - -If you are running in a X Window System environment, @code{gpg-agent} -prompts for a passphrase by opening a graphical window. However, if -you are running Emacs on a text terminal, @code{gpg-agent} has trouble -receiving input from the terminal, since it is being sent to Emacs. -One workaround for this problem is to run @code{gpg-agent} on a -different terminal from Emacs, with the @code{--keep-tty} option; this -tells @code{gpg-agent} use its own terminal to prompt for passphrases. - -When @code{gpg-agent} is not being used, PGG prompts for a passphrase -through Emacs. It also has its own passphrase caching mechanism, -which is controlled by the variable @code{pgg-cache-passphrase} (see -below). - -There is a security risk in handling passphrases through PGG rather -than @code{gpg-agent}. When you enter your passphrase into an Emacs -prompt, it is temporarily stored as a cleartext string in the memory -of the Emacs executable. If the executable memory is swapped to disk, -the root user can, in theory, extract the passphrase from the -swapfile. Furthermore, the swapfile containing the cleartext -passphrase might remain on the disk after the system is discarded or -stolen. @code{gpg-agent} avoids this problem by using certain tricks, -such as memory locking, which have not been implemented in Emacs. - -@defvar pgg-cache-passphrase -If non-@code{nil}, store passphrases. The default value of this -variable is @code{t}. If you are worried about security issues, -however, you could stop the caching of passphrases by setting this -variable to @code{nil}. -@end defvar - -@defvar pgg-passphrase-cache-expiry -Elapsed time for expiration in seconds. -@end defvar - -If your passphrase contains non-ASCII characters, you might need to -specify the coding system to be used to encode your passphrases, since -GnuPG treats them as a byte sequence, not as a character sequence. - -@defvar pgg-passphrase-coding-system -Coding system used to encode passphrase. -@end defvar - -@node Default user identity -@section Default user identity - -The PGP implementation is usually able to select the proper key to use -for signing and decryption, but if you have more than one key, you may -need to specify the key id to use. - -@defvar pgg-default-user-id -User ID of your default identity. It defaults to the value returned -by @samp{(user-login-name)}. You can customize this variable. -@end defvar - -@defvar pgg-gpg-user-id -User ID of the GnuPG default identity. It defaults to @samp{nil}. -This overrides @samp{pgg-default-user-id}. You can customize this -variable. -@end defvar - -@defvar pgg-pgp-user-id -User ID of the PGP 2.x/6.x default identity. It defaults to -@samp{nil}. This overrides @samp{pgg-default-user-id}. You can -customize this variable. -@end defvar - -@defvar pgg-pgp5-user-id -User ID of the PGP 5.x default identity. It defaults to @samp{nil}. -This overrides @samp{pgg-default-user-id}. You can customize this -variable. -@end defvar - -@node Architecture -@chapter Architecture - -PGG introduces the notion of a "scheme of PGP implementation" (used -interchangeably with "scheme" in this document). This term refers to a -singleton object wrapped with the luna object system. - -Since PGG was designed for accessing and developing PGP functionality, -the architecture had to be designed not just for interoperability but -also for extensibility. In this chapter we explore the architecture -while finding out how to write the PGG back end. - -@menu -* Initializing:: -* Back end methods:: -* Getting output:: -@end menu - -@node Initializing -@section Initializing - -A scheme must be initialized before it is used. -It had better guarantee to keep only one instance of a scheme. - -The following code is snipped out of @file{pgg-gpg.el}. Once an -instance of @code{pgg-gpg} scheme is initialized, it's stored to the -variable @code{pgg-scheme-gpg-instance} and will be reused from now on. - -@lisp -(defvar pgg-scheme-gpg-instance nil) - -(defun pgg-make-scheme-gpg () - (or pgg-scheme-gpg-instance - (setq pgg-scheme-gpg-instance - (luna-make-entity 'pgg-scheme-gpg)))) -@end lisp - -The name of the function must follow the -regulation---@code{pgg-make-scheme-} follows the back end name. - -@node Back end methods -@section Back end methods - -In each back end, these methods must be present. The output of these -methods is stored in special buffers (@ref{Getting output}), so that -these methods must tell the status of the execution. - -@deffn Method pgg-scheme-lookup-key scheme string &optional type -Return keys associated with @var{string}. If the optional third -argument @var{type} is non-@code{nil}, it searches from the secret -keyrings. -@end deffn - -@deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase -Encrypt the current region between @var{start} and @var{end} for -@var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign -and encrypt. If encryption is successful, it returns @code{t}, -otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase -Encrypt the current region between @var{start} and @var{end} using a -symmetric cipher and a passphrases. If encryption is successful, it -returns @code{t}, otherwise @code{nil}. This function is currently only -implemented for GnuPG. -@end deffn - -@deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase -Decrypt the current region between @var{start} and @var{end}. If -decryption is successful, it returns @code{t}, otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase -Make the signature from text between @var{start} and @var{end}. If the -optional third argument @var{cleartext} is non-@code{nil}, it does not -create a detached signature. If signing is successful, it returns -@code{t}, otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-verify-region scheme start end &optional signature -Verify the current region between @var{start} and @var{end}. If the -optional third argument @var{signature} is non-@code{nil}, it is treated -as the detached signature of the current region. If the signature is -successfully verified, it returns @code{t}, otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-insert-key scheme -Retrieve the user's public key and insert it as ASCII-armored format. -On success, it returns @code{t}, otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-snarf-keys-region scheme start end -Collect public keys in the current region between @var{start} and -@var{end}, and add them into the user's keyring. -On success, it returns @code{t}, otherwise @code{nil}. -@end deffn - -@node Getting output -@section Getting output - -The output of the back end methods (@ref{Back end methods}) is stored in -special buffers, so that these methods must tell the status of the -execution. - -@defvar pgg-errors-buffer -The standard error output of the execution of the PGP command is stored -here. -@end defvar - -@defvar pgg-output-buffer -The standard output of the execution of the PGP command is stored here. -@end defvar - -@defvar pgg-status-buffer -The rest of status information of the execution of the PGP command is -stored here. -@end defvar - -@node Parsing OpenPGP packets -@chapter Parsing OpenPGP packets - -The format of OpenPGP messages is maintained in order to publish all -necessary information needed to develop interoperable applications. -The standard is documented in RFC 2440. - -PGG has its own parser for the OpenPGP packets. - -@defun pgg-parse-armor string -List the sequence of packets in @var{string}. -@end defun - -@defun pgg-parse-armor-region start end -List the sequence of packets in the current region between @var{start} -and @var{end}. -@end defun - -@defvar pgg-ignore-packet-checksum -If non-@code{nil}, don't check the checksum of the packets. -@end defvar - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index -@unnumbered Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@bye - -@c End: diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi deleted file mode 100644 index 0174c3fa87f..00000000000 --- a/doc/misc/rcirc.texi +++ /dev/null @@ -1,950 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename ../../info/rcirc -@settitle rcirc Manual -@c %**end of header - -@copying -Copyright @copyright{} 2006-2012 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license is -included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* Rcirc: (rcirc). Internet Relay Chat (IRC) client. -@end direntry - -@titlepage -@title rcirc Manual -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Basics, (dir), (dir) -@top rcirc Manual - -@code{rcirc} is an Emacs IRC client. - -IRC (Internet Relay Chat) is a multi-user chat protocol. Users -communicate with each other in real-time. Communication occurs both in -topic channels which are collections of many users, or privately, with -just one other user. - -@insertcopying - -@end ifnottex - -@menu -* Basics:: -* Reference:: -* Fighting Information Overload:: -* Hacking and Tweaking:: -* GNU Free Documentation License:: -* Key Index:: -* Variable Index:: -* Index:: - -@detailmenu - --- The Detailed Node Listing --- - -Basics - -* Internet Relay Chat:: -* Getting started with rcirc:: - -Reference - -* rcirc commands:: -* Useful IRC commands:: -* Configuration:: - -Fighting Information Overload - -* Channels:: -* People:: -* Keywords:: -* Notices:: - -Hacking and Tweaking - -* Skipping /away messages using handlers:: -* Using fly spell mode:: -* Scrolling conservatively:: -* Changing the time stamp format:: -* Defining a new command:: -* Reconnecting after you have lost the connection:: - -@end detailmenu -@end menu - -@node Basics, Reference, Top, Top -@chapter Basics - -This chapter contains a brief introduction to IRC (Internet Relay Chat), -and a quick tutorial on @code{rcirc}. - -@menu -* Internet Relay Chat:: -* Getting started with rcirc:: -@end menu - -@node Internet Relay Chat, Getting started with rcirc, Basics, Basics -@section Internet Relay Chat -@cindex internet relay chat -@cindex irc - -@cindex channel -@dfn{Internet Relay Chat} (IRC) is a form of instant communication over the -Internet. It is mainly designed for group (many-to-many) communication -in discussion forums called channels, but also allows one-to-one -communication. - -@cindex instant messaging, comparison -@cindex server -@cindex network -Contrary to most Instant Messenger (IM) systems, users usually don't -connect to a central server. Instead, users connect to a random -server in a network, and servers relay messages from one to the next. - -Here's a typical example: - -@cindex redirection to random servers -When you connect to the Freenode network -(@code{http://freenode.net/}), you point your IRC client at the -server @code{irc.freenode.net}. That server will redirect your client -to a random server on the network, such as @code{zelazny.freenode.net}. - -@cindex channel name -@cindex # starts a channel name -Once you're connected, you can send messages to all other users -connected to the same network, and you can join all channels on the same -network. You might join the @code{#emacs} and the @code{#rcirc} -channels, for example. (Typically, channel names begin with a hash -character.) - -Once you have joined a channel, anything you type will be broadcast to -all the other users on the same channel. - -@cindex addressing other people -@cindex other people, addressing them -@cindex talk to other people -If you want to address someone specifically, for example as an answer to -a question, it is customary to prefix the message with the nick followed -by a colon, like this: - -@example -deego: fsbot rules! -@end example - -@cindex nick completion -@cindex completion of nicks -@kindex TAB -Since this is so common, you can use @key{TAB} to do nick completion. - -@node Getting started with rcirc, , Internet Relay Chat, Basics -@section Getting started with rcirc -@cindex getting started -@cindex connecting to a server - -@cindex irc command -Use the command @kbd{M-x irc} to connect using the defaults. -@xref{Configuration}, if you want to change the defaults. - -Use @kbd{C-u M-x irc} if you don't want to use the defaults, eg. if you -want to connect to a different network, or connect to the same network -using a different nick. This will prompt you for four things: - -@table @asis -@cindex server, connecting -@cindex Freenode network -@item IRC Server -What server do you want to connect to? All the servers in a particular -network are equivalent. Some networks use a round-robin system where a -single server redirects new connections to a random server in the -network. @code{irc.freenode.net} is such a server for the Freenode -network. Freenode provides the network ``for the Free and Open Source -Software communities, for not-for-profit organizations and for related -communities and organizations.'' - -@cindex port, connecting -@cindex 6667, default IRC port -@item IRC Port -All network connections require a port. Just as web servers and clients -use port 80 per default, IRC uses port 6667 per default. You rarely -have to use a different port. - -@cindex nick, connecting -@cindex changing nick -@cindex name changes -@item IRC Nick -@vindex user-login-name -Every users needs a handle on-line. You will automatically be assigned -a slightly different nick if your chosen nick is already in use. If -your @code{user-login-name} is @code{alex}, and this nick is already -in use, you might for example get assigned the nick @code{alex`}. - -@cindex channels, connecting -@cindex initial channels -@cindex startup channels -@item IRC Channels -A space separated list of channels you want to join when connecting. -You don't need to join any channels, if you just want to have one-to-one -conversations with friends on the same network. If you're new to the -Freenode network, join @code{#emacs}, the channel about all things -Emacs, or join @code{#rcirc}, the channel about @code{rcirc}. -@end table - -@cindex server buffer -When you have answered these questions, @code{rcirc} will create a server -buffer, which will be named something like @code{*irc.freenode.net*}, -and a channel buffer for each of the channels you wanted to join. - -@kindex RET -@cindex talking -@cindex communicating -To talk in a channel, just type what you want to say in a channel -buffer, and press @key{RET}. - -@kindex C-c C-c -@cindex multiline messages -@cindex messages, multiple lines -@cindex pasting multiple lines -@cindex edit message before sending -If you want to paste multiple lines, such as source code, you can use -@kbd{C-c C-c} to edit your message in a separate buffer. Use @kbd{C-c -C-c} to finish editing. You still need to press @key{RET} to send it, -though. Generally, IRC users don't like people pasting more than around -four lines of code, so use with care. - -@comment This section copied from the Channels section. -@comment All index markers should point to the original! -Once you are connected to multiple channels, or once you've turned you -attention to other buffers in Emacs, you probably want to be notified -of any activity in channels not currently visible. All you need to do -is switch channel tracking on using @kbd{M-x rcirc-track-minor-mode}. -To make this permanent, add the following to your init file: - -@example -(rcirc-track-minor-mode 1) -@end example - -Use @kbd{C-c C-@key{SPC}} to switch to these buffers. - -@node Reference, Fighting Information Overload, Basics, Top -@chapter Reference -@cindex reference - -This is the reference section of the manual. It is not complete. For -complete listings of @code{rcirc} features, use Emacs built-in -documentation. - -@menu -* rcirc commands:: -* Useful IRC commands:: -* Configuration:: -@end menu - -@node rcirc commands, Useful IRC commands, Reference, Reference -@section rcirc commands -@cindex rcirc commands -@cindex commands - -@kindex C-h m -This is a list of commands that you may use in @code{rcirc}. It is not -complete. For a complete listing, press @kbd{C-h m} in an @code{rcirc} -buffer. - -In addition to using regular Emacs key bindings, you can call them by -typing them into an @code{rcirc} buffer. - -@cindex call commands -@cindex typing commands -@cindex commands -For instance, instead of using the command @kbd{C-c C-j} to join a new -channel, you may type this in an @code{rcirc} buffer, and press @key{RET}: - -@example -/join #emacs -@end example - -@cindex / starts a command -@cindex messages starting with a slash disappear -@cindex disappearing messages if starting with a slash -@cindex slash hides message -This is why you cannot start a message with a slash. You will have to -precede the command with a space, or rewrite your message in order to -send it to a channel. - -@cindex multiple words as parameters -@cindex string delimiters -@cindex quotes -@cindex double-quotes -Many commands take parameters. IRC commands usually ignore string -delimiters. Neither quote nor double-quote have special meanings in -IRC. - -@example -/nick "alex schroeder" -@end example - -This will try to change your nick to @code{"alex}. Usually this will -fail because the double quote character is not a valid character for -nicks. - -@cindex case insensitive commands -These commands are case insensitive. - -@cindex new command -@cindex unknown command -@cindex command unknown -If a command isn't known by @code{rcirc}, it will simply be sent along to the -server. There is a list of some useful commands like that in the next -section. - -@table @kbd -@item C-c C-j -@kindex C-c C-j -@cindex /join -@cindex join channels -@cindex other channels -@cindex rooms, joining -@cindex discussion, joining -This joins a channel such as @code{#rcirc} or @code{#emacs}. On most -networks, anybody can create new channels. If you want to talk with -some friends, for example, all you have to do is agree on a valid -channel name and join that channel. (Also @code{/join #emacs}.) - -@item C-c C-p -@kindex C-c C-p -@cindex /part -@cindex part a channel -@cindex leave a channel -@cindex disconnect from a channel -@cindex stop talking on a channel -@cindex kill channel buffer -This leaves the current channel. You can optionally provide a reason -for parting. When you kill a channel buffer, you automatically part the -corresponding channel. (Also @code{/part you are too weird!}.) - -@item C-c C-r -@kindex C-c C-r -@cindex /nick -@cindex change name -@cindex nick changing -@cindex rename yourself -@cindex other name -This changes your nick to some other name. Your nick must be unique -across the network. Most networks don't allow too many nick changes in -quick succession, and have restrictions on the valid characters in nick -names. (Also @code{/nick alex-test}) - -@item C-c C-w -@kindex C-c C-w -@cindex /whois -@cindex who are these people -@cindex identifying people -@cindex channels other people are on -@cindex what channels people are on -Gives you some basic information about a nick. This often includes what -other channels people are on. (Also @code{/whois fsbot}.) - -@item C-c C-q -@kindex C-c C-q -@cindex /query -@cindex starting a private conversation -@cindex one-to-one conversation -@cindex talk privately -@cindex private conversation -@cindex contact one person only -@cindex query a person -Starts a one-to-one conversation with another person on the same -network. A new buffer will be created for this conversation. It works -like a channel with only two members. (Also @code{/query fsbot}.) - -@item C-c @key{RET} -@kindex C-c RET -@cindex /msg -@cindex single message -@cindex message sending -This sends a single message to a nick. Like with @kbd{C-c C-q}, a new -buffer is created, where the response from the other party will show -up. (Also @code{/msg nickserv identify secret}.) - -@item C-c C-x -@kindex C-c C-x -@cindex /quit -@cindex quit -@cindex disconnect -@cindex kill connection -@cindex connection end -@cindex part all channels -@cindex end connection -@cindex server buffer killing -@cindex reason for quitting -This disconnects from the server and parts all channels. You can -optionally provide a reason for quitting. When you kill the server -buffer, you automatically quit the server and part all channels. (Also -@code{/quit ZZZzzz...}.) -@end table - -@node Useful IRC commands, Configuration, rcirc commands, Reference -@section Useful IRC commands -@cindex irc commands -@cindex commands - -As mentioned, if a command isn't known by @code{rcirc}, it will simply be sent -along to the server. Some such commands are available on nearly all IRC -servers, such as: - -@table @code -@item /away -@cindex /away -@cindex away status -@cindex pause status -@cindex unavailable status -@cindex set away status -This sets your status as ``being away'' if you provide a reason, or sets -your status as ``being back'' if you do not. People can use the -@kbd{C-c C-w} command to check your status. Example: @code{/away food}. -@end table - -@cindex irc resources -@cindex help about irc -Typical IRC servers implement many more commands. You can read more -about the fantastic world of IRC online at -@uref{http://www.irchelp.org/, the Internet Relay Chat (IRC) help -archive}. - -@node Configuration, , Useful IRC commands, Reference -@section Configuration -@cindex configuring rcirc - -These are some variables you can change to configure @code{rcirc} to your -liking. - -@table @code -@item rcirc-server-alist -@vindex rcirc-server-alist -@cindex channels, configuration -@cindex initial channels, configuration -@cindex startup channels, configuration -@cindex servers, configuration -@cindex initial servers, configuration -@cindex startup servers, configuration -This variable contains an alist of servers to connect to by default -and the keywords parameters to use. The keyword parameters are -optional. If you don't provide any, the defaults as documented below -will be used. - -The most important parameter is the @code{:channels} parameter. It -controls which channels you will join by default as soon as you are -connected to the server. - -Here's an example of how to set it: - -@example -(add-to-list 'rcirc-server-alist - '("otherworlders.org" - :channels ("#FUDGE" "#game-design"))) -@end example - -By default you will be connected to the @code{rcirc} support channel: -@code{#rcirc} on @code{irc.freenode.net}. - -@table @code -@item :nick -This overrides @code{rcirc-default-nick}. - -@item :port -This overrides @code{rcirc-default-port}. - -@item :user-name -This overrides @code{rcirc-default-user-name}. - -@item :full-name -This overrides @code{rcirc-default-full-name}. - -@item :channels -This describes which channels to join when connecting to the server. -If absent, no channels will be connected to automatically. - -@end table - -@item rcirc-default-nick -@vindex rcirc-default-nick -This variable is used for the default nick. It defaults to the login -name returned by @code{user-login-name}. - -@example -(setq rcirc-default-nick "kensanata") -@end example - -@item rcirc-default-port -@vindex rcirc-default-port -@cindex port -This variable contains the default port to connect to. It is 6667 by -default and rarely needs changing. - -@item rcirc-default-user-name -@vindex rcirc-default-user-name -@cindex user name -This variable contains the default user name to report to the server. -It defaults to the login name returned by @code{user-login-name}, just -like @code{rcirc-default-nick}. - -@item rcirc-default-full-name -@vindex rcirc-default-full-name -@cindex full name -@cindex real name -@cindex surname -This variable is used to set your ``real name'' on IRC. It defaults -to the name returned by @code{user-full-name}. If you want to hide -your full name, you might want to set it to some pseudonym. - -@example -(setq rcirc-default-full-name "Curious Minds Want To Know") -@end example - -@item rcirc-authinfo -@vindex rcirc-authinfo -@cindex authentication -@cindex identification -@cindex nickserv -@cindex login -This variable is an alist used to automatically identify yourself on -networks. Each sublist starts with a regular expression that is -compared to the server address you're connecting to. The second -element in the list is a symbol representing the method to use, -followed by the arguments this method requires. - -Here is an example to illustrate how you would set it: - -@example -(setq rcirc-authinfo - '(("freenode" nickserv "bob" "p455w0rd") - ("freenode" chanserv "bob" "#bobland" "passwd99") - ("bitlbee" bitlbee "robert" "sekrit"))) -@end example - -And here are the valid method symbols and the arguments they require: - -@table @code -@item nickserv -@cindex nickserv authentication -Use this symbol if you need to identify yourself as follows when -connecting to a network: @code{/msg nickserv identify secret}. The -necessary arguments are the nickname you want to use this for, and the -password to use. - -Before you can use this method, you will have to register your nick and -pick a password for it. Contact @code{nickserv} and check out the -details. (Using @code{/msg nickserv help}, for example.) - -@item chanserv -@cindex chanserv authentication -Use this symbol if you need to identify yourself as follows if you want -to join a particular channel: @code{/msg chanserv identify #underground -secret}. The necessary arguments are the nickname and channel you want -to use this for, and the password to use. - -Before you can use this method, a channel contact must tell you about -the password to use. Contact @code{chanserv} and check out the details. -(Using @code{/msg chanserv help}, for example.) - -@item bitlbee -@cindex bitlbee authentication -Use this symbol if you need to identify yourself in the Bitlbee channel -as follows: @code{identify secret}. The necessary arguments are the -nickname you want to use this for, and the password to use. - -@cindex gateway to other IM services -@cindex instant messaging, other services -@cindex Jabber -@cindex AIM -@cindex ICQ -@cindex MSN -@cindex Yahoo! -Bitlbee acts like an IRC server, but in fact it is a gateway to a lot of -other instant messaging services. You can either install Bitlbee -locally or use a public Bitlbee server. There, you need to create an -account with a password. This is the nick and password you need to -provide for the bitlbee authentication method. - -Later, you will tell Bitlbee about your accounts and passwords on all -the other instant messaging services, and Bitlbee will log you in. All -@code{rcirc} needs to know, is the login to your Bitlbee account. Don't -confuse the Bitlbee account with all the other accounts. - -@end table - -@end table - -@node Fighting Information Overload, Hacking and Tweaking, Reference, Top -@chapter Fighting Information Overload -@cindex information overload - -This is the section of the manual that caters to the busy person -online. There are support channels with several hundred people in -them. Trying to follow a conversation in these channels can be a -daunting task. This chapters tells you how @code{rcirc} can help. - -@menu -* Channels:: -* People:: -* Keywords:: -* Notices:: -@end menu - -@node Channels, People, Fighting Information Overload, Fighting Information Overload -@section Channels -@cindex channels -@cindex modeline - -@comment This section copied to the Getting started with rcirc section -@kindex C-c C-SPC -@vindex rcirc-track-minor-mode -@cindex switching channels -@cindex tracking activity -@cindex active channel -@cindex abbreviated channel names -@cindex modeline tracks activity -Most people want a notification when something is said on a channel they -have joined, particularly if they have been addressed directly. There -is a global minor mode that will do this kind of tracking for you. All -you need to do is switch it on using @kbd{M-x rcirc-track-minor-mode}. -To make this permanent, add the following to your init file: - -@example -(rcirc-track-minor-mode 1) -@end example - -When other people say things in buffers that are currently buried (no -window is showing them), the mode line will now show you the abbreviated -channel or nick name. Use @kbd{C-c C-@key{SPC}} to switch to these -buffers. - -@vindex rcirc-mode-hook -If you prefer not to load @code{rcirc} immediately, you can delay the -activation of this mode: - -@example -(add-hook 'rcirc-mode-hook - (lambda () - (rcirc-track-minor-mode 1))) -@end example - -@cindex busy channels -If you've joined a very active support channel, tracking activity is -no longer useful. The channel will be always active. Switching to -active channels using @kbd{C-c C-@key{SPC}} no longer works as -expected. - -@kindex C-c C-l -@cindex low priority channels -The solution is to mark this channel as a low priority channel. -Use @kbd{C-c C-l} to make the current channel a low-priority channel. -Low priority channels have the modeline indicator ``LowPri''. -@kbd{C-c C-@key{SPC}} will not switch to low priority channels unless -you use the @kbd{C-u} prefix. - -@kindex C-c TAB -@cindex ignored channels -If you prefer a channel to never show up in the modeline, then you -have to ignore it. Use @kbd{C-c @key{TAB}} to ignore the current -channel. - -@node People, Keywords, Channels, Fighting Information Overload -@section People -@cindex people, how to ignore -@cindex nicks, how to ignore -@cindex friends -@cindex buddies -@cindex trolls - -The most important command available to the discerning IRC user is -@code{/ignore}. It's the big equalizer online: If people aggravate -you, just ignore them. - -This is of course a crude all-or-nothing solution. Fear not, -@code{rcirc} offers alternatives: You can ``brighten'' your buddies -and ``dim'' certain other nicks that you don't want to ignore -altogether. - -@table @code -@item /ignore -@cindex /ignore -@cindex ignoring other people -@cindex trolls, ignoring -@cindex hide some posts -@cindex idiots online -This command toggles the ignore status of a nick, if you provide one. -If you don't provide a nick, the command lists all the nicks you are -ignoring. All messages by ignored nicks are---you guessed it---ignored. -Since only ``operators'' can kick people from channels, the -ignore command is often the only way to deal with some of the more -obnoxious fellows online. Example: @code{/ignore rudybot}. - -@item /bright -@cindex /bright -@cindex highlight other people -@cindex friends, highlight -@cindex buddies, highlight -@cindex nicks, highlight -@cindex brighten nicks -This command toggles the bright status of a nick, if you provide one. -If you don't provide a nick, the command lists all the ``brightened'' -nicks. All messages by brightened nicks are---you guessed -it---brightened. Use this for your friends. Example: @code{/bright -rcy}. - -@item /dim -@cindex /dim -@cindex soft-ignore other people -@cindex obnoxious people online -@cindex rabble online -This command toggles the dim status of a nick, if you provide one. If -you don't provide a nick, the command lists all the ``dimmed'' nicks. -All messages by dimmed nicks are---you guessed it---dimmed. Use this -for boring people and bots. If you are tracking channel activity, -messages by dimmed nicks will not register as activity. Example: -@code{/dim fsbot}. -@end table - - -@node Keywords, Notices, People, Fighting Information Overload -@section Keywords -@cindex keywords - -On a busy channel, you might want to ignore all activity (using -@kbd{C-c @key{TAB}}) and just watch for certain keywords. The -following command allows you to highlight certain keywords: - -@table @code -@item /keyword -@cindex /keyword -This command toggles the highlighting of a keyword, if you provide -one. If you don't provide a keyword, the current keywords are -listed. Example: @code{/keyword manual}. -@end table - -@node Notices, , Keywords, Fighting Information Overload -@section Notices -@cindex part notices, how to omit -@cindex join notices, how to omit -@cindex quit notices, how to omit -@cindex nick notices, how to omit - -@kindex C-c C-o -@cindex low priority channels -In busy channels you might not be interested in all the joining, -parting, quitting, and renaming that goes on. You can omit those -notices using @kbd{C-c C-o}. - -@vindex rcirc-omit-responses -@cindex away notices, how to omit -You can control which notices get omitted via the -@code{rcirc-omit-responses} variable. Here's an example of how to -omit away messages: - -@example -(setq rcirc-omit-responses '("JOIN" "PART" "QUIT" "NICK" "AWAY)) -@end example - -@vindex rcirc-omit-threshold -Notice that these messages will not be omitted if the nick in question -has recently been active. After all, you don't want to continue a -conversation with somebody who just left. That's why @code{rcirc} -checks recent lines in the buffer to figure out if a nick has been -active and only omits a message if the nick has not been active. The -window @code{rcirc} considers is controlled by the -@code{rcirc-omit-threshold} variable. - -@node Hacking and Tweaking, GNU Free Documentation License, Fighting Information Overload, Top -@chapter Hacking and Tweaking -@cindex hacking and tweaking - -Here are some examples of stuff you can do to configure @code{rcirc}. - -@menu -* Skipping /away messages using handlers:: -* Using fly spell mode:: -* Scrolling conservatively:: -* Changing the time stamp format:: -* Defining a new command:: -* Reconnecting after you have lost the connection:: -@end menu - -@node Skipping /away messages using handlers, Using fly spell mode, Hacking and Tweaking, Hacking and Tweaking -@section Skipping @code{/away} messages using handlers -@cindex /away messages - -@cindex handlers -@cindex status codes -The IRC protocol specifies how certain events are signaled from server -to client. These events have numbers and are dealt with using so-called -handlers. You can override existing handlers by exploiting the naming -convention adopted for @code{rcirc}. - -Here's how to stop @code{rcirc} from printing @code{/away} messages. -Since @code{rcirc} doesn't define a 301 handler, you don't need to -require @code{rcirc} before defining the handler: - -@example -(defun rcirc-handler-301 (process cmd sender args) - "/away message handler.") -@end example - -@node Using fly spell mode, Scrolling conservatively, Skipping /away messages using handlers, Hacking and Tweaking -@section Using fly spell mode -@cindex fly spell -@cindex spelling -@cindex spell-checking as you type -@cindex automatic spelling -@vindex rcirc-mode-hook - -The following code activates Fly Spell Mode -for @code{rcirc} buffers: - -@example -(add-hook 'rcirc-mode-hook (lambda () - (flyspell-mode 1))) -@end example - -@xref{Spelling, , Flyspell mode, emacs, The GNU Emacs Manual}, -for details. - -@node Scrolling conservatively, Changing the time stamp format, Using fly spell mode, Hacking and Tweaking -@section Scrolling conservatively -@cindex input line -@cindex scrolling -@vindex scroll-conservatively -@vindex rcirc-mode-hook - -IRC buffers are constantly growing. If you want to see as much as -possible at all times, you would want the prompt at the bottom of the -window when possible. The following snippet uses a local value for -@code{scroll-conservatively} to achieve this: - -@example -(add-hook 'rcirc-mode-hook - (lambda () - (set (make-local-variable 'scroll-conservatively) - 8192))) -@end example - -@xref{Scrolling, , Scrolling conservatively, emacs, The GNU Emacs -Manual}, for details. - -@node Changing the time stamp format, Defining a new command, Scrolling conservatively, Hacking and Tweaking -@section Changing the time stamp format -@cindex time stamp -@cindex date time -@cindex format time stamp -@vindex rcirc-time-format - -@code{rcirc-time-format} is the format used for the time stamp. Here's -how to include the date in the time stamp: - -@example -(setq rcirc-time-format "%Y-%m-%d %H:%M ") -@end example - -@node Defining a new command, Reconnecting after you have lost the connection, Changing the time stamp format, Hacking and Tweaking -@section Defining a new command -@cindex defining commands -@cindex commands, defining -@cindex new commands, defining - -Here's a simple new command, @code{/sv}. With it, you can boast about -your IRC client. It shows how you can use @code{defun-rcirc-command} to -define new commands. - -We're waiting for the definition of this command until @code{rcirc} is loaded -because @code{defun-rcirc-command} is not yet available, and without -@code{rcirc} loaded, the command wouldn't do us much good anyway. - -@smallexample -(eval-after-load 'rcirc - '(defun-rcirc-command sv (arg) - "Boast about rcirc." - (interactive "i") - (rcirc-send-message process target - (concat "I use " rcirc-id-string)))) -@end smallexample - -@node Reconnecting after you have lost the connection, , Defining a new command, Hacking and Tweaking -@section Reconnecting after you have lost the connection -@cindex reconnecting -@cindex disconnecting servers, reconnecting - -If you're chatting from a laptop, then you might be familiar with this -problem: When your laptop falls asleep and wakes up later, your IRC -client doesn't realize that it has been disconnected. It takes several -minutes until the client decides that the connection has in fact been -lost. The simple solution is to use @kbd{M-x rcirc}. The problem is -that this opens an @emph{additional} connection, so you'll have two -copies of every channel buffer --- one dead and one live. - -The real answer, therefore, is a @code{/reconnect} command: - -@smallexample -(eval-after-load 'rcirc - '(defun-rcirc-command reconnect (arg) - "Reconnect the server process." - (interactive "i") - (unless process - (error "There's no process for this target")) - (let* ((server (car (process-contact process))) - (port (process-contact process :service)) - (nick (rcirc-nick process)) - channels query-buffers) - (dolist (buf (buffer-list)) - (with-current-buffer buf - (when (eq process (rcirc-buffer-process)) - (remove-hook 'change-major-mode-hook - 'rcirc-change-major-mode-hook) - (if (rcirc-channel-p rcirc-target) - (setq channels (cons rcirc-target channels)) - (setq query-buffers (cons buf query-buffers)))))) - (delete-process process) - (rcirc-connect server port nick - rcirc-default-user-name - rcirc-default-full-name - channels)))) -@end smallexample - -@node GNU Free Documentation License, Key Index, Hacking and Tweaking, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Key Index, Variable Index, GNU Free Documentation License, Top -@unnumbered Key Index -@printindex ky - -@node Variable Index, Index, Key Index, Top -@unnumbered Variable Index -@printindex vr - -@node Index, , Variable Index, Top -@unnumbered Index -@printindex cp - -@bye diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi deleted file mode 100644 index 69092093af8..00000000000 --- a/doc/misc/reftex.texi +++ /dev/null @@ -1,5892 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/reftex -@settitle RefTeX User Manual -@synindex ky cp -@syncodeindex vr cp -@syncodeindex fn cp - -@c Version and Contact Info -@set VERSION 4.31 -@set EDITION 4.31 -@set DATE February 2006 -@set AUCTEXSITE @uref{http://www.gnu.org/software/auctex/,AUCTeX distribution site} -@set MAINTAINERSITE @uref{http://www.gnu.org/software/auctex/reftex.html,Ref@TeX{} web page} -@set MAINTAINERCONTACT @uref{mailto:auctex-devel@@gnu.org,contact the maintainers} -@set MAINTAINER the AUC@TeX{} project -@set SUPPORTADDRESS AUC@TeX{} user mailing list (@email{auctex@@gnu.org}) -@set DEVELADDRESS AUC@TeX{} developer mailing list (@email{auctex-devel@@gnu.org}) -@set BUGADDRESS AUC@TeX{} bug mailing list (@email{bug-auctex@@gnu.org}) -@set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site} -@c %**end of header - -@copying -This file documents @b{Ref@TeX{}}, a package to do labels, references, -citations and indices for LaTeX documents with Emacs. - -This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for -@b{Ref@TeX{}} @value{VERSION} - -Copyright @copyright{} 1997-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* RefTeX: (reftex). Emacs support for LaTeX cross-references - and citations. -@end direntry - -@finalout - -@c Macro definitions - -@c Subheadings inside a table. Need a difference between info and the rest. -@macro tablesubheading{text} -@ifinfo -@subsubheading \text\ -@end ifinfo -@ifnotinfo -@item @b{\text\} -@end ifnotinfo -@end macro - -@titlepage -@title Ref@TeX{} User Manual -@subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs -@subtitle Edition @value{EDITION}, @value{DATE} - -@author by Carsten Dominik -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@ifnottex -@node Top,,,(dir) -@top RefTeX - -@b{Ref@TeX{}} is a package for managing Labels, References, -Citations and index entries with GNU Emacs. - -Don't be discouraged by the size of this manual, which covers -@b{Ref@TeX{}} in great depth. All you need to know to use -@b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a -Nutshell}). You can go back later to other parts of this document when -needed. - -@insertcopying - -@menu -* Introduction:: Quick-Start information. - -* Table of Contents:: A Tool to move around quickly. -* Labels and References:: Creating and referencing labels. -* Citations:: Creating Citations. -* Index Support:: Creating and Checking Index Entries. -* Viewing Cross-References:: Who references or cites what? - -* RefTeXs Menu:: The Ref menu in the menubar. -* Key Bindings:: The default key bindings. -* Faces:: Fontification of RefTeX's buffers. -* Multifile Documents:: Document spread over many files. -* Language Support:: How to support other languages. -* Finding Files:: Included TeX files and BibTeX .bib files. -* AUCTeX:: Cooperation with AUCTeX. -* Optimizations:: When RefTeX is too slow. -* Problems and Work-Arounds:: First Aid. -* Imprint:: Author, Web-site, Thanks - -* Commands:: Which are the available commands. -* Options:: How to extend and configure RefTeX. -* Keymaps and Hooks:: For customization. -* Changes:: A List of recent changes to RefTeX. -* GNU Free Documentation License:: The license for this documentation. - -The Index - -* Index:: The full index. - -@detailmenu - -Introduction - -* Installation:: How to install and activate RefTeX. -* RefTeX in a Nutshell:: A brief summary and quick guide. - -Labels and References - -* Creating Labels:: -* Referencing Labels:: -* Builtin Label Environments:: The environments RefTeX knows about. -* Defining Label Environments:: ... and environments it doesn't. -* Reference Info:: View the label corresponding to a \ref. -* xr (LaTeX package):: References to external documents. -* varioref (LaTeX package):: How to create \vref instead of \ref. -* fancyref (LaTeX package):: How to create \fref instead of \ref. - -Defining Label Environments - -* Theorem and Axiom:: Defined with @code{\newenvironment}. -* Quick Equation:: When a macro sets the label type. -* Figure Wrapper:: When a macro argument is a label. -* Adding Magic Words:: Other words for other languages. -* Using \eqref:: How to switch to this AMS-LaTeX macro. -* Non-Standard Environments:: Environments without \begin and \end -* Putting it Together:: How to combine many entries. - -Citations - -* Creating Citations:: How to create them. -* Citation Styles:: Natbib, Harvard, Chicago and Co. -* Citation Info:: View the corresponding database entry. -* Chapterbib and Bibunits:: Multiple bibliographies in a Document. -* Citations Outside LaTeX:: How to make citations in Emails etc. -* BibTeX Database Subsets:: Extract parts of a big database. - -Index Support - -* Creating Index Entries:: Macros and completion of entries. -* The Index Phrases File:: A special file for global indexing. -* Displaying and Editing the Index:: The index editor. -* Builtin Index Macros:: The index macros RefTeX knows about. -* Defining Index Macros:: ... and macros it doesn't. - -The Index Phrases File - -* Collecting Phrases:: Collecting from document or external. -* Consistency Checks:: Check for duplicates etc. -* Global Indexing:: The interactive indexing process. - -AUCTeX - -* AUCTeX-RefTeX Interface:: How both packages work together -* Style Files:: AUCTeX's style files can support RefTeX -* Bib-Cite:: Hypertext reading of a document - -Options, Keymaps, Hooks - -* Options (Table of Contents):: -* Options (Defining Label Environments):: -* Options (Creating Labels):: -* Options (Referencing Labels):: -* Options (Creating Citations):: -* Options (Index Support):: -* Options (Viewing Cross-References):: -* Options (Finding Files):: -* Options (Optimizations):: -* Options (Fontification):: -* Options (Misc):: - -@end detailmenu -@end menu - -@end ifnottex - -@node Introduction, Table of Contents, , Top -@chapter Introduction -@cindex Introduction - -@b{Ref@TeX{}} is a specialized package for support of labels, -references, citations, and the index in LaTeX. @b{Ref@TeX{}} wraps -itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite}, -and @code{\index}. Using these macros usually requires looking up -different parts of the document and searching through BibTeX database -files. @b{Ref@TeX{}} automates these time--consuming tasks almost -entirely. It also provides functions to display the structure of a -document and to move around in this structure quickly. - -@iftex -Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}} -in great depth. All you need to know to use @b{Ref@TeX{}} can be -summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go -back later to other parts of this document when needed. -@end iftex - -@xref{Imprint}, for information about who to contact for help, bug -reports or suggestions. - -@menu -* Installation:: How to install and activate RefTeX. -* RefTeX in a Nutshell:: A brief summary and quick guide. -@end menu - -@node Installation, RefTeX in a Nutshell, , Introduction -@section Installation -@cindex Installation - -@b{Ref@TeX{}} is bundled and pre--installed with Emacs since version -20.2. It was also bundled and pre--installed with XEmacs 19.16--20.x. -XEmacs 21.x users want to install the corresponding plug-in package -which is available from the @value{XEMACSFTP}. See the XEmacs 21.x -documentation on package installation for details. - -Users of earlier Emacs distributions (including Emacs 19) can get a copy -of the @b{Ref@TeX{}} distribution from the maintainers web-page. -@xref{Imprint}, for more information. - -@section Environment -@cindex Finding files -@cindex BibTeX database files, not found -@cindex TeX files, not found -@cindex @code{TEXINPUTS}, environment variable -@cindex @code{BIBINPUTS}, environment variable - -@b{Ref@TeX{}} needs to access all files which are part of a multifile -document, and the BibTeX database files requested by the -@code{\bibliography} command. To find these files, @b{Ref@TeX{}} will -require a search path, i.e. a list of directories to check. Normally -this list is stored in the environment variables @code{TEXINPUTS} and -@code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on some -systems these variables do not contain the full search path. If -@b{Ref@TeX{}} does not work for you because it cannot find some files, -read @ref{Finding Files}. - -@section Entering @b{Ref@TeX{}} Mode - -@findex turn-on-reftex -@findex reftex-mode -@vindex LaTeX-mode-hook -@vindex latex-mode-hook -To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use -@kbd{M-x reftex-mode}. To turn on @b{Ref@TeX{}} Mode for all LaTeX -files, add the following lines to your @file{.emacs} file: - -@example -(add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode -(add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode -@end example - -@page -@node RefTeX in a Nutshell, , Installation, Introduction -@section @b{Ref@TeX{}} in a Nutshell -@cindex Quick-Start -@cindex Getting Started -@cindex RefTeX in a Nutshell -@cindex Nutshell, RefTeX in a - -@enumerate -@item -@b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show -a table of contents of the document. This buffer can display sections, -labels and index entries defined in the document. From the buffer, you -can jump quickly to every part of your document. Press @kbd{?} to get -help. - -@item -@b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels -and to find the correct key for references quickly. It distinguishes -labels for different environments, knows about all standard -environments (and many others), and can be configured to recognize any -additional labeled environments you have defined yourself (variable -@code{reftex-label-alist}). - -@itemize @bullet -@item -@b{Creating Labels}@* -Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point. -@b{Ref@TeX{}} will either -@itemize @minus -@item -derive a label from context (default for section labels) -@item -prompt for a label string (default for figures and tables) or -@item -insert a simple label made of a prefix and a number (all other -environments) -@end itemize -@noindent -Which labels are created how is configurable with the variable -@code{reftex-insert-label-flags}. - -@item -@b{Referencing Labels}@* To make a reference, type @kbd{C-c )} -(@code{reftex-reference}). This shows an outline of the document with -all labels of a certain type (figure, equation,...) and some label -context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro -into the original buffer. -@end itemize - -@item -@b{Citations}@* -Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a -regular expression to search in current BibTeX database files (as -specified in the @code{\bibliography} command) and pull out a list of -matches for you to choose from. The list is @emph{formatted} and -sorted. The selected article is referenced as @samp{\cite@{@var{key}@}} -(see the variable @code{reftex-cite-format} if you want to insert -different macros). - -@item -@b{Index Support}@* -@b{Ref@TeX{}} helps to enter index entries. It also compiles all -entries into an alphabetically sorted @file{*Index*} buffer which you -can use to check and edit the entries. @b{Ref@TeX{}} knows about the -standard index macros and can be configured to recognize any additional -macros you have defined (@code{reftex-index-macros}). Multiple indices -are supported. - -@itemize @bullet -@item -@b{Creating Index Entries}@* -To index the current selection or the word at point, type @kbd{C-c /} -(@code{reftex-index-selection-or-word}). The default macro -@code{reftex-index-default-macro} will be used. For a more complex entry -type @kbd{C-c <} (@code{reftex-index}), select any of the index macros -and enter the arguments with completion. - -@item -@b{The Index Phrases File (Delayed Indexing)}@* -Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add -the current word or selection to a special @emph{index phrase file}. -@b{Ref@TeX{}} can later search the document for occurrences of these -phrases and let you interactively index the matches. - -@item -@b{Displaying and Editing the Index}@* -To display the compiled index in a special buffer, type @kbd{C-c >} -(@code{reftex-display-index}). From that buffer you can check and edit -all entries. -@end itemize - -@page -@item @b{Viewing Cross-References}@* -When point is on the @var{key} argument of a cross--referencing macro -(@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, -@code{\index}, and variations) or inside a BibTeX database entry, you -can press @kbd{C-c &} (@code{reftex-view-crossref}) to display -corresponding locations in the document and associated BibTeX database -files. @* -When the enclosing macro is @code{\cite} or @code{\ref} and no other -message occupies the echo area, information about the citation or label -will automatically be displayed in the echo area. - -@item -@b{Multifile Documents}@* -Multifile Documents are fully supported. The included files must have a -file variable @code{TeX-master} or @code{tex-main-file} pointing to the -master file. @b{Ref@TeX{}} provides cross-referencing information from -all parts of the document, and across document borders -(@file{xr.sty}). - -@item -@b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in -order to find labels and other information. It does it automatically -once and updates its list internally when @code{reftex-label} and -@code{reftex-index} are used. To enforce reparsing, call any of the -commands described above with a raw @kbd{C-u} prefix, or press the -@kbd{r} key in the label selection buffer, the table of contents -buffer, or the index buffer. - -@item -@b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can -cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeX -contains style files which trigger appropriate settings in -@b{Ref@TeX{}}, so that for many of the popular LaTeX packages no -additional customizations will be necessary. - -@item -@b{Useful Settings}@* -To integrate RefTeX with AUCTeX, use -@lisp -(setq reftex-plug-into-AUCTeX t) -@end lisp - -To make your own LaTeX macro definitions known to @b{Ref@TeX{}}, -customize the variables -@example -@code{reftex-label-alist} @r{(for label macros/environments)} -@code{reftex-section-levels} @r{(for sectioning commands)} -@code{reftex-cite-format} @r{(for @code{\cite}-like macros)} -@code{reftex-index-macros} @r{(for @code{\index}-like macros)} -@code{reftex-index-default-macro} @r{(to set the default macro)} -@end example -If you have a large number of macros defined, you may want to write -an AUCTeX style file to support them with both AUCTeX and -@b{Ref@TeX{}}. - -@item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menus -until you have picked up the key bindings. For an overview of what you -can do in each of the different special buffers, press @kbd{?}. Read -the manual if you get stuck, of if you are curious what else might be -available. The first part of the manual explains in -a tutorial way how to use and customize @b{Ref@TeX{}}. The second -part is a command and variable reference. -@end enumerate - -@node Table of Contents, Labels and References, Introduction, Top -@chapter Table of Contents -@cindex @file{*toc*} buffer -@cindex Structure editing -@cindex Table of contents buffer -@findex reftex-toc -@kindex C-c = - -Pressing the keys @kbd{C-c =} pops up a buffer showing the table of -contents of the document. By default, this @file{*toc*} buffer shows -only the sections of a document. Using the @kbd{l} and @kbd{i} keys you -can display all labels and index entries defined in the document as -well. - -With the cursor in any of the lines denoting a location in the -document, simple key strokes will display the corresponding part in -another window, jump to that location, or perform other actions. - -@kindex ? -Here is a list of special commands in the @file{*toc*} buffer. A -summary of this information is always available by pressing -@kbd{?}. - -@table @kbd - -@tablesubheading{General} -@item ? -Display a summary of commands. - -@item 0-9, - -Prefix argument. - -@tablesubheading{Moving around} -@item n -Goto next entry in the table of context. - -@item p -Goto previous entry in the table of context. - -@item C-c C-n -Goto next section heading. Useful when many labels and index entries -separate section headings. - -@item C-c C-p -Goto previous section heading. - -@item N z -Jump to section N, using the prefix arg. For example, @kbd{3 z} jumps -to section 3. - -@tablesubheading{Access to document locations} -@item @key{SPC} -Show the corresponding location in another window. This command does -@emph{not} select that other window. - -@item @key{TAB} -Goto the location in another window. - -@item @key{RET} -Go to the location and hide the @file{*toc*} buffer. This will restore -the window configuration before @code{reftex-toc} (@kbd{C-c =}) was -called. - -@item mouse-2 -@vindex reftex-highlight-selection -Clicking with mouse button 2 on a line has the same effect as @key{RET}. -See also variable @code{reftex-highlight-selection}, @ref{Options -(Fontification)}. - -@item f -@vindex reftex-toc-follow-mode -@vindex reftex-revisit-to-follow -Toggle follow mode. When follow mode is active, the other window will -always show the location corresponding to the line at point in the -@file{*toc*} buffer. This is similar to pressing @key{SPC} after each -cursor motion. The default for this flag can be set with the variable -@code{reftex-toc-follow-mode}. Note that only context in files already -visited is shown. @b{Ref@TeX{}} will not visit a file just for follow -mode. See, however, the variable -@code{reftex-revisit-to-follow}. - -@item . -Show calling point in another window. This is the point from where -@code{reftex-toc} was last called. - -@page -@tablesubheading{Promotion and Demotion} - -@item < -Promote the current section. This will convert @code{\section} to -@code{\chapter}, @code{\subsection} to @code{\section} etc. If there is -an active region, all sections in the region will be promoted, including -the one at point. To avoid mistakes, @b{Ref@TeX{}} requires a fresh -document scan before executing this command - if necessary, it will -automatically do this scan and ask the user to repeat the promotion -command. - -@item > -Demote the current section. This is the opposite of promotion. It will -convert @code{\chapter} to @code{\section} etc. If there is an active -region, all sections in the region will be demoted, including the one at -point. - -@item M-% -Rename the label at point. While generally not recommended, this can be -useful when a package like @file{fancyref} is used where the label -prefix determines the wording of a reference. After a -promotion/demotion it may be necessary to change a few labels from -@samp{sec:xyz} to @samp{cha:xyz} or vice versa. This command can be -used to do this - it launches a query replace to rename the definition -and all references of a label. - -@tablesubheading{Exiting} -@item q -Hide the @file{*toc*} buffer, return to the position where -@code{reftex-toc} was last called. - -@item k -Kill the @file{*toc*} buffer, return to the position where -@code{reftex-toc} was last called. - -@item C-c > -Switch to the @file{*Index*} buffer of this document. With prefix -@samp{2}, restrict the index to the section at point in the @file{*toc*} -buffer. - -@tablesubheading{Controlling what gets displayed} - -@item t -@vindex reftex-toc-max-level -Change the maximum level of toc entries displayed in the @file{*toc*} -buffer. Without prefix arg, all levels will be included. With prefix -arg (e.g @kbd{3 t}), ignore all toc entries with level greater than -@var{arg} (3 in this case). Chapters are level 1, sections are level 2. -The mode line @samp{T<>} indicator shows the current value. The default -depth can be configured with the variable -@code{reftex-toc-max-level}. - -@item F -@vindex reftex-toc-include-file-boundaries -Toggle the display of the file borders of a multifile document in the -@file{*toc*} buffer. The default for this flag can be set with the -variable @code{reftex-toc-include-file-boundaries}. - -@item l -@vindex reftex-toc-include-labels -Toggle the display of labels in the @file{*toc*} buffer. The default -for this flag can be set with the variable -@code{reftex-toc-include-labels}. When called with a prefix argument, -@b{Ref@TeX{}} will prompt for a label type and include only labels of -the selected type in the @file{*toc*} buffer. The mode line @samp{L<>} -indicator shows which labels are included. - -@item i -@vindex reftex-toc-include-index-entries -Toggle the display of index entries in the @file{*toc*} buffer. The -default for this flag can be set with the variable -@code{reftex-toc-include-index-entries}. When called with a prefix -argument, @b{Ref@TeX{}} will prompt for a specific index and include -only entries in the selected index in the @file{*toc*} buffer. The mode -line @samp{I<>} indicator shows which index is used. - -@item c -@vindex reftex-toc-include-context -Toggle the display of label and index context in the @file{*toc*} -buffer. The default for this flag can be set with the variable -@code{reftex-toc-include-context}. - -@tablesubheading{Updating the buffer} - -@item g -Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the -document. - -@item r -@vindex reftex-enable-partial-scans -Reparse the LaTeX document and rebuild the @file{*toc*} buffer. When -@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this -location is defined in, not the entire document. - -@item C-u r -Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*} -buffer. - -@item x -Switch to the @file{*toc*} buffer of an external document. When the -current document is using the @code{xr} package (@pxref{xr (LaTeX -package)}), @b{Ref@TeX{}} will switch to one of the external -documents. - - -@tablesubheading{Automatic recentering} - -@item d -Toggle the display of a dedicated frame displaying just the @file{*toc*} -buffer. Follow mode and visiting locations will not work that frame, -but automatic recentering will make this frame always show your current -editing location in the document (see below). - -@item a -Toggle the automatic recentering of the @file{*toc*} buffer. When this -option is on, moving around in the document will cause the @file{*toc*} -to always highlight the current section. By default, this option is -active while the dedicated @file{*TOC*} frame exists. See also the -variable @code{reftex-auto-recenter-toc}. - -@end table - -@vindex reftex-toc-map -In order to define additional commands for the @file{*toc*} buffer, the -keymap @code{reftex-toc-map} may be used. - -@findex reftex-toc-recenter -@vindex reftex-auto-recenter-toc -@vindex reftex-idle-time -@cindex @file{*toc*} buffer, recentering -@cindex Table of contents buffer, recentering -@kindex C-c - -If you call @code{reftex-toc} while the @file{*toc*} buffer already -exists, the cursor will immediately jump to the right place, i.e. the -section from which @code{reftex-toc} was called will be highlighted. -The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay -the @file{*toc*} buffer and highlight the correct line without actually -selecting the @file{*toc*} window. This can be useful to quickly find -out where in the document you currently are. You can also automate this -by asking RefTeX to keep track of your current editing position in the -TOC. The TOC window will then be updated whenever you stop typing for -more than @code{reftex-idle-time} seconds. By default this works only -with the dedicated @file{*TOC*} frame. But you can also force automatic -recentering of the TOC window on the current frame with -@lisp -(setq reftex-auto-recenter-toc t) -@end lisp - - -@cindex Sectioning commands -@cindex KOMA-Script, LaTeX classes -@cindex LaTeX classes, KOMA-Script -@cindex TOC entries for environments -@vindex reftex-section-levels -The section macros recognized by @b{Ref@TeX{}} are all LaTeX section -macros (from @code{\part} to @code{\subsubparagraph}) and the commands -@code{\addchap} and @code{\addsec} from the KOMA-Script classes. -Additional macros can be configured with the variable -@code{reftex-section-levels}. It is also possible to add certain LaTeX -environments to the table of contents. This is probably only useful for -theorem-like environments. @xref{Defining Label Environments}, for an -example. - -@node Labels and References, Citations, Table of Contents, Top -@chapter Labels and References -@cindex Labels in LaTeX -@cindex References in LaTeX -@cindex Label category -@cindex Label environment -@cindex @code{\label} - -LaTeX provides a powerful mechanism to deal with cross--references in a -document. When writing a document, any part of it can be marked with a -label, like @samp{\label@{mark@}}. LaTeX records the current value of a -certain counter when a label is defined. Later references to this label -(like @samp{\ref@{mark@}}) will produce the recorded value of the -counter. - -Labels can be used to mark sections, figures, tables, equations, -footnotes, items in enumerate lists etc. LaTeX is context sensitive in -doing this: A label defined in a figure environment automatically -records the figure counter, not the section counter. - -Several different environments can share a common counter and therefore -a common label category. E.g. labels in both @code{equation} and -@code{eqnarray} environments record the value of the same counter - the -equation counter. - -@menu -* Creating Labels:: -* Referencing Labels:: -* Builtin Label Environments:: The environments RefTeX knows about. -* Defining Label Environments:: ... and environments it doesn't. -* Reference Info:: View the label corresponding to a \ref. -* xr (LaTeX package):: References to external documents. -* varioref (LaTeX package):: How to create \vref instead of \ref. -* fancyref (LaTeX package):: How to create \fref instead of \ref. -@end menu - -@node Creating Labels, Referencing Labels, , Labels and References -@section Creating Labels -@cindex Creating labels -@cindex Labels, creating -@cindex Labels, deriving from context -@kindex C-c ( -@findex reftex-label - -In order to create a label in a LaTeX document, press @kbd{C-c (} -(@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitive -and will figure out the environment it currently is in and adapt the -label to that environment. A label usually consists of a short prefix -indicating the type of the label and a unique mark. @b{Ref@TeX{}} has -3 different modes to create this mark. - -@enumerate -@item -@vindex reftex-translate-to-ascii-function -@vindex reftex-derive-label-parameters -@vindex reftex-label-illegal-re -@vindex reftex-abbrev-parameters -A label can be derived from context. This means, @b{Ref@TeX{}} takes -the context of the label definition and constructs a label from -that@footnote{Note that the context may contain constructs which are -invalid in labels. @b{Ref@TeX{}} will therefore strip the accent from -accented Latin-1 characters and remove everything else which is not -valid in labels. This mechanism is safe, but may not be satisfactory -for non-western languages. Check the following variables if you need to -change things: @code{reftex-translate-to-ascii-function}, -@code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re}, -@code{reftex-abbrev-parameters}.}. This works best for section labels, -where the section heading is used to construct a label. In fact, -@b{Ref@TeX{}}'s default settings use this method only for section -labels. You will be asked to confirm the derived label, or edit -it. - -@item -We may also use a simple unique number to identify a label. This is -mostly useful for labels where it is difficult to come up with a very -good descriptive name. @b{Ref@TeX{}}'s default settings use this method -for equations, enumerate items and footnotes. The author of @b{Ref@TeX{}} -tends to write documents with many equations and finds it impossible -to come up with good names for each of them. These simple labels are -inserted without query, and are therefore very fast. Good descriptive -names are not really necessary as @b{Ref@TeX{}} will provide context to -reference a label (@pxref{Referencing Labels}). - -@item -The third method is to ask the user for a label. This is most -useful for things which are easy to describe briefly and do not turn up -too frequently in a document. @b{Ref@TeX{}} uses this for figures and -tables. Of course, one can enter the label directly by typing the full -@samp{\label@{mark@}}. The advantage of using @code{reftex-label} -anyway is that @b{Ref@TeX{}} will know that a new label has been defined. -It will then not be necessary to rescan the document in order to access -this label later. -@end enumerate - -@vindex reftex-insert-label-flags -If you want to change the way certain labels are created, check out the -variable @code{reftex-insert-label-flags} (@pxref{Options (Creating -Labels)}). - -If you are using AUCTeX to write your LaTeX documents, you can -set it up to delegate the creation of labels to -@b{Ref@TeX{}}. @xref{AUCTeX}, for more information. - -@node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References -@section Referencing Labels -@cindex Referencing labels -@cindex Labels, referencing -@cindex Selection buffer, labels -@cindex Selection process -@cindex @code{\ref} -@kindex C-c ) -@findex reftex-reference - -@vindex reftex-trust-label-prefix -@b{Ref@TeX{}} scans the document in order to find all labels. To make -referencing labels easier, it assigns to each label a category, the -@emph{label type} (for example section, table, figure, equation, etc.). -In order to determine the label type, RefTeX parses around each label -to see in what kind of environments it is located. You can speed up -the parsing by using type-specific prefixes for labels and configuring -the variable @code{reftex-trust-label-prefix}. - -Referencing Labels is really at the heart of @b{Ref@TeX{}}. Press @kbd{C-c -)} in order to reference a label (reftex-reference). This will start a -selection process and finally insert the complete @samp{\ref@{label@}} -into the buffer. - -First, @b{Ref@TeX{}} will determine the label category which is required. -Often that can be figured out from context. For example, if you -write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knows -that an equation label is going to be referenced. If it cannot figure -out what label category is needed, it will query for one. - -You will then be presented with a label selection menu. This is a -special buffer which contains an outline of the document along with all -labels of the given label category. In addition, next to the label -there will be one line of context of the label definition, which is some -text in the buffer near the label definition. Usually this is -sufficient to identify the label. If you are unsure about a certain -label, pressing @key{SPC} will show the label definition point in -another window. - -In order to reference a label, move to cursor to the correct label and -press @key{RET}. You can also reference several labels with a single -call to @code{reftex-reference} by marking entries with the @kbd{m} -key (see below). - -@kindex ? -Here is a list of special commands in the selection buffer. A summary -of this information is always available from the selection process by -pressing @kbd{?}. - - - -@table @kbd -@tablesubheading{General} -@item ? -Show a summary of available commands. - -@item 0-9,- -Prefix argument. - -@tablesubheading{Moving around} -@item n -Go to next label. - -@item p -Go to previous label. - -@item b -Jump back to the position where you last left the selection buffer. -Normally this should get you back to the last referenced label. - -@item C-c C-n -Goto next section heading. - -@item C-c C-p -Goto previous section heading. - -@item N z -Jump to section N, using the prefix arg. For example @kbd{3 z} jumps to -section 3. - -@tablesubheading{Displaying Context} -@item @key{SPC} -Show the surroundings of the definition of the current label in another -window. See also the @kbd{f} key. - -@item f -@vindex reftex-revisit-to-follow -Toggle follow mode. When follow mode is active, the other window will -always display the full context of the current label. This is similar -to pressing @key{SPC} after each cursor motion. Note that only context -in files already visited is shown. @b{RefTeX} will not visit a file -just for follow mode. See, however, the variable -@code{reftex-revisit-to-follow}. - -@item . -Show insertion point in another window. This is the point from where you -called @code{reftex-reference}. - -@tablesubheading{Selecting a label and creating the reference} -@item @key{RET} -Insert a reference to the label at point into the buffer from which the -selection process was started. When entries have been marked, @key{RET} -references all marked labels. - -@item mouse-2 -@vindex reftex-highlight-selection -Clicking with mouse button 2 on a label will accept it like @key{RET} -would. See also variable @code{reftex-highlight-selection}, @ref{Options -(Misc)}. - -@vindex reftex-multiref-punctuation -@item m - + , -Mark the current entry. When several entries have been marked, pressing -@kbd{RET} will accept all of them and place them into several -@code{\ref} macros. The special markers @samp{,-+} also store a -separator to be inserted before the corresponding reference. So marking -six entries with the keys @samp{m , , - , +} will give a reference list -like this (see the variable @code{reftex-multiref-punctuation}) -@example -In eqs. (1), (2), (3)--(4), (5) and (6) -@end example - -@item u -Unmark a marked entry. - -@c FIXME: Do we need `A' as well for consistency? -@cindex LaTeX packages, @code{saferef} -@cindex @code{saferef}, LaTeX package -@item a -Accept the marked entries and put all labels as a comma-separated list -into one @emph{single} @code{\ref} macro. Some packages like -@file{saferef.sty} support multiple references in this way. - -@item l -Use the last referenced label(s) again. This is equivalent to moving to -that label and pressing @key{RET}. - -@item @key{TAB} -Enter a label with completion. This may also be a label which does not -yet exist in the document. - -@item v -@cindex @code{varioref}, LaTeX package -@cindex @code{\vref} -@cindex LaTeX packages, @code{varioref} -Toggle between @code{\ref} and @code{\vref} macro for references. The -@code{\vref} macro is defined in the @code{varioref} LaTeX package. -With this key you can force @b{Ref@TeX{}} to insert a @code{\vref} -macro. The current state of this flag is displayed by the @samp{S<>} -indicator in the mode line of the selection buffer. - -@item V -@cindex @code{fancyref}, LaTeX package -@cindex @code{\fref} -@cindex @code{\Fref} -@cindex LaTeX packages, @code{fancyref} -Cycle between @code{\ref}, @code{\fref} and @code{\Fref}. The -@code{\fref} and @code{\Fref} macros are defined in the @code{fancyref} -LaTeX package. With this key you can force @b{Ref@TeX{}} to insert a -@code{\fref} or @code{\Fref} macro. The current state of this flag is -displayed by the @samp{S<>} indicator in the mode line of the -selection buffer. - -@tablesubheading{Exiting} - -@item q -Exit the selection process without inserting any reference into the -buffer. - -@tablesubheading{Controlling what gets displayed} -@vindex reftex-label-menu-flags -The defaults for the following flags can be configured with the variable -@code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}). - -@item c -Toggle the display of the one-line label definition context in the -selection buffer. - -@item F -Toggle the display of the file borders of a multifile document in the -selection buffer. - -@item t -Toggle the display of the table of contents in the selection buffer. -With prefix @var{arg}, change the maximum level of toc entries displayed -to @var{arg}. Chapters are level 1, section are level 2. - -@item # -Toggle the display of a label counter in the selection buffer. - -@item % -Toggle the display of labels hidden in comments in the selection -buffers. Sometimes, you may have commented out parts of your document. -If these parts contain label definitions, @b{Ref@TeX{}} can still display -and reference these labels. - -@tablesubheading{Updating the buffer} -@item g -Update the menu. This will rebuilt the menu from the internal label -list, but not reparse the document (see @kbd{r}). - -@item r -@vindex reftex-enable-partial-scans -Reparse the document to update the information on all labels and rebuild -the menu. If the variable @code{reftex-enable-partial-scans} is -non-@code{nil} and your document is a multifile document, this will -reparse only a part of the document (the file in which the label at -point was defined). - -@item C-u r -Reparse the @emph{entire} document. - -@item s -Switch the label category. After prompting for another label category, -a menu for that category will be shown. - -@item x -Reference a label from an external document. With the LaTeX package -@code{xr} it is possible to reference labels defined in another -document. This key will switch to the label menu of an external -document and let you select a label from there (@pxref{xr (LaTeX -package),,xr}). - -@end table - -@vindex reftex-select-label-map -In order to define additional commands for the selection process, the -keymap @code{reftex-select-label-map} may be used. - -@node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References -@section Builtin Label Environments -@cindex Builtin label environments -@cindex Label environments, builtin -@cindex Environments, builtin -@vindex reftex-label-alist -@vindex reftex-label-alist-builtin - -@b{Ref@TeX{}} needs to be aware of the environments which can be referenced -with a label (i.e. which carry their own counters). By default, @b{Ref@TeX{}} -recognizes all labeled environments and macros discussed in @cite{The -LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley -1994.}. These are: - -@itemize @minus -@item -@cindex @code{figure}, LaTeX environment -@cindex @code{figure*}, LaTeX environment -@cindex @code{table}, LaTeX environment -@cindex @code{table*}, LaTeX environment -@cindex @code{equation}, LaTeX environment -@cindex @code{eqnarray}, LaTeX environment -@cindex @code{enumerate}, LaTeX environment -@cindex @code{\footnote}, LaTeX macro -@cindex LaTeX macro @code{footnote} -@cindex LaTeX core -@code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation}, -@code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is -the LaTeX core stuff) -@item -@cindex AMS-LaTeX -@cindex @code{amsmath}, LaTeX package -@cindex LaTeX packages, @code{amsmath} -@cindex @code{align}, AMS-LaTeX environment -@cindex @code{gather}, AMS-LaTeX environment -@cindex @code{multline}, AMS-LaTeX environment -@cindex @code{flalign}, AMS-LaTeX environment -@cindex @code{alignat}, AMS-LaTeX environment -@cindex @code{xalignat}, AMS-LaTeX environment -@cindex @code{xxalignat}, AMS-LaTeX environment -@cindex @code{subequations}, AMS-LaTeX environment -@code{align}, @code{gather}, @code{multline}, @code{flalign}, -@code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations} -(from AMS-LaTeX's @file{amsmath.sty} package) -@item -@cindex @code{endnote}, LaTeX package -@cindex LaTeX packages, @code{endnote} -@cindex @code{\endnote}, LaTeX macro -the @code{\endnote} macro (from @file{endnotes.sty}) -@item -@cindex @code{fancybox}, LaTeX package -@cindex LaTeX packages, @code{fancybox} -@cindex @code{Beqnarray}, LaTeX environment -@code{Beqnarray} (@file{fancybox.sty}) -@item -@cindex @code{floatfig}, LaTeX package -@cindex LaTeX packages, @code{floatfig} -@cindex @code{floatingfig}, LaTeX environment -@code{floatingfig} (@file{floatfig.sty}) -@item -@cindex @code{longtable}, LaTeX package -@cindex LaTeX packages, @code{longtable} -@cindex @code{longtable}, LaTeX environment -@code{longtable} (@file{longtable.sty}) -@item -@cindex @code{picinpar}, LaTeX package -@cindex LaTeX packages, @code{picinpar} -@cindex @code{figwindow}, LaTeX environment -@cindex @code{tabwindow}, LaTeX environment -@code{figwindow}, @code{tabwindow} (@file{picinpar.sty}) -@item -@cindex @code{sidecap}, LaTeX package -@cindex LaTeX packages, @code{sidecap} -@cindex @code{SCfigure}, LaTeX environment -@cindex @code{SCtable}, LaTeX environment -@code{SCfigure}, @code{SCtable} (@file{sidecap.sty}) -@item -@cindex @code{rotating}, LaTeX package -@cindex LaTeX packages, @code{rotating} -@cindex @code{sidewaysfigure}, LaTeX environment -@cindex @code{sidewaystable}, LaTeX environment -@code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty}) -@item -@cindex @code{subfig}, LaTeX package -@cindex LaTeX packages, @code{subfigure} -@cindex @code{subfigure}, LaTeX environment -@cindex @code{subfigure*}, LaTeX environment -@code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro -(@file{subfigure.sty}) -@item -@cindex @code{supertab}, LaTeX package -@cindex LaTeX packages, @code{supertab} -@cindex @code{supertabular}, LaTeX environment -@code{supertabular} (@file{supertab.sty}) -@item -@cindex @code{wrapfig}, LaTeX package -@cindex LaTeX packages, @code{wrapfig} -@cindex @code{wrapfigure}, LaTeX environment -@code{wrapfigure} (@file{wrapfig.sty}) -@end itemize - -If you want to use other labeled environments, defined with -@code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize -them (@pxref{Defining Label Environments}). - -@node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References -@section Defining Label Environments -@cindex Label environments, defining - -@vindex reftex-label-alist -@b{Ref@TeX{}} can be configured to recognize additional labeled -environments and macros. This is done with the variable -@code{reftex-label-alist} (@pxref{Options (Defining Label -Environments)}). If you are not familiar with Lisp, you can use the -@code{custom} library to configure this rather complex variable. To do -this, use - -@example -@kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}} -@end example - -@vindex reftex-label-alist-builtin -Here we will discuss a few examples, in order to make things clearer. -It can also be instructive to look at the constant -@code{reftex-label-alist-builtin} which contains the entries for -all the builtin environments and macros (@pxref{Builtin Label -Environments}). - -@menu -* Theorem and Axiom:: Defined with @code{\newenvironment}. -* Quick Equation:: When a macro sets the label type. -* Figure Wrapper:: When a macro argument is a label. -* Adding Magic Words:: Other words for other languages. -* Using \eqref:: How to switch to this AMS-LaTeX macro. -* Non-Standard Environments:: Environments without \begin and \end -* Putting it Together:: How to combine many entries. -@end menu - -@node Theorem and Axiom, Quick Equation, , Defining Label Environments -@subsection Theorem and Axiom Environments -@cindex @code{theorem}, newtheorem -@cindex @code{axiom}, newtheorem -@cindex @code{\newtheorem} - -Suppose you are using @code{\newtheorem} in LaTeX in order to define two -new environments, @code{theorem} and @code{axiom} - -@example -\newtheorem@{axiom@}@{Axiom@} -\newtheorem@{theorem@}@{Theorem@} -@end example - -@noindent -to be used like this: - -@example -\begin@{axiom@} -\label@{ax:first@} - .... -\end@{axiom@} -@end example - -So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new -labeled environments which define their own label categories. We can -either use Lisp to do this (e.g. in @file{.emacs}) or use the custom -library. With Lisp it would look like this - -@lisp -(setq reftex-label-alist - '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2) - ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "th.") -3))) -@end lisp - -The type indicator characters @code{?a} and @code{?h} are used for -prompts when @b{Ref@TeX{}} queries for a label type. @code{?h} -was chosen for @code{theorem} since @code{?t} is already taken by -@code{table}. Note that also @code{?s}, @code{?f}, @code{?e}, -@code{?i}, @code{?n} are already used for standard environments. - -@noindent -The labels for Axioms and Theorems will have the prefixes @samp{ax:} and -@samp{thr:}, respectively. @xref{AUCTeX}, for information on how -AUCTeX can use RefTeX to automatically create labels when a new environment -is inserted into a buffer. Additionally, the following needs to be -added to one's .emacs file before AUCTeX will automatically create -labels for the new environments. - -@lisp -(add-hook 'LaTeX-mode-hook - (lambda () - (LaTeX-add-environments - '("axiom" LaTeX-env-label) - '("theorem" LaTeX-env-label)))) -@end lisp - - -@noindent -The @samp{~\ref@{%s@}} is a format string indicating how to insert -references to these labels. - -@noindent -The next item indicates how to grab context of the label definition. -@itemize @minus -@item -@code{t} means to get it from a default location (from the beginning of -a @code{\macro} or after the @code{\begin} statement). @code{t} is -@emph{not} a good choice for eqnarray and similar environments. -@item -@code{nil} means to use the text right after the label definition. -@item -For more complex ways of getting context, see the variable -@code{reftex-label-alist} (@ref{Options (Defining Label -Environments)}). -@end itemize - -The following list of strings is used to guess the correct label type -from the word before point when creating a reference. E.g. if you -write: @samp{As we have shown in Theorem} and then press @kbd{C-c )}, -@b{Ref@TeX{}} will know that you are looking for a theorem label and -restrict the menu to only these labels without even asking. - -The final item in each entry is the level at which the environment -should produce entries in the table of context buffer. If the number is -positive, the environment will produce numbered entries (like -@code{\section}), if it is negative the entries will be unnumbered (like -@code{\section*}). Use this only for environments which structure the -document similar to sectioning commands. For everything else, omit the -item. - -To do the same configuration with @code{customize}, you need to click on -the @code{[INS]} button twice to create two templates and fill them in -like this: - -@example -Reftex Label Alist: [Hide] -[INS] [DEL] Package or Detailed : [Value Menu] Detailed: - Environment or \macro : [Value Menu] String: axiom - Type specification : [Value Menu] Char : a - Label prefix string : [Value Menu] String: ax: - Label reference format: [Value Menu] String: ~\ref@{%s@} - Context method : [Value Menu] After label - Magic words: - [INS] [DEL] String: axiom - [INS] [DEL] String: ax. - [INS] - [X] Make TOC entry : [Value Menu] Level: -2 -[INS] [DEL] Package or Detailed : [Value Menu] Detailed: - Environment or \macro : [Value Menu] String: theorem - Type specification : [Value Menu] Char : h - Label prefix string : [Value Menu] String: thr: - Label reference format: [Value Menu] String: ~\ref@{%s@} - Context method : [Value Menu] Default position - Magic words: - [INS] [DEL] String: theorem - [INS] [DEL] String: theor. - [INS] [DEL] String: th. - [INS] - [X] Make TOC entry : [Value Menu] Level: -3 -@end example - -@vindex reftex-insert-label-flags -@vindex reftex-label-menu-flags -Depending on how you would like the label insertion and selection for -the new environments to work, you might want to add the letters @samp{a} -and @samp{h} to some of the flags in the variables -@code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)}) -and @code{reftex-label-menu-flags} (@pxref{Options (Referencing -Labels)}). - - -@node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments -@subsection Quick Equation Macro -@cindex Quick equation macro -@cindex Macros as environment wrappers - -Suppose you would like to have a macro for quick equations. It -could be defined like this: - -@example -\newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@} -@end example - -@noindent -and used like this: - -@example -Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}. -@end example - -We need to tell @b{Ref@TeX{}} that any label defined in the argument of the -@code{\quickeq} is an equation label. Here is how to do this with lisp: - -@lisp -(setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil))) -@end lisp - -The first element in this list is now the macro with empty braces as an -@emph{image} of the macro arguments. @code{?e} indicates that this is -an equation label, the different @code{nil} elements indicate to use the -default values for equations. The @samp{1} as the fifth element -indicates that the context of the label definition should be the 1st -argument of the macro. - -Here is again how this would look in the customization buffer: - -@example -Reftex Label Alist: [Hide] -[INS] [DEL] Package or Detailed : [Value Menu] Detailed: - Environment or \macro : [Value Menu] String: \quickeq@{@} - Type specification : [Value Menu] Char : e - Label prefix string : [Value Menu] Default - Label reference format: [Value Menu] Default - Context method : [Value Menu] Macro arg nr: 1 - Magic words: - [INS] - [ ] Make TOC entry : [Value Menu] No entry -@end example - -@node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments -@subsection Figure Wrapping Macro -@cindex Macros as environment wrappers -@cindex Figure wrapping macro - -Suppose you want to make figures not directly with the figure -environment, but with a macro like - -@example -\newcommand@{\myfig@}[5][tbp]@{% - \begin@{figure@}[#1] - \epsimp[#5]@{#2@} - \caption@{#3@} - \label@{#4@} - \end@{figure@}@} -@end example - -@noindent -which would be called like - -@example -\myfig[htp]@{filename@}@{caption text@}@{label@}@{1@} -@end example - -Now we need to tell @b{Ref@TeX{}} that the 4th argument of the -@code{\myfig} macro @emph{is itself} a figure label, and where to find -the context. - -@lisp -(setq reftex-label-alist - '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3))) -@end lisp - -The empty pairs of brackets indicate the different arguments of the -@code{\myfig} macro. The @samp{*} marks the label argument. @code{?f} -indicates that this is a figure label which will be listed together with -labels from normal figure environments. The @code{nil} entries for -prefix and reference format mean to use the defaults for figure labels. -The @samp{3} for the context method means to grab the 3rd macro argument -- the caption. - -As a side effect of this configuration, @code{reftex-label} will now -insert the required naked label (without the @code{\label} macro) when -point is directly after the opening parenthesis of a @code{\myfig} macro -argument. - -Again, here the configuration in the customization buffer: - -@example -[INS] [DEL] Package or Detailed : [Value Menu] Detailed: - Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@} - Type specification : [Value Menu] Char : f - Label prefix string : [Value Menu] Default - Label reference format: [Value Menu] Default - Context method : [Value Menu] Macro arg nr: 3 - Magic words: - [INS] - [ ] Make TOC entry : [Value Menu] No entry -@end example - -@node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments -@subsection Adding Magic Words -@cindex Magic words -@cindex German magic words -@cindex Label category - -Sometimes you don't want to define a new label environment or macro, but -just change the information associated with a label category. Maybe you -want to add some magic words, for another language. Changing only the -information associated with a label category is done by giving -@code{nil} for the environment name and then specify the items you want -to define. Here is an example which adds German magic words to all -predefined label categories. - -@lisp -(setq reftex-label-alist - '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil")) - (nil ?e nil nil nil ("Gleichung" "Gl.")) - (nil ?t nil nil nil ("Tabelle")) - (nil ?f nil nil nil ("Figur" "Abbildung" "Abb.")) - (nil ?n nil nil nil ("Anmerkung" "Anm.")) - (nil ?i nil nil nil ("Punkt")))) -@end lisp - -@node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments -@subsection Using @code{\eqref} -@cindex @code{\eqref}, AMS-LaTeX macro -@cindex AMS-LaTeX -@cindex Label category - -Another case where one only wants to change the information associated -with the label category is to change the macro which is used for -referencing the label. When working with the AMS-LaTeX stuff, you might -prefer @code{\eqref} for doing equation references. Here is how to -do this: - -@lisp -(setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil))) -@end lisp - -@b{Ref@TeX{}} has also a predefined symbol for this special purpose. The -following is equivalent to the line above. - -@lisp -(setq reftex-label-alist '(AMSTeX)) -@end lisp - -Note that this is automatically done by the @file{amsmath.el} style file -of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX, -this configuration will not be necessary. - -@node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments -@subsection Non-standard Environments -@cindex Non-standard environments -@cindex Environments without @code{\begin} -@cindex Special parser functions -@cindex Parser functions, for special environments - -Some LaTeX packages define environment-like structures without using the -standard @samp{\begin..\end} structure. @b{Ref@TeX{}} cannot parse -these directly, but you can write your own special-purpose parser and -use it instead of the name of an environment in an entry for -@code{reftex-label-alist}. The function should check if point is -currently in the special environment it was written to detect. If so, -it must return a buffer position indicating the start of this -environment. The return value must be @code{nil} on failure to detect -the environment. The function is called with one argument @var{bound}. -If non-@code{nil}, @var{bound} is a boundary for backwards searches -which should be observed. We will discuss two examples. - -@cindex LaTeX commands, abbreviated - -Some people define abbreviations for -environments, like @code{\be} for @code{\begin@{equation@}}, and -@code{\ee} for @code{\end@{equation@}}. The parser function would have -to search backward for these macros. When the first match is -@code{\ee}, point is not in this environment. When the first match is -@code{\be}, point is in this environment and the function must return -the beginning of the match. To avoid scanning too far, we can also look -for empty lines which cannot occur inside an equation environment. -Here is the setup: - -@lisp -;; Setup entry in reftex-label-alist, using all defaults for equations -(setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil))) - -(defun detect-be-ee (bound) - ;; Search backward for the macros or an empty line - (if (re-search-backward - "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t) - (if (match-beginning 2) - (match-beginning 2) ; Return start of environment - nil) ; Return nil because env is closed - nil)) ; Return nil for not found -@end lisp - -@cindex @code{linguex}, LaTeX package -@cindex LaTeX packages, @code{linguex} -A more complex example is the @file{linguex.sty} package which defines -list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are -terminated by @samp{\z.} or by an empty line. - -@example -\ex. \label@{ex:12@} Some text in an exotic language ... - \a. \label@{ex:13@} more stuff - \b. \label@{ex:14@} still more stuff - \a. List on a deeper level - \b. Another item - \b. and the third one - \z. - \b. Third item on this level. - -... text after the empty line terminating all lists -@end example - -The difficulty is that the @samp{\a.} lists can nest and that an empty -line terminates all list levels in one go. So we have to count nesting -levels between @samp{\a.} and @samp{\z.}. Here is the implementation -for @b{Ref@TeX{}}. - -@lisp -(setq reftex-label-alist - '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) - -(defun detect-linguex (bound) - (let ((cnt 0)) - (catch 'exit - (while - ;; Search backward for all possible delimiters - (re-search-backward - (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|" - "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)") - nil t) - ;; Check which delimiter was matched. - (cond - ((match-beginning 1) - ;; empty line terminates all - return nil - (throw 'exit nil)) - ((match-beginning 2) - ;; \z. terminates one list level - decrease nesting count - (decf cnt)) - ((match-beginning 3) - ;; \ex. : return match unless there was a \z. on this level - (throw 'exit (if (>= cnt 0) (match-beginning 3) nil))) - ((match-beginning 4) - ;; \a. : return match when on level 0, otherwise - ;; increment nesting count - (if (>= cnt 0) - (throw 'exit (match-beginning 4)) - (incf cnt)))))))) -@end lisp - -@node Putting it Together, , Non-Standard Environments, Defining Label Environments -@subsection Putting it all together - -When you have to put several entries into @code{reftex-label-alist}, just -put them after each other in a list, or create that many templates in -the customization buffer. Here is a lisp example which uses several of -the entries described above: - -@lisp -(setq reftex-label-alist - '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2) - ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.") -3) - ("\\quickeq@{@}" ?e nil nil 1 nil) - AMSTeX - ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3) - (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) -@end lisp - -@node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References -@section Reference Info -@findex reftex-view-crossref -@findex reftex-mouse-view-crossref -@cindex Cross-references, displaying -@cindex Reference info -@cindex Displaying cross-references -@cindex Viewing cross-references -@kindex C-c & -@kindex S-mouse-2 - -When point is idle for more than @code{reftex-idle-time} seconds on the -argument of a @code{\ref} macro, the echo area will display some -information about the label referenced there. Note that the information -is only displayed if the echo area is not occupied by a different -message. - -@b{Ref@TeX{}} can also display the label definition corresponding to a -@code{\ref} macro, or all reference locations corresponding to a -@code{\label} macro. @xref{Viewing Cross-References}, for more -information. - -@node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References -@section @code{xr}: Cross-Document References -@cindex @code{xr}, LaTeX package -@cindex LaTeX packages, @code{xr} -@cindex @code{\externaldocument} -@cindex External documents -@cindex References to external documents -@cindex Cross-document references - -The LaTeX package @code{xr} makes it possible to create references to -labels defined in external documents. The preamble of a document using -@code{xr} will contain something like this: - -@example -\usepackage@{xr@} -\externaldocument[V1-]@{volume1@} -\externaldocument[V3-]@{volume3@} -@end example - -@noindent -and we can make references to any labels defined in these -external documents by using the prefixes @samp{V1-} and @samp{V3-}, -respectively. - -@b{Ref@TeX{}} can be used to create such references as well. Start the -referencing process normally, by pressing @kbd{C-c )}. Select a label -type if necessary. When you see the label selection buffer, pressing -@kbd{x} will switch to the label selection buffer of one of the external -documents. You may then select a label as before and @b{Ref@TeX{}} will -insert it along with the required prefix. - -For this kind of inter-document cross-references, saving of parsing -information and the use of multiple selection buffers can mean a large -speed-up (@pxref{Optimizations}). - -@node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References -@section @code{varioref}: Variable Page References -@cindex @code{varioref}, LaTeX package -@cindex @code{\vref} -@cindex LaTeX packages, @code{varioref} -@vindex reftex-vref-is-default -@code{varioref} is a frequently used LaTeX package to create -cross--references with page information. When you want to make a -reference with the @code{\vref} macro, just press the @kbd{v} key in the -selection buffer to toggle between @code{\ref} and @code{\vref} -(@pxref{Referencing Labels}). The mode line of the selection buffer -shows the current status of this switch. If you find that you almost -always use @code{\vref}, you may want to make it the default by -customizing the variable @code{reftex-vref-is-default}. If this -toggling seems too inconvenient, you can also use the command -@code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}. -Or use AUCTeX to create your macros (@pxref{AUCTeX}). - -@node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References -@section @code{fancyref}: Fancy Cross References -@cindex @code{fancyref}, LaTeX package -@cindex @code{\fref} -@cindex @code{\Fref} -@cindex LaTeX packages, @code{fancyref} -@vindex reftex-fref-is-default -@code{fancyref} is a LaTeX package where a macro call like -@code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of -the referenced counter but also the complete text around it, like -@samp{Figure 3 on the preceding page}. In order to make it work you -need to use label prefixes like @samp{fig:} consistently - something -@b{Ref@TeX{}} does automatically. When you want to make a reference -with the @code{\fref} macro, just press the @kbd{V} key in the selection -buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref} -(@pxref{Referencing Labels}). The mode line of the selection buffer -shows the current status of this switch. If this cycling seems -inconvenient, you can also use the commands @code{reftex-fancyref-fref} -and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c -f} and @kbd{C-c F}.}. Or use AUCTeX to create your macros -(@pxref{AUCTeX}). - -@node Citations, Index Support, Labels and References, Top -@chapter Citations -@cindex Citations -@cindex @code{\cite} - -Citations in LaTeX are done with the @code{\cite} macro or variations of -it. The argument of the macro is a citation key which identifies an -article or book in either a BibTeX database file or in an explicit -@code{thebibliography} environment in the document. @b{Ref@TeX{}}'s -support for citations helps to select the correct key quickly. - -@menu -* Creating Citations:: How to create them. -* Citation Styles:: Natbib, Harvard, Chicago and Co. -* Citation Info:: View the corresponding database entry. -* Chapterbib and Bibunits:: Multiple bibliographies in a Document. -* Citations Outside LaTeX:: How to make citations in Emails etc. -* BibTeX Database Subsets:: Extract parts of a big database. -@end menu - -@node Creating Citations, Citation Styles, , Citations -@section Creating Citations -@cindex Creating citations -@cindex Citations, creating -@findex reftex-citation -@kindex C-c [ -@cindex Selection buffer, citations -@cindex Selection process - -In order to create a citation, press @kbd{C-c [}. @b{Ref@TeX{}} then -prompts for a regular expression which will be used to search through -the database and present the list of matches to choose from in a -selection process similar to that for selecting labels -(@pxref{Referencing Labels}). - -The regular expression uses an extended syntax: @samp{&&} defines a -logic @code{and} for regular expressions. For example -@samp{Einstein&&Bose} will match all articles which mention -Bose-Einstein condensation, or which are co-authored by Bose and -Einstein. When entering the regular expression, you can complete on -known citation keys. RefTeX also offers a default when prompting for a -regular expression. This default is the word before the cursor or the -word before the current @samp{\cite} command. Sometimes this may be a -good search key. - -@cindex @code{\bibliography} -@cindex @code{thebibliography}, LaTeX environment -@cindex @code{BIBINPUTS}, environment variable -@cindex @code{TEXBIB}, environment variable -@b{Ref@TeX{}} prefers to use BibTeX database files specified with a -@code{\bibliography} macro to collect its information. Just like -BibTeX, it will search for the specified files in the current directory -and along the path given in the environment variable @code{BIBINPUTS}. -If you do not use BibTeX, but the document contains an explicit -@code{thebibliography} environment, @b{Ref@TeX{}} will collect its -information from there. Note that in this case the information -presented in the selection buffer will just be a copy of relevant -@code{\bibitem} entries, not the structured listing available with -BibTeX database files. - -@kindex ? -In the selection buffer, the following keys provide special commands. A -summary of this information is always available from the selection -process by pressing @kbd{?}. - -@table @kbd -@tablesubheading{General} -@item ? -Show a summary of available commands. - -@item 0-9,- -Prefix argument. - -@tablesubheading{Moving around} -@item n -Go to next article. - -@item p -Go to previous article. - -@tablesubheading{Access to full database entries} -@item @key{SPC} -Show the database entry corresponding to the article at point, in -another window. See also the @kbd{f} key. - -@item f -Toggle follow mode. When follow mode is active, the other window will -always display the full database entry of the current article. This is -equivalent to pressing @key{SPC} after each cursor motion. With BibTeX -entries, follow mode can be rather slow. - -@tablesubheading{Selecting entries and creating the citation} -@item @key{RET} -Insert a citation referencing the article at point into the buffer from -which the selection process was started. - -@item mouse-2 -@vindex reftex-highlight-selection -Clicking with mouse button 2 on a citation will accept it like @key{RET} -would. See also variable @code{reftex-highlight-selection}, @ref{Options -(Misc)}. - -@item m -Mark the current entry. When one or several entries are marked, -pressing @kbd{a} or @kbd{A} accepts all marked entries. Also, -@key{RET} behaves like the @kbd{a} key. - -@item u -Unmark a marked entry. - -@item a -Accept all (marked) entries in the selection buffer and create a single -@code{\cite} macro referring to them. - -@item A -Accept all (marked) entries in the selection buffer and create a -separate @code{\cite} macro for each of it. - -@item e -Create a new BibTeX database file which contains all @i{marked} entries -in the selection buffer. If no entries are marked, all entries are -selected. - -@item E -Create a new BibTeX database file which contains all @i{unmarked} -entries in the selection buffer. If no entries are marked, all entries -are selected. - -@item @key{TAB} -Enter a citation key with completion. This may also be a key which does -not yet exist. - -@item . -Show insertion point in another window. This is the point from where you -called @code{reftex-citation}. - -@tablesubheading{Exiting} -@item q -Exit the selection process without inserting a citation into the -buffer. - -@tablesubheading{Updating the buffer} - -@item g -Start over with a new regular expression. The full database will be -rescanned with the new expression (see also @kbd{r}). - -@c FIXME: Should we use something else here? r is usually rescan! -@item r -Refine the current selection with another regular expression. This will -@emph{not} rescan the entire database, but just the already selected -entries. - -@end table - -@vindex reftex-select-bib-map -In order to define additional commands for this selection process, the -keymap @code{reftex-select-bib-map} may be used. - -@node Citation Styles, Citation Info, Creating Citations, Citations -@section Citation Styles -@cindex Citation styles -@cindex Citation styles, @code{natbib} -@cindex Citation styles, @code{harvard} -@cindex Citation styles, @code{chicago} -@cindex Citation styles, @code{jurabib} -@cindex @code{natbib}, citation style -@cindex @code{harvard}, citation style -@cindex @code{chicago}, citation style -@cindex @code{jurabib}, citation style - -@vindex reftex-cite-format -The standard LaTeX macro @code{\cite} works well with numeric or simple -key citations. To deal with the more complex task of author-year -citations as used in many natural sciences, a variety of packages has -been developed which define derived forms of the @code{\cite} macro. -@b{Ref@TeX{}} can be configured to produce these citation macros as well -by setting the variable @code{reftex-cite-format}. For the most -commonly used packages (@code{natbib}, @code{harvard}, @code{chicago}, -@code{jurabib}) this may be done from the menu, under -@code{Ref->Citation Styles}. Since there are usually several macros to -create the citations, executing @code{reftex-citation} (@kbd{C-c [}) -starts by prompting for the correct macro. For the Natbib style, this -looks like this: - -@example -SELECT A CITATION FORMAT - -[^M] \cite@{%l@} -[t] \citet@{%l@} -[T] \citet*@{%l@} -[p] \citep@{%l@} -[P] \citep*@{%l@} -[e] \citep[e.g.][]@{%l@} -[s] \citep[see][]@{%l@} -[a] \citeauthor@{%l@} -[A] \citeauthor*@{%l@} -[y] \citeyear@{%l@} -@end example - -@vindex reftex-cite-prompt-optional-args -If cite formats contain empty paris of square brackets, RefTeX can -will prompt for values of these optional arguments if you call the -@code{reftex-citation} command with a @kbd{C-u} prefix. -Following the most generic of these packages, @code{natbib}, the builtin -citation packages always accept the @kbd{t} key for a @emph{textual} -citation (like: @code{Jones et al. (1997) have shown...}) as well as -the @kbd{p} key for a parenthetical citation (like: @code{As shown -earlier (Jones et al, 1997)}). - -To make one of these styles the default, customize the variable -@code{reftex-cite-format} or put into @file{.emacs}: - -@lisp -(setq reftex-cite-format 'natbib) -@end lisp - -You can also use AUCTeX style files to automatically set the -citation style based on the @code{usepackage} commands in a given -document. @xref{Style Files}, for information on how to set up the style -files correctly. - -@node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top -@section Citation Info -@cindex Displaying citations -@cindex Citations, displaying -@cindex Citation info -@cindex Viewing citations -@kindex C-c & -@kindex S-mouse-2 -@findex reftex-view-crossref -@findex reftex-mouse-view-crossref - -When point is idle for more than @code{reftex-idle-time} seconds on the -argument of a @code{\cite} macro, the echo area will display some -information about the article cited there. Note that the information is -only displayed if the echo area is not occupied by a different message. - -@b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database -entry corresponding to a @code{\cite} macro, or all citation locations -corresponding to a @code{\bibitem} or BibTeX database entry. -@xref{Viewing Cross-References}. - -@node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations -@section Chapterbib and Bibunits -@cindex @code{chapterbib}, LaTeX package -@cindex @code{bibunits}, LaTeX package -@cindex Bibliographies, multiple - -@code{chapterbib} and @code{bibunits} are two LaTeX packages which -produce multiple bibliographies in a document. This is no problem for -@b{Ref@TeX{}} as long as all bibliographies use the same BibTeX database -files. If they do not, it is best to have each document part in a -separate file (as it is required for @code{chapterbib} anyway). Then -@b{Ref@TeX{}} will still scan the locally relevant databases correctly. If -you have multiple bibliographies within a @emph{single file}, this may -or may not be the case. - -@node Citations Outside LaTeX, BibTeX Database Subsets, Chapterbib and Bibunits, Citations -@section Citations outside LaTeX -@cindex Citations outside LaTeX -@vindex reftex-default-bibliography - -The command @code{reftex-citation} can also be executed outside a LaTeX -buffer. This can be useful to reference articles in the mail buffer and -other documents. You should @emph{not} enter @code{reftex-mode} for -this, just execute the command. The list of BibTeX files will in this -case be taken from the variable @code{reftex-default-bibliography}. -Setting the variable @code{reftex-cite-format} to the symbol -@code{locally} does a decent job of putting all relevant information -about a citation directly into the buffer. Here is the lisp code to add -the @kbd{C-c [} binding to the mail buffer. It also provides a local -binding for @code{reftex-cite-format}. - -@lisp -(add-hook 'mail-setup-hook - (lambda () (define-key mail-mode-map "\C-c[" - (lambda () - (interactive) - (let ((reftex-cite-format 'locally)) - (reftex-citation)))))) -@end lisp - -@node BibTeX Database Subsets, , Citations Outside LaTeX, Citations -@section Database Subsets -@cindex BibTeX database subsets -@findex reftex-create-bibtex-file - -@b{Ref@TeX{}} offers two ways to create a new BibTeX database file. - -The first option produces a file which contains only the entries -actually referenced in the current document. This can be useful if -the database in only meant for a single document and you want to clean -it of old and unused ballast. It can also be useful while writing a -document together with collaborators, in order to avoid sending around -the entire (possibly very large) database. To create the file, use -@kbd{M-x reftex-create-bibtex-file}, also available from the menu -under @code{Ref->Global Actions->Create Bibtex File}. The command will -prompt for a BibTeX file name and write the extracted entries to that -file. - -The second option makes use of the selection process started by the -command @kbd{C-c [} (@pxref{Creating Citations}). This command uses a -regular expression to select entries, and lists them in a formatted -selection buffer. After pressing the @kbd{e} key (mnemonics: Export), -the command will prompt for the name of a new BibTeX file and write -the selected entries to that file. You can also first mark some -entries in the selection buffer with the @kbd{m} key and then export -either the @i{marked} entries (with the @kbd{e} key) or the -@i{unmarked} entries (with the @kbd{E} key). - -@node Index Support, Viewing Cross-References, Citations, Top -@chapter Index Support -@cindex Index Support -@cindex @code{\index} - -LaTeX has builtin support for creating an Index. The LaTeX core -supports two different indices, the standard index and a glossary. With -the help of special LaTeX packages (@file{multind.sty} or -@file{index.sty}), any number of indices can be supported. - -Index entries are created with the @code{\index@{@var{entry}@}} macro. -All entries defined in a document are written out to the @file{.aux} -file. A separate tool must be used to convert this information into a -nicely formatted index. Tools used with LaTeX include @code{MakeIndex} -and @code{xindy}. - -Indexing is a very difficult task. It must follow strict conventions to -make the index consistent and complete. There are basically two -approaches one can follow, and both have their merits. - -@enumerate -@item -Part of the indexing should already be done with the markup. The -document structure should be reflected in the index, so when starting -new sections, the basic topics of the section should be indexed. If the -document contains definitions, theorems or the like, these should all -correspond to appropriate index entries. This part of the index can -very well be developed along with the document. Often it is worthwhile -to define special purpose macros which define an item and at the same -time make an index entry, possibly with special formatting to make the -reference page in the index bold or underlined. To make @b{Ref@TeX{}} -support for indexing possible, these special macros must be added to -@b{Ref@TeX{}}'s configuration (@pxref{Defining Index Macros}). - -@item -The rest of the index is often just a collection of where in the -document certain words or phrases are being used. This part is -difficult to develop along with the document, because consistent entries -for each occurrence are needed and are best selected when the document -is ready. @b{Ref@TeX{}} supports this with an @emph{index phrases file} -which collects phrases and helps indexing the phrases globally. -@end enumerate - -Before you start, you need to make sure that @b{Ref@TeX{}} knows about -the index style being used in the current document. @b{Ref@TeX{}} has -builtin support for the default @code{\index} and @code{\glossary} -macros. Other LaTeX packages, like the @file{multind} or @file{index} -package, redefine the @code{\index} macro to have an additional -argument, and @b{Ref@TeX{}} needs to be configured for those. A -sufficiently new version of AUCTeX (9.10c or later) will do this -automatically. If you really don't use AUCTeX (you should!), this -configuration needs to be done by hand with the menu (@code{Ref->Index -Style}), or globally for all your documents with - -@lisp -(setq reftex-index-macros '(multind)) @r{or} -(setq reftex-index-macros '(index)) -@end lisp - -@menu -* Creating Index Entries:: Macros and completion of entries. -* The Index Phrases File:: A special file for global indexing. -* Displaying and Editing the Index:: The index editor. -* Builtin Index Macros:: The index macros RefTeX knows about. -* Defining Index Macros:: ... and macros it doesn't. -@end menu - -@node Creating Index Entries, The Index Phrases File, , Index Support -@section Creating Index Entries -@cindex Creating index entries -@cindex Index entries, creating -@kindex C-c < -@findex reftex-index -@kindex C-c / -@findex reftex-index-selection-or-word - -In order to index the current selection or the word at the cursor press -@kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the -selection or word @samp{@var{word}} to be replaced with -@samp{\index@{@var{word}@}@var{word}}. The macro which is used -(@code{\index} by default) can be configured with the variable -@code{reftex-index-default-macro}. When the command is called with a -prefix argument (@kbd{C-u C-c /}), you get a chance to edit the -generated index entry. Use this to change the case of the word or to -make the entry a subentry, for example by entering -@samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes -(@kbd{C-u C-u C-c /}), you will be asked for the index macro as well. -When there is nothing selected and no word at point, this command will -just call @code{reftex-index}, described below. - -In order to create a general index entry, press @kbd{C-c <} -(@code{reftex-index}). @b{Ref@TeX{}} will prompt for one of the -available index macros and for its arguments. Completion will be -available for the index entry and, if applicable, the index tag. The -index tag is a string identifying one of multiple indices. With the -@file{multind} and @file{index} packages, this tag is the first argument -to the redefined @code{\index} macro. - -@node The Index Phrases File, Displaying and Editing the Index, Creating Index Entries, Index Support -@section The Index Phrases File -@cindex Index phrase file -@cindex Phrase file -@kindex C-c | -@findex reftex-index-visit-phrases-buffer -@cindex Macro definition lines, in phrase buffer - -@b{Ref@TeX{}} maintains a file in which phrases can be collected for -later indexing. The file is located in the same directory as the master -file of the document and has the extension @file{.rip} (@b{R}eftex -@b{I}ndex @b{P}hrases). You can create or visit the file with @kbd{C-c -|} (@code{reftex-index-visit-phrases-buffer}). If the file is empty it -is initialized by inserting a file header which contains the definition -of the available index macros. This list is initialized from -@code{reftex-index-macros} (@pxref{Defining Index Macros}). You can -edit the header as needed, but if you define new LaTeX indexing macros, -don't forget to add them to @code{reftex-index-macros} as well. Here is -a phrase file header example: - -@example -% -*- mode: reftex-index-phrases -*- -% Key Macro Format Repeat -%---------------------------------------------------------- ->>>INDEX_MACRO_DEFINITION: i \index@{%s@} t ->>>INDEX_MACRO_DEFINITION: I \index*@{%s@} nil ->>>INDEX_MACRO_DEFINITION: g \glossary@{%s@} t ->>>INDEX_MACRO_DEFINITION: n \index*[name]@{%s@} nil -%---------------------------------------------------------- -@end example - -The macro definition lines consist of a unique letter identifying a -macro, a format string and the @var{repeat} flag, all separated by -@key{TAB}. The format string shows how the macro is to be applied, the -@samp{%s} will be replaced with the index entry. The repeat flag -indicates if @var{word} is indexed by the macro as -@samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as -@samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}). In the -above example it is assumed that the macro @code{\index*@{@var{word}@}} -already typesets its argument in the text, so that it is unnecessary to -repeat @var{word} outside the macro. - -@menu -* Collecting Phrases:: Collecting from document or external. -* Consistency Checks:: Check for duplicates etc. -* Global Indexing:: The interactive indexing process. -@end menu - -@node Collecting Phrases, Consistency Checks, , The Index Phrases File -@subsection Collecting Phrases -@cindex Collecting index phrases -@cindex Index phrases, collection -@cindex Phrases, collecting - -Phrases for indexing can be collected while writing the document. The -command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) -copies the current selection (if active) or the word near point into the -phrases buffer. It then selects this buffer, so that the phrase line -can be edited. To return to the LaTeX document, press @kbd{C-c C-c} -(@code{reftex-index-phrases-save-and-return}). - -You can also prepare the list of index phrases in a different way and -copy it into the phrases file. For example you might want to start from -a word list of the document and remove all words which should not be -indexed. - -The phrase lines in the phrase buffer must have a specific format. -@b{Ref@TeX{}} will use font-lock to indicate if a line has the proper -format. A phrase line looks like this: - -@example -[@var{key}] @var{phrase} [ @var{arg}[&&@var{arg}]... [ || @var{arg}]...] -@end example - -@code{} stands for white space containing at least one @key{TAB}. -@var{key} must be at the start of the line and is the character -identifying one of the macros defined in the file header. It is -optional - when omitted, the first macro definition line in the file -will be used for this phrase. The @var{phrase} is the phrase to be -searched for when indexing. It may contain several words separated by -spaces. By default the search phrase is also the text entered as -argument of the index macro. If you want the index entry to be -different from the search phrase, enter another @key{TAB} and the index -argument @var{arg}. If you want to have each match produce several -index entries, separate the different index arguments with @samp{ && -}@footnote{@samp{&&} with optional spaces, see -@code{reftex-index-phrases-logical-and-regexp}.}. If you want to be -able to choose at each match between several different index arguments, -separate them with @samp{ || }@footnote{@samp{||} with optional spaces, -see @code{reftex-index-phrases-logical-or-regexp}.}. Here is an -example: - -@example -%-------------------------------------------------------------------- -I Sun -i Planet Planets -i Vega Stars!Vega - Jupiter Planets!Jupiter -i Mars Planets!Mars || Gods!Mars || Chocolate Bars!Mars -i Pluto Planets!Pluto && Kuiper Belt Objects!Pluto -@end example - - -So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while -@samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}. -@samp{Vega} will be indexed as a subitem of @samp{Stars}. The -@samp{Jupiter} line will also use the @samp{i} macro as it was the first -macro definition in the file header (see above example). At each -occurrence of @samp{Mars} you will be able choose between indexing it as -a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}. -Finally, every occurrence of @samp{Pluto} will be indexed as -@samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto} -and will therefore create two different index entries. - -@node Consistency Checks, Global Indexing, Collecting Phrases, The Index Phrases File -@subsection Consistency Checks -@cindex Index phrases, consistency checks -@cindex Phrases, consistency checks -@cindex Consistency check for index phrases - -@kindex C-c C-s -Before indexing the phrases in the phrases buffer, they should be -checked carefully for consistency. A first step is to sort the phrases -alphabetically - this is done with the command @kbd{C-c C-s} -(@code{reftex-index-sort-phrases}). It will sort all phrases in the -buffer alphabetically by search phrase. If you want to group certain -phrases and only sort within the groups, insert empty lines between the -groups. Sorting will only change the sequence of phrases within each -group (see the variable @code{reftex-index-phrases-sort-in-blocks}). - -@kindex C-c C-i -A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info}) -which lists information about the phrase at point, including an example -of how the index entry will look like and the number of expected matches -in the document. - -@kindex C-c C-t -Another important check is to find out if there are double or -overlapping entries in the buffer. For example if you are first -searching and indexing @samp{Mars} and then @samp{Planet Mars}, the -second phrase will not match because of the index macro inserted before -@samp{Mars} earlier. The command @kbd{C-c C-t} -(@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in -the buffer which is either duplicate or a subphrase of another phrase. -In order to check the whole buffer like this, start at the beginning and -execute this command repeatedly. - -@node Global Indexing, , Consistency Checks, The Index Phrases File -@subsection Global Indexing -@cindex Global indexing -@cindex Indexing, global -@cindex Indexing, from @file{phrases} buffer - -Once the index phrases have been collected and organized, you are set -for global indexing. I recommend to do this only on an otherwise -finished document. Global indexing starts from the phrases buffer. -There are several commands which start indexing: @kbd{C-c C-x} acts on -the current phrase line, @kbd{C-c C-r} on all lines in the current -region and @kbd{C-c C-a} on all phrase lines in the buffer. It is -probably good to do indexing in small chunks since your concentration -may not last long enough to do everything in one go. - -@b{Ref@TeX{}} will start at the first phrase line and search the phrase -globally in the whole document. At each match it will stop, compute the -replacement string and offer you the following choices@footnote{Windows -users: Restrict yourself to the described keys during indexing. Pressing -@key{Help} at the indexing prompt can apparently hang Emacs.}: - -@table @kbd -@item y -Replace this match with the proposed string. -@item n -Skip this match. -@item ! -Replace this and all further matches in this file. -@item q -Skip this match, start with next file. -@item Q -Skip this match, start with next phrase. -@item o -Select a different indexing macro for this match. -@item 1-9 -Select one of multiple index keys (those separated with @samp{||}). -@item e -Edit the replacement text. -@item C-r -Recursive edit. Use @kbd{C-M-c} to return to the indexing process. -@item s -Save this buffer and ask again about the current match. -@item S -Save all document buffers and ask again about the current match. -@item C-g -Abort the indexing process. -@end table - -The @samp{Find and Index in Document} menu in the phrases buffer also -lists a few options for the indexing process. The options have -associated customization variables to set the defaults (@pxref{Options -(Index Support)}). Here is a short explanation of what the options do: - -@table @i -@item Match Whole Words -When searching for index phrases, make sure whole words are matched. -This should probably always be on. -@item Case Sensitive Search -Search case sensitively for phrases. I recommend to have this setting -off, in order to match the capitalized words at the beginning of a -sentence, and even typos. You can always say @emph{no} at a match you -do not like. -@item Wrap Long Lines -Inserting index macros increases the line length. Turn this option on -to allow @b{Ref@TeX{}} to wrap long lines. -@item Skip Indexed Matches -When this is on, @b{Ref@TeX{}} will at each match try to figure out if -this match is already indexed. A match is considered indexed if it is -either the argument of an index macro, or if an index macro is directly -(without whitespace separation) before or after the match. Index macros -are those configured in @code{reftex-index-macros}. Intended for -re-indexing a documents after changes have been made. -@end table - -Even though indexing should be the last thing you do to a document, you -are bound to make changes afterwards. Indexing then has to be applied -to the changed regions. The command -@code{reftex-index-phrases-apply-to-region} is designed for this -purpose. When called from a LaTeX document with active region, it will -apply @code{reftex-index-all-phrases} to the current region. - -@node Displaying and Editing the Index, Builtin Index Macros, The Index Phrases File, Index Support -@section Displaying and Editing the Index -@cindex Displaying the Index -@cindex Editing the Index -@cindex Index entries, creating -@cindex Index, displaying -@cindex Index, editing -@kindex C-c > -@findex reftex-display-index - -In order to compile and display the index, press @kbd{C-c >}. If the -document uses multiple indices, @b{Ref@TeX{}} will ask you to select -one. Then, all index entries will be sorted alphabetically and -displayed in a special buffer, the @file{*Index*} buffer. From that -buffer you can check and edit each entry. - -The index can be restricted to the current section or the region. Then -only entries in that part of the document will go into the compiled -index. To restrict to the current section, use a numeric prefix -@samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current -region, make the region active and use a numeric prefix @samp{3} (press -@kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the -restriction can be moved from one section to the next by pressing the -@kbd{<} and @kbd{>} keys. - -One caveat: @b{Ref@TeX{}} finds the definition point of an index entry -by searching near the buffer position where it had found to macro during -scanning. If you have several identical index entries in the same -buffer and significant changes have shifted the entries around, you must -rescan the buffer to ensure the correspondence between the -@file{*Index*} buffer and the definition locations. It is therefore -advisable to rescan the document (with @kbd{r} or @kbd{C-u r}) -frequently while editing the index from the @file{*Index*} -buffer. - -@kindex ? -Here is a list of special commands available in the @file{*Index*} buffer. A -summary of this information is always available by pressing -@kbd{?}. - -@table @kbd -@tablesubheading{General} -@item ? -Display a summary of commands. - -@item 0-9, - -Prefix argument. - -@tablesubheading{Moving around} -@item ! A..Z -Pressing any capital letter will jump to the corresponding section in -the @file{*Index*} buffer. The exclamation mark is special and jumps to -the first entries alphabetically sorted below @samp{A}. These are -usually non-alphanumeric characters. -@item n -Go to next entry. -@item p -Go to previous entry. - -@tablesubheading{Access to document locations} -@item @key{SPC} -Show the place in the document where this index entry is defined. - -@item @key{TAB} -Go to the definition of the current index entry in another -window. - -@item @key{RET} -Go to the definition of the current index entry and hide the -@file{*Index*} buffer window. - -@item f -@vindex reftex-index-follow-mode -@vindex reftex-revisit-to-follow -Toggle follow mode. When follow mode is active, the other window will -always show the location corresponding to the line in the @file{*Index*} -buffer at point. This is similar to pressing @key{SPC} after each -cursor motion. The default for this flag can be set with the variable -@code{reftex-index-follow-mode}. Note that only context in files -already visited is shown. @b{Ref@TeX{}} will not visit a file just for -follow mode. See, however, the variable -@code{reftex-revisit-to-follow}. - -@tablesubheading{Entry editing} -@item e -Edit the current index entry. In the minibuffer, you can edit the -index macro which defines this entry. - -@item C-k -Kill the index entry. Currently not implemented because I don't know -how to implement an @code{undo} function for this. - -@item * -Edit the @var{key} part of the entry. This is the initial part of the -entry which determines the location of the entry in the index. - -@item | -Edit the @var{attribute} part of the entry. This is the part after the -vertical bar. With @code{MakeIndex}, this part is an encapsulating -macro. With @code{xindy}, it is called @emph{attribute} and is a -property of the index entry that can lead to special formatting. When -called with @kbd{C-u} prefix, kill the entire @var{attribute} -part. - -@item @@ -Edit the @var{visual} part of the entry. This is the part after the -@samp{@@} which is used by @code{MakeIndex} to change the visual -appearance of the entry in the index. When called with @kbd{C-u} -prefix, kill the entire @var{visual} part. - -@item ( -Toggle the beginning of page range property @samp{|(} of the -entry. - -@item ) -Toggle the end of page range property @samp{|)} of the entry. - -@item _ -Make the current entry a subentry. This command will prompt for the -superordinate entry and insert it. - -@item ^ -Remove the highest superordinate entry. If the current entry is a -subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy -(@samp{bbb!ccc}). - -@tablesubheading{Exiting} -@item q -Hide the @file{*Index*} buffer. - -@item k -Kill the @file{*Index*} buffer. - -@item C-c = -Switch to the Table of Contents buffer of this document. - -@tablesubheading{Controlling what gets displayed} -@item c -@vindex reftex-index-include-context -Toggle the display of short context in the @file{*Index*} buffer. The -default for this flag can be set with the variable -@code{reftex-index-include-context}. - -@item @} -Restrict the index to a single document section. The corresponding -section number will be displayed in the @code{R<>} indicator in the -mode line and in the header of the @file{*Index*} buffer. - -@item @{ -Widen the index to contain all entries of the document. - -@item < -When the index is currently restricted, move the restriction to the -previous section. - -@item > -When the index is currently restricted, move the restriction to the -next section. - -@tablesubheading{Updating the buffer} -@item g -Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the -document. However, it sorts the entries again, so that edited entries -will move to the correct position. - -@item r -@vindex reftex-enable-partial-scans -Reparse the LaTeX document and rebuild the @file{*Index*} buffer. When -@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this -location is defined in, not the entire document. - -@item C-u r -Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*} -buffer. - -@item s -Switch to a different index (for documents with multiple -indices). -@end table - - -@node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support -@section Builtin Index Macros -@cindex Builtin index macros -@cindex Index macros, builtin -@vindex reftex-index-macros -@cindex @code{multind}, LaTeX package -@cindex @code{index}, LaTeX package -@cindex LaTeX packages, @code{multind} -@cindex LaTeX packages, @code{index} - -@b{Ref@TeX{}} by default recognizes the @code{\index} and -@code{\glossary} macros which are defined in the LaTeX core. It has -also builtin support for the re-implementations of @code{\index} -in the @file{multind} and @file{index} packages. However, since -the different definitions of the @code{\index} macro are incompatible, -you will have to explicitly specify the index style used. -@xref{Creating Index Entries}, for information on how to do that. - -@node Defining Index Macros, , Builtin Index Macros, Index Support -@section Defining Index Macros -@cindex Defining Index Macros -@cindex Index macros, defining -@vindex reftex-index-macros - -When writing a document with an index you will probably define -additional macros which make entries into the index. -Let's look at an example. - -@example -\newcommand@{\ix@}[1]@{#1\index@{#1@}@} -\newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@} -\newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@} -@end example - -The first macro @code{\ix} typesets its argument in the text and places -it into the index. The second macro @code{\nindex} typesets its -argument in the text and places it into a separate index with the tag -@samp{name}@footnote{We are using the syntax of the @file{index} package -here.}. The last macro also places its argument into the index, but as -subitems under the main index entry @samp{Astronomical Objects}. Here -is how to make @b{Ref@TeX{}} recognize and correctly interpret these -macros, first with Emacs Lisp. - -@lisp -(setq reftex-index-macros - '(("\\ix@{*@}" "idx" ?x "" nil nil) - ("\\nindex@{*@}" "name" ?n "" nil nil) - ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t))) -@end lisp - -Note that the index tag is @samp{idx} for the main index, and -@samp{name} for the name index. @samp{idx} and @samp{glo} are reserved -for the default index and for the glossary. - -The character arguments @code{?x}, @code{?n}, and @code{?o} are for -quick identification of these macros when @b{Ref@TeX{}} inserts new -index entries with @code{reftex-index}. These codes need to be -unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the -@code{\index}, @code{\index*}, and @code{\glossary} macros, -respectively. - -The following string is empty unless your macro adds a superordinate -entry to the index key - this is the case for the @code{\astobj} macro. - -The next entry can be a hook function to exclude certain matches, it -almost always can be @code{nil}. - -The final element in the list indicates if the text being indexed needs -to be repeated outside the macro. For the normal index macros, this -should be @code{t}. Only if the macro typesets the entry in the text -(like @code{\ix} and @code{\nindex} in the example do), this should be -@code{nil}. - -To do the same thing with customize, you need to fill in the templates -like this: - -@example -Repeat: -[INS] [DEL] List: - Macro with args: \ix@{*@} - Index Tag : [Value Menu] String: idx - Access Key : x - Key Prefix : - Exclusion hook : nil - Repeat Outside : [Toggle] off (nil) -[INS] [DEL] List: - Macro with args: \nindex@{*@} - Index Tag : [Value Menu] String: name - Access Key : n - Key Prefix : - Exclusion hook : nil - Repeat Outside : [Toggle] off (nil) -[INS] [DEL] List: - Macro with args: \astobj@{*@} - Index Tag : [Value Menu] String: idx - Access Key : o - Key Prefix : Astronomical Objects! - Exclusion hook : nil - Repeat Outside : [Toggle] on (non-nil) -[INS] -@end example - -With the macro @code{\ix} defined, you may want to change the default -macro used for indexing a text phrase (@pxref{Creating Index Entries}). -This would be done like this - -@lisp -(setq reftex-index-default-macro '(?x "idx")) -@end lisp - -which specifies that the macro identified with the character @code{?x} (the -@code{\ix} macro) should be used for indexing phrases and words already -in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}). -The index tag is "idx". - -@node Viewing Cross-References, RefTeXs Menu, Index Support, Top -@chapter Viewing Cross--References -@findex reftex-view-crossref -@findex reftex-mouse-view-crossref -@kindex C-c & -@kindex S-mouse-2 - -@b{Ref@TeX{}} can display cross--referencing information. This means, -if two document locations are linked, @b{Ref@TeX{}} can display the -matching location(s) in another window. The @code{\label} and @code{\ref} -macros are one way of establishing such a link. Also, a @code{\cite} -macro is linked to the corresponding @code{\bibitem} macro or a BibTeX -database entry. - -The feature is invoked by pressing @kbd{C-c &} -(@code{reftex-view-crossref}) while point is on the @var{key} argument -of a macro involved in cross--referencing. You can also click with -@kbd{S-mouse-2} on the macro argument. Here is what will happen for -individual classes of macros: - -@table @asis - -@item @code{\ref} -@cindex @code{\ref} -Display the corresponding label definition. All usual -variants@footnote{all macros that start with @samp{ref} or end with -@samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for -cross--reference display. This works also for labels defined in an -external document when the current document refers to them through the -@code{xr} interface (@pxref{xr (LaTeX package)}). - -@item @code{\label} -@cindex @code{\label} -@vindex reftex-label-alist -Display a document location which references this label. Pressing -@kbd{C-c &} several times moves through the entire document and finds -all locations. Not only the @code{\label} macro but also other macros -with label arguments (as configured with @code{reftex-label-alist}) are -active for cross--reference display. - -@item @code{\cite} -@cindex @code{\cite} -Display the corresponding BibTeX database entry or @code{\bibitem}. -All usual variants@footnote{all macros that either start or end with -@samp{cite}} of the @code{\cite} macro are active for cross--reference -display. - -@item @code{\bibitem} -@cindex @code{\bibitem} -Display a document location which cites this article. Pressing -@kbd{C-c &} several times moves through the entire document and finds -all locations. - -@item BibTeX -@cindex BibTeX buffer, viewing cite locations from -@cindex Viewing cite locations from BibTeX buffer -@kbd{C-c &} is also active in BibTeX buffers. All locations in a -document where the database entry at point is cited will be displayed. -On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to -the document you want to search. Subsequent calls will use the same -document, until you break this link with a prefix argument to @kbd{C-c -&}. - -@item @code{\index} -@cindex @code{\index} -Display other locations in the document which are marked by an index -macro with the same key argument. Along with the standard @code{\index} -and @code{\glossary} macros, all macros configured in -@code{reftex-index-macros} will be recognized. -@end table - -@vindex reftex-view-crossref-extra -While the display of cross referencing information for the above -mentioned macros is hard--coded, you can configure additional relations -in the variable @code{reftex-view-crossref-extra}. - -@iftex -@chapter All the Rest -@end iftex - -@node RefTeXs Menu, Key Bindings, Viewing Cross-References, Top -@section @b{Ref@TeX{}}'s Menu -@cindex RefTeXs Menu -@cindex Menu, in the menu bar - -@b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems -which support this. From this menu you can access all of -@b{Ref@TeX{}}'s commands and a few of its options. There is also a -@code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s -entire set of options. - -@node Key Bindings, Faces, RefTeXs Menu, Top -@section Default Key Bindings -@cindex Key Bindings, summary - -Here is a summary of the available key bindings. - -@kindex C-c = -@kindex C-c - -@kindex C-c ( -@kindex C-c ) -@kindex C-c [ -@kindex C-c & -@kindex S-mouse-2 -@kindex C-c / -@kindex C-c \ -@kindex C-c | -@kindex C-c < -@kindex C-c > -@example -@kbd{C-c =} @code{reftex-toc} -@kbd{C-c -} @code{reftex-toc-recenter} -@kbd{C-c (} @code{reftex-label} -@kbd{C-c )} @code{reftex-reference} -@kbd{C-c [} @code{reftex-citation} -@kbd{C-c &} @code{reftex-view-crossref} -@kbd{S-mouse-2} @code{reftex-mouse-view-crossref} -@kbd{C-c /} @code{reftex-index-selection-or-word} -@kbd{C-c \} @code{reftex-index-phrase-selection-or-word} -@kbd{C-c |} @code{reftex-index-visit-phrases-buffer} -@kbd{C-c <} @code{reftex-index} -@kbd{C-c >} @code{reftex-display-index} -@end example - -Note that the @kbd{S-mouse-2} binding is only provided if this key is -not already used by some other package. @b{Ref@TeX{}} will not override an -existing binding to @kbd{S-mouse-2}. - -Personally, I also bind some functions in the users @kbd{C-c} map for -easier access. - -@c FIXME: Do we need bindings for the Index macros here as well? -@c C-c i C-c I or so???? -@c How about key bindings for reftex-reset-mode and reftex-parse-document? -@kindex C-c t -@kindex C-c l -@kindex C-c r -@kindex C-c c -@kindex C-c v -@kindex C-c s -@kindex C-c g -@example -@kbd{C-c t} @code{reftex-toc} -@kbd{C-c l} @code{reftex-label} -@kbd{C-c r} @code{reftex-reference} -@kbd{C-c c} @code{reftex-citation} -@kbd{C-c v} @code{reftex-view-crossref} -@kbd{C-c s} @code{reftex-search-document} -@kbd{C-c g} @code{reftex-grep-document} -@end example - -@noindent These keys are reserved for the user, so I cannot bind them by -default. If you want to have these key bindings available, set in your -@file{.emacs} file: - -@vindex reftex-extra-bindings -@lisp -(setq reftex-extra-bindings t) -@end lisp - -@vindex reftex-load-hook -Changing and adding to @b{Ref@TeX{}}'s key bindings is best done in the hook -@code{reftex-load-hook}. For information on the keymaps -which should be used to add keys, see @ref{Keymaps and Hooks}. - -@node Faces, AUCTeX, Key Bindings, Top -@section Faces -@cindex Faces - -@b{Ref@TeX{}} uses faces when available to structure the selection and -table of contents buffers. It does not create its own faces, but uses -the ones defined in @file{font-lock.el}. Therefore, @b{Ref@TeX{}} will -use faces only when @code{font-lock} is loaded. This seems to be -reasonable because people who like faces will very likely have it -loaded. If you wish to turn off fontification or change the involved -faces, see @ref{Options (Fontification)}. - -@node Multifile Documents, Language Support, AUCTeX, Top -@section Multifile Documents -@cindex Multifile documents -@cindex Documents, spread over files - -The following is relevant when working with documents spread over many -files: - -@itemize @bullet -@item -@b{Ref@TeX{}} has full support for multifile documents. You can edit parts of -several (multifile) documents at the same time without conflicts. -@b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and -@code{query-replace} on all files which are part of a multifile -document. - -@item -@vindex tex-main-file -@vindex TeX-master -All files belonging to a multifile document should define a File -Variable (@code{TeX-master} for AUCTeX or @code{tex-main-file} for the -standard Emacs LaTeX mode) containing the name of the master file. For -example, to set the file variable @code{TeX-master}, include something -like the following at the end of each TeX file: - -@example -%%% Local Variables: *** -%%% mode:latex *** -%%% TeX-master: "thesis.tex" *** -%%% End: *** -@end example - -AUCTeX with the setting - -@lisp -(setq-default TeX-master nil) -@end lisp - -will actually ask you for each new file about the master file and insert -this comment automatically. For more details see the documentation of -the AUCTeX (@pxref{Multifile,,,auctex, The AUC TeX User Manual}), the -documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs, -The GNU Emacs Manual}) and the Emacs documentation on File Variables -(@pxref{File Variables,,,emacs, The GNU Emacs Manual}). - -@item -The context of a label definition must be found in the same file as the -label itself in order to be processed correctly by @b{Ref@TeX{}}. The only -exception is that section labels referring to a section statement -outside the current file can still use that section title as -context. -@end itemize - -@node Language Support, Finding Files, Multifile Documents, Top -@section Language Support -@cindex Language support - -Some parts of @b{Ref@TeX{}} are language dependent. The default -settings work well for English. If you are writing in a different -language, the following hints may be useful: - -@itemize @bullet -@item -@vindex reftex-derive-label-parameters -@vindex reftex-abbrev-parameters -The mechanism to derive a label from context includes the abbreviation -of words and omission of unimportant words. These mechanisms may have -to be changed for other languages. See the variables -@code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}. - -@item -@vindex reftex-translate-to-ascii-function -@vindex reftex-label-illegal-re -Also, when a label is derived from context, @b{Ref@TeX{}} clears the -context string from non-ASCII characters in order to make a valid label. -If there should ever be a version of @TeX{} which allows extended -characters @emph{in labels}, then we will have to look at the -variables @code{reftex-translate-to-ascii-function} and -@code{reftex-label-illegal-re}. - -@item -When a label is referenced, @b{Ref@TeX{}} looks at the word before point -to guess which label type is required. These @emph{magic words} are -different in every language. For an example of how to add magic words, -see @ref{Adding Magic Words}. - -@vindex reftex-multiref-punctuation -@vindex reftex-cite-punctuation -@item -@b{Ref@TeX{}} inserts ``punctuation'' for multiple references and -for the author list in citations. Some of this may be language -dependent. See the variables @code{reftex-multiref-punctuation} and -@code{reftex-cite-punctuation}. -@end itemize - -@node Finding Files, Optimizations, Language Support, Top -@section Finding Files -@cindex Finding files - -In order to find files included in a document via @code{\input} or -@code{\include}, @b{Ref@TeX{}} searches all directories specified in the -environment variable @code{TEXINPUTS}. Similarly, it will search the -path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for -BibTeX database files. - -When searching, @b{Ref@TeX{}} will also expand recursive path -definitions (directories ending in @samp{//} or @samp{!!}). But it will -only search and expand directories @emph{explicitly} given in these -variables. This may cause problems under the following circumstances: - -@itemize @bullet -@item -Most TeX system have a default search path for both TeX files and BibTeX -files which is defined in some setup file. Usually this default path is -for system files which @b{Ref@TeX{}} does not need to see. But if your -document needs TeX files or BibTeX database files in a directory only -given in the default search path, @b{Ref@TeX{}} will fail to find them. -@item -Some TeX systems do not use environment variables at all in order to -specify the search path. Both default and user search path are then -defined in setup files. -@end itemize - -@noindent -There are three ways to solve this problem: - -@itemize @bullet -@item -Specify all relevant directories explicitly in the environment -variables. If for some reason you don't want to mess with the default -variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own -variables and configure @b{Ref@TeX{}} to use them instead: - -@lisp -(setq reftex-texpath-environment-variables '("MYTEXINPUTS")) -(setq reftex-bibpath-environment-variables '("MYBIBINPUTS")) -@end lisp - -@item -Specify the full search path directly in @b{Ref@TeX{}}'s variables. - -@lisp -(setq reftex-texpath-environment-variables - '("./inp:/home/cd/tex//:/usr/local/tex//")) -(setq reftex-bibpath-environment-variables - '("/home/cd/tex/lit/")) -@end lisp - -@item -Some TeX systems provide stand--alone programs to do the file search just -like TeX and BibTeX. E.g. Thomas Esser's @code{teTeX} uses the -@code{kpathsearch} library which provides the command @code{kpsewhich} -to search for files. @b{Ref@TeX{}} can be configured to use this -program. Note that the exact syntax of the @code{kpsewhich} -command depends upon the version of that program. - -@lisp -(setq reftex-use-external-file-finders t) -(setq reftex-external-file-finders - '(("tex" . "kpsewhich -format=.tex %f") - ("bib" . "kpsewhich -format=.bib %f"))) -@end lisp -@end itemize - -@cindex Noweb files -@vindex reftex-file-extensions -@vindex TeX-file-extensions -Some people like to use RefTeX with noweb files, which usually have the -extension @file{.nw}. In order to deal with such files, the new -extension must be added to the list of valid extensions in the variable -@code{reftex-file-extensions}. When working with AUCTeX as major mode, -the new extension must also be known to AUCTeX via the variable -@code{TeX-file-extension}. For example: - -@lisp -(setq reftex-file-extensions - '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib"))) -(setq TeX-file-extensions - '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo")) -@end lisp - -@node Optimizations, Problems and Work-Arounds, Finding Files, Top -@section Optimizations -@cindex Optimizations - -@b{Note added 2002. Computers have gotten a lot faster, so most of the -optimizations discussed below will not be necessary on new machines. I -am leaving this stuff in the manual for people who want to write thick -books, where some of it still might be useful.} - -Implementing the principle of least surprises, the default settings of -@b{Ref@TeX{}} ensure a safe ride for beginners and casual users. However, -when using @b{Ref@TeX{}} for a large project and/or on a small computer, -there are ways to improve speed or memory usage. - -@itemize @bullet -@item -@b{Removing Lookup Buffers}@* -@cindex Removing lookup buffers -@b{Ref@TeX{}} will load other parts of a multifile document as well as BibTeX -database files for lookup purposes. These buffers are kept, so that -subsequent use of the same files is fast. If you can't afford keeping -these buffers around, and if you can live with a speed penalty, try - -@vindex reftex-keep-temporary-buffers -@lisp -(setq reftex-keep-temporary-buffers nil) -@end lisp - -@item -@b{Partial Document Scans}@* -@cindex Partial documents scans -@cindex Document scanning, partial -A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label} -(@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}), -@code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c -=}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates -re-parsing of the entire document in order to update the parsing -information. For a large document this can be unnecessary, in -particular if only one file has changed. @b{Ref@TeX{}} can be configured -to do partial scans instead of full ones. @kbd{C-u} re-parsing then -does apply only to the current buffer and files included from it. -Likewise, the @kbd{r} key in both the label selection buffer and the -table-of-contents buffer will only prompt scanning of the file in which -the label or section macro near the cursor was defined. Re-parsing of -the entire document is still available by using @kbd{C-u C-u} as a -prefix, or the capital @kbd{R} key in the menus. To use this feature, -try - -@vindex reftex-enable-partial-scans -@lisp -(setq reftex-enable-partial-scans t) -@end lisp - -@item -@b{Saving Parser Information}@* -@cindex Saving parser information -@cindex Parse information, saving to a file -@vindex reftex-parse-file-extension -Even with partial scans enabled, @b{Ref@TeX{}} still has to make one full -scan, when you start working with a document. To avoid this, parsing -information can be stored in a file. The file @file{MASTER.rel} is used -for storing information about a document with master file -@file{MASTER.tex}. It is written automatically when you kill a buffer -in @code{reftex-mode} or when you exit Emacs. The information is -restored when you begin working with a document in a new editing -session. To use this feature, put into @file{.emacs}: - -@vindex reftex-save-parse-info -@lisp -(setq reftex-save-parse-info t) -@end lisp - -@item -@b{Identifying label types by prefix}@* -@cindex Parse information, saving to a file -@vindex reftex-trust-label-prefix -@b{Ref@TeX{}} normally parses around each label to check in which -environment this label is located, in order to assign a label type to -the label. If your document contains thousands of labels, document -parsing will take considerable time. If you have been using label prefixes -like tab: and fn: consistently, you can tell @b{Ref@TeX{}} to get the -label type directly from the prefix, without additional parsing. This -will be faster and also allow labels to end up in the correct category -if for some reason it is not possible to derive the correct type from -context. For example, to enable this feature for footnote and -equation labels, use - -@lisp -(setq reftex-trust-label-prefix '("fn:" "eq:")) -@end lisp - -@item -@b{Automatic Document Scans}@* -@cindex Automatic document scans -@cindex Document scanning, automatic -At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the -document. If this gets into your way, it can be turned off with - -@vindex reftex-allow-automatic-rescan -@lisp -(setq reftex-allow-automatic-rescan nil) -@end lisp - -@b{Ref@TeX{}} will then occasionally annotate new labels in the selection -buffer, saying that their position in the label list in uncertain. A -manual document scan will fix this. - -@item -@b{Multiple Selection Buffers}@* -@cindex Multiple selection buffers -@cindex Selection buffers, multiple -Normally, the selection buffer @file{*RefTeX Select*} is re-created for -every selection process. In documents with very many labels this can -take several seconds. @b{Ref@TeX{}} provides an option to create a -separate selection buffer for each label type and to keep this buffer -from one selection to the next. These buffers are updated automatically -only when a new label has been added in the buffers category with -@code{reftex-label}. Updating the buffer takes as long as recreating it -- so the time saving is limited to cases where no new labels of that -category have been added. To turn on this feature, use - -@vindex reftex-use-multiple-selection-buffers -@lisp -(setq reftex-use-multiple-selection-buffers t) -@end lisp - -@noindent -@cindex Selection buffers, updating -You can also inhibit the automatic updating entirely. Then the -selection buffer will always pop up very fast, but may not contain the -most recently defined labels. You can always update the buffer by hand, -with the @kbd{g} key. To get this behavior, use instead - -@vindex reftex-auto-update-selection-buffers -@lisp -(setq reftex-use-multiple-selection-buffers t - reftex-auto-update-selection-buffers nil) -@end lisp -@end itemize - -@need 2000 -@noindent -@b{As a summary}, here are the settings I recommend for heavy use of -@b{Ref@TeX{}} with large documents: - -@lisp -@group -(setq reftex-enable-partial-scans t - reftex-save-parse-info t - reftex-use-multiple-selection-buffers t) -@end group -@end lisp - -@node AUCTeX, Multifile Documents, Faces, Top -@section AUC@TeX{} -@cindex @code{AUCTeX}, Emacs package -@cindex Emacs packages, @code{AUCTeX} - -AUCTeX is without doubt the best major mode for editing TeX and LaTeX -files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}). -If AUCTeX is not part of your Emacs distribution, you can get -it@footnote{XEmacs 21.x users may want to install the corresponding -XEmacs package.} by ftp from the @value{AUCTEXSITE}. - -@menu -* AUCTeX-RefTeX Interface:: How both packages work together -* Style Files:: AUCTeX's style files can support RefTeX -* Bib-Cite:: Hypertext reading of a document -@end menu - -@node AUCTeX-RefTeX Interface, Style Files, , AUCTeX -@subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface - -@b{Ref@TeX{}} contains code to interface with AUCTeX. When this -interface is turned on, both packages will interact closely. Instead of -using @b{Ref@TeX{}}'s commands directly, you can then also use them -indirectly as part of the AUCTeX -environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be -needed for all of this to work. Parts of it work also with earlier -versions.}. The interface is turned on with - -@lisp -(setq reftex-plug-into-AUCTeX t) -@end lisp - -If you need finer control about which parts of the interface are used -and which not, read the docstring of the variable -@code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x -customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}. - -The following list describes the individual parts of the interface. - -@itemize @bullet -@item -@findex reftex-label -@vindex LaTeX-label-function, @r{AUCTeX} -@kindex C-c C-e -@kindex C-c C-s -@findex LaTeX-section, @r{AUCTeX} -@findex TeX-insert-macro, @r{AUCTeX} -@b{AUCTeX calls @code{reftex-label} to insert labels}@* -When a new section is created with @kbd{C-c C-s}, or a new environment -is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to -go with it. With the interface, @code{reftex-label} is called instead. -For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and -@b{Ref@TeX{}} will insert - -@example -\begin@{equation@} -\label@{eq:1@} - -\end@{equation@} -@end example - -@noindent -without further prompts. - -Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}} -will offer its default label which is derived from the section title. - -@item -@b{AUCTeX tells @b{Ref@TeX{}} about new sections}@* -When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not -have to rescan the buffer in order to see it. - -@item -@findex reftex-arg-label -@findex TeX-arg-label, @r{AUCTeX function} -@findex reftex-arg-ref -@findex TeX-arg-ref, @r{AUCTeX function} -@findex reftex-arg-cite -@findex TeX-arg-cite, @r{AUCTeX function} -@findex reftex-arg-index -@findex TeX-arg-index, @r{AUCTeX function} -@findex TeX-insert-macro, @r{AUCTeX function} -@kindex C-c @key{RET} -@b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro -interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for -macro arguments. Internally, it uses the functions -@code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to -prompt for arguments which are labels, citation keys and index entries. -The interface takes over these functions@footnote{@code{fset} is used to -do this, which is not reversible. However, @b{Ref@TeX{}} implements the -old functionality when you later decide to turn off the interface.} and -supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms. For -example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}} -will supply its label selection process (@pxref{Referencing -Labels}). - -@item -@b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@* -@b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list. -@end itemize - -@node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX -@subsection Style Files -@cindex Style files, AUCTeX -@findex TeX-add-style-hook, @r{AUCTeX} -Style files are Emacs Lisp files which are evaluated by AUCTeX in -association with the @code{\documentclass} and @code{\usepackage} -commands of a document (@pxref{Style Files,,,auctex}). Support for -@b{Ref@TeX{}} in such a style file is useful when the LaTeX style -defines macros or environments connected with labels, citations, or the -index. Many style files (e.g. @file{amsmath.el} or @file{natbib.el}) -distributed with AUCTeX already support @b{Ref@TeX{}} in this -way. - -Before calling a @b{Ref@TeX{}} function, the style hook should always -test for the availability of the function, so that the style file will -also work for people who do not use @b{Ref@TeX{}}. - -Additions made with style files in the way described below remain local -to the current document. For example, if one package uses AMSTeX, the -style file will make @b{Ref@TeX{}} switch over to @code{\eqref}, but -this will not affect other documents. - -@findex reftex-add-label-environments -@findex reftex-add-to-label-alist -A style hook may contain calls to -@code{reftex-add-label-environments}@footnote{This used to be the -function @code{reftex-add-to-label-alist} which is still available as an -alias for compatibility.} which defines additions to -@code{reftex-label-alist}. The argument taken by this function must have -the same format as @code{reftex-label-alist}. The @file{amsmath.el} -style file of AUCTeX for example contains the following: - -@lisp -@group -(TeX-add-style-hook "amsmath" - (lambda () - (if (fboundp 'reftex-add-label-environments) - (reftex-add-label-environments '(AMSTeX))))) -@end group -@end lisp - -@noindent -@findex LaTeX-add-environments, @r{AUCTeX} -while a package @code{myprop} defining a @code{proposition} environment -with @code{\newtheorem} might use - -@lisp -@group -(TeX-add-style-hook "myprop" - (lambda () - (LaTeX-add-environments '("proposition" LaTeX-env-label)) - (if (fboundp 'reftex-add-label-environments) - (reftex-add-label-environments - '(("proposition" ?p "prop:" "~\\ref@{%s@}" t - ("Proposition" "Prop.") -3)))))) -@end group -@end lisp - -@findex reftex-set-cite-format -Similarly, a style hook may contain a call to -@code{reftex-set-cite-format} to set the citation format. The style -file @file{natbib.el} for the Natbib citation style does switch -@b{Ref@TeX{}}'s citation format like this: - -@lisp -(TeX-add-style-hook "natbib" - (lambda () - (if (fboundp 'reftex-set-cite-format) - (reftex-set-cite-format 'natbib)))) -@end lisp - -@findex reftex-add-index-macros -The hook may contain a call to @code{reftex-add-index-macros} to -define additional @code{\index}-like macros. The argument must have -the same format as @code{reftex-index-macros}. It may be a symbol, to -trigger support for one of the builtin index packages. For example, -the style @file{multind.el} contains - -@lisp -(TeX-add-style-hook "multind" - (lambda () - (and (fboundp 'reftex-add-index-macros) - (reftex-add-index-macros '(multind))))) -@end lisp - -If you have your own package @file{myindex} which defines the -following macros to be used with the LaTeX @file{index.sty} file -@example -\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@} -\newcommand@{\aindex@}[1]@{#1\index[author]@{#1@} -@end example - -you could write this in the style file @file{myindex.el}: - -@lisp -(TeX-add-style-hook "myindex" - (lambda () - (TeX-add-symbols - '("molec" TeX-arg-index) - '("aindex" TeX-arg-index)) - (if (fboundp 'reftex-add-index-macros) - (reftex-add-index-macros - '(("molec@{*@}" "idx" ?m "Molecules!" nil nil) - ("aindex@{*@}" "author" ?a "" nil nil)))))) -@end lisp - -@findex reftex-add-section-levels -Finally the hook may contain a call to @code{reftex-add-section-levels} -to define additional section statements. For example, the FoilTeX class -has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here -is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these: - -@lisp -(TeX-add-style-hook "foils" - (lambda () - (if (fboundp 'reftex-add-section-levels) - (reftex-add-section-levels '(("foilhead" . 3) - ("rotatefoilhead" . 3)))))) -@end lisp - -@node Bib-Cite, , Style Files, AUCTeX -@subsection Bib-Cite -@cindex @code{bib-cite}, Emacs package -@cindex Emacs packages, @code{bib-cite} - -Once you have written a document with labels, references and citations, -it can be nice to read it like a hypertext document. @b{Ref@TeX{}} has -support for that: @code{reftex-view-crossref} (bound to @kbd{C-c -&}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and -@code{reftex-search-document}. A somewhat fancier interface with mouse -highlighting is provided (among other things) by Peter S. Galbraith's -@file{bib-cite.el}. There is some overlap in the functionalities of -Bib-cite and @b{Ref@TeX{}}. Bib-cite.el comes bundled with -AUCTeX. - -Bib-cite version 3.06 and later can be configured so that bib-cite's -mouse functions use @b{Ref@TeX{}} for displaying references and citations. -This can be useful in particular when working with the LaTeX @code{xr} -package or with an explicit @code{thebibliography} environment (rather -than BibTeX). Bib-cite cannot handle those, but @b{Ref@TeX{}} does. To -make use of this feature, try - -@vindex bib-cite-use-reftex-view-crossref -@lisp -(setq bib-cite-use-reftex-view-crossref t) -@end lisp - -@page -@node Problems and Work-Arounds, Imprint, Optimizations, Top -@section Problems and Work-arounds -@cindex Problems and work-arounds - -@itemize @bullet -@item -@b{LaTeX commands}@* -@cindex LaTeX commands, not found -@code{\input}, @code{\include}, and @code{\section} (etc.) statements -have to be first on a line (except for white space). - -@item -@b{Commented regions}@* -@cindex Labels, commented out -@b{Ref@TeX{}} sees also labels in regions commented out and will refuse to -make duplicates of such labels. This is considered to be a feature. - -@item -@b{Wrong section numbers}@* -@cindex Section numbers, wrong -@vindex reftex-enable-partial-scans -When using partial scans (@code{reftex-enable-partial-scans}), the section -numbers in the table of contents may eventually become wrong. A full -scan will fix this. - -@item -@b{Local settings}@* -@cindex Settings, local -@findex reftex-add-label-environments -@findex reftex-set-cite-format -@findex reftex-add-section-levels -The label environment definitions in @code{reftex-label-alist} are -global and apply to all documents. If you need to make definitions -local to a document, because they would interfere with settings in other -documents, you should use AUCTeX and set up style files with calls to -@code{reftex-add-label-environments}, @code{reftex-set-cite-format}, -@code{reftex-add-index-macros}, and @code{reftex-add-section-levels}. -Settings made with these functions remain local to the current -document. @xref{AUCTeX}. - -@item -@b{Funny display in selection buffer}@* -@cindex @code{x-symbol}, Emacs package -@cindex Emacs packages, @code{x-symbol} -@cindex @code{isotex}, Emacs package -@cindex Emacs packages, @code{isotex} -@cindex @code{iso-cvt}, Emacs package -@cindex Emacs packages, @code{iso-cvt} -When using packages which make the buffer representation of a file -different from its disk representation (e.g. x-symbol, isotex, -iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimes -reflects the disk state of a file. This happens only in @emph{unvisited} -parts of a multifile document, because @b{Ref@TeX{}} visits these files -literally for speed reasons. Then both short context and section -headings may look different from what you usually see on your screen. -In rare cases @code{reftex-toc} may have problems to jump to an affected -section heading. There are three possible ways to deal with -this: -@itemize @minus -@item -@vindex reftex-keep-temporary-buffers -@code{(setq reftex-keep-temporary-buffers t)}@* -This implies that @b{Ref@TeX{}} will load all parts of a multifile -document into Emacs (i.e. there won't be any temporary buffers). -@item -@vindex reftex-initialize-temporary-buffers -@code{(setq reftex-initialize-temporary-buffers t)}@* -This means full initialization of temporary buffers. It involves -a penalty when the same unvisited file is used for lookup often. -@item -Set @code{reftex-initialize-temporary-buffers} to a list of hook -functions doing a minimal initialization. -@end itemize -@vindex reftex-refontify-context -See also the variable @code{reftex-refontify-context}. - -@item -@b{Labels as arguments to \begin}@* -@cindex @code{pf}, LaTeX package -@cindex LaTeX packages, @code{pf} -Some packages use an additional argument to a @code{\begin} macro -to specify a label. E.g. Lamport's @file{pf.sty} uses both -@example -\step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@} - @var{claim} - \end@{step+@} -@end example - -@noindent -We need to trick @b{Ref@TeX{}} into swallowing this: - -@lisp -@group -;; Configuration for Lamport's pf.sty -(setq reftex-label-alist - '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St.")) - ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000))) -@end group -@end lisp - -@noindent -The first line is just a normal configuration for a macro. For the -@code{step+} environment we actually tell @b{Ref@TeX{}} to look for the -@emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first} -argument (which really is a second argument to the macro @code{\begin}) -as a label of type @code{?p}. Argument count for this macro starts only -after the @samp{@{step+@}}, also when specifying how to get -context. - -@item -@b{Idle timers in XEmacs}@* -@cindex Idle timer restart -@vindex reftex-use-itimer-in-xemacs -In XEmacs, idle timer restart does not work reliably after fast -keystrokes. Therefore @b{Ref@TeX{}} currently uses the post command -hook to start the timer used for automatic crossref information. When -this bug gets fixed, a real idle timer can be requested with -@lisp -(setq reftex-use-itimer-in-xemacs t) -@end lisp - -@item -@b{Viper mode}@* -@cindex Viper mode -@cindex Key bindings, problems with Viper mode -@findex viper-harness-minor-mode -With @i{Viper} mode prior to Vipers version 3.01, you need to protect -@b{Ref@TeX{}}'s keymaps with - -@lisp -(viper-harness-minor-mode "reftex") -@end lisp - -@end itemize - -@page -@node Imprint, Commands, Problems and Work-Arounds, Top -@section Imprint -@cindex Imprint -@cindex Maintainer -@cindex Acknowledgments -@cindex Thanks -@cindex Bug reports -@cindex @code{http}, @b{Ref@TeX{}} home page -@cindex @code{ftp}, @b{Ref@TeX{}} site - -Ref@TeX{} was written by @i{Carsten Dominik} -@email{dominik@@science.uva.nl}, with contributions by @i{Stephen -Eglen}. Ref@TeX{} is currently maintained by @value{MAINTAINER}, see -the @value{MAINTAINERSITE} for detailed information. - -If you have questions about Ref@TeX{}, you can send email to the -@value{SUPPORTADDRESS}. If you want to contribute code or ideas, write -to the @value{DEVELADDRESS}. And in the rare case of finding a bug, -please use @kbd{M-x reftex-report-bug @key{RET}} which will prepare a -bug report with useful information about your setup. Remember to add -essential information like a recipe for reproducing the bug, what you -expected to happen, and what actually happened. Send the bug report to -the @value{BUGADDRESS}. - -There are also several Usenet groups which have competent readers who -might be able to help: @code{comp.emacs}, @code{gnu.emacs.help}, -@code{comp.emacs.xemacs}, and @code{comp.text.tex}. - -@b{Ref@TeX{}} is bundled and pre-installed with Emacs since version 20.2. -It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs -21.x users want to install the corresponding plugin package which is -available from the @value{XEMACSFTP}. See the XEmacs 21.x -documentation on package installation for details. - -Users of earlier Emacs distributions (including Emacs 19) can get a -@b{Ref@TeX{}} distribution from the @value{MAINTAINERSITE}. Note that -the Emacs 19 version supports many but not all features described in -this manual. - -Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped -developing it with their reports. In particular thanks to @i{Ralf -Angeli, Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton, -Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai -Grossjohann, Frank Harrell, Till A. Heilmann, Peter Heslin, Stephan -Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz, -Juri Linkov, Rory Molinari, Stefan Monnier, Laurent Mugnier, Dan -Nicolaescu, Sudeep Kumar Palat, Daniel Polani, Alan Shutko, Robin Socha, -Richard Stanton, Allan Strand, Jan Vroonhof, Christoph Wedler, Alan -Williams, Roland Winkler, Hans-Christoph Wirth, Eli Zaretskii}. - - -The @code{view-crossref} feature was inspired by @i{Peter Galbraith's} -@file{bib-cite.el}. - -Finally thanks to @i{Uwe Bolick} who first got me interested in -supporting LaTeX labels and references with an editor (which was -MicroEmacs at the time). - -@node Commands, Options, Imprint, Top -@chapter Commands -@cindex Commands, list of - -Here is a summary of @b{Ref@TeX{}}'s commands which can be executed from -LaTeX files. Command which are executed from the special buffers are -not described here. All commands are available from the @code{Ref} -menu. See @xref{Key Bindings}. - -@deffn Command reftex-toc -Show the table of contents for the current document. When called with -one ore two @kbd{C-u} prefixes, rescan the document first. -@end deffn - -@deffn Command reftex-label -Insert a unique label. With one or two @kbd{C-u} prefixes, enforce -document rescan first. -@end deffn - -@deffn Command reftex-reference -Start a selection process to select a label, and insert a reference to -it. With one or two @kbd{C-u} prefixes, enforce document rescan first. -@end deffn - -@deffn Command reftex-citation -Make a citation using BibTeX database files. After prompting for a regular -expression, scans the buffers with BibTeX entries (taken from the -@code{\bibliography} command or a @code{thebibliography} environment) -and offers the matching entries for selection. The selected entry is -formatted according to @code{reftex-cite-format} and inserted into the -buffer. @* -When called with a @kbd{C-u} prefix, prompt for optional arguments in -cite macros. When called with a numeric prefix, make that many citations. -When called with point inside the braces of a @code{\cite} command, it -will add another key, ignoring the value of -@code{reftex-cite-format}. @* -The regular expression uses an expanded syntax: @samp{&&} is interpreted -as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain -both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion -on knows citation keys is possible. @samp{=} is a good regular -expression to match all entries in all files. -@end deffn - -@deffn Command reftex-index -Query for an index macro and insert it along with its arguments. The -index macros available are those defined in @code{reftex-index-macro} or -by a call to @code{reftex-add-index-macros}, typically from an AUCTeX -style file. @b{Ref@TeX{}} provides completion for the index tag and the -index key, and will prompt for other arguments. -@end deffn - -@deffn Command reftex-index-selection-or-word -Put current selection or the word near point into the default index -macro. This uses the information in @code{reftex-index-default-macro} -to make an index entry. The phrase indexed is the current selection or -the word near point. When called with one @kbd{C-u} prefix, let the -user have a chance to edit the index entry. When called with 2 -@kbd{C-u} as prefix, also ask for the index macro and other stuff. When -called inside TeX math mode as determined by the @file{texmathp.el} -library which is part of AUCTeX, the string is first processed with the -@code{reftex-index-math-format}, which see. -@end deffn - -@deffn Command reftex-index-phrase-selection-or-word -Add current selection or the word at point to the phrases buffer. -When you are in transient-mark-mode and the region is active, the -selection will be used - otherwise the word at point. -You get a chance to edit the entry in the phrases buffer - to save the -buffer and return to the LaTeX document, finish with @kbd{C-c C-c}. -@end deffn - -@deffn Command reftex-index-visit-phrases-buffer -Switch to the phrases buffer, initialize if empty. -@end deffn - -@deffn Command reftex-index-phrases-apply-to-region -Index all index phrases in the current region. -This works exactly like global indexing from the index phrases buffer, -but operation is restricted to the current region. -@end deffn - -@deffn Command reftex-display-index -Display a buffer with an index compiled from the current document. -When the document has multiple indices, first prompts for the correct one. -When index support is turned off, offer to turn it on. -With one or two @kbd{C-u} prefixes, rescan document first. -With prefix 2, restrict index to current document section. -With prefix 3, restrict index to active region. -@end deffn - -@deffn Command reftex-view-crossref -View cross reference of macro at point. Point must be on the @var{key} -argument. Works with the macros @code{\label}, @code{\ref}, -@code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of -these. Where it makes sense, subsequent calls show additional -locations. See also the variable @code{reftex-view-crossref-extra} and -the command @code{reftex-view-crossref-from-bibtex}. With one or two -@kbd{C-u} prefixes, enforce rescanning of the document. With argument -2, select the window showing the cross reference. -@end deffn - -@deffn Command reftex-view-crossref-from-bibtex -View location in a LaTeX document which cites the BibTeX entry at point. -Since BibTeX files can be used by many LaTeX documents, this function -prompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset this -link to a document, call the function with a prefix arg. Calling -this function several times find successive citation locations. -@end deffn - -@deffn Command reftex-create-tags-file -Create TAGS file by running @code{etags} on the current document. The -TAGS file is also immediately visited with -@code{visit-tags-table}. -@end deffn - -@deffn Command reftex-grep-document -Run grep query through all files related to this document. -With prefix arg, force to rescan document. -No active TAGS table is required. -@end deffn - -@deffn Command reftex-search-document -Regexp search through all files of the current document. -Starts always in the master file. Stops when a match is found. -No active TAGS table is required. -@end deffn - -@deffn Command reftex-query-replace-document -Run a query-replace-regexp of @var{from} with @var{to} over the entire -document. With prefix arg, replace only word-delimited matches. No -active TAGS table is required. -@end deffn - -@deffn Command reftex-isearch-minor-mode -Toggle a minor mode which enables incremental search to work globally -on the entire multifile document. Files will be searched in th -sequence they appear in the document. -@end deffn - -@deffn Command reftex-goto-label -Prompt for a label (with completion) and jump to the location of this -label. Optional prefix argument @var{other-window} goes to the label in -another window. -@end deffn - - -@deffn Command reftex-change-label -Query replace @var{from} with @var{to} in all @code{\label} and -@code{\ref} commands. Works on the entire multifile document. No -active TAGS table is required. -@end deffn - -@deffn Command reftex-renumber-simple-labels -Renumber all simple labels in the document to make them sequentially. -Simple labels are the ones created by RefTeX, consisting only of the -prefix and a number. After the command completes, all these labels will -have sequential numbers throughout the document. Any references to the -labels will be changed as well. For this, @b{Ref@TeX{}} looks at the -arguments of any macros which either start or end with the string -@samp{ref}. This command should be used with care, in particular in -multifile documents. You should not use it if another document refers -to this one with the @code{xr} package. -@end deffn - -@deffn Command reftex-find-duplicate-labels -Produce a list of all duplicate labels in the document. -@end deffn - -@deffn Command reftex-create-bibtex-file -Create a new BibTeX database file with all entries referenced in document. -The command prompts for a filename and writes the collected entries to -that file. Only entries referenced in the current document with -any @code{\cite}-like macros are used. -The sequence in the new file is the same as it was in the old database. -@end deffn - -@deffn Command reftex-customize -Run the customize browser on the @b{Ref@TeX{}} group. -@end deffn -@deffn Command reftex-show-commentary -Show the commentary section from @file{reftex.el}. -@end deffn -@deffn Command reftex-info -Run info on the top @b{Ref@TeX{}} node. -@end deffn -@deffn Command reftex-parse-document -Parse the entire document in order to update the parsing information. -@end deffn -@deffn Command reftex-reset-mode -Enforce rebuilding of several internal lists and variables. Also -removes the parse file associated with the current document. -@end deffn - -@node Options, Keymaps and Hooks, Commands, Top -@chapter Options, Keymaps, Hooks -@cindex Options, list of - -Here is a complete list of @b{Ref@TeX{}}'s configuration variables. All -variables have customize support - so if you are not familiar with Emacs -Lisp (and even if you are) you might find it more comfortable to use -@code{customize} to look at and change these variables. @kbd{M-x -reftex-customize} will get you there. - -@menu -* Options (Table of Contents):: -* Options (Defining Label Environments):: -* Options (Creating Labels):: -* Options (Referencing Labels):: -* Options (Creating Citations):: -* Options (Index Support):: -* Options (Viewing Cross-References):: -* Options (Finding Files):: -* Options (Optimizations):: -* Options (Fontification):: -* Options (Misc):: -@end menu - -@node Options (Table of Contents), Options (Defining Label Environments), , Options -@section Table of Contents -@cindex Options, table of contents -@cindex Table of contents, options - -@defopt reftex-include-file-commands -List of LaTeX commands which input another file. -The file name is expected after the command, either in braces or separated -by whitespace. -@end defopt - -@defopt reftex-max-section-depth -Maximum depth of section levels in document structure. -Standard LaTeX needs 7, default is 12. -@end defopt - -@defopt reftex-section-levels -Commands and levels used for defining sections in the document. The -@code{car} of each cons cell is the name of the section macro. The -@code{cdr} is a number indicating its level. A negative level means the -same as the positive value, but the section will never get a number. -The @code{cdr} may also be a function which then has to return the -level. This list is also used for promotion and demotion of sectioning -commands. If you are using a document class which has several sets of -sectioning commands, promotion only works correctly if this list is -sorted first by set, then within each set by level. The promotion -commands always select the nearest entry with the correct new level. - -@end defopt - -@defopt reftex-toc-max-level -The maximum level of toc entries which will be included in the TOC. -Section headings with a bigger level will be ignored. In RefTeX, -chapters are level 1, sections level 2 etc. This variable can be -changed from within the @file{*toc*} buffer with the @kbd{t} key. -@end defopt - -@defopt reftex-part-resets-chapter -Non-@code{nil} means, @code{\part} is like any other sectioning command. -This means, part numbers will be included in the numbering of chapters, and -chapter counters will be reset for each part. -When @code{nil} (the default), parts are special, do not reset the -chapter counter and also do not show up in chapter numbers. -@end defopt - -@defopt reftex-auto-recenter-toc -Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on. -When active, the @file{*TOC*} window will always show the section you -are currently working in. Recentering happens whenever Emacs is idle for -more than @code{reftex-idle-time} seconds. - -Value @code{t} means, turn on immediately when RefTeX gets started. Then, -recentering will work for any toc window created during the session. - -Value @code{frame} (the default) means, turn automatic recentering on -only while the dedicated TOC frame does exist, and do the recentering -only in that frame. So when creating that frame (with @kbd{d} key in an -ordinary TOC window), the automatic recentering is turned on. When the -frame gets destroyed, automatic recentering is turned off again. - -This feature can be turned on and off from the menu -(Ref->Options). -@end defopt - -@defopt reftex-toc-split-windows-horizontally -Non-@code{nil} means, create TOC window by splitting window -horizontally. The default is to split vertically. -@end defopt - -@defopt reftex-toc-split-windows-fraction -Fraction of the width or height of the frame to be used for TOC window. -@end defopt - -@defopt reftex-toc-keep-other-windows -Non-@code{nil} means, split the selected window to display the -@file{*toc*} buffer. This helps to keep the window configuration, but -makes the @file{*toc*} small. When @code{nil}, all other windows except -the selected one will be deleted, so that the @file{*toc*} window fills -half the frame. -@end defopt - -@defopt reftex-toc-include-file-boundaries -Non-@code{nil} means, include file boundaries in @file{*toc*} buffer. -This flag can be toggled from within the @file{*toc*} buffer with the -@kbd{i} key. -@end defopt - -@defopt reftex-toc-include-labels -Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag -can be toggled from within the @file{*toc*} buffer with the @kbd{l} -key. -@end defopt - -@defopt reftex-toc-include-index-entries -Non-@code{nil} means, include index entries in @file{*toc*} buffer. -This flag can be toggled from within the @file{*toc*} buffer with the -@kbd{i} key. -@end defopt - -@defopt reftex-toc-include-context -Non-@code{nil} means, include context with labels in the @file{*toc*} -buffer. Context will only be shown if the labels are visible as well. -This flag can be toggled from within the @file{*toc*} buffer with the -@kbd{c} key. -@end defopt - -@defopt reftex-toc-follow-mode -Non-@code{nil} means, point in @file{*toc*} buffer (the -table-of-contents buffer) will cause other window to follow. The other -window will show the corresponding part of the document. This flag can -be toggled from within the @file{*toc*} buffer with the @kbd{f} -key. -@end defopt - -@deffn {Normal Hook} reftex-toc-mode-hook -Normal hook which is run when a @file{*toc*} buffer is -created. -@end deffn - -@deffn Keymap reftex-toc-map -The keymap which is active in the @file{*toc*} buffer. -(@pxref{Table of Contents}). -@end deffn - -@node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options -@section Defining Label Environments -@cindex Options, defining label environments -@cindex Defining label environments, options - -@defopt reftex-default-label-alist-entries -Default label alist specifications. It is a list of symbols with -associations in the constant @code{reftex-label-alist-builtin}. -@code{LaTeX} should always be the last entry. -@end defopt - -@defopt reftex-label-alist -Set this variable to define additions and changes to the defaults in -@code{reftex-default-label-alist-entries}. The only things you -@emph{must not} change is that @code{?s} is the type indicator for -section labels, and @key{SPC} for the @code{any} label type. These are -hard-coded at other places in the code. - -The value of the variable must be a list of items. Each item is a list -itself and has the following structure: - -@example - (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format} - @var{context-method} (@var{magic-word} ... ) @var{toc-level}) -@end example - -Each list entry describes either an environment carrying a counter for -use with @code{\label} and @code{\ref}, or a LaTeX macro defining a -label as (or inside) one of its arguments. The elements of each list -entry are: - -@table @asis -@item @var{env-or-macro} -Name of the environment (like @samp{table}) or macro (like -@samp{\myfig}). For macros, indicate the arguments, as in -@samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional -arguments, a star to mark the label argument, if any. The macro does -not have to have a label argument - you could also use -@samp{\label@{...@}} inside one of its arguments. - -Special names: @code{section} for section labels, @code{any} to define a -group which contains all labels. - -This may also be a function to do local parsing and identify point to be -in a non-standard label environment. The function must take an -argument @var{bound} and limit backward searches to this value. It -should return either nil or a cons cell @code{(@var{function} -. @var{position})} with the function symbol and the position where the -special environment starts. See the Info documentation for an -example. - -Finally this may also be @code{nil} if the entry is only meant to change -some settings associated with the type indicator character (see -below). - -@item @var{type-key} -Type indicator character, like @code{?t}, must be a printable ASCII -character. The type indicator is a single character which defines a -label type. Any label inside the environment or macro is assumed to -belong to this type. The same character may occur several times in this -list, to cover cases in which different environments carry the same -label type (like @code{equation} and @code{eqnarray}). If the type -indicator is @code{nil} and the macro has a label argument @samp{@{*@}}, -the macro defines neutral labels just like @code{\label}. In this case -the reminder of this entry is ignored. - -@item @var{label-prefix} -Label prefix string, like @samp{tab:}. The prefix is a short string -used as the start of a label. It may be the empty string. The prefix -may contain the following @samp{%} escapes: - -@example -%f Current file name, directory and extension stripped. -%F Current file name relative to master file directory. -%m Master file name, directory and extension stripped. -%M Directory name (without path) where master file is located. -%u User login name, on systems which support this. -%S A section prefix derived with variable @code{reftex-section-prefixes}. -@end example - -@noindent -Example: In a file @file{intro.tex}, @samp{eq:%f:} will become -@samp{eq:intro:}. - -@item @var{reference-format} -Format string for reference insert in buffer. @samp{%s} will be -replaced by the label. When the format starts with @samp{~}, this -@samp{~} will only be inserted when the character before point is -@emph{not} a whitespace. - -@item @var{context-method} -Indication on how to find the short context. -@itemize @minus -@item -If @code{nil}, use the text following the @samp{\label@{...@}} macro. -@item -If @code{t}, use -@itemize @minus -@item -the section heading for section labels. -@item -text following the @samp{\begin@{...@}} statement of environments (not -a good choice for environments like eqnarray or enumerate, where one has -several labels in a single environment). -@item -text after the macro name (starting with the first arg) for -macros. -@end itemize -@item -If an integer, use the nth argument of the macro. As a special case, -1000 means to get text after the last macro argument. -@item -If a string, use as regexp to search @emph{backward} from the label. -Context is then the text following the end of the match. E.g. putting -this to @samp{\\caption[[@{]} will use the caption in a figure or table -environment. @samp{\\begin@{eqnarray@}\|\\\\} works for -eqnarrays. -@item -If any of @code{caption}, @code{item}, @code{eqnarray-like}, -@code{alignat-like}, this symbol will internally be translated into an -appropriate regexp (see also the variable -@code{reftex-default-context-regexps}). -@item -If a function, call this function with the name of the environment/macro -as argument. On call, point will be just after the @code{\label} macro. -The function is expected to return a suitable context string. It should -throw an exception (error) when failing to find context. As an example, -here is a function returning the 10 chars following the label macro as -context: - -@example -(defun my-context-function (env-or-mac) - (if (> (point-max) (+ 10 (point))) - (buffer-substring (point) (+ 10 (point))) - (error "Buffer too small"))) -@end example -@end itemize - -Label context is used in two ways by @b{Ref@TeX{}}: For display in the label -menu, and to derive a label string. If you want to use a different -method for each of these, specify them as a dotted pair. -E.g. @code{(nil . t)} uses the text after the label (@code{nil}) for -display, and text from the default position (@code{t}) to derive a label -string. This is actually used for section labels. - -@item @var{magic-word-list} -List of magic words which identify a reference to be of this type. If -the word before point is equal to one of these words when calling -@code{reftex-reference}, the label list offered will be automatically -restricted to labels of the correct type. If the first element of this -word--list is the symbol `regexp', the strings are interpreted as regular -expressions. - -@item @var{toc-level} -The integer level at which this environment should be added to the table -of contents. See also @code{reftex-section-levels}. A positive value -will number the entries mixed with the sectioning commands of the same -level. A negative value will make unnumbered entries. Useful only for -theorem-like environments which structure the document. Will be ignored -for macros. When omitted or @code{nil}, no TOC entries will be -made. -@end table - -If the type indicator characters of two or more entries are the same, -@b{Ref@TeX{}} will use -@itemize @minus -@item -the first non-@code{nil} format and prefix -@item -the magic words of all involved entries. -@end itemize - -Any list entry may also be a symbol. If that has an association in -@code{reftex-label-alist-builtin}, the @code{cddr} of that association is -spliced into the list. However, builtin defaults should normally be set -with the variable @code{reftex-default-label-alist-entries}. -@end defopt - -@defopt reftex-section-prefixes -Prefixes for section labels. When the label prefix given in an entry in -@code{reftex-label-alist} contains @samp{%S}, this list is used to -determine the correct prefix string depending on the current section -level. The list is an alist, with each entry of the form -@w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro -names like @samp{chapter}, integer section levels (as given in -@code{reftex-section-levels}), and @code{t} for the default. -@end defopt - -@defopt reftex-default-context-regexps -Alist with default regular expressions for finding context. The emacs -lisp form @w{@code{(format regexp (regexp-quote environment))}} is used -to calculate the final regular expression - so @samp{%s} will be -replaced with the environment or macro. -@end defopt - -@defopt reftex-trust-label-prefix -Non-@code{nil} means, trust the label prefix when determining label type. -It is customary to use special label prefixes to distinguish different label -types. The label prefixes have no syntactic meaning in LaTeX (unless -special packages like fancyref) are being used. RefTeX can and by -default does parse around each label to detect the correct label type, -but this process can be slow when a document contains thousands of -labels. If you use label prefixes consistently, you may speed up -document parsing by setting this variable to a non-nil value. RefTeX -will then compare the label prefix with the prefixes found in -`reftex-label-alist' and derive the correct label type in this way. -Possible values for this option are: - -@example -t @r{This means to trust any label prefixes found.} -regexp @r{If a regexp, only prefixes matched by the regexp are trusted.} -list @r{List of accepted prefixes, as strings. The colon is part of} - @r{the prefix, e.g. ("fn:" "eqn:" "item:").} -nil @r{Never trust a label prefix.} -@end example -The only disadvantage of using this feature is that the label context -displayed in the label selection buffer along with each label is -simply some text after the label definition. This is no problem if you -place labels keeping this in mind (e.g. @i{before} the equation, @i{at -the beginning} of a fig/tab caption ...). Anyway, it is probably best -to use the regexp or the list value types to fine-tune this feature. -For example, if your document contains thousands of footnotes with -labels fn:xxx, you may want to set this variable to the value "^fn:$" or -("fn:"). Then RefTeX will still do extensive parsing for any -non-footnote labels. -@end defopt - -@node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options -@section Creating Labels -@cindex Options, creating labels -@cindex Creating labels, options - -@defopt reftex-insert-label-flags -Flags governing label insertion. The value has the form - -@example -(@var{derive} @var{prompt}) -@end example - -If @var{derive} is @code{t}, @b{Ref@TeX{}} will try to derive a sensible -label from context. A section label for example will be derived from -the section heading. The conversion of the context to a valid label is -governed by the specifications given in -@code{reftex-derive-label-parameters}. If @var{derive} is @code{nil}, -the default label will consist of the prefix and a unique number, like -@samp{eq:23}. - -If @var{prompt} is @code{t}, the user will be prompted for a label -string. When @var{prompt} is @code{nil}, the default label will be -inserted without query. - -So the combination of @var{derive} and @var{prompt} controls label -insertion. Here is a table describing all four possibilities: - -@example -@group -@var{derive} @var{prompt} @var{action} ------------------------------------------------------------ -nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.} -nil t @r{Prompt for label.} -t nil @r{Derive a label from context and insert. No query.} -t t @r{Derive a label from context, prompt for confirmation.} -@end group -@end example - -Each flag may be set to @code{t}, @code{nil}, or a string of label type -letters indicating the label types for which it should be true. Thus, -the combination may be set differently for each label type. The default -settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from -headings (with confirmation). Prompt for figure and table labels. Use -simple labels without confirmation for everything else. - -The available label types are: @code{s} (section), @code{f} (figure), -@code{t} (table), @code{i} (item), @code{e} (equation), @code{n} -(footnote), @code{N} (endnote) plus any definitions in -@code{reftex-label-alist}. -@end defopt - -@deffn Hook reftex-format-label-function -If non-@code{nil}, should be a function which produces the string to -insert as a label definition. The function will be called with two -arguments, the @var{label} and the @var{default-format} (usually -@samp{\label@{%s@}}). It should return the string to insert into the -buffer. -@end deffn - -@deffn Hook reftex-string-to-label-function -Function to turn an arbitrary string into a valid label. -@b{Ref@TeX{}}'s default function uses the variable -@code{reftex-derive-label-parameters}. -@end deffn - -@deffn Hook reftex-translate-to-ascii-function -Filter function which will process a context string before it is used to -derive a label from it. The intended application is to convert ISO or -Mule characters into something valid in labels. The default function -@code{reftex-latin1-to-ascii} removes the accents from Latin-1 -characters. X-Symbol (>=2.6) sets this variable to the much more -general @code{x-symbol-translate-to-ascii}. -@end deffn - -@defopt reftex-derive-label-parameters -Parameters for converting a string into a label. This variable is a -list of the following items: -@table @asis -@item @var{nwords} -Number of words to use. -@item @var{maxchar} -Maximum number of characters in a label string. -@item @var{invalid} -@code{nil}: Throw away any words containing characters invalid in labels.@* -@code{t}: Throw away only the invalid characters, not the whole word. -@item @var{abbrev} -@code{nil}: Never abbreviate words.@* -@code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@* -@code{1}: Abbreviate words if necessary to shorten label string. -@item @var{separator} -String separating different words in the label. -@item @var{ignorewords} -List of words which should not be part of labels. -@item @var{downcase} -@code{t}: Downcase words before putting them into the label.@* -@end table -@end defopt - -@defopt reftex-label-illegal-re -Regexp matching characters not valid in labels. -@end defopt - -@defopt reftex-abbrev-parameters -Parameters for abbreviation of words. A list of four parameters. -@table @asis -@item @var{min-chars} -Minimum number of characters remaining after abbreviation. -@item @var{min-kill} -Minimum number of characters to remove when abbreviating words. -@item @var{before} -Character class before abbrev point in word. -@item @var{after} -Character class after abbrev point in word. -@end table -@end defopt - -@node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options -@section Referencing Labels -@cindex Options, referencing labels -@cindex Referencing labels, options - -@defopt reftex-label-menu-flags -List of flags governing the label menu makeup. The flags are: -@table @asis -@item @var{table-of-contents} -Show the labels embedded in a table of context. -@item @var{section-numbers} -Include section numbers (like 4.1.3) in table of contents. -@item @var{counters} -Show counters. This just numbers the labels in the menu. -@item @var{no-context} -Non-@code{nil} means do @emph{not} show the short context. -@item @var{follow} -Follow full context in other window. -@item @var{show-commented} -Show labels from regions which are commented out. -@item @var{match-everywhere} -Obsolete flag. -@item @var{show-files} -Show begin and end of included files. -@end table - -Each of these flags can be set to @code{t} or @code{nil}, or to a string -of type letters indicating the label types for which it should be true. -These strings work like character classes in regular expressions. Thus, -setting one of the flags to @samp{"sf"} makes the flag true for section -and figure labels, @code{nil} for everything else. Setting it to -@samp{"^sf"} makes it the other way round. - -The available label types are: @code{s} (section), @code{f} (figure), -@code{t} (table), @code{i} (item), @code{e} (equation), @code{n} -(footnote), plus any definitions in @code{reftex-label-alist}. - -Most options can also be switched from the label menu itself - so if you -decide here to not have a table of contents in the label menu, you can -still get one interactively during selection from the label menu. -@end defopt - -@defopt reftex-multiref-punctuation -Punctuation strings for multiple references. When marking is used in -the selection buffer to select several references, this variable -associates the 3 marking characters @samp{,-+} with prefix strings to be -inserted into the buffer before the corresponding @code{\ref} macro. -This is used to string together whole reference sets, like -@samp{eqs. 1,2,3-5,6 and 7} in a single call to -@code{reftex-reference}. -@end defopt - -@defopt reftex-vref-is-default -Non-@code{nil} means, the varioref macro @code{\vref} is used as -default. In the selection buffer, the @kbd{v} key toggles the reference -macro between @code{\ref} and @code{\vref}. The value of this variable -determines the default which is active when entering the selection -process. Instead of @code{nil} or @code{t}, this may also be a string -of type letters indicating the label types for which it should be -true. -@end defopt - -@defopt reftex-fref-is-default -Non-@code{nil} means, the fancyref macro @code{\fref} is used as -default. In the selection buffer, the @kbd{V} key toggles the reference -macro between @code{\ref}, @code{\fref} and @code{\Fref}. The value of -this variable determines the default which is active when entering the -selection process. Instead of @code{nil} or @code{t}, this may also be -a string of type letters indicating the label types for which it should -be true. -@end defopt - -@deffn Hook reftex-format-ref-function -If non-@code{nil}, should be a function which produces the string to -insert as a reference. Note that the insertion format can also be -changed with @code{reftex-label-alist}. This hook also is used by the -special commands to insert @code{\vref} and @code{\fref} references, so -even if you set this, your setting will be ignored by the special -commands. The function will be called with two arguments, the -@var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}). -It should return the string to insert into the buffer. -@end deffn - -@defopt reftex-level-indent -Number of spaces to be used for indentation per section level. -@end defopt - -@defopt reftex-guess-label-type -Non-@code{nil} means, @code{reftex-reference} will try to guess the -label type. To do that, @b{Ref@TeX{}} will look at the word before the -cursor and compare it with the magic words given in -@code{reftex-label-alist}. When it finds a match, @b{Ref@TeX{}} will -immediately offer the correct label menu - otherwise it will prompt you -for a label type. If you set this variable to @code{nil}, @b{Ref@TeX{}} -will always prompt for a label type. -@end defopt - -@deffn {Normal Hook} reftex-display-copied-context-hook -Normal Hook which is run before context is displayed anywhere. Designed -for @w{@code{X-Symbol}}, but may have other uses as well. -@end deffn - -@deffn Hook reftex-pre-refontification-functions -@code{X-Symbol} specific hook. Probably not useful for other purposes. -The functions get two arguments, the buffer from where the command -started and a symbol indicating in what context the hook is -called. -@end deffn - -@deffn {Normal Hook} reftex-select-label-mode-hook -Normal hook which is run when a selection buffer enters -@code{reftex-select-label-mode}. -@end deffn - -@deffn Keymap reftex-select-label-map -The keymap which is active in the labels selection process -(@pxref{Referencing Labels}). -@end deffn - -@node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options -@section Creating Citations -@cindex Options, creating citations -@cindex Creating citations, options - -@defopt reftex-bibliography-commands -LaTeX commands which specify the BibTeX databases to use with the document. -@end defopt - -@defopt reftex-bibfile-ignore-regexps -List of regular expressions to exclude files in -@code{\\bibliography@{..@}}. File names matched by any of these regexps -will not be parsed. Intended for files which contain only -@code{@@string} macro definitions and the like, which are ignored by -@b{Ref@TeX{}} anyway. -@end defopt - -@defopt reftex-default-bibliography -List of BibTeX database files which should be used if none are specified. -When @code{reftex-citation} is called from a document with neither -a @samp{\bibliography@{...@}} statement nor a @code{thebibliography} -environment, @b{Ref@TeX{}} will scan these files instead. Intended for -using @code{reftex-citation} in non-LaTeX files. The files will be -searched along the BIBINPUTS or TEXBIB path. -@end defopt - -@defopt reftex-sort-bibtex-matches -Sorting of the entries found in BibTeX databases by reftex-citation. -Possible values: -@example -nil @r{Do not sort entries.} -author @r{Sort entries by author name.} -year @r{Sort entries by increasing year.} -reverse-year @r{Sort entries by decreasing year.} -@end example -@end defopt - -@defopt reftex-cite-format -The format of citations to be inserted into the buffer. It can be a -string, an alist or a symbol. In the simplest case this is just the string -@samp{\cite@{%l@}}, which is also the default. See the definition of -@code{reftex-cite-format-builtin} for more complex examples. - -If @code{reftex-cite-format} is a string, it will be used as the format. -In the format, the following percent escapes will be expanded. - -@table @code -@item %l -The BibTeX label of the citation. -@item %a -List of author names, see also @code{reftex-cite-punctuation}. -@item %2a -Like %a, but abbreviate more than 2 authors like Jones et al. -@item %A -First author name only. -@item %e -Works like @samp{%a}, but on list of editor names. (@samp{%2e} and -@samp{%E} work a well). -@end table - -It is also possible to access all other BibTeX database fields: - -@example -%b booktitle %c chapter %d edition %h howpublished -%i institution %j journal %k key %m month -%n number %o organization %p pages %P first page -%r address %s school %u publisher %t title -%v volume %y year -%B booktitle, abbreviated %T title, abbreviated -@end example - -@noindent -Usually, only @samp{%l} is needed. The other stuff is mainly for the -echo area display, and for @code{(setq reftex-comment-citations t)}. - -@samp{%<} as a special operator kills punctuation and space around it -after the string has been formatted. - -A pair of square brackets indicates an optional argument, and RefTeX -will prompt for the values of these arguments. - -Beware that all this only works with BibTeX database files. When -citations are made from the @code{\bibitems} in an explicit -@code{thebibliography} environment, only @samp{%l} is available. - -If @code{reftex-cite-format} is an alist of characters and strings, the -user will be prompted for a character to select one of the possible -format strings. - -In order to configure this variable, you can either set -@code{reftex-cite-format} directly yourself or set it to the -@emph{symbol} of one of the predefined styles. The predefined symbols -are those which have an association in the constant -@code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format -'natbib)}. -@end defopt - -@deffn Hook reftex-format-cite-function -If non-@code{nil}, should be a function which produces the string to -insert as a citation. Note that the citation format can also be changed -with the variable @code{reftex-cite-format}. The function will be -called with two arguments, the @var{citation-key} and the -@var{default-format} (taken from @code{reftex-cite-format}). It should -return the string to insert into the buffer. -@end deffn - -@defopt reftex-cite-prompt-optional-args -Non-@code{nil} means, prompt for empty optional arguments in cite macros. -When an entry in @code{reftex-cite-format} ist given with square brackets to -indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can -prompt for values. Possible values are: -@example -nil @r{Never prompt for optional arguments} -t @r{Always prompt} -maybe @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg}@end example -Unnecessary empty optional arguments are removed before insertion into -the buffer. See @code{reftex-cite-cleanup-optional-args}. -@end defopt - -@defopt reftex-cite-cleanup-optional-args -Non-@code{nil} means, remove empty optional arguments from cite macros -if possible. -@end defopt - -@defopt reftex-comment-citations -Non-@code{nil} means add a comment for each citation describing the full -entry. The comment is formatted according to -@code{reftex-cite-comment-format}. -@end defopt - -@defopt reftex-cite-comment-format -Citation format used for commented citations. Must @emph{not} contain -@samp{%l}. See the variable @code{reftex-cite-format} for possible -percent escapes. -@end defopt - -@defopt reftex-cite-punctuation -Punctuation for formatting of name lists in citations. This is a list -of 3 strings. -@enumerate -@item -normal names separator, like @samp{, } in Jones, Brown and Miller -@item -final names separator, like @samp{ and } in Jones, Brown and Miller -@item -The @samp{et al.} string, like @samp{ @{\it et al.@}} in -Jones @{\it et al.@} -@end enumerate -@end defopt - -@deffn {Normal Hook} reftex-select-bib-mode-hook -Normal hook which is run when a selection buffer enters -@code{reftex-select-bib-mode}. -@end deffn - -@deffn Keymap reftex-select-bib-map -The keymap which is active in the citation-key selection process -(@pxref{Creating Citations}). -@end deffn - -@node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations), Options -@section Index Support -@cindex Options, Index support -@cindex Index support, options - -@defopt reftex-support-index -Non-@code{nil} means, index entries are parsed as well. Index support -is resource intensive and the internal structure holding the parsed -information can become quite big. Therefore it can be turned off. When -this is @code{nil} and you execute a command which requires index -support, you will be asked for confirmation to turn it on and rescan the -document. -@end defopt - -@defopt reftex-index-special-chars -List of special characters in index entries, given as strings. These -correspond to the @code{MakeIndex} keywords -@code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}. -@end defopt - -@defopt reftex-index-macros -List of macros which define index entries. The structure of each entry -is -@lisp -(@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat}) -@end lisp - -@var{macro} is the macro. Arguments should be denoted by empty braces, -as for example in @samp{\index[]@{*@}}. Use square brackets to denote -optional arguments. The star marks where the index key is. - -@var{index-tag} is a short name of the index. @samp{idx} and @samp{glo} -are reserved for the default index and the glossary. Other indices can -be defined as well. If this is an integer, the Nth argument of the -macro holds the index tag. - -@var{key} is a character which is used to identify the macro for input -with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are -reserved for default index and glossary. - -@var{prefix} can be a prefix which is added to the @var{key} part of the -index entry. If you have a macro -@code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix -should be @samp{Molecules!}. - -@var{exclude} can be a function. If this function exists and returns a -non-@code{nil} value, the index entry at point is ignored. This was -implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts -in the LaTeX2e @code{index} package. - -@var{repeat}, if non-@code{nil}, means the index macro does not typeset -the entry in the text, so that the text has to be repeated outside the -index macro. Needed for @code{reftex-index-selection-or-word} and for -indexing from the phrase buffer. - -The final entry may also be a symbol. It must have an association in -the variable @code{reftex-index-macros-builtin} to specify the main -indexing package you are using. Valid values are currently -@example -default @r{The LaTeX default - unnecessary to specify this one} -multind @r{The multind.sty package} -index @r{The index.sty package} -index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.} - @r{Should not be used - only for old documents} -@end example -Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well, -so with a sufficiently new version of AUCTeX, you should not set the -package here. -@end defopt - -@defopt reftex-index-default-macro -The default index macro for @code{reftex-index-selection-or-word}. -This is a list with @code{(@var{macro-key} @var{default-tag})}. - -@var{macro-key} is a character identifying an index macro - see -@code{reftex-index-macros}. - -@var{default-tag} is the tag to be used if the macro requires a -@var{tag} argument. When this is @code{nil} and a @var{tag} is needed, -@b{Ref@TeX{}} will ask for it. When this is the empty string and the -TAG argument of the index macro is optional, the TAG argument will be -omitted. -@end defopt - -@defopt reftex-index-default-tag -Default index tag. When working with multiple indexes, RefTeX queries -for an index tag when creating index entries or displaying a specific -index. This variable controls the default offered for these queries. -The default can be selected with @key{RET} during selection or -completion. Valid values of this variable are: -@example -nil @r{Do not provide a default index} -"tag" @r{The default index tag given as a string, e.g. "idx"} -last @r{The last used index tag will be offered as default} -@end example -@end defopt - -@defopt reftex-index-math-format -Format of index entries when copied from inside math mode. When -@code{reftex-index-selection-or-word} is executed inside TeX math mode, -the index key copied from the buffer is processed with this format -string through the @code{format} function. This can be used to add the -math delimiters (e.g. @samp{$}) to the string. Requires the -@file{texmathp.el} library which is part of AUCTeX. -@end defopt - -@defopt reftex-index-phrase-file-extension -File extension for the index phrase file. This extension will be added -to the base name of the master file. -@end defopt - -@defopt reftex-index-phrases-logical-and-regexp -Regexp matching the @samp{and} operator for index arguments in phrases -file. When several index arguments in a phrase line are separated by -this operator, each part will generate an index macro. So each match of -the search phrase will produce @emph{several} different index entries. -Make sure this does no match things which are not separators. This -logical @samp{and} has higher priority than the logical @samp{or} -specified in @code{reftex-index-phrases-logical-or-regexp}. -@end defopt - -@defopt reftex-index-phrases-logical-or-regexp -Regexp matching the @samp{or} operator for index arguments in phrases -file. When several index arguments in a phrase line are separated by -this operator, the user will be asked to select one of them at each -match of the search phrase. The first index arg will be the default. A -number key @kbd{1}--@kbd{9} must be pressed to switch to another. Make -sure this does no match things which are not separators. The logical -@samp{and} specified in @code{reftex-index-phrases-logical-or-regexp} -has higher priority than this logical @samp{or}. -@end defopt - -@defopt reftex-index-phrases-search-whole-words -Non-@code{nil} means phrases search will look for whole words, not subwords. -This works by requiring word boundaries at the beginning and end of -the search string. When the search phrase already has a non-word-char -at one of these points, no word boundary is required there. -@end defopt - -@defopt reftex-index-phrases-case-fold-search -Non-@code{nil} means, searching for index phrases will ignore -case. -@end defopt - -@defopt reftex-index-verify-function -A function which is called at each match during global indexing. -If the function returns nil, the current match is skipped. -@end defopt - -@defopt reftex-index-phrases-skip-indexed-matches -Non-@code{nil} means, skip matches which appear to be indexed already. -When doing global indexing from the phrases buffer, searches for some -phrases may match at places where that phrase was already indexed. In -particular when indexing an already processed document again, this -will even be the norm. When this variable is non-@code{nil}, -@b{Ref@TeX{}} checks if the match is an index macro argument, or if an -index macro is directly before or after the phrase. If that is the -case, that match will be ignored. -@end defopt - -@defopt reftex-index-phrases-wrap-long-lines -Non-@code{nil} means, when indexing from the phrases buffer, wrap lines. -Inserting indexing commands in a line makes the line longer - often -so long that it does not fit onto the screen. When this variable is -non-@code{nil}, newlines will be added as necessary before and/or after the -indexing command to keep lines short. However, the matched text -phrase and its index command will always end up on a single line. -@end defopt - -@defopt reftex-index-phrases-sort-prefers-entry -Non-@code{nil} means when sorting phrase lines, the explicit index entry -is used. Phrase lines in the phrases buffer contain a search phrase, and -sorting is normally based on these. Some phrase lines also have -an explicit index argument specified. When this variable is -non-@code{nil}, the index argument will be used for sorting. -@end defopt - -@defopt reftex-index-phrases-sort-in-blocks -Non-@code{nil} means, empty and comment lines separate phrase buffer -into blocks. Sorting will then preserve blocks, so that lines are -re-arranged only within blocks. -@end defopt - -@defopt reftex-index-phrases-map -Keymap for the Index Phrases buffer. -@end defopt - -@defopt reftex-index-phrases-mode-hook -Normal hook which is run when a buffer is put into -@code{reftex-index-phrases-mode}. -@end defopt - -@defopt reftex-index-section-letters -The letters which denote sections in the index. Usually these are all -capital letters. Don't use any downcase letters. Order is not -significant, the index will be sorted by whatever the sort function -thinks is correct. In addition to these letters, @b{Ref@TeX{}} will -create a group @samp{!} which contains all entries sorted below the -lowest specified letter. In the @file{*Index*} buffer, pressing any of -these capital letters or @kbd{!} will jump to that section. -@end defopt - -@defopt reftex-index-include-context -Non-@code{nil} means, display the index definition context in the -@file{*Index*} buffer. This flag may also be toggled from the -@file{*Index*} buffer with the @kbd{c} key. -@end defopt - -@defopt reftex-index-follow-mode -Non-@code{nil} means, point in @file{*Index*} buffer will cause other -window to follow. The other window will show the corresponding part of -the document. This flag can be toggled from within the @file{*Index*} -buffer with the @kbd{f} key. -@end defopt - -@deffn Keymap reftex-index-map -The keymap which is active in the @file{*Index*} buffer -(@pxref{Index Support}). -@end deffn - -@node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support), Options -@section Viewing Cross-References -@cindex Options, viewing cross-references -@cindex Viewing cross-references, options - -@defopt reftex-view-crossref-extra -Macros which can be used for the display of cross references. -This is used when `reftex-view-crossref' is called with point in an -argument of a macro. Note that crossref viewing for citations, -references (both ways) and index entries is hard-coded. This variable -is only to configure additional structures for which crossreference -viewing can be useful. Each entry has the structure -@example -(@var{macro-re} @var{search-re} @var{highlight}). -@end example -@var{macro-re} is matched against the macro. @var{search-re} is the -regexp used to search for cross references. @samp{%s} in this regexp is -replaced with the macro argument at point. @var{highlight} is an -integer indicating which subgroup of the match should be highlighted. -@end defopt - -@defopt reftex-auto-view-crossref -Non-@code{nil} means, initially turn automatic viewing of crossref info -on. Automatic viewing of crossref info normally uses the echo area. -Whenever point is idle for more than @code{reftex-idle-time} seconds on -the argument of a @code{\ref} or @code{\cite} macro, and no other -message is being displayed, the echo area will display information about -that cross reference. You can also set the variable to the symbol -@code{window}. In this case a small temporary window is used for the -display. This feature can be turned on and off from the menu -(Ref->Options). -@end defopt - -@defopt reftex-idle-time -Time (secs) Emacs has to be idle before automatic crossref display -or toc recentering is done. -@end defopt - -@defopt reftex-cite-view-format -Citation format used to display citation info in the message area. See -the variable @code{reftex-cite-format} for possible percent -escapes. -@end defopt - -@defopt reftex-revisit-to-echo -Non-@code{nil} means, automatic citation display will revisit files if -necessary. When nil, citation display in echo area will only be active -for cached echo strings (see @code{reftex-cache-cite-echo}), or for -BibTeX database files which are already visited by a live associated -buffers. -@end defopt - -@defopt reftex-cache-cite-echo -Non-@code{nil} means, the information displayed in the echo area for -cite macros (see variable @code{reftex-auto-view-crossref}) is cached and -saved along with the parsing information. The cache survives document -scans. In order to clear it, use @kbd{M-x reftex-reset-mode}. -@end defopt - -@node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References), Options -@section Finding Files -@cindex Options, Finding Files -@cindex Finding files, options - -@defopt reftex-texpath-environment-variables -List of specifications how to retrieve the search path for TeX files. -Several entries are possible. -@itemize @minus -@item -If an element is the name of an environment variable, its content is -used. -@item -If an element starts with an exclamation mark, it is used as a command -to retrieve the path. A typical command with the kpathsearch library -would be @w{@code{"!kpsewhich -show-path=.tex"}}. -@item -Otherwise the element itself is interpreted as a path. -@end itemize -Multiple directories can be separated by the system dependent -@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will -be expanded recursively. See also @code{reftex-use-external-file-finders}. -@end defopt - -@defopt reftex-bibpath-environment-variables -List of specifications how to retrieve the search path for BibTeX -files. Several entries are possible. -@itemize @minus -@item -If an element is the name of an environment variable, its content is -used. -@item -If an element starts with an exclamation mark, it is used as a command -to retrieve the path. A typical command with the kpathsearch library -would be @w{@code{"!kpsewhich -show-path=.bib"}}. -@item -Otherwise the element itself is interpreted as a path. -@end itemize -Multiple directories can be separated by the system dependent -@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will -be expanded recursively. See also @code{reftex-use-external-file-finders}. -@end defopt - -@defopt reftex-file-extensions -Association list with file extensions for different file types. -This is a list of items, each item is like: -@code{(@var{type} . (@var{def-ext} @var{other-ext} ...))} -@example -@var{type}: @r{File type like @code{"bib"} or @code{"tex"}.} -@var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.} -@var{other-ext}: @r{Any number of other valid extensions for this file type.} -@end example -When a files is searched and it does not have any of the valid extensions, -we try the default extension first, and then the naked file name. -@end defopt - -@defopt reftex-search-unrecursed-path-first -Non-@code{nil} means, search all specified directories before trying -recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./}, -then @samp{/tex/}, and then all subdirectories of @samp{./}. If this -option is @code{nil}, the subdirectories of @samp{./} are searched -before @samp{/tex/}. This is mainly for speed - most of the time the -recursive path is for the system files and not for the user files. Set -this to @code{nil} if the default makes @b{Ref@TeX{}} finding files with -equal names in wrong sequence. -@end defopt - -@defopt reftex-use-external-file-finders -Non-@code{nil} means, use external programs to find files. Normally, -@b{Ref@TeX{}} searches the paths given in the environment variables -@code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX -database files. With this option turned on, it calls an external -program specified in the option @code{reftex-external-file-finders} -instead. As a side effect, the variables -@code{reftex-texpath-environment-variables} and -@code{reftex-bibpath-environment-variables} will be ignored. -@end defopt - -@defopt reftex-external-file-finders -Association list with external programs to call for finding files. Each -entry is a cons cell @w{@code{(@var{type} . @var{program})}}. -@var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a -string containing the external program to use with any arguments. -@code{%f} will be replaced by the name of the file to be found. Note -that these commands will be executed directly, not via a shell. Only -relevant when @code{reftex-use-external-file-finders} is -non-@code{nil}. -@end defopt - -@page -@node Options (Optimizations), Options (Fontification), Options (Finding Files), Options -@section Optimizations -@cindex Options, optimizations -@cindex Optimizations, options - -@defopt reftex-keep-temporary-buffers -Non-@code{nil} means, keep buffers created for parsing and lookup. -@b{Ref@TeX{}} sometimes needs to visit files related to the current -document. We distinguish files visited for -@table @asis -@item PARSING -Parts of a multifile document loaded when (re)-parsing the -document. -@item LOOKUP -BibTeX database files and TeX files loaded to find a reference, to -display label context, etc. -@end table -The created buffers can be kept for later use, or be thrown away -immediately after use, depending on the value of this variable: - -@table @code -@item nil -Throw away as much as possible. -@item t -Keep everything. -@item 1 -Throw away buffers created for parsing, but keep the ones created for -lookup. -@end table - -If a buffer is to be kept, the file is visited normally (which is -potentially slow but will happen only once). If a buffer is to be thrown -away, the initialization of the buffer depends upon the variable -@code{reftex-initialize-temporary-buffers}. -@end defopt - -@defopt reftex-initialize-temporary-buffers -Non-@code{nil} means do initializations even when visiting file -temporarily. When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and -other stuff to briefly visit a file. When @code{t}, the full default -initializations are done (@code{find-file-hook} etc.). Instead of -@code{t} or @code{nil}, this variable may also be a list of hook -functions to do a minimal initialization. -@end defopt - -@defopt reftex-no-include-regexps -List of regular expressions to exclude certain input files from parsing. -If the name of a file included via @code{\include} or @code{\input} is -matched by any of the regular expressions in this list, that file is not -parsed by @b{Ref@TeX{}}. -@end defopt - -@defopt reftex-enable-partial-scans -Non-@code{nil} means, re-parse only 1 file when asked to re-parse. -Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}} -commands, or with the @kbd{r} key in menus. When this option is -@code{t} in a multifile document, we will only parse the current buffer, -or the file associated with the label or section heading near point in a -menu. Requesting re-parsing of an entire multifile document then -requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in -menus. -@end defopt - -@defopt reftex-save-parse-info -Non-@code{nil} means, save information gathered with parsing in files. -The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is -used to save the information. When this variable is @code{t}, -@itemize @minus -@item -accessing the parsing information for the first time in an editing -session will read that file (if available) instead of parsing the -document. -@item -exiting Emacs or killing a buffer in reftex-mode will cause a new -version of the file to be written. -@end itemize -@end defopt - -@defopt reftex-parse-file-extension -File extension for the file in which parser information is stored. -This extension is added to the base name of the master file. -@end defopt - -@defopt reftex-allow-automatic-rescan -Non-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seems -necessary. Applies (currently) only in rare cases, when a new label -cannot be placed with certainty into the internal label list. -@end defopt - -@defopt reftex-use-multiple-selection-buffers -Non-@code{nil} means use a separate selection buffer for each label -type. These buffers are kept from one selection to the next and need -not to be created for each use - so the menu generally comes up faster. -The selection buffers will be erased (and therefore updated) -automatically when new labels in its category are added. See the -variable @code{reftex-auto-update-selection-buffers}. -@end defopt - -@defopt reftex-auto-update-selection-buffers -Non-@code{nil} means, selection buffers will be updated automatically. -When a new label is defined with @code{reftex-label}, all selection -buffers associated with that label category are emptied, in order to -force an update upon next use. When @code{nil}, the buffers are left -alone and have to be updated by hand, with the @kbd{g} key from the -label selection process. The value of this variable will only have any -effect when @code{reftex-use-multiple-selection-buffers} is -non-@code{nil}. -@end defopt - -@node Options (Fontification), Options (Misc), Options (Optimizations), Options -@section Fontification -@cindex Options, fontification -@cindex Fontification, options - -@defopt reftex-use-fonts -Non-@code{nil} means, use fonts in label menu and on-the-fly help. -Font-lock must be loaded as well to actually get fontified -display. After changing this option, a rescan may be necessary to -activate it. -@end defopt - -@defopt reftex-refontify-context -Non-@code{nil} means, re-fontify the context in the label menu with -font-lock. This slightly slows down the creation of the label menu. It -is only necessary when you definitely want the context fontified. - -This option may have 3 different values: -@table @code -@item nil -Never refontify. -@item t -Always refontify. -@item 1 -Refontify when necessary, e.g. with old versions of the x-symbol -package. -@end table -The option is ignored when @code{reftex-use-fonts} is @code{nil}. -@end defopt - -@defopt reftex-highlight-selection -Non-@code{nil} means, highlight selected text in selection and -@file{*toc*} buffers. Normally, the text near the cursor is the -@emph{selected} text, and it is highlighted. This is the entry most -keys in the selection and @file{*toc*} buffers act on. However, if you -mainly use the mouse to select an item, you may find it nice to have -mouse-triggered highlighting @emph{instead} or @emph{as well}. The -variable may have one of these values: - -@example -nil @r{No highlighting.} -cursor @r{Highlighting is cursor driven.} -mouse @r{Highlighting is mouse driven.} -both @r{Both cursor and mouse trigger highlighting.} -@end example - -Changing this variable requires to rebuild the selection and *toc* -buffers to become effective (keys @kbd{g} or @kbd{r}). -@end defopt - -@defopt reftex-cursor-selected-face -Face name to highlight cursor selected item in toc and selection buffers. -See also the variable @code{reftex-highlight-selection}. -@end defopt -@defopt reftex-mouse-selected-face -Face name to highlight mouse selected item in toc and selection buffers. -See also the variable @code{reftex-highlight-selection}. -@end defopt -@defopt reftex-file-boundary-face -Face name for file boundaries in selection buffer. -@end defopt -@defopt reftex-label-face -Face name for labels in selection buffer. -@end defopt -@defopt reftex-section-heading-face -Face name for section headings in toc and selection buffers. -@end defopt -@defopt reftex-toc-header-face -Face name for the header of a toc buffer. -@end defopt -@defopt reftex-bib-author-face -Face name for author names in bib selection buffer. -@end defopt -@defopt reftex-bib-year-face -Face name for year in bib selection buffer. -@end defopt -@defopt reftex-bib-title-face -Face name for article title in bib selection buffer. -@end defopt -@defopt reftex-bib-extra-face -Face name for bibliographic information in bib selection buffer. -@end defopt -@defopt reftex-select-mark-face -Face name for marked entries in the selection buffers. -@end defopt -@defopt reftex-index-header-face -Face name for the header of an index buffer. -@end defopt -@defopt reftex-index-section-face -Face name for the start of a new letter section in the index. -@end defopt -@defopt reftex-index-tag-face -Face name for index names (for multiple indices). -@end defopt -@defopt reftex-index-face -Face name for index entries. -@end defopt - -@node Options (Misc), , Options (Fontification), Options -@section Miscellaneous -@cindex Options, misc - -@defopt reftex-extra-bindings -Non-@code{nil} means, make additional key bindings on startup. These -extra bindings are located in the users @samp{C-c letter} -map. @xref{Key Bindings}. -@end defopt - -@defopt reftex-plug-into-AUCTeX -Plug-in flags for AUCTeX interface. This variable is a list of -5 boolean flags. When a flag is non-@code{nil}, @b{Ref@TeX{}} -will - -@example -- supply labels in new sections and environments (flag 1) -- supply arguments for macros like @code{\label} (flag 2) -- supply arguments for macros like @code{\ref} (flag 3) -- supply arguments for macros like @code{\cite} (flag 4) -- supply arguments for macros like @code{\index} (flag 5) -@end example - -You may also set the variable itself to t or nil in order to turn all -options on or off, respectively.@* -Supplying labels in new sections and environments applies when creating -sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@* -Supplying macro arguments applies when you insert such a macro -interactively with @kbd{C-c @key{RET}}.@* -See the AUCTeX documentation for more information. -@end defopt - -@defopt reftex-revisit-to-follow -Non-@code{nil} means, follow-mode will revisit files if necessary. -When nil, follow-mode will be suspended for stuff in unvisited files. -@end defopt - -@defopt reftex-allow-detached-macro-args -Non-@code{nil} means, allow arguments of macros to be detached by -whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb -[xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that -this will be the case even if @code{\bb} is defined with zero or one -argument. -@end defopt - -@node Keymaps and Hooks, Changes, Options, Top -@section Keymaps and Hooks -@cindex Keymaps - -@b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook. - -@deffn Keymap reftex-mode-map -The keymap for @b{Ref@TeX{}} mode. -@end deffn - -@deffn {Normal Hook} reftex-load-hook -Normal hook which is being run when loading @file{reftex.el}. -@end deffn - -@deffn {Normal Hook} reftex-mode-hook -Normal hook which is being run when turning on @b{Ref@TeX{}} mode. -@end deffn - -Furthermore, the 4 modes used for referencing labels, creating -citations, the table of contents buffer and the phrases buffer have -their own keymaps and mode hooks. See the respective sections. There -are many more hooks which are described in the relevant sections about -options for a specific part of @b{Ref@TeX{}}. - -@node Changes, GNU Free Documentation License, Keymaps and Hooks, Top -@chapter Changes -@cindex Changes - -Here is a list of recent changes to @b{Ref@TeX{}}. - -@noindent @b{Version 4.28} -@itemize @bullet -@item Support for the Jurabib package. -@item Improvements when selecting several items in a selection buffer. -@end itemize - -@noindent @b{Version 4.26} -@itemize @bullet -@item -Support for global incremental search. -@item -Some improvements for XEmacs compatibility. -@end itemize - -@noindent @b{Version 4.25} -@itemize @bullet -@item -Fixed bug with @samp{%F} in a label prefix. Added new escapes -@samp{%m} and @samp{%M} for mater file name and master directory. -@end itemize - -@noindent @b{Version 4.24} -@itemize @bullet -@item -Inserting citation commands now prompts for optional arguments -when called with a prefix argument. Related new options are -@code{reftex-cite-prompt-optional-args} and -@code{reftex-cite-cleanup-optional-args}. -@item -New option @code{reftex-trust-label-prefix}. Configure this variable -if you'd like RefTeX to base its classification of labels on prefixes. -This can speed-up document parsing, but may in some cases reduce the -quality of the context used by RefTeX to describe a label. -@item -Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations} -is non-nil. -@item -Fixed bugs in indexing: Case-sensitive search, quotes before and/or -after words. Disabled indexing in comment lines. -@end itemize - -@noindent @b{Version 4.22} -@itemize @bullet -@item -New command @code{reftex-create-bibtex-file} to create a new database -with all entries referenced in the current document. -@item -New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file -from entries marked in a citation selection buffer. -@end itemize - -@noindent @b{Version 4.21} -@itemize @bullet -@item -Renaming labels from the toc buffer with key @kbd{M-%}. -@end itemize - -@noindent @b{Version 4.20} -@itemize @bullet -@item -Structure editing capabilities. The command keys @kbd{<} and @kbd{>} in -the TOC buffer promote/demote the section at point or all sections in -the current region. -@item -New option @code{reftex-toc-split-windows-fraction} to set the size of -the window used by the TOC. This makes the old variable -@code{reftex-toc-split-windows-horizontally-fraction} obsolete. -@item -A dedicated frame can show the TOC with the current section -always automatically highlighted. The frame is created and -deleted from the toc buffer with the @kbd{d} key. -@end itemize - -@noindent @b{Version 4.19} -@itemize @bullet -@item -New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current -section in the TOC buffer without selecting the TOC window. -@item -Recentering happens automatically in idle time when the option -@code{reftex-auto-recenter-toc} is turned on. -@item -Fixed several bugs related to automatic cursor positioning in the TOC -buffer. -@item -The highlight in the TOC buffer stays when the focus moves to a -different window. -@item -New command `reftex-goto-label'. -@item -Part numbers are no longer included in chapter numbers, and a new -part does not reset the chapter counter. See new option -@code{reftex-part-resets-chapter}. -@end itemize - -@noindent @b{Version 4.18} -@itemize @bullet -@item -@code{reftex-citation} uses the word before the cursor as a default -search string. -@item -Simplified several regular expressions for speed. -@item -Better support for chapterbib. -@end itemize - -@noindent @b{Version 4.17} -@itemize @bullet -@item -The toc window can be split off horizontally. See new options -@code{reftex-toc-split-windows-horizontally}, -@code{reftex-toc-split-windows-horizontally-fraction}. -@item -It is possible to specify a function which verifies an index match -during global indexing. See new option @code{reftex-index-verify-function}. -@item -The macros which input a file in LaTeX (like \input, \include) can -be configured. See new option @code{reftex-include-file-commands}. -@item -The macros which specify the bibliography file (like \bibliography) can -be configured. See new option @code{reftex-bibliography-commands}. -@item -The regular expression used to search for the \bibliography macro has -been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by -chapterbib. -@item -Small bug fixes. -@end itemize - -@noindent @b{Version 4.15} -@itemize @bullet -@item -Fixed bug with parsing of BibTeX files, when fields contain quotes or -unmatched parenthesis. -@item -Small bug fixes. -@item -Improved interaction with Emacs LaTeX mode. -@end itemize - -@noindent @b{Version 4.12} -@itemize @bullet -@item -Support for @file{bibentry} citation style. -@end itemize - -@noindent @b{Version 4.11} -@itemize @bullet -@item -Fixed bug which would parse @samp{\Section} just like @samp{\section}. -@end itemize - -@noindent @b{Version 4.10} -@itemize @bullet -@item -Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict -with @file{reftex-vars.el} on DOS machines. -@item -New options @code{reftex-parse-file-extension} and -@code{reftex-index-phrase-file-extension}. -@end itemize - -@noindent [.....] -@ignore -@noindent @b{Version 4.09} -@itemize @bullet -@item -New option @code{reftex-toc-max-level} to limit the depth of the toc. -New key binding @kbd{t} in the @file{*toc*} buffer to change this -setting. -@item -RefTeX maintains an @file{Index Phrases} file in which phrases can be -collected. When the document is ready, RefTeX can search all -these phrases and assist indexing all matches. -@item -The variables @code{reftex-index-macros} and -@code{reftex-index-default-macro} have changed their syntax slightly. -The @var{repeat} parameter has move from the latter to the former. -Also calls to @code{reftex-add-index-macros} from AUCTeX style files -need to be adapted. -@item -The variable @code{reftex-section-levels} no longer contains the -default stuff which has been moved to a constant. -@item -Environments like theorems can be placed into the TOC by putting -entries for @samp{"begin@{theorem@}"} in -@code{reftex-section-levels}. -@end itemize - -@noindent @b{Version 4.06} -@itemize @bullet -@item -@code{reftex-section-levels} can contain a function to compute the level -of a sectioning command. -@item -Multiple @code{thebibliography} environments recognized. -@end itemize - -@noindent @b{Version 4.04} -@itemize @bullet -@item -New option @code{reftex-index-default-tag} implements a default for queries. -@end itemize - -@noindent @b{Version 4.02} -@itemize @bullet -@item -macros ending in @samp{refrange} are considered to contain references. -@item -Index entries made with @code{reftex-index-selection-or-word} in TeX -math mode automatically get enclosing @samp{$} to preserve math mode. See -new option @code{reftex-index-math-format}. Requires AUCTeX. -@end itemize - -@noindent @b{Version 4.01} -@itemize @bullet -@item -New command @code{reftex-index-globally} to index a word in many -places in the document. Also available from the index buffer with -@kbd{&}. -@item -The first item in a @code{reftex-label-alist} entry may now also be a parser -function to do non-standard parsing. -@item -@code{reftex-auto-view-crossref} no longer interferes with -@code{pop-up-frames} (patch from Stefan Monnier). -@end itemize - -@noindent @b{Version 4.00} -@itemize @bullet -@item -RefTeX has been split into several smaller files which are autoloaded on -demand. -@item -Index support, along with many new options. -@item -The selection of keys for @code{\ref} and @code{\cite} now allows to -select multiple items by marking entries with the @kbd{m} key. -@item -Fancyref support. -@end itemize - -@noindent @b{Version 3.43} -@itemize @bullet -@item -Viewing cross-references generalized. Now works on @code{\label}, -@code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of -these, and from BibTeX buffers. -@item -New option @code{reftex-view-crossref-extra}. -@item -Support for the additional sectioning commands @code{\addchap} and -@code{\addsec} which are defined in the LaTeX KOMA-Script classes. -@item -Files in @code{reftex-default-bibliography} will be searched along -@code{BIBINPUTS} path. -@item -Reading a parse file now checks consistency. -@end itemize - -@noindent @b{Version 3.42} -@itemize @bullet -@item -File search further refined. New option @code{reftex-file-extensions}. -@item -@file{*toc*} buffer can show the file boundaries of a multifile -document, all labels and associated context. New keys @kbd{i}, @kbd{l}, -and @kbd{c}. New options @code{reftex-toc-include-labels}, -@code{reftex-toc-include-context}, -@code{reftex-toc-include-file-boundaries}. -@end itemize - -@noindent @b{Version 3.41} -@itemize @bullet -@item -New options @code{reftex-texpath-environment-variables}, -@code{reftex-use-external-file-finders}, -@code{reftex-external-file-finders}, -@code{reftex-search-unrecursed-path-first}. -@item -@emph{kpathsearch} support. See new options and -@code{reftex-bibpath-environment-variables}. -@end itemize - -@noindent @b{Version 3.38} -@itemize @bullet -@item -@code{reftex-view-crossref} no longer moves to find a macro. Point has -to be on the macro argument. -@end itemize - -@noindent @b{Version 3.36} -@itemize @bullet -@item -New value @code{window} for option @code{reftex-auto-view-crossref}. -@end itemize - -@noindent @b{Version 3.35} -@itemize @bullet -@item -ISO 8859 Latin-1 chars are converted to ASCII to derive better labels. -This takes back the related changes in 3.34 for safety reasons. -@end itemize - -@noindent @b{Version 3.34} -@itemize @bullet -@item -Additional flag in @code{reftex-derive-label-parameters} do make only -lowercase labels (default @code{t}). -@item -All @file{.rel} files have a final newline to avoid queries. -@item -Single byte representations of accented European letters (ISO-8859-1) -are now valid in labels. -@end itemize - -@noindent @b{Version 3.33} -@itemize @bullet -@item -Multiple selection buffers are now hidden buffers (they start with a -SPACE). -@item -Fixed bug with file search when TEXINPUTS environment variable is empty. -@end itemize - -@noindent @b{Version 3.30} -@itemize @bullet -@item -In @code{reftex-citation}, the regular expression used to scan BibTeX -files can be specified using completion on known citation keys. -@item -New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all} -entries. -@item -New command @code{reftex-renumber-simple-labels} to renumber simple -labels like @samp{eq:13} sequentially through a document. -@end itemize - -@noindent @b{Version 3.28} -@itemize @bullet -@item -Auto view crossref for XEmacs uses @code{post-command-hook} to restart the -timer, since itimer restart is not reliable. -@item -Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}. -@item -Expansion of recursive tex and bib path rewritten. -@item -Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers. -@item -Fixed bug with section numbering after *-red sections. -@end itemize - -@noindent @b{Version 3.27} -@itemize @bullet -@item -Macros can define @emph{neutral} labels, just like @code{\label} -itself. -@item -New option @code{reftex-allow-detached-macro-args}, default @code{nil}! -@end itemize - -@noindent @b{Version 3.26} -@itemize @bullet -@item -[X]Emacs 19 no longer supported. Use 3.22 for Emacs 19. -@item -New hooks @code{reftex-translate-to-ascii-function}, -@code{reftex-string-to-label-function}. -@item -Made sure automatic crossref display will not visit/scan files. -@end itemize - -@noindent @b{Version 3.25} -@itemize @bullet -@item -Echoing of citation info caches the info for displayed entries. -New option @code{reftex-cache-cite-echo}. -@item -@kbd{M-x reftex-reset-mode} now also removes the file with parsing -info. -@item -Default of @code{reftex-revisit-to-follow} changed to nil. -@end itemize - -@noindent @b{Version 3.24} -@itemize @bullet -@item -New option @code{reftex-revisit-to-echo}. -@item -Interface with X-Symbol (>=2.6) is now complete and stable. -@item -Adapted to new outline, which uses overlays. -@item -File names in @code{\bibliography} may now have the @code{.bib} -extension. -@item -Fixed Bug with parsing "single file" from master file buffer. -@end itemize - -@noindent @b{Version 3.23} -@itemize @bullet -@item -Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs. -@item -@code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse -file. -@item -The cursor inside a @code{\ref} or @code{\cite} macro can now trigger -automatic display of crossref information in the echo area. See -variable @code{reftex-auto-view-crossref}. -@item -AUCTeX interface updates: -@itemize @minus -@item -AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections. -@item -@b{Ref@TeX{}} notifies AUCTeX about new labels. -@item -@code{TeX-arg-ref} no longer used (introduction was unnecessary). -@item -@code{reftex-arg-label} and @code{reftex-arg-cite} fixed up. -@item -Settings added to @b{Ref@TeX{}} via style files remain local. -@end itemize -@item -Fixed bug with @code{reftex-citation} in non-latex buffers. -@item -Fixed bug with syntax table and context refontification. -@item -Safety-net for name change of @code{font-lock-reference-face}. -@end itemize - -@noindent @b{Version 3.22} -@itemize @bullet -@item -Fixed bug with empty context strings. -@item -@code{reftex-mouse-view-crossref} is now bound by default at -@kbd{S-mouse-2}. -@end itemize - -@noindent @b{Version 3.21} -@itemize @bullet -@item -New options for all faces used by @b{Ref@TeX{}}. They're in the -customization group @code{reftex-fontification-configurations}. -@end itemize - -@noindent @b{Version 3.19} -@itemize @bullet -@item -Fixed bug with AUCTeX @code{TeX-master}. -@end itemize - -@noindent @b{Version 3.18} -@itemize @bullet -@item -The selection now uses a recursive edit, much like minibuffer input. -This removes all restrictions during selection. E.g. you can now -switch buffers at will, use the mouse etc. -@item -New option @code{reftex-highlight-selection}. -@item -@kbd{mouse-2} can be used to select in selection and @file{*toc*} -buffers. -@item -Fixed some problems regarding the interaction with VIPER mode. -@item -Follow-mode is now only used after point motion. -@item -@b{Ref@TeX{}} now finally does not fontify temporary files anymore. -@end itemize - -@noindent @b{Version 3.17} -@itemize @bullet -@item -Additional bindings in selection and @file{*toc*} buffers. @kbd{g} -redefined. -@item -New command @code{reftex-save-all-document-buffers}. -@item -Magic word matching made more intelligent. -@item -Selection process can switch to completion (with @key{TAB}). -@item -@code{\appendix} is now recognized and influences section numbering. -@item -File commentary shortened considerably (use Info documentation). -@item -New option @code{reftex-no-include-regexps} to skip some include files. -@item -New option @code{reftex-revisit-to-follow}. -@end itemize - -@noindent @b{Version 3.16} -@itemize @bullet -@item -New hooks @code{reftex-format-label-function}, -@code{reftex-format-ref-function}, @code{reftex-format-cite-function}. -@item -TeXInfo documentation completed. -@item -Some restrictions in Label inserting and referencing removed. -@item -New variable @code{reftex-default-bibliography}. -@end itemize - -@noindent @b{Version 3.14} -@itemize @bullet -@item -Selection buffers can be kept between selections: this is faster. -See new variable @code{reftex-use-multiple-selection-buffers}. -@item -Prefix interpretation of reftex-view-crossref changed. -@item -Support for the @code{varioref} package (@kbd{v} key in selection -buffer). -@end itemize - -@noindent @b{Version 3.12} -@itemize @bullet -@item -There are 3 new keymaps for customization: @code{reftex-toc-map}, -@code{reftex-select-label-map}, @code{reftex-select-bib-map}. -@item -Refontification uses more standard font-lock stuff. -@item -When no BibTeX database files are specified, citations can also use -@code{\bibitem} entries from a @code{thebibliography} environment. -@end itemize - -@noindent @b{Version 3.11} -@itemize @bullet -@item -Fixed bug which led to naked label in (e.g.) footnotes. -@item -Added scroll-other-window functions to RefTeX-Select. -@end itemize - -@noindent @b{Version 3.10} -@itemize @bullet -@item -Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19. -@item -Removed unimportant code which caused OS/2 Emacs to crash. -@item -All customization variables now accessible from menu. -@end itemize - -@noindent @b{Version 3.07} -@itemize @bullet -@item -@code{Ref} menu improved. -@end itemize - -@noindent @b{Version 3.05} -@itemize @bullet -@item -Compatibility code now first checks for XEmacs feature. -@end itemize - -@noindent @b{Version 3.04} -@itemize @bullet -@item -Fixed BUG in the @emph{xr} support. -@end itemize - -@noindent @b{Version 3.03} -@itemize @bullet -@item -Support for the LaTeX package @code{xr}, for inter-document -references. -@item -A few (minor) Mule-related changes. -@item -Fixed bug which could cause @emph{huge} @file{.rel} files. -@item -Search for input and @file{.bib} files with recursive path definitions. -@end itemize - -@noindent @b{Version 3.00} -@itemize @bullet -@item -@b{Ref@TeX{}} should work better for very large projects: -@item -The new parser works without creating a master buffer. -@item -Rescanning can be limited to a part of a multifile document. -@item -Information from the parser can be stored in a file. -@item -@b{Ref@TeX{}} can deal with macros having a naked label as an argument. -@item -Macros may have white space and newlines between arguments. -@item -Multiple identical section headings no longer confuse -@code{reftex-toc}. -@item -@b{Ref@TeX{}} should work correctly in combination with buffer-altering -packages like outline, folding, x-symbol, iso-cvt, isotex, etc. -@item -All labeled environments discussed in @emph{The LaTeX Companion} by -Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of -@b{Ref@TeX{}}'s defaults. -@end itemize - -@noindent @b{Version 2.17} -@itemize @bullet -@item -Label prefix expands % escapes with current file name and other stuff. -@item -Citation format now with % escapes. This is not backward -compatible! -@item -TEXINPUTS variable recognized when looking for input files. -@item -Context can be the nth argument of a macro. -@item -Searching in the select buffer is now possible (@kbd{C-s} and -@kbd{C-r}). -@item -Display and derive-label can use two different context methods. -@item -AMSmath @code{xalignat} and @code{xxalignat} added. -@end itemize - -@noindent @b{Version 2.14} -@itemize @bullet -@item -Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with -AUCTeX. -@end itemize - -@noindent @b{Version 2.11} -@itemize @bullet -@item -Submitted for inclusion to Emacs and XEmacs. -@end itemize - -@noindent @b{Version 2.07} -@itemize @bullet -@item -New functions @code{reftex-search-document}, -@code{reftex-query-replace-document}. -@end itemize - -@noindent @b{Version 2.05} -@itemize @bullet -@item -Support for @file{custom.el}. -@item -New function @code{reftex-grep-document} (thanks to Stephen Eglen). -@end itemize - -@noindent @b{Version 2.03} -@itemize @bullet -@item -@code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to -default environments. -@item -@code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari). -@item -New functions @code{reftex-arg-label}, @code{reftex-arg-ref}, -@code{reftex-arg-cite}. -@item -Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is -required. -@item -@code{reftex-add-to-label-alist} (to be called from AUCTeX style -files). -@item -Finding context with a hook function. -@item -Sorting BibTeX entries (new variable: -@code{reftex-sort-bibtex-matches}). -@end itemize - -@noindent @b{Version 2.00} -@itemize @bullet -@item -Labels can be derived from context (default for sections). -@item -Configuration of label insertion and label referencing revised. -@item -Crossref fields in BibTeX database entries. -@item -@code{reftex-toc} introduced (thanks to Stephen Eglen). -@end itemize - -@noindent @b{Version 1.09} -@itemize @bullet -@item -Support for @code{tex-main-file}, an analogue for -@code{TeX-master}. -@item -MS-DOS support. -@end itemize - -@noindent @b{Version 1.07} -@itemize @bullet -@item -@b{Ref@TeX{}} gets its own menu. -@end itemize - -@noindent @b{Version 1.05} -@itemize @bullet -@item -XEmacs port. -@end itemize - -@noindent @b{Version 1.04} -@itemize @bullet -@item -Macros as wrappers, AMSTeX support, delayed context parsing for -new labels. -@end itemize -@end ignore - -@noindent @b{Version 1.00} -@itemize @bullet -@item -released on 7 Jan 1997. -@end itemize - -@node GNU Free Documentation License, Index, Changes, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index, , GNU Free Documentation License, Top -@unnumbered Index -@printindex cp - -@bye diff --git a/doc/misc/remember.texi b/doc/misc/remember.texi deleted file mode 100644 index 1dd7d1b6153..00000000000 --- a/doc/misc/remember.texi +++ /dev/null @@ -1,412 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/remember -@settitle Remember Manual -@syncodeindex fn cp -@c %**end of header - -@copying -This manual is for Remember Mode, version 1.9 - -Copyright @copyright{} 2001, 2004-2005, 2007-2012 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Remember: (remember). Simple information manager for Emacs. -@end direntry - -@titlepage -@title Guide to Remember Mode -@subtitle a simple information manager -@subtitle for Emacs and XEmacs - -@c The following two commands -@c start the copyright page. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Preface, (dir), (dir) -@comment node-name, next, previous, up -@top Remember - -@insertcopying -@end ifnottex - -@menu -* Preface:: About the documentation. -* Introduction:: What is Remember Mode? -* Installation:: How to install Remember. -* Implementation:: How Remember came into existence. -* Quick Start:: Get started using Remember. -* Function Reference:: Interactive functions in remember.el. -* Keystrokes:: Keystrokes bound in Remember Mode. -* Backends:: Backends for saving notes. -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: Search for terms. - -@detailmenu - --- The Detailed Node Listing --- - -Backends - -* Text File:: Saving to a text file. -* Diary:: Saving to a Diary file. -* Mailbox:: Saving to a mailbox. -* Org:: Saving to an Org Mode file. - -@end detailmenu -@end menu - -@node Preface, Introduction, Top, Top -@comment node-name, next, previous, up -@chapter Preface - -This document describes remember-el, which was written by John Wiegley, -was once maintained by Sacha Chua, and is now maintained by the Emacs -developers. - -This document is a work in progress, and your contribution will be -greatly appreciated. - -@node Introduction, Installation, Preface, Top -@comment node-name, next, previous, up -@chapter Introduction - -Todo lists, schedules, phone databases... everything we use databases -for is really just a way to extend the power of our memory, to be able -to remember what our conscious mind may not currently have access to. - -There are many different databases out there---and good ones---which -this mode is not trying to replace. Rather, it's how that data gets -there that's the question. Most of the time, we just want to say -"Remember so-and-so's phone number, or that I have to buy dinner for the -cats tonight." That's the FACT. How it's stored is really the -computer's problem. But at this point in time, it's most definitely -also the user's problem, and sometimes so laboriously so that people -just let data slip, rather than expend the effort to record it. - -``Remember'' is a mode for remembering data. It uses whatever -back-end is appropriate to record and correlate the data, but its main -intention is to allow you to express as @emph{little} structure as -possible up front. If you later want to express more powerful -relationships between your data, or state assumptions that were at -first too implicit to be recognized, you can ``study'' the data later -and rearrange it. But the initial ``just remember this'' impulse -should be as close to simply throwing the data at Emacs as possible. - -Have you ever noticed that having a laptop to write on doesn't -@emph{actually} increase the amount of quality material that you turn -out, in the long run? Perhaps it's because the time we save -electronically in one way, we're losing electronically in another; the -tool should never dominate one's focus. As the mystic Faridu'd-Din -`Attar wrote: ``Be occupied as little as possible with things of the -outer world but much with things of the inner world; then right action -will overcome inaction.'' - -If Emacs could become a more intelligent data store, where brainstorming -would focus on the @emph{ideas} involved---rather than the structuring -and format of those ideas, or having to stop your current flow of work -in order to record them---it would map much more closely to how the mind -(well, at least mine) works, and hence would eliminate that very -manual-ness which computers from the very beginning have been championed -as being able to reduce. - -@node Installation, Implementation, Introduction, Top -@comment node-name, next, previous, up -@chapter Installation - -Installing Remember Mode is as simple as adding the following lines to -your Emacs configuration file (usually @file{~/.emacs.d/init.el} or -@file{~/.emacs}). - -@lisp -(add-to-list 'load-path "/path/to/remember") -(require 'remember) -@end lisp - -@node Implementation, Quick Start, Installation, Top -@comment node-name, next, previous, up -@chapter Implementation - -Hyperbole, as a data presentation tool, always struck me as being very -powerful, but it seemed to require a lot of ``front-end'' work before -that data was really available. The problem with BBDB, or keeping up -a Bibl-mode file, is that you have to use different functions to -record the data, and it always takes time to stop what you're doing, -format the data in the manner expected by that particular data -interface, and then resume your work. - -With ``remember'', you just hit @kbd{M-x remember} (you'd probably -want to bind this to an easily accessible keystroke, like @kbd{C-x -M-r}), slam in your text however you like, and then hit @kbd{C-c C-c}. -It will file the data away for later retrieval, and possibly indexing. - -Indexing is to data what ``studying'' is in the real world. What you do -when you study (or lucubrate, for some of us) is to realize certain -relationships implicit in the data, so that you can make use of those -relationships. Expressing that a certain quote you remembered was a -literary quote, and that you want the ability to pull up all quotes of a -literary nature, is what studying does. This is a more labor intensive -task than the original remembering of the data, and it's typical in real -life to set aside a special period of time for doing this work. - -``Remember'' works in the same way. When you enter data, either by -typing it into a buffer, or using the contents of the selected region, -it will store that data---unindexed, uninterpreted---in a data pool. -It will also try to remember as much context information as possible -(any text properties that were set, where you copied it from, when, -how, etc). Later, you can walk through your accumulated set of data -(both organized, and unorganized) and easily begin moving things -around, and making annotations that will express the full meaning of -that data, as far as you know it. - -Obviously this latter stage is more user-interface intensive, and it -would be nice if ``remember'' could do it as elegantly as possible, -rather than requiring a billion keystrokes to reorganize your -hierarchy. Well, as the future arrives, hopefully experience and user -feedback will help to make this as intuitive a tool as possible. - -@node Quick Start, Function Reference, Implementation, Top -@comment node-name, next, previous, up -@chapter Quick Start - -@itemize - -@item -Load @file{remember.el}. - -@item -Type @kbd{M-x remember}. The @samp{*Remember*} buffer should be -displayed. - -@item -Type in what you want to remember. The first line will be treated as -the headline, and the rest of the buffer will contain the body of the -note. - -@item -Type @kbd{C-c C-c} (@code{remember-finalize}) to save the note and close -the @samp{*Remember*} buffer. -@end itemize - -By default, @code{remember-finalize} saves the note in @file{~/.notes}. -You can edit it now to see the remembered and timestamped note. You -can edit this file however you want. New entries will always be added -to the end. - -To remember a region of text, use the universal prefix. @kbd{C-u M-x -remember} displays a @samp{*Remember*} buffer with the region as the -initial contents. - -As a simple beginning, you can start by using the Text File backend, -keeping your @file{~/.notes} file in outline-mode format, with a final -entry called @samp{* Raw data}. Remembered data will be added to the -end of the file. Every so often, you can move the data that gets -appended there into other files, or reorganize your document. - -You can also store remembered data in other backends. -(@pxref{Backends}) - -Here is one way to map the remember functions in your @file{.emacs} to -very accessible keystrokes facilities using the mode: - -@lisp -(autoload 'remember ``remember'' nil t) -(autoload 'remember-region ``remember'' nil t) - -(define-key global-map (kbd " r") 'remember) -(define-key global-map (kbd " R") 'remember-region) -@end lisp - -By default, remember uses the first annotation returned by -@code{remember-annotation-functions}. To include all of the annotations, -set @code{remember-run-all-annotation-functions-flag} to non-nil. - -@defopt remember-run-all-annotation-functions-flag -Non-nil means use all annotations returned by -@code{remember-annotation-functions}. -@end defopt - -You can write custom functions that use a different set of -remember-annotation-functions. For example: - -@lisp -(defun my/remember-with-filename () - "Always use the filename." - (interactive) - (let ((remember-annotation-functions '(buffer-file-name))) - (call-interactively 'remember))) -@end lisp - -@node Function Reference, Keystrokes, Quick Start, Top -@comment node-name, next, previous, up -@chapter Function Reference - -@file{remember.el} defines the following interactive functions: - -@defun remember initial -Remember an arbitrary piece of data. With a prefix, it will use the -region as @var{initial}. -@end defun - -@defun remember-region beg end -If called from within the remember buffer, @var{beg} and @var{end} are -ignored, and the entire buffer will be remembered. If called from any -other buffer, that region, plus any context information specific to -that region, will be remembered. -@end defun - -@defun remember-clipboard -Remember the contents of the current clipboard. This is most useful -for remembering things from Netscape or other X Windows applications. -@end defun - -@defun remember-finalize -Remember the contents of the current buffer. -@end defun - -@defun remember-mode -This enters the major mode for output from @command{remember}. This -buffer is used to collect data that you want remember. Just hit -@kbd{C-c C-c} when you're done entering, and it will go ahead and file -the data for latter retrieval, and possible indexing. -@end defun - -@node Keystrokes, Backends, Function Reference, Top -@comment node-name, next, previous, up -@chapter Keystroke Reference - -@file{remember.el} defines the following keybindings by default: - -@table @kbd - -@item C-c C-c (`remember-finalize') -Remember the contents of the current buffer. - -@item C-c C-k (`remember-destroy') -Destroy the current *Remember* buffer. - -@item C-x C-s (`remember-finalize') -Remember the contents of the current buffer. - -@end table - -@node Backends, GNU Free Documentation License, Keystrokes, Top -@comment node-name, next, previous, up -@chapter Backends - -You can save remembered notes to a variety of backends. - -@menu -* Text File:: Saving to a text file. -* Diary:: Saving to a Diary file. -* Mailbox:: Saving to a mailbox. -* Org:: Saving to an Org Mode file. -@end menu - -@node Text File, Diary, Backends, Backends -@comment node-name, next, previous, up -@section Saving to a Text File -@cindex text file, saving to - -@subheading Insinuation - -@lisp -(setq remember-handler-functions '(remember-append-to-file)) -@end lisp - -@subheading Options - -@defopt remember-data-file -The file in which to store unprocessed data. -@end defopt - -@defopt remember-leader-text -The text used to begin each remember item. -@end defopt - -@node Diary, Mailbox, Text File, Backends -@comment node-name, next, previous, up -@section Saving to a Diary file -@cindex diary, integration - -@subheading Insinuation - -@lisp -(add-to-list 'remember-handler-functions 'remember-diary-extract-entries) -@end lisp - -@subheading Options - -@defopt remember-diary-file -File for extracted diary entries. -If this is nil, then @code{diary-file} will be used instead." -@end defopt - -@node Mailbox, Org, Diary, Backends -@comment node-name, next, previous, up -@section Saving to a Mailbox -@cindex mailbox, saving to - -@subheading Insinuation - -@lisp -(add-to-list 'remember-handler-functions 'remember-store-in-mailbox) -@end lisp - -@subheading Options - -@defopt remember-mailbox -The file in which to store remember data as mail. -@end defopt - -@defopt remember-default-priority -The default priority for remembered mail messages. -@end defopt - -@node Org, , Mailbox, Backends -@comment node-name, next, previous, up -@section Saving to an Org Mode file -@cindex org mode, integration - -@ignore -From org.texi: -Up to version 6.36 Org used a special setup -for @file{remember.el}. @file{org-remember.el} is still part of Org mode for -backward compatibility with existing setups. You can find the documentation -for org-remember at @url{http://orgmode.org/org-remember.pdf}. -@end ignore -For instructions on how to integrate Remember with Org Mode, -consult @ref{Capture, , , org}. - -@node GNU Free Documentation License, Concept Index, Backends, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index, , GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Index - -@printindex cp - -@bye diff --git a/doc/misc/sasl.texi b/doc/misc/sasl.texi deleted file mode 100644 index a31d9ca5e38..00000000000 --- a/doc/misc/sasl.texi +++ /dev/null @@ -1,277 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@include gnus-overrides.texi - -@setfilename ../../info/sasl - -@set VERSION 0.2 -@settitle Emacs SASL Library @value{VERSION} - -@copying -This file describes the Emacs SASL library, version @value{VERSION}. - -Copyright @copyright{} 2000, 2004-2012 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License'' -in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* SASL: (sasl). The Emacs SASL library. -@end direntry - - -@titlepage -@ifset WEBHACKDEVEL -@title Emacs SASL Library @value{VERSION} (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title Emacs SASL Library @value{VERSION} -@end ifclear - -@author by Daiki Ueno -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - - -@node Top -@top Emacs SASL - -SASL is a common interface to share several authentication mechanisms between -applications using different protocols. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: What Emacs SASL library is. -* How to use:: Adding authentication support to your applications. -* Data types:: -* Back end drivers:: Writing your own drivers. -* Index:: -* Function Index:: -* Variable Index:: -@end menu - -@node Overview -@chapter Overview - -@sc{sasl} is short for @dfn{Simple Authentication and Security Layer}. -This standard is documented in RFC2222. It provides a simple method for -adding authentication support to various application protocols. - -The toplevel interface of this library is inspired by Java @sc{sasl} -Application Program Interface. It defines an abstraction over a series -of authentication mechanism drivers (@ref{Back end drivers}). - -Back end drivers are designed to be close as possible to the -authentication mechanism. You can access the additional configuration -information anywhere from the implementation. - -@node How to use -@chapter How to use - -(Not yet written). - -To use Emacs SASL library, please evaluate following expression at the -beginning of your application program. - -@lisp -(require 'sasl) -@end lisp - -If you want to check existence of sasl.el at runtime, instead you -can list autoload settings for functions you want. - -@node Data types -@chapter Data types - -There are three data types to be used for carrying a negotiated -security layer---a mechanism, a client parameter and an authentication -step. - -@menu -* Mechanisms:: -* Clients:: -* Steps:: -@end menu - -@node Mechanisms -@section Mechanisms - -A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl} -authentication mechanism driver. - -@defvar sasl-mechanisms -A list of mechanism names. -@end defvar - -@defun sasl-find-mechanism mechanisms - -Retrieve an appropriate mechanism. -This function compares @var{mechanisms} and @code{sasl-mechanisms} then -returns appropriate @code{sasl-mechanism} object. - -@example -(let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5"))) - (setq mechanism (sasl-find-mechanism server-supported-mechanisms))) -@end example - -@end defun - -@defun sasl-mechanism-name mechanism -Return name of mechanism, a string. -@end defun - -If you want to write an authentication mechanism driver (@ref{Back end -drivers}), use @code{sasl-make-mechanism} and modify -@code{sasl-mechanisms} and @code{sasl-mechanism-alist} correctly. - -@defun sasl-make-mechanism name steps -Allocate a @code{sasl-mechanism} object. -This function takes two parameters---name of the mechanism, and a list -of authentication functions. - -@example -(defconst sasl-anonymous-steps - '(identity ;no initial response - sasl-anonymous-response)) - -(put 'sasl-anonymous 'sasl-mechanism - (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps)) -@end example - -@end defun - -@node Clients -@section Clients - -A client (@code{sasl-client} object) initialized with four -parameters---a mechanism, a user name, name of the service and name of -the server. - -@defun sasl-make-client mechanism name service server -Prepare a @code{sasl-client} object. -@end defun - -@defun sasl-client-mechanism client -Return the mechanism (@code{sasl-mechanism} object) of client. -@end defun - -@defun sasl-client-name client -Return the authorization name of client, a string. -@end defun - -@defun sasl-client-service client -Return the service name of client, a string. -@end defun - -@defun sasl-client-server client -Return the server name of client, a string. -@end defun - -If you want to specify additional configuration properties, please use -@code{sasl-client-set-property}. - -@defun sasl-client-set-property client property value -Add the given property/value to client. -@end defun - -@defun sasl-client-property client property -Return the value of the property of client. -@end defun - -@defun sasl-client-set-properties client plist -Destructively set the properties of client. -The second argument is the new property list. -@end defun - -@defun sasl-client-properties client -Return the whole property list of client configuration. -@end defun - -@node Steps -@section Steps - -A step (@code{sasl-step} object) is an abstraction of authentication -``step'' which holds the response value and the next entry point for the -authentication process (the latter is not accessible). - -@defun sasl-step-data step -Return the data which @var{step} holds, a string. -@end defun - -@defun sasl-step-set-data step data -Store @var{data} string to @var{step}. -@end defun - -To get the initial response, you should call the function -@code{sasl-next-step} with the second argument @code{nil}. - -@example -(setq name (sasl-mechanism-name mechanism)) -@end example - -At this point we could send the command which starts a SASL -authentication protocol exchange. For example, - -@example -(process-send-string - process - (if (sasl-step-data step) ;initial response - (format "AUTH %s %s\r\n" name (base64-encode-string (sasl-step-data step) t)) - (format "AUTH %s\r\n" name))) -@end example - -To go on with the authentication process, all you have to do is call -@code{sasl-next-step} consecutively. - -@defun sasl-next-step client step -Perform the authentication step. -At the first time @var{step} should be set to @code{nil}. -@end defun - -@node Back end drivers -@chapter Back end drivers - -(Not yet written). - -@node Index -@chapter Index -@printindex cp - -@node Function Index -@chapter Function Index -@printindex fn - -@node Variable Index -@chapter Variable Index -@printindex vr - -@summarycontents -@contents -@bye - -@c End: diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi deleted file mode 100644 index 60de89e676d..00000000000 --- a/doc/misc/sc.texi +++ /dev/null @@ -1,1924 +0,0 @@ -\input texinfo @comment -*-texinfo-*- -@comment 3.48 -@comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/sc -@settitle Supercite User's Manual -@iftex -@finalout -@end iftex - -@c @setchapternewpage odd % For book style double sided manual. -@comment %**end of header (This is for running Texinfo on a region.) - -@copying -This document describes Supercite, an Emacs package for citing and -attributing replies to mail and news messages. - -Copyright @copyright{} 1993, 2001-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@c @smallbook - -@dircategory Emacs network features -@direntry -* SC: (sc). Supercite lets you cite parts of messages - you're replying to, in flexible ways. -@end direntry - -@titlepage -@title Supercite User's Manual -@subtitle cite and attribute mail and -@subtitle news, in flexible ways - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top Supercite -@comment node-name, next, previous, up - -@insertcopying - -The manual is divided -into the following chapters. - -@menu -* Introduction:: -* Citations:: -* Getting Connected:: -* Replying and Yanking:: -* Selecting an Attribution:: -* Configuring the Citation Engine:: -* Post-yank Formatting Commands:: -* Information Keys and the Info Alist:: -* Reference Headers:: -* Hints to MUA Authors:: -* Thanks and History:: - -* GNU Free Documentation License:: -* Concept Index:: -* Command Index:: -* Key Index:: -* Variable Index:: -@end menu -@end ifnottex - - -@node Introduction, Usage Overview, Top, Top -@chapter Introduction - -Supercite is a GNU Emacs package written entirely in Emacs Lisp. It -interfaces to most of the commonly used Emacs mail user agents -(@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides -sophisticated facilities for the citing and attributing of message -replies. Supercite has a very specific and limited role in the process -of composing replies to both USENET network news and electronic mail. - -The preferred way to spell Supercite is with a capital @samp{S}, -lowercase @samp{upercite}. - -@menu -* Usage Overview:: -* What Supercite Does Not Do:: -* What Supercite Does:: -@end menu - -@cindex MUA -@cindex NUA -Supercite is only useful in conjunction with MUAs and NUAs such as VM, -Gnus, RMAIL, MH-E, etc. Supercite is typically called by the MUA after a -reply buffer has been setup. Thereafter, Supercite's many commands and -formatting styles are available in that reply buffer until the reply is -sent. Supercite is re-initialized in each new reply buffer. - - -@node Usage Overview, What Supercite Does Not Do, Introduction, Introduction -@kindex r -@kindex f -@kindex C-c C-y -@cindex yank -@cindex cite, citing -@cindex attribute, attributing -@section Usage Overview - -Typical usage is as follows. You want to reply or followup to a message -in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f} -(i.e., ``forward'') to begin composing the reply. In response, the MUA -will create a reply buffer and initialize the outgoing mail headers -appropriately. The body of the reply will usually be empty at this -point. You now decide that you would like to include part of the -original message in your reply. To do this, you @dfn{yank} the original -message into the reply buffer, typically with a key stroke such as -@kbd{C-c C-y}. This sequence will invoke an MUA-specific function which -fills the body of the reply with the original message and then -@dfn{attributes} this text to its author. This is called @dfn{citing} -and its effect is to prefix every line from the original message with a -special text tag. Most MUAs provide some default style of citing; by -using Supercite you gain a wider flexibility in the look and style of -citations. Supercite's only job is to cite the original message. - -@node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction -@section What Supercite Doesn't Do - -Because of this clear division of labor, there are useful features which -are the sole responsibility of the MUA, even though it might seem that -Supercite should provide them. For example, many people would like to -be able to yank (and cite) only a portion of the original message. -Since Supercite only modifies the text it finds in the reply buffer as -set up by the MUA, it is the MUA's responsibility to do partial yanking. -@xref{Reply Buffer Initialization}.@refill - -@vindex mail-header-separator -Another potentially useful thing would be for Supercite to set up the -outgoing mail headers with information it gleans from the reply buffer. -But by previously agreed upon convention, any text above the -@code{mail-header-separator} which separates mail headers from message -bodies cannot be modified by Supercite. Supercite, in fact, doesn't -know anything about the meaning of these headers, and never ventures -outside the designated region. @xref{Hints to MUA Authors}, for more -details.@refill - -@node What Supercite Does, Citations, What Supercite Does Not Do, Introduction -@findex sc-cite-original -@section What Supercite Does - -Supercite is invoked for the first time on a reply buffer via your MUA's -reply or forward command. This command will actually perform citations -by calling a hook variable to which Supercite's top-level function -@code{sc-cite-original} has been added. When @code{sc-cite-original} is -executed, the original message must be set up in a very specific way, -but this is handled automatically by the MUA. @xref{Hints to MUA -Authors}.@refill - -@cindex info alist -The first thing Supercite does, via @code{sc-cite-original}, is to parse -through the original message's mail headers. It saves this data in an -@dfn{information association list}, or @dfn{info alist}. The information -in this list is used in a number of places throughout Supercite. -@xref{Information Keys and the Info Alist}.@refill - -@cindex nuking mail headers -@cindex reference header -After the mail header info is extracted, the headers are optionally -removed (@dfn{nuked}) from the reply. Supercite then writes a -@dfn{reference header} into the buffer. This reference header is a -string carrying details about the citation it is about to perform. - -@cindex modeline -Next, Supercite visits each line in the reply, transforming the line -according to a customizable ``script.'' Lines which were not previously -cited in the original message are given a citation, while already cited -lines remain untouched, or are coerced to your preferred style. -Finally, Supercite installs a keymap into the reply buffer so that you -have access to Supercite's post-yank formatting and reciting commands as -you subsequently edit your reply. You can tell that Supercite has been -installed into the reply buffer because that buffer's modeline will -display the minor mode string @samp{SC}. - -@cindex filladapt -@cindex gin-mode -@vindex fill-prefix -@findex fill-paragraph -When the original message is cited by @code{sc-cite-original}, it will -(optionally) be filled by Supercite. However, if you manually edit the -cited text and want to re-fill it, you must use an add-on package such -as @cite{filladapt} or @cite{gin-mode}. These packages can recognize -Supercited text and will fill them appropriately. Emacs's built-in -filling routines, e.g@. @code{fill-paragraph}, do not recognize cited -text and will not re-fill them properly because it cannot guess the -@code{fill-prefix} being used. -@xref{Post-yank Formatting Commands}, for details.@refill - -As mentioned above, Supercite provides commands to recite or uncite -regions of text in the reply buffer, and commands to perform other -beautifications on the cited original text, maintaining consistent and -informative citations throughout. Supercite tries to be as configurable -as possible to allow for a wide range of personalized citation styles, -but it is also immediately useful with the default configuration, once -it has been properly connected to your MUA. @xref{Getting Connected}, -for more details.@refill - -@node Citations, Citation Elements, What Supercite Does, Top -@cindex nested citations -@cindex citation -@chapter Citations - -A @dfn{citation} is the acknowledgement of the original author of a mail -message in the body of the reply. There are two basic citation styles -which Supercite supports. The first, called @dfn{nested citations} is -an anonymous form of citation; in other words, an indication is made -that the cited line was written by someone @emph{other} that the current -message author (i.e., other than you, the person composing the reply), -but no reference is made as to the identity of the original author. -This style should look familiar since its use on the net is widespread. -Here's an example of what a message buffer would look like using nested -citations after multiple replies: - -@example ->> John originally wrote this ->> and this as well -> Jane said that John didn't know -> what he was talking about -And that's what I think too. -@end example - -@menu -* Citation Elements:: -* Recognizing Citations:: -@end menu - -Note that multiple inclusions of the original messages result in a -nesting of the @samp{@code{>}} characters. This can sometimes be quite -confusing when many levels of citations are included since it may be -difficult or impossible to figure out who actually participated in the -thread, and multiple nesting of @samp{@code{>}} characters can sometimes -make the message very difficult for the eye to scan. - -@cindex non-nested citations -In @dfn{non-nested citations}, each cited line begins with an -informative string attributing that line to the original author. Only -the first level of attribution will be shown; subsequent citations don't -nest the citation strings. The above dialog might look like this when -non-nested citations are used: - -@example -John> John originally wrote this -John> and this as well -Jane> Jane said that John didn't know -Jane> what he was talking about -And that's what I think too. -@end example - -Notice here that my inclusion of Jane's inclusion of John's original -message did not result in a line cited with @samp{Jane>John>}. - -@vindex sc-nested-citation-p -@vindex nested-citation-p (sc-) -Supercite supports both styles of citation, and the variable -@code{sc-nested-citation-p} controls which style it will use when citing -previously uncited text. When this variable is @code{nil} (the default), -non-nested citations are used. When non-@code{nil}, nested citations -are used. - - -@node Citation Elements, Recognizing Citations, Citations, Citations -@cindex citation string -@section Citation Elements - -@dfn{Citation strings} are composed of one or more elements. Non-nested -citations are composed of four elements, three of which are directly -user definable. The elements are concatenated together, in this order: - -@cindex citation leader -@vindex citation-leader (sc-) -@vindex sc-citation-leader -@enumerate -@item -The @dfn{citation leader}. The citation leader is contained in the -variable @code{sc-citation-leader}, and has the default value of a -string containing four spaces. - -@cindex attribution string -@item -The @dfn{attribution string}. This element is supplied automatically by -Supercite, based on your preferences and the original message's mail -headers, though you may be asked to confirm Supercite's choice. -@xref{Selecting an Attribution}, for more details.@refill - -@cindex citation delimiter -@vindex sc-citation-delimiter -@vindex citation-delimiter (sc-) -@item -The @dfn{citation delimiter}. This string, contained in the variable -@code{sc-citation-delimiter} visually separates the citation from the -text of the line. This variable has a default value of @code{">"} and -for best results, the string should consist of only a single character. - -@cindex citation separator -@vindex citation-separator (sc-) -@vindex sc-citation-separator -@item -The @dfn{citation separator}. The citation separator is contained in -the variable @code{sc-citation-separator}, and has the default value of -a string containing a single space. -@end enumerate - -For example, suppose you were using the default values for the above -variables, and Supercite provided the attribution string @samp{Jane}. -In this case, the composed, non-nested citation string used might be -something like -@code{@asis{" Jane> "}}. -This citation string will be inserted in front of -every line in the original message that is not already cited.@refill - -Nested citations, being simpler than non-nested citations, are composed -of the same elements, sans the attribution string. Supercite is smart -enough to not put additional spaces between citation delimiters for -multi-level nested citations. - -@node Recognizing Citations, Getting Connected, Citation Elements, Citations -@section Recognizing Citations - -Supercite also recognizes citations in the original article, and can -transform these already cited lines in a number of ways. This is how -Supercite suppresses the multiple citing of non-nested citations. -Recognition of cited lines is controlled by variables analogous to those -that make up the citation string as mentioned previously. - -@vindex sc-citation-leader-regexp -@vindex citation-leader-regexp (sc-) -@vindex sc-citation-delimiter-regexp -@vindex citation-delimiter-regexp (sc-) -@vindex sc-citation-separator-regexp -@vindex citation-separator-regexp (sc-) -@vindex sc-citation-root-regexp -@vindex citation-root-regexp (sc-) -@vindex sc-citation-nonnested-root-regexp -@vindex citation-nonnested-root-regexp (sc-) - -The variable @code{sc-citation-leader-regexp} describes how citation -leaders can look, by default it matches any number of spaces or tabs. -Note that since the lisp function @code{looking-at} is used to do the -matching, if you change this variable it need not start with a leading -@code{"^"}. - -Similarly, the variables @code{sc-citation-delimiter-regexp} and -@code{sc-citation-separator-regexp} respectively describe how citation -delimiters and separators can look. They follow the same rule as -@code{sc-citation-leader-regexp} above. - -When Supercite composes a citation string, it provides the attribution -automatically. The analogous variable which handles recognition of the -attribution part of citation strings is @code{sc-citation-root-regexp}. -This variable describes the attribution root for both nested and -non-nested citations. By default it can match zero-to-many alphanumeric -characters (also ``.'', ``-'', and ``_''). But in some situations, -Supercite has to determine whether it is looking at a nested or -non-nested citation. Thus the variable -@code{sc-citation-nonnested-root-regexp} is used to describe only -non-nested citation roots. It is important to remember that if you -change @code{sc-citation-root-regexp} you should always also change -@code{sc-citation-nonnested-root-regexp}.@refill - -@node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top -@cindex information keys -@cindex Info Alist -@cindex information extracted from mail fields -@findex sc-mail-field -@findex mail-field (sc-) -@chapter Information Keys and the Info Alist - -@dfn{Mail header information keys} are nuggets of information that -Supercite extracts from the various mail headers of the original -message, placed in the reply buffer by the MUA. Information is kept in -the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in -various places within Supercite, such as in header rewrite functions and -attribution selection. Other bits of data, composed and created by -Supercite, are also kept as key-value pairs in this alist. In the case -of mail fields, the key is the name of the field, omitting the trailing -colon. Info keys are always case insensitive (as are mail headers), and -the value for a corresponding key can be retrieved from the alist with -the @code{sc-mail-field} function. Thus, if the following fields were -present in the original article:@refill - -@example -Date:@: 08 April 1991, 17:32:09 EST -Subject:@: Better get out your asbestos suit -@end example - -@vindex sc-mumble -@vindex mumble (sc-) -@noindent -then, the following lisp constructs return: - -@example -(sc-mail-field "date") -==> "08 April 1991, 17:32:09 EST" - -(sc-mail-field "subject") -==> "Better get out your asbestos suit" -@end example - -Since the argument to @code{sc-mail-field} can be any string, it is -possible that the mail field will not be present on the info alist -(possibly because the mail header was not present in the original -message). In this case, @code{sc-mail-field} will return the value of -the variable @code{sc-mumble}. - -Supercite always places all mail fields found in the yanked original -article into the info alist. If possible, Supercite will also places -the following keys into the info alist: - -@table @code -@cindex sc-attribution info field -@cindex attribution info field (sc-) -@item "sc-attribution" -the selected attribution string. - -@cindex sc-citation info field -@cindex citation info field (sc-) -@item "sc-citation" -the non-nested citation string. - -@cindex sc-from-address info field -@cindex from-address info field (sc-) -@item "sc-from-address" -email address extracted from the @samp{From:@:} field. - -@cindex sc-reply-address info field -@cindex reply-address info field (sc-) -@item "sc-reply-address" -email address extracted from the @samp{Reply-To:@:} field. - -@cindex sc-sender-address info field -@cindex sender-address info field (sc-) -@item "sc-sender-address" -email address extracted from the @samp{Sender:@:} field. - -@cindex sc-emailname info field -@cindex emailname info field (sc-) -@item "sc-emailname" -email terminus extracted from the @samp{From:@:} field. - -@cindex sc-initials info field -@cindex initials info field (sc-) -@item "sc-initials" -the author's initials. - -@cindex sc-author info field -@cindex author info field (sc-) -@item "sc-author" -the author's full name. - -@cindex sc-firstname info field -@cindex firstname info field (sc-) -@item "sc-firstname" -the author's first name. - -@cindex sc-lastname info field -@cindex lastname info field (sc-) -@item "sc-lastname" -the author's last name. - -@cindex sc-middlename-1 info field -@cindex middlename-1 info field (sc-) -@item "sc-middlename-1" -the author's first middle name. -@end table - -If the author's name has more than one middle name, they will appear as -info keys with the appropriate index (e.g., @code{"sc-middlename-2"}, -@dots{}). @xref{Selecting an Attribution}.@refill - -@node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top -@cindex reference headers -@chapter Reference Headers - -Supercite will insert an informative @dfn{reference header} at the -beginning of the cited body of text, which display more detail about the -original article and provides the mapping between the attribution and -the original author in non-nested citations. Whereas the citation -string usually only contains a portion of the original author's name, -the reference header can contain such information as the author's full -name, email address, the original article's subject, etc. In fact any -information contained in the info alist can be inserted into a reference -header. - -@menu -* The Built-in Header Rewrite Functions:: -* Electric References:: -@end menu - -@cindex header rewrite functions -@vindex sc-rewrite-header-list -@vindex rewrite-header-list (sc-) -There are a number of built-in @dfn{header rewrite functions} supplied -by Supercite, but you can write your own custom header rewrite functions -(perhaps using the built-in ones as examples). The variable -@code{sc-rewrite-header-list} contains the list of such header rewrite -functions. This list is consulted both when inserting the initial -reference header, and when displaying @dfn{electric references}. -@xref{Electric References}. - -@vindex sc-preferred-header-style -@vindex preferred-header-style (sc-) -When Supercite is initially run on a reply buffer (via -@code{sc-cite-original}), it will automatically call one of these -functions. The one it uses is defined in the variable -@code{sc-preferred-header-style}. The value of this variable is an -integer which is an index into the @code{sc-rewrite-header-list}, -beginning at zero. - -@node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers -@cindex header rewrite functions, built-in -@section The Built-in Header Rewrite Functions - -Below are examples of the various built-in header rewrite functions. -Please note the following:@: first, the text which appears in the -examples below as @var{infokey} indicates that the corresponding value -of the info key from the info alist will be inserted there. -(@pxref{Information Keys and the Info Alist}). For example, in @code{sc-header-on-said} -below, @var{date} and @var{from} correspond to the values of the -@samp{Date:@:} and @samp{From:@:} mail headers respectively.@refill - -@vindex sc-reference-tag-string -@vindex reference-tag-string (sc-) -Also, the string @code{">>>>>"} below is really the value of the -variable @code{sc-reference-tag-string}. This variable is used in all -built-in header rewrite functions, and you can customize its value to -change the tag string globally. - -Finally, the references headers actually written may omit certain parts -of the header if the info key associated with @var{infokey} is not -present in the info alist. In fact, for all built-in headers, if the -@samp{From:@:} field is not present in the mail headers, the entire -reference header will be omitted (but this usually signals a serious -problem either in your MUA or in Supercite's installation). - -@table @code -@findex sc-no-header -@findex no-header (sc-) -@item sc-no-header -This function produces no header. It should be used instead of -@code{nil} to produce a blank header. This header can possibly contain -a blank line after the @code{mail-header-separator} line. - -@item sc-no-blank-line-or-header -@findex sc-no-blank-line-or-header -@findex no-blank-line-or-header (sc-) -This function is similar to @code{sc-no-header} except that any blank -line after the @code{mail-header-separator} line will be removed. - -@item sc-header-on-said -@findex sc-header-on-said -@findex header-on-said (sc-) -@code{>>>>> On @var{date}, @var{from} said:} - -@item sc-header-inarticle-writes -@findex sc-header-inarticle-writes -@findex header-inarticle-writes (sc-) -@code{>>>>> In article @var{message-id}, @var{from} writes:} - -@item sc-header-regarding-adds -@findex sc-header-regarding-adds -@findex header-regarding-adds (sc-) -@code{>>>>> Regarding @var{subject}; @var{from} adds:} - -@item sc-header-attributed-writes -@findex sc-header-attributed-writes -@findex header-attributed-writes (sc-) -@code{>>>>> "@var{sc-attribution}" == @var{sc-author} <@var{sc-reply-address}> writes:} - -@item sc-header-author-writes -@findex sc-header-author-writes -@findex header-author-writes (sc-) -@code{>>>>> @var{sc-author} writes:} - -@item sc-header-verbose -@findex sc-header-verbose -@findex header-verbose (sc-) -@code{>>>>> On @var{date},}@* -@code{>>>>> @var{sc-author}}@* -@code{>>>>> from the organization of @var{organization}}@* -@code{>>>>> who can be reached at:@: @var{sc-reply-address}}@* -@code{>>>>> (whose comments are cited below with:@: "@var{sc-cite}")}@* -@code{>>>>> had this to say in article @var{message-id}}@* -@code{>>>>> in newsgroups @var{newsgroups}}@* -@code{>>>>> concerning the subject of @var{subject}}@* -@code{>>>>> see @var{references} for more details} -@end table - -@node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers -@cindex electric references -@section Electric References - -By default, when Supercite cites the original message for the first -time, it just goes ahead and inserts the reference header indexed by -@code{sc-preferred-header-style}. However, you may want to select -different reference headers based on the type of reply or forwarding you -are doing. You may also want to preview the reference header before -deciding whether to insert it into the reply buffer or not. Supercite -provides an optional @dfn{electric reference} mode which you can drop -into to give you this functionality. - -@vindex sc-electric-references-p -@vindex electric-references-p (sc-) -If the variable @code{sc-electric-references-p} is non-@code{nil}, -Supercite will bring up an electric reference mode buffer and place you -into a recursive edit. The electric reference buffer is read-only, so -you cannot directly modify the reference text until you exit electric -references and insert the text into the reply buffer. But you can cycle -through all the reference header rewrite functions in your -@code{sc-rewrite-header-list}. - -You can also set a new preferred header style, jump to any header, or -jump to the preferred header. The header will be shown in the electric -reference buffer and the header index and function name will appear in -the echo area. - -The following commands are available while in electric reference mode -(shown here with their default key bindings): - -@table @asis -@item @code{sc-eref-next} (@kbd{n}) -@findex sc-eref-next -@findex eref-next (sc-) -@kindex n -@vindex sc-electric-circular-p -@vindex electric-circular-p (sc-) -Displays the next reference header in the electric reference buffer. If -the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking -@code{sc-eref-next} while viewing the last reference header in the list -will wrap around to the first header.@refill - -@item @code{sc-eref-prev} (@kbd{p}) -@findex sc-eref-prev -@findex eref-prev (sc-) -@kindex p -Displays the previous reference header in the electric reference buffer. -If the variable @code{sc-electric-circular-p} is non-@code{nil}, -invoking @code{sc-eref-prev} will wrap around to the last header.@refill - -@item @code{sc-eref-goto} (@kbd{g}) -@findex sc-eref-goto -@findex eref-goto (sc-) -@kindex g -Goes to a specified reference header. The index (into the -@code{sc-rewrite-header-list}) can be specified as a numeric argument to -the command. Otherwise, Supercite will query you for the index in the -minibuffer.@refill - -@item @code{sc-eref-jump} (@kbd{j}) -@findex sc-eref-jump -@findex eref-jump (sc-) -@kindex j -Display the preferred reference header, i.e., the one indexed by the current -value of @code{sc-preferred-header-style}. - -@item @code{sc-eref-setn} (@kbd{s}) -@findex sc-eref-setn -@findex eref-setn (sc-) -@kindex s -Set the preferred reference header (i.e., -@code{sc-preferred-header-style}) to the currently displayed header.@refill - -@item @code{sc-eref-exit} (@kbd{C-j}, @key{RET}, and @key{ESC C-c}) -@kindex RET -@kindex C-j -@kindex q -@findex sc-eref-exit -@findex eref-exit (sc-) -Exit from electric reference mode and insert the current header into the -reply buffer.@refill - -@item @code{sc-eref-abort} (@kbd{q}, @kbd{x}) -@findex sc-eref-abort -@findex eref-abort (sc-) -@kindex x -Exit from electric reference mode without inserting the current header. -@end table - -@vindex sc-electric-mode-hook -@vindex electric-mode-hook (sc-) -@noindent -Supercite will execute the hook @code{sc-electric-mode-hook} before -entering electric reference mode. - -@node Getting Connected, Replying and Yanking, Recognizing Citations, Top -@cindex citation interface specification -@chapter Getting Connected - - -@vindex mail-citation-hook -@cindex .emacs file -In most cases, all that is necessary to begin using Supercite is to add -the following to @file{~.emacs}: - -@example -(add-hook 'mail-citation-hook 'sc-cite-original) -@end example - -@noindent For more details of the process, read on@dots{} - -Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the -original message into the reply buffer. In reality, the citation of the -original message is performed via a call through a configurable hook -variable. The name of this variable has been agreed to in advance as -part of the @dfn{citation interface specification}. By default this -hook variable has a @code{nil} value, which the MUA recognizes to mean, -``use your default citation function.'' When you add Supercite's -citation function to the hook, thereby giving the variable a -non-@code{nil} value, it tells the MUA to run the hook via -@code{run-hooks} instead of using the default citation.@refill - -Early in Supercite's development, the Supercite author, a few MUA -authors, and some early Supercite users got together and agreed upon a -standard interface between MUAs and citation packages (of which -Supercite is currently the only known add-on @t{:-)}. Supercite can -probably be used with most Emacs MUAs, with a greater or lesser degree -of effort. - -To learn exactly how to connect Supercite to the software systems you -are using, read the appropriate following sections. For details on the -interface specifications, or if you are writing or maintaining an MUA, -@pxref{Hints to MUA Authors}. - -@cindex autoload -@cindex .emacs file -@findex sc-cite-original -@findex cite-original (sc-) -The first thing that everyone should do, regardless of the MUA you are -using is to set up Emacs so it will load Supercite at the appropriate -time. This happens automatically if Supercite is distributed with your -Emacs version. If not, you can set up an @dfn{autoload} for Supercite. - -To do the latter, put the following in your @file{.emacs} file: - -@example -(autoload 'sc-cite-original "supercite" nil t) -@end example - -@cindex point -@cindex mark -The function @code{sc-cite-original} is the top-level Supercite function -designed to be run from the citation hook. It expects -@samp{point} and @samp{mark} to be set around the region to cite, and it -expects the original article's mail headers to be present within this -region. Note that Supercite @emph{never} touches any text outside this -region. Note further that the region need not be active -for @code{sc-cite-original} to do its job. -@xref{Hints to MUA Authors}.@refill - -The other step in the getting connected process is to make sure your -MUA calls @code{sc-cite-original} at the right time. As mentioned -above, some MUAs handle this differently. Read the sections that follow -pertaining to the MUAs you are using. - -@vindex sc-load-hook -@vindex load-hook (sc-) -@vindex sc-pre-hook -@vindex pre-hook (sc-) -One final note. After Supercite is loaded into your Emacs session, it -runs the hook @code{sc-load-hook}. You can put any customizations into -this hook since it is only run once. This will not work, however, if -your Emacs maintainer has put Supercite into your dumped Emacs image. -In that case, you can use the @code{sc-pre-hook} variable, but this will -get executed every time @code{sc-cite-original} is called. @xref{Reply -Buffer Initialization}.@refill - -@node Replying and Yanking, Reply Buffer Initialization, Getting Connected, Top -@chapter Replying and Yanking - -This chapter explains what happens when you reply and yank an original -message from an MUA. - -@menu -* Reply Buffer Initialization:: -* Filling Cited Text:: -@end menu - -@node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking -@findex sc-cite-original -@findex cite-original (sc-) -@section Reply Buffer Initialization - -Executing @code{sc-cite-original} performs the following steps as it -initializes the reply buffer: - -@enumerate -@item -@vindex sc-pre-hook -@vindex pre-hook (sc-) -@emph{Runs @code{sc-pre-hook}.} -This hook variable is run before @code{sc-cite-original} does any other -work. You could conceivably use this hook to set certain Supercite -variables based on the reply buffer's mode or name (i.e., to do -something different based on whether you are replying or following up to -an article).@refill - -@item -@emph{Inserts Supercite's keymap.} -@vindex sc-mode-map-prefix -@vindex mode-map-prefix (sc-) -@kindex C-c C-p -@cindex keymap prefix -Supercite provides a number of commands for performing post-yank -modifications to the reply buffer. These commands are installed on -Supercite's top-level keymap. Since Supercite has to interface with a -wide variety of MUAs, it does not install all of its commands directly -into the reply buffer's keymap. Instead, it puts its commands on a -keymap prefix, then installs this prefix onto the buffer's keymap. What -this means is that you typically have to type more characters to invoke -a Supercite command, but Supercite's key bindings can be made much more -consistent across MUAs. - -You can control what key Supercite uses as its keymap prefix by changing -the variable @code{sc-mode-map-prefix}. By default, this variable is -set to @code{C-c C-p}; a finger twister perhaps, but unfortunately the -best default due to the scarcity of available key bindings in many MUAs. - -@item -@emph{Turns on Supercite minor mode.} -@cindex modeline -The modeline of the reply buffer should indicate that Supercite is -active in that buffer by displaying the string @samp{SC}. - -@item -@emph{Sets the ``Undo Boundary.''} -@cindex undo boundary -Supercite sets an undo boundary before it begins to modify the original -yanked text. This allows you to easily undo Supercite's changes to -affect alternative citing styles. - -@item -@emph{Processes the mail headers.} -@vindex sc-confirm-always-p -@vindex confirm-always-p (sc-) -@vindex sc-mail-warn-if-non-rfc822-p -@vindex mail-warn-if-non-rfc822-p (sc-) -All previously retrieved info key-value pairs are deleted from the info -alist, then the mail headers in the body of the yanked message are -scanned. Info key-value pairs are created for each header found. Also, -such useful information as the author's name and email address are -extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is -non-@code{nil}, then Supercite will warn you if it finds a mail header -that does not conform to RFC822. This is rare and indicates a problem -either with your MUA or the original author's MUA, or some MTA (mail -transport agent) along the way. - -@vindex sc-nuke-mail-headers -@vindex sc-nuke-mail-header-list -@vindex nuke-mail-headers (sc-) -@vindex nuke-mail-header-list (sc-) -Once the info keys have been extracted from the mail headers, the -headers are nuked from the reply buffer. You can control exactly which -headers are removed or kept, but by default, all headers are removed. - -There are two variables which control mail header nuking. The variable -@code{sc-nuke-mail-headers} controls the overall behavior of the header -nuking routines. By setting this variable to @code{'all}, you -automatically nuke all mail headers. Likewise, setting this variable to -@code{'none} inhibits nuking of any mail headers. In between these -extremes, you can tell Supercite to nuke only a specified list of mail -headers by setting this variable to @code{'specified}, or to keep only a -specified list of headers by setting it to @code{'keep}. - -If @code{sc-nuke-mail-headers} is set to @code{'specified} or -@code{'keep}, then the variable @code{sc-nuke-mail-header-list} is -consulted for the list of headers to nuke or keep. This variable -contains a list of regular expressions. If the mail header line matches -a regular expression in this list, the header will be nuked or kept. -The line is matched against the regexp using @code{looking-at} rooted at -the beginning of the line. - -@vindex sc-blank-lines-after-headers -@vindex blank-lines-after-headers (sc-) -If the variable @code{sc-blank-lines-after-headers} is non-@code{nil}, -it contains the number of blank lines remaining in the buffer after mail -headers are nuked. By default, only one blank line is left in the buffer. - -@item -@emph{Selects the attribution and citation strings.} -Once the mail headers have been processed, Supercite selects a -attribution string and a citation string which it will use to cite the -original message. @xref{Selecting an Attribution}, for details. - -@item -@emph{Cites the message body.} -@vindex sc-cite-region-limit -@vindex cite-region-limit (sc-)b -After the selection of the attribution and citation strings, Supercite -cites the original message by inserting the citation string prefix in -front of every uncited line. You may not want Supercite to -automatically cite very long messages however. For example, some email -could contain a smaller header section followed by a huge uuencoded -message. It wouldn't make sense to cite the uuencoded message part when -responding to the original author's short preface. For this reason, -Supercite provides a variable which limits the automatic citation of -long messages to a certain maximum number of lines. The variable is -called @code{sc-cite-region-limit}. If this variable contains an -integer, messages with more lines that this will not be cited at all, -and a warning message will be displayed. Supercite has performed -everything necessary, though, for you to manually cite only the small -portion of the original message that you want to use. - -If @code{sc-cite-region-limit} contains a non-@code{nil} value, the -original message will always be cited, regardless of its size. If the -variable contains the value @code{nil}, the region will never be cited -automatically. Use this if you always want to be able to edit and cite -the message manually. - -@vindex sc-cite-blank-lines-p -@vindex cite-blank-lines-p (sc-) -The variable @code{sc-cite-blank-lines-p} controls whether blank lines -in the original message should be cited or not. If this variable is -non-@code{nil}, blank lines will be cited just like non-blank lines. -Otherwise, blank lines will be treated as paragraph separators. - -Citing of the original message is highly configurable. Supercite's -default setup does a pretty good job of citing many common forms of -previously cited messages. But there are as many citation styles out -there as people on the net, or just about! It would be impossible for -Supercite to anticipate every style in existence, and you probably -wouldn't encounter them all anyway. But you can configure Supercite to -recognize those styles you see often. -@xref{Configuring the Citation Engine}, for details.@refill - -@item -@emph{Runs @code{sc-post-hook}.} -@vindex sc-post-hook -@vindex post-hook (sc-) -This variable is very similar to @code{sc-pre-hook}, except that it runs -after @code{sc-cite-original} is finished. This hook is provided mostly -for completeness and backward compatibility. Perhaps it could be used to -reset certain variables set in @code{sc-pre-hook}.@refill -@end enumerate - -@node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking -@cindex filling paragraphs -@vindex sc-auto-fill-region-p -@vindex auto-fill-region-p (sc-) -@cindex filladapt -@cindex gin-mode -@findex sc-setup-filladapt -@findex setup-filladapt (sc-) -@vindex sc-load-hook -@vindex load-hook (sc-) -@section Filling Cited Text - -Supercite will automatically fill newly cited text from the original -message unless the variable @code{sc-auto-fill-region-p} has a -@code{nil} value. Supercite will also re-fill paragraphs when you -manually cite or re-cite text. - -However, during normal editing, Supercite itself cannot be used to fill -paragraphs. This is a change from version 2. There are other add-on -lisp packages which do filling much better than Supercite ever did. The -two best known are @dfn{filladapt} and @dfn{gin-mode}. Both work well -with Supercite and both are available at the normal Emacs Lisp archive -sites. @dfn{gin-mode} works pretty well out of the box, but if you use -@dfn{filladapt}, you may want to run the function -@code{sc-setup-filladapt} from your @code{sc-load-hook}. This simply -makes @dfn{filladapt} a little more Supercite savvy than its default -setup. - -@vindex sc-fixup-whitespace-p -@vindex fixup-whitespace-p (sc-) -Also, Supercite will collapse leading whitespace between the citation -string and the text on a line when the variable -@code{sc-fixup-whitespace-p} is non-@code{nil}. The default value for -this variable is @code{nil}.@refill - -@vindex fill-prefix -Its important to understand that Supercite's automatic filling (during -the initial citation of the reply) is very fragile. That is because -figuring out the @code{fill-prefix} for a particular paragraph is a -really hard thing to do automatically. This is especially the case when -the original message contains code or some other text where leading -whitespace is important to preserve. For this reason, many Supercite -users typically run with @code{sc-auto-fill-region-p} (and possibly also -@code{sc-fixup-whitespace-p}) set to @code{nil}. They then manually -fill each cited paragraph in the reply buffer. - -I usually run with both these variables containing their default values. -When Supercite's automatic filling breaks on a particular message, I -will use Emacs's undo feature to undo back before the citation was -applied to the original message. Then I'll toggle the variables and -manually cite those paragraphs that I don't want to fill or collapse -whitespace on. @xref{Variable Toggling Shortcuts}.@refill - -@kindex C-c C-p C-p -If you find that Supercite's automatic filling is just too fragile for -your tastes, you might consider one of these alternate approaches. -Also, to make life easier, a shortcut function to toggle the state of -both of these variables is provided on the key binding -@kbd{C-c C-p C-p} (with the default value of @code{sc-mode-map-prefix}; -@pxref{Post-yank Formatting Commands}).@refill - -You will noticed that the minor mode string will -show the state of these variables as qualifier characters. When both -variables are @code{nil}, the Supercite minor mode string will display -@samp{SC}. When just @code{sc-auto-fill-region-p} is non-@code{nil}, the -string will display @samp{SC:f}, and when just -@code{sc-fixup-whitespace-p} is non-@code{nil}, the string will display -@samp{SC:w}. When both variables are non-@code{nil}, the string will -display @samp{SC:fw}. Note that the qualifiers chosen are mnemonics for -the default bindings of the toggling function for each respective -variable. -@xref{Variable Toggling Shortcuts}.@refill - -Why are these variables not set to @code{nil} by default? It is because -many users won't manually fill paragraphs that are Supercited, and there -have been widespread complaints on the net about mail and news messages -containing lines greater than about 72 characters. So the default is to -fill cited text. - -@node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top -@cindex attribution list -@vindex sc-preferred-attribution-list -@vindex preferred-attribution-list (sc-) -@chapter Selecting an Attribution - -As you know, the attribution string is the part of the author's name -that will be used to composed a non-nested citation string. Supercite -scans the various mail headers present in the original article and uses -a number of heuristics to extract strings which it puts into the -@dfn{attribution association list} or @dfn{attribution alist}. This is -analogous, but different than, the info alist previously mentioned. Each -element in the attribution alist is a key-value pair containing such -information as the author's first name, middle names, and last name, the -author's initials, and the author's email terminus. - -@menu -* Attribution Preferences:: -* Anonymous Attributions:: -* Author Names:: -@end menu - -@node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution -@section Attribution Preferences - -When you cite an original message, you can tell Supercite which part of -the author's name you would prefer it to use as the attribution. The -variable @code{sc-preferred-attribution-list} controls this; it contains -keys which are matched against the attribution alist in the given order. -The first value of a key that produces a non-@code{nil}, non-empty -string match is used as the attribution string, and if no keys match, a -secondary mechanism is used to generate the attribution. -@xref{Anonymous Attributions}. - -The following preferences are always available in the attribution alist -(barring error): - -@table @code -@item "emailname" -the author's email terminus. - -@item "initials" -the author's initials. - -@item "firstname" -the author's first name. - -@item "lastname" -the author's last name. - -@item "middlename-1" -the author's first middle name. - -@item "sc-lastchoice" -the last attribution string you have selected. This is useful when you -recite paragraphs in the reply.@refill - -@item "sc-consult" -@vindex sc-attrib-selection-list -@vindex attrib-selection-list (sc-) -consults the customizable list @code{sc-attrib-selection-list} which can -be used to select special attributions based on the value of any info -key. See below for details. - -@item "x-attribution" -the original author's suggestion for attribution string choice. See below -for details.@refill -@end table - -Middle name indexes can be any positive integer greater than zero, -though it is unlikely that many authors will have more than one middle -name, if that many. - -At this point, let me digress into a discussion of etiquette. It is my -belief that while the style of the citations is a reflection of the -personal tastes of the replier (i.e., you), the attribution selection is -ultimately the personal choice of the original author. In a sense it is -his or her ``net nickname'', and therefore the author should have some -say in the selection of attribution string. Imagine how you would feel -if someone gave you a nickname that you didn't like? - -For this reason, Supercite recognizes a special mail header, -@samp{X-Attribution:}, which if present, tells Supercite the attribution -string preferred by the original author. It is the value of this header -that is associated with the @code{"x-attribution"} key in the -attribution alist. Currently, you can override the preference of this -key by changing @code{sc-preferred-attribution-list}, but that isn't -polite, and in the future Supercite may hard-code this. For now, it is -suggested that if you change the order of the keys in this list, that -@code{"x-attribution"} always be first, or possible second behind only -@code{"sc-lastchoice"}. This latter is the default. - -@vindex sc-attrib-selection-list -@vindex attrib-selection-list (sc-) -The value @code{"sc-consult"} in @code{sc-preferred-attribution-list} -has a special meaning during attribution selection. When Supercite -encounters this preference, it begins processing a customizable list of -attributions, contained in the variable @code{sc-attrib-selection-list}. -Each element in this list contains lists of the following form: - -@example -@group -(@var{infokey} ((@var{regexp} @. @var{attribution}) - (@var{regexp} @. @var{attribution}) - (@dots{}))) -@end group -@end example - -@noindent -@findex sc-mail-field -@findex mail-field (sc-) -where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp} -is a regular expression to match against the @var{infokey}'s value. If -@var{regexp} matches the @var{infokey}'s value, the @var{attribution} is -used as the attribution string. Actually, @var{attribution} can be a -string or a list; if it is a list, it is @code{eval}uated and the return -value (which must be a string), is used as the attribution. - -This can be very useful for when you are replying to net acquaintances -who do not use the @samp{X-Attribution:@:} mail header. You may know -what nickname they would prefer to use, and you can set up this list to -match against a specific mail field, e.g., @samp{From:@:}, allowing you -to cite your friend's message with the appropriate attribution. - -@node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution -@vindex sc-default-author-name -@vindex default-author-name (sc-) -@vindex sc-default-attribution -@vindex default-attribution (sc-) -@section Anonymous Attributions - -When the author's name cannot be found in the @samp{From:@:} mail -header, a fallback author name and attribution string must be supplied. -The fallback author name is contained in the variable -@code{sc-default-author-name} and the fallback attribution string is -contained in the variable @code{sc-default-attribution}. Default values -for these variables are @code{"Anonymous"} and @code{"Anon"}, -respectively. Note that in most circumstances, getting the default -author name or attribution is a sign that something is set up -incorrectly. - -@vindex sc-use-only-preference-p -@vindex use-only-preference-p (sc-) -Also, if the preferred attribution, which you specified in your -@code{sc-preferred-attribution-list} variable cannot be found, a -secondary method can be employed to find a valid attribution string. The -variable @code{sc-use-only-preference-p} controls what happens in this -case. If the variable's value is non-@code{nil}, then -@code{sc-default-author-name} and @code{sc-default-attribution} are -used, otherwise, the following steps are taken to find a valid -attribution string, and the first step to return a non-@code{nil}, -non-empty string becomes the attribution:@refill - -@enumerate -@item -Use the last selected attribution, if there is one. - -@item -Use the value of the @code{"x-attribution"} key. - -@item -Use the author's first name. - -@item -Use the author's last name. - -@item -Use the author's initials. - -@item -Find the first non-@code{nil}, non-empty attribution string in the -attribution alist. - -@item -@code{sc-default-attribution} is used. -@end enumerate - -@vindex sc-confirm-always-p -@vindex confirm-always-p (sc-) -Once the attribution string has been automatically selected, a number of -things can happen. If the variable @code{sc-confirm-always-p} is -non-@code{nil}, you are queried for confirmation of the chosen -attribution string. The possible values for completion are those strings -in the attribution alist, however you are not limited to these choices. -You can type any arbitrary string at the confirmation prompt. The string -you enter becomes the value associated with the @code{"sc-lastchoice"} -key in the attribution alist. - -@vindex sc-downcase-p -@vindex downcase-p (sc-) -Once an attribution string has been selected, Supercite will force the -string to lower case if the variable @code{sc-downcase-p} is -non-@code{nil}. - -@vindex sc-attribs-preselect-hook -@vindex attribs-preselect-hook (sc-) -@vindex sc-attribs-postselect-hook -@vindex attribs-postselect-hook (sc-) - -Two hook variables provide even greater control of the attribution -selection process. The hook @code{sc-attribs-preselect-hook} is run -before any attribution is selected. Likewise, the hook -@code{sc-attribs-postselect-hook} is run after the attribution is -selected (and the corresponding citation string is built), but before -these values are committed for use by Supercite. During the -post-selection hook, the local variables @code{attribution} and -@code{citation} are bound to the appropriate strings. By changing these -variables in your hook functions, you change the attribution and -citation strings used by Supercite. One possible use of this would be -to override any automatically derived attribution string when it is only -one character long; e.g. you prefer to use @code{"initials"} but the -author only has one name.@refill - -@node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution -@cindex author names -@section Author Names - -Supercite employs a number of heuristics to decipher the author's name -based on value of the @samp{From:@:} mail field of the original message. -Supercite can recognize almost all of the common @samp{From:@:} field -formats in use. If you encounter a @samp{From:@:} field that Supercite -cannot parse, please report this bug using @kbd{M-x report-emacs-bug}. - -@vindex sc-titlecue-regexp -@vindex titlecue-regexp (sc-) -There are a number of Supercite variables that control how author names -are extracted from the @samp{From:@:} header. Some headers may contain a -descriptive title as in: - -@example -From:@: computer!speedy!doe (John Xavier-Doe -- Decent Hacker) -@end example - -Supercite knows which part of the @samp{From:@:} header is email address -and which part is author name, but in this case the string @code{"Decent -Hacker"} is not part of the author's name. You can tell Supercite to -ignore the title, while still recognizing hyphenated names through the -use of a regular expression in the variable @code{sc-titlecue-regexp}. -This variable has the default value of @code{"\\\\s +-+\\\\s +"}. Any -text after this regexp is encountered is ignored as noise. - -@vindex sc-name-filter-alist -@vindex name-filter-alist (sc-) -Some @samp{From:@:} headers may contain extra titles in the name fields -not separated by a title cue, but which are nonetheless not part of the -author's name proper. Examples include the titles ``Dr.'', ``Mr.'', -``Ms.'', ``Jr.'', ``Sr.'', and ``III'' (e.g., Thurston Howe, the Third). -Also, some companies prepend or append the name of the division, -organization, or project on the author's name. All of these titles are -noise which should be ignored. The variable @code{sc-name-filter-alist} -is used for this purpose. As implied by its name, this variable is an -association list, where each element is a cons cell of the form: - -@example -(@var{regexp} @. @var{position}) -@end example - -@noindent -where @var{regexp} is a regular expression that is matched (using -@code{string-match}) against each element of the @samp{From:@:} field's -author name. @var{position} is a position indicator, starting at zero. -Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name, -@code{sc-name-filter-alist} would have an entry such as: - -@example -("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0) -@end example - -@noindent -which only removes them if they appear as the first word in the name. -The position indicator is an integer, or one of the two special symbols -@code{last} or @code{any}. @code{last} always matches against the last -word in the name field, while @code{any} matches against every word in -the name field. - -@node Configuring the Citation Engine, Using Regi, Author Names, Top -@cindex Regi -@cindex frames (Regi) -@cindex entries (Regi) -@chapter Configuring the Citation Engine - -At the heart of Supercite is a regular expression interpreting engine -called @dfn{Regi}. Regi operates by interpreting a data structure -called a Regi-frame (or just @dfn{frame}), which is a list of -Regi-entries (or just @dfn{entry}). Each entry contains a predicate, -typically a regular expression, which is matched against a line of text -in the current buffer. If the predicate matches true, an associated -expression is @code{eval}uated. In this way, an entire region of text -can be transformed in an @emph{awk}-like manner. Regi is used -throughout Supercite, from mail header information extraction, to header -nuking, to citing text. - -@menu -* Using Regi:: -* Frames You Can Customize:: -@end menu - -While the details of Regi are discussed below (@pxref{Using Regi}), only -those who wish to customize certain aspects of Supercite need concern -themselves with it. It is important to understand though, that any -conceivable citation style that can be described by a regular expression -can be recognized by Supercite. This leads to some interesting -applications. For example, if you regularly receive email from a -co-worker that uses an uncommon citation style (say one that employs a -@samp{|} or @samp{@}} character at the front of the line), it is -possible for Supercite to recognize this and @emph{coerce} the citation -to your preferred style, for consistency. In theory, it is possible for -Supercite to recognize such things as uuencoded messages or C code and -cite or fill those differently than normal text. None of this is -currently part of Supercite, but contributions are welcome! - -@node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine -@findex regi-interpret -@findex eval -@findex looking-at -@section Using Regi - -Regi works by interpreting frames with the function -@code{regi-interpret}. A frame is a list of arbitrary size where each -element is a entry of the following form: - -@example -(@var{pred} @var{func} [@var{negate-p} [@var{case-fold-search}]]) -@end example - -Regi starts with the first entry in a frame, evaluating the @var{pred} -of that entry against the beginning of the line that @samp{point} is on. -If the @var{pred} evaluates to true (or false if the optional -@var{negate-p} is non-@code{nil}), then the @var{func} for that entry is -@code{eval}uated. How processing continues is determined by the return -value for @var{func}, and is described below. If @var{pred} was false -the next entry in the frame is checked until all entries have been -matched against the current line. If no entry matches, @samp{point} is -moved forward one line and the frame is reset to the first entry. - -@var{pred} can be a string, a variable, a list or one of the following -symbols: @code{t}, @code{begin}, @code{end}, or @code{every}. If -@var{pred} is a string, or a variable or list that @code{eval}uates to a -string, it is interpreted as a regular expression. This regexp is -matched against the current line, from the beginning, using -@code{looking-at}. This match folds case if the optional -@var{case-fold-search} is non-@code{nil}. If @var{pred} is not a -string, or does not @code{eval}uate to a string, it is interpreted as a -binary value (@code{nil} or non-@code{nil}).@refill - -The four special symbol values for @var{pred} are recognized: - -@table @code -@item t -Always produces a true outcome. -@item begin -Always executed before the frame is interpreted. This can be used to -initialize some global variables for example. -@item end -Always executed after frame interpreting is completed. This can be used -to perform any necessary post-processing. -@item every -Executes whenever the frame is reset, usually after the entire frame has -been matched against the current line. -@end table - -Note that @var{negate-p} and @var{case-fold-search} are ignored if -@var{pred} is one of these special symbols. Only the first occurrence of -each symbol in a frame is used; any duplicates are ignored. Also -note that for performance reasons, the entries associated with these -symbols are removed from the frame during the main interpreting loop. - -Your @var{func} can return certain values which control continued Regi -processing. By default, if your @var{func} returns @code{nil} (as it -should be careful to do explicitly), Regi will reset the frame to the -first entry, and advance @samp{point} to the beginning of the next line. -If a list is returned from your function, it can contain any combination -of the following elements:@refill - -@table @asis -@item the symbol @code{continue} -This tells Regi to continue processing entries after a match, instead of -resetting the frame and moving @samp{point}. In this way, lines of text -can have multiple matches, but you have to be careful to avoid entering -infinite loops. - -@item the symbol @code{abort} -This tells Regi to terminate frame processing. However, any @code{end} -entry is still processed. - -@item the list @code{(frame . @var{newframe})} -This tells Regi to substitute @var{newframe} as the frame it is -interpreting. In other words, your @var{func} can modify the Regi frame -on the fly. @var{newframe} can be a variable containing a frame, or it -can be the frame in-lined.@refill - -@item the list @code{(step . @var{step})} -Tells Regi to move @var{step} number of lines forward as it continues -processing. By default, Regi moves forward one line. @var{step} can be -zero or negative of course, but watch out for infinite loops.@refill -@end table - -During execution of your @var{func}, the following variables will be -temporarily bound to some useful information:@refill - -@table @code -@item curline -The current line in the buffer that Regi is @code{looking-at}, as a string. -@item curframe -The current frame being interpreted. -@item curentry -The current frame entry being interpreted. -@end table - -@node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine -@vindex sc-nuke-mail-header -@section Frames You Can Customize - -As mentioned earlier, Supercite uses various frames to perform -certain jobs such as mail header information extraction and mail header -nuking. However, these frames are not available for you to customize, -except through abstract interfaces such as @code{sc-nuke-mail-header}, -et al. - -@vindex sc-default-cite-frame -However, the citation frames Supercite uses provide a lot of customizing -power and are thus available to you to change to suit your needs. The -workhorse of citation is the frame contained in the variable -@code{sc-default-cite-frame}. This frame recognizes many situations, -such as blank lines, which it interprets as paragraph separators. It -also recognizes previously cited nested and non-nested citations in the -original message. By default it will coerce non-nested citations into -your preferred citation style, and it will add a level of citation to -nested citations. It will also simply cite uncited lines in your -preferred style. - -@cindex unciting -@cindex reciting -@vindex sc-default-uncite-frame -@vindex sc-default-recite-frame -In a similar vein, there are default frames for @dfn{unciting} and -@dfn{reciting}, contained in the variables -@code{sc-default-uncite-frame} and @code{sc-default-recite-frame} -respectively.@refill - -As mentioned earlier (@pxref{Recognizing Citations}), citations are -recognized through the values of the regular expressions -@code{sc-citation-root-regexp}, et al. To recognize odd styles, you -could modify these variables, or you could modify the default citing -frame. Alternatively, you could set up association lists of frames for -recognizing specific alternative forms. - -@vindex sc-cite-frame-alist -@vindex sc-uncite-frame-alist -@vindex sc-recite-frame-alist -For each of the actions -- citing, unciting, and reciting -- an alist is -consulted to find the frame to use (@code{sc-cite-frame-alist}, -@code{sc-uncite-frame-alist}, and @code{sc-recite-frame-alist} -respectively). These frames can contain alists of the form: - -@example -((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{}) - (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{}) - (@dots{})) -@end example - -@vindex sc-mail-field -@findex string-match -Where @var{infokey} is a key suitable for @code{sc-mail-field}, -@var{regexp} is a regular expression which is @code{string-match}'d -against the value of the @code{sc-mail-field} key, and @var{frame} is -the frame to use if a match occurred. @var{frame} can be a variable -containing a frame or a frame in-lined.@refill - -When Supercite is about to cite, uncite, or recite a region, it consults -the appropriate alist and attempts to find a frame to use. If one -is not found from the alist, then the appropriate default frame is used. - -@node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top -@vindex sc-mode-map-prefix -@vindex mode-map-prefix (sc-) -@kindex C-c C-p -@chapter Post-yank Formatting Commands - -Once the original message has been yanked into the reply buffer, and -@code{sc-cite-original} has had a chance to do its thing, a number of -useful Supercite commands will be available to you. Since there is wide -variety in the keymaps that MUAs set up in their reply buffers, it is -next to impossible for Supercite to properly sprinkle its commands into -the existing keymap. For this reason Supercite places its commands on a -separate keymap, putting this keymap onto a prefix key in the reply -buffer. You can customize the prefix key Supercite uses by changing the -variable @code{sc-mode-map-prefix}. By default, the -@code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice, -but unfortunately the best general solution so far. In the rest of this -chapter, we'll assume you've installed Supercite's keymap on the default -prefix.@refill - -@menu -* Citing Commands:: -* Insertion Commands:: -* Variable Toggling Shortcuts:: -* Mail Field Commands:: -* Miscellaneous Commands:: -@end menu - -@node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands -@vindex sc-cite-region-limit -@section Commands to Manually Cite, Recite, and Uncite - -Probably the three most common post-yank formatting operations that you -will perform will be the manual citing, reciting, and unciting of -regions of text in the reply buffer. Often you may want to recite a -paragraph to use a nickname, or manually cite a message when setting -@code{sc-cite-region-limit} to @code{nil}. The following commands -perform these functions on the region of text between @samp{point} and -@samp{mark}. Each of them sets the @dfn{undo boundary} before modifying -the region so that the command can be undone in the standard Emacs -way.@refill - -Here is the list of Supercite citing commands: - -@table @asis -@findex sc-cite-region -@findex cite-region (sc-) -@kindex C-c C-p c -@vindex sc-pre-cite-hook -@vindex pre-cite-hook (sc-) -@vindex sc-confirm-always-p -@vindex confirm-always-p -@kindex C-u -@item @code{sc-cite-region} (@kbd{C-c C-p c}) -This command cites each line in the region of text by interpreting the -selected frame from @code{sc-cite-frame-alist}, or the default citing -frame @code{sc-default-cite-frame}. It runs the hook -@code{sc-pre-cite-hook} before interpreting the frame. With an optional -universal argument (@kbd{C-u}), it temporarily sets -@code{sc-confirm-always-p} to @code{t} so you can confirm the -attribution string for a single manual citing. -@xref{Configuring the Citation Engine}.@refill - -@findex sc-uncite-region -@findex uncite-region (sc-) -@kindex C-c C-p u -@item @code{sc-uncite-region} (@kbd{C-c C-p u}) -This command removes any citation strings from the beginning of each -cited line in the region by interpreting the selected frame from -@code{sc-uncite-frame-alist}, or the default unciting frame -@code{sc-default-uncite-frame}. It runs the hook -@code{sc-pre-uncite-hook} before interpreting the frame. -@xref{Configuring the Citation Engine}.@refill - -@findex sc-recite-region -@findex recite-region (sc-) -@kindex C-c C-p r -@item @code{sc-recite-region} (@kbd{C-c C-p r}) -This command recites each line the region by interpreting the selected -frame from @code{sc-recite-frame-alist}, or the default reciting frame -@code{sc-default-recite-frame}. It runs the hook -@code{sc-pre-recite-hook} before interpreting the frame. -@xref{Configuring the Citation Engine}.@refill - -@vindex sc-confirm-always-p -@vindex confirm-always-p (sc-) -Supercite will always ask you to confirm the attribution when reciting a -region, regardless of the value of @code{sc-confirm-always-p}. -@end table - -@node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands -@section Insertion Commands - -These two functions insert various strings into the reply buffer. - -@table @asis -@findex sc-insert-reference -@findex insert-reference (sc-) -@kindex C-c C-p w -@item @code{sc-insert-reference} (@kbd{C-c C-p w}) -@vindex sc-preferred-header-style -@vindex preferred-header-style (sc-) -Inserts a reference header into the reply buffer at @samp{point}. With -no arguments, the header indexed by @code{sc-preferred-header-style} is -inserted. An optional numeric argument is the index into -@code{sc-rewrite-header-list} indicating which reference header to -write.@refill - -With just the universal argument (@kbd{C-u}), electric reference mode is -entered, regardless of the value of @code{sc-electric-references-p}. - -@findex sc-insert-citation -@findex insert-citation (sc-) -@kindex C-c C-p i -@item @code{sc-insert-citation} (@kbd{C-c C-p i}) -Inserts the current citation string at the beginning of the line that -@samp{point} is on. If the line is already cited, Supercite will issue -an error and will not cite the line. -@end table - -@node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands -@cindex toggling variables -@section Variable Toggling Shortcuts - -Supercite defines a number of commands that make it easier for you to -toggle and set various Supercite variables as you are editing the reply -buffer. For example, you may want to turn off filling or whitespace -cleanup, but only temporarily. These toggling shortcut commands make -this easy to do. - -@kindex C-c C-p C-t -Like Supercite commands in general, the toggling commands are placed on -a keymap prefix within the greater Supercite keymap. For the default -value of @code{sc-mode-map-prefix}, this will be -@kbd{C-c C-p C-t}.@refill - -The following commands toggle the value of certain Supercite variables -which take only a binary value: - -@table @kbd -@item C-c C-p C-t b -Toggles the variable @code{sc-mail-nuke-blank-lines-p}. - -@item C-c C-p C-t c -Toggles the variable @code{sc-confirm-always-p}. - -@item C-c C-p C-t d -Toggles the variable @code{sc-downcase-p}. - -@item C-c C-p C-t e -Toggles the variable @code{sc-electric-references-p}. - -@item C-c C-p C-t f -Toggles the variable @code{sc-auto-fill-region-p}. - -@item C-c C-p C-t o -Toggles the variable @code{sc-electric-circular-p}. - -@item C-c C-p C-t s -Toggles the variable @code{sc-nested-citation-p}. - -@item C-c C-p C-t u -Toggles the variable @code{sc-use-only-preferences-p}. - -@item C-c C-p C-t w -Toggles the variable @code{sc-fixup-whitespace-p}. -@end table - -@findex set-variable -The following commands let you set the value of multi-value variables, -in the same way that Emacs's @code{set-variable} does: - -@table @kbd -@item C-c C-p C-t a -Sets the value of the variable @code{sc-preferred-attribution-list}. - -@item C-c C-p C-t l -Sets the value of the variable @code{sc-cite-region-limit}. - -@item C-c C-p C-t n -Sets the value of the variable @code{sc-mail-nuke-mail-headers}. - -@item C-c C-p C-t N -Sets the value of the variable @code{sc-mail-header-nuke-list}. - -@item C-c C-p C-t p -Sets the value of the variable @code{sc-preferred-header-style}. -@end table - -@kindex C-c C-p C-p -One special command is provided to toggle both -@code{sc-auto-fill-region-p} and @code{sc-fixup-whitespace-p} together. -This is because you typically want to run Supercite with either variable -as @code{nil} or non-@code{nil}. The command to toggle these variables -together is bound on @kbd{C-c C-p C-p}.@refill - -Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?}) -brings up a Help message on the toggling keymap. - - -@node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands -@section Mail Field Commands - -These commands allow you to view, modify, add, and delete various bits -of information from the info alist. -@xref{Information Keys and the Info Alist}.@refill - -@table @asis -@kindex C-c C-p f -@findex sc-mail-field-query -@findex mail-field-query (sc-) -@kindex C-c C-p f -@item @code{sc-mail-field-query} (@kbd{C-c C-p f}) -Allows you to interactively view, modify, add, and delete info alist -key-value pairs. With no argument, you are prompted (with completion) -for a info key. The value associated with that key is displayed in the -minibuffer. With an argument, this command will first ask if you want -to view, modify, add, or delete an info key. Viewing is identical to -running the command with no arguments. - -If you want to modify the value of a key, Supercite will first prompt -you (with completion) for the key of the value you want to change. It -will then put you in the minibuffer with the key's current value so you -can edit the value as you wish. When you hit @key{RET}, the key's value -is changed. Minibuffer history is kept for the values. - -If you choose to delete a key-value pair, Supercite will prompt you (with -completion) for the key to delete. - -If you choose to add a new key-value pair, Supercite firsts prompts you -for the key to add. Note that completion is turned on for this prompt, -but you can type any key name here, even one that does not yet exist. -After entering the key, Supercite prompts you for the key's value. It -is not an error to enter a key that already exists, but the new value -will override any old value. It will not replace it though; if you -subsequently delete the key-value pair, the old value will reappear. - -@findex sc-mail-process-headers -@findex mail-process-headers (sc-) -@kindex C-c C-p g -@item @code{sc-mail-process-headers} (@kbd{C-c C-p g}) -This command lets you re-initialize Supercite's info alist from any set -of mail headers in the region between @samp{point} and @samp{mark}. -This function is especially useful for replying to digest messages where -Supercite will initially set up its information for the digest -originator, but you want to cite each component article with the real -message author. Note that unless an error during processing occurs, any -old information is lost.@refill -@end table - -@node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands -@section Miscellaneous Commands - -@table @asis -@findex sc-open-line -@findex open-line (sc-) -@findex open-line -@kindex C-c C-p o -@item @code{sc-open-line} (@kbd{C-c C-p o}) -Similar to Emacs's standard @code{open-line} commands, but inserts the -citation string in front of the new line. As with @code{open-line}, -an optional numeric argument inserts that many new lines.@refill -@end table - -@node Hints to MUA Authors, Thanks and History, Electric References, Top -@chapter Hints to MUA Authors - -In June of 1989, some discussion was held between the various MUA -authors, the Supercite author, and other Supercite users. These -discussions centered around the need for a standard interface between -MUAs and Supercite (or any future Supercite-like packages). This -interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in -a mail message to the Supercite mailing list: - -@example - Martin> Each news/mail-reader should provide a form of - Martin> mail-yank-original that - - Martin> 1: inserts the original message incl. header into the - Martin> reply buffer; no indentation/prefixing is done, the header - Martin> tends to be a "full blown" version rather than to be - Martin> stripped down. - - Martin> 2: `point' is at the start of the header, `mark' at the - Martin> end of the message body. - - Martin> 3: (run-hooks 'mail-yank-hooks) - - Martin> [Supercite] should be run as such a hook and merely - Martin> rewrite the message. This way it isn't anymore - Martin> [Supercite]'s job to gather the original from obscure - Martin> sources. [@dots{}] -@end example - -@vindex mail-citation-hook -@vindex mail-yank-hooks -@cindex sendmail.el -@findex mail-yank-original -@findex defvar -This specification was adopted, but underwent a slight modification with -the release of Emacs 19. Instead of the variable -@code{mail-yank-hooks}, the hook variable that the MUA should provide is -@code{mail-citation-hook}. Richard Stallman suggests that the MUAs -should @code{defvar} @code{mail-citation-hook} to @code{nil} and perform -some default citing when that is the case.@refill - -If you are writing a new MUA package, or maintaining an existing MUA -package, you should make it conform to this interface so that your users -will be able to link Supercite easily and seamlessly. To do this, when -setting up a reply or forward buffer, your MUA should follow these -steps: - -@enumerate -@item -Insert the original message, including the mail headers into the reply -buffer. At this point you should not modify the raw text in any way -(except for any necessary decoding, e.g. of quoted-printable text), and -you should place all the original headers into the body of the reply. -This means that many of the mail headers will be duplicated, one copy -above the @code{mail-header-separator} line and one copy below, however -there will probably be more headers below this line.@refill - -@item -Set @samp{point} to the beginning of the line containing the first mail -header in the body of the reply. Set @samp{mark} at the end of the -message text. It is very important that the region be set around the -text Supercite is to modify and that the mail headers are within this -region. Supercite will not venture outside the region for any reason, -and anything within the region is fair game, so don't put anything that -@strong{must} remain unchanged inside the region.@refill - -@item -Run the hook @code{mail-citation-hook}. You will probably want to -provide some kind of default citation functions in cases where the user -does not have Supercite installed. By default, your MUA should -@code{defvar} @code{mail-citation-hook} to @code{nil}, and in your -yanking function, check its value. If it finds -@code{mail-citation-hook} to be @code{nil}, it should perform some -default citing behavior. User who want to connect to Supercite then -need only add @code{sc-cite-original} to this list of hooks using -@code{add-hook}.@refill -@end enumerate - -If you do all this your MUA will join the ranks of those that conform to -this interface ``out of the box.'' - -@node Thanks and History, GNU Free Documentation License, Hints to MUA Authors, Top -@chapter Thanks and History - -The Supercite package was derived from its predecessor Superyank 1.11 -which was inspired by various bits of code and ideas from Martin Neitzel -and Ashwin Ram. They were the folks who came up with the idea of -non-nested citations and implemented some rough code to provide this -style. Superyank and Supercite version 2 evolved to the point where much -of the attribution selection mechanism was automatic, and features have -been continuously added through the comments and suggestions of the -Supercite mailing list participants. - -With version 3, Supercite underwent an almost complete rewrite, -benefiting in a number of ways, including vast improvements in the -speed of performance, a big reduction in size of the code and in the use -of Emacs resources, and a much cleaner and flexible internal -architecture. Most of this work was internal and not of very great -importance to the casual user. There were some changes at the -user-visible level, but for the most part, the Supercite configuration -variables from version 2 should still be relevant to version 3. -Hopefully Supercite version 3 is faster, smaller, and much more flexible -than its predecessors. - -In the version 2 manual I thanked some specific people for their help in -developing Supercite 2. You folks know who you are and your continued -support is greatly appreciated. I wish to thank everyone on the -Supercite mailing list, especially the brave alpha testers, who helped -considerably in testing out the concepts and implementation of Supercite -version 3. Special thanks go out to the MUA and Emacs authors Kyle -Jones, Stephen Gildea, Richard Stallman, and Jamie Zawinski for coming -to a quick agreement on the new @code{mail-citation-hook} interface, and -for adding the magic lisp to their code to support this. - -All who have helped and contributed have been greatly appreciated. - -Supercite was written by Barry Warsaw. - -@node GNU Free Documentation License, Concept Index, Thanks and History, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index, Command Index, GNU Free Documentation License, Top -@unnumbered Concept Index -@printindex cp - -@node Command Index, Key Index, Concept Index, Top -@unnumbered Command Index - -Since all supercite commands are prepended with the string -``@code{sc-}'', each appears under its @code{sc-}@var{command} name and -its @var{command} name. -@iftex -@sp 2 -@end iftex -@printindex fn - -@node Key Index, Variable Index, Command Index, Top -@unnumbered Key Index -@printindex ky - -@node Variable Index, , Key Index, Top -@unnumbered Variable Index - -Since all supercite variables are prepended with the string -``@code{sc-}'', each appears under its @code{sc-}@var{variable} name and -its @var{variable} name. -@iftex -@sp 2 -@end iftex -@printindex vr -@bye diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi deleted file mode 100644 index 9f4dc72fea3..00000000000 --- a/doc/misc/sem-user.texi +++ /dev/null @@ -1,1331 +0,0 @@ -@c This file is included by semantic.texi - -@c Copyright (C) 1999-2005, 2007, 2009-2012 Free Software Foundation, Inc. - -@c Permission is granted to copy, distribute and/or modify this -@c document under the terms of the GNU Free Documentation License, -@c Version 1.3 or any later version published by the Free Software -@c Foundation; with no Invariant Sections, no Front-Cover Texts, and -@c no Back-Cover Texts. A copy of the license is included in the -@c section entitled ``GNU Free Documentation License''. - -You can begin using @semantic{} by enabling Semantic mode, a global -minor mode: type @kbd{M-x semantic-mode}, or open the @samp{Tools} -menu and click on the menu item named @samp{Source Code Parsers -(Semantic)}. @xref{Semantic mode}. - -When Semantic mode is turned on, Emacs automatically parses each file -you visit. You can then use @semantic{} user commands in those -buffers (@pxref{Semantic mode user commands}). You can also choose to -enable a number of ``helper'' minor modes for saving tags, displaying -tag information, and so forth. - -To enable Semantic mode each time you start Emacs, add the line -@code{(semantic-mode 1)} to your initialization file. @xref{Init -File,,,emacs,Emacs manual}. - -@menu -* Semantic mode:: Global minor mode for @semantic{}. -* SemanticDB:: Caching parsed buffers between sessions. -* Idle Scheduler:: @semantic{} actions that occur when idle. -* Analyzer:: Semantic tools for analyzing code. -* Speedbar:: Using @semantic{} with the Speedbar. -* SymRef:: Interface to symbol reference tools. -* MRU Bookmarks:: Managing tag "bookmarks". -* Sticky Func Mode:: Showing declarations in the header line. -* Highlight Func Mode:: Highlight the current function declaration. -* Tag Decoration Mode:: Minor mode to decorate tags. -@end menu - -@node Semantic mode -@section Semantic mode -@cindex Semantic mode - -Semantic mode is a global minor mode for @semantic{} as a whole. When -enabled, each file you visit is automatically parsed, provided its -major mode is specified in the variable -@code{semantic-new-buffer-setup-functions} (the default value of this -variable sets up parsing for all the parsers included with Emacs, but -you may add to it if you install additional parsers). - -In each parser-enabled buffer, a number of @semantic{} commands are -available for navigating, querying, and editing source code. -@xref{Semantic mode user commands}. Enabling Semantic mode also -installs a @samp{Development} menu on the menu-bar, with many of these -commands. - -In addition, enabling Semantic mode turns on certain auxiliary global -minor modes. The variable @code{semantic-default-submodes} determines -which auxiliary modes are enabled; the defaults are SemanticDB mode -(@pxref{SemanticDB}) and Global Semantic Idle Scheduler mode -(@pxref{Idle Scheduler}). You can also toggle the auxiliary minor -modes separately, using their mode functions (e.g. @kbd{M-x -semanticdb-minor-mode}), or via the @samp{Development} menu. The -various auxiliary minor modes are described in the following sections. - -@defvar semantic-new-buffer-setup-functions -The value of this variable is an alist of functions to call for -setting up @semantic{} parsing in the buffer. Each element has the -form @code{(@var{mode} . @var{fn})}, where @var{mode} is a value of -@code{major-mode} for the buffer and @var{fn} is the corresponding -function for setting up the parser. @var{fn} is called, with no -arguments, after the major mode is initialized (and after the mode -hooks have been run). - -The default value enables @semantic{} for all supported major modes -(i.e., C, C++, Scheme, Javascript, Java, HTML, SRecode, and Make), but -you can remove modes from this list if you don't want to use -@semantic{} with them. -@end defvar - -@defvar semantic-default-submodes -The value of this variable is a list of symbols, specifying the -auxiliary minor modes to enable when enabling Semantic mode. The -valid mode symbols are: - -@itemize -@item @code{global-semantic-idle-scheduler-mode} (@pxref{Idle Scheduler}). -@item @code{global-semanticdb-minor-mode} (@pxref{SemanticDB}). -@item @code{global-semantic-idle-summary-mode} (@pxref{Idle Summary Mode}). -@item @code{global-semantic-idle-completions-mode} (@pxref{Idle Completions Mode}). -@item @code{global-semantic-highlight-func-mode} (@pxref{Highlight Func Mode}). -@item @code{global-semantic-decoration-mode} (@pxref{Tag Decoration Mode}). -@item @code{global-semantic-stickyfunc-mode} (@pxref{Sticky Func Mode}). -@item @code{global-semantic-mru-bookmark-mode} (@pxref{MRU Bookmarks}). -@end itemize -@end defvar - -@menu -* Semantic mode user commands:: -@end menu - -@node Semantic mode user commands -@subsection Semantic mode user commands - -Semantic mode provides a number of commands for navigating, querying, -and editing source code in a language-aware manner. These commands -generally act on @dfn{tags}, which are the source-code units deemed -``important'' by the present programming language (e.g. functions in -the C programming language). - -These commands may be used in any buffer that has been parsed by -@semantic{}. Several of them prompt for a tag name using the -minibuffer; here, the @kbd{TAB} key can be used to complete tag names. -Others act on the @dfn{current tag}, meaning the tag at (or around) -point. - -@table @kbd -@item C-c , j -Prompt for a tag defined in the current file, and move point to it -(@code{semantic-complete-jump-local}). - -@item C-c , J -Prompt for a tag defined in any file that Emacs has parsed, and move -point to it (@code{semantic-complete-jump}). - -@item C-c , l -Display a list of the possible completions of the current tag -(@code{semantic-analyze-possible-completions}). - -@item C-c , g -Prompt for a tag, and display a list of tags that call it -(@code{semantic-symref-symbol}). This relies on the presence of an -external symbol reference tool. @xref{SymRef}. - -@item C-c , G -Display a list of tags that call the current tag -(@code{semantic-symref}). This relies on the presence of an external -symbol reference tool. @xref{SymRef}. - -@item C-c , p -Move point to the previous tag (@code{senator-previous-tag}). - -@item C-c , n -Move point to the next tag (@code{senator-next-tag}). - -@item C-c , u -Move point ``up'' one reference (@code{senator-go-to-up-reference}). -The meaning of ``up'' is language-dependent; in C++, for instance, -this means moving to the parent of the current tag. - -@item C-c, @key{SPC} -Display a list of possible completions for the symbol at point -(@code{semantic-complete-analyze-inline}). This also activates a -special set of keybindings for choosing a completion: @key{RET} -accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through -possible completions, @key{TAB} completes as far as possible and then -cycles, and @kbd{C-g} or any other key aborts the completion. -@xref{Smart Completion}. - -@item C-c , C-w -Kill the current tag (@code{senator-kill-tag}). This removes the text -for that tag, placing it in the kill ring. You can retrieve the text -with @kbd{C-y}. This also places the tag in the @dfn{tag ring}, so -that you can yank it with @kbd{\C-c,\C-y}, below. - -@item C-c , M-w -Copy the current tag into the kill ring as well as the tag ring -(@code{senator-copy-tag}). - -@item C-c , C-y -Yank a tag from the tag ring (@code{senator-yank-tag}). - -@item C-c , r -Copy the current tag into a register -(@code{senator-copy-tag-to-register}). With an optional argument, -kill it as well. This allows you to insert or jump to that tag with -the usual register commands. @xref{Registers,,,emacs,Emacs manual}. - -@item C-c , @kbd{up} -Transpose the current tag with the previous one -(@code{senator-transpose-tags-up}). - -@item C-c , @kbd{down} -Transpose the current tag with the next one -(@code{senator-transpose-tags-down}). -@end table - -@node SemanticDB -@section Semantic Database -@cindex SemanticDB - -The Semantic Database (SemanticDB) caches the results of parsing -source code files. This data can be saved to disk when you exit -Emacs, and reloaded automatically when you subsequently revisit the -same source code files. This saves time by eliminating the need to -re-parse unmodified files. - -SemanticDB also provides an @acronym{API} that programs can use to -acquire information about source code tags. This information can be -accessed without loading the original the source files into memory. -It can also be used to create alternate ``back-ends'' for storing tag -information in alternative on-disk formats. - -By default, SemanticDB is enabled together with Semantic mode. To -disable it, remove it from @code{semantic-default-submodes} -(@pxref{Semantic mode}). You can also enable or disable SemanticDB -with @kbd{M-x global-semanticdb-minor-mode}. - -@deffn Command global-semanticdb-minor-mode -Toggle SemanticDB mode. When enabled, any source code parsed by -@semantic{} is cached in a database. -@end deffn - -SemanticDB offers a large number of customizable options, which are -described in the following subsections. - -@menu -* Semanticdb Tag Storage:: -* Semanticdb Search Configuration:: -* Changing Backends:: -* Create System Databases:: -@end menu - -@node Semanticdb Tag Storage -@subsection Semanticdb Tag Storage - -Each time you exit Emacs, any data cached by SemanticDB is saved in -the directory @file{.emacs.d/semanticdb/}, located in your home -directory. Within this directory, the cache data is written into a -set of files according to a SemanticDB-specific filename convention. -If the SemanticDB directory does not exist, Emacs first asks if you -want to create it. - -You can change the name of the SemanticDB directory by customizing the -variable @code{semanticdb-default-save-directory}. - -@deffn Option semanticdb-default-save-directory -The name of the directory where SemanticDB cache files are saved. If -the value is @code{nil}, SemanticDB saves its data into a single file, -in the current directory, whose filename is given by -@code{semanticdb-default-file-name}. -@end deffn - -@deffn Option semanticdb-default-file-name -The name of a cache file in which to save SemanticDB, when -@code{semanticdb-default-save-directory} is @code{nil}. -@end deffn - -You can force SemanticDB to save the data from only certain files, or -suppress saving altogether, by customizing -@code{semanticdb-persistent-path}: - -@deffn Option semanticdb-persistent-path -List of valid paths for SemanticDB to cache. Each element should be a -directory name (a string); then the parse data from any file in that -directory is saved. - -As a special exception, the value of this variable can be a list -containing a single symbol: @code{never}, @code{always}, or -@code{project}. The symbol @code{never} disables saving anywhere; -@code{always} enables saving everywhere; and @code{project} enables -saving directory based on the variable -@code{semanticdb-project-predicate-functions}. - -The default value is @code{(always)}. -@end deffn - -@defvar semanticdb-project-predicate-functions -The value of this variable is a list of predicates for indicating that -a directory belongs to a project. This list is used when the value of -@code{semanticdb-persistent-path} is @code{(project)}. If the list is -empty, all paths are considered valid. - -Project management packages, such as EDE (@pxref{Top,,,ede,EDE -manual}), may add their own predicates with @dfn{add-hook} to this -variable. This allows SemanticDB to save tag caches in directories -controlled by them. -@end defvar - -@deffn Option semanticdb-save-database-hooks -Abnormal hook run after a database is saved. Each function is called -with one argument, the object representing the database recently -written. -@end deffn - -@node Semanticdb Search Configuration -@subsection Semanticdb Search Configuration - - When another part of @semantic{} (or another Emacs package using -@semantic{}) queries the SemanticDB library for a source code tag, the -search need not be limited to tags defined within the current file. -It can include tags defined elsewhere, such as @dfn{header files} -referenced by the current file (e.g., via the C/C++ @code{#include} -directive). While performing the search, the SemanticDB library may -even automatically visit other files and parse them, if necessary. - - The variable @code{semanticdb-find-default-throttle} determines how -aggressively SemanticDB searches for source code tags. @xref{Search -Throttle}. - - The details of SemanticDB searches can vary from language to -language. In C/C++ code, for example, SemanticDB distinguishes -between @dfn{project header files} and @dfn{system header files}, -based on whether the @code{#include} directive uses the @code{""} or -@code{<>} filename delimiter. SemanticDB looks for system header in -the @dfn{system include path} (@pxref{Include paths}). - -@menu -* Search Throttle:: Controlling how semanticdb searches occur. -* Semanticdb Roots:: Specifying the root of different projects. -* Include paths:: Specifying the directories to search. -* Semanticdb search debugging commands:: -@end menu - -@node Search Throttle -@subsubsection SemanticDB Search Throttle - -The SemanticDB @dfn{search throttle} determines how aggressive -SemanticDB searches are. It is controlled by the variable -@code{semanticdb-find-default-throttle}. The default value of this -variable aims for maximum accuracy, at the expense of search time. - -Other parts of the @semantic{} package, particularly the different -language parsers, may change the value of -@code{semanticdb-find-default-throttle}. You can override its value, -for a given major mode, like this: - -@example -(setq-mode-local c-mode - semanticdb-find-default-throttle - '(project unloaded system recursive)) -@end example - -@defvar semanticdb-find-default-throttle -The default throttle for @code{semanticdb-find} routines. -The throttle controls how detailed the list of database -tables is for a symbol lookup. The value is a list with -the following keys: - -@table @code -@item file -The file the search is being performed from. This option is here for -completeness only, and is assumed to always be on. -@item local -Tables from the same local directory are included. This includes -files directly referenced by a file name which might be in a different -directory. -@item project -Tables from the same local project are included If @code{project} is -specified, then @code{local} is assumed. -@item unloaded -If a table is not in memory, load it. If it is not cached on disk -either, get the source, parse it, and create the table. -@item system -Tables from system databases. These are specifically tables -from system header files, or language equivalent. -@item recursive -For include based searches, includes tables referenced by included -files. -@item omniscience -Included system databases which are omniscience, or somehow know -everything. Omniscience databases are found in -@code{semanticdb-project-system-databases}. The Emacs Lisp system -@var{db} is an omniscience database. -@end table -@end defvar - -@node Semanticdb Roots -@subsubsection SemanticDB project roots - -The @code{project} setting in the SemanticDB search throttle -(@pxref{Search Throttle}) tells SemanticDB to search within the -current single code project. For @semantic{}'s point of view, -@dfn{projects} are determined by their top-level directories, or -@dfn{project roots}; every subdirectory of a project root is -considered part of the same project. - -If you use EDE for project management, it will set the project roots -automatically. @xref{Top,,,ede,EDE manual}. You can also specify -them yourself. - -@deffn Option semanticdb-project-roots -The value of this variable is a list of directories (strings) that are -project roots. All subdirectories of a project root are considered -part of the same project. This variable can be overridden by -@code{semanticdb-project-root-functions}. -@end deffn - -@defvar semanticdb-project-root-functions -The value of this variable is a list of functions to determine a given -directory's project root. These functions are called, one at a time, -with one argument (the directory name), and must return either -@code{nil}, a string (the project root), or a list of strings -(multiple project roots, for complex systems). The first -non-@code{nil} return value, if any, is taken to be the project root, -overriding @code{semanticdb-project-roots}. -@end defvar - -@node Include paths -@subsubsection Include Paths - -System include paths are standard locations to find source code tags, -such as the @dfn{header files} in @file{/usr/include} and its -subdirectories on Unix-like operating systems. - -You can add and remove system include paths using the following -commands: - -@deffn Command semantic-add-system-include dir &optional mode -Prompts for a directory, @var{dir}, and add it as a system include -path for the current major mode. When called non-interactively, the -major mode can be specified with the @var{mode} argument. -@end deffn - -@deffn Command semantic-remove-system-include dir &optional mode -Prompt for a directory, @var{dir}, and remove it from the system -include path for the current major mode (or @var{mode}). -@end deffn - -@deffn Command semantic-customize-system-include-path &optional mode -Customize the system include path for the current major mode (or -@var{mode}). -@end deffn - -@defun semanticdb-implied-include-tags -Include tags implied for all files of a given mode. You can set this -variable with @code{defvar-mode-local} for a particular mode so that -any symbols that exist for all files for that mode are included. -@end defun - -@c @xref{Search Optimization}, for more information on include paths. - -@node Semanticdb search debugging commands -@subsubsection Semanticdb search debugging commands - -You can use @kbd{M-x semanticdb-dump-all-table-summary} to see the -list of databases that will be searched from a given buffer. You can -follow up with @kbd{M-x semanticdb-find-test-translate-path} to then -make sure specific tables from the path are discovered correctly. -Alternately, you can get a list of include files @semantic{} -encountered, but could not find on disk using @kbd{M-x -semanticdb-find-adebug-lost-includes}. - -@deffn Command semanticdb-dump-all-table-summary -Dump a list of all databases in Emacs memory. -@end deffn - -@deffn Command semanticdb-find-test-translate-path &optional arg -Call and output results of @dfn{semanticdb-find-translate-path}. In -the displayed buffer, you can type @key{SPC} to expand items. With -@var{arg} non-@code{nil}, specify a @var{brutish} translation. -@end deffn - -@deffn Command semanticdb-find-adebug-lost-includes -Translate the current path, then display the lost includes. -Examines the variable @code{semanticdb-find-lost-includes}. -@end deffn - -Lastly, you can test an explicit search term using this command: - -@deffn Command semantic-adebug-searchdb regex -Search the semanticdb for @var{regex} for the current buffer. -Display the results as a debug list. -@end deffn - -@node Changing Backends -@subsection Changing Backends - -If you want to use some other form of backend, you can use this -variable to choose which back end class to use for your general tag -storage. - -The default is to save databases in flat files. Alternatively, you -could write a new database backend that stores tags into a database, -or other storage system. - -@defvar semanticdb-new-database-class -The default type of database created for new files. This can be -changed on a per file basis, so that some directories are saved using -one mechanism, and some directories via a different mechanism. -@end defvar - -@node Create System Databases -@subsection Create System Databases - -If your supported language stores the system libraries in readily -available parsable source code, you can pre-generate database files -for them once, which will be used over and over for tools such as -summary-mode, or the analyzer. - -@deffn Command semanticdb-create-ebrowse-database dir -Create an @var{ebrowse} database for directory @var{dir}. -The database file is stored in ~/.semanticdb, or whichever directory -is specified by @code{semanticdb-default-system-save-directory}. -@end deffn - -@node Idle Scheduler -@section Idle Scheduler -@cindex Idle Scheduler - -The @dfn{Semantic Idle Scheduler} is a part of @semantic{} that -performs various operations while Emacs is waiting for user input -(idle time). Its primary job is to perform buffer parsing during idle -time. You can also use the Idle Scheduler to display function -prototypes (@pxref{Idle Summary Mode}) or symbol completions -(@pxref{Idle Completions Mode}). - -@deffn Command global-semantic-idle-scheduler-mode &optional arg -This command toggles Semantic Idle Scheduler mode in every -@semantic{}-enabled buffer. This minor mode ensures that the buffer -is automatically reparsed whenever Emacs is idle. If there is -additional idle time, it runs jobs scheduled by other parts of -@semantic{}, such as Semantic Idle Summary mode (@pxref{Idle Summary -Mode}) and Semantic Idle Completions mode (@pxref{Idle Completions -Mode}). -@end deffn - -@deffn Option semantic-idle-scheduler-idle-time -The value of this variable is the amount of idle time, in seconds, -before the Semantic idle scheduler activates. The default is 1. -@end deffn - -@deffn Option semantic-idle-scheduler-verbose-flag -If this variable is non-@code{nil}, the idle scheduler prints verbose -messages while running, which are useful for debugging. -@end deffn - -@menu -* Reparsing Options:: Reparsing the current buffer in idle time. -* Idle Working Options:: Options for extra work done at idle time. -* Debugging Idle Time Issues:: How to produce good bug reports. -* Idle Summary Mode:: Display prototype of symbol under cursor. -* Idle Completions Mode:: Smart completion pop-up help. -@end menu - -@node Reparsing Options -@subsection Reparsing Options - -When activated during idle time, the Semantic idle scheduler -automatically reparses all buffers that need it. Any arriving user -input cancels this, returning Emacs to its normal editing behavior. - -@deffn Option semantic-idle-scheduler-max-buffer-size -Maximum size in bytes of buffers automatically reparsed. If this -value is less than or equal to @var{0}, buffers are automatically -reparsed regardless of their size. -@end deffn - -@deffn Option semantic-idle-scheduler-no-working-message -If non-@code{nil}, disable display of working messages while reparsing. -@end deffn - -@deffn Option semantic-idle-scheduler-working-in-modeline-flag -If non-@code{nil}, show working messages in the mode line. Normally, -re-parsing shows messages in the minibuffer; this moves the parse -message to the modeline instead. -@end deffn - -@defvar semantic-before-idle-scheduler-reparse-hook -This normal hook is run just before the idle scheduler begins -reparsing. If any hook function throws an error, the value of this -variable is reset to @code{nil}. This hook is not protected from -lexical errors. -@end defvar - -@defvar semantic-after-idle-scheduler-reparse-hook - -This normal hook is run after the idle scheduler finishes reparsing. -If any hook throws an error, this variable is reset to @code{nil}. -This hook is not protected from lexical errors. -@end defvar - -@node Idle Working Options -@subsection Idle Working Options - -In addition to reparsing buffers, the Semantic idle scheduler performs -additional operations, including the following: - -@itemize -@item -Creating the include path caches required for symbol lookup. -@item -Create data type caches. -@item -Saving SemanticDB caches to disk. -@item -Speculatively parsing the files in the same directory as the current -buffer. -@end itemize - -Because this extra work is quite time-consuming, it is only carried -out after a longer idle delay. The following features control how the -idle work is performed. - -@deffn Option semantic-idle-scheduler-work-idle-time -The value of this variable is the amount of idle time, in seconds, -before commencing idle work. The default is 60. -@end deffn - -@deffn Option semantic-idle-work-parse-neighboring-files-flag -If the value of this variable is non-@code{nil}, the Semantic idle -scheduler uses idle work time to parse files in the same directory as -the current buffer. This improves the accuracy of tag searches and -saves time when visiting those files later, at the cost of doing a lot -of parsing. The default is @code{t}. -@end deffn - -@node Debugging Idle Time Issues -@subsection Debugging Idle Time Issues - -If you see an error signaled during idle time, it could be an -indication of a more serious issue elsewhere. It is not enough to -enable @code{debug-on-error}, because the idle scheduler inhibits the -debugger. Instead, use the following commands to debug the error: - -@deffn Command semantic-debug-idle-function -Run the Semantic idle function with debugging turned on. -@end deffn - -@deffn Command semantic-debug-idle-work-function -Run the Semantic idle work function with debugging turned on. -@end deffn - -@node Idle Summary Mode -@subsection Idle Summary Mode - -Semantic Idle Summary mode is a minor mode that displays a short -summary of the symbol at point, such as its function prototype, in the -echo area. Its functionality is similar to what ElDoc mode provides -for Emacs Lisp (@pxref{Lisp Doc,,,emacs,Emacs manual}). - -@deffn global-semantic-idle-summary-mode &optional arg -This command toggles Semantic Idle Summary mode in all -@semantic{}-enabled buffers. You can also toggle it via the -@samp{Show Tag Summaries} menu item in the @samp{Development} menu. -@end deffn - -When Semantic Idle Summary mode is active, a summary of the tag at -point is displayed in the echo area. This display takes place during -the idle time, as given by @code{semantic-idle-scheduler-idle-time} -(@pxref{Idle Scheduler}). - -You can override the method for getting the current tag to display by -setting @code{idle-summary-current-symbol-info}. - -@deffn Option semantic-idle-summary-function -The value of this variable should be a function to call to display tag -information during idle time. See the variable -@code{semantic-format-tag-functions} for a list of useful functions. -@end deffn - -@defvar semantic-idle-summary-out-of-context-faces -The value of this variable is a list of font-lock faces indicating -useless summary contexts. These are generally faces used to highlight -comments or strings. Semantic Idle Summary mode does not display its -usual summary if the text at point has one of these faces. -@end defvar - -@node Idle Completions Mode -@subsection Idle Completions Mode - -Semantic Idle Completions mode is a minor mode for performing -@dfn{code completions} during idle time. The completions are -displayed inline, with keybindings that allow you to cycle through -different alternatives. - -Semantic Idle Completions mode performs completion based on the -Semantic Analyzer (@pxref{Analyzer}). - -@deffn global-semantic-idle-completions-mode &optional arg -This command toggles Semantic Idle Completions mode in every -@semantic{}-enabled buffer. You can also toggle it via the @samp{Show -Tag Completions} menu item in the @samp{Development} menu. -@end deffn - -If the tag at point has at least one completion, Semantic Idle -Completions mode displays that completion inline---i.e., as part of -the buffer text (you can change the display method by customizing -@code{semantic-complete-inline-analyzer-idle-displayor-class}, as -described below). The completed part is highlighted, to indicate that -it is not yet properly inserted into the buffer. The echo area shows -the completion, and whether there are other possible completions, like -this: - -@example -besselj [1 of 6 matches] -@end example - -@noindent -While the completion is being displayed, the following keybindings -take effect: - -@table @kbd -@item @key{RET} -@itemx C-m -Accept the current completion (@code{semantic-complete-inline-done}), -placing it in the buffer and moving point to the end of the completed -tag. -@item M-n -Select the next possible completion -(@code{semantic-complete-inline-down}). The new completion is shown -inline, replacing the old completion. -@item M-p -Select the previous possible completion -(@code{semantic-complete-inline-up}). -@item @key{TAB} -@item C-i -Accept as much of the completion as possible. If no additional -completion can be accepted without ambiguity, select the next possible -completion (@code{semantic-complete-inline-TAB}). -@item C-g -Quit without completing (@code{semantic-complete-inline-quit}). -@end table - -@noindent -You can also exit inline completion by issuing any other Emacs -command. The completion text then disappears from the buffer. - -@deffn Command semantic-complete-analyze-inline-idle -This is the command for performing inline code completion. It is -called by Semantic Idle Completions mode during idle time, but you can -also call it yourself. It returns immediately, leaving the buffer in -a state for inline completion. -@end deffn - -@deffn Option semantic-complete-inline-analyzer-idle-displayor-class -The value of this variable determines how -@code{semantic-complete-analyze-inline-idle} shows its completions. -Possible values include: - -@table @code -@item semantic-displayor-ghost -Display completions ``inline'' with the buffer text, as described -above. This is the default value. - -@item semantic-displayor-tooltip -Display completions in a tooltip. - -@item semantic-displayor-traditional -Display completions in a separate window. -@end table -@end deffn - -@node Analyzer -@section Analyzer -@cindex Analyzer - -The Semantic Analyzer is a library for performing context analysis on -source code. It provides user commands for displaying, completing, -and navigating through source code. - -@menu -* Smart Completion:: Performing code completion. -* Smart Summary:: Displaying help on a symbol. -* Smart Jump:: Jumping to the definition of a tag. -* Analyzer Debug:: Debugging problems with the analyzer. -@end menu - -@node Smart Completion -@subsection Smart Completion - -The Semantic Analyzer can be used to perform code completion in a -manner that takes the local context into account. (In addition to the -user commands in this section, Semantic Idle Completions mode also -uses the Semantic Analyzer. @xref{Idle Completions Mode}.) - -@deffn Command semantic-analyze-possible-completions context -This is the most basic command for Semantic Analyzer-based completion. -Called interactively, it displays a list of the possible completions -for the symbol at point. - -When called from a Lisp program, -@code{semantic-analyze-possible-completions} does not display a -completions list. The argument @var{context} should be either a -buffer position, or a context object. The return value is a list of -@semantic{} tag objects that complete the symbol for @var{context}, -based on the following criteria: - -@itemize -@item Elements currently in scope. -@item Constants currently in scope. -@item Elements matching the context's @code{:prefix}. -@item Type of the completion matching the type of the context. -@end itemize - -Most of the other commands documented in this section call -@code{semantic-analyze-possible-completions} internally. -@end deffn - -@deffn Command semantic-complete-analyze-inline -This command is bound to @kbd{C-c , @key{SPC}} when Semantic mode is -enabled (@pxref{Semantic mode user commands}). It displays a list of -possible completions for the symbol at point, and activates a special -set of keybindings for choosing a completion. - -You can type @key{RET} to accept the current completion, @kbd{M-n} and -@kbd{M-p} to cycle through the possible completions, @key{TAB} to -complete as far as possible and then cycle through completions, and -either @kbd{C-g} or any other key to abort the completion. - -This command is similar to the completion performed by Semantic Idle -Completions mode. The main difference is that it is called -explicitly, whereas Semantic Idle Completions mode completes during -idle time (@pxref{Idle Completions Mode}). -@end deffn - -@deffn Option semantic-complete-inline-analyzer-idle-displayor-class -The value of this variable determines how -@code{semantic-complete-analyze-inline} shows its completions. -Possible values include: - -@table @code -@item semantic-displayor-traditional -Display completions in a separate window. This is the default value. - -@item semantic-displayor-ghost -Display completions ``inline'' with the buffer text, similar to the -default behavior of Semantic Idle Completions mode (@pxref{Idle -Completions Mode}). - -@item semantic-displayor-tooltip -Display completions in a tooltip. -@end table -@end deffn - -In addition to @code{semantic-complete-analyze-inline}, you can use -the simpler command @code{semantic-ia-complete-symbol point}. This -behaves like the usual @kbd{M-@key{TAB}} (@code{complete-symbol}) -command (@pxref{Symbol Completion,,,emacs,Emacs manual}), except it -uses the Semantic Analyzer. - -@deffn Command semantic-ia-complete-symbol point -Complete the current symbol at @var{point}. -@end deffn - -@node Smart Summary -@subsection Smart Summary - -You can use the following commands to obtain information about the -code at point: - -@deffn Command semantic-ia-show-summary pos -Display a summary for the symbol at @var{pos}. Called interactively, -@var{pos} defaults to point. -@end deffn - -@deffn Command semantic-ia-show-doc pos -Display the code-level documentation for the symbol at @var{pos}. -Called interactively, @var{pos} defaults to point. -@end deffn - -@deffn Command semantic-ia-describe-class typename -Prompt for the name of a data type, @var{typename}, and display its -components. For instance, if the type in question is a class, this -displays the methods and member variables. -@end deffn - -You can also use Semantic Idle Summary mode to show information about -the current symbol in the echo area during idle time. @xref{Idle -Summary Mode}. - -@node Smart Jump -@subsection Smart Jump - -The Semantic Analyzer can be used to jump directly to the definition -for a code symbol. - -@deffn Command semantic-ia-fast-jump pos -Jump to the definition for the symbol at @var{pos}. Called -interactively, @var{pos} defaults to point. -@end deffn - -@defun semantic-ia-fast-mouse-jump event -Jump to the definition for the symbol at the position of the mouse -event @var{event}. This command is meant to be bound to a mouse -command, like this: - -@example -(global-set-key '[(S-mouse-1)] semantic-ia-fast-mouse-jump) -@end example -@end defun - -These commands are often more accurate than the @code{find-tag} -command (@pxref{Tags,,,emacs,Emacs manual}), because the Semantic -Analyzer is context-sensitive. - -You can also use @kbd{C-c , j} (@code{semantic-complete-jump-local}) -and @kbd{C-c , J} (@code{semantic-complete-jump}) to navigate tags. -@xref{Semantic mode user commands}. Those commands do not make use of -the Semantic Analyzer. - -@node Analyzer Debug -@subsection Debugging the Semantic Analyzer - -If the Semantic Analyzer does not analyze your code properly, you can -take steps to identify and solve the problem. This section was -written with C/C++ in mind, but should be relevant for any typed -language. - -@subsubsection Step 1: Check the context - -To check the current context, type @kbd{M-x -semantic-analyze-current-context}. - -@deffn Command semantic-analyze-current-context pos -Analyze the context at @var{pos}. This function is used by most of -the other Semantic Analyzer commands to obtain the context of the code -at a given buffer position. The return value is an EIEIO object -describing the context at @var{pos} (@pxref{Top,,,eieio,EIEIO -manual}). - -When called interactively, this displays a @samp{*Semantic Context -Analysis*} buffer containing a summary of the context at point. -@end deffn - -@noindent -The Prefix section of the @samp{*Semantic Context Analysis*} buffer -lists the tags based on the text at point. If it shows only a simple -string, the Semantic was unable to identify what the data type was. - -The first item in the list of the prefix is the first lookup failure -in the chain, and that is the item to focus debugging effort on. For -example: - -@example -Context Type: # -Bounds: (182 . 185) -Prefix: Foo* bar - int bbb (const char* y) -Prefix Types: class Foo @{@} --------- --> Local Vars: int argc - char** argv -@end example - -In this example you can see that the prefix has two fully found tags. -In the following example, the symbol ``bbb'' is incomplete, and could -not be found: - -@example -Context Type: # -Bounds: (182 . 184) -Prefix: Foo* bar - "bb" -Prefix Classes: 'function - 'variable -Prefix Types: class Foo @{@} --------- --> Local Vars: int argc - char** argv -@end example - -@subsubsection Step 2 : Check your include path - -Once you know the missing symbol, check your include path. The header -or include file containing the needed definition may not be in the -list of headers @semantic{} is searching through. To get a basic -list, you can use @kbd{M-x semanticdb-find-test-translate-path}. -@xref{Semanticdb search debugging commands}. - -If items should be loaded but aren't, or if you see some tables that -have no tags in them, then you you may have an incorrectly-set search -throttle (@pxref{Search Throttle}). For example, - -@example -*# -*# -@end example - -Here, @semantic{} found @file{foo.hh}, but there are 0 tags. This may -be because you had set the throttle to avoid reading and parsing files -that Emacs has not visited. To fix this, visit the file and let -@semantic{} parse it. - -For C++, check also that the @samp{#include} statements for your -project-level files use quotes, not angle brackets; angle brackets are -for system files. - -@subsubsection Step 3: Check the local scope - -If your data type is somehow abbreviated based on scope, such as from -a @code{using} statement, you should make sure that the symbol you -want is in the local scope. Examine the scope with @kbd{M-x -semantic-calculate-scope}. The scope structure is displayed in ADEBUG -mode, so use @kbd{SPC} to expand different elements and looking for -your symbol. - -If your symbol should be in the scope, but you cannot find it, then -you may have found a language support bug in the local-variable -parser, or using statement parser. - -Calling @kbd{M-x bovinte} should force a reset on the scope in case -there is merely some bad state. - -@example - ] Name: Cache - ] Class: #'semantic-scope-cache - ] :table # - ] tag createMoose : class moose - ] scopetypes 'nil - ] parents # - ] scope # - ] fullscope # - ] localvar # -@end example - -In the above sample output, the @code{tag} slot specifies where within -you source this scope is relevant. @code{Parents} should contain any -in scope parents, such as the class a method belongs to. -@code{Localvar} should contain your local variables. @code{Scope} -should contain datatypes in scope due to a @code{using} statement or -the like. - -@subsubsection Step 4: Check the typecache - -For complex typed languages like C++, @semantic{} creates a typecache, -or an optimized search table with all the various data types in it. -Elements in the typecache do not obey local scope. It only contains -fully qualified names. You can examine the typecache with -@kbd{M-x semanticdb-typecache-dump}. - -If your data types are not in the typecache, there may be some parsing -error or other bug. Calling @kbd{M-x bovinte} should force a reset on -the typecache in case there is merely some bad state. - -@example -]# - ] Name: /home/zappo/cedet/semantic/tests/testsubclass.cpp - ] Class: #'semanticdb-typecache - ] filestream 'nil - ] includestream # - ] stream 'nil - ] dependants 'nil -@end example - -In the above example, the output of @kbd{M-x semanticdb-typecache-dump} -was expanded one level. The @code{filestream} slot should contain -datatypes in the current file. The @code{includestream} should -contain all the datatypes in all included header files. - -The @code{dependants} slot will specify other files that depend on -this one. - -@subsubsection Step 5: Check the parser - -Go to the location where your unfound tag should be. You can call -@kbd{M-x bovinate}, and see a dump of the raw tag structure. To see a -navigable tree, use @kbd{M-x semantic-adebug-bovinate} instead. You -can then look to make sure your tag has been properly parsed. - -If it has not, then you may have found a parser bug. To get a feel -how @semantic{} treats your file, type @kbd{M-x -global-semantic-show-unmatched-syntax-mode}. This causes any syntax -it cannot parse to be underlined in red. - -If your type is not parsable, it could be for a couple of reasons: - -@enumerate -@item -If there is a MACRO keyword used in the definition of the type, you -may need to update the @code{semantic-lex-c-preprocessor-symbol-map} -to account for it. - -@item -Or perhaps the parser needs to be fixed. -@end enumerate - -@node Speedbar -@section Speedbar -@cindex speedbar - -You can integrate @semantic{} with the Speedbar. -@xref{Speedbar,,,emacs,Emacs manual}. To do this, add the following -line to your init file: - -@example -(add-hook 'speedbar-load-hook (lambda () (require 'semantic/sb))) -@end example - -@noindent -Or, alternatively: - -@example -(require 'semantic/sb) -@end example - -Once installed, the Speedbar will use @semantic{} to find and display -tags. Tags from @semantic{} are displayed with more details than -ordinary Speedbar tags, such as function arguments and return type. - -In addition, you can use the Speedbar to show the output of the -Semantic Analyzer (@pxref{Analyzer}). To do this, go to the -@samp{Display} menu item on the Speedbar menu and select -@samp{Analyze}; or type @kbd{M-x semantic-speedbar-analysis}. - -@deffn Command semantic-speedbar-analysis -Start the Speedbar in Semantic Analysis mode. -@end deffn - -In Semantic Analysis mode, the Speedbar displays information about the -local context, such as the current function, local arguments and -variables, and details on the prefix (the current symbol). Each entry -has an @samp{} button; clicking on this shows a summary of what -@semantic{} knows about that variable or type. The Speedbar also -displays a list of possible completions at point. - -@node SymRef -@section Symbol References -@cindex symref - -@semantic{} can interface with external @dfn{symbol reference tools}, -such as GNU Global and GNU Idutils. These tools provide information -about where different tags or symbols appear. - -By default, @semantic{} tries to look for the best external symbol -reference tool that can be used. The supported tools are GNU Global, -GNU Idutils, CScope, and Grep (the fallback method). For best -results, use GNU Global. However, @semantic{} does not manage your -GNU Global tables for you; you must manage them yourself. - -@defvar semantic-symref-tool -The value of this variable is a symbol that determines the external -symbol reference tool to use. The default value, @code{detect}, says -to look for the best available tool. Other possible values are -@code{global}, @code{idutils}, @code{cscope}, and @code{grep}. Note -that @code{grep} is much slower than the others. -@end defvar - -The commands to display symbol references are @kbd{C-c , g} -(@code{semantic-symref-symbol} and @kbd{C-c , G} -(@code{semantic-symref}). These keybindings are available whenever -Semantic mode is enabled (@pxref{Semantic mode user commands}). - -@deffn Command semantic-symref-symbol sym -This command (normally bound to @kbd{C-c , g}) prompts for a symbol -name, and uses an external reference tool to find references to that -tag. -@end deffn - -@deffn Command semantic-symref -This command (normally bound to @kbd{C-c , G}) uses an external -reference tool to find references to the current tag. -@end deffn - -Both @code{semantic-symref-symbol} and @code{semantic-symref} display -a list of symbol references in a separate buffer. The entries are -organized by file, and by function name. Typing @key{RET} on the -@samp{[+]} next to each function name ``expands'' that entry, listing -all references to the target symbol occurring within that function. -Typing @kbd{RET} on a reference line jumps to that reference. - -@node MRU Bookmarks -@section MRU Bookmarks mode -@cindex semantic-mru-bookmark-mode - -Semantic MRU Bookmarks mode is a minor mode that keeps track of the -tags you have edited, allowing you to quickly return to them later -(MRU stands for ``Most Recently Used''). - -@deffn Command global-semantic-mru-bookmark-mode &optional arg -Toggle Semantic MRU Bookmarks mode globally. The minor mode can be -turned on only if the current buffer was set up for parsing. With -argument @var{arg}, turn the minor mode if @var{arg} is positive, and -off otherwise. -@end deffn - -Semantic MRU Bookmarks mode takes note of each tag you edit. -Afterwards, you can type @kbd{C-x B} -(@code{semantic-mrub-switch-tags}) to return to a tag. This command -prompts for a tag name, completing with the names of edited tags; at -the prompt, you can use @kbd{M-p} and @kbd{M-n} to cycle through tags -in order of last modification time. - -@node Sticky Func Mode -@section Sticky Function mode - -Semantic Sticky Function minor mode displays a header line that shows -the declaration line of the function or tag on the topmost line in the -text area. This allows you to keep that declaration line in view at -all times, even if it is scrolls off the ``top'' of the screen. - -In addition, clicking @kbd{Mouse-1} on the header line opens a context -menu that contains menu items for copying, killing, or narrowing to -that tag. - -@deffn Command global-semantic-stickyfunc-mode &optional arg -Toggle Semantic Sticky Function mode in all Semantic-enabled buffers. -With an optional argument @var{arg}, enable if @var{arg} is positive, -and disable otherwise. -@end deffn - -@defvar semantic-stickyfunc-sticky-classes -The value of this variable is a list of tag classes that Semantic -Sticky Function mode makes ``sticky''. The default is -@code{'(function type)}, meaning function declarations and type -declarations. Other possible tag classes are @code{variable}, -@code{include}, and @code{package}. -@end defvar - -@node Highlight Func Mode -@section Highlight Func Mode -@cindex semantic-highlight-func-mode - -Semantic Highlight Function minor mode highlights the declaration line -of the current function or tag (that is to say, the first line that -describes the rest of the construct). - -In addition, clicking @kbd{Mouse-3} on the highlighted declaration -line opens a context menu that contains menu items for copying, -killing, or narrowing to that tag. - -The tag classes highlighted by Semantic Highlight Function mode are -the same ones given by @code{semantic-stickyfunc-sticky-classes}. -@xref{Sticky Func Mode}. - -@defun global-semantic-highlight-func-mode &optional arg -Toggle Semantic Highlight Function mode in all Semantic-enabled -buffers. With an optional argument @var{arg}, enable if @var{arg} is -positive, and disable otherwise. -@end defun - -@deffn Face semantic-highlight-func-current-tag-face -This face is used to highlight declaration lines in Semantic Highlight -Func mode. -@end deffn - -@node Tag Decoration Mode -@section Tag Decoration Mode -@cindex semantic-decoration-mode - -Semantic Tag Decoration mode ``decorates'' each tag based on certain -arbitrary features of that tag. Decorations are specified using the -variable @code{semantic-decoration-styles}. - -@deffn Command global-semantic-decoration-mode &optional arg -Toggle Semantic Tag Decoration mode in all Semantic-enabled buffers. -With an optional argument @var{arg}, enable if @var{arg} is positive, -and disable otherwise. -@end deffn - -@defvar semantic-decoration-styles -The value of this variable is a list of decoration styles for Semantic -Tag Decoration mode. Each element in this list should have the form -@code{(@var{name} . @var{flag})}, where @var{name} is a style name (a -symbol) and @var{flag} is non-@code{nil} if the style is enabled. - -The following styles are available: - -@table @code -@item semantic-tag-boundary -Place an overline in front of each long tag (excluding prototypes). - -@item semantic-decoration-on-private-members -Highlight class members that are designated as private. - -@item semantic-decoration-on-protected-members -Highlight class members that are designated as protected. - -@item semantic-decoration-on-includes -Highlight class members that are includes. Clicking on the -highlighted include statements opens a context menu for configuring -@semantic{} includes. -@end table -@end defvar - -To enable or disable specific decorations, use this function: - -@deffn Command semantic-toggle-decoration-style name &optional arg -Prompt for a decoration style, @var{name}, and turn it on or off. -With prefix argument @var{arg}, turn on if positive, otherwise off. -Return non-@code{nil} if the decoration style is enabled. -@end deffn - -@deffn Face semantic-tag-boundary-face -Face for long tags in the @code{semantic-tag-boundary} decoration -style. -@end deffn - -@deffn Face semantic-decoration-on-private-members-face -Face for privately-scoped tags in the -@code{semantic-decoration-on-private-members} decoration style. -@end deffn - -@deffn Face semantic-decoration-on-protected-members-face -Face for protected tags in the -@code{semantic-decoration-on-protected-members} decoration style. -@end deffn - -@deffn Face semantic-decoration-on-includes -Face for includes that are not in some other state, in the -@code{semantic-decoration-on-includes} decoration style. -@end deffn - -@deffn Face semantic-decoration-on-unknown-includes -Face for includes that cannot be found, in the -@code{semantic-decoration-on-includes} decoration style. -@end deffn - -@deffn Face semantic-decoration-on-unparsed-includes -Face for includes that have not yet been parsed, in the -@code{semantic-decoration-on-includes} decoration style. -@end deffn - -@subsection Creating New Decoration Modes - -You can create new types of decorations using the following function: - -@defun define-semantic-decoration-style name doc &rest flags -Define a new decoration style with @var{name}. -@var{doc} is a documentation string describing the decoration style @var{name}. -It is appended to auto-generated doc strings. -An Optional list of @var{flags} can also be specified. Flags are: - @code{:enabled} - specify the default enabled value for @var{name}. - - -This defines two new overload functions respectively called @code{NAME-p} -and @code{NAME-highlight}, for which you must provide a default -implementation in respectively the functions @code{NAME-p-default} and -@code{NAME-highlight-default}. Those functions are passed a tag. @code{NAME-p} -must return non-@code{nil} to indicate that the tag should be decorated by -@code{NAME-highlight}. - -To put primary decorations on a tag @code{NAME-highlight}, use -functions like @dfn{semantic-set-tag-face}, -@dfn{semantic-set-tag-intangible}, etc., found in the -semantic-decorate library. - -To add other kind of decorations on a tag, @code{NAME-highlight} must use -@dfn{semantic-decorate-tag}, and other functions of the semantic -decoration @var{api} found in this library. -@end defun diff --git a/doc/misc/semantic.texi b/doc/misc/semantic.texi deleted file mode 100644 index ad8392c208b..00000000000 --- a/doc/misc/semantic.texi +++ /dev/null @@ -1,623 +0,0 @@ -\input texinfo -@setfilename ../../info/semantic -@set TITLE Semantic Manual -@set AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim -@settitle @value{TITLE} - -@c ************************************************************************* -@c @ Header -@c ************************************************************************* - -@c Merge all indexes into a single index for now. -@c We can always separate them later into two or more as needed. -@syncodeindex vr cp -@syncodeindex fn cp -@syncodeindex ky cp -@syncodeindex pg cp -@syncodeindex tp cp - -@c @footnotestyle separate -@c @paragraphindent 2 -@c @@smallbook -@c %**end of header - -@copying -This manual documents the Semantic library and utilities. - -Copyright @copyright{} 1999-2005, 2007, 2009-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Semantic: (semantic). Source code parser library and utilities. -@end direntry - -@titlepage -@center @titlefont{Semantic} -@sp 4 -@center by @value{AUTHOR} -@end titlepage -@page - -@macro semantic{} -@i{Semantic} -@end macro - -@macro keyword{kw} -@anchor{\kw\} -@b{\kw\} -@end macro - -@macro obsolete{old,new} -@sp 1 -@strong{Compatibility}: -@code{\new\} introduced in @semantic{} version 2.0 supersedes -@code{\old\} which is now obsolete. -@end macro - -@c ************************************************************************* -@c @ Document -@c ************************************************************************* -@contents - -@node top -@top @value{TITLE} - -@semantic{} is a suite of Emacs libraries and utilities for parsing -source code. At its core is a lexical analyzer and two parser -generators (@code{bovinator} and @code{wisent}) written in Emacs Lisp. -@semantic{} provides a variety of tools for making use of the parser -output, including user commands for code navigation and completion, as -well as enhancements for imenu, speedbar, whichfunc, eldoc, -hippie-expand, and several other parts of Emacs. - -To send bug reports, or participate in discussions about semantic, -use the mailing list cedet-semantic@@sourceforge.net via the URL: -@url{http://lists.sourceforge.net/lists/listinfo/cedet-semantic} - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Introduction:: -* Using Semantic:: -* Semantic Internals:: -* Glossary:: -* GNU Free Documentation License:: -* Index:: -@end menu - -@node Introduction -@chapter Introduction - -This chapter gives an overview of @semantic{} and its goals. - -Ordinarily, Emacs uses regular expressions (and syntax tables) to -analyze source code for purposes such as syntax highlighting. This -approach, though simple and efficient, has its limitations: roughly -speaking, it only ``guesses'' the meaning of each piece of source code -in the context of the programming language, instead of rigorously -``understanding'' it. - -@semantic{} provides a new infrastructure to analyze source code using -@dfn{parsers} instead of regular expressions. It contains two -built-in parser generators (an @acronym{LL} generator named -@code{Bovine} and an @acronym{LALR} generator named @code{Wisent}, -both written in Emacs Lisp), and parsers for several common -programming languages. It can also make use of @dfn{external -parsers}---programs such as GNU Global and GNU IDUtils. - -@semantic{} provides a uniform, language-independent @acronym{API} for -accessing the parser output. This output can be used by other Emacs -Lisp programs to implement ``syntax-aware'' behavior. @semantic{} -itself includes several such utilities, including user-level Emacs -commands for navigating, searching, and completing source code. - -The following diagram illustrates the structure of the @semantic{} -package: - -@table @strong -@item Please Note: -The words in all-capital are those that @semantic{} itself provides. -Others are current or future languages or applications that are not -distributed along with @semantic{}. -@end table - -@example - Applications - and - Utilities - ------- - / \ - +---------------+ +--------+ +--------+ - C --->| C PARSER |--->| | | | - +---------------+ | | | | - +---------------+ | COMMON | | COMMON |<--- SPEEDBAR - Java --->| JAVA PARSER |--->| PARSE | | | - +---------------+ | TREE | | PARSE |<--- SEMANTICDB - +---------------+ | FORMAT | | API | - Scheme --->| SCHEME PARSER |--->| | | |<--- ecb - +---------------+ | | | | - +---------------+ | | | | - Texinfo --->| TEXI. PARSER |--->| | | | - +---------------+ | | | | - - ... ... ... ... - - +---------------+ | | | | - Lang. Y --->| Y Parser |--->| | | |<--- app. ? - +---------------+ | | | | - +---------------+ | | | |<--- app. ? - Lang. Z --->| Z Parser |--->| | | | - +---------------+ +--------+ +--------+ -@end example - -@menu -* Semantic Components:: -@end menu - -@node Semantic Components -@section Semantic Components - -In this section, we provide a more detailed description of the major -components of @semantic{}, and how they interact with one another. - -The first step in parsing a source code file is to break it up into -its fundamental components. This step is called lexical analysis: - -@example - syntax table, keywords list, and options - | - | - v - input file ----> Lexer ----> token stream -@end example - -@noindent -The output of the lexical analyzer is a list of tokens that make up -the file. The next step is the actual parsing, shown below: - -@example - parser tables - | - v - token stream ---> Parser ----> parse tree -@end example - -@noindent -The end result, the parse tree, is @semantic{}'s internal -representation of the language grammar. @semantic{} provides an -@acronym{API} for Emacs Lisp programs to access the parse tree. - -Parsing large files can take several seconds or more. By default, -@semantic{} automatically caches parse trees by saving them in your -@file{.emacs.d} directory. When you revisit a previously-parsed file, -the parse tree is automatically reloaded from this cache, to save -time. @xref{SemanticDB}. - -@node Using Semantic -@chapter Using Semantic - -@include sem-user.texi - -@node Semantic Internals -@chapter Semantic Internals - -This chapter provides an overview of the internals of @semantic{}. -This information is usually not needed by application developers or -grammar developers; it is useful mostly for the hackers who would like -to learn more about how @semantic{} works. - -@menu -* Parser code :: Code used for the parsers -* Tag handling :: Code used for manipulating tags -* Semanticdb Internals :: Code used in the semantic database -* Analyzer Internals :: Code used in the code analyzer -* Tools :: Code used in user tools -* Tests :: Code used for testing -@end menu - -@node Parser code -@section Parser code - -@semantic{} parsing code is spread across a range of files. - -@table @file -@item semantic.el -The core infrastructure sets up buffers for parsing, and has all the -core parsing routines. Most parsing routines are overloadable, so the -actual implementation may be somewhere else. - -@item semantic-edit.el -Incremental reparse based on user edits. - -@item semantic-grammar.el -@itemx semantic-grammar.wy -Parser for the different grammar languages, and a major mode for -editing grammars in Emacs. - -@item semantic-lex.el -Infrastructure for implementing lexical analyzers. Provides macros -for creating individual analyzers for specific features, and a way to -combine them together. - -@item semantic-lex-spp.el -Infrastructure for a lexical symbolic preprocessor. This was written -to implement the C preprocessor, but could be used for other lexical -preprocessors. - -@item bovine/bovine-grammar.el -@itemx bovine/bovine-grammar-macros.el -@itemx bovine/semantic-bovine.el -The ``bovine'' grammar. This is the first grammar mode written for -@semantic{} and is useful for simple creating simple parsers. - -@item wisent/wisent.el -@itemx wisent/bison-wisent.el -@itemx wisent/semantic-wisent.el -@itemx wisent/semantic-debug-grammar.el -A port of bison to Emacs. This infrastructure lets you create LALR -based parsers for @semantic{}. - -@item semantic-ast.el -Manage Abstract Syntax Trees for parsers. - -@item semantic-debug.el -Infrastructure for debugging grammars. - -@item semantic-util.el -Various utilities for manipulating tags, such as describing the tag -under point, adding labels, and the all important -@code{semantic-something-to-tag-table}. - -@end table - -@node Tag handling -@section Tag handling - -A tag represents an individual item found in a buffer, such as a -function or variable. Tag handling is handled in several source -files. - -@table @file -@item semantic-tag.el -Basic tag creation, queries, cloning, binding, and unbinding. - -@item semantic-tag-write.el -Write a tag or tag list to a stream. These routines are used by -@file{semanticdb-file.el} when saving a list of tags. - -@item semantic-tag-file.el -Files associated with tags. Goto-tag, file for include, and file for -a prototype. - -@item semantic-tag-ls.el -Language dependent features of a tag, such as parent calculation, slot -protection, and other states like abstract, virtual, static, and leaf. - -@item semantic-dep.el -Include file handling. Contains the include path concepts, and -routines for looking up file names in the include path. - -@item semantic-format.el -Convert a tag into a nicely formatted and colored string. Use -@code{semantic-test-all-format-tag-functions} to test different output -options. - -@item semantic-find.el -Find tags matching different conditions in a tag table. -These routines are used by @file{semanticdb-find.el} once the database -has been converted into a simpler tag table. - -@item semantic-sort.el -Sorting lists of tags in different ways. Includes sorting a plain -list of tags forward or backward. Includes binning tags based on -attributes (bucketize), and tag adoption for multiple references to -the same thing. - -@item semantic-doc.el -Capture documentation comments from near a tag. - -@end table - -@node Semanticdb Internals -@section Semanticdb Internals - -@acronym{Semanticdb} complexity is certainly an issue. It is a rather -hairy problem to try and solve. - -@table @file -@item semanticdb.el -Defines a @dfn{database} and a @dfn{table} base class. You can -instantiate these classes, and use them, but they are not persistent. - -This file also provides support for @code{semanticdb-minor-mode}, -which automatically associates files with tables in databases so that -tags are @emph{saved} while a buffer is not in memory. - -The database and tables both also provide applicable cache information, -and cache flushing system. The semanticdb search routines use caches -to save datastructures that are complex to calculate. - -Lastly, it provides the concept of @dfn{project root}. It is a system -by which a file can be associated with the root of a project, so if -you have a tree of directories and source files, it can find the root, -and allow a tag-search to span all available databases in that -directory hierarchy. - -@item semanticdb-file.el -Provides a subclass of the basic table so that it can be saved to -disk. Implements all the code needed to unbind/rebind tags to a -buffer and writing them to a file. - -@item semanticdb-el.el -Implements a special kind of @dfn{system} database that uses Emacs -internals to perform queries. - -@item semanticdb-ebrowse.el -Implements a system database that uses Ebrowse to parse files into a -table that can be queried for tag names. Successful tag hits during a -find causes @semantic{} to pick up and parse the reference files to -get the full details. - -@item semanticdb-find.el -Infrastructure for searching groups @semantic{} databases, and dealing -with the search results format. - -@item semanticdb-ref.el -Tracks crossreferences. Cross references are needed when buffer is -reparsed, and must alert other tables that any dependent caches may -need to be flushed. References are in the form of include files. - -@end table - -@node Analyzer Internals -@section Analyzer Internals - -The @semantic{} analyzer is a complex engine which has been broken -down across several modules. When the @semantic{} analyzer fails, -start with @code{semantic-analyze-debug-assist}, then dive into some -of these files. - -@table @file -@item semantic-analyze.el -The core analyzer for defining the @dfn{current context}. The -current context is an object that contains references to aspects of -the local context including the current prefix, and a tag list -defining what the prefix means. - -@item semantic-analyze-complete.el -Provides @code{semantic-analyze-possible-completions}. - -@item semantic-analyze-debug.el -The analyzer debugger. Useful when attempting to get everything -configured. - -@item semantic-analyze-fcn.el -Various support functions needed by the analyzer. - -@item semantic-ctxt.el -Local context parser. Contains overloadable functions used to move -around through different scopes, get local variables, and collect the -current prefix used when doing completion. - -@item semantic-scope.el -Calculate @dfn{scope} for a location in a buffer. The scope includes -local variables, and tag lists in scope for various reasons, such as -C++ using statements. - -@item semanticdb-typecache.el -The typecache is part of @code{semanticdb}, but is used primarily by -the analyzer to look up datatypes and complex names. The typecache is -bound across source files and builds a master lookup table for data -type names. - -@item semantic-ia.el -Interactive Analyzer functions. Simple routines that do completion or -lookups based on the results from the Analyzer. These routines are -meant as examples for application writers, but are quite useful as -they are. - -@item semantic-ia-sb.el -Speedbar support for the analyzer, displaying context info, and -completion lists. - -@end table - -@node Tools -@section Tools - -These files contain various tools a user can use. - -@table @file -@item semantic-idle.el -Idle scheduler for @semantic{}. Manages reparsing buffers after -edits, and large work tasks in idle time. Includes modes for showing -summary help and pop-up completion. - -@item senator.el -The @semantic{} navigator. Provides many ways to move through a -buffer based on the active tag table. - -@item semantic-decorate.el -A minor mode for decorating tags based on details from the parser. -Includes overlines for functions, or coloring class fields based on -protection. - -@item semantic-decorate-include.el -A decoration mode for include files, which assists users in setting up -parsing for their includes. - -@item semantic-complete.el -Advanced completion prompts for reading tag names in the minibuffer, or -inline in a buffer. - -@item semantic-imenu.el -Imenu support for using @semantic{} tags in imenu. - -@item semantic-mru-bookmark.el -Automatic bookmarking based on tags. Jump to locations you've been -before based on tag name. - -@item semantic-sb.el -Support for @semantic{} tag usage in Speedbar. - -@item semantic-util-modes.el -A bunch of small minor-modes that exposes aspects of the semantic -parser state. Includes @code{semantic-stickyfunc-mode}. - -@item document.el -@itemx document-vars.el -Create an update comments for tags. - -@item semantic-adebug.el -Extensions of @file{data-debug.el} for @semantic{}. - -@item semantic-chart.el -Draw some charts from stats generated from parsing. - - -@item semantic-elp.el -Profiler for helping to optimize the @semantic{} analyzer. - - -@end table - -@node Tests -@section Tests - -@table @file - -@item semantic-utest.el -Basic testing of parsing and incremental parsing for most supported -languages. - -@item semantic-ia-utest.el -Test the semantic analyzer's ability to provide smart completions. - -@item semantic-utest-c.el -Tests for the C parser's lexical pre-processor. - -@item semantic-regtest.el -Regression tests from the older Semantic 1.x API. - -@end table - -@node Glossary -@appendix Glossary - -@table @keyword -@item BNF -In semantic 1.4, a BNF file represented ``Bovine Normal Form'', the -grammar file used for the 1.4 parser generator. This was a play on -Backus-Naur Form which proved too confusing. - -@item bovinate -A verb representing what happens when a bovine parser parses a file. - -@item bovine lambda -In a bovine, or LL parser, the bovine lambda is a function to execute -when a specific set of match rules has succeeded in matching text from -the buffer. - -@item bovine parser -A parser using the bovine parser generator. It is an LL parser -suitable for small simple languages. - -@item context - -@item LALR - -@item lexer -A program which converts text into a stream of tokens by analyzing -them lexically. Lexers will commonly create strings, symbols, -keywords and punctuation, and strip whitespaces and comments. - -@item LL - -@item nonterminal -A nonterminal symbol or simply a nonterminal stands for a class of -syntactically equivalent groupings. A nonterminal symbol name is used -in writing grammar rules. - -@item overloadable -Some functions are defined via @code{define-overload}. -These can be overloaded via .... - -@item parser -A program that converts @b{tokens} to @b{tags}. - -@item tag -A tag is a representation of some entity in a language file, such as a -function, variable, or include statement. In semantic, the word tag is -used the same way it is used for the etags or ctags tools. - -A tag is usually bound to a buffer region via overlay, or it just -specifies character locations in a file. - -@item token -A single atomic item returned from a lexer. It represents some set -of characters found in a buffer. - -@item token stream -The output of the lexer as well as the input to the parser. - -@item wisent parser -A parser using the wisent parser generator. It is a port of bison to -Emacs Lisp. It is an LALR parser suitable for complex languages. -@end table - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index -@printindex cp - -@iftex -@contents -@summarycontents -@end iftex - -@bye - -@c Following comments are for the benefit of ispell. - -@c LocalWords: alist API APIs arg argc args argv asis assoc autoload Wisent -@c LocalWords: backquote bnf bovinate bovinates LALR -@c LocalWords: bovinating bovination bovinator bucketize -@c LocalWords: cb cdr charquote checkcache cindex CLOS -@c LocalWords: concat concocting const constantness ctxt Decl defcustom -@c LocalWords: deffn deffnx defun defvar destructor's dfn diff dir -@c LocalWords: doc docstring EDE EIEIO elisp emacsman emph enum -@c LocalWords: eq Exp EXPANDFULL expression fn foo func funcall -@c LocalWords: ia ids iff ifinfo imenu imenus init int isearch itemx java kbd -@c LocalWords: keymap keywordtable lang languagemode lexer lexing Ludlam -@c LocalWords: menubar metaparent metaparents min minibuffer Misc mode's -@c LocalWords: multitable NAvigaTOR noindent nomedian nonterm noselect -@c LocalWords: nosnarf obarray OLE OO outputfile paren parsetable POINT's -@c LocalWords: popup positionalonly positiononly positionormarker pre -@c LocalWords: printf printindex Programmatically pt quotemode -@c LocalWords: ref regex regexp Regexps reparse resetfile samp sb -@c LocalWords: scopestart SEmantic semanticdb setfilename setq -@c LocalWords: settitle setupfunction sexp sp SPC speedbar speedbar's -@c LocalWords: streamorbuffer struct subalist submenu submenus -@c LocalWords: subsubsection sw sym texi texinfo titlefont titlepage -@c LocalWords: tok TOKEN's toplevel typemodifiers uml unset untar -@c LocalWords: uref usedb var vskip xref yak diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi deleted file mode 100644 index 8cd2ee813ec..00000000000 --- a/doc/misc/ses.texi +++ /dev/null @@ -1,983 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/ses -@settitle SES: Simple Emacs Spreadsheet -@setchapternewpage off -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@c %**end of header - -@copying -This file documents SES: the Simple Emacs Spreadsheet. - -Copyright @copyright{} 2002-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* SES: (ses). Simple Emacs Spreadsheet. -@end direntry - -@finalout - -@titlepage -@title SES -@subtitle Simple Emacs Spreadsheet -@author Jonathan A. Yavner -@author @email{jyavner@@member.fsf.org} - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@c =================================================================== - -@ifnottex -@node Top, Sales Pitch, (dir), (dir) -@comment node-name, next, previous, up -@top SES: Simple Emacs Spreadsheet - -@display -SES is a major mode for GNU Emacs to edit spreadsheet files, which -contain a rectangular grid of cells. The cells' values are specified -by formulas that can refer to the values of other cells. -@end display -@end ifnottex - -To report bugs, send email to @email{jyavner@@member.fsf.org}. - -@insertcopying - -@menu -* Sales Pitch:: Why use SES? -* The Basics:: Basic spreadsheet commands -* Advanced Features:: Want to know more? -* For Gurus:: Want to know @emph{even more}? -* Index:: Concept, Function and Variable Index -* Acknowledgements:: Acknowledgements -* GNU Free Documentation License:: The license for this documentation. -@end menu - -@c =================================================================== - -@node Sales Pitch, The Basics, Top, Top -@comment node-name, next, previous, up -@chapter Sales Pitch -@cindex features - -@itemize @bullet -@item Create and edit simple spreadsheets with a minimum of fuss. -@item Full undo/redo/autosave. -@item Immune to viruses in spreadsheet files. -@item Cell formulas are straight Emacs Lisp. -@item Printer functions for control of cell appearance. -@item Intuitive keystroke commands: C-o = insert row, M-o = insert column, etc. -@item ``Spillover'' of lengthy cell values into following blank cells. -@item Header line shows column letters or a selected row. -@item Completing-read for entering symbols as cell values. -@item Cut, copy, and paste can transfer formulas and printer functions. -@item Import and export of tab-separated values or tab-separated formulas. -@item Plaintext, easily-hacked file format. -@end itemize - -@c =================================================================== - -@node The Basics, Advanced Features, Sales Pitch, Top -@comment node-name, next, previous, up -@chapter The Basics -@cindex basic commands -@findex ses-jump -@findex ses-mark-row -@findex ses-mark-column -@findex ses-mark-whole-buffer -@findex set-mark-command -@findex keyboard-quit - -To create a new spreadsheet, visit a nonexistent file whose name ends - with ".ses". For example, @kbd{C-x C-f test.ses RET}. - - -A @dfn{cell identifier} is a symbol with a column letter and a row -number. Cell B7 is the 2nd column of the 7th row. For very wide -spreadsheets, there are two column letters: cell AB7 is the 28th -column of the 7th row. Super wide spreadsheets get AAA1, etc. - -@table @kbd -@item j -Moves point to cell, specified by identifier (@code{ses-jump}). -@end table - -Point is always at the left edge of a cell, or at the empty endline. -When mark is inactive, the current cell is underlined. When mark is -active, the range is the highlighted rectangle of cells (SES always -uses transient mark mode). Drag the mouse from A1 to A3 to create the -range A1-A2. Many SES commands operate only on single cells, not -ranges. - -@table @kbd -@item C-SPC -@itemx C-@@ -Set mark at point (@code{set-mark-command}). - -@item C-g -Turn off the mark (@code{keyboard-quit}). - -@item M-h -Highlight current row (@code{ses-mark-row}). - -@item S-M-h -Highlight current column (@code{ses-mark-column}). - -@item C-x h -Highlight all cells (@code{mark-whole-buffer}). -@end table - -@menu -* Formulas:: -* Resizing:: -* Printer functions:: -* Clearing cells:: -* Copy/cut/paste:: -* Customizing SES:: -@end menu - -@node Formulas, Resizing, The Basics, The Basics -@section Cell formulas -@cindex formulas -@cindex formulas, entering -@findex ses-read-cell -@findex ses-read-symbol -@findex ses-edit-cell -@findex ses-recalculate-cell -@findex ses-recalculate-all - -To enter a number into the current cell, just start typing: - -@table @kbd -@item 0..9 -Self-insert a digit (@code{ses-read-cell}). - -@item - -Self-insert a negative number (@code{ses-read-cell}). - -@item . -Self-insert a fractional number (@code{ses-read-cell}). - -@item " -Self-insert a quoted string. The ending double-quote -is inserted for you (@code{ses-read-cell}). - -@item ( -Self-insert an expression. The right-parenthesis is inserted for you -(@code{ses-read-cell}). To access another cell's value, just use its -identifier in your expression. Whenever the other cell is changed, -this cell's formula will be reevaluated. While typing in the -expression, you can use @kbd{M-@key{TAB}} to complete symbol names. - -@item ' @r{(apostrophe)} -Enter a symbol (ses-read-symbol). SES remembers all symbols that have -been used as formulas, so you can type just the beginning of a symbol -and use @kbd{@key{SPC}}, @kbd{@key{TAB}}, and @kbd{?} to complete it. -@end table - -To enter something else (e.g., a vector), begin with a digit, then -erase the digit and type whatever you want. - -@table @kbd -@item RET -Edit the existing formula in the current cell (@code{ses-edit-cell}). - -@item C-c C-c -Force recalculation of the current cell or range (@code{ses-recalculate-cell}). - -@item C-c C-l -Recalculate the entire spreadsheet (@code{ses-recalculate-all}). -@end table - -@node Resizing, Printer functions, Formulas, The Basics -@section Resizing the spreadsheet -@cindex resizing spreadsheets -@findex ses-insert-row -@findex ses-insert-column -@findex ses-delete-row -@findex ses-delete-column -@findex ses-set-column-width -@findex ses-forward-or-insert -@findex ses-append-row-jump-first-column - - -Basic commands: - -@table @kbd -@item C-o -(@code{ses-insert-row}) - -@item M-o -(@code{ses-insert-column}) - -@item C-k -(@code{ses-delete-row}) - -@item M-k -(@code{ses-delete-column}) - -@item w -(@code{ses-set-column-width}) - -@item TAB -Moves point to the next rightward cell, or inserts a new column if -already at last cell on line, or inserts a new row if at endline -(@code{ses-forward-or-insert}). - -@item C-j -Linefeed inserts below the current row and moves to column A -(@code{ses-append-row-jump-first-column}). -@end table - -Resizing the spreadsheet (unless you're just changing a column width) -relocates all the cell-references in formulas so they still refer to -the same cells. If a formula mentioned B1 and you insert a new first -row, the formula will now mention B2. - -If you delete a cell that a formula refers to, the cell-symbol is -deleted from the formula, so @code{(+ A1 B1 C1)} after deleting the third -column becomes @code{(+ A1 B1)}. In case this is not what you wanted: - -@table @kbd -@item C-_ -@itemx C-x u -Undo previous action (@code{(undo)}). -@end table - - -@node Printer functions, Clearing cells, Resizing, The Basics -@section Printer functions -@cindex printer functions -@findex ses-read-cell-printer -@findex ses-read-column-printer -@findex ses-read-default-printer -@findex ses-center -@findex ses-center-span -@findex ses-dashfill -@findex ses-dashfill-span -@findex ses-tildefill-span - - -Printer functions convert binary cell values into the print forms that -Emacs will display on the screen. - -A printer can be a format string, like @samp{"$%.2f"}. The result -string is right-aligned within the print cell. To get left-alignment, -use parentheses: @samp{("$%.2f")}. A printer can also be a -one-argument function (a symbol or a lambda), whose result is a string -(right-aligned) or list of one string (left-aligned). While typing in -a lambda, you can use @kbd{M-@key{TAB}} to complete the names of symbols. - -Each cell has a printer. If @code{nil}, the column-printer for the cell's -column is used. If that is also @code{nil}, the default-printer for the -spreadsheet is used. - -@table @kbd -@item p -Enter a printer for current cell or range (@code{ses-read-cell-printer}). - -@item M-p -Enter a printer for the current column (@code{ses-read-column-printer}). - -@item C-c C-p -Enter the default printer for the spreadsheet -(@code{ses-read-default-printer}). -@end table - -The @code{ses-read-@r{XXX}-printer} commands have their own minibuffer -history, which is preloaded with the set of all printers used in this -spreadsheet, plus the standard printers. - -The standard printers are suitable only for cells, not columns or -default, because they format the value using the column-printer (or -default-printer if @code{nil}) and then center the result: - -@table @code -@item ses-center -Just centering. - -@item ses-center-span -Centering with spill-over to following blank cells. - -@item ses-dashfill -Centering using dashes (-) instead of spaces. - -@item ses-dashfill-span -Centering with dashes and spill-over. - -@item ses-tildefill-span -Centering with tildes (~) and spill-over. -@end table - - -@node Clearing cells, Copy/cut/paste, Printer functions, The Basics -@section Clearing cells -@cindex clearing commands -@findex ses-clear-cell-backward -@findex ses-clear-cell-forward - -These commands set both formula and printer to @code{nil}: - -@table @kbd -@item DEL -Clear cell and move left (@code{ses-clear-cell-backward}). - -@item C-d -Clear cell and move right (@code{ses-clear-cell-forward}). -@end table - - -@node Copy/cut/paste, Customizing SES, Clearing cells, The Basics -@section Copy, cut, and paste -@cindex copy -@cindex cut -@cindex paste -@findex kill-ring-save -@findex mouse-set-region -@findex mouse-set-secondary -@findex ses-kill-override -@findex yank -@findex clipboard-yank -@findex mouse-yank-at-click -@findex mouse-yank-at-secondary -@findex ses-yank-pop - -The copy functions work on rectangular regions of cells. You can paste the -copies into non-SES buffers to export the print text. - -@table @kbd -@item M-w -@itemx [copy] -@itemx [C-insert] -Copy the highlighted cells to kill ring and primary clipboard -(@code{kill-ring-save}). - -@item [drag-mouse-1] -Mark a region and copy it to kill ring and primary clipboard -(@code{mouse-set-region}). - -@item [M-drag-mouse-1] -Mark a region and copy it to kill ring and secondary clipboard -(@code{mouse-set-secondary}). - -@item C-w -@itemx [cut] -@itemx [S-delete] -The cut functions do not actually delete rows or columns---they copy -and then clear (@code{ses-kill-override}). - -@item C-y -@itemx [S-insert] -Paste from kill ring (@code{yank}). The paste functions behave -differently depending on the format of the text being inserted: -@itemize @bullet -@item -When pasting cells that were cut from a SES buffer, the print text is -ignored and only the attached formula and printer are inserted; cell -references in the formula are relocated unless you use @kbd{C-u}. -@item -The pasted text overwrites a rectangle of cells whose top left corner -is the current cell. If part of the rectangle is beyond the edges of -the spreadsheet, you must confirm the increase in spreadsheet size. -@item -Non-SES text is usually inserted as a replacement formula for the -current cell. If the formula would be a symbol, it's treated as a -string unless you use @kbd{C-u}. Pasted formulas with syntax errors -are always treated as strings. -@end itemize - -@item [paste] -Paste from primary clipboard or kill ring (@code{clipboard-yank}). - -@item [mouse-2] -Set point and paste from primary clipboard (@code{mouse-yank-at-click}). - -@item [M-mouse-2] -Set point and paste from secondary clipboard (@code{mouse-yank-secondary}). - -@item M-y -Immediately after a paste, you can replace the text with a preceding -element from the kill ring (@code{ses-yank-pop}). Unlike the standard -Emacs yank-pop, the SES version uses @code{undo} to delete the old -yank. This doesn't make any difference? -@end table - -@node Customizing SES, , Copy/cut/paste, The Basics -@section Customizing SES -@cindex customizing -@vindex enable-local-eval -@vindex ses-mode-hook -@vindex safe-functions -@vindex enable-local-eval - - -By default, a newly-created spreadsheet has 1 row and 1 column. The -column width is 7 and the default printer is @samp{"%.7g"}. Each of these -can be customized. Look in group ``ses''. - -After entering a cell value, point normally moves right to the next -cell. You can customize @code{ses-after-entry-functions} to move left or -up or down. For diagonal movement, select two functions from the -list. - -@code{ses-mode-hook} is a normal mode hook (list of functions to -execute when starting SES mode for a buffer). - -The variable @code{safe-functions} is a list of possibly-unsafe -functions to be treated as safe when analyzing formulas and printers. -@xref{Virus protection}. Before customizing @code{safe-functions}, -think about how much you trust the person who's suggesting this -change. The value @code{t} turns off all anti-virus protection. A -list-of-functions value might enable a ``gee whiz'' spreadsheet, but it -also creates trapdoors in your anti-virus armor. In order for virus -protection to work, you must always press @kbd{n} when presented with -a virus warning, unless you understand what the questionable code is -trying to do. Do not listen to those who tell you to customize -@code{enable-local-eval}---this variable is for people who don't wear -safety belts! - - -@c =================================================================== - -@node Advanced Features, For Gurus, The Basics, Top -@chapter Advanced Features -@cindex advanced features -@findex ses-read-header-row - - -@table @kbd -@item C-c M-C-h -(@code{ses-set-header-row}). The header line at the top of the SES -window normally shows the column letter for each column. You can set -it to show a copy of some row, such as a row of column titles, so that -row will always be visible. Default is to set the current row as the -header; use C-u to prompt for header row. Set the header to row 0 to -show column letters again. -@item [header-line mouse-3] -Pops up a menu to set the current row as the header, or revert to -column letters. -@end table - -@menu -* The print area:: -* Ranges in formulas:: -* Sorting by column:: -* Standard formula functions:: -* More on cell printing:: -* Import and export:: -* Virus protection:: -* Spreadsheets with details and summary:: -@end menu - -@node The print area, Ranges in formulas, Advanced Features, Advanced Features -@section The print area -@cindex print area -@findex widen -@findex ses-renarrow-buffer -@findex ses-reprint-all - -A SES file consists of a print area and a data area. Normally the -buffer is narrowed to show only the print area. The print area is -read-only except for special SES commands; it contains cell values -formatted by printer functions. The data area records the formula and -printer functions, etc. - -@table @kbd -@item C-x n w -Show print and data areas (@code{widen}). - -@item C-c C-n -Show only print area (@code{ses-renarrow-buffer}). - -@item S-C-l -@itemx M-C-l -Recreate print area by reevaluating printer functions for all cells -(@code{ses-reprint-all}). -@end table - -@node Ranges in formulas, Sorting by column, The print area, Advanced Features -@section Ranges in formulas -@cindex ranges -@findex ses-insert-range-click -@findex ses-insert-range -@findex ses-insert-ses-range-click -@findex ses-insert-ses-range -@vindex from -@vindex to - -A formula like -@lisp -(+ A1 A2 A3) -@end lisp -is the sum of three specific cells. If you insert a new second row, -the formula becomes -@lisp -(+ A1 A3 A4) -@end lisp -and the new row is not included in the sum. - -The macro @code{(ses-range @var{from} @var{to})} evaluates to a list of -the values in a rectangle of cells. If your formula is -@lisp -(apply '+ (ses-range A1 A3)) -@end lisp -and you insert a new second row, it becomes -@lisp -(apply '+ (ses-range A1 A4)) -@end lisp -and the new row is included in the sum. - -While entering or editing a formula in the minibuffer, you can select -a range in the spreadsheet (using mouse or keyboard), then paste a -representation of that range into your formula. Suppose you select -A1-C1: - -@table @kbd -@item [S-mouse-3] -Inserts "A1 B1 C1" @code{(ses-insert-range-click}) - -@item C-c C-r -Keyboard version (@code{ses-insert-range}). - -@item [C-S-mouse-3] -Inserts "(ses-range A1 C1)" (@code{ses-insert-ses-range-click}). - -@item C-c C-s -Keyboard version (@code{ses-insert-ses-range}). -@end table - -If you delete the @var{from} or @var{to} cell for a range, the nearest -still-existing cell is used instead. If you delete the entire range, -the formula relocator will delete the ses-range from the formula. - -If you insert a new row just beyond the end of a one-column range, or -a new column just beyond a one-row range, the new cell is included in -the range. New cells inserted just before a range are not included. - - -@node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features -@section Sorting by column -@cindex sorting -@findex ses-sort-column -@findex ses-sort-column-click - -@table @kbd -@item C-c M-C-s -Sort the cells of a range using one of the columns -(@code{ses-sort-column}). The rows (or partial rows if the range -doesn't include all columns) are rearranged so the chosen column will -be in order. - -@item [header-line mouse-2] -The easiest way to sort is to click mouse-2 on the chosen column's header row -(@code{ses-sort-column-click}). -@end table - -The sort comparison uses @code{string<}, which works well for -right-justified numbers and left-justified strings. - -With prefix arg, sort is in descending order. - -Rows are moved one at a time, with relocation of formulas. This works -well if formulas refer to other cells in their row, not so well for -formulas that refer to other rows in the range or to cells outside the -range. - - -@node Standard formula functions, More on cell printing, Sorting by column, Advanced Features -@section Standard formula functions -@cindex standard formula functions -@cindex *skip* -@cindex *error* -@findex ses-delete-blanks -@findex ses-average -@findex ses+ - -Oftentimes you want a calculation to exclude the blank cells. Here -are some useful functions to call from your formulas: - -@table @code -@item (ses-delete-blanks &rest @var{args}) -Returns a list from which all blank cells (value is either @code{nil} or -'*skip*) have been deleted. - -@item (ses+ &rest @var{args}) -Sum of non-blank arguments. - -@item (ses-average @var{list}) -Average of non-blank elements in @var{list}. Here the list is passed -as a single argument, since you'll probably use it with @code{ses-range}. -@end table - -@node More on cell printing, Import and export, Standard formula functions, Advanced Features -@section More on cell printing -@cindex cell printing, more -@findex ses-truncate-cell -@findex ses-recalculate-cell - -Special cell values: -@itemize -@item nil prints the same as "", but allows previous cell to spill over. -@item '*skip* replaces nil when the previous cell actually does spill over; -nothing is printed for it. -@item '*error* indicates that the formula signaled an error instead of -producing a value: the print cell is filled with hash marks (#). -@end itemize - -If the result from the printer function is too wide for the cell and -the following cell is @code{nil}, the result will spill over into the -following cell. Very wide results can spill over several cells. If -the result is too wide for the available space (up to the end of the -row or the next non-@code{nil} cell), the result is truncated if the cell's -value is a string, or replaced with hash marks otherwise. - -SES could get confused by printer results that contain newlines or -tabs, so these are replaced with question marks. - -@table @kbd -@item t -Confine a cell to its own column (@code{ses-truncate-cell}). This -allows you to move point to a rightward cell that would otherwise be -covered by a spill-over. If you don't change the rightward cell, the -confined cell will spill over again the next time it is reprinted. - -@item c -When applied to a single cell, this command displays in the echo area -any formula error or printer error that occurred during -recalculation/reprinting (@code{ses-recalculate-cell}). You can use -this to undo the effect of @kbd{t}. -@end table - -When a printer function signals an error, the fallback printer -@samp{"%s"} is substituted. This is useful when your column printer -is numeric-only and you use a string as a cell value. Note that the -standard default printer is ``%.7g'' which is numeric-only, so cells -that are empty of contain strings will use the fallback printer. -@kbd{c} on such cells will display ``Format specifier doesn't match -argument type''. - - -@node Import and export, Virus protection, More on cell printing, Advanced Features -@section Import and export -@cindex import and export -@cindex export, and import -@findex ses-export-tsv -@findex ses-export-tsf - -@table @kbd -@item x t -Export a range of cells as tab-separated values (@code{ses-export-tsv}). -@item x T -Export a range of cells as tab-separated formulas (@code{ses-export-tsf}). -@end table - -The exported text goes to the kill ring --- you can paste it into -another buffer. Columns are separated by tabs, rows by newlines. - -To import text, use any of the yank commands where the text to paste -contains tabs and/or newlines. Imported formulas are not relocated. - -@node Virus protection, Spreadsheets with details and summary, Import and export, Advanced Features -@section Virus protection -@cindex virus protection - -Whenever a formula or printer is read from a file or is pasted into -the spreadsheet, it receives a ``needs safety check'' marking. Later, -when the formula or printer is evaluated for the first time, it is -checked for safety using the @code{unsafep} predicate; if found to be -``possibly unsafe'', the questionable formula or printer is displayed -and you must press Y to approve it or N to use a substitute. The -substitute always signals an error. - -Formulas or printers that you type in are checked immediately for -safety. If found to be possibly unsafe and you press N to disapprove, -the action is canceled and the old formula or printer will remain. - -Besides viruses (which try to copy themselves to other files), -@code{unsafep} can also detect all other kinds of Trojan horses, such as -spreadsheets that delete files, send email, flood Web sites, alter -your Emacs settings, etc. - -Generally, spreadsheet formulas and printers are simple things that -don't need to do any fancy computing, so all potentially-dangerous -parts of the Emacs Lisp environment can be excluded without cramping -your style as a formula-writer. See the documentation in @file{unsafep.el} -for more info on how Lisp forms are classified as safe or unsafe. - -@node Spreadsheets with details and summary, , Virus protection, Advanced Features -@section Spreadsheets with details and summary -@cindex details and summary -@cindex summary, and details - -A common organization for spreadsheets is to have a bunch of ``detail'' -rows, each perhaps describing a transaction, and then a set of -``summary'' rows that each show reduced data for some subset of the -details. SES supports this organization via the @code{ses-select} -function. - -@table @code -@item (ses-select @var{fromrange} @var{test} @var{torange}) -Returns a subset of @var{torange}. For each member in @var{fromrange} -that is equal to @var{test}, the corresponding member of @var{torange} -is included in the result. -@end table - -Example of use: -@lisp -(ses-average (ses-select (ses-range A1 A5) 'Smith (ses-range B1 B5))) -@end lisp -This computes the average of the B column values for those rows whose -A column value is the symbol 'Smith. - -Arguably one could specify only @var{fromrange} plus -@var{to-row-offset} and @var{to-column-offset}. The @var{torange} is -stated explicitly to ensure that the formula will be recalculated if -any cell in either range is changed. - -File @file{etc/ses-example.el} in the Emacs distribution is an example of a -details-and-summary spreadsheet. - - -@c =================================================================== - -@node For Gurus, Index, Advanced Features, Top -@chapter For Gurus -@cindex advanced features - -@menu -* Deferred updates:: -* Nonrelocatable references:: -* The data area:: -* Buffer-local variables in spreadsheets:: -* Uses of defadvice in SES:: -@end menu - -@node Deferred updates, Nonrelocatable references, For Gurus, For Gurus -@section Deferred updates -@cindex deferred updates -@cindex updates, deferred -@vindex run-with-idle-timer - -To save time by avoiding redundant computations, cells that need -recalculation due to changes in other cells are added to a set. At -the end of the command, each cell in the set is recalculated once. -This can create a new set of cells that need recalculation. The -process is repeated until either the set is empty or it stops changing -(due to circular references among the cells). In extreme cases, you -might see progress messages of the form ``Recalculating... (@var{nnn} -cells left)''. If you interrupt the calculation using @kbd{C-g}, the -spreadsheet will be left in an inconsistent state, so use @kbd{C-_} or -@kbd{C-c C-l} to fix it. - -To save even more time by avoiding redundant writes, cells that have -changes are added to a set instead of being written immediately to the -data area. Each cell in the set is written once, at the end of the -command. If you change vast quantities of cells, you might see a -progress message of the form ``Writing... (@var{nnn} cells left)''. -These deferred cell-writes cannot be interrupted by @kbd{C-g}, so -you'll just have to wait. - -SES uses @code{run-with-idle-timer} to move the cell underline when -Emacs will be scrolling the buffer after the end of a command, and -also to narrow and underline after @kbd{C-x C-v}. This is visible as -a momentary glitch after C-x C-v and certain scrolling commands. You -can type ahead without worrying about the glitch. - - -@node Nonrelocatable references, The data area, Deferred updates, For Gurus -@section Nonrelocatable references -@cindex nonrelocatable references -@cindex references, nonrelocatable - -@kbd{C-y} relocates all cell-references in a pasted formula, while -@kbd{C-u C-y} relocates none of the cell-references. What about mixed -cases? - -You can use -@lisp -(symbol-value 'B3) -@end lisp -to make an @dfn{absolute reference}. The formula relocator skips over -quoted things, so this will not be relocated when pasted or when -rows/columns are inserted/deleted. However, B3 will not be recorded -as a dependency of this cell, so this cell will not be updated -automatically when B3 is changed. - -The variables @code{row} and @code{col} are dynamically bound while a -cell formula is being evaluated. You can use -@lisp -(ses-cell-value row 0) -@end lisp -to get the value from the leftmost column in the current row. This -kind of dependency is also not recorded. - - -@node The data area, Buffer-local variables in spreadsheets, Nonrelocatable references, For Gurus -@section The data area -@cindex data area -@findex ses-reconstruct-all - -Begins with an 014 character, followed by sets of cell-definition -macros for each row, followed by column-widths, column-printers, -default-printer, and header-row. Then there's the global parameters -(file-format ID, numrows, numcols) and the local variables (specifying -SES mode for the buffer, etc.) - -When a SES file is loaded, first the numrows and numcols values are -loaded, then the entire data area is @code{eval}ed, and finally the local -variables are processed. - -You can edit the data area, but don't insert or delete any newlines -except in the local-variables part, since SES locates things by -counting newlines. Use @kbd{C-x C-e} at the end of a line to install -your edits into the spreadsheet data structures (this does not update -the print area, use e.g. @kbd{C-c C-l} for that). - -The data area is maintained as an image of spreadsheet data -structures that area stored in buffer-local variables. If the data -area gets messed up, you can try reconstructing the data area from the -data structures: - -@table @kbd -@item C-c M-C-l -(@code{ses-reconstruct-all}). -@end table - - -@node Buffer-local variables in spreadsheets, Uses of defadvice in SES, The data area, For Gurus -@section Buffer-local variables in spreadsheets -@cindex buffer-local variables -@cindex variables, buffer-local - -You can add additional local variables to the list at the bottom of -the data area, such as hidden constants you want to refer to in your -formulas. - -You can override the variable @code{ses--symbolic-formulas} to be a list of -symbols (as parenthesized strings) to show as completions for the ' -command. This initial completions list is used instead of the actual -set of symbols-as-formulas in the spreadsheet. - -For an example of this, see file @file{etc/ses-example.ses}. - -If (for some reason) you want your formulas or printers to save data -into variables, you must declare these variables as buffer-locals in -order to avoid a virus warning. - -You can define functions by making them values for the fake local -variable @code{eval}. Such functions can then be used in your -formulas and printers, but usually each @code{eval} is presented to -the user during file loading as a potential virus --- this can get -annoying. - -You can define functions in your @file{.emacs} file. Other people can -still read the print area of your spreadsheet, but they won't be able -to recalculate or reprint anything that depends on your functions. To -avoid virus warnings, each function used in a formula needs -@lisp -(put 'your-function-name 'safe-function t) -@end lisp - -@node Uses of defadvice in SES, , Buffer-local variables in spreadsheets, For Gurus -@section Uses of defadvice in SES -@cindex defadvice -@cindex undo-more -@cindex copy-region-as-kill -@cindex yank - -@table @code -@item undo-more -Defines a new undo element format (@var{fun} . @var{args}), which -means ``undo by applying @var{fun} to @var{args}''. For spreadsheet -buffers, it allows undos in the data area even though that's outside -the narrowing. - -@item copy-region-as-kill -When copying from the print area of a spreadsheet, treat the region as -a rectangle and attach each cell's formula and printer as 'ses -properties. - -@item yank -When yanking into the print area of a spreadsheet, first try to yank -as cells (if the yank text has 'ses properties), then as tab-separated -formulas, then (if all else fails) as a single formula for the current -cell. -@end table - -@c =================================================================== -@node Index, Acknowledgements, For Gurus, Top -@unnumbered Index - -@printindex cp - -@c =================================================================== - -@node Acknowledgements, GNU Free Documentation License, Index, Top -@chapter Acknowledgements - -Coding by: -@quotation -Jonathan Yavner @email{jyavner@@member.fsf.org}@* -Stefan Monnier @email{monnier@@gnu.org}@* -Shigeru Fukaya @email{shigeru.fukaya@@gmail.com} -@end quotation - -@noindent -Texinfo manual by: -@quotation -Jonathan Yavner @email{jyavner@@member.fsf.org}@* -Brad Collins -@end quotation - -@noindent -Ideas from: -@quotation -Christoph Conrad @email{christoph.conrad@@gmx.de}@* -CyberBob @email{cyberbob@@redneck.gacracker.org}@* -Syver Enstad @email{syver-en@@online.no}@* -Ami Fischman @email{fischman@@zion.bpnetworks.com}@* -Thomas Gehrlein @email{Thomas.Gehrlein@@t-online.de}@* -Chris F.A. Johnson @email{c.f.a.johnson@@rogers.com}@* -Yusong Li @email{lyusong@@hotmail.com}@* -Juri Linkov @email{juri@@jurta.org}@* -Harald Maier @email{maierh@@myself.com}@* -Alan Nash @email{anash@@san.rr.com}@* -François Pinard @email{pinard@@iro.umontreal.ca}@* -Pedro Pinto @email{ppinto@@cs.cmu.edu}@* -Stefan Reichör @email{xsteve@@riic.at}@* -Oliver Scholz @email{epameinondas@@gmx.de}@* -Richard M. Stallman @email{rms@@gnu.org}@* -Luc Teirlinck @email{teirllm@@dms.auburn.edu}@* -J. Otto Tennant @email{jotto@@pobox.com}@* -Jean-Philippe Theberge @email{jphil@@acs.pagesjaunes.fr} -@end quotation - -@c =================================================================== - -@node GNU Free Documentation License, , Acknowledgements, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@bye diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi deleted file mode 100644 index d13f25c2a55..00000000000 --- a/doc/misc/sieve.texi +++ /dev/null @@ -1,361 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@include gnus-overrides.texi - -@setfilename ../../info/sieve -@settitle Emacs Sieve Manual -@synindex fn cp -@synindex vr cp -@synindex pg cp - -@copying -This file documents the Emacs Sieve package, for server-side mail filtering. - -Copyright @copyright{} 2001-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* Sieve: (sieve). Managing Sieve scripts in Emacs. -@end direntry -@iftex -@finalout -@end iftex -@setchapternewpage odd - -@titlepage -@ifset WEBHACKDEVEL -@title Emacs Sieve Manual (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title Emacs Sieve Manual -@end ifclear - -@author by Simon Josefsson -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@node Top -@top Sieve Support for Emacs - -This is intended as a users manual for Sieve Mode and Manage Sieve, and -as a reference manual for the @samp{sieve-manage} protocol Emacs Lisp -API. - -Sieve is a language for server-side filtering of mail. The language -is documented in RFC 3028. This manual does not attempt to document -the language, so keep RFC 3028 around. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Installation:: Getting ready to use the package. -* Sieve Mode:: Editing Sieve scripts. -* Managing Sieve:: Managing Sieve scripts on a remote server. -* Examples :: A few Sieve code snippets. -* Manage Sieve API :: Interfacing to the Manage Sieve Protocol API. -* Standards:: A summary of RFCs and working documents used. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Function and variable index. -@end menu - - -@node Installation -@chapter Installation -@cindex Install -@cindex Setup - -The Sieve package should come with your Emacs version, and should be -ready for use directly. - -However, to manually set up the package you can put the following -commands in your @code{~/.emacs}: - -@lisp -(autoload 'sieve-mode "sieve-mode") -@end lisp -@lisp -(setq auto-mode-alist (cons '("\\.s\\(v\\|iv\\|ieve\\)\\'" . sieve-mode) - auto-mode-alist)) -@end lisp - - -@node Sieve Mode -@chapter Sieve Mode - -Sieve mode provides syntax-based indentation, font-locking support and -other handy functions to make editing Sieve scripts easier. - -Use @samp{M-x sieve-mode} to switch to this major mode. This command -runs the hook @code{sieve-mode-hook}. - -@vindex sieve-mode-map -@vindex sieve-mode-syntax-table -Sieve mode is derived from @code{c-mode}, and is very similar except -for the syntax of comments. The keymap (@code{sieve-mode-map}) is -inherited from @code{c-mode}, as are the variables for customizing -indentation. Sieve mode has its own abbrev table -(@code{sieve-mode-abbrev-table}) and syntax table -(@code{sieve-mode-syntax-table}). - -In addition to the editing utility functions, Sieve mode also contains -bindings to manage Sieve scripts remotely. @xref{Managing Sieve}. - -@table @kbd - -@item C-c RET -@kindex C-c RET -@findex sieve-manage -@cindex manage remote sieve script -Open a connection to a remote server using the Managesieve protocol. - -@item C-c C-l -@kindex C-c C-l -@findex sieve-upload -@cindex upload sieve script -Upload the Sieve script to the currently open server. - -@end table - - -@node Managing Sieve -@chapter Managing Sieve - -Manage Sieve is a special mode used to display Sieve scripts available -on a remote server. It can be invoked with @kbd{M-x sieve-manage -RET}, which queries the user for a server and if necessary, user -credentials to use. - -When a server has been successfully contacted, the Manage Sieve buffer -looks something like: - -@example -Server : mailserver:2000 - -2 scripts on server, press RET on a script name edits it, or -press RET on to create a new script. - - ACTIVE .sieve - template.siv -@end example - -One of the scripts are highlighted, and standard point navigation -commands (@kbd{}, @kbd{} etc) can be used to navigate the -list. - -The following commands are available in the Manage Sieve buffer: - -@table @kbd - -@item m -@kindex m -@findex sieve-activate -Activates the currently highlighted script. - -@item u -@kindex u -@findex sieve-deactivate -Deactivates the currently highlighted script. - -@item C-M-? -@kindex C-M-? -@findex sieve-deactivate-all -Deactivates all scripts. - -@item r -@kindex r -@findex sieve-remove -Remove currently highlighted script. - -@item RET -@item mouse-2 -@item f -@kindex RET -@kindex mouse-2 -@kindex f -@findex sieve-edit-script -Bury the server buffer and download the currently highlighted script -into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}). - -@item o -@kindex o -@findex sieve-edit-script-other-window -Create a new buffer in another window containing the currently -highlighted script for editing in Sieve mode (@pxref{Sieve Mode}). - -@item q -@kindex q -@findex sieve-bury-buffer -Bury the Manage Sieve buffer without closing the connection. - -@item ? -@item h -@kindex ? -@kindex h -@findex sieve-help -Displays help in the minibuffer. - -@end table - -@node Examples -@chapter Examples - -If you are not familiar with Sieve, this chapter contains a few simple -code snippets that you can cut'n'paste and modify at will, until you -feel more comfortable with the Sieve language to write the rules from -scratch. - -The following complete Sieve script places all messages with a matching -@samp{Sender:} header into the given mailbox. Many mailing lists uses -this format. The first line makes sure your Sieve server understands -the @code{fileinto} command. - -@example -require "fileinto"; - -if address "sender" "owner-w3-beta@@xemacs.org" @{ - fileinto "INBOX.w3-beta"; -@} -@end example - -A few mailing lists do not use the @samp{Sender:} header, but has a -unique identifier in some other header. The following is not a -complete script, it assumes that @code{fileinto} has already been -required. - -@example -if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{ - fileinto "INBOX.auc-tex"; -@} -@end example - -At last, we have the hopeless mailing lists that does not have any -unique identifier and you are forced to match on the @samp{To:} and -@samp{Cc} headers. As before, this snippet assumes that @code{fileinto} -has been required. - -@example -if address ["to", "cc"] "kerberos@@mit.edu" @{ - fileinto "INBOX.kerberos"; -@} -@end example - -@node Manage Sieve API -@chapter Manage Sieve API - -The @file{sieve-manage.el} library contains low-level functionality -for talking to a server with the @sc{managesieve} protocol. - -A number of user-visible variables exist, which all can be customized -in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}): - -@table @code - -@item sieve-manage-default-port -@vindex sieve-manage-default-port -Sets the default port to use, the suggested port number is @code{2000}. - -@item sieve-manage-log -@vindex sieve-manage-log -If non-@code{nil}, should be a string naming a buffer where a protocol trace -is dumped (for debugging purposes). - -@end table - -The API functions include: - -@table @code - -@item sieve-manage-open -@findex sieve-manage-open -Open connection to managesieve server, returning a buffer to be used -by all other API functions. - -@item sieve-manage-opened -@findex sieve-manage-opened -Check if a server is open or not. - -@item sieve-manage-close -@findex sieve-manage-close -Close a server connection. - -@item sieve-manage-authenticate -@findex sieve-manage-authenticate -Authenticate to the server. - -@item sieve-manage-capability -@findex sieve-manage-capability -Return a list of capabilities the server supports. - -@item sieve-manage-listscripts -@findex sieve-manage-listscripts -List scripts on the server. - -@item sieve-manage-havespace -@findex sieve-manage-havespace -Return non-@code{nil} if the server has room for a script of given -size. - -@item sieve-manage-getscript -@findex sieve-manage-getscript -Download script from server. - -@item sieve-manage-putscript -@findex sieve-manage-putscript -Upload script to server. - -@item sieve-manage-setactive -@findex sieve-manage-setactive -Indicate which script on the server should be active. - -@end table - -@node Standards -@chapter Standards - -The Emacs Sieve package implements all or parts of a small but -hopefully growing number of RFCs and drafts documents. This chapter -lists the relevant ones. They can all be fetched from -@uref{http://quimby.gnus.org/notes/}. - -@table @dfn - -@item RFC3028 -Sieve: A Mail Filtering Language. - -@item draft-martin-managesieve-03 -A Protocol for Remotely Managing Sieve Scripts - -@end table - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index -@printindex cp - -@bye - -@c End: diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi deleted file mode 100644 index 4e4df3f0bbb..00000000000 --- a/doc/misc/smtpmail.texi +++ /dev/null @@ -1,444 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/smtpmail -@settitle Emacs SMTP Library -@syncodeindex vr fn -@copying -Copyright @copyright{} 2003-2012 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs lisp libraries -@direntry -* SMTP: (smtpmail). Emacs library for sending mail via SMTP. -@end direntry - -@titlepage -@title{Emacs SMTP Library} -@subtitle{An Emacs package for sending mail via SMTP} -@author{Simon Josefsson, Alex Schroeder} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Emacs SMTP Library - -@insertcopying -@end ifnottex - -@menu -* How Mail Works:: Brief introduction to mail concepts. -* Emacs Speaks SMTP:: How to use the SMTP library in Emacs. -* Authentication:: Authenticating yourself to the server. -* Encryption:: Protecting your connection to the server. -* Queued delivery:: Sending mail without an internet connection. -* Server workarounds:: Mail servers with special requirements. -* Debugging:: Tracking down problems. -* GNU Free Documentation License:: The license for this documentation. - -Indices - -* Index:: Index over variables and functions. -@end menu - -@node How Mail Works -@chapter How Mail Works - -@cindex SMTP -@cindex MTA - On the internet, mail is sent from mail host to mail host using the -simple mail transfer protocol (SMTP). To send and receive mail, you -must get it from and send it to a mail host. Every mail host runs a -mail transfer agent (MTA) such as Exim that accepts mails and passes -them on. The communication between a mail host and other clients does -not necessarily involve SMTP, however. Here is short overview of what -is involved. - -@cindex MUA - The mail program --- also called a mail user agent (MUA) --- -usually sends outgoing mail to a mail host. When your computer is -permanently connected to the internet, it might even be a mail host -itself. In this case, the MUA will pipe mail to the -@file{/usr/lib/sendmail} application. It will take care of your mail -and pass it on to the next mail host. - -@cindex ISP - When you are only connected to the internet from time to time, your -internet service provider (ISP) has probably told you which mail host -to use. You must configure your MUA to use that mail host. Since you -are reading this manual, you probably want to configure Emacs to use -SMTP to send mail to that mail host. More on that in the next -section. - -@cindex MDA - Things are different when reading mail. The mail host responsible -for your mail keeps it in a file somewhere. The messages get into the -file by way of a mail delivery agent (MDA) such as procmail. These -delivery agents often allow you to filter and munge your mails before -you get to see it. When your computer is that mail host, this file is -called a spool, and sometimes located in the directory -@file{/var/spool/mail/}. All your MUA has to do is read mail from the -spool, then. - -@cindex POP3 -@cindex IMAP - When your computer is not always connected to the internet, you -must get the mail from the remote mail host using a protocol such as -POP3 or IMAP. POP3 essentially downloads all your mail from the mail -host to your computer. The mail is stored in some file on your -computer, and again, all your MUA has to do is read mail from the -spool. - - When you read mail from various machines, downloading mail from the -mail host to your current machine is not convenient. In that case, -you will probably want to use the IMAP protocol. Your mail is kept on -the mail host, and you can read it while you are connected via IMAP to -the mail host. - -@cindex Webmail - So how does reading mail via the web work, you ask. In that case, -the web interface just allows you to remote-control a MUA on the web -host. Whether the web host is also a mail host, and how all the -pieces interact is completely irrelevant. You usually cannot use -Emacs to read mail via the web, unless you use software that parses -the ever-changing HTML of the web interface. - -@node Emacs Speaks SMTP -@chapter Emacs Speaks SMTP - - Emacs includes a package for sending your mail to a SMTP server and -have it take care of delivering it to the final destination, rather -than letting the MTA on your local system take care of it. This can -be useful if you don't have a MTA set up on your host, or if your -machine is often disconnected from the internet. - - Sending mail via SMTP requires configuring your mail user agent -(@pxref{Mail Methods,,,emacs}) to use the SMTP library. If you -have not configured anything, then in Emacs 24.1 and later the first -time you try to send a mail Emacs will ask how you want to send -mail. To use this library, answer @samp{smtp} when prompted. Emacs -then asks for the name of the SMTP server. - - If you prefer, or if you are using a non-standard mail user agent, -you can configure this yourself. The normal way to do this is to set -the variable @code{send-mail-function} (@pxref{Mail -Sending,,,emacs}) to the value you want to use. To use this library: - -@smallexample -(setq send-mail-function 'smtpmail-send-it) -@end smallexample - -@noindent -The default value for this variable is @code{sendmail-query-once}, -which interactively asks how you want to send mail. - -Your mail user agent might use a different variable for this purpose. -It should inherit from @code{send-mail-function}, but if it does not, -or if you prefer, you can set that variable directly. Consult your -mail user agent's documentation for more details. For example, -(@pxref{Mail Variables,,,message}). - - Before using SMTP you must find out the hostname of the SMTP server -to use. Your system administrator or mail service provider should -supply this information. Often it is some variant of the server you -receive mail from. If your email address is -@samp{yourname@@example.com}, then the name of the SMTP server is -may be something like @samp{smtp.example.com}. - -@table @code -@item smtpmail-smtp-server -@vindex smtpmail-smtp-server -@vindex SMTPSERVER - The variable @code{smtpmail-smtp-server} controls the hostname of -the server to use. It is a string with an IP address or hostname. It -defaults to the contents of the @env{SMTPSERVER} environment -variable, or, if empty, the contents of -@code{smtpmail-default-smtp-server}. - -@item smtpmail-default-smtp-server -@vindex smtpmail-default-smtp-server - The variable @code{smtpmail-default-smtp-server} controls the -default hostname of the server to use. It is a string with an IP -address or hostname. It must be set before the SMTP library is -loaded. It has no effect if set after the SMTP library has been -loaded, or if @code{smtpmail-smtp-server} is defined. It is usually -set by system administrators in a site wide initialization file. -@end table - -The following example illustrates what you could put in -@file{~/.emacs} to set the SMTP server name. - -@example -;; Send mail using SMTP via mail.example.org. -(setq smtpmail-smtp-server "mail.example.org") -@end example - -@cindex Mail Submission -SMTP is normally used on the registered ``smtp'' TCP service port 25. -Some environments use SMTP in ``Mail Submission'' mode, which uses -port 587. Using other ports is not uncommon, either for security by -obscurity purposes, port forwarding, or otherwise. - -@table @code -@item smtpmail-smtp-service -@vindex smtpmail-smtp-service - The variable @code{smtpmail-smtp-service} controls the port on the -server to contact. It is either a string, in which case it will be -translated into an integer using system calls, or an integer. -@end table - -The following example illustrates what you could put in -@file{~/.emacs} to set the SMTP service port. - -@example -;; Send mail using SMTP on the mail submission port 587. -(setq smtpmail-smtp-service 587) -@end example - -@node Authentication -@chapter Authentication - -@cindex password -@cindex user name -Most SMTP servers require clients to authenticate themselves before -they are allowed to send mail. Authentication usually involves -supplying a user name and password. - -If you have not configured anything, then the first time you try to -send mail via a server, Emacs (version 24.1 and later) prompts you -for the user name and password to use, and then offers to save the -information. By default, Emacs stores authentication information in -a file @file{~/.authinfo}. - -@cindex authinfo -The basic format of the @file{~/.authinfo} file is one line for each -set of credentials. Each line consists of pairs of variables and -values. A simple example would be: - -@smallexample -machine mail.example.org port 25 login myuser password mypassword -@end smallexample - -@noindent -This specifies that when using the SMTP server called @samp{mail.example.org} -on port 25, Emacs should send the user name @samp{myuser} and the -password @samp{mypassword}. Either or both of the login and password -fields may be absent, in which case Emacs prompts for the information -when you try to send mail. (This replaces the old -@code{smtpmail-auth-credentials} variable used prior to Emacs 24.1.) - -@vindex smtpmail-smtp-user - When the SMTP library connects to a host on a certain port, it -searches the @file{~/.authinfo} file for a matching entry. If an -entry is found, the authentication process is invoked and the -credentials are used. If the variable @code{smtpmail-smtp-user} is -set to a non-@code{nil} value, then only entries for that user are -considered. For more information on the @file{~/.authinfo} -file, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. - -@cindex SASL -@cindex CRAM-MD5 -@cindex PLAIN -@cindex LOGIN -The process by which the SMTP library authenticates you to the server -is known as ``Simple Authentication and Security Layer'' (SASL). -There are various SASL mechanisms, and this library supports three of -them: CRAM-MD5, PLAIN, and LOGIN. It tries each of them, in that order, -until one succeeds. The first uses a form of encryption to obscure -your password, while the other two do not. - - -@node Encryption -@chapter Encryption - -@cindex STARTTLS -@cindex TLS -@cindex SSL -For greater security, you can encrypt your connection to the SMTP -server. If this is to work, both Emacs and the server must support it. - -The SMTP library supports the ``Transport Layer Security'' (TLS), and -the older ``Secure Sockets Layer'' (SSL) encryption mechanisms. -It also supports STARTTLS, which is a variant of TLS in which the -initial connection to the server is made in plain text, requesting a -switch to an encrypted channel for the rest of the process. - -@vindex smtpmail-stream-type -The variable @code{smtpmail-stream-type} controls what form of -connection the SMTP library uses. The default value is @code{nil}, -which means to use a plain connection, but try to switch to a STARTTLS -encrypted connection if the server supports it. Other possible values -are: @code{starttls} - insist on STARTTLS; @code{ssl} - use TLS/SSL; -and @code{plain} - no encryption. - -Use of any form of TLS/SSL requires support in Emacs. You can either -use the built-in support (in Emacs 24.1 and later), or the -@file{starttls.el} Lisp library. The built-in support uses the GnuTLS -@footnote{@url{http://www.gnu.org/software/gnutls/}} library. -If your Emacs has GnuTLS support built-in, the function -@code{gnutls-available-p} is defined and returns non-@code{nil}. -Otherwise, you must use the @file{starttls.el} library (see that file for -more information on customization options, etc.). The Lisp library -requires one of the following external tools to be installed: - -@enumerate -@item -The GnuTLS command line tool @samp{gnutls-cli}, which you can get from -@url{http://www.gnu.org/software/gnutls/}. This is the recommended -tool, mainly because it can verify server certificates. - -@item -The @samp{starttls} external program, which you can get from -@file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}. -@end enumerate - -@cindex certificates -@cindex keys -The SMTP server may also request that you verify your identity by -sending a certificate and the associated encryption key to the server. -If you need to do this, you can use an @file{~/.authinfo} entry like this: - -@smallexample -machine mail.example.org port 25 key "~/.my_smtp_tls.key" cert "~/.my_smtp_tls.cert" -@end smallexample - -@noindent -(This replaces the old @code{smtpmail-starttls-credentials} variable used -prior to Emacs 24.1.) - - -@node Queued delivery -@chapter Queued delivery - -@cindex Dialup connection -If you connect to the internet via a dialup connection, or for some -other reason don't have permanent internet connection, sending mail -will fail when you are not connected. The SMTP library implements -queued delivery, and the following variable control its behavior. - -@table @code -@item smtpmail-queue-mail -@vindex smtpmail-queue-mail - The variable @code{smtpmail-queue-mail} controls whether a simple -off line mail sender is active. This variable is a boolean, and -defaults to @code{nil} (disabled). If this is non-@code{nil}, mail is -not sent immediately but rather queued in the directory -@code{smtpmail-queue-dir} and can be later sent manually by invoking -@code{smtpmail-send-queued-mail} (typically when you connect to the -internet). - -@item smtpmail-queue-dir -@vindex smtpmail-queue-dir - The variable @code{smtpmail-queue-dir} specifies the name of the -directory to hold queued messages. It defaults to -@file{~/Mail/queued-mail/}. -@end table - -@findex smtpmail-send-queued-mail - The function @code{smtpmail-send-queued-mail} can be used to send -any queued mail when @code{smtpmail-queue-mail} is enabled. It is -typically invoked interactively with @kbd{M-x -smtpmail-send-queued-mail RET} when you are connected to the internet. - -@node Server workarounds -@chapter Server workarounds - -Some SMTP servers have special requirements. The following variables -implement support for common requirements. - -@table @code - -@item smtpmail-local-domain -@vindex smtpmail-local-domain - The variable @code{smtpmail-local-domain} controls the hostname sent -in the first @code{EHLO} or @code{HELO} command sent to the server. -It should only be set if the @code{system-name} function returns a -name that isn't accepted by the server. Do not set this variable -unless your server complains. - -@item smtpmail-sendto-domain -@vindex smtpmail-sendto-domain - The variable @code{smtpmail-sendto-domain} makes the SMTP library -add @samp{@@} and the specified value to recipients specified in the -message when they are sent using the @code{RCPT TO} command. Some -configurations of sendmail requires this behavior. Don't bother to -set this unless you have get an error like: - -@example - Sending failed; SMTP protocol error -@end example - -when sending mail, and the debug buffer (@pxref{Debugging})) contains -an error such as: - -@example - RCPT TO: @var{someone} - 501 @var{someone}: recipient address must contain a domain -@end example - -@end table - - -@node Debugging -@chapter Debugging - -Sometimes delivery fails, often with the generic error message -@samp{Sending failed; SMTP protocol error}. Enabling one or both of -the following variables and inspecting a trace buffer will often give -clues to the reason for the error. - -@table @code - -@item smtpmail-debug-info -@vindex smtpmail-debug-info - The variable @code{smtpmail-debug-info} controls whether to print -the SMTP protocol exchange in the minibuffer, and retain the entire -exchange in a buffer @samp{*trace of SMTP session to @var{server}*}, -where @var{server} is the name of the mail server to which you send -mail. - -@item smtpmail-debug-verb -@vindex smtpmail-debug-verb - The variable @code{smtpmail-debug-verb} controls whether to send the -@code{VERB} token to the server. The @code{VERB} server instructs the -server to be more verbose, and often also to attempt final delivery -while your SMTP session is still running. It is usually only useful -together with @code{smtpmail-debug-info}. Note that this may cause -mail delivery to take considerable time if the final destination -cannot accept mail. - -@end table - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include doclicense.texi - -@node Index -@chapter Index - -@section Concept Index - -@printindex cp - -@section Function and Variable Index - -@printindex fn - -@bye diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi deleted file mode 100644 index 6604dc5f0d0..00000000000 --- a/doc/misc/speedbar.texi +++ /dev/null @@ -1,1255 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/speedbar -@settitle Speedbar: File/Tag summarizing utility -@syncodeindex fn cp - -@copying -Copyright @copyright{} 1999-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Speedbar: (speedbar). File/Tag summarizing utility. -@end direntry - -@titlepage -@sp 10 -@center @titlefont{Speedbar} -@sp 2 -@center Eric Ludlam -@vskip 0pt plus 1 fill -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top, , , (dir)Top -@comment node-name, next, previous, up -@top Speedbar - -Speedbar is a program for Emacs which can be used to summarize -information related to the current buffer. Its original inspiration -is the `explorer' often used in modern development environments, office -packages, and web browsers. - -Speedbar displays a narrow frame in which a tree view is shown. This -tree view defaults to containing a list of files and directories. Files -can be `expanded' to list tags inside. Directories can be expanded to -list the files within itself. Each file or tag can be jumped to -immediately. - -Speedbar expands upon `explorer' windows by maintaining context with the -user. For example, when using the file view, the current buffer's file -is highlighted. Speedbar also mimics the explorer windows by providing -multiple display modes. These modes come in two flavors. Major display -modes remain consistent across buffers, and minor display modes appear -only when a buffer of the applicable type is shown. This allows -authors of other packages to provide speedbar summaries customized to -the needs of that mode. - -Throughout this manual, activities are defined as `clicking on', or -`expanding' items. Clicking means using @kbd{Mouse-2} on a -button. Expanding refers to clicking on an expansion button to display -an expanded summary of the entry the expansion button is -on. @xref{Basic Navigation}. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Introduction:: Basics of speedbar. -* Basic Navigation:: Basics of speedbar common between all modes. -* File Mode:: Summarizing files. -* Buffer Mode:: Summarizing buffers. -* Minor Modes:: Additional minor modes such as Info and RMAIL. -* Customizing:: Changing speedbar behavior. -* Extending:: Extend speedbar for your own project. -* GNU Free Documentation License:: The license for this documentation. -* Index:: -@end menu - -@node Introduction, Basic Navigation, , Top -@comment node-name, next, previous, up -@chapter Introduction -@cindex introduction - -To start using speedbar use the command @kbd{M-x speedbar RET} or -select it from the @samp{Options->Show/Hide} sub-menu. This command -will open a new frame to summarize the local files. On X Window -systems or on MS-Windows, speedbar's frame is twenty characters wide, -and will mimic the height of the frame from which it was started. It -positions itself to the left or right of the frame you started it -from. - -To use speedbar effectively, it is important to understand its -relationship with the frame you started it from. This frame is the -@dfn{attached frame} which speedbar will use as a reference point. Once -started, speedbar watches the contents of this frame, and attempts to -make its contents relevant to the buffer loaded into the attached -frame. In addition, all requests made in speedbar that require the -display of another buffer will display in the attached frame. - -When used in terminal mode, the new frame appears the same size as the -terminal. Since it is not visible while working in the attached frame, -speedbar will save time by using the @dfn{slowbar mode}, where no tracking is -done until speedbar is requested to show itself (i.e., the speedbar's -frame becomes the selected frame). - -@cindex @code{speedbar-get-focus} -The function to use when switching between frames using the keyboard is -@code{speedbar-get-focus}. This function will toggle between frames, and -it's useful to bind it to a key in terminal mode. @xref{Customizing}. - -@node Basic Navigation, File Mode, Introduction, Top -@comment node-name, next, previous, up -@chapter Basic Navigation - -Speedbar can display different types of data, and has several display -and behavior modes. These modes all have a common behavior, menu -system, and look. If one mode is learned, then the other modes are easy -to use. - -@menu -* Basic Key Bindings:: -* Basic Visuals:: -* Mouse Bindings:: -* Displays Submenu:: -@end menu - -@node Basic Key Bindings, Basic Visuals, Basic Navigation, Basic Navigation -@comment node-name, next, previous, up -@section Basic Key Bindings -@cindex key bindings - -These key bindings are common across all modes: - -@table @kbd -@item Q -@cindex quitting speedbar -Quit speedbar, and kill the frame. -@item q -Quit speedbar, and hide the frame. This makes it faster to restore the -speedbar frame, than if you press @kbd{Q}. -@item g -@cindex refresh speedbar display -Refresh whatever contents are in speedbar. -@item t -@cindex slowbar mode -Toggle speedbar to and from slowbar mode. In slowbar mode, frame -tracking is not done. -@item n -@itemx p -@cindex navigation -Move, respectively, to the next or previous item. A summary of that -item will be displayed in the attached frame's minibuffer. -@item M-n -@itemx M-p -Move to the next or previous item in a restricted fashion. If a list is -open, the cursor will skip over it. If the cursor is in an open list, -it will not leave it. -@item C-M-n -@itemx C-M-p -Move forwards and backwards across extended groups. This lets you -quickly skip over all files, directories, or other common sub-items at -the same current depth. -@item C-x b -Switch buffers in the attached frame. -@end table - -Speedbar can handle multiple modes. Two are provided by default. -These modes are File mode, and Buffers mode. There are accelerators to -switch into these different modes. - -@cindex mode switching hotkeys -@table @kbd -@item b -Switch into Quick Buffers mode (@pxref{Buffer Mode}). After one use, the -previous display mode is restored. -@item f -Switch into File mode. -@item r -Switch back to the previous mode. -@end table - -Some modes provide groups, lists and tags. @xref{Basic Visuals}. When -these are available, some additional common bindings are available. - -@cindex common keys -@table @kbd -@item RET -@itemx e -Edit/Open the current group or tag. This behavior is dependent on the -mode. In general, files or buffers are opened in the attached frame, -and directories or group nodes are expanded locally. -@item + -@itemx = -Expand the current group, displaying sub items. -When used with a prefix argument, any data that may have been cached is -flushed. This is similar to a power click. @xref{Mouse Bindings}. -@item - -Contract the current group, hiding sub items. -@end table - -@node Basic Visuals, Mouse Bindings, Basic Key Bindings, Basic Navigation -@comment node-name, next, previous, up -@section Basic Visuals -@cindex visuals - -Speedbar has visual cues for indicating different types of data. These -cues are used consistently across the different speedbar modes to make -them easier to interpret. - -At a high level, in File mode, there are directory buttons, sub -directory buttons, file buttons, tag buttons, and expansion buttons. -This makes it easy to use the mouse to navigate a directory tree, and -quickly view files, or a summary of those files. - -The most basic visual effect used to distinguish between these button -types is color and mouse highlighting. Anything the mouse highlights -can be clicked on and is called a button (@pxref{Mouse Bindings}). -Anything not highlighted by the mouse will not be clickable. - -Text in speedbar consists of four different types of data. Knowing how -to read these textual elements will make it easier to navigate by -identifying the types of data available. - -@subsubsection Groups -@cindex groups - -Groups summarize information in a single line, and provide a high level -view of more complex systems, like a directory tree, or manual chapters. - -Groups appear at different indentation levels, and are prefixed with a -@samp{+} in some sort of `box'. The group name will summarize the -information within it, and the expansion box will display that -information inline. In File mode, directories and files are `groups' -where the @samp{+} is surrounded by brackets like this: - -@example -<+> include -<-> src - [+] foo.c -@end example - -In this example, we see both open and closed directories, in addition to -a file. The directories have a box consisting of angle brackets, and a -file uses square brackets. - -In all modes, a group can be `edited' by pressing @kbd{RET}, meaning a -file will be opened, or a directory explicitly opened in speedbar. A -group can be expanded or contracted using @kbd{+} or -@kbd{-}. @xref{Basic Key Bindings}. - -Sometimes groups may have a @samp{?} in its indicator box. This means -that it is a group type, but there are no contents, or no known way of -extracting contents of that group. - -When a group has been expanded, the indicator button changes from -@samp{+} to @samp{-}. This indicates that the contents are being shown. -Click the @samp{-} button to contract the group, or hide the contents -currently displayed. - -@subsubsection Tags -@cindex tags - -Tags are the leaf nodes of the tree system. Tags are generally prefixed -with a simple character, such as @samp{>}. Tags can only be jumped to using -@kbd{RET} or @kbd{e}. - -@subsubsection Boolean Flags - -Sometimes a group or tag is given a boolean flag. These flags appear as -extra text characters at the end of the line. File mode uses boolean -flags, such as a @samp{*} to indicate that a file has been checked out -of a versioning system. - -For additional flags, see -@c Note to self, update these to sub-nodes which are more relevant. -@ref{File Mode}, and @ref{Version Control}. - -@subsubsection Unadorned Text - -Unadorned text generally starts in column 0, without any special symbols -prefixing them. In Buffers mode different buffer groups are prefixed -with a description of what the following buffers are (Files, scratch -buffers, and invisible buffers.) - -Unadorned text will generally be colorless, and not clickable. - -@subsubsection Color Cues - -Each type of Group, item indicator, and label is given a different -color. The colors chosen are dependent on whether the background color -is light or dark. -Of important note is that the `current item', which may be a buffer or -file name, is highlighted red, and underlined. - -Colors can be customized from the group @code{speedbar-faces}. Some -modes, such as for Info, will use the Info colors instead of default -speedbar colors as an indication of what is currently being displayed. - -The face naming convention mirrors the File display mode. Modes which -do not use files will attempt to use the same colors on analogous -entries. - -@node Mouse Bindings, Displays Submenu, Basic Visuals, Basic Navigation -@comment node-name, next, previous, up -@section Mouse Bindings -@cindex mouse bindings - -The mouse has become a common information navigation tool. Speedbar -will use the mouse to navigate file systems, buffer lists, and other -data. The different textual cues provide buttons which can be clicked -on (@pxref{Basic Visuals}). Anything that highlights can be clicked on -with the mouse, or affected by the menu. - -The mouse bindings are: - -@table @kbd -@item Mouse-1 -Move cursor to that location. -@item Mouse-2 -@itemx Double-Mouse-1 -Activate the current button. @kbd{Double-Mouse-1} is called a @dfn{double -click} on other platforms, and is useful for windows users with two -button mice. -@c Isn't it true that with two-button mice, the right button is Mouse-2? -@c On GNU/Linux, the right button is Mouse-3. -@item S-Mouse-2 -@itemx S-Double-Mouse-1 -@cindex power click -This has the same effect as @kbd{Mouse-2}, except it is called a power -click. This means that if a group with an expansion button @samp{+} is -clicked, any caches are flushed, and subitems re-read. If it is a name, -it will be opened in a new frame. -@item Mouse-3 -Activate the speedbar menu. The item selected affects the line clicked, -not the line where the cursor was. -@item Mouse-1 @r{(mode line)} -Activate the menu. This affects the item the cursor is on before the -click, since the mouse was not clicked on anything. -@item C-Mouse-1 -Buffers sub-menu. The buffer in the attached frame is switched. -@end table - -When the mouse moves over buttons in speedbar, details of that item -should be displayed in the minibuffer of the attached frame. Sometimes -this can contain extra information such as file permissions, or tag -location. - -@node Displays Submenu, , Mouse Bindings, Basic Navigation -@comment node-name, next, previous, up -@section Displays Submenu -@cindex displays submenu - -You can display different data by using different display modes. These -specialized modes make it easier to navigate the relevant pieces of -information, such as files and directories, or buffers. - -In the main menu, found by clicking @kbd{Mouse-3}, there is a submenu -labeled @samp{Displays}. This submenu lets you easily choose between -different display modes. - -The contents are modes currently loaded into emacs. By default, this -would include Files, Quick Buffers, and Buffers. Other major display -modes such as Info are loaded separately. - -@node File Mode, Buffer Mode, Basic Navigation, Top -@comment node-name, next, previous, up -@chapter File Mode -@cindex file mode - -File mode displays a summary of your current directory. You can display -files in the attached frame, or summarize the tags found in files. You -can even see if a file is checked out of a version control system, or -has some associated object file. - -Advanced behavior, like copying and renaming files, is also provided. - -@menu -* Directory Display:: What the display means. -* Hidden Files:: How to display hidden files. -* File Key Bindings:: Performing file operations. -@end menu - -@node Directory Display, Hidden Files, File Mode, File Mode -@comment node-name, next, previous, up -@section Directory Display -@cindex directory display - -There are three major sections in the display. The first line or two is -the root directory speedbar is currently viewing. You can jump to one -of the parent directories by clicking on the name of the directory you -wish to jump to. - -Next, directories are listed. A directory starts with the group -indicator button @samp{<+>}. Clicking the directory name makes speedbar -load that directory as the root directory for its display. Clicking the -@samp{<+>} button will list all directories and files beneath. - -Next, files are listed. Files start with the group indicator @samp{[+]} -or @samp{[?]}. You can jump to a file in the attached frame by clicking -on the file name. You can expand a file and look at its tags by -clicking on the @samp{[+]} symbol near the file name. - -A typical session might look like this: - -@example -~/lisp/ -<+> checkdoc -<+> eieio -<-> speedbar - [+] Makefile - [+] rpm.el # - [+] sb-gud.el # - [+] sb-info.el # - [+] sb-rmail.el # - [+] sb-w3.el - [-] speedbar.el *! - @{+@} Types - @{+@} Variables - @{+@} def (group) - @{+@} speedbar- - [+] speedbar.texi * -<+> testme -[+] align.el -[+] autoconf.el -@end example - -In this example, you can see several directories. The directory -@file{speedbar} has been opened inline. Inside the directory -@file{speedbar}, the file @file{speedbar.el} has its tags exposed. -These tags are extensive, and they are summarized into tag groups. - -Files get additional boolean flags associated with them. Valid flags are: - -@cindex file flags -@table @code -@item * -This file has been checked out of a version control -system. @xref{Version Control}. -@cindex @code{speedbar-obj-alist} -@item # -This file has an up to date object file associated with it. The -variable @code{speedbar-obj-alist} defines how speedbar determines this -value. -@item ! -This file has an out of date object file associated with it. -@end table - -A Tag group is prefixed with the symbol @samp{@{+@}}. Clicking this -symbol will show all symbols that have been organized into that group. -Different types of files have unique tagging methods as defined by their -major mode. Tags are generated with either the @code{imenu} package, or -through the @code{etags} interface. - -Tag groups are defined in multiple ways which make it easier to find the -tag you are looking for. Imenu keywords explicitly create groups, and -speedbar will automatically create groups if tag lists are too long. - -In our example, Imenu created the groups @samp{Types} and -@samp{Variables}. All remaining top-level symbols are then regrouped -based on the variable @code{speedbar-tag-hierarchy-method}. The -subgroups @samp{def} and @samp{speedbar-} are groupings where the first -few characters of the given symbols are specified in the group name. -Some group names may say something like @samp{speedbar-t to speedbar-v}, -indicating that all symbols which alphabetically fall between those -categories are included in that sub-group. @xref{Tag Hierarchy Methods}. - -@node Hidden Files, File Key Bindings, Directory Display, File Mode -@comment node-name, next, previous, up -@section Hidden Files -@cindex hidden files - -On GNU and Unix systems, a hidden file is a file whose name starts -with a period. They are hidden from a regular directory listing -because the user is not generally interested in them. - -In speedbar, a hidden file is a file which isn't very interesting and -might prove distracting to the user. Any uninteresting files are -removed from the File display. There are two levels of uninterest in -speedbar. The first level of uninterest are files which have no -expansion method, or way of extracting tags. The second level is any -file that matches the same pattern used for completion in -@code{find-file}. This is derived from the variable -@code{completion-ignored-extensions}. - -You can toggle the display of uninteresting files from the toggle menu -item @samp{Show All Files}. This will display all level one hidden files. -These files will be shown with a @samp{?} indicator. Level 2 hidden -files will still not be shown. - -Object files fall into the category of level 2 hidden files. You can -determine their presence by the @samp{#} and @samp{!} file indicators. -@xref{Directory Display}. - -@node File Key Bindings, , Hidden Files, File Mode -@comment node-name, next, previous, up -@section File Key Bindings -@cindex file key bindings - -File mode has key bindings permitting different file system operations -such as copy or rename. These commands all operate on the @dfn{current -file}. In this case, the current file is the file at point, or clicked -on when pulling up the menu. - -@table @kbd -@item U -Move the entire speedbar display up one directory. -@item I -Display information in the minibuffer about this line. This is the same -information shown when navigating with @kbd{n} and @kbd{p}, or moving -the mouse over an item. -@item B -Byte compile the Emacs Lisp file on this line. -@item L -Load the Emacs Lisp file on this line. If a @file{.elc} file exists, -optionally load that. -@item C -Copy the current file to some other location. -@item R -Rename the current file, possibly moving it to some other location. -@item D -Delete the current file. -@item O -Delete the current file's object file. Use the symbols @samp{#} and -@samp{!} to determine if there is an object file available. -@end table - -One menu item toggles the display of all available files. By default, -only files which Emacs understands, and knows how to convert into a tag -list, are shown. By showing all files, additional files such as text files are -also displayed, but they are prefixed with the @samp{[?]} symbol. This -means that it is a file, but Emacs doesn't know how to expand it. - -@node Buffer Mode, Minor Modes, File Mode, Top -@comment node-name, next, previous, up -@chapter Buffer Mode -@cindex buffer mode - -Buffer mode is very similar to File mode, except that instead of -tracking the current directory and all files available there, the -current list of Emacs buffers is shown. - -These buffers can have their tags expanded in the same way as files, -and uses the same unknown file indicator (@pxref{File Mode}). - -Buffer mode does not have file operation bindings, but the following -buffer specific key bindings are available: - -@table @kbd -@item k -Kill this buffer. Do not touch its file. -@item r -Revert this buffer, reloading from disk. -@end table - -In addition to Buffer mode, there is also Quick Buffer mode. In fact, -Quick Buffers is bound to the @kbd{b} key. The only difference between -Buffers and Quick Buffers is that after one operation is performed -which affects the attached frame, the display is immediately reverted to -the last displayed mode. - -Thus, if you are in File mode, and you need quick access to a buffer, -press @kbd{b}, click on the buffer you want, and speedbar will revert -back to File mode. - -@node Minor Modes, Customizing, Buffer Mode, Top -@comment node-name, next, previous, up -@chapter Minor Display Modes -@cindex minor display modes - -For some buffers, a list of files and tags makes no sense. This could -be because files are not currently in reference (such as web pages), or -that the files you might be interested have special properties (such as -email folders.) - -In these cases, a minor display mode is needed. A minor display mode -will override any major display mode currently being displayed for the -duration of the specialized buffer's use. Minor display modes -will follow the general rules of their major counterparts in terms of -key bindings and visuals, but will have specialized behaviors. - -@menu -* RMAIL:: Managing folders. -* Info:: Browsing topics. -* GDB:: Watching expressions or managing the current - stack trace. -@end menu - -@node RMAIL, Info, Minor Modes, Minor Modes -@comment node-name, next, previous, up -@section RMAIL -@cindex RMAIL - -When using RMAIL, speedbar will display two sections. The first is a -layer one reply button. Clicking here will initialize a reply buffer -showing only this email address in the @samp{To:} field. - -The second section lists all RMAIL folders in the same directory as your -main RMAIL folder. The general rule is that RMAIL folders always appear -in all caps, or numbers. It is possible to save mail in folders with -lower case letters, but there is no clean way of detecting such RMAIL folders -without opening them all. - -Each folder can be visited by clicking the name. You can move mail from -the current RMAIL folder into a different folder by clicking the -@samp{} button. The @samp{M} stands for Move. - -In this way you can manage your existing RMAIL folders fairly easily -using the mouse. - -@node Info, GDB, RMAIL, Minor Modes -@comment node-name, next, previous, up -@section Info -@cindex Info - -When browsing Info files, all local relevant information is displayed in -the info buffer and a topical high-level view is provided in speedbar. -All top-level info nodes are shown in the speedbar frame, and can be -jumped to by clicking the name. - -You can open these nodes with the @samp{[+]} button to see what sub-topics -are available. Since these sub-topics are not examined until you click -the @samp{[+]} button, sometimes a @samp{[?]} will appear when you click on -a @samp{[+]}, indicating that there are no sub-topics. - -@node GDB, , Info, Minor Modes -@comment node-name, next, previous, up -@section GDB -@cindex gdb -@cindex gud - -You can debug an application with GDB in Emacs using graphical mode or -text command mode (@pxref{GDB Graphical Interface,,, emacs, The -extensible self-documenting text editor}). - -If you are using graphical mode you can see how selected variables -change each time your program stops (@pxref{Watch Expressions,,, -emacs, The extensible self-documenting text editor}). - -If you are using text command mode, speedbar can show -you the current stack when the current buffer is the @file{*gdb*} -buffer. Usually, it will just report that there is no stack, but when -the application is stopped, the current stack will be shown. - -You can click on any stack element and gdb will move to that stack -level. You can then check variables local to that level at the GDB -prompt. - -@node Customizing, Extending, Minor Modes, Top -@comment node-name, next, previous, up -@chapter Customizing -@cindex customizing - -Speedbar is highly customizable, with a plethora of control elements. -Since speedbar is so visual and reduces so much information, this is an -important aspect of its behavior. - -In general, there are three custom groups you can use to quickly modify -speedbar's behavior. - -@table @code -@item speedbar -Basic speedbar behaviors. -@item speedbar-vc -Customizations regarding version control handling. -@item speedbar-faces -Customize speedbar's many colors and fonts. -@end table - -@menu -* Frames and Faces:: Visible behaviors. -* Tag Hierarchy Methods:: Customizing how tags are displayed. -* Version Control:: Adding new VC detection modes. -* Hooks:: The many hooks you can use. -@end menu - -@node Frames and Faces, Tag Hierarchy Methods, Customizing, Customizing -@comment node-name, next, previous, up -@section Frames and Faces -@cindex faces -@cindex frame parameters - -There are several faces speedbar generates to provide a consistent -color scheme across display types. You can customize these faces using -your favorite method. They are: - -@table @asis -@cindex @code{speedbar-button-face} -@item speedbar-button-face -Face used on expand/contract buttons. -@cindex @code{speedbar-file-face} -@item speedbar-file-face -Face used on Files. Should also be used on non-directory like nodes. -@cindex @code{speedbar-directory-face} -@item speedbar-directory-face -Face used for directories, or nodes which consist of groups of other nodes. -@cindex @code{speedbar-tag-face} -@item speedbar-tag-face -Face used for tags in a file, or for leaf items. -@cindex @code{speedbar-selected-face} -@item speedbar-selected-face -Face used to highlight the selected item. This would be the current -file being edited. -@cindex @code{speedbar-highlight-face} -@item speedbar-highlight-face -Face used when the mouse passes over a button. -@end table - -You can also customize speedbar's initial frame parameters. How this is -accomplished is dependent on your platform being Emacs or XEmacs. - -@cindex @code{speedbar-frame-parameters}, Emacs -In Emacs, change the alist @code{speedbar-frame-parameters}. This -variable is used to set up initial details. Height is also -automatically added when speedbar is created, though you can override -it. - -@cindex @code{speedbar-frame-plist}, XEmacs -In XEmacs, change the plist @code{speedbar-frame-plist}. This is the -XEmacs way of doing the same thing. - -@node Tag Hierarchy Methods, Version Control, Frames and Faces, Customizing -@comment node-name, next, previous, up -@section Tag Hierarchy Methods -@cindex tag hierarchy -@cindex tag groups -@cindex tag sorting - -When listing tags within a file, it is possible to get an annoyingly -long list of entries. Imenu (which generates the tag list in Emacs) -will group some classes of items automatically. Even here, however, -some tag groups can be quite large. - -@cindex @code{speedbar-tag-hierarchy-method} -To solve this problem, tags can be grouped into logical units through a -hierarchy processor. The specific variable to use is -@code{speedbar-tag-hierarchy-method}. There are several methods that -can be applied in any order. They are: - -@table @code -@cindex @code{speedbar-trim-words-tag-hierarchy} -@item speedbar-trim-words-tag-hierarchy -Find a common prefix for all elements of a group, and trim it off. -@cindex @code{speedbar-prefix-group-tag-hierarchy} -@item speedbar-prefix-group-tag-hierarchy -If a group is too large, place sets of tags into bins based on common -prefixes. -@cindex @code{speedbar-simple-group-tag-hierarchy} -@item speedbar-simple-group-tag-hierarchy -Take all items in the top level list not in a group, and stick them into -a @samp{Tags} group. -@cindex @code{speedbar-sort-tag-hierarchy} -@item speedbar-sort-tag-hierarchy -Sort all items, leaving groups on top. -@end table - -You can also add your own functions to reorganize tags as you see fit. - -Some other control variables are: - -@table @code -@cindex @code{speedbar-tag-group-name-minimum-length} -@item speedbar-tag-group-name-minimum-length -Default value: 4. - -The minimum length of a prefix group name before expanding. Thus, if -the @code{speedbar-tag-hierarchy-method} includes -@code{speedbar-prefix-group-tag-hierarchy} and one such group's common -characters is less than this number of characters, then the group name -will be changed to the form of: - -@example -worda to wordb -@end example - -instead of just - -@example -word -@end example - -This way we won't get silly looking listings. - -@cindex @code{speedbar-tag-split-minimum-length} -@item speedbar-tag-split-minimum-length -Default value: 20. - -Minimum length before we stop trying to create sub-lists in tags. -This is used by all tag-hierarchy methods that break large lists into -sub-lists. - -@cindex @code{speedbar-tag-regroup-maximum-length} -@item speedbar-tag-regroup-maximum-length -Default value: 10. - -Maximum length of submenus that are regrouped. -If the regrouping option is used, then if two or more short subgroups -are next to each other, then they are combined until this number of -items is reached. -@end table - -@node Version Control, Hooks, Tag Hierarchy Methods, Customizing -@comment node-name, next, previous, up -@section Version Control -@cindex version control -@cindex vc extensions - -When using the file mode in speedbar, information regarding a version -control system adds small details to the display. If a file is in a -version control system, and is ``checked out'' or ``locked'' locally, an -asterisk @samp{*} appears at the end of the file name. In addition, -the directory name for Version Control systems are left out of the -speedbar display. - -@cindex @code{speedbar-directory-unshown-regexp} -You can easily add new version control systems into speedbar's detection -scheme. To make a directory ``disappear'' from the list, use the variable -@code{speedbar-directory-unshown-regexp}. - -@cindex @code{speedbar-vc-path-enable-hook} -Next, you need to write entries for two hooks. The first is -@code{speedbar-vc-path-enable-hook} which will enable a VC check in the -current directory for the group of files being checked. Your hook -function should take one parameter (the directory to check) and return -@code{t} if your VC method is in control here. - -@cindex @code{speedbar-vc-in-control-hook} -The second function is @code{speedbar-vc-in-control-hook}. This hook -takes two parameters, the @var{path} of the file to check, and the -@var{file} name. Return @code{t} if you want to have the asterisk -placed near this file. - -@cindex @code{speedbar-vc-indicator} -Lastly, you can change the VC indicator using the variable -@code{speedbar-vc-indicator}, and specify a single character string. - -@node Hooks, , Version Control, Customizing -@comment node-name, next, previous, up -@section Hooks -@cindex hooks - -There are several hooks in speedbar allowing custom behaviors to be -added. Available hooks are: - -@table @code -@cindex @code{speedbar-visiting-file-hook} -@item speedbar-visiting-file-hook -Hooks run when speedbar visits a file in the selected frame. -@cindex @code{speedbar-visiting-tag-hook} -@item speedbar-visiting-tag-hook -Hooks run when speedbar visits a tag in the selected frame. -@cindex @code{speedbar-load-hook} -@item speedbar-load-hook -Hooks run when speedbar is loaded. -@cindex @code{speedbar-reconfigure-keymaps-hook} -@item speedbar-reconfigure-keymaps-hook -Hooks run when the keymaps are regenerated. Keymaps are reconfigured -whenever modes change. This will let you add custom key bindings. -@cindex @code{speedbar-before-popup-hook} -@item speedbar-before-popup-hook -Hooks called before popping up the speedbar frame. -New frames are often popped up when ``power clicking'' on an item to view -it. -@cindex @code{speedbar-before-delete-hook} -@item speedbar-before-delete-hook -Hooks called before deleting or hiding the speedbar frame. -@cindex @code{speedbar-mode-hook} -@item speedbar-mode-hook -Hooks called after creating a speedbar buffer. -@cindex @code{speedbar-timer-hook} -@item speedbar-timer-hook -Hooks called after running the speedbar timer function. -@cindex @code{speedbar-scanner-reset-hook} -@item speedbar-scanner-reset-hook -Hook called whenever generic scanners are reset. -Set this to implement your own scanning or rescan safe functions with -state data. -@end table - -@node Extending, GNU Free Documentation License, Customizing, Top -@comment node-name, next, previous, up -@chapter Extending -@cindex extending - -Speedbar can run different types of Major display modes such as Files -(@pxref{File Mode}), and Buffers (@pxref{Buffer Mode}). It can also manage -different minor display modes for use with buffers handling specialized -data. - -These major and minor display modes are handled through an extension -system which permits specialized keymaps and menu extensions, in -addition to a unique rendering function. You can also specify a wide -range of tagging functions. The default uses @code{imenu}, but new -tagging methods can be easily added. In this chapter, you will -learn how to write your own major or minor display modes, and how to -create specialized tagging functions. - -@menu -* Minor Display Modes:: How to create a minor display mode. -* Major Display Modes:: How to create a major display mode. -* Tagging Extensions:: How to create your own tagging methods. -* Creating a display:: How to insert buttons and hierarchies. -@end menu - -@node Minor Display Modes, Major Display Modes, Extending, Extending -@section Minor Display Modes -@cindex create minor display mode - -A @dfn{minor display mode} is a mode useful when using a specific type of -buffer. This mode might not be useful for any other kind of data or -mode, or may just be more useful that a files or buffers based mode when -working with a specialized mode. - -Examples that already exist for speedbar include RMAIL, Info, and gdb. -These modes display information specific to the major mode shown in the -attached frame. - -To enable a minor display mode in your favorite Major mode, follow these -steps. The string @samp{@var{name}} is the name of the major mode being -augmented with speedbar. - -@enumerate -@item -Create the keymap variable @code{@var{name}-speedbar-key-map}. - -@item -Create a function, named whatever you like, which assigns values into your -keymap. Use this command to create the keymap before assigning -bindings: - -@smallexample - (setq @var{name}-speedbar-key-map (speedbar-make-specialized-keymap)) -@end smallexample - -This function creates a special keymap for use in speedbar. - -@item -Call your install function, or assign it to a hook like this: - -@smallexample -(if (featurep 'speedbar) - (@var{name}-install-speedbar-variables) - (add-hook 'speedbar-load-hook '@var{name}-install-speedbar-variables)) -@end smallexample - -@item -Create an easymenu compatible vector named -@code{@var{name}-speedbar-menu-items}. This will be spliced into -speedbar's control menu. - -@item -Create a function called @code{@var{name}-speedbar-buttons}. This function -should take one variable, which is the buffer for which it will create -buttons. At this time @code{(current-buffer)} will point to the -uncleared speedbar buffer. -@end enumerate - -When writing @code{@var{name}-speedbar-buttons}, the first thing you will -want to do is execute a check to see if you need to re-create your -display. If it needs to be cleared, you need to erase the speedbar -buffer yourself, and start drawing buttons. @xref{Creating a display}. - -@node Major Display Modes, Tagging Extensions, Minor Display Modes, Extending -@section Major Display Modes -@cindex create major display mode - -Creating a @dfn{Major Display Mode} for speedbar requires authoring a keymap, -an easy-menu segment, and writing several functions. These items can be -given any name, and are made the same way as in a minor display mode -(@pxref{Minor Display Modes}). Once this is done, these items need to be -registered. - -Because this setup activity may or may not have speedbar available when -it is being loaded, it is necessary to create an install function. This -function should create and initialize the keymap, and add your -expansions into the customization tables. - -@cindex @code{speedbar-make-specialized-keymap} -When creating the keymap, use the function -@code{speedbar-make-specialized-keymap} instead of other keymap making -functions. This will provide you with the initial bindings needed. -Some common speedbar functions you might want to bind are: - -@table @code -@cindex @code{speedbar-edit-line} -@item speedbar-edit-line -Edit the item on the current line. -@cindex @code{speedbar-expand-line} -@item speedbar-expand-line -Expand the item under the cursor. -With a numeric argument (@kbd{C-u}), flush cached data before expanding. -@cindex @code{speedbar-contract-line} -@item speedbar-contract-line -Contract the item under the cursor. -@end table - -@cindex @code{speedbar-line-path} -These function require that function @code{speedbar-line-path} be -correctly overloaded to work. - -Next, register your extension like this; - -@example - (speedbar-add-expansion-list '("MyExtension" - MyExtension-speedbar-menu-items - MyExtension-speedbar-key-map - MyExtension-speedbar-buttons)) -@end example - -There are no limitations to the names you use. - -The first parameter is the string representing your display mode. -The second parameter is a variable name containing an easymenu compatible -menu definition. This will be stuck in the middle of speedbar's menu. -The third parameter is the variable name containing the keymap we -discussed earlier. -The last parameter is a function which draws buttons for your mode. -This function must take two parameters. The directory currently being -displayed, and the depth at which you should start rendering buttons. -The function will then draw (starting at the current cursor position) -any buttons deemed necessary based on the input parameters. -@xref{Creating a display}. - -Next, you need to register function overrides. This may look something -like this: - -@example -(speedbar-add-mode-functions-list - '("MYEXTENSION" - (speedbar-item-info . MyExtension-speedbar-item-info) - (speedbar-line-path . MyExtension-speedbar-line-path))) -@end example - -The first element in the list is the name of you extension. The second -is an alist of functions to overload. The function to overload is -first, followed by what you want called instead. - -For @code{speedbar-line-path} your function should take an optional DEPTH -parameter. This is the starting depth for heavily indented lines. If -it is not provided, you can derive it like this: - -@example -(save-match-data - (if (not depth) - (progn - (beginning-of-line) - (looking-at "^\\([0-9]+\\):") - (setq depth (string-to-int (match-string 1))))) -@end example - -@noindent -where the depth is stored as invisible text at the beginning of each -line. - -The path returned should be the full path name of the file associated -with that line. If the cursor is on a tag, then the file containing -that tag should be returned. This is critical for built in file based -functions to work (meaning less code for you to write). If your display -does not deal in files, you do not need to overload this function. - -@cindex @code{speedbar-item-info} -The function @code{speedbar-item-info}, however, is very likely to need -overloading. This function takes no parameters and must derive a text -summary to display in the minibuffer. - -There are several helper functions you can use if you are going to use -built in tagging. These functions can be @code{or}ed since each one -returns non-@code{nil} if it displays a message. They are: - -@table @code -@cindex @code{speedbar-item-info-file-helper} -@item speedbar-item-info-file-helper -This takes an optional @var{filename} parameter. You can derive your own -filename, or it will derive it using a (possibly overloaded) function -@code{speedbar-line-file}. It shows details about a file. -@cindex @code{speedbar-item-info-tag-helper} -@item speedbar-item-info-tag-helper -If the current line is a tag, then display information about that tag, -such as its parent file, and location. -@end table - -Your custom function might look like this: - -@example -(defun MyExtension-item-info () - "Display information about the current line." - (or (speedbar-item-info-tag-helper) - (message "Interesting detail."))) -@end example - -Once you have done all this, speedbar will show an entry in the -@samp{Displays} menu declaring that your extension is available. - -@node Tagging Extensions, Creating a display, Major Display Modes, Extending -@section Tagging Extensions - -It is possible to create new methods for tagging files in speedbar. -To do this, you need two basic functions, one function to fetch the -tags from a buffer, the other to insert them below the filename. - -@defun my-fetch-dynamic-tags file -Parse @var{file} for a list of tags. Return the list, or @code{t} if there was -an error. -@end defun - -The non-error return value can be anything, as long as it can be -inserted by its paired function: - -@defun my-insert-tag-list level lst -Insert a list of tags @var{lst} started at indentation level -@var{level}. Creates buttons for each tag, and provides any other -display information required. -@end defun - -@cindex @code{speedbar-create-tag-hierarchy} -It is often useful to use @code{speedbar-create-tag-hierarchy} on your -token list. See that function's documentation for details on what it -requires. - -@cindex @code{speedbar-dynamic-tags-function-list} -Once these two functions are written, modify the variable -@code{speedbar-dynamic-tags-function-list} to include your parser at the -beginning, like this: - -@example -(add-to-list 'speedbar-dynamic-tags-function-list - '(my-fetch-dynamic-tags . my-insert-tag-list)) -@end example - -If your parser is only good for a few types of files, make sure that it -is either a buffer local modification, or that the tag generator returns -@code{t} for non valid buffers. - -@node Creating a display, , Tagging Extensions, Extending -@section Creating a display -@cindex creating a display - -Rendering a display in speedbar is completely flexible. When your -button function is called, see @ref{Minor Display Modes}, and @ref{Major -Display Modes}, you have control to @code{insert} anything you want. - -The conventions allow almost anything to be inserted, but several helper -functions are provided to make it easy to create the standardized -buttons. - -To understand the built in functions, each `button' in speedbar consists -of four important pieces of data. The text to be displayed, token -data to be associated with the text, a function to call, and some face to -display it in. - -When a function is provided, then that text becomes mouse activated, -meaning the mouse will highlight the text. - -Additionally, for data which can form deep trees, each line is given a -depth which indicates how far down the tree it is. This information is -stored in invisible text at the beginning of each line, and is used by -the navigation commands. - -@defun speedbar-insert-button text face mouse function &optional token prevline -This function inserts one button into the current location. -@var{text} is the text to insert. @var{face} is the face in which it -will be displayed. @var{mouse} is the face to display over the text -when the mouse passes over it. @var{function} is called whenever the -user clicks on the text. - -The optional argument @var{token} is extra data to associated with the -text. Lastly @var{prevline} should be non-@code{nil} if you want this line to -appear directly after the last button which was created instead of on -the next line. -@end defun - -@defun speedbar-make-tag-line exp-button-type exp-button-char exp-button-function exp-button-data tag-button tag-button-function tag-button-data tag-button-face depth - -Create a tag line with @var{exp-button-type} for the small expansion -button. This is the button that expands or contracts a node (if -applicable), and @var{exp-button-char} the character in it (@samp{+}, -@samp{-}, @samp{?}, etc). @var{exp-button-function} is the function -to call if it's clicked on. Button types are @code{bracket}, -@code{angle}, @code{curly}, @code{expandtag}, @code{statictag}, and -@code{nil}. @var{exp-button-data} is extra data attached to the text -forming the expansion button. - -Next, @var{tag-button} is the text of the tag. -@var{tag-button-function} is the function to call if clicked on, and -@var{tag-button-data} is the data to attach to the text field (such a -tag positioning, etc). @var{tag-button-face} is a face used for this -type of tag. - -Lastly, @var{depth} shows the depth of expansion. - -This function assumes that the cursor is in the speedbar window at the -position to insert a new item, and that the new item will end with a CR. -@end defun - -@defun speedbar-insert-generic-list level list expand-fun find-fun - -At @var{level}, (the current indentation level desired) insert a generic -multi-level alist @var{list}. Associations with lists get @samp{@{+@}} -tags (to expand into more nodes) and those with positions or other data -just get a @samp{>} as the indicator. @samp{@{+@}} buttons will have the -function @var{expand-fun} and the token is the @code{cdr} list. The -token name will have the function @var{find-fun} and not token. - -Each element of the list can have one of these forms: - -@table @code -@item (@var{name} . marker-or-number) -One tag at this level. -@item (@var{name} (@var{name} . marker-or-number) (@var{name} . marker-or-number) ... ) -One group of tags. -@item (@var{name} marker-or-number (@var{name} . marker-or-number) ... ) -One Group of tags where the group has a starting position. -@end table - -When you use @code{speedbar-insert-generic-list}, there are some -variables you can set buffer-locally to change the behavior. The most -obvious is @code{speedbar-tag-hierarchy-method}. -@xref{Tag Hierarchy Methods}. - -@defvar speedbar-generic-list-group-expand-button-type -This is the button type used for groups of tags, whether expanded -or added in via a hierarchy method. Two good values are -@code{curly} and @code{expandtag}. Curly is the default button, and -@code{expandtag} is useful if the groups also has a position. -@end defvar - -@defvar speedbar-generic-list-tag-button-type -This is the button type used for a single tag. -Two good values are @code{nil} and @code{statictag}. -@code{nil} is the default, and @code{statictag} has the same width as -@code{expandtag}. -@end defvar - -@end defun - -@node GNU Free Documentation License, Index, Extending, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Index, , GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Concept Index -@printindex cp - -@bye -@c LocalWords: speedbar's xref slowbar kbd subsubsection -@c LocalWords: keybindings diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi deleted file mode 100644 index 7fbd11decd7..00000000000 --- a/doc/misc/tramp.texi +++ /dev/null @@ -1,3716 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/tramp -@c %**start of header -@settitle TRAMP User Manual -@c %**end of header - -@c This is *so* much nicer :) -@footnotestyle end - -@c In the Tramp CVS, the version number is auto-frobbed from -@c configure.ac, so you should edit that file and run -@c "autoconf && ./configure" to change the version number. - -@c Additionally, flags are set with respect to the Emacs flavor; and -@c depending whether Tramp is packaged into (X)Emacs, or standalone. - -@include trampver.texi - -@c Macro for formatting a filename according to the respective syntax. -@c xxx and yyy are auxiliary macros in order to omit leading and -@c trailing whitespace. Not very elegant, but I don't know it better. - -@macro xxx {one}@c -@set \one\@c -@end macro - -@macro yyy {one, two}@c -@xxx{x\one\}@c -@ifclear x@c -\one\@w{}\two\@c -@end ifclear -@clear x\one\@c -@end macro - -@macro trampfn {method, user, host, localname}@c -@value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c -@end macro - -@copying -Copyright @copyright{} 1999-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to -copy and modify this GNU manual. Buying copies from the FSF -supports it in developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@c Entries for @command{install-info} to use -@dircategory @value{emacsname} network features -@direntry -* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol - @value{emacsname} remote file access via rsh and rcp. -@end direntry - -@titlepage -@title @value{tramp} version @value{trampver} User Manual -@author by Daniel Pittman -@author based on documentation by Kai Gro@ss{}johann -@page -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Overview, (dir), (dir) -@top @value{tramp} version @value{trampver} User Manual - -This file documents @value{tramp} version @value{trampver}, a remote file -editing package for @value{emacsname}. - -@value{tramp} stands for `Transparent Remote (file) Access, Multiple -Protocol'. This package provides remote file editing, similar to -@value{ftppackagename}. - -The difference is that @value{ftppackagename} uses FTP to transfer -files between the local and the remote host, whereas @value{tramp} uses a -combination of @command{rsh} and @command{rcp} or other work-alike -programs, such as @command{ssh}/@command{scp}. - -You can find the latest version of this document on the web at -@uref{http://www.gnu.org/software/tramp/}. - -@c Pointer to the other Emacs flavor is necessary only in case of -@c standalone installation. -@ifset installchapter -The manual has been generated for @value{emacsname}. -@ifinfo -If you want to read the info pages for @value{emacsothername}, you -should read in @ref{Installation} how to create them. -@end ifinfo -@ifhtml -If you're using the other Emacs flavor, you should read the -@uref{@value{emacsotherfilename}, @value{emacsothername}} pages. -@end ifhtml -@end ifset - -@ifhtml -The latest release of @value{tramp} is available for -@uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see -@ref{Obtaining Tramp} for more details, including the CVS server -details. - -@value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/, -Savannah Project Page}. -@end ifhtml - -There is a mailing list for @value{tramp}, available at -@email{tramp-devel@@gnu.org}, and archived at -@uref{http://lists.gnu.org/archive/html/tramp-devel/, the -@value{tramp} Mail Archive}. -@ifhtml -Older archives are located at -@uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel, -SourceForge Mail Archive} and -@uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/, -The Mail Archive}. -@c in HTML output, there's no new paragraph. -@*@* -@end ifhtml - -@insertcopying - -@end ifnottex - -@menu -* Overview:: What @value{tramp} can and cannot do. - -For the end user: - -* Obtaining Tramp:: How to obtain @value{tramp}. -* History:: History of @value{tramp}. -@ifset installchapter -* Installation:: Installing @value{tramp} with your @value{emacsname}. -@end ifset -* Configuration:: Configuring @value{tramp} for use. -* Usage:: An overview of the operation of @value{tramp}. -* Bug Reports:: Reporting Bugs and Problems. -* Frequently Asked Questions:: Questions and answers from the mailing list. -* Function Index:: @value{tramp} functions. -* Variable Index:: User options and variables. -* Concept Index:: An item for each concept. - -For the developer: - -* Files directories and localnames:: How file names, directories and localnames are mangled and managed. -* Traces and Profiles:: How to Customize Traces. -* Issues:: Debatable Issues and What Was Decided. - -* GNU Free Documentation License:: The license for this documentation. - -@detailmenu - --- The Detailed Node Listing --- -@c -@ifset installchapter -Installing @value{tramp} with your @value{emacsname} - -* Installation parameters:: Parameters in order to control installation. -* Load paths:: How to plug-in @value{tramp} into your environment. - -@end ifset - -Configuring @value{tramp} for use - -* Connection types:: Types of connections made to remote machines. -* Inline methods:: Inline methods. -* External methods:: External methods. -@ifset emacsgvfs -* GVFS based methods:: GVFS based external methods. -@end ifset -@ifset emacsgw -* Gateway methods:: Gateway methods. -@end ifset -* Default Method:: Selecting a default method. -* Default User:: Selecting a default user. -* Default Host:: Selecting a default host. -* Multi-hops:: Connecting to a remote host using multiple hops. -* Customizing Methods:: Using Non-Standard Methods. -* Customizing Completion:: Selecting config files for user/host name completion. -* Password handling:: Reusing passwords for several connections. -* Connection caching:: Reusing connection related information. -* Remote Programs:: How @value{tramp} finds and uses programs on the remote machine. -* Remote shell setup:: Remote shell setup hints. -* Windows setup hints:: Issues with Cygwin ssh. -* Auto-save and Backup:: Auto-save and Backup. - -Using @value{tramp} - -* Filename Syntax:: @value{tramp} filename conventions. -* Alternative Syntax:: URL-like filename syntax. -* Filename completion:: Filename completion. -* Remote processes:: Integration with other @value{emacsname} packages. -* Cleanup remote connections:: Cleanup remote connections. - -How file names, directories and localnames are mangled and managed - -* Localname deconstruction:: Breaking a localname into its components. -@ifset emacs -* External packages:: Integration with external Lisp packages. -@end ifset - -@end detailmenu -@end menu - -@node Overview -@chapter An overview of @value{tramp} -@cindex overview - -After the installation of @value{tramp} into your @value{emacsname}, you -will be able to access files on remote machines as though they were -local. Access to the remote file system for editing files, version -control, and @code{dired} are transparently enabled. - -Your access to the remote machine can be with the @command{rsh}, -@command{rlogin}, @command{telnet} programs or with any similar -connection method. This connection must pass @acronym{ASCII} -successfully to be usable but need not be 8-bit clean. - -The package provides support for @command{ssh} connections out of the -box, one of the more common uses of the package. This allows -relatively secure access to machines, especially if @command{ftp} -access is disabled. - -Under Windows, @value{tramp} is integrated with the PuTTY package, -using the @command{plink} program. - -The majority of activity carried out by @value{tramp} requires only that -the remote login is possible and is carried out at the terminal. In -order to access remote files @value{tramp} needs to transfer their content -to the local machine temporarily. - -@value{tramp} can transfer files between the machines in a variety of ways. -The details are easy to select, depending on your needs and the -machines in question. - -The fastest transfer methods for large files rely on a remote file -transfer package such as @command{rcp}, @command{scp}, @command{rsync} -or (under Windows) @command{pscp}. - -If the remote copy methods are not suitable for you, @value{tramp} also -supports the use of encoded transfers directly through the shell. -This requires that the @command{mimencode} or @command{uuencode} tools -are available on the remote machine. These methods are generally -faster for small files. - -@value{tramp} is still under active development and any problems you encounter, -trivial or major, should be reported to the @value{tramp} developers. -@xref{Bug Reports}. - - -@subsubheading Behind the scenes -@cindex behind the scenes -@cindex details of operation -@cindex how it works - -This section tries to explain what goes on behind the scenes when you -access a remote file through @value{tramp}. - -Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name, -then hit @kbd{@key{TAB}} for completion. Suppose further that this is -the first time that @value{tramp} is invoked for the host in question. Here's -what happens: - -@itemize -@item -@value{tramp} discovers that it needs a connection to the host. So it -invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l -@var{user}} or a similar tool to connect to the remote host. -Communication with this process happens through an -@value{emacsname} buffer, that is, the output from the remote end -goes into a buffer. - -@item -The remote host may prompt for a login name (for @command{telnet}). -The login name is given in the file name, so @value{tramp} sends the -login name and a newline. - -@item -The remote host may prompt for a password or pass phrase (for -@command{rsh} or for @command{telnet} after sending the login name). -@value{tramp} displays the prompt in the minibuffer, asking you for the -password or pass phrase. - -You enter the password or pass phrase. @value{tramp} sends it to the remote -host, followed by a newline. - -@item -@value{tramp} now waits for the shell prompt or for a message that the login -failed. - -If @value{tramp} sees neither of them after a certain period of time -(a minute, say), then it issues an error message saying that it -couldn't find the remote shell prompt and shows you what the remote -host has sent. - -If @value{tramp} sees a @samp{login failed} message, it tells you so, -aborts the login attempt and allows you to try again. - -@item -Suppose that the login was successful and @value{tramp} sees the shell prompt -from the remote host. Now @value{tramp} invokes @command{/bin/sh} because -Bourne shells and C shells have different command -syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login -shell doesn't recognize @samp{exec /bin/sh} as a valid command. -Maybe you use the Scheme shell @command{scsh}@dots{}} - -After the Bourne shell has come up, @value{tramp} sends a few commands to -ensure a good working environment. It turns off echoing, it sets the -shell prompt, and a few other things. - -@item -Now the remote shell is up and it good working order. Remember, what -was supposed to happen is that @value{tramp} tries to find out what files exist -on the remote host so that it can do filename completion. - -So, @value{tramp} basically issues @command{cd} and @command{ls} commands and -also sometimes @command{echo} with globbing. Another command that is -often used is @command{test} to find out whether a file is writable or a -directory or the like. The output of each command is parsed for the -necessary operation. - -@item -Suppose you are finished with filename completion, have entered @kbd{C-x -C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to -transfer the file contents from the remote host to the local host so -that you can edit them. - -See above for an explanation of how @value{tramp} transfers the file contents. - -For inline transfers, @value{tramp} issues a command like @samp{mimencode -b -/path/to/remote/file}, waits until the output has accumulated in the -buffer that's used for communication, then decodes that output to -produce the file contents. - -For external transfers, @value{tramp} issues a command like the -following: -@example -rcp user@@host:/path/to/remote/file /tmp/tramp.4711 -@end example -It then reads the local temporary file @file{/tmp/tramp.4711} into a -buffer and deletes the temporary file. - -@item -You now edit the buffer contents, blithely unaware of what has happened -behind the scenes. (Unless you have read this section, that is.) When -you are finished, you type @kbd{C-x C-s} to save the buffer. - -@item -Again, @value{tramp} transfers the file contents to the remote host -either inline or external. This is the reverse of what happens when -reading the file. -@end itemize - -I hope this has provided you with a basic overview of what happens -behind the scenes when you open a file with @value{tramp}. - - -@c For the end user -@node Obtaining Tramp -@chapter Obtaining Tramp. -@cindex obtaining Tramp - -@value{tramp} is freely available on the Internet and the latest -release may be downloaded from @uref{ftp://ftp.gnu.org/gnu/tramp/}. -This release includes the full documentation and code for -@value{tramp}, suitable for installation. But Emacs (22 or later) -includes @value{tramp} already, and there is a @value{tramp} package -for XEmacs, as well. So maybe it is easier to just use those. But if -you want the bleeding edge, read on@dots{...} - -For the especially brave, @value{tramp} is available from CVS. The CVS -version is the latest version of the code and may contain incomplete -features or new issues. Use these versions at your own risk. - -Instructions for obtaining the latest development version of @value{tramp} -from CVS can be found by going to the Savannah project page at the -following URL and then clicking on the CVS link in the navigation bar -at the top. - -@noindent -@uref{http://savannah.gnu.org/projects/tramp/} - -@noindent -Or follow the example session below: - -@example -] @strong{cd ~/@value{emacsdir}} -] @strong{export CVS_RSH="ssh"} -] @strong{cvs -z3 -d:pserver:anonymous@@cvs.savannah.gnu.org:/sources/tramp co tramp} -@end example - -@noindent -You should now have a directory @file{~/@value{emacsdir}/tramp} -containing the latest version of @value{tramp}. You can fetch the latest -updates from the repository by issuing the command: - -@example -] @strong{cd ~/@value{emacsdir}/tramp} -] @strong{export CVS_RSH="ssh"} -] @strong{cvs update -d} -@end example - -@noindent -Once you've got updated files from the CVS repository, you need to run -@command{autoconf} in order to get an up-to-date @file{configure} -script: - -@example -] @strong{cd ~/@value{emacsdir}/tramp} -] @strong{autoconf} -@end example - - -@node History -@chapter History of @value{tramp} -@cindex history -@cindex development history - -Development was started end of November 1998. The package was called -@file{rssh.el}, back then. It only provided one method to access a -file, using @command{ssh} to log in to a remote host and using -@command{scp} to transfer the file contents. After a while, the name -was changed to @file{rcp.el}, and now it's @value{tramp}. Along the way, -many more methods for getting a remote shell and for transferring the -file contents were added. Support for VC was added. - -After that, there were added the multi-hop methods in April 2000 and -the unification of @value{tramp} and Ange-FTP filenames in July 2002. -In July 2004, multi-hop methods have been replaced by proxy hosts. -Running commands on remote hosts was introduced in December 2005. -@ifset emacsgw -Support of gateways exists since April 2007. -@end ifset -@ifset emacsgvfs -GVFS integration started in February 2009. -@end ifset - -In December 2001, @value{tramp} has been added to the XEmacs package -repository. Being part of the Emacs repository happened in June 2002, -the first release including @value{tramp} was Emacs 22.1. - -@value{tramp} is also a Debian GNU/Linux package since February 2001. - - -@c Installation chapter is necessary only in case of standalone -@c installation. Text taken from trampinst.texi. -@ifset installchapter -@include trampinst.texi -@end ifset - -@node Configuration -@chapter Configuring @value{tramp} for use -@cindex configuration - -@cindex default configuration -@value{tramp} is (normally) fully functional when it is initially -installed. It is initially configured to use the @command{scp} -program to connect to the remote host. So in the easiest case, you -just type @kbd{C-x C-f} and then enter the filename -@file{@trampfn{, user, machine, /path/to.file}}. - -On some hosts, there are problems with opening a connection. These are -related to the behavior of the remote shell. See @xref{Remote shell -setup}, for details on this. - -If you do not wish to use these commands to connect to the remote -host, you should change the default connection and transfer method -that @value{tramp} uses. There are several different methods that @value{tramp} -can use to connect to remote machines and transfer files -(@pxref{Connection types}). - -If you don't know which method is right for you, see @xref{Default -Method}. - - -@menu -* Connection types:: Types of connections made to remote machines. -* Inline methods:: Inline methods. -* External methods:: External methods. -@ifset emacsgvfs -* GVFS based methods:: GVFS based external methods. -@end ifset -@ifset emacsgw -* Gateway methods:: Gateway methods. -@end ifset -* Default Method:: Selecting a default method. - Here we also try to help those who - don't have the foggiest which method - is right for them. -* Default User:: Selecting a default user. -* Default Host:: Selecting a default host. -* Multi-hops:: Connecting to a remote host using multiple hops. -* Customizing Methods:: Using Non-Standard Methods. -* Customizing Completion:: Selecting config files for user/host name completion. -* Password handling:: Reusing passwords for several connections. -* Connection caching:: Reusing connection related information. -* Remote Programs:: How @value{tramp} finds and uses programs on the remote machine. -* Remote shell setup:: Remote shell setup hints. -* Windows setup hints:: Issues with Cygwin ssh. -* Auto-save and Backup:: Auto-save and Backup. -@end menu - - -@node Connection types -@section Types of connections made to remote machines. -@cindex connection types, overview - -There are two basic types of transfer methods, each with its own -advantages and limitations. Both types of connection make use of a -remote shell access program such as @command{rsh}, @command{ssh} or -@command{telnet} to connect to the remote machine. - -This connection is used to perform many of the operations that @value{tramp} -requires to make the remote file system transparently accessible from -the local machine. It is only when visiting files that the methods -differ. - -@cindex inline methods -@cindex external methods -@cindex methods, inline -@cindex methods, external -Loading or saving a remote file requires that the content of the file -be transferred between the two machines. The content of the file can -be transferred using one of two methods: the @dfn{inline method} over -the same connection used to log in to the remote machine, or the -@dfn{external method} through another connection using a remote copy -program such as @command{rcp}, @command{scp} or @command{rsync}. - -The performance of the external methods is generally better than that -of the inline methods, at least for large files. This is caused by -the need to encode and decode the data when transferring inline. - -The one exception to this rule are the @command{scp} based transfer -methods. While these methods do see better performance when actually -transferring files, the overhead of the cryptographic negotiation at -startup may drown out the improvement in file transfer times. - -External methods should be configured such a way that they don't -require a password (with @command{ssh-agent}, or such alike). Modern -@command{scp} implementations offer options to reuse existing -@command{ssh} connections, see method @command{scpc}. If it isn't -possible, you should consider @ref{Password handling}, otherwise you -will be prompted for a password every copy action. - - -@node Inline methods -@section Inline methods -@cindex inline methods -@cindex methods, inline - -The inline methods in @value{tramp} are quite powerful and can work in -situations where you cannot use an external transfer program to connect. -Inline methods are the only methods that work when connecting to the -remote machine via telnet. (There are also strange inline methods which -allow you to transfer files between @emph{user identities} rather than -hosts, see below.) - -These methods depend on the existence of a suitable encoding and -decoding command on remote machine. Locally, @value{tramp} may be able to -use features of @value{emacsname} to decode and encode the files or -it may require access to external commands to perform that task. - -@cindex uuencode -@cindex mimencode -@cindex base-64 encoding -@value{tramp} checks the availability and usability of commands like -@command{mimencode} (part of the @command{metamail} package) or -@command{uuencode} on the remote host. The first reliable command -will be used. The search path can be customized, see @ref{Remote -Programs}. - -If both commands aren't available on the remote host, @value{tramp} -transfers a small piece of Perl code to the remote host, and tries to -apply it for encoding and decoding. - -The variable @var{tramp-inline-compress-start-size} controls, whether -a file shall be compressed before encoding. This could increase -transfer speed for large text files. - - -@table @asis -@item @option{rsh} -@cindex method rsh -@cindex rsh method - -Connect to the remote host with @command{rsh}. Due to the unsecure -connection it is recommended for very local host topology only. - -On operating systems which provide the command @command{remsh} instead -of @command{rsh}, you can use the method @option{remsh}. This is true -for HP-UX or Cray UNICOS, for example. - - -@item @option{ssh} -@cindex method ssh -@cindex ssh method - -Connect to the remote host with @command{ssh}. This is identical to -the previous option except that the @command{ssh} package is used, -making the connection more secure. - -There are also two variants, @option{ssh1} and @option{ssh2}, that -call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can -explicitly select whether you want to use the SSH protocol version 1 -or 2 to connect to the remote host. (You can also specify in -@file{~/.ssh/config}, the SSH configuration file, which protocol -should be used, and use the regular @option{ssh} method.) - -All the methods based on @command{ssh} have an additional feature: you -can specify a host name which looks like @file{host#42} (the real host -name, then a hash sign, then a port number). This means to connect to -the given host but to also pass @code{-p 42} as arguments to the -@command{ssh} command. - - -@item @option{telnet} -@cindex method telnet -@cindex telnet method - -Connect to the remote host with @command{telnet}. This is as unsecure -as the @option{rsh} method. - - -@item @option{su} -@cindex method su -@cindex su method - -This method does not connect to a remote host at all, rather it uses -the @command{su} program to allow you to edit files as another user. -That means, the specified host name in the file name must be either -@samp{localhost} or the host name as returned by the function -@command{(system-name)}. For an exception of this rule see -@ref{Multi-hops}. - - -@item @option{sudo} -@cindex method sudo -@cindex sudo method - -This is similar to the @option{su} method, but it uses @command{sudo} -rather than @command{su} to become a different user. - -Note that @command{sudo} must be configured to allow you to start a -shell as the user. It would be nice if it was sufficient if -@command{ls} and @command{mimencode} were allowed, but that is not -easy to implement, so I haven't got around to it, yet. - - -@item @option{sshx} -@cindex method sshx -@cindex sshx method - -As you would expect, this is similar to @option{ssh}, only a little -different. Whereas @option{ssh} opens a normal interactive shell on -the remote host, this option uses @samp{ssh -t -t @var{host} -l -@var{user} /bin/sh} to open a connection. This is useful for users -where the normal login shell is set up to ask them a number of -questions when logging in. This procedure avoids these questions, and -just gives @value{tramp} a more-or-less `standard' login shell to work -with. - -Note that this procedure does not eliminate questions asked by -@command{ssh} itself. For example, @command{ssh} might ask ``Are you -sure you want to continue connecting?'' if the host key of the remote -host is not known. @value{tramp} does not know how to deal with such a -question (yet), therefore you will need to make sure that you can log -in without such questions. - -This is also useful for Windows users where @command{ssh}, when -invoked from an @value{emacsname} buffer, tells them that it is not -allocating a pseudo tty. When this happens, the login shell is wont -to not print any shell prompt, which confuses @value{tramp} mightily. - -This supports the @samp{-p} argument. - - -@item @option{krlogin} -@cindex method krlogin -@cindex krlogin method -@cindex Kerberos (with krlogin method) - -This method is also similar to @option{ssh}. It only uses the -@command{krlogin -x} command to log in to the remote host. - - -@item @option{ksu} -@cindex method ksu -@cindex ksu method -@cindex Kerberos (with ksu method) - -This is another method from the Kerberos suite. It behaves like @option{su}. - - -@item @option{plink} -@cindex method plink -@cindex plink method - -This method is mostly interesting for Windows users using the PuTTY -implementation of SSH. It uses @samp{plink -ssh} to log in to the -remote host. - -This supports the @samp{-P} argument. - -Additionally, the methods @option{plink1} and @option{plink2} are -provided, which call @samp{plink -1 -ssh} or @samp{plink -2 -ssh} in -order to use SSH protocol version 1 or 2 explicitly. - -CCC: Do we have to connect to the remote host once from the command -line to accept the SSH key? Maybe this can be made automatic? - -CCC: Say something about the first shell command failing. This might -be due to a wrong setting of @code{tramp-rsh-end-of-line}. - - -@item @option{plinkx} -@cindex method plinkx -@cindex plinkx method - -Another method using PuTTY on Windows. Instead of host names, it -expects PuTTY session names, calling @samp{plink -load @var{session} --t"}. User names are relevant only in case the corresponding session -hasn't defined a user name. Different port numbers must be defined in -the session. - -@end table - - -@node External methods -@section External methods -@cindex methods, external -@cindex external methods - -The external methods operate through multiple channels, using the -remote shell connection for many actions while delegating file -transfers to an external transfer utility. - -This saves the overhead of encoding and decoding that multiplexing the -transfer through the one connection has with the inline methods. - -Since external methods need their own overhead opening a new channel, -all files which are smaller than @var{tramp-copy-size-limit} are still -transferred with the corresponding inline method. It should provide a -fair trade-off between both approaches. - -@table @asis -@item @option{rcp} --- @command{rsh} and @command{rcp} -@cindex method rcp -@cindex rcp method -@cindex rcp (with rcp method) -@cindex rsh (with rcp method) - -This method uses the @command{rsh} and @command{rcp} commands to connect -to the remote machine and transfer files. This is probably the fastest -connection method available. - -The alternative method @option{remcp} uses the @command{remsh} and -@command{rcp} commands. It should be applied on machines where -@command{remsh} is used instead of @command{rsh}. - - -@item @option{scp} --- @command{ssh} and @command{scp} -@cindex method scp -@cindex scp method -@cindex scp (with scp method) -@cindex ssh (with scp method) - -Using @command{ssh} to connect to the remote host and @command{scp} to -transfer files between the machines is the best method for securely -connecting to a remote machine and accessing files. - -The performance of this option is also quite good. It may be slower than -the inline methods when you often open and close small files however. -The cost of the cryptographic handshake at the start of an @command{scp} -session can begin to absorb the advantage that the lack of encoding and -decoding presents. - -There are also two variants, @option{scp1} and @option{scp2}, that -call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can -explicitly select whether you want to use the SSH protocol version 1 -or 2 to connect to the remote host. (You can also specify in -@file{~/.ssh/config}, the SSH configuration file, which protocol -should be used, and use the regular @option{scp} method.) - -All the @command{ssh} based methods support the @samp{-p} feature -where you can specify a port number to connect to in the host name. -For example, the host name @file{host#42} tells @value{tramp} to -specify @samp{-p 42} in the argument list for @command{ssh}, and to -specify @samp{-P 42} in the argument list for @command{scp}. - - -@item @option{sftp} --- @command{ssh} and @command{sftp} -@cindex method sftp -@cindex sftp method -@cindex sftp (with sftp method) -@cindex ssh (with sftp method) - -That is mostly the same method as @option{scp}, but using -@command{sftp} as transfer command. So the same remarks are valid. - -This command does not work like @value{ftppackagename}, where -@command{ftp} is called interactively, and all commands are send from -within this session. Instead of, @command{ssh} is used for login. - -This method supports the @samp{-p} argument. - - -@item @option{rsync} --- @command{ssh} and @command{rsync} -@cindex method rsync -@cindex rsync method -@cindex rsync (with rsync method) -@cindex ssh (with rsync method) - -Using the @command{ssh} command to connect securely to the remote -machine and the @command{rsync} command to transfer files is almost -identical to the @option{scp} method. - -While @command{rsync} performs much better than @command{scp} when -transferring files that exist on both hosts, this advantage is lost if -the file exists only on one side of the connection. A file can exists -on both the remote and local host, when you copy a file from/to a -remote host. When you just open a file from the remote host (or write -a file there), a temporary file on the local side is kept as long as -the corresponding buffer, visiting this file, is alive. - -This method supports the @samp{-p} argument. - - -@item @option{scpx} --- @command{ssh} and @command{scp} -@cindex method scpx -@cindex scpx method -@cindex scp (with scpx method) -@cindex ssh (with scpx method) - -As you would expect, this is similar to @option{scp}, only a little -different. Whereas @option{scp} opens a normal interactive shell on -the remote host, this option uses @samp{ssh -t -t @var{host} -l -@var{user} /bin/sh} to open a connection. This is useful for users -where the normal login shell is set up to ask them a number of -questions when logging in. This procedure avoids these questions, and -just gives @value{tramp} a more-or-less `standard' login shell to work -with. - -This is also useful for Windows users where @command{ssh}, when -invoked from an @value{emacsname} buffer, tells them that it is not -allocating a pseudo tty. When this happens, the login shell is wont -to not print any shell prompt, which confuses @value{tramp} mightily. - -This method supports the @samp{-p} argument. - - -@item @option{scpc} --- @command{ssh} and @command{scp} -@cindex method scpc -@cindex scpc method -@cindex scp (with scpc method) -@cindex ssh (with scpc method) - -Newer versions of @option{ssh} (for example OpenSSH 4) offer an option -@option{ControlMaster}. This allows @option{scp} to reuse an existing -@option{ssh} channel, which increases performance. - -Before you use this method, you should check whether your @option{ssh} -implementation supports this option. Try from the command line - -@example -ssh localhost -o ControlMaster=yes /bin/true -@end example - -If that command succeeds silently, then you can use @option{scpc}; but -if it fails like - -@example -command-line: line 0: Bad configuration option: ControlMaster -@end example - -then you cannot use it. - -This method supports the @samp{-p} argument. - - -@item @option{rsyncc} --- @command{ssh} and @command{rsync} -@cindex method rsyncc -@cindex rsyncc method -@cindex rsync (with rsyncc method) -@cindex ssh (with rsyncc method) - -Like the @option{scpc} method, @option{rsyncc} improves the underlying -@command{ssh} connection by the option @option{ControlMaster}. This -allows @command{rsync} to reuse an existing @command{ssh} channel, -which increases performance. - -This method supports the @samp{-p} argument. - - -@item @option{pscp} --- @command{plink} and @command{pscp} -@cindex method pscp -@cindex pscp method -@cindex pscp (with pscp method) -@cindex plink (with pscp method) -@cindex PuTTY (with pscp method) - -This method is similar to @option{scp}, but it uses the -@command{plink} command to connect to the remote host, and it uses -@command{pscp} for transferring the files. These programs are part -of PuTTY, an SSH implementation for Windows. - -This method supports the @samp{-P} argument. - - -@item @option{psftp} --- @command{plink} and @command{psftp} -@cindex method psftp -@cindex psftp method -@cindex psftp (with psftp method) -@cindex plink (with psftp method) -@cindex PuTTY (with psftp method) - -As you would expect, this method is similar to @option{sftp}, but it -uses the @command{plink} command to connect to the remote host, and it -uses @command{psftp} for transferring the files. These programs are -part of PuTTY, an SSH implementation for Windows. - -This method supports the @samp{-P} argument. - - -@item @option{fcp} --- @command{fsh} and @command{fcp} -@cindex method fcp -@cindex fcp method -@cindex fsh (with fcp method) -@cindex fcp (with fcp method) - -This method is similar to @option{scp}, but it uses the @command{fsh} -command to connect to the remote host, and it uses @command{fcp} for -transferring the files. @command{fsh/fcp} are a front-end for -@command{ssh} which allow for reusing the same @command{ssh} session -for submitting several commands. This avoids the startup overhead of -@command{scp} (which has to establish a secure connection whenever it -is called). Note, however, that you can also use one of the inline -methods to achieve a similar effect. - -This method uses the command @samp{fsh @var{host} -l @var{user} -/bin/sh -i} to establish the connection, it does not work to just say -@command{fsh @var{host} -l @var{user}}. - -@cindex method fsh -@cindex fsh method - -There is no inline method using @command{fsh} as the multiplexing -provided by the program is not very useful in our context. @value{tramp} -opens just one connection to the remote host and then keeps it open, -anyway. - - -@item @option{ftp} -@cindex method ftp -@cindex ftp method - -This is not a native @value{tramp} method. Instead, it forwards all -requests to @value{ftppackagename}. -@ifset xemacs -This works only for unified filenames, see @ref{Issues}. -@end ifset - - -@item @option{smb} --- @command{smbclient} -@cindex method smb -@cindex smb method - -This is another not natural @value{tramp} method. It uses the -@command{smbclient} command on different Unices in order to connect to -an SMB server. An SMB server might be a Samba (or CIFS) server on -another UNIX host or, more interesting, a host running MS Windows. So -far, it is tested against MS Windows NT, MS Windows 2000, and MS -Windows XP. - -The first directory in the localname must be a share name on the remote -host. Remember that the @code{$} character, in which default shares -usually end, must be written @code{$$} due to environment variable -substitution in file names. If no share name is given (i.e. remote -directory @code{/}), all available shares are listed. - -Since authorization is done on share level, you will always be -prompted for a password if you access another share on the same host. -This can be suppressed by @ref{Password handling}. - -For authorization, MS Windows uses both a user name and a domain name. -Because of this, the @value{tramp} syntax has been extended: you can -specify a user name which looks like @code{user%domain} (the real user -name, then a percent sign, then the domain name). So, to connect to -the machine @code{melancholia} as user @code{daniel} of the domain -@code{BIZARRE}, and edit @file{.emacs} in the home directory (share -@code{daniel$}) I would specify the filename @file{@trampfn{smb, -daniel%BIZARRE, melancholia, /daniel$$/.emacs}}. - -Depending on the Windows domain configuration, a Windows user might be -considered as domain user per default. In order to connect as local -user, the WINS name of that machine must be given as domain name. -Usually, it is the machine name in capital letters. In the example -above, the local user @code{daniel} would be specified as -@file{@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}. - -The domain name as well as the user name are optional. If no user -name is specified at all, the anonymous user (without password -prompting) is assumed. This is different from all other @value{tramp} -methods, where in such a case the local user name is taken. - -The @option{smb} method supports the @samp{-p} argument. - -@strong{Please note:} If @value{emacsname} runs locally under MS -Windows, this method isn't available. Instead, you can use UNC -file names like @file{//melancholia/daniel$$/.emacs}. The only -disadvantage is that there's no possibility to specify another user -name. -@end table - - -@ifset emacsgvfs -@node GVFS based methods -@section GVFS based external methods -@cindex methods, gvfs -@cindex gvfs based methods -@cindex dbus - -The connection methods described in this section are based on GVFS -@uref{http://en.wikipedia.org/wiki/GVFS}. Via GVFS, the remote -filesystem is mounted locally through FUSE. @value{tramp} uses -this local mounted directory internally. - -The communication with GVFS is implemented via D-Bus messages. -Therefore, your @value{emacsname} must have D-Bus integration, -@pxref{Top, , D-Bus, dbus}. - -@table @asis -@item @option{dav} -@cindex method dav -@cindex method davs -@cindex dav method -@cindex davs method - -This method provides access to WebDAV files and directories. There -exists also the external method @option{davs}, which uses SSL -encryption for the access. - -Both methods support the port number specification as discussed above. - - -@item @option{obex} -@cindex method obex -@cindex obex method - -OBEX is an FTP-like access protocol for simple devices, like cell -phones. For the time being, @value{tramp} only supports OBEX over Bluetooth. - - -@item @option{synce} -@cindex method synce -@cindex synce method - -The @option{synce} method allows communication with Windows Mobile -devices. Beside GVFS for mounting remote files and directories via -FUSE, it also needs the SYNCE-GVFS plugin. -@end table - -@defopt tramp-gvfs-methods -This customer option, a list, defines the external methods which -shall be used with GVFS. Per default, these are @option{dav}, -@option{davs}, @option{obex} and @option{synce}. Other possible -values are @option{ftp}, @option{sftp} and @option{smb}. -@end defopt -@end ifset - - -@ifset emacsgw -@node Gateway methods -@section Gateway methods -@cindex methods, gateway -@cindex gateway methods - -Gateway methods are not methods to access a remote host directly. -These methods are intended to pass firewalls or proxy servers. -Therefore, they can be used for proxy host declarations -(@pxref{Multi-hops}) only. - -A gateway method must always come along with a method which supports -port setting. This is because @value{tramp} targets the accompanied -method to @file{localhost#random_port}, from where the firewall or -proxy server is accessed. - -Gateway methods support user name and password declarations. These -are used to authenticate towards the corresponding firewall or proxy -server. They can be passed only if your friendly administrator has -granted your access. - -@table @asis -@item @option{tunnel} -@cindex method tunnel -@cindex tunnel method - -This method implements an HTTP tunnel via the @command{CONNECT} -command (see RFC 2616, 2817). Any HTTP 1.1 compliant (proxy) server -shall support this command. - -As authentication method, only @option{Basic Authentication} (see RFC -2617) is implemented so far. If no port number is given in the -declaration, port @option{8080} is used for the proxy server. - - -@item @option{socks} -@cindex method socks -@cindex socks method - -The @command{socks} method provides access to SOCKSv5 servers (see -RFC 1928). @option{Username/Password Authentication} according to RFC -1929 is supported. - -The default port number of the socks server is @option{1080}, if not -specified otherwise. - -@end table -@end ifset - - -@node Default Method -@section Selecting a default method -@cindex default method - -@vindex tramp-default-method -When you select an appropriate transfer method for your typical usage -you should set the variable @code{tramp-default-method} to reflect that -choice. This variable controls which method will be used when a method -is not specified in the @value{tramp} file name. For example: - -@lisp -(setq tramp-default-method "ssh") -@end lisp - -@vindex tramp-default-method-alist -You can also specify different methods for certain user/host -combinations, via the variable @code{tramp-default-method-alist}. For -example, the following two lines specify to use the @option{ssh} -method for all user names matching @samp{john} and the @option{rsync} -method for all host names matching @samp{lily}. The third line -specifies to use the @option{su} method for the user @samp{root} on -the machine @samp{localhost}. - -@lisp -(add-to-list 'tramp-default-method-alist '("" "john" "ssh")) -(add-to-list 'tramp-default-method-alist '("lily" "" "rsync")) -(add-to-list 'tramp-default-method-alist - '("\\`localhost\\'" "\\`root\\'" "su")) -@end lisp - -@noindent -See the documentation for the variable -@code{tramp-default-method-alist} for more details. - -External methods are normally preferable to inline methods, giving -better performance. - -@xref{Inline methods}. -@xref{External methods}. - -Another consideration with the selection of transfer methods is the -environment you will use them in and, especially when used over the -Internet, the security implications of your preferred method. - -The @option{rsh} and @option{telnet} methods send your password as -plain text as you log in to the remote machine, as well as -transferring the files in such a way that the content can easily be -read from other machines. - -If you need to connect to remote systems that are accessible from the -Internet, you should give serious thought to using @option{ssh} based -methods to connect. These provide a much higher level of security, -making it a non-trivial exercise for someone to obtain your password -or read the content of the files you are editing. - - -@subsection Which method is the right one for me? -@cindex choosing the right method - -Given all of the above, you are probably thinking that this is all fine -and good, but it's not helping you to choose a method! Right you are. -As a developer, we don't want to boss our users around but give them -maximum freedom instead. However, the reality is that some users would -like to have some guidance, so here I'll try to give you this guidance -without bossing you around. You tell me whether it works @dots{} - -My suggestion is to use an inline method. For large files, external -methods might be more efficient, but I guess that most people will -want to edit mostly small files. And if you access large text files, -compression (driven by @var{tramp-inline-compress-start-size}) shall -still result in good performance. - -I guess that these days, most people can access a remote machine by -using @command{ssh}. So I suggest that you use the @option{ssh} -method. So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost, -/etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other -host. - -If you can't use @option{ssh} to log in to the remote host, then -select a method that uses a program that works. For instance, Windows -users might like the @option{plink} method which uses the PuTTY -implementation of @command{ssh}. Or you use Kerberos and thus like -@option{krlogin}. - -For the special case of editing files on the local host as another -user, see the @option{su} or @option{sudo} methods. They offer -shortened syntax for the @samp{root} account, like -@file{@trampfn{su, , , /etc/motd}}. - -People who edit large files may want to consider @option{scpc} instead -of @option{ssh}, or @option{pscp} instead of @option{plink}. These -external methods are faster than inline methods for large files. -Note, however, that external methods suffer from some limitations. -Please try first whether you really get a noticeable speed advantage -from using an external method! Maybe even for large files, inline -methods are fast enough. - - -@node Default User -@section Selecting a default user -@cindex default user - -The user part of a @value{tramp} file name can be omitted. Usually, -it is replaced by the user name you are logged in. Often, this is not -what you want. A typical use of @value{tramp} might be to edit some -files with root permissions on the local host. This case, you should -set the variable @code{tramp-default-user} to reflect that choice. -For example: - -@lisp -(setq tramp-default-user "root") -@end lisp - -@code{tramp-default-user} is regarded as obsolete, and will be removed -soon. - -@vindex tramp-default-user-alist -You can also specify different users for certain method/host -combinations, via the variable @code{tramp-default-user-alist}. For -example, if you always have to use the user @samp{john} in the domain -@samp{somewhere.else}, you can specify the following: - -@lisp -(add-to-list 'tramp-default-user-alist - '("ssh" ".*\\.somewhere\\.else\\'" "john")) -@end lisp - -@noindent -See the documentation for the variable -@code{tramp-default-user-alist} for more details. - -One trap to fall in must be known. If @value{tramp} finds a default -user, this user will be passed always to the connection command as -parameter (for example @samp{ssh here.somewhere.else -l john}. If you -have specified another user for your command in its configuration -files, @value{tramp} cannot know it, and the remote access will fail. -If you have specified in the given example in @file{~/.ssh/config} the -lines - -@example -Host here.somewhere.else - User lily -@end example - -@noindent -than you must discard selecting a default user by @value{tramp}. This -will be done by setting it to @code{nil} (or @samp{lily}, likewise): - -@lisp -(add-to-list 'tramp-default-user-alist - '("ssh" "\\`here\\.somewhere\\.else\\'" nil)) -@end lisp - -The last entry in @code{tramp-default-user-alist} could be your -default user you'll apply predominantly. You shall @emph{append} it -to that list at the end: - -@lisp -(add-to-list 'tramp-default-user-alist '(nil nil "jonas") t) -@end lisp - - -@node Default Host -@section Selecting a default host -@cindex default host - -@vindex tramp-default-host -Finally, it is even possible to omit the host name part of a -@value{tramp} file name. This case, the value of the variable -@code{tramp-default-host} is used. Per default, it is initialized -with the host name your local @value{emacsname} is running. - -If you, for example, use @value{tramp} mainly to contact the host -@samp{target} as user @samp{john}, you can specify: - -@lisp -(setq tramp-default-user "john" - tramp-default-host "target") -@end lisp - -Then the simple file name @samp{@trampfn{ssh, , ,}} will connect you -to John's home directory on target. -@ifset emacs -Note, however, that the most simplification @samp{/::} won't work, -because @samp{/:} is the prefix for quoted file names. -@end ifset - - -@node Multi-hops -@section Connecting to a remote host using multiple hops -@cindex multi-hop -@cindex proxy hosts - -Sometimes, the methods described before are not sufficient. Sometimes, -it is not possible to connect to a remote host using a simple command. -For example, if you are in a secured network, you might have to log in -to a `bastion host' first before you can connect to the outside world. -Of course, the target host may also require a bastion host. - -@vindex tramp-default-proxies-alist -In order to specify such multiple hops, it is possible to define a proxy -host to pass through, via the variable -@code{tramp-default-proxies-alist}. This variable keeps a list of -triples (@var{host} @var{user} @var{proxy}). - - The first matching item specifies the proxy host to be passed for a -file name located on a remote target matching @var{user}@@@var{host}. -@var{host} and @var{user} are regular expressions or @code{nil}, which -is interpreted as a regular expression which always matches. - -@var{proxy} must be a Tramp filename which localname part is ignored. -Method and user name on @var{proxy} are optional, which is interpreted -with the default values. -@ifset emacsgw -The method must be an inline or gateway method (@pxref{Inline -methods}, @pxref{Gateway methods}). -@end ifset -@ifclear emacsgw -The method must be an inline method (@pxref{Inline methods}). -@end ifclear -If @var{proxy} is @code{nil}, no additional hop is required reaching -@var{user}@@@var{host}. - -If you, for example, must pass the host @samp{bastion.your.domain} as -user @samp{bird} for any remote host which is not located in your local -domain, you can set - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}")) -(add-to-list 'tramp-default-proxies-alist - '("\\.your\\.domain\\'" nil nil)) -@end lisp - -Please note the order of the code. @code{add-to-list} adds elements at the -beginning of a list. Therefore, most relevant rules must be added last. - -Proxy hosts can be cascaded. If there is another host called -@samp{jump.your.domain}, which is the only one in your local domain who -is allowed connecting @samp{bastion.your.domain}, you can add another -rule: - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\`bastion\\.your\\.domain\\'" - "\\`bird\\'" - "@trampfn{ssh, , jump.your.domain,}")) -@end lisp - -@var{proxy} can contain the patterns @code{%h} or @code{%u}. These -patterns are replaced by the strings matching @var{host} or -@var{user}, respectively. - -If you, for example, wants to work as @samp{root} on hosts in the -domain @samp{your.domain}, but login as @samp{root} is disabled for -non-local access, you might add the following rule: - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}")) -@end lisp - -Opening @file{@trampfn{sudo, , randomhost.your.domain,}} would connect -first @samp{randomhost.your.domain} via @code{ssh} under your account -name, and perform @code{sudo -u root} on that host afterwards. It is -important to know that the given method is applied on the host which -has been reached so far. @code{sudo -u root}, applied on your local -host, wouldn't be useful here. - -@var{host}, @var{user} and @var{proxy} can also be Lisp forms. These -forms are evaluated, and must return a string, or @code{nil}. The -previous example could be generalized then: For all hosts except my -local one connect via @code{ssh} first, and apply @code{sudo -u root} -afterwards: - -@lisp -(add-to-list 'tramp-default-proxies-alist - '(nil "\\`root\\'" "@trampfn{ssh, , %h,}")) -(add-to-list 'tramp-default-proxies-alist - '((regexp-quote (system-name)) nil nil)) -@end lisp - -This is the recommended configuration to work as @samp{root} on remote -Ubuntu hosts. - -@ifset emacsgw -Finally, @code{tramp-default-proxies-alist} can be used to pass -firewalls or proxy servers. Imagine your local network has a host -@samp{proxy.your.domain} which is used on port 3128 as HTTP proxy to -the outer world. Your friendly administrator has granted you access -under your user name to @samp{host.other.domain} on that proxy -server.@footnote{HTTP tunnels are intended for secure SSL/TLS -communication. Therefore, many proxy server restrict the tunnels to -related target ports. You might need to run your ssh server on your -target host @samp{host.other.domain} on such a port, like 443 (https). -See @uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall} -for discussion of ethical issues.} You would need to add the -following rule: - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\`host\\.other\\.domain\\'" nil - "@trampfn{tunnel, , proxy.your.domain#3128,}")) -@end lisp - -Gateway methods can be declared as first hop only in a multiple hop -chain. -@end ifset - - -@node Customizing Methods -@section Using Non-Standard Methods -@cindex customizing methods -@cindex using non-standard methods -@cindex create your own methods - -There is a variable @code{tramp-methods} which you can change if the -predefined methods don't seem right. - -For the time being, I'll refer you to the Lisp documentation of that -variable, accessible with @kbd{C-h v tramp-methods @key{RET}}. - - -@node Customizing Completion -@section Selecting config files for user/host name completion -@cindex customizing completion -@cindex selecting config files -@vindex tramp-completion-function-alist - -The variable @code{tramp-completion-function-alist} is intended to -customize which files are taken into account for user and host name -completion (@pxref{Filename completion}). For every method, it keeps -a set of configuration files, accompanied by a Lisp function able to -parse that file. Entries in @code{tramp-completion-function-alist} -have the form (@var{method} @var{pair1} @var{pair2} ...). - -Each @var{pair} is composed of (@var{function} @var{file}). -@var{function} is responsible to extract user names and host names -from @var{file} for completion. There are two functions which access -this variable: - -@defun tramp-get-completion-function method -This function returns the list of completion functions for @var{method}. - -Example: -@example -(tramp-get-completion-function "rsh") - - @result{} ((tramp-parse-rhosts "/etc/hosts.equiv") - (tramp-parse-rhosts "~/.rhosts")) -@end example -@end defun - -@defun tramp-set-completion-function method function-list -This function sets @var{function-list} as list of completion functions -for @var{method}. - -Example: -@example -(tramp-set-completion-function "ssh" - '((tramp-parse-sconfig "/etc/ssh_config") - (tramp-parse-sconfig "~/.ssh/config"))) - - @result{} ((tramp-parse-sconfig "/etc/ssh_config") - (tramp-parse-sconfig "~/.ssh/config")) -@end example -@end defun - -The following predefined functions parsing configuration files exist: - -@table @asis -@item @code{tramp-parse-rhosts} -@findex tramp-parse-rhosts - -This function parses files which are syntactical equivalent to -@file{~/.rhosts}. It returns both host names and user names, if -specified. - -@item @code{tramp-parse-shosts} -@findex tramp-parse-shosts - -This function parses files which are syntactical equivalent to -@file{~/.ssh/known_hosts}. Since there are no user names specified -in such files, it can return host names only. - -@item @code{tramp-parse-sconfig} -@findex tramp-parse-shosts - -This function returns the host nicknames defined by @code{Host} entries -in @file{~/.ssh/config} style files. - -@item @code{tramp-parse-shostkeys} -@findex tramp-parse-shostkeys - -SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and -@file{~/ssh2/hostkeys/*}. Hosts are coded in file names -@file{hostkey_@var{portnumber}_@var{host-name}.pub}. User names -are always @code{nil}. - -@item @code{tramp-parse-sknownhosts} -@findex tramp-parse-shostkeys - -Another SSH2 style parsing of directories like -@file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This -case, hosts names are coded in file names -@file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}. - -@item @code{tramp-parse-hosts} -@findex tramp-parse-hosts - -A function dedicated to @file{/etc/hosts} style files. It returns -host names only. - -@item @code{tramp-parse-passwd} -@findex tramp-parse-passwd - -A function which parses @file{/etc/passwd} like files. Obviously, it -can return user names only. - -@item @code{tramp-parse-netrc} -@findex tramp-parse-netrc - -Finally, a function which parses @file{~/.netrc} like files. This -includes also @file{~/.authinfo}-style files. -@end table - -If you want to keep your own data in a file, with your own structure, -you might provide such a function as well. This function must meet -the following conventions: - -@defun my-tramp-parse file -@var{file} must be either a file name on your host, or @code{nil}. -The function must return a list of (@var{user} @var{host}), which are -taken as candidates for user and host name completion. - -Example: -@example -(my-tramp-parse "~/.my-tramp-hosts") - - @result{} ((nil "toto") ("daniel" "melancholia")) -@end example -@end defun - - -@node Password handling -@section Reusing passwords for several connections. -@cindex passwords - -Sometimes it is necessary to connect to the same remote host several -times. Reentering passwords again and again would be annoying, when -the chosen method does not support access without password prompt -through own configuration. - -The best recommendation is to use the method's own mechanism for -password handling. Consider @command{ssh-agent} for @option{ssh}-like -methods, or @command{pageant} for @option{plink}-like methods. - -However, if you cannot apply such native password handling, -@value{tramp} offers alternatives. - - -@anchor{Using an authentication file} -@subsection Using an authentication file - -@vindex auth-sources -The package @file{auth-source.el}, originally developed in No Gnus, -offers the possibility to read passwords from a file, like FTP does it -from @file{~/.netrc}. The default authentication file is -@file{~/.authinfo.gpg}, this can be changed via the variable -@code{auth-sources}. - -@noindent -A typical entry in the authentication file would be - -@example -machine melancholia port scp login daniel password geheim -@end example - -The port can be any @value{tramp} method (@pxref{Inline methods}, -@pxref{External methods}), to match only this method. When you omit -the port, you match all @value{tramp} methods. - -In case of problems, setting @code{auth-source-debug} to @code{t} -gives useful debug messages. - - -@anchor{Caching passwords} -@subsection Caching passwords - -If there is no authentication file, @value{tramp} caches the passwords -entered by you. They will be reused next time if a connection needs -them for the same user name and host name, independently of the -connection method. - -@vindex password-cache-expiry -Passwords are not saved permanently, that means the password caching -is limited to the lifetime of your @value{emacsname} session. You -can influence the lifetime of password caching by customizing the -variable @code{password-cache-expiry}. The value is the number of -seconds how long passwords are cached. Setting it to @code{nil} -disables the expiration. - -@vindex password-cache -If you don't like this feature for security reasons, password caching -can be disabled totally by customizing the variable -@code{password-cache} (setting it to @code{nil}). - -Implementation Note: password caching is based on the package -@file{password-cache.el}. For the time being, it is activated only -when this package is seen in the @code{load-path} while loading -@value{tramp}. -@ifset installchapter -If you don't use No Gnus, you can take @file{password.el} from the -@value{tramp} @file{contrib} directory, see @ref{Installation -parameters}. -@end ifset - - -@node Connection caching -@section Reusing connection related information. -@cindex caching - -@vindex tramp-persistency-file-name -In order to reduce initial connection time, @value{tramp} stores -connection related information persistently. The variable -@code{tramp-persistency-file-name} keeps the file name where these -information are written. Its default value is -@ifset emacs -@file{~/.emacs.d/tramp}. -@end ifset -@ifset xemacs -@file{~/.xemacs/tramp}. -@end ifset -It is recommended to choose a local file name. - -@value{tramp} reads this file during startup, and writes it when -exiting @value{emacsname}. You can simply remove this file if -@value{tramp} shall be urged to recompute these information next -@value{emacsname} startup time. - -Using such persistent information can be disabled by setting -@code{tramp-persistency-file-name} to @code{nil}. - -Once consequence of reusing connection related information is that -@var{tramp} needs to distinguish hosts. If you, for example, run a -local @code{sshd} on port 3001, which tunnels @command{ssh} to another -host, you could access both @file{@trampfn{ssh, , localhost,}} and -@file{@trampfn{ssh, , localhost#3001,}}. @var{tramp} would use the -same host related information (like paths, Perl variants, etc) for -both connections, although the information is valid only for one of -them. - -In order to avoid trouble, you must use another host name for one of -the connections, like introducing a @option{Host} section in -@file{~/.ssh/config} (@pxref{Frequently Asked Questions}) or applying -multiple hops (@pxref{Multi-hops}). - -When @value{tramp} detects a changed operating system version on a -remote host (via the command @command{uname -sr}), it flushes all -connection related information for this host, and opens the -connection again. - - -@node Remote Programs -@section How @value{tramp} finds and uses programs on the remote machine. - -@value{tramp} depends on a number of programs on the remote host in order to -function, including @command{ls}, @command{test}, @command{find} and -@command{cat}. - -In addition to these required tools, there are various tools that may be -required based on the connection method. See @ref{Inline methods} and -@ref{External methods} for details on these. - -Certain other tools, such as @command{perl} (or @command{perl5}) and -@command{grep} will be used if they can be found. When they are -available, they are used to improve the performance and accuracy of -remote file access. - -@vindex tramp-remote-path -@vindex tramp-default-remote-path -@vindex tramp-own-remote-path -@defopt tramp-remote-path -When @value{tramp} connects to the remote machine, it searches for the -programs that it can use. The variable @code{tramp-remote-path} -controls the directories searched on the remote machine. - -By default, this is set to a reasonable set of defaults for most -machines. The symbol @code{tramp-default-remote-path} is a place -holder, it is replaced by the list of directories received via the -command @command{getconf PATH} on your remote machine. For example, -on Debian GNU/Linux this is @file{/bin:/usr/bin}, whereas on Solaris -this is @file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. -It is recommended to apply this symbol on top of -@code{tramp-remote-path}. - -It is possible, however, that your local (or remote ;) system -administrator has put the tools you want in some obscure local -directory. - -In this case, you can still use them with @value{tramp}. You simply -need to add code to your @file{.emacs} to add the directory to the -remote path. This will then be searched by @value{tramp} when you -connect and the software found. - -To add a directory to the remote search path, you could use code such -as: - -@lisp -@i{;; We load @value{tramp} to define the variable.} -(require 'tramp) -@i{;; We have @command{perl} in "/usr/local/perl/bin"} -(add-to-list 'tramp-remote-path "/usr/local/perl/bin") -@end lisp - -Another possibility is to reuse the path settings of your remote -account when you log in. Usually, these settings are overwritten, -because they might not be useful for @value{tramp}. The place holder -@code{tramp-own-remote-path} preserves these settings. You can -activate it via - -@lisp -(add-to-list 'tramp-remote-path 'tramp-own-remote-path) -@end lisp -@end defopt - -@value{tramp} caches several information, like the Perl binary -location. The changed remote search path wouldn't affect these -settings. In order to force @value{tramp} to recompute these values, -you must exit @value{emacsname}, remove your persistency file -(@pxref{Connection caching}), and restart @value{emacsname}. - - -@node Remote shell setup -@section Remote shell setup hints -@cindex remote shell setup -@cindex @file{.profile} file -@cindex @file{.login} file -@cindex shell init files - -As explained in the @ref{Overview} section, @value{tramp} connects to the -remote host and talks to the shell it finds there. Of course, when you -log in, the shell executes its init files. Suppose your init file -requires you to enter the birth date of your mother; clearly @value{tramp} -does not know this and hence fails to log you in to that host. - -There are different possible strategies for pursuing this problem. One -strategy is to enable @value{tramp} to deal with all possible situations. -This is a losing battle, since it is not possible to deal with -@emph{all} situations. The other strategy is to require you to set up -the remote host such that it behaves like @value{tramp} expects. This might -be inconvenient because you have to invest a lot of effort into shell -setup before you can begin to use @value{tramp}. - -The package, therefore, pursues a combined approach. It tries to -figure out some of the more common setups, and only requires you to -avoid really exotic stuff. For example, it looks through a list of -directories to find some programs on the remote host. And also, it -knows that it is not obvious how to check whether a file exists, and -therefore it tries different possibilities. (On some hosts and -shells, the command @command{test -e} does the trick, on some hosts -the shell builtin doesn't work but the program @command{/usr/bin/test --e} or @command{/bin/test -e} works. And on still other hosts, -@command{ls -d} is the right way to do this.) - -Below you find a discussion of a few things that @value{tramp} does not deal -with, and that you therefore have to set up correctly. - -@table @asis -@item @var{shell-prompt-pattern} -@vindex shell-prompt-pattern - -After logging in to the remote host, @value{tramp} has to wait for the remote -shell startup to finish before it can send commands to the remote -shell. The strategy here is to wait for the shell prompt. In order to -recognize the shell prompt, the variable @code{shell-prompt-pattern} has -to be set correctly to recognize the shell prompt on the remote host. - -Note that @value{tramp} requires the match for @code{shell-prompt-pattern} -to be at the end of the buffer. Many people have something like the -following as the value for the variable: @code{"^[^>$][>$] *"}. Now -suppose your shell prompt is @code{a c $ }. In this case, -@value{tramp} recognizes the @code{>} character as the end of the prompt, -but it is not at the end of the buffer. - -@item @var{tramp-shell-prompt-pattern} -@vindex tramp-shell-prompt-pattern - -This regular expression is used by @value{tramp} in the same way as -@code{shell-prompt-pattern}, to match prompts from the remote shell. -This second variable exists because the prompt from the remote shell -might be different from the prompt from a local shell --- after all, -the whole point of @value{tramp} is to log in to remote hosts as a -different user. The default value of -@code{tramp-shell-prompt-pattern} is the same as the default value of -@code{shell-prompt-pattern}, which is reported to work well in many -circumstances. - -@item @var{tramp-password-prompt-regexp} -@vindex tramp-password-prompt-regexp -@vindex tramp-wrong-passwd-regexp - -During login, @value{tramp} might be forced to enter a password or a -passphrase. The difference between both is that a password is -requested from the shell on the remote host, while a passphrase is -needed for accessing local authentication information, like your ssh -key. - -@var{tramp-password-prompt-regexp} handles the detection of such -requests for English environments. When you use another localization -of your (local or remote) host, you might need to adapt this. Example: - -@lisp -(setq - tramp-password-prompt-regexp - (concat - "^.*" - (regexp-opt - '("passphrase" "Passphrase" - ;; English - "password" "Password" - ;; Deutsch - "passwort" "Passwort" - ;; Fran@,{c}ais - "mot de passe" "Mot de passe") t) - ".*:? *")) -@end lisp - -In parallel, it might also be necessary to adapt -@var{tramp-wrong-passwd-regexp}. - -@item @command{tset} and other questions -@cindex Unix command tset -@cindex tset Unix command - -Some people invoke the @command{tset} program from their shell startup -scripts which asks the user about the terminal type of the shell. -Maybe some shells ask other questions when they are started. -@value{tramp} does not know how to answer these questions. There are -two approaches for dealing with this problem. One approach is to take -care that the shell does not ask any questions when invoked from -@value{tramp}. You can do this by checking the @code{TERM} -environment variable, it will be set to @code{dumb} when connecting. - -@vindex tramp-terminal-type -The variable @code{tramp-terminal-type} can be used to change this value -to @code{dumb}. - -@vindex tramp-actions-before-shell -The other approach is to teach @value{tramp} about these questions. See -the variable @code{tramp-actions-before-shell}. Example: - -@lisp -(defconst my-tramp-prompt-regexp - (concat (regexp-opt '("Enter the birth date of your mother:") t) - "\\s-*") - "Regular expression matching my login prompt question.") - -(defun my-tramp-action (proc vec) - "Enter \"19000101\" in order to give a correct answer." - (save-window-excursion - (with-current-buffer (tramp-get-connection-buffer vec) - (tramp-message vec 6 "\n%s" (buffer-string)) - (tramp-send-string vec "19000101")))) - -(add-to-list 'tramp-actions-before-shell - '(my-tramp-prompt-regexp my-tramp-action)) -@end lisp - - -@item Environment variables named like users in @file{.profile} - -If you have a user named frumple and set the variable @code{FRUMPLE} in -your shell environment, then this might cause trouble. Maybe rename -the variable to @code{FRUMPLE_DIR} or the like. - -This weird effect was actually reported by a @value{tramp} user! - - -@item Non-Bourne commands in @file{.profile} - -After logging in to the remote host, @value{tramp} issues the command -@command{exec /bin/sh}. (Actually, the command is slightly -different.) When @command{/bin/sh} is executed, it reads some init -files, such as @file{~/.shrc} or @file{~/.profile}. - -Now, some people have a login shell which is not @code{/bin/sh} but a -Bourne-ish shell such as bash or ksh. Some of these people might put -their shell setup into the files @file{~/.shrc} or @file{~/.profile}. -This way, it is possible for non-Bourne constructs to end up in those -files. Then, @command{exec /bin/sh} might cause the Bourne shell to -barf on those constructs. - -As an example, imagine somebody putting @command{export FOO=bar} into -the file @file{~/.profile}. The standard Bourne shell does not -understand this syntax and will emit a syntax error when it reaches -this line. - -Another example is the tilde (@code{~}) character, say when adding -@file{~/bin} to @code{PATH}. Many Bourne shells will not expand this -character, and since there is usually no directory whose name consists -of the single character tilde, strange things will happen. - -What can you do about this? - -Well, one possibility is to make sure that everything in -@file{~/.shrc} and @file{~/.profile} on all remote hosts is -Bourne-compatible. In the above example, instead of @command{export -FOO=bar}, you might use @command{FOO=bar; export FOO} instead. - -The other possibility is to put your non-Bourne shell setup into some -other files. For example, bash reads the file @file{~/.bash_profile} -instead of @file{~/.profile}, if the former exists. So bash -aficionados just rename their @file{~/.profile} to -@file{~/.bash_profile} on all remote hosts, and Bob's your uncle. - -The @value{tramp} developers would like to circumvent this problem, so -if you have an idea about it, please tell us. However, we are afraid -it is not that simple: before saying @command{exec /bin/sh}, -@value{tramp} does not know which kind of shell it might be talking -to. It could be a Bourne-ish shell like ksh or bash, or it could be a -csh derivative like tcsh, or it could be zsh, or even rc. If the -shell is Bourne-ish already, then it might be prudent to omit the -@command{exec /bin/sh} step. But how to find out if the shell is -Bourne-ish? - - -@item Interactive shell prompt - -@value{tramp} redefines the shell prompt in order to parse the shell's -output robustly. When calling an interactive shell by @kbd{M-x -shell}, this doesn't look nice. - -You can redefine the shell prompt by checking the environment variable -@code{INSIDE_EMACS}, which is set by @value{tramp}, in your startup -script @file{~/.emacs_SHELLNAME}. @code{SHELLNAME} might be the string -@code{bash} or similar, in case of doubt you could set it the -environment variable @code{ESHELL} in your @file{.emacs}: - -@lisp -(setenv "ESHELL" "bash") -@end lisp - -Your file @file{~/.emacs_SHELLNAME} could contain code like - -@example -# Reset the prompt for remote Tramp shells. -if [ "$@{INSIDE_EMACS/*tramp*/tramp@}" == "tramp" ] ; then - PS1="[\u@@\h \w]$ " -fi -@end example - -@ifinfo -@ifset emacs -@xref{Interactive Shell, , , @value{emacsdir}}. -@end ifset -@end ifinfo - -@end table - - -@node Auto-save and Backup -@section Auto-save and Backup configuration -@cindex auto-save -@cindex backup -@ifset emacs -@vindex backup-directory-alist -@end ifset -@ifset xemacs -@vindex bkup-backup-directory-info -@end ifset - -Normally, @value{emacsname} writes backup files to the same directory -as the original files, but this behavior can be changed via the -variable -@ifset emacs -@code{backup-directory-alist}. -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info}. -@end ifset -In connection with @value{tramp}, this can have unexpected side -effects. Suppose that you specify that all backups should go to the -directory @file{~/.emacs.d/backups/}, and then you edit the file -@file{@trampfn{su, root, localhost, /etc/secretfile}}. The effect is -that the backup file will be owned by you and not by root, thus -possibly enabling others to see it even if they were not intended to -see it. - -When -@ifset emacs -@code{backup-directory-alist} -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info} -@end ifset -is @code{nil} (the default), such problems do not occur. - -Therefore, it is useful to set special values for @value{tramp} -files. For example, the following statement effectively `turns off' -the effect of -@ifset emacs -@code{backup-directory-alist} -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info} -@end ifset -for @value{tramp} files: - -@ifset emacs -@lisp -(add-to-list 'backup-directory-alist - (cons tramp-file-name-regexp nil)) -@end lisp -@end ifset -@ifset xemacs -@lisp -(require 'backup-dir) -(add-to-list 'bkup-backup-directory-info - (list tramp-file-name-regexp "")) -@end lisp -@end ifset - -@ifset emacs -It is also possible to disable backups depending on the used method. -The following code disables backups for the @option{su} and -@option{sudo} methods: - -@lisp -(setq backup-enable-predicate - (lambda (name) - (and (normal-backup-enable-predicate name) - (not - (let ((method (file-remote-p name 'method))) - (when (stringp method) - (member method '("su" "sudo")))))))) -@end lisp -@end ifset - - -Another possibility is to use the @value{tramp} variable -@ifset emacs -@code{tramp-backup-directory-alist}. -@end ifset -@ifset xemacs -@code{tramp-bkup-backup-directory-info}. -@end ifset -This variable has the same meaning like -@ifset emacs -@code{backup-directory-alist}. -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info}. -@end ifset -If a @value{tramp} file is backed up, and DIRECTORY is an absolute -local file name, DIRECTORY is prepended with the @value{tramp} file -name prefix of the file to be backed up. - -@noindent -Example: - -@ifset emacs -@lisp -(add-to-list 'backup-directory-alist - (cons "." "~/.emacs.d/backups/")) -(setq tramp-backup-directory-alist backup-directory-alist) -@end lisp -@end ifset -@ifset xemacs -@lisp -(require 'backup-dir) -(add-to-list 'bkup-backup-directory-info - (list "." "~/.emacs.d/backups/" 'full-path)) -(setq tramp-bkup-backup-directory-info bkup-backup-directory-info) -@end lisp -@end ifset - -@noindent -The backup file name of @file{@trampfn{su, root, localhost, -/etc/secretfile}} would be -@ifset emacs -@file{@trampfn{su, root, localhost, -~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}} -@end ifset -@ifset xemacs -@file{@trampfn{su, root, localhost, -~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}} -@end ifset - -The same problem can happen with auto-saving files. -@ifset emacs -The variable @code{auto-save-file-name-transforms} keeps information, -on which directory an auto-saved file should go. By default, it is -initialized for @value{tramp} files to the local temporary directory. - -On some versions of @value{emacsname}, namely the version built for -Debian GNU/Linux, the variable @code{auto-save-file-name-transforms} -contains the directory where @value{emacsname} was built. A -workaround is to manually set the variable to a sane value. - -If auto-saved files should go into the same directory as the original -files, @code{auto-save-file-name-transforms} should be set to @code{nil}. - -Another possibility is to set the variable -@code{tramp-auto-save-directory} to a proper value. -@end ifset -@ifset xemacs -For this purpose you can set the variable @code{auto-save-directory} -to a proper value. -@end ifset - - -@node Windows setup hints -@section Issues with Cygwin ssh -@cindex Cygwin, issues - -This section needs a lot of work! Please help. - -@cindex method sshx with Cygwin -@cindex sshx method with Cygwin -The recent Cygwin installation of @command{ssh} works only with a -Cygwinized @value{emacsname}. You can check it by typing @kbd{M-x -eshell}, and starting @kbd{ssh test.machine}. The problem is evident -if you see a message like this: - -@example -Pseudo-terminal will not be allocated because stdin is not a terminal. -@end example - -Older @command{ssh} versions of Cygwin are told to cooperate with -@value{tramp} selecting @option{sshx} as the connection method. You -can find information about setting up Cygwin in their FAQ at -@uref{http://cygwin.com/faq/}. - -@cindex method scpx with Cygwin -@cindex scpx method with Cygwin -If you wish to use the @option{scpx} connection method, then you might -have the problem that @value{emacsname} calls @command{scp} with a -Windows filename such as @code{c:/foo}. The Cygwin version of -@command{scp} does not know about Windows filenames and interprets -this as a remote filename on the host @code{c}. - -One possible workaround is to write a wrapper script for @option{scp} -which converts the Windows filename to a Cygwinized filename. - -@cindex Cygwin and ssh-agent -@cindex SSH_AUTH_SOCK and @value{emacsname} on Windows -If you want to use either @option{ssh} based method on Windows, then -you might encounter problems with @command{ssh-agent}. Using this -program, you can avoid typing the pass-phrase every time you log in. -However, if you start @value{emacsname} from a desktop shortcut, then -the environment variable @code{SSH_AUTH_SOCK} is not set and so -@value{emacsname} and thus @value{tramp} and thus @command{ssh} and -@command{scp} started from @value{tramp} cannot communicate with -@command{ssh-agent}. It works better to start @value{emacsname} from -the shell. - -If anyone knows how to start @command{ssh-agent} under Windows in such a -way that desktop shortcuts can profit, please holler. I don't really -know anything at all about Windows@dots{} - - -@node Usage -@chapter Using @value{tramp} -@cindex using @value{tramp} - -Once you have installed @value{tramp} it will operate fairly -transparently. You will be able to access files on any remote machine -that you can log in to as though they were local. - -Files are specified to @value{tramp} using a formalized syntax specifying the -details of the system to connect to. This is similar to the syntax used -by the @value{ftppackagename} package. - -@cindex type-ahead -Something that might happen which surprises you is that -@value{emacsname} remembers all your keystrokes, so if you see a -password prompt from @value{emacsname}, say, and hit @kbd{@key{RET}} -twice instead of once, then the second keystroke will be processed by -@value{emacsname} after @value{tramp} has done its thing. Why, this -type-ahead is normal behavior, you say. Right you are, but be aware -that opening a remote file might take quite a while, maybe half a -minute when a connection needs to be opened. Maybe after half a -minute you have already forgotten that you hit that key! - -@menu -* Filename Syntax:: @value{tramp} filename conventions. -* Alternative Syntax:: URL-like filename syntax. -* Filename completion:: Filename completion. -* Remote processes:: Integration with other @value{emacsname} packages. -* Cleanup remote connections:: Cleanup remote connections. -@end menu - - -@node Filename Syntax -@section @value{tramp} filename conventions -@cindex filename syntax -@cindex filename examples - -To access the file @var{localname} on the remote machine @var{machine} -you would specify the filename @file{@trampfn{, , machine, -localname}}. This will connect to @var{machine} and transfer the file -using the default method. @xref{Default Method}. - -Some examples of @value{tramp} filenames are shown below. - -@table @file -@item @trampfn{, , melancholia, .emacs} -Edit the file @file{.emacs} in your home directory on the machine -@code{melancholia}. - -@item @trampfn{, , melancholia.danann.net, .emacs} -This edits the same file, using the fully qualified domain name of -the machine. - -@item @trampfn{, , melancholia, ~/.emacs} -This also edits the same file --- the @file{~} is expanded to your -home directory on the remote machine, just like it is locally. - -@item @trampfn{, , melancholia, ~daniel/.emacs} -This edits the file @file{.emacs} in the home directory of the user -@code{daniel} on the machine @code{melancholia}. The @file{~} -construct is expanded to the home directory of that user on the remote -machine. - -@item @trampfn{, , melancholia, /etc/squid.conf} -This edits the file @file{/etc/squid.conf} on the machine -@code{melancholia}. - -@end table - -@var{machine} can also be an IPv4 or IPv6 address, like in -@file{@trampfn{, , 127.0.0.1, .emacs}} or @file{@trampfn{, , -@value{ipv6prefix}::1@value{ipv6postfix}, .emacs}}. -@ifset emacs -For syntactical reasons, IPv6 addresses must be embedded in square -brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}. -@end ifset - -Unless you specify a different name to use, @value{tramp} will use the -current local user name as the remote user name to log in with. If you -need to log in as a different user, you can specify the user name as -part of the filename. - -To log in to the remote machine as a specific user, you use the syntax -@file{@trampfn{, user, machine, path/to.file}}. That means that -connecting to @code{melancholia} as @code{daniel} and editing -@file{.emacs} in your home directory you would specify -@file{@trampfn{, daniel, melancholia, .emacs}}. - -It is also possible to specify other file transfer methods -(@pxref{Inline methods}, @pxref{External methods}) as part of the -filename. -@ifset emacs -This is done by putting the method before the user and host name, as -in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the -trailing colon). -@end ifset -@ifset xemacs -This is done by replacing the initial @file{@value{prefix}} with -@file{@value{prefix}@value{postfixhop}}. (Note the trailing -slash!). -@end ifset -The user, machine and file specification remain the same. - -So, to connect to the machine @code{melancholia} as @code{daniel}, -using the @option{ssh} method to transfer files, and edit -@file{.emacs} in my home directory I would specify the filename -@file{@trampfn{ssh, daniel, melancholia, .emacs}}. - -Finally, for some methods it is possible to specify a different port -number than the default one, given by the method. This is specified -by adding @file{#} to the host name, like in @file{@trampfn{ssh, -daniel, melancholia#42, .emacs}}. - - -@node Alternative Syntax -@section URL-like filename syntax -@cindex filename syntax -@cindex filename examples - -Additionally to the syntax described in the previous chapter, it is -possible to use a URL-like syntax for @value{tramp}. This can be -switched on by customizing the variable @code{tramp-syntax}. Please -note that this feature is experimental for the time being. - -The variable @code{tramp-syntax} must be set before requiring @value{tramp}: - -@lisp -(setq tramp-syntax 'url) -(require 'tramp) -@end lisp - -Then, a @value{tramp} filename would look like this: -@file{/@var{method}://@var{user}@@@var{machine}:@var{port}/@var{path/to.file}}. -@file{/@var{method}://} is mandatory, all other parts are optional. -@file{:@var{port}} is useful for methods only who support this. - -The last example from the previous section would look like this: -@file{/ssh://daniel@@melancholia/.emacs}. - -For the time being, @code{tramp-syntax} can have the following values: - -@itemize @w{} -@ifset emacs -@item @code{ftp} -- That is the default syntax -@item @code{url} -- URL-like syntax -@end ifset -@ifset xemacs -@item @code{sep} -- That is the default syntax -@item @code{url} -- URL-like syntax -@item @code{ftp} -- EFS-like syntax -@end ifset -@end itemize - - -@node Filename completion -@section Filename completion -@cindex filename completion - -Filename completion works with @value{tramp} for completion of method -names, of user names and of machine names as well as for completion of -file names on remote machines. -@ifset emacs -In order to enable this, partial completion must be activated in your -@file{.emacs}. -@ifinfo -@xref{Completion Options, , , @value{emacsdir}}. -@end ifinfo -@end ifset - -If you, for example, type @kbd{C-x C-f @value{prefix}t -@key{TAB}}, @value{tramp} might give you as result the choice for - -@example -@multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}} -@ifset emacs -@item @value{prefixhop}telnet@value{postfixhop} @tab tmp/ -@item @value{prefixhop}toto@value{postfix} @tab -@end ifset -@ifset xemacs -@item @value{prefixhop}telnet@value{postfixhop} @tab @value{prefixhop}toto@value{postfix} -@end ifset -@end multitable -@end example - -@samp{@value{prefixhop}telnet@value{postfixhop}} -is a possible completion for the respective method, -@ifset emacs -@samp{tmp/} stands for the directory @file{/tmp} on your local -machine, -@end ifset -and @samp{@value{prefixhop}toto@value{postfix}} -might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts} -file (given you're using default method @option{ssh}). - -If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to -@samp{@value{prefix}telnet@value{postfixhop}}. -Next @kbd{@key{TAB}} brings you all machine names @value{tramp} detects in -your @file{/etc/hosts} file, let's say - -@example -@multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}} -@item @trampfn{telnet, , 127.0.0.1,} @tab @trampfn{telnet, , 192.168.0.1,} -@item @trampfn{telnet, , @value{ipv6prefix}::1@value{ipv6postfix},} @tab @trampfn{telnet, , localhost,} -@item @trampfn{telnet, , melancholia.danann.net,} @tab @trampfn{telnet, , melancholia,} -@end multitable -@end example - -Now you can choose the desired machine, and you can continue to -complete file names on that machine. - -If the configuration files (@pxref{Customizing Completion}), which -@value{tramp} uses for analysis of completion, offer user names, those user -names will be taken into account as well. - -Remote machines which have been visited in the past and kept -persistently (@pxref{Connection caching}) will be offered too. - -Once the remote machine identification is completed, it comes to -filename completion on the remote host. This works pretty much like -for files on the local host, with the exception that minibuffer -killing via a double-slash works only on the filename part, except -that filename part starts with @file{//}. -@ifset emacs -A triple-slash stands for the default behavior. -@end ifset -@ifinfo -@xref{Minibuffer File, , , @value{emacsdir}}. -@end ifinfo - -@noindent -Example: - -@example -@ifset emacs -@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin//etc} @key{TAB}} - @print{} @trampfn{telnet, , melancholia, /etc} - -@kbd{C-x C-f @trampfn{telnet, , melancholia, //etc} @key{TAB}} - @print{} /etc - -@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin///etc} @key{TAB}} - @print{} /etc -@end ifset - -@ifset xemacs -@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin//}} - @print{} @trampfn{telnet, , melancholia, /} - -@kbd{C-x C-f @trampfn{telnet, , melancholia, //}} - @print{} / -@end ifset -@end example - -A remote directory might have changed its contents out of -@value{emacsname} control, for example by creation or deletion of -files by other processes. Therefore, during filename completion, the -remote directory contents are reread regularly in order to detect such -changes, which would be invisible otherwise (@pxref{Connection caching}). - -@defopt tramp-completion-reread-directory-timeout -This variable defines the number of seconds since last remote command -before rereading a directory contents. A value of 0 would require an -immediate reread during filename completion, @code{nil} means to use -always cached values for the directory contents. -@end defopt - - -@node Remote processes -@section Integration with other @value{emacsname} packages. -@cindex compile -@cindex recompile - -@value{tramp} supports running processes on a remote host. This -allows to exploit @value{emacsname} packages without modification for -remote file names. It does not work for the @option{ftp} and -@option{smb} methods. Association of a pty, as specified in -@code{start-file-process}, is not supported. - -@code{process-file} and @code{start-file-process} work on the remote -host when the variable @code{default-directory} is remote: - -@lisp -(let ((default-directory "/ssh:remote.host:")) - (start-file-process "grep" (get-buffer-create "*grep*") - "/bin/sh" "-c" "grep -e tramp *")) -@end lisp - -@ifset emacsgvfs -If the remote host is mounted via GVFS (see @ref{GVFS based methods}), -the remote filesystem is mounted locally. Therefore, there are no -remote processes; all processes run still locally on your machine with -an adapted @code{default-directory}. This section does not apply for -such connection methods. -@end ifset - -Remote processes are started when a corresponding command is executed -from a buffer belonging to a remote file or directory. Up to now, the -packages @file{compile.el} (commands like @code{compile} and -@code{grep}) and @file{gud.el} (@code{gdb} or @code{perldb}) have been -integrated. Integration of further packages is planned, any help for -this is welcome! - -When your program is not found in the default search path -@value{tramp} sets on the remote machine, you should either use an -absolute path, or extend @code{tramp-remote-path} (see @ref{Remote -Programs}): - -@lisp -(add-to-list 'tramp-remote-path "~/bin") -(add-to-list 'tramp-remote-path "/appli/pub/bin") -@end lisp - -The environment for your program can be adapted by customizing -@code{tramp-remote-process-environment}. This variable is a list of -strings. It is structured like @code{process-environment}. Each -element is a string of the form ENVVARNAME=VALUE. An entry -ENVVARNAME= disables the corresponding environment variable, which -might have been set in your init file like @file{~/.profile}. - -@noindent -Adding an entry can be performed via @code{add-to-list}: - -@lisp -(add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java") -@end lisp - -Changing or removing an existing entry is not encouraged. The default -values are chosen for proper @value{tramp} work. Nevertheless, if for -example a paranoid system administrator disallows changing the -@code{HISTORY} environment variable, you can customize -@code{tramp-remote-process-environment}, or you can apply the -following code in your @file{.emacs}: - -@lisp -(let ((process-environment tramp-remote-process-environment)) - (setenv "HISTORY" nil) - (setq tramp-remote-process-environment process-environment)) -@end lisp - -If you use other @value{emacsname} packages which do not run -out-of-the-box on a remote host, please let us know. We will try to -integrate them as well. @xref{Bug Reports}. - - -@subsection Running remote programs that create local X11 windows - -If you want to run a remote program, which shall connect the X11 -server you are using with your local host, you can set the -@code{DISPLAY} environment variable on the remote host: - -@lisp -(add-to-list 'tramp-remote-process-environment - (format "DISPLAY=%s" (getenv "DISPLAY"))) -@end lisp - -@noindent -@code{(getenv "DISPLAY")} shall return a string containing a host -name, which can be interpreted on the remote host; otherwise you might -use a fixed host name. Strings like @code{:0} cannot be used properly -on the remote host. - -Another trick might be that you put @code{ForwardX11 yes} or -@code{ForwardX11Trusted yes} to your @file{~/.ssh/config} file for -that host. - - -@subsection Running @code{shell} on a remote host -@cindex shell - -Calling @code{M-x shell} in a buffer related to a remote host runs the -local shell as defined in @option{shell-file-name}. This might be -also a valid path name for a shell to be applied on the remote host, -but it will fail at least when your local and remote hosts belong to -different system types, like @samp{windows-nt} and @samp{gnu/linux}. - -You must set the variable @option{explicit-shell-file-name} to the -shell path name on the remote host, in order to start that shell on -the remote host. - -@ifset emacs -Starting with Emacs 24 this won't be necessary, if you call -@code{shell} interactively. You will be asked for the remote shell -path, if you are on a remote buffer, and if -@option{explicit-shell-file-name} is equal to @code{nil}. -@end ifset - - -@subsection Running @code{shell-command} on a remote host -@cindex shell-command - -@code{shell-command} allows to execute commands in a shell, either -synchronously, either asynchronously. This works also on remote -hosts. Example: - -@example -@kbd{C-x C-f @trampfn{sudo, , , } @key{RET}} -@kbd{M-! tail -f /var/log/syslog.log & @key{RET}} -@end example - -You will see the buffer @file{*Async Shell Command*}, containing the -continuous output of the @command{tail} command. - - -@subsection Running @code{eshell} on a remote host -@cindex eshell - -@value{tramp} is integrated into @file{eshell.el}. That is, you can -open an interactive shell on your remote host, and run commands there. -After you have started @code{M-x eshell}, you could perform commands -like this: - -@example -@b{~ $} cd @trampfn{sudo, , , /etc} @key{RET} -@b{@trampfn{sudo, root, host, /etc} $} hostname @key{RET} -host -@b{@trampfn{sudo, root, host, /etc} $} id @key{RET} -uid=0(root) gid=0(root) groups=0(root) -@b{@trampfn{sudo, root, host, /etc} $} find-file shadow @key{RET} -# -@b{@trampfn{sudo, root, host, /etc} $} -@end example - -@ifset emacs -Since @value{emacsname} 23.2, @code{eshell} has also an own -implementation of the @code{su} and @code{sudo} commands. Both -commands change the default directory of the @file{*eshell*} buffer to -the value related to the user the command has switched to. This works -even on remote hosts, adding silently a corresponding entry to the -variable @code{tramp-default-proxies-alist} (@pxref{Multi-hops}): - -@example -@b{~ $} cd @trampfn{ssh, user, remotehost, /etc} @key{RET} -@b{@trampfn{ssh, user, remotehost, /etc} $} find-file shadow @key{RET} -File is not readable: @trampfn{ssh, user, remotehost, /etc/shadow} -@b{@trampfn{ssh, user, remotehost, /etc} $} sudo find-file shadow @key{RET} -# - -@b{@trampfn{ssh, user, remotehost, /etc} $} su - @key{RET} -@b{@trampfn{su, root, remotehost, /root} $} id @key{RET} -uid=0(root) gid=0(root) groups=0(root) -@b{@trampfn{su, root, remotehost, /root} $} -@end example -@end ifset - - -@anchor{Running a debugger on a remote host} -@subsection Running a debugger on a remote host -@cindex gud -@cindex gdb -@cindex perldb - -@file{gud.el} offers an unified interface to several symbolic -debuggers -@ifset emacs -@ifinfo -(@ref{Debuggers, , , @value{emacsdir}}). -@end ifinfo -@end ifset -With @value{tramp}, it is possible to debug programs on -remote hosts. You can call @code{gdb} with a remote file name: - -@example -@kbd{M-x gdb @key{RET}} -@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host, ~/myprog} @key{RET} -@end example - -The file name can also be relative to a remote default directory. -Given you are in a buffer that belongs to the remote directory -@trampfn{ssh, , host, /home/user}, you could call - -@example -@kbd{M-x perldb @key{RET}} -@b{Run perldb (like this):} perl -d myprog.pl @key{RET} -@end example - -It is not possible to use just the absolute local part of a remote -file name as program to debug, like @kbd{perl -d -/home/user/myprog.pl}, though. - -Arguments of the program to be debugged are taken literally. That -means, file names as arguments must be given as ordinary relative or -absolute file names, without any remote specification. - - -@node Cleanup remote connections -@section Cleanup remote connections. -@cindex cleanup - -Sometimes it is useful to cleanup remote connections. The following -commands support this. - -@deffn Command tramp-cleanup-connection vec -This command flushes all connection related objects. @option{vec} is -the internal representation of a remote connection. Called -interactively, the command offers all active remote connections in the -minibuffer as remote file name prefix like @file{@trampfn{method, -user, host, }}. The cleanup includes password cache (@pxref{Password -handling}), file cache, connection cache (@pxref{Connection caching}), -connection buffers. -@end deffn - -@deffn Command tramp-cleanup-this-connection -This command flushes all objects of the current buffer's remote -connection. The same objects are removed as in -@code{tramp-cleanup-connection}. -@end deffn - -@deffn Command tramp-cleanup-all-connections -This command flushes objects for all active remote connections. The -same objects are removed as in @code{tramp-cleanup-connection}. -@end deffn - -@deffn Command tramp-cleanup-all-buffers -Like in @code{tramp-cleanup-all-connections}, all remote connections -are cleaned up. Additionally all buffers, which are related to a -remote connection, are killed. -@end deffn - - -@node Bug Reports -@chapter Reporting Bugs and Problems -@cindex bug reports - -Bugs and problems with @value{tramp} are actively worked on by the -development team. Feature requests and suggestions are also more than -welcome. - -The @value{tramp} mailing list is a great place to get information on -working with @value{tramp}, solving problems and general discussion -and advice on topics relating to the package. It is moderated so -non-subscribers can post but messages will be delayed, possibly up to -48 hours (or longer in case of holidays), until the moderator approves -your message. - -The mailing list is at @email{tramp-devel@@gnu.org}. Messages sent to -this address go to all the subscribers. This is @emph{not} the address -to send subscription requests to. - -Subscribing to the list is performed via -@uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/, -the @value{tramp} Mail Subscription Page}. - -@findex tramp-bug -To report a bug in @value{tramp}, you should execute @kbd{M-x -tramp-bug}. This will automatically generate a buffer with the details -of your system and @value{tramp} version. - -When submitting a bug report, please try to describe in excruciating -detail the steps required to reproduce the problem, the setup of the -remote machine and any special conditions that exist. You should also -check that your problem is not described already in @xref{Frequently -Asked Questions}. - -If you can identify a minimal test case that reproduces the problem, -include that with your bug report. This will make it much easier for -the development team to analyze and correct the problem. - -Before reporting the bug, you should set the verbosity level to 6 -(@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file and -repeat the bug. Then, include the contents of the @file{*tramp/foo*} -and @file{*debug tramp/foo*} buffers in your bug report. A verbosity -level greater than 6 will produce a very huge debug buffer, which is -mostly not necessary for the analysis. - -Please be aware that, with a verbosity level of 6 or greater, the -contents of files and directories will be included in the debug -buffer. Passwords you've typed will never be included there. - - -@node Frequently Asked Questions -@chapter Frequently Asked Questions -@cindex frequently asked questions -@cindex FAQ - -@itemize @bullet -@item -Where can I get the latest @value{tramp}? - -@value{tramp} is available under the URL below. - -@noindent -@uref{ftp://ftp.gnu.org/gnu/tramp/} - -@noindent -There is also a Savannah project page. - -@noindent -@uref{http://savannah.gnu.org/projects/tramp/} - - -@item -Which systems does it work on? - -The package has been used successfully on Emacs 22, Emacs 23, Emacs -24, XEmacs 21 (starting with 21.4), and SXEmacs 22. - -The package was intended to work on Unix, and it really expects a -Unix-like system on the remote end (except the @option{smb} method), -but some people seemed to have some success getting it to work on MS -Windows XP/Vista/7 @value{emacsname}. - - -@item -How could I speed up @value{tramp}? - -In the backstage, @value{tramp} needs a lot of operations on the -remote host. The time for transferring data from and to the remote -host as well as the time needed to perform the operations there count. -In order to speed up @value{tramp}, one could either try to avoid some -of the operations, or one could try to improve their performance. - -Use an external method, like @option{scpc}. - -Use caching. This is already enabled by default. Information about -the remote host as well as the remote files are cached for reuse. The -information about remote hosts is kept in the file specified in -@code{tramp-persistency-file-name}. Keep this file. If you are -confident that files on remote hosts are not changed out of -@value{emacsname}' control, set @code{remote-file-name-inhibit-cache} -to @code{nil}. - -Disable version control. If you access remote files which are not -under version control, a lot of check operations can be avoided by -disabling VC. This can be achieved by - -@lisp -(setq vc-ignore-dir-regexp - (format "\\(%s\\)\\|\\(%s\\)" - vc-ignore-dir-regexp - tramp-file-name-regexp)) -@end lisp - -Disable excessive traces. The default trace level of @value{tramp}, -defined in the variable @code{tramp-verbose}, is 3. You should -increase this level only temporarily, hunting bugs. - - -@item -@value{tramp} does not connect to the remote host - -When @value{tramp} does not connect to the remote host, there are three -reasons heading the bug mailing list: - -@itemize @minus -@item -Unknown characters in the prompt - -@value{tramp} needs to recognize the prompt on the remote machine -after execution any command. This is not possible when the prompt -contains unknown characters like escape sequences for coloring. This -should be avoided on the remote side. @xref{Remote shell setup}. for -setting the regular expression detecting the prompt. - -You can check your settings after an unsuccessful connection by -switching to the @value{tramp} connection buffer @file{*tramp/foo*}, -setting the cursor at the top of the buffer, and applying the expression - -@example -@kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))} -@end example - -If it fails, or the cursor is not moved at the end of the buffer, your -prompt is not recognized correctly. - -A special problem is the zsh, which uses left-hand side and right-hand -side prompts in parallel. Therefore, it is necessary to disable the -zsh line editor on the remote host. You shall add to @file{~/.zshrc} -the following command: - -@example -[ $TERM = "dumb" ] && unsetopt zle && PS1='$ ' -@end example - -Furthermore it has been reported, that @value{tramp} (like sshfs, -incidentally) doesn't work with WinSSHD due to strange prompt settings. - -@item -Echoed characters after login - -When the remote machine opens an echoing shell, there might be control -characters in the welcome message. @value{tramp} tries to suppress -such echoes via the @code{stty -echo} command, but sometimes this -command is not reached, because the echoed output has confused -@value{tramp} already. In such situations it might be helpful to use -the @option{sshx} or @option{scpx} methods, which allocate a pseudo tty. -@xref{Inline methods}. - -@item -@value{tramp} doesn't transfer strings with more than 500 characters -correctly - -On some few systems, the implementation of @code{process-send-string} -seems to be broken for longer strings. It is reported for HP-UX, -FreeBSD and Tru64 Unix, for example. This case, you should customize -the variable @code{tramp-chunksize} to 500. For a description how to -determine whether this is necessary see the documentation of -@code{tramp-chunksize}. - -Additionally, it will be useful to set @code{file-precious-flag} to -@code{t} for @value{tramp} files. Then the file contents will be -written into a temporary file first, which is checked for correct -checksum. -@ifinfo -@pxref{Saving Buffers, , , elisp} -@end ifinfo - -@lisp -(add-hook - 'find-file-hooks - '(lambda () - (when (file-remote-p default-directory) - (set (make-local-variable 'file-precious-flag) t)))) -@end lisp -@end itemize - - -@item -@value{tramp} does not recognize hung @command{ssh} sessions - -When your network connection is down, @command{ssh} sessions might -hang. @value{tramp} cannot detect it safely, because it still sees a -running @command{ssh} process. Timeouts cannot be used as well, -because it cannot be predicted how long a remote command will last, -for example when copying very large files. - -Therefore, you must configure the @command{ssh} process to die -in such a case. The following entry in @file{~/.ssh/config} would do -the job: - -@example -Host * - ServerAliveInterval 5 -@end example - - -@item -File name completion does not work with @value{tramp} - -When you log in to the remote machine, do you see the output of -@command{ls} in color? If so, this may be the cause of your problems. - -@command{ls} outputs @acronym{ANSI} escape sequences that your terminal -emulator interprets to set the colors. These escape sequences will -confuse @value{tramp} however. - -In your @file{.bashrc}, @file{.profile} or equivalent on the remote -machine you probably have an alias configured that adds the option -@option{--color=yes} or @option{--color=auto}. - -You should remove that alias and ensure that a new login @emph{does not} -display the output of @command{ls} in color. If you still cannot use -filename completion, report a bug to the @value{tramp} developers. - - -@item -File name completion does not work in large directories - -@value{tramp} uses globbing for some operations. (Globbing means to use the -shell to expand wildcards such as `*.c'.) This might create long -command lines, especially in directories with many files. Some shells -choke on long command lines, or don't cope well with the globbing -itself. - -If you have a large directory on the remote end, you may wish to execute -a command like @samp{ls -d * ..?* > /dev/null} and see if it hangs. -Note that you must first start the right shell, which might be -@command{/bin/sh}, @command{ksh} or @command{bash}, depending on which -of those supports tilde expansion. - - -@item -How can I get notified when @value{tramp} file transfers are complete? - -The following snippet can be put in your @file{~/.emacs} file. It -makes @value{emacsname} beep after reading from or writing to the -remote host. - -@lisp -(defadvice tramp-handle-write-region - (after tramp-write-beep-advice activate) - "Make tramp beep after writing a file." - (interactive) - (beep)) - -(defadvice tramp-handle-do-copy-or-rename-file - (after tramp-copy-beep-advice activate) - "Make tramp beep after copying a file." - (interactive) - (beep)) - -(defadvice tramp-handle-insert-file-contents - (after tramp-insert-beep-advice activate) - "Make tramp beep after inserting a file." - (interactive) - (beep)) -@end lisp - - -@ifset emacs -@item -I'ld like to get a Visual Warning when working in a sudo:ed context - -When you are working with @samp{root} privileges, it might be useful -to get an indication in the buffer's modeline. The following code, -tested with @value{emacsname} 22.1, does the job. You should put it -into your @file{~/.emacs}: - -@lisp -(defun my-mode-line-function () - (when (string-match "^/su\\(do\\)?:" default-directory) - (setq mode-line-format - (format-mode-line mode-line-format 'font-lock-warning-face)))) - -(add-hook 'find-file-hooks 'my-mode-line-function) -(add-hook 'dired-mode-hook 'my-mode-line-function) -@end lisp -@end ifset - - -@ifset emacs -@item -I'ld like to see a host indication in the mode line when I'm remote - -The following code has been tested with @value{emacsname} 22.1. You -should put it into your @file{~/.emacs}: - -@lisp -(defconst my-mode-line-buffer-identification - (list - '(:eval - (let ((host-name - (if (file-remote-p default-directory) - (tramp-file-name-host - (tramp-dissect-file-name default-directory)) - (system-name)))) - (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name) - (substring host-name 0 (match-beginning 1)) - host-name))) - ": %12b")) - -(setq-default - mode-line-buffer-identification - my-mode-line-buffer-identification) - -(add-hook - 'dired-mode-hook - '(lambda () - (setq - mode-line-buffer-identification - my-mode-line-buffer-identification))) -@end lisp - -Since @value{emacsname} 23.1, the mode line contains an indication if -@code{default-directory} for the current buffer is on a remote host. -The corresponding tooltip includes the name of that host. If you -still want the host name as part of the mode line, you can use the -example above, but the @code{:eval} clause can be simplified: - -@lisp - '(:eval - (let ((host-name - (or (file-remote-p default-directory 'host) - (system-name)))) - (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name) - (substring host-name 0 (match-beginning 1)) - host-name))) -@end lisp -@end ifset - - -@ifset emacs -@item -My remote host does not understand default directory listing options - -@value{emacsname} computes the @command{dired} options depending on -the local host you are working. If your @command{ls} command on the -remote host does not understand those options, you can change them -like this: - -@lisp -(add-hook - 'dired-before-readin-hook - '(lambda () - (when (file-remote-p default-directory) - (setq dired-actual-switches "-al")))) -@end lisp -@end ifset - - -@item -There's this @file{~/.sh_history} file on the remote host which keeps -growing and growing. What's that? - -Sometimes, @value{tramp} starts @command{ksh} on the remote host for -tilde expansion. Maybe @command{ksh} saves the history by default. -@value{tramp} tries to turn off saving the history, but maybe you have -to help. For example, you could put this in your @file{.kshrc}: - -@example -if [ -f $HOME/.sh_history ] ; then - /bin/rm $HOME/.sh_history -fi -if [ "$@{HISTFILE-unset@}" != "unset" ] ; then - unset HISTFILE -fi -if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then - unset HISTSIZE -fi -@end example - - -@item There are longish file names to type. How to shorten this? - -Let's say you need regularly access to @file{@trampfn{ssh, news, -news.my.domain, /opt/news/etc}}, which is boring to type again and -again. The following approaches can be mixed: - -@enumerate - -@item Use default values for method and user name: - -You can define default methods and user names for hosts, -(@pxref{Default Method}, @pxref{Default User}): - -@lisp -(setq tramp-default-method "ssh" - tramp-default-user "news") -@end lisp - -The file name left to type would be -@kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}. - -Note that there are some useful settings already. Accessing your -local host as @samp{root} user, is possible just by @kbd{C-x C-f -@trampfn{su, , ,}}. - -@item Use configuration possibilities of your method: - -Several connection methods (i.e. the programs used) offer powerful -configuration possibilities (@pxref{Customizing Completion}). In the -given case, this could be @file{~/.ssh/config}: - -@example -Host xy - HostName news.my.domain - User news -@end example - -The file name left to type would be @kbd{C-x C-f @trampfn{ssh, , xy, -/opt/news/etc}}. Depending on files in your directories, it is even -possible to complete the host name with @kbd{C-x C-f -@value{prefix}ssh@value{postfixhop}x @key{TAB}}. - -@item Use environment variables: - -File names typed in the minibuffer can be expanded by environment -variables. You can set them outside @value{emacsname}, or even with -Lisp: - -@lisp -(setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}") -@end lisp - -Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you -are. The disadvantage is that you cannot edit the file name, because -environment variables are not expanded during editing in the -minibuffer. - -@item Define own keys: - -You can define your own key sequences in @value{emacsname}, which can -be used instead of @kbd{C-x C-f}: - -@lisp -(global-set-key - [(control x) (control y)] - (lambda () - (interactive) - (find-file - (read-file-name - "Find Tramp file: " - "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))) -@end lisp - -Simply typing @kbd{C-x C-y} would initialize the minibuffer for -editing with your beloved file name. - -See also @uref{http://www.emacswiki.org/cgi-bin/wiki/TrampMode, the -Emacs Wiki} for a more comprehensive example. - -@item Define own abbreviation (1): - -It is possible to define an own abbreviation list for expanding file -names: - -@lisp -(add-to-list - 'directory-abbrev-alist - '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")) -@end lisp - -This shortens the file opening command to @kbd{C-x C-f /xy -@key{RET}}. The disadvantage is, again, that you cannot edit the file -name, because the expansion happens after entering the file name only. - -@item Define own abbreviation (2): - -The @code{abbrev-mode} gives more flexibility for editing the -minibuffer: - -@lisp -(define-abbrev-table 'my-tramp-abbrev-table - '(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))) - -(add-hook - 'minibuffer-setup-hook - '(lambda () - (abbrev-mode 1) - (setq local-abbrev-table my-tramp-abbrev-table))) - -(defadvice minibuffer-complete - (before my-minibuffer-complete activate) - (expand-abbrev)) - -;; If you use partial-completion-mode -(defadvice PC-do-completion - (before my-PC-do-completion activate) - (expand-abbrev)) -@end lisp - -After entering @kbd{C-x C-f xy @key{TAB}}, the minibuffer is -expanded, and you can continue editing. - -@item Use bookmarks: - -Bookmarks can be used to visit Tramp files or directories. -@ifinfo -@pxref{Bookmarks, , , @value{emacsdir}} -@end ifinfo - -When you have opened @file{@trampfn{ssh, news, news.my.domain, -/opt/news/etc/}}, you should save the bookmark via -@ifset emacs -@kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{set}}. -@end ifset -@ifset xemacs -@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{set}}. -@end ifset - -Later on, you can always navigate to that bookmark via -@ifset emacs -@kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{jump}}. -@end ifset -@ifset xemacs -@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{jump}}. -@end ifset - -@item Use recent files: - -@ifset emacs -@file{recentf} -@end ifset -@ifset xemacs -@file{recent-files} -@end ifset -remembers visited places. -@ifinfo -@ifset emacs -@pxref{File Conveniences, , , @value{emacsdir}} -@end ifset -@ifset xemacs -@pxref{recent-files, , , edit-utils} -@end ifset -@end ifinfo - -You could keep remote file names in the recent list without checking -their readability through a remote access: - -@lisp -@ifset emacs -(recentf-mode 1) -@end ifset -@ifset xemacs -(recent-files-initialize) -(add-hook - 'find-file-hooks - (lambda () - (when (file-remote-p (buffer-file-name)) - (recent-files-make-permanent))) - 'append) -@end ifset -@end lisp - -The list of files opened recently is reachable via -@ifset emacs -@kbd{@key{menu-bar} @key{file} @key{Open Recent}}. -@end ifset -@ifset xemacs -@kbd{@key{menu-bar} @key{Recent Files}}. -@end ifset - -@ifset emacs -@item Use filecache: - -@file{filecache} remembers visited places. Add the directory into -the cache: - -@lisp -(eval-after-load "filecache" - '(file-cache-add-directory - "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")) -@end lisp - -Whenever you want to load a file, you can enter @kbd{C-x C-f -C-@key{TAB}} in the minibuffer. The completion is done for the given -directory. -@end ifset - -@ifset emacs -@item Use bbdb: - -@file{bbdb} has a built-in feature for @value{ftppackagename} files, -which works also for @value{tramp}. -@ifinfo -@pxref{bbdb-ftp, Storing FTP sites in the BBDB, , bbdb} -@end ifinfo - -You need to load @file{bbdb}: - -@lisp -(require 'bbdb) -(bbdb-initialize) -@end lisp - -Then you can create a BBDB entry via @kbd{M-x bbdb-create-ftp-site}. -Because BBDB is not prepared for @value{tramp} syntax, you must -specify a method together with the user name when needed. Example: - -@example -@kbd{M-x bbdb-create-ftp-site @key{RET}} -@b{Ftp Site:} news.my.domain @key{RET} -@b{Ftp Directory:} /opt/news/etc/ @key{RET} -@b{Ftp Username:} ssh@value{postfixhop}news @key{RET} -@b{Company:} @key{RET} -@b{Additional Comments:} @key{RET} -@end example - -When you have opened your BBDB buffer, you can access such an entry by -pressing the key @key{F}. -@end ifset - -@end enumerate - -I would like to thank all @value{tramp} users who have contributed to -the different recipes! - - -@ifset emacs -@item -How can I use @value{tramp} to connect to a remote @value{emacsname} -session? - -You can configure Emacs Client doing this. -@ifinfo -@xref{Emacs Server, , , @value{emacsdir}}. -@end ifinfo - -On the remote host, you start the Emacs Server: - -@lisp -(require 'server) -(setq server-host (system-name) - server-use-tcp t) -(server-start) -@end lisp - -Make sure that the result of @code{(system-name)} can be resolved on -your local host; otherwise you might use a hard coded IP address. - -The resulting file @file{~/.emacs.d/server/server} must be copied to -your local host, at the same location. You can call then the Emacs -Client from the command line: - -@example -emacsclient @trampfn{ssh, user, host, /file/to/edit} -@end example - -@code{user} and @code{host} shall be related to your local host. - -If you want to use Emacs Client also as editor for other programs, you -could write a script @file{emacsclient.sh}: - -@example -#!/bin/sh -emacsclient @trampfn{ssh, $(whoami), $(hostname --fqdn), $1} -@end example - -Then you must set the environment variable @code{EDITOR} pointing to -that script: - -@example -export EDITOR=/path/to/emacsclient.sh -@end example -@end ifset - - -@item -There are packages which call @value{tramp} although I haven't entered -a remote file name ever. I dislike it, how could I disable it? - -In general, @value{tramp} functions are used only when -you apply remote file name syntax. However, some packages enable -@value{tramp} on their own. - -@itemize @minus -@item -@file{ido.el} - -You could disable @value{tramp} file name completion: - -@lisp -(custom-set-variables - '(ido-enable-tramp-completion nil)) -@end lisp - -@item -@file{rlogin.el} - -You could disable remote directory tracking mode: - -@lisp -(rlogin-directory-tracking-mode -1) -@end lisp -@end itemize - - -@item -How can I disable @value{tramp} at all? - -Shame on you, why did you read until now? - -@itemize @minus -@ifset emacs -@item -If you just want to have @value{ftppackagename} as default remote -files access package, you should apply the following code: - -@lisp -(setq tramp-default-method "ftp") -@end lisp -@end ifset - -@item -In order to disable -@ifset emacs -@value{tramp} (and @value{ftppackagename}), -@end ifset -@ifset xemacs -@value{tramp}, -@end ifset -you must set @code{tramp-mode} to @code{nil}: - -@lisp -(setq tramp-mode nil) -@end lisp - -@item -Unloading @value{tramp} can be achieved by applying @kbd{M-x -tramp-unload-tramp}. -@ifset emacs -This resets also the @value{ftppackagename} plugins. -@end ifset -@end itemize -@end itemize - - -@c For the developer -@node Files directories and localnames -@chapter How file names, directories and localnames are mangled and managed. - -@menu -* Localname deconstruction:: Breaking a localname into its components. -@ifset emacs -* External packages:: Integration with external Lisp packages. -@end ifset -@end menu - - -@node Localname deconstruction -@section Breaking a localname into its components. - -@value{tramp} file names are somewhat different, obviously, to ordinary file -names. As such, the lisp functions @code{file-name-directory} and -@code{file-name-nondirectory} are overridden within the @value{tramp} -package. - -Their replacements are reasonably simplistic in their approach. They -dissect the filename, call the original handler on the localname and -then rebuild the @value{tramp} file name with the result. - -This allows the platform specific hacks in the original handlers to take -effect while preserving the @value{tramp} file name information. - - -@ifset emacs -@node External packages -@section Integration with external Lisp packages. -@subsection Filename completion. - -While reading filenames in the minibuffer, @value{tramp} must decide -whether it completes possible incomplete filenames, or not. Imagine -there is the following situation: You have typed @kbd{C-x C-f -@value{prefix}ssh@value{postfixhop} @key{TAB}}. @value{tramp} cannot -know, whether @option{ssh} is a method or a host name. It checks -therefore the last input character you have typed. If this is -@key{TAB}, @key{SPACE} or @kbd{?}, @value{tramp} assumes that you are -still in filename completion, and it does not connect to the possible -remote host @option{ssh}. - -@vindex tramp-completion-mode -External packages, which use other characters for completing filenames -in the minibuffer, must signal this to @value{tramp}. For this case, -the variable @code{tramp-completion-mode} can be bound temporarily to -a non-@code{nil} value. - -@lisp -(let ((tramp-completion-mode t)) - ...) -@end lisp - - -@subsection File attributes cache. - -When @value{tramp} runs remote processes, files on the remote host -could change their attributes. Consequently, @value{tramp} must flush -its complete cache keeping attributes for all files of the remote host -it has seen so far. - -This is a performance degradation, because the lost file attributes -must be recomputed when needed again. In cases the caller of -@code{process-file} knows that there are no file attribute changes, it -shall let-bind the variable @code{process-file-side-effects} to -@code{nil}. @value{tramp} wouldn't flush the file attributes cache then. - -@lisp -(let (process-file-side-effects) - ...) -@end lisp - -For asynchronous processes, @value{tramp} flushes the file attributes -cache via a process sentinel. If the caller of -@code{start-file-process} knows that there are no file attribute -changes, it shall set the process sentinel to @code{nil}. In case the -caller defines an own process sentinel, @value{tramp}'s process -sentinel is overwritten. The caller can still flush the file -attributes cache in its process sentinel with this code: - -@lisp -(unless (memq (process-status proc) '(run open)) - (dired-uncache remote-directory)) -@end lisp - -@code{remote-directory} shall be the root directory, where file -attribute changes can happen during the process lifetime. -@value{tramp} traverses all subdirectories, starting at this -directory. Often, it is sufficient to use @code{default-directory} of -the process buffer as root directory. -@end ifset - - -@node Traces and Profiles -@chapter How to Customize Traces - -All @value{tramp} messages are raised with a verbosity level. The -verbosity level can be any number between 0 and 10. Only messages with -a verbosity level less than or equal to @code{tramp-verbose} are -displayed. - -The verbosity levels are - - @w{ 0} silent (no @value{tramp} messages at all) -@*@indent @w{ 1} errors -@*@indent @w{ 2} warnings -@*@indent @w{ 3} connection to remote hosts (default verbosity) -@*@indent @w{ 4} activities -@*@indent @w{ 5} internal -@*@indent @w{ 6} sent and received strings -@*@indent @w{ 7} file caching -@*@indent @w{ 8} connection properties -@*@indent @w{ 9} test commands -@*@indent @w{10} traces (huge) - -When @code{tramp-verbose} is greater than or equal to 4, the messages -are also written into a @value{tramp} debug buffer. This debug buffer -is useful for analyzing problems; sending a @value{tramp} bug report -should be done with @code{tramp-verbose} set to a verbosity level of at -least 6 (@pxref{Bug Reports}). - -The debug buffer is in -@ifinfo -@ref{Outline Mode, , , @value{emacsdir}}. -@end ifinfo -@ifnotinfo -Outline Mode. -@end ifnotinfo -That means, you can change the level of messages to be viewed. If you -want, for example, see only messages up to verbosity level 5, you must -enter @kbd{C-u 6 C-c C-q}. -@ifinfo -Other keys for navigating are described in -@ref{Outline Visibility, , , @value{emacsdir}}. -@end ifinfo - -@value{tramp} errors are handled internally in order to raise the -verbosity level 1 messages. When you want to get a Lisp backtrace in -case of an error, you need to set both - -@lisp -(setq debug-on-error t - debug-on-signal t) -@end lisp - -Sometimes, it might be even necessary to step through @value{tramp} -function call traces. Such traces are enabled by the following code: - -@lisp -(require 'tramp) -(require 'trace) -(dolist (elt (all-completions "tramp-" obarray 'functionp)) - (trace-function-background (intern elt))) -(untrace-function 'tramp-read-passwd) -(untrace-function 'tramp-gw-basic-authentication) -@end lisp - -The function call traces are inserted in the buffer -@file{*trace-output*}. @code{tramp-read-passwd} and -@code{tramp-gw-basic-authentication} shall be disabled when the -function call traces are added to @value{tramp}, because both -functions return password strings, which should not be distributed. - - -@node Issues -@chapter Debatable Issues and What Was Decided - -@itemize @bullet -@item The uuencode method does not always work. - -Due to the design of @value{tramp}, the encoding and decoding programs -need to read from stdin and write to stdout. On some systems, -@command{uudecode -o -} will read stdin and write the decoded file to -stdout, on other systems @command{uudecode -p} does the same thing. -But some systems have uudecode implementations which cannot do this at -all---it is not possible to call these uudecode implementations with -suitable parameters so that they write to stdout. - -Of course, this could be circumvented: the @code{begin foo 644} line -could be rewritten to put in some temporary file name, then -@command{uudecode} could be called, then the temp file could be -printed and deleted. - -But I have decided that this is too fragile to reliably work, so on some -systems you'll have to do without the uuencode methods. - -@item The @value{tramp} filename syntax differs between Emacs and XEmacs. - -The Emacs maintainers wish to use a unified filename syntax for -Ange-FTP and @value{tramp} so that users don't have to learn a new -syntax. It is sufficient to learn some extensions to the old syntax. - -For the XEmacs maintainers, the problems caused from using a unified -filename syntax are greater than the gains. The XEmacs package system -uses EFS for downloading new packages. So, obviously, EFS has to be -installed from the start. If the filenames were unified, @value{tramp} -would have to be installed from the start, too. - -@ifset xemacs -@strong{Note:} If you'd like to use a similar syntax like -@value{ftppackagename}, you need the following settings in your init -file: - -@lisp -(setq tramp-unified-filenames t) -(require 'tramp) -@end lisp - -The autoload of the @value{emacsname} @value{tramp} package must be -disabled. This can be achieved by setting file permissions @code{000} -to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}. - -In case of unified filenames, all @value{emacsname} download sites are -added to @code{tramp-default-method-alist} with default method -@option{ftp} @xref{Default Method}. These settings shouldn't be -touched for proper working of the @value{emacsname} package system. - -The syntax for unified filenames is described in the @value{tramp} manual -for @value{emacsothername}. -@end ifset -@end itemize - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index -@unnumbered Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@bye - -@c TODO -@c -@c * Say something about the .login and .profile files of the remote -@c shells. -@c * Explain how tramp.el works in principle: open a shell on a remote -@c host and then send commands to it. -@c * Use `filename' resp. `file name' consistently. -@c * Use `host' resp. `machine' consistently. -@c * Consistent small or capitalized words especially in menus. diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi deleted file mode 100644 index b4fb5f9aa6a..00000000000 --- a/doc/misc/trampver.texi +++ /dev/null @@ -1,69 +0,0 @@ -@c -*-texinfo-*- -@c texi/trampver.texi. Generated from trampver.texi.in by configure. - -@c This is part of the Emacs manual. -@c Copyright (C) 2003-2012 Free Software Foundation, Inc. -@c See file doclicense.texi for copying conditions. - -@c In the Tramp CVS, the version number is auto-frobbed from -@c configure.ac, so you should edit that file and run -@c "autoconf && ./configure" to change the version number. -@set trampver 2.2.3-24.1 - -@c Other flags from configuration -@set instprefix /usr/local -@set lispdir /usr/local/share/emacs/site-lisp -@set infodir /usr/local/share/info - -@c Formatting of the tramp program name consistent. -@set tramp @sc{tramp} - -@c Whether or not describe GVFS integration. -@ifclear noemacsgvfs -@set emacsgvfs -@end ifclear - -@c Whether or not describe gateway methods. -@ifclear noemacsgw -@set emacsgw -@end ifclear - -@c Some flags which make the text independent on the (X)Emacs flavor. -@c "emacs" resp "xemacs" are set in the Makefile. Default is "emacs". -@ifclear emacs -@ifclear xemacs -@set emacs -@end ifclear -@end ifclear - -@c Emacs values. -@ifset emacs -@set emacsname Emacs -@set emacsdir emacs -@set ftppackagename Ange-FTP -@set prefix / -@set prefixhop -@set postfix : -@set postfixhop : -@set ipv6prefix [ -@set ipv6postfix ] -@set emacsothername XEmacs -@set emacsotherdir xemacs -@set emacsotherfilename tramp-xemacs.html -@end ifset - -@c XEmacs counterparts. -@ifset xemacs -@set emacsname XEmacs -@set emacsdir xemacs -@set ftppackagename EFS -@set prefix /[ -@set prefixhop [ -@set postfix ] -@set postfixhop / -@set ipv6prefix -@set ipv6postfix -@set emacsothername Emacs -@set emacsotherdir emacs -@set emacsotherfilename tramp-emacs.html -@end ifset diff --git a/doc/misc/url.texi b/doc/misc/url.texi deleted file mode 100644 index 680f1921479..00000000000 --- a/doc/misc/url.texi +++ /dev/null @@ -1,1196 +0,0 @@ -\input texinfo -@setfilename ../../info/url -@settitle URL Programmer's Manual - -@iftex -@c @finalout -@end iftex -@c @setchapternewpage odd -@c @smallbook - -@tex -\overfullrule=0pt -%\global\baselineskip 30pt % for printing in double space -@end tex -@dircategory Emacs lisp libraries -@direntry -* URL: (url). URL loading package. -@end direntry - -@copying -This file documents the Emacs Lisp URL loading package. - -Copyright @copyright{} 1993-1999, 2002, 2004-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@c -@titlepage -@title URL Programmer's Manual -@subtitle First Edition, URL Version 2.0 -@author William M. Perry @email{wmperry@@gnu.org} -@author David Love @email{fx@@gnu.org} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top URL - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Getting Started:: Preparing your program to use URLs. -* Retrieving URLs:: How to use this package to retrieve a URL. -* Supported URL Types:: Descriptions of URL types currently supported. -* Defining New URLs:: How to define a URL loader for a new protocol. -* General Facilities:: URLs can be cached, accessed via a gateway - and tracked in a history list. -* Customization:: Variables you can alter. -* GNU Free Documentation License:: The license for this documentation. -* Function Index:: -* Variable Index:: -* Concept Index:: -@end menu - -@node Getting Started -@chapter Getting Started -@cindex URLs, definition -@cindex URIs - -@dfn{Uniform Resource Locators} (URLs) are a specific form of -@dfn{Uniform Resource Identifiers} (URI) described in RFC 2396 which -updates RFC 1738 and RFC 1808. RFC 2016 defines uniform resource -agents. - -URIs have the form @var{scheme}:@var{scheme-specific-part}, where the -@var{scheme}s supported by this library are described below. -@xref{Supported URL Types}. - -FTP, NFS, HTTP, HTTPS, @code{rlogin}, @code{telnet}, tn3270, -IRC and gopher URLs all have the form - -@example -@var{scheme}://@r{[}@var{userinfo}@@@r{]}@var{hostname}@r{[}:@var{port}@r{]}@r{[}/@var{path}@r{]} -@end example -@noindent -where @samp{@r{[}} and @samp{@r{]}} delimit optional parts. -@var{userinfo} sometimes takes the form @var{username}:@var{password} -but you should beware of the security risks of sending cleartext -passwords. @var{hostname} may be a domain name or a dotted decimal -address. If the @samp{:@var{port}} is omitted then the library will -use the ``well known'' port for that service when accessing URLs. With -the possible exception of @code{telnet}, it is rare for ports to be -specified, and it is possible using a non-standard port may have -undesired consequences if a different service is listening on that -port (e.g., an HTTP URL specifying the SMTP port can cause mail to be -sent). @c , but @xref{Other Variables, url-bad-port-list}. -The meaning of the @var{path} component depends on the service. - -@menu -* Configuration:: -* Parsed URLs:: URLs are parsed into vector structures. -@end menu - -@node Configuration -@section Configuration - -@defvar url-configuration-directory -@cindex @file{~/.url} -@cindex configuration files -The directory in which URL configuration files, the cache etc., -reside. The old default was @file{~/.url}, and this directory -is still used if it exists. The new default is a @file{url/} -directory in @code{user-emacs-directory}, which is normally -@file{~/.emacs.d}. -@end defvar - -@node Parsed URLs -@section Parsed URLs -@cindex parsed URLs -The library functions typically operate on @dfn{parsed} versions of -URLs. These are actually vectors of the form: - -@example -[@var{type} @var{user} @var{password} @var{host} @var{port} @var{file} @var{target} @var{attributes} @var{full}] -@end example - -@noindent where -@table @var -@item type -is the type of the URL scheme, e.g., @code{http} -@item user -is the username associated with it, or @code{nil}; -@item password -is the user password associated with it, or @code{nil}; -@item host -is the host name associated with it, or @code{nil}; -@item port -is the port number associated with it, or @code{nil}; -@item file -is the ``file'' part of it, or @code{nil}. This doesn't necessarily -actually refer to a file; -@item target -is the target part, or @code{nil}; -@item attributes -is the attributes associated with it, or @code{nil}; -@item full -is @code{t} for a fully-specified URL, with a host part indicated by -@samp{//} after the scheme part. -@end table - -@findex url-type -@findex url-user -@findex url-password -@findex url-host -@findex url-port -@findex url-file -@findex url-target -@findex url-attributes -@findex url-full -@findex url-set-type -@findex url-set-user -@findex url-set-password -@findex url-set-host -@findex url-set-port -@findex url-set-file -@findex url-set-target -@findex url-set-attributes -@findex url-set-full -These attributes have accessors named @code{url-@var{part}}, where -@var{part} is the name of one of the elements above, e.g., -@code{url-host}. Similarly, there are setters of the form -@code{url-set-@var{part}}. - -There are functions for parsing and unparsing between the string and -vector forms. - -@defun url-generic-parse-url url -Return a parsed version of the string @var{url}. -@end defun - -@defun url-recreate-url url -@cindex unparsing URLs -Recreates a URL string from the parsed @var{url}. -@end defun - -@node Retrieving URLs -@chapter Retrieving URLs - -@defun url-retrieve-synchronously url -Retrieve @var{url} synchronously and return a buffer containing the -data. @var{url} is either a string or a parsed URL structure. Return -@code{nil} if there are no data associated with it (the case for dired, -info, or mailto URLs that need no further processing). -@end defun - -@defun url-retrieve url callback &optional cbargs silent no-cookies -Retrieve @var{url} asynchronously and call @var{callback} with args -@var{cbargs} when finished. The callback is called when the object -has been completely retrieved, with the current buffer containing the -object and any MIME headers associated with it. @var{url} is either a -string or a parsed URL structure. Returns the buffer @var{url} will -load into, or @code{nil} if the process has already completed. -If the optional argument @var{silent} is non-@code{nil}, suppress -progress messages. If the optional argument @var{no-cookies} is -non-@code{nil}, do not store or send cookies. -@end defun - -@vindex url-queue-parallel-processes -@vindex url-queue-timeout -@defun url-queue-retrieve url callback &optional cbargs silent no-cookies -This acts like the @code{url-retrieve} function, but with limits on -the degree of parallelism. The option @code{url-queue-parallel-processes} -controls the number of concurrent processes, and the option -@code{url-queue-timeout} sets a timeout in seconds. -@end defun - -@node Supported URL Types -@chapter Supported URL Types - -@menu -* http/https:: Hypertext Transfer Protocol. -* file/ftp:: Local files and FTP archives. -* info:: Emacs "Info" pages. -* mailto:: Sending email. -* news/nntp/snews:: Usenet news. -* rlogin/telnet/tn3270:: Remote host connectivity. -* irc:: Internet Relay Chat. -* data:: Embedded data URLs. -* nfs:: Networked File System -@c * finger:: -@c * gopher:: -@c * netrek:: -@c * prospero:: -* cid:: Content-ID. -* about:: -* ldap:: Lightweight Directory Access Protocol -* imap:: IMAP mailboxes. -* man:: Unix man pages. -@end menu - -@node http/https -@section @code{http} and @code{https} - -The scheme @code{http} is Hypertext Transfer Protocol. The library -supports version 1.1, specified in RFC 2616. (This supersedes 1.0, -defined in RFC 1945) HTTP URLs have the following form, where most of -the parts are optional: -@example -http://@var{user}:@var{password}@@@var{host}:@var{port}/@var{path}?@var{searchpart}#@var{fragment} -@end example -@c The @code{:@var{port}} part is optional, and @var{port} defaults to -@c 80. The @code{/@var{path}} part, if present, is a slash-separated -@c series elements. The @code{?@var{searchpart}}, if present, is the -@c query for a search or the content of a form submission. The -@c @code{#fragment} part, if present, is a location in the document. - -The scheme @code{https} is a secure version of @code{http}, with -transmission via SSL. It is defined in RFC 2069. Its default port is -443. This scheme depends on SSL support in Emacs via the -@file{ssl.el} library and is actually implemented by forcing the -@code{ssl} gateway method to be used. @xref{Gateways in general}. - -@defopt url-honor-refresh-requests -This controls honoring of HTTP @samp{Refresh} headers by which -servers can direct clients to reload documents from the same URL or a -or different one. @code{nil} means they will not be honored, -@code{t} (the default) means they will always be honored, and -otherwise the user will be asked on each request. -@end defopt - - -@menu -* Cookies:: -* HTTP language/coding:: -* HTTP URL Options:: -* Dealing with HTTP documents:: -@end menu - -@node Cookies -@subsection Cookies - -@defopt url-cookie-file -The file in which cookies are stored, defaulting to @file{cookies} in -the directory specified by @code{url-configuration-directory}. -@end defopt - -@defopt url-cookie-confirmation -Specifies whether confirmation is require to accept cookies. -@end defopt - -@defopt url-cookie-multiple-line -Specifies whether to put all cookies for the server on one line in the -HTTP request to satisfy broken servers like -@url{http://www.hotmail.com}. -@end defopt - -@defopt url-cookie-trusted-urls -A list of regular expressions matching URLs from which to accept -cookies always. -@end defopt - -@defopt url-cookie-untrusted-urls -A list of regular expressions matching URLs from which to reject -cookies always. -@end defopt - -@defopt url-cookie-save-interval -The number of seconds between automatic saves of cookies to disk. -Default is one hour. -@end defopt - - -@node HTTP language/coding -@subsection Language and Encoding Preferences - -HTTP allows clients to express preferences for the language and -encoding of documents which servers may honor. For each of these -variables, the value is a string; it can specify a single choice, or -it can be a comma-separated list. - -Normally, this list is ordered by descending preference. However, each -element can be followed by @samp{;q=@var{priority}} to specify its -preference level, a decimal number from 0 to 1; e.g., for -@code{url-mime-language-string}, @w{@code{"de, en-gb;q=0.8, -en;q=0.7"}}. An element that has no @samp{;q} specification has -preference level 1. - -@defopt url-mime-charset-string -@cindex character sets -@cindex coding systems -This variable specifies a preference for character sets when documents -can be served in more than one encoding. - -HTTP allows specifying a series of MIME charsets which indicate your -preferred character set encodings, e.g., Latin-9 or Big5, and these -can be weighted. The default series is generated automatically from -the associated MIME types of all defined coding systems, sorted by the -coding system priority specified in Emacs. @xref{Recognize Coding, , -Recognizing Coding Systems, emacs, The GNU Emacs Manual}. -@end defopt - -@defopt url-mime-language-string -@cindex language preferences -A string specifying the preferred language when servers can serve -files in several languages. Use RFC 1766 abbreviations, e.g., -@samp{en} for English, @samp{de} for German. - -The string can be @code{"*"} to get the first available language (as -opposed to the default). -@end defopt - -@node HTTP URL Options -@subsection HTTP URL Options - -HTTP supports an @samp{OPTIONS} method describing things supported by -the URL@. - -@defun url-http-options url -Returns a property list describing options available for URL. The -property list members are: - -@table @code -@item methods -A list of symbols specifying what HTTP methods the resource -supports. - -@item dav -@cindex DAV -A list of numbers specifying what DAV protocol/schema versions are -supported. - -@item dasl -@cindex DASL -A list of supported DASL search types supported (string form). - -@item ranges -A list of the units available for use in partial document fetches. - -@item p3p -@cindex P3P -The @dfn{Platform For Privacy Protection} description for the resource. -Currently this is just the raw header contents. -@end table - -@end defun - -@node Dealing with HTTP documents -@subsection Dealing with HTTP documents - -HTTP URLs are retrieved into a buffer containing the HTTP headers -followed by the body. Since the headers are quasi-MIME, they may be -processed using the MIME library. @xref{Top,, Emacs MIME, -emacs-mime, The Emacs MIME Manual}. - -@node file/ftp -@section file and ftp -@cindex files -@cindex FTP -@cindex File Transfer Protocol -@cindex compressed files -@cindex dired - -@example -ftp://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file} -file://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file} -@end example - -These schemes are defined in RFC 1808. -@samp{ftp:} and @samp{file:} are synonymous in this library. They -allow reading arbitrary files from hosts. Either @samp{ange-ftp} -(Emacs) or @samp{efs} (XEmacs) is used to retrieve them from remote -hosts. Local files are accessed directly. - -Compressed files are handled, but support is hard-coded so that -@code{jka-compr-compression-info-list} and so on have no affect. -Suffixes recognized are @samp{.z}, @samp{.gz}, @samp{.Z} and -@samp{.bz2}. - -@defopt url-directory-index-file -The filename to look for when indexing a directory, default -@samp{"index.html"}. If this file exists, and is readable, then it -will be viewed instead of using @code{dired} to view the directory. -@end defopt - -@node info -@section info -@cindex Info -@cindex Texinfo -@findex Info-goto-node - -@example -info:@var{file}#@var{node} -@end example - -Info URLs are not officially defined. They invoke -@code{Info-goto-node} with argument @samp{(@var{file})@var{node}}. -@samp{#@var{node}} is optional, defaulting to @samp{Top}. - -@node mailto -@section mailto - -@cindex mailto -@cindex email -A mailto URL will send an email message to the address in the -URL, for example @samp{mailto:foo@@bar.com} would compose a -message to @samp{foo@@bar.com}. - -@defopt url-mail-command -@vindex mail-user-agent -The function called whenever url needs to send mail. This should -normally be left to default from @var{mail-user-agent}. @xref{Mail -Methods, , Mail-Composition Methods, emacs, The GNU Emacs Manual}. -@end defopt - -An @samp{X-Url-From} header field containing the URL of the document -that contained the mailto URL is added if that URL is known. - -RFC 2368 extends the definition of mailto URLs in RFC 1738. -The form of a mailto URL is -@example -@samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]} -@end example -@noindent where an arbitrary number of @var{header}s can be added. If the -@var{header} is @samp{body}, then @var{contents} is put in the body -otherwise a @var{header} header field is created with @var{contents} -as its contents. Note that the URL library does not consider any -headers ``dangerous'' so you should check them before sending the -message. - -@c Fixme: update -Email messages are defined in @sc{rfc}822. - -@node news/nntp/snews -@section @code{news}, @code{nntp} and @code{snews} -@cindex news -@cindex network news -@cindex usenet -@cindex NNTP -@cindex snews - -@c draft-gilman-news-url-01 -The network news URL scheme take the following forms following RFC -1738 except that for compatibility with other clients, host and port -fields may be included in news URLs though they are properly only -allowed for nntp an snews. - -@table @samp -@item news:@var{newsgroup} -Retrieves a list of messages in @var{newsgroup}; -@item news:@var{message-id} -Retrieves the message with the given @var{message-id}; -@item news:* -Retrieves a list of all available newsgroups; -@item nntp://@var{host}:@var{port}/@var{newsgroup} -@itemx nntp://@var{host}:@var{port}/@var{message-id} -@itemx nntp://@var{host}:@var{port}/* -Similar to the @samp{news} versions. -@end table - -@samp{:@var{port}} is optional and defaults to :119. - -@samp{snews} is the same as @samp{nntp} except that the default port -is :563. -@cindex SSL -(It is tunneled through SSL.) - -An @samp{nntp} URL is the same as a news URL, except that the URL may -specify an article by its number. - -@defopt url-news-server -This variable can be used to override the default news server. -Usually this will be set by the Gnus package, which is used to fetch -news. -@cindex environment variable -@vindex NNTPSERVER -It may be set from the conventional environment variable -@code{NNTPSERVER}. -@end defopt - -@node rlogin/telnet/tn3270 -@section rlogin, telnet and tn3270 -@cindex rlogin -@cindex telnet -@cindex tn3270 -@cindex terminal emulation -@findex terminal-emulator - -These URL schemes from RFC 1738 for logon via a terminal emulator have -the form -@example -telnet://@var{user}:@var{password}@@@var{host}:@var{port} -@end example -but the @code{:@var{password}} component is ignored. - -To handle rlogin, telnet and tn3270 URLs, a @code{rlogin}, -@code{telnet} or @code{tn3270} (the program names and arguments are -hardcoded) session is run in a @code{terminal-emulator} buffer. -Well-known ports are used if the URL does not specify a port. - -@node irc -@section irc -@cindex IRC -@cindex Internet Relay Chat -@cindex ZEN IRC -@cindex ERC -@cindex rcirc -@c Fixme: reference (was http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt) -@dfn{Internet Relay Chat} (IRC) is handled by handing off the @sc{irc} -session to a function named in @code{url-irc-function}. - -@defopt url-irc-function -A function to actually open an IRC connection. -This function -must take five arguments, @var{host}, @var{port}, @var{channel}, -@var{user} and @var{password}. The @var{channel} argument specifies the -channel to join immediately, this can be @code{nil}. By default this is -@code{url-irc-rcirc}. -@end defopt -@defun url-irc-rcirc host port channel user password -Processes the arguments and lets @code{rcirc} handle the session. -@end defun -@defun url-irc-erc host port channel user password -Processes the arguments and lets @code{ERC} handle the session. -@end defun -@defun url-irc-zenirc host port channel user password -Processes the arguments and lets @code{zenirc} handle the session. -@end defun - -@node data -@section data -@cindex data URLs - -@example -data:@r{[}@var{media-type}@r{]}@r{[};@var{base64}@r{]},@var{data} -@end example - -Data URLs contain MIME data in the URL itself. They are defined in -RFC 2397. - -@var{media-type} is a MIME @samp{Content-Type} string, possibly -including parameters. It defaults to -@samp{text/plain;charset=US-ASCII}. The @samp{text/plain} can be -omitted but the charset parameter supplied. If @samp{;base64} is -present, the @var{data} are base64-encoded. - -@node nfs -@section nfs -@cindex NFS -@cindex Network File System -@cindex automounter - -@example -nfs://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file} -@end example - -The @samp{nfs:} scheme is defined in RFC 2224. It is similar to -@samp{ftp:} except that it points to a file on a remote host that is -handled by the automounter on the local host. - -@defvar url-nfs-automounter-directory-spec -@end defvar -A string saying how to invoke the NFS automounter. Certain @samp{%} -sequences are recognized: - -@table @samp -@item %h -The hostname of the NFS server; -@item %n -The port number of the NFS server; -@item %u -The username to use to authenticate; -@item %p -The password to use to authenticate; -@item %f -The filename on the remote server; -@item %% -A literal @samp{%}. -@end table - -Each can be used any number of times. - -@node cid -@section cid -@cindex Content-ID - -RFC 2111 - -@node about -@section about - -@node ldap -@section ldap -@cindex LDAP -@cindex Lightweight Directory Access Protocol - -The LDAP scheme is defined in RFC 2255. - -@node imap -@section imap -@cindex IMAP - -RFC 2192 - -@node man -@section man -@cindex @command{man} -@cindex Unix man pages -@findex man - -@example -@samp{man:@var{page-spec}} -@end example - -This is a non-standard scheme. @var{page-spec} is passed directly to -the Lisp @code{man} function. - -@node Defining New URLs -@chapter Defining New URLs - -@menu -* Naming conventions:: -* Required functions:: -* Optional functions:: -* Asynchronous fetching:: -* Supporting file-name-handlers:: -@end menu - -@node Naming conventions -@section Naming conventions - -@node Required functions -@section Required functions - -@node Optional functions -@section Optional functions - -@node Asynchronous fetching -@section Asynchronous fetching - -@node Supporting file-name-handlers -@section Supporting file-name-handlers - -@node General Facilities -@chapter General Facilities - -@menu -* Disk Caching:: -* Proxies:: -* Gateways in general:: -* History:: -@end menu - -@node Disk Caching -@section Disk Caching -@cindex Caching -@cindex Persistent Cache -@cindex Disk Cache - -The disk cache stores retrieved documents locally, whence they can be -retrieved more quickly. When requesting a URL that is in the cache, -the library checks to see if the page has changed since it was last -retrieved from the remote machine. If not, the local copy is used, -saving the transmission over the network. -@cindex Cleaning the cache -@cindex Clearing the cache -@cindex Cache cleaning -Currently the cache isn't cleared automatically. -@c Running the @code{clean-cache} shell script -@c fist is recommended, to allow for future cleaning of the cache. This -@c shell script will remove all files that have not been accessed since it -@c was last run. To keep the cache pared down, it is recommended that this -@c script be run from @i{at} or @i{cron} (see the manual pages for -@c crontab(5) or at(1) for more information) - -@defopt url-automatic-caching -Setting this variable non-@code{nil} causes documents to be cached -automatically. -@end defopt - -@defopt url-cache-directory -This variable specifies the -directory to store the cache files. It defaults to sub-directory -@file{cache} of @code{url-configuration-directory}. -@end defopt - -@defopt url-cache-creation-function -The cache relies on a scheme for mapping URLs to files in the cache. -This variable names a function which sets the type of cache to use. -It takes a URL as argument and returns the absolute file name of the -corresponding cache file. The two supplied possibilities are -@code{url-cache-create-filename-using-md5} and -@code{url-cache-create-filename-human-readable}. -@end defopt - -@defun url-cache-create-filename-using-md5 url -Creates a cache file name from @var{url} using MD5 hashing. -This is creates entries with very few cache collisions and is fast. -@cindex MD5 -@smallexample -(url-cache-create-filename-using-md5 "http://www.example.com/foo/bar") - @result{} "/home/fx/.url/cache/fx/http/com/example/www/b8a35774ad20db71c7c3409a5410e74f" -@end smallexample -@end defun - -@defun url-cache-create-filename-human-readable url -Creates a cache file name from @var{url} more obviously connected to -@var{url} than for @code{url-cache-create-filename-using-md5}, but -more likely to conflict with other files. -@smallexample -(url-cache-create-filename-human-readable "http://www.example.com/foo/bar") - @result{} "/home/fx/.url/cache/fx/http/com/example/www/foo/bar" -@end smallexample -@end defun - -@defun url-cache-expired -This function returns non-nil if a cache entry has expired (or is absent). -The arguments are a URL and optional expiration delay in seconds -(default @var{url-cache-expire-time}). -@end defun - -@defopt url-cache-expire-time -This variable is the default number of seconds to use for the -expire-time argument of the function @code{url-cache-expired}. -@end defopt - -@defun url-fetch-from-cache -This function takes a URL as its argument and returns a buffer -containing the data cached for that URL. -@end defun - -@c Fixme: never actually used currently? -@c @defopt url-standalone-mode -@c @cindex Relying on cache -@c @cindex Cache only mode -@c @cindex Standalone mode -@c If this variable is non-@code{nil}, the library relies solely on the -@c cache for fetching documents and avoids checking if they have changed -@c on remote servers. -@c @end defopt - -@c With a large cache of documents on the local disk, it can be very handy -@c when traveling, or any other time the network connection is not active -@c (a laptop with a dial-on-demand PPP connection, etc). Emacs/W3 can rely -@c solely on its cache, and avoid checking to see if the page has changed -@c on the remote server. In the case of a dial-on-demand PPP connection, -@c this will keep the phone line free as long as possible, only bringing up -@c the PPP connection when asking for a page that is not located in the -@c cache. This is very useful for demonstrations as well. - -@node Proxies -@section Proxies and Gatewaying - -@c fixme: check/document url-ns stuff -@cindex proxy servers -@cindex proxies -@cindex environment variables -@vindex HTTP_PROXY -Proxy servers are commonly used to provide gateways through firewalls -or as caches serving some more-or-less local network. Each protocol -(HTTP, FTP, etc.)@: can have a different gateway server. Proxying is -conventionally configured commonly amongst different programs through -environment variables of the form @code{@var{protocol}_proxy}, where -@var{protocol} is one of the supported network protocols (@code{http}, -@code{ftp} etc.). The library recognizes such variables in either -upper or lower case. Their values are of one of the forms: -@itemize @bullet -@item @code{@var{host}:@var{port}} -@item A full URL; -@item Simply a host name. -@end itemize - -@vindex NO_PROXY -The @code{NO_PROXY} environment variable specifies URLs that should be -excluded from proxying (on servers that should be contacted directly). -This should be a comma-separated list of hostnames, domain names, or a -mixture of both. Asterisks can be used as wildcards, but other -clients may not support that. Domain names may be indicated by a -leading dot. For example: -@example -NO_PROXY="*.aventail.com,home.com,.seanet.com" -@end example -@noindent says to contact all machines in the @samp{aventail.com} and -@samp{seanet.com} domains directly, as well as the machine named -@samp{home.com}. If @code{NO_PROXY} isn't defined, @code{no_PROXY} -and @code{no_proxy} are also tried, in that order. - -Proxies may also be specified directly in Lisp. - -@defopt url-proxy-services -This variable is an alist of URL schemes and proxy servers that -gateway them. The items are of the form @w{@code{(@var{scheme} -. @var{host}:@var{portnumber})}}, says that the URL @var{scheme} is -gatewayed through @var{portnumber} on the specified @var{host}. An -exception is the pseudo scheme @code{"no_proxy"}, which is paired with -a regexp matching host names not to be proxied. This variable is -initialized from the environment as above. - -@example -(setq url-proxy-services - '(("http" . "proxy.aventail.com:80") - ("no_proxy" . "^.*\\(aventail\\|seanet\\)\\.com"))) -@end example -@end defopt - -@node Gateways in general -@section Gateways in General -@cindex gateways -@cindex firewalls - -The library provides a general gateway layer through which all -networking passes. It can both control access to the network and -provide access through gateways in firewalls. This may make direct -connections in some cases and pass through some sort of gateway in -others.@footnote{Proxies (which only operate over HTTP) are -implemented using this.} The library's basic function responsible for -making connections is @code{url-open-stream}. - -@defun url-open-stream name buffer host service -@cindex opening a stream -@cindex stream, opening -Open a stream to @var{host}, possibly via a gateway. The other -arguments are as for @code{open-network-stream}. This will not make a -connection if @code{url-gateway-unplugged} is non-@code{nil}. -@end defun - -@defvar url-gateway-local-host-regexp -This is a regular expression that matches local hosts that do not -require the use of a gateway. If @code{nil}, all connections are made -through the gateway. -@end defvar - -@defvar url-gateway-method -This variable controls which gateway method is used. It may be useful -to bind it temporarily in some applications. It has values taken from -a list of symbols. Possible values are: - -@table @code -@item telnet -@cindex @command{telnet} -Use this method if you must first telnet and log into a gateway host, -and then run telnet from that host to connect to outside machines. - -@item rlogin -@cindex @command{rlogin} -This method is identical to @code{telnet}, but uses @command{rlogin} -to log into the remote machine without having to send the username and -password over the wire every time. - -@item socks -@cindex @sc{socks} -Use if the firewall has a @sc{socks} gateway running on it. The -@sc{socks} v5 protocol is defined in RFC 1928. - -@c @item ssl -@c This probably shouldn't be documented -@c Fixme: why not? -- fx - -@item native -This method uses Emacs's builtin networking directly. This is the -default. It can be used only if there is no firewall blocking access. -@end table -@end defvar - -The following variables control the gateway methods. - -@defopt url-gateway-telnet-host -The gateway host to telnet to. Once logged in there, you then telnet -out to the hosts you want to connect to. -@end defopt -@defopt url-gateway-telnet-parameters -This should be a list of parameters to pass to the @command{telnet} program. -@end defopt -@defopt url-gateway-telnet-password-prompt -This is a regular expression that matches the password prompt when -logging in. -@end defopt -@defopt url-gateway-telnet-login-prompt -This is a regular expression that matches the username prompt when -logging in. -@end defopt -@defopt url-gateway-telnet-user-name -The username to log in with. -@end defopt -@defopt url-gateway-telnet-password -The password to send when logging in. -@end defopt -@defopt url-gateway-prompt-pattern -This is a regular expression that matches the shell prompt. -@end defopt - -@defopt url-gateway-rlogin-host -Host to @samp{rlogin} to before telnetting out. -@end defopt -@defopt url-gateway-rlogin-parameters -Parameters to pass to @samp{rsh}. -@end defopt -@defopt url-gateway-rlogin-user-name -User name to use when logging in to the gateway. -@end defopt -@defopt url-gateway-prompt-pattern -This is a regular expression that matches the shell prompt. -@end defopt - -@defopt socks-server -This specifies the default server, it takes the form -@w{@code{("Default server" @var{server} @var{port} @var{version})}} -where @var{version} can be either 4 or 5. -@end defopt -@defvar socks-password -If this is @code{nil} then you will be asked for the password, -otherwise it will be used as the password for authenticating you to -the @sc{socks} server. -@end defvar -@defvar socks-username -This is the username to use when authenticating yourself to the -@sc{socks} server. By default this is your login name. -@end defvar -@defvar socks-timeout -This controls how long, in seconds, to wait for responses from the -@sc{socks} server; it is 5 by default. -@end defvar -@c fixme: these have been effectively commented-out in the code -@c @defopt socks-server-aliases -@c This a list of server aliases. It is a list of aliases of the form -@c @var{(alias hostname port version)}. -@c @end defopt -@c @defopt socks-network-aliases -@c This a list of network aliases. Each entry in the list takes the form -@c @var{(alias (network))} where @var{alias} is a string that names the -@c @var{network}. The networks can contain a pair (not a dotted pair) of -@c @sc{ip} addresses which specify a range of @sc{ip} addresses, an @sc{ip} -@c address and a netmask, a domain name or a unique hostname or @sc{ip} -@c address. -@c @end defopt -@c @defopt socks-redirection-rules -@c This a list of redirection rules. Each rule take the form -@c @var{(Destination network Connection type)} where @var{Destination -@c network} is a network alias from @code{socks-network-aliases} and -@c @var{Connection type} can be @code{nil} in which case a direct -@c connection is used, or it can be an alias from -@c @code{socks-server-aliases} in which case that server is used as a -@c proxy. -@c @end defopt -@defopt socks-nslookup-program -@cindex @command{nslookup} -This the @samp{nslookup} program. It is @code{"nslookup"} by default. -@end defopt - -@menu -* Suppressing network connections:: -@end menu -@c * Broken hostname resolution:: - -@node Suppressing network connections -@subsection Suppressing Network Connections - -@cindex network connections, suppressing -@cindex suppressing network connections -@cindex bugs, HTML -@cindex HTML `bugs' -In some circumstances it is desirable to suppress making network -connections. A typical case is when rendering HTML in a mail user -agent, when external URLs should not be activated, particularly to -avoid ``bugs'' which ``call home'' by fetch single-pixel images and the -like. To arrange this, bind the following variable for the duration -of such processing. - -@defvar url-gateway-unplugged -If this variable is non-@code{nil} new network connections are never -opened by the URL library. -@end defvar - -@c @node Broken hostname resolution -@c @subsection Broken Hostname Resolution - -@c @cindex hostname resolver -@c @cindex resolver, hostname -@c Some C libraries do not include the hostname resolver routines in -@c their static libraries. If Emacs was linked statically, and was not -@c linked with the resolver libraries, it will not be able to get to any -@c machines off the local network. This is characterized by being able -@c to reach someplace with a raw ip number, but not its hostname -@c (@url{http://129.79.254.191/} works, but -@c @url{http://www.cs.indiana.edu/} doesn't). This used to happen on -@c SunOS4 and Ultrix, but is now probably now rare. If Emacs can't be -@c rebuilt linked against the resolver library, it can use the external -@c @command{nslookup} program instead. - -@c @defopt url-gateway-broken-resolution -@c @cindex @code{nslookup} program -@c @cindex program, @code{nslookup} -@c If non-@code{nil}, this variable says to use the program specified by -@c @code{url-gateway-nslookup-program} program to do hostname resolution. -@c @end defopt - -@c @defopt url-gateway-nslookup-program -@c The name of the program to do hostname lookup if Emacs can't do it -@c directly. This program should expect a single argument on the command -@c line---the hostname to resolve---and should produce output similar to -@c the standard Unix @command{nslookup} program: -@c @example -@c Name: www.cs.indiana.edu -@c Address: 129.79.254.191 -@c @end example -@c @end defopt - -@node History -@section History - -@findex url-do-setup -The library can maintain a global history list tracking URLs accessed. -URL completion can be done from it. The history mechanism is set up -automatically via @code{url-do-setup} when it is configured to be on. -Note that the size of the history list is currently not limited. - -@vindex url-history-hash-table -The history ``list'' is actually a hash table, -@code{url-history-hash-table}. It contains access times keyed by URL -strings. The times are in the format returned by @code{current-time}. - -@defun url-history-update-url url time -This function updates the history table with an entry for @var{url} -accessed at the given @var{time}. -@end defun - -@defopt url-history-track -If non-@code{nil}, the library will keep track of all the URLs -accessed. If it is @code{t}, the list is saved to disk at the end of -each Emacs session. The default is @code{nil}. -@end defopt - -@defopt url-history-file -The file storing the history list between sessions. It defaults to -@file{history} in @code{url-configuration-directory}. -@end defopt - -@defopt url-history-save-interval -@findex url-history-setup-save-timer -The number of seconds between automatic saves of the history list. -Default is one hour. Note that if you change this variable directly, -rather than using Custom, after @code{url-do-setup} has been run, you -need to run the function @code{url-history-setup-save-timer}. -@end defopt - -@defun url-history-parse-history &optional fname -Parses the history file @var{fname} (default @code{url-history-file}) -and sets up the history list. -@end defun - -@defun url-history-save-history &optional fname -Saves the current history to file @var{fname} (default -@code{url-history-file}). -@end defun - -@defun url-completion-function string predicate function -You can use this function to do completion of URLs from the history. -@end defun - -@node Customization -@chapter Customization - -@section Environment Variables - -@cindex environment variables -The following environment variables affect the library's operation at -startup. - -@table @code -@item TMPDIR -@vindex TMPDIR -@vindex url-temporary-directory -If this is defined, @var{url-temporary-directory} is initialized from -it. -@end table - -@section General User Options - -The following user options, settable with Customize, affect the -general operation of the package. - -@defopt url-debug -@cindex debugging -Specifies the types of debug messages which are logged to -the @code{*URL-DEBUG*} buffer. -@code{t} means log all messages. -A number means log all messages and show them with @code{message}. -It may also be a list of the types of messages to be logged. -@end defopt -@defopt url-personal-mail-address -@end defopt -@defopt url-privacy-level -@end defopt -@defopt url-uncompressor-alist -@end defopt -@defopt url-passwd-entry-func -@end defopt -@defopt url-standalone-mode -@end defopt -@defopt url-bad-port-list -@end defopt -@defopt url-max-password-attempts -@end defopt -@defopt url-temporary-directory -@end defopt -@defopt url-show-status -@end defopt -@defopt url-confirmation-func -The function to use for asking yes or no functions. This is normally -either @code{y-or-n-p} or @code{yes-or-no-p}, but could be another -function taking a single argument (the prompt) and returning @code{t} -only if an affirmative answer is given. -@end defopt -@defopt url-gateway-method -@c fixme: describe gatewaying -A symbol specifying the type of gateway support to use for connections -from the local machine. The supported methods are: - -@table @code -@item telnet -Run telnet in a subprocess to connect; -@item rlogin -Rlogin to another machine to connect; -@item socks -Connect through a socks server; -@item ssl -Connect with SSL; -@item native -Connect directly. -@end table -@end defopt - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index -@unnumbered Command and Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@bye diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi deleted file mode 100644 index 0d9bb286330..00000000000 --- a/doc/misc/vip.texi +++ /dev/null @@ -1,1947 +0,0 @@ -\input texinfo -@setfilename ../../info/vip -@settitle VIP - -@copying -Copyright @copyright{} 1987, 2001-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@titlepage -@sp 10 -@center @titlefont{VIP} -@sp 1 -@center A Vi Package for GNU Emacs -@center (Version 3.5, September 15, 1987) -@sp 2 -@center Masahiko Sato -@page -@vskip 0pt plus1filll -@insertcopying -@end titlepage - -@finalout -@contents - -@dircategory Emacs misc features -@direntry -* VIP: (vip). An older VI-emulation for Emacs. -@end direntry - -@ifnottex -@node Top, Survey,, (DIR) -@top VIP - -VIP is a Vi emulating package written in Emacs Lisp. VIP implements most -Vi commands including Ex commands. It is therefore hoped that this package -will enable you to do Vi style editing under the powerful GNU Emacs -environment. This info file describes the usage of VIP assuming that you -are fairly accustomed to Vi but not so much with Emacs. Also we will -concentrate mainly on differences from Vi, especially features unique to -VIP. - -It is recommended that you read nodes on survey and on customization before -you start using VIP. Other nodes may be visited as needed. - -Comments and bug reports are welcome. Please send messages to -@code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to -@code{masahiko@@sato.riec.tohoku.junet} if you are in Japan.@refill - -@insertcopying - -@end ifnottex - -@menu -* Survey:: A survey of VIP. -* Vi Commands:: Details of Vi commands. -* Ex Commands:: Details of Ex commands. -* Customization:: How to customize VIP. -* GNU Free Documentation License:: The license for this documentation. - -@end menu -@iftex -@unnumbered Introduction - -VIP is a Vi emulating package written in Emacs Lisp. VIP implements most -Vi commands including Ex commands. It is therefore hoped that this package -will enable you to do Vi style editing under the powerful GNU Emacs -environment. This manual describes the usage of VIP assuming that you are -fairly accustomed to Vi but not so much with Emacs. Also we will -concentrate mainly on differences from Vi, especially features unique to -VIP. - -It is recommended that you read chapters on survey and on customization -before you start using VIP. Other chapters may be used as future -references. - -Comments and bug reports are welcome. Please send messages to -@code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to -@code{masahiko@@unsun.riec.tohoku.junet} if you are in Japan. -@end iftex - -@node Survey, Basic Concepts, Top, Top -@chapter A Survey of VIP - -In this chapter we describe basics of VIP with emphasis on the features not -found in Vi and on how to use VIP under GNU Emacs. - -@menu -* Basic Concepts:: Basic concepts in Emacs. -* Loading VIP:: How to load VIP automatically. -* Modes in VIP:: VIP has three modes, which are orthogonal to modes - in Emacs. -* Differences from Vi:: Differences of VIP from Vi is explained. -@end menu - -@node Basic Concepts, Loading VIP, Survey, Survey -@section Basic Concepts - -We begin by explaining some basic concepts of Emacs. These concepts are -explained in more detail in the GNU Emacs Manual. - -@cindex buffer -@cindex point -@cindex mark -@cindex text -@cindex looking at -@cindex end (of buffer) -@cindex region - -Conceptually, a @dfn{buffer} is just a string of @acronym{ASCII} characters and two -special characters @key{PNT} (@dfn{point}) and @key{MRK} (@dfn{mark}) such -that the character @key{PNT} occurs exactly once and @key{MRK} occurs at -most once. The @dfn{text} of a buffer is obtained by deleting the -occurrences of @key{PNT} and @key{MRK}. If, in a buffer, there is a -character following @key{PNT} then we say that point is @dfn{looking at} -the character; otherwise we say that point is @dfn{at the end of buffer}. -@key{PNT} and @key{MRK} are used -to indicate positions in a buffer and they are not part of the text of the -buffer. If a buffer contains a @key{MRK} then the text between @key{MRK} -and @key{PNT} is called the @dfn{region} of the buffer.@refill - -@cindex window - -Emacs provides (multiple) @dfn{windows} on the screen, and you can see the -content of a buffer through the window associated with the buffer. The -cursor of the screen is always positioned on the character after @key{PNT}. -@refill - -@cindex mode -@cindex keymap -@cindex local keymap -@cindex global keymap - -A @dfn{keymap} is a table that records the bindings between characters and -command functions. There is the @dfn{global keymap} common to all the -buffers. Each buffer has its @dfn{local keymap} that determines the -@dfn{mode} of the buffer. Local keymap overrides global keymap, so that if -a function is bound to some key in the local keymap then that function will -be executed when you type the key. If no function is bound to a key in the -local map, however, the function bound to the key in the global map becomes -in effect.@refill - -@node Loading VIP, Modes in VIP, Basic Concepts, Survey -@section Loading VIP - -The recommended way to load VIP automatically is to include the line: -@example -(load "vip") -@end example -@noindent -in your @file{.emacs} file. The @file{.emacs} file is placed in your home -directory and it will be executed every time you invoke Emacs. If you wish -to be in vi mode whenever Emacs starts up, you can include the following -line in your @file{.emacs} file instead of the above line: -@example -(setq term-setup-hook 'vip-mode) -@end example -@noindent -(@xref{Vi Mode}, for the explanation of vi mode.) - -Even if your @file{.emacs} file does not contain any of the above lines, -you can load VIP and enter vi mode by typing the following from within -Emacs. -@example -M-x vip-mode -@end example -@noindent - -@node Modes in VIP, Emacs Mode, Loading VIP, Survey -@section Modes in VIP - -@kindex 032 @kbd{C-z} (@code{vip-change-mode-to-vi}) -@kindex 0301 @kbd{C-x C-z} (@code{suspend-emacs}) - -Loading VIP has the effect of globally binding @kbd{C-z} (@kbd{Control-z}) -to the function @code{vip-change-mode-to-vi}. The default binding of @kbd{C-z} -in GNU Emacs is @code{suspend-emacs}, but, you can also call -@code{suspend-emacs} by typing @kbd{C-x C-z}. Other than this, all the -key bindings of Emacs remain the same after loading VIP.@refill - -@cindex vi mode - -Now, if you hit @kbd{C-z}, the function @code{vip-change-mode-to-vi} will be -called and you will be in @dfn{vi mode}. (Some major modes may locally bind -@kbd{C-z} to some special functions. In such cases, you can call -@code{vip-change-mode-to-vi} by @code{execute-extended-command} which is -invoked by @kbd{M-x}. Here @kbd{M-x} means @kbd{Meta-x}, and if your -terminal does not have a @key{META} key you can enter it by typing -@kbd{@key{ESC} x}. The same effect can also be achieve by typing -@kbd{M-x vip-mode}.)@refill - -@cindex mode line - -You can observe the change of mode by looking at the @dfn{mode line}. For -instance, if the mode line is:@refill -@example ------Emacs: *scratch* (Lisp Interaction)----All------------ -@end example -@noindent -then it will change to: -@example ------Vi: *scratch* (Lisp Interaction)----All------------ -@end example -@noindent -Thus the word @samp{Emacs} in the mode line will change to @samp{Vi}. - -@cindex insert mode -@cindex emacs mode - -You can go back to the original @dfn{emacs mode} by typing @kbd{C-z} in -vi mode. Thus @kbd{C-z} toggles between these two modes.@refill - -Note that modes in VIP exist orthogonally to modes in Emacs. This means -that you can be in vi mode and at the same time, say, shell mode. - -Vi mode corresponds to Vi's command mode. From vi mode you can enter -@dfn{insert mode} (which corresponds to Vi's insert mode) by usual Vi command -keys like @kbd{i}, @kbd{a}, @kbd{o} @dots{} etc. - -In insert mode, the mode line will look like this: -@example ------Insert *scratch* (Lisp Interaction)----All------------ -@end example -@noindent -You can exit from insert mode by hitting @key{ESC} key as you do in Vi. - -That VIP has three modes may seem very complicated, but in fact it is not -so. VIP is implemented so that you can do most editing remaining only -in the two modes for Vi (that is vi mode and insert mode). - -@ifinfo -The figure below shows the transition of three modes in VIP. -@display - - - === C-z ==> == i,o ... ==> -emacs mode vi mode insert mode - <== X-z === <=== ESC ==== -@end display -@end ifinfo - -@menu -* Emacs Mode:: This is the mode you should know better. -* Vi Mode:: Vi commands are executed in this mode. -* Insert Mode:: You can enter text, and also can do editing if you - know enough Emacs commands. -@end menu - -@node Emacs Mode, Vi Mode, Modes in VIP, Modes in VIP -@subsection Emacs Mode - -@kindex 032 @kbd{C-z} (@code{vip-change-mode-to-vi}) - -You will be in this mode just after you loaded VIP. You can do all -normal Emacs editing in this mode. Note that the key @kbd{C-z} is globally -bound to @code{vip-change-mode-to-vi}. So, if you type @kbd{C-z} in this mode -then you will be in vi mode.@refill - -@node Vi Mode, Insert Mode, Emacs Mode, Modes in VIP -@subsection Vi Mode - -This mode corresponds to Vi's command mode. Most Vi commands work as they -do in Vi. You can go back to emacs mode by typing @kbd{C-z}. You can -enter insert mode, just as in Vi, by typing @kbd{i}, @kbd{a} etc. - -@node Insert Mode, Differences from Vi, Vi Mode, Modes in VIP -@subsection Insert Mode - -The key bindings in this mode is the same as in the emacs mode except for -the following 4 keys. So, you can move around in the buffer and change -its content while you are in insert mode. - -@table @kbd -@item @key{ESC} -@kindex 033 @kbd{ESC} (@code{vip-change-mode-to-vi}) (insert mode) -This key will take you back to vi mode. -@item C-h -@kindex 010 @kbd{C-h} (@code{vip-delete-backward-char}) (insert mode) -Delete previous character. -@item C-w -@kindex 027 @kbd{C-w} (@code{vip-delete-backward-word}) (insert mode) -Delete previous word. -@item C-z -@kindex 032 @kbd{C-z} (@code{vip-ESC}) (insert mode) -Typing this key has the same effect as typing @key{ESC} in emacs mode. -Thus typing @kbd{C-z x} in insert mode will have the same effect as typing -@kbd{ESC x} in emacs mode. -@end table - -@node Differences from Vi, Undoing, Insert Mode, Survey -@section Differences from Vi - -The major differences from Vi are explained below. - -@menu -* Undoing:: You can undo more in VIP. -* Changing:: Commands for changing the text. -* Searching:: Search commands. -* z Command:: You can now use zH, zM and zL as well as z- etc. -* Counts:: Some Vi commands which do not accept a count now - accept one. -* Marking:: You can now mark the current point, beginning of - the buffer etc. -* Region Commands:: You can now give a region as an argument for delete - commands etc. -* New Commands:: Some new commands not available in Vi are added. -* New Bindings:: Bindings of some keys are changed for the - convenience of editing under Emacs. -* Window Commands:: Commands for moving among windows etc. -* Buffer Commands:: Commands for selecting buffers etc. -* File Commands:: Commands for visiting files etc. -* Misc Commands:: Other useful commands. -@end menu - -@node Undoing, Changing, Differences from Vi, Differences from Vi -@subsection Undoing - -@kindex 165 @kbd{u} (@code{vip-undo}) -@kindex 056 @kbd{.} (@code{vip-repeat}) - -You can repeat undoing by the @kbd{.} key. So, @kbd{u} will undo -a single change, while @kbd{u .@: .@: .@:}, for instance, will undo 4 previous -changes. Undo is undoable as in Vi. So the content of the buffer will -be the same before and after @kbd{u u}.@refill - -@node Changing, Searching, Undoing, Differences from Vi -@subsection Changing - -Some commands which change a small number of characters are executed -slightly differently. Thus, if point is at the beginning of a word -@samp{foo} and you wished to change it to @samp{bar} by typing @w{@kbd{c w}}, -then VIP will prompt you for a new word in the minibuffer by the prompt -@samp{foo => }. You can then enter @samp{bar} followed by @key{RET} or -@key{ESC} to complete the command. Before you enter @key{RET} or -@key{ESC} you can abort the command by typing @kbd{C-g}. In general, -@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) -you can abort a partially formed command by typing @kbd{C-g}.@refill - -@node Searching, z Command, Changing, Differences from Vi -@subsection Searching - -@kindex 057 @kbd{/} (@code{vip-search-forward}) -@kindex 077 @kbd{?} (@code{vip-search-backward}) - -As in Vi, searching is done by @kbd{/} and @kbd{?}. The string will be -searched literally by default. To invoke a regular expression search, -first execute the search command @kbd{/} (or @kbd{?}) with empty search -string. (I.e, type @kbd{/} followed by @key{RET}.) -A search for empty string will toggle the search mode between vanilla -search and regular expression search. You cannot give an offset to the -search string. (It is a limitation.) By default, search will wrap around -the buffer as in Vi. You can change this by rebinding the variable -@code{vip-search-wrap-around}. @xref{Customization}, for how to do this.@refill - -@node z Command, Counts, Searching, Differences from Vi -@subsection z Command - -@kindex 1723 @kbd{z H} (@code{vip-line-to-top}) -@kindex 1721 @kbd{z RET} (@code{vip-line-to-top}) -@kindex 1723 @kbd{z M} (@code{vip-line-to-middle}) -@kindex 1722 @kbd{z .} (@code{vip-line-to-middle}) -@kindex 1723 @kbd{z L} (@code{vip-line-to-bottom}) -@kindex 1722 @kbd{z -} (@code{vip-line-to-bottom}) - -For those of you who cannot remember which of @kbd{z} followed by @key{RET}, -@kbd{.}@: and @kbd{-} do what. You can also use @kbd{z} followed by @kbd{H}, -@kbd{M} and @kbd{L} to place the current line in the Home (Middle, and -Last) line of the window.@refill - -@node Counts, Marking, z Command, Differences from Vi -@subsection Counts - -Some Vi commands which do not accept a count now accept one - -@table @kbd -@item p -@itemx P -@kindex 160 @kbd{p} (@code{vip-put-back}) -@kindex 120 @kbd{P} (@code{vip-Put-back}) -Given counts, text will be yanked (in Vi's sense) that many times. Thus -@kbd{3 p} is the same as @kbd{p p p}. -@item o -@itemx O -@kindex 157 @kbd{o} (@code{vip-open-line}) -@kindex 117 @kbd{O} (@code{vip-Open-line}) -Given counts, that many copies of text will be inserted. Thus -@kbd{o a b c @key{ESC}} will insert 3 lines of @samp{abc} below the current -line. -@item / -@itemx ? -@kindex 057 @kbd{/} (@code{vip-search-forward}) -@kindex 077 @kbd{?} (@code{vip-search-backward}) -Given a count @var{n}, @var{n}-th occurrence will be searched. -@end table - -@node Marking, Region Commands, Counts, Differences from Vi -@subsection Marking - -Typing an @kbd{m} followed by a lower-case character @var{ch} marks the -point to the register named @var{ch} as in Vi. In addition to these, we -have following key bindings for marking. - -@kindex 155 @kbd{m} (@code{vip-mark-point}) - -@table @kbd -@item m < -Set mark at the beginning of buffer. -@item m > -Set mark at the end of buffer. -@item m . -Set mark at point (and push old mark on mark ring). -@item m , -Jump to mark (and pop mark off the mark ring). -@end table - -@node Region Commands, New Commands, Marking, Differences from Vi -@subsection Region Commands - -@cindex region - -Vi operators like @kbd{d}, @kbd{c} etc. are usually used in combination -with motion commands. It is now possible to use current region as the -argument to these operators. (A @dfn{region} is a part of buffer -delimited by point and mark.) The key @kbd{r} is used for this purpose. -Thus @kbd{d r} will delete the current region. If @kbd{R} is used instead -of @kbd{r} the region will first be enlarged so that it will become the -smallest region containing the original region and consisting of whole -lines. Thus @kbd{m .@: d R} will have the same effect as @kbd{d d}.@refill - -@node New Commands, New Bindings, Region Commands, Differences from Vi -@subsection Some New Commands - -Note that the keys below (except for @kbd{R}) are not used in Vi. - -@table @kbd -@item C-a -@kindex 001 @kbd{C-a} (@code{vip-beginning-of-line}) -Move point to the beginning of line. -@item C-n -@kindex 016 @kbd{C-n} (@code{vip-next-window}) -If you have two or more windows in the screen, this key will move point to -the next window. -@item C-o -@kindex 017 @kbd{C-o} (@code{vip-open-line-at-point}) -Insert a newline and leave point before it, and then enter insert mode. -@item C-r -@kindex 022 @kbd{C-r} (@code{isearch-backward}) -Backward incremental search. -@item C-s -@kindex 023 @kbd{C-s} (@code{isearch-forward}) -Forward incremental search. -@item C-c -@itemx C-x -@itemx @key{ESC} -@kindex 003 @kbd{C-c} (@code{vip-ctl-c}) -@kindex 0300 @kbd{C-x} (@code{vip-ctl-x}) -@kindex 033 @kbd{ESC} (@code{vip-ESC}) -These keys will exit from vi mode and return to emacs mode temporarily. If -you hit one of these keys, Emacs will be in emacs mode and will believe -that you hit that key in emacs mode. For example, if you hit @kbd{C-x} -followed by @kbd{2}, then the current window will be split into 2 and you -will be in vi mode again. -@item \ -@kindex 134 @kbd{\} (@code{vip-escape-to-emacs}) -Escape to emacs mode. Hitting @kbd{\} will take you to emacs mode, and you -can execute a single Emacs command. After executing the Emacs command you -will be in vi mode again. You can give a count before typing @kbd{\}. -Thus @kbd{5 \ *}, as well as @kbd{\ C-u 5 *}, will insert @samp{*****} -before point. Similarly @kbd{1 0 \ C-p} will move the point 10 lines above -the current line.@refill -@item K -@kindex 113 @kbd{K} (@code{vip-kill-buffer}) -Kill current buffer if it is not modified. Useful when you selected a -buffer which you did not want. -@item Q -@itemx R -@kindex 121 @kbd{Q} (@code{vip-query-replace}) -@kindex 122 @kbd{R} (@code{vip-replace-string}) -@kbd{Q} is for query replace and @kbd{R} is for replace. By default, -string to be replaced are treated literally. If you wish to do a regular -expression replace, first do replace with empty string as the string to be -replaced. In this way, you can toggle between vanilla and regular -expression replacement. -@item v -@itemx V -@kindex 166 @kbd{v} (@code{vip-find-file}) -@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) -These keys are used to Visit files. @kbd{v} will switch to a buffer -visiting file whose name can be entered in the minibuffer. @kbd{V} is -similar, but will use window different from the current window. -@item # -@kindex 0430 @kbd{#} (@code{vip-command-argument}) -If followed by a certain character @var{ch}, it becomes an operator whose -argument is the region determined by the motion command that follows. -Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q} and -@kbd{s}.@refill -@item # c -@kindex 0432 @kbd{# c} (@code{downcase-region}) -Change upper-case characters in the region to lower case -(@code{downcase-region}). -@item # C -@kindex 0431 @kbd{# C} (@code{upcase-region}) -Change lower-case characters in the region to upper case. For instance, -@kbd{# C 3 w} will capitalize 3 words from the current point -(@code{upcase-region}). -@item # g -@kindex 0432 @kbd{# g} (@code{vip-global-execute}) -Execute last keyboard macro for each line in the region -(@code{vip-global-execute}).@refill -@item # q -@kindex 0432 @kbd{# q} (@code{vip-quote-region}) -Insert specified string at the beginning of each line in the region -(@code{vip-quote-region}). -@item # s -@kindex 0432 @kbd{# s} (@code{spell-region}) -Check spelling of words in the region (@code{spell-region}). -@item * -@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) -Call last keyboard macro. -@end table - -@node New Bindings, Window Commands, New Commands, Differences from Vi -@subsection New Key Bindings - -In VIP the meanings of some keys are entirely different from Vi. These key -bindings are done deliberately in the hope that editing under Emacs will -become easier. It is however possible to rebind these keys to functions -which behave similarly as in Vi. @xref{Customizing Key Bindings}, for -details. - -@table @kbd -@item C-g -@itemx g -@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) -@kindex 147 @kbd{g} (@code{vip-info-on-file}) -In Vi, @kbd{C-g} is used to get information about the file associated to -the current buffer. Here, @kbd{g} will do that, and @kbd{C-g} is -used to abort a command (this is for compatibility with emacs mode.) -@item SPC -@itemx @key{RET} -@kindex 040 @kbd{SPC} (@code{vip-scroll}) -@kindex 015 @kbd{RET} (@code{vip-scroll-back}) -Now these keys will scroll up and down the text of current window. -Convenient for viewing the text. -@item s -@itemx S -@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) -@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) -They are used to switch to a specified buffer. Useful for switching to -already existing buffer since buffer name completion is provided. Also -a default buffer will be given as part of the prompt, to which you can -switch by just typing @key{RET} key. @kbd{s} is used to select buffer -in the current window, while @kbd{S} selects buffer in another window. -@item C -@itemx X -@kindex 103 @kbd{C} (@code{vip-ctl-c-equivalent}) -@kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent}) -These keys will exit from vi mode and return to emacs mode temporarily. -If you type @kbd{C} (@kbd{X}), Emacs will be in emacs mode and will believe -that you have typed @kbd{C-c} (@kbd{C-x}, resp.) in emacs mode. Moreover, -if the following character you type is an upper-case letter, then Emacs -will believe that you have typed the corresponding control character. -You will be in vi mode again after the command is executed. For example, -typing @kbd{X S} in vi mode is the same as typing @kbd{C-x C-s} in emacs -mode. You get the same effect by typing @kbd{C-x C-s} in vi mode, but -the idea here is that you can execute useful Emacs commands without typing -control characters. For example, if you hit @kbd{X} (or @kbd{C-x}) followed -by @kbd{2}, then the current window will be split into 2 and you will be in -vi mode again.@refill -@end table - -In addition to these, @code{ctl-x-map} is slightly modified: - -@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) - -@table @kbd -@item X 3 -@itemx C-x 3 -This is equivalent to @kbd{C-x 1 C-x 2} (1 + 2 = 3). -@end table - -@node Window Commands, Buffer Commands, New Bindings, Differences from Vi -@subsection Window Commands - -In this and following subsections, we give a summary of key bindings for -basic functions related to windows, buffers and files. - -@table @kbd -@item C-n -@kindex 016 @kbd{C-n} (@code{vip-next-window}) -Switch to next window. -@item X 1 -@itemx C-x 1 -@kindex 1301 @kbd{X 1} (@code{delete-other-windows}) -Delete other windows. -@item X 2 -@itemx C-x 2 -@kindex 1301 @kbd{X 2} (@code{split-window-vertically}) -Split current window into two windows. -@item X 3 -@itemx C-x 3 -@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) -Show current buffer in two windows. -@end table - -@node Buffer Commands, File Commands, Window Commands, Differences from Vi -@subsection Buffer Commands - -@table @kbd -@item s -@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) -Switch to the specified buffer in the current window -(@code{vip-switch-to-buffer}). -@item S -@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) -Switch to the specified buffer in another window -(@code{vip-switch-to-buffer-other-window}). -@item K -@kindex 113 @kbd{K} (@code{vip-kill-buffer}) -Kill the current buffer if it is not modified. -@item X S -@itemx C-x C-s -@kindex 1302 @kbd{X S} (@code{save-buffer}) -Save the current buffer in the file associated to the buffer. -@end table - -@node File Commands, Misc Commands, Buffer Commands, Differences from Vi -@subsection File Commands - -@table @kbd -@item v -@kindex 166 @kbd{v} (@code{vip-find-file}) -Visit specified file in the current window. -@item V -@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) -Visit specified file in another window. -@item X W -@itemx C-x C-w -@kindex 1302 @kbd{X W} (@code{write-file}) -Write current buffer into the specified file. -@item X I -@itemx C-x C-i -@kindex 1302 @kbd{X I} (@code{insert-file}) - -Insert specified file at point. -@end table - -@node Misc Commands, Vi Commands, File Commands, Differences from Vi -@subsection Miscellaneous Commands - -@table @kbd -@item X ( -@itemx C-x ( -@kindex 1301 @kbd{X (} (@code{start-kbd-macro}) -Start remembering keyboard macro. -@item X ) -@itemx C-x ) -@kindex 1301 @kbd{X )} (@code{end-kbd-macro}) -Finish remembering keyboard macro. -@item * -@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) -Call last remembered keyboard macro. -@item X Z -@itemx C-x C-z -@kindex 1302 @kbd{X Z} (@code{suspend-emacs}) -Suspend Emacs. -@item Z Z -Exit Emacs. -@itemx Q -Query replace. -@itemx R -Replace. -@end table - -@node Vi Commands, Numeric Arguments, Misc Commands, Top -@chapter Vi Commands - -This chapter describes Vi commands other than Ex commands implemented in -VIP. Except for the last section which discusses insert mode, all the -commands described in this chapter are to be used in vi mode. - -@menu -* Numeric Arguments:: Many commands accept numeric arguments -* Important Keys:: Some very important keys. -* Buffers and Windows:: Commands for handling buffers and windows. -* Files:: Commands for handling files. -* Viewing the Buffer:: How you can view the current buffer. -* Mark Commands:: Marking positions in a buffer. -* Motion Commands:: Commands for moving point. -* Searching and Replacing:: Commands for searching and replacing. -* Modifying Commands:: Commands for modifying the buffer. -* Other Vi Commands:: Miscellaneous Commands. -* Commands in Insert Mode:: Commands for entering insert mode. -@end menu - -@node Numeric Arguments, Important Keys, Vi Commands, Vi Commands -@section Numeric Arguments - -@cindex numeric arguments -@cindex count -@kindex 061 @kbd{1} (numeric argument) -@kindex 062 @kbd{2} (numeric argument) -@kindex 063 @kbd{3} (numeric argument) -@kindex 064 @kbd{4} (numeric argument) -@kindex 065 @kbd{5} (numeric argument) -@kindex 066 @kbd{6} (numeric argument) -@kindex 067 @kbd{7} (numeric argument) -@kindex 068 @kbd{8} (numeric argument) -@kindex 069 @kbd{9} (numeric argument) - -Most Vi commands accept a @dfn{numeric argument} which can be supplied as -a prefix to the commands. A numeric argument is also called a @dfn{count}. -In many cases, if a count is given, the command is executed that many times. -For instance, @kbd{5 d d} deletes 5 lines while simple @kbd{d d} deletes a -line. In this manual the metavariable @var{n} will denote a count.@refill - -@node Important Keys, Buffers and Windows, Numeric Arguments, Vi Commands -@section Important Keys - -The keys @kbd{C-g} and @kbd{C-l} are unique in that their associated -functions are the same in any of emacs, vi and insert mode. - -@table @kbd -@item C-g -@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) -Quit. Cancel running or partially typed command (@code{keyboard-quit}). -@item C-l -@kindex 014 @kbd{C-l} (@code{recenter}) -Clear the screen and reprint everything (@code{recenter}). -@end table - -In Emacs many commands are bound to the key strokes that start with -@kbd{C-x}, @kbd{C-c} and @key{ESC}. These commands can be -accessed from vi mode as easily as from emacs mode.@refill - -@table @kbd -@item C-x -@itemx C-c -@itemx @key{ESC} -@kindex 003 @kbd{C-c} (@code{vip-ctl-c}) -@kindex 0300 @kbd{C-x} (@code{vip-ctl-x}) -@kindex 033 @kbd{ESC} (@code{vip-ESC}) -Typing one of these keys have the same effect as typing it in emacs mode. -Appropriate command will be executed according as the keys you type after -it. You will be in vi mode again after the execution of the command. -For instance, if you type @kbd{@key{ESC} <} (in vi mode) then the cursor will -move to the beginning of the buffer and you will still be in vi mode. -@item C -@itemx X -@kindex 103 @kbd{C} (@code{vip-ctl-c-equivalent}) -@kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent}) -Typing one of these keys have the effect of typing the corresponding -control character in emacs mode. Moreover, if you type an upper-case -character following it, that character will also be translated to the -corresponding control character. Thus typing @kbd{X W} in vi mode is the -same as typing @kbd{C-x C-w} in emacs mode. You will be in vi mode again -after the execution of a command. -@item \ -@kindex 134 @kbd{\} (@code{vip-escape-to-emacs}) -Escape to emacs mode. Hitting the @kbd{\} key will take you to emacs mode, -and you can execute a single Emacs command. After executing the -Emacs command you will be in vi mode again. You can give a count before -typing @kbd{\}. Thus @kbd{5 \ +}, as well as @kbd{\ C-u 5 +}, will insert -@samp{+++++} before point.@refill -@end table - -@node Buffers and Windows, Files, Important Keys, Vi Commands -@section Buffers and Windows - -@cindex buffer -@cindex selected buffer -@cindex current buffer - -In Emacs the text you edit is stored in a @dfn{buffer}. -See GNU Emacs Manual, for details. There is always one @dfn{current} -buffer, also called the @dfn{selected buffer}.@refill - -@cindex window -@cindex modified (buffer) - -You can see the contents of buffers through @dfn{windows} created by Emacs. -When you have multiple windows on the screen only one of them is selected. -Each buffer has a unique name, and each window has a mode line which shows -the name of the buffer associated with the window and other information -about the status of the buffer. You can change the format of the mode -line, but normally if you see @samp{**} at the beginning of a mode line it -means that the buffer is @dfn{modified}. If you write out the content of -the buffer to a file, then the buffer will become not modified. Also if -you see @samp{%%} at the beginning of the mode line, it means that the file -associated with the buffer is write protected. - -We have the following commands related to windows and buffers. - -@table @kbd -@item C-n -@kindex 016 @kbd{C-n} (@code{vip-next-window}) -Move cursor to the next-window (@code{vip-next-window}). -@item X 1 -@kindex 1301 @kbd{X 1} (@code{delete-other-windows}) -Delete other windows and make the selected window fill the screen -@*(@code{delete-other-windows}). -@item X 2 -@kindex 1301 @kbd{X 2} (@code{split-window-vertically}) -Split current window into two windows (@code{split-window-vertically}). -@item X 3 -@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) -Show current buffer in two windows. -@item s @var{buffer} @key{RET} -@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) -Select or create a buffer named @var{buffer} (@code{vip-switch-to-buffer}). -@item S @var{buffer} @key{RET} -@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) -Similar but select a buffer named @var{buffer} in another window -@*(@code{vip-switch-to-buffer-other-window}). -@item K -@kindex 113 @kbd{K} (@code{vip-kill-buffer}) -Kill the current buffer if it is not modified or if it is not associated -with a file @*(@code{vip-kill-buffer}). -@item X B -@kindex 1302 @kbd{X B} (@code{list-buffers}) -List the existing buffers (@code{list-buffers}). -@end table - -@cindex buffer name completion - -As @dfn{buffer name completion} is provided, you have only to type in -initial substring of the buffer name which is sufficient to identify it -among names of existing buffers. After that, if you hit @key{TAB} the rest -of the buffer name will be supplied by the system, and you can confirm it -by @key{RET}. The default buffer name to switch to will also be prompted, -and you can select it by giving a simple @key{RET}. See GNU Emacs Manual -for details of completion. - -@node Files, Viewing the Buffer, Buffers and Windows, Vi Commands -@section Files - -We have the following commands related to files. They are used to visit, -save and insert files. - -@table @kbd -@item v @var{file} @key{RET} -@kindex 166 @kbd{v} (@code{vip-find-file}) -Visit specified file in the current window (@code{vip-find-file}). -@item V @var{file} @key{RET} -@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) -Visit specified file in another window (@code{vip-find-file-other-window}). -@item X S -@kindex 1302 @kbd{X S} (@code{save-buffer}) -Save current buffer to the file associated with the buffer. If no file is -associated with the buffer, the name of the file to write out the content -of the buffer will be asked in the minibuffer. -@item X W @var{file} @key{RET} -@kindex 1302 @kbd{X W} (@code{write-file}) -Write current buffer into a specified file. -@item X I @var{file} @key{RET} -@kindex 1302 @kbd{X I} (@code{insert-file}) -Insert a specified file at point. -@item g -@kindex 147 @kbd{g} (@code{vip-info-on-file}) -Give information on the file associated with the current buffer. Tell you -the name of the file associated with the buffer, the line number of the -current point and total line numbers in the buffer. If no file is -associated with the buffer, this fact will be indicated by the null file -name @samp{""}. -@end table - -@cindex visiting (a file) -@cindex default directory - -In Emacs, you can edit a file by @dfn{visiting} it. If you wish to visit a -file in the current window, you can just type @kbd{v}. Emacs maintains the -@dfn{default directory} which is specific to each buffer. Suppose, for -instance, that the default directory of the current buffer is -@file{/usr/masahiko/lisp/}. Then you will get the following prompt in the -minibuffer.@refill -@example -visit file: /usr/masahiko/lisp/ -@end example -@noindent -@cindex file name completion -If you wish to visit, say, @file{vip.el} in this directory, then you can -just type @samp{vip.el} followed by @key{RET}. If the file @file{vip.el} -already exists in the directory, Emacs will visit that file, and if not, -the file will be created. Emacs will use the file name (@file{vip.el}, in -this case) as the name of the buffer visiting the file. In order to make -the buffer name unique, Emacs may append @samp{<2>}, @samp{<3>} etc., to -the buffer name. As the @dfn{file name completion} is provided here, you -can sometime save typing. For instance, suppose there is only one file in the -default directory whose name starts with @samp{v}, that is @samp{vip.el}. -Then if you just type @kbd{v @key{TAB}} then it will be completed to -@samp{vip.el}. Thus, in this case, you just have to type @kbd{v v @key{TAB} -@key{RET}} to visit @file{/usr/masahiko/lisp/vip.el}. Continuing the -example, let us now suppose that you wished to visit the file -@file{/usr/masahiko/man/vip.texinfo}. Then to the same prompt which you get -after you typed @kbd{v}, you can enter @samp{/usr/masahiko/man/vip.texinfo} or -@samp{../man/vip.texinfo} followed by @key{RET}. - -Use @kbd{V} instead of @kbd{v}, if you wish to visit a file in another -window. - -You can verify which file you are editing by typing @kbd{g}. (You can also -type @kbd{X B} to get information on other buffers too.) If you type -@kbd{g} you will get an information like below in the echo area:@refill -@example -"/usr/masahiko/man/vip.texinfo" line 921 of 1949 -@end example - -After you edited the buffer (@samp{vip.texinfo}, in our example) for a while, -you may wish to save it in a file. If you wish to save it in the file -associated with the buffer (@file{/usr/masahiko/man/vip.texinfo}, in this -case), you can just say @kbd{X S}. If you wish to save it in another file, -you can type @kbd{X W}. You will then get a similar prompt as you get for -@kbd{v}, to which you can enter the file name.@refill - -@node Viewing the Buffer, Mark Commands, Files, Vi Commands -@section Viewing the Buffer - -In this and next section we discuss commands for moving around in the -buffer. These command do not change the content of the buffer. The -following commands are useful for viewing the content of the current -buffer. - -@table @kbd -@item @key{SPC} -@itemx C-f -@kindex 040 @kbd{SPC} (@code{vip-scroll}) -@kindex 006 @kbd{C-f} (@code{vip-scroll-back}) -Scroll text of current window upward almost full screen. You can go -@i{forward} in the buffer by this command (@code{vip-scroll}). -@item @key{RET} -@itemx C-b -@kindex 015 @kbd{RET} (@code{vip-scroll-back}) -@kindex 002 @kbd{C-b} (@code{vip-scroll-back}) -Scroll text of current window downward almost full screen. You can go -@i{backward} in the buffer by this command (@code{vip-scroll-back}). -@itemx C-d -@kindex 004 @kbd{C-d} (@code{vip-scroll-up}) -Scroll text of current window upward half screen. You can go -@i{down} in the buffer by this command (@code{vip-scroll-down}). -@itemx C-u -@kindex 025 @kbd{C-u} (@code{vip-scroll-down}) -Scroll text of current window downward half screen. You can go -@i{up} in the buffer by this command (@code{vip-scroll-up}). -@item C-y -@kindex 031 @kbd{C-y} (@code{vip-scroll-down-one}) -Scroll text of current window upward by one line (@code{vip-scroll-down-one}). -@item C-e -@kindex 005 @kbd{C-e} (@code{vip-scroll-up-one}) -Scroll text of current window downward by one line (@code{vip-scroll-up-one}). -@end table -@noindent -You can repeat these commands by giving a count. Thus, @kbd{2 @key{SPC}} -has the same effect as @kbd{@key{SPC} @key{SPC}}. - -The following commands reposition point in the window. - -@table @kbd -@item z H -@itemx z @key{RET} -@kindex 1723 @kbd{z H} (@code{vip-line-to-top}) -@kindex 1721 @kbd{z RET} (@code{vip-line-to-top}) -Put point on the top (@i{home}) line in the window. So the current line -becomes the top line in the window. Given a count @var{n}, point will be -placed in the @var{n}-th line from top (@code{vip-line-to-top}). -@item z M -@itemx z . -@kindex 1723 @kbd{z M} (@code{vip-line-to-middle}) -@kindex 1722 @kbd{z .} (@code{vip-line-to-middle}) -Put point on the @i{middle} line in the window. Given a count @var{n}, -point will be placed in the @var{n}-th line from the middle line -(@code{vip-line-to-middle}). -@item z L -@itemx z - -@kindex 1723 @kbd{z L} (@code{vip-line-to-bottom}) -@kindex 1722 @kbd{z -} (@code{vip-line-to-bottom}) -Put point on the @i{bottom} line in the window. Given a count @var{n}, -point will be placed in the @var{n}-th line from bottom -(@code{vip-line-to-bottom}). -@item C-l -Center point in window and redisplay screen (@code{recenter}). -@end table - -@node Mark Commands, Motion Commands, Viewing the Buffer, Vi Commands -@section Mark Commands - -The following commands are used to mark positions in the buffer. - -@table @kbd -@item m @var{ch} -@kindex 155 @kbd{m} (@code{vip-mark-point}) -Store current point in the register @var{ch}. @var{ch} must be a -lower-case @acronym{ASCII} letter. -@item m < -Set mark at the beginning of current buffer. -@item m > -Set mark at the end of current buffer. -@item m . -Set mark at point. -@item m , -Jump to mark (and pop mark off the mark ring). -@end table - -@cindex mark ring - -Emacs uses the @dfn{mark ring} to store marked positions. The commands -@kbd{m <}, @kbd{m >} and @kbd{m .}@: not only set mark but also add it as the -latest element of the mark ring (replacing the oldest one). By repeating -the command `@kbd{m ,}' you can visit older and older marked positions. You -will eventually be in a loop as the mark ring is a ring. - -@node Motion Commands, Searching and Replacing, Mark Commands, Vi Commands -@section Motion Commands - -Commands for moving around in the current buffer are collected here. These -commands are used as an `argument' for the delete, change and yank commands -to be described in the next section. - -@table @kbd -@item h -@kindex 150 @kbd{h} (@code{vip-backward-char}) -Move point backward by one character. Signal error if point is at the -beginning of buffer, but (unlike Vi) do not complain otherwise -(@code{vip-backward-char}). -@item l -@kindex 154 @kbd{l} (@code{vip-forward-char}) -Move point backward by one character. Signal error if point is at the -end of buffer, but (unlike Vi) do not complain otherwise -(@code{vip-forward-char}). -@item j -@kindex 152 @kbd{j} (@code{vip-next-line}) -Move point to the next line keeping the current column. If point is on the -last line of the buffer, a new line will be created and point will move to -that line (@code{vip-next-line}). -@item k -@kindex 153 @kbd{k} (@code{vip-previous-line}) -Move point to the previous line keeping the current column -(@code{vip-next-line}). -@item + -@kindex 053 @kbd{+} (@code{vip-next-line-at-bol}) -Move point to the next line at the first non-white character. If point is -on the last line of the buffer, a new line will be created and point will -move to the beginning of that line (@code{vip-next-line-at-bol}). -@item - -@kindex 055 @kbd{-} (@code{vip-previous-line-at-bol}) -Move point to the previous line at the first non-white character -(@code{vip-previous-line-at-bol}). -@end table -@noindent -If a count is given to these commands, the commands will be repeated that -many times. - -@table @kbd -@item 0 -@kindex 060 @kbd{0} (@code{vip-beginning-of-line}) -Move point to the beginning of line (@code{vip-beginning-of-line}). -@item ^ -@kindex 136 @kbd{^} (@code{vip-bol-and-skip-white}) -Move point to the first non-white character on the line -(@code{vip-bol-and-skip-white}). -@item $ -@kindex 044 @kbd{$} (@code{vip-goto-eol}) -Move point to the end of line (@code{vip-goto-eol}). -@item @var{n} | -@kindex 174 @kbd{|} (@code{vip-goto-col}) -Move point to the @var{n}-th column on the line (@code{vip-goto-col}). -@end table -@noindent -Except for the @kbd{|} command, these commands neglect a count. - -@cindex word - -@table @kbd -@item w -@kindex 167 @kbd{w} (@code{vip-forward-word}) -Move point forward to the beginning of the next word -(@code{vip-forward-word}). -@item W -@kindex 127 @kbd{W} (@code{vip-forward-Word}) -Move point forward to the beginning of the next word, where a @dfn{word} is -considered as a sequence of non-white characters (@code{vip-forward-Word}). -@item b -@kindex 142 @kbd{b} (@code{vip-backward-word}) -Move point backward to the beginning of a word (@code{vip-backward-word}). -@item B -@kindex 102 @kbd{B} (@code{vip-backward-Word}) -Move point backward to the beginning of a word, where a @i{word} is -considered as a sequence of non-white characters (@code{vip-forward-Word}). -@item e -@kindex 145 @kbd{e} (@code{vip-end-of-word}) -Move point forward to the end of a word (@code{vip-end-of-word}). -@item E -@kindex 105 @kbd{E} (@code{vip-end-of-Word}) -Move point forward to the end of a word, where a @i{word} is -considered as a sequence of non-white characters (@code{vip-end-of-Word}). -@end table -@noindent -@cindex syntax table -Here the meaning of the word `word' for the @kbd{w}, @kbd{b} and @kbd{e} -commands is determined by the @dfn{syntax table} effective in the current -buffer. Each major mode has its syntax mode, and therefore the meaning of -a word also changes as the major mode changes. See GNU Emacs Manual for -details of syntax table. - -@table @kbd -@item H -@kindex 110 @kbd{H} (@code{vip-window-top}) -Move point to the beginning of the @i{home} (top) line of the window. -Given a count @var{n}, go to the @var{n}-th line from top -(@code{vip-window-top}). -@item M -@kindex 115 @kbd{M} (@code{vip-window-middle}) -Move point to the beginning of the @i{middle} line of the window. Given -a count @var{n}, go to the @var{n}-th line from the middle line -(@code{vip-window-middle}). -@item L -@kindex 114 @kbd{L} (@code{vip-window-bottom}) -Move point to the beginning of the @i{lowest} (bottom) line of the -window. Given count, go to the @var{n}-th line from bottom -(@code{vip-window-bottom}). -@end table -@noindent -These commands can be used to go to the desired line visible on the screen. - -@table @kbd -@item ( -@kindex 050 @kbd{(} (@code{vip-backward-sentence}) -Move point backward to the beginning of the sentence -(@code{vip-backward-sentence}). -@item ) -@kindex 051 @kbd{)} (@code{vip-forward-sentence}) -Move point forward to the end of the sentence -(@code{vip-forward-sentence}). -@item @{ -@kindex 173 @kbd{@{} (@code{vip-backward-paragraph}) -Move point backward to the beginning of the paragraph -(@code{vip-backward-paragraph}). -@item @} -@kindex 175 @kbd{@}} (@code{vip-forward-paragraph}) -Move point forward to the end of the paragraph -(@code{vip-forward-paragraph}). -@end table -@noindent -A count repeats the effect for these commands. - -@table @kbd -@item G -@kindex 107 @kbd{G} (@code{vip-goto-line}) -Given a count @var{n}, move point to the @var{n}-th line in the buffer on -the first non-white character. Without a count, go to the end of the buffer -(@code{vip-goto-line}). -@item ` ` -@kindex 140 @kbd{`} (@code{vip-goto-mark}) -Exchange point and mark (@code{vip-goto-mark}). -@item ` @var{ch} -Move point to the position stored in the register @var{ch}. @var{ch} must -be a lower-case letter. -@item ' ' -@kindex 047 @kbd{'} (@code{vip-goto-mark-and-skip-white}) -Exchange point and mark, and then move point to the first non-white -character on the line (@code{vip-goto-mark-and-skip-white}). -@item ' @var{ch} -Move point to the position stored in the register @var{ch} and skip to the -first non-white character on the line. @var{ch} must be a lower-case letter. -@item % -@kindex 045 @kbd{%} (@code{vip-paren-match}) -Move point to the matching parenthesis if point is looking at @kbd{(}, -@kbd{)}, @kbd{@{}, @kbd{@}}, @kbd{[} or @kbd{]} -@*(@code{vip-paren-match}). -@end table -@noindent -The command @kbd{G} mark point before move, so that you can return to the -original point by @kbd{` `}. The original point will also be stored in -the mark ring. - -The following commands are useful for moving points on the line. A count -will repeat the effect. - -@table @kbd -@item f @var{ch} -@kindex 146 @kbd{f} (@code{vip-find-char-forward}) -Move point forward to the character @var{ch} on the line. Signal error if -@var{ch} could not be found (@code{vip-find-char-forward}). -@item F @var{ch} -@kindex 106 @kbd{F} (@code{vip-find-char-backward}) -Move point backward to the character @var{ch} on the line. Signal error if -@var{ch} could not be found (@code{vip-find-char-backward}). -@item t @var{ch} -@kindex 164 @kbd{t} (@code{vip-goto-char-forward}) -Move point forward upto the character @var{ch} on the line. Signal error if -@var{ch} could not be found (@code{vip-goto-char-forward}). -@item T @var{ch} -@kindex 124 @kbd{T} (@code{vip-goto-char-backward}) -Move point backward upto the character @var{ch} on the line. Signal error if -@var{ch} could not be found (@code{vip-goto-char-backward}). -@item ; -@kindex 073 @kbd{;} (@code{vip-repeat-find}) -Repeat previous @kbd{f}, @kbd{t}, @kbd{F} or @kbd{T} command -(@code{vip-repeat-find}). -@item , -@kindex 054 @kbd{,} (@code{vip-repeat-find-opposite}) -Repeat previous @kbd{f}, @kbd{t}, @kbd{F} or @kbd{T} command, in the -opposite direction (@code{vip-repeat-find-opposite}). -@end table - -@node Searching and Replacing, Modifying Commands, Motion Commands, Vi Commands -@section Searching and Replacing - -Following commands are available for searching and replacing. - -@cindex regular expression (search) - -@table @kbd -@item / @var{string} @key{RET} -@kindex 057 @kbd{/} (@code{vip-search-forward}) -Search the first occurrence of the string @var{string} forward starting -from point. Given a count @var{n}, the @var{n}-th occurrence of -@var{string} will be searched. If the variable @code{vip-re-search} has value -@code{t} then @dfn{regular expression} search is done and the string -matching the regular expression @var{string} is found. If you give an -empty string as @var{string} then the search mode will change from vanilla -search to regular expression search and vice versa -(@code{vip-search-forward}). -@item ? @var{string} @key{RET} -@kindex 077 @kbd{?} (@code{vip-search-backward}) -Same as @kbd{/}, except that search is done backward -(@code{vip-search-backward}). -@item n -@kindex 156 @kbd{n} (@code{vip-search-next}) -Search the previous search pattern in the same direction as before -(@code{vip-search-next}). -@item N -@kindex 116 @kbd{N} (@code{vip-search-Next}) -Search the previous search pattern in the opposite direction -(@code{vip-search-Next}). -@item C-s -@kindex 023 @kbd{C-s} (@code{isearch-forward}) -Search forward incrementally. See GNU Emacs Manual for details -(@code{isearch-forward}). -@item C-r -@kindex 022 @kbd{C-r} (@code{isearch-backward}) -Search backward incrementally (@code{isearch-backward}). -@cindex vanilla (replacement) -@cindex regular expression (replacement) -@item R @var{string} RET @var{newstring} -@kindex 122 @kbd{R} (@code{vip-replace-string}) -There are two modes of replacement, @dfn{vanilla} and @dfn{regular expression}. -If the mode is @i{vanilla} you will get a prompt @samp{Replace string:}, -and if the mode is @i{regular expression} you will ge a prompt -@samp{Replace regexp:}. The mode is initially @i{vanilla}, but you can -toggle these modes by giving a null string as @var{string}. If the mode is -vanilla, this command replaces every occurrence of @var{string} with -@var{newstring}. If the mode is regular expression, @var{string} is -treated as a regular expression and every string matching the regular -expression is replaced with @var{newstring} (@code{vip-replace-string}). -@item Q @var{string} RET @var{newstring} -@kindex 121 @kbd{Q} (@code{vip-query-replace}) -Same as @kbd{R} except that you will be asked form confirmation before each -replacement -@*(@code{vip-query-replace}). -@item r @var{ch} -@kindex 162 @kbd{r} (@code{vip-replace-char}) -Replace the character point is looking at by the character @var{ch}. Give -count, replace that many characters by @var{ch} (@code{vip-replace-char}). -@end table -@noindent -The commands @kbd{/} and @kbd{?} mark point before move, so that you can -return to the original point by @w{@kbd{` `}}. - -@node Modifying Commands, Delete Commands, Searching and Replacing, Vi Commands -@section Modifying Commands - -In this section, commands for modifying the content of a buffer are -described. These commands affect the region determined by a motion command -which is given to the commands as their argument. - -@cindex point commands -@cindex line commands - -We classify motion commands into @dfn{point commands} and -@dfn{line commands}. The point commands are as follows: -@example -@kbd{h}, @kbd{l}, @kbd{0}, @kbd{^}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, @kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, @kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,} -@end example -@noindent -The line commands are as follows: -@example -@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, @kbd{@}}, @kbd{G}, @kbd{'} -@end example -@noindent -@cindex expanding (region) -If a point command is given as an argument to a modifying command, the -region determined by the point command will be affected by the modifying -command. On the other hand, if a line command is given as an argument to a -modifying command, the region determined by the line command will be -enlarged so that it will become the smallest region properly containing the -region and consisting of whole lines (we call this process @dfn{expanding -the region}), and then the enlarged region will be affected by the modifying -command. - -@menu -* Delete Commands:: Commands for deleting text. -* Yank Commands:: Commands for yanking text in Vi's sense. -* Put Back Commands:: Commands for putting back deleted/yanked text. -* Change Commands:: Commands for changing text. -* Repeating and Undoing Modifications:: -@end menu -@node Delete Commands, Yank Commands, Modifying Commands, Modifying Commands -@subsection Delete Commands - -@table @kbd -@item d @var{motion-command} -@kindex 1440 @kbd{d} (@code{vip-command-argument}) -Delete the region determined by the motion command @var{motion-command}. -@end table -@noindent -For example, @kbd{d $} will delete the region between point and end of -current line since @kbd{$} is a point command that moves point to end of line. -@kbd{d G} will delete the region between the beginning of current line and -end of the buffer, since @kbd{G} is a line command. A count given to the -command above will become the count for the associated motion command. -Thus, @kbd{3 d w} will delete three words. - -@kindex 042 @kbd{"} (@code{vip-command-argument}) -It is also possible to save the deleted text into a register you specify. -For example, you can say @kbd{" t 3 d w} to delete three words and save it -to register @kbd{t}. The name of a register is a lower-case letter between -@kbd{a} and @kbd{z}. If you give an upper-case letter as an argument to -a delete command, then the deleted text will be appended to the content of -the register having the corresponding lower-case letter as its name. So, -@kbd{" T d w} will delete a word and append it to register @kbd{t}. Other -modifying commands also accept a register name as their argument, and we -will not repeat similar explanations. - -We have more delete commands as below. - -@table @kbd -@item d d -@kindex 1442 @kbd{d d} -Delete a line. Given a count @var{n}, delete @var{n} lines. -@item d r -@kindex 1442 @kbd{d r} -Delete current region. -@item d R -@kindex 1441 @kbd{d R} -Expand current region and delete it. -@item D -@kindex 104 @kbd{D} (@code{vip-kill-line}) -Delete to the end of a line (@code{vip-kill-line}). -@item x -@kindex 170 @kbd{x} (@code{vip-delete-char}) -Delete a character after point. Given @var{n}, delete @var{n} characters -(@code{vip-delete-char}). -@item @key{DEL} -@kindex 177 @kbd{DEL} (@code{vip-delete-backward-char}) -Delete a character before point. Given @var{n}, delete @var{n} characters -(@code{vip-delete-backward-char}). -@end table - -@node Yank Commands, Put Back Commands, Delete Commands, Modifying Commands -@subsection Yank Commands - -@cindex yank - -Yank commands @dfn{yank} a text of buffer into a (usually anonymous) register. -Here the word `yank' is used in Vi's sense. Thus yank commands do not -alter the content of the buffer, and useful only in combination with -commands that put back the yanked text into the buffer. - -@table @kbd -@item y @var{motion-command} -@kindex 1710 @kbd{y} (@code{vip-command-argument}) -Yank the region determined by the motion command @var{motion-command}. -@end table -@noindent -For example, @kbd{y $} will yank the text between point and the end of line -into an anonymous register, while @kbd{"c y $} will yank the same text into -register @kbd{c}. - -Use the following command to yank consecutive lines of text. - -@table @kbd -@item y y -@itemx Y -@kindex 131 @kbd{Y} (@code{vip-yank-line}) -@kindex 1712 @kbd{y y} (@code{vip-yank-line}) -Yank a line. Given @var{n}, yank @var{n} lines (@code{vip-yank-line}). -@item y r -@kindex 1712 @kbd{y r} -Yank current region. -@item y R -@kindex 1711 @kbd{y R} -Expand current region and yank it. -@end table - -@node Put Back Commands, Change Commands, Yank Commands, Modifying Commands -@subsection Put Back Commands -Deleted or yanked texts can be put back into the buffer by the command -below. - -@table @kbd -@item p -@kindex 160 @kbd{p} (@code{vip-put-back}) -Insert, after the character point is looking at, most recently -deleted/yanked text from anonymous register. Given a register name -argument, the content of the named register will be put back. Given a -count, the command will be repeated that many times. This command also -checks if the text to put back ends with a new line character, and if so -the text will be put below the current line (@code{vip-put-back}). -@item P -@kindex 120 @kbd{P} (@code{vip-Put-back}) -Insert at point most recently deleted/yanked text from anonymous register. -Given a register name argument, the content of the named register will -be put back. Given a count, the command will be repeated that many times. -This command also checks if the text to put back ends with a new line -character, and if so the text will be put above the current line rather -than at point (@code{vip-Put-back}). -@end table -@noindent -@cindex number register -Thus, @kbd{" c p} will put back the content of the register @kbd{c} into the -buffer. It is also possible to specify @dfn{number register} which is a -numeral between @kbd{1} and @kbd{9}. If the number register @var{n} is -specified, @var{n}-th previously deleted/yanked text will be put back. It -is an error to specify a number register for the delete/yank commands. - -@node Change Commands, Repeating and Undoing Modifications, Put Back Commands, Modifying Commands -@subsection Change Commands - -Most commonly used change command takes the following form. - -@table @kbd -@item c @var{motion-command} -@kindex 1430 @kbd{c} (@code{vip-command-argument}) -Replace the content of the region determined by the motion command -@var{motion-command} by the text you type. If the motion command is a -point command then you will type the text into minibuffer, and if the -motion command is a line command then the region will be deleted first and -you can insert the text in @var{insert mode}. -@end table -@noindent -For example, if point is at the beginning of a word @samp{foo} and you -wish to change it to @samp{bar}, you can type @kbd{c w}. Then, as @kbd{w} -is a point command, you will get the prompt @samp{foo =>} in the -minibuffer, for which you can type @kbd{b a r @key{RET}} to complete the change -command.@refill - -@table @kbd -@item c c -@kindex 1432 @kbd{c c} -Change a line. Given a count, that many lines are changed. -@item c r -@kindex 1432 @kbd{c r} -Change current region. -@item c R -@kindex 1431 @kbd{c R} -Expand current region and change it. -@end table - -@node Repeating and Undoing Modifications, Other Vi Commands, Change Commands, Modifying Commands -@subsection Repeating and Undoing Modifications - -VIP records the previous modifying command, so that it is easy to repeat -it. It is also very easy to undo changes made by modifying commands. - -@table @kbd -@item u -@kindex 165 @kbd{u} (@code{vip-undo}) -Undo the last change. You can undo more by repeating undo by the repeat -command @samp{.}. For example, you can undo 5 previous changes by typing -@samp{u....}. If you type @samp{uu}, then the second @samp{u} undoes the -first undo command (@code{vip-undo}). -@item . -@kindex 056 @kbd{.} (@code{vip-repeat}) -Repeat the last modifying command. Given count @var{n} it becomes the new -count for the repeated command. Otherwise, the count for the last -modifying command is used again (@code{vip-repeat}). -@end table - -@node Other Vi Commands, Commands in Insert Mode, Repeating and Undoing Modifications, Vi Commands -@section Other Vi Commands - -Miscellaneous Vi commands are collected here. - -@table @kbd -@item Z Z -@kindex 132 @kbd{Z Z} (@code{save-buffers-kill-emacs}) -Exit Emacs. If modified buffers exist, you will be asked whether you wish -to save them or not (@code{save-buffers-kill-emacs}). -@item !@: @var{motion-command} @var{format-command} -@itemx @var{n} !@: !@: @var{format-command} -@kindex 041 @kbd{!} (@code{vip-command-argument}) -The region determined by the motion command @var{motion-command} will be -given to the shell command @var{format-command} and the region will be -replaced by its output. If a count is given, it will be passed to -@var{motion-command}. For example, @samp{3!Gsort} will sort the region -between point and the 3rd line. If @kbd{!} is used instead of -@var{motion-command} then @var{n} lines will be processed by -@var{format-command} (@code{vip-command-argument}). -@item J -@kindex 112 @kbd{J} (@code{vip-join-lines}) -Join two lines. Given count, join that many lines. A space will be -inserted at each junction (@code{vip-join-lines}). -@item < @var{motion-command} -@itemx @var{n} < < -@kindex 074 @kbd{<} (@code{vip-command-argument}) -Shift region determined by the motion command @var{motion-command} to -left by @var{shift-width} (default is 8). If @kbd{<} is used instead of -@var{motion-command} then shift @var{n} lines -@*(@code{vip-command-argument}). -@item > @var{motion-command} -@itemx @var{n} > > -@kindex 076 @kbd{>} (@code{vip-command-argument}) -Shift region determined by the motion command @var{motion-command} to -right by @var{shift-width} (default is 8). If @kbd{<} is used instead of -@var{motion-command} then shift @var{n} lines -@*(@code{vip-command-argument}). -@item = @var{motion-command} -@kindex 075 @kbd{=} (@code{vip-command-argument}) -Indent region determined by the motion command @var{motion-command}. If -@kbd{=} is used instead of @var{motion-command} then indent @var{n} lines -(@code{vip-command-argument}). -@item * -@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) -Call last remembered keyboard macro. -@item # -A new vi operator. @xref{New Commands}, for more details. -@end table - -The following keys are reserved for future extensions, and currently -assigned to a function that just beeps (@code{vip-nil}). - -@kindex 046 @kbd{&} (@code{vip-nil}) -@kindex 100 @kbd{@@} (@code{vip-nil}) -@kindex 125 @kbd{U} (@code{vip-nil}) -@kindex 133 @kbd{[} (@code{vip-nil}) -@kindex 135 @kbd{]} (@code{vip-nil}) -@kindex 137 @kbd{_} (@code{vip-nil}) -@kindex 161 @kbd{q} (@code{vip-nil}) -@kindex 176 @kbd{~} (@code{vip-nil}) - -@example -&, @@, U, [, ], _, q, ~ -@end example - -VIP uses a special local keymap to interpret key strokes you enter in vi -mode. The following keys are bound to @var{nil} in the keymap. Therefore, -these keys are interpreted by the global keymap of Emacs. We give below a -short description of the functions bound to these keys in the global -keymap. See GNU Emacs Manual for details. - -@table @kbd -@item C-@@ -@kindex 000 @kbd{C-@@} (@code{set-mark-command}) -Set mark and push previous mark on mark ring (@code{set-mark-command}). -@item TAB -@kindex 011 TAB (@code{indent-for-tab-command}) -Indent line for current major mode (@code{indent-for-tab-command}). -@item C-j -@kindex 012 @kbd{C-j} (@code{newline-and-indent}) -Insert a newline, then indent according to mode (@code{newline-and-indent}). -@item C-k -@kindex 013 @kbd{C-k} (@code{kill-line}) -Kill the rest of the current line; before a newline, kill the newline. -With a numeric argument, kill that many lines from point. Negative arguments -kill lines backward (@code{kill-line}). -@item C-l -@kindex 014 @kbd{C-l} (@code{recenter}) -Clear the screen and reprint everything (@code{recenter}). -@item @var{n} C-p -@kindex 020 @kbd{C-p} (@code{previous-line}) -Move cursor vertically up @var{n} lines (@code{previous-line}). -@item C-q -@kindex 021 @kbd{C-q} (@code{quoted-insert}) -Read next input character and insert it. Useful for inserting control -characters -@*(@code{quoted-insert}). -@item C-r -@kindex 022 @kbd{C-r} (@code{isearch-backward}) -Search backward incrementally (@code{isearch-backward}). -@item C-s -@kindex 023 @kbd{C-s} (@code{isearch-forward}) -Search forward incrementally (@code{isearch-forward}). -@item @var{n} C-t -@kindex 024 @kbd{C-t} (@code{transpose-chars}) -Interchange characters around point, moving forward one character. With -count @var{n}, take character before point and drag it forward past @var{n} -other characters. If no argument and at end of line, the previous two -characters are exchanged (@code{transpose-chars}). -@item @var{n} C-v -@kindex 026 @kbd{C-v} (@code{scroll-up}) -Scroll text upward @var{n} lines. If @var{n} is not given, scroll near -full screen (@code{scroll-up}). -@item C-w -@kindex 027 @kbd{C-w} (@code{kill-region}) -Kill between point and mark. The text is save in the kill ring. The -command @kbd{P} or @kbd{p} can retrieve it from kill ring -(@code{kill-region}). -@end table - -@node Commands in Insert Mode, Ex Commands, Other Vi Commands, Vi Commands -@section Insert Mode - -You can enter insert mode by one of the following commands. In addition to -these, you will enter insert mode if you give a change command with a line -command as the motion command. Insert commands are also modifying commands -and you can repeat them by the repeat command @kbd{.} (@code{vip-repeat}). - -@table @kbd -@item i -@kindex 151 @kbd{i} (@code{vip-insert}) -Enter insert mode at point (@code{vip-insert}). -@item I -@kindex 111 @kbd{I} (@code{vip-Insert}) -Enter insert mode at the first non white character on the line -(@code{vip-Insert}). -@item a -@kindex 141 @kbd{a} (@code{vip-append}) -Move point forward by one character and then enter insert mode -(@code{vip-append}). -@item A -@kindex 101 @kbd{A} (@code{vip-Append}) -Enter insert mode at end of line (@code{vip-Append}). -@item o -@kindex 157 @kbd{o} (@code{vip-open-line}) -Open a new line below the current line and enter insert mode -(@code{vip-open-line}). -@item O -@kindex 117 @kbd{O} (@code{vip-Open-line}) -Open a new line above the current line and enter insert mode -(@code{vip-Open-line}). -@item C-o -@kindex 017 @kbd{C-o} (@code{vip-open-line-at-point}) -Insert a newline and leave point before it, and then enter insert mode -@*(@code{vip-open-line-at-point}). -@end table - -Insert mode is almost like emacs mode. Only the following 4 keys behave -differently from emacs mode. - -@table @kbd -@item @key{ESC} -@kindex 033 @kbd{ESC} (@code{vip-change-mode-to-vi}) (insert mode) -This key will take you back to vi mode (@code{vip-change-mode-to-vi}). -@item C-h -@kindex 010 @kbd{C-h} (@code{delete-backward-char}) (insert mode) -Delete previous character (@code{delete-backward-char}). -@item C-w -@kindex 027 @kbd{C-w} (@code{vip-delete-backward-word}) (insert mode) -Delete previous word (@code{vip-delete-backward-word}). -@item C-z -@kindex 032 @kbd{C-z} (@code{vip-ESC}) (insert mode) -This key simulates @key{ESC} key in emacs mode. For instance, typing -@kbd{C-z x} in insert mode is the same as typing @kbd{ESC x} in emacs mode -(@code{vip-ESC}). -@end table -@noindent -You can also bind @kbd{C-h} to @code{help-command} if you like. -(@xref{Customizing Key Bindings}, for details.) Binding @kbd{C-h} to -@code{help-command} has the effect of making the meaning of @kbd{C-h} -uniform among emacs, vi and insert modes. - -When you enter insert mode, VIP records point as the start point of -insertion, and when you leave insert mode the region between point and -start point is saved for later use by repeat command etc. Therefore, repeat -command will not really repeat insertion if you move point by emacs -commands while in insert mode. - -@node Ex Commands, Ex Command Reference, Commands in Insert Mode, Top -@chapter Ex Commands - -@kindex 072 @kbd{:} (@code{vip-ex}) - -In vi mode, you can execute an Ex command @var{ex-command} by typing: -@example -@kbd{:@: @var{ex-command} @key{RET}} -@end example -Every Ex command follows the following pattern: -@example -@var{address command} @kbd{!}@: @var{parameters count flags} -@end example -@noindent -@cindex address -where all parts are optional. For the syntax of @dfn{address}, the reader -is referred to the reference manual of Ex. - -@cindex magic -@cindex regular expression - -In the current version of VIP, searching by Ex commands is always -@dfn{magic}. That is, search patterns are always treated as @dfn{regular -expressions}. For example, a typical forward search would be invoked by -@kbd{:/@var{pat}/}. If you wish to include @samp{/} as part of -@var{pat} you must preceded it by @samp{\}. VIP strips off these @kbd{\}'s -before @kbd{/} and the resulting @var{pat} becomes the actual search -pattern. Emacs provides a different and richer class or regular -expressions than Vi/Ex, and VIP uses Emacs's regular expressions. See GNU -Emacs Manual for details of regular expressions. - -Several Ex commands can be entered in a line by separating them by a pipe -character @samp{|}. - -@menu -* Ex Command Reference:: Explain all the Ex commands available in VIP. -@end menu -@node Ex Command Reference, Customization, Ex Commands, Ex Commands -@section Ex Command Reference -In this section we briefly explain all the Ex commands supported by VIP. -Most Ex commands expect @var{address} as their argument, and they use -default addresses if they are not explicitly given. In the following, such -default addresses will be shown in parentheses. - -Most command names can and preferably be given in abbreviated forms. In -the following, optional parts of command names will be enclosed in -brackets. For example, @samp{co[py]} will mean that copy command can be -give as @samp{co} or @samp{cop} or @samp{copy}. - -If @var{command} is empty, point will move to the beginning of the line -specified by the @var{address}. If @var{address} is also empty, point will -move to the beginning of the current line. - -@cindex flag - -Some commands accept @dfn{flags} which are one of @kbd{p}, @kbd{l} and -@kbd{#}. If @var{flags} are given, the text affected by the commands will -be displayed on a temporary window, and you will be asked to hit return to -continue. In this way, you can see the text affected by the commands -before the commands will be executed. If you hit @kbd{C-g} instead of -@key{RET} then the commands will be aborted. Note that the meaning of -@var{flags} is different in VIP from that in Vi/Ex. - -@table @kbd -@item (.,.@:) co[py] @var{addr} @var{flags} -@itemx (.,.@:) t @var{addr} @var{flags} -Place a copy of specified lines after @var{addr}. If @var{addr} is -@kbd{0}, it will be placed before the first line. -@item (.,.@:) d[elete] @var{register} @var{count} @var{flags} -Delete specified lines. Text will be saved in a named @var{register} if a -lower-case letter is given, and appended to a register if a capital letter is -given. -@item e[dit] !@: +@var{addr} @var{file} -@itemx e[x] !@: +@var{addr} @var{file} -@itemx vi[sual] !@: +@var{addr} @var{file} -Edit a new file @var{file} in the current window. The command will abort -if current buffer is modified, which you can override by giving @kbd{!}. -If @kbd{+}@var{addr} is given, @var{addr} becomes the current line. -@item file -Give information about the current file. -@item (1,$) g[lobal] !@: /@var{pat}/ @var{cmds} -@itemx (1,$) v /@var{pat}/ @var{cmds} -Among specified lines first mark each line which matches the regular -expression @var{pat}, and then execute @var{cmds} on each marked line. -If @kbd{!}@: is given, @var{cmds} will be executed on each line not matching -@var{pat}. @kbd{v} is same as @kbd{g!}. -@item (.,.+1) j[oin] !@: @var{count} @var{flags} -Join specified lines into a line. Without @kbd{!}, a space character will -be inserted at each junction. -@item (.@:) k @var{ch} -@itemx (.@:) mar[k] @var{ch} -Mark specified line by a lower-case character @var{ch}. Then the -addressing form @kbd{'}@var{ch} will refer to this line. No white space is -required between @kbd{k} and @var{ch}. A white space is necessary between -@kbd{mark} and @var{ch}, however. -@item map @var{ch} @var{rhs} -Define a macro for vi mode. After this command, the character @var{ch} -will be expanded to @var{rhs} in vi mode. -@item (.,.@:) m[ove] @var{addr} -Move specified lines after @var{addr}. -@item (.@:) pu[t] @var{register} -Put back previously deleted or yanked text. If @var{register} is given, -the text saved in the register will be put back; otherwise, last deleted or -yanked text will be put back. -@item q[uit] ! -Quit from Emacs. If modified buffers with associated files exist, you will -be asked whether you wish to save each of them. At this point, you may -choose not to quit, by hitting @kbd{C-g}. If @kbd{!}@: is given, exit from -Emacs without saving modified buffers. -@item (.@:) r[ead] @var{file} -Read in the content of the file @var{file} after the specified line. -@item (.@:) r[ead] !@: @var{command} -Read in the output of the shell command @var{command} after the specified -line. -@item se[t] -Set a variable's value. @xref{Customizing Constants}, for the list of variables -you can set. -@item sh[ell] -Run a subshell in a window. -@item (.,.@:) s[ubstitute] /@var{pat}/@var{repl}/ @var{options} @var{count} @var{flags} -@itemx (.,.@:) & @var{options} @var{count} @var{flags} -On each specified line, the first occurrence of string matching regular -expression @var{pat} is replaced by replacement pattern @var{repl}. Option -characters are @kbd{g} and @kbd{c}. If global option character @kbd{g} -appears as part of @var{options}, all occurrences are substituted. If -confirm option character @kbd{c} appears, you will be asked to give -confirmation before each substitution. If @kbd{/@var{pat}/@var{repl}/} is -missing, the last substitution is repeated. -@item st[op] -Suspend Emacs. -@item ta[g] @var{tag} -@cindex tag -@cindex selected tags table -Find first definition of @var{tag}. If no @var{tag} is given, previously -given @var{tag} is used and next alternate definition is find. By default, -the file @file{TAGS} in the current directory becomes the @dfn{selected tags -table}. You can select another tags table by @kbd{set} command. -@xref{Customizing Constants}, for details. -@item und[o] -Undo the last change. -@item unm[ap] @var{ch} -The macro expansion associated with @var{ch} is removed. -@item ve[rsion] -Tell the version number of VIP. -@item (1,$) w[rite] !@: @var{file} -Write out specified lines into file @var{file}. If no @var{file} is given, -text will be written to the file associated to the current buffer. Unless -@kbd{!}@: is given, if @var{file} is different from the file associated to -the current buffer and if the file @var{file} exists, the command will not -be executed. Unlike Ex, @var{file} becomes the file associated to the -current buffer. -@item (1,$) w[rite]>> @var{file} -Write out specified lines at the end of file @var{file}. @var{file} -becomes the file associated to the current buffer. -@item (1,$) wq !@: @var{file} -Same as @kbd{write} and then @kbd{quit}. If @kbd{!}@: is given, same as -@kbd{write !}@: then @kbd{quit}. -@item (.,.) y[ank] @var{register} @var{count} -Save specified lines into register @var{register}. If no register is -specified, text will be saved in an anonymous register. -@item @var{addr} !@: @var{command} -Execute shell command @var{command}. The output will be shown in a new -window. If @var{addr} is given, specified lines will be used as standard -input to @var{command}. -@item ($) = -Print the line number of the addressed line. -@item (.,.) > @var{count} @var{flags} -Shift specified lines to the right. The variable @code{vip-shift-width} -(default value is 8) determines the amount of shift. -@item (.,.) < @var{count} @var{flags} -Shift specified lines to the left. The variable @code{vip-shift-width} -(default value is 8) determines the amount of shift. -@item (.,.@:) ~ @var{options} @var{count} @var{flags} -Repeat the previous @kbd{substitute} command using previous search pattern -as @var{pat} for matching. -@end table - -The following Ex commands are available in Vi, but not implemented in VIP. -@example -@kbd{abbreviate}, @kbd{list}, @kbd{next}, @kbd{print}, @kbd{preserve}, @kbd{recover}, @kbd{rewind}, @kbd{source}, -@kbd{unabbreviate}, @kbd{xit}, @kbd{z} -@end example - -@node Customization, Customizing Constants, Ex Command Reference, Top -@chapter Customization - -If you have a file called @file{.vip} in your home directory, then it -will also be loaded when VIP is loaded. This file is thus useful for -customizing VIP. - -@menu -* Customizing Constants:: How to change values of constants. -* Customizing Key Bindings:: How to change key bindings. -@end menu - -@node Customizing Constants, Customizing Key Bindings, Customization, Customization -@section Customizing Constants -An easy way to customize VIP is to change the values of constants used -in VIP. Here is the list of the constants used in VIP and their default -values. - -@table @code -@item vip-shift-width 8 -The number of columns shifted by @kbd{>} and @kbd{<} command. -@item vip-re-replace nil -If @code{t} then do regexp replace, if @code{nil} then do string replace. -@item vip-search-wrap-around t -If @code{t}, search wraps around the buffer. -@item vip-re-search nil -If @code{t} then search is reg-exp search, if @code{nil} then vanilla -search. -@item vip-case-fold-search nil -If @code{t} search ignores cases. -@item vip-re-query-replace nil -If @code{t} then do reg-exp replace in query replace. -@item vip-open-with-indent nil -If @code{t} then indent to the previous current line when open a new line -by @kbd{o} or @kbd{O} command. -@item vip-tags-file-name "TAGS" -The name of the file used as the tags table. -@item vip-help-in-insert-mode nil -If @code{t} then @key{C-h} is bound to @code{help-command} in insert mode, -if @code{nil} then it sis bound to @code{delete-backward-char}. -@end table -@noindent -You can reset these constants in VIP by the Ex command @kbd{set}. Or you -can include a line like this in your @file{.vip} file: -@example -(setq vip-case-fold-search t) -@end example - -@node Customizing Key Bindings,, Customizing Constants, Customization -@section Customizing Key Bindings - -@cindex local keymap - -VIP uses @code{vip-command-mode-map} as the @dfn{local keymap} for vi mode. -For example, in vi mode, @key{SPC} is bound to the function -@code{vip-scroll}. But, if you wish to make @key{SPC} and some other keys - behave like Vi, you can include the following lines in your @file{.vip} -file. - -@example -(define-key vip-command-mode-map "\C-g" 'vip-info-on-file) -(define-key vip-command-mode-map "\C-h" 'vip-backward-char) -(define-key vip-command-mode-map "\C-m" 'vip-next-line-at-bol) -(define-key vip-command-mode-map " " 'vip-forward-char) -(define-key vip-command-mode-map "g" 'vip-keyboard-quit) -(define-key vip-command-mode-map "s" 'vip-substitute) -(define-key vip-command-mode-map "C" 'vip-change-to-eol) -(define-key vip-command-mode-map "R" 'vip-change-to-eol) -(define-key vip-command-mode-map "S" 'vip-substitute-line) -(define-key vip-command-mode-map "X" 'vip-delete-backward-char) -@end example - -@node GNU Free Documentation License,,, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@unnumbered Key Index - -@printindex ky - -@unnumbered Concept Index -@printindex cp - -@bye diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi deleted file mode 100644 index 94f7e53ce8c..00000000000 --- a/doc/misc/viper.texi +++ /dev/null @@ -1,4557 +0,0 @@ -% -*-texinfo-*- -\input texinfo - -@comment Using viper.info instead of viper in setfilename breaks DOS. -@comment @setfilename viper -@comment @setfilename viper.info -@setfilename ../../info/viper - -@copying -Copyright @copyright{} 1995-1997, 2001-2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* VIPER: (viper). A VI-emulation mode for Emacs. -@end direntry - -@finalout - -@titlepage -@title Viper Is a Package for Emacs Rebels -@subtitle a Vi emulator for Emacs -@subtitle November 2008, Viper Version 3.11.2 - -@author Michael Kifer (Viper) -@author Aamod Sane (VIP 4.4) -@author Masahiko Sato (VIP 3.5) - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Overview,, (DIR) - -@unnumbered Viper - -We believe that one or more of the following statements are adequate -descriptions of Viper: - -@example -Viper Is a Package for Emacs Rebels; -it is a VI Plan for Emacs Rescue -and/or a venomous VI PERil. -@end example - -Technically speaking, Viper is a Vi emulation package for Emacs. It -implements all Vi and Ex commands, occasionally improving on them and -adding many new features. It gives the user the best of both worlds: Vi -keystrokes for editing combined with the power of the Emacs environment. - -Viper emulates Vi at several levels, from the one that closely follows Vi -conventions to the one that departs from many of them. It has many -customizable options, which can be used to tailor Viper to the work habits -of various users. -This manual describes Viper, concentrating on the differences from Vi and -new features of Viper. - -Viper, formerly known as VIP-19, was written by Michael Kifer. It is based -on VIP version 3.5 by Masahiko Sato and VIP version 4.4 by Aamod Sane. -About 15% of the code still comes from those older packages. - -Viper is intended to be usable without reading this manual --- the defaults -are set to make Viper as close to Vi as possible. At startup, Viper will -try to set the most appropriate default environment for you, based on -your familiarity with Emacs. It will also tell you the basic GNU Emacs window -management commands to help you start immediately. - -Although this manual explains how to customize Viper, some basic -familiarity with Emacs Lisp is a plus. - -It is recommended that you read the Overview node. The other nodes may -be visited as needed. - -Comments and bug reports are welcome. -@code{kifer@@cs.stonybrook.edu} is the current address for Viper bug reports. -Please use the Ex command @kbd{:submitReport} for this purpose.@refill - -@insertcopying -@end ifnottex - -@menu -* Overview:: Read for a smoother start -* Improvements over Vi:: New features, Improvements -* Customization:: How to customize Viper -* Commands:: Vi and Ex Commands - -* Key Index:: Index of Vi and Ex Commands -* Function Index:: Index of Viper Functions -* Variable Index:: Index of Viper Variables -* Package Index:: Index of Packages Mentioned in this Document -* Concept Index:: Vi, Ex and Emacs concepts - -* Acknowledgments:: -* GNU Free Documentation License:: The license for this documentation. - -@end menu -@iftex -@unnumbered Introduction - -We believe that one or more of the following statements are adequate -descriptions of Viper: - -@example -Viper Is a Package for Emacs Rebels; -it is a VI Plan for Emacs Rescue -and/or a venomous VI PERil. -@end example - -Viper is a Vi emulation package for Emacs. Viper contains virtually all -of Vi and Ex functionality and much more. It gives you the best of both -worlds: Vi keystrokes for editing combined with the GNU Emacs -environment. Viper also fixes some common complaints with Vi commands. -This manual describes Viper, concentrating on the differences from Vi -and on the new features of Viper. - -Viper was written by Michael Kifer. It is based on VIP version 3.5 by -Masahiko Sato and VIP version 4.4 by Aamod Sane. About 15% of the code -still comes from those older packages. - -Viper is intended to be usable out of the box, without reading this manual ---- the defaults are set to make Viper as close to Vi as possible. At -startup, Viper will attempt to set the most appropriate default environment -for you, based on your familiarity with Emacs. It will also tell you the -basic GNU Emacs window management commands to help you start immediately. - -Although this manual explains how to customize Viper, some basic -familiarity with Emacs Lisp is a plus. - -It is recommended that you read the chapter Overview. The other chapters -will be useful for customization and advanced usage. - -You should also learn to use the Info on-line hypertext manual system that -comes with Emacs. This manual can be read as an Info file. Try the command -@kbd{@key{ESC} x info} with vanilla Emacs sometime. - -Comments and bug reports are welcome. -@code{kifer@@cs.stonybrook.edu} is the current address for Viper bug reports. -Please use the Ex command @kbd{:submitReport} for this purpose.@refill - -@end iftex - -@node Overview,Improvements over Vi,Top,Top -@chapter Overview of Viper - -Viper is a Vi emulation on top of Emacs. At the same time, Viper provides a -virtually unrestricted access to Emacs facilities. Perfect compatibility -with Vi is possible but not desirable. This chapter tells you about the -Emacs ideas that you should know about, how to use Viper within Emacs and -some incompatibilities. - -This manual is written with the assumption that you are an experienced Vi -user who wants to switch to Emacs while retaining the ability to edit files -Vi style. Incredible as it might seem, there are experienced Emacs users -who use Viper as a backdoor into the superior (as every Vi user already knows) -world of Vi! These users are well familiar with Emacs bindings and prefer them -in some cases, especially in the Vi Insert state. John Hawkins - has provided a set of customizations, which -enables additional Emacs bindings under Viper. These customizations can be -included in your @file{~/.viper} file and are found at the following URL: -@file{http://traeki.freeshell.org/files/viper-sample}. - -@menu -* Emacs Preliminaries:: Basic concepts in Emacs. -* Loading Viper:: Loading and Preliminary Configuration. -* States in Viper:: Viper has four states orthogonal to Emacs - modes. -* The Minibuffer:: Command line in Emacs. -* Multiple Files in Viper:: True multiple file handling. -* Unimplemented Features:: That are unlikely to be implemented. -@end menu - -@node Emacs Preliminaries, Loading Viper, Overview, Overview -@section Emacs Preliminaries - -@cindex buffer -@cindex point -@cindex mark -@cindex text -@cindex looking at -@cindex end (of buffer) -@cindex end (of line) -@cindex region - -Emacs can edit several files at once. A file in Emacs is placed in a -@dfn{buffer} that usually has the same name as the file. Buffers are also used -for other purposes, such as shell interfaces, directory editing, etc. -@xref{Dired,,Directory Editor,emacs,The -GNU Emacs Manual}, for an example.@refill - -A buffer has a distinguished position called the @dfn{point}. -A @dfn{point} is always between 2 characters, and is @dfn{looking at} -the right hand character. The cursor is positioned on the right hand -character. Thus, when the @dfn{point} is looking at the end-of-line, -the cursor is on the end-of-line character, i.e.@: beyond the last -character on the line. This is the default Emacs behavior.@refill - -The default settings of Viper try to mimic the behavior of Vi, preventing -the cursor from going beyond the last character on the line. By using -Emacs commands directly (such as those bound to arrow keys), it is possible -to get the cursor beyond the end-of-line. However, this won't (or -shouldn't) happen if you restrict yourself to standard Vi keys, unless you -modify the default editing style. @xref{Customization}.@refill - -In addition to the @dfn{point}, there is another distinguished buffer -position called the @dfn{mark}. @xref{Mark,,Mark,emacs,The GNU Emacs -manual}, for more info on the mark. The text between the @dfn{point} and -the @dfn{mark} is called the @dfn{region} of the buffer. For the Viper -user, this simply means that in addition to the Vi textmarkers a--z, there -is another marker called @dfn{mark}. This is similar to the unnamed Vi -marker used by the jump commands @kbd{``} and @kbd{''}, which move the -cursor to the position of the last absolute jump. Viper provides access to -the region in most text manipulation commands as @kbd{r} and @kbd{R} suffix -to commands that operate on text regions, e.g., @kbd{dr} to delete region, -etc. - -Furthermore, Viper lets Ex-style commands to work on the current region. -This is done by typing a digit argument before @kbd{:}. For instance, -typing @kbd{1:} will prompt you with something like @emph{:123,135}, -assuming that the current region starts at line 123 and ends at line -135. There is no need to type the line numbers, since Viper inserts them -automatically in front of the Ex command. - -@xref{Basics}, for more info.@refill - -@cindex window -@cindex mode line -@cindex buffer information -@cindex Minibuffer -@cindex command line -@cindex buffer (modified) - -Emacs divides the screen into tiled @dfn{windows}. You can see the -contents of a buffer through the window associated with the buffer. The -cursor of the screen is positioned on the character after @dfn{point}. -Every window has a @dfn{mode line} that displays information about the buffer. -You can change the format of the mode -line, but normally if you see @samp{**} at the beginning of a mode line it -means that the buffer is @dfn{modified}. If you write out the contents of -a buffer to a file, then the buffer will become not modified. Also if -you see @samp{%%} at the beginning of the mode line, it means that the file -associated with the buffer is write protected. The mode line will also -show the buffer name and current major and minor modes (see below). -A special buffer called @dfn{Minibuffer} is displayed as the last line -in a minibuffer window. The minibuffer window is used for command input -output. Viper uses minibuffer window for @kbd{/} and @kbd{:} -commands.@refill - -@cindex mode -@cindex keymap -@cindex local keymap -@cindex global keymap -@cindex major mode -@cindex minor mode - -An Emacs buffer can have a @dfn{major mode} that customizes Emacs for -editing text of a particular sort by changing the functionality of the keys. -Keys are defined using a @dfn{keymap} that records the bindings between -keystrokes and -functions. The @dfn{global keymap} is common to all the -buffers. Additionally, each buffer has its @dfn{local keymap} that determines the -@dfn{mode} of the buffer. If a function is bound to some key in the local -keymap then that function will be executed when you type the key. -If no function is bound to a key in the -local map, however, the function bound to the key in the global map -will be executed. @xref{Major Modes,Major Modes,Major Modes,emacs,The -GNU Emacs Manual}, for more information.@refill - -A buffer can also have a @dfn{minor mode}. Minor modes are options that -you can use or not. A buffer in @code{text-mode} can have -@code{auto-fill-mode} as minor mode, which can be turned off or on at -any time. In Emacs, a minor mode may have it own keymap, -which overrides the local keymap when the minor mode is turned on. For -more information, @pxref{Minor Modes,Minor Modes,Minor Modes,emacs,The -GNU Emacs Manual} @refill - -@cindex Viper as minor mode -@cindex Control keys -@cindex Meta key - -Viper is implemented as a collection of minor modes. Different minor modes -are involved when Viper emulates Vi command mode, Vi insert mode, etc. -You can also turn Viper on and off at any time while in Vi command mode. -@xref{States in Viper}, for -more information.@refill - -Emacs uses Control and Meta modifiers. These are denoted as C and M, -e.g.@: @kbd{^Z} as @kbd{C-z} and @kbd{Meta-x} as @kbd{M-x}. The Meta key is -usually located on each side of the Space bar; it is used in a manner -similar to the Control key, e.g., @kbd{M-x} means typing @kbd{x} while -holding the Meta key down. For keyboards that do not have a Meta key, -@key{ESC} is used as Meta. Thus @kbd{M-x} is typed as @kbd{@key{ESC} -x}. Viper uses @key{ESC} to switch from Insert state to Vi state. Therefore -Viper defines @kbd{C-\} as its Meta key in Vi state. @xref{Vi State}, for -more info.@refill - -Emacs is structured as a Lisp interpreter around a C core. Emacs keys -cause Lisp functions to be called. It is possible to call these -functions directly, by typing @kbd{M-x function-name}. - -@node Loading Viper, States in Viper, Emacs Preliminaries, Overview -@section Loading Viper - -The most common way to load it automatically is to include the following -lines (in the given order!): - -@lisp -(setq viper-mode t) -(require 'viper) -@end lisp - -@noindent -in your @file{~/.emacs} file. The @file{.emacs} file is placed in your -home directory and it is be executed every time you invoke Emacs. This is -the place where all general Emacs customization takes place. Beginning with -version 20.0, Emacsen have an interactive interface, which simplifies the -job of customization significantly. - -Viper also uses the file @file{~/.viper} for Viper-specific customization. -The location of Viper customization file can be changed by setting the -variable @code{viper-custom-file-name} in @file{.emacs} @emph{prior} to loading -Viper. - -The latest versions of Emacs have an interactive customization facility, -which allows you to (mostly) bypass the use of the @file{.emacs} and -@file{.viper} files. You can reach this customization -facility from within Viper's VI state by executing the Ex command -@kbd{:customize}. - -Once invoked, Viper will arrange to bring up Emacs buffers in Vi state -whenever this makes sense. -@xref{Packages that Change Keymaps}, to find out when forcing Vi command state -on a buffer may be counter-productive. - -Even if your @file{.emacs} file does not invoke Viper automatically, -you can still load Viper and enter the Vi command state by typing the -following from within Emacs: - -@lisp -M-x viper-mode -@end lisp - -When Emacs first comes up, if you have not specified a file on the -command line, it will show the @samp{*scratch*} buffer, in the -@samp{Lisp Interaction} mode. After you invoke Viper, you can start -editing files by using @kbd{:e}, @kbd{:vi}, or @kbd{v} commands. -(@xref{File and Buffer Handling}, for more information on @kbd{v} and other -new commands that, in many cases, are more convenient than @kbd{:e}, -@kbd{:vi}, and similar old-style Vi commands.)@refill - -Finally, if at some point you would want to de-Viperize your running -copy of Emacs after Viper has been loaded, the command @kbd{M-x -viper-go-away} will do it for you. The function @code{toggle-viper-mode} -toggles Viperization of Emacs on and off. - -@node States in Viper, The Minibuffer, Loading Viper,Overview -@section States in Viper - -@kindex @kbd{C-z} -@kindex @key{ESC} -@kindex @kbd{i} -@cindex Emacs state -@cindex Vi state -@cindex Insert state -@cindex Replace state -@cindex Ex commands -@findex @code{viper-go-away} -@findex @code{toggle-viper-mode} - -Viper has four states, Emacs, Vi, Insert, and Replace. - -@table @samp -@item Emacs state -This is the state plain vanilla Emacs is normally in. After you have loaded -Viper, @kbd{C-z} will normally take you to Vi command state. Another -@kbd{C-z} will take you back to Emacs state. This toggle key can be -changed, @pxref{Customization} You can also type @kbd{M-x viper-mode} to -change to Vi state.@refill - - -For users who chose to set their user level to 1 at Viper setup time, -switching to Emacs state is deliberately made harder in order to not -confuse the novice user. In this case, @kbd{C-z} will either iconify Emacs -(if Emacs runs as an application under X) or it will stop Emacs (if -Emacs runs on a dumb terminal or in an Xterm window). - -@item Vi state -This is the Vi command mode. Any of the Vi commands, such as @kbd{i, o, a}, -@dots{}, will take you to Insert state. All Vi commands may -be used in this mode. Most Ex commands can also be used. -For a full list of Ex commands supported by Viper, type -@kbd{:} and then @key{TAB}. To get help on any issue, including the Ex -commands, type @kbd{:help}. This will invoke Viper Info -(if it is installed). Then typing @kbd{i} will prompt you for a topic to -search in the index. Note: to search for Ex commands in the index, you -should start them with a @kbd{:}, e.g., @kbd{:WW}. - -In Viper, Ex commands can be made to work on the current Emacs region. -This is done by typing a digit argument before @kbd{:}. -For instance, typing @kbd{1:} will prompt you with something like -@emph{:123,135}, assuming that the current region starts at line 123 and -ends at line 135. There is no need to type the line numbers, since Viper -inserts them automatically in front of the Ex command. - -@item Insert state -Insert state is the Vi insertion mode. @key{ESC} will take you back to -Vi state. Insert state editing can be done, including auto-indentation. By -default, Viper disables Emacs key bindings in Insert state. - -@item Replace state -Commands like @kbd{cw} invoke the Replace state. When you cross the -boundary of a replacement region (usually designated via a @samp{$} sign), -it will automatically change to Insert state. You do not have to worry -about it. The key bindings remain practically the same as in Insert -state. If you type @key{ESC}, Viper will switch to Vi command mode, terminating the -replacement state.@refill -@end table - -@cindex mode line - -The modes are indicated on the @dfn{mode line} as , , , and , -so that the multiple modes do not confuse you. Most of your editing can be -done in Vi and Insert states. Viper will try to make all new buffers be in Vi -state, but sometimes they may come up in Emacs state. @kbd{C-z} -will take you to Vi state in such a case. In some major modes, like Dired, -Info, Gnus, etc., you should not switch to Vi state (and Viper will not -attempt to do so) because these modes are not intended for text editing and -many of the Vi keys have special meaning there. If you plan to read news, -browse directories, read mail, etc., from Emacs (which you should start -doing soon!), you should learn about the meaning of the various keys in -those special modes (typing @kbd{C-h m} in a buffer provides -help with key bindings for the major mode of that buffer). - -If you switch to Vi in Dired or similar modes---no harm is done. It is just -that the special key bindings provided by those modes will be temporarily -overshadowed by Viper's bindings. Switching back to Viper's Emacs state -will revive the environment provided by the current major mode. - -States in Viper are orthogonal to Emacs major modes, such as C mode or Dired -mode. You can turn Viper on and off for any Emacs state. When Viper is turned -on, Vi state can be used to move around. In Insert state, the bindings for -these modes can be accessed. For beginners (users at Viper levels 1 and 2), -these bindings are suppressed in Insert state, so that new users are not -confused by the Emacs states. Note that unless you allow Emacs bindings in -Insert state, you cannot do many interesting things, like language -sensitive editing. For the novice user (at Viper level 1), all major mode -bindings are turned off in Vi state as well. This includes the bindings for -key sequences that start with @kbd{C-c}, which practically means that all -major mode bindings are unsupported. @xref{Customization}, to find out how -to allow Emacs keys in Insert state. - -@menu -* Emacs State:: This is the state you should learn more about when - you get up to speed with Viper. -* Vi State:: Vi commands are executed in this state. -* Insert State:: You can enter text, and also can do sophisticated - editing if you know enough Emacs commands. -* Replace State:: Like Insert mode, but it is invoked via the - replacement commands, such as cw, C, R, etc. -@end menu - -@node Emacs State, Vi State, States in Viper, States in Viper -@subsection Emacs State - -@kindex @kbd{C-z} -@cindex Emacs state - - -You will be in this mode only by accident (hopefully). This is the state -Emacs is normally in (imagine!!). Now leave it as soon as possible by -typing @kbd{C-z}. Then you will be in Vi state (sigh of relief) :-). - -Emacs state is actually a Viperism to denote all the major and minor modes -(@pxref{Emacs Preliminaries}) other than Viper that Emacs can be in. Emacs -can have several modes, such as C mode for editing C programs, LaTeX mode -for editing LaTeX documents, Dired for directory editing, etc. These are -major modes, each with a different set of key-bindings. Viper states are -orthogonal to these Emacs major modes. The presence of these language -sensitive and other modes is a major win over Vi. @xref{Improvements over -Vi}, for more.@refill - -The bindings for these modes can be made available in the Viper Insert state -as well as in Emacs state. Unless you specify your user level as 1 (a -novice), all major mode key sequences that start with @kbd{C-x} and -@kbd{C-c} are also available in Vi state. This is important because major -modes designed for editing files, such as cc-mode or latex-mode, use key -sequences that begin with @kbd{C-x} and @kbd{C-c}. - -There is also a key that lets you temporarily escape to Vi command state -from the Insert state: typing @kbd{C-z} will let you execute a -single Vi command while staying in Viper's Insert state. - - -@node Vi State, Insert State, Emacs State, States in Viper -@subsection Vi State - -@cindex Vi state - -This is the Vi command mode. When Viper is in Vi state, you will see the sign - in the mode line. Most keys will work as in Vi. The notable -exceptions are: - -@table @kbd -@item C-x -@kindex @kbd{C-x} -@kbd{C-x} is used to invoke Emacs commands, mainly those that do window -management. @kbd{C-x 2} will split a window, @kbd{C-x 0} will close a -window. @kbd{C-x 1} will close all other windows. @kbd{C-xb} is used to -switch buffers in a window, and @kbd{C-xo} to move through windows. -These are about the only necessary keystrokes. -For the rest, see the GNU Emacs Manual. - -@item C-c -@kindex @kbd{C-c} -For user levels 2 and higher, this key serves as a prefix key for the key -sequences used by various major modes. For users at Viper level 1, @kbd{C-c} -simply beeps. - -@item C-g and C-] -@kindex @kbd{C-g} -@kindex @kbd{C-]} - -These are the Emacs @samp{quit} keys. -There will be cases where you will have to -use @kbd{C-g} to quit. Similarly, @kbd{C-]} is used to exit -@samp{Recursive Edits} in Emacs for which there is no comparable Vi -functionality and no key-binding. Recursive edits are indicated by -@samp{[]} brackets framing the modes on the mode line. -@xref{Recursive Edit,Recursive -Edit,Recursive Edit,emacs,The GNU Emacs Manual}. -At user level 1, @kbd{C-g} is bound to @code{viper-info-on-file} -function instead. -@refill -@item C-\ -@kindex @kbd{C-\} -@cindex Meta key - -Viper uses @key{ESC} as a switch between Insert and Vi states. Emacs uses -@key{ESC} for Meta. The Meta key is very important in Emacs since many -functions are accessible only via that key as @kbd{M-x function-name}. -Therefore, we need to simulate it somehow. In Viper's Vi, Insert, and -Replace states, the meta key is set to be @kbd{C-\}. Thus, to get -@kbd{M-x}, you should type @kbd{C-\ x} (if the keyboard has no Meta key, -which is rare these days). -This works both in the Vi command state and in the Insert and Replace -states. In Vi command state, you can also use @kbd{\ @key{ESC}} as the -meta key. - -Note: Emacs binds @kbd{C-\} to a function that offers to change the -keyboard input method in the multilingual environment. Viper overrides this -binding. However, it is still possible to switch the input method by typing -@kbd{\ C-\} in the Vi command state and @kbd{C-z \ C-\} in the Insert state. -Or you can use the MULE menu in the menubar. -@end table -@noindent -Other differences are mostly improvements. The ones you should know -about are: - -@table @samp -@item Undo -@kindex @kbd{u} -@kbd{u} will undo. Undo can be repeated by the @kbd{.} key. Undo itself -can be undone. Another @kbd{u} will change the direction. The presence -of repeatable undo means that @kbd{U}, undoing lines, is not very -important. Therefore, @kbd{U} also calls @code{viper-undo}. -@cindex multiple undo -@cindex undo - - -@item Counts -Most commands, @kbd{~}, @kbd{[[}, @kbd{p}, @kbd{/}, @dots{}, etc., take counts. - -@comment ]] Just to balance parens -@item Regexps -Viper uses Emacs Regular Expressions for searches. These are a superset of -Vi regular -expressions, excepting the change-of-case escapes @samp{\u}, @samp{\L}, -@dots{}, etc. @xref{Regexps,,Syntax of Regular Expressions,emacs,The -GNU Emacs Manual}, for details. -Files specified to @kbd{:e} use @code{csh} regular expressions -(globbing, wildcards, what have you). -However, the function @code{viper-toggle-search-style}, bound to @kbd{C-c /}, -lets the user switch from search with regular expressions to plain vanilla -search and vice versa. It also lets one switch from case-sensitive search -to case-insensitive and back. -@xref{Viper Specials}, for more details. -@cindex regular expressions -@cindex vanilla search -@cindex case-sensitive search -@cindex case-insensitive search -@kindex @kbd{C-c /} - -@item Ex commands -@cindex Ex commands -The current working directory of a buffer is automatically inserted in the -minibuffer if you type @kbd{:e} then space. Absolute filenames are -required less often in Viper. For file names, Emacs uses a convention that -is slightly different from other programs. It is designed to minimize the -need for deleting file names that Emacs provides in its prompts. (This is -usually convenient, but occasionally the prompt may suggest a wrong file -name for you.) If you see a prompt @kbd{/usr/foo/} and you wish to edit the -file @kbd{~/.viper}, you don't have to erase the prompt. Instead, simply -continue typing what you need. Emacs will interpret @kbd{/usr/foo/~/.viper} -correctly. Similarly, if the prompt is @kbd{~/foo/} and you need to get to -@kbd{/bar/file}, keep typing. Emacs interprets @kbd{~/foo//bar/} as -@kbd{/bar/file}, since when it sees @samp{//}, it understands that -@kbd{~/foo/} is to be discarded. - -The command @kbd{:cd} will change the default directory for the -current buffer. The command @kbd{:e} will interpret the -filename argument in @code{csh}. @xref{Customization}, if you -want to change the default shell. -The command @kbd{:next} takes counts from -@kbd{:args}, so that @kbd{:rew} is obsolete. Also, @kbd{:args} will show only -the invisible files (i.e., those that are not currently seen in Emacs -windows). - -When applicable, Ex commands support file completion and history. This -means that by typing a partial file name and then @key{TAB}, Emacs will try -to complete the name or it will offer a menu of possible completions. -This works similarly to Tcsh and extends the behavior of Csh. While Emacs -is waiting for a file name, you can type @kbd{M-p} to get the previous file -name you typed. Repeatedly typing @kbd{M-p} and @kbd{M-n} will let you -browse through the file history. - -Like file names, partially typed Ex commands can be completed by typing -@key{TAB}, and Viper keeps the history of Ex commands. After typing -@kbd{:}, you can browse through the previously entered Ex commands by -typing @kbd{M-p} and @kbd{M-n}. Viper tries to rationalize when it puts Ex -commands on the history list. For instance, if you typed @kbd{:w!@: foo}, -only @kbd{:w!} will be placed on the history list. This is because the -last history element is the default that can be invoked simply by typing -@kbd{: @key{RET}}. If @kbd{:w!@: foo} were placed on the list, it would be all to -easy to override valuable data in another file. Reconstructing the full -command, @kbd{:w!@: foo}, from the history is still not that hard, since Viper -has a separate history for file names. By typing @kbd{: M-p}, you will get -@kbd{:w!} in the minibuffer. Then, repeated @kbd{M-p} will get you through -the file history, inserting one file name after another. - -In contrast to @kbd{:w!@: foo}, if the command were @kbd{:r foo}, the entire -command will appear in the history list. This is because having @kbd{:r} -alone as a default is meaningless, since this command requires a file -argument. -@refill -@end table -@noindent -As in Vi, Viper's destructive commands can be re-executed by typing `@kbd{.}'. -However, in addition, Viper keeps track of the history of such commands. This -history can be perused by typing @kbd{C-c M-p} and @kbd{C-c M-n}. -Having found the appropriate command, it can be then executed by typing -`@kbd{.}'. -@xref{Improvements over Vi}, for more information. - -@node Insert State, Replace State, Vi State, States in Viper -@subsection Insert State - -@cindex Insert state - -To avoid confusing the beginner (at Viper level 1 and 2), Viper makes only the -standard Vi keys available in Insert state. The implication is that -Emacs major modes cannot be used in Insert state. -It is strongly recommended that as soon as you are comfortable, make the -Emacs state bindings visible (by changing your user level to 3 or higher). -@xref{Customization}, -to see how to do this.@refill - -Once this is done, it is possible to do quite a bit of editing in -Insert state. For instance, Emacs has a @dfn{yank} command, @kbd{C-y}, -which is similar to Vi's @kbd{p}. However, unlike @kbd{p}, @kbd{C-y} can be -used in Insert state of Viper. Emacs also has a kill ring where it keeps -pieces of text you deleted while editing buffers. The command @kbd{M-y} is -used to delete the text previously put back by Emacs's @kbd{C-y} or by Vi's -@kbd{p} command and reinsert text that was placed on the kill-ring earlier. - -This works both in Vi and Insert states. -In Vi state, @kbd{M-y} is a much better alternative to the usual Vi's way -of recovering the 10 previously deleted chunks of text. In Insert state, -you can -use this as follows. Suppose you deleted a piece of text and now you need -to re-insert it while editing in Insert mode. The key @kbd{C-y} will put -back the most recently deleted chunk. If this is not what you want, type -@kbd{M-y} repeatedly and, hopefully, you will find the chunk you want. - -Finally, in Insert and Replace states, Viper provides the history of -pieces of text inserted in previous insert or replace commands. These -strings of text can be recovered by repeatedly typing @kbd{C-c M-p} or -@kbd{C-c M-n} while in Insert or Replace state. (This feature is disabled -in the minibuffer: the above keys are usually bound to other histories, -which are more appropriate in the minibuffer.) - - -@cindex Meta key - -You can call Meta functions from Insert state. As in Vi state, the Meta key -is @kbd{C-\}. Thus @kbd{M-x} is typed as @kbd{C-\ x}. - -Other Emacs commands that are useful in Insert state are @kbd{C-e} -and @kbd{C-a}, which move the cursor to the end and the beginning of the -current line, respectively. You can also use @kbd{M-f} and @kbd{M-b}, -which move the cursor forward (or backward) one word. -If your display has a Meta key, these functions are invoked by holding the -Meta key and then typing @kbd{f} and @kbd{b}, respectively. On displays -without the Meta key, these functions are invoked by typing -@kbd{C-\ f} and @kbd{C-\ b} (@kbd{C-\} simulates the Meta key in Insert -state, as explained above). - -The key @kbd{C-z} is sometimes also useful in Insert state: it allows you -to execute a single command in Vi state without leaving the Insert state! -For instance, @kbd{C-z d2w} will delete the next two words without leaving -the Insert state. - -When Viper is in Insert state, you will see in the mode line. - -@node Replace State,, Insert State, States in Viper -@subsection Replace State - -@cindex Replace state - -This state is entered through Vi replacement commands, such as @kbd{C}, -@kbd{cw}, etc., or by typing @kbd{R}. In Replace state, Viper puts in -the mode line to let you know which state is in effect. If Replace state is -entered through @kbd{R}, Viper stays in that state until the user hits -@key{ESC}. If this state is entered via the other replacement commands, -then Replace state is in effect until you hit @key{ESC} or until you cross -the rightmost boundary of the replacement region. In the latter case, Viper -changes its state from Replace to Insert (which you will notice by the -change in the mode line). - -Since Viper runs under Emacs, it is possible to switch between buffers -while in Replace state. You can also move the cursor using the arrow keys -(even on dumb terminals!)@: and the mouse. Because of this freedom (which is -unattainable in regular Vi), it is possible to take the cursor outside the -replacement region. (This may be necessary for several reasons, including -the need to enable text selection and region-setting with the mouse.) - -The issue then arises as to what to do when the user -hits the @key{ESC} key. In Vi, this would cause the text between cursor and -the end of the replacement region to be deleted. But what if, as is -possible in Viper, the cursor is not inside the replacement region? - -To solve the problem, Viper keeps track of the last cursor position while it -was still inside the replacement region. So, in the above situation, Viper -would delete text between this position and the end of the replacement -region. - -@node The Minibuffer,Multiple Files in Viper, States in Viper, Overview -@section The Minibuffer - -@cindex Minibuffer - -The minibuffer is where commands are entered in. Editing can be done -by commands from Insert state, namely: - -@table @kbd -@item C-h -Backspace -@item C-w -Delete Word -@item C-u -Erase line -@item C-v -Quote the following character -@item @key{RET} -Execute command -@item C-g and C-] -Emacs quit and abort keys. These may be necessary. @xref{Vi State}, for an -explanation. -@item M-p and M-n -These keys are bound to functions that peruse minibuffer history. The -precise history to be perused depends on the context. It may be the history -of search strings, Ex commands, file names, etc. -@item C-s -If the minibuffer is entered via the Viper search commands @kbd{/} or -@kbd{?}, then this key inserts the last search string used by the -Emacs incremental search command -(which is bound to @kbd{C-s} everywhere except in this case). -@end table - -Most of the Emacs keys are functional in the minibuffer. While in the -minibuffer, Viper tries to make editing resemble Vi's behavior when the -latter is waiting for the user to type an Ex command. In particular, you -can use the regular Vi commands to edit the minibuffer. You can switch -between the Vi state and Insert state at will, and even use the replace mode. -Initially, the minibuffer comes up in Insert state. - -Some users prefer plain Emacs bindings in the minibuffer. To this end, set -@code{viper-vi-style-in-minibuffer} to @code{nil} in @file{.viper}. -@xref{Customization}, to learn how to do this. - -When the minibuffer changes Viper states, you will notice that the appearance -of the text there changes as well. This is useful because the minibuffer -has no mode line to tell which Vi state it is in. -The appearance of the text in the minibuffer can be changed. -@xref{Viper Specials}, for more details. - -@node Multiple Files in Viper,Unimplemented Features,The Minibuffer,Overview -@section Multiple Files in Viper - -@cindex multiple files -@cindex managing multiple files - -Viper can edit multiple files. This means, for example that you never need -to suffer through @code{No write since last change} errors. -Some Viper elements are common over all the files. - -@table @samp -@item Textmarkers -@cindex markers -@cindex textmarkers -Textmarkers remember @emph{files and positions}. -If you set marker @samp{a} in -file @file{foo}, start editing file @file{bar} and type @kbd{'a}, then -@emph{YOU WILL SWITCH TO FILE @file{foo}}. You can see the contents of a -textmarker using the Viper command @kbd{[} where are the -textmarkers, e.g., @kbd{[a} to view marker @samp{a} .@refill -@item Repeated Commands -Command repetitions are common over files. Typing @kbd{!!} will repeat the -last @kbd{!} command whichever file it was issued from. -Typing @kbd{.} will repeat the last command from any file, and -searches will repeat the last search. Ex commands can be repeated by typing -@kbd{: @key{RET}}.@refill -Note: in some rare cases, that @kbd{: @key{RET}} may do something dangerous. -However, usually its effect can be undone by typing @kbd{u}. -@item Registers -@cindex registers -Registers are common to files. Also, text yanked with @kbd{y} can be -put back (@kbd{p}) into any file. The Viper command @kbd{]}, where are -the registers, can be used to look at the contents of a register, e.g., -type @kbd{]a} to view register @samp{a}. - -There is one difference in text deletion that you should be -aware of. This difference comes from Emacs and was adopted in Viper -because we find it very useful. In Vi, if you delete a line, say, and then -another line, these two deletions are separated and are put back -separately if you use the @samp{p} command. In Emacs (and Viper), successive -series of deletions that are @emph{not interrupted} by other commands are -lumped together, so the deleted text gets accumulated and can be put back -as one chunk. If you want to break a sequence of deletions so that the -newly deleted text could be put back separately from the previously deleted -text, you should perform a non-deleting action, e.g., move the cursor one -character in any direction. -@item Absolute Filenames -@cindex absolute file names -The current directory name for a file is automatically prepended to the -file name in any -@kbd{:e}, @kbd{:r}, @kbd{:w}, etc., command (in Emacs, each buffer has a -current directory). -This directory is inserted in the minibuffer once you type space after -@kbd{:e, r}, etc. Viper also supports completion of file names and Ex -commands (@key{TAB}), and it keeps track of -command and file history (@kbd{M-p}, @kbd{M-n}). -Absolute filenames are required less -often in Viper. - -You should be aware that Emacs interprets @kbd{/foo/bar//bla} as -@kbd{/bla} and @kbd{/foo/~/bar} as @kbd{~/bar}. This is designed to -minimize the need for erasing file names that Emacs suggests in its -prompts, if a suggested file name is not what you wanted. - -The command @kbd{:cd} will change the default directory for the -current Emacs buffer. The Ex command @kbd{:e} will interpret the -filename argument in @samp{csh}, by default. @xref{Customization}, if you -want to change this. -@end table - -@noindent -Currently undisplayed files can be listed using the @kbd{:ar} command. The -command @kbd{:n} can be given counts from the @kbd{:ar} list to switch to -other files. For example, use `:n3' to move to the third file in that list. - -@node Unimplemented Features,,Multiple Files in Viper,Overview -@section Unimplemented Features - -Unimplemented features include: - -@itemize @bullet -@item -@kbd{:ab} and @kbd{:una} are not implemented, since -@kbd{:ab} is considered obsolete, since Emacs has much -more powerful facilities for defining abbreviations. -@item -@kbd{:set option?} is not implemented. The current -@kbd{:set} can also be used to set Emacs variables. -@item -@kbd{:se list} requires modification of the display code for Emacs, so -it is not implemented. -A useful alternative is @code{cat -t -e file}. Unfortunately, it cannot -be used directly inside Emacs, since Emacs will obdurately change @samp{^I} -back to normal tabs.@refill -@end itemize - -@comment node-name, next, previous, up -@node Improvements over Vi, Customization, Overview, Top -@chapter Improvements over Vi - -Some common problems with Vi and Ex have been solved in Viper. This -includes better implementation of existing commands, new commands, and -the facilities provided by Emacs. - -@menu -* Basics:: Basic Viper differences, Multi-file effects. -* Undo and Backups:: Multiple undo, auto-save, backups and changes -* History:: History for Ex and Vi commands. -* Macros and Registers:: Keyboard Macros (extended ".")@: @@reg execution. -* Completion:: Filename and Command Completion for Ex. -* Improved Search:: Incremental Search and Buffer Content Search. -* Abbreviation Facilities:: Normal Abbrevs, Templates, and Dynamic Abbrevs. -* Movement and Markers:: Screen Editor movements, viewing textmarkers. -* New Commands:: Commands that do not exist in Vi. -* Useful Packages:: A Sampling of some Emacs packages, and things - you should know about. -@end menu - -@node Basics, Undo and Backups, Improvements over Vi, Improvements over Vi -@section Basics - -The Vi command set is based on the idea of combining motion commands -with other commands. The motion command is used as a text region -specifier for other commands. -We classify motion commands into @dfn{point commands} and -@dfn{line commands}.@refill - -@cindex point commands - -The point commands are: - -@quotation -@kbd{h}, @kbd{l}, @kbd{0}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, -@kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, -@kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^} -@end quotation - -@cindex line commands - -The line commands are: - -@quotation -@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, -@kbd{@}}, @kbd{G}, @kbd{'}, @kbd{[[}, @kbd{]]}, @kbd{[]} -@end quotation - -@cindex region -@cindex region specification -@cindex expanding (region) -@cindex describing regions -@cindex movement commands - -@noindent -If a point command is given as an argument to a modifying command, the -region determined by the point command will be affected by the modifying -command. On the other hand, if a line command is given as an argument to a -modifying command, the region determined by the line command will be -enlarged so that it will become the smallest region properly containing the -region and consisting of whole lines (we call this process @dfn{expanding -the region}), and then the enlarged region will be affected by the modifying -command. -Text Deletion Commands (@pxref{Deleting Text}), Change commands -(@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands}) -use these commands to describe a region of text to operate on. -Thus, type @kbd{dw} to delete a word, @kbd{>@}} to shift a paragraph, or -@kbd{!'afmt} to format a region from @samp{point} to textmarker -@samp{a}. - -@cindex r and R region specifiers - -Viper adds the region specifiers @samp{r} and @samp{R}. Emacs has a -special marker called @dfn{mark}. The text-area between the current cursor -position @dfn{point} and the @dfn{mark} is called the @dfn{region}. -@samp{r} specifies the raw region and @samp{R} is the expanded region -(i.e., the minimal contiguous chunk of full lines that contains the raw -region). -@kbd{dr} will now delete the region, @kbd{>r} will shift it, etc. -@kbd{r,R} are not motion commands, however. The special mark is set by -@kbd{m.} and other commands. @xref{Marking}, for more info. - -Viper also adds counts to most commands for which it would make sense. - -In the Overview chapter, some Multiple File issues were discussed -(@pxref{Multiple Files in Viper}). In addition to the files, Emacs has -buffers. These can be seen in the @kbd{:args} list and switched using -@kbd{:next} if you type @kbd{:set ex-cycle-through-non-files t}, or -specify @code{(setq ex-cycle-through-non-files t)} in your @file{.viper} -file. @xref{Customization}, for details. - -@node Undo and Backups, History, Basics, Improvements over Vi -@section Undo and Backups - -@cindex undo - -Viper provides multiple undo. The number of undo's and the size is limited -by the machine. The Viper command @kbd{u} does an undo. Undo can be -repeated by typing @kbd{.} (a period). Another @kbd{u} will undo the undo, -and further -@kbd{.} will repeat it. Typing @kbd{u} does the first undo, and changes the -direction. - -@cindex backup files -@cindex auto save - -Since the undo size is limited, Viper can create backup files and -auto-save files. It will normally do this automatically. It is possible -to have numbered backups, etc. For details, @pxref{Backup,,Backup and -Auto-Save,emacs,The GNU Emacs Manual} @refill - -@comment [ balance parens -@cindex viewing registers and markers -@cindex registers -@cindex markers -@cindex textmarkers - -The results of the 9 previous changes are available in the 9 numeric -registers, as in Vi. The extra goody is the ability to @emph{view} these -registers, in addition to being able to access them through @kbd{p} and -@kbd{M-y} (@xref{Insert State}, for details.) -The Viper command @kbd{] register} will display the contents of any -register, numeric or alphabetical. The related command @kbd{[ textmarker} -will show the text around the textmarker. @samp{register} and @samp{textmarker} -can be any letters from a through z. -@comment ] balance parens - -@node History, Macros and Registers, Undo and Backups,Improvements over Vi -@section History - -@cindex history -@cindex Minibuffer - -History is provided for Ex commands, Vi searches, file names, pieces of -text inserted in earlier commands that use Insert or Replace state, and for -destructive commands in Vi state. These are -useful for fixing those small typos that screw up searches and @kbd{:s}, -and for eliminating routine associated with repeated typing of file names -or pieces of text that need to be inserted frequently. -At the @kbd{:} or @kbd{/} prompts in the minibuffer, you can do the following: - -@table @kbd -@item M-p and M-n -To move to previous and next history items. This causes the history -items to appear on the command line, where you can edit them, or -simply type Return to execute. -@item M-r and M-s -To search backward and forward through the history. -@item @key{RET} -Type @key{RET} to accept a default (which is displayed in the prompt). -@end table - -The history of insertions can be perused by -typing @kbd{C-c M-p} and @kbd{C-c M-n} while in Insert or Replace state. -The history of destructive Vi commands can be perused via the same keys -when Viper is in Vi state. @xref{Viper Specials}, for details. - -All Ex commands have a file history. For instance, typing @kbd{:e}, space -and then @kbd{M-p} will bring up the name of the previously typed file -name. Repeatedly typing @kbd{M-p}, @kbd{M-n}, etc., will let you browse -through the file history. - -Similarly, commands that have to do with switching buffers -have a buffer history, and commands that expect strings or regular -expressions keep a history on those items. - -@node Macros and Registers,Completion,History,Improvements over Vi -@section Macros and Registers - -@cindex keyboard macros -@cindex macros -@cindex registers -@cindex register execution - -Viper facilitates the use of Emacs-style keyboard macros. @kbd{@@#} will -start a macro definition. As you type, the commands will be executed, and -remembered (This is called ``learn mode'' in some editors.) -@kbd{@@register} will complete the macro, putting it into @samp{register}, -where @samp{register} is any character from @samp{a} through @samp{z}. Then -you can execute this macro using @kbd{@@register}. It is, of course, -possible to yank some text into a register and execute it using -@kbd{@@register}. Typing @kbd{@@@@}, @kbd{@@RET}, or @kbd{@@C-j} will -execute the last macro that was executed using @kbd{@@register}.@refill - -Viper will automatically lowercase the register, so that pressing the -@kbd{SHIFT} key for @kbd{@@} will not create problems. This is for -@kbd{@@} macros and @kbd{"p} @emph{only}. In the case of @kbd{y}, -@kbd{"Ayy} will append to @emph{register a}. For @kbd{[,],',`}, it -is an error to use a Uppercase register name. - -@comment [ balance parens -@cindex viewing registers and markers - -The contents of a register can be seen by @kbd{]register}. (@kbd{[textmarker} -will show the contents of a textmarker). -@comment ] balance parens - -@cindex last keyboard macro - -The last keyboard macro can also be executed using -@kbd{*}, and it can be yanked into a register using @kbd{@@!register}. -This is useful for Emacs style keyboard macros defined using @kbd{C-x(} -and @kbd{C-x)}. Emacs keyboard macros have more capabilities. -@xref{Keyboard Macros,,Keyboard Macros,emacs, The GNU Emacs Manual}, for -details.@refill - -Keyboard Macros allow an interesting form of Query-Replace: -@kbd{/pattern} or @kbd{n} to go to the next pattern (the query), followed by a -Keyboard Macro execution @kbd{@@@@} (the replace). - -Viper also provides Vi-style macros. @xref{Vi Macros}, for details. - - -@node Completion, Improved Search, Macros and Registers, Improvements over Vi -@section Completion - -@cindex completion - -Completion is done when you type @key{TAB}. The Emacs completer does not -grok wildcards in file names. Once you type a wildcard, the completer will -no longer work for that file name. Remember that Emacs interprets a file name -of the form @kbd{/foo//bar} as @kbd{/bar} and @kbd{/foo/~/bar} as -@kbd{~/bar}. - -@node Improved Search, Abbreviation Facilities, Completion, Improvements over Vi -@section Improved Search - -@cindex buffer search -@cindex word search - -Viper provides buffer search, the ability to search the buffer for a region -under the cursor. You have to turn this on in @file{.viper} either by calling - -@example -(viper-buffer-search-enable) -@end example - -@noindent -or by setting @code{viper-buffer-search-char} to, say, @kbd{f3}: -@example -(setq viper-buffer-search-char ?g) -@end example - -@noindent -If the user calls @code{viper-buffer-search-enable} explicitly (the first -method), then @code{viper-buffer-search-char} will be set to @kbd{g}. -Regardless of how this feature is enabled, the key -@code{viper-buffer-search-char} will take movement commands, like -@kbd{w,/,e}, to find a region and then search for the contents of that -region. This command is very useful for searching for variable names, etc., -in a program. The search can be repeated by @kbd{n} or reversed by @kbd{N}. - -@cindex incremental search - -Emacs provides incremental search. As you type the string in, the -cursor will move to the next match. You can snarf words from the buffer -as you go along. Incremental Search is normally bound to @kbd{C-s} and -@kbd{C-r}. @xref{Customization}, to find out how to change the bindings -of @kbd{C-r or C-s}. -For details, @pxref{Incremental Search,,Incremental -Search,emacs,The GNU Emacs Manual} @refill - -@cindex query replace - -Viper also provides a query replace function that prompts through the -minibuffer. It is invoked by the @kbd{Q} key in Vi state. - -@cindex mouse search - -On a window display, Viper supports mouse search, i.e., you can search for a -word by clicking on it. @xref{Viper Specials}, for details. - -Finally, on a window display, Viper highlights search patterns as it finds -them. This is done through what is known as @emph{faces} in Emacs. The -variable that controls how search patterns are highlighted is -@code{viper-search-face}. If you don't want any highlighting at all, put -@example -(copy-face 'default 'viper-search-face) -@end example -@vindex @code{viper-search-face} -@noindent -in @file{~/.viper}. If you want to change how patterns are highlighted, you -will have to change @code{viper-search-face} to your liking. The easiest -way to do this is to use Emacs customization widget, which is accessible -from the menubar. Viper customization group is located under the -@emph{Emulations} customization group, which in turn is under the -@emph{Editing} group (or simply by typing @kbd{:customize}). All Viper -faces are grouped together under Viper's -@emph{Highlighting} group. - -Try it: it is really simple! - -@node Abbreviation Facilities,Movement and Markers,Improved Search,Improvements over Vi -@section Abbreviation Facilities - -@cindex abbrevs - -It is possible in Emacs to define abbrevs based on the contents of the -buffer. -Sophisticated templates can be defined using the Emacs abbreviation -facilities. @xref{Abbrevs,,Abbreviations,emacs,The GNU Emacs Manual}, for -details. - -@cindex dynamic abbrevs - -Emacs also provides Dynamic Abbreviations. Given a partial word, Emacs -will search the buffer to find an extension for this word. For instance, -one can type @samp{Abbreviations} by typing @samp{A}, followed by a keystroke -that completed the @samp{A} to @samp{Abbreviations}. Repeated typing -will search further back in the buffer, so that one could get -@samp{Abbrevs} by repeating the -keystroke, which appears earlier in the text. Emacs binds this to -@kbd{@key{ESC} /}, so you will have to find a key and bind the function -@code{dabbrev-expand} to that key. -Facilities like this make Vi's @kbd{:ab} command obsolete. - -@node Movement and Markers, New Commands, Abbreviation Facilities, Improvements over Vi -@section Movement and Markers - -@cindex Ex style motion -@cindex line editor motion - -Viper can be set free from the line--limited movements in Vi, such as @kbd{l} -refusing to move beyond the line, @key{ESC} moving one character back, -etc. These derive from Ex, which is a line editor. If your @file{.viper} -contains - -@example -@code{(setq viper-ex-style-motion nil)} -@end example - -@noindent -the motion will be a true screen editor motion. One thing you must then -watch out for is that it is possible to be on the end-of-line character. -The keys @kbd{x} and @kbd{%} will still work correctly, i.e., as if they -were on the last character. - -@vindex @code{viper-syntax-preference} -@cindex syntax table - -The word-movement commands @kbd{w}, @kbd{e}, etc., and the associated -deletion/yanking commands, @kbd{dw}, @kbd{yw}, etc., can be made to -understand Emacs syntax tables. If the variable -@code{viper-syntax-preference} is set to @code{strict-vi} then -the meaning of @emph{word} is the same as in -Vi. However, if the value is @code{reformed-vi} (the default) then the -alphanumeric symbols will be those specified by the current Emacs syntax -table (which may be different for different major modes) plus the -underscore symbol @kbd{_}, minus some non-word symbols, like '.;,|, etc. -Both @code{strict-vi} and @code{reformed-vi} work close to Vi in -traditional cases, but @code{reformed-vi} does a better job when editing -text in non-Latin alphabets. - -The user can also specify the value @code{emacs}, which would -make Viper use exactly the Emacs notion of word. In particular, the -underscore may not be part of a word. Finally, if -@code{viper-syntax-preference} is set to @code{extended}, Viper words would -consist of characters that are classified as alphanumeric @emph{or} as -parts of symbols. This is convenient for writing programs and in many other -situations. - -@code{viper-syntax-preference} is a local variable, so it can have different -values for different major modes. For instance, in programming modes it can -have the value @code{extended}. In text modes where words contain special -characters, such as European (non-English) letters, Cyrillic letters, etc., -the value can be @code{reformed-vi} or @code{emacs}. - -Changes to @code{viper-syntax-preference} should be done in the hooks to -various major modes by executing @code{viper-set-syntax-preference} as in -the following example: - -@example -(viper-set-syntax-preference nil "emacs") -@end example - -@findex @code{viper-set-syntax-preference} - -The above discussion of the meaning of Viper's words concerns only Viper's -movement commands. In regular expressions, words remain the same as in -Emacs. That is, the expressions @code{\w}, @code{\>}, @code{\<}, etc., use -Emacs's idea of what is a word, and they don't look into the value of -variable @code{viper-syntax-preference}. This is because Viper doesn't change -syntax tables in fear of upsetting the various major modes that set these -tables. - -@cindex textmarkers - -Textmarkers in Viper remember the file and the position, so that you can -switch files by simply doing @kbd{'a}. If you set up a regimen for using -Textmarkers, this is very useful. Contents of textmarkers can be viewed -by @kbd{[marker}. (Contents of registers can be viewed by @kbd{]register}). - -@node New Commands, Useful Packages, Movement and Markers, Improvements over Vi -@section New Commands - -These commands have no Vi analogs. - -@table @kbd -@item C-x, C-c -@kindex @kbd{C-x} -@kindex @kbd{C-c} -These two keys invoke many important Emacs functions. For example, if you -hit @kbd{C-x} followed by @kbd{2}, then the current window will be split -into 2. Except for novice users, @kbd{C-c} is also set to execute an Emacs -command from the current major mode. @key{ESC} will do the same, if you -configure @key{ESC} as Meta by setting @code{viper-no-multiple-ESC} to @code{nil} -in @file{.viper}. @xref{Customization}. @kbd{C-\} in Insert, Replace, or Vi -states will make Emacs think @kbd{Meta} has been hit.@refill -@item \ -@kindex @kbd{\} -Escape to Emacs to execute a single Emacs command. For instance, -@kbd{\ @key{ESC}} will act like a Meta key. -@item Q -@kindex @kbd{Q} -@cindex query replace -@kbd{Q} is for query replace. By default, -each string to be replaced is treated as a regular expression. You can use -@code{(setq viper-re-query-replace nil)} in your @file{.emacs} file to -turn this off. (For normal searches, @kbd{:se nomagic} will work. Note -that @kbd{:se nomagic} turns Regexps off completely, unlike Vi). -@item v -@itemx V -@itemx C-v -@kindex @kbd{v} -@kindex @kbd{V} -@kindex @kbd{C-v} -These keys are used to visit files. @kbd{v} will switch to a buffer -visiting file whose name can be entered in the minibuffer. @kbd{V} is -similar, but will use a window different from the current window. -@kbd{C-v} is like @kbd{V}, except that a new frame (X window) will be used -instead of a new Emacs window. -@item # -@kindex @kbd{#} -If followed by a certain character @var{ch}, it becomes an operator whose -argument is the region determined by the motion command that follows -(indicated as ). -Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q}, and -@kbd{s}. For instance, @kbd{#qr} will prompt you for a string and then -prepend this string to each line in the buffer.@refill -@item # c -@kindex @kbd{#c} -@cindex changing case -Change upper-case characters in the region to lower-case -(@code{downcase-region}). -Emacs command @kbd{M-l} does the same for words. -@item # C -@kindex @kbd{#C} -Change lower-case characters in the region to upper-case. For instance, -@kbd{# C 3 w} will capitalize 3 words from the current point -(@code{upcase-region}). -Emacs command @kbd{M-u} does the same for words. -@item # g -@kindex @kbd{#g} -Execute last keyboard macro for each line in the region -(@code{viper-global-execute}).@refill -@item # q -@kindex @kbd{#q} -Insert specified string at the beginning of each line in the region -(@code{viper-quote-region}). The default string is composed of the comment -character(s) appropriate for the current major mode. -@item # s -@kindex @kbd{#s} -Check spelling of words in the region (@code{spell-region}). -The function used for spelling is determined from the variable -@code{viper-spell-function}. -@vindex @code{viper-spell-function} -@item * -@kindex @kbd{*} -Call last keyboard macro. -@item m . -Set mark at point and push old mark off the ring -@item m< -@item m> -Set mark at beginning and end of buffer, respectively. -@item m, -Jump to mark and pop mark off the ring. @xref{Mark,,Mark,emacs,The GNU -Emacs Manual}, for more info. -@item ] register -@kindex @kbd{]} -View contents of register -@item [ textmarker -@kindex @kbd{[} -View filename and position of textmarker -@item @@# -@item @@register -@item @@! -@kindex @kbd{@@#} -@kindex @kbd{@@} -@kindex @kbd{@@!} -@cindex keyboard macros -@cindex register execution - -Begin/end keyboard macro. @@register has a different meaning when used after -a @kbd{@@#}. @xref{Macros and Registers}, for details -@item [] -@kindex @kbd{[]} -Go to end of heading. -@item g <@emph{movement command}> -Search buffer for text delimited by movement command. The canonical -example is @kbd{gw} to search for the word under the cursor. -@xref{Improved Search}, for details.@refill -@item C-g and C-] -@kindex @kbd{C-g} -@kindex @kbd{C-]} -Quit and Abort Recursive edit. These may be necessary on occasion. -@xref{Vi State}, for a reason. -@item C-c C-g -@kindex @kbd{C-c C-g} -Hitting @kbd{C-c} followed by @kbd{C-g} will display the information on the -current buffer. This is the same as hitting @kbd{C-g} in Vi, but, as -explained above, @kbd{C-g} is needed for other purposes in Emacs. -@item C-c / -@kindex @kbd{C-c /} -Without a prefix argument, this command toggles -case-sensitive/case-insensitive search modes and plain vanilla/regular -expression search. With the prefix argument 1, i.e., -@kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2, -toggles plain vanilla search and search using -regular expressions. @xref{Viper Specials}, for alternative ways to invoke -this function. -@cindex vanilla search -@cindex case-sensitive search -@cindex case-insensitive search - -@item M-p and M-n -@kindex @kbd{M-p} -@kindex @kbd{M-n} -In the minibuffer, these commands navigate through the minibuffer -histories, such as the history of search strings, Ex commands, etc. - -@item C-s -@kindex @kbd{C-s} -If the minibuffer is entered via a Viper search commands @kbd{/} or @kbd{?}, -then typing this key inserts the last search string used by the -Emacs incremental search command (that is bound to @kbd{C-s} everywhere -except in this case). - -@item C-c M-p and C-c M-n -@kindex @kbd{C-c M-p} -@kindex @kbd{C-c M-n} -@cindex Insertion history -@cindex Insertion ring -@cindex Command history -@cindex Command ring - -In Insert or Replace state, these commands let the user -peruse the history of insertion strings used in previous insert or replace -commands. Try to hit @kbd{C-c M-p} or @kbd{C-c M-n} repeatedly and see what -happens. @xref{Viper Specials}, for more. - -In Vi state, these commands let the user peruse the history of Vi-style -destructive commands, such as @kbd{dw}, @kbd{J}, @kbd{a}, etc. -By repeatedly typing @kbd{C-c M-p} or @kbd{C-c M-n} you will cycle Viper -through the recent history of Vi commands, displaying the commands one by -one. Once -an appropriate command is found, it can be executed by typing `@kbd{.}'. - -Since typing @kbd{C-c M-p} is tedious, it is more convenient to bind an -appropriate function to a function key on the keyboard and use that key. -@xref{Viper Specials}, for details. - -@item Ex commands -@findex @kbd{:args} -@findex @kbd{:n} -@findex @kbd{:pwd} -@findex @kbd{:pre} -The commands @kbd{:args}, @kbd{:next}, @kbd{:pre} behave -differently. @kbd{:pwd} exists to get current directory. -The commands @kbd{:b} and @kbd{:B} switch buffers around. @xref{File and -Buffer Handling}, for details. -There are also the new commands @kbd{:RelatedFile} and -@kbd{PreviousRelatedFile} (which abbreviate to @kbd{R} and @kbd{P}, -respectively. @xref{Viper Specials}, for details. -@findex @kbd{:RelatedFile} -@findex @kbd{:PreviousRelatedFile} -@end table - -Apart from the new commands, many old commands have been enhanced. Most -notably, Vi style macros are much more powerful in Viper than in Vi. @xref{Vi -Macros}, for details. - -@node Useful Packages, ,New Commands, Improvements over Vi -@section Useful Packages - -Some Emacs packages are mentioned here as an aid to the new Viper user, to -indicate what Viper is capable of. -A vast number comes with the standard Emacs distribution, and many more exist -on the net and on the archives. - -This manual also mentions some Emacs features a new user -should know about. The details of these are found in the GNU Emacs -Manual. - -The features first. For details, look up the Emacs Manual. - -@table @samp -@item Make -@cindex make -@cindex compiling - -Makes and Compiles can be done from the editor. Error messages will be -parsed and you can move to the error lines. -@item Shell -@cindex shell -@cindex interactive shell -You can talk to Shells from inside the editor. Your entire shell session -can be treated as a file. -@item Mail -@cindex email -@cindex mail -Mail can be read from and sent within the editor. Several sophisticated -packages exist. -@item Language Sensitive Editing -Editing modes are written for most computer languages in existence. By -controlling indentation, they catch punctuation errors. -@end table - -The packages, below, represents a drop in the sea of special-purpose -packages that come with standard distribution of Emacs. - -@table @samp -@item Transparent FTP -@cindex transparent ftp -@pindex ange-ftp.el -@code{ange-ftp.el} can ftp from the editor to files on other machines -transparent to the user. -@item RCS Interfaces -@cindex version maintenance -@cindex RCS -@pindex vc.el -@code{vc.el} for doing RCS commands from inside the editor -@item Directory Editor -@cindex dired -@pindex dired.el -@code{dired.el} for editing contents of directories and for navigating in -the file system. -@item Syntactic Highlighting -@cindex font-lock -@pindex font-lock.el -@code{font-lock.el} for automatic highlighting various parts of a buffer -using different fonts and colors. -@item Saving Emacs Configuration -@cindex desktop -@pindex desktop.el -@code{desktop.el} for saving/restoring configuration on Emacs exit/startup. -@item Spell Checker -@cindex ispell -@pindex ispell.el -@code{ispell.el} for spell checking the buffer, words, regions, etc. -@item File and Buffer Comparison -@cindex ediff -@pindex ediff.el -@code{ediff.el} for finding differences between files and for applying -patches. -@end table - -@noindent -Emacs Lisp archives exist on -@samp{archive.cis.ohio-state.edu} -and @samp{wuarchive.wustl.edu}@refill - - -@node Customization,Commands,Improvements over Vi,Top -@chapter Customization - -@cindex customization - -Customization can be done in 2 ways. - -@itemize @bullet -@item -@cindex initialization -@cindex .viper -Elisp code in a @file{.viper} file in your home directory. Viper -loads @file{.viper} just before it does the binding for mode -hooks. This is recommended for experts only. -@item -@cindex .emacs -Elisp code in your @file{.emacs} file before and after the @code{(require -'viper)} line. This method is @emph{not} recommended, unless you know what -you are doing. Only two variables, @code{viper-mode} and -@code{viper-custom-file-name}, are supposed to be customized in @file{.emacs}, -prior to loading Viper (i.e., prior to @code{(require 'viper)} command.@refill -@item -@cindex :customize -By executing the @kbd{:customize} Ex command. This takes you to the Emacs -customization widget, which lets you change the values of Viper -customizable variables easily. This method is good for novice and -experts alike. The customization code in the form of Lisp commands will be -placed in @file{~/.emacs} or some other customization file depending on the -version of Emacs that you use. Still, it is recommended to separate -Viper-related customization produced by the Emacs customization widget -and keep it in the @file{.viper} file. - -Some advanced customization cannot be accomplished this way, however, and -has to be done in Emacs Lisp in the @file{.viper} file. For the common -cases, examples are provided that you can use directly. -@end itemize - - -@menu -* Rudimentary Changes:: Simple constant definitions. -* Key Bindings:: Enabling Emacs Keys, Rebinding keys, etc. -* Packages that Change Keymaps:: How to deal with such beasts. -* Viper Specials:: Special Viper commands. -* Vi Macros:: How to do Vi style macros. -@end menu - -@node Rudimentary Changes,Key Bindings,Customization,Customization -@section Rudimentary Changes - -@cindex setting variables -@cindex variables for customization -@findex @kbd{:set} - -An easy way to customize Viper is to change the values of constants used in -Viper. Here is the list of the constants used in Viper and their default -values. The corresponding :se command is also indicated. (The symbols -@code{t} and @code{nil} represent ``true'' and ``false'' in Lisp). - -Viper supports both the abbreviated Vi variable names and their full -names. Variable completion is done on full names only. @key{TAB} and -@key{SPC} complete -variable names. Typing `=' will complete the name and then will prompt for -a value, if applicable. For instance, @kbd{:se au @key{SPC}} will complete the -command to @kbd{:set autoindent}; @kbd{:se ta @key{SPC}} will complete the command -and prompt further like this: @kbd{:set tabstop = }. -However, typing @kbd{:se ts @key{SPC}} will produce a ``No match'' message -because @kbd{ts} is an abbreviation for @kbd{tabstop} and Viper supports -completion on full names only. However, you can still hit @key{RET} -or @kbd{=}, which will complete the command like this: @kbd{:set ts = } and -Viper will be waiting for you to type a value for the tabstop variable. -To get the full list of Vi variables, type @kbd{:se @key{SPC} @key{TAB}}. - -@table @code -@item viper-auto-indent nil -@itemx :se ai (:se autoindent) -@itemx :se ai-g (:se autoindent-global) -If @code{t}, enable auto indentation. -by @key{RET}, @kbd{o} or @kbd{O} command. - -@code{viper-auto-indent} is a local variable. To change the value globally, use -@code{setq-default}. It may be useful for certain major modes to have their -own values of @code{viper-auto-indent}. This can be achieved by using -@code{setq} to change the local value of this variable in the hooks to the -appropriate major modes. - -@kbd{:se ai} changes the value of @code{viper-auto-indent} in the current -buffer only; @kbd{:se ai-g} does the same globally. -@item viper-electric-mode t -If not @code{nil}, auto-indentation becomes electric, which means that -@key{RET}, @kbd{O}, and @kbd{o} indent cursor according to the current -major mode. In the future, this variable may control additional electric -features. - -This is a local variable: @code{setq} changes the value of this variable -in the current buffer only. Use @code{setq-default} to change the value in -all buffers. -@item viper-case-fold-search nil -@itemx :se ic (:se ignorecase) -If not @code{nil}, search ignores cases. -This can also be toggled by quickly hitting @kbd{/} twice. -@item viper-re-search nil -@itemx :se magic -If not @code{nil}, search will use regular expressions; if @code{nil} then -use vanilla search. -This behavior can also be toggled by quickly hitting @kbd{/} trice. -@item buffer-read-only -@itemx :se ro (:se readonly) -Set current buffer to read only. To change globally put -@code{(setq-default buffer-read-only t)} in your @file{.emacs} file. -@item blink-matching-paren t -@itemx :se sm (:se showmatch) -Show matching parens by blinking cursor. -@item tab-width t (default setting via @code{setq-default}) -@itemx :se ts=value (:se tabstop=value) -@itemx :se ts-g=value (:se tabstop-global=value) -@code{tab-width} is a local variable that controls the width of the tab stops. -To change the value globally, use @code{setq-default}; for local settings, -use @code{setq}. - -The command @kbd{:se ts} -sets the tab width in the current -buffer only; it has no effect on other buffers. - -The command @kbd{:se ts-g} sets tab width globally, -for all buffers where the tab is not yet set locally, -including the new buffers. - -Note that typing @key{TAB} normally -doesn't insert the tab, since this key is usually bound to -a text-formatting function, @code{indent-for-tab-command} (which facilitates -programming and document writing). Instead, the tab is inserted via the -command @code{viper-insert-tab}, which is bound to @kbd{S-tab} (shift + tab). - -On some non-windowing terminals, Shift doesn't modify the @key{TAB} key, so -@kbd{S-tab} behaves as if it were @key{TAB}. In such a case, you will have -to bind @code{viper-insert-tab} to some other convenient key. - -@item viper-shift-width 8 -@itemx :se sw=value (:se shiftwidth=value) -The number of columns shifted by @kbd{>} and @kbd{<} commands. -@item viper-search-wrap-around t -@itemx :se ws (:se wrapscan) -If not @code{nil}, search wraps around the end/beginning of buffer. -@item viper-search-scroll-threshold 2 -If search lands within this many lines of the window top or bottom, the -window will be scrolled up or down by about 1/7-th of its size, to reveal -the context. If the value is negative---don't scroll. -@item viper-tags-file-name "TAGS" -The name of the file used as the tag table. -@item viper-re-query-replace nil -If not @code{nil}, use reg-exp replace in query replace. -@item viper-want-ctl-h-help nil -If not @code{nil}, @kbd{C-h} is bound to @code{help-command}; -otherwise, @kbd{C-h} is bound as usual in Vi. -@item viper-vi-style-in-minibuffer t -If not @code{nil}, Viper provides a high degree of compatibility with Vi -insert mode when you type text in the minibuffer; if @code{nil}, typing in -the minibuffer feels like plain Emacs. -@item viper-no-multiple-ESC t -If you set this to @code{nil}, you can use @key{ESC} as Meta in Vi state. -Normally, this is not necessary, since graphical displays have separate -Meta keys (usually on each side of the space bar). On a dumb terminal, Viper -sets this variable to @code{twice}, which is almost like @code{nil}, except -that double @key{ESC} beeps. This, too, lets @key{ESC} to be used as a Meta. -@item viper-fast-keyseq-timeout 200 -Key sequences separated by this many milliseconds are treated as Vi-style -keyboard macros. If the key sequence is defined as such a macro, it will be -executed. Otherwise, it is processed as an ordinary sequence of typed keys. - -Setting this variable too high may slow down your typing. Setting it too -low may make it hard to type macros quickly enough. -@item viper-ex-style-motion t -Set this to @code{nil}, if you want @kbd{l,h} to cross -lines, etc. @xref{Movement and Markers}, for more info. -@item viper-ex-style-editing t -Set this to @code{nil}, if you want -@kbd{C-h} and @key{DEL} to not stop -at the beginning of a line in Insert state, @key{X} and @key{x} to delete -characters across lines in Vi command state, etc. -@item viper-ESC-moves-cursor-back t -It @code{t}, cursor moves back 1 character when switching from insert state to vi -state. If @code{nil}, the cursor stays where it was before the switch. -@item viper-always t -@code{t} means: leave it to Viper to decide when a buffer must be brought -up in Vi state, -Insert state, or Emacs state. This heuristics works well in virtually all -cases. @code{nil} means you either has to invoke @code{viper-mode} manually -for each buffer (or you can add @code{viper-mode} to the appropriate major mode -hooks using @code{viper-load-hook}). - -This option must be set in the file @file{~/.viper}. -@item viper-custom-file-name "~/.viper" -File used for Viper-specific customization. -Change this setting, if you want. Must be set in @file{.emacs} (not @file{.viper}!) -before Viper is loaded. Note that you -have to set it as a string inside double quotes. -@item viper-spell-function 'ispell-region -Function used by the command @kbd{#c} to spell. -@item viper-glob-function -The value of this variable is the function symbol used to expand wildcard -symbols. This is platform-dependent. The default tries to set this variable -to work with most shells, MS Windows, OS/2, etc. However, if it -doesn't work the way you expect, you should write your own. -Use @code{viper-glob-unix-files} and @code{viper-glob-mswindows-files} in -@file{viper-util.el} as examples. - -This feature is used to expand wildcards in the Ex command @kbd{:e}. -Note that Viper doesn't support wildcards in the @kbd{:r} and @kbd{:w} -commands, because file completion is a better mechanism. -@findex @code{viper-glob-function} - -@item ex-cycle-other-window t -If not @code{nil}, @kbd{:n} and @kbd{:b} will cycle through files in another -window, if one exists. -@item ex-cycle-through-non-files nil -@kbd{:n} does not normally cycle through buffers. Set this to get -buffers also. -@item viper-want-emacs-keys-in-insert -This is set to @code{nil} for user levels 1 and 2 and to @code{t} for user -levels 3 and 4. Users who specify level 5 are allowed to set this variable -as they please (the default for this level is @code{t}). If set to -@code{nil}, complete Vi compatibility is provided in Insert state. This is -really not recommended, as this precludes you from using language-specific -features provided by the major modes. -@item viper-want-emacs-keys-in-vi -This is set to @code{nil} for user -level 1 and to @code{t} for user levels 2--4. -At level 5, users are allowed to set this variable as they please (the -default for this level is @code{t}). -If set to @code{nil}, complete Vi compatibility is provided -in Vi command state. Setting this to @code{nil} is really a bad idea, -unless you are a novice, as this precludes the use -of language-specific features provided by the major modes. -@item viper-keep-point-on-repeat t -If not @code{nil}, point is not moved when the user repeats the previous -command by typing `.' This is very useful for doing repeated changes with -the @kbd{.} key. -@item viper-repeat-from-history-key 'f12 -Prefix key used to invoke the macros @kbd{f12 1} and @kbd{f12 2} that repeat -the second-last and the third-last destructive command. -Both these macros are bound (as Viper macros) to -@code{viper-repeat-from-history}, -which checks the second key by which it is invoked to see which of the -previous commands to invoke. Viper binds @kbd{f12 1} and @kbd{f12 2} only, -but the user can bind more in @file{~/.viper}. @xref{Vi Macros}, for how to do -this. -@item viper-keep-point-on-undo nil -If not @code{nil}, Viper tries to not move point when undoing commands. -Instead, it will briefly move the cursor to the place where change has -taken place. However, if the undone piece of text is not seen in window, -then point will be moved to the place where the change took place. -Set it to @code{t} and see if you like it better. -@item viper-delete-backwards-in-replace nil -If not @code{nil}, @key{DEL} key will delete characters while moving the cursor -backwards. If @code{nil}, the cursor will move backwards without deleting -anything. -@item viper-replace-overlay-face 'viper-replace-overlay-face -On a graphical display, Viper highlights replacement regions instead of -putting a @samp{$} at the end. This variable controls the so called -@dfn{face} used to highlight the region. - -By default, @code{viper-replace-overlay-face} underlines the replacement on -monochrome displays and also lays a stipple over them. On color displays, -replacement regions are highlighted with color. - -If you know something about Emacs faces and don't like how Viper highlights -replacement regions, you can change @code{viper-replace-overlay-face} by -specifying a new face. (Emacs faces are described in the Emacs Lisp -reference.) On a color display, the following customization method is -usually most effective: -@example -(set-face-foreground viper-replace-overlay-face "DarkSlateBlue") -(set-face-background viper-replace-overlay-face "yellow") -@end example -For a complete list of colors available to you, evaluate the expression -@code{(x-defined-colors)}. (Type it in the buffer @code{*scratch*} and then -hit the @kbd{C-j} key. - -@item viper-replace-overlay-cursor-color "Red" -@vindex @code{viper-replace-overlay-cursor-color} -Cursor color when it is inside the replacement region. -This has effect only on color displays and only when Emacs runs as an X -application. -@item viper-insert-state-cursor-color nil -@vindex @code{viper-insert-state-cursor-color} -If set to a valid color, this will be the cursor color when Viper is in -insert state. -@item viper-emacs-state-cursor-color nil -@vindex @code{viper-emacs-state-cursor-color} -If set to a valid color, this will be the cursor color when Viper is in -emacs state. -@item viper-replace-region-end-delimiter "$" -A string used to mark the end of replacement regions. It is used only on -TTYs or if @code{viper-use-replace-region-delimiters} is non-@code{nil}. -@item viper-replace-region-start-delimiter "" -A string used to mark the beginning of replacement regions. It is used -only on TTYs or if @code{viper-use-replace-region-delimiters} is non-@code{nil}. -@item viper-use-replace-region-delimiters -If non-@code{nil}, Viper will always use @code{viper-replace-region-end-delimiter} and -@code{viper-replace-region-start-delimiter} to delimit replacement regions, -even on color displays (where this is unnecessary). By default, this -variable is non-@code{nil} only on TTYs or monochrome displays. -@item viper-allow-multiline-replace-regions t -If non-@code{nil}, multi-line text replacement regions, such as those produced by -commands @kbd{c55w}, @kbd{3C}, etc., will stay around until the user exits -the replacement mode. In this variable is set to @code{nil}, Viper will -emulate the standard Vi behavior, which supports only intra-line -replacement regions (and multi-line replacement regions are deleted). -@item viper-toggle-key "\C-z" -Specifies the key used to switch from Emacs to Vi and back. -Must be set in @file{.viper}. This variable can't be -changed interactively after Viper is loaded. - -In Insert state, this key acts as a temporary escape to Vi state, i.e., it -will set Viper up so that the very next command will be executed as if it -were typed in Vi state. -@item viper-buffer-search-char nil -Key used for buffer search. @xref{Viper Specials}, for details. -@item viper-surrounding-word-function 'viper-surrounding-word -The value of this variable is a function name that is used to determine -what constitutes a word clicked upon by the mouse. This is used by mouse -search and insert. -@item viper-search-face 'viper-search-face -Variable that controls how search patterns are highlighted when they are -found. -@item viper-vi-state-hook nil -List of parameterless functions to be run just after entering the Vi -command state. -@item viper-insert-state-hook nil -Same for Insert state. This hook is also run after entering Replace state. -@item viper-replace-state-hook nil -List of (parameterless) functions called just after entering Replace state -(and after all @code{viper-insert-state-hook}). -@item viper-emacs-state-hook nil -List of (parameterless) functions called just after switching from Vi state -to Emacs state. -@item viper-load-hook nil -List of (parameterless) functions called just after loading Viper. This is -the last chance to do customization before Viper is up and running. -@end table -@noindent -You can reset some of these constants in Viper with the Ex command @kbd{:set} -(when so indicated in the table). Or you -can include a line like this in your @file{.viper} file: -@example -(setq viper-case-fold-search t) -@end example -@vindex @code{viper-auto-indent} -@vindex @code{viper-electric-mode} -@vindex @code{viper-case-fold-search} -@vindex @code{viper-re-search} -@vindex @code{viper-shift-width} -@vindex @code{buffer-read-only} -@vindex @code{viper-search-wrap-around} -@vindex @code{viper-search-scroll-threshold} -@vindex @code{viper-search-face} -@vindex @code{viper-tags-file-name} -@vindex @code{viper-re-query-replace} -@vindex @code{viper-want-ctl-h-help} -@vindex @code{viper-vi-style-in-minibuffer} -@vindex @code{viper-no-multiple-ESC} -@vindex @code{viper-always} -@vindex @code{viper-fast-keyseq-timeout} -@vindex @code{viper-ex-style-motion} -@vindex @code{viper-ex-style-editing} -@vindex @code{viper-ESC-moves-cursor-back} -@vindex @code{viper-custom-file-name} -@vindex @code{viper-spell-function} -@vindex @code{ex-cycle-other-window} -@vindex @code{ex-cycle-through-non-files} -@vindex @code{viper-want-emacs-keys-in-insert} -@vindex @code{viper-want-emacs-keys-in-vi} -@vindex @code{viper-keep-point-on-repeat} -@vindex @code{viper-keep-point-on-undo} -@vindex @code{viper-delete-backwards-in-replace} -@vindex @code{viper-replace-overlay-face} -@vindex @code{viper-replace-region-end-symbol} -@vindex @code{viper-replace-region-start-symbol} -@vindex @code{viper-allow-multiline-replace-regions} -@vindex @code{viper-toggle-key} -@vindex @code{viper-buffer-search-char} -@vindex @code{viper-surrounding-word-function} -@vindex @code{viper-vi-state-hook} -@vindex @code{viper-insert-state-hook} -@vindex @code{viper-replace-state-hook} -@vindex @code{viper-emacs-state-hook} - -@node Key Bindings, Packages that Change Keymaps, Rudimentary Changes,Customization -@section Key Bindings - -@cindex key bindings -@cindex keymaps - -Viper lets you define hot keys, i.e., you can associate keyboard keys -such as F1, Help, PgDn, etc., with Emacs Lisp functions (that may already -exist or that you will write). Each key has a "preferred form" in -Emacs. For instance, the Up key's preferred form is [up], the Help key's -preferred form is [help], and the Undo key has the preferred form [f14]. -You can find out the preferred form of a key by typing @kbd{M-x -describe-key-briefly} and then typing the key you want to know about. - -Under the X Window System, every keyboard key emits its preferred form, -so you can just type - -@lisp -(global-set-key [f11] 'calendar) ; L1, Stop -(global-set-key [f14] 'undo) ; L4, Undo -@end lisp - -@noindent -to bind L1 (a key that exists on some SUN workstations) so it will invoke -the Emacs Calendar and to bind L4 so it will undo changes. -However, on a dumb terminal or in an Xterm window, even the standard arrow -keys may -not emit the right signals for Emacs to understand. To let Emacs know about -those keys, you will have to find out which key sequences they emit -by typing @kbd{C-q} and then the key (you should switch to Emacs state -first). Then you can bind those sequences to their preferred forms using -@code{input-decode-map} as follows: - -@lisp -(cond ((string= (getenv "TERM") "xterm") -(define-key input-decode-map "\e[192z" [f11]) ; L1 -(define-key input-decode-map "\e[195z" [f14]) ; L4, Undo -@end lisp - -The above illustrates how to do this for Xterm. On VT100, you would have to -replace "xterm" with "vt100" and also change the key sequences (the same -key may emit different sequences on different types of terminals). - -The above keys are global, so they are overwritten by the local maps -defined by the major modes and by Viper itself. Therefore, if you wish to -change a binding set by a major mode or by Viper, read this. - -Viper users who wish to specify their own key bindings should be concerned -only with the following three keymaps: -@code{viper-vi-global-user-map} for Vi state commands, -@code{viper-insert-global-user-map} for Insert state commands, -and @code{viper-emacs-global-user-map} for Emacs state commands (note: -customized bindings for Emacs state made to @code{viper-emacs-global-user-map} -are @emph{not} inherited by Insert state). - -For more information on Viper keymaps, see the header of the file -@file{viper.el}. -If you wish to change a Viper binding, you can use the -@code{define-key} command, to modify @code{viper-vi-global-user-map}, -@code{viper-insert-global-user-map}, and @code{viper-emacs-global-user-map}, as -explained below. Each of these key maps affects the corresponding Viper state. -The keymap @code{viper-insert-global-user-map} also affects Viper's Replace -state. - -@noindent -If you want to -bind a key, say @kbd{C-v}, to the function that scrolls -page down and to make @kbd{0} display information on the current buffer, -putting this in @file{.viper} will do the trick in Vi state: -@example -(define-key viper-vi-global-user-map "\C-v" 'scroll-down) -@end example -@noindent -To set a key globally, -@example -(define-key viper-emacs-global-user-map "\C-c m" 'smail) -(define-key viper-vi-global-user-map "0" 'viper-info-on-file) -@end example -@noindent -Note, however, that this binding may be overwritten by other keymaps, since -the global keymap has the lowest priority. -To make sure that nothing will override a binding in Emacs state, you -can write this: -@example -(define-key viper-emacs-global-user-map "\C-c m" 'smail) -@end example -@noindent -To customize the binding for @kbd{C-h} in Insert state: -@example -(define-key viper-insert-global-user-map "\C-h" 'my-del-backwards-function) -@end example -@noindent - -Each Emacs command key calls some Lisp function. If you have enabled the -Help, (@pxref{Rudimentary Changes}) @kbd{C-h k} will show you the function -for each specific key; @kbd{C-h b} will show all bindings, and @kbd{C-h m} -will provide information on the major mode in effect. If Help is not -enabled, you can still get help in Vi state by prefixing the above commands -with @kbd{\}, e.g., @kbd{\ C-h k} (or you can use the Help menu in the -menu bar, if Emacs runs under X). - -Viper users can also change bindings on a per major mode basis. As with -global bindings, this can be done separately for each of the three main Viper -states. To this end, Viper provides the function -@code{viper-modify-major-mode}. -@findex @code{viper-modify-major-mode} - -To modify keys in Emacs state for @code{my-favorite-major-mode}, the user -needs to create a sparse keymap, say, @code{my-fancy-map}, bind whatever -keys necessary in that keymap, and put - -@example -(viper-modify-major-mode 'dired-mode 'emacs-state my-fancy-map) -@end example - -@noindent -in @file{~/.viper}. To do the same in Vi and Insert states, you should use -@code{vi-state} and @code{insert-state}. Changes in Insert state are also -in effect in Replace state. For instance, suppose that the user wants to -use @kbd{dd} in Vi state under Dired mode to delete files, @kbd{u} to unmark -files, etc. The following code in @file{~/.viper} will then do the job: - -@example -(setq my-dired-modifier-map (make-sparse-keymap)) -(define-key my-dired-modifier-map "dd" 'dired-flag-file-deletion) -(define-key my-dired-modifier-map "u" 'dired-unmark) -(viper-modify-major-mode 'dired-mode 'vi-state my-dired-modifier-map) -@end example - -A Vi purist may want to modify Emacs state under Dired mode so that -@kbd{k}, @kbd{l}, etc., will move around in directory buffers, as in -Vi. Although this is not recommended, as these keys are bound to useful -Dired functions, the trick can be accomplished via the following code: - -@example -(setq my-dired-vi-purist-map (make-sparse-keymap)) -(define-key my-dired-vi-purist-map "k" 'viper-previous-line) -(define-key my-dired-vi-purist-map "l" 'viper-forward-char) -(viper-modify-major-mode 'dired-mode 'emacs-state my-dired-vi-purist-map) -@end example - -Yet another way to customize key bindings in a major mode is to edit the -list @code{viper-major-mode-modifier-list} using the customization widget. -@vindex @code{viper-major-mode-modifier-list} -(This variable is in the Viper-misc customization group.) -The elements of this list are triples of the form: (major-mode viper-state -keymap), where the keymap contains bindings that are supposed to be active -in the given major mode and the given viper-state. - -Effects similar to key binding changes can be achieved by defining Vi -keyboard macros using the Ex commands @kbd{:map} and @kbd{:map!}. The -difference is that multi-key Vi macros do not override the keys they are -bound to, unless these keys are typed in quick succession. So, with macros, -one can use the normal keys alongside with the macros. If per-mode -modifications are needed, the user can try both ways and see which one is -more convenient. -@findex @kbd{:map} -@xref{Vi Macros}, for details. - -Note: in major modes that come up in @emph{Emacs state} by default, the -aforesaid modifications may not take place immediately (but only after the -buffer switches to some other Viper state and then back to Emacs state). To -avoid this, one should add @code{viper-change-state-to-emacs} to an -appropriate hook of that major mode. (Check the function -@code{viper-set-hooks} in @file{viper.el} for examples.) However, if you -did not set @code{viper-always} to @code{nil}, chances are that you won't -need to perform the above procedure, because Viper will take care of most -useful defaults. - - -Finally, Viper has a facility that lets the user define per-buffer -bindings, i.e., bindings that are in effect in some specific buffers -only. Unlike per-mode bindings described above, per-buffer bindings can be -defined based on considerations other than the major mode. This is done -via the function @code{viper-add-local-keys}, which lets one specify bindings -that should be in effect in the current buffer only and for a specific Viper -state. For instance, -@lisp -(viper-add-local-keys 'vi-state '(("ZZ" .@: TeX-command-master) - ("ZQ" .@: viper-save-kill-buffer))) -@end lisp -@noindent -redefines @kbd{ZZ} to invoke @code{TeX-command-master} in @code{vi-state} -and @kbd{ZQ} to save-then-kill the current buffer. These bindings take -effect only in the buffer where this command is executed. The typical use -of this function is to execute the above expression from within a function -that is included in a hook to some major mode. For instance, the above -expression -could be called from a function, @code{my-tex-init}, which may be added to -@code{tex-mode-hook} as follows: -@lisp -(add-hook 'tex-mode-hook 'my-tex-init) -@end lisp -@noindent -When TeX mode starts, the hook is executed and the above Lisp expression is -evaluated. Then, the bindings for @kbd{ZZ} and @kbd{ZQ} are changed in Vi -command mode for all buffers in TeX mode. - -Another useful application is to bind @kbd{ZZ} to @code{send-mail} -in the Mail mode buffers (the specifics of this depend on which mail -package you are using, @code{rmail}, @code{mh-e}, @code{vm}, etc. -For instance, here is how to do this for @code{mh-e}, the Emacs interface -to MH: -@lisp -(defun mh-add-vi-keys () - "Set up ZZ for MH-e and XMH." - (viper-add-local-keys 'vi-state '(("ZZ" .@: mh-send-letter)))) -(add-hook 'mh-letter-mode-hook 'mh-add-vi-keys) -@end lisp - -You can also use @code{viper-add-local-keys} to set per buffer -bindings in Insert state and Emacs state by passing as a parameter the -symbols @code{insert-state} and @code{emacs-state}, respectively. -As with global bindings, customized local bindings done to Emacs state -are not inherited by Insert state. - -On rare occasions, local keys may be added by mistake. Usually this is done -indirectly, by invoking a major mode that adds local keys (e.g., -@code{shell-mode} redefines @key{RET}). In such a case, exiting the wrong -major mode won't rid you from unwanted local keys, since these keys are -local to Viper state and the current buffer, not to the major mode. -In such situations, the remedy is to type @kbd{M-x viper-zap-local-keys}. - -So much about Viper-specific bindings. -@xref{Customization,,Customization,emacs,The GNU Emacs -Manual}, and the Emacs quick reference card for the general info on key -bindings in Emacs. - -@vindex @code{input-decode-map} -@vindex @code{function-key-map} -@vindex @code{viper-vi-global-user-map} -@vindex @code{viper-insert-global-user-map} -@vindex @code{viper-emacs-global-user-map} -@findex @code{viper-add-local-keys} -@findex @code{viper-zap-local-keys} - -@node Packages that Change Keymaps,Viper Specials,Key Bindings,Customization -@subsection Packages that Change Keymaps -@cindex C-c and Viper -@cindex Viper and C-c - -Viper is designed to coexist with all major and minor modes of Emacs. This -means that bindings set by those modes are generally available with Viper -(unless you explicitly prohibit them by setting -@code{viper-want-emacs-keys-in-vi} and @code{viper-want-emacs-keys-in-insert} to -@code{nil}). -If @code{viper-always} is set to @code{t} (which is the default), Viper -will try to bring each buffer -in the Viper state that is most appropriate for that buffer. -Usually, this would be the Vi state, but sometimes it could be the Insert -state or the Emacs state. - -Some major mode bindings will necessarily be overwritten by Viper. Indeed, in -Vi state, most of the 1-character keys are used for Vi-style editing. This -usually causes no problems because most packages designed for editing files -typically do not bind such keys. Instead, they use key sequences that start -with @kbd{C-x} and @kbd{C-c}. This is why it was so important for us to -free up @kbd{C-x} and @kbd{C-c}. -It is common for language-specific major modes to bind @key{TAB} and -@kbd{C-j} (the line feed) keys to various formatting functions. This is -extremely useful, but may require some getting used to for a Vi user. If you -decide that this feature is not for you, you can re-bind these keys as -explained earlier (@pxref{Customization}). - -Binding for @key{TAB} is one of the most unusual aspects of Viper for many -novice users. In Emacs, @key{TAB} is used to format text and programs, and -is extremely useful. For instance, hitting @key{TAB} causes the current -line to be re-indented in accordance with the context. In programming, -this is very important, since improper automatic indentation would -immediately alert the programmer to a possible error. For instance, if a -@kbd{)} or a @kbd{"} is missing somewhere above the current -line, @key{TAB} is likely to mis-indent the line. - -For this reason, Viper doesn't change the standard Emacs binding of -@key{TAB}, thereby sacrificing Vi compatibility -(except for users at level 1). Instead, in Viper, the key -@kbd{S-tab} (shift+ tab) is chosen to emulate Vi's @key{TAB}. - -We should note that on some non-windowing terminals, Shift doesn't modify -the @key{TAB} key, so @kbd{S-tab} behaves as if it were @key{TAB}. In such -a case, you will have to bind @code{viper-insert-tab} to some other -convenient key. - -Some packages, notably Dired, Gnus, Info, etc., attach special meaning to -common keys like @key{SPC}, @kbd{x}, @kbd{d}, @kbd{v}, and others. This -means that Vi command state is inappropriate for working with these -packages. Fortunately, these modes operate on read-only buffers and are -designed not for editing files, but for special-purpose browsing, reading -news, mail, etc., and Vi commands are meaningless in these situations. For -this reason, Viper doesn't force Vi state on such major modes---it -brings them in Emacs state. You can switch to Vi state by typing @kbd{C-z} -if, for instance, you want to do Vi-style search in a buffer (although, -usually, incremental search, which is bound to @kbd{C-s}, is sufficient in -these situations). But you should then switch back to Emacs state if you -plan to continue using these major modes productively. You can also switch -to Vi temporarily, to execute just one command. This is done by typing -@kbd{C-c \}. (In some of these modes, @kbd{/} and @kbd{:} are bound -Vi-style, unless these keys perform essential duties.) - -If you would like certain major modes to come up in Emacs state rather than -Vi state (but Viper thinks otherwise), you should put these major modes -on the @code{viper-emacs-state-mode-list} list and delete them from -@code{viper-vi-state-mode-list}. -Likewise, you can force Viper's Insert state on a major mode by putting it -in @code{viper-insert-state-mode-list}. -@vindex @code{viper-emacs-state-mode-list} -@vindex @code{viper-insert-state-mode-list} -@vindex @code{viper-vi-state-mode-list} - -It is also possible to impose Vi on some major modes, even though they may -bind common keys to specialized commands. This might make sense for modes -that bind only a small number of common keys. For instance, Viper subverts -the Shell mode by changing the bindings for @kbd{C-m} and @kbd{C-d} using -@code{viper-add-local-keys} described in the section on customization -(@pxref{Customization}). - -In some cases, some @emph{minor} modes might override certain essential -bindings in Vi command state. This is not a big problem because this -can happen only in the beginning, when the minor mode kicks in. Typing -@code{M-x viper-mode} will correct the situation. Viper knows about -several such minor modes and takes care of them, so the above trick -is usually not necessary. If you find that some minor mode, e.g., -@code{nasty-mode} interferes with Viper, putting the following in -@file{.viper} should fix the problem: -@lisp -(viper-harness-minor-mode "nasty-mode") -@end lisp -@noindent -The argument to @code{viper-harness-minor-mode} is the name of the file for the -offending minor mode with the suffixes @file{.el} and @file{.elc} removed. - -It may not be always obvious which minor mode is at fault. The only -guidance here is to look into the file that defines the minor mode you are -suspecting, say @file{nasty-mode.el}, and see if it has a variable called -@code{nasty-mode-map}. Then check if there is a statement of the form -@lisp -(define-key nasty-mode-map key function) -@end lisp -@noindent -that binds the misbehaving -keys. If so, use the above line to harness @code{nasty-mode}. If your -suspicion is wrong, no harm is done if you harness a minor mode that -doesn't need to be harnessed. - -It is recommended to harness even those minor modes that don't override -Viper keys, but still have their own keymaps. A general way to -make a minor mode, @code{my-mode}, -compatible with Viper is to have the file @file{my-mode.el} include the following code: - -@lisp -(when (fboundp 'viper-harness-minor-mode) - (let ((lib (file-name-sans-extension - (file-name-nondirectory load-file-name)))) - (viper-harness-minor-mode lib))) -@end lisp - -@vindex @code{viper-want-emacs-keys-in-vi} -@vindex @code{viper-want-emacs-keys-in-insert} -@vindex @code{viper-always} -@findex @code{viper-set-hooks} -@findex @code{viper-mode} -@findex @code{viper-harness-minor-mode} -@findex @code{remove-hook} -@findex @code{add-hook} - -@node Viper Specials,Vi Macros,Packages that Change Keymaps,Customization -@section Viper Specials - -Viper extends Vi with a number of useful features. This includes various -search functions, histories of search strings, Ex commands, insertions, and -Vi's destructive commands. In addition, Viper supports file name completion -and history, completion of Ex commands and variables, and many other -features. Some of these features are explained in detail elsewhere in this -document. Other features are explained here. - -@table @code -@item (viper-buffer-search-enable) -@item viper-buffer-search-char nil -Enable buffer search. Explicit call to @code{viper-buffer-search-enable} -sets @code{viper-buffer-search-char} to @kbd{g}. Alternatively, the user can -set @code{viper-buffer-search-char} in @file{.viper} to a key sequence -to be used for buffer search. There is no need to call -@code{viper-buffer-search-enable} in that case. -@findex @code{viper-buffer-search-enable} -@vindex @code{viper-buffer-search-char} -@item viper-toggle-search-style -This function, bound to @kbd{C-c /}, lets one toggle case-sensitive and -case-insensitive search, and also switch between plain vanilla search and -search via regular expressions. Without the prefix argument, the user is -asked which mode to toggle. With prefix argument 1, this toggles -case-sensitivity. With prefix argument 2, regular expression/vanilla search -will be toggled. - -However, we found that the most convenient way to toggle -these options is to bind a Vi macro to -bind @kbd{//} to toggles case sensitivity and to @kbd{///} to toggles -vanilla search. Thus, quickly hitting @kbd{/} twice will switch Viper from -case sensitive search to case-insensitive. Repeating this once again will -restore the original state. Likewise, quickly hitting @kbd{/} three times -will switch you from vanilla-style search to search via regular expressions. -If you hit something other than @kbd{/} after the first @kbd{/} or if the -second @kbd{/} doesn't follow quickly enough, then Viper will issue the -usual prompt @kbd{/} and will wait for input, as usual in Vi. -If you don't like this behavior, you can ``unrecord'' these macros in your -@file{~/.viper} file. For instance, if you don't like the above feature, put -this in @file{~/.viper}: -@example -(viper-set-searchstyle-toggling-macros 'undefine) -@end example -@findex @code{viper-set-searchstyle-toggling-macros} - -If you don't like this feature as a default, but would still like to have -it in some major modes, you can do so by first unsetting it globally, as -shown above, and then setting it in the desired major modes as follows: -@example -(viper-set-searchstyle-toggling-macros nil 'c-mode) -(viper-set-searchstyle-toggling-macros nil 'lisp-mode) -@end example - -@item Vi-isms in Emacs state -Some people find it useful to use the Vi-style search key, `/', to invoke -search in modes which Viper leaves in emacs-state. These modes are: -@code{dired-mode}, @code{mh-folder-mode}, -@code{Info-mode}, and @code{Buffer-menu-mode} -(more may be added in the future). So, in the above modes, Viper binds `/' -so that it will behave Vi-style. Furthermore, in those major modes, Viper -binds `:' to invoke ex-style commands, like in vi-state. And, as described -above, `//' and `///' get bound to Vi-style macros that toggle -case-insensitivity and regexp-search. - -If you don't like these features---which I don't really understand---you -can unbind `/' and `:' in @code{viper-dired-modifier-map} (for Dired) or in -@code{viper-slash-and-colon-map}, for other modes. -@vindex @code{viper-slash-and-colon-map} -@vindex @code{viper-dired-modifier-map} - -To unbind the macros `//' and `///' for a major mode where you feel they -are undesirable, execute @code{viper-set-emacs-state-searchstyle-macros} with a -non-@code{nil} argument. This can be done either interactively, by supplying a -prefix argument, or by placing -@example -(viper-set-emacs-state-searchstyle-macros 'undefine) -@end example -@findex @code{viper-set-emacs-state-searchstyle-macros} -in the hook to the major mode (e.g., @code{dired-mode-hook}). -@xref{Vi Macros}, for more information on Vi macros. - -@item viper-heading-start -@item viper-heading-end -@cindex headings -@cindex sections -@cindex paragraphs -@cindex sentences -Regular Expressions for @kbd{[[} and @kbd{]]}. Note that Emacs defines -Regexps for paragraphs and sentences. @xref{Paragraphs,,Paragraphs and -Sentences,emacs,The GNU Emacs Manual}, for details. -@item M-x viper-set-expert-level -@findex @code{viper-set-expert-level} -Change your user level interactively. -@item viper-smart-suffix-list '("" "tex" "c" "cc" "el" "p") -@vindex @code{viper-smart-suffix-list} -Viper supports Emacs-style file completion when it prompts the user for a -file name. However, in many cases, the same directory may contain files -with identical prefix but different suffixes, e.g., prog.c, prog.o, -paper.tex, paper.dvi. In such cases, completion will stop at the `.'. -If the above variable is a list of strings representing suffixes, Viper will -try these suffixes -in the order listed and will check if the corresponding file exists. - -For instance, if completion stopped at `paper.'@: and the user typed -@key{RET}, -then Viper will check if the files `paper.', `paper.tex', `paper.c', etc., exist. -It will take the first such file. If no file exists, Viper will give a chance -to complete the file name by typing the appropriate suffix. If `paper.'@: was -the intended file name, hitting return will accept it. - -To turn this feature off, set the above variable to @code{nil}. - -@item viper-insertion-ring-size 14 -@vindex @code{viper-insertion-ring-size} -@cindex Insertion ring -Viper remembers what was previously inserted in Insert and Replace states. -Several such recent insertions are kept in a special ring of strings of size -@code{viper-insertion-ring-size}. -If you enter Insert or Replace state you can reinsert strings from this -ring by typing @kbd{C-c M-p} or @kbd{C-c M-n}. The former will search the -ring in -the direction of older insertions, and the latter will search in -the direction of newer insertions. Hitting @kbd{C-c M-p} or @kbd{C-c M-n} -in succession -will undo the previous insertion from the ring and insert the next item on -the ring. If a larger ring size is needed, change the value of the above -variable in the @file{~/.viper} file. - -Since typing these sequences of keys may be tedious, it is suggested that the -user should bind a function key, such as @kbd{f31}, as follows: -@example -(define-key viper-insert-global-user-map [f31] - 'viper-insert-prev-from-insertion-ring) -@end example -This binds @kbd{f31} (which is usually @kbd{R11} on a Sun workstation) -to the function that inserts the previous string in the insertion history. -To rotate the history in the opposite -direction, you can either bind an unused key to -@code{viper-insert-next-from-insertion-ring} or hit any digit (1 to 9) then -@kbd{f31}. - -One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since -this will interfere with the minibuffer histories and, possibly, other -major modes. - -@item viper-command-ring-size 14 -@vindex @code{viper-command-ring-size} -@cindex Destructive command ring -@cindex Destructive command history -Viper keeps track of the recent history of destructive -commands, such as @kbd{dw}, @kbd{i}, etc. -In Vi state, -the most recent command can be re-executed by hitting `@kbd{.}', as in Vi. -However, repeated typing @kbd{C-c M-p} will cause Viper to show the -previous destructive commands in the minibuffer. Subsequent hitting `@kbd{.}' -will execute the command that was displayed last. -The key @kbd{C-c M-n} will cycle through the command history in the -opposite direction. -Since typing @kbd{C-c M-p} may be tedious, it is more convenient to bind an -appropriate function to an unused function key on the keyboard and use that -key. For instance, the following -@example -(define-key viper-vi-global-user-map [f31] - 'viper-prev-destructive-command) -@end example -binds the key @kbd{f31} (which is usually @kbd{R11} on a Sun workstation) -to the function that searches the command history in the direction of older -commands. To search in the opposite -direction, you can either bind an unused key to -@code{viper-next-destructive-command} or hit any digit (1 to 9) then @kbd{f31}. - -One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since -this will interfere with the minibuffer histories and, possibly, other -major modes. - -@item viper-minibuffer-vi-face 'viper-minibuffer-vi-face -@item viper-minibuffer-insert-face 'viper-minibuffer-insert-face -@item viper-minibuffer-emacs-face 'viper-minibuffer-emacs-face -These faces control the appearance of the minibuffer text in the -corresponding Viper states. You can change the appearance of these faces -through Emacs's customization widget, which is accessible through the -menubar. - -Viper is located in this widget under the @emph{Emulations} customization -subgroup of the @emph{Editing} group. All Viper faces are grouped together -in Viper's @emph{Highlighting} customization subgroup. - -Note that only the text you type in is affected by the above faces. -Prompts and minibuffer messages are not affected. - -Purists who do not like adornments in the minibuffer can always zap them by -putting -@example -(copy-face 'default 'viper-minibuffer-vi-face) -(copy-face 'default 'viper-minibuffer-insert-face) -(copy-face 'default 'viper-minibuffer-emacs-face) -@end example -in the @file{~/.viper} file or through the customization widget, as -described above. However, in that case, the user will not have any -indication of the current Viper state in the minibuffer. (This is important -if the user accidentally switches to another Viper state by typing @key{ESC} or -@kbd{C-z}). -@item M-x viper-go-away -@findex @code{viper-go-away} -Make Viper disappear from the face of your running Emacs instance. If your -fingers start aching again, @kbd{M-x viper-mode} might save your day. -@item M-x toggle-viper-mode -@findex @code{toggle-viper-mode} -Toggle Viperization of Emacs on and off. -@end table - -@cindex Multifile documents and programs - -Viper provides some support for multi-file documents and programs. -If a document consists of several files we can designate one of them as a -master and put the following at the end of that file: -@lisp -;; Local Variables: -;; eval: (viper-setup-master-buffer "file1" "file2" "file3" "file4") -;; End: -@end lisp -@noindent -where @code{file1} to @code{file4} are names of files related to the master -file. Next time, when the master file is visited, the command -@code{viper-setup-master-buffer} will be evaluated and the above files will -be associated with the master file. Then, the new Ex command -@kbd{:RelatedFile} (abbr.@: @kbd{:R}) will display files 1 to 4 one after -another, so you can edit them. If a file is not in any Emacs buffer, it -will be visited. The command @kbd{PreviousRelatedFile} (abbr., @kbd{:P}) -goes through the file list in the opposite direction. -@findex @kbd{:RelatedFile} -@findex @kbd{:PreviousRelatedFile} - -These commands are akin to @kbd{:n} and @kbd{:N}, but they allow the user to -focus on relevant files only. - -Note that only the master file needs to have the aforementioned block of -commands. Also, ";;" above can be replaced by some other -markers. Semicolon is good for Lisp programs, since it is considered a -comment designator there. For LaTeX, this could be "%%%", and for C the -above block should be commented out. - -Even though these commands are sometimes useful, they are no substitute for -the powerful @emph{tag table} facility of Emacs. Viper's @kbd{:tag} command -in a primitive interface to Emacs tags. @xref{Tags,Tags,Tags,emacs, -The GNU Emacs Manual}, for more information on tags. - -The following two commands are normally bound to a mouse click and are part -of Viper. They work only if Emacs runs as an application under X -Windows (or under some other window system for which a port of GNU Emacs 20 -is available). Clicking the mouse when Emacs is invoked in an Xterm window -(using @code{emacs -nw}) will do no good. - -@table @code -@cindex mouse -@cindex mouse-search -@item viper-mouse-search-key (meta shift 1) -@vindex @code{viper-mouse-insert-key} -This variable controls the @emph{mouse-search} feature of Viper. The -default value -states that holding Meta and Shift keys while clicking mouse button 1 -should initiate search for a region under the mouse pointer (defined -below). This command can take a prefix argument, which indicates the -occurrence of the pattern to search for. - -Note: while loading initially, Viper binds this mouse action only if it is -not already bound to something else. If you want to use the mouse-search -feature, and the @kbd{Meta-Shift-Mouse-1} mouse action is already bound to -something else, you can rebind the mouse-search feature by setting -@code{viper-mouse-search-key} to something else in your @code{~/.viper} -file: -@lisp -(setq viper-mouse-search-key '(meta 1)) -@end lisp -This would bind mouse search to the action invoked by pressing the -Meta key and clicking mouse button 1. The allowed values of -@code{viper-mouse-search-key} are lists that contain a mouse-button number -(1,2, or 3) and any combination of the words `control', `meta', and -`shift'. - -If the requested mouse action (e.g., (meta 1)) is already taken for other -purposes then you have to confirm your intention by placing the following -command in @code{~/.viper} after setting @code{viper-mouse-search-key}: -@lisp -(viper-bind-mouse-search-key 'force) -@end lisp - -You can also change this setting interactively, through the customization -widget of Emacs (type @kbd{:customize}). - -The region that is chosen as a pattern to search for is determined as -follows. If search is invoked via a single click, Viper chooses the region -that lies between the beginning of the ``word'' under the pointer (``word'' -is understood in Vi sense) and the end of that word. The only difference -with Vi's words is that in Lisp major modes `-' is considered an -alphanumeric symbol. This is done for the convenience of working with Lisp -symbols, which often have an `-' in them. Also, if you click on a -non-alphanumeric character that is not a word separator (in Vi sense) then -this character will also be considered alphanumeric, provided that it is -adjacent (from either side) to an alphanumeric character. This useful -feature gives added control over the patterns selected by the mouse click. - -On a double-click, the region is determined by the beginning of the current -Vi's ``Word'' (i.e., the largest non-separator chunk of text) and the End -of that ``Word'' (as determined by the @kbd{E} command). - -On a triple-click, the region consists of the entire line where the click -occurred with all leading and trailing spaces and tabs removed. - -@cindex mouse-insert -@item viper-mouse-insert-key (meta shift 2) -@vindex @code{viper-mouse-insert-key} -This variable controls the @emph{mouse-insert} feature of Viper. -The above default value states that -holding Meta and Shift keys while clicking mouse button 2 -should insert the region surrounding the -mouse pointer. The rules defining this region are the same as for -mouse-search. This command takes an optional prefix argument, which -indicates how many such regions to snarf from the buffer and insert. (In -case of a triple-click, the prefix argument is ignored.) - -Note: while loading initially, Viper binds this mouse action only if it not -already bound to something else. If you want to use this feature and the -default mouse action is already bound, you can rebind mouse-insert by -placing this command in @code{~/.viper}: -@lisp -(setq viper-mouse-insert-key '(meta 2)) -@end lisp -If you want to bind mouse-insert to an action even if this action is -already taken for other purposes in Emacs, then you should add this command -to @code{~/.viper}, after setting @code{viper-mouse-insert-key}: -@lisp -(viper-bind-mouse-insert-key 'force) -@end lisp - -This value can also be changed via the Emacs customization widget at the -menubar. - -@item viper-multiclick-timeout -This variable controls the rate at which double-clicking must occur for the -purpose of mouse search and mouse insert. By default, this is set to -@code{double-click-time} in Emacs and to -@code{mouse-track-multi-click-time} milliseconds in XEmacs. -@end table -@kindex @kbd{S-Mouse-1} -@kindex @kbd{S-Mouse-2} -@kindex @kbd{meta shift button1up} -@kindex @kbd{meta shift button2up} -@vindex @code{viper-multiclick-timeout} -@findex @code{viper-mouse-click-insert-word} -@findex @code{viper-mouse-click-search-word} - -Note: The above functions search and insert in the selected window of -the latest active frame. This means that you can click in another window or -another frame and have search or insertion done in the frame and window you -just left. This lets one use these functions in a multi-frame -configuration. However, this may require some getting used to. For -instance, if you are typing in a frame, A, and then move the mouse to frame -B and click to invoke mouse search, search (or insertion) will be performed -in frame A. To perform search/insertion in frame B, you will first have to -shift focus there, which doesn't happen until you type a character or -perform some other action in frame B---mouse search doesn't shift focus. - -If you decide that you don't like the above feature and always want -search/insertion be performed in the frame where the click occurs, don't -bind (and unbind, if necessary) @code{viper-mouse-catch-frame-switch} from -the mouse event it is bound to. - -Mouse search is integrated with Vi-style search, so you can -repeat it with @kbd{n} and @kbd{N}. It should be also noted that, while -case-sensitivity of search in Viper is controlled by the variable -@code{viper-case-fold-search}, the case of mouse search is -controlled by the Emacs variable @code{case-fold-search}, which may be set -differently from @code{viper-case-fold-search}. Therefore, case-sensitivity -of mouse search may be different from that of the usual Vi-style search. - -Finally, if the way Viper determines the word to be searched for or to be -inserted is not what you want, there is a variable, -@code{viper-surrounding-word-function}, which can be changed to indicate -another function for snarfing words out of the buffer. The catch is that -you will then have to write such a function and make it known to your -Emacs. The function @code{viper-surrounding-word} in @file{viper.el} can be -used as a guiding example. - -@node Vi Macros, ,Viper Specials,Customization -@section Vi Macros - -@cindex Vi macros - -Viper supports much enhanced Vi-style macros and also facilitates the use -of Emacs-style macros. To define a temporary macro, it is generally more -convenient to use Emacs keyboard macro facility. Emacs keyboard macros are -usually defined anonymously, and the latest macro can be executed by typing -@kbd{C-x e} (or @kbd{*}, if Viper is in Vi state). If you need to use several -temporary macros, Viper lets you save them to a -register (a lowercase letter); such macros can then be executed by typing -@kbd{@@a} in Vi state (if a macro was previously saved in register -@kbd{a}). -@xref{Macros and Registers}, for details. - -If, however, you need to use a macro regularly, it must be given a -permanent name and saved. Emacs manual explains how to do this, but -invocation of named Emacs macros is quite different from Vi's. First, -invocation of permanent Emacs macros takes time because it requires typing -too many keys (to a Vi user's taste, anyway). -Second, binding such macros to function keys, for -fast access, hogs valuable real estate on the keyboard. - -Vi-style macros are better in that respect, since Vi lets the user overload -the meaning of key sequences: keys typed in fast succession are treated -specially, if this key sequence is bound to a macro. - -Viper provides Vi-style keyboard macros through the usual Ex commands, -@kbd{:map} and -@kbd{:map!}. These macros are much more powerful in Viper than -they are in the original Vi and in other emulators. This is because Viper -implements an enhanced vi-style -interface to the powerful Emacs keyboard macro facility. - -First, any Emacs -command can be executed while defining a macro, not just the Vi -commands. In particular, the user can invoke Emacs commands via @kbd{M-x -command-name} or by pressing various function keys on the keyboard. One -can even use the mouse, although this is usually not useful and is not -recommended (and macros defined with the use of the mouse cannot be saved in -command history and in the startup file, for future use). - -Macros defined by mixing Vi and Emacs commands are represented as -vectors. So, don't be confused when you see one (usually through the -history of Ex commands). For instance, if @kbd{gg} is defined by typing -@kbd{l}, the up-arrow key and @kbd{M-x next-line}, its definition will look -as follows in Emacs: - -@example -[l up (meta x) n e x t - l i n e return] -@end example - -Second, Viper macros are defined in a WYSIWYG style. This means that -commands are executed as you type them, so you can see precisely what is -being defined. Third, macros can be bound to arbitrary sequences of keys, -not just to printable keys. For instance, one can define a macro that will -be invoked by hitting @kbd{f3} then @kbd{f2} function keys. (The keys -@kbd{delete} and @kbd{backspace} are excluded; also, a macro invocation -sequence can't start with @key{ESC}. Some other keys, such as @kbd{f1} and -@kbd{help}, can't be bound to macros under Emacs, since they -are bound in @code{key-translation-map}, which overrides any other binding -the user gives to keys. In general, keys that have a binding in -@code{key-translation-map} can't be bound to a macro.) - -Fourth, in Viper, one can define macros that are specific to a given -buffer, a given major mode, or macros that are defined for all buffers. In -fact, the same macro name can have several different definitions: one -global, several definitions for various major modes, and -definitions for various specific buffers. Buffer-specific definitions -override mode-specific definitions, which, in turn, override global -definitions. - -As if all that is not enough, Viper (through its interface to Emacs -macros) lets the user define keyboard macros that ask for confirmation or -even prompt the user for input and then continue. To do this, one should -type @kbd{C-x q} (for confirmation) or @kbd{C-u C-x q} (for prompt). -For details, @pxref{Keyboard Macro Query,,Customization,emacs,The GNU Emacs -Manual} @refill - -When the user finishes defining a macro (which is done by typing @kbd{C-x)} --- -a departure from Vi), you will be asked whether you want this -macro to be global, mode-specific, or buffer-specific. You will also be -given a chance to save the macro in your @file{~/.viper} file. -This is the easiest way to save a macro and make -it permanently available. If you work your startup files with bare hands, -here is how Viper saves the above macro so that it will be -available in Viper's Insert state (and Replace state) in buffer @code{my-buf} -only: - -@example -(viper-record-kbd-macro "gg" 'insert-state - [l up (meta x) n e x t - l i n e return] - "my-buf") -@end example - -@noindent -To do the same for Vi state and all buffers with the major mode -@code{cc-mode}, use: - -@example -(viper-record-kbd-macro "gg" 'vi-state - [l up (meta x) n e x t - l i n e return] - 'cc-mode) -@end example - -@noindent -Both macro names and macro definitions are vectors of symbols that denote -keys on the keyboard. Some keys, like @kbd{\}, @kbd{ }, or digit-keys must -be escaped with a backslash. Modified keys are represented as lists. For -instance, holding Meta and Control and pressing @kbd{f4} is represented as -@kbd{(control meta f4)}. -If all members of a vectors are printable characters (or sequences, such as -@kbd{\e}, @kbd{\t}, for @key{ESC} and @key{TAB}), then they can also be represented as -strings: - -@example -(viper-record-kbd-macro "aa" 'vi-state "aaa\e" "my-buffer") -@end example - -@noindent -Thus, typing @kbd{aa} fast in Vi state will switch Viper to Insert state -(due to the first @kbd{a}), insert @kbd{aa}, and then it will switch back to Vi -state. All this will take effect only in the buffer named @code{my-buffer}. - -Note that the last argument to @code{viper-record-kbd-macro} must be either a -string (a buffer name), a symbol representing a major mode, or @code{t}; -the latter says that the macro is to be defined for all buffers -(which is how macros are defined in original Vi). - -For convenience, Viper also lets you define Vi-style macros in its Emacs -state. There is no Ex command, like @kbd{:map} and @kbd{:map!} for doing -this, but the user can include such a macro in the @file{~/.viper} file. The -only thing is that the @code{viper-record-kbd-macro} command should specify -@code{emacs-state} instead of @code{vi-state} or @code{insert-state}. - -The user can get rid of a macro either by using the Ex commands @kbd{:unmap} -and @kbd{:unmap!} or by issuing a call to @code{viper-unrecord-kbd-macro}. -The latter is more powerful, since it can delete macros even in -@code{emacs-state}. However, @code{viper-unrecord-kbd-macro} is usually -needed only when the user needs to get rid of the macros that are already -predefined in Viper. -The syntax is: -@findex @code{viper-unrecord-kbd-macro} -@example -(viper-unrecord-kbd-macro macro state) -@end example -@noindent -The second argument must be @code{vi-state}, @code{insert-state}, or -@code{emacs-state}. The first argument is a name of a macro. To avoid -mistakes in specifying names of existing macros, type @kbd{M-x -viper-describe-kbd-macros} and use a name from the list displayed by this -command. - -If an error occurs during macro definition, Emacs -aborts the process, and it must be repeated. This is analogous to Vi, -except that in Vi the user doesn't know there is an error until the macro is -actually run. All that means that in order for a definition to be -successful, the user must do some simple planning of the process in -advance, to avoid errors. For instance, if you want to map @kbd{gg} to -@kbd{llll} in Vi state, you must make sure that there is enough room on the -current line. Since @kbd{l} moves the cursor forward, it may signal an -error on reaching the end of line, which will abort the definition. - -These precautions are necessary only when defining macros; they will help -avoid the need to redo the job. When macros are actually run, an error -during the execution will simply terminate the current execution -(but the macro will remain mapped). - -A macro name can be a string of characters or a vector of keys. -The latter makes it possible to define macros bound to, say, double-hits -on a function key, such as @kbd{up} or @kbd{f13}. -This is very useful if you run out of function keys on your keyboard; it -makes Viper macro facility a @emph{keyboard doubler}, so to speak. - -Elsewhere (@xref{Key Bindings}, for details), we review -the standard Emacs mechanism for binding function keys to commands. -For instance, - -@example -(global-set-key [f13] 'repeat-complex-command) -@end example - -@noindent -binds the key f13 to the Emacs function that repeats the last minibuffer -command. Under Viper, however, you may still use this key for additional -purposes, if you bind, say, a double-hitting action for that key to some -other function. Emacs doesn't allow the user to do that, but Viper does -this through its keyboard macro facility. To do this, type @kbd{:map } -first. When you are asked to enter a macro name, hit f13 twice, followed by -@key{RET} or @key{SPC}. - -Emacs will now start the mapping process by actually executing -Vi and Emacs commands, so that you could see what will happen each time the -macro is executed. Suppose now we wanted to bind the key sequence -@kbd{f13 f13} to the command @code{eval-last-sexp}. To accomplish this, we -can type @kbd{M-x eval-last-sexp} followed by @kbd{C-x )}. -If you answer positively to Viper's offer to save this macro in @file{~/.viper} -for future uses, the following will be inserted in that file: - -@example -(viper-record-kbd-macro [f16 f16] 'vi-state - [(meta x) e v a l - l a s t - s e x p] - 'lisp-interaction-mode) -@end example - -To illustrate the above point, Viper provides two canned macros, which, by -default, are bound to @kbd{[f12 \1]} and @kbd{[f12 \2]} (invoked by typing -@kbd{f12} then @kbd{1} and @kbd{2}, respectively). These macros are useful -shortcuts to Viper's command ring history. The first macro will execute the -second-last destructive command (the last one is executed by @kbd{.}, as -usual). The second macro executes the third-last command. - -If you need to go deeper into the command history, you will have to use -other commands, as described earlier in this section; or you can bind, -say, @kbd{f12 \3} like this: - -@example -(viper-record-kbd-macro [f12 \3] 'vi-state - [(meta x) r e p e a t - f r o m - h i s t o r y] - t) -@end example - - -Note that even though the macro uses the function key @kbd{f12}, the key is -actually free and can still be bound to some Emacs function via -@code{define-key} or @code{global-set-key}. - - -Viper allows the user to define macro names that are prefixes of other macros. -For instance, one can define @kbd{[[} and @kbd{[[[[} to be macros. -If you type the exact sequence of such keys and then pause, Viper will -execute the right macro. However, if you don't pause and, say, type -@kbd{[[[[text} then the conflict is resolved as follows. If only one of the -key sequences, @kbd{[[} or @kbd{[[[[} has a definition applicable to the -current buffer, then, in fact, there is no conflict and the right macro -will be chosen. If both have applicable definitions, then the first one -found will be executed. Usually this is the macro with a shorter name. So, -in our case, @kbd{[[[[text} will cause the macro @kbd{[[} to be executed -twice and then the remaining keys, @kbd{t e x t}, will be processed. - -When defining macros using @kbd{:map} or @kbd{:map!}, the user enters -the actually keys to be used to invoke the macro. For instance, you -should hit the actual key @kbd{f6} if it is to be part of a macro -name; you do @emph{not} write @kbd{f 6}. When entering keys, Viper -displays them as strings or vectors (e.g., @code{"abc"} or @code{[f6 -f7 a]}). The same holds for unmapping. Hitting @key{TAB} while -typing a macro name in the @kbd{:unmap} or @kbd{:unmap!} command will -cause name completion. Completions are displayed as strings or -vectors. However, as before, you don't actually type @samp{"}, -@samp{[}, or @samp{]} that appear in the completions. These are -meta-symbols that indicate whether the corresponding macro name is a -vector or a string. - -One last difference from Vi: Vi-style keyboard macros cannot be defined in -terms of other Vi-style keyboard macros (but named Emacs macros are OK). -More precisely, while defining or executing a macro, the special meaning -of key sequences (as Vi macros) is ignored. -This is because it is all too easy to create an infinite loop in this way. -Since Viper macros are much more powerful than Vi's it is impossible to -detect such loops. In practice, this is not really a limitation but, -rather, a feature. - -We should also note that Vi macros are disabled in the minibuffer, which -helps keep some potential troubles away. - -The rate at which the user must type keys in order for them to be -recognized as a timeout macro is controlled by the variable -@code{viper-fast-keyseq-timeout}, which defaults to 200 milliseconds. - -For the most part, Viper macros defined in @file{~/.viper} can be shared -between X and TTY modes. -The problem with TTY may be that the function keys there generate sequences -of events instead of a single event (as under a window system). -Emacs maps some of these sequences back to the logical keys -(e.g., the sequences generated by the arrow keys are mapped to @kbd{up}, -@kbd{left}, etc.). However, not all function keys are mapped in this way. -Macros that are bound to key sequences that contain such unmapped function -keys have to be redefined for TTY's (and possibly for every type of TTY you -may be using). To do this, start Emacs on an appropriate TTY device and -define the macro using @kbd{:map}, as usual. - -@findex @code{viper-describe-kbd-macros} -Finally, Viper provides a function that conveniently displays all macros -currently defined. To see all macros along with their definitions, type -@kbd{M-x viper-describe-kbd-macros}. - -@node Commands,,Customization,Top -@chapter Commands - -This section is a semi-automatically bowdlerized version of the Vi -reference created by @* @samp{maart@@cs.vu.nl} and others. It can be -found on the Vi archives. This reference has been adapted for Viper.@refill - -@menu -* Groundwork:: Textual Conventions and Viper basics -* Text Handling:: Moving, Editing, Undoing. -* Display:: Scrolling. -* File and Buffer Handling:: Editing, Writing and Quitting. -* Mapping:: Mapping Keys, Keyboard Macros -* Shell Commands:: Accessing Shell Commands, Processing Text -* Options:: Ex options, the @kbd{:set} commands -* Emacs Related Commands:: Meta Keys, Windows -* Mouse-bound Commands:: Search and insertion of text -@end menu - -@node Groundwork, Text Handling, Commands, Commands -@comment node-name, next, previous, up -@section Groundwork - -The VI command set is based on the idea of combining motion commands -with other commands. The motion command is used as a text region -specifier for other commands. -We classify motion commands into @dfn{point commands} and -@dfn{line commands}.@refill - -@cindex point commands - -The point commands are: - -@quotation -@kbd{h}, @kbd{l}, @kbd{0}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, -@kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, -@kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^} -@end quotation - -@cindex line commands - -The line commands are: - -@quotation -@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, -@kbd{@}}, @kbd{G}, @kbd{'}, @kbd{[[}, @kbd{]]}, @kbd{[]} -@end quotation -@noindent - -Text Deletion Commands (@pxref{Deleting Text}), Change commands -(@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands}) -use these commands to describe a region of text to operate on. - -@cindex r and R region specifiers - -Viper adds two region descriptors, @kbd{r} and @kbd{R}. These describe -the Emacs regions (@pxref{Basics}), but they are not movement commands. - -The command description uses angle brackets @samp{<>} to indicate -metasyntactic variables, since the normal conventions of using simple -text can be confusing with Viper where the commands themselves are -characters. Watch out where @kbd{<} shift commands and @kbd{} are -mentioned together!!! - -@kindex -@kindex -@kindex
-@cindex -@cindex -@cindex
-@cindex movements - -@samp{} refers to the above movement commands, and @samp{} -refers to registers or textmarkers from @samp{a} to @samp{z}. Note -that the @samp{} is described by full move commands, that is to -say they will take counts, and otherwise behave like normal move commands. -@cindex Ex addresses -@samp{
} refers to Ex line addresses, which include - -@table @kbd -@item .@: -Current line -@item .+n .-n -Add or subtract for current line -@item number -Actual line number, use @kbd{.=} to get the line number -@item ' -Textmarker -@item $ -Last line -@item x,y -Where x and y are one of the above -@item % -@cindex % (Ex address) -For the whole file, same as (1,$). -@item // -@itemx ?? -Next or previous line with pattern . - -Note that the pattern is allowed to contain newline character (inserted as -@kbd{C-qC-j}). Therefore, one can search for patterns that span several -lines. -@end table - -@cindex % (Current file) -Note that @samp{%} is used in Ex commands @kbd{:e} and @kbd{:r } -to mean current file. If you want a @samp{%} in your command, it must be -escaped as @samp{\%}. Note that @kbd{:w} and the regular @kbd{:r } -command doesn't support the meta symbols @samp{%} and @samp{#}, because -file history is a better mechanism. -@cindex # (Previous file) -Similarly, @samp{#} expands to the previous file. The previous file is -the first file in @kbd{:args} listing. This defaults to previous window -in the VI sense if you have one window only. - -@kindex -@kindex -@cindex -@cindex -@noindent -Others like @samp{ -- arguments}, @samp{ -- command} etc. -should be fairly obvious. - -@noindent -Common characters referred to include: - -@table @kbd -@item -Space -@item -Tab -@item -Linefeed -@item -Escape -@item -Return, Enter -@end table -@cindex -@cindex -@cindex -@cindex -@cindex - -@cindex words -@cindex WORDS -@cindex char -@cindex CHAR - -We also use @samp{word} for alphanumeric/non-alphanumeric words, and -@samp{WORD} for whitespace delimited words. @samp{char} refers to any -@acronym{ASCII} character, @samp{CHAR} to non-whitespace character. -Brackets @samp{[]} indicate optional parameters; @samp{} also -optional, usually defaulting to 1. Brackets are elided for -@samp{} to eschew obfuscation. - -Viper's idea of Vi's words is slightly different from Vi. First, Viper -words understand Emacs symbol tables. Therefore, all symbols declared to be -alphanumeric in a symbol table can automatically be made part of the Viper -word. This is useful when, for instance, editing text containing European, -Cyrillic, Japanese, etc., texts. - -Second, Viper lets you depart from Vi's idea of a word by changing the a -syntax preference via the customization widget (the variable -@code{viper-syntax-preference}) or by executing -@code{viper-set-syntax-preference} interactively. - -By default, Viper syntax preference is @code{reformed-vi}, which means that -Viper considers only those symbols to be part of a word that are specified -as word-symbols by the current Emacs syntax table (which may be different -for different major modes) plus the underscore symbol @kbd{_}, minus the -symbols that are not considered words in Vi (e.g., `,',;, etc.), but may be -considered as word-symbols by various Emacs major modes. Reformed-Vi works -very close to Vi, and it also recognizes words in other -alphabets. Therefore, this is the most appropriate mode for editing text -and is likely to fit all your needs. - -You can also set Viper syntax preference to @code{strict-vi}, which would -cause Viper to view all non-English letters as non-word-symbols. - -You can also specify @code{emacs} as your preference, which would -make Viper use exactly the same notion of a word as Emacs does. In -particular, the underscore may not be part of a word in some major modes. - -Finally, if @code{viper-syntax-preference} is set to @code{extended}, Viper -words would consist of characters that are classified as alphanumeric -@emph{or} as parts of symbols. This is convenient for editing programs. - -@code{viper-syntax-preference} is a local variable, so it can have different -values for different major modes. For instance, in programming modes it can -have the value @code{extended}. In text modes where words contain special -characters, such as European (non-English) letters, Cyrillic letters, etc., -the value can be @code{reformed-vi} or @code{emacs}. -If you consider using different syntactic preferences for different major -modes, you should execute, for example, - -@example -(viper-set-syntax-preference nil "extended") -@end example - -in the appropriate major mode hooks. - -@vindex @code{viper-syntax-preference} -@findex @code{viper-set-syntax-preference} -@cindex syntax table - - - -The above discussion concerns only the movement commands. In regular -expressions, words remain the same as in Emacs. That is, the expressions -@code{\w}, @code{\>}, @code{\<}, etc., use Emacs's idea of what is a word, -and they don't look into the value of variable -@code{viper-syntax-preference}. This is because Viper avoids changing -syntax tables in order to not thwart the various major modes that set these -tables. - -The usual Emacs convention is used to indicate Control Characters, i.e -C-h for Control-h. @emph{Do not confuse this with a sequence of separate -characters -C, -, h!!!} The @kbd{^} is itself, never used to indicate a -Control character. - -Finally, we note that Viper's Ex-style commands can be made to work on the -current Emacs region. This is done by typing a digit argument before -@kbd{:}. For instance, typing @kbd{1:} will prompt you with something like -@emph{:123,135}, assuming that the current region starts at line 123 and -ends at line 135. There is no need to type the line numbers, since Viper -inserts them automatically in front of the Ex command. -@cindex Ex commands - -@node Text Handling, Display, Groundwork, Commands -@section Text Handling - -@menu -* Move Commands:: Moving, Searching -* Marking:: Textmarkers in Viper and the Emacs Mark. -* Appending Text:: Text insertion, Shifting, Putting -* Editing in Insert State:: Autoindent, Quoting etc. -* Deleting Text:: Deleting -* Changing Text:: Changing, Replacement, Joining -* Search and Replace:: Searches, Query Replace, Pattern Commands -* Yanking:: Yanking, Viewing Registers -* Undoing:: Multiple Undo, Backups -@end menu - -@node Move Commands,Marking,,Text Handling -@subsection Move Commands - -@cindex movement commands -@cindex searching -@cindex textmarkers -@cindex markers -@cindex column movement -@cindex paragraphs -@cindex headings -@cindex sections -@cindex sentences -@cindex matching parens -@cindex paren matching - -@table @kbd -@item h C-h - chars to the left. -@item j C-n - lines downward. -@item l - chars to the right. -@item k C-p - lines upward. -@item $ -To the end of line from the cursor. -@item ^ -To the first CHAR - 1 lines lower. -@item - -To the first CHAR lines higher. -@item + -To the first CHAR lines lower. -@item 0 -To the first char of the line. -@item | -To column -@item f - s to the right (find). -@item t -Till before s to the right. -@item F - s to the left. -@item T -Till after s to the left. -@item ; -Repeat latest @kbd{f t F T} times. -@item , -Repeat latest @kbd{f t F T} - times in opposite direction. -@item w - words forward. -@item W - WORDS forward. -@item b - words backward. -@item B - WORDS backward. -@item e -To the end of word forward. -@item E -To the end of WORD forward. -@item G -Go to line (default end-of-file). -@item H -To line from top of the screen (home). -@item L -To line from bottom of the screen (last). -@item M -To the middle line of the screen. -@item ) - sentences forward. -@item ( - sentences backward. -@item @} - paragraphs forward. -@item @{ - paragraphs backward. -@item ]] -To the th heading. -@item [[ -To the th previous heading. -@item [] -To the end of th heading. -@item m -Mark the cursor position with a letter. -@item ` -To the mark. -@item ' -To the first CHAR of the line with the mark. -@item [ -Show contents of textmarker. -@item ] -Show contents of register. -@item `` -To the cursor position before the latest absolute -jump (of which are examples @kbd{/} and @kbd{G}). -@item '' -To the first CHAR of the line on which the cursor -was placed before the latest absolute jump. -@item / -To the th occurrence of . -@item / -To the th occurrence of from previous @kbd{/ or ?}. -@item ? -To the th previous occurrence of . -@item ? -To the th previous occurrence of from previous @kbd{?@: or /}. -@item n -Repeat latest @kbd{/} @kbd{?} (next). -@item N -Repeat latest search in opposite direction. -@item C-c / -Without a prefix argument, this command toggles -case-sensitive/case-insensitive search modes and plain vanilla/regular -expression search. With the prefix argument 1, i.e., -@kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2, -toggles plain vanilla search and search using -regular expressions. @xref{Viper Specials}, for alternative ways to invoke -this function. -@cindex vanilla search -@cindex case-sensitive search -@cindex case-insensitive search -@item % -Find the next bracket/parenthesis/brace and go to its match. -By default, Viper ignores brackets/parentheses/braces that occur inside -parentheses. You can change this by setting -@code{viper-parse-sexp-ignore-comments} to @code{nil} in your @file{.viper} file. -This option can also be toggled interactively if you quickly hit @kbd{%%%}. - -This latter feature is implemented as a vi-style keyboard macro. If you -don't want this macro, put - -@example -(viper-set-parsing-style-toggling-macro 'undefine) -@end example -@findex @code{viper-set-parsing-style-toggling-macro} - -in your @file{~/.viper} file. - -@end table -@kindex @kbd{%} -@kindex @kbd{C-c /} -@kindex @kbd{N} -@kindex @kbd{n} -@kindex @kbd{?} -@kindex @kbd{/} -@kindex @kbd{?} -@kindex @kbd{/} -@kindex @kbd{''} -@kindex @kbd{``} -@kindex @kbd{]} -@kindex @kbd{[} -@kindex @kbd{'} -@kindex @kbd{`} -@kindex @kbd{m} -@kindex @kbd{[]} -@kindex @kbd{[[} -@kindex @kbd{]]} -@kindex @kbd{@{} -@kindex @kbd{@}} -@kindex @kbd{(} -@kindex @kbd{)} -@kindex @kbd{M} -@kindex @kbd{L} -@kindex @kbd{H} -@kindex @kbd{G} -@kindex @kbd{E} -@kindex @kbd{e} -@kindex @kbd{B} -@kindex @kbd{b} -@kindex @kbd{W} -@kindex @kbd{w} -@kindex @kbd{,} -@kindex @kbd{;} -@kindex @kbd{T} -@kindex @kbd{F} -@kindex @kbd{t} -@kindex @kbd{f} -@kindex @kbd{|} -@kindex @kbd{0} -@kindex @kbd{} -@kindex @kbd{+} -@kindex @kbd{-} -@kindex @kbd{^} -@kindex @kbd{$} -@kindex @kbd{C-p} -@kindex @kbd{} -@kindex @kbd{} -@kindex @kbd{C-n} -@kindex @kbd{C-h} -@kindex @kbd{h} -@kindex @kbd{j} -@kindex @kbd{k} -@kindex @kbd{l} -@vindex @code{viper-parse-sexp-ignore-comments} - -@node Marking,Appending Text,Move Commands,Text Handling -@subsection Marking - -Emacs mark is referred to in the region specifiers @kbd{r} and @kbd{R}. -@xref{Emacs Preliminaries}, and @xref{Basics}, for explanation. Also -see @ref{Mark,,Mark,emacs,The GNU Emacs manual}, for an explanation of -the Emacs mark ring. - -@cindex marking - -@table @kbd -@item m -Mark the current file and position with the specified letter. -@item m . -Set the Emacs mark (@pxref{Emacs Preliminaries}) at point. -@item m ^ -Set the Emacs mark (@pxref{Emacs Preliminaries}) back to where it was last -set with the @kbd{m.} command. This is useful when you set the mark with -@kbd{m.}, but then some other command (such as @kbd{L} or @kbd{G}) changes -it in a way that you didn't like. -@item m < -Set the Emacs mark at beginning of buffer. -@item m > -Set the Emacs mark at end of buffer. -@item m , -Jump to the Emacs mark. -@item :mark -Mark position with text marker named . This is an Ex command. -@item :k -Same as @kbd{:mark}. -@item `` -Exchange point and mark. -@item '' -Exchange point and mark and go to the first CHAR on line. -@item ' -Go to specified Viper mark. -@item -Go to specified Viper mark and go to the first CHAR on line. -@end table -@kindex @kbd{m} -@kindex @kbd{m.} -@kindex @kbd{m>} -@kindex @kbd{m<} -@kindex @kbd{m,} -@kindex @kbd{m^} -@findex @kbd{:mark} -@findex @kbd{:k} -@kindex @kbd{''} -@kindex @kbd{``} -@kindex @kbd{`} -@kindex @kbd{'} - -@node Appending Text, Editing in Insert State, Marking,Text Handling -@subsection Appending Text - -@xref{Options}, to see how to change tab and shiftwidth size. See the GNU -Emacs manual, or try @kbd{C-ha tabs} (If you have turned Emacs help on). -Check out the variable @code{indent-tabs-mode} to put in just spaces. -Also see options for word-wrap. - -@cindex inserting -@cindex appending -@cindex paste -@cindex put - -@table @kbd -@item a - times after the cursor. -@item A - times at the end of line. -@item i - times before the cursor (insert). -@item I - times before the first CHAR of the line -@item o -On a new line below the current (open). -The count is only useful on a slow terminal. -@item O -On a new line above the current. -The count is only useful on a slow terminal. -@item > -Shift the lines described by one -shiftwidth to the right (layout!). -@item >> -Shift lines one shiftwidth to the right. -@item ["]p -Put the contents of the (default undo) buffer - times after the cursor. The register will -be automatically down-cased. -@item ["]P -Put the contents of the (default undo) buffer - times before the cursor. The register will -@item [ -Show contents of textmarker. -@item ] -Show contents of register. -@item . -Repeat previous command times. For destructive -commands as well as undo. -@item f1 1 and f1 2 -While @kbd{.} repeats the last destructive command, -these two macros repeat the second-last and the third-last destructive -commands. @xref{Vi Macros}, for more information on Vi macros. -@item C-c M-p and C-c M-n -In Vi state, -these commands help peruse the history of Vi's destructive commands. -Successive typing of @kbd{C-c M-p} causes Viper to search the history in -the direction -of older commands, while hitting @kbd{C-c M-n} does so in reverse -order. Each command in the history is displayed in the minibuffer. The -displayed command can -then be executed by typing `@kbd{.}'. - -Since typing the above sequences of keys may be tedious, the -functions doing the perusing can be bound to unused keyboard keys in the -@file{~/.viper} file. @xref{Viper Specials}, for details. -@end table -@kindex @kbd{C-c M-p} -@kindex @kbd{C-c M-n} -@kindex @kbd{.} -@kindex @kbd{]} -@kindex @kbd{[} -@kindex @kbd{P} -@kindex @kbd{p} -@kindex @kbd{"p} -@kindex @kbd{"P} -@kindex @kbd{>>} -@kindex @kbd{>} -@kindex @kbd{O} -@kindex @kbd{o} -@kindex @kbd{i} -@kindex @kbd{A} -@kindex @kbd{a} - -@node Editing in Insert State, Deleting Text, Appending Text,Text Handling -@subsection Editing in Insert State - -Minibuffer can be edited similarly to Insert state, and you can switch -between Insert/Replace/Vi states at will. -Some users prefer plain Emacs feel in the minibuffer. To this end, set -@var{viper-vi-style-in-minibuffer} to @code{nil}. - -@cindex Insert state - -@table @kbd -@item C-v -Deprive the next char of its special meaning (quoting). -@item C-h -One char back. -@item C-w -One word back. -@item C-u -Back to the begin of the change on the -current line. - -@end table -@kindex @kbd{C-u} -@kindex @kbd{C-w} -@kindex @kbd{C-v} - -@node Deleting Text, Changing Text, Editing in Insert State, Text Handling -@subsection Deleting Text - - -There is one difference in text deletion that you should be -aware of. This difference comes from Emacs and was adopted in Viper -because we find it very useful. In Vi, if you delete a line, say, and then -another line, these two deletions are separated and are put back -separately if you use the @samp{p} command. In Emacs (and Viper), successive -series of deletions that are @emph{not interrupted} by other commands are -lumped together, so the deleted text gets accumulated and can be put back -as one chunk. If you want to break a sequence of deletions so that the -newly deleted text could be put back separately from the previously deleted -text, you should perform a non-deleting action, e.g., move the cursor one -character in any direction. - -@cindex shifting text - -@table @kbd -@item x -Delete chars under and after the cursor. -@item X -Delete chars before the cursor. -@item d -Delete from point to endpoint of . -@item dd -Delete lines. -@item D -The rest of the line. -@item < -Shift the lines described by one -shiftwidth to the left (layout!). -@item << -Shift lines one shiftwidth to the left. -@end table -@kindex @kbd{<<} -@kindex @kbd{<} -@kindex @kbd{D} -@kindex @kbd{dd} -@kindex @kbd{d} -@kindex @kbd{X} -@kindex @kbd{x} - -@node Changing Text, Search and Replace, Deleting Text,Text Handling -@subsection Changing Text - -@cindex joining lines -@cindex changing case -@cindex quoting regions -@cindex substitution - -@table @kbd -@item r -Replace chars by - no . -@item R -Overwrite the rest of the line, -appending change @var{count - 1} times. -@item s -Substitute chars. -@item S -Change lines. -@item c -Change from begin to endpoint of . -@item cc -Change lines. -@item C -The rest of the line and - 1 next lines. -@item = -Reindent the region described by move. -@item ~ -Switch lower and upper cases. -@item J -Join lines (default 2). -@item :[x,y]s/// -Substitute (on lines x through y) the pattern - (default the last pattern) with . Useful -flags are @samp{g} for @samp{global} (i.e.@: change every -non-overlapping occurrence of ) and @samp{c} for -@samp{confirm} (type @samp{y} to confirm a particular -substitution, else @samp{n} ). Instead of @kbd{/} any -punctuation CHAR unequal to and can be used as -delimiter. - -In Emacs, @samp{\&} stands for the last matched expression, so -@kbd{s/[ab]+/\&\&/} will double the string matched by @kbd{[ab]}. -Viper doesn't treat @samp{&} specially, unlike Vi: use @samp{\&} instead. - -Viper does not parse search patterns and does not expand special symbols -found there (e.g., @samp{~} is not expanded to the result of the previous -substitution). - -Note: @emph{The newline character (inserted as @kbd{C-qC-j}) -can be used in }. -@item :[x,y]copy [z] -Copy text between @kbd{x} and @kbd{y} to the position after @kbd{z}. -@item :[x,y]t [z] -Same as @kbd{:copy}. -@item :[x,y]move [z] -Move text between @kbd{x} and @kbd{y} to the position after @kbd{z}. -@item & -Repeat latest Ex substitute command, e.g. -@kbd{:s/wrong/right}. -@item :x,yp -@itemx :g/Pat/p -@itemx :v/Pat/p -The above commands display certain buffer lines in a -temporary buffer. The first form above displays the buffer lines between -@kbd{x} and @kbd{y}. The second displays the lines of the buffer, which -match a given pattern. The third form displays the lines that do @emph{not} -match the given pattern. -@item #c -Change upper-case characters in the region to lower-case. -@item #C -Change lower-case characters in the region to upper-case. -@item #q -Insert specified string at the beginning of each line in the region -@item C-c M-p and C-c M-n -In Insert and Replace states, these keys are bound to commands that peruse -the history of the text -previously inserted in other insert or replace commands. By repeatedly typing -@kbd{C-c M-p} or @kbd{C-c M-n}, you will cause Viper to -insert these previously used strings one by one. -When a new string is inserted, the previous one is deleted. - -In Vi state, these keys are bound to functions that peruse the history of -destructive Vi commands. -@xref{Viper Specials}, for details. -@end table -@kindex @kbd{C-c M-p} -@kindex @kbd{C-c M-n} -@kindex @kbd{#q } -@kindex @kbd{#C} -@kindex @kbd{#c} -@kindex @kbd{&} -@kindex @kbd{\&} -@findex @kbd{:substitute///} -@findex @kbd{:s///} -@findex @kbd{:copy [z]} -@findex @kbd{:t [z]} -@findex @kbd{:move [z]} -@kindex @kbd{J} -@kindex @kbd{~} -@kindex @kbd{=} -@kindex @kbd{C} -@kindex @kbd{cc} -@kindex @kbd{c} -@kindex @kbd{S} -@kindex @kbd{s} -@kindex @kbd{R} -@kindex @kbd{r} - -@node Search and Replace, Yanking, Changing Text,Text Handling -@subsection Search and Replace - -@xref{Groundwork}, for Ex address syntax. @xref{Options}, to see how to -get literal (non-regular-expression) search and how to stop search from -wrapping around. - -@table @kbd -@item C-c / -Toggle case-sensitive search. With prefix argument, toggle vanilla/regular -expression search. -@item / -To the th occurrence of . - -Viper does not parse search patterns and does not expand special symbols -found there (e.g., @samp{~} is not expanded to the result of the previous -substitution). - -After typing @kbd{/} or @kbd{?} all the usual Emacs minibuffer commands, such as -@kbd{M-p} and @kbd{M-n} are available. In addition, typing @kbd{C-s} will -insert the last search string used by the Emacs incremental search command -(which is bound to @kbd{C-s} everywhere except in this case). - -@item ? -To the th previous occurrence of . -@item g -Search for the text described by move. (off by default) -@item n -Repeat latest @kbd{/} @kbd{?} (next). -@item N -Idem in opposite direction. -@item % -Find the next bracket and go to its match -@item :[x,y]g// -@cindex text processing -Search globally [from line x to y] for -and execute the Ex on each occurrence. -@item :[x,y]v// -Execute on the lines that don't match. -@item #g -Execute the last keyboard macro for each line in the region. -@xref{Macros and Registers}, for more info. -@item Q -Query Replace. -@item :ta -Search in the tags file where is defined (file, line), and go to it. -@item :[x,y]s/// -Substitute (on lines x through y) the pattern (default the last -pattern) with . Useful -flags are @samp{g} for @samp{global} (i.e.@: change every -non-overlapping occurrence of ) and @samp{c} for -@samp{confirm} (type @samp{y} to confirm a particular -substitution, else @samp{n}). Instead of @kbd{/} any -punctuation character other than and can be used as -delimiter. - -Note: @emph{The newline character (inserted as @kbd{C-qC-j}) -can be used in }. -@item & -Repeat latest Ex substitute command, e.g.@: @kbd{:s/wrong/right}. -@item :global // -@itemx :g // -Execute on all lines that match . -@item :vglobal // -@itemx :v // -Execute on all lines that do not match . -@end table -@kindex @kbd{&} -@findex @kbd{:substitute///} -@kindex @kbd{Q} -@kindex @kbd{#g} -@findex @kbd{:v} -@findex @kbd{:g} -@findex @kbd{:global} -@findex @kbd{:vglobal} -@findex @kbd{:tag } -@kindex @kbd{%} -@kindex @kbd{N} -@kindex @kbd{n} -@kindex @kbd{g} -@kindex @kbd{?} -@kindex @kbd{/} - -@node Yanking,Undoing,Search and Replace,Text Handling -@subsection Yanking - -@cindex cut and paste -@cindex paste - -@table @kbd -@item y -Yank from begin to endpoint of . -@item "y -Yank from begin to endpoint of to register. -@item "y -Yank from begin to endpoint of and append -to register. -@item yy - lines. -@item Y -Idem (should be equivalent to @kbd{y$} though). -@item m -Mark the cursor position with a letter. -@item [ -Show contents of textmarker. -@item ] -Show contents of register. -@item ["]p -Put the contents of the (default undo) buffer - times after the cursor. The register will -be automatically down-cased. -@item ["]P -Put the contents of the (default undo) buffer - times before the cursor. The register will -@end table -@kindex @kbd{P} -@kindex @kbd{p} -@kindex @kbd{"p} -@kindex @kbd{"P} -@kindex @kbd{]} -@kindex @kbd{[} -@kindex @kbd{m} -@kindex @kbd{Y} -@kindex @kbd{yy} -@kindex @kbd{"y} -@kindex @kbd{"y} -@kindex @kbd{y} -@kindex @kbd{yank} -@findex @kbd{:yank} - -@node Undoing,, Yanking,Text Handling -@subsection Undoing - -@cindex undo -@cindex backup files - -@table @kbd -@item u U -Undo the latest change. -@item . -Repeat undo. -@item :q! -Quit Vi without writing. -@item :e! -Re-edit a messed-up file. -@item :rec -Recover file from autosave. Viper also creates backup files -that have a @samp{~} appended to them. -@end table -@findex @kbd{:rec} -@findex @kbd{:e!} -@findex @kbd{:q!} -@kindex @kbd{.} -@kindex @kbd{U} -@kindex @kbd{u} - -@node Display, File and Buffer Handling, Text Handling, Commands -@section Display - -@cindex scrolling - -@table @kbd -@item C-g -At user level 1, -give file name, status, current line number -and relative position.@* -At user levels 2 and higher, abort the current command. -@item C-c g -Give file name, status, current line number and relative position -- all -user levels. -@item C-l -Refresh the screen. -@item C-e -Expose more lines at bottom, cursor stays put (if possible). -@item C-y -Expose more lines at top, cursor stays put (if possible). -@item C-d -Scroll lines downward (default the number of the previous scroll; -initialization: half a page). -@item C-u -Scroll lines upward (default the number of the previous scroll; -initialization: half a page). -@item C-f - pages forward. -@item C-b - pages backward (in older versions @kbd{C-b} only works without count). -@item z -@item zH -Put line at the top of the window (default the current line). -@item z- -@item zL -Put line at the bottom of the window -(default the current line). -@item z. -@item zM -Put line in the center of the window -(default the current line). -@end table -@kindex @kbd{zM} -@kindex @kbd{zL} -@kindex @kbd{zH} -@kindex @kbd{z} -@kindex @kbd{z.} -@kindex @kbd{z-} -@kindex @kbd{z} -@kindex @kbd{C-b} -@kindex @kbd{C-f} -@kindex @kbd{C-u} -@kindex @kbd{C-d} -@kindex @kbd{C-y} -@kindex @kbd{C-e} -@kindex @kbd{C-l} -@kindex @kbd{C-g} - - -@node File and Buffer Handling, Mapping, Display,Commands -@section File and Buffer Handling - -@cindex multiple files - -In all file handling commands, space should be typed before entering the file -name. If you need to type a modifier, such as @kbd{>>} or @kbd{!}, don't -put any space between the command and the modifier. - -Note that many Ex commands, e.g., @kbd{:w}, accept command arguments. The -effect is that the command would start acting on the current region. For -instance, if the current region spans the lines 11 through 22, then if you -type @kbd{1:w} you would see @samp{:11,22w} in the minibuffer. - -@table @kbd -@item :q -Quit buffer except if modified. -@item :q! -Quit buffer without checking. In Viper, these two commands -are identical. Confirmation is required if exiting modified buffers that -visit files. -@item :suspend -@item :stop -Suspend Viper -@item :[x,y] w -Write the file. Viper makes sure that a final newline is always added to -any file where this newline is missing. This is done by setting Emacs -variable @code{require-final-newline} to @code{t}. If you don't like this -feature, use @code{setq-default} to set @code{require-final-newline} to -@code{nil}. This must be done in @file{.viper} file. -@item :[x,y] w -Write to the file . -@item :[x,y] w>> -Append the buffer to the file . There should be no space between -@kbd{w} and @kbd{>>}. Type space after the @kbd{>>} and see what happens. -@item :w!@: -Overwrite the file . In Viper, @kbd{:w} and @kbd{:w!} are identical. -Confirmation is required for writing to an existing file (if this is not -the file the buffer is visiting) or to a read-only file. -@item :x,y w -Write lines x through y to the file . -@item :wq -Write the file and kill buffer. -@item :r [ ...] -Read file into a buffer, inserting its contents after the current line. -@item :xit -Same as @kbd{:wq}. -@item :Write -@itemx :W -Save all unsaved buffers, asking for confirmation. -@item :WWrite -@itemx :WW -Like @kbd{W}, but without asking for confirmation. -@item ZZ -Save current buffer and kill it. If user level is 1, then save all files -and kill Emacs. Killing Emacs is the wrong way to use it, so you should -switch to higher user levels as soon as possible. -@item :x [] -Save and kill buffer. -@item :x!@: [] -@kbd{:w![]} and @kbd{:q}. -@item :pre -Preserve the file -- autosave buffers. -@item :rec -Recover file from autosave. -@item :f [] -without the argument, prints file name and character/line information afout -the currently visited file. With an argument, sets the currently visited -filename to @file{file}. -@item :cd [] -Set the working directory to (default home directory). -@item :pwd -Print present working directory. -@item :e [+] -Edit files. If no filename is given, edit the file visited by the current -buffer. If buffer was modified or the file changed on disk, ask for -confirmation. Unlike Vi, Viper allows @kbd{:e} to take multiple arguments. -The first file is edited the same way as in Vi. The rest are visited -in the usual Emacs way. -@item :e!@: [+] -Re-edit file. If no filename, re-edit current file. -In Viper, unlike Vi, @kbd{e!} is identical to @kbd{:e}. In both cases, the -user is asked to confirm if there is a danger of discarding changes to a -buffer. -@item :q! -Quit Vi without writing. -@item C-^ -Edit the alternate (normally the previous) file. -@item :rew -Obsolete -@item :args -List files not shown anywhere with counts for next -@item :n [count] [+] [] -Edit file, or edit files. The count comes from @kbd{:args}. -@item :N [count] [+] [] -Like @kbd{:n}, but the meaning of the variable -@var{ex-cycle-other-window} is reversed. -@item :b -Switch to another buffer. If @var{ex-cycle-other-window} is @code{t}, -switch in another window. Buffer completion is supported. -The variable @var{viper-read-buffer-function} controls which function is -actually used to read the buffer name. The default is @code{read-buffer}, -but better alternatives are also available in Emacs (e.g., -@code{iswitchb-read-buffer}). -@vindex @var{viper-read-buffer-function} -@item :B -Like @kbd{:b}, but the meaning of @var{ex-cycle-other-window} is reversed. -@item :
r -Read the file into the buffer after the line
. -@item v, V, C-v -Edit a file in current or another window, or in another frame. File name -is typed in minibuffer. File completion and history are supported. -@end table -@kindex @kbd{v} -@kindex @kbd{V} -@findex @kbd{:args} -@findex @kbd{:rew} -@kindex @kbd{C-^} -@findex @kbd{:e!@: []} -@findex @kbd{:e []} -@findex @kbd{:edit []} -@findex @kbd{:edit!@: []} -@findex @kbd{:q!} -@findex @kbd{:q} -@findex @kbd{:quit} -@findex @kbd{:quit!} -@findex @kbd{:f} -@findex @kbd{:rec} -@findex @kbd{:r} -@findex @kbd{:read} -@findex @kbd{:pre} -@kindex @kbd{ZZ} -@findex @kbd{:wq} -@findex @kbd{:w } -@findex @kbd{:w!@: } -@findex @kbd{:w >> } -@findex @kbd{:write } -@findex @kbd{:write!@: } -@findex @kbd{:write >> } -@findex @kbd{:W} -@findex @kbd{:WW} -@findex @kbd{:Write} -@findex @kbd{:WWrite} -@findex @kbd{:WWrite} -@findex @kbd{:x} -@findex @kbd{:x!} -@findex @kbd{:suspend} -@findex @kbd{:stop} -@findex @kbd{:n [ | ]} -@findex @kbd{:cd []} -@findex @kbd{:pwd} - -@node Mapping, Shell Commands, File and Buffer Handling, Commands -@section Mapping - -@cindex key bindings -@cindex key mapping - -@table @kbd -@item :map -Start defining a Vi-style keyboard macro. -For instance, typing -@kbd{:map www} followed by @kbd{:!wc %} and then typing @kbd{C-x )} -will cause @kbd{www} to run wc on -current file (Vi replaces @samp{%} with the current file name). -@item C-x ) -Finish defining a keyboard macro. -In Viper, this command completes the process of defining all keyboard -macros, whether they are Emacs-style or Vi-style. -This is a departure from Vi, needed to allow WYSIWYG mapping of -keyboard macros and to permit the use of function keys and arbitrary Emacs -functions in the macros. -@item :unmap -Deprive of its mappings in Vi state. -@item :map!@: -Map a macro for Insert state. -@item :unmap!@: -Deprive of its mapping in Insert state (see @kbd{:unmap}). -@item @@ -In Vi state, -execute the contents of register as a command. -@item @@@@ -In Vi state, -repeat last register command. -@item @@# -In Vi state, -begin keyboard macro. End with @@. This will -put the macro in the proper register. Register will -be automatically down-cased. -@xref{Macros and Registers}, for more info. -@item @@! -In Vi state, -yank anonymous macro to register -@item * -In Vi state, -execute anonymous macro (defined by C-x( and C-x )). -@item C-x e -Like @kbd{*}, but works in all Viper states. -@item #g -Execute the last keyboard macro for each line in the region. -@xref{Macros and Registers}, for more info. -@item [ -Show contents of textmarker. -@item ] -Show contents of register. -@end table -@kindex @kbd{]} -@kindex @kbd{[} -@kindex @kbd{#g} -@kindex @kbd{*} -@kindex @kbd{@@!} -@kindex @kbd{@@#} -@kindex @kbd{@@@@} -@kindex @kbd{@@} -@findex @kbd{:unmap } -@findex @kbd{:map } -@findex @kbd{:unmap!@: } -@findex @kbd{:map!@: } - -@node Shell Commands, Options, Mapping, Commands -@section Shell Commands - -@cindex % (Current file) - -The symbol @samp{%} is used in Ex shell commands to mean current file. If -you want a @samp{%} in your command, it must be escaped as @samp{\%}. -@cindex @samp{%} (Ex address) -However if @samp{%} is the first character, it stands as the address for -the whole file. -@cindex @samp{#} (Previous file) -Similarly, @samp{#} expands to the previous file. The previous file is the -first file in @kbd{:args} listing. This defaults to the previous file in -the VI sense if you have one window.@refill - -Symbols @samp{%} and @samp{#} are also used in the Ex commands @kbd{:e} and -@kbd{:r }. The commands @kbd{:w} and the regular @kbd{:r -} command don't support these meta symbols, because file history is a -better mechanism. - -@cindex shell commands - -@table @kbd -@item :sh -Execute a subshell in another window -@item :[x,y]! -Execute a shell [on lines x through y; -% is replace by current file, \% is changed to % -@item :[x,y]!!@: [] -Repeat last shell command [and append ]. -@item :! -Just execute command and display result in a buffer. -@item :!!@: -Repeat last shell command and append -@item ! -The shell executes , with standard -input the lines described by , -next the standard output replaces those lines -(think of @samp{cb}, @samp{sort}, @samp{nroff}, etc.). -@item !! -Give lines as standard input to the -shell , next let the standard output -replace those lines. -@item :[x,y] w ! -Let lines x to y be standard input for -(notice the between @kbd{w} and @kbd{!}). -@item :
r ! -Put the output of after the line
(default current). -@item :
r -Read the file into the buffer after the line
(default -current). -@item :make -Run the make command in the current directory. -@end table -@findex @kbd{:
r } -@findex @kbd{:
r !} -@findex @kbd{!} -@findex @kbd{!!} -@findex @kbd{!} -@findex @kbd{:w !} -@findex @kbd{:x,y w !} -@findex @kbd{:!!@: } -@findex @kbd{:!} -@findex @kbd{:sh} -@findex @kbd{:make} - -@node Options,Emacs Related Commands,Shell Commands,Commands -@section Options - -@cindex Vi options - -@table @kbd -@item autoindent -@itemx ai -@cindex autoindent -autoindent -- In append mode after a the -cursor will move directly below the first -character on the previous line. -This setting affects the current buffer only. -@item autoindent-global -@itemx ai-global -Same as `autoindent', but affects all buffers. -@item noautoindent -@itemx noai -Cancel autoindent. -@item noautoindent-global -@itemx noai-g -Cancel autoindent-global. -@item ignorecase -@itemx ic -@cindex case and searching -ignorecase -- No distinction between upper and lower cases when searching. -@item noignorecase -@itemx noic -Cancel ignorecase. -@item magic -@itemx ma -@cindex literal searching -Regular expressions used in searches; nomagic means no regexps. -@item nomagic -@item noma -Cancel magic. -@item readonly -@itemx ro -@cindex readonly files -readonly -- The file is not to be changed. -If the user attempts to write to this file, confirmation will be requested. -@item noreadonly -@itemx noro -Cancel readonly. -@item shell= -@itemx sh= -@cindex shell -shell -- The program to be used for shell escapes -(default @samp{$SHELL} (default @file{/bin/sh})). -@item shiftwidth= -@itemx sw= -@cindex layout -@cindex shifting text -shiftwidth -- Gives the shiftwidth (default 8 positions). -@item showmatch -@itemx sm -@cindex paren matching -@cindex matching parens -showmatch -- Whenever you append a @kbd{)}, Vi shows -its match if it's on the same page; also with -@kbd{@{} and @kbd{@}}. If there's no match, Vi will beep. -@item noshowmatch -@itemx nosm -Cancel showmatch. -@item tabstop= -@itemx ts= -@cindex changing tab width -@cindex tabbing -tabstop -- The length of a ; warning: this is -only IN the editor, outside of it s have -their normal length (default 8 positions). -This setting affects the current buffer only. -@item tabstop-global -@itemx ts-g -Same as `tabstop', but affects all buffers. -@item wrapmargin= -@itemx wm= -@cindex auto fill -@cindex word wrap -wrapmargin -- In append mode Vi automatically -puts a whenever there is a or -within columns from the right margin. -@item wrapscan -@itemx ws -@cindex searching -wrapscan -- When searching, the end is -considered @samp{stuck} to the begin of the file. -@item nowrapscan -@itemx nows -Cancel wrapscan. -@item :set